@primusclaw/personal-agent 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,36 @@
+import type { Shown } from "./board.js";
+import type { Click, SessionClicks } from "./clicks.js";
+import type { CommandParts } from "./commands.js";
+export declare class StartClicks {
+    private readonly p;
+    private readonly c;
+    constructor(p: CommandParts, c: SessionClicks);
+    private now;
+    /** The connector and agent a tap names, from the person's own list as Claw gives it now; null (said) when gone. */
+    private named;
+    /** New session: on an agent the person has, in a folder it reports or a conversation it offers. */
+    newSession(click: Click): Promise<void>;
+    /**
+     * Where a New session tap starts: the conversation it takes over (where it lives is what the agent reported), or the folder the
+     * card names; and the kind of session the card asked for when it is not how the agent starts. Or why not.
+     */
+    private whereTo;
+    /** The watch of this conversation is over: the session that takes it over is the chat's now. */
+    private closeWatchOf;
+    /** Attach: to one of the person's sessions, as the list showed it. */
+    attach(click: Click): Promise<void>;
+    /**
+     * Take over… on a conversation a terminal has open: the card becomes the confirmation that says what taking it over does;
+     * nothing starts until its Take over is tapped. A conversation the terminal let go of meanwhile needs no confirmation.
+     */
+    takeover(click: Click): Promise<void>;
+    /**
+     * What a tap that attached the chat leaves: one line saying which session it is in now, then its status card as a NEW message
+     * and the tapped card deleted (a phone does not redraw an edit). Where no new card can be sent, the tapped card becomes the
+     * status card in place.
+     */
+    becomeStatus(click: Click, card: Shown | null): Promise<void>;
+    private post;
+    private inPlace;
+    private removeTapped;
+}

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

@@ -0,0 +1,61 @@
+import type { Lang } from "../locales/lang.js";
+import type { RemoteState } from "../ports/store/remote.js";
+import { type Conversation, type OutMessage } from "../ports/surface.js";
+import { type AgentCommands, type CommandParts } from "./commands.js";
+import type { Provider } from "./ended.js";
+import type { Settle } from "./permissions.js";
+import type { Prompts } from "./prompt.js";
+import { type Tap } from "./window/closer.js";
+/** One tap: who, with which credential, on which card, and how it ends. */
+export interface Click extends Tap {
+    readonly key: string;
+    readonly provider: Provider;
+    /** The channel's id of the tap (a Send's idempotency). */
+    readonly id: string;
+    readonly settle: Settle;
+}
+/** The ops a tap may name; anything else is refused. */
+export declare const CLICK_OPS: readonly ["new", "attach", "detach", "close", "mode", "set_mode", "row", "list", "switch", "stop", "takeover", "send", "full", "pair", "hide", "hidden", "unhide"];
+export type ClickOp = (typeof CLICK_OPS)[number];
+export declare function isClickOp(op: string): op is ClickOp;
+/** The taps that only show something or act on the attached session. */
+export declare class SessionClicks {
+    private readonly p;
+    private readonly commands;
+    private readonly prompts;
+    constructor(p: CommandParts, commands: AgentCommands, prompts: Prompts);
+    lang(click: Click): Lang;
+    end(click: Click, card: OutMessage | string, fallback?: string, announce?: boolean): Promise<boolean>;
+    /** End a tap with the card it came from again (the sessions card, or the agents card), `lead` on top. */
+    home(click: Click, lead: string): Promise<void>;
+    /**
+     * A tap on the agents card (or the sessions card) that leaves the chat where it is ends with that card again, sent as a NEW
+     * message and the tapped one deleted (or closed down to a line pointing at the new one). The chat's status card is never deleted
+     * here: a tap that ends on the list from it is answered in place, and so is any tap whose new card could not be sent.
+     */
+    repost(click: Click, card: OutMessage, lead?: string): Promise<void>;
+    deleted(to: Conversation, id: string): Promise<boolean>;
+    /** A tap that did not go through: the status card again when it was one of its buttons and still the chat's, else the list. */
+    back(click: Click, lead: string): Promise<void>;
+    /** The chat's attachment when the tap is about it (the card names the session); else the tap is answered and null. */
+    ownSession(click: Click): Promise<RemoteState | null>;
+    /** Connect a new machine: the command as a message of its own, then the agents card again under it, pointing up to it. */
+    pair(click: Click): Promise<void>;
+    row(click: Click): Promise<void>;
+    /** Switch (and Sessions, Refresh): the card that was tapped becomes the list of every session, with no line in the chat. */
+    switch(click: Click): Promise<void>;
+    stop(click: Click): Promise<void>;
+    private closer;
+    /** Send on the session card: the card's text box goes to the session; the tap ends at once with the window showing it. */
+    send(click: Click): Promise<void>;
+    /** Full output: the output the window holds, whole (masked), as messages after the card. */
+    full(click: Click): Promise<void>;
+    mode(click: Click): Promise<void>;
+    setMode(click: Click): Promise<void>;
+    detach(click: Click): Promise<void>;
+    close(click: Click): Promise<void>;
+    list(click: Click): Promise<void>;
+}
+/** One part of the full output as its fenced block holds it: what the rich text drops taken out first (else `https:\x01//` or a
+ * fence split by a bidi override would join once it reads them), every address broken in place, no fence that could close it. */
+export declare function fullBlockText(part: string): string;

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

