@primusclaw/personal-agent 0.0.0-stage → 0.1.0

package/dist/types/capabilities/natural.d.ts

@@ -0,0 +1,19 @@
+import { sessionControl, switchCommand } from "./sessions-words.js";
+import { clockOf } from "./spoken.js";
+export { clockOf, sessionControl, switchCommand };
+/** `key` (a whole message as `phraseKey` makes it) without the words people put around a detach, from either end, repeatedly. */
+export declare function detachKey(key: string): string;
+/**
+ * Every pattern a command said in plain words is read with, by family. No two `\s*` meet across an optional part in any
+ * of them (a run of spaces could then be split between them in every way before a match fails: polynomial time), which
+ * the ReDoS tests check by running each over adversarial input.
+ */
+export declare const NATURAL_PATTERNS: readonly (readonly [string, readonly RegExp[]])[];
+/**
+ * `text` as the command it means when it is one of the plain sentences help teaches (or a close way of saying it), else `text`
+ * itself. Only the whole message counts. `group`: a group chat reads only what a group may do (help, stop, a new session, which
+ * account, feedback). `off`: what this chat cannot do right now, as a command word (`board` without the assistant, `github` without
+ * the review service, `agents` and `agent` with remote agents off) or a command and its verb (`agent detach` with no agent
+ * attached): a sentence that would mean one of them stays the words it is, for Claw.
+ */
+export declare function naturalCommand(text: string, group?: boolean, off?: ReadonlySet<string>): string;

package/dist/types/capabilities/phrases.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The plain sentences help teaches, and close ways of saying the same, each read as the command it means (`natural.ts`). A whole
+ * message is looked up as a phrase: lower case, no spaces between the words, no punctuation at either end (`phraseKey`).
+ */
+export declare const HELP: string[];
+export declare const STOP: string[];
+/**
+ * "Stop it" said to a chat attached to an agent's session: that agent's turn is stopped (`/stop`). With the assistant the same words
+ * are the assistant's to read, so they are a command only while attached (`naturalCommand`'s `off` carries "stop it" otherwise).
+ */
+export declare const STOP_IT: string[];
+export declare const NEW: string[];
+export declare const SESSIONS: string[];
+export declare const BOARD: string[];
+export declare const WHOAMI: string[];
+export declare const MEMORY: string[];
+export declare const MEMORY_ON: string[];
+export declare const MEMORY_OFF: string[];
+export declare const UNLINK: string[];
+export declare const AGENTS: string[];
+export declare const AGENT_SESSIONS: string[];
+export declare const DETACH: string[];
+/**
+ * What people put around "回到助理" without changing what it asks (好了，回到助理吧 / ok, back to the assistant please): dropped from
+ * either end before the phrase is looked up. Only these words: "回到助理然后跑测试" is not a detach.
+ */
+export declare const DETACH_LEAD: string[];
+export declare const DETACH_TAIL: string[];
+export declare const RESUME: string[];
+export declare const QUIET_SHOW: string[];
+export declare const QUIET_OFF: string[];
+export declare const BRIEF_OFF: string[];
+export declare const BRIEF_NOW: string[];
+export declare const PAUSE_ALL: string[];
+export declare const GITHUB_BIND: string[];
+export declare const GITHUB_UNBIND: string[];
+export declare const GITHUB_STATUS: string[];
+export declare const DELEGATION_ON: string[];
+export declare const DELEGATION_OFF: string[];
+export declare const TIMEZONE_SHOW: string[];
+export declare const LANG_AUTO: string[];
+export declare const FEEDBACK_ALONE: string[];

package/dist/types/capabilities/registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What the bot can do for a person, as one registry; help is rendered from it (`help.ts`).
+ *
+ * Help teaches what can be got done, grouped by what it is for, each with one sentence a person would really type on a phone; it
+ * does not list commands. The slash commands keep working, and the commands menu has the common ones, which help says once at the
+ * end. `test/capabilities.test.ts` walks the code's closed sets and fails when one is not covered by an entry here, and sends every
+ * example sentence through the real routing to check it reaches the capability it is the example of.
+ */
+import type { Capability } from "./capability.js";
+export { CATEGORIES, type Capability, type CapabilityMode, type Category, type CategoryKey, type Part, type Where, } from "./capability.js";
+export declare const CAPABILITIES: readonly Capability[];
+export declare function byKey(key: string): Capability;

