@buildaharness/aielia 0.3.4 → 0.3.5

package/dist/lexical/lexical-mode.d.ts

@@ -0,0 +1,29 @@
+export declare const LEXICAL_FAMILIES: readonly ["fact-markers", "coding-fact", "injection", "enumeration", "risk", "task-cancel", "plan-mode", "batch-list", "tool-yield", "template-keywords"];
+export type LexicalFamily = (typeof LEXICAL_FAMILIES)[number];
+/** The families `lexicalMode: 'disabled'` (the default) switches off: all of them. */
+export declare const LEXICAL_CHECK_FAMILIES: readonly LexicalFamily[];
+export type LexicalMode = 'enabled' | 'disabled';
+export declare const DEFAULT_LEXICAL_MODE: LexicalMode;
+type EnvLike = Record<string, string | undefined>;
+export declare function isLexicalFamily(v: string): v is LexicalFamily;
+/** Unset/empty ⇒ default silently; an unrecognized value ⇒ default with a warning. */
+export declare function resolveLexicalMode(env?: EnvLike): LexicalMode;
+/** Every family currently switched off: named in OFF, or not named in ON while the mode is disabled. */
+export declare function resolveLexicalOff(env?: EnvLike): ReadonlySet<LexicalFamily>;
+/** True only if this family is switched on. */
+export declare function lexicalActive(family: LexicalFamily, env?: EnvLike): boolean;
+/**
+ * The off families as a comma list, for handing to an out-of-process helper (the MCP server). Always
+ * pass it, even empty: the helper reads an unset variable as "every family off" (the default) and an
+ * empty one as "none off".
+ */
+export declare function lexicalOffEnvValue(env?: EnvLike): string;
+/**
+ * Hands this mode to the harness package's own lexical switch (`setHarnessLexicalMode`), so
+ * `ASSISTANT_LEXICAL_MODE=enabled` turns the harness's checks back on too. Works in a browser as well
+ * as in Node (it sets no environment variable), and an explicit HARNESS_LEXICAL_MODE /
+ * HARNESS_LEXICAL_ON / HARNESS_LEXICAL_OFF still wins inside the harness. Called at the start of every
+ * harness run.
+ */
+export declare function syncHarnessLexicalEnv(env?: EnvLike): void;
+export {};

package/dist/memory-consolidation.d.ts