@@ -0,0 +1,60 @@
+import type { Lang } from "../locales/lang.js";
+import { type Conversation, type OutMessage } from "../ports/surface.js";
+import type { StatusBoard } from "./board.js";
+import type { RemoteContext } from "./context.js";
+import type { Provider } from "./ended.js";
+import type { FollowControl } from "./follow/control.js";
+import { type AgentsAnswer, type Lists } from "./lists.js";
+import type { SessionOps } from "./session-ops.js";
+import type { SessionStarts } from "./sessions.js";
+import { type ChatState } from "./state.js";
+import { type Targets } from "./targets.js";
+import { type Watches } from "./watches.js";
+/** One `/agent` command: the chat, the person's credential, where to answer, and what refreshes the credential. */
+export interface CommandCall {
+    readonly chatKey: string;
+    readonly key: string;
+    readonly to: Conversation;
+    readonly provider: Provider;
+}
+/** What the commands work with. */
+export interface CommandParts {
+    readonly ctx: RemoteContext;
+    readonly state: ChatState;
+    readonly board: StatusBoard;
+    readonly lists: Lists;
+    readonly starts: SessionStarts;
+    readonly ops: SessionOps;
+    readonly targets: Targets;
+    readonly watches: Watches;
+    readonly follow: FollowControl;
+}
+/** The sentence for an error a remote-agents call ended in, or null when it is none of the expected ones (it is thrown on). */
+export declare function refusalOf(error: unknown, ctx: RemoteContext, lang: Lang): string | null;
+/** A message for what `/agents` shows. */
+export declare function agentsMessage(answer: AgentsAnswer): OutMessage;
+export declare class AgentCommands {
+    private readonly p;
+    constructor(p: CommandParts);
+    private lang;
+    private say;
+    /** `/agents`; the reasons it cannot be shown are sentences like everywhere else here. */
+    agents(call: CommandCall, lead?: string, machines?: boolean): Promise<void>;
+    /** `/agent ARGS`. */
+    agent(call: CommandCall, args: string): Promise<void>;
+    private run;
+    private pair;
+    private newSession;
+    /** Start a session (taking over its conversation, when there is one), say so, and watch for the agent's first word. */
+    private start;
+    private sessions;
+    private attach;
+    private detach;
+    private mode;
+    /** Ask the agent to switch to `mode` (the watch says when it has): why not, or null. */
+    changeMode(call: CommandCall, mode: string): Promise<string | null>;
+    private close;
+    /** The session a person named by its number in the last listing or by its id; null after saying why not. */
+    private pickSession;
+    private off;
+}

package/dist/types/remote/connector/reasons.d.ts

