@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/remote/tail.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Where a session's events end now, so a chat that attaches (or sends a message) does not replay them: the id of the last event,
+ * what the agent said about its modes, whether it is at work (text or tool events after the last turn end: a turn of this chat's,
+ * or the agent going on by itself, which the events do not tell apart), the steps that have begun and not ended since then, and the
+ * permission requests nobody has answered yet.
+ */
+import type { SseEvent } from "../claw/model.js";
+import { type RemoteStep } from "./events.js";
+/** Events read per page of the replay; a shorter page is the last. */
+export declare const TAIL_PAGE = 1000;
+export interface SessionTail {
+    /** The id of the last event ('' none). */
+    readonly cursor: string;
+    readonly mode: string | null;
+    readonly modes: readonly string[];
+    readonly unattended: boolean | null;
+    readonly modeFlags: Readonly<Record<string, boolean>> | null;
+    /** The session only watches a conversation open in a terminal. */
+    readonly readOnly: boolean;
+    /** What is sent is typed into a terminal on the machine. */
+    readonly terminal: boolean;
+    /** Output after the last turn end. */
+    readonly active: boolean;
+    /** The steps begun and not ended since the last turn end. */
+    readonly steps: readonly string[];
+    /** The permission requests nobody has answered, while a turn is open. */
+    readonly pending: readonly Readonly<Record<string, unknown>>[];
+    /** ... their action ids. */
+    readonly asked: readonly string[];
+}
+/** One stored event as the replay lists it. */
+export interface EventRow {
+    readonly id: string;
+    readonly type: string;
+    readonly data: unknown;
+}
+/** The event a replayed row is, as the stream would have sent it (a `data` that is no object says nothing). */
+export declare function rowEvent(row: EventRow): SseEvent;
+/** The rows of a session's events folded into its tail, step by step. */
+export declare class TailFold {
+    private cursor;
+    private mode;
+    private modes;
+    private unattended;
+    private modeFlags;
+    private readOnly;
+    private terminal;
+    private open;
+    private readonly asked;
+    private readonly steps;
+    /** One row and what it decoded to. A replayed event is not the session's own: it moves nothing, not even the cursor. */
+    add(rowId: string, step: RemoteStep): void;
+    private noteModes;
+    result(): SessionTail;
+}
+/** An object with at least one field (an empty payload says nothing). */
+export declare function filled(payload: Readonly<Record<string, unknown>> | null): payload is Readonly<Record<string, unknown>>;
+/** The `actionId` a permission request (or its resolution) names, as text ('' none). */
+export declare function actionIdOf(payload: Readonly<Record<string, unknown>>): string;
+/** Reads a page of a session's stored events after a cursor (null: from the start). */
+export type ReadEvents = (after: string | null, limit: number) => Promise<readonly EventRow[]>;
+/** The session's tail, read page by page from its start. */
+export declare function readTail(read: ReadEvents, decode: (event: SseEvent) => RemoteStep): Promise<SessionTail>;

