@agen-ai/provider-acp 0.4.0 → 0.4.2

package/dist/node/execution/types.d.ts

@@ -0,0 +1,20 @@
+import type { MaybePromise } from '@agen-ai/agent-runtime';
+import type { AcpConnectionFactoryContext, AcpConnectionStreams } from '../../contracts.js';
+export interface NodeAcpExecutionInput {
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly shutdownTimeoutMs: number;
+}
+/** Reserve fresh inert state; resource acquisition and execution belong to start. */
+export interface NodeAcpExecutionBoundary {
+    readonly reserve: (input: NodeAcpExecutionInput) => NodeAcpExecutionReservation;
+}
+/** Own the workload before execution, including descendants in other groups or sessions. */
+export interface NodeAcpExecutionReservation {
+    readonly start: (context: AcpConnectionFactoryContext) => MaybePromise<AcpConnectionStreams>;
+    /** Fence startup, terminate and join the workload and streams; failed release remains retryable. */
+    readonly release: () => MaybePromise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/node/index.d.ts

@@ -1,6 +1,8 @@
 import type { AgentProviderDriver } from '@agen-ai/agent-runtime';
 import type { CreateNodeAcpProviderDriverOptions } from './contracts.js';
 export type { NodeAcpLaunchOptions, CreateNodeAcpProviderDriverOptions } from './contracts.js';
-/** Launches an owned POSIX process group. Windows hosts must supply an owned connection factory. */
+export type { NodeAcpExecutionInput, NodeAcpExecutionBoundary, NodeAcpExecutionReservation } from './execution/types.js';
+export { NodeAcpExecutionCleanupError, isNodeAcpExecutionCleanupError } from './execution/errors.js';
+/** Uses the supplied inert execution owner, or the default owned POSIX process-group launcher. */
 export declare function createNodeAcpProviderDriver(options: CreateNodeAcpProviderDriverOptions): AgentProviderDriver;
 //# sourceMappingURL=index.d.ts.map

package/dist/node/index.js

@@ -1,20 +1,30 @@
-import { createAcpProviderDriver } from "../driver.js";
-import { resolveNodeAcpLaunch } from "./launch.js";
+import { createAcpProviderDriverInternal } from "../driverFactory.js";
+import { resolveNodeAcpLaunch, resolveNodeAcpSessionInteractions } from "./launch.js";
 import { spawnAcpProcess } from "./process.js";
+import { executionReservationSource } from "./execution/owner.js";
+import { NodeAcpExecutionCleanupError, isNodeAcpExecutionCleanupError } from "./execution/errors.js";
 function createNodeAcpProviderDriver(options) {
   const launch = resolveNodeAcpLaunch(options.launch);
-  return createAcpProviderDriver({
+  const boundary = options.executionBoundary;
+  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("Selected Grok session mappings require an exclusive descendant-owning execution boundary.");
+  return createAcpProviderDriverInternal({
     providerKey: options.providerKey,
-    createConnection: (context) => spawnAcpProcess(launch, context),
+    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.limits ? { limits: options.limits } : {},
     ...options.configuration ? { configuration: options.configuration } : {},
     ...options.authentication ? { authentication: options.authentication } : {},
     ...options.host ? { host: options.host } : {},
     ...options.mcpServers ? { mcpServers: options.mcpServers } : {},
     ...options.sessionMcpBinding ? { sessionMcpBinding: options.sessionMcpBinding } : {}
-  });
+  }, sessionInteractions);
 }
 export {
-  createNodeAcpProviderDriver
+  NodeAcpExecutionCleanupError,
+  createNodeAcpProviderDriver,
+  isNodeAcpExecutionCleanupError
 };

package/dist/node/launch.d.ts

@@ -1,10 +1,7 @@
-import type { NodeAcpLaunchOptions } from './contracts.js';
-export interface ResolvedNodeAcpLaunch {
-    readonly executable: string;
-    readonly args: readonly string[];
-    readonly cwd: string;
-    readonly env: Readonly<Record<string, string>>;
-    readonly shutdownTimeoutMs: number;
-}
+import type { CreateNodeAcpProviderDriverOptions, NodeAcpLaunchOptions } from './contracts.js';
+import type { AcpSessionInteractionSelection } from '../sessionInteractions/contracts.js';
+import type { NodeAcpExecutionInput } from './execution/types.js';
+export type ResolvedNodeAcpLaunch = NodeAcpExecutionInput;
 export declare function resolveNodeAcpLaunch(launch: NodeAcpLaunchOptions): ResolvedNodeAcpLaunch;
+export declare function resolveNodeAcpSessionInteractions(options: CreateNodeAcpProviderDriverOptions, launch: ResolvedNodeAcpLaunch): AcpSessionInteractionSelection | undefined;
 //# sourceMappingURL=launch.d.ts.map

package/dist/node/launch.js

@@ -31,6 +31,18 @@ function resolveNodeAcpLaunch(launch) {
     shutdownTimeoutMs
   });
 }
