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

package/dist/core/extensions/agent-composition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-composition.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/agent-composition.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n\tAgentCompositionAPI,\n\tAgentCompositionDefinitionBinding,\n\tAgentCompositionHostBinding,\n\tAgentCompositionScopedHostBinding,\n\tAgentContextCommitRequestV1,\n\tAgentContextCommitResultV1,\n\tAgentContextFacadeV1,\n\tAgentControllerLease,\n\tAgentDefinition,\n\tAgentExecutionContext,\n\tAgentHostPrimitivesFactory,\n\tAgentHostPrimitivesV1,\n\tAgentInstance,\n\tAgentInstanceResult,\n\tAgentInstanceSnapshot,\n\tAgentInstanceStatus,\n\tAgentModelFacadeV1,\n\tAgentModelInvocationV1,\n\tAgentOperationFacadeV1,\n\tAgentSessionFacadeV1,\n\tAgentToolFacadeV1,\n\tDisposableRegistration,\n\tOperationHandle,\n\tOperationProgress,\n\tOperationStatus,\n\tOutputArtifactAPI,\n\tOutputArtifactChunk,\n\tOutputArtifactRef,\n\tStateAPI,\n\tStateChange,\n} from \"./public-api.ts\";\n\nexport interface AgentCompositionRuntimeOptions {\n\tidFactory?: (kind: string) => string;\n\tdefaultLeaseOwner?: string;\n\thostPrimitivesFactory?: AgentHostPrimitivesFactory;\n}\n\nexport type AgentCompositionLifecycleEventName = \"start\" | \"step\" | \"cancel\" | \"end\";\nexport type AgentCompositionLifecycleTerminalStatus = \"succeeded\" | \"failed\" | \"cancelled\";\n\nexport interface AgentCompositionLifecycleEvent {\n\treadonly event: AgentCompositionLifecycleEventName;\n\treadonly operationId: string;\n\treadonly operationKind: string;\n\treadonly owner?: string;\n\treadonly status?: AgentCompositionLifecycleTerminalStatus;\n\treadonly step?: number;\n\treadonly progress?: OperationProgress;\n}\n\nexport type AgentCompositionLifecycleDispatcher = (event: AgentCompositionLifecycleEvent) => void;\n\n/** Host-only binding used by CapabilityRuntime to observe composition operations. */\nexport interface AgentCompositionLifecycleBinding {\n\tsetLifecycleDispatcher(dispatcher?: AgentCompositionLifecycleDispatcher): void;\n}\n\n/**\n * Host-only binding used by CapabilityRuntime to clear instance-scoped state\n * when an instance is disposed. Instance ids are unique per composition\n * runtime, so every registered clearer is invoked on each disposal and\n * resolves by id whether the disposed instance belongs to it.\n */\nexport interface AgentCompositionInstanceStateBinding {\n\t/** Registers a clearer invoked after a disposed instance's execution drained. Returns an unsubscribe function. */\n\taddInstanceStateClearer(clearer: (instanceId: string) => void): () => void;\n}\n\ntype DefinitionRef = { id: string; version: number };\n\nconst terminalStatuses = new Set<AgentInstanceStatus>([\"succeeded\", \"failed\", \"cancelled\", \"disposed\"]);\n\nfunction abortError(reason?: unknown): Error {\n\tif (reason instanceof Error) return reason;\n\tconst error = new Error(reason === undefined ? \"Agent operation cancelled\" : String(reason));\n\terror.name = \"AbortError\";\n\treturn error;\n}\n\nfunction combinedAbortSignal(...signals: readonly (AbortSignal | undefined)[]): {\n\tsignal: AbortSignal;\n\tdispose(): void;\n} {\n\tconst controller = new AbortController();\n\tconst listeners: Array<{ signal: AbortSignal; listener: () => void }> = [];\n\tfor (const signal of new Set(signals.filter((signal): signal is AbortSignal => signal !== undefined))) {\n\t\tconst abort = () => {\n\t\t\tif (!controller.signal.aborted) controller.abort(signal.reason);\n\t\t};\n\t\tif (signal.aborted) {\n\t\t\tabort();\n\t\t\tbreak;\n\t\t}\n\t\tsignal.addEventListener(\"abort\", abort, { once: true });\n\t\tlisteners.push({ signal, listener: abort });\n\t}\n\treturn {\n\t\tsignal: controller.signal,\n\t\tdispose: () => {\n\t\t\tfor (const { signal, listener } of listeners) signal.removeEventListener(\"abort\", listener);\n\t\t},\n\t};\n}\n\nfunction freezeSnapshot(snapshot: AgentInstanceSnapshot): AgentInstanceSnapshot {\n\treturn Object.freeze({ ...snapshot });\n}\n\nfunction validateAgentDefinition<TInput, TResult>(\n\tdefinition: AgentDefinition<TInput, TResult>,\n): AgentDefinition<TInput, TResult> {\n\tif (!definition || typeof definition !== \"object\") {\n\t\tthrow new Error(\"Agent definition is required\");\n\t}\n\tif (typeof definition.id !== \"string\" || !definition.id.trim()) {\n\t\tthrow new Error(\"Agent definition requires a non-empty id\");\n\t}\n\tif (!Number.isSafeInteger(definition.version) || definition.version < 1) {\n\t\tthrow new Error(\"Agent definition version must be a positive safe integer\");\n\t}\n\tif (definition.role !== \"root-agent-controller\" && definition.role !== \"child-agent-controller\") {\n\t\tthrow new Error(\"Agent definition role must be root-agent-controller or child-agent-controller\");\n\t}\n\tif (typeof definition.run !== \"function\") {\n\t\tthrow new Error(\"Agent definition requires a run function\");\n\t}\n\tif (definition.owner !== undefined && (typeof definition.owner !== \"string\" || !definition.owner.trim())) {\n\t\tthrow new Error(\"Agent definition owner must be a non-empty string when provided\");\n\t}\n\treturn definition;\n}\n\nfunction detachedFreeze<T>(value: T, seen = new WeakMap<object, unknown>()): T {\n\tif (value === null || typeof value !== \"object\") return value;\n\tif (value instanceof Uint8Array) return new Uint8Array(value) as T;\n\tconst existing = seen.get(value);\n\tif (existing) return existing as T;\n\tconst result: Record<string, unknown> | unknown[] = Array.isArray(value) ? [] : {};\n\tseen.set(value, result);\n\tfor (const [key, item] of Object.entries(value as Record<string, unknown>)) {\n\t\t(result as Record<string, unknown>)[key] = detachedFreeze(item, seen);\n\t}\n\treturn Object.freeze(result) as T;\n}\n\nfunction disposable(dispose: () => void | Promise<void>): DisposableRegistration {\n\tlet disposed = false;\n\treturn {\n\t\tid: \"agent-host-registration\",\n\t\tkind: \"agent-host\",\n\t\tdispose: () => {\n\t\t\tif (disposed) return;\n\t\t\tdisposed = true;\n\t\t\treturn dispose();\n\t\t},\n\t};\n}\n\nfunction revokedError(instanceId: string): Error {\n\treturn new Error(`Agent host primitives are revoked: ${instanceId}`);\n}\n\ninterface RevocableHost {\n\treadonly value: AgentHostPrimitivesV1;\n\trevoke(): void;\n}\n\nfunction createOperationFacade<TResult>(\n\toperation: OperationRuntime<TResult>,\n\tinstanceId: string,\n\tactive: () => boolean,\n): AgentOperationFacadeV1 {\n\treturn Object.freeze({\n\t\tversion: 1 as const,\n\t\tid: operation.id,\n\t\tsignal: operation.signal,\n\t\tstatus: () => {\n\t\t\tif (!active()) return \"cancelled\" as OperationStatus;\n\t\t\treturn operation.status();\n\t\t},\n\t\tisActive: () => active() && operation.status() === \"running\",\n\t\treportProgress: (progress: OperationProgress) => active() && operation.reportProgress(progress),\n\t\tonCancel: (handler: (reason: unknown) => void | Promise<void>) => {\n\t\t\tif (!active()) throw revokedError(instanceId);\n\t\t\tconst listener = () => {\n\t\t\t\tvoid handler(operation.signal.reason);\n\t\t\t};\n\t\t\toperation.signal.addEventListener(\"abort\", listener, { once: true });\n\t\t\treturn disposable(() => operation.signal.removeEventListener(\"abort\", listener));\n\t\t},\n\t\tcancel: async (reason?: string) => {\n\t\t\tif (!active()) throw revokedError(instanceId);\n\t\t\tawait operation.cancel(reason);\n\t\t},\n\t});\n}\n\nfunction createRevocableHostPrimitives(\n\traw: AgentHostPrimitivesV1,\n\toperation: OperationRuntime<unknown>,\n\tinstance: AgentInstanceSnapshot,\n): RevocableHost {\n\tlet active = true;\n\tconst cleanups: Array<() => void | Promise<void>> = [];\n\tconst track = (registration: DisposableRegistration): DisposableRegistration => {\n\t\tlet released = false;\n\t\tconst dispose = async () => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tconst index = cleanups.indexOf(cleanup);\n\t\t\tif (index >= 0) cleanups.splice(index, 1);\n\t\t\tawait registration.dispose();\n\t\t};\n\t\tconst cleanup = dispose;\n\t\tcleanups.push(cleanup);\n\t\treturn {\n\t\t\tid: registration.id,\n\t\t\tkind: registration.kind,\n\t\t\tdispose,\n\t\t};\n\t};\n\tconst assertActive = () => {\n\t\tif (!active) throw revokedError(instance.id);\n\t\tif (operation.signal.aborted) throw abortError(operation.signal.reason);\n\t};\n\n\tconst session = raw.session\n\t\t? (Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\tgetSessionId: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.session!.getSessionId();\n\t\t\t\t},\n\t\t\t\tgetRevision: raw.session.getRevision\n\t\t\t\t\t? () => {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn detachedFreeze(raw.session!.getRevision!());\n\t\t\t\t\t\t}\n\t\t\t\t\t: undefined,\n\t\t\t\tgetMessages: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(raw.session!.getMessages());\n\t\t\t\t},\n\t\t\t\tgetBranchEntries: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(raw.session!.getBranchEntries());\n\t\t\t\t},\n\t\t\t\tisIdle: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.session!.isIdle();\n\t\t\t\t},\n\t\t\t\twaitForIdle: async () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tawait raw.session!.waitForIdle();\n\t\t\t\t\tassertActive();\n\t\t\t\t},\n\t\t\t\tappendEntry: (customType: string, data?: unknown) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.session!.appendEntry(customType, detachedFreeze(data));\n\t\t\t\t},\n\t\t\t}) as AgentSessionFacadeV1)\n\t\t: undefined;\n\n\tconst context = raw.context\n\t\t? (Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\tget: <TValue = unknown>() => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(raw.context!.get<TValue>());\n\t\t\t\t},\n\t\t\t\tcommit: async <TValue = unknown>(request: AgentContextCommitRequestV1<TValue>) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tif (request.signal?.aborted) throw abortError(request.signal.reason);\n\t\t\t\t\tconst result = await raw.context!.commit({\n\t\t\t\t\t\t...request,\n\t\t\t\t\t\tvalue: detachedFreeze(request.value),\n\t\t\t\t\t});\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(result) as AgentContextCommitResultV1<TValue>;\n\t\t\t\t},\n\t\t\t}) as AgentContextFacadeV1)\n\t\t: undefined;\n\n\t// One guarded StateAPI facade shared by the owner namespace and the\n\t// instance-private namespace: same revocation gating and detached snapshots.\n\tconst guardedStateFacade = (source: StateAPI): StateAPI =>\n\t\tObject.freeze({\n\t\t\tget: (key: string) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn detachedFreeze(source.get(key));\n\t\t\t},\n\t\t\tset: (key: string, value: Parameters<StateAPI[\"set\"]>[1], options?: Parameters<StateAPI[\"set\"]>[2]) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn source.set(key, detachedFreeze(value), options);\n\t\t\t},\n\t\t\tdelete: (key: string, options?: Parameters<StateAPI[\"delete\"]>[1]) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn source.delete(key, options);\n\t\t\t},\n\t\t\tlist: (prefix?: string) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn detachedFreeze(source.list(prefix));\n\t\t\t},\n\t\t\twatch: (prefix: string | undefined, handler: (change: StateChange) => void | Promise<void>) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn track(\n\t\t\t\t\tsource.watch(prefix, (change: StateChange) => {\n\t\t\t\t\t\tif (!active || operation.signal.aborted) return;\n\t\t\t\t\t\tvoid handler(detachedFreeze(change));\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t},\n\t\t}) as StateAPI;\n\n\tconst state = raw.state ? guardedStateFacade(raw.state) : undefined;\n\tconst instanceState = raw.instanceState ? guardedStateFacade(raw.instanceState) : undefined;\n\n\tconst artifact = raw.artifact\n\t\t? (Object.freeze({\n\t\t\t\tput: async (\n\t\t\t\t\tinput: Parameters<OutputArtifactAPI[\"put\"]>[0],\n\t\t\t\t\toptions?: Parameters<OutputArtifactAPI[\"put\"]>[1],\n\t\t\t\t) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tconst data = input.data instanceof Uint8Array ? new Uint8Array(input.data) : input.data;\n\t\t\t\t\tconst abort = combinedAbortSignal(operation.signal, options?.signal);\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst ref = await raw.artifact!.put({ ...input, data }, { ...options, signal: abort.signal });\n\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\treturn detachedFreeze(ref) as OutputArtifactRef;\n\t\t\t\t\t} finally {\n\t\t\t\t\t\tabort.dispose();\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\tstat: async (ref: OutputArtifactRef) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tconst result = await raw.artifact!.stat(detachedFreeze(ref));\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(result);\n\t\t\t\t},\n\t\t\t\tread: async (ref: OutputArtifactRef, options?: Parameters<OutputArtifactAPI[\"read\"]>[1]) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tconst chunk = await raw.artifact!.read(detachedFreeze(ref), options);\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze({\n\t\t\t\t\t\t...chunk,\n\t\t\t\t\t\tdata: new Uint8Array(chunk.data),\n\t\t\t\t\t}) as OutputArtifactChunk;\n\t\t\t\t},\n\t\t\t}) as OutputArtifactAPI)\n\t\t: undefined;\n\n\tconst operationFacade = raw.operation\n\t\t? Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\tid: raw.operation.id,\n\t\t\t\tsignal: raw.operation.signal,\n\t\t\t\tstatus: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.operation!.status();\n\t\t\t\t},\n\t\t\t\tisActive: () => active && raw.operation!.isActive(),\n\t\t\t\treportProgress: (progress: OperationProgress) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.operation!.reportProgress(progress);\n\t\t\t\t},\n\t\t\t\tonCancel: (handler: (reason: unknown) => void | Promise<void>) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn track(raw.operation!.onCancel(handler));\n\t\t\t\t},\n\t\t\t\tcancel: async (reason?: string) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tawait raw.operation!.cancel(reason);\n\t\t\t\t},\n\t\t\t})\n\t\t: createOperationFacade(operation, instance.id, () => active);\n\n\tconst value = Object.freeze({\n\t\tversion: 1 as const,\n\t\t...(session ? { session } : {}),\n\t\t...(context ? { context } : {}),\n\t\t...(state ? { state } : {}),\n\t\t...(instanceState ? { instanceState } : {}),\n\t\t...(artifact ? { artifact } : {}),\n\t\t...(operationFacade ? { operation: operationFacade } : {}),\n\t\t...(raw.model\n\t\t\t? {\n\t\t\t\t\tmodel: Object.freeze({\n\t\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\t\tget facts() {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn raw.model!.facts;\n\t\t\t\t\t\t},\n\t\t\t\t\t\tinvocation: {\n\t\t\t\t\t\t\tinvoke: async (input: Parameters<AgentModelInvocationV1[\"invoke\"]>[0], signal: AbortSignal) => {\n\t\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\t\tconst result = await raw.model!.invocation.invoke(input, signal);\n\t\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\t\treturn result;\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t}) satisfies AgentModelFacadeV1,\n\t\t\t\t}\n\t\t\t: {}),\n\t\t...(raw.tool\n\t\t\t? {\n\t\t\t\t\ttool: Object.freeze({\n\t\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\t\tlistTools: () => {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn raw.tool!.listTools();\n\t\t\t\t\t\t},\n\t\t\t\t\t\tinvokeTool: (name: string, input: unknown, invokeOptions?: { readonly signal?: AbortSignal }) => {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn raw.tool!.invokeTool(name, input, invokeOptions);\n\t\t\t\t\t\t},\n\t\t\t\t\t}) satisfies AgentToolFacadeV1,\n\t\t\t\t}\n\t\t\t: {}),\n\t});\n\treturn {\n\t\tvalue,\n\t\trevoke: () => {\n\t\t\tif (!active) return;\n\t\t\tactive = false;\n\t\t\tfor (const cleanup of [...cleanups]) void cleanup();\n\t\t},\n\t};\n}\n\nclass AgentInstanceRuntime<TInput, TResult> implements AgentInstance<TInput, TResult> {\n\treadonly id: string;\n\treadonly definition: AgentDefinition<TInput, TResult>;\n\n\tprivate statusValue: AgentInstanceStatus = \"created\";\n\tprivate revisionValue = 0;\n\tprivate activeLease?: ControllerLeaseRuntime;\n\tprivate activeOperation?: OperationRuntime<TResult>;\n\tprivate activeExecution?: Promise<void>;\n\tprivate completion: Promise<AgentInstanceResult<TResult>>;\n\tprivate resolveCompletion!: (result: AgentInstanceResult<TResult>) => void;\n\tprivate completionResolved = false;\n\tprivate readonly parentInstanceId: string | undefined;\n\tprivate readonly nextId: (kind: string) => string;\n\tprivate readonly defaultLeaseOwner: string;\n\tprivate readonly hostPrimitivesFactory?: AgentHostPrimitivesFactory;\n\tprivate readonly lifecycleDispatcher?: AgentCompositionLifecycleDispatcher;\n\tprivate readonly clearInstanceState?: (instanceId: string) => void;\n\n\tconstructor(\n\t\tdefinition: AgentDefinition<TInput, TResult>,\n\t\tid: string,\n\t\tparentInstanceId: string | undefined,\n\t\tnextId: (kind: string) => string,\n\t\tdefaultLeaseOwner: string,\n\t\thostPrimitivesFactory: AgentHostPrimitivesFactory | undefined,\n\t\tlifecycleDispatcher: AgentCompositionLifecycleDispatcher | undefined,\n\t\tclearInstanceState: ((instanceId: string) => void) | undefined,\n\t) {\n\t\tthis.id = id;\n\t\tthis.definition = definition;\n\t\tthis.parentInstanceId = parentInstanceId;\n\t\tthis.nextId = nextId;\n\t\tthis.defaultLeaseOwner = defaultLeaseOwner;\n\t\tthis.hostPrimitivesFactory = hostPrimitivesFactory;\n\t\tthis.lifecycleDispatcher = lifecycleDispatcher;\n\t\tthis.clearInstanceState = clearInstanceState;\n\t\tthis.completion = new Promise<AgentInstanceResult<TResult>>((resolve) => {\n\t\t\tthis.resolveCompletion = resolve;\n\t\t});\n\t}\n\n\tsnapshot(): AgentInstanceSnapshot {\n\t\treturn freezeSnapshot({\n\t\t\tid: this.id,\n\t\t\tdefinitionId: this.definition.id,\n\t\t\tdefinitionVersion: this.definition.version,\n\t\t\trole: this.definition.role,\n\t\t\t...(this.parentInstanceId ? { parentInstanceId: this.parentInstanceId } : {}),\n\t\t\tstatus: this.statusValue,\n\t\t\trevision: this.revisionValue,\n\t\t\t...(this.activeLease?.isActive() ? { leaseOwner: this.activeLease.owner } : {}),\n\t\t});\n\t}\n\n\tasync acquireControllerLease(\n\t\towner = this.definition.owner ?? this.defaultLeaseOwner,\n\t): Promise<AgentControllerLease> {\n\t\tthis.assertNotDisposed();\n\t\tif (this.activeLease?.isActive())\n\t\t\tthrow new Error(`Agent instance already has an active controller lease: ${this.id}`);\n\t\tconst lease = new ControllerLeaseRuntime(this, this.nextId(\"agent-lease\"), owner, this.revisionValue + 1);\n\t\tthis.activeLease = lease;\n\t\treturn lease;\n\t}\n\n\trun(input: TInput, options: { lease?: AgentControllerLease; signal?: AbortSignal } = {}): OperationHandle<TResult> {\n\t\tthis.assertNotDisposed();\n\t\tif (this.statusValue !== \"created\")\n\t\t\tthrow new Error(`Agent instance cannot run from status ${this.statusValue}: ${this.id}`);\n\t\tconst lease = this.activeLease;\n\t\tif (!lease?.isActive()) throw new Error(`Agent instance requires an active controller lease: ${this.id}`);\n\t\tif (options.lease !== lease || !this.isLeaseUsable(options.lease)) {\n\t\t\tthrow new Error(`Agent controller lease is not valid for instance: ${this.id}`);\n\t\t}\n\n\t\tthis.statusValue = \"running\";\n\t\tconst controller = new AbortController();\n\t\tconst externalSignal = options.signal;\n\t\tlet externalAbortListener: (() => void) | undefined;\n\t\tif (externalSignal) {\n\t\t\texternalAbortListener = () => {\n\t\t\t\tcontroller.abort(externalSignal.reason);\n\t\t\t\tvoid this.cancel(externalSignal.reason === undefined ? undefined : String(externalSignal.reason));\n\t\t\t};\n\t\t\tif (!externalSignal.aborted) externalSignal.addEventListener(\"abort\", externalAbortListener, { once: true });\n\t\t}\n\n\t\tlet operation!: OperationRuntime<TResult>;\n\t\toperation = new OperationRuntime<TResult>(\n\t\t\tthis.nextId(\"agent-operation\"),\n\t\t\tcontroller,\n\t\t\t() => this.cancel(controller.signal.reason),\n\t\t\t(progress, step) => this.reportLifecycle(\"step\", operation, undefined, progress, step),\n\t\t);\n\t\tthis.activeOperation = operation;\n\t\tif (externalSignal?.aborted) {\n\t\t\tcontroller.abort(externalSignal.reason);\n\t\t} else {\n\t\t\tthis.reportLifecycle(\"start\", operation);\n\t\t}\n\t\tthis.activeExecution = this.execute(input, lease, operation, externalSignal, externalAbortListener);\n\t\tif (externalSignal?.aborted) {\n\t\t\t// Trigger cancellation only after the execution is tracked, so the\n\t\t\t// pre-aborted path drains like every other cancellation path instead\n\t\t\t// of resolving completion ahead of the execution body.\n\t\t\tvoid this.cancel(externalSignal.reason === undefined ? undefined : String(externalSignal.reason));\n\t\t}\n\t\treturn operation;\n\t}\n\n\tasync wait(): Promise<AgentInstanceResult<TResult>> {\n\t\treturn this.completion;\n\t}\n\n\tasync cancel(reason?: string): Promise<void> {\n\t\tif (this.statusValue === \"disposed\" || terminalStatuses.has(this.statusValue)) return;\n\t\tthis.statusValue = \"cancelled\";\n\t\tthis.revisionValue += 1;\n\t\tconst operation = this.activeOperation;\n\t\tif (operation) {\n\t\t\tthis.reportLifecycle(\"cancel\", operation);\n\t\t\tthis.reportLifecycle(\"end\", operation, \"cancelled\");\n\t\t\toperation.cancelFromInstance(reason);\n\t\t}\n\t\t// The run body must eventually observe the abort signal: cancellation only\n\t\t// settles after the execution drained, so wait() and lease disposal never\n\t\t// race side effects still in flight. There is deliberately no timeout. A run\n\t\t// body that awaits this cancel(), dispose(), or its own lease release\n\t\t// self-deadlocks by contract.\n\t\tawait this.drainExecution();\n\t\tthis.resolveCompletionOnce({ status: \"cancelled\", revision: this.revisionValue, error: abortError(reason) });\n\t}\n\n\tasync dispose(): Promise<void> {\n\t\tif (this.statusValue === \"disposed\") return;\n\t\tif (this.statusValue === \"created\") {\n\t\t\tawait this.activeLease?.release();\n\t\t\tthis.statusValue = \"disposed\";\n\t\t\tthis.revisionValue += 1;\n\t\t\tthis.clearInstanceState?.(this.id);\n\t\t\tthis.resolveCompletionOnce({ status: \"disposed\", revision: this.revisionValue });\n\t\t\treturn;\n\t\t}\n\t\tif (!terminalStatuses.has(this.statusValue)) await this.cancel(\"Agent instance disposed\");\n\t\t// A concurrent cancel() may still be draining; release the lease only after\n\t\t// the execution has settled.\n\t\tawait this.drainExecution();\n\t\tawait this.activeLease?.release();\n\t\tthis.statusValue = \"disposed\";\n\t\tthis.revisionValue += 1;\n\t\t// The instance-private state namespace (and its watchers) dies with the\n\t\t// instance, after every drain the run body could still rely on.\n\t\tthis.clearInstanceState?.(this.id);\n\t\tthis.resolveCompletionOnce({ status: \"disposed\", revision: this.revisionValue });\n\t}\n\n\tasync deactivateLease(lease: ControllerLeaseRuntime): Promise<void> {\n\t\tif (this.activeLease !== lease) return;\n\t\tthis.activeLease = undefined;\n\t\tif (this.statusValue === \"running\") {\n\t\t\tawait this.cancel(\"Controller lease released\");\n\t\t\treturn;\n\t\t}\n\t\t// A cancel() from another path may still be draining the execution.\n\t\tawait this.drainExecution();\n\t}\n\n\tisLeaseUsable(lease: AgentControllerLease | undefined): lease is ControllerLeaseRuntime {\n\t\treturn (\n\t\t\tlease instanceof ControllerLeaseRuntime &&\n\t\t\tlease.instanceId === this.id &&\n\t\t\tlease.isActive() &&\n\t\t\tthis.activeLease === lease\n\t\t);\n\t}\n\n\tprivate async execute(\n\t\tinput: TInput,\n\t\tlease: ControllerLeaseRuntime,\n\t\toperation: OperationRuntime<TResult>,\n\t\texternalSignal: AbortSignal | undefined,\n\t\texternalAbortListener: (() => void) | undefined,\n\t): Promise<void> {\n\t\tconst instanceSnapshot = this.snapshot();\n\t\tlet hostScope: RevocableHost | undefined;\n\t\tconst revokeHost = () => hostScope?.revoke();\n\t\toperation.signal.addEventListener(\"abort\", revokeHost, { once: true });\n\t\ttry {\n\t\t\tif (operation.signal.aborted) throw abortError(operation.signal.reason);\n\t\t\tif (this.hostPrimitivesFactory) {\n\t\t\t\tconst raw = await this.hostPrimitivesFactory({\n\t\t\t\t\tinstance: instanceSnapshot,\n\t\t\t\t\toperationId: operation.id,\n\t\t\t\t\tsignal: operation.signal,\n\t\t\t\t\tleaseOwner: lease.owner,\n\t\t\t\t});\n\t\t\t\tif (raw !== undefined) {\n\t\t\t\t\tif (raw.version !== 1) throw new Error(\"Unsupported Agent host primitives version\");\n\t\t\t\t\tif (raw.operation && (raw.operation.id !== operation.id || raw.operation.signal !== operation.signal))\n\t\t\t\t\t\tthrow new Error(`Agent host operation does not match active operation: ${operation.id}`);\n\t\t\t\t\thostScope = createRevocableHostPrimitives(\n\t\t\t\t\t\t{ ...raw, operation: raw.operation ?? createOperationFacade(operation, this.id, () => true) },\n\t\t\t\t\t\toperation as OperationRuntime<unknown>,\n\t\t\t\t\t\tinstanceSnapshot,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (operation.signal.aborted) throw abortError(operation.signal.reason);\n\t\t\tconst context: AgentExecutionContext = Object.freeze({\n\t\t\t\tinstance: instanceSnapshot,\n\t\t\t\tsignal: operation.signal,\n\t\t\t\tinputRevision: this.revisionValue,\n\t\t\t\t...(hostScope ? { host: hostScope.value } : {}),\n\t\t\t});\n\t\t\tconst output = await this.definition.run(input, context);\n\t\t\tif (operation.signal.aborted || !this.isLeaseUsable(lease) || this.statusValue !== \"running\") return;\n\t\t\tthis.statusValue = \"succeeded\";\n\t\t\tthis.revisionValue += 1;\n\t\t\toperation.resolve(output);\n\t\t\tthis.reportLifecycle(\"end\", operation, \"succeeded\");\n\t\t\tthis.resolveCompletionOnce({ status: \"succeeded\", revision: this.revisionValue, output });\n\t\t} catch (error) {\n\t\t\tif (operation.signal.aborted || this.statusValue === \"cancelled\" || this.statusValue === \"disposed\") {\n\t\t\t\t// Instance-level cancellation marks the handle cancelled before this\n\t\t\t\t// catch runs; the pre-aborted run() path gets here first, so settle\n\t\t\t\t// the handle as cancelled instead of failed.\n\t\t\t\toperation.cancelFromInstance(operation.signal.reason);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tthis.statusValue = \"failed\";\n\t\t\tthis.revisionValue += 1;\n\t\t\toperation.reject(error);\n\t\t\tthis.reportLifecycle(\"end\", operation, \"failed\");\n\t\t\tthis.resolveCompletionOnce({ status: \"failed\", revision: this.revisionValue, error });\n\t\t} finally {\n\t\t\thostScope?.revoke();\n\t\t\toperation.signal.removeEventListener(\"abort\", revokeHost);\n\t\t\tif (externalSignal && externalAbortListener)\n\t\t\t\texternalSignal.removeEventListener(\"abort\", externalAbortListener);\n\t\t\tif (this.activeOperation === operation) this.activeOperation = undefined;\n\t\t\t// run() requires status \"created\", so at most one execution ever exists\n\t\t\t// per instance and clearing the field unconditionally is safe.\n\t\t\tthis.activeExecution = undefined;\n\t\t}\n\t}\n\n\tprivate async drainExecution(): Promise<void> {\n\t\t// Capture the reference before awaiting: execute()'s finally clears the\n\t\t// field while drainers still need the promise.\n\t\tconst execution = this.activeExecution;\n\t\tif (!execution) return;\n\t\tawait execution;\n\t}\n\n\tprivate assertNotDisposed(): void {\n\t\tif (this.statusValue === \"disposed\") throw new Error(`Agent instance is disposed: ${this.id}`);\n\t}\n\n\tprivate resolveCompletionOnce(result: AgentInstanceResult<TResult>): void {\n\t\tif (this.completionResolved) return;\n\t\tthis.completionResolved = true;\n\t\tthis.resolveCompletion(result);\n\t}\n\n\tprivate reportLifecycle(\n\t\tevent: AgentCompositionLifecycleEventName,\n\t\toperation: OperationRuntime<TResult>,\n\t\tstatus?: AgentCompositionLifecycleTerminalStatus,\n\t\tprogress?: OperationProgress,\n\t\tstep?: number,\n\t): void {\n\t\tif (!this.lifecycleDispatcher) return;\n\t\ttry {\n\t\t\tthis.lifecycleDispatcher({\n\t\t\t\tevent,\n\t\t\t\toperationId: operation.id,\n\t\t\t\toperationKind: `agent:${this.definition.id}@${this.definition.version}`,\n\t\t\t\t...(this.definition.owner === undefined ? {} : { owner: this.definition.owner }),\n\t\t\t\t...(status === undefined ? {} : { status }),\n\t\t\t\t...(progress === undefined ? {} : { progress }),\n\t\t\t\t...(step === undefined ? {} : { step }),\n\t\t\t});\n\t\t} catch {\n\t\t\t// Lifecycle delivery is observational and must not affect the operation.\n\t\t}\n\t}\n}\n\ninterface LeaseOwner {\n\tid: string;\n\tdeactivateLease(lease: ControllerLeaseRuntime): Promise<void>;\n}\n\nclass ControllerLeaseRuntime implements AgentControllerLease {\n\tprivate active = true;\n\tprivate readonly instance: LeaseOwner;\n\treadonly id: string;\n\treadonly owner: string;\n\treadonly revision: number;\n\n\tconstructor(instance: LeaseOwner, id: string, owner: string, revision: number) {\n\t\tthis.instance = instance;\n\t\tthis.id = id;\n\t\tthis.owner = owner;\n\t\tthis.revision = revision;\n\t}\n\n\tget instanceId(): string {\n\t\treturn this.instance.id;\n\t}\n\n\tisActive(): boolean {\n\t\treturn this.active;\n\t}\n\n\tasync release(): Promise<void> {\n\t\tif (!this.active) return;\n\t\tthis.active = false;\n\t\tawait this.instance.deactivateLease(this);\n\t}\n}\n\nclass OperationRuntime<TResult> implements OperationHandle<TResult> {\n\tprivate statusValue: OperationStatus = \"queued\";\n\tprivate resolveResult!: (result: TResult) => void;\n\tprivate rejectResult!: (error: unknown) => void;\n\treadonly result: Promise<TResult>;\n\treadonly id: string;\n\tprivate readonly controller: AbortController;\n\tprivate readonly cancelCallback: () => Promise<void>;\n\tprivate readonly reportProgressCallback: (progress: OperationProgress, step: number) => void;\n\tprivate progressSequence = 0;\n\n\tconstructor(\n\t\tid: string,\n\t\tcontroller: AbortController,\n\t\tcancelCallback: () => Promise<void>,\n\t\treportProgress: (progress: OperationProgress, step: number) => void,\n\t) {\n\t\tthis.id = id;\n\t\tthis.controller = controller;\n\t\tthis.cancelCallback = cancelCallback;\n\t\tthis.reportProgressCallback = reportProgress;\n\t\tthis.signal = controller.signal;\n\t\tthis.result = new Promise<TResult>((resolve, reject) => {\n\t\t\tthis.resolveResult = resolve;\n\t\t\tthis.rejectResult = reject;\n\t\t});\n\t\tthis.statusValue = \"running\";\n\t}\n\n\treadonly signal: AbortSignal;\n\n\tstatus(): OperationStatus {\n\t\treturn this.statusValue;\n\t}\n\n\treportProgress(progress: OperationProgress): boolean {\n\t\tif (this.statusValue !== \"running\" || this.signal.aborted) return false;\n\t\tthis.reportProgressCallback(progress, ++this.progressSequence);\n\t\treturn true;\n\t}\n\n\tasync cancel(reason?: string): Promise<void> {\n\t\tif (this.statusValue === \"succeeded\" || this.statusValue === \"failed\" || this.statusValue === \"cancelled\") return;\n\t\tthis.controller.abort(reason);\n\t\t// The handle must settle cancellation without waiting for an uncooperative\n\t\t// run body. AgentInstanceRuntime.cancel() still drains the body when the\n\t\t// caller explicitly cancels/releases the instance, but OperationHandle is\n\t\t// the non-blocking public fence used by callers that cannot coordinate the\n\t\t// plugin's private awaits. The callback synchronously marks the operation\n\t\t// cancelled before its first await; any later drain is best-effort here.\n\t\ttry {\n\t\t\tvoid this.cancelCallback().catch(() => undefined);\n\t\t} catch {\n\t\t\t// A cancellation request is already reflected by this operation's\n\t\t\t// aborted signal and terminal status; callback failures must not turn\n\t\t\t// cancel() into an unbounded or rejected wait.\n\t\t}\n\t}\n\n\tcancelFromInstance(reason?: string): void {\n\t\tif (this.statusValue === \"succeeded\" || this.statusValue === \"failed\" || this.statusValue === \"cancelled\") return;\n\t\tthis.statusValue = \"cancelled\";\n\t\tthis.controller.abort(reason);\n\t\tthis.rejectResult(abortError(reason));\n\t}\n\n\tresolve(value: TResult): void {\n\t\tif (this.statusValue === \"cancelled\" || this.statusValue === \"failed\") return;\n\t\tthis.statusValue = \"succeeded\";\n\t\tthis.resolveResult(value);\n\t}\n\n\treject(error: unknown): void {\n\t\tif (this.statusValue === \"cancelled\") return;\n\t\tthis.statusValue = \"failed\";\n\t\tthis.rejectResult(error);\n\t}\n}\n\nexport class AgentCompositionRuntime\n\timplements\n\t\tAgentCompositionAPI,\n\t\tAgentCompositionHostBinding,\n\t\tAgentCompositionDefinitionBinding,\n\t\tAgentCompositionScopedHostBinding,\n\t\tAgentCompositionInstanceStateBinding\n{\n\tprivate readonly definitions = new Map<string, AgentDefinition<unknown, unknown>>();\n\tprivate readonly instances = new Map<string, AgentInstanceRuntime<unknown, unknown>>();\n\tprivate readonly instanceStateClearers = new Set<(instanceId: string) => void>();\n\tprivate sequence = 0;\n\tprivate readonly nextId: (kind: string) => string;\n\tprivate readonly defaultLeaseOwner?: string;\n\tprivate hostPrimitivesFactory?: AgentHostPrimitivesFactory;\n\tprivate lifecycleDispatcher?: AgentCompositionLifecycleDispatcher;\n\n\tconstructor(options: AgentCompositionRuntimeOptions = {}) {\n\t\tthis.defaultLeaseOwner = options.defaultLeaseOwner;\n\t\tthis.hostPrimitivesFactory = options.hostPrimitivesFactory;\n\t\tthis.nextId = options.idFactory ?? ((kind: string) => `${kind}-${++this.sequence}`);\n\t}\n\n\tsetHostPrimitivesFactory(factory?: AgentHostPrimitivesFactory): void {\n\t\tthis.hostPrimitivesFactory = factory;\n\t}\n\n\tsetLifecycleDispatcher(dispatcher?: AgentCompositionLifecycleDispatcher): void {\n\t\tthis.lifecycleDispatcher = dispatcher;\n\t}\n\n\taddInstanceStateClearer(clearer: (instanceId: string) => void): () => void {\n\t\tthis.instanceStateClearers.add(clearer);\n\t\treturn () => {\n\t\t\tthis.instanceStateClearers.delete(clearer);\n\t\t};\n\t}\n\n\tdisposeDefinitions(definitions: readonly AgentDefinition[]): void {\n\t\tconst owned = new Set(definitions);\n\t\tfor (const [key, definition] of this.definitions) {\n\t\t\tif (owned.has(definition)) this.definitions.delete(key);\n\t\t}\n\t\tfor (const [id, instance] of this.instances) {\n\t\t\tif (!owned.has(instance.definition)) continue;\n\t\t\tthis.instances.delete(id);\n\t\t\tvoid instance.dispose();\n\t\t}\n\t}\n\n\tdefine<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult>,\n\t): AgentDefinition<TInput, TResult> {\n\t\tvalidateAgentDefinition(definition);\n\t\tif (this.definitions.has(this.definitionKey(definition.id, definition.version))) {\n\t\t\tthrow new Error(`Agent definition already registered: ${definition.id}@${definition.version}`);\n\t\t}\n\t\tconst frozen = Object.freeze({ ...definition });\n\t\tthis.definitions.set(\n\t\t\tthis.definitionKey(definition.id, definition.version),\n\t\t\tfrozen as AgentDefinition<unknown, unknown>,\n\t\t);\n\t\treturn frozen;\n\t}\n\n\tget<TInput = unknown, TResult = unknown>(id: string, version: number): AgentDefinition<TInput, TResult> {\n\t\tconst definition = this.definitions.get(this.definitionKey(id, version));\n\t\tif (!definition) throw new Error(`Unknown Agent definition: ${id}@${version}`);\n\t\treturn definition as AgentDefinition<TInput, TResult>;\n\t}\n\n\tcreate<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult> | DefinitionRef,\n\t\toptions: { id?: string; parentInstanceId?: string } = {},\n\t): AgentInstance<TInput, TResult> {\n\t\treturn this.createInternal(definition, options, this.hostPrimitivesFactory);\n\t}\n\n\tcreateWithHostPrimitives<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult> | DefinitionRef,\n\t\toptions: { id?: string; parentInstanceId?: string } | undefined,\n\t\thostPrimitivesFactory: AgentHostPrimitivesFactory,\n\t\tlifecycleDispatcher?: AgentCompositionLifecycleDispatcher,\n\t): AgentInstance<TInput, TResult> {\n\t\t// A CapabilityRuntime supplies a complete, session-bound factory for this\n\t\t// plugin invocation. Do not merge the runtime-wide factory here: one\n\t\t// composition runtime may be shared by more than one AgentSession.\n\t\treturn this.createInternal(\n\t\t\tdefinition,\n\t\t\toptions ?? {},\n\t\t\thostPrimitivesFactory,\n\t\t\tlifecycleDispatcher ?? this.lifecycleDispatcher,\n\t\t);\n\t}\n\n\tprivate createInternal<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult> | DefinitionRef,\n\t\toptions: { id?: string; parentInstanceId?: string },\n\t\thostPrimitivesFactory: AgentHostPrimitivesFactory | undefined,\n\t\tlifecycleDispatcher: AgentCompositionLifecycleDispatcher | undefined = this.lifecycleDispatcher,\n\t): AgentInstance<TInput, TResult> {\n\t\tif (!definition || typeof definition !== \"object\") throw new Error(\"Agent definition or reference is required\");\n\t\tconst resolved =\n\t\t\t\"run\" in definition\n\t\t\t\t? validateAgentDefinition(definition as AgentDefinition<TInput, TResult>)\n\t\t\t\t: this.get<TInput, TResult>(definition.id, definition.version);\n\t\tif (options.parentInstanceId !== undefined && !this.instances.has(options.parentInstanceId)) {\n\t\t\tthrow new Error(`Unknown parent Agent instance: ${options.parentInstanceId}`);\n\t\t}\n\t\tif (this.instances.has(options.id ?? \"\")) throw new Error(`Agent instance id already exists: ${options.id}`);\n\t\tconst id = options.id ?? this.nextId(\"agent-instance\");\n\t\tif (this.instances.has(id)) throw new Error(`Agent instance id already exists: ${id}`);\n\t\tconst instance = new AgentInstanceRuntime(\n\t\t\tresolved,\n\t\t\tid,\n\t\t\toptions.parentInstanceId,\n\t\t\tthis.nextId,\n\t\t\tthis.defaultLeaseOwner ?? resolved.owner ?? \"agent-composition\",\n\t\t\thostPrimitivesFactory,\n\t\t\tlifecycleDispatcher,\n\t\t\t(instanceId: string) => {\n\t\t\t\tfor (const clearer of this.instanceStateClearers) clearer(instanceId);\n\t\t\t},\n\t\t);\n\t\tthis.instances.set(id, instance as AgentInstanceRuntime<unknown, unknown>);\n\t\treturn instance;\n\t}\n\n\tlistInstances(): readonly AgentInstanceSnapshot[] {\n\t\treturn Object.freeze([...this.instances.values()].map((instance) => instance.snapshot()));\n\t}\n\n\tprivate definitionKey(id: string, version: number): string {\n\t\treturn `${id}@${version}`;\n\t}\n}\n\nexport function createAgentCompositionRuntime(options: AgentCompositionRuntimeOptions = {}): AgentCompositionRuntime {\n\treturn new AgentCompositionRuntime(options);\n}\n"]}
+{"version":3,"file":"agent-composition.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/agent-composition.ts"],"names":[],"mappings":"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","sourcesContent":["import { t } from \"../i18n/index.ts\";\nimport type {\n\tAgentCompositionAPI,\n\tAgentCompositionDefinitionBinding,\n\tAgentCompositionHostBinding,\n\tAgentCompositionScopedHostBinding,\n\tAgentContextCommitRequestV1,\n\tAgentContextCommitResultV1,\n\tAgentContextFacadeV1,\n\tAgentControllerLease,\n\tAgentDefinition,\n\tAgentExecutionContext,\n\tAgentHostPrimitivesFactory,\n\tAgentHostPrimitivesV1,\n\tAgentInstance,\n\tAgentInstanceResult,\n\tAgentInstanceSnapshot,\n\tAgentInstanceStatus,\n\tAgentModelFacadeV1,\n\tAgentModelInvocationV1,\n\tAgentOperationFacadeV1,\n\tAgentSessionFacadeV1,\n\tAgentToolFacadeV1,\n\tDisposableRegistration,\n\tOperationHandle,\n\tOperationProgress,\n\tOperationStatus,\n\tOutputArtifactAPI,\n\tOutputArtifactChunk,\n\tOutputArtifactRef,\n\tStateAPI,\n\tStateChange,\n} from \"./public-api.ts\";\n\nexport interface AgentCompositionRuntimeOptions {\n\tidFactory?: (kind: string) => string;\n\tdefaultLeaseOwner?: string;\n\thostPrimitivesFactory?: AgentHostPrimitivesFactory;\n}\n\nexport type AgentCompositionLifecycleEventName = \"start\" | \"step\" | \"cancel\" | \"end\";\nexport type AgentCompositionLifecycleTerminalStatus = \"succeeded\" | \"failed\" | \"cancelled\";\n\nexport interface AgentCompositionLifecycleEvent {\n\treadonly event: AgentCompositionLifecycleEventName;\n\treadonly operationId: string;\n\treadonly operationKind: string;\n\treadonly owner?: string;\n\treadonly status?: AgentCompositionLifecycleTerminalStatus;\n\treadonly step?: number;\n\treadonly progress?: OperationProgress;\n}\n\nexport type AgentCompositionLifecycleDispatcher = (event: AgentCompositionLifecycleEvent) => void;\n\n/** Host-only binding used by CapabilityRuntime to observe composition operations. */\nexport interface AgentCompositionLifecycleBinding {\n\tsetLifecycleDispatcher(dispatcher?: AgentCompositionLifecycleDispatcher): void;\n}\n\n/**\n * Host-only binding used by CapabilityRuntime to clear instance-scoped state\n * when an instance is disposed. Instance ids are unique per composition\n * runtime, so every registered clearer is invoked on each disposal and\n * resolves by id whether the disposed instance belongs to it.\n */\nexport interface AgentCompositionInstanceStateBinding {\n\t/** Registers a clearer invoked after a disposed instance's execution drained. Returns an unsubscribe function. */\n\taddInstanceStateClearer(clearer: (instanceId: string) => void): () => void;\n}\n\ntype DefinitionRef = { id: string; version: number };\n\nconst terminalStatuses = new Set<AgentInstanceStatus>([\"succeeded\", \"failed\", \"cancelled\", \"disposed\"]);\n\nfunction abortError(reason?: unknown): Error {\n\tif (reason instanceof Error) return reason;\n\tconst error = new Error(reason === undefined ? \"Agent operation cancelled\" : String(reason));\n\terror.name = \"AbortError\";\n\treturn error;\n}\n\nfunction combinedAbortSignal(...signals: readonly (AbortSignal | undefined)[]): {\n\tsignal: AbortSignal;\n\tdispose(): void;\n} {\n\tconst controller = new AbortController();\n\tconst listeners: Array<{ signal: AbortSignal; listener: () => void }> = [];\n\tfor (const signal of new Set(signals.filter((signal): signal is AbortSignal => signal !== undefined))) {\n\t\tconst abort = () => {\n\t\t\tif (!controller.signal.aborted) controller.abort(signal.reason);\n\t\t};\n\t\tif (signal.aborted) {\n\t\t\tabort();\n\t\t\tbreak;\n\t\t}\n\t\tsignal.addEventListener(\"abort\", abort, { once: true });\n\t\tlisteners.push({ signal, listener: abort });\n\t}\n\treturn {\n\t\tsignal: controller.signal,\n\t\tdispose: () => {\n\t\t\tfor (const { signal, listener } of listeners) signal.removeEventListener(\"abort\", listener);\n\t\t},\n\t};\n}\n\nfunction freezeSnapshot(snapshot: AgentInstanceSnapshot): AgentInstanceSnapshot {\n\treturn Object.freeze({ ...snapshot });\n}\n\nfunction validateAgentDefinition<TInput, TResult>(\n\tdefinition: AgentDefinition<TInput, TResult>,\n): AgentDefinition<TInput, TResult> {\n\tif (!definition || typeof definition !== \"object\") {\n\t\tthrow new Error(t(\"Agent definition is required\"));\n\t}\n\tif (typeof definition.id !== \"string\" || !definition.id.trim()) {\n\t\tthrow new Error(t(\"Agent definition requires a non-empty id\"));\n\t}\n\tif (!Number.isSafeInteger(definition.version) || definition.version < 1) {\n\t\tthrow new Error(t(\"Agent definition version must be a positive safe integer\"));\n\t}\n\tif (definition.role !== \"root-agent-controller\" && definition.role !== \"child-agent-controller\") {\n\t\tthrow new Error(t(\"Agent definition role must be root-agent-controller or child-agent-controller\"));\n\t}\n\tif (typeof definition.run !== \"function\") {\n\t\tthrow new Error(t(\"Agent definition requires a run function\"));\n\t}\n\tif (definition.owner !== undefined && (typeof definition.owner !== \"string\" || !definition.owner.trim())) {\n\t\tthrow new Error(t(\"Agent definition owner must be a non-empty string when provided\"));\n\t}\n\treturn definition;\n}\n\nfunction detachedFreeze<T>(value: T, seen = new WeakMap<object, unknown>()): T {\n\tif (value === null || typeof value !== \"object\") return value;\n\tif (value instanceof Uint8Array) return new Uint8Array(value) as T;\n\tconst existing = seen.get(value);\n\tif (existing) return existing as T;\n\tconst result: Record<string, unknown> | unknown[] = Array.isArray(value) ? [] : {};\n\tseen.set(value, result);\n\tfor (const [key, item] of Object.entries(value as Record<string, unknown>)) {\n\t\t(result as Record<string, unknown>)[key] = detachedFreeze(item, seen);\n\t}\n\treturn Object.freeze(result) as T;\n}\n\nfunction disposable(dispose: () => void | Promise<void>): DisposableRegistration {\n\tlet disposed = false;\n\treturn {\n\t\tid: \"agent-host-registration\",\n\t\tkind: \"agent-host\",\n\t\tdispose: () => {\n\t\t\tif (disposed) return;\n\t\t\tdisposed = true;\n\t\t\treturn dispose();\n\t\t},\n\t};\n}\n\nfunction revokedError(instanceId: string): Error {\n\treturn new Error(`Agent host primitives are revoked: ${instanceId}`);\n}\n\ninterface RevocableHost {\n\treadonly value: AgentHostPrimitivesV1;\n\trevoke(): void;\n}\n\nfunction createOperationFacade<TResult>(\n\toperation: OperationRuntime<TResult>,\n\tinstanceId: string,\n\tactive: () => boolean,\n): AgentOperationFacadeV1 {\n\treturn Object.freeze({\n\t\tversion: 1 as const,\n\t\tid: operation.id,\n\t\tsignal: operation.signal,\n\t\tstatus: () => {\n\t\t\tif (!active()) return \"cancelled\" as OperationStatus;\n\t\t\treturn operation.status();\n\t\t},\n\t\tisActive: () => active() && operation.status() === \"running\",\n\t\treportProgress: (progress: OperationProgress) => active() && operation.reportProgress(progress),\n\t\tonCancel: (handler: (reason: unknown) => void | Promise<void>) => {\n\t\t\tif (!active()) throw revokedError(instanceId);\n\t\t\tconst listener = () => {\n\t\t\t\tvoid handler(operation.signal.reason);\n\t\t\t};\n\t\t\toperation.signal.addEventListener(\"abort\", listener, { once: true });\n\t\t\treturn disposable(() => operation.signal.removeEventListener(\"abort\", listener));\n\t\t},\n\t\tcancel: async (reason?: string) => {\n\t\t\tif (!active()) throw revokedError(instanceId);\n\t\t\tawait operation.cancel(reason);\n\t\t},\n\t});\n}\n\nfunction createRevocableHostPrimitives(\n\traw: AgentHostPrimitivesV1,\n\toperation: OperationRuntime<unknown>,\n\tinstance: AgentInstanceSnapshot,\n): RevocableHost {\n\tlet active = true;\n\tconst cleanups: Array<() => void | Promise<void>> = [];\n\tconst track = (registration: DisposableRegistration): DisposableRegistration => {\n\t\tlet released = false;\n\t\tconst dispose = async () => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tconst index = cleanups.indexOf(cleanup);\n\t\t\tif (index >= 0) cleanups.splice(index, 1);\n\t\t\tawait registration.dispose();\n\t\t};\n\t\tconst cleanup = dispose;\n\t\tcleanups.push(cleanup);\n\t\treturn {\n\t\t\tid: registration.id,\n\t\t\tkind: registration.kind,\n\t\t\tdispose,\n\t\t};\n\t};\n\tconst assertActive = () => {\n\t\tif (!active) throw revokedError(instance.id);\n\t\tif (operation.signal.aborted) throw abortError(operation.signal.reason);\n\t};\n\n\tconst session = raw.session\n\t\t? (Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\tgetSessionId: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.session!.getSessionId();\n\t\t\t\t},\n\t\t\t\tgetRevision: raw.session.getRevision\n\t\t\t\t\t? () => {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn detachedFreeze(raw.session!.getRevision!());\n\t\t\t\t\t\t}\n\t\t\t\t\t: undefined,\n\t\t\t\tgetMessages: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(raw.session!.getMessages());\n\t\t\t\t},\n\t\t\t\tgetBranchEntries: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(raw.session!.getBranchEntries());\n\t\t\t\t},\n\t\t\t\tisIdle: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.session!.isIdle();\n\t\t\t\t},\n\t\t\t\twaitForIdle: async () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tawait raw.session!.waitForIdle();\n\t\t\t\t\tassertActive();\n\t\t\t\t},\n\t\t\t\tappendEntry: (customType: string, data?: unknown) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.session!.appendEntry(customType, detachedFreeze(data));\n\t\t\t\t},\n\t\t\t}) as AgentSessionFacadeV1)\n\t\t: undefined;\n\n\tconst context = raw.context\n\t\t? (Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\tget: <TValue = unknown>() => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(raw.context!.get<TValue>());\n\t\t\t\t},\n\t\t\t\tcommit: async <TValue = unknown>(request: AgentContextCommitRequestV1<TValue>) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tif (request.signal?.aborted) throw abortError(request.signal.reason);\n\t\t\t\t\tconst result = await raw.context!.commit({\n\t\t\t\t\t\t...request,\n\t\t\t\t\t\tvalue: detachedFreeze(request.value),\n\t\t\t\t\t});\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(result) as AgentContextCommitResultV1<TValue>;\n\t\t\t\t},\n\t\t\t}) as AgentContextFacadeV1)\n\t\t: undefined;\n\n\t// One guarded StateAPI facade shared by the owner namespace and the\n\t// instance-private namespace: same revocation gating and detached snapshots.\n\tconst guardedStateFacade = (source: StateAPI): StateAPI =>\n\t\tObject.freeze({\n\t\t\tget: (key: string) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn detachedFreeze(source.get(key));\n\t\t\t},\n\t\t\tset: (key: string, value: Parameters<StateAPI[\"set\"]>[1], options?: Parameters<StateAPI[\"set\"]>[2]) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn source.set(key, detachedFreeze(value), options);\n\t\t\t},\n\t\t\tdelete: (key: string, options?: Parameters<StateAPI[\"delete\"]>[1]) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn source.delete(key, options);\n\t\t\t},\n\t\t\tlist: (prefix?: string) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn detachedFreeze(source.list(prefix));\n\t\t\t},\n\t\t\twatch: (prefix: string | undefined, handler: (change: StateChange) => void | Promise<void>) => {\n\t\t\t\tassertActive();\n\t\t\t\treturn track(\n\t\t\t\t\tsource.watch(prefix, (change: StateChange) => {\n\t\t\t\t\t\tif (!active || operation.signal.aborted) return;\n\t\t\t\t\t\tvoid handler(detachedFreeze(change));\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t},\n\t\t}) as StateAPI;\n\n\tconst state = raw.state ? guardedStateFacade(raw.state) : undefined;\n\tconst instanceState = raw.instanceState ? guardedStateFacade(raw.instanceState) : undefined;\n\n\tconst artifact = raw.artifact\n\t\t? (Object.freeze({\n\t\t\t\tput: async (\n\t\t\t\t\tinput: Parameters<OutputArtifactAPI[\"put\"]>[0],\n\t\t\t\t\toptions?: Parameters<OutputArtifactAPI[\"put\"]>[1],\n\t\t\t\t) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tconst data = input.data instanceof Uint8Array ? new Uint8Array(input.data) : input.data;\n\t\t\t\t\tconst abort = combinedAbortSignal(operation.signal, options?.signal);\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst ref = await raw.artifact!.put({ ...input, data }, { ...options, signal: abort.signal });\n\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\treturn detachedFreeze(ref) as OutputArtifactRef;\n\t\t\t\t\t} finally {\n\t\t\t\t\t\tabort.dispose();\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\tstat: async (ref: OutputArtifactRef) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tconst result = await raw.artifact!.stat(detachedFreeze(ref));\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze(result);\n\t\t\t\t},\n\t\t\t\tread: async (ref: OutputArtifactRef, options?: Parameters<OutputArtifactAPI[\"read\"]>[1]) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tconst chunk = await raw.artifact!.read(detachedFreeze(ref), options);\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn detachedFreeze({\n\t\t\t\t\t\t...chunk,\n\t\t\t\t\t\tdata: new Uint8Array(chunk.data),\n\t\t\t\t\t}) as OutputArtifactChunk;\n\t\t\t\t},\n\t\t\t}) as OutputArtifactAPI)\n\t\t: undefined;\n\n\tconst operationFacade = raw.operation\n\t\t? Object.freeze({\n\t\t\t\tversion: 1 as const,\n\t\t\t\tid: raw.operation.id,\n\t\t\t\tsignal: raw.operation.signal,\n\t\t\t\tstatus: () => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.operation!.status();\n\t\t\t\t},\n\t\t\t\tisActive: () => active && raw.operation!.isActive(),\n\t\t\t\treportProgress: (progress: OperationProgress) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn raw.operation!.reportProgress(progress);\n\t\t\t\t},\n\t\t\t\tonCancel: (handler: (reason: unknown) => void | Promise<void>) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\treturn track(raw.operation!.onCancel(handler));\n\t\t\t\t},\n\t\t\t\tcancel: async (reason?: string) => {\n\t\t\t\t\tassertActive();\n\t\t\t\t\tawait raw.operation!.cancel(reason);\n\t\t\t\t},\n\t\t\t})\n\t\t: createOperationFacade(operation, instance.id, () => active);\n\n\tconst value = Object.freeze({\n\t\tversion: 1 as const,\n\t\t...(session ? { session } : {}),\n\t\t...(context ? { context } : {}),\n\t\t...(state ? { state } : {}),\n\t\t...(instanceState ? { instanceState } : {}),\n\t\t...(artifact ? { artifact } : {}),\n\t\t...(operationFacade ? { operation: operationFacade } : {}),\n\t\t...(raw.model\n\t\t\t? {\n\t\t\t\t\tmodel: Object.freeze({\n\t\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\t\tget facts() {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn raw.model!.facts;\n\t\t\t\t\t\t},\n\t\t\t\t\t\tinvocation: {\n\t\t\t\t\t\t\tinvoke: async (input: Parameters<AgentModelInvocationV1[\"invoke\"]>[0], signal: AbortSignal) => {\n\t\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\t\tconst result = await raw.model!.invocation.invoke(input, signal);\n\t\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\t\treturn result;\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t}) satisfies AgentModelFacadeV1,\n\t\t\t\t}\n\t\t\t: {}),\n\t\t...(raw.tool\n\t\t\t? {\n\t\t\t\t\ttool: Object.freeze({\n\t\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\t\tlistTools: () => {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn raw.tool!.listTools();\n\t\t\t\t\t\t},\n\t\t\t\t\t\tinvokeTool: (name: string, input: unknown, invokeOptions?: { readonly signal?: AbortSignal }) => {\n\t\t\t\t\t\t\tassertActive();\n\t\t\t\t\t\t\treturn raw.tool!.invokeTool(name, input, invokeOptions);\n\t\t\t\t\t\t},\n\t\t\t\t\t}) satisfies AgentToolFacadeV1,\n\t\t\t\t}\n\t\t\t: {}),\n\t});\n\treturn {\n\t\tvalue,\n\t\trevoke: () => {\n\t\t\tif (!active) return;\n\t\t\tactive = false;\n\t\t\tfor (const cleanup of [...cleanups]) void cleanup();\n\t\t},\n\t};\n}\n\nclass AgentInstanceRuntime<TInput, TResult> implements AgentInstance<TInput, TResult> {\n\treadonly id: string;\n\treadonly definition: AgentDefinition<TInput, TResult>;\n\n\tprivate statusValue: AgentInstanceStatus = \"created\";\n\tprivate revisionValue = 0;\n\tprivate activeLease?: ControllerLeaseRuntime;\n\tprivate activeOperation?: OperationRuntime<TResult>;\n\tprivate activeExecution?: Promise<void>;\n\tprivate completion: Promise<AgentInstanceResult<TResult>>;\n\tprivate resolveCompletion!: (result: AgentInstanceResult<TResult>) => void;\n\tprivate completionResolved = false;\n\tprivate readonly parentInstanceId: string | undefined;\n\tprivate readonly nextId: (kind: string) => string;\n\tprivate readonly defaultLeaseOwner: string;\n\tprivate readonly hostPrimitivesFactory?: AgentHostPrimitivesFactory;\n\tprivate readonly lifecycleDispatcher?: AgentCompositionLifecycleDispatcher;\n\tprivate readonly clearInstanceState?: (instanceId: string) => void;\n\n\tconstructor(\n\t\tdefinition: AgentDefinition<TInput, TResult>,\n\t\tid: string,\n\t\tparentInstanceId: string | undefined,\n\t\tnextId: (kind: string) => string,\n\t\tdefaultLeaseOwner: string,\n\t\thostPrimitivesFactory: AgentHostPrimitivesFactory | undefined,\n\t\tlifecycleDispatcher: AgentCompositionLifecycleDispatcher | undefined,\n\t\tclearInstanceState: ((instanceId: string) => void) | undefined,\n\t) {\n\t\tthis.id = id;\n\t\tthis.definition = definition;\n\t\tthis.parentInstanceId = parentInstanceId;\n\t\tthis.nextId = nextId;\n\t\tthis.defaultLeaseOwner = defaultLeaseOwner;\n\t\tthis.hostPrimitivesFactory = hostPrimitivesFactory;\n\t\tthis.lifecycleDispatcher = lifecycleDispatcher;\n\t\tthis.clearInstanceState = clearInstanceState;\n\t\tthis.completion = new Promise<AgentInstanceResult<TResult>>((resolve) => {\n\t\t\tthis.resolveCompletion = resolve;\n\t\t});\n\t}\n\n\tsnapshot(): AgentInstanceSnapshot {\n\t\treturn freezeSnapshot({\n\t\t\tid: this.id,\n\t\t\tdefinitionId: this.definition.id,\n\t\t\tdefinitionVersion: this.definition.version,\n\t\t\trole: this.definition.role,\n\t\t\t...(this.parentInstanceId ? { parentInstanceId: this.parentInstanceId } : {}),\n\t\t\tstatus: this.statusValue,\n\t\t\trevision: this.revisionValue,\n\t\t\t...(this.activeLease?.isActive() ? { leaseOwner: this.activeLease.owner } : {}),\n\t\t});\n\t}\n\n\tasync acquireControllerLease(\n\t\towner = this.definition.owner ?? this.defaultLeaseOwner,\n\t): Promise<AgentControllerLease> {\n\t\tthis.assertNotDisposed();\n\t\tif (this.activeLease?.isActive())\n\t\t\tthrow new Error(t(\"Agent instance already has an active controller lease: {id}\", { id: this.id }));\n\t\tconst lease = new ControllerLeaseRuntime(this, this.nextId(\"agent-lease\"), owner, this.revisionValue + 1);\n\t\tthis.activeLease = lease;\n\t\treturn lease;\n\t}\n\n\trun(input: TInput, options: { lease?: AgentControllerLease; signal?: AbortSignal } = {}): OperationHandle<TResult> {\n\t\tthis.assertNotDisposed();\n\t\tif (this.statusValue !== \"created\")\n\t\t\tthrow new Error(\n\t\t\t\tt(\"Agent instance cannot run from status {statusValue}: {id}\", {\n\t\t\t\t\tstatusValue: this.statusValue,\n\t\t\t\t\tid: this.id,\n\t\t\t\t}),\n\t\t\t);\n\t\tconst lease = this.activeLease;\n\t\tif (!lease?.isActive())\n\t\t\tthrow new Error(t(\"Agent instance requires an active controller lease: {id}\", { id: this.id }));\n\t\tif (options.lease !== lease || !this.isLeaseUsable(options.lease)) {\n\t\t\tthrow new Error(t(\"Agent controller lease is not valid for instance: {id}\", { id: this.id }));\n\t\t}\n\n\t\tthis.statusValue = \"running\";\n\t\tconst controller = new AbortController();\n\t\tconst externalSignal = options.signal;\n\t\tlet externalAbortListener: (() => void) | undefined;\n\t\tif (externalSignal) {\n\t\t\texternalAbortListener = () => {\n\t\t\t\tcontroller.abort(externalSignal.reason);\n\t\t\t\tvoid this.cancel(externalSignal.reason === undefined ? undefined : String(externalSignal.reason));\n\t\t\t};\n\t\t\tif (!externalSignal.aborted) externalSignal.addEventListener(\"abort\", externalAbortListener, { once: true });\n\t\t}\n\n\t\tlet operation!: OperationRuntime<TResult>;\n\t\toperation = new OperationRuntime<TResult>(\n\t\t\tthis.nextId(\"agent-operation\"),\n\t\t\tcontroller,\n\t\t\t() => this.cancel(controller.signal.reason),\n\t\t\t(progress, step) => this.reportLifecycle(\"step\", operation, undefined, progress, step),\n\t\t);\n\t\tthis.activeOperation = operation;\n\t\tif (externalSignal?.aborted) {\n\t\t\tcontroller.abort(externalSignal.reason);\n\t\t} else {\n\t\t\tthis.reportLifecycle(\"start\", operation);\n\t\t}\n\t\tthis.activeExecution = this.execute(input, lease, operation, externalSignal, externalAbortListener);\n\t\tif (externalSignal?.aborted) {\n\t\t\t// Trigger cancellation only after the execution is tracked, so the\n\t\t\t// pre-aborted path drains like every other cancellation path instead\n\t\t\t// of resolving completion ahead of the execution body.\n\t\t\tvoid this.cancel(externalSignal.reason === undefined ? undefined : String(externalSignal.reason));\n\t\t}\n\t\treturn operation;\n\t}\n\n\tasync wait(): Promise<AgentInstanceResult<TResult>> {\n\t\treturn this.completion;\n\t}\n\n\tasync cancel(reason?: string): Promise<void> {\n\t\tif (this.statusValue === \"disposed\" || terminalStatuses.has(this.statusValue)) return;\n\t\tthis.statusValue = \"cancelled\";\n\t\tthis.revisionValue += 1;\n\t\tconst operation = this.activeOperation;\n\t\tif (operation) {\n\t\t\tthis.reportLifecycle(\"cancel\", operation);\n\t\t\tthis.reportLifecycle(\"end\", operation, \"cancelled\");\n\t\t\toperation.cancelFromInstance(reason);\n\t\t}\n\t\t// The run body must eventually observe the abort signal: cancellation only\n\t\t// settles after the execution drained, so wait() and lease disposal never\n\t\t// race side effects still in flight. There is deliberately no timeout. A run\n\t\t// body that awaits this cancel(), dispose(), or its own lease release\n\t\t// self-deadlocks by contract.\n\t\tawait this.drainExecution();\n\t\tthis.resolveCompletionOnce({ status: \"cancelled\", revision: this.revisionValue, error: abortError(reason) });\n\t}\n\n\tasync dispose(): Promise<void> {\n\t\tif (this.statusValue === \"disposed\") return;\n\t\tif (this.statusValue === \"created\") {\n\t\t\tawait this.activeLease?.release();\n\t\t\tthis.statusValue = \"disposed\";\n\t\t\tthis.revisionValue += 1;\n\t\t\tthis.clearInstanceState?.(this.id);\n\t\t\tthis.resolveCompletionOnce({ status: \"disposed\", revision: this.revisionValue });\n\t\t\treturn;\n\t\t}\n\t\tif (!terminalStatuses.has(this.statusValue)) await this.cancel(\"Agent instance disposed\");\n\t\t// A concurrent cancel() may still be draining; release the lease only after\n\t\t// the execution has settled.\n\t\tawait this.drainExecution();\n\t\tawait this.activeLease?.release();\n\t\tthis.statusValue = \"disposed\";\n\t\tthis.revisionValue += 1;\n\t\t// The instance-private state namespace (and its watchers) dies with the\n\t\t// instance, after every drain the run body could still rely on.\n\t\tthis.clearInstanceState?.(this.id);\n\t\tthis.resolveCompletionOnce({ status: \"disposed\", revision: this.revisionValue });\n\t}\n\n\tasync deactivateLease(lease: ControllerLeaseRuntime): Promise<void> {\n\t\tif (this.activeLease !== lease) return;\n\t\tthis.activeLease = undefined;\n\t\tif (this.statusValue === \"running\") {\n\t\t\tawait this.cancel(\"Controller lease released\");\n\t\t\treturn;\n\t\t}\n\t\t// A cancel() from another path may still be draining the execution.\n\t\tawait this.drainExecution();\n\t}\n\n\tisLeaseUsable(lease: AgentControllerLease | undefined): lease is ControllerLeaseRuntime {\n\t\treturn (\n\t\t\tlease instanceof ControllerLeaseRuntime &&\n\t\t\tlease.instanceId === this.id &&\n\t\t\tlease.isActive() &&\n\t\t\tthis.activeLease === lease\n\t\t);\n\t}\n\n\tprivate async execute(\n\t\tinput: TInput,\n\t\tlease: ControllerLeaseRuntime,\n\t\toperation: OperationRuntime<TResult>,\n\t\texternalSignal: AbortSignal | undefined,\n\t\texternalAbortListener: (() => void) | undefined,\n\t): Promise<void> {\n\t\tconst instanceSnapshot = this.snapshot();\n\t\tlet hostScope: RevocableHost | undefined;\n\t\tconst revokeHost = () => hostScope?.revoke();\n\t\toperation.signal.addEventListener(\"abort\", revokeHost, { once: true });\n\t\ttry {\n\t\t\tif (operation.signal.aborted) throw abortError(operation.signal.reason);\n\t\t\tif (this.hostPrimitivesFactory) {\n\t\t\t\tconst raw = await this.hostPrimitivesFactory({\n\t\t\t\t\tinstance: instanceSnapshot,\n\t\t\t\t\toperationId: operation.id,\n\t\t\t\t\tsignal: operation.signal,\n\t\t\t\t\tleaseOwner: lease.owner,\n\t\t\t\t});\n\t\t\t\tif (raw !== undefined) {\n\t\t\t\t\tif (raw.version !== 1) throw new Error(t(\"Unsupported Agent host primitives version\"));\n\t\t\t\t\tif (raw.operation && (raw.operation.id !== operation.id || raw.operation.signal !== operation.signal))\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\tt(\"Agent host operation does not match active operation: {id}\", { id: operation.id }),\n\t\t\t\t\t\t);\n\t\t\t\t\thostScope = createRevocableHostPrimitives(\n\t\t\t\t\t\t{ ...raw, operation: raw.operation ?? createOperationFacade(operation, this.id, () => true) },\n\t\t\t\t\t\toperation as OperationRuntime<unknown>,\n\t\t\t\t\t\tinstanceSnapshot,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (operation.signal.aborted) throw abortError(operation.signal.reason);\n\t\t\tconst context: AgentExecutionContext = Object.freeze({\n\t\t\t\tinstance: instanceSnapshot,\n\t\t\t\tsignal: operation.signal,\n\t\t\t\tinputRevision: this.revisionValue,\n\t\t\t\t...(hostScope ? { host: hostScope.value } : {}),\n\t\t\t});\n\t\t\tconst output = await this.definition.run(input, context);\n\t\t\tif (operation.signal.aborted || !this.isLeaseUsable(lease) || this.statusValue !== \"running\") return;\n\t\t\tthis.statusValue = \"succeeded\";\n\t\t\tthis.revisionValue += 1;\n\t\t\toperation.resolve(output);\n\t\t\tthis.reportLifecycle(\"end\", operation, \"succeeded\");\n\t\t\tthis.resolveCompletionOnce({ status: \"succeeded\", revision: this.revisionValue, output });\n\t\t} catch (error) {\n\t\t\tif (operation.signal.aborted || this.statusValue === \"cancelled\" || this.statusValue === \"disposed\") {\n\t\t\t\t// Instance-level cancellation marks the handle cancelled before this\n\t\t\t\t// catch runs; the pre-aborted run() path gets here first, so settle\n\t\t\t\t// the handle as cancelled instead of failed.\n\t\t\t\toperation.cancelFromInstance(operation.signal.reason);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tthis.statusValue = \"failed\";\n\t\t\tthis.revisionValue += 1;\n\t\t\toperation.reject(error);\n\t\t\tthis.reportLifecycle(\"end\", operation, \"failed\");\n\t\t\tthis.resolveCompletionOnce({ status: \"failed\", revision: this.revisionValue, error });\n\t\t} finally {\n\t\t\thostScope?.revoke();\n\t\t\toperation.signal.removeEventListener(\"abort\", revokeHost);\n\t\t\tif (externalSignal && externalAbortListener)\n\t\t\t\texternalSignal.removeEventListener(\"abort\", externalAbortListener);\n\t\t\tif (this.activeOperation === operation) this.activeOperation = undefined;\n\t\t\t// run() requires status \"created\", so at most one execution ever exists\n\t\t\t// per instance and clearing the field unconditionally is safe.\n\t\t\tthis.activeExecution = undefined;\n\t\t}\n\t}\n\n\tprivate async drainExecution(): Promise<void> {\n\t\t// Capture the reference before awaiting: execute()'s finally clears the\n\t\t// field while drainers still need the promise.\n\t\tconst execution = this.activeExecution;\n\t\tif (!execution) return;\n\t\tawait execution;\n\t}\n\n\tprivate assertNotDisposed(): void {\n\t\tif (this.statusValue === \"disposed\") throw new Error(t(\"Agent instance is disposed: {id}\", { id: this.id }));\n\t}\n\n\tprivate resolveCompletionOnce(result: AgentInstanceResult<TResult>): void {\n\t\tif (this.completionResolved) return;\n\t\tthis.completionResolved = true;\n\t\tthis.resolveCompletion(result);\n\t}\n\n\tprivate reportLifecycle(\n\t\tevent: AgentCompositionLifecycleEventName,\n\t\toperation: OperationRuntime<TResult>,\n\t\tstatus?: AgentCompositionLifecycleTerminalStatus,\n\t\tprogress?: OperationProgress,\n\t\tstep?: number,\n\t): void {\n\t\tif (!this.lifecycleDispatcher) return;\n\t\ttry {\n\t\t\tthis.lifecycleDispatcher({\n\t\t\t\tevent,\n\t\t\t\toperationId: operation.id,\n\t\t\t\toperationKind: `agent:${this.definition.id}@${this.definition.version}`,\n\t\t\t\t...(this.definition.owner === undefined ? {} : { owner: this.definition.owner }),\n\t\t\t\t...(status === undefined ? {} : { status }),\n\t\t\t\t...(progress === undefined ? {} : { progress }),\n\t\t\t\t...(step === undefined ? {} : { step }),\n\t\t\t});\n\t\t} catch {\n\t\t\t// Lifecycle delivery is observational and must not affect the operation.\n\t\t}\n\t}\n}\n\ninterface LeaseOwner {\n\tid: string;\n\tdeactivateLease(lease: ControllerLeaseRuntime): Promise<void>;\n}\n\nclass ControllerLeaseRuntime implements AgentControllerLease {\n\tprivate active = true;\n\tprivate readonly instance: LeaseOwner;\n\treadonly id: string;\n\treadonly owner: string;\n\treadonly revision: number;\n\n\tconstructor(instance: LeaseOwner, id: string, owner: string, revision: number) {\n\t\tthis.instance = instance;\n\t\tthis.id = id;\n\t\tthis.owner = owner;\n\t\tthis.revision = revision;\n\t}\n\n\tget instanceId(): string {\n\t\treturn this.instance.id;\n\t}\n\n\tisActive(): boolean {\n\t\treturn this.active;\n\t}\n\n\tasync release(): Promise<void> {\n\t\tif (!this.active) return;\n\t\tthis.active = false;\n\t\tawait this.instance.deactivateLease(this);\n\t}\n}\n\nclass OperationRuntime<TResult> implements OperationHandle<TResult> {\n\tprivate statusValue: OperationStatus = \"queued\";\n\tprivate resolveResult!: (result: TResult) => void;\n\tprivate rejectResult!: (error: unknown) => void;\n\treadonly result: Promise<TResult>;\n\treadonly id: string;\n\tprivate readonly controller: AbortController;\n\tprivate readonly cancelCallback: () => Promise<void>;\n\tprivate readonly reportProgressCallback: (progress: OperationProgress, step: number) => void;\n\tprivate progressSequence = 0;\n\n\tconstructor(\n\t\tid: string,\n\t\tcontroller: AbortController,\n\t\tcancelCallback: () => Promise<void>,\n\t\treportProgress: (progress: OperationProgress, step: number) => void,\n\t) {\n\t\tthis.id = id;\n\t\tthis.controller = controller;\n\t\tthis.cancelCallback = cancelCallback;\n\t\tthis.reportProgressCallback = reportProgress;\n\t\tthis.signal = controller.signal;\n\t\tthis.result = new Promise<TResult>((resolve, reject) => {\n\t\t\tthis.resolveResult = resolve;\n\t\t\tthis.rejectResult = reject;\n\t\t});\n\t\tthis.statusValue = \"running\";\n\t}\n\n\treadonly signal: AbortSignal;\n\n\tstatus(): OperationStatus {\n\t\treturn this.statusValue;\n\t}\n\n\treportProgress(progress: OperationProgress): boolean {\n\t\tif (this.statusValue !== \"running\" || this.signal.aborted) return false;\n\t\tthis.reportProgressCallback(progress, ++this.progressSequence);\n\t\treturn true;\n\t}\n\n\tasync cancel(reason?: string): Promise<void> {\n\t\tif (this.statusValue === \"succeeded\" || this.statusValue === \"failed\" || this.statusValue === \"cancelled\") return;\n\t\tthis.controller.abort(reason);\n\t\t// The handle must settle cancellation without waiting for an uncooperative\n\t\t// run body. AgentInstanceRuntime.cancel() still drains the body when the\n\t\t// caller explicitly cancels/releases the instance, but OperationHandle is\n\t\t// the non-blocking public fence used by callers that cannot coordinate the\n\t\t// plugin's private awaits. The callback synchronously marks the operation\n\t\t// cancelled before its first await; any later drain is best-effort here.\n\t\ttry {\n\t\t\tvoid this.cancelCallback().catch(() => undefined);\n\t\t} catch {\n\t\t\t// A cancellation request is already reflected by this operation's\n\t\t\t// aborted signal and terminal status; callback failures must not turn\n\t\t\t// cancel() into an unbounded or rejected wait.\n\t\t}\n\t}\n\n\tcancelFromInstance(reason?: string): void {\n\t\tif (this.statusValue === \"succeeded\" || this.statusValue === \"failed\" || this.statusValue === \"cancelled\") return;\n\t\tthis.statusValue = \"cancelled\";\n\t\tthis.controller.abort(reason);\n\t\tthis.rejectResult(abortError(reason));\n\t}\n\n\tresolve(value: TResult): void {\n\t\tif (this.statusValue === \"cancelled\" || this.statusValue === \"failed\") return;\n\t\tthis.statusValue = \"succeeded\";\n\t\tthis.resolveResult(value);\n\t}\n\n\treject(error: unknown): void {\n\t\tif (this.statusValue === \"cancelled\") return;\n\t\tthis.statusValue = \"failed\";\n\t\tthis.rejectResult(error);\n\t}\n}\n\nexport class AgentCompositionRuntime\n\timplements\n\t\tAgentCompositionAPI,\n\t\tAgentCompositionHostBinding,\n\t\tAgentCompositionDefinitionBinding,\n\t\tAgentCompositionScopedHostBinding,\n\t\tAgentCompositionInstanceStateBinding\n{\n\tprivate readonly definitions = new Map<string, AgentDefinition<unknown, unknown>>();\n\tprivate readonly instances = new Map<string, AgentInstanceRuntime<unknown, unknown>>();\n\tprivate readonly instanceStateClearers = new Set<(instanceId: string) => void>();\n\tprivate sequence = 0;\n\tprivate readonly nextId: (kind: string) => string;\n\tprivate readonly defaultLeaseOwner?: string;\n\tprivate hostPrimitivesFactory?: AgentHostPrimitivesFactory;\n\tprivate lifecycleDispatcher?: AgentCompositionLifecycleDispatcher;\n\n\tconstructor(options: AgentCompositionRuntimeOptions = {}) {\n\t\tthis.defaultLeaseOwner = options.defaultLeaseOwner;\n\t\tthis.hostPrimitivesFactory = options.hostPrimitivesFactory;\n\t\tthis.nextId = options.idFactory ?? ((kind: string) => `${kind}-${++this.sequence}`);\n\t}\n\n\tsetHostPrimitivesFactory(factory?: AgentHostPrimitivesFactory): void {\n\t\tthis.hostPrimitivesFactory = factory;\n\t}\n\n\tsetLifecycleDispatcher(dispatcher?: AgentCompositionLifecycleDispatcher): void {\n\t\tthis.lifecycleDispatcher = dispatcher;\n\t}\n\n\taddInstanceStateClearer(clearer: (instanceId: string) => void): () => void {\n\t\tthis.instanceStateClearers.add(clearer);\n\t\treturn () => {\n\t\t\tthis.instanceStateClearers.delete(clearer);\n\t\t};\n\t}\n\n\tdisposeDefinitions(definitions: readonly AgentDefinition[]): void {\n\t\tconst owned = new Set(definitions);\n\t\tfor (const [key, definition] of this.definitions) {\n\t\t\tif (owned.has(definition)) this.definitions.delete(key);\n\t\t}\n\t\tfor (const [id, instance] of this.instances) {\n\t\t\tif (!owned.has(instance.definition)) continue;\n\t\t\tthis.instances.delete(id);\n\t\t\tvoid instance.dispose();\n\t\t}\n\t}\n\n\tdefine<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult>,\n\t): AgentDefinition<TInput, TResult> {\n\t\tvalidateAgentDefinition(definition);\n\t\tif (this.definitions.has(this.definitionKey(definition.id, definition.version))) {\n\t\t\tthrow new Error(\n\t\t\t\tt(\"Agent definition already registered: {id}@{version}\", {\n\t\t\t\t\tid: definition.id,\n\t\t\t\t\tversion: definition.version,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst frozen = Object.freeze({ ...definition });\n\t\tthis.definitions.set(\n\t\t\tthis.definitionKey(definition.id, definition.version),\n\t\t\tfrozen as AgentDefinition<unknown, unknown>,\n\t\t);\n\t\treturn frozen;\n\t}\n\n\tget<TInput = unknown, TResult = unknown>(id: string, version: number): AgentDefinition<TInput, TResult> {\n\t\tconst definition = this.definitions.get(this.definitionKey(id, version));\n\t\tif (!definition) throw new Error(t(\"Unknown Agent definition: {id}@{version}\", { id, version }));\n\t\treturn definition as AgentDefinition<TInput, TResult>;\n\t}\n\n\tcreate<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult> | DefinitionRef,\n\t\toptions: { id?: string; parentInstanceId?: string } = {},\n\t): AgentInstance<TInput, TResult> {\n\t\treturn this.createInternal(definition, options, this.hostPrimitivesFactory);\n\t}\n\n\tcreateWithHostPrimitives<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult> | DefinitionRef,\n\t\toptions: { id?: string; parentInstanceId?: string } | undefined,\n\t\thostPrimitivesFactory: AgentHostPrimitivesFactory,\n\t\tlifecycleDispatcher?: AgentCompositionLifecycleDispatcher,\n\t): AgentInstance<TInput, TResult> {\n\t\t// A CapabilityRuntime supplies a complete, session-bound factory for this\n\t\t// plugin invocation. Do not merge the runtime-wide factory here: one\n\t\t// composition runtime may be shared by more than one AgentSession.\n\t\treturn this.createInternal(\n\t\t\tdefinition,\n\t\t\toptions ?? {},\n\t\t\thostPrimitivesFactory,\n\t\t\tlifecycleDispatcher ?? this.lifecycleDispatcher,\n\t\t);\n\t}\n\n\tprivate createInternal<TInput = unknown, TResult = unknown>(\n\t\tdefinition: AgentDefinition<TInput, TResult> | DefinitionRef,\n\t\toptions: { id?: string; parentInstanceId?: string },\n\t\thostPrimitivesFactory: AgentHostPrimitivesFactory | undefined,\n\t\tlifecycleDispatcher: AgentCompositionLifecycleDispatcher | undefined = this.lifecycleDispatcher,\n\t): AgentInstance<TInput, TResult> {\n\t\tif (!definition || typeof definition !== \"object\")\n\t\t\tthrow new Error(t(\"Agent definition or reference is required\"));\n\t\tconst resolved =\n\t\t\t\"run\" in definition\n\t\t\t\t? validateAgentDefinition(definition as AgentDefinition<TInput, TResult>)\n\t\t\t\t: this.get<TInput, TResult>(definition.id, definition.version);\n\t\tif (options.parentInstanceId !== undefined && !this.instances.has(options.parentInstanceId)) {\n\t\t\tthrow new Error(\n\t\t\t\tt(\"Unknown parent Agent instance: {parentInstanceId}\", { parentInstanceId: options.parentInstanceId }),\n\t\t\t);\n\t\t}\n\t\tif (this.instances.has(options.id ?? \"\"))\n\t\t\tthrow new Error(t(\"Agent instance id already exists: {id}\", { id: options.id ?? \"\" }));\n\t\tconst id = options.id ?? this.nextId(\"agent-instance\");\n\t\tif (this.instances.has(id)) throw new Error(t(\"Agent instance id already exists: {id}\", { id }));\n\t\tconst instance = new AgentInstanceRuntime(\n\t\t\tresolved,\n\t\t\tid,\n\t\t\toptions.parentInstanceId,\n\t\t\tthis.nextId,\n\t\t\tthis.defaultLeaseOwner ?? resolved.owner ?? \"agent-composition\",\n\t\t\thostPrimitivesFactory,\n\t\t\tlifecycleDispatcher,\n\t\t\t(instanceId: string) => {\n\t\t\t\tfor (const clearer of this.instanceStateClearers) clearer(instanceId);\n\t\t\t},\n\t\t);\n\t\tthis.instances.set(id, instance as AgentInstanceRuntime<unknown, unknown>);\n\t\treturn instance;\n\t}\n\n\tlistInstances(): readonly AgentInstanceSnapshot[] {\n\t\treturn Object.freeze([...this.instances.values()].map((instance) => instance.snapshot()));\n\t}\n\n\tprivate definitionKey(id: string, version: number): string {\n\t\treturn `${id}@${version}`;\n\t}\n}\n\nexport function createAgentCompositionRuntime(options: AgentCompositionRuntimeOptions = {}): AgentCompositionRuntime {\n\treturn new AgentCompositionRuntime(options);\n}\n"]}

