@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/proactive/quiet.d.ts

@@ -0,0 +1,27 @@
+/**
+ * When something unasked may reach a person (teams_agent/proactive.py): quiet hours in their time zone, an explicit pause, and the
+ * expiry of an approval or a remote agent's permission request that was held.
+ */
+import { type Prefs } from "../ports/store/index.js";
+/** When an approval event carries no usable `expires_at`: fail closed, a short life. */
+export declare const APPROVAL_DEFAULT_SECONDS = 600;
+/** When a pushed permission request carries no usable `expires_at`. */
+export declare const PERMISSION_DEFAULT_SECONDS = 600;
+/** The person's time zone when it is one this runtime knows, else DEFAULT_TIMEZONE (Python's `zone_of`). */
+export declare function zoneOf(prefs: Pick<Prefs, "timezone">): string;
+/** Minutes since local midnight of `epochSeconds` in `zone`. */
+export declare function localMinutes(epochSeconds: number, zone: string): number;
+/** Is `now` inside the daily window [start, end) in `zone`? A window may wrap midnight (22:00-08:00); start == end is none. */
+export declare function inQuiet(now: number, zone: string, start: string, end: string): boolean;
+export type Muted = "paused" | "quiet";
+/** Why nothing may be pushed right now, or undefined when it may. */
+export declare function muted(prefs: Prefs, now: number): Muted | undefined;
+/**
+ * An ISO time with an offset, as epoch seconds; undefined for anything else (Python's `datetime.fromisoformat` on a "Z" or
+ * "+hh:mm" time: a time without an offset cannot be compared safely).
+ */
+export declare function isoSeconds(raw: unknown): number | undefined;
+/** When an approval event runs out: its `approval.expires_at`, else APPROVAL_DEFAULT_SECONDS from now. */
+export declare function approvalExpiry(event: Readonly<Record<string, unknown>>, now: number): number;
+/** When a pushed permission request runs out: its `expires_at`, at most an hour on; else PERMISSION_DEFAULT_SECONDS from now. */
+export declare function remoteAskExpiry(ask: Readonly<Record<string, unknown>>, now: number): number;

package/dist/types/proactive/release.d.ts

@@ -0,0 +1,24 @@
+import type { ProactiveDeps } from "./deps.js";
+import type { Proactive } from "./proactive.js";
+/** Held assistant messages sent one by one when the person can be reached; the older ones are one line. */
+export declare const ASSISTANT_RELEASE_MAX = 10;
+/** Held remote agent messages sent one by one; the older ones are one line. */
+export declare const REMOTE_RELEASE_MAX = 5;
+export declare class Release {
+    private readonly deps;
+    private readonly proactive;
+    constructor(deps: ProactiveDeps, proactive: Proactive);
+    /** Deliver what was held for every person who may be reached now. Run on a timer; one person's failure does not stop the rest. */
+    releaseDue(): Promise<void>;
+    /** Send what was held for this person; on a failure everything is held again for the next sweep, and the error goes on. */
+    release(userId: string): Promise<void>;
+    private sort;
+    private sendAll;
+    private digest;
+    /**
+     * Send again every approval card that was recorded and never reached the chat (its worker died between recording it and the
+     * send). Quiet hours do not apply: a card is recorded only once it was due. At least once: a second copy is answered "already
+     * answered". Returns how many were sent.
+     */
+    resendUnsentApprovals(): Promise<number>;
+}

