@mcoda/codali 0.1.108 → 0.1.109

package/dist/connectors/mcp/McpServerRegistry.js

@@ -0,0 +1,180 @@
+import { ToolExecutionError } from "../../tools/ToolTypes.js";
+import { McpClient, McpClientError, } from "./McpClient.js";
+import { mcpToolsToDefinitions } from "./McpToolAdapter.js";
+/**
+ * Owns the lifetime of every configured MCP server.
+ *
+ * Three properties matter more than features here:
+ *
+ *   - **Isolation.** One broken server degrades its own tools to unavailable
+ *     and never fails the run or affects another server.
+ *   - **Boundedness.** Every call has a timeout, at most one retry, and
+ *     competes for a global concurrency budget, so a slow server cannot
+ *     monopolise a run.
+ *   - **Cleanup.** stdio servers are child processes. They must be shut down
+ *     even when a run fails, or the CLI leaves orphans behind.
+ */
+/** Concurrent in-flight MCP calls across all servers. */
+export const DEFAULT_MAX_CONCURRENT_CALLS = 4;
+/** One retry, and only for transport-level failures. */
+const MAX_CALL_ATTEMPTS = 2;
+/** A minimal semaphore. Keeps concurrent MCP work inside a known bound. */
+class Semaphore {
+    constructor(limit) {
+        this.limit = limit;
+        this.active = 0;
+        this.waiting = [];
+    }
+    async acquire() {
+        if (this.active < this.limit) {
+            this.active += 1;
+            return () => this.release();
+        }
+        await new Promise((resolve) => this.waiting.push(resolve));
+        this.active += 1;
+        return () => this.release();
+    }
+    release() {
+        this.active -= 1;
+        const next = this.waiting.shift();
+        if (next)
+            next();
+    }
+}
+export class McpServerRegistry {
+    constructor(options) {
+        this.options = options;
+        this.clients = new Map();
+        this.health = new Map();
+        this.discovered = false;
+        this.semaphore = new Semaphore(options.maxConcurrentCalls ?? DEFAULT_MAX_CONCURRENT_CALLS);
+    }
+    /**
+     * Connects to every enabled server and returns their tools as Codali tool
+     * definitions. Servers are contacted in parallel; a failure is recorded as
+     * unhealthy rather than thrown, so one bad entry in a tenant's config cannot
+     * take down the run.
+     */
+    async discoverTools() {
+        const definitions = [];
+        const results = await Promise.all(this.options.servers.map(async (definition) => {
+            if (definition.enabled === false) {
+                this.health.set(definition.name, {
+                    name: definition.name,
+                    status: "disabled",
+                    toolCount: 0,
+                });
+                this.options.onEvent?.({
+                    type: "server_skipped",
+                    server: definition.name,
+                    reason: "disabled",
+                });
+                return [];
+            }
+            const startedMs = Date.now();
+            const client = this.options.createClient
+                ? this.options.createClient(definition)
+                : new McpClient({ definition });
+            this.clients.set(definition.name, client);
+            let tools;
+            try {
+                tools = await client.listTools();
+            }
+            catch (error) {
+                const message = error instanceof McpClientError
+                    ? error.message
+                    : error instanceof Error
+                        ? error.message
+                        : String(error);
+                this.health.set(definition.name, {
+                    name: definition.name,
+                    status: "failed",
+                    toolCount: 0,
+                    error: message,
+                });
+                this.options.onEvent?.({
+                    type: "server_failed",
+                    server: definition.name,
+                    error: message,
+                });
+                // Drop the client so a later call does not retry a dead connection.
+                this.clients.delete(definition.name);
+                await client.close();
+                return [];
+            }
+            const durationMs = Date.now() - startedMs;
+            this.health.set(definition.name, {
+                name: definition.name,
+                status: "connected",
+                toolCount: tools.length,
+                discoveryMs: durationMs,
+            });
+            this.options.onEvent?.({
+                type: "server_connected",
+                server: definition.name,
+                toolCount: tools.length,
+                durationMs,
+            });
+            return mcpToolsToDefinitions(tools, {
+                client: this.wrapClient(client),
+                server: definition.name,
+                capability: definition.name,
+                // Operator declaration only. Claiming read-only for an unvetted
+                // server would mislabel tools like `edit_file` and `move_file`, which
+                // is worse than admitting we do not know.
+                readOnly: definition.readOnly === true,
+            });
+        }));
+        for (const group of results)
+            definitions.push(...group);
+        this.discovered = true;
+        return definitions;
+    }
+    /**
+     * Wraps a client so every tool call is bounded by the concurrency budget and
+     * retried once on a transport failure. Retrying is safe here because Phase 2
+     * connectors are read-only.
+     */
+    wrapClient(client) {
+        const semaphore = this.semaphore;
+        const wrapped = Object.create(client);
+        wrapped.callTool = async (name, args) => {
+            const release = await semaphore.acquire();
+            try {
+                let lastError;
+                for (let attempt = 1; attempt <= MAX_CALL_ATTEMPTS; attempt += 1) {
+                    try {
+                        return await client.callTool(name, args);
+                    }
+                    catch (error) {
+                        lastError = error;
+                        const retryable = error instanceof McpClientError && error.retryable;
+                        if (!retryable || attempt === MAX_CALL_ATTEMPTS)
+                            break;
+                    }
+                }
+                throw new ToolExecutionError("tool_execution_failed", lastError instanceof Error ? lastError.message : String(lastError), { retryable: false, details: { tool: name } });
+            }
+            finally {
+                release();
+            }
+        };
+        return wrapped;
+    }
+    healthReport() {
+        return [...this.health.values()];
+    }
+    get isDiscovered() {
+        return this.discovered;
+    }
+    /**
+     * Shuts down every connection. Must run even when a run fails: stdio servers
+     * are child processes and would otherwise be orphaned.
+     */
+    async close() {
+        const clients = [...this.clients.values()];
+        this.clients.clear();
+        await Promise.all(clients.map((client) => client.close()));
+    }
+}
+export const createMcpServerRegistry = (options) => new McpServerRegistry(options);

