@agen-ai/provider-acp 0.4.3 → 0.4.4

package/README.md

@@ -1,17 +1,20 @@
 # @agen-ai/provider-acp
 
 An optional provider for the AgenAI coding-agent runtime. It translates the stable
-Agent Client Protocol wire version 1 into the existing Agent Protocol V12 session
-API. The coordinated release is `0.4.3`; published `0.4.1` qualification remains
-historical evidence for its exact V11 artifacts.
+Agent Client Protocol wire version 1 into the Agent Protocol V13 session API. Current source is
+the unpublished coordinated eight-package `0.4.4` candidate. Published `0.4.3` is the seven-package
+V12 release; published `0.4.1` qualification remains historical evidence for its exact V11 artifacts.
 The package is ESM, MIT licensed, side-effect-free on import and requires Node.js
 22 or newer. It depends only on the public transport, runtime and protocol packages;
 the core packages remain independent of ACP.
 
 The provider pins the transport's `schema-v1.23.0` stable profile. It translates
-ACP into current V12 capabilities and rejects unsupported semantics explicitly.
+ACP into current V13 capabilities and rejects unsupported semantics explicitly.
 Connection negotiation, configured host facilities, and mapping policy fix one
 capability envelope per instance; every later connection must match it.
+The [0.4.4 upgrade guide](../../UPGRADING-TO-0.4.4.md) describes the coordinated candidate.
+Optional `@agen-ai/agent-history` browsing remains independent of this execution provider; native
+transcript JSON and ACP metadata alone establish no structured-generation capability.
 
 Tool approvals default to once-only scoped consequences. Both constructors accept an explicit
 `permissionMapping` selection for completely described provider-managed remembered choices.
@@ -53,9 +56,11 @@ under a different policy.
 | Surface | Supported behavior and requirements |
 | --- | --- |
 | Turns and requests | Default text turns, streamed assistant/reasoning text, tool progress, cancellation and once-only exact-action permissions by default, with opt-in complete remembered-choice mappings. One execution retains the original native prompt across request waits and answers. |
+| Execution input | Unsupported for every public ACP/Grok composition. There is no input mapping selection or native interjection dispatch; peer labels, metadata and extension advertisements cannot enable it. |
+| Structured final output | Unsupported for generic ACP. Explicit `grok-build-1.0.62-structured-output-v1` mapping supports native turn-scoped `agenai.output-schema.v1` requests and independently validated terminal objects, within the bounds below. |
 | Resume | Exact persisted binding using advertised `session/resume`, otherwise advertised `session/load`. Load history is bounded and suppressed from new-turn output. No automatic recreation after failure. |
 | Configuration | Managed by default. Explicit `configuration: 'selectable'` maps observed boolean/select catalogs, with a session-mode fallback when config options are absent. Unknown metadata differs from observed empty metadata. |
-| Forms | Canonical boolean/single-select/multi-select forms that fit V12 constraints. An intent stage preserves decline separately from cancel, followed by answers on the same native waiter. Explicit host form facilities can handle broader native forms. |
+| Forms | Canonical boolean/single-select/multi-select forms that fit V13 constraints. An intent stage preserves decline separately from cancel, followed by answers on the same native waiter. Explicit host form facilities can handle broader native forms. |
 | Images | Inline base64 PNG/JPEG/WebP only when the peer advertises image input, within image and total turn budgets. No implicit local-file read or URL fetch. |
 | Plans | Complete replacements of observed turn plans. A mode called “plan” does not establish enforced planning behavior or approval authority. |
 | File changes | Partial structured observations from native tool diffs. Canonical paths contained by the working directory become sorted relative display paths without filesystem reads. Unfinished tools remain unknown at ordinary turn completion. No final workspace diff or Review artifact is inferred. |
@@ -69,7 +74,7 @@ Through-turn branching, same-turn steering, enforced plan mode, persistent
 SDK-owned tool-approval grants, context usage/compaction, account quota, effective skill/rule
 inventory, collaboration, generated resources and artifact publication remain
 unsupported. ACP usage counters can decrease without confirmed compaction and
-cannot satisfy V12's context continuity contract. Unsupported media output fails
+cannot satisfy V13's context continuity contract. Unsupported media output fails
 explicitly rather than disappearing from an otherwise successful transcript.
 Embedded terminal references also fail explicitly: a mutable, possibly truncated
 terminal snapshot does not provide an ordered append-only transcript. Agents can
@@ -80,9 +85,121 @@ this release. Host-owned integrations may use the transport directly with their
 own authorization and native lifecycle policy. No capability grants authority
 over other conversations or account state.
 
