@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/locales/steps.d.ts

@@ -0,0 +1,42 @@
+/** A label: `one` for a step, `many` for the same step repeated ("Reading files (3)"); Chinese has one form. */
+export declare const stepText: import("./catalog.js").Catalog<{
+    read: string;
+    reads: string;
+    edit: string;
+    edits: string;
+    shell: string;
+    shells: string;
+    search: string;
+    web: string;
+    task: string;
+    tasks: string;
+    boardRead: string;
+    boardReads: string;
+    safe: string;
+    boardList: (p: {
+        what: string;
+    }) => string;
+    /** "Listing board issues" names what is listed in English. */
+    boardListWhat: (p: {
+        verb: string;
+    }) => string;
+    skill: (p: {
+        skill: string;
+    }) => string;
+    generic: (p: {
+        what: string;
+    }) => string;
+    failed: (p: {
+        label: string;
+    }) => string;
+    safeQuery: (p: {
+        what: string;
+    }) => string;
+    query: (p: {
+        server: string;
+    }) => string;
+}>;
+/** What a SaFE read is about, by the first word of its name (`node_list` -> nodes): (English, Chinese). */
+export declare const SAFE_OBJECTS: Readonly<Record<string, readonly [string, string]>>;
+/** The assistant's own tools (`mcp__assistant__*`), by what the person sees it do: (English, Chinese). */
+export declare const ASSISTANT_STEPS: Readonly<Record<string, readonly [string, string]>>;

