@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/turn/engine/extras.d.ts

@@ -0,0 +1,16 @@
+import { type Delivery } from "../deliveries.js";
+import { type TurnContext } from "./context.js";
+/** Under a message that says something went wrong: one button that starts /feedback. */
+export declare function offerReport(ctx: TurnContext): Promise<void>;
+/** Under the final answer of a turn from a client whose thumbs never reach us: the worker's own thumbs. */
+export declare function offerThumbs(ctx: TurnContext): Promise<void>;
+/**
+ * Under a finished answer: what the session changed, with Create PR and Open diff in Claw. Nothing is shown for anything
+ * that is not a plain success: no changes, a sandbox that is gone, a slow or failed call.
+ */
+export declare function offerChanges(ctx: TurnContext, sessionId: string): Promise<void>;
+/**
+ * After the answer: the files the agent delivered. A 1:1 chat gets a card for each (a small image shown in it), a group
+ * chat one line each with the link and nothing of the file.
+ */
+export declare function offerDeliveries(ctx: TurnContext, sessionId: string, deliveries: readonly Delivery[]): Promise<void>;

package/dist/types/turn/engine/fallback.d.ts

@@ -0,0 +1,17 @@
+/** A turn refused for want of the user's model key, run once more on a model that needs none. */
+import type { StatusMessage } from "../progress/status-message.js";
+import type { Step } from "../step.js";
+import { TurnState } from "../turn-state.js";
+import { type TurnContext } from "./context.js";
+export interface Rerun {
+    readonly state: TurnState;
+    readonly ok: boolean;
+}
+/**
+ * Runs the turn once more on the fallback model: the session is pinned to it for this one turn and put back on the
+ * worker's model afterwards. Undefined when there is nothing to run it on, or Claw would not move the session: the caller
+ * then tells the user to upload the key.
+ */
+export declare function rerunOnFallback(ctx: TurnContext, sessionId: string, status: StatusMessage<Step>, onSession: (sessionId: string) => void, running: {
+    called: boolean;
+}): Promise<Rerun | undefined>;

package/dist/types/turn/engine/outcome.d.ts

@@ -0,0 +1,33 @@
+import type { TurnState } from "../turn-state.js";
+import type { PublicErrors } from "../../public-error/public-errors.js";
+import { type ClawError } from "../../claw/errors.js";
+import { type TurnContext } from "./context.js";
+/** The chat stops following a turn after this; the run itself does not stop. */
+export declare const TURN_DEADLINE_SECONDS: number;
+/** What the chat says when the turn's time is up and the run is still going. */
+export declare function stillRunningText(ctx: TurnContext, deadlineSeconds?: number): string;
+/** What a Claw refusal before the turn ran is said as. The log gets the status and Claw's error word only, never the body. */
+export declare function clawFailure(errors: PublicErrors, err: ClawError, review?: boolean): string;
+/**
+ * A review whose stream showed its GitHub result before the turn broke off: its result line, to go above what the chat
+ * is told, since the progress message that showed it is replaced. '' otherwise.
+ */
+export declare function resultLead(ctx: TurnContext, state: TurnState | undefined): string;
+export interface Ending {
+    /** What the turn answered, with its failure cut off. */
+    readonly answer: string;
+    /** `answer` as the chat shows it (a review's one message). */
+    readonly shown: string;
+    readonly link: string;
+    readonly ok: boolean;
+    readonly stopped: boolean;
+    /** A stop Claw confirmed: said as stopped only. */
+    readonly confirmed: boolean;
+    /** The line in front of an answer a fallback model gave. */
+    readonly lead: string;
+}
+/**
+ * The messages that end a turn. Claw ends a turn it was told to stop as failed: a stop it confirmed is said as stopped
+ * only; a stop asked for but not confirmed leaves a failure said as one.
+ */
+export declare function endingParts(ctx: TurnContext, ending: Ending): string[];

package/dist/types/turn/engine/run-turn.d.ts

