@buildaharness/aielia 0.3.0

package/dist/shell-executor.d.ts

@@ -0,0 +1,14 @@
+import { ShellCommandExecutor } from './shell-tools.js';
+/**
+ * Actually runs a previously staged, already-sandboxed command — the real child_process.spawn call,
+ * invoked only at approval time via file-tools.ts's applyPendingAction(..., { executeShell }). `cwd`
+ * is pinned to the staged (already-validated) path; `env` is reduced to an explicit allowlist so a
+ * secret like ASSISTANT_PROXY_TOKEN/ANTHROPIC_API_KEY can't leak into the command's environment,
+ * plus network-containment.ts's loopback-only proxy forced via HTTP(S)_PROXY (Decision 6 — see
+ * networkContainmentEnv's doc comment). A hard timeout SIGKILLs the whole process group (not just
+ * the immediate child — `detached: true` + a negative-pid kill reaches anything the shell itself
+ * spawned) rather than leaving it running. A non-zero exit code is not a thrown error — it's
+ * reported normally, same as a real shell; only a spawn failure (e.g. the shell itself couldn't
+ * start) throws.
+ */
+export declare const runApprovedShellCommand: ShellCommandExecutor;

package/dist/shell-tools.d.ts

@@ -0,0 +1,84 @@
+import { FsBackend, ToolDefinition } from '@buildaharness/runtime';
+import { ShellExecutionResult } from './file-tools.js';
+/**
+ * Executes a previously staged, already-sandboxed command for real — see shell-executor.ts's
+ * runApprovedShellCommand for the Node implementation. Typed here (not in shell-executor.ts)
+ * so ShellToolsContext can reference it without this module — which assistant.ts/index.ts
+ * import unconditionally, including into the browser build — ever importing node:child_process.
+ */
+export type ShellCommandExecutor = (command: string, cwd: string, options?: {
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    networkAllowlist?: string[];
+}) => Promise<ShellExecutionResult>;
+/**
+ * Heuristic-only: flags a command whose text contains a literal `..` parent-directory path
+ * segment (e.g. `cd ..`, `mkdir ../foo`, `cat ../../etc/passwd`). Unlike write_file, there is no
+ * real filesystem containment for run_shell_command once approved — shell-executor.ts's
+ * runApprovedShellCommand validates only that the *starting* `cwd` resolves inside the workspace
+ * (assertRealPathInWorkspace below); the command text itself then runs with the process's real
+ * OS-level filesystem access, so `cd ..` or a `../`-relative path genuinely escapes the workspace
+ * root on disk (confirmed live — see the conv06 batch finding this heuristic exists to surface).
+ * This exists purely to append an honest heads-up to the approval prompt so a human approver
+ * isn't misled by write_file's "sandboxed workspace" framing into assuming the same containment
+ * applies here. It is NOT a guard: it doesn't block anything, and it cannot catch every escape
+ * vector (absolute paths, symlinks, `cd $(pwd)/..`, indirection through env vars, etc.) — treat a
+ * `false` result as "this particular heuristic didn't fire," not "this command is contained."
+ */
+export declare function commandMayLeaveWorkspace(command: string): boolean;
+/**
+ * Heuristic-only: flags a command that looks like it makes an outbound HTTP(S) request (curl,
+ * wget, or a bare http(s):// URL), the shape network-containment.ts's proxy actually intercepts.
+ * Used to decide whether an executed command's output needs an explicit note that a deny-all
+ * network allowlist (the default — see AssistantConfig.shellNetworkAllowlist's doc comment)
+ * turns any such request into an immediate local 403, indistinguishable in the raw output from a
+ * real server response — found live (conv B, 2026-08-18 batch): without this, the LLM call that
+ * synthesizes a reply from the raw output has no way to know containment was even in play (it
+ * never sees run_shell_command's tool description, only the command + its output) and reliably
+ * misattributes the block to the destination server. A tool-description-only fix does not reach
+ * this synthesis call, so this deterministic check is required in addition to it.
+ */
+export declare function commandLooksLikeNetworkRequest(command: string): boolean;
+export declare const RUN_SHELL_COMMAND_TOOL: ToolDefinition;
+export declare const SHELL_TOOLS: ToolDefinition[];
+/** Everything executeShellTool needs to validate + stage a proposal — no execution capability required. */
+export interface ShellStagingContext {
+    backend: FsBackend;
+    workspaceRoot: string;
+}
+/**
+ * Everything PersonalAssistant needs to both stage and, once approved, actually apply a shell
+ * action. `executeCommand` is required (not just an optional extra) because assistant.ts itself
+ * never imports node:child_process — it's bundled into the browser build (via index.ts) too, so
+ * the real Node implementation (shell-executor.ts's runApprovedShellCommand) is only ever wired
+ * in by a Node-only caller (cli.ts), exactly like node-fs-backend.ts already is.
+ */
+export interface ShellToolsContext extends ShellStagingContext {
+    /** Hard timeout for an approved command, in ms. Passed through to executeCommand at apply time. Default 30000. */
+    timeoutMs?: number;
+    /**
+     * Hostnames an approved command's HTTP(S)_PROXY traffic may reach (exact match or subdomain) —
+     * see network-containment.ts and shell-executor.ts's networkContainmentEnv. Passed through to
+     * executeCommand at apply time, same as timeoutMs. Undefined/empty denies all network access,
+     * the safe default (Decision 6, plans/lexical_functions_hardening_plan.html Phase 4).
+     */
+    networkAllowlist?: string[];
+    executeCommand: ShellCommandExecutor;
+}
+export type ShellToolResult = {
+    kind: 'staged_shell';
+    id: string;
+    command: string;
+    cwd: string;
+};
+/**
+ * Executes run_shell_command by name. Never spawns anything itself — only stages, exactly like
+ * write_file does for file-tools, every time — no cached-result shortcut, since a command's real
+ * output can change from one run to the next regardless of whether its text is identical.
+ *
+ * The cwd validation above and the stagePendingAction call below both run unconditionally on this
+ * call's own concrete (command, cwd) arguments, regardless of what risk-classifier.ts concluded
+ * about the user's message text — see stagePendingAction's doc comment in file-tools.ts for the
+ * general "gate on the concrete tool call, not the free text" principle this follows.
+ */
+export declare function executeShellTool(ctx: ShellStagingContext, toolName: string, input: Record<string, unknown>): Promise<ShellToolResult>;