package/dist/types/capabilities/sessions-words.d.ts

@@ -0,0 +1,9 @@
+/** Whether the whole message asks to switch the chat to another agent session or to open a new one. */
+export declare function sessionControl(text: string): boolean;
+/** The session-control and switch patterns, for the ReDoS tests (see natural.ts NATURAL_PATTERNS). */
+export declare const SESSION_PATTERNS: readonly (readonly [string, readonly RegExp[]])[];
+/**
+ * `/agent attach MACHINE/AGENT` (or `/agent attach AGENT`) when the whole message asks to switch the chat to an agent's session, as
+ * people say it ("切到 robin-dev-pod 的 claude", "switch to claude on robin-dev-pod"); else null.
+ */
+export declare function switchCommand(text: string): string | null;

package/dist/types/capabilities/spoken.d.ts

@@ -0,0 +1,19 @@
+/** The punctuation and spacing a whole message may carry at either end without changing what it says. */
+export declare const PUNCT = " \t\r\n\u3002\uFF0E.\uFF01!\uFF1F?\uFF5E~\uFF0C,\u3001\uFF1B;\uFF1A:\"'\u201C\u201D\u2018\u2019\uFF08\uFF09()";
+/** What a sentence may end with ("切到 X 的 claude。"): dropped before it is matched whole. */
+export declare const TRAILING = "\u3002.\uFF01!\uFF1F?\uFF5E~ ";
+/** One or two digits, or a Chinese number up to 99. */
+export declare const NUM: string;
+export declare const PERIOD: string;
+/** A time of day: "22:00", "晚上 10 点", "8 点半", "九点十五分". No capturing groups: it is used inside other patterns. */
+export declare const TIME: string;
+/** A whole message as a phrase to look up: lower case, no spaces between the words, no punctuation at either end. */
+export declare function phraseKey(text: string): string;
+/** A whole message as it is matched against a sentence pattern: no spacing at either end, no closing punctuation. */
+export declare function flatten(text: string): string;
+/** A number as written ("12", "十二", "两"); null when it is none. */
+export declare function spokenNumber(text: string): number | null;
+/** '晚上 10 点' / '早上 8 点半' / '22:00' / '九点' as '22:00' / '08:30' / '22:00' / '09:00'; null when it is no time of day. */
+export declare function clockOf(text: string): string | null;
+/** A duration as `/pause` takes it ("30m", "2h", "1d") from a number and a unit as said; null when it is none. */
+export declare function spokenDuration(count: string, unit: string): string | null;

package/dist/types/capabilities/visibility.d.ts

@@ -0,0 +1,32 @@
+import { type Capability, type Part } from "./registry.js";
+export interface ChatShape {
+    readonly group: boolean;
+    readonly assistant: boolean;
+    readonly parts: ReadonlySet<Part>;
+    readonly understanding?: boolean;
+}
+/** Whether help shows `c` in this chat: a group shows what works in a group, a 1:1 chat what works there. */
+export declare function shown(c: Capability, chat: ChatShape): boolean;
+/**
+ * What the assistant may never ask a chat to do, whatever a message says: what cannot be undone (/unlink, /github unbind), what binds
+ * an account (/link, /github bind), and what loosens a safety setting (/github auto-merge, the confirmation setting).
+ */
+export declare const NOT_ACTIONS: ReadonlySet<string>;
+/**
+ * `agent` is declared only with these verbs: switching the chat to a session, back, and the list. Starting, closing, a mode that does
+ * not ask and disconnecting a machine are the person's own taps.
+ */
+export declare const AGENT_ACTION_VERBS: readonly ["attach", "detach", "sessions"];
+export declare const AGENT_ACTION_USAGE: string;
+/** The arguments of an `agent` action the assistant asked for are one of AGENT_ACTION_VERBS, with at most one reference. */
+export declare function agentActionAllowed(args: string): boolean;
+export interface ChannelAction {
+    readonly name: string;
+    readonly usage: string;
+    readonly summary: string;
+}
+/**
+ * The actions a 1:1 chat with the assistant declares: the capabilities marked `action` that this chat shows, as the command the
+ * assistant may ask for, how it is written, and what it is for. `agent` is declared once, with one usage line for its verbs.
+ */
+export declare function channelActions(parts: ReadonlySet<Part>): ChannelAction[];

