@mcoda/codali 0.1.87 → 0.1.89

package/dist/runtime/CodaliJobRuntime.js

@@ -0,0 +1,590 @@
+import { randomUUID } from "node:crypto";
+import { runCodaliTask, } from "./CodaliRuntime.js";
+const DEFAULT_JOB_TYPE = "codali_job";
+const DEFAULT_MAX_RUNTIME_MS = 3600000;
+const DEFAULT_MAX_FOLLOWUPS = 1;
+const DEFAULT_MAX_PARALLEL_STAGES = 2;
+const DEFAULT_STAGES = [
+    {
+        id: "router",
+        kind: "router",
+        goal: "Classify the request, identify the relevant tools, and decide whether clarification is needed.",
+    },
+    {
+        id: "planner",
+        kind: "planner",
+        dependsOn: ["router"],
+        goal: "Create a concise execution plan grounded in the available context and tool manifest.",
+    },
+    {
+        id: "worker",
+        kind: "worker",
+        dependsOn: ["planner"],
+        goal: "Answer the request or produce the requested artifact using only allowed read-only capabilities unless writes are explicitly enabled.",
+    },
+    {
+        id: "adjudicator",
+        kind: "adjudicator",
+        dependsOn: ["worker"],
+        goal: "Check whether the worker output follows the plan and policy.",
+    },
+    {
+        id: "synthesizer",
+        kind: "synthesizer",
+        dependsOn: ["worker", "adjudicator"],
+        goal: "Produce the final user-facing response from the prior stages.",
+    },
+    {
+        id: "verifier",
+        kind: "verifier",
+        dependsOn: ["synthesizer"],
+        goal: "Verify the final response. Return JSON with passed, summary, issues, and repairPrompt when possible.",
+        response: { format: "json" },
+    },
+];
+const nowIso = () => new Date().toISOString();
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const cleanText = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+const normalizeDependsOn = (stage) => {
+    const value = stage.dependsOn ??
+        stage.depends_on ??
+        [];
+    return Array.isArray(value)
+        ? value.map((entry) => cleanText(entry)).filter((entry) => Boolean(entry))
+        : [];
+};
+const normalizeStage = (stage, index) => {
+    const id = cleanText(stage.id) ?? `${stage.kind || "stage"}-${index + 1}`;
+    const kind = cleanText(stage.kind) ?? "worker";
+    return {
+        ...stage,
+        id: id.replace(/[^a-zA-Z0-9._-]+/g, "_"),
+        kind,
+        dependsOn: normalizeDependsOn(stage),
+    };
+};
+const normalizeStages = (stages) => (stages?.length ? stages : DEFAULT_STAGES).map(normalizeStage);
+const validateStageDag = (stages) => {
+    const ids = new Set();
+    for (const stage of stages) {
+        if (ids.has(stage.id)) {
+            throw new Error(`Duplicate Codali job stage id: ${stage.id}`);
+        }
+        ids.add(stage.id);
+    }
+    for (const stage of stages) {
+        for (const dependency of stage.dependsOn ?? []) {
+            if (!ids.has(dependency)) {
+                throw new Error(`Codali job stage ${stage.id} depends on unknown stage ${dependency}`);
+            }
+            if (dependency === stage.id) {
+                throw new Error(`Codali job stage ${stage.id} depends on itself`);
+            }
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const byId = new Map(stages.map((stage) => [stage.id, stage]));
+    const visit = (stage) => {
+        if (visited.has(stage.id))
+            return;
+        if (visiting.has(stage.id)) {
+            throw new Error(`Codali job stage dependency cycle includes ${stage.id}`);
+        }
+        visiting.add(stage.id);
+        for (const dependency of stage.dependsOn ?? []) {
+            const dep = byId.get(dependency);
+            if (dep)
+                visit(dep);
+        }
+        visiting.delete(stage.id);
+        visited.add(stage.id);
+    };
+    for (const stage of stages)
+        visit(stage);
+};
+const describeUnknown = (value) => {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+};
+const truncate = (value, max = 6000) => value.length > max ? `${value.slice(0, max)}\n[truncated]` : value;
+const formatPriorStageResults = (results) => {
+    if (!results.length)
+        return "None yet.";
+    return results
+        .map((result) => {
+        const header = `${result.id} (${result.kind}, ${result.status})`;
+        const error = result.error ? `\nError: ${result.error.code}: ${result.error.message}` : "";
+        return `### ${header}\n${truncate(result.output || "", 2000)}${error}`;
+    })
+        .join("\n\n");
+};
+const buildStageTask = (input) => {
+    const { request, stage, priorResults, evidence, toolManifest, repairPrompt } = input;
+    const lines = [
+        "Codali multi-stage job runtime",
+        `Job id: ${request.id ?? "unspecified"}`,
+        `Job type: ${request.jobType || DEFAULT_JOB_TYPE}`,
+        `Stage id: ${stage.id}`,
+        `Stage kind: ${stage.kind}`,
+        stage.role ? `Stage role: ${stage.role}` : "",
+        stage.title ? `Stage title: ${stage.title}` : "",
+        stage.goal ? `Stage goal: ${stage.goal}` : "",
+        stage.prompt ? `Stage instructions:\n${stage.prompt}` : "",
+        repairPrompt ? `Verifier repair request:\n${repairPrompt}` : "",
+        "Original job input:",
+        truncate(describeUnknown(request.input) || "(no explicit input)"),
+        request.context ? `Job context:\n${truncate(describeUnknown(request.context))}` : "",
+        request.tenant ? `Tenant scope:\n${truncate(describeUnknown(request.tenant), 2000)}` : "",
+        toolManifest ? `Runtime tool manifest:\n${truncate(describeUnknown(toolManifest), 3000)}` : "",
+        evidence.length ? `Evidence accumulated:\n${truncate(describeUnknown(evidence), 3000)}` : "",
+        "Prior stage results:",
+        formatPriorStageResults(priorResults),
+        request.response?.requireEvidence
+            ? "When making factual claims, include evidence cards in a JSON evidence array when the response format allows it."
+            : "",
+        "Stay within the active runtime policy and tenant/workspace scope.",
+    ];
+    return lines.filter(Boolean).join("\n\n");
+};
+const parseJsonLikeObject = (content) => {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return undefined;
+    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+    const body = fenced?.[1]?.trim() ?? trimmed;
+    const tryParse = (value) => {
+        try {
+            const parsed = JSON.parse(value);
+            return isRecord(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const exact = tryParse(body);
+    if (exact)
+        return exact;
+    const first = body.indexOf("{");
+    const last = body.lastIndexOf("}");
+    if (first >= 0 && last > first) {
+        return tryParse(body.slice(first, last + 1));
+    }
+    return undefined;
+};
+const normalizeEvidence = (stageId, parsed) => {
+    const raw = parsed?.evidence;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter(isRecord).map((entry, index) => ({
+        id: cleanText(entry.id) ?? `${stageId}-evidence-${index + 1}`,
+        stageId,
+        source: cleanText(entry.source),
+        title: cleanText(entry.title),
+        summary: cleanText(entry.summary) ?? cleanText(entry.text) ?? cleanText(entry.content),
+        confidence: typeof entry.confidence === "number" ? entry.confidence : undefined,
+        metadata: isRecord(entry.metadata) ? entry.metadata : undefined,
+    }));
+};
+const normalizeVerifier = (stage, parsed) => {
+    if (stage.kind !== "verifier" && parsed?.passed === undefined)
+        return undefined;
+    const issues = Array.isArray(parsed?.issues)
+        ? parsed.issues.map((issue) => cleanText(issue)).filter((issue) => Boolean(issue))
+        : undefined;
+    return {
+        passed: parsed?.passed === true,
+        summary: cleanText(parsed?.summary) ?? cleanText(parsed?.message),
+        issues,
+        repairPrompt: cleanText(parsed?.repairPrompt) ?? cleanText(parsed?.repair_prompt),
+        metadata: isRecord(parsed?.metadata) ? parsed.metadata : undefined,
+    };
+};
+const needsClarification = (parsed) => parsed?.status === "needs_clarification" ||
+    parsed?.needsClarification === true ||
+    parsed?.needs_clarification === true ||
+    typeof parsed?.clarifyingQuestion === "string" ||
+    typeof parsed?.clarifying_question === "string";
+const mergeUsage = (left, right) => {
+    if (!right)
+        return left;
+    const inputTokens = (left?.inputTokens ?? 0) + (right.inputTokens ?? 0);
+    const outputTokens = (left?.outputTokens ?? 0) + (right.outputTokens ?? 0);
+    const totalTokens = (left?.totalTokens ?? 0) + (right.totalTokens ?? right.inputTokens ?? 0) + (right.outputTokens ?? 0);
+    return { inputTokens, outputTokens, totalTokens };
+};
+const mergeUnique = (values) => Array.from(new Set(values.flat().filter(Boolean)));
+const resolveStageAgent = (request, runtime, stage) => stage.agent ??
+    request.agentPolicy?.stageAgents?.[stage.id] ??
+    (stage.role ? request.agentPolicy?.stageAgents?.[stage.role] : undefined) ??
+    request.agentPolicy?.stageAgents?.[stage.kind] ??
+    request.agentPolicy?.defaultAgent ??
+    runtime.agent;
+const resolveStageProvider = (request, runtime, stage) => stage.provider ??
+    request.agentPolicy?.stageProviders?.[stage.id] ??
+    (stage.role ? request.agentPolicy?.stageProviders?.[stage.role] : undefined) ??
+    request.agentPolicy?.stageProviders?.[stage.kind] ??
+    request.agentPolicy?.defaultProvider ??
+    runtime.provider;
+const responseForStage = (request, runtime, stage) => {
+    if (stage.response)
+        return stage.response;
+    if (stage.outputSchema)
+        return { format: "json_schema", schema: stage.outputSchema };
+    if (request.response?.format === "json_schema") {
+        return { format: "json_schema", schema: request.response.schema };
+    }
+    if (request.response?.format === "json")
+        return { format: "json" };
+    return runtime.response;
+};
+const runWithLimit = async (items, maxParallel, worker) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(Math.max(1, maxParallel), items.length) }, async () => {
+        while (next < items.length) {
+            const index = next;
+            next += 1;
+            results[index] = await worker(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+};
+const errorStageResult = (input) => {
+    const ended = Date.now();
+    const started = Date.parse(input.startedAt);
+    return {
+        id: input.stage.id,
+        kind: input.stage.kind,
+        status: "failed",
+        attempt: input.attempt,
+        output: "",
+        messages: [],
+        toolCallsExecuted: 0,
+        touchedFiles: [],
+        warnings: [],
+        evidence: [],
+        startedAt: input.startedAt,
+        endedAt: new Date(ended).toISOString(),
+        durationMs: Number.isFinite(started) ? ended - started : 0,
+        agentSlug: input.agentSlug,
+        model: input.model,
+        error: input.error,
+    };
+};
+const buildTelemetry = (input) => ({
+    runId: input.runId,
+    runtime: "codali",
+    mode: "job",
+    jobId: input.jobId,
+    jobType: input.jobType,
+    status: input.status,
+    stageCount: input.stages.length,
+    toolCallCount: input.stages.reduce((sum, stage) => sum + stage.toolCallsExecuted, 0),
+    calledTools: mergeUnique(input.stages.map((stage) => stage.telemetry?.calledTools ?? [])),
+    consideredTools: mergeUnique(input.stages.map((stage) => stage.telemetry?.consideredTools ?? [])),
+    warnings: input.warnings,
+    errors: input.errors,
+    stages: input.stages.map((stage) => ({
+        id: stage.id,
+        kind: stage.kind,
+        status: stage.status,
+        attempt: stage.attempt,
+        durationMs: stage.durationMs,
+        toolCallsExecuted: stage.toolCallsExecuted,
+        agentSlug: stage.agentSlug,
+        model: stage.model,
+        errorCode: stage.error?.code,
+    })),
+});
+const pickFinalOutput = (stages) => {
+    for (let index = stages.length - 1; index >= 0; index -= 1) {
+        const stage = stages[index];
+        if ((stage.kind === "repair" || stage.kind === "synthesizer") && stage.status === "completed" && stage.output) {
+            return stage.output;
+        }
+    }
+    for (let index = stages.length - 1; index >= 0; index -= 1) {
+        const stage = stages[index];
+        if (stage.status === "completed" && stage.output) {
+            return stage.output;
+        }
+    }
+    return "";
+};
+export const runCodaliJob = async (input) => {
+    const jobId = input.request.id ?? input.runtime.metadata?.jobId ?? randomUUID();
+    const jobType = input.request.jobType || DEFAULT_JOB_TYPE;
+    const runId = input.runtime.metadata?.requestId ?? jobId;
+    const runTask = input.runTask ?? runCodaliTask;
+    const stages = normalizeStages(input.request.stages);
+    validateStageDag(stages);
+    const warnings = [];
+    const errors = [];
+    const events = [];
+    const results = [];
+    const resultById = new Map();
+    const started = Date.now();
+    const maxRuntimeMs = input.request.budgets?.maxRuntimeMs ?? input.runtime.policy.timeoutMs ?? DEFAULT_MAX_RUNTIME_MS;
+    const deadline = started + maxRuntimeMs;
+    const maxParallel = input.request.budgets?.maxParallelStages ?? DEFAULT_MAX_PARALLEL_STAGES;
+    let remainingToolCalls = input.request.budgets?.maxToolCalls ?? input.runtime.policy.maxToolCalls;
+    let status = "succeeded";
+    let usage;
+    let stopped = false;
+    const emit = async (event) => {
+        events.push(event);
+        await input.onEvent?.(event);
+    };
+    await emit({ type: "job_start", runId, jobId, jobType, at: nowIso() });
+    const runStage = async (stage, allocatedToolCalls, attempt, repairPrompt) => {
+        const stageAgent = resolveStageAgent(input.request, input.runtime, stage);
+        const stageProvider = resolveStageProvider(input.request, input.runtime, stage);
+        const startedAt = nowIso();
+        await emit({ type: "stage_start", runId, jobId, stageId: stage.id, kind: stage.kind, attempt, at: startedAt });
+        if (Date.now() >= deadline) {
+            const error = { stageId: stage.id, code: "job_timeout", message: "Codali job runtime budget expired." };
+            await emit({ type: "stage_error", runId, jobId, kind: stage.kind, ...error, at: nowIso() });
+            return errorStageResult({ stage, attempt, startedAt, error, agentSlug: stageAgent?.slug, model: stageProvider.model });
+        }
+        if (allocatedToolCalls < 0) {
+            const error = { stageId: stage.id, code: "tool_budget_exhausted", message: "Codali job tool-call budget is exhausted." };
+            await emit({ type: "stage_error", runId, jobId, kind: stage.kind, ...error, at: nowIso() });
+            return errorStageResult({ stage, attempt, startedAt, error, agentSlug: stageAgent?.slug, model: stageProvider.model });
+        }
+        const priorResults = results.slice();
+        const task = buildStageTask({
+            request: input.request,
+            stage,
+            priorResults,
+            evidence: results.flatMap((result) => result.evidence),
+            toolManifest: input.request.toolManifest ?? input.runtime.docdex?.toolManifest,
+            repairPrompt,
+        });
+        const timeoutMs = Math.max(0, Math.min(stage.timeoutMs ?? input.runtime.policy.timeoutMs, deadline - Date.now()));
+        const policy = {
+            ...input.runtime.policy,
+            mode: stage.mode ?? input.runtime.policy.mode,
+            maxSteps: stage.maxSteps ?? input.runtime.policy.maxSteps,
+            maxToolCalls: Math.max(0, Math.min(stage.maxToolCalls ?? allocatedToolCalls, allocatedToolCalls)),
+            timeoutMs,
+        };
+        try {
+            const runtimeResult = await runTask({
+                ...input.runtime,
+                task,
+                messages: input.runtime.messages,
+                provider: stageProvider,
+                agent: stageAgent,
+                policy,
+                response: responseForStage(input.request, input.runtime, stage),
+                docdex: {
+                    ...input.runtime.docdex,
+                    toolManifest: input.request.toolManifest ?? input.runtime.docdex?.toolManifest,
+                },
+                metadata: {
+                    ...input.runtime.metadata,
+                    jobId,
+                    requestId: `${runId}:${stage.id}:attempt-${attempt}`,
+                    agentSlug: stageAgent?.slug ?? input.runtime.metadata?.agentSlug,
+                },
+                onEvent: async (event) => {
+                    await input.runtime.onEvent?.(event);
+                    await emit({ type: "runtime_event", runId, jobId, stageId: stage.id, event, at: nowIso() });
+                },
+            });
+            const ended = Date.now();
+            const parsedOutput = parseJsonLikeObject(runtimeResult.finalMessage);
+            const evidence = normalizeEvidence(stage.id, parsedOutput);
+            const verifier = normalizeVerifier(stage, parsedOutput);
+            const stageWarnings = [...runtimeResult.warnings];
+            if (runtimeResult.toolCallsExecuted > policy.maxToolCalls) {
+                stageWarnings.push(`Stage ${stage.id} reported ${runtimeResult.toolCallsExecuted} tool calls, above allocated budget ${policy.maxToolCalls}.`);
+            }
+            const stageResult = {
+                id: stage.id,
+                kind: stage.kind,
+                status: "completed",
+                attempt,
+                output: runtimeResult.finalMessage,
+                parsedOutput,
+                usage: runtimeResult.usage,
+                messages: runtimeResult.messages,
+                toolCallsExecuted: runtimeResult.toolCallsExecuted,
+                touchedFiles: runtimeResult.touchedFiles,
+                warnings: stageWarnings,
+                telemetry: runtimeResult.telemetry,
+                evidence,
+                verifier,
+                startedAt,
+                endedAt: new Date(ended).toISOString(),
+                durationMs: ended - Date.parse(startedAt),
+                agentSlug: stageAgent?.slug,
+                model: stageProvider.model,
+                metadata: stage.metadata,
+            };
+            await emit({
+                type: "stage_result",
+                runId,
+                jobId,
+                stageId: stage.id,
+                kind: stage.kind,
+                status: stageResult.status,
+                durationMs: stageResult.durationMs,
+                toolCallsExecuted: stageResult.toolCallsExecuted,
+                at: nowIso(),
+            });
+            return stageResult;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const runtimeError = {
+                stageId: stage.id,
+                code: error instanceof Error ? error.name : "stage_error",
+                message,
+            };
+            await emit({ type: "stage_error", runId, jobId, kind: stage.kind, ...runtimeError, at: nowIso() });
+            return errorStageResult({
+                stage,
+                attempt,
+                startedAt,
+                error: runtimeError,
+                agentSlug: stageAgent?.slug,
+                model: stageProvider.model,
+            });
+        }
+    };
+    const pending = new Map(stages.map((stage) => [stage.id, stage]));
+    while (pending.size && !stopped) {
+        const ready = Array.from(pending.values()).filter((stage) => (stage.dependsOn ?? []).every((dependency) => resultById.has(dependency)));
+        if (!ready.length) {
+            throw new Error("Codali job stage scheduler stalled; dependency validation may be incomplete.");
+        }
+        const active = ready.slice(0, Math.max(1, maxParallel));
+        const allocations = new Map();
+        const requested = active.map((stage) => Math.max(0, stage.maxToolCalls ?? remainingToolCalls));
+        const requestedTotal = requested.reduce((sum, value) => sum + value, 0);
+        if (requestedTotal <= remainingToolCalls) {
+            active.forEach((stage, index) => allocations.set(stage.id, requested[index] ?? 0));
+        }
+        else {
+            let rest = remainingToolCalls;
+            active.forEach((stage, index) => {
+                const slotsLeft = active.length - index;
+                const fairShare = Math.floor(rest / slotsLeft);
+                const allocation = Math.min(requested[index] ?? 0, fairShare);
+                allocations.set(stage.id, allocation);
+                rest -= allocation;
+            });
+        }
+        const waveResults = await runWithLimit(active, maxParallel, async (stage) => {
+            if (remainingToolCalls <= 0 && (stage.maxToolCalls ?? input.runtime.policy.maxToolCalls) > 0) {
+                const startedAt = nowIso();
+                const error = {
+                    stageId: stage.id,
+                    code: "tool_budget_exhausted",
+                    message: "Codali job tool-call budget is exhausted.",
+                };
+                return errorStageResult({ stage, attempt: 1, startedAt, error });
+            }
+            return runStage(stage, allocations.get(stage.id) ?? 0, 1);
+        });
+        for (const stageResult of waveResults) {
+            pending.delete(stageResult.id);
+            results.push(stageResult);
+            resultById.set(stageResult.id, stageResult);
+            usage = mergeUsage(usage, stageResult.usage);
+            remainingToolCalls -= stageResult.toolCallsExecuted;
+            warnings.push(...stageResult.warnings);
+            if (stageResult.error) {
+                errors.push(stageResult.error);
+                const originalStage = stages.find((stage) => stage.id === stageResult.id);
+                if (!originalStage?.optional) {
+                    status = "failed";
+                    stopped = true;
+                }
+                else {
+                    status = status === "succeeded" ? "partial" : status;
+                }
+            }
+            if (needsClarification(stageResult.parsedOutput)) {
+                status = "needs_clarification";
+                stopped = true;
+            }
+        }
+    }
+    const verifier = results.find((stage) => stage.verifier)?.verifier;
+    if (status === "succeeded" && verifier && !verifier.passed) {
+        status = "partial";
+        warnings.push(verifier.summary ?? "Verifier did not pass the synthesized result.");
+        const maxFollowups = input.request.budgets?.maxFollowups ?? DEFAULT_MAX_FOLLOWUPS;
+        if (maxFollowups > 0 && remainingToolCalls > 0) {
+            const repairStage = {
+                id: "repair-1",
+                kind: "repair",
+                goal: "Repair the synthesized answer using the verifier feedback.",
+                prompt: verifier.repairPrompt,
+                dependsOn: [],
+                maxToolCalls: remainingToolCalls,
+            };
+            const repairResult = await runStage(repairStage, remainingToolCalls, 1, verifier.repairPrompt);
+            results.push(repairResult);
+            usage = mergeUsage(usage, repairResult.usage);
+            remainingToolCalls -= repairResult.toolCallsExecuted;
+            warnings.push(...repairResult.warnings);
+            if (repairResult.error) {
+                errors.push(repairResult.error);
+            }
+        }
+    }
+    if (status !== "failed" && remainingToolCalls < 0) {
+        status = "failed";
+        errors.push({
+            code: "tool_budget_exceeded",
+            message: "Codali job exceeded its total tool-call budget.",
+        });
+    }
+    const output = pickFinalOutput(results);
+    const evidence = results.flatMap((stage) => stage.evidence);
+    const messages = results.flatMap((stage) => stage.messages);
+    const touchedFiles = mergeUnique(results.map((stage) => stage.touchedFiles));
+    const toolCallsExecuted = results.reduce((sum, stage) => sum + stage.toolCallsExecuted, 0);
+    const telemetry = buildTelemetry({ runId, jobId, jobType, status, stages: results, warnings, errors });
+    await emit({
+        type: "job_result",
+        runId,
+        jobId,
+        status,
+        stageCount: results.length,
+        toolCallsExecuted,
+        at: nowIso(),
+    });
+    return {
+        output,
+        status,
+        runId,
+        jobId,
+        jobType,
+        stages: results,
+        evidence,
+        verifier,
+        messages,
+        usage,
+        toolCallsExecuted,
+        touchedFiles,
+        warnings,
+        errors,
+        events,
+        telemetry,
+        metadata: input.request.metadata,
+    };
+};