package/dist/types/proactive/said-memory.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The assistant's messages this process sent lately that a later one may add to (`amends`) or take the place of (`replaces`):
+ * event id -> (the channel's message id, the event). In memory: after a restart an addition is sent as a message of its own.
+ * Shared by every delivery path of one process (teams_agent/proactive.py `_SAID`).
+ */
+import type { JsonObject } from "../json.js";
+import type { MessageId } from "../ports/surface.js";
+export declare const SAID_MAX = 512;
+export interface SaidMessage {
+    readonly messageId: MessageId;
+    readonly event: JsonObject;
+}
+export declare class SaidMessages {
+    private readonly max;
+    private readonly said;
+    constructor(max?: number);
+    get(eventId: string): SaidMessage | undefined;
+    /** Remember an `assistant.say` sent as `messageId` (nothing for another event, one without an id, or no message id). */
+    remember(event: JsonObject, messageId: MessageId | undefined): void;
+    set(eventId: string, said: SaidMessage): void;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * What reaches a person unasked, as views (the arguments of teams_agent/render.py event_card, digest_card, approval_card,
+ * item_approval_card and item_question_card, one for one), and the pure helpers their cards share: the one link a card may open,
+ * a clock time in the person's zone, and the line that names which work item asks.
+ */
+import type { JsonObject } from "../json.js";
+import type { Lang } from "../locales/lang.js";
+import type { PublicErrors } from "../public-error/public-errors.js";
+/** The longest summary a notice shows. */
+export declare const NOTICE_SUMMARY_MAX = 280;
+/** What Claw sends as an approval's target is at most this long; a bash command is shown whole. */
+export declare const TARGET_MAX = 300;
+/** At a phone's width 300 characters are about 6 lines; the card keeps four and the clip marks the rest. */
+export declare const TARGET_LINES = 4;
+/** The longest work item title a request card names. */
+export declare const ITEM_TITLE_MAX = 80;
+/** A Claw event (run.completed, run.failed, another notice) as a card (render.event_card). */
+export interface RunEventModel {
+    /** The event, made public first (`publicRunEvent`). */
+    readonly event: JsonObject;
+    readonly publicBaseUrl: string;
+}
+/** Everything held back while the person was away, as one card (render.digest_card). */
+export interface DigestModel {
+    readonly events: readonly JsonObject[];
+    /** Approvals that ran out while held, and were refused. */
+    readonly expiredApprovals: number;
+    readonly publicBaseUrl: string;
+}
+/** An approval.requested event of a run (render.approval_card), or of a work item (render.item_approval_card). */
+export interface ProactiveApprovalModel {
+    readonly event: JsonObject;
+    readonly publicBaseUrl: string;
+    /** When it runs out, epoch seconds, shown as HH:MM in `zone`. */
+    readonly expiresAt: number;
+    /** An IANA time zone name. */
+    readonly zone: string;
+}
+/** A work item's question to its person (render.item_question_card). */
+export interface ItemQuestionModel {
+    readonly event: JsonObject;
+}
+declare module "../ports/surface.js" {
+    interface ViewMap {
+        digest: DigestModel;
+        itemApproval: ProactiveApprovalModel;
+        itemQuestion: ItemQuestionModel;
+        proactiveApproval: ProactiveApprovalModel;
+        runEvent: RunEventModel;
+    }
+}
+/** The absolute https URL of a Claw-relative link; null for anything else (never an arbitrary URL). */
+export declare function openUrl(link: unknown, publicBaseUrl: string): string | null;
+/** `datetime.fromtimestamp(at, zone).strftime("%H:%M")`. */
+export declare function clockText(at: number, zone: string): string;
+/** The language of a work item's request card: the model's summary, else the item's title (what the person asked for). */
+export declare function itemLang(event: Readonly<Record<string, unknown>>): Lang;
+/** The line that names the work item a request comes from: "Task #13: title" ("task") or "... asks you" ("asks"). */
+export declare function itemRequestLabel(event: Readonly<Record<string, unknown>>, key: "task" | "asks", lang: Lang): string;
+/** A target Claw sent, masked for credential shapes and clipped (what a work item's approval card shows). */
+export declare function maskedTarget(target: unknown): string;
+/**
+ * A run.failed event as it may be shown: what Claw says about a failed run may be the raw error, so a title with the shape of
+ * internal detail is dropped and such a summary is withheld to the log under a reference the person is told. Other events are
+ * returned as they are. `looksInternal` is the public-error check of a service error or internal detail.
+ */
+export declare function publicRunEvent(event: JsonObject, errors: PublicErrors, looksInternal: (text: unknown) => boolean): JsonObject;

package/dist/types/protocol/claw-api/assistant-events.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The outbound events an assistant produces, and the payloads they carry: what a
+ * notification subscription that lists their types receives (`POST` to its URL), and
+ * what the API builds in `packages/api/src/assistant/outbound.ts`.
+ *
+ * They are not run events: there is no session, task or link to report, only
+ * something the assistant said, so they do not reuse `NotificationPayload`. They
+ * say nothing about who receives them -- a subscription asks for the type and
+ * the receiver decides how a person sees it.
+ */
+export declare const ASSISTANT_EVENT_TYPES: readonly ["assistant.say", "work_item.needs_you", "assistant.action"];
+export type AssistantEventType = (typeof ASSISTANT_EVENT_TYPES)[number];
+/** What a receiver needs to draw the item a message is about; derived from the item's state, never written by a model. */
+export interface AssistantItemSnapshot {
+    item_id: string;
+    seq: number;
+    title: string;
+    board_state: string;
+    result_version: number;
+    can_accept: boolean;
+}
+interface AssistantEventBase {
+    /** The id of the stored message: the receiver's dedup key. */
+    event_id: string;
+    occurred_at: string;
+    user_id: string;
+    text: string;
+    item?: AssistantItemSnapshot;
+}
+/**
+ * A channel action put to the person rather than run (`channel_action` when their message was not its command typed whole).
+ * A channel that can draw a button shows one for `/{name} {args}` and runs it, as if the person typed it, only when that person
+ * presses it, under the same checks as an `assistant.action` (a message it sent for them, an action that message declared).
+ * A channel that cannot shows the text, which tells the person the command to type.
+ */
+export interface AssistantConfirmAction {
+    name: string;
+    args: string;
+    /** The id of the turn's message in Claw. */
+    message_id: string;
+    /** What the channel called that message when it sent it. */
+    channel_message_id: string;
+}
+/**
+ * A source the message cites (`assistant/citations.ts`): `n` is the number its text writes as `[n]`. Each comes from a lookup the turn
+ * made (a web page it found or read, an object of the user's GitHub), never from the model's own words. `title` is a plain line,
+ * already cut and stripped of markup, but what someone else wrote: shown as text only.
+ */
+export interface AssistantSaySource {
+    n: number;
+    url: string;
+    title: string;
+    kind: "web" | "github_pr" | "github_issue" | "github_repo" | "github_check" | "github_file" | "board";
+}
+/**
+ * A write the router proposed and Claw holds until the person answers it (`assistant/schedules.ts`): creating or cancelling a
+ * scheduled task. A channel that can draw buttons shows the message's text with two: one that lets it through and one that does
+ * not, each calling `POST /v1/assistant/confirmations/{confirmation_id}/decision` as that person (`allow` or `deny`). A channel that
+ * cannot shows the text, which tells the person the command that lets it through (`批准 #{ref}`).
+ */
+export interface AssistantConfirmWrite {
+    confirmation_id: string;
+    /** The short id the person may type back. */
+    ref: string;
+    /** `devenv_send`: an instruction for an agent on the person's own machine (`assistant/devenv-tools.ts`). */
+    kind: "trigger_create" | "trigger_cancel" | "github_comment" | "devenv_send" | "devenv_hide";
+    /** What the button that lets it through says, in the language of the text. */
+    allow_label: string;
+    expires_at: string;
+}
+/**
+ * A file a work item's worker delivered (`deliver_file`, `deliver_text`), or one the router wrote (`deliver_text`), for a channel to
+ * offer as a download. The download is Claw's own link, `GET /v1/sessions/{session_id}/deliveries/{id}`, which answers only the
+ * signed-in owner of that session (the item's worker session, or the assistant's own, both the user's). `data_base64` is a small image itself (`DELIVERY_INLINE_TYPES`, at most
+ * `DELIVERY_INLINE_MAX_BYTES`), for a channel that shows it without fetching the link.
+ */
+export interface AssistantFile {
+    /** The work item whose worker delivered it; absent for a file the router wrote itself (`text-delivery.ts`). */
+    item_id?: string;
+    session_id: string;
+    id: string;
+    name: string;
+    size: number;
+    content_type: string;
+    data_base64?: string;
+}
+/**
+ * What a development environment session's own message is about (`assistant/remote-items.ts`): one of the three things a session is
+ * ever said for, so a channel can draw it and tell it apart. `done`: the instruction finished; `needs_you`: the agent waits on the person
+ * (`ask`: the permission request, for a channel to put to them with its options as buttons, answered as an attached chat's card is, a
+ * decision on the session); `error`: the instruction failed, was refused, or its session ended before it finished. `machine` and
+ * `agent` are what the connector reported, and `ask`'s words what the agent wrote: untrusted text, shown as text only.
+ */
+export interface AssistantRemoteNotice {
+    kind: "done" | "needs_you" | "error";
+    session_id: string;
+    machine: string;
+    agent: string;
+    ask?: AssistantRemoteAsk;
+}
+/** A permission request a development environment's agent waits on (`permissionRequest`), as its connector posted it. */
+export interface AssistantRemoteAsk {
+    action_id: string;
+    tool: string;
+    /** The options the agent offered, ids as the agent gave them: the only answers a decision may carry. */
+    options: Array<{
+        optionId: string;
+        name: string;
+        kind: string;
+    }>;
+    /** When the connector stops waiting for an answer (it refuses the request then); absent when it did not say. */
+    expires_at?: string;
+}
+/** Something the assistant chose to say to the user. */
+export interface AssistantSayPayload extends AssistantEventBase {
+    type: "assistant.say";
+    confirm_action?: AssistantConfirmAction;
+    /** Present only when the message cites any (`CLAW_ASSISTANT_CITATIONS`); a receiver that does not read it shows the text alone. */
+    sources?: AssistantSaySource[];
+    /**
+     * Present only when the router suggested any (`CLAW_ASSISTANT_SUGGESTED_REPLIES`): up to three short replies the user may send
+     * next, each one plain line. A channel shows them as buttons that send the words as the user's message; one that cannot ignores them.
+     */
+    suggested_replies?: string[];
+    confirm_write?: AssistantConfirmWrite;
+    /** Files the user gets with the message (a worker's deliveries, `deliveries.ts`): one download each. */
+    files?: AssistantFile[];
+    /** Present on a development environment session's own message: which session, and which of its three kinds of news. */
+    remote?: AssistantRemoteNotice;
+    /**
+     * The `event_id` of an earlier message of this turn that this one adds to: the system's start notice of an item, after which the
+     * router's words belong in that same message. A channel that still has that message shows it with these words added (its current
+     * text, a blank line, this text); one that does not shows this as a message of its own. When the start notice took the place of the
+     * server's "on it" line (`replaces`), this names that line's id: the message the channel shows, whose current text is the notice.
+     */
+    amends?: string;
+    /**
+     * The `event_id` of the router's first message of this turn, which this one takes the place of: a turn speaks to the user once, and a
+     * later say of it (the answer after a quick "查一下", or a correction) is that whole message again. A channel that still has that message
+     * shows this text in its place; one that does not shows this as a message of its own.
+     */
+    replaces?: string;
+    /** The message id of the turn a system notice answers or a router say belongs to (what an `amends` or a `replaces` is matched by). */
+    turn_message_id?: string;
+}
+/** The system's own message, sent when an item has needed the user for a while and nobody has said so. */
+export interface WorkItemNeedsYouPayload extends AssistantEventBase {
+    type: "work_item.needs_you";
+    fallback: true;
+    item: AssistantItemSnapshot;
+    /** Present when what the item waits for is a write its worker holds for the person (`AssistantHeldWrite`). */
+    held_write?: AssistantHeldWrite;
+}
+/**
+ * A write an item's worker holds for the person (`assistant/holds.ts`), on the message that says so: what a card needs to put it to them
+ * beside the text. The person answers it as any held call is answered: a `decision` (`allow` or `deny`, with `tool_use_id`) on the
+ * worker's session, `POST /v1/sessions/{session_id}/messages`; the channel that got the item's `approval.requested` draws the same card
+ * from that. Every field is what Claw recorded of the hold, never a model's words; `action` is in the person's language.
+ */
+export interface AssistantHeldWrite {
+    item_id: string;
+    /** The worker's session, where the decision is sent. */
+    session_id: string;
+    tool_use_id: string;
+    /** What it would do, in plain words (`approvalAction`). */
+    action: string;
+    expires_at?: string;
+}
+/**
+ * A review the person asked of someone else, handed to the channel that carried their message (`review_start` with a reviewer, when
+ * that message declared `channel_context.handoffs: ["review_for_other"]`). It runs on the reviewer's own credentials, which only that
+ * channel holds, so the channel starts it itself (`POST /v1/assistant/reviews` with the reviewer's token and key) and answers the
+ * person's message about it, in one message (the router says nothing about it). Every field is the router's call as Claw checked it: the
+ * reviewer is someone the channel listed with this message, each pull request is one the person's message names. `requester_note` is the
+ * person's own message, to quote to the reviewer as untrusted. `handoff_id` names the record Claw kept of it: the channel echoes it as
+ * `handoff_id` in that request, which then starts once and merges only if `merge` is true (Claw reads the record, not the request); how it
+ * merges is the reviewer's own review setting's, as for a review asked of them in the chat, and the route's answer says so per item.
+ */
+export interface AssistantReviewHandoff {
+    handoff_id: string;
+    reviewer: {
+        user_id: string;
+        name: string;
+    };
+    prs: Array<{
+        owner: string;
+        repo: string;
+        number: number;
+    }>;
+    merge: boolean;
+    requester_note: string;
+    /**
+     * What the router said in the same turn before handing the review over (another question of the person's answered), in order. Held
+     * and never delivered on its own (`say-hold.ts`), so the channel's one answer carries it: the channel adds it to that answer. Absent
+     * when nothing was said.
+     */
+    held_says?: string[];
+}
+/** The name an `assistant.action` carries when it is a handoff rather than one of the channel's own commands. */
+export declare const REVIEW_HANDOFF_ACTION = "review_for_other";
+/**
+ * A setting the channel offered beside the user's message, to be run by that channel as if the user typed it
+ * (`channel_action`); or, with `review` (and the action named `review_for_other`), a review asked of someone else, handed to the
+ * channel to start with that person's credentials. The channel runs it only for a message it sent itself (`channel_message_id`), once
+ * per `event_id`.
+ */
+export interface AssistantActionPayload {
+    type: "assistant.action";
+    event_id: string;
+    occurred_at: string;
+    user_id: string;
+    /** The id of the turn's message in Claw. */
+    message_id: string;
+    /** What the channel called that message when it sent it. */
+    channel_message_id: string;
+    action: {
+        name: string;
+        args: string;
+    };
+    review?: AssistantReviewHandoff;
+}
+export type AssistantEventPayload = AssistantSayPayload | WorkItemNeedsYouPayload | AssistantActionPayload;
+export {};

package/dist/types/protocol/claw-api/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./work-items.js";
+export * from "./reviews.js";
+export * from "./assistant-events.js";
+export * from "./notifications.js";
+export * from "./session-events.js";

package/dist/types/protocol/claw-api/notifications.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Outbound notifications as the Claw HTTP API defines them: the subscriptions a user keeps
+ * (`/v1/notification-subscriptions`) and the run and approval events posted to them. The assistant's own events are in
+ * `assistant-events.ts`.
+ *
+ * Types and constants only. The API builds these in `packages/api/src/notifications/outbox.ts`,
+ * `packages/api/src/assistant/holds.ts` and `packages/api/src/routes/notification-subscriptions.ts`.
+ */
+import { type AssistantEventPayload, type AssistantItemSnapshot } from "./assistant-events.js";
+export declare const NOTIFICATION_RUN_EVENT_TYPES: readonly ["run.completed", "run.failed", "approval.requested"];
+export type NotificationEventType = (typeof NOTIFICATION_RUN_EVENT_TYPES)[number];
+/**
+ * Every type a subscription may list. A new subscription gets `run.completed` and `run.failed` unless it names its own;
+ * `approval.requested` and the assistant's events have to be asked for.
+ */
+export declare const NOTIFICATION_SUBSCRIPTION_EVENT_TYPES: readonly ["run.completed", "run.failed", "approval.requested", "assistant.say", "work_item.needs_you", "assistant.action"];
+/**
+ * What started a run, which narrows run events (`trigger`, `long_run`), and `assistant_item`: an `approval.requested`
+ * that an assistant's work item holds. A new subscription gets `trigger` and `long_run` unless it names its own.
+ */
+export declare const NOTIFICATION_SOURCES: readonly ["trigger", "long_run", "assistant_item"];
+export type NotificationSource = (typeof NOTIFICATION_SOURCES)[number];
+/** One subscription, as listed, created (with its signing `secret`, once) and changed. */
+export interface NotificationSubscription<Time = string> {
+    subscription_id: string;
+    url: string;
+    event_types: string[];
+    sources: string[];
+    enabled: boolean;
+    consecutive_failures: number;
+    created_at: Time;
+}
+/** The part of an `approval.requested` payload that says what is being asked. */
+export interface ApprovalInfo {
+    tool_use_id: string;
+    tool: string;
+    /** Redacted and clipped to 300 characters. */
+    target: string;
+    /** ISO-8601 with an offset: when Brain stops waiting, after which the request is refused. */
+    expires_at: string;
+}
+/** A run event (`run.completed`, `run.failed`) or an `approval.requested`. */
+export interface NotificationPayload {
+    event_id: string;
+    type: NotificationEventType;
+    occurred_at: string;
+    user_id: string;
+    session_id: string;
+    task_id: string;
+    /**
+     * Run events only: the message whose turn this run was (`null` for a task that has none). A client that sent the
+     * message can tell this run's end is that turn's by the id, not by when it ended.
+     */
+    message_id?: string | null;
+    trigger_id: string | null;
+    title: string;
+    summary: string;
+    link: string;
+    /** Present on `approval.requested` only. */
+    approval?: ApprovalInfo;
+    /**
+     * `assistant_item`: an `approval.requested` held by the worker of an assistant's work item, sent only to a subscription
+     * that lists that source. Absent on every other event.
+     */
+    source?: "assistant_item";
+    /** With `source`: the work item that waits, as an assistant event draws it. */
+    item?: AssistantItemSnapshot;
+    /**
+     * With `source`, when what waits is a question (`approval.tool` is `ask_user_question`): what it asks. Answered as a
+     * client answers any question (`messageType: "answer"`), not with a decision.
+     */
+    questions?: HeldQuestion[];
+}
+/** One question of an `ask_user_question`, as a channel shows it: masked and clipped. */
+export interface HeldQuestion {
+    id: string;
+    question: string;
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+    allow_multiple: boolean;
+}
+/** Everything a subscription can be posted. */
+export type OutboundPayload = NotificationPayload | AssistantEventPayload;

package/dist/types/protocol/claw-api/reviews.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Review items as the Claw HTTP API returns them: the reviews `POST /v1/assistant/reviews` started, and what the person
+ * who asked for a review someone else runs may see of it (`GET /v1/work-items/:id` and the stop's answer for that person,
+ * `GET /v1/work-items/asked-of-others`).
+ *
+ * Types only. The API builds these in `packages/api/src/assistant/review-items.ts` and `requester-view.ts`.
+ */
+/** One pull request. */
+export interface PrRef {
+    owner: string;
+    repo: string;
+    number: number;
+}
+/** One review `POST /v1/assistant/reviews` started (`data.items[]`), as its owner is answered. */
+export interface StartedReview {
+    item_id: string;
+    seq: number;
+    title: string;
+    session_id: string;
+    pr: PrRef;
+    /** The turn id of the session's first message (`claw-pending-<id>`), for a caller that follows that turn's stream. */
+    message_id: string | null;
+    /** What the request named that the review does not take (a review asked of someone else runs on their settings). */
+    ignored?: Array<"model" | "effort">;
+    /** The review never merges. */
+    review_only: boolean;
+    /** Present when every merge of this review waits for the acting user's own confirmation, whatever their review mode. */
+    merge_needs_confirmation?: true;
+    /** Present on a review asked of someone else that may merge: the requester's own account merges it once it is approved and green. */
+    merge_by_requester?: true;
+    /** With model choice on: the model the review runs on (null: the deployment's default). Absent with model choice off. */
+    model?: string | null;
+    /** The model it was to run on, which the payer's key could not use. */
+    fell_back_from?: string;
+    /** Present when the item waits for a slot (`reason`: the limit that was full); it starts by itself. Absent: it started. */
+    queued?: {
+        reason: string;
+    };
+}
+/** A review started for someone else, as the person who asked is answered: the session is the reviewer's, so its ids are left out. */
+export type StartedReviewForRequester = Omit<StartedReview, "session_id" | "message_id">;
+/** What the person who asked for a review someone else runs may see of it, and all they see. */
+export interface RequesterView {
+    /** `queued`: made, and waiting for a slot; it starts by itself, and then reads `in_progress`. */
+    status: "queued" | "in_progress" | "waiting_for_reviewer" | "done" | "stopped";
+    pr_url: string | null;
+    verdict: "approve" | "request_changes" | "comment" | null;
+    merged: boolean;
+    /** Only while `status` is `waiting_for_reviewer`, else null. */
+    waiting_for: "confirm_merge" | "confirm_review" | "failed" | "reviewer" | null;
+    /** Open findings the review posted on the pull request; null when it posted none (no record yet). */
+    findings: number | null;
+    /** The first open finding, one line, credentials masked; null when there is none. */
+    note: string | null;
+    /** What the pull request does, in one sentence the review gave with its verdict; null when it gave none. */
+    pr_summary: string | null;
+}
+/** One review the caller asked of someone else (`GET /v1/work-items/asked-of-others`): its id, who reviews it, and the view. */
+export interface AskedOfOther {
+    item_id: string;
+    reviewer: string | null;
+    view: RequesterView;
+}

package/dist/types/protocol/claw-api/session-events.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A session's event stream as the Claw HTTP API serves it: `GET /v1/chat/sessions/:id/messages` as SSE, and the same
+ * history as JSON with `?mode=replay`.
+ *
+ * Types and constants only. The API builds these in `packages/api/src/routes/events.ts`.
+ */
+/**
+ * The SSE event that ends the replayed history and starts the live stream. It carries no `id:`, so it never moves a
+ * client's Last-Event-ID.
+ */
+export declare const HISTORY_COMPLETE_EVENT = "historyComplete";
+/** The `data:` of the `historyComplete` frame. */
+export interface HistoryCompleteData {
+    type: typeof HISTORY_COMPLETE_EVENT;
+    /** The events the history sent. */
+    count: number;
+    /** Older events were not sent; `?history=all`, or `?mode=replay` with `after`/`tail`, reads them. */
+    has_more: boolean;
+}
+/** One stored event of `?mode=replay`, oldest first: the row the SSE stream sends as `id:` and `data:`. */
+export interface SessionReplayRow<Time = string> {
+    event_id: string;
+    /** The stored event's name; `data.type` says what it is to a client. */
+    event_type: string;
+    /** The event, redacted as the stream sends it. */
+    data: unknown;
+    created_at: Time;
+}
+/** `?mode=replay` with `tail`, `limit` or `after`: one window of the history, and whether more remains past its cut. */
+export interface SessionReplayWindow<Time = string> {
+    ok: true;
+    data: Array<SessionReplayRow<Time>>;
+    has_more: boolean;
+}

package/dist/types/protocol/claw-api/work-items.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Work items as the Claw HTTP API returns them: the board (`GET /v1/work-items`), one item
+ * (`GET /v1/work-items/:id`) and the answers of accept, stop and retry
+ * (`POST /v1/work-items/:id/{accept,stop,retry}`).
+ *
+ * Types and constants only. The API builds these from its rows (`packages/api/src/assistant/work-items.ts`);
+ * a client of the API reads them. Timestamps are `Date` where the API builds the object and ISO 8601
+ * strings on the wire, so every type that carries one takes it as a parameter, `string` by default.
+ */
+export declare const BOARD_STATES: readonly ["in_progress", "needs_you", "done"];
+export type BoardState = (typeof BOARD_STATES)[number];
+/** What a worker's report says; the last one is the item's `last_report_kind`. */
+export declare const REPORT_KINDS: readonly ["progress", "waiting", "ready", "answer", "blocked", "failed", "dropped"];
+export type ReportKind = (typeof REPORT_KINDS)[number];
+/** How a `done` item ended. */
+export type WorkItemOutcome = "accepted" | "answered" | "dropped" | "stopped";
+/**
+ * `task`: a worker that reports does it. `review`: a GitHub review on someone's behalf (its `params` say which pull
+ * request, as whom, how). `remote`: an agent on one of the user's own machines.
+ */
+export declare const ITEM_KINDS: readonly ["task", "review", "remote"];
+export type ItemKind = (typeof ITEM_KINDS)[number];
+/** One work item as the board lists it, and as accept, stop and retry answer with it. */
+export interface WorkItemView<Time = string> {
+    item_id: string;
+    seq: number;
+    title: string;
+    summary: string;
+    board_state: BoardState;
+    last_report_kind: ReportKind | null;
+    pending_question: string | null;
+    outcome: WorkItemOutcome | null;
+    result_version: number;
+    accepted_version: number | null;
+    /** A result waits for this person: `board_state` is `needs_you` and the last report was `ready`. */
+    can_accept: boolean;
+    kind: ItemKind;
+    /** What a review was asked with; `{}` for a task. */
+    params: Record<string, unknown>;
+    updated_at: Time;
+}
+/** One entry of an item's history, newest first in `WorkItemDetail.events`. */
+export interface WorkItemEvent<Time = string> {
+    /** A bigint row id, sent as a string. */
+    id: string;
+    /**
+     * `created`, `run_started`, a report kind (`ReportKind`), `accepted` or `stopped`. Kept a string: a client meets kinds
+     * a newer server adds.
+     */
+    kind: string;
+    /** Who wrote it: `worker`, `turn_end`, `sweep`, `watchdog`, `user`, `router`, `policy`, `github`. */
+    source: string;
+    generation: number;
+    run_id: string | null;
+    summary: string | null;
+    question: string | null;
+    /** A `ready` report's result as the worker gave it (`{refs: [{type: "pr", url}], ...}`), the accepted version, or null. */
+    result: unknown;
+    created_at: Time;
+}
+/** `GET /v1/work-items/:id` for the item's owner: the item, where its worker runs, and its latest events. */
+export interface WorkItemDetail<Time = string> extends WorkItemView<Time> {
+    worker_session_id: string;
+    /** The repository the item was bound to, as it was asked (`{url, branch?}`), or null. */
+    repo: unknown;
+    created_at: Time;
+    closed_at: Time | null;
+    events: Array<WorkItemEvent<Time>>;
+}
+/** Why a review item cannot be stopped: its merge is being made, or was made. */
+export type StopRefusal = "merge_in_progress" | "already_merged";
+/** The `error` of a 409 from accept or stop; its `data` is the item as it is now. */
+export type WorkItemDecisionError = "version_mismatch" | "not_acceptable" | "item_closed" | StopRefusal;
+/** The `error` of a 409 from retry; its `data` is the item as it is now. */
+export type RetryRefusal = "not_retryable" | "too_many_active_items" | "session_not_found" | "no_credentials" | "acting_session_unattended";