package/dist/spend-cap.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-turn, cross-session spend enforcement — the review's §5.2 finding was that `/cost`
+ * reports usage but nothing ever refuses a turn over it. Pure math/formatting only; PersonalAssistant
+ * (assistant.ts) owns the actual persisted SpendState and calls checkSpendCap() once per turn,
+ * before any LLM call for that turn is made (see assistant.ts's turn() wrapper).
+ */
+export interface SpendCapConfig {
+    /** Undefined = unbounded, today's default behavior. */
+    sessionCostLimitUsd?: number;
+    /**
+     * Optional secondary ceiling on completed turns this session (not raw internal LLM call
+     * count — a single turn can make several real LLM calls of its own, e.g. decomposition +
+     * tool-loop round trips, and none of those sub-calls can trigger a mid-turn refusal per
+     * checkSpendCap's "pre-turn only" contract, so counting at that finer grain would have
+     * nothing to enforce against). Named sessionCallLimit to match the review's own "dollar/call
+     * ceiling" framing (§11).
+     */
+    sessionCallLimit?: number;
+}
+export interface SpendState {
+    cumulativeCostUsd: number;
+    cumulativeCalls: number;
+    /** Tracked alongside cumulativeCostUsd (same cross-turn, cross-session lifetime) so /cost's
+     * token tally and its dollar/ceiling figures always describe the same scope — previously the
+     * token counts lived only in cli.ts's in-process `sessionUsage`, which resets on /new (and on
+     * every fresh process) while this store does not, producing a "0 in / 0 out tokens" line next
+     * to a real nonzero dollar cost once any turn had run before the current /new. */
+    cumulativeInputTokens: number;
+    cumulativeOutputTokens: number;
+}
+export declare const EMPTY_SPEND_STATE: SpendState;
+export type SpendCapCheck = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Called once at the start of turn(), before any LLM call for that turn is made. A turn already in flight is never interrupted mid-turn. */
+export declare function checkSpendCap(state: SpendState, config: SpendCapConfig): SpendCapCheck;
+/** Shared by /status and /cost (cli.ts) so the ceiling reads the same way in both places — undefined when no ceiling is configured, so callers can omit the line entirely rather than showing a meaningless "N% of nothing". */
+export declare function formatSpendCapStatus(state: SpendState, config: SpendCapConfig): string | undefined;

package/dist/spike.d.ts

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

package/dist/spike.js

@@ -0,0 +1,18 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { render, useInput, Box, Text } from "ink";
+function Spike() {
+  const [lastKey, setLastKey] = useState("(none yet)");
+  useInput((input, key) => {
+    if (key.escape || key.ctrl && input === "c") {
+      process.exit(0);
+    }
+    setLastKey(key.return ? "<enter>" : input || JSON.stringify(key));
+  });
+  return /* @__PURE__ */ jsx(Box, { borderStyle: "round", padding: 1, children: /* @__PURE__ */ jsxs(Text, { children: [
+    "Ink spike — hello world. Last key: ",
+    lastKey
+  ] }) });
+}
+render(/* @__PURE__ */ jsx(Spike, {}));
+//# sourceMappingURL=spike.js.map

package/dist/spike.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spike.js","sources":["../src/tui-spike.tsx"],"sourcesContent":["// Phase 0 feasibility spike for plans/personal_assistant_cli_pinned_input_plan.html.\n// Throwaway — not part of the shipped feature. Delete once Phase 5 confirms Ink\n// works over a real live terminal (raw-mode input + redraw), along with its\n// temporary build entry in vite.config.lib.ts.\nimport React, { useState } from 'react'\nimport { Box, Text, render, useInput } from 'ink'\n\nfunction Spike() {\n  const [lastKey, setLastKey] = useState('(none yet)')\n\n  useInput((input, key) => {\n    if (key.escape || (key.ctrl && input === 'c')) {\n      process.exit(0)\n    }\n    setLastKey(key.return ? '<enter>' : input || JSON.stringify(key))\n  })\n\n  return (\n    <Box borderStyle=\"round\" padding={1}>\n      <Text>Ink spike — hello world. Last key: {lastKey}</Text>\n    </Box>\n  )\n}\n\nrender(<Spike />)\n"],"names":[],"mappings":";;;AAOA,SAAS,QAAQ;AACf,QAAM,CAAC,SAAS,UAAU,IAAI,SAAS,YAAY;AAEnD,WAAS,CAAC,OAAO,QAAQ;AACvB,QAAI,IAAI,UAAW,IAAI,QAAQ,UAAU,KAAM;AAC7C,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,eAAW,IAAI,SAAS,YAAY,SAAS,KAAK,UAAU,GAAG,CAAC;AAAA,EAClE,CAAC;AAED,6BACG,KAAA,EAAI,aAAY,SAAQ,SAAS,GAChC,+BAAC,MAAA,EAAK,UAAA;AAAA,IAAA;AAAA,IAAoC;AAAA,EAAA,EAAA,CAAQ,EAAA,CACpD;AAEJ;AAEA,OAAO,oBAAC,SAAM,CAAE;"}

package/dist/supervisor-decider.d.ts

@@ -0,0 +1,3 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { SupervisorDirectiveData, TrajectoryDigestData } from '@buildaharness/harness';
+export declare function decideSupervisorDirective(digest: TrajectoryDigestData, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<Partial<SupervisorDirectiveData> | null>;

package/dist/system-prompt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The assistant's base system prompt — split into its own module so both assistant.ts's
+ * sequencer (which splices in the per-turn facts/reminders blocks) and
+ * action-approval-service.ts's shell-output synthesis call (SYNTHESIS_SYSTEM_PROMPT below) can
+ * depend on it without either module owning the other.
+ */
+export declare const SYSTEM_PROMPT: string;
+export declare const SYNTHESIS_SYSTEM_PROMPT: string;

package/dist/task-mapping.d.ts

@@ -0,0 +1,42 @@
+import { Task } from '@buildaharness/harness';
+import { TurnIntentClassification } from './turn-intent-classifier.js';
+/**
+ * Builds a fresh harness Task[] from a flat task-spec list — shared by the single-task
+ * fallback, the ad hoc decomposition path, a newly built plan, and a resumed plan.
+ * `status` defaults to 'PENDING' when omitted (decomposeObjective's and
+ * buildPlanFromTemplate's output never carries one). A resumed plan passes its tasks'
+ * real statuses through *including* COMPLETE ones — TaskGraph.selectUnblockedLeaf
+ * resolves depends_on by looking up each dependency's status in the current graph, so
+ * a completed dependency that got filtered out of initialTasks would never register as
+ * satisfied and its dependents would stay permanently blocked.
+ *
+ * A task's own `riskLevel` (classifyTurnIntent's per-task judgment for ad hoc decompositions,
+ * or buildPlanFromTemplate's template-curated risk_level for a plan — see plan-store.ts's
+ * PlanTaskRecord) is used directly when present — see Phase 4.2 of the harness layer activation
+ * plan: a plan step like "delete the draft file" shouldn't inherit an unrelated sibling step's
+ * risk profile just because they were rendered from the same turn-level classification.
+ * `fallbackRiskLevel` (one flat level, or a per-task function keyed off description) is only
+ * consulted when a task has no `riskLevel` of its own — the single-task path (never has one,
+ * always uses the flat turn-level classification.riskLevel) and a plan persisted before this
+ * field existed (falls back to lexical planTaskRiskLevel/classifyRisk, exactly as every task
+ * used to unconditionally).
+ */
+export declare function toHarnessTasks(tasks: {
+    id: string;
+    description: string;
+    depends_on: string[];
+    status?: Task['status'];
+    riskLevel?: Task['risk_level'];
+}[], fallbackRiskLevel: Task['risk_level'] | ((description: string) => Task['risk_level'])): Task[];
+/**
+ * packages/harness's own risk-level types (Task['risk_level'], TurnComplexitySignal['riskLevel'])
+ * are a strict LOW/MEDIUM/HIGH enum with no UNKNOWN concept — classification.riskLevel can be
+ * 'UNKNOWN' only via failSafeClassification (turn-intent-classifier.ts), which also always leaves
+ * decomposedTasks null, so in practice this only ever maps the flat, single-task fallback path.
+ * Mapped to 'HIGH' (not 'LOW') as the conservative choice: an unknown risk should get the
+ * harness's most cautious handling, not its least. Shared by every module that crosses into a
+ * packages/harness-typed field (task-interpreter.ts and harness-bridge.ts).
+ */
+export declare function toTaskRiskLevel(riskLevel: TurnIntentClassification['riskLevel']): Task['risk_level'];
+/** Lexical fallback for a durable plan's steps that were persisted before per-task riskLevel existed (see toHarnessTasks) — reuses classifyRisk's own keyword patterns against each step's own description. */
+export declare function planTaskRiskLevel(description: string): Task['risk_level'];

package/dist/tool-control-plane.d.ts

@@ -0,0 +1,67 @@
+import { WorldModel, EvidenceStore, Diagnostics, FailureDiagnostics, ControlState, ToolAvailability } from '@buildaharness/harness';
+/**
+ * Phase 4c of plans/harness_and_assistant_architecture_remediation_plan.html — a live, per-turn
+ * harness ControlState, so tool-policy.ts's evaluateToolPolicy() can be given a real
+ * controlState instead of the pre-evidence-baseline `undefined` every call site passed before
+ * this phase. Deliberately builds on the fallback control-plane design (no packages/harness core
+ * changes): composes the harness's own pure, already-exported node functions directly, never
+ * touching HarnessRuntime's generator.
+ *
+ * DESIGN NOTE — why this never calls the generic updateDiagnostics() node: that function's
+ * coverage_health.symptom_coverage is computed from HypothesisSet.active, which nothing in this
+ * minimal tool-call-outcome-only pipeline ever populates (there's no hypothesis-generation/
+ * task-graph engine backing it here). symptom_coverage would therefore read structurally as 0 —
+ * below CRITICAL_THRESHOLD — the moment updateDiagnostics() ran, which would spuriously DENY
+ * almost every second-or-later tool call in every tool-using turn, regardless of whether
+ * anything actually failed. Verified against adapter-equivalent source
+ * (update-diagnostics.ts:150-167, resolve-control-state.ts:96-97,174-178) before this file was
+ * written. Instead: coverage_health/execution_health.{progress_rate,oscillation_score} are left
+ * at their constructor-safe defaults (confirmed outside the CAUTIOUS band), and only
+ * execution_health.failure_recurrence is hand-updated, using update-diagnostics.ts's own exact
+ * formula. That crosses CRITICAL_THRESHOLD at 8+ same-turn tool failures — a real, honest bar,
+ * not a hair-trigger. (Not exactly the 9 a back-of-envelope 1-in-10 reading suggests: at exactly
+ * 8 failures, failure_recurrence is 0.8, and resolve-control-state.ts's own pre-existing
+ * `1 - failure_recurrence` comparison evaluates to 0.19999999999999996 in IEEE754 double
+ * arithmetic — a floating-point rounding quirk already present in that comparison, not
+ * introduced here — landing just under CRITICAL_THRESHOLD (0.2) one failure earlier than exact
+ * decimal math would suggest. See tool-control-plane.test.ts for the pinned boundary.)
+ *
+ * SCOPE BOUNDARY, explicit and deliberate: this state is turn-scoped and in-memory only. A
+ * persisted resume path (e.g. resolvePendingBatchConfirmation's batch-approval round trip
+ * through storage) does not carry a live ControlState across the gap — the original turn's
+ * state is gone by the time a resume happens. Real, buildable future work; out of scope here.
+ */
+export interface TurnControlPlaneState {
+    readonly evidenceStore: EvidenceStore;
+    readonly worldModel: WorldModel;
+    readonly diagnostics: Diagnostics;
+    readonly failureDiagnostics: FailureDiagnostics;
+    controlState: ControlState;
+}
+/**
+ * A fresh EvidenceStore defaults to an EMPTY tool_availability_manifest, which makes
+ * gatherEvidence() silently no-op for every tool. Seed it with every tool name this turn's
+ * config actually enables, so tool outcomes are never silently dropped.
+ */
+export declare function toolAvailabilityManifest(toolNames: string[]): Record<string, ToolAvailability>;
+export declare function createTurnControlPlaneState(toolNames: string[]): TurnControlPlaneState;
+export interface ToolOutcome {
+    toolName: string;
+    ok: boolean;
+    /** Short, human-readable — never the full resultText (can be large/untrusted). */
+    summary: string;
+}
+/**
+ * The more tool-restrictive of two ControlStates (ties → `a`). A harness-driven proposer must
+ * honor BOTH the harness's own per-iteration ControlState AND the turn-local one accumulated
+ * from this turn's prior tool-call outcomes (via recordToolOutcome) — neither may silently
+ * downgrade the other. Overwriting one with the other (which the one-loop proposer used to do)
+ * loses whichever restriction the discarded side carried; this keeps the stricter one.
+ */
+export declare function moreRestrictiveControlState(a: ControlState, b: ControlState): ControlState;
+/**
+ * Feeds one tool call's outcome through the partial pipeline described in this file's own
+ * top-of-file doc comment, mutates `state` in place, and returns the freshly-resolved
+ * ControlState (also left on `state.controlState` for convenience).
+ */
+export declare function recordToolOutcome(state: TurnControlPlaneState, outcome: ToolOutcome): ControlState;

package/dist/tool-policy.d.ts

@@ -0,0 +1,45 @@
+import { RiskLevel } from './turn-intent-classifier.js';
+/**
+ * Phase 4 of plans/harness_and_assistant_architecture_remediation_plan.html: the deterministic,
+ * authoritative decision point for whether a specific tool call may proceed — replacing "advisory
+ * LLM classification, checked after the fact" with "deterministic policy informed by real harness
+ * state, checked before execution" (the substantive fix both external architecture critiques
+ * asked for).
+ *
+ * Modeled on file-tools.ts's stagePendingAction gate, which already runs unconditionally on a
+ * tool call's own concrete arguments (the literal path/content or command/cwd), independent of
+ * whatever risk-classifier text patterns concluded about the user's phrasing — see that function's
+ * own doc comment for the "gate on the concrete tool call, not the free text" rationale this
+ * module generalizes into a single, reusable, unit-testable decision function instead of the
+ * pattern living only inline at each tool's own call site.
+ *
+ * `riskHint` (turn-intent-classifier.ts's RiskLevel, including the fail-safe 'UNKNOWN') is an
+ * input/signal, never itself the gate — a HIGH riskHint can't downgrade a real harness DENY, and a
+ * LOW riskHint can't upgrade past what the concrete tool call and control state already require.
+ */
+export type ToolPolicyDecision = 'ALLOW' | 'REQUIRE_APPROVAL' | 'DENY';
+/** Structural subset of packages/harness's ControlState — only the fields this policy reads,
+ * so callers can pass either a live ControlState instance or a plain matching object without an
+ * import-time dependency on the class itself. */
+export interface ToolPolicyControlState {
+    permission: 'ALLOW' | 'DENY';
+    execution_mode: 'NORMAL' | 'CAUTIOUS' | 'RECOVERY';
+    escalation: 'NONE' | 'HUMAN_REQUIRED' | 'SYSTEM_BREAKING';
+}
+export interface ToolPolicyInput {
+    toolName: string;
+    riskHint: RiskLevel;
+    /**
+     * The harness's live ControlState for this turn, when one has actually been computed —
+     * `undefined` for the pre-evidence baseline before any tool call this turn has produced
+     * observations to resolve a real ControlState from (see resolve-control-state.ts: a fresh
+     * WorldModel with zero evidence resolves to an uninformative NORMAL/ALLOW every time, so
+     * treating "not yet computed" the same as "computed and permissive" costs nothing here).
+     */
+    controlState?: ToolPolicyControlState;
+}
+export interface ToolPolicyResult {
+    decision: ToolPolicyDecision;
+    reason: string;
+}
+export declare function evaluateToolPolicy(input: ToolPolicyInput): ToolPolicyResult;

package/dist/tool-step.d.ts

@@ -0,0 +1,23 @@
+import { ToolStepEvent } from '@buildaharness/runtime';
+/**
+ * Live, UI-facing tool-call event — deliberately distinct from trace-events.ts's TraceEvent
+ * (`kind: 'tool_call'`), which is intentionally name/status-only telemetry safe to hand to
+ * an arbitrary logging sink. This one exists purely so a front end can show "what is the
+ * assistant doing right now" the way Claude Code's own CLI does, so it carries a
+ * human-readable summary and the raw input.
+ */
+export interface AssistantToolStep extends ToolStepEvent {
+    summary: string;
+}
+/**
+ * Strips an MCP-qualified tool name (`mcp__<server>__<tool>`, how Claude Code CLI surfaces
+ * a tool registered via --mcp-config) down to the bare name our own tool defs use — a
+ * plain API/proxy backend's tool names never have this prefix, so this is a no-op there.
+ */
+export declare function stripMcpToolPrefix(name: string): string;
+/**
+ * One human-readable line per tool call, shared across every front end (CLI/chat-ui/desktop)
+ * and every backend (the proxy's own tool loop in assistant.ts, ClaudeCliLLMClient's stream
+ * parsing) so "what step is this" reads identically no matter where it's rendered.
+ */
+export declare function summarizeToolStep(tool: string, input: Record<string, unknown>): string;

package/dist/tool-yield-classifier.d.ts

@@ -0,0 +1,7 @@
+export type ToolYield = 'productive' | 'dead_end';
+/**
+ * Zero-LLM-call heuristic run on every web tool result inside a batch sub-loop, so it has to stay
+ * cheap. Defaults to 'productive' whenever the result isn't unambiguously a dead end — see
+ * DEAD_END_MARKERS' comment for why that asymmetry is deliberate.
+ */
+export declare function classifyToolYield(toolName: 'web_search' | 'fetch_url', resultText: string): ToolYield;

package/dist/trace-events.d.ts

@@ -0,0 +1,126 @@
+import { RiskLevel } from './turn-intent-classifier.js';
+import { ExecutionMode } from './execution-mode.js';
+import { ToolPolicyDecision } from './tool-policy.js';
+import { ProposerKind } from './assistant-types.js';
+/**
+ * Structured turn telemetry — deliberately name/status-only, never full message
+ * content, so it's cheap to log and safe to hand to an arbitrary sink (Langfuse,
+ * console, a custom collector). See PersonalAssistantOptions.onTrace.
+ */
+export type TraceEvent = {
+    kind: 'turn_start';
+    sessionId: string;
+    message: string;
+} | {
+    kind: 'turn_end';
+    sessionId: string;
+    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval';
+} | {
+    kind: 'risk_classified';
+    riskLevel: RiskLevel;
+    requiresApproval: boolean;
+} | {
+    kind: 'triviality_classified';
+    isTrivial: boolean;
+} | {
+    kind: 'plan_classified';
+    isCandidate: boolean;
+    matchedTemplate: string | null;
+} | {
+    kind: 'plan_updated';
+    templateName: string | null;
+    completionPct: number;
+} | {
+    kind: 'harness_node';
+    node: string;
+    stepsUsed: number;
+} | {
+    kind: 'tool_call';
+    tool: string;
+    ok: boolean;
+} | {
+    kind: 'escalation';
+    reason: string;
+} | {
+    kind: 'error';
+    message: string;
+}
+/**
+ * One of the harness's 11 layers did (or explicitly skipped) real work this step —
+ * see plans/harness_layer_activation_plan.html Phase 2/3.1. `layer` is a stable slug
+ * ('world_model' | 'evidence_reasoning' | 'hypothesis' | 'contradiction' | 'diagnostics' |
+ * 'control_state' | 'planning' | 'execution' | 'verification' | 'recovery' | 'reviewer_pass'),
+ * not a free-text name, so a "Why?"/`/layers` renderer can key off it directly.
+ */
+ | {
+    kind: 'layer_activity';
+    layer: string;
+    fired: boolean;
+    reason: string;
+}
+/**
+ * A prior-turn harness checkpoint (see runTurn's runId doc comment — left behind when a
+ * process died mid-run before reaching normal cleanup) failed to resume `failedAttempts` times
+ * in a row and was discarded automatically instead of being retried again; this turn started
+ * fresh instead of resuming it. See PersonalAssistant.clearCheckpoint for the manual
+ * equivalent, and RESUME_ATTEMPT_CAP in assistant.ts for the threshold.
+ */
+ | {
+    kind: 'checkpoint_discarded';
+    sessionId: string;
+    failedAttempts: number;
+}
+/**
+ * Phase 4 of plans/harness_and_assistant_architecture_remediation_plan.html — see
+ * execution-mode.ts's own doc comment for each mode's guarantee level.
+ */
+ | {
+    kind: 'execution_mode_classified';
+    mode: ExecutionMode;
+}
+/**
+ * ToolPolicy's decision for one specific tool call, before it runs — the deterministic,
+ * harness-state-informed gate replacing "advisory classification checked after the fact" (see
+ * tool-policy.ts).
+ */
+ | {
+    kind: 'tool_policy_decision';
+    tool: string;
+    decision: ToolPolicyDecision;
+    reason: string;
+}
+/**
+ * Which proposer drove this turn — 'posthoc' (flag OFF, or a trivial / no-tool turn),
+ * 'flat-oneloop', or 'batch-oneloop' (both flag ON). Emitted once per turn from runTurn, right
+ * after `useOneLoop` is resolved. See AssistantTurnResult.proposerKind and
+ * plans/chat_ui_browser_e2e_plan.html phase B1 for why this exists.
+ */
+ | {
+    kind: 'proposer_selected';
+    proposerKind: ProposerKind;
+}
+/**
+ * P9 of plans/ask_question_and_plan_mode_plan.html — the lightweight plan-sketch delegate
+ * (PlanSketchService) ran. `requestPreview` is truncated to stay name/status-only per this
+ * type's own doc comment, not the full request text. Distinct from `plan_classified`/
+ * `plan_updated`, which are about the stateful drafting/approval machinery (PlanDraftingService)
+ * this delegate deliberately never touches (INV-35).
+ */
+ | {
+    kind: 'plan_sketch';
+    requestPreview: string;
+}
+/**
+ * P10 of plans/ask_question_and_plan_mode_plan.html — a write_file/run_shell_command/send_email
+ * proposal was auto-applied instead of staged for approval because it was proposed while
+ * `taskId` (part of a plan approved with `'approve_trusted'`) was the currently RUNNING task —
+ * see PlanRecord.trustApprovedSteps and INV-36. The action itself still went through
+ * ActionApprovalService.resolvePendingAction exactly as a manually-approved one would (same
+ * transcript entry, same real-undo record) — this event is purely additional "why no approval
+ * prompt" observability, name/status-only per this type's own doc comment.
+ */
+ | {
+    kind: 'plan_trust_auto_applied';
+    pendingActionKind: 'write' | 'shell' | 'email';
+    taskId: string;
+};

package/dist/transcript-compaction.d.ts

@@ -0,0 +1,13 @@
+import { ChatMessage } from '@buildaharness/runtime';
+export interface CompactionResult {
+    transcript: ChatMessage[];
+    compacted: boolean;
+}
+/**
+ * Collapses the oldest messages beyond the most recent `KEEP_RECENT` into one
+ * synthetic summary message once the transcript crosses a message-count or
+ * char-count threshold. Deliberately a truncated concatenation, not an LLM
+ * summary — keeps compaction free instead of costing an extra call every time
+ * a long session crosses the threshold.
+ */
+export declare function compactTranscript(transcript: ChatMessage[]): CompactionResult;

package/dist/trust-tagging.d.ts

@@ -0,0 +1,38 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+/**
+ * Wraps content fetched from the web before it enters the model's context —
+ * `read_file`/`list_directory` results are untouched (file content is
+ * user-owned, not adversarial-by-default); only web_search/fetch_url results
+ * go through this. SYSTEM_PROMPT in assistant.ts carries the matching
+ * instruction that content in this tag is data, never instructions.
+ */
+export declare function wrapUntrusted(text: string): string;
+export interface InjectionDetection {
+    flagged: boolean;
+    reason?: string;
+}
+/** Content is always still returned to the model, flagged or not — this only decides whether a warning gets prepended. */
+export declare function detectInjectionLikely(text: string): InjectionDetection;
+/**
+ * `AUDIT_LLM_INJECTION_DETECT` gate — feature-value audit (Phase A5 of
+ * plans/feature_audit_automation_plan.html). Default **ON**: the semantic injection-detection LLM
+ * call ships enabled, so an unset / empty / truthy value keeps today's behaviour. Set to a falsy
+ * value (`0` / `false` / `off` / `no` / `disabled`) to skip the LLM escalation entirely and fall
+ * back to the always-on deterministic regex/pattern pass only. Read at exactly one place —
+ * `detectInjectionLikelyWithLLM` below, the single helper both `agent-loop.ts` and
+ * `action-approval-service.ts` route their tool-output checks through. Same shape as
+ * `semanticContradictionEnabled()` (contradiction-checker.ts) and the harness's `supervisorEnabled()`.
+ */
+export declare function llmInjectionDetectEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * Semantic escalation layered on top of the regex check above — only reached when the regex
+ * found nothing (a real injection attempt this codebase has already seen looks nothing like
+ * the fixed phrase list) and the content is long enough to plausibly hide one. Uses a
+ * structured JSON response (not a free chat reply) and an explicit "you are not the assistant
+ * being targeted" framing so the untrusted content itself has no natural surface to hijack —
+ * the same defense the main model already gets via SYSTEM_PROMPT's own instruction, applied to
+ * this classifier too. Falls back to "not flagged" on any parse failure or LLM error, matching
+ * this codebase's other LLM-backed classifiers — a missed detection costs nothing worse than
+ * the regex-only behavior this is layered on top of.
+ */
+export declare function detectInjectionLikelyWithLLM(text: string, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<InjectionDetection>;