@primusclaw/personal-agent 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,20 @@
+import type { Lang } from "../locales/lang.js";
+export interface PermissionOption {
+    readonly optionId: string;
+    readonly name: string;
+    readonly kind: string;
+}
+/** The options an agent offered, as strings and nothing else: an entry without a usable `optionId` is dropped, a repeated id is
+ * kept once, at most twelve. */
+export declare function parseOptions(raw: unknown): PermissionOption[];
+/** What a button says: the agent's own name for the option, clipped; an option that persists (`allow_always`) always says so,
+ * whatever the agent called it. With no name the kind's plain words, else the id. */
+export declare function buttonTitle(option: PermissionOption, lang?: Lang): string;
+/** The options a card shows, in the fixed order, at most OPTION_BUTTONS_MAX. */
+export declare function shownOptions(options: readonly PermissionOption[]): PermissionOption[];
+/** The one primary button is allow once; a rejection is a plain one. */
+export declare function isPrimary(option: PermissionOption): boolean;
+/** Whether choosing one of `options` changes what the agent may do from now on (an always option). */
+export declare function offersAlways(options: readonly PermissionOption[]): boolean;
+/** What an option came to, once chosen ("Allowed once"), or its button's words for a kind with no verdict of its own. */
+export declare function decidedVerdict(option: PermissionOption, lang?: Lang): string;

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

@@ -0,0 +1,41 @@
+import type { Lang } from "../locales/lang.js";
+import { type Conversation, type OutMessage } from "../ports/surface.js";
+import { type PermissionOption } from "./options.js";
+import type { RemoteContext } from "./context.js";
+import type { StatusBoard } from "./board.js";
+import { type ChatState } from "./state.js";
+/** How a click ends: the clicked card replaced by `card` (a note when it is text), and the outcome said (W4's `ClickRoute.settle`). */
+export type Settle = (card: OutMessage | string, options?: {
+    readonly fallback?: string;
+    readonly announce?: boolean;
+}) => Promise<boolean>;
+/** A click on an option of a permission card. */
+export interface Decision {
+    /** Who clicked (their 1:1 chat key). */
+    readonly person: string;
+    readonly key: string;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly settle: Settle;
+}
+/** The one line an answered approval comes to ("已允许一次：Bash", "Allowed once: Bash."). */
+export declare function decidedLine(option: PermissionOption, tool: string, lang: Lang): string;
+export declare class Permissions {
+    private readonly ctx;
+    private readonly state;
+    private readonly board;
+    constructor(ctx: RemoteContext, state: ChatState, board: StatusBoard);
+    /**
+     * One card per request. The row is written BEFORE the card is shown, so the owner and the options are known when it is clicked;
+     * a request the connector sends again after a reconnect finds its row and is not shown twice.
+     */
+    show(chatKey: string, sessionId: string, request: Readonly<Record<string, unknown>>, to: Conversation): Promise<void>;
+    /** The card again with its buttons and `text` on it: the decision did not go through. */
+    private reopened;
+    /** A click on an option of a permission card (see the module). */
+    decide(click: Decision): Promise<void>;
+    /** Past its time a request is refused, whatever the button says. */
+    private ranOut;
+    private answer;
+    /** The decision to Claw; false (and the click answered) when it did not go through. */
+    private send;
+}

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

