@qduc/term2 0.11.0 → 0.12.0

package/dist/services/session/post-execute-pause-capability.js

@@ -0,0 +1,27 @@
+import { createPostExecutePausePolicy } from './post-execute-pause-policy.js';
+/**
+ * Session-owned construction capability. It is deliberately supplied only to
+ * the root AgentClient: nested/subagent tool factories retain their existing
+ * behavior until a later slice gives them an explicit ownership model.
+ */
+export class PostExecutePauseCapability {
+    pending;
+    #activeRunId = null;
+    constructor(pending) {
+        this.pending = pending;
+    }
+    setActiveRunId(runId) {
+        this.#activeRunId = runId;
+    }
+    forTool(definition) {
+        if (!definition.postExecutePause)
+            return undefined;
+        return createPostExecutePausePolicy({
+            pending: this.pending,
+            runId: () => this.#activeRunId,
+            describe: definition.postExecutePause.describe,
+            resolve: definition.postExecutePause.resolve,
+        });
+    }
+}
+//# sourceMappingURL=post-execute-pause-capability.js.map

package/dist/services/session/post-execute-pause-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-execute-pause-capability.js","sourceRoot":"","sources":["../../../source/services/session/post-execute-pause-capability.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAG9E;;;;GAIG;AACH,MAAM,OAAO,0BAA0B;IAGhB,OAAO;IAF5B,YAAY,GAAkB,IAAI,CAAC;IAEnC,YAAqB,OAAmC;uBAAnC,OAAO;IAA+B,CAAC;IAE5D,cAAc,CAAC,KAAoB;QACjC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;IAC5B,CAAC;IAMD,OAAO,CAAC,UAA6B;QACnC,IAAI,CAAC,UAAU,CAAC,gBAAgB;YAAE,OAAO,SAAS,CAAC;QACnD,OAAO,4BAA4B,CAAC;YAClC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY;YAC9B,QAAQ,EAAE,UAAU,CAAC,gBAAgB,CAAC,QAAQ;YAC9C,OAAO,EAAE,UAAU,CAAC,gBAAgB,CAAC,OAAO;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/services/session/post-execute-pause-policy.d.ts

@@ -0,0 +1,20 @@
+import type { PostExecutePolicy } from '../../tools/types.js';
+import type { PostExecutePendingRegistry } from './post-execute-pending-registry.js';
+/**
+ * Turns the application-owned tool seam into a fail-closed gate. It intentionally
+ * does not know about SDK streams: holding this promise leaves the already-live
+ * SDK execution waiting at the tool boundary; an approval re-executes exactly
+ * once through the supplied non-recursive callback.
+ */
+export declare function createPostExecutePausePolicy<Params>(options: {
+    pending: PostExecutePendingRegistry;
+    /** A live run is created after tools are assembled, so production wiring may resolve lazily. */
+    runId: string | null | (() => string | null);
+    describe: (params: Params, result: unknown, details: unknown) => {
+        toolName: string;
+        argumentsText: string;
+        deniedRead?: import('../../contracts/conversation.js').DeniedReadMetadata;
+    } | null;
+    resolve?: (context: Parameters<PostExecutePolicy<Params>>[0], decision: import('../../contracts/conversation.js').PostExecuteDecision) => Promise<unknown> | unknown;
+}): PostExecutePolicy<Params>;
+//# sourceMappingURL=post-execute-pause-policy.d.ts.map

package/dist/services/session/post-execute-pause-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-execute-pause-policy.d.ts","sourceRoot":"","sources":["../../../source/services/session/post-execute-pause-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAErF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,EAAE;IAC5D,OAAO,EAAE,0BAA0B,CAAC;IACpC,gGAAgG;IAChG,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,QAAQ,EAAE,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,KACb;QACH,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,OAAO,iCAAiC,EAAE,kBAAkB,CAAC;KAC3E,GAAG,IAAI,CAAC;IACT,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,UAAU,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EACjD,QAAQ,EAAE,OAAO,iCAAiC,EAAE,mBAAmB,KACpE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACjC,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAuB5B"}

package/dist/services/session/post-execute-pause-policy.js

