@wrenai/genbi 0.0.4 → 0.0.6

package/dist-server/server/native-component-context.js

@@ -0,0 +1,76 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { generatePreparedContext } from "../harness/compile/context-loader.js";
+import { hashDirectory } from "../harness/compile/fingerprint.js";
+import { captureWrenAccessIdentity } from "../harness/components/wren-access.js";
+import { prepareCodexDirectTools } from "./runtime-host/codex-direct-tools.js";
+import { prepareNativeComponentHost } from "./native-component-preparation.js";
+import { createNativeComponentRuntimeBindings } from "./native-component-runtime.js";
+/** Capture file-only context before host admission; never opens a vendor or Wren process. */
+export async function prepareCapturedNativeComponentHost(irDocument, scope, options) {
+    const capturedScope = structuredClone(scope);
+    const bindings = await captureBindings(irDocument, options);
+    return prepareNativeComponentHost(irDocument, capturedScope, bindings);
+}
+/** Direct-session variant shares the same captured project/credential provenance. */
+export async function prepareCapturedCodexDirectTools(irDocument, scope, options) {
+    if (options.vendor.vendor !== "codex" || options.identity.vendor !== "codex")
+        throw new Error("Direct session requires Codex");
+    const capturedScope = structuredClone(scope);
+    const accountEmail = options.vendor.accountEmail;
+    const bindings = await captureBindings(irDocument, options);
+    return prepareCodexDirectTools({ irDocument, scope: capturedScope, bindings, producerBinary: options.producerBinary,
+        accountEmail, expiresAt: options.expiresAt, signal: options.signal });
+}
+async function captureBindings(irDocument, options) {
+    const identity = structuredClone(options.identity);
+    const project = path.resolve(options.project);
+    const signal = options.signal;
+    const currentIdentity = options.currentIdentity.bind(options);
+    const assertBinding = options.assertCurrent.bind(options);
+    const assertVendor = options.vendor.assertCurrent.bind(options.vendor);
+    const check = () => {
+        signal.throwIfAborted();
+        assertBinding();
+        assertVendor();
+        if (!isDeepStrictEqual(currentIdentity(), identity))
+            throw new Error("Native component context binding expired");
+    };
+    check();
+    const ir = z.object({ warble_ir_version: z.literal("0.9"), components: z.array(z.object({
+            id: z.string(), context_binding: z.record(z.string(), z.unknown()).optional(),
+        }).passthrough()) }).passthrough().parse(JSON.parse(irDocument));
+    if (new Set(ir.components.map((component) => component.id)).size !== ir.components.length)
+        throw new Error("Duplicate component identity");
+    const fingerprint = await hashDirectory(project);
+    const accessIdentity = await captureWrenAccessIdentity(project, options.wrenEnvironment);
+    check();
+    const scratch = await mkdtemp(path.join(os.tmpdir(), "genbi-native-context-"));
+    try {
+        const snapshotPath = path.join(scratch, "context.json");
+        await generatePreparedContext(options.contextLoaderBinary, project, snapshotPath, signal);
+        const snapshot = z.object({ context_version: z.literal(2), parseable: z.literal(true) }).passthrough()
+            .parse(JSON.parse(await readFile(snapshotPath, "utf8")));
+        await accessIdentity.assertCurrent();
+        if (fingerprint !== await hashDirectory(project))
+            throw new Error("Native component project changed during context capture");
+        check();
+        const contexts = Object.fromEntries(ir.components.flatMap((component) => {
+            const binding = component.context_binding;
+            // Other, unreachable components cannot contribute a project or context grant.
+            // Preparation below requires a captured context for every reachable component.
+            if (!binding || typeof binding.project !== "string" || path.resolve(binding.project) !== project)
+                return [];
+            return [[component.id, { binding, snapshot }]];
+        }));
+        const bindings = createNativeComponentRuntimeBindings({ ...options, identity, contexts, currentIdentity, assertCurrent: check,
+            wren: { executable: options.wrenBinary, project, fingerprint, identity: accessIdentity } });
+        return bindings;
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}

package/dist-server/server/native-component-preparation.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentBrokerOptions } from "../harness/components/broker.js";
+import type { NativeComponentIdentity, NativeComponentPreparation } from "./native-components.js";
+/** The certified provisioner supplies bindings; this module derives scope/closure authority. */
+export interface NativeComponentBindings {
+    readonly identity: NativeComponentIdentity;
+    readonly contexts: ComponentBrokerOptions["contexts"];
+    readonly verifierBinary: string;
+    readonly prepare: ComponentBrokerOptions["prepare"];
+    readonly step: ComponentBrokerOptions["step"];
+    readonly normalize: ComponentBrokerOptions["normalize"];
+    readonly persistRoot?: ComponentBrokerOptions["persistRoot"];
+    readonly onEvent?: ComponentBrokerOptions["onEvent"];
+    currentIdentity(): NativeComponentIdentity | undefined;
+    /** Includes exact executable/account/generation and context snapshot provenance. */
+    assertCurrent(): void;
+}
+/** Select only composed eligible roots; direct non-composed vendor entries retain their path. */
+export declare function prepareNativeComponentHost(irDocument: string, scope: Readonly<Record<string, unknown>>, bindings: NativeComponentBindings): NativeComponentPreparation | undefined;
+/** Direct Codex sessions pin one root even when it has no child components. */
+export declare function prepareDirectCodexComponentHost(irDocument: string, scope: Readonly<Record<string, unknown>>, bindings: NativeComponentBindings): NativeComponentPreparation;