@@ -0,0 +1,31 @@
+import type { Lang } from "../../locales/lang.js";
+import { Setup } from "./setup.js";
+/** A sentence in both languages: [Chinese, English]. */
+export type Pair = readonly [zh: string, en: string];
+/** The release whose Claude agent runs as root with `approval = "never"`; an older connector there refuses every new session. */
+export declare const FIXED_IN: readonly [number, number, number];
+/** The one upgrade command: it installs the new version and restarts the connector on it, under whichever supervisor it has. */
+export declare const UPGRADE: Pair;
+export declare const SANDBOX: Pair;
+export declare const STATUS: Pair;
+/** Codes an older connector hits on a root machine with `approval = "never"`: an upgrade fixes them (see `FIXED_IN`). */
+export declare const OLD_CONNECTOR: ReadonlySet<string>;
+/** Every code that has a sentence of its own. */
+export declare function knownReasons(): string[];
+/** `0.1.4` (or `v0.1.4`, `0.1.5-rc.1`) as [major, minor, patch]; null for anything else. */
+export declare function parseVersion(value: unknown): [number, number, number] | null;
+export declare function isCode(reason: string): boolean;
+/**
+ * [Chinese, English] for one reason code: what happened and what to do. An unknown code gets a generic pair that names it.
+ * `setup`: the commands of the address this worker reaches Claw at (the login a revoked connector is given).
+ */
+export declare function explain(code: string, version?: unknown, setup?: Setup): Pair;
+/** A reason as given: trimmed, without the full stops at its end. */
+export declare function bareReason(reason: string | null | undefined): string;
+/**
+ * The sentence(s) for a reason a connector gave, in `lang` (null: Chinese, then English on the next line). '' for no reason. A
+ * reason that is not a code (words, or an internal error withheld) is kept as it is, as a sentence.
+ */
+export declare function describe(reason: string | null | undefined, lang: Lang | null, version?: unknown, setup?: Setup): string;
+/** `lead` ("the session could not start") with the reason after it, as one paragraph in `lang` (null: both, one per line). */
+export declare function ended(lead: Pair, reason: string | null | undefined, lang: Lang | null, version?: unknown, setup?: Setup): string;

package/dist/types/remote/connector/setup.d.ts

@@ -0,0 +1,62 @@
+/**
+ * How to connect a machine to PrimusClaw and how to upgrade its connector, as the exact commands a person copies.
+ *
+ * Claw says what to run (`GET /v1/remote-agents/setup`): the npm package, `claw-connector init`, `claw-connector login` with Claw's
+ * public API URL and the identity service it signs in with, and `claw-connector service install`. When that route cannot be read
+ * (an older Claw), the same commands are made from the address this worker reaches Claw at, and its host's identity service.
+ *
+ * Nothing here talks to Claw or to a chat.
+ */
+import type { ConnectSteps, ConnectorSetupWords } from "../setup.js";
+import type { Connector } from "../model.js";
+import type { Lang } from "../../locales/lang.js";
+export declare const CONNECTOR_PACKAGE_NAME = "@primusclaw/connector";
+/**
+ * Upgrades the connector and restarts it on the new version: a running connector keeps the old code until it is restarted, and
+ * `service install` starts it again under whichever supervisor the machine has. The same as Claw's `upgrade_command`.
+ */
+export declare const UPGRADE_COMMAND = "npm install -g @primusclaw/connector@latest && claw-connector stop && claw-connector service install";
+/** `value` as an address fit for a shell command, without a trailing slash; null when it is anything else. */
+export declare function safeUrl(value: unknown): string | null;
+/** The commands that connect a machine: the server it signs in to and the identity service it signs in with. */
+export declare class Setup {
+    readonly server: string;
+    readonly identityUrl: string | null;
+    constructor(server: string, identityUrl: string | null);
+    login(): string;
+    commands(): string[];
+}
+/**
+ * The commands Claw gave (`data`, the route's answer), else the ones made from `baseUrl` (the address this worker reaches Claw at)
+ * and its host's identity service. What Claw gave is taken only when its server is on that host over the same scheme, and its
+ * identity service too (a different one is replaced by that host's): a person is never sent to sign in somewhere else, nor over
+ * plain http.
+ */
+export declare function setupFrom(data: unknown, baseUrl: string): Setup;
+/**
+ * The one line that pairs a machine, from Claw's answer: rebuilt from its code (only of the shape Claw issues) and its server (only
+ * on the host this worker reaches Claw at, as `setupFrom` takes one), so nothing else reaches a shell. Null when either is not so.
+ */
+export declare function pairCommand(data: unknown, baseUrl: string): string | null;
+/** The connect steps, in the order they are shown: what a message or a card is made from. */
+export declare function connectSteps(setup: Setup, lang: Lang, lead?: string): ConnectSteps;
+/** The connect steps as markdown for a rich message: the commands in one code block a person copies whole. */
+export declare function connectMarkdown(setup: Setup, lang: Lang, lead?: string): string;
+export declare function upgradeText(lang: Lang, command?: string): string;
+/**
+ * One line under a machine whose connector Claw says is old (`version_status`), with the command that upgrades it; else null. The
+ * command is this module's, never text from the connector list.
+ */
+export declare function versionNote(connector: Pick<Connector, "version" | "versionStatus">, lang?: Lang): string | null;
+/** What brings an offline machine back. */
+export declare function offlineHint(lang?: Lang): string;
+/** What the remote-agent views say about connecting a machine, from the commands of the address this worker reaches Claw at. */
+export declare class ConnectorSetup implements ConnectorSetupWords {
+    readonly setup: Setup;
+    constructor(setup: Setup);
+    connectMarkdown(lang: Lang, lead?: string): string;
+    connectSteps(lang: Lang, lead?: string): ConnectSteps;
+    versionNote(connector: Connector, lang: Lang): string | null;
+    offlineHint(lang: Lang): string;
+    login(): string;
+}

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

