@primusclaw/personal-agent 0.0.0-stage → 0.1.0

package/dist/types/security/redact.d.ts

@@ -0,0 +1,2 @@
+/** Credential masking: the one copy every package uses. */
+export { MASK, NOTE, redactLogLine, redactText } from "./redact-text.js";

package/dist/types/subscriptions/event-types.d.ts

@@ -0,0 +1,29 @@
+/** The event types Claw gives a subscription that asks for none in particular. */
+export declare const SUBSCRIPTION_BASE_TYPES: readonly string[];
+/** `approval.requested`: a run, or a work item's worker, waits for the person's decision or answer. */
+export declare const APPROVAL_EVENT: "approval.requested";
+/** The assistant asks the chat to carry out one of the actions a message declared. */
+export declare const ASSISTANT_ACTION: "assistant.action";
+/** What the assistant says, and a work item that needs the person: the events this worker shows as the assistant's words. */
+export declare const ASSISTANT_SAID_TYPES: readonly string[];
+/** The sources Claw gives a subscription that asks for none in particular (a trigger's runs, a long one's). */
+export declare const RUN_SOURCES: readonly string[];
+/** The source of an `approval.requested` a work item holds for its person. */
+export declare const ITEM_SOURCE: "assistant_item";
+export declare const APPROVAL_SOURCES: readonly string[];
+export declare const ASSISTANT_SUBSCRIPTION_TYPES: readonly string[];
+/** `types_version` of a subscription with the assistant's types; 0 is the base types. */
+export declare const ASSISTANT_TYPES_VERSION = 1;
+/** `types_version` of a subscription that also has the approvals of work items. */
+export declare const APPROVALS_TYPES_VERSION = 2;
+/** One rung of what a subscription asks for: its types, its sources (undefined: whatever it has) and the version recorded. */
+export interface WantedTypes {
+    readonly types: readonly string[];
+    readonly sources: readonly string[] | undefined;
+    readonly version: number;
+}
+/**
+ * What a subscription asks for with the assistant on, best first; the next is taken when Claw refuses one (400): a Claw from before
+ * the work items' approvals, or before `assistant.action` (asked only for people whose every message the assistant understands).
+ */
+export declare function wantedTypes(understood: boolean): WantedTypes[];

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

@@ -0,0 +1,3 @@
+/** What the assembly wires of the notification subscription. */
+export { Subscriptions as SubscriptionKeeper } from "./subscriptions.js";
+export { UPGRADE_RETRY_SECONDS } from "./subscriptions.js";

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

@@ -0,0 +1,9 @@
+/** What the subscription keeper needs from the store (W1's repositories) and from Claw (W2's notification subscriptions). */
+import type { ClawNotificationsPort } from "../ports/claw/index.js";
+import type { ConversationRefRepository, LinkRepository, NotifySubscriptionRepository } from "../ports/store/index.js";
+export interface SubscriptionStore {
+    readonly notifySubs: Omit<NotifySubscriptionRepository, "notifySubByRoute">;
+    readonly links: Pick<LinkRepository, "getKey" | "setClawUserId" | "needsClawUserId" | "linkedUsers">;
+    readonly references: Pick<ConversationRefRepository, "getReference">;
+}
+export type ClawSubscriptions = ClawNotificationsPort;

package/dist/types/subscriptions/subscriptions.d.ts