package/dist/types/remote/targets.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What a typed or tapped name of a session or conversation means: a session by its number in the last listing or a prefix of its
+ * id; an agent as people name it, which means its newest active session, else a conversation it offers to take over, else a new
+ * session in its first folder; a conversation by its ref. And what a tap on a card names (a folder, a conversation to take over),
+ * read against what the agent reports NOW, never against the card.
+ */
+import type { Lang } from "../locales/lang.js";
+import { type Conversation } from "./conversations.js";
+import type { ChatRegistry } from "./chats.js";
+import type { Agent, Connector, Session } from "./model.js";
+/** Characters of a session id that name it (fewer is a number from the last listing). */
+export declare const MIN_ID_PREFIX = 6;
+/** A session to start: on which agent, taking over (or watching) which conversation, in which folder. */
+export interface ToStart {
+    readonly kind: "start";
+    readonly connector: Connector;
+    readonly agent: Agent;
+    readonly entry: Conversation | null;
+    readonly path: string;
+}
+export type Target = {
+    readonly kind: "session";
+    readonly session: Session;
+} | ToStart | {
+    readonly kind: "refusal";
+    readonly text: string;
+};
+/** The sessions `ref` names as a session: its number in the last listing, or a prefix of its id of at least 6 characters. */
+export declare function sessionsByRef(listing: readonly string[], sessions: readonly Session[], ref: string): Session[];
+/** What a tap names, read against what this process and the agent's report say now. */
+export declare class Targets {
+    private readonly chats;
+    constructor(chats: ChatRegistry);
+    /**
+     * What `/agent attach REF` goes to: a session, or (for an agent) its newest active session, else the newest conversation it
+     * offers to take over that no terminal has open, else a new session in its first folder, else the one a terminal has open,
+     * watched. `now`: wall-clock seconds.
+     */
+    target(chatKey: string, listing: readonly string[], connectors: readonly Connector[], sessions: readonly Session[], ref: string, now: number, lang: Lang): Target;
+    private forAgent;
+    /**
+     * A conversation an agent on the person's machines offers to take over, named by its ref (or its first characters): what the
+     * assistant puts to the person as that conversation's attach command. Null when no conversation of theirs has that ref.
+     */
+    private conversationByRef;
+    /**
+     * The conversation a "Take over" (or "Watch") tap names, or why not: it must be on the agent's list NOW. One open in a terminal
+     * is watched, read-only, unless the tap is the Take over of the confirmation card this process showed this chat for it (its
+     * ticket, once, in time): then the connector ends the terminal first.
+     */
+    takeoverOf(chatKey: string, connector: Connector, agent: Agent, data: Readonly<Record<string, unknown>>, now: number, lang: Lang): {
+        entry: Conversation | null;
+        problem: string;
+    };
+    /**
+     * The folder a "New session" tap asks for, or why there is none: a choice among the roots the agent reports NOW and a subfolder
+     * below it, or the whole folder when it reports none; or, from the card that asks which of a machine's agents, the folder this
+     * process kept when it was typed (the card carries only a token).
+     */
+    folderOf(chatKey: string, agent: Agent, data: Readonly<Record<string, unknown>>, now: number, lang: Lang): {
+        path: string;
+        problem: string;
+    };
+}
+/** The block of the card a tap came from (-1: the tap names none that the card has). */
+export declare function slotOf(data: Readonly<Record<string, unknown>>): number;

package/dist/types/remote/tasks.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from "../ports/logger.js";
+/**
+ * Work that runs on its own (a turn being read, a short watch, a throttled edit of a card) and can be cancelled: its signal
+ * aborts, and every await it makes on a cancellable call ends. Cancelling is cooperative: the work checks its signal after what it
+ * awaited, the way an asyncio task meets its cancellation at its next await.
+ */
+export declare class Task {
+    private readonly controller;
+    private finished;
+    readonly done: Promise<void>;
+    constructor(work: (signal: AbortSignal) => Promise<void>, logger: Logger, what: string);
+    get running(): boolean;
+    get cancelled(): boolean;
+    cancel(): void;
+}
+/** One chat at a time: what runs for a chat waits for the one before it (the Python worker's per-chat `asyncio.Lock`). */
+export declare class ChatLocks {
+    private readonly tails;
+    with<T>(chatKey: string, work: () => Promise<T>): Promise<T>;
+}

package/dist/types/remote/time.d.ts

@@ -0,0 +1,15 @@
+/** How long ago, and clock times, as the remote-agent cards say them. */
+import type { Lang } from "../locales/lang.js";
+/** Seconds since the epoch of an ISO 8601 time as Claw writes it (`2026-10-29T05:00:00Z`, an offset, or fractional seconds), or
+ * null when it is none. A time without an offset is read as UTC. */
+export declare function parseIsoSeconds(value: unknown): number | null;
+/** "just now", "3 h ago": how long before `now` (seconds since the epoch) the ISO time `when` was; "" when it is no time. */
+export declare function ago(now: number, when: unknown, lang?: Lang): string;
+/** `ago` for a time in seconds since the epoch; "" for none. */
+export declare function agoEpoch(now: number, when: number | null, lang?: Lang): string;
+/** `HH:MM` of `seconds` in the time zone `zone` (an IANA name). */
+export declare function clock(seconds: number, zone: string): string;
+/** `HH:MM:SSZ` of `seconds` in UTC. */
+export declare function utcClock(seconds: number): string;
+/** `MM-DD HH:MMZ` of `seconds` in UTC. */
+export declare function utcStamp(seconds: number): string;

package/dist/types/remote/turn-state.d.ts

