@jini-ai/daemon 0.3.8 → 0.5.0

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

@@ -0,0 +1,230 @@
+import { createSystemClock } from '@jini-ai/core/primitives';
+/**
+ * `createSqliteEventLog` — the durable `EventLog` adapter (extraction-plan §8 task 8,
+ * §2.6: "`@jini-ai/daemon/store/event-log/sqlite` is the default adapter... an adapter conformance suite covers
+ * transactions/ordering/cursor-durability/cancellation/migrations").
+ *
+ * Implements the protocol's two-object `EventLog` call shape, with the same distinguishable `'replay-gap'` result,
+ * same never-reused monotonic per-run cursor allocation, same FIFO eviction at
+ * `maxEntriesPerRun` — see `createInMemoryEventLog` in `@jini-ai/daemon` for the
+ * reference behavior this mirrors. `better-sqlite3` is synchronous; every public
+ * method still returns a `Promise` per extraction-plan §2.6 ("ports are async-only
+ * from day one... a real persistent adapter is a drop-in swap"), and every
+ * multi-statement operation (`append`'s dedupe-check + insert + eviction) runs
+ * inside a `better-sqlite3` transaction for atomicity.
+ *
+ * Three deliberate divergences from the in-memory reference adapter, all scoped to this durable
+ * adapter only: (1) `maxEntriesPerRun` defaults to {@link DEFAULT_MAX_ENTRIES_PER_RUN} (2000)
+ * instead of unbounded — see `SqliteEventLogOptions.maxEntriesPerRun`'s doc; (2) `replay`'s
+ * `afterCursor` is validated up front and throws for anything other than `null` or a
+ * non-negative-safe-integer string, instead of returning a `'invalid-cursor'` result — see
+ * `assertValidReplayCursor`; (3) dedupe evidence is retained only while its entry remains in the
+ * FIFO window. Memory keeps dedupe evidence until drop, including evicted entries. This durable
+ * adapter preserves its existing bounded SQL/schema behavior rather than adding a hidden archive.
+ */
+import { openSqliteConnection } from '@jini-ai/db/sqlite';
+/**
+ * Default per-run retention cap applied when `SqliteEventLogOptions.maxEntriesPerRun` is
+ * omitted — see that option's doc for why a durable adapter defaults to a bound instead of
+ * mirroring the in-memory reference adapter's unbounded-by-default behavior.
+ */
+export const DEFAULT_MAX_ENTRIES_PER_RUN = 2000;
+/** @internal Validates and resolves `options.maxEntriesPerRun`, applying the documented default. */
+function resolveMaxEntriesPerRun(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_ENTRIES_PER_RUN;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`createSqliteEventLog: options.maxEntriesPerRun must be a non-negative safe integer, got ${value}`);
+    }
+    return value;
+}
+/** @internal Validates a `replay(runId, afterCursor)` cursor. `null` ("from the beginning") is always valid. */
+function assertValidReplayCursor(afterCursor) {
+    if (afterCursor === null)
+        return;
+    const n = Number(afterCursor);
+    if (!Number.isSafeInteger(n) || n < 0) {
+        throw new Error(`createSqliteEventLog: invalid replay cursor ${JSON.stringify(afterCursor)} — must be a non-negative safe integer string`);
+    }
+}
+function rowToEntry(row) {
+    return {
+        id: String(row.cursor),
+        event: row.event,
+        data: JSON.parse(row.data),
+        recordedAt: row.recorded_at,
+    };
+}
+/**
+ * Borrows the caller's connection and ensures the dedicated event-log schema idempotently.
+ * Closing this adapter never closes a borrowed handle or changes its pragmas.
+ * Use openSqliteEventLog with an explicit file/opener to acquire an owned connection.
+ * @throws Host SQL/setup failures, or a missing borrowed connection.
+ * @complexity Setup O(1) statements; append costs depend on the retained per-run cap.
+ */
+export function createSqliteEventLog(input, options = {}) {
+    resolveMaxEntriesPerRun(options.maxEntriesPerRun);
+    if (!input || typeof input !== 'object' || !input.db) {
+        throw new Error('createSqliteEventLog: pass a borrowed SqliteDb');
+    }
+    return bindSqliteEventLog(input.db, options);
+}
+/**
+ * Acquires a connection through the host opener; setup failure closes that connection.
+ * Successful close is idempotent and closes only this owned handle.
+ * @param input File and host-owned opener; no ambient driver is loaded.
+ * @returns Durable event log with an owned closer.
+ * @throws Original acquisition/schema/prepare failure; cleanup never masks it.
+ * @complexity O(1) acquisition calls; subsequent costs are the borrowed adapter's.
+ */
+export function openSqliteEventLog(input, options = {}) {
+    resolveMaxEntriesPerRun(options.maxEntriesPerRun);
+    let db;
+    try {
+        db = openSqliteConnection({ filePath: input.file, open(file, settings) {
+                db = input.open(file, settings);
+                return db;
+            }, pragmas: ['journal_mode = WAL'] });
+        const log = bindSqliteEventLog(db, options);
+        let closed = false;
+        return { ...log, async close(_args) { if (closed)
+                return; closed = true; db.close(); } };
+    }
+    catch (error) {
+        try {
+            db?.close();
+        }
+        catch { /* Preserve the setup failure. */ }
+        throw error;
+    }
+}
+/** Binds the unchanged cursor/dedupe/retention SQL to a borrowed synchronous connection. */
+function bindSqliteEventLog(db, options) {
+    const maxEntriesPerRun = resolveMaxEntriesPerRun(options.maxEntriesPerRun);
+    const clock = options.clock ?? createSystemClock();
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS jini_event_log_runs (
+      run_id TEXT PRIMARY KEY,
+      next_cursor INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS jini_event_log_entries (
+      run_id TEXT NOT NULL,
+      cursor INTEGER NOT NULL,
+      event TEXT NOT NULL,
+      data TEXT NOT NULL,
+      recorded_at INTEGER NOT NULL,
+      dedupe_key TEXT,
+      PRIMARY KEY (run_id, cursor)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_jini_event_log_entries_dedupe
+      ON jini_event_log_entries (run_id, dedupe_key)
+      WHERE dedupe_key IS NOT NULL;
+  `);
+    const getRunStmt = db.prepare('SELECT run_id, next_cursor FROM jini_event_log_runs WHERE run_id = ?');
+    const insertRunStmt = db.prepare('INSERT INTO jini_event_log_runs (run_id, next_cursor) VALUES (?, ?)');
+    const updateNextCursorStmt = db.prepare('UPDATE jini_event_log_runs SET next_cursor = ? WHERE run_id = ?');
+    const getByDedupeStmt = db.prepare('SELECT * FROM jini_event_log_entries WHERE run_id = ? AND dedupe_key = ?');
+    const insertEntryStmt = db.prepare('INSERT INTO jini_event_log_entries (run_id, cursor, event, data, recorded_at, dedupe_key) VALUES (?, ?, ?, ?, ?, ?)');
+    const countEntriesStmt = db.prepare('SELECT COUNT(*) AS count FROM jini_event_log_entries WHERE run_id = ?');
+    const evictOldestStmt = db.prepare(`
+    DELETE FROM jini_event_log_entries
+    WHERE run_id = ? AND cursor IN (
+      SELECT cursor FROM jini_event_log_entries WHERE run_id = ? ORDER BY cursor ASC LIMIT ?
+    )
+  `);
+    const selectAllStmt = db.prepare('SELECT * FROM jini_event_log_entries WHERE run_id = ? ORDER BY cursor ASC');
+    const selectAfterStmt = db.prepare('SELECT * FROM jini_event_log_entries WHERE run_id = ? AND cursor > ? ORDER BY cursor ASC');
+    const selectOldestStmt = db.prepare('SELECT * FROM jini_event_log_entries WHERE run_id = ? ORDER BY cursor ASC LIMIT 1');
+    const selectRunIdsStmt = db.prepare('SELECT run_id FROM jini_event_log_runs ORDER BY run_id ASC');
+    const deleteRunEntriesStmt = db.prepare('DELETE FROM jini_event_log_entries WHERE run_id = ?');
+    const deleteRunStmt = db.prepare('DELETE FROM jini_event_log_runs WHERE run_id = ?');
+    // `db.transaction()` does not preserve a wrapped callback's own generic parameter (the
+    // returned `Transaction` type is non-generic), so this runs on `unknown` payloads and the
+    // public `append<Payload>` method below casts at the boundary — the same pattern
+    // `createInMemoryEventLog` uses for its dedupe-hit early return.
+    const appendTxn = db.transaction((input) => {
+        let runRow = getRunStmt.get(input.runId);
+        if (!runRow) {
+            insertRunStmt.run(input.runId, 1);
+            runRow = { run_id: input.runId, next_cursor: 1 };
+        }
+        if (input.dedupeKey !== undefined) {
+            const existing = getByDedupeStmt.get(input.runId, input.dedupeKey);
+            if (existing) {
+                return rowToEntry(existing);
+            }
+        }
+        const cursor = runRow.next_cursor;
+        const recordedAt = clock.nowMs();
+        insertEntryStmt.run(input.runId, cursor, input.event, JSON.stringify(input.data ?? null), recordedAt, input.dedupeKey ?? null);
+        updateNextCursorStmt.run(cursor + 1, input.runId);
+        const { count } = countEntriesStmt.get(input.runId);
+        if (count > maxEntriesPerRun) {
+            evictOldestStmt.run(input.runId, input.runId, count - maxEntriesPerRun);
+        }
+        return {
+            id: String(cursor),
+            event: input.event,
+            data: input.data,
+            recordedAt,
+        };
+    });
+    function replaySync(runId, afterCursor) {
+        // Validated up front, independent of whether `runId` is known: a malformed cursor is a
+        // caller/transport bug regardless of run state, so it throws rather than being folded into
+        // (or masked by) an `'unknown-run'`/`'replay-gap'` result.
+        assertValidReplayCursor(afterCursor);
+        const runRow = getRunStmt.get(runId);
+        if (!runRow) {
+            return { kind: 'unknown-run' };
+        }
+        if (afterCursor === null) {
+            const oldestRow = selectOldestStmt.get(runId);
+            const truncated = oldestRow !== undefined && oldestRow.cursor > 1;
+            return {
+                kind: 'ok',
+                entries: selectAllStmt.all(runId).map(rowToEntry),
+                ...(truncated ? { truncated: true } : {}),
+            };
+        }
+        // Safe: assertValidReplayCursor already proved this parses to a non-negative safe integer.
+        const afterCursorNum = Number(afterCursor);
+        const oldestRow = selectOldestStmt.get(runId);
+        const oldestRetainedId = oldestRow ? oldestRow.cursor : runRow.next_cursor;
+        if (afterCursorNum < oldestRetainedId - 1) {
+            return {
+                kind: 'replay-gap',
+                requestedCursor: afterCursor,
+                oldestAvailableCursor: oldestRow ? String(oldestRow.cursor) : null,
+            };
+        }
+        return {
+            kind: 'ok',
+            entries: selectAfterStmt.all(runId, afterCursorNum).map(rowToEntry),
+        };
+    }
+    const dropTxn = db.transaction((runId) => {
+        deleteRunEntriesStmt.run(runId);
+        deleteRunStmt.run(runId);
+    });
+    return {
+        async append(input, options = {}) {
+            return appendTxn({ ...input, dedupeKey: options.dedupeKey });
+        },
+        async replay({ runId, afterCursor }) {
+            return replaySync(runId, afterCursor);
+        },
+        async listRunIds(_args) {
+            return selectRunIdsStmt.all().map((row) => row.run_id);
+        },
+        async drop({ runId }) {
+            dropTxn(runId);
+        },
+        async close(_args) {
+            // Borrowed handle: the host owns its lifetime.
+        },
+    };
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/surface-exchanges.d.ts

@@ -0,0 +1,97 @@
+import type { Clock, IdGenerator } from '@jini-ai/core/primitives';
+import type { SurfaceEmission, SurfaceEmitter } from '@jini-ai/core';
+import type { SchedulerPort } from './scheduler.js';
+export type { SchedulerPort } from './scheduler.js';
+export declare const SURFACE_EXCHANGE_ID_PARAM = "__exchangeId";
+export declare const SURFACE_DISMISSED_PARAM = "__dismissed";
+export declare const SURFACE_TYPED_ANSWER_PARAM = "__typedAnswer";
+export declare const DEFAULT_SURFACE_IDLE_TTL_MS: number;
+export declare const DEFAULT_SURFACE_MAX_LIFETIME_MS: number;
+export type SurfaceAnswerChannel = string;
+export interface SurfaceExchangeBinding {
+    readonly toolId: string;
+    readonly principalId: string;
+    readonly channel?: SurfaceAnswerChannel;
+}
+export type SurfaceMessage = {
+    status: 'received';
+    params: Record<string, unknown>;
+} | {
+    status: 'expired';
+} | {
+    status: 'abandoned';
+};
+export type SurfaceDeliveryRejectionReason = 'unknown-or-closed' | 'binding-mismatch';
+export type DeliverResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: SurfaceDeliveryRejectionReason;
+};
+export interface SurfaceExchange {
+    readonly id: string;
+    send(args: {
+        emission: SurfaceEmission;
+    }): Promise<void>;
+    receive(_args: Record<string, never>): Promise<SurfaceMessage>;
+    close(_args: Record<string, never>): void;
+}
+export interface SurfaceDeliverySpec {
+    exchangeId: string;
+    params: Record<string, unknown>;
+    principalId: string;
+    toolId?: string;
+    channel?: SurfaceAnswerChannel;
+}
+export interface SurfaceExchangeStore {
+    open(args: {
+        binding: SurfaceExchangeBinding;
+        emit: SurfaceEmitter;
+    }): SurfaceExchange;
+    deliver(requiredArgs: Pick<SurfaceDeliverySpec, "exchangeId" | "params" | "principalId">, optionalArgs?: Pick<SurfaceDeliverySpec, "toolId" | "channel">): DeliverResult;
+    findTypedAnswerTarget(args: {
+        principalId: string;
+        toolId: string;
+    }): string | undefined;
+    size(): number;
+}
+/** In-process held calls. Inject a scheduler that unrefs its timers where appropriate. */
+export declare function createSurfaceExchangeStore(deps: {
+    scheduler: SchedulerPort;
+    clock: Clock;
+    idGenerator: IdGenerator;
+    defaultChannel: SurfaceAnswerChannel;
+}, { idleTtlMs, maxLifetimeMs }?: {
+    idleTtlMs?: number;
+    maxLifetimeMs?: number;
+}): SurfaceExchangeStore;
+export declare function askOnce({ exchange, emission }: {
+    exchange: SurfaceExchange;
+    emission: SurfaceEmission;
+}): Promise<SurfaceMessage>;
+export declare function askThenReport<T>({ exchange, confirmationEmission, handle }: {
+    exchange: SurfaceExchange;
+    confirmationEmission: SurfaceEmission;
+    handle: (answer: SurfaceMessage) => Promise<{
+        result: T;
+        outcome?: SurfaceEmission;
+    }>;
+}): Promise<T>;
+export type ConfirmationOutcome = {
+    confirmed: true;
+} | {
+    confirmed: false;
+    reason: 'declined' | 'expired' | 'abandoned';
+};
+/** Typed prose is never consent; only an explicit literal decision grants approval. */
+export declare function classifyConfirmationAnswer({ answer }: {
+    answer: SurfaceMessage;
+}): ConfirmationOutcome;
+export declare function resolveConfirmationDecision(args: {
+    exchange: SurfaceExchange;
+    emission: SurfaceEmission;
+}): Promise<ConfirmationOutcome>;
+export interface AssistantSurfaceDeps {
+    readonly surfaceExchanges: SurfaceExchangeStore;
+}
+//# sourceMappingURL=surface-exchanges.d.ts.map

package/dist/surface-exchanges.js

@@ -0,0 +1,153 @@
+export const SURFACE_EXCHANGE_ID_PARAM = '__exchangeId';
+export const SURFACE_DISMISSED_PARAM = '__dismissed';
+export const SURFACE_TYPED_ANSWER_PARAM = '__typedAnswer';
+export const DEFAULT_SURFACE_IDLE_TTL_MS = 5 * 60 * 1000;
+export const DEFAULT_SURFACE_MAX_LIFETIME_MS = 5.5 * 60 * 1000;
+/** In-process held calls. Inject a scheduler that unrefs its timers where appropriate. */
+export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_IDLE_TTL_MS, maxLifetimeMs = DEFAULT_SURFACE_MAX_LIFETIME_MS } = {}) {
+    if (!Number.isFinite(idleTtlMs) || idleTtlMs <= 0 || !Number.isFinite(maxLifetimeMs) || maxLifetimeMs <= 0)
+        throw new Error('surface deadlines must be finite and positive');
+    const openExchanges = new Map();
+    return {
+        open({ binding, emit }) {
+            const id = deps.idGenerator.newId();
+            if (!id || openExchanges.has(id))
+                throw new Error('surface exchange ID must be unique and nonempty');
+            const inbox = [];
+            const waiters = [];
+            let terminal;
+            let cancelIdle;
+            let cancelLifetime;
+            const lifetimeDeadline = deps.clock.nowMs() + maxLifetimeMs;
+            let idleDeadline = deps.clock.nowMs() + idleTtlMs;
+            function end(reason) {
+                if (terminal)
+                    return;
+                terminal = reason;
+                cancelIdle?.();
+                cancelLifetime?.();
+                openExchanges.delete(id);
+                while (waiters.length > 0)
+                    waiters.shift()(reason);
+            }
+            function expireIfDue() {
+                const at = deps.clock.nowMs();
+                if (at >= idleDeadline || at >= lifetimeDeadline)
+                    end({ status: 'expired' });
+            }
+            function armIdle() {
+                if (terminal)
+                    return;
+                cancelIdle?.();
+                idleDeadline = deps.clock.nowMs() + idleTtlMs;
+                cancelIdle = deps.scheduler.schedule({ delayMs: idleTtlMs, callback: () => end({ status: 'expired' }) });
+            }
+            // Register only after both timers are installed, so scheduler failure leaves no discoverable exchange.
+            try {
+                cancelLifetime = deps.scheduler.schedule({ delayMs: maxLifetimeMs, callback: () => end({ status: 'expired' }) });
+                armIdle();
+            }
+            catch (error) {
+                cancelLifetime?.();
+                cancelIdle?.();
+                throw error;
+            }
+            openExchanges.set(id, {
+                binding: { ...binding },
+                accept(params) {
+                    expireIfDue();
+                    if (terminal)
+                        return;
+                    armIdle();
+                    const waiter = waiters.shift();
+                    if (waiter)
+                        waiter({ status: 'received', params });
+                    else
+                        inbox.push(params);
+                },
+            });
+            return {
+                id,
+                async send({ emission }) {
+                    expireIfDue();
+                    if (terminal)
+                        throw new Error(`surface exchange ${id} has already ended`);
+                    armIdle();
+                    await emit(emission);
+                },
+                async receive(_args) {
+                    expireIfDue();
+                    // Preserve the original FIFO contract: already delivered answers precede terminal status.
+                    const buffered = inbox.shift();
+                    if (buffered) {
+                        armIdle();
+                        return { status: 'received', params: buffered };
+                    }
+                    if (terminal)
+                        return terminal;
+                    return new Promise(resolve => waiters.push(resolve));
+                },
+                close(_args) { end({ status: 'abandoned' }); },
+            };
+        },
+        deliver(requiredArgs, optionalArgs = {}) {
+            const spec = { ...requiredArgs, ...optionalArgs };
+            const entry = openExchanges.get(spec.exchangeId);
+            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)
+                return { ok: false, reason: 'binding-mismatch' };
+            entry.accept(spec.params);
+            return openExchanges.has(spec.exchangeId) ? { ok: true } : { ok: false, reason: 'unknown-or-closed' };
+        },
+        findTypedAnswerTarget({ principalId, toolId }) {
+            let found;
+            for (const [id, entry] of openExchanges) {
+                if (entry.binding.principalId !== principalId || entry.binding.toolId !== toolId)
+                    continue;
+                if (found !== undefined)
+                    return undefined;
+                found = id;
+            }
+            return found;
+        },
+        size: () => openExchanges.size,
+    };
+}
+export async function askOnce({ exchange, emission }) {
+    try {
+        await exchange.send({ emission });
+        return await exchange.receive({});
+    }
+    finally {
+        exchange.close({});
+    }
+}
+export async function askThenReport({ exchange, confirmationEmission, handle }) {
+    try {
+        await exchange.send({ emission: confirmationEmission });
+        const { result, outcome } = await handle(await exchange.receive({}));
+        if (outcome !== undefined) {
+            try {
+                await exchange.send({ emission: outcome });
+            }
+            catch { /* Model result remains authoritative. */ }
+        }
+        return result;
+    }
+    finally {
+        exchange.close({});
+    }
+}
+/** Typed prose is never consent; only an explicit literal decision grants approval. */
+export function classifyConfirmationAnswer({ answer }) {
+    if (answer.status !== 'received')
+        return { confirmed: false, reason: answer.status };
+    return answer.params['decision'] === 'confirm' ? { confirmed: true } : { confirmed: false, reason: 'declined' };
+}
+export async function resolveConfirmationDecision(args) {
+    return classifyConfirmationAnswer({ answer: await askOnce(args) });
+}
+//# sourceMappingURL=surface-exchanges.js.map

package/dist/terminal-session.d.ts

@@ -30,7 +30,7 @@ export declare const denyAllTerminalCreatePolicy: ToolPolicy;
  * package (`@jini-ai/daemon`) actually declares — this is exactly the
  * resolver injection seam `spawnHelperCandidatePaths` was built for.
  */
-export declare function loadRealSpawnPty(): Promise<PtySpawn>;
+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;
@@ -81,17 +81,49 @@ export type TerminalSessionActionResult = {
 export type TerminalSessionAttachResult = 'attached' | 'ended' | 'not-found';
 export interface TerminalSessionManager {
     /** The one call gated through `ToolExecutor` (see module doc §2) — this method is what `createTerminalToolRegistrations`'s handler calls, never invoked directly by a route. */
-    create(principal: Principal, options: CreateTerminalSessionOptions): Promise<TerminalSessionInfo>;
-    get(principal: Principal, id: string): TerminalSessionAccessResult;
+    create(args: {
+        readonly principal: Principal;
+        readonly options: CreateTerminalSessionOptions;
+    }): Promise<TerminalSessionInfo>;
+    get(args: {
+        readonly principal: Principal;
+        readonly id: string;
+    }): TerminalSessionAccessResult;
     /** Sessions the given principal owns, optionally narrowed by `resourceRef`. Never returns another principal's sessions. */
-    list(principal: Principal, filter?: TerminalSessionListFilter): readonly TerminalSessionInfo[];
-    write(principal: Principal, id: string, input: string): Promise<TerminalSessionActionResult>;
-    resize(principal: Principal, id: string, cols: number, rows: number): Promise<TerminalSessionActionResult>;
-    kill(principal: Principal, id: string, signal?: string): Promise<TerminalSessionActionResult>;
+    list(args: {
+        readonly principal: Principal;
+    }, optionalArgs?: {
+        readonly filter?: TerminalSessionListFilter;
+    }): readonly TerminalSessionInfo[];
+    write(args: {
+        readonly principal: Principal;
+        readonly id: string;
+        readonly input: string;
+    }): Promise<TerminalSessionActionResult>;
+    resize(args: {
+        readonly principal: Principal;
+        readonly id: string;
+        readonly cols: number;
+        readonly rows: number;
+    }): Promise<TerminalSessionActionResult>;
+    kill(args: {
+        readonly principal: Principal;
+        readonly id: string;
+    }, optionalArgs?: {
+        readonly signal?: string;
+    }): Promise<TerminalSessionActionResult>;
     /** Replays scrollback after `lastEventId` and attaches `sink` for live output — ownership-checked the same as `write`/`resize`/`kill`, since reading a session's output is exactly as sensitive as writing to it. */
-    attach(principal: Principal, id: string, lastEventId: number, sink: TerminalSseSink): TerminalSessionAttachResult;
+    attach(args: {
+        readonly principal: Principal;
+        readonly id: string;
+        readonly lastEventId: number;
+        readonly sink: TerminalSseSink;
+    }): TerminalSessionAttachResult;
     /** No ownership check: removing a sink that was never attached (e.g. a foreign/unknown id) is already a safe no-op at the `@jini-ai/platform` layer, and detach carries no capability of its own. */
-    detach(id: string, sink: TerminalSseSink): void;
+    detach(args: {
+        readonly id: string;
+        readonly sink: TerminalSseSink;
+    }): void;
     shutdownActive(options?: {
         graceMs?: number;
     }): Promise<void>;
@@ -115,7 +147,7 @@ export interface CreateTerminalSessionManagerOptions {
  * the kill/write/resize lock, and (via {@link createTerminalToolRegistrations})
  * `ToolExecutor` gating for creation. See module doc for the full design.
  */
-export declare function createTerminalSessionManager(options?: CreateTerminalSessionManagerOptions): TerminalSessionManager;
+export declare function createTerminalSessionManager(requiredArgs: Record<string, never>, optionalArgs?: Pick<CreateTerminalSessionManagerOptions, "terminalService" | "loadSpawnPty" | "maxEvents" | "maxBufferBytes" | "exitTailBytes" | "flushIntervalMs" | "flushThresholdBytes" | "ttlMs" | "shutdownGraceMs">): TerminalSessionManager;
 export interface CreateTerminalToolRegistrationsOptions {
     readonly manager: TerminalSessionManager;
     /** @default {@link denyAllTerminalCreatePolicy} — see its doc for why a permissive default was rejected. */
@@ -135,5 +167,5 @@ export interface TerminalToolRegistrations {
  * audit trail (matching `db-ops.ts`'s `createDaemonDbToolRegistrations`
  * precedent).
  */
-export declare function createTerminalToolRegistrations(options: CreateTerminalToolRegistrationsOptions): TerminalToolRegistrations;
+export declare function createTerminalToolRegistrations(requiredArgs: Pick<CreateTerminalToolRegistrationsOptions, "manager">, optionalArgs?: Pick<CreateTerminalToolRegistrationsOptions, "policy" | "requiresConfirmation" | "timeoutMs">): TerminalToolRegistrations;
 //# sourceMappingURL=terminal-session.d.ts.map