@@ -0,0 +1,143 @@
+/**
+ * What the remote agents need of their view (core/src/remote-view, which implements it as `createRemoteViews`): the cards they
+ * post, as messages, and the live view of a turn. The domain says what is shown (the inputs here); the view says how. The
+ * assembly gives the domain the view's implementation (`RemoteContext.views`), so the domain never imports the view.
+ */
+import type { Lang } from "../locales/lang.js";
+import type { OutMessage } from "../ports/surface.js";
+import type { ButtonFields, DecisionButton } from "./actions.js";
+import type { Conversation } from "./conversations.js";
+import type { RemoteStep } from "./events.js";
+import type { StatusPhase } from "./lines.js";
+import type { Agent, Connector, Session } from "./model.js";
+import type { PermissionOption } from "./options.js";
+import type { ConnectorSetupWords } from "./setup.js";
+import type { WindowView } from "./window/view.js";
+export interface StatusInput {
+    /** `icon name` of the agent. */
+    readonly label: string;
+    readonly host: string;
+    readonly cwd: string;
+    readonly mode: string | null;
+    readonly sessionId: string;
+    readonly phase: StatusPhase;
+    /** When the phase was last true, seconds since the epoch (shown as UTC, so a phone that did not redraw shows its age). */
+    readonly at: number;
+    readonly lang?: Lang;
+    /** The agent said its modes: Mode is offered. */
+    readonly hasModes?: boolean;
+    readonly unattended?: boolean;
+    readonly lead?: string;
+    /** The title of the conversation the chat joined, "" for none. */
+    readonly conversation?: string;
+    /** What Take over… carries, for a watched conversation the connector can take over; null for none. */
+    readonly takeover?: ButtonFields | null;
+    /** What is sent is typed into a terminal on the machine, so Stop says it interrupts the turn running there. */
+    readonly terminal?: boolean;
+    /** The assistant's display name. */
+    readonly bot: string;
+}
+export interface AgentsInput {
+    readonly connectors: readonly Connector[];
+    readonly sessions: readonly Session[];
+    /** The session the chat is attached to. */
+    readonly attached: string | null;
+    readonly now: number;
+    /** One line on top: what the tap that brought the card back did, or why it did not. */
+    readonly lead?: string;
+    readonly machines?: boolean;
+    readonly lang?: Lang;
+    /** Session id -> (title, the ref of the terminal conversation it joined, "" for none) of the sessions this chat started. */
+    readonly names?: ReadonlyMap<string, {
+        readonly title: string;
+        readonly ref: string;
+    }>;
+    /** Session id -> the machine's conversation id of this chat's own sessions. */
+    readonly own?: ReadonlyMap<string, string>;
+    readonly setup: ConnectorSetupWords;
+}
+export interface SessionsInput {
+    readonly connectors: readonly Connector[];
+    readonly sessions: readonly Session[];
+    readonly attached: string | null;
+    readonly now: number;
+    readonly lang?: Lang;
+    readonly lead?: string;
+    readonly setup: ConnectorSetupWords;
+    /** Session ids with an approval card open. */
+    readonly waiting?: ReadonlySet<string>;
+}
+/** One approval the session waits on: the tool, when it runs out, and the agent's own options as buttons. */
+export interface WindowApproval {
+    readonly actionId: string;
+    readonly tool: string;
+    readonly expiresAt: number;
+    readonly buttons: readonly DecisionButton[];
+}
+export interface WindowInput {
+    /** `icon name` of the agent. */
+    readonly label: string;
+    readonly host: string;
+    readonly cwd: string;
+    readonly mode: string | null;
+    readonly sessionId: string;
+    readonly phase: StatusPhase;
+    readonly at: number;
+    readonly lang: Lang;
+    readonly view: WindowView;
+    readonly approvals: readonly WindowApproval[];
+    /** The person's time zone (an IANA name). */
+    readonly zone?: string;
+    readonly unattended?: boolean;
+    readonly lead?: string;
+    readonly conversation?: string;
+    readonly hasModes?: boolean;
+    readonly takeover?: ButtonFields | null;
+    /** A group chat bound to the session: its approvals go to the binder's 1:1 chat, never here. */
+    readonly group?: boolean;
+    readonly terminal?: boolean;
+    /** The assistant's display name. */
+    readonly bot: string;
+}
+export interface PermissionCard {
+    readonly request: Readonly<Record<string, unknown>>;
+    readonly options: readonly PermissionOption[];
+    readonly sessionId: string;
+    readonly who: string;
+    readonly expiresAt: number;
+    readonly zone: string;
+    readonly lang: Lang;
+}
+/** A card that lists sessions, and the session ids it numbers. */
+export interface ListedMessage {
+    readonly message: OutMessage;
+    readonly listing: readonly string[];
+}
+/** The live view of a remote turn in a chat (`RemoteLiveView`): what the turn's status message shows as it goes. */
+export interface RemoteLive {
+    readonly header: string;
+    /** True when the step changed what is shown. */
+    apply(step: RemoteStep): boolean;
+    render(): string;
+    statusLines(): string[];
+}
+/** The remote agents' cards, as messages to post. */
+export interface RemoteViews {
+    status(input: StatusInput): OutMessage;
+    window(input: WindowInput): {
+        readonly message: OutMessage;
+        readonly takesInput: boolean;
+    };
+    agents(input: AgentsInput): ListedMessage;
+    sessions(input: SessionsInput): ListedMessage;
+    machineChoice(connector: Connector, agents: readonly Agent[], token: string, path: string, lang: Lang): OutMessage;
+    mode(sessionId: string, current: string | null, modes: readonly string[], unattended: ReadonlySet<string>, lang: Lang): OutMessage;
+    disconnect(host: string, connectorId: string, setup: ConnectorSetupWords, lang: Lang, paired: boolean): OutMessage;
+    permission(card: PermissionCard): OutMessage;
+    decided(option: PermissionOption, when: number, zone: string, lang: Lang): OutMessage;
+    takeover(connector: Connector, agent: Agent, entry: Conversation, lang: Lang, view: string, ticket: string): OutMessage;
+    hidden(connector: Connector, now: number, lang: Lang): OutMessage;
+    /** A permission request's buttons (the ones its card shows). */
+    optionButtons(options: readonly PermissionOption[], sessionId: string, actionId: string, lang: Lang): DecisionButton[];
+    liveView(label: string, lang: Lang): RemoteLive;
+}

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