package/dist/connectors/mcp/McpToolAdapter.d.ts

@@ -0,0 +1,48 @@
+import type { ToolDefinition, ToolInputSchema } from "../../tools/ToolTypes.js";
+import type { McpClient, McpToolDefinition } from "./McpClient.js";
+/**
+ * Adapts MCP tools into Codali's own tool contract.
+ *
+ * The direction matters: MCP adapts *into* the neutral `ToolDefinition`, never
+ * the reverse. Codali's internals stay decoupled from MCP's evolution, and a
+ * built-in tool, a docdex tool and an MCP tool are indistinguishable to the
+ * planner and the executor.
+ */
+/** `mcp:<server>:<tool>` — the namespace that keeps two servers from colliding. */
+export declare const mcpToolName: (server: string, tool: string) => string;
+export declare const parseMcpToolName: (name: string) => {
+    server: string;
+    tool: string;
+} | undefined;
+/**
+ * Normalizes an MCP input schema into Codali's `ToolInputSchema`.
+ *
+ * `additionalProperties` is forced open because the registry rejects unknown
+ * arguments by default, and MCP servers frequently omit properties they still
+ * accept. Rejecting a valid argument is worse here than passing an extra one
+ * through: the server validates its own inputs.
+ */
+export declare const normalizeMcpInputSchema: (schema: Record<string, unknown> | undefined) => ToolInputSchema;
+export interface McpToolAdapterOptions {
+    client: McpClient;
+    server: string;
+    /**
+     * Capability group the server's tools belong to, used for the orchestrator's
+     * first-stage selection. Defaults to the server name, which is usually what
+     * an operator means ("github", "jira").
+     */
+    capability?: string;
+    /**
+     * Whether these tools may mutate anything.
+     *
+     * Decided by Codali policy — an operator marking a connector read-only —
+     * never by the server's own `readOnlyHint`. A server asserting it is harmless
+     * is the party being constrained vouching for itself.
+     */
+    readOnly: boolean;
+    /** Result text beyond this is truncated before it reaches a model. */
+    maxOutputChars?: number;
+}
+export declare const mcpToolToDefinition: (tool: McpToolDefinition, options: McpToolAdapterOptions) => ToolDefinition;
+export declare const mcpToolsToDefinitions: (tools: readonly McpToolDefinition[], options: McpToolAdapterOptions) => ToolDefinition[];
+//# sourceMappingURL=McpToolAdapter.d.ts.map

package/dist/connectors/mcp/McpToolAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpToolAdapter.d.ts","sourceRoot":"","sources":["../../../src/connectors/mcp/McpToolAdapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnE;;;;;;;GAOG;AAEH,mFAAmF;AACnF,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,MAClC,CAAC;AAE1B,eAAO,MAAM,gBAAgB,GAC3B,MAAM,MAAM,KACX;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAIrC,CAAC;AAKF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAC1C,eAeF,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AA4BD,eAAO,MAAM,mBAAmB,GAC9B,MAAM,iBAAiB,EACvB,SAAS,qBAAqB,KAC7B,cAsCF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,OAAO,SAAS,iBAAiB,EAAE,EACnC,SAAS,qBAAqB,KAC7B,cAAc,EAA6D,CAAC"}

