@primusclaw/personal-agent 0.2.0 → 0.3.0

package/dist/index.js

@@ -9557,7 +9557,8 @@ You will get a short code; send \`/link CODE\` here (valid for 10 minutes, works
 `,
     tooManyWrong: (p) => `Too many wrong codes. Wait ${String(p.minutes)} minute${p.minutes !== 1 ? "s" : ""} and try again.`,
     linkingPaused: "Linking is paused for a few minutes because of too many wrong codes. Please try again later.",
-    badCode: "That code is not valid or has expired. Get a new one on the console page."
+    badCode: "That code is not valid or has expired. Get a new one on the console page.",
+    identityRefused: "That needs you in person: confirm your identity once on this card, then ask again."
   },
   zh: {
     linkSteps: (p) => `${p.lead}\u8981\u4F7F\u7528 ${p.bot}\uFF0C\u8BF7\u5148\u8FDE\u4E0A\u4F60\u7684 PrimusClaw \u8D26\u53F7\u3002\u6253\u5F00\u8FD9\u4E2A\u9875\u9762\uFF0C\u767B\u5F55\u540E\u9009\u62E9 Connect Microsoft Teams\uFF1A
@@ -9579,7 +9580,8 @@ ${p.page}
 `,
     tooManyWrong: (p) => `Too many wrong codes. Wait ${String(p.minutes)} minute${p.minutes !== 1 ? "s" : ""} and try again.`,
     linkingPaused: "Linking is paused for a few minutes because of too many wrong codes. Please try again later.",
-    badCode: "That code is not valid or has expired. Get a new one on the console page."
+    badCode: "That code is not valid or has expired. Get a new one on the console page.",
+    identityRefused: "\u8FD9\u4E00\u6B65\u9700\u8981\u4F60\u672C\u4EBA\uFF1A\u5728\u8FD9\u5F20\u5361\u7247\u4E0A\u786E\u8BA4\u4E00\u6B21\u8EAB\u4EFD\uFF0C\u7136\u540E\u518D\u8BF4\u4E00\u904D\u5C31\u884C\u3002"
   }
 });
 var LINK_KEY_NAME = "PrimusClaw Teams";
@@ -9682,6 +9684,28 @@ var Credentials = class {
     await chat.say(linkText.in("en").platformDown);
     return void 0;
   }