@@ -0,0 +1,22 @@
+import { type TurnContext } from "./context.js";
+/** Claw's 403 to a session made as someone else once it has review items. */
+export declare const ACTING_AS_MUST_BE_SELF = "acting_as_must_be_self";
+/** The chat stopped following the turn after TURN_DEADLINE_SECONDS. */
+export declare class DeadlineExpired extends Error {
+    constructor();
+}
+/** What the caller decides while the turn runs. */
+export interface TurnControls {
+    /** Records the session the turn runs in. */
+    readonly onSession: (sessionId: string) => void;
+    /** A stop was asked for (/stop, an item's Stop). */
+    readonly stopRequested: () => boolean;
+    /** The user denied a tool in this turn. */
+    readonly toolDenied?: () => boolean;
+    /** Claw confirmed the stop: the turn is said as stopped only. */
+    readonly stopConfirmed?: () => boolean;
+    /** The turn is cancelled: no live edit is sent after it, and the run's record is still kept. */
+    readonly signal?: AbortSignal;
+}
+/** Runs the turn and always leaves the user a message; `controls.onSession` records the session id. */
+export declare function runTurn(ctx: TurnContext, controls: TurnControls): Promise<void>;

package/dist/types/turn/engine/submit.d.ts

@@ -0,0 +1,23 @@
+import type { SendOptions } from "../../ports/claw/sessions.js";
+import { type TurnContext } from "./context.js";
+/**
+ * The id of the newest event the session holds, read just before the message is sent: the turn's events come after it, so
+ * its stream starts there and not with the session's history. Best effort: undefined starts where Claw starts it.
+ */
+export declare function turnStart(ctx: TurnContext, sessionId: string, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * The turn Claw is running on the session just before this message is sent, if any: a message sent now is queued behind
+ * it, and the queued turn is told from older ones by starting after it. Best effort.
+ */
+export declare function turnInFront(ctx: TurnContext, sessionId: string, signal?: AbortSignal): Promise<string | undefined>;
+/** The model key and the acting flag for the two calls that start a model turn (only when the turn has them). */
+export declare function sendOptions(ctx: TurnContext): SendOptions;
+/**
+ * Fetches the files the user sent and puts them in `sessionId` before the message goes, so the agent finds them when it
+ * reads the message. With no session, or when it was deleted, one is made without a message. A file that could not be
+ * fetched or that Claw did not take is named to the user, and the message still goes. Returns the session.
+ */
+export declare function putFiles(ctx: TurnContext, sessionId: string | undefined, signal?: AbortSignal): Promise<string | undefined>;
+export type Submitted = readonly [sessionId: string, messageId: string | undefined, behind: string | undefined];
+/** (session, message id, turn in front); the message id is undefined when Claw queued the message behind a running turn. */
+export declare function submit(ctx: TurnContext, signal?: AbortSignal): Promise<Submitted>;

package/dist/types/turn/files.d.ts

@@ -0,0 +1,10 @@
+/** A file's name said back to the user is cut to this. */
+export declare const SHOWN_NAME_MAX = 100;
+/** The folder the files of one message go to, so two messages never overwrite each other's files. */
+export declare function uploadFolder(messageId: string): string;
+/** The line the model reads after the user's words: where the files are, and that what is in them is the user's data. */
+export declare function filesNote(paths: readonly string[]): string;
+/** A file's name as it is said back in a message: in a code span, one line, its backticks turned to quotes, clipped. */
+export declare function shownName(name: string): string;
+/** What the user is told about files that did not reach the agent (the reasons are this worker's own words). */
+export declare function failedFilesLine(failed: ReadonlyArray<readonly [name: string, why: string]>): string;

package/dist/types/turn/github-outcome.d.ts

@@ -0,0 +1,16 @@
+/** (tool, status, review event): one call's outcome. */
+export type GithubOutcome = readonly [tool: string, status: string, event: string];
+/**
+ * What a finished call left on GitHub: (tool, status, review event) for a review posted, a merge or a place in the merge
+ * queue, or a try that says it already wrote (`wrote: true`); undefined for anything that left nothing.
+ */
+export declare function githubWrite(tool: string, description: unknown): GithubOutcome | undefined;
+/** How many inline comments a review gh_review_submit posted carried (`"comments": N`); 0 when it does not say. */
+export declare function reviewComments(description: unknown): number;
+/** The sentence of what the pull request does that a write call gave (`"pr_summary"`), clipped as shown; '' for none. */
+export declare function githubPrSummary(tool: string, description: unknown): string;
+/**
+ * How a finished call came out, whatever it was: (tool, status, review event) with the `status` of its answer, or "error"
+ * when the call failed and its answer says no status. Undefined for any other tool, and for a call not finished.
+ */
+export declare function githubResult(tool: string, status: string, description: unknown): GithubOutcome | undefined;

package/dist/types/turn/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The turn engine and the answer's views (the Python worker's turn.py and the answer/progress/plan part of render.py):
+ * submit a message to Claw, follow the session's stream, show progress, answer. Exported as the `turn` namespace.
+ */
+export { answerParts, deepLink, MAX_ANSWER_CHARS, MAX_ANSWER_MESSAGES, replyParts, wholeParts, } from "./answer-parts.js";
+export { type Changes, type FileChange, parseChanges, type RepoChanges, repoName, totalAdditions, totalDeletions, totalFiles, } from "./changes.js";
+export { clip, plain, SUMMARY_MAX, TITLE_MAX } from "./clip.js";
+export { assistantDeliveries, DELIVERIES_MAX, type Delivery, deliveryLine, deliveryOf, INLINE_IMAGE_MAX_BYTES, sizeText, } from "./deliveries.js";
+export { type TurnContext, type TurnDeps, type TurnHooks, type TurnRecord, type TurnRequest, type TurnStyle, newRecord, } from "./engine/context.js";
+export { stillRunningText, TURN_DEADLINE_SECONDS } from "./engine/outcome.js";
+export { runTurn, type TurnControls } from "./engine/run-turn.js";
+export { filesNote, failedFilesLine, shownName, uploadFolder } from "./files.js";
+export { type GithubOutcome, githubPrSummary, githubResult, githubWrite, reviewComments } from "./github-outcome.js";
+export { lastAnswer, LAST_ANSWER_TAIL, type LastAnswerDeps } from "./last-answer.js";
+export { LIVE_HEADER, LIVE_HEADERS, LiveView } from "./live-view.js";
+export { failedLine, isShell, Label, labelFor, lookupLabel, skillInCommand } from "./step-labels.js";
+export { planText, type Todo, todosOf } from "./plan.js";
+export type { TurnClaw, TurnSurface } from "./ports.js";
+export { StatusMessage, type StatusOptions, turnStatusMessage, type TurnStatusOptions, } from "./progress/status-message.js";
+export { defaultStreamFinish, type LiveViewLike, type StatusPolicy, STREAM_TEXT_MAX, type StreamFinish, type StreamFinishInput, TurnStatusPolicy, } from "./progress/status-policy.js";
+export type { Step } from "./step.js";
+export { TurnState } from "./turn-state.js";
+export { type ChangesModel, type DeliveryModel, viewMessage } from "./views.js";
+export { type ReviewTurnOptions, type ReviewTurnOutcome, type TurnApprovals, TurnEngine, type TurnEngineDeps, } from "./runner.js";
+export { OFFER_KEEP_SECONDS, type Offer, STOP_CARD_DELAY_SECONDS, STOP_KINDS, StopButtons, type StopButtonsDeps, type StopKind, stopMessage, type StopModel, } from "./stop-buttons.js";
+export { stopText } from "../locales/turn.js";

