@jini-ai/core 0.4.1 → 0.4.2

package/dist/model-facing-tool-errors.js

@@ -7,12 +7,57 @@
 // Domains explicitly own which classes/messages are safe to expose, including anonymous callers:
 // stacks, internal paths, SQL, credentials, and another tenant's data must remain unlisted/redacted.
 import { ToolInputError } from "./tool-registry.js";
+/**
+ * The code every domain publishes an authorization refusal under, parameterized by domain prefix.
+ *
+ * Exists because `ForbiddenError` is the ONE class in this ladder that no domain declares: the kit's
+ * `requireToolPermission` throws it on every domain's behalf. Deriving the rule here rather than
+ * retyping `{ error: ForbiddenError, code: "X_FORBIDDEN" }` in six files means a later decision to
+ * reconcile this code with the HTTP arm's own `FORBIDDEN` is a one-line change here, not a sweep.
+ *
+ * NOTE (2026-09-16): the model-facing and HTTP arms disagree on this code today — the HTTP mappers
+ * return `FORBIDDEN` while the model-facing arm returns `<DOMAIN>_FORBIDDEN`. That drift predates
+ * this file (see `features/widgets/tool-registrations.ts`'s `toModelFacingWidgetsError` doc, which
+ * documented it for Widgets) and is owned elsewhere. This helper deliberately matches the SHIPPED
+ * model-facing convention rather than inventing a third spelling.
+ *
+ * The refusal message `requireToolPermission` builds names the principal, the permission, and the
+ * `authorize()` reason — no data, no internals. Surfacing it tells a model whether to stop asking
+ * or to ask a human for access; redacting it tells it only that something broke.
+ *
+ * @param required.domainPrefix - The domain's SCREAMING_SNAKE prefix, e.g. `MEMBERS`.
+ * @param required.error - The consumer's permission-error class; core has no CMS dependency.
+ * @returns The rule to place in that domain's allowlist.
+ * @complexity O(1).
+ */
 export function forbiddenRule(required) {
     return { error: required.error, code: `${required.domainPrefix}_FORBIDDEN` };
 }
 // First match wins: list subclasses before superclasses. Unmatched values must retain identity so
 // the transport's redaction remains the default; already-classified ToolInputError also stays intact
 // to avoid doubling a prefix attached by schema/recovery wrapping.