package/dist/types/locales/transparency.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What the bot tells people about its answers and their data (security review). One place for the wording, so that help, the first
+ * 1:1 message and the connect cards say the same thing. Each text is plain and short so it translates line by line.
+ *
+ * The numbers were checked against the code and the live configuration: the worker keeps its copy of a delivered problem report for
+ * 30 days (the store's feedback retention); Claw keeps a session until its owner deletes it; database backups go back about a week.
+ * A change to any of these is a change to this text.
+ */
+import { type Lang } from "./lang.js";
+/** One text in each language. */
+export type Phrase = Readonly<Record<Lang, string>>;
+export declare const AI_NOTICE: Phrase;
+export declare const DATA_TITLE: Phrase;
+export declare const DATA_LINES: Readonly<Record<Lang, readonly string[]>>;
+/** Only where remote agents are on (a 1:1 chat): an attached chat's messages go to the person's own machine, not to PrimusClaw. */
+export declare const REMOTE_LINE: Phrase;
+/** The section of help about answers and data, in `lang`; `remote`: remote agents are on in this chat. */
+export declare function dataStatement(lang: string, remote?: boolean): string;

package/dist/types/locales/turn.d.ts

@@ -0,0 +1,70 @@
+import type { SuggestedReply } from "../ports/surface.js";
+import type { Lang } from "./lang.js";
+/** Said in the person's language. */
+export declare const turnText: import("./catalog.js").Catalog<{
+    /** The progress message's first line. */
+    liveHeader: string;
+    preparing: string;
+    planHead: (p: {
+        done: number;
+        total: number;
+    }) => string;
+    planAllDone: (p: {
+        total: number;
+    }) => string;
+    planMore: (p: {
+        n: number;
+        done: number;
+        todo: number;
+    }) => string;
+    /** A floating status before anything happened. */
+    thinking: string;
+    /** A turn still running when its stream has to close: the answer follows as a message of its own. */
+    stillWorking: string;
+    interrupted: string;
+    /** The final message of a stream whose turn ended with nothing to say (it is never empty). */
+    doneShort: string;
+    /** What a failed turn says; the error itself, and its reference, go to the log only. */
+    taskFailed: string;
+    openSession: string;
+    queuedNotice: string;
+    stillRunning: (p: {
+        minutes: number;
+    }) => string;
+    stillRunningNotify: string;
+    stillRunningOpen: string;
+}>;
+/** Suggested replies under a finished answer in a 1:1 chat: what the button says, and what it sends. */
+export declare const SUGGESTED_REPLIES: Readonly<Record<Lang, readonly SuggestedReply[]>>;
+/** Said in English in every chat (the Python worker has them in English only). */
+export declare const turnEnglish: {
+    /** The one line the progress message is edited down to where it cannot be deleted. */
+    readonly doneLine: "Done — answer below";
+    readonly noTextOutput: "Done. There was no text output.";
+    readonly shortened: "... (shortened)";
+    readonly openFullAnswer: "Open the full answer";
+    readonly onlyTheAsker: " (only the person who asked can open it)";
+    readonly wholeCutNote: "\n\n… (the rest did not fit in three messages)";
+    readonly couldNotLoad: (name: string, count: number) => string;
+    readonly stopped: "Stopped.";
+    readonly lostConnection: "I lost the connection to PrimusClaw before the task finished.";
+    readonly openSessionLink: "Open the session";
+    readonly keyRejected: "PrimusClaw rejected your linked key (it may have expired or been deleted). Send /unlink, then link again.";
+    readonly clawBusy: "PrimusClaw is busy right now. Please try again in a minute.";
+    readonly clawRequestFailed: (status: number, ref: string) => string;
+    readonly nothingStarted: "Nothing was started.";
+    /** Both languages in one line: the group of a review is told, whatever its language. */
+    readonly reviewRefused: "没能开始 review：请求人的 PrimusClaw 凭据没有被接受，我已私信请求人说明。 / The review did not start: PrimusClaw did not accept the asker's credentials; I told them in their own chat.";
+    readonly filesNotPassed: (list: string) => string;
+    readonly anImage: "an image";
+    readonly aFile: "a file";
+    readonly filesNotTaken: "this worker does not take files";
+    readonly clawDidNotTake: "Claw did not take it";
+    readonly deliveryLine: (name: string, size: string, caption: string, url: string) => string;
+};
+/** The Stop card of a turn from a phone (stop_button.py); what a press is answered with is in locales/routing.ts. */
+export declare const stopText: import("./catalog.js").Catalog<{
+    card: string;
+    button: string;
+    notChecked: string;
+}>;

package/dist/types/locales/typed-answer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What a typed answer is asked back with (`typed-answer/`). Each says it in Chinese and English at once, in one
+ * message: a typed answer comes from a person whose language this agent has not settled, so both are written, as the
+ * Python worker wrote them.
+ */
+export declare const typedAnswerText: {
+    readonly nothingWaits: "现在没有在等你确认的合入或 review（可能已经处理过，或已过期）。 / Nothing is waiting for your confirmation now.";
+    readonly notWaiting: (p: {
+        name: string;
+        listing: string;
+    }) => string;
+    readonly whichRepo: (p: {
+        name: string;
+        count: number;
+        listing: string;
+        repo: string;
+        number: number;
+    }) => string;
+    readonly which: (p: {
+        listing: string;
+        first: number;
+    }) => string;
+    readonly heldTwice: (p: {
+        pull: string;
+        held: string;
+        pr: number;
+    }) => string;
+    readonly heldMerge: "合入";
+    readonly heldReview: (p: {
+        event: string;
+    }) => string;
+};

package/dist/types/note/note.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A short note, under an optional headline, with the buttons that go with it: what replaces a card the person just
+ * clicked (the outcome of the click, and the buttons again when it has to be repeated), and any other "a line and a
+ * button" message (render.py's note_card). Every line uses this view for that shape.
+ */
+import type { OutMessage, ViewButton } from "../ports/surface.js";
+/** How the note's headline reads: its colour and its emoji. */
+export type NoteTone = "default" | "good" | "attention" | "warning" | "accent";
+export interface NoteModel {
+    readonly text: string;
+    /** A headline over the note (none: the note alone). */
+    readonly title?: string;
+    readonly tone?: NoteTone;
+    readonly buttons?: readonly ViewButton[];
+}
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        note: NoteModel;
+    }
+}
+/** The note as a message; a client that cannot draw it shows its text. */
+export declare function noteMessage(model: NoteModel): OutMessage;