@@ -0,0 +1,80 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { UserFact } from './fact-extraction.js';
+/**
+ * Memory consolidation and staged forgetting (M5 of the agent memory framework plan).
+ *
+ * Pure pieces only: the flag, the retention window, the bounded model pass that PROPOSES changes, and
+ * the deterministic archive-candidate rule. Applying a proposal lives in MemoryService (the only
+ * place allowed to write the durable store, through `commitDurable`). Nothing here writes anything.
+ *
+ * D2: no lexical similarity anywhere. Whether two facts overlap is the model's judgement; the only
+ * deterministic rule is on the usage fields M1 added (timestamps and counters), never on text.
+ */
+/** `AUDIT_MEMORY_CONSOLIDATION`: default OFF; `1/true/on/yes/enabled` enables. Read fresh each call. */
+export declare function memoryConsolidationEnabled(env?: Record<string, string | undefined>): boolean;
+/** D4: retention window, start 90 days, to be calibrated. `AUDIT_MEMORY_RETENTION_DAYS` overrides (a positive number). */
+export declare const DEFAULT_MEMORY_RETENTION_DAYS = 90;
+export declare function memoryRetentionDays(env?: Record<string, string | undefined>): number;
+export type ProposalKind = 'merge' | 'supersede' | 'tighten' | 'archive';
+/** A staged change waiting for the user (`/memory consolidate accept|dismiss <n>`). Nothing here has been applied. */
+export interface ConsolidationProposal {
+    id: string;
+    kind: ProposalKind;
+    /** `text|extractedAt` ids of the durable facts the proposal touches. */
+    factIds: string[];
+    /** merge/tighten: the replacement wording. */
+    text?: string;
+    /** supersede: the id of the fact that replaces the retired ones in meaning (informational). */
+    by?: string;
+    reason: string;
+    createdAt: string;
+    /** True when any touched fact is `user_asserted`: the user said it themselves, so the UI must say so. */
+    touchesUserAsserted: boolean;
+}
+export interface ConsolidationState {
+    /** Highest audit seq already considered. The audit log's rotation keeps everything newer than this. */
+    lastSeq: number;
+    at?: string;
+    nextProposalNo?: number;
+    /** Signatures of proposals the user dismissed, so the same proposal is not raised again. */
+    dismissed?: string[];
+}
+export interface RawProposal {
+    kind: 'merge' | 'supersede' | 'tighten';
+    refs: string[];
+    text?: string;
+    by?: string;
+    reason: string;
+}
+export interface ConsolidationInput {
+    facts: Array<{
+        ref: string;
+        text: string;
+        source: string;
+        key?: string;
+        injectedCount?: number;
+        lastInjectedAt?: string;
+    }>;
+    recentChanges: Array<{
+        op: string;
+        text: string;
+    }>;
+    budget: {
+        usedChars: number;
+        budgetChars: number;
+    };
+}
+export declare const CONSOLIDATION_SYSTEM_PROMPT: string;
+/**
+ * One bounded call proposing merges, supersessions and tightenings. Returns the validated proposals,
+ * or `undefined` when the call failed or its answer was unusable (the caller then changes nothing,
+ * not even the watermark, so the next run retries). Anything the model returns that does not name
+ * real refs, repeats a ref, or has the wrong shape for its kind is dropped individually.
+ */
+export declare function proposeConsolidationOps(input: ConsolidationInput, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<RawProposal[] | undefined>;
+/**
+ * Deterministic archive rule over M1's usage fields, never over text: a live fact whose last sign of
+ * use (`lastInjectedAt`, else when it was stated) is older than the retention window. "Injected" means
+ * "was in the prompt", which is weaker than "was used"; the proposal says so rather than claiming usage.
+ */
+export declare function findArchiveCandidates(facts: UserFact[], nowMs: number, windowDays: number): UserFact[];

package/dist/memory-governance.d.ts

@@ -0,0 +1,30 @@
+import { UserFact } from './fact-extraction.js';
+/**
+ * M6 governance: WHERE a candidate memory write is allowed to land. Pure and structural: it reads
+ * the fact's own `source`/`confidence`/`durable` bits and the configured mode, never its wording
+ * (D2: no lexical checks). `MemoryService` is the only caller (`memoryWriteMode` is resolved in
+ * MemoryService only), so no writer can pick its own route.
+ *
+ * - `auto`      model-inferred in-turn facts follow today's confidence policy; cross-turn writers
+ *               (digest/reviewer/consolidation, M3/M4/M5) may add durable facts directly.
+ * - `staged`    (default, D1) in-turn writer keeps today's policy; every cross-turn writer is
+ *               staged in the pending queue. Nothing is auto-deleted.
+ * - `user_only` the model never creates a durable fact on its own: every model-inferred candidate
+ *               that would have been durable waits in the pending queue for `/memory confirm`.
+ *               Facts the user stated in their own words (`user_asserted`) are the user writing.
+ */
+export type MemoryWriteMode = 'auto' | 'staged' | 'user_only';
+export declare const MEMORY_WRITE_MODES: readonly MemoryWriteMode[];
+export declare const DEFAULT_MEMORY_WRITE_MODE: MemoryWriteMode;
+/**
+ * Which writer produced the candidate. `in_turn` is the classifier/lexical pass that already
+ * exists. The other three are EXTENSION POINTS owned by later phases: M3 digests (`digest`), M4's
+ * post-turn reviewer (`reviewer`), M5 consolidation proposals (`consolidation`). They are routed
+ * by `MemoryService.submitCandidate()` and are not built here.
+ */
+export type MemoryWriter = 'in_turn' | 'digest' | 'reviewer' | 'consolidation';
+export type CrossTurnWriter = Exclude<MemoryWriter, 'in_turn'>;
+export type WriteRoute = 'durable' | 'pending' | 'session';
+/** Unknown / absent values resolve to the default instead of throwing: a typo must never silently widen write authority. */
+export declare function resolveMemoryWriteMode(raw: unknown): MemoryWriteMode;
+export declare function resolveWriteRoute(mode: MemoryWriteMode, writer: MemoryWriter, fact: Pick<UserFact, 'source' | 'durable' | 'confidence'>): WriteRoute;

package/dist/memory-reviewer.d.ts

@@ -0,0 +1,114 @@
+import { ChatMessage, ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { MemoryService, StageReviewerResult } from './memory-service.js';
+import { UserFact, CandidateJudgement } from './fact-extraction.js';
+import { FactCategory } from './turn-intent-classifier.js';
+/**
+ * M4 of the agent memory framework plan: a post-turn, cross-turn memory reviewer. The in-turn writer already catches a
+ * fact stated in one message; the only thing this adds is aggregation across turns (a preference enforced by repetition,
+ * a decision that held). It reads the session's USER messages only (the injected memory block stripped), proposes typed
+ * operations, has each judged by a bounded semantic verifier, and hands the survivors to `MemoryService.stageReviewerOps`,
+ * which stages them in the pending queue with their evidence (decision D1). No keyword, regex or substring judgement of
+ * natural language anywhere here: language is judged by the two model calls, structure by plain code.
+ *
+ * Integration point for M3 (episodic digests): `ReviewerInput.digests` is accepted and passed to the reviewer as
+ * additional context but nothing populates it yet; M3's session-edge digest can feed it without changing this module.
+ */
+/** `AUDIT_MEMORY_REVIEWER`: default **OFF** (opt-in layer; M4 always ships off). `1`/`true`/`on`/`yes`/`enabled` enables. */
+export declare function memoryReviewerEnabled(env?: Record<string, string | undefined>): boolean;
+/** `AUDIT_MEMORY_REVIEWER_VERIFY`: the bounded verifier call. Default ON when the reviewer runs; a falsy value skips it (the negative control: ops are then staged unverified). */
+export declare function memoryReviewerVerifyEnabled(env?: Record<string, string | undefined>): boolean;
+/** `AUDIT_MEMORY_REVIEWER_EVERY`: review every N user turns. Default 5 (to be calibrated in the pilot). */
+export declare const DEFAULT_REVIEW_EVERY = 5;
+export declare function memoryReviewerEvery(env?: Record<string, string | undefined>): number;
+/** Most operations one review may stage; a bound on the output, not a language judgement. */
+export declare const MAX_REVIEW_OPS = 5;
+export type ReviewScope = 'general' | 'this_context';
+export type ReviewVerification = 'supported' | 'unsupported' | 'not_checked';
+/** One typed operation the reviewer proposes. `evidence` is the user's own words; it is stored and shown, never string-matched. */
+export interface ReviewOp {
+    kind: 'upsert' | 'retire' | 'noop';
+    /** upsert: stable model-chosen key for a single-valued attribute (M1 supersession). */
+    key?: string;
+    /** upsert: the claim, phrased to preserve what the user said ("asked for X in this context" unless they stated a general preference). */
+    text?: string;
+    /** retire: the `id` of the existing fact (from the list the reviewer was shown) to propose retiring. */
+    targetId?: number;
+    evidence?: string;
+    scope?: ReviewScope;
+    category?: FactCategory;
+    judgement?: CandidateJudgement;
+}
+export interface VerifiedReviewOp extends ReviewOp {
+    verification: ReviewVerification;
+    /** Verifier's one-line reason when it said unsupported. */
+    reason?: string;
+}
+export interface ReviewerInput {
+    /** The session transcript; only `user` messages are read as claims. */
+    transcript: readonly ChatMessage[];
+    /** Block last injected into the prompt; removed verbatim from every user message (feedback-loop prevention). */
+    injectedBlock: string;
+    /** Current durable facts, shown to the reviewer so a retire can name its target. `id` is the index the reviewer uses. */
+    existingFacts: readonly {
+        id: number;
+        text: string;
+        source: string;
+    }[];
+    /** M3 integration point: episodic digests of earlier sessions, context only. Unused until M3 lands. */
+    digests?: readonly string[];
+}
+/** The user-only digest the reviewer sees: recent turns verbatim, older turns clipped, memory block stripped, total bounded. Pure formatting, no language judgement. */
+export declare function buildUserDigest(transcript: readonly ChatMessage[], injectedBlock: string): string[];
+/** One bounded reviewer call. Returns no ops (never throws) on any error or unparseable output: a failed review writes nothing. */
+export declare function proposeMemoryOps(input: ReviewerInput, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<ReviewOp[]>;
+/**
+ * One bounded verifier call (same shape as grounding-check.ts, fail-open): is each op supported by the user's messages, at
+ * the stated scope, and not a generalisation of a one-off request. Fail-open: an error, an unparseable answer or a missing
+ * verdict leaves the op `not_checked` (it still only reaches the pending queue, never durable memory).
+ */
+export declare function verifyMemoryOps(ops: readonly ReviewOp[], input: ReviewerInput, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<VerifiedReviewOp[]>;
+/** The facts the reviewer must read through `UserFact` shape — re-exported so the staging method has one type to take. */
+export type ReviewerFact = UserFact;
+/**
+ * Trigger bookkeeping: a per-session counter of user turns since the last memory write (or review). Fires on the Nth
+ * turn; a turn in which any memory write occurred resets it (the in-turn writer is already doing the job). Pure state,
+ * no timers: it can only fire when `noteTurn` is called after a turn finished, so it never fires during a turn.
+ */
+export declare class ReviewTrigger {
+    private readonly every;
+    private counts;
+    constructor(every?: () => number);
+    noteTurn(sessionId: string, wroteMemoryThisTurn: boolean): boolean;
+    reset(sessionId: string): void;
+    count(sessionId: string): number;
+}
+export interface ReviewRunResult {
+    proposed: number;
+    stage: StageReviewerResult | undefined;
+    /** The run was aborted (a new turn began) before it wrote anything. */
+    aborted: boolean;
+}
+/**
+ * Orchestrates one review: reviewer call, verifier call, staging. Owns the trigger counter and the single in-flight run,
+ * which `abort()` cancels (checked between every await and again immediately before the writes, so an abort leaves no
+ * partial write). Never throws. LLM usage is reported through `onUsage`, which the host folds into the session's spend.
+ */
+export declare class MemoryReviewer {
+    private readonly memoryService;
+    private readonly llmClient;
+    private readonly model;
+    private readonly getTranscript;
+    readonly trigger: ReviewTrigger;
+    private controller;
+    private inFlight;
+    constructor(memoryService: MemoryService, llmClient: ILLMClient, model: () => string | undefined, getTranscript: (sessionId: string) => Promise<ChatMessage[]>);
+    /** Cancels the run in progress, if any (a new user turn began). */
+    abort(): void;
+    /** Resolves when the run in progress (if any) has finished; for hosts that must not exit mid-review and for tests. */
+    settled(): Promise<void>;
+    /** Starts a review off the caller's critical path and returns immediately. */
+    start(sessionId: string, onUsage?: (u: TokenUsage) => void): void;
+    /** Runs a review to completion (session edge). */
+    runNow(sessionId: string, onUsage?: (u: TokenUsage) => void): Promise<ReviewRunResult>;
+    private run;
+}