@@ -0,0 +1,101 @@
+import type { RemoteViews } from "./ports.js";
+import type { DirectChat } from "../direct-chat/direct-chat.js";
+import type { ClawRemoteAgentsPort } from "../ports/claw/remote-agents.js";
+import type { JsonObject } from "../json.js";
+import type { Lang } from "../locales/lang.js";
+import type { PublicErrors } from "../public-error/public-errors.js";
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { Random } from "../ports/random.js";
+import type { ConversationRefRepository, PrefsRepository } from "../ports/store/people.js";
+import type { RemotePermissionRepository, RemoteSessionNameRepository, RemoteStateRepository } from "../ports/store/remote.js";
+import type { Conversation } from "../ports/surface.js";
+import type { ConnectorSetup } from "./connector/setup.js";
+import type { FollowReach } from "./follow/speaker.js";
+import type { FollowTimings } from "./follow/timings.js";
+import type { RefusalErrors } from "./refusals.js";
+import type { WindowMode } from "./window/view.js";
+/** The per-person limits of what a remote agent may do without asking (`guardrails`). */
+export type GuardedOperation = "remote_agent" | "approval";
+export interface GuardRefusal {
+    /** The sentence the person is told (English unless asked otherwise). */
+    text(): string;
+}
+export interface RemoteGuard {
+    /** Count one operation, or refuse it (nothing counted). `ticket` names this count for `giveBack`. */
+    take(person: string, operation: GuardedOperation, ticket: object, ids?: Readonly<Record<string, string | null>>): GuardRefusal | null;
+    giveBack(person: string, operation: GuardedOperation, ticket: object | null): void;
+}
+/** What a person is told of a failure and what goes to the log instead (`public-error`). */
+export interface RemoteErrors extends PublicErrors, RefusalErrors {
+    /** The text with a raw error at its end cut off: what may be shown, and the cut error (for the log). */
+    splitErrorTail(text: string): {
+        readonly kept: string;
+        readonly tail: string;
+    };
+    /** A fresh reference id for a sentence about a failure. */
+    newRef(): string;
+}
+export interface RemoteSettings {
+    /** Remote agents are on for this deployment. */
+    readonly enabled: boolean;
+    /** An attached chat hears its session between turns (REMOTE_PUSH_ENABLED). */
+    readonly follow: boolean;
+    /** Where the chat box goes when its person never said (REMOTE_WINDOW_DEFAULT). */
+    readonly windowDefault: WindowMode;
+    readonly timings: FollowTimings;
+    /** How a watched conversation is followed. */
+    readonly watchTimings: FollowTimings;
+    /** The assistant's display name. */
+    readonly botName: string;
+    /** How long `/agent new` waits for the agent's first word, and `/agent mode` for its answer (defaults: 30 s and 10 s). */
+    readonly watchSeconds?: {
+        readonly start: number;
+        readonly mode: number;
+    };
+    /** A turn is shown in a live stream answering the person's message (the reply style streams here and the channel can). */
+    readonly streaming: boolean;
+}
+export interface RemoteContext {
+    readonly settings: RemoteSettings;
+    readonly claw: ClawRemoteAgentsPort;
+    /** The address this worker reaches Claw at: what the commands for a machine are checked against. */
+    readonly clawBaseUrl: string;
+    /** The connect commands of that address. */
+    readonly setup: ConnectorSetup;
+    /** The cards and the live view the remote agents show (the view's `createRemoteViews`, given by the assembly). */
+    readonly views: RemoteViews;
+    readonly remoteState: RemoteStateRepository;
+    readonly sessionNames: RemoteSessionNameRepository;
+    readonly permissions: RemotePermissionRepository;
+    readonly prefs: PrefsRepository;
+    readonly references: ConversationRefRepository;
+    /** The conversation a stored reference posts to. */
+    conversationFor(reference: JsonObject): Conversation;
+    /** What to read Claw with for a person with nobody to ask (null: none; throws `CredentialUnavailable` just now). */
+    credentialFor(person: string): Promise<string | null>;
+    readonly reach: FollowReach;
+    readonly guard: RemoteGuard;
+    /** One security event (`approval_answered`). */
+    audit(event: "approval_answered", fields: Readonly<Record<string, string | number | null>>): void;
+    readonly errors: RemoteErrors;
+    readonly clock: Clock;
+    /**
+     * The clock of the remote agents' own paced waits (a turn's live view, a throttled edit of the session card, a retry): `clock`
+     * when not given. Tests give a virtual one, so nothing really waits for them.
+     */
+    readonly paceClock?: Clock;
+    readonly random: Random;
+    readonly logger: Logger;
+    /** The hex digest of `text` (UTF-8): an idempotency key, a correlation id. */
+    digestHex(algorithm: "sha1" | "sha256", text: string): string;
+    /** The language a person is answered in. */
+    langOf(person: string): Lang;
+    /** TEAMS_DIRECT_CHAT: whose 1:1 chat is the agent's window itself. */
+    readonly directChat: DirectChat;
+}
+/**
+ * The per-person limits as a chat key reads them (Python's `_PersonGuard`): a group binding's chat key
+ * (`person#conversation`) counts against its binder's own allowance, so binding another group is no new allowance.
+ */
+export declare function perPerson(guard: RemoteGuard): RemoteGuard;

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