package/dist/types/observability/ip-address.d.ts

@@ -0,0 +1,13 @@
+/**
+ * IP addresses parsed and written the way Python's `ipaddress.ip_address` and `str()` do (core cannot use `node:net`,
+ * and the logged form has to stay the one SIEM rules were written against): strict dotted IPv4 (no leading zeros), IPv6
+ * with at most one `::` and an optional dotted IPv4 tail, written lower-case with the first longest run of two or more
+ * zero groups compressed, and an IPv4-mapped address as `::ffff:a.b.c.d`. No scope id (`%zone`).
+ */
+/** An address as Python writes it, and, for an IPv4-mapped IPv6 address, the IPv4 address it maps. */
+export interface IpAddress {
+    readonly address: string;
+    readonly mappedV4: string | null;
+}
+/** `text` as an IP address the way Python's `ipaddress` reads and writes it, or null when it is not one. */
+export declare function parseIpAddress(text: string): IpAddress | null;

package/dist/types/observability/metrics-catalog.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The closed lists every metric label value comes from, so the number of series is fixed and no label names a person,
+ * a conversation or anything a person chose.
+ */
+/** The category fields of a security event that become labels of `clawy_security_events_total`, in this order. */
+export declare const SECURITY_EVENT_LABELS: readonly ["scope", "outcome", "reason"];
+/** Why a message or task was refused by a per-person limit. */
+export declare const LIMIT_REASONS: readonly ["user_limit", "concurrency_limit"];
+export type LimitReason = (typeof LIMIT_REASONS)[number];
+/** The event types from Claw that are labels as themselves; any other is counted as "other". */
+export declare const DELIVERED_EVENT_TYPES: readonly ["approval.requested", "work_item.needs_you", "assistant.say", "assistant.action", "run.completed", "run.failed", "other"];
+/**
+ * Where a file a person sent did not reach Claw: the assistant path, a session turn, a chat attached to a remote agent,
+ * a review request, and a file the channel gave no way to fetch. Every one is also said to the person.
+ */
+export declare const FILES_DROPPED_PATHS: readonly ["assistant", "session", "remote_agent", "review", "unreadable"];
+export type FilesDroppedPath = (typeof FILES_DROPPED_PATHS)[number];

package/dist/types/observability/security-events.d.ts

@@ -0,0 +1,26 @@
+/** The security events, their log levels (a closed list: SIEM rules match on these names). */
+export declare const SECURITY_EVENTS: {
+    readonly link_attempt: "info";
+    readonly link_lockout: "warn";
+    readonly token_rejected: "warn";
+    readonly approval_answered: "info";
+    readonly merge_confirmed: "info";
+    readonly pr_merged: "info";
+    readonly rate_limited: "warn";
+    readonly key_unlinked: "info";
+    readonly on_behalf_message: "info";
+};
+export type SecurityEventName = keyof typeof SECURITY_EVENTS;
+/** One logged security event: `event` first, then only allow-listed, shape-checked fields, and `dropped` field names. */
+export type SecurityEventRecord = Readonly<{
+    event: SecurityEventName;
+    dropped?: readonly string[];
+} & Record<string, unknown>>;
+/** What the log of security events is called (the Python worker's logger name, which SIEM rules select on). */
+export declare const SECURITY_LOGGER = "clawy.security";
+/**
+ * The record of one security event. `event` must be one of SECURITY_EVENTS (anything else is a bug: InvariantError). A
+ * field whose value is null or undefined is left out. A field whose value does not fit its shape is dropped and its
+ * name listed in `dropped`; a field that is not one of SECURITY_FIELDS is listed as `<unknown_field>` (its name could be text).
+ */
+export declare function securityEventRecord(event: SecurityEventName, fields?: Readonly<Record<string, unknown>>): SecurityEventRecord;

package/dist/types/observability/security-fields.d.ts

