@xenosystem/agent-interface-host 0.1.3

package/dist/acp/AcpHostBridge.js

@@ -0,0 +1,101 @@
+import { UnavailableCoordinationLaneBridge, } from '../coordination/laneBridge.js';
+import { XENO_ACP_COORDINATION_CLAIM_METHOD, XENO_ACP_COORDINATION_QUERY_METHOD, XENO_ACP_COORDINATION_SEND_METHOD, } from './AcpCoordinationBridge.js';
+import { AcpUnsupportedMethodError } from './acpErrors.js';
+export const XENO_ACP_META_KEY = 'xeno.dev';
+export const XENO_ACP_CHOOSE_DIRECTORY_METHOD = 'xeno.dev/choose_directory';
+export const XENO_ACP_CHOOSE_WORKSPACE_PLACEMENT_METHOD = 'xeno.dev/choose_workspace_placement';
+/**
+ * Every host method an ACP agent may call, by the name it is ADVERTISED under.
+ *
+ * 🔴 ONE table, because dispatch and advertisement are two halves of the same
+ * fact and a method with only one of them is unreachable.
+ *
+ * Advertisement is not documentation: `initialize` sends this list, and an
+ * agent that never receives a method's name never calls it. A dispatcher
+ * handling a method nobody was told about is "built, tested, unreachable"
+ * wearing a protocol — the shape this repo has now hit five times. Deriving the
+ * advertisement from this array makes the mismatch unrepresentable rather than
+ * merely tested for; a mutation setting one entry to `false` no longer compiles
+ * into anything, because there is nowhere to write it.
+ */
+export const XENO_ACP_HOST_REQUEST_METHODS = {
+    chooseDirectory: XENO_ACP_CHOOSE_DIRECTORY_METHOD,
+    chooseWorkspacePlacement: XENO_ACP_CHOOSE_WORKSPACE_PLACEMENT_METHOD,
+    coordinationSend: XENO_ACP_COORDINATION_SEND_METHOD,
+    coordinationQuery: XENO_ACP_COORDINATION_QUERY_METHOD,
+    coordinationClaim: XENO_ACP_COORDINATION_CLAIM_METHOD,
+};
+/** The `_meta['xeno.dev'].hostRequests` payload, derived, never hand-listed. */
+export function xenoAcpHostRequestAdvertisement() {
+    return Object.fromEntries(Object.keys(XENO_ACP_HOST_REQUEST_METHODS).map((name) => [name, true]));
+}
+export class FailClosedAcpHostBridge {
+    async chooseDirectory() {
+        return {
+            cancelled: true,
+            error: 'XENO ACP host choose-directory bridge is not available.',
+        };
+    }
+    async chooseWorkspacePlacement() {
+        return {
+            cancelled: true,
+            error: 'XENO ACP host workspace-placement bridge is not available.',
+        };
+    }
+}
+export function parseChooseDirectoryRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const record = value;
+    return {
+        sessionId: typeof record.sessionId === 'string' && record.sessionId.trim() ? record.sessionId.trim() : undefined,
+        requestId: typeof record.requestId === 'string' && record.requestId.trim() ? record.requestId.trim() : undefined,
+        title: typeof record.title === 'string' && record.title.trim() ? record.title.trim().slice(0, 160) : undefined,
+        toolCallId: typeof record.toolCallId === 'string' && record.toolCallId.trim()
+            ? record.toolCallId.trim().slice(0, 256)
+            : undefined,
+    };
+}
+export function parseChooseWorkspacePlacementRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const record = value;
+    return {
+        sessionId: typeof record.sessionId === 'string' && record.sessionId.trim() ? record.sessionId.trim() : undefined,
+        requestId: typeof record.requestId === 'string' && record.requestId.trim() ? record.requestId.trim() : undefined,
+        directory: typeof record.directory === 'string' && record.directory.trim() ? record.directory.trim().slice(0, 2000) : undefined,
+        title: typeof record.title === 'string' && record.title.trim() ? record.title.trim().slice(0, 160) : undefined,
+        toolCallId: typeof record.toolCallId === 'string' && record.toolCallId.trim()
+            ? record.toolCallId.trim().slice(0, 256)
+            : undefined,
+    };
+}
+export async function handleAcpHostExtensionRequest(method, params, bridge = new FailClosedAcpHostBridge(), 
+/**
+ * Coordination — §5.2b's three primitives, on the surface that already exists.
+ *
+ * 🔴 Defaults to the UNAVAILABLE bridge, not to a working one and not to
+ * silence. A host without coordination mounted must say so by name: "no
+ * peers" and "this host cannot coordinate" are the same empty list and
+ * opposite meanings, and an agent told the first concludes it is working
+ * alone — then edits a file another run has claimed.
+ */
+coordination = new UnavailableCoordinationLaneBridge()) {
+    if (method === XENO_ACP_CHOOSE_DIRECTORY_METHOD) {
+        return bridge.chooseDirectory(parseChooseDirectoryRequest(params));
+    }
+    if (method === XENO_ACP_CHOOSE_WORKSPACE_PLACEMENT_METHOD) {
+        return bridge.chooseWorkspacePlacement(parseChooseWorkspacePlacementRequest(params));
+    }
+    if (method === XENO_ACP_COORDINATION_SEND_METHOD)
+        return coordination.send(params);
+    if (method === XENO_ACP_COORDINATION_QUERY_METHOD)
+        return coordination.query(params);
+    if (method === XENO_ACP_COORDINATION_CLAIM_METHOD)
+        return coordination.claim(params);
+    throw new AcpUnsupportedMethodError(method);
+}
+export function cancelAcpHostBridge(bridge, reason = 'ACP prompt cancelled.') {
+    bridge.cancelOutstanding?.(reason);
+}
+//# sourceMappingURL=AcpHostBridge.js.map

