@primusclaw/personal-agent 0.4.0 → 0.5.0

package/dist/types/approvals/questions.d.ts

@@ -34,3 +34,10 @@ export interface Answers {
  * typed; a choice the card never offered is ignored.
  */
 export declare function answersOf(data: Readonly<Record<string, unknown>>): Answers;
+/**
+ * A message the person typed in the chat while a question card waited, taken as the card's answer. With one question, a
+ * reply that names its options (by label or by number, several of them for a multiple choice) answers with their labels,
+ * as a press on the card would; any other reply is the free answer the card's text box takes. With several questions the
+ * whole reply answers each of them: the agent reads which part answers which. Nothing is skipped.
+ */
+export declare function typedAnswers(questions: readonly CardQuestion[], typed: string): Answers;

package/dist/types/approvals/records.d.ts

@@ -35,8 +35,8 @@ export declare const TURN_DEADLINE_SECONDS: number;
  * the person the turn is for (Python `store.save_approval(sender.aad_id, ...)`).
  */
 export interface TurnApprovalRecords {
-    record(userId: string, sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope): boolean;
-    sent(sessionId: string, toolUseId: string): void;
+    record(userId: string, sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope, questions?: unknown): boolean;
+    sent(sessionId: string, toolUseId: string, cardId?: string): void;
     unsent(sessionId: string, toolUseId: string): void;
 }
 /** The records of the approvals a turn shows (the Python `on_approval`, `on_approval_sent`, `on_approval_unsent`). */

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

@@ -3,6 +3,7 @@
  * channel adapter renders them; `approvalView` (approval-view.ts) is what an approval card says.
  */
 import type { JsonObject } from "../json.js";
+import type { Lang } from "../locales/lang.js";
 import type { CardQuestion } from "./questions.js";
 /** An approval card: the arguments of the Python worker's `render.permission_card`, one for one. */
 export interface ApprovalCardModel {
@@ -27,6 +28,11 @@ export interface QuestionCardModel {
     readonly ownerName: string;
     /** A line under the header: which task asks, or what happened when the card comes back after a click ("" when none). */
     readonly note: string;
+    /**
+     * The card says it can also be answered by a message in the chat: a turn's question, which a typed message answers
+     * (`routing/question-reply.ts`). A work item's question is answered on its card only.
+     */
+    readonly typedReply?: boolean;
 }
 /** What replaces an approval card once it was answered (render.decided_card). */
 export interface ApprovalDecidedModel {
@@ -47,6 +53,8 @@ export interface QuestionAnsweredModel {
     readonly answers: readonly (readonly [string, string])[];
     readonly when: number;
     readonly zone: string;
+    /** Answered by a message typed in the chat (not on the card), in this language: the card says "Answered: <answer>". */
+    readonly replied?: Lang;
 }
 /** An approval card put back after a press that did not go through: the note, then Approve and Deny again. */
 export interface ApprovalAgainModel {

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

@@ -62,7 +62,7 @@ export declare class ReceiptConversation implements Conversation {
     update(id: MessageId, message: OutMessage, options?: UpdateOptions): Promise<void>;
     delete(id: MessageId): ReturnType<Conversation["delete"]>;
     outgoing(message: OutMessage): Envelope;
-    deliver(envelope: Envelope): Promise<void>;
+    deliver(envelope: Envelope): Promise<MessageId | undefined>;
     openStream(replyTo: MessageId, status: string): ReturnType<Conversation["openStream"]>;
     /** What the assistant said beside the handoff, when no text message carried it: said on its own. */
     sayPostscript(): Promise<void>;

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

@@ -28,4 +28,15 @@ export declare const approvalText: import("./catalog.js").Catalog<{
     }) => string;
     questionAsker: string;
     send: string;
+    /** Under a question card's questions: a client that does not show the card can still answer. */
+    questionReply: string;
+    /** The same in a group chat, where only a message that @mentions the bot reaches it. */
+    questionReplyGroup: string;
+    /** A question card once a message typed in the chat answered it. */
+    questionReplied: (p: {
+        answer: string;
+    }) => string;
+    questionRepliedAt: (p: {
+        at: string;
+    }) => string;
 }>;

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

@@ -21,6 +21,8 @@ export declare const turnText: import("./catalog.js").Catalog<{
     thinking: string;
     /** A turn still running when its stream has to close: the answer follows as a message of its own. */
     stillWorking: string;
+    /** A turn whose stream is closed because a card now waits for the person's choice. */
+    awaitingChoice: string;
     interrupted: string;
     /** What a turn the person stopped ends with. */
     stopped: string;

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

@@ -25,12 +25,29 @@ export interface NewApproval {
     readonly expiresAt: number;
     /** The card as it will be published, kept until `approvalSent` so a worker that dies before the send leaves it to the next. */
     readonly envelope?: JsonObject | null;
+    /**
+     * A question card of a turn: its questions as the card's button carries them. Kept so that what the person types next in
+     * the chat can be taken as the answer (`pendingQuestion`).
+     */
+    readonly questions?: readonly JsonObject[] | null;
+}
+/** A question card still waiting for its answer, with what it takes to answer it from a typed message. */
+export interface PendingQuestion {
+    readonly sessionId: string;
+    readonly toolUseId: string;
+    readonly userId: string;
+    /** When it runs out, epoch seconds. */
+    readonly expiresAt: number;
+    /** The questions as recorded with the card (`NewApproval.questions`). */
+    readonly questions: readonly JsonObject[];
+    /** The chat's id of the card ("" when the channel never said it: the card cannot be edited). */
+    readonly cardId: string;
 }
 export interface ApprovalRepository {
     /** True when this call recorded it; false when a card for the same approval was recorded before. */
     saveApproval(approval: NewApproval): boolean;
-    /** The card reached the chat: nothing is left to send. */
-    approvalSent(sessionId: string, toolUseId: string): void;
+    /** The card reached the chat: nothing is left to send. `cardId`: the chat's id of the card, when it said it. */
+    approvalSent(sessionId: string, toolUseId: string, cardId?: string): void;
     /** Its card is being sent right now by this process and may still fail. */
     approvalInFlight(sessionId: string, toolUseId: string): boolean;
     /** The card never reached the chat: take the record back (a row answered meanwhile stays). */
@@ -40,6 +57,11 @@ export interface ApprovalRepository {
     /** A claimed card could not be sent: the next sweep tries again. */
     approvalSendFailed(sessionId: string, toolUseId: string): void;
     getApproval(sessionId: string, toolUseId: string): Approval | null;
+    /**
+     * The newest question card of `userId` in `sessionId` that is still pending, in time, and was recorded with its questions;
+     * null when there is none.
+     */
+    pendingQuestion(sessionId: string, userId: string): PendingQuestion | null;
     /** Move an approval to `state`; true if this call did it (only from 'pending' unless `onlyIfPending` is false). */
     closeApproval(sessionId: string, toolUseId: string, state: ApprovalState, options?: {
         readonly onlyIfPending?: boolean;

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

@@ -336,8 +336,11 @@ export interface Conversation {
     delete(id: MessageId): Promise<Result<void, DeleteUnsupported>>;
     /** The envelope `send` would publish for `message` (masked in a group), built without sending it. */
     outgoing(message: OutMessage): Envelope;
-    /** Publish an envelope `outgoing` built (possibly in another process, from storage). */
-    deliver(envelope: Envelope): Promise<void>;
+    /**
+     * Publish an envelope `outgoing` built (possibly in another process, from storage). The id of the posted message when the
+     * channel said it at once (a direct send); undefined otherwise (a queued send: the message cannot be edited by id).
+     */
+    deliver(envelope: Envelope): Promise<MessageId | undefined>;
     /**
      * A live stream that answers `replyTo` (the person's message), showing `status` as its first informative update.
      * Success means that first update has been sent and the channel took it; refused when the channel cannot stream here

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

@@ -1,4 +1,6 @@
-import type { OutMessage } from "../ports/surface.js";
+import type { LinkRepository } from "../ports/store/link.js";
+import type { OutMessage, UserRef } from "../ports/surface.js";
+import type { TokenExchange } from "../plugins/token-exchange.js";
 import type { Chat } from "./chat.js";
 import type { RouterDeps } from "./deps.js";
 import type { CredentialProvider } from "./features.js";
@@ -12,6 +14,12 @@ export declare const IDENTITY_CARD_INTERVAL_SECONDS: number;
 /** Its kind in the store's notice record (`claimGithubNotice`): the time it was last sent to the person. */
 export declare const IDENTITY_CARD_NOTICE = "identity_card";
 type CredentialDeps = Pick<RouterDeps, "store" | "exchange" | "config" | "logger">;
+/**
+ * What an action of the person's outside a turn (a thumb on an answer) calls Claw with: what their chats run on, so it acts
+ * on the same session as the same Claw user. With chats on the exchange (`exchange` given), the person's exchanged token,
+ * else their linked key; without, the linked key. Undefined when they have neither. Never asks or tells them anything.
+ */
+export declare function chatCredentialOf(links: Pick<LinkRepository, "getKey">, exchange: TokenExchange | undefined): (sender: UserRef) => Promise<string | undefined>;
 /**
  * What Claw is called with for a person, and what a person who has none is told (the Python `Agent._credential`,
  * `_unlinked`, `_connect_identity`, `_binding_card`, `_ask_to_link`, `_background_credential`, `_fresh_credential`).

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

@@ -38,7 +38,7 @@ export interface RouterConfig {
     readonly ownThumbsMobile: boolean;
 }
 /** The repositories the router reads and writes (the W1 store, as far as routing goes). */
-export type RouterStore = Pick<StorePort, "links" | "references" | "prefs" | "members" | "sessions" | "repoHistory" | "turns" | "onboarding" | "idempotency" | "assistantMessages" | "notifySubs" | "reviewDelegation" | "now">;
+export type RouterStore = Pick<StorePort, "links" | "references" | "prefs" | "members" | "sessions" | "repoHistory" | "turns" | "onboarding" | "idempotency" | "assistantMessages" | "notifySubs" | "reviewDelegation" | "approvals" | "now">;
 /** The per-person limits (Python `limits.py`): messages per window and tasks at the same time. */
 export interface RouterLimits {
     readonly maxConcurrentTasks: number;

package/dist/types/routing/personal-text.d.ts

@@ -2,7 +2,7 @@ import type { InboundFile, InboundMessage } from "../ports/surface.js";
 import type { Chat } from "./chat.js";
 import type { CommandTable } from "./command-table.js";
 import type { RouterContext } from "./context.js";
-import type { TurnStarter } from "./turn-start.js";
+import { type TurnStarter } from "./turn-start.js";
 /**
  * A 1:1 message that is not one of the chat's commands, as it goes on (the Python `Agent._text_of`, `_on_text`,
  * `_sent_on`, `_talks_to_agent`, `_session_control`, `_understand`, `_understood`, `_offer_github`, `_attachments`):

package/dist/types/routing/question-reply.d.ts

@@ -0,0 +1,22 @@
+import type { Chat } from "./chat.js";
+import type { RouterContext } from "./context.js";
+/**
+ * A question with less than this left of its wait is not answered from a typed message: Brain may already have stopped
+ * waiting (the card's time is counted from when the worker saw the question, a little after Brain's), and an answer nobody
+ * waits for is dropped. The message then goes on as a new one, as before.
+ */
+export declare const TYPED_ANSWER_MARGIN_SECONDS = 15;
+/** A typed message that may answer the person's waiting question. */
+export interface TypedReply {
+    readonly chat: Chat;
+    readonly text: string;
+    /** The Claw credential of the person, read when there is a question to answer. */
+    readonly credential: () => Promise<string>;
+}
+/**
+ * Answers the question card that waits in the chat's session with `reply.text`: true when it did (the card now says
+ * "Answered: ...", and the message must not go on as a new one); false when there was nothing to answer, or it could not be
+ * answered (the message then goes on as before). Only the person the card was raised for answers it: their own session in
+ * this chat, their own record.
+ */
+export declare function answerWaitingQuestion(ctx: RouterContext, reply: TypedReply): Promise<boolean>;

package/dist/types/routing/turn-start.d.ts

@@ -1,10 +1,22 @@
 import type { Lang } from "../locales/lang.js";
+import type { Logger } from "../ports/logger.js";
 import type { InboundFile } from "../ports/surface.js";
 import type { Chat } from "./chat.js";
 import type { RouterContext } from "./context.js";
 import type { ReviewRunFields, TurnOutcome } from "./turn-runner.js";
 /** Teams on a phone or a tablet: its own Stop under a reply is greyed out, and its own thumbs never reach the worker. */
 export declare function isMobile(clientPlatform: string): boolean;
+/**
+ * The path a message from Teams took: to the person's assistant, to a plain Claw session of their own (the old path, neither
+ * the assistant's nor a work item's), or to a review's turn. Logged so the worker's lines can be counted per path.
+ */
+export type TurnRoute = "assistant" | "legacy" | "review";
+/**
+ * The line for a turn started from Teams: where it came from and which path it took, never its words or any id. One line
+ * per turn: a message to the assistant or to a plain session is one turn, and a review request for several pull requests
+ * starts one review turn (and one line) for each.
+ */
+export declare function logTurnStarted(logger: Logger, clientPlatform: string, group: boolean, route: TurnRoute): void;
 /** A review the review service starts as a turn here (its item runs in Claw already; the turn only follows it). */
 export interface ReviewTurnStart {
     /** The work item Claw made for it ("" none: the turn makes a session of its own). */
@@ -41,6 +53,11 @@ export interface StartTurn {
     readonly sent?: string;
     readonly files?: readonly InboundFile[];
     readonly review?: ReviewTurnStart;
+    /**
+     * The person typed it in the chat (not a button, not a review): while the agent waits on a question card in this chat's
+     * session, it is the answer to that question and starts no turn.
+     */
+    readonly typed?: boolean;
 }
 /**
  * Starting and following a turn (the Python `Agent._start_turn`, `_queue_behind`, `_guarded`, `_record_session`,
@@ -56,6 +73,8 @@ export declare class TurnStarter {
     settled(): Promise<void>;
     /** The turn that runs (its end is `done`), or undefined when none was started (the person was told why). */
     start(request: StartTurn): Promise<RunningTurn | undefined>;
+    /** A typed message the waiting question card of the chat's session took as its answer (`question-reply.ts`). */
+    private answersQuestion;
     private track;
     /** The turn goes to Claw now; its end is `done`. */
     private launch;

package/dist/types/turn/engine/context.d.ts

@@ -70,9 +70,11 @@ export interface TurnHooks {
     /**
      * An approval or question is about to be shown, as `envelope`: false when a card for it is already in a chat (the
      * notification got there first), and the turn then shows none. `expiresIn`: the seconds Brain waits for the answer.
+     * `questions`: a question's questions, as its event carried them (undefined for an approval).
      */
-    readonly onApproval?: (sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope) => boolean | undefined;
-    readonly onApprovalSent?: (sessionId: string, toolUseId: string) => void;
+    readonly onApproval?: (sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope, questions?: unknown) => boolean | undefined;
+    /** The card is in the chat; `cardId`: the chat's id of it, when the chat said it. */
+    readonly onApprovalSent?: (sessionId: string, toolUseId: string, cardId?: string) => void;
     readonly onApprovalUnsent?: (sessionId: string, toolUseId: string) => void;
     /** (session, "started" | "delivered" | "failed", Claw message id or ''). */
     readonly onTurn?: (sessionId: string, what: "started" | "delivered" | "failed", messageId: string) => void;

package/dist/types/turn/engine/run-turn.d.ts

@@ -18,5 +18,7 @@ export interface TurnControls {
     /** The turn is cancelled: no live edit is sent after it, and the run's record is still kept. */
     readonly signal?: AbortSignal;
 }
+/** The id Claw gives a message it queued behind a running turn (`queuedMessageId`, claw/packages/api/src/tasks/chat-run.ts). */
+export declare const QUEUED_MESSAGE_PREFIX = "claw-pending-";
 /** Runs the turn and always leaves the user a message; `controls.onSession` records the session id. */
 export declare function runTurn(ctx: TurnContext, controls: TurnControls): Promise<void>;

package/dist/types/turn/progress/status-message.d.ts

@@ -54,6 +54,8 @@ export declare class StatusMessage<S> {
     private opening;
     private expiry;
     private again;
+    /** The stream being closed because a card waits for the person (`awaitingChoice`). */
+    private choice;
     private preparingTimer;
     private lastText;
     private lastAt;
@@ -80,6 +82,24 @@ export declare class StatusMessage<S> {
     private statusLines;
     /** Close the stream with STILL_WORKING before the chat's limit; the answer, whenever it comes, is a message of its own. */
     private closeInTime;
+    /**
+     * Close the open stream with `line` (after the agent's words in the bubble) while the turn goes on; the answer, whenever it comes, is
+     * a message of its own. Nothing more is sent to the stream once this has begun.
+     */
+    private closeEarly;
+    /**
+     * A card now waits for the person (a question of the agent): it is their turn, so the floating status must not go on
+     * saying "Thinking…" until the chat's limit. An open stream is closed at once with AWAITING_CHOICE, and the answer comes
+     * as a message of its own, as after the limit. Without a stream (the progress message) nothing changes: it has no
+     * spinner. Never fails the turn.
+     */
+    awaitingChoice(): void;
+    /**
+     * Claw queued the message behind a turn it is still running: `notice` closes the stream at once, so it does not say
+     * "Thinking…" for the whole wait. The answer comes as a message of its own, as after the limit. When the stream did not open
+     * after all, `notice` is said as a message. False when there is no stream: the caller says it. Never fails the turn.
+     */
+    queued(notice: string): boolean;
     /** The chat's id of the posted message; undefined when the post failed or its id never came (nothing is edited then). */
     private messageId;
     /**

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

@@ -24,8 +24,8 @@ export interface TurnApprovals {
      * False when a card for this approval is already in a chat: the turn then shows none. `userId`: the person the turn is for,
      * whose approval it is (Python `store.save_approval(sender.aad_id, ...)`).
      */
-    record(userId: string, sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope): boolean;
-    sent(sessionId: string, toolUseId: string): void;
+    record(userId: string, sessionId: string, toolUseId: string, tool: string, expiresIn: number | undefined, envelope: Envelope, questions?: unknown): boolean;
+    sent(sessionId: string, toolUseId: string, cardId?: string): void;
     unsent(sessionId: string, toolUseId: string): void;
 }
 /** What a review turn adds to a chat turn (the review service fills it in). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primusclaw/personal-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The personal agent's channel-neutral core: domain logic, ports and plugin interfaces.",
   "license": "MIT",
   "repository": {