@ai-agent-forge/agent-forge 0.86.7 → 0.88.0

package/dist/core/extensions/capability-runtime.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { performance } from "node:perf_hooks";
+import { t } from "../i18n/index.js";
 import { createLifecycleRuntime } from "./capability-runtime-events.js";
 import { guardedComposition, guardedCredentials, guardedInteraction, guardedOutput, guardedSession, RuntimeAgentTask, withNormalizedToolResultExecute, } from "./capability-runtime-guards.js";
 import { createRuntimeInspector } from "./capability-runtime-inspect.js";
@@ -48,55 +49,55 @@ export function createCapabilityRuntime(inputHost, options = {}) {
     const hasSessionExport = host.features.includes("session-export");
     const hasSessionRevision = host.features.includes("session-revision-v1");
     if (hasSession && !options.session) {
-        throw new Error("Host declares session capability without a SessionAPI");
+        throw new Error(t("Host declares session capability without a SessionAPI"));
     }
     if (!hasSession && options.session) {
-        throw new Error("Host provides a SessionAPI without the session capability");
+        throw new Error(t("Host provides a SessionAPI without the session capability"));
     }
     if (hasSessionExport && !hasSession) {
-        throw new Error("Host declares session-export capability without the session capability");
+        throw new Error(t("Host declares session-export capability without the session capability"));
     }
     if (hasSessionExport && !options.session?.exportArtifact) {
-        throw new Error("Host declares session-export capability without SessionAPI.exportArtifact");
+        throw new Error(t("Host declares session-export capability without SessionAPI.exportArtifact"));
     }
     if (hasSessionRevision && !hasSession) {
-        throw new Error("Host declares session-revision-v1 capability without the session capability");
+        throw new Error(t("Host declares session-revision-v1 capability without the session capability"));
     }
     if (hasSessionRevision && !options.session?.getRevision) {
-        throw new Error("Host declares session-revision-v1 capability without SessionAPI.getRevision");
+        throw new Error(t("Host declares session-revision-v1 capability without SessionAPI.getRevision"));
     }
     if (host.features.includes("agents") && !options.session) {
-        throw new Error("Host declares agents capability without a parent SessionAPI");
+        throw new Error(t("Host declares agents capability without a parent SessionAPI"));
     }
     if (host.features.includes("agents") &&
         !options.agents &&
         options.agentSessionReader === undefined &&
         options.agentSessionLister === undefined) {
-        throw new Error("Host declares agents capability without an AgentTaskAdapter or a session reader/lister");
+        throw new Error(t("Host declares agents capability without an AgentTaskAdapter or a session reader/lister"));
     }
     if (options.agents && !host.features.includes("agents")) {
-        throw new Error("Host provides an AgentTaskAdapter without the agents capability");
+        throw new Error(t("Host provides an AgentTaskAdapter without the agents capability"));
     }
     if (options.agentResults && !host.features.includes("agent-result-replay-v1")) {
-        throw new Error("Host provides an agentResults option without the agent-result-replay-v1 capability");
+        throw new Error(t("Host provides an agentResults option without the agent-result-replay-v1 capability"));
     }
     if (host.features.includes("agent-result-replay-v1") && !options.agentResults) {
-        throw new Error("Host declares agent-result-replay-v1 capability without an agentResults option");
+        throw new Error(t("Host declares agent-result-replay-v1 capability without an agentResults option"));
     }
     if (host.features.includes("credentials") && !options.credentials) {
-        throw new Error("Host declares credentials capability without a CredentialAPI");
+        throw new Error(t("Host declares credentials capability without a CredentialAPI"));
     }
     if (options.credentials && !host.features.includes("credentials")) {
-        throw new Error("Host provides a CredentialAPI without the credentials capability");
+        throw new Error(t("Host provides a CredentialAPI without the credentials capability"));
     }
     if (host.features.includes("interaction") && !options.interaction) {
-        throw new Error("Host declares interaction capability without an InteractionHostV1");
+        throw new Error(t("Host declares interaction capability without an InteractionHostV1"));
     }
     if (options.interaction && !host.features.includes("interaction")) {
-        throw new Error("Host provides an InteractionHostV1 without the interaction capability");
+        throw new Error(t("Host provides an InteractionHostV1 without the interaction capability"));
     }
     if (host.features.includes("agent-result-replay-v1") && !host.features.includes("agents")) {
-        throw new Error("Host declares the agent-result-replay-v1 feature without the agents capability");
+        throw new Error(t("Host declares the agent-result-replay-v1 feature without the agents capability"));
     }
     const clock = options.clock ?? (() => 0);
     // Per-runtime unique segment for generated agent task ids: without an
@@ -128,7 +129,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             return fallback;
         const id = options.idFactory(kind, sequence);
         if (typeof id !== "string" || !id.trim()) {
-            throw new Error(`Runtime idFactory must return a non-empty string for ${kind}`);
+            throw new Error(t("Runtime idFactory must return a non-empty string for {kind}", { kind }));
         }
         return id;
     };
