@jini-ai/daemon 0.5.2 → 0.5.4

package/dist/attachment-content.d.ts

@@ -0,0 +1,45 @@
+export interface MessageAttachmentImage {
+    readonly mimeType: string;
+    readonly data: string;
+}
+export interface MessageAttachmentSource {
+    readonly name: string;
+    readonly mimeType: string;
+    readonly bytes: Uint8Array;
+    readonly path?: string;
+}
+export interface MessageAttachmentReader {
+    (required: {
+        ref: string;
+    }, optional: Record<string, never>): Promise<MessageAttachmentSource>;
+}
+/** One byte-bearing message path for CLI and API consumers. The host reader owns authorization,
+ * integrity and MIME sniffing; this module never opens a caller-selected path itself. Unsupported
+ * files are explicit so the model cannot mistake a filename for content it has received. */
+export declare function prepareMessageAttachments({ refs, read }: {
+    refs: readonly string[];
+    read: MessageAttachmentReader;
+}, { fileAccess, imageAccess }?: {
+    fileAccess?: boolean;
+    imageAccess?: boolean;
+}): Promise<{
+    images: MessageAttachmentImage[];
+    imagePaths: string[];
+    notice: string;
+}>;
+/** Stream-JSON runtimes use the same normalized pixels as provider APIs. */
+export declare function messageContentWithImages({ prompt, images }: {
+    prompt: string;
+    images: readonly MessageAttachmentImage[];
+}, _optional?: {}): ({
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+} | {
+    type: "text";
+    text: string;
+})[];
+//# sourceMappingURL=attachment-content.d.ts.map

package/dist/attachment-content.js

@@ -0,0 +1,40 @@
+import { Buffer } from 'node:buffer';
+/** One byte-bearing message path for CLI and API consumers. The host reader owns authorization,
+ * integrity and MIME sniffing; this module never opens a caller-selected path itself. Unsupported
+ * files are explicit so the model cannot mistake a filename for content it has received. */
+export async function prepareMessageAttachments({ refs, read }, { fileAccess = false, imageAccess = true } = {}) {
+    const images = [];
+    const notices = [];
+    const imagePaths = [];
+    for (const ref of refs) {
+        const source = await read({ ref }, {});
+        if (['image/png', 'image/jpeg', 'image/gif', 'image/webp'].includes(source.mimeType)) {
+            if (!imageAccess) {
+                notices.push(`${source.name}: image attachments are unsupported by this runtime.`);
+                continue;
+            }
+            if (source.path)
+                imagePaths.push(source.path);
+            images.push({ mimeType: source.mimeType, data: Buffer.from(source.bytes).toString('base64') });
+            continue;
+        }
+        const video = source.mimeType.startsWith('video/');
+        if (fileAccess && source.path) {
+            notices.push(video
+                ? `${source.name}: video attachments are unsupported by this runtime; the file is available at ${source.path}.`
+                : `${source.name}: read the attached file at ${source.path}.`);
+        }
+        else {
+            notices.push(`${source.name}: ${video ? 'video' : 'file'} attachments are unsupported by this runtime.`);
+        }
+    }
+    return { images, imagePaths, notice: notices.length ? `\n\nAttachments to this message:\n${notices.join('\n')}` : '' };
+}
+/** Stream-JSON runtimes use the same normalized pixels as provider APIs. */
+export function messageContentWithImages({ prompt, images }, _optional = {}) {
+    return [
+        { type: 'text', text: prompt },
+        ...images.map(image => ({ type: 'image', source: { type: 'base64', media_type: image.mimeType, data: image.data } })),
+    ];
+}
+//# sourceMappingURL=attachment-content.js.map

package/dist/core/read-only-tools.d.ts