package/dist/core/extensions/agent-composition.js

@@ -1,3 +1,4 @@
+import { t } from "../i18n/index.js";
 const terminalStatuses = new Set(["succeeded", "failed", "cancelled", "disposed"]);
 function abortError(reason) {
     if (reason instanceof Error)
@@ -34,22 +35,22 @@ function freezeSnapshot(snapshot) {
 }
 function validateAgentDefinition(definition) {
     if (!definition || typeof definition !== "object") {
-        throw new Error("Agent definition is required");
+        throw new Error(t("Agent definition is required"));
     }
     if (typeof definition.id !== "string" || !definition.id.trim()) {
-        throw new Error("Agent definition requires a non-empty id");
+        throw new Error(t("Agent definition requires a non-empty id"));
     }
     if (!Number.isSafeInteger(definition.version) || definition.version < 1) {
-        throw new Error("Agent definition version must be a positive safe integer");
+        throw new Error(t("Agent definition version must be a positive safe integer"));
     }
     if (definition.role !== "root-agent-controller" && definition.role !== "child-agent-controller") {
-        throw new Error("Agent definition role must be root-agent-controller or child-agent-controller");
+        throw new Error(t("Agent definition role must be root-agent-controller or child-agent-controller"));
     }
     if (typeof definition.run !== "function") {
-        throw new Error("Agent definition requires a run function");
+        throw new Error(t("Agent definition requires a run function"));
     }
     if (definition.owner !== undefined && (typeof definition.owner !== "string" || !definition.owner.trim())) {
-        throw new Error("Agent definition owner must be a non-empty string when provided");
+        throw new Error(t("Agent definition owner must be a non-empty string when provided"));
     }
     return definition;
 }
@@ -381,7 +382,7 @@ class AgentInstanceRuntime {
     async acquireControllerLease(owner = this.definition.owner ?? this.defaultLeaseOwner) {
         this.assertNotDisposed();
         if (this.activeLease?.isActive())
-            throw new Error(`Agent instance already has an active controller lease: ${this.id}`);
+            throw new Error(t("Agent instance already has an active controller lease: {id}", { id: this.id }));
         const lease = new ControllerLeaseRuntime(this, this.nextId("agent-lease"), owner, this.revisionValue + 1);
         this.activeLease = lease;
         return lease;
@@ -389,12 +390,15 @@ class AgentInstanceRuntime {
     run(input, options = {}) {
         this.assertNotDisposed();
         if (this.statusValue !== "created")
-            throw new Error(`Agent instance cannot run from status ${this.statusValue}: ${this.id}`);
+            throw new Error(t("Agent instance cannot run from status {statusValue}: {id}", {
+                statusValue: this.statusValue,
+                id: this.id,
+            }));
         const lease = this.activeLease;
         if (!lease?.isActive())
-            throw new Error(`Agent instance requires an active controller lease: ${this.id}`);
+            throw new Error(t("Agent instance requires an active controller lease: {id}", { id: this.id }));
         if (options.lease !== lease || !this.isLeaseUsable(options.lease)) {
-            throw new Error(`Agent controller lease is not valid for instance: ${this.id}`);
+            throw new Error(t("Agent controller lease is not valid for instance: {id}", { id: this.id }));
         }
         this.statusValue = "running";
         const controller = new AbortController();
@@ -506,9 +510,9 @@ class AgentInstanceRuntime {
                 });
                 if (raw !== undefined) {
                     if (raw.version !== 1)
-                        throw new Error("Unsupported Agent host primitives version");
+                        throw new Error(t("Unsupported Agent host primitives version"));
                     if (raw.operation && (raw.operation.id !== operation.id || raw.operation.signal !== operation.signal))
-                        throw new Error(`Agent host operation does not match active operation: ${operation.id}`);
+                        throw new Error(t("Agent host operation does not match active operation: {id}", { id: operation.id }));
                     hostScope = createRevocableHostPrimitives({ ...raw, operation: raw.operation ?? createOperationFacade(operation, this.id, () => true) }, operation, instanceSnapshot);
                 }
             }
@@ -565,7 +569,7 @@ class AgentInstanceRuntime {
     }
     assertNotDisposed() {
         if (this.statusValue === "disposed")
-            throw new Error(`Agent instance is disposed: ${this.id}`);
+            throw new Error(t("Agent instance is disposed: {id}", { id: this.id }));
     }
     resolveCompletionOnce(result) {
         if (this.completionResolved)
@@ -730,7 +734,10 @@ export class AgentCompositionRuntime {
     define(definition) {
         validateAgentDefinition(definition);
         if (this.definitions.has(this.definitionKey(definition.id, definition.version))) {
-            throw new Error(`Agent definition already registered: ${definition.id}@${definition.version}`);
+            throw new Error(t("Agent definition already registered: {id}@{version}", {
+                id: definition.id,
+                version: definition.version,
+            }));
         }
         const frozen = Object.freeze({ ...definition });
         this.definitions.set(this.definitionKey(definition.id, definition.version), frozen);
@@ -739,7 +746,7 @@ export class AgentCompositionRuntime {
     get(id, version) {
         const definition = this.definitions.get(this.definitionKey(id, version));
         if (!definition)
-            throw new Error(`Unknown Agent definition: ${id}@${version}`);
+            throw new Error(t("Unknown Agent definition: {id}@{version}", { id, version }));
         return definition;
     }
     create(definition, options = {}) {
@@ -753,18 +760,18 @@ export class AgentCompositionRuntime {
     }
     createInternal(definition, options, hostPrimitivesFactory, lifecycleDispatcher = this.lifecycleDispatcher) {
         if (!definition || typeof definition !== "object")
-            throw new Error("Agent definition or reference is required");
+            throw new Error(t("Agent definition or reference is required"));
         const resolved = "run" in definition
             ? validateAgentDefinition(definition)
             : this.get(definition.id, definition.version);
         if (options.parentInstanceId !== undefined && !this.instances.has(options.parentInstanceId)) {
-            throw new Error(`Unknown parent Agent instance: ${options.parentInstanceId}`);
+            throw new Error(t("Unknown parent Agent instance: {parentInstanceId}", { parentInstanceId: options.parentInstanceId }));
         }
         if (this.instances.has(options.id ?? ""))
-            throw new Error(`Agent instance id already exists: ${options.id}`);
+            throw new Error(t("Agent instance id already exists: {id}", { id: options.id ?? "" }));
         const id = options.id ?? this.nextId("agent-instance");
         if (this.instances.has(id))
-            throw new Error(`Agent instance id already exists: ${id}`);
+            throw new Error(t("Agent instance id already exists: {id}", { id }));
         const instance = new AgentInstanceRuntime(resolved, id, options.parentInstanceId, this.nextId, this.defaultLeaseOwner ?? resolved.owner ?? "agent-composition", hostPrimitivesFactory, lifecycleDispatcher, (instanceId) => {
             for (const clearer of this.instanceStateClearers)
                 clearer(instanceId);