@primusclaw/personal-agent 0.1.0 → 0.2.0

package/dist/types/assistant/chat.d.ts

@@ -158,9 +158,9 @@ export declare class AssistantChat {
     /**
      * `/stop`: interrupts what the assistant is doing this moment; a task is stopped by name. `onlyMessage`: interrupt only while
      * Claw's running turn answers that message (a Stop card's turn, read just before the interrupt goes); false, with nothing said
-     * or interrupted, when it does not.
+     * or interrupted, when it does not. Said in `lang`, the chat's.
      */
-    stop(_userId: string, credential: string, conversation: Conversation, onlyMessage?: string): Promise<boolean>;
+    stop(_userId: string, credential: string, conversation: Conversation, onlyMessage?: string, lang?: Lang): Promise<boolean>;
 }
 /** The session a chat is attached to as the assistant is told it: its text and yes/no fields, each text clipped. */
 export declare function attachedOf(attached: JsonObject | null): JsonObject | null;

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

@@ -42,11 +42,16 @@ export declare function confirmWriteOf(event: Event): ConfirmWrite | undefined;
  */
 export declare function suggestedRepliesOf(event: Event, text: string, styleOn: boolean, lang?: Lang): SuggestedReply[];
 export interface RemoteNotice {
-    readonly kind: "done" | "needs_you" | "error";
+    /** `resolved`: a question a terminal asked no longer waits here (answered there, or given up); `resolved` says which. */
+    readonly kind: "done" | "needs_you" | "error" | "resolved";
     readonly sessionId: string;
     readonly ask: Event | undefined;
     readonly machine: string;
     readonly agent: string;
+    readonly resolved?: {
+        readonly actionId: string;
+        readonly by: string;
+    };
 }
 /** What an `assistant.say` says of an agent session on the person's machine, or undefined for any other message. */
 export declare function remoteNoticeOf(event: Event): RemoteNotice | undefined;

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

