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

package/dist/frontend-session-registry.js

@@ -46,6 +46,34 @@
  *    so the existing `timeoutMs` on a tool descriptor covers this for free.
  */
 import { randomUUID } from 'node:crypto';
+/** Shared owner comparison for attachment, binding and human-only reply gates. */
+export function sameFrontendOwner({ expected: a, actual: b }, _options = {}) {
+    if (!a || !b)
+        return a === b;
+    return a.workspaceId === b.workspaceId && a.principalId === b.principalId && a.tabId === b.tabId;
+}
+/** Expected admission refusal; HTTP maps it to a quiet 429 before opening SSE. */
+export class FrontendSessionCapacityError extends Error {
+    constructor() { super('Frontend session capacity reached'); this.name = 'FrontendSessionCapacityError'; }
+}
+/** Admission is synchronous with attach, so concurrent opens cannot oversubscribe a scope.
+ * O(s × k) over the bounded live sessions and the host's quota keys; no retained IP counters.
+ * Detach automatically releases capacity, including stale handles and expired connections. */
+function assertSessionCapacity({ sessions, descriptor, options }) {
+    if (options.maxSessions !== undefined && sessions.size >= options.maxSessions)
+        throw new FrontendSessionCapacityError();
+    if (options.maxSessionsPerKey === undefined)
+        return;
+    for (const key of descriptor.capacityKeys ?? []) {
+        let count = 0;
+        for (const session of sessions.values()) {
+            if (session.descriptor.capacityKeys?.includes(key))
+                count++;
+        }
+        if (count >= options.maxSessionsPerKey)
+            throw new FrontendSessionCapacityError();
+    }
+}
 /**
  * Creates an in-memory registry of attached surfaces.
  *
@@ -53,8 +81,8 @@ import { randomUUID } from 'node:crypto';
  * so it cannot outlive the process that holds it, and a restart correctly presents as "nothing
  * attached" rather than as a stale route to a tab that is long gone.
  *
- * @complexity Every operation is O(1) except `detach`, which is O(p + b) in that surface\'s pending
- * invocations and bound runs.
+ * @complexity `attach` checks O(s × k) live sessions/quota keys when limits are configured;
+ * `detach` is O(p + b) in pending invocations and bound runs. Other addressing operations are O(1).
  */
 export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
     const options = { ...requiredArgs, ...optionalArgs };
@@ -106,11 +134,12 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
         }
         return session;
     }
-    function attach({ descriptor, deliver }) {
+    function attach({ descriptor, deliver, cancel }) {
+        assertSessionCapacity({ sessions, descriptor, options });
         if (sessions.has(descriptor.sessionId)) {
             throw new Error(`FrontendSessionRegistry: session "${descriptor.sessionId}" is already attached`);
         }
-        const session = { descriptor, deliver, pending: new Map() };
+        const session = { descriptor, deliver, ...(cancel ? { cancel } : {}), pending: new Map() };
         sessions.set(descriptor.sessionId, session);
         const bindToken = newBindToken();
         bindTokens.set(bindToken, descriptor.sessionId);
@@ -133,6 +162,7 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
                 }
                 for (const [, entry] of session.pending) {
                     entry.dispose();
+                    entry.onApprovalStateChange?.({ pending: false });
                     entry.reject(new Error(`frontend session "${descriptor.sessionId}" detached before answering`));
                 }
                 session.pending.clear();
@@ -153,12 +183,12 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
                 runBindings.delete(runId);
         };
     }