package/dist/types/claw/credential.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What a Claw call is made with: a person's own linked API key (`ak-...`) or an identity token the identity service
+ * exchanged for them. The credential is a per-call argument and never kept on the client, so no code path can reach Claw
+ * with a credential other than the one its caller names.
+ */
+export type ClawCredential = string;
+/** Whether `credential` is a person's linked API key rather than an exchanged identity token. */
+export declare function isApiKey(credential: ClawCredential): boolean;

package/dist/types/claw/errors.d.ts

@@ -0,0 +1,61 @@
+/** Whether `code` is a plain snake_case error word ("connector_outdated"), safe to put in front of a person or in a log. */
+export declare function isErrorWord(code: string): boolean;
+/** The `error` word of Claw's `{"ok": false, "error": "..."}` answer in `detail` ("" when the body is not that). */
+export declare function errorCodeOf(detail: string): string;
+/**
+ * Claw refused or failed a call. `detail` keeps the start of the answer's body so that `code` can read Claw's error word,
+ * but the error's message is only the status and that word: a body can echo what the request carried.
+ */
+export declare class ClawError extends Error {
+    readonly name: string;
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, detail?: string);
+    /** The `error` word of Claw's answer ("" when the body is not that). */
+    get code(): string;
+}
+/** The answer Claw gives for an id that is not the caller's; also what an id that is not a Claw id is refused as. */
+export declare function notAClawId(): ClawError;
+/**
+ * Claw refused a request for reviews as a whole (it starts all of them or none): its `error` word, its sentence for a
+ * person (`said`) and its `data` (which pull request, the limit, what remains).
+ */
+export declare class ReviewsRefused extends ClawError {
+    readonly name: string;
+    readonly error: string;
+    readonly said: string;
+    readonly data: Readonly<Record<string, unknown>>;
+    constructor(status: number, error: string, said: string, data: Readonly<Record<string, unknown>>);
+}
+/** A reply this process will not hold: larger than the caller allows, or content-encoded. */
+export declare class ReplayRefused extends Error {
+    readonly name: string;
+}
+/** Claw answered with something this client does not understand (not a list, an item without an id, ...). */
+export declare class ClawAnswerInvalid extends Error {
+    readonly name: string;
+}
+/**
+ * A call that would send the wrong kind of credential, refused before anything goes out: an `ak-` API key where only an
+ * exchanged identity token may go, or a model key next to an API key.
+ */
+export declare class CredentialMisuse extends Error {
+    readonly name: string;
+}
+/**
+ * How a call failed to reach Claw: `connect`, the request never went out (no connection could be made: refused, no such
+ * host, unreachable; Python's `httpx.ConnectError`); `timeout`, Claw did not answer in time; `network`, the connection
+ * broke after the request was sent.
+ */
+export type UnreachableKind = "connect" | "timeout" | "network";
+/** Claw was not reached, or did not answer in time. `kind` says which; the cause's text is never kept. */
+export declare class ClawUnreachable extends Error {
+    readonly name: string;
+    readonly kind: UnreachableKind;
+    constructor(kind: UnreachableKind, what: string);
+}
+/**
+ * What a log line says about a failed call: Claw's status (and error word), or only the kind of error. Never the text of
+ * another library's error, which can carry a URL, a header or the body of an answer.
+ */
+export declare function errorKind(err: unknown): string;