package/dist-server/server/native-component-preparation.js

@@ -0,0 +1,129 @@
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { createComponentBroker } from "../harness/components/broker.js";
+import { HOST_FEATURES, planDigest } from "../harness/components/plan.js";
+const nodeSchema = z.object({ id: z.string().min(1), verb: z.string().min(1), entrypoint: z.boolean().optional(),
+    type: z.literal("analytical"), realization_kind: z.literal("skill"), trigger: z.object({ kind: z.literal("one_shot") }),
+    required_capabilities: z.array(z.string()), guardrails: z.array(z.record(z.string(), z.unknown())),
+    context_binding: z.record(z.string(), z.unknown()),
+    llm_calls: z.array(z.object({ tier: z.string().min(1), component_calls: z.array(z.object({ alias: z.string(), component: z.string() })).optional() }).passthrough()),
+}).passthrough();
+const irSchema = z.object({ warble_ir_version: z.literal("0.9"), components: z.array(z.record(z.string(), z.unknown())) }).passthrough();
+const supportedGuards = new Set(["read_only_execution", "row_limit", "statement_timeout", "deterministic_gate", "artifact_write", "additivity_guard", "drill_depth_limit"]);
+const execution = ["ordered_steps", "isolated_step_tools", "artifact_provenance", "per_step_tiers", "bounded_repair", "render_contract"];
+function freeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Select only composed eligible roots; direct non-composed vendor entries retain their path. */
+export function prepareNativeComponentHost(irDocument, scope, bindings) {
+    return prepareHost(irDocument, scope, bindings, false);
+}
+/** Direct Codex sessions pin one root even when it has no child components. */
+export function prepareDirectCodexComponentHost(irDocument, scope, bindings) {
+    if (bindings.identity.vendor !== "codex")
+        throw new Error("Direct session requires Codex");
+    const prepared = prepareHost(irDocument, scope, bindings, true);
+    if (!prepared || Object.keys(prepared.hostRoots).length !== 1)
+        throw new Error("Direct session requires one entry");
+    return prepared;
+}
+function prepareHost(irDocument, scope, bindings, direct) {
+    bindings.assertCurrent();
+    const identity = freeze(structuredClone(bindings.identity));
+    const contexts = freeze(structuredClone(bindings.contexts));
+    const assertCurrent = bindings.assertCurrent.bind(bindings);
+    const currentIdentity = bindings.currentIdentity.bind(bindings);
+    const prepare = bindings.prepare, step = bindings.step, normalize = bindings.normalize;
+    const persistRoot = bindings.persistRoot, onEvent = bindings.onEvent, verifierBinary = bindings.verifierBinary;
+    const check = () => {
+        assertCurrent();
+        if (!isDeepStrictEqual(currentIdentity(), identity))
+            throw new Error("Native component binding expired");
+    };
+    check();
+    const ir = irSchema.parse(JSON.parse(irDocument));
+    const nodes = new Map(ir.components.map((node) => [z.string().min(1).parse(node.id), node]));
+    if (nodes.size !== ir.components.length)
+        throw new Error("Duplicate component identity");
+    const entry = z.union([
+        z.object({ kind: z.literal("scope"), prompt: z.string() }).strict(),
+        z.object({ kind: z.literal("agent").default("agent"), verb: z.string(), prompt: z.string() }).strict(),
+    ]).parse(scope.entry);
+    if (identity.vendor === "codex" && entry.kind !== "agent")
+        throw new Error("Codex requires a single pinned entry");
+    if (!isDeepStrictEqual(scope.binding, identity.binding))
+        throw new Error("Native component scope binding mismatch");
+    const eligible = [...nodes.values()].filter((node) => node.entrypoint !== false && (entry.kind === "scope" || node.verb === entry.verb));
+    if (entry.kind === "agent" && eligible.length !== 1)
+        throw new Error("Unknown or ambiguous pinned entry");
+    const roots = eligible.filter((node) => direct || z.array(z.object({ component_calls: z.array(z.unknown()).optional() }).passthrough()).parse(node.llm_calls)
+        .some((step) => (step.component_calls?.length ?? 0) > 0));
+    if (!roots.length)
+        return undefined;
+    const needed = new Set();
+    const hostRoots = Object.fromEntries(roots.map((root) => {
+        const visited = new Set();
+        const visiting = new Set();
+        const visit = (id, depth) => {
+            if (depth > 8 || visiting.has(id))
+                throw new Error("Invalid component invocation closure");
+            if (visited.has(id))
+                return;
+            const node = nodeSchema.parse(nodes.get(id));
+            visiting.add(id);
+            for (const guard of node.guardrails)
+                if (!supportedGuards.has(String(guard.name)))
+                    throw new Error("Unsupported native component guard");
+            for (const call of node.llm_calls)
+                for (const edge of call.component_calls ?? [])
+                    visit(edge.component, depth + 1);
+            visiting.delete(id);
+            visited.add(id);
+            needed.add(id);
+        };
+        visit(String(root.id), 0);
+        const components = Object.fromEntries([...visited].sort().map((id) => {
+            const node = nodeSchema.parse(nodes.get(id));
+            const context = contexts[id];
+            if (!context || !isDeepStrictEqual(context.binding, node.context_binding))
+                throw new Error("Missing or mismatched component context");
+            const capabilities = Object.fromEntries(node.required_capabilities.filter((capability) => !capability.startsWith("llm:")).map((capability) => {
+                if (capability === "sql_execution:read_only")
+                    return [capability, { tool: "query_read_only" }];
+                if (capability === "semantic_introspection")
+                    return [capability, { tool: "inspect_context" }];
+                if (["component_invocation", "artifact_write", "render_contract"].includes(capability))
+                    return [capability, {}];
+                throw new Error("Unsupported native component capability");
+            }));
+            return [id, { version: "2", tiers: [...new Set(node.llm_calls.map((call) => call.tier))], guardrails: node.guardrails, capabilities, execution }];
+        }));
+        return [String(root.id), { version: "2", protocol: "warble-component-host/1", execution: HOST_FEATURES, components }];
+    }));
+    freeze(hostRoots);
+    const selectedContexts = Object.fromEntries([...needed].sort().map((id) => [id, contexts[id]]));
+    const snapshots = Object.fromEntries(Object.entries(selectedContexts).map(([id, value]) => [id, value.snapshot]));
+    return freeze({
+        identity, hostRoots, contexts: freeze(snapshots), assertCurrent: check,
+        async host(root, plan, signal) {
+            check();
+            signal.throwIfAborted();
+            const descriptor = hostRoots[root];
+            if (!descriptor || plan.entries.length !== 1 || plan.entries[0] !== root || !isDeepStrictEqual(Object.keys(plan.components).sort(), Object.keys(descriptor.components).sort()))
+                throw new Error("Native component root mismatch");
+            const rootContexts = Object.fromEntries(Object.keys(plan.components).map((id) => [id, selectedContexts[id]]));
+            const brokerIdentity = { session: identity.session_id, vendor: identity.vendor, account: identity.auth_identity,
+                generation: identity.runtime_generation, project: identity.binding.project_identity, bindingRevision: identity.binding.revision,
+                contextDigest: planDigest(rootContexts), planDigest: plan.identity };
+            return createComponentBroker({ plan, contexts: rootContexts, verifierBinary,
+                identity: brokerIdentity, currentIdentity: () => { check(); return signal.aborted ? undefined : brokerIdentity; },
+                prepare, step, normalize, ...(persistRoot ? { persistRoot } : {}), ...(onEvent ? { onEvent } : {}),
+            });
+        },
+    });
+}

