@primusclaw/personal-agent 0.0.0-stage → 0.1.0

package/dist/types/remote/follow/speaker.d.ts

@@ -0,0 +1,122 @@
+import type { SseEvent } from "../../claw/model.js";
+import type { JsonObject } from "../../json.js";
+import type { Lang } from "../../locales/lang.js";
+import type { Clock } from "../../ports/clock.js";
+import type { Logger } from "../../ports/logger.js";
+import type { ConversationRefRepository } from "../../ports/store/people.js";
+import type { RemoteStateRepository } from "../../ports/store/remote.js";
+import { type Conversation } from "../../ports/surface.js";
+import { type RemoteStep } from "../events.js";
+import { type RemoteTurnState } from "../turn-state.js";
+import { type FollowTimings } from "./timings.js";
+/** Whether a person may be woken now, and where what they may not be told yet is held (`proactive`). */
+export interface FollowReach {
+    reachable(chatKey: string): boolean;
+    /** "paused" when the person paused proactive messages (`/pause`); anything else is not a pause. */
+    muted(chatKey: string): string | null;
+    /**
+     * Hold what was not said for the assistant's release. `eventId`: the id of the last event the held text came with (the assistant
+     * holds one burst once, whoever holds it again).
+     */
+    holdRemote(chatKey: string, label: string, text: string, eventId: string): void;
+}
+/** What the speaker needs: where to say it, whether it may, and how. */
+export interface SpeakerDeps {
+    readonly clock: Clock;
+    readonly logger: Logger;
+    readonly timings: FollowTimings;
+    readonly reach: FollowReach;
+    readonly remoteState: RemoteStateRepository;
+    readonly references: ConversationRefRepository;
+    /** The conversation a stored reference posts to. */
+    conversationFor(reference: JsonObject): Conversation;
+    showPermission(chatKey: string, sessionId: string, request: Readonly<Record<string, unknown>>, to: Conversation): Promise<void>;
+    lang(): Lang;
+    /** The chat is the agent's window itself (`direct-chat`): what the agent says is signed with its head. */
+    direct(): boolean;
+    /** The paragraph that says the session ended and why (the reason a connector gave). */
+    describeEnd?: (reason: string) => Promise<string>;
+    /** The chat's session card, when it is the window: the text so far (`final` false) or the burst (`final` true); false when
+     * the chat shows no window. */
+    window?: (text: string, final: boolean) => Promise<boolean>;
+    /** The card is told once what the burst came to has been taken in. */
+    windowSettled?: () => Promise<void>;
+}
+/** When the text that waits is due, from what the reader knows. */
+export interface DueContext {
+    readonly lastEvent: number;
+    /** A step this reader saw begin, or a permission request, is open. */
+    readonly busy: boolean;
+    readonly now: number;
+}
+export declare class BurstSpeaker {
+    private readonly chatKey;
+    private readonly sessionId;
+    private readonly deps;
+    private readonly turn;
+    /** Aborted when the reader is cancelled: a send still in flight is given up (Python's task cancel cuts it off). */
+    private readonly cutOff?;
+    /** The read position before which no text waits: what may be written as the cursor. */
+    safe: string;
+    private pendingSince;
+    private lastPush;
+    private retryAt;
+    private sent;
+    private typedTurn;
+    private settle;
+    private lastTextEvent;
+    constructor(chatKey: string, sessionId: string, deps: SpeakerDeps, turn: RemoteTurnState, 
+    /** Aborted when the reader is cancelled: a send still in flight is given up (Python's task cancel cuts it off). */
+    cutOff?: AbortSignal | undefined);
+    /** Text of the agent's is waiting to be said. */
+    get waiting(): boolean;
+    feed(event: SseEvent): RemoteStep;
+    settleAt(cursor: string): void;
+    /** Milliseconds until the text that waits is due, 0 when it is, null when none waits (then only an event can matter). */
+    dueInMs(at: DueContext): number | null;
+    /** A message chunk: the burst began now, and the session card shows the text so far. */
+    noteText(step: RemoteStep, now: number): Promise<void>;
+    /**
+     * Say the text that waits (held in quiet hours or a pause, unless `force`), and move the safe position to `cursor`. When it
+     * cannot be sent: tried again after a while, or (`holdOnFailure`, for a reader being stopped) held for the sweep. True when the
+     * safe position moved (the caller writes it).
+     */
+    flush(how: {
+        readonly force: boolean;
+        readonly holdOnFailure: boolean;
+    }, cursor: string): Promise<boolean>;
+    /**
+     * The reader was cancelled because it did not stop in time, so a send of its was cut off: what it was saying is held for the
+     * sweep (at least once, never lost), and the read position moves past it. The safe position, for the caller to write.
+     */
+    abandon(cursor: string): string;
+    private forget;
+    private mayWake;
+    /** Deliver `text`; false when it could not be sent (it is kept and tried again). `force` lifts quiet hours, never a pause. */
+    private say;
+    /** The burst into the session card when it is the window: true shown, false failed, null no window. */
+    private intoWindow;
+    /** One message per part: headed with who said it, or signed with the agent's head in a chat that is its window. */
+    private messages;
+    private signed;
+    private langOr;
+    /** How many leading parts of `raw` were delivered already. */
+    private delivered;
+    /** Hold what has not been delivered of `text` for the sweep. */
+    private hold;
+    settleWindow(): Promise<void>;
+    /** A permission request gets its card at once, and none while the person may not be woken. */
+    ask(request: Readonly<Record<string, unknown>>): Promise<void>;
+    /** A prompt typed at the terminal the chat shares: one message, so the reply that follows reads as its answer. */
+    typed(text: string): Promise<void>;
+    /** The connector restarted and this session is back: one line, never to wake anyone. */
+    recovered(interrupted: boolean, continuing: boolean): Promise<void>;
+    /**
+     * The session ended while the chat was idle: say so and send the chat's messages to the assistant again. Nothing is said, and
+     * nothing changed, for a person who may not be woken: their next message is told that the session has ended.
+     */
+    ended(reason: string): Promise<void>;
+    /** The chat to tell now, or null: nobody to tell, or (`unlessPaused`: also a pause) the person may not be woken. */
+    private reachable;
+    private tell;
+}