@@ -0,0 +1,130 @@
+import { type Principal, type ToolRegistry } from '@jini-ai/core';
+import type { ToolExecutor } from '../tool-executor.js';
+import type { IdGenerator } from '@jini-ai/core/primitives';
+/**
+ * A `Principal` narrowed to tools that only read.
+ *
+ * An HTTP route preflight only ever validates the OUTER `toolId` — the one the caller
+ * named in the HTTP request. It cannot see what a consumer's own `ToolExecutor` composition does
+ * once `bridge.execute()` hands control to `deps.toolExecutor`: a decorator that composition
+ * stacks on top of the bare executor (a recovery loop that retries through a different tool id
+ * after a failure, for instance) can dispatch a tool the caller never named, using the exact same
+ * `principal` the outer call carried — one hop past the only check the HTTP route ever ran. Adding a
+ * second request-shaped flag would not close that gap either: it would have to be threaded, by
+ * hand, through every decorator between here and the handler, and a decorator that forgot would
+ * fail open silently. `principal` is the one value every layer already passes unchanged, so the
+ * constraint travels as an ATTENUATED IDENTITY instead — a principal permitted to invoke only
+ * read-only tools, checkable by {@link refuseNonReadOnlyDispatch} at any depth a consumer's own
+ * composition cares to ask.
+ *
+ * A distinct field rather than a `Principal.roles` entry: `roles` is what a `ToolPolicy` branches
+ * on, and a synthetic role would silently join that decision for every registration in the
+ * process. This field is inert to everything except {@link refuseNonReadOnlyDispatch}.
+ */
+export interface ReadOnlyConstrainedPrincipal extends Principal {
+    readonly toolAccess: 'read-only';
+}
+/**
+ * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
+ * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
+ * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
+ */
+export declare const defaultDaemonMessages: {
+    readOnly: {
+        unverifiableMessage: string;
+        toolRefusalMessage: ({ toolId }: {
+            toolId: string;
+        }) => string;
+    };
+};
+/** Required host wording; absent metadata is always a refusal. */
+export interface ReadOnlyToolMessages {
+    readonly unverifiableMessage: string;
+    toolRefusalMessage(required: {
+        toolId: string;
+    }): string;
+}
+export interface ReadOnlyToolCheckRequired {
+    readonly toolId: string;
+    readonly registry: Pick<ToolRegistry, 'list'> | undefined;
+    readonly messages: ReadOnlyToolMessages;
+}
+export interface ReadOnlyToolConstraintRequired {
+    readonly inner: ToolExecutor;
+    readonly registry: Pick<ToolRegistry, 'list'> | undefined;
+    readonly idGenerator: IdGenerator;
+    readonly messages: ReadOnlyToolMessages;
+}
+/** @returns A copied, attenuated principal; its roles are unchanged. */
+export declare function constrainPrincipalToReadOnlyTools({ principal }: {
+    principal: Principal;
+}, _optional?: Record<string, never>): ReadOnlyConstrainedPrincipal;
+/** @returns Whether attenuation survived the executor/decorator boundary. */
+export declare function principalIsReadOnlyConstrained({ principal }: {
+    principal: Principal;
+}, _optional?: Record<string, never>): boolean;
+/** @returns Required host wording for an unknown or non-read-only tool. */
+export declare function readOnlyToolRefusalMessage({ toolId, messages }: {
+    toolId: string;
+    messages: ReadOnlyToolMessages;
+}, _optional?: Record<string, never>): string;
+/**
+ * Single read-only registration decision, shared by routes and inner dispatch.
+ * @returns Null for an explicitly read-only registration, otherwise host refusal text.
+ */
+export declare function checkReadOnlyTool({ toolId, registry, messages }: ReadOnlyToolCheckRequired, _optional?: Record<string, never>): string | null;
+/**
+ * THE read-only dispatch decision for any tool id a consumer's own `ToolExecutor` composition is
+ * about to invoke — the outer call the route already checked, or a nested one a decorator issues
+ * one or more hops in. Every consumer's own composition should ask this before dispatching on
+ * behalf of a principal it did not itself resolve; none should re-implement the check, so changing
+ * what the constraint means stays one edit.
+ *
+ * @param required.principal - The principal the dispatch would run under. Unconstrained ⇒ always
+ *   `null` — this is a no-op for every pre-existing caller that never attenuates a principal.
+ * @param required.toolId - The id actually about to be dispatched, which is not necessarily the id
+ *   named in the original request — that difference is the whole reason this function exists.
+ * @param required.registry - Descriptors to resolve `toolId` against; `undefined` ⇒ refuse (an
+ *   unverifiable constrained dispatch is refused, never waived, matching `checkReadOnlyTool`).
+ * @returns `null` when the dispatch may proceed, otherwise the refusal text to report.
+ * @complexity O(1) for an unconstrained principal; O(n) in registered tool count for a constrained
+ *   one, since `ToolRegistry` exposes enumeration rather than lookup by id.
+ */
+export declare function refuseNonReadOnlyDispatch(required: ReadOnlyToolCheckRequired & {
+    readonly principal: Principal;
+}, _optional?: Record<string, never>): string | null;
+/** @returns Caller-formatted recovery refusal, preserving the original refusal verbatim as input. */
+export declare function readOnlyRemedyRefusalMessage({ refusal, formatMessage }: {
+    refusal: string;
+    formatMessage: (required: {
+        refusal: string;
+    }) => string;
+}, _optional?: Record<string, never>): string;
+/**
+ * Wraps `inner` so a read-only-constrained principal (one {@link constrainPrincipalToReadOnlyTools}
+ * attenuated) cannot dispatch a tool that isn't registered read-only — whichever layer chose the
+ * id. This is what turns the attenuation into an actual gate rather than a field nobody reads:
+ * {@link refuseNonReadOnlyDispatch} is the decision, this is its enforcement point.
+ *
+ * **Compose this as close to the bare `ToolExecutor` as your own stack allows** — directly around
+ * `@jini-ai/daemon`'s `createToolExecutor` output, beneath any decorator of your own that might
+ * dispatch a tool id the caller never named (a retry, a recovery loop that calls a different tool
+ * as a remedy, ...). Every such decorator's own `inner.execute` call still has to come through here
+ * to reach a handler, which is what makes this a gate on the CLASS of defect (an unnamed nested
+ * dispatch) rather than on one instance of it.
+ *
+ * `delegatedToolExecuteRoute`'s own `handle` additionally composes this around whatever
+ * `ToolExecutor` a host supplies, whenever a call attenuates its principal. That outer composition
+ * only re-covers the SAME outer `toolId` the route preflight already checked — it
+ * cannot see a nested dispatch a host's own inner decorator issues, because that decorator holds a
+ * reference to whatever `ToolExecutor` IT was built with, not to the HTTP route's wrapped one. Closing
+ * the nested case for a given host's stack requires that host to compose this decorator itself,
+ * innermost, in its own `ToolExecutor` construction — this export exists so it can, without having
+ * to rediscover or reimplement the mechanism.
+ *
+ * @returns A drop-in `ToolExecutor`; `resumeConfirmation`/`cancel`/`getAuditRecord` delegate
+ *   straight through.
+ * @complexity One extra property read per unconstrained call; one registry scan per constrained one.
+ */
+export declare function withReadOnlyToolConstraint({ inner, registry, idGenerator, messages }: ReadOnlyToolConstraintRequired, _optional?: Record<string, never>): ToolExecutor;
+//# sourceMappingURL=read-only-tools.d.ts.map