package/dist/types/turn/json.d.ts

@@ -0,0 +1,10 @@
+/** Reading the untyped JSON of a stream event's `data` field by field, with the Python worker's truthiness. */
+import type { JsonObject, JsonValue } from "../json.js";
+export type { JsonObject, JsonValue };
+export declare function isObject(value: unknown): value is JsonObject;
+/** `value` when it is an object, else an empty one (Python: `data.get(x) or {}`). */
+export declare function objectOr(value: unknown): JsonObject;
+/** Python truthiness of a JSON value. */
+export declare function truthy(value: unknown): boolean;
+/** Python's `str(value or "")` for a field that should be text: '' for anything falsy, a number as Python prints it. */
+export declare function textOf(value: unknown): string;

package/dist/types/turn/last-answer.d.ts

@@ -0,0 +1,44 @@
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import { type TurnClaw } from "./ports.js";
+import { TurnState } from "./turn-state.js";
+import type { PublicErrors } from "../public-error/public-errors.js";
+import type { SseEvent } from "../claw/model.js";
+export declare const READ_OVERALL_SECONDS = 20;
+/** After a turn has finished, this much silence means the history replay is over. */
+export declare const READ_IDLE_SECONDS = 2;
+/** Events read for the last answer: the last finished turn is in it even behind a long running one. */
+export declare const LAST_ANSWER_TAIL = 2000;
+/** A replay larger than this is refused unread: a Claw that predates `tail` sends everything. */
+export declare const LAST_ANSWER_MAX_BYTES: number;
+/** Turns whose state is kept while the history is read: the newest ones (the last finished turn is kept apart). */
+export declare const LAST_ANSWER_TURNS = 8;
+/**
+ * The turns of a history read for its last answer: one TurnState per message, and only the newest LAST_ANSWER_TURNS of
+ * them, so a long history does not leave a state behind for every turn it ever had.
+ */
+export declare class Turns {
+    readonly states: Map<string, TurnState>;
+    current: string;
+    lastDone: TurnState | undefined;
+    feed(event: SseEvent): void;
+}
+/** Replay rows `{event_id, event_type, data}` as the events the stream would have sent for them. */
+export declare function replayed(rows: ReadonlyArray<{
+    event_id?: unknown;
+    event_type?: unknown;
+    data?: unknown;
+}>): SseEvent[];
+export interface LastAnswerDeps {
+    readonly claw: TurnClaw;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly errors: PublicErrors;
+}
+/**
+ * The answer of the session's last finished turn (undefined: no turn has finished), read with `key`. Reads the last
+ * LAST_ANSWER_TAIL events, never the whole history; when the replay cannot be read (other than refused), the stream's
+ * history is read, keeping only the newest turns' states. Claw refuses either (401/403/404) for a session the key does not
+ * own, which is what stops anybody reading somebody else's session.
+ */
+export declare function lastAnswer(deps: LastAnswerDeps, key: string, sessionId: string): Promise<string | undefined>;