@@ -0,0 +1,69 @@
+import type { Logger } from "../ports/logger.js";
+import type { Random } from "../ports/random.js";
+import type { ClawSubscriptions, SubscriptionStore } from "./ports.js";
+/** Notifications off on Claw, or Claw unreachable: a subscription is tried again at most daily. */
+export declare const RETRY_SECONDS: number;
+/** How often a subscription is looked at in Claw (and mended) with the assistant on. */
+export declare const UPGRADE_RETRY_SECONDS = 600;
+/** Why a person cannot be reached by the events of their work items ("" is reachable). */
+export type Unreachable = "" | "unlinked" | "no_subscription" | "no_user_id" | "no_chat";
+export interface SubscriptionsOptions {
+    readonly store: SubscriptionStore;
+    readonly claw: ClawSubscriptions;
+    readonly random: Random;
+    readonly logger: Logger;
+    /** NOTIFY_WEBHOOK_URL, e.g. http://<worker service>/claw-events. */
+    readonly baseUrl: string;
+    /** ASSISTANT_ENABLED: subscriptions also get the assistant's event types. */
+    readonly assistant?: boolean;
+    /** TEAMS_ASSISTANT_UNDERSTANDING_USERS: whose subscription also asks for `assistant.action`. */
+    readonly understood?: (aadId: string) => boolean;
+    /** ASSISTANT_USERS: whose subscription gets the assistant's types (an empty list: everybody's). */
+    readonly assistantFor?: (aadId: string) => boolean;
+    /** (key) -> the Claw user id the key is of; undefined when that could not be read. Absent: ids are not filled in. */
+    readonly userIdOf?: (key: string) => Promise<string | undefined>;
+}
+export declare class Subscriptions {
+    private readonly store;
+    private readonly claw;
+    private readonly random;
+    private readonly log;
+    private readonly base;
+    private readonly assistant;
+    private readonly understood;
+    private readonly assistantFor;
+    private readonly userIdOf;
+    constructor(options: SubscriptionsOptions);
+    /** This person's subscription gets the assistant's events (so the assistant can reach them). */
+    hasAssistantTypes(aadId: string): boolean;
+    private assistantOnFor;
+    /**
+     * `ensure` for every linked person the assistant is on for, after filling in every missing Claw user id. Returns how many people
+     * were looked at. Never throws.
+     */
+    ensureAll(): Promise<number>;
+    /** Record the Claw user id of every linked person whose link has none. Returns how many were filled in. Never throws. */
+    fillUserIds(): Promise<number>;
+    /** `fillUserIds` for one person: true when an id was recorded now. */
+    fillUserId(aadId: string): Promise<boolean>;
+    /**
+     * Whether the events of this person's work items reach their chat: "" when they do, else why not. The subscription is made or
+     * mended first and the user id filled in, so what is said is the state after trying. Never throws.
+     */
+    reachable(aadId: string): Promise<Unreachable>;
+    /** Make sure this linked person has a subscription (with the assistant's types when it is on). Never throws. */
+    ensure(aadId: string): Promise<void>;
+    private create;
+    /**
+     * With the assistant on, the recorded subscription must be there in Claw, enabled and asking for the assistant's events: looked
+     * at, and mended with one PATCH, at most every UPGRADE_RETRY_SECONDS. One Claw no longer has is forgotten (the caller makes a new
+     * one); one Claw refuses even the assistant's types (400, 404) takes the person back to sessions (`types_version` 0).
+     */
+    private reconcile;
+    /** The best rung the subscription has already, or the best Claw takes; throws Claw's last refusal when it takes none. */
+    private mend;
+    /** Delete this person's earlier subscriptions to this worker: their secret is unknown here, so they would only be refused. */
+    private dropStale;
+    /** /unlink: delete the subscription in Claw (best effort) and forget it here. */
+    remove(aadId: string, key: string | null): Promise<void>;
+}

package/dist/types/text/neutral.d.ts

@@ -0,0 +1 @@
+export declare function neutral(text: string, limit?: number): string;

package/dist/types/text/plain.d.ts

@@ -0,0 +1,6 @@
+/** `" ".join(text.split())` cut to `limit` code points, a cut one ending in "…" (render._clip, approval_view._clip). */
+export declare function clip(text: string, limit: number): string;
+/** `json.dumps(value, ensure_ascii=False)`, with `separators=(",", ":")` when `compact`. */
+export declare function pyJson(value: unknown, options?: {
+    readonly compact?: boolean;
+}): string;

package/dist/types/text/py-chars.d.ts

@@ -0,0 +1,12 @@
+/** The characters Python calls white space and printable (`str.isspace`, `str.isprintable`). */
+/** The code point at `at` of `text`, which must have one there (`ord(text[at])`). */
+export declare function pointAt(text: string, at?: number): number;
+/**
+ * The characters Python's `str.isspace()` is true for, which is also what `\s` matches in a Python `str` pattern
+ * (JavaScript's `\s` lacks `\x1c`-`\x1f` and `\x85`, and has `\ufeff`). For a pattern: `new RegExp(`[${PY_SPACE}]`, "u")`.
+ */
+export declare const PY_SPACE = "\\t\\n\\v\\f\\r\\x1c-\\x20\\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
+/** `ch.isspace()` for one code point. */
+export declare function isPySpace(ch: string): boolean;
+/** `ch.isprintable()` for one code point. */
+export declare function isPyPrintable(ch: string): boolean;

