@zihanw/pi-forge 0.4.0-beta.1 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zihanw/pi-forge",
-  "version": "0.4.0-beta.1",
+	"version": "0.4.1",
   "description": "Pi extension for prompt stacks, one-shot agent profiles, policy, import, and debugging.",
   "repository": {
     "type": "git",
@@ -33,6 +33,7 @@
       "import": "./dist/*.js",
       "default": "./dist/*.js"
     },
+    "./src/web-editor/client/*": null,
     "./examples/*": "./examples/*"
   },
   "keywords": [
@@ -51,9 +52,11 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "0.80.10",
-    "@earendil-works/pi-ai": "0.80.10",
-    "@earendil-works/pi-coding-agent": "0.80.10"
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-agent-core": {
@@ -64,36 +67,47 @@
     },
     "@earendil-works/pi-coding-agent": {
       "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@earendil-works/pi-tui": "0.80.10",
-    "typebox": "^1.1.38"
+    "@zihanw/pi-subagent-runtime": "0.1.0-beta.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.80.10",
-    "@earendil-works/pi-ai": "0.80.10",
-    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
     "@types/node": "22.20.1",
-    "esbuild": "^0.28.1",
+    "@vitejs/plugin-vue": "6.0.8",
     "playwright-core": "1.61.1",
-    "typescript": "6.0.3"
+    "typebox": "1.3.7",
+    "typescript": "6.0.3",
+    "vite": "8.1.5",
+    "vue": "3.5.40",
+    "vue-tsc": "3.3.8"
   },
   "scripts": {
     "build": "npm run build:client && tsc -p tsconfig.build.json",
     "build:client": "node scripts/build-web-client.mjs",
     "check:client": "node scripts/build-web-client.mjs --check",
+    "check:docs": "node scripts/check-docs.mjs",
     "check:dist": "node scripts/check-dist.mjs",
     "check:package": "node scripts/check-package.mjs",
     "prepack": "npm run build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && vue-tsc --noEmit -p tsconfig.web.json",
     "test": "node --test tests/*.test.ts",
-    "test:browser": "node --test tests-browser/*.test.ts",
-    "spike:subagent": "node scripts/subagent-sdk-spike.ts",
-    "verify": "npm test && npm run test:browser && npm run typecheck && npm run check:client && npm run check:dist && npm run check:package"
+    "test:browser": "node --test --test-concurrency=1 tests-browser/*.test.ts",
+    "verify": "npm test && npm run test:browser && npm run typecheck && npm run check:client && npm run check:docs && npm run check:dist && npm run check:package"
   },
   "files": [
     "dist/",
+    "docs/",
     "examples/",
     "README.md",
     "README.zh-CN.md",

package/dist/subagent/backend-registry.d.ts

@@ -1,75 +0,0 @@
-import { type AgentExecutionPlan, type AgentProfileSnapshot, type AgentRequest, type AgentResponse, type BackendPreflightResult, type SubagentBackendDescriptor, type SubagentHostPlanPreparer, type SubagentPreparationBaseInput, type SubagentPreparationResult, type SubagentPreparationRuntime, type SubagentTraceReference } from "./contract.ts";
-type WithoutTrace<T> = T extends AgentResponse ? Omit<T, "trace"> : never;
-export interface SubagentBackendTraceResult {
-    id: string;
-    expiresAt?: string;
-}
-export type SubagentBackendExecutionResult = WithoutTrace<AgentResponse> & {
-    trace?: SubagentBackendTraceResult;
-};
-export interface SubagentBackendPreflightInput {
-    request: AgentRequest;
-    snapshot: AgentProfileSnapshot;
-    signal?: AbortSignal;
-}
-export interface SubagentBackendPreparationContext {
-    signal?: AbortSignal;
-    prepare(runtime: SubagentPreparationRuntime): Promise<SubagentPreparationResult>;
-}
-export interface SubagentBackendExecutionContext {
-    signal: AbortSignal;
-    onUpdate?: (update: SubagentBackendExecutionUpdate) => void;
-}
-export interface SubagentBackendExecutionUpdate {
-    phase: "starting" | "message" | "tool-result" | "finishing";
-    message: string;
-    details?: unknown;
-}
-export interface SubagentBackendCancelInput {
-    runId: string;
-    reason: string;
-}
-export interface SubagentBackendTraceInput {
-    traceId: string;
-    signal?: AbortSignal;
-}
-export interface SubagentBackend {
-    readonly descriptor: SubagentBackendDescriptor;
-    preflight(input: SubagentBackendPreflightInput): Promise<BackendPreflightResult> | BackendPreflightResult;
-    prepare?(input: SubagentPreparationBaseInput, context: SubagentBackendPreparationContext): Promise<SubagentPreparationResult> | SubagentPreparationResult;
-    execute(plan: AgentExecutionPlan, context: SubagentBackendExecutionContext): Promise<SubagentBackendExecutionResult> | SubagentBackendExecutionResult;
-    discard?(preflightId: string): Promise<boolean> | boolean;
-    cancel?(input: SubagentBackendCancelInput): Promise<void> | void;
-    inspectTrace?(input: SubagentBackendTraceInput): Promise<unknown> | unknown;
-}
-export interface SubagentBackendRegistryOptions {
-    idFactory?: (kind: "preflight" | "trace") => string;
-    now?: () => number;
-}
-export interface SubagentExecutionOptions {
-    authorizationScope: string;
-    signal?: AbortSignal;
-    onUpdate?: (update: SubagentBackendExecutionUpdate) => void;
-}
-export declare class SubagentBackendRegistryError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string);
-}
-export declare class SubagentBackendRegistry {
-    #private;
-    constructor(options?: SubagentBackendRegistryOptions);
-    get size(): number;
-    register(backend: SubagentBackend): () => boolean;
-    unregister(backendId: string): boolean;
-    descriptors(): SubagentBackendDescriptor[];
-    forgetPreflight(preflightId: string): boolean;
-    discard(preflightId: string): Promise<boolean>;
-    preflight(backendId: string, request: AgentRequest, snapshot: AgentProfileSnapshot, signal?: AbortSignal): Promise<BackendPreflightResult>;
-    prepare(backendId: string, input: SubagentPreparationBaseInput, hostPreparer: SubagentHostPlanPreparer, signal?: AbortSignal): Promise<SubagentPreparationResult>;
-    execute(plan: AgentExecutionPlan, options: SubagentExecutionOptions): Promise<AgentResponse>;
-    cancel(runId: string, reason?: string): Promise<boolean>;
-    inspectTrace(reference: SubagentTraceReference, authorizationScope: string, signal?: AbortSignal): Promise<unknown>;
-    forgetTrace(handle: string): boolean;
-}
-export {};
-//# sourceMappingURL=backend-registry.d.ts.map

