feat(core): add cloud agent runtime profiles

Introduce runtime profile configuration, protocol-aware adapter matching, and cloudAgent handoff metadata on task records and handles. Add the prepareTask adapter hook so providers can return session details before execution starts, and cover the new routing and validation paths with tests.

Author: vamgan

README.md

@@ -1,18 +1,90 @@
 # @agent-dispatch/core
 
-Provider-neutral runtime contracts and dispatch orchestration for AgentDispatch.
+[![npm](https://img.shields.io/npm/v/@agent-dispatch/core.svg)](https://www.npmjs.com/package/@agent-dispatch/core)
+[![license](https://img.shields.io/npm/l/@agent-dispatch/core.svg)](https://www.npmjs.com/package/@agent-dispatch/core)
 
-This package is the compatibility anchor for all AgentDispatch repositories. Cloud adapters, stores, SDKs, CLIs, and MCP servers depend on these interfaces; `@agent-dispatch/core` does not depend on any adapter package.
+Provider-neutral runtime primitives for AgentDispatch: the MCP control plane that lets a lead agent spawn, monitor, and interact with cloud subagents without binding itself to one cloud API.
 
-## Core concepts
+## Why this package exists
 
-- Providers: `aws`, `gcp`, `azure`, `kubernetes`, `local`, or future provider strings.
-- Capabilities: `agent-runtime` in V1, with reserved support for `service-deploy`, `job-runner`, `container-task`, and `workflow-runner`.
-- Tasks: durable work units with provider-neutral lifecycle state.
-- Adapters: provider-specific implementations behind a stable `BackendAdapter` contract.
-- Policies: provider-neutral authorization rules for account profiles, capabilities, task types, and target modes.
-- Testing: `assertBackendAdapterContract` gives adapter repos a reusable conformance check.
-
-## Publishing
+Agents should not need to know whether a long-running task runs on AWS AgentCore, Cloud Run, Azure Container Apps, Kubernetes, or a local worker. They should ask for a capability, account profile, task type, and target. `@agent-dispatch/core` defines that stable contract and keeps every adapter compatible with the rest of the system.
 
 See the [release workflow](https://github.com/agent-dispatch/core/blob/main/docs/release.md) for the npm publishing workflow and the dependency-order checklist for the separate `agent-dispatch` repositories.
+
+```mermaid
+flowchart LR
+  A["Lead agent\n(OpenClaw, Hermes, Codex, Claude Code)"] --> B["AgentDispatch core"]
+  B --> C["Backend adapter"]
+  C --> D["Cloud runtime"]
+  D --> E["Cloud subagent"]
+```
+
+## What core owns
+
+- Provider-neutral models for `Provider`, `Capability`, `AccountProfile`, `Target`, `Task`, `Runtime`, `Session`, `Event`, and `Artifact`.
+- Adapter registration and routing by `provider + capability + task_type + target.mode`.
+- Durable task lifecycle orchestration with pluggable stores.
+- Runtime protocol metadata for A2A, MCP, AG-UI, and HTTP interaction planes.
+- Clarification-safe request validation so MCP servers can ask for missing runtime inputs before dispatch.
+
+## Adapter contract
+
+Every provider adapter implements the same shape:
+
+```ts
+interface BackendAdapter {
+  provider: string;
+  capabilities(): AdapterCapability[];
+  resolveTarget(request: DispatchRequest): Promise<ResolvedTarget>;
+  provision(request: ProvisionRequest): Promise<ProvisionResult>;
+  prepareTask?(request: PrepareTaskRequest): Promise<PrepareTaskResult>;
+  startTask(request: StartTaskRequest): Promise<StartTaskResult>;
+  streamEvents(taskId: string): AsyncIterable<RuntimeEvent>;
+  cancel(taskId: string): Promise<CancelResult>;
+  cleanup(target: RuntimeTarget): Promise<CleanupResult>;
+}
+```
+
+Adapters translate provider-neutral requests into provider APIs, then return provider-neutral task handles, events, artifacts, and optional `cloudAgent` metadata. Provider-specific values stay in adapter config or `target.details`; the MCP server and SDK do not import provider SDK types.
+
+## Install
+
+```bash
+npm install @agent-dispatch/core
+```
+
+## Example
+
+```ts
+import { RuntimeService } from "@agent-dispatch/core";
+
+const runtime = new RuntimeService({
+  adapters: [awsAgentCoreAdapter],
+  store,
+  config
+});
+
+const task = await runtime.dispatchTask({
+  provider: "aws",
+  accountProfile: "dev-aws",
+  capability: "agent-runtime",
+  taskType: "agent.run",
+  target: { mode: "session", protocol: "a2a" },
+  input: {
+    instruction: "Analyze this repository and produce a migration plan."
+  }
+});
+```
+
+## Package role
+
+`@agent-dispatch/core` is the compatibility anchor. All adapters depend on it. It depends on no adapters. If a future provider needs a new feature, the design goal is to extend core once and keep the agent-facing MCP tools stable.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```

src/adapter.ts

@@ -3,6 +3,8 @@ import type {
   CancelResult,
   CleanupResult,
   DispatchRequest,
+  PrepareTaskRequest,
+  PrepareTaskResult,
   ProvisionRequest,
   ProvisionResult,
   ResolvedTarget,
@@ -17,6 +19,7 @@ export interface BackendAdapter {
   readonly provider: string;
 
   capabilities(): AdapterCapability[];
+  prepareTask?(request: PrepareTaskRequest): Promise<PrepareTaskResult>;
   resolveTarget(request: DispatchRequest): Promise<ResolvedTarget>;
   provision(request: ProvisionRequest): Promise<ProvisionResult>;
   startTask(request: StartTaskRequest): Promise<StartTaskResult>;
@@ -31,7 +34,8 @@ export function adapterSupports(adapter: BackendAdapter, request: DispatchReques
       capability.provider === request.provider &&
       capability.capability === request.capability &&
       capability.taskTypes.includes(request.taskType) &&
-      capability.targetModes.includes(request.target.mode)
+      capability.targetModes.includes(request.target.mode) &&
+      (!request.target.protocol || !capability.protocols || capability.protocols.includes(request.target.protocol))
     );
   });
 }

src/config.ts

@@ -1,4 +1,6 @@
-import type { AccountProfile, Capability, DispatchPolicy, DispatchTarget, Provider, TargetMode } from "./types.js";
+import type { AccountProfile, Capability, DispatchPolicy, DispatchTarget, Provider, RuntimeProtocol, TargetMode } from "./types.js";
+
+export type RuntimeModelConfig = string | Record<string, unknown>;
 
 export interface BackendConfig {
   provider: Provider;
@@ -14,8 +16,11 @@ export interface RuntimeProfileConfig {
   capability: Capability;
   backend: string;
   target?: Partial<DispatchTarget> & { mode: TargetMode };
+  protocol?: RuntimeProtocol;
   framework?: string;
+  model?: RuntimeModelConfig;
   runtimeTools?: Record<string, unknown>;
+  requiredInputs?: string[];
   metadata?: Record<string, unknown>;
 }
 
@@ -33,7 +38,9 @@ export interface AgentDispatchConfig {
     capability?: Capability;
     backend?: string;
     targetMode?: TargetMode;
+    protocol?: RuntimeProtocol;
     framework?: string;
+    model?: RuntimeModelConfig;
     runtimeTools?: Record<string, unknown>;
   };
   policy?: DispatchPolicy;

src/runtime.ts

@@ -56,6 +56,11 @@ export class RuntimeService {
     return getRuntimeProfile(this.config, name);
   }
 
+  getBackend(name: string) {
+    const backend = this.config.backends[name];
+    return backend ? { name, ...backend } : undefined;
+  }
+
   getDefaultRuntimeProfile() {
     return getDefaultRuntimeProfile(this.config);
   }
@@ -90,6 +95,13 @@ export class RuntimeService {
     const adapter = this.selectAdapter(request);
 
     const task = this.createTaskRecord(request, adapter.name);
+    const prepared = adapter.prepareTask ? await adapter.prepareTask({ dispatch: request, task }) : undefined;
+    if (prepared?.providerRefs) {
+      task.providerRefs = { ...task.providerRefs, ...prepared.providerRefs };
+    }
+    if (prepared?.cloudAgent) {
+      task.cloudAgent = prepared.cloudAgent;
+    }
     await this.store.saveTask(task);
     await this.store.appendEvent(this.event(task.id, "task.created", "Task accepted by AgentDispatch."));
 
@@ -102,6 +114,7 @@ export class RuntimeService {
       accountProfile: task.accountProfile,
       capability: task.capability,
       backend: adapter.name,
+      cloudAgent: prepared?.cloudAgent,
       poll: {
         statusTool: "get_task_status",
         logsTool: "get_task_logs",
@@ -180,6 +193,7 @@ export class RuntimeService {
       await this.store.updateTask(task.id, {
         status: "starting",
         providerRefs: { ...task.providerRefs, ...provisioned.providerRefs, ...target.providerRefs },
+        cloudAgent: provisioned.cloudAgent ?? task.cloudAgent,
         updatedAt: nowIso()
       });
       await this.store.appendEvent(this.event(task.id, "task.started", "Starting provider task."));
@@ -200,6 +214,7 @@ export class RuntimeService {
       await this.store.updateTask(task.id, {
         status: "running",
         providerRefs: { ...(await this.latestProviderRefs(task.id)), ...started.providerRefs },
+        cloudAgent: started.cloudAgent ?? provisioned.cloudAgent ?? task.cloudAgent,
         updatedAt: nowIso()
       });
       for (const artifact of started.artifacts ?? []) {

src/types.ts

@@ -20,6 +20,8 @@ export type TaskType = KnownTaskType | (string & {});
 
 export type TargetMode = "session" | "runtime" | "managed-service" | "job" | (string & {});
 
+export type RuntimeProtocol = "http" | "a2a" | "mcp" | "ag-ui" | (string & {});
+
 export type TaskStatus =
   | "queued"
   | "provisioning"
@@ -62,6 +64,7 @@ export interface AccountProfile {
 
 export interface DispatchTarget {
   mode: TargetMode;
+  protocol?: RuntimeProtocol;
   details?: Record<string, unknown>;
 }
 
@@ -111,6 +114,7 @@ export interface AdapterCapability {
   capability: Capability;
   taskTypes: TaskType[];
   targetModes: TargetMode[];
+  protocols?: RuntimeProtocol[];
   configRequirements?: string[];
 }
 
@@ -120,6 +124,7 @@ export interface RuntimeTarget {
   capability: Capability;
   backend: string;
   mode: TargetMode;
+  protocol?: RuntimeProtocol;
   details?: Record<string, unknown>;
   providerRefs?: Record<string, unknown>;
 }
@@ -167,6 +172,7 @@ export interface TaskRecord {
   backend?: string;
   status: TaskStatus;
   providerRefs: Record<string, unknown>;
+  cloudAgent?: CloudAgentInteraction;
   result?: Record<string, unknown>;
   error?: RuntimeErrorShape;
   createdAt: string;
@@ -215,10 +221,52 @@ export interface ProvisionRequest {
   target: RuntimeTarget;
 }
 
+export interface PrepareTaskRequest {
+  dispatch: DispatchRequest;
+  task: TaskRecord;
+}
+
+export interface ProviderInvocationDetails {
+  type: string;
+  provider: Provider;
+  region?: string;
+  accountProfile: string;
+  credentialSource?: string;
+  [key: string]: unknown;
+}
+
+export interface A2AInteractionDetails {
+  transport: "json-rpc-2.0-http" | (string & {});
+  messageMethod: "message/send" | (string & {});
+  agentCardPath?: string;
+  agentCardOperation?: string;
+  payloadFormat?: string;
+  [key: string]: unknown;
+}
+
+export interface CloudAgentInteraction {
+  protocol: RuntimeProtocol;
+  provider: Provider;
+  backend: string;
+  accountProfile: string;
+  sessionId?: string;
+  providerRefs?: Record<string, unknown>;
+  invocation?: ProviderInvocationDetails;
+  a2a?: A2AInteractionDetails;
+  model?: unknown;
+  tools?: Record<string, unknown>;
+}
+
+export interface PrepareTaskResult {
+  providerRefs?: Record<string, unknown>;
+  cloudAgent?: CloudAgentInteraction;
+}
+
 export interface ProvisionResult {
   runtime?: RuntimeRecord;
   session?: SessionRecord;
   providerRefs?: Record<string, unknown>;
+  cloudAgent?: CloudAgentInteraction;
 }
 
 export interface StartTaskRequest {
@@ -231,6 +279,7 @@ export interface StartTaskRequest {
 
 export interface StartTaskResult {
   providerRefs?: Record<string, unknown>;
+  cloudAgent?: CloudAgentInteraction;
   result?: Record<string, unknown>;
   artifacts?: ArtifactRecord[];
 }
@@ -254,6 +303,7 @@ export interface TaskHandle {
   accountProfile: string;
   capability: Capability;
   backend: string;
+  cloudAgent?: CloudAgentInteraction;
   poll: {
     statusTool: "get_task_status";
     logsTool: "get_task_logs";

test/config.test.ts

@@ -19,8 +19,10 @@ const config: AgentDispatchConfig = {
       account: "dev-aws",
       capability: "agent-runtime",
       backend: "aws-agentcore",
+      protocol: "a2a",
       target: { mode: "session", details: { runtimeArn: "arn:aws:bedrock-agentcore:test" } },
       framework: "strands",
+      model: { provider: "bedrock", modelId: "anthropic.claude-3-5-sonnet" },
       runtimeTools: { enabled: ["web-search"] }
     }
   },
@@ -37,7 +39,8 @@ describe("AgentDispatchConfig runtime profiles", () => {
       provider: "aws",
       account: "dev-aws",
       capability: "agent-runtime",
-      backend: "aws-agentcore"
+      backend: "aws-agentcore",
+      protocol: "a2a"
     });
     expect(getDefaultRuntimeProfile(config)).toMatchObject({ name: "research-agent" });
   });

test/runtime.test.ts

@@ -49,6 +49,21 @@ function mockAdapter(events: RuntimeEvent[], cleanup: CleanupResult = { status:
     name: "mock-agent-runtime",
     provider: "aws",
     capabilities: () => [{ provider: "aws", capability: "agent-runtime", taskTypes: ["agent.run"], targetModes: ["session"] }],
+    prepareTask: async ({ dispatch }) => ({
+      providerRefs: { runtimeSessionId: "agentcore_session_mock" },
+      cloudAgent: {
+        protocol: dispatch.target.protocol ?? "a2a",
+        provider: "aws",
+        backend: "mock-agent-runtime",
+        accountProfile: dispatch.accountProfile,
+        sessionId: "agentcore_session_mock",
+        providerRefs: { runtimeSessionId: "agentcore_session_mock" },
+        a2a: {
+          transport: "json-rpc-2.0-http",
+          messageMethod: "message/send"
+        }
+      }
+    }),
     resolveTarget: async (request) => ({
       account: { name: request.accountProfile, provider: "aws", credentialSource: "test" },
       target: { provider: "aws", accountProfile: request.accountProfile, capability: "agent-runtime", backend: "mock-agent-runtime", mode: "session" }
@@ -73,7 +88,7 @@ describe("RuntimeService", () => {
       accountProfile: "dev-aws",
       capability: "agent-runtime",
       taskType: "agent.run",
-      target: { mode: "session" },
+      target: { mode: "session", protocol: "a2a" },
       input: { instruction: "run" }
     };
     const service = new RuntimeService({
@@ -88,10 +103,15 @@ describe("RuntimeService", () => {
     const handle = await service.dispatchTask(request);
     expect(handle.provider).toBe("aws");
     expect(handle.capability).toBe("agent-runtime");
+    expect(handle.cloudAgent).toMatchObject({
+      protocol: "a2a",
+      sessionId: "agentcore_session_mock"
+    });
 
     await new Promise((resolve) => setTimeout(resolve, 10));
     const task = await service.getTaskStatus(handle.taskId);
     expect(["running", "succeeded"]).toContain(task.status);
+    expect(task.cloudAgent).toMatchObject({ protocol: "a2a" });
   });
 
   it("applies configured dispatch policy before adapter selection", async () => {