@guuey/host 0.1.0

package/dist/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * `@guuey/host` — the universal config-driven Guuey worker.
+ *
+ * Reads the resolved agent.json snapshot (`GUUEY_AGENT_SNAPSHOT`), lazily
+ * loads the runner for `snapshot.framework`, and drives one turn per
+ * `invoke`, emitting each framework-native event to fd-3 as a `native`
+ * WorkerEvent. The Router dispatches those to the matching
+ * `@silverprotocol/<framework>` normalizer. On the runner's result it emits
+ * `done`; on a throw it emits `error`; on `shutdown` (or stdin EOF) it exits.
+ *
+ * **Thin-wrapper contract:** the agent runtimes
+ * (`@anthropic-ai/claude-agent-sdk`, `@openai/agents`, `@google/adk`) are
+ * OPTIONAL PEER dependencies — the host is orchestration; the runtime is the
+ * installer's declaration (the platform pins them in
+ * `@guuey-private/host-shared`, the `/shared` composition package). Runners
+ * are loaded via dynamic `import()` so a pod only ever loads the one SDK its
+ * framework needs; a missing peer fails with an actionable install hint, not
+ * a bare module-resolution stack.
+ *
+ * Runs inside bubblewrap with NO IRSA — it never mints federation tokens. A
+ * federated MCP server's credentials are read from the well-known path the
+ * Router-side credential broker wrote: `<sessionDir>/.guuey/credentials/<srv>.json`.
+ *
+ * Protocol wiring (per `@guuey/worker`): Router→Worker control on fd 0 (stdin),
+ * Worker→Router events on fd 3. We use the raw emitter (NOT the text-only
+ * `serve(handler)`) because the host emits `native`.
+ */
+import { createWriteStream } from "node:fs";
+import { createEmitter, isInvoke, isShutdown, parseControl, } from "@guuey/worker";
+/**
+ * Per-framework runner registry: module path + the peer package whose absence
+ * is the overwhelmingly likely cause of an import failure (the install hint).
+ */
+const RUNNERS = {
+    "claude-agent-sdk": { module: "./frameworks/claude-runner.js", peer: "@anthropic-ai/claude-agent-sdk", agentEntry: false },
+    "openai-agents-sdk": { module: "./frameworks/openai-runner.js", peer: "@openai/agents", agentEntry: false },
+    "google-adk": { module: "./frameworks/google-adk.js", peer: "@google/adk", agentEntry: true },
+};
+/**
+ * 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 function assertGracefulSupport(framework, agentEntryEnv) {
+    if (agentEntryEnv === undefined || agentEntryEnv === "")
+        return;
+    const entry = RUNNERS[framework];
+    if (entry !== undefined && !entry.agentEntry) {
+        throw new Error(`@guuey/host: guuey.json#agent.entry (graceful mode) is not supported for framework "${framework}" yet — ` +
+            `only ${Object.entries(RUNNERS)
+                .filter(([, r]) => r.agentEntry)
+                .map(([f]) => f)
+                .join(", ")} run a dev-exported agent module. ` +
+            `Use a full worker (serveNative) for this framework, or remove agent.entry.`);
+    }
+}
+/** Parse the boot snapshot — the resolved `agent` section (a {@link GuueyAgent}). */
+function readSnapshot() {
+    const raw = process.env.GUUEY_AGENT_SNAPSHOT ?? "{}";
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("@guuey/host: GUUEY_AGENT_SNAPSHOT must be a JSON object (the agent section).");
+    }
+    return parsed;
+}
+/**
+ * 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 async function loadRunner(framework) {
+    const entry = RUNNERS[framework];
+    if (!entry) {
+        throw new Error(`@guuey/host: unknown framework "${framework}" — supported: ${Object.keys(RUNNERS).join(", ")}`);
+    }
+    try {
+        const mod = (await import(entry.module));
+        return mod.createRunner();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+            throw new Error(`@guuey/host: cannot load the "${framework}" runner — its runtime is an optional peer. ` +
+                `Install ${entry.peer} next to @guuey/host to run this framework. (${String(err)})`);
+        }
+        throw err;
+    }
+}
+/** Async-iterate NDJSON lines off stdin. */
+async function* lines(input) {
+    let buf = "";
+    for await (const chunk of input) {
+        buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let nl = buf.indexOf("\n");
+        while (nl !== -1) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (line.length > 0)
+                yield line;
+            nl = buf.indexOf("\n");
+        }
+    }
+    const tail = buf.trim();
+    if (tail.length > 0)
+        yield tail;
+}
+/** The worker loop: per `invoke` run the framework runner; on `shutdown`/EOF exit. */
+async function main() {
+    const snapshot = readSnapshot();
+    const framework = snapshot.framework ?? "claude-agent-sdk";
+    // fd 3 is the write end of the pipe the Router created at spawn.
+    const out = createWriteStream("", { fd: 3 });
+    const emit = createEmitter(out);
+    // Load ONCE at boot — the pod runs one framework for its whole life, and a
+    // missing peer must fail the first turn loudly, not lazily mid-session.
+    assertGracefulSupport(framework, process.env.GUUEY_AGENT_ENTRY);
+    const runner = await loadRunner(framework);
+    for await (const line of lines(process.stdin)) {
+        const msg = parseControl(line);
+        if (isShutdown(msg))
+            break;
+        if (!isInvoke(msg))
+            continue;
+        const { type: _type, ...turn } = msg;
+        // Turns are sequential — await this invoke before reading the next line.
+        await runner.runTurn(snapshot, turn, emit);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`@guuey/host fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/options.d.ts

@@ -0,0 +1,173 @@
+/**
+ * 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";
+/**
+ * The credential file the Router-side broker writes per invoke at
+ * `<sessionDir>/.guuey/credentials/<server>.json`. Shape from spec §7.1 (B2-mcp).
+ * `transport` is required so the worker knows which SDK arm to build 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;
+}
+/**
+ * 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>;
+/**
+ * Render prior context sections (conversation history, thread memory, working
+ * state) as a preamble and prepend to the system prompt. The SDK's `query()`
+ * accepts only the current `input` as `prompt`, so feeding context here is how
+ * an ephemeral worker gives the model memory across invokes.
+ *
+ * Empty sections are omitted; if all inputs are empty/undefined the original
+ * system prompt is returned unchanged. Exported for unit testing + reuse by the
+ * worker loop.
+ */
+export declare function withContextPreamble(systemPrompt: string, history: HistoryMessage[] | undefined, priorMemory: PriorMemoryRecord[] | undefined, priorState: JsonValue | undefined): string;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

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

package/dist/options.js

@@ -0,0 +1,248 @@
+import { GUUEY_DEFAULT_SYSTEM_PROMPT, defaultModelFor } from "@guuey/config";
+/**
+ * Default Claude model — only used when the snapshot omits `model`. Derived
+ * from the `@guuey/config` registry (single source of truth per the
+ * model-release playbook §8 item A) rather than a bare literal, so a
+ * registry default change propagates here automatically.
+ */
+const DEFAULT_MODEL = defaultModelFor("claude-agent-sdk");
+/** Default cap on agent-loop turns per user message (matches the SDK/runner default). */
+const DEFAULT_MAX_TURNS = 25;
+/**
+ * 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 const ENV_HOME_DIR = "GUUEY_HOME_DIR";
+export const ENV_APP_DIR = "GUUEY_APP_DIR";
+/**
+ * File tools enabled when GuueyFS layers are bound. `Bash` is added separately
+ * (see {@link BASH_TOOL}) so the two are independently testable.
+ */
+const FS_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep"];
+/**
+ * Real shell exec, enabled alongside the file tools when GuueyFS layers are
+ * bound. Unlike the source runner — which enabled `Bash` only when the SDK's OWN
+ * `sandbox:{}` block was on — this host runs entirely INSIDE the Router's
+ * bubblewrap jail, so the OS isolation is always present whenever fs is bound.
+ * The SDK `sandbox:{}` block is therefore NOT set here (it would spawn a nested
+ * bubblewrap inside the Router's bwrap); the Router's bwrap IS the isolation.
+ */
+const BASH_TOOL = "Bash";
+/**
+ * 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 function buildOptions(snapshot, ctx) {
+    const apiKey = ctx.apiKey;
+    const baseUrl = ctx.baseUrl;
+    const authToken = ctx.authToken;
+    // Require either the loopback proxy credentials (hosted/broker path) or a
+    // direct API key (local-dev fallback). Neither → fail loudly.
+    if (!((baseUrl !== undefined && authToken !== undefined) || apiKey)) {
+        throw new Error("@guuey/host: either (baseUrl + authToken) for the managed-LLM proxy, " +
+            "or ANTHROPIC_API_KEY for local dev, is required.");
+    }
+    // Snapshots reach the worker fully resolved — the CLI's loader inlines any
+    // `{file}` system prompt before upload. A `{file}` reaching the worker means
+    // someone hit the API directly with an un-resolved snapshot; reject loudly.
+    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.`);
+    }
+    const mcpServers = resolveMcpServers(ctx);
+    const allowedTools = buildAllowedTools(snapshot, Object.keys(mcpServers), Boolean(ctx.fs));
+    const systemPrompt = withContextPreamble(snapshot.systemPrompt ?? GUUEY_DEFAULT_SYSTEM_PROMPT, ctx.history, ctx.priorMemory, ctx.priorState);
+    const model = snapshot.model ?? DEFAULT_MODEL;
+    const maxTurns = snapshot.runtime?.maxTurns ?? DEFAULT_MAX_TURNS;
+    const fs = ctx.fs;
+    // Build the subprocess env. Two mutually-exclusive paths:
+    //
+    //  - Proxy path (baseUrl + authToken present): route the Claude CLI
+    //    subprocess through the managed-LLM broker. baseUrl + authToken are
+    //    spread LAST so a builder's snapshot.env cannot override them.
+    //    ANTHROPIC_API_KEY is intentionally absent — the proxy owns auth.
+    //    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC suppresses telemetry pings
+    //    that would bypass the proxy.
+    //
+    //  - Local-dev fallback (only apiKey present): pass the real key directly.
+    //    The guard above guarantees apiKey is non-null on this branch.
+    // Explicit Record<string, string> annotation prevents TypeScript from widening
+    // the ternary to a union `{ K: string } | {}`, which would make spread targets
+    // produce optional-undefined keys that conflict with Record<string, string>.
+    const fsEnv = fs
+        ? { [ENV_HOME_DIR]: fs.home, [ENV_APP_DIR]: fs.app }
+        : {};
+    let env;
+    if (baseUrl !== undefined && authToken !== undefined) {
+        env = {
+            ...(snapshot.env ?? {}),
+            ...fsEnv,
+            ANTHROPIC_BASE_URL: baseUrl,
+            ANTHROPIC_AUTH_TOKEN: authToken,
+            CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+        };
+    }
+    else {
+        // apiKey is guaranteed non-null by the guard; the if-check narrows the type.
+        if (!apiKey)
+            throw new Error("unreachable: apiKey guard should have prevented this path");
+        env = {
+            ANTHROPIC_API_KEY: apiKey,
+            ...(snapshot.env ?? {}),
+            ...fsEnv,
+        };
+    }
+    // Whether the operator pinned a Claude permission mode in agent.json. When
+    // set we forward it verbatim and let the SDK's mode govern the posture; when
+    // unset we install the auto-allow `canUseTool` below so the default no-code
+    // agent's Bash runs prompt-free (a never-answered prompt would hang the pod).
+    const explicitMode = snapshot.claude?.permissions?.mode;
+    const options = {
+        model,
+        mcpServers,
+        allowedTools,
+        // With GuueyFS layers bound, expose the file tools PLUS real `Bash`; without
+        // them this is byte-identical to the source (purely MCP-driven). `Bash` is
+        // safe here because the host already runs inside the Router's bubblewrap
+        // jail — that bwrap, NOT the SDK's own `sandbox:{}` block, is the isolation.
+        tools: fs ? [...FS_TOOLS, BASH_TOOL] : [],
+        // Settings isolation. Empty array = "no filesystem settings loaded" — guards
+        // against a future SDK change auto-pulling `~/.claude/settings.json` and
+        // leaking the operator's logged-in Claude Code MCPs into the tool catalog.
+        settingSources: [],
+        strictMcpConfig: true,
+        maxTurns,
+        env,
+        systemPrompt,
+        // GuueyFS binding (opt-in): session dir as cwd, home+app as extra roots.
+        ...(fs ? { cwd: fs.session, additionalDirectories: [fs.home, fs.app] } : {}),
+        // Permission posture. Two mutually-exclusive paths:
+        //
+        //  - Operator pinned `claude.permissions.mode` → forward it verbatim; the
+        //    operator owns the posture (e.g. `acceptEdits`).
+        //  - No explicit mode + fs bound → install an auto-allow `canUseTool`. In
+        //    the SDK permission flow (hooks → deny → allow → ask → mode/canUseTool),
+        //    `default` mode with no callback routes Bash subcommands through an
+        //    interactive permission prompt — which, in this headless ephemeral pod,
+        //    no one answers, so the agent would HANG. The auto-allow callback short-
+        //    circuits that: every tool the model picks (already constrained to
+        //    `tools`/`allowedTools` + `settingSources:[]` + `strictMcpConfig`) is
+        //    allowed without a prompt. This is safe precisely because the Router's
+        //    bubblewrap jail is the real isolation boundary — NOT the SDK's own
+        //    `sandbox:{}` block (which is intentionally absent to avoid a nested
+        //    bwrap inside the Router's bwrap). We do NOT use `bypassPermissions`
+        //    here: it requires `allowDangerouslySkipPermissions` and globally
+        //    disables hooks/deny-rule evaluation, whereas the callback keeps the
+        //    deny/hook stages intact while only collapsing the final ask stage.
+        ...(explicitMode
+            ? { permissionMode: explicitMode }
+            : fs
+                ? { canUseTool: autoAllowTool }
+                : {}),
+        ...(ctx.abortController ? { abortController: ctx.abortController } : {}),
+    };
+    return 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 const autoAllowTool = (_toolName, input) => Promise.resolve({ behavior: "allow", updatedInput: input });
+/**
+ * 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 function resolveMcpServers(ctx) {
+    const out = {};
+    for (const { name, cred } of ctx.listCredentials()) {
+        out[name] = {
+            type: cred.transport,
+            url: cred.url,
+            // Declared MCP servers ARE this agent's tool surface. Without
+            // alwaysLoad the CLI defers MCP tools behind its ToolSearch built-in —
+            // absent here (tools: []) — leaving the model tool-less. Empirically
+            // load-bearing; mirrors the scaffold template's worker (see
+            // create-agentic-app templates-src claude worker.ts).
+            alwaysLoad: true,
+            ...(Object.keys(cred.headers).length > 0 ? { headers: cred.headers } : {}),
+        };
+    }
+    return out;
+}
+/**
+ * Build the SDK's `allowedTools` array. MCP tools are auto-namespaced by the SDK
+ * as `mcp__<server>__<tool>`; we can't enumerate the namespaces ahead of time,
+ * so the allowlist is necessarily wildcard-ish.
+ *
+ * - explicit `tools.allowlist` → pass those literal names through.
+ * - else → allow every tool from every declared server via `mcp__<server>`.
+ *
+ * When GuueyFS layers are bound, the file tools AND `Bash` join the allowlist
+ * (an allow rule in the SDK permission flow), so the model may use them
+ * alongside the MCP allowlist. The auto-allow `canUseTool` (or the operator's
+ * pinned mode) governs whether those still prompt — see `buildOptions`.
+ */
+function buildAllowedTools(snapshot, declaredServerNames, fsBound) {
+    const explicit = snapshot.tools?.allowlist;
+    const base = explicit && explicit.length > 0
+        ? explicit.slice()
+        : declaredServerNames.map((s) => `mcp__${s}`);
+    return fsBound ? [...base, ...FS_TOOLS, BASH_TOOL] : base;
+}
+/**
+ * Render prior context sections (conversation history, thread memory, working
+ * state) as a preamble and prepend to the system prompt. The SDK's `query()`
+ * accepts only the current `input` as `prompt`, so feeding context here is how
+ * an ephemeral worker gives the model memory across invokes.
+ *
+ * Empty sections are omitted; if all inputs are empty/undefined the original
+ * system prompt is returned unchanged. Exported for unit testing + reuse by the
+ * worker loop.
+ */
+export function withContextPreamble(systemPrompt, history, priorMemory, priorState) {
+    const sections = [];
+    if (history && history.length > 0) {
+        sections.push([
+            "Prior conversation with this user, for context. Continue naturally;",
+            "do not repeat it back verbatim.",
+            "<conversation_history>",
+            ...history.map((m) => `${roleLabel(m.role)}: ${m.text}`),
+            "</conversation_history>",
+        ].join("\n"));
+    }
+    if (priorMemory && priorMemory.length > 0) {
+        sections.push([
+            "Facts you previously recorded for this thread. Treat as known.",
+            "<thread_memory>",
+            ...priorMemory.map((m) => `${m.key ?? "(unkeyed)"}: ${JSON.stringify(m.value)}`),
+            "</thread_memory>",
+        ].join("\n"));
+    }
+    if (priorState !== undefined) {
+        sections.push([
+            "Your working state carried from the previous turn.",
+            "<working_state>",
+            JSON.stringify(priorState, null, 2),
+            "</working_state>",
+        ].join("\n"));
+    }
+    if (sections.length === 0)
+        return systemPrompt;
+    return `${sections.join("\n\n")}\n\n${systemPrompt}`;
+}
+function roleLabel(role) {
+    return role === "agent" ? "Assistant" : "User";
+}

