@tangle-network/agent-app 0.60.248 → 0.60.249

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,7 @@ import {
3
3
  } from "./chunk-L7MB2LLM.js";
4
4
  import {
5
5
  useWorkspacePrewarmHandle
6
- } from "./chunk-OXUBZ5SE.js";
6
+ } from "./chunk-2HQP2CTA.js";
7
7
  import {
8
8
  filterCommandPaletteItems
9
9
  } from "./chunk-SJWIZT7B.js";
@@ -1603,4 +1603,4 @@ export {
1603
1603
  ComposerModeControls,
1604
1604
  EntryComposer
1605
1605
  };
1606
- //# sourceMappingURL=chunk-WCXHXCER.js.map
1606
+ //# sourceMappingURL=chunk-63QAQP7I.js.map
@@ -15,6 +15,7 @@ export * from './sandbox-run-tool';
15
15
  export * from './sandbox-exec-tool';
16
16
  export * from './prewarm-claim-d1';
17
17
  export * from './prewarm-route';
18
+ export * from './warm-receipts';
18
19
  export * from './foreground-single-flight';
19
20
  export * from './warm-lease';
20
21
  export * from './warm-lease-d1';
@@ -6,6 +6,7 @@ import {
6
6
  DEFAULT_PROVISION_TIMEOUT_MS,
7
7
  DEFAULT_SANDBOX_RESOURCES,
8
8
  DEFAULT_WARM_LEASE_TABLE,
9
+ DEFAULT_WARM_RECEIPT_TABLE,
9
10
  ENV_TOTAL_MAX_BYTES,
10
11
  ENV_VALUE_MAX_BYTES,
11
12
  PREWARM_CLAIM_TABLE_DDL,
@@ -25,6 +26,7 @@ import {
25
26
  WARM_LEASE_DECLINED_UNTIL_DDL,
26
27
  WARM_LEASE_PENDING_DDL,
27
28
  WARM_LEASE_TABLE_DDL,
29
+ WARM_RECEIPT_TABLE_DDL,
28
30
  WARM_SLOTS,
29
31
  adaptSandboxStream,
30
32
  addColdArrival,
@@ -44,7 +46,9 @@ import {
44
46
  createCacheReuseStore,
45
47
  createD1PrewarmClaimStore,
46
48
  createD1WarmLeaseStore,
49
+ createD1WarmReceiptStore,
47
50
  createEscalationSpeculator,
51
+ createMemoryWarmReceiptStore,
48
52
  createSandboxExecTool,
49
53
  createSandboxPrewarmer,
50
54
  createSandboxRunTool,
@@ -98,9 +102,11 @@ import {
98
102
  traceSandboxPromptEvents,
99
103
  utcDay,
100
104
  warmBinOf,
105
+ warmKey,
106
+ warmReceiptId,
101
107
  warmWeekdayOf,
102
108
  writeProfileFilesToBox
103
- } from "../chunk-CFGBGIRK.js";
109
+ } from "../chunk-5Y7Z5G3Y.js";
104
110
  import {
105
111
  EGRESS_PROXY_RECOVERY_PHASE,
106
112
  EGRESS_PROXY_RECOVERY_REQUIRED,
@@ -160,6 +166,7 @@ export {
160
166
  DEFAULT_PROVISION_TIMEOUT_MS,
161
167
  DEFAULT_SANDBOX_RESOURCES,
162
168
  DEFAULT_WARM_LEASE_TABLE,
169
+ DEFAULT_WARM_RECEIPT_TABLE,
163
170
  EGRESS_PROXY_RECOVERY_PHASE,
164
171
  EGRESS_PROXY_RECOVERY_REQUIRED,
165
172
  ENV_TOTAL_MAX_BYTES,
@@ -184,6 +191,7 @@ export {
184
191
  WARM_LEASE_DECLINED_UNTIL_DDL,
185
192
  WARM_LEASE_PENDING_DDL,
186
193
  WARM_LEASE_TABLE_DDL,
194
+ WARM_RECEIPT_TABLE_DDL,
187
195
  WARM_SLOTS,
188
196
  WORKSPACE_SANDBOX_HOST_EXHAUSTED,
189
197
  WORKSPACE_SANDBOX_MISSING,
@@ -212,7 +220,9 @@ export {
212
220
  createCacheReuseStore,
213
221
  createD1PrewarmClaimStore,
214
222
  createD1WarmLeaseStore,
223
+ createD1WarmReceiptStore,
215
224
  createEscalationSpeculator,
225
+ createMemoryWarmReceiptStore,
216
226
  createSandboxExecTool,
217
227
  createSandboxPrewarmer,
218
228
  createSandboxRunTool,
@@ -284,6 +294,8 @@ export {
284
294
  traceSandboxPromptEvents,
285
295
  utcDay,
286
296
  warmBinOf,
297
+ warmKey,
298
+ warmReceiptId,
287
299
  warmWeekdayOf,
288
300
  workspaceSandboxRecoveryDiagnostic,
289
301
  workspaceSandboxRecoveryFromError,
@@ -1,36 +1,4 @@
1
- /**
2
- * `createWorkspacePrewarmRoute`: the HTTP face of prewarm-on-open, so every
3
- * agent-app product warms the same way. The browser half is
4
- * `useWorkspacePrewarm` in `/web-react`: it POSTs here when a member opens a
5
- * workspace page in a visible tab, and again when they focus the composer.
6
- *
7
- * WHAT THE PRODUCT SUPPLIES. Only `authorize`. It authenticates the member
8
- * from the request exactly as the product's other routes do and returns the
9
- * warm to run: a box resume, a profile preparation, or `createSandboxPrewarmer`
10
- * from this subpath. The route owns everything shared: bot and prefetch
11
- * refusal, per-key single-flight, a short success memory, timing, and the rule
12
- * that a warm never reaches the member as an error.
13
- *
14
- * WHY THE WARM RUNS INSIDE THE REQUEST. A suspended box takes ~31 s to resume
15
- * (Hospitality production, 2026-10-10), past the 30 s that Cloudflare's
16
- * `waitUntil` grants after a response. Awaiting the warm keeps the request
17
- * open for as long as the member's tab is, which is exactly as long as a warm
18
- * is useful. The browser never awaits it for UI.
19
- *
20
- * IDEMPOTENCE. The in-process record only collapses concurrent calls within
21
- * one isolate, and a second call answers `joined` at once instead of awaiting
22
- * the first: on Workers a warm's I/O belongs to the request that started it, so
23
- * when that request is cancelled (the member navigates) its promise never
24
- * settles, and requests awaiting it hung 43-45 s (Hospitality production,
25
- * 2026-10-11). A record older than `staleMs` no longer counts. Two isolates can
26
- * both run the warm, so the product's warm must be safe to repeat: a resume of
27
- * a running box is a no-op, and a creation needs a claim store (see
28
- * `createSandboxPrewarmer`).
29
- *
30
- * FAILURE. A thrown warm answers 200 `{ outcome: 'failed' }` without the error
31
- * text, which can name internal hosts. `onEvent` receives the error so the
32
- * product can log it. The next real turn takes its normal placement path.
33
- */
1
+ import { type WarmReceiptStore } from './warm-receipts';
34
2
  /** What the product decided for this request. */
35
3
  export type WorkspacePrewarmAuthorization =
36
4
  /** Not signed in, not a member, or a foreign origin: return this response. */
@@ -53,9 +21,32 @@ export type WorkspacePrewarmAuthorization =
53
21
  status: 'allowed';
54
22
  key: string;
55
23
  warm: () => Promise<WorkspacePrewarmReport | void>;
24
+ }
25
+ /** Run each step whose key has no unexpired receipt. */
26
+ | {
27
+ status: 'allowed';
28
+ steps: readonly WorkspaceWarmStep[];
56
29
  };
57
- /** Why the browser asked: `useWorkspacePrewarm` sends `page-open` or `composer-focus`. */
58
- export type WorkspacePrewarmReason = 'page-open' | 'composer-focus';
30
+ /** One warm step, keyed by exactly what it depends on. */
31
+ export interface WorkspaceWarmStep {
32
+ /** A short name, unique within the response: `session`, `vault_heads`, `tool_catalog`, `box`. */
33
+ name: string;
34
+ /** What the step depends on (`warmKey({ userId, workspaceId, vaultHead })`). Members who share the result share the key. */
35
+ key: string;
36
+ /** How long a successful run counts. Keep it shorter than the warmed thing's own idle expiry (a box that suspends
37
+ * after 5 idle minutes gets a TTL well under that), because a receipt cannot see the thing go cold. */
38
+ ttlMs: number;
39
+ /** Do the work. The report, small JSON and never a credential, is stored on the receipt for the turn to read. */
40
+ run: () => Promise<WorkspacePrewarmReport | void>;
41
+ }
42
+ /** Why the browser asked: `useWorkspacePrewarm` sends `page-open`, `composer-focus`, or `heartbeat` while the tab stays open. */
43
+ export type WorkspacePrewarmReason = 'page-open' | 'composer-focus' | 'heartbeat';
44
+ export type WorkspaceWarmStepOutcome = 'hit' | 'miss' | 'joined' | 'failed';
45
+ export interface WorkspaceWarmStepResult {
46
+ name: string;
47
+ outcome: WorkspaceWarmStepOutcome;
48
+ ms: number;
49
+ }
59
50
  export type WorkspacePrewarmReport = Record<string, string | number | boolean | null>;
60
51
  export type WorkspacePrewarmOutcome =
61
52
  /** This request ran the warm to completion. */
@@ -72,6 +63,8 @@ export interface WorkspacePrewarmResponse {
72
63
  ms: number;
73
64
  reason?: string;
74
65
  report?: WorkspacePrewarmReport;
66
+ /** Each step's outcome, for an authorization that returned `steps`. */
67
+ steps?: WorkspaceWarmStepResult[];
75
68
  }
76
69
  export type WorkspacePrewarmEvent = {
77
70
  type: 'warmed';
@@ -83,15 +76,28 @@ export type WorkspacePrewarmEvent = {
83
76
  key: string;
84
77
  ms: number;
85
78
  error: string;
79
+ }
80
+ /** One step of a stepped warm; `failed` carries the error. */
81
+ | {
82
+ type: 'step';
83
+ name: string;
84
+ key: string;
85
+ outcome: WorkspaceWarmStepOutcome;
86
+ ms: number;
87
+ error?: string;
86
88
  };
87
89
  export interface CreateWorkspacePrewarmRouteOptions<Context = void> {
88
90
  /** `context` is whatever the caller passed beside the request, such as a
89
91
  * Hono context carrying the Worker's bindings. */
92
+ /** `threadId` is the thread the composer belongs to, when the browser sent one (composer focus). Check the member's access to it before warming anything for it. */
90
93
  authorize(input: {
91
94
  request: Request;
92
95
  context: Context;
93
96
  reason: WorkspacePrewarmReason;
97
+ threadId?: string;
94
98
  }): Promise<WorkspacePrewarmAuthorization>;
99
+ /** Where step receipts live across isolates (`createD1WarmReceiptStore`). Without it, receipts last for this isolate only. */
100
+ receipts?: WarmReceiptStore;
95
101
  /** After a successful warm, answer `recent` for this long. Default 30 000 ms. */
96
102
  recentMs?: number;
97
103
  /** A warm started longer ago than this no longer blocks the key: its request
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Warm receipts: the record that a warm step already ran for exactly the
3
+ * inputs it depends on, so a second warm with the same inputs does no work.
4
+ *
5
+ * A warm step (verify the session, resolve a child key, read the vault heads,
6
+ * build the connected-tool catalog, resume the box) is keyed by what it
7
+ * depends on: identity, workspace, thread, content hash, credential expiry.
8
+ * `createWorkspacePrewarmRoute` looks the key up before it runs the step; an
9
+ * unexpired receipt answers `hit` after one read and the step does not run.
10
+ * The turn reads the same receipt at send to reuse what the warm produced.
11
+ *
12
+ * The receipt store is shared across isolates (D1), because Workers spread one
13
+ * member's requests over many isolates: an in-isolate cache missed on 2 of 3
14
+ * warm turns in Creative staging (2026-10-21, connected-tool catalog 928-2,742
15
+ * ms). The route still keeps an in-isolate copy, so a repeat in the same
16
+ * isolate costs no read at all.
17
+ *
18
+ * A receipt's `report` is small JSON the product chooses (a vault head, a
19
+ * catalog digest, a box id). It must never hold a credential: receipts are
20
+ * rows any reader of the table can see.
21
+ */
22
+ export type WarmReceiptReport = Record<string, string | number | boolean | null>;
23
+ export interface WarmReceipt {
24
+ /** Epoch ms the step finished. */
25
+ at: number;
26
+ /** Epoch ms after which the receipt no longer counts. */
27
+ expiresAt: number;
28
+ report?: WarmReceiptReport;
29
+ }
30
+ export interface WarmReceiptStore {
31
+ get(id: string): Promise<WarmReceipt | null>;
32
+ put(id: string, receipt: WarmReceipt): Promise<void>;
33
+ }
34
+ /** The receipt id for one step and its key. */
35
+ export declare function warmReceiptId(step: string, key: string): string;
36
+ /**
37
+ * A warm key from exactly the values a step depends on: the same values give
38
+ * the same key whatever their order, and any change gives a new one. Values
39
+ * are hashed (SHA-256, hex), so a key names no member, path or expiry in the
40
+ * clear. Pass a credential's expiry or revision, never the credential.
41
+ */
42
+ export declare function warmKey(parts: Record<string, string | number | boolean | null>): Promise<string>;
43
+ /** Receipts in one isolate's memory: for tests and single-process hosts. */
44
+ export declare function createMemoryWarmReceiptStore(options?: {
45
+ limit?: number;
46
+ }): WarmReceiptStore;
47
+ /** The D1 surface the store uses. A real `D1Database` satisfies it. */
48
+ export interface WarmReceiptD1Like {
49
+ prepare(query: string): {
50
+ bind(...values: unknown[]): {
51
+ first<T = Record<string, unknown>>(): Promise<T | null>;
52
+ run(): Promise<unknown>;
53
+ };
54
+ };
55
+ }
56
+ export declare const DEFAULT_WARM_RECEIPT_TABLE = "warm_receipts";
57
+ /** Paste into a product migration; the store never runs DDL. Times are epoch ms. */
58
+ export declare const WARM_RECEIPT_TABLE_DDL = "CREATE TABLE IF NOT EXISTS warm_receipts (\n id TEXT PRIMARY KEY,\n at INTEGER NOT NULL,\n expires_at INTEGER NOT NULL,\n report TEXT\n);\nCREATE INDEX IF NOT EXISTS warm_receipts_by_expiry ON warm_receipts (expires_at)";
59
+ /**
60
+ * Receipts in one D1 table, shared by every isolate. A missing table throws on
61
+ * the first read, which the route treats as a miss: the step runs, and the
62
+ * failure reaches `onEvent`.
63
+ */
64
+ export declare function createD1WarmReceiptStore(db: WarmReceiptD1Like, options?: {
65
+ table?: string;
66
+ now?: () => number;
67
+ }): WarmReceiptStore;
@@ -181,7 +181,7 @@ import {
181
181
  preloadWhenIdle,
182
182
  useComposerAttachments,
183
183
  useDictation
184
- } from "../chunk-WCXHXCER.js";
184
+ } from "../chunk-63QAQP7I.js";
185
185
  import "../chunk-L7MB2LLM.js";
186
186
  import {
187
187
  WorkspaceInitial,
@@ -192,7 +192,7 @@ import {
192
192
  requestWorkspacePrewarm,
193
193
  useWorkspacePrewarm,
194
194
  useWorkspacePrewarmHandle
195
- } from "../chunk-OXUBZ5SE.js";
195
+ } from "../chunk-2HQP2CTA.js";
196
196
  import {
197
197
  tabTerminalConnectionId,
198
198
  useSandboxTerminalConnection
@@ -6,9 +6,12 @@
6
6
  *
7
7
  * Fires only from a visible, non-prerendered document. A tab opened in the
8
8
  * background fires when it first becomes visible. Requests for the same URL
9
- * are spaced by `minIntervalMs` across every mount in the tab, so navigating
10
- * between pages of one workspace sends one request, not one per page. Call
11
- * `reassert()` on composer focus: a box can suspend while a tab sits open.
9
+ * and reason are spaced by `minIntervalMs` across every mount in the tab, so
10
+ * navigating between pages of one workspace sends one request, not one per
11
+ * page. Call `reassert()` on composer focus: a box can suspend while a tab sits
12
+ * open, and focus warms the thread itself. While the tab stays visible it sends
13
+ * a `heartbeat` every `heartbeatMs`, so what is warm stays warm; the route's
14
+ * receipts make a heartbeat over warm state cost one read.
12
15
  *
13
16
  * Failures are silent by design. A warm is an optimization; the turn itself
14
17
  * still places the box, so nothing here may surface to the member.
@@ -17,13 +20,18 @@ export interface WorkspacePrewarmRequestOptions {
17
20
  /** Minimum gap between requests for the same URL in this tab. Default 60 000 ms. */
18
21
  minIntervalMs?: number;
19
22
  /** Sent to the route so a product can budget page opens apart from composer focus. Default `page-open`. */
20
- reason?: 'page-open' | 'composer-focus';
23
+ reason?: 'page-open' | 'composer-focus' | 'heartbeat';
24
+ /** The thread the composer belongs to, so composer focus can warm that thread. */
25
+ threadId?: string;
21
26
  }
22
27
  export interface UseWorkspacePrewarmOptions extends WorkspacePrewarmRequestOptions {
23
28
  /** The product's prewarm route for this workspace. Empty disables. */
24
29
  url: string | null | undefined;
25
30
  /** False until the member is known to be signed in and allowed to chat. Default true. */
26
31
  enabled?: boolean;
32
+ /** Re-warm this often while the tab is visible and the member has used the page since the last beat (a key,
33
+ * pointer or scroll), so an idle tab lets the box park. Default 240 000 ms; 0 disables. */
34
+ heartbeatMs?: number;
27
35
  }
28
36
  export interface WorkspacePrewarmHandle {
29
37
  /** Ask again, subject to the same visibility and spacing rules. */
@@ -7,7 +7,7 @@ import {
7
7
  import {
8
8
  WorkspacePrewarmContext,
9
9
  useWorkspacePrewarm
10
- } from "../chunk-OXUBZ5SE.js";
10
+ } from "../chunk-2HQP2CTA.js";
11
11
  import {
12
12
  buildSessionNavItem,
13
13
  composeSidebarSessions,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tangle-network/agent-app",
3
- "version": "0.60.248",
3
+ "version": "0.60.249",
4
4
  "packageManager": "pnpm@11.24.0",
5
5
  "description": "Build agent applications with typed chat, tools, sandboxes, integrations, billing, and evaluation.",
6
6
  "keywords": [