package/dist/types/claw/lenient.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Field readers for Claw's answers, which this agent reads the way the Python worker did: a field that is absent, or of
+ * another type than expected, is read as absent (`undefined`) and the reading fills in its own default. The answer as a
+ * whole is still checked (an object where an object is expected), by the caller's schema.
+ */
+import { z } from "zod";
+/** A value `schema` accepts, else `undefined`: a field Claw sent wrong is read as one it did not send. */
+export declare function lenient<T extends z.ZodType>(schema: T): z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<Awaited<z.output<T>> | undefined, unknown>>>;
+/** Any string. */
+export declare const anyText: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+/** A string that is not empty (Python's `isinstance(v, str) and v`). */
+export declare const someText: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+/** A whole number (Python's `isinstance(v, int) and not isinstance(v, bool)`). */
+export declare const wholeNumber: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | undefined, unknown>>>;
+export declare const flag: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<boolean | undefined, unknown>>>;
+/** A JSON object (not an array). */
+export declare const objectOf: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<Record<string, unknown> | undefined, unknown>>>;
+/** Whatever was there, unread. */
+export declare const anything: z.ZodOptional<z.ZodUnknown>;
+/** Rows of a list: the ones `schema` accepts (rows that are not objects are left out). */
+export declare function rowsOf<T extends z.ZodType>(schema: T): z.ZodType<Array<z.output<T>>>;
+/** Whether `value` is a JSON object (a dict to Python): not null, not an array. */
+export declare function isObject(value: unknown): value is Record<string, unknown>;

package/dist/types/claw/message-text.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the worker appends to a person's message before it goes to Claw, and how it is taken off again: the request
+ * for a change summary (the phone has no diff view), then the reply-style rule a Claw rule tool holds.
+ */
+/** What the reply-style rule is introduced with. */
+export declare const RULE_HEADING = "## Teams reply style (formatting only, facts unchanged)";
+/** What the change-summary request is introduced with. */
+export declare const CHANGE_HEADING = "## Teams change summary (only when files in a git repository changed)";
+/** The change-summary request: about the answer's last lines, not a style, so it is kept apart from the rule. */
+export declare const CHANGE_SUMMARY_RULE: string;
+/** Exactly what the worker appends first, whether or not a rule follows. */
+export declare const CHANGE_SECTION = "\n\n## Teams change summary (only when files in a git repository changed)\n\nIf during this task you changed files in a git working tree, end your answer with a short section titled **Changes**: in one code block, the output of `git diff --stat HEAD` (and, for a new file git does not track yet, its line from `git status --short`), at most 15 lines, then \"+N more files\" for the rest. Read-only commands only; do not stage, commit or push to produce it. If nothing in a git working tree changed, leave the section out.";
+/** A rule is edited in Claw; a changed rule reaches the chat within this. */
+export declare const RULE_TTL_MS = 600000;
+/** A reply-style rule is about 1 KB; anything this large is not one. */
+export declare const RULE_MAX_BYTES = 32768;
+/**
+ * `text` as the person wrote it, with what the worker appended taken off again. The change summary is a fixed text and
+ * always the first thing appended, so it marks where the person's own words end: it is looked for from the end, and
+ * everything from it on goes. A message from before the request existed has only the rule: it is cut where the rule's
+ * heading first starts.
+ */
+export declare function withoutRule(text: string): string;
+/**
+ * The content of a message to a plain session: the person's text, then the change-summary request (only where a rule
+ * tool is configured), then the rule when there is one.
+ */
+export declare function messageContent(text: string, rule: string, withRuleTool: boolean): string;

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

