@primusclaw/personal-agent 0.0.0-stage → 0.1.0

package/dist/types/assistant/chat.d.ts

@@ -0,0 +1,166 @@
+/**
+ * A 1:1 chat that talks to the person's one assistant in Claw instead of to a session (teams_agent/assistant.py, the chat half).
+ *
+ * With the assistant on for a person, their message goes to the assistant and returns at once: nothing waits for an answer and
+ * nothing locks the chat. What the assistant says comes back later as an `assistant.say` notification (proactive). The message
+ * opens a receipt under it ("Got it, working on it…") that the turn's steps move and the reply closes.
+ */
+import type { JsonObject } from "../json.js";
+import type { Lang } from "../locales/lang.js";
+import type { ClawAssistantPort, ClawSessionsPort } from "../ports/claw/index.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { Random } from "../ports/random.js";
+import type { StorePort } from "../ports/store/index.js";
+import type { Conversation, InboundFile } from "../ports/surface.js";
+import type { DirectChat } from "../direct-chat/direct-chat.js";
+import { type MessageFiles } from "./files.js";
+import { type StepLabel } from "./follow.js";
+import type { Receipts } from "./receipts.js";
+/** A Claw that answers "no assistant here" is not asked again for this long. */
+export declare const OFF_SECONDS = 60;
+/** Each string of an attached session told to the assistant is at most this long (understanding.CONTEXT_TEXT_MAX). */
+export declare const CONTEXT_TEXT_MAX = 200;
+export type ChatStore = Pick<StorePort, "now" | "prefs" | "sessions" | "remoteState"> & {
+    readonly links: Pick<StorePort["links"], "clawUserIdOf">;
+};
+/** The reply style's switches the assistant reads (style.py). */
+export interface AssistantStyle {
+    readonly assistantProgress: boolean;
+    readonly assistantStreamSay: boolean;
+}
+export interface AssistantChatOptions {
+    readonly store: ChatStore;
+    readonly claw: {
+        readonly assistant: Pick<ClawAssistantPort, "session" | "send">;
+        readonly sessions: Pick<ClawSessionsPort, "turn" | "interrupt" | "stream" | "uploadFiles">;
+    };
+    /** Whether the person's subscription has the assistant's events (`Subscriptions.hasAssistantTypes`); undefined: no notifications. */
+    readonly hasAssistantTypes: ((userId: string) => boolean) | undefined;
+    readonly receipts: Receipts;
+    readonly directChat: DirectChat;
+    readonly clock: Clock;
+    readonly random: Random;
+    readonly logger: Logger;
+    readonly stepLabel: StepLabel;
+    readonly style: () => AssistantStyle;
+    /** ASSISTANT_ENABLED. */
+    readonly enabled: boolean;
+    /** ASSISTANT_USERS, lower case (empty: everybody the switch is on for). */
+    readonly users: ReadonlySet<string>;
+    /** TEAMS_ASSISTANT_UNDERSTANDING_USERS, lower case (empty: nobody). */
+    readonly understanding: ReadonlySet<string>;
+    /** CLAW_PLUGIN_ID: named on each message; undefined for none. */
+    readonly pluginId: number | undefined;
+    /** A chat turn of the old kind is running for this person: it is let finish. */
+    readonly legacyTurn: (userId: string) => boolean;
+    readonly files: MessageFiles | undefined;
+    readonly onFilesDropped: (path: string, count: number) => void;
+    /** The locale of the client the message being handled came from ("" none). */
+    readonly clientLocale?: () => string;
+    /** `/board` (assistant.py `board`). */
+    readonly board: {
+        show(userId: string, credential: string, conversation: Conversation): Promise<void>;
+    };
+    /** The router's reading of commands (commands.py parse_command, command_args). */
+    readonly commands: {
+        parse(text: string): string | undefined;
+        args(text: string, name: string): string | undefined;
+    };
+}
+/** Told (session id, message id; null when Claw queued it) once Claw has taken a message (the Stop card of a phone's message). */
+export type OnSent = (sessionId: string, messageId: string | null) => void;
+export declare class AssistantChat {
+    private readonly o;
+    private offUntil;
+    private readonly switched;
+    constructor(o: AssistantChatOptions);
+    /** The assistant is on for this person: the switch is on, and they are listed (an empty list is everybody). */
+    forUser(userId: string): boolean;
+    /**
+     * This person's 1:1 chat talks to the assistant: it is on for them, the assistant can reach them, Claw has an assistant, and no
+     * turn of the old kind is still running for them.
+     */
+    on(userId: string): boolean;
+    /** Every 1:1 message of this person that is not an exact command goes to their assistant first. */
+    understands(userId: string): boolean;
+    /** The assistant can answer this person: their subscription has its events and their Claw user id is known. */
+    reachable(userId: string): boolean;
+    forget(userId: string): void;
+    /** What a message of files and no words says to the assistant. */
+    filesOnly(lang: Lang): string;
+    private langOf;
+    /**
+     * A message of a person the assistant understands, with the chat's context. True when the assistant has it; otherwise the
+     * person was told it could not be reached and nothing else was done with it.
+     */
+    understand(request: {
+        userId: string;
+        credential: string;
+        modelKey: string;
+        prompt: string;
+        context: JsonObject;
+        lang: Lang;
+        conversation: Conversation;
+        files: readonly InboundFile[];
+        onSent?: OnSent;
+    }): Promise<boolean>;
+    /**
+     * A 1:1 message that is not a command. True: the assistant has it (or the person was told it could not be sent). False: it is
+     * for a session, as before. `attached` (only where remote agents are on) is told as `channel_context.attached`.
+     */
+    route(request: {
+        userId: string;
+        credential: string;
+        prompt: string;
+        conversation: Conversation;
+        files: readonly InboundFile[];
+        attached?: JsonObject | null;
+        onSent?: OnSent;
+    }): Promise<boolean>;
+    /**
+     * Does this message go to the assistant? A person's first one does only when the session they had in Claw is not busy (that
+     * work finishes where it started); after that it always does. A Claw that cannot say keeps the old path for now.
+     */
+    private takes;
+    /** Hand the message to the assistant and return: false when this Claw has no assistant (the caller carries on the old way). */
+    private sayTo;
+    /**
+     * Acknowledge the message (receipt or typing), follow its turn into the receipt, and send it with `send` (given the assistant's
+     * session id, and `ready`, which `send` awaits just before the message goes to Claw, after its files). The turn in front of
+     * the message is read beside the receipt being opened, so that only the message's own turn closes its receipt; `ready` waits
+     * for it, then starts following the turn and waits (at most FOLLOW_OPEN_SECONDS) until Claw has answered the stream's request:
+     * the requests to Claw come in one order (the turn in front, the stream, the message), and a turn Claw starts at once cannot
+     * say its first step before the stream is there. `ok` when the assistant has it; otherwise Claw's refusal (undefined when it
+     * did not answer).
+     */
+    private handTo;
+    /** Tell `onSent` that Claw took a message; what it does with that never fails the message. */
+    private tellSent;
+    private handOverFiles;
+    /** Follow the turn that answers this message into its receipt: undefined without a receipt or with progress off. */
+    private follow;
+    /**
+     * The person sees at once that their message was taken: the receipt under it, or (none can be opened) the typing indicator.
+     * Never fails the message. In a chat that is an agent's window the receipt's words start with Clawy's head.
+     */
+    private acknowledge;
+    private attachedReader;
+    /** The message did not reach the assistant: said in the receipt's place when one is open (it closes it), else as a message. */
+    private notTaken;
+    /**
+     * What to say to `/new`, `/sessions` and `/repo`, which the assistant makes needless (it keeps one conversation and a task of its
+     * own for each thing asked), in the chat's language (the router's `said_in`); undefined for anything else. Nothing is done.
+     */
+    hiddenCommand(said: string, lang: Lang): string | undefined;
+    /** `/board`: the person's work items, and a card for each one that waits for them. */
+    board(userId: string, credential: string, conversation: Conversation): Promise<void>;
+    /**
+     * `/stop`: interrupts what the assistant is doing this moment; a task is stopped by name. `onlyMessage`: interrupt only while
+     * Claw's running turn answers that message (a Stop card's turn, read just before the interrupt goes); false, with nothing said
+     * or interrupted, when it does not.
+     */
+    stop(_userId: string, credential: string, conversation: Conversation, onlyMessage?: string): Promise<boolean>;
+}
+/** The session a chat is attached to as the assistant is told it: its text and yes/no fields, each text clipped. */
+export declare function attachedOf(attached: JsonObject | null): JsonObject | null;

