@jangts/agent-core 0.1.1 → 0.2.1

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'));
     }
 }

package/dist/cjs/context/fragments.js

@@ -5,30 +5,73 @@ exports.validateContextFragment = validateContextFragment;
 exports.validateContextBudget = validateContextBudget;
 const errors_js_1 = require("../structs/errors.js");
 const rules_js_1 = require("../utils/rules.js");
-/** Validate one fragment before formatting. The shared set preserves registration order. */
+/**
+ * Validate one fragment and return the text it contributes to the model input.
+ *
+ * @param fragment Declaration to check.
+ * @param ids Optional accumulator of ids already seen. Callers validating a batch pass the
+ *   same set for every fragment so duplicates are detected across the whole input.
+ * @param checkBudget Whether this fragment's own `maxChars` is enforced. Disable only when the
+ *   same serialized text has already been checked against the identical limit.
+ * @returns The exact text the fragment contributes: the value when it is a string, otherwise
+ *   the JSON form used for structured fields.
+ * @throws Error when identity, trust, lifetime, role, the `maxChars` declaration or the value
+ *   shape is invalid, or when untrusted content is declared as a system instruction.
+ * @throws ValidationError when the serialized text exceeds `maxChars`; text is never truncated.
+ */
 function validateContextFragment(fragment, ids = new Set(), checkBudget = true) {
-    if (!/^[a-z][a-zA-Z0-9:._-]*$/.test(fragment.id) || ids.has(fragment.id) || !fragment.sourceId
-        || !['instruction', 'server', 'user', 'tool'].includes(fragment.trust)
-        || !['configuration', 'turn', 'step'].includes(fragment.lifetime) || !['system', 'user'].includes(fragment.role)
-        || !Number.isSafeInteger(fragment.maxChars) || fragment.maxChars < 1)
+    // Ids are stable keys in usage records and protected-context errors, so they start with a
+    // lowercase letter and admit only characters that are safe in both positions.
+    if (!/^[a-z][a-zA-Z0-9:._-]*$/.test(fragment.id) ||
+        ids.has(fragment.id) ||
+        !fragment.sourceId ||
+        !['instruction', 'server', 'user', 'tool'].includes(fragment.trust) ||
+        !['configuration', 'turn', 'step'].includes(fragment.lifetime) ||
+        !['system', 'user'].includes(fragment.role) ||
+        !Number.isSafeInteger(fragment.maxChars) ||
+        fragment.maxChars < 1)
         throw new Error('Invalid context fragment');
+    // Consumed before the later checks: a failed fragment must not leave its id reusable by a
+    // retry through the same accumulator.
     ids.add(fragment.id);
-    if (fragment.role === 'system' && (fragment.trust === 'user' || fragment.trust === 'tool' || typeof fragment.value !== 'string'))
+    if (fragment.role === 'system' &&
+        (fragment.trust === 'user' || fragment.trust === 'tool' || typeof fragment.value !== 'string'))
         throw new Error('Untrusted context cannot become a system instruction');
-    if (typeof fragment.value !== 'string' && (!fragment.value || typeof fragment.value !== 'object' || Array.isArray(fragment.value)))
+    if (typeof fragment.value !== 'string' &&
+        (!fragment.value || typeof fragment.value !== 'object' || Array.isArray(fragment.value)))
         throw new Error('Invalid context value');
+    // Structured values are measured as the JSON text that will be sent, so the declared budget
+    // describes the payload rather than the in-memory object.
     const serialized = typeof fragment.value === 'string' ? fragment.value : JSON.stringify(fragment.value);
     if (checkBudget && serialized.length > fragment.maxChars)
-        throw new errors_js_1.ValidationError([{ code: 'CONTEXT_BUDGET', message: `上下文片段 ${fragment.id} 超过预算；不截断原问题、约束与证据。` }]);
+        throw new errors_js_1.ValidationError([
+            {
+                code: 'CONTEXT_BUDGET',
+                message: `上下文片段 ${fragment.id} 超过预算；不截断原问题、约束与证据。`,
+            },
+        ]);
     return serialized;
 }
-/** Core input-budget boundary; helpers may retain their existing error presentation. */
+/**
+ * Enforce the character budget of the whole model input.
+ *
+ * @param inputChars Characters that will be sent; must be a non-negative safe integer.
+ * @param maxInputChars Budget limit. `Infinity` is accepted as an explicit "no limit", which
+ *   is why it is allowed in place of a safe integer.
+ * @param exceeded Optional factory for the over-budget error. Support may pass one to keep its
+ *   own message; Core otherwise raises a `CONTEXT_BUDGET` ValidationError.
+ * @returns Nothing.
+ * @throws TypeError when either count is not a non-negative integer.
+ * @throws Error when the budget is exceeded: the `exceeded` result, or a ValidationError.
+ */
 function validateContextBudget(inputChars, maxInputChars, exceeded) {
     (0, rules_js_1.breakWhile)(!Number.isSafeInteger(inputChars) || inputChars < 0, () => new TypeError('Invalid context input size'));
     (0, rules_js_1.breakWhile)(maxInputChars !== Infinity && (!Number.isSafeInteger(maxInputChars) || maxInputChars < 0), () => new TypeError('Invalid context budget'));
     if (inputChars > maxInputChars)
-        throw exceeded?.(maxInputChars)
-            ?? new errors_js_1.ValidationError([{ code: 'CONTEXT_BUDGET', message: `Model input exceeds ${maxInputChars} characters` }]);
+        throw (exceeded?.(maxInputChars) ??
+            new errors_js_1.ValidationError([
+                { code: 'CONTEXT_BUDGET', message: `Model input exceeds ${maxInputChars} characters` },
+            ]));
 }
 var text_js_1 = require("../utils/text.js");
 Object.defineProperty(exports, "commonPrefixLength", { enumerable: true, get: function () { return text_js_1.commonPrefixLength; } });

package/dist/cjs/context/index.js

@@ -15,6 +15,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assembleContextPlan = exports.assembleFragments = void 0;
+/**
+ * Context surface: fragment trust, per-fragment budgets, message assembly, structural audit,
+ * the request-local journal and plan assembly.
+ *
+ * Core owns the guarantees here. A fragment declares its trust, lifetime and character
+ * budget in one place; assembly validates those declarations and refuses to truncate;
+ * auditing rejects structural change to protected fragments. Selection, ordering, compression
+ * and model choice remain App-side nodes that run before this boundary.
+ *
+ * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal`, the fragment helpers,
+ * and the evidence Kit helpers consumed alongside assembled context.
+ */
 __exportStar(require("./fragments.js"), exports);
 var assembly_js_1 = require("./assembly.js");
 Object.defineProperty(exports, "assembleFragments", { enumerable: true, get: function () { return assembly_js_1.assembleFragments; } });