package/dist/types/remote/follow/steps.d.ts

@@ -0,0 +1,9 @@
+import { type ToolUpdate } from "../events.js";
+/** Steps remembered as running (a connector that never ends its steps cannot grow this). */
+export declare const STEPS_KEPT = 200;
+/**
+ * Fold one tool event into the steps that have begun and not ended: the follower's, and the one made of a session's events when
+ * a chat attaches (`tail.ts`), so that both say the same of the same events. The value says whether this reader read the step's
+ * beginning (a step running when the chat attached holds no text back).
+ */
+export declare function noteStep(steps: Map<string, boolean>, tool: ToolUpdate): void;

package/dist/types/remote/follow/timings.d.ts

@@ -0,0 +1,29 @@
+/** When a burst of what an agent says on its own is over (milliseconds). Tests use short ones. */
+export interface FollowTimings {
+    /** No event for this long, and no step or permission request open: the burst is over. */
+    readonly quietMs: number;
+    /** ... when one is open: the agent may be waiting for a long step. */
+    readonly toolQuietMs: number;
+    /** At most one message per this long (what comes in between is said with the next one). */
+    readonly gapMs: number;
+    /** The longest text waits for a pause, however busy the agent is. */
+    readonly maxAgeMs: number;
+    /** First wait before reading again after a stream ended (it doubles, up to `RECONNECT_MAX_MS`). */
+    readonly reconnectMs: number;
+    /** After a message failed to go out, the wait before it is tried again (`RETRY_MS` when not given). */
+    readonly retryMs?: number;
+    /** How long a stop waits for the reader to deliver what it read (`STOP_WAIT_MS` when not given). */
+    readonly stopWaitMs?: number;
+}
+export declare const DEFAULT_TIMINGS: FollowTimings;
+/** How a watched conversation (open in a terminal, read-only) is followed: told after a few quiet seconds, not half a minute. */
+export declare const WATCH_TIMINGS: FollowTimings;
+export declare const RECONNECT_MAX_MS = 60000;
+/** A message that could not be sent is tried again after this long. */
+export declare const RETRY_MS = 15000;
+/** `stop` waits this long for the reader to finish what it was doing. */
+export declare const STOP_WAIT_MS = 15000;
+/** Events between two writes of the read position (a write also follows every delivery). */
+export declare const CURSOR_EVERY = 25;
+/** The wait before reading again after `failures` failed reads in a row. */
+export declare function reconnectDelayMs(timings: FollowTimings, failures: number): number;

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