@@ -0,0 +1,118 @@
+/**
+ * What this agent reads out of Claw's answers, after they were checked (`ClawPort` implementations and the parsers in
+ * this directory build these). The wire shapes themselves are `@claw/protocol`'s (`../protocol.ts`); these are the
+ * readings: tolerant of a missing field the way the worker always was, and in this codebase's naming.
+ */
+import type { JsonObject } from "../json.js";
+import type { PrRef } from "../protocol.js";
+/** One pull request: `{owner, repo, number}` as Claw writes it. */
+export type PullRef = Readonly<PrRef>;
+/**
+ * One work item as Claw's board shows it (`GET /v1/work-items`) and as an assistant event carries it. `canAccept` is
+ * Claw's own word for "a result waits for this person" (false as well when Claw says it needs no acceptance).
+ */
+export interface WorkItem {
+    readonly itemId: string;
+    readonly seq: number;
+    readonly title: string;
+    /** in_progress | needs_you | done (another word from a newer Claw is kept as it came). */
+    readonly boardState: string;
+    readonly resultVersion: number;
+    readonly canAccept: boolean;
+    readonly lastReportKind: string | null;
+    readonly pendingQuestion: string | null;
+    readonly summary: string;
+    /** accepted | answered | dropped | stopped, once the item is done. */
+    readonly outcome: string | null;
+    /** task | review | remote. */
+    readonly kind: string;
+    /** What a review was asked with (`{}` for a task). */
+    readonly params: Readonly<JsonObject>;
+    /** The pull request of a review item, or null. */
+    readonly pull: PullRef | null;
+    /** When Claw last changed it (ISO 8601; "" not said). */
+    readonly updatedAt: string;
+}
+/**
+ * What Claw answered to a person's accept, stop or retry: `ok`, or a 409 that says why not (`error`) and carries the item
+ * as it is now, so that a card for an old version can be replaced by one for the current one.
+ */
+export interface Decision {
+    readonly ok: boolean;
+    readonly item: WorkItem;
+    /** version_mismatch | not_acceptable | item_closed | ... ("" when ok). */
+    readonly error: string;
+}
+/**
+ * What the asker of a review someone else runs may know of it: its state, the pull request's link, the conclusion and
+ * whether it was merged, what a waiting one waits for, what it found, and what the pull request does.
+ */
+export interface AskerView {
+    readonly itemId: string;
+    readonly status: string;
+    readonly prUrl: string;
+    /** approve | request_changes | comment ("" none yet). */
+    readonly verdict: string;
+    readonly merged: boolean;
+    /** confirm_merge | confirm_review | failed | reviewer ("" Claw did not say). */
+    readonly waitingFor: string;
+    /** Open findings posted on the pull request (null: Claw did not say). */
+    readonly findings: number | null;
+    /** The first open finding in one line ("" none). */
+    readonly note: string;
+    /** What the pull request does, clipped for showing ("" Claw did not say). */
+    readonly prSummary: string;
+}
+/** A review the caller asked of someone else: its item, whom they asked, and their view of it. */
+export interface ReviewAskedOfOther {
+    readonly itemId: string;
+    readonly reviewer: string;
+    readonly view: AskerView;
+}
+/**
+ * One pull request Claw started a review item for (`POST /v1/assistant/reviews`): the item, and the session Claw made
+ * for it with its first message queued.
+ */
+export interface ReviewStart {
+    readonly target: PullRef;
+    readonly itemId: string;
+    readonly seq: number;
+    readonly title: string;
+    /** "" for a review asked of someone else (that person's session, never followed). */
+    readonly sessionId: string;
+    /** The first turn's id when Claw says it ("" otherwise). */
+    readonly messageId: string;
+    /** The model Claw says it runs on ("" its default); null: Claw did not say. */
+    readonly model: string | null;
+    /** The model it was to run on, which the payer's key cannot use ("" none). */
+    readonly fellBackFrom: string;
+    /** What Claw set aside of the request ("model", "effort"). */
+    readonly ignored: readonly string[];
+    /** true: every merge waits for the reviewer's confirmation; false: their review mode decides; null: Claw did not say. */
+    readonly mergeNeedsConfirmation: boolean | null;
+    /** The item limit that was full when Claw queued it ("" it started). */
+    readonly queued: string;
+    /** Claw merges it with the asker's own account once approved and green. */
+    readonly mergeByRequester: boolean;
+}
+/** Which GitHub token Claw's GitHub tools use for the token's own user now (never the token). */
+export interface GithubConnection {
+    /** "env" | "binding" | "" (none: `missing` says why). */
+    readonly readsWith: string;
+    readonly login: string;
+    /** "none" | "expired" | "". */
+    readonly missing: string;
+    readonly bindingReads: boolean;
+}
+/** One frame of a Claw SSE stream. `name` is the `event:` line, or the data's `type` for a plain `message` frame. */
+export interface SseEvent {
+    readonly id: string;
+    readonly name: string;
+    readonly data: Readonly<JsonObject>;
+}
+/** A person's long-term memory in Claw: whether it is on, whether Claw has it at all, and what it remembers. */
+export interface MemoryState {
+    readonly enabled: boolean;
+    readonly available: boolean;
+    readonly items: readonly string[];
+}

