@agen-ai/provider-acp 0.0.0-stage → 0.4.0

package/dist/auth/controller.js

@@ -0,0 +1,170 @@
+import {
+  createAgentAuthenticationOutput,
+  throwIfAgentOperationAborted
+} from "@agen-ai/agent-runtime";
+import { AcpProviderConnectionError } from "../connection/errors.js";
+import { awaitHost, hostDeadline } from "../host/lifecycle.js";
+import { AcpHostLeases } from "../host/leases.js";
+import { hostExitStatus } from "../host/validation.js";
+function createAcpAuthentication(input) {
+  let active;
+  const terminals = new AcpHostLeases(input.limits.hostOperationTimeoutMs);
+  const port = input.methods.size === 0 ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    start: (context) => start(context),
+    async cancel(context) {
+      throwIfAgentOperationAborted(context.signal);
+      if (!active || active.id !== context.attemptId || active.terminal || context.providerLoginId !== void 0) {
+        return { status: "failed", error: { category: "invalid_request", code: "authentication_attempt_not_active", message: "The authentication attempt is not active.", recovery: { kind: "none" } } };
+      }
+      const attempt = active;
+      attempt.expired = context.reason === "timeout";
+      attempt.controller.abort(new DOMException("Authentication canceled.", "AbortError"));
+      await attempt.settled;
+      return attempt.dispatched && !attempt.terminal ? { status: "failed", error: { category: "unknown", code: "authentication_outcome_uncertain", message: "Authentication was interrupted after native execution began.", recovery: { kind: "unknown" } } } : { status: "canceled" };
+    }
+  });
+  async function* start(context) {
+    throwIfAgentOperationAborted(context.signal);
+    throwIfAgentOperationAborted(input.lifetime);
+    if (active) throw new AcpProviderConnectionError("acp_authentication_active", "An ACP authentication attempt is already active.");
+    if (terminals.size) throw new AcpProviderConnectionError("acp_authentication_cleanup_pending", "Authentication terminal cleanup must complete before another attempt.");
+    const method = input.methods.get(context.flow);
+    if (!method) throw new TypeError("The ACP authentication flow is unsupported.");
+    let settle;
+    const attempt = {
+      id: context.attemptId,
+      controller: new AbortController(),
+      settled: new Promise((resolve) => {
+        settle = resolve;
+      }),
+      resolve: () => settle(),
+      dispatched: false,
+      expired: false,
+      terminal: false
+    };
+    active = attempt;
+    let started;
+    const admitted = new Promise((resolve) => {
+      started = resolve;
+    });
+    const result = runAttempt(context, method, attempt, started);
+    void result.catch(() => void 0);
+    try {
+      await admitted;
+      yield createAgentAuthenticationOutput({ attemptId: context.attemptId, status: "awaiting_user", occurredAt: input.now() });
+      yield await result;
+    } finally {
+      if (active === attempt) attempt.controller.abort(new DOMException("Authentication observer closed.", "AbortError"));
+      await attempt.settled;
+    }
+  }
+  async function runAttempt(context, method, attempt, started) {
+    const parent = AbortSignal.any([input.lifetime, attempt.controller.signal, ...context.signal ? [context.signal] : []]);
+    const remaining = context.deadlineAt ? Date.parse(context.deadlineAt) - Date.now() : input.limits.authenticationTimeoutMs;
+    const deadline = hostDeadline(parent, Math.max(0, Math.min(input.limits.authenticationTimeoutMs, remaining)));
+    let connection;
+    let terminalRelease;
+    let releaseAttempted = false;
+    let succeeded = false;
+    let cleanupFailed = false;
+    try {
+      connection = await input.acquire(deadline.signal);
+      throwIfAgentOperationAborted(deadline.signal);
+      const scope = { kind: "authentication", attemptId: context.attemptId, flow: context.flow };
+      if (method.type === "agent") {
+        const operation = connection.requestWithScope("authenticate", { methodId: method.methodId }, scope, {
+          signal: deadline.signal,
+          timeoutMs: Math.max(1, Math.min(input.limits.authenticationTimeoutMs, remaining)),
+          onRequestDispatch: () => {
+            attempt.dispatched = true;
+          },
+          onResponseReceived: () => {
+            attempt.terminal = true;
+          }
+        });
+        started();
+        await operation;
+      } else {
+        await input.retire(connection);
+        connection = void 0;
+        attempt.dispatched = true;
+        started();
+        const { lease, release } = await terminals.acquire((signal) => input.host.authenticateInTerminal({
+          instanceId: input.instanceId,
+          scope,
+          signal,
+          methodId: method.methodId,
+          args: method.args,
+          env: method.env
+        }), deadline.signal, deadline.signal, (lease2) => {
+          if (lease2?.exited) void Promise.resolve(lease2.exited).catch(() => void 0);
+        });
+        terminalRelease = release;
+        if (!lease || typeof lease.release !== "function" || !lease.exited || typeof lease.exited.then !== "function") {
+          throw new TypeError("The authentication terminal lease is invalid.");
+        }
+        const status = hostExitStatus(await awaitHost(lease.exited, deadline.signal));
+        if (status.exitCode !== 0 || status.signal !== void 0) throw new AcpProviderConnectionError("acp_authentication_terminal_failed", "The authentication terminal did not exit successfully.");
+        releaseAttempted = true;
+        await terminalRelease();
+        connection = await input.acquire(deadline.signal);
+        attempt.terminal = true;
+      }
+      throwIfAgentOperationAborted(deadline.signal);
+      input.retain(connection);
+      succeeded = true;
+    } catch {
+    } finally {
+      if (!succeeded) {
+        const cleanup = await Promise.allSettled([
+          ...terminalRelease && !releaseAttempted ? [terminalRelease()] : [],
+          ...connection ? [input.retire(connection)] : []
+        ]);
+        cleanupFailed = cleanup.some((result) => result.status === "rejected");
+      }
+      started();
+      deadline.close();
+      active = void 0;
+      attempt.resolve();
+    }
+    if (succeeded) return createAgentAuthenticationOutput({ attemptId: context.attemptId, status: "completed", occurredAt: input.now() });
+    const interrupted = parent.aborted || deadline.signal.aborted;
+    const uncertain = attempt.dispatched && !attempt.terminal;
+    const failed = uncertain || cleanupFailed || !interrupted;
+    const expired = attempt.expired || !parent.aborted && deadline.signal.aborted;
+    return createAgentAuthenticationOutput({
+      attemptId: context.attemptId,
+      status: failed ? "failed" : expired ? "expired" : "canceled",
+      occurredAt: input.now(),
+      ...failed ? { error: {
+        category: "unknown",
+        code: uncertain ? "authentication_outcome_uncertain" : "authentication_failed",
+        message: uncertain ? "Authentication ended without a confirmed native result." : "The authentication operation failed.",
+        recovery: { kind: "unknown" }
+      } } : {}
+    });
+  }
+  return {
+    port,
+    get active() {
+      return active !== void 0;
+    },
+    get cleanupPending() {
+      return terminals.size > 0;
+    },
+    async close() {
+      if (active) {
+        const attempt = active;
+        attempt.controller.abort(input.lifetime.reason);
+        await attempt.settled;
+        if (terminals.size) throw new AcpProviderConnectionError("acp_authentication_cleanup_pending", "Authentication terminal cleanup failed.");
+        return;
+      }
+      await terminals.close();
+    }
+  };
+}
+export {
+  createAcpAuthentication
+};

