@jini-ai/daemon 0.6.15 → 0.6.16

package/dist/http/frontend-guest-scope.js

@@ -0,0 +1,63 @@
+/** Opaque guest cookie plus independently minted document credential for public frontends. */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { timingSafeTokenMatch } from '@jini-ai/core';
+/** Per-instance keys isolate visitor control from every other frontend registry.
+ * Tokens are bounded and expire; never put either credential in URLs or diagnostics.
+ * O(1) bounded cookie/token parsing and signing, no persistent guest database. */
+export function createFrontendGuestScope({ workspaceId, cookieName, cookiePath, allowsRequest }, { now = Date.now, lifetimeMs = 30 * 60_000 } = {}) {
+    const key = randomBytes(32);
+    const sign = (text) => createHmac('sha256', key).update(text).digest('base64url');
+    const mint = (value) => { const payload = Buffer.from(JSON.stringify(value)).toString('base64url'); return `${payload}.${sign(payload)}`; };
+    function read(value) {
+        if (value.length > 1024)
+            return null;
+        const parts = value.split('.');
+        if (parts.length !== 2)
+            return null;
+        const [payload, signature] = parts;
+        if (!payload || !signature)
+            return null;
+        const expected = sign(payload);
+        // The shared matcher checks UTF-8 byte lengths before native comparison can throw.
+        if (!timingSafeTokenMatch({ presented: signature, expected, timingSafeEqual: ({ left, right }) => timingSafeEqual(left, right) }))
+            return null;
+        try {
+            const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+            return typeof parsed.expires === 'number' && parsed.expires > now() ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    function guest(req) {
+        const cookie = (req.get('cookie') ?? '').split(';').map(part => part.trim()).find(part => part.startsWith(`${cookieName}=`));
+        const value = read(cookie?.slice(cookieName.length + 1) ?? '');
+        return value?.kind === 'guest' && typeof value.guest === 'string' ? value.guest : undefined;
+    }
+    return {
+        /** Authenticate the cookie independently of a tab for credential-minting budgets. */
+        async resolveGuest({ req }, _options = {}) {
+            return await allowsRequest({ req }) ? guest(req) : undefined;
+        },
+        async issue({ req, res }, _options = {}) {
+            if (!await allowsRequest({ req }))
+                return null;
+            const principalId = guest(req) ?? randomBytes(24).toString('base64url');
+            const expires = now() + lifetimeMs;
+            // A JS-readable tab token must never authenticate as the HttpOnly guest cookie.
+            res.cookie(cookieName, mint({ kind: 'guest', guest: principalId, expires }), { httpOnly: true, sameSite: 'strict', secure: req.secure, path: cookiePath, maxAge: lifetimeMs });
+            res.setHeader('Cache-Control', 'no-store');
+            return { tabCredential: mint({ kind: 'tab', guest: principalId, tab: randomBytes(24).toString('base64url'), expires }) };
+        },
+        async resolveOwner({ req }, _options = {}) {
+            if (!await allowsRequest({ req }))
+                return null;
+            const principalId = guest(req);
+            const tab = read(req.get('x-frontend-tab') ?? '');
+            if (!principalId || tab?.kind !== 'tab' || tab.guest !== principalId || typeof tab.tab !== 'string')
+                return null;
+            return { workspaceId, principalId, tabId: tab.tab };
+        },
+    };
+}
+//# sourceMappingURL=frontend-guest-scope.js.map

package/dist/http/frontend-sessions.d.ts

@@ -1,5 +1,6 @@
+import type { ToolApprovalDecision } from '@jini-ai/core';
 import type { Express, Request, Response } from 'express';
-import type { FrontendSessionRegistry } from '../index.js';
+import type { FrontendSessionRegistry, FrontendSessionOwner } from '../frontend-session-registry.js';
 import { type AdapterContext } from '@jini-ai/http-kit';
 export declare const FRONTEND_SESSION_STREAM_ROUTE_PATH = "/api/frontend-sessions/stream";
 export declare const FRONTEND_SESSION_RESPONSE_ROUTE_PATH = "/api/frontend-sessions/:sessionId/responses";
@@ -29,7 +30,10 @@ export interface FrontendSessionErrorEvent {
     readonly type: 'error';
     readonly message: string;
 }
-export type FrontendSessionStreamEvent = FrontendSessionAttachedEvent | FrontendSessionInvocationEvent | FrontendSessionErrorEvent;
+export type FrontendSessionStreamEvent = {
+    readonly type: 'cancelled';
+    readonly invocationId: string;
+} | FrontendSessionAttachedEvent | FrontendSessionInvocationEvent | FrontendSessionErrorEvent;
 /**
  * A surface's answer, as a discriminated union rather than a flat record with two optional fields.
  *
@@ -40,6 +44,11 @@ export type FrontendSessionStreamEvent = FrontendSessionAttachedEvent | Frontend
  * to fabricate an impossible input.
  */
 export type FrontendSessionResponseRequest = {
+    readonly sessionId: string;
+    readonly invocationId: string;
+    readonly phase: 'approval-pending' | 'execution-started';
+    readonly decision?: ToolApprovalDecision;
+} | {
     readonly sessionId: string;
     readonly invocationId: string;
     readonly ok: true;
@@ -56,6 +65,20 @@ export interface FrontendSessionResponseBody {
 }
 export interface FrontendSessionsHttpDeps {
     readonly registry: FrontendSessionRegistry;
+    /** An isolated public instance supplies its own endpoints and authenticated guest/tab owner. */
+    readonly routePrefix?: string;
+    /** Must authenticate same-origin metadata as well as credentials on every request. */
+    readonly resolveOwner?: (args: {
+        req: Request;
+        res: Response;
+    }) => Promise<FrontendSessionOwner | null>;
+    readonly allowedCapabilities?: readonly string[];
+    readonly sessionTtlMs?: number;
+    /** Trusted quota identities supplied by the host, not query parameters. */
+    readonly resolveCapacityKeys?: (args: {
+        req: Request;
+        owner?: FrontendSessionOwner;
+    }) => readonly string[];
     /**
      * Mints session ids. Defaults to `randomUUID`. A surface never supplies its own: an id the
      * caller chose could collide with, or deliberately impersonate, a session already attached.
@@ -79,14 +102,14 @@ export declare function parseCapabilityQuery({ raw }: {
 /**
  * Handles one surface's stream from open to close.
  *
- * SSE commits `text/event-stream` headers before anything else can be known, so a bad request is
- * reported as one `{type:'error'}` data event and then closed — there is no status-code channel
- * left. Same precedent as `run-stream.ts`.
+ * Invalid capability queries use a final SSE error event. Capacity admission happens before
+ * opening the stream so resource refusals retain a real HTTP status and create no connection.
  */
-export declare function handleFrontendSessionStream({ req, res, deps }: {
+export declare function handleFrontendSessionStream({ req, res, deps, owner }: {
     readonly req: Request;
     readonly res: Response;
     readonly deps: FrontendSessionsHttpDeps;
+    readonly owner?: FrontendSessionOwner;
 }, _optional?: Record<string, never>): void;
 /**
  * `POST /api/frontend-sessions/:sessionId/responses` — delivers a surface's answer to the tool

package/dist/http/frontend-sessions.js

@@ -30,6 +30,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
+import { FrontendSessionCapacityError } from '../frontend-session-registry.js';
 import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
 import { guardSameOrigin } from '@jini-ai/http-kit';
 import { createSseResponse } from '@jini-ai/http-kit';
@@ -72,20 +73,34 @@ export function parseCapabilityQuery({ raw }, _optional = {}) {
 /**
  * Handles one surface's stream from open to close.
  *
- * SSE commits `text/event-stream` headers before anything else can be known, so a bad request is
- * reported as one `{type:'error'}` data event and then closed — there is no status-code channel
- * left. Same precedent as `run-stream.ts`.
+ * Invalid capability queries use a final SSE error event. Capacity admission happens before
+ * opening the stream so resource refusals retain a real HTTP status and create no connection.
  */
-export function handleFrontendSessionStream({ req, res, deps }, _optional = {}) {
-    const capabilities = parseCapabilityQuery({ raw: req.query['capability'] });
+export function handleFrontendSessionStream({ req, res, deps, owner }, _optional = {}) {
+    const requested = parseCapabilityQuery({ raw: req.query['capability'] });
+    const capabilities = requested?.filter(id => !deps.allowedCapabilities || deps.allowedCapabilities.includes(id)) ?? null;
     // Assigned below, after the connection exists — `attach` needs something to deliver through, and
     // `onClose` has to be armed before then so a connection that dies during setup still detaches.
     let handle;
-    const connection = createSseResponse({ req, res }, {
-        // Detach on close rather than on an explicit teardown call: this fires for a closed tab and a
-        // dropped connection too, which an unregister route would not.
-        onClose: () => handle?.detach({}),
-    });
+    let expiry;
+    // Reserve capacity before committing SSE headers, so a full scope gets a real 429.
+    // Delivery cannot occur until the attached token has been sent to the client.
+    let connection;
+    if (capabilities !== null) {
+        handle = attachFrontendSession({ req, deps, capabilities, owner,
+            deliver: invocation => connection.send({ data: { type: 'invocation', ...invocation } }),
+            cancel: ({ invocationId }) => connection.send({ data: { type: 'cancelled', invocationId } }) });
+    }
+    try {
+        connection = createSseResponse({ req, res }, {
+            // Close and expiry release the same quota reservation, without a separate counter lifecycle.
+            onClose: () => { clearTimeout(expiry); handle?.detach({}); },
+        });
+    }
+    catch (error) {
+        handle?.detach({});
+        throw error;
+    }
     if (capabilities === null) {
         connection.send({
             data: {
@@ -96,16 +111,22 @@ export function handleFrontendSessionStream({ req, res, deps }, _optional = {})
         connection.close();
         return;
     }
-    const sessionId = (deps.newSessionId ?? randomUUID)();
-    handle = deps.registry.attach({ descriptor: { sessionId, capabilities }, deliver: (invocation) => connection.send({ data: { type: 'invocation', ...invocation } }) });
+    expiry = expireScopedSession({ owner, handle: handle, close: () => connection.close(), ttl: deps.sessionTtlMs });
     connection.send({
         data: {
             type: 'attached',
-            sessionId,
+            sessionId: handle.sessionId,
             bindToken: handle.bindToken,
         }
     });
 }
+/** Reserve the registry's capacity before SSE commits headers. Host keys are never client input. */
+function attachFrontendSession({ req, deps, capabilities, owner, deliver, cancel }) {
+    const sessionId = (deps.newSessionId ?? randomUUID)();
+    const capacityKeys = deps.resolveCapacityKeys?.({ req, ...(owner ? { owner } : {}) });
+    return deps.registry.attach({ descriptor: { sessionId, capabilities, ...(owner ? { owner } : {}), ...(capacityKeys ? { capacityKeys } : {}) },
+        deliver, cancel });
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -120,12 +141,28 @@ function parseFrontendSessionResponse(input) {
     if (typeof invocationId !== 'string' || invocationId.trim().length === 0) {
         return err({ error: validationError({ message: 'invocationId must be a non-empty string' }, { issues: [{ path: 'invocationId', message: 'required non-empty string' }] }) });
     }
-    const okFlag = input.body['ok'];
+    return parseResponseOutcome({ sessionId, invocationId, body: input.body });
+}
+/** Progress is scoped to a pending invocation; only fixed, value-free decisions enter the audit. */
+function parseApprovalProgress({ sessionId, invocationId, phase, decision }, _options = {}) {
+    if (decision === undefined)
+        return ok({ value: { sessionId, invocationId, phase } });
+    if (phase !== 'execution-started' || typeof decision !== 'string' || !['approved', 'declined', 'expired', 'abandoned'].includes(decision)) {
+        return err({ error: validationError({ message: 'invalid approval decision' }) });
+    }
+    return ok({ value: { sessionId, invocationId, phase, decision: decision } });
+}
+/** Identity parsing precedes outcome parsing so progress and results share exactly one scope. */
+function parseResponseOutcome({ sessionId, invocationId, body }, _options = {}) {
+    const phase = body['phase'];
+    if (phase === 'approval-pending' || phase === 'execution-started')
+        return parseApprovalProgress({ sessionId, invocationId, phase, decision: body['decision'] });
+    const okFlag = body['ok'];
     if (typeof okFlag !== 'boolean') {
         return err({ error: validationError({ message: 'ok must be a boolean' }, { issues: [{ path: 'ok', message: 'required boolean' }] }) });
     }
     if (!okFlag) {
-        const message = input.body['message'];
+        const message = body['message'];
         if (typeof message !== 'string' || message.trim().length === 0) {
             // A failure with no reason gives the agent nothing to act on, which is how a caller ends up
             // retrying the same refusal forever.
@@ -133,7 +170,7 @@ function parseFrontendSessionResponse(input) {
         }
         return ok({ value: { sessionId, invocationId, ok: false, message } });
     }
-    return ok({ value: { sessionId, invocationId, ok: true, output: input.body['output'] } });
+    return ok({ value: { sessionId, invocationId, ok: true, output: body['output'] } });
 }
 /**
  * `POST /api/frontend-sessions/:sessionId/responses` — delivers a surface's answer to the tool
@@ -142,6 +179,8 @@ function parseFrontendSessionResponse(input) {
  */
 export const frontendSessionResponseRoute = defineJsonRoute({
     method: 'post', path: FRONTEND_SESSION_RESPONSE_ROUTE_PATH, parse: parseFrontendSessionResponse, handle: ({ input, deps }) => {
+        if ('phase' in input)
+            return ok({ value: { settled: deps.registry.progress({ sessionId: input.sessionId, invocationId: input.invocationId, pending: input.phase === 'approval-pending', ...(input.decision ? { decision: input.decision } : {}) }) } });
         const settled = deps.registry.settle({ sessionId: input.sessionId, invocationId: input.invocationId, outcome: input.ok
                 ? { ok: true, output: input.output }
                 : { ok: false, message: input.message } });
@@ -157,26 +196,65 @@ export const frontendSessionResponseRoute = defineJsonRoute({
  * never gets a stream (and, notably, never mints a session id or `bindToken` either).
  */
 export function registerFrontendSessionRoutes({ app, deps, adapter }, _optional = {}) {
-    app.get(FRONTEND_SESSION_STREAM_ROUTE_PATH, (req, res) => {
-        const origin = guardSameOrigin({ req, origin: adapter });
+    const prefix = deps.routePrefix ?? '/api/frontend-sessions';
+    app.get(`${prefix}/stream`, async (req, res) => {
+        // Scoped hosts authenticate origin together with guest/tab ownership in resolveOwner.
+        const origin = deps.resolveOwner ? ok({ value: undefined }) : guardSameOrigin({ req, origin: adapter });
         if (!origin.ok) {
             sendApiError({ res, status: statusForError({ error: origin.error }), error: origin.error });
             return;
         }
         try {
-            handleFrontendSessionStream({ req, res, deps });
+            const owner = deps.resolveOwner ? await deps.resolveOwner({ req, res }) : undefined;
+            if (owner === null) {
+                res.sendStatus(403);
+                return;
+            }
+            handleFrontendSessionStream({ req, res, deps, ...(owner ? { owner } : {}) });
         }
         catch (error) {
-            reportInternalError(deps, 'stream', error);
-            if (res.headersSent) {
-                if (!res.writableEnded)
-                    res.end();
-            }
-            else {
-                res.status(500).json({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }) });
-            }
+            endStreamOnError({ error, res, deps });
         }
     });
-    mountJsonRoute({ app, spec: frontendSessionResponseRoute, deps, adapter });
+    const responsePath = `${prefix}/:sessionId/responses`;
+    if (deps.resolveOwner)
+        app.post(responsePath, async (req, res, next) => {
+            try {
+                const owner = await deps.resolveOwner({ req, res });
+                const bindToken = req.get('x-frontend-bind-token') ?? '';
+                if (!owner || !deps.registry.ownsSession({ sessionId: String(req.params['sessionId']), owner, bindToken })) {
+                    res.sendStatus(403);
+                    return;
+                }
+                next();
+            }
+            catch {
+                res.sendStatus(403);
+            }
+        });
+    mountJsonRoute({ app, spec: { ...frontendSessionResponseRoute, path: responsePath, requireSameOrigin: !deps.resolveOwner }, deps, adapter });
+}
+/** Capacity is ordinary admission refusal, not a loggable internal failure. */
+function endStreamOnError({ error, res, deps }) {
+    if (error instanceof FrontendSessionCapacityError && !res.headersSent) {
+        res.sendStatus(429);
+        return;
+    }
+    reportInternalError(deps, 'stream', error);
+    if (res.headersSent) {
+        if (!res.writableEnded)
+            res.end();
+    }
+    else {
+        res.status(500).json({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }) });
+    }
+}
+/** Expiry tears down addressing and the stream together, including clients which never disconnect. */
+function expireScopedSession({ owner, handle, close, ttl = 30 * 60_000 }) {
+    if (!owner)
+        return undefined;
+    const timer = setTimeout(() => { handle.detach({}); close(); }, ttl);
+    timer.unref();
+    return timer;
 }
 //# sourceMappingURL=frontend-sessions.js.map

package/dist/http/index.d.ts

@@ -57,4 +57,5 @@ export { ATTACHMENT_LOOKUP_ROUTE_PATH, registerAttachmentLookupRoutes } from './
 export type { RemoteAttachmentLookupOptional, RemoteAttachmentLookupRequired } from '../remote-attachment-lookup.js';
 export { createRemoteAttachmentLookup } from '../remote-attachment-lookup.js';
 export { createTavilyResearchProvider } from './research-tavily.adapter.js';
+export { createFrontendGuestScope } from './frontend-guest-scope.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -30,4 +30,5 @@ export { DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR, regi
 export { ATTACHMENT_LOOKUP_ROUTE_PATH, registerAttachmentLookupRoutes } from './attachment-lookup-routes.js';
 export { createRemoteAttachmentLookup } from '../remote-attachment-lookup.js';
 export { createTavilyResearchProvider } from './research-tavily.adapter.js';
+export { createFrontendGuestScope } from './frontend-guest-scope.js';
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -72,8 +72,8 @@
  *   solution belongs at the lifecycle or transport boundary, rather than a
  *   restart-unsafe recorder cache that makes the two paths disagree.
  *
- * node-pty uses native addons. Linux deployment requires python3, make and a
- * C/C++ compiler during installation; source compilation is the fallback.
+ * The opt-in @jini-ai/daemon/terminal adapter uses node-pty's native addon.
+ * Linux hosts selecting it need python3, make and a C/C++ compiler for fallback compilation.
  * Vendoring foreign prebuilt binaries would create an unowned maintenance burden.
  * See the owning modules and packages/daemon/README.md for detailed contracts.
  */

package/dist/index.js

@@ -72,8 +72,8 @@
  *   solution belongs at the lifecycle or transport boundary, rather than a
  *   restart-unsafe recorder cache that makes the two paths disagree.
  *
- * node-pty uses native addons. Linux deployment requires python3, make and a
- * C/C++ compiler during installation; source compilation is the fallback.
+ * The opt-in @jini-ai/daemon/terminal adapter uses node-pty's native addon.
+ * Linux hosts selecting it need python3, make and a C/C++ compiler for fallback compilation.
  * Vendoring foreign prebuilt binaries would create an unowned maintenance burden.
  * See the owning modules and packages/daemon/README.md for detailed contracts.
  */

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);

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,

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