@buildaharness/aielia 0.3.0

package/dist/tui-app.d.ts

@@ -0,0 +1,125 @@
+import { RunCliOptions } from './cli.js';
+import { CaptureEvent } from './tui-output-capture.js';
+/**
+ * A minimal pub/sub store, one per piece of state the Ink tree needs — deliberately not React
+ * state, because the values that drive it arrive from outside React entirely: `startCapture`
+ * (Phase 1) calls its `onEvent` callback synchronously from a monkey-patched `console.log`/
+ * `process.stdout.write`, and `askYesNo`/`askLine` (Decision 1's override seam) are plain
+ * functions handed to `runCli()` before any component has mounted. `useSyncExternalStore` is the
+ * React-correct way to subscribe a component to state that's mutated from outside React's own
+ * render cycle, without the chicken-and-egg problem of needing a `setState` that only exists
+ * after the first render.
+ */
+interface Store<T> {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => T;
+}
+/**
+ * Which visual style a committed scrollback line gets (this task's ask: "different formats for
+ * user text vs aielia response vs tool call details"). `'margin'` is a blank spacer line between
+ * turns, not a real writer's output — kept as its own kind rather than reusing `'system'` so
+ * rendering never has to guess a blank line's intent from empty text alone.
+ */
+export type LineKind = 'user' | 'assistant' | 'tool' | 'error' | 'system' | 'margin';
+export interface LogLine {
+    text: string;
+    kind: LineKind;
+}
+export interface TuiLogState {
+    /** Every permanently-committed scrollback line, oldest first — fed straight into `<Static>`. */
+    lines: LogLine[];
+    /** `writeProgress`'s current `\r`-overwritten line — shown in the transient region, never committed. */
+    progressText: string;
+    /** `writeToken`'s not-yet-newline-terminated streamed reply text — shown in the transient region until the next committed-line event closes it out. */
+    transientText: string;
+}
+/**
+ * Classifies and accumulates `CaptureEvent`s (Phase 1) into the three regions Phase 3's layout
+ * needs: permanent scrollback, the transient progress line, and the transient in-progress
+ * streamed reply. A `'line'` event closes out whatever streamed-token text is currently pending
+ * (see `cli.ts`'s `writeToken`/`handleTurn`: a streamed reply is one or more raw `'token'` writes
+ * followed by exactly one final `'line'` write for the trailing hint text) — merging the two
+ * before committing is what turns "Hi the|re!\n\n" (streamed "Hi the" + committed "re!\n\n") into
+ * one correct committed line instead of two garbled ones.
+ */
+export declare class EventLogBridge implements Store<TuiLogState> {
+    private lines;
+    private progressText;
+    private transientText;
+    private snapshot;
+    private listeners;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => TuiLogState;
+    private commit;
+    /**
+     * A blank spacer line ("some margins between different conversations", later extended to "at
+     * least one line spacing between the user and system messages") — called from three places in
+     * `handleSubmitChat` (never from a resolved approval/clarification prompt answer, which stays
+     * visually grouped with the turn it belongs to): once before a new turn's echo (separating it
+     * from the previous turn's reply) and once right after it (separating the echo from whatever
+     * system/tool/assistant output follows). A no-op on an empty log or if the last line is already
+     * a margin, so calling it from both of those spots back-to-back across turns can't stack blank
+     * lines — the "before next turn" and "after this turn" calls collapse into the same one line.
+     */
+    pushTurnMargin(): void;
+    /** Records a line the user just submitted (chat or a resolved prompt answer) into permanent scrollback — mirrors a real terminal's own line-echo, which the inert (non-TTY) input stream this shell uses never produces on its own. `prefix` is `''` for an ordinary chat line (no "you>" label — see `LogLineText`'s doc comment) and `'> '` for a resolved prompt answer, which keeps its prefix since it's answering a question printed just above it, not identifying whose turn it is. */
+    pushEchoLine(prefix: string, text: string): void;
+    handleEvent(event: CaptureEvent): void;
+}
+export type PendingPrompt = {
+    question: string;
+} | undefined;
+/**
+ * Bridges `runCli()`'s `askYesNo`/`askLine` override seam (Decision 1) to Ink: each call parks
+ * a resolver and exposes the pending question to the component tree via `getSnapshot()`, instead
+ * of the original `rl.question`-based implementation. `TuiInput`'s own `promptLabel` prop
+ * (Phase 2) already knows how to render this state and route Enter to `onSubmitPrompt` instead
+ * of `onSubmitChat` — this class only needs to supply the question text and resolve the answer.
+ */
+export declare class PromptBridge implements Store<PendingPrompt> {
+    private pending;
+    private resolve;
+    private listeners;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => PendingPrompt;
+    private ask;
+    /** Matches `RunCliOptions.askYesNo`'s exact parsing convention (`answer.trim().toLowerCase().startsWith('y')`) — same fail-closed shape, just answered via the Ink prompt instead of `rl.question`. */
+    askYesNo: (question: string) => Promise<boolean>;
+    askLine: (question: string) => Promise<string>;
+    submit(answer: string): void;
+}
+/** The status line's short indicator list (Phase 3 step 5) — polled from `CliInstance.getStatusIndicators()` after every dispatched line, since plan/spend-cap state only changes as a side effect of a turn. */
+export declare class StatusBridge implements Store<string[]> {
+    private indicators;
+    private listeners;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => string[];
+    set(indicators: string[]): void;
+}
+export interface TuiAppProps {
+    eventLog: EventLogBridge;
+    prompt: PromptBridge;
+    status: StatusBridge;
+    onSubmitChat: (line: string) => void;
+    onExit: () => void;
+    /** Overrides the live terminal width for tests — same seam `TuiInput` already accepts. */
+    columns?: number;
+}
+/**
+ * The top-level Ink app (Phase 3): a `<Static>` scrollback of every committed line, a transient
+ * region for the in-progress progress line/streamed reply, a one-row separator, the Phase 2
+ * multiline input box pinned to the bottom, and a reserved status line under that. Composition
+ * only — command parsing/dispatch stays entirely inside `cli.ts`'s `dispatchLine()` (Decision 1),
+ * and this component never re-implements it.
+ */
+export declare function TuiApp(props: TuiAppProps): React.JSX.Element;
+export type RunTuiAppOptions = Omit<RunCliOptions, 'askYesNo' | 'askLine'>;
+/**
+ * Constructs `runCli()` wired to this file's Ink shell (Phase 4 calls this once, behind the
+ * `tuiMode` rollout flag) and renders it. Resolves once the user exits (Ctrl+C — see `TuiApp`'s
+ * `onExit`), after the same graceful-exit steps `cli.ts`'s own `rl.on('SIGINT', ...)` handler
+ * performs: restore the captured `console`/`process.stdout`, close the underlying `CliInstance`,
+ * then exit the process.
+ */
+export declare function runTuiApp(options?: RunTuiAppOptions): Promise<void>;
+export {};