package/dist/types/claw/py-value.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Python's `str(value)` of a JSON value, where the worker wrote `str(x)` without `or ""`: None is "None", a boolean
+ * "True" / "False"; a list or an object is written as Python's JSON of it (its repr differs only in quotes).
+ */
+export declare function pyStrOf(value: unknown): string;
+/** `bool(value)` of a JSON value, as the Python worker tested an answer's field: "", 0, false, null, [] and {} are false. */
+export declare function pyTruthy(value: unknown): boolean;

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

@@ -0,0 +1,138 @@
+/**
+ * The answers of Claw's remote-agents routes (the user side) as this agent reads them. Claw does not name these list
+ * and response shapes in `@claw/protocol` yet (only `RemoteAgentDescriptor`); each field below is what the worker reads.
+ * A field that is absent, or of another type than written here, is read as absent (`undefined`): the domain fills in
+ * its own default, as the Python worker did with `dict.get`. A row that is not an object is left out.
+ */
+import type { JsonObject } from "../json.js";
+import { z } from "zod";
+import type { RemoteHidden } from "../protocol.js";
+/** One agent a connector reports (`RemoteAgentDescriptor`, read leniently). */
+export declare const remoteAgentSchema: z.ZodObject<{
+    agent_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    kind: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    name: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    capabilities: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<Record<string, unknown> | undefined, unknown>>>;
+}, z.core.$loose>;
+export type RemoteAgent = z.output<typeof remoteAgentSchema>;
+/** One of the caller's connectors (`GET /v1/remote-agents/connectors`). */
+export declare const remoteConnectorSchema: z.ZodObject<{
+    connector_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    name: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    online: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<boolean | undefined, unknown>>>;
+    version: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    last_seen_at: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    heartbeat_at: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    agents: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+        [x: string]: unknown;
+        agent_id?: string | undefined;
+        kind?: string | undefined;
+        name?: string | undefined;
+        capabilities?: Record<string, unknown> | undefined;
+    }[] | undefined, unknown>>>;
+}, z.core.$loose>;
+export type RemoteConnector = z.output<typeof remoteConnectorSchema>;
+/** One remote session (`GET /v1/remote-agents/sessions[/:id]`, and the answer of `POST /sessions`). */
+export declare const remoteSessionSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    status: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    connector_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    agent_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    cwd: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    read_only: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<boolean | undefined, unknown>>>;
+    updated_at: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+}, z.core.$loose>;
+export type RemoteSession = z.output<typeof remoteSessionSchema>;
+/** One stored event of a remote session (`GET .../events?mode=replay`): `{id, seq, type, ts, data}`. */
+export declare const remoteEventRowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    seq: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | undefined, unknown>>>;
+    type: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    ts: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | undefined, unknown>>>;
+    data: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<Record<string, unknown> | undefined, unknown>>>;
+}, z.core.$loose>;
+export type RemoteEventRow = z.output<typeof remoteEventRowSchema>;
+/** A list of rows read with `schema` (rows that are not objects are left out). */
+export declare const remoteConnectorsSchema: z.ZodType<{
+    [x: string]: unknown;
+    connector_id?: string | undefined;
+    name?: string | undefined;
+    online?: boolean | undefined;
+    version?: string | undefined;
+    last_seen_at?: string | undefined;
+    heartbeat_at?: string | undefined;
+    agents?: {
+        [x: string]: unknown;
+        agent_id?: string | undefined;
+        kind?: string | undefined;
+        name?: string | undefined;
+        capabilities?: Record<string, unknown> | undefined;
+    }[] | undefined;
+}[], unknown, z.core.$ZodTypeInternals<{
+    [x: string]: unknown;
+    connector_id?: string | undefined;
+    name?: string | undefined;
+    online?: boolean | undefined;
+    version?: string | undefined;
+    last_seen_at?: string | undefined;
+    heartbeat_at?: string | undefined;
+    agents?: {
+        [x: string]: unknown;
+        agent_id?: string | undefined;
+        kind?: string | undefined;
+        name?: string | undefined;
+        capabilities?: Record<string, unknown> | undefined;
+    }[] | undefined;
+}[], unknown>>;
+export declare const remoteSessionsSchema: z.ZodType<{
+    [x: string]: unknown;
+    session_id?: string | undefined;
+    status?: string | undefined;
+    connector_id?: string | undefined;
+    agent_id?: string | undefined;
+    cwd?: string | undefined;
+    read_only?: boolean | undefined;
+    updated_at?: string | undefined;
+}[], unknown, z.core.$ZodTypeInternals<{
+    [x: string]: unknown;
+    session_id?: string | undefined;
+    status?: string | undefined;
+    connector_id?: string | undefined;
+    agent_id?: string | undefined;
+    cwd?: string | undefined;
+    read_only?: boolean | undefined;
+    updated_at?: string | undefined;
+}[], unknown>>;
+export declare const remoteEventRowsSchema: z.ZodType<{
+    [x: string]: unknown;
+    id?: string | undefined;
+    seq?: number | undefined;
+    type?: string | undefined;
+    ts?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+}[], unknown, z.core.$ZodTypeInternals<{
+    [x: string]: unknown;
+    id?: string | undefined;
+    seq?: number | undefined;
+    type?: string | undefined;
+    ts?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+}[], unknown>>;
+/**
+ * The answer of hiding conversations of a machine from the owner's lists, or showing them again
+ * (`POST /v1/remote-agents/connectors/:cid/hidden`): `@claw/protocol`'s `RemoteHidden`, the refs that changed and the
+ * ones refused (`live`: a process has it open; `unknown_conversation`: the machine does not report it now). Read
+ * strictly: an answer of another shape is one this client does not understand.
+ */
+export declare const remoteHiddenSchema: z.ZodType<RemoteHidden>;
+/** How to connect a machine (`GET /setup`): the connector's package and the exact commands, passed on as Claw wrote them. */
+export type RemoteSetup = JsonObject;
+/** A one-time pairing (`POST /pairings`). */
+export declare const remotePairingSchema: z.ZodObject<{
+    code: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    expires_at: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    expires_in: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | undefined, unknown>>>;
+    server: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+    command: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+}, z.core.$loose>;
+export type RemotePairing = z.output<typeof remotePairingSchema>;