+/**
+ * Re-classifies one rejection against a domain's allowlist, so a listed domain error reaches the
+ * model as a `ToolInputError` carrying its real message instead of a redacted `INTERNAL_ERROR`.
+ *
+ * Rules are evaluated IN ORDER and the first `instanceof` match wins, so a domain listing both a
+ * subclass and its superclass must place the subclass first — the same ordering discipline any
+ * hand-written `instanceof` ladder carries, made explicit here because an array hides it less than
+ * a chain of `if`s does.
+ *
+ * A matched rule publishes the error's own message, or {@link ModelFacingErrorRule.message} instead
+ * when the rule sets one — see that field for which classes need it and why.
+ *
+ * An already-`ToolInputError` rejection is returned untouched: it is already correctly classified,
+ * and re-wrapping it would double a code prefix that a `withSchemaOnRejection` wrap may have
+ * already attached.
+ *
+ * @param required.err - The rejection, of unknown type — anything a handler can throw.
+ * @param required.rules - The domain's allowlist. Anything unmatched is returned UNCHANGED and stays
+ * redacted; see this file's header for why that default is the security-relevant half.
+ * @returns The value to re-throw: a `ToolInputError` for a matched rule, otherwise `err` itself.
+ * @complexity O(r) in the rule count, on the failure path only.
+ */
 export function reclassifyToolError(required) {
     const { err, rules } = required;
     if (err instanceof ToolInputError)
@@ -28,6 +73,24 @@ export function reclassifyToolError(required) {
 // Wrap the whole map once: a correct per-handler converter previously reached only one handler
 // while sibling operations still leaked into the internal-error redactor. Central wrapping has no
 // omitted call-site arm, and successful results pass through untouched.
+/**
+ * Wraps EVERY handler in a domain's map with {@link reclassifyToolError}, returning a new map.
+ *
+ * Wrapping the whole map once — rather than reclassifying at each call site — is the point. This
+ * codebase's dominant defect is a correct primitive with an unwired call site, and a per-call-site
+ * reshape is exactly that defect waiting to happen: `features/post/tool-registrations.ts` had a
+ * correct `toModelFacingUpdateError` wired into ONE of its handlers while its siblings kept
+ * throwing the same class straight through to the redactor. A map-level wrap cannot have a missed
+ * arm, because it has no arms.
+ *
+ * The wrap is transparent on the success path: the handler's own return value is passed through
+ * untouched, and only the `catch` does work.
+ *
+ * @param required.handlers - The domain's handler map, keyed by tool id.
+ * @param rules - The domain's allowlist, applied identically to every handler.
+ * @returns A new map with the same keys; the input map is not mutated.
+ * @complexity O(h) handlers wrapped once at build time; O(r) per failed call, none per successful one.
+ */
 export function withModelFacingErrors(required) {
     const { handlers, rules } = required;
     return Object.fromEntries(Object.entries(handlers).map(([toolId, handler]) => [
@@ -44,6 +107,24 @@ export function withModelFacingErrors(required) {
 }
 // Registration-array builders need the same blanket coverage as handler maps. Preserve descriptor,
 // policy, ordering, and successful results; only the rejection path is reclassified.
+/**
+ * Wraps EVERY registration's handler in a domain's `ToolRegistration[]` with
+ * {@link reclassifyToolError}, returning a new array. The `ToolRegistration[]`-shaped sibling of
+ * {@link withModelFacingErrors} — for the registry-converted domains whose `build*Registrations`
+ * returns an array of `{descriptor, handler, policy}` (see `assistant/tool-contribution-registry.ts`'s
+ * `ToolContributor.build`) rather than a `Record<toolId, handler>`. `features/entries`,
+ * `features/content-types`, `features/navigation` and `features/workspace` are re-exported Jini
+ * builders of exactly this shape — see each one's `contribute*Tools`.
+ *
+ * Same transparency guarantee as {@link withModelFacingErrors}: only the `catch` arm does work, and
+ * every other field of each registration (`descriptor`, `policy`) passes through unchanged.
+ *
+ * @param required.registrations - The domain's registrations, in whatever order `build*Registrations`
+ * returned them.
+ * @param rules - The domain's allowlist, applied identically to every registration.
+ * @returns A new array with the same length and order; the input array is not mutated.
+ * @complexity O(n) registrations wrapped once at build time; O(r) per failed call, none per successful one.
+ */
 export function withModelFacingRegistrationErrors(required) {
     const { registrations, rules } = required;
     return registrations.map((registration) => ({
@@ -60,6 +141,20 @@ export function withModelFacingRegistrationErrors(required) {
 }
 // Unknown classes, raw driver errors, and non-Error throws get fixed fallback text, never raw error
 // content. The fallback itself must not be derived from err; first matching rule still wins.
+/**
+ * The message a RETURNED failure result may carry for `err`: a listed class's message (or its fixed
+ * replacement), otherwise `fallback`.
+ *
+ * Unknown means redacted. An error class added tomorrow, a raw driver error, or a non-`Error` throw
+ * all get `fallback`, never their own text. Rules are evaluated in order; the first `instanceof`
+ * match wins.
+ *
+ * @param required.err - The caught value, of unknown type.
+ * @param required.rules - The allowlist.
+ * @param required.fallback - Fixed text for everything unlisted. Must not be built from `err`.
+ * @returns The message to publish.
+ * @complexity O(r) in the rule count.
+ */
 export function callerSafeErrorMessage(required) {
     const { err, rules, fallback } = required;
     for (const rule of rules) {
@@ -68,4 +163,33 @@ export function callerSafeErrorMessage(required) {
     }
     return fallback;
 }
+/** A driver/system error code worth logging (`SQLITE_READONLY`, `ECONNREFUSED`, `ERR_INVALID_CHAR`) —
+ *  a short constant token, never free text that could carry a value. */
+const LOGGABLE_ERROR_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** `ClassName` or `ClassName(CODE)` for one thrown value; `typeof` for a non-`Error` throw. */
+function describeOneErrorForLog(value) {
+    if (!(value instanceof Error))
+        return typeof value;
+    const className = value.constructor.name || "Error";
+    const code = value.code;
+    return typeof code === "string" && LOGGABLE_ERROR_CODE.test(code) ? `${className}(${code})` : className;
+}
+/**
+ * What a server-side log line may say about an error whose message is NOT known to be safe: its class
+ * name, a constant-token `code`, and the same for its direct `cause`. Never the message, which can
+ * quote a secret — `JSON.parse` quotes its input, and a sealer is handed plaintext.
+ *
+ * Use it wherever the raw message could carry a credential. Where a class's message is designed for
+ * logs (`EgressRefusedError.message`), log that instead.
+ *
+ * @param required.err - The caught value.
+ * @returns e.g. `SqliteError(SQLITE_BUSY)`, or `TypeError cause=Error(ECONNREFUSED)`.
+ * @complexity O(1).
+ */
+export function describeErrorForLog(required, _optional = {}) {
+    const { err } = required;
+    const described = describeOneErrorForLog(err);
+    const cause = err instanceof Error ? err.cause : undefined;
+    return cause === undefined ? described : `${described} cause=${describeOneErrorForLog(cause)}`;
+}
 //# sourceMappingURL=model-facing-tool-errors.js.map

package/dist/native-regexp.d.ts

@@ -0,0 +1,10 @@
+/** Native RegExp.escape is available in Node 24 and modern browsers, but the supported
+ * TypeScript 5.8 libraries do not declare it yet. Declare the native contract without a
+ * polyfill or a second escaping implementation; hosts must supply the native capability. */
+declare global {
+    interface RegExpConstructor {
+        escape(value: string): string;
+    }
+}
+export {};
+//# sourceMappingURL=native-regexp.d.ts.map

package/dist/native-regexp.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=native-regexp.js.map

package/dist/primitives/index.d.ts

@@ -2,6 +2,8 @@ export * from './time.js';
 export * from './ids.js';
 export * from './json.js';
 export * from './http.js';
+export { decodeSseFrames, decodeSseStream, parseSseRecord } from './sse.js';
+export type { DecodedSseEvent, DecodedSseFrame, SseFramingOptions } from './sse.js';
 export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';

package/dist/primitives/index.js

@@ -2,6 +2,7 @@ export * from './time.js';
 export * from './ids.js';
 export * from './json.js';
 export * from './http.js';
+export { decodeSseFrames, decodeSseStream, parseSseRecord } from './sse.js';
 export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';

package/dist/primitives/sse.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module primitives/sse
+ *
+ * Minimal, tolerant Server-Sent-Events *frame decoder* for an INBOUND
+ * provider stream — the response body a call to the Anthropic Messages API
+ * or the OpenAI Chat Completions API sends back when `stream: true` is
+ * requested. This is deliberately not `@jini-ai/http-kit`'s `sse.ts`: that module
+ * is the OUTBOUND channel a route uses to push events to a browser client
+ * (bounded queue, backpressure, `Last-Event-ID` replay). This module has
+ * none of that — it only turns a raw byte/text stream into `{event, data}`
+ * frames per the SSE wire format (`text/event-stream`, RFC-ish: fields
+ * separated by `\n`, records separated by a blank line), so a provider-
+ * specific turn-runner (`anthropic-messages.ts`, `openai-chat.ts`) can
+ * `JSON.parse` each frame's `data` field without re-deriving line/record
+ * framing itself.
+ *
+ * Field parsing and framing are shared by providers and durable run consumers.
+ * The public leaf has no Node imports; callers keep their own JSON, EOF and
+ * reader-ownership policies rather than re-deriving line/record framing.
+ */
+/** Provider-facing record. Metadata remains absent from this compatibility contract. */
+export interface DecodedSseEvent {
+    /** Null without event: (OpenAI Chat Completions implicitly sends plain messages). */
+    readonly event: string | null;
+    /** Multiple data: values joined with newlines, per the SSE spec. */
+    readonly data: string;
+}
+/** Raw field values, including explicit (possibly empty) IDs; IDs do not carry across records. */
+export interface DecodedSseFrame extends DecodedSseEvent {
+    readonly id?: string;
+    readonly dataLines: readonly string[];
+}
+export interface SseFramingOptions {
+    /** Providers flush EOF tails; durable run readers require a terminating blank line. */
+    readonly flushFinalFrame?: boolean;
+    /** Bounds all pending record text, including comments and ignored fields, in UTF-16 units. */
+    readonly maxBufferChars?: number;
+}
+/** Parse one delimiter-free record without JSON interpretation. O(text) time and space. */
+export declare function parseSseRecord({ rawFrame }: {
+    rawFrame: string;
+}, _options?: Record<string, never>): DecodedSseFrame;
+/**
+ * Browser-safe inbound framing for byte/text iterables; accepts LF and CRLF, including split
+ * UTF-8 and CRLF chunks. Reader ownership stays with the source iterator. Optional bounds throw
+ * RangeError before buffered text exceeds the limit. Early return closes the source iterator.
+ * @complexity O(text + repeated copying of an unfinished line); O(pending record + chunk) space.
+ */
+export declare function decodeSseFrames({ source }: {
+    source: AsyncIterable<Uint8Array | string>;
+}, options?: SseFramingOptions): AsyncGenerator<DecodedSseFrame>;
+/**
+ * Provider compatibility entry: drops reconnect metadata (meaningless for a single proxied
+ * request/response pair) and flushes unterminated EOF records. Keeps the published frame shape.
+ * @complexity Inherits decodeSseFrames' streaming cost and buffer size.
+ */
+export declare function decodeSseStream({ source }: {
+    source: AsyncIterable<Uint8Array | string>;
+}, _options?: Record<string, never>): AsyncGenerator<DecodedSseEvent>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/primitives/sse.js

@@ -0,0 +1,122 @@
+/**
+ * @module primitives/sse
+ *
+ * Minimal, tolerant Server-Sent-Events *frame decoder* for an INBOUND
+ * provider stream — the response body a call to the Anthropic Messages API
+ * or the OpenAI Chat Completions API sends back when `stream: true` is
+ * requested. This is deliberately not `@jini-ai/http-kit`'s `sse.ts`: that module
+ * is the OUTBOUND channel a route uses to push events to a browser client
+ * (bounded queue, backpressure, `Last-Event-ID` replay). This module has
+ * none of that — it only turns a raw byte/text stream into `{event, data}`
+ * frames per the SSE wire format (`text/event-stream`, RFC-ish: fields
+ * separated by `\n`, records separated by a blank line), so a provider-
+ * specific turn-runner (`anthropic-messages.ts`, `openai-chat.ts`) can
+ * `JSON.parse` each frame's `data` field without re-deriving line/record
+ * framing itself.
+ *
+ * Field parsing and framing are shared by providers and durable run consumers.
+ * The public leaf has no Node imports; callers keep their own JSON, EOF and
+ * reader-ownership policies rather than re-deriving line/record framing.
+ */
+/** Owns field parsing for both raw records and incremental streams; callers own interpretation. */
+function createRecordDecoder() {
+    let event = null;
+    let id;
+    let dataLines = [];
+    return {
+        line(raw) {
+            const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+            if (line.startsWith(':'))
+                return; // comment line, per spec
+            const colon = line.indexOf(':');
+            const field = colon === -1 ? line : line.slice(0, colon);
+            let value = colon === -1 ? '' : line.slice(colon + 1);
+            if (value.startsWith(' '))
+                value = value.slice(1);
+            if (field === 'event')
+                event = value;
+            else if (field === 'data')
+                dataLines.push(value);
+            else if (field === 'id')
+                id = value;
+            // retry/unknown fields do not belong to per-record interpretation.
+        },
+        take() {
+            const frame = { event, data: dataLines.join('\n'), dataLines, ...(id !== undefined ? { id } : {}) };
+            event = null;
+            id = undefined;
+            dataLines = [];
+            return frame;
+        },
+    };
+}
+/** Parse one delimiter-free record without JSON interpretation. O(text) time and space. */
+export function parseSseRecord({ rawFrame }, _options = {}) {
+    const record = createRecordDecoder();
+    for (const line of rawFrame.split('\n'))
+        record.line(line);
+    return record.take();
+}
+/**
+ * Browser-safe inbound framing for byte/text iterables; accepts LF and CRLF, including split
+ * UTF-8 and CRLF chunks. Reader ownership stays with the source iterator. Optional bounds throw
+ * RangeError before buffered text exceeds the limit. Early return closes the source iterator.
+ * @complexity O(text + repeated copying of an unfinished line); O(pending record + chunk) space.
+ */
+export async function* decodeSseFrames({ source }, options = {}) {
+    const decoder = new TextDecoder();
+    const record = createRecordDecoder();
+    let buffer = '';
+    let scanFrom = 0;
+    let recordChars = 0;
+    function* drainCompleteLines() {
+        if (options.maxBufferChars !== undefined && recordChars + buffer.length > options.maxBufferChars) {
+            throw new RangeError(`SSE stream exceeded the ${options.maxBufferChars}-character unterminated-frame buffer limit`);
+        }
+        let newlineIndex;
+        while ((newlineIndex = buffer.indexOf('\n', scanFrom)) !== -1) {
+            const line = buffer.slice(0, newlineIndex);
+            buffer = buffer.slice(newlineIndex + 1);
+            scanFrom = 0;
+            if (line === '' || line === '\r') {
+                const completed = record.take();
+                recordChars = 0;
+                if (completed.event !== null || completed.dataLines.length > 0 || completed.id !== undefined)
+                    yield completed;
+            }
+            else {
+                recordChars += newlineIndex + 1;
+                record.line(line);
+            }
+        }
+        scanFrom = buffer.length;
+    }
+    for await (const chunk of source) {
+        buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+        yield* drainCompleteLines();
+    }
+    buffer += decoder.decode();
+    yield* drainCompleteLines();
+    if (options.flushFinalFrame === false)
+        return;
+    // Flush whatever is left: either a trailing unterminated line (no final
+    // `\n` at all), or a fully-parsed-but-not-blank-line-terminated record.
+    // A provider closing immediately after its last byte must not silently lose it.
+    if (buffer.length > 0)
+        record.line(buffer);
+    const completed = record.take();
+    if (completed.event !== null || completed.dataLines.length > 0 || completed.id !== undefined)
+        yield completed;
+}
+/**
+ * Provider compatibility entry: drops reconnect metadata (meaningless for a single proxied
+ * request/response pair) and flushes unterminated EOF records. Keeps the published frame shape.
+ * @complexity Inherits decodeSseFrames' streaming cost and buffer size.
+ */
+export async function* decodeSseStream({ source }, _options = {}) {
+    for await (const frame of decodeSseFrames({ source })) {
+        if (frame.event !== null || frame.dataLines.length > 0)
+            yield { event: frame.event, data: frame.data };
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/redact.js

@@ -102,11 +102,12 @@ const PATTERNS = [
     // Phone numbers. Tight US-leaning shape; a global PII detector would
     // need a real lib. We keep this so US-based test prompts ('call me at
     // (415) 555-...') don't ship. Note: no leading \b — '(' isn't a word
-    // char, so a starting boundary would refuse to match `(415)`. We
-    // require a non-digit (or start of string) before the run instead.
+    // char, so a starting boundary would refuse to match `(415)`. Reject
+    // adjacent word characters or hyphens so digit segments of UUIDs,
+    // hashes and identifiers stay readable; separators within phones still match.
     {
         name: 'phone',
-        regex: /(?<!\d)(?:\+?\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}(?!\d)/g,
+        regex: /(?<![\w-])(?:\+?\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}(?![\w-])/g,
     },
 ];
 // Credit card sweep is special: a naive 13-19 digit run matches a lot of

package/dist/registration-kit.d.ts

@@ -139,6 +139,17 @@ export declare function isRecord(required: {
 }, _optional?: Record<string, never>): required is {
     value: Record<string, unknown>;
 };
+/**
+ * Accepts non-null, non-array objects, including class instances and null-prototype records.
+ * This is a shape check, not plain-object validation or sanitization. Keep `isRecord`'s
+ * broader contract: existing tool readers deliberately continue to accept arrays.
+ * @param required.value - The untrusted value whose object shape is checked.
+ */
+export declare function isNonArrayRecord(required: {
+    value: unknown;
+}, _optional?: Record<string, never>): required is {
+    value: Record<string, unknown>;
+};
 /** Narrows `ctx.input` to a record, refusing anything else. The first line of most handlers. */
 export declare function requireInputRecord(required: {
     input: unknown;
@@ -327,6 +338,8 @@ export declare function buildDomainRegistrations(spec: {
     catalog: ReadonlyMap<string, AgentToolDefinition>;
     handlers: Record<string, ToolHandler>;
     derivedRisk: DerivedRiskByToolId;
+    /** Host vocabulary and reviewed action policy; risk remains independently checked above. */
+    metadata?: import('./tool-metadata.js').ToolMetadataById;
 }, optional?: {
     unwiredToolIds?: ReadonlySet<string>;
 }): ToolRegistration[];

package/dist/registration-kit.js

@@ -25,6 +25,7 @@
  * describes, where a reviewer reading the handler can see it.
  */
 import { ToolInputError } from "./tool-registry.js";
+import { toolMetadataFor } from "./tool-metadata.js";
 /**
  * Audit provenance stamped onto every revision row a tool handler writes.
  *
@@ -103,6 +104,15 @@ export function isRecord(required, _optional = {}) {
     const { value } = required;
     return typeof value === "object" && value !== null;
 }
+/**
+ * Accepts non-null, non-array objects, including class instances and null-prototype records.
+ * This is a shape check, not plain-object validation or sanitization. Keep `isRecord`'s
+ * broader contract: existing tool readers deliberately continue to accept arrays.
+ * @param required.value - The untrusted value whose object shape is checked.
+ */
+export function isNonArrayRecord(required, _optional = {}) {
+    return isRecord(required) && !Array.isArray(required.value);
+}
 /** Narrows `ctx.input` to a record, refusing anything else. The first line of most handlers. */
 export function requireInputRecord(required, _optional = {}) {
     const { input } = required;
@@ -371,11 +381,13 @@ export function buildDomainRegistrations(spec, optional = {}) {
         if (!catalogEntry.inputSchema) {
             throw new Error(`tool-registrations: wired tool '${id}' publishes no inputSchema — add one to its entry in ${spec.catalogModule} so the model gets a contract, or leave the tool unwired`);
         }
+        const metadata = catalogEntry.metadata ?? toolMetadataFor({ toolId: id, metadata: spec.metadata });
         registrations.push({
             descriptor: {
                 id,
                 description: catalogEntry.description,
                 inputSchema: catalogEntry.inputSchema,
+                ...(metadata ? { metadata } : {}),
                 // The ONE place a domain's declared risk becomes the descriptor flag every read-only gate
                 // reads (`@jini-ai/core`'s `isReadOnlyTool`). Placed here rather than in each domain's
                 // `tool-registrations.ts` for the same reason the drift tripwire is: twelve copies of this

package/dist/settings/agent-tools.d.ts

@@ -0,0 +1,10 @@
+import type { AgentToolDefinition } from "../agent-tools.js";
+/**
+ * The Settings domain's fixed agent-tool catalog — three reads, three bounded writes, and two bulk/schema writes documented but never
+ * wired. See file header.
+ *
+ * @complexity O(1) — a fixed, statically-defined list.
+ * @overallScore 100
+ */
+export declare function getSettingsAgentToolCatalog(): AgentToolDefinition[];
+//# sourceMappingURL=agent-tools.d.ts.map