package/dist/core/read-only-tools.js

@@ -0,0 +1,115 @@
+import { isReadOnlyTool } from '@jini-ai/core';
+/**
+ * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
+ * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
+ * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
+ */
+export const defaultDaemonMessages = {
+    readOnly: {
+        unverifiableMessage: 'this host cannot verify read-only tools — POST /api/delegated-tool-calls was mounted without DelegatedToolsHttpDeps.toolRegistry, so a requireReadOnly call cannot be checked and is refused',
+        toolRefusalMessage: ({ toolId }) => `tool "${toolId}" is not registered as read-only — this gateway executes only tools whose registration declares readOnly; call it through execute_delegated_tool instead`,
+    },
+};
+/** @returns A copied, attenuated principal; its roles are unchanged. */
+export function constrainPrincipalToReadOnlyTools({ principal }, _optional = {}) {
+    return { ...principal, toolAccess: 'read-only' };
+}
+// Read structurally so passing through layers typed as the base Principal cannot erase the
+// execution's authority constraint.
+/** @returns Whether attenuation survived the executor/decorator boundary. */
+export function principalIsReadOnlyConstrained({ principal }, _optional = {}) {
+    return 'toolAccess' in principal && principal.toolAccess === 'read-only';
+}
+/** @returns Required host wording for an unknown or non-read-only tool. */
+export function readOnlyToolRefusalMessage({ toolId, messages }, _optional = {}) {
+    return messages.toolRefusalMessage({ toolId });
+}
+// Unknown registrations and omitted read-only classification both lack evidence of safety.
+// Every dispatch/preflight consults this decision; recovery preflight prevents asking a human
+// for form input that the innermost gate would refuse after submission.
+/**
+ * Single read-only registration decision, shared by routes and inner dispatch.
+ * @returns Null for an explicitly read-only registration, otherwise host refusal text.
+ */
+export function checkReadOnlyTool({ toolId, registry, messages }, _optional = {}) {
+    if (registry === undefined)
+        return messages.unverifiableMessage;
+    const descriptor = registry.list({}).find((candidate) => candidate.id === toolId);
+    if (isReadOnlyTool({ descriptor }))
+        return null;
+    return readOnlyToolRefusalMessage({ toolId, messages });
+}
+/**
+ * THE read-only dispatch decision for any tool id a consumer's own `ToolExecutor` composition is
+ * about to invoke — the outer call the route already checked, or a nested one a decorator issues
+ * one or more hops in. Every consumer's own composition should ask this before dispatching on
+ * behalf of a principal it did not itself resolve; none should re-implement the check, so changing
+ * what the constraint means stays one edit.
+ *
+ * @param required.principal - The principal the dispatch would run under. Unconstrained ⇒ always
+ *   `null` — this is a no-op for every pre-existing caller that never attenuates a principal.
+ * @param required.toolId - The id actually about to be dispatched, which is not necessarily the id
+ *   named in the original request — that difference is the whole reason this function exists.
+ * @param required.registry - Descriptors to resolve `toolId` against; `undefined` ⇒ refuse (an
+ *   unverifiable constrained dispatch is refused, never waived, matching `checkReadOnlyTool`).
+ * @returns `null` when the dispatch may proceed, otherwise the refusal text to report.
+ * @complexity O(1) for an unconstrained principal; O(n) in registered tool count for a constrained
+ *   one, since `ToolRegistry` exposes enumeration rather than lookup by id.
+ */
+export function refuseNonReadOnlyDispatch(required, _optional = {}) {
+    if (!principalIsReadOnlyConstrained({ principal: required.principal }))
+        return null;
+    return checkReadOnlyTool(required);
+}
+// Report the original failure alongside the refused remedy; silently hiding an automatic
+// recovery attempt would mislead the caller even when the constraint correctly prevents writes.
+/** @returns Caller-formatted recovery refusal, preserving the original refusal verbatim as input. */
+export function readOnlyRemedyRefusalMessage({ refusal, formatMessage }, _optional = {}) {
+    return formatMessage({ refusal });
+}
+// A route can validate the caller's read-only tool and still miss a recovery decorator choosing
+// a writing remedy afterward. Enforce on every actual dispatch at the innermost executor to
+// close that class of authority laundering, including dispatchers introduced later.
+/**
+ * Wraps `inner` so a read-only-constrained principal (one {@link constrainPrincipalToReadOnlyTools}
+ * attenuated) cannot dispatch a tool that isn't registered read-only — whichever layer chose the
+ * id. This is what turns the attenuation into an actual gate rather than a field nobody reads:
+ * {@link refuseNonReadOnlyDispatch} is the decision, this is its enforcement point.
+ *
+ * **Compose this as close to the bare `ToolExecutor` as your own stack allows** — directly around
+ * `@jini-ai/daemon`'s `createToolExecutor` output, beneath any decorator of your own that might
+ * dispatch a tool id the caller never named (a retry, a recovery loop that calls a different tool
+ * as a remedy, ...). Every such decorator's own `inner.execute` call still has to come through here
+ * to reach a handler, which is what makes this a gate on the CLASS of defect (an unnamed nested
+ * dispatch) rather than on one instance of it.
+ *
+ * `delegatedToolExecuteRoute`'s own `handle` additionally composes this around whatever
+ * `ToolExecutor` a host supplies, whenever a call attenuates its principal. That outer composition
+ * only re-covers the SAME outer `toolId` the route preflight already checked — it
+ * cannot see a nested dispatch a host's own inner decorator issues, because that decorator holds a
+ * reference to whatever `ToolExecutor` IT was built with, not to the HTTP route's wrapped one. Closing
+ * the nested case for a given host's stack requires that host to compose this decorator itself,
+ * innermost, in its own `ToolExecutor` construction — this export exists so it can, without having
+ * to rediscover or reimplement the mechanism.
+ *
+ * @returns A drop-in `ToolExecutor`; `resumeConfirmation`/`cancel`/`getAuditRecord` delegate
+ *   straight through.
+ * @complexity One extra property read per unconstrained call; one registry scan per constrained one.
+ */
+export function withReadOnlyToolConstraint({ inner, registry, idGenerator, messages }, _optional = {}) {
+    return {
+        execute: async (requiredArgs, optionalArgs = {}) => {
+            const { principal, toolId } = requiredArgs;
+            const refusal = refuseNonReadOnlyDispatch({ principal, toolId, registry, messages });
+            // Deny before inner: no handler or kernel audit record exists. Use the authorization result
+            // union instead of throwing, and mint a denial ID because there is no inner execution ID.
+            if (refusal !== null)
+                return { executionId: idGenerator.newId(), status: 'denied', error: refusal };
+            return inner.execute(requiredArgs, optionalArgs);
+        },
+        resumeConfirmation: (requiredArgs) => inner.resumeConfirmation(requiredArgs),
+        cancel: (requiredArgs) => inner.cancel(requiredArgs),
+        getAuditRecord: (requiredArgs) => inner.getAuditRecord(requiredArgs),
+    };
+}
+//# sourceMappingURL=read-only-tools.js.map