+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") || !["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("Selected Grok session mappings require exact direct arguments: agent --no-leader stdio.");
+  }
+  return Object.freeze({ mapping: selection.mapping });
+}
 export {
-  resolveNodeAcpLaunch
+  resolveNodeAcpLaunch,
+  resolveNodeAcpSessionInteractions
 };

package/dist/permissions/contracts.d.ts

@@ -0,0 +1,22 @@
+export interface AcpPermissionOptionSignature {
+    readonly optionId: string;
+    readonly kind: 'allow_once' | 'reject_once' | 'allow_always' | 'reject_always';
+}
+export interface AcpPermissionMenuSignature {
+    readonly toolKind: 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'switch_mode' | 'other';
+    readonly options: readonly [AcpPermissionOptionSignature, ...AcpPermissionOptionSignature[]];
+}
+/** Complete declarations attest that these exact menus add no unrepresented choice effects. */
+export type AcpPermissionMappingSelection = Readonly<{
+    mapping: 'once-only-v1';
+}> | Readonly<{
+    mapping: 'grok-build-1.0.50-edit-remembrance-v1';
+}> | Readonly<{
+    mapping: 'declared-complete-consequences-v1';
+    agentInfo: Readonly<{
+        name: string;
+        version: string;
+    }>;
+    menus: readonly [AcpPermissionMenuSignature, ...AcpPermissionMenuSignature[]];
+}>;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/permissions/mapping.d.ts

@@ -0,0 +1,13 @@
+import type { AcpJsonObject } from '@agen-ai/acp-transport';
+import { type AgentApprovalOption } from '@agen-ai/agent-protocol';
+import type { AcpPermissionMappingSelection } from './contracts.js';
+export interface MappedPermissionOptions {
+    readonly options: readonly AgentApprovalOption[];
+    readonly nativeOptions: ReadonlyMap<string, string>;
+    readonly warning?: Readonly<{
+        code: string;
+        message: string;
+    }>;
+}
+export declare function mapAcpPermissionOptions(selection: AcpPermissionMappingSelection, params: AcpJsonObject): MappedPermissionOptions;
+//# sourceMappingURL=mapping.d.ts.map

package/dist/permissions/mapping.js

