@ai-agent-forge/agent-forge 0.85.0

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

@@ -0,0 +1,785 @@
+const terminalStatuses = new Set(["succeeded", "failed", "cancelled", "disposed"]);
+function abortError(reason) {
+    if (reason instanceof Error)
+        return reason;
+    const error = new Error(reason === undefined ? "Agent operation cancelled" : String(reason));
+    error.name = "AbortError";
+    return error;
+}
+function combinedAbortSignal(...signals) {
+    const controller = new AbortController();
+    const listeners = [];
+    for (const signal of new Set(signals.filter((signal) => signal !== undefined))) {
+        const abort = () => {
+            if (!controller.signal.aborted)
+                controller.abort(signal.reason);
+        };
+        if (signal.aborted) {
+            abort();
+            break;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+        listeners.push({ signal, listener: abort });
+    }
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            for (const { signal, listener } of listeners)
+                signal.removeEventListener("abort", listener);
+        },
+    };
+}
+function freezeSnapshot(snapshot) {
+    return Object.freeze({ ...snapshot });
+}
+function validateAgentDefinition(definition) {
+    if (!definition || typeof definition !== "object") {
+        throw new Error("Agent definition is required");
+    }
+    if (typeof definition.id !== "string" || !definition.id.trim()) {
+        throw new Error("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");
+    }
+    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");
+    }
+    if (typeof definition.run !== "function") {
+        throw new Error("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");
+    }
+    return definition;
+}
+function detachedFreeze(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (value instanceof Uint8Array)
+        return new Uint8Array(value);
+    const existing = seen.get(value);
+    if (existing)
+        return existing;
+    const result = Array.isArray(value) ? [] : {};
+    seen.set(value, result);
+    for (const [key, item] of Object.entries(value)) {
+        result[key] = detachedFreeze(item, seen);
+    }
+    return Object.freeze(result);
+}
+function disposable(dispose) {
+    let disposed = false;
+    return {
+        id: "agent-host-registration",
+        kind: "agent-host",
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            return dispose();
+        },
+    };
+}
+function revokedError(instanceId) {
+    return new Error(`Agent host primitives are revoked: ${instanceId}`);
+}
+function createOperationFacade(operation, instanceId, active) {
+    return Object.freeze({
+        version: 1,
+        id: operation.id,
+        signal: operation.signal,
+        status: () => {
+            if (!active())
+                return "cancelled";
+            return operation.status();
+        },
+        isActive: () => active() && operation.status() === "running",
+        reportProgress: (progress) => active() && operation.reportProgress(progress),
+        onCancel: (handler) => {
+            if (!active())
+                throw revokedError(instanceId);
+            const listener = () => {
+                void handler(operation.signal.reason);
+            };
+            operation.signal.addEventListener("abort", listener, { once: true });
+            return disposable(() => operation.signal.removeEventListener("abort", listener));
+        },
+        cancel: async (reason) => {
+            if (!active())
+                throw revokedError(instanceId);
+            await operation.cancel(reason);
+        },
+    });
+}
+function createRevocableHostPrimitives(raw, operation, instance) {
+    let active = true;
+    const cleanups = [];
+    const track = (registration) => {
+        let released = false;
+        const dispose = async () => {
+            if (released)
+                return;
+            released = true;
+            const index = cleanups.indexOf(cleanup);
+            if (index >= 0)
+                cleanups.splice(index, 1);
+            await registration.dispose();
+        };
+        const cleanup = dispose;
+        cleanups.push(cleanup);
+        return {
+            id: registration.id,
+            kind: registration.kind,
+            dispose,
+        };
+    };
+    const assertActive = () => {
+        if (!active)
+            throw revokedError(instance.id);
+        if (operation.signal.aborted)
+            throw abortError(operation.signal.reason);
+    };
+    const session = raw.session
+        ? Object.freeze({
+            version: 1,
+            getSessionId: () => {
+                assertActive();
+                return raw.session.getSessionId();
+            },
+            getRevision: raw.session.getRevision
+                ? () => {
+                    assertActive();
+                    return detachedFreeze(raw.session.getRevision());
+                }
+                : undefined,
+            getMessages: () => {
+                assertActive();
+                return detachedFreeze(raw.session.getMessages());
+            },
+            getBranchEntries: () => {
+                assertActive();
+                return detachedFreeze(raw.session.getBranchEntries());
+            },
+            isIdle: () => {
+                assertActive();
+                return raw.session.isIdle();
+            },
+            waitForIdle: async () => {
+                assertActive();
+                await raw.session.waitForIdle();
+                assertActive();
+            },
+            appendEntry: (customType, data) => {
+                assertActive();
+                return raw.session.appendEntry(customType, detachedFreeze(data));
+            },
+        })
+        : undefined;
+    const context = raw.context
+        ? Object.freeze({
+            version: 1,
+            get: () => {
+                assertActive();
+                return detachedFreeze(raw.context.get());
+            },
+            commit: async (request) => {
+                assertActive();
+                if (request.signal?.aborted)
+                    throw abortError(request.signal.reason);
+                const result = await raw.context.commit({
+                    ...request,
+                    value: detachedFreeze(request.value),
+                });
+                assertActive();
+                return detachedFreeze(result);
+            },
+        })
+        : undefined;
+    // One guarded StateAPI facade shared by the owner namespace and the
+    // instance-private namespace: same revocation gating and detached snapshots.
+    const guardedStateFacade = (source) => Object.freeze({
+        get: (key) => {
+            assertActive();
+            return detachedFreeze(source.get(key));
+        },
+        set: (key, value, options) => {
+            assertActive();
+            return source.set(key, detachedFreeze(value), options);
+        },
+        delete: (key, options) => {
+            assertActive();
+            return source.delete(key, options);
+        },
+        list: (prefix) => {
+            assertActive();
+            return detachedFreeze(source.list(prefix));
+        },
+        watch: (prefix, handler) => {
+            assertActive();
+            return track(source.watch(prefix, (change) => {
+                if (!active || operation.signal.aborted)
+                    return;
+                void handler(detachedFreeze(change));
+            }));
+        },
+    });
+    const state = raw.state ? guardedStateFacade(raw.state) : undefined;
+    const instanceState = raw.instanceState ? guardedStateFacade(raw.instanceState) : undefined;
+    const artifact = raw.artifact
+        ? Object.freeze({
+            put: async (input, options) => {
+                assertActive();
+                const data = input.data instanceof Uint8Array ? new Uint8Array(input.data) : input.data;
+                const abort = combinedAbortSignal(operation.signal, options?.signal);
+                try {
+                    const ref = await raw.artifact.put({ ...input, data }, { ...options, signal: abort.signal });
+                    assertActive();
+                    return detachedFreeze(ref);
+                }
+                finally {
+                    abort.dispose();
+                }
+            },
+            stat: async (ref) => {
+                assertActive();
+                const result = await raw.artifact.stat(detachedFreeze(ref));
+                assertActive();
+                return detachedFreeze(result);
+            },
+            read: async (ref, options) => {
+                assertActive();
+                const chunk = await raw.artifact.read(detachedFreeze(ref), options);
+                assertActive();
+                return detachedFreeze({
+                    ...chunk,
+                    data: new Uint8Array(chunk.data),
+                });
+            },
+        })
+        : undefined;
+    const operationFacade = raw.operation
+        ? Object.freeze({
+            version: 1,
+            id: raw.operation.id,
+            signal: raw.operation.signal,
+            status: () => {
+                assertActive();
+                return raw.operation.status();
+            },
+            isActive: () => active && raw.operation.isActive(),
+            reportProgress: (progress) => {
+                assertActive();
+                return raw.operation.reportProgress(progress);
+            },
+            onCancel: (handler) => {
+                assertActive();
+                return track(raw.operation.onCancel(handler));
+            },
+            cancel: async (reason) => {
+                assertActive();
+                await raw.operation.cancel(reason);
+            },
+        })
+        : createOperationFacade(operation, instance.id, () => active);
+    const value = Object.freeze({
+        version: 1,
+        ...(session ? { session } : {}),
+        ...(context ? { context } : {}),
+        ...(state ? { state } : {}),
+        ...(instanceState ? { instanceState } : {}),
+        ...(artifact ? { artifact } : {}),
+        ...(operationFacade ? { operation: operationFacade } : {}),
+        ...(raw.model
+            ? {
+                model: Object.freeze({
+                    version: 1,
+                    get facts() {
+                        assertActive();
+                        return raw.model.facts;
+                    },
+                    invocation: {
+                        invoke: async (input, signal) => {
+                            assertActive();
+                            const result = await raw.model.invocation.invoke(input, signal);
+                            assertActive();
+                            return result;
+                        },
+                    },
+                }),
+            }
+            : {}),
+        ...(raw.tool
+            ? {
+                tool: Object.freeze({
+                    version: 1,
+                    listTools: () => {
+                        assertActive();
+                        return raw.tool.listTools();
+                    },
+                    invokeTool: (name, input, invokeOptions) => {
+                        assertActive();
+                        return raw.tool.invokeTool(name, input, invokeOptions);
+                    },
+                }),
+            }
+            : {}),
+    });
+    return {
+        value,
+        revoke: () => {
+            if (!active)
+                return;
+            active = false;
+            for (const cleanup of [...cleanups])
+                void cleanup();
+        },
+    };
+}
+class AgentInstanceRuntime {
+    id;
+    definition;
+    statusValue = "created";
+    revisionValue = 0;
+    activeLease;
+    activeOperation;
+    activeExecution;
+    completion;
+    resolveCompletion;
+    completionResolved = false;
+    parentInstanceId;
+    nextId;
+    defaultLeaseOwner;
+    hostPrimitivesFactory;
+    lifecycleDispatcher;
+    clearInstanceState;
+    constructor(definition, id, parentInstanceId, nextId, defaultLeaseOwner, hostPrimitivesFactory, lifecycleDispatcher, clearInstanceState) {
+        this.id = id;
+        this.definition = definition;
+        this.parentInstanceId = parentInstanceId;
+        this.nextId = nextId;
+        this.defaultLeaseOwner = defaultLeaseOwner;
+        this.hostPrimitivesFactory = hostPrimitivesFactory;
+        this.lifecycleDispatcher = lifecycleDispatcher;
+        this.clearInstanceState = clearInstanceState;
+        this.completion = new Promise((resolve) => {
+            this.resolveCompletion = resolve;
+        });
+    }
+    snapshot() {
+        return freezeSnapshot({
+            id: this.id,
+            definitionId: this.definition.id,
+            definitionVersion: this.definition.version,
+            role: this.definition.role,
+            ...(this.parentInstanceId ? { parentInstanceId: this.parentInstanceId } : {}),
+            status: this.statusValue,
+            revision: this.revisionValue,
+            ...(this.activeLease?.isActive() ? { leaseOwner: this.activeLease.owner } : {}),
+        });
+    }
+    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}`);
+        const lease = new ControllerLeaseRuntime(this, this.nextId("agent-lease"), owner, this.revisionValue + 1);
+        this.activeLease = lease;
+        return lease;
+    }
+    run(input, options = {}) {
+        this.assertNotDisposed();
+        if (this.statusValue !== "created")
+            throw new Error(`Agent instance cannot run from status ${this.statusValue}: ${this.id}`);
+        const lease = this.activeLease;
+        if (!lease?.isActive())
+            throw new Error(`Agent instance requires an active controller lease: ${this.id}`);
+        if (options.lease !== lease || !this.isLeaseUsable(options.lease)) {
+            throw new Error(`Agent controller lease is not valid for instance: ${this.id}`);
+        }
+        this.statusValue = "running";
+        const controller = new AbortController();
+        const externalSignal = options.signal;
+        let externalAbortListener;
+        if (externalSignal) {
+            externalAbortListener = () => {
+                controller.abort(externalSignal.reason);
+                void this.cancel(externalSignal.reason === undefined ? undefined : String(externalSignal.reason));
+            };
+            if (!externalSignal.aborted)
+                externalSignal.addEventListener("abort", externalAbortListener, { once: true });
+        }
+        let operation;
+        operation = new OperationRuntime(this.nextId("agent-operation"), controller, () => this.cancel(controller.signal.reason), (progress, step) => this.reportLifecycle("step", operation, undefined, progress, step));
+        this.activeOperation = operation;
+        if (externalSignal?.aborted) {
+            controller.abort(externalSignal.reason);
+        }
+        else {
+            this.reportLifecycle("start", operation);
+        }
+        this.activeExecution = this.execute(input, lease, operation, externalSignal, externalAbortListener);
+        if (externalSignal?.aborted) {
+            // Trigger cancellation only after the execution is tracked, so the
+            // pre-aborted path drains like every other cancellation path instead
+            // of resolving completion ahead of the execution body.
+            void this.cancel(externalSignal.reason === undefined ? undefined : String(externalSignal.reason));
+        }
+        return operation;
+    }
+    async wait() {
+        return this.completion;
+    }
+    async cancel(reason) {
+        if (this.statusValue === "disposed" || terminalStatuses.has(this.statusValue))
+            return;
+        this.statusValue = "cancelled";
+        this.revisionValue += 1;
+        const operation = this.activeOperation;
+        if (operation) {
+            this.reportLifecycle("cancel", operation);
+            this.reportLifecycle("end", operation, "cancelled");
+            operation.cancelFromInstance(reason);
+        }
+        // The run body must eventually observe the abort signal: cancellation only
+        // settles after the execution drained, so wait() and lease disposal never
+        // race side effects still in flight. There is deliberately no timeout. A run
+        // body that awaits this cancel(), dispose(), or its own lease release
+        // self-deadlocks by contract.
+        await this.drainExecution();
+        this.resolveCompletionOnce({ status: "cancelled", revision: this.revisionValue, error: abortError(reason) });
+    }
+    async dispose() {
+        if (this.statusValue === "disposed")
+            return;
+        if (this.statusValue === "created") {
+            await this.activeLease?.release();
+            this.statusValue = "disposed";
+            this.revisionValue += 1;
+            this.clearInstanceState?.(this.id);
+            this.resolveCompletionOnce({ status: "disposed", revision: this.revisionValue });
+            return;
+        }
+        if (!terminalStatuses.has(this.statusValue))
+            await this.cancel("Agent instance disposed");
+        // A concurrent cancel() may still be draining; release the lease only after
+        // the execution has settled.
+        await this.drainExecution();
+        await this.activeLease?.release();
+        this.statusValue = "disposed";
+        this.revisionValue += 1;
+        // The instance-private state namespace (and its watchers) dies with the
+        // instance, after every drain the run body could still rely on.
+        this.clearInstanceState?.(this.id);
+        this.resolveCompletionOnce({ status: "disposed", revision: this.revisionValue });
+    }
+    async deactivateLease(lease) {
+        if (this.activeLease !== lease)
+            return;
+        this.activeLease = undefined;
+        if (this.statusValue === "running") {
+            await this.cancel("Controller lease released");
+            return;
+        }
+        // A cancel() from another path may still be draining the execution.
+        await this.drainExecution();
+    }
+    isLeaseUsable(lease) {
+        return (lease instanceof ControllerLeaseRuntime &&
+            lease.instanceId === this.id &&
+            lease.isActive() &&
+            this.activeLease === lease);
+    }
+    async execute(input, lease, operation, externalSignal, externalAbortListener) {
+        const instanceSnapshot = this.snapshot();
+        let hostScope;
+        const revokeHost = () => hostScope?.revoke();
+        operation.signal.addEventListener("abort", revokeHost, { once: true });
+        try {
+            if (operation.signal.aborted)
+                throw abortError(operation.signal.reason);
+            if (this.hostPrimitivesFactory) {
+                const raw = await this.hostPrimitivesFactory({
+                    instance: instanceSnapshot,
+                    operationId: operation.id,
+                    signal: operation.signal,
+                    leaseOwner: lease.owner,
+                });
+                if (raw !== undefined) {
+                    if (raw.version !== 1)
+                        throw new Error("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}`);
+                    hostScope = createRevocableHostPrimitives({ ...raw, operation: raw.operation ?? createOperationFacade(operation, this.id, () => true) }, operation, instanceSnapshot);
+                }
+            }
+            if (operation.signal.aborted)
+                throw abortError(operation.signal.reason);
+            const context = Object.freeze({
+                instance: instanceSnapshot,
+                signal: operation.signal,
+                inputRevision: this.revisionValue,
+                ...(hostScope ? { host: hostScope.value } : {}),
+            });
+            const output = await this.definition.run(input, context);
+            if (operation.signal.aborted || !this.isLeaseUsable(lease) || this.statusValue !== "running")
+                return;
+            this.statusValue = "succeeded";
+            this.revisionValue += 1;
+            operation.resolve(output);
+            this.reportLifecycle("end", operation, "succeeded");
+            this.resolveCompletionOnce({ status: "succeeded", revision: this.revisionValue, output });
+        }
+        catch (error) {
+            if (operation.signal.aborted || this.statusValue === "cancelled" || this.statusValue === "disposed") {
+                // Instance-level cancellation marks the handle cancelled before this
+                // catch runs; the pre-aborted run() path gets here first, so settle
+                // the handle as cancelled instead of failed.
+                operation.cancelFromInstance(operation.signal.reason);
+                return;
+            }
+            this.statusValue = "failed";
+            this.revisionValue += 1;
+            operation.reject(error);
+            this.reportLifecycle("end", operation, "failed");
+            this.resolveCompletionOnce({ status: "failed", revision: this.revisionValue, error });
+        }
+        finally {
+            hostScope?.revoke();
+            operation.signal.removeEventListener("abort", revokeHost);
+            if (externalSignal && externalAbortListener)
+                externalSignal.removeEventListener("abort", externalAbortListener);
+            if (this.activeOperation === operation)
+                this.activeOperation = undefined;
+            // run() requires status "created", so at most one execution ever exists
+            // per instance and clearing the field unconditionally is safe.
+            this.activeExecution = undefined;
+        }
+    }
+    async drainExecution() {
+        // Capture the reference before awaiting: execute()'s finally clears the
+        // field while drainers still need the promise.
+        const execution = this.activeExecution;
+        if (!execution)
+            return;
+        await execution;
+    }
+    assertNotDisposed() {
+        if (this.statusValue === "disposed")
+            throw new Error(`Agent instance is disposed: ${this.id}`);
+    }
+    resolveCompletionOnce(result) {
+        if (this.completionResolved)
+            return;
+        this.completionResolved = true;
+        this.resolveCompletion(result);
+    }
+    reportLifecycle(event, operation, status, progress, step) {
+        if (!this.lifecycleDispatcher)
+            return;
+        try {
+            this.lifecycleDispatcher({
+                event,
+                operationId: operation.id,
+                operationKind: `agent:${this.definition.id}@${this.definition.version}`,
+                ...(this.definition.owner === undefined ? {} : { owner: this.definition.owner }),
+                ...(status === undefined ? {} : { status }),
+                ...(progress === undefined ? {} : { progress }),
+                ...(step === undefined ? {} : { step }),
+            });
+        }
+        catch {
+            // Lifecycle delivery is observational and must not affect the operation.
+        }
+    }
+}
+class ControllerLeaseRuntime {
+    active = true;
+    instance;
+    id;
+    owner;
+    revision;
+    constructor(instance, id, owner, revision) {
+        this.instance = instance;
+        this.id = id;
+        this.owner = owner;
+        this.revision = revision;
+    }
+    get instanceId() {
+        return this.instance.id;
+    }
+    isActive() {
+        return this.active;
+    }
+    async release() {
+        if (!this.active)
+            return;
+        this.active = false;
+        await this.instance.deactivateLease(this);
+    }
+}
+class OperationRuntime {
+    statusValue = "queued";
+    resolveResult;
+    rejectResult;
+    result;
+    id;
+    controller;
+    cancelCallback;
+    reportProgressCallback;
+    progressSequence = 0;
+    constructor(id, controller, cancelCallback, reportProgress) {
+        this.id = id;
+        this.controller = controller;
+        this.cancelCallback = cancelCallback;
+        this.reportProgressCallback = reportProgress;
+        this.signal = controller.signal;
+        this.result = new Promise((resolve, reject) => {
+            this.resolveResult = resolve;
+            this.rejectResult = reject;
+        });
+        this.statusValue = "running";
+    }
+    signal;
+    status() {
+        return this.statusValue;
+    }
+    reportProgress(progress) {
+        if (this.statusValue !== "running" || this.signal.aborted)
+            return false;
+        this.reportProgressCallback(progress, ++this.progressSequence);
+        return true;
+    }
+    async cancel(reason) {
+        if (this.statusValue === "succeeded" || this.statusValue === "failed" || this.statusValue === "cancelled")
+            return;
+        this.controller.abort(reason);
+        // The handle must settle cancellation without waiting for an uncooperative
+        // run body. AgentInstanceRuntime.cancel() still drains the body when the
+        // caller explicitly cancels/releases the instance, but OperationHandle is
+        // the non-blocking public fence used by callers that cannot coordinate the
+        // plugin's private awaits. The callback synchronously marks the operation
+        // cancelled before its first await; any later drain is best-effort here.
+        try {
+            void this.cancelCallback().catch(() => undefined);
+        }
+        catch {
+            // A cancellation request is already reflected by this operation's
+            // aborted signal and terminal status; callback failures must not turn
+            // cancel() into an unbounded or rejected wait.
+        }
+    }
+    cancelFromInstance(reason) {
+        if (this.statusValue === "succeeded" || this.statusValue === "failed" || this.statusValue === "cancelled")
+            return;
+        this.statusValue = "cancelled";
+        this.controller.abort(reason);
+        this.rejectResult(abortError(reason));
+    }
+    resolve(value) {
+        if (this.statusValue === "cancelled" || this.statusValue === "failed")
+            return;
+        this.statusValue = "succeeded";
+        this.resolveResult(value);
+    }
+    reject(error) {
+        if (this.statusValue === "cancelled")
+            return;
+        this.statusValue = "failed";
+        this.rejectResult(error);
+    }
+}
+export class AgentCompositionRuntime {
+    definitions = new Map();
+    instances = new Map();
+    instanceStateClearers = new Set();
+    sequence = 0;
+    nextId;
+    defaultLeaseOwner;
+    hostPrimitivesFactory;
+    lifecycleDispatcher;
+    constructor(options = {}) {
+        this.defaultLeaseOwner = options.defaultLeaseOwner;
+        this.hostPrimitivesFactory = options.hostPrimitivesFactory;
+        this.nextId = options.idFactory ?? ((kind) => `${kind}-${++this.sequence}`);
+    }
+    setHostPrimitivesFactory(factory) {
+        this.hostPrimitivesFactory = factory;
+    }
+    setLifecycleDispatcher(dispatcher) {
+        this.lifecycleDispatcher = dispatcher;
+    }
+    addInstanceStateClearer(clearer) {
+        this.instanceStateClearers.add(clearer);
+        return () => {
+            this.instanceStateClearers.delete(clearer);
+        };
+    }
+    disposeDefinitions(definitions) {
+        const owned = new Set(definitions);
+        for (const [key, definition] of this.definitions) {
+            if (owned.has(definition))
+                this.definitions.delete(key);
+        }
+        for (const [id, instance] of this.instances) {
+            if (!owned.has(instance.definition))
+                continue;
+            this.instances.delete(id);
+            void instance.dispose();
+        }
+    }
+    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}`);
+        }
+        const frozen = Object.freeze({ ...definition });
+        this.definitions.set(this.definitionKey(definition.id, definition.version), frozen);
+        return frozen;
+    }
+    get(id, version) {
+        const definition = this.definitions.get(this.definitionKey(id, version));
+        if (!definition)
+            throw new Error(`Unknown Agent definition: ${id}@${version}`);
+        return definition;
+    }
+    create(definition, options = {}) {
+        return this.createInternal(definition, options, this.hostPrimitivesFactory);
+    }
+    createWithHostPrimitives(definition, options, hostPrimitivesFactory, lifecycleDispatcher) {
+        // A CapabilityRuntime supplies a complete, session-bound factory for this
+        // plugin invocation. Do not merge the runtime-wide factory here: one
+        // composition runtime may be shared by more than one AgentSession.
+        return this.createInternal(definition, options ?? {}, hostPrimitivesFactory, lifecycleDispatcher ?? this.lifecycleDispatcher);
+    }
+    createInternal(definition, options, hostPrimitivesFactory, lifecycleDispatcher = this.lifecycleDispatcher) {
+        if (!definition || typeof definition !== "object")
+            throw new Error("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}`);
+        }
+        if (this.instances.has(options.id ?? ""))
+            throw new Error(`Agent instance id already exists: ${options.id}`);
+        const id = options.id ?? this.nextId("agent-instance");
+        if (this.instances.has(id))
+            throw new Error(`Agent instance id already exists: ${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);
+        });
+        this.instances.set(id, instance);
+        return instance;
+    }
+    listInstances() {
+        return Object.freeze([...this.instances.values()].map((instance) => instance.snapshot()));
+    }
+    definitionKey(id, version) {
+        return `${id}@${version}`;
+    }
+}
+export function createAgentCompositionRuntime(options = {}) {
+    return new AgentCompositionRuntime(options);
+}
+//# sourceMappingURL=agent-composition.js.map