@@ -0,0 +1,37 @@
+import type { Agent } from "./model.js";
+/** What a connector says about a conversation: no process runs it, a terminal has it open, a session of the chat's holds it. */
+export type ConversationState = "idle" | "live" | "attached" | "unknown";
+/** What a connector says a terminal is doing with a conversation it has open. */
+export type TerminalActivity = "working" | "waiting" | "idle";
+/** One conversation an agent offers, read defensively. */
+export interface Conversation {
+    readonly ref: string;
+    /** One inert line, "" when the connector gave none. */
+    readonly title: string;
+    readonly cwd: string;
+    /** Seconds since the epoch, or null. */
+    readonly updatedAt: number | null;
+    readonly state: ConversationState;
+    /** Only for one a terminal has open. */
+    readonly activity?: TerminalActivity;
+    /** What its terminal waits for (only while `activity` is waiting), one inert line. */
+    readonly waitingFor?: string;
+    /** Its connector types what is sent into that terminal (only for one a terminal has open). */
+    readonly input?: "terminal";
+}
+/** What a connector says about a conversation that may be taken over now. */
+export declare const TAKEOVER_STATES: readonly ConversationState[];
+/** Open in a terminal: it can be watched, read-only (the connector shows it and refuses input). */
+export declare const WATCH_STATE: ConversationState;
+/** The conversations an agent offers (newest first, as reported), at most twelve. An entry without a usable `ref` or `cwd` is
+ * dropped, a repeated ref is kept once, and a state that is none of the four is "unknown". */
+export declare function resumableOf(agent: Agent): Conversation[];
+/** Its terminal waits for its person. */
+export declare function needsYou(entry: Conversation): boolean;
+/** A subfolder typed under a root as `a/b` (separators `/` or `\`, `.` parts dropped); "" when nothing was typed; null for anything
+ * that is not a plain path below the root: absolute, `~`, a drive, a `..` part, a control character, too long. */
+export declare function cleanSubfolder(text: unknown): string | null;
+/** `root` with `sub` below it, with the separator the root itself uses. */
+export declare function joinPath(root: string, sub: string): string;
+/** The conversations of an agent its owner hid (`hidden: true`, in a listing with them included), read as `resumableOf` reads them. */
+export declare function hiddenOf(agent: Agent): Conversation[];

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