package/dist/types/claw/requester-view.d.ts

@@ -0,0 +1,15 @@
+import type { AskerView } from "./model.js";
+/** A pull request's one-sentence summary is shown at most this long (code points): Chinese, Japanese, Korean / other. */
+export declare const PR_SUMMARY_MAX_CJK = 80;
+export declare const PR_SUMMARY_MAX_OTHER = 160;
+/**
+ * A review's sentence of what the pull request does, as it is shown: one line, credentials masked, no link or tag
+ * markup, at most PR_SUMMARY_MAX_CJK code points when it is Chinese and PR_SUMMARY_MAX_OTHER otherwise (a longer one
+ * is cut and ends in an ellipsis). "" for anything that is not a non-empty string.
+ */
+export declare function clipPrSummary(value: unknown): string;
+/**
+ * The asker's view of a review item from Claw's answer; null when the answer carries none. Only the view's own fields
+ * are read.
+ */
+export declare function parseRequesterView(raw: unknown, itemId: string): AskerView | null;

package/dist/types/claw/service-refusal.d.ts

@@ -0,0 +1,4 @@
+import type { Lang } from "../locales/lang.js";
+import type { ClawError } from "./errors.js";
+/** The sentence for a refusal of Claw's: its reason (a word it does not name reads as the last one) and what was not done. */
+export declare function serviceRefusal(err: ClawError, undone: string, lang?: Lang): string;

package/dist/types/claw/sse.d.ts

@@ -0,0 +1,12 @@
+import type { SseEvent } from "./model.js";
+/** One SSE frame ("id:/event:/data:" lines) to an event; null for comments and anything whose data is not a JSON object. */
+export declare function parseSseBlock(block: string): SseEvent | null;
+/**
+ * Splits a stream of text chunks into SSE frames, as they complete (a frame ends at a blank line; CRLF is read as LF).
+ * What is left at the end of the stream without a blank line is not a frame.
+ */
+export declare class SseFrames {
+    private buffer;
+    /** The events completed by `chunk`. */
+    push(chunk: string): SseEvent[];
+}

package/dist/types/claw/started-review.d.ts

