co-maintainer 0.5.0 → 0.5.1-beta.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Murat Kirazkaya
-
-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.
+MIT License
+
+Copyright (c) 2026 Murat Kirazkaya
+
+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

@@ -3,7 +3,7 @@
 [![NPM Version](https://img.shields.io/npm/v/co-maintainer)](https://www.npmjs.com/package/co-maintainer) [![](https://img.shields.io/badge/blog-co_maintainer_an_imitator_of_yours-blue)](https://muratkirazkaya.com/blogs/co-maintainer-an-imitator-of-yours)
 
 [Website](https://co-maintainer.com) ·
-[Docs](https://co-maintainer.com/docs) ·
+[Docs](https://co-maintainer.com/docs/getting-started.html) ·
 [Cloud](https://cloud.co-maintainer.com) (hosted, free, early access, invite only for now)
 
 An imitator of yours, A PR review tool like co-maintainer.
@@ -37,19 +37,21 @@ co-maintainer review owner/repo 123 --improve-matrix=2 --debug
 
 co-maintainer review              # local branch (staged, unstaged, untracked)
 co-maintainer review --json       # machine-readable stdout, logs on stderr
+co-maintainer review --output=github  # annotations and a job summary inside GitHub Actions
 ```
 
 Settings live in `config.json`, so a flag you use every time can be saved once:
 
 ```sh
-co-maintainer config set ai-key sk-or-...        # OpenRouter key
+co-maintainer config set ai openrouter             # or openai, anthropic, opencode-zen, opencode-go
+co-maintainer config set ai-key sk-or-...        # your provider's key (OpenRouter, OpenAI, Anthropic or OpenCode)
 co-maintainer config set high-model openai/gpt-5.6-luna
 co-maintainer config set low-model openai/gpt-oss-120b
 co-maintainer config list                        # every key, its value and its source
 ```
 
 Documentation: [Getting started](https://co-maintainer.com/docs/getting-started.html)
-(install to first review) and the [full docs site](https://co-maintainer.com/docs),
+(install to first review) and the [full docs site](https://co-maintainer.com/docs/getting-started.html),
 sources in [`docs/md/`](docs/md/).
 
 Use `co-maintainer help`, `co-maintainer -h`, or `co-maintainer --help` for the

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "co-maintainer",
-    "version": "0.5.0",
+    "version": "0.5.1-beta.2",
     "description": "An imitator of yours, A PR review tool like co-maintainer.",
     "keywords": [
         "ai",

package/dist/src/ai/anthropic.d.ts

@@ -0,0 +1,55 @@
+/** Anthropic via the Messages API.
+ *
+ * The raw fetch shape every other provider uses, against Anthropic's own
+ * contract (docs.anthropic.com/en/api/messages). The request/response shapes
+ * differ from the Chat-Completions style this codebase's `AiRequest`/
+ * `AiMessage` types follow the way OpenAI's Responses API does, so this file is
+ * the one place that translates:
+ *
+ *  - the system message becomes the top-level `system` field, not a message
+ *  - an assistant tool call is a `tool_use` content block, not a `tool_calls`
+ *    field on the message
+ *  - tool results are `tool_result` blocks inside a `user` message, referenced
+ *    by `tool_use_id`
+ *  - a function tool is `{name, description, input_schema}`, not the
+ *    Chat-Completions `{type:"function", function:{...}}` nesting
+ *  - structured output is `output_config.format`, reasoning effort is
+ *    `output_config.effort`, and there is no `temperature`: Claude Opus 5 and
+ *    Sonnet 5 reject sampling parameters with a 400
+ *
+ * `cache_control` is set on the system prompt, which every review sends as the
+ * same guide prefix. Anthropic caches the longest stable prefix, so the
+ * guides are billed at the cached rate from the second review on and the
+ * `cache_read_input_tokens` count shows up in the usage log.
+ *
+ * ponytail: this talks to Messages without streaming. The original design
+ * called for the SDK's `stream()` + `finalMessage()` helper for large `max_tokens` (a single
+ * review can ask for 96k). The SDK is not a dependency (kept fetch-only, the
+ * same as every other provider), and a hand-rolled SSE accumulation loop is a
+ * lot of code for a first cut. Anthropic's HTTP request timeout is the risk;
+ * if a real review ever hits it, add the streaming loop here. Upgrade path:
+ * `stream:true` + parse `content_block_delta` events into the same
+ * `parseMessagesBody` result shape.
+ */
+import type { AiProvider, AiRequest, AiResponse, Json } from "../types.ts";
+import { CliError } from "../cli/error.ts";
+/** Required on every Messages request and the only version the errors below
+ * are written against. */
+export declare const ANTHROPIC_VERSION = "2023-06-01";
+/** `CM_ANTHROPIC_URL` points at a local fake in tests. Unset means the real
+ * endpoint, so production behavior is unchanged. */
+export declare function anthropicBase(): string;
+/** A failed response as actionable text. Only the error's own
+ * `message` is surfaced: the raw body can carry request ids that mean nothing
+ * in a terminal. */
+export declare function anthropicError(model: string, status: number, body: string): CliError;
+export declare function parseMessagesBody(json: Json, model: string): AiResponse;
+export declare class AnthropicProvider implements AiProvider {
+    readonly supportsTools = true;
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    constructor(apiKey: string, model: string);
+    private post;
+    complete(request: AiRequest): Promise<AiResponse>;
+}

package/dist/src/ai/anthropic.js

@@ -0,0 +1,262 @@
+import { getEnv } from "../util/runtime.js";
+import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, } from "../cli/error.js";
+/** Required on every Messages request and the only version the errors below
+ * are written against. */
+export const ANTHROPIC_VERSION = "2023-06-01";
+/** `CM_ANTHROPIC_URL` points at a local fake in tests. Unset means the real
+ * endpoint, so production behavior is unchanged. */
+export function anthropicBase() {
+    const endpoint = getEnv("CM_ANTHROPIC_URL") ?? "https://api.anthropic.com/v1";
+    return endpoint.replace(/\/$/, "");
+}
+/** A failed response as actionable text. Only the error's own
+ * `message` is surfaced: the raw body can carry request ids that mean nothing
+ * in a terminal. */
+export function anthropicError(model, status, body) {
+    let detail = "";
+    let type = "";
+    try {
+        const parsed = JSON.parse(body);
+        detail = String(parsed.error?.message ?? "");
+        type = String(parsed.error?.type ?? "");
+    }
+    catch {
+        detail = body.trim().slice(0, 200);
+    }
+    if (status === 401 || status === 403) {
+        return new CliError("anthropic_unauthorized", "Anthropic rejected the API key.", "Set a new one with co-maintainer set --token=...", EXIT_USAGE);
+    }
+    if ((status === 400 || status === 404) &&
+        (type === "not_found_error" || /model/i.test(detail))) {
+        return new CliError("anthropic_unknown_model", `Anthropic does not know the model ${model}.`, "Pick one at https://docs.anthropic.com/en/docs/about-claude/models and set it with co-maintainer set --high-model=...", EXIT_USAGE);
+    }
+    return new CliError("anthropic_failed", `Anthropic failed with ${status}${detail ? `: ${detail}` : "."}`, undefined, EXIT_RUNTIME);
+}
+/** The Chat-Completions-shaped message list every caller already builds
+ * (`chatBody` does the same fallback for OpenRouter). */
+function effectiveMessages(request) {
+    return (request.messages ?? [
+        ...(request.system
+            ? [{ role: "system", content: request.system }]
+            : []),
+        { role: "user", content: request.prompt },
+    ]);
+}
+/** `{type:"function",function:{name,parameters}}` (what `mermaid.ts` and the
+ * codegraph tools build) to Anthropic's `input_schema` shape. */
+function toAnthropicTool(tool) {
+    const fn = (tool.function ?? {});
+    return {
+        name: String(fn.name ?? ""),
+        description: fn.description ? String(fn.description) : undefined,
+        input_schema: fn.parameters ?? { type: "object" },
+    };
+}
+/** A tool call and its result do not live inside a message the way Chat
+ * Completions nests them. Anthropic delivers `tool_use` blocks in the
+ * assistant turn, and the caller must send every result back in a single
+ * `user` message with one `tool_result` block each, in the same order. */
+function toAnthropicMessages(messages) {
+    const system = [];
+    const out = [];
+    // Consecutive `tool` messages collapse into one `user` turn: Anthropic
+    // rejects two user messages in a row.
+    let pendingResults = [];
+    const flushResults = () => {
+        if (!pendingResults.length)
+            return;
+        out.push({ role: "user", content: pendingResults });
+        pendingResults = [];
+    };
+    for (const message of messages) {
+        if (message.role === "system") {
+            system.push(String(message.content ?? ""));
+            continue;
+        }
+        if (message.role === "tool") {
+            pendingResults.push({
+                type: "tool_result",
+                tool_use_id: message.tool_call_id ?? "",
+                content: message.content ?? "",
+            });
+            continue;
+        }
+        flushResults();
+        if (message.tool_calls?.length) {
+            const content = [];
+            if (message.content)
+                content.push({ type: "text", text: message.content });
+            for (const call of message.tool_calls) {
+                let input = {};
+                try {
+                    input = JSON.parse(call.function.arguments);
+                }
+                catch {
+                    input = {};
+                }
+                content.push({
+                    type: "tool_use",
+                    id: call.id,
+                    name: call.function.name,
+                    input,
+                });
+            }
+            out.push({ role: "assistant", content });
+            continue;
+        }
+        out.push({ role: message.role, content: message.content ?? "" });
+    }
+    flushResults();
+    return {
+        system: system.length ? system.join("\n\n") : undefined,
+        messages: out,
+    };
+}
+/** Haiku 4.5 does not support `output_config.effort`; sending it is a 400.
+ * Anthropic's effort accepts low/medium/high/xhigh/max, so the only level this
+ * has to drop is "none": it means "reasoning off" in `AiRequest` and is not an
+ * effort value Anthropic lists. */
+function supportsEffort(model) {
+    return !/haiku/i.test(model);
+}
+function messagesBody(model, request) {
+    const { system, messages } = toAnthropicMessages(effectiveMessages(request));
+    const schema = request.responseFormat?.json_schema;
+    const effort = request.reasoningEffort && request.reasoningEffort !== "none"
+        ? request.reasoningEffort
+        : undefined;
+    // `output_config` carries both the structured-output schema and the effort
+    // level. It is only sent when one of them applies, so a plain request stays
+    // on the request shape every model understands.
+    const outputConfig = {
+        ...(schema?.schema
+            ? { format: { type: "json_schema", schema: schema.schema } }
+            : {}),
+        ...(effort && supportsEffort(model) ? { effort } : {}),
+    };
+    return {
+        model,
+        max_tokens: request.maxTokens,
+        // `cache_control` marks the guide prefix every review repeats, so it is
+        // read from cache instead of re-billed.
+        ...(system
+            ? {
+                system: [
+                    {
+                        type: "text",
+                        text: system,
+                        cache_control: { type: "ephemeral" },
+                    },
+                ],
+            }
+            : {}),
+        messages,
+        ...(request.tools?.length
+            ? {
+                tools: request.tools.map(toAnthropicTool),
+                tool_choice: { type: "auto" },
+            }
+            : {}),
+        ...(Object.keys(outputConfig).length
+            ? { output_config: outputConfig }
+            : {}),
+    };
+}
+/** `refusal` stop reason with the human-readable explanation when Anthropic
+ * supplies one. Kept here so both the non-streaming body and any future
+ * streaming loop share one message. */
+function refusalError(details) {
+    const explanation = details && typeof details.explanation === "string"
+        ? details.explanation
+        : "no reason given";
+    return new CliError("anthropic_refusal", `Anthropic refused to answer: ${explanation}`, undefined, EXIT_RUNTIME);
+}
+export function parseMessagesBody(json, model) {
+    const stopReason = String(json.stop_reason ?? "");
+    if (stopReason === "refusal") {
+        throw refusalError(json.stop_details);
+    }
+    const content = Array.isArray(json.content)
+        ? json.content
+        : [];
+    const texts = [];
+    const toolCalls = [];
+    for (const block of content) {
+        if (block.type === "text" && block.text) {
+            texts.push(block.text);
+            continue;
+        }
+        if (block.type === "tool_use" && block.id && block.name) {
+            toolCalls.push({
+                id: block.id,
+                type: "function",
+                function: {
+                    name: block.name,
+                    arguments: JSON.stringify(block.input ?? {}),
+                },
+            });
+        }
+    }
+    const usage = json.usage;
+    return {
+        text: texts.join(""),
+        ...(toolCalls.length ? { toolCalls } : {}),
+        tokensIn: Number(usage?.input_tokens ?? 0),
+        tokensOut: Number(usage?.output_tokens ?? 0),
+        // Anthropic reports only token counts, never a dollar cost, so this is
+        // always unknown (`costReasonText`'s "provider_did_not_report").
+        cost: undefined,
+        model,
+        provider: "anthropic",
+    };
+}
+export class AnthropicProvider {
+    supportsTools = true;
+    endpoint = `${anthropicBase()}/messages`;
+    apiKey;
+    model;
+    constructor(apiKey, model) {
+        if (!apiKey)
+            throw new Error("Anthropic requires an API key");
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async post(body) {
+        try {
+            return await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "x-api-key": this.apiKey,
+                    "anthropic-version": ANTHROPIC_VERSION,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            throw networkFailure(this.endpoint, error);
+        }
+    }
+    async complete(request) {
+        let response = await this.post(messagesBody(this.model, request));
+        // A model may reject `output_config.format` next to tools. The schema is
+        // only a hint (the prompt also asks for a fenced JSON block), so one retry
+        // without it beats failing the review outright.
+        if (response.status === 400 && request.responseFormat) {
+            const detail = await response.text();
+            if (/output_config|json_schema|structured/i.test(detail)) {
+                const { responseFormat: _dropped, ...withoutSchema } = request;
+                response = await this.post(messagesBody(this.model, withoutSchema));
+                if (response.ok) {
+                    return parseMessagesBody((await response.json()), this.model);
+                }
+                throw anthropicError(this.model, response.status, await response.text());
+            }
+            throw anthropicError(this.model, response.status, detail);
+        }
+        if (!response.ok) {
+            throw anthropicError(this.model, response.status, await response.text());
+        }
+        return parseMessagesBody((await response.json()), this.model);
+    }
+}

package/dist/src/ai/batch.d.ts

@@ -3,7 +3,7 @@ type UsageSink = (job: string, response: AiResponse) => Promise<void>;
 /** Returns `null` when a response is usable, or a short reason when it is not.
  * `synthesis.ts` supplies one that parses the model text, because a syntactically
  * fine HTTP response can still be unparseable output, and caching that is what
- * poisoned every later `sync` (CORE-30 / F04). */
+ * poisoned every later `sync`. */
 export type AiValidator = (request: AiRequest, response: AiResponse) => string | null;
 /** A unit whose output never parsed, kept so the run can say what it dropped. */
 export type SkippedUnit = {
@@ -28,7 +28,7 @@ export declare class AiBatch {
     /** Runs one unit, caching its response only when the validator accepts it.
      * A rejected response is retried once; a second rejection is recorded as
      * skipped and never cached, so the next `sync` retries it rather than
-     * replaying the same unusable output (CORE-30 / F04). */
+     * replaying the same unusable output. */
     private completeUnit;
     /** Records a unit as skipped: no cache write, so it stays retried and its
      * absence is never mistaken for a deliberate empty result. */

package/dist/src/ai/batch.js

@@ -91,7 +91,7 @@ export class AiBatch {
     /** Runs one unit, caching its response only when the validator accepts it.
      * A rejected response is retried once; a second rejection is recorded as
      * skipped and never cached, so the next `sync` retries it rather than
-     * replaying the same unusable output (CORE-30 / F04). */
+     * replaying the same unusable output. */
     async completeUnit(item, results, usage, startedAt) {
         for (const attempt of [1, 2]) {
             try {

package/dist/src/ai/estimate.d.ts

@@ -28,6 +28,10 @@ export type Estimate = {
     usd?: [number, number];
     basis: "history" | "calibration";
 };
+/** The probe's cost line: a dollar range when one is known, otherwise why
+ * not, so a provider with no price list (OpenAI, Anthropic) gets its own
+ * reason instead of being told to switch to OpenRouter. */
+export declare function estimateCostLine(estimate: Estimate, ai: string, openRouterPricesUnavailable: boolean): string;
 /** The number of `extract_unit` jobs the recommended init would queue: one per
  * pull request plus one for the codebase/documents, matching
  * `extractAiFacts`. */

package/dist/src/ai/estimate.js

@@ -1,4 +1,4 @@
-/** Cost and time estimate for the recommended `init` (CORE-24, F17).
+/** Cost and time estimate for the recommended `init`.
  *
  * Three sources, in order of trust:
  *
@@ -11,7 +11,7 @@
  * 3. Time and per-job tokens come from this repository's recorded jobs when
  *    there are enough, and from the calibration below otherwise.
  *
- * Calibration (plan §CORE-24): cm-dx-lab, 4 pull requests and 8 files, 5
+ * Calibration: cm-dx-lab, 4 pull requests and 8 files, 5
  * extract and 9 synth jobs, 151 s, $0.0014 — about 151/14 ≈ 10.8 s per job.
  * Token counts per job are near 2.4k in and 0.7k out. The text always says
  * the numbers are an estimate. */
@@ -67,6 +67,21 @@ export async function readJobHistory(repo) {
 function band(value) {
     return [value * (1 - SPREAD), value * (1 + SPREAD)];
 }
+/** The probe's cost line: a dollar range when one is known, otherwise why
+ * not, so a provider with no price list (OpenAI, Anthropic) gets its own
+ * reason instead of being told to switch to OpenRouter. */
+export function estimateCostLine(estimate, ai, openRouterPricesUnavailable) {
+    if (estimate.usd) {
+        return `$${estimate.usd[0].toFixed(4)}-$${estimate.usd[1].toFixed(4)}`;
+    }
+    if (ai !== "none" && ai !== "openrouter") {
+        return "estimate unavailable for this provider";
+    }
+    if (openRouterPricesUnavailable) {
+        return "unknown (could not read OpenRouter prices)";
+    }
+    return "set --ai=openrouter with both models to estimate dollars";
+}
 /** The number of `extract_unit` jobs the recommended init would queue: one per
  * pull request plus one for the codebase/documents, matching
  * `extractAiFacts`. */

package/dist/src/ai/mermaid_loop.js

@@ -40,18 +40,21 @@ export async function completeWithMermaidTools(provider, request, maxTools, extr
         tokensOut: 0,
         cost: undefined,
     };
-    let costKnown = true;
+    const calls = { known: 0, unknown: 0 };
     const merge = (response) => {
         totals.tokensIn += response.tokensIn;
         totals.tokensOut += response.tokensOut;
         if (response.cost === undefined)
-            costKnown = false;
-        else if (costKnown)
+            calls.unknown++;
+        else {
+            calls.known++;
             totals.cost = (totals.cost ?? 0) + response.cost;
+        }
         return {
             ...response,
             ...totals,
-            cost: costKnown ? totals.cost : undefined,
+            cost: calls.unknown === 0 ? totals.cost : undefined,
+            costCalls: { ...calls },
         };
     };
     for (let round = 0; round < maxToolRounds; round++) {

package/dist/src/ai/openai.d.ts

@@ -0,0 +1,45 @@
+/** OpenAI via the Responses API.
+ *
+ * Chosen over Chat Completions on OpenAI's own advice: "Reasoning models work
+ * better with the Responses API" (platform.openai.com/docs/guides/reasoning).
+ * Responses has a different shape from the Chat-Completions style the rest of
+ * this codebase's `AiRequest`/`AiMessage` types follow (OpenRouter speaks Chat
+ * Completions directly), so this file is the one place that translates:
+ *
+ *  - the system message becomes the top-level `instructions` field
+ *  - a tool call is its own `function_call` item, not a field on a message
+ *  - a tool's result is a `function_call_output` item, referenced by `call_id`
+ *  - a function tool is `{type:"function", name, parameters}`, not nested
+ *    under a `function` key
+ *  - usage is `input_tokens`/`output_tokens`, not `prompt_tokens`/
+ *    `completion_tokens`, and carries no dollar cost at all
+ *
+ * ponytail: a tool round replays only the function call and its result, not
+ * the `reasoning` items a reasoning model's own turn produced alongside them.
+ * OpenAI's function-calling guide says those "must also be passed back with
+ * tool call outputs" for a reasoning model, so a multi-round tool loop with
+ * one (`gpt-6-astra` and similar) may reason less well on later rounds than
+ * it could, or in the worst case have a round rejected for missing context.
+ * The full fix is `previous_response_id`, which needs a response id to
+ * survive between calls, and `AiProvider.complete` is stateless for every
+ * provider. Upgrade path: thread a response id through `AiResponse` if this
+ * turns out to matter in practice; codegraph's own tool loop caps rounds low
+ * (mermaid_loop.ts's `maxToolRounds`), which limits how much is at stake.
+ */
+import type { AiProvider, AiRequest, AiResponse } from "../types.ts";
+import { CliError } from "../cli/error.ts";
+/** `CM_OPENAI_URL` points at a local fake in tests. Unset means the real
+ * endpoint, so production behavior is unchanged. */
+export declare function openAiBase(): string;
+/** A failed response as actionable text. Only `error.message` is
+ * shown: the raw body can carry request ids that mean nothing in a terminal. */
+export declare function openAiError(model: string, status: number, body: string): CliError;
+export declare class OpenAiProvider implements AiProvider {
+    readonly supportsTools = true;
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    constructor(apiKey: string, model: string);
+    private post;
+    complete(request: AiRequest): Promise<AiResponse>;
+}