package/dist/tui-input.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One word-wrapped visual row of the draft. `wraps: true` means the next row is a continuation
+ * of the same logical (`\n`-delimited) line — no real newline between `end` and the next row's
+ * `start` — which is what lets {@link offsetToRowCol} tell a wrap boundary (cursor snaps to the
+ * start of the next row) apart from a real end-of-line (cursor stays put at this row's end).
+ */
+export interface DraftRow {
+    text: string;
+    start: number;
+    end: number;
+    wraps: boolean;
+}
+/**
+ * Splits `value` into visual rows at `\n` boundaries and, within each logical line, at every
+ * `columns`-wide chunk — plain character wrapping (not word-boundary wrapping): a real terminal
+ * hard-wraps by character when a row overflows, so this matches what the terminal will actually
+ * show rather than reflowing at word boundaries the way a GUI text area would.
+ */
+export declare function wrapDraftIntoRows(value: string, columns: number): DraftRow[];
+/** Maps a character offset into `value` to its (row, col) among `rows` — see {@link DraftRow.wraps} for the wrap-vs-newline distinction this leans on. */
+export declare function offsetToRowCol(rows: DraftRow[], cursor: number): {
+    row: number;
+    col: number;
+};
+/** Inverse of {@link offsetToRowCol}, clamping both row and column into range — used to preserve column when moving the cursor a visual row up/down. */
+export declare function rowColToOffset(rows: DraftRow[], row: number, col: number): number;
+/** Home = start of the current logical (`\n`-delimited) line, not the current visual row. */
+export declare function homeOffset(value: string, cursor: number): number;
+/** End = end of the current logical (`\n`-delimited) line, not the current visual row. */
+export declare function endOffset(value: string, cursor: number): number;
+/**
+ * Keeps the cursor's row inside a `maxRows`-tall window, scrolling the minimum amount needed —
+ * matches an ordinary scrolling textarea rather than re-centering on every keystroke.
+ */
+export declare function computeViewportStart(prevStart: number, cursorRow: number, totalRows: number, maxRows: number): number;
+export interface TuiInputProps {
+    /** Question text for a pending askYesNo/askLine prompt (Decision 1's override seam) — undefined means ordinary chat mode. Shown as a label above the box, since it's real information (the question being asked), unlike chat mode's old static "you" label, which was dropped in favor of a placeholder inside the box (see `placeholder` below). */
+    promptLabel?: string;
+    /** Faint placeholder shown inside the (empty) box in chat mode, replacing the old "you" label above it. */
+    placeholder?: string;
+    /** Called when Enter submits a non-empty draft in chat mode. Also appended to in-session history. */
+    onSubmitChat: (line: string) => void;
+    /** Called when Enter resolves a pending prompt (promptLabel set). Not added to chat history. */
+    onSubmitPrompt: (line: string) => void;
+    /** Terminal width; defaults to the live width from Ink's useWindowSize. Pass explicitly for a deterministic wrap width in tests. */
+    columns?: number;
+    /** Max input box height in rows before internal scrolling kicks in. */
+    maxRows?: number;
+    isActive?: boolean;
+}
+export declare function TuiInput(props: TuiInputProps): React.JSX.Element;

package/dist/tui-mode-flag.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure logic backing PersonalAssistant's ASSISTANT_TUI handling — split out so it's
+ * unit-testable in isolation, mirroring one-loop-flag.ts/ask-mode-flag.ts/plan-mode-flag.ts's
+ * exact shape (module-level default, an injectable resolver so tests never touch real
+ * process.env).
+ *
+ * Phase 4 of plans/personal_assistant_cli_pinned_input_plan.html — the rollout flag gating
+ * whether `cli.ts`'s `main()` launches the Phase 3 Ink shell (`runTuiApp()`) instead of
+ * today's plain `readline`-based `runCli()` loop. 'disabled' (the default, for this plan's
+ * whole rollout window, per `DEFAULT_TUI_MODE`) means `main()` behaves exactly as it does
+ * today, byte-for-byte — the Ink shell is never constructed. 'enabled' only takes effect when
+ * `main()` also confirms a real interactive TTY on both stdio streams (see cli.ts); it never
+ * affects `runCli()` when called directly with test-only options, since that call site is
+ * `cli.test.ts`/`non-interactive-mode.ts`'s own, not `main()`'s.
+ */
+export type TuiMode = 'enabled' | 'disabled';
+export declare const DEFAULT_TUI_MODE: TuiMode;
+/**
+ * Value-level resolver: `resolveTuiMode` (CLI, reads `process.env.ASSISTANT_TUI`). Unlike
+ * `oneLoopMode`/`askMode`/`planMode`, this flag has no browser-facing analog (chat-ui/desktop
+ * have no terminal to pin input to), so there's no `envOverridesFromImportMetaEnv` counterpart.
+ * An unset or empty value falls back to the default silently; an unrecognized non-empty value
+ * falls back with a startup warning naming `varName` — same typo-tolerance-with-a-warning
+ * convention `normalizeOneLoopMode`/`normalizeAskMode`/`normalizePlanMode` use.
+ */
+export declare function normalizeTuiMode(raw: string | undefined, varName?: string): TuiMode;
+export declare function resolveTuiMode(env: NodeJS.ProcessEnv): TuiMode;
+/**
+ * The full gate `cli.ts`'s `main()` applies before ever constructing the Ink shell — split out
+ * as a pure function so the decision is unit-testable without a real pty. `tuiMode === 'enabled'`
+ * alone isn't sufficient: a piped/scripted invocation (`printf 'msg\nexit\n' | node dist/cli.js`,
+ * this repo's own documented headless workflow, or a real CI/non-interactive shell) must always
+ * fall through to the plain `readline` loop regardless of the flag, since Ink's raw-mode input
+ * has nothing to attach to without a real TTY on both streams.
+ */
+export declare function shouldLaunchTuiApp(tuiMode: TuiMode, stdoutIsTty: boolean, stdinIsTty: boolean): boolean;