package/dist/types/assistant/citation-sources.d.ts

@@ -0,0 +1,20 @@
+export declare const CITATION_NAME_MAX = 80;
+export declare const SOURCE_URL_MAX = 2048;
+/** What of a title is read at all (Claw sends at most 80 code points): bounded work, whatever comes. */
+export declare const SOURCE_TITLE_INPUT_MAX = 1000;
+/** `urlsplit(url).hostname` of an address `sourceUrl` accepted. */
+export declare function hostnameOf(url: string): string | undefined;
+/** `urllib.parse.unquote_plus`: `+` is a space, `%XX` is decoded in each ASCII run, anything else kept. */
+export declare function unquotePlus(text: string): string;
+/**
+ * `raw` when it can be a source's link: an absolute http(s) address with a host, no credentials (neither in it as a
+ * user nor as a query or fragment parameter), no whitespace, control, format or markup character (`<>"'` and the like),
+ * nothing a credential mask would touch, at most SOURCE_URL_MAX characters. Undefined otherwise.
+ */
+export declare function sourceUrl(raw: unknown): string | undefined;
+/**
+ * A source's title as a citation shows it: one plain line, without markup, tags, character references, a leading
+ * heading, list or quote marker, addresses, token-like runs or hidden characters, at most CITATION_NAME_MAX characters,
+ * masked before and after; the host when nothing is left.
+ */
+export declare function sourceName(raw: unknown, host: string): string;

