@okrlinkhub/agent-factory 3.0.2 → 3.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Convex Agent Factory
 
-[![npm version](https://badge.fury.io/js/@example%2Fagent-factory.svg)](https://badge.fury.io/js/@example%2Fagent-factory)
+[npm version](https://badge.fury.io/js/@example%2Fagent-factory)
 
 A Convex component for hydration-based orchestration of OpenClaw agents on a generic worker pool (Fly Machines first, provider abstraction built-in).
 
@@ -20,29 +20,83 @@ app.use(agentFactory);
 export default app;
 ```
 
+## Upgrade to 3.1.0
+
+Version `3.1.0` introduces a **Telegram bot identity routing change**.
+
+What changed:
+
+- Telegram integrations now derive a stable `botIdentity` from `Telegram getMe` using the imported bot token.
+- `agentProfiles`, `pairingCodes`, and `identityBindings` now persist `botIdentity`.
+- Telegram webhook ingress now requires `X-Telegram-Bot-Api-Secret-Token` and resolves agents by `botIdentity + telegramUserId/chatId`.
+- Pairing is now bot-scoped, so a bot token must be imported and verified before creating a new pairing code.
+- Hydrated bridge runtime config now carries the resolved profile `botIdentity` alongside the effective bridge secret ref.
+
+Why this matters:
+
+- This release fixes cross-bot collisions where different users chatting with different bots could still be resolved through only `telegramUserId` / `telegramChatId`.
+- The supported model is `1 user -> 1 bot`, with the receiving bot acting as the first discriminator of the whole Telegram flow.
+
+Important compatibility notes for existing consumer apps:
+
+- If your app already has paired Telegram agents created before `3.1.0`, treat them as legacy rows until they are reconciled or re-paired.
+- If your app wraps `configureTelegramWebhook`, `importTelegramTokenForAgent`, or `getUserAgentOnboardingState`, update local validators/types to include `botIdentity` and `secretTokenConfigured`.
+- If your onboarding UI previously allowed pairing before token verification, it should now require successful token import first.
+- If you have custom Telegram ingress code outside `registerRoutes(...)`, you must validate `X-Telegram-Bot-Api-Secret-Token` and pass `botIdentity` into pairing / resolution flows.
+
+Recommended upgrade checklist:
+
+1. Upgrade the package to `3.1.0`.
+2. Regenerate Convex bindings in the consumer app.
+3. Re-import or reconcile Telegram bot tokens so each `agentProfile` stores the correct `botIdentity`.
+4. Reconfigure Telegram webhooks so the component can set the new `secret_token`.
+5. Run the soft-reset migration for legacy Telegram bindings without `botIdentity`.
+6. Create a fresh pairing for existing bots unless you have a verified reconciliation path in place.
+7. Smoke-test two different bots end-to-end and confirm each webhook resolves and bridges through the correct `agentKey`.
+
+Recommended rollout for apps that already have this component installed:
+
+1. Deploy the updated consumer app code first so it understands the new return shapes and onboarding readiness rules.
+2. Upgrade to `@okrlinkhub/agent-factory@3.1.0`.
+3. Regenerate codegen / bindings.
+4. For every existing bot token, run the token reconciliation or re-import flow, then call webhook configuration again.
+5. Run `softResetTelegramBindingsMissingBotIdentity` during the rollout window so legacy bot-agnostic bindings are marked and optionally revoked in a controlled way.
+6. Re-pair existing bots that were active before this release.
+
+New / updated component surfaces involved in this rollout:
+
+- `importTelegramTokenForAgent`: now derives `botIdentity` from `Telegram getMe` and persists it before continuing.
+- `configureTelegramWebhook`: now configures Telegram `secret_token` using the derived `botIdentity`.
+- `reconcileTelegramBotIdentityForAgent`: verifies a stored token again and re-syncs `botIdentity` on the profile.
+- `softResetTelegramBindingsMissingBotIdentity`: explicit migration helper for legacy Telegram bindings and pending pairings.
+
 ## Upgrade to 1.0.0
 
 Version `1.0.0` introduces a **worker lifecycle breaking change**.
 
 What changed:
+
 - `workers.status` is no longer binary.
 - New persisted statuses are now possible: `draining` and `stopping`.
 - The lifecycle is now `active -> draining -> stopping -> stopped`.
 - `active` now means **claimable**, not just "row exists and machine once existed".
 
 Current status values:
+
 - `active`: worker is healthy and can claim new jobs.
 - `draining`: worker must stop claiming and is waiting for final snapshot / shutdown progression.
 - `stopping`: final snapshot is ready or provider teardown is in progress / pending retry.
 - `stopped`: terminal state for that worker instance. Stopped workers are never reactivated.
 
 Important compatibility notes:
+
 - **No manual data migration is required** if your existing rows only contain `active` or `stopped`.
 - **Consumer code may require updates** if it assumes `worker.status` can only be `active` or `stopped`.
 - Any exhaustive `switch` / `if` logic, dashboards, alerts, or admin tools that parse worker status must handle `draining` and `stopping`.
 - `workerControlState` is stricter now: workers in non-claimable states, stale-heartbeat workers, and overdue workers return `shouldStop = true`.
 
 Recommended upgrade checklist:
+
 1. Upgrade the package to `1.0.0`.
 2. Regenerate Convex bindings in the consumer app.
 3. Update any consumer-side status handling for `workers.status`.
@@ -72,6 +126,7 @@ export default crons;
 Version `2.0.0` introduces a **conversation identity breaking change**.
 
 What changed:
+
 - `conversationId` is now required for worker snapshot upload and restore APIs.
 - `dataSnapshots.conversationId` is now mandatory in persisted storage.
 - Snapshot restore no longer falls back to the latest archive for `workspaceId + agentKey`.
@@ -79,6 +134,7 @@ What changed:
 - Telegram pairing no longer changes the conversation lineage used for chat history and snapshots.
 
 Important warnings:
+
 - This release is intentionally **not backward compatible** with legacy snapshots created without `conversationId`.
 - Existing non-prod agents, snapshots, bindings, and conversations created with the old model should be deleted before rollout.
 - If a worker runtime or consumer app still calls snapshot APIs without `conversationId`, the call will now fail at validation time.
@@ -86,6 +142,7 @@ Important warnings:
 - If you have custom dashboards, scripts, or admin tools that query snapshots only by `agentKey`, they must be updated to scope by `workspaceId + agentKey + conversationId`.
 
 Quick upgrade checklist:
+
 1. Delete legacy non-production agents, snapshots, conversations, and identity bindings created before this release.
 2. Upgrade the package to `2.0.0`.
 3. Regenerate Convex bindings in the consumer app.
@@ -95,6 +152,7 @@ Quick upgrade checklist:
 7. Smoke-test one manual user-agent flow, one Telegram-paired flow, and one worker snapshot restore flow before wider rollout.
 
 Recommended release notes to communicate to consumers:
+
 - treat this as a major upgrade, not a safe drop-in patch;
 - start from a clean non-prod environment;
 - roll out workers and consumer app together;
@@ -107,11 +165,13 @@ Recommended release notes to communicate to consumers:
 Starting with this release, the component also exposes an additive set of **user-facing aggregate APIs** for building pages like `MyAgent` and `MyAgentNew` without reconstructing state in the consumer app.
 
 What stays in the consumer app:
+
 - naming policy for agents and Telegram usernames
 - product-specific onboarding copy
 - cron presets or local `agentSettings`
 
 What is now exposed directly by the component:
+
 - user agent overview and active/history lookup
 - onboarding and pairing state
 - conversation view and queue items for a user agent
@@ -119,6 +179,7 @@ What is now exposed directly by the component:
 - user-centric snapshot listing and latest snapshot lookup
 
 Core APIs added for this pattern:
+
 - `listUserAgents`
 - `getUserAgent`
 - `getActiveUserAgent`
@@ -187,6 +248,7 @@ when you pass values inline from the UI, but automatic paths (enqueue + cron) re
 these stored secrets.
 
 If one is missing, reconcile fails with errors like:
+
 - `Missing Convex URL. Import an active 'convex.url' secret or pass convexUrl explicitly.`
 - `Missing Fly API token. Import an active 'fly.apiToken' secret or pass flyApiToken explicitly.`
 
@@ -205,6 +267,7 @@ npx convex run example:importSecret '{
 ```
 
 Important URL mapping:
+
 - Fly worker environment variable `CONVEX_URL` must use the `.convex.cloud` URL.
 - Component secret `convex.url` must use the `.convex.site` URL (used by component workflows and webhook-facing integration paths).
 
@@ -247,6 +310,7 @@ export const enqueueTelegramMessage = mutation({
 ```
 
 After enqueue, a **queue processor runtime** must process the queue by calling:
+
 - `components.agentFactory.lib.claim`
 - `components.agentFactory.lib.getHydrationBundle`
 - `components.agentFactory.lib.heartbeat`
@@ -257,6 +321,7 @@ explicitly alongside `workspaceId` and `agentKey`; the component no longer suppo
 fallbacks that select the latest archive for an agent without matching the conversation.
 
 Worker autoscaling reconcile now follows a hybrid model:
+
 - `enqueue` schedules an immediate async reconcile trigger (`runAfter(0, ...)`)
 - a periodic cron fallback is still recommended to recover from missed triggers
 - desired worker count is conversation-aware, so multiple queued messages on the same `conversationId` do not over-scale worker spawn
@@ -287,6 +352,89 @@ export default crons;
 
 This cron is a safety net. The primary path remains enqueue-triggered reconcile.
 
+### Component Fly cleanup for billing protection
+
+The package now supports a dedicated Fly cleanup action in the component itself. The intent is to
+protect the consumer's billing by giving every integration the same tested cleanup path instead of
+reimplementing destructive Fly logic in each consumer app.
+
+The public component action is exposed as:
+
+- `components.agentFactory.lib.runFlyCleanup`
+
+What the action does:
+
+- resolves the target Fly app from `providerRuntimeConfig` unless the caller passes an explicit override
+- reads `fly.apiToken` from the component secret store unless the caller passes an explicit override
+- inventories machines and destroys them per machine ID
+- verifies machine count again
+- inventories volumes and destroys them per volume ID
+- verifies volume count again and returns a report with counts, warnings, and errors
+
+What the consumer still owns:
+
+- choosing whether to run this policy at all
+- choosing the schedule window
+- optionally exposing an admin-only helper/wrapper
+
+Thin wrapper through `exposeApi(...)`:
+
+```ts
+const {
+  startWorkers,
+  runFlyCleanup,
+} = exposeApi(components.agentFactory, {
+  providerConfig: EXAMPLE_PROVIDER_CONFIG,
+  auth: async (ctx, operation) => {
+    const userId = await getAuthUserId(ctx);
+    if (userId === null && operation.type === "write") {
+      throw new Error("Unauthorized");
+    }
+    return userId;
+  },
+});
+```
+
+This keeps the consumer surface small: the wrapper only forwards auth and the local
+`providerConfig`, while the package owns the actual Fly inventory, destroy, and verification logic.
+
+Minimal consumer cron wiring:
+
+```ts
+import { cronJobs } from "convex/server";
+import { api } from "./_generated/api";
+
+const crons = cronJobs();
+
+crons.interval(
+  "agent-factory reconcile workers fallback",
+  { minutes: 5 },
+  api.example.startWorkers,
+  {},
+);
+
+crons.cron(
+  "agent-factory nightly fly cleanup",
+  "0 3 * * *",
+  api.example.runFlyCleanup,
+  {},
+);
+
+export default crons;
+```
+
+Recommended consumer helper:
+
+- keep it thin
+- call `components.agentFactory.lib.runFlyCleanup` directly, or expose `runFlyCleanup` through `exposeApi(...)`
+- avoid duplicating inventory, destroy sequencing, or verification logic in the consumer
+
+Operational prerequisites:
+
+- `fly.apiToken` must be present as an active component secret
+- the effective `providerRuntimeConfig` must point at the Fly app you want to protect
+- the cleanup remains intentionally destructive, so it should only target a single explicit app per deployment
+
 ### Agent pushing schedule (hourly dispatcher)
 
 For agent pushing, the recommended scheduler is an hourly cron that dispatches due jobs:
@@ -308,6 +456,7 @@ export default crons;
 ```
 
 Important product constraint:
+
 - job configuration supports only fixed schedule slots (`HH:mm`, plus weekday/day-of-month)
 - minute-based recurrence ("every N minutes") is intentionally not supported
 
@@ -318,16 +467,19 @@ Admin broadcast is also supported through `sendBroadcastToAllActiveAgents`, whic
 The model/provider is controlled by Fly worker environment variables (for example `OPENCLAW_AGENT_MODEL`, `MOONSHOT_API_KEY`, `OPENAI_API_KEY`) and applied at runtime by the worker image bootstrap.
 
 Why:
+
 - keeps model routing as infrastructure/runtime concern
 - avoids per-agent schema coupling to a specific LLM field
 - lets you switch model/provider with a Fly deploy or env change only
 
 Practical notes:
+
 - set model/provider env on the Fly app (`fly secrets set` / `[env]` in `fly.toml`)
 - keep `agentProfiles` focused on identity, bridge configuration, and secrets references
 - worker image tag stays centralized in `src/component/config.ts` (`DEFAULT_WORKER_IMAGE`)
 
 If you use `exposeApi(...)`, the worker contract is available directly on the consumer API surface:
+
 - `workerClaim`
 - `workerHydrationBundle`
 - `workerHeartbeat`
@@ -339,6 +491,7 @@ If you use `exposeApi(...)`, the worker contract is available directly on the co
 `agent-factory` does **not** execute `agent-bridge` tools.
 
 Its role stops at:
+
 - storing bridge settings on the agent profile
 - resolving bridge secrets from the component secret store
 - exposing `bridgeRuntimeConfig` in hydration
@@ -346,7 +499,7 @@ Its role stops at:
 
 Tool execution belongs to the OpenClaw worker runtime / worker image, not to `agent-factory`.
 
-1) Configure an agent profile with bridge settings:
+1. Configure an agent profile with bridge settings:
 
 ```ts
 await ctx.runMutation(components.agentFactory.lib.configureAgent, {
@@ -363,7 +516,7 @@ await ctx.runMutation(components.agentFactory.lib.configureAgent, {
 });
 ```
 
-2) Import bridge service key in component secrets:
+1. Import bridge service key in component secrets:
 
 ```sh
 npx convex run example:importSecret '{
@@ -373,6 +526,7 @@ npx convex run example:importSecret '{
 ```
 
 Naming convention supported by hydration resolver:
+
 - per-agent service key: `agent-bridge.serviceKey.<agentKey>` (recommended)
 - global service key fallback: `agent-bridge.serviceKey`
 - optional profile override: `bridgeConfig.serviceKeySecretRef`
@@ -399,6 +553,7 @@ Do **not** treat `agent-factory` as the place where `bridge.<functionKey>` tool
 If your OpenClaw agents use `agent-bridge`, that execution flow must live in the worker runtime itself.
 
 Fallback env (worker-side only, used when hydration misses values):
+
 - `OPENCLAW_AGENT_BRIDGE_BASE_URL` or `AGENT_BRIDGE_BASE_URL`
 - `OPENCLAW_SERVICE_ID` or `AGENT_BRIDGE_SERVICE_ID`
 - `OPENCLAW_SERVICE_KEY` or `AGENT_BRIDGE_SERVICE_KEY`
@@ -408,12 +563,14 @@ Fallback env (worker-side only, used when hydration misses values):
 
 When `agent-factory` is used together with `agent-bridge`, spawned workers may need these environment variables available in their runtime:
 
-| Env var | Component secret ref | Purpose |
-|---------|----------------------|---------|
-| `OPENCLAW_SERVICE_ID` | `agent-bridge.serviceId` | Service identity for bridge auth |
-| `OPENCLAW_SERVICE_KEY` | `agent-bridge.serviceKey` | Service key for bridge auth |
+
+| Env var                          | Component secret ref               | Purpose                                            |
+| -------------------------------- | ---------------------------------- | -------------------------------------------------- |
+| `OPENCLAW_SERVICE_ID`            | `agent-bridge.serviceId`           | Service identity for bridge auth                   |
+| `OPENCLAW_SERVICE_KEY`           | `agent-bridge.serviceKey`          | Service key for bridge auth                        |
 | `OPENCLAW_LINKING_SHARED_SECRET` | `agent-bridge.linkingSharedSecret` | Shared secret for `execute-on-behalf` user linking |
 
+
 The scheduler forwards these from the component secret store into each machine's env at spawn time. These values prepare the worker runtime for bridge usage; they do not implement bridge tool execution inside `agent-factory`.
 
 Import all three into the component secret store:
@@ -445,6 +602,7 @@ export default http;
 ```
 
 This exposes:
+
 - `POST /agent-factory/telegram/webhook` -> enqueue-only (no business processing)
 
 Important: the webhook/router only receives ingress and enqueues.
@@ -472,6 +630,7 @@ await configureTelegramWebhook({
 ```
 
 This API:
+
 - loads bot token from component secrets (active secret for `secretRef`)
 - calls Telegram `setWebhook`
 - verifies status with `getWebhookInfo`
@@ -483,31 +642,35 @@ Typical one-time pairing flow:
 
 1. Configure webhook and verify `isReady === true` via `configureTelegramWebhook`.
 2. Your app authenticates the user and creates a one-time pairing code via
-   `createPairingCode`.
+  `createPairingCode`.
 3. User opens Telegram deep-link (`/start <pairingCode>`).
 4. `registerRoutes(...)` webhook consumes the pairing code and performs
-   `bindUserAgent` automatically with `source: "telegram_pairing"` and
+  `bindUserAgent` automatically with `source: "telegram_pairing"` and
    Telegram ids from the update.
 5. Webhook ingress then resolves the binding internally and enqueues with the mapped
-   `agentKey`.
+  `agentKey`.
 
 Available pairing APIs (via `exposeApi(...)`):
+
 - `createPairingCode`
 - `getPairingCodeStatus`
 - `configureTelegramWebhook`
 
 Telegram token storage (multi-tenant):
+
 - store tenant token in component secrets with an agent-scoped ref (for example `telegram.botToken.<agentKey>`)
 - include that ref in `agentProfiles.secretsRef`
 - worker gets resolved plaintext from hydration bundle (`telegramBotToken`) at runtime
 - do not use a single global `TELEGRAM_BOT_TOKEN` on Fly app
 
 `registerRoutes(...)` supports this behavior with:
+
 - `resolveAgentKeyFromBinding` (default `true`)
 - `fallbackAgentKey` (default `"default"`)
 - `requireBindingForTelegram` (default `false`, when `true` rejects unbound users)
 
 Special handling for `/start`:
+
 - `/start <pairingCode>` attempts pairing consumption and does not enqueue the command.
 - invalid `/start` payload returns `200` with pairing error details to avoid Telegram retries.
 
@@ -530,9 +693,12 @@ flowchart LR
   flyWorkers --> claimLoop
 ```
 
+
+
 ## Data model
 
 Core tables:
+
 - `agentProfiles`
 - `conversations`
 - `messageQueue`
@@ -540,6 +706,7 @@ Core tables:
 - `secrets`
 
 Hydration/runtime tables:
+
 - `conversationHydrationCache`
 - `dataSnapshots`
 
@@ -558,12 +725,14 @@ Hydration/runtime tables:
 
 ## OpenClaw workspace persistence
 
-| OpenClaw source | Persistence layer |
-|---|---|
-| `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md`, `HEARTBEAT.md`, `TOOLS.md` | worker filesystem backup (`/data/workspace`) |
-| `memory/YYYY-MM-DD.md`, `MEMORY.md` | worker filesystem backup (`/data/workspace`) |
-| Skills and related assets | bundled directly in worker image (`openclaw-okr-image`) |
-| Conversation-specific deltas | `conversationHydrationCache` |
+
+| OpenClaw source                                                              | Persistence layer                                       |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md`, `HEARTBEAT.md`, `TOOLS.md` | worker filesystem backup (`/data/workspace`)            |
+| `memory/YYYY-MM-DD.md`, `MEMORY.md`                                          | worker filesystem backup (`/data/workspace`)            |
+| Skills and related assets                                                    | bundled directly in worker image (`openclaw-okr-image`) |
+| Conversation-specific deltas                                                 | `conversationHydrationCache`                            |
+
 
 ## Failure model
 
@@ -576,6 +745,7 @@ Hydration/runtime tables:
 ## Config-first
 
 `src/component/config.ts` defines type-safe policies:
+
 - queue policy
 - retry policy
 - lease policy
@@ -585,6 +755,7 @@ Hydration/runtime tables:
 ## Fly.io provider notes
 
 The current provider implementation uses Fly Machines API endpoints for:
+
 - create machine
 - list machines
 - cordon machine
@@ -596,11 +767,13 @@ Do **not** share the same Fly app across multiple Convex backends/components tha
 their own queue polling/reconcile loop.
 
 Why this is required:
+
 - workers in a Fly app share the same control plane (create/list/stop),
 - each backend computes desired capacity from its own queue state only,
 - mixed backends in one app can stop each other's machines or produce unpredictable polling behavior.
 
 Recommended pattern:
+
 - one Convex backend -> one dedicated Fly app (for example `agent-factory-workers-prod`)
 - another Convex backend -> another dedicated Fly app (for example `agent-factory-workers-staging`)
 - keep `providerConfig.appName` and worker image registry aligned per backend/environment.
@@ -608,27 +781,32 @@ Recommended pattern:
 ### Worker image setup (required first step for custom skills)
 
 Any new skill you want inside OpenClaw agents must be added to the worker image source repo:
-- https://github.com/okrlinkhub/openclaw-okr-image
+
+- [https://github.com/okrlinkhub/openclaw-okr-image](https://github.com/okrlinkhub/openclaw-okr-image)
 
 Fork this repository to maintain your own image with your custom skills/assets.
 
 For `globalSkills` managed by this component, the recommended runtime pattern is different:
+
 - store the source of truth in component tables `globalSkills`, `globalSkillVersions`, `globalSkillReleases`
 - treat each skill as a mini filesystem bundle (`files[]`), not as a single `sourceJs` blob
 - expose them through `getWorkerGlobalSkillsManifest`
 - let the worker image materialize them into `OPENCLAW_SKILLS_DIR` during prestart, before the OpenClaw gateway boots
 
 The manifest now carries an explicit on-disk layout contract for OpenClaw workspace skills:
+
 - `layoutVersion = openclaw-workspace-skill-v1`
 - `skillDirName`
 - `files[]` with `path`, `content`, `sha256`
 
 Breaking change in `3.0.0`:
+
 - `sourceJs` has been removed from the global skill model
 - existing legacy global skill rows must be deleted before moving to `3.0.0`
 - existing legacy skills must be republished as full bundles
 
 Bundle contract for `3.0.0`:
+
 - required user files:
   - `SKILL.md`
   - `scripts/index.mjs` or `scripts/index.cjs` (must match `moduleFormat`)
@@ -642,6 +820,7 @@ Extract a `Bundle files JSON` payload from an existing OpenClaw skill directory:
 Use this when you already have a correctly materialized skill inside an OpenClaw workspace and want to republish it as a `3.0.0` global skill bundle.
 
 Important:
+
 - run the command against the skill directory itself (for example `/path/to/workspace/skills/agent-bridge`)
 - the command automatically excludes `.af-global-skill.json`
 - hidden files other than `.af-global-skill.json` are excluded by default
@@ -720,11 +899,13 @@ EOF
 ```
 
 The resulting JSON should contain files like:
+
 - `SKILL.md`
 - `scripts/index.mjs`
 - any extra files such as `scripts/agent-bridge-cli.mjs`
 
 Recommended worker bootstrap order:
+
 1. restore snapshot into `/data`
 2. fetch `workerGlobalSkillsManifest`
 3. verify checksums and materialize skills atomically into `OPENCLAW_SKILLS_DIR`
@@ -733,11 +914,12 @@ Recommended worker bootstrap order:
 This avoids the historical race where the gateway could start before restored or DB-backed skills were present on disk.
 
 First required flow:
-1) Take the image repo (fork/clone your own `openclaw-okr-image`).
-2) Build and deploy it on your own Fly app.
-   - Recommended build mode: remote Fly builder, `depot` disabled, `--remote-only`.
-3) Use the published image as reference in `src/component/config.ts` (`DEFAULT_WORKER_IMAGE` is the source of truth).
-4) Repeat the same process for every runtime/skills update.
+
+1. Take the image repo (fork/clone your own `openclaw-okr-image`).
+2. Build and deploy it on your own Fly app.
+  - Recommended build mode: remote Fly builder, `depot` disabled, `--remote-only`.
+3. Use the published image as reference in `src/component/config.ts` (`DEFAULT_WORKER_IMAGE` is the source of truth).
+4. Repeat the same process for every runtime/skills update.
 
 **Enterprise security model**: The worker image enforces a security policy where only skills explicitly included by the image maintainer are installed by default. Any other skills that may be present in the workspace are automatically removed on each worker startup. This ensures that only approved, vetted skills from the image source can execute within your OpenClaw agents.
 
@@ -745,20 +927,21 @@ First required flow:
 
 When you update the worker runtime (for example in `openclaw-okr-image/worker.mjs`), use this flow to publish and roll out safely.
 
-1) Deploy with remote Fly builder (explicitly disabling Depot):
+1. Deploy with remote Fly builder (explicitly disabling Depot):
 
 ```sh
 cd /path/to/openclaw-okr-image
 fly deploy --remote-only --depot=false --yes
 ```
 
-2) If deployment fails with `CONVEX_URL not set`, set the secret and retry:
+1. If deployment fails with `CONVEX_URL not set`, set the secret and retry:
 
 ```sh
 fly secrets set CONVEX_URL="https://<your-convex-deployment>.convex.cloud" -a <your-fly-worker-app>
 ```
 
-3) Capture the new image tag from deploy output (for example
+1. Capture the new image tag from deploy output (for example
+
 `registry.fly.io/<your-fly-worker-app>:deployment-XXXXXXXXXXXX`), then update
 `src/component/config.ts` in this repo:
 
@@ -767,30 +950,34 @@ export const DEFAULT_WORKER_IMAGE =
   "registry.fly.io/<your-fly-worker-app>:deployment-XXXXXXXXXXXX";
 ```
 
-4) Verify rollout:
+1. Verify rollout:
 
 ```sh
 fly status -a <your-fly-worker-app>
 fly logs -a <your-fly-worker-app> --no-tail
 ```
 
-5) (Recommended) Commit the `DEFAULT_WORKER_IMAGE` update so scheduler-driven
+1. (Recommended) Commit the `DEFAULT_WORKER_IMAGE` update so scheduler-driven
+
 spawns use the exact image that was just deployed.
 
 Recommended runtime split:
+
 - Consumer app (Next.js/Vercel): webhook ingress + enqueue only
 - Fly worker app: claim/heartbeat/complete/fail loop
 
 Anti-pattern to avoid:
+
 - Telegram webhook -> Fly worker HTTP endpoint
 - Reason: workers are batch processors, may be scaled to zero, and should not be used as public ingress.
 - Global Fly env `TELEGRAM_BOT_TOKEN` for all tenants
 - Reason: breaks multi-tenant isolation and forces shared bot credentials.
 
 References:
-- https://docs.machines.dev/
-- https://fly.io/docs/machines/api/machines-resource/
-- https://docs.convex.dev/components/authoring
+
+- [https://docs.machines.dev/](https://docs.machines.dev/)
+- [https://fly.io/docs/machines/api/machines-resource/](https://fly.io/docs/machines/api/machines-resource/)
+- [https://docs.convex.dev/components/authoring](https://docs.convex.dev/components/authoring)
 
 ## Development
 
@@ -799,4 +986,21 @@ npm i
 npm run dev
 ```
 
-Upgrade note for older releases: version `0.2.14` makes `agentProfiles.providerUserId`, `agentProfiles.soulMd`, `agentProfiles.clientMd`, and `agentProfiles.skills` optional only to let you clean them safely. Before upgrading to version `0.2.15`, where those fields are expected to be removed from the schema, install `0.2.14`, run `components.agentFactory.lib.clearDeprecatedAgentProfileFields` from Convex Dashboard, and make sure a second run returns `updated = 0`. This avoids schema validation issues caused by leftover stored values during the upgrade to `0.2.15`.
+### Release validation note
+
+For npm releases cut from `develop`, known failures in the `example` Vitest suite are currently treated as non-blocking release noise.
+
+What we still verify before publishing:
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm pack --dry-run`
+- focused package tests when a change touches runtime behavior outside the example app
+
+What we intentionally do not require for publish:
+
+- a fully green `npm test` run when the remaining failures are limited to the `example` app test surface and do not affect the published package itself
+
+This choice was applied for the `3.0.2` npm release after confirming the package checks above passed and the remaining instability was in the example-only test flow.
+
+Upgrade note for older releases: version `0.2.14` makes `agentProfiles.providerUserId`, `agentProfiles.soulMd`, `agentProfiles.clientMd`, and `agentProfiles.skills` optional only to let you clean them safely. Before upgrading to version `0.2.15`, where those fields are expected to be removed from the schema, install `0.2.14`, run `components.agentFactory.lib.clearDeprecatedAgentProfileFields` from Convex Dashboard, and make sure a second run returns `updated = 0`. This avoids schema validation issues caused by leftover stored values during the upgrade to `0.2.15`.

package/dist/client/bridge.d.ts

@@ -5,6 +5,7 @@ export type HydratedBridgeRuntimeConfig = {
     appKey: string | null;
     serviceKey: string | null;
     serviceKeySecretRef: string | null;
+    botIdentity?: string | null;
 };
 export type ResolvedBridgeRuntimeConfig = {
     baseUrl: string;

package/dist/client/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/client/bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/client/bridge.ts"],"names":[],"mappings":"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"}