@@ -0,0 +1,20 @@
+import type { Lang } from "../locales/lang.js";
+import type { Agent, Connector } from "./model.js";
+export interface MachineProblem {
+    /** The agent it is about, or null for one of the machine as a whole (said once). */
+    readonly agent: Agent | null;
+    readonly code: string;
+    /** A failure, not a warning. */
+    readonly fail: boolean;
+    readonly detail: unknown;
+    readonly fix: unknown;
+}
+/** The machine's problems, failures first, a machine-wide one once, and when they were checked; null when no agent reports
+ * health (an older connector: unknown, not fine). */
+export declare function machineProblems(connector: Connector): {
+    problems: MachineProblem[];
+    checked: string | null;
+} | null;
+/** One line per problem of the machine (at most HEALTH_LINES_MAX, then how many more): what is wrong and the command that fixes it
+ * on that machine. [] when it reports none or no health at all. */
+export declare function healthLines(connector: Connector, lang?: Lang): string[];

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

@@ -0,0 +1,21 @@
+/**
+ * The remote agents' domain as other packages see it (`remoteDomain` of the core entry): what a connector reports and how it is
+ * read, the session's events, the limits, the reasons, the lines said in a chat, and the inputs of the cards (`RemoteViews`).
+ * The view (core/src/remote-view, `remoteView`) builds on these and never passes them on.
+ */
+export * from "./actions.js";
+export * from "./agents.js";
+export * from "./answer.js";
+export * from "./conversations.js";
+export * from "./events.js";
+export * from "./health.js";
+export { defang, lit, neutral, plain } from "./inert.js";
+export * from "./limits.js";
+export { breakAddresses, inertAnswer } from "./links/answer.js";
+export * from "./lines.js";
+export * from "./listing.js";
+export * from "./options.js";
+export type { Reported } from "./reported.js";
+export * from "./setup.js";
+export * from "./turn-state.js";
+export type { AgentsInput, SessionsInput, StatusInput, WindowApproval, WindowInput } from "./ports.js";

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

@@ -0,0 +1,18 @@
+/** `text` for a card TextBlock, which reads markdown: its markup characters escaped, so that `__init__.py` is not bold. */
+export declare function plain(text: string): string;
+/** One short line of untrusted text, safe in a card or a list (`text/neutral`), from whatever a connector reported: a value that
+ * is not text is read as Python's `str(value or "")` would. */
+export declare function neutral(text: unknown, limit?: number): string;
+/** `text` with no address a client links by itself (`https://`, `www.`, a bare domain, a mail address, escaped or not): a
+ * zero-width space breaks each, which no one sees. Where the text is shown as it is (a short line, the window card's output, the
+ * full output), not made words as an answer is. */
+export declare function breakLinks(text: string): string;
+/** `neutral`, then markup escaped: text supplied by an agent, a machine or a session as it goes into a card TextBlock. */
+export declare function lit(text: unknown, limit: number): string;
+/** `text` whole, but unable to make a markdown link or image (`](` gets a zero-width space inside) or a tag (`<`/`>` look-alikes). */
+export declare function inertLinks(text: string): string;
+/** A copy of an agent's JSON with every string unable to make a link or a tag: `](` gets a zero-width space inside, and
+ * `<`/`>` become look-alikes. Unlike `neutral` it keeps the text whole. */
+export declare function defang(value: unknown): unknown;
+/** `text` with credential-shaped values masked. */
+export declare function masked(text: string): string;

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

