@tangle-network/agent-app 0.60.100 → 0.60.101

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,
@@ -37,6 +38,7 @@ import {
37
38
  collectSandboxPromptText,
38
39
  createD1PrewarmClaimStore,
39
40
  createD1WarmLeaseStore,
41
+ createEscalationSpeculator,
40
42
  createSandboxPrewarmer,
41
43
  createSandboxTerminalConnectionRoute,
42
44
  createWarmLeases,
@@ -49,6 +51,7 @@ import {
49
51
  driveSandboxTurn,
50
52
  ensureSandboxToolBinDir,
51
53
  ensureWorkspaceSandbox,
54
+ escalationHints,
52
55
  flattenHistory,
53
56
  getClient,
54
57
  isAutomatedPrewarmRequest,
@@ -56,6 +59,7 @@ import {
56
59
  mergeExtraMcp,
57
60
  mergeHistoryIntoParts,
58
61
  mintSandboxScopedToken,
62
+ parsePrewarmHint,
59
63
  peekWorkspaceSandbox,
60
64
  predictColdArrival,
61
65
  readSandboxBinaryBytes,
@@ -85,7 +89,7 @@ import {
85
89
  warmBinOf,
86
90
  warmWeekdayOf,
87
91
  writeProfileFilesToBox
88
- } from "../chunk-N2UQIEWN.js";
92
+ } from "../chunk-MWJK4HLU.js";
89
93
  import {
90
94
  EGRESS_PROXY_RECOVERY_PHASE,
91
95
  EGRESS_PROXY_RECOVERY_REQUIRED,
@@ -135,6 +139,7 @@ import "../chunk-UGWQLQDS.js";
135
139
  import "../chunk-TMOYOMSW.js";
136
140
  import "../chunk-D6UJEOZQ.js";
137
141
  export {
142
+ DEFAULT_ESCALATION_TOOLS,
138
143
  DEFAULT_FOREGROUND_PROVISION_CLAIM_TTL_SECONDS,
139
144
  DEFAULT_FOREGROUND_PROVISION_POLL_INTERVAL_MS,
140
145
  DEFAULT_PREWARM_CLAIM_TABLE,
@@ -187,6 +192,7 @@ export {
187
192
  collectSandboxPromptText,
188
193
  createD1PrewarmClaimStore,
189
194
  createD1WarmLeaseStore,
195
+ createEscalationSpeculator,
190
196
  createSandboxPrewarmer,
191
197
  createSandboxTerminalConnectionRoute,
192
198
  createWarmLeases,
@@ -200,6 +206,7 @@ export {
200
206
  driveSandboxTurn,
201
207
  ensureSandboxToolBinDir,
202
208
  ensureWorkspaceSandbox,
209
+ escalationHints,
203
210
  flattenHistory,
204
211
  formatSandboxProvisioningSupportDetails,
205
212
  formatSandboxProvisioningUserMessage,
@@ -219,6 +226,7 @@ export {
219
226
  mergeExtraMcp,
220
227
  mergeHistoryIntoParts,
221
228
  mintSandboxScopedToken,
229
+ parsePrewarmHint,
222
230
  peekWorkspaceSandbox,
223
231
  predictColdArrival,
224
232
  preferredWorkspaceSandboxRecoveryBoxKey,
@@ -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. */
@@ -199,7 +202,7 @@ export interface WarmLeasesOptions {
199
202
  absentCooldownMs?: number;
200
203
  /** After a capacity refusal, refuse that key's signals this long. Default 5 min. */
201
204
  capacityCooldownMs?: number;
202
- /** Reasons subject to the budget. Default page-open, member-activity, predicted, scheduled. */
205
+ /** Reasons subject to the budget. Default page-open, member-activity, predicted, scheduled, escalation-likely. */
203
206
  budgetedReasons?: readonly string[];
204
207
  /** Starting predicted-warm threshold, a probability. Default 0.25. */
205
208
  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.101",
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": [