@maintainabilityai/research-runner 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MaintainabilityAI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @maintainabilityai/research-runner
+
+CLI that orchestrates the **Archeologist** (research) and **PRD** agent pipelines
+for the MaintainabilityAI governance mesh. Invoked by the Looking Glass-scaffolded
+GitHub Actions workflows in the mesh repo (`archeologist.yml`, `prd.yml`).
+
+See [docs/design/research-and-prd-agents.md](../../docs/design/research-and-prd-agents.md)
+for the full pipeline design.
+
+## Status
+
+**v0.1 — Phase 1**: package scaffold, Zod schemas, audit emitter (hash-chained
+JSONL), Hatter's Tag builder, stub orchestrators. **No LLM or search-API calls
+yet** — those land in subsequent phases.
+
+## Install
+
+```bash
+npm install -g @maintainabilityai/research-runner
+# or run via npx in CI:
+npx research-runner archeologist --brief "..." --scope-level bar --scope-id APP-IMDB-002
+```
+
+## CLI
+
+```
+research-runner archeologist [options]
+  --brief         <text>      Plain-English research brief (required)
+  --scope-level   portfolio|platform|bar
+  --scope-id      <id>        BAR or platform id (required when scope is platform|bar)
+  --path          research|archaeology     (default: research)
+  --target-repo   owner/repo  (archaeology path only)
+  --guardrails    strict|default|lenient   (default: default)
+  --output        <dir>       Where to write artifacts (default: ./research)
+  --audit         <dir>       Where to write JSONL audit log (default: ./.research-audit)
+  --emit-pr-body  <path>      Write the PR body markdown to this path
+  --mesh          <dir>       Mesh repo root (default: cwd)
+
+research-runner prd [options]
+  --research-pr   <url|path>  Merged research PR url or research doc path
+  --scope-level   portfolio|platform|bar
+  --scope-id      <id>
+  --mode          shallow|deep                (default: deep)
+  --grounding     strict|default|lenient      (default: default)
+  --max-iterations <n>                        (default: 3)
+  --output        <dir>       Where to write artifacts (default: ./prds)
+  --audit         <dir>
+  --emit-pr-body  <path>
+  --mesh          <dir>
+```
+
+## Architecture
+
+- `src/schemas/`     Zod schemas for every input/output shape
+- `src/runner/`      Pipeline orchestrators + cross-cutting utilities (audit, Hatter's Tag)
+- `src/utils/`       Stateless helpers (run-id, time, hashing)
+- `bin/`             CLI entry stub that requires `dist/cli.js`
+
+The runner is deliberately split into **pure nodes** (validation, search APIs,
+dedupe, publish) and **LLM nodes** (query planning, synthesis, expert reviews).
+Pure nodes are reproducible; LLM nodes produce non-deterministic content but
+deterministic *shape* (Zod-validated). See the design doc for the full
+determinism contract.
+
+## Audit log
+
+Every node emits a hash-chained JSONL event to
+`<audit-dir>/<run_id>.jsonl`. Each event carries `prev_event_hash` and
+`event_hash` (sha256), forming a tamper-evident Merkle-like chain. The final
+`run_complete` event summarizes the run and pins the chain root hash.
+
+## Hatter's Tag
+
+Every published artifact (research doc, PRD) ends with a `## Hatter's Tag`
+YAML block that pins the run to a specific mesh sha, prompt-library version,
+LLM provider/model, token count, cost, grounding score, and audit chain hash.
+Auditors verify the artifact by re-running the chain against the recorded
+mesh sha.
+
+## License
+
+MIT

package/bin/research-runner.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli.js');

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,209 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @maintainabilityai/research-runner CLI entry.
+ *
+ * Two subcommands: `archeologist` (research pipeline) and `prd` (PRD pipeline).
+ * Parses argv into a typed brief, runs the orchestrator, prints structured
+ * outputs that the calling GitHub Action consumes via `core.setOutput`.
+ *
+ * Zero dep on a CLI framework — argv parsing is hand-rolled to keep the
+ * package small. The flag surface is fixed by the design doc and shouldn't
+ * grow without intent.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const archeologist_1 = require("./runner/archeologist");
+const prd_1 = require("./runner/prd");
+const PKG = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            continue;
+        }
+        const key = arg.slice(2).replace(/-/g, '_');
+        const value = argv[i + 1];
+        if (!value || value.startsWith('--')) {
+            // boolean flag — not used yet
+            continue;
+        }
+        flags[key] = value;
+        i++;
+    }
+    return flags;
+}
+function emitGithubOutput(outputs) {
+    // Run inside GitHub Actions, write to GITHUB_OUTPUT so `steps.<id>.outputs.*` works.
+    const githubOutput = process.env.GITHUB_OUTPUT;
+    if (!githubOutput) {
+        return;
+    }
+    const lines = Object.entries(outputs).map(([k, v]) => `${k}=${v}`);
+    fs.appendFileSync(githubOutput, lines.join('\n') + '\n', 'utf8');
+}
+function abort(msg, code = 1) {
+    process.stderr.write(`research-runner: ${msg}\n`);
+    process.exit(code);
+}
+async function archeologistCmd(argv) {
+    const flags = parseFlags(argv);
+    if (!flags.brief) {
+        abort('--brief is required');
+    }
+    if (!flags.scope_level) {
+        abort('--scope-level is required');
+    }
+    if (!flags.scope_id) {
+        abort('--scope-id is required (portfolio scope was removed; pass platform slug or BAR id)');
+    }
+    const briefInput = {
+        topic: flags.brief,
+        scope: {
+            level: flags.scope_level,
+            id: flags.scope_id,
+        },
+        path: flags.path || 'research',
+        target_repo: flags.target_repo || undefined,
+        guardrails: flags.guardrails || 'default',
+        llm_provider: flags.llm_provider || undefined,
+        trigger: {
+            kind: process.env.GITHUB_ACTIONS === 'true' ? 'workflow_dispatch' : 'local_dev',
+            actor: process.env.GITHUB_ACTOR,
+        },
+    };
+    const result = await (0, archeologist_1.runArcheologist)({
+        brief: briefInput,
+        meshDir: flags.mesh ? path.resolve(flags.mesh) : process.cwd(),
+        outputDir: flags.output || 'research',
+        auditDir: flags.audit || '.research-audit',
+        emitPrBodyPath: flags.emit_pr_body,
+        agentVersion: PKG.version,
+    });
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    emitGithubOutput({
+        run_id: result.run_id,
+        topic: result.topic,
+        artifact_path: result.artifact_path,
+        chain_root_hash: result.chain_root_hash,
+        pr_body_path: result.pr_body_path || '',
+    });
+}
+async function prdCmd(argv) {
+    const flags = parseFlags(argv);
+    if (!flags.research_pr) {
+        abort('--research-pr is required');
+    }
+    if (!flags.scope_level) {
+        abort('--scope-level is required');
+    }
+    if (!flags.scope_id) {
+        abort('--scope-id is required (portfolio scope was removed; pass platform slug or BAR id)');
+    }
+    const isUrl = /^https?:\/\//.test(flags.research_pr);
+    const briefInput = {
+        research_source: isUrl
+            ? { kind: 'pr', url: flags.research_pr }
+            : { kind: 'path', relative_path: flags.research_pr },
+        scope: {
+            level: flags.scope_level,
+            id: flags.scope_id,
+        },
+        mode: flags.mode || 'deep',
+        grounding: flags.grounding || 'default',
+        max_iterations: flags.max_iterations ? parseInt(flags.max_iterations, 10) : 3,
+        llm_provider: flags.llm_provider || undefined,
+        trigger: {
+            kind: process.env.GITHUB_ACTIONS === 'true' ? 'workflow_dispatch' : 'local_dev',
+            actor: process.env.GITHUB_ACTOR,
+        },
+    };
+    const result = await (0, prd_1.runPrd)({
+        brief: briefInput,
+        meshDir: flags.mesh ? path.resolve(flags.mesh) : process.cwd(),
+        outputDir: flags.output || 'prds',
+        auditDir: flags.audit || '.research-audit',
+        emitPrBodyPath: flags.emit_pr_body,
+        agentVersion: PKG.version,
+    });
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    emitGithubOutput({
+        run_id: result.run_id,
+        topic: result.topic,
+        artifact_path: result.artifact_path,
+        chain_root_hash: result.chain_root_hash,
+        pr_body_path: result.pr_body_path || '',
+        final_score: result.final_score,
+        iterations: result.iterations,
+    });
+}
+function help() {
+    process.stdout.write(`research-runner v${PKG.version}
+
+Usage:
+  research-runner archeologist --brief "<topic>" --scope-level <platform|bar> --scope-id ID [--path research|archaeology] [...]
+  research-runner prd --research-pr <url|path> --scope-level <platform|bar> --scope-id ID [...]
+
+See README.md for the full flag surface.
+`);
+}
+async function main() {
+    const [, , subcommand, ...rest] = process.argv;
+    switch (subcommand) {
+        case 'archeologist':
+            await archeologistCmd(rest);
+            break;
+        case 'prd':
+            await prdCmd(rest);
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+        case undefined:
+            help();
+            break;
+        case '--version':
+        case '-v':
+            process.stdout.write(`${PKG.version}\n`);
+            break;
+        default: abort(`unknown subcommand: ${subcommand}`);
+    }
+}
+main().catch(err => {
+    process.stderr.write(`research-runner: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/llm/anthropic-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * anthropic-client — minimal `fetch`-based wrapper around Anthropic's
+ * `/v1/messages` endpoint. Returns the LLM telemetry shape the audit
+ * emitter wants.
+ *
+ * Why not the official SDK? Three reasons:
+ *   1. Smaller install (~300kb saved)
+ *   2. The runner needs to support multiple providers (anthropic, openai,
+ *      azure-openai) and a uniform `fetch`-based abstraction keeps the
+ *      switch deterministic and testable.
+ *   3. Dependency-injecting `fetch` makes mocking trivial in node:test.
+ */
+export type AnthropicModel = 'claude-haiku-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-7';
+export interface CallAnthropicOpts {
+    apiKey: string;
+    model: AnthropicModel;
+    /** Optional system prompt (instructions that bypass user-message framing). */
+    system?: string;
+    /** The user-message body — typically the filled prompt pack content. */
+    prompt: string;
+    /** Hard ceiling on response tokens. */
+    maxTokens: number;
+    /** Sampling temperature 0-1. Default 0 for deterministic shape. */
+    temperature?: number;
+    /** Test injection point; defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** Abort timeout (ms). Default 60s. */
+    timeoutMs?: number;
+}
+export interface CallAnthropicResult {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** USD cost estimate from public pricing (haiku ~$0.25/$1.25, sonnet ~$3/$15, opus ~$15/$75 per Mtok). */
+    costUsd: number;
+    /** Anthropic HTTP status (200 on success). */
+    httpStatus: number;
+}
+export declare function callAnthropic(opts: CallAnthropicOpts): Promise<CallAnthropicResult>;

package/dist/llm/anthropic-client.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * anthropic-client — minimal `fetch`-based wrapper around Anthropic's
+ * `/v1/messages` endpoint. Returns the LLM telemetry shape the audit
+ * emitter wants.
+ *
+ * Why not the official SDK? Three reasons:
+ *   1. Smaller install (~300kb saved)
+ *   2. The runner needs to support multiple providers (anthropic, openai,
+ *      azure-openai) and a uniform `fetch`-based abstraction keeps the
+ *      switch deterministic and testable.
+ *   3. Dependency-injecting `fetch` makes mocking trivial in node:test.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callAnthropic = callAnthropic;
+const PRICING = {
+    'claude-haiku-4-5': { inputPerMtok: 0.25, outputPerMtok: 1.25 },
+    'claude-sonnet-4-6': { inputPerMtok: 3.00, outputPerMtok: 15.00 },
+    'claude-opus-4-7': { inputPerMtok: 15.00, outputPerMtok: 75.00 },
+};
+async function callAnthropic(opts) {
+    if (!opts.apiKey) {
+        throw new Error('ANTHROPIC_API_KEY missing — set the env var or pass apiKey directly');
+    }
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 60_000);
+    let response;
+    try {
+        response = await fetchImpl('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'x-api-key': opts.apiKey,
+                'anthropic-version': '2023-06-01',
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: opts.model,
+                max_tokens: opts.maxTokens,
+                temperature: opts.temperature ?? 0,
+                ...(opts.system ? { system: opts.system } : {}),
+                messages: [{ role: 'user', content: opts.prompt }],
+            }),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const httpStatus = response.status;
+    if (!response.ok) {
+        const body = await safeText(response);
+        throw new Error(`Anthropic returned ${httpStatus}: ${body.slice(0, 400)}`);
+    }
+    const data = await response.json();
+    const text = (data.content ?? [])
+        .filter(b => b.type === 'text')
+        .map(b => b.text ?? '')
+        .join('');
+    const inputTokens = data.usage?.input_tokens ?? 0;
+    const outputTokens = data.usage?.output_tokens ?? 0;
+    const pricing = PRICING[opts.model];
+    const costUsd = (inputTokens / 1_000_000) * pricing.inputPerMtok +
+        (outputTokens / 1_000_000) * pricing.outputPerMtok;
+    return { text, inputTokens, outputTokens, costUsd, httpStatus };
+}
+async function safeText(r) {
+    try {
+        return await r.text();
+    }
+    catch {
+        return '';
+    }
+}

package/dist/llm/github-models-client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * github-models-client — fetch-based wrapper around the GitHub Models
+ * inference endpoint (`https://models.github.ai/inference/chat/completions`).
+ *
+ * The endpoint is OpenAI-compatible: standard `messages` array, `model`,
+ * `max_tokens`, `temperature`. Authentication is the workflow's GITHUB_TOKEN
+ * with `permissions: models: read` — no separate API key as a repo secret.
+ *
+ * Returns the same telemetry shape as callAnthropic so plan_queries /
+ * synthesize_report can route through either client without branching on
+ * their result types.
+ *
+ * Model names use GitHub Models namespacing — e.g. `openai/gpt-4o`,
+ * `openai/gpt-4o-mini`, `anthropic/claude-3-5-sonnet`. The router (in
+ * llm-router.ts) maps internal logical model tiers (`plan` / `synth`) to
+ * the concrete provider-specific id.
+ */
+/** Subset of GitHub Models model ids we use. Extend as new tiers land. */
+export type GitHubModelsModel = 'openai/gpt-4o' | 'openai/gpt-4o-mini' | 'anthropic/claude-3-5-sonnet' | 'anthropic/claude-3-5-haiku';
+export interface CallGitHubModelsOpts {
+    /** Workflow GITHUB_TOKEN. The model server checks the `models:read` permission scope. */
+    token: string;
+    model: GitHubModelsModel;
+    system?: string;
+    prompt: string;
+    maxTokens: number;
+    temperature?: number;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /** Override the endpoint (for Azure-routed Models or test environments). */
+    endpoint?: string;
+}
+export interface CallGitHubModelsResult {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * GitHub Models billing is opaque to the caller — pricing is org/quota
+     * driven, not per-token-published. We report 0 so the audit envelope
+     * stays well-typed; reviewers see `provider: github-models` and know to
+     * check the GitHub billing surface for the actual spend.
+     */
+    costUsd: number;
+    httpStatus: number;
+}
+export declare function callGitHubModels(opts: CallGitHubModelsOpts): Promise<CallGitHubModelsResult>;

package/dist/llm/github-models-client.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * github-models-client — fetch-based wrapper around the GitHub Models
+ * inference endpoint (`https://models.github.ai/inference/chat/completions`).
+ *
+ * The endpoint is OpenAI-compatible: standard `messages` array, `model`,
+ * `max_tokens`, `temperature`. Authentication is the workflow's GITHUB_TOKEN
+ * with `permissions: models: read` — no separate API key as a repo secret.
+ *
+ * Returns the same telemetry shape as callAnthropic so plan_queries /
+ * synthesize_report can route through either client without branching on
+ * their result types.
+ *
+ * Model names use GitHub Models namespacing — e.g. `openai/gpt-4o`,
+ * `openai/gpt-4o-mini`, `anthropic/claude-3-5-sonnet`. The router (in
+ * llm-router.ts) maps internal logical model tiers (`plan` / `synth`) to
+ * the concrete provider-specific id.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callGitHubModels = callGitHubModels;
+const DEFAULT_ENDPOINT = 'https://models.github.ai/inference/chat/completions';
+async function callGitHubModels(opts) {
+    if (!opts.token) {
+        throw new Error('GITHUB_TOKEN missing — `permissions: models: read` is required on the workflow');
+    }
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 60_000);
+    const messages = [];
+    if (opts.system) {
+        messages.push({ role: 'system', content: opts.system });
+    }
+    messages.push({ role: 'user', content: opts.prompt });
+    let response;
+    try {
+        response = await fetchImpl(endpoint, {
+            method: 'POST',
+            headers: {
+                'authorization': `Bearer ${opts.token}`,
+                'content-type': 'application/json',
+                'accept': 'application/json',
+            },
+            body: JSON.stringify({
+                model: opts.model,
+                messages,
+                max_tokens: opts.maxTokens,
+                temperature: opts.temperature ?? 0,
+            }),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const httpStatus = response.status;
+    if (!response.ok) {
+        const body = await safeText(response);
+        throw new Error(`GitHub Models returned ${httpStatus}: ${body.slice(0, 400)}`);
+    }
+    const data = await response.json();
+    const text = data.choices?.[0]?.message?.content ?? '';
+    return {
+        text,
+        inputTokens: data.usage?.prompt_tokens ?? 0,
+        outputTokens: data.usage?.completion_tokens ?? 0,
+        costUsd: 0,
+        httpStatus,
+    };
+}
+async function safeText(r) {
+    try {
+        return await r.text();
+    }
+    catch {
+        return '';
+    }
+}

package/dist/llm/llm-router.d.ts

@@ -0,0 +1,46 @@
+/**
+ * llm-router — single entry point for every LLM hop in the runner.
+ *
+ * Picks the right provider client based on the brief's `llm_provider` and
+ * the requested logical tier (`plan` for cheap structured-JSON work,
+ * `synth` for higher-quality long-form synthesis). Translates the tier
+ * into a provider-specific model name so node code never hard-codes a
+ * model id.
+ *
+ * Returns a uniform result shape so plan_queries / synthesize_report can
+ * use it without branching on provider in their own bodies.
+ */
+import type { LlmProvider } from '../schemas';
+/**
+ * Logical model tiers. Each is mapped to a concrete provider-specific id
+ * inside the router. Keeping the surface this narrow avoids the runner
+ * sprinkling model strings across nodes.
+ */
+export type LlmTier = 'plan' | 'synth';
+export interface CallLlmOpts {
+    provider: LlmProvider;
+    tier: LlmTier;
+    /**
+     * Anthropic API key (used when provider === 'anthropic'). For
+     * 'github-models', leave undefined and supply `githubToken` instead.
+     */
+    anthropicApiKey?: string;
+    /** GITHUB_TOKEN (used when provider === 'github-models'). */
+    githubToken?: string;
+    system?: string;
+    prompt: string;
+    maxTokens: number;
+    temperature?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface CallLlmResult {
+    provider: LlmProvider;
+    /** The actual model id sent to the provider (e.g. `claude-haiku-4-5` or `openai/gpt-4o-mini`). */
+    model: string;
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    httpStatus: number;
+}
+export declare function callLlm(opts: CallLlmOpts): Promise<CallLlmResult>;

package/dist/llm/llm-router.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callLlm = callLlm;
+const anthropic_client_1 = require("./anthropic-client");
+const github_models_client_1 = require("./github-models-client");
+/** Per-tier per-provider model id lookup. */
+const MODEL_BY_TIER = {
+    plan: { anthropic: 'claude-haiku-4-5', githubModels: 'openai/gpt-4o-mini' },
+    synth: { anthropic: 'claude-sonnet-4-6', githubModels: 'anthropic/claude-3-5-sonnet' },
+};
+async function callLlm(opts) {
+    const tierModels = MODEL_BY_TIER[opts.tier];
+    if (opts.provider === 'anthropic') {
+        if (!opts.anthropicApiKey) {
+            throw new Error(`callLlm: provider=anthropic requires anthropicApiKey (set ANTHROPIC_API_KEY).`);
+        }
+        const r = await (0, anthropic_client_1.callAnthropic)({
+            apiKey: opts.anthropicApiKey,
+            model: tierModels.anthropic,
+            system: opts.system,
+            prompt: opts.prompt,
+            maxTokens: opts.maxTokens,
+            temperature: opts.temperature,
+            fetchImpl: opts.fetchImpl,
+        });
+        return {
+            provider: 'anthropic',
+            model: tierModels.anthropic,
+            text: r.text,
+            inputTokens: r.inputTokens,
+            outputTokens: r.outputTokens,
+            costUsd: r.costUsd,
+            httpStatus: r.httpStatus,
+        };
+    }
+    if (opts.provider === 'github-models') {
+        if (!opts.githubToken) {
+            throw new Error(`callLlm: provider=github-models requires githubToken (set GITHUB_TOKEN; workflow needs \`permissions: models: read\`).`);
+        }
+        const r = await (0, github_models_client_1.callGitHubModels)({
+            token: opts.githubToken,
+            model: tierModels.githubModels,
+            system: opts.system,
+            prompt: opts.prompt,
+            maxTokens: opts.maxTokens,
+            temperature: opts.temperature,
+            fetchImpl: opts.fetchImpl,
+        });
+        return {
+            provider: 'github-models',
+            model: tierModels.githubModels,
+            text: r.text,
+            inputTokens: r.inputTokens,
+            outputTokens: r.outputTokens,
+            costUsd: r.costUsd,
+            httpStatus: r.httpStatus,
+        };
+    }
+    throw new Error(`callLlm: provider "${opts.provider}" not yet implemented (phase 2c.1 ships anthropic + github-models; openai + azure-openai land later).`);
+}

package/dist/mesh/get-mesh-sha.d.ts

@@ -0,0 +1 @@
+export declare function getMeshSha(meshPath: string): string | null;