@tangle-network/agent-app 0.60.100 → 0.60.102

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.
@@ -121,9 +121,9 @@ export declare function createPublicConsultation(options: PublicConsultationOpti
121
121
  executionBudget?: ChatTurnExecutionLimits;
122
122
  maxOutputTokens?: number;
123
123
  }) => Promise<{
124
- start?: undefined;
125
124
  status: 'unsupported';
126
125
  reason: string;
126
+ start?: undefined;
127
127
  } | {
128
128
  reason?: undefined;
129
129
  status: 'prepared';
@@ -8,7 +8,7 @@ import {
8
8
  runToolLoop,
9
9
  streamToolLoop,
10
10
  toLoopEvents
11
- } from "../chunk-TQ7K5FRG.js";
11
+ } from "../chunk-3FH4GZ27.js";
12
12
  import {
13
13
  DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR,
14
14
  DEFAULT_TANGLE_ROUTER_BASE_URL,
@@ -43,6 +43,16 @@ export type LoopEvent = {
43
43
  } | {
44
44
  type: 'reasoning';
45
45
  text: string;
46
+ }
47
+ /** The model has begun a tool call: its name is known, its arguments are
48
+ * still streaming. Emitted once per call, before its `tool_call`. Lets a
49
+ * caller start slow work the call will need (resuming a sandbox box for
50
+ * `sandbox_run`) while the arguments arrive. Consumers that do not care
51
+ * ignore it: it never drives the loop. */
52
+ | {
53
+ type: 'tool_call_start';
54
+ toolCallId?: string;
55
+ toolName: string;
46
56
  } | {
47
57
  type: 'tool_call';
48
58
  call: import('@tangle-network/agent-runtime/tool-loop').ToolLoopCall;
@@ -51,6 +51,10 @@ export interface OpenAIStreamChunk {
51
51
  * chunks and emitted as one complete `tool_call` event when the stream finishes
52
52
  * (arguments JSON-parsed; an empty/garbled args string yields `{}` rather than
53
53
  * throwing). Works for the Tangle Router, tcloud, or any OpenAI-compat source.
54
+ *
55
+ * Each call also yields one `tool_call_start` as soon as its name arrives,
56
+ * while its arguments are still streaming, so a caller can start work the call
57
+ * will need. Providers send the whole name in the call's first delta.
54
58
  */
55
59
  export declare function toLoopEvents(chunks: AsyncIterable<OpenAIStreamChunk>): AsyncIterable<LoopEvent>;
56
60
  /**
@@ -0,0 +1,66 @@
1
+ /**
2
+ * `createEscalationSpeculator`: warm a turn's sandbox box when the turn is
3
+ * likely to escalate to it, so `sandbox_run` finds the box running instead of
4
+ * paying the resume (p50 6.4 s on escalated turns, agent turn architecture S8).
5
+ *
6
+ * TWO SIGNALS, CHEAPEST FIRST. Deterministic rules on the turn's input fire
7
+ * before the model is called: an attachment a process must read (PDF, sheet,
8
+ * archive, code), a fenced code block, or words that ask for execution. Then,
9
+ * while the reply streams, `tool_call_start` for an escalation tool fires as
10
+ * soon as the model names it, seconds before its arguments finish. Either one
11
+ * signals the box's warm lease with reason `escalation-likely`, at most once
12
+ * per turn.
13
+ *
14
+ * NEVER GATES. Signals are fire-and-forget: the lease dedupes across isolates,
15
+ * charges unused warms to the key's daily budget (`escalation-likely` is a
16
+ * budgeted reason), and backs off on capacity. A speculation that is wrong
17
+ * costs box time within that budget; it never delays or fails the turn.
18
+ *
19
+ * MEASURING IT. The `sandbox_run` binding calls `leases.turn(boxKey)` when the
20
+ * tool runs. A `warm_hit` with reason `escalation-likely` is a box the
21
+ * speculation made ready in time. The S8 number is that count over all
22
+ * escalated turns.
23
+ *
24
+ * Off unless the app passes `mode: 'deterministic'` (from `SANDBOX_PREWARM_HINT`).
25
+ */
26
+ /** `SANDBOX_PREWARM_HINT`: `off` (default) or `deterministic`. */
27
+ export type PrewarmHintMode = 'off' | 'deterministic';
28
+ export declare function parsePrewarmHint(value: string | undefined | null): PrewarmHintMode;
29
+ /** Why a turn was judged likely to escalate. */
30
+ export type EscalationHint = 'attachment' | 'code-block' | 'execution-words' | 'tool-call-start';
31
+ export interface EscalationInput {
32
+ text?: string;
33
+ attachments?: ReadonlyArray<{
34
+ mediaType?: string;
35
+ name?: string;
36
+ }>;
37
+ }
38
+ /** The tools that run in the box. A `tool_call_start` for one of these warms it. */
39
+ export declare const DEFAULT_ESCALATION_TOOLS: readonly ['sandbox_run', 'sandbox_exec'];
40
+ /** Pure: the reasons this input suggests the turn will need the box, if any. */
41
+ export declare function escalationHints(input: EscalationInput): EscalationHint[];
42
+ export interface EscalationSpeculatorOptions {
43
+ mode: PrewarmHintMode;
44
+ /** The box's warm lease; only `signal` is used. */
45
+ leases: {
46
+ signal(key: string, reason: 'escalation-likely'): Promise<unknown>;
47
+ };
48
+ /** The warm-lease key of the box `sandbox_run` would use for this turn. */
49
+ boxKey: string;
50
+ escalationTools?: readonly string[];
51
+ /** Observability: called once, when the turn's warm is signalled. */
52
+ onSpeculate?(hint: EscalationHint): void;
53
+ }
54
+ export interface EscalationSpeculator {
55
+ /** Call with the turn's input before the model call. */
56
+ onInput(input: EscalationInput): void;
57
+ /** Call with each event the model stream yields. Non-tool events are ignored. */
58
+ onEvent(event: {
59
+ type: string;
60
+ toolName?: string;
61
+ }): void;
62
+ /** The hint that fired for this turn, if any. */
63
+ readonly fired: EscalationHint | null;
64
+ }
65
+ /** One speculator per turn. */
66
+ export declare function createEscalationSpeculator(options: EscalationSpeculatorOptions): EscalationSpeculator;
@@ -879,3 +879,4 @@ export * from './prewarm-route';
879
879
  export * from './foreground-single-flight';
880
880
  export * from './warm-lease';
881
881
  export * from './warm-lease-d1';
882
+ export * from './escalation-speculator';
@@ -1,4 +1,5 @@
1
1
  import {
2
+ DEFAULT_ESCALATION_TOOLS,
2
3
  DEFAULT_FOREGROUND_PROVISION_CLAIM_TTL_SECONDS,
3
4
  DEFAULT_FOREGROUND_PROVISION_POLL_INTERVAL_MS,
4
5
  DEFAULT_PREWARM_CLAIM_TABLE,
@@ -18,6 +19,7 @@ import {
18
19
  SandboxRecoveryFailedError,
19
20
  SandboxRuntimeAuthRefreshError,
20
21
  WARM_LEASE_DECLINED_UNTIL_DDL,
22
+ WARM_LEASE_PENDING_DDL,
21
23
  WARM_LEASE_TABLE_DDL,
22
24
  WARM_SLOTS,
23
25
  adaptSandboxStream,
@@ -37,6 +39,7 @@ import {
37
39
  collectSandboxPromptText,
38
40
  createD1PrewarmClaimStore,
39
41
  createD1WarmLeaseStore,
42
+ createEscalationSpeculator,
40
43
  createSandboxPrewarmer,
41
44
  createSandboxTerminalConnectionRoute,
42
45
  createWarmLeases,
@@ -49,6 +52,7 @@ import {
49
52
  driveSandboxTurn,
50
53
  ensureSandboxToolBinDir,
51
54
  ensureWorkspaceSandbox,
55
+ escalationHints,
52
56
  flattenHistory,
53
57
  getClient,
54
58
  isAutomatedPrewarmRequest,
@@ -56,6 +60,7 @@ import {
56
60
  mergeExtraMcp,
57
61
  mergeHistoryIntoParts,
58
62
  mintSandboxScopedToken,
63
+ parsePrewarmHint,
59
64
  peekWorkspaceSandbox,
60
65
  predictColdArrival,
61
66
  readSandboxBinaryBytes,
@@ -85,7 +90,7 @@ import {
85
90
  warmBinOf,
86
91
  warmWeekdayOf,
87
92
  writeProfileFilesToBox
88
- } from "../chunk-N2UQIEWN.js";
93
+ } from "../chunk-P2EKAQUB.js";
89
94
  import {
90
95
  EGRESS_PROXY_RECOVERY_PHASE,
91
96
  EGRESS_PROXY_RECOVERY_REQUIRED,
@@ -135,6 +140,7 @@ import "../chunk-UGWQLQDS.js";
135
140
  import "../chunk-TMOYOMSW.js";
136
141
  import "../chunk-D6UJEOZQ.js";
137
142
  export {
143
+ DEFAULT_ESCALATION_TOOLS,
138
144
  DEFAULT_FOREGROUND_PROVISION_CLAIM_TTL_SECONDS,
139
145
  DEFAULT_FOREGROUND_PROVISION_POLL_INTERVAL_MS,
140
146
  DEFAULT_PREWARM_CLAIM_TABLE,
@@ -159,6 +165,7 @@ export {
159
165
  SandboxRuntimeAuthRefreshError,
160
166
  SandboxTransientDeadlineError,
161
167
  WARM_LEASE_DECLINED_UNTIL_DDL,
168
+ WARM_LEASE_PENDING_DDL,
162
169
  WARM_LEASE_TABLE_DDL,
163
170
  WARM_SLOTS,
164
171
  WORKSPACE_SANDBOX_HOST_EXHAUSTED,
@@ -187,6 +194,7 @@ export {
187
194
  collectSandboxPromptText,
188
195
  createD1PrewarmClaimStore,
189
196
  createD1WarmLeaseStore,
197
+ createEscalationSpeculator,
190
198
  createSandboxPrewarmer,
191
199
  createSandboxTerminalConnectionRoute,
192
200
  createWarmLeases,
@@ -200,6 +208,7 @@ export {
200
208
  driveSandboxTurn,
201
209
  ensureSandboxToolBinDir,
202
210
  ensureWorkspaceSandbox,
211
+ escalationHints,
203
212
  flattenHistory,
204
213
  formatSandboxProvisioningSupportDetails,
205
214
  formatSandboxProvisioningUserMessage,
@@ -219,6 +228,7 @@ export {
219
228
  mergeExtraMcp,
220
229
  mergeHistoryIntoParts,
221
230
  mintSandboxScopedToken,
231
+ parsePrewarmHint,
222
232
  peekWorkspaceSandbox,
223
233
  predictColdArrival,
224
234
  preferredWorkspaceSandboxRecoveryBoxKey,
@@ -15,9 +15,11 @@ import { type WarmLeaseStore } from './warm-lease';
15
15
  */
16
16
  export declare const DEFAULT_WARM_LEASE_TABLE = "sandbox_warm_lease";
17
17
  /** Paste into a migration. Times are epoch milliseconds; 0 means never. */
18
- export declare const WARM_LEASE_TABLE_DDL = "CREATE TABLE IF NOT EXISTS sandbox_warm_lease (\n key TEXT PRIMARY KEY,\n lease_id TEXT,\n reason TEXT,\n started_at INTEGER NOT NULL DEFAULT 0,\n hold_until INTEGER NOT NULL DEFAULT 0,\n warm_at INTEGER NOT NULL DEFAULT 0,\n used_at INTEGER NOT NULL DEFAULT 0,\n resumed INTEGER NOT NULL DEFAULT 0,\n ping_at INTEGER NOT NULL DEFAULT 0,\n last_turn_at INTEGER NOT NULL DEFAULT 0,\n day TEXT NOT NULL DEFAULT '',\n day_warm_ms INTEGER NOT NULL DEFAULT 0,\n threshold REAL NOT NULL DEFAULT 0,\n slots TEXT NOT NULL DEFAULT '',\n slots_at INTEGER NOT NULL DEFAULT 0,\n first_seen_at INTEGER NOT NULL DEFAULT 0,\n predicted_at INTEGER NOT NULL DEFAULT 0,\n declined_until INTEGER NOT NULL DEFAULT 0\n)";
18
+ export declare const WARM_LEASE_TABLE_DDL = "CREATE TABLE IF NOT EXISTS sandbox_warm_lease (\n key TEXT PRIMARY KEY,\n lease_id TEXT,\n reason TEXT,\n started_at INTEGER NOT NULL DEFAULT 0,\n hold_until INTEGER NOT NULL DEFAULT 0,\n warm_at INTEGER NOT NULL DEFAULT 0,\n used_at INTEGER NOT NULL DEFAULT 0,\n resumed INTEGER NOT NULL DEFAULT 0,\n ping_at INTEGER NOT NULL DEFAULT 0,\n last_turn_at INTEGER NOT NULL DEFAULT 0,\n day TEXT NOT NULL DEFAULT '',\n day_warm_ms INTEGER NOT NULL DEFAULT 0,\n threshold REAL NOT NULL DEFAULT 0,\n slots TEXT NOT NULL DEFAULT '',\n slots_at INTEGER NOT NULL DEFAULT 0,\n first_seen_at INTEGER NOT NULL DEFAULT 0,\n predicted_at INTEGER NOT NULL DEFAULT 0,\n declined_until INTEGER NOT NULL DEFAULT 0,\n pending_warm_at INTEGER NOT NULL DEFAULT 0,\n pending_ms INTEGER NOT NULL DEFAULT 0,\n pending_reason TEXT\n)";
19
19
  /** For a table created from an earlier \`WARM_LEASE_TABLE_DDL\`: paste into a migration. */
20
20
  export declare const WARM_LEASE_DECLINED_UNTIL_DDL = "ALTER TABLE sandbox_warm_lease ADD COLUMN declined_until INTEGER NOT NULL DEFAULT 0";
21
+ /** For a table created before pending charges: paste each into a migration. */
22
+ export declare const WARM_LEASE_PENDING_DDL: readonly ["ALTER TABLE sandbox_warm_lease ADD COLUMN pending_warm_at INTEGER NOT NULL DEFAULT 0", "ALTER TABLE sandbox_warm_lease ADD COLUMN pending_ms INTEGER NOT NULL DEFAULT 0", "ALTER TABLE sandbox_warm_lease ADD COLUMN pending_reason TEXT"];
21
23
  /** The D1 surface this store uses: `prepare().bind()` with `first`, `run` and `all`. A real `D1Database` satisfies it. */
22
24
  export interface WarmLeaseD1Like {
23
25
  prepare(query: string): {
@@ -40,7 +40,10 @@
40
40
  * rate and wasted minutes per workspace from its logs alone.
41
41
  */
42
42
  /** Why a warm was requested. Products may add their own reasons. */
43
- export type WarmReason = 'page-open' | 'composer-focus' | 'line-ingress' | 'member-activity' | 'predicted' | 'scheduled' | (string & {});
43
+ export type WarmReason = 'page-open' | 'composer-focus' | 'line-ingress' | 'member-activity' | 'predicted' | 'scheduled'
44
+ /** A turn is likely to call a sandbox tool (deterministic input rules, or a
45
+ * `sandbox_run` call starting to stream). See `createEscalationSpeculator`. */
46
+ | 'escalation-likely' | (string & {});
44
47
  /** What the product's `warm` did to the box. */
45
48
  export type WarmBoxOutcome =
46
49
  /** The box was stopped and is now running: this warm caused its up-time. */
@@ -135,6 +138,12 @@ export interface WarmLeaseRow {
135
138
  /** Signals are refused without calling the product's warm until this time:
136
139
  * set after an 'absent' or 'capacity' outcome, cleared by a turn. */
137
140
  declinedUntil: number;
141
+ /** An ended, unused warm whose box may still be up: settled at the span no
142
+ * turn used, when a turn arrives or its idle window closes. 0 when none. */
143
+ pendingWarmAt: number;
144
+ /** The most the pending warm can be charged: until the box's idle timeout. */
145
+ pendingMs: number;
146
+ pendingReason: string | null;
138
147
  }
139
148
  /** Persistence for leases. `begin` and `markUsed` must be atomic across isolates. */
140
149
  export interface WarmLeaseStore {
@@ -167,6 +176,16 @@ export interface WarmLeaseStore {
167
176
  markPredicted(key: string, at: number): Promise<void>;
168
177
  /** Refuse signals for `key` until `until` (cleared by the next turn). */
169
178
  markDeclined(key: string, until: number): Promise<void>;
179
+ /** Record an ended, unused warm whose charge is settled later. */
180
+ markPending(key: string, warmAt: number, maxMs: number, reason: string): Promise<void>;
181
+ /**
182
+ * Charge the pending warm that started at `warmAt` `chargeMs` to `day` and
183
+ * clear it. Only the first settler of a given warm succeeds (a turn and a
184
+ * sweep may race); returns whether this call settled it.
185
+ */
186
+ settlePending(key: string, warmAt: number, day: string, chargeMs: number): Promise<boolean>;
187
+ /** Pending warms whose idle window has closed by `now`. */
188
+ listPendingDue(now: number, limit: number): Promise<WarmLeaseRow[]>;
170
189
  /** Bounded batches for `sweep`. */
171
190
  listExpired(now: number, limit: number): Promise<WarmLeaseRow[]>;
172
191
  listHeld(now: number, limit: number): Promise<WarmLeaseRow[]>;
@@ -199,7 +218,7 @@ export interface WarmLeasesOptions {
199
218
  absentCooldownMs?: number;
200
219
  /** After a capacity refusal, refuse that key's signals this long. Default 5 min. */
201
220
  capacityCooldownMs?: number;
202
- /** Reasons subject to the budget. Default page-open, member-activity, predicted, scheduled. */
221
+ /** Reasons subject to the budget. Default page-open, member-activity, predicted, scheduled, escalation-likely. */
203
222
  budgetedReasons?: readonly string[];
204
223
  /** Starting predicted-warm threshold, a probability. Default 0.25. */
205
224
  initialThreshold?: number;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tangle-network/agent-app",
3
- "version": "0.60.100",
3
+ "version": "0.60.102",
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": [