@@ -0,0 +1,25 @@
+import { type Pair } from "./connector/reasons.js";
+import type { RemoteContext } from "./context.js";
+import type { Lists } from "./lists.js";
+import type { ChatState } from "./state.js";
+/** What reads Claw for a person now: their key, or what a provider gives (an exchanged token). */
+export type Provider = (() => Promise<string>) | undefined;
+export declare function credentialOf(key: string, provider: Provider): Promise<string>;
+export declare class EndedWords {
+    private readonly ctx;
+    private readonly state;
+    private readonly lists;
+    constructor(ctx: RemoteContext, state: ChatState, lists: Lists);
+    /**
+     * The version the machine's connector reports, when the reason is one an upgrade fixes and Claw says it; null otherwise (the
+     * sentence then offers the upgrade, which cannot hurt).
+     */
+    connectorVersion(key: string, provider: Provider, connectorId: string, reason: string | null): Promise<string | null>;
+    /** `lead` with the reason after it, in the chat's language, the version read when an upgrade would fix it. */
+    said(chatKey: string, lead: Pair, key: string, provider: Provider, connectorId: string, reason: string): Promise<string>;
+    /**
+     * The paragraph that says a session ended and why; `follow`: told while the chat was idle (its messages go to the assistant
+     * again).
+     */
+    sessionEnded(chatKey: string, key: string, provider: Provider, connectorId: string, reason: string, follow?: boolean): Promise<string>;
+}

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

@@ -0,0 +1,65 @@
+import type { SseEvent } from "../claw/model.js";
+import type { PublicErrors } from "../public-error/public-errors.js";
+export interface ToolUpdate {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+}
+/** What the runner does after one event. Every field but the flags is null when the event does not say it. */
+export interface RemoteStep {
+    readonly chunk: {
+        readonly kind: "message" | "thought";
+        readonly text: string;
+    } | null;
+    readonly tool: ToolUpdate | null;
+    /** One line saying where the plan stands. */
+    readonly plan: string | null;
+    /** A permissionRequest's payload, to turn into a card. */
+    readonly permission: Readonly<Record<string, unknown>> | null;
+    /** A permission_resolved payload: another client answered. */
+    readonly resolved: Readonly<Record<string, unknown>> | null;
+    readonly mode: string | null;
+    readonly modes: readonly string[] | null;
+    /** The session, as it is now, does not ask before a step. */
+    readonly unattended: boolean | null;
+    /** Mode id -> whether selecting it makes the session unattended, for the modes that say. */
+    readonly modeFlags: Readonly<Record<string, boolean>> | null;
+    /** One line for the view (a resume, a mode change, an error). */
+    readonly note: string | null;
+    readonly started: boolean;
+    /** The turn is over. */
+    readonly finished: boolean;
+    readonly stopReason: string;
+    /** The session ended: the reason, "" when none was given. */
+    readonly closed: string | null;
+    /** A command the connector refused. */
+    readonly rejected: {
+        readonly type: string;
+        readonly reason: string;
+    } | null;
+    /** An event of history the agent replayed: never shown as new. */
+    readonly replay: boolean;
+    /** The session only watches a conversation open in a terminal. */
+    readonly readOnly: boolean | null;
+    /** The connector restarted and the session is back. */
+    readonly recovered: {
+        readonly interrupted: boolean;
+        readonly continuing: boolean;
+    } | null;
+    /** A message for a terminal's conversation waits for that terminal (the connector's reason). */
+    readonly queued: string | null;
+    /** What the person typed at the terminal of a conversation shared with the chat. */
+    readonly typed: string | null;
+    /** What is sent is typed into a terminal on the machine (`input: "terminal"`). */
+    readonly terminal: boolean | null;
+    /** That terminal's permission mode as its connector read it at the start. */
+    readonly terminalMode: string | null;
+    /** The conversation id the agent runs the session under on the machine. */
+    readonly acp: string | null;
+}
+export declare const NOTHING: RemoteStep;
+/** A step that says only `fields`. */
+export declare function remoteStep(fields?: Partial<RemoteStep>): RemoteStep;
+/** One SSE frame of a remote session to what the runner does. What cannot be read is skipped (usage_update, history_complete
+ * and every type this client does not know are nothing). */
+export declare function decode(event: SseEvent, errors: PublicErrors): RemoteStep;

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