@@ -21,6 +21,12 @@ export interface Capability {
     /** What it is, in a few words. */
     readonly zh: string;
     readonly en: string;
+    /**
+     * What it is in a handful of words, for the line of a group's help that says what else a 1:1 chat with the bot does ("" : not
+     * named there). Only a capability a group does not show has one.
+     */
+    readonly dmZh: string;
+    readonly dmEn: string;
     /** One sentence a person would type for it ("" : it is done with buttons). */
     readonly sayZh: string;
     readonly sayEn: string;

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

@@ -12,7 +12,7 @@ export declare const NATURAL_PATTERNS: readonly (readonly [string, readonly RegE
 /**
  * `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
+ * account, feedback), and asking it to introduce itself, read as help. `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.
  */

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

@@ -3,6 +3,11 @@
  * 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[];
+/**
+ * Asking the bot to introduce itself, read as help in a group only: there the answer is said to everyone, and help is what knows
+ * what the bot does (a group's session is shared and knows nothing of it). In a 1:1 chat the words stay the person's, as before.
+ */
+export declare const INTRODUCE: 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

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

@@ -6,7 +6,7 @@
 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"];
+export declare const PERSONAL_ONLY_COMMANDS: readonly ["link", "unlink", "resume", "timezone", "quiet", "pause", "brief", "repo", "sessions", "agents", "agent", "lang", "approvals"];
 /**
  * `/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.

package/dist/types/config/settings.d.ts

@@ -1,3 +1,4 @@
+import type { GroupContextSettings } from "../group-context/buffer.js";
 import type { SecretsSourceName } from "../ports/secret-source.js";
 import type { LinkLimits } from "../ports/store/link.js";
 /**
@@ -36,6 +37,11 @@ export interface Settings {
     readonly onBehalfUsers: ReadonlySet<string>;
     /** TEAMS_OBSERVE_USERS (lower-cased): who may turn on observing a group chat. */
     readonly observeUsers: ReadonlySet<string>;
+    /**
+     * TEAMS_GROUP_CONTEXT_MESSAGES (30; 0 off), TEAMS_GROUP_CONTEXT_HOURS (4), TEAMS_GROUP_CONTEXT_CHARS (500): the recent
+     * messages of a group chat kept in memory as background for an @mention.
+     */
+    readonly groupContext: GroupContextSettings;
     /** TEAMS_LIMIT_<OPERATION>: the per-person limits of operations that act with someone's authority. */
     readonly sensitiveLimits: ReadonlyMap<string, Limit>;
     /** TEAMS_LINK_MAX_FAILURES_PER_USER (5) / TEAMS_LINK_MAX_FAILURES_GLOBAL (100) / TEAMS_LINK_ATTEMPT_WINDOW_SECONDS (600). */

package/dist/types/feedback/reporting.d.ts

@@ -1,4 +1,5 @@
 import type { IdentityLookup } from "../plugins/identity-lookup.js";
+import type { ClawAssistantPort } from "../ports/claw/assistant.js";
 import type { Clock } from "../ports/clock.js";
 import type { Logger } from "../ports/logger.js";
 import type { RouteBase } from "../ports/routing.js";
@@ -8,6 +9,9 @@ import type { FeedbackService, ReportResult } from "./service.js";
 export interface ReportingDeps {
     readonly service: FeedbackService;
     readonly sessions: Pick<SessionRepository, "getSession">;
+    readonly assistant: Pick<ClawAssistantPort, "session">;
+    /** A 1:1 chat that talks to the person's assistant: its turns are in the assistant's session, which the report's scene is then. */
+    readonly assistantOn: (userId: string) => boolean;
     /** The person's Claw credential if they have one; never asks them for it (`undefined`: not linked). */
     readonly credential: (sender: UserRef) => Promise<string | undefined>;
     readonly identity: IdentityLookup;
@@ -19,6 +23,12 @@ export declare class FeedbackReporting {
     private readonly deps;
     constructor(deps: ReportingDeps);
     file(route: RouteBase, text: string): Promise<void>;
+    /**
+     * The session whose turns the report shows: the one the chat talks to. A 1:1 chat with the assistant on talks to the assistant's
+     * session (as a thumb's vote is cast there, `thumbs.ts`), so its turns are the ones reported, not the plain chat session's. When the
+     * assistant's session cannot be read, the report goes without turns rather than with another session's.
+     */
+    private sessionOf;
     /** What the channel gave, and for what is missing, what the key's platform says; a slow or failed lookup is skipped. */
     private reporterOf;
 }

package/dist/types/group-context/buffer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The recent messages of a group chat, as background for the next time someone @mentions the bot there.
+ *
+ * A channel hands the bot a group message that does not @mention it only where the chat granted that (Teams: the
+ * resource-specific permission ChatMessage.Read.Chat). Without it nothing reaches `record` and the bot works exactly as
+ * before. With it, each such message is kept in this worker's memory only: never answered, never stored, never logged,
+ * masked as an outbound message is before it is kept, cut to `messageChars`, the sender's display name and the words
+ * alone (no files). A chat keeps its newest `messages`, none older than `maxAgeSeconds`; the whole chat is dropped when
+ * the bot is removed from it, when it says `/context off`, or once its newest message is that old. When someone
+ * @mentions the bot, `background` gives what is kept, marked as untrusted history, for the turn to send before what they
+ * wrote.
+ */
+import type { Clock } from "../ports/clock.js";
+import type { Logger } from "../ports/logger.js";
+import type { GroupContextRepository } from "../ports/store/group-context.js";
+import type { InboundMessage } from "../ports/surface.js";
+/** How much a group's context keeps (the deployment's TEAMS_GROUP_CONTEXT_* settings). */
+export interface GroupContextSettings {
+    /** The most messages kept per chat; 0 turns the feature off (nothing is kept). */
+    readonly messages: number;
+    /** How old a kept message may get. */
+    readonly maxAgeSeconds: number;
+    /** The longest text kept of one message (code points). */
+    readonly messageChars: number;
+}
+export declare const DEFAULT_GROUP_CONTEXT: GroupContextSettings;
+/** The most chats kept at once: past it, the chat that heard nothing for longest is dropped. */
+export declare const MAX_CHATS = 2000;
+export interface GroupContextDeps {
+    readonly settings: GroupContextSettings;
+    readonly clock: Clock;
+    /** Credentials and the like masked out, as in an outbound message. */
+    readonly mask: (text: string) => string;
+    readonly off: GroupContextRepository;
+    readonly log: Logger;
+}
+export declare class GroupContext {
+    private readonly deps;
+    /** Per chat, oldest first; a Map keeps chats in the order they last heard something (oldest first). */
+    private readonly chats;
+    constructor(deps: GroupContextDeps);
+    get enabled(): boolean;
+    /** A group message not addressed to the bot: kept, never answered. */
+    record(message: InboundMessage): void;
+    /** The person edited a kept message: the new words replace the old (nothing when it is not kept). */
+    edit(chatId: string, messageId: string, newText: string): void;
+    /** A kept message was deleted: it is no longer shown. */
+    remove(chatId: string, messageId: string): void;
+    /** The bot was removed from the chat, or the chat turned the context off: all of it is dropped. */
+    forget(chatId: string): void;
+    /** Drops what has grown too old in every chat (a timer runs it, so a quiet chat does not keep its words). */
+    sweep(): void;
+    /** `/context off`: kept off for the chat (stored), and what was kept is dropped at once. */
+    turnOff(chatId: string): void;
+    /** `/context on`. */
+    turnOn(chatId: string): void;
+    isOff(chatId: string): boolean;
+    /** How many messages the chat has kept now (never what). */
+    count(chatId: string): number;
+    /** How many chats have something kept (for a test or a gauge; never what). */
+    get size(): number;
+    /** The chat's kept messages as background for a turn ("" none, or the chat turned it off). */
+    background(chatId: string): string;
+    private cleaned;
+    private fresh;
+}

package/dist/types/group-context/command.d.ts

@@ -0,0 +1,11 @@
+import type { MessageInterceptor } from "../ports/routing.js";
+import type { GroupContext } from "./buffer.js";
+/** `/context on | off | status`, said to the bot in a group; with 开/关/状态 as well. */
+export type ContextVerb = "on" | "off" | "status" | "usage";
+/** The command's verb, `usage` for a malformed one, undefined when the text is not this command. */
+export declare function parseContext(text: string): ContextVerb | undefined;
+/**
+ * `/context on|off|status` in a group, read before the account check: anybody in the chat may turn it off or on (it is
+ * the chat's, not one person's), and off drops what was kept at once.
+ */
+export declare function contextInterceptor(context: GroupContext): MessageInterceptor;

package/dist/types/group-context/index.d.ts

@@ -0,0 +1,3 @@
+export { GROUP_CONTEXT_TEXT, groupContextText } from "../locales/group-context.js";
+export * from "./buffer.js";
+export * from "./command.js";

package/dist/types/index.d.ts

@@ -17,6 +17,7 @@ export { INTENT_PROMPT, MODE_PROMPT } from "./locales/review-github.js";
 export * from "./typed-answer/index.js";
 export * from "./understanding/index.js";
 export * from "./locales/index.js";
+export * from "./group-context/index.js";
 export * from "./observe/index.js";
 export * from "./plugins/index.js";
 export * from "./ports/crypto.js";
@@ -66,6 +67,7 @@ export * from "./review/index.js";
 export * as remoteDomain from "./remote/index.js";
 export * as remoteView from "./remote-view/index.js";
 export { RemoteAgents } from "./remote/remote-agents.js";
+export { TerminalApprovalsCommand } from "./remote/approvals-command.js";
 export type { RemoteContext, RemoteErrors, RemoteGuard, RemoteSettings } from "./remote/context.js";
 export { ConnectorSetup, setupFrom } from "./remote/connector/setup.js";
 export { CredentialUnavailable as FollowCredentialUnavailable } from "./remote/follow/follower.js";

package/dist/types/locales/assistant-chat.d.ts

@@ -1,13 +1,13 @@
 export declare const assistantChatText: import("./catalog.js").Catalog<{
     unavailable: string;
     rejected: string;
-    stopFailed: string;
-    stopped: string;
-    notBusy: string;
-    stopHint: string;
     notTaken: string;
     clawRefused: string;
     anImage: string;
     notUnderstood: string;
     filesOnly: string;
+    stopFailed: string;
+    stopped: string;
+    notBusy: string;
+    stopHint: string;
 }>;

package/dist/types/locales/connector-reasons.d.ts

@@ -53,6 +53,7 @@ export declare const connectorReasonText: import("./catalog.js").Catalog<{
     terminal_gone: string;
     terminal_switched: string;
     terminal_input_failed: string;
+    terminal_input_unseen: string;
     terminal_input_unconfirmed: string;
     terminal_input_unavailable: string;
     empty_prompt: string;

package/dist/types/locales/group-context.d.ts

@@ -0,0 +1,44 @@
+export declare const groupContextText: import("./catalog.js").Catalog<{
+    turnedOff: (p: {
+        bot: string;
+    }) => string;
+    turnedOn: (p: {
+        bot: string;
+    }) => string;
+    isOn: (p: {
+        bot: string;
+        count: string;
+    }) => string;
+    isOnEmpty: (p: {
+        bot: string;
+    }) => string;
+    isOff: (p: {
+        bot: string;
+    }) => string;
+    unavailable: string;
+    usage: (p: {
+        bot: string;
+    }) => string;
+}>;
+export declare const GROUP_CONTEXT_TEXT: {
+    turnedOff: (p: {
+        bot: string;
+    }) => string;
+    turnedOn: (p: {
+        bot: string;
+    }) => string;
+    isOn: (p: {
+        bot: string;
+        count: string;
+    }) => string;
+    isOnEmpty: (p: {
+        bot: string;
+    }) => string;
+    isOff: (p: {
+        bot: string;
+    }) => string;
+    unavailable: string;
+    usage: (p: {
+        bot: string;
+    }) => string;
+};

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

@@ -7,7 +7,18 @@ export declare const remoteAgentText: import("./catalog.js").Catalog<{
     notEnabled: string;
     offline: string;
     outdated: string;
-    stillWorking: string;
+    queuedBehind: (p: {
+        n: number;
+    }) => string;
+    queueFull: (p: {
+        n: number;
+    }) => string;
+    queueDropped: (p: {
+        n: number;
+    }) => string;
+    queuedRefused: (p: {
+        reason: string;
+    }) => string;
     stopFirst: string;
     notAttached: string;
     approvalInactive: string;

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

@@ -3,8 +3,15 @@ export declare const routingText: import("./catalog.js").Catalog<{
     notConnected: string;
     onlyChats: string;
     stillWorking: string;
-    oneWaiting: string;
-    stoppedNextRuns: string;
+    queuedBehind: (p: {
+        n: number;
+    }) => string;
+    queueFull: (p: {
+        n: number;
+    }) => string;
+    queueDropped: (p: {
+        n: number;
+    }) => string;
     unlinkAsk: string;
     nothingRunning: string;
     noSessions: string;

package/dist/types/locales/terminal-approvals.d.ts

@@ -0,0 +1,44 @@
+export declare const terminalApprovalText: import("./catalog.js").Catalog<{
+    title: string;
+    who: (p: {
+        agent: string;
+        host: string;
+        project: string;
+    }) => string;
+    asksRun: string;
+    asksEdit: (p: {
+        path: string;
+    }) => string;
+    asksPlan: string;
+    asksQuestion: string;
+    asksTool: (p: {
+        tool: string;
+    }) => string;
+    oldText: string;
+    newText: string;
+    alwaysOption: (p: {
+        name: string;
+    }) => string;
+    firstAnswerWins: string;
+    tooLong: string;
+    questionOf: (p: {
+        n: number;
+        of: number;
+    }) => string;
+    optionYes: string;
+    optionSession: string;
+    optionNo: string;
+    optionNoStop: string;
+    optionPlanApprove: string;
+    optionPlanKeep: string;
+    answeredInTerminal: string;
+    noLongerWaiting: string;
+    answeredInTerminalLine: string;
+    noLongerWaitingLine: string;
+    approvalsOn: string;
+    approvalsOff: string;
+    approvalsTurnedOn: string;
+    approvalsTurnedOff: string;
+    approvalsUsage: string;
+    approvalsUnavailable: string;
+}>;

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

@@ -39,6 +39,10 @@ export interface ClawRemoteAgentsPort {
     /** A one-time pairing code inside the command line that uses it. */
     pair(key: ClawCredential): Promise<RemotePairing>;
     revoke(key: ClawCredential, connectorId: string): Promise<void>;
+    /** Whether the questions the caller's terminals ask come to them (`GET /approvals`; on unless they turned it off). */
+    approvals(key: ClawCredential): Promise<boolean>;
+    /** Turn them on or off (`PUT /approvals`); answers the setting as Claw stored it. */
+    setApprovals(key: ClawCredential, enabled: boolean): Promise<boolean>;
     createSession(key: ClawCredential, session: NewRemoteSession): Promise<RemoteSession>;
     sessions(key: ClawCredential): Promise<RemoteSession[]>;
     session(key: ClawCredential, sessionId: string): Promise<RemoteSession>;

package/dist/types/ports/store/group-context.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The group chats that turned the recent-messages context off (`/context off`). Only the switch is kept: the messages
+ * themselves are never stored (they live in the worker's memory, `group-context/buffer.ts`).
+ */
+export interface GroupContextRepository {
+    /** True when the chat turned the context off. */
+    contextOff(conversationId: string): boolean;
+    /** Turns it off (`off` true) or back on. */
+    setContextOff(conversationId: string, off: boolean): void;
+}

package/dist/types/ports/store/index.d.ts

@@ -13,6 +13,7 @@ import type { ApprovalRepository } from "./approvals.js";
 import type { AssistantButtonRepository, AssistantCardRepository, AssistantMessageRepository } from "./assistant.js";
 import type { FeedbackRepository } from "./feedback.js";
 import type { GithubConfirmationRepository, ReviewDelegationRepository } from "./github.js";
+import type { GroupContextRepository } from "./group-context.js";
 import type { IdempotencyRepository } from "./idempotency.js";
 import type { LinkRepository } from "./link.js";
 import type { NotifySubscriptionRepository } from "./notify.js";
@@ -31,6 +32,7 @@ export interface StorePort {
     readonly notifySubs: NotifySubscriptionRepository;
     readonly approvals: ApprovalRepository;
     readonly observe: ObserveRepository;
+    readonly groupContext: GroupContextRepository;
     readonly assistantCards: AssistantCardRepository;
     readonly assistantButtons: AssistantButtonRepository;
     readonly assistantMessages: AssistantMessageRepository;
@@ -52,6 +54,7 @@ export type * from "./approvals.js";
 export type * from "./assistant.js";
 export type * from "./feedback.js";
 export type * from "./github.js";
+export type * from "./group-context.js";
 export type * from "./idempotency.js";
 export type * from "./link.js";
 export type * from "./notify.js";

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

@@ -91,6 +91,10 @@ export interface RemotePermission {
     readonly options: readonly unknown[];
     readonly expiresAt: number;
     readonly state: RemotePermissionState;
+    /** The message the card went out as, when the channel said its id ("" none): a card a terminal's answer ends is edited there. */
+    readonly messageId: string;
+    /** For a question a terminal asks: the whole `remote.ask`, so the card can be drawn again with its content (null otherwise). */
+    readonly ask: Readonly<Record<string, unknown>> | null;
 }
 export interface NewRemotePermission {
     readonly userId: string;
@@ -99,6 +103,8 @@ export interface NewRemotePermission {
     readonly tool: string;
     readonly options: readonly unknown[];
     readonly expiresAt: number;
+    /** For a question a terminal asks: the whole `remote.ask` (see {@link RemotePermission.ask}). */
+    readonly ask?: Readonly<Record<string, unknown>>;
 }
 export interface RemotePermissionRepository {
     /** Recorded before it is shown; false when this request already has a row. */
@@ -108,7 +114,12 @@ export interface RemotePermissionRepository {
     pendingRemotePermissions(userId: string, sessionId: string): RemotePermission[];
     waitingRemoteSessions(userId: string): Set<string>;
     forgetRemotePermission(sessionId: string, actionId: string): void;
-    closeRemotePermission(sessionId: string, actionId: string, state: RemotePermissionState, options?: {
+    /** Record the message the card went out as. */
+    setRemotePermissionMessage(sessionId: string, actionId: string, messageId: string): void;
+    closeRemotePermission(sessionId: string, actionId: string, state: RemotePermissionState, 
+    /** `onlyIfState`: only from that state (instead of only from pending). */
+    options?: {
         readonly onlyIfPending?: boolean;
+        readonly onlyIfState?: RemotePermissionState;
     }): boolean;
 }

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

@@ -12,6 +12,11 @@ export declare class Deliveries {
     send(userId: string, reference: JsonObject, event: JsonObject): Promise<boolean>;
     /** An approval's card, recorded BEFORE it goes out (atomically: the turn may show the same approval) and WITH its envelope. */
     private sendApproval;
+    /**
+     * A development environment session's own card: a request that waits on the person (its card), or the end of a terminal's
+     * question (its card edited). Undefined when the message goes on as words.
+     */
+    private remoteCard;
     /** What the assistant said (or a work item that needs the person and was not said). */
     private sendSaid;
     /** The client locale of the message being handled ("" for a push or a sweep: Python CLIENT_LOCALE's default). */
@@ -39,6 +44,12 @@ export declare class Deliveries {
      * or it ran out while held), undefined when it offers nothing that can be answered (its words go as they are).
      */
     private sendRemoteAsk;
+    /**
+     * A question a terminal asked no longer waits here (`resolved`): answered at the terminal, or given up. Its card is edited in
+     * place to say so, without its buttons, and a click on it is told the same. True when that is done (or there is nothing to
+     * do: answered here already); false when the card cannot be found or edited, and the notice's own line is said instead.
+     */
+    private endTerminalAsk;
     /** A run started by a chat turn is named by what the person asked there (Claw names it by its session's first message). */
     namedByPrompt(event: JsonObject): JsonObject;
     /**

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

@@ -92,11 +92,21 @@ export interface AssistantFile {
  * `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";
+    /**
+     * `resolved` (only for a terminal's request, `ask.origin` "terminal"): a request this channel was sent as a card was answered, or stopped
+     * waiting, somewhere else (`resolved`), so a channel that still shows that card marks it so in place; the text says the same in one line
+     * for a channel that does not.
+     */
+    kind: "done" | "needs_you" | "error" | "resolved";
     session_id: string;
     machine: string;
     agent: string;
     ask?: AssistantRemoteAsk;
+    /** With `kind: "resolved"`: which request, and who ended it (`terminal`, or `timeout`, `session_end`, `connector_restart` when nobody did). */
+    resolved?: {
+        action_id: string;
+        by: string;
+    };
 }
 /** A permission request a development environment's agent waits on (`permissionRequest`), as its connector posted it. */
 export interface AssistantRemoteAsk {
@@ -110,6 +120,25 @@ export interface AssistantRemoteAsk {
     }>;
     /** When the connector stops waiting for an answer (it refuses the request then); absent when it did not say. */
     expires_at?: string;
+    /**
+     * `terminal`: asked in a terminal on the machine (a conversation its person started there), whose own prompt stays open: whichever
+     * answer comes first is taken. Absent for a session opened through Claw.
+     */
+    origin?: "terminal";
+    /** A terminal's request: what kind of prompt it is (`execute`, `edit`, `question`, `switch_mode` for a plan, `mcp`, `other`). */
+    kind?: string;
+    /**
+     * A terminal's request: what it would do, whole, as its connector posted it (the command, the edit, the plan, the question): a channel
+     * shows all of it, or offers only the options that refuse. Absent when it was too large to carry whole; the options are then only
+     * those that refuse.
+     */
+    input?: unknown;
+    /** A terminal's request: the conversation's title (its project or session name) and the folder it runs in; plain one-line text. */
+    title?: string;
+    cwd?: string;
+    /** A terminal's question asked as several cards: which this is (from 0), and how many. */
+    question_index?: number;
+    question_count?: number;
 }
 /** Something the assistant chose to say to the user. */
 export interface AssistantSayPayload extends AssistantEventBase {

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

@@ -155,6 +155,40 @@ export interface RemoteSessionNew {
     takeover: boolean;
 }
 export declare function parseSessionNew(body: unknown): Parsed<RemoteSessionNew>;
+/**
+ * Approvals a terminal asks for, carried to the phone (`POST /v1/remote-agents/connectors/:cid/terminal-sessions`).
+ *
+ * A coding agent its person started in their own terminal asks there before it runs a command, edits a file, leaves plan mode or
+ * puts a multiple-choice question. A connector whose hook sees such a prompt opens (or finds) one session per terminal conversation
+ * (`ref`, the agent's own conversation id) and posts each prompt on it as a `permissionRequest`, with
+ * `data.origin` {@link REMOTE_ORIGIN_TERMINAL_HOOK}; the owner answers it as any other, with a `decision`. The terminal keeps its own
+ * prompt: whichever answer comes first is the one the agent takes, and the connector says which (`permission_resolved.by`).
+ *
+ * Such a session carries nothing else: no prompt, no turn, no mode. It is not one of the sessions a user opens, so it neither counts
+ * against {@link REMOTE_AGENT_LIMITS.maxActiveSessionsPerUser} nor is closed to make room for one.
+ */
+export declare const REMOTE_ORIGIN_TERMINAL_HOOK = "terminal_hook";
+/** The only commands a terminal-hook session takes: an answer, and closing it. */
+export declare const TERMINAL_HOOK_COMMANDS: readonly RemoteCommandType[];
+export declare const TERMINAL_SESSION_LIMITS: {
+    /** Terminal-hook sessions one user may open per minute, across their machines (a new terminal conversation opens one). */
+    readonly opensPerMinute: 30;
+    /** Characters of a session's title (the conversation's name, or the start of its first prompt). */
+    readonly maxTitleChars: 80;
+};
+export interface RemoteTerminalSessionOpen {
+    agent_id: string;
+    /** The agent's own id of the conversation open in the terminal. */
+    ref: string;
+    cwd: string;
+    /** The conversation's name, or the start of its first prompt; empty when the connector has neither. */
+    title: string;
+}
+export declare function parseTerminalSessionOpen(body: unknown): Parsed<RemoteTerminalSessionOpen>;
+/** The owner's switch for approvals from terminals (`GET`/`PUT /v1/remote-agents/approvals`). On unless they turned it off. */
+export declare function parseApprovalsSetting(body: unknown): Parsed<{
+    enabled: boolean;
+}>;
 /**
  * Hiding conversations of a machine from its owner's lists (`POST /v1/remote-agents/connectors/:cid/hidden`), and the
  * listing that leaves them out (`GET /v1/remote-agents/connectors`, `?hidden=include` to list them too). Nothing on the

package/dist/types/remote/approvals-command.d.ts

@@ -0,0 +1,8 @@
+import type { ClawRemoteAgentsPort } from "../ports/claw/remote-agents.js";
+import type { CommandHandler, CommandRoute } from "../ports/routing.js";
+export declare class TerminalApprovalsCommand implements CommandHandler {
+    private readonly claw;
+    readonly name = "approvals";
+    constructor(claw: Pick<ClawRemoteAgentsPort, "approvals" | "setApprovals">);
+    run(route: CommandRoute, args: string): Promise<boolean>;
+}