@jangts/agent-core 0.1.1 → 0.2.0

package/dist/cjs/capabilities/tool-runtime.js

@@ -1,36 +1,88 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createToolRegistry = createToolRegistry;
+/**
+ * Bridge from typed tool definitions to the Core `ToolRegistry`.
+ *
+ * A `ToolDefinition` is the App-facing declaration: a schema adapter plus authorize, execute
+ * and parseOutput handlers. This module pins those handlers to their definition and adapts
+ * them to the lower-level `ExecutableTool` contract, while keeping the synchronous and
+ * asynchronous boundaries explicit: `invokeAsync` awaits authorization and execution,
+ * `invoke` rejects a promise from either.
+ *
+ * Exports: `createToolRegistry`.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const tools_js_1 = require("./tools.js");
-/** Preserve synchronous tools; asynchronous authorization/I/O remain awaited by Core invokeAsync. */
+/**
+ * Run authorization and execution for one call, in that order.
+ *
+ * Authorization must resolve to undefined; a discarded boolean is treated as a contract
+ * violation instead of being silently ignored. Cancellation is checked before and after each
+ * phase so an aborted request never produces a successful value.
+ */
 function execute(definition, input, context, execution) {
     const { signal, mode, diagnostics, report, createSubFlowLogger } = execution;
     signal.throwIfAborted();
-    const complete = (value) => { signal.throwIfAborted(); return value; };
+    // Re-check after the handler returned: work that completed during cancellation must not be
+    // reported as a success.
+    const complete = (value) => {
+        signal.throwIfAborted();
+        return value;
+    };
     const operation = { app: context, signal, diagnostics, report, createSubFlowLogger };
     const authorized = (result) => {
         (0, synchronous_js_1.assertion)(result, 'Tool authorization must return void');
         signal.throwIfAborted();
         const value = definition.execute(input, operation);
-        return mode === 'sync' ? complete((0, synchronous_js_1.synchronous)(value, 'Synchronous tools must not return a Promise'))
-            : (0, synchronous_js_1.isPromiseLike)(value) ? Promise.resolve(value).then(complete) : complete(value);
+        return mode === 'sync'
+            ? complete((0, synchronous_js_1.synchronous)(value, 'Synchronous tools must not return a Promise'))
+            : (0, synchronous_js_1.isPromiseLike)(value)
+                ? Promise.resolve(value).then(complete)
+                : complete(value);
     };
     const allowed = definition.authorize(input, operation);
-    return mode === 'sync' ? authorized((0, synchronous_js_1.synchronous)(allowed, 'Synchronous tool authorization must not return a Promise'))
-        : (0, synchronous_js_1.isPromiseLike)(allowed) ? Promise.resolve(allowed).then(authorized) : authorized(allowed);
+    return mode === 'sync'
+        ? authorized((0, synchronous_js_1.synchronous)(allowed, 'Synchronous tool authorization must not return a Promise'))
+        : (0, synchronous_js_1.isPromiseLike)(allowed)
+            ? Promise.resolve(allowed).then(authorized)
+            : authorized(allowed);
 }