package/dist/subagent/backend-registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"backend-registry.d.ts","sourceRoot":"","sources":["../../src/subagent/backend-registry.ts"],"names":[],"mappings":"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"}

package/dist/subagent/backend-registry.js

@@ -1,463 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { SUBAGENT_CONTRACT_VERSION, canonicalSubagentJson, hasSubagentErrors, validateAgentExecutionPlan, validateAgentProfileSnapshot, validateAgentRequest, validateAgentResponse, validateBackendPreflight, validatePreparationRuntime, validateSubagentTraceReference, } from "./contract.js";
-export class SubagentBackendRegistryError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = "SubagentBackendRegistryError";
-        this.code = code;
-    }
-}
-export class SubagentBackendRegistry {
-    #backends = new Map();
-    #preflights = new Map();
-    #traces = new Map();
-    #activeRuns = new Map();
-    #idFactory;
-    #now;
-    constructor(options = {}) {
-        this.#idFactory = options.idFactory ?? ((kind) => `${kind}:${randomUUID()}`);
-        this.#now = options.now ?? Date.now;
-    }
-    get size() {
-        return this.#backends.size;
-    }
-    register(backend) {
-        validateRegistration(backend);
-        const id = backend.descriptor.id;
-        if (this.#backends.has(id))
-            throw new SubagentBackendRegistryError("backend.duplicate", `A subagent backend is already registered as ${id}.`);
-        this.#backends.set(id, backend);
-        return () => this.unregister(id);
-    }
-    unregister(backendId) {
-        if ([...this.#activeRuns.values()].some((run) => run.backend.descriptor.id === backendId)) {
-            throw new SubagentBackendRegistryError("backend.active", `Cannot unregister backend ${backendId} while one of its runs is active or draining.`);
-        }
-        const removed = this.#backends.delete(backendId);
-        if (!removed)
-            return false;
-        for (const [id, record] of this.#preflights)
-            if (record.backendId === backendId)
-                this.#preflights.delete(id);
-        for (const [handle, record] of this.#traces)
-            if (record.reference.backendId === backendId)
-                this.#traces.delete(handle);
-        return true;
-    }
-    descriptors() {
-        return [...this.#backends.values()]
-            .map((backend) => structuredClone(backend.descriptor))
-            .sort((left, right) => left.id.localeCompare(right.id));
-    }
-    forgetPreflight(preflightId) {
-        if ([...this.#activeRuns.values()].some((run) => run.plan.preflightId === preflightId)) {
-            throw new SubagentBackendRegistryError("preflight.active", `Cannot forget preflight ${preflightId} while its run is active or draining.`);
-        }
-        return this.#preflights.delete(preflightId);
-    }
-    async discard(preflightId) {
-        if ([...this.#activeRuns.values()].some((run) => run.plan.preflightId === preflightId)) {
-            throw new SubagentBackendRegistryError("preflight.active", `Cannot discard preflight ${preflightId} while its run is active or draining.`);
-        }
-        const record = this.#preflights.get(preflightId);
-        if (!record)
-            return false;
-        const backend = this.#requireBackend(record.backendId);
-        await backend.discard?.(preflightId);
-        this.#preflights.delete(preflightId);
-        return true;
-    }
-    async preflight(backendId, request, snapshot, signal) {
-        const backend = this.#requireBackend(backendId);
-        const inputDiagnostics = [...validateAgentRequest(request), ...validateAgentProfileSnapshot(snapshot)];
-        if (hasSubagentErrors(inputDiagnostics))
-            return this.#rejectedPreflight(backend, inputDiagnostics);
-        if (signal?.aborted)
-            return this.#rejectedPreflight(backend, [diagnostic("preflight.cancelled", "Preflight was cancelled before backend discovery.")]);
-        let result;
-        try {
-            result = await backend.preflight({ request: structuredClone(request), snapshot: structuredClone(snapshot), signal });
-        }
-        catch (error) {
-            return this.#rejectedPreflight(backend, [diagnostic("preflight.backend-error", errorMessage(error))]);
-        }
-        const diagnostics = validateBackendPreflight(result, request, snapshot);
-        if (result.backend?.id !== backendId || !sameDescriptor(result.backend, backend.descriptor)) {
-            diagnostics.push(diagnostic("preflight.backend-identity", "Backend preflight descriptor does not match its registered identity.", "backend"));
-        }
-        if (this.#preflights.has(result.preflightId))
-            diagnostics.push(diagnostic("preflight.duplicate-id", "Backend reused an existing preflightId.", "preflightId"));
-        if (hasSubagentErrors(diagnostics))
-            return this.#rejectedPreflight(backend, diagnostics, validOpaqueId(result.preflightId) ? result.preflightId : undefined);
-        if (result.status === "accepted") {
-            this.#preflights.set(result.preflightId, {
-                backendId,
-                requestId: request.requestId,
-                profileFingerprint: snapshot.profileFingerprint,
-                requestCanonical: canonicalSubagentJson(request),
-                snapshotCanonical: canonicalSubagentJson(snapshot),
-                preflightCanonical: canonicalSubagentJson(result),
-            });
-        }
-        return structuredClone(result);
-    }
-    async prepare(backendId, input, hostPreparer, signal) {
-        const backend = this.#requireBackend(backendId);
-        this.#assertPreflightBinding(input.preflight, input.request, input.snapshot);
-        const record = this.#preflights.get(input.preflight.preflightId);
-        if (record.preparation)
-            throw new SubagentBackendRegistryError("preparation.already-bound", "Accepted preflight already has a host preparation bound to it.");
-        if (signal?.aborted)
-            throw new SubagentBackendRegistryError("preparation.cancelled", "Preparation was cancelled before it started.");
-        const fidelity = backend.descriptor.capabilities.promptRuntimeFidelity;
-        if (fidelity === "partial")
-            throw new SubagentBackendRegistryError("preparation.partial", "A partial prompt runtime cannot prepare an execution plan.");
-        let hostResult;
-        const prepare = async (runtime) => {
-            if (hostResult)
-                throw new SubagentBackendRegistryError("preparation.duplicate", "Backend attempted to prepare the same request more than once.");
-            const runtimeDiagnostics = [];
-            validatePreparationRuntime(runtime, "runtime", runtimeDiagnostics, fidelity);
-            if (runtime.model.provider !== input.preflight.model.provider || runtime.model.id !== input.preflight.model.id) {
-                runtimeDiagnostics.push(diagnostic("preparation.runtime-model", "Prompt runtime model does not match the accepted preflight model.", "runtime.model"));
-            }
-            if (hasSubagentErrors(runtimeDiagnostics))
-                throw new SubagentBackendRegistryError("preparation.invalid-runtime", summarizeDiagnostics(runtimeDiagnostics));
-            const exactInput = { ...structuredClone(input), runtime: structuredClone(runtime) };
-            hostResult = {
-                runtime: structuredClone(runtime),
-                preparation: structuredClone(await hostPreparer(exactInput)),
-            };
-            return structuredClone(hostResult);
-        };
-        if (fidelity === "exact-preflight") {
-            if (!input.preflight.promptRuntime)
-                throw new SubagentBackendRegistryError("preparation.runtime-missing", "Exact-preflight backend did not provide a prompt runtime receipt.");
-            const result = await prepare(input.preflight.promptRuntime);
-            this.#bindPreparation(record, result);
-            return result;
-        }
-        if (!backend.prepare)
-            throw new SubagentBackendRegistryError("preparation.unsupported", `Backend ${backendId} advertises backend-assisted preparation but has no prepare method.`);
-        const backendResult = structuredClone(await backend.prepare(structuredClone(input), { signal, prepare }));
-        if (!hostResult)
-            throw new SubagentBackendRegistryError("preparation.host-bypass", `Backend ${backendId} returned without invoking host preparation.`);
-        if (canonicalSubagentJson(backendResult) !== canonicalSubagentJson(hostResult)) {
-            throw new SubagentBackendRegistryError("preparation.host-mismatch", `Backend ${backendId} altered the host preparation result.`);
-        }
-        this.#bindPreparation(record, backendResult);
-        return backendResult;
-    }
-    async execute(plan, options) {
-        const backend = this.#requireBackend(plan.backendId);
-        const planDiagnostics = validateAgentExecutionPlan(plan);
-        if (hasSubagentErrors(planDiagnostics))
-            throw new SubagentBackendRegistryError("execution.invalid-plan", summarizeDiagnostics(planDiagnostics));
-        const preflightRecord = this.#preflights.get(plan.preflightId);
-        if (!preflightRecord
-            || preflightRecord.backendId !== plan.backendId
-            || preflightRecord.requestId !== plan.requestId
-            || preflightRecord.profileFingerprint !== plan.profile.profileFingerprint
-            || preflightRecord.snapshotCanonical !== canonicalSubagentJson(plan.profile)
-            || preflightRecord.preflightCanonical !== canonicalSubagentJson(plan.preflight)) {
-            throw new SubagentBackendRegistryError("execution.unbound-preflight", "Execution plan is not bound to an accepted registry preflight.");
-        }
-        const preparation = preflightRecord.preparation;
-        if (!preparation
-            || preparation.promptRuntimeFingerprint !== plan.promptRuntimeFingerprint
-            || preparation.systemPrompt !== plan.systemPrompt
-            || preparation.messagesCanonical !== canonicalSubagentJson(plan.messages)
-            || preparation.effectiveToolIdsCanonical !== canonicalSubagentJson(plan.effectiveToolIds)
-            || preparation.contextBudgetCanonical !== canonicalSubagentJson(plan.contextBudget ?? null)) {
-            throw new SubagentBackendRegistryError("execution.unbound-preparation", "Execution plan does not match the exact host preparation bound to its preflight.");
-        }
-        if (!validNamespace(options.authorizationScope))
-            throw new SubagentBackendRegistryError("execution.authorization", "authorizationScope must be a normalized namespace.");
-        if (this.#activeRuns.has(plan.runId))
-            throw new SubagentBackendRegistryError("execution.duplicate-run", `Run ${plan.runId} is already active.`);
-        const startedAt = this.#now();
-        const controller = new AbortController();
-        let resolveTerminal;
-        const terminal = new Promise((resolve) => { resolveTerminal = resolve; });
-        const active = { backend, plan, controller, settled: false, terminal };
-        this.#activeRuns.set(plan.runId, active);
-        let timeout;
-        let externalAbort;
-        const settle = (response) => {
-            if (active.settled)
-                return false;
-            active.settled = true;
-            if (timeout)
-                clearTimeout(timeout);
-            if (externalAbort && options.signal)
-                options.signal.removeEventListener("abort", externalAbort);
-            resolveTerminal(response);
-            return true;
-        };
-        const cancelRun = (kind, reason) => {
-            if (active.settled || active.cancellation)
-                return;
-            active.cancellation = { kind, reason };
-            controller.abort(reason);
-            active.cancelPromise = Promise.resolve(backend.cancel?.({ runId: plan.runId, reason })).catch(() => undefined);
-        };
-        active.requestCancellation = cancelRun;
-        const settleCancellation = () => {
-            const cancellation = active.cancellation;
-            if (!cancellation)
-                return false;
-            const durationMs = elapsed(this.#now(), startedAt);
-            return settle(cancellation.kind === "timed-out"
-                ? { ...responseCommon(plan, durationMs), status: "timed-out", reason: cancellation.reason, enforcedTimeoutMs: plan.limits.timeoutMs.value }
-                : { ...responseCommon(plan, durationMs), status: "cancelled", reason: cancellation.reason });
-        };
-        if (options.signal) {
-            externalAbort = () => cancelRun("cancelled", abortReason(options.signal, "user"));
-            if (options.signal.aborted)
-                externalAbort();
-            else
-                options.signal.addEventListener("abort", externalAbort, { once: true });
-        }
-        const timeoutLimit = plan.limits.timeoutMs;
-        if (!active.settled && timeoutLimit?.enforcement === "host-abort") {
-            timeout = setTimeout(() => cancelRun("timed-out", "host timeout"), timeoutLimit.value);
-        }
-        const backendExecution = Promise.resolve()
-            .then(async () => {
-            if (active.cancellation) {
-                await active.cancelPromise;
-                await backend.discard?.(plan.preflightId);
-                settleCancellation();
-                return;
-            }
-            const result = await backend.execute(structuredClone(plan), {
-                signal: controller.signal,
-                onUpdate: options.onUpdate
-                    ? (update) => {
-                        try {
-                            options.onUpdate?.(structuredClone(update));
-                        }
-                        catch {
-                            // UI/reporting callbacks cannot fail backend execution.
-                        }
-                    }
-                    : undefined,
-            });
-            if (active.cancellation) {
-                await active.cancelPromise;
-                settleCancellation();
-                return;
-            }
-            settle(this.#normalizeBackendResponse(result, plan, options.authorizationScope, elapsed(this.#now(), startedAt)));
-        })
-            .catch(async (error) => {
-            if (active.cancellation) {
-                await active.cancelPromise;
-                settleCancellation();
-                return;
-            }
-            settle({
-                ...responseCommon(plan, elapsed(this.#now(), startedAt)),
-                status: "failed",
-                error: { code: "backend-execution", message: errorMessage(error), retryable: false },
-            });
-        })
-            .finally(() => {
-            if (timeout)
-                clearTimeout(timeout);
-            if (externalAbort && options.signal)
-                options.signal.removeEventListener("abort", externalAbort);
-            if (this.#activeRuns.get(plan.runId) === active)
-                this.#activeRuns.delete(plan.runId);
-            this.#preflights.delete(plan.preflightId);
-        });
-        void backendExecution;
-        return terminal;
-    }
-    async cancel(runId, reason = "user") {
-        const active = this.#activeRuns.get(runId);
-        if (!active || active.settled || active.cancellation)
-            return false;
-        active.requestCancellation?.("cancelled", reason);
-        await active.terminal;
-        return true;
-    }
-    async inspectTrace(reference, authorizationScope, signal) {
-        const diagnostics = validateSubagentTraceReference(reference);
-        if (hasSubagentErrors(diagnostics))
-            throw new SubagentBackendRegistryError("trace.invalid", summarizeDiagnostics(diagnostics));
-        const record = this.#traces.get(reference.handle);
-        if (!record || !sameTraceReference(record.reference, reference))
-            throw new SubagentBackendRegistryError("trace.unknown", "Trace handle is unknown or does not match its registered route.");
-        if (reference.authorizationScope !== authorizationScope)
-            throw new SubagentBackendRegistryError("trace.forbidden", "Trace authorization scope does not match the caller.");
-        if (reference.expiresAt && Date.parse(reference.expiresAt) <= this.#now()) {
-            this.#traces.delete(reference.handle);
-            throw new SubagentBackendRegistryError("trace.expired", "Trace handle has expired.");
-        }
-        const backend = this.#requireBackend(reference.backendId);
-        if (!backend.descriptor.capabilities.traceInspection || !backend.inspectTrace) {
-            throw new SubagentBackendRegistryError("trace.unsupported", `Backend ${reference.backendId} does not support trace inspection.`);
-        }
-        return backend.inspectTrace({ traceId: record.backendTraceId, signal });
-    }
-    forgetTrace(handle) {
-        return this.#traces.delete(handle);
-    }
-    #requireBackend(backendId) {
-        const backend = this.#backends.get(backendId);
-        if (!backend)
-            throw new SubagentBackendRegistryError("backend.unknown", `Unknown subagent backend: ${backendId}`);
-        return backend;
-    }
-    #assertPreflightBinding(preflight, request, snapshot) {
-        const record = this.#preflights.get(preflight.preflightId);
-        if (!record
-            || record.backendId !== preflight.backend.id
-            || record.requestId !== request.requestId
-            || record.profileFingerprint !== snapshot.profileFingerprint
-            || record.requestCanonical !== canonicalSubagentJson(request)
-            || record.snapshotCanonical !== canonicalSubagentJson(snapshot)
-            || record.preflightCanonical !== canonicalSubagentJson(preflight)) {
-            throw new SubagentBackendRegistryError("preparation.unbound-preflight", "Preparation input is not bound to an accepted registry preflight.");
-        }
-    }
-    #bindPreparation(record, result) {
-        record.preparation = {
-            promptRuntimeFingerprint: result.runtime.promptRuntimeFingerprint,
-            systemPrompt: result.preparation.systemPrompt,
-            messagesCanonical: canonicalSubagentJson(result.preparation.messages),
-            effectiveToolIdsCanonical: canonicalSubagentJson(result.preparation.toolNegotiation.effectiveToolIds),
-            contextBudgetCanonical: canonicalSubagentJson(result.preparation.contextBudget ?? null),
-        };
-    }
-    #rejectedPreflight(backend, diagnostics, preflightId) {
-        return {
-            status: "rejected",
-            preflightId: preflightId ?? this.#idFactory("preflight"),
-            backend: structuredClone(backend.descriptor),
-            diagnostics: ensureErrorDiagnostics(diagnostics),
-        };
-    }
-    #normalizeBackendResponse(result, plan, authorizationScope, durationMs) {
-        let trace;
-        if (result.trace) {
-            if (!validOpaqueId(result.trace.id) || (result.trace.expiresAt !== undefined && !validIsoDate(result.trace.expiresAt))) {
-                return invalidBackendResponse(plan, durationMs, "Backend returned malformed trace routing metadata.");
-            }
-            trace = {
-                handle: this.#uniqueId("trace", this.#traces),
-                backendId: plan.backendId,
-                authorizationScope,
-                expiresAt: result.trace.expiresAt,
-            };
-        }
-        const { trace: _backendTrace, ...responseFields } = result;
-        const response = { ...responseFields, durationMs, trace };
-        const diagnostics = validateAgentResponse(response, { plan });
-        if (hasSubagentErrors(diagnostics))
-            return invalidBackendResponse(plan, durationMs, summarizeDiagnostics(diagnostics));
-        if (trace && result.trace)
-            this.#traces.set(trace.handle, { reference: trace, backendTraceId: result.trace.id });
-        return structuredClone(response);
-    }
-    #uniqueId(kind, values) {
-        for (let attempt = 0; attempt < 10; attempt += 1) {
-            const id = this.#idFactory(kind);
-            if (validOpaqueId(id) && !values.has(id))
-                return id;
-        }
-        throw new SubagentBackendRegistryError(`${kind}.id`, `Could not allocate a unique valid ${kind} identifier.`);
-    }
-}
-function validateRegistration(backend) {
-    if (!backend || typeof backend !== "object")
-        throw new SubagentBackendRegistryError("backend.type", "Subagent backend must be an object.");
-    if (typeof backend.preflight !== "function" || typeof backend.execute !== "function") {
-        throw new SubagentBackendRegistryError("backend.methods", "Subagent backend must implement preflight and execute.");
-    }
-    const diagnostics = validateBackendPreflight({
-        status: "rejected",
-        preflightId: "descriptor-check",
-        backend: backend.descriptor,
-        diagnostics: [diagnostic("backend.descriptor-check", "Descriptor validation sentinel.")],
-    });
-    if (hasSubagentErrors(diagnostics))
-        throw new SubagentBackendRegistryError("backend.descriptor", summarizeDiagnostics(diagnostics));
-    if (backend.descriptor.capabilities.promptRuntimeFidelity === "backend-assisted" && typeof backend.prepare !== "function") {
-        throw new SubagentBackendRegistryError("backend.prepare", "A backend-assisted backend must implement prepare.");
-    }
-    if (backend.descriptor.capabilities.traceInspection && typeof backend.inspectTrace !== "function") {
-        throw new SubagentBackendRegistryError("backend.trace", "A trace-inspection backend must implement inspectTrace.");
-    }
-}
-function responseCommon(plan, durationMs) {
-    return {
-        schemaVersion: SUBAGENT_CONTRACT_VERSION,
-        requestId: plan.requestId,
-        runId: plan.runId,
-        backendId: plan.backendId,
-        profileFingerprint: plan.profile.profileFingerprint,
-        executionFingerprint: plan.executionFingerprint,
-        model: structuredClone(plan.model),
-        effectiveToolIds: [...plan.effectiveToolIds],
-        enforcement: { access: structuredClone(plan.access), limits: structuredClone(plan.limits) },
-        durationMs,
-        artifacts: [],
-    };
-}
-function invalidBackendResponse(plan, durationMs, detail) {
-    return {
-        ...responseCommon(plan, durationMs),
-        status: "failed",
-        error: { code: "backend-invalid-response", message: detail, retryable: false },
-    };
-}
-function diagnostic(code, message, path) {
-    return { level: "error", code, message, path };
-}
-function ensureErrorDiagnostics(diagnostics) {
-    const cloned = structuredClone(diagnostics);
-    if (cloned.some((item) => item.level === "error"))
-        return [...cloned];
-    return [diagnostic("registry.rejected", "Registry rejected the backend operation."), ...cloned];
-}
-function summarizeDiagnostics(diagnostics) {
-    return diagnostics.filter((item) => item.level === "error").slice(0, 4).map((item) => `${item.code}: ${item.message}`).join("; ") || "Subagent validation failed.";
-}
-function sameDescriptor(left, right) {
-    try {
-        return canonicalSubagentJson(left) === canonicalSubagentJson(right);
-    }
-    catch {
-        return false;
-    }
-}
-function sameTraceReference(left, right) {
-    return left.handle === right.handle
-        && left.backendId === right.backendId
-        && left.authorizationScope === right.authorizationScope
-        && left.expiresAt === right.expiresAt;
-}
-function validOpaqueId(value) {
-    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
-}
-function validNamespace(value) {
-    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value);
-}
-function validIsoDate(value) {
-    return !Number.isNaN(Date.parse(value)) && new Date(value).toISOString() === value;
-}
-function elapsed(now, start) {
-    return Math.max(0, now - start);
-}
-function abortReason(signal, fallback) {
-    if (!signal)
-        return fallback;
-    return typeof signal.reason === "string" && signal.reason.trim() ? signal.reason : fallback;
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-//# sourceMappingURL=backend-registry.js.map