@buildaharness/aielia 0.3.8 → 0.3.10

package/dist/writer/writer-chat-capture.d.ts

@@ -0,0 +1,25 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { ArticleRef, CaptureOp, WriterChatState } from './writer-chat-state.js';
+/**
+ * Reads one message from the writer and proposes changes to the article's chat-held state. The meaning is judged by a
+ * model; this module only stores the result (no word matching). Only the writer's own message is read, never the
+ * assistant's replies. One bounded call; any failure leaves the state unchanged and says so.
+ */
+export type CaptureStatus = 'captured' | 'needs_article' | 'not_captured';
+export interface CaptureResult {
+    status: CaptureStatus;
+    state: WriterChatState;
+    /** The article the message concerns, when it could be told. The caller keeps it as the active article. */
+    articleId?: string;
+    applied: string[];
+    skipped: string[];
+    /** Set with `needs_article`: apply these with `applyCaptureOps` once the writer names the article. */
+    pendingOps?: CaptureOp[];
+    question?: string;
+}
+export declare function captureChatState(input: {
+    message: string;
+    state: WriterChatState;
+    articles: readonly ArticleRef[];
+    now?: string;
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<CaptureResult>;

package/dist/writer/writer-chat-history.d.ts

@@ -0,0 +1,17 @@
+import { ChatMessage } from '@buildaharness/runtime';
+/**
+ * The conversation so far, as the earlier messages of a model call that changes the article. A change is asked for in the middle of a talk
+ * ("add the rest of those to the problem section"), so the call must see the talk; it goes before the article and the instruction, so that
+ * what is the same from one request to the next stays at the start, where a provider can reuse it.
+ */
+export interface ChatTurn {
+    from: 'you' | 'aielia';
+    text: string;
+}
+/**
+ * Alternating user and assistant messages from the newest turns: each clipped, runs by the same side joined, the oldest dropped to fit,
+ * starting with the writer and ending with the assistant (the writer's newest message is the instruction, which the caller adds).
+ */
+export declare function chatHistoryMessages(turns: readonly ChatTurn[] | undefined): ChatMessage[];
+/** Added to the instructions of a call that is given the conversation. */
+export declare const CHAT_HISTORY_NOTE = " The messages before the last are the conversation so far between the writer and the assistant: the instruction may refer to them (\"those\", \"the rest\", \"what you listed\"); follow the instruction, and take from the conversation only what it points to.";

package/dist/writer/writer-chat-state.d.ts

@@ -0,0 +1,358 @@
+import { z } from 'zod';
+/**
+ * State the writer gives in chat (T13, plans/aielia_write_article_model_plan.html section 8): reviewer comments,
+ * the writer's decisions about them, conflicts between comments, and corrections to facts or sources. It belongs to
+ * the article, not to the conversation, so work that resumes in a new session still has it.
+ *
+ * Pure data and pure functions only (no node:* / DOM imports): the browser bundles this module.
+ */
+export declare const WRITER_CHAT_STATE_VERSION = 1;
+export declare const WriterCommentSchema: z.ZodObject<{
+    id: z.ZodString;
+    articleId: z.ZodString;
+    /** The label the writer or reviewer uses ("C1", "G2"), when there is one. Not unique across articles. */
+    label: z.ZodOptional<z.ZodString>;
+    reviewer: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+    /** `open` covers "decided but not carried out": a decision is recorded, but the comment is only `addressed` once the text shows it. */
+    state: z.ZodEnum<["open", "addressed", "dismissed"]>;
+    decision: z.ZodOptional<z.ZodString>;
+    /** Ids of comments that cannot be followed together with this one. Always mutual. */
+    conflictsWith: z.ZodArray<z.ZodString, "many">;
+    origin: z.ZodEnum<["reviewer", "writer", "assistant"]>;
+    /** Where the comment applies, when it is tied to one section or claim (article model, "about" link). */
+    anchor: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<["section", "claim"]>;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        type: "section" | "claim";
+    }, {
+        id: string;
+        type: "section" | "claim";
+    }>>;
+    /** The stretch of text the writer highlighted when commenting. Found again by the quote after the text changes. */
+    span: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        quote: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        quote: string;
+        start: number;
+        end: number;
+    }, {
+        quote: string;
+        start: number;
+        end: number;
+    }>>;
+    /** The text the comment was on no longer exists as it was. The comment is kept. */
+    outdated: z.ZodOptional<z.ZodBoolean>;
+    /** The suggestion that addressed it, if any. */
+    suggestionId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    text: string;
+    origin: "reviewer" | "assistant" | "writer";
+    articleId: string;
+    state: "open" | "addressed" | "dismissed";
+    conflictsWith: string[];
+    capturedAt: string;
+    reviewer?: string | undefined;
+    decision?: string | undefined;
+    label?: string | undefined;
+    span?: {
+        quote: string;
+        start: number;
+        end: number;
+    } | undefined;
+    anchor?: {
+        id: string;
+        type: "section" | "claim";
+    } | undefined;
+    outdated?: boolean | undefined;
+    suggestionId?: string | undefined;
+}, {
+    id: string;
+    text: string;
+    origin: "reviewer" | "assistant" | "writer";
+    articleId: string;
+    state: "open" | "addressed" | "dismissed";
+    conflictsWith: string[];
+    capturedAt: string;
+    reviewer?: string | undefined;
+    decision?: string | undefined;
+    label?: string | undefined;
+    span?: {
+        quote: string;
+        start: number;
+        end: number;
+    } | undefined;
+    anchor?: {
+        id: string;
+        type: "section" | "claim";
+    } | undefined;
+    outdated?: boolean | undefined;
+    suggestionId?: string | undefined;
+}>;
+export type WriterComment = z.infer<typeof WriterCommentSchema>;
+/** A correction the writer states in chat. It is the "author's say-so" source kind (D2): lower-trust, and it supersedes what it names. */
+export declare const WriterCorrectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    articleId: z.ZodString;
+    kind: z.ZodLiteral<"say_so">;
+    trust: z.ZodLiteral<"lower">;
+    /** What is now true, in the writer's terms ("p99 latency is 41 ms after a re-run"). */
+    note: z.ZodString;
+    /** The earlier value or source it replaces, when the writer names one. */
+    supersedes: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind: "say_so";
+    note: string;
+    articleId: string;
+    capturedAt: string;
+    trust: "lower";
+    supersedes?: string | undefined;
+}, {
+    id: string;
+    kind: "say_so";
+    note: string;
+    articleId: string;
+    capturedAt: string;
+    trust: "lower";
+    supersedes?: string | undefined;
+}>;
+export type WriterCorrection = z.infer<typeof WriterCorrectionSchema>;
+export declare const WriterChatStateSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<1>;
+    comments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        articleId: z.ZodString;
+        /** The label the writer or reviewer uses ("C1", "G2"), when there is one. Not unique across articles. */
+        label: z.ZodOptional<z.ZodString>;
+        reviewer: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+        /** `open` covers "decided but not carried out": a decision is recorded, but the comment is only `addressed` once the text shows it. */
+        state: z.ZodEnum<["open", "addressed", "dismissed"]>;
+        decision: z.ZodOptional<z.ZodString>;
+        /** Ids of comments that cannot be followed together with this one. Always mutual. */
+        conflictsWith: z.ZodArray<z.ZodString, "many">;
+        origin: z.ZodEnum<["reviewer", "writer", "assistant"]>;
+        /** Where the comment applies, when it is tied to one section or claim (article model, "about" link). */
+        anchor: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<["section", "claim"]>;
+            id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            type: "section" | "claim";
+        }, {
+            id: string;
+            type: "section" | "claim";
+        }>>;
+        /** The stretch of text the writer highlighted when commenting. Found again by the quote after the text changes. */
+        span: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+            quote: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            quote: string;
+            start: number;
+            end: number;
+        }, {
+            quote: string;
+            start: number;
+            end: number;
+        }>>;
+        /** The text the comment was on no longer exists as it was. The comment is kept. */
+        outdated: z.ZodOptional<z.ZodBoolean>;
+        /** The suggestion that addressed it, if any. */
+        suggestionId: z.ZodOptional<z.ZodString>;
+        capturedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        text: string;
+        origin: "reviewer" | "assistant" | "writer";
+        articleId: string;
+        state: "open" | "addressed" | "dismissed";
+        conflictsWith: string[];
+        capturedAt: string;
+        reviewer?: string | undefined;
+        decision?: string | undefined;
+        label?: string | undefined;
+        span?: {
+            quote: string;
+            start: number;
+            end: number;
+        } | undefined;
+        anchor?: {
+            id: string;
+            type: "section" | "claim";
+        } | undefined;
+        outdated?: boolean | undefined;
+        suggestionId?: string | undefined;
+    }, {
+        id: string;
+        text: string;
+        origin: "reviewer" | "assistant" | "writer";
+        articleId: string;
+        state: "open" | "addressed" | "dismissed";
+        conflictsWith: string[];
+        capturedAt: string;
+        reviewer?: string | undefined;
+        decision?: string | undefined;
+        label?: string | undefined;
+        span?: {
+            quote: string;
+            start: number;
+            end: number;
+        } | undefined;
+        anchor?: {
+            id: string;
+            type: "section" | "claim";
+        } | undefined;
+        outdated?: boolean | undefined;
+        suggestionId?: string | undefined;
+    }>, "many">;
+    corrections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        articleId: z.ZodString;
+        kind: z.ZodLiteral<"say_so">;
+        trust: z.ZodLiteral<"lower">;
+        /** What is now true, in the writer's terms ("p99 latency is 41 ms after a re-run"). */
+        note: z.ZodString;
+        /** The earlier value or source it replaces, when the writer names one. */
+        supersedes: z.ZodOptional<z.ZodString>;
+        capturedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "say_so";
+        note: string;
+        articleId: string;
+        capturedAt: string;
+        trust: "lower";
+        supersedes?: string | undefined;
+    }, {
+        id: string;
+        kind: "say_so";
+        note: string;
+        articleId: string;
+        capturedAt: string;
+        trust: "lower";
+        supersedes?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    comments: {
+        id: string;
+        text: string;
+        origin: "reviewer" | "assistant" | "writer";
+        articleId: string;
+        state: "open" | "addressed" | "dismissed";
+        conflictsWith: string[];
+        capturedAt: string;
+        reviewer?: string | undefined;
+        decision?: string | undefined;
+        label?: string | undefined;
+        span?: {
+            quote: string;
+            start: number;
+            end: number;
+        } | undefined;
+        anchor?: {
+            id: string;
+            type: "section" | "claim";
+        } | undefined;
+        outdated?: boolean | undefined;
+        suggestionId?: string | undefined;
+    }[];
+    formatVersion: 1;
+    corrections: {
+        id: string;
+        kind: "say_so";
+        note: string;
+        articleId: string;
+        capturedAt: string;
+        trust: "lower";
+        supersedes?: string | undefined;
+    }[];
+}, {
+    comments: {
+        id: string;
+        text: string;
+        origin: "reviewer" | "assistant" | "writer";
+        articleId: string;
+        state: "open" | "addressed" | "dismissed";
+        conflictsWith: string[];
+        capturedAt: string;
+        reviewer?: string | undefined;
+        decision?: string | undefined;
+        label?: string | undefined;
+        span?: {
+            quote: string;
+            start: number;
+            end: number;
+        } | undefined;
+        anchor?: {
+            id: string;
+            type: "section" | "claim";
+        } | undefined;
+        outdated?: boolean | undefined;
+        suggestionId?: string | undefined;
+    }[];
+    formatVersion: 1;
+    corrections: {
+        id: string;
+        kind: "say_so";
+        note: string;
+        articleId: string;
+        capturedAt: string;
+        trust: "lower";
+        supersedes?: string | undefined;
+    }[];
+}>;
+export type WriterChatState = z.infer<typeof WriterChatStateSchema>;
+export interface ArticleRef {
+    id: string;
+    title: string;
+    /** The short name shown in the header; the title is shown when there is none. */
+    name?: string;
+}
+export declare function createEmptyWriterChatState(): WriterChatState;
+/** One change the capture step proposes. `ref` is a comment id, or the label of a comment in the same article. */
+export type CaptureOp = {
+    op: 'add_comment';
+    label?: string;
+    reviewer?: string;
+    text: string;
+    origin?: 'reviewer' | 'writer';
+} | {
+    op: 'decide';
+    ref: string;
+    decision: string;
+} | {
+    op: 'conflict';
+    refs: string[];
+} | {
+    op: 'set_state';
+    ref: string;
+    state: 'addressed' | 'dismissed';
+} | {
+    op: 'add_correction';
+    note: string;
+    supersedes?: string;
+};
+export interface ApplyResult {
+    state: WriterChatState;
+    /** One short line per change that was made. */
+    applied: string[];
+    /** One short line per op that could not be applied (unknown reference, empty text). Never silent. */
+    skipped: string[];
+}
+/** Applies ops to the state for one article. Pure: returns a new state; the input is untouched. */
+export declare function applyCaptureOps(state: WriterChatState, articleId: string, ops: readonly CaptureOp[], now: string): ApplyResult;
+/**
+ * The block added to the assistant's system prompt on every call: only the article under discussion, so work on one
+ * article never leaks into another. Empty when there is nothing to say.
+ */
+export declare function renderWriterChatBlock(state: WriterChatState, articleId: string | undefined, articles: readonly ArticleRef[]): string;