-    function bindRunByToken({ runId, bindToken }) {
+    function bindRunByToken({ runId, bindToken, owner }) {
         const sessionId = bindTokens.get(bindToken);
         // One message for both "no such token" and "the surface holding it detached". Distinguishing
         // them tells a caller whether a guess was close, which is the feedback a probe needs and the
         // only feedback it needs.
-        if (sessionId === undefined) {
+        if (sessionId === undefined || !sameFrontendOwner({ expected: sessions.get(sessionId)?.descriptor.owner, actual: owner })) {
             throw new Error(`FrontendSessionRegistry: cannot bind run "${runId}" — unknown or expired bind token`);
         }
         return bindRun({ runId: runId, sessionId: sessionId });
@@ -167,13 +197,18 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
     // every other failure here. Throwing synchronously out of a Promise-returning function would
     // make `invoke(...).catch(...)` an uncaught exception for exactly the fail-closed cases this
     // registry exists to report.
-    async function invoke({ runId, capabilityId, input }, { signal } = {}) {
+    async function invoke({ runId, capabilityId, input }, { signal, onApprovalStateChange } = {}) {
         const target = resolveTarget(runId, capabilityId);
         const invocationId = newInvocationId();
         return new Promise((resolve, reject) => {
             const cancelled = () => new Error(`"${capabilityId}" was cancelled before the frontend answered`);
             const onAbort = () => {
                 target.pending.delete(invocationId);
+                try {
+                    target.cancel?.({ invocationId });
+                }
+                catch { /* A closed channel cannot revive the action. */ }
+                onApprovalStateChange?.({ pending: false });
                 reject(cancelled());
             };
             const dispose = () => signal?.removeEventListener('abort', onAbort);
@@ -182,7 +217,7 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
                 return;
             }
             signal?.addEventListener('abort', onAbort, { once: true });
-            target.pending.set(invocationId, { resolve, reject, dispose });
+            target.pending.set(invocationId, { resolve, reject, dispose, ...(onApprovalStateChange ? { onApprovalStateChange } : {}) });
             try {
                 target.deliver({ invocationId, capabilityId, input });
             }
@@ -190,10 +225,23 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
                 // A dead channel must fail the call rather than leave it pending until the tool times out.
                 target.pending.delete(invocationId);
                 dispose();
+                onApprovalStateChange?.({ pending: false });
                 reject(error instanceof Error ? error : new Error(String(error)));
             }
         });
     }
+    function progress({ sessionId, invocationId, pending, decision }) {
+        const entry = sessions.get(sessionId)?.pending.get(invocationId);
+        if (!entry)
+            return false;
+        // Only the first outcome following a real wait is recorded; replayed frames are observation-free.
+        const settledDecision = entry.approvalPending && !pending ? decision : undefined;
+        if (settledDecision)
+            entry.approvalRecorded = true;
+        entry.approvalPending = pending && !entry.approvalRecorded;
+        entry.onApprovalStateChange?.({ pending, ...(settledDecision ? { decision: settledDecision } : {}) });
+        return true;
+    }
     function settle({ sessionId, invocationId, outcome }) {
         const session = sessions.get(sessionId);
         const entry = session?.pending.get(invocationId);
@@ -201,6 +249,7 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
             return false;
         session.pending.delete(invocationId);
         entry.dispose();
+        entry.onApprovalStateChange?.({ pending: false });
         if (outcome.ok)
             entry.resolve(outcome.output);
         else
@@ -213,6 +262,9 @@ export function createFrontendSessionRegistry(requiredArgs, optionalArgs = {}) {
     function capabilitiesFor({ runId }) {
         return sessionFor({ runId: runId })?.capabilities ?? [];
     }
-    return { attach, bindRun, bindRunByToken, invoke, settle, capabilitiesFor, sessionFor };
+    function ownsSession({ sessionId, owner, bindToken }) {
+        return bindTokens.get(bindToken) === sessionId && sameFrontendOwner({ expected: sessions.get(sessionId)?.descriptor.owner, actual: owner });
+    }
+    return { attach, bindRun, bindRunByToken, invoke, settle, progress, capabilitiesFor, sessionFor, ownsSession };
 }
 //# sourceMappingURL=frontend-session-registry.js.map

package/dist/http/agents.d.ts

@@ -51,6 +51,10 @@ export interface AgentSummary {
      * as `true` (no known reason to warn) rather than assuming the worst.
      */
     readonly supportsTools?: boolean;
+    /** Project the runtime definition so picker preflight agrees with launch enforcement. */
+    readonly supportsNativeToolAccess?: boolean;
+    readonly fullCliAccessOnly?: boolean;
+    readonly fullCliAccessNote?: string;
 }
 export interface AgentsHttpDeps {
     /** Returns the host's cached or freshly resolved client-safe agent inventory. */

package/dist/http/attachments.js

@@ -284,13 +284,12 @@ const SIGNATURE_BYTES = FTYP_COMPATIBLE_BRANDS_OFFSET + MAX_SCANNED_COMPATIBLE_B
  * production is a check nobody knows works — a fake identity states each case directly.
  */
 export function isUnchangedAttachment({ recorded, observed }, _optional = {}) {
-    return observed.isRegularFile
-        && observed.canonicalPath === recorded.filePath
-        && observed.dev === recorded.dev
-        && observed.ino === recorded.ino
-        && observed.size === recorded.size
-        && (recorded.mtimeMs === undefined || observed.mtimeMs === recorded.mtimeMs)
+    const sameFile = observed.isRegularFile && observed.canonicalPath === recorded.filePath
+        && observed.dev === recorded.dev && observed.ino === recorded.ino;
+    // A recorded timestamp must still hold; one never recorded cannot disagree.
+    const sameTimes = (recorded.mtimeMs === undefined || observed.mtimeMs === recorded.mtimeMs)
         && (recorded.ctimeMs === undefined || observed.ctimeMs === recorded.ctimeMs);
+    return sameFile && observed.size === recorded.size && sameTimes;
 }
 /**
  * Phase 1 of `claim()`: synchronously reserves `attachments` for `runId`, or throws (releasing
@@ -384,13 +383,15 @@ export function sanitizeAttachmentName({ requestedName }, _optional = {}) {
         return 'attachment';
     return basename(requestedName).replaceAll(/[^a-zA-Z0-9._ -]/gu, '_') || 'attachment';
 }
+/** An attachment no run has claimed, or one claimed by `runId` (never by an absent run id). */
+function isUnclaimedOrClaimedBy(claimedRunId, runId) {
+    return claimedRunId === undefined || (runId !== undefined && claimedRunId === runId);
+}
+/** The complete PNG signature includes the CR/LF and control-byte corruption markers. */
+const PNG_SIGNATURE_PREFIX = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
 /** `true` when `body`'s first 8 bytes are the PNG signature. */
 export function hasPngSignature({ body }, _optional = {}) {
-    return body.length >= 8
-        && body[0] === 0x89
-        && body[1] === 0x50
-        && body[2] === 0x4e
-        && body[3] === 0x47;
+    return body.length >= 8 && PNG_SIGNATURE_PREFIX.every((byte, index) => body[index] === byte);
 }
 /** `true` when `body`'s first 3 bytes are the JPEG start-of-image marker. */
 export function hasJpegSignature({ body }, _optional = {}) {
@@ -934,7 +935,7 @@ export async function createDiskAttachmentStore(requiredArgs, optionalArgs = {})
                 // what makes an ownerless record excluded rather than accidentally matched by a falsy-ish
                 // `ownerId` argument — see this method's own doc on why that must never be a wildcard.
                 .filter((record) => record.ownerId !== undefined && record.ownerId === ownerId
-                && (record.claimedRunId === undefined || (runId !== undefined && record.claimedRunId === runId)))
+                && isUnclaimedOrClaimedBy(record.claimedRunId, runId))
                 .sort((a, b) => a.createdAt - b.createdAt)
                 .map((record) => ({ ref: record.id, name: record.name, kind: record.kind, size: record.size, createdAt: record.createdAt }));
         },

package/dist/http/component-catalog.js

@@ -12,7 +12,7 @@ function parseSearchInput(input) {
     const rawLimit = input.query.limit;
     if (rawLimit === undefined)
         return ok({ value: { query: rawQuery, limit: DEFAULT_SEARCH_LIMIT } });
-    if (typeof rawLimit !== 'string' || !/^[0-9]+$/.test(rawLimit)) {
+    if (typeof rawLimit !== 'string' || !/^\d+$/.test(rawLimit)) {
         return err({ error: validationError({ message: 'limit must be a single positive-integer query-string value when provided' }) });
     }
     const parsed = Number(rawLimit);

package/dist/http/connectors.js

@@ -49,6 +49,8 @@ import { createApiError } from '@jini-ai/protocol';
 import { ClientFacingError, defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
 import { validationError } from '@jini-ai/http-kit';
 import { err, ok } from '@jini-ai/http-kit';
+/** Validation message for a request body that is not a JSON object. */
+const BODY_NOT_OBJECT_MESSAGE = 'body must be a JSON object';
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
     console.error(`[@jini-ai/http-kit] internal error (connectors/${context.source}.${context.operation}, correlationId=${context.correlationId})`, context.error);
@@ -86,7 +88,7 @@ function firstQueryValue(raw) {
 // ---------------------------------------------------------------------------
 function parseAuthCredentials(input) {
     if (!isRecord(input.body))
-        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+        return err({ error: validationError({ message: BODY_NOT_OBJECT_MESSAGE }) });
     const email = nonEmptyString(input.body.email);
     if (!email)
         return err({ error: validationError({ message: 'email must be a non-empty string' }, { issues: [{ path: 'email', message: 'required non-empty string' }] }) });
@@ -97,7 +99,7 @@ function parseAuthCredentials(input) {
 }
 function parseAuthToken(input) {
     if (!isRecord(input.body))
-        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+        return err({ error: validationError({ message: BODY_NOT_OBJECT_MESSAGE }) });
     const token = nonEmptyString(input.body.token);
     if (!token)
         return err({ error: validationError({ message: 'token must be a non-empty string' }, { issues: [{ path: 'token', message: 'required non-empty string' }] }) });
@@ -164,7 +166,7 @@ function parseStoragePut(input) {
     if (!keyResult.ok)
         return keyResult;
     if (!isRecord(input.body))
-        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+        return err({ error: validationError({ message: BODY_NOT_OBJECT_MESSAGE }) });
     const dataBase64 = input.body.dataBase64;
     if (typeof dataBase64 !== 'string' || !isWellFormedBase64(dataBase64)) {
         return err({ error: validationError({ message: 'dataBase64 must be a non-empty base64-encoded string' }, { issues: [{ path: 'dataBase64', message: 'required base64 string' }] }) });
@@ -231,7 +233,7 @@ function parseDbInsert(input) {
     if (!collectionResult.ok)
         return collectionResult;
     if (!isRecord(input.body))
-        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+        return err({ error: validationError({ message: BODY_NOT_OBJECT_MESSAGE }) });
     const id = input.body.id;
     if (typeof id !== 'string' || id.length === 0) {
         return err({ error: validationError({ message: 'id must be a non-empty string field' }, { issues: [{ path: 'id', message: 'required non-empty string' }] }) });
@@ -252,7 +254,7 @@ function parseDbUpdate(input) {
     if (!parsed.ok)
         return parsed;
     if (!isRecord(input.body))
-        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+        return err({ error: validationError({ message: BODY_NOT_OBJECT_MESSAGE }) });
     return ok({ value: { ...parsed.value, patch: input.body } });
 }
 function parseDbQueryRequest(input) {

package/dist/http/db-ops.js

@@ -138,6 +138,11 @@ function toolResultToApiResult(deps, source, result) {
             sink({ source, correlationId, error: result.status === 'failed' ? result.error : result.status });
             return err({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId }) });
         }
+        default: {
+            // Unreachable: every tool result status has a case above, and a new one fails typecheck here.
+            const unhandled = result.status;
+            throw new TypeError(`Unhandled tool result status: ${String(unhandled)}`);
+        }
     }
 }
 /** `GET /api/daemon/db` — the database inventory (schema version, tables, row counts, size). */

package/dist/http/delegated-tools.js

@@ -144,6 +144,11 @@ function toolExecutionResultToApiResult(deps, { runId, toolId, result }) {
             return err({ error: reportInternalError(deps, { source: 'delegated-tool-execute', error: result.status, runId, toolId, status: result.status }) });
         case 'failed':
             return err({ error: failedResultToApiError(deps, { runId, toolId, result }) });
+        default: {
+            // Unreachable: every tool result status has a case above, and a new one fails typecheck here.
+            const unhandled = result.status;
+            throw new TypeError(`Unhandled tool result status: ${String(unhandled)}`);
+        }
     }
 }
 /** The `failed` arm of {@link toolExecutionResultToApiResult} — see its doc for the three-way split. */

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

@@ -35,6 +35,8 @@
  * their own metadata in it. The engine stays neutral and the host keeps one place to look.
  */
 import type { Express } from 'express';
+import type { FrontendSessionOwner } from '../frontend-session-registry.js';
+import type { FrontendSessionsHttpDeps } from './frontend-sessions.js';
 import type { ToolPolicy, ToolRegistration } from '@jini-ai/core';
 import { type FrontendCapabilitySpec } from '../index.js';
 import type { AdapterContext } from '@jini-ai/http-kit';
@@ -67,6 +69,10 @@ export interface CreateFrontendControlOptions {
      * (see `frontend-capability-tools.ts`'s module doc for why the edge points one way).
      */
     readonly capabilities: readonly FrontendCapabilitySpec[];
+    readonly session?: Pick<FrontendSessionsHttpDeps, 'routePrefix' | 'resolveOwner' | 'sessionTtlMs' | 'resolveCapacityKeys'> & {
+        readonly maxSessions?: number;
+        readonly maxSessionsPerKey?: number;
+    };
     /**
      * Reads this run's bind token out of the host's own run request, or returns `undefined` when the
      * run has no originating surface.
@@ -98,6 +104,13 @@ export interface CreateFrontendControlOptions {
     readonly onBindError?: (context: FrontendBindErrorContext) => void;
 }
 export interface FrontendControl {
+    /** Request-lifetime binding for hosts without daemon runs; release in finally and on cancel. */
+    bindRequest(required: {
+        runId: string;
+        bindToken: string;
+        owner: FrontendSessionOwner;
+        signal: AbortSignal;
+    }, optional?: Record<string, never>): () => void;
     /**
      * Mounts the frontend-session stream and response routes. Pass in `createLocalNodeDaemon`'s
      * `httpExtensions`, or call it directly with `(app, { adapter })` from a host that owns its own

package/dist/http/frontend-control.js

@@ -17,7 +17,10 @@ function defaultBindErrorSink(context) {
 export function createFrontendControl(requiredArgs, optionalArgs = {}) {
     const options = { ...requiredArgs, ...optionalArgs };
     // Closed over, never exposed. See the module doc: reaching this is reaching an ungated `invoke`.
-    const registry = createFrontendSessionRegistry({});
+    const registry = createFrontendSessionRegistry({}, {
+        ...(options.session?.maxSessions !== undefined ? { maxSessions: options.session.maxSessions } : {}),
+        ...(options.session?.maxSessionsPerKey !== undefined ? { maxSessionsPerKey: options.session.maxSessionsPerKey } : {}),
+    });
     const onBindError = options.onBindError ?? defaultBindErrorSink;
     const toolRegistrations = createFrontendCapabilityRegistrations({
         registry,
@@ -28,7 +31,7 @@ export function createFrontendControl(requiredArgs, optionalArgs = {}) {
         ...(options.maxOutputBytes !== undefined ? { maxOutputBytes: options.maxOutputBytes } : {}),
     });
     const httpExtension = ({ app, context }) => {
-        registerFrontendSessionRoutes({ app, deps: { registry }, adapter: context.adapter });
+        registerFrontendSessionRoutes({ app, deps: { registry, ...options.session, allowedCapabilities: options.capabilities.map(c => c.id) }, adapter: context.adapter });
     };
     /**
      * The error boundary the `onBindError` contract actually needs. A `RunStartHandler` throwing is
@@ -74,6 +77,14 @@ export function createFrontendControl(requiredArgs, optionalArgs = {}) {
             .then(release, release)
             .catch(() => undefined);
     };
-    return { httpExtension, toolRegistrations, bindOnStarted };
+    const bindRequest = ({ runId, bindToken, owner, signal }) => {
+        if (signal.aborted)
+            throw new Error('Frontend request cancelled');
+        const unbind = registry.bindRunByToken({ runId, bindToken, owner });
+        const release = () => { signal.removeEventListener('abort', release); unbind(); };
+        signal.addEventListener('abort', release, { once: true });
+        return release;
+    };
+    return { httpExtension, toolRegistrations, bindOnStarted, bindRequest };
 }
 //# sourceMappingURL=frontend-control.js.map

package/dist/http/frontend-guest-scope.d.ts

@@ -0,0 +1,32 @@
+import type { Request, Response } from 'express';
+import type { FrontendSessionOwner } from '../frontend-session-registry.js';
+/** 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 declare function createFrontendGuestScope({ workspaceId, cookieName, cookiePath, allowsRequest }: {
+    workspaceId: string;
+    cookieName: string;
+    cookiePath: string;
+    allowsRequest: (args: {
+        req: Request;
+    }) => Promise<boolean>;
+}, { now, lifetimeMs }?: {
+    now?: () => number;
+    lifetimeMs?: number;
+}): {
+    /** Authenticate the cookie independently of a tab for credential-minting budgets. */
+    resolveGuest({ req }: {
+        req: Request;
+    }, _options?: {}): Promise<string | undefined>;
+    issue({ req, res }: {
+        req: Request;
+        res: Response;
+    }, _options?: {}): Promise<{
+        tabCredential: string;
+    } | null>;
+    resolveOwner({ req }: {
+        req: Request;
+        res?: Response;
+    }, _options?: {}): Promise<FrontendSessionOwner | null>;
+};
+//# sourceMappingURL=frontend-guest-scope.d.ts.map

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