package/dist/types/text/py-json.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `str(value or "")` for a value read from JSON: a falsy value (none, false, 0, "", an empty list or object) is "", a
+ * string is itself, `true` is "True", a number is its digits (or float repr), a list or object is Python's `repr`.
+ */
+export declare function pyStr(value: unknown): string;
+/**
+ * `repr(value)` for a value parsed from JSON (`None`, `True`, `'text'`, `[1, 2]`, `{'a': 1}`). An object's keys are in
+ * its order, which JavaScript keeps for every key but integer-like ones ("2", "10"): those come first, ascending.
+ */
+export declare function pyRepr(value: unknown): string;
+export interface JsonDumpsOptions {
+    /** `indent=`: each nesting level on its own lines, this many spaces deeper (items then end in "," alone). */
+    readonly indent?: number;
+    /** `sort_keys=True`: keys in code-point order, as Python sorts `str`. */
+    readonly sortKeys?: boolean;
+}
+/**
+ * `json.dumps(value, ensure_ascii=False, ...)` for a value parsed from JSON: non-ASCII kept (a lone surrogate too);
+ * `", "` and `": "` separators, or `","` and newlines with `indent`. A key whose value is undefined is left out.
+ * Without `sortKeys`, keys are in the object's order, which JavaScript keeps for every key except integer-like ones
+ * ("2", "10"): those come first, ascending (Python would keep them where JSON had them).
+ */
+export declare function pyJsonDumps(value: unknown, options?: JsonDumpsOptions): string;

package/dist/types/text/py-number.d.ts

@@ -0,0 +1,18 @@
+/** Numbers as Python writes them: `repr(float)`, `str`/`json.dumps` of a parsed JSON number, `f"{x:.{n}f}"`. */
+/**
+ * A number as Python writes it, for a value parsed from JSON: a safe integer as the int JSON gave, anything else as
+ * Python's float `repr` (`1e-07`, `1e+300`). `str` writes the non-finite as `nan`/`inf`, `json.dumps` as `NaN`/
+ * `Infinity`. What JSON cannot tell apart once JavaScript has parsed it is written the likelier way: a float `1.0` was
+ * already the number 1 (an int), a negative zero is the float `-0.0` (JSON's `-0` int is rare), an integer beyond 2^53
+ * is written as the float it became.
+ */
+export declare function pyNumber(value: number, how: "str" | "json"): string;
+/** Python's `repr(float)`: the shortest digits, positional for exponents -4..15, else `d.ddde±XX`. */
+export declare function floatRepr(value: number): string;
+/**
+ * `f"{value:.{digits}f}"`: the exact binary value rounded to `digits` decimals, an exact tie to even, as Python formats
+ * it (for any magnitude and any number of digits).
+ */
+export declare function fixedN(value: number, digits: number): string;
+/** `f"{value:.1f}"`. */
+export declare function fixed1(value: number): string;

package/dist/types/text/py-regex-escapes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Python `re` escapes (in a `str` pattern) as JavaScript `u`-mode pattern text: the classes, anchors and character
+ * escapes Python knows, each read as Python reads it. An escape Python refuses ("bad escape") is refused here too.
+ */
+/** Python's `\w` (letters, numbers and `_` of any script) as a character class. */
+export declare const PY_W: string;
+/** The inside of `PY_W`, to put in a class of one's own (`[${PY_W_CHARS}.-]`). */
+export declare const PY_W_CHARS: string;
+/** Python's `\d` (a decimal digit of any script), to put in a class. */
+export declare const PY_D: string;
+/** Python's `\b` before a word: not preceded by a word character. */
+export declare const PY_B_START: string;
+/** Python's `\b` after a word: not followed by a word character. */
+export declare const PY_B_END: string;
+export declare const START: string;
+export declare const END: string;
+/** Python folds these four together under IGNORECASE; JavaScript's case folding keeps the dotless and dotted apart. */
+export declare const I_VARIANTS = "iI\u0131\u0130";
+export interface EscapeContext {
+    readonly inClass: boolean;
+    readonly ignoreCase: boolean;
+}
+export interface Escape {
+    /** The JavaScript pattern text. */
+    readonly text: string;
+    /** How many characters of the Python source it took. */
+    readonly length: number;
+}
+/** One character as a JavaScript literal; under IGNORECASE, outside a class, `i`, `I`, `ı`, `İ` are one another. */
+export declare function literal(ch: string, context: EscapeContext): string;
+/** The escape that starts at `source[i]` (a backslash), as JavaScript pattern text. */
+export declare function translateEscape(source: string, i: number, context: EscapeContext): Escape;

package/dist/types/text/py-regex.d.ts

