@bakers-build/addon-claude 0.0.0-stage → 0.1.0-next.38

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+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

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-claude
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bakers.build agent plugin for the Claude CLI.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://git.key-tec.de/bakers-build/bakers-build (bakers-cli/).

package/dist/src/footprint.d.ts

@@ -0,0 +1,22 @@
+import { type AgentFootprint } from '@bakers-build/conductor/contract';
+/**
+ * Parse a Claude-Code JSONL transcript into an agent footprint (BB-132).
+ *
+ * This is Claude's transcript format specifically — the transcript is one JSON
+ * object per line. Assistant turns carry a `message.usage` token breakdown and
+ * `message.content` blocks (text / tool_use); genuine user prompts are user
+ * messages whose `message.content` is a plain string (tool results come back
+ * as an array and are ignored). Blank or malformed lines are skipped — never
+ * throws.
+ *
+ * `duration_s` is the run's wall-clock length: the span between the first and
+ * last entry that carries a parseable `timestamp` (BB-151). This makes the
+ * transcript the single source of the run length — no `started_at` re-read, no
+ * JSON:API timestamp round-trip to mis-parse. Fewer than two timestamps → 0.
+ *
+ * `active_s` is `duration_s` minus the time spent waiting on the human. Two
+ * gaps count as waiting: from the last assistant entry of a turn to the next
+ * genuine user prompt, and from an `AskUserQuestion`/`ExitPlanMode` tool_use
+ * to its tool_result. Only timestamped entries take part; no threshold.
+ */
+export declare function parseClaudeTranscript(jsonl: string): AgentFootprint;

package/dist/src/footprint.js