package/dist/types/turn/live-view.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What a chat shows while a turn runs: the agent's own short lines between tool calls, and at most one line for the step
+ * running now.
+ *
+ * The lines are the main agent's visible text (one per step) and a "⚠️ ... failed, continuing" line for a step that
+ * failed. The step running now is one "⏳ <label>" line at the end, replaced in place by the next step and gone when the
+ * step is over: a finished step leaves nothing, so the view never grows a list of tools. The label is humanized (never a
+ * raw tool name) and consecutive repeats of the same step collapse into one line with a count. Every line is its own
+ * paragraph, because Teams runs lines that are only separated by a single newline together.
+ *
+ * Hidden reasoning, subagent text and tool inputs never reach this class (TurnState.feed does not put them on a Step).
+ * The view is bounded: `render` keeps the newest blocks that fit LIVE_MAX_CHARS. Brain's setup steps are not steps: while
+ * setup is running `preparing` adds one transient line at the end, and a setup step that failed is one line per name. The
+ * agent's own checklist (`todo_write`) sits under the header with a budget of its own.
+ */
+import { type Lang } from "../locales/lang.js";
+import type { Step } from "./step.js";
+import { type Integrations } from "../plugins/integrations.js";
+export declare const LIVE_HEADER: string;
+/** The progress message's first line, in the person's language. */
+export declare const LIVE_HEADERS: Readonly<Record<Lang, string>>;
+/** The live view of a running turn: only the newest part, well under Teams' limit. */
+export declare const LIVE_MAX_CHARS = 2500;
+/** A long turn does not grow the view without bound. */
+export declare const LIVE_KEEP_BLOCKS = 40;
+export declare const LIVE_TOOL_NAME_MAX = 60;
+/** The one line of the step that is running now. */
+export declare const RUNNING_MARK = "\u23F3";
+export declare const PREPARING_LINE: string;
+/** The agent's newest line in a floating status (a 1:1 chat) is clipped to this. */
+export declare const STATUS_NARRATION_MAX = 200;
+export declare function preparationFailureLine(name: string, count?: number): string;
+export declare class LiveView {
+    readonly lang: string;
+    /** A deployment's MCP servers, whose steps read as "Querying <name>". */
+    private readonly integrations;
+    /** The first line of every render (a subclass names what is working). */
+    header: string;
+    /** Setup is running: one transient line at the end. */
+    preparing: boolean;
+    private todos;
+    private blocks;
+    private running;
+    /** The newest step, and how often in a row it has started. */
+    private group;
+    constructor(lang?: string, 
+    /** A deployment's MCP servers, whose steps read as "Querying <name>". */
+    integrations?: Integrations);
+    /** Fold one step in; true when what `render` returns changed. */
+    apply(step: Step): boolean;
+    /** Only a failed setup step gets here: one line per name, with a count. */
+    private loadFailed;
+    private start;
+    private finish;
+    private runningLine;
+    private failedText;
+    private preparingLine;
+    private paragraphs;
+    /**
+     * The view as the few short lines of a floating status: in a 1:1 chat (`private`) where the plan stands and the agent's
+     * newest line; in every chat a step that failed last and the step running now. A group sees no words of the agent's or
+     * of its plan: only the humanized step lines, which come from a fixed list. Nothing yet: [].
+     */
+    statusLines(isPrivate: boolean): string[];
+    private privateLines;
+    render(): string;
+}