@@ -0,0 +1,34 @@
+import { asRecord, getCallIdFromObject } from '../interruption-info.js';
+/**
+ * Turns the application-owned tool seam into a fail-closed gate. It intentionally
+ * does not know about SDK streams: holding this promise leaves the already-live
+ * SDK execution waiting at the tool boundary; an approval re-executes exactly
+ * once through the supplied non-recursive callback.
+ */
+export function createPostExecutePausePolicy(options) {
+    return async (context) => {
+        const { params, result, details, executeAgain } = context;
+        const runId = typeof options.runId === 'function' ? options.runId() : options.runId;
+        const descriptor = options.describe(params, result, details);
+        if (!descriptor)
+            return result;
+        // A policy accidentally invoked outside an owned foreground run must not
+        // manufacture an unresumable gate. Let a custom resolver discard any
+        // call-scoped state using the same fail-closed rejection path as disposal.
+        if (!runId)
+            return options.resolve ? options.resolve(context, 'reject') : result;
+        const toolCallId = getCallIdFromObject(asRecord(details)?.toolCall);
+        if (!toolCallId) {
+            throw new Error('Post-execute approval requires an SDK tool call ID');
+        }
+        const decision = await options.pending.register({
+            runId,
+            toolCallId,
+            toolName: descriptor.toolName,
+            argumentsText: descriptor.argumentsText,
+            deniedRead: descriptor.deniedRead,
+        });
+        return options.resolve ? options.resolve(context, decision) : decision === 'approve' ? executeAgain() : result;
+    };
+}
+//# sourceMappingURL=post-execute-pause-policy.js.map

package/dist/services/session/post-execute-pause-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-execute-pause-policy.js","sourceRoot":"","sources":["../../../source/services/session/post-execute-pause-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAIxE;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAS,OAiBpD;IACC,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;QAC1D,MAAM,KAAK,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;QACpF,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU;YAAE,OAAO,MAAM,CAAC;QAC/B,yEAAyE;QACzE,qEAAqE;QACrE,2EAA2E;QAC3E,IAAI,CAAC,KAAK;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACjF,MAAM,UAAU,GAAG,mBAAmB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;QACpE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;YAC9C,KAAK;YACL,UAAU;YACV,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,aAAa,EAAE,UAAU,CAAC,aAAa;YACvC,UAAU,EAAE,UAAU,CAAC,UAAU;SAClC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACjH,CAAC,CAAC;AACJ,CAAC"}

package/dist/services/session/post-execute-pending-registry.d.ts

@@ -0,0 +1,63 @@
+import type { PostExecuteDecision } from '../../contracts/conversation.js';
+export type { PostExecuteDecision } from '../../contracts/conversation.js';
+export type PostExecutePendingEntry = {
+    /** Stable across UI re-renders; includes the session epoch and live run identity. */
+    id: string;
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    argumentsText: string;
+    deniedRead?: import('../../contracts/conversation.js').DeniedReadMetadata;
+};
+export type PostExecutePendingSnapshot = {
+    sessionId: string;
+    epoch: string | number;
+    /** Monotonic snapshot revision. Notifications are only a hint to re-read this. */
+    revision: number;
+    entries: readonly PostExecutePendingEntry[];
+    closed: boolean;
+};
+export type PostExecuteDecisionRequest = {
+    revision: number;
+    ids: readonly string[];
+    decision: PostExecuteDecision;
+};
+export type PostExecuteDecisionResult = {
+    kind: 'settled';
+    settledIds: readonly string[];
+} | {
+    kind: 'invalid';
+    reason: 'closed' | 'revision_mismatch' | 'empty_selection' | 'duplicate_id' | 'unknown_entry';
+};
+/**
+ * Session/epoch-owned post-execute gates.
+ *
+ * This deliberately has no notion of an SDK dispatch barrier: each snapshot is
+ * authoritative only for registrations visible at its revision. Callers must
+ * re-read after every wakeup. Decisions validate the complete selected set
+ * before settling any gate, so a stale or partial request cannot half-apply.
+ */
+export declare class PostExecutePendingRegistry {
+    #private;
+    constructor(options: {
+        sessionId: string;
+        epoch: string | number;
+    });
+    get version(): number;
+    snapshot(): PostExecutePendingSnapshot;
+    entriesForRun(runId: string): readonly PostExecutePendingEntry[];
+    /** Resolves after a later state change, or immediately if one was already observed. */
+    waitForChange(observedVersion: number): Promise<number>;
+    /** Cancellable subscription for consumers that race registry and local events. */
+    watchForChange(observedVersion: number): {
+        promise: Promise<number>;
+        unsubscribe: () => void;
+    };
+    register(input: Omit<PostExecutePendingEntry, 'id'>): Promise<PostExecuteDecision>;
+    decide(request: PostExecuteDecisionRequest): PostExecuteDecisionResult;
+    /** Fail closed: unblock every held tool before the session can be replaced. */
+    close(): void;
+    /** Fail closed for one terminal live run without closing its replacement session. */
+    closeRun(runId: string): void;
+}
+//# sourceMappingURL=post-execute-pending-registry.d.ts.map

