@provos/ironcurtain 0.10.0 → 0.11.0

package/dist/session/session-manager.d.ts

@@ -12,6 +12,24 @@
 import type { Session } from './types.js';
 import type { Transport } from './transport.js';
 import type { JobId } from '../cron/types.js';
+/**
+ * Minimal escalation data stored on a ManagedSession. Allows
+ * late-connecting clients (e.g. a new browser tab) to enumerate
+ * pending escalations without having received the original event.
+ */
+export interface PendingEscalationData {
+    readonly escalationId: string;
+    readonly sessionLabel: number;
+    readonly toolName: string;
+    readonly serverName: string;
+    readonly arguments: Record<string, unknown>;
+    readonly reason: string;
+    readonly context?: Record<string, string>;
+    readonly whitelistCandidates?: readonly {
+        readonly description: string;
+    }[];
+    readonly receivedAt: string;
+}
 /**
  * Source discriminant for managed sessions.
  * Determines cleanup behavior, notification routing, and
@@ -21,6 +39,8 @@ import type { JobId } from '../cron/types.js';
  *   Accepts follow-up messages via forwardToSession().
  * - 'cron': headless session created by the cron scheduler.
  *   Does NOT accept follow-up messages.
+ * - 'web': interactive session created via the web UI.
+ *   Always targeted by explicit label (no currentLabel focus).
  */
 export type SessionSource = {
     readonly kind: 'signal';
@@ -28,6 +48,9 @@ export type SessionSource = {
     readonly kind: 'cron';
     readonly jobId: JobId;
     readonly jobName: string;
+} | {
+    readonly kind: 'web';
+    readonly persona?: string;
 };
 /**
  * Unified managed session entry. Used for both Signal-initiated
@@ -43,7 +66,8 @@ export interface ManagedSession {
     readonly transport: Transport;
     readonly source: SessionSource;
     messageInFlight: boolean;
-    pendingEscalationId: string | null;
+    /** Full escalation data for late-connecting clients and expiry handling. */
+    pendingEscalation: PendingEscalationData | null;
     escalationResolving: boolean;
     /**
      * The promise returned by transport.run(). When set, SessionManager.end()
@@ -52,6 +76,10 @@ export interface ManagedSession {
      */
     runPromise: Promise<void> | null;
 }