@@ -0,0 +1,99 @@
+import { parseAgentApprovalOptionId } from "@agen-ai/agent-protocol";
+import { AcpProviderSessionError } from "../session/errors.js";
+import { displayText, nativeObject, nativeString } from "../session/native.js";
+const GROK_EDIT_MENU = {
+  toolKind: "edit",
+  options: [
+    { optionId: "allow-edits-session", kind: "allow_always" },
+    { optionId: "allow-once", kind: "allow_once" },
+    { optionId: "reject-once", kind: "reject_once" }
+  ]
+};
+function unsupportedConsequence() {
+  throw new AcpProviderSessionError("acp_permission_consequence_unsupported", "The selected ACP permission mapping does not represent this complete native menu.");
+}
+function readNativeOptions(params) {
+  if (!Array.isArray(params.options) || params.options.length < 1 || params.options.length > 16) {
+    throw new AcpProviderSessionError("acp_permission_options_invalid", "ACP permission menus require between one and sixteen options.");
+  }
+  const ids = /* @__PURE__ */ new Set();
+  return params.options.map((value) => {
+    const option = nativeObject(value, "permission option");
+    const optionId = nativeString(option.optionId, "permission option identity");
+    if (!optionId || optionId.length > 256 || optionId !== optionId.trim() || /[\u0000-\u001f\u007f-\u009f]/u.test(optionId)) {
+      throw new AcpProviderSessionError("acp_permission_options_invalid", "ACP permission option identities must be bounded canonical strings.");
+    }
+    if (ids.has(optionId)) throw new AcpProviderSessionError("acp_permission_option_duplicate", "ACP repeated a permission option identity.");
+    ids.add(optionId);
+    const kind = option.kind;
+    if (kind !== "allow_once" && kind !== "reject_once" && kind !== "allow_always" && kind !== "reject_always") {
+      throw new AcpProviderSessionError("acp_permission_options_invalid", "ACP permission option kind is unsupported.");
+    }
+    return { optionId, kind, source: option };
+  });
+}
+function matchesMenu(menu, tool, options) {
+  return menu.toolKind === tool.kind && menu.options.length === options.length && menu.options.every((option, index) => option.optionId === options[index]?.optionId && option.kind === options[index]?.kind);
+}
+function assertCompleteChoiceFields(params, options) {
+  if (Object.keys(params).some((key) => !["sessionId", "toolCall", "options"].includes(key)) || options.some((option) => Object.keys(option.source).some((key) => !["optionId", "name", "kind"].includes(key)))) {
+    unsupportedConsequence();
+  }
+}
+function qualifiedGrokEdit(tool, options) {
+  const input = tool.rawInput;
+  if (input === null || typeof input !== "object" || Array.isArray(input)) return false;
+  return matchesMenu(GROK_EDIT_MENU, tool, options) && Object.keys(input).length === 5 && typeof input.file_path === "string" && input.file_path.length > 0 && typeof input.old_string === "string" && typeof input.new_string === "string" && input.variant === "SearchReplace" && input.replace_all === false;
+}
+function mapAcpPermissionOptions(selection, params) {
+  const native = readNativeOptions(params);
+  const tool = nativeObject(params.toolCall, "permission tool");
+  let complete = false;
+  let fallback = false;
+  if (selection.mapping === "declared-complete-consequences-v1") {
+    assertCompleteChoiceFields(params, native);
+    if (!selection.menus.some((menu) => matchesMenu(menu, tool, native))) unsupportedConsequence();
+    complete = true;
+  } else if (selection.mapping === "grok-build-1.0.50-edit-remembrance-v1") {
+    if (tool.kind === "edit") {
+      assertCompleteChoiceFields(params, native);
+      if (!qualifiedGrokEdit(tool, native)) unsupportedConsequence();
+      complete = true;
+    } else fallback = true;
+  }
+  const nativeOptions = /* @__PURE__ */ new Map();
+  const options = [];
+  for (const [index, option] of native.entries()) {
+    const remembered = option.kind === "allow_always" || option.kind === "reject_always";
+    if (remembered && !complete) continue;
+    const approved = option.kind === "allow_once" || option.kind === "allow_always";
+    const optionId = parseAgentApprovalOptionId(`acp:option:${index + 1}`);
+    nativeOptions.set(optionId, option.optionId);
+    options.push({
+      optionId,
+      label: remembered ? approved ? "Allow and remember" : "Deny and remember" : displayText(option.source.name, approved ? "Allow once" : "Reject once"),
+      decision: approved ? "approved" : "denied",
+      consequence: remembered ? {
+        kind: "provider_managed_remembrance",
+        duration: { kind: "unknown" },
+        applicability: { kind: "unknown" },
+        explanation: "The provider is asked to remember this decision. Duration and future matching are unspecified. Delivery does not establish successful persistence or revocation."
+      } : { kind: "scoped", persistence: "once", scope: { kind: "exact_action" } }
+    });
+  }
+  if (options.length === 0) {
+    if (fallback) unsupportedConsequence();
+    throw new AcpProviderSessionError("acp_permission_persistence_unsupported", "ACP offered no supported once-only permission choice.");
+  }
+  return {
+    options,
+    nativeOptions,
+    ...fallback ? { warning: {
+      code: "acp_permission_remembrance_unmapped",
+      message: "The selected ACP profile does not map remembered choices for this action. Only once-only choices are available."
+    } } : {}
+  };
+}
+export {
+  mapAcpPermissionOptions
+};

