@jini-ai/core 0.6.21 → 0.6.23

package/dist/teardown.d.ts

@@ -0,0 +1,30 @@
+/** A cleanup step may be synchronous or asynchronous; failures are reported after all steps run. */
+export type TeardownStep = () => unknown;
+/** Injected lifecycle registration; core has no dependency on a particular test runner or host. */
+export interface TeardownHost {
+    after(fn: () => unknown): void;
+}
+/**
+ * Attempt every step in reverse registration order. Preserve a single failure's identity;
+ * report several as an AggregateError only after attempting the remaining cleanup.
+ * @param requiredArgs Steps owned by one lifecycle context; the input array is not mutated.
+ * @returns Resolves after cleanup, or rejects with the collected failure(s).
+ * @complexity O(n) time and space for n registered steps, excluding each step's own work.
+ * @example await runTeardownSteps({ steps: [closeDatabase, closeServer] });
+ */
+export declare function runTeardownSteps({ steps }: {
+    steps: readonly TeardownStep[];
+}, _options?: {}): Promise<void>;
+/**
+ * Queue a step on the host's single cleanup hook. Hosts that stop at the first throwing hook
+ * still attempt every registered resource cleanup before this hook reports a failure.
+ * @param requiredArgs Lifecycle host and a step to run when that host finishes.
+ * @returns Nothing; registers one hook on first use, then appends to that host's queue.
+ * @complexity O(1) registration; cleanup is O(n) time/space for n registered steps.
+ * @example onTeardown({ t: context, step: closeServer });
+ */
+export declare function onTeardown({ t, step }: {
+    t: TeardownHost;
+    step: TeardownStep;
+}, _options?: {}): void;
+//# sourceMappingURL=teardown.d.ts.map

package/dist/teardown.js