@@ -0,0 +1,36 @@
+export { PY_B_END, PY_B_START, PY_D, PY_W, PY_W_CHARS } from "./py-regex-escapes.js";
+/**
+ * Python `re` patterns (on a `str`) as JavaScript regular expressions, for the rules the worker matches text with.
+ * Where the two engines read the same pattern differently, the translation makes JavaScript read it as Python does:
+ *  - `\s` is Python's white space (`\x1c`-`\x1f` and `\x85` in, `\ufeff` out), `\S` the rest;
+ *  - `\d` is a decimal digit of any script (`\p{Nd}`), `\D` the rest;
+ *  - `\w` is a letter, a number or `_` of any script, `\W` the rest, and `\b`/`\B` are boundaries of that `\w`;
+ *  - `^`, `$`, `\A`, `\Z` and `.` are Python's: `$` also matches before a final "\n" (with `m`, before any "\n" only, not
+ *    "\r"), and `.` is anything but "\n" (with `s`, anything);
+ *  - `(?P<name>...)` and `(?P=name)` are Python's named groups; a leading `(?ims)` is the flag; `(?#...)` is a comment;
+ *  - `\-`, `\ `, `\#` (what `re.escape` writes) are the characters themselves, as are `\x..`, `\u....`, `\U........`,
+ *    octal escapes and `\a`; a `{` or `}` that is no quantifier and a `]` outside a class are literal; `{,n}` is `{0,n}`;
+ *  - with the `i` flag, `i`, `I`, `ı` and `İ` all match one another, as Python folds them (JavaScript does not).
+ *    One difference is kept: under `i` JavaScript folds U+0345 (a combining mark) into `\w` through ι, where Python
+ *    does not. Leaving it out would take a scoped `(?-i:...)`, which in V8 turns off the Unicode case folding of every
+ *    class in the pattern (the Kelvin sign then no longer matches `[a-z]`): a far larger difference.
+ * The `u` flag is always on. What has no JavaScript form is refused when the pattern is built, with an InvariantError:
+ * an escape Python refuses, `\N{...}`, a negated class escape inside a class (`[\S]`), inline flags anywhere but at the
+ * start or scoped to a group (`(?s:...)`), a backreference (JavaScript matches one to a group that took no part as
+ * the empty string, where Python fails), and any
+ * other syntax JavaScript cannot read.
+ */
+/** `ch.isalnum()` for one character: a letter or a number of any script. */
+export declare function pyIsAlnum(ch: string): boolean;
+/** Letters A-Z and a-z only, at least one: what `re`'s `[A-Za-z]+` takes (`str.isalpha` would take any script). */
+export declare function isAsciiAlpha(word: string): boolean;
+/**
+ * `re.compile(source, flags)` used with `search`: `regex.exec(text)` finds the first match anywhere. `flags`: `i`, `m`,
+ * `s`, and JavaScript's `g`/`y` for finding every match.
+ */
+export declare function pyRegExp(source: string, flags?: string): RegExp;
+/**
+ * `re.fullmatch(source, text, flags)` as a RegExp: `regex.test(text)` / `regex.exec(text)` match the whole text, the same
+ * on every call (`g`/`y` would make it stateful, so they are refused). `flags`: `i`, `m`, `s`.
+ */
+export declare function pyFullmatch(source: string, flags?: string): RegExp;

package/dist/types/text/py-text.d.ts