@@ -0,0 +1,8 @@
+/** A field's check: the value to log, or undefined when it must not be logged. */
+export type FieldCheck = (value: unknown) => unknown;
+/** Whether `value` holds a `/link` code, as printed, as typed or inside a longer value. */
+export declare function holdsALinkCode(value: string): boolean;
+/** Category field -> the values it takes. Categories are chosen by the code, never by a person. */
+export declare const SECURITY_FIELD_CATEGORIES: Readonly<Record<string, ReadonlySet<string>>>;
+/** Field name -> its check. */
+export declare const SECURITY_FIELDS: Readonly<Record<string, FieldCheck>>;

package/dist/types/observability/security-log.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Security events: one structured log line per security-relevant decision, for SIEM detection rules, counted into the
+ * metrics as well. The line's message is the record as compact JSON whose first key is `event` (the same line the Python
+ * worker wrote), on the logger named SECURITY_LOGGER.
+ */
+import type { Logger } from "../ports/logger.js";
+import type { MetricsPort } from "../ports/metrics.js";
+import { type RequestScope } from "../ports/request-scope.js";
+import { type SecurityEventName, type SecurityEventRecord } from "./security-events.js";
+export declare class SecurityLog {
+    private readonly metrics;
+    private readonly scope;
+    private readonly log;
+    constructor(logger: Logger, metrics: MetricsPort, scope?: RequestScope);
+    /**
+     * Logs and counts one security event; the record that was logged (see `securityEventRecord`). A caller that names no
+     * `activity_id` gets the activity being handled, after its own fields; one that names it, even as null, keeps its own
+     * (Python guardrails.audit).
+     */
+    event(event: SecurityEventName, fields?: Readonly<Record<string, unknown>>): SecurityEventRecord;
+}

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

@@ -0,0 +1,18 @@
+import type { ClawAssistantPort } from "../ports/claw/assistant.js";
+import type { Logger } from "../ports/logger.js";
+import type { ObserveRepository } from "../ports/store/observe.js";
+import { type Conversation } from "../ports/surface.js";
+export interface BoardDeps {
+    readonly observe: ObserveRepository;
+    readonly assistant: Pick<ClawAssistantPort, "observations">;
+    readonly log: Logger;
+}
+export declare class ObserveBoard {
+    private readonly deps;
+    constructor(deps: BoardDeps);
+    show(userId: string, key: string, conversation: Conversation): Promise<void>;
+    /** A group's record; one that cannot be read is left out of this board. */
+    private record;
+    /** The calls of one recorded message that are suggestions and are not settled yet. */
+    private suggestionsOf;
+}

package/dist/types/observe/command.d.ts

@@ -0,0 +1,6 @@
+/** `/observe on | off | status`, said to the bot in a group; with 开/关/状态 as well. */
+export type ObserveVerb = "on" | "off" | "status" | "usage";
+/** The command's verb, `usage` for a malformed one, undefined when the text is not this command. */
+export declare function parseObserve(text: string): ObserveVerb | undefined;
+/** The scope a group chat is to Claw, or undefined when its id cannot be one. */
+export declare function scopeOf(conversationId: string): string | undefined;

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

@@ -0,0 +1,6 @@
+export { OBSERVE_TEXT, observeText } from "../locales/observe.js";
+export * from "./command.js";
+export * from "./suggestions.js";
+export * from "./board.js";
+export * from "./observer.js";
+export * from "./views.js";

package/dist/types/observe/observer.d.ts

