@cuylabs/agent-runtime-dapr 0.9.0 → 0.11.0

package/dist/index-BY0FipV1.d.ts

@@ -0,0 +1,770 @@
+import { AgentTaskPayload, SteeringResponse, FollowUpResponse, Tool, AgentTaskResult, AgentTaskRunner, Agent, AgentTaskRunnerOptions, AgentTaskObserver, FollowUpPolicy, AgentEvent, ApprovalRememberScope, HumanInputResponse, FollowUpStatus, QueuedFollowUpRecord, FollowUpDecisionAction } from '@cuylabs/agent-core';
+import { h as DaprExecutionStore } from './store-BXBIDz40.js';
+import { q as DaprPubSubEventBridge, v as DaprWorkflowApprovalRuntime, C as DaprWorkflowHumanInputRuntime, y as DaprWorkflowFollowUpRuntime, F as DaprWorkflowStarterLike, d as DaprAgentWorkflowRunRequest, e as DaprAgentWorkflowRunResult, x as DaprWorkflowEventRaiserLike, f as DaprAgentWorkflowSteerRequest, b as DaprAgentWorkflowFollowUpRequest, a as DaprAgentWorkflowHost, c as DaprAgentWorkflowHostOptions } from './workflow-host-D6W6fXoL.js';
+import { EventBus } from '@cuylabs/agent-core/events';
+import { b as DaprServiceInvoker, c as DaprServiceInvokerOptions } from './invoker-B6ikdYaz.js';
+import { D as DaprWorkflowWorker, d as DaprWorkflowWorkerRuntime } from './worker-CXq0IFGX.js';
+import { RuntimeDriver, RuntimeDriverContext, RuntimeJobRecord, WorkloadRuntime, RuntimeWorkloadRunner, WorkloadRuntimeOptions, RuntimeWorkloadContext } from '@cuylabs/agent-runtime';
+import { c as DaprRuntimeDriverOptions, D as DaprExecutionStoreOptions } from './workflow-bridge-BcicHH1Y.js';
+import { D as DaprWorkflowClient } from './client-UsEIzDF6.js';
+import { Server } from 'node:http';
+
+interface DaprJobTriggerHandler {
+    handleJobTriggerByName(jobName: string): Promise<boolean>;
+}
+interface DaprHttpJobHandlerOptions {
+    driver: DaprJobTriggerHandler;
+    handledStatus?: number;
+    unhandledStatus?: number;
+    errorStatus?: number;
+    onError?: (error: unknown, jobName: string) => void | Promise<void>;
+}
+interface DaprHttpJobHandlerResult {
+    status: number;
+    handled: boolean;
+    error?: unknown;
+}
+declare function createDaprHttpJobHandler(options: DaprHttpJobHandlerOptions): (jobName: string) => Promise<DaprHttpJobHandlerResult>;
+
+declare class DaprRuntimeDriver<TPayload = unknown> implements RuntimeDriver<TPayload> {
+    readonly name = "dapr";
+    private readonly client;
+    private readonly jobsApi;
+    private readonly keyPrefix;
+    private context;
+    private started;
+    constructor(options: DaprRuntimeDriverOptions);
+    start(context: RuntimeDriverContext): Promise<void>;
+    stop(): Promise<void>;
+    private ensureStarted;
+    listJobs(): Promise<RuntimeJobRecord<TPayload>[]>;
+    getJob(jobId: string): Promise<RuntimeJobRecord<TPayload> | undefined>;
+    upsertJob(job: RuntimeJobRecord<TPayload>): Promise<RuntimeJobRecord<TPayload>>;
+    removeJob(jobId: string): Promise<boolean>;
+    /**
+     * Handle a Dapr scheduler callback routed to `/job/:name`.
+     * Returns false when the job name is not managed by this driver.
+     */
+    handleJobTriggerByName(jobName: string): Promise<boolean>;
+    private syncScheduledJob;
+    private fromDaprJobName;
+    private stateKeyForJob;
+    private readJob;
+    private writeJob;
+    private listJobsViaStateQuery;
+    private decodeStoredJob;
+    private deleteScheduledJob;
+}
+
+interface DaprHostedAgentInfo<TPayload extends AgentTaskPayload = AgentTaskPayload> {
+    readonly id: string;
+    readonly aliases: string[];
+    readonly description?: string;
+    readonly workflowHost: {
+        readonly workflowName: string;
+        /** Event bus for real-time streaming. `undefined` if not configured. */
+        readonly eventBus?: EventBus;
+        /** Dapr pub/sub bridge for multi-instance fan-out. `undefined` if not configured. */
+        readonly pubsubBridge?: DaprPubSubEventBridge;
+        /** Durable approval runtime for workflow-backed approvals, when configured. */
+        readonly approvalRuntime?: DaprWorkflowApprovalRuntime;
+        /** Durable human-input runtime for workflow-backed question tools, when configured. */
+        readonly humanInputRuntime?: DaprWorkflowHumanInputRuntime;
+        /** Durable follow-up runtime for workflow-backed next-turn control, when configured. */
+        readonly followUpRuntime?: DaprWorkflowFollowUpRuntime;
+        startTurn(client: DaprWorkflowStarterLike, request: DaprAgentWorkflowRunRequest): Promise<DaprAgentWorkflowRunResult>;
+        steerTurn?(client: DaprWorkflowEventRaiserLike, request: DaprAgentWorkflowSteerRequest): Promise<SteeringResponse>;
+        followUpTurn?(client: DaprWorkflowEventRaiserLike, request: DaprAgentWorkflowFollowUpRequest): Promise<FollowUpResponse>;
+    };
+    readonly runtimeBundle: {
+        readonly executionStore?: DaprExecutionStore<TPayload>;
+    };
+}
+interface DaprHostReadinessCheck {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly detail?: string;
+}
+interface DaprHostReadinessStatus {
+    readonly ok: boolean;
+    readonly checks: readonly DaprHostReadinessCheck[];
+}
+interface DaprHostApp<TPayload extends AgentTaskPayload = AgentTaskPayload> {
+    isRunning(): boolean;
+    checkReadiness?(): DaprHostReadinessStatus | Promise<DaprHostReadinessStatus>;
+    listAgents(): readonly DaprHostedAgentInfo<TPayload>[];
+    getAgent(idOrAlias: string): DaprHostedAgentInfo<TPayload> | undefined;
+    runAgent(idOrAlias: string, payload: TPayload): Promise<unknown>;
+    handleScheduledJob(jobName: string): Promise<DaprHttpJobHandlerResult>;
+}
+
+/**
+ * Remote agent tool — wraps Dapr service invocation into an agent Tool.
+ *
+ * Creates a tool that a coordinator agent can use to invoke a remote
+ * agent running as its own Dapr app. Each remote agent has its own
+ * sidecar, workflow runtime, and state — making them independently
+ * durable and scalable.
+ *
+ * ## Modes
+ *
+ * ### Durable (default, `mode: "durable"`)
+ *
+ * 1. `POST /agents/run-durable` on the remote app → 202 `{ instanceId, sessionId }`
+ * 2. Poll `GET /agents/{id}/workflows/{instanceId}` until terminal status
+ * 3. Fetch result from `GET /agents/{id}/executions/{sessionId}`
+ *
+ * Both sides are fully durable workflows. If the remote agent crashes
+ * mid-turn, its Dapr workflow resumes from the last checkpoint — the
+ * coordinator just keeps polling.
+ *
+ * ### Direct (`mode: "direct"`)
+ *
+ * `POST /agents/run` — synchronous. Simple but not durable on the
+ * remote side. If the remote crashes, the call fails and the
+ * coordinator's workflow retries the whole tool call.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * const researcherTool = createRemoteAgentTool({
+ *   appId: "researcher",
+ *   name: "researcher",
+ *   description: "Research topics and gather information.",
+ *   // mode: "durable" is the default — fully durable
+ * });
+ * ```
+ */
+
+interface CreateRemoteAgentToolOptions {
+    /**
+     * The Dapr service invoker to use for HTTP requests.
+     * If omitted, a new invoker is created with default settings
+     * (or you can pass `invokerOptions` instead).
+     */
+    invoker?: DaprServiceInvoker;
+    /**
+     * Options for creating a `DaprServiceInvoker` when `invoker` is not
+     * provided. Ignored if `invoker` is set.
+     */
+    invokerOptions?: DaprServiceInvokerOptions;
+    /**
+     * The Dapr app ID of the remote agent.
+     * This must match the `--app-id` used when launching the remote agent
+     * with `dapr run`.
+     */
+    appId: string;
+    /**
+     * Tool name exposed to the LLM. The tool will be registered as
+     * `ask_{name}` (e.g., `ask_researcher`).
+     */
+    name: string;
+    /**
+     * Tool description exposed to the LLM. Explain what the remote agent
+     * is good at so the coordinator knows when to delegate.
+     */
+    description: string;
+    /**
+     * Execution mode for the remote agent.
+     *
+     * - `"durable"` (default) — Starts a durable workflow on the remote
+     *   agent and polls for completion. Both coordinator and remote agent
+     *   are independently durable. If the remote crashes, its workflow
+     *   resumes from the last activity checkpoint.
+     *
+     * - `"direct"` — Synchronous `POST /agents/run`. Simpler but if the
+     *   remote crashes, the whole call fails and the coordinator retries
+     *   from scratch.
+     */
+    mode?: "durable" | "direct";
+    /**
+     * Polling interval for checking workflow completion (workflow mode only).
+     * Defaults to 2000ms.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Maximum time to wait for the remote workflow to complete.
+     * Defaults to 5 minutes (300_000ms).
+     */
+    timeoutMs?: number;
+}
+/**
+ * Create a tool that invokes a remote Dapr agent via service invocation.
+ *
+ * In the default `"durable"` mode, both the coordinator and the remote
+ * agent run as independent durable workflows:
+ *
+ * ```
+ * Coordinator Workflow
+ *   │
+ *   ├─ activity: start remote workflow
+ *   │    POST /agents/run-durable → 202 { instanceId, sessionId }
+ *   │    checkpoint instanceId ✓
+ *   │
+ *   ├─ activity: poll remote workflow
+ *   │    GET /agents/{id}/workflows/{instanceId}
+ *   │    ...RUNNING → RUNNING → COMPLETED
+ *   │    checkpoint completion ✓
+ *   │
+ *   ├─ activity: fetch remote result
+ *   │    GET /agents/{id}/executions/{sessionId}
+ *   │    checkpoint result ✓
+ * ```
+ *
+ * If the coordinator crashes after starting the remote workflow, it
+ * resumes polling (doesn't re-start the remote). If the remote crashes
+ * mid-turn, its own Dapr workflow resumes from the last activity
+ * checkpoint.
+ *
+ * @returns A `Tool.AnyInfo` that can be passed to `createAgent({ tools: [...] })`.
+ */
+declare function createRemoteAgentTool(options: CreateRemoteAgentToolOptions): Tool.AnyInfo;
+
+interface DaprWorkloadResultContext<TPayload = unknown, TResult = unknown> {
+    jobId: string;
+    payload: TPayload;
+    runtimeContext: RuntimeWorkloadContext;
+    result: TResult;
+}
+interface DaprWorkloadErrorContext<TPayload = unknown> {
+    jobId: string;
+    payload: TPayload;
+    runtimeContext: RuntimeWorkloadContext;
+    error: unknown;
+    message: string;
+}
+interface DaprWorkloadRuntimeOptions<TPayload = unknown, TResult = unknown> {
+    /** Dapr driver configuration (sidecar + state store + retries). */
+    driver: DaprRuntimeDriverOptions;
+    /**
+     * Optional runtime options excluding driver and execute.
+     * Use this to set concurrency/timeouts/logging behavior.
+     */
+    runtime?: Omit<WorkloadRuntimeOptions<TPayload>, "driver" | "execute">;
+    /**
+     * Domain workload executed for each scheduled or manually triggered job.
+     *
+     * This is the neutral seam between `agent-runtime` orchestration and
+     * application-specific work. `agent-core` task runners can plug in here,
+     * but so can any other job/workload adapter.
+     */
+    runWorkload: RuntimeWorkloadRunner<TPayload, TResult>;
+    /** Optional hook invoked after successful workload execution. */
+    onWorkloadResult?: (context: DaprWorkloadResultContext<TPayload, TResult>) => void | Promise<void>;
+    /** Optional hook invoked when workload execution fails. */
+    onWorkloadError?: (context: DaprWorkloadErrorContext<TPayload>) => void | Promise<void>;
+}
+interface DaprWorkloadRuntimeBundle<TPayload = unknown, TResult = unknown> {
+    runtime: WorkloadRuntime<TPayload>;
+    driver: DaprRuntimeDriver<TPayload>;
+    runWorkload: RuntimeWorkloadRunner<TPayload, TResult>;
+    handleDaprJob: (jobName: string) => Promise<DaprHttpJobHandlerResult>;
+}
+type DaprAgentTaskResultContext<TPayload extends AgentTaskPayload = AgentTaskPayload> = DaprWorkloadResultContext<TPayload, AgentTaskResult>;
+type DaprAgentTaskErrorContext<TPayload extends AgentTaskPayload = AgentTaskPayload> = DaprWorkloadErrorContext<TPayload>;
+interface DaprAgentRuntimeOptions<TPayload extends AgentTaskPayload = AgentTaskPayload> extends Omit<DaprWorkloadRuntimeOptions<TPayload, AgentTaskResult>, "runWorkload" | "onWorkloadResult" | "onWorkloadError"> {
+    /** Agent instance used for job execution. */
+    agent: Agent;
+    /**
+     * Optional explicit task runner. If omitted, one is created with
+     * createAgentTaskRunner(agent, taskRunnerOptions).
+     */
+    taskRunner?: AgentTaskRunner<TPayload>;
+    /** Options used when creating the default task runner. */
+    taskRunnerOptions?: AgentTaskRunnerOptions<TPayload>;
+    /**
+     * Persist neutral execution snapshots/checkpoints into Dapr state.
+     *
+     * Enabled by default when this helper creates the task runner. Disable it if
+     * you only want outer scheduling/orchestration durability.
+     */
+    persistExecutionState?: boolean;
+    /**
+     * Optional pre-created execution store. When omitted and
+     * `persistExecutionState !== false`, a store is created from the driver
+     * configuration.
+     */
+    executionStore?: DaprExecutionStore<TPayload>;
+    /**
+     * Optional execution store configuration override. This is only used when
+     * `executionStore` is not provided.
+     */
+    executionStoreOptions?: DaprExecutionStoreOptions;
+    /** Optional hook invoked after successful task execution. */
+    onTaskResult?: (context: DaprAgentTaskResultContext<TPayload>) => void | Promise<void>;
+    /** Optional hook invoked when task execution fails. */
+    onTaskError?: (context: DaprAgentTaskErrorContext<TPayload>) => void | Promise<void>;
+}
+interface DaprAgentRuntimeBundle<TPayload extends AgentTaskPayload = AgentTaskPayload> extends DaprWorkloadRuntimeBundle<TPayload, AgentTaskResult> {
+    runTask: AgentTaskRunner<TPayload>;
+    executionStore?: DaprExecutionStore<TPayload>;
+}
+/**
+ * Create a Dapr-backed runtime bundle for generic application workloads.
+ *
+ * This is the neutral Dapr implementation of the `agent-runtime` workload
+ * contract. Agent-specific helpers in this package are built on top of this.
+ */
+declare function createDaprWorkloadRuntime<TPayload = unknown, TResult = unknown>(options: DaprWorkloadRuntimeOptions<TPayload, TResult>): DaprWorkloadRuntimeBundle<TPayload, TResult>;
+/**
+ * Create a Dapr-backed runtime bundle for executing `agent-core` task
+ * workloads. This is a thin agent-specific wrapper over
+ * `createDaprWorkloadRuntime(...)`.
+ *
+ * This is the outer integration seam:
+ * - `createAgentTaskRunner(...)` adapts an `Agent` into a workload-shaped task
+ * - `createDaprWorkloadRuntime(...)` lets `agent-runtime` schedule and dispatch it
+ *
+ * Durable workflow decomposition is handled separately by the workflow host
+ * and `workflow/runtime.ts`.
+ */
+declare function createDaprAgentRuntime<TPayload extends AgentTaskPayload = AgentTaskPayload>(options: DaprAgentRuntimeOptions<TPayload>): DaprAgentRuntimeBundle<TPayload>;
+
+interface DaprHostRemoteRunRequest extends AgentTaskPayload {
+    agentId?: string;
+}
+
+/**
+ * Main HTTP router for a Dapr host app.
+ *
+ * This is a thin dispatcher that delegates to domain-specific routers
+ * under `routers/`. Each router returns `Response | undefined` — `undefined`
+ * means "not my route", so the chain continues.
+ */
+
+type DaprHostHttpHandler = (request: Request) => Promise<Response>;
+interface DaprHostHttpHandlerOptions<TPayload extends AgentTaskPayload = DaprHostRemoteRunRequest> {
+    app: DaprHostApp<TPayload>;
+    workflowClient?: DaprWorkflowClient;
+}
+/**
+ * Create a lightweight HTTP handler for a Dapr host app.
+ *
+ * Routes:
+ * - `GET /health` / `GET /healthz`
+ * - `GET /ready` / `GET /readyz`
+ * - `GET /agents`
+ * - `POST /job/:name`
+ * - `GET /dapr/subscribe`
+ * - `POST /dapr/:topic`
+ * - `POST /agents/run`
+ * - `POST /agents/run-durable`
+ * - `POST /agents/:id/run`
+ * - `POST /agents/:id/run-durable`
+ * - `GET /agents/:id/events/:sessionId` — SSE stream
+ * - `GET /agents/:id/executions/:sessionId`
+ * - `GET /agents/:id/executions/:sessionId/checkpoints`
+ * - `GET /agents/:id/workflows/:instanceId`
+ * - `POST /agents/:id/workflows/:instanceId/terminate`
+ * - `POST /agents/:id/workflows/:instanceId/pause`
+ * - `POST /agents/:id/workflows/:instanceId/resume`
+ * - `POST /agents/:id/workflows/:instanceId/purge`
+ * - `GET /agents/:id/inputs` / `:requestId` / `:requestId/respond`
+ * - `GET /agents/:id/approvals` / `:requestId` / `:requestId/respond`
+ * - `GET /agents/:id/follow-ups` / `:requestId` / `:requestId/respond`
+ * - `POST /agents/:id/steer`
+ * - `POST /agents/:id/follow-up`
+ * - Shorthand variants (`/agents/inputs`, `/agents/approvals`, etc.) for single-agent hosts
+ */
+declare function createDaprHostHttpHandler<TPayload extends AgentTaskPayload = DaprHostRemoteRunRequest>(options: DaprHostHttpHandlerOptions<TPayload>): DaprHostHttpHandler;
+
+interface DaprHttpServerOptions {
+    handler: DaprHostHttpHandler;
+    port: number;
+    host?: string;
+}
+interface DaprHostHttpServerOptions<TPayload extends AgentTaskPayload = DaprHostRemoteRunRequest> extends DaprHostHttpHandlerOptions<TPayload> {
+    port: number;
+    host?: string;
+}
+interface DaprHostHttpServer {
+    server: Server;
+    origin: string;
+    close(): Promise<void>;
+}
+declare function startDaprHttpServer(options: DaprHttpServerOptions): Promise<DaprHostHttpServer>;
+declare function startDaprHostHttpServer<TPayload extends AgentTaskPayload = DaprHostRemoteRunRequest>(options: DaprHostHttpServerOptions<TPayload>): Promise<DaprHostHttpServer>;
+
+interface DaprAgentRunnerOptions {
+    /** The agent to run. */
+    agent: Agent;
+    /**
+     * Unique identifier for this agent in the Dapr ecosystem.
+     * Defaults to `agent.name` if omitted.
+     */
+    name?: string;
+    /**
+     * Dapr sidecar HTTP endpoint.
+     * Defaults to `http://${DAPR_HOST ?? "127.0.0.1"}:${DAPR_HTTP_PORT ?? "3500"}`.
+     */
+    daprHttpEndpoint?: string;
+    /**
+     * Dapr gRPC host for the workflow runtime.
+     * Configure this directly on the provided `workflowRuntime`.
+     */
+    /**
+     * Dapr state store component name.
+     * Defaults to `"statestore"`.
+     */
+    stateStoreName?: string;
+    /**
+     * Dapr workflow component name.
+     * Defaults to `"dapr"`.
+     */
+    workflowComponent?: string;
+    /**
+     * Advanced Dapr driver options shared by the runtime bundle and readiness
+     * checks. Use this for API tokens, retry/timeouts, or custom fetch impls.
+     */
+    driverOptions?: Omit<DaprRuntimeDriverOptions, "stateStoreName" | "daprHttpEndpoint">;
+    /**
+     * The Dapr workflow runtime for registering workflows and activities.
+     * Must implement `start()`, `stop()`, `registerWorkflowWithName()`,
+     * and `registerActivityWithName()`.
+     *
+     * Pass `new WorkflowRuntime(...)` from `@dapr/dapr`.
+     */
+    workflowRuntime: DaprWorkflowWorkerRuntime;
+    /**
+     * Optional aliases for multi-agent lookups.
+     */
+    aliases?: string[];
+    /**
+     * Optional description for this agent.
+     */
+    description?: string;
+    /**
+     * Additional observers for execution lifecycle events.
+     * A logging observer is always included by default — pass extras here
+     * for persistence (e.g. `createDaprExecutionObserver()`), telemetry, etc.
+     */
+    observers?: AgentTaskObserver[];
+    /**
+     * Enable/disable the built-in console logging observer.
+     * Defaults to `true`.
+     */
+    logging?: boolean;
+    /**
+     * Prefix for log lines from the built-in logging observer.
+     * Defaults to `[${name}]`.
+     */
+    logPrefix?: string;
+    /**
+     * Override for workflow host options (advanced).
+     * Properties set here override the defaults derived from the runner config.
+     */
+    workflowHost?: Omit<DaprAgentWorkflowHostOptions, "agent" | "observers">;
+    /**
+     * Policy for deferred follow-up requests in durable mode.
+     */
+    followUpPolicy?: FollowUpPolicy;
+    /**
+     * Override for runtime bundle options (advanced).
+     * The `agent` and `driver` fields are always derived from the runner config.
+     */
+    runtimeOptions?: Omit<DaprAgentRuntimeOptions, "agent" | "driver" | "taskRunnerOptions"> & {
+        taskRunnerOptions?: Omit<NonNullable<DaprAgentRuntimeOptions["taskRunnerOptions"]>, "observers">;
+    };
+}
+interface DaprAgentServeOptions {
+    /** HTTP port. Defaults to `3000`. */
+    port?: number;
+    /** HTTP host. Defaults to all interfaces. */
+    host?: string;
+    /** Serve static assets from this directory before the built-in agent routes. */
+    staticDir?: string;
+    /** File served for `/` when `staticDir` is configured. Defaults to `index.html`. */
+    indexFile?: string;
+    /** Additional exact-match routes evaluated before static assets and built-in routes. */
+    extraRoutes?: readonly DaprAgentHttpRoute[];
+}
+interface DaprAgentHttpRoute {
+    /** Exact URL pathname match, e.g. `/` or `/ui/config.json`. */
+    path: string;
+    /** Allowed HTTP methods. Defaults to all methods. */
+    method?: string | readonly string[];
+    handler(request: Request): Response | Promise<Response>;
+}
+interface DaprAgentHttpHandlerOptions {
+    staticDir?: string;
+    indexFile?: string;
+    extraRoutes?: readonly DaprAgentHttpRoute[];
+}
+interface DaprAgentDurableRunOptions {
+    sessionId?: string;
+    system?: string;
+    workflowInstanceId?: string;
+    maxSteps?: number;
+}
+interface DaprAgentDurableRunResult {
+    agentId: string;
+    workflowName: string;
+    sessionId: string;
+    instanceId: string;
+}
+interface DaprAgentRunner {
+    /** Agent name / ID. */
+    readonly name: string;
+    /** The underlying agent instance. */
+    readonly agent: Agent;
+    /** The underlying workflow host. */
+    readonly workflowHost: DaprAgentWorkflowHost;
+    /** The underlying runtime bundle (scheduling, workload adapter, execution store). */
+    readonly runtimeBundle: DaprAgentRuntimeBundle;
+    /** The underlying workflow worker. */
+    readonly worker: DaprWorkflowWorker;
+    /** The workflow client for managing workflow instances. */
+    readonly workflowClient: DaprWorkflowClient;
+    /**
+     * Return a capabilities patch describing the Dapr runtime backing.
+     *
+     * Structurally compatible with `AgentServerCapabilitiesPatch` from
+     * `@cuylabs/agent-server`. Used internally by
+     * `createDaprAgentServerAdapter(...)` and available for custom
+     * composition if you need to layer additional transport metadata.
+     *
+     * @example
+     * ```ts
+     * import { createDaprAgentServerAdapter } from "@cuylabs/agent-runtime-dapr";
+     * const adapter = createDaprAgentServerAdapter(runner);
+     * ```
+     */
+    agentServerCapabilities(): {
+        runtime: {
+            execution: "local";
+            orchestration: "agent-runtime-dapr";
+            durability: "workflow";
+            dapr: {
+                available: true;
+                delegatedTurns: false;
+                workflowBacked: true;
+            };
+        };
+    };
+    /**
+     * Start the runtime and workflow worker.
+     * Must be called before `serve()` or manual invocation.
+     */
+    start(): Promise<void>;
+    /**
+     * Start the HTTP server and block until SIGINT/SIGTERM.
+     * Calls `start()` internally if not already started.
+     */
+    serve(options?: DaprAgentServeOptions): Promise<void>;
+    /**
+     * Build the HTTP handler for this runner.
+     * Useful when embedding the Dapr host routes inside a custom server.
+     */
+    createHttpHandler(options?: DaprAgentHttpHandlerOptions): DaprHostHttpHandler;
+    /**
+     * Run a task directly (synchronous execution, no workflow).
+     * The agent must be started first.
+     */
+    run(message: string, options?: {
+        sessionId?: string;
+    }): Promise<AgentTaskResult>;
+    /**
+     * Start a durable workflow-backed task and return its identifiers.
+     * The agent must be started first.
+     */
+    runDurable(message: string, options?: DaprAgentDurableRunOptions): Promise<DaprAgentDurableRunResult>;
+    /**
+     * Gracefully shut down the runner.
+     */
+    stop(): Promise<void>;
+}
+interface DaprMultiAgentRunnerAgentConfig {
+    /** The agent instance. */
+    agent: Agent;
+    /** Unique identifier for this agent in the Dapr ecosystem. */
+    name: string;
+    /** Optional aliases for multi-agent lookups. */
+    aliases?: string[];
+    /** Optional description for this agent. */
+    description?: string;
+    /** Policy for deferred follow-up requests for this hosted agent. */
+    followUpPolicy?: FollowUpPolicy;
+}
+interface DaprMultiAgentRunnerOptions {
+    /** Agent configurations. */
+    agents: DaprMultiAgentRunnerAgentConfig[];
+    /** Shared Dapr workflow runtime. */
+    workflowRuntime: DaprWorkflowWorkerRuntime;
+    /** Dapr sidecar HTTP endpoint. */
+    daprHttpEndpoint?: string;
+    /** Dapr state store component name. Defaults to `"statestore"`. */
+    stateStoreName?: string;
+    /** Advanced Dapr driver options shared by all hosted runtimes. */
+    driverOptions?: Omit<DaprRuntimeDriverOptions, "stateStoreName" | "daprHttpEndpoint">;
+    /** Dapr workflow component name. Defaults to `"dapr"`. */
+    workflowComponent?: string;
+    /** Additional observers applied to all agents. */
+    observers?: AgentTaskObserver[];
+    /** Enable/disable built-in console logging. Defaults to `true`. */
+    logging?: boolean;
+}
+interface DaprMultiAgentRunner {
+    /** Start all runtimes and the shared workflow worker. */
+    start(): Promise<void>;
+    /** Start HTTP server and block until SIGINT/SIGTERM. Calls `start()` internally. */
+    serve(options?: DaprAgentServeOptions): Promise<void>;
+    /** Build the HTTP handler for this multi-agent runner. */
+    createHttpHandler(options?: DaprAgentHttpHandlerOptions): DaprHostHttpHandler;
+    /** Gracefully shut down. */
+    stop(): Promise<void>;
+}
+
+type AgentServerCapabilitiesPatch = Record<string, unknown>;
+interface AppToolInfo {
+    id: string;
+}
+interface AppSkillInfo {
+    name: string;
+    description?: string;
+    path?: string;
+}
+interface AppSubAgentProfileInfo {
+    name: string;
+    description?: string;
+}
+interface AppPluginCommandInfo {
+    pluginId?: string;
+    name: string;
+    alias: string[];
+    summary: string;
+    metadata?: unknown;
+}
+interface AppModelState {
+    label: string;
+    switchable: boolean;
+}
+type AppModelSwitchResult = {
+    ok: true;
+    label: string;
+} | {
+    ok: false;
+    error: string;
+};
+type AppRuntimeStatusSnapshot = {
+    session: Record<string, unknown>;
+    model: Record<string, unknown>;
+    context: unknown;
+};
+type AppContextCompactionResult = unknown;
+type AppUndoResult = unknown;
+interface AppFollowUpListOptions {
+    sessionId?: string;
+    sourceTurnId?: string;
+    status?: FollowUpStatus | FollowUpStatus[];
+}
+type ResolveInputRequestPayload = {
+    kind: "approval";
+    action: "allow" | "deny" | "remember";
+    feedback?: string;
+    rememberScope?: ApprovalRememberScope;
+} | {
+    kind: "human";
+    response: HumanInputResponse;
+};
+interface AgentServerPluginCommand {
+    pluginId?: string;
+    name: string;
+    alias: string[];
+    summary: string;
+    metadata?: unknown;
+    execute(args: string): Promise<string | null> | string | null;
+}
+interface AgentServerAdapter {
+    readonly cwd: string;
+    getCapabilities?(): AgentServerCapabilitiesPatch;
+    getModelState?(): Promise<AppModelState> | AppModelState;
+    switchModel?(spec: string): Promise<AppModelSwitchResult> | AppModelSwitchResult;
+    getSessionRuntimeStatus?(sessionId: string): Promise<AppRuntimeStatusSnapshot> | AppRuntimeStatusSnapshot;
+    listTools?(): Promise<AppToolInfo[]> | AppToolInfo[];
+    listSkills?(): Promise<AppSkillInfo[]> | AppSkillInfo[];
+    listSubAgents?(): Promise<AppSubAgentProfileInfo[]> | AppSubAgentProfileInfo[];
+    compactSessionContext?(sessionId: string): Promise<AppContextCompactionResult> | AppContextCompactionResult;
+    undoSessionTurn?(sessionId: string): Promise<AppUndoResult> | AppUndoResult;
+    getSessionTurnDiff?(sessionId: string): Promise<string | null> | string | null;
+    chat(sessionId: string, message: string, options?: {
+        system?: string;
+        abort?: AbortSignal;
+    }): AsyncGenerator<AgentEvent>;
+    steer?(request: {
+        sessionId: string;
+        turnId: string;
+        message: string;
+    }): SteeringResponse;
+    followUp?(request: {
+        sessionId: string;
+        turnId: string;
+        message: string;
+    }): FollowUpResponse;
+    interruptTurn?(request: {
+        sessionId: string;
+        turnId: string;
+    }): void | Promise<void>;
+    respondToInputRequest?(requestId: string, payload: ResolveInputRequestPayload): void | Promise<void>;
+    listFollowUps?(options?: AppFollowUpListOptions): Promise<QueuedFollowUpRecord[]> | QueuedFollowUpRecord[];
+    getFollowUp?(followUpId: string): Promise<QueuedFollowUpRecord | null> | QueuedFollowUpRecord | null;
+    resolveFollowUp?(followUpId: string, action: FollowUpDecisionAction): Promise<QueuedFollowUpRecord | null> | QueuedFollowUpRecord | null;
+    listSessions(): ReturnType<Agent["listSessions"]>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    getSessionStorage(): ReturnType<ReturnType<Agent["getSessionManager"]>["getStorage"]>;
+    listPluginCommands?(): Promise<AppPluginCommandInfo[]> | AppPluginCommandInfo[];
+    executePluginCommand?(name: string, args: string): Promise<string | null> | string | null;
+}
+interface CreateDaprAgentServerAdapterOptions {
+    pluginCommands?: AgentServerPluginCommand[];
+    currentModelLabel?: string;
+    switchModel?: (spec: string) => Promise<AppModelSwitchResult> | AppModelSwitchResult;
+    listSkills?: () => Promise<AppSkillInfo[]> | AppSkillInfo[];
+    listSubAgents?: () => Promise<AppSubAgentProfileInfo[]> | AppSubAgentProfileInfo[];
+    capabilities?: AgentServerCapabilitiesPatch;
+}
+declare function createDaprAgentServerAdapter(runner: DaprAgentRunner, options?: CreateDaprAgentServerAdapterOptions): AgentServerAdapter;
+
+/**
+ * Create a Dapr agent runner — the single-call composition of all pieces
+ * needed to run an agent with Dapr durability.
+ *
+ * Equivalent to Diagrid's `DaprWorkflowAgentRunner`. Internally creates:
+ * - Workflow host (Dapr workflow registration + turn state management)
+ * - Runtime bundle (scheduling + workload adapter + execution store)
+ * - Workflow worker (gRPC worker for Dapr workflow engine)
+ * - Workflow client (HTTP client for managing workflow instances)
+ * - HTTP server (on `serve()`)
+ *
+ * @example
+ * ```ts
+ * const runner = createDaprAgentRunner({
+ *   agent,
+ *   name: "my-agent",
+ *   workflowRuntime: new WorkflowRuntime({ daprHost: "127.0.0.1", daprPort: "50001" }),
+ * });
+ *
+ * await runner.serve({ port: 3000 });
+ * ```
+ */
+declare function createDaprAgentRunner(options: DaprAgentRunnerOptions): DaprAgentRunner;
+
+/**
+ * Create a multi-agent Dapr runner — multiple agents sharing a single
+ * workflow worker, HTTP server, and Dapr sidecar.
+ *
+ * @example
+ * ```ts
+ * const runner = createDaprMultiAgentRunner({
+ *   agents: [
+ *     { agent: greeter, name: "greeter" },
+ *     { agent: calculator, name: "calculator" },
+ *   ],
+ *   workflowRuntime: new WorkflowRuntime(),
+ * });
+ *
+ * await runner.serve({ port: 3000 });
+ * ```
+ */
+declare function createDaprMultiAgentRunner(options: DaprMultiAgentRunnerOptions): DaprMultiAgentRunner;
+
+export { type DaprWorkloadRuntimeBundle as A, type DaprWorkloadRuntimeOptions as B, type CreateDaprAgentServerAdapterOptions as C, type DaprAgentDurableRunOptions as D, createDaprAgentRunner as E, createDaprAgentRuntime as F, createDaprAgentServerAdapter as G, createDaprHostHttpHandler as H, createDaprHttpJobHandler as I, createDaprMultiAgentRunner as J, createDaprWorkloadRuntime as K, createRemoteAgentTool as L, startDaprHostHttpServer as M, type DaprAgentHttpHandlerOptions as N, type DaprAgentHttpRoute as O, type DaprHostHttpHandler as P, type DaprHttpServerOptions as Q, startDaprHttpServer as R, type CreateRemoteAgentToolOptions as a, type DaprAgentDurableRunResult as b, type DaprAgentRunner as c, type DaprAgentRunnerOptions as d, type DaprAgentRuntimeBundle as e, type DaprAgentRuntimeOptions as f, type DaprAgentServeOptions as g, type DaprAgentTaskErrorContext as h, type DaprAgentTaskResultContext as i, type DaprHostApp as j, type DaprHostHttpHandlerOptions as k, type DaprHostHttpServer as l, type DaprHostHttpServerOptions as m, type DaprHostReadinessCheck as n, type DaprHostReadinessStatus as o, type DaprHostRemoteRunRequest as p, type DaprHostedAgentInfo as q, type DaprHttpJobHandlerOptions as r, type DaprHttpJobHandlerResult as s, type DaprJobTriggerHandler as t, type DaprMultiAgentRunner as u, type DaprMultiAgentRunnerAgentConfig as v, type DaprMultiAgentRunnerOptions as w, DaprRuntimeDriver as x, type DaprWorkloadErrorContext as y, type DaprWorkloadResultContext as z };