package/dist/types/turn/plan.d.ts

@@ -0,0 +1,31 @@
+import { type JsonObject } from "./json.js";
+export declare const TODO_TOOLS: ReadonlySet<string>;
+export declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed", "cancelled"];
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+/** Items read from one event; a list longer than this is not a plan a person reads. */
+export declare const TODO_MAX_ITEMS = 100;
+/** One item is clipped to this: a phone shows about 40 characters a line. */
+export declare const TODO_ITEM_MAX = 80;
+/** A plan with more items than this is folded. */
+export declare const TODO_FULL_MAX = 8;
+/** A folded plan shows this many items in progress ... */
+export declare const TODO_FOLD_ACTIVE = 2;
+/** ... and this many of the ones that come next. */
+export declare const TODO_FOLD_NEXT = 3;
+export declare const TODO_MARKS: Readonly<Record<TodoStatus, string>>;
+/** One item of the plan: its text (one clipped line) and its status. */
+export type Todo = readonly [text: string, status: TodoStatus];
+/** The plan's count line ("**Plan: 1 of 3 done**"), for the floating status too. */
+export declare function planHead(lang: string, done: number, total: number): string;
+/**
+ * The agent's list from a `todo_write` toolUsed event; undefined when the event says nothing about it (another tool, a
+ * call that failed, no list in the event). An empty list is a list: the agent cleared it. Malformed items are skipped,
+ * never raised: an item that is not an object or has no text; a status Brain does not know counts as pending.
+ */
+export declare function todosOf(tool: string, status: string, data: JsonObject): Todo[] | undefined;
+/**
+ * The plan as the live view shows it: a count line, then one paragraph per item. A plan of more than TODO_FULL_MAX items
+ * is folded to the last finished item, the ones in progress, the next few and one line that counts the rest. A plan that
+ * is all done is its count line alone; a list with nothing in it to do or done (empty, or all cancelled) is no plan: "".
+ */
+export declare function planText(todos: readonly Todo[], lang?: string): string;

package/dist/types/turn/ports.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What the turn engine needs from the world: the calls of the ports other lines own that it makes (W0: Conversation,
+ * Clock; W2: the Claw sessions port). Nothing here knows Teams, HTTP or a card's JSON.
+ */
+import type { Clock } from "../ports/clock.js";
+import type { ClawSessionsPort } from "../ports/claw/sessions.js";
+import type { Conversation } from "../ports/surface.js";
+/** Monotonic seconds of `clock`: the unit the turn's intervals are written in. */
+export declare function nowSeconds(clock: Clock): number;
+/** Sleep `seconds` of `clock`; rejects with the signal's reason when it is aborted. */
+export declare function sleepSeconds(clock: Clock, seconds: number, signal?: AbortSignal): Promise<void>;
+/** The conversation the turn answers in: the calls of the Conversation port it makes. */
+export type TurnSurface = Pick<Conversation, "typing" | "send" | "post" | "update" | "delete" | "openStream" | "outgoing" | "deliver">;
+/** The calls of Claw's sessions port a turn makes. */
+export type TurnClaw = Pick<ClawSessionsPort, "create" | "sendMessage" | "setModel" | "lastEventId" | "turn" | "stream" | "uploadFiles" | "events" | "deliveryLink" | "changes">;

package/dist/types/turn/progress/answer-messages.d.ts