package/dist/core/tool-audit.d.ts

@@ -0,0 +1,131 @@
+import type { Principal, RunRef, SurfaceEmitter } from '@jini-ai/core';
+import type { ConfirmationDecision, ToolExecutionAuditRecord, ToolExecutionPhase, ToolExecutionResult, ToolExecutionStatus, ToolExecutor } from '../tool-executor.js';
+/** The daemon vocabulary, plus attempts that never acquired an execution ID. */
+/** Execution telemetry never proves a mutation occurred; domain revisions own write provenance. */
+export type ToolAttemptPhase = Extract<ToolExecutionPhase, 'requested' | ToolExecutionStatus> | 'unknown-tool';
+export declare const TOOL_ATTEMPT_PHASES: readonly ["requested", "completed", "denied", "confirmation-denied", "timed-out", "cancelled", "failed", "unknown-tool"];
+export interface ToolAttemptEvent {
+    readonly attemptId: string;
+    readonly executionId: string | null;
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly toolId: string;
+    readonly principalId: string;
+    readonly phase: ToolAttemptPhase;
+    readonly at: string;
+    /** Value-free metadata; never raw input, query, output or error text. */
+    readonly detail?: string | null;
+}
+export interface ToolAttemptAuditSink {
+    append(requiredArgs: Pick<ToolAttemptEvent, "attemptId" | "executionId" | "workspaceId" | "runId" | "toolId" | "principalId" | "phase" | "at">, optionalArgs?: Pick<ToolAttemptEvent, "detail">): Promise<void>;
+}
+export interface ToolAuditDependencies {
+    readonly sink: ToolAttemptAuditSink;
+    readonly now: () => string;
+    readonly newAttemptId: () => string;
+}
+export interface ToolAuditOptions {
+    readonly onSinkError?: (error: unknown) => void;
+}
+/** Retain key names and array lengths, never operator values; unreadable objects are summarized
+ * without throwing. The durable trail needs only enough metadata to distinguish attempts. */
+export declare function describeInput({ input }: {
+    readonly input: unknown;
+}, _optional?: Record<string, never>): string;
+export interface AuditedToolExecutor {
+    execute(args: {
+        principal: Principal;
+        run: RunRef;
+        toolId: string;
+        input: unknown;
+    }, options?: {
+        signal?: AbortSignal;
+        emitSurface?: SurfaceEmitter;
+    }): Promise<ToolExecutionResult>;
+    resumeConfirmation(args: {
+        executionId: string;
+        decision: ConfirmationDecision;
+    }, optional?: Record<string, never>): void;
+    cancel(args: {
+        executionId: string;
+    }, optional?: Record<string, never>): void;
+    getAuditRecord(args: {
+        executionId: string;
+    }, optional?: Record<string, never>): ToolExecutionAuditRecord | null;
+}
+/** Append requested BEFORE delegation: unknown tools and throwing authorization have no execution
+ * record yet, and wrapping a handler would miss denied/confirmed attempts. The executor's own
+ * in-memory audit remains authoritative for getAuditRecord; an injected sink can retain history.
+ * Audit observes rather than gates: sink/reporting failures never alter execution outcomes.
+ * ADR-021 §2 keeps authorization with ToolPolicy.authorize and the domain evaluator.
+ * Forward emitSurface unchanged or human-answer tools would silently take their fallback path.
+ * Settled details retain truncation or an errorId link, never error text or operator content. */
+export declare function withToolAttemptAudit(deps: ToolAuditDependencies & {
+    readonly inner: ToolExecutor;
+    readonly workspaceId: string;
+    readonly readErrorId: (args: {
+        result: ToolExecutionResult;
+    }) => string | undefined;
+}, options?: ToolAuditOptions): AuditedToolExecutor;
+/** Keep ids in returned rank order and record queryLength/limit, never raw query text, scores
+ * or descriptions: a pasted secret must not become durable audit content. */
+export declare function searchToolsAuditDetail({ query, limit, hits }: {
+    query: string;
+    limit: number | null;
+    hits: readonly {
+        id: string;
+    }[];
+}, _optional?: Record<string, never>): string;
+/** Id and found flag suffice; repeating the entry schema/description adds no diagnostic value. */
+export declare function describeToolAuditDetail({ id, entry }: {
+    id: string;
+    entry: unknown | null;
+}, _optional?: Record<string, never>): string;
+export interface ToolCatalogAuditIdentity {
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly principalId: string;
+}
+export interface ToolCatalogAttemptEvent extends ToolCatalogAuditIdentity {
+    readonly toolId: string;
+    readonly detail: string;
+}
+/** Catalog reads bypass ToolExecutor and therefore need their own observation. Fire without
+ * awaiting so synchronous catalog calls stay synchronous; appendSafely contains sink failures.
+ * Completed is a read phase, not an authorization/confirmation lifecycle. */
+export declare function appendToolCatalogAttempt(deps: ToolAuditDependencies & {
+    readonly event: ToolCatalogAttemptEvent;
+}, options?: ToolAuditOptions): void;
+/** Structural source port: no database or catalog-provider dependency. */
+export interface ToolCatalogAuditSource<Hit extends {
+    id: string;
+}, Entry> {
+    search(args: {
+        query: string;
+    }, options?: {
+        limit?: number;
+    }): readonly Hit[];
+    describe(args: {
+        id: string;
+    }, optional?: Record<string, never>): Entry | null;
+}
+/** Preserve catalog results/ranking while appending under the supplied fixed identity. Hosts
+ * with per-call attribution use appendToolCatalogAttempt directly; no identity is inferred here. */
+export declare function withToolCatalogAudit<Hit extends {
+    id: string;
+}, Entry>(deps: ToolAuditDependencies & {
+    catalog: ToolCatalogAuditSource<Hit, Entry>;
+    identity: ToolCatalogAuditIdentity;
+    searchToolId: string;
+    describeToolId: string;
+}, options?: ToolAuditOptions): {
+    search({ query }: {
+        query: string;
+    }, { limit }?: {
+        limit?: number;
+    }): readonly Hit[];
+    describe({ id }: {
+        id: string;
+    }): Entry | null;
+};
+//# sourceMappingURL=tool-audit.d.ts.map