@@ -0,0 +1,7 @@
+/**
+ * Reading one field of an untrusted JSON object (a connector's report, an agent's event, a card's data) the way the Python worker
+ * read its dicts: text is what is there, nothing for a missing, empty, false or zero value.
+ */
+export declare function textOf(value: unknown): string;
+/** An object field as a record, or null for anything else. */
+export declare function recordOf(value: unknown): Readonly<Record<string, unknown>> | null;

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

@@ -0,0 +1,39 @@
+import type { RemoteContext } from "../context.js";
+import type { StatusBoard } from "../board.js";
+import type { ChatState } from "../state.js";
+/** How the follower says a session's end and shows a permission request (the domain's own sentences and cards). */
+export interface FollowHooks {
+    describeEnd(chatKey: string, connectorId: string, reason: string): Promise<string>;
+    showPermission(chatKey: string, sessionId: string, request: Readonly<Record<string, unknown>>, to: import("../../ports/surface.js").Conversation): Promise<void>;
+}
+export declare class FollowControl {
+    private readonly ctx;
+    private readonly state;
+    private readonly board;
+    private readonly hooks;
+    constructor(ctx: RemoteContext, state: ChatState, board: StatusBoard, hooks: FollowHooks);
+    /** An attached chat hears its session between turns: what the session says shows there by itself. */
+    get follows(): boolean;
+    /**
+     * Make sure an attached chat has its reader, unless a turn or a short watch is reading the session. `active`: the agent was seen
+     * at work just now, so `/stop` reaches it before its next event. `steps`, `asks`: the steps still running and the permission
+     * requests still waiting at that moment.
+     */
+    ensure(chatKey: string, active?: boolean, steps?: readonly string[], asks?: readonly string[]): void;
+    /** The chat has left its session (or something else is about to read it): the reader goes, with what it had not said. */
+    drop(chatKey: string): void;
+    /** Stop the reader before a message goes to the agent, with what it has read delivered: true when there was one to stop. */
+    stop(chatKey: string): Promise<boolean>;
+    /** The chat leaves its session. */
+    detach(chatKey: string): void;
+    /** Follow every chat that is attached: a worker that starts delivers what its agents said while it was away, once. */
+    resume(): void;
+    shutdown(): void;
+    /**
+     * TEAMS_DIRECT_CHAT is on for this person: an attachment that still has the session card as its window is moved to the chat,
+     * here and in the store, so nothing reads it as a card any more (the card itself is left where it is).
+     */
+    chatIsWindow(chatKey: string): void;
+    /** The chats of a person: their 1:1 chat and every group chat they bound to a session. */
+    chatsOf(person: string): string[];
+}

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