package/dist/tui-output-capture.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One classified write, mirroring the three writer patterns `cli.ts` already uses (see that
+ * file's `writeProgress`/`clearProgress`, `writeToolStep`, `writeToken`) — not a new convention,
+ * just naming what's already there so Phase 3's Ink shell can route each kind to the right
+ * region (transient status line, transient streamed-reply buffer, permanent scrollback).
+ */
+export type CaptureEvent = {
+    /** `writeProgress`'s `\r`-overwritten step counter, or `clearProgress`'s blank-out of it. */
+    type: 'progress';
+    /** The current progress text with the `\r` control character and `padEnd` filler removed — `''` once cleared. */
+    text: string;
+} | {
+    /** `writeToken`'s raw incremental streamed characters — no trailing newline until the turn ends. */
+    type: 'token';
+    text: string;
+} | {
+    /** A `console.log`/`console.error` call, or any write that completes with a trailing newline — one or more committed, permanently-scrolled lines. */
+    type: 'line';
+    lines: string[];
+    /** Which global function produced this — `'stderr'` only for `console.error`, everything else (`console.log`, raw `process.stdout.write`) is `'stdout'`. Lets a consumer (Phase 3's `EventLogBridge`) style error output distinctly without guessing from content. */
+    stream: 'stdout' | 'stderr';
+};
+/**
+ * Monkey-patches `console.log`, `console.error`, and `process.stdout.write` for the duration of
+ * the interactive Ink session, classifying every write via {@link classify} and routing it to
+ * `onEvent` instead of the real terminal — Ink owns the frame once this is active (Decision 1:
+ * every command handler still calls the same global functions unmodified). Returns a restore
+ * function that puts the originals back; call it on exit and in every test's `afterEach`.
+ */
+export declare function startCapture(onEvent: (event: CaptureEvent) => void): () => void;

package/dist/tui-spike.d.ts

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

package/dist/turn-intent-classifier.d.ts

@@ -0,0 +1,96 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { DecomposedTaskSpec } from './decomposition-classifier.js';
+/**
+ * 'UNKNOWN' is never produced by a successful classification (TURN_INTENT_SCHEMA's riskLevel enum
+ * only ever allows LOW/MEDIUM/HIGH from the model) — it exists solely as failSafeClassification's
+ * fail-safe value, so callers can route a classifier failure to their most conservative branch
+ * instead of silently treating it as LOW risk. See failSafeClassification's doc comment.
+ */
+export type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'UNKNOWN';
+/** Only meaningful for `source: 'model_inferred'` facts — see fact-extraction.ts's `UserFact`. */
+export type FactConfidence = 'high' | 'medium' | 'low';
+/**
+ * Fixed enum, not free text, so the pending-confirmation queue (Phase 3 of
+ * plans/personal_assistant_fact_extraction_llm_confidence_plan.html) can group entries stably
+ * instead of drifting between synonyms ("job"/"occupation"/"work") for the same underlying topic.
+ */
+export type FactCategory = 'identity' | 'health' | 'preference' | 'location' | 'occupation' | 'relationships' | 'project' | 'other';
+export interface StatedFact {
+    text: string;
+    durable: boolean;
+    confidence: FactConfidence;
+    category: FactCategory;
+}
+export interface TurnIntentContext {
+    /** Whether an active durable plan exists for this session — gates whether the abandon
+     *  judgment means anything and whether plan-template matching should even be attempted
+     *  (mirrors assistant.ts's own `if (activePlan) { ... } else { match a template } ` split). */
+    hasActivePlan: boolean;
+}
+export interface TurnIntentClassification {
+    riskLevel: RiskLevel;
+    riskReason: string;
+    /** Computed here from riskLevel/isBulkReminderRequest for trace/display purposes and any
+     *  caller that only wants the raw classifier verdict. Phase D3: no gating call site reads this
+     *  field directly anymore — turn-interpreter.ts's approval gate and assistant.ts's
+     *  execution-mode classification both recompute the decision from riskLevel/isBulkReminderRequest
+     *  via turn-policy.ts's evaluateTurnPolicy() instead, so a future bug here can't silently change
+     *  what those care about (INV-14). */
+    requiresApproval: boolean;
+    /** Only meaningful when riskLevel === 'LOW' — same precondition classifyTriviality had. */
+    isTrivial: boolean;
+    decomposedTasks: DecomposedTaskSpec[] | null;
+    /** True when the request asks to create a calendar/reminder entry (regardless of how many). */
+    isReminderRequest: boolean;
+    /** True when isReminderRequest is true AND the request looks like it may create more than one
+     *  reminder in a single turn — same signal risk-classifier.ts's BULK_REMINDER_REASON gated on,
+     *  folded into requiresApproval the same way. Always false when isReminderRequest is false. */
+    isBulkReminderRequest: boolean;
+    /** Only meaningful when context.hasActivePlan is true. */
+    isAbandonRequest: boolean;
+    /** One of listTemplateNames()'s names, or null. Only ever set when context.hasActivePlan is false. */
+    matchedPlanTemplate: string | null;
+    /**
+     * P3 of plans/ask_question_and_plan_mode_plan.html — the generalized, domain-general
+     * counterpart to matchedPlanTemplate: true when the request warrants a durable, tracked,
+     * user-approved plan even though it doesn't match one of the 7 named template kinds (e.g. a
+     * code-implementation request spanning several files/tests). Always false when
+     * matchedPlanTemplate is already set (a template match is itself one flavor of "needs a
+     * plan" — callers should treat `matchedPlanTemplate !== null || needsMultiStepPlan` as the
+     * combined trigger) and always false when context.hasActivePlan is true, same gating
+     * matchedPlanTemplate already uses.
+     */
+    needsMultiStepPlan: boolean;
+    /**
+     * Every durable/session fact the message states about the user (name, preference,
+     * health/dietary, current location/job, ...) — the LLM-backed primary extraction path this
+     * plan builds (plans/personal_assistant_fact_extraction_llm_confidence_plan.html Phase 1),
+     * superseding the old single-fact `statesDurableFact` fallback so a turn stating more than one
+     * fact ("I'm Priya, I'm vegetarian, and I live in Austin") isn't truncated to one. `confidence`
+     * is anchored to an observable criterion, not a bare self-report: `high` = stated directly and
+     * unhedged in first person; `medium` = stated about the user but hedged, indirect, or inferred
+     * from context; `low` = a weak inference, or primarily about a third party and only tangentially
+     * about the user. `durable`'s contract is unchanged from the old field: true only for
+     * identity/safety-relevant facts meant to persist indefinitely, false for something expected to
+     * change. Empty array (not null) when nothing was stated, including on classifier failure — see
+     * failSafeClassification.
+     */
+    statesDurableFacts: StatedFact[];
+}
+/**
+ * Runs the single consolidated LLM call every turn (replacing the old lexical-gate-then-maybe-
+ * LLM-call chain) and derives all seven downstream judgments from one structured response. Falls
+ * back to failSafeClassification's conservative defaults on any parse failure or LLM error:
+ * UNKNOWN risk requiring approval / not trivial / no decomposition / no abandon / no template
+ * match / no stated fact — i.e. "do the careful thing" (run the full harness, require approval
+ * rather than guessing LOW, don't auto-abandon, return no stated facts when the call failed).
+ * Per-task riskLevel (Phase 1 of plans/lexical_functions_hardening_plan.html) is this call's
+ * LLM-backed backstop for what used to be a pure-lexical, no-fallback judgment —
+ * risk-classifier.ts's standalone per-task classifyRisk — which stays as the free, zero-latency
+ * first check; this call is only trusted when it finds nothing (see assistant.ts's call site).
+ * statesDurableFacts (Phase 1 of
+ * plans/personal_assistant_fact_extraction_llm_confidence_plan.html) is, as of that plan, the
+ * *primary* fact-extraction path rather than a fallback — see that plan for how memory-service.ts
+ * merges it with fact-extraction.ts's regex backstop.
+ */
+export declare function classifyTurnIntent(message: string, llmClient: ILLMClient, context: TurnIntentContext, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<TurnIntentClassification>;

package/dist/turn-interpreter.d.ts

@@ -0,0 +1,71 @@
+import { Task } from '@buildaharness/harness';
+import { ILLMClient, TokenUsage, ReminderStore } from '@buildaharness/runtime';
+import { TurnIntentClassification } from './turn-intent-classifier.js';
+import { PlanRecord } from './plan-store.js';
+import { PlanService } from './plan-service.js';
+import { AssistantTurnResult } from './assistant-types.js';
+/**
+ * The front portion of runTurn — plan-cancel-bypass detection, the classifyTurnIntent call, the
+ * message-level risk-gate decision, and (via `resolveTasks`) decomposition/plan-template
+ * resolution — as a pure decision-maker. Deliberately no MemoryAdapter/onTrace dependency beyond
+ * what's passed as plain arguments/collaborators (PlanService, ReminderStore), so this stays
+ * unit-testable without heavy mocks. Does NOT append to the transcript or call onTrace itself —
+ * every variant below carries enough data for the sequencer (assistant.ts) to do both, in the
+ * exact order the pre-split code did.
+ */
+export type TurnInterpretation = {
+    kind: 'bypass';
+    result: AssistantTurnResult;
+    transcriptAppend: {
+        user: string;
+        assistant: string;
+    };
+    planUpdatedTrace: {
+        templateName: string | null;
+        completionPct: number;
+    };
+} | {
+    kind: 'needs_approval';
+    classification: TurnIntentClassification;
+    result: AssistantTurnResult;
+} | {
+    kind: 'proceed';
+    classification: TurnIntentClassification;
+    planForCancelCheck: PlanRecord | null;
+};
+export interface ResolvedTasks {
+    initialTasks: Task[];
+    activePlan: PlanRecord | null;
+    /** Only set when a NEW plan match was attempted this turn (i.e. no active plan was already being resumed) — mirrors the original code's `else` branch, which is the only place this trace fired. */
+    planClassifiedTrace?: {
+        isCandidate: boolean;
+        matchedTemplate: string | null;
+    };
+}
+export declare class TurnInterpreter {
+    private readonly llmClient;
+    private readonly model;
+    private readonly planService;
+    private readonly reminderStore;
+    constructor(llmClient: ILLMClient, model: () => string | undefined, planService: PlanService, reminderStore: ReminderStore);
+    interpretIntent(params: {
+        userMessage: string;
+        sessionId: string;
+        toolLoopWillRun: boolean;
+        approved: boolean;
+        dangerouslySkipPermissions: boolean;
+        onUsage: (usage: TokenUsage) => void;
+    }): Promise<TurnInterpretation>;
+    /**
+     * Decomposition/plan-template resolution — only meaningful (and only ever called by the
+     * sequencer) once a turn is known NOT to be trivial, since a trivial turn returns before any
+     * of this would matter and must not spend buildPlanFromTemplate's LLM call for nothing.
+     */
+    resolveTasks(params: {
+        userMessage: string;
+        sessionId: string;
+        classification: TurnIntentClassification;
+        planForCancelCheck: PlanRecord | null;
+        onUsage: (usage: TokenUsage) => void;
+    }): Promise<ResolvedTasks>;
+}

package/dist/turn-policy.d.ts

@@ -0,0 +1,45 @@
+import { RiskLevel } from './turn-intent-classifier.js';
+/**
+ * Phase D3 (plans/harness_consolidation_and_control_plane_plan.html, A3): the deterministic,
+ * authoritative decision point for whether a turn's message-level risk requires human approval
+ * before the turn proceeds — the message-level analog of tool-policy.ts's evaluateToolPolicy().
+ *
+ * turn-intent-classifier.ts's own `requiresApproval` field is computed from the same
+ * riskLevel/isBulkReminderRequest signals and still exists for trace/display purposes, but no
+ * gating call site should read that boolean directly — TurnPolicyInput deliberately has no
+ * `requiresApproval` field to read, so a gate built on this module always recomputes the decision
+ * from the underlying signals rather than trusting a pass-through boolean (INV-14: a consequential
+ * decision cannot be set by LLM output alone). See turn-interpreter.ts and assistant.ts's
+ * classifyAndTraceExecutionMode call sites for where this replaces a direct
+ * `classification.requiresApproval` read.
+ */
+export type TurnPolicyDecision = 'ALLOW' | 'REQUIRE_APPROVAL';
+export interface TurnPolicyInput {
+    /** turn-intent-classifier.ts's RiskLevel — a signal, never itself the gate (same contract
+     *  tool-policy.ts's ToolPolicyInput.riskHint documents). */
+    riskHint: RiskLevel;
+    /** turn-intent-classifier.ts's own isBulkReminderRequest verdict — only meaningful alongside a
+     *  MEDIUM riskHint (see turn-intent-classifier.ts), but read here unconditionally since a
+     *  MEDIUM-only precondition on this field is itself already enforced upstream. */
+    isBulkReminderRequest: boolean;
+}
+export interface TurnPolicyResult {
+    decision: TurnPolicyDecision;
+    reason: string;
+}
+export declare function evaluateTurnPolicy(input: TurnPolicyInput): TurnPolicyResult;
+export interface AbandonPolicyInput {
+    /** Structural fact — an active durable plan record actually exists for this session,
+     *  independent of anything the LLM said this turn. */
+    hasActivePlan: boolean;
+    /** turn-intent-classifier.ts's isAbandonRequest verdict — a signal, never itself sufficient:
+     *  an LLM claiming "abandon the plan" means nothing when no plan is actually active. */
+    abandonHint: boolean;
+}
+/**
+ * The deterministic gate for plan abandonment: `abandonHint` alone is never enough — it only
+ * takes effect when `hasActivePlan` (independent of the LLM call) is also true. Centralizes the
+ * same check turn-intent-classifier.ts and turn-interpreter.ts each already performed inline, so
+ * it's asserted once, not maintained in two places that could drift apart.
+ */
+export declare function evaluateAbandonPolicy(input: AbandonPolicyInput): boolean;

package/dist/web-fetch-core.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Runtime-agnostic SSRF guard + safe-fetch core used by web-tools.ts (desktop/CLI path). Split
+ * out of web-tools.ts so the guard/redirect/byte-cap logic is one focused module instead of
+ * living inline in the tool executor.
+ *
+ * packages/proxy/src/web-fetch.ts (POST /web/fetch, W2) intentionally carries its own copy of
+ * this guard rather than importing this module as a workspace dependency — same call W1's
+ * web-search.ts already made for the search parsing code: this package's only `exports` entry is
+ * the whole `dist/index.js` bundle (nodemailer, the MCP SDK, the CLI), and this repo's proxy CI
+ * job (and this plan's own suggested gate script) typechecks/tests packages/proxy without a
+ * `build:personal-assistant` step first, so a real cross-package import isn't actually wired up
+ * to build here. Keep the two guards in sync by hand if one changes — same discipline the ported
+ * DDG/Brave search code in web-search.ts already requires.
+ */
+/**
+ * Thrown by assertPublicHttpUrl instead of returning a falsy value, so callers
+ * can't accidentally proceed past a rejected URL.
+ */
+export declare class PrivateNetworkTargetError extends Error {
+    readonly requestedUrl: string;
+    readonly detail: string;
+    constructor(requestedUrl: string, detail: string);
+}
+/** Thrown when the fetched body's content-type (header and/or sniffed bytes) isn't on the allowlist. */
+export declare class UnsupportedContentTypeError extends Error {
+    readonly requestedUrl: string;
+    readonly detail: string;
+    constructor(requestedUrl: string, detail: string);
+}
+/** Resolves a hostname to its IP addresses. Injected so assertPublicHttpUrl stays unit-testable without real DNS/network access. */
+export type DnsResolver = (hostname: string) => Promise<string[]>;
+/**
+ * Parses `url`, rejects non-http(s) schemes / credentialed URLs / non-80/443 ports / raw IP
+ * literals outright (all before any DNS call), then resolves the hostname and throws
+ * PrivateNetworkTargetError if any resolved address is loopback, RFC1918 private, link-local,
+ * or a well-known cloud metadata address. Must be called again on every redirect hop — a public
+ * URL can 302 to a private one — which is exactly what fetchTextSafely's redirect loop below does.
+ */
+export declare function assertPublicHttpUrl(url: string, dns?: DnsResolver): Promise<void>;
+export declare const MAX_REDIRECTS = 5;
+export declare const MAX_FETCH_CHARS = 15000;
+export interface FetchTextSafelyOptions {
+    url: string;
+    dns?: DnsResolver;
+    fetchImpl?: typeof fetch;
+    maxBytes?: number;
+    maxRedirects?: number;
+    allowedContentTypes?: string[];
+    timeoutMs?: number;
+}
+export interface FetchTextSafelyResult {
+    text: string;
+    finalUrl: string;
+    /** True if either the streamed byte cap or the char-level cap truncated the returned text. */
+    truncated: boolean;
+}
+/**
+ * Fetches `options.url`, following redirects manually (not via fetch's automatic redirect-follow)
+ * so every hop gets its own assertPublicHttpUrl check — a public URL that 302s to a private
+ * target is rejected mid-fetch, not silently followed. Enforces a streamed byte cap (a
+ * Content-Length header can lie), a content-type allowlist (checked against both the header and
+ * the sniffed body bytes), and a connect+read timeout. Sends a fixed User-Agent and nothing else
+ * client-supplied — zero ambient authority, safe to run on a caller's behalf server-side.
+ */
+export declare function fetchTextSafely(options: FetchTextSafelyOptions): Promise<FetchTextSafelyResult>;

package/dist/web-search-provider.d.ts

@@ -0,0 +1,12 @@
+import { WebSearchResult } from './web-tools.js';
+export interface BraveSearchOptions {
+    maxResults?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Queries the Brave Search API and returns a bounded, parsed result list. Matches
+ * WebToolsContext['search']'s signature. Requires a Brave Search API key — see
+ * https://api.search.brave.com/app/keys — passed as `apiKey`, sent as the
+ * `X-Subscription-Token` header Brave's API expects.
+ */
+export declare function braveSearch(query: string, apiKey: string, options?: BraveSearchOptions): Promise<WebSearchResult[]>;

package/dist/web-tools.d.ts

@@ -0,0 +1,26 @@
+import { ToolDefinition } from '@buildaharness/runtime';
+import { DnsResolver } from './web-fetch-core.js';
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export { PrivateNetworkTargetError, assertPublicHttpUrl } from './web-fetch-core.js';
+export type { DnsResolver } from './web-fetch-core.js';
+export interface WebToolsContext {
+    /** No default implementation — the caller supplies a real search backend (an API client, etc.), same way FileToolsContext's `backend` is injected rather than defaulted to real disk. See `braveSearch` in web-search-provider.ts for a ready-made one. */
+    search(query: string): Promise<WebSearchResult[]>;
+    /** Overrides the HTTP client fetch_url uses — defaults to the global `fetch`. Lets tests and non-browser runtimes inject their own. */
+    fetchImpl?: typeof fetch;
+    /** Injected DNS resolver for the SSRF guard below — defaults to a lazily-imported node:dns/promises. Tests inject a fake to avoid real network access. */
+    dns?: DnsResolver;
+}
+export declare const WEB_SEARCH_TOOL: ToolDefinition;
+export declare const FETCH_URL_TOOL: ToolDefinition;
+export declare const WEB_TOOLS: ToolDefinition[];
+export type WebToolResult = {
+    kind: 'text';
+    text: string;
+};
+/** Executes web_search/fetch_url. Both return raw, untagged text — trust-tagging is applied by the caller (assistant.ts), not here, so this stays a plain I/O layer like executeFileTool. */
+export declare function executeWebTool(ctx: WebToolsContext, toolName: string, input: Record<string, unknown>): Promise<WebToolResult>;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@buildaharness/aielia",
+  "version": "0.3.0",
+  "description": "An open-source AI chat assistant that runs the full 11-layer Build A Harness every turn — light for a fact lookup, and it stops for approval before it sends an email or runs a shell command. CLI, browser, and desktop.",
+  "license": "Apache-2.0",
+  "homepage": "https://buildaharness.com/personal-assistant",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/3IVIS/buildaharness.git",
+    "directory": "packages/aielia"
+  },
+  "keywords": [
+    "aielia",
+    "ai-assistant",
+    "personal-assistant",
+    "chat-agent",
+    "agent-harness",
+    "human-in-the-loop",
+    "tool-approval",
+    "self-hosted",
+    "llm",
+    "openclaw-alternative",
+    "open-source"
+  ],
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "aielia": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build --config vite.config.lib.ts && cp src/file-tools-mcp-server.mjs dist/file-tools-mcp-server.mjs && mkdir -p dist/lexical/patterns && cp src/lexical/patterns/*.json dist/lexical/patterns/ && node -e \"const f='dist/cli.js',s=require('fs'),c=s.readFileSync(f,'utf8');if(!c.startsWith('#!'))s.writeFileSync(f,'#!/usr/bin/env node\\n'+c)\"",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "cli": "tsx src/cli.ts",
+    "eval:turn-intent": "tsx scripts/eval-turn-intent.ts",
+    "eval:contradiction-checker": "tsx scripts/eval-contradiction-checker.ts",
+    "eval:harness-benchmark": "tsx scripts/run-harness-benchmark.ts"
+  },
+  "dependencies": {
+    "@buildaharness/harness": "^0.2.0",
+    "@buildaharness/runtime": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ink": "^7.1.1",
+    "nodemailer": "^6.9.14",
+    "react": "^19.3.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/nodemailer": "^6.4.15",
+    "@types/react": "^19.3.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.4.5",
+    "vite": "^5.3.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^1.6.0"
+  }
+}