@ai-agent-forge/agent-forge 0.85.0

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

@@ -0,0 +1,800 @@
+import { SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES } from "@agent-forge/protocol/subagent";
+import { cancellationError } from "./capability-runtime-operation.js";
+import { definitionSnapshot, detachedSnapshot } from "./capability-runtime-snapshot.js";
+import { validateCredentialRequest, validateInteractionNotifyRequest, validateInteractionRequest, validateInteractionTimeoutMs, } from "./capability-runtime-validation.js";
+import { createDisposableRegistration, } from "./public-api.js";
+export function guardedSession(session, assertUsable, options) {
+    const detachedExportArtifact = (artifact) => ({
+        ...detachedSnapshot(artifact),
+        bytes: new Uint8Array(artifact.bytes),
+    });
+    const exportArtifact = session.exportArtifact;
+    const getRevision = session.getRevision;
+    const setSessionName = session.setSessionName;
+    const getSessionName = session.getSessionName;
+    const setLabel = session.setLabel;
+    const getLabel = session.getLabel;
+    const getActiveTools = session.getActiveTools;
+    const setActiveTools = session.setActiveTools;
+    const getAllTools = session.getAllTools;
+    const getCommands = session.getCommands;
+    const getModel = session.getModel;
+    const getScopedModels = session.getScopedModels;
+    const getThinkingLevel = session.getThinkingLevel;
+    const setThinkingLevel = session.setThinkingLevel;
+    const setModel = session.setModel;
+    const getSystemPrompt = session.getSystemPrompt;
+    const getSystemPromptOptions = session.getSystemPromptOptions;
+    const getContextUsage = session.getContextUsage;
+    const steer = session.steer;
+    const queueFollowUp = session.queueFollowUp;
+    const sendMessage = session.sendMessage;
+    return {
+        getSessionId: () => {
+            assertUsable();
+            return session.getSessionId();
+        },
+        ...(options.allowRevision && getRevision
+            ? {
+                getRevision: () => {
+                    assertUsable();
+                    return detachedSnapshot(getRevision());
+                },
+            }
+            : {}),
+        getMessages: () => {
+            assertUsable();
+            return detachedSnapshot(session.getMessages());
+        },
+        isIdle: () => {
+            assertUsable();
+            return session.isIdle();
+        },
+        prompt: async (text) => {
+            assertUsable();
+            return session.prompt(text);
+        },
+        abort: async () => {
+            assertUsable();
+            await session.abort();
+        },
+        waitForIdle: async () => {
+            assertUsable();
+            await session.waitForIdle();
+        },
+        ...(session.compact
+            ? {
+                compact: async (customInstructions) => {
+                    assertUsable();
+                    return session.compact?.(customInstructions);
+                },
+            }
+            : {}),
+        ...(session.navigateTree
+            ? {
+                navigateTree: async (targetId, options) => {
+                    assertUsable();
+                    return session.navigateTree?.(targetId, options);
+                },
+            }
+            : {}),
+        appendEntry: (customType, data) => {
+            assertUsable();
+            return session.appendEntry(customType, data);
+        },
+        ...(setSessionName
+            ? {
+                setSessionName: (name) => {
+                    assertUsable();
+                    setSessionName(name);
+                },
+            }
+            : {}),
+        ...(getSessionName
+            ? {
+                getSessionName: () => {
+                    assertUsable();
+                    return getSessionName();
+                },
+            }
+            : {}),
+        ...(setLabel
+            ? {
+                setLabel: (entryId, label) => {
+                    assertUsable();
+                    return setLabel(entryId, label);
+                },
+            }
+            : {}),
+        ...(getLabel
+            ? {
+                getLabel: (entryId) => {
+                    assertUsable();
+                    return getLabel(entryId);
+                },
+            }
+            : {}),
+        ...(getActiveTools
+            ? {
+                getActiveTools: () => {
+                    assertUsable();
+                    return getActiveTools();
+                },
+            }
+            : {}),
+        ...(setActiveTools
+            ? {
+                setActiveTools: (toolNames) => {
+                    assertUsable();
+                    setActiveTools(toolNames);
+                },
+            }
+            : {}),
+        // Tool parameters are TypeBox schemas carrying symbol values; detachedSnapshot's
+        // structuredClone would throw DataCloneError, so the definition snapshot keeps
+        // symbol values by reference instead.
+        ...(getAllTools
+            ? {
+                getAllTools: () => {
+                    assertUsable();
+                    return definitionSnapshot(getAllTools());
+                },
+            }
+            : {}),
+        ...(getCommands
+            ? {
+                getCommands: () => {
+                    assertUsable();
+                    return detachedSnapshot(getCommands());
+                },
+            }
+            : {}),
+        // Model facts are plain data; detachedSnapshot's structuredClone is safe here.
+        ...(getModel
+            ? {
+                getModel: () => {
+                    assertUsable();
+                    return detachedSnapshot(getModel());
+                },
+            }
+            : {}),
+        ...(getScopedModels
+            ? {
+                getScopedModels: () => {
+                    assertUsable();
+                    return detachedSnapshot(getScopedModels());
+                },
+            }
+            : {}),
+        ...(getThinkingLevel
+            ? {
+                getThinkingLevel: () => {
+                    assertUsable();
+                    return getThinkingLevel();
+                },
+            }
+            : {}),
+        ...(setThinkingLevel
+            ? {
+                setThinkingLevel: (level) => {
+                    assertUsable();
+                    setThinkingLevel(level);
+                },
+            }
+            : {}),
+        ...(setModel
+            ? {
+                setModel: async (modelId) => {
+                    assertUsable();
+                    return setModel(modelId);
+                },
+            }
+            : {}),
+        ...(getSystemPrompt
+            ? {
+                getSystemPrompt: () => {
+                    assertUsable();
+                    return getSystemPrompt();
+                },
+            }
+            : {}),
+        ...(getSystemPromptOptions
+            ? {
+                getSystemPromptOptions: () => {
+                    assertUsable();
+                    return detachedSnapshot(getSystemPromptOptions());
+                },
+            }
+            : {}),
+        // ContextUsage 是纯数值投影事实；detachedSnapshot 让插件拿到的是冻结副本。
+        ...(getContextUsage
+            ? {
+                getContextUsage: () => {
+                    assertUsable();
+                    return detachedSnapshot(getContextUsage());
+                },
+            }
+            : {}),
+        ...(steer
+            ? {
+                steer: async (text) => {
+                    assertUsable();
+                    await steer(text);
+                },
+            }
+            : {}),
+        ...(queueFollowUp
+            ? {
+                queueFollowUp: async (text) => {
+                    assertUsable();
+                    await queueFollowUp(text);
+                },
+            }
+            : {}),
+        // 逐字转发宿主 sendCustomMessage：不在此层发明校验或默认值。
+        ...(sendMessage
+            ? {
+                sendMessage: async (message, options) => {
+                    assertUsable();
+                    await sendMessage(message, options);
+                },
+            }
+            : {}),
+        getBranchEntries: () => {
+            assertUsable();
+            return detachedSnapshot(session.getBranchEntries());
+        },
+        ...(options.allowExport && exportArtifact
+            ? {
+                exportArtifact: (request) => {
+                    assertUsable();
+                    return detachedExportArtifact(exportArtifact(request));
+                },
+            }
+            : {}),
+    };
+}
+export function guardedCredentials(credentials, assertUsable) {
+    return {
+        resolve: async (request) => {
+            assertUsable();
+            validateCredentialRequest(request);
+            const result = await credentials.resolve(request);
+            assertUsable();
+            return result === undefined ? undefined : detachedSnapshot(result);
+        },
+    };
+}
+/**
+ * Allowed host-resolved outcome shapes by status, per the frozen 1A.8
+ * semantics of {@link InteractionOutcomeV1}.
+ */
+const HOST_INTERACTION_OUTCOME_KEYS = new Map([
+    ["delivered", ["status"]],
+    ["answered", ["status", "value"]],
+    ["cancelled", ["status"]],
+    ["timeout", ["status"]],
+    ["unavailable", ["status"]],
+]);
+/**
+ * Validate a host-resolved interaction outcome before it crosses the plugin
+ * boundary. The host side is app-owned, so a malformed result is a host bug:
+ * it rejects the pending request() instead of silently passing broken data to
+ * the plugin (previously any host-resolved value was accepted verbatim).
+ * Beyond shape, the frozen production conditions are enforced: `timeout` is
+ * only ever produced by `options.timeoutMs` (never by a host), and
+ * `delivered` is only valid for notify-kind requests.
+ */
+function validateHostInteractionOutcome(outcome, requestKind) {
+    if (!outcome || typeof outcome !== "object" || Array.isArray(outcome)) {
+        throw new Error("Interaction prompt outcome must be an object");
+    }
+    const record = outcome;
+    const status = record.status;
+    if (typeof status !== "string" || !HOST_INTERACTION_OUTCOME_KEYS.has(status)) {
+        throw new Error(`Interaction prompt outcome has an unknown status: ${String(status)}`);
+    }
+    if (status === "timeout") {
+        throw new Error("Interaction prompt outcome timeout can only be produced by options.timeoutMs, never by the host");
+    }
+    if (status === "delivered" && requestKind !== "notify") {
+        throw new Error("Interaction prompt outcome delivered is only valid for notify requests");
+    }
+    const expectedKeys = HOST_INTERACTION_OUTCOME_KEYS.get(status) ?? [];
+    const unexpected = Object.keys(record).filter((key) => !expectedKeys.includes(key));
+    if (unexpected.length > 0) {
+        throw new Error(`Interaction prompt outcome has unsupported fields: ${unexpected.join(", ")}`);
+    }
+    if (status === "answered" && typeof record.value !== "boolean" && typeof record.value !== "string") {
+        throw new Error("Interaction prompt outcome answered requires a boolean or string value");
+    }
+}
+/**
+ * Guard the host interaction surface for one plugin API. Requests and outcomes
+ * cross the boundary as detached, deep-frozen snapshots, and every pending
+ * request settles as "cancelled" when the wrapper's registration is disposed.
+ * Cancellation is per request: `options.signal` aborts (and `timeoutMs`
+ * expires) only the request that declared it — concurrent requests of the same
+ * plugin are independent. Owner-level teardown (registration dispose) is the
+ * only path that cancels all in-flight requests.
+ */
+export function guardedInteraction(interaction, owner, assertUsable, own) {
+    const pendingControllers = new Set();
+    own(createDisposableRegistration("interaction", () => {
+        for (const controller of pendingControllers)
+            controller.abort();
+        pendingControllers.clear();
+        return interaction.dispose?.();
+    }, `registration:${owner}:interaction`));
+    return {
+        notify: (request) => {
+            assertUsable();
+            validateInteractionNotifyRequest(request);
+            interaction.notify(detachedSnapshot(request));
+        },
+        request: (request, options) => {
+            assertUsable();
+            validateInteractionRequest(request);
+            validateInteractionTimeoutMs(options?.timeoutMs);
+            const externalSignal = options?.signal;
+            if (externalSignal?.aborted)
+                return Promise.resolve({ status: "cancelled" });
+            const hostRequest = detachedSnapshot(request);
+            const controller = new AbortController();
+            pendingControllers.add(controller);
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                let timeoutId;
+                const onExternalAbort = () => {
+                    // Settle first so the internal-abort listener below cannot win the
+                    // race with "cancelled"; then propagate the abort so the host can
+                    // dismiss its dialog per its ctx.signal contract.
+                    settle({ status: "cancelled" });
+                    controller.abort();
+                };
+                const onInternalAbort = () => settle({ status: "cancelled" });
+                const cleanup = () => {
+                    if (timeoutId !== undefined)
+                        clearTimeout(timeoutId);
+                    externalSignal?.removeEventListener("abort", onExternalAbort);
+                    controller.signal.removeEventListener("abort", onInternalAbort);
+                    pendingControllers.delete(controller);
+                };
+                const settle = (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve(outcome);
+                };
+                externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
+                controller.signal.addEventListener("abort", onInternalAbort, { once: true });
+                if (options?.timeoutMs !== undefined) {
+                    timeoutId = setTimeout(() => {
+                        settle({ status: "timeout" });
+                        controller.abort();
+                    }, options.timeoutMs);
+                }
+                interaction.prompt(hostRequest, { signal: controller.signal }).then((outcome) => {
+                    // A late host result loses the race against local settlement
+                    // (external abort, timeout, revoke/dispose) and is discarded.
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    try {
+                        // A host result delivered to a plainly revoked API (revoke
+                        // without disposal) is the sanctioned request() rejection.
+                        assertUsable();
+                        // A malformed host outcome fails the request visibly
+                        // instead of reaching the plugin.
+                        validateHostInteractionOutcome(outcome, hostRequest.kind);
+                    }
+                    catch (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve(detachedSnapshot(outcome));
+                }, () => settle({ status: "unavailable" }));
+            });
+        },
+    };
+}
+export function guardedOutput(output, assertUsable) {
+    return {
+        put: async (input, options) => {
+            assertUsable();
+            const result = await output.put(input, options);
+            assertUsable();
+            return result;
+        },
+        stat: async (ref) => {
+            assertUsable();
+            const result = await output.stat(ref);
+            assertUsable();
+            return result;
+        },
+        read: async (ref, options) => {
+            assertUsable();
+            const result = await output.read(ref, options);
+            assertUsable();
+            return result;
+        },
+    };
+}
+/**
+ * Terminal-state classification for agent task runs (D-044 §5.2): an
+ * AbortError thrown out of the adapter's run is treated as a cancelled
+ * terminal outcome, not a failure, so an aborted child prompt is never
+ * recorded as succeeded.
+ */
+function isCancellationClassError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+/** steer 结构化拒绝：带 code 的普通错误，调用方按码分支（未知任务/非运行态/无 steer 面）。 */
+function steerError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+export class RuntimeAgentTask {
+    id;
+    parentSessionId;
+    session;
+    currentStatus = "created";
+    started = false;
+    disposed = false;
+    controller = new AbortController();
+    runPromise;
+    disposePromise;
+    request;
+    host;
+    assertApiUsable;
+    agentResults;
+    /**
+     * Runtime-owned release hook: the runtime keeps each task in its live-task
+     * set and on the parent fence signal so runtime/plugin disposal can still
+     * reach in-flight work. Both references must be dropped when the task itself
+     * is disposed, otherwise every settled task keeps its host — and with it the
+     * whole child session graph — reachable for the rest of the parent session.
+     */
+    releaseRuntimeReferences;
+    terminalResult;
+    constructor(id, parentSessionId, request, host, assertApiUsable, allowRevision, agentResults, releaseRuntimeReferences) {
+        this.id = id;
+        this.parentSessionId = parentSessionId;
+        this.request = request;
+        this.host = host;
+        this.assertApiUsable = assertApiUsable;
+        this.agentResults = agentResults;
+        this.releaseRuntimeReferences = releaseRuntimeReferences;
+        this.session = guardedSession(host.session, () => this.assertUsable(), {
+            allowExport: host.session.exportArtifact !== undefined,
+            allowRevision,
+        });
+    }
+    status() {
+        this.assertUsable();
+        return this.currentStatus;
+    }
+    /**
+     * 父→子引导（D-060 S4）：向**运行中**的任务宿主会话投递一条有界引导消息，
+     * 复用会话自身 steer 语义，不新增队列。未启动/已终态/宿主无 steer 面都以
+     * 带 code 的错误拒绝（`subagent_not_running` / `subagent_steer_unsupported`）。
+     */
+    async steer(text) {
+        this.assertUsable();
+        if (text.length === 0 || new TextEncoder().encode(text).length > SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES) {
+            throw steerError("subagent_message_too_large", `steer text must be 1..${SUBAGENT_MAILBOX_MAX_MESSAGE_BYTES} utf-8 bytes`);
+        }
+        if (!this.started || this.currentStatus !== "running") {
+            throw steerError("subagent_not_running", `Agent task is not running: ${this.id}`);
+        }
+        const steerFn = this.host.session.steer;
+        if (typeof steerFn !== "function") {
+            throw steerError("subagent_steer_unsupported", `Agent task host session exposes no steer: ${this.id}`);
+        }
+        await steerFn.call(this.host.session, text);
+    }
+    /**
+     * Run the task's prompt on the host adapter exactly once. Resolves when the
+     * run settles succeeded or cancelled; rejects only on failure or when a
+     * terminal outcome could not be persisted. An AbortError escaping
+     * `host.run` is a cancelled terminal state (D-044 §5.2), not a failure.
+     */
+    run() {
+        this.assertUsable();
+        if (this.started || this.currentStatus !== "created") {
+            throw new Error(`Agent task can only run once: ${this.id}`);
+        }
+        this.started = true;
+        this.currentStatus = "running";
+        this.runPromise = (async () => {
+            try {
+                await this.host.run(this.request.prompt, this.controller.signal);
+            }
+            catch (error) {
+                if (this.currentStatus === "cancelled")
+                    return;
+                if (isCancellationClassError(error)) {
+                    this.currentStatus = "cancelled";
+                    try {
+                        await this.settleTerminalResult("cancelled");
+                    }
+                    catch (persistError) {
+                        // The task's own cancellation stays the primary rejection;
+                        // the replay-channel failure is attached as its cause instead
+                        // of shadowing it.
+                        if (error instanceof Error && !("cause" in error)) {
+                            error.cause = persistError;
+                            throw error;
+                        }
+                        throw new Error("Agent task was cancelled and its result could not be persisted", {
+                            cause: { task: error, persist: persistError },
+                        });
+                    }
+                    return;
+                }
+                this.currentStatus = "failed";
+                try {
+                    await this.settleTerminalResult("failed");
+                }
+                catch (persistError) {
+                    // The task's own failure stays the primary rejection; the
+                    // replay-channel failure is attached as its cause instead of
+                    // shadowing it.
+                    if (error instanceof Error && !("cause" in error)) {
+                        error.cause = persistError;
+                        throw error;
+                    }
+                    throw new Error("Agent task failed and its result could not be persisted", {
+                        cause: { task: error, persist: persistError },
+                    });
+                }
+                throw error;
+            }
+            if (this.currentStatus === "running") {
+                this.currentStatus = "succeeded";
+                await this.settleTerminalResult("succeeded");
+            }
+        })();
+        void this.runPromise.catch(() => { });
+        return this.runPromise;
+    }
+    wait(options) {
+        this.assertUsable();
+        if (this.currentStatus === "created")
+            throw new Error(`Agent task has not been started: ${this.id}`);
+        const completion = this.runPromise ?? Promise.resolve();
+        const result = completion.then(() => ({
+            sessionId: this.host.session.getSessionId(),
+            messages: this.host.session.getMessages(),
+        }));
+        const signal = options?.signal;
+        if (!signal)
+            return result;
+        if (signal.aborted)
+            return Promise.reject(cancellationError(signal.reason));
+        return Promise.race([
+            result,
+            new Promise((_resolve, reject) => {
+                signal.addEventListener("abort", () => reject(cancellationError(signal.reason)), { once: true });
+            }),
+        ]);
+    }
+    async cancel(reason = "cancelled") {
+        this.assertUsable();
+        if (this.currentStatus === "succeeded" || this.currentStatus === "failed" || this.currentStatus === "cancelled") {
+            return;
+        }
+        this.currentStatus = "cancelled";
+        this.controller.abort(reason);
+        await this.host.cancel(reason);
+        await this.settleTerminalResult("cancelled");
+    }
+    dispose() {
+        this.disposePromise ??= (async () => {
+            this.disposed = true;
+            try {
+                if (this.currentStatus === "created" || this.currentStatus === "running") {
+                    this.currentStatus = "cancelled";
+                    this.controller.abort("agent task disposed");
+                    // The terminal record captures the session messages before the
+                    // adapter disposes them; a settle after host.dispose() could read
+                    // already-released session state.
+                    await this.settleTerminalResult("cancelled");
+                    try {
+                        await this.host.cancel("agent task disposed");
+                    }
+                    finally {
+                        await this.host.dispose();
+                    }
+                    return;
+                }
+                await this.host.dispose();
+            }
+            finally {
+                // Also on a failing host disposal: a disposed task must not stay
+                // reachable from the runtime's live-task set or the parent fence.
+                this.releaseRuntimeReferences?.();
+            }
+        })();
+        return this.disposePromise;
+    }
+    result() {
+        // Replay read: no liveness assertion, the frozen terminal outcome
+        // stays readable after dispose.
+        return this.terminalResult;
+    }
+    /**
+     * Capture the frozen terminal outcome at settle: the record is detached and
+     * deep-frozen so the replay read survives dispose and shares no identity
+     * with live session state. When a durable replay channel is configured, the
+     * record is persisted under the deterministic artifact id
+     * `agent-task:<taskId>`; a persist failure propagates verbatim from the
+     * originating settle call (run/cancel/dispose) without affecting the
+     * already-captured in-memory result.
+     */
+    async settleTerminalResult(status) {
+        // detachedSnapshot deep-clones and recursively freezes; the session
+        // snapshot in public-api.ts clones without freezing, so the frozen
+        // terminal outcome requires this projection.
+        const record = detachedSnapshot({
+            taskId: this.id,
+            parentSessionId: this.parentSessionId,
+            status,
+            sessionId: this.host.session.getSessionId(),
+            messages: this.host.session.getMessages(),
+        });
+        this.terminalResult = record;
+        if (!this.agentResults)
+            return;
+        await this.agentResults.store.persistArtifact({
+            writerId: this.agentResults.writerId,
+            artifactId: `agent-task:${this.id}`,
+            sessionId: this.parentSessionId,
+            data: record,
+        });
+    }
+    assertUsable() {
+        this.assertApiUsable();
+        if (this.disposed)
+            throw new Error(`Agent task handle is disposed: ${this.id}`);
+    }
+}
+/**
+ * Normalize a capability tool's execute outcome into an AgentToolResult shape.
+ *
+ * Capability tools execute to plain domain objects ({memoryId, kind, ...}); the
+ * agent core's tool-result message reads `result.content` and would surface an
+ * empty result to the model. Strings become the text directly, objects without
+ * a content array are serialized as stable pretty JSON, results that already
+ * carry a content array pass through untouched, and undefined/null keep the
+ * existing empty-content normalization the agent core performs.
+ */
+export function normalizeCapabilityToolResult(result) {
+    if (result === undefined || result === null)
+        return result;
+    if (typeof result === "string") {
+        return { content: [{ type: "text", text: result }], details: {} };
+    }
+    if (typeof result === "object" && Array.isArray(result.content))
+        return result;
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: {} };
+}
+/**
+ * Wrap a listed tool definition's execute with {@link normalizeCapabilityToolResult}.
+ *
+ * listTools() is the only face the model-facing chain reads (the session's
+ * capability tool registry), so wrapping here fixes the model result surface
+ * for every capability tool at one point while runtime.invokeTool keeps
+ * returning raw values to deterministic callers. The wrapper forwards all
+ * arguments and propagates rejections untouched (the agent core already maps
+ * thrown errors to error tool results).
+ */
+export function withNormalizedToolResultExecute(definition) {
+    if (!definition || typeof definition !== "object")
+        return definition;
+    const execute = definition.execute;
+    if (typeof execute !== "function")
+        return definition;
+    const run = execute;
+    const wrapped = (...args) => {
+        const outcome = run(...args);
+        if (outcome instanceof Promise)
+            return outcome.then(normalizeCapabilityToolResult);
+        return normalizeCapabilityToolResult(outcome);
+    };
+    return Object.freeze({ ...definition, execute: wrapped });
+}
+export function guardedComposition(composition, assertUsable, trackInstance, trackDefinition, hostPrimitivesFactory, lifecycleDispatcher, manifest) {
+    const declaredAgent = (id, version, role) => {
+        const declaration = manifest.agents?.find((agent) => agent.id === id && agent.version === version && (role === undefined || agent.role === role));
+        if (!declaration)
+            throw new Error(`Agent definition must be declared by plugin manifest: ${id}@${version}`);
+    };
+    const assertOwnedDefinition = (definition) => {
+        declaredAgent(definition.id, definition.version, definition.role);
+        if (definition.owner !== undefined && definition.owner !== manifest.id) {
+            throw new Error(`Agent definition owner must match plugin manifest: ${manifest.id}`);
+        }
+    };
+    const assertOwnedParent = (parentInstanceId) => {
+        if (parentInstanceId === undefined)
+            return;
+        const parent = composition.listInstances().find((instance) => instance.id === parentInstanceId);
+        if (!parent)
+            return;
+        const definition = composition.get(parent.definitionId, parent.definitionVersion);
+        if (definition.owner !== undefined && definition.owner !== manifest.id) {
+            throw new Error(`Parent Agent instance must belong to plugin manifest: ${parentInstanceId}`);
+        }
+        assertOwnedDefinition(definition);
+    };
+    return Object.freeze({
+        define: (definition) => {
+            assertUsable();
+            assertOwnedDefinition(definition);
+            const registered = composition.define({ ...definition, owner: manifest.id });
+            trackDefinition(registered);
+            return registered;
+        },
+        get: (id, version) => {
+            assertUsable();
+            declaredAgent(id, version);
+            const definition = composition.get(id, version);
+            assertOwnedDefinition(definition);
+            return definition;
+        },
+        create: (definition, options) => {
+            assertUsable();
+            if ("run" in definition) {
+                assertOwnedDefinition(definition);
+            }
+            else {
+                declaredAgent(definition.id, definition.version);
+                assertOwnedDefinition(composition.get(definition.id, definition.version));
+            }
+            assertOwnedParent(options?.parentInstanceId);
+            const scopedBinding = composition;
+            if (!scopedBinding.createWithHostPrimitives) {
+                throw new Error("Agent composition runtime does not support owner-scoped host primitives");
+            }
+            const instance = scopedBinding.createWithHostPrimitives(definition, options, hostPrimitivesFactory, lifecycleDispatcher);
+            const guarded = Object.freeze({
+                id: instance.id,
+                definition: instance.definition,
+                snapshot: () => {
+                    assertUsable();
+                    return instance.snapshot();
+                },
+                acquireControllerLease: (owner) => {
+                    assertUsable();
+                    return instance.acquireControllerLease(owner);
+                },
+                run: (input, runOptions) => {
+                    assertUsable();
+                    return instance.run(input, runOptions);
+                },
+                wait: () => instance.wait(),
+                cancel: (reason) => {
+                    assertUsable();
+                    return instance.cancel(reason);
+                },
+                dispose: () => instance.dispose(),
+            });
+            trackInstance(guarded);
+            return guarded;
+        },
+        listInstances: () => {
+            assertUsable();
+            return composition.listInstances().filter((instance) => {
+                try {
+                    return composition.get(instance.definitionId, instance.definitionVersion).owner === manifest.id;
+                }
+                catch {
+                    return false;
+                }
+            });
+        },
+    });
+}
+//# sourceMappingURL=capability-runtime-guards.js.map