+## Input during an execution
+
+The optional runtime `execution.input` contract is available in the unpublished `0.4.4`
+candidate, but this provider exposes no supported execution-input port. Consumers must narrow
+`execution.input?.kind === 'supported'` before sending. Absence and `{ kind: 'unsupported' }`
+both mean unsupported; use ordinary `startTurn()` for new work when idle. Strict `turns.steer`
+semantics are unchanged and remain unsupported here. The
+[runtime README](../agent-runtime/README.md) explains receipt, consumption and output ownership.
+
+Stable ACP `schema-v1.23.0` negotiation and standard unknown-extension handling do not grant
+native input support. Grok Build `1.0.67` has native interjection facilities, but the inspected
+behavior did not establish an authoritative input-to-command link, ownership of autonomous wake
+work, or reusable-session producer quiescence. Queued acknowledgements, matching text and empty
+queue snapshots cannot establish those guarantees. No Grok input mapping is shipped. The
+independent Grok `1.0.62` structured-output mapping and history qualification retain their own
+versions and scope.
+
+Installed public-package proof exercises six unsupported cases: generic ACP, Grok labels and
+input advertisements, and the selected Grok `1.0.62` structured-output mapping, each with borrowed
+and owned connections. The actual packed provider constructors use a synthetic serialized peer;
+all six retain one original turn and reader, dispatch zero native input requests, and join cleanup.
+An unsolicited input extension request receives `-32601`. This is public unsupported-boundary
+proof, separate from private controlled Claude qualification; no public Claude execution constructor ships.
+
+## Structured final output
+
+ACP schema `1.23.0` does not define a portable final-output-schema capability. Generic provider
+instances declare `turns.structuredOutput: { kind: 'unsupported' }`. Standard unknown-extension
+handling, a peer accepting metadata, or JSON-looking assistant text cannot enable it.
+
+Both constructors accept one exact opt-in native mapping:
+
+```ts
+import { parseAgentProviderKey } from '@agen-ai/agent-protocol';
+import { createNodeAcpProviderDriver } from '@agen-ai/provider-acp/node';
+
+const driver = createNodeAcpProviderDriver({
+  providerKey: parseAgentProviderKey('grok-build'),
+  structuredOutputMapping: { mapping: 'grok-build-1.0.62-structured-output-v1' },
+  launch: {
+    executable: approvedExecutable,
+    args: ['agent', '--no-leader', 'stdio'],
+    cwd: workingDirectory,
+    env: explicitNativeEnvironment,
+  },
+});
+```
+
+The host supplies and verifies the executable, environment, credentials and confinement policy.
+For injected connections, pass the same `structuredOutputMapping` to `createAcpProviderDriver`.
+The selection is captured at construction; each connection must negotiate the pinned stable ACP
+profile and initialize with Grok's exact `grokShell: true` / `agentVersion: '1.0.62'` identity.
+Initialization identity is an admission check, not executable provenance or inference proof.
+Changing a mapping needs a new driver/materialization; it is absent from serialized empty
+`driverConfiguration`.
+
+The supported declaration has `mechanism: 'native'`,
+`schemaProfile: 'agenai.output-schema.v1'`, `scope: 'turn'`, `maxSchemaBytes: 16_384`,
+`maxOutputBytes: 16_384`, `resume: false`, and `branch: false`. Supply the schema on `startTurn`,
+or use [`generateObject`](../agent-runtime/README.md#generate-a-typed-object), which borrows the
+selected instance and owns a fresh session through cleanup. Session-opening output is rejected.
+A later ordinary turn omits `output` and sends no schema. Ordinary exact-binding resume remains
+separate; structured requests cannot restore schema state through resume or branch.
+
+The mapping sends the admitted schema through prompt `_meta.outputSchema` and reads only the
+correlated authoritative prompt response's `_meta.structuredOutput`. A successful `end_turn`
+and a complete schema-valid object are both required for terminal `structuredOutput.kind: 'json'`.
+Text deltas are not parsed as output, and the SDK never extracts a JSON substring or repairs it.
+The shared runtime validates the candidate independently against the exact admitted schema.
+
+| Native observation | Portable structured result |
+| --- | --- |
+| `refusal` | `unavailable/refused`, preserving native completed outcome |
+| Non-`end_turn` stop, including token/request limit or cancellation | `unavailable/incomplete`, preserving native outcome |
+| Successful `end_turn` without structured metadata | `unavailable/missing_output` |
+| Bounded native `structuredOutputError` | `unavailable/provider_error`; Grok's free text cannot distinguish exhausted retries from other native validation errors |
+| Oversized metadata/value | `unavailable/output_limit_exceeded` |
+| Complete object that fails the admitted schema | `unavailable/schema_mismatch` with bounded issues |
+
+Native structured metadata is capped at 32,768 UTF-8 bytes and its error string at 4,096 bytes.
+The canonical schema/value ceilings are each 16,384 serialized bytes, with the additional
+[portable shape limits](../agent-protocol/README.md#the-agenaioutput-schemav1-profile). Ambiguous
+value-plus-error metadata, a wrong native session identity, or malformed error metadata is a
+contract failure. Ordinary turns report `structuredOutput: { kind: 'not_requested' }`.
+Only `outcome: 'completed'` can carry `json`; a native finished turn does not guarantee generation
+success. There is no SDK generation retry, fallback model or tool replay. Native validation/fallback
+attempts may occur inside the provider's one prompt and are not described as SDK retries.
+
+Selecting this mapping does not disable native tools or alter host permission policy. A generation
+that requires a human response needs an explicit handler; the helper fails with
+`interaction_required` when one is absent. Retain cleanup errors and their callable retry owners
+as described by the [runtime generation lifecycle](../agent-runtime/README.md#deadlines-requests-and-cleanup).
+
+### Qualified installed native scope
+
+The 2026-10-22 qualification used all eight installed public `0.4.4` candidate tarballs, only public
+entrypoints, stable ACP schema `1.23.0`, Linux x86_64 / Node `24.18.0`, Grok Build `1.0.62`
+(`1474f9cbdd91`), `grok-4.3`, low reasoning and explicit xAI API-key authentication. The executable
+SHA-256 was `2a46d9e4d7ebd7a9cff7f95716714b19dad5f21dd2a497822400b1fb128969aa`.
+The shipped title example returned a typed title and saved it after session/reader closure. Further
+native turns produced an independently validated rich nested object, a changed `{ count: 7 }`
+schema, and ordinary `Ready` text with no schema. Sessions/readers closed, both observed native
+process groups were absent, the caller-owned registry was disposed and owned scratch removed.
+
+This exact local tuple establishes the public mapping's installed native behavior. It does not
+qualify generic ACP, other Grok releases/models/authentication modes, OpenCode, Cursor or arbitrary
+harnesses. Process-group evidence does not establish escaped-descendant or cgroup containment;
+the Node launcher grants no production execution authority or backend billing guarantee. The
+separate private Codex and Claude diagnostic mappings are not public provider packages and cannot
+be imported through this package. Existing history/delegation/approval qualifications below keep
+their original version-specific scope. The `0.4.4` candidate remains unpublished.
+
 ## Operational failures and uncertainty
 
-The provider maps supported standard `schema-v1.23.0` prompt errors into V12 `AgentError` values.
+The provider maps supported standard `schema-v1.23.0` prompt errors into V13 `AgentError` values.
 Standard `-32000` reports `authentication` with an `authenticate` user-action hint; `-32602` reports
 `invalid_request`; `-32603` reports `provider`; standard parse/request/method errors report `protocol`.
 Other remote codes remain `unknown` with unknown recovery. Mapping uses the standard error code,
@@ -414,7 +531,7 @@ unknown-extension handling never enables it implicitly.
 The selected launch arguments are exactly `['agent', '--no-leader', 'stdio']`.
 The adapter exposes the exact `sessionInteractions.mappings` tuple
 `{ openingOperation: 'create', requestKind: 'decision' }`, exclusive producer
-ownership and, in current 0.4.3 source, `humanWait: ['bounded', 'until_withdrawn_or_closed']`. The handler receives a neutral workspace
+ownership and, in current source, `humanWait: ['bounded', 'until_withdrawn_or_closed']`. The handler receives a neutral workspace
 decision and can keep its response capability after opening returns, before
 any model turn. Use the generic
 [runtime lifecycle](../agent-runtime/README.md#session-lifetime-interactions)
@@ -479,7 +596,7 @@ other builds/platforms, browser login, native durable recovery, SDK-managed
 remembered permissions or private execution support. The earlier failed native
 ownership attempt remains unqualified.
 
-The current V12 decision descriptor omits `expiresAt` because this native mapping reports no
+The current V13 decision descriptor omits `expiresAt` because this native mapping reports no
 provider-owned expiry. The bounded host timer remains a separate policy boundary;
 `humanWait: { kind: 'until_withdrawn_or_closed' }` omits that human timer and
 rejects an explicitly supplied `limits.requestTimeoutMs`. Initialization,
@@ -494,7 +611,7 @@ validated consumer facade. Session forms, plan reviews and native continuations
 remain unsupported by `grok-folder-trust-v1`. The retained SDK02 native evidence
 above remains specific to its original finite waiting configuration.
 
-## Restored plan requests in current 0.4.3 source
+## Restored plan requests
 
 The Node constructor accepts a separate explicit selection:
 `sessionInteractions: { mapping: 'grok-build-1.0.60-session-requests-v1' }`.
@@ -921,8 +1038,8 @@ close ends that handle's ownership. The host retains control over its process po
 Canonical forms preflight the whole schema before presenting a request. They
 support at most 16 ordinary fields and 100 choices per selection. Free-text fields,
 nested objects, numeric fields, defaults, patterns/formats, and constraints without
-a V12 representation are rejected. Native free text permits blank/whitespace values
-and measures length in Unicode code points; V12 text answers use nonblank/UTF-16
+a V13 representation are rejected. Native free text permits blank/whitespace values
+and measures length in Unicode code points; V13 text answers use nonblank/UTF-16
 bounds. The provider does not narrow those native semantics silently. Enumerated
 string values can map through opaque canonical selection IDs.
 A required multi-select must require exactly one minimum selection; an optional
@@ -943,7 +1060,7 @@ binding grants no interaction authority. Their host callbacks receive a turn
 lifetime signal that ends on cancellation, settlement or close.
 
 Image input allows at most 16 images, 375,000 decoded bytes per image and 750,000
-decoded bytes total, subject to the stricter 1 MiB V12 turn-content bound. Declared
+decoded bytes total, subject to the stricter 1 MiB V13 turn-content bound. Declared
 media type, dimensions, base64 encoding and byte counts are validated. The provider
 does not decode pixels or publish generated bytes; hosts needing image-content
 inspection must perform it before submitting input.
@@ -952,18 +1069,40 @@ inspection must perform it before submitting input.
 
 `limits` can override `maxQueuedMessages`, `maxQueuedBytes`,
 `maxPendingRequests`, `maxHostTerminals`, `hostOperationTimeoutMs`,
-`authenticationTimeoutMs`, `initializationTimeoutMs`, `promptTimeoutMs`, and
+`authenticationTimeoutMs`, `initializationTimeoutMs`, `terminalWaitTimeoutMs`, and
 `cancellationTimeoutMs`. Defaults share a 128-entry, 8 MiB budget across queued
 sources and retained current-turn item state, with output/control headroom
 reserved inside that budget. Large bursts and turns with many retained items
 can exhaust the same budget. Defaults allow 16 pending requests, 16 host terminals,
 30 seconds for initialization or a host operation, 15 minutes for authentication,
-30 minutes for a prompt, and 5 seconds for cancellation. Admission
+30 minutes for an individual host-terminal exit wait, and 5 seconds for cancellation. Admission
 reserves finite source capacity synchronously. Response and cancellation
 processing remain independent of slow output consumers. Overflow, malformed
 messages, process loss, or unconfirmed cancellation fail closed and require
 closing the unusable session before rematerialization.
 
+Ordinary prompts have no implicit execution deadline. Omit turn `deadlineAt` to
+retain the original prompt, sole output reader and connection until native
+completion, explicit cancellation or close. Startup, authentication, host APIs,
+human-decision policies, output capacity and cleanup keep their independent bounds.
+Selected native continuations also retain their original execution and reader;
+their preparation, promotion and response observations remain separately bounded.
+
+Set `deadlineAt` on each `startTurn` for a caller-selected finite execution budget,
+for example `new Date(Date.now() + 86_400_000).toISOString()` for one day. Distant
+dates use timer slices without an SDK business-duration ceiling or premature Node
+timer overflow. Expiry sends native `session/cancel` while retaining the original
+prompt RPC until its native terminal. A confirmed canceled response produces
+`expired`; an unconfirmed cancellation fails the session and starts owned cleanup.
+Neither expiry nor a cancellation request invents a completed native receipt.
+
+The former provider `limits.promptTimeoutMs` is rejected. Migrate its numeric
+budget to each turn's `deadlineAt`; use `terminalWaitTimeoutMs` only for host-terminal
+exit observation. That setting preserves the prior finite 30-minute default and
+maximum. A host-terminal wait timeout leaves its terminal lease owned for explicit
+kill/release or connection cleanup. Applications retain live owners and close them;
+unbounded prompt waiting does not provide controller-crash survival.
+
 Readiness reports completed initialization and the reported agent version when
 available. It does not prove authentication or inference. The Node launcher
 does not install agents, load credentials, apply a sandbox, or grant production

package/dist/capabilities.d.ts

@@ -2,5 +2,6 @@ import { type AgentAuthenticationFlow, type AgentCapabilities, type AgentProvide
 import type { AcpNegotiatedAgent } from './connection/contracts.js';
 import type { AcpSessionInteractionSelection } from './sessionInteractions/contracts.js';
 import type { AcpPermissionMappingSelection } from './permissions/contracts.js';
-export declare function acpProviderCapabilities(providerKey: AgentProviderKey, negotiated: AcpNegotiatedAgent, configuration?: 'managed' | 'selectable', authenticationFlows?: readonly AgentAuthenticationFlow[], sessionInteractions?: AcpSessionInteractionSelection, permissionMapping?: AcpPermissionMappingSelection): AgentCapabilities;
+import { type AcpStructuredOutputMappingSelection } from './structuredOutput/mapping.js';
+export declare function acpProviderCapabilities(providerKey: AgentProviderKey, negotiated: AcpNegotiatedAgent, configuration?: 'managed' | 'selectable', authenticationFlows?: readonly AgentAuthenticationFlow[], sessionInteractions?: AcpSessionInteractionSelection, permissionMapping?: AcpPermissionMappingSelection, structuredOutputMapping?: AcpStructuredOutputMappingSelection): AgentCapabilities;
 //# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.js

@@ -1,5 +1,6 @@
 import { parseAgentCapabilities } from "@agen-ai/agent-protocol";
 import { acpPermissionCapability } from "./permissions/selection.js";
+import { acpStructuredOutputCapability } from "./structuredOutput/mapping.js";
 function freezeCapabilities(value) {
   if (value && typeof value === "object") {
     for (const child of Object.values(value)) freezeCapabilities(child);
@@ -7,12 +8,12 @@ function freezeCapabilities(value) {
   }
   return value;
 }
-function acpProviderCapabilities(providerKey, negotiated, configuration = "managed", authenticationFlows = [], sessionInteractions, permissionMapping = { mapping: "once-only-v1" }) {
+function acpProviderCapabilities(providerKey, negotiated, configuration = "managed", authenticationFlows = [], sessionInteractions, permissionMapping = { mapping: "once-only-v1" }, structuredOutputMapping) {
   return freezeCapabilities(parseAgentCapabilities({
-    protocolVersion: 12,
+    protocolVersion: 13,
     providerKey,
     sessions: { create: true, resume: sessionInteractions?.mapping !== "grok-folder-trust-v1" && (negotiated.agentCapabilities.loadSession === true || negotiated.agentCapabilities.sessionCapabilities?.resume != null), branch: { kind: "unsupported" } },
-    turns: { interactionModes: ["default"], interrupt: true, steer: { kind: "unsupported" } },
+    turns: { structuredOutput: acpStructuredOutputCapability(structuredOutputMapping), interactionModes: ["default"], interrupt: true, steer: { kind: "unsupported" } },
     requests: {
       approval: acpPermissionCapability(permissionMapping),
       elicitation: { kind: "supported", fieldKinds: ["single_select", "multi_select", "boolean"], maxFields: 16, sensitiveFields: false }

package/dist/connection/contracts.d.ts

@@ -24,7 +24,7 @@ export interface AcpNegotiatedAgent {
         name: string;
         version: string;
     }>;
-    /** Bounded compatibility observation retained only by the selected Grok permission profile. */
+    /** Bounded native version observation retained by explicitly selected Grok mappings. */
     readonly agentVersion?: string;
     readonly agentCapabilities: AcpJsonObject;
     readonly authMethods: readonly AcpJsonValue[];

package/dist/connection/initialize.d.ts

@@ -5,6 +5,7 @@ import type { AcpConnectionAcquisition, AcpInitializedConnection } from './contr
 import type { AcpAuthenticationMethods, AcpHostFacilities } from '../host/contracts.js';
 import type { AcpSessionInteractionSelection } from '../sessionInteractions/contracts.js';
 import type { AcpPermissionMappingSelection } from '../permissions/contracts.js';
+import type { AcpStructuredOutputMappingSelection } from '../structuredOutput/mapping.js';
 export declare function initializeAcpConnection(input: {
     readonly source: AcpConnectionAcquisition;
     readonly unknownExtensionPolicy: AcpUnknownExtensionPolicy;
@@ -16,5 +17,6 @@ export declare function initializeAcpConnection(input: {
     readonly configuration?: 'managed' | 'selectable';
     readonly sessionInteractions?: AcpSessionInteractionSelection;
     readonly permissionMapping?: AcpPermissionMappingSelection;
+    readonly structuredOutputMapping?: AcpStructuredOutputMappingSelection;
 }): Promise<AcpInitializedConnection>;
 //# sourceMappingURL=initialize.d.ts.map

package/dist/connection/initialize.js

@@ -208,7 +208,7 @@ async function initializeAcpConnection(input) {
       signal: initialization.signal
     });
     if (stopped.signal.aborted) throw stopped.signal.reason;
-    const negotiated = readNegotiatedAgent(response, input.permissionMapping, input.sessionInteractions);
+    const negotiated = readNegotiatedAgent(response, input.permissionMapping, input.sessionInteractions, input.structuredOutputMapping);
     initialization.signal.removeEventListener("abort", onAbort);
     return Object.freeze({
       client,

package/dist/connection/negotiation.d.ts

@@ -2,7 +2,8 @@ import type { AcpJsonValue } from '@agen-ai/acp-transport';
 import type { AcpNegotiatedAgent } from './contracts.js';
 import type { AcpPermissionMappingSelection } from '../permissions/contracts.js';
 import type { AcpSessionInteractionSelection } from '../sessionInteractions/contracts.js';
+import { type AcpStructuredOutputMappingSelection } from '../structuredOutput/mapping.js';
 /** The transport has already validated the complete pinned initialize response. */
-export declare function readNegotiatedAgent(response: AcpJsonValue, permissionMapping?: AcpPermissionMappingSelection, sessionInteractions?: AcpSessionInteractionSelection): AcpNegotiatedAgent;
+export declare function readNegotiatedAgent(response: AcpJsonValue, permissionMapping?: AcpPermissionMappingSelection, sessionInteractions?: AcpSessionInteractionSelection, structuredOutputMapping?: AcpStructuredOutputMappingSelection): AcpNegotiatedAgent;
 export declare function negotiatedEnvelope(negotiated: AcpNegotiatedAgent): string;
 //# sourceMappingURL=negotiation.d.ts.map

package/dist/connection/negotiation.js

@@ -1,4 +1,5 @@
 import { AcpProviderConnectionError } from "./errors.js";
+import { assertAcpStructuredOutputIdentity } from "../structuredOutput/mapping.js";
 function immutableProtocolData(value) {
   if (Array.isArray(value)) {
     const items = value.map(immutableProtocolData);
@@ -11,7 +12,7 @@ function immutableProtocolData(value) {
   }
   return value;
 }
-function readNegotiatedAgent(response, permissionMapping = { mapping: "once-only-v1" }, sessionInteractions) {
+function readNegotiatedAgent(response, permissionMapping = { mapping: "once-only-v1" }, sessionInteractions, structuredOutputMapping) {
   const value = response;
   if (value.protocolVersion !== 1) {
     throw new AcpProviderConnectionError("acp_provider_version_unsupported", "ACP wire version 1 is required.");
@@ -28,6 +29,8 @@ function readNegotiatedAgent(response, permissionMapping = { mapping: "once-only
     agentInfo = Object.freeze({ name: info.name, version: info.version });
   }
   let agentVersion;
+  assertAcpStructuredOutputIdentity(value, structuredOutputMapping);
+  if (structuredOutputMapping) agentVersion = "1.0.62";
   if (sessionInteractions?.mapping === "grok-build-1.0.60-session-requests-v1") {
     const meta = value._meta;
     if (meta === null || typeof meta !== "object" || Array.isArray(meta) || meta.agentVersion !== "1.0.60") {

package/dist/contracts.d.ts

@@ -5,6 +5,7 @@ import type { AcpProviderLimits } from './limits.js';
 import type { AcpStandardMcpServer, AcpUnknownExtensionPolicy } from '@agen-ai/acp-transport';
 import type { AcpAuthenticationMethods, AcpHostFacilities } from './host/contracts.js';
 import type { AcpPermissionMappingSelection } from './permissions/contracts.js';
+import type { AcpStructuredOutputMappingSelection } from './structuredOutput/mapping.js';
 export type { AcpProviderLimits } from './limits.js';
 export interface AcpConnectionStreams {
     readonly stdout: Readable;
@@ -54,6 +55,8 @@ export interface CreateAcpProviderDriverOptions {
     readonly unknownExtensionPolicy?: AcpUnknownExtensionPolicy;
     /** Defaults to once-only choices; complete profiles require independently qualified native semantics. */
     readonly permissionMapping?: AcpPermissionMappingSelection;
+    /** Opts into the exact qualified native schema contract; absent means unsupported. */
+    readonly structuredOutputMapping?: AcpStructuredOutputMappingSelection;
     readonly limits?: Partial<AcpProviderLimits>;
     readonly configuration?: 'managed' | 'selectable';
     readonly authentication?: AcpAuthenticationMethods;

package/dist/driverFactory.js

@@ -7,6 +7,7 @@ import { resolveAuthenticationMapping } from "./auth/methods.js";
 import { resolveHostFacilities } from "./host/validation.js";
 import { resolveAcpMcpServers, resolveAcpSessionMcpBinding } from "./mcp.js";
 import { resolveAcpPermissionMapping } from "./permissions/selection.js";
+import { resolveAcpStructuredOutputMapping } from "./structuredOutput/mapping.js";
 function createAcpProviderDriverInternal(options, sessionInteractions) {
   const providerKey = parseAgentProviderKey(options.providerKey);
   const connectionSource = options.connectionSource;
@@ -21,6 +22,7 @@ function createAcpProviderDriverInternal(options, sessionInteractions) {
   const mcpServers = resolveAcpMcpServers(options.mcpServers);
   const sessionMcpBinding = resolveAcpSessionMcpBinding(options.sessionMcpBinding);
   const permissionMapping = resolveAcpPermissionMapping(options.permissionMapping);
+  const structuredOutputMapping = resolveAcpStructuredOutputMapping(options.structuredOutputMapping);
   const usedStreams = /* @__PURE__ */ new WeakSet();
   return defineAgentProviderDriver({
     providerKey,
@@ -38,6 +40,7 @@ function createAcpProviderDriverInternal(options, sessionInteractions) {
       host,
       mcpServers,
       permissionMapping,
+      ...structuredOutputMapping ? { structuredOutputMapping } : {},
       ...sessionMcpBinding ? { sessionMcpBinding } : {},
       ...sessionInteractions ? { sessionInteractions } : {}
     })

package/dist/host/router.d.ts

@@ -31,9 +31,19 @@ export declare class AcpHostRouter {
                 readonly requestId: AcpRequestId;
             }) => void;
             onResponseReceived: (response: import("@agen-ai/acp-transport").AcpResponseReceived) => void;
+            signal?: AbortSignal;
+            lifetime?: "bounded";
             timeoutMs?: number;
             deadlineAt?: number | Date;
+        } | {
+            onRequestDispatch: (context: {
+                readonly requestId: AcpRequestId;
+            }) => void;
+            onResponseReceived: (response: import("@agen-ai/acp-transport").AcpResponseReceived) => void;
             signal?: AbortSignal;
+            lifetime: "until_settled";
+            timeoutMs?: never;
+            deadlineAt?: never;
         };
         close: () => Promise<void>;
     };

package/dist/host/router.js

@@ -95,7 +95,7 @@ class AcpHostRouter {
       if (!ingress) throw invalidHostRequest();
       return ingress.onPermissionRequest(context);
     }
-    const timeout = context.method === "terminal/wait_for_exit" ? this.input.limits.promptTimeoutMs : this.input.limits.hostOperationTimeoutMs;
+    const timeout = context.method === "terminal/wait_for_exit" ? this.input.limits.terminalWaitTimeoutMs : this.input.limits.hostOperationTimeoutMs;
     const deadline = hostDeadline(session.signal, timeout);
     return this.hostRequest(context.method, params, { ...session, signal: deadline.signal }).finally(() => deadline.close());
   }

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { createAcpProviderDriver } from './driver.js';
 export { DEFAULT_ACP_PROVIDER_LIMITS, type AcpProviderLimits } from './limits.js';
 export { AcpProviderConnectionError } from './connection/errors.js';
 export { AcpProviderSessionError } from './session/errors.js';
+export type { AcpStructuredOutputMappingSelection } from './structuredOutput/mapping.js';
 export type { AcpPermissionOptionSignature, AcpPermissionMenuSignature, AcpPermissionMappingSelection, } from './permissions/contracts.js';
 export type { AcpConnectionStreams, AcpConnectionLease, AcpConnectionFactoryContext, AcpConnectionFactory, AcpSessionMcpBindingContext, AcpSessionMcpBindingLease, AcpSessionMcpBindingFactory, AcpSessionMcpBindingOptions, CreateAcpProviderDriverOptions, } from './contracts.js';
 export type { AcpAuthenticationMethods, AcpHostFacilities, AcpHostInteractionScope, AcpHostInteractionInput, AcpHostFormInput, AcpHostFormResponse, AcpHostUrlInput, AcpHostUrlDecision, AcpHostUrlInteractionLease, AcpHostSessionInput, AcpHostFileReadInput, AcpHostFileWriteInput, AcpHostTerminalCreateInput, AcpHostTerminalLease, AcpHostTerminalOutput, AcpHostTerminalExitStatus, AcpHostAuthenticationTerminalInput, AcpHostAuthenticationTerminalLease, } from './host/contracts.js';

package/dist/instance.d.ts

@@ -7,6 +7,7 @@ import type { AcpProviderLimits } from './limits.js';
 import type { AcpConnectionSource } from './connection/contracts.js';
 import type { AcpSessionInteractionSelection } from './sessionInteractions/contracts.js';
 import type { AcpPermissionMappingSelection } from './permissions/contracts.js';
+import type { AcpStructuredOutputMappingSelection } from './structuredOutput/mapping.js';
 export declare function createAcpProviderInstance(input: {
     readonly providerKey: AgentProviderKey;
     readonly instanceId: AgentInstanceId;
@@ -19,6 +20,7 @@ export declare function createAcpProviderInstance(input: {
     readonly host: AcpHostFacilities;
     readonly mcpServers: readonly AcpStandardMcpServer[];
     readonly permissionMapping: AcpPermissionMappingSelection;
+    readonly structuredOutputMapping?: AcpStructuredOutputMappingSelection;
     readonly sessionMcpBinding?: AcpSessionMcpBindingOptions;
     readonly sessionInteractions?: AcpSessionInteractionSelection;
 }): Promise<MaterializedAgentProviderInstance>;

package/dist/instance.js

@@ -43,6 +43,7 @@ async function createAcpProviderInstance(input) {
       authentication: input.authentication,
       host: input.host,
       permissionMapping: input.permissionMapping,
+      ...input.structuredOutputMapping ? { structuredOutputMapping: input.structuredOutputMapping } : {},
       ...input.sessionInteractions ? { sessionInteractions: input.sessionInteractions } : {}
     });
   };
@@ -53,7 +54,15 @@ async function createAcpProviderInstance(input) {
   try {
     assertAcpMcpSupport(input.mcpServers, negotiated);
     methods = selectedAuthenticationMethods(negotiated, input.authentication, input.host);
-    capabilities = acpProviderCapabilities(input.providerKey, negotiated, input.configuration, [...methods.keys()], input.sessionInteractions, input.permissionMapping);
+    capabilities = acpProviderCapabilities(
+      input.providerKey,
+      negotiated,
+      input.configuration,
+      [...methods.keys()],
+      input.sessionInteractions,
+      input.permissionMapping,
+      input.structuredOutputMapping
+    );
   } catch (cause) {
     if (eager.execution?.cleanupFailure) throw eager.execution.retainedError(cause, eager.execution.cleanupFailure.error);
     try {
@@ -133,6 +142,11 @@ async function createAcpProviderInstance(input) {
   const open = async (context, resume) => {
     throwIfAgentOperationAborted(context.signal);
     throwIfAgentOperationAborted(lifetime.signal);
+    if ("output" in context && context.output !== void 0) throw new AgentProviderContractError(
+      input.providerKey,
+      capabilities.turns.structuredOutput.kind === "unsupported" ? "structured_output_unsupported" : "structured_output_scope_mismatch",
+      "ACP structured output is accepted only when starting a turn."
+    );
     if (input.sessionInteractions?.mapping === "grok-folder-trust-v1" && resume) throw new AgentProviderContractError(
       input.providerKey,
       "session_interactions_unsupported",

package/dist/limits.d.ts

@@ -7,7 +7,7 @@ export interface AcpProviderLimits {
     readonly authenticationTimeoutMs: number;
     readonly cancellationTimeoutMs: number;
     readonly initializationTimeoutMs: number;
-    readonly promptTimeoutMs: number;
+    readonly terminalWaitTimeoutMs: number;
 }
 export declare const DEFAULT_ACP_PROVIDER_LIMITS: AcpProviderLimits;
 export declare function resolveAcpProviderLimits(overrides?: Partial<AcpProviderLimits>): AcpProviderLimits;

package/dist/limits.js

@@ -7,7 +7,7 @@ const DEFAULT_ACP_PROVIDER_LIMITS = Object.freeze({
   authenticationTimeoutMs: 15 * 6e4,
   cancellationTimeoutMs: 5e3,
   initializationTimeoutMs: 3e4,
-  promptTimeoutMs: 30 * 6e4
+  terminalWaitTimeoutMs: 30 * 6e4
 });
 const BOUNDS = {
   maxQueuedMessages: [4, 1024],
@@ -18,7 +18,7 @@ const BOUNDS = {
   authenticationTimeoutMs: [10, 30 * 6e4],
   cancellationTimeoutMs: [10, 6e4],
   initializationTimeoutMs: [10, 30 * 6e4],
-  promptTimeoutMs: [10, 30 * 6e4]
+  terminalWaitTimeoutMs: [10, 30 * 6e4]
 };
 function resolveAcpProviderLimits(overrides = {}) {
   if (Object.keys(overrides).some((key) => !Object.hasOwn(BOUNDS, key))) {

package/dist/node/index.js

@@ -15,6 +15,7 @@ function createNodeAcpProviderDriver(options) {
     connectionSource: reserve ? { kind: "reserved", reserve } : { kind: "factory", create: (context) => spawnAcpProcess(launch, context) },
     ...options.unknownExtensionPolicy !== void 0 ? { unknownExtensionPolicy: options.unknownExtensionPolicy } : {},
     ...options.permissionMapping !== void 0 ? { permissionMapping: options.permissionMapping } : {},
+    ...options.structuredOutputMapping !== void 0 ? { structuredOutputMapping: options.structuredOutputMapping } : {},
     ...options.limits ? { limits: options.limits } : {},
     ...options.configuration ? { configuration: options.configuration } : {},
     ...options.authentication ? { authentication: options.authentication } : {},

package/dist/session/completion.js

@@ -2,15 +2,16 @@ import { AcpProviderSessionError } from "./errors.js";
 import { nativeObject, nativeString } from "./native.js";
 function acpTurnCompletion(response, cancelReason) {
   if (response.kind === "error") return {
+    structuredOutput: { kind: "not_requested" },
     outcome: "failed",
     error: promptFailure(response.error.code)
   };
   const reason = nativeString(nativeObject(response.result, "prompt response").stopReason, "prompt stop reason");
-  if (reason === "cancelled") return { outcome: cancelReason === "timeout" ? "expired" : "canceled" };
-  if (reason === "end_turn") return { outcome: "completed" };
-  if (reason === "max_tokens") return { outcome: "completed", reason: "The agent reached its token limit." };
-  if (reason === "max_turn_requests") return { outcome: "completed", reason: "The agent reached its request limit." };
-  if (reason === "refusal") return { outcome: "completed", reason: "The agent declined the request." };
+  if (reason === "cancelled") return { structuredOutput: { kind: "not_requested" }, outcome: cancelReason === "timeout" ? "expired" : "canceled" };
+  if (reason === "end_turn") return { structuredOutput: { kind: "not_requested" }, outcome: "completed" };
+  if (reason === "max_tokens") return { structuredOutput: { kind: "not_requested" }, outcome: "completed", reason: "The agent reached its token limit." };
+  if (reason === "max_turn_requests") return { structuredOutput: { kind: "not_requested" }, outcome: "completed", reason: "The agent reached its request limit." };
+  if (reason === "refusal") return { structuredOutput: { kind: "not_requested" }, outcome: "completed", reason: "The agent declined the request." };
   throw new AcpProviderSessionError("acp_stop_reason_invalid", "ACP returned an unsupported prompt stop reason.");
 }
 function promptFailure(code) {

package/dist/session/deadline.d.ts

@@ -0,0 +1,2 @@
+export declare function scheduleTurnDeadline(deadlineAt: string, expire: () => void): () => void;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/session/deadline.js

@@ -0,0 +1,18 @@
+const MAX_TIMER_DELAY_MS = 2147483647;
+function scheduleTurnDeadline(deadlineAt, expire) {
+  const expiresAt = Date.parse(deadlineAt);
+  let timer;
+  const check = () => {
+    const remaining = expiresAt - Date.now();
+    if (remaining <= 0) {
+      expire();
+      return;
+    }
+    timer = setTimeout(check, Math.min(remaining, MAX_TIMER_DELAY_MS));
+  };
+  timer = setTimeout(check, Math.min(Math.max(0, expiresAt - Date.now()), MAX_TIMER_DELAY_MS));
+  return () => clearTimeout(timer);
+}
+export {
+  scheduleTurnDeadline
+};

package/dist/session/mapping.js

@@ -20,7 +20,7 @@ class TurnMapping {
   planRevision = 0;
   event(type, payload) {
     return createAgentEventOutput({
-      protocolVersion: 12,
+      protocolVersion: 13,
       sessionId: this.context.sessionId,
       turnId: this.context.turnId,
       occurredAt: this.context.now(),

package/dist/session/session.js

@@ -25,6 +25,9 @@ import { prepareAcpSessionElicitation } from "./requests/elicitation.js";
 import { canceledRequestReply, PendingSessionRequests } from "./requests/pending.js";
 import { nativeBytes, nativeObject, nativeString, SESSION_METADATA_UPDATES } from "./native.js";
 import { deferred, SessionQueue } from "./queue.js";
+import { prepareAcpStructuredOutput } from "../structuredOutput/request.js";
+import { acpStructuredOutputCompletion } from "../structuredOutput/completion.js";
+import { scheduleTurnDeadline } from "./deadline.js";
 class SessionState {
   constructor(input) {
     this.input = input;
@@ -286,16 +289,18 @@ class SessionState {
       throw new AcpProviderSessionError("acp_input_unsupported", "ACP supports only the default interaction mode.");
     }
     const prompt = prepareAcpPrompt(input.parts, this.input.capabilities);
-    const turn = this.createNativeTurn(input.turnId);
-    return this.execution(turn, () => this.streamTurn(turn, input, prompt));
+    const output = prepareAcpStructuredOutput(input.output, this.input.capabilities);
+    const turn = this.createNativeTurn(input.turnId, output?.schema);
+    return this.execution(turn, () => this.streamTurn(turn, input, prompt, output?.promptMeta));
   }
-  createNativeTurn(turnId) {
+  createNativeTurn(turnId, outputSchema) {
     this.requireUsable();
     if (this.turn && !this.turn.sourceSettled) throw new AcpProviderSessionError("acp_turn_active", "The ACP session already has an active or waiting turn.");
     const settled = deferred();
     void settled.promise.catch(() => void 0);
     const turn = {
       turnId,
+      ...outputSchema ? { outputSchema } : {},
       mapping: new TurnMapping({
         sessionId: this.input.context.sessionId,
         turnId,
@@ -348,7 +353,7 @@ class SessionState {
     this.queue.admit({ kind: "terminal", payload }, nativeBytes(payload), true);
     turn.settled.resolve(payload);
   }
-  launchTurn(turn, input, prompt) {
+  launchTurn(turn, input, prompt, promptMeta) {
     this.requireUsable();
     throwIfAgentOperationAborted(input.signal);
     if (turn.nativeSettled) return;
@@ -356,11 +361,17 @@ class SessionState {
     turn.nativeStarted = true;
     turn.prompt = this.operations.prompt({
       sessionId: this.nativeSessionId,
-      prompt
+      prompt,
+      ...promptMeta ? { _meta: promptMeta } : {}
     }, {
-      timeoutMs: this.input.limits.promptTimeoutMs,
+      lifetime: "until_settled",
       onResponseReceived: (response) => {
-        const payload = acpTurnCompletion(response, turn.cancelReason);
+        const payload = acpStructuredOutputCompletion(
+          acpTurnCompletion(response, turn.cancelReason),
+          response,
+          turn.outputSchema,
+          this.nativeSessionId
+        );
         this.completeNativeTurn(turn, payload);
       }
     }).then(() => void 0, (error) => {
@@ -376,8 +387,7 @@ class SessionState {
       if (input.signal.aborted) abort();
     }
     if (input.deadlineAt !== void 0) {
-      const timer = setTimeout(() => cancel("timeout"), Math.min(2147483647, Math.max(0, Date.parse(input.deadlineAt) - Date.now())));
-      turn.cleanup.push(() => clearTimeout(timer));
+      turn.cleanup.push(scheduleTurnDeadline(input.deadlineAt, () => cancel("timeout")));
     }
   }
   async *emit(output) {
@@ -499,10 +509,10 @@ class SessionState {
     if (turn.terminal) return;
     yield* this.emit(turn.mapping.event("turn.state_changed", { state: "waiting_for_request", requestId: canonical.requestId }));
   }
-  async *streamTurn(turn, input, prompt) {
+  async *streamTurn(turn, input, prompt, promptMeta) {
     let stable = false;
     try {
-      this.launchTurn(turn, input, prompt);
+      this.launchTurn(turn, input, prompt, promptMeta);
       yield* this.emit(turn.mapping.event("turn.started", {}));
       yield* this.drain(turn);
       await this.requests.join();
@@ -534,7 +544,7 @@ class SessionState {
     this.requests.cancelAll();
     turn.hostInteractions.abort(new DOMException("The ACP turn was canceled.", "AbortError"));
     if (!turn.nativeStarted) {
-      const payload = { outcome: reason === "timeout" ? "expired" : "canceled" };
+      const payload = { structuredOutput: turn.outputSchema ? { kind: "unavailable", reason: "incomplete" } : { kind: "not_requested" }, outcome: reason === "timeout" ? "expired" : "canceled" };
       turn.nativeSettled = true;
       this.queue.admit({ kind: "terminal", payload }, nativeBytes(payload), true);
       turn.settled.resolve(payload);

package/dist/session/turn.d.ts

@@ -1,5 +1,5 @@
 import type { AcpJsonObject } from '@agen-ai/acp-transport';
-import type { AgentRequestId, AgentTurnCompletedPayload, AgentTurnId } from '@agen-ai/agent-protocol';
+import type { AgentOutputSchema, AgentRequestId, AgentTurnCompletedPayload, AgentTurnId } from '@agen-ai/agent-protocol';
 import type { TurnMapping } from './mapping.js';
 import type { deferred } from './queue.js';
 import type { PendingSessionRequest } from './requests/pending.js';
@@ -19,6 +19,7 @@ export type SessionMessage = Readonly<{
 }>;
 export interface NativeTurn {
     readonly turnId: AgentTurnId;
+    readonly outputSchema?: AgentOutputSchema;
     readonly mapping: TurnMapping;
     readonly settled: ReturnType<typeof deferred<AgentTurnCompletedPayload>>;
     readonly cleanup: (() => void)[];

package/dist/structuredOutput/completion.d.ts

@@ -0,0 +1,4 @@
+import type { AcpResponseReceived } from '@agen-ai/acp-transport';
+import type { AgentOutputSchema, AgentTurnCompletedPayload } from '@agen-ai/agent-protocol';
+export declare function acpStructuredOutputCompletion(completion: AgentTurnCompletedPayload, response: AcpResponseReceived, schema: AgentOutputSchema | undefined, nativeSessionId: string): AgentTurnCompletedPayload;
+//# sourceMappingURL=completion.d.ts.map

package/dist/structuredOutput/completion.js

@@ -0,0 +1,55 @@
+import { createAgentStructuredOutputCandidate } from "@agen-ai/agent-runtime";
+import { AcpProviderSessionError } from "../session/errors.js";
+import { nativeBytes, nativeObject } from "../session/native.js";
+const GROK_STRUCTURED_METADATA_BYTES_LIMIT = 32768;
+const GROK_STRUCTURED_ERROR_BYTES_LIMIT = 4096;
+function structuredOutputResult(response, schema, nativeSessionId) {
+  if (!schema) return { kind: "not_requested" };
+  const unavailable = (reason) => createAgentStructuredOutputCandidate({
+    schema,
+    candidate: { kind: "unavailable", reason }
+  });
+  if (response.kind === "error") return unavailable("provider_error");
+  const result = nativeObject(response.result, "structured prompt response");
+  const meta = result._meta === void 0 ? void 0 : nativeObject(result._meta, "structured response metadata");
+  if (meta && nativeBytes(meta) > GROK_STRUCTURED_METADATA_BYTES_LIMIT) return unavailable("output_limit_exceeded");
+  if (meta?.sessionId !== void 0 && meta.sessionId !== nativeSessionId) {
+    throw new AcpProviderSessionError(
+      "acp_structured_output_identity_mismatch",
+      "Structured output metadata identifies a different native session."
+    );
+  }
+  const hasOutput = meta !== void 0 && Object.hasOwn(meta, "structuredOutput");
+  const hasError = meta !== void 0 && Object.hasOwn(meta, "structuredOutputError");
+  if (hasOutput && hasError) {
+    throw new AcpProviderSessionError(
+      "acp_structured_output_ambiguous",
+      "Structured output response contains both a value and an error."
+    );
+  }
+  if (hasError && (typeof meta?.structuredOutputError !== "string" || !meta.structuredOutputError.trim() || Buffer.byteLength(meta.structuredOutputError, "utf8") > GROK_STRUCTURED_ERROR_BYTES_LIMIT)) {
+    throw new AcpProviderSessionError(
+      "acp_structured_output_error_invalid",
+      "Structured output error must be a bounded nonempty native error string."
+    );
+  }
+  if (result.stopReason === "refusal") return unavailable("refused");
+  if (result.stopReason !== "end_turn") return unavailable("incomplete");
+  if (hasError) return unavailable("provider_error");
+  if (!hasOutput) return unavailable("missing_output");
+  return createAgentStructuredOutputCandidate({ schema, candidate: { kind: "json_value", value: meta?.structuredOutput } });
+}
+function acpStructuredOutputCompletion(completion, response, schema, nativeSessionId) {
+  const structuredOutput = structuredOutputResult(response, schema, nativeSessionId);
+  if (completion.outcome === "completed") return { ...completion, structuredOutput };
+  if (structuredOutput.kind === "json") {
+    throw new AcpProviderSessionError(
+      "acp_structured_output_terminal_invalid",
+      "A structured output value requires successful native completion."
+    );
+  }
+  return { ...completion, structuredOutput };
+}
+export {
+  acpStructuredOutputCompletion
+};

package/dist/structuredOutput/mapping.d.ts

@@ -0,0 +1,10 @@
+import { type AgentStructuredOutputCapability } from '@agen-ai/agent-protocol';
+import type { AcpJsonObject } from '@agen-ai/acp-transport';
+/** Explicit native contract; generic ACP metadata support does not imply this feature. */
+export interface AcpStructuredOutputMappingSelection {
+    readonly mapping: 'grok-build-1.0.62-structured-output-v1';
+}
+export declare function resolveAcpStructuredOutputMapping(input: unknown): AcpStructuredOutputMappingSelection | undefined;
+export declare function assertAcpStructuredOutputIdentity(initialized: AcpJsonObject, selected: AcpStructuredOutputMappingSelection | undefined): void;
+export declare function acpStructuredOutputCapability(selected: AcpStructuredOutputMappingSelection | undefined): AgentStructuredOutputCapability;
+//# sourceMappingURL=mapping.d.ts.map

package/dist/structuredOutput/mapping.js

@@ -0,0 +1,45 @@
+import {
+  AGENT_OUTPUT_SCHEMA_BYTES_LIMIT,
+  AGENT_OUTPUT_SCHEMA_PROFILE,
+  AGENT_OUTPUT_VALUE_BYTES_LIMIT
+} from "@agen-ai/agent-protocol";
+import { AcpProviderConnectionError } from "../connection/errors.js";
+function resolveAcpStructuredOutputMapping(input) {
+  if (input === void 0) return void 0;
+  if (input === null || typeof input !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) {
+    throw new TypeError("ACP structured output mapping must be an explicit selection.");
+  }
+  const keys = Reflect.ownKeys(input);
+  const descriptor = Object.getOwnPropertyDescriptor(input, "mapping");
+  if (keys.length !== 1 || keys[0] !== "mapping" || !descriptor || !("value" in descriptor) || !descriptor.enumerable || descriptor.value !== "grok-build-1.0.62-structured-output-v1") {
+    throw new TypeError("ACP structured output mapping is unsupported.");
+  }
+  return Object.freeze({ mapping: "grok-build-1.0.62-structured-output-v1" });
+}
+function assertAcpStructuredOutputIdentity(initialized, selected) {
+  if (!selected) return;
+  const meta = initialized._meta;
+  if (meta === null || typeof meta !== "object" || Array.isArray(meta) || meta.grokShell !== true || meta.agentVersion !== "1.0.62") {
+    throw new AcpProviderConnectionError(
+      "acp_structured_output_profile_mismatch",
+      "The selected structured output mapping requires exact Grok Build agentVersion 1.0.62."
+    );
+  }
+}
+function acpStructuredOutputCapability(selected) {
+  return selected ? {
+    kind: "supported",
+    mechanism: "native",
+    schemaProfile: AGENT_OUTPUT_SCHEMA_PROFILE,
+    scope: "turn",
+    maxSchemaBytes: AGENT_OUTPUT_SCHEMA_BYTES_LIMIT,
+    maxOutputBytes: AGENT_OUTPUT_VALUE_BYTES_LIMIT,
+    resume: false,
+    branch: false
+  } : { kind: "unsupported" };
+}
+export {
+  acpStructuredOutputCapability,
+  assertAcpStructuredOutputIdentity,
+  resolveAcpStructuredOutputMapping
+};

package/dist/structuredOutput/request.d.ts

@@ -0,0 +1,7 @@
+import { type AcpJsonObject } from '@agen-ai/acp-transport';
+import { type AgentCapabilities, type AgentOutputSchema, type AgentStructuredOutputRequest } from '@agen-ai/agent-protocol';
+export declare function prepareAcpStructuredOutput(request: AgentStructuredOutputRequest | undefined, capabilities: AgentCapabilities): Readonly<{
+    schema: AgentOutputSchema;
+    promptMeta: AcpJsonObject;
+}> | undefined;
+//# sourceMappingURL=request.d.ts.map

package/dist/structuredOutput/request.js

@@ -0,0 +1,19 @@
+import { assertBoundedAcpJson, DEFAULT_ACP_PROTOCOL_LIMITS } from "@agen-ai/acp-transport";
+import { parseAgentOutputSchema } from "@agen-ai/agent-protocol";
+import { AgentProviderContractError } from "@agen-ai/agent-runtime";
+function prepareAcpStructuredOutput(request, capabilities) {
+  if (request === void 0) return void 0;
+  if (capabilities.turns.structuredOutput.kind === "unsupported") {
+    throw new AgentProviderContractError(
+      capabilities.providerKey,
+      "structured_output_unsupported",
+      "The ACP provider has no selected native structured output mapping."
+    );
+  }
+  const schema = parseAgentOutputSchema(request.schema);
+  assertBoundedAcpJson(schema, DEFAULT_ACP_PROTOCOL_LIMITS);
+  return { schema, promptMeta: { outputSchema: schema } };
+}
+export {
+  prepareAcpStructuredOutput
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/provider-acp",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "private": false,
   "description": "Optional Agent Client Protocol provider for the AgenAI coding-agent runtime.",
   "type": "module",
@@ -27,9 +27,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@agen-ai/acp-transport": "^0.4.3",
-    "@agen-ai/agent-protocol": "^0.4.3",
-    "@agen-ai/agent-runtime": "^0.4.3"
+    "@agen-ai/acp-transport": "^0.4.4",
+    "@agen-ai/agent-runtime": "^0.4.4",
+    "@agen-ai/agent-protocol": "^0.4.4"
   },
   "devDependencies": {
     "tsup": "^8.5.0"