@@ -0,0 +1,45 @@
+import type { JsonObject } from "../json.js";
+import type { ClawAssistantPort } from "../ports/claw/assistant.js";
+import type { Logger } from "../ports/logger.js";
+import type { ClickHandler, MessageInterceptor } from "../ports/routing.js";
+import type { LinkRepository } from "../ports/store/link.js";
+import type { ObserveRepository } from "../ports/store/observe.js";
+import { type Conversation, type InboundMessage } from "../ports/surface.js";
+import type { Observing } from "../routing/features.js";
+export interface ObserverDeps {
+    readonly observe: ObserveRepository;
+    readonly links: Pick<LinkRepository, "getKey">;
+    readonly assistant: Pick<ClawAssistantPort, "observeScope" | "observe" | "observations" | "session" | "send">;
+    /** Who may turn it on (TEAMS_OBSERVE_USERS, any case); empty: nobody. */
+    readonly users: readonly string[];
+    /** A conversation from the reference the store kept for a group (the channel's `ConversationRef.wire`). */
+    readonly conversationOf: (wire: JsonObject) => Conversation;
+    /** CLAW_PLUGIN_ID, named on the request an accepted suggestion becomes. */
+    readonly pluginId: number | undefined;
+    readonly log: Logger;
+}
+export declare class Observer implements Observing {
+    private readonly deps;
+    private readonly users;
+    private readonly boardReader;
+    constructor(deps: ObserverDeps);
+    get enabled(): boolean;
+    mayTurnOn(userId: string): boolean;
+    /** `/observe on|off|status` in a group (before the account check: on needs the person's key, off and status none). */
+    readonly interceptor: MessageInterceptor;
+    /** Accept and Dismiss under a suggestion card (1:1, with the person's key). */
+    readonly clicks: ClickHandler;
+    board(userId: string, credential: string, conversation: Conversation): Promise<void>;
+    private command;
+    private turnOn;
+    /**
+     * A group message not addressed to the bot. In a group nobody observes: nothing (not read, kept or logged). In an
+     * observed one: to the observer's assistant with the observer's key, as who said it and what.
+     */
+    forward(message: InboundMessage): Promise<void>;
+    /** A press under a suggestion card: only its own person's, and of two presses one is carried out. */
+    private onClick;
+    private postReply;
+    /** Anything but a reply: the person's own request to their own assistant, which answers in their 1:1 chat. */
+    private handOver;
+}

package/dist/types/observe/suggestions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What an observer turn would have done, as a suggestion: which recorded tool calls are suggestions at all, and how one
+ * is shown on its card and carried out on Accept (exactly as shown).
+ */
+/** `pass` (it would do nothing) and the lookups an observer turn makes on its way to a decision: nothing to accept. */
+export declare const NOT_SUGGESTIONS: ReadonlySet<string>;
+/** The assistant tool's own name, without the MCP prefix. */
+export declare function toolOf(raw: unknown): string;
+export interface Suggestion {
+    /** What kind of thing it would have done. */
+    readonly kind: string;
+    /** What exactly: the reply's text, the task's title and brief, else the call's arguments. */
+    readonly what: string;
+}
+/** The suggestion a recorded call `tool(args)` is. */
+export declare function describe(tool: string, args: unknown): Suggestion;

package/dist/types/observe/views.d.ts

@@ -0,0 +1,19 @@
+import type { ViewButton, OutMessage } from "../ports/surface.js";
+/** One suggestion of an observed group, on the observer's /board: what their assistant would have done there. */
+export interface ObserveSuggestionView {
+    readonly cardId: string;
+    /** The group's name ("" when the channel gave none). */
+    readonly group: string;
+    /** What was said in the group. */
+    readonly message: string;
+    readonly kind: string;
+    readonly what: string;
+}
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        observeSuggestion: ObserveSuggestionView;
+    }
+}
+/** Accept (the primary button) and Dismiss: what a suggestion card has, and what a press that did nothing puts back. */
+export declare function suggestionButtons(cardId: string): ViewButton[];
+export declare function suggestionMessage(model: ObserveSuggestionView): OutMessage;

package/dist/types/own.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lookups in a plain object by a key that is not a literal. A plain object inherits Object.prototype, so `table[key]`
+ * answers `table.constructor` for the key "constructor" and `"toString" in table` is true, where the Python dict the
+ * code was ported from has no such keys. The lint rule `own-keys/no-prototype-keys` refuses the bare forms; these are
+ * the forms it accepts (or use a Map, or build a table with `Object.fromEntries`, which keeps a "__proto__" key as an
+ * own key).
+ */
+/** `table.get(key)` of a Python dict: the table's own value for `key`, else undefined. */
+export declare function own<V>(table: Readonly<Record<string, V>>, key: string): V | undefined;