package/dist/services/session/post-execute-pending-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-execute-pending-registry.d.ts","sourceRoot":"","sources":["../../../source/services/session/post-execute-pending-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,YAAY,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,MAAM,MAAM,uBAAuB,GAAG;IACpC,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,iCAAiC,EAAE,kBAAkB,CAAC;CAC3E,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC5C,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,mBAAmB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,cAAc,GAAG,eAAe,CAAA;CAAE,CAAC;AAOvH;;;;;;;GAOG;AACH,qBAAa,0BAA0B;;IAQrC,YAAY,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EAGjE;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,QAAQ,IAAI,0BAA0B,CAQrC;IAED,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,uBAAuB,EAAE,CAE/D;IAED,uFAAuF;IACvF,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGtD;IAED,kFAAkF;IAClF,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAAC,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE,CAkB7F;IAED,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,uBAAuB,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CASjF;IAED,MAAM,CAAC,OAAO,EAAE,0BAA0B,GAAG,yBAAyB,CAarE;IAED,+EAA+E;IAC/E,KAAK,IAAI,IAAI,CAOZ;IAED,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAM5B;CAQF"}

package/dist/services/session/post-execute-pending-registry.js

@@ -0,0 +1,123 @@
+/**
+ * Session/epoch-owned post-execute gates.
+ *
+ * This deliberately has no notion of an SDK dispatch barrier: each snapshot is
+ * authoritative only for registrations visible at its revision. Callers must
+ * re-read after every wakeup. Decisions validate the complete selected set
+ * before settling any gate, so a stale or partial request cannot half-apply.
+ */
+export class PostExecutePendingRegistry {
+    #sessionId;
+    #epoch;
+    #pending = new Map();
+    #waiters = new Set();
+    #revision = 0;
+    #closed = false;
+    constructor(options) {
+        this.#sessionId = options.sessionId;
+        this.#epoch = options.epoch;
+    }
+    get version() {
+        return this.#revision;
+    }
+    snapshot() {
+        return {
+            sessionId: this.#sessionId,
+            epoch: this.#epoch,
+            revision: this.#revision,
+            entries: [...this.#pending.values()].map(({ entry }) => ({ ...entry })),
+            closed: this.#closed,
+        };
+    }
+    entriesForRun(runId) {
+        return this.snapshot().entries.filter((entry) => entry.runId === runId);
+    }
+    /** Resolves after a later state change, or immediately if one was already observed. */
+    waitForChange(observedVersion) {
+        if (this.#revision !== observedVersion)
+            return Promise.resolve(this.#revision);
+        return new Promise((resolve) => this.#waiters.add(resolve));
+    }
+    /** Cancellable subscription for consumers that race registry and local events. */
+    watchForChange(observedVersion) {
+        if (this.#revision !== observedVersion) {
+            return { promise: Promise.resolve(this.#revision), unsubscribe: () => { } };
+        }
+        let active = true;
+        let resolveWaiter;
+        const promise = new Promise((resolve) => {
+            resolveWaiter = resolve;
+            this.#waiters.add(resolveWaiter);
+        });
+        return {
+            promise,
+            unsubscribe: () => {
+                if (!active)
+                    return;
+                active = false;
+                this.#waiters.delete(resolveWaiter);
+            },
+        };
+    }
+    register(input) {
+        if (this.#closed)
+            throw new Error('Post-execute pending registry is closed');
+        const id = `${this.#sessionId}:${this.#epoch}:${input.runId}:${input.toolCallId}`;
+        if (this.#pending.has(id))
+            throw new Error(`Duplicate active post-execute gate: ${id}`);
+        return new Promise((settle) => {
+            this.#pending.set(id, { entry: { ...input, id }, settle });
+            this.#changed();
+        });
+    }
+    decide(request) {
+        if (this.#closed)
+            return { kind: 'invalid', reason: 'closed' };
+        if (request.revision !== this.#revision)
+            return { kind: 'invalid', reason: 'revision_mismatch' };
+        if (request.ids.length === 0)
+            return { kind: 'invalid', reason: 'empty_selection' };
+        const ids = [...request.ids];
+        if (new Set(ids).size !== ids.length)
+            return { kind: 'invalid', reason: 'duplicate_id' };
+        if (ids.some((id) => !this.#pending.has(id)))
+            return { kind: 'invalid', reason: 'unknown_entry' };
+        const selected = ids.map((id) => this.#pending.get(id));
+        for (const id of ids)
+            this.#pending.delete(id);
+        this.#changed();
+        for (const pending of selected)
+            pending.settle(request.decision);
+        return { kind: 'settled', settledIds: ids };
+    }
+    /** Fail closed: unblock every held tool before the session can be replaced. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const pending = [...this.#pending.values()];
+        this.#pending.clear();
+        this.#changed();
+        for (const gate of pending)
+            gate.settle('reject');
+    }
+    /** Fail closed for one terminal live run without closing its replacement session. */
+    closeRun(runId) {
+        const pending = [...this.#pending.entries()].filter(([, gate]) => gate.entry.runId === runId);
+        if (pending.length === 0)
+            return;
+        for (const [id] of pending)
+            this.#pending.delete(id);
+        this.#changed();
+        for (const [, gate] of pending)
+            gate.settle('reject');
+    }
+    #changed() {
+        this.#revision += 1;
+        const waiters = [...this.#waiters];
+        this.#waiters.clear();
+        for (const wake of waiters)
+            wake(this.#revision);
+    }
+}
+//# sourceMappingURL=post-execute-pending-registry.js.map

package/dist/services/session/post-execute-pending-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-execute-pending-registry.js","sourceRoot":"","sources":["../../../source/services/session/post-execute-pending-registry.ts"],"names":[],"mappings":"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"}

package/dist/services/session/session-access-state.d.ts

@@ -0,0 +1,24 @@
+import type { ISettingsService } from '../service-interfaces.js';
+export type DockerHostControlGrant = 'once' | 'session' | 'project';
+/** Session-bound read and Docker state; project Docker grants stay in settings. */
+export declare class SessionAccessState {
+    #private;
+    private readonly settings;
+    constructor(settings: ISettingsService);
+    allowReadFolder(folder: string): void;
+    allowsRead(targetPath: string, baseDir?: string): boolean;
+    allowEditFile(file: string, baseDir?: string): void;
+    allowEditFolder(folder: string, baseDir?: string): void;
+    allowsEdit(targetPath: string, baseDir?: string): boolean;
+    requiresDockerApproval(command: string): boolean;
+    grantDocker(command: string, cwd: string, scope: DockerHostControlGrant): void;
+    hasDockerGrant(command: string, cwd: string): boolean;
+    hasDockerSessionGrant(cwd: string): boolean;
+    hasDockerProject(cwd: string): boolean;
+    recordDockerDenial(command: string): void;
+    consumeDockerDenial(command: string): boolean;
+    /** Clears state that must not survive a reset or imported conversation. */
+    clearTransient(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=session-access-state.d.ts.map

package/dist/services/session/session-access-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-access-state.d.ts","sourceRoot":"","sources":["../../../source/services/session/session-access-state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpE,mFAAmF;AACnF,qBAAa,kBAAkB;;IAQjB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAArC,YAA6B,QAAQ,EAAE,gBAAgB,EAAI;IAE3D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEpC;IAED,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,OAAO,CAMvE;IAED,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,IAAI,CAEjE;IAED,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,IAAI,CAErE;IAED,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,OAAO,CAMvE;IAED,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/C;IAED,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAI7E;IAED,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;IAED,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1C;IAED,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErC;IAED,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAExC;IAED,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE5C;IAED,2EAA2E;IAC3E,cAAc,IAAI,IAAI,CAOrB;IAED,OAAO,IAAI,IAAI,CAEd;CAOF"}

package/dist/services/session/session-access-state.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { requestsDockerHostControl } from '../../utils/shell/sandbox/docker-host-control.js';
+/** Session-bound read and Docker state; project Docker grants stay in settings. */
+export class SessionAccessState {
+    settings;
+    #readFolders = new Set();
+    #editFiles = new Set();
+    #editFolders = new Set();
+    #dockerOnce = new Set();
+    #dockerRoots = new Set();
+    #dockerDenials = new Set();
+    constructor(settings) {
+        this.settings = settings;
+    }
+    allowReadFolder(folder) {
+        this.#readFolders.add(folder);
+    }
+    allowsRead(targetPath, baseDir = process.cwd()) {
+        const target = path.resolve(baseDir, targetPath);
+        return [...this.#readFolders].some((folder) => {
+            const resolvedFolder = path.resolve(baseDir, folder);
+            return target === resolvedFolder || target.startsWith(`${resolvedFolder}${path.sep}`);
+        });
+    }
+    allowEditFile(file, baseDir = process.cwd()) {
+        this.#editFiles.add(path.resolve(baseDir, file));
+    }
+    allowEditFolder(folder, baseDir = process.cwd()) {
+        this.#editFolders.add(path.resolve(baseDir, folder));
+    }
+    allowsEdit(targetPath, baseDir = process.cwd()) {
+        const target = path.resolve(baseDir, targetPath);
+        return (this.#editFiles.has(target) ||
+            [...this.#editFolders].some((folder) => target === folder || target.startsWith(`${folder}${path.sep}`)));
+    }
+    requiresDockerApproval(command) {
+        return requestsDockerHostControl(command) || this.#dockerDenials.has(command);
+    }
+    grantDocker(command, cwd, scope) {
+        if (scope === 'once')
+            this.#dockerOnce.add(command);
+        if (scope === 'session')
+            this.#dockerRoots.add(realRoot(cwd));
+        if (scope === 'project')
+            this.#grantDockerProject(cwd);
+    }
+    hasDockerGrant(command, cwd) {
+        return this.hasDockerProject(cwd) || this.#dockerRoots.has(realRoot(cwd)) || this.#dockerOnce.delete(command);
+    }
+    hasDockerSessionGrant(cwd) {
+        return this.#dockerRoots.has(realRoot(cwd));
+    }
+    hasDockerProject(cwd) {
+        return (this.settings.get('sandbox.dockerHostControlProjects') ?? []).includes(realRoot(cwd));
+    }
+    recordDockerDenial(command) {
+        this.#dockerDenials.add(command);
+    }
+    consumeDockerDenial(command) {
+        return this.#dockerDenials.delete(command);
+    }
+    /** Clears state that must not survive a reset or imported conversation. */
+    clearTransient() {
+        this.#readFolders.clear();
+        this.#editFiles.clear();
+        this.#editFolders.clear();
+        this.#dockerOnce.clear();
+        this.#dockerRoots.clear();
+        this.#dockerDenials.clear();
+    }
+    dispose() {
+        this.clearTransient();
+    }
+    #grantDockerProject(cwd) {
+        const root = realRoot(cwd);
+        const projects = this.settings.get('sandbox.dockerHostControlProjects') ?? [];
+        if (!projects.includes(root))
+            this.settings.set('sandbox.dockerHostControlProjects', [...projects, root]);
+    }
+}
+const realRoot = (cwd) => {
+    const resolved = path.resolve(cwd);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+};
+//# sourceMappingURL=session-access-state.js.map

package/dist/services/session/session-access-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-access-state.js","sourceRoot":"","sources":["../../../source/services/session/session-access-state.ts"],"names":[],"mappings":"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"}

package/dist/services/session/session-client-factory.d.ts

@@ -0,0 +1,61 @@
+import type { ConversationAgentClient } from '../conversation-agent-client.js';
+import type { ContinuationProjectionMode } from '../../lib/continuation-projection-mode.js';
+import { ToolOwnershipRegistry } from '../approval/tool-ownership-registry.js';
+import { PostExecutePendingRegistry } from './post-execute-pending-registry.js';
+import { PostExecutePauseCapability } from './post-execute-pause-capability.js';
+import { SessionAccessState } from './session-access-state.js';
+import type { ISettingsService } from '../service-interfaces.js';
+import { ProviderContinuity } from '../provider-continuity.js';
+import { OpenAICandidateObserver } from '../openai-candidate-observer.js';
+import { type OpenAIRootFreshTurnSelectorParityObserver } from '../openai-root-selector-parity-observer.js';
+import { type OpenAIRootCheckpointLifecycleObserver } from '../openai-root-checkpoint-lifecycle-observer.js';
+import type { HookLifecyclePort } from '../hooks/hook-service.js';
+import { HookEventFactory } from '../hooks/hook-event-factory.js';
+import type { ToolExecutionLifecyclePort } from '../../tools/types.js';
+import { BackgroundShellRegistry } from '../shell/background-shell-registry.js';
+import type { BackgroundShellExecutionResult } from '../../tools/system/shell.js';
+/** A client whose lifetime is owned by the session that requested it. */
+export type SessionClientHandle = {
+    readonly agentClient: ConversationAgentClient;
+    /** The sole continuity instance shared by this handle's root client and runtime. */
+    readonly providerContinuity?: ProviderContinuity;
+    /** Present only for an owned root session handle. */
+    readonly openAIRootFreshTurnSelectorParityObserver?: OpenAIRootFreshTurnSelectorParityObserver;
+    /** Present only for an owned root OpenAI session handle. */
+    readonly openAIRootCheckpointLifecycleObserver?: OpenAIRootCheckpointLifecycleObserver;
+    /** Compatibility selection fixed when this handle's client was created. */
+    readonly continuationProjectionMode: ContinuationProjectionMode;
+    readonly toolOwnership: ToolOwnershipRegistry;
+    readonly access?: SessionAccessState;
+    readonly postExecutePending?: PostExecutePendingRegistry;
+    readonly postExecutePauseCapability?: PostExecutePauseCapability;
+    readonly hookLifecycle?: HookLifecyclePort;
+    readonly hookEvents?: HookEventFactory;
+    readonly toolLifecycle?: ToolExecutionLifecyclePort;
+    /** Present only for an owned root session handle. */
+    readonly backgroundShellRegistry?: BackgroundShellRegistry<BackgroundShellExecutionResult>;
+    /** Idempotently release resources captured by this session's client. */
+    dispose(): void;
+};
+/** Creates the closure-bound client for one conversation session. */
+export type SessionClientFactory = {
+    create(sessionId: string, options?: {
+        allowBackgroundShell?: boolean;
+    }): SessionClientHandle;
+};
+type DisposableConversationAgentClient = ConversationAgentClient & {
+    dispose?: () => void;
+};
+/**
+ * Makes a factory for production clients. Each handle owns exactly the client
+ * it creates, so replacement sessions cannot retain a prior closure-bound
+ * client or its subscriptions.
+ */
+export declare function createOwnedSessionClientFactory(settings: ISettingsService, createClient: (sessionId: string, toolOwnership: ToolOwnershipRegistry, postExecutePauseCapability: PostExecutePauseCapability, access: SessionAccessState, continuationProjectionMode: ContinuationProjectionMode, providerContinuity: ProviderContinuity, requestCapture: OpenAICandidateObserver, toolLifecycle?: ToolExecutionLifecyclePort, backgroundShellRegistry?: BackgroundShellRegistry<BackgroundShellExecutionResult>, allowBackgroundShell?: boolean) => DisposableConversationAgentClient, hookLifecycle?: HookLifecyclePort): SessionClientFactory;
+/**
+ * Compatibility seam for callers that provide a prebuilt client. Its owner
+ * remains responsible for disposal, including across ConversationService reset.
+ */
+export declare function createCallerOwnedSessionClientFactory(agentClient: ConversationAgentClient, toolOwnership: ToolOwnershipRegistry): SessionClientFactory;
+export {};
+//# sourceMappingURL=session-client-factory.d.ts.map

package/dist/services/session/session-client-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-client-factory.d.ts","sourceRoot":"","sources":["../../../source/services/session/session-client-factory.ts"],"names":[],"mappings":"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"}

package/dist/services/session/session-client-factory.js

@@ -0,0 +1,103 @@
+import { ToolOwnershipRegistry } from '../approval/tool-ownership-registry.js';
+import { PostExecutePendingRegistry } from './post-execute-pending-registry.js';
+import { PostExecutePauseCapability } from './post-execute-pause-capability.js';
+import { SessionAccessState } from './session-access-state.js';
+import { ProviderContinuity } from '../provider-continuity.js';
+import { OpenAICandidateObserver } from '../openai-candidate-observer.js';
+import { ProviderContinuityOpenAIRootSelectorParityObserver, } from '../openai-root-selector-parity-observer.js';
+import { DefaultOpenAIRootCheckpointLifecycleObserver, } from '../openai-root-checkpoint-lifecycle-observer.js';
+import { OpenAIRootProviderIdentity } from '../openai-root-provider-identity.js';
+import { HookEventFactory } from '../hooks/hook-event-factory.js';
+import { createToolExecutionLifecyclePort } from '../hooks/hook-tool-lifecycle.js';
+import { BackgroundShellRegistry } from '../shell/background-shell-registry.js';
+/**
+ * Makes a factory for production clients. Each handle owns exactly the client
+ * it creates, so replacement sessions cannot retain a prior closure-bound
+ * client or its subscriptions.
+ */
+export function createOwnedSessionClientFactory(settings, createClient, hookLifecycle) {
+    return {
+        create(sessionId, options) {
+            const continuationProjectionMode = settings.get('agent.provider') === 'openai' ? 'openai-provider' : 'legacy';
+            const toolOwnership = new ToolOwnershipRegistry();
+            const access = new SessionAccessState(settings);
+            const postExecutePending = new PostExecutePendingRegistry({ sessionId, epoch: crypto.randomUUID() });
+            const postExecutePauseCapability = new PostExecutePauseCapability(postExecutePending);
+            const providerContinuity = new ProviderContinuity();
+            const openAIRootCheckpointLifecycleObserver = continuationProjectionMode === 'openai-provider'
+                ? new DefaultOpenAIRootCheckpointLifecycleObserver()
+                : undefined;
+            const openAIRootProviderIdentity = new OpenAIRootProviderIdentity();
+            const requestCapture = new OpenAICandidateObserver(providerContinuity, openAIRootCheckpointLifecycleObserver, openAIRootProviderIdentity);
+            const hookEvents = hookLifecycle
+                ? new HookEventFactory({
+                    sessionId,
+                    includeUserText: settings.getDynamic('hooks.includeUserText') === true,
+                    includeToolArguments: settings.getDynamic('hooks.includeToolArguments') === true,
+                    includeToolResults: settings.getDynamic('hooks.includeToolResults') === true,
+                })
+                : undefined;
+            const toolLifecycle = hookLifecycle && hookEvents ? createToolExecutionLifecyclePort(hookLifecycle, hookEvents) : undefined;
+            const allowBackgroundShell = options?.allowBackgroundShell !== false;
+            const backgroundShellRegistry = allowBackgroundShell
+                ? new BackgroundShellRegistry()
+                : undefined;
+            const openAIRootFreshTurnSelectorParityObserver = continuationProjectionMode === 'openai-provider'
+                ? new ProviderContinuityOpenAIRootSelectorParityObserver(providerContinuity, () => settings.get('agent.model'), undefined, () => openAIRootProviderIdentity.current)
+                : undefined;
+            const agentClient = createClient(sessionId, toolOwnership, postExecutePauseCapability, access, continuationProjectionMode, providerContinuity, requestCapture, toolLifecycle, backgroundShellRegistry, allowBackgroundShell);
+            let disposed = false;
+            return {
+                agentClient,
+                providerContinuity,
+                openAIRootFreshTurnSelectorParityObserver,
+                openAIRootCheckpointLifecycleObserver,
+                continuationProjectionMode,
+                toolOwnership,
+                access,
+                postExecutePending,
+                postExecutePauseCapability,
+                hookLifecycle,
+                hookEvents,
+                toolLifecycle,
+                backgroundShellRegistry,
+                dispose() {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    agentClient.dispose?.();
+                    void backgroundShellRegistry?.dispose();
+                    postExecutePauseCapability.setActiveRunId(null);
+                    postExecutePending.close();
+                    toolOwnership.clear();
+                    access.dispose();
+                },
+            };
+        },
+    };
+}
+/**
+ * Compatibility seam for callers that provide a prebuilt client. Its owner
+ * remains responsible for disposal, including across ConversationService reset.
+ */
+export function createCallerOwnedSessionClientFactory(agentClient, toolOwnership) {
+    return {
+        create() {
+            const providerContinuity = new ProviderContinuity();
+            const postExecutePending = new PostExecutePendingRegistry({
+                sessionId: 'caller-owned',
+                epoch: crypto.randomUUID(),
+            });
+            return {
+                agentClient,
+                providerContinuity,
+                continuationProjectionMode: 'legacy',
+                toolOwnership,
+                postExecutePending,
+                postExecutePauseCapability: new PostExecutePauseCapability(postExecutePending),
+                dispose: () => { },
+            };
+        },
+    };
+}
+//# sourceMappingURL=session-client-factory.js.map

package/dist/services/session/session-client-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-client-factory.js","sourceRoot":"","sources":["../../../source/services/session/session-client-factory.ts"],"names":[],"mappings":"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"}