package/dist/connectors/mcp/McpToolAdapter.js

@@ -0,0 +1,101 @@
+import { ToolExecutionError } from "../../tools/ToolTypes.js";
+import { truncateToolResult } from "../../tools/TruncateResult.js";
+/**
+ * Adapts MCP tools into Codali's own tool contract.
+ *
+ * The direction matters: MCP adapts *into* the neutral `ToolDefinition`, never
+ * the reverse. Codali's internals stay decoupled from MCP's evolution, and a
+ * built-in tool, a docdex tool and an MCP tool are indistinguishable to the
+ * planner and the executor.
+ */
+/** `mcp:<server>:<tool>` — the namespace that keeps two servers from colliding. */
+export const mcpToolName = (server, tool) => `mcp:${server}:${tool}`;
+export const parseMcpToolName = (name) => {
+    const parts = name.split(":");
+    if (parts.length < 3 || parts[0] !== "mcp")
+        return undefined;
+    return { server: parts[1] ?? "", tool: parts.slice(2).join(":") };
+};
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Normalizes an MCP input schema into Codali's `ToolInputSchema`.
+ *
+ * `additionalProperties` is forced open because the registry rejects unknown
+ * arguments by default, and MCP servers frequently omit properties they still
+ * accept. Rejecting a valid argument is worse here than passing an extra one
+ * through: the server validates its own inputs.
+ */
+export const normalizeMcpInputSchema = (schema) => {
+    if (!isRecord(schema)) {
+        return { type: "object", properties: {}, additionalProperties: true };
+    }
+    return {
+        ...schema,
+        type: "object",
+        properties: isRecord(schema.properties)
+            ? schema.properties
+            : {},
+        required: Array.isArray(schema.required)
+            ? schema.required.filter((entry) => typeof entry === "string")
+            : undefined,
+        additionalProperties: true,
+    };
+};
+const DEFAULT_MAX_OUTPUT_CHARS = 12000;
+const tryParseJson = (value) => {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+const truncate = (value, limit) => value.length > limit
+    ? `${value.slice(0, limit)}\n…[truncated ${value.length - limit} characters]`
+    : value;
+/**
+ * Builds a description the planner can act on. MCP descriptions are sometimes
+ * absent, in which case the tool name is all we have — say so plainly rather
+ * than inventing capability the tool may not have.
+ */
+const describeMcpTool = (tool, server) => {
+    const base = tool.description?.trim();
+    if (base)
+        return base;
+    return `${tool.name} (provided by the ${server} MCP server; no description supplied).`;
+};
+export const mcpToolToDefinition = (tool, options) => {
+    const maxOutputChars = options.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+    const qualified = mcpToolName(options.server, tool.name);
+    return {
+        name: qualified,
+        description: describeMcpTool(tool, options.server),
+        inputSchema: normalizeMcpInputSchema(tool.inputSchema),
+        outputSchema: tool.outputSchema,
+        readOnly: options.readOnly,
+        capability: options.capability ?? options.server,
+        handler: async (args) => {
+            const result = await options.client.callTool(tool.name, args);
+            if (!result.ok) {
+                // Surface as a tool failure so the runner records it and the model is
+                // told, rather than passing an error string off as a result.
+                throw new ToolExecutionError("tool_execution_failed", result.text || `MCP tool ${qualified} reported an error.`, { retryable: false, details: { server: options.server, tool: tool.name } });
+            }
+            // Structural where possible: an oversized list keeps whole items so the
+            // model receives valid JSON, not a document cut mid-token.
+            const structured = result.structured ?? tryParseJson(result.text);
+            const trimmed = structured !== undefined
+                ? truncateToolResult(structured, result.text, maxOutputChars)
+                : { text: truncate(result.text, maxOutputChars), truncated: false };
+            return {
+                output: trimmed.text || "(the tool returned no content)",
+                // The *parsed* payload, not the MCP envelope. Evidence normalization
+                // reads this to turn each returned record into its own evidence item;
+                // handed `{content:[{type:"text",…}]}` it finds no records and emits a
+                // single "returned structured data" placeholder instead.
+                data: structured ?? result.raw,
+            };
+        },
+    };
+};
+export const mcpToolsToDefinitions = (tools, options) => tools.map((tool) => mcpToolToDefinition(tool, options));

package/dist/connectors/mcp/McpToolSource.d.ts

@@ -0,0 +1,27 @@
+import { createMcpServerRegistry, type McpServerRegistry } from "./McpServerRegistry.js";
+import type { McpServerHealth } from "./McpServerRegistry.js";
+import type { RunContext } from "../../runcontext/RunContextResolver.js";
+import type { ToolRegistry } from "../../tools/ToolRegistry.js";
+/**
+ * Connects a run's configured MCP servers and registers what they expose into
+ * the run's `ToolRegistry`.
+ *
+ * Registration goes into the *existing* registry rather than a parallel store:
+ * one source of truth means the planner cannot see a schema the executor would
+ * not honour, no matter where the tool came from.
+ */
+export interface McpAttachResult {
+    registry?: McpServerRegistry;
+    health: McpServerHealth[];
+    registered: string[];
+    warnings: string[];
+}
+export interface McpAttachOptions {
+    context: RunContext;
+    toolRegistry: ToolRegistry;
+    maxConcurrentCalls?: number;
+    /** Injected in tests. */
+    createRegistry?: typeof createMcpServerRegistry;
+}
+export declare const attachMcpTools: (options: McpAttachOptions) => Promise<McpAttachResult>;
+//# sourceMappingURL=McpToolSource.d.ts.map

package/dist/connectors/mcp/McpToolSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpToolSource.d.ts","sourceRoot":"","sources":["../../../src/connectors/mcp/McpToolSource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;;;GAOG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,cAAc,CAAC,EAAE,OAAO,uBAAuB,CAAC;CACjD;AAED,eAAO,MAAM,cAAc,GACzB,SAAS,gBAAgB,KACxB,OAAO,CAAC,eAAe,CAuCzB,CAAC"}

package/dist/connectors/mcp/McpToolSource.js

@@ -0,0 +1,33 @@
+import { createMcpServerRegistry } from "./McpServerRegistry.js";
+export const attachMcpTools = async (options) => {
+    const servers = options.context.mcpServers ?? [];
+    if (servers.length === 0) {
+        return { health: [], registered: [], warnings: [] };
+    }
+    const warnings = [];
+    const registry = (options.createRegistry ?? createMcpServerRegistry)({
+        servers,
+        maxConcurrentCalls: options.maxConcurrentCalls,
+    });
+    const definitions = await registry.discoverTools();
+    const registered = [];
+    for (const definition of definitions) {
+        try {
+            options.toolRegistry.register(definition);
+            registered.push(definition.name);
+        }
+        catch (error) {
+            // A duplicate name means two servers claimed the same namespaced tool,
+            // which the `mcp:<server>:<tool>` scheme should prevent. Report rather
+            // than crash, and keep the first registration.
+            warnings.push(`mcp_tool_registration_failed:${definition.name}:${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const health = registry.healthReport();
+    for (const entry of health) {
+        if (entry.status === "failed") {
+            warnings.push(`mcp_server_unavailable:${entry.name}:${entry.error ?? "unknown"}`);
+        }
+    }
+    return { registry, health, registered, warnings };
+};

package/dist/connectors/media/ImageGenerationTool.d.ts

@@ -0,0 +1,43 @@
+import type { ToolDefinition } from "../../tools/ToolTypes.js";
+/**
+ * Image generation, as an ordinary tool.
+ *
+ * The original design gave media its own orchestration route, which forced
+ * every request to be classified as "media or not" up front and duplicated the
+ * planning path. It is simpler and more accurate to treat generation as a tool
+ * the orchestrator may call: "generate an image of a puppy" becomes a plan with
+ * one task, exactly like any other single-source question, and a request that
+ * needs both research *and* an image needs no special case at all.
+ *
+ * The tool returns an `ArtifactRef`. Image bytes are written to disk and
+ * referenced — never inlined into evidence or an answer, which would blow the
+ * context budget and put base64 in the trace.
+ */
+export interface ImageGenerationConfig {
+    /** OpenAI-compatible `/v1/images/generations` endpoint. */
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    /** Where artifacts are written. Defaults to `<workspace>/.codali/artifacts`. */
+    artifactDir?: string;
+    timeoutMs?: number;
+    size?: string;
+}
+export interface ImageToolOptions {
+    config: ImageGenerationConfig;
+    workspaceRoot: string;
+    runId?: string;
+    fetchImpl?: typeof fetch;
+    /** Called for each artifact so the gateway can surface it in the result. */
+    onArtifact?: (artifact: {
+        id: string;
+        type: string;
+        path: string;
+        mimeType: string;
+        model: string;
+        prompt: string;
+    }) => void;
+}
+export declare const IMAGE_TOOL_NAME = "media_generate_image";
+export declare const createImageGenerationTool: (options: ImageToolOptions) => ToolDefinition;
+//# sourceMappingURL=ImageGenerationTool.d.ts.map

package/dist/connectors/media/ImageGenerationTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageGenerationTool.d.ts","sourceRoot":"","sources":["../../../src/connectors/media/ImageGenerationTool.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0BD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE;QACtB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,IAAI,CAAC;CACZ;AAED,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAEtD,eAAO,MAAM,yBAAyB,GAAI,SAAS,gBAAgB,KAAG,cAgIrE,CAAC"}

package/dist/connectors/media/ImageGenerationTool.js

@@ -0,0 +1,122 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ToolExecutionError } from "../../tools/ToolTypes.js";
+const DEFAULT_TIMEOUT_MS = 180000;
+const DEFAULT_SIZE = "512x512";
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Extracts image bytes from an OpenAI-compatible response. Servers return
+ * either `b64_json` or a `url`; both shapes are handled because local
+ * stable-diffusion servers and hosted APIs differ here.
+ */
+const readImagePayload = (payload) => {
+    if (!isRecord(payload))
+        return undefined;
+    const data = payload.data;
+    if (!Array.isArray(data) || data.length === 0)
+        return undefined;
+    const first = data[0];
+    if (!isRecord(first))
+        return undefined;
+    const b64 = typeof first.b64_json === "string" ? first.b64_json : undefined;
+    const url = typeof first.url === "string" ? first.url : undefined;
+    return b64 || url ? { b64, url } : undefined;
+};
+export const IMAGE_TOOL_NAME = "media_generate_image";
+export const createImageGenerationTool = (options) => {
+    const { config } = options;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    return {
+        name: IMAGE_TOOL_NAME,
+        description: "Generate an image from a text prompt. Returns the path to the written image file, not the image itself. Use for any request to draw, render, or generate a picture.",
+        capability: "media",
+        // Generation writes a file, but only inside the run's own artifact
+        // directory — it cannot touch the workspace or anything the user owns.
+        readOnly: true,
+        inputSchema: {
+            type: "object",
+            required: ["prompt"],
+            properties: {
+                prompt: { type: "string", minLength: 1 },
+                size: { type: "string" },
+            },
+        },
+        handler: async (args) => {
+            const record = isRecord(args) ? args : {};
+            const prompt = typeof record.prompt === "string" ? record.prompt.trim() : "";
+            if (!prompt) {
+                throw new ToolExecutionError("tool_invalid_args", "An image prompt is required.", {
+                    retryable: false,
+                });
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            let response;
+            try {
+                response = await fetchImpl(new URL("images/generations", config.baseUrl.endsWith("/")
+                    ? config.baseUrl
+                    : `${config.baseUrl}/`).toString(), {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+                    },
+                    body: JSON.stringify({
+                        model: config.model,
+                        prompt,
+                        n: 1,
+                        size: typeof record.size === "string" ? record.size : (config.size ?? DEFAULT_SIZE),
+                        response_format: "b64_json",
+                    }),
+                    signal: controller.signal,
+                });
+            }
+            catch (error) {
+                throw new ToolExecutionError("tool_execution_failed", `Image generation request failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!response.ok) {
+                throw new ToolExecutionError("tool_execution_failed", `Image generation returned HTTP ${response.status}.`, { retryable: response.status >= 500, details: { status: response.status } });
+            }
+            const payload = await response.json();
+            const image = readImagePayload(payload);
+            if (!image) {
+                throw new ToolExecutionError("tool_execution_failed", "Image generation returned no image data.", { retryable: false });
+            }
+            let bytes;
+            if (image.b64) {
+                bytes = Buffer.from(image.b64, "base64");
+            }
+            else {
+                const fetched = await fetchImpl(image.url);
+                if (!fetched.ok) {
+                    throw new ToolExecutionError("tool_execution_failed", `Could not download the generated image (HTTP ${fetched.status}).`, { retryable: true });
+                }
+                bytes = Buffer.from(await fetched.arrayBuffer());
+            }
+            const artifactDir = config.artifactDir ??
+                path.join(options.workspaceRoot, ".codali", "artifacts", options.runId ?? "run");
+            await mkdir(artifactDir, { recursive: true });
+            const id = `img-${randomUUID()}`;
+            const filePath = path.join(artifactDir, `${id}.png`);
+            await writeFile(filePath, bytes);
+            options.onArtifact?.({
+                id,
+                type: "image",
+                path: filePath,
+                mimeType: "image/png",
+                model: config.model,
+                prompt,
+            });
+            return {
+                // The path, not the bytes: inlining base64 would blow the context
+                // budget and put megabytes of noise in the trace.
+                output: `Generated an image and wrote it to ${filePath}`,
+                data: { artifactId: id, path: filePath, mimeType: "image/png", prompt },
+            };
+        },
+    };
+};

package/dist/connectors/oauth/DeviceCodeAuth.d.ts

@@ -0,0 +1,74 @@
+/**
+ * OAuth 2.0 device authorization grant (RFC 8628).
+ *
+ * The right flow for a CLI. Authorization-code needs a redirect URI and a local
+ * web server; client-credentials gets app-only permissions, which for
+ * "summarize *my* mail" would mean reading the entire tenant — both overreach
+ * and a different consent conversation.
+ *
+ * Device code needs neither: the user is shown a short code, approves in a
+ * browser on any device, and we receive an access token plus a refresh token.
+ * The refresh token is what gets stored; access tokens live about an hour and
+ * are minted on demand.
+ */
+export interface DeviceCodeStartResult {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    expiresInSeconds: number;
+    intervalSeconds: number;
+    message?: string;
+}
+export interface DeviceCodeTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresInSeconds: number;
+    scope?: string;
+    tokenType: string;
+}
+export interface DeviceCodeConfig {
+    deviceCodeUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    scope: string;
+}
+export declare class DeviceCodeError extends Error {
+    readonly code: string;
+    readonly description?: string;
+    constructor(code: string, description?: string);
+}
+export declare const startDeviceCode: (config: DeviceCodeConfig, fetchImpl?: typeof fetch) => Promise<DeviceCodeStartResult>;
+export interface PollOptions {
+    onPending?: (secondsRemaining: number) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Polls until the user approves, declines, or the code expires.
+ *
+ * `authorization_pending` is the normal state and must not be treated as an
+ * error; `slow_down` requires backing off, and ignoring it gets the request
+ * throttled.
+ */
+export declare const pollForDeviceCodeTokens: (config: DeviceCodeConfig, start: DeviceCodeStartResult, fetchImpl?: typeof fetch, options?: PollOptions) => Promise<DeviceCodeTokens>;
+/**
+ * Exchanges a stored refresh token for a fresh access token.
+ *
+ * Microsoft rotates refresh tokens, so the response may carry a new one; a
+ * caller that ignores it will find its stored token dead after the old one's
+ * sliding window closes.
+ */
+export declare const refreshAccessToken: (config: Omit<DeviceCodeConfig, "deviceCodeUrl">, refreshToken: string, fetchImpl?: typeof fetch) => Promise<DeviceCodeTokens>;
+/** Microsoft identity platform endpoints for a tenant. */
+export declare const microsoftEndpoints: (tenantId: string) => {
+    deviceCodeUrl: string;
+    tokenUrl: string;
+};
+/**
+ * Delegated Graph scopes Codali asks for, matching what okacam's
+ * `microsoft-integration-service` already requests. `offline_access` is what
+ * yields a refresh token — without it the grant is good for one hour and then
+ * gone.
+ */
+export declare const MICROSOFT_GRAPH_SCOPES: string;
+//# sourceMappingURL=DeviceCodeAuth.d.ts.map

package/dist/connectors/oauth/DeviceCodeAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeviceCodeAuth.d.ts","sourceRoot":"","sources":["../../../src/connectors/oauth/DeviceCodeAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAM/C;AAQD,eAAO,MAAM,eAAe,GAC1B,QAAQ,gBAAgB,EACxB,YAAW,OAAO,KAAa,KAC9B,OAAO,CAAC,qBAAqB,CAyB/B,CAAC;AAWF,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ,gBAAgB,EACxB,OAAO,qBAAqB,EAC5B,YAAW,OAAO,KAAa,EAC/B,UAAS,WAAgB,KACxB,OAAO,CAAC,gBAAgB,CA+C1B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,EAC/C,cAAc,MAAM,EACpB,YAAW,OAAO,KAAa,KAC9B,OAAO,CAAC,gBAAgB,CAsB1B,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM;;;CAGjD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QASxB,CAAC"}