@@ -0,0 +1,85 @@
+import type { SseEvent } from "../../claw/model.js";
+import type { RemotePermissionRepository } from "../../ports/store/remote.js";
+import { type RemoteStep } from "../events.js";
+import { type RemoteTurnState } from "../turn-state.js";
+import { type SpeakerDeps } from "./speaker.js";
+/**
+ * What the reader reads with could not be had just now (the identity service is down) and there is no other credential: not the
+ * same as having none. The reader waits and asks again; a credential that is null is a person who has none (unlinked), and ends it.
+ */
+export declare class CredentialUnavailable extends Error {
+    readonly name = "CredentialUnavailable";
+}
+export interface FollowerDeps extends SpeakerDeps {
+    readonly permissions: RemotePermissionRepository;
+    /** The session's events after a cursor, live; ends when the stream ends; throws `ClawError` or a transport error. */
+    stream(key: string, sessionId: string, after: string | undefined, signal: AbortSignal): AsyncIterable<SseEvent>;
+    /** What to read with (null: nobody to read for; throws `CredentialUnavailable` when it cannot be had just now). */
+    credential(): Promise<string | null>;
+    newTurn(): RemoteTurnState;
+}
+/** The event says something of the session's permission modes. */
+export declare function saysModes(step: RemoteStep): boolean;
+/** The reader of one attached chat's session, for as long as no turn reads it. */
+export declare class Follower {
+    readonly chatKey: string;
+    readonly sessionId: string;
+    private readonly deps;
+    private readonly speaker;
+    private readonly cancel;
+    private readonly stopped;
+    private flushOnStop;
+    private doneTurn;
+    private readonly active;
+    private readonly asks;
+    private cursor;
+    private handled;
+    private lastEvent;
+    private pauseOverAfter;
+    private inbox;
+    private task;
+    private finished;
+    constructor(chatKey: string, sessionId: string, deps: FollowerDeps);
+    get alive(): boolean;
+    /**
+     * Begin reading. `active`: the agent was at work a moment ago (`busy` says so until `quiet` has passed with no event). `steps`
+     * and `asks`: the steps that had begun and the permission requests nobody had answered when the chat attached: `busy` says so
+     * until their own end (or answer) is read. They do not hold back the text that comes after.
+     */
+    start(active?: boolean, steps?: Iterable<string>, asks?: Iterable<string>): void;
+    /** Stop reading and forget what was waiting: the chat has left the session. */
+    drop(): void;
+    /**
+     * Stop reading, and (`flush`) deliver the text that waits, whoever may be woken: called when the person has just written.
+     * Returns when the reader is gone.
+     */
+    stop(flush?: boolean): Promise<void>;
+    /** The chat left the session: the reader goes, with nothing more said. */
+    private cancelled;
+    /** The person wrote: the reader stops, with what it read delivered. */
+    private stopping;
+    /** The agent is, as far as can be told, working on its own now (what `/stop` should reach). */
+    busy(): boolean;
+    private guarded;
+    private run;
+    /** The credential; undefined when it cannot be had just now. */
+    private readCredential;
+    /** One stream, read until it ends, the reader is stopped, or there is nothing left to read. */
+    private readOnce;
+    /** Wait before reading again, longer for each failure in a row, and no longer than it takes to be stopped. */
+    private wait;
+    /** The session's events into the inbox, so the reader can also wait for the end of a pause. */
+    private pump;
+    /** Events and the ends of pauses, until the stream ends ('again'), the reader is stopped ('stop'), or nothing is left ('done'). */
+    private consume;
+    private failure;
+    private dueContext;
+    /** Fold one event in. False when the reader has nothing more to do. */
+    private handle;
+    private askOrResolve;
+    /** What is said between two stretches of the agent's text: a prompt typed at the terminal, the connector coming back. */
+    private sayBetween;
+    private advance;
+    private flush;
+    private persist;
+}

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

@@ -0,0 +1,16 @@
+import type { Clock } from "../../ports/clock.js";
+/** What `Inbox.next` gives when its wait ran out with nothing in it. */
+export declare const TIMED_OUT: unique symbol;
+/**
+ * A queue one reader waits on, for an item or the end of a pause (`next` with a timeout), whichever comes first. A wait that runs
+ * out never takes an item away: the next `next` gets it.
+ */
+export declare class Inbox<T> {
+    private readonly clock;
+    private readonly items;
+    private wake;
+    constructor(clock: Clock);
+    push(item: T): void;
+    /** The next item, or `TIMED_OUT` after `timeoutMs` (null: wait for an item however long). */
+    next(timeoutMs: number | null): Promise<T | typeof TIMED_OUT>;
+}