package/dist/types/assistant/citations.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The Teams citations of an assistant reply: the `sources` of an `assistant.say` (`[{n, url, title, kind}]`, which Claw
+ * sends only from the turn's own lookups) become one source card each for the `[n]` its text writes. The text itself is
+ * never changed (its words may already be on screen, streamed).
+ *
+ * Lengths and cuts count code points, white space is Python's `str.isspace`, and the patterns read Unicode the way the
+ * Python worker's `re` does (`\w`, `\d`, `\b` and IGNORECASE over all of Unicode). The address handling follows
+ * `urllib.parse.urlsplit` itself rather than the WHATWG `URL`, which normalises (lower-cases, punycodes, resolves dots,
+ * percent-encodes) where `urlsplit` only splits; `citation-sources.ts` has it.
+ */
+import type { Citation } from "../ports/surface.js";
+export { CITATION_NAME_MAX, SOURCE_TITLE_INPUT_MAX, SOURCE_URL_MAX, sourceName } from "./citation-sources.js";
+/** Teams shows at most 20 citations on a message. */
+export declare const CITATIONS_MAX = 20;
+export declare const CITATION_ABSTRACT_MAX = 160;
+/** What a source's `kind` is shown as on its card; any other kind is "Source". */
+export declare const SOURCE_KINDS: ReadonlyMap<string, string>;
+/** `text` with markdown's backslash escapes resolved (`\-` is `-`), as a renderer reads it. */
+export declare function unescapeMarkdown(text: string): string;
+/** Whether the text can make a link, read as it is shown: with its backslash escapes resolved (`www\.x` is `www.x`). */
+export declare function makesLink(text: string): boolean;
+/**
+ * The numbers the text cites as `[n]` on their own, outside every bracket, and none at all in a text that can make a
+ * link (`makesLink`): the router is told to put addresses in `sources` and never in the text, so no `[n]` can be, or be
+ * inside, a link to an address of the model's. An escaped bracket is no bracket; an unclosed `[` leaves what follows it
+ * uncited. (UTF-16 units: an escape that skips the first half of a surrogate pair lands on the second, which is no
+ * bracket, so it skips the same code point Python does.)
+ */
+export declare function citedNumbers(text: string): Set<number>;
+/**
+ * The Teams citations of an assistant reply: one per source it carries (`[{n, url, title, kind}]`) whose `[n]` the
+ * text has, in number order, at most CITATIONS_MAX. A source that is not well formed, repeats a number or is not cited
+ * in the text is left out.
+ *
+ * One difference from Python, which JSON parsing makes: `{"n": 1.0}` is a float there (refused) and the number 1 here
+ * (accepted).
+ */
+export declare function citationsFromSources(text: string, sources: unknown): Citation[];

package/dist/types/assistant/confirm-outcome.d.ts

@@ -0,0 +1,11 @@
+import type { Lang } from "../locales/lang.js";
+type Fields = Readonly<Record<string, unknown>>;
+/** An ISO time as the person reads it: their wall clock in the trigger's timezone, `2026-11-07 09:00` (else the text as sent). */
+export declare function localTime(at: unknown, zone: string): string;
+/** What came of a press on a drafted comment's card, or undefined for what every card says alike (answered before, lapsed). */
+export declare function commentOutcome(out: Fields, lang: Lang): string | undefined;
+/** What came of a press on an instruction card (`devenv_send`): sent, as which item, or why not. */
+export declare function devenvSendOutcome(status: string, out: Fields, lang: Lang): string;
+/** What came of a press on a held write's card of `kind`, in one line: Claw's answer said plainly. */
+export declare function confirmOutcome(kind: string, out: Fields, lang: Lang): string;
+export {};

package/dist/types/assistant/devenv-hide-outcome.d.ts

@@ -0,0 +1,4 @@
+import type { Lang } from "../locales/lang.js";
+type Fields = Readonly<Record<string, unknown>>;
+export declare function devenvHideOutcome(status: string, out: Fields, lang: Lang): string;
+export {};

package/dist/types/assistant/events.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What an assistant event asks of the chat beyond its words (teams_agent/assistant.py): a command it puts to the person
+ * (`confirm_action`), a write Claw holds for them (`confirm_write`), the replies to tap under it (`suggested_replies`), a pull
+ * request a result names, and what it says of an agent session on the person's machine (`remote`, proactive.py). Every field is
+ * Claw's and is read defensively: anything not of the expected shape is as if absent.
+ */
+import type { Lang } from "../locales/lang.js";
+import type { SuggestedReply } from "../direct-chat/direct-chat.js";
+/** A result's words that link a pull request: its card offers to watch it. */
+export declare const PULL_LINK: RegExp;
+/** Code points of one of Claw's suggested replies (Claw sends at most 30): a button's few words. */
+export declare const SUGGESTED_REPLY_MAX = 30;
+/** Teams shows the first three suggested replies only. */
+export declare const SUGGESTIONS_MAX = 3;
+/** The writes Claw holds for the person that this worker draws as a card. */
+export declare const CONFIRM_KINDS: readonly ["trigger_create", "trigger_cancel", "devenv_send", "github_comment", "devenv_hide"];
+/** The default replies under what the assistant said: (what the button says, what it sends). */
+export declare const ASSISTANT_SUGGESTED_REPLIES: Readonly<Record<Lang, readonly SuggestedReply[]>>;
+type Event = Readonly<Record<string, unknown>>;
+/** A pull request's link as people say it in a chat: #381. */
+export declare function shortPull(url: string): string;
+export interface ConfirmAction {
+    readonly channelMessageId: string;
+    readonly name: string;
+    readonly args: string;
+}
+/**
+ * The command an `assistant.say` puts to the person (the assistant did not run it, since the message was not that command typed
+ * whole); undefined when it carries none that could be one. `exactCommand` is the router's test of a command typed whole.
+ */
+export declare function confirmActionOf(event: Event, exactCommand: (text: string) => boolean): ConfirmAction | undefined;
+export interface ConfirmWrite {
+    readonly confirmationId: string;
+    readonly kind: (typeof CONFIRM_KINDS)[number];
+    readonly allowLabel: string;
+}
+/** The write Claw holds for the person (`confirm_write` of an `assistant.say`); undefined when it carries none this worker draws. */
+export declare function confirmWriteOf(event: Event): ConfirmWrite | undefined;
+/**
+ * The suggested replies under an `assistant.say` (none under anything else, or with the style off): Claw's own, each one plain
+ * line that is no command, else the defaults in the person's language (`lang`; without it, the language of `text`).
+ */
+export declare function suggestedRepliesOf(event: Event, text: string, styleOn: boolean, lang?: Lang): SuggestedReply[];
+export interface RemoteNotice {
+    readonly kind: "done" | "needs_you" | "error";
+    readonly sessionId: string;
+    readonly ask: Event | undefined;
+    readonly machine: string;
+    readonly agent: string;
+}
+/** What an `assistant.say` says of an agent session on the person's machine, or undefined for any other message. */
+export declare function remoteNoticeOf(event: Event): RemoteNotice | undefined;
+export {};

package/dist/types/assistant/failures.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How the assistant's flows tell Claw's failures apart (the Python worker's `except ClawError`, `except httpx.HTTPError`,
+ * `except (ValueError, KeyError)`): a refusal with a status, no answer at all, an answer this client does not understand. Anything
+ * else is a bug and is not caught.
+ */
+import { ClawError } from "../claw/errors.js";
+/** Claw answered with an error status. */
+export declare function refusal(error: unknown): ClawError | undefined;
+/** No answer at all (the request may or may not have arrived). */
+export declare function unreachable(error: unknown): boolean;
+/** An answer this client does not understand (the Python worker's `ValueError` from reading it). */
+export declare function answerInvalid(error: unknown): boolean;
+/** Any of Claw's failures: refused, unreachable, or an answer not understood. */
+export declare function clawFailure(error: unknown): boolean;
+/** Rethrows anything that is not one of Claw's failures. */
+export declare function onlyClawFailures(error: unknown): void;

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

@@ -0,0 +1,37 @@
+import type { JsonObject } from "../json.js";
+import type { ClawSessionsPort } from "../ports/claw/index.js";
+import type { Logger } from "../ports/logger.js";
+import type { Conversation, InboundFile } from "../ports/surface.js";
+/** Where `ClawPort.sessions.uploadFiles` says an upload is; Claw names it by the rest. */
+export declare const UPLOADS_ROOT = "/workspace/.uploads/";
+export interface FetchedUpload {
+    readonly name: string;
+    readonly mediaType: string;
+    readonly bytes: Uint8Array;
+}
+/** The channel's side of a message's files (W3's inbound): fetching them, and how a failure and a folder are worded. */
+export interface MessageFiles {
+    fetch(files: readonly InboundFile[]): Promise<{
+        fetched: FetchedUpload[];
+        failed: [name: string, why: string][];
+    }>;
+    /** The folder under .uploads/ one message's files go to. */
+    uploadFolder(messageId: string): string;
+    /** What the person is told about files that did not reach the agent. */
+    failedLine(failed: readonly (readonly [string, string])[]): string;
+}
+export interface HandOverDeps {
+    readonly claw: Pick<ClawSessionsPort, "uploadFiles">;
+    /** Undefined where this worker takes no files: they are named back. */
+    readonly files: MessageFiles | undefined;
+    readonly logger: Logger;
+    /** (path, how many) of a message's files did not reach Claw: counted for /metrics. */
+    readonly onDropped: (path: string, count: number) => void;
+}
+export declare function handOver(deps: HandOverDeps, call: {
+    credential: string;
+    sessionId: string;
+    folder: string;
+    files: readonly InboundFile[];
+    conversation: Conversation;
+}): Promise<JsonObject[]>;

package/dist/types/assistant/finish.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How a press on one of the assistant's cards ends (teams_agent/assistant.py `_finish`): the pressed card is replaced by `edited`
+ * (a note when it is text), and `said` (by default the same text) is said as a new message, since Teams on a phone does not redraw
+ * an edited card. `said` may be a card of its own, which can be pressed again.
+ */
+import type { CardClick } from "../approvals/click.js";
+import type { OutMessage } from "../ports/surface.js";
+export declare function finish(click: CardClick, edited: OutMessage | string, said?: OutMessage | string): Promise<void>;

package/dist/types/assistant/follow.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The assistant's turn, followed live while it answers a message, so that its receipt moves (teams_agent/assistant_follow.py).
+ *
+ * The turn's live stream says each tool it calls (`toolUsed`) and the words of its reply as the model writes them
+ * (`toolTextDelta`); this shows the step it is on, then the words, in the receipt. The reply itself still comes by notification
+ * and closes the receipt. Best effort: a stream that cannot be opened, breaks or says nothing leaves the receipt as it was. Only
+ * the live part is read (`LIVE_ONLY`), until the turn has spoken or ended, the receipt is closed, or FOLLOW_SECONDS have passed.
+ */
+import type { SseEvent } from "../claw/model.js";
+import type { Lang } from "../locales/lang.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { Receipt } from "./receipt.js";
+/** An event id later than every id Claw gives: the stream sends no history, only what happens from now on. */
+export declare const LIVE_ONLY = "claw-99999999999999";
+export declare const FOLLOW_SECONDS = 180;
+/** How long a message waits for its turn's stream to open (`TurnFollower.waitOpen`); later, it is sent anyway. */
+export declare const FOLLOW_OPEN_SECONDS = 2;
+export declare const SAY_TOOL = "mcp__assistant__say";
+/** Opens the session's live stream after `after`; closed when `signal` aborts. */
+/** The session's stream from `after`; `onOpen` once Claw has answered its request, before any event. */
+export type OpenStream = (after: string, signal: AbortSignal, onOpen: () => void) => AsyncIterable<SseEvent>;
+/** The step a tool call is, in the person's language (step_labels.lookup_label). */
+export type StepLabel = (tool: string, lang: Lang) => string;
+/**
+ * Whether a say's terminal toolUsed event says it was sent: not when the call failed, or Claw answered it with a refusal
+ * (`{"ok": false, ...}` as its `description`).
+ */
+export declare function said(data: Readonly<Record<string, unknown>>): boolean;
+export interface FollowerOptions {
+    readonly open: OpenStream;
+    readonly receipt: Receipt;
+    readonly lang: Lang;
+    /** Stream the reply's words into the receipt (style `assistant_stream_say`). */
+    readonly streamSay: boolean;
+    readonly stepLabel: StepLabel;
+    readonly clock: Clock;
+    readonly logger: Logger;
+}
+/**
+ * One message's turn, followed into its receipt: `start` before the message is handed over, then `answers(messageId)` with the
+ * id Claw gave it, or `answers(undefined)` when there is none (then nothing is shown).
+ */
+export declare class TurnFollower {
+    private readonly options;
+    private messageId;
+    private known;
+    private readonly early;
+    private readonly steps;
+    private readonly stop;
+    private knownWaiters;
+    /** Settles when following has ended (for tests and orderly shutdown). */
+    done: Promise<void>;
+    private markOpen;
+    /** Claw has answered the stream's request (or it could not open at all): the turn's events reach it from now on. */
+    private readonly opened;
+    constructor(options: FollowerOptions);
+    start(): void;
+    /**
+     * Wait, at most `seconds`, until Claw has answered the stream's request, so that a message sent after it cannot have its turn's
+     * first event go by before the stream is there (the stream reads only what comes after it opens: LIVE_ONLY). False when it
+     * did not open in time (the receipt then shows what reaches it, as before). A stream that could not open at all ends the wait.
+     */
+    waitOpen(seconds: number): Promise<boolean>;
+    /** The id of the message the followed turn answers; undefined stops following. */
+    answers(messageId: string | undefined): void;
+    private run;
+    private follow;
+    /** Show what `event` says the followed turn did. True when the turn has spoken or ended: nothing more to follow. */
+    private apply;
+    /** The say's own events: its words as the model writes them, or that they will not be said. */
+    private applySay;
+    /** A tool call starts: its step joins the steps shown so far. */
+    private applyStep;
+}

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

@@ -0,0 +1,12 @@
+/** What the assembly wires of the assistant (one line each; the views and work-item text are exported from the package root). */
+export { AssistantActionClicks } from "./action-handler.js";
+export { AssistantActions } from "./actions.js";
+export { Board } from "./board.js";
+export { AssistantChat as AssistantChatService } from "./chat.js";
+export type { AssistantChatOptions } from "./chat.js";
+export type { MessageFiles } from "./files.js";
+export { Receipts } from "./receipts.js";
+export { SayPlanner } from "./say.js";
+export { WatchClicks } from "./watch-clicks.js";
+export { WorkClicks } from "./work-clicks.js";
+export { WorkCardClicks } from "./work-handler.js";

package/dist/types/assistant/informative.d.ts

@@ -0,0 +1,9 @@
+/** An informative update is at most 1000 characters and 1 KB. */
+export declare const INFORMATIVE_MAX_CHARS = 1000;
+export declare const INFORMATIVE_MAX_BYTES = 1024;
+export declare const STATUS_JOIN = " \u00B7 ";
+/**
+ * The lines joined by " · " (white space collapsed), cut to INFORMATIVE_MAX_CHARS and INFORMATIVE_MAX_BYTES by keeping the END
+ * (the newest) after a leading "…", never starting with a combining mark.
+ */
+export declare function informativeText(lines: readonly string[]): string;

package/dist/types/assistant/item-of.d.ts

@@ -0,0 +1,2 @@
+import type { WorkItem } from "../claw/model.js";
+export declare function parseWorkItem(raw: unknown): WorkItem | undefined;

package/dist/types/assistant/receipt.d.ts

@@ -0,0 +1,113 @@
+import type { Lang } from "../locales/lang.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { MessageId, OutMessage, StreamRefused, UpdateOptions } from "../ports/surface.js";
+import type { Result } from "../result.js";
+/** Teams closes a stream 10 minutes after its first request; the receipt closes itself before that. */
+export declare const RECEIPT_CLOSE_SECONDS: number;
+/** The reply's words streamed into the receipt stop growing here; the reply itself still comes whole. */
+export declare const STREAM_SAY_MAX = 4000;
+/** What the receipt needs of a live stream (a superset of the Surface's `LiveStream`). */
+export interface ReceiptStream {
+    /** Still open: no final was sent and Teams has not closed it. */
+    readonly open: boolean;
+    /** The text streamed so far ("" none). */
+    readonly streamed: string;
+    /** The stream's message id once Teams gave one ("" before). */
+    readonly streamId: MessageId;
+    /** The person's message the stream answers. */
+    readonly replyTo: MessageId;
+    /** A final may still be refused and then edited into place: the stream has an id and was not closed. */
+    readonly closable: boolean;
+    /** Seconds since the stream's first request. */
+    ageSeconds(): number;
+    /** A status update; once `options.signal` aborts it is given up at once (refused). */
+    inform(text: string, options?: UpdateOptions): Promise<Result<void, StreamRefused>>;
+    /** The reply's words so far; as `inform`. */
+    emit(text: string, options?: UpdateOptions): Promise<Result<void, StreamRefused>>;
+    final(message: OutMessage): Promise<Result<void, StreamRefused>>;
+    /** Replace the posted message `id` (the stream's, once it was closed). */
+    update(id: MessageId, message: OutMessage): Promise<void>;
+    delete(id: MessageId): Promise<void>;
+}
+/** The words a message carries as text ("" for a view). */
+export declare function messageWords(message: OutMessage): string;
+export declare class Receipt {
+    readonly stream: ReceiptStream;
+    readonly conversation: string;
+    readonly lang: Lang;
+    private readonly log;
+    /** Closed, or being closed: nothing more is shown in it. */
+    done: boolean;
+    /** Kept for the answer of a handed-back review. */
+    reserved: boolean;
+    /** The words shown are known not to be said. */
+    voided: boolean;
+    /** The line the reply starts with (direct chat: Clawy's head), shown before its words. */
+    head: string;
+    /**
+     * Which turn of the assistant's session answers the message this receipt stands under (`answeredBy`): its id, once Claw gave
+     * one; for a message Claw queued (no id), the turn it was queued behind, read just before it was sent. `unsent`: the message
+     * is not yet handed to Claw, so no turn there can be answering it.
+     */
+    messageId: string | undefined;
+    behind: string | undefined;
+    unsent: boolean;
+    private want;
+    private sender;
+    private readonly closedWaiters;
+    private readonly closer;
+    /** Aborted when the receipt is dropped: an update on its way is given up. */
+    private readonly updates;
+    constructor(stream: ReceiptStream, conversation: string, lang: Lang, log: Logger);
+    /** The message is not yet handed to Claw (the assistant opened the receipt): nothing Claw says answers it yet. */
+    awaitHandOver(): void;
+    /** The message is being handed to Claw now: from here on a turn may answer it, other than `behind` (a queued one runs after it). */
+    handingOver(behind: string | undefined): void;
+    /** Claw took the message: when it gave the message's id, only the turn of that id answers it (none: it was queued). */
+    takenAs(messageId: string | null | undefined): void;
+    /**
+     * Whether a reply said by the turn `turn` (an `assistant.say`'s `turn_message_id`) may close this receipt: only the message's own
+     * turn's may (stream.py `Receipt.answered_by`). Another turn of the same session says something else, and its words under this
+     * message would read as the answer to it. Nothing Claw says before the message is handed over answers it, not even a reply that
+     * names no turn (Claw's notice of a lost turn names none). After that, a reply that names no turn, or a receipt that knows
+     * neither its turn nor the one in front of it, closes it as before.
+     */
+    answeredBy(turn: string | undefined): boolean;
+    /** Resolves when the receipt is closed (or being closed): what follows the turn stops then. */
+    closed(): Promise<void>;
+    /** Show `line` as the status, unless words of the reply are shown already. */
+    showStep(line: string): void;
+    /** Show the reply's words so far: ignored once they no longer grow from what is shown, pass STREAM_SAY_MAX, or are not to be shown. */
+    showText(words: string): void;
+    /** The words shown are not going to be said: nothing more is streamed, and the receipt is not closed with them. */
+    voidText(): void;
+    private show;
+    /** Send the newest wanted update, then the one wanted meanwhile, until there is none; a refusal ends it. */
+    private sendWanted;
+    /** Nothing more is shown, and an update already on its way has gone (or failed), so what was shown is final. */
+    private settle;
+    /**
+     * The worker stops: the receipt is dropped, not closed (Python's shutdown cancels its tasks; the channel ends the stream
+     * itself). Its close timer is cancelled, an update on its way to the channel is given up, and what follows the turn stops
+     * (`closed()` resolves), so nothing keeps the process up.
+     */
+    drop(): void;
+    /** Close the receipt by itself at RECEIPT_CLOSE_SECONDS unless a reply closed it first. */
+    arm(clock: Clock, stillMine: () => boolean, onClose: () => void): void;
+    private closeInTime;
+    /** The reply's words this receipt shows, final: nothing more is shown in it from now on. */
+    shownWords(): Promise<string>;
+    /**
+     * Send `message` (the assistant's reply; `words` its words as written) as the receipt's final message. False: it was not sent
+     * (the caller sends it as a message of its own). Words already streamed are kept (the reply is sent as them, now whole); a view
+     * that starts with them closes the stream with the words and is a message of its own; a reply that does not start with them
+     * replaces them.
+     */
+    deliver(message: OutMessage, words?: string): Promise<boolean>;
+    /**
+     * Close the stream with `message` in place of the words streamed into it. Should Teams refuse a final that does not contain
+     * what was streamed, the stream is closed with those words and that message is edited into `message` (deleted when it cannot be).
+     */
+    private closeReplacing;
+}