@@ -0,0 +1,29 @@
+import type { SseEvent } from "../claw/model.js";
+import type { PublicErrors } from "../public-error/public-errors.js";
+import { type RemoteStep } from "./events.js";
+/**
+ * One turn of a remote agent, folded event by event. The stream is read from the cursor after the previous turn's end, so every
+ * message chunk until the turn's end is this turn's. Like Claw's own turns, the answer is the agent's last piece of text: the text
+ * before a tool call is narration, shown while it runs. What it holds is bounded, however long a turn runs.
+ */
+export declare class RemoteTurnState {
+    private readonly errors;
+    /** Event ids already seen, oldest first (at most SEEN_KEPT). */
+    readonly seen: Set<string>;
+    /** Message text, one entry per stretch between tool calls (at most SEGMENTS_KEPT). */
+    readonly segments: string[];
+    stopReason: string;
+    ended: boolean;
+    closed: string | null;
+    note: string | null;
+    private toolSinceText;
+    constructor(errors: PublicErrors);
+    feed(event: SseEvent): RemoteStep;
+    /** The agent's last piece of text, stripped. */
+    get answer(): string;
+    /** The answer so far, and the text is forgotten (the event ids already seen are not): what a reader that goes on after a
+     * piece of the agent's output was delivered folds the next piece from. */
+    takeAnswer(): string;
+    private remember;
+    private addText;
+}

package/dist/types/remote/turns/chat-turn.d.ts

@@ -0,0 +1,50 @@
+import type { Logger } from "../../ports/logger.js";
+import type { Clock } from "../../ports/clock.js";
+import { type RemoteStep } from "../events.js";
+import type { RemoteLive } from "../ports.js";
+import { type LiveViewLike, type StatusPolicy, type StreamFinish, type StreamFinishInput } from "../../turn/progress/status-policy.js";
+import type { TurnSurface } from "../../turn/ports.js";
+import type { FinishWith, TurnDisplay } from "./display.js";
+import type { Signer } from "./signer.js";
+/** What the bubble shows of a remote turn, and how its stream ends. */
+export declare class RemoteStatusPolicy implements StatusPolicy<RemoteStep> {
+    private readonly live;
+    private readonly cutError;
+    private readonly signer;
+    /** A line of ours after the answer (how the turn ended): not the agent's words. */
+    tail: string;
+    private readonly segments;
+    private newSegment;
+    /** The live view as the status shows it (a remote turn has no setup phase: it never says "Preparing"). */
+    readonly view: LiveViewLike;
+    constructor(live: RemoteLive, cutError: (text: string) => string, signer: Signer | null);
+    applyStep(step: RemoteStep): boolean;
+    /** Everything the agent has written this turn, as it is shown (under its head, with a signer). */
+    private saidText;
+    streamable(streamed: string): string;
+    /**
+     * The bubble holds the agent's words. The final message keeps them (the chat refuses a stream whose text shrinks), and what the
+     * agent wrote after them follows as messages of its own: nothing is said twice. The line of ours about how the turn ended goes
+     * last. Only when the words shown are not the start of what the agent wrote (a mask that moved) does it end as every turn's does.
+     */
+    finishStream(input: StreamFinishInput): StreamFinish | undefined;
+}
+/** The turn shown in the chat (a stream, else a progress message), as a `TurnDisplay`. */
+export declare class ChatTurn implements TurnDisplay {
+    private readonly surface;
+    private readonly policy;
+    private readonly options;
+    private readonly status;
+    constructor(surface: TurnSurface, policy: RemoteStatusPolicy, options: {
+        readonly clock: Clock;
+        readonly log: Logger;
+        readonly lang: string;
+        readonly replyTo: string | undefined;
+    });
+    get tail(): string;
+    set tail(line: string);
+    begin(): void;
+    progress(step: RemoteStep): void;
+    close(hard?: boolean): void;
+    finish(parts: readonly string[], options: FinishWith): Promise<void>;
+}

package/dist/types/remote/turns/display.d.ts

@@ -0,0 +1,18 @@
+import type { SuggestedReply } from "../../ports/surface.js";
+import { type RemoteStep } from "../events.js";
+/** How a remote turn is shown while it runs and when it ends: in the chat (a stream, or a progress message), or in the session card. */
+export interface TurnDisplay {
+    /** A line of ours after the answer (how the turn ended): not the agent's words. */
+    tail: string;
+    begin(): void;
+    progress(step: RemoteStep): void;
+    /** Nothing more is shown (`hard`: the turn was cancelled). */
+    close(hard?: boolean): void;
+    /** The answer: `parts` in order, the suggested `replies` under the last. */
+    finish(parts: readonly string[], options: FinishWith): Promise<void>;
+}
+export interface FinishWith {
+    /** What the agent wrote (the AI label). */
+    readonly ai: boolean;
+    readonly replies?: readonly SuggestedReply[];
+}

