@guuey/host 0.1.0

package/dist/frameworks/google-adk.js

@@ -0,0 +1,269 @@
+/**
+ * Google-ADK runner — drives the OFFICIAL `@google/adk` (JS) per invoke and
+ * emits every native ADK `Event` to fd-3 for the Router's
+ * `createAdkNormalizer`. Replaces the Python ADK host (`guuey_adk_host`)
+ * behavior-for-behavior: same hello handshake, same context preamble, same
+ * per-invoke `InMemoryRunner` semantics, same final-text extraction.
+ *
+ * Deliberate mechanics (each one adversarially reviewed):
+ *
+ *  - **Lazy SDK load + single-copy rule.** `@google/adk` is an optional peer,
+ *    imported at runner creation — never at module top. In graceful mode
+ *    (`GUUEY_AGENT_ENTRY`, T3) the SDK is resolved from the AGENT ENTRY's own
+ *    tree via `createRequire(entryUrl)` so the dev's agent and this runner
+ *    share ONE copy (the dev's version wins in their lane); no-code resolves
+ *    from the host's own tree (the platform pin in
+ *    `@guuey-private/host-shared`).
+ *  - **`role: "user"` pinned on `newMessage`.** Omitting it 400s on tool
+ *    follow-ups (upstream adk-js#475); the pin is a mechanistically complete
+ *    mitigation for arbitrary-depth tool loops.
+ *  - **MCP = Streamable-HTTP only.** The JS `MCPToolset` speaks stdio +
+ *    Streamable-HTTP; a `transport: "sse"` credential is REJECTED with an
+ *    actionable error (the Python-era SSE arm has no JS mapping). Auth
+ *    headers ride `transportOptions.requestInit.headers` (the non-deprecated
+ *    channel).
+ *  - **Gemini arming is the documented env pair.** `@google/genai` reads
+ *    `GOOGLE_GEMINI_BASE_URL` (verified: getBaseUrl in genai 1.52) and the
+ *    ADK's GoogleLlm reads `GOOGLE_GENAI_API_KEY || GEMINI_API_KEY` — the
+ *    Router's `buildWorkerEnv` gemini arm injects exactly `GEMINI_API_KEY` +
+ *    `GOOGLE_GEMINI_BASE_URL`. ADK 1.3.0 exposes no programmatic
+ *    httpOptions path, so env IS the sanctioned channel here.
+ *
+ * NEVER rejects to the loop — every failure becomes a terminal `error` event
+ * (the wire contract the Python host also kept).
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { AGENT_ENTRY_ENV, WORKER_ROOT_ENV, loadAgentEntry, materializeAgent, nativeLoad, resolveAgentEntry, } from "../agent-entry.js";
+import { listCredentials } from "../creds.js";
+import { withContextPreamble } from "../preamble.js";
+import { resolveSdkVersion } from "../sdk-version.js";
+const ADK_FRAMEWORK = "google-adk";
+/**
+ * Given a require-resolved entry file inside a package, walk up to the
+ * package root and return the absolute path of the root export's `import`
+ * condition (string conditions only — `@google/adk` 1.3.0's shape), or
+ * `undefined` when there is no exports map / no import condition.
+ */
+export function importConditionEntry(resolvedEntry) {
+    let dir = dirname(resolvedEntry);
+    for (let depth = 0; depth < 6; depth++) {
+        const pkgPath = join(dir, "package.json");
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            if (pkg.name === ADK_PACKAGE) {
+                const root = typeof pkg.exports === "object" && pkg.exports !== null ? pkg.exports["."] : undefined;
+                const target = typeof root === "object" && root !== null ? root.import : undefined;
+                return typeof target === "string" ? join(dir, target) : undefined;
+            }
+        }
+        catch {
+            // not at this level — keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+const ADK_PACKAGE = "@google/adk";
+const DEFAULT_MODEL = "gemini-3.5-flash";
+/**
+ * Load `@google/adk`, honoring the single-copy rule: when `entryPath` (the
+ * graceful agent module) is given, resolve the SDK from THAT tree so the
+ * runner drives the same copy the dev's agent was built with; otherwise
+ * import from the host's own tree. A resolution failure surfaces as the
+ * actionable missing-peer error.
+ */
+export async function loadAdk(entryPath) {
+    try {
+        if (entryPath !== undefined) {
+            const entryRequire = createRequire(pathToFileURL(entryPath).href);
+            const resolved = entryRequire.resolve(ADK_PACKAGE);
+            // Dual-package hazard (review finding): `require.resolve` picks the
+            // exports REQUIRE condition (CJS build), but the dev's ESM agent module
+            // `import`s the IMPORT condition (ESM build) — same version, two module
+            // instances. Re-resolve the IMPORT-condition entry from the package
+            // root so the runner drives the SAME instance the dev's agent was
+            // built with; fall back to the require resolution when the package has
+            // no exports map (plain `main`).
+            return nativeLoad(importConditionEntry(resolved) ?? resolved);
+        }
+        return (await import(ADK_PACKAGE));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+            throw new Error(`@guuey/host: cannot load the "${ADK_FRAMEWORK}" runner — its runtime is an optional peer. ` +
+                `Install ${ADK_PACKAGE} ${entryPath !== undefined ? `next to the agent entry (${entryPath})` : "next to @guuey/host"} ` +
+                `to run this framework. (${String(err)})`);
+        }
+        throw err;
+    }
+}
+/**
+ * Map the broker's credential files to ADK MCP toolsets. Throws on an `sse`
+ * credential — the JS toolset has no SSE transport (unlike the Python-era
+ * host); the error names the server and the supported path.
+ */
+export function buildToolsets(adk, creds) {
+    return creds.map(({ name, cred }) => {
+        if (cred.transport === "sse") {
+            throw new Error(`@guuey/host: MCP server "${name}" uses transport "sse", which @google/adk's MCPToolset does not support ` +
+                `(Streamable-HTTP only). Point the server at a Streamable-HTTP endpoint or use a different framework for this agent.`);
+        }
+        return new adk.MCPToolset({
+            type: "StreamableHTTPConnectionParams",
+            url: cred.url,
+            transportOptions: { requestInit: { headers: cred.headers } },
+        });
+    });
+}
+/**
+ * Extract a native event's last non-thought text part ("" when none).
+ * Structural narrowing from `JsonValue` — the event stays untyped JSON on its
+ * way to the normalizer; only this thin slice is inspected.
+ */
+export function finalTextOf(event) {
+    let finalText = "";
+    if (typeof event !== "object" || event === null || Array.isArray(event))
+        return finalText;
+    const content = event.content;
+    if (typeof content !== "object" || content === null || Array.isArray(content))
+        return finalText;
+    const parts = content.parts;
+    if (!Array.isArray(parts))
+        return finalText;
+    for (const part of parts) {
+        if (typeof part !== "object" || part === null || Array.isArray(part))
+            continue;
+        const { text, thought } = part;
+        if (typeof text === "string" && text !== "" && thought !== true)
+            finalText = text;
+    }
+    return finalText;
+}
+/**
+ * One turn against a caller-supplied agent + module (the seam graceful mode
+ * (T3) and the unit tests share). Emits hello → native* → done|error.
+ */
+export async function runAdkTurn(adk, agent, turn, emit, sdkVersion) {
+    emit.hello(ADK_FRAMEWORK, ADK_PACKAGE, sdkVersion);
+    try {
+        const runner = new adk.InMemoryRunner({ agent });
+        const session = await runner.sessionService.createSession({
+            appName: runner.appName,
+            userId: turn.identity.userId,
+        });
+        let finalText = "";
+        for await (const event of runner.runAsync({
+            userId: turn.identity.userId,
+            sessionId: session.id,
+            // `role` pinned — see the module header (adk-js#475).
+            newMessage: { role: "user", parts: [{ text: turn.input }] },
+            // SSE streaming, matching the Python host's RunConfig(streaming_mode=SSE)
+            // — the ADK default is NONE, which silently drops incremental text
+            // (review finding). "sse" is StreamingMode.SSE's literal value.
+            runConfig: { streamingMode: "sse" },
+        })) {
+            // The full native event passes to the normalizer untouched; JS events
+            // are already the camelCase shapes the AdkEvent contract expects.
+            emit.native(ADK_FRAMEWORK, event);
+            finalText = finalTextOf(event) || finalText;
+        }
+        emit.done(finalText, "end_turn");
+    }
+    catch (err) {
+        // never propagate to the wire
+        emit.error(err instanceof Error ? `${err.name}: ${err.message}` : String(err));
+    }
+}
+/**
+ * Assemble the per-turn {@link GuueyContext} — the ONE discoverable object a
+ * graceful factory receives (spec §2.2). `instruction` carries the standard
+ * context preamble already prepended; the raw fields ride alongside for
+ * factories that render context themselves.
+ */
+export function buildGuueyContext(snapshot, turn, instruction, mcpToolsets) {
+    return {
+        model: snapshot.model ?? DEFAULT_MODEL,
+        instruction,
+        mcpToolsets,
+        user: { id: turn.identity.userId, authMode: turn.identity.authMode },
+        files: { app: turn.fs.app, home: turn.fs.home, session: turn.fs.session },
+        history: turn.history.map((m) => ({ role: m.role, text: m.text })),
+        memory: (turn.priorMemory ?? []).map((m) => (m.key !== undefined ? { key: m.key, value: m.value } : { value: m.value })),
+        workingState: turn.priorState,
+    };
+}
+export function createRunner(deps = {}) {
+    const load = deps.load ?? loadAdk;
+    // Graceful mode: guuey.json#agent.entry → GUUEY_AGENT_ENTRY (relative),
+    // resolved strictly under the worker root. Read once at runner creation —
+    // the pod runs one agent module for its whole life.
+    const entryRel = process.env[AGENT_ENTRY_ENV];
+    const workerRoot = process.env[WORKER_ROOT_ENV];
+    let boot;
+    return {
+        async runTurn(snapshot, turn, emit) {
+            boot ??= (async () => {
+                if (entryRel !== undefined && entryRel !== "") {
+                    const entryPath = resolveAgentEntry(entryRel, workerRoot);
+                    // Single-copy rule: the SDK comes from the AGENT's own tree.
+                    const adk = await load(entryPath);
+                    const exported = await loadAgentEntry(entryPath);
+                    return { adk, exported, entryPath };
+                }
+                return { adk: await load(), exported: undefined };
+            })();
+            let adk;
+            let exported;
+            let entryPath;
+            try {
+                ({ adk, exported, entryPath } = await boot);
+            }
+            catch (err) {
+                emit.hello(ADK_FRAMEWORK, ADK_PACKAGE, null);
+                emit.error(err instanceof Error ? err.message : String(err));
+                return;
+            }
+            const sdkVersion = resolveSdkVersion(ADK_PACKAGE, entryPath);
+            // Snapshots reach the worker fully resolved — a `{file}` systemPrompt
+            // here means an un-resolved snapshot hit the API directly; reject loudly
+            // (same posture as the claude path).
+            if (snapshot.systemPrompt !== undefined && typeof snapshot.systemPrompt !== "string") {
+                emit.hello(ADK_FRAMEWORK, ADK_PACKAGE, sdkVersion);
+                emit.error(`@guuey/host: snapshot.systemPrompt must be a resolved string (got ${JSON.stringify(snapshot.systemPrompt)}).`);
+                return;
+            }
+            const instruction = withContextPreamble(snapshot.systemPrompt ?? "", turn.history, turn.priorMemory, turn.priorState);
+            let agent;
+            try {
+                const toolsets = buildToolsets(adk, listCredentials(turn.fs)());
+                if (exported !== undefined) {
+                    // Graceful: the dev's export (plain agent or factory(GuueyContext)).
+                    const ctx = buildGuueyContext(snapshot, turn, instruction, toolsets);
+                    agent = await materializeAgent(exported, ctx, (message) => process.stderr.write(`${message}\n`));
+                }
+                else {
+                    // No-code: construct from the snapshot.
+                    agent = new adk.LlmAgent({
+                        name: "guuey",
+                        model: snapshot.model ?? DEFAULT_MODEL,
+                        instruction,
+                        tools: toolsets,
+                    });
+                }
+            }
+            catch (err) {
+                emit.hello(ADK_FRAMEWORK, ADK_PACKAGE, sdkVersion);
+                emit.error(err instanceof Error ? `${err.name}: ${err.message}` : String(err));
+                return;
+            }
+            await runAdkTurn(adk, agent, turn, emit, sdkVersion);
+        },
+    };
+}

package/dist/frameworks/openai-runner.d.ts

@@ -0,0 +1,3 @@
+import type { FrameworkRunner } from "../index.js";
+export declare function createRunner(): FrameworkRunner;
+//# sourceMappingURL=openai-runner.d.ts.map

package/dist/frameworks/openai-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-runner.d.ts","sourceRoot":"","sources":["../../src/frameworks/openai-runner.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,aAAa,CAAC;AAgB3E,wBAAgB,YAAY,IAAI,eAAe,CAW9C"}

package/dist/frameworks/openai-runner.js

@@ -0,0 +1,37 @@
+/**
+ * OpenAI runner module — the `FrameworkRunner` adapter around the existing
+ * openai turn loop (`openai.ts#runInvokeOpenai`). Imports the SDK at module
+ * top level so the host's lazy `import()` of this file is what pulls the
+ * optional peer.
+ *
+ * Credential posture (unchanged from the pre-restructure host): the key (or
+ * opaque broker token in hosted mode) is applied globally to the SDK via
+ * `setDefaultOpenAIKey` once at runner creation. The OpenAI SDK also reads
+ * `OPENAI_BASE_URL` + `OPENAI_API_KEY` from env directly, so the broker env
+ * injected by the Router's `buildWorkerEnv` already routes it.
+ */
+import { run as openaiRun, setDefaultOpenAIKey } from "@openai/agents";
+import { runInvokeOpenai } from "./openai.js";
+import { listCredentials } from "../creds.js";
+import { buildHostContext } from "../boot-context.js";
+/**
+ * The real `@openai/agents` `run` (streamed overload), narrowed to the
+ * injected {@link OpenaiRunFn} surface the loop consumes. The SDK's `run` is
+ * generic over the agent + context; the loop only needs
+ * `(agent, input, {stream,maxTurns}) → a streamed result`. A typed adapter
+ * (NOT a cast) pins the streamed overload.
+ */
+const realOpenaiRun = (agent, input, options) => openaiRun(agent, input, { stream: true, ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}) });
+export function createRunner() {
+    const bootCtx = buildHostContext(process.env);
+    if (bootCtx.openaiKey !== undefined)
+        setDefaultOpenAIKey(bootCtx.openaiKey);
+    return {
+        async runTurn(snapshot, turn, emit) {
+            // Broker fields (`baseUrl`/`authToken`) are only wired for the Claude
+            // path — the OpenAI SDK reads its env directly.
+            const runtime = { listCredentials: listCredentials(turn.fs) };
+            await runInvokeOpenai(snapshot, turn, runtime, emit, realOpenaiRun);
+        },
+    };
+}