package/dist/permissions/selection.d.ts

@@ -0,0 +1,5 @@
+import type { AgentApprovalCapability } from '@agen-ai/agent-protocol';
+import type { AcpPermissionMappingSelection } from './contracts.js';
+export declare function resolveAcpPermissionMapping(value: unknown): AcpPermissionMappingSelection;
+export declare function acpPermissionCapability(selection: AcpPermissionMappingSelection): AgentApprovalCapability;
+//# sourceMappingURL=selection.d.ts.map

package/dist/permissions/selection.js

@@ -0,0 +1,96 @@
+function selectionObject(value, keys) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || Reflect.ownKeys(value).some((key) => typeof key !== "string" || !keys.includes(key))) {
+    throw new TypeError("ACP permission mapping selections must contain only their declared fields.");
+  }
+  return value;
+}
+function canonicalText(value, maximum, identity = false) {
+  if (typeof value !== "string" || !value || value !== value.trim() || value.length > maximum || (identity ? /[\p{Cc}\p{Cf}]/u : /[\u0000-\u001f\u007f-\u009f]/u).test(value)) {
+    throw new TypeError("ACP permission mapping identities must be bounded canonical strings.");
+  }
+  return value;
+}
+function optionKind(value) {
+  switch (value) {
+    case "allow_once":
+    case "reject_once":
+    case "allow_always":
+    case "reject_always":
+      return value;
+    default:
+      throw new TypeError("ACP permission option kind is invalid.");
+  }
+}
+function toolKind(value) {
+  switch (value) {
+    case "read":
+    case "edit":
+    case "delete":
+    case "move":
+    case "search":
+    case "execute":
+    case "think":
+    case "fetch":
+    case "switch_mode":
+    case "other":
+      return value;
+    default:
+      throw new TypeError("ACP permission tool kind is invalid.");
+  }
+}
+function boundedNonempty(value, parse) {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 16) {
+    throw new TypeError("ACP permission declarations require between one and sixteen entries.");
+  }
+  const first = parse(value[0]);
+  return Object.freeze([first, ...Array.from(value.slice(1), parse)]);
+}
+function menuSignature(value) {
+  const menu = selectionObject(value, ["toolKind", "options"]);
+  const ids = /* @__PURE__ */ new Set();
+  const options = boundedNonempty(menu.options, (entry) => {
+    const option = selectionObject(entry, ["optionId", "kind"]);
+    const optionId = canonicalText(option.optionId, 256);
+    if (ids.has(optionId)) throw new TypeError("ACP declared permission option identities must be unique.");
+    ids.add(optionId);
+    return Object.freeze({ optionId, kind: optionKind(option.kind) });
+  });
+  return Object.freeze({ toolKind: toolKind(menu.toolKind), options });
+}
+function resolveAcpPermissionMapping(value) {
+  if (value === void 0) return Object.freeze({ mapping: "once-only-v1" });
+  const selection = selectionObject(value, ["mapping", "agentInfo", "menus"]);
+  if (selection.mapping === "once-only-v1" || selection.mapping === "grok-build-1.0.50-edit-remembrance-v1") {
+    selectionObject(value, ["mapping"]);
+    return Object.freeze({ mapping: selection.mapping });
+  }
+  if (selection.mapping !== "declared-complete-consequences-v1") throw new TypeError("ACP permission mapping is invalid.");
+  const info = selectionObject(selection.agentInfo, ["name", "version"]);
+  const agentInfo = Object.freeze({ name: canonicalText(info.name, 256, true), version: canonicalText(info.version, 160, true) });
+  const signatures = /* @__PURE__ */ new Set();
+  const menus = boundedNonempty(selection.menus, (entry) => {
+    const menu = menuSignature(entry);
+    const signature = JSON.stringify(menu);
+    if (signatures.has(signature)) throw new TypeError("ACP declared permission menus must be unique.");
+    signatures.add(signature);
+    return menu;
+  });
+  return Object.freeze({ mapping: selection.mapping, agentInfo, menus });
+}
+function acpPermissionCapability(selection) {
+  const once = { persistence: "once", scopeKinds: ["exact_action"] };
+  if (selection.mapping === "once-only-v1") {
+    return { kind: "supported", modes: [once], providerManagedRemembrance: false };
+  }
+  if (selection.mapping === "grok-build-1.0.50-edit-remembrance-v1") {
+    return { kind: "supported", modes: [once], providerManagedRemembrance: true };
+  }
+  const options = selection.menus.flatMap((menu) => menu.options);
+  const precise = options.some((option) => option.kind === "allow_once" || option.kind === "reject_once");
+  const remembered = options.some((option) => option.kind === "allow_always" || option.kind === "reject_always");
+  return remembered ? { kind: "supported", modes: precise ? [once] : [], providerManagedRemembrance: true } : { kind: "supported", modes: [once], providerManagedRemembrance: false };
+}
+export {
+  acpPermissionCapability,
+  resolveAcpPermissionMapping
+};

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/create.d.ts

