@uniquedivine/tg-sai 0.0.3 → 0.0.5

package/README.md

@@ -5,6 +5,30 @@ Sai Telegram admin audit and bootstrap CLI.
 See file `RUNBOOK.md` for operator setup, profile management, and safe
 execution workflows.
 
+## Install
+
+Requires [Bun](https://bun.sh). No clone needed:
+
+```bash
+bunx @uniquedivine/tg-sai --help          # run once
+bun add -g @uniquedivine/tg-sai           # or install the `tg-sai` command
+tg-sai profile add --name me --login --qr --interactive
+```
+
+Move Sai chats you own to the custody account and add SaiTeam_bot as admin.
+The command is a dry run until you add `--run`:
+
+```bash
+tg-sai ops sai-bootstrap --file chats.txt          # plan only
+tg-sai ops sai-bootstrap --file chats.txt --run    # apply
+```
+
+File `chats.txt` holds one chat ID per line. Ownership transfer needs your
+Telegram 2FA password in `TELEGRAM_PASSWORD` or the saved profile. The owner
+target defaults to the Sai custody account,
+[@SaiTeam_AI](https://t.me/SaiTeam_AI) (user 8274304175), and the bot is
+[@SaiTeam_bot](https://t.me/SaiTeam_bot). `--target-user` overrides the owner.
+
 ## Development
 
 ```bash

package/RUNBOOK.md

@@ -35,8 +35,15 @@ Credential profile behavior:
 
 - Command `tg-sai profile find` reports discovered Telegram credential sources
   without writing profile state.
-- Command `tg-sai profile add` stores a local profile from explicit flags,
-  process environment variables, or one unambiguous discovered source.
+- Bare commands `tg-sai profile` and `tg-sai profile add` show help and configured
+  profiles without saving state or connecting to Telegram.
+- Command `tg-sai profile add` with explicit options stores a local profile from
+  flags, process environment variables, or merged non-conflicting discovered
+  sources. Use a distinct `--name` for another account; without it, explicit
+  options update the active/default profile.
+- Explicit `--qr`, `--phone`, or `--login` starts a fresh account login and
+  ignores discovered/environment sessions and account passwords. App credentials
+  can still come from discovery, environment, or interactive input.
 - Commands `tg-sai profile list`, `tg-sai profile show`, `tg-sai profile use`,
   and `tg-sai profile remove` manage local session profiles.
 
@@ -102,11 +109,12 @@ cd /path/to/tg-sai
 uv sync
 ```
 
-Create file `.env` in the `tg-sai` directory with Telegram app
-credentials:
+Create user-local file `~/.tg-sai/.env` with Telegram app credentials:
 
 ```bash
-cat > .env <<'EOF'
+mkdir -p ~/.tg-sai
+chmod 700 ~/.tg-sai
+cat > ~/.tg-sai/.env <<'EOF'
 TELEGRAM_API_ID=<api id from https://my.telegram.org/apps>
 TELEGRAM_API_HASH=<api hash from https://my.telegram.org/apps>
 EOF
@@ -121,18 +129,20 @@ The session string is generated after QR login.
 Generate the session string and save it directly into a `tg-sai` profile:
 
 ```bash
-tg-sai profile add --name operator --src 1 --login --qr
+tg-sai profile add --name sai-custody --login --qr --interactive
 ```
 
 Scan the QR code in Telegram with **Settings > Devices > Link Desktop Device**.
-After login succeeds, command `tg-sai profile add` saves the generated
-`sessionString` into profile `operator`.
+Scan while signed into the intended account. After login succeeds, this command
+saves its verified identity and session in the separate `sai-custody` profile.
+The existing active profile stays selected. Inspect the result with command
+`tg-sai profile show sai-custody`.
 
 If you generated the session string manually, save it with explicit flags:
 
 ```bash
 tg-sai profile add \
-  --name operator \
+  --name sai-custody \
   --api-id <api id> \
   --api-hash <api hash> \
   --session-string '<session string>'
@@ -142,7 +152,7 @@ Store the Telegram 2FA password in the same profile when ownership transfer is
 needed:
 
 ```bash
-tg-sai profile add --name operator --password '<password>'
+tg-sai profile add --name sai-custody --password '<password>'
 ```
 
 Check the local setup:
@@ -169,17 +179,26 @@ Add a local profile from a numbered source shown by command
 `tg-sai profile find`:
 
 ```bash
-tg-sai profile add --name operator --src 1
+tg-sai profile add --name another-account --src 1
 ```
 
 Command `tg-sai profile add` can store the Telegram 2FA password with flag
 `--password`. Command `tg-sai profile show` redacts stored `apiHash`,
 `sessionString`, and `password`.
 
+For password or metadata updates, `--name` selects an existing saved profile by
+name, handle, numeric user ID, or saved-list index. The update preserves that
+profile's account identity and session without importing environment or discovered
+credentials. An unknown password-update selector fails instead of creating a
+profile. Explicit login/import cannot replace a known profile with a different
+account; use a new name for another account, or remove the old profile first.
+Flag `--src` selects a credential source numbered by `tg-sai profile find`, not
+the saved-profile index printed by `tg-sai profile list`.
+
 Create a blank draft profile for onboarding:
 
 ```bash
-tg-sai profile add --name operator
+tg-sai profile add --name draft
 ```
 
 Blank or partial profiles are useful while collecting `apiId`, `apiHash`, and
@@ -190,7 +209,7 @@ Add a local profile from explicit values:
 
 ```bash
 tg-sai profile add \
-  --name operator \
+  --name another-account \
   --handle <telegram-handle> \
   --user-id <telegram-user-id> \
   --display-name "<display name>"
@@ -202,6 +221,11 @@ List local profiles:
 tg-sai profile list
 ```
 
+Command `tg-sai profile` also shows configured profiles beneath its command
+list. Bare command `tg-sai profile add` explains fresh QR enrollment and how
+named accounts differ from updates to the active profile. Neither changes the
+saved configuration.
+
 Find Sai-related chats visible to the active Telegram session:
 
 ```bash
@@ -308,10 +332,10 @@ different user is the creator.
 
 ## Suggested workflow
 
-1. Run command `just tg-sai profile find` to inspect available Telegram
+1. Run command `tg-sai profile find` to inspect available Telegram
    credential sources.
-2. Run command `just tg-sai profile add --name <name> --src <number>` to
-   save a local profile from discovery output.
+2. Run command `tg-sai profile add --qr` to save a local profile and generate a
+   missing session string.
 3. Run command `tg-sai audit --chat <id>` before writes.
 4. Run command `tg-sai add-bot --chat <id>` or command
    `tg-sai add-owner --chat <id> --target-user <user>` as a dry-run.
@@ -341,3 +365,100 @@ list regular members as admins. This tool uses per-member lookups
 - Emit a reviewable table or JSON artifact for batch dry-runs.
 - Add named rights profiles for bot admin and owner-target admin promotion.
 - Add fixtures for a completed ownership transfer.
+
+## Custody Chat Provisioning
+
+SaiTeam_bot's private `/newdealchat` flow submits an approved request to the
+Deal Desk API. A separate worker creates the private supergroup as custody
+user `8274304175`, profile `SaiTeam_AI`. The bot, Unique, and the requester
+become admins. August and Erick are ordinary default members. The deployed bot
+configuration controls the requester allowlist and defaults.
+
+When adding an operator, configure their numeric Telegram user ID in the bot
+allowlist. A fresh custody session may not know that ID's access hash. Add a
+verified handle alias in `provisioningRuntime.ts` for new team operators and
+deploy the worker with it. Resolve the handle through the custody account first
+and verify the exact numeric ID and that it is a user account. The runtime
+rejects handles that later resolve to a different account.
+
+For explicit CLI requests, prepare a JSON file with a stable `requestId`,
+`custodyProfile`, `expectedUserId`, `title`, `participants`, `admins`,
+`botRightsProfile`, and `dealIds`. Each admin uses `rightsProfile: "team"`;
+the bot uses `botRightsProfile: "baseline"`. `optionalParticipants` must be a
+subset of ordinary participants. `dealIds: []` registers a chat without
+creating or linking a commercial deal.
+
+```sh
+tg-sai chat provision prepare --file request.json
+tg-sai chat provision prepare --file request.json --run
+tg-sai chat provision run --request-id <request-id>
+tg-sai chat provision run --request-id <request-id> --run
+tg-sai chat provision status --request-id <request-id>
+```
+
+The cloud CLI credential needs the corresponding chat workflow capabilities.
+The background worker uses a dedicated read-only record credential with only
+`chats:work` granted for workflow writes. The worker service gets only the
+custody profile, without personal sessions or ownership-transfer passwords.
+
+```sh
+tg-sai worker --custody-profile SaiTeam_AI --once
+tg-sai worker --custody-profile SaiTeam_AI --once --run
+tg-sai worker --custody-profile SaiTeam_AI --run --interval-ms 5000
+```
+
+Without `--run`, the worker reads one queue page and does not connect to
+Telegram. Execution uses a durable worker identity, account lock, and local
+receipts. Never delete these files to force a retry. An uncertain creation
+blocks further creation until an operator reconciles the original request.
+Use `chat provision resolve --help` to adopt a verified group with its original
+creation marker. Known-group partial setup resumes against that same group.
+
+Required admins must be members before setup becomes ready. An ordinary member
+blocked by privacy settings can remain pending with a 24-hour, approval-required
+invite link. A link does not mean the person joined. Handle-based resolution of
+fixed team defaults must verify the expected numeric ID before any invitation.
+
+New ready receipts include an `openGroupUrl` anchored to a message actually
+observed in the group and the existing `primaryInviteLink`, when available.
+These read-only lookups run together with a 10-second limit each. A missing link
+does not undo verified setup. Existing primary invitations are never rotated or
+created by this step, and privacy-blocked members keep their separate controlled
+invitations. The bot displays the saved links in its completion reply and
+`/chatstatus`. Completed requests are not rewritten to refresh missing links.
+
+The source bot configuration starts with admission in `observe` mode. Check
+`~/ki/boku/epics/comms/telegram-bot.md` and its dated rollout evidence for
+the actual deployed state before testing bot commands.
+
+
+## Runtime Health and Deployment Readiness
+
+`tg-sai health` now defaults to offline runtime checks. It verifies both bundled
+WASM assets, crypto and compression operations, and actual Telegram client
+preparation with a temporary SQLite store. It does not read profiles or contact
+Telegram. `--json` provides a machine-readable result and failures exit nonzero.
+
+```sh
+tg-sai health --offline --json
+tg-sai health --online --custody-profile SaiTeam_AI --json
+```
+
+Online mode additionally strict-loads custody user `8274304175`, acquires the
+same account lock used by provisioning, and performs bounded `getMe` validation.
+It cannot fall back to a personal account and does not create or modify chats.
+An account-lock conflict fails the check; run it while the worker is stopped or
+idle. The earlier active-profile/workstation diagnostics remain available with
+`tg-sai health --local` and are separate from custody-worker readiness.
+
+The deployed executable includes a worker command and the same health commands.
+A release candidate must pass offline health as the worker Unix user before
+installation selects it. The worker systemd unit runs offline and online checks
+before starting the queue loop. A service being alive, `--help`, or an empty
+queue preview does not prove Telegram client initialization.
+
+From the Boku Deal Desk source directory, `just bot-health` checks the deployed
+runtime under its service sandbox. `just bot-health --online` also validates
+custody identity. These are operator probes, not the API's `/health` endpoint.
+That endpoint reports API health and whether bot ingress is configured; it does
+not certify Telegram custody readiness.

package/actionExecutor.ts

@@ -8,54 +8,54 @@
 export type BatchActionEvent =
   | {
       /** Operation attempt started. */
-      type: "action_start";
+      type: "action_start"
       /** Telegram chat ID or peer for the attempted action. */
-      chatId: number | string;
+      chatId: number | string
       /** Stable action name, for example `bot_add`. */
-      action: string;
+      action: string
       /** One-based attempt number for this action. */
-      attempt: number;
+      attempt: number
     }
   | {
       /** Telegram returned `FLOOD_WAIT_X` and the executor will retry later. */
-      type: "flood_wait";
+      type: "flood_wait"
       /** Telegram chat ID or peer for the rate-limited action. */
-      chatId: number | string;
+      chatId: number | string
       /** Stable action name, for example `bot_promote_admin`. */
-      action: string;
+      action: string
       /** One-based attempt number that received the flood-wait error. */
-      attempt: number;
+      attempt: number
       /** Seconds Telegram requested in `FLOOD_WAIT_X`. */
-      waitSeconds: number;
+      waitSeconds: number
       /** Milliseconds the executor sleeps, including configured buffer. */
-      sleepMs: number;
+      sleepMs: number
     }
   | {
       /** Operation completed successfully. */
-      type: "action_success";
+      type: "action_success"
       /** Telegram chat ID or peer for the successful action. */
-      chatId: number | string;
+      chatId: number | string
       /** Stable action name, for example `owner_target_add`. */
-      action: string;
+      action: string
       /** Number of attempts required before success. */
-      attempts: number;
+      attempts: number
       /** Elapsed milliseconds from first attempt to success. */
-      elapsedMs: number;
+      elapsedMs: number
     }
   | {
       /** Operation failed with a non-retryable error or exhausted retries. */
-      type: "action_error";
+      type: "action_error"
       /** Telegram chat ID or peer for the failed action. */
-      chatId: number | string;
+      chatId: number | string
       /** Stable action name, for example `transfer_owner`. */
-      action: string;
+      action: string
       /** One-based attempt number that produced the final error. */
-      attempt: number;
+      attempt: number
       /** Error name normalized for logs. */
-      errorName: string;
+      errorName: string
       /** Error message normalized for logs. */
-      errorMessage: string;
-    };
+      errorMessage: string
+    }
 
 /**
  * Receives structured batch action events.
@@ -64,7 +64,7 @@ export type BatchActionEvent =
  * Tests can use `MemoryBatchLogger` to inspect event order without parsing text.
  */
 export interface BatchLogger {
-  event(event: BatchActionEvent): void | Promise<void>;
+  event(event: BatchActionEvent): void | Promise<void>
 }
 
 /**
@@ -72,9 +72,9 @@ export interface BatchLogger {
  */
 export interface TelegramActionContext {
   /** Telegram chat ID or resolvable chat peer for the action. */
-  chatId: number | string;
+  chatId: number | string
   /** Stable action name such as `bot_add` or `owner_target_promote_admin`. */
-  action: string;
+  action: string
 }
 
 /**
@@ -85,28 +85,28 @@ export interface TelegramActionContext {
  */
 export interface TelegramActionExecutorDeps {
   /** Event sink for action start, success, error, and flood-wait events. */
-  logger: BatchLogger;
+  logger: BatchLogger
   /** Sleep function used after Telegram returns `FLOOD_WAIT_X`. */
-  sleep: (ms: number) => Promise<void>;
+  sleep: (ms: number) => Promise<void>
   /** Clock function used to compute elapsed action time. */
-  now: () => number;
+  now: () => number
   /** Number of retries after the first failed attempt. */
-  maxRetries: number;
+  maxRetries: number
   /** Extra milliseconds added to Telegram's required flood-wait duration. */
-  bufferMs: number;
+  bufferMs: number
 }
 
 /**
  * Test logger that stores every event in insertion order.
  */
 export class MemoryBatchLogger implements BatchLogger {
-  readonly events: BatchActionEvent[] = [];
+  readonly events: BatchActionEvent[] = []
 
   /**
    * Appends an event to the in-memory event list.
    */
   event(event: BatchActionEvent): void {
-    this.events.push(event);
+    this.events.push(event)
   }
 }
 
@@ -120,16 +120,16 @@ export class MemoryBatchLogger implements BatchLogger {
  */
 export function parseFloodWaitSeconds(error: unknown): number | null {
   if (!(error instanceof Error)) {
-    return null;
+    return null
   }
 
-  const haystack = `${error.name} ${error.message}`;
-  const match = haystack.match(/FLOOD_WAIT_(\d+)/);
+  const haystack = `${error.name} ${error.message}`
+  const match = haystack.match(/FLOOD_WAIT_(\d+)/)
   if (!match) {
-    return null;
+    return null
   }
 
-  return Number(match[1]);
+  return Number(match[1])
 }
 
 /**
@@ -137,9 +137,9 @@ export function parseFloodWaitSeconds(error: unknown): number | null {
  */
 export function errorName(error: unknown): string {
   if (error instanceof Error && error.name) {
-    return error.name;
+    return error.name
   }
-  return "UnknownError";
+  return "UnknownError"
 }
 
 /**
@@ -147,9 +147,9 @@ export function errorName(error: unknown): string {
  */
 export function errorMessage(error: unknown): string {
   if (error instanceof Error) {
-    return error.message;
+    return error.message
   }
-  return String(error);
+  return String(error)
 }
 
 /**
@@ -165,8 +165,8 @@ export async function withFloodWaitRetry<T>(
   operation: () => Promise<T>,
   deps: TelegramActionExecutorDeps,
 ): Promise<T> {
-  const startedAt = deps.now();
-  const maxAttempts = deps.maxRetries + 1;
+  const startedAt = deps.now()
+  const maxAttempts = deps.maxRetries + 1
 
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     await deps.logger.event({
@@ -174,21 +174,21 @@ export async function withFloodWaitRetry<T>(
       chatId: context.chatId,
       action: context.action,
       attempt,
-    });
+    })
 
     try {
-      const result = await operation();
+      const result = await operation()
       await deps.logger.event({
         type: "action_success",
         chatId: context.chatId,
         action: context.action,
         attempts: attempt,
         elapsedMs: deps.now() - startedAt,
-      });
-      return result;
+      })
+      return result
     } catch (error) {
-      const waitSeconds = parseFloodWaitSeconds(error);
-      const canRetry = waitSeconds !== null && attempt < maxAttempts;
+      const waitSeconds = parseFloodWaitSeconds(error)
+      const canRetry = waitSeconds !== null && attempt < maxAttempts
 
       if (!canRetry) {
         await deps.logger.event({
@@ -198,11 +198,11 @@ export async function withFloodWaitRetry<T>(
           attempt,
           errorName: errorName(error),
           errorMessage: errorMessage(error),
-        });
-        throw error;
+        })
+        throw error
       }
 
-      const sleepMs = waitSeconds * 1000 + deps.bufferMs;
+      const sleepMs = waitSeconds * 1000 + deps.bufferMs
       await deps.logger.event({
         type: "flood_wait",
         chatId: context.chatId,
@@ -210,10 +210,10 @@ export async function withFloodWaitRetry<T>(
         attempt,
         waitSeconds,
         sleepMs,
-      });
-      await deps.sleep(sleepMs);
+      })
+      await deps.sleep(sleepMs)
     }
   }
 
-  throw new Error(`unreachable action executor state: ${context.action}`);
+  throw new Error(`unreachable action executor state: ${context.action}`)
 }