package/dist/types/plugins/feedback-sink.d.ts

@@ -0,0 +1,31 @@
+import { type Result } from "../result.js";
+/**
+ * Where `/feedback` reports go (the Python worker's `feedback.GitHubIssues`: issues in one repository). The report is
+ * recorded before it is delivered, and a hidden marker in the issue or comment lets a retry find what an earlier
+ * attempt delivered without an answer, so nothing is filed twice.
+ */
+export interface IssueRef {
+    readonly number: number;
+    readonly url: string;
+}
+/** The sink could not do it: the HTTP status it got (0 when nothing answered) and a short code; never a body. */
+export interface SinkFailed {
+    readonly kind: "sink_failed";
+    readonly status: number;
+    readonly code: string;
+}
+/** No sink is configured: reports are recorded and not delivered. */
+export interface SinkNotConfigured {
+    readonly kind: "sink_not_configured";
+}
+export type SinkError = SinkFailed | SinkNotConfigured;
+export interface FeedbackSink {
+    createIssue(title: string, body: string, labels: readonly string[]): Promise<Result<IssueRef, SinkError>>;
+    /** The report issue whose body carries `marker`, created since `sinceEpochMs`; undefined when there is none. */
+    findIssue(marker: string, sinceEpochMs: number): Promise<Result<IssueRef | undefined, SinkError>>;
+    /** Whether a comment on issue `issue` since `sinceEpochMs` carries `marker`. */
+    hasComment(issue: number, marker: string, sinceEpochMs: number): Promise<Result<boolean, SinkError>>;
+    comment(issue: number, body: string): Promise<Result<void, SinkError>>;
+}
+/** No sink: every call says so, and the report stays recorded. */
+export declare const noFeedbackSink: FeedbackSink;

package/dist/types/plugins/identity-lookup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Who a Claw key belongs to, asked of the platform that issued it (the Python worker's `safe.whoami`, `safe.safe_user`
+ * and `safe.user_id_of`: one `/users/self` call made with the key itself). Used when a person links a key, to record
+ * whose it is, and to check that a key presented later is the same person's.
+ */
+export interface KeyOwner {
+    /** The platform's user id ("" when it gave none). */
+    readonly id: string;
+    /** The display name ("" when it gave none). */
+    readonly name: string;
+    /** "" when it gave none. */
+    readonly email: string;
+    /** The account type, lower case ("sso", "default", ...; "" when it gave none). */
+    readonly accountType: string;
+}
+export interface IdentityLookup {
+    /** The owner of `key`; undefined on any failure (unreachable, rejected, malformed answer): the caller says so. */
+    ownerOfKey(key: string): Promise<KeyOwner | undefined>;
+}
+/** No platform to ask: nobody is known. */
+export declare const noIdentityLookup: IdentityLookup;

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

@@ -0,0 +1,31 @@
+import { type FeedbackSink } from "./feedback-sink.js";
+import { type IdentityLookup } from "./identity-lookup.js";
+import { type Integrations } from "./integrations.js";
+import { type KeyRevoker } from "./key-revoker.js";
+import { type ModelRefusalPolicy } from "./model-refusal-policy.js";
+import { type RouteExtension } from "./route-extension.js";
+import { type TokenExchange } from "./token-exchange.js";
+/**
+ * What a deployment plugs in. The public build runs with the neutral defaults (`neutralPlugins`); a deployment's own
+ * assembly passes its implementations (an identity platform, a model gateway's refusal rules, extra routes). Core
+ * depends on these interfaces only.
+ */
+export interface Plugins {
+    readonly identityLookup: IdentityLookup;
+    readonly keyRevoker: KeyRevoker;
+    readonly feedbackSink: FeedbackSink;
+    readonly modelRefusalPolicy: ModelRefusalPolicy;
+    readonly tokenExchange: TokenExchange;
+    readonly routeExtensions: readonly RouteExtension[];
+    /** The deployment's MCP servers and /whoami lines (`integrations.ts`); none in the public build. */
+    readonly integrations: Integrations;
+}
+/** Every plugin at its neutral default, with `overrides` in their place. */
+export declare function neutralPlugins(overrides?: Partial<Plugins>): Plugins;
+export * from "./feedback-sink.js";
+export * from "./identity-lookup.js";
+export * from "./key-revoker.js";
+export * from "./model-refusal-policy.js";
+export * from "./route-extension.js";
+export * from "./token-exchange.js";
+export * from "./integrations.js";

