@buildaharness/aielia 0.3.1 → 0.3.3

package/README.md

@@ -1,8 +1,11 @@
 # @buildaharness/aielia
 
-A general-purpose, everyday-use chat assistant that runs on the full 11-layer
-harness (`@buildaharness/harness`) every turn — light enough for "what's the
-weather" and consequential enough to gate "send that email" behind approval.
+A general-purpose, everyday-use AI agent you can hand real, multi-step work to —
+research across a list, files to go through, a message to draft and send. It runs
+on the full 11-layer harness (`@buildaharness/harness`) every turn, which controls
+what it may do, what it may believe, and what a job may cost — light enough for
+"what's the weather", and it stages anything that can't be undone (`write_file`,
+`run_shell_command`, `send_email`) for your approval. Website: https://myaielia.com.
 
 ## Design
 
@@ -13,7 +16,7 @@ policy-governed gates decide what's actually allowed to happen — see
 ADR-003 (harness consolidation) for the 5-primitive model this
 assistant's design is one instance of. **As of 2026-09-06 the tool loop
 runs inside the harness by default** (`ASSISTANT_ONE_LOOP`, default
-`enabled` — `plans/harness_d2_one_loop_rewire_plan.html`): `HarnessRuntime`'s
+`enabled` — the internal plan): `HarnessRuntime`'s
 own `driveMainLoop` calls `AgentLoop`'s tool-calling machinery one iteration
 at a time, and the per-tool-call gate composes the harness's own live
 `ControlState` with the turn-local one accumulated from this turn's prior
@@ -96,7 +99,7 @@ silently starting over.
 
 Net effect: one real LLM call per ordinary turn, zero for a blocked one, and
 every layer of the harness touched on the ones that do run — matching what