package/dist/types/remote/turns/outcome.d.ts

@@ -0,0 +1,41 @@
+/**
+ * How a remote turn ended, as the person is told it: the agent's answer (its last piece of text), and lines of ours after it (a
+ * failure with a reference, the session's end, a stop at a limit, a turn the connector could not complete). A turn that ended with
+ * no words of the agent's is never said as "Done" when a line of ours says otherwise.
+ */
+import type { Lang } from "../../locales/lang.js";
+/** What the turn's fold says of its end. */
+export interface TurnEnd {
+    readonly answer: string;
+    readonly stopReason: string;
+    readonly note: string | null;
+    readonly closed: string | null;
+    /** The person asked to stop it. */
+    readonly stopRequested: boolean;
+}
+/** What says a turn's end in words: the session's end, a connector's code, a raw error withheld. */
+export interface EndSayers {
+    readonly label: string;
+    readonly host: string;
+    readonly lang: Lang;
+    splitErrorTail(text: string): {
+        readonly kept: string;
+        readonly tail: string;
+    };
+    /** Log the raw error of a failed call and return its reference. */
+    withhold(error: string): string;
+    sessionEnded(reason: string): Promise<string>;
+    turnIncomplete(code: string): Promise<string>;
+    /** The answer's parts under the agent's head, in a chat that is its window (`signer.ts`). */
+    sign?: (parts: string[]) => string[];
+}
+export interface TurnOutcome {
+    /** The messages of the answer, the lines of ours on the last. */
+    readonly parts: string[];
+    /** The lines of ours ('' none). */
+    readonly tail: string;
+    /** The agent wrote something. */
+    readonly ai: boolean;
+}
+/** The answer and the lines of ours, as the person is told the end of the turn. */
+export declare function turnOutcome(end: TurnEnd, say: EndSayers): Promise<TurnOutcome>;

package/dist/types/remote/turns/runner.d.ts

@@ -0,0 +1,55 @@
+import type { RemoteState } from "../../ports/store/remote.js";
+import { type Conversation } from "../../ports/surface.js";
+import type { StatusBoard } from "../board.js";
+import type { RemoteContext } from "../context.js";
+import { type EndedWords, type Provider } from "../ended.js";
+import type { FollowControl } from "../follow/control.js";
+import { type ChatState } from "../state.js";
+import type { TurnDisplay } from "./display.js";
+import type { Signer } from "./signer.js";
+/** A coding agent may work for hours; after this the chat stops watching (it keeps going). */
+export declare const REMOTE_TURN_DEADLINE_SECONDS: number;
+export declare const RECONNECT_BACKOFF_SECONDS = 1;
+/** Events between two writes of the read position. */
+export declare const CURSOR_EVERY = 25;
+/** A stream that keeps dropping is given up after this many tries in a row. */
+export declare const STREAM_ATTEMPTS = 4;
+/** How the turn is shown: in the chat, or in the session card (`window-turn.ts`). */
+export type DisplayFor = (request: TurnRequest, signer: Signer | null) => TurnDisplay;
+/** What a turn needs besides the chat: the person's credential, how to show it, and who carries what it asks. */
+export interface TurnRequest {
+    readonly chatKey: string;
+    readonly key: string;
+    readonly provider: Provider;
+    readonly to: Conversation;
+    readonly state: RemoteState;
+    /** The person's message the turn answers (a stream answers it); undefined: shown by a progress message. */
+    readonly replyTo: string | undefined;
+}
+export declare class TurnRunner {
+    private readonly ctx;
+    private readonly state;
+    private readonly board;
+    private readonly follow;
+    private readonly ended;
+    private readonly show;
+    private readonly displayFor;
+    constructor(ctx: RemoteContext, state: ChatState, board: StatusBoard, follow: FollowControl, ended: EndedWords, show: (chatKey: string, sid: string, request: Readonly<Record<string, unknown>>, to: Conversation) => Promise<void>, displayFor: DisplayFor);
+    /** Watch the turn that is open on the chat's session. */
+    start(request: TurnRequest): void;
+    cancel(chatKey: string): void;
+    private guarded;
+    private display;
+    private run;
+    /** The turn could not be read to its end: the session is gone, Claw refused, or the connection was lost. */
+    private failed;
+    /**
+     * Read the session's events from the cursor until the turn ends or the session closes; a stream that drops is picked up again
+     * from the last event handled (the server replays what is stored after it).
+     */
+    private read;
+    /** One stream, read until it ends or the turn does. */
+    private readStream;
+    private apply;
+    private sayRecovered;
+}