package/dist/auth/methods.d.ts

@@ -0,0 +1,12 @@
+import type { AgentAuthenticationFlow } from '@agen-ai/agent-protocol';
+import type { AcpNegotiatedAgent } from '../connection/contracts.js';
+import type { AcpAuthenticationMethods, AcpHostFacilities } from '../host/contracts.js';
+export interface AcpAuthenticationMethod {
+    readonly methodId: string;
+    readonly type: 'agent' | 'terminal';
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+export declare function resolveAuthenticationMapping(value?: AcpAuthenticationMethods): AcpAuthenticationMethods;
+export declare function selectedAuthenticationMethods(negotiated: AcpNegotiatedAgent, selections: AcpAuthenticationMethods, host: AcpHostFacilities): ReadonlyMap<AgentAuthenticationFlow, AcpAuthenticationMethod>;
+//# sourceMappingURL=methods.d.ts.map

package/dist/auth/methods.js

@@ -0,0 +1,51 @@
+import { hostObject, hostText } from "../host/validation.js";
+function resolveAuthenticationMapping(value = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((flow) => !["browser", "device_code", "terminal"].includes(flow))) {
+    throw new TypeError("ACP authentication requires explicit supported flow mappings.");
+  }
+  return Object.freeze(Object.fromEntries(Object.entries(value).map(([flow, selection]) => {
+    if (!selection || typeof selection !== "object" || Object.keys(selection).some((key) => key !== "methodId")) {
+      throw new TypeError("ACP authentication selections contain only an advertised method ID.");
+    }
+    return [flow, Object.freeze({ methodId: hostText(selection.methodId, 256) })];
+  })));
+}
+function selectedAuthenticationMethods(negotiated, selections, host) {
+  if (negotiated.authMethods.length > 32) throw new TypeError("ACP authentication method inventory exceeds its bound.");
+  const methods = /* @__PURE__ */ new Map();
+  for (const value of negotiated.authMethods) {
+    const method = hostObject(value);
+    const id = hostText(method.id, 256);
+    if (methods.has(id)) throw new TypeError("ACP authentication method IDs must be unique.");
+    methods.set(id, method);
+  }
+  const selected = /* @__PURE__ */ new Map();
+  for (const flow of ["device_code", "browser", "terminal"]) {
+    const selection = selections[flow];
+    if (!selection) continue;
+    const method = methods.get(selection.methodId);
+    if (!method) throw new TypeError("A selected ACP authentication method was not advertised.");
+    const type = method.type ?? "agent";
+    if (type !== "agent" && type !== "terminal") throw new TypeError("The selected ACP authentication method type is unsupported.");
+    if (flow === "terminal" && (type !== "terminal" || !host.authenticateInTerminal) || flow !== "terminal" && type !== "agent") throw new TypeError("ACP authentication method and host flow do not match.");
+    const args = method.args ?? [];
+    if (!Array.isArray(args) || args.length > 128) throw new TypeError("ACP authentication arguments exceed their bound.");
+    const env = method.env == null ? {} : hostObject(method.env);
+    if (Object.keys(env).length > 128) throw new TypeError("ACP authentication environment exceeds its bound.");
+    const variables = Object.entries(env).map(([name, value]) => {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)) throw new TypeError("ACP authentication environment names are invalid.");
+      return [name, hostText(value, 16384, true)];
+    });
+    selected.set(flow, Object.freeze({
+      methodId: selection.methodId,
+      type,
+      args: Object.freeze(args.map((value) => hostText(value, 16384, true))),
+      env: Object.freeze(Object.fromEntries(variables))
+    }));
+  }
+  return selected;
+}
+export {
+  resolveAuthenticationMapping,
+  selectedAuthenticationMethods
+};