package/dist/types/plugins/integrations.d.ts

@@ -0,0 +1,34 @@
+import type { Lang } from "../locales/lang.js";
+import type { KeyOwner } from "./identity-lookup.js";
+/**
+ * Services of one deployment that the worker names, registered here so that the worker's own code names none of them
+ * (the Python worker's `integrations.py`). A deployment may run MCP servers of its own whose steps should read as
+ * "Querying <name>", and may have accounts whose kind decides what else a person can use, said as one more line of
+ * /whoami. Those names and lines come from the deployment's assembly (`register(registry)`), never from core.
+ */
+export interface IntegrationRegistry {
+    /**
+     * An MCP server (its name lower case as Claw's tool names carry it, `mcp__<server>__<verb>`) people see as `shown`;
+     * with `query`, its `get_*` / `list_*` steps read as "Querying <shown>" in progress lines.
+     */
+    addMcpServer(name: string, shown: string, options?: {
+        readonly query?: boolean;
+    }): void;
+    /**
+     * One line of /whoami's connections, after GitHub's: a function of the key's owner (undefined when it could not be
+     * read) and the language of the chat.
+     */
+    addConnectionLine(line: (owner: KeyOwner | undefined, lang: Lang) => string): void;
+}
+/** What a registry holds, as the features that use it read it. */
+export interface Integrations {
+    /** MCP server name (lower case) -> the name people see. */
+    readonly mcpServers: ReadonlyMap<string, string>;
+    /** The servers whose reads a progress line names ("Querying <name>"). */
+    readonly queryServers: ReadonlySet<string>;
+    readonly connectionLines: readonly ((owner: KeyOwner | undefined, lang: Lang) => string)[];
+}
+/** A registry, and what has been registered in it. */
+export declare function integrationRegistry(): IntegrationRegistry & Integrations;
+/** No integrations: the public build names no deployment's services. */
+export declare const noIntegrations: Integrations;

package/dist/types/plugins/key-revoker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Deleting a person's own key when they unlink (the Python worker's `safe.revoke_own_key`: authenticate with the key,
+ * find its id, delete it). Best effort: the link is removed whatever this answers.
+ */
+export interface KeyRevoker {
+    /** True when the key was deleted; false on any failure (the caller tells the person to delete it themselves). */
+    revoke(key: string): Promise<boolean>;
+}
+/** Nothing to revoke at: every revoke reports that the key is still there. */
+export declare const noKeyRevoker: KeyRevoker;

package/dist/types/plugins/model-refusal-policy.d.ts