@@ -0,0 +1,60 @@
+import { type Conversation } from "../ports/surface.js";
+import type { StatusBoard } from "./board.js";
+import type { RemoteTurn } from "./chats.js";
+import type { RemoteContext } from "./context.js";
+import type { Provider } from "./ended.js";
+import type { FollowControl } from "./follow/control.js";
+import type { SessionStarts } from "./sessions.js";
+import { type ChatState } from "./state.js";
+import type { TurnRunner } from "./turns/runner.js";
+import type { Watches } from "./watches.js";
+import type { SentFrom } from "./window/view.js";
+/** One message for the agent. */
+export interface Prompt {
+    readonly chatKey: string;
+    readonly key: string;
+    readonly to: Conversation;
+    readonly provider: Provider;
+    readonly text: string;
+    /** The channel's id of the message (one key per message: a redelivered one queues one prompt). */
+    readonly messageId: string;
+    /** Where it was typed (`card`: the session card's box); '' works it out (a reply quoting the card, or the chat box). */
+    readonly source: SentFrom;
+    /** The message replies quoting this chat's session card. */
+    readonly quotesWindow: boolean;
+}
+export declare class Prompts {
+    private readonly ctx;
+    private readonly state;
+    private readonly board;
+    private readonly follow;
+    private readonly starts;
+    private readonly runner;
+    private readonly watches;
+    constructor(ctx: RemoteContext, state: ChatState, board: StatusBoard, follow: FollowControl, starts: SessionStarts, runner: TurnRunner, watches: Watches);
+    private say;
+    /** Plain text from a chat that is attached: it is the agent's, not the assistant's. */
+    prompt(p: Prompt): Promise<void>;
+    /** The terminal is using the session: what is typed here is answered, never sent. */
+    private watched;
+    /** The prompt to Claw; false (and the person told why) when it did not go. */
+    private send;
+    private failure;
+    private started;
+    /**
+     * Move the read position to the end of the session's events, so a turn reads its own and nothing the agent wrote before. Null
+     * when it was moved; otherwise the sentence for the person (the end could not be read, or the session is gone: the chat leaves it).
+     */
+    private skipBacklog;
+    /**
+     * `/stop` for a chat that is attached: the agent is told to cancel. False when the chat is not attached. `only`: cancel only while
+     * that turn is the one this worker watches, checked with no wait before the cancel goes (a Stop card's turn); false, with nothing
+     * said or sent, when it is not.
+     */
+    stop(chatKey: string, key: string, to: Conversation, only?: RemoteTurn): Promise<boolean>;
+    /** The Stop card's turn is still the one running for the chat, and the chat is still attached. */
+    private stillOn;
+    private cancel;
+    /** A turn nobody reads any more is not open: what the agent says from here on is the follower's. */
+    private closeTurn;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * What a refusal from Claw's remote-agents API means for a person, in the chat's language. The refusals that have a sentence of
+ * their own are a closed set, by (status, `error` code), then by status alone; a 400 names its code when that is a plain word
+ * that names no service, else a reference to the log line that keeps it.
+ */
+import { ClawError } from "../claw/errors.js";
+import type { Lang } from "../locales/lang.js";
+import type { PublicErrors } from "../public-error/public-errors.js";
+import { type RemoteSentence } from "../locales/remote-agents.js";
+import type { Connector } from "./model.js";
+/**
+ * How a detail that may be internal is kept from a person (`public-error`): whether text looks internal, and logging it under
+ * a new reference that the person is given instead.
+ */
+export interface RefusalErrors extends Pick<PublicErrors, "withhold"> {
+    looksInternal(text: string): boolean;
+}
+/** A new session refused as offline twice while the machine was reconnecting: said as that, never as "restart it". */
+export declare class Reconnecting extends ClawError {
+    readonly connector: Connector;
+    readonly name: string;
+    constructor(connector: Connector);
+}
+/** Claw's refusals that have a sentence of their own, by "status error" (`failureText`). */
+export declare const REFUSALS: ReadonlyMap<string, RemoteSentence>;
+/** ... and by status alone. */
+export declare const STATUS_REFUSALS: ReadonlyMap<number, RemoteSentence>;
+/** A fixed sentence of remote agents in `lang`. */
+export declare function saidIn(lang: Lang, sentence: RemoteSentence): string;
+/** What a refusal from Claw's remote-agents API means for a person, in `lang`. `now`: wall-clock seconds. */
+export declare function failureText(err: ClawError, errors: RefusalErrors, now: number, lang?: Lang): string;
+/** `base` as a sentence, with the reason an agent or a connector gave when there is one. */
+export declare function withReason(base: string, reason: string | null | undefined): string;
+/** What makes one key per inbound message: a hash of the text (hex), and fresh randomness for a message that has no id. */
+export interface KeyMaker {
+    sha1Hex(text: string): string;
+    hexId(): string;
+}
+/** One key per inbound message, so a redelivered message queues one prompt (Claw accepts `[A-Za-z0-9._:-]{1,64}`). */
+export declare function idempotencyKey(keys: KeyMaker, userId: string, activityId: string): string;

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

@@ -0,0 +1,84 @@
+/**
+ * Remote agents from the chat: the coding agents on a person's own machines, driven from the chat. `/agents` lists them,
+ * `/agent new|attach|detach|mode|sessions|close|off|pair` manages sessions, and once a chat is attached its plain messages go to
+ * the remote session instead of to the assistant. Claw's remote-agents API relays everything; this is the chat's side of it.
+ *
+ * Everything runs as the person who wrote: their credential, and nobody else's, is what every call carries, and Claw answers 404
+ * for a session or connector that is not theirs. Cards are not trusted: a click is checked against what this process stored when
+ * it showed the card, never against the card. The agent's own words are untrusted text. This is the router's `RemoteChat` and the
+ * click handler of the remote-agent cards; the parts are assembled here and nowhere else.
+ */
+import type { JsonObject } from "../json.js";
+import type { Lang } from "../locales/lang.js";
+import type { ClickHandler } from "../ports/routing.js";
+import type { Conversation, InboundMessage, UserRef } from "../ports/surface.js";
+import type { Attachment, RemoteAgentCommand, RemoteChat, RemotePrompt } from "../routing/features.js";
+import { type RemoteTurn } from "./chats.js";
+import type { RemoteContext } from "./context.js";
+/** How long the assistant's context waits for a session's watch marker to be read back. */
+export declare const CHAT_CONTEXT_WATCH_SECONDS = 2;
+export declare class RemoteAgents implements RemoteChat {
+    private readonly chats;
+    private readonly state;
+    private readonly board;
+    private readonly follow;
+    private readonly commands;
+    private readonly clicks;
+    private readonly starts;
+    private readonly machine;
+    private readonly permissions;
+    private readonly prompts;
+    private readonly runner;
+    private readonly ctx;
+    constructor(context: RemoteContext);
+    /** What reads Claw for a chat with nobody to ask (its binder's credential for a group binding). */
+    private readKey;
+    /** How a turn is shown: in the session card when it is the window, else in the chat. */
+    private display;
+    get enabled(): boolean;
+    /** An attached chat hears its session between turns. */
+    get follows(): boolean;
+    attached(chatKey: string): boolean;
+    running(chatKey: string): boolean;
+    direct(chatKey: string): boolean;
+    /** Where the chat box of an attached chat goes: 'card' (to the assistant) or 'chat' (to the session). */
+    windowMode(chatKey: string): "card" | "chat";
+    quotesWindow(chatKey: string, message: InboundMessage): boolean;
+    /** What help says this chat is attached to (agent.py's help lead): each part made safe to show. */
+    attachment(chatKey: string, lang: Lang): Attachment | undefined;
+    groupChatKey(userId: string, scope: string): string;
+    /**
+     * The session this chat is attached to, as its assistant is told it beside a message. The watch marker is read back the first
+     * time this process is asked, but never holds the message up longer than CHAT_CONTEXT_WATCH_SECONDS.
+     */
+    chatContext(chatKey: string, credential: string): Promise<JsonObject | null>;
+    private call;
+    prompt(request: RemotePrompt): Promise<void>;
+    /** `only`: a Stop card's turn; the press stops nothing once that turn is not the one running (see Prompts.stop). */
+    stop(chat: UserRef, credential: string, conversation: Conversation, only?: RemoteTurn): Promise<boolean>;
+    /** The turn this worker is watching for the chat now, if any (what a phone's Stop card is sent for). */
+    currentTurn(chatKey: string): RemoteTurn | undefined;
+    /** The chat's session card is its window (`/agent mode card`, not a direct chat): a turn is shown there, with its own Stop. */
+    windowed(chatKey: string): boolean;
+    agents(sender: UserRef, credential: string, conversation: Conversation): Promise<void>;
+    agent(command: RemoteAgentCommand): Promise<void>;
+    /** Stop watching for a chat whose person unlinked: no reader may outlive the key it reads with. */
+    forget(chatKey: string): void;
+    /** `forget` for the person's 1:1 chat and every group chat they bound to a session. */
+    forgetPerson(userId: 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;
+    /** The chats a turn or a short watch is reading now. */
+    busyChats(): string[];
+    /** Every turn and short watch is cancelled: nothing outlives the process (or the test) that started it. */
+    cancelAll(): void;
+    /** The click handler of the remote-agent cards: the agents and sessions cards, the status card, approvals, disconnect. */
+    get clickHandler(): ClickHandler;
+    private onClick;
+    /** A click on an option of a permission card (on the session card, the window stays the card). */
+    private decide;
+    /** A tap on a button of the agents card or of the status card. */
+    private tap;
+    private runOp;
+}

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

@@ -0,0 +1,8 @@
+/** One entry of a connector's report (a conversation, a health problem, a permission option). */
+export type Reported = Readonly<Record<string, unknown>>;
+/** `value` when it is a JSON object, else null. */
+export declare function objOrNull(value: unknown): Reported | null;
+/** The list `value` is, or []. */
+export declare function list(value: unknown): readonly unknown[];
+/** `value` when it is a string, else "". */
+export declare function str(value: unknown): string;

package/dist/types/remote/session-ops.d.ts

@@ -0,0 +1,57 @@
+import type { Lang } from "../locales/lang.js";
+import type { RemoteState } from "../ports/store/remote.js";
+import type { Conversation } from "../ports/surface.js";
+import type { StatusPhase } from "./lines.js";
+import type { Shown, StatusBoard } from "./board.js";
+import type { RemoteContext } from "./context.js";
+import type { Provider } from "./ended.js";
+import type { AttachHooks } from "./sessions.js";
+import type { FollowControl } from "./follow/control.js";
+import { type Lists } from "./lists.js";
+import { type Agent } from "./model.js";
+import { type ChatState } from "./state.js";
+import type { TurnRunner } from "./turns/runner.js";
+export declare class SessionOps {
+    private readonly ctx;
+    private readonly state;
+    private readonly board;
+    private readonly lists;
+    private readonly follow;
+    private readonly runner;
+    private readonly show;
+    constructor(ctx: RemoteContext, state: ChatState, board: StatusBoard, lists: Lists, follow: FollowControl, runner: TurnRunner, show: (chatKey: string, sid: string, request: Readonly<Record<string, unknown>>, to: Conversation) => Promise<void>);
+    /**
+     * What follows an attachment once it is shown. Output after the last `turn_end` is a turn only when this chat sent a prompt that
+     * has not ended (the connector never ends what the agent goes on with by itself): that output is the follower's. A permission
+     * nobody answered gets its card.
+     */
+    attachHooks(chatKey: string, key: string, provider: Provider, to: Conversation): AttachHooks;
+    /**
+     * Back to the assistant while a turn of this chat's runs (or its message waits for the terminal): the chat stops reading it and
+     * nothing is sent to the machine, so a turn running in a terminal goes on there untouched (Stop is what interrupts). A message
+     * still waiting for the terminal is taken back where the connector can do that without stopping anything. The sentence for the
+     * person ('' when no turn of theirs was running).
+     */
+    letGoOfTurn(chatKey: string, key: string, state: RemoteState): Promise<string>;
+    /** Take back the messages that wait for the session's terminal, where its connector says it can. False when it cannot or did not. */
+    private withdraw;
+    /** The chat leaves its session for good (its machine went): nothing reads it any more. */
+    leave(chatKey: string): void;
+    /** The agent (as its machine reports it now) a chat is attached to; null when it cannot be read: what depends on it is not shown. */
+    agentOf(key: string, state: RemoteState): Promise<Agent | null>;
+    /**
+     * The chat's status card, with a note when the session runs without asking for approval (what the agent's machine reports about
+     * its mode, while the session itself has not said).
+     */
+    rowCard(chatKey: string, key: string, state: RemoteState, lead?: string, agent?: Agent, phase?: StatusPhase): Promise<Shown>;
+    /** Why `mode` cannot be asked for on this session, or null when it may be. */
+    modeRefusal(chatKey: string, state: RemoteState, mode: string, lang: Lang): string | null;
+    /**
+     * Close session `target` (one of the person's): whether it was, and the sentence (`folder` is named in it when known, and
+     * `number`, the number the list showed it under). The session this chat is attached to is left behind with it.
+     */
+    close(chatKey: string, key: string, target: string, folder?: string, number?: number): Promise<{
+        done: boolean;
+        text: string;
+    }>;
+}

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

@@ -0,0 +1,80 @@
+import type { RemoteContext } from "./context.js";
+import type { FollowControl } from "./follow/control.js";
+import type { Lists } from "./lists.js";
+import { type Agent, type Connector, type Session } from "./model.js";
+import type { ChatState } from "./state.js";
+import { type SessionTail } from "./tail.js";
+/** A new session refused as offline while its machine was reconnecting is asked for once more after this. */
+export declare const RECONNECT_RETRY_SECONDS = 10;
+/** What a new session is: where, and the conversation it takes over (or watches), when one. */
+export interface NewSession {
+    readonly connector: Connector;
+    readonly agent: Agent;
+    readonly path: string;
+    readonly resumeRef?: string | undefined;
+    /** The person confirmed that the terminal that has the conversation open is ended first. */
+    readonly takeover?: boolean;
+    /** The conversation's title, which the status card names. */
+    readonly conversation?: string;
+    /** The count a start in a mode that does not ask took, given back when no session is made. */
+    readonly ticket: object | null;
+}
+/** What attaching came to: whether it did, the sentence (why not), what to do once it is shown, and what the card says. */
+export interface Attached {
+    readonly ok: boolean;
+    readonly text: string;
+    followUp(): Promise<void>;
+    readonly phase: "idle" | "working" | "watching" | "offline";
+    readonly lead: string;
+}
+export declare class SessionStarts {
+    private readonly ctx;
+    private readonly state;
+    private readonly lists;
+    private readonly follow;
+    constructor(ctx: RemoteContext, state: ChatState, lists: Lists, follow: FollowControl);
+    /** Where the chat box goes when a chat attaches: the person's `/agent mode`, else the default; always the chat in a direct chat. */
+    newWindow(chatKey: string): string;
+    /**
+     * A new session of an agent configured to start in a mode that does not ask is that mode from its first message: it counts
+     * against the same per-person limit as a switch to one. The ticket of the count (null: none taken), or the refusal.
+     */
+    takeUnattendedStart(chatKey: string, agent: Agent): {
+        ticket: object | null;
+        refusal: string;
+    };
+    /** The label a session of `agent` is shown with: its icon and name. */
+    static labelOf(agent: Agent): string;
+    /**
+     * Start a session and attach the chat to it: the session id. The caller tells the person, then starts the watch for the agent's
+     * first word. The count `ticket` is given back when no session is made.
+     */
+    begin(chatKey: string, key: string, start: NewSession): Promise<string>;
+    /** The chat leaves what it was reading: a short watch, the follower; and it may be followed again. */
+    private leaveCurrent;
+    /**
+     * Ask Claw for the session. Refused as offline while the machine is reconnecting (heard from moments ago), it is asked for once
+     * more a little later; refused again, the refusal says it is reconnecting, never to restart a connector coming back by itself.
+     */
+    private create;
+    /** Where a session's events end now (`tail.ts`). */
+    tail(key: string, sessionId: string): Promise<SessionTail>;
+    /**
+     * Attach the chat to one of the person's sessions: nothing is replayed, the agent's own session is brought back. The caller
+     * shows `text` (why not), then runs `followUp` (a turn that is open is shown, a permission nobody answered gets its card).
+     */
+    attach(chatKey: string, key: string, session: Session, hooks: AttachHooks): Promise<Attached>;
+    /** The attachment in the store, and what this process knows of it. */
+    private remember;
+    /** Bring the agent's own session back (it keeps its context; nothing is replayed). */
+    private resume;
+}
+/** What the caller does once an attachment is shown: show a turn that is open, the permissions nobody answered, follow it. */
+export interface AttachHooks {
+    followUp(found: {
+        readonly sessionId: string;
+        readonly tail: SessionTail;
+        readonly working: boolean;
+        readonly sent: boolean;
+    }): Promise<void>;
+}

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

@@ -0,0 +1,26 @@
+import type { Lang } from "../locales/lang.js";
+import type { Connector } from "./model.js";
+/** The connect steps for a card: the first line (the lead, or "You have no machine connected.", then what to run), each command
+ * on a line of its own, what to do after, and the per-system notes (one line each, joined by newlines). */
+export interface ConnectSteps {
+    readonly lead: string;
+    readonly commands: readonly string[];
+    readonly after: string;
+    readonly notes: string;
+}
+/**
+ * What the remote-agent views say about connecting a machine and upgrading its connector: the exact commands a person copies
+ * (the connector-setup module of the remote-agent domain provides it, from what Claw says or the address Claw is reached at).
+ */
+export interface ConnectorSetupWords {
+    /** The connect steps as markdown for a rich message: the commands in one code block a person copies whole. */
+    connectMarkdown(lang: Lang): string;
+    /** The same for a card; `lead` replaces the first sentence. */
+    connectSteps(lang: Lang, lead?: string): ConnectSteps;
+    /** One line under a machine whose connector Claw says is old, with the command that upgrades it; null otherwise. */
+    versionNote(connector: Connector, lang: Lang): string | null;
+    /** What brings an offline machine back. */
+    offlineHint(lang: Lang): string;
+    /** The exact `claw-connector login` command. */
+    login(): string;
+}

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

@@ -0,0 +1,55 @@
+import type { Lang } from "../locales/lang.js";
+import type { RemotePermission, RemoteState } from "../ports/store/remote.js";
+import type { ChatRegistry } from "./chats.js";
+import type { RemoteContext } from "./context.js";
+import { WindowView } from "./window/view.js";
+/** What a chat's session is doing, as its status card says it. */
+export type ChatPhase = "detached" | "watching" | "working" | "idle";
+export declare class ChatState {
+    private readonly ctx;
+    readonly chats: ChatRegistry;
+    /** What each chat's session card shows of its session's output, in this process. */
+    private readonly views;
+    constructor(ctx: RemoteContext, chats: ChatRegistry);
+    attached(chatKey: string): RemoteState | null;
+    /** The language the chat is answered in ("en" when it cannot be read). */
+    lang(chatKey: string): Lang;
+    /** TEAMS_DIRECT_CHAT is on for this 1:1 chat's person (a group binding keeps its session card). */
+    directOn(chatKey: string): boolean;
+    /** The chat is the agent's window itself, with no card. */
+    direct(chatKey: string): boolean;
+    /** The chat's session only watches a conversation open in a terminal (read-only). */
+    watches(chatKey: string, state: RemoteState | null): boolean;
+    typesIntoTerminal(chatKey: string, state: RemoteState | null): boolean;
+    /**
+     * `watches`, with the marker read back from the session itself the first time this process is asked (a worker that restarted
+     * knows its chats' sessions, not which of them only watch): the newest `session_started`/`session_resumed` among its first events
+     * says. When that cannot be read the marker as it is answers.
+     */
+    knownWatch(chatKey: string, key: string, state: RemoteState): Promise<boolean>;
+    /** The watched session has ended (the terminal let the conversation go). False when it is on, or cannot be read now. */
+    watchOver(key: string, state: RemoteState): Promise<boolean>;
+    /** The watching status card offers Take over…: the ref is known, and the connector can take it over (or is not known not to). */
+    offersTakeover(chatKey: string): boolean;
+    phase(chatKey: string): ChatPhase;
+    /** The chat's window view, reset to its session's. */
+    view(chatKey: string, state?: RemoteState | null): WindowView;
+    /** The view when the chat has one, without making one. */
+    existingView(chatKey: string): WindowView | undefined;
+    forgetView(chatKey: string): void;
+    /** The approvals the chat's session waits for, as the window shows them (none in a group: those go to the binder's 1:1). */
+    approvalsOf(chatKey: string, state: RemoteState): RemotePermission[];
+    /** The person's time zone (IANA), the default when theirs is not one. */
+    zone(chatKey: string): string;
+}
+/** The zone the worker falls back to (the store's DEFAULT_TIMEZONE). */
+export declare const DEFAULT_ZONE = "Asia/Shanghai";
+/** `zone` when it is a time zone this runtime knows, else the default. */
+export declare function validZone(zone: string): string;
+/** Claw was not reached, or did not answer in time (the transport's own failure, never a refusal). */
+export declare function isTransport(error: unknown): boolean;
+/**
+ * What the session said of `mode` (`true`: it does not ask, `false`: it asks), or undefined when it said nothing. Its own keys only:
+ * a mode called `constructor` or `__proto__` is no flag (Python's `dict.get`).
+ */
+export declare function modeFlagOf(flags: Readonly<Record<string, boolean>>, mode: string): boolean | undefined;