package/dist/types/remote/turns/signer.d.ts

@@ -0,0 +1,14 @@
+import type { Lang } from "../../locales/lang.js";
+import type { SuggestedReply } from "../../ports/surface.js";
+export declare class Signer {
+    readonly label: string;
+    readonly host: string;
+    readonly lang: Lang;
+    readonly replies: readonly SuggestedReply[];
+    readonly suffix: string;
+    constructor(label: string, host: string, lang: Lang, replies?: readonly SuggestedReply[], suffix?: string);
+    /** The agent's words (already masked) under its head. */
+    first(text: string): string;
+    /** `parts` as messages `first`, `first`+1, ... of one answer (1: the first one has the full head). */
+    later(parts: readonly string[], first?: number): string[];
+}

package/dist/types/remote/turns/window-turn.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A remote agent's turn shown in the chat's session card (the window), in place of the chat's stream: what the agent writes fills
+ * the card's output (an edit at most every EDIT_SECONDS), the step it runs and a message waiting for the terminal are its state,
+ * and the end of the turn refreshes it (posted again at the bottom: a phone may not redraw an edit). Nothing else is posted.
+ */
+import type { Conversation } from "../../ports/surface.js";
+import { type RemoteStep } from "../events.js";
+import type { StatusBoard } from "../board.js";
+import type { ChatState } from "../state.js";
+import type { TurnDisplay } from "./display.js";
+export declare class WindowTurn implements TurnDisplay {
+    private readonly chatKey;
+    private readonly to;
+    private readonly state;
+    private readonly board;
+    private readonly cutError;
+    tail: string;
+    private readonly segments;
+    private newSegment;
+    private closed;
+    constructor(chatKey: string, to: Conversation, state: ChatState, board: StatusBoard, cutError: (text: string) => string);
+    private get view();
+    private said;
+    begin(): void;
+    progress(step: RemoteStep): void;
+    close(): void;
+    /** (the window has no labels or replies: the options are the chat's) */
+    finish(parts: readonly string[]): Promise<void>;
+}

package/dist/types/remote/views.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The cards the domain builds beside `cards.ts`: the note that replaces a tapped card (and the notes that bring a card's buttons
+ * back), and the session card as the window. Built from the note view and the remote views; nothing here talks to a channel.
+ */
+import type { Lang } from "../locales/lang.js";
+import type { OutMessage, ViewButton } from "../ports/surface.js";
+import { type DecisionButton } from "./actions.js";
+/** A short note that replaces a tapped card (under `title` when there is one). */
+export declare function noteCard(text: string, title?: string, buttons?: readonly ViewButton[]): OutMessage;
+/** The permission card's buttons again under `text`, titled with the request: the decision did not go through. */
+export declare function reopenedCard(buttons: readonly DecisionButton[], title: string, text: string): OutMessage;
+/** The disconnect buttons again under `text`: pressing again can help. */
+export declare function disconnectAgainCard(text: string, connectorId: string, title: string, lang: Lang): OutMessage;

package/dist/types/remote/watches.d.ts