+export interface EscalationResolutionResult {
+    readonly resolved: boolean;
+    readonly reason?: 'not_found' | 'already_resolving';
+}
 /**
  * Owns all managed session state. Both SignalBotDaemon and
  * CronScheduler delegate to this class for session registration,
@@ -59,8 +87,14 @@ export interface ManagedSession {
  *
  * Invariants:
  * - Labels are monotonically increasing integers starting at 1.
- * - At most one session exists per label.
+ * - At most one registered session exists per label.
  * - currentLabel is always either null or a valid label in the map.
+ *
+ * Label space is shared with workflow-owned agent sessions via
+ * `reserveLabel()` — those labels are live at the TokenStreamBridge
+ * but have no entry in this manager's `sessions` map. Code that
+ * iterates `sessions` or calls `end(label)` will silently skip them;
+ * their lifecycle is owned by the workflow orchestrator.
  */
 export declare class SessionManager {
     private sessions;
@@ -70,15 +104,23 @@ export declare class SessionManager {
      * When a Signal message arrives without an explicit #N prefix, it
      * is routed to this session.
      *
-     * Only updated by register() for Signal sessions. Cron sessions
-     * do not steal Signal focus.
+     * Only updated by register() for Signal sessions. Cron and web
+     * sessions do not steal Signal focus.
      */
     currentLabel: number | null;
+    /**
+     * Reserves a fresh label without registering a session. Exists so
+     * that non-managed sessions (workflow-owned agent sessions, which
+     * run without a Transport) can share the same label space as
+     * managed sessions. A single label authority avoids collisions in
+     * the TokenStreamBridge, which keys per-session state by label.
+     */
+    reserveLabel(): number;
     /**
      * Registers a new session and returns its assigned label.
      *
      * For Signal sessions: sets currentLabel to the new session.
-     * For cron sessions: currentLabel is NOT changed.
+     * For cron/web sessions: currentLabel is NOT changed.
      */
     register(session: Session, transport: Transport, source: SessionSource): number;
     /**
@@ -98,11 +140,24 @@ export declare class SessionManager {
     /** Returns the number of active sessions. */
     get size(): number;
     /** Records that a session has a pending escalation. */
-    setPendingEscalation(label: number, escalationId: string): void;
+    setPendingEscalation(label: number, escalation: PendingEscalationData | string): void;
     /** Clears a session's pending escalation. */
     clearPendingEscalation(label: number): void;
     /** Returns sessions that have pending escalations. */
     withPendingEscalation(): readonly ManagedSession[];
+    /** Finds a session by pending escalation ID. */
+    findByEscalation(escalationId: string): ManagedSession | undefined;
+    /**
+     * Resolves a pending escalation on any session. Encapsulates the
+     * escalationResolving guard, the resolveEscalation call, and the
+     * clearPendingEscalation cleanup.
+     *
+     * This is the single codepath for escalation resolution. All three
+     * transports (Signal, web, cron auto-deny) call through here.
+     */
+    resolveSessionEscalation(escalationId: string, decision: 'approved' | 'denied', options?: {
+        whitelistSelection?: number;
+    }): Promise<EscalationResolutionResult>;
     /**
      * Finds the most recently registered Signal session label.
      * Returns null if no Signal sessions exist.

package/dist/session/session-manager.js

@@ -17,8 +17,14 @@ import * as logger from '../logger.js';
  *
  * Invariants:
  * - Labels are monotonically increasing integers starting at 1.
- * - At most one session exists per label.
+ * - At most one registered session exists per label.
  * - currentLabel is always either null or a valid label in the map.
+ *
+ * Label space is shared with workflow-owned agent sessions via
+ * `reserveLabel()` — those labels are live at the TokenStreamBridge
+ * but have no entry in this manager's `sessions` map. Code that
+ * iterates `sessions` or calls `end(label)` will silently skip them;
+ * their lifecycle is owned by the workflow orchestrator.
  */
 export class SessionManager {
     sessions = new Map();
@@ -28,15 +34,25 @@ export class SessionManager {
      * When a Signal message arrives without an explicit #N prefix, it
      * is routed to this session.
      *
-     * Only updated by register() for Signal sessions. Cron sessions
-     * do not steal Signal focus.
+     * Only updated by register() for Signal sessions. Cron and web
+     * sessions do not steal Signal focus.
      */
     currentLabel = null;
+    /**
+     * Reserves a fresh label without registering a session. Exists so
+     * that non-managed sessions (workflow-owned agent sessions, which
+     * run without a Transport) can share the same label space as
+     * managed sessions. A single label authority avoids collisions in
+     * the TokenStreamBridge, which keys per-session state by label.
+     */
+    reserveLabel() {
+        return this.nextLabel++;
+    }
     /**
      * Registers a new session and returns its assigned label.
      *
      * For Signal sessions: sets currentLabel to the new session.
-     * For cron sessions: currentLabel is NOT changed.
+     * For cron/web sessions: currentLabel is NOT changed.
      */
     register(session, transport, source) {
         const label = this.nextLabel++;
@@ -46,7 +62,7 @@ export class SessionManager {
             transport,
             source,
             messageInFlight: false,
-            pendingEscalationId: null,
+            pendingEscalation: null,
             escalationResolving: false,
             runPromise: null,
         };
@@ -114,23 +130,69 @@ export class SessionManager {
         return this.sessions.size;
     }
     /** Records that a session has a pending escalation. */
-    setPendingEscalation(label, escalationId) {
+    setPendingEscalation(label, escalation) {
         const managed = this.sessions.get(label);
-        if (managed) {
-            managed.pendingEscalationId = escalationId;
+        if (!managed)
+            return;
+        if (typeof escalation === 'string') {
+            // Backward compat: Signal transport passes just the ID
+            managed.pendingEscalation = {
+                escalationId: escalation,
+                sessionLabel: label,
+                toolName: '',
+                serverName: '',
+                arguments: {},
+                reason: '',
+                receivedAt: new Date().toISOString(),
+            };
+        }
+        else {
+            managed.pendingEscalation = escalation;
         }
     }
     /** Clears a session's pending escalation. */
     clearPendingEscalation(label) {
         const managed = this.sessions.get(label);
         if (managed) {
-            managed.pendingEscalationId = null;
+            managed.pendingEscalation = null;
             managed.escalationResolving = false;
         }
     }
     /** Returns sessions that have pending escalations. */
     withPendingEscalation() {
-        return [...this.sessions.values()].filter((m) => m.pendingEscalationId !== null);
+        return [...this.sessions.values()].filter((m) => m.pendingEscalation !== null);
+    }
+    /** Finds a session by pending escalation ID. */
+    findByEscalation(escalationId) {
+        return [...this.sessions.values()].find((m) => m.pendingEscalation?.escalationId === escalationId);
+    }
+    /**
+     * Resolves a pending escalation on any session. Encapsulates the
+     * escalationResolving guard, the resolveEscalation call, and the
+     * clearPendingEscalation cleanup.
+     *
+     * This is the single codepath for escalation resolution. All three
+     * transports (Signal, web, cron auto-deny) call through here.
+     */
+    async resolveSessionEscalation(escalationId, decision, options) {
+        const managed = this.findByEscalation(escalationId);
+        if (!managed) {
+            return { resolved: false, reason: 'not_found' };
+        }
+        if (managed.escalationResolving) {
+            return { resolved: false, reason: 'already_resolving' };
+        }
+        managed.escalationResolving = true;
+        try {
+            await managed.session.resolveEscalation(escalationId, decision, options);
+            return { resolved: true };
+        }
+        finally {
+            managed.escalationResolving = false;
+            if (managed.pendingEscalation?.escalationId === escalationId) {
+                managed.pendingEscalation = null;
+            }
+        }
     }
     /**
      * Finds the most recently registered Signal session label.

package/dist/session/session-manager.js.map

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

package/dist/session/session-metadata.d.ts

@@ -6,13 +6,29 @@
  */
 import type { SessionMetadata } from './types.js';
 /**
- * Writes session metadata to disk. No-ops if the file already exists
- * (idempotent for edge cases like retried session creation).
+ * Writes session metadata to an explicit path. Primary API used by
+ * borrow-mode callers (e.g., workflow per-state dirs) that don't live
+ * under `{home}/sessions/{sessionId}/`.
+ *
+ * No-ops if the file already exists (idempotent for retried session
+ * creation). Uses `wx` flag to atomically fail on existence rather than
+ * stat-then-write (TOCTOU-safe).
+ */
+export declare function saveSessionMetadataTo(path: string, metadata: SessionMetadata): void;
+/**
+ * Writes session metadata for a session ID. Thin wrapper around
+ * `saveSessionMetadataTo` that derives the path from the session ID.
  */
 export declare function saveSessionMetadata(sessionId: string, metadata: SessionMetadata): void;
 /**
- * Reads session metadata from disk. Returns undefined if the file
- * is missing or contains invalid JSON (graceful for old sessions
- * created before metadata persistence was added).
+ * Reads session metadata from an explicit path. Used by callers (e.g. workflow
+ * per-state metadata under workflow-runs) that don't live under the standard
+ * sessions directory layout. Returns undefined for missing files or invalid JSON.
+ */
+export declare function loadSessionMetadataFromPath(path: string): SessionMetadata | undefined;
+/**
+ * Reads session metadata for a session ID. Thin wrapper that derives the path
+ * from the session ID. Graceful for old sessions created before metadata
+ * persistence was added.
  */
 export declare function loadSessionMetadata(sessionId: string): SessionMetadata | undefined;

package/dist/session/session-metadata.js

@@ -4,25 +4,39 @@
  * Written once when a session is created; read back on --resume so
  * the session continues with the same settings.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { getSessionMetadataPath } from '../config/paths.js';
 /**
- * Writes session metadata to disk. No-ops if the file already exists
- * (idempotent for edge cases like retried session creation).
+ * Writes session metadata to an explicit path. Primary API used by
+ * borrow-mode callers (e.g., workflow per-state dirs) that don't live
+ * under `{home}/sessions/{sessionId}/`.
+ *
+ * No-ops if the file already exists (idempotent for retried session
+ * creation). Uses `wx` flag to atomically fail on existence rather than
+ * stat-then-write (TOCTOU-safe).
+ */
+export function saveSessionMetadataTo(path, metadata) {
+    try {
+        writeFileSync(path, JSON.stringify(metadata, null, 2) + '\n', { flag: 'wx', encoding: 'utf-8' });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+}
+/**
+ * Writes session metadata for a session ID. Thin wrapper around
+ * `saveSessionMetadataTo` that derives the path from the session ID.
  */
 export function saveSessionMetadata(sessionId, metadata) {
-    const path = getSessionMetadataPath(sessionId);
-    if (existsSync(path))
-        return;
-    writeFileSync(path, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+    saveSessionMetadataTo(getSessionMetadataPath(sessionId), metadata);
 }
 /**
- * Reads session metadata from disk. Returns undefined if the file
- * is missing or contains invalid JSON (graceful for old sessions
- * created before metadata persistence was added).
+ * Reads session metadata from an explicit path. Used by callers (e.g. workflow
+ * per-state metadata under workflow-runs) that don't live under the standard
+ * sessions directory layout. Returns undefined for missing files or invalid JSON.
  */
-export function loadSessionMetadata(sessionId) {
-    const path = getSessionMetadataPath(sessionId);
+export function loadSessionMetadataFromPath(path) {
     try {
         const raw = readFileSync(path, 'utf-8');
         return JSON.parse(raw);
@@ -31,4 +45,12 @@ export function loadSessionMetadata(sessionId) {
         return undefined;
     }
 }
+/**
+ * Reads session metadata for a session ID. Thin wrapper that derives the path
+ * from the session ID. Graceful for old sessions created before metadata
+ * persistence was added.
+ */
+export function loadSessionMetadata(sessionId) {
+    return loadSessionMetadataFromPath(getSessionMetadataPath(sessionId));
+}
 //# sourceMappingURL=session-metadata.js.map

package/dist/session/session-metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-metadata.js","sourceRoot":"","sources":["../../src/session/session-metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAG5D;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,QAAyB;IAC9E,MAAM,IAAI,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC7B,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,MAAM,IAAI,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"session-metadata.js","sourceRoot":"","sources":["../../src/session/session-metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAG5D;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,QAAyB;IAC3E,IAAI,CAAC;QACH,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC;IAClE,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,QAAyB;IAC9E,qBAAqB,CAAC,sBAAsB,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,2BAA2B,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,CAAC;AACxE,CAAC"}