package/dist/capabilities.d.ts

@@ -0,0 +1,4 @@
+import { type AgentAuthenticationFlow, type AgentCapabilities, type AgentProviderKey } from '@agen-ai/agent-protocol';
+import type { AcpNegotiatedAgent } from './connection/contracts.js';
+export declare function acpProviderCapabilities(providerKey: AgentProviderKey, negotiated: AcpNegotiatedAgent, configuration?: 'managed' | 'selectable', authenticationFlows?: readonly AgentAuthenticationFlow[]): AgentCapabilities;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.js

@@ -0,0 +1,46 @@
+import { parseAgentCapabilities } from "@agen-ai/agent-protocol";
+function freezeCapabilities(value) {
+  if (value && typeof value === "object") {
+    for (const child of Object.values(value)) freezeCapabilities(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+function acpProviderCapabilities(providerKey, negotiated, configuration = "managed", authenticationFlows = []) {
+  return freezeCapabilities(parseAgentCapabilities({
+    protocolVersion: 10,
+    providerKey,
+    sessions: { create: true, resume: negotiated.agentCapabilities.loadSession === true || negotiated.agentCapabilities.sessionCapabilities?.resume != null, branch: { kind: "unsupported" } },
+    turns: { interactionModes: ["default"], interrupt: true, steer: { kind: "unsupported" } },
+    requests: {
+      approval: { kind: "supported", modes: [{ persistence: "once", scopeKinds: ["exact_action"] }] },
+      elicitation: { kind: "supported", fieldKinds: ["single_select", "multi_select", "boolean"], maxFields: 16, sensitiveFields: false }
+    },
+    context: { usage: { kind: "unsupported" }, compaction: { kind: "unsupported" } },
+    input: { text: true, images: negotiated.agentCapabilities.promptCapabilities?.image === true ? {
+      kind: "supported",
+      sourceKinds: ["base64"],
+      mediaTypes: ["image/png", "image/jpeg", "image/webp"],
+      maxImages: 16,
+      maxBytesPerImage: 375e3,
+      maxTotalBytes: 75e4,
+      maxWidthPixels: 1e5,
+      maxHeightPixels: 1e5,
+      maxPixelsPerImage: 1e8,
+      supportsImageOnly: true
+    } : { kind: "unsupported" }, contentReferences: { kind: "unsupported" } },
+    output: { streaming: true, plans: true, fileChanges: "structured", artifactKinds: [] },
+    configuration: configuration === "managed" ? { kind: "managed" } : { kind: "selectable", fieldKinds: ["boolean", "single_select"], maxFields: 100 },
+    operations: { kind: "unsupported" },
+    managedContent: { kind: "unsupported" },
+    integrations: { kind: "unsupported" },
+    environment: { instance: { kind: "unsupported" }, session: { kind: "read_and_watch", domains: ["commands"] } },
+    collaboration: { kind: "unsupported" },
+    generatedResources: { kind: "unsupported" },
+    authentication: authenticationFlows.length ? { kind: "supported", flows: authenticationFlows } : { kind: "unsupported" },
+    versionReporting: negotiated.agentInfo !== void 0
+  }));
+}
+export {
+  acpProviderCapabilities
+};

package/dist/configuration/catalog.d.ts

@@ -0,0 +1,35 @@
+import type { AcpJsonObject } from '@agen-ai/acp-transport';
+import { type AgentBooleanConfigurationField, type AgentCapabilities, type AgentConfigurationCatalog, type AgentConfigurationSelectionInput, type AgentSingleSelectConfigurationField } from '@agen-ai/agent-protocol';
+type ConfigurationField = Omit<AgentBooleanConfigurationField, 'revision'> | Omit<AgentSingleSelectConfigurationField, 'revision'>;
+interface AcpConfigurationBinding {
+    readonly field: ConfigurationField;
+    readonly method: 'session/set_config_option' | 'session/set_mode';
+    readonly nativeId: string;
+    readonly options: ReadonlyMap<string, string>;
+}
+export declare class AcpConfigurationCatalogState {
+    private readonly maxSnapshotBytes;
+    private readonly capability;
+    private snapshot;
+    private bindings;
+    private fingerprint;
+    private failure;
+    private source;
+    constructor(maxSnapshotBytes: number, capability: Extract<AgentCapabilities['configuration'], {
+        readonly kind: 'selectable';
+    }>);
+    private replace;
+    assertValid(): void;
+    retire(error: Error): void;
+    observeSetup(response: AcpJsonObject): void;
+    observeUpdate(update: AcpJsonObject): boolean;
+    observeConfigResponse(response: AcpJsonObject): void;
+    observeMode(nativeMode: string): void;
+    list(): AgentConfigurationCatalog;
+    resolve(input: AgentConfigurationSelectionInput): {
+        readonly binding: AcpConfigurationBinding;
+        readonly selection: AgentConfigurationSelectionInput;
+    };
+}
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/configuration/catalog.js

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import {
+  AGENT_CONFIGURATION_FIELDS_MAX_LENGTH,
+  AGENT_CONFIGURATION_OPTIONS_MAX_LENGTH,
+  parseAgentConfigurationCatalog,
+  parseAgentConfigurationSelectionFor
+} from "@agen-ai/agent-protocol";
+import { AcpConfigurationError, invalidConfigurationCatalog } from "./errors.js";
+function object(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return invalidConfigurationCatalog();
+  return value;
+}
+function string(value) {
+  if (typeof value !== "string" || !value || value.length > 4096) return invalidConfigurationCatalog();
+  return value;
+}
+function optionalDescription(value) {
+  return value === null || value === void 0 || value === "" ? {} : { description: string(value) };
+}
+function id(kind, ...nativeIds) {
+  return `acp:${kind}:${createHash("sha256").update(JSON.stringify(nativeIds)).digest("hex")}`;
+}
+function compareKeys(left, right) {
+  return left.key < right.key ? -1 : left.key > right.key ? 1 : 0;
+}
+function selectBinding(input) {
+  if (!input.values.length || input.values.length > AGENT_CONFIGURATION_OPTIONS_MAX_LENGTH) return invalidConfigurationCatalog();
+  const options = /* @__PURE__ */ new Map();
+  const nativeValues = /* @__PURE__ */ new Set();
+  const publicOptions = input.values.map((option) => {
+    const nativeValue = string(input.method === "session/set_mode" ? option.id : option.value);
+    if (nativeValues.has(nativeValue)) return invalidConfigurationCatalog();
+    nativeValues.add(nativeValue);
+    const optionId = id("value", input.method, input.nativeId, nativeValue);
+    options.set(optionId, nativeValue);
+    return { optionId, label: string(option.name), ...optionalDescription(option.description) };
+  }).sort((left, right) => compareKeys({ key: left.optionId }, { key: right.optionId }));
+  if (!nativeValues.has(input.currentValue)) return invalidConfigurationCatalog();
+  return {
+    field: {
+      key: id("field", input.method, input.nativeId),
+      fieldKind: "single_select",
+      label: input.name,
+      ...input.description === void 0 ? {} : { description: input.description },
+      scope: "session",
+      applicationTiming: "immediate",
+      mutable: true,
+      currentValue: id("value", input.method, input.nativeId, input.currentValue),
+      options: publicOptions
+    },
+    method: input.method,
+    nativeId: input.nativeId,
+    options
+  };
+}
+function selectValues(value) {
+  if (!Array.isArray(value) || value.length > AGENT_CONFIGURATION_OPTIONS_MAX_LENGTH) return invalidConfigurationCatalog();
+  const values = [];
+  const groupIds = /* @__PURE__ */ new Set();
+  const grouped = value.length > 0 && Object.hasOwn(object(value[0]), "group");
+  for (const item of value) {
+    const option = object(item);
+    if (Object.hasOwn(option, "group") !== grouped) return invalidConfigurationCatalog();
+    if (grouped) {
+      const groupId = string(option.group);
+      if (groupIds.has(groupId)) return invalidConfigurationCatalog();
+      groupIds.add(groupId);
+      const groupName = string(option.name);
+      if (!Array.isArray(option.options)) return invalidConfigurationCatalog();
+      for (const member of option.options) {
+        if (values.length >= AGENT_CONFIGURATION_OPTIONS_MAX_LENGTH) return invalidConfigurationCatalog();
+        const groupedOption = object(member);
+        values.push({ ...groupedOption, name: `${groupName}: ${string(groupedOption.name)}` });
+      }
+    } else values.push(option);
+  }
+  return values;
+}
+function mapAcpConfigOptions(value) {
+  if (!Array.isArray(value) || value.length > AGENT_CONFIGURATION_FIELDS_MAX_LENGTH) return invalidConfigurationCatalog();
+  const nativeIds = /* @__PURE__ */ new Set();
+  return value.map((item) => {
+    const option = object(item);
+    const nativeId = string(option.id);
+    if (nativeIds.has(nativeId)) return invalidConfigurationCatalog();
+    nativeIds.add(nativeId);
+    const common = {
+      key: id("field", "session/set_config_option", nativeId),
+      label: string(option.name),
+      ...optionalDescription(option.description),
+      scope: "session",
+      applicationTiming: "immediate",
+      mutable: true
+    };
+    if (option.type === "boolean" && typeof option.currentValue === "boolean") {
+      return {
+        field: { ...common, fieldKind: "boolean", currentValue: option.currentValue },
+        method: "session/set_config_option",
+        nativeId,
+        options: /* @__PURE__ */ new Map()
+      };
+    }
+    if (option.type !== "select") return invalidConfigurationCatalog();
+    return selectBinding({
+      nativeId,
+      name: common.label,
+      ...optionalDescription(option.description),
+      currentValue: string(option.currentValue),
+      values: selectValues(option.options),
+      method: "session/set_config_option"
+    });
+  }).sort((left, right) => compareKeys(left.field, right.field));
+}
+function mapAcpModes(value) {
+  const modes = object(value);
+  if (!Array.isArray(modes.availableModes)) return invalidConfigurationCatalog();
+  return [selectBinding({
+    nativeId: "mode",
+    name: "Session mode",
+    currentValue: string(modes.currentModeId),
+    values: modes.availableModes.map(object),
+    method: "session/set_mode"
+  })];
+}
+class AcpConfigurationCatalogState {
+  constructor(maxSnapshotBytes, capability) {
+    this.maxSnapshotBytes = maxSnapshotBytes;
+    this.capability = capability;
+  }
+  maxSnapshotBytes;
+  capability;
+  snapshot;
+  bindings = /* @__PURE__ */ new Map();
+  fingerprint;
+  failure;
+  source;
+  replace(source, native) {
+    this.assertValid();
+    try {
+      if (native === void 0 || Buffer.byteLength(JSON.stringify(native), "utf8") > this.maxSnapshotBytes) return invalidConfigurationCatalog();
+      const bindings = source === "config" ? mapAcpConfigOptions(native) : mapAcpModes(native);
+      if (bindings.length > this.capability.maxFields || bindings.some((binding) => !this.capability.fieldKinds.includes(binding.field.fieldKind))) return invalidConfigurationCatalog();
+      const fingerprint = JSON.stringify(bindings.map((binding) => binding.field));
+      if (this.source === source && this.fingerprint === fingerprint) return;
+      const revision = (this.snapshot?.revision ?? 0) + 1;
+      if (!Number.isSafeInteger(revision)) return invalidConfigurationCatalog();
+      const fields = bindings.map((binding) => {
+        const previous = this.bindings.get(binding.field.key);
+        const previousField = this.snapshot?.fields.find((field) => field.key === binding.field.key);
+        const fieldRevision = previous && previousField && JSON.stringify(previous.field) === JSON.stringify(binding.field) ? previousField.revision : revision;
+        return { ...binding.field, revision: fieldRevision };
+      });
+      const snapshot = parseAgentConfigurationCatalog({ revision, fields });
+      this.bindings = new Map(bindings.map((binding) => [binding.field.key, binding]));
+      this.snapshot = snapshot;
+      this.source = source;
+      this.fingerprint = fingerprint;
+    } catch (cause) {
+      const error = cause instanceof AcpConfigurationError ? cause : new AcpConfigurationError(
+        "acp_configuration_catalog_invalid",
+        "ACP configuration cannot be represented faithfully within the declared bounds.",
+        { cause }
+      );
+      this.failure = error;
+      throw error;
+    }
+  }
+  assertValid() {
+    if (this.failure) throw this.failure;
+  }
+  retire(error) {
+    this.failure ??= error;
+  }
+  observeSetup(response) {
+    if (response.configOptions !== null && response.configOptions !== void 0) this.replace("config", response.configOptions);
+    else if (this.source !== "config" && response.modes !== null && response.modes !== void 0) this.replace("modes", response.modes);
+  }
+  observeUpdate(update) {
+    if (update.sessionUpdate === "config_option_update") {
+      this.replace("config", update.configOptions);
+      return true;
+    }
+    if (update.sessionUpdate === "current_mode_update") {
+      if (this.source === "modes") this.observeMode(string(update.currentModeId));
+      return true;
+    }
+    return false;
+  }
+  observeConfigResponse(response) {
+    this.replace("config", response.configOptions);
+  }
+  observeMode(nativeMode) {
+    this.assertValid();
+    const binding = [...this.bindings.values()].find((candidate) => candidate.method === "session/set_mode");
+    if (this.source !== "modes" || !binding || binding.field.fieldKind !== "single_select") return invalidConfigurationCatalog();
+    const availableModes = binding.field.options.map((option) => ({
+      id: binding.options.get(option.optionId),
+      name: option.label,
+      ...option.description === void 0 ? {} : { description: option.description }
+    }));
+    this.replace("modes", { currentModeId: nativeMode, availableModes });
+  }
+  list() {
+    this.assertValid();
+    if (!this.snapshot) throw new AcpConfigurationError("acp_configuration_catalog_unknown", "The ACP peer has not supplied a configuration catalog.");
+    return this.snapshot;
+  }
+  resolve(input) {
+    try {
+      const selection = parseAgentConfigurationSelectionFor(this.list(), input);
+      const binding = this.bindings.get(selection.key);
+      if (!binding) return invalidConfigurationCatalog();
+      return { binding, selection };
+    } catch (cause) {
+      if (cause instanceof AcpConfigurationError) throw cause;
+      throw new AcpConfigurationError("acp_configuration_selection_invalid", "The configuration selection is stale or outside the offered catalog.", { cause });
+    }
+  }
+}
+export {
+  AcpConfigurationCatalogState
+};

package/dist/configuration/control.d.ts

@@ -0,0 +1,19 @@
+import type { AcpClient, AcpJsonObject } from '@agen-ai/acp-transport';
+import { type AgentCapabilities, type AgentSessionConfiguration } from '@agen-ai/agent-protocol';
+import { type AgentSessionConfigurationControl } from '@agen-ai/agent-runtime';
+export interface AcpSessionConfiguration {
+    readonly control: AgentSessionConfigurationControl;
+    readonly observeSetup: (response: AcpJsonObject) => void;
+    readonly observeUpdate: (update: AcpJsonObject) => boolean;
+    readonly applyOpeningConfiguration: (configuration: AgentSessionConfiguration, signal?: AbortSignal) => Promise<void>;
+}
+export declare function createAcpSessionConfiguration(input: {
+    readonly capability: AgentCapabilities['configuration'];
+    readonly client: AcpClient;
+    readonly getSessionId: () => string;
+    readonly assertUsable: () => void;
+    readonly onFailure: (error: Error) => void;
+    readonly timeoutMs: number;
+    readonly maxSnapshotBytes?: number;
+}): AcpSessionConfiguration;
+//# sourceMappingURL=control.d.ts.map