@@ -0,0 +1,64 @@
+import { type Conversation } from "../ports/surface.js";
+import { type RemoteStep } from "./events.js";
+import type { StatusBoard } from "./board.js";
+import type { RemoteContext } from "./context.js";
+import { type EndedWords, type Provider } from "./ended.js";
+import type { FollowControl } from "./follow/control.js";
+import { type ChatState } from "./state.js";
+/** How long `/agent new` waits to say the agent is ready. */
+export declare const WATCH_SECONDS = 30;
+export declare const MODE_WATCH_SECONDS = 10;
+export declare const MODE_ID_MAX = 64;
+/** What a mode switch waits for: the mode the agent now reports, or the connector's refusal of the switch. */
+export declare function modeAnswer(step: RemoteStep): boolean;
+/** What the watch of a new session needs: who, where, and what the card asked for. */
+export interface StartWatch {
+    readonly chatKey: string;
+    readonly sessionId: string;
+    readonly key: string;
+    readonly provider: Provider;
+    readonly to: Conversation;
+    /** The kind of session the card asked for when it is not how the agent starts ("ask" | "unattended"). */
+    readonly want: string | null;
+    /** The count a start in a mode that does not ask took, given back when it turns out not to be one. */
+    readonly ticket: object | null;
+}
+export declare class Watches {
+    private readonly ctx;
+    private readonly state;
+    private readonly board;
+    private readonly follow;
+    private readonly ended;
+    constructor(ctx: RemoteContext, state: ChatState, board: StatusBoard, follow: FollowControl, ended: EndedWords);
+    /** How long a watch of a new session (`start`) or of a mode switch (`mode`) reads. */
+    private seconds;
+    /** Run a watch for the chat; once it is over (not cancelled) the follower reads on. */
+    spawn(chatKey: string, work: (signal: AbortSignal) => Promise<void>): void;
+    cancel(chatKey: string): void;
+    /**
+     * Read the session's events until one is `wanted` (or the session ends), for at most `seconds`; the read position moves past
+     * what was read. That step, a closing step, or null when time ran out.
+     */
+    watch(chatKey: string, sessionId: string, credential: () => Promise<string>, wanted: (step: RemoteStep) => boolean, seconds: number, signal: AbortSignal): Promise<RemoteStep | null>;
+    /** The watch of a new session: say it is ready (in place, on its status card), or why it could not start. */
+    start(w: StartWatch, signal: AbortSignal): Promise<void>;
+    private couldNotStart;
+    /** Open in a terminal: watched, read-only; its output is told as it comes. */
+    private watching;
+    private ready;
+    private notReported;
+    /**
+     * The card asked for a kind of session the agent does not start as: the agent has just said which modes it offers and which of
+     * them ask, so switch it to one that does what was asked, and say so. What a connector refuses or does not say is told, never
+     * guessed: a mode id is never made up. (The same per-person limit as `/agent mode` to a mode that does not ask.)
+     */
+    private approvalNote;
+    /** Ask the session to switch to `target` and watch for its answer: why it did not (a line), or null when it may have. */
+    private switchTo;
+    /** The watch of a mode switch: say what it came to. */
+    mode(chatKey: string, sessionId: string, mode: string, w: {
+        key: string;
+        provider: Provider;
+        to: Conversation;
+    }, signal: AbortSignal): Promise<void>;
+}

package/dist/types/remote/window/closer.d.ts