package/dist/preamble.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Framework-neutral context preamble, shared by every runner.
+ *
+ * Render prior context sections (conversation history, thread memory, working
+ * state) as a preamble and prepend to the system prompt. Ephemeral workers
+ * accept only the current `input` as the turn prompt, so feeding context here
+ * is how they give the model memory across invokes. The rendering is
+ * byte-identical across runners (the Python ADK host carried a verbatim port
+ * of this function; the JS ADK runner now shares the original).
+ *
+ * Empty sections are omitted; if all inputs are empty/undefined the original
+ * system prompt is returned unchanged.
+ */
+import type { HistoryMessage, JsonValue, PriorMemoryRecord } from "@guuey/worker";
+export declare function withContextPreamble(systemPrompt: string, history: HistoryMessage[] | undefined, priorMemory: PriorMemoryRecord[] | undefined, priorState: JsonValue | undefined): string;
+//# sourceMappingURL=preamble.d.ts.map

package/dist/preamble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preamble.d.ts","sourceRoot":"","sources":["../src/preamble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElF,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,EAAE,GAAG,SAAS,EACrC,WAAW,EAAE,iBAAiB,EAAE,GAAG,SAAS,EAC5C,UAAU,EAAE,SAAS,GAAG,SAAS,GAChC,MAAM,CAuCR"}