package/dist-server/server/native-component-runtime.d.ts

@@ -0,0 +1,36 @@
+import { type WrenAccessIdentity } from "../harness/components/wren-access.js";
+import type { NativeComponentBindings } from "./native-component-preparation.js";
+import { type ClaudeComponentRuntime } from "./runtime-host/claude-component-step.js";
+import { type CodexComponentPolicy } from "./runtime-host/codex-component-step.js";
+import type { RpcTransport } from "./runtime-host/codex-rpc.js";
+/** Injected only after vendor certification. This factory does not confer certification. */
+export type NativeComponentVendor = {
+    readonly authIdentity: string;
+    readonly accountEmail: string;
+    readonly generation: string;
+    readonly models: Readonly<Record<string, string>>;
+    assertCurrent(): void;
+    assertLive?(): void;
+} & ({
+    readonly vendor: "claude";
+    open(model: string, signal: AbortSignal): Promise<ClaudeComponentRuntime>;
+} | {
+    readonly vendor: "codex";
+    open(model: string, signal: AbortSignal): Promise<{
+        readonly transport: RpcTransport;
+        readonly policy: CodexComponentPolicy;
+    }>;
+});
+export interface NativeComponentRuntimeOptions extends Pick<NativeComponentBindings, "identity" | "contexts" | "verifierBinary" | "currentIdentity" | "assertCurrent" | "persistRoot" | "onEvent"> {
+    readonly vendor: NativeComponentVendor;
+    /** Optional cheap scope guard; integrity remains mandatory at protected operations. */
+    assertLive?(): void;
+    readonly wren: {
+        readonly executable: string;
+        readonly project: string;
+        readonly fingerprint: string;
+        readonly identity: WrenAccessIdentity;
+    };
+}
+/** Bind governed steps to one approved account and captured tier map; no outer-session transport. */
+export declare function createNativeComponentRuntimeBindings(options: NativeComponentRuntimeOptions): NativeComponentBindings;

