@buildaharness/aielia 0.3.0

package/dist/claude-cli-llm-client.d.ts

@@ -0,0 +1,139 @@
+import { ILLMClient, ChatMessage, ChatOptions, ToolDefinition, LLMStructuredResponse } from '@buildaharness/runtime';
+export interface ClaudeCliLLMClientOptions {
+    /** Path to the claude binary. Defaults to CLAUDE_PATH env var, then 'claude' on PATH. */
+    claudePath?: string;
+    /**
+     * When set, callChatStructured wires in the file-tools MCP server (read_file/
+     * list_directory/write_file, scoped to workspaceRoot) via --mcp-config instead
+     * of throwing when tools are supplied. Absent by default — an ordinary chat
+     * turn through this backend stays fully tool-free, exactly as before.
+     */
+    fileTools?: {
+        workspaceRoot: string;
+    };
+    /**
+     * When set (and fileTools is also set — the MCP server only starts at all
+     * when fileTools is configured), also registers create_reminder/list_reminders
+     * on the same MCP server, backed by this file. Must point at the exact file a
+     * `FileSystemAdapter` (namespace "reminders") would use for the key
+     * "reminders" — see file-tools-mcp-server.mjs's doc comment — so this
+     * subprocess and the parent process's own ReminderStore share one reminder
+     * list instead of drifting into two disconnected ones. Absent by default —
+     * those two tools stay unregistered, same as before this option existed.
+     * fetch_url needs no such option: it's registered unconditionally whenever
+     * fileTools is set, since it has no shared-state dependency to configure.
+     */
+    remindersFile?: string;
+    /**
+     * When set, also registers run_shell_command on the same MCP server (started
+     * whenever fileTools or shellTools is configured) — gated behind an env var
+     * the same way reminders are gated behind `remindersFile`. Bash itself is
+     * never added to --tools regardless of this setting — see the class doc
+     * comment. Kept as a separate option from fileTools so a caller can enable
+     * shell without file access or vice versa, even though `workspaceRoot` is
+     * typically the same value for both on this backend.
+     */
+    shellTools?: {
+        workspaceRoot: string;
+    };
+    /**
+     * When set, also registers `web_search` on the same MCP server (started
+     * whenever fileTools, shellTools, or webTools is configured), backed by the
+     * Brave Search API (the only backend — see web-search-provider.ts). Gated
+     * behind the `BRAVE_SEARCH_API_KEY` env var passed to the server, the same
+     * way shell is gated behind `ENABLE_SHELL_TOOLS`. `fetch_url` is registered
+     * independently whenever the server runs at all — this option only adds the
+     * search half.
+     */
+    webTools?: {
+        braveApiKey?: string;
+    };
+    /**
+     * When set, also registers send_email on the same MCP server (started whenever any of
+     * fileTools/shellTools/webTools/actionTools is configured), gated behind an env var the same
+     * way run_shell_command is. The MCP server only ever *stages* the message — the parent process
+     * delivers it, after approval, through its own configured SendEmail transport (email.ts /
+     * email-smtp.ts). Kept separate from fileTools so email can be enabled without file access.
+     */
+    actionTools?: {
+        workspaceRoot: string;
+    };
+    /**
+     * Default model passed as `--model` to every `claude -p` call when the per-call
+     * `ChatOptions.model` doesn't already set one. The benchmark (Plan A1) uses this to pin every
+     * audit run to a stated model instead of silently inheriting the CLI default. `undefined` keeps
+     * the pre-A1 behaviour (no `--model` flag → CLI default).
+     */
+    model?: string;
+}
+/**
+ * ILLMClient backed by a local `claude -p` subprocess instead of a hosted API key —
+ * runs PersonalAssistant against an already-authenticated Claude Code CLI session.
+ * Always passes --system-prompt (so the CLI's own default prompt/CLAUDE.md/skills
+ * never leak into an ordinary chat turn) and --tools "" (PersonalAssistant only
+ * ever calls callChatSync — there's nothing here that expects tool use). **Bash is
+ * never added to --tools, under any configuration** — run_shell_command instead goes
+ * through the same MCP server as the file tools, which only stages (never executes),
+ * exactly like write_file: once a built-in like Bash is active, Claude Code's own
+ * agentic loop would execute it autonomously within the single `claude -p` call, with
+ * no point at which our code sees the command before it runs.
+ *
+ * **onUsage's costUsd caveat:** token counts (`inputTokens`/`outputTokens`) are always real —
+ * they come straight from `claude --output-format json`'s `usage` field. `costUsd` comes from
+ * that same response's `total_cost_usd`, which reflects real API billing when the underlying
+ * `claude` session is authenticated with an API key, but may read `0` when it's authenticated
+ * against a Pro/Max subscription instead (no per-call dollar cost to report). A caller
+ * presenting this to a user (see personal-assistant's /cost) must not read a `0` here as "this
+ * turn was free" without that context.
+ */
+export declare class ClaudeCliLLMClient implements ILLMClient {
+    private readonly claudePath;
+    private readonly fileTools?;
+    private readonly remindersFile?;
+    private readonly shellTools?;
+    private readonly webTools?;
+    private readonly actionTools?;
+    private readonly model?;
+    /**
+     * The concrete model id the last `claude -p` call actually reported running against (read from
+     * the response's own `model` field, not the CLI alias). `undefined` until a call resolves one.
+     * Plan A1 records this into the benchmark report so a published table can name the model.
+     */
+    resolvedModelId?: string;
+    constructor(options?: ClaudeCliLLMClientOptions);
+    callChat(messages: ChatMessage[], options?: ChatOptions): AsyncIterable<string>;
+    callChatSync(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+    /**
+     * When `tools` is non-empty and `fileTools`/`shellTools` was configured, wires the
+     * file-tools MCP server into a single `claude -p` call and lets Claude Code's own
+     * agentic loop call read_file/list_directory/write_file/fetch_url/create_reminder/
+     * list_reminders/run_shell_command autonomously — we don't get to intercept each
+     * call the way the proxy backend's manual tool loop does (see
+     * plans/personal_assistant_file_tools_plan.html, T6). fetch_url is always
+     * registered on that server; create_reminder/list_reminders only when
+     * `remindersFile` is set; run_shell_command only when `shellTools` is set;
+     * web_search only when `webTools` is set (Brave Search — see the `webTools`
+     * option). Three
+     * possible outcomes: a final text reply (no tool call this backend needs to
+     * surface), a write or shell command staged by the MCP server mid-call (surfaced
+     * as a synthetic `__staged_action` tool call so assistant.ts's tool loop treats it
+     * the same as a manually staged action without staging it a second time), or —
+     * for fetch_url/create_reminder/list_reminders — the tool's result text folded
+     * directly into Claude Code's own reply, since (unlike the proxy backend's
+     * `executeToolCall`) there's no outer loop here to intercept each call and
+     * re-apply trust-tagging itself; the MCP server tags fetch_url's result before
+     * Claude Code ever sees it instead (see file-tools-mcp-server.mjs).
+     */
+    callChatStructured(messages: ChatMessage[], tools?: ToolDefinition[], options?: ChatOptions): Promise<LLMStructuredResponse>;
+    /** Diffs .pending-actions/ against the call's start time to detect a write or shell command the MCP server staged during this subprocess call. */
+    /**
+     * When the MCP server staged more than one action this call (e.g. "run X AND write Y" —
+     * see file-tools-mcp-server.mjs's stagePendingAction doc comment), every one of them lands
+     * in `.pending-actions/` with an mtime after `startTimeMs`, in `readdir`-arbitrary order —
+     * not necessarily staging order. Must return the *chain head* (earliest `stagedAt`)
+     * specifically, since resolvePendingAction (assistant.ts) walks `nextPendingActionId`
+     * forward from whichever record it's handed; returning a later link here would surface the
+     * chain out of order and orphan the earlier, still-unresolved action.
+     */
+    private findPendingActionStagedSince;
+}

package/dist/claude-cli-prompt.d.ts

@@ -0,0 +1,86 @@
+import { ChatMessage, TokenUsage } from '@buildaharness/runtime';
+import { PendingActionRecord } from './file-tools.js';
+/**
+ * Synthetic tool name a claude-cli-backed ILLMClient uses to signal "an action was already
+ * staged by the file-tools MCP server during this call" — distinct from `write_file`/
+ * `run_shell_command` so assistant.ts's tool loop adopts the already-staged id instead of
+ * staging a second, redundant pending action. Shared across every backend that wires that
+ * MCP server into a `claude -p` call (claude-cli-llm-client.ts today; a Tauri desktop
+ * bridge tomorrow) so assistant.ts's `call.name === '__staged_action'` check has exactly
+ * one producer to stay in sync with.
+ */
+export declare const ALREADY_STAGED_ACTION_TOOL = "__staged_action";
+/**
+ * Reduces a staged record down to the synthetic __staged_action tool call's input shape. Shared
+ * for the same reason ALREADY_STAGED_ACTION_TOOL above is. `kind: 'revert'` is never passed here
+ * — a revert is only ever staged directly (assistant.ts's stageUndoAction, driven by
+ * /undo-action), never proposed by the model through the claude-cli MCP server's staging path.
+ */
+export declare function stagedActionInput(record: PendingActionRecord): {
+    id: string;
+    kind: 'write' | 'shell' | 'email';
+} & Record<string, unknown>;
+/**
+ * Converts a ChatMessage[] transcript into the `--system-prompt`/trailing-prompt-argument
+ * pair a `claude -p` invocation expects. Pure and environment-agnostic (no node:child_process
+ * import) so it can be shared by every backend that shells out to the Claude CLI — today
+ * that's claude-cli-llm-client.ts (spawns `claude` directly via node:child_process, used by
+ * the CLI front end) and chat-ui's TauriClaudeCliLLMClient (invokes a Tauri Rust command that
+ * spawns `claude`, used by the desktop front end) — without the two drifting apart.
+ *
+ * Every call to `claude -p` is a fresh, stateless subprocess (`--no-session-persistence`) —
+ * there is no real prior turn from the underlying API's point of view, only whatever text we
+ * hand it in this one prompt argument. When there's more than one prior turn to carry, the
+ * history is explicitly framed as a labeled, delimited block ("verbatim conversation so far
+ * ... never doubt, deny, or second-guess it") clearly separated from the current message,
+ * rather than just interleaved as bare lines — found via live testing (conv150/conv166's
+ * re-probe) that a flat, unframed interleaving occasionally led the model to treat its own
+ * prior "Assistant:" line as fabricated/untrustworthy and explicitly disclaim it to the user,
+ * on perfectly ordinary turns, not just the synthetic decline-notice line that first surfaced
+ * this. A single-message call (the common case — most turns have no history yet) is left
+ * exactly as before: the bare content, no framing overhead.
+ */
+export declare function buildClaudePrompt(messages: ChatMessage[]): {
+    systemPrompt: string;
+    prompt: string;
+};
+export interface ParsedClaudeCliOutput {
+    reply: string;
+    /** Real usage/cost from Claude's own accounting — absent when stdout wasn't valid JSON (e.g. a plain-text error). See ClaudeCliLLMClient's doc comment for the Pro/Max-subscription caveat on costUsd. */
+    usage?: TokenUsage;
+    /** The concrete model id the CLI reported running against (`model` field of the result event), not the `--model` alias. Absent when the CLI didn't report one. */
+    model?: string;
+}
+/**
+ * Parses `claude --output-format json`'s stdout into the reply text plus usage, falling back
+ * to just the raw stdout as the reply if it isn't valid JSON (e.g. the CLI printed a
+ * plain-text error before reaching --output-format handling). Shared for the same reason
+ * buildClaudePrompt above is.
+ */
+/**
+ * The claude-cli backend has no schema-constrained "structured output" mode of its own —
+ * callChatStructured's schema is only ever a system-prompt instruction ("Respond with JSON
+ * only, no prose") the model can, and routinely does, still wrap in a markdown code fence
+ * (```json ... ```). Every caller (classifyTurnIntent, checkForContradictions,
+ * reframeTaskDescriptionWithLLM, buildPlanFromTemplate, review-checker.ts, trust-tagging.ts,
+ * failure-mode-matcher.ts) does a
+ * bare `JSON.parse(response.content)` and falls back to its own "nothing structured" default on
+ * any parse failure — a fenced reply silently looked exactly like the model declining to
+ * decompose/flag/reframe anything, rather than a parsing bug. Only strips a fence that wraps the
+ * *entire* trimmed reply (leading and trailing) — never touches an ordinary conversational reply
+ * that legitimately contains a code block, since this is only ever applied to the
+ * structured-output path, not plain callChat/callChatSync results.
+ */
+export declare function stripJsonCodeFence(content: string): string;
+/**
+ * The `claude` CLI (2.1.x) reports no top-level `model` on a `--output-format json`/`stream-json`
+ * result — only a `modelUsage` map, and it routinely has **two** entries: the model that actually
+ * ran the turn (per `--model`) plus a small internal Haiku call the CLI makes for its own
+ * bookkeeping. `Object.keys(modelUsage)[0]` was picking that auxiliary Haiku, which is why every
+ * audit report on disk says `claude-haiku-4-5-20251001` even though `--model=sonnet` was honoured.
+ *
+ * The primary turn always carries the full prompt + cached context, so it has by far the most
+ * input tokens — pick the entry with the largest `input + cacheRead + cacheCreation`.
+ */
+export declare function primaryModelFromUsage(modelUsage: Record<string, unknown> | undefined): string | undefined;
+export declare function parseClaudeCliOutput(stdout: string): ParsedClaudeCliOutput;

package/dist/cli-config.d.ts

@@ -0,0 +1,27 @@
+import { AssistantConfig, CONFIG_KEYS } from './config.js';
+/**
+ * Pure logic backing cli.ts's /config command family — split out so it's unit-testable in
+ * isolation, the same way error-classifier.ts and node-display-names.ts are split out of
+ * cli.ts for the same reason. cli.ts itself stays thin glue (readline dispatch, ConfigStore
+ * I/O, rebuilding the assistant) on top of these functions.
+ */
+export { CONFIG_KEYS };
+/** Never printed in full by formatConfigValue — /config shows these masked regardless of value. */
+export declare const SECRET_CONFIG_KEYS: ReadonlySet<keyof AssistantConfig>;
+/** Which env var, if any, can pin a given key — shown next to a value in /config's listing when that var is set. */
+export declare const ENV_VAR_FOR_CONFIG_KEY: Partial<Record<keyof AssistantConfig, string>>;
+export declare function isConfigKey(key: string): key is keyof AssistantConfig;
+/**
+ * Builds the `overrides` argument for resolveConfig() from process.env — only includes a key
+ * when its env var is actually set, so an absent env var can never shadow a persisted config
+ * value with a falsy default. Mirrors the exact env vars/parsing cli.ts read individually
+ * before this module existed (ASSISTANT_ENABLE_WEB/ASSISTANT_ENABLE_SHELL must be exactly "1").
+ */
+export declare function envOverridesFromProcessEnv(env: NodeJS.ProcessEnv): Partial<AssistantConfig>;
+/** Thrown by parseConfigValue on a value that doesn't fit the target key's type — cli.ts reports .message and leaves the config unchanged. */
+export declare class ConfigValueParseError extends Error {
+}
+/** Parses a raw `/config set <key> <value>` string into the type AssistantConfig[key] expects. */
+export declare function parseConfigValue(key: keyof AssistantConfig, raw: string): unknown;
+/** Renders /config's full listing as a single multi-line string — cli.ts just console.logs the result. */
+export declare function formatConfigListing(config: AssistantConfig, overriddenKeys: ReadonlySet<keyof AssistantConfig>): string;