@@ -0,0 +1,64 @@
+export * from "./py-chars.js";
+export * from "./py-json.js";
+export * from "./py-number.js";
+/** `text.split()`: the words between runs of white space, none empty. */
+export declare function pySplit(text: string): string[];
+/** `" ".join(text.split())`: one line, single spaces. */
+export declare function squashSpaces(text: string): string;
+/** `text.strip()`, or `text.strip(chars)`. */
+export declare function pyStrip(text: string, chars?: string): string;
+/** `text.lstrip()`, or `text.lstrip(chars)`. */
+export declare function pyLstrip(text: string, chars?: string): string;
+/** `text.rstrip()`, or `text.rstrip(chars)`. */
+export declare function pyRstrip(text: string, chars?: string): string;
+/**
+ * `text.lower()`. JavaScript's `toLowerCase()` is the same full, context-sensitive mapping (final sigma, `İ` to `i̇`),
+ * locale-independent as Python's; checked over every code point (they differ only where Node's Unicode is newer).
+ */
+export declare function pyLower(text: string): string;
+/**
+ * `text.casefold()`: for comparing without case (`ß` and `ss`, `ſ` and `s` fold together; `ı` stays apart from `i`;
+ * no final-sigma context, every `σ`/`ς`/`Σ` folds to `σ`). Per code point, as Python folds.
+ */
+export declare function pyCasefold(text: string): string;
+/** `text.split(None, 1)`: the first word and the rest (its leading white space removed); at most two parts. */
+export declare function splitOnce(text: string): string[];
+/**
+ * At least one character, each a decimal digit of any script (`\p{Nd}`: what `\d` matches in Python's `re`, and what
+ * `int()` reads). NOT Python's `str.isdigit()`, which also takes
+ * superscripts and circled digits (every caller reads ASCII or `\d` input, where the two agree).
+ */
+export declare function isDigits(text: string): boolean;
+/**
+ * `int(text)` for a run of decimal digits of any script (`１２` is 12, `٣` is 3), exactly, of any size; undefined for
+ * anything else.
+ */
+export declare function decimalBigInt(text: string): bigint | undefined;
+/**
+ * `int(text)` as a number: exact up to 2^53, which the counts, hours and ids the rules read are far below; NaN for
+ * anything that is no run of decimal digits, and refused (RangeError) past 2^53 rather than rounded (use
+ * `decimalBigInt` for that).
+ */
+export declare function decimalInt(text: string): number;
+/**
+ * `text.isupper()`: at least one uppercase character, and none that is lowercase or titlecase (the Unicode properties
+ * Python reads: `ℂ` is upper though it has no lowercase form; `ĸ` and `ª` are lowercase though they have no uppercase).
+ */
+export declare function isUpper(text: string): boolean;
+/** `len(text)`: code points. */
+export declare function cpLength(text: string): number;
+/** `text[start:end]`, counted in code points; a negative bound counts from the end, as in Python. */
+export declare function cpSlice(text: string, start: number, end?: number): string;
+/** `text.rfind(sub)`: the code-point index of the last occurrence, -1 when there is none. */
+export declare function cpRfind(text: string, sub: string): number;
+/** `text if len(text) <= limit else text[: limit - 1].rstrip() + "…"`. */
+export declare function clipLine(text: string, limit: number): string;
+/** `text[:limit]`, without splitting a string that is short enough. */
+export declare function cpHead(text: string, limit: number): string;
+/**
+ * `text.splitlines(keepends)`: the lines, without their breaks or (`keepends`) each with its own ("\r\n" is one break);
+ * a trailing break makes no empty last line.
+ */
+export declare function pySplitlines(text: string, keepends?: boolean): string[];
+/** Whether `text` holds a control character: U+0000-U+001F or U+007F (Python's `[\x00-\x1f\x7f]`). */
+export declare function hasControl(text: string): boolean;

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

@@ -0,0 +1,23 @@
+export declare const MAX_ANSWER_CHARS = 3000;
+/** A long answer: at most this many messages (1:1 and group alike), then the link. */
+export declare const MAX_ANSWER_MESSAGES = 3;
+export declare const WHOLE_CUT_NOTE: "\n\n… (the rest did not fit in three messages)";
+/** The web console's page of a session. */
+export declare function deepLink(publicBaseUrl: string, sessionId: string): string;
+/**
+ * The messages that carry a final answer: the whole answer split at paragraph boundaries, at most MAX_ANSWER_MESSAGES
+ * messages, and only what is beyond that is left to the link. In a group the link says that only the asker can open it
+ * (it opens the asker's own Claw session). `lead` is one line in front of the answer.
+ */
+export declare function answerParts(text: string, link: string, group?: boolean, lead?: string): string[];
+/**
+ * `text` as at most `most` messages of at most `limit` characters, each cut at a paragraph or line break when one is near
+ * enough, and never shortened when it fits in `most` messages: a cut is taken only where what is left still fits in the
+ * messages after it. Only a longer text has its last message end in a note that the rest was cut.
+ */
+export declare function wholeParts(text: string, limit?: number, most?: number): string[];
+/**
+ * The messages of the assistant's reply `text` (`wholeParts`), after the words its receipt already shows (`shown`): when
+ * they are a longer start of the reply than the first message would be, they are the first message and the rest follows.
+ */
+export declare function replyParts(text: string, shown?: string): string[];

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

@@ -0,0 +1,42 @@
+import type { Logger } from "../ports/logger.js";
+import type { TurnClaw } from "./ports.js";
+/** One try, then nothing: the answer is already in the chat. */
+export declare const CHANGES_TIMEOUT_SECONDS = 5;
+export interface FileChange {
+    readonly path: string;
+    /** M modified, A added, D deleted, R renamed, ? untracked or unknown. */
+    readonly status: string;
+    /** undefined: not counted (binary, or Claw could not say). */
+    readonly additions: number | undefined;
+    readonly deletions: number | undefined;
+    readonly binary: boolean;
+}
+export interface RepoChanges {
+    /** "/workspace/<name>". */
+    readonly path: string;
+    readonly branch: string | undefined;
+    /** Short sha. */
+    readonly head: string;
+    /** Claw listed fewer files than changed. */
+    readonly truncated: boolean;
+    readonly files: readonly FileChange[];
+    /** What Claw counted (at least the files listed). */
+    readonly totalFiles: number;
+    readonly additions: number;
+    readonly deletions: number;
+}
+export interface Changes {
+    readonly repos: readonly RepoChanges[];
+    readonly truncated: boolean;
+}
+export declare function repoName(repo: RepoChanges): string;
+export declare const totalFiles: (changes: Changes) => number;
+export declare const totalAdditions: (changes: Changes) => number;
+export declare const totalDeletions: (changes: Changes) => number;
+/**
+ * The reply as `Changes`, or undefined when it is not a changes reply or nothing changed. Items that are not what the
+ * contract says are left out one by one, so a single odd file never hides the rest.
+ */
+export declare function parseChanges(reply: unknown): Changes | undefined;
+/** The session's changes, or undefined for anything that means there is nothing to show. Never rejects. */
+export declare function fetchChanges(claw: TurnClaw, key: string, sessionId: string, log: Logger): Promise<Changes | undefined>;

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