@@ -0,0 +1,152 @@
+import { emptyAgentFootprint, } from '@bakers-build/conductor/contract';
+/** Token buckets summed into the total; each defaults to 0 when absent. */
+const TOKEN_KEYS = [
+    'input_tokens',
+    'output_tokens',
+    'cache_creation_input_tokens',
+    'cache_read_input_tokens',
+];
+/** Tools whose open call means the agent is waiting on the human's answer. */
+const QUESTION_TOOLS = new Set(['AskUserQuestion', 'ExitPlanMode']);
+/** Prefix of the user entry Claude Code writes when a background agent ends. */
+const TASK_NOTIFICATION = '<task-notification>';
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function countWords(text) {
+    const trimmed = text.trim();
+    return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
+}
+/**
+ * Parse a Claude-Code JSONL transcript into an agent footprint (BB-132).
+ *
+ * This is Claude's transcript format specifically — the transcript is one JSON
+ * object per line. Assistant turns carry a `message.usage` token breakdown and
+ * `message.content` blocks (text / tool_use); genuine user prompts are user
+ * messages whose `message.content` is a plain string (tool results come back
+ * as an array and are ignored). Blank or malformed lines are skipped — never
+ * throws.
+ *
+ * `duration_s` is the run's wall-clock length: the span between the first and
+ * last entry that carries a parseable `timestamp` (BB-151). This makes the
+ * transcript the single source of the run length — no `started_at` re-read, no
+ * JSON:API timestamp round-trip to mis-parse. Fewer than two timestamps → 0.
+ *
+ * `active_s` is `duration_s` minus the time spent waiting on the human. Two
+ * gaps count as waiting: from the last assistant entry of a turn to the next
+ * genuine user prompt, and from an `AskUserQuestion`/`ExitPlanMode` tool_use
+ * to its tool_result. Only timestamped entries take part; no threshold.
+ */
+export function parseClaudeTranscript(jsonl) {
+    const footprint = emptyAgentFootprint();
+    let minTs = Number.POSITIVE_INFINITY;
+    let maxTs = Number.NEGATIVE_INFINITY;
+    let waitMs = 0;
+    let lastAssistantTs;
+    // shortcut: parallel open questions are summed, not merged, so overlapping
+    // waits count twice (clamped at 0); merge intervals if parallel asks appear.
+    const openQuestions = new Map();
+    for (const raw of jsonl.split('\n')) {
+        const line = raw.trim();
+        if (line === '') {
+            continue;
+        }
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        // Track the run span across ANY timestamped entry (user, assistant,
+        // system, …) — not just the turns we meter for tokens.
+        let ts;
+        if (typeof entry.timestamp === 'string') {
+            const parsed = Date.parse(entry.timestamp);
+            if (Number.isFinite(parsed)) {
+                ts = parsed;
+                if (ts < minTs)
+                    minTs = ts;
+                if (ts > maxTs)
+                    maxTs = ts;
+            }
+        }
+        const message = entry.message;
+        if (!message || typeof message !== 'object') {
+            continue;
+        }
+        if (ts !== undefined) {
+            waitMs += humanWait(entry.type, message.content, ts);
+        }
+        if (entry.type === 'assistant') {
+            footprint.agent_turns += 1;
+            const usage = message.usage ?? {};
+            for (const key of TOKEN_KEYS) {
+                footprint.tokens += num(usage[key]);
+            }
+            if (Array.isArray(message.content)) {
+                for (const block of message.content) {
+                    if (block &&
+                        typeof block === 'object' &&
+                        block.type === 'tool_use') {
+                        footprint.tool_calls += 1;
+                    }
+                }
+            }
+            if (typeof message.model === 'string') {
+                footprint.model = message.model;
+            }
+        }
+        else if (entry.type === 'user' && typeof message.content === 'string') {
+            footprint.user_prompts += 1;
+            footprint.user_prompt_words += countWords(message.content);
+        }
+    }
+    if (Number.isFinite(minTs) && Number.isFinite(maxTs) && maxTs > minTs) {
+        footprint.duration_s = Math.floor((maxTs - minTs) / 1000);
+        footprint.active_s = Math.max(0, Math.floor((maxTs - minTs - waitMs) / 1000));
+    }
+    return footprint;
+    /** Wait (ms) that ends at this entry; also tracks turn ends and open asks. */
+    function humanWait(type, content, ts) {
+        if (type === 'assistant') {
+            lastAssistantTs = ts;
+            for (const block of Array.isArray(content) ? content : []) {
+                const use = block;
+                if (use?.type === 'tool_use' &&
+                    typeof use.id === 'string' &&
+                    QUESTION_TOOLS.has(use.name)) {
+                    openQuestions.set(use.id, ts);
+                }
+            }
+            return 0;
+        }
+        if (type !== 'user') {
+            return 0;
+        }
+        let wait = 0;
+        if (typeof content === 'string' && content.startsWith(TASK_NOTIFICATION)) {
+            // A background agent finished: agent-side work, so it anchors the turn end.
+            lastAssistantTs = ts;
+            return 0;
+        }
+        if (typeof content === 'string') {
+            if (lastAssistantTs !== undefined) {
+                wait = Math.max(0, ts - lastAssistantTs);
+            }
+            lastAssistantTs = undefined;
+            return wait;
+        }
+        for (const block of Array.isArray(content) ? content : []) {
+            const id = block?.tool_use_id;
+            const start = typeof id === 'string' ? openQuestions.get(id) : undefined;
+            if (start !== undefined) {
+                wait += Math.max(0, ts - start);
+                openQuestions.delete(id);
+                // The answer ends this wait; a prompt typed right after must not recount it.
+                lastAssistantTs = undefined;
+            }
+        }
+        return wait;
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,44 @@
+import { type AgentFootprint, type AgentPlugin, type AgentRunIdentity, type BbAgent } from '@bakers-build/conductor/contract';
+export { parseClaudeTranscript } from './footprint.js';
+/**
+ * Encode an absolute cwd the way Claude Code names its per-project transcript
+ * directory under `~/.claude/projects/`: every non-alphanumeric char → `-`.
+ */
+export declare function encodeClaudeProjectDir(cwd: string): string;
+export interface ClaudeAgentOptions {
+    model?: string;
+    effort?: string;
+    args?: string[];
+    skip_permissions?: boolean;
+    /**
+     * When true, the launch runs through `measure/claude-measure.mjs`, which
+     * starts the logging proxy for the lifetime of this Claude process and
+     * applies the state-group settings shipped with the addon.
+     */
+    measure?: boolean;
+}
+export declare class ClaudeAgent implements BbAgent {
+    private readonly home;
+    readonly id = "claude";
+    private readonly args;
+    private readonly model;
+    private readonly effort;
+    private readonly skipPermissions;
+    private readonly measure;
+    private readonly overrides;
+    constructor(options?: ClaudeAgentOptions, home?: string);
+    launchCommand(prompt: string, run?: AgentRunIdentity): string;
+    /**
+     * `claude --session-id <uuid>` refuses to start when that session already
+     * exists (BB-473 review round 2), so the conductor checks this before
+     * pinning the run's own UUID — a re-dispatch of the same run would
+     * otherwise mint the very id its first attempt already wrote and fail to
+     * launch at all, silently (`claude` exits 0 on that error).
+     */
+    sessionExists(worktreePath: string, sessionId: string): Promise<boolean>;
+    getRunLog(worktreePath: string, run?: AgentRunIdentity): Promise<string>;
+    parseFootprint(log: string): AgentFootprint;
+}
+/** Config-facing factory: `claudeAgent({ model: 'claude-opus-4-8' })`. */
+export declare function claudeAgent(options?: ClaudeAgentOptions): AgentPlugin;
+export default claudeAgent;

package/dist/src/index.js

@@ -0,0 +1,217 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveAgentCliOptions, validateOptionalBoolean, } from '@bakers-build/conductor/contract';
+import { shellQuote } from '@bakers-build/core';
+import { parseClaudeTranscript } from './footprint.js';
+export { parseClaudeTranscript } from './footprint.js';
+/** src/index.ts and dist/src/index.js both sit two levels below the package root. */
+const MEASURE_WRAPPER = fileURLToPath(new URL(import.meta.url.includes('/dist/')
+    ? '../../measure/claude-measure.mjs'
+    : '../measure/claude-measure.mjs', import.meta.url));
+const MEASURE_FLAGS = [
+    '--setting-sources',
+    'project,local',
+    '--settings',
+    '.bakers/claude-measure.settings.json',
+    '--strict-mcp-config',
+    '--mcp-config',
+    '{"mcpServers":{}}',
+];
+/**
+ * Encode an absolute cwd the way Claude Code names its per-project transcript
+ * directory under `~/.claude/projects/`: every non-alphanumeric char → `-`.
+ */
+export function encodeClaudeProjectDir(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+const CLAUDE_RESERVED = [
+    '--session-id',
+    '--dangerously-skip-permissions',
+    '--allow-dangerously-skip-permissions',
+    '--permission-mode',
+];
+const CLAUDE_KNOWN = [
+    { kind: 'model', flags: ['--model'] },
+    { kind: 'effort', flags: ['--effort'] },
+];
+export class ClaudeAgent {
+    home;
+    id = 'claude';
+    args;
+    model;
+    effort;
+    skipPermissions;
+    measure;
+    overrides;
+    constructor(options = {}, home = homedir()) {
+        this.home = home;
+        const cli = resolveAgentCliOptions(options, CLAUDE_RESERVED, CLAUDE_KNOWN);
+        this.args = cli.args;
+        this.model = cli.model;
+        this.effort = cli.effort;
+        this.overrides = cli.overrides;
+        this.skipPermissions =
+            validateOptionalBoolean(options.skip_permissions, 'skip_permissions') ??
+                true;
+        this.measure = validateOptionalBoolean(options.measure, 'measure') ?? false;
+    }
+    launchCommand(prompt, run) {
+        if (prompt === '') {
+            return 'claude';
+        }
+        const parts = this.measure
+            ? ['node', shellQuote(MEASURE_WRAPPER), 'claude', shellQuote(prompt)]
+            : ['claude', shellQuote(prompt)];
+        if (this.model !== undefined && !this.overrides.model) {
+            parts.push('--model', shellQuote(this.model));
+        }
+        if (this.effort !== undefined && !this.overrides.effort) {
+            parts.push('--effort', shellQuote(this.effort));
+        }
+        if (this.skipPermissions) {
+            parts.push('--dangerously-skip-permissions');
+        }
+        // Pin the transcript's own session id to the run's UUID (BB-473), so
+        // `getRunLog` can read that ONE file directly instead of scanning the
+        // worktree-keyed directory by mtime — the scan is what let a
+        // resumed/re-dispatched/reused worktree finalise a foreign transcript.
+        if (run?.sessionId) {
+            parts.push('--session-id', run.sessionId);
+        }
+        parts.push(...this.args.map(shellQuote));
+        if (this.measure) {
+            parts.push(...MEASURE_FLAGS.map(shellQuote));
+        }
+        return parts.join(' ');
+    }
+    /**
+     * `claude --session-id <uuid>` refuses to start when that session already
+     * exists (BB-473 review round 2), so the conductor checks this before
+     * pinning the run's own UUID — a re-dispatch of the same run would
+     * otherwise mint the very id its first attempt already wrote and fail to
+     * launch at all, silently (`claude` exits 0 on that error).
+     */
+    async sessionExists(worktreePath, sessionId) {
+        const dir = join(this.home, '.claude', 'projects', encodeClaudeProjectDir(worktreePath));
+        try {
+            await stat(join(dir, `${sessionId}.jsonl`));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async getRunLog(worktreePath, run) {
+        const dir = join(this.home, '.claude', 'projects', encodeClaudeProjectDir(worktreePath));
+        const startedAtMs = run?.startedAt !== undefined ? new Date(run.startedAt).getTime() : null;
+        // BB-473: when the run's own session id is known (pinned at launch via
+        // `--session-id`), read that file directly — no directory scan, so a
+        // foreign transcript (resumed run, re-dispatch, reused worktree) can
+        // never be selected. AC-5: when the pinned file is missing (a run
+        // dispatched before this change, or the agent never wrote it), fall
+        // through to the scan below — bounded by `run.startedAt` where known —
+        // instead of returning '' and turning a wrong log into no log at all.
+        //
+        // Round 4 (review round 3, Critical 1): the pinned file can also be
+        // *stale* rather than missing — a re-dispatch omits `--session-id` (see
+        // `sessionExists`) precisely because attempt 1's file already owns this
+        // name, so a direct read here would silently keep returning attempt 1's
+        // transcript forever. `startedAt` is re-stamped by the conductor on
+        // every dispatch (`markRunning`), so a pinned file older than this
+        // attempt's own start can only be a leftover from a prior attempt —
+        // reject it and fall through to the scan, which is bounded by the same
+        // timestamp and will find the fresh, unpinned file this attempt wrote.
+        // BB-473 review round 4 (Critical 2): when the run's deterministic
+        // attempt family is known, select the HIGHEST-numbered attempt whose
+        // file actually exists — an IDENTITY, not the `startedAt` window below,
+        // which a sibling session newer than the bound could still beat. Each
+        // family member names a distinct attempt, so no staleness check is
+        // needed: whichever member exists IS that attempt's own transcript.
+        if (run?.attemptFamily?.length) {
+            for (let i = run.attemptFamily.length - 1; i >= 0; i--) {
+                try {
+                    return await readFile(join(dir, `${run.attemptFamily[i]}.jsonl`), 'utf8');
+                }
+                catch {
+                    // try the next, lower-numbered attempt.
+                }
+            }
+            // AC-5: none of the family's files exist yet — a run dispatched before
+            // this change, or the agent never wrote its pinned file — so fall
+            // through to the scan below instead of returning ''.
+        }
+        else if (run?.sessionId) {
+            try {
+                const path = join(dir, `${run.sessionId}.jsonl`);
+                const isStale = startedAtMs !== null &&
+                    Number.isFinite(startedAtMs) &&
+                    (await stat(path)).mtimeMs < startedAtMs;
+                if (!isStale) {
+                    return await readFile(path, 'utf8');
+                }
+            }
+            catch {
+                // fall through to the scan.
+            }
+        }
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            return '';
+        }
+        let latest = null;
+        for (const name of entries) {
+            if (!name.endsWith('.jsonl')) {
+                continue;
+            }
+            const full = join(dir, name);
+            try {
+                const s = await stat(full);
+                if (startedAtMs !== null &&
+                    Number.isFinite(startedAtMs) &&
+                    s.mtimeMs < startedAtMs) {
+                    continue;
+                }
+                if (!latest || s.mtimeMs > latest.mtimeMs) {
+                    latest = { path: full, mtimeMs: s.mtimeMs };
+                }
+            }
+            catch {
+                // entry vanished between readdir and stat — skip.
+            }
+        }
+        if (!latest) {
+            return '';
+        }
+        try {
+            return await readFile(latest.path, 'utf8');
+        }
+        catch {
+            return '';
+        }
+    }
+    parseFootprint(log) {
+        return parseClaudeTranscript(log);
+    }
+}
+/** Config-facing factory: `claudeAgent({ model: 'claude-opus-4-8' })`. */
+export function claudeAgent(options = {}) {
+    const agent = new ClaudeAgent(options);
+    return {
+        kind: 'agent',
+        id: 'claude',
+        requiredModules: [],
+        async createAgent() {
+            return agent;
+        },
+    };
+}
+// Default export: this module also exports the `ClaudeAgent` class, so the
+// config resolver's auto-pick (no `export:`) sees 2 function exports and
+// would otherwise throw "specify export" — see conductor/src/config.ts
+// `loadNamedPlugin`. The default export makes the factory win.
+export default claudeAgent;

package/dist/src/preset.d.ts

@@ -0,0 +1,4 @@
+import type { Preset } from '@bakers-build/conductor/contract';
+import { type ClaudeAgentOptions } from './index.js';
+export declare const agents: Preset<ClaudeAgentOptions | undefined>['agents'];
+export declare const scopes: Preset['scopes'];

package/dist/src/preset.js

@@ -0,0 +1,33 @@
+import claudeAgent from './index.js';
+export const agents = (acc, opts) => {
+    if (opts?.model) {
+        return [
+            ...acc,
+            {
+                agent: claudeAgent(opts),
+                model: opts.model,
+                description: 'Custom Claude variant; suitability depends on the configured model.',
+            },
+        ];
+    }
+    return [
+        ...acc,
+        {
+            alias: 'opus',
+            description: 'Strong reasoning for ambiguous design, diagnosis and demanding implementation.',
+            model: 'opus',
+        },
+        {
+            alias: 'sonnet',
+            description: 'Efficient implementation of well-specified changes and routine maintenance.',
+            model: 'sonnet',
+        },
+    ].map((candidate) => 'agent' in candidate
+        ? candidate
+        : {
+            ...candidate,
+            agent: claudeAgent({ ...opts, model: candidate.model }),
+        });
+};
+// Agents are per machine: list this addon in ~/.bakers/machine.config.js addons[].
+export const scopes = ['machine'];