@agentproto/runtime 2.11.0 → 2.12.0

package/dist/index.d.ts

@@ -13,8 +13,8 @@ export { CostBudget, CostBudgetScope } from '@agentproto/auth';
 import { R as ResolvedContextContinuityPolicy } from './context-continuity-ib9_bVYM.js';
 import { SandboxMode } from '@agentproto/command-sandbox';
 import { AdapterHandle, SetupField, AdapterResolver, AdapterLister, HarnessCapabilities, AdapterEntry } from '@agentproto/provider-kit';
-import { R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-DUnTfwVK.js';
-export { a as AuthEcho, b as AuthResolutionError, C as CLAUDE_CODE_OAUTH_SOURCE, c as CredentialSource, d as DefaultsAdapterAuthConfig, e as DefaultsAdapterConfig, f as ResolveSubscriptionCredentialInput, g as ResolvedSpawnAuthMaterial, h as ResolvedSpawnDefaults, S as SpawnDefaultsConfig, i as SubscriptionCredentialResolution, j as SubscriptionSourceError, k as credentialFingerprint, n as normalizeSkillsOption, r as resolveAuthSpec, l as resolveSpawnDefaults, m as resolveSubscriptionCredential } from './spawn-defaults-DUnTfwVK.js';
+import { R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-D4W661ui.js';
+export { a as AuthEcho, b as AuthResolutionError, C as CLAUDE_CODE_OAUTH_SOURCE, c as CredentialSource, d as DefaultsAdapterAuthConfig, e as DefaultsAdapterConfig, f as ResolveSubscriptionCredentialInput, g as ResolvedSpawnAuthMaterial, h as ResolvedSpawnDefaults, S as SpawnDefaultsConfig, i as SubscriptionCredentialResolution, j as SubscriptionSourceError, k as credentialFingerprint, n as normalizeSkillsOption, r as resolveAuthSpec, l as resolveSpawnDefaults, m as resolveSubscriptionCredential } from './spawn-defaults-D4W661ui.js';
 import { CatalogModelsQuery, CatalogModelsResponse } from './catalog-models.js';
 export { CatalogAdapterInput, CatalogAdapterModelInput, CatalogPricing, CatalogProduct, CatalogRoute, CatalogRouteSummary, CatalogVendor, buildCatalogModels } from './catalog-models.js';
 import { FooterSession } from './pr-provenance.js';
@@ -1684,7 +1684,7 @@ declare function createTaskLedger(opts: {
  * and session_monitor MCP tool (long-poll multiplexed).
  */
 
-type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:awaiting-input-flagged" | "session:permission-request" | "session:permission-resolved" | "session:exited" | "session:reaped" | "session:stalled" | "session:stall-cleared" | "session:watcher-attached" | "session:watcher-detached" | "session:bg-tasks-parked" | "session:bg-tasks-cleared" | "session:resumed" | "session:spawned" | "session:command-done" | "session:model-changed" | "session:config-changed" | "session:renamed" | "session:pinned-changed" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed" | "activity:changed" | "task:changed";
+type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:awaiting-input-flagged" | "session:awaiting-question-answered" | "session:permission-request" | "session:permission-resolved" | "session:exited" | "session:reaped" | "session:stalled" | "session:stall-cleared" | "session:watcher-attached" | "session:watcher-detached" | "session:bg-tasks-parked" | "session:bg-tasks-cleared" | "session:resumed" | "session:spawned" | "session:command-done" | "session:model-changed" | "session:config-changed" | "session:renamed" | "session:pinned-changed" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed" | "activity:changed" | "task:changed" | "workflow:gate-report" | "session:harness-warning";
 /**
  * Fixed severity vocabulary for a judge-gate finding (WP-D). Deliberately
  * small and fixed so `policy_status` output is comparable across different
@@ -1813,6 +1813,26 @@ interface SessionPermissionRequestEvent {
     label?: string;
     ts: string;
 }
+/**
+ * Emitted when a client's next prompt text matched one of a structured
+ * `awaitingQuestion`'s `options` (case-insensitive, trimmed) and was
+ * therefore treated as an answer instead of a normal turn — see
+ * `sessions.ts`'s structured-question-answer dispatch. Distinct from
+ * `session:awaiting-input-flagged`: that fires for an EXTERNAL manual
+ * override of the flag; this fires when the session's own declared options
+ * were used as intended, by whichever seam the prompt came through
+ * (`agent_prompt`, the HTTP prompt route, or the CLI).
+ */
+interface SessionAwaitingQuestionAnsweredEvent {
+    type: "session:awaiting-question-answered";
+    sessionId: string;
+    /** The matched option string, verbatim from `question.options`. */
+    answer: string;
+    /** The question that was answered. */
+    question: SessionAwaitingQuestion;
+    label?: string;
+    ts: string;
+}
 /**
  * Emitted when a parked permission is resolved — by an inbox
  * approve/deny, or auto-`cancelled` when the session is torn down while the
@@ -2272,7 +2292,72 @@ interface TaskChangedEvent {
     sessionId?: string;
     ts: string;
 }
-type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionAwaitingInputFlaggedEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionReapedEvent | SessionStalledEvent | SessionStallClearedEvent | SessionWatcherAttachedEvent | SessionWatcherDetachedEvent | SessionBgTasksParkedEvent | SessionBgTasksClearedEvent | SessionResumedEvent | SessionSpawnedEvent | SessionCommandDoneEvent | SessionModelChangedEvent | SessionConfigChangedEvent | SessionRenamedEvent | SessionPinnedEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent | ActivityChangedEvent | TaskChangedEvent;
+/**
+ * Emitted by the workflow runner (`workflow-runner.ts`) for every `kind:
+ * "gate"` step command attempt — not just the last — carrying that attempt's
+ * pass/fail, exit code, and parsed report (AIP-15 P3). Rides the same bus
+ * fan-out as every other lifecycle event (`session_events_poll`, the
+ * webhook notifier, `session_monitor`), giving a live watcher visibility
+ * into a retry-with-reprompt loop as it happens, not just its final state.
+ */
+interface WorkflowGateReportEvent {
+    type: "workflow:gate-report";
+    runId: string;
+    stepId: string;
+    ok: boolean;
+    exitCode: number;
+    report: unknown;
+    attempt: number;
+    ts: string;
+}
+/**
+ * Emitted by the workflow runner (`workflow-runner.ts`) when a `kind:
+ * "approval"` step parks its run awaiting a human decision — the run's
+ * status flips to `awaiting-approval`, `workflow_status` carries
+ * `awaitingApproval`, and `workflow_escalation_resolve` (approval form)
+ * resolves it. Same bus distribution as every other lifecycle event.
+ */
+interface WorkflowApprovalRequestedEvent {
+    type: "workflow:approval-requested";
+    runId: string;
+    approvalId: string;
+    stepId: string;
+    prompt: string;
+    approvers: readonly string[];
+    artifacts?: readonly string[];
+    requestedAt: string;
+    ts: string;
+}
+/**
+ * Emitted by the workflow runner when a parked approval is resolved — by a
+ * human (`workflow_escalation_resolve`), a timeout (`who: "timeout"`), or a
+ * cancel. The run resumes (or unwinds) right after this fires.
+ */
+interface WorkflowApprovalResolvedEvent {
+    type: "workflow:approval-resolved";
+    runId: string;
+    approvalId: string;
+    stepId: string;
+    approved: boolean;
+    who: string;
+    note?: string;
+    ts: string;
+}
+/**
+ * Emitted when a `kind: "agent"` step's `harness` block declared a field the
+ * spawn couldn't honor (today: `harness.tools` — no adapter exposes a
+ * generic per-spawn tool allowlist this runtime can drive; see
+ * `AgentHarness.tools`'s doc) — the "never silently ignore" fallback AIP-15
+ * P2 requires. Same bus distribution as every other lifecycle event.
+ */
+interface SessionHarnessWarningEvent {
+    type: "session:harness-warning";
+    sessionId: string;
+    warnings: string[];
+    label?: string;
+    ts: string;
+}
+type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionAwaitingInputFlaggedEvent | SessionAwaitingQuestionAnsweredEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionReapedEvent | SessionStalledEvent | SessionStallClearedEvent | SessionWatcherAttachedEvent | SessionWatcherDetachedEvent | SessionBgTasksParkedEvent | SessionBgTasksClearedEvent | SessionResumedEvent | SessionSpawnedEvent | SessionCommandDoneEvent | SessionModelChangedEvent | SessionConfigChangedEvent | SessionRenamedEvent | SessionPinnedEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent | ActivityChangedEvent | TaskChangedEvent | WorkflowGateReportEvent | WorkflowApprovalRequestedEvent | WorkflowApprovalResolvedEvent | SessionHarnessWarningEvent;
 interface SessionEventBus {
     emit(ev: SessionEvent): void;
     /** Subscribe to a specific event type. Returns an unsubscribe fn. */
@@ -3401,6 +3486,23 @@ declare function createActivityProjector(opts: {
  */
 type AgentsMdMode = "inline" | "pointer" | "absent";
 
+/** What a served app records on the session descriptor and echoes in the
+ *  spawn result — non-secret, caller-visible. */
+interface SessionAppServeInfo {
+    /** App id the box's `app_install` registered. */
+    appId: string;
+    /** The in-box app dir that was installed + served. */
+    dir: string;
+    /** Port the UI binds inside the box. */
+    port: number;
+    /** Provider-resolved public URL for the served UI. */
+    url: string;
+    /** True when a probe against `url` answered OK within the readiness
+     *  window. False means the URL is the right address but the server had
+     *  not answered yet — retry the fetch rather than re-spawning. */
+    ready: boolean;
+}
+
 /**
  * Policy layer for `agent_start.worktree` — the config-driven decision of
  * WHETHER to isolate a spawn into its own git worktree, kept deliberately
@@ -3870,6 +3972,17 @@ type AgentAdapterResolver = (slug: string) => Promise<{
          *  no caller-facing `env` passthrough on `agent_start` today, so this is
          *  daemon-authored only, not a general escape hatch. */
         env?: Record<string, string>;
+        /** Absolute paths OUTSIDE the session cwd the adapter's workspace
+         *  toolset may READ (never write). Daemon-authored only — used for the
+         *  exact AGENTS.md file an inherited (pointer-mode) prompt names, so a
+         *  cwd below the repo root can actually read the contract file its
+         *  prompt points at instead of erroring
+         *  (`path … escapes the workspace`). NOT a general escape hatch: the
+         *  driver forwards these to its confinement layer as extra READ paths
+         *  and (for the mastra-agent adapter) to `makeWorkspaceTools` as a
+         *  read-only grant; writes and sibling reads stay denied. Adapters
+         *  that can't model the grant ignore it. */
+        additionalReadPaths?: string[];
     }): Promise<AgentSessionLike>;
     /** Display label for the descriptor's `command` field. */
     commandPreview?: string;
@@ -3973,6 +4086,11 @@ interface AdapterListEntry {
      * cli`'s `AdapterInfo.routeSelection` without importing it.
      */
     routeSelection?: "free" | "derived-from-model";
+    /** Known-valid model identifiers for this adapter (`@agentproto/cli`'s
+     *  `AdapterInfo.models`, forwarded verbatim). Undefined when the lister
+     *  behind `AgentAdapterLister` doesn't populate it — `adapter_list`'s
+     *  `summary` projection depends on this being present. */
+    models?: string[];
 }
 type AgentAdapterLister = () => Promise<AdapterListEntry[]>;
 /**
@@ -4291,6 +4409,11 @@ interface AgentStreamEvent {
      *  @agentproto/acp's `StreamEvent`'s `agent-prompt` kind. Harness-shaped
      *  and untyped; don't assume a stable schema across adapters. */
     rawInput?: unknown;
+    /** "agent-prompt" `_meta` bag, e.g. an ACP `requestPermission`'s
+     *  `toolCall._meta` (mastra-agent's `mastra-agent/suspendPayload` carries a
+     *  submit_plan's plan text there) — see @agentproto/acp's `StreamEvent`'s
+     *  `agent-prompt` kind. Harness-shaped and untyped. */
+    _meta?: unknown;
     /** "plan" event title — see @agentproto/acp's `StreamEvent`'s `plan` kind. */
     title?: string;
     /** "plan" event entries — see @agentproto/acp's `StreamEvent`'s `plan` kind. */
@@ -5207,6 +5330,16 @@ interface SessionDescriptor {
     /** True when the session has been hard-stopped by the context-continuity
      *  policy — no new prompt may be admitted. */
     contextContinuityHardStopped?: boolean;
+    /** The context percentage at which the user last answered "keep-going" to
+     *  the `ask`-mode continue-fresh question. `evaluateContextContinuity`
+     *  won't re-raise the same question until `contextPct` climbs past this
+     *  value again — otherwise the very next turn-boundary check (context
+     *  hasn't moved) would immediately re-ask, since the `ask` state covers
+     *  the whole `[compactAtPct, hardStopAtPct)` band, not just the instant it
+     *  was crossed. The hard-stop threshold is never suppressed by this — it
+     *  is checked ahead of `ask` in `contextContinuityStateForPct` and fires
+     *  regardless of any acknowledgment. */
+    contextContinuityAckedAtPct?: number;
     /** Id of the most recent checkpoint created for this session. */
     checkpointId?: string;
     /** When this session was continued fresh, the source session id. */
@@ -5288,6 +5421,15 @@ interface SessionDescriptor {
      *  default, ephemeral) or `"pause"` (keeps `sandboxId` reconnectable via
      *  `agent_start.sandbox.reuse`). Only set when `remote` is true. */
     sandboxTeardown?: "kill" | "pause";
+    /** App ports exposed at boot time (`SandboxSpec.extraPorts`) — maps port
+     *  number to its public URL. Only present for sandbox sessions where the
+     *  provider resolved `extraPorts` into `BootedSandbox.ports`. */
+    sandboxPorts?: Record<number, string>;
+    /** WP3 — an app UI served from INSIDE this sandbox session's box
+     *  (`agent_start.appServe`): the box-installed appId, the in-box dir, the
+     *  serve port, and the provider-resolved public URL. See
+     *  `sandbox-app-serve.ts`. */
+    appServe?: SessionAppServeInfo;
 }
 /**
  * Lightweight panel projection of SessionDescriptor for the VS Code Sessions
@@ -5392,6 +5534,8 @@ interface SessionSummary {
     remote?: boolean;
     sandboxId?: string;
     sandboxTeardown?: "kill" | "pause";
+    sandboxPorts?: Record<number, string>;
+    appServe?: SessionAppServeInfo;
 }
 /**
  * Thrown by the lazy resume path when a resumable session has already failed to
@@ -5515,15 +5659,27 @@ interface PendingPermission {
      * schema across adapters.
      */
     rawInput?: unknown;
+    /**
+     * The tool call's `_meta` (e.g. mastra-agent's `mastra-agent/suspendPayload`
+     * carrying a submit_plan's plan text), carried through from the ACP
+     * `agent-prompt` event's `_meta` field when the driver supplied one.
+     * Harness-shaped and untyped — don't assume a stable schema across adapters.
+     */
+    _meta?: unknown;
 }
 /** How a caller resolves a pending permission — an explicit `optionId` wins
  *  over the `decision`→option mapping (approve → an allow-flavored option,
  *  deny → a reject-flavored option). `scope: "always"` prefers an
- *  allow-always option when the request offers one. */
+ *  allow-always option when the request offers one. `feedback` is optional
+ *  free text (e.g. "reject, but do X instead") sent alongside the outcome —
+ *  the acp client forwards it on the ACP outcome's `_meta`
+ *  (`agentproto/feedback`) for adapters that consume it (mastra-agent folds
+ *  it into a suspension's resumeData). */
 interface PermissionRespondInput {
     decision: "approve" | "deny";
     optionId?: string;
     scope?: "once" | "always";
+    feedback?: string;
 }
 type PermissionRespondResult = {
     ok: true;
@@ -6369,6 +6525,12 @@ interface SpawnAgentInput {
     /** What session close does to the box, when `remote` is true — see
      *  `SessionDescriptor.sandboxTeardown`. */
     sandboxTeardown?: "kill" | "pause";
+    /** Port-to-URL map from the booted sandbox — see
+     *  `SessionDescriptor.sandboxPorts`. */
+    sandboxPorts?: Record<number, string>;
+    /** WP3 — in-box app-serve echo (`agent_start.appServe`), recorded verbatim
+     *  onto {@link SessionDescriptor.appServe}. See `sandbox-app-serve.ts`. */
+    appServe?: SessionAppServeInfo;
     /** True when the driver session was started in permission-hold mode
      *  (`AgentCliStartOptions.permissionHold`) — its `agent-prompt` events carry
      *  respondable permission requests. Gates whether the registry registers