package/dist/preamble.js

@@ -0,0 +1,34 @@
+export function withContextPreamble(systemPrompt, history, priorMemory, priorState) {
+    const sections = [];
+    if (history && history.length > 0) {
+        sections.push([
+            "Prior conversation with this user, for context. Continue naturally;",
+            "do not repeat it back verbatim.",
+            "<conversation_history>",
+            ...history.map((m) => `${roleLabel(m.role)}: ${m.text}`),
+            "</conversation_history>",
+        ].join("\n"));
+    }
+    if (priorMemory && priorMemory.length > 0) {
+        sections.push([
+            "Facts you previously recorded for this thread. Treat as known.",
+            "<thread_memory>",
+            ...priorMemory.map((m) => `${m.key ?? "(unkeyed)"}: ${JSON.stringify(m.value)}`),
+            "</thread_memory>",
+        ].join("\n"));
+    }
+    if (priorState !== undefined) {
+        sections.push([
+            "Your working state carried from the previous turn.",
+            "<working_state>",
+            JSON.stringify(priorState, null, 2),
+            "</working_state>",
+        ].join("\n"));
+    }
+    if (sections.length === 0)
+        return systemPrompt;
+    return `${sections.join("\n\n")}\n\n${systemPrompt}`;
+}
+function roleLabel(role) {
+    return role === "agent" ? "Assistant" : "User";
+}