package/dist/core/tool-audit.js

@@ -0,0 +1,113 @@
+export const TOOL_ATTEMPT_PHASES = [
+    'requested', 'completed', 'denied', 'confirmation-denied', 'timed-out', 'cancelled', 'failed', 'unknown-tool',
+];
+function reportSinkError(error, options) {
+    // An observer's reporter is itself an observer: a throwing reporter cannot gate a tool.
+    try {
+        options.onSinkError?.(error);
+    }
+    catch { /* execution remains authoritative */ }
+}
+async function appendSafely(event, deps, options) {
+    try {
+        await deps.sink.append(event);
+    }
+    catch (error) {
+        reportSinkError(error, options);
+    }
+}
+/** Retain key names and array lengths, never operator values; unreadable objects are summarized
+ * without throwing. The durable trail needs only enough metadata to distinguish attempts. */
+export function describeInput({ input }, _optional = {}) {
+    if (input === null || input === undefined)
+        return `input: ${String(input)}`;
+    if (Array.isArray(input))
+        return `input: an array of ${input.length}`;
+    if (typeof input !== 'object')
+        return `input: a ${typeof input}`;
+    try {
+        const parts = Object.entries(input).map(([key, value]) => Array.isArray(value) ? `${key}[${value.length}]` : key).sort();
+        return parts.length === 0 ? 'keys: none' : `keys: ${parts.join(', ')}`;
+    }
+    catch {
+        return 'input: an unreadable object';
+    }
+}
+/** Append requested BEFORE delegation: unknown tools and throwing authorization have no execution
+ * record yet, and wrapping a handler would miss denied/confirmed attempts. The executor's own
+ * in-memory audit remains authoritative for getAuditRecord; an injected sink can retain history.
+ * Audit observes rather than gates: sink/reporting failures never alter execution outcomes.
+ * ADR-021 §2 keeps authorization with ToolPolicy.authorize and the domain evaluator.
+ * Forward emitSurface unchanged or human-answer tools would silently take their fallback path.
+ * Settled details retain truncation or an errorId link, never error text or operator content. */
+export function withToolAttemptAudit(deps, options = {}) {
+    return {
+        async execute({ principal, run, toolId, input }, { signal, emitSurface } = {}) {
+            const base = { attemptId: deps.newAttemptId(), workspaceId: deps.workspaceId, runId: run.id, toolId, principalId: principal.id };
+            await appendSafely({ ...base, executionId: null, phase: 'requested', at: deps.now(), detail: describeInput({ input }) }, deps, options);
+            let result;
+            try {
+                result = await deps.inner.execute({ principal, run, toolId, input }, {
+                    ...(signal === undefined ? {} : { signal }),
+                    ...(emitSurface === undefined ? {} : { emitSurface }),
+                });
+            }
+            catch (error) {
+                // The boundary exposes no typed unknown-tool error. Wording drift loses only label
+                // precision, never the row or execution behavior; retain the error class, not its message.
+                const phase = error instanceof Error && /unknown tool/i.test(error.message) ? 'unknown-tool' : 'failed';
+                await appendSafely({ ...base, executionId: null, phase, at: deps.now(), detail: error instanceof Error ? error.name : typeof error }, deps, options);
+                throw error;
+            }
+            let detail = result.truncated ? 'output truncated' : null;
+            // Host error-ID metadata is optional observation, never part of execution success.
+            if (detail === null) {
+                try {
+                    const id = deps.readErrorId({ result });
+                    if (id !== undefined)
+                        detail = `errorId=${id}`;
+                }
+                catch (error) {
+                    reportSinkError(error, options);
+                }
+            }
+            await appendSafely({ ...base, executionId: result.executionId, phase: result.status, at: deps.now(), detail }, deps, options);
+            return result;
+        },
+        resumeConfirmation: ({ executionId, decision }) => deps.inner.resumeConfirmation({ executionId: executionId, decision: decision }),
+        cancel: ({ executionId }) => deps.inner.cancel({ executionId }),
+        getAuditRecord: ({ executionId }) => deps.inner.getAuditRecord({ executionId: executionId }),
+    };
+}
+/** Keep ids in returned rank order and record queryLength/limit, never raw query text, scores
+ * or descriptions: a pasted secret must not become durable audit content. */
+export function searchToolsAuditDetail({ query, limit, hits }, _optional = {}) {
+    return JSON.stringify({ queryLength: query.length, limit, resultIds: hits.map(hit => hit.id), resultCount: hits.length });
+}
+/** Id and found flag suffice; repeating the entry schema/description adds no diagnostic value. */
+export function describeToolAuditDetail({ id, entry }, _optional = {}) {
+    return JSON.stringify({ id, found: entry !== null });
+}
+/** Catalog reads bypass ToolExecutor and therefore need their own observation. Fire without
+ * awaiting so synchronous catalog calls stay synchronous; appendSafely contains sink failures.
+ * Completed is a read phase, not an authorization/confirmation lifecycle. */
+export function appendToolCatalogAttempt(deps, options = {}) {
+    void appendSafely({ ...deps.event, attemptId: deps.newAttemptId(), executionId: null, phase: 'completed', at: deps.now() }, deps, options);
+}
+/** Preserve catalog results/ranking while appending under the supplied fixed identity. Hosts
+ * with per-call attribution use appendToolCatalogAttempt directly; no identity is inferred here. */
+export function withToolCatalogAudit(deps, options = {}) {
+    return {
+        search({ query }, { limit } = {}) {
+            const hits = deps.catalog.search({ query }, limit === undefined ? {} : { limit });
+            appendToolCatalogAttempt({ ...deps, event: { ...deps.identity, toolId: deps.searchToolId, detail: searchToolsAuditDetail({ query, limit: limit ?? null, hits }) } }, options);
+            return hits;
+        },
+        describe({ id }) {
+            const entry = deps.catalog.describe({ id });
+            appendToolCatalogAttempt({ ...deps, event: { ...deps.identity, toolId: deps.describeToolId, detail: describeToolAuditDetail({ id, entry }) } }, options);
+            return entry;
+        },
+    };
+}
+//# sourceMappingURL=tool-audit.js.map