@@ -0,0 +1,48 @@
+/** How much of what an agent or a connector reports is read, kept and shown. */
+/** A phone screen holds this many buttons under a card. */
+export declare const OPTION_BUTTONS_MAX = 4;
+/** A permission request that names no timeout lives this long, as long as the connector keeps it. */
+export declare const PERMISSION_DEFAULT_SECONDS = 600;
+export declare const BUTTON_TITLE_MAX = 40;
+export declare const TOOL_TITLE_MAX = 100;
+export declare const THOUGHT_MAX = 200;
+export declare const SESSIONS_SHOWN = 8;
+export declare const ANSWER_MESSAGES_MAX = 3;
+export declare const ANSWER_CHARS_MAX = 3000;
+/** The answer is cut to about 9000 characters on its way out: no point holding more of it. */
+export declare const SEGMENT_KEEP_CHARS = 12000;
+/** The answer is the last text; the stretches before it are narration. */
+export declare const SEGMENTS_KEPT = 4;
+/** Event ids remembered for dropping a repeat (a reconnect resumes after the last event anyway). */
+export declare const SEEN_KEPT = 2000;
+/** Steps shown as running at once (a connector that never ends its steps cannot grow the view). */
+export declare const ACTIVE_STEPS_MAX = 40;
+/** A block of the live view keeps this much of its end (the view shows the newest 2500 anyway). */
+export declare const BLOCK_KEEP_CHARS = 3000;
+export declare const OPTION_ID_MAX = 128;
+/** Online agents that get a "New session" block on the agents card. */
+export declare const AGENT_BLOCKS_MAX = 6;
+/** Sessions the agents card lists, newest first. */
+export declare const SESSION_CARD_MAX = 5;
+/** Folders a connector reports per agent. */
+export declare const ROOTS_MAX = 8;
+export declare const ROOT_MAX = 300;
+export declare const SUBFOLDER_MAX = 200;
+/** Conversations of one agent the agents card offers to take over (a connector reports at most twelve). */
+export declare const RESUMABLE_SHOWN = 5;
+/** Of them, the ones no process runs (listed after those a terminal has open, in a group of their own). */
+export declare const IDLE_SHOWN = 2;
+/** What Claw accepts as a resume_ref. */
+export declare const RESUME_REF_MAX = 128;
+/** Conversations a connector reports per agent. */
+export declare const RESUMABLE_READ_MAX = 12;
+export declare const WAITING_FOR_MAX = 60;
+export declare const TYPED_LINES_MAX = 40;
+/** Problems one machine shows on the agents card. */
+export declare const HEALTH_LINES_MAX = 4;
+/** Problems read from one agent's report (Claw caps capabilities at 4 KiB; this bounds the rest). */
+export declare const HEALTH_READ_MAX = 16;
+/** Sessions of one agent the sessions card lists, newest first. */
+export declare const SESSIONS_PER_AGENT = 5;
+/** Conversations of one agent the sessions card offers to take over. */
+export declare const CONVERSATIONS_PER_AGENT = 3;

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

@@ -0,0 +1,66 @@
+/** The one-line messages of a chat attached to a remote session: where it is, what happened, what a refusal means. */
+import type { Lang } from "../locales/lang.js";
+/** What Claw writes for an instruction or a start its machine never got (a reason code, said by the connector reasons). */
+export declare const NOT_DELIVERED = "not_delivered";
+/** ... or, when Claw cannot tell (the machine was alive moments before it was queued): it may have run. */
+export declare const DELIVERY_UNCONFIRMED = "delivery_unconfirmed";
+/** The connector's and Claw's refusal of input to a watched session. */
+export declare const READ_ONLY_REASONS: readonly string[];
+/** A watched conversation's terminal let it go: the watch is over. */
+export declare const TERMINAL_CLOSED = "terminal_closed";
+/** The connector's own word for a turn it ended because it restarted. */
+export declare const CONNECTOR_RESTARTED = "connector_restarted";
+/** A terminal's permission modes in which Claude Code acts without asking, and what they are called. */
+export declare const NO_ASK_MODES: Readonly<Record<string, string>>;
+/** The warning for a terminal whose mode does not ask, or null for one that asks (or whose mode is not known). */
+export declare function noAskLine(mode: string | null, lang: Lang): string | null;
+export type StopReason = "cancelled" | "max_tokens" | "max_turn_requests" | "refusal";
+/** Whether `reason` is a way a turn stopped that has a line of its own. */
+export declare function isStopReason(reason: string): reason is StopReason;
+/** The line for how a turn stopped. */
+export declare function stopNote(reason: StopReason, lang?: Lang): string;
+/** What a new session is called once something was sent to it: its first line, at most 30 characters. */
+export declare function sessionTitle(text: string): string;
+/** The last part of a folder (`…/repo`), which tells two sessions apart better than the whole path does (inert, for a card). */
+export declare function placeOf(cwd: unknown, lit: (text: unknown, limit: number) => string): string;
+/** A typed line is cut at this many characters: well under what the rich text converts, past which the message would go as plain
+ * markdown (where a reference link could be live). */
+export declare const TYPED_CHARS_MAX = 4000;
+/** How a prompt typed at the terminal shows in the chat: said as the terminal's, quoted, credentials masked, and unable to make a
+ * link, an image or a tag, nor an address the rich text links by itself (whoever types at that terminal reaches the chat through the
+ * connector: what they typed is shown, never followed). */
+export declare function typedLine(text: string, lang: Lang): string;
+/**
+ * Teams' floating status (an informative update) is cut on a phone after a few characters. Microsoft documents only an upper
+ * bound (1000 characters) and no display width; the one measurement is a phone on 2026-11-10, which showed four Chinese
+ * characters after the icon. So a line saying why a message still waits for its terminal is at most WAIT_LINE_MAX_ZH code points
+ * in Chinese and WAIT_LINE_MAX_EN in English, the "⏳ " included.
+ */
+export declare const WAIT_LINE_MAX_ZH = 6;
+export declare const WAIT_LINE_MAX_EN = 16;
+/** What a message for a conversation open in a terminal waits for (`terminal_input_queued`), in the chat's language: one short
+ * line within WAIT_LINE_MAX_ZH / WAIT_LINE_MAX_EN, so that a phone shows all of it. */
+export declare function queuedLine(reason: string, lang: Lang): string;
+/** What a message to a watched session is answered with: it was not sent, and what makes sending possible without taking the
+ * conversation from the terminal; `takeover`: the status card also offers Take over…, which ends the terminal's session. */
+export declare function readOnlyRefused(lang: Lang, takeover?: boolean): string;
+/** The watch is over because the terminal let the conversation go. */
+export declare function terminalClosedLine(lang: Lang): string;
+/** `dev-pod · 🟠 Claude Code`: which session a chat talks to, in one line. */
+export declare function whereLine(label: string, host: string): string;
+/** The short line a switch leaves in the chat, so that on a phone the two stretches of conversation can be told apart. */
+export declare function switchedLine(label: string, host: string, lang: Lang): string;
+/** What a chat is told, once, when the connector on the machine restarted and its session is back: whether a turn was cut off,
+ * and whether the agent goes on with it by itself or waits for a word. */
+export declare function recoveredLine(label: string, host: string, lang: Lang, interrupted: boolean, continuing: boolean): string;
+export declare function backLine(lang: Lang): string;
+/** Which messages of an attached chat stay with the assistant: said on the status card, where the person looks. */
+export declare function clawyLine(lang: Lang, bot: string): string;
+/** How to connect a machine with the one command line Claw gave (`claw-connector pair`): run it there, it does the rest. */
+export declare function pairText(command: string, minutes: number, lang: Lang, lead?: string): string;
+/** The disconnect card's title. */
+export declare function disconnectTitle(host: unknown, lang?: Lang): string;
+/** What the disconnect card becomes once the machine is disconnected. A paired machine is told only the pairing way back. */
+export declare function disconnectedText(host: unknown, login: string, lang?: Lang, paired?: boolean): string;
+/** Where the chat's session stands, as its status card says it. */
+export type StatusPhase = "idle" | "working" | "starting" | "offline" | "detached" | "ended" | "watching";