@@ -0,0 +1,25 @@
+import type { Lang } from "../locales/lang.js";
+/**
+ * A turn the model gateway refused for a reason the person can fix (the Python worker's `apim_key`: no key bound for
+ * the model, or one the gateway no longer accepts). The turn engine asks the policy whether the answer is such a
+ * refusal; if it is, the turn runs once more on the fallback model (when one is configured), the answer is led by
+ * `fallbackLead`, and when there is no fallback or it fails too the person is told `guidance` instead of a raw error.
+ */
+export interface ModelRefusal {
+    /** Which refusal, in the policy's own words ("missing", "invalid", ...). */
+    readonly kind: string;
+}
+export interface ModelRefusalPolicy {
+    /**
+     * Whether the turn's whole answer is such a refusal. `failed` is how Claw ended the turn: undefined while not known
+     * (the live view: the whole message has to be the error), true (it is the error text, beginning with it is enough),
+     * false (Claw says it succeeded, so it is an answer).
+     */
+    classify(answer: string, failed: boolean | undefined): ModelRefusal | undefined;
+    /** What the person is told instead of the refused answer (markdown, in `lang`). */
+    guidance(refusal: ModelRefusal, lang: Lang): string;
+    /** The line in front of an answer the fallback model gave (markdown, in `lang`). */
+    fallbackLead(refusal: ModelRefusal, lang: Lang): string;
+}
+/** No gateway refusal is recognised: every answer is an answer. */
+export declare const noModelRefusalPolicy: ModelRefusalPolicy;

package/dist/types/plugins/route-extension.d.ts

@@ -0,0 +1,27 @@
+/**
+ * An HTTP route a deployment adds to the worker's server (the Python worker's `POST /primus-claw-agent/on-behalf`:
+ * a request a person's coordinator sends into the person's own 1:1 chat). The runtime's server mounts every extension
+ * it is given; the extension is built by the deployment's assembly, with whatever core services it needs.
+ *
+ * The body is unvalidated: the extension reads it through its own schema. The response body is JSON.
+ */
+import type { JsonValue } from "../json.js";
+export interface RouteRequest {
+    /** Header names lower case. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The bearer token of the Authorization header ("" when there is none). */
+    readonly bearer: string;
+    readonly body: unknown;
+}
+export interface RouteResponse {
+    readonly status: number;
+    readonly body: JsonValue;
+}
+export interface RouteExtension {
+    readonly method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Absolute path, e.g. "/personal-agent/on-behalf". */
+    readonly path: string;
+    handle(request: RouteRequest): Promise<RouteResponse>;
+}
+/** No extensions: the server has only its own routes. */
+export declare const noRouteExtensions: readonly RouteExtension[];

package/dist/types/plugins/token-exchange.d.ts

@@ -0,0 +1,36 @@
+import { type Result } from "../result.js";
+/**
+ * Short-lived tokens that act as a person, from an identity service's token exchange (RFC 8693; the Python worker's
+ * `exchange.ExchangeClient`). The person's channel identity is traded for a token; nothing long-lived is stored. A
+ * person with no confirmed binding gets `not_bound` and is offered a one-time binding link (`bindingRequest`).
+ */
+export interface NotBound {
+    readonly kind: "not_bound";
+}
+/** The exchange could not be done (service down, client rejected, malformed reply); `reason` is status and code only. */
+export interface ExchangeFailed {
+    readonly kind: "exchange_failed";
+    readonly reason: string;
+}
+/** No exchange is configured in this deployment. */
+export interface ExchangeUnavailable {
+    readonly kind: "exchange_unavailable";
+}
+export type ExchangeError = NotBound | ExchangeFailed | ExchangeUnavailable;
+/** A one-time link that binds this channel user to the account that confirms it. */
+export interface BindingRequest {
+    readonly confirmUrl: string;
+    readonly expiresInSeconds: number;
+}
+export interface TokenExchange {
+    /** False when no exchange is configured: the flows that need one are not offered. */
+    readonly enabled: boolean;
+    /** A token acting as the person bound to channel user `userId`. */
+    tokenFor(userId: string): Promise<Result<string, ExchangeError>>;
+    /** The confirm link for `userId`; `email`, when the channel supplied one, restricts who can confirm it. */
+    bindingRequest(userId: string, email: string): Promise<Result<BindingRequest, ExchangeFailed | ExchangeUnavailable>>;
+    /** Forget the cached token and the cached "not bound" of `userId` (after the person says they confirmed). */
+    invalidate(userId: string): void;
+}
+/** No exchange configured. */
+export declare const noTokenExchange: TokenExchange;