@mcoda/codali 0.1.108 → 0.1.110

package/dist/agents/AgentInventory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Loads the mcoda agent inventory that {@link resolveCodaliGatewayAgentTiers}
+ * resolves roles against.
+ *
+ * Loaded **once** and cached for the process lifetime. Shelling out to
+ * `mcoda agent list` costs hundreds of milliseconds and the inventory does not
+ * change mid-request, so doing it per query would put a subprocess spawn on the
+ * critical path of every question asked.
+ */
+export interface AgentInventoryEntry extends Record<string, unknown> {
+    id?: string;
+    slug?: string;
+    adapter?: string;
+    defaultModel?: string;
+    model?: string;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    supportsTools?: boolean;
+    capabilities?: string[];
+    rating?: number;
+    reasoningRating?: number;
+    costPerMillion?: number;
+    maxComplexity?: number;
+    health?: {
+        status?: string;
+    };
+}
+export interface AgentInventoryLoadOptions {
+    command?: string;
+    timeoutMs?: number;
+    /** Include agents whose health is unknown. Unhealthy is always excluded. */
+    includeUnknownHealth?: boolean;
+    /** Injected in tests. */
+    runCommand?: (command: string, args: string[], timeoutMs: number) => Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export interface AgentInventoryLoadResult {
+    agents: AgentInventoryEntry[];
+    warnings: string[];
+    source: "mcoda" | "empty";
+}
+export declare const loadAgentInventory: (options?: AgentInventoryLoadOptions) => Promise<AgentInventoryLoadResult>;
+export declare const isLocallyDrivable: (agent: AgentInventoryEntry) => boolean;
+/** Narrows an inventory to agents the in-process CLI can actually call. */
+export declare const filterLocallyDrivable: (agents: readonly AgentInventoryEntry[]) => AgentInventoryEntry[];
+/**
+ * Process-lifetime cached inventory. Call once at startup; every later caller
+ * gets the same promise rather than spawning another subprocess.
+ */
+export declare const getAgentInventory: (options?: AgentInventoryLoadOptions) => Promise<AgentInventoryLoadResult>;
+/** Test-only: drops the cache so a fresh load can be exercised. */
+export declare const resetAgentInventoryCache: () => void;
+//# sourceMappingURL=AgentInventory.d.ts.map

package/dist/agents/AgentInventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentInventory.d.ts","sourceRoot":"","sources":["../../src/agents/AgentInventory.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,MAAM,WAAW,mBAAoB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,yBAAyB;IACzB,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,MAAM,KACd,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;CAC3B;AA0ED,eAAO,MAAM,kBAAkB,GAC7B,UAAS,yBAA8B,KACtC,OAAO,CAAC,wBAAwB,CAiClC,CAAC;AAwBF,eAAO,MAAM,iBAAiB,GAAI,OAAO,mBAAmB,KAAG,OAG9D,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,mBAAmB,EAAE,KACrC,mBAAmB,EAAsC,CAAC;AAI7D;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAS,yBAA8B,KACtC,OAAO,CAAC,wBAAwB,CAGlC,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,QAAO,IAE3C,CAAC"}

package/dist/agents/AgentInventory.js

@@ -0,0 +1,131 @@
+import { spawn } from "node:child_process";
+const DEFAULT_COMMAND = "mcoda";
+const DEFAULT_TIMEOUT_MS = 20000;
+const runCommandImpl = (command, args, timeoutMs) => new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        child.kill("SIGKILL");
+        resolve({ code: -1, stdout, stderr: `${stderr}\ntimed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+        stdout += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ code: -1, stdout, stderr: `${stderr}\n${error.message}` });
+    });
+    child.on("close", (code) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ code: code ?? 0, stdout, stderr });
+    });
+});
+const parseInventory = (stdout) => {
+    try {
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+};
+const isUsable = (agent, includeUnknownHealth) => {
+    const status = agent.health?.status;
+    if (status === "healthy")
+        return true;
+    // An agent reporting `limited` has exhausted its quota; `unhealthy` is
+    // self-explanatory. Both would fail at call time, so exclude them here where
+    // the reason can still be reported.
+    if (status === "unhealthy" || status === "limited")
+        return false;
+    return includeUnknownHealth;
+};
+/**
+ * Normalizes to the shape AgentTierResolver reads, so an entry always exposes a
+ * `model` even when mcoda only reports `defaultModel`.
+ */
+const normalize = (agent) => ({
+    ...agent,
+    model: agent.model ?? agent.defaultModel,
+});
+export const loadAgentInventory = async (options = {}) => {
+    const command = options.command ?? DEFAULT_COMMAND;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const run = options.runCommand ?? runCommandImpl;
+    const warnings = [];
+    // Prefer fresh health; fall back for older mcoda builds without the flag.
+    let result = await run(command, ["agent", "list", "--json", "--refresh-health"], timeoutMs);
+    if (result.code !== 0) {
+        warnings.push("agent_inventory_refresh_health_unavailable");
+        result = await run(command, ["agent", "list", "--json"], timeoutMs);
+    }
+    if (result.code !== 0) {
+        warnings.push(`agent_inventory_unavailable:${(result.stderr || "unknown error").trim().slice(0, 200)}`);
+        return { agents: [], warnings, source: "empty" };
+    }
+    const parsed = parseInventory(result.stdout);
+    if (parsed.length === 0) {
+        warnings.push("agent_inventory_empty");
+        return { agents: [], warnings, source: "empty" };
+    }
+    const usable = parsed.filter((agent) => isUsable(agent, options.includeUnknownHealth ?? true));
+    const excluded = parsed.length - usable.length;
+    if (excluded > 0) {
+        warnings.push(`agent_inventory_excluded_unhealthy:${excluded}`);
+    }
+    return { agents: usable.map(normalize), warnings, source: "mcoda" };
+};
+/**
+ * Adapters the local CLI can drive in-process.
+ *
+ * mswarm self-hosted agents were excluded here until 2026-08-05: the gateway's
+ * dedicated self-hosted route reused the generic chat handler, so a local model
+ * id missed the catalog lookup and was forwarded to OpenRouter, which rejected
+ * it. That is fixed (gateway runtime 0e9e877) — the route is self-hosted-only,
+ * serves the exact ids from `/v1/swarm/self-hosted/openai/models`, and returns
+ * 404/503 instead of falling through to a cloud provider. They are drivable now.
+ */
+const LOCAL_DRIVABLE_ADAPTERS = new Set([
+    "claude-cli",
+    "codex-cli",
+    "gemini-cli",
+    "openai-cli",
+    "ollama-cli",
+    "ollama-remote",
+    "openai-api",
+    "anthropic-api",
+    "zhipu-api",
+]);
+export const isLocallyDrivable = (agent) => {
+    const adapter = typeof agent.adapter === "string" ? agent.adapter.toLowerCase() : "";
+    return LOCAL_DRIVABLE_ADAPTERS.has(adapter);
+};
+/** Narrows an inventory to agents the in-process CLI can actually call. */
+export const filterLocallyDrivable = (agents) => agents.filter(isLocallyDrivable);
+let cached;
+/**
+ * Process-lifetime cached inventory. Call once at startup; every later caller
+ * gets the same promise rather than spawning another subprocess.
+ */
+export const getAgentInventory = (options = {}) => {
+    cached ?? (cached = loadAgentInventory(options));
+    return cached;
+};
+/** Test-only: drops the cache so a fresh load can be exercised. */
+export const resetAgentInventoryCache = () => {
+    cached = undefined;
+};

package/dist/agents/RoleResolution.d.ts

@@ -0,0 +1,49 @@
+import { type AgentTierResolution, type CodaliGatewayAgentAssignment } from "../gateway/AgentTierResolver.js";
+import type { RunContextAgentRoles } from "../runcontext/RunContextResolver.js";
+import type { AgentInventoryEntry } from "./AgentInventory.js";
+/**
+ * Codali's configurable model roles.
+ *
+ * `AgentTierResolver` knows twelve internal roles, each with a working default.
+ * Requiring an operator to configure twelve agents to ask one question is a
+ * burden with no payoff, so only three are exposed:
+ *
+ *   orchestrator — routes, plans, assesses completeness, repairs
+ *   synthesizer  — produces multi-source answers
+ *   media        — generates images and other artifacts
+ *
+ * "Classifier", "planner", "verifier" and "repair" remain distinct *prompts*,
+ * but they run against the orchestrator model. The internal roles are still
+ * available for advanced tuning; they simply are not part of configuration.
+ */
+export type CodaliConfigurableRole = "orchestrator" | "worker" | "synthesizer" | "media";
+/** Phase 1 resolves only these; media arrives with image generation. */
+export declare const PHASE_ONE_ROLES: CodaliConfigurableRole[];
+export interface RoleResolutionInput {
+    inventory: AgentInventoryEntry[];
+    /** Explicit slug bindings from run context, e.g. `synthesizer = "suku-large"`. */
+    bindings?: RunContextAgentRoles;
+    roles?: CodaliConfigurableRole[];
+    allowImageWorker?: boolean;
+}
+export interface RoleResolutionResult {
+    resolution: AgentTierResolution;
+    /** Configurable role -> the assignment that will serve it. */
+    assignments: Partial<Record<CodaliConfigurableRole, CodaliGatewayAgentAssignment>>;
+    /** Configurable role -> agent slug, for display in `codali doctor`. */
+    bindings: Partial<Record<CodaliConfigurableRole, string>>;
+    /**
+     * An assignment whose agent can actually emit tool calls.
+     *
+     * The orchestrator model is chosen for planning quality, and plenty of
+     * capable small models report `supportsTools: false`. Running worker tasks on
+     * one of those produces a plan full of correct tool tasks and then zero tool
+     * calls — the run "succeeds" having gathered nothing. So tool execution gets
+     * its own assignment, and its absence is reported rather than discovered
+     * through an empty answer.
+     */
+    toolCapable?: CodaliGatewayAgentAssignment;
+    warnings: string[];
+}
+export declare const resolveConfigurableRoles: (input: RoleResolutionInput) => RoleResolutionResult;
+//# sourceMappingURL=RoleResolution.d.ts.map

package/dist/agents/RoleResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoleResolution.d.ts","sourceRoot":"","sources":["../../src/agents/RoleResolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAClC,MAAM,iCAAiC,CAAC;AAKzC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,sBAAsB,GAC9B,cAAc,GACd,QAAQ,GACR,aAAa,GACb,OAAO,CAAC;AAuBZ,wEAAwE;AACxE,eAAO,MAAM,eAAe,EAAE,sBAAsB,EAInD,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,KAAK,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACjC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,mBAAmB,CAAC;IAChC,8DAA8D;IAC9D,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,sBAAsB,EAAE,4BAA4B,CAAC,CAAC,CAAC;IACnF,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,4BAA4B,CAAC;IAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAmFD,eAAO,MAAM,wBAAwB,GACnC,OAAO,mBAAmB,KACzB,oBA8FF,CAAC"}

package/dist/agents/RoleResolution.js

@@ -0,0 +1,166 @@
+import { resolveCodaliGatewayAgentTiers, } from "../gateway/AgentTierResolver.js";
+/** Internal roles each configurable role stands in for. */
+const ROLE_EXPANSION = {
+    // Thinking stages: JSON in, JSON out, no tool calls. A small fast model is
+    // usually enough, and these run on every question.
+    orchestrator: [
+        "router",
+        "classifier",
+        "planner",
+        "query_expander",
+        "context_refiner",
+        "verifier",
+        "repair",
+    ],
+    // Tool-calling stages. Accuracy here decides whether a run gathers anything:
+    // a weak model invents dates and empty ids. Split out so a bigger model can
+    // be put exactly here without slowing down planning.
+    worker: ["rag_worker", "tool_worker", "extractor"],
+    synthesizer: ["final_synthesizer"],
+    media: ["image_worker"],
+};
+/** Phase 1 resolves only these; media arrives with image generation. */
+export const PHASE_ONE_ROLES = [
+    "orchestrator",
+    "worker",
+    "synthesizer",
+];
+/** Internal roles whose policies already demand tool support, best first. */
+const TOOL_CAPABLE_PREFERENCE = ["tool_worker", "rag_worker"];
+/**
+ * Adapters driven through a text CLI. They advertise `supportsTools: true`
+ * because the CLI itself has tools, but Codali's provider for them cannot
+ * surface a structured tool call — so choosing one as the tool worker yields a
+ * correct plan and zero tool calls.
+ */
+const NON_TOOL_CALLING_ADAPTERS = new Set(["claude-cli", "codex-cli", "gemini-cli"]);
+const canEmitToolCalls = (assignment) => assignment?.candidate.supportsTools === true &&
+    !NON_TOOL_CALLING_ADAPTERS.has((assignment.candidate.adapter ?? "").toLowerCase());
+const findToolCapableAssignment = (resolution, preferred) => {
+    if (canEmitToolCalls(preferred))
+        return preferred;
+    for (const role of TOOL_CAPABLE_PREFERENCE) {
+        const assignment = resolution.assignments[role];
+        if (canEmitToolCalls(assignment))
+            return assignment;
+    }
+    return Object.values(resolution.assignments).find((assignment) => canEmitToolCalls(assignment));
+};
+const findBySlug = (inventory, slug) => inventory.find((agent) => agent.slug === slug || agent.id === slug);
+/**
+ * Builds the tier policy the resolver consumes. An explicitly bound slug is
+ * honoured for every internal role the configurable role stands in for, so
+ * binding `orchestrator` really does move planning, verification and repair
+ * onto that agent.
+ */
+const buildAgentPolicy = (bindings, inventory, warnings) => {
+    if (!bindings)
+        return undefined;
+    const roles = {};
+    let hasBinding = false;
+    for (const [role, slug] of Object.entries(bindings)) {
+        if (!slug)
+            continue;
+        const agent = findBySlug(inventory, slug);
+        if (!agent) {
+            warnings.push(`agent_binding_not_found:${role}:${slug}`);
+            continue;
+        }
+        hasBinding = true;
+        // Use the bound agent's *own* tier for the role. Imposing the role's
+        // nominal tier here silently discards the operator's choice: binding
+        // `orchestrator` to a large agent left it failing a "medium" requirement
+        // and falling back to whatever the resolver preferred, with the config
+        // appearing to have no effect.
+        const boundTier = (typeof agent.tier === "string" ? agent.tier : undefined) ??
+            (role === "synthesizer" ? "large" : role === "media" ? "image" : "medium");
+        for (const internalRole of ROLE_EXPANSION[role] ?? []) {
+            roles[internalRole] = {
+                tier: boundTier,
+                preferredRunnerKinds: undefined,
+            };
+        }
+    }
+    return hasBinding ? { resolver: "mcoda_inventory", roles } : undefined;
+};
+export const resolveConfigurableRoles = (input) => {
+    const warnings = [];
+    const roles = input.roles ?? PHASE_ONE_ROLES;
+    const internalRoles = roles.flatMap((role) => ROLE_EXPANSION[role] ?? []);
+    const agentPolicy = buildAgentPolicy(input.bindings, input.inventory, warnings);
+    const resolution = resolveCodaliGatewayAgentTiers({
+        inventory: input.inventory,
+        agentPolicy,
+        roles: internalRoles,
+        allowImageWorker: input.allowImageWorker ?? roles.includes("media"),
+    });
+    const assignments = {};
+    const bindingsOut = {};
+    for (const role of roles) {
+        // An explicit binding is the operator's decision and overrides tier
+        // matching outright. Routing it through the tier policy silently discarded
+        // the choice: mcoda's inventory carries no `tier` field — the resolver
+        // infers one — so a bound large agent failed a nominal "medium"
+        // requirement and the config appeared to do nothing.
+        const boundSlug = input.bindings?.[role];
+        if (boundSlug) {
+            const candidate = resolution.candidates.find((entry) => entry.slug === boundSlug || entry.id === boundSlug);
+            if (candidate) {
+                const existing = Object.values(resolution.assignments).find((assignment) => assignment.candidate.slug === candidate.slug);
+                assignments[role] = existing ?? {
+                    role,
+                    policy: { tier: candidate.tier },
+                    candidate,
+                    agent: {
+                        slug: candidate.slug,
+                        adapter: candidate.adapter ?? "",
+                        model: candidate.model ?? "",
+                        supportsTools: candidate.supportsTools,
+                        contextWindow: candidate.contextWindow,
+                        maxOutputTokens: candidate.maxOutputTokens,
+                    },
+                    score: 0,
+                    reasons: ["explicit_binding"],
+                };
+                bindingsOut[role] = candidate.slug;
+                continue;
+            }
+            warnings.push(`agent_binding_unavailable:${role}:${boundSlug}`);
+        }
+        // Otherwise the role is served by the first of its internal roles that
+        // resolved. They share a tier, so any is a valid stand-in.
+        for (const internalRole of ROLE_EXPANSION[role] ?? []) {
+            const assignment = resolution.assignments[internalRole];
+            if (assignment) {
+                assignments[role] = assignment;
+                bindingsOut[role] = assignment.candidate.slug;
+                break;
+            }
+        }
+        if (!assignments[role]) {
+            warnings.push(`agent_role_unresolved:${role}`);
+        }
+    }
+    // An internal role that failed to resolve is only worth reporting when the
+    // configurable role standing in for it also failed. Otherwise every run on a
+    // sparse inventory emits a wall of errors for roles that fell back correctly
+    // and never affected the answer.
+    const servedInternalRoles = new Set(roles
+        .filter((role) => assignments[role])
+        .flatMap((role) => ROLE_EXPANSION[role] ?? []));
+    for (const error of resolution.errors) {
+        if (error.role && servedInternalRoles.has(error.role))
+            continue;
+        warnings.push(`agent_resolution_error:${error.code}${error.role ? `:${error.role}` : ""}`);
+    }
+    const toolCapable = findToolCapableAssignment(resolution, 
+    // An explicitly bound worker wins; otherwise fall back to the orchestrator.
+    assignments.worker ?? assignments.orchestrator);
+    if (!toolCapable) {
+        warnings.push("no_tool_capable_agent");
+    }
+    else if (toolCapable !== assignments.orchestrator) {
+        warnings.push(`tool_worker_substituted:${toolCapable.candidate.slug}`);
+    }
+    return { resolution, assignments, bindings: bindingsOut, toolCapable, warnings };
+};

package/dist/api/ChatCompletionsAdapter.d.ts

@@ -0,0 +1,76 @@
+import { runCodali, type CodaliMessage, type CodaliRequest, type CodaliResult } from "./CodaliApi.js";
+import type { RunContext } from "../runcontext/RunContextResolver.js";
+/**
+ * OpenAI-compatible chat-completions adapter.
+ *
+ * okacam AI chat already speaks this shape. Rather than changing AI chat to
+ * learn Codali's contract, Codali speaks AI chat's — the product points its
+ * existing client at a different base URL and gets orchestration, tools, and
+ * citations without a rewrite.
+ *
+ * The adapter is deliberately thin. It maps message shapes and nothing else;
+ * all routing, tool selection and budget enforcement stay in the one code path
+ * `runCodali` provides, so the adapter cannot drift from the CLI's behaviour.
+ */
+export interface ChatCompletionMessage {
+    role: string;
+    content: string | null;
+}
+export interface ChatCompletionRequest {
+    model?: string;
+    messages: ChatCompletionMessage[];
+    stream?: boolean;
+    response_format?: {
+        type?: string;
+        json_schema?: {
+            schema?: Record<string, unknown>;
+        };
+    };
+    /** Codali-specific extras, ignored by a plain OpenAI client. */
+    codali?: {
+        runContext?: RunContext;
+        workspaceRoot?: string;
+        mode?: CodaliRequest["mode"];
+        media?: CodaliRequest["media"];
+        budgets?: CodaliRequest["budgets"];
+    };
+}
+export interface ChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: "assistant";
+            content: string;
+        };
+        finish_reason: "stop" | "length" | "content_filter";
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    /**
+     * Codali's provenance, carried alongside the OpenAI shape. A plain client
+     * ignores this; a product that wants citations reads it. Without it the
+     * adapter would throw away the very thing that makes an orchestrated answer
+     * trustworthy.
+     */
+    codali: {
+        status: CodaliResult["status"];
+        sources: CodaliResult["sources"];
+        artifacts: CodaliResult["artifacts"];
+        warnings: string[];
+        traceId: string;
+        output?: unknown;
+    };
+}
+export declare const toCodaliMessages: (messages: readonly ChatCompletionMessage[]) => CodaliMessage[];
+export interface ChatAdapterDependencies {
+    run?: typeof runCodali;
+}
+export declare const handleChatCompletion: (request: ChatCompletionRequest, deps?: ChatAdapterDependencies) => Promise<ChatCompletionResponse>;
+//# sourceMappingURL=ChatCompletionsAdapter.d.ts.map

package/dist/api/ChatCompletionsAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatCompletionsAdapter.d.ts","sourceRoot":"","sources":["../../src/api/ChatCompletionsAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAEtE;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAA;KAAE,CAAC;IACxF,gEAAgE;IAChE,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7B,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAC/B,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;KACpC,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,KAAK,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE;YAAE,IAAI,EAAE,WAAW,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;QAChD,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,gBAAgB,CAAC;KACrD,CAAC,CAAC;IACH,KAAK,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF;;;;;OAKG;IACH,MAAM,EAAE;QACN,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC/B,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;QACjC,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;QACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAID,eAAO,MAAM,gBAAgB,GAC3B,UAAU,SAAS,qBAAqB,EAAE,KACzC,aAAa,EAMT,CAAC;AAWR,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,EAAE,OAAO,SAAS,CAAC;CACxB;AAED,eAAO,MAAM,oBAAoB,GAC/B,SAAS,qBAAqB,EAC9B,OAAM,uBAA4B,KACjC,OAAO,CAAC,sBAAsB,CAsChC,CAAC"}

package/dist/api/ChatCompletionsAdapter.js

@@ -0,0 +1,54 @@
+import { runCodali } from "./CodaliApi.js";
+const CHAT_ROLES = new Set(["system", "user", "assistant"]);
+export const toCodaliMessages = (messages) => messages
+    .filter((message) => CHAT_ROLES.has(message.role) && typeof message.content === "string")
+    .map((message) => ({
+    role: message.role,
+    content: message.content,
+}));
+const readResponseSchema = (request) => {
+    const format = request.response_format;
+    if (!format)
+        return undefined;
+    if (format.type === "json_schema")
+        return format.json_schema?.schema;
+    return undefined;
+};
+export const handleChatCompletion = async (request, deps = {}) => {
+    const run = deps.run ?? runCodali;
+    const result = await run({
+        messages: toCodaliMessages(request.messages),
+        runContext: request.codali?.runContext,
+        workspaceRoot: request.codali?.workspaceRoot,
+        mode: request.codali?.mode,
+        media: request.codali?.media,
+        budgets: request.codali?.budgets,
+        responseSchema: readResponseSchema(request),
+        responseMode: request.response_format?.type === "json_object" ? "json" : "text",
+        product: { name: "chat-completions" },
+    });
+    return {
+        id: `chatcmpl-${result.traceId}`,
+        object: "chat.completion",
+        created: Math.floor(Date.now() / 1000),
+        model: request.model ?? "codali",
+        choices: [
+            {
+                index: 0,
+                message: { role: "assistant", content: result.answer },
+                // A partial or clarification-seeking answer is not a normal stop. A
+                // client that only inspects finish_reason must not mistake it for a
+                // complete response.
+                finish_reason: result.status === "succeeded" ? "stop" : "length",
+            },
+        ],
+        codali: {
+            status: result.status,
+            sources: result.sources,
+            artifacts: result.artifacts,
+            warnings: result.warnings,
+            traceId: result.traceId,
+            output: result.output,
+        },
+    };
+};

package/dist/api/CodaliApi.d.ts

@@ -0,0 +1,78 @@
+import { attachMcpTools } from "../connectors/mcp/McpToolSource.js";
+import { type ImageGenerationConfig } from "../connectors/media/ImageGenerationTool.js";
+import { createProviderForAssignment } from "../gateway/LocalGatewayProvider.js";
+import { getAgentInventory } from "../agents/AgentInventory.js";
+import { ToolRegistry } from "../tools/ToolRegistry.js";
+import type { RunContext } from "../runcontext/RunContextResolver.js";
+import type { CodaliArtifactRef, CodaliGatewayMode, CodaliGatewaySource, CodaliGatewayStatus } from "../gateway/CodaliGatewayTypes.js";
+/**
+ * The canonical Codali API.
+ *
+ * This is the contract products integrate against — okacam AI chat, line items,
+ * badges, employee daily-log review. One entry point, one result shape, the
+ * same behaviour the CLI gets, so a product never has to reimplement routing,
+ * tool selection, evidence handling, or budget enforcement.
+ *
+ * Everything a run is allowed to touch arrives on the request as `runContext`.
+ * Codali does not call back into the host to fetch tenant configuration: the
+ * authenticated host already holds it, and a callback would make every request
+ * a circular distributed dependency.
+ */
+export interface CodaliMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface CodaliRequest {
+    messages: CodaliMessage[];
+    /** Tenant scope, tools, credentials, agent bindings, limits. */
+    runContext?: RunContext;
+    /** JSON Schema the answer must satisfy. Enforced, with one repair attempt. */
+    responseSchema?: Record<string, unknown>;
+    responseMode?: "text" | "json" | "artifact";
+    mode?: CodaliGatewayMode;
+    /** Workspace the run resolves paths against. Defaults to `process.cwd()`. */
+    workspaceRoot?: string;
+    requestId?: string;
+    product?: {
+        name?: string;
+        version?: string;
+        surface?: string;
+    };
+    /** Image generation config; absent means the media tool is not offered. */
+    media?: ImageGenerationConfig;
+    budgets?: {
+        maxRounds?: number;
+        maxToolCalls?: number;
+        maxModelCalls?: number;
+        deadlineMs?: number;
+    };
+}
+export interface CodaliSourceRef extends CodaliGatewaySource {
+}
+export interface CodaliResult {
+    status: CodaliGatewayStatus;
+    /** Text answer, or the clarifying question when status is needs_clarification. */
+    answer: string;
+    /** Schema-conformant structured output when a responseSchema was supplied. */
+    output: unknown;
+    sources: CodaliSourceRef[];
+    artifacts: CodaliArtifactRef[];
+    warnings: string[];
+    traceId: string;
+}
+/** Flattens a message list into the single query the gateway plans against. */
+export declare const messagesToQuery: (messages: readonly CodaliMessage[]) => string;
+export interface CodaliRunDependencies {
+    loadInventory?: typeof getAgentInventory;
+    resolveRunContext?: (workspaceRoot: string) => Promise<RunContext>;
+    buildRegistry?: (workspaceRoot: string, context: RunContext) => ToolRegistry;
+    createProvider?: typeof createProviderForAssignment;
+    attachMcp?: typeof attachMcpTools;
+}
+/**
+ * Runs one Codali request end to end.
+ *
+ * The same code path the CLI uses, so a product and the terminal cannot drift.
+ */
+export declare const runCodali: (request: CodaliRequest, deps?: CodaliRunDependencies) => Promise<CodaliResult>;
+//# sourceMappingURL=CodaliApi.d.ts.map

package/dist/api/CodaliApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodaliApi.d.ts","sourceRoot":"","sources":["../../src/api/CodaliApi.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,4CAA4C,CAAC;AAIpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAGjF,OAAO,EAAE,iBAAiB,EAAyB,MAAM,6BAA6B,CAAC;AAGvF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EAEjB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,gEAAgE;IAChE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IAC5C,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,2EAA2E;IAC3E,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;CAAG;AAE/D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD,+EAA+E;AAC/E,eAAO,MAAM,eAAe,GAAI,UAAU,SAAS,aAAa,EAAE,KAAG,MAWpE,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,OAAO,iBAAiB,CAAC;IACzC,iBAAiB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACnE,aAAa,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,YAAY,CAAC;IAC7E,cAAc,CAAC,EAAE,OAAO,2BAA2B,CAAC;IACpD,SAAS,CAAC,EAAE,OAAO,cAAc,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GACpB,SAAS,aAAa,EACtB,OAAM,qBAA0B,KAC/B,OAAO,CAAC,YAAY,CAkOtB,CAAC"}