package/dist-server/server/native-component-runtime.js

@@ -0,0 +1,92 @@
+import { isDeepStrictEqual } from "node:util";
+import { hashDirectory } from "../harness/compile/fingerprint.js";
+import { normalizeComponentEvidence } from "../harness/components/normalize.js";
+import { openWrenComponentAccess } from "../harness/components/wren-access.js";
+import { runClaudeComponentStep } from "./runtime-host/claude-component-step.js";
+import { runCodexComponentStep } from "./runtime-host/codex-component-step.js";
+/** Bind governed steps to one approved account and captured tier map; no outer-session transport. */
+export function createNativeComponentRuntimeBindings(options) {
+    const identity = structuredClone(options.identity);
+    const contexts = structuredClone(options.contexts);
+    const provider = options.vendor;
+    const vendor = provider.vendor;
+    const account = { authIdentity: provider.authIdentity, accountEmail: provider.accountEmail, generation: provider.generation };
+    const models = structuredClone(provider.models);
+    const assertBinding = options.assertCurrent.bind(options);
+    const currentIdentity = options.currentIdentity.bind(options);
+    const assertVendor = provider.assertCurrent.bind(provider);
+    const open = provider.open.bind(provider);
+    const wren = { ...options.wren };
+    const persistRoot = options.persistRoot;
+    const used = new WeakSet();
+    const assertBindingLive = options.assertLive?.bind(options) ?? assertBinding;
+    const assertVendorLive = provider.assertLive?.bind(provider) ?? assertVendor;
+    const checkIdentity = () => {
+        if (identity.vendor !== vendor || identity.auth_identity !== account.authIdentity || identity.runtime_generation !== account.generation
+            || !account.accountEmail || !isDeepStrictEqual(currentIdentity(), identity)
+            || provider.vendor !== vendor || provider.authIdentity !== account.authIdentity || provider.accountEmail !== account.accountEmail
+            || provider.generation !== account.generation || !isDeepStrictEqual(provider.models, models))
+            throw new Error("Native component runtime binding expired");
+    };
+    const check = () => { assertBinding(); assertVendor(); checkIdentity(); };
+    const checkLive = () => { assertBindingLive(); assertVendorLive(); checkIdentity(); };
+    check();
+    const checkAccess = async (signal) => {
+        signal.throwIfAborted();
+        check();
+        await wren.identity.assertCurrent();
+        if (await hashDirectory(wren.project) !== wren.fingerprint)
+            throw new Error("Native component project changed");
+        signal.throwIfAborted();
+        check();
+    };
+    return {
+        identity, contexts, verifierBinary: options.verifierBinary, currentIdentity, assertCurrent: check,
+        ...(persistRoot ? { persistRoot: async (...args) => { await checkAccess(args[2]); await persistRoot(...args); } } : {}), ...(options.onEvent ? { onEvent: options.onEvent } : {}),
+        async prepare(component, _identity, signal) {
+            await checkAccess(signal);
+            if (component.steps.some((step) => !models[step.tier]))
+                throw new Error("Missing native component tier binding");
+            if (component.steps.every((step) => step.tools.length === 0))
+                return {
+                    async query() { throw new Error("No component query grant"); }, async inspect() { throw new Error("No component context grant"); }, async close() { },
+                };
+            return openWrenComponentAccess({ ...wren, signal });
+        },
+        async step(run, component) {
+            await checkAccess(run.signal);
+            const model = models[run.tier];
+            if (!model || !component.steps.some((step) => step.tier === run.tier))
+                throw new Error("Missing native component step binding");
+            const resource = await open(model, run.signal);
+            const transport = "transport" in resource ? resource.transport : resource;
+            let closing;
+            const close = () => closing ??= transport.close();
+            try {
+                await checkAccess(run.signal);
+                if (used.has(transport))
+                    throw new Error("Native component step requires a fresh runtime");
+                used.add(transport);
+                if (vendor === "codex" && "transport" in resource) {
+                    if (resource.policy.accountEmail !== account.accountEmail || resource.policy.model !== model)
+                        throw new Error("Native component account or model mismatch");
+                    const originalCheck = resource.policy.assertCurrent.bind(resource.policy);
+                    const originalLive = resource.policy.assertLive?.bind(resource.policy) ?? originalCheck;
+                    return await runCodexComponentStep({ listen: resource.transport.listen.bind(resource.transport), write: resource.transport.write.bind(resource.transport), close }, { ...resource.policy, assertCurrent() { check(); originalCheck(); },
+                        assertLive() { checkLive(); originalLive(); } }, run);
+                }
+                if (vendor === "claude" && !("transport" in resource)) {
+                    if (resource.account.email !== account.accountEmail || resource.model !== model)
+                        throw new Error("Native component account or model mismatch");
+                    const originalCheck = resource.assertCurrent.bind(resource);
+                    return await runClaudeComponentStep({ ...resource, query: resource.query.bind(resource), close, assertCurrent() { check(); originalCheck(); } }, run);
+                }
+                throw new Error("Native component vendor mismatch");
+            }
+            finally {
+                await close();
+            }
+        },
+        async normalize(component, evidence, signal, context) { await checkAccess(signal); return normalizeComponentEvidence(component, evidence, context); },
+    };
+}