@@ -0,0 +1,20 @@
+import type { OutMessage, SuggestedReply, UserRef } from "../../ports/surface.js";
+export interface FinishOptions {
+    /** The parts are an answer: rich text with the markdown converted (the live edits stay plain markdown). */
+    readonly rich?: boolean;
+    /** The chat's thumbs go under the LAST part, and nowhere else. */
+    readonly feedback?: boolean;
+    /** The asker of a review in a group: their answer @mentions them, and only them. */
+    readonly mention?: UserRef | undefined;
+    /** What the agent wrote: the chat's AI label. */
+    readonly ai?: boolean;
+    /** Suggested replies under the last part. */
+    readonly replies?: readonly SuggestedReply[] | undefined;
+}
+/** A plain markdown message. */
+export declare function plainMessage(text: string, ai?: boolean): OutMessage;
+/**
+ * The messages that carry `parts`: each rich or markdown and, for an agent's answer, labelled as AI. Its links stay links
+ * and never become citations: an address the model wrote is not a source.
+ */
+export declare function answerMessages(parts: readonly string[], options: FinishOptions): OutMessage[];

package/dist/types/turn/progress/status-message.d.ts

@@ -0,0 +1,144 @@
+import type { Clock } from "../../ports/clock.js";
+import type { Logger } from "../../ports/logger.js";
+import { type Integrations } from "../../plugins/integrations.js";
+import { type TurnSurface } from "../ports.js";
+import type { Step } from "../step.js";
+import { type FinishOptions } from "./answer-messages.js";
+import { type StatusPolicy } from "./status-policy.js";
+/** A Claw turn's status options: its view is a LiveView in the turn's language. */
+export interface TurnStatusOptions extends Omit<StatusOptions<Step>, "policy"> {
+    /** The agent's text is streamed into the answer's bubble. */
+    readonly streamText?: boolean;
+    /** A deployment's MCP servers, named in progress lines. */
+    readonly integrations?: Integrations;
+}
+/** The status message of a Claw turn (`TurnStatusPolicy`). */
+export declare function turnStatusMessage(surface: TurnSurface, options: TurnStatusOptions): StatusMessage<Step>;
+/** The live view is edited at most this often (the chat throttles edits). */
+export declare const LIVE_MIN_INTERVAL = 1.5;
+/** Brain's setup shows one "Preparing" line only if it lasts this long. */
+export declare const PREPARING_AFTER_SECONDS = 1.5;
+/** The progress message is retired this long after the last progress edit: a late edit must not land on DONE_LINE. */
+export declare const FINAL_SETTLE_SECONDS = 1;
+/** ... and one that is late anyway is covered by sending DONE_LINE once more this long afterwards. */
+export declare const REASSERT_SECONDS = 6;
+/** The chat closes a stream this long after it opened; this one is closed by its final message before that. */
+export declare const STREAM_CLOSE_SECONDS: number;
+export interface StatusOptions<S> {
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly lang?: string;
+    /** What is shown of the turn's steps and words (a Claw turn's: `TurnStatusPolicy`, see `turnStatusMessage`). */
+    readonly policy: StatusPolicy<S>;
+    /** Shown at the top from the first post on (a review's acknowledgement). */
+    readonly lead?: string;
+    /** The person's message a live stream answers; undefined: no stream here (the progress message). */
+    readonly streamReplyTo?: string | undefined;
+    /** Every member sees the floating status: it carries no words of the agent's. */
+    readonly group?: boolean;
+}
+export declare class StatusMessage<S> {
+    private readonly surface;
+    private readonly clock;
+    private readonly log;
+    private readonly lang;
+    private readonly policy;
+    private readonly lead;
+    private readonly group;
+    /** undefined: the progress message (no stream here, or the chat refused it). */
+    private stream;
+    /** The stream itself, kept after a refusal: it is still closed when it can be. */
+    private readonly live;
+    private posted;
+    private flusher;
+    private opening;
+    private expiry;
+    private again;
+    private preparingTimer;
+    private lastText;
+    private lastAt;
+    private begunAt;
+    private sending;
+    private closed;
+    /** When the last live progress edit left. */
+    private editedAt;
+    /** Brain's setup has started and no real step has followed yet. */
+    private preparing;
+    /** A line shown above the live view (a review's result). */
+    private headlineText;
+    /** The stream is being closed before the chat's limit ... */
+    private expiring;
+    /** ... and has been: the answer comes as a message of its own. */
+    private streamOver;
+    /** The turn was cancelled (`close(true)`). */
+    private hard;
+    constructor(surface: TurnSurface, options: StatusOptions<S>);
+    begin(): void;
+    private openStream;
+    /** The chat did not take the stream: the turn is shown by the progress message from here on. */
+    private fallBack;
+    private statusLines;
+    /** Close the stream with STILL_WORKING before the chat's limit; the answer, whenever it comes, is a message of its own. */
+    private closeInTime;
+    /** The chat's id of the posted message; undefined when the post failed or its id never came (nothing is edited then). */
+    private messageId;
+    /**
+     * Track Brain's setup. The first setup step starts a timer; if no real step has come by the time it fires,
+     * "Preparing…" is shown. A real step ends setup and retracts the line. Call it before `progress` for the same step.
+     */
+    note(step: Step): void;
+    private stopPreparingTimer;
+    private announcePreparing;
+    /** Make sure the newest live view gets sent. */
+    private kick;
+    /** Show `line` above the live view from the next edit on (a review's result the moment the stream shows it). */
+    headline(line: string): void;
+    private render;
+    /** Fold the step into what is shown and make sure the newest of it gets sent. */
+    progress(step: S): void;
+    /** The text for the answer's bubble ('' when there is none); what was streamed when it no longer grows from that. */
+    private streamable;
+    /** Whether the turn is still shown by its stream (a refusal hands it to the progress message). */
+    private streaming;
+    private flush;
+    /**
+     * The newest status (or streamed text) to the stream, at most every LIVE_MIN_INTERVAL seconds. A request the chat
+     * refuses with 429 or 400 is skipped (the next one says the newer thing); any other refusal ends the stream.
+     */
+    private flushStream;
+    private update;
+    /**
+     * Stop sending progress. A sleeping flusher is cancelled; one that is mid-send finishes that one send, unless the turn
+     * itself was cancelled (`hard`). A stream still open when the turn is cancelled is closed with INTERRUPTED, in the
+     * background (the floating status must not spin until the chat's limit).
+     */
+    close(hard?: boolean): void;
+    private interrupt;
+    /**
+     * The turn is over: the user gets `parts`, in order. With a stream the first part is its final message (in the place
+     * of the status) and the others follow; without one they are NEW messages, and the progress message is then retired.
+     * The thumbs (`feedback`) and suggested replies go under the LAST part, and nowhere else.
+     */
+    finish(parts: readonly string[], options?: FinishOptions): Promise<void>;
+    /** Stop the live view and wait for what is still on its way: the stream's opening, the last edit, a closing stream. */
+    private quiesce;
+    /**
+     * The stream opened and the chat later refused an update of it, so the progress message took over: the stream is still
+     * closed, with the first part of the answer when the chat takes that. Returns what is left to send as messages.
+     */
+    private closeRefusedStream;
+    /**
+     * The stream's final message is the first part of the answer (the chat then draws its AI label and thumbs); the other
+     * parts follow as messages. A final the chat refuses is sent as a message of its own, so the answer is never lost.
+     */
+    private finishStream;
+    /** Wait until FINAL_SETTLE_SECONDS have passed since the last progress edit left. */
+    private settle;
+    /**
+     * The answer is posted below: delete the progress message. The chat may refuse, and a queue cannot delete; the message
+     * is then edited down to one line, so it does not sit above the answer as stale progress. Never fails the turn.
+     */
+    private retire;
+    /** Live edits went out, so one may still arrive after `message` replaced the progress message: send it once more. */
+    private reassert;
+}