@@ -285,12 +286,12 @@ export function createCapabilityRuntime(inputHost, options = {}) {
     };
     const assertStateKey = (key) => {
         if (typeof key !== "string" || !key.trim())
-            throw new Error("State key must be a non-empty string");
+            throw new Error(t("State key must be a non-empty string"));
     };
     const assertStateOptions = (options) => {
         if (options?.expectedRevision !== undefined &&
             (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision < 0)) {
-            throw new Error("State expectedRevision must be a non-negative safe integer");
+            throw new Error(t("State expectedRevision must be a non-negative safe integer"));
         }
     };
     const stateSnapshot = (key, state) => detachedSnapshot({ key, revision: state.revision, value: state.value });
@@ -313,9 +314,9 @@ export function createCapabilityRuntime(inputHost, options = {}) {
     const notifyStateWatchers = (owner, change) => dispatchStateChange(stateWatchers.get(owner), owner, change);
     const recordLog = (level, owner, message, fields, cause) => {
         if (typeof message !== "string" || !message.trim())
-            throw new Error("Logger message must be non-empty");
+            throw new Error(t("Logger message must be non-empty"));
         if (fields !== undefined && !isPluginConfigValue(fields))
-            throw new Error("Logger fields must be serializable");
+            throw new Error(t("Logger fields must be serializable"));
         const record = {
             version: 1,
             level,
@@ -436,12 +437,12 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             assertStateKey(key);
             assertStateOptions(options);
             if (!isPluginConfigValue(value))
-                throw new Error("State value must be serializable");
+                throw new Error(t("State value must be serializable"));
             const namespace = view.ensureNamespace();
             const revisions = view.ensureRevisions();
             const currentRevision = revisions.get(key) ?? 0;
             if (options?.expectedRevision !== undefined && options.expectedRevision !== currentRevision)
-                throw new Error(`State revision conflict: ${view.conflictScope}/${key}`);
+                throw new Error(t("State revision conflict: {conflictScope}/{key}", { conflictScope: view.conflictScope, key }));
             const revision = currentRevision + 1;
             revisions.set(key, revision);
             namespace.set(key, { revision, value: detachedSnapshot(value) });
@@ -463,7 +464,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             const revisions = view.ensureRevisions();
             const currentRevision = revisions.get(key) ?? 0;
             if (options?.expectedRevision !== undefined && options.expectedRevision !== currentRevision)
-                throw new Error(`State revision conflict: ${view.conflictScope}/${key}`);
+                throw new Error(t("State revision conflict: {conflictScope}/{key}", { conflictScope: view.conflictScope, key }));
             const revision = currentRevision + 1;
             revisions.set(key, revision);
             namespace.delete(key);
@@ -479,7 +480,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         list: (prefix) => {
             assertUsable();
             if (prefix !== undefined && typeof prefix !== "string")
-                throw new Error("State prefix must be a string");
+                throw new Error(t("State prefix must be a string"));
             return view
                 .listEntries()
                 .filter(([key]) => prefix === undefined || key.startsWith(prefix))
@@ -489,9 +490,9 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         watch: (prefix, handler) => {
             assertUsable();
             if (prefix !== undefined && typeof prefix !== "string")
-                throw new Error("State prefix must be a string");
+                throw new Error(t("State prefix must be a string"));
             if (typeof handler !== "function")
-                throw new Error("State watcher requires a handler");
+                throw new Error(t("State watcher requires a handler"));
             const watchers = view.ensureWatchers();
             const sequence = ++stateWatcherSequence;
             const id = createRuntimeId("state-watcher", sequence, `state-watcher:${view.watchScope}:${sequence}`);
@@ -589,7 +590,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         const entry = { owner, ownerToken, value };
         if (registry.has(name)) {
             if (!replaceable)
-                throw new Error(`${kind} is already registered: ${name}`);
+                throw new Error(t("{kind} is already registered: {name}", { kind, name }));
             const replaced = registry.get(name);
             // 同 owner 重注册 = 更新自身注册，不进替换链；恢复语义只跨 owner 生效。
             if (replaced.ownerToken !== ownerToken) {
@@ -631,7 +632,11 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 continue;
             if (requirement.optional)
                 continue;
-            throw new Error(`Plugin capability is required but unavailable: ${requirement.id}@${requirement.version} (${manifest.id})`);
+            throw new Error(t("Plugin capability is required but unavailable: {capabilityId}@{version} ({pluginId})", {
+                capabilityId: requirement.id,
+                version: requirement.version,
+                pluginId: manifest.id,
+            }));
         }
     };
     const listContributionEntries = (point) => Array.from(point.entries.values())
@@ -669,10 +674,10 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             async add(input) {
                 assertPointActive();
                 if (!input || typeof input.id !== "string" || !input.id.trim()) {
-                    throw new Error(`Contribution requires a non-empty id: ${pointId}`);
+                    throw new Error(t("Contribution requires a non-empty id: {pointId}", { pointId }));
                 }
                 if (point.entries.has(input.id)) {
-                    throw new Error(`Contribution is already registered: ${pointId}@${version}:${input.id}`);
+                    throw new Error(t("Contribution is already registered: {pointId}@{version}:{id}", { pointId, version, id: input.id }));
                 }
                 const value = detachedSnapshot(point.definition.validate(detachedSnapshot(input.value)));
                 const entry = Object.freeze({ id: input.id, pointId, version, owner, ownerToken, lifecycle, value });
@@ -712,9 +717,13 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 assertPointActive();
                 const entry = point.entries.get(id);
                 if (!entry)
-                    throw new Error(`Contribution is not registered: ${pointId}@${version}:${id}`);
+                    throw new Error(t("Contribution is not registered: {pointId}@{version}:{id}", { pointId, version, id }));
                 if (entry.ownerToken !== ownerToken)
-                    throw new Error(`Contribution can only be removed by its owner: ${pointId}@${version}:${id}`);
+                    throw new Error(t("Contribution can only be removed by its owner: {pointId}@{version}:{id}", {
+                        pointId,
+                        version,
+                        id,
+                    }));
                 point.entries.delete(id);
                 await notifyContributionSubscribers(point, {
                     pointId,
@@ -731,7 +740,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             subscribe: (handler) => {
                 assertPointActive();
                 if (typeof handler !== "function")
-                    throw new Error(`Contribution subscriber must be callable: ${pointId}`);
+                    throw new Error(t("Contribution subscriber must be callable: {pointId}", { pointId }));
                 const sequence = ++contributionSubscriptionSequence;
                 const id = createRuntimeId("contribution-subscription", sequence, `contribution-subscription:${owner}:${pointId}@${version}:${sequence}`);
                 point.subscribers.set(id, { ownerToken, handler });
@@ -744,15 +753,15 @@ export function createCapabilityRuntime(inputHost, options = {}) {
     const lifecycleReference = (event, version) => {
         if (typeof event === "string") {
             if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) {
-                throw new Error("Lifecycle event version must be provided as a positive safe integer");
+                throw new Error(t("Lifecycle event version must be provided as a positive safe integer"));
             }
             return { id: event, version };
         }
         if (!event || typeof event !== "object" || typeof event.id !== "string" || !event.id.trim()) {
-            throw new Error("Lifecycle event reference requires a non-empty id");
+            throw new Error(t("Lifecycle event reference requires a non-empty id"));
         }
         if (!Number.isSafeInteger(event.version) || event.version < 1) {
-            throw new Error("Lifecycle event version must be a positive safe integer");
+            throw new Error(t("Lifecycle event version must be a positive safe integer"));
         }
         return { id: event.id, version: event.version };
     };
@@ -760,32 +769,34 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         const reference = lifecycleReference(event, version);
         const stored = lifecycleDefinitions.get(lifecycleEventKey(reference.id, reference.version));
         if (!stored || !activeOwnerTokens.has(stored.ownerToken)) {
-            throw new Error(`Lifecycle event is not defined: ${reference.id}@${reference.version}`);
+            throw new Error(t("Lifecycle event is not defined: {id}@{version}", { id: reference.id, version: reference.version }));
         }
         return stored;
     };
     const lifecycleRegistration = (kind, event, handler, version, owner, ownerToken, assertUsable, own, deliveryOptions) => {
         assertUsable();
         if (!lifecycleRegistrationKinds.has(kind) || typeof handler !== "function") {
-            throw new Error(`Lifecycle ${kind} registration requires a callable handler`);
+            throw new Error(t("Lifecycle {kind} registration requires a callable handler", { kind }));
         }
         const stored = lifecycleDefinitionFor(event, version);
         if (stored.definition.allowedRegistrationKinds?.includes(kind) === false) {
-            throw new Error(`Lifecycle ${kind} registration is not allowed: ${stored.definition.id}`);
+            throw new Error(t("Lifecycle {kind} registration is not allowed: {id}", { kind, id: stored.definition.id }));
         }
         if (kind === "transform" &&
             !(stored.definition.allowedPhases ?? [stored.definition.phase]).includes("candidate")) {
-            throw new Error(`Lifecycle transform requires a candidate event: ${stored.definition.id}`);
+            throw new Error(t("Lifecycle transform requires a candidate event: {id}", { id: stored.definition.id }));
         }
         if (kind === "execute" && !(stored.definition.allowedPhases ?? [stored.definition.phase]).includes("committed")) {
-            throw new Error(`Lifecycle execute requires a committed event: ${stored.definition.id}`);
+            throw new Error(t("Lifecycle execute requires a committed event: {id}", { id: stored.definition.id }));
         }
         if (kind === "after-commit" &&
             !(stored.definition.allowedPhases ?? [stored.definition.phase]).includes("committed")) {
-            throw new Error(`Lifecycle after-commit requires a committed event: ${stored.definition.id}`);
+            throw new Error(t("Lifecycle after-commit requires a committed event: {id}", { id: stored.definition.id }));
         }
         if (deliveryOptions !== undefined && kind !== "observe" && kind !== "after-commit") {
-            throw new Error(`Lifecycle delivery options are only supported for observation registrations: ${stored.definition.id}`);
+            throw new Error(t("Lifecycle delivery options are only supported for observation registrations: {id}", {
+                id: stored.definition.id,
+            }));
         }
         const key = lifecycleEventKey(stored.definition.id, stored.definition.version);
         const sequence = ++lifecycleRegistrationSequence;
@@ -809,7 +820,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 measureBytes: (delivery) => {
                     const serialized = JSON.stringify(delivery.event);
                     if (serialized === undefined)
-                        throw new Error("Lifecycle event is not serializable");
+                        throw new Error(t("Lifecycle event is not serializable"));
                     return new TextEncoder().encode(serialized).byteLength || 1;
                 },
                 deliver: (delivery) => {
@@ -933,11 +944,11 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             start: (name, attributes, parentSpanId) => {
                 assertUsable();
                 if (typeof name !== "string" || !name.trim())
-                    throw new Error("Diagnostic span name must be non-empty");
+                    throw new Error(t("Diagnostic span name must be non-empty"));
                 if (attributes !== undefined && !isPluginConfigValue(attributes))
-                    throw new Error("Diagnostic attributes must be serializable");
+                    throw new Error(t("Diagnostic attributes must be serializable"));
                 if (parentSpanId !== undefined && (typeof parentSpanId !== "string" || !parentSpanId.trim()))
-                    throw new Error("Diagnostic parentSpanId must be non-empty");
+                    throw new Error(t("Diagnostic parentSpanId must be non-empty"));
                 const spanSequenceValue = ++spanSequence;
                 const spanId = createRuntimeId("span", spanSequenceValue, `span:${owner}:${spanSequenceValue}`);
                 const traceId = parentSpanId
@@ -970,12 +981,12 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     annotate(fields) {
                         assertUsable();
                         if (ended)
-                            throw new Error(`Diagnostic span is already ended: ${spanId}`);
+                            throw new Error(t("Diagnostic span is already ended: {spanId}", { spanId }));
                         if (!fields || typeof fields !== "object" || Array.isArray(fields) || !isPluginConfigValue(fields))
-                            throw new Error("Diagnostic annotations must be a plain object");
+                            throw new Error(t("Diagnostic annotations must be a plain object"));
                         const current = spans.get(spanId);
                         if (!current)
-                            throw new Error(`Diagnostic span is not available: ${spanId}`);
+                            throw new Error(t("Diagnostic span is not available: {spanId}", { spanId }));
                         current.attributes = detachedSnapshot({
                             ...current.attributes,
                             ...fields,
@@ -984,14 +995,14 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     end(outcome = { status: "ok" }) {
                         assertUsable();
                         if (ended)
-                            throw new Error(`Diagnostic span is already ended: ${spanId}`);
+                            throw new Error(t("Diagnostic span is already ended: {spanId}", { spanId }));
                         if (!["ok", "error", "cancelled"].includes(outcome.status))
-                            throw new Error("Diagnostic span status is invalid");
+                            throw new Error(t("Diagnostic span status is invalid"));
                         if (outcome.result !== undefined && !isPluginConfigValue(outcome.result))
-                            throw new Error("Diagnostic span result must be serializable");
+                            throw new Error(t("Diagnostic span result must be serializable"));
                         const current = spans.get(spanId);
                         if (!current)
-                            throw new Error(`Diagnostic span is not available: ${spanId}`);
+                            throw new Error(t("Diagnostic span is not available: {spanId}", { spanId }));
                         ended = true;
                         current.status = outcome.status;
                         current.endedAt = clock();
@@ -1021,14 +1032,21 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 assertUsable();
                 assertPluginCapabilityDeclarations([declaration], `Plugin capability declaration: ${owner}`);
                 if (typeof handler !== "function")
-                    throw new Error("Plugin capability provider requires a callable handler");
+                    throw new Error(t("Plugin capability provider requires a callable handler"));
                 const declared = manifestSnapshot.provides?.some((item) => item.id === declaration.id && item.version === declaration.version && item.kind === declaration.kind);
                 if (!declared) {
-                    throw new Error(`Plugin capability must be declared by its manifest: ${declaration.id}@${declaration.version} (${owner})`);
+                    throw new Error(t("Plugin capability must be declared by its manifest: {id}@{version} ({owner})", {
+                        id: declaration.id,
+                        version: declaration.version,
+                        owner,
+                    }));
                 }
                 const key = capabilityKey(declaration.id, declaration.version);
                 if (pluginCapabilities.has(key)) {
-                    throw new Error(`Plugin capability is already provided: ${declaration.id}@${declaration.version}`);
+                    throw new Error(t("Plugin capability is already provided: {id}@{version}", {
+                        id: declaration.id,
+                        version: declaration.version,
+                    }));
                 }
                 const registered = {
                     declaration: detachedSnapshot(declaration),
@@ -1049,7 +1067,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 assertPluginCapabilityVersion(version, "Plugin capability version");
                 const registered = pluginCapabilities.get(capabilityKey(id, version));
                 if (!registered)
-                    throw new Error(`Plugin capability is not available: ${id}@${version}`);
+                    throw new Error(t("Plugin capability is not available: {id}@{version}", { id, version }));
                 const declaration = detachedSnapshot(registered.declaration);
                 return Object.freeze({
                     declaration,
@@ -1096,7 +1114,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 const validated = validateContributionPointDefinition(definition);
                 const key = contributionPointKey(validated.id, validated.version);
                 if (contributionPoints.has(key))
-                    throw new Error(`Contribution point is already defined: ${key}`);
+                    throw new Error(t("Contribution point is already defined: {key}", { key }));
                 const point = {
                     owner,
                     ownerToken,
@@ -1135,7 +1153,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             const adapter = options.agents;
             const session = options.session;
             if (!adapter || !session)
-                throw new Error("Agent task capability is not available from this host");
+                throw new Error(t("Agent task capability is not available from this host"));
             const hostTask = await adapter.create(request);
             try {
                 assertUsable();
@@ -1345,7 +1363,9 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     get: () => sessionApi.getContextSnapshot(),
                     commit: async (request) => {
                         if (request.operationId !== operationId) {
-                            throw new Error(`Agent context operationId must match active operation: ${operationId}`);
+                            throw new Error(t("Agent context operationId must match active operation: {operationId}", {
+                                operationId,
+                            }));
                         }
                         return sessionApi.commitContext({ ...request, signal: request.signal ?? signal });
                     },
@@ -1356,13 +1376,13 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     ...stateApi,
                     set: (key, value, options) => {
                         if (options?.operationId !== undefined && options.operationId !== operationId) {
-                            throw new Error(`Agent state operationId must match active operation: ${operationId}`);
+                            throw new Error(t("Agent state operationId must match active operation: {operationId}", { operationId }));
                         }
                         return stateApi.set(key, value, { ...options, operationId });
                     },
                     delete: (key, options) => {
                         if (options?.operationId !== undefined && options.operationId !== operationId) {
-                            throw new Error(`Agent state operationId must match active operation: ${operationId}`);
+                            throw new Error(t("Agent state operationId must match active operation: {operationId}", { operationId }));
                         }
                         return stateApi.delete(key, { ...options, operationId });
                     },
@@ -1402,14 +1422,14 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                         const runtime = options.modelRuntime;
                         const resolved = runtime.getModelFacts();
                         if (!resolved)
-                            throw new Error("No model is set on this session's agent");
+                            throw new Error(t("No model is set on this session's agent"));
                         return resolved;
                     },
                     invocation: {
                         invoke: async (input, signal) => {
                             const runtime = options.modelRuntime;
                             if (!runtime)
-                                throw new Error("Agent model runtime is not available");
+                                throw new Error(t("Agent model runtime is not available"));
                             return runtime.invoke({
                                 ...(input.systemPrompt === undefined ? {} : { systemPrompt: input.systemPrompt }),
                                 prompt: input.prompt,
@@ -1439,7 +1459,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                         assertUsable();
                         const registered = tools.get(name);
                         if (!registered || !activeOwnerTokens.has(registered.ownerToken)) {
-                            throw new Error(`Agent tool is not registered: ${name}`);
+                            throw new Error(t("Agent tool is not registered: {name}", { name }));
                         }
                         return invokeRegisteredCapability(registered, (value) => invokeCapabilityTool(asHandler(value, "Tool"), input, toolExecutionContext, invokeOptions?.signal));
                     },
@@ -1462,7 +1482,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 const normalized = validateLifecycleEventDefinition(definition);
                 const key = lifecycleEventKey(normalized.id, normalized.version);
                 if (lifecycleDefinitions.has(key))
-                    throw new Error(`Lifecycle event is already defined: ${key}`);
+                    throw new Error(t("Lifecycle event is already defined: {key}", { key }));
                 lifecycleDefinitions.set(key, { owner, ownerToken, definition: normalized });
                 const registration = own(createDisposableRegistration("lifecycle-definition", () => {
                     const current = lifecycleDefinitions.get(key);
@@ -1602,33 +1622,33 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             registerOperation(name, handler) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Operation requires a non-empty name");
+                    throw new Error(t("Operation requires a non-empty name"));
                 return own(register("operation", name, handler, owner, ownerToken, operations));
             },
             registerRpcMethod(name, handler) {
                 assertUsable();
                 if (!name)
-                    throw new Error("RPC method requires a non-empty name");
+                    throw new Error(t("RPC method requires a non-empty name"));
                 return own(register("rpc", name, handler, owner, ownerToken, rpcMethods));
             },
             registerContextStrategy(name, strategy) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Context strategy requires a non-empty name");
+                    throw new Error(t("Context strategy requires a non-empty name"));
                 return own(register("context-strategy", name, strategy, owner, ownerToken, contextStrategies));
             },
             registerEntryProjection(projection) {
                 assertUsable();
                 if (!projection?.customType)
-                    throw new Error("Entry projection requires a non-empty customType");
+                    throw new Error(t("Entry projection requires a non-empty customType"));
                 if (typeof projection.project !== "function") {
-                    throw new Error("Entry projection requires a callable project");
+                    throw new Error(t("Entry projection requires a callable project"));
                 }
                 // 转发到宿主 SessionAPI（SessionManager 持有注册表并应用于上下文投影）。
                 // 宿主未支持时显式失败——第三方与第一方看到同一个错误。
                 const register = options.session?.registerEntryProjection;
                 if (register === undefined) {
-                    throw new Error("Entry projections require a host with entry projection support");
+                    throw new Error(t("Entry projections require a host with entry projection support"));
                 }
                 const wrapped = {
                     customType: projection.customType,
@@ -1646,18 +1666,18 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             registerProviderHeaderTransform(name, transform) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Provider header transform requires a non-empty name");
+                    throw new Error(t("Provider header transform requires a non-empty name"));
                 if (typeof transform !== "function") {
-                    throw new Error("Provider header transform requires a callable transform");
+                    throw new Error(t("Provider header transform requires a callable transform"));
                 }
                 return own(register("provider-header-transform", name, transform, owner, ownerToken, providerHeaderTransforms));
             },
             registerStreamFnWrapper(name, wrapper) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Stream function wrapper requires a non-empty name");
+                    throw new Error(t("Stream function wrapper requires a non-empty name"));
                 if (typeof wrapper !== "function") {
-                    throw new Error("Stream function wrapper requires a callable wrapper");
+                    throw new Error(t("Stream function wrapper requires a callable wrapper"));
                 }
                 return own(register("stream-fn-wrapper", name, wrapper, owner, ownerToken, streamFnWrappers));
             },
@@ -1665,49 +1685,49 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 assertUsable();
                 const name = capabilityName(definition, "Skill");
                 if (typeof definition.description !== "string" || !definition.description.trim()) {
-                    throw new Error("Skill definition requires a non-empty description");
+                    throw new Error(t("Skill definition requires a non-empty description"));
                 }
                 if (typeof definition.filePath !== "string" || !definition.filePath) {
-                    throw new Error("Skill definition requires a filePath");
+                    throw new Error(t("Skill definition requires a filePath"));
                 }
                 if (typeof definition.baseDir !== "string" || !definition.baseDir) {
-                    throw new Error("Skill definition requires a baseDir");
+                    throw new Error(t("Skill definition requires a baseDir"));
                 }
                 return own(register("skill", name, definition, owner, ownerToken, skills));
             },
             registerRetryPolicy(name, policy) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Retry policy requires a non-empty name");
+                    throw new Error(t("Retry policy requires a non-empty name"));
                 if (!policy || typeof policy.decide !== "function") {
-                    throw new Error("Retry policy requires a decide function");
+                    throw new Error(t("Retry policy requires a decide function"));
                 }
                 return own(register("retry-policy", name, policy, owner, ownerToken, retryPolicies));
             },
             registerCompactionPolicy(name, policy) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Compaction policy requires a non-empty name");
+                    throw new Error(t("Compaction policy requires a non-empty name"));
                 if (!policy || typeof policy.decide !== "function") {
-                    throw new Error("Compaction policy requires a decide function");
+                    throw new Error(t("Compaction policy requires a decide function"));
                 }
                 return own(register("compaction-policy", name, policy, owner, ownerToken, compactionPolicies));
             },
             registerOverflowPolicy(name, policy) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Overflow policy requires a non-empty name");
+                    throw new Error(t("Overflow policy requires a non-empty name"));
                 if (!policy || typeof policy.decide !== "function") {
-                    throw new Error("Overflow policy requires a decide function");
+                    throw new Error(t("Overflow policy requires a decide function"));
                 }
                 return own(register("overflow-policy", name, policy, owner, ownerToken, overflowPolicies));
             },
             registerBranchSummaryPolicy(name, policy) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Branch summary policy requires a non-empty name");
+                    throw new Error(t("Branch summary policy requires a non-empty name"));
                 if (!policy || typeof policy.summarize !== "function") {
-                    throw new Error("Branch summary policy requires a summarize function");
+                    throw new Error(t("Branch summary policy requires a summarize function"));
                 }
                 return own(register("branch-summary-policy", name, policy, owner, ownerToken, branchSummaryPolicies));
             },
@@ -1722,10 +1742,10 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     "shouldStopAfterTurn",
                 ];
                 if (!positions.includes(position)) {
-                    throw new Error(`Agent loop hook position is invalid: ${String(position)}`);
+                    throw new Error(t("Agent loop hook position is invalid: {value}", { value: String(position) }));
                 }
                 if (typeof handler !== "function") {
-                    throw new Error("Agent loop hook requires a callable handler");
+                    throw new Error(t("Agent loop hook requires a callable handler"));
                 }
                 const entries = loopHooks.get(position) ?? [];
                 loopHooks.set(position, entries);
@@ -1746,16 +1766,16 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             registerRunLoopStrategy(name, strategy) {
                 assertUsable();
                 if (!name)
-                    throw new Error("Run loop strategy requires a non-empty name");
+                    throw new Error(t("Run loop strategy requires a non-empty name"));
                 if (!strategy || typeof strategy.decideNextCycle !== "function") {
-                    throw new Error("Run loop strategy requires a decideNextCycle function");
+                    throw new Error(t("Run loop strategy requires a decideNextCycle function"));
                 }
                 return own(register("run-loop-strategy", name, strategy, owner, ownerToken, runLoopStrategies));
             },
             subscribe(type, handler) {
                 assertUsable();
                 if (!type)
-                    throw new Error("Event type requires a non-empty name");
+                    throw new Error(t("Event type requires a non-empty name"));
                 const handlers = subscribers.get(type) ?? new Map();
                 subscribers.set(type, handlers);
                 const sequence = ++subscriptionSequence;
@@ -1810,7 +1830,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 assertUsable();
                 const registered = operations.get(operation);
                 if (!registered)
-                    throw new Error(`Operation is not registered: ${operation}`);
+                    throw new Error(t("Operation is not registered: {operation}", { operation }));
                 assertRegisteredCapabilityActive(registered);
                 const sequence = ++operationSequence;
                 const id = createRuntimeId("operation", sequence, `operation:${owner}:${operation}:${sequence}`);
@@ -1887,7 +1907,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     const result = registration.dispose();
                     if (result && typeof result.then === "function") {
                         observeUnexpectedAsyncCleanup(result, id);
-                        throw new Error(`Capability plugin ${id} has asynchronous cleanup; use the async loader`);
+                        throw new Error(t("Capability plugin {id} has asynchronous cleanup; use the async loader", { id }));
                     }
                 }
                 catch (error) {
@@ -1998,25 +2018,25 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         async classifyRetry(name, request) {
             const policy = retryPolicies.get(name);
             if (!policy)
-                throw new Error(`Retry policy is not registered: ${name}`);
+                throw new Error(t("Retry policy is not registered: {name}", { name }));
             if (!policy.value.classify)
-                throw new Error(`Retry policy does not support classification: ${name}`);
+                throw new Error(t("Retry policy does not support classification: {name}", { name }));
             const retryable = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.classify?.(request));
             if (typeof retryable !== "boolean") {
-                throw new Error(`Retry policy returned an invalid classification: ${name}`);
+                throw new Error(t("Retry policy returned an invalid classification: {name}", { name }));
             }
             return retryable;
         },
         async decideRetry(name, request) {
             const policy = retryPolicies.get(name);
             if (!policy)
-                throw new Error(`Retry policy is not registered: ${name}`);
+                throw new Error(t("Retry policy is not registered: {name}", { name }));
             const decision = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.decide(request));
             if (!decision || typeof decision.retry !== "boolean") {
-                throw new Error(`Retry policy returned an invalid decision: ${name}`);
+                throw new Error(t("Retry policy returned an invalid decision: {name}", { name }));
             }
             if (decision.delayMs !== undefined && (!Number.isFinite(decision.delayMs) || decision.delayMs < 0)) {
-                throw new Error(`Retry policy returned an invalid delayMs: ${name}`);
+                throw new Error(t("Retry policy returned an invalid delayMs: {name}", { name }));
             }
             return decision;
         },
@@ -2024,19 +2044,19 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         async prepareCompaction(name, request) {
             const policy = compactionPolicies.get(name);
             if (!policy)
-                throw new Error(`Compaction policy is not registered: ${name}`);
+                throw new Error(t("Compaction policy is not registered: {name}", { name }));
             if (!policy.value.prepare)
-                throw new Error(`Compaction policy does not support preparation: ${name}`);
+                throw new Error(t("Compaction policy does not support preparation: {name}", { name }));
             return invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.prepare?.(request));
         },
         hasBranchSummaryPolicy: (name) => branchSummaryPolicies.has(name),
         async summarizeBranch(name, request) {
             const policy = branchSummaryPolicies.get(name);
             if (!policy)
-                throw new Error(`Branch summary policy is not registered: ${name}`);
+                throw new Error(t("Branch summary policy is not registered: {name}", { name }));
             const result = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.summarize(request));
             if (!result || typeof result !== "object") {
-                throw new Error(`Branch summary policy returned an invalid result: ${name}`);
+                throw new Error(t("Branch summary policy returned an invalid result: {name}", { name }));
             }
             return result;
         },
@@ -2052,42 +2072,42 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         async decideRunLoop(name, request) {
             const strategy = runLoopStrategies.get(name);
             if (!strategy)
-                throw new Error(`Run loop strategy is not registered: ${name}`);
+                throw new Error(t("Run loop strategy is not registered: {name}", { name }));
             const decision = await invokeRegisteredCapabilityWithSignal(strategy, request.signal, (value) => value.decideNextCycle(request));
             if (!decision || typeof decision.continueLoop !== "boolean") {
-                throw new Error(`Run loop strategy returned an invalid decision: ${name}`);
+                throw new Error(t("Run loop strategy returned an invalid decision: {name}", { name }));
             }
             return decision;
         },
         async decideCompaction(name, request) {
             const policy = compactionPolicies.get(name);
             if (!policy)
-                throw new Error(`Compaction policy is not registered: ${name}`);
+                throw new Error(t("Compaction policy is not registered: {name}", { name }));
             const decision = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.decide(request));
             if (!decision || typeof decision.compact !== "boolean") {
-                throw new Error(`Compaction policy returned an invalid decision: ${name}`);
+                throw new Error(t("Compaction policy returned an invalid decision: {name}", { name }));
             }
             if (decision.retry !== undefined && typeof decision.retry !== "boolean") {
-                throw new Error(`Compaction policy returned an invalid retry value: ${name}`);
+                throw new Error(t("Compaction policy returned an invalid retry value: {name}", { name }));
             }
             if (decision.failureMessage !== undefined && typeof decision.failureMessage !== "string") {
-                throw new Error(`Compaction policy returned an invalid failureMessage: ${name}`);
+                throw new Error(t("Compaction policy returned an invalid failureMessage: {name}", { name }));
             }
             return decision;
         },
         async summarizeCompaction(name, request) {
             const policy = compactionPolicies.get(name);
             if (!policy)
-                throw new Error(`Compaction policy is not registered: ${name}`);
+                throw new Error(t("Compaction policy is not registered: {name}", { name }));
             if (!policy.value.summarize)
-                throw new Error(`Compaction policy does not support summaries: ${name}`);
+                throw new Error(t("Compaction policy does not support summaries: {name}", { name }));
             const result = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.summarize?.(request));
             if (!result ||
                 typeof result.summary !== "string" ||
                 !result.summary ||
                 typeof result.firstKeptEntryId !== "string" ||
                 !Number.isFinite(result.tokensBefore)) {
-                throw new Error(`Compaction policy returned an invalid summary: ${name}`);
+                throw new Error(t("Compaction policy returned an invalid summary: {name}", { name }));
             }
             return result;
         },
@@ -2095,19 +2115,19 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         async decideOverflow(name, request) {
             const policy = overflowPolicies.get(name);
             if (!policy)
-                throw new Error(`Overflow policy is not registered: ${name}`);
+                throw new Error(t("Overflow policy is not registered: {name}", { name }));
             const decision = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.decide(request));
             if (!decision ||
                 typeof decision.contextOverflow !== "boolean" ||
                 typeof decision.recoverableLength !== "boolean") {
-                throw new Error(`Overflow policy returned an invalid decision: ${name}`);
+                throw new Error(t("Overflow policy returned an invalid decision: {name}", { name }));
             }
             return decision;
         },
         async invokeTool(name, input, options) {
             const registered = tools.get(name);
             if (!registered)
-                throw new Error(`Tool is not registered: ${name}`);
+                throw new Error(t("Tool is not registered: {name}", { name }));
             return invokeRegisteredCapability(registered, (value) => invokeCapabilityTool(asHandler(value, "Tool"), input, toolExecutionContext, options?.signal));
         },
         // 中断分级读面（设计 §4.2，2026-10-02）：活任务集合的有界投影。已终态
@@ -2134,45 +2154,45 @@ export function createCapabilityRuntime(inputHost, options = {}) {
         async invokeCommand(name, args, options) {
             const registered = commands.get(name);
             if (!registered)
-                throw new Error(`Command is not registered: ${name}`);
+                throw new Error(t("Command is not registered: {name}", { name }));
             return validateCommandResult(await invokeRegisteredCapability(registered, (value) => value.execute(args, options ?? { signal: new AbortController().signal })), name);
         },
         hasRpcMethod: (name) => rpcMethods.has(name),
         async dispatchRpc(name, input) {
             const registered = rpcMethods.get(name);
             if (!registered)
-                throw new Error(`RPC method is not registered: ${name}`);
+                throw new Error(t("RPC method is not registered: {name}", { name }));
             return invokeRegisteredCapability(registered, (value) => value(input));
         },
         hasContextStrategy: (name) => contextStrategies.has(name),
         async transformContext(name, context, options) {
             const strategy = contextStrategies.get(name);
             if (!strategy)
-                throw new Error(`Context strategy is not registered: ${name}`);
+                throw new Error(t("Context strategy is not registered: {name}", { name }));
             return invokeRegisteredCapability(strategy, (value) => value.transform(context, options));
         },
         async snapshotContext(name, context, options) {
             const registered = contextStrategies.get(name);
             if (!registered)
-                throw new Error(`Context strategy is not registered: ${name}`);
+                throw new Error(t("Context strategy is not registered: {name}", { name }));
             if (!registered.value.snapshot)
-                throw new Error(`Context strategy does not support snapshots: ${name}`);
+                throw new Error(t("Context strategy does not support snapshots: {name}", { name }));
             return invokeRegisteredCapability(registered, (value) => value.snapshot?.(context, options));
         },
         async restoreContext(name, snapshot, options) {
             const registered = contextStrategies.get(name);
             if (!registered)
-                throw new Error(`Context strategy is not registered: ${name}`);
+                throw new Error(t("Context strategy is not registered: {name}", { name }));
             if (!registered.value.restore)
-                throw new Error(`Context strategy does not support restore: ${name}`);
+                throw new Error(t("Context strategy does not support restore: {name}", { name }));
             return invokeRegisteredCapability(registered, (value) => value.restore?.(snapshot, options));
         },
         async replaceContext(name, context, options) {
             const registered = contextStrategies.get(name);
             if (!registered)
-                throw new Error(`Context strategy is not registered: ${name}`);
+                throw new Error(t("Context strategy is not registered: {name}", { name }));
             if (!registered.value.replace)
-                throw new Error(`Context strategy does not support replacement: ${name}`);
+                throw new Error(t("Context strategy does not support replacement: {name}", { name }));
             return invokeRegisteredCapability(registered, (value) => value.replace?.(context, options));
         },
         async transformProviderHeaders(request) {