package/dist/acp/AcpHostBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcpHostBridge.js","sourceRoot":"","sources":["../../src/acp/AcpHostBridge.ts"],"names":[],"mappings":"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"}

package/dist/acp/AcpInteractivePermissionBridge.d.ts

@@ -0,0 +1,77 @@
+import type { AcpPermissionOutcome, AcpPermissionRequest } from './acpTypes.js';
+import type { AcpPermissionBridge } from './AcpPermissionBridge.js';
+/**
+ * THE INTERACTIVE HALF of ACP permissions (ADE spec §10b.0).
+ *
+ * `PolicyGatedAcpPermissionBridge` decides what stored rules can decide. This is
+ * the delegate it falls back to: it asks a human.
+ *
+ * Until now there was no such delegate, so the composed adapter fell through to
+ * `FailClosedAcpPermissionBridge` and every ACP permission request was refused
+ * without anyone being asked.
+ *
+ * ## Why this publishes through the host rather than to a window
+ *
+ * The SDK-native lane raises its prompts with `mainWindow.webContents.send`,
+ * which bypasses the host entirely — which is why the contract advertises
+ * `elicitation.permission.requested` and the host has never once published it
+ * (`createElicitationSurfaceMessenger()` had no callers).
+ *
+ * This bridge takes that messenger instead. The host publishes, surfaces
+ * subscribe, and the renderer stays a renderer: it is handed a request and
+ * returns an answer, and holds no authority over the outcome (§7). It also
+ * means the prompt reaches EVERY attached surface rather than one window, which
+ * is a prerequisite for the detached host.
+ *
+ * ## Fail-closed, deliberately and visibly
+ *
+ * Anything other than an explicit grant — a denial, a cancelled turn, a timeout,
+ * a shutdown — resolves to a refusal. The one thing that must never happen is a
+ * request answered "allow" because nobody answered it.
+ */
+export interface AcpInteractivePermissionSurfaceMessenger {
+    send(channel: string, payload: Record<string, unknown>): void;
+}
+export interface AcpInteractivePermissionBridgeOptions {
+    messenger: AcpInteractivePermissionSurfaceMessenger;
+    /**
+     * How long to wait for a human before refusing. A permission prompt with no
+     * answer must not pin an agent turn open forever.
+     */
+    timeoutMs?: undefined | number;
+    newPermissionId?: undefined | (() => string);
+}
+export interface AcpPermissionAnswer {
+    permissionId: string;
+    granted: boolean;
+    /**
+     * An explicit choice among the options the agent offered — how a surface
+     * expresses "allow always" rather than "allow once".
+     *
+     * VALIDATED against the offered set before use. The renderer is untrusted
+     * (§7): an id it invents must never be forwarded to an agent, because the
+     * agent decides what each id means and an unknown one could map to anything.
+     */
+    selectedOptionId?: undefined | string;
+}
+/** Whether this bridge owned the answered permission id. */
+export interface AcpPermissionAnswerResult {
+    handled: boolean;
+}
+export declare class AcpInteractivePermissionBridge implements AcpPermissionBridge {
+    private readonly messenger;
+    private readonly timeoutMs;
+    private readonly newPermissionId;
+    private readonly pending;
+    constructor(options: AcpInteractivePermissionBridgeOptions);
+    requestPermission(request: AcpPermissionRequest): Promise<AcpPermissionOutcome>;
+    /**
+     * Routes a surface answer. Returns `handled: false` when the id belongs to
+     * another lane, so a composite interaction service can fall through rather
+     * than swallowing an SDK-native answer.
+     */
+    answerPermission(answer: AcpPermissionAnswer): AcpPermissionAnswerResult;
+    cancelOutstanding(): void;
+    get pendingCount(): number;
+}
+//# sourceMappingURL=AcpInteractivePermissionBridge.d.ts.map