package/dist/types/turn/progress/status-policy.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What a StatusMessage shows of a turn, and how it closes its live stream: injected, so that a turn of another kind (a
+ * remote agent's) shows its own steps and words through the same status message. `TurnStatusPolicy` is a Claw turn's.
+ */
+import type { OutMessage } from "../../ports/surface.js";
+import { LiveView } from "../live-view.js";
+import type { Step } from "../step.js";
+import { type FinishOptions } from "./answer-messages.js";
+/** The agent's text streamed into a bubble stops growing here; the answer still comes whole. */
+export declare const STREAM_TEXT_MAX = 6000;
+/** What a status message needs of a live view: its first line, its text, its status lines and the setup flag. */
+export interface LiveViewLike {
+    readonly header: string;
+    /** Setup is running: one transient line at the end. */
+    preparing: boolean;
+    render(): string;
+    /** The view as a floating status's lines; `withWords`: the agent's own words and plan may be shown (a 1:1 chat). */
+    statusLines(withWords: boolean): string[];
+}
+/** Everything the stream's last message is decided from. */
+export interface StreamFinishInput {
+    /** What the bubble shows now. */
+    readonly streamed: string;
+    /** What the policy would stream now (`streamable(streamed)`). */
+    readonly streamable: string;
+    /** The answer's messages as they would be sent without a stream. */
+    readonly messages: readonly OutMessage[];
+    readonly parts: readonly string[];
+    readonly options: FinishOptions;
+}
+/** The stream's final message, and what follows it as messages of their own. */
+export interface StreamFinish {
+    readonly final: OutMessage;
+    readonly rest: readonly OutMessage[];
+}
+export interface StatusPolicy<S> {
+    readonly view: LiveViewLike;
+    /** Fold one step in; true when what is shown changed. */
+    applyStep(step: S): boolean;
+    /** The text the bubble should hold now, given what it shows (`streamed`); '' when there is nothing to stream. */
+    streamable(streamed: string): string;
+    /**
+     * The final message when the bubble holds streamed text (`input.streamed` not ''); undefined: the default (the text
+     * as it stands, and the answer after it unless it ends with the answer).
+     */
+    finishStream?(input: StreamFinishInput): StreamFinish | undefined;
+}
+/**
+ * The default way a stream that holds text closes: the final keeps all of it (the chat refuses a stream whose content
+ * shrinks). When it ends with the answer, that is the whole of it (thumbs and replies go on it); otherwise the answer
+ * follows as messages of its own.
+ */
+export declare function defaultStreamFinish(input: StreamFinishInput): StreamFinish;
+/**
+ * A Claw turn's status: the LiveView of its steps, and with `streamText` the agent's whole model turns and the one being
+ * written, streamed into the answer's bubble up to STREAM_TEXT_MAX.
+ */
+export declare class TurnStatusPolicy implements StatusPolicy<Step> {
+    readonly view: LiveView;
+    private readonly streamText;
+    private readonly said;
+    private partial;
+    constructor(view: LiveView, streamText: boolean);
+    applyStep(step: Step): boolean;
+    streamable(streamed: string): string;
+}

package/dist/types/turn/progress/status-text.d.ts

@@ -0,0 +1,10 @@
+/** A status update is at most this many characters ... */
+export declare const STATUS_MAX_CHARS = 1000;
+/** ... and this many bytes of UTF-8. */
+export declare const STATUS_MAX_BYTES = 1024;
+export declare const STATUS_JOIN = " \u00B7 ";
+/**
+ * Status lines as one status update: whitespace collapsed, the lines joined by " · ", cut to the limits by keeping the
+ * END (the newest) after a leading "…", never in the middle of a character's combining marks.
+ */
+export declare function statusText(lines: readonly string[]): string;

package/dist/types/turn/progress/stream-handle.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One live stream in reply to one user message, as the turn follows it: whether it is open, whether it can still be
+ * closed, what was streamed into it, and how old it is. The channel adapter behind `openStream` paces the requests and
+ * keeps one stream per conversation; this keeps the turn's view of it (the Python worker's `TeamsStream` state).
+ */
+import type { Clock } from "../../ports/clock.js";
+import type { OutMessage, StreamRefused } from "../../ports/surface.js";
+import { type Result } from "../../result.js";
+import { type TurnSurface } from "../ports.js";
+/** A refusal that leaves the stream usable: throttled (429), or this one update not taken (400). */
+export declare function isPassing(refusal: StreamRefused): boolean;
+export declare class StreamHandle {
+    private readonly surface;
+    private readonly replyTo;
+    private readonly clock;
+    private stream;
+    private broken;
+    private closed;
+    private openedAt;
+    /** The text streamed into the bubble so far ('' : only status so far). */
+    streamed: string;
+    constructor(surface: TurnSurface, replyTo: string, clock: Clock);
+    /** Updates can be sent: it opened, and neither failed nor closed. */
+    get open(): boolean;
+    /** A final message can still be tried: it opened and is not closed (a refused update leaves it closable). */
+    get closable(): boolean;
+    /** Seconds since it opened. */
+    age(): number;
+    /** Open it with its first status. */
+    start(status: string): Promise<Result<void, StreamRefused>>;
+    private refused;
+    private usable;
+    /** A new status (shown only until text is streamed). */
+    inform(status: string): Promise<Result<void, StreamRefused>>;
+    /** The streamed text so far: what was streamed before must be the start of it (the channel refuses anything else). */
+    emit(text: string): Promise<Result<void, StreamRefused>>;
+    /** Close it with `message`, the message that stays in the chat. */
+    final(message: OutMessage): Promise<Result<void, StreamRefused>>;
+}