@@ -0,0 +1,7 @@
+import type { ReviewStart } from "./model.js";
+/**
+ * Claw's `data` for reviews it started. One without its pull request or its session cannot be told from the others or
+ * followed: an answer this client does not understand (ClawAnswerInvalid), never a review that is quietly not shown.
+ * `followed` false: reviews asked of someone else, whose sessions are that person's; none is needed.
+ */
+export declare function parseStartedReviews(data: unknown, followed?: boolean): ReviewStart[];

package/dist/types/claw/work-item.d.ts

@@ -0,0 +1,25 @@
+import type { AskerView, PullRef, WorkItem } from "./model.js";
+/** The pull request of a review item (`params.pr`); null for anything else, or for one that is not a pull request. */
+export declare function pullOf(params: Readonly<Record<string, unknown>> | undefined): PullRef | null;
+/**
+ * A work item from Claw's JSON; null when it is not one (no id, or not an object), so a malformed row is skipped. Only
+ * a `can_accept` that is true counts, and not when Claw says the result needs no acceptance (`needs_accept` false).
+ */
+export declare function parseWorkItem(raw: unknown): WorkItem | null;
+/**
+ * A work item made of the asker's view alone (Claw answers the asker of someone else's review with nothing more): its
+ * id, its pull request as its title, and the view in `params` so that what is shown is what the asker may see.
+ */
+export declare function requesterViewItem(view: AskerView, raw: unknown): WorkItem;
+/**
+ * The item an accept, stop or retry answered with. To the asker of a review someone else runs Claw answers with the
+ * asker's view alone: an answer without the board's own fields (`board_state`) is read as that view.
+ */
+export declare function decidedItem(itemId: string, data: unknown): WorkItem | null;
+/** The statuses of a review that is still open to its asker; a waiting one waits for its reviewer. */
+export declare const REQUESTER_VIEW_WAITING: ReadonlySet<string>;
+export declare const REQUESTER_VIEW_OPEN: ReadonlySet<string>;
+/** Whether the review is over, to its asker. */
+export declare function isFinished(view: AskerView): boolean;
+/** Whether the review waits for its reviewer. */
+export declare function waitsForReviewer(view: AskerView): boolean;

package/dist/types/commands/agent-args.d.ts

@@ -0,0 +1,9 @@
+export declare const AGENT_SUBCOMMANDS: readonly ["new", "attach", "detach", "mode", "sessions", "close", "off", "pair"];
+export type AgentSubcommand = (typeof AGENT_SUBCOMMANDS)[number];
+export interface AgentCommand {
+    readonly verb: AgentSubcommand;
+    /** What follows the verb; `new` keeps it whole (a folder name may hold spaces). */
+    readonly rest: string;
+}
+/** The arguments of `/agent ARGS`; null when ARGS is empty or names no subcommand (the caller shows the usage). */
+export declare function parseAgentCommand(arg: string): AgentCommand | null;

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

@@ -0,0 +1,19 @@
+/**
+ * The chat's command words. Anything else, unknown `/words` included, goes on as the person's text.
+ *
+ * What help says is rendered from the capability registry (`capabilities/registry.ts`), not from this list.
+ */
+export declare const COMMANDS: readonly ["help", "new", "stop", "unlink", "whoami", "resume", "memory", "sessions"];
+/** The only commands a group chat accepts. */
+export declare const GROUP_COMMANDS: readonly ["help", "new", "stop", "whoami", "feedback"];
+export declare const PERSONAL_ONLY_COMMANDS: readonly ["link", "unlink", "resume", "timezone", "quiet", "pause", "brief", "repo", "sessions", "agents", "agent", "lang"];
+/**
+ * `/feedback [TEXT]` takes an argument, so it is read with `commandArgs`, never `parseCommand`; it is listed here (not in
+ * COMMANDS) only so that a group chat accepts it and an unknown `/word` is still plain text.
+ */
+export declare const ARGUMENT_COMMANDS: readonly ["feedback"];
+export type Command = (typeof COMMANDS)[number];
+/** A command the worker handles itself (anything else is text for Claw). */
+export declare function isKnownCommand(name: string): boolean;
+export declare function isGroupCommand(name: string): boolean;
+export declare function isCommand(name: string): name is Command;