@tangle-network/agent-app 0.60.248 → 0.60.250

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.
@@ -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.250",
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": [