@agen-ai/provider-acp 0.4.1 → 0.4.3

package/dist/host/router.js

@@ -15,7 +15,7 @@ class AcpHostRouter {
   terminals;
   requests = /* @__PURE__ */ new Map();
   binding;
-  pending = 0;
+  pending = /* @__PURE__ */ new Map();
   bytes = 0;
   bindSession(binding) {
     if (this.binding && (binding.nativeSessionId !== this.binding.nativeSessionId || binding.sessionId !== this.binding.sessionId || binding.workingDirectory !== this.binding.workingDirectory)) {
@@ -54,32 +54,27 @@ class AcpHostRouter {
     };
   }
   admit(context) {
+    const params = hostObject(context.params);
+    if (context.method === "session/request_permission" || context.method === "elicitation/create" && Object.hasOwn(params, "sessionId")) return this.route(context, params);
     const bytes = Buffer.byteLength(JSON.stringify(context.params), "utf8");
-    if (this.pending >= this.input.limits.maxPendingRequests || this.bytes + bytes > this.input.limits.maxQueuedBytes) {
+    if (this.pending.size >= this.input.limits.maxPendingRequests || this.bytes + bytes > this.input.limits.maxQueuedBytes) {
       throw new AcpRpcHandlerError(-32603, "The host request capacity was exceeded.");
     }
-    this.pending += 1;
     this.bytes += bytes;
-    let result;
-    try {
-      result = this.route(context);
-    } catch (error) {
-      this.pending -= 1;
+    const retirement = context.settled.then(() => this.interactions.joinRequest(context.settled)).then(() => {
+      this.pending.delete(context.settled);
       this.bytes -= bytes;
-      throw error;
-    }
+    });
+    this.pending.set(context.settled, retirement);
+    const result = this.route(context, params);
     return result.then((value) => {
       if (Buffer.byteLength(JSON.stringify(value), "utf8") > Math.min(this.input.limits.maxQueuedBytes, 8 * 1024 * 1024) - 512) {
         throw invalidHostRequest();
       }
       return value;
-    }).finally(() => {
-      this.pending -= 1;
-      this.bytes -= bytes;
     });
   }
-  route(context) {
-    const params = hostObject(context.params);
+  route(context, params) {
     if (context.method === "elicitation/create") {
       const session2 = Object.hasOwn(params, "sessionId");
       const request = Object.hasOwn(params, "requestId");
@@ -143,20 +138,28 @@ class AcpHostRouter {
     const id = hostText(hostObject(value).elicitationId, 256);
     return this.interactions.complete(id);
   }
-  sessionElicitation(context) {
+  sessionElicitation(context, observeCallback) {
     const bound = this.requireSession(hostObject(context.params), context.signal);
     return this.interactions.request(context, {
       kind: "session",
       sessionId: bound.sessionId,
       workingDirectory: bound.workingDirectory
-    }, context.signal);
+    }, context.signal, observeCallback);
   }
   async close() {
     for (const request of this.requests.values()) request.abort();
     this.requests.clear();
-    const results = await Promise.allSettled([this.interactions.close(), this.terminals.close()]);
-    const failures = results.filter((result) => result.status === "rejected");
-    if (failures.length) throw new AggregateError(failures.map((result) => result.reason), "ACP host facility cleanup failed.");
+    const deadline = hostDeadline(new AbortController().signal, this.input.limits.hostOperationTimeoutMs);
+    const join = async () => {
+      while (this.pending.size > 0) await Promise.all(this.pending.values());
+    };
+    try {
+      const results = await Promise.allSettled([this.interactions.close(), this.terminals.close(), awaitHost(join(), deadline.signal)]);
+      const failures = results.filter((result) => result.status === "rejected");
+      if (failures.length) throw new AggregateError(failures.map((result) => result.reason), "ACP host facility cleanup failed.");
+    } finally {
+      deadline.close();
+    }
   }
 }
 export {

package/dist/instance.js

@@ -7,7 +7,6 @@ import {
   createAgentProviderSessionCleanupError,
   isAgentProviderSessionCleanupErrorFor,
   throwIfAgentOperationAborted,
-  validateAgentProviderAdapter,
   AgentProviderContractError,
   DEFAULT_AGENT_SESSION_INTERACTION_LIMITS
 } from "@agen-ai/agent-runtime";
@@ -134,12 +133,12 @@ async function createAcpProviderInstance(input) {
   const open = async (context, resume) => {
     throwIfAgentOperationAborted(context.signal);
     throwIfAgentOperationAborted(lifetime.signal);
-    if (input.sessionInteractions && resume) throw new AgentProviderContractError(
+    if (input.sessionInteractions?.mapping === "grok-folder-trust-v1" && resume) throw new AgentProviderContractError(
       input.providerKey,
       "session_interactions_unsupported",
       "The selected ACP session interaction mapping supports creation only."
     );
-    if (input.sessionInteractions && context.interactions === void 0) throw new AgentProviderContractError(
+    if (input.sessionInteractions && (input.sessionInteractions.mapping === "grok-folder-trust-v1" || resume) && context.interactions === void 0) throw new AgentProviderContractError(
       input.providerKey,
       "invalid_session_interaction",
       "The selected ACP session interaction mapping requires a handler before opening."
@@ -201,7 +200,7 @@ async function createAcpProviderInstance(input) {
           openingInput: context,
           ...parsed.operation === "resume" ? { resume: {
             binding: parsed.binding,
-            method: sessionCapabilities?.resume != null ? "session/resume" : "session/load"
+            method: input.sessionInteractions?.mapping === "grok-build-1.0.60-session-requests-v1" ? "session/load" : sessionCapabilities?.resume != null ? "session/resume" : "session/load"
           } } : {},
           mcpServers,
           connection,
@@ -216,7 +215,7 @@ async function createAcpProviderInstance(input) {
           closeResources
         });
         throwIfAgentOperationAborted(signal);
-        connection.sessionInteractions?.adopt();
+        if (context.interactions) connection.sessionInteractions?.adopt();
         sessions.set(parsed.sessionId, opened.session);
         return opened.session;
       } catch (cause) {
@@ -254,10 +253,21 @@ async function createAcpProviderInstance(input) {
   const adapter = Object.freeze({
     ...input.sessionInteractions ? { sessionInteractions: Object.freeze({
       kind: "supported",
-      openingOperations: Object.freeze(["create"]),
-      requestKinds: Object.freeze(["decision"]),
-      producerOwnership: "exclusive"
+      mappings: input.sessionInteractions.mapping === "grok-folder-trust-v1" ? Object.freeze([Object.freeze({ openingOperation: "create", requestKind: "decision" })]) : Object.freeze([Object.freeze({ openingOperation: "resume", requestKind: "plan_review" })]),
+      producerOwnership: "exclusive",
+      humanWait: Object.freeze(["bounded", "until_withdrawn_or_closed"])
     }) } : {},
+    ...input.sessionInteractions?.mapping === "grok-build-1.0.60-session-requests-v1" ? {
+      nativeContinuations: Object.freeze({
+        kind: "supported",
+        producerOwnership: "exclusive",
+        mappings: Object.freeze([Object.freeze({
+          openingOperation: "resume",
+          requestKind: "plan_review",
+          timing: "after_open_return"
+        })])
+      })
+    } : {},
     hostBinding: bindingSupported ? Object.freeze({ kind: "supported", toolTransport: "mcp", instructionPlacements: Object.freeze(["tool_context"]) }) : Object.freeze({ kind: "unsupported" }),
     createSession: (context) => open(context, false),
     resumption: capabilities.sessions.resume ? Object.freeze({ kind: "supported", resumeSession: (context) => open(context, true) }) : Object.freeze({ kind: "unsupported" }),
@@ -267,7 +277,7 @@ async function createAcpProviderInstance(input) {
   return Object.freeze({
     instanceId: input.instanceId,
     capabilities,
-    adapter: input.sessionInteractions ? validateAgentProviderAdapter(capabilities, adapter) : adapter,
+    adapter,
     accountQuota: { kind: "unsupported" },
     environment: { kind: "unsupported" },
     checkReadiness(check = {}) {

package/dist/node/contracts.d.ts

@@ -12,9 +12,9 @@ export interface NodeAcpLaunchOptions {
 export interface CreateNodeAcpProviderDriverOptions extends Omit<CreateAcpProviderDriverOptions, 'createConnection' | 'limits'> {
     readonly launch: NodeAcpLaunchOptions;
     readonly executionBoundary?: NodeAcpExecutionBoundary;
-    /** Requires a genuine direct native executable, exact no-leader arguments and a handler for every created session. */
+    /** Requires a direct native executable, exact no-leader arguments and a handler for each selected opening tuple. */
     readonly sessionInteractions?: Readonly<{
-        readonly mapping: 'grok-folder-trust-v1';
+        readonly mapping: 'grok-folder-trust-v1' | 'grok-build-1.0.60-session-requests-v1';
     }>;
     readonly limits?: Partial<AcpProviderLimits>;
 }

package/dist/node/index.js

@@ -9,7 +9,7 @@ function createNodeAcpProviderDriver(options) {
   if (boundary === void 0 && Object.hasOwn(options, "executionBoundary")) throw new TypeError("An explicitly supplied execution boundary must be valid.");
   const reserve = boundary === void 0 ? void 0 : executionReservationSource(boundary, launch);
   const sessionInteractions = resolveNodeAcpSessionInteractions(options, launch);
-  if (sessionInteractions && !reserve) throw new TypeError("The Grok folder-trust mapping requires an exclusive descendant-owning execution boundary.");
+  if (sessionInteractions && !reserve) throw new TypeError("Selected Grok session mappings require an exclusive descendant-owning execution boundary.");
   return createAcpProviderDriverInternal({
     providerKey: options.providerKey,
     connectionSource: reserve ? { kind: "reserved", reserve } : { kind: "factory", create: (context) => spawnAcpProcess(launch, context) },

package/dist/node/launch.js

@@ -34,13 +34,13 @@ function resolveNodeAcpLaunch(launch) {
 function resolveNodeAcpSessionInteractions(options, launch) {
   const selection = options.sessionInteractions;
   if (selection === void 0 && !Object.hasOwn(options, "sessionInteractions")) return void 0;
-  if (!selection || typeof selection !== "object" || Array.isArray(selection) || Reflect.ownKeys(selection).length !== 1 || !Object.hasOwn(selection, "mapping") || selection.mapping !== "grok-folder-trust-v1") {
+  if (!selection || typeof selection !== "object" || Array.isArray(selection) || Reflect.ownKeys(selection).length !== 1 || !Object.hasOwn(selection, "mapping") || !["grok-folder-trust-v1", "grok-build-1.0.60-session-requests-v1"].includes(selection.mapping)) {
     throw new TypeError("ACP session interaction selection must name the supported mapping without additional fields.");
   }
   if (launch.args.length !== 3 || launch.args[0] !== "agent" || launch.args[1] !== "--no-leader" || launch.args[2] !== "stdio") {
-    throw new TypeError("The Grok folder-trust mapping requires exact direct arguments: agent --no-leader stdio.");
+    throw new TypeError("Selected Grok session mappings require exact direct arguments: agent --no-leader stdio.");
   }
-  return Object.freeze({ mapping: "grok-folder-trust-v1" });
+  return Object.freeze({ mapping: selection.mapping });
 }
 export {
   resolveNodeAcpLaunch,

package/dist/session/continuation.d.ts

@@ -0,0 +1,33 @@
+import type { AcpJsonObject, AcpNotificationContext } from '@agen-ai/acp-transport';
+import type { AgentTurnCompletedPayload, AgentTurnId } from '@agen-ai/agent-protocol';
+import { type AgentProviderOutput, type AgentProviderTurnExecution } from '@agen-ai/agent-runtime';
+import type { PreparePlanContinuation } from '../sessionInteractions/request.js';
+import { type SessionQueue } from './queue.js';
+import type { NativeTurn, SessionMessage } from './turn.js';
+/** The selected restored-plan continuation shares the session's turn and output owners. */
+export declare class GrokPlanContinuations {
+    private readonly input;
+    private readonly historicalPrompts;
+    private readonly completedPrompts;
+    private continuation;
+    constructor(input: Readonly<{
+        queue: SessionQueue<SessionMessage>;
+        selected: boolean;
+        requireUsable: () => void;
+        assertNativeSession: (params: AcpJsonObject) => void;
+        createNativeTurn: (turnId: AgentTurnId) => NativeTurn;
+        execution: (turn: NativeTurn, stream: () => AsyncGenerator<AgentProviderOutput>) => AgentProviderTurnExecution;
+        stream: (turn: NativeTurn, ready: Promise<boolean>) => AsyncGenerator<AgentProviderOutput>;
+        completeNativeTurn: (turn: NativeTurn, payload: AgentTurnCompletedPayload) => void;
+        close: () => Promise<void>;
+    }>);
+    private replayed;
+    private promptIds;
+    private rememberPrompts;
+    admitOutput(params: AcpJsonObject, update: AcpJsonObject, historical: boolean): boolean;
+    admitNotification(context: AcpNotificationContext): void;
+    prepareResponse(input: Parameters<PreparePlanContinuation>[0]): ReturnType<PreparePlanContinuation>;
+    complete(turn: NativeTurn): void;
+    stop(error: Error): void;
+}
+//# sourceMappingURL=continuation.d.ts.map

package/dist/session/continuation.js

@@ -0,0 +1,185 @@
+import {
+  throwIfAgentOperationAborted
+} from "@agen-ai/agent-runtime";
+import { GROK_QUEUE_METHOD } from "../sessionInteractions/grokPlanReview.js";
+import { AcpProviderSessionError } from "./errors.js";
+import { acpTurnCompletion } from "./completion.js";
+import { nativeObject, nativeString, SESSION_METADATA_UPDATES } from "./native.js";
+import { deferred } from "./queue.js";
+class GrokPlanContinuations {
+  constructor(input) {
+    this.input = input;
+  }
+  historicalPrompts = /* @__PURE__ */ new Map();
+  completedPrompts = /* @__PURE__ */ new Set();
+  continuation;
+  replayed(meta) {
+    if (meta?.isReplay !== void 0 && typeof meta.isReplay !== "boolean") throw new AcpProviderSessionError(
+      "acp_continuation_replay_invalid",
+      "The selected native replay marker must be a boolean."
+    );
+    return meta?.isReplay === true;
+  }
+  promptIds(values) {
+    return values.flatMap((value) => {
+      if (value === void 0 || value === null) return [];
+      const id = nativeString(value, "prompt identity");
+      if (!id || Buffer.byteLength(id, "utf8") > 256) throw new AcpProviderSessionError(
+        "acp_continuation_identity_invalid",
+        "Native prompt identity exceeds its bound."
+      );
+      return [id];
+    });
+  }
+  rememberPrompts(ids) {
+    for (const id of ids) if (!this.historicalPrompts.has(id)) this.historicalPrompts.set(id, this.input.queue.reserveState(id));
+  }
+  admitOutput(params, update, historical) {
+    if (!this.input.selected) return true;
+    const meta = params._meta === void 0 ? void 0 : nativeObject(params._meta, "continuation metadata");
+    const replay = this.replayed(meta);
+    const ids = this.promptIds([meta?.promptId, update.prompt_id]);
+    if (historical || replay || !this.continuation?.state.dispatched) this.rememberPrompts(ids);
+    if (historical || replay) return false;
+    if (SESSION_METADATA_UPDATES.has(nativeString(update.sessionUpdate, "session update kind"))) return true;
+    if (this.continuation && !this.continuation.turn.terminal) {
+      if (!this.continuation.state.promptId || meta?.promptId !== this.continuation.state.promptId) {
+        throw new AcpProviderSessionError("acp_continuation_output_mismatch", "Native continuation output requires its exact promoted prompt identity.");
+      }
+      this.continuation.state.outputObserved = true;
+    }
+    return true;
+  }
+  admitNotification(context) {
+    this.input.requireUsable();
+    const params = nativeObject(context.params, "continuation notification");
+    this.input.assertNativeSession(params);
+    const meta = params._meta === void 0 ? void 0 : nativeObject(params._meta, "continuation metadata");
+    const replay = this.replayed(meta);
+    const update = context.method === GROK_QUEUE_METHOD ? void 0 : nativeObject(params.update, "native session update");
+    const ids = this.promptIds([meta?.promptId, update?.prompt_id, ...context.method === GROK_QUEUE_METHOD ? [params.runningPromptId, ...Array.isArray(params.entries) ? params.entries.map((entry) => nativeObject(entry, "queue entry").id) : []] : []]);
+    if (replay || !this.continuation?.state.dispatched) this.rememberPrompts(ids);
+    if (replay) return;
+    if (context.method === GROK_QUEUE_METHOD) {
+      const continuation2 = this.continuation;
+      if (!continuation2?.state.dispatched || params.runningPromptId == null) return;
+      const id = nativeString(params.runningPromptId, "promoted prompt identity");
+      if (params.runningKind !== "prompt" || !id.startsWith("plan-resume-") || this.historicalPrompts.has(id) && continuation2.state.promptId !== id || meta?.promptId != null && meta.promptId !== id || ids.some((value) => value !== id && !this.historicalPrompts.has(value)) || continuation2.state.promptId !== void 0 && continuation2.state.promptId !== id) {
+        throw new AcpProviderSessionError("acp_continuation_promotion_invalid", "The native continuation promotion does not identify its fresh owned prompt.");
+      }
+      if (!continuation2.state.promptId) {
+        continuation2.state.promptId = id;
+        continuation2.turn.nativeStarted = true;
+        continuation2.outcome.resolve(Object.freeze({ kind: "started" }));
+        continuation2.ready.resolve(true);
+      }
+      return;
+    }
+    if (update?.sessionUpdate !== "turn_completed") return;
+    const continuation = this.continuation;
+    if (!continuation?.state.dispatched) {
+      if (typeof update.prompt_id === "string" && this.completedPrompts.has(update.prompt_id)) throw new AcpProviderSessionError(
+        "acp_continuation_terminal_invalid",
+        "The native continuation repeated an already completed terminal."
+      );
+      return;
+    }
+    if (update.prompt_id !== continuation.state.promptId) {
+      if (typeof update.prompt_id === "string" && this.historicalPrompts.has(update.prompt_id)) return;
+      throw new AcpProviderSessionError("acp_continuation_terminal_mismatch", "The terminal does not identify the owned promoted prompt.");
+    }
+    if (!continuation.state.promptId || continuation.turn.nativeSettled || update.stop_reason !== "end_turn" && update.stop_reason !== "cancelled" || update.stop_reason === "end_turn" && !continuation.state.outputObserved || update.error != null || params.error != null) throw new AcpProviderSessionError(
+      "acp_continuation_terminal_invalid",
+      "The native continuation did not produce its exact terminal."
+    );
+    this.input.completeNativeTurn(continuation.turn, acpTurnCompletion({
+      kind: "result",
+      result: { stopReason: update.stop_reason }
+    }, continuation.turn.cancelReason));
+  }
+  prepareResponse(input) {
+    this.input.requireUsable();
+    throwIfAgentOperationAborted(input.signal);
+    let canceled = false;
+    let dispatched = false;
+    let owned;
+    const outcome = deferred();
+    const ready = deferred();
+    void outcome.promise.catch(() => {
+    });
+    void ready.promise.catch(() => {
+    });
+    const cancel = async () => {
+      if (canceled) return;
+      canceled = true;
+      if (dispatched) {
+        await this.input.close();
+        return;
+      }
+      outcome.resolve(Object.freeze({ kind: "not_started" }));
+      ready.resolve(false);
+      if (owned) {
+        owned.turn.terminal = true;
+        owned.turn.sourceSettled = true;
+        owned.turn.mapping.release();
+        owned.outcome.resolve(Object.freeze({ kind: "not_started" }));
+        owned.ready.resolve(false);
+        this.input.queue.wakeReader();
+        if (this.continuation === owned) this.continuation = void 0;
+      }
+    };
+    const dispatch = async () => {
+      throwIfAgentOperationAborted(input.signal);
+      if (canceled || dispatched) throw new AcpProviderSessionError("acp_continuation_dispatch_invalid", "A prepared response can enter only once.");
+      if (input.response.action !== "abandon" && !owned) throw new AcpProviderSessionError("acp_continuation_owner_missing", "The native continuation requires its prepared reader.");
+      dispatched = true;
+      if (owned) owned.state.dispatched = true;
+      const result = await input.dispatch();
+      if (result.status !== "delivered" && owned) {
+        owned.turn.terminal = true;
+        owned.turn.mapping.release();
+        owned.outcome.resolve(Object.freeze({ kind: "not_started" }));
+        owned.ready.resolve(false);
+      }
+      return result;
+    };
+    if (input.response.action === "abandon") return Object.freeze({ kind: "no_continuation", dispatch, cancel });
+    return Object.freeze({
+      kind: "native_continuation",
+      outcome: outcome.promise,
+      dispatch,
+      cancel,
+      createExecution: ({ turnId, signal }) => {
+        if (owned || canceled || dispatched) throw new AcpProviderSessionError("acp_continuation_owner_invalid", "The prepared execution can be acquired only once.");
+        throwIfAgentOperationAborted(signal);
+        const turn = this.input.createNativeTurn(turnId);
+        owned = { turn, outcome, ready, state: { dispatched: false, outputObserved: false } };
+        this.continuation = owned;
+        const owner = this.input;
+        return owner.execution(turn, async function* () {
+          yield* owner.stream(turn, ready.promise);
+          if (dispatched) await input.nativeSettled;
+        });
+      }
+    });
+  }
+  complete(turn) {
+    if (this.continuation?.turn !== turn) return;
+    const promptId = this.continuation.state.promptId;
+    if (promptId !== void 0) {
+      this.rememberPrompts([promptId]);
+      this.completedPrompts.add(promptId);
+    }
+    this.continuation = void 0;
+  }
+  stop(error) {
+    this.continuation?.ready.reject(error);
+    this.continuation?.outcome.reject(error);
+    for (const release of this.historicalPrompts.values()) release();
+    this.historicalPrompts.clear();
+    this.completedPrompts.clear();
+  }
+}
+export {
+  GrokPlanContinuations
+};

package/dist/session/descendants.d.ts

@@ -0,0 +1,29 @@
+import type { AcpJsonObject, AcpNotificationContext } from '@agen-ai/acp-transport';
+import type { SessionQueue } from './queue.js';
+import type { GrokChildPermissionWithdrawals } from './requests/grokWithdrawals.js';
+export interface DescendantIdentity {
+    readonly parentSessionId: string;
+    readonly childSessionId: string;
+    readonly subagentId: string;
+    readonly attemptId?: string;
+    readonly parentPromptId?: string;
+}
+/** Selected native descendants are bounded observations, with no parent output or host authority. */
+export declare class GrokDescendantObservations {
+    private readonly input;
+    private readonly bySession;
+    private readonly bySubagent;
+    constructor(input: Readonly<{
+        reserveState: SessionQueue<unknown>['reserveState'];
+        rootSessionId: () => string | undefined;
+        activeTurn: () => boolean;
+        observeHistory: (params: AcpJsonObject) => void;
+        withdrawals: GrokChildPermissionWithdrawals;
+    }>);
+    /** Returns true only when this notification is wholly owned by the observation scope. */
+    admit(context: AcpNotificationContext, historical: boolean): boolean;
+    private spawn;
+    private validateQueue;
+    stop(): void;
+}
+//# sourceMappingURL=descendants.d.ts.map

package/dist/session/descendants.js

@@ -0,0 +1,97 @@
+import { GROK_QUEUE_METHOD, GROK_SESSION_NOTIFICATION_METHOD } from "../sessionInteractions/grokPlanReview.js";
+import { AcpProviderSessionError } from "./errors.js";
+import { nativeIdentity, nativeObject, nativeString } from "./native.js";
+class GrokDescendantObservations {
+  constructor(input) {
+    this.input = input;
+  }
+  bySession = /* @__PURE__ */ new Map();
+  bySubagent = /* @__PURE__ */ new Map();
+  /** Returns true only when this notification is wholly owned by the observation scope. */
+  admit(context, historical) {
+    const params = nativeObject(context.params, "descendant notification");
+    const meta = params._meta === void 0 ? void 0 : nativeObject(params._meta, "descendant metadata");
+    if (meta?.isReplay !== void 0 && typeof meta.isReplay !== "boolean") throw new AcpProviderSessionError(
+      "acp_descendant_replay_invalid",
+      "The selected native replay marker must be a boolean."
+    );
+    const replay = historical || meta?.isReplay === true;
+    const root = this.input.rootSessionId();
+    if (params.sessionId === root && root !== void 0) {
+      if (context.method !== GROK_SESSION_NOTIFICATION_METHOD) return false;
+      const update = nativeObject(params.update, "descendant session update");
+      if (update.sessionUpdate === "subagent_spawned") this.spawn(update, root, replay);
+      else if (update.sessionUpdate === "subagent_finished") {
+        const child = this.bySession.get(nativeIdentity(update.child_session_id, "finished child session identity"));
+        if (child?.origin === "live" && !replay) this.input.withdrawals.finish(child.identity, update);
+      } else return false;
+      this.input.observeHistory(params);
+      return true;
+    }
+    if (root === void 0) return false;
+    const sessionId = nativeIdentity(params.sessionId, "child session identity");
+    const observation = this.bySession.get(sessionId);
+    if (!observation || observation.origin === "historical" && !replay) return false;
+    if (context.method === GROK_QUEUE_METHOD) {
+      this.validateQueue(params);
+    } else {
+      const update = nativeObject(params.update, "child session update");
+      const kind = nativeString(update.sessionUpdate, "child session update kind");
+      if (kind === "subagent_spawned") throw new AcpProviderSessionError(
+        "acp_descendant_nested_unsupported",
+        "The selected native mapping does not admit nested descendant relationships."
+      );
+      if (context.method === GROK_SESSION_NOTIFICATION_METHOD && !replay) this.input.withdrawals.observe(observation.identity, update);
+    }
+    this.input.observeHistory(params);
+    return true;
+  }
+  spawn(update, root, historical) {
+    const value = Object.freeze({
+      parentSessionId: nativeIdentity(update.parent_session_id, "parent session identity"),
+      childSessionId: nativeIdentity(update.child_session_id, "child session identity"),
+      subagentId: nativeIdentity(update.subagent_id, "subagent identity"),
+      ...update.attempt_id === void 0 ? {} : { attemptId: nativeIdentity(update.attempt_id, "attempt identity") },
+      ...update.parent_prompt_id === void 0 ? {} : { parentPromptId: nativeIdentity(update.parent_prompt_id, "parent prompt identity") }
+    });
+    if (value.parentSessionId !== root || value.childSessionId === root || value.subagentId === root) throw new AcpProviderSessionError(
+      "acp_descendant_identity_invalid",
+      "The selected native spawn does not identify a direct child of the bound root."
+    );
+    const prior = this.bySession.get(value.childSessionId) ?? this.bySubagent.get(value.subagentId);
+    if (prior) {
+      if (JSON.stringify(prior.identity) !== JSON.stringify(value) || prior.origin === "historical" && !historical) throw new AcpProviderSessionError(
+        "acp_descendant_identity_conflict",
+        "The selected native descendant identity cannot be rebound or revived."
+      );
+      return;
+    }
+    if (!historical && !this.input.activeTurn()) throw new AcpProviderSessionError(
+      "acp_descendant_without_prompt",
+      "A live native descendant requires active owned parent work."
+    );
+    const observation = {
+      identity: value,
+      origin: historical ? "historical" : "live",
+      release: this.input.reserveState(value)
+    };
+    this.bySession.set(value.childSessionId, observation);
+    this.bySubagent.set(value.subagentId, observation);
+  }
+  validateQueue(params) {
+    if (!Array.isArray(params.entries) || params.entries.length > 256) throw new AcpProviderSessionError(
+      "acp_descendant_queue_invalid",
+      "The selected native child queue is invalid."
+    );
+    for (const entry of params.entries) nativeIdentity(nativeObject(entry, "child queue entry").id, "child queue prompt identity");
+    if (params.runningPromptId != null) nativeIdentity(params.runningPromptId, "running child prompt identity");
+  }
+  stop() {
+    for (const observation of this.bySession.values()) observation.release();
+    this.bySession.clear();
+    this.bySubagent.clear();
+  }
+}
+export {
+  GrokDescendantObservations
+};

package/dist/session/mapping.js

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

package/dist/session/native.d.ts

@@ -1,6 +1,7 @@
 import type { AcpJsonObject, AcpJsonValue } from '@agen-ai/acp-transport';
 export declare function nativeObject(value: AcpJsonValue | undefined, field: string): AcpJsonObject;
 export declare function nativeString(value: AcpJsonValue | undefined, field: string): string;
+export declare function nativeIdentity(value: unknown, field: string): string;
 export declare function displayText(value: AcpJsonValue | undefined, fallback: string, limit?: number): string;
 export declare function nativeBytes(value: unknown): number;
 export declare const SESSION_METADATA_UPDATES: Set<string>;

package/dist/session/native.js

@@ -11,6 +11,13 @@ function nativeString(value, field) {
   }
   return value;
 }
+function nativeIdentity(value, field) {
+  if (typeof value !== "string" || !value || value !== value.trim() || Buffer.byteLength(value, "utf8") > 256 || /[\p{Cc}\p{Cf}]/u.test(value)) throw new AcpProviderSessionError(
+    "acp_descendant_identity_invalid",
+    `The selected native ${field} is invalid.`
+  );
+  return value;
+}
 function displayText(value, fallback, limit = 120) {
   const text = typeof value === "string" ? value.trim() : "";
   return (text || fallback).slice(0, limit).trimEnd();
@@ -29,6 +36,7 @@ export {
   SESSION_METADATA_UPDATES,
   displayText,
   nativeBytes,
+  nativeIdentity,
   nativeObject,
   nativeString
 };

package/dist/session/opening.js

@@ -34,7 +34,7 @@ async function openAcpNativeSession(input, hooks) {
   const client = acpSessionControlClient(input);
   const operations = createAcpStandardSessionOperations(client);
   const resumed = input.resume;
-  const sessionInteractions = input.connection.sessionInteractions;
+  const sessionInteractions = input.context.interactions ? input.connection.sessionInteractions : void 0;
   if (resumed) {
     hooks.bind(resumed.binding);
     hooks.replay.active = resumed.method === "session/load";

package/dist/session/requests/elicitation.d.ts

@@ -9,6 +9,6 @@ export declare function prepareAcpSessionElicitation(input: {
     readonly host: AcpInitializedConnection['hostElicitation'];
 }): Readonly<{
     form?: PreparedAcpForm;
-    host?: () => Promise<AcpJsonValue>;
+    host?: (observeCallback: (work: Promise<void>) => void) => Promise<AcpJsonValue>;
 }>;
 //# sourceMappingURL=elicitation.d.ts.map

package/dist/session/requests/elicitation.js

@@ -14,7 +14,7 @@ function prepareAcpSessionElicitation(input) {
     const invoke = input.host;
     if (!invoke) throw new Error("This ACP elicitation requires an explicitly configured host UI.");
     const signal = AbortSignal.any([input.context.signal, input.lifetime]);
-    return { host: () => invoke({ ...input.context, signal }) };
+    return { host: (observeCallback) => invoke({ ...input.context, signal }, observeCallback) };
   } catch (error) {
     throw new AcpRpcHandlerError(-32602, error instanceof Error ? error.message : "Unsupported ACP form.");
   }

package/dist/session/requests/grokWithdrawals.d.ts

@@ -0,0 +1,28 @@
+import type { AcpJsonObject } from '@agen-ai/acp-transport';
+import type { DescendantIdentity } from '../descendants.js';
+import { type SessionQueue } from '../queue.js';
+import type { NativeTurn } from '../turn.js';
+import type { PendingSessionRequest } from './pending.js';
+/** Only the observed ordered child/tool callback and exact canceled attempt can withdraw a permission. */
+export declare class GrokChildPermissionWithdrawals {
+    private readonly input;
+    private readonly children;
+    private readonly requests;
+    constructor(input: Readonly<{
+        reserveState: SessionQueue<unknown>['reserveState'];
+        currentTurn: () => NativeTurn | undefined;
+        timeoutMs: number;
+        withdraw: (request: PendingSessionRequest) => void;
+        fail: (error: Error) => void;
+    }>);
+    observe(identity: DescendantIdentity, update: AcpJsonObject): void;
+    attach(request: PendingSessionRequest): void;
+    finish(identity: DescendantIdentity, update: AcpJsonObject): void;
+    answerGate(request: PendingSessionRequest): Promise<void> | undefined;
+    settle(request: PendingSessionRequest): void;
+    private child;
+    private retire;
+    private stale;
+    stop(error: Error): void;
+}
+//# sourceMappingURL=grokWithdrawals.d.ts.map