@@ -2,6 +2,7 @@ import type { AgentCapabilities, AgentSessionBinding } from '@agen-ai/agent-prot
 import { type AgentProviderCreateSessionInput, type AgentProviderResumeSessionInput, type AgentProviderSession, type AgentProviderSessionContext } from '@agen-ai/agent-runtime';
 import type { AcpInitializedConnection } from '../connection/contracts.js';
 import type { AcpProviderLimits } from '../limits.js';
+import type { AcpPermissionMappingSelection } from '../permissions/contracts.js';
 export interface CreateAcpProviderSessionInput {
     readonly context: AgentProviderCreateSessionInput | AgentProviderResumeSessionInput;
     readonly openingInput: AgentProviderSessionContext;
@@ -13,9 +14,14 @@ export interface CreateAcpProviderSessionInput {
     readonly connection: AcpInitializedConnection;
     readonly capabilities: AgentCapabilities;
     readonly limits: AcpProviderLimits;
+    readonly permissionMapping: AcpPermissionMappingSelection;
     readonly now: () => string;
     readonly onClosed: () => void;
     readonly closeResources: () => Promise<void>;
 }
-export declare function createAcpProviderSession(input: CreateAcpProviderSessionInput): Promise<AgentProviderSession>;
+export interface AcpOpenedProviderSession {
+    readonly session: AgentProviderSession;
+    readonly cleanup: () => Promise<void>;
+}
+export declare function createAcpProviderSession(input: CreateAcpProviderSessionInput): Promise<AcpOpenedProviderSession>;
 //# sourceMappingURL=create.d.ts.map

package/dist/session/create.js

@@ -6,7 +6,9 @@ async function createAcpProviderSession(input) {
   let state;
   try {
     state = new SessionState(input);
-    return await state.open();
+    const session = await state.open();
+    const owner = state;
+    return Object.freeze({ session, cleanup: () => owner.close() });
   } catch (error) {
     const cleanup = () => state ? state.close() : input.closeResources();
     try {

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