@@ -0,0 +1,14 @@
+import { type Conversation } from "../../ports/surface.js";
+import type { StatusBoard } from "../board.js";
+import type { RemoteContext } from "../context.js";
+import type { Settle } from "../permissions.js";
+import type { ChatState } from "../state.js";
+/** The tap a settle answers: the card it was on, and the data it carried. */
+export interface Tap {
+    readonly chatKey: string;
+    readonly to: Conversation;
+    /** The message that holds the tapped card ("" not said). */
+    readonly tapped: string;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+export declare function windowCloser(ctx: RemoteContext, state: ChatState, board: StatusBoard, tap: Tap, settle: Settle): Settle;

package/dist/types/remote/window/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./output.js";
+export * from "./view.js";

package/dist/types/remote/window/output.d.ts

@@ -0,0 +1,28 @@
+/** The agent's output as the window shows it: masked by credential shape before it is cut, so a cut cannot leave half of one. */
+import type { Lang } from "../../locales/lang.js";
+import type { SentFrom, WindowMode } from "./view.js";
+/** One message of "完整输出". */
+export declare const FULL_PART_CHARS = 3000;
+export declare const FULL_PARTS_MAX = 12;
+export declare function masked(text: string): string;
+/**
+ * The last `lines` lines of `text` that fit in `chars` characters (masked first), and whether anything before them was left out.
+ */
+export declare function tailLines(text: string, chars: number, lines: number): {
+    lines: string[];
+    cut: boolean;
+};
+/**
+ * "完整输出": the whole output kept, masked, in messages of FULL_PART_CHARS at most, cut at line ends where it can; the last
+ * FULL_PARTS_MAX of them (what came before is on the machine).
+ */
+export declare function fullParts(text: string): string[];
+/** The line over what was last sent to the session, by where it was typed. */
+export declare function sentLabel(source: SentFrom, lang: Lang): string;
+/**
+ * Where what is typed goes, said on the card (and by /help): the chat box to the assistant, the card's box to the session; or, in
+ * `chat` mode, everything to the session but what starts with @ the assistant. `bot`: the assistant's display name.
+ */
+export declare function chatBoxLine(window: string, lang: Lang, bot: string): string;
+/** What `/agent mode card|chat` answers. */
+export declare function modeSetLine(window: WindowMode, lang: Lang, attached: boolean, bot: string): string;

package/dist/types/remote/window/view.d.ts

@@ -0,0 +1,73 @@
+export declare const WINDOW_MODES: readonly ["card", "chat"];
+export type WindowMode = (typeof WINDOW_MODES)[number];
+export declare function isWindowMode(value: string): value is WindowMode;
+/** The output of the current (or last) turn kept for "完整输出". */
+export declare const FULL_KEEP_CHARS = 60000;
+/** The card's text box. */
+export declare const INPUT_MAX = 4000;
+/** The id of that box in what a tap carries. */
+export declare const INPUT_ID = "window_text";
+/** An edit more than this many times since the card was posted: it is posted again at the bottom. */
+export declare const REPOST_EDITS = 6;
+/** ... while a turn streams into it (an edit every EDIT_SECONDS: about a minute). */
+export declare const REPOST_EDITS_STREAMING = 20;
+/** Characters of output new since the card was posted that make it worth posting again. */
+export declare const REPOST_GROWTH = 400;
+/** At most one edit of the card per this long while a turn streams into it. */
+export declare const EDIT_SECONDS = 3;
+/** Where what was last sent to the session was typed: the card's box, a reply quoting the card, the chat box. */
+export type SentFrom = "card" | "quote" | "chat" | "";
+/**
+ * What one attached chat's window shows of its session's output, in this process (it starts empty after a restart: the next turn
+ * fills it). `text` is the output of the current turn, or of the last one; `postedLen` how much of it the card showed when it was
+ * last posted (not edited); `edits` the edits since then.
+ */
+export declare class WindowView {
+    sessionId: string;
+    text: string;
+    /** The step the agent is running now ('' none). */
+    step: string;
+    /** Why a message waits for the terminal ('' it does not). */
+    queued: string;
+    /** The last message that went to the session from this chat. */
+    sent: string;
+    sentFrom: SentFrom;
+    /** What the card's box held when the person last tapped a button on it other than Send (shown in it again). */
+    draft: string;
+    /** The card the chat shows now has the text box. */
+    boxed: boolean;
+    /** Older cards with a box, left for the person's next act. */
+    kept: string[];
+    /** One line of ours under the output (how a turn ended, a refusal). */
+    note: string;
+    postedLen: number;
+    edits: number;
+    approvalsSeen: Set<string>;
+    /** A turn ended and the card has not been refreshed since (the next refresh reads it once). */
+    ended: boolean;
+    /** A view of another session starts empty. */
+    reset(sessionId: string): void;
+    /**
+     * The output now. A text that is not the continuation of the one shown (a new turn, a new burst) is measured from nothing: what
+     * the card showed when it was posted was another output, and only how much of this one there is counts (`shouldRepost`).
+     */
+    setText(text: string): void;
+}
+/**
+ * Whether the next refresh of the window posts it again at the bottom (and removes the old one) rather than editing it in place.
+ * `streaming`: an edit while a turn streams into the card, posted again only for an approval or after many edits. A turn's end
+ * always posts it again: the card said "running" until then, and a phone that does not redraw the edit would keep saying so.
+ */
+export declare function shouldRepost(view: WindowView, approvals: readonly string[], ended?: boolean, streaming?: boolean): boolean;
+export declare function markPosted(view: WindowView, approvals: readonly string[]): void;
+export declare function markEdited(view: WindowView): void;
+/**
+ * Whether the card in this phase has the text box: only while the session is idle. A running turn's card is edited every
+ * EDIT_SECONDS and posted again at the turn's end, and Teams keeps nothing typed into a card across an edit or a delete.
+ */
+export declare function takesInput(phase: string): boolean;
+/**
+ * The message is a reply that quotes one of this chat's session cards (the channel names the quoted message's id): in `card` mode
+ * it goes to the session, like the card's own box.
+ */
+export declare function quotesWindow(quotedIds: readonly string[], cardIds: readonly string[]): boolean;