@@ -0,0 +1,6 @@
+export declare const TITLE_MAX = 120;
+export declare const SUMMARY_MAX = 280;
+/** One line: whitespace collapsed, cut to `limit` characters with an ellipsis. */
+export declare function clip(text: unknown, limit: number): string;
+/** `text` for a card text block, which reads markdown: its markup characters escaped, so `__init__.py` is not bold. */
+export declare function plain(text: string): string;

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

@@ -0,0 +1,31 @@
+import { type JsonObject } from "./json.js";
+export declare const DELIVER_TOOL = "deliver_file";
+export declare const DELIVERY_NAME_MAX = 200;
+/** Files shown for one turn; a turn that delivers more is told to zip them by the tool's own wording. */
+export declare const DELIVERIES_MAX = 5;
+export declare const INLINE_IMAGE_TYPES: readonly string[];
+/** A message of about 28 KB is refused, so an image is shown only as a data URI that fits. */
+export declare const INLINE_IMAGE_MAX_BYTES = 15000;
+export interface Delivery {
+    readonly id: string;
+    readonly name: string;
+    readonly size: number;
+    readonly contentType: string;
+    readonly caption: string;
+    /** A data URI of the image itself, when it came along and is one the chat can show; '' otherwise. */
+    readonly image: string;
+}
+/**
+ * The file a successful `deliver_file` call delivered, from its terminal toolUsed event; undefined for anything else, and
+ * for a delivery that does not say what it is (an id that is not one, no name, no size).
+ */
+export declare function deliveryOf(tool: string, status: string, data: JsonObject): Delivery | undefined;
+/**
+ * The files an assistant message hands the user (Claw's `files`), as (the worker session the download is under, the file),
+ * read as strictly as a turn's `deliver_file` event: a file that does not say what it is, or names no session, is left out.
+ */
+export declare function assistantDeliveries(event: JsonObject): Array<readonly [string, Delivery]>;
+/** A size as a file manager says it: "512 B", "1.5 KB", "12 MB". */
+export declare function sizeText(size: number): string;
+/** A group chat's line for a delivered file: its name and the link, which only the person who asked can open. */
+export declare function deliveryLine(delivery: Delivery, url: string): string;

package/dist/types/turn/engine/claw-errors.d.ts

@@ -0,0 +1,7 @@
+import { ClawError, ClawUnreachable } from "../../claw/errors.js";
+/** A Claw call failed in a way the turn survives (an error status, no answer, an answer it could not read). */
+export declare function isClawFailure(err: unknown): boolean;
+/** An error status or no answer at all: Python's `(ClawError, httpx.HTTPError)`. */
+export declare function isClawOrNetwork(err: unknown): err is ClawError | ClawUnreachable;
+/** What a log line says about it: the status, or the kind of failure. */
+export declare function statusOrKind(err: ClawError | ClawUnreachable): string | number;

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