+/**
+ * Build a sealed tool registry from typed definitions.
+ *
+ * @param definitions Tool declarations in registration order; ids must be unique.
+ * @param context App context captured for every call made through this registry.
+ * @param options Registry ports: the request-lifetime signal, diagnostics, and the error
+ *   mapping used for unavailable tools and failure codes.
+ * @returns The sealed registry.
+ * @throws Error when the registry is sealed already or an id is duplicated.
+ * @throws TypeError when a definition is invalid, raised during registration.
+ */
 function createToolRegistry(definitions, context, options) {
     const registry = new tools_js_1.ToolRegistry(options);
-    registry.registerAll(definitions.map(definition => {
+    registry.registerAll(definitions.map((definition) => {
         // Every entry point pins the same canonical handlers, including callers
         // that use this creator directly rather than defineToolCatalog.
-        const { id, kind, description, inputSchema, authorize, execute: handle, parseOutput, debugSteps } = definition;
-        const bound = Object.freeze({ id, kind, description, inputSchema,
-            authorize: authorize.bind(definition), execute: handle.bind(definition), parseOutput: parseOutput.bind(definition),
+        const { id, kind, description, inputSchema, authorize, execute: handle, parseOutput, debugSteps, } = definition;
+        const bound = Object.freeze({
+            id,
+            kind,
+            description,
+            inputSchema,
+            authorize: authorize.bind(definition),
+            execute: handle.bind(definition),
+            parseOutput: parseOutput.bind(definition),
         });
-        return { id, kind, description, debugSteps: debugSteps?.bind(definition),
-            parseInput: inputSchema.parse.bind(inputSchema), parseOutput: bound.parseOutput,
+        return {
+            id,
+            kind,
+            description,
+            debugSteps: debugSteps?.bind(definition),
+            // Bind to the adapter captured above, so a later replacement of the property on the
+            // definition cannot change what this registry validates.
+            parseInput: inputSchema.parse.bind(inputSchema),
+            parseOutput: bound.parseOutput,
             execute: (input, execution) => execute(bound, input, context, execution),
         };
     }));

package/dist/cjs/capabilities/tools.js

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeInvocation = exports.ToolRegistry = void 0;
+/**
+ * Core tool registry: the mechanism that turns registered tools into invoked tools.
+ *
+ * `ToolRegistry` owns identity, registration-time validation, cancellation, diagnostics,
+ * output parsing and success/failure bookkeeping. It deliberately knows nothing about
+ * visibility, authorization policy or domain metadata: those are App registrations, and
+ * `authorize` is called by the typed bridge in `tool-runtime.js`.
+ *
+ * `invoke` requires a synchronous tool; `invokeAsync` awaits thenables. Both reject an
+ * unknown tool and report through the ports bound at construction.
+ *
+ * Exports: `ToolRegistry`, `executeInvocation`, and the tool/invocation contracts.
+ */
 const events_js_1 = require("../execution/events.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
@@ -8,14 +21,28 @@ const cancellation_js_1 = require("../utils/cancellation.js");
 const index_js_1 = require("../diagnostics/index.js");
 const registration_js_1 = require("../utils/registration.js");
 const reporting_js_1 = require("../execution/reporting.js");
-/** Mechanism only. Visibility, authorization, schemas and semantic metadata are host registrations. */
+/**
+ * Registry mechanism only: visibility, authorization policy, schemas and semantic metadata
+ * are host registrations. A registry is mutable until sealed and keeps its own call log.
+ */
 class ToolRegistry {
+    /** Insertion order is the declaration order and is preserved by every enumeration below. */
     tools = new Map();
+    /** Sealing is one-way: a running stage must not add tools to the registry it executes. */
     sealed = false;
+    /** In-memory execution facts for this registry's lifetime, one entry per completed call. */
     executionEvents = [];
-    get events() { return Object.freeze([...this.executionEvents]); }
+    /** Frozen snapshot of the recorded execution facts. */
+    get events() {
+        return Object.freeze([...this.executionEvents]);
+    }
     diagnostics;
     ports;
+    /**
+     * @param options.execution Request-lifetime signal plus the diagnostics/observer source the
+     *   registry starts from.
+     * @param options.errors Factories for the unknown-tool error and for failure codes.
+     */
     constructor({ execution, errors } = {}) {
         this.ports = {
             signal: execution?.signal,
@@ -25,42 +52,137 @@ class ToolRegistry {
         };
         this.diagnostics = this.ports.diagnostics;
     }
-    setDiagnostics(diagnostics) { this.diagnostics = diagnostics; }
+    /**
+     * Replace the diagnostics scope used by subsequent calls.
+     *
+     * Calls already in flight keep the scope they started with.
+     *
+     * @param diagnostics New diagnostics context, or undefined to stop emitting events.
+     */
+    setDiagnostics(diagnostics) {
+        this.diagnostics = diagnostics;
+    }
+    /**
+     * Register one executable tool.
+     *
+     * The stored entry is frozen and its parsers are bound to the tool, so later changes on the
+     * caller's object cannot alter validation or execution.
+     *
+     * @param tool Executable tool; `id` and `kind` must be non-empty, and the parse and execute
+     *   handlers must all be functions.
+     * @returns This registry, for chaining.
+     * @throws Error when the registry is sealed or the id is already registered.
+     * @throws TypeError when the tool shape is invalid.
+     */
     register(tool) {
         if (this.sealed)
             throw new Error('Tool registry is sealed');
         const { id, kind, description, parseInput, parseOutput, execute, debugSteps } = tool;
-        if (!id?.trim() || !kind?.trim() || ![parseInput, parseOutput, execute].every(value => typeof value === 'function'))
+        if (!id?.trim() ||
+            !kind?.trim() ||
+            ![parseInput, parseOutput, execute].every((value) => typeof value === 'function'))
             throw new TypeError('Invalid executable tool');
         if (this.tools.has(id))
             throw new Error(`Duplicate registered tool: ${id}`);
         const input = parseInput.bind(tool), output = parseOutput.bind(tool);
-        this.tools.set(id, Object.freeze({ ...(0, registration_js_1.registrationData)(tool, ['id', 'kind', 'description', 'parseInput', 'parseOutput', 'execute', 'debugSteps']), id, kind, description,
-            debugSteps: debugSteps?.bind(tool), parseInput: input, parseOutput: output,
-            execute: execute.bind(tool) }));
+        this.tools.set(id, Object.freeze({
+            ...(0, registration_js_1.registrationData)(tool, [
+                'id',
+                'kind',
+                'description',
+                'parseInput',
+                'parseOutput',
+                'execute',
+                'debugSteps',
+            ]),
+            id,
+            kind,
+            description,
+            debugSteps: debugSteps?.bind(tool),
+            parseInput: input,
+            parseOutput: output,
+            execute: execute.bind(tool),
+        }));
         return this;
     }
+    /**
+     * Invoke a registered tool synchronously.
+     *
+     * @param request Single request object carrying `toolId`, `input`, and optional signal and
+     *   diagnostics. Exactly one argument is accepted; the arity check is runtime-enforced
+     *   because callers may bypass the type system.
+     * @returns The tool result, with frozen invocation metadata.
+     * @throws TypeError when the request shape is wrong, the diagnostics belong to another run,
+     *   or the tool returns a promise.
+     * @throws Error when the tool is unknown or the tool itself fails; the abort reason
+     *   surfaces when the signal is cancelled.
+     */
     invoke(request) {
         const call = (0, invocation_js_1.toolInvocation)(request, arguments.length);
         return this.execute(call.toolId, call.input, false, call.diagnostics, call.signal);
     }
+    /**
+     * Invoke a registered tool and await its result.
+     *
+     * @param request Single request object, identical to `invoke`.
+     * @returns The tool result once the tool settles.
+     * @throws TypeError or Error under the same conditions as `invoke`; rejections from an
+     *   asynchronous tool are propagated unchanged.
+     */
     async invokeAsync(request) {
         const call = (0, invocation_js_1.toolInvocation)(request, arguments.length);
-        return await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal);
+        return (await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal));
     }
+    /**
+     * Run one call: validate, parse input, execute, parse output, then record the outcome.
+     *
+     * @param name Registered tool id.
+     * @param input Untrusted caller input, parsed before the tool sees it.
+     * @param asynchronous Whether promises returned by the tool are awaited.
+     * @param parentDiagnostics Scope the call is recorded under; defaults to the registry's.
+     * @param requestSignal Per-call signal, combined with the request-lifetime signal.
+     * @returns The frozen result on success; every failure path throws.
+     */
     execute(name, input, asynchronous, parentDiagnostics = this.diagnostics, requestSignal) {
-        if (this.diagnostics?.identity?.runId && parentDiagnostics?.identity?.runId && this.diagnostics.identity.runId !== parentDiagnostics.identity.runId)
+        // A tool call stays inside the run that invoked it: mixing two diagnostic trees would
+        // produce records with two parents and break run-scoped correlation.
+        if (this.diagnostics?.identity?.runId &&
+            parentDiagnostics?.identity?.runId &&
+            this.diagnostics.identity.runId !== parentDiagnostics.identity.runId)
             throw new TypeError('Tool diagnostics must belong to the same run');
         const tool = this.tools.get(name);
         if (!tool)
             throw this.ports.unavailable?.(name) ?? new Error(`Tool is not registered: ${name}`);
+        // Either signal may cancel the call; combining them keeps both lifetimes effective.
         const signal = (0, cancellation_js_1.combineSignals)(this.ports.signal, requestSignal);
         const invocationId = (0, invocation_js_1.invocationId)();
-        const diagnostics = parentDiagnostics?.child(invocationId, { invocationId, nodeRole: 'invocation', definitionKind: 'tool', definitionId: name, nodeId: name, nodeName: name, nodeKind: 'tool', nodeDescription: tool.description?.slice(0, 1024), stageId: undefined, definitionRevision: undefined });
+        const diagnostics = parentDiagnostics?.child(invocationId, {
+            invocationId,
+            nodeRole: 'invocation',
+            definitionKind: 'tool',
+            definitionId: name,
+            nodeId: name,
+            nodeName: name,
+            nodeKind: 'tool',
+            // Cap the persisted description so an App-supplied string cannot inflate every record.
+            nodeDescription: tool.description?.slice(0, 1024),
+            // Tool calls are not stage-scoped; explicit undefined clears inherited span fields.
+            stageId: undefined,
+            definitionRevision: undefined,
+        });
         const reports = new reporting_js_1.NodeReports(diagnostics, signal, 'tool.result');
-        const reporting = { report: reports.report.bind(reports), createSubFlowLogger: reports.createSubFlowLogger.bind(reports) };
-        diagnostics?.emit('tool.call', () => ({ toolId: name, invocationId, ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}) }));
+        const reporting = {
+            report: reports.report.bind(reports),
+            createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
+        };
+        diagnostics?.emit('tool.call', () => ({
+            toolId: name,
+            invocationId,
+            ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}),
+        }));
         const started = Date.now();
+        // Track the phase for failure reports, so input or output parsing errors can be told
+        // apart from failures raised by the tool itself.
         let phase = 'input';
         const output = (value) => {
             signal.throwIfAborted();
@@ -74,28 +196,82 @@ class ToolRegistry {
             let debug = reports.debug();
             if (tool.debugSteps && diagnostics?.enabled('tool.result', 'content')) {
                 try {
-                    debug = reports.debug({ subs: (0, synchronous_js_1.synchronous)(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous') });
+                    debug = reports.debug({
+                        subs: (0, synchronous_js_1.synchronous)(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous'),
+                    });
                 }
                 catch (error) {
-                    debug = { usedModel: reports.debug().usedModel, subSteps: () => { throw error; } };
+                    // Debug material is optional evidence: it must not turn a successful tool call into
+                    // a failure. Defer the error until a consumer actually asks for the sub-steps.
+                    debug = {
+                        usedModel: reports.debug().usedModel,
+                        subSteps: () => {
+                            throw error;
+                        },
+                    };
                 }
             }
             signal.throwIfAborted();
             reports.close();
-            diagnostics?.emit('tool.result', () => ({ toolId: name, invocationId, status: 'success', ...(diagnostics?.enabled('tool.result', 'content') ? { value: result } : {}), durationMs: Date.now() - started }), debug);
-            this.executionEvents.push(Object.freeze({ ...diagnostics?.identity, toolId: name, invocationId, startedAtMs: started, kind: tool.kind, durationMs: Date.now() - started, status: 'success' }));
-            return (0, invocation_js_1.invocationResult)(result, { ...diagnostics?.identity, invocationId, toolId: name, startedAtMs: started, durationMs: Date.now() - started, status: 'success' });
+            diagnostics?.emit('tool.result', () => ({
+                toolId: name,
+                invocationId,
+                status: 'success',
+                ...(diagnostics?.enabled('tool.result', 'content') ? { value: result } : {}),
+                durationMs: Date.now() - started,
+            }), debug);
+            // Kept locally as well as emitted, so a run summary does not require a log consumer.
+            this.executionEvents.push(Object.freeze({
+                ...diagnostics?.identity,
+                toolId: name,
+                invocationId,
+                startedAtMs: started,
+                kind: tool.kind,
+                durationMs: Date.now() - started,
+                status: 'success',
+            }));
+            return (0, invocation_js_1.invocationResult)(result, {
+                ...diagnostics?.identity,
+                invocationId,
+                toolId: name,
+                startedAtMs: started,
+                durationMs: Date.now() - started,
+                status: 'success',
+            });
         };
         const fail = (error) => {
             reports.close();
-            diagnostics?.emit('rule.result', () => ({ tags: [name, phase], error: (0, index_js_1.diagnosticError)(error) }));
-            diagnostics?.emit('tool.result', () => ({ toolId: name, invocationId, status: signal.aborted ? 'cancelled' : 'error', ...(diagnostics?.enabled('tool.result', 'content') ? { error: (0, index_js_1.diagnosticError)(error) } : {}), durationMs: Date.now() - started }), reports.debug());
+            // Rule-level record carries the failing phase, which the tool result does not.
+            diagnostics?.emit('rule.result', () => ({
+                tags: [name, phase],
+                error: (0, index_js_1.diagnosticError)(error),
+            }));
+            diagnostics?.emit('tool.result', () => ({
+                toolId: name,
+                invocationId,
+                status: signal.aborted ? 'cancelled' : 'error',
+                ...(diagnostics?.enabled('tool.result', 'content')
+                    ? { error: (0, index_js_1.diagnosticError)(error) }
+                    : {}),
+                durationMs: Date.now() - started,
+            }), reports.debug());
             let errorCode = signal.aborted ? 'CANCELLED' : 'TOOL_ERROR';
             try {
                 errorCode = this.ports.errorCode?.(error) ?? errorCode;
             }
-            catch { /* Error decoration cannot replace the original failure. */ }
-            this.executionEvents.push(Object.freeze({ ...diagnostics?.identity, toolId: name, invocationId, startedAtMs: started, kind: tool.kind, durationMs: Date.now() - started, status: signal.aborted ? 'cancelled' : 'error', ...(errorCode ? { errorCode } : {}) }));
+            catch {
+                /* Error decoration cannot replace the original failure. */
+            }
+            this.executionEvents.push(Object.freeze({
+                ...diagnostics?.identity,
+                toolId: name,
+                invocationId,
+                startedAtMs: started,
+                kind: tool.kind,
+                durationMs: Date.now() - started,
+                status: signal.aborted ? 'cancelled' : 'error',
+                ...(errorCode ? { errorCode } : {}),
+            }));
             throw error;
         };
         try {
@@ -103,8 +279,16 @@ class ToolRegistry {
             const parsed = (0, synchronous_js_1.synchronous)(tool.parseInput(input), 'Tool input parsers must be synchronous');
             signal.throwIfAborted();
             phase = 'execute';
-            const value = tool.execute(parsed, { mode: asynchronous ? 'async' : 'sync', invocationId, signal, diagnostics, ...reporting });
+            const value = tool.execute(parsed, {
+                mode: asynchronous ? 'async' : 'sync',
+                invocationId,
+                signal,
+                diagnostics,
+                ...reporting,
+            });
             if (asynchronous)
+                // Async completions are routed to `fail` explicitly, so bookkeeping runs exactly once
+                // whether the tool settles immediately or later.
                 return (0, cancellation_js_1.awaitWithSignal)(value, signal).then(output).then(succeed).catch(fail);
             return succeed(output((0, synchronous_js_1.synchronous)(value, 'Synchronous tools must not return a Promise')));
         }
@@ -112,20 +296,71 @@ class ToolRegistry {
             return fail(error);
         }
     }
+    /**
+     * Register several tools.
+     *
+     * @param tools Executable tools applied in iteration order.
+     * @returns This registry, for chaining.
+     * @throws Error or TypeError under the same conditions as `register`.
+     */
     registerAll(tools) {
         for (const tool of tools)
             this.register(tool);
         return this;
     }
-    get(name) { return this.tools.get(name); }
-    get definitions() { return Object.freeze([...this.tools.values()]); }
-    ids() { return Object.freeze([...this.tools.keys()]); }
-    entries() { return this.tools.entries(); }
-    require(id) { const tool = this.get(id); if (!tool)
-        throw this.ports.unavailable?.(id) ?? new Error(`Tool is not registered: ${id}`); return tool; }
-    has(name) { return this.tools.has(name); }
-    values() { return this.tools.values(); }
-    seal() { this.sealed = true; return this; }
+    /**
+     * @param name Tool id.
+     * @returns The registered tool, or undefined when absent.
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** Frozen snapshot of the registered tools, in declaration order. */
+    get definitions() {
+        return Object.freeze([...this.tools.values()]);
+    }
+    /** Registered tool ids in declaration order. */
+    ids() {
+        return Object.freeze([...this.tools.keys()]);
+    }
+    /** Live iterator over `[id, tool]` pairs; it reflects only entries added before sealing. */
+    entries() {
+        return this.tools.entries();
+    }
+    /**
+     * @param id Tool id.
+     * @returns The registered tool.
+     * @throws Error when the tool is unknown; the App-supplied `unavailable` factory can
+     *   replace the default message.
+     */
+    require(id) {
+        const tool = this.get(id);
+        if (!tool)
+            throw this.ports.unavailable?.(id) ?? new Error(`Tool is not registered: ${id}`);
+        return tool;
+    }
+    /**
+     * @param name Tool id.
+     * @returns Whether the id is registered in this registry.
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /** Live iterator over the registered tools. */
+    values() {
+        return this.tools.values();
+    }
+    /**
+     * Close the registry to further registration.
+     *
+     * Sealing is idempotent and does not affect existing tools.
+     *
+     * @returns This registry.
+     */
+    seal() {
+        this.sealed = true;
+        return this;
+    }
 }
 exports.ToolRegistry = ToolRegistry;
 var invocation_js_2 = require("./invocation.js");

package/dist/cjs/context/assembly.js

@@ -2,11 +2,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commonPrefixLength = void 0;
 exports.assembleFragments = assembleFragments;
+/**
+ * Assemble validated fragments into the messages sent to the model.
+ *
+ * The order is fixed: system text first, then one user message carrying structured fields as
+ * JSON. Fragment metadata stays program-side in `fragmentUsage` and never becomes an
+ * instruction. The finished message list is measured against the overall budget, so a caller
+ * sees the same character count a transport will deliver.
+ *
+ * Exports: `assembleFragments`, plus a shared text helper and the fragment types.
+ */
 const fragments_js_1 = require("./fragments.js");
 const errors_js_1 = require("../structs/errors.js");
-/** Metadata remains program-side. Data never becomes a system instruction. */
+/**
+ * Build the model input from fragments.
+ *
+ * Metadata remains program-side: data never becomes a system instruction.
+ *
+ * @param fragments Fragments in carriage order; ids must be unique across the list.
+ * @param maxInputChars Total character budget for the resulting messages.
+ * @returns Messages, per-fragment usage and the measured input size.
+ * @throws Error when a fragment is invalid or duplicated, a user fragment carries a string
+ *   value, or two user fragments declare the same field.
+ * @throws ValidationError when a fragment or the assembled input exceeds its budget.
+ */
 function assembleFragments(fragments, maxInputChars) {
     const ids = new Set();
+    // One merged object lets duplicate field names be rejected rather than silently overwritten.
     const fields = {};
     const system = [];
     const usage = [];
@@ -20,15 +42,34 @@ function assembleFragments(fragments, maxInputChars) {
             for (const [key, value] of Object.entries(fragment.value)) {
                 if (Object.hasOwn(fields, key))
                     throw new Error(`Duplicate context field: ${key}`);
+                // defineProperty keeps names such as `__proto__` as own data instead of letting an
+                // assignment reach the object prototype.
                 Object.defineProperty(fields, key, { value, enumerable: true });
             }
         }
-        usage.push({ id: fragment.id, sourceId: fragment.sourceId, trust: fragment.trust, lifetime: fragment.lifetime,
-            chars: serialized.length, maxChars: fragment.maxChars });
+        usage.push({
+            id: fragment.id,
+            sourceId: fragment.sourceId,
+            trust: fragment.trust,
+            lifetime: fragment.lifetime,
+            chars: serialized.length,
+            maxChars: fragment.maxChars,
+        });
     }
-    const messages = [{ role: 'system', content: system.join('\n\n') }, { role: 'user', content: JSON.stringify(fields) }];
+    // Blank-line separation keeps independently declared instructions readable and attributable
+    // while still arriving as one system message.
+    const messages = [
+        { role: 'system', content: system.join('\n\n') },
+        { role: 'user', content: JSON.stringify(fields) },
+    ];
+    // Measured on the exact strings above, so the count matches what the transport will send.
     const inputChars = messages.reduce((sum, message) => sum + message.content.length, 0);
-    (0, fragments_js_1.validateContextBudget)(inputChars, maxInputChars, () => new errors_js_1.ValidationError([{ code: 'CONTEXT_BUDGET', message: `上下文超过${maxInputChars}字符；不截断原问题、约束与证据。` }]));
+    (0, fragments_js_1.validateContextBudget)(inputChars, maxInputChars, () => new errors_js_1.ValidationError([
+        {
+            code: 'CONTEXT_BUDGET',
+            message: `上下文超过${maxInputChars}字符；不截断原问题、约束与证据。`,
+        },
+    ]));
     return { messages, fragmentUsage: usage, inputChars, maxInputChars };
 }
 var text_js_1 = require("../utils/text.js");

package/dist/cjs/context/audit.js

@@ -3,20 +3,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.auditContextChange = auditContextChange;
 const errors_js_1 = require("../structs/errors.js");
 const rules_js_1 = require("../utils/rules.js");
+/** Single code for every violation, so consumers can classify audit failures uniformly. */
 const fail = (message) => new errors_js_1.ValidationError([{ code: 'CONTEXT_POLICY', message }]);
-/** Structural audit only: semantic fidelity of a summary requires an application audit. */
+/**
+ * Compare trusted originals with the fragments about to be assembled.
+ *
+ * @param original Fragments captured before any App-side processing.
+ * @param current Fragments that will actually be assembled; same length as `original`.
+ * @param mutable Ids explicitly allowed to change value. Everything else is protected.
+ * @returns Nothing; a clean audit has no side effect.
+ * @throws ValidationError when the fragment list, its metadata, the value type or the field
+ *   set changed, or when a protected fragment was rewritten.
+ */
 function auditContextChange(original, current, mutable) {
+    // Fragments may be rewritten in place but not added or removed: assembly and audit both
+    // assume the same positions describe the same fragment.
     (0, rules_js_1.breakWhile)(original.length !== current.length, fail('Context fragments cannot be added or removed'));
     for (const [index, before] of original.entries()) {
         const after = current[index];
+        // Metadata and value are compared separately: only the value may be rewritten, and only
+        // for ids the plan explicitly allows.
         const { value: _before, ...beforeMetadata } = before;
         const { value: _after, ...afterMetadata } = after;
-        (0, rules_js_1.breakWhile)(Object.keys(beforeMetadata).length !== Object.keys(afterMetadata).length
-            || Object.entries(beforeMetadata).some(([key, value]) => afterMetadata[key] !== value), fail('Context identity, trust and budgets must be preserved'));
+        (0, rules_js_1.breakWhile)(Object.keys(beforeMetadata).length !== Object.keys(afterMetadata).length ||
+            Object.entries(beforeMetadata).some(([key, value]) => afterMetadata[key] !== value), fail('Context identity, trust and budgets must be preserved'));
+        // A type change would alter how the fragment is serialized, so it is rejected before any
+        // value comparison is attempted.
         (0, rules_js_1.breakWhile)(typeof before.value !== typeof after.value, fail('Context value type must be preserved'));
+        // String comparison captures both values and their key order; a reordered rewrite counts
+        // as a change, which is the conservative direction for an audit.
         const changed = JSON.stringify(before.value) !== JSON.stringify(after.value);
-        (0, rules_js_1.breakWhile)(changed && (!mutable.has(before.id) || before.role === 'system' || before.trust === 'instruction'), fail(`Protected context changed: ${before.id}`));
-        if (changed && typeof before.value === 'object' && typeof after.value === 'object')
-            (0, rules_js_1.breakWhile)(JSON.stringify(Object.keys(before.value).sort()) !== JSON.stringify(Object.keys(after.value).sort()), fail('Context fields must be preserved'));
+        (0, rules_js_1.breakWhile)(changed &&
+            (!mutable.has(before.id) || before.role === 'system' || before.trust === 'instruction'), fail(`Protected context changed: ${before.id}`));
+        if (changed &&
+            before.value !== null &&
+            after.value !== null &&
+            typeof before.value === 'object' &&
+            typeof after.value === 'object')
+            // Only the field set is compared here; field order is not meaningful for context data.
+            (0, rules_js_1.breakWhile)(JSON.stringify(Object.keys(before.value).sort()) !==
+                JSON.stringify(Object.keys(after.value).sort()), fail('Context fields must be preserved'));
     }
 }