package/dist-server/server/native-components.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { type ExecutionPlan, type RunnerHost } from "../harness/components/runner.js";
+import type { ComponentInvocationResult } from "@warble/claude-agent-sdk";
+export declare const NATIVE_COMPONENT_REQUEST_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly request: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 65536;
+        };
+    };
+    readonly required: readonly ["request"];
+};
+declare const launchHost: z.ZodObject<{
+    protocol: z.ZodLiteral<"warble-component-host/1">;
+    execution: z.ZodLiteral<"host_owned_steps">;
+    session_id: z.ZodString;
+    vendor: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+    }>;
+    auth_identity: z.ZodString;
+    runtime_generation: z.ZodString;
+    binding: z.ZodObject<{
+        project_identity: z.ZodString;
+        generation: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    host_plan_sha256: z.ZodString;
+    plan_path: z.ZodLiteral<".warble/component-plans.json">;
+    root_tools: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+export type NativeComponentIdentity = Pick<z.infer<typeof launchHost>, "session_id" | "vendor" | "auth_identity" | "runtime_generation" | "binding">;
+export interface NativeComponentReceipt {
+    readonly identity: NativeComponentIdentity;
+    readonly irDocument: string;
+    readonly scopeDocument: string;
+    readonly hostRoots: Readonly<Record<string, unknown>>;
+    readonly contexts: Readonly<Record<string, unknown>>;
+}
+export interface NativeComponentPlans {
+    readonly identity: NativeComponentIdentity;
+    readonly digest: string;
+    readonly roots: Readonly<Record<string, ExecutionPlan>>;
+    readonly tools: Readonly<Record<string, string>>;
+}
+/** Supplied by a certified server-side provisioner, never browser/runtime settings JSON. */
+export interface NativeComponentPreparation {
+    readonly identity: NativeComponentIdentity;
+    readonly hostRoots: Readonly<Record<string, unknown>>;
+    readonly contexts: Readonly<Record<string, unknown>>;
+    /** Revalidates the approved account and exact vendor execution generation. */
+    assertCurrent(): void;
+    host(root: string, plan: ExecutionPlan, signal: AbortSignal): Promise<RunnerHost>;
+}
+export declare function nativeComponentHostContract(prepared: NativeComponentPreparation): Readonly<Record<string, unknown>>;
+/** Correlate emitted launch/plan data with host-owned inputs, never model arguments. */
+export declare function readNativeComponentPlans(document: string, launch: unknown, receipt: NativeComponentReceipt): NativeComponentPlans;
+/** Per-session fixed-root admission. A tool name selects a root, never an active step. */
+export declare class NativeComponentAdmission {
+    private readonly current;
+    private readonly host;
+    private readonly controller;
+    private readonly requests;
+    private active;
+    private activeController;
+    private cleanupFailure;
+    private closing?;
+    private readonly plans;
+    constructor(plans: NativeComponentPlans, current: () => NativeComponentIdentity | undefined, host: (root: string, plan: ExecutionPlan, signal: AbortSignal) => Promise<RunnerHost>);
+    private check;
+    list(): readonly {
+        name: string;
+        description: string;
+        inputSchema: typeof NATIVE_COMPONENT_REQUEST_SCHEMA;
+    }[];
+    call(name: string, input: unknown, requestId: string | number, signal?: AbortSignal): Promise<ComponentInvocationResult>;
+    /** Browser detach cancels work while allowing the retained terminal to reconnect. */
+    cancelActive(): void;
+    close(): Promise<void>;
+}
+export {};

package/dist-server/server/native-components.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { canonicalPlanJson, planDigest, readExecutionPlan } from "../harness/components/plan.js";
+import { ComponentRunner } from "../harness/components/runner.js";
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const binding = z.object({ project_identity: z.string().min(1), generation: z.string().min(1), revision: z.string().min(1) }).strict();
+const identity = {
+    protocol: z.literal("warble-component-host/1"), execution: z.literal("host_owned_steps"),
+    session_id: z.string().min(1), vendor: z.enum(["claude", "codex"]), auth_identity: z.string().min(1),
+    runtime_generation: z.string().min(1), binding,
+};
+export const NATIVE_COMPONENT_REQUEST_SCHEMA = { type: "object", additionalProperties: false,
+    properties: { request: { type: "string", minLength: 1, maxLength: 65_536 } }, required: ["request"],
+};
+const rootTools = z.record(z.string(), z.string().regex(/^warble_run_[a-f0-9]{32}$/));
+const launchHost = z.object({ ...identity, host_plan_sha256: digest,
+    plan_path: z.literal(".warble/component-plans.json"), root_tools: rootTools,
+}).strict();
+const nativePlan = z.object({ ...identity, version: z.literal("1"), execution_status: z.literal("not_executed"),
+    host_plan_sha256: digest, input_ir_sha256: digest, scope_sha256: digest,
+    plans: z.record(z.string(), z.record(z.string(), z.unknown())), prepared_contexts: z.record(z.string(), digest),
+    root_tools: rootTools, request_schema: z.unknown(),
+}).strict();
+export function nativeComponentHostContract(prepared) {
+    prepared.assertCurrent();
+    return { version: "1", protocol: "warble-component-host/1", ...structuredClone(prepared.identity),
+        roots: structuredClone(prepared.hostRoots),
+        prepared_contexts: Object.fromEntries(Object.entries(prepared.contexts).map(([id, context]) => [id, planDigest(context)])),
+    };
+}
+function equal(left, right) {
+    if (!isDeepStrictEqual(left, right))
+        throw new Error("Native component receipt mismatch");
+}
+function bytesDigest(value) { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+/** Correlate emitted launch/plan data with host-owned inputs, never model arguments. */
+export function readNativeComponentPlans(document, launch, receipt) {
+    if (Buffer.byteLength(document) > 4 * 1024 * 1024)
+        throw new Error("Native component plan exceeds byte limit");
+    const raw = JSON.parse(document);
+    const parsed = nativePlan.parse(raw);
+    const descriptor = launchHost.parse(launch);
+    const { host_plan_sha256: claimed, ...payload } = raw;
+    equal(claimed, planDigest(payload));
+    equal(descriptor.host_plan_sha256, claimed);
+    for (const key of ["session_id", "vendor", "auth_identity", "runtime_generation", "binding"]) {
+        equal(parsed[key], receipt.identity[key]);
+        equal(descriptor[key], receipt.identity[key]);
+    }
+    equal(parsed.input_ir_sha256, bytesDigest(receipt.irDocument));
+    const scope = JSON.parse(receipt.scopeDocument);
+    // The v3 scope contract defaults an omitted entry kind to the pinned agent form.
+    if (scope.entry?.kind === undefined && typeof scope.entry?.verb === "string")
+        scope.entry.kind = "agent";
+    equal(parsed.scope_sha256, planDigest(scope));
+    equal(parsed.root_tools, descriptor.root_tools);
+    equal(parsed.request_schema, NATIVE_COMPONENT_REQUEST_SCHEMA);
+    equal(Object.keys(parsed.plans).sort(), Object.keys(receipt.hostRoots).sort());
+    equal(Object.keys(parsed.root_tools).sort(), Object.keys(parsed.plans).sort());
+    if (new Set(Object.values(parsed.root_tools)).size !== Object.keys(parsed.root_tools).length)
+        throw new Error("Duplicate native admission tool");
+    equal(parsed.prepared_contexts, Object.fromEntries(Object.entries(receipt.contexts).map(([id, context]) => [id, planDigest(context)])));
+    const ir = z.object({ context_binding: z.record(z.string(), z.unknown()), components: z.array(z.object({ id: z.string() }).passthrough()) }).passthrough().parse(JSON.parse(receipt.irDocument));
+    const declarations = Object.fromEntries(ir.components.map((component) => [component.id, component]));
+    const roots = Object.fromEntries(Object.entries(parsed.plans).map(([root, plan]) => {
+        equal(plan.entry, root);
+        const executable = readExecutionPlan(JSON.stringify(plan), { digest: digest.parse(plan.plan_sha256), inputIrDigest: parsed.input_ir_sha256,
+            contextBinding: ir.context_binding, declarations, directHostDocument: canonicalPlanJson(receipt.hostRoots[root]),
+        });
+        for (const id of Object.keys(executable.components))
+            if (!Object.hasOwn(receipt.contexts, id))
+                throw new Error("Missing native component context");
+        return [root, executable];
+    }));
+    return { identity: structuredClone(receipt.identity), digest: parsed.host_plan_sha256, roots, tools: parsed.root_tools };
+}
+/** Per-session fixed-root admission. A tool name selects a root, never an active step. */
+export class NativeComponentAdmission {
+    current;
+    host;
+    controller = new AbortController();
+    requests = new Set();
+    active;
+    activeController;
+    cleanupFailure = false;
+    closing;
+    plans;
+    constructor(plans, current, host) {
+        this.current = current;
+        this.host = host;
+        this.plans = structuredClone(plans);
+    }
+    check() {
+        this.controller.signal.throwIfAborted();
+        if (this.cleanupFailure)
+            throw new Error("Native component cleanup failed");
+        if (!isDeepStrictEqual(this.current(), this.plans.identity)) {
+            this.controller.abort();
+            throw new Error("Native component session expired");
+        }
+    }
+    list() {
+        this.check();
+        return Object.entries(this.plans.tools).map(([root, name]) => ({ name,
+            description: String(this.plans.roots[root].components[root].declaration.description ?? `Run ${root}`), inputSchema: NATIVE_COMPONENT_REQUEST_SCHEMA, }));
+    }
+    async call(name, input, requestId, signal) {
+        this.check();
+        const root = Object.entries(this.plans.tools).find(([, tool]) => tool === name)?.[0];
+        const parsed = z.object({ request: z.string().trim().min(1).max(65_536) }).strict().parse(input);
+        if (!root || Buffer.byteLength(JSON.stringify(parsed)) > 65_536)
+            throw new Error("Invalid native component request");
+        const key = JSON.stringify(requestId);
+        if (this.active || this.requests.has(key) || this.requests.size >= 1024)
+            throw new Error("Native component request is busy or replayed");
+        this.requests.add(key);
+        const activeController = new AbortController();
+        this.activeController = activeController;
+        const combined = AbortSignal.any([this.controller.signal, activeController.signal, ...(signal ? [signal] : [])]);
+        const plan = this.plans.roots[root];
+        const run = (async () => {
+            const host = await this.host(root, plan, combined);
+            this.check();
+            combined.throwIfAborted();
+            const runner = new ComponentRunner(plan, host);
+            const result = await runner.run(root, parsed, combined);
+            this.cleanupFailure ||= runner.cleanupFailed;
+            this.check();
+            combined.throwIfAborted();
+            return result;
+        })();
+        this.active = run;
+        try {
+            return await run;
+        }
+        finally {
+            this.active = undefined;
+            this.activeController = undefined;
+        }
+    }
+    /** Browser detach cancels work while allowing the retained terminal to reconnect. */
+    cancelActive() { this.activeController?.abort(); }
+    close() {
+        this.controller.abort();
+        return this.closing ??= (async () => {
+            let timer;
+            try {
+                await Promise.race([this.active?.catch(() => { }), new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("Native component cleanup timed out")), 5_000);
+                    })]);
+                if (this.cleanupFailure)
+                    throw new Error("Native component cleanup failed");
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        })();
+    }
+}

package/dist-server/server/native-dispatch-process.d.ts

@@ -0,0 +1,8 @@
+/** Bounded compiler process group; cancellation also reaps descendants before returning. */
+export declare function runNativeDispatchProcess(input: {
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+}): Promise<void>;