package/dist/writer/writer-chat-turn.d.ts

@@ -0,0 +1,52 @@
+import { ILLMClient, MemoryAdapter, TokenUsage } from '@buildaharness/runtime';
+import { CaptureStatus } from './writer-chat-capture.js';
+import { ArticleRef, CaptureOp, WriterChatState } from './writer-chat-state.js';
+/**
+ * One turn of the chat-held state (T13): capture what the writer's message adds, store it per article (not per
+ * session), and return the block the assistant's system prompt gets. The host supplies a port for storage and for the
+ * list of articles; with no port the assistant does none of this.
+ */
+export interface WriterChatPort {
+    articles(): Promise<ArticleRef[]> | ArticleRef[];
+    load(): Promise<WriterChatState>;
+    save(state: WriterChatState): Promise<void>;
+    getActive(): Promise<string | undefined>;
+    setActive(articleId: string | undefined): Promise<void>;
+    getPending(): Promise<CaptureOp[] | undefined>;
+    setPending(ops: CaptureOp[] | undefined): Promise<void>;
+    /** The current text of an article, when the host can give it. Shown to the answering model so it can talk about what is on the page (clipped). */
+    articleText?(articleId: string): Promise<string | undefined>;
+    /** False when the writer has turned chat capture off: the message is not read, but what is already recorded is still shown. */
+    captureEnabled?(): Promise<boolean>;
+    /** The ideas on the article's list that are not in the text yet, as plain lines. Shown to the answering model so the writer can talk about them. */
+    ideasText?(articleId: string): Promise<string[]>;
+    /** The writer's brief and writing profile for the article as plain text, or '' when there is none. */
+    styleText?(articleId: string): Promise<string>;
+    /** What is still open before the article is ready, as plain lines, or '' when nothing is. */
+    openItemsText?(articleId: string): Promise<string>;
+    /** The article's stored sources as text (address and passage), or '' when there are none. Shown to the answering model so it can use them. */
+    sourcesText?(articleId: string): Promise<string>;
+}
+/** A port backed by the assistant's own memory adapter. The articles list comes from the host (the page that owns the articles). */
+export declare function createMemoryWriterChatPort(memory: MemoryAdapter, articles: () => Promise<ArticleRef[]> | ArticleRef[]): WriterChatPort;
+/**
+ * Only the recording half of a turn, for a message that asks for an edit, a draft or suggestions: what the writer says is read and kept in the
+ * article's record exactly as in a full turn (the edit reads that record), but no reply is written, so it is one model call instead of the
+ * whole turn. Never throws: a failure is reported as `not_captured`.
+ */
+export declare function recordWriterMessage(input: {
+    message: string;
+    port: WriterChatPort;
+    now?: string;
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<{
+    status: CaptureStatus | 'off';
+}>;
+/**
+ * Returns the text to append to the system prompt for this turn (empty when there is nothing to say). Never throws:
+ * a failure of any kind returns the not-captured note, so the assistant cannot claim something was saved that was not.
+ */
+export declare function processWriterMessage(input: {
+    message: string;
+    port: WriterChatPort;
+    now?: string;
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<string>;

package/dist/writer/writer-intent.d.ts

@@ -0,0 +1,20 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+/**
+ * What a writer's chat message asks for, judged by a model (no word matching): change the text now, propose changes to review, or just
+ * talk. The Write page uses it when the chat is in Auto mode, so the writer never has to set a mode before asking for something.
+ * A failure or an unclear message is an answer: the cheaper mistake, since the reply offers to apply the change.
+ */
+export type ChatIntent = 'edit' | 'rewrite' | 'suggest' | 'check' | 'answer';
+export type EditScope = 'outline' | 'text' | 'both';
+/** What a message asks for, and the web pages it points to as something to follow or draw on (read by the host, which knows whether it can fetch pages). */
+export interface WriterIntent {
+    intent: ChatIntent;
+    links: string[];
+    /** For an edit: what it changes. The headings alone (add, rename, move or remove sections), the wording alone, or both (e.g. a new section and what it says). */
+    scope: EditScope;
+}
+export declare function readWriterIntent(input: {
+    message: string;
+    articleHasText: boolean;
+    lastReply?: string;
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void, signal?: AbortSignal): Promise<WriterIntent>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildaharness/aielia",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "An open-source AI agent you can hand real work to. Runs the full 11-layer Build A Harness every turn, controlling what it may do, believe and spend, and stages file writes, shell commands and email for your approval. CLI, browser, and desktop.",
   "license": "Apache-2.0",
   "homepage": "https://myaielia.com",
@@ -48,8 +48,8 @@
     "shadow-report": "tsx scripts/shadow-report.ts"
   },
   "dependencies": {
-    "@buildaharness/harness": "^0.3.2",
-    "@buildaharness/runtime": "^0.3.3",
+    "@buildaharness/harness": "^0.3.3",
+    "@buildaharness/runtime": "^0.3.4",
     "@dagrejs/dagre": "^3.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "diff": "^8.0.4",