package/dist/types/remote/links/answer.d.ts

@@ -0,0 +1,7 @@
+/** What the chat's rich text drops before it reads anything: controls and bidi overrides (the rich text's own set). */
+export declare const DROPPED_BY_RICH_TEXT: RegExp;
+/** `text` with a zero-width space after every `www` of a `www.` and every `:` of a `://`, also when a markdown escape stands in
+ * either (`www\.`, `:\/\/`): no client takes what is left for an address. Its other text is unchanged. */
+export declare function breakAddresses(text: string): string;
+/** `text` with every link, image and address made words. Applying it again leaves no link either. */
+export declare function inertAnswer(text: string): string;

package/dist/types/remote/links/domains.d.ts

@@ -0,0 +1,19 @@
+/** Bare domains (`example.com/path`) in a remote agent's text, the ones a client that links fuzzy domains would link. */
+/** Where a code span this scan made opens or closes (a backtick in the end, see `answer.ts`): the scans after it read it as the
+ * backtick it will be, and an agent's own backtick left in the prose is told apart from it. */
+export declare const CODE = "\u0002";
+/** Whether a port, a path, a query or a fragment starts at `at` (`:`, `/`, `?`, `#`), escaped too (`\/`: the client shows `/`). */
+export declare function tailAt(text: string, at: number): boolean;
+/** The bare domains of one text, found left to right: [start, end of its run of labels] each. */
+export declare function domains(text: string, from?: number): Generator<[number, number]>;
+/** Where the next bare domain of one text starts at or after `from`, for a `from` that never goes back (one pass in all). */
+export declare class DomainFinder {
+    private readonly found;
+    private next;
+    private started;
+    constructor(text: string);
+    at(from: number): number;
+    private step;
+    /** Where the run of labels of the domain that starts at `start` ends, -1 when no domain starts there. */
+    runEnd(start: number): number;
+}

package/dist/types/remote/links/hosts.d.ts