@@ -0,0 +1,43 @@
+const queues = new WeakMap();
+/**
+ * Attempt every step in reverse registration order. Preserve a single failure's identity;
+ * report several as an AggregateError only after attempting the remaining cleanup.
+ * @param requiredArgs Steps owned by one lifecycle context; the input array is not mutated.
+ * @returns Resolves after cleanup, or rejects with the collected failure(s).
+ * @complexity O(n) time and space for n registered steps, excluding each step's own work.
+ * @example await runTeardownSteps({ steps: [closeDatabase, closeServer] });
+ */
+export async function runTeardownSteps({ steps }, _options = {}) {
+    const failures = [];
+    for (const step of [...steps].reverse()) {
+        try {
+            await step();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1)
+        throw new AggregateError(failures, "test teardown failed", { cause: failures[0] });
+}
+/**
+ * Queue a step on the host's single cleanup hook. Hosts that stop at the first throwing hook
+ * still attempt every registered resource cleanup before this hook reports a failure.
+ * @param requiredArgs Lifecycle host and a step to run when that host finishes.
+ * @returns Nothing; registers one hook on first use, then appends to that host's queue.
+ * @complexity O(1) registration; cleanup is O(n) time/space for n registered steps.
+ * @example onTeardown({ t: context, step: closeServer });
+ */
+export function onTeardown({ t, step }, _options = {}) {
+    const queued = queues.get(t);
+    if (queued) {
+        queued.push(step);
+        return;
+    }
+    const steps = [step];
+    queues.set(t, steps);
+    t.after(() => runTeardownSteps({ steps }));
+}
+//# sourceMappingURL=teardown.js.map

package/dist/tool-input-envelope.d.ts

@@ -0,0 +1,20 @@
+/** Decode a transport's object-valued field without accepting arrays, scalars or invalid JSON.
+ * @returns A JSON object; never includes supplied values in a refusal.
+ * @throws ToolInputError when a string does not encode an object.
+ * @complexity O(n) time/space for n JSON characters; no I/O or mutation.
+ * @example decodeToolInputObject({ input: '{}' }); // {}
+ */
+export declare function decodeToolInputObject({ input }: {
+    input: unknown;
+}, _options?: Record<string, never>): unknown;
+/** Remove one delegated envelope only when the tool contract cannot own an `input` field.
+ * Mixed fields and schemas without an explicit object contract retain ordinary validation.
+ * @returns The original value or decoded inner object; never mutates caller arguments.
+ * @complexity O(k + n) time/space for k keys and n encoded input characters; no I/O.
+ * @example unwrapToolInputEnvelope({ input: { input: '{}' }, schema: { type: 'object', properties: {} } });
+ */
+export declare function unwrapToolInputEnvelope({ input, schema }: {
+    input: unknown;
+    schema: unknown;
+}, _options?: Record<string, never>): unknown;
+//# sourceMappingURL=tool-input-envelope.d.ts.map

package/dist/tool-input-envelope.js

@@ -0,0 +1,40 @@
+import { ToolInputError } from './tool-input-errors.js';
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Decode a transport's object-valued field without accepting arrays, scalars or invalid JSON.
+ * @returns A JSON object; never includes supplied values in a refusal.
+ * @throws ToolInputError when a string does not encode an object.
+ * @complexity O(n) time/space for n JSON characters; no I/O or mutation.
+ * @example decodeToolInputObject({ input: '{}' }); // {}
+ */
+export function decodeToolInputObject({ input }, _options = {}) {
+    if (typeof input !== 'string')
+        return input;
+    let decoded;
+    try {
+        decoded = JSON.parse(input);
+    }
+    catch {
+        throw new ToolInputError({ message: 'The delegated input is not valid JSON. Send one JSON object containing the tool fields.' });
+    }
+    if (!record(decoded))
+        throw new ToolInputError({ message: 'The delegated input must be a JSON object. Send the tool fields inside an object.' });
+    return decoded;
+}
+/** Remove one delegated envelope only when the tool contract cannot own an `input` field.
+ * Mixed fields and schemas without an explicit object contract retain ordinary validation.
+ * @returns The original value or decoded inner object; never mutates caller arguments.
+ * @complexity O(k + n) time/space for k keys and n encoded input characters; no I/O.
+ * @example unwrapToolInputEnvelope({ input: { input: '{}' }, schema: { type: 'object', properties: {} } });
+ */
+export function unwrapToolInputEnvelope({ input, schema }, _options = {}) {
+    if (!record(input) || !record(schema) || schema.type !== 'object')
+        return input;
+    const properties = schema.properties ?? {};
+    if (!record(properties) || Object.hasOwn(properties, 'input'))
+        return input;
+    if (Object.keys(input).length !== 1 || !Object.hasOwn(input, 'input'))
+        return input;
+    const decoded = decodeToolInputObject({ input: input.input });
+    return record(decoded) ? decoded : input;
+}
+//# sourceMappingURL=tool-input-envelope.js.map

package/dist/tool-input-normalization.js

@@ -1,5 +1,6 @@
 import { isNonArrayRecord } from './records.js';
 import { ToolInputError, ToolInputNormalizationError } from './tool-input-errors.js';
+import { unwrapToolInputEnvelope } from './tool-input-envelope.js';
 export { ToolInputNormalizationError } from './tool-input-errors.js';
 const object = (value) => isNonArrayRecord({ value });
 const keyShape = (key) => key.replace(/[_-]/g, '').toLowerCase();
@@ -204,6 +205,7 @@ const isObjectTool = (schema) => object(schema) && schema.type === 'object';
 /** First pass (open), the optional domain hook, then the final closed-schema pass. */
 async function normalizeWithinGate({ input, registration }) {
     const schema = registration.invocationSchema ?? registration.descriptor.inputSchema;
+    input = unwrapToolInputEnvelope({ input, schema });
     if (isObjectTool(schema) && !object(input))
         throw new ToolInputError({ message: `${registration.descriptor.id}: send one input object containing the tool's fields.` });
     const notes = [];

package/dist/user-facing-error.d.ts

@@ -0,0 +1,34 @@
+import { type SecretRedactionOptions } from './redact.js';
+/** Sanitized explanation and copyable evidence. Missing boundary metadata stays explicitly unavailable. */
+export interface UserFacingError {
+    readonly message: string;
+    readonly action: string;
+    readonly step: string;
+    readonly cause: string;
+    readonly errorId?: string;
+    readonly appVersion?: string;
+    readonly jiniVersion?: string;
+    readonly time?: string;
+    readonly copyText: string;
+}
+/** Boundary-owned metadata and redaction policy; formatting never reads a clock or generates IDs. */
+export interface UserFacingErrorOptions extends SecretRedactionOptions {
+    readonly errorId?: string;
+    readonly appVersion?: string;
+    readonly jiniVersion?: string;
+    readonly time?: string;
+}
+/**
+ * Format an approved explanation and an untrusted cause for disclosure and copying.
+ * Callers own disclosure policy: redaction does not make private backend facts public-safe.
+ * Redacts complete fields before bounding them; uses an existing ERR ID before a boundary fallback.
+ * No I/O, logging, clock, randomness or input mutation. Core handles hostile/circular causes.
+ * @complexity O(n) diagnostic serialization plus core redaction over all input characters; bounded output.
+ */
+export declare function formatUserFacingError(requiredArgs: {
+    message: string;
+    action: string;
+    step: string;
+    cause: unknown;
+}, optionalArgs?: UserFacingErrorOptions): UserFacingError;
+//# sourceMappingURL=user-facing-error.d.ts.map

package/dist/user-facing-error.js

@@ -0,0 +1,42 @@
+import { formatErrorForLog, redactSecrets } from './redact.js';
+/**
+ * Format an approved explanation and an untrusted cause for disclosure and copying.
+ * Callers own disclosure policy: redaction does not make private backend facts public-safe.
+ * Redacts complete fields before bounding them; uses an existing ERR ID before a boundary fallback.
+ * No I/O, logging, clock, randomness or input mutation. Core handles hostile/circular causes.
+ * @complexity O(n) diagnostic serialization plus core redaction over all input characters; bounded output.
+ */
+export function formatUserFacingError(requiredArgs, optionalArgs = {}) {
+    const diagnostic = formatErrorForLog({ error: requiredArgs.cause }, optionalArgs);
+    const existingId = diagnostic.match(/\bERR-[A-Fa-f0-9]{4}(?:-[A-Fa-f0-9]{4}){3}\b/)?.[0];
+    const metadata = {
+        errorId: existingId ?? optionalArgs.errorId,
+        appVersion: optionalArgs.appVersion,
+        jiniVersion: optionalArgs.jiniVersion,
+        time: optionalArgs.time,
+    };
+    const fields = {
+        message: safeField({ text: requiredArgs.message }, optionalArgs),
+        action: safeField({ text: requiredArgs.action }, optionalArgs),
+        step: safeField({ text: requiredArgs.step }, optionalArgs),
+        cause: bound({ text: diagnostic, limit: 4096 }),
+        ...Object.fromEntries(Object.entries(metadata).filter((entry) => entry[1] !== undefined)
+            .map(([key, text]) => [key, safeField({ text }, optionalArgs)])),
+    };
+    const labels = [
+        ['Message', fields.message], ['Next action', fields.action], ['Error ID', fields.errorId],
+        ['Step', fields.step], ['Cause', fields.cause], ['App version', fields.appVersion],
+        ['Jini version', fields.jiniVersion], ['Time', fields.time],
+    ];
+    // Exact secrets can span a fixed label and a field; scrub the assembled block as well.
+    const copyText = bound({ text: redactSecrets({ input: labels.map(([label, value]) => `${label}: ${value ?? 'Unavailable'}`).join('\n') }, optionalArgs), limit: 8192 });
+    return { ...fields, copyText };
+}
+/** Redact the complete value so a credential crossing the display bound cannot leak its prefix. */
+function safeField({ text }, options) {
+    return bound({ text: redactSecrets({ input: text }, options), limit: 512 });
+}
+function bound({ text, limit }) {
+    return text.length > limit ? text.slice(0, limit - 1) + '…' : text;
+}
+//# sourceMappingURL=user-facing-error.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {