@primusclaw/personal-agent 0.0.0-stage → 0.1.0

package/dist/types/protocol/remote-agents.d.ts

@@ -0,0 +1,230 @@
+/** Version carried in every command frame, as `v`. */
+export declare const REMOTE_AGENT_PROTOCOL_VERSION = 1;
+export declare const REMOTE_AGENT_LIMITS: {
+    /** Connectors one user may keep (revoked ones do not count). */
+    readonly maxConnectorsPerUser: 5;
+    /** Sessions one user may have open at once. */
+    readonly maxActiveSessionsPerUser: 10;
+    /** Bytes of one event's `data`, as JSON. */
+    readonly maxEventBytes: number;
+    readonly maxEventsPerBatch: 200;
+    readonly maxAgentsPerConnector: 20;
+    /** Bytes of the capabilities object one agent reports. */
+    readonly maxCapabilitiesBytes: number;
+    /** Bytes of one prompt. */
+    readonly maxPromptBytes: number;
+    /** Commands one user may issue per minute, across all connectors. */
+    readonly commandsPerMinute: 60;
+};
+export declare const REMOTE_AGENT_TIMING: {
+    /** The server sends an `event: ping` frame this often on every stream. */
+    readonly pingMs: 25000;
+    /** A connector posts a heartbeat this often. */
+    readonly heartbeatMs: 30000;
+    /**
+     * A connector is online while its command stream is open and its last
+     * heartbeat is at most this old. Three missed heartbeats.
+     */
+    readonly onlineWindowMs: 90000;
+    /**
+     * How long a `prompt`, `set_mode` or `resume` (the commands with `needsOnline`) stays
+     * deliverable once queued. They are accepted only while the connector is online, so one
+     * still uncollected after this was sent into a connection that had died unnoticed, and
+     * nobody is waiting on it: it is dropped, not replayed when the machine wakes hours later.
+     * Longer than the connector's watchdog plus a reconnect, so an ordinary blip loses nothing.
+     */
+    readonly liveCommandTtlMs: number;
+    /** A connector that sees no byte for this long drops the stream and reconnects. */
+    readonly watchdogMs: 75000;
+};
+/** The npm package the connector is published as; its command is `claw-connector`. */
+export declare const CONNECTOR_PACKAGE = "@primusclaw/connector";
+/**
+ * Which connector versions a server takes. Below `minimum` a connector still registers and is listed (so its owner
+ * sees why), but no new session is started on it (`409 connector_outdated`); below `recommended` it works and its
+ * owner is told to upgrade. A server may move both with `CLAW_REMOTE_AGENTS_MIN_CONNECTOR_VERSION` and
+ * `CLAW_REMOTE_AGENTS_RECOMMENDED_CONNECTOR_VERSION`. 0.1.3 is the first release with `service install`; 0.1.4 names
+ * the prompt every `turn_end` ends, without which an assistant item stays in progress after its last instruction.
+ */
+export declare const CONNECTOR_VERSIONS: {
+    readonly minimum: "0.1.3";
+    readonly recommended: "0.1.4";
+};
+/** `current`: at least the recommended version; `outdated`: works, upgrade; `unsupported`: below the minimum; `unknown`: no readable version. */
+export type ConnectorVersionStatus = "current" | "outdated" | "unsupported" | "unknown";
+/**
+ * Compares two `x.y.z` versions as semver orders them (a prerelease sorts before its release; build metadata is ignored). Null when
+ * either is not a version.
+ */
+export declare function compareConnectorVersions(a: string, b: string): number | null;
+/** Where `version` stands against `policy`. A connector that reports no version, or one that is no `x.y.z`, is `unknown`: it is not refused. */
+export declare function connectorVersionStatus(version: string | null | undefined, policy?: {
+    minimum: string;
+    recommended: string;
+}): ConnectorVersionStatus;
+/** Event types the server itself acts on; every other type is stored and relayed as is. */
+export declare const REMOTE_EVENT_PERMISSION_REQUEST = "permissionRequest";
+export declare const REMOTE_EVENT_PERMISSION_RESOLVED = "permission_resolved";
+export declare const REMOTE_EVENT_SESSION_CLOSED = "session_closed";
+/**
+ * What the person sent a session (a `prompt` command), written by Claw itself when it queues the prompt: `{text, cmd_id, cmd_seq,
+ * client, by: "claw"}` with a negative `seq`. An agent's events carry only its own side, so without it a window opened on the
+ * session elsewhere (another device, the web page beside a Teams chat) shows answers to questions it cannot see. A connector may
+ * not post it: a frame of this type is always Claw's account of what was sent.
+ */
+export declare const REMOTE_EVENT_USER_PROMPT = "user_prompt";
+export type Parsed<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** A UUID in canonical lower case, or null. */
+export declare function parseRemoteId(v: unknown): string | null;
+export interface RemoteAgentDescriptor {
+    agent_id: string;
+    /** Opaque to the server; a client picks an icon from it. */
+    kind: string;
+    name: string;
+    /**
+     * Whatever the connector reports, stored and relayed unchanged (at most `maxCapabilitiesBytes`). The connector in
+     * this repository reports `unattended` and `unattended_allowed` (docs/remote-agents.md, "Whether a session asks
+     * before it acts"); the server does not read them.
+     */
+    capabilities: Record<string, unknown>;
+}
+export interface RemoteHeartbeat {
+    version: string | null;
+    agents: RemoteAgentDescriptor[];
+    /** Highest `cmd_seq` the connector has fully handled; the server may forget up to it. */
+    cmdCursor: number | null;
+}
+export declare function parseConnectorRegistration(body: unknown): Parsed<{
+    name: string;
+    version: string | null;
+}>;
+export declare function parseHeartbeat(body: unknown): Parsed<RemoteHeartbeat>;
+export interface RemoteEventIn {
+    session_id: string;
+    seq: number;
+    type: string;
+    /** Milliseconds since the epoch, as the connector's clock saw it. */
+    ts: number;
+    data: Record<string, unknown>;
+}
+/** An accepted event, with its position in the posted array so a later refusal can name it. */
+export interface ParsedRemoteEvent extends RemoteEventIn {
+    index: number;
+}
+export interface RemoteEventRejection {
+    /** Position in the posted array. */
+    index: number;
+    session_id: string | null;
+    seq: number | null;
+    reason: string;
+}
+export interface RemoteEventBatch {
+    batchId: string;
+    /** Events that passed the field rules, in posted order. */
+    events: ParsedRemoteEvent[];
+    /** Events that did not. They are never stored, and retrying them cannot help. */
+    rejected: RemoteEventRejection[];
+}
+/**
+ * A malformed envelope refuses the whole batch; a malformed event refuses only
+ * itself. A client that kept resending one bad event would otherwise block every
+ * good one behind it, forever.
+ */
+export declare function parseEventBatch(body: unknown): Parsed<RemoteEventBatch>;
+export interface RemoteSessionNew {
+    connector_id: string;
+    agent_id: string;
+    cwd: string;
+    mode: string | null;
+    /**
+     * Names a session of that agent that already exists on the machine, to continue it instead of starting a new
+     * one. Claw does not interpret it: the connector reported the value (in an agent's `capabilities`) and is the
+     * only one that knows what it means.
+     */
+    resume_ref: string | null;
+    /**
+     * With `resume_ref`: the person confirmed that whatever holds that session open on the machine (a terminal) is to be
+     * ended so that this session can continue it. Without it a session held open elsewhere is only watched, read-only.
+     */
+    takeover: boolean;
+}
+export declare function parseSessionNew(body: unknown): Parsed<RemoteSessionNew>;
+/**
+ * Hiding conversations of a machine from its owner's lists (`POST /v1/remote-agents/connectors/:cid/hidden`), and the
+ * listing that leaves them out (`GET /v1/remote-agents/connectors`, `?hidden=include` to list them too). Nothing on the
+ * machine changes: only which of the conversations it reports (`capabilities.resumable`) the owner's lists show.
+ */
+export declare const REMOTE_HIDE_LIMITS: {
+    /** Conversation refs one request names, at least one. */
+    readonly maxRefs: 50;
+    /** A ref as the machine reported it: printable ASCII, no space. */
+    readonly maxRefChars: 128;
+};
+/** The value of `?hidden=` that lists the hidden conversations too, each marked `hidden: true`. */
+export declare const REMOTE_HIDDEN_INCLUDE = "include";
+/** The body of a hide (or, `hidden: false`, show again). */
+export interface RemoteHiddenRequest {
+    refs: string[];
+    hidden: boolean;
+}
+/** Why a conversation was not hidden: a process has it open (or a session holds it), or the machine does not report it now. */
+export type RemoteHideRefusalReason = "live" | "unknown_conversation";
+export interface RemoteHideRefusal {
+    ref: string;
+    reason: RemoteHideRefusalReason;
+}
+/** The answer of a hide or show (`data`): the refs that changed, and the ones refused with why. */
+export interface RemoteHidden {
+    changed: string[];
+    refused: RemoteHideRefusal[];
+}
+/** One conversation of `capabilities.resumable` as the owner's listing returns it: as the machine reported it, marked when hidden. */
+export type RemoteResumableListed = Record<string, unknown> & {
+    hidden?: true;
+};
+/**
+ * What the listing makes of an agent's `capabilities` once its owner hid any of its conversations: the conversations left
+ * (`?hidden=include`: all of them, the hidden ones marked) and how many are hidden. Absent while nothing of it is hidden.
+ */
+export interface RemoteHiddenCapabilities {
+    resumable: RemoteResumableListed[];
+    hidden_count: number;
+}
+/** A hide request as the route takes it: `hidden` a boolean, then 1 to 50 refs of printable ASCII. */
+export declare function parseHiddenRequest(body: unknown): Parsed<RemoteHiddenRequest>;
+/**
+ * The commands a user can issue into an existing session.
+ *
+ * `session.new` is not here: it creates the session and goes through
+ * {@link parseSessionNew}. The set is closed on purpose. A connector is not a
+ * remote shell, so a type that is not listed is refused at the server and
+ * dropped (and audited) at the connector.
+ */
+export declare const REMOTE_COMMAND_TYPES: readonly ["prompt", "cancel", "set_mode", "resume", "close", "decision", "withdraw"];
+export type RemoteCommandType = (typeof REMOTE_COMMAND_TYPES)[number];
+export interface RemoteCommandSpec {
+    /**
+     * Whether the command is refused while the connector is offline instead of
+     * being queued. An instruction nobody could see being waited on must not run
+     * half an hour later; an answer, a cancel or a close is safe to deliver late.
+     */
+    needsOnline: boolean;
+    /** Whether it ends the session once it is accepted. */
+    closesSession: boolean;
+    /** Validated fields as the connector will receive them (without the frame fields). */
+    parse(body: Record<string, unknown>): Parsed<Record<string, unknown>>;
+    /** What the audit trail keeps. Never the text a user typed. */
+    audit(payload: Record<string, unknown>): Record<string, unknown>;
+}
+export declare const REMOTE_COMMANDS: Record<RemoteCommandType, RemoteCommandSpec>;
+export declare function isRemoteCommandType(v: unknown): v is RemoteCommandType;
+/** One server-sent-events frame. `id` is omitted for frames a client must not resume from. */
+export declare function sseFrame(event: string | null, data: unknown, id?: string | number): string;
+/** The SSE resume position: `Last-Event-ID` or `after`, a non-negative integer, or a refusal. */
+export declare function parseCursor(...candidates: unknown[]): Parsed<number>;

package/dist/types/protocol.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The one place the personal agent reaches the Claw wire contract. The definitions live in `claw/packages/protocol`
+ * and are compiled in, never copied: Claw, the connector and the personal agent share the field names, the event
+ * types and the limits by construction, and a field Claw renames or drops fails this workspace's typecheck.
+ * `test/protocol-source.test.ts` fails if any other file under `packages/` imports that path or restates a constant.
+ *
+ * Other modules import from `./protocol.js` (inside core) or from `@primusclaw/personal-agent` (runtime, teams).
+ */
+export * from "./protocol/claw-api/index.js";
+export * from "./protocol/remote-agents.js";

package/dist/types/public-error/classify.d.ts

@@ -0,0 +1,21 @@
+/** How much of a text is looked at (the patterns stay cheap on a hostile text); a longer text is withheld. */
+export declare const SCAN_MAX = 4000;
+/** True when `text` has the shape of internal detail: an address, a host or service name, a path, a stack trace, an exception class, raw JSON. */
+export declare function looksInternal(text: unknown): boolean;
+/** True when `text` is the error a model call or a service failed with, as Brain writes it (an HTTP status first), or a stack trace. */
+export declare function looksLikeServiceError(text: unknown): boolean;
+/**
+ * True when `text` is a service error, or names an address or a stack trace and says something failed: an error, not the
+ * model's own words about one.
+ */
+export declare function looksLikeFailure(text: unknown): boolean;
+/** A failed turn's last text, split into the model's own words and the error that ended it (for the log only). */
+export interface ErrorTail {
+    readonly kept: string;
+    readonly tail: string;
+}
+/**
+ * From the first paragraph that is Brain's error on, or else the last paragraph when it names an address and says
+ * something failed, the text is the error. A paragraph with a code fence is the model's and is never cut.
+ */
+export declare function splitErrorTail(text: unknown): ErrorTail;

package/dist/types/public-error/index.d.ts

@@ -0,0 +1,4 @@
+export { SCAN_MAX, looksInternal, looksLikeFailure, looksLikeServiceError, splitErrorTail } from "./classify.js";
+export type { ErrorTail } from "./classify.js";
+export { DETAIL_LOG_MAX, PublicErrorLog, newRef } from "./public-error-log.js";
+export type { PublicErrors, WithheldIds } from "./public-errors.js";

package/dist/types/public-error/patterns.d.ts

@@ -0,0 +1,20 @@
+/** A test that holds when any of its patterns is found in the text (Python's one pattern with scoped `(?i:...)` parts). */
+export interface AnyOf {
+    test(text: string): boolean;
+}
+/** Shapes of internal detail. Any one of them is enough to keep the text back from the chat. */
+export declare const INTERNAL: AnyOf;
+/** The subset of INTERNAL that is an address or a crash, not just words a person writes. */
+export declare const ADDRESS: AnyOf;
+/** Words of a failure: live narration that has internal detail and one of these is held back. */
+export declare const FAILURE_WORDS: RegExp;
+/** The start of the error Brain writes for a model call that failed: optional error classes, then the HTTP status. */
+export declare const SERVICE_ERROR: RegExp;
+/** The part of SERVICE_ERROR that is never the model's own words (a bare "ValueError: ..." may be). */
+export declare const BRAIN_ERROR: RegExp;
+/** Credentials a URL can carry in its user-info part (scheme://user:password@host). */
+export declare const USERINFO: RegExp;
+/** Links to well-known public sites the model cites while it works: no internal endpoint, so no sign of an error. */
+export declare const PUBLIC_LINK: RegExp;
+/** A line that opens or closes a code fence. */
+export declare const FENCE: RegExp;

package/dist/types/public-error/public-error-log.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from "../ports/logger.js";
+import type { Random } from "../ports/random.js";
+import type { PublicErrors, WithheldIds } from "./public-errors.js";
+/** How much of the withheld text the log line keeps (after credential shapes are masked). */
+export declare const DETAIL_LOG_MAX = 500;
+/** A short id that ties what the person was told to the log line with the detail: 8 random hex characters. */
+export declare function newRef(random: Random): string;
+/** The PublicErrors of a worker: withheld text goes to `logger` under a reference from `random`. */
+export declare class PublicErrorLog implements PublicErrors {
+    private readonly logger;
+    private readonly random;
+    constructor(logger: Logger, random: Random);
+    withhold(where: string, detail?: unknown, ids?: WithheldIds): string;
+    publicReason(reason: unknown, where: string, ids?: WithheldIds): string;
+}

package/dist/types/public-error/public-errors.d.ts

@@ -0,0 +1,20 @@
+/** Identifiers a withheld detail is logged with (a session id, an item id); never text a person or an agent wrote. */
+export type WithheldIds = Readonly<Record<string, string | number | boolean | null | undefined>>;
+/**
+ * What a person is told when something failed, and what is kept back for the log. Text the worker did not write (a
+ * model gateway's error, a remote agent's reason, Claw's reason for a merge it did not do) can name internal hosts,
+ * paths and stack traces; the person gets a short sentence with a reference id instead, and the text goes to the log
+ * under that id.
+ */
+export interface PublicErrors {
+    /**
+     * Logs `detail` (credential shapes masked, clipped, one line) under a new reference id and returns that id, for the
+     * person's sentence. `where` names the path (a fixed word of the caller's).
+     */
+    withhold(where: string, detail?: unknown, ids?: WithheldIds): string;
+    /**
+     * `reason` as it may be shown; when it has the shape of internal detail, "an internal error (ref <id>)" with the
+     * reason withheld to the log. "" (or blank) stays "".
+     */
+    publicReason(reason: unknown, where: string, ids?: WithheldIds): string;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The buttons of the remote-agent cards, as what they do: an operation (`op`) and the fields it carries. The data a button
+ * carries is wire format (it comes back with the click): `{primusclaw: "remote", op, ...fields}`, which the worker checks against
+ * Claw's own lists, never trusting the card. The channel decides how a button looks.
+ */
+/** What the agents card, the sessions card, the status card and their follow-ups do. */
+export type RemoteOp = "new" | "list" | "attach" | "detach" | "close" | "switch" | "row" | "stop" | "mode" | "set_mode" | "pair" | "takeover" | "full" | "send" | "hide" | "hidden" | "unhide";
+/** A button's look: the primary act (`positive`), a primary act that stops or removes (`destructive`), or plain. */
+export type ButtonStyle = "positive" | "destructive" | "default";
+export type ButtonFields = Readonly<Record<string, string | number | boolean>>;
+export interface RemoteButton {
+    readonly title: string;
+    readonly op: RemoteOp;
+    /** null: no style of its own. */
+    readonly style: ButtonStyle | null;
+    /** In the order they go into the data. */
+    readonly fields: ButtonFields;
+}
+export declare function remoteButton(title: string, op: RemoteOp, style?: ButtonStyle | null, fields?: ButtonFields): RemoteButton;
+/** What a button of the agents card, the action row and their follow-ups carries; `op` says which handler. */
+export declare function remoteData(op: RemoteOp, fields?: ButtonFields): Record<string, string | number | boolean>;
+/** A button on a permission card: the option the agent offered, by its own id. */
+export interface DecisionButton {
+    readonly title: string;
+    readonly sessionId: string;
+    readonly actionId: string;
+    readonly optionId: string;
+    /** The one primary button (allow once). */
+    readonly primary: boolean;
+    /** On the session card as the window: the answer refreshes the window, not a permission card of its own. */
+    readonly inWindow?: boolean;
+}
+/** What a decision button carries (wire format: the worker reads it back). */
+export declare function decisionData(button: DecisionButton): Record<string, string | boolean>;
+/** What a button of the disconnect card carries (wire format). */
+export declare function disconnectData(connectorId: string, confirm: boolean): Record<string, string | boolean>;

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

@@ -0,0 +1,37 @@
+import type { Agent, Connector } from "./model.js";
+/** The icons of the agent kinds, and of an agent of no known kind. */
+export declare const KIND_ICONS: readonly string[];
+export interface KindLabel {
+    readonly icon: string;
+    readonly label: string;
+}
+/** The icon and label of a connector's agent `kind`. */
+export declare function kindLabel(kind: unknown): KindLabel;
+/** What a user types to name an agent: `machine/id`, shown inside a code span, each part inert and no backtick in it. */
+export declare function agentRef(connector: Pick<Connector, "name">, agent: Pick<Agent, "agentId">): string;
+/** The folders an agent says it may work in (`capabilities.roots`): strings only, one line each, each once, at most ROOTS_MAX. */
+export declare function agentRoots(agent: Agent): string[];
+/** The connector can take back a message that waits for its terminal without stopping anything (`withdraw`). */
+export declare function withdraws(agent: Agent | null | undefined): boolean;
+/** The connector can open a conversation that is open in a terminal read-only (`watch_live`). */
+export declare function watchesLive(agent: Agent): boolean;
+/** The connector types messages into the terminal that has this conversation open (a tmux pane of its user's). */
+export declare function typesInto(agent: Agent, entry: {
+    readonly input?: string;
+}): boolean;
+/** The connector can type into a terminal at all (`terminal_input`), whether or not this conversation's is one it can reach. */
+export declare function canTypeIntoTerminals(agent: Agent): boolean;
+/** A new session of this agent starts in a mode that does not ask before a write or a command (`capabilities.unattended`). */
+export declare function startsUnattended(agent: Agent): boolean;
+/** A client may switch this agent to a mode that does not ask (`capabilities.unattended_allowed`). */
+export declare function unattendedAllowed(agent: Agent): boolean;
+export type Approval = "ask" | "unattended";
+/** What a new session of `agent` may be asked to run as, when its connector lets a client switch to a mode that does not ask;
+ * the default is how its owner configured it to start. null when there is nothing to choose. */
+export declare function approvalChoice(agent: Agent): {
+    readonly default: Approval;
+} | null;
+/** The connector can take over a conversation a terminal has open, once the person confirms (`capabilities.takeover`). */
+export declare function canTakeOver(agent: Agent): boolean;
+/** The name of the agent: its own (made inert), or its kind's label. */
+export declare function agentName(agent: Agent, limit: number): string;

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

@@ -0,0 +1,9 @@
+import type { Lang } from "../locales/lang.js";
+/** `text` cut into pieces of at most `limit` characters, at a paragraph break (else a line break) past half the limit. */
+export declare function splitAtParagraphs(text: string, limit: number): string[];
+/** The messages that carry a remote agent's final text: split at paragraph boundaries, at most ANSWER_MESSAGES_MAX, and what is
+ * beyond that cut with a line saying so (the rest is in the session on the machine). Credentials are masked. */
+export declare function answerParts(text: string, lang?: Lang): string[];
+/** The messages for what a remote agent said on its own, between turns: the answer's parts, the first headed with who said it,
+ * so it is not read as the reply to the user's last message. `typed`: it answers what was typed at the terminal the chat shares. */
+export declare function unsolicitedParts(label: string, text: string, lang?: Lang, typed?: boolean): string[];

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

@@ -0,0 +1,108 @@
+import type { RemoteState } from "../ports/store/remote.js";
+import { type Conversation, type MessageId, type OutMessage } from "../ports/surface.js";
+import type { StatusPhase } from "./lines.js";
+import type { RemoteContext } from "./context.js";
+import type { ChatState } from "./state.js";
+import { Signer } from "./turns/signer.js";
+/** A status card, and whether it carries the window's text box. */
+export interface Shown {
+    readonly message: OutMessage;
+    readonly takesInput: boolean;
+}
+/** How a refresh of the window goes. */
+export interface Refresh {
+    /** A turn's end is shown. */
+    readonly ended?: boolean;
+    /** An edit while a turn streams into the card. */
+    readonly streaming?: boolean;
+    readonly lead?: string;
+    /** It answers the person's own act (only then is a card with the text box edited or removed). */
+    readonly byPerson?: boolean;
+    /** Post it again at the bottom whatever changed. */
+    readonly repost?: boolean;
+    /** A scheduled edit's: aborted, it does nothing, even when it was already waiting for its turn (Python's task cancel). */
+    readonly signal?: AbortSignal;
+}
+export declare class StatusBoard {
+    private readonly ctx;
+    private readonly state;
+    private readonly locks;
+    private readonly edits;
+    private readonly background;
+    constructor(ctx: RemoteContext, state: ChatState);
+    /** The chat's status card in `phase` (the session card when it is the window). */
+    statusOf(chatKey: string, state: RemoteState, phase: StatusPhase, lead?: string, unattended?: boolean): Shown;
+    /**
+     * Show the window as it is now: edited in place, or posted again at the bottom (the old one deleted, or closed down to a line
+     * where it cannot be) when the change is worth a new message. One at a time per chat. True when a new card was posted.
+     */
+    refreshWindow(chatKey: string, to: Conversation, how?: Refresh): Promise<boolean>;
+    /** The window edited in place when that is enough, else posted again; true when a new card was posted. */
+    private editOrRepost;
+    /**
+     * Post the window as a new card at the bottom; the one it replaces is deleted, or, with `keep`, left as it is (it has the text
+     * box: `dropKept` removes it at the person's next act). False when no new card came.
+     */
+    private repostWindow;
+    /** Delete a card of this chat's, or (the channel cannot) close it down to the line that says where the new one is. */
+    removeOrRetire(chatKey: string, to: Conversation, cardId: MessageId): Promise<void>;
+    /** The person has acted: the older cards with a text box that were kept for them go now. */
+    dropKept(chatKey: string, to: Conversation): Promise<void>;
+    /** An edit of the window EDIT_SECONDS from now, unless one is waiting already (it shows what is newest when it runs). */
+    scheduleWindow(chatKey: string, to: Conversation): void;
+    cancelWindowEdit(chatKey: string): void;
+    private track;
+    /** Wait for what runs in the background (tests, shutdown). */
+    settled(): Promise<void>;
+    /**
+     * What the agent says between turns, into the window: `final`, a burst that is over (shown by `windowSettled`, once the reader
+     * has let go of it); else the text so far, shown by a throttled edit. False when the chat shows no window.
+     */
+    windowSaid(chatKey: string, text: string, final: boolean): boolean;
+    /** What the agent said between turns has been taken in by the reader: the window shows it, and the state as it is now. */
+    windowSettled(chatKey: string): Promise<void>;
+    /**
+     * Send the status card as a new message and remember it; the card it replaces is closed down to a line saying where the new one
+     * is (it is history now, and its buttons would act on a card that is not the chat's any more).
+     */
+    postStatus(chatKey: string, to: Conversation, card: Shown): Promise<void>;
+    /** A status card was just posted or put in place: when it is the session card, what it shows counts as posted. */
+    noteWindowShown(chatKey: string, card: Shown): void;
+    retireStatus(to: Conversation, cardId: MessageId, chatKey: string): Promise<void>;
+    /**
+     * Edit the chat's status card in place: true when there is one and the edit was handed over. Never for a chat that is the
+     * agent's window itself: it has no status card, and one it had before is left as it is.
+     */
+    editStatus(chatKey: string, to: Conversation, card: Shown): Promise<boolean>;
+    /**
+     * The session has started (ready, or found open in a terminal): the status card says so, in place. A session card that is the
+     * window is posted again at the bottom instead (the card that said "starting" had no text box). True when the card shows it.
+     */
+    settleStatus(chatKey: string, to: Conversation, state: RemoteState, phase: StatusPhase, lead?: string): Promise<boolean>;
+    /**
+     * The status card says what the session is doing now (a turn began or ended): edited in the background, never a new message
+     * (the window may be posted again when that is due). `state`: the session the card is about when the chat has just left it.
+     */
+    touchStatus(chatKey: string, to: Conversation, phase?: StatusPhase, state?: RemoteState, byPerson?: boolean): void;
+    /**
+     * What a chat that has just attached (or switched) by a typed command is shown: entering from the assistant, ONE new status
+     * card; switching from another session, the status card edited in place and one short line saying which session it is in now.
+     */
+    showEntered(chatKey: string, to: Conversation, was: RemoteState | null, phase: StatusPhase, lead?: string, unattended?: boolean): Promise<void>;
+    /**
+     * A chat that is the agent's window itself has just attached or switched: one line says where its messages go now (with a
+     * warning when the session does not ask before it acts), and the way back is the suggested reply under it. The status card it
+     * may still have from before is forgotten, so nothing edits it any more.
+     */
+    sayEntered(chatKey: string, to: Conversation, state: RemoteState, unattended?: boolean, lead?: string): Promise<void>;
+    /**
+     * The suggested replies under what the assistant says to a chat that is the agent's window itself: back to the assistant while
+     * attached, else back to the agent it last talked to.
+     */
+    backReplies(chatKey: string): {
+        title: string;
+        value: string;
+    }[];
+    /** How a chat that is the agent's window signs what it wrote: its head, and the way on and back under the last message. */
+    signerOf(chatKey: string, state: RemoteState): Signer;
+}

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

@@ -0,0 +1,4 @@
+/** A view as a message to post. */
+import type { OutMessage, View } from "../ports/surface.js";
+/** A view as a message; `fallback` is what a client that cannot show it shows. */
+export declare function viewMessage(view: View, fallback: string): OutMessage;

package/dist/types/remote/chat-key.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A group chat's binding to a session is its own chat state, kept apart from the person's 1:1 chat: every per-chat record of
+ * remote agents (the attached session, its status card, the reader that follows it) is keyed by a "chat key", the binder's user
+ * id and the group conversation. Only the binder's own messages in that group read it, so another member's words never reach
+ * the session. A 1:1 chat's key is the person's id itself. The stored keys keep this exact shape (`remote_state.aad_id`).
+ */
+/** Joins the binder and the group conversation (a user id is a GUID: it never holds one). */
+export declare const GROUP_KEY_SEP = "#";
+/** The chat key of `userId`'s binding in the group conversation `conversationId`. */
+export declare function groupChatKey(userId: string, conversationId: string): string;
+/** The person a chat key belongs to: the key itself for a 1:1 chat, the binder for a group's. */
+export declare function personOf(chatKey: string): string;
+export declare function isGroupKey(chatKey: string): boolean;

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

@@ -0,0 +1,76 @@
+/**
+ * What this process knows of each chat attached to a remote session, beside what the store keeps: what reads the session now (a
+ * turn, a short watch, the follower), what its connector reported when the chat attached, whether the session only watches a
+ * conversation open in a terminal, and the one-time tokens of the cards it showed. Keyed by the chat key (`chat-key.ts`). All of it
+ * is lost when the process restarts, as it was in the Python worker; what must survive is in the store.
+ */
+import type { Follower } from "./follow/follower.js";
+import type { Task } from "./tasks.js";
+/** Folders typed in a `/agent new MACHINE PATH` kept for the buttons of the card that asks which agent, per chat. */
+export declare const TYPED_PATHS_KEPT = 20;
+export declare const TYPED_PATH_SECONDS = 3600;
+/** How long a takeover's confirmation card can be answered. */
+export declare const TAKEOVER_CONFIRM_SECONDS = 600;
+/** A turn this process is reading: its task, and whether the person asked to stop it. */
+export interface RemoteTurn {
+    task: Task | null;
+    stopRequested: boolean;
+    /** Its message waits for the machine's terminal and has not been typed there yet. */
+    waitsForTerminal: boolean;
+    /** Nothing runs it any more (or nothing ever did): a Stop card's press for it stops nothing. */
+    readonly ended: boolean;
+}
+/** A turn about to be watched (its task is set right after). */
+export declare function newTurn(): RemoteTurn;
+/** The confirmation card for taking over a conversation a terminal has open: only its own Take over carries the ticket. */
+export interface TakeoverTicket {
+    readonly connectorId: string;
+    readonly agentId: string;
+    readonly ref: string;
+    readonly ticket: string;
+    /** Wall-clock seconds. */
+    readonly until: number;
+}
+export declare class ChatRegistry {
+    /** The reader of the attached session while no turn reads it. */
+    readonly followers: Map<string, Follower>;
+    /** Chats `forget` was called for: nothing follows them until they attach again. */
+    readonly unlinked: Set<string>;
+    readonly turns: Map<string, RemoteTurn>;
+    /** A short watch (`/agent new` waiting for the agent, `/agent mode` for its answer). */
+    readonly watchers: Map<string, Task>;
+    /** Whether the agent of the attached session starts in a mode that does not ask (its connector's report). */
+    readonly agentUnattended: Map<string, boolean>;
+    /** Whether the agent of the attached session can take over a conversation a terminal has open. */
+    readonly agentTakeover: Map<string, boolean>;
+    private readonly typed;
+    private readonly readOnly;
+    private readonly readOnlyKnown;
+    private readonly terminalInput;
+    private readonly tickets;
+    watching(chatKey: string): boolean;
+    /** The chat's session only watches a conversation open in a terminal (read-only). */
+    watches(chatKey: string, sessionId: string | null): boolean;
+    /** Whether this process has learned (from an event, or by reading back) whether the session only watches. */
+    knowsWatch(chatKey: string, sessionId: string): boolean;
+    learnedWatch(chatKey: string, sessionId: string): void;
+    markReadOnly(chatKey: string, sessionId: string, readOnly: boolean): void;
+    /** A new session says itself whether it only watches. */
+    clearReadOnly(chatKey: string): void;
+    markTerminal(chatKey: string, sessionId: string, terminal: boolean): void;
+    /** What is sent to the chat's session is typed into a terminal on the machine. */
+    typesIntoTerminal(chatKey: string, sessionId: string | null): boolean;
+    /**
+     * Keep a folder typed for the buttons of the card that asks which agent (a token names it: the card can say where a session goes,
+     * a tap cannot choose it). A few per chat, for an hour. `now`: wall-clock seconds.
+     */
+    rememberPath(chatKey: string, path: string, token: string, now: number): string;
+    typedPath(chatKey: string, token: string, now: number): string | null;
+    /** Remember the takeover card shown last to this chat (the previous one is replaced: only the last can start a takeover). */
+    issueTicket(chatKey: string, ticket: TakeoverTicket): void;
+    ticketOf(chatKey: string): TakeoverTicket | undefined;
+    /** The ticket is used: a takeover starts from that card once. */
+    spendTicket(chatKey: string): void;
+    /** Everything known of a chat whose person unlinked (its session's reader is stopped by the caller). */
+    forget(chatKey: string): void;
+}

package/dist/types/remote/clicks-machine.d.ts

@@ -0,0 +1,24 @@
+import type { Click, SessionClicks } from "./clicks.js";
+import type { CommandParts } from "./commands.js";
+export declare class MachineClicks {
+    private readonly p;
+    private readonly c;
+    constructor(p: CommandParts, c: SessionClicks);
+    /** The person's connector the tapped button names, as Claw lists it now; null (said) when it is not theirs any more. */
+    private ownConnector;
+    /** Hide one conversation (`ref`), or every one no process runs of one agent (`all: idle`), from the list. */
+    hide(click: Click): Promise<void>;
+    /** The conversations hidden on that machine, each with Unhide. */
+    hidden(click: Click): Promise<void>;
+    /** Show one hidden conversation (`ref`) again, or all of that machine's (`all`). */
+    unhide(click: Click): Promise<void>;
+    /**
+     * A tap on the disconnect card. The card names a connector id; whose it is is Claw's to say (404 for anyone else's), and the
+     * machine's name is read again from the person's own list.
+     */
+    off(click: Click): Promise<void>;
+    /** The tap ends with `text` in place of the card. */
+    private settled;
+    /** It did not go through: said; where pressing again can help, the card comes back with its buttons. */
+    private offRefused;
+}