@okrlinkhub/agent-factory 1.0.10 → 2.0.0

package/README.md

@@ -67,6 +67,39 @@ crons.interval(
 export default crons;
 ```
 
+## Upgrade to 2.0.0
+
+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`.
+- User-agent flows now use a stable conversation identity scoped to `consumerUserId + agentKey`.
+- 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.
+- If your integration assumed conversation IDs like `telegram:<chatId>` or `user:<consumerUserId>` for user-agent flows, you must update it to treat `conversationId` as an opaque stable identifier.
+- 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.
+4. Redeploy all worker runtimes and make sure they always pass `conversationId` to snapshot upload/restore APIs.
+5. Update any custom integrations that assumed user-agent conversation IDs were derived from Telegram chat IDs.
+6. Verify that snapshot restore returns data only for the exact `workspaceId + agentKey + conversationId` tuple.
+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;
+- do not reuse legacy archives generated before `conversationId` became mandatory.
+
 ## Usage
 
 ### User-facing agent APIs
@@ -103,6 +136,10 @@ Core APIs added for this pattern:
 - `listSnapshotsForUserAgent`
 - `getLatestSnapshotForUserAgent`
 
+For user-agent flows, the component now treats `conversationId` as a stable identity scoped to
+`consumerUserId + agentKey`, so Telegram pairing changes do not move the chat to a different
+conversation history or snapshot lineage.
+
 Minimal consumer example:
 
 ```ts
@@ -215,6 +252,10 @@ After enqueue, a **queue processor runtime** must process the queue by calling:
 - `components.agentFactory.lib.heartbeat`
 - `components.agentFactory.lib.complete` or `components.agentFactory.lib.fail`
 
+When workers create or restore filesystem snapshots, `conversationId` must always be passed
+explicitly alongside `workspaceId` and `agentKey`; the component no longer supports snapshot
+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
@@ -293,9 +334,17 @@ If you use `exposeApi(...)`, the worker contract is available directly on the co
 - `workerComplete`
 - `workerFail`
 
-### Native integration with `agent-bridge` (no consumer glue code)
+### `agent-bridge`: config and secrets for OpenClaw workers
+
+`agent-factory` does **not** execute `agent-bridge` tools.
 
-`agent-factory` now exposes a native contract for bridge execution. You only configure profile + secrets in the component.
+Its role stops at:
+- storing bridge settings on the agent profile
+- resolving bridge secrets from the component secret store
+- exposing `bridgeRuntimeConfig` in hydration
+- forwarding bridge-related env vars to spawned OpenClaw workers
+
+Tool execution belongs to the OpenClaw worker runtime / worker image, not to `agent-factory`.
 
 1) Configure an agent profile with bridge settings:
 
@@ -346,32 +395,8 @@ skills (`APP_BASE_URL_MAP_JSON`).
 
 Hydration includes `bridgeRuntimeConfig` for the worker loop.
 
-3) In worker runtime use built-in helpers from this package:
-
-```ts
-import {
-  maybeExecuteBridgeToolCall,
-  resolveBridgeRuntimeConfig,
-} from "@okrlinkhub/agent-factory";
-
-const resolved = resolveBridgeRuntimeConfig(hydration.bridgeRuntimeConfig);
-if (resolved.ok) {
-  // Optional proactive resolution check
-}
-
-const toolResult = await maybeExecuteBridgeToolCall({
-  toolName: pendingToolCall.toolName,
-  toolArgs,
-  hydratedConfig: hydration.bridgeRuntimeConfig,
-  userToken: maybeUserJwtOrNull,
-});
-```
-
-`maybeExecuteBridgeToolCall` handles:
-- `bridge.<functionKey>` mapping to `POST /agent/execute`
-- strict headers (`X-Agent-Service-Id`, `X-Agent-Service-Key`, `X-Agent-App`)
-- retry for `429` and `5xx`
-- deterministic response object to map back into conversation/tool messages
+Do **not** treat `agent-factory` as the place where `bridge.<functionKey>` tool calls are executed.
+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`
@@ -381,7 +406,7 @@ Fallback env (worker-side only, used when hydration misses values):
 
 ### Required Fly.io / component secrets for agent-bridge
 
-When `agent-factory` is connected to `agent-bridge`, every spawned worker must receive these three environment variables for bridge execution and user linking to work correctly:
+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 |
 |---------|----------------------|---------|
@@ -389,7 +414,7 @@ When `agent-factory` is connected to `agent-bridge`, every spawned worker must r
 | `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. If any is missing, the worker may fail bridge calls (e.g. `403 delegation_denied` when linking is required).
+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:
 

package/dist/client/index.d.ts

@@ -22,8 +22,8 @@ export declare function exposeApi(component: ComponentApi, options: {
     getProviderRuntimeConfig: import("convex/server").RegisteredQuery<"public", {}, Promise<any>>;
     setProviderRuntimeConfig: import("convex/server").RegisteredMutation<"public", {
         providerConfig: {
-            appName: string;
             kind: "fly" | "runpod" | "ecs";
+            appName: string;
             organizationSlug: string;
             image: string;
             region: string;
@@ -39,10 +39,9 @@ export declare function exposeApi(component: ComponentApi, options: {
         };
     }, Promise<null>>;
     enqueue: import("convex/server").RegisteredMutation<"public", {
-        metadata?: Record<string, string> | undefined;
         providerConfig?: {
-            appName: string;
             kind: "fly" | "runpod" | "ecs";
+            appName: string;
             organizationSlug: string;
             image: string;
             region: string;
@@ -50,11 +49,12 @@ export declare function exposeApi(component: ComponentApi, options: {
             volumePath: string;
             volumeSizeGb: number;
         } | undefined;
-        priority?: number | undefined;
         externalMessageId?: string | undefined;
         rawUpdateJson?: string | undefined;
-        agentKey: string;
+        metadata?: Record<string, string> | undefined;
+        priority?: number | undefined;
         conversationId: string;
+        agentKey: string;
         provider: string;
         providerUserId: string;
         messageText: string;
@@ -90,18 +90,18 @@ export declare function exposeApi(component: ComponentApi, options: {
         };
     } | null>>;
     workerHeartbeat: import("convex/server").RegisteredMutation<"public", {
-        messageId: string;
         workerId: string;
+        messageId: string;
         leaseId: string;
     }, Promise<boolean>>;
     workerComplete: import("convex/server").RegisteredMutation<"public", {
-        messageId: string;
         workerId: string;
+        messageId: string;
         leaseId: string;
     }, Promise<boolean>>;
     workerFail: import("convex/server").RegisteredMutation<"public", {
-        messageId: string;
         workerId: string;
+        messageId: string;
         leaseId: string;
         errorMessage: string;
     }, Promise<{
@@ -110,8 +110,8 @@ export declare function exposeApi(component: ComponentApi, options: {
         requeued: boolean;
     }>>;
     workerHydrationBundle: import("convex/server").RegisteredQuery<"public", {
-        workspaceId: string;
         messageId: string;
+        workspaceId: string;
     }, Promise<{
         agentKey: string;
         bridgeRuntimeConfig: null | {
@@ -147,8 +147,8 @@ export declare function exposeApi(component: ComponentApi, options: {
         telegramBotToken: null | string;
     } | null>>;
     workerGlobalSkillsManifest: import("convex/server").RegisteredQuery<"public", {
-        workspaceId?: string | undefined;
         workerId?: string | undefined;
+        workspaceId?: string | undefined;
         releaseChannel?: "stable" | "canary" | undefined;
     }, Promise<any>>;
     workerConversationHasQueued: import("convex/server").RegisteredQuery<"public", {
@@ -159,8 +159,8 @@ export declare function exposeApi(component: ComponentApi, options: {
         conversationId: string;
         messages: {
             at?: number | undefined;
-            content: string;
             role: "system" | "user" | "assistant" | "tool";
+            content: string;
         }[];
     }, Promise<{
         messageCount: number;
@@ -170,26 +170,26 @@ export declare function exposeApi(component: ComponentApi, options: {
         workerId: string;
     }, Promise<any>>;
     workerPrepareSnapshotUpload: import("convex/server").RegisteredMutation<"public", {
-        conversationId?: string | undefined;
+        conversationId: string;
         agentKey: string;
-        workspaceId: string;
         workerId: string;
-        reason: "manual" | "drain" | "signal";
+        workspaceId: string;
+        reason: "drain" | "signal" | "manual";
     }, Promise<any>>;
     workerFinalizeSnapshotUpload: import("convex/server").RegisteredMutation<"public", {
         workerId: string;
-        storageId: string;
         snapshotId: string;
+        storageId: string;
         sha256: string;
         sizeBytes: number;
     }, Promise<any>>;
     workerFailSnapshotUpload: import("convex/server").RegisteredMutation<"public", {
-        error: string;
         workerId: string;
         snapshotId: string;
+        error: string;
     }, Promise<any>>;
     workerLatestSnapshotForRestore: import("convex/server").RegisteredQuery<"public", {
-        conversationId?: string | undefined;
+        conversationId: string;
         agentKey: string;
         workspaceId: string;
     }, Promise<any>>;
@@ -202,25 +202,25 @@ export declare function exposeApi(component: ComponentApi, options: {
         messageId: string;
     }, Promise<any>>;
     globalSkillsDeploy: import("convex/server").RegisteredMutation<"public", {
-        actor?: string | undefined;
-        description?: string | undefined;
+        releaseChannel?: "stable" | "canary" | undefined;
         displayName?: string | undefined;
+        description?: string | undefined;
         entryPoint?: string | undefined;
         moduleFormat?: "esm" | "cjs" | undefined;
-        releaseChannel?: "stable" | "canary" | undefined;
-        version: string;
+        actor?: string | undefined;
         slug: string;
+        version: string;
         sourceJs: string;
     }, Promise<any>>;
     globalSkillsList: import("convex/server").RegisteredQuery<"public", {
+        releaseChannel?: "stable" | "canary" | undefined;
         status?: "active" | "disabled" | undefined;
         limit?: number | undefined;
-        releaseChannel?: "stable" | "canary" | undefined;
     }, Promise<any>>;
     globalSkillsSetStatus: import("convex/server").RegisteredMutation<"public", {
         actor?: string | undefined;
-        status: "active" | "disabled";
         slug: string;
+        status: "active" | "disabled";
     }, Promise<any>>;
     globalSkillsDelete: import("convex/server").RegisteredMutation<"public", {
         slug: string;
@@ -291,8 +291,8 @@ export declare function exposeApi(component: ComponentApi, options: {
     bindUserAgent: import("convex/server").RegisteredMutation<"public", {
         metadata?: Record<string, string> | undefined;
         source?: "manual" | "telegram_pairing" | "api" | undefined;
-        telegramChatId?: string | undefined;
         telegramUserId?: string | undefined;
+        telegramChatId?: string | undefined;
         agentKey: string;
         consumerUserId: string;
     }, Promise<{
@@ -345,8 +345,8 @@ export declare function exposeApi(component: ComponentApi, options: {
         consumerUserId: string;
     }, Promise<any>>;
     resolveAgentForTelegram: import("convex/server").RegisteredQuery<"public", {
-        telegramChatId?: string | undefined;
         telegramUserId?: string | undefined;
+        telegramChatId?: string | undefined;
     }, Promise<{
         agentKey: null | string;
         consumerUserId: null | string;
@@ -372,8 +372,8 @@ export declare function exposeApi(component: ComponentApi, options: {
         consumerUserId: string;
     }, Promise<any>>;
     consumePairingCode: import("convex/server").RegisteredMutation<"public", {
-        telegramChatId: string;
         telegramUserId: string;
+        telegramChatId: string;
         code: string;
     }, Promise<{
         agentKey: string;
@@ -406,8 +406,8 @@ export declare function exposeApi(component: ComponentApi, options: {
     importTelegramTokenForAgent: import("convex/server").RegisteredMutation<"public", {
         metadata?: Record<string, string> | undefined;
         agentKey: string;
-        consumerUserId: string;
         plaintextValue: string;
+        consumerUserId: string;
     }, Promise<any>>;
     getUserAgentOnboardingState: import("convex/server").RegisteredQuery<"public", {
         agentKey: string;
@@ -443,11 +443,11 @@ export declare function exposeApi(component: ComponentApi, options: {
     }, Promise<any>>;
     createPushTemplate: import("convex/server").RegisteredMutation<"public", {
         enabled?: boolean | undefined;
-        companyId: string;
         periodicity: "manual" | "daily" | "weekly" | "monthly";
-        text: string;
+        companyId: string;
+        templateKey: string;
         title: string;
-        actorUserId: string;
+        text: string;
         suggestedTimes: ({
             kind: "daily";
             time: string;
@@ -460,13 +460,12 @@ export declare function exposeApi(component: ComponentApi, options: {
             time: string;
             dayOfMonth: number | "last";
         })[];
-        templateKey: string;
+        actorUserId: string;
     }, Promise<any>>;
     updatePushTemplate: import("convex/server").RegisteredMutation<"public", {
-        enabled?: boolean | undefined;
         periodicity?: "manual" | "daily" | "weekly" | "monthly" | undefined;
-        text?: string | undefined;
         title?: string | undefined;
+        text?: string | undefined;
         suggestedTimes?: ({
             kind: "daily";
             time: string;
@@ -479,8 +478,9 @@ export declare function exposeApi(component: ComponentApi, options: {
             time: string;
             dayOfMonth: number | "last";
         })[] | undefined;
-        templateId: string;
+        enabled?: boolean | undefined;
         actorUserId: string;
+        templateId: string;
     }, Promise<any>>;
     deletePushTemplate: import("convex/server").RegisteredMutation<"public", {
         templateId: string;
@@ -507,14 +507,17 @@ export declare function exposeApi(component: ComponentApi, options: {
         } | undefined;
         consumerUserId: string;
         companyId: string;
-        timezone: string;
         templateId: string;
+        timezone: string;
     }, Promise<any>>;
     createPushJobCustom: import("convex/server").RegisteredMutation<"public", {
         enabled?: boolean | undefined;
         consumerUserId: string;
-        companyId: string;
         periodicity: "manual" | "daily" | "weekly" | "monthly";
+        companyId: string;
+        title: string;
+        text: string;
+        timezone: string;
         schedule: {
             kind: "manual";
         } | {
@@ -529,13 +532,13 @@ export declare function exposeApi(component: ComponentApi, options: {
             time: string;
             dayOfMonth: number | "last";
         };
-        text: string;
-        timezone: string;
-        title: string;
     }, Promise<any>>;
     updatePushJob: import("convex/server").RegisteredMutation<"public", {
-        enabled?: boolean | undefined;
         periodicity?: "manual" | "daily" | "weekly" | "monthly" | undefined;
+        title?: string | undefined;
+        text?: string | undefined;
+        enabled?: boolean | undefined;
+        timezone?: string | undefined;
         schedule?: {
             kind: "manual";
         } | {
@@ -550,9 +553,6 @@ export declare function exposeApi(component: ComponentApi, options: {
             time: string;
             dayOfMonth: number | "last";
         } | undefined;
-        text?: string | undefined;
-        timezone?: string | undefined;
-        title?: string | undefined;
         jobId: string;
     }, Promise<any>>;
     deletePushJob: import("convex/server").RegisteredMutation<"public", {
@@ -572,7 +572,7 @@ export declare function exposeApi(component: ComponentApi, options: {
     }, Promise<any>>;
     listQueueItemsForUserAgent: import("convex/server").RegisteredQuery<"public", {
         limit?: number | undefined;
-        statuses?: ("failed" | "done" | "queued" | "processing" | "dead_letter")[] | undefined;
+        statuses?: ("queued" | "processing" | "done" | "failed" | "dead_letter")[] | undefined;
         agentKey: string;
         consumerUserId: string;
     }, Promise<any>>;
@@ -584,8 +584,8 @@ export declare function exposeApi(component: ComponentApi, options: {
     sendMessageToUserAgent: import("convex/server").RegisteredMutation<"public", {
         metadata?: Record<string, string> | undefined;
         agentKey: string;
-        consumerUserId: string;
         content: string;
+        consumerUserId: string;
     }, Promise<any>>;
     listSnapshotsForConversation: import("convex/server").RegisteredQuery<"public", {
         limit?: number | undefined;
@@ -627,15 +627,18 @@ export declare function exposeApi(component: ComponentApi, options: {
         agentKey: string;
         consumerUserId: string;
         companyId: string;
-        timezone: string;
         templateId: string;
+        timezone: string;
     }, Promise<any>>;
     createPushJobCustomForAgent: import("convex/server").RegisteredMutation<"public", {
         enabled?: boolean | undefined;
         agentKey: string;
         consumerUserId: string;
-        companyId: string;
         periodicity: "manual" | "daily" | "weekly" | "monthly";
+        companyId: string;
+        title: string;
+        text: string;
+        timezone: string;
         schedule: {
             kind: "manual";
         } | {
@@ -650,13 +653,13 @@ export declare function exposeApi(component: ComponentApi, options: {
             time: string;
             dayOfMonth: number | "last";
         };
-        text: string;
-        timezone: string;
-        title: string;
     }, Promise<any>>;
     updatePushJobForAgent: import("convex/server").RegisteredMutation<"public", {
-        enabled?: boolean | undefined;
         periodicity?: "manual" | "daily" | "weekly" | "monthly" | undefined;
+        title?: string | undefined;
+        text?: string | undefined;
+        enabled?: boolean | undefined;
+        timezone?: string | undefined;
         schedule?: {
             kind: "manual";
         } | {
@@ -671,9 +674,6 @@ export declare function exposeApi(component: ComponentApi, options: {
             time: string;
             dayOfMonth: number | "last";
         } | undefined;
-        text?: string | undefined;
-        timezone?: string | undefined;
-        title?: string | undefined;
         agentKey: string;
         consumerUserId: string;
         jobId: string;
@@ -706,8 +706,8 @@ export declare function exposeApi(component: ComponentApi, options: {
     }, Promise<any>>;
     sendBroadcastToAllActiveAgents: import("convex/server").RegisteredMutation<"public", {
         companyId: string;
-        text: string;
         title: string;
+        text: string;
         requestedBy: string;
     }, Promise<any>>;
     listPushDispatchesByJob: import("convex/server").RegisteredQuery<"public", {

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAiDhC,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,gBAAgB,EAChB,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,GACjC,MAAM,aAAa,CAAC;AAErB,wBAAgB,SAAS,CACvB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE;IACP,IAAI,EAAE,CACJ,GAAG,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,EACnB,SAAS,EACL;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QACE,IAAI,EAAE,OAAO,CAAC;QACd,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,KACF,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAusCulpB,CAAC;;oBAA+D,CAAC;;;yBAAqH,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAAkmM,CAAC;;oBAA+D,CAAC;;;yBAAqH,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA5Mzi2B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,YAAY,EACvB,EACE,UAA6B,EAC7B,eAAe,EACf,0BAAiC,EACjC,gBAA4B,EAC5B,yBAAiC,EACjC,cAAc,GACf,GAAE;IACD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAC9C,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC5B,QA+KP"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAiDhC,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,gBAAgB,EAChB,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,GACjC,MAAM,aAAa,CAAC;AAErB,wBAAgB,SAAS,CACvB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE;IACP,IAAI,EAAE,CACJ,GAAG,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,EACnB,SAAS,EACL;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QACE,IAAI,EAAE,OAAO,CAAC;QACd,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,KACF,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BA4sC42oB,CAAC;;oBAA+D,CAAC;;;yBAAqH,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAAkmM,CAAC;;oBAA+D,CAAC;;;yBAAqH,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAjN9z1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,YAAY,EACvB,EACE,UAA6B,EAC7B,eAAe,EACf,0BAAiC,EACjC,gBAA4B,EAC5B,yBAAiC,EACjC,cAAc,GACf,GAAE;IACD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAC9C,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC5B,QAoLP"}

package/dist/client/index.js

@@ -226,7 +226,7 @@ export function exposeApi(component, options) {
                 workerId: v.string(),
                 workspaceId: v.string(),
                 agentKey: v.string(),
-                conversationId: v.optional(v.string()),
+                conversationId: v.string(),
                 reason: v.union(v.literal("drain"), v.literal("signal"), v.literal("manual")),
             },
             handler: async (ctx, args) => {
@@ -262,7 +262,7 @@ export function exposeApi(component, options) {
             args: {
                 workspaceId: v.string(),
                 agentKey: v.string(),
-                conversationId: v.optional(v.string()),
+                conversationId: v.string(),
             },
             handler: async (ctx, args) => {
                 await options.auth(ctx, { type: "read" });
@@ -1106,12 +1106,17 @@ export function registerRoutes(http, component, { pathPrefix = "/agent-factory",
                     headers: { "Content-Type": "application/json" },
                 });
             }
-            const mapped = resolveAgentKeyFromBinding
+            const mappedRaw = resolveAgentKeyFromBinding
                 ? await ctx.runQuery(component.lib.resolveAgentForTelegram, {
                     telegramUserId,
                     telegramChatId,
                 })
-                : { consumerUserId: null, agentKey: null };
+                : { consumerUserId: null, agentKey: null, conversationId: null };
+            const mapped = {
+                consumerUserId: mappedRaw.consumerUserId,
+                agentKey: mappedRaw.agentKey,
+                conversationId: "conversationId" in mappedRaw ? mappedRaw.conversationId : null,
+            };
             const configuredAgentKey = resolveAgentKey ? resolveAgentKey(update) : null;
             const agentKey = configuredAgentKey ?? mapped.agentKey ?? fallbackAgentKey;
             if (!agentKey || (requireBindingForTelegram && !configuredAgentKey && !mapped.agentKey)) {
@@ -1167,7 +1172,7 @@ export function registerRoutes(http, component, { pathPrefix = "/agent-factory",
                 metadata.telegramVideoFileId = message.video.file_id;
             }
             await ctx.runMutation(component.lib.enqueue, {
-                conversationId: `telegram:${telegramChatId}`,
+                conversationId: mapped.conversationId ?? `telegram:${telegramChatId}`,
                 agentKey,
                 payload: {
                     provider: "telegram",