melchizedek-agents 0.9.0

package/dist/lib/session/transcript.js

@@ -0,0 +1,309 @@
+/**
+ * Cross-agent transcript sharing.
+ *
+ * ── The problem this solves ───────────────────────────────────────────────
+ * Under plan-dispatch every route runs as its OWN root agent (XScout,
+ * Conversationalist, FinancialAnalyst) against ONE shared session. Sharing
+ * the session is necessary but not sufficient: ADK decides how a stored
+ * event is rendered into a prompt by comparing `event.author` against the
+ * agent that is running, and every prior event fails that comparison the
+ * moment the route changes. `convertForeignEvent` then rewrites each one to
+ * `role: "user"` prefixed with "For context:".
+ *
+ * Replaying a real production session — a four-turn thread that had passed
+ * through three routes — through ADK's own content processor showed what the
+ * last route actually received: 15 contents, 118,013 bytes, and EVERY ONE of them
+ * `role: "user"`. Not a single `role: "model"` turn in the prompt. The
+ * history was all there — and unreadable as a conversation, because nothing
+ * in it was marked as having been said by the desk. That is the "it doesn't
+ * know what I'm referring to" failure, and no amount of session sharing
+ * fixes it, because sharing was never the broken part.
+ *
+ * Two further leaks rode along in the same conversion. `convertForeignEvent`
+ * clones any part it does not recognise verbatim, so the previous route's
+ * private chain-of-thought ("**My Micron Monday Decision Strategy** Okay, so
+ * the question is…", `thought: true`) arrived as USER speech. And raw tool
+ * payloads were inlined as text — one `load_memory` result alone was 23,502
+ * characters, one `get_company_fundamentals` 8,953 — all of it handed to a
+ * 400-character, tool-less flash-lite route that could do nothing with it.
+ *
+ * ── The fix ───────────────────────────────────────────────────────────────
+ * Project the stored transcript before ADK ever sees it: rewrite each past
+ * agent turn to the CURRENT agent's name so it survives as a real
+ * `role: "model"` turn, label it with the desk that spoke, and drop what no
+ * successor can use — thoughts, tool calls, tool results.
+ *
+ * The projection is a READ-TIME view. The stored session keeps everything,
+ * verbatim, because long-term memory ingestion reads the real record.
+ */
+import { BaseSessionService } from '@google/adk';
+const DEFAULT_MAX_HISTORY_CHARS = 40_000;
+const DEFAULT_MAX_HISTORY_TURNS = 16;
+const DEFAULT_MAX_TURN_CHARS = 4_000;
+/**
+ * Longest tool result kept in the DURABLE record. See {@link trimEventForStorage}.
+ */
+export const DEFAULT_MAX_STORED_PAYLOAD_CHARS = 2_000;
+/**
+ * The text a successor can actually read: spoken output only.
+ *
+ * Excluded, deliberately:
+ *  - `thought: true` parts — another agent's reasoning is not conversation,
+ *    and ADK's own foreign-event conversion leaks it as user speech.
+ *  - function calls and their results — the successor cannot re-enter that
+ *    tool loop, and the payloads dwarf the answers they produced.
+ *  - `toolCall` / `toolResponse` parts (the camelCase shape some providers
+ *    emit) — invisible to ADK's `part.functionCall` checks, so they survive
+ *    its conversion untouched and arrive as empty noise.
+ */
+function spokenText(event) {
+    const parts = (event.content?.parts ?? []);
+    return parts
+        .filter(p => !p.thought && !p.functionCall && !p.functionResponse && !p.toolCall && !p.toolResponse)
+        .map(p => (typeof p.text === 'string' ? p.text : ''))
+        .join('')
+        .trim();
+}
+function elide(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit)}\n[…turn truncated]`;
+}
+/**
+ * Render a stored transcript as history the given agent can read.
+ *
+ * User events pass through untouched. Every agent event becomes a
+ * `role: "model"` turn ATTRIBUTED to `forAgent`, which is what keeps ADK
+ * from rewriting it into "For context:" user text — with the original
+ * author kept as a visible `[Name]` label when it was a different desk, so
+ * attribution survives without costing the turn structure.
+ *
+ * Events that said nothing out loud (a pure tool call, a pure tool result)
+ * disappear entirely. Calls and their responses are dropped together, so
+ * ADK's function-response pairing never sees a widowed half.
+ *
+ * Pure and synchronous — see tests/transcript.test.ts.
+ */
+export function projectTranscript(events, forAgent, options = {}) {
+    const maxHistory = options.maxHistoryChars ?? DEFAULT_MAX_HISTORY_CHARS;
+    const maxTurns = options.maxHistoryTurns ?? DEFAULT_MAX_HISTORY_TURNS;
+    const maxTurn = options.maxTurnChars ?? DEFAULT_MAX_TURN_CHARS;
+    const kept = [];
+    let budget = maxHistory;
+    // Backwards: whichever ceiling binds first, it is the OLDEST context that
+    // goes. The newest exchange is always the one the user is talking about.
+    for (let i = events.length - 1; i >= 0 && kept.length < maxTurns; i--) {
+        const event = events[i];
+        if (event.author === 'user') {
+            const text = spokenText(event);
+            if (!text)
+                continue;
+            budget -= text.length;
+            kept.push(event);
+            if (budget <= 0)
+                break;
+            continue;
+        }
+        const text = spokenText(event);
+        if (!text)
+            continue;
+        const label = event.author && event.author !== forAgent ? `[${event.author}] ` : '';
+        const body = `${label}${elide(text, maxTurn)}`;
+        budget -= body.length;
+        kept.push({
+            ...event,
+            author: forAgent,
+            content: { role: 'model', parts: [{ text: body }] },
+        });
+        if (budget <= 0)
+            break;
+    }
+    return kept.reverse();
+}
+/**
+ * Strip from an event what no reader of the STORED session will ever use.
+ *
+ * ── What the durable record is actually made of ───────────────────────────
+ * Measured across 128 live sessions, by part field:
+ *
+ *     thoughtSignature            14.14 MB   73.3%
+ *     functionResponse.response    2.07 MB   10.8%
+ *     text (the conversation)      1.86 MB    9.6%
+ *     toolResponse.response        1.06 MB    5.5%
+ *
+ * Nine-tenths of every byte stored is machinery. `thoughtSignature` is the
+ * opaque base64 blob Gemini attaches for thought continuity — a single part
+ * of it reached 115 KB — and tool payloads are the rest, the largest being
+ * Gemini's grounding `search_suggestions`, an HTML and CSS widget attached
+ * to every web-search result.
+ *
+ * Beware the shape of this data when measuring it: bucketing a part by
+ * whichever tool key it carries attributes the whole part to the tool
+ * response, when the weight is in a sibling field. That misattribution said
+ * "76% is tool results" and predicted a 70% saving from eliding payloads
+ * alone; the real saving from that change was 12%.
+ *
+ * ── Why none of it is needed ──────────────────────────────────────────────
+ * The stored row has exactly two readers. {@link projectTranscript} drops
+ * thought parts and tool traffic entirely on the way into a prompt, so a
+ * stored signature is never replayed to a model. The memory service's
+ * `serializeEvents` walks `part.text` alone, so a payload has never
+ * contributed one extracted fact. Everything above is written, re-uploaded
+ * on every later event in the turn (this service re-upserts the whole
+ * array), and re-fetched whole next turn — for nothing. One live session had
+ * reached 1.17 MB; a 60-turn conversation uploaded ~288 MB getting there.
+ *
+ * ── What survives ─────────────────────────────────────────────────────────
+ * A trimmed response KEEPS its shape: `id` and `name` are preserved and only
+ * the body is replaced, because ADK pairs calls to responses by id
+ * (`rearrangeEventsForLatestFunctionResponse` throws on a widowed half), so
+ * an elided result must remain a result. The marker records what was dropped
+ * and how big it was — what an operator reading the row needs. Small results
+ * pass through untouched: they are cheap, and a short one is occasionally
+ * the only record of what a number was.
+ *
+ * ── The one constraint on changing this ───────────────────────────────────
+ * Dropping `thoughtSignature` is safe BECAUSE the projection never feeds
+ * stored events back to a model. Anything that starts replaying raw stored
+ * events into Gemini would need the signature preserved, or lose thought
+ * continuity across a resumed session.
+ *
+ * Pure: returns a new event, never mutates the input. The caller applies it
+ * to the SERIALIZED COPY only — the live in-memory session must keep both
+ * signature and payloads, or the agent's own tool loop breaks mid-turn.
+ */
+export function trimEventForStorage(event, maxPayloadChars = DEFAULT_MAX_STORED_PAYLOAD_CHARS) {
+    const parts = event.content?.parts;
+    if (!parts?.length)
+        return event;
+    let trimmedAny = false;
+    const next = parts.map(part => {
+        let out = part;
+        // The dominant cost, and never read back from storage.
+        if (out.thoughtSignature !== undefined) {
+            const { thoughtSignature, ...rest } = out;
+            out = rest;
+            trimmedAny = true;
+        }
+        // Both spellings occur: `functionResponse` is ADK's, `toolResponse` comes
+        // from providers whose parts ADK passes through untouched.
+        const key = out.functionResponse ? 'functionResponse' : out.toolResponse ? 'toolResponse' : null;
+        if (!key)
+            return out;
+        const holder = out[key];
+        const body = holder?.response;
+        if (body === undefined)
+            return out;
+        const size = typeof body === 'string' ? body.length : JSON.stringify(body).length;
+        if (size <= maxPayloadChars)
+            return out;
+        trimmedAny = true;
+        return {
+            ...out,
+            [key]: {
+                ...holder,
+                response: {
+                    elided: `${size.toLocaleString()} chars dropped before storage — tool results are not read back by any consumer (lib/session/transcript.ts)`,
+                },
+            },
+        };
+    });
+    if (!trimmedAny)
+        return event;
+    return { ...event, content: { ...event.content, parts: next } };
+}
+/**
+ * A compact plain-text digest of the exchange, for an agent that must be
+ * given history as INPUT rather than as conversation.
+ *
+ * The dispatch classifier is that agent. It runs in its own lane so its JSON
+ * verdicts never pollute the user-facing transcript — and the cost of that
+ * isolation, in production, was a router that had never seen a single answer
+ * it routed. On 2026-08-15 its lane held four user messages and four of its
+ * own verdicts, nothing else; a user's counter-argument to the desk's
+ * MU/SNDK/NVDA/AMD call therefore read as a remark with no request behind
+ * it, and went to small talk. Its own rules ("follow-ups on prior analysis →
+ * FinancialAnalyst") were unusable, because no prior analysis was in view.
+ *
+ * @param maxTurns        newest N exchanges to show
+ * @param maxCharsPerTurn per-line budget — the router classifies, it does not
+ *                        read; the shape of an answer is enough
+ */
+export function renderTranscriptDigest(events, { maxTurns = 8, maxCharsPerTurn = 400 } = {}) {
+    const lines = [];
+    for (let i = events.length - 1; i >= 0 && lines.length < maxTurns; i--) {
+        const event = events[i];
+        const text = spokenText(event);
+        if (!text)
+            continue;
+        // The per-message date marker is harness plumbing, not conversation, and
+        // it would consume a quarter of every line's budget.
+        const clean = text.replace(/^\[System Context:[^\]]*\]\s*/, '').replace(/\s+/g, ' ').trim();
+        if (!clean)
+            continue;
+        const speaker = event.author === 'user' ? 'user' : event.author || 'desk';
+        lines.push(`${speaker}: ${clean.length > maxCharsPerTurn ? `${clean.slice(0, maxCharsPerTurn)}…` : clean}`);
+    }
+    return lines.reverse().join('\n');
+}
+/**
+ * A read-time projection over another session service.
+ *
+ * `getSession` returns the transcript as {@link projectTranscript} renders it
+ * for one named agent; every write goes to the REAL session held underneath,
+ * so the durable record keeps thoughts, tool calls and full payloads for
+ * long-term memory ingestion and for operators reading the row.
+ *
+ * Both views are kept live during a turn: the runner appends to the
+ * projected session it is holding (it re-reads `session.events` before every
+ * model call, so the agent's own in-flight tool calls must stay visible and
+ * unprojected), while the same event is appended and persisted to the real
+ * one. Only history is projected; the current turn never is.
+ *
+ * Construct one per turn — it is bound to a single agent name.
+ */
+export class ProjectedSessionService extends BaseSessionService {
+    inner;
+    forAgent;
+    options;
+    /** Real sessions handed out by `getSession`, keyed by identity. */
+    stored = new Map();
+    constructor(inner, forAgent, options = {}) {
+        super();
+        this.inner = inner;
+        this.forAgent = forAgent;
+        this.options = options;
+    }
+    key(appName, userId, sessionId) {
+        return `${appName}:${userId}:${sessionId}`;
+    }
+    async createSession(request) {
+        return this.inner.createSession(request);
+    }
+    async listSessions(request) {
+        return this.inner.listSessions(request);
+    }
+    async deleteSession(request) {
+        this.stored.delete(this.key(request.appName, request.userId, request.sessionId));
+        return this.inner.deleteSession(request);
+    }
+    async getSession(request) {
+        const real = await this.inner.getSession(request);
+        if (!real)
+            return undefined;
+        this.stored.set(this.key(request.appName, request.userId, request.sessionId), real);
+        return {
+            ...real,
+            events: projectTranscript(real.events, this.forAgent, this.options),
+        };
+    }
+    async appendEvent(request) {
+        const { session, event } = request;
+        if (event.partial)
+            return event;
+        // The runner's view (projected) — base class merges state deltas.
+        await super.appendEvent({ session, event });
+        // The durable record (real), persisted by the wrapped service.
+        const real = this.stored.get(this.key(session.appName, session.userId, session.id));
+        await this.inner.appendEvent({ session: real && real !== session ? real : session, event });
+        return event;
+    }
+}

package/dist/lib/toolRegistry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * lib/toolRegistry.ts — single source of truth mapping YAML tool names to
+ * live ADK tool instances.
+ *
+ * WHY this exists:
+ *   a2a_server.ts and syndicate_chat.ts each carried an identical `resolveTools`
+ *   switch. The two copies had already begun to drift. Centralising the mapping
+ *   here means a newly added tool is available to every entrypoint at once.
+ */
+/**
+ * Resolve an array of tool-name strings to live ADK tool instances.
+ * Unknown names are skipped; `onUnknown` (if provided) is invoked for each so
+ * callers can log in their own format.
+ */
+export declare function resolveTools(toolNames?: string[], onUnknown?: (name: string) => void): any[];

package/dist/lib/toolRegistry.js

@@ -0,0 +1,58 @@
+/**
+ * lib/toolRegistry.ts — single source of truth mapping YAML tool names to
+ * live ADK tool instances.
+ *
+ * WHY this exists:
+ *   a2a_server.ts and syndicate_chat.ts each carried an identical `resolveTools`
+ *   switch. The two copies had already begun to drift. Centralising the mapping
+ *   here means a newly added tool is available to every entrypoint at once.
+ */
+import { GOOGLE_SEARCH, LOAD_MEMORY, PRELOAD_MEMORY, } from '@google/adk';
+import { COLLECTIONS_SEARCH } from "./tools/collectionsSearchTool.js";
+import { generateImageTool } from "./tools/generateImageTool.js";
+import { inspectImageTool } from "./tools/inspectImageTool.js";
+import { toFunctionTool } from "./tools/toolContract.js";
+import { WEB_SEARCH } from "./tools/webSearchTool.js";
+import { WIKI_AGENT_TOOL_CONTRACTS } from "./tools/wikiTools.js";
+import { X_SEARCH } from "./tools/xSearchTool.js";
+// Knowledge-bundle tools, derived from their contracts so the YAML names
+// can never drift from the definitions. The agentic composites
+// (wiki_query/wiki_garden) are deliberately absent: a syndicate reaches
+// that behavior by being an agent WITH these primitives.
+const WIKI_TOOLS = Object.fromEntries(WIKI_AGENT_TOOL_CONTRACTS.map((contract) => [
+    contract.name,
+    toFunctionTool(contract),
+]));
+const TOOL_MAP = {
+    ...WIKI_TOOLS,
+    // Provider-agnostic web search: routes to the model's NATIVE search
+    // (Gemini grounding / Anthropic / OpenAI / xAI); omitted with a warning
+    // for local models. Prefer this in new YAMLs.
+    web_search: WEB_SEARCH,
+    x_search: X_SEARCH,
+    // xAI-only: semantic search over hosted Collections (XAI_COLLECTION_IDS).
+    collections_search: COLLECTIONS_SEARCH,
+    // Gemini-only ADK grounding tool, kept for backward compatibility.
+    google_search: GOOGLE_SEARCH,
+    generate_image: generateImageTool,
+    inspect_image: inspectImageTool,
+    load_memory: LOAD_MEMORY,
+    preload_memory: PRELOAD_MEMORY,
+};
+/**
+ * Resolve an array of tool-name strings to live ADK tool instances.
+ * Unknown names are skipped; `onUnknown` (if provided) is invoked for each so
+ * callers can log in their own format.
+ */
+export function resolveTools(toolNames = [], onUnknown) {
+    return toolNames
+        .map((name) => {
+        const tool = TOOL_MAP[name];
+        if (tool === undefined) {
+            onUnknown?.(name);
+            return null;
+        }
+        return tool;
+    })
+        .filter(Boolean);
+}

package/dist/lib/tools/collectionsSearchTool.d.ts

@@ -0,0 +1,55 @@
+/**
+ * lib/tools/collectionsSearchTool.ts — xAI Collections search, sentinel-style.
+ *
+ * WHY this file exists:
+ *   xAI's Agent Tools API can search "Collections" — hosted document stores
+ *   (PDFs, text, CSVs) uploaded at console.x.ai or via the management API —
+ *   semantic RAG run SERVER-SIDE, with citations back to source files
+ *   (collections://<collection_id>/files/<file_id>). Declaring
+ *   `collections_search` in an agent's YAML tools list turns it on for
+ *   grok-* agents; xAI decides retrieval, we never ship documents in the
+ *   prompt.
+ *
+ * HOW IT WORKS (mirrors xSearchTool.ts exactly):
+ *   The sentinel self-registers in llmRequest.toolsDict; _getDeclaration()
+ *   returns undefined so it is never sent as a client-side function tool.
+ *   The GptLlm/GrokLlm request builder calls wantsCollectionsSearch() and
+ *   appends the OpenAI-compatible wire shape:
+ *     { type: 'file_search', vector_store_ids: [...], max_num_results? }
+ *
+ * WHICH COLLECTIONS: ids come from the environment, not YAML —
+ *   XAI_COLLECTION_IDS (comma-separated) names the collections, and
+ *   XAI_COLLECTIONS_MAX_RESULTS optionally caps retrieved chunks. Ids are
+ *   deployment configuration (they differ per account/stage), which is
+ *   what .env is for; the YAML stays shareable. Declared with no ids
+ *   configured, the tool is omitted with a warning — never fatal.
+ *
+ * SCOPE: xAI-only. OpenAI's Responses API shares the file_search wire
+ *   shape but searches OPENAI vector stores — a different product with
+ *   different ids — so this sentinel gates to grok-* models and is a
+ *   silent no-op everywhere else (same non-throwing routing contract as
+ *   web_search / x_search).
+ */
+import { BaseTool } from '@google/adk';
+import type { LlmRequest } from '@google/adk';
+export declare const COLLECTIONS_SEARCH_TOOL_NAME = "collections_search";
+export declare class CollectionsSearchTool extends BaseTool {
+    constructor();
+    /** Never a client-side function tool — xAI runs retrieval server-side. */
+    _getDeclaration(): undefined;
+    /** Server-side tool: nothing to execute locally. */
+    runAsync(): Promise<unknown>;
+    processLlmRequest({ llmRequest }: {
+        llmRequest: LlmRequest;
+    }): Promise<void>;
+}
+/** Shared instance, mirroring WEB_SEARCH / X_SEARCH. */
+export declare const COLLECTIONS_SEARCH: CollectionsSearchTool;
+/** True when the agent requested collections search (xAI sentinel path). */
+export declare function wantsCollectionsSearch(llmRequest: LlmRequest): boolean;
+/** Sentinel test used by the request builder to skip function-tool emission. */
+export declare function isCollectionsSearchSentinel(tool: unknown): boolean;
+/** Collection ids from XAI_COLLECTION_IDS (comma-separated, trimmed). */
+export declare function collectionIdsFromEnv(): string[];
+/** Optional retrieval cap from XAI_COLLECTIONS_MAX_RESULTS (positive int). */
+export declare function collectionsMaxResultsFromEnv(): number | undefined;

package/dist/lib/tools/collectionsSearchTool.js

@@ -0,0 +1,86 @@
+/**
+ * lib/tools/collectionsSearchTool.ts — xAI Collections search, sentinel-style.
+ *
+ * WHY this file exists:
+ *   xAI's Agent Tools API can search "Collections" — hosted document stores
+ *   (PDFs, text, CSVs) uploaded at console.x.ai or via the management API —
+ *   semantic RAG run SERVER-SIDE, with citations back to source files
+ *   (collections://<collection_id>/files/<file_id>). Declaring
+ *   `collections_search` in an agent's YAML tools list turns it on for
+ *   grok-* agents; xAI decides retrieval, we never ship documents in the
+ *   prompt.
+ *
+ * HOW IT WORKS (mirrors xSearchTool.ts exactly):
+ *   The sentinel self-registers in llmRequest.toolsDict; _getDeclaration()
+ *   returns undefined so it is never sent as a client-side function tool.
+ *   The GptLlm/GrokLlm request builder calls wantsCollectionsSearch() and
+ *   appends the OpenAI-compatible wire shape:
+ *     { type: 'file_search', vector_store_ids: [...], max_num_results? }
+ *
+ * WHICH COLLECTIONS: ids come from the environment, not YAML —
+ *   XAI_COLLECTION_IDS (comma-separated) names the collections, and
+ *   XAI_COLLECTIONS_MAX_RESULTS optionally caps retrieved chunks. Ids are
+ *   deployment configuration (they differ per account/stage), which is
+ *   what .env is for; the YAML stays shareable. Declared with no ids
+ *   configured, the tool is omitted with a warning — never fatal.
+ *
+ * SCOPE: xAI-only. OpenAI's Responses API shares the file_search wire
+ *   shape but searches OPENAI vector stores — a different product with
+ *   different ids — so this sentinel gates to grok-* models and is a
+ *   silent no-op everywhere else (same non-throwing routing contract as
+ *   web_search / x_search).
+ */
+import { BaseTool } from '@google/adk';
+import { providerForModel } from "../models/providerMap.js";
+export const COLLECTIONS_SEARCH_TOOL_NAME = 'collections_search';
+export class CollectionsSearchTool extends BaseTool {
+    constructor() {
+        super({
+            name: COLLECTIONS_SEARCH_TOOL_NAME,
+            description: 'Semantic search over xAI Collections (hosted document stores) via ' +
+                'Agent Tools — grok-* models only; a no-op sentinel on every other ' +
+                'provider. Collections are selected by XAI_COLLECTION_IDS.',
+        });
+    }
+    /** Never a client-side function tool — xAI runs retrieval server-side. */
+    _getDeclaration() {
+        return undefined;
+    }
+    /** Server-side tool: nothing to execute locally. */
+    async runAsync() {
+        return Promise.resolve();
+    }
+    async processLlmRequest({ llmRequest }) {
+        if (!llmRequest.model)
+            return;
+        if (providerForModel(llmRequest.model) !== 'xai')
+            return; // no-op elsewhere
+        llmRequest.toolsDict[COLLECTIONS_SEARCH_TOOL_NAME] = this;
+    }
+}
+/** Shared instance, mirroring WEB_SEARCH / X_SEARCH. */
+export const COLLECTIONS_SEARCH = new CollectionsSearchTool();
+/** True when the agent requested collections search (xAI sentinel path). */
+export function wantsCollectionsSearch(llmRequest) {
+    return (llmRequest.toolsDict?.[COLLECTIONS_SEARCH_TOOL_NAME] instanceof
+        CollectionsSearchTool);
+}
+/** Sentinel test used by the request builder to skip function-tool emission. */
+export function isCollectionsSearchSentinel(tool) {
+    return tool instanceof CollectionsSearchTool;
+}
+/** Collection ids from XAI_COLLECTION_IDS (comma-separated, trimmed). */
+export function collectionIdsFromEnv() {
+    return (process.env.XAI_COLLECTION_IDS ?? '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+}
+/** Optional retrieval cap from XAI_COLLECTIONS_MAX_RESULTS (positive int). */
+export function collectionsMaxResultsFromEnv() {
+    const raw = process.env.XAI_COLLECTIONS_MAX_RESULTS?.trim();
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}

package/dist/lib/tools/generateImageTool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * generateImageTool — native ADK FunctionTool for real image generation.
+ *
+ * WHY a FunctionTool instead of an AgentTool subagent:
+ *   AgentTool converts all subagent output to a text function-response before
+ *   returning it to the orchestrator. Binary inlineData (the base64 image bytes
+ *   from an image-generation model) is therefore lost in transit.
+ *
+ *   A FunctionTool runs arbitrary TypeScript: we call @google/genai directly,
+ *   receive the raw response including inlineData, write the file to disk, and
+ *   return a plain-text confirmation with the saved file path. The orchestrator
+ *   sees the path and relays it to the user.
+ */
+import { FunctionTool } from '@google/adk';
+import { type Schema } from '@google/genai';
+export declare const generateImageTool: FunctionTool<Schema>;

package/dist/lib/tools/generateImageTool.js

@@ -0,0 +1,119 @@
+/**
+ * generateImageTool — native ADK FunctionTool for real image generation.
+ *
+ * WHY a FunctionTool instead of an AgentTool subagent:
+ *   AgentTool converts all subagent output to a text function-response before
+ *   returning it to the orchestrator. Binary inlineData (the base64 image bytes
+ *   from an image-generation model) is therefore lost in transit.
+ *
+ *   A FunctionTool runs arbitrary TypeScript: we call @google/genai directly,
+ *   receive the raw response including inlineData, write the file to disk, and
+ *   return a plain-text confirmation with the saved file path. The orchestrator
+ *   sees the path and relays it to the user.
+ */
+import { FunctionTool } from '@google/adk';
+import { GoogleGenAI } from '@google/genai';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const IMAGE_MODEL = 'gemini-3.1-flash-image-preview';
+export const generateImageTool = new FunctionTool({
+    name: 'generate_image',
+    description: 'Generates a real image from a structured payload and saves it to the outputs/ directory. ' +
+        'Returns the saved file path. Call this only after the user has approved the image payload.',
+    parameters: {
+        type: 'OBJECT',
+        properties: {
+            prompt: {
+                type: 'STRING',
+                description: 'The full image prompt describing the scene and subject.',
+            },
+            style: {
+                type: 'STRING',
+                description: 'Visual style (e.g. "Ansel Adams", "impressionist", "photorealistic").',
+            },
+            aspect_ratio: {
+                type: 'STRING',
+                description: 'Desired aspect ratio (e.g. "3:2", "16:9", "1:1").',
+            },
+            color_palette: {
+                type: 'STRING',
+                description: 'Color palette guidance (e.g. "monochromatic", "warm tones", "vivid").',
+            },
+        },
+        required: ['prompt'],
+    },
+    execute: async (input) => {
+        console.log("[ImageTool] Starting image generation execution...");
+        const { prompt, style, aspect_ratio, color_palette } = input;
+        const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+        if (!apiKey) {
+            const err = new Error('Gemini API Key is not configured (neither GEMINI_API_KEY nor GOOGLE_GENAI_API_KEY was found in environment).');
+            console.error(`[ImageTool ERROR] Initialization failed: ${err.message}`);
+            throw err;
+        }
+        console.log(`[ImageTool] Parameters - Prompt: "${prompt}", Style: "${style ?? 'none'}", Aspect Ratio: "${aspect_ratio ?? 'none'}", Color Palette: "${color_palette ?? 'none'}"`);
+        const ai = new GoogleGenAI({ apiKey });
+        // Build a rich prompt that bakes in the structured parameters.
+        const parts = [prompt];
+        if (style)
+            parts.push(`Style: ${style}`);
+        if (color_palette)
+            parts.push(`Color palette: ${color_palette}`);
+        if (aspect_ratio)
+            parts.push(`Aspect ratio: ${aspect_ratio}`);
+        const fullPrompt = parts.join('. ');
+        try {
+            console.log(`[ImageTool] Sending generateContent request to Gemini API (Model: ${IMAGE_MODEL})...`);
+            const response = await ai.models.generateContent({
+                model: IMAGE_MODEL,
+                contents: [{ role: 'user', parts: [{ text: fullPrompt }] }],
+                config: {
+                    responseModalities: ['IMAGE', 'TEXT'],
+                },
+            });
+            console.log("[ImageTool] Received response from Gemini API.");
+            const candidates = response.candidates ?? [];
+            console.log(`[ImageTool] Candidates found: ${candidates.length}`);
+            for (let i = 0; i < candidates.length; i++) {
+                const candidate = candidates[i];
+                console.log(`[ImageTool] Candidate ${i}: FinishReason = ${candidate.finishReason ?? 'none'}`);
+                const partsList = candidate.content?.parts ?? [];
+                console.log(`[ImageTool] Candidate ${i} has ${partsList.length} parts.`);
+                for (let j = 0; j < partsList.length; j++) {
+                    const part = partsList[j];
+                    const inlineData = part.inlineData;
+                    console.log(`[ImageTool] Part ${j}: hasText = ${!!part.text}, hasInlineData = ${!!inlineData}`);
+                    if (inlineData?.data) {
+                        const { mimeType, data } = inlineData;
+                        const ext = mimeType?.split('/')[1] ?? 'png';
+                        // OUTPUTS_DIR env overrides the cwd default (package consumers).
+                        const outputDir = process.env.OUTPUTS_DIR
+                            ? resolve(process.env.OUTPUTS_DIR)
+                            : join(process.cwd(), 'outputs');
+                        console.log(`[ImageTool] Found inline image data. MimeType: ${mimeType}, Data Length: ${data.length} chars.`);
+                        console.log(`[ImageTool] Ensuring output directory exists: ${outputDir}`);
+                        mkdirSync(outputDir, { recursive: true });
+                        const filename = `image_${Date.now()}.${ext}`;
+                        const filepath = join(outputDir, filename);
+                        console.log(`[ImageTool] Saving image to disk: ${filepath}`);
+                        writeFileSync(filepath, Buffer.from(data, 'base64'));
+                        return `[ImageTool Success] Image saved to outputs/${filename}`;
+                    }
+                }
+            }
+            // Fallback: model returned text only (no image data in response)
+            console.warn("[ImageTool WARNING] No image data found in any of the response parts.");
+            const textFallback = candidates[0]?.content?.parts
+                ?.map((p) => p.text)
+                .filter(Boolean)
+                .join('');
+            return textFallback || `No image data returned. Model used: ${IMAGE_MODEL}`;
+        }
+        catch (err) {
+            // Surface the raw API error so the orchestrator can relay it accurately.
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[ImageTool ERROR] Execution failed: ${msg}`);
+            return `[generate_image ERROR] Model: ${IMAGE_MODEL} - ${msg}`;
+        }
+    },
+});