package/dist/http/active-context.d.ts

@@ -88,13 +88,13 @@ interface ActiveContextRouteDeps {
  * `POST /api/active` — records (or, with `{active: false}`, clears) the
  * caller's current resource focus.
  */
-export declare const setActiveRoute: import("@jini-ai/http-kit").JsonRouteSpec<SetActiveInput, SetActiveOutput, ActiveContextRouteDeps>;
+export declare const setActiveRoute: import("@jini-ai/http-kit").JsonRouteSpec<SetActiveInput, SetActiveOutput, ActiveContextRouteDeps, undefined>;
 /**
  * `GET /api/active` — reads back the current resource focus, resolving a
  * display name for it, or `{active: false}` if nothing is set or the
  * recorded focus has aged past {@link ACTIVE_CONTEXT_TTL_MS}.
  */
-export declare const getActiveRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, GetActiveOutput, ActiveContextRouteDeps>;
+export declare const getActiveRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, GetActiveOutput, ActiveContextRouteDeps, undefined>;
 /** Mounts both active-context routes on `app`, sharing one in-memory store between them. A pack's `http(app, services)` calls this directly. */
 export declare function registerActiveContextRoutes({ app, deps, adapter }: {
     readonly app: Express;

package/dist/http/agents.d.ts

@@ -16,9 +16,12 @@
  */
 import type { Express } from 'express';
 import { type AdapterContext } from '@jini-ai/http-kit';
+import type { ModelCatalogSnapshot, DefaultModelResolution, ModelIdentityKind } from '@jini-ai/agent-runtime';
 export interface AgentModelSummary {
     readonly id: string;
     readonly label: string;
+    readonly identityKind?: ModelIdentityKind;
+    readonly resolvedId?: string;
 }
 /**
  * Client-safe agent discovery data. Optional probe fields preserve the
@@ -34,7 +37,10 @@ export interface AgentSummary {
     readonly models?: readonly AgentModelSummary[];
     readonly reasoningOptions?: readonly AgentModelSummary[];
     readonly modelsSource?: 'live' | 'fallback';
+    readonly modelCatalog?: ModelCatalogSnapshot;
+    readonly defaultModelResolution?: DefaultModelResolution;
     readonly supportsCustomModel?: boolean;
+    readonly supportsConcreteModelSelection?: boolean;
     readonly diagnostic?: string;
     /**
      * Whether this runtime can receive external MCP servers (the host application's or this engine's
@@ -56,9 +62,9 @@ export interface AgentListResponse {
     readonly agents: readonly AgentSummary[];
 }
 /** `GET /api/agents` — read-only, no side effects; matches `runListRoute`/`runStatusRoute`'s posture of not requiring same-origin. */
-export declare const agentListRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, AgentListResponse, AgentsHttpDeps>;
+export declare const agentListRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, AgentListResponse, AgentsHttpDeps, undefined>;
 /** `POST /api/agents/rescan` — explicit state refresh, protected by the local same-origin gate. */
-export declare const agentRescanRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, AgentListResponse, AgentsHttpDeps>;
+export declare const agentRescanRoute: import("@jini-ai/http-kit").JsonRouteSpec<void, AgentListResponse, AgentsHttpDeps, undefined>;
 /** Mounts the read and explicit-rescan agent discovery routes. */
 export declare function registerAgentRoutes({ app, deps, adapter }: {
     readonly app: Express;

package/dist/http/agents.js

@@ -1,9 +1,13 @@
 import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
 import { ok } from '@jini-ai/http-kit';
 /** `GET /api/agents` — read-only, no side effects; matches `runListRoute`/`runStatusRoute`'s posture of not requiring same-origin. */
-export const agentListRoute = defineJsonRoute({ method: 'get', path: '/api/agents', parse: () => ok({ value: undefined }), handle: async ({ input: _input, deps }) => ok({ value: { agents: await deps.listAgents() } }) });
+export const agentListRoute = defineJsonRoute({ method: 'get', path: '/api/agents', parse: () => ok({ value: undefined }), handle: async ({ input: _input, deps }) => ok({ value: { agents: activeAgents(await deps.listAgents()) } }) });
 /** `POST /api/agents/rescan` — explicit state refresh, protected by the local same-origin gate. */
-export const agentRescanRoute = defineJsonRoute({ method: 'post', path: '/api/agents/rescan', parse: () => ok({ value: undefined }), handle: async ({ input: _input, deps }) => ok({ value: { agents: await (deps.rescanAgents ?? deps.listAgents)() } }) }, { requireSameOrigin: true });
+export const agentRescanRoute = defineJsonRoute({ method: 'post', path: '/api/agents/rescan', parse: () => ok({ value: undefined }), handle: async ({ input: _input, deps }) => ok({ value: { agents: activeAgents(await (deps.rescanAgents ?? deps.listAgents)()) } }) }, { requireSameOrigin: true });
+/** Retired CLI inventories can survive in a host cache; never advertise them over this route. */
+function activeAgents(agents) {
+    return agents.filter((agent) => agent.id !== 'gemini');
+}
 /** Mounts the read and explicit-rescan agent discovery routes. */
 export function registerAgentRoutes({ app, deps, adapter }, _optional = {}) {
     mountJsonRoute({ app, spec: agentListRoute, deps, adapter });