-[buildaharness.com/harness-comparison](https://buildaharness.com/harness-comparison)
+[myaielia.com/harness-comparison](https://myaielia.com/harness-comparison)
 calls out as missing from Hermes Agent, Kilo Code, and OpenClaw: none of them
 ships a formal Control State resolver *and* a Reviewer/output gate together.
 <!--
@@ -367,7 +370,7 @@ follow-up `needs_clarification` batch if it's still unresolved once the first ba
 folded in, resolved through this exact same path.
 
 Two kinds of sites can raise a `questions` batch: the Trajectory Supervisor's `ASK_USER` directive
-(see `docs/adr/005-trajectory-supervisor.md` — currently inert by default, since
+(see ADR-005 — currently inert by default, since
 `HARNESS_TRAJECTORY_SUPERVISOR` stays off) and a handful of deterministic sites with a genuinely
 enumerable option set, e.g. a batch-research budget running out ("continue with N more steps" /
 "stop and summarize" / "let me clarify the goal"). A site with no discrete option set keeps
@@ -382,7 +385,7 @@ time, or a per-`turn()` `{ askMode: 'enabled' }` override — following `oneLoop
 env/build-time/per-call chain. The effective mode is always the most restrictive of (global
 config, per-session override, per-call-site opt-out): a narrower scope can turn structured
 questions off even when a broader one left them on, never the reverse. See
-`docs/adr/006-generic-ask-question-mechanism.md` for the full design and why the default hasn't
+ADR-006 for the full design and why the default hasn't
 flipped to `'enabled'` yet — the mechanism and its conformance suite are done, but the benchmark
 run that would justify the flip hasn't happened.
 
@@ -549,7 +552,7 @@ that opens raw sockets and ignores those env vars entirely. That tradeoff —
 weaker than real OS-native sandboxing (Linux seccomp/landlock, macOS
 `sandbox-exec`, Windows job objects) or a container-per-command, but
 identical across the CLI and the Tauri desktop app with no new dependency —
-is deliberate; see `plans/lexical_functions_hardening_plan.html`'s Decision 6
+is deliberate; see the internal plan's Decision 6
 for the full comparison.
 
 **The command's output gets the same trust boundary as `fetch_url`/`web_search`.**
@@ -664,6 +667,26 @@ piped-stdin case an intentional choice instead of an implicit one. An
 unrecognized value is ignored, with a startup warning, rather than silently
 picking one of the two behaviors for you.
 
+#### Updates and the update check
+
+`aielia --version` / `aielia --help` print and exit. `aielia update` replaces the
+**standalone binary** with the latest release (`aielia update --dry-run` only
+reports what it would do): it downloads the binary for your platform, verifies
+its SHA-256 against the hash published in the release manifest at
+`https://myaielia.com/aielia-latest.json` (HTTPS only — anything else is
+refused), and only then swaps it in. A copy installed with npm can't
+self-replace, so there it prints `npm update -g @buildaharness/aielia` instead.
+
+While an interactive session starts, the CLI also does a **passive update
+check**: at most once per 24 hours, one plain `GET` of that manifest (falling
+back to GitHub's Releases API) — no query string, no identifiers, default
+User-Agent only — and, if a newer version exists, a one-line notice. The request
+is visible to GitHub and Cloudflare (which serve myaielia.com). It never runs
+for scripted use (stdin not a TTY, or `ASSISTANT_NON_INTERACTIVE_APPROVAL` set).
+Turn it off with `ASSISTANT_UPDATE_CHECK=disabled` or
+`/config set updateCheck disabled`; the explicit `aielia update` still works
+with it off.
+
 #### Web search needs a Brave Search API key
 
 Brave Search is the only backend `web_search` supports. Enable web tools with

package/dist/agent-loop.d.ts

@@ -26,7 +26,7 @@ export type ToolLoopResult = {
     reason: string;
 };
 /**
- * R2 of plans/harness_d2_one_loop_rewire_plan.html: thrown by a harness-driven proposer
+ * R2 of the internal plan: thrown by a harness-driven proposer
  * (createHarnessProposer, below) when runToolIterationStep produces a 'needs_approval' or
  * 'escalated' ToolLoopResult — the harness's own execute() rethrows anything satisfying
  * isHarnessPauseSignal unexamined (no SYSTEM_ERROR evidence, no task-FAILED transition), so this
@@ -40,7 +40,7 @@ export declare class OneLoopPause extends Error implements HarnessPauseSignal {
         kind: 'needs_approval' | 'escalated';
     }>;
     /**
-     * P10 of plans/ask_question_and_plan_mode_plan.html: the plan task (if any) that was RUNNING
+     * P10 of the internal plan: the plan task (if any) that was RUNNING
      * — i.e. whichever task `execute()` was calling this proposer for — when `result` was
      * produced, threaded from `ToolExecutorContext.currentTaskId`. Lets the catcher
      * (assistant.ts's `buildToolLoopPauseResult`) check INV-36's trust condition without
@@ -54,7 +54,7 @@ export declare class OneLoopPause extends Error implements HarnessPauseSignal {
         kind: 'needs_approval' | 'escalated';
     }>, 
     /**
-     * P10 of plans/ask_question_and_plan_mode_plan.html: the plan task (if any) that was RUNNING
+     * P10 of the internal plan: the plan task (if any) that was RUNNING
      * — i.e. whichever task `execute()` was calling this proposer for — when `result` was
      * produced, threaded from `ToolExecutorContext.currentTaskId`. Lets the catcher
      * (assistant.ts's `buildToolLoopPauseResult`) check INV-36's trust condition without
@@ -164,7 +164,7 @@ export declare class AgentLoop {
      */
     createControlPlaneState(): TurnControlPlaneState;
     /**
-     * R2 of plans/harness_d2_one_loop_rewire_plan.html: builds the real toolExecutors['default']
+     * R2 of the internal plan: builds the real toolExecutors['default']
      * entry HarnessBridge.run() swaps in when the one-loop flag is enabled — a proposer that calls
      * runToolIterationStep once per driveMainLoop iteration and translates its discriminated result
      * into the primitives D0/D1 already built: a plain return (status 'continue', no output yet) for
@@ -198,7 +198,7 @@ export declare class AgentLoop {
         riskHint?: TurnIntentClassification['riskLevel'];
     }): (toolCtx: ToolExecutorContext) => Promise<unknown>;
     /**
-     * R3 of plans/harness_d2_one_loop_rewire_plan.html: the wiring-level counterpart to
+     * R3 of the internal plan: the wiring-level counterpart to
      * `createHarnessProposer` above — builds the same `messages`/`tools` shape `runToolLoop` builds
      * (system prompt + transcript + user message; whichever of FILE_TOOLS/WEB_TOOLS/SHELL_TOOLS/
      * ACTION_TOOLS/REMINDER_TOOLS are configured) so `assistant.ts`'s `runTurn` doesn't need to
@@ -213,7 +213,7 @@ export declare class AgentLoop {
         sources: AssistantSource[];
     };
     /**
-     * R4 of plans/harness_d2_one_loop_rewire_plan.html: the batch-research counterpart to
+     * R4 of the internal plan: the batch-research counterpart to
      * `createOneLoopProposer` above — routes `runBatchToolLoop`'s probe → calibrate → confirm-gate
      * → resolve-remaining → synthesize sequence through the same harness-driven proposer mechanism,
      * instead of batch research remaining a second code path that (per R3) never reached the
@@ -280,7 +280,7 @@ export declare class AgentLoop {
     private runToolIterations;
     /**
      * One iteration's worth of `runToolIterations`' ReAct loop, extracted (R1 of the D2
-     * one-loop-rewire follow-up plan, `plans/harness_d2_one_loop_rewire_plan.html`) so a
+     * one-loop-rewire follow-up plan, the internal plan) so a
      * harness-driven proposer (R2) can call this directly, once per `driveMainLoop` iteration,
      * instead of only ever being driven by `runToolIterations`' own `for` loop. Preserves every
      * early-return branch of the original loop body exactly — the unparsed-tool-call retry,
@@ -350,7 +350,7 @@ export declare class AgentLoop {
     private executeToolCall;
     /**
      * Trajectory Supervisor GATHER_EVIDENCE host (S5 of
-     * plans/harness_trajectory_supervisor_plan.html). A bounded, strictly read-only tool
+     * the internal plan). A bounded, strictly read-only tool
      * loop the harness calls (via HarnessRunOptions.runInvestigation) when the supervisor
      * decides the run is stuck for lack of a fact.
      *

package/dist/ask-clarification-service.d.ts

@@ -25,7 +25,7 @@ export interface AskClarificationPendingState {
 }
 /**
  * Owns the ask-question "staged clarification, resolved by ID" pattern — Q2 of
- * plans/ask_question_and_plan_mode_plan.html, structurally mirroring ActionApprovalService (T4 of
+ * the internal plan, structurally mirroring ActionApprovalService (T4 of
  * the file-tools plan: what gets resolved is exactly what was staged, never re-derived from a
  * second LLM call). Unlike a write/shell action, resolving a clarification means resuming a
  * *harness run* — the checkpoint HarnessBridge would otherwise have deleted on any thrown

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

@@ -3,7 +3,7 @@
  * unit-testable in isolation, mirroring one-loop-flag.ts's exact shape (module-level default,
  * an injectable resolver so tests never touch real process.env).
  *
- * Q2 of plans/ask_question_and_plan_mode_plan.html: the "global flag" control point (tier 1 of
+ * Q2 of the internal plan: the "global flag" control point (tier 1 of
  * Q1's three-tier INV-29 resolution) for the batched-questions ask-question mechanism, resolved
  * at this package's boundary and handed to `@buildaharness/harness`'s `resolveAskMode()` as
  * `globalEnabled`. 'disabled' (the default, for the whole rollout window, per Q1's

package/dist/assistant-session.d.ts

@@ -6,7 +6,7 @@ import { ShellToolsContext } from './shell-tools.js';
 import { ActionToolsContext } from './action-tools.js';
 import { SpendCapConfig, SpendState } from './spend-cap.js';
 /**
- * P1 of plans/ask_question_and_plan_mode_plan.html — session/turn-routing switch, distinct from a
+ * P1 of the internal plan — session/turn-routing switch, distinct from a
  * tool-permission list. While `active`, `assistant.ts`'s turn entry point routes every incoming
  * message for this session to `PlanDraftingService` instead of `TurnInterpreter`'s normal
  * classify/tool-loop pipeline (see PlanDraftingService's own doc comment for the two designed

package/dist/assistant-types.d.ts

@@ -29,7 +29,7 @@ export interface AssistantTrace {
 }
 /**
  * Which code path actually produced this turn's reply — a test/telemetry affordance for
- * plans/chat_ui_browser_e2e_plan.html phase B1 (the browser-e2e lane that unblocks the
+ * the internal plan phase B1 (the browser-e2e lane that unblocks the
  * ASSISTANT_ONE_LOOP default-flip, R5 of the D2 one-loop rewire). The reply text itself is
  * identical across all three by design (INV-19); this field is how a test asserts "the flag
  * changed which path ran" without diffing internal traces.
@@ -45,7 +45,7 @@ export interface AssistantTrace {
 export type ProposerKind = 'posthoc' | 'flat-oneloop' | 'batch-oneloop';
 export interface AssistantTurnResult {
     /**
-     * `needs_clarification` (Q2 of plans/ask_question_and_plan_mode_plan.html): a structured
+     * `needs_clarification` (Q2 of the internal plan): a structured
      * ask-question escalation (a populated `EscalationHalt.blocker.questions`, Q0) was staged for
      * resume via AskClarificationService instead of terminating the turn — pass
      * `pendingClarificationId` + a completed `AskResponse` back into
@@ -54,7 +54,7 @@ export interface AssistantTurnResult {
      * every escalation on the pre-existing `escalated`/`reply: null` path, byte-identical to today.
      */
     /**
-     * `needs_plan_approval` (P2 of plans/ask_question_and_plan_mode_plan.html): a drafted plan
+     * `needs_plan_approval` (P2 of the internal plan): a drafted plan
      * (plan mode's P1/P3) was staged for the mandatory whole-plan approval gate instead of
      * continuing to revise — pass `planApprovalId` back into
      * `turn(message, { planApprovalId, planDecision, edits? })` to resolve it. Every drafted plan

package/dist/assistant.d.ts

@@ -42,7 +42,7 @@ export interface TurnOptions {
     approved?: boolean;
     pendingActionId?: string;
     /**
-     * Q2 of plans/ask_question_and_plan_mode_plan.html — resolves a staged `needs_clarification`
+     * Q2 of the internal plan — resolves a staged `needs_clarification`
      * result (see AssistantTurnResult.pendingClarificationId) with the user's answer. Mirrors
      * `pendingActionId`/`approved`'s own "resolved by ID, never re-derived" shape:
      * `clarificationAnswer` must answer exactly the questions that were staged, validated
@@ -51,7 +51,7 @@ export interface TurnOptions {
     pendingClarificationId?: string;
     clarificationAnswer?: AskResponse;
     /**
-     * P2 of plans/ask_question_and_plan_mode_plan.html — resolves a staged `needs_plan_approval`
+     * P2 of the internal plan — resolves a staged `needs_plan_approval`
      * result (see AssistantTurnResult.planApprovalId) with the user's decision. Mirrors
      * `pendingActionId`/`approved`'s "resolved by ID, never re-derived" shape: what gets
      * approved/declined is exactly the plan that was staged, never re-drafted.
@@ -198,7 +198,7 @@ export interface PersonalAssistantOptions {
      */
     spendCap?: SpendCapConfig;
     /**
-     * R2 of plans/harness_d2_one_loop_rewire_plan.html — see one-loop-flag.ts's doc comment for the
+     * R2 of the internal plan — see one-loop-flag.ts's doc comment for the
      * full rollout rationale. 'disabled' (the default, for the whole R2-R4 rollout window): today's
      * behavior, byte-for-byte — HarnessBridge.run() always uses `() => draftReply` as its toolFn,
      * regardless of whether a caller happens to supply a proposer. 'enabled' lets a supplied
@@ -208,7 +208,7 @@ export interface PersonalAssistantOptions {
      */
     oneLoopMode?: OneLoopMode;
     /**
-     * Q2 of plans/ask_question_and_plan_mode_plan.html — global-flag control point (tier 1 of
+     * Q2 of the internal plan — global-flag control point (tier 1 of
      * INV-29) for the ask-question mechanism. Undefined (the default) falls back to
      * `DEFAULT_ASK_MODE` ('disabled') — today's behavior, byte-for-byte: every escalation stays on
      * the plain `escalated`/`reply: null` path. Only cli.ts/chat-ui's App.tsx (or an equivalent
@@ -218,7 +218,7 @@ export interface PersonalAssistantOptions {
      */
     askMode?: AskMode;
     /**
-     * P11 of plans/ask_question_and_plan_mode_plan.html — see plan-mode-flag.ts's doc comment for
+     * P11 of the internal plan — see plan-mode-flag.ts's doc comment for
      * the full rollout rationale. 'legacy' (the default, for the whole rollout window): P3's
      * judgment-based auto-trigger below never fires, so `turn()` never auto-enters plan mode's
      * exclusive drafting+approval loop — today's behavior, byte-for-byte, for every real user turn.
@@ -255,7 +255,7 @@ export declare class PersonalAssistant {
     private readonly dangerouslySkipPermissions;
     /** Whenever any of fileTools/webTools/shellTools is configured, `turn()` routes through AgentLoop instead of a single plain chat call — computed once here since it never changes for the lifetime of an instance. */
     private readonly toolLoopWillRun;
-    /** R3 of plans/harness_d2_one_loop_rewire_plan.html — mirrors the same flag HarnessBridge was given at construction, kept here too so runTurn can decide whether to defer the tool loop into a harness-driven proposer instead of precomputing draftReply. See PersonalAssistantOptions.oneLoopMode's doc comment. */
+    /** R3 of the internal plan — mirrors the same flag HarnessBridge was given at construction, kept here too so runTurn can decide whether to defer the tool loop into a harness-driven proposer instead of precomputing draftReply. See PersonalAssistantOptions.oneLoopMode's doc comment. */
     private readonly oneLoopMode;
     /** Q2 — global-flag tier of the ask-question mechanism's three-tier INV-29 resolution. See PersonalAssistantOptions.askMode's doc comment. */
     private readonly askMode;
@@ -266,7 +266,7 @@ export declare class PersonalAssistant {
      * AssistantTurnResult.proposerKind, and emitted as a 'proposer_selected' trace event from
      * runTurn itself. A single mutable field is safe because `turn()` is awaited end to end (turns
      * never overlap within one instance). See AssistantTurnResult.proposerKind and
-     * plans/chat_ui_browser_e2e_plan.html phase B1.
+     * the internal plan phase B1.
      */
     private lastProposerKind;
     private readonly memoryService;
@@ -309,7 +309,7 @@ export declare class PersonalAssistant {
     /** Ends the current conversation — see AssistantSession.clearSession's doc comment for exactly what is and isn't cleared. */
     clearSession(sessionId: string): Promise<void>;
     /**
-     * P1 of plans/ask_question_and_plan_mode_plan.html — explicit entry point into plan mode's
+     * P1 of the internal plan — explicit entry point into plan mode's
      * exclusive drafting state. No production caller yet: P3 will later set this automatically from
      * a judgment-based trigger ahead of TurnInterpreter's classification. Until then this is reached
      * only by a caller (a future `/plan` CLI command, or a test) that wants to exercise the drafting
@@ -322,7 +322,7 @@ export declare class PersonalAssistant {
         draftId: string;
     }>;
     /**
-     * P7 of plans/ask_question_and_plan_mode_plan.html — the raw current `PlanRecord` for this
+     * P7 of the internal plan — the raw current `PlanRecord` for this
      * session, regardless of `mode`, so a caller (chat-ui's persistent banner, the CLI's `/plan
      * show`) can display live drafting/awaiting-approval state independent of any single turn's
      * own result (a `needs_plan_approval` result only carries a snapshot at the moment it's
@@ -331,7 +331,7 @@ export declare class PersonalAssistant {
      */
     getPlanState(sessionId: string): Promise<PlanRecord | null>;
     /**
-     * P9 of plans/ask_question_and_plan_mode_plan.html — the lightweight plan-sketch delegate: a
+     * P9 of the internal plan — the lightweight plan-sketch delegate: a
      * cheaper "just go research and draft an approach" path than plan mode's durable task-graph
      * machinery (P0-P8), explicitly invoked (a CLI `/plan sketch <request>` command, a chat-ui
      * "Sketch a plan" action) rather than auto-triggered. Returns advice in the reply text — it
@@ -376,7 +376,7 @@ export declare class PersonalAssistant {
     /**
      * `/memory confirm <n|category>` — `selector` is either a 1-based index into `/memory`'s
      * flat, display-order "Pending confirmation" listing, or one of FactCategory's names for a
-     * bulk confirm. Phase 3 of plans/personal_assistant_fact_extraction_llm_confidence_plan.html.
+     * bulk confirm. Phase 3 of the internal plan.
      * `conflictNotices` (if any) are advisory only — every confirmed fact is promoted regardless,
      * matching how every other contradiction check in this codebase never gates belief admission.
      */
@@ -411,7 +411,7 @@ export declare class PersonalAssistant {
     /**
      * Shared by the flag-OFF flat/batch tool loop's own needs_approval/escalated ToolLoopResult and
      * the flag-ON harness-driven proposer's equivalent OneLoopPause (R3 of
-     * plans/harness_d2_one_loop_rewire_plan.html, see runTurn's two call sites) — "the model wants
+     * the internal plan, see runTurn's two call sites) — "the model wants
      * to write/run/send something" or "the tool loop gave up" means the same thing to the caller
      * regardless of which loop discovered it.
      */

package/dist/batch-research-fixtures.d.ts

@@ -2,7 +2,7 @@ import { LLMStructuredResponse } from '@buildaharness/runtime';
 import { WebSearchResult } from './web-tools.js';
 /**
  * The real school-dates comparison this plan is built on (see
- * plans/personal_assistant_dynamic_tool_budget_plan.html's Reference Transcripts tab), encoded as
+ * the internal plan's Reference Transcripts tab), encoded as
  * a reusable scripted-LLM-response fixture instead of duplicated inline in assistant.test.ts —
  * so the integration replay test stays traceable back to the actual incident that motivated this
  * plan, and any recalibration of thresholds later has the real shape to check against.

package/dist/benchmark-injected-failure.d.ts

@@ -18,7 +18,7 @@ export interface InjectedFailureOptions {
      * injected into this turn). The benchmark reads it back as `ArmTurnOutput.injectedFailureFired`
      * so `recoveryRate` only counts tasks where the failure genuinely fired for this arm — not
      * every task that merely *declares* an `injectedFailure` (see
-     * plans/feature_audit_fair_comparison_plan.html F2).
+     * the internal plan F2).
      */
     onInjected?: () => void;
 }