@@ -0,0 +1,2 @@
+/** The host name an address points at, "" when it names none (a relative path, `javascript:`, a fragment, a host that is not one). */
+export declare function hostOf(address: string): string;

package/dist/types/remote/links/scans.d.ts

@@ -0,0 +1,27 @@
+export { CODE } from "./domains.js";
+/** What a link becomes, given its words and its address. */
+export type Mark = (label: string, address: string) => string;
+/** `[label]: url` at the start of a line: its brackets escaped (no `[words][label]` can use it) and the address made words. */
+export declare function referenceDefinitions(text: string, mark: Mark): string;
+/** Every `[words](dest)` and `![alt](dest)`, brackets and parentheses balanced (within the limits, inside one paragraph), the
+ * words made words themselves (a link in a link's words, two levels deep). */
+export declare function links(text: string, mark: Mark, depth?: number): string;
+/** `<a href=...>words</a>` as its words and host, `<img src=... alt=...>` as `🖼 alt` and host, `<scheme:...>` as its host; any
+ * other tag as it is. */
+export declare function tags(text: string, mark: Mark): string;
+/** An address without the punctuation that ends its sentence, or the closing parentheses it did not open (counted once). One
+ * pass from the end, sliced once. */
+export declare function trim(address: string): string;
+/** Every bare address as its host (in a code span whole when it names none), without the punctuation that ends its sentence or
+ * a closing parenthesis it did not open; read with any markdown escape in it taken out, as the rich text reads it. */
+export declare function bare(text: string, mark: Mark): string;
+/** Every mail address `name@host.tld` (a client makes a mail link of one) in a code span; not looked for inside a code span an
+ * earlier scan made (one there is code already, and a span opened inside it would cross it). */
+export declare function emails(text: string): string;
+/** A short line with no bare domain or mail address a client could link: a zero-width space before the dot of a domain's last
+ * label (`example\u200b.com`) and right after the `@` of a mail address. Neither shows. */
+export declare function breakDomainsAndMails(text: string): string;
+/** A bare domain left in prose next to a code span or a host made here: the scans read `docs.evil.mdmailto:` as one word, but
+ * once `mailto:` is code the client sees `docs.evil.md` on its own. Each stretch of prose between spans is read again for bare
+ * domains, its ends as a start and an end. */
+export declare function leftoverDomains(text: string): string;

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

@@ -0,0 +1,38 @@
+import type { Lang } from "../locales/lang.js";
+import { type Conversation } from "./conversations.js";
+import type { Connector, Session } from "./model.js";
+import type { ConnectorSetupWords } from "./setup.js";
+/** How an offline machine is shown: when it was last seen, in UTC (`last_seen_at`, else its last heartbeat). */
+export declare function offlineSince(connector: Connector, lang?: Lang): string;
+/** Sessions newest first (by `updated_at` as Claw wrote it), the order kept among equals. */
+export declare function newestFirst(sessions: readonly Session[]): Session[];
+/** The active sessions (a closed one can be neither attached nor closed). */
+export declare function activeSessions(sessions: readonly Session[]): Session[];
+/** The sessions the agents card lists: the active ones, newest first, at most SESSION_CARD_MAX. */
+export declare function shownSessions(sessions: readonly Session[]): Session[];
+/** The connectors by id. */
+export declare function byConnector(connectors: readonly Connector[]): Map<string, Connector>;
+export interface SessionFacts {
+    /** `icon name` of its agent. */
+    readonly who: string;
+    /** The machine's name. */
+    readonly host: string;
+    /** `attached, active, 2 h ago`. */
+    readonly facts: string;
+}
+/** Who, where and how one session of a listing is. A status Claw has no words for here is shown as it came, made inert. */
+export declare function sessionFacts(session: Session, connectors: ReadonlyMap<string, Connector>, attached: string | null, now: number, lang?: Lang): SessionFacts;
+/** `/agents` as text. With no machine: the exact commands that connect one (markdown, for a rich message). */
+export declare function agentsText(connectors: readonly Connector[], setup: ConnectorSetupWords, lang?: Lang): string;
+/** The message, and the session ids in the order shown: the newest sessions first, numbered for `/agent attach N`. */
+export declare function sessionsText(sessions: readonly Session[], connectors: readonly Connector[], attached: string | null, now: number, lang?: Lang): {
+    text: string;
+    listing: string[];
+};
+/** One conversation of the machine's own: what its terminal is doing first (waiting for you, with what for; working), then its
+ * title, folder and last activity. */
+export declare function conversationLine(entry: Conversation, now: number, lang: Lang): string;
+/** The console has a page per remote session, and the list of them, under this path. */
+export declare const SESSION_PAGE_PATH = "/primus-claw/agent-sessions";
+/** The console page of one session (or of the list, with no id); "" with no base (the worker was not told where it is). */
+export declare function sessionPageUrl(base: string, sessionId?: string): string;

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

