@jini-ai/daemon 0.6.15-rc.2 → 0.6.16

package/dist/store/agent-sessions/sql.js

@@ -13,6 +13,12 @@ export function validateSessionKernel({ kernel, dialect, transports }) {
 function runSessionQuery(kernel, body) {
     return kernel.run(db => body(db));
 }
+/** The one atomic upsert behind `setSessionId`: insert the pair, or replace its session id and time. */
+function upsertSessionQuery({ conversationId, agentId, sessionId, updatedAt }) {
+    return (db) => db.insertInto('assistant_agent_sessions')
+        .values({ conversation_id: conversationId, agent_id: agentId, session_id: sessionId, updated_at: updatedAt })
+        .onConflict(oc => oc.columns(['conversation_id', 'agent_id']).doUpdateSet({ session_id: sessionId, updated_at: updatedAt })).execute();
+}
 /** Translate opaque driver failures without losing their cause or mutating host state. */
 async function atSessionBoundary(operation) {
     try {
@@ -43,9 +49,7 @@ export function createSqlAgentSessionStore({ kernel }, { clock = createSystemClo
         setSessionId({ conversationId, agentId, sessionId }) {
             return atSessionBoundary(async () => {
                 const updatedAt = clock.nowMs();
-                await runSessionQuery(kernel, db => db.insertInto('assistant_agent_sessions')
-                    .values({ conversation_id: conversationId, agent_id: agentId, session_id: sessionId, updated_at: updatedAt })
-                    .onConflict(oc => oc.columns(['conversation_id', 'agent_id']).doUpdateSet({ session_id: sessionId, updated_at: updatedAt })).execute());
+                await runSessionQuery(kernel, upsertSessionQuery({ conversationId, agentId, sessionId, updatedAt }));
             });
         },
         clearSessionId({ conversationId, agentId }) {

package/dist/store/event-log/sqlite-kernel.js

@@ -1,4 +1,5 @@
 /** Async SQLite execution over the host kernel; event-log policy lives in sqlite-policy. */
+import { loadOptionalPeer } from '@jini-ai/core/optional-peer';
 import { createSystemClock } from '@jini-ai/core/primitives';
 import { SQLITE_EVENT_LOG_SCHEMA, resolveMaxEntriesPerRun, assertValidReplayCursor, existingAppendResult, replayResult, rowToEntry, } from './sqlite-policy.js';
 /**
@@ -57,7 +58,7 @@ export async function createKernelSqliteEventLog(required, optional = {}) {
 async function setupSchema({ db }, options = {}) {
     if (options.schemaSetup !== 'host') {
         // Keep the existing synchronous factory free of a new eager peer import.
-        const { sql } = await import('kysely');
+        const { sql } = await loadOptionalPeer({ feature: 'SQL storage adapters', dependency: 'kysely', load: () => import('kysely') });
         // Kysely executes one statement at a time; the owner DDL contains no embedded semicolons.
         for (const statement of SQLITE_EVENT_LOG_SCHEMA.split(';').filter(part => part.trim())) {
             await sql.raw(statement).execute(db);
@@ -129,7 +130,11 @@ async function replayInKernel({ db, runId, afterCursor }) {
     const result = replayResult({ run: { run_id: runId, next_cursor: first.next_cursor }, oldest, afterCursor });
     if (result.kind !== 'ok')
         return result;
-    const entries = rows.flatMap(({ cursor, event, data, recorded_at }) => cursor === null || event === null || data === null || recorded_at === null ? [] : [rowToEntry({ cursor, event, data, recorded_at })]);
+    // A row missing any event column carries no entry.
+    const entries = rows.flatMap(({ cursor, event, data, recorded_at }) => {
+        const missing = cursor === null || event === null;
+        return missing || data === null || recorded_at === null ? [] : [rowToEntry({ cursor, event, data, recorded_at })];
+    });
     return { ...result, entries };
 }
 //# sourceMappingURL=sqlite-kernel.js.map

package/dist/store/event-log/sqlite.js

@@ -58,8 +58,12 @@ export function openSqliteEventLog(input, options = {}) {
             } }, { pragmas: ['journal_mode = WAL'] });
         const log = bindSqliteEventLog(db, options);
         let closed = false;
-        return { ...log, async close(_args) { if (closed)
-                return; closed = true; db.close(); } };
+        return { ...log, async close(_args) {
+                if (closed)
+                    return;
+                closed = true;
+                db.close();
+            } };
     }
     catch (error) {
         try {

package/dist/surface-exchanges.js

@@ -143,9 +143,9 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
             // Unknown and closed are the same situation to a human whose dialog is no longer waiting.
             if (!entry)
                 return { ok: false, reason: 'unknown-or-closed' };
-            if ((spec.toolId !== undefined && entry.binding.toolId !== spec.toolId)
-                || (entry.binding.channel ?? deps.defaultChannel) !== (spec.channel ?? deps.defaultChannel)
-                || entry.binding.principalId !== spec.principalId) {
+            const toolMismatch = spec.toolId !== undefined && entry.binding.toolId !== spec.toolId;
+            const channelMismatch = (entry.binding.channel ?? deps.defaultChannel) !== (spec.channel ?? deps.defaultChannel);
+            if (toolMismatch || channelMismatch || entry.binding.principalId !== spec.principalId) {
                 // A wrong-binding delivery must not consume a conversation the right human is still having.
                 return { ok: false, reason: 'binding-mismatch' };
             }

package/dist/terminal-session.d.ts

@@ -1,3 +1,50 @@
+/**
+ * @module terminal-session
+ *
+ * Interactive-terminal session manager: the `@jini-ai/daemon`-side wiring for
+ * OD's `apps/daemon/src/terminals.ts` + `apps/daemon/src/routes/terminal.ts`
+ * (see `ADS-memory/reports/proposals/PROP-http-route-packs-terminal-pty-2026-07-21.md`
+ * for the full design discussion this module implements a specific decision
+ * from). The generic ring-buffer/coalescing/SSE-agnostic session engine
+ * already exists as `@jini-ai/platform`'s `terminal.ts` (ported 2026-07-18,
+ * before this task) — this module does **not** reimplement that. It adds
+ * exactly the three things that engine deliberately left to a caller:
+ *
+ * 1. **A host-injected `PtySpawn` or `TerminalService`.** The native adapter
+ *    lives exclusively at `@jini-ai/daemon/terminal`; this default-entry
+ *    session manager never imports it. The host opts in by supplying
+ *    `loadSpawnPty: () => loadRealSpawnPty({})` from that subpath.
+ *
+ * 2. **Session-token gating.** The proposal's blocker was that a
+ *    *session-scoped* dangerous capability (once a shell is spawned, every
+ *    subsequent `stdin` write is arbitrary unaudited input for the
+ *    session's lifetime) does not fit `ToolExecutor`'s call-scoped shape.
+ *    The resolved design: `ToolExecutor.execute('terminal.create', ...)`
+ *    (via {@link createTerminalToolRegistrations}) is the one full
+ *    deny-by-default gated call — it authorizes *creating* a session.
+ *    Every subsequent `write`/`resize`/`kill`/`attach` call against that
+ *    session id is validated by a lighter, still-explicit check: this
+ *    module records which `Principal` created each session at `create()`
+ *    time, and every later call verifies the calling principal matches,
+ *    denying (as a `'not-found'` result, never a distinguishable "forbidden"
+ *    — see {@link checkOwnership}'s doc for why) otherwise. This is not
+ *    "the session id is unguessable therefore secure" — it is a real,
+ *    per-call identity check, independent of how hard the id is to guess.
+ *
+ * 3. **The kill/stdin/resize race fix.** OD's origin (and `@jini-ai/platform`'s
+ *    faithful port of it) has no lock between a `kill` and a concurrent
+ *    `write`/`resize` on the same session id: `kill()` only *requests* the
+ *    real OS process die (sends `SIGTERM`) — the session's `status` does not
+ *    flip to `'exited'` until the pty's own `onExit` callback fires,
+ *    asynchronously, once the real process actually dies. A `write`/`resize`
+ *    processed in that window still observes `status: 'running'` and still
+ *    reaches the real pty. This module closes that window with its own
+ *    immediate, lock-protected `killed` flag (see {@link runExclusive} and
+ *    the `write`/`resize`/`kill` implementations below): once a `kill` call
+ *    has run its own critical section, any `write`/`resize` queued behind it
+ *    for the same session id sees `killed: true` and is rejected — it never
+ *    depends on the real process having actually exited yet.
+ */
 import type { Principal, ToolPolicy, ToolRegistration } from '@jini-ai/core';
 import { type PtySpawn, type TerminalService, type TerminalSseSink } from '@jini-ai/platform';
 export type { TerminalSseSink } from '@jini-ai/platform';
@@ -13,24 +60,6 @@ export declare const TERMINAL_CREATE_TOOL_ID = "terminal.create";
  * merely by registering the tool.
  */
 export declare const denyAllTerminalCreatePolicy: ToolPolicy;
-/**
- * The real, `node-pty`-backed {@link PtySpawn}. Dynamically imports
- * `node-pty` (mirroring OD's origin `await import('node-pty')`, not a
- * static top-level import) so a host process whose platform/environment
- * lacks a usable `node-pty` addon can still boot — only an actual
- * `terminal.create` call fails, cleanly, rather than crashing at
- * module-eval time. Before the first spawn, repairs `node-pty`'s bundled
- * `spawn-helper` binary's executable bit (pnpm unpacks it non-executable —
- * see `@jini-ai/platform`'s `terminal.ts` module doc for the full story) via
- * that package's own `spawnHelperCandidatePaths`/`ensureSpawnHelperExecutable`,
- * but with the resolver anchored at **this** module
- * (`createRequire(import.meta.url)` here, not `@jini-ai/platform`'s own
- * default): `@jini-ai/platform` deliberately does not depend on `node-pty`, so
- * its default `require.resolve('node-pty')` would not find the copy this
- * package (`@jini-ai/daemon`) actually declares — this is exactly the
- * resolver injection seam `spawnHelperCandidatePaths` was built for.
- */
-export declare function loadRealSpawnPty(_requiredArgs: Record<string, never>): Promise<PtySpawn>;
 /** The public, principal-neutral session snapshot this module exposes — deliberately its own shape rather than re-exporting `@jini-ai/platform`'s `TerminalSession` verbatim, since that type carries an OD-shaped per-session grouping key (see `@jini-ai/platform`'s `terminal.ts`) this module replaces entirely with the caller-supplied `resourceRef` (see {@link CreateTerminalSessionOptions}), tracked only in this module's own metadata and never forwarded to `@jini-ai/platform` at all — this package's own identifier-neutrality lint (`__tests__/identifier-lint.test.ts`) forbids that origin field's exact name from appearing anywhere in this package's source. */
 export interface TerminalSessionInfo {
     readonly id: string;
@@ -129,9 +158,9 @@ export interface TerminalSessionManager {
     }): Promise<void>;
 }
 export interface CreateTerminalSessionManagerOptions {
-    /** Injected for tests (a fake session manager without a real pty) or an alternate host wiring. @default a fresh `@jini-ai/platform` `TerminalService` backed by {@link loadRealSpawnPty}. */
+    /** Host-owned session service. Otherwise a fresh platform service uses the injected `loadSpawnPty`. */
     readonly terminalService?: TerminalService;
-    /** @default {@link loadRealSpawnPty} */
+    /** Host-owned PTY loader, e.g. `() => loadRealSpawnPty({})` from `@jini-ai/daemon/terminal`. Required for creation unless `terminalService` is supplied. */
     readonly loadSpawnPty?: () => Promise<PtySpawn>;
     readonly maxEvents?: number;
     readonly maxBufferBytes?: number;
@@ -146,6 +175,8 @@ export interface CreateTerminalSessionManagerOptions {
  * around a `@jini-ai/platform` `TerminalService` adding session ownership,
  * the kill/write/resize lock, and (via {@link createTerminalToolRegistrations})
  * `ToolExecutor` gating for creation. See module doc for the full design.
+ * Without a host-owned service or loader, boot is inert and `create()` rejects
+ * with injection guidance. Wrapper setup is O(1); session work stays in the platform service.
  */
 export declare function createTerminalSessionManager(_requiredArgs: Record<string, never>, options?: Pick<CreateTerminalSessionManagerOptions, "terminalService" | "loadSpawnPty" | "maxEvents" | "maxBufferBytes" | "exitTailBytes" | "flushIntervalMs" | "flushThresholdBytes" | "ttlMs" | "shutdownGraceMs">): TerminalSessionManager;
 export interface CreateTerminalToolRegistrationsOptions {

package/dist/terminal-session.js

@@ -1,54 +1,4 @@
-/**
- * @module terminal-session
- *
- * Interactive-terminal session manager: the `@jini-ai/daemon`-side wiring for
- * OD's `apps/daemon/src/terminals.ts` + `apps/daemon/src/routes/terminal.ts`
- * (see `ADS-memory/reports/proposals/PROP-http-route-packs-terminal-pty-2026-07-21.md`
- * for the full design discussion this module implements a specific decision
- * from). The generic ring-buffer/coalescing/SSE-agnostic session engine
- * already exists as `@jini-ai/platform`'s `terminal.ts` (ported 2026-07-18,
- * before this task) — this module does **not** reimplement that. It adds
- * exactly the three things that engine deliberately left to a caller:
- *
- * 1. **A real `node-pty`-backed `PtySpawn`.** `@jini-ai/platform` intentionally
- *    does not depend on `node-pty` (a native compiled addon); `@jini-ai/daemon`
- *    does (see this package's `package.json` and `archived provenance ledger`'s dated
- *    section for why that dependency now lives here, not in `@jini-ai/http-kit` or
- *    `@jini-ai/platform`). {@link loadRealSpawnPty} is the real, dynamically
- *    imported default the reference session manager below uses.
- *
- * 2. **Session-token gating.** The proposal's blocker was that a
- *    *session-scoped* dangerous capability (once a shell is spawned, every
- *    subsequent `stdin` write is arbitrary unaudited input for the
- *    session's lifetime) does not fit `ToolExecutor`'s call-scoped shape.
- *    The resolved design: `ToolExecutor.execute('terminal.create', ...)`
- *    (via {@link createTerminalToolRegistrations}) is the one full
- *    deny-by-default gated call — it authorizes *creating* a session.
- *    Every subsequent `write`/`resize`/`kill`/`attach` call against that
- *    session id is validated by a lighter, still-explicit check: this
- *    module records which `Principal` created each session at `create()`
- *    time, and every later call verifies the calling principal matches,
- *    denying (as a `'not-found'` result, never a distinguishable "forbidden"
- *    — see {@link checkOwnership}'s doc for why) otherwise. This is not
- *    "the session id is unguessable therefore secure" — it is a real,
- *    per-call identity check, independent of how hard the id is to guess.
- *
- * 3. **The kill/stdin/resize race fix.** OD's origin (and `@jini-ai/platform`'s
- *    faithful port of it) has no lock between a `kill` and a concurrent
- *    `write`/`resize` on the same session id: `kill()` only *requests* the
- *    real OS process die (sends `SIGTERM`) — the session's `status` does not
- *    flip to `'exited'` until the pty's own `onExit` callback fires,
- *    asynchronously, once the real process actually dies. A `write`/`resize`
- *    processed in that window still observes `status: 'running'` and still
- *    reaches the real pty. This module closes that window with its own
- *    immediate, lock-protected `killed` flag (see {@link runExclusive} and
- *    the `write`/`resize`/`kill` implementations below): once a `kill` call
- *    has run its own critical section, any `write`/`resize` queued behind it
- *    for the same session id sees `killed: true` and is rejected — it never
- *    depends on the real process having actually exited yet.
- */
-import { createRequire } from 'node:module';
-import { createTerminalService, ensureSpawnHelperExecutable, spawnHelperCandidatePaths, } from '@jini-ai/platform';
+import { createTerminalService, } from '@jini-ai/platform';
 /** The `ToolRegistry` id `terminal.create` executes through — see module doc §2. */
 export const TERMINAL_CREATE_TOOL_ID = 'terminal.create';
 /**
@@ -63,43 +13,6 @@ export const TERMINAL_CREATE_TOOL_ID = 'terminal.create';
 export const denyAllTerminalCreatePolicy = {
     authorize: () => 'deny',
 };
-const daemonRequire = createRequire(import.meta.url);
-/** Adapts a real `node-pty` `IPty` to `@jini-ai/platform`'s narrower `PtyProcess` port — explicit per-member mapping rather than relying on structural assignability, matching this package's established "explicit adapter, no implicit coercion" convention (e.g. `agent-executor.ts`'s `toStringEnvRecord`). */
-function toPtyProcess(pty) {
-    return {
-        onData: (cb) => {
-            pty.onData(cb);
-        },
-        onExit: (cb) => {
-            pty.onExit(cb);
-        },
-        write: (input) => pty.write(input),
-        resize: (cols, rows) => pty.resize(cols, rows),
-        kill: (signal) => pty.kill(signal),
-    };
-}
-/**
- * The real, `node-pty`-backed {@link PtySpawn}. Dynamically imports
- * `node-pty` (mirroring OD's origin `await import('node-pty')`, not a
- * static top-level import) so a host process whose platform/environment
- * lacks a usable `node-pty` addon can still boot — only an actual
- * `terminal.create` call fails, cleanly, rather than crashing at
- * module-eval time. Before the first spawn, repairs `node-pty`'s bundled
- * `spawn-helper` binary's executable bit (pnpm unpacks it non-executable —
- * see `@jini-ai/platform`'s `terminal.ts` module doc for the full story) via
- * that package's own `spawnHelperCandidatePaths`/`ensureSpawnHelperExecutable`,
- * but with the resolver anchored at **this** module
- * (`createRequire(import.meta.url)` here, not `@jini-ai/platform`'s own
- * default): `@jini-ai/platform` deliberately does not depend on `node-pty`, so
- * its default `require.resolve('node-pty')` would not find the copy this
- * package (`@jini-ai/daemon`) actually declares — this is exactly the
- * resolver injection seam `spawnHelperCandidatePaths` was built for.
- */
-export async function loadRealSpawnPty(_requiredArgs) {
-    ensureSpawnHelperExecutable(spawnHelperCandidatePaths({ resolve: (specifier) => daemonRequire.resolve(specifier) }));
-    const nodePty = await import('node-pty');
-    return (shell, args, options) => toPtyProcess(nodePty.spawn(shell, args, options));
-}
 function toSessionInfo(session, resourceRef) {
     return {
         id: session.id,
@@ -144,11 +57,15 @@ async function runExclusive(locks, id, fn) {
  * around a `@jini-ai/platform` `TerminalService` adding session ownership,
  * the kill/write/resize lock, and (via {@link createTerminalToolRegistrations})
  * `ToolExecutor` gating for creation. See module doc for the full design.
+ * Without a host-owned service or loader, boot is inert and `create()` rejects
+ * with injection guidance. Wrapper setup is O(1); session work stays in the platform service.
  */
 export function createTerminalSessionManager(_requiredArgs, options = {}) {
     const terminalService = options.terminalService ??
         createTerminalService({
-            loadSpawnPty: options.loadSpawnPty ?? (() => loadRealSpawnPty({})),
+            loadSpawnPty: options.loadSpawnPty ?? (() => {
+                throw new Error('Interactive terminals require a host-supplied terminalService or loadSpawnPty. Import loadRealSpawnPty from @jini-ai/daemon/terminal to enable node-pty.');
+            }),
             ...definedOnly({
                 maxEvents: options.maxEvents,
                 maxBufferBytes: options.maxBufferBytes,
@@ -200,11 +117,10 @@ export function createTerminalSessionManager(_requiredArgs, options = {}) {
         const result = [];
         for (const session of terminalService.list()) {
             const meta = metadata.get(session.id);
-            if (!meta || meta.principalId !== principal.id)
-                continue;
-            if (filter.resourceRef !== undefined && meta.resourceRef !== filter.resourceRef)
-                continue;
-            result.push(toSessionInfo(session, meta.resourceRef));
+            const visible = meta !== undefined && meta.principalId === principal.id
+                && (filter.resourceRef === undefined || meta.resourceRef === filter.resourceRef);
+            if (visible)
+                result.push(toSessionInfo(session, meta.resourceRef));
         }
         return result;
     }

package/dist/terminal.adapter.d.ts

@@ -0,0 +1,22 @@
+import { type PtySpawn } from '@jini-ai/platform';
+/**
+ * The real, `node-pty`-backed {@link PtySpawn}. Dynamically imports
+ * `node-pty` (mirroring OD's origin `await import('node-pty')`, not a
+ * static top-level import) so a host process whose platform/environment
+ * lacks a usable `node-pty` addon can still boot — only an actual
+ * `terminal.create` call fails, cleanly, rather than crashing at
+ * module-eval time. Before the first spawn, repairs `node-pty`'s bundled
+ * `spawn-helper` binary's executable bit (pnpm unpacks it non-executable —
+ * see `@jini-ai/platform`'s `terminal.ts` module doc for the full story) via
+ * that package's own `spawnHelperCandidatePaths`/`ensureSpawnHelperExecutable`,
+ * but with the resolver anchored at **this** module
+ * (`createRequire(import.meta.url)` here, not `@jini-ai/platform`'s own
+ * default): `@jini-ai/platform` deliberately does not depend on `node-pty`, so
+ * its default `require.resolve('node-pty')` would not find the copy this
+ * package (`@jini-ai/daemon`) actually declares — this is exactly the
+ * resolver injection seam `spawnHelperCandidatePaths` was built for.
+ * @throws A feature-specific load error with the original resolution/ABI error as `cause`.
+ * @complexity O(1) adapter work; module loading and helper repair belong to the platform.
+ */
+export declare function loadRealSpawnPty(_requiredArgs: Record<string, never>, _optionalArgs?: Record<string, never>): Promise<PtySpawn>;
+//# sourceMappingURL=terminal.adapter.d.ts.map

package/dist/terminal.adapter.js

@@ -0,0 +1,47 @@
+/**
+ * Opt-in native PTY adapter. Import from `@jini-ai/daemon/terminal` and inject
+ * `() => loadRealSpawnPty({})` into the session manager's `loadSpawnPty` port.
+ */
+import { loadOptionalPeer } from '@jini-ai/core/optional-peer';
+import { createRequire } from 'node:module';
+import { ensureSpawnHelperExecutable, spawnHelperCandidatePaths, } from '@jini-ai/platform';
+const daemonRequire = createRequire(import.meta.url);
+/** Adapts a real `node-pty` `IPty` to `@jini-ai/platform`'s narrower `PtyProcess` port — explicit per-member mapping rather than relying on structural assignability, matching this package's established "explicit adapter, no implicit coercion" convention (e.g. `agent-executor.ts`'s `toStringEnvRecord`). */
+function toPtyProcess(pty) {
+    return {
+        onData: (cb) => {
+            pty.onData(cb);
+        },
+        onExit: (cb) => {
+            pty.onExit(cb);
+        },
+        write: (input) => pty.write(input),
+        resize: (cols, rows) => pty.resize(cols, rows),
+        kill: (signal) => pty.kill(signal),
+    };
+}
+/**
+ * The real, `node-pty`-backed {@link PtySpawn}. Dynamically imports
+ * `node-pty` (mirroring OD's origin `await import('node-pty')`, not a
+ * static top-level import) so a host process whose platform/environment
+ * lacks a usable `node-pty` addon can still boot — only an actual
+ * `terminal.create` call fails, cleanly, rather than crashing at
+ * module-eval time. Before the first spawn, repairs `node-pty`'s bundled
+ * `spawn-helper` binary's executable bit (pnpm unpacks it non-executable —
+ * see `@jini-ai/platform`'s `terminal.ts` module doc for the full story) via
+ * that package's own `spawnHelperCandidatePaths`/`ensureSpawnHelperExecutable`,
+ * but with the resolver anchored at **this** module
+ * (`createRequire(import.meta.url)` here, not `@jini-ai/platform`'s own
+ * default): `@jini-ai/platform` deliberately does not depend on `node-pty`, so
+ * its default `require.resolve('node-pty')` would not find the copy this
+ * package (`@jini-ai/daemon`) actually declares — this is exactly the
+ * resolver injection seam `spawnHelperCandidatePaths` was built for.
+ * @throws A feature-specific load error with the original resolution/ABI error as `cause`.
+ * @complexity O(1) adapter work; module loading and helper repair belong to the platform.
+ */
+export async function loadRealSpawnPty(_requiredArgs, _optionalArgs = {}) {
+    ensureSpawnHelperExecutable(spawnHelperCandidatePaths({ resolve: (specifier) => daemonRequire.resolve(specifier) }));
+    const nodePty = await loadOptionalPeer({ feature: 'Interactive terminals', dependency: 'node-pty', load: () => import('node-pty') });
+    return (shell, args, options) => toPtyProcess(nodePty.spawn(shell, args, options));
+}
+//# sourceMappingURL=terminal.adapter.js.map

package/dist/tool-executor.d.ts

@@ -17,7 +17,7 @@ export interface ToolConfirmationRequest {
  * The transport-supplied seam for the two touchpoints a headless kernel
  * cannot render itself. Both are optional: a tool whose `ToolPolicy`
  * always resolves definitively needs no `onAuthorize`, and a tool with
- * `requiresConfirmation` unset never triggers `onConfirm`.
+ * `requiresConfirmation` unset has no default prompt; a host may strengthen a single call with `requireConfirmation: true`.
  */
 export interface ExecutionDelegate {
     /**
@@ -42,7 +42,7 @@ export interface ExecutionDelegate {
      */
     onConfirm?(request: ToolConfirmationRequest): ConfirmationDecision | Promise<ConfirmationDecision> | void;
 }
-export type ToolExecutionPhase = 'requested' | 'authorized' | 'denied' | 'confirmed' | 'confirmation-denied' | 'started' | 'completed' | 'failed' | 'timed-out' | 'cancelled';
+export type ToolExecutionPhase = 'requested' | 'authorized' | 'denied' | 'confirmed' | 'approval-recorded' | 'confirmation-denied' | 'started' | 'completed' | 'failed' | 'timed-out' | 'cancelled';
 export interface ToolExecutionAuditEvent {
     readonly phase: ToolExecutionPhase;
     readonly at: number;
@@ -85,6 +85,7 @@ export interface ToolExecutor {
      * @param emitSurface - Transport-supplied seam letting the handler push a human-only surface into
      * the run's event stream *before* this call settles. Omit for a caller with no run event stream;
      * see `@jini-ai/core`'s `SurfaceEmitter` for why a handler that waits on a human needs it.
+     * @param requireConfirmation - Strengthens this call only; cannot bypass a descriptor confirmation.
      * @throws {ToolInputError} If `toolId` isn't registered, with up to eight registered prefix matches.
      */
     execute(args: {
@@ -95,6 +96,7 @@ export interface ToolExecutor {
     }, optionalArgs?: {
         readonly signal?: AbortSignal;
         readonly emitSurface?: SurfaceEmitter;
+        readonly requireConfirmation?: true;
     }): Promise<ToolExecutionResult>;
     /** @throws If `executionId` has no confirmation currently pending (already resumed, never required one, or unknown). */
     resumeConfirmation(args: {

package/dist/tool-executor.js

@@ -46,7 +46,7 @@
  * answer gets back in.
  */
 import { randomUUID } from 'node:crypto';
-import { ToolInputError, withNormalizationNotes, ToolInputNormalizationError, } from '@jini-ai/core';
+import { ToolInputError, APPROVAL_WAIT_TIMEOUT_MS, withNormalizationNotes, ToolInputNormalizationError, isReadOnlyTool, } from '@jini-ai/core';
 import { authorizeToolInvocation } from '@jini-ai/core/composition';
 import { toolCandidates } from './core/tool-candidates.js';
 /**
@@ -104,6 +104,8 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
     // Finished executionIds, oldest first (Set insertion order): the only records `retireAudit` evicts.
     const finishedAudits = new Set();
     const pendingConfirmations = new Map();
+    // Owned by the executor, not a bridge: concurrent HTTP/MCP calls create separate bridges.
+    const approvalWaits = new Map();
     const activeControllers = new Map();
     /**
      * Marks a pending confirmation `cancel()` just resolved (as opposed to a genuine human `deny`),
@@ -114,6 +116,34 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
      * `requestConfirmation()` settles, so it can never leak onto a later execution.
      */
     const cancelledConfirmations = new Set();
+    /** Records only actual human waits; terminal decisions and aborts release the run's write block.
+     * @complexity O(1) time/space per pending execution; empty run entries are removed. */
+    function approvalStateChange({ run, executionId, toolId, pending }, _optional = {}) {
+        if (pending) {
+            const waits = approvalWaits.get(run.id) ?? new Map();
+            waits.set(executionId, toolId);
+            approvalWaits.set(run.id, waits);
+            return;
+        }
+        const waits = approvalWaits.get(run.id);
+        waits?.delete(executionId);
+        if (waits?.size === 0)
+            approvalWaits.delete(run.id);
+    }
+    /** Refuses writes using the registered read-only contract, never a model's claim.
+     * The validation result reaches every delegated transport as an actionable error, without
+     * resolving or approving the original call. @complexity O(1) time/space. */
+    function approvalRefusal({ executionId, run, descriptor }, _optional = {}) {
+        const pendingToolId = approvalWaits.get(run.id)?.values().next().value;
+        if (pendingToolId === undefined || isReadOnlyTool({ descriptor }))
+            return undefined;
+        const error = JSON.stringify({
+            status: 'awaiting_approval', started: false, toolId: descriptor.id, pendingToolId,
+            message: 'Another action is waiting for human confirmation and has not started. This write was refused. Reads may continue. Never say an action has started until its tool result explicitly says it started.',
+        });
+        appendEvent(executionId, 'failed', error);
+        return { executionId, status: 'failed', errorKind: 'validation', error };
+    }
     function appendEvent(executionId, phase, detail) {
         // Every call site passes an `executionId` this same `execute()` call
         // already registered in `audits` (right before its first `appendEvent`
@@ -176,15 +206,45 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
      * what distinguishes a `timed-out` result from a `cancelled` one.
      */
     function startTimeout(controller, timeoutMs) {
-        if (timeoutMs === undefined)
-            return { handle: undefined, timedOut: () => false };
+        let handle;
         let timedOut = false;
-        const handle = setTimeout(() => {
-            timedOut = true;
-            controller.abort();
-        }, timeoutMs);
-        handle.unref?.();
-        return { handle, timedOut: () => timedOut };
+        let waiting = false;
+        let approvalWindowUsed = false;
+        let remaining = timeoutMs;
+        let started = Date.now();
+        const stop = () => {
+            if (handle === undefined)
+                return;
+            clearTimeout(handle);
+            handle = undefined;
+        };
+        const arm = (duration) => {
+            stop();
+            started = Date.now();
+            if (duration === undefined)
+                return;
+            handle = setTimeout(() => { timedOut = true; controller.abort(); }, duration);
+            handle.unref?.();
+        };
+        arm(remaining);
+        return {
+            stop,
+            timedOut: () => timedOut,
+            /** Human waiting is bounded independently and cannot replenish the execution budget.
+             * Duplicate progress frames cannot extend either deadline. */
+            approval: ({ pending }) => {
+                if (pending === waiting || controller.signal.aborted)
+                    return;
+                if (pending && approvalWindowUsed)
+                    return;
+                if (pending)
+                    approvalWindowUsed = true;
+                if (pending && remaining !== undefined)
+                    remaining = Math.max(0, remaining - (Date.now() - started));
+                waiting = pending;
+                arm(pending ? APPROVAL_WAIT_TIMEOUT_MS : remaining);
+            },
+        };
     }
     /** Records a terminal transition that carries no detail and returns its bare result. */
     function terminal({ executionId, status }) {
@@ -242,7 +302,7 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
      * Acts on the authorization outcome synchronously: `{ refusal }` if the call ends here
      * (cancelled meanwhile, or denied), otherwise records `authorized` and returns `{ allowed }`.
      */
-    function admitAuthorized({ executionId, resolved, signal }) {
+    function admitAuthorized({ executionId, resolved, signal, run }) {
         // `authorize()` isn't itself signal-aware — it's typically a fast policy check, not a
         // human-in-the-loop wait — so this is a post-await check rather than a mid-flight abort, the
         // same idiom the post-handler check below already uses: a signal that fired while `authorize()`
@@ -253,6 +313,10 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
             return { refusal: terminal({ executionId, status: 'denied' }) };
         const { normalizationNotes } = resolved;
         appendEvent(executionId, 'authorized', normalizationNotes.length ? `normalized: ${normalizationNotes.join('; ')}` : undefined);
+        // Check after authorization awaits: an approval may have opened while this policy was pending.
+        const refusal = approvalRefusal({ executionId, run, descriptor: resolved.descriptor });
+        if (refusal)
+            return { refusal };
         return { allowed: resolved };
     }
     /**
@@ -268,13 +332,18 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
     async function confirmGate(request) {
         const { executionId } = request;
         let confirmation;
+        const state = { run: request.run, executionId, toolId: request.tool.id };
         try {
+            approvalStateChange({ ...state, pending: true });
             confirmation = await requestConfirmation(request);
         }
         catch {
             // Same reasoning as the authorization gate: terminal, recorded, and generic.
             return operationalFailure({ executionId, error: 'confirmation failed' });
         }
+        finally {
+            approvalStateChange({ ...state, pending: false });
+        }
         if (confirmation === 'confirm') {
             appendEvent(executionId, 'confirmed');
             return undefined;
@@ -353,6 +422,10 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         if (controller.signal.aborted) {
             return terminal({ executionId, status: 'cancelled' });
         }
+        // Guidance may await I/O after admission; another call can open a confirmation in that gap.
+        const refusal = approvalRefusal({ executionId, run, descriptor });
+        if (refusal)
+            return refusal;
         const timeout = startTimeout(controller, descriptor.timeoutMs);
         // Cleanup (clear the timeout) is repeated at
         // each return below rather than centralized in a `finally` — a
@@ -363,8 +436,8 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         // the catch). Repeating one call avoids leaving an uncoverable branch
         // behind instead of writing a contrived test or suppressing it.
         const cleanup = () => {
-            if (timeout.handle)
-                clearTimeout(timeout.handle);
+            timeout.stop();
+            approvalStateChange({ run, executionId, toolId: call.toolId, pending: false });
         };
         appendEvent(executionId, 'started');
         try {
@@ -379,6 +452,13 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
                 signal: controller.signal,
             }, {
                 ...surfaceOption(emitSurface),
+                onApprovalStateChange: ({ pending, decision }) => {
+                    // The tab owns human confirmation; retain its outcome without opening a chat surface.
+                    if (decision)
+                        appendEvent(executionId, 'approval-recorded', `frontend approval: ${decision}`);
+                    timeout.approval({ pending });
+                    approvalStateChange({ run, executionId, toolId: call.toolId, pending });
+                },
                 invokeTool: nestedInvoker({ principal, run, toolId: call.toolId, invocationRegistry: call.invocationRegistry, signal: controller.signal }, { emitSurface }),
             });
             cleanup();
@@ -389,7 +469,7 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
             return failureResult({ executionId, err, timedOut: timeout.timedOut(), aborted: controller.signal.aborted }, { normalizationNotes, guidance });
         }
     }
-    async function execute({ principal, run, toolId, input }, { signal, emitSurface, invocationRegistry = registry } = {}) {
+    async function execute({ principal, run, toolId, input }, { signal, emitSurface, invocationRegistry = registry, requireConfirmation } = {}) {
         // Existence is checked separately from — and before — authorization so the audit record can
         // be opened before the (possibly slow, possibly throwing) authorization gate runs, matching
         // pre-authorizeToolInvocation timing: `requested` used to precede `policy.authorize`, and a
@@ -443,14 +523,14 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         // `invocationRegistry.has({ toolId })` above already confirmed the tool exists, and `ToolRegistry` is
         // append-only (no unregister — see `createToolRegistry`'s doc), so `authorizeToolInvocation`
         // resolving the same `toolId` against the same `registry` cannot come back `undefined` here.
-        const gate = admitAuthorized({ executionId, resolved: resolved, signal: controller.signal });
+        const gate = admitAuthorized({ executionId, resolved: resolved, signal: controller.signal, run });
         if ('refusal' in gate) {
             cleanupCancellation();
             return gate.refusal;
         }
         const admitted = gate.allowed;
         const { descriptor } = admitted;
-        if (descriptor.requiresConfirmation) {
+        if (descriptor.requiresConfirmation || requireConfirmation) {
             const declined = await confirmGate({ executionId, principal, run, tool: descriptor, input: admitted.input });
             if (declined) {
                 cleanupCancellation();