[Optimus] [Feature Request] First-class Agent Runtime abstraction above delegate_task / ACP for application-side integrations

[cloga]

Problem

Optimus Code already has strong orchestration and transport primitives:

• delegate_task / delegate_task_async
• engine / model resolution
• CLI adapters
• ACP support (see [Optimus] [Epic] Universal ACP (Agent Client Protocol) Engine & Domestic Agent Support #319)

However, for application projects that want to use agents as a domain service, there is still a missing layer:

a first-class Agent Runtime abstraction between business code and raw delegation / transport.

In my project (Trinity-Alpha), we are refactoring script generation into:

• skill
• agent runtime layer
• script_agent_service

After working through the design, the boundary became very clear:

• Skill should contain prompt / playbook / instructions only
• Runtime should own execution semantics
• Service should remain application / business code

Right now, every project has to invent its own runtime wrapper.

Why this matters

Without a built-in runtime layer, application projects end up re-implementing the same concerns over and over:

• choosing backend engine / model
• mapping a business request into agent input
• structured-output capture
• timeout / retry / fallback policy
• session pinning / resume behavior
• error taxonomy
• manual-intervention signaling
• sync vs async execution policy
• telemetry / trace metadata
• normalized result envelopes for service-layer consumption

This is especially painful when the business feature is not “delegate a coding task”, but something like:

• script generation
• classification
• extraction
• review / scoring
• structured content generation

In those cases, delegate_task_async is too low-level and orchestration-oriented, while ACP / CLI adapters are transport-oriented.

What is missing is an application-facing runtime contract.

Concrete example

We do not want to put these things into a Skill:

• data loading
• JSON validation
• persistence
• DB writes
• app-specific orchestration

Those should stay in Python service code.

But we also do not want app code to know about:

• Copilot CLI vs Claude Code vs ACP
• prompt execution plumbing
• runtime retries / fallback
• structured result extraction policy
• session lifecycle details

That belongs in a reusable runtime layer.

Proposed abstraction

Introduce a first-class Agent Runtime in Optimus Code, conceptually above transport / adapters and below app services.

Responsibility split

1. Skill

Owns:

• prompt / playbook
• output expectations at the instruction level
• domain procedure

Does not own:

• app data access
• schema validation implementation
• persistence
• transport / runtime state

2. Agent Runtime

Owns:

• backend selection (github-copilot, claude-code, ACP, etc.)
• sync / async execution
• timeout / retry / fallback
• structured response capture
• session reuse / pinned continuation
• manual-intervention signaling
• normalized error / result envelope
• execution metadata / trace IDs

3. Service Layer (application code)

Owns:

• loading business data
• preparing runtime inputs
• validating returned JSON / schema
• persistence / DB writes
• downstream workflow integration

What would help

A reusable runtime API with semantics like:

runAgent({
  role: "script-generator",
  skill: "script-generation",
  input: {...},
  output_schema: {...},
  runtime_policy: {
    mode: "sync",
    timeout_ms: 120000,
    retries: 1,
    fallback_engines: ["github-copilot", "claude-code"]
  }
})

or an async form:

startAgentRun({...})
getAgentRunStatus(runId)
resumeAgentRun(runId, ...)
cancelAgentRun(runId)

Expected output contract

{
  status: "completed" | "failed" | "blocked_manual_intervention",
  result: {...},
  error_code: "...",
  error_message: "...",
  requires_manual_intervention: boolean,
  action_required: "...",
  runtime_metadata: {
    engine: "...",
    model: "...",
    session_id: "...",
    duration_ms: 1234
  }
}

Why this should live in Optimus Code

This feels like a platform concern, not a project-local workaround.

If every downstream project builds its own runtime wrapper, we will get:

• duplicated logic
• inconsistent failure semantics
• repeated transport leakage into app code
• inconsistent skill / service boundaries

Optimus Code is already the right place for:

• engines
• adapters
• delegation
• async task management

So it is also the natural place to provide a business-facing runtime abstraction on top of those primitives.

Non-goals

This request is not asking Optimus Skills to absorb business logic.

Specifically, this is not asking for Skills to handle:

• data loading
• schema validation implementation
• DB persistence
• application integration logic

Those should remain in the host application / service layer.

Relation to existing work

This seems complementary to #319 (ACP transport work), not a duplicate.

• [Optimus] [Epic] Universal ACP (Agent Client Protocol) Engine & Domestic Agent Support #319 solves transport / protocol standardization
• this request asks for a higher-level runtime abstraction that application code can depend on

Success criteria

• A first-class runtime abstraction exists above raw delegation / transport
• Application code can call it without being coupled to Copilot CLI / Claude / ACP details
• Skills remain prompt / playbook-focused
• Service layers remain responsible for app-specific validation / persistence
• Runtime returns normalized status / error / manual-intervention envelopes
• Session reuse / retry / fallback are handled centrally rather than per-project

---

🤖 Created by master-orchestrator via Optimus Spartan Swarm

[cloga]

[patrol-manager] Triaged as P2 (Enhancement). This feature request proposes a first-class Agent Runtime abstraction layer above delegate_task/ACP for application-side integrations. Assessed as medium priority: meaningful capability improvement but non-blocking and no active implementation in progress. Labeled system-maintained for tracking.