@guuey/host 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @guuey/host
+
+The universal agent host for [guuey.com](https://guuey.com) — the injected
+harness that runs declarative (no-code) and graceful code-mode agents on
+Guuey pods, and locally under `guuey dev --serve`.
+
+**You usually don't install this directly.** It arrives two ways:
+
+- on Guuey pods, baked into the platform image (`/shared`);
+- locally, as a dependency of [`@guuey/cli`](https://www.npmjs.com/package/@guuey/cli),
+  which spawns it so your local loop matches production exactly.
+
+## What it does
+
+Reads the resolved agent snapshot, lazily loads the runner for the agent's
+framework, drives one turn per invoke, and streams the framework's native
+events to the platform (which normalizes them to AgJSON via
+`@silverprotocol/*`). Frameworks are **optional peer dependencies** — the
+host is orchestration; the runtime comes from the installer (on Guuey, the
+platform's pinned versions; in graceful mode, _your_ project's copy wins).
+
+| framework           | runner                                              | runtime peer                     |
+| ------------------- | --------------------------------------------------- | -------------------------------- |
+| `claude-agent-sdk`  | Claude Agent SDK loop                               | `@anthropic-ai/claude-agent-sdk` |
+| `openai-agents-sdk` | OpenAI Agents loop                                  | `@openai/agents`                 |
+| `google-adk`        | official Google ADK (`LlmAgent` + `InMemoryRunner`) | `@google/adk`                    |
+
+## Graceful mode
+
+If `guuey.json#agent.entry` names a module, the host imports it and runs
+your framework-native agent — plain export or factory:
+
+```ts
+import type { GuueyContext } from "@guuey/config";
+export default (guuey: GuueyContext) =>
+  new LlmAgent({
+    model: guuey.model,
+    instruction: guuey.instruction,
+    tools: [myTool, ...guuey.mcpToolsets],
+  });
+```
+
+Scaffold one with `npm create @guuey/agentic-app`.
+
+## License
+
+MIT © Loqu, Inc.

package/dist/agent-entry.d.ts

@@ -0,0 +1,38 @@
+import type { GuueyContext } from "@guuey/config";
+/**
+ * Load a module by absolute path with NODE's own resolution — opaque to
+ * bundlers/test transformers (vitest's SSR runner rewrites literal `import()`
+ * into its own resolver, which cannot load arbitrary runtime paths under
+ * /worker). `createRequire` + Node ≥22.12 `require(esm)` handles both CJS and
+ * ESM customer modules synchronously; a module using top-level await is the
+ * one unsupported shape (pathological for a per-invoke-loaded agent) and
+ * surfaces as Node's own ERR_REQUIRE_ASYNC_MODULE.
+ */
+export declare function nativeLoad(modulePath: string): unknown;
+/** Env var carrying the entry path (relative to the worker root). */
+export declare const AGENT_ENTRY_ENV = "GUUEY_AGENT_ENTRY";
+/** Env var overriding the worker root (defaults to the sandbox mount). */
+export declare const WORKER_ROOT_ENV = "GUUEY_WORKER_ROOT";
+/** The sandbox's worker mount — where builder-mode code lives. */
+export declare const DEFAULT_WORKER_ROOT = "/worker";
+/**
+ * Resolve `entry` (from guuey.json, customer-controlled) against the worker
+ * root, rejecting anything that escapes it. Returns the absolute entry path.
+ */
+export declare function resolveAgentEntry(entry: string, workerRoot?: string): string;
+/**
+ * Import the entry module and return its default export. A module without a
+ * default export is a contract error with an actionable message.
+ */
+export declare function loadAgentEntry(entryPath: string): Promise<unknown>;
+/**
+ * Materialize the agent from the entry's default export:
+ *  - a FUNCTION is the factory form — invoked (and awaited) with the
+ *    {@link GuueyContext};
+ *  - anything else is the plain-agent form, used as-is. Platform MCP toolsets
+ *    are NOT silently injected into a dev-constructed agent (no mutation
+ *    magic) — when servers are configured but the export is plain, `warn` is
+ *    called once with the factory-form hint.
+ */
+export declare function materializeAgent<TToolset>(exported: unknown, ctx: GuueyContext<TToolset>, warn: (message: string) => void): Promise<object>;
+//# sourceMappingURL=agent-entry.d.ts.map

package/dist/agent-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-entry.d.ts","sourceRoot":"","sources":["../src/agent-entry.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,sBAAsB,CAAC;AACnD,0EAA0E;AAC1E,eAAO,MAAM,eAAe,sBAAsB,CAAC;AACnD,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAA4B,GAAG,MAAM,CAcjG;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAC7C,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,YAAY,CAAC,QAAQ,CAAC,EAC3B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/dist/agent-entry.js

@@ -0,0 +1,87 @@
+/**
+ * Graceful-mode agent-entry loading: resolve the dev's module STRICTLY under
+ * the worker root, import it, and materialize the agent from its default
+ * export (plain agent object or `(GuueyContext) => agent` factory).
+ *
+ * Security posture: `GUUEY_AGENT_ENTRY` originates from customer-controlled
+ * `guuey.json#agent.entry`, so the resolved path MUST stay inside the worker
+ * root — traversal (`../…`, absolute escapes) is rejected before any import
+ * happens. The boundary this protects is tidiness, not secrecy (the sandbox
+ * is the real boundary; the host process holds nothing a full worker would
+ * not), but containment is cheap and closes the path-injection class.
+ */
+import { createRequire } from "node:module";
+import { isAbsolute, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * Load a module by absolute path with NODE's own resolution — opaque to
+ * bundlers/test transformers (vitest's SSR runner rewrites literal `import()`
+ * into its own resolver, which cannot load arbitrary runtime paths under
+ * /worker). `createRequire` + Node ≥22.12 `require(esm)` handles both CJS and
+ * ESM customer modules synchronously; a module using top-level await is the
+ * one unsupported shape (pathological for a per-invoke-loaded agent) and
+ * surfaces as Node's own ERR_REQUIRE_ASYNC_MODULE.
+ */
+export function nativeLoad(modulePath) {
+    return createRequire(pathToFileURL(modulePath).href)(modulePath);
+}
+/** Env var carrying the entry path (relative to the worker root). */
+export const AGENT_ENTRY_ENV = "GUUEY_AGENT_ENTRY";
+/** Env var overriding the worker root (defaults to the sandbox mount). */
+export const WORKER_ROOT_ENV = "GUUEY_WORKER_ROOT";
+/** The sandbox's worker mount — where builder-mode code lives. */
+export const DEFAULT_WORKER_ROOT = "/worker";
+/**
+ * Resolve `entry` (from guuey.json, customer-controlled) against the worker
+ * root, rejecting anything that escapes it. Returns the absolute entry path.
+ */
+export function resolveAgentEntry(entry, workerRoot = DEFAULT_WORKER_ROOT) {
+    if (isAbsolute(entry)) {
+        throw new Error(`@guuey/host: agent.entry must be a path relative to the worker root (got absolute "${entry}").`);
+    }
+    const root = resolve(workerRoot);
+    const resolved = resolve(root, entry);
+    if (resolved !== root && !resolved.startsWith(root + sep)) {
+        throw new Error(`@guuey/host: agent.entry "${entry}" escapes the worker root (${root}) — traversal is not allowed.`);
+    }
+    return resolved;
+}
+/**
+ * Import the entry module and return its default export. A module without a
+ * default export is a contract error with an actionable message.
+ */
+export async function loadAgentEntry(entryPath) {
+    const mod = nativeLoad(entryPath);
+    if (mod.default === undefined) {
+        throw new Error(`@guuey/host: the agent entry (${entryPath}) has no default export. ` +
+            `Export your framework-native agent object, or a factory (guuey: GuueyContext) => agent.`);
+    }
+    return mod.default;
+}
+/**
+ * Materialize the agent from the entry's default export:
+ *  - a FUNCTION is the factory form — invoked (and awaited) with the
+ *    {@link GuueyContext};
+ *  - anything else is the plain-agent form, used as-is. Platform MCP toolsets
+ *    are NOT silently injected into a dev-constructed agent (no mutation
+ *    magic) — when servers are configured but the export is plain, `warn` is
+ *    called once with the factory-form hint.
+ */
+export async function materializeAgent(exported, ctx, warn) {
+    if (typeof exported === "function") {
+        const agent = await exported(ctx);
+        if (typeof agent !== "object" || agent === null) {
+            throw new Error(`@guuey/host: the agent factory returned ${agent === null ? "null" : typeof agent} — expected the framework-native agent object.`);
+        }
+        return agent;
+    }
+    if (typeof exported !== "object" || exported === null) {
+        throw new Error(`@guuey/host: the agent entry's default export is ${exported === null ? "null" : typeof exported} — ` +
+            `expected an agent object or a factory function.`);
+    }
+    if (ctx.mcpToolsets.length > 0) {
+        warn(`@guuey/host: guuey.json declares ${ctx.mcpToolsets.length} MCP server(s), but the agent entry exports a plain agent — ` +
+            `platform MCP toolsets are NOT auto-injected. Export a factory ((guuey) => agent) and spread guuey.mcpToolsets into your tools to use them.`);
+    }
+    return exported;
+}

package/dist/boot-context.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure boot-context builder for `@guuey/host`.
+ *
+ * Extracted from `index.ts` so the env-reading logic is unit-testable without
+ * importing the worker entrypoint (which calls `main()` as a top-level side
+ * effect). `buildHostContext` is pure — no disk access, no I/O.
+ *
+ * OSS-legal: no guuey-private imports — only Node built-ins.
+ */
+/**
+ * Parts of the worker boot context derived from the process environment.
+ * Resolved once at worker startup by the entrypoint (`index.ts`); per-invoke
+ * context lives on `HostInvoke` + `HostRuntime` in `run.ts`.
+ */
+export interface HostBootContext {
+    /**
+     * OpenAI API key — or the opaque broker token in hosted mode (the Task 8
+     * `buildWorkerEnv` injects it as `OPENAI_API_KEY`). Applied globally to the
+     * SDK via `setDefaultOpenAIKey` before the first invoke. `undefined` means
+     * no OpenAI credentials are available.
+     */
+    openaiKey?: string;
+    /**
+     * Anthropic API key — the local-dev fallback when the managed-LLM broker is
+     * NOT configured. Absent in hosted (broker) mode; present for `guuey dev`
+     * and local testing.
+     */
+    anthropicApiKey?: string;
+    /**
+     * Loopback proxy base URL — hosted/broker mode. Task 8 injects this as
+     * `ANTHROPIC_BASE_URL` into the worker's env via `buildWorkerEnv`. When
+     * present together with `anthropicAuthToken`, the Claude CLI subprocess is
+     * routed through the managed-LLM broker; the real API key is intentionally
+     * absent so it cannot leak to agent code.
+     */
+    anthropicBaseUrl?: string;
+    /**
+     * Opaque session token for the loopback proxy — hosted/broker mode. Task 8
+     * injects this as `ANTHROPIC_AUTH_TOKEN`. Required when `anthropicBaseUrl`
+     * is set; ignored when only `anthropicApiKey` is present.
+     */
+    anthropicAuthToken?: string;
+}
+/**
+ * Build the host boot context from the process environment. Pure — no side
+ * effects, no disk access. Takes `env` as a parameter (rather than reading
+ * `process.env` directly) so the function is straightforward to unit-test.
+ */
+export declare function buildHostContext(env: NodeJS.ProcessEnv): HostBootContext;
+//# sourceMappingURL=boot-context.d.ts.map

package/dist/boot-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-context.d.ts","sourceRoot":"","sources":["../src/boot-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,eAAe,CAOxE"}

package/dist/boot-context.js

@@ -0,0 +1,22 @@
+/**
+ * Pure boot-context builder for `@guuey/host`.
+ *
+ * Extracted from `index.ts` so the env-reading logic is unit-testable without
+ * importing the worker entrypoint (which calls `main()` as a top-level side
+ * effect). `buildHostContext` is pure — no disk access, no I/O.
+ *
+ * OSS-legal: no guuey-private imports — only Node built-ins.
+ */
+/**
+ * Build the host boot context from the process environment. Pure — no side
+ * effects, no disk access. Takes `env` as a parameter (rather than reading
+ * `process.env` directly) so the function is straightforward to unit-test.
+ */
+export function buildHostContext(env) {
+    return {
+        openaiKey: env.OPENAI_API_KEY,
+        anthropicApiKey: env.ANTHROPIC_API_KEY,
+        anthropicBaseUrl: env.ANTHROPIC_BASE_URL,
+        anthropicAuthToken: env.ANTHROPIC_AUTH_TOKEN,
+    };
+}

package/dist/creds.d.ts

@@ -0,0 +1,26 @@
+import type { Fs } from "@guuey/worker";
+/**
+ * One parsed credential file. The shape is the broker's §7.1 contract — the
+ * worker consumes it verbatim without consulting the snapshot (the broker
+ * owns ALL resolution including transport).
+ */
+export interface CredentialFile {
+    /** The resolved MCP URL (may be scoped `<host>/apps/<id>` for federated ggui). */
+    url: string;
+    /** Transport the broker selected for this server. */
+    transport: "http" | "sse";
+    /** Headers to forward — typically `{ authorization: 'Bearer <token>' }`. */
+    headers: Record<string, string>;
+    /** ISO expiry; informational for the worker (the Router refreshes per invoke). */
+    expiresAt?: string;
+}
+/**
+ * Read all credential files the Router broker wrote for this invoke. Returns
+ * one `{ name, cred }` per valid `.json` file — malformed files are silently
+ * skipped (never crash the turn). Missing directory → empty array (no MCP).
+ */
+export declare function listCredentials(fs: Fs): () => Array<{
+    name: string;
+    cred: CredentialFile;
+}>;
+//# sourceMappingURL=creds.d.ts.map

package/dist/creds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creds.d.ts","sourceRoot":"","sources":["../src/creds.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,eAAe,CAAC;AAExC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC,CA6B3F"}

package/dist/creds.js

@@ -0,0 +1,45 @@
+/**
+ * Framework-neutral credential-file reading, shared by every runner.
+ *
+ * The Router-side credential broker resolves EVERYTHING (default server,
+ * federation, minting, env substitution) and writes one JSON file per MCP
+ * server to `<sessionDir>/.guuey/credentials/<server>.json` before each
+ * worker spawn. Runners only read and shape — no resolution logic here.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Read all credential files the Router broker wrote for this invoke. Returns
+ * one `{ name, cred }` per valid `.json` file — malformed files are silently
+ * skipped (never crash the turn). Missing directory → empty array (no MCP).
+ */
+export function listCredentials(fs) {
+    return () => {
+        const dir = join(fs.session, ".guuey", "credentials");
+        let names;
+        try {
+            names = readdirSync(dir).filter((n) => n.endsWith(".json"));
+        }
+        catch {
+            return []; // no cred dir this turn → no MCP.
+        }
+        const out = [];
+        for (const file of names) {
+            try {
+                const parsed = JSON.parse(readFileSync(join(dir, file), "utf8"));
+                if (typeof parsed === "object" &&
+                    parsed !== null &&
+                    !Array.isArray(parsed) &&
+                    typeof parsed.url === "string" &&
+                    (parsed.transport === "http" ||
+                        parsed.transport === "sse")) {
+                    out.push({ name: file.replace(/\.json$/, ""), cred: parsed });
+                }
+            }
+            catch {
+                // malformed file → skip (never crash the turn).
+            }
+        }
+        return out;
+    };
+}

package/dist/frameworks/claude-options.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Snapshot → Claude Agent SDK `Options` construction. Lifted from
+ * `backend/services/nocode-runtime/src/agent-runner.ts` (the pure-logic half),
+ * with the B2-mcp amendment: `@guuey/host` is a THIN CRED-DIR READER. All MCP
+ * resolution (default, federation, mint, env-substitution) now lives once on the
+ * Router-side credential broker. The worker just reads
+ * `<sessionDir>/.guuey/credentials/*.json` (via ctx.listCredentials) and shapes
+ * each entry into the framework-neutral `SdkMcpServer` map.
+ *
+ * Two responsibilities:
+ *
+ * 1. **Snapshot → SDK options mapping.** Translates the agent.json shape
+ *    (model, allowedTools, maxTurns, GuueyFS binding) and the cred-dir contents
+ *    into the Claude Agent SDK's `mcpServers` + `allowedTools` + `maxTurns`.
+ * 2. **Cred-dir mapping.** `resolveMcpServers(ctx)` globs the cred dir via
+ *    `ctx.listCredentials()` → one `SdkMcpServer` per file; ALL the old
+ *    federation/default/isGguiUrl/env-sub logic is DELETED (Router-side now).
+ *
+ * OSS-legality: this package imports ONLY `@anthropic-ai/claude-agent-sdk`,
+ * `@guuey/worker`, `@guuey/config`, and Node built-ins.
+ */
+import type { CanUseTool, Options, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { Fs, HistoryMessage, JsonValue } from "@guuey/worker";
+import { type GuueyAgent } from "@guuey/config";
+export type { SDKMessage };
+/**
+ * Env-var names the Router injects so agent code reaches the home/app layers
+ * portably. Host-owned copies of `@guuey/fs`'s `ENV_HOME_DIR`/`ENV_APP_DIR`
+ * (trivial string literals — not imported, to keep this package OSS-legal).
+ */
+export declare const ENV_HOME_DIR = "GUUEY_HOME_DIR";
+export declare const ENV_APP_DIR = "GUUEY_APP_DIR";
+export type { CredentialFile } from "../creds.js";
+import type { CredentialFile } from "../creds.js";
+/**
+ * SDK's `mcpServers` value shape — recreated structurally rather than imported
+ * because the SDK ships it as part of `Options['mcpServers']` (a record-of-union)
+ * and pulling out a single arm is awkward in TS.
+ */
+export type SdkMcpServer = {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+    alwaysLoad?: boolean;
+} | {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+    alwaysLoad?: boolean;
+} | {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    alwaysLoad?: boolean;
+};
+/**
+ * One prior memory record fed into the `<thread_memory>` preamble. Host-owned,
+ * minimal projection of `@silverprotocol/core`'s `AgMemoryRecord` (the preamble
+ * reads only `key`/`value`). Not imported — OSS-legality.
+ */
+export interface PriorMemoryRecord {
+    key?: string;
+    value: JsonValue;
+}
+/**
+ * Per-invoke context `buildOptions` needs beyond the static snapshot. Sourced by
+ * the worker loop from the `invoke` control message + boot env.
+ */
+export interface BuildOptionsContext {
+    /** The user message — passed to `query({ prompt })` by the caller. */
+    input: string;
+    /** Router-vouched end-user identity. */
+    identity: {
+        userId: string;
+        authMode: "anonymous" | "authenticated";
+    };
+    /**
+     * Anthropic API key — used for local-dev / off-sandbox fallback when
+     * `baseUrl` + `authToken` are absent. One of (`baseUrl`+`authToken`) or
+     * `apiKey` must be provided; `buildOptions` throws if neither is present.
+     */
+    apiKey?: string;
+    /**
+     * Loopback proxy base URL for the managed-LLM broker (`ANTHROPIC_BASE_URL`).
+     * When present together with `authToken`, the Claude CLI subprocess is routed
+     * through the broker; the real API key is intentionally omitted from
+     * `options.env` so it cannot leak to agent code.
+     */
+    baseUrl?: string;
+    /**
+     * Opaque session token for the loopback proxy (`ANTHROPIC_AUTH_TOKEN`).
+     * Required when `baseUrl` is set; ignored when only `apiKey` is present.
+     */
+    authToken?: string;
+    /**
+     * Per-session GuueyFS layer mounts (the invoke's `fs`). When present, the
+     * invoke binds `cwd`=session, exposes home+app as `additionalDirectories`,
+     * enables the file tools, and injects `GUUEY_*` env. Absent → no FS binding.
+     */
+    fs?: Fs;
+    /** Recent conversation window for the `<conversation_history>` preamble. */
+    history?: HistoryMessage[];
+    /** Thread-scoped memory for the `<thread_memory>` preamble (the §1.4 push). */
+    priorMemory?: PriorMemoryRecord[];
+    /** Prior working-state blob for the `<working_state>` preamble. */
+    priorState?: JsonValue;
+    /**
+     * Returns every credential the Router broker wrote to
+     * `<sessionDir>/.guuey/credentials/` this invoke — one `{name, cred}` per
+     * usable MCP server. `name` is the filename stem (server name); `cred` is the
+     * parsed `CredentialFile`. Injected so option-building stays pure (no disk).
+     */
+    listCredentials: () => Array<{
+        name: string;
+        cred: CredentialFile;
+    }>;
+    /** Cancels the in-flight `query` when the client disconnects. */
+    abortController?: AbortController;
+}
+/**
+ * Build the Claude Agent SDK `Options` for one invoke. Pure: all disk/env access
+ * is injected via {@link BuildOptionsContext}. Throws on an unresolved `{file}`
+ * system prompt or a missing API key (the same loud failures the source had).
+ */
+export declare function buildOptions(snapshot: GuueyAgent, ctx: BuildOptionsContext): Options;
+/**
+ * Auto-allow permission callback. Installed when fs is bound and the operator
+ * did NOT pin `claude.permissions.mode`, so the default no-code agent's `Bash`
+ * (and the file tools) run prompt-free. Returns `{ behavior: 'allow' }` for
+ * every request, passing the input through unchanged.
+ *
+ * Safe because the model's tool surface is already locked down BEFORE the
+ * callback ever fires — `tools`/`allowedTools` cap which tools exist,
+ * `settingSources:[]` blocks filesystem-loaded settings, `strictMcpConfig`
+ * pins the MCP catalog — and the real OS isolation is the Router's bubblewrap
+ * jail this whole process runs inside. The callback only collapses the SDK's
+ * final interactive "ask" stage (which would otherwise hang a headless pod);
+ * the earlier hook/deny-rule stages of the permission flow still run.
+ */
+export declare const autoAllowTool: CanUseTool;
+/**
+ * Map the Router-resolved cred files to the framework-neutral SdkMcpServer map.
+ * The Router (credential-broker) owns ALL resolution — default, federation, mint,
+ * env-substitution; this worker just reads `<session>/.guuey/credentials/*.json`
+ * (via ctx.listCredentials) and shapes each entry. Keyed by the server name.
+ */
+export declare function resolveMcpServers(ctx: BuildOptionsContext): Record<string, SdkMcpServer>;
+export { withContextPreamble } from "../preamble.js";
+//# sourceMappingURL=claude-options.d.ts.map

package/dist/frameworks/claude-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-options.d.ts","sourceRoot":"","sources":["../../src/frameworks/claude-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,KAAK,EAAE,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAgD,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE9F,YAAY,EAAE,UAAU,EAAE,CAAC;AAa3B;;;;GAIG;AACH,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAC7C,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAoB3C,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,GAAG,eAAe,CAAA;KAAE,CAAC;IACtE;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,EAAE,CAAC,EAAE,EAAE,CAAC;IACR,4EAA4E;IAC5E,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,mEAAmE;IACnE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IACrE,iEAAiE;IACjE,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CA6HpF;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,EAAE,UACiC,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAgBxF;AA8BD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}