package/dist/frameworks/openai.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The OpenAI (`@openai/agents`) arm of the universal host loop. Mirrors
+ * `run.ts`'s `runInvoke` shape: one invoke → an `@openai/agents` `Agent` built
+ * from the snapshot, run streamed, each raw `RunStreamEvent` emitted to fd-3 as
+ * a `native('openai-agents-sdk', …)` WorkerEvent (the Router dispatches them to
+ * the `@silverprotocol/openai-agents` normalizer). On clean completion it emits
+ * `done`; on `MaxTurnsExceededError` it emits the `__host_error__` sentinel the
+ * normalizer maps to `turn.error` (code `max_turns`), THEN `done(..,"max_turns")`;
+ * on any other failure it emits `error`. Never throws — every failure path is a
+ * terminal event so the Router always sees one. Emits `hello` FIRST (§8 item B)
+ * — the SDK-version handshake.
+ *
+ * `run` (the `@openai/agents` runner) is injected so the loop is unit-testable
+ * without a live model — the entrypoint (`index.ts`) passes the real SDK `run`.
+ *
+ * Snapshot → Agent mapping:
+ *  - `model`        → `snapshot.model` (or the SDK's own default when absent —
+ *                     NOT Claude's; this is the OpenAI path).
+ *  - `instructions` → `systemPrompt` + the §1.4 context preamble (reuses
+ *                     `withContextPreamble`, identical to the Claude path).
+ *  - `mcpServers`   → the framework-neutral `resolveMcpServers` output (same
+ *                     federation/env-substitution as Claude), each `http`/`sse`
+ *                     entry → an `MCPServerStreamableHttp` carrying its
+ *                     `Authorization` (and any other) header via `requestInit`.
+ *  - `maxTurns`     → `snapshot.runtime?.maxTurns` (passed to `run(...)`; the SDK
+ *                     THROWS `MaxTurnsExceededError` from `stream.completed`).
+ *  - API key        → `OPENAI_API_KEY` (the Router sets it at pod boot), applied
+ *                     globally via `setDefaultOpenAIKey` by the entrypoint.
+ */
+import { Agent, type RunStreamEvent } from "@openai/agents";
+import type { Emitter } from "@guuey/worker";
+import type { HostInvoke, HostRuntime } from "./claude.js";
+import { type GuueyAgent } from "@guuey/config";
+/**
+ * The streamed-result surface the loop CONSUMES — exactly the three members it
+ * reads off the `@openai/agents` `StreamedRunResult`: async iteration over raw
+ * events, `completed` (which THROWS `MaxTurnsExceededError`), and the resolved
+ * `finalOutput`. A minimal structural interface (NOT the full `StreamedRunResult`
+ * class) so the real runner result AND a test fake both satisfy it without a cast
+ * — `StreamedRunResult` has private fields, so a plain object could never match
+ * the class, but it DOES match this read-only projection.
+ */
+export interface OpenaiRunResult extends AsyncIterable<RunStreamEvent> {
+    readonly completed: Promise<void>;
+    /** Resolved text output for the default text-output Agent (or `undefined`). */
+    readonly finalOutput?: string | undefined;
+}
+/**
+ * The `run` surface the loop needs — the real `@openai/agents` `run` (streamed
+ * overload) satisfies it (its `StreamedRunResult` is assignable to
+ * {@link OpenaiRunResult}). Injected so the loop is testable without a live model.
+ */
+export type OpenaiRunFn = (agent: Agent, input: string, options: {
+    stream: true;
+    maxTurns?: number;
+}) => Promise<OpenaiRunResult>;
+/**
+ * Run one invoke through `@openai/agents`. Emits `native` per `RunStreamEvent`,
+ * `done` on completion (with the `max_turns` sentinel + reason on a turn-cap),
+ * `error` on a build failure or any non-max-turns throw. Never throws.
+ */
+export declare function runInvokeOpenai(snapshot: GuueyAgent & {
+    framework?: string;
+}, invoke: HostInvoke, runtime: HostRuntime, emit: Emitter, run: OpenaiRunFn): Promise<void>;
+//# sourceMappingURL=openai.d.ts.map

package/dist/frameworks/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/frameworks/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EACL,KAAK,EAIL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,eAAe,CAAC;AAOxD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAQ7E;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa,CAAC,cAAc,CAAC;IACpE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KACzC,OAAO,CAAC,eAAe,CAAC,CAAC;AAgB9B;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,UAAU,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7C,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,IAAI,CAAC,CA4Gf"}

package/dist/frameworks/openai.js

@@ -0,0 +1,207 @@
+/**
+ * The OpenAI (`@openai/agents`) arm of the universal host loop. Mirrors
+ * `run.ts`'s `runInvoke` shape: one invoke → an `@openai/agents` `Agent` built
+ * from the snapshot, run streamed, each raw `RunStreamEvent` emitted to fd-3 as
+ * a `native('openai-agents-sdk', …)` WorkerEvent (the Router dispatches them to
+ * the `@silverprotocol/openai-agents` normalizer). On clean completion it emits
+ * `done`; on `MaxTurnsExceededError` it emits the `__host_error__` sentinel the
+ * normalizer maps to `turn.error` (code `max_turns`), THEN `done(..,"max_turns")`;
+ * on any other failure it emits `error`. Never throws — every failure path is a
+ * terminal event so the Router always sees one. Emits `hello` FIRST (§8 item B)
+ * — the SDK-version handshake.
+ *
+ * `run` (the `@openai/agents` runner) is injected so the loop is unit-testable
+ * without a live model — the entrypoint (`index.ts`) passes the real SDK `run`.
+ *
+ * Snapshot → Agent mapping:
+ *  - `model`        → `snapshot.model` (or the SDK's own default when absent —
+ *                     NOT Claude's; this is the OpenAI path).
+ *  - `instructions` → `systemPrompt` + the §1.4 context preamble (reuses
+ *                     `withContextPreamble`, identical to the Claude path).
+ *  - `mcpServers`   → the framework-neutral `resolveMcpServers` output (same
+ *                     federation/env-substitution as Claude), each `http`/`sse`
+ *                     entry → an `MCPServerStreamableHttp` carrying its
+ *                     `Authorization` (and any other) header via `requestInit`.
+ *  - `maxTurns`     → `snapshot.runtime?.maxTurns` (passed to `run(...)`; the SDK
+ *                     THROWS `MaxTurnsExceededError` from `stream.completed`).
+ *  - API key        → `OPENAI_API_KEY` (the Router sets it at pod boot), applied
+ *                     globally via `setDefaultOpenAIKey` by the entrypoint.
+ */
+import { Agent, MaxTurnsExceededError, MCPServerStreamableHttp, } from "@openai/agents";
+import { resolveMcpServers, withContextPreamble, } from "./claude-options.js";
+import { GUUEY_DEFAULT_SYSTEM_PROMPT } from "@guuey/config";
+import { resolveSdkVersion } from "../sdk-version.js";
+/** The framework tag this arm runs — matches the `AgentFramework` enum value. */
+const OPENAI_FRAMEWORK = "openai-agents-sdk";
+/** The npm package whose installed version is this framework's `hello.sdkVersion`. */
+const OPENAI_SDK_PACKAGE = "@openai/agents";
+/**
+ * Run one invoke through `@openai/agents`. Emits `native` per `RunStreamEvent`,
+ * `done` on completion (with the `max_turns` sentinel + reason on a turn-cap),
+ * `error` on a build failure or any non-max-turns throw. Never throws.
+ */
+export async function runInvokeOpenai(snapshot, invoke, runtime, emit, run) {
+    // The SDK-version handshake (§8 item B, additive-optional) — ALWAYS the
+    // first event of this invoke's fd-3 stream, before any native/turn event.
+    // `sdkVersion` is resolved at runtime, never hardcoded; `null` (SDK not
+    // resolvable) is tolerated by the Router.
+    emit.hello(OPENAI_FRAMEWORK, OPENAI_SDK_PACKAGE, resolveSdkVersion(OPENAI_SDK_PACKAGE));
+    // The host runs inside the Router's bubblewrap jail with NO IRSA; a federated
+    // MCP server reads its Router-written credential file. `resolveMcpServers`
+    // needs the same per-invoke context the Claude path builds.
+    const ctx = {
+        input: invoke.input,
+        identity: invoke.identity,
+        fs: invoke.fs,
+        history: invoke.history,
+        listCredentials: runtime.listCredentials,
+        ...(runtime.apiKey !== undefined ? { apiKey: runtime.apiKey } : {}),
+        ...(invoke.priorMemory !== undefined ? { priorMemory: invoke.priorMemory } : {}),
+        ...(invoke.priorState !== undefined ? { priorState: invoke.priorState } : {}),
+    };
+    // Build the Agent (+ connect its MCP servers). A build failure (e.g. an
+    // unresolved {file} system prompt, or an unsupported MCP arm) is a terminal
+    // `error` — never a throw out of this function.
+    let instructions;
+    let mcpServers;
+    try {
+        // Snapshots reach the worker fully resolved — the CLI inlines any `{file}`
+        // system prompt before upload. A non-string reaching the worker means a
+        // direct API hit with an un-resolved snapshot; reject loudly (same as Claude).
+        if (snapshot.systemPrompt !== undefined && typeof snapshot.systemPrompt !== "string") {
+            throw new Error(`@guuey/host: snapshot.systemPrompt must be a resolved string (got ${JSON.stringify(snapshot.systemPrompt)}). The CLI inlines {file} references before upload; workers never read the filesystem.`);
+        }
+        instructions = withContextPreamble(snapshot.systemPrompt ?? GUUEY_DEFAULT_SYSTEM_PROMPT, ctx.history, ctx.priorMemory, ctx.priorState);
+        mcpServers = buildOpenaiMcpServers(ctx);
+    }
+    catch (err) {
+        emit.error(err instanceof Error ? err.message : String(err));
+        return;
+    }
+    try {
+        for (const server of mcpServers) {
+            await server.connect();
+        }
+    }
+    catch (err) {
+        await closeAll(mcpServers);
+        emit.error(err instanceof Error ? err.message : String(err));
+        return;
+    }
+    try {
+        const maxTurns = snapshot.runtime?.maxTurns;
+        // `MCPServerStreamableHttp` IS an `MCPServer`; the Agent's `mcpServers` field
+        // is `MCPServer[]` — widen via the interface (no cast; structural subtype).
+        const servers = mcpServers;
+        const agent = new Agent({
+            name: "guuey-agent",
+            instructions,
+            mcpServers: servers,
+            ...(snapshot.model !== undefined ? { model: snapshot.model } : {}),
+        });
+        const stream = await run(agent, invoke.input, {
+            stream: true,
+            ...(maxTurns !== undefined ? { maxTurns } : {}),
+        });
+        // Drive the stream: each raw event crosses the wire as native.
+        for await (const ev of stream) {
+            emit.native(OPENAI_FRAMEWORK, toJson(ev));
+        }
+        // The runner THROWS `MaxTurnsExceededError` from `completed` AFTER the stream
+        // ends. Catch it specifically → feed the normalizer the `__host_error__`
+        // sentinel, then a terminal `done(.., "max_turns")`. Other throws → `error`.
+        try {
+            await stream.completed;
+        }
+        catch (err) {
+            if (err instanceof MaxTurnsExceededError) {
+                // The `__host_error__` sentinel — a fresh object literal so it is checked
+                // directly against `JsonValue` (the `native` payload type). Shape is the
+                // BINDING contract {@link HostErrorSentinel}.
+                emit.native(OPENAI_FRAMEWORK, {
+                    type: "__host_error__",
+                    code: "max_turns",
+                    message: err.message,
+                });
+                emit.done(finalText(stream), "max_turns");
+                return;
+            }
+            throw err;
+        }
+        emit.done(finalText(stream), "end_turn");
+    }
+    catch (err) {
+        emit.error(err instanceof Error ? err.message : String(err));
+    }
+    finally {
+        await closeAll(mcpServers);
+    }
+}
+/**
+ * The agent's final text output, or `""` when absent (a tool-only turn, or a
+ * turn cut short by `max_turns`). For the default text-output Agent `finalOutput`
+ * is `string | undefined`.
+ */
+function finalText(stream) {
+    const out = stream.finalOutput;
+    return typeof out === "string" ? out : "";
+}
+/**
+ * Translate the framework-neutral resolved MCP map → connected-capable
+ * `MCPServerStreamableHttp` instances. Each `http`/`sse` entry's `headers`
+ * (typically `{ authorization: 'Bearer <token>' }`, from the federation
+ * credential file or `${env.NAME}` substitution) ride on the underlying MCP
+ * transport's `RequestInit.headers` via `requestInit`.
+ *
+ * The cred dir only yields `http`/`sse` servers (the Router resolves all
+ * transport to one of those two); the `stdio` arm below is unreachable
+ * defensive code — kept so a future schema change can't silently drop a server.
+ */
+function buildOpenaiMcpServers(ctx) {
+    const resolved = resolveMcpServers(ctx);
+    const servers = [];
+    for (const [name, entry] of Object.entries(resolved)) {
+        servers.push(toOpenaiMcpServer(name, entry));
+    }
+    return servers;
+}
+/**
+ * One resolved `SdkMcpServer` → an `MCPServerStreamableHttp`. Both `http` and
+ * `sse` arms map to the StreamableHTTP server (the SDK's HTTP MCP transport);
+ * the `stdio` arm is unreachable (`resolveMcpServers` rejects colocated before
+ * we get here) — handled with a loud throw so a future schema change can't
+ * silently drop a server.
+ */
+function toOpenaiMcpServer(name, entry) {
+    if (entry.type === "stdio") {
+        throw new Error(`mcpServers["${name}"]: stdio (colocated) MCP is not supported on the OpenAI host path.`);
+    }
+    const headers = entry.headers;
+    return new MCPServerStreamableHttp({
+        url: entry.url,
+        name,
+        ...(headers && Object.keys(headers).length > 0 ? { requestInit: { headers } } : {}),
+        // `customDataExtractor` (agents 0.12+) is the ONLY channel that carries an
+        // MCP tool result's `structuredContent` onto the wire (`item.customData`)
+        // WITHOUT leaking it into model-visible text — without this, the ggui cache
+        // marker never reaches the normalizer and render metering goes blind.
+        // Mirrors the verified silverprotocol capture-agent wiring; the facet reads
+        // `item.customData.structuredContent`.
+        customDataExtractor: (context) => context.structuredContent !== undefined
+            ? { structuredContent: context.structuredContent }
+            : undefined,
+    });
+}
+/** Best-effort close of every connected MCP server (release the transport). */
+async function closeAll(servers) {
+    await Promise.allSettled(servers.map((s) => s.close()));
+}
+/**
+ * Coerce one `RunStreamEvent` to the `JsonValue` the `native` event carries.
+ * Stream events are plain JSON-serializable objects; the round-trip drops any
+ * non-JSON surface and yields the exact shape the Router's normalizer parses off
+ * the wire. Mirrors `run.ts`'s `toJson`.
+ */
+function toJson(ev) {
+    return JSON.parse(JSON.stringify(ev));
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { type Emitter, type Invoke } from "@guuey/worker";
+import type { GuueyAgent } from "@guuey/config";
+/** The snapshot shape the host boots from (`framework` selects the runner). */
+export type HostSnapshot = GuueyAgent & {
+    framework?: string;
+};
+/**
+ * One turn's input, as a runner receives it — the `Invoke` control message
+ * minus the discriminator.
+ */
+export type HostTurn = Omit<Invoke, "type">;
+/** The uniform surface every framework runner module exposes. */
+export interface FrameworkRunner {
+    /** Run one turn: drive the SDK, emit native events; resolve when the turn ends. */
+    runTurn(snapshot: HostSnapshot, turn: HostTurn, emit: Emitter): Promise<void>;
+}
+/**
+ * Graceful mode (`GUUEY_AGENT_ENTRY`) is per-runner: a framework whose runner
+ * ignores the entry env must FAIL LOUDLY, not silently run the no-code
+ * snapshot instead of the dev's module (review finding — "non-goal" means
+ * rejected, not ignored). Boot-time check, same posture as a missing peer.
+ */
+export declare function assertGracefulSupport(framework: string, agentEntryEnv: string | undefined): void;
+/**
+ * Load the runner for `framework`, translating a module-resolution failure
+ * into the actionable missing-peer message (the runtimes are optional peers —
+ * the host deliberately does not bundle them).
+ */
+export declare function loadRunner(framework: string): Promise<FrameworkRunner>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA6BA,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,MAAM,EACZ,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAYD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAahG;AAYD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAoB5E"}