package/dist/acp/AcpInteractivePermissionBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcpInteractivePermissionBridge.d.ts","sourceRoot":"","sources":["../../src/acp/AcpInteractivePermissionBridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAC/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,wCAAwC;IACvD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC9D;AAED,MAAM,WAAW,qCAAqC;IACpD,SAAS,EAAE,wCAAwC,CAAA;IACnD;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAA;IAC9B,eAAe,CAAC,EAAE,SAAS,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,SAAS,GAAG,MAAM,CAAA;CACtC;AAED,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,CAAA;CACjB;AAUD,qBAAa,8BAA+B,YAAW,mBAAmB;IACxE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;gBAEtD,OAAO,EAAE,qCAAqC;IAMpD,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAuDrF;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,yBAAyB;IA+CxE,iBAAiB,IAAI,IAAI;IAMzB,IAAI,YAAY,IAAI,MAAM,CAEzB;CACF"}

package/dist/acp/AcpInteractivePermissionBridge.js

@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+import { selectOptionForDecision } from './AcpPermissionPolicy.js';
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+export class AcpInteractivePermissionBridge {
+    messenger;
+    timeoutMs;
+    newPermissionId;
+    pending = new Map();
+    constructor(options) {
+        this.messenger = options.messenger;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.newPermissionId = options.newPermissionId || (() => `acp-permission-${randomUUID()}`);
+    }
+    async requestPermission(request) {
+        // Prefer the host's journalled id — see AcpPermissionRequest.hostPermissionId.
+        // Minting a second id here is how a prompt becomes unanswerable.
+        const permissionId = request.hostPermissionId || this.newPermissionId();
+        return await new Promise((resolve) => {
+            const settle = (outcome) => {
+                const entry = this.pending.get(permissionId);
+                if (!entry)
+                    return;
+                if (entry.timer)
+                    clearTimeout(entry.timer);
+                this.pending.delete(permissionId);
+                resolve(outcome);
+            };
+            const timer = this.timeoutMs > 0
+                ? setTimeout(() => { settle({ outcome: 'cancelled' }); }, this.timeoutMs)
+                : undefined;
+            timer?.unref?.();
+            this.pending.set(permissionId, { resolve: settle, request, timer });
+            try {
+                // Same channel and shape the renderer already renders for the
+                // SDK-native lane, so no second prompt UI is needed. `toolName` and
+                // `path` come from the ACP toolCall, which is why carrying it through
+                // the parse was the prerequisite for this.
+                this.messenger.send('agent:permission-request', {
+                    // REQUIRED by the surface: it routes the prompt onto a conversation
+                    // by this id and drops any permission event without one.
+                    requestId: request.hostRequestId,
+                    permissionId,
+                    source: 'acp',
+                    sessionId: request.sessionId,
+                    toolName: request.toolCall?.title || request.toolCall?.kind || 'ACP tool call',
+                    toolKind: request.toolCall?.kind,
+                    // A human-readable action description, matching how the SDK-native
+                    // lane uses this field (it sends `actionText`, not a filesystem path).
+                    path: (request.toolCall?.locations || []).map((location) => location.path).join(', ')
+                        || request.toolCall?.title
+                        || request.toolCall?.kind
+                        || 'ACP tool call',
+                    directory: (request.toolCall?.locations || [])[0]?.path,
+                    options: (request.options || []).map((option) => ({
+                        id: option.id,
+                        label: option.label,
+                        kind: option.kind,
+                    })),
+                    allowAlwaysOptionId: (request.options || []).find((option) => option.kind === 'allow_always')?.id,
+                    rejectAlwaysOptionId: (request.options || []).find((option) => option.kind === 'reject_always')?.id,
+                });
+            }
+            catch {
+                // A surface that cannot be reached is a refusal, not an approval.
+                settle({ outcome: 'cancelled' });
+            }
+        });
+    }
+    /**
+     * Routes a surface answer. Returns `handled: false` when the id belongs to
+     * another lane, so a composite interaction service can fall through rather
+     * than swallowing an SDK-native answer.
+     */
+    answerPermission(answer) {
+        const entry = this.pending.get(answer.permissionId);
+        if (!entry)
+            return { handled: false };
+        /**
+         * An explicit choice is honoured for BOTH directions — "always deny" is as
+         * real a choice as "always allow" — but only after two checks:
+         *
+         *  1. the id was actually offered by the agent, and
+         *  2. its KIND agrees with `granted`.
+         *
+         * The second matters more than it looks. Without it, a renderer bug or a
+         * hostile one could send `granted: false` alongside an `allow_always` id and
+         * the host would grant a permission the user had just refused. A mismatch
+         * is therefore ignored in favour of the safe mapping, never trusted.
+         */
+        const offered = answer.selectedOptionId
+            ? (entry.request.options || []).find((option) => option.id === answer.selectedOptionId)
+            : undefined;
+        const agreesWithAnswer = offered?.kind
+            ? (answer.granted
+                ? offered.kind === 'allow_once' || offered.kind === 'allow_always'
+                : offered.kind === 'reject_once' || offered.kind === 'reject_always')
+            : false;
+        if (offered && agreesWithAnswer) {
+            entry.resolve({ outcome: 'selected', selectedOptionId: offered.id });
+            return { handled: true };
+        }
+        if (!answer.granted) {
+            const rejection = selectOptionForDecision(entry.request.options, 'deny');
+            entry.resolve(rejection
+                ? { outcome: 'selected', selectedOptionId: rejection.id }
+                : { outcome: 'cancelled' });
+            return { handled: true };
+        }
+        const approval = selectOptionForDecision(entry.request.options, 'allow');
+        // A grant we cannot express is NOT an approval. Selecting an arbitrary
+        // option id here would authorise something other than what the user
+        // approved, so it degrades to a refusal.
+        entry.resolve(approval
+            ? { outcome: 'selected', selectedOptionId: approval.id }
+            : { outcome: 'cancelled' });
+        return { handled: true };
+    }
+    cancelOutstanding() {
+        for (const permissionId of [...this.pending.keys()]) {
+            this.pending.get(permissionId)?.resolve({ outcome: 'cancelled' });
+        }
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+}
+//# sourceMappingURL=AcpInteractivePermissionBridge.js.map

package/dist/acp/AcpInteractivePermissionBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcpInteractivePermissionBridge.js","sourceRoot":"","sources":["../../src/acp/AcpInteractivePermissionBridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAuElE,MAAM,kBAAkB,GAAG,EAAE,GAAG,MAAM,CAAA;AAEtC,MAAM,OAAO,8BAA8B;IACxB,SAAS,CAA0C;IACnD,SAAS,CAAQ;IACjB,eAAe,CAAc;IAC7B,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAA;IAElE,YAAY,OAA8C;QACxD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;QAClC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAA;QACxD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,CAAC,kBAAkB,UAAU,EAAE,EAAE,CAAC,CAAA;IAC5F,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,OAA6B;QACnD,+EAA+E;QAC/E,iEAAiE;QACjE,MAAM,YAAY,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC,eAAe,EAAE,CAAA;QACvE,OAAO,MAAM,IAAI,OAAO,CAAuB,CAAC,OAAO,EAAE,EAAE;YACzD,MAAM,MAAM,GAAG,CAAC,OAA6B,EAAQ,EAAE;gBACrD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;gBAC5C,IAAI,CAAC,KAAK;oBAAE,OAAM;gBAClB,IAAI,KAAK,CAAC,KAAK;oBAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;gBAC1C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;gBACjC,OAAO,CAAC,OAAO,CAAC,CAAA;YAClB,CAAC,CAAA;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC;gBAC9B,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAA,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC;gBACxE,CAAC,CAAC,SAAS,CAAA;YACb,KAAK,EAAE,KAAK,EAAE,EAAE,CAAA;YAChB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;YAEnE,IAAI,CAAC;gBACH,8DAA8D;gBAC9D,oEAAoE;gBACpE,sEAAsE;gBACtE,2CAA2C;gBAC3C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,0BAA0B,EAAE;oBAC9C,oEAAoE;oBACpE,yDAAyD;oBACzD,SAAS,EAAE,OAAO,CAAC,aAAa;oBAChC,YAAY;oBACZ,MAAM,EAAE,KAAK;oBACb,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,IAAI,OAAO,CAAC,QAAQ,EAAE,IAAI,IAAI,eAAe;oBAC9E,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI;oBAChC,mEAAmE;oBACnE,uEAAuE;oBACvE,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;2BAChF,OAAO,CAAC,QAAQ,EAAE,KAAK;2BACvB,OAAO,CAAC,QAAQ,EAAE,IAAI;2BACtB,eAAe;oBACpB,SAAS,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI;oBACvD,OAAO,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;wBAChD,EAAE,EAAE,MAAM,CAAC,EAAE;wBACb,KAAK,EAAE,MAAM,CAAC,KAAK;wBACnB,IAAI,EAAE,MAAM,CAAC,IAAI;qBAClB,CAAC,CAAC;oBACH,mBAAmB,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,EAAE,EAAE;oBACjG,oBAAoB,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,eAAe,CAAC,EAAE,EAAE;iBACpG,CAAC,CAAA;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;gBAClE,MAAM,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAA;YAClC,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,gBAAgB,CAAC,MAA2B;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QACnD,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;QAErC;;;;;;;;;;;WAWG;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,gBAAgB;YACrC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,gBAAgB,CAAC;YACvF,CAAC,CAAC,SAAS,CAAA;QACb,MAAM,gBAAgB,GAAG,OAAO,EAAE,IAAI;YACpC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO;gBACf,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,YAAY,IAAI,OAAO,CAAC,IAAI,KAAK,cAAc;gBAClE,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,OAAO,CAAC,IAAI,KAAK,eAAe,CAAC;YACvE,CAAC,CAAC,KAAK,CAAA;QACT,IAAI,OAAO,IAAI,gBAAgB,EAAE,CAAC;YAChC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAA;YACpE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAC1B,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,SAAS,GAAG,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YACxE,KAAK,CAAC,OAAO,CAAC,SAAS;gBACrB,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,CAAC,EAAE,EAAE;gBACzD,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAA;YAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAC1B,CAAC;QAED,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACxE,uEAAuE;QACvE,oEAAoE;QACpE,yCAAyC;QACzC,KAAK,CAAC,OAAO,CAAC,QAAQ;YACpB,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,EAAE;YACxD,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAA;QAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAC1B,CAAC;IAED,iBAAiB;QACf,KAAK,MAAM,YAAY,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACpD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAA;QACnE,CAAC;IACH,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC1B,CAAC;CACF"}

package/dist/acp/AcpPermissionBridge.d.ts

@@ -0,0 +1,19 @@
+import type { AcpPermissionOutcome, AcpPermissionRequest } from './acpTypes.js';
+export interface AcpPermissionBridge {
+    requestPermission(request: AcpPermissionRequest): Promise<AcpPermissionOutcome>;
+    cancelOutstanding?(reason?: undefined | string): void;
+}
+export declare class FailClosedAcpPermissionBridge implements AcpPermissionBridge {
+    requestPermission(): Promise<AcpPermissionOutcome>;
+}
+export declare class DeterministicAcpPermissionBridge implements AcpPermissionBridge {
+    private readonly decision;
+    private cancelled;
+    constructor(decision?: AcpPermissionOutcome);
+    requestPermission(request: AcpPermissionRequest): Promise<AcpPermissionOutcome>;
+    cancelOutstanding(): void;
+}
+export declare function parsePermissionRequest(value: unknown): AcpPermissionRequest;
+export declare function handleAcpPermissionRequest(request: unknown, bridge?: AcpPermissionBridge): Promise<Record<string, unknown>>;
+export declare function cancelAcpPermissionBridge(bridge: AcpPermissionBridge, reason?: string): void;
+//# sourceMappingURL=AcpPermissionBridge.d.ts.map

package/dist/acp/AcpPermissionBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcpPermissionBridge.d.ts","sourceRoot":"","sources":["../../src/acp/AcpPermissionBridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAEpB,oBAAoB,EAGrB,MAAM,eAAe,CAAA;AAEtB,MAAM,WAAW,mBAAmB;IAClC,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAC/E,iBAAiB,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAAA;CACtD;AAED,qBAAa,6BAA8B,YAAW,mBAAmB;IACjE,iBAAiB,IAAI,OAAO,CAAC,oBAAoB,CAAC;CAGzD;AAED,qBAAa,gCAAiC,YAAW,mBAAmB;IAG9D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,SAAS,CAAQ;gBAEI,QAAQ,GAAE,oBAAyE;IAE1G,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAWrF,iBAAiB,IAAI,IAAI;CAG1B;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CA6B3E;AA6CD,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,mBAAyD,GAChE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKlC;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,SAA0B,GAAG,IAAI,CAI7G"}

package/dist/acp/AcpPermissionBridge.js

@@ -0,0 +1,110 @@
+export class FailClosedAcpPermissionBridge {
+    async requestPermission() {
+        return { outcome: 'cancelled' };
+    }
+}
+export class DeterministicAcpPermissionBridge {
+    decision;
+    cancelled = false;
+    constructor(decision = { outcome: 'selected', selectedOptionId: 'allow' }) {
+        this.decision = decision;
+    }
+    async requestPermission(request) {
+        if (this.cancelled)
+            return { outcome: 'cancelled' };
+        if (this.decision.outcome === 'selected') {
+            const requestedIds = new Set((request.options || []).map((option) => option.id));
+            if (requestedIds.size > 0 && !requestedIds.has(this.decision.selectedOptionId)) {
+                return { outcome: 'cancelled' };
+            }
+        }
+        return this.decision;
+    }
+    cancelOutstanding() {
+        this.cancelled = true;
+    }
+}
+export function parsePermissionRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const record = value;
+    const options = Array.isArray(record.options)
+        ? record.options
+            .filter((option) => !!option && typeof option === 'object' && !Array.isArray(option))
+            .map((option) => ({
+            id: typeof option.id === 'string'
+                ? option.id
+                : typeof option.optionId === 'string' ? option.optionId : '',
+            label: typeof option.label === 'string'
+                ? option.label
+                : typeof option.name === 'string' ? option.name : undefined,
+            description: typeof option.description === 'string' ? option.description : undefined,
+            ...(typeof option.kind === 'string' && OPTION_KINDS.has(option.kind)
+                ? { kind: option.kind }
+                : {}),
+        }))
+            .filter((option) => option.id)
+        : undefined;
+    return {
+        sessionId: typeof record.sessionId === 'string' ? record.sessionId : undefined,
+        prompt: typeof record.prompt === 'string' ? record.prompt : undefined,
+        options,
+        toolCall: parsePermissionToolCall(record.toolCall),
+        metadata: record.metadata && typeof record.metadata === 'object' && !Array.isArray(record.metadata)
+            ? record.metadata
+            : undefined,
+    };
+}
+const OPTION_KINDS = new Set([
+    'allow_once', 'allow_always', 'reject_once', 'reject_always',
+]);
+const TOOL_KINDS = new Set([
+    'read', 'edit', 'delete', 'move', 'search', 'execute', 'think', 'fetch', 'switch_mode', 'other',
+]);
+/**
+ * ACP requires `toolCall` on every permission request. It is the only thing
+ * that says WHAT is being permitted, so it is parsed defensively rather than
+ * trusted: an agent is untrusted input, and a malformed field must degrade to
+ * "unknown" instead of throwing inside the permission path — a parser that
+ * throws here would fail a permission request open or closed by accident
+ * rather than by decision.
+ */
+function parsePermissionToolCall(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const kind = typeof record.kind === 'string' && TOOL_KINDS.has(record.kind)
+        ? record.kind
+        : undefined;
+    const locations = Array.isArray(record.locations)
+        ? record.locations
+            .filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry))
+            .map((entry) => ({
+            path: typeof entry.path === 'string' ? entry.path : '',
+            ...(typeof entry.line === 'number' && Number.isFinite(entry.line) ? { line: entry.line } : {}),
+        }))
+            .filter((entry) => entry.path)
+        : undefined;
+    const toolCall = {
+        ...(typeof record.toolCallId === 'string' ? { toolCallId: record.toolCallId } : {}),
+        ...(typeof record.title === 'string' ? { title: record.title } : {}),
+        ...(kind ? { kind } : {}),
+        ...(locations && locations.length > 0 ? { locations } : {}),
+        ...(record.rawInput && typeof record.rawInput === 'object' && !Array.isArray(record.rawInput)
+            ? { rawInput: record.rawInput }
+            : {}),
+    };
+    return Object.keys(toolCall).length > 0 ? toolCall : undefined;
+}
+export async function handleAcpPermissionRequest(request, bridge = new FailClosedAcpPermissionBridge()) {
+    const outcome = await bridge.requestPermission(parsePermissionRequest(request));
+    return outcome.outcome === 'selected'
+        ? { outcome: { outcome: 'selected', optionId: outcome.selectedOptionId } }
+        : { outcome: { outcome: 'cancelled' } };
+}
+export function cancelAcpPermissionBridge(bridge, reason = 'ACP prompt cancelled.') {
+    if (bridge.cancelOutstanding) {
+        bridge.cancelOutstanding(reason);
+    }
+}
+//# sourceMappingURL=AcpPermissionBridge.js.map