@@ -0,0 +1,35 @@
+import type { StatusMessage } from "../progress/status-message.js";
+import type { Step } from "../step.js";
+import type { TurnState } from "../turn-state.js";
+import { type TurnContext } from "./context.js";
+export declare const STREAM_ATTEMPTS = 4;
+/** A wait longer than this in a request is not believed. */
+export declare const MAX_APPROVAL_WAIT_SECONDS: number;
+/** The tool whose call waits for the answer to a question card (Brain's userQuestion event). */
+export declare const QUESTION_TOOL = "ask_user_question";
+/** The stream dropped STREAM_ATTEMPTS times before the turn ended. */
+export declare class StreamKeptDropping extends Error {
+    constructor();
+}
+/** The wait Brain announces in a permissionRequest (`timeout_ms`) in seconds; undefined for anything not a sane number. */
+export declare function waitSeconds(milliseconds: unknown): number | undefined;
+export declare function noteRunning(ctx: TurnContext, state: TurnState, once: {
+    called: boolean;
+}): void;
+export interface ConsumeArgs {
+    readonly sessionId: string;
+    readonly state: TurnState;
+    readonly status: StatusMessage<Step>;
+    readonly running: {
+        called: boolean;
+    };
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * Read the stream until the turn ends; reconnects from the last event if it drops. A turn whose message Claw took at once
+ * starts after the newest event stored before it was sent, so the history it replays is this turn's. A queued one reads
+ * the history Claw sends without `after` (the session's tail): it is told from older turns by coming after the one in
+ * front of it. A Claw whose history marker has no `has_more` compares `after` as text: seen on a connection that had an
+ * `after`, the stream is read once more from where Claw starts it, and every reconnect starts there too.
+ */
+export declare function consume(ctx: TurnContext, args: ConsumeArgs): Promise<boolean>;

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

@@ -0,0 +1,157 @@
+/** Everything one turn runs with: who it acts for, what it sends, where it answers, and what it reports back. */
+import type { Lang } from "../../locales/lang.js";
+import type { PullRef } from "../../claw/model.js";
+import type { Integrations } from "../../plugins/integrations.js";
+import type { ModelRefusalPolicy } from "../../plugins/model-refusal-policy.js";
+import type { Clock } from "../../ports/clock.js";
+import type { Logger } from "../../ports/logger.js";
+import type { PublicErrors } from "../../public-error/public-errors.js";
+import type { Envelope, FetchedFile, InboundFile, OutMessage, UserRef } from "../../ports/surface.js";
+import type { GithubOutcome } from "../github-outcome.js";
+import type { TurnClaw, TurnSurface } from "../ports.js";
+import type { ClawError } from "../../claw/errors.js";
+import type { TurnCards } from "../../ports/turn-cards.js";
+/** What the turn is and whom it acts for. Read only by the turn. */
+export interface TurnRequest {
+    /** The key of the user this turn acts for, and nobody else. */
+    readonly key: string;
+    /** What the user wrote (the session's title, the language of the answer). */
+    readonly text: string;
+    readonly idempotencyKey: string;
+    readonly publicBaseUrl: string;
+    /** The person's message: a live stream answers it (undefined: the turn is shown by an edited message). */
+    readonly streamReplyTo?: string;
+    /** A group chat: no tool input on cards, approvals are recorded and owner-only. */
+    readonly group?: boolean;
+    readonly ownerName?: string;
+    /** Claw will push this user a run's end and its approvals. */
+    readonly notifies?: boolean;
+    /** The model this worker pins its sessions to ('' sends none). */
+    readonly model?: string;
+    /** The model a turn refused for want of a model key is run again on ('' never). */
+    readonly fallbackModel?: string;
+    /** The user's client never sends the chat's thumbs on: the answer gets thumbs of our own. */
+    readonly ownThumbs?: boolean;
+    /** A review turn: the id of the user whose GitHub account the session's tools use (always a new session). */
+    readonly actingAs?: string;
+    /** A review turn: the one pull request the session is bound to. */
+    readonly reviewTarget?: PullRef;
+    /** A review turn: the requester's own linked key, sent beside `key` as the model key. Never logged. */
+    readonly modelKey?: string;
+    /** A review turn: the model its request named. */
+    readonly reviewModel?: string;
+    /** A review turn that may not merge. */
+    readonly reviewOnly?: boolean;
+    /** A review Claw made itself: its session has its first message queued, so nothing is sent and the turn is followed. */
+    readonly attach?: boolean;
+    /** That turn's id when Claw said it ('' when not: it is the session's first turn). */
+    readonly attachMessageId?: string;
+    /** Shown at the top of the progress message from its first post on (a review's acknowledgement). */
+    readonly lead?: string;
+    /** A review asked in a group: the asker, whom its answer @mentions (nobody else). */
+    readonly mention?: UserRef;
+    /** (url, branch) a NEW session is bound to; undefined: no repository. */
+    readonly repo?: readonly [string, string];
+    /** A card with what the session changed follows a finished answer (1:1 chats). */
+    readonly showChanges?: boolean;
+    /** The message(s) this one quotes, as text for the model ('' none). */
+    readonly quote?: string;
+    /** `text` with the address behind each of its links; '' when it is `text` itself. */
+    readonly sent?: string;
+    /** The language the person is answered in (undefined: the language of `text`). */
+    readonly lang?: Lang;
+    /** What the user sent with the message. */
+    readonly files?: readonly InboundFile[];
+}
+/** What the turn tells its caller as it goes. Each is optional; none of them can fail the turn's answer. */
+export interface TurnHooks {
+    /** A fresh credential per call (exchanged tokens expire); without it the request's `key`. */
+    readonly keyProvider?: () => Promise<string>;
+    /**
+     * An approval or question is about to be shown, as `envelope`: false when a card for it is already in a chat (the
+     * notification got there first), and the turn then shows none. `expiresIn`: the seconds Brain waits for the answer.
+     */
+    readonly onApproval?: (sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope) => boolean | undefined;
+    readonly onApprovalSent?: (sessionId: string, toolUseId: string) => void;
+    readonly onApprovalUnsent?: (sessionId: string, toolUseId: string) => void;
+    /** (session, "started" | "delivered" | "failed", Claw message id or ''). */
+    readonly onTurn?: (sessionId: string, what: "started" | "delivered" | "failed", messageId: string) => void;
+    /** Once, when Claw is running this turn's message. */
+    readonly onRunning?: () => void;
+    /** The "Report a problem" message for a turn that went wrong. */
+    readonly reportMessage?: () => OutMessage;
+    /**
+     * A review turn: (answer, link to the session, model, the GitHub results, inline comments, the PR's one sentence) ->
+     * the text posted, the review's one message.
+     */
+    readonly shapeAnswer?: (answer: string, link: string, model: string, results: GithubOutcome[], comments: number, prSummary: string) => string;
+    /** A review turn: each finished GitHub write as it arrives; the line it returns is shown at the top of the progress. */
+    readonly onGithubResult?: (outcome: GithubOutcome, model: string) => string | undefined;
+    /** A review asked of someone else that Claw refused as `acting_as_must_be_self`: true when the asker was told. */
+    readonly asItem?: () => Promise<boolean>;
+    /** Fetches the files the user sent: (the files fetched, [(name, why not)]). */
+    readonly fetchFiles?: (files: readonly InboundFile[]) => Promise<readonly [FetchedFile[], Array<readonly [string, string]>]>;
+    /** (how many) of the message's files did not reach Claw. */
+    readonly onFilesDropped?: (count: number) => void;
+}
+/** The reply style's switches that touch the turn. */
+export interface TurnStyle {
+    /** The agent's text is streamed into the answer's bubble (1:1 chats). */
+    readonly streamText: boolean;
+    /** Suggested replies under a finished 1:1 answer. */
+    readonly suggestedReplies: boolean;
+}
+export interface TurnDeps {
+    readonly claw: TurnClaw;
+    readonly surface: TurnSurface;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly refusals: ModelRefusalPolicy;
+    /** What a person is told of a failure, and what is kept back for the log. */
+    readonly errors: PublicErrors;
+    readonly style: TurnStyle;
+    /** The approval, question and thumbs cards (the approvals' and the feedback feature's). */
+    readonly cards: TurnCards;
+    /** A deployment's MCP servers, named in progress lines (none: the public build's). */
+    readonly integrations?: Integrations;
+}
+/** What the turn records as it runs, for whoever runs something after it. */
+export interface TurnRecord {
+    /** undefined: create a session with this message. */
+    sessionId: string | undefined;
+    /** The model the session is known to have; a turn updates it. */
+    sessionModel: string;
+    /** The model the turn ran on: what the gateway said served it, else what the session asks for. */
+    ranModel: string;
+    /** What the turn left on GitHub. */
+    wrote: GithubOutcome[];
+    /** A review turn: the sentence of what the pull request does. */
+    prSummary: string;
+    /** What the turn ended with. */
+    finalAnswer: string;
+    /** A review turn that Claw answered 401: the asker's credentials were not taken. */
+    refusal: ClawError | undefined;
+    /** The review was asked for again as the reviewer's item, and the asker told. */
+    moved: boolean;
+    /** Where the files are, for the model (set once they are in the session). */
+    filesNote: string;
+    /** The files, once fetched (once per turn). */
+    fetched: FetchedFile[] | undefined;
+    /** The newest event the session held just before this turn's message was sent: the stream is read after it. */
+    streamAfter: string | undefined;
+}
+export interface TurnContext {
+    readonly request: TurnRequest;
+    readonly hooks: TurnHooks;
+    readonly deps: TurnDeps;
+    readonly record: TurnRecord;
+}
+export declare function newRecord(sessionId: string | undefined, sessionModel?: string): TurnRecord;
+export declare function credential(ctx: TurnContext): Promise<string>;
+/** The language the turn's own lines are said in: the person's, else that of what they wrote. */
+export declare function langOf(ctx: TurnContext): Lang;
+/**
+ * What Claw is sent: the quoted messages, then what the user wrote (with the addresses behind its links), then where the
+ * files they sent are. `text` stays the words alone: the session's title, the language of the answer.
+ */
+export declare function messageOf(ctx: TurnContext): string;