+  /**
+   * After an answer of the assistant that was refused for want of a confirmed identity (`needs_identity`: a person whose chats
+   * run on their key because they never confirmed it asked for something only they may do, such as a review as them): the card
+   * that confirms it, unless the person has confirmed by now. Nothing when chats do not run on the exchange, or it cannot be
+   * asked. Never before that: connecting a machine and the rest of what a key may do are not held behind it.
+   */
+  async identityAfterRefusal(chat) {
+    if (this.chatExchange === void 0) return false;
+    const token = await this.chatExchange.tokenFor(chat.sender.id);
+    if (token.ok || token.error.kind !== "not_bound") return false;
+    return this.sendIdentityCard(chat, linkText.in(chat.lang()).identityRefused);
+  }
+  /** The binding card with `lead`; false (nothing sent) when the identity service gives no link: a key's owner is not sent the `/link` steps. */
+  async sendIdentityCard(chat, lead) {
+    const request = await this.deps.exchange.bindingRequest(chat.sender.id, chat.sender.email);
+    if (!request.ok) {
+      this.deps.logger.warn("binding request failed", { kind: request.error.kind });
+      return false;
+    }
+    await chat.send(this.views.binding(request.value.confirmUrl, lead));
+    return true;
+  }
   /** A fresh credential per call when chats run on exchanged tokens (they expire); undefined: the key as it is. */
   provider(userId, key) {
     return this.chatExchange === void 0 ? void 0 : () => this.fresh(userId, key);
@@ -12973,16 +12997,58 @@ var PersonalRouter = class {
   text;
   stopPress;
   showHere;
+  /** A person's bound id is read and kept one message at a time, so a late lookup of an earlier token never wins. */
+  boundLock = new KeyedLock();
   async route(event, chat) {
     const { store, subscriptions } = this.ctx.deps;
     const userId = chat.sender.id;
     store.references.saveReference(userId, wireOf(event));
     if (event.type === "action" && event.invoke) store.members.notePersonalClick(userId);
-    await this.backfill(userId);
-    if (subscriptions !== void 0 && store.links.getKey(userId) !== null) await subscriptions.ensure(userId);
+    if (store.links.getKey(userId) !== null) {
+      await this.backfill(userId);
+      if (subscriptions !== void 0) await subscriptions.ensure(userId);
+    } else {
+      await this.boundLock.run(userId, () => this.reachBound(userId));
+    }
     if (event.type === "message") await this.message(event, chat);
     else await this.click(event, chat);
   }
+  /**
+   * A person with no link whose chats run on an exchanged token (bound at the identity service): their Claw user id is
+   * read with the token and their subscription made with it, as a link's are, so their 1:1 chat reaches the assistant
+   * from this message on (the assistant reaches only a person whose Claw user id and subscription it knows).
+   *
+   * The id is read again whenever the token is not the one it was read with (tokens last minutes, so at most once a token):
+   * a person who rebinds to another account is followed to it, and one no longer bound is forgotten, so the assistant
+   * never keeps answering for an account the person no longer holds (nor for one whose owner a new token cannot tell yet).
+   * A subscription is made or mended only with a token whose owner is the id kept.
+   */
+  async reachBound(userId) {
+    const { credentials, owners } = this.ctx;
+    const { store, subscriptions } = this.ctx.deps;
+    if (!credentials.onExchange) return;
+    let token;
+    try {
+      token = await credentials.background(userId);
+    } catch (error) {
+      if (error instanceof CredentialUnavailable) return;
+      throw error;
+    }
+    if (token === void 0) {
+      store.links.forgetBound(userId);
+      return;
+    }
+    const kept = store.links.boundClawUser(userId, token);
+    if (kept?.current !== true) {
+      const clawUserId = await owners.userIdOf(token);
+      if (clawUserId === void 0) {
+        if (kept !== null) store.links.forgetBound(userId);
+        return;
+      }
+      store.links.setBoundClawUser(userId, clawUserId, token);
+    }
+    if (subscriptions !== void 0) await subscriptions.ensure(userId, token);
+  }
   /** Linked before the Claw user id was kept: it is read now. */
   async backfill(userId) {
     const { links: links2 } = this.ctx.deps.store;
@@ -19398,8 +19464,27 @@ var Deliveries = class {
       return this.sendRemoteAsk(userId, conversation, event, remote);
     return void 0;
   }
-  /** What the assistant said (or a work item that needs the person and was not said). */
+  /**
+   * What the assistant said, then, when its turn was refused something for want of a confirmed identity (`needs_identity`) and
+   * this is the person's own chat (a group binding's key has `#`), the card that confirms it. A card that could not be sent never
+   * makes the message undelivered.
+   */
   async sendSaid(userId, conversation, event) {
+    const sent = await this.sendSaidWords(userId, conversation, event);
+    const offer = this.deps.identityAfterRefusal;
+    if (sent && offer !== void 0 && event["type"] === "assistant.say" && event["needs_identity"] === true && !userId.includes("#")) {
+      try {
+        await offer(userId, conversation, str5(event["turn_message_id"]) || str5(event["event_id"]));
+      } catch (error) {
+        this.deps.logger.warn("the identity card after a refused answer could not be sent", {
+          error: error instanceof Error ? error.name : "unknown"
+        });
+      }
+    }
+    return sent;
+  }
+  /** What the assistant said (or a work item that needs the person and was not said). */
+  async sendSaidWords(userId, conversation, event) {
     const card = await this.remoteCard(userId, conversation, event);
     if (card !== void 0) return card;
     let words3 = workEventText(parseWorkItem2(event["item"]) ?? null, event["text"]);
@@ -20071,13 +20156,17 @@ var Subscriptions = class {
       return "no_subscription";
     }
   }
-  /** Make sure this linked person has a subscription (with the assistant's types when it is on). Never throws. */
-  async ensure(aadId) {
+  /**
+   * Make sure this person has a subscription (with the assistant's types when it is on). It is made and mended with
+   * `credential` when one is given (a person with no link, whose chats run on an exchanged token), else with their linked
+   * key. Never throws.
+   */
+  async ensure(aadId, credential2) {
     try {
+      const key = credential2 ?? this.store.links.getKey(aadId);
       let found = this.store.notifySubs.getNotifySub(aadId);
-      if (found !== null && this.assistantOnFor(aadId)) found = await this.reconcile(aadId, found.subscriptionId);
+      if (found !== null && this.assistantOnFor(aadId)) found = await this.reconcile(aadId, found.subscriptionId, key);
       if (found !== null) return;
-      const key = this.store.links.getKey(aadId);
       if (key === null || !this.store.notifySubs.claimNotifyAttempt(aadId, RETRY_SECONDS)) return;
       await this.create(aadId, key);
     } catch (error) {
@@ -20117,8 +20206,7 @@ var Subscriptions = class {
    * at, and mended with one PATCH, at most every UPGRADE_RETRY_SECONDS. One Claw no longer has is forgotten (the caller makes a new
    * one); one Claw refuses even the assistant's types (400, 404) takes the person back to sessions (`types_version` 0).
    */
-  async reconcile(aadId, subscriptionId) {
-    const key = this.store.links.getKey(aadId);
+  async reconcile(aadId, subscriptionId, key) {
     if (key === null || !this.store.notifySubs.claimNotifyAttempt(aadId, UPGRADE_RETRY_SECONDS)) {
       return this.store.notifySubs.getNotifySub(aadId);
     }

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

@@ -25,6 +25,7 @@ export declare const linkText: import("./catalog.js").Catalog<{
     }) => string;
     linkingPaused: string;
     badCode: string;
+    identityRefused: string;
 }>;
 /** The name the linked key has in SaFE (the console creates it under this name). */
 export declare const LINK_KEY_NAME = "PrimusClaw Teams";

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

@@ -30,7 +30,26 @@ export interface LinkRepository {
     setClawUserId(userId: string, clawUserId: string): void;
     /** Linked before the Claw user id was kept (or the lookup failed at link time). */
     needsClawUserId(userId: string): boolean;
+    /**
+     * The link's Claw user id; for a person with no link, the one kept for their binding at the identity service (their
+     * chats run on exchanged tokens). The assistant reaches either by it.
+     */
     clawUserIdOf(userId: string): string | null;
+    /**
+     * A person with no link, bound at the identity service: the Claw user id kept for them, and whether it was read with
+     * `credential` (the token they write with now); null when none is kept.
+     */
+    boundClawUser(userId: string, credential: string): {
+        clawUserId: string;
+        current: boolean;
+    } | null;
+    /**
+     * Keep the Claw user id read with `credential` for a bound person with no link. When it names another account than the
+     * one kept, their subscription (made with the earlier account's token) is forgotten, to be made again with this one.
+     */
+    setBoundClawUser(userId: string, clawUserId: string, credential: string): void;
+    /** A person with no link is no longer bound: forget their kept Claw user id and their subscription. */
+    forgetBound(userId: string): void;
     /** Every linked person, in a stable order. */
     linkedUsers(): string[];
     userForClawUser(clawUserId: string): string | null;

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

@@ -17,8 +17,14 @@ export declare class Deliveries {
      * 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). */
+    /**
+     * What the assistant said, then, when its turn was refused something for want of a confirmed identity (`needs_identity`) and
+     * this is the person's own chat (a group binding's key has `#`), the card that confirms it. A card that could not be sent never
+     * makes the message undelivered.
+     */
     private sendSaid;
+    /** What the assistant said (or a work item that needs the person and was not said). */
+    private sendSaidWords;
     /** The client locale of the message being handled ("" for a push or a sweep: Python CLIENT_LOCALE's default). */
     private clientLocale;
     /** The chat is an agent's window now: direct chat is on for the person and the chat is attached to a session. */

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

@@ -74,4 +74,10 @@ export interface ProactiveDeps {
      * handled (`/resume`, quiet hours off) answer in their client's language; a push or a sweep reads none. Default: none.
      */
     readonly requestScope?: RequestScope;
+    /**
+     * After an assistant message whose turn was refused for want of a confirmed identity (`needs_identity`), in the person's own
+     * chat: the card that confirms it (`Credentials.identityAfterRefusal`), once per turn (`turn`: the message the turn answers,
+     * else the say's own id; a later say of the same turn replaces the first and carries the field too). Default: none.
+     */
+    readonly identityAfterRefusal?: (userId: string, conversation: Conversation, turn: string) => Promise<void>;
 }

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

@@ -171,6 +171,11 @@ export interface AssistantSayPayload extends AssistantEventBase {
     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;
+    /**
+     * Present when the turn was refused something only the person may do because their message came with a key, not with a confirmed
+     * identity (`not_attended`): a channel that can bind the person's identity offers it with this message; one that cannot ignores it.
+     */
+    needs_identity?: true;
 }
 /** 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 {

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

@@ -25,6 +25,15 @@ export declare class Credentials {
     get onExchange(): boolean;
     /** What to call Claw with for this person, or undefined after they were told what to do (`ask`). */
     credential(chat: Chat, ask?: boolean): Promise<string | undefined>;
+    /**
+     * After an answer of the assistant that was refused for want of a confirmed identity (`needs_identity`: a person whose chats
+     * run on their key because they never confirmed it asked for something only they may do, such as a review as them): the card
+     * that confirms it, unless the person has confirmed by now. Nothing when chats do not run on the exchange, or it cannot be
+     * asked. Never before that: connecting a machine and the rest of what a key may do are not held behind it.
+     */
+    identityAfterRefusal(chat: Chat): Promise<boolean>;
+    /** The binding card with `lead`; false (nothing sent) when the identity service gives no link: a key's owner is not sent the `/link` steps. */
+    private sendIdentityCard;
     /** A fresh credential per call when chats run on exchanged tokens (they expire); undefined: the key as it is. */
     provider(userId: string, key: string): CredentialProvider;
     /** The person's exchanged token, else `fallback` (a turn can outlive a 10-minute token: each Claw call asks again). */

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

@@ -134,7 +134,8 @@ export interface RemoteChat {
 }
 /** The person's notification subscription in Claw (Python `subscriptions.Subscriptions`); undefined when notifications are off. */
 export interface Subscriptions {
-    ensure(userId: string): Promise<void>;
+    /** Made or mended with `credential` when given (a person with no link: their exchanged token), else the linked key. */
+    ensure(userId: string, credential?: string): Promise<void>;
     /** Before the key is revoked: Claw needs it to delete the subscription. */
     remove(userId: string, key: string): Promise<void>;
 }

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

@@ -15,8 +15,21 @@ export declare class PersonalRouter {
     private readonly text;
     private readonly stopPress;
     private readonly showHere;
+    /** A person's bound id is read and kept one message at a time, so a late lookup of an earlier token never wins. */
+    private readonly boundLock;
     constructor(ctx: RouterContext, sets: CommandSets, text: PersonalText);
     route(event: InboundMessage | InboundAction, chat: Chat): Promise<void>;
+    /**
+     * A person with no link whose chats run on an exchanged token (bound at the identity service): their Claw user id is
+     * read with the token and their subscription made with it, as a link's are, so their 1:1 chat reaches the assistant
+     * from this message on (the assistant reaches only a person whose Claw user id and subscription it knows).
+     *
+     * The id is read again whenever the token is not the one it was read with (tokens last minutes, so at most once a token):
+     * a person who rebinds to another account is followed to it, and one no longer bound is forgotten, so the assistant
+     * never keeps answering for an account the person no longer holds (nor for one whose owner a new token cannot tell yet).
+     * A subscription is made or mended only with a token whose owner is the id kept.
+     */
+    private reachBound;
     /** Linked before the Claw user id was kept: it is read now. */
     private backfill;
     private message;

package/dist/types/subscriptions/subscriptions.d.ts

@@ -51,8 +51,12 @@ export declare class Subscriptions {
      * mended first and the user id filled in, so what is said is the state after trying. Never throws.
      */
     reachable(aadId: string): Promise<Unreachable>;
-    /** Make sure this linked person has a subscription (with the assistant's types when it is on). Never throws. */
-    ensure(aadId: string): Promise<void>;
+    /**
+     * Make sure this person has a subscription (with the assistant's types when it is on). It is made and mended with
+     * `credential` when one is given (a person with no link, whose chats run on an exchanged token), else with their linked
+     * key. Never throws.
+     */
+    ensure(aadId: string, credential?: string): Promise<void>;
     private create;
     /**
      * With the assistant on, the recorded subscription must be there in Claw, enabled and asking for the assistant's events: looked

package/package.json

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