package/dist/acp/AcpPermissionBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcpPermissionBridge.js","sourceRoot":"","sources":["../../src/acp/AcpPermissionBridge.ts"],"names":[],"mappings":"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"}

package/dist/acp/AcpPermissionPolicy.d.ts

@@ -0,0 +1,111 @@
+import type { AcpPermissionOption, AcpPermissionOutcome, AcpPermissionRequest, AcpToolKind } from './acpTypes.js';
+import type { AcpPermissionBridge } from './AcpPermissionBridge.js';
+/**
+ * CLIENT-SIDE PERMISSION POLICY (ADE spec §7 "one authority", §9 step 1).
+ *
+ * ACP's `allow_always` says "remember the choice" and carries NO scope — a
+ * `PermissionOption` has `optionId`, `name`, `kind` and nothing else. The
+ * protocol therefore cannot express "allow always for paths under X".
+ *
+ * That is not a gap, it is a relocation, and this file is where the relocation
+ * lands: in ACP the CLIENT answers, so the scope algebra belongs here. The user
+ * picks "always", WE record what "always" means, and we answer matching requests
+ * without asking again. The agent simply asks every time.
+ *
+ * Why that is better than the agent remembering (which is what the SDK-native
+ * lane does today): one policy engine serves every agent, ours and third-party,
+ * and the rules are inspectable and auditable in one place. An agent-held policy
+ * is per-agent, invisible to the host, and impossible to review across a fleet.
+ *
+ * ## Rules this file will not bend
+ *
+ * - **Deny wins.** A matching deny beats any matching allow, whatever the order.
+ * - **Every location must be covered.** A rule scoped to one directory must not
+ *   authorise a tool call that also touches a second, unrelated one.
+ * - **Never guess an option.** A stored `allow` is only actionable if the agent
+ *   actually offered an allow-kind option. If it did not, the decision degrades
+ *   to `ask` rather than picking something that looks plausible — selecting the
+ *   wrong option id here means granting the wrong thing.
+ * - **Unknown means ask.** No tool call, no kind, or no locations against a
+ *   path-scoped rule all resolve to `ask`, never to allow.
+ */
+export type AcpPermissionDecision = 'allow' | 'deny' | 'ask';
+export interface AcpPermissionRule {
+    id: string;
+    decision: 'allow' | 'deny';
+    /** Restrict to one class of operation. Omitted means any kind. */
+    kind?: undefined | AcpToolKind;
+    /**
+     * Restrict to a directory subtree. Omitted means the rule is UNSCOPED and
+     * applies regardless of path — deliberately representable, because "allow all
+     * `read`" is a legitimate choice, but callers should treat it as such.
+     */
+    pathPrefix?: undefined | string;
+    createdAt?: undefined | number;
+}
+export interface AcpPermissionPolicyStore {
+    list(): AcpPermissionRule[];
+    add(rule: AcpPermissionRule): void;
+}
+export declare class InMemoryAcpPermissionPolicyStore implements AcpPermissionPolicyStore {
+    private readonly rules;
+    constructor(initial?: AcpPermissionRule[]);
+    list(): AcpPermissionRule[];
+    add(rule: AcpPermissionRule): void;
+}
+/**
+ * Case- and separator-insensitive containment with a BOUNDARY check.
+ *
+ * `C:/repo` must not match `C:/repo-evil`. A bare `startsWith` says it does,
+ * and that is the classic way a scoped grant silently becomes a wider one.
+ */
+export declare function isWithinPathPrefix(path: string, prefix: string): boolean;
+export interface AcpPermissionPolicyEvaluation {
+    decision: AcpPermissionDecision;
+    ruleId?: undefined | string;
+}
+export declare function evaluateAcpPermissionPolicy(request: AcpPermissionRequest, rules: readonly AcpPermissionRule[]): AcpPermissionPolicyEvaluation;
+/**
+ * The option to select for a decision, or undefined when the agent offered
+ * nothing that means it. Undefined must escalate to a human — never a guess.
+ */
+export declare function selectOptionForDecision(options: readonly AcpPermissionOption[] | undefined, decision: 'allow' | 'deny'): AcpPermissionOption | undefined;
+/** Derives the rule to store when a user picks an `*_always` option. */
+export declare function ruleFromAlwaysChoice(request: AcpPermissionRequest, optionKind: string, id: string, now: number): AcpPermissionRule | undefined;
+export interface PolicyGatedAcpPermissionBridgeOptions {
+    store: AcpPermissionPolicyStore;
+    /** Consulted only when policy says `ask`. */
+    delegate: AcpPermissionBridge;
+    /** Reports every decision, so a silent auto-answer is still observable. */
+    onDecision?: undefined | ((event: AcpPermissionPolicyDecisionEvent) => void);
+    now?: undefined | (() => number);
+    newRuleId?: undefined | (() => string);
+}
+export interface AcpPermissionPolicyDecisionEvent {
+    decision: AcpPermissionDecision;
+    ruleId?: undefined | string;
+    source: 'policy' | 'user';
+    outcome: AcpPermissionOutcome;
+    /** Set when a decision could not be applied and had to escalate. */
+    escalationReason?: undefined | string;
+}
+/**
+ * Answers permission requests from stored policy, delegating anything the
+ * policy cannot decide.
+ *
+ * Note it never *reports* an allow it could not actually express: if the policy
+ * says allow and the agent offered no allow-kind option, the request escalates
+ * with a named reason rather than being answered.
+ */
+export declare class PolicyGatedAcpPermissionBridge implements AcpPermissionBridge {
+    private readonly store;
+    private readonly delegate;
+    private readonly onDecision;
+    private readonly now;
+    private readonly newRuleId;
+    private ruleCounter;
+    constructor(options: PolicyGatedAcpPermissionBridgeOptions);
+    requestPermission(request: AcpPermissionRequest): Promise<AcpPermissionOutcome>;
+    cancelOutstanding(reason?: undefined | string): void;
+}
+//# sourceMappingURL=AcpPermissionPolicy.d.ts.map

package/dist/acp/AcpPermissionPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcpPermissionPolicy.d.ts","sourceRoot":"","sources":["../../src/acp/AcpPermissionPolicy.ts"],"names":[],"mappings":"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"}