@@ -0,0 +1,56 @@
+import type { RemoteConnector, RemoteSession } from "../claw/remote.js";
+import type { Lang } from "../locales/lang.js";
+import { ConnectorSetup } from "./connector/setup.js";
+import type { RemoteContext } from "./context.js";
+import { type Connector, type Session } from "./model.js";
+/** Claw answered 404 to a route that exists whenever remote agents are on: they are off on this PrimusClaw. */
+export declare class RemoteOff extends Error {
+    readonly name = "RemoteOff";
+}
+/** What `/agents` shows: a card, or a text (rich: it holds commands to copy). */
+export type AgentsAnswer = {
+    readonly kind: "card";
+    readonly message: import("../ports/surface.js").OutMessage;
+} | {
+    readonly kind: "rich";
+    readonly text: string;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+};
+/** The machines and sessions as Claw listed them, read with the worker's defaults (`model.ts`). */
+export interface Machines {
+    readonly raw: readonly RemoteConnector[];
+    readonly connectors: readonly Connector[];
+}
+export interface Sessions {
+    readonly raw: readonly RemoteSession[];
+    readonly sessions: readonly Session[];
+}
+export declare class Lists {
+    private readonly ctx;
+    constructor(ctx: RemoteContext);
+    private now;
+    /** The person's machines; `includeHidden`: the conversations they hid are listed too, marked hidden. */
+    machines(key: string, includeHidden?: boolean): Promise<Machines>;
+    sessions(key: string): Promise<Sessions>;
+    /**
+     * What connecting a machine takes here: Claw's own answer, else the same commands made from the address this worker reaches
+     * Claw at (an older Claw has no such route).
+     */
+    setup(key: string): Promise<ConnectorSetup>;
+    /**
+     * The pairing command for a new machine (`claw-connector pair`), or null when this Claw cannot give one: the caller then gives
+     * the sign-in steps. The line a person pastes into a shell is rebuilt here, never taken as Claw wrote it.
+     */
+    pairView(key: string, lang: Lang, lead?: string): Promise<string | null>;
+    /** The line of a card with no machine to show. */
+    noMachineLead(lang: Lang, lead: string): string;
+    /**
+     * What `/agents` shows: the agents card (`machines` false: its sessions part alone), or a text when there is nothing to tap.
+     * The sessions listed are remembered as the numbers of `/agent attach N`. `lead` is one line on top.
+     */
+    agentsView(chatKey: string, key: string, lang: Lang, lead?: string, machines?: boolean): Promise<AgentsAnswer>;
+    /** Every session the user has, on every machine; its active ones are the numbers of `/agent attach N` from now on. */
+    sessionsView(chatKey: string, key: string, lang: Lang, lead?: string): Promise<import("../ports/surface.js").OutMessage>;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Which of the user's machines and agents a typed name means, and how an offline machine is told. People name a machine
+ * (`dev-pod`), an agent by its id or by what it is (`codex`, `claude`), or both (`dev-pod/codex`); a name that more than one
+ * online machine answers to must be qualified. A machine that is offline but was heard from moments ago is reconnecting by
+ * itself (a PrimusClaw release ends every connection for a few seconds): it is tried, and never told to be restarted.
+ */
+import type { Lang } from "../locales/lang.js";
+import type { Agent, Connector, Session } from "./model.js";
+/** What a user types to name an agent: `machine/id`, inert, with no backtick to end the code span it is shown in. */
+export declare function agentRefOf(connector: Connector, agent: Agent): string;
+/** A machine last seen this recently is reconnecting, not gone. */
+export declare const RECONNECT_WINDOW_SECONDS = 120;
+/** An agent on a machine: what a name resolves to. */
+export interface AgentOnMachine {
+    readonly kind: "agent";
+    readonly connector: Connector;
+    readonly agent: Agent;
+}
+/** A name that is a machine's, not an agent's, and the machine has more than one agent to choose from. */
+export interface MachineChoice {
+    readonly kind: "machine";
+    readonly connector: Connector;
+    readonly agents: readonly Agent[];
+}
+/** Why nothing was found, as the sentence to say. */
+export interface Unresolved {
+    readonly kind: "refusal";
+    readonly text: string;
+}
+export type Resolved = AgentOnMachine | MachineChoice | Unresolved;
+/**
+ * The machine is offline but was heard from moments ago: its connector is most likely reconnecting by itself, and restarting it
+ * is not what to do. `now`: wall-clock seconds.
+ */
+export declare function reconnecting(connector: Connector, now: number): boolean;
+/** Why nothing can be started on an offline machine, and what to do: wait a moment when it is reconnecting, else start it. */
+export declare function offlineText(connector: Connector, now: number, lang?: Lang): string;
+/** The sentence `resolveAgent` gives when nothing the user has is called `ref`. */
+export declare function noAgentCalled(ref: string, lang?: Lang): string;
+/**
+ * The agent a user named, or why none: `AGENT` is an agent id (or what people call it), `MACHINE/AGENT` names the machine as
+ * well, and a name that more than one online machine has must be qualified. A bare name that is no agent's but a machine's is
+ * read as the machine. `now`: wall-clock seconds.
+ */
+export declare function resolveAgent(connectors: readonly Connector[], ref: string, now: number, lang?: Lang): Resolved;
+/**
+ * The title and ref of the existing conversation a session of `agent` continues (or watches), as its connector lists it now: the
+ * one entry it says this connector holds (`attached`; for a watch, the one a terminal has open, `live`) in the session's folder.
+ * Both '' when that is not exactly one: a title is shown only when it is certain.
+ */
+export declare function conversationOf(agent: Agent, session: Session, readOnly: boolean): {
+    title: string;
+    ref: string;
+};

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

@@ -0,0 +1,5 @@
+/** The marks a line of a list starts with, the same emoji every card uses for the meaning. */
+export declare const MARKS: {
+    readonly needsYou: "⚠️";
+    readonly working: "⏳";
+};

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

@@ -0,0 +1,51 @@
+/**
+ * The user's machines (connectors), the agents each reports and their remote sessions, as the remote-agent domain reads them:
+ * Claw's answers as the Claw client parsed them (`claw/remote.ts`, where a field that is absent or of another type is
+ * `undefined`), with the defaults the Python worker read them with (`dict.get(...)` and its fallbacks). Text stays as it came:
+ * whatever shows it makes it inert. An agent's `capabilities` stay opaque (the connector's own keys, read one by one where they
+ * are used), and times stay the strings Claw sent (they are compared and aged as written).
+ */
+import type { RemoteAgent, RemoteConnector, RemoteSession } from "../claw/remote.js";
+/** An agent a machine reports. */
+export type Agent = {
+    readonly agentId: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly capabilities: Readonly<Record<string, unknown>>;
+};
+/** One of the user's machines: its connector, whether it is online now, and the agents it reports. */
+export type Connector = {
+    readonly connectorId: string;
+    readonly name: string;
+    readonly online: boolean;
+    /** The connector's version as it reported it ("" not said). */
+    readonly version: string;
+    /** Claw's word on that version: current | outdated | unsupported | unknown ("" not said). */
+    readonly versionStatus: string;
+    /** When Claw last heard from it, ISO 8601 as Claw wrote it ("" not said); `heartbeatAt` is the older field of the same. */
+    readonly lastSeenAt: string;
+    readonly heartbeatAt: string;
+    /** Joined with a pairing code (`claw-connector pair`) rather than a sign-in. */
+    readonly paired: boolean;
+    readonly agents: readonly Agent[];
+};
+/** One of the user's remote sessions. */
+export type Session = {
+    readonly sessionId: string;
+    readonly connectorId: string;
+    readonly agentId: string;
+    readonly cwd: string;
+    /** active | closed (another word from a newer Claw is kept as it came). */
+    readonly status: string;
+    /** The session only watches a conversation open in a terminal (null: not said). */
+    readonly readOnly: boolean | null;
+    /** When it last changed, as Claw wrote it ("" not said): the newest is the one an agent's name attaches to. */
+    readonly updatedAt: string;
+};
+export declare function agentFrom(raw: RemoteAgent): Agent;
+export declare function connectorFrom(raw: RemoteConnector): Connector;
+export declare function sessionFrom(raw: RemoteSession): Session;
+/** The connector `connectorId` names, or undefined. */
+export declare function connectorById(connectors: readonly Connector[], connectorId: string): Connector | undefined;
+/** The agent `agentId` names on `connector`, or undefined. */
+export declare function agentById(connector: Connector | undefined, agentId: string): Agent | undefined;