@bluecopa/harness 0.1.0-snapshot.133 → 0.1.0-snapshot.135
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.
package/dist/arc/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { A as AnyTool, T as ToolProvider, a as ToolResult, M as ModelFactory, b as ToolResultArtifact
|
|
2
|
-
export {
|
|
3
|
-
import
|
|
1
|
+
import { A as AnyTool, T as ToolProvider, a as ToolResult, M as ModelFactory, b as ToolResultArtifact } from '../shared-types-DRxnerLT.js';
|
|
2
|
+
export { c as ActionType, B as BashOptions, d as BatchOp, e as BatchResult, G as GlobOptions, f as GrepOptions, R as ReadOptions, g as TextEditorRequest, h as ThreadStatus, i as ToolProviderCapabilities, W as WebFetchOptions } from '../shared-types-DRxnerLT.js';
|
|
3
|
+
import 'ai';
|
|
4
4
|
|
|
5
5
|
interface ToolCallInfo {
|
|
6
6
|
toolCallId: string;
|
|
@@ -32,78 +32,6 @@ interface AgentMessage {
|
|
|
32
32
|
/** Provider-specific metadata preserved across round-trips (e.g., Gemini thought signatures). */
|
|
33
33
|
providerMetadata?: Record<string, unknown>;
|
|
34
34
|
}
|
|
35
|
-
interface ToolCallAction {
|
|
36
|
-
type: "tool";
|
|
37
|
-
name: string;
|
|
38
|
-
args: Record<string, unknown>;
|
|
39
|
-
toolCallId?: string;
|
|
40
|
-
/** Provider-specific metadata preserved across round-trips (e.g., Gemini thought signatures). */
|
|
41
|
-
providerMetadata?: Record<string, unknown>;
|
|
42
|
-
/** Short user-visible rationale text emitted before the tool call. */
|
|
43
|
-
publicRationale?: string;
|
|
44
|
-
}
|
|
45
|
-
interface FinalAction {
|
|
46
|
-
type: "final";
|
|
47
|
-
content: string;
|
|
48
|
-
}
|
|
49
|
-
interface ToolBatchAction {
|
|
50
|
-
type: "tool_batch";
|
|
51
|
-
calls: ToolCallAction[];
|
|
52
|
-
/** Short user-visible rationale text emitted before the tool batch. */
|
|
53
|
-
publicRationale?: string;
|
|
54
|
-
}
|
|
55
|
-
type AgentAction = ToolCallAction | FinalAction | ToolBatchAction;
|
|
56
|
-
/** Token usage breakdown for a single LLM step. */
|
|
57
|
-
interface StepUsage {
|
|
58
|
-
inputTokens?: number;
|
|
59
|
-
outputTokens?: number;
|
|
60
|
-
cacheReadTokens?: number;
|
|
61
|
-
cacheWriteTokens?: number;
|
|
62
|
-
reasoningTokens?: number;
|
|
63
|
-
}
|
|
64
|
-
type AgentStreamEvent = {
|
|
65
|
-
type: "text_delta";
|
|
66
|
-
text: string;
|
|
67
|
-
} | {
|
|
68
|
-
type: "tool_start";
|
|
69
|
-
name: string;
|
|
70
|
-
args: Record<string, unknown>;
|
|
71
|
-
toolCallId?: string;
|
|
72
|
-
} | {
|
|
73
|
-
type: "tool_end";
|
|
74
|
-
name: string;
|
|
75
|
-
result: {
|
|
76
|
-
success: boolean;
|
|
77
|
-
output: string;
|
|
78
|
-
error?: string;
|
|
79
|
-
[key: string]: unknown;
|
|
80
|
-
};
|
|
81
|
-
} | {
|
|
82
|
-
type: "step_start";
|
|
83
|
-
step: number;
|
|
84
|
-
} | {
|
|
85
|
-
type: "step_end";
|
|
86
|
-
step: number;
|
|
87
|
-
usage?: StepUsage;
|
|
88
|
-
} | {
|
|
89
|
-
type: "done";
|
|
90
|
-
output: string;
|
|
91
|
-
steps: number;
|
|
92
|
-
};
|
|
93
|
-
interface AgentLoop {
|
|
94
|
-
nextAction(messages: AgentMessage[], signal?: AbortSignal): Promise<AgentAction>;
|
|
95
|
-
streamAction?(messages: AgentMessage[]): AsyncIterable<AgentStreamEvent>;
|
|
96
|
-
}
|
|
97
|
-
/** Context passed to `prepareStep` before each LLM call. */
|
|
98
|
-
interface PrepareStepContext {
|
|
99
|
-
stepNumber: number;
|
|
100
|
-
toolCallHistory: string[];
|
|
101
|
-
}
|
|
102
|
-
/** Overrides returned by `prepareStep`. All fields optional — omit to keep defaults. */
|
|
103
|
-
interface PrepareStepResult {
|
|
104
|
-
model?: string;
|
|
105
|
-
activeTools?: string[];
|
|
106
|
-
}
|
|
107
35
|
|
|
108
36
|
/**
|
|
109
37
|
* Tool registry: the Tool contract and schema extraction.
|
|
@@ -120,8 +48,6 @@ interface Tool {
|
|
|
120
48
|
/** Execute using the ToolProvider. If not set, tool is handled externally (e.g. ARC tools). */
|
|
121
49
|
execute?: (provider: ToolProvider, args: Record<string, unknown>, workDir: string) => Promise<ToolResult>;
|
|
122
50
|
}
|
|
123
|
-
/** Get only the AI SDK tool schemas from a registry (skips tools without schemas) */
|
|
124
|
-
declare function toolSchemasFromRegistry(registry: Map<string, Tool>): Record<string, AnyTool>;
|
|
125
51
|
|
|
126
52
|
interface StoredMessage {
|
|
127
53
|
id: string;
|
|
@@ -148,6 +74,10 @@ interface MessageStore {
|
|
|
148
74
|
conversationId?: string;
|
|
149
75
|
maxResults?: number;
|
|
150
76
|
}): GrepResult[];
|
|
77
|
+
/** Serialize all messages for session persistence. */
|
|
78
|
+
serialize(): StoredMessage[];
|
|
79
|
+
/** Load serialized messages into this store (for session hydration). */
|
|
80
|
+
loadFrom(messages: StoredMessage[]): void;
|
|
151
81
|
}
|
|
152
82
|
declare class MemoryMessageStore implements MessageStore {
|
|
153
83
|
private messages;
|
|
@@ -155,6 +85,9 @@ declare class MemoryMessageStore implements MessageStore {
|
|
|
155
85
|
append(message: StoredMessage): void;
|
|
156
86
|
getConversation(conversationId: string): StoredMessage[];
|
|
157
87
|
getMessage(conversationId: string, index: number): StoredMessage | null;
|
|
88
|
+
serialize(): StoredMessage[];
|
|
89
|
+
loadFrom(messages: StoredMessage[]): void;
|
|
90
|
+
static hydrate(messages: StoredMessage[]): MemoryMessageStore;
|
|
158
91
|
grep(pattern: string, opts?: {
|
|
159
92
|
conversationId?: string;
|
|
160
93
|
maxResults?: number;
|
|
@@ -182,23 +115,48 @@ interface CompactionOpts {
|
|
|
182
115
|
interface SummaryDAG {
|
|
183
116
|
addLeaf(node: SummaryNode): void;
|
|
184
117
|
compact(opts?: CompactionOpts): SummaryNode[];
|
|
185
|
-
getNode(id: string): SummaryNode |
|
|
118
|
+
getNode(id: string): SummaryNode | null;
|
|
186
119
|
getLineage(id: string, visited?: Set<string>): string[];
|
|
187
|
-
getFrontier(budget: number):
|
|
188
|
-
|
|
120
|
+
getFrontier(budget: number): {
|
|
121
|
+
frontier: SummaryNode[];
|
|
122
|
+
coveredIds: Set<string>;
|
|
123
|
+
};
|
|
189
124
|
getAllNodes(): SummaryNode[];
|
|
125
|
+
/** Serialize DAG state for session persistence. */
|
|
126
|
+
serialize(): {
|
|
127
|
+
nodes: SummaryNode[];
|
|
128
|
+
coveredBy: [string, string][];
|
|
129
|
+
};
|
|
130
|
+
/** Load serialized DAG state into this instance (for session hydration). */
|
|
131
|
+
loadFrom(data: {
|
|
132
|
+
nodes: SummaryNode[];
|
|
133
|
+
coveredBy: [string, string][];
|
|
134
|
+
}): void;
|
|
190
135
|
}
|
|
191
136
|
declare class MemorySummaryDAG implements SummaryDAG {
|
|
192
137
|
private nodes;
|
|
193
138
|
/** Tracks which source IDs have been covered by a parent node */
|
|
194
139
|
private coveredBy;
|
|
140
|
+
serialize(): {
|
|
141
|
+
nodes: SummaryNode[];
|
|
142
|
+
coveredBy: [string, string][];
|
|
143
|
+
};
|
|
144
|
+
loadFrom(data: {
|
|
145
|
+
nodes: SummaryNode[];
|
|
146
|
+
coveredBy: [string, string][];
|
|
147
|
+
}): void;
|
|
148
|
+
static hydrate(data: {
|
|
149
|
+
nodes: SummaryNode[];
|
|
150
|
+
coveredBy: [string, string][];
|
|
151
|
+
}): MemorySummaryDAG;
|
|
195
152
|
addLeaf(node: SummaryNode): void;
|
|
196
153
|
compact(opts?: CompactionOpts): SummaryNode[];
|
|
197
|
-
getNode(id: string): SummaryNode |
|
|
154
|
+
getNode(id: string): SummaryNode | null;
|
|
198
155
|
getLineage(id: string, visited?: Set<string>): string[];
|
|
199
|
-
getFrontier(budget: number):
|
|
200
|
-
|
|
201
|
-
|
|
156
|
+
getFrontier(budget: number): {
|
|
157
|
+
frontier: SummaryNode[];
|
|
158
|
+
coveredIds: Set<string>;
|
|
159
|
+
};
|
|
202
160
|
getAllNodes(): SummaryNode[];
|
|
203
161
|
}
|
|
204
162
|
|
|
@@ -216,41 +174,6 @@ interface AssembledContext {
|
|
|
216
174
|
frontierText?: string;
|
|
217
175
|
ghostCueText?: string;
|
|
218
176
|
}
|
|
219
|
-
interface AssembleContextOpts {
|
|
220
|
-
conversationId: string;
|
|
221
|
-
store: MessageStore;
|
|
222
|
-
dag: SummaryDAG;
|
|
223
|
-
budget: number;
|
|
224
|
-
freshTailSize: number;
|
|
225
|
-
taskContext: string;
|
|
226
|
-
ooda?: OodaSnapshot;
|
|
227
|
-
}
|
|
228
|
-
/**
|
|
229
|
-
* Budget-driven context assembly from MessageStore + SummaryDAG.
|
|
230
|
-
*
|
|
231
|
-
* Algorithm:
|
|
232
|
-
* 1. Always include: task context (task, workspace, budget info)
|
|
233
|
-
* 2. Fresh tail: last N raw messages from the conversation
|
|
234
|
-
* 3. Frontier: walk DAG from deepest summaries, adding within budget
|
|
235
|
-
* 4. Ghost cues: for any DAG region not expanded, insert a pointer
|
|
236
|
-
* 5. OODA snapshot if provided
|
|
237
|
-
*/
|
|
238
|
-
declare function assembleContext(opts: AssembleContextOpts): AssembledContext;
|
|
239
|
-
interface AssembleWorkerContextOpts {
|
|
240
|
-
store: MessageStore;
|
|
241
|
-
dag: SummaryDAG;
|
|
242
|
-
budget: number;
|
|
243
|
-
taskContext: string;
|
|
244
|
-
instruction: string;
|
|
245
|
-
vectorIndex?: VectorIndex;
|
|
246
|
-
transcriptStore?: TranscriptStore;
|
|
247
|
-
scratchPad?: ScratchPad;
|
|
248
|
-
}
|
|
249
|
-
/**
|
|
250
|
-
* Assemble context specifically for a worker dispatch.
|
|
251
|
-
* Workers get: task context + relevant prior summaries + vector retrieval + scratch notes.
|
|
252
|
-
*/
|
|
253
|
-
declare function assembleWorkerContext(opts: AssembleWorkerContextOpts): Promise<AssembledContext>;
|
|
254
177
|
|
|
255
178
|
type HookEventName = 'PreToolUse' | 'PostToolUse' | 'BeforeWorker' | 'AfterWorker';
|
|
256
179
|
interface HookContext {
|
|
@@ -308,6 +231,8 @@ interface ExpectedOutputContract {
|
|
|
308
231
|
verification?: string | undefined;
|
|
309
232
|
description?: string | undefined;
|
|
310
233
|
}
|
|
234
|
+
/** Worker model tier for dispatch routing. */
|
|
235
|
+
type DispatchTier = "fast" | "strong";
|
|
311
236
|
/** Worker instruction tuple */
|
|
312
237
|
interface Tuple {
|
|
313
238
|
id: string;
|
|
@@ -320,13 +245,16 @@ interface Tuple {
|
|
|
320
245
|
tools: string[];
|
|
321
246
|
/** Step budget (1-10) */
|
|
322
247
|
steps: number;
|
|
248
|
+
/** Worker model tier — 'fast' for simple tasks, 'strong' (default) for complex reasoning. */
|
|
249
|
+
tier?: DispatchTier | undefined;
|
|
323
250
|
/** Public orchestrator rationale that preceded this dispatch */
|
|
324
251
|
orchestratorContext?: string | undefined;
|
|
325
252
|
}
|
|
326
253
|
interface DispatchRecord {
|
|
327
254
|
tuple: Tuple;
|
|
328
255
|
artifact: Artifact;
|
|
329
|
-
transcript
|
|
256
|
+
/** Reference to transcript in TranscriptStore — NOT the full transcript body. */
|
|
257
|
+
transcriptId: string;
|
|
330
258
|
progress: WorkerProgressEvent[];
|
|
331
259
|
completedAt: number;
|
|
332
260
|
/** Worker execution result (artifacts, actions, status) */
|
|
@@ -456,6 +384,33 @@ interface ScratchPad {
|
|
|
456
384
|
write(key: string, content: string): Promise<void>;
|
|
457
385
|
read(key: string): Promise<string | null>;
|
|
458
386
|
list(): Promise<string[]>;
|
|
387
|
+
clear(): Promise<void>;
|
|
388
|
+
}
|
|
389
|
+
/** Serialized session state — everything needed to hydrate an ArcLoop. */
|
|
390
|
+
interface SessionSnapshot {
|
|
391
|
+
messages: StoredMessage[];
|
|
392
|
+
dispatches: DispatchRecord[];
|
|
393
|
+
dagNodes: SummaryNode[];
|
|
394
|
+
dagCoveredBy: [string, string][];
|
|
395
|
+
turn: number;
|
|
396
|
+
dispatchCount: number;
|
|
397
|
+
orchestratorMessageIndex: number;
|
|
398
|
+
}
|
|
399
|
+
/** Lightweight session metadata for listing/picking. */
|
|
400
|
+
interface SessionMeta {
|
|
401
|
+
id: string;
|
|
402
|
+
slug: string;
|
|
403
|
+
createdAt: number;
|
|
404
|
+
lastActiveAt: number;
|
|
405
|
+
taskCount?: number;
|
|
406
|
+
summary: string;
|
|
407
|
+
}
|
|
408
|
+
interface SessionStore {
|
|
409
|
+
load(id: string): Promise<SessionSnapshot | null>;
|
|
410
|
+
save(id: string, snapshot: SessionSnapshot): Promise<void>;
|
|
411
|
+
getMeta(id: string): Promise<SessionMeta | null>;
|
|
412
|
+
saveMeta(id: string, meta: SessionMeta): Promise<void>;
|
|
413
|
+
list(): Promise<SessionMeta[]>;
|
|
459
414
|
}
|
|
460
415
|
/** What the orchestrator sees each turn */
|
|
461
416
|
interface OrchestratorContext {
|
|
@@ -472,12 +427,8 @@ interface OrchestratorContext {
|
|
|
472
427
|
turnsRemaining: number;
|
|
473
428
|
/** Number of dispatches so far */
|
|
474
429
|
dispatchCount: number;
|
|
475
|
-
/** Number of dispatches since the orchestrator has not emitted done yet */
|
|
476
|
-
dispatchesWithoutFinalAnswer: number;
|
|
477
430
|
/** Artifact status counts across all completed dispatches */
|
|
478
431
|
artifactStatusCounts: Record<Artifact["status"], number>;
|
|
479
|
-
/** True while the orchestrator has not emitted the final done output */
|
|
480
|
-
noFinalAnswerYet: boolean;
|
|
481
432
|
/** True when no dispatch artifact has reached complete status */
|
|
482
433
|
allIncomplete: boolean;
|
|
483
434
|
/** Completed dispatches in chronological order */
|
|
@@ -488,8 +439,6 @@ interface OrchestratorContext {
|
|
|
488
439
|
messageStore?: MessageStore | undefined;
|
|
489
440
|
/** LCM summary DAG */
|
|
490
441
|
summaryDAG?: SummaryDAG | undefined;
|
|
491
|
-
/** Ghost cues for compacted regions */
|
|
492
|
-
ghostCues?: GhostCue[] | undefined;
|
|
493
442
|
}
|
|
494
443
|
|
|
495
444
|
interface ArcConfig {
|
|
@@ -499,6 +448,8 @@ interface ArcConfig {
|
|
|
499
448
|
model: string;
|
|
500
449
|
/** Model ID for workers */
|
|
501
450
|
workerModel: string;
|
|
451
|
+
/** Optional per-tier worker model overrides. Falls back to workerModel when a tier is missing. */
|
|
452
|
+
workerModelMap?: Partial<Record<DispatchTier, string>> | undefined;
|
|
502
453
|
createModel?: ModelFactory;
|
|
503
454
|
toolProvider: ToolProvider;
|
|
504
455
|
/** Agent-provided tool definitions (Bash, Read, Write, etc.) with schemas, execute, and artifact metadata. Harness adds ARC framework tools internally. */
|
|
@@ -529,6 +480,10 @@ interface ArcConfig {
|
|
|
529
480
|
hookRunner?: HookRunner | undefined;
|
|
530
481
|
/** Callback for AskUser orchestrator tool. If provided, AskUser is available to the orchestrator. */
|
|
531
482
|
askUser?: ((question: string, options?: string[]) => Promise<string>) | undefined;
|
|
483
|
+
/** Session store for persistence across restarts. */
|
|
484
|
+
sessionStore?: SessionStore | undefined;
|
|
485
|
+
/** Session ID to resume. If provided with sessionStore, loop hydrates from saved state. */
|
|
486
|
+
sessionId?: string | undefined;
|
|
532
487
|
}
|
|
533
488
|
type ArcEvent = {
|
|
534
489
|
type: "orchestrator_turn";
|
|
@@ -568,9 +523,17 @@ type ArcEvent = {
|
|
|
568
523
|
type: "ask_user";
|
|
569
524
|
question: string;
|
|
570
525
|
options?: string[] | undefined;
|
|
526
|
+
} | {
|
|
527
|
+
type: "orchestrator_usage";
|
|
528
|
+
turn: number;
|
|
529
|
+
inputTokens?: number;
|
|
530
|
+
outputTokens?: number;
|
|
571
531
|
} | {
|
|
572
532
|
type: "done";
|
|
573
533
|
output: string;
|
|
534
|
+
} | {
|
|
535
|
+
type: "session_saved";
|
|
536
|
+
sessionId: string;
|
|
574
537
|
} | {
|
|
575
538
|
type: "text_delta";
|
|
576
539
|
text: string;
|
|
@@ -588,6 +551,8 @@ type WorkerProgressEvent = {
|
|
|
588
551
|
publicRationale?: string | undefined;
|
|
589
552
|
missingPublicRationale?: boolean | undefined;
|
|
590
553
|
outputSummary?: string | undefined;
|
|
554
|
+
inputTokens?: number | undefined;
|
|
555
|
+
outputTokens?: number | undefined;
|
|
591
556
|
} | {
|
|
592
557
|
kind: "model_error";
|
|
593
558
|
step: number;
|
|
@@ -676,13 +641,13 @@ interface ArcRunResult {
|
|
|
676
641
|
events: ArcEvent[];
|
|
677
642
|
}
|
|
678
643
|
declare class ArcLoop {
|
|
679
|
-
private
|
|
644
|
+
private config;
|
|
680
645
|
private readonly transcriptStore;
|
|
681
646
|
private readonly vectorIndex;
|
|
682
647
|
private readonly scratchPad;
|
|
683
648
|
private readonly artifactStore;
|
|
684
|
-
private
|
|
685
|
-
private
|
|
649
|
+
private messageStore;
|
|
650
|
+
private summaryDAG;
|
|
686
651
|
private readonly createModel;
|
|
687
652
|
private readonly windowSize;
|
|
688
653
|
private readonly model;
|
|
@@ -695,20 +660,36 @@ declare class ArcLoop {
|
|
|
695
660
|
private readonly dispatchState;
|
|
696
661
|
private orchestratorMessageIndex;
|
|
697
662
|
private turn;
|
|
663
|
+
private maxTurns;
|
|
698
664
|
/** Per-turn abort controller — cancelled by interrupt(), refreshed each turn. */
|
|
699
665
|
private turnController;
|
|
666
|
+
/** Resolver for the next task — set when the loop is waiting between tasks. */
|
|
667
|
+
private taskResolve;
|
|
700
668
|
constructor(config: ArcConfig);
|
|
701
669
|
/**
|
|
702
670
|
* Interrupt the current turn — cancels in-flight model calls and workers.
|
|
703
671
|
* The orchestrator loop stays alive and will prompt for user steering.
|
|
704
672
|
*/
|
|
705
673
|
interrupt(): void;
|
|
674
|
+
/** True when the loop is waiting for the next task (between done boundaries). */
|
|
675
|
+
get idle(): boolean;
|
|
676
|
+
/**
|
|
677
|
+
* Push a follow-up task into the loop. The orchestrator sees it as
|
|
678
|
+
* a new user message with full conversational context from prior tasks.
|
|
679
|
+
*/
|
|
680
|
+
pushTask(task: string): boolean;
|
|
681
|
+
private waitForNextTask;
|
|
682
|
+
/** Save session snapshot + update meta if a session store is configured. */
|
|
683
|
+
private saveSession;
|
|
684
|
+
/** Reset per-task state while keeping full conversation history. */
|
|
685
|
+
private resetForNewTask;
|
|
706
686
|
/**
|
|
707
687
|
* Stream events from the orchestration loop.
|
|
708
688
|
*/
|
|
709
689
|
stream(signal?: AbortSignal): AsyncGenerator<ArcEvent>;
|
|
710
690
|
/**
|
|
711
|
-
* Run
|
|
691
|
+
* Run a single task to completion (for headless/test use).
|
|
692
|
+
* Breaks after the first `done` event — does not wait for follow-up tasks.
|
|
712
693
|
*/
|
|
713
694
|
run(signal?: AbortSignal): Promise<ArcRunResult>;
|
|
714
695
|
/** Append a message to the LCM message store (single source of truth) */
|
|
@@ -724,18 +705,6 @@ declare class ArcLoop {
|
|
|
724
705
|
private handleInterrupt;
|
|
725
706
|
}
|
|
726
707
|
|
|
727
|
-
type ModelMessage = any;
|
|
728
|
-
/**
|
|
729
|
-
* Convert AgentMessage[] to Vercel AI SDK ModelMessage[].
|
|
730
|
-
* Extracted from VercelAgentLoop — identical logic, standalone pure function.
|
|
731
|
-
*
|
|
732
|
-
* System messages that appear after user/assistant/tool messages are
|
|
733
|
-
* converted to user messages with a [System] prefix. The Anthropic API
|
|
734
|
-
* does not allow interleaved system messages; the actual system prompt
|
|
735
|
-
* is passed separately via the `system` parameter.
|
|
736
|
-
*/
|
|
737
|
-
declare function toModelMessages(messages: AgentMessage[]): ModelMessage[];
|
|
738
|
-
|
|
739
708
|
/**
|
|
740
709
|
* Episode projection: minimal formatting for orchestrator context.
|
|
741
710
|
*
|
|
@@ -748,104 +717,8 @@ declare function formatDispatchForPrompt(record: DispatchRecord, options?: {
|
|
|
748
717
|
compact?: boolean;
|
|
749
718
|
maxChars?: number;
|
|
750
719
|
}): string;
|
|
751
|
-
/** Build OODA snapshot from dispatch records — reads WorkerResult directly */
|
|
752
|
-
declare function buildOodaSnapshot(input: {
|
|
753
|
-
turn: number;
|
|
754
|
-
maxTurns: number;
|
|
755
|
-
turnsRemaining: number;
|
|
756
|
-
dispatchCount: number;
|
|
757
|
-
allIncomplete: boolean;
|
|
758
|
-
dispatches: DispatchRecord[];
|
|
759
|
-
}): OodaSnapshot;
|
|
760
|
-
declare function formatOodaSnapshotForPrompt(snapshot: OodaSnapshot): string;
|
|
761
|
-
declare function formatReadEpisodeResult(record: DispatchRecord): string;
|
|
762
|
-
declare function formatTranscriptTrace(messages: AgentMessage[], toolResultLimit: number): string;
|
|
763
|
-
|
|
764
|
-
/** Dispatch a worker to accomplish a task */
|
|
765
|
-
declare const dispatch: ai.Tool<{
|
|
766
|
-
instruction: string;
|
|
767
|
-
expectedOutput: string | {
|
|
768
|
-
artifacts?: {
|
|
769
|
-
type: "unknown" | "file" | "directory" | "value";
|
|
770
|
-
path?: string | undefined;
|
|
771
|
-
description?: string | undefined;
|
|
772
|
-
}[] | undefined;
|
|
773
|
-
successCriteria?: string[] | undefined;
|
|
774
|
-
verification?: string | undefined;
|
|
775
|
-
description?: string | undefined;
|
|
776
|
-
kind?: "unknown" | "file" | "value" | "files" | undefined;
|
|
777
|
-
path?: string | undefined;
|
|
778
|
-
paths?: string[] | undefined;
|
|
779
|
-
};
|
|
780
|
-
inputs?: string[] | undefined;
|
|
781
|
-
}, never>;
|
|
782
|
-
/** Mark task complete and return final output */
|
|
783
|
-
declare const done: ai.Tool<{
|
|
784
|
-
output: string;
|
|
785
|
-
}, never>;
|
|
786
|
-
interface ArcToolDeps {
|
|
787
|
-
readEpisode?: (args: ReadEpisodeArgs) => Promise<string>;
|
|
788
|
-
historySearch?: (pattern: string, opts?: {
|
|
789
|
-
conversationId?: string;
|
|
790
|
-
maxResults?: number;
|
|
791
|
-
}) => GrepResult[];
|
|
792
|
-
historyExpand?: (summaryId: string, maxTokens?: number) => string;
|
|
793
|
-
historyOverview?: (summaryId?: string) => string;
|
|
794
|
-
historyRead?: (conversationId: string, messageIndex: number) => string | null;
|
|
795
|
-
scratchPad?: ScratchPad;
|
|
796
|
-
recall?: (query: string) => Promise<string>;
|
|
797
|
-
askUser?: (question: string, options?: string[]) => Promise<string>;
|
|
798
|
-
}
|
|
799
|
-
/** Build worker-facing ARC tools with execute closures */
|
|
800
|
-
declare function buildWorkerToolEntries(deps: ArcToolDeps): Map<string, Tool>;
|
|
801
|
-
/** Build orchestrator-facing ARC tools with execute closures (excludes dispatch/done which are control flow) */
|
|
802
|
-
declare function buildOrchestratorToolEntries(deps: ArcToolDeps): Map<string, Tool>;
|
|
803
|
-
|
|
804
|
-
/**
|
|
805
|
-
* Build a depth-0 (leaf) summary node from a completed dispatch record.
|
|
806
|
-
* Reads artifacts and actions directly from the worker result.
|
|
807
|
-
*/
|
|
808
|
-
declare function buildLeafSummary(record: DispatchRecord): SummaryNode;
|
|
809
|
-
|
|
810
|
-
interface LcmToolDeps {
|
|
811
|
-
messageStore: MessageStore;
|
|
812
|
-
summaryDAG: SummaryDAG;
|
|
813
|
-
vectorIndex: VectorIndex;
|
|
814
|
-
transcriptStore: TranscriptStore;
|
|
815
|
-
/** Needed for expandSummary fallback when message store has no messages for a leaf */
|
|
816
|
-
findDispatchRecord: (summaryId: string) => DispatchRecord | undefined;
|
|
817
|
-
}
|
|
818
|
-
/** Expand a summary node — leaf nodes return source transcript, rollups return child summaries */
|
|
819
|
-
declare function expandSummary(deps: LcmToolDeps, summaryId: string, maxTokens: number): string;
|
|
820
|
-
/** Describe a summary node's metadata, or show DAG overview */
|
|
821
|
-
declare function describeSummary(deps: LcmToolDeps, summaryId?: string): string;
|
|
822
|
-
/** Direct vector search recall — returns matching transcript excerpts */
|
|
823
|
-
declare function recallDirect(deps: LcmToolDeps, query: string): Promise<string>;
|
|
824
|
-
/** Read a specific message from the message store at full fidelity */
|
|
825
|
-
declare function historyRead(deps: LcmToolDeps, conversationId: string, messageIndex: number): string | null;
|
|
826
|
-
/** Search across all stored messages from all conversations */
|
|
827
|
-
declare const history_search: ai.Tool<{
|
|
828
|
-
pattern: string;
|
|
829
|
-
conversationId?: string | undefined;
|
|
830
|
-
maxResults?: number | undefined;
|
|
831
|
-
}, never>;
|
|
832
|
-
/** Expand a summary node back to its source messages or child summaries */
|
|
833
|
-
declare const history_expand: ai.Tool<{
|
|
834
|
-
summaryId: string;
|
|
835
|
-
maxTokens?: number | undefined;
|
|
836
|
-
}, never>;
|
|
837
|
-
/** Show summary node metadata or history overview */
|
|
838
|
-
declare const history_overview: ai.Tool<{
|
|
839
|
-
summaryId?: string | undefined;
|
|
840
|
-
}, never>;
|
|
841
|
-
/** Read a specific message from run history at full fidelity */
|
|
842
|
-
declare const history_read: ai.Tool<{
|
|
843
|
-
conversationId: string;
|
|
844
|
-
messageIndex: number;
|
|
845
|
-
}, never>;
|
|
846
720
|
|
|
847
721
|
declare function cloneForTrace<T>(value: T): T;
|
|
848
|
-
declare function normalizeReadEpisodeArgs(args: Record<string, unknown>): ReadEpisodeArgs;
|
|
849
722
|
|
|
850
723
|
/** In-memory transcript store for testing */
|
|
851
724
|
declare class MemoryTranscriptStore implements TranscriptStore {
|
|
@@ -869,6 +742,7 @@ declare class MemoryScratchPad implements ScratchPad {
|
|
|
869
742
|
write(key: string, content: string): Promise<void>;
|
|
870
743
|
read(key: string): Promise<string | null>;
|
|
871
744
|
list(): Promise<string[]>;
|
|
745
|
+
clear(): Promise<void>;
|
|
872
746
|
}
|
|
873
747
|
/** In-memory artifact store for testing */
|
|
874
748
|
declare class MemoryArtifactStore implements ArtifactStore {
|
|
@@ -877,6 +751,16 @@ declare class MemoryArtifactStore implements ArtifactStore {
|
|
|
877
751
|
get(id: string): Promise<Artifact | null>;
|
|
878
752
|
getAll(): Promise<Record<string, Artifact>>;
|
|
879
753
|
}
|
|
754
|
+
/** In-memory session store for testing */
|
|
755
|
+
declare class MemorySessionStore implements SessionStore {
|
|
756
|
+
private snapshots;
|
|
757
|
+
private metas;
|
|
758
|
+
load(id: string): Promise<SessionSnapshot | null>;
|
|
759
|
+
save(id: string, snapshot: SessionSnapshot): Promise<void>;
|
|
760
|
+
getMeta(id: string): Promise<SessionMeta | null>;
|
|
761
|
+
saveMeta(id: string, meta: SessionMeta): Promise<void>;
|
|
762
|
+
list(): Promise<SessionMeta[]>;
|
|
763
|
+
}
|
|
880
764
|
|
|
881
765
|
/**
|
|
882
766
|
* File-based transcript store.
|
|
@@ -909,61 +793,4 @@ declare class FsArtifactStore implements ArtifactStore {
|
|
|
909
793
|
private save;
|
|
910
794
|
}
|
|
911
795
|
|
|
912
|
-
|
|
913
|
-
* Run a stateless worker with the given configuration.
|
|
914
|
-
* Workers see only: instruction, input artifacts, and tools.
|
|
915
|
-
*/
|
|
916
|
-
declare function runWorker(config: RunWorkerConfig): Promise<WorkerResult>;
|
|
917
|
-
|
|
918
|
-
declare const ORCHESTRATOR_SYSTEM_PROMPT = "You accomplish tasks by dispatching workers and synthesizing results.\n\nDispatch workers for anything requiring tool use. Answer directly with done for questions you can answer from knowledge or prior results.\n\nWorkers are stateless \u2014 they see only their instruction, input artifacts, and tools. They also have access to history and scratch pad tools, so you don't need to repeat everything.\n\nOlder context gets compacted into summaries. Use history_search to find specific prior results, history_read for full content, and history_expand to restore compacted summaries.\n\nBefore dispatching, check what prior workers attempted. Do not repeat failed approaches \u2014 change strategy or decompose differently.\n\nExplain your reasoning before each tool call.\n\nCall done as soon as the task is satisfied. Re-dispatching costs turns \u2014 only follow up if the result is incomplete, failed, or clearly wrong.";
|
|
919
|
-
declare const WORKER_SYSTEM_PROMPT = "Complete the instruction using the available tools. Workers are stateless and cannot interact with the user \u2014 assume reasonable defaults and proceed.\n\nBefore starting, check ScratchPad_List for notes from prior workers and use history_search to find relevant prior attempts.\n\nIf you are running low on steps, stop and write your progress to ScratchPad_Write \u2014 this is more valuable than one more attempt.\n\nBefore finishing, verify your work against the expected output contract. If verification fails, fix it.\n\nExplain your reasoning before each tool call.";
|
|
920
|
-
|
|
921
|
-
/** A system prompt block with optional Anthropic cache control. */
|
|
922
|
-
interface SystemPromptBlock {
|
|
923
|
-
text: string;
|
|
924
|
-
cacheControl?: {
|
|
925
|
-
type: "ephemeral";
|
|
926
|
-
};
|
|
927
|
-
}
|
|
928
|
-
interface VercelAgentLoopConfig {
|
|
929
|
-
model?: string;
|
|
930
|
-
/** System prompt — string or structured blocks with cache control markers. */
|
|
931
|
-
systemPrompt?: string | SystemPromptBlock[];
|
|
932
|
-
createModel?: ModelFactory;
|
|
933
|
-
/** @deprecated Prefer createModel. */
|
|
934
|
-
apiKey?: string;
|
|
935
|
-
/** Custom tool definitions. If provided, replaces built-in agentTools for LLM calls. */
|
|
936
|
-
tools?: Record<string, AnyTool>;
|
|
937
|
-
/** Tool choice for LLM calls. Supports per-turn callbacks. Default: 'auto'. */
|
|
938
|
-
toolChoice?: ToolChoiceConfig;
|
|
939
|
-
/** Provider options passed to generateText/streamText (e.g. anthropic thinking config). */
|
|
940
|
-
providerOptions?: Record<string, unknown>;
|
|
941
|
-
/** Per-step callback to override model and active tools before each LLM call. */
|
|
942
|
-
prepareStep?: (context: PrepareStepContext) => PrepareStepResult | void;
|
|
943
|
-
}
|
|
944
|
-
declare class VercelAgentLoop implements AgentLoop {
|
|
945
|
-
private readonly model;
|
|
946
|
-
private readonly createModel;
|
|
947
|
-
private readonly systemPrompt;
|
|
948
|
-
private readonly tools;
|
|
949
|
-
private readonly validToolNames;
|
|
950
|
-
private readonly toolChoiceConfig;
|
|
951
|
-
private readonly providerOptions;
|
|
952
|
-
private readonly prepareStep;
|
|
953
|
-
/** Track tool names called across steps for prepareStep context. */
|
|
954
|
-
private toolCallHistory;
|
|
955
|
-
private step;
|
|
956
|
-
/** Last step's token usage — read after nextAction/streamAction completes. */
|
|
957
|
-
lastUsage: StepUsage | undefined;
|
|
958
|
-
constructor(config?: VercelAgentLoopConfig);
|
|
959
|
-
/** Build the `system` parameter for generateText/streamText. */
|
|
960
|
-
private buildSystemParam;
|
|
961
|
-
/** Resolve model + tools for this step via prepareStep callback. */
|
|
962
|
-
private resolveStep;
|
|
963
|
-
/** Extract StepUsage from AI SDK usage object. */
|
|
964
|
-
private static extractUsage;
|
|
965
|
-
nextAction(messages: AgentMessage[], signal?: AbortSignal): Promise<AgentAction>;
|
|
966
|
-
streamAction(messages: AgentMessage[]): AsyncGenerator<AgentStreamEvent>;
|
|
967
|
-
}
|
|
968
|
-
|
|
969
|
-
export { AnyTool, type ArcConfig, type ArcEvent, ArcLoop, type ArcRunResult, type ArcToolDeps, type ArcTraceEvent, type Artifact, type ArtifactStore, type AssembleWorkerContextOpts, type AssembledContext, type CompactionOpts, type DispatchRecord, type ExpectedArtifact, type ExpectedOutputContract, FsArtifactStore, FsTranscriptStore, type GhostCue, type GrepResult, type HookCallback, type HookContext, type HookDecision, type HookEventName, HookRunner, type LcmToolDeps, MemoryArtifactStore, MemoryMessageStore, MemoryScratchPad, MemorySummaryDAG, MemoryTranscriptStore, MemoryVectorIndex, type MessageStore, ModelFactory, ORCHESTRATOR_SYSTEM_PROMPT, type OodaSnapshot, type OrchestratorContext, type ReadEpisodeArgs, type ReadEpisodeDetail, type RunWorkerConfig, type ScratchPad, type StoredMessage, type SummaryDAG, type SummaryNode, type SystemPromptBlock, type Tool, ToolChoiceConfig, ToolProvider, ToolResult, ToolResultArtifact, type TraceToolCall, type Transcript, type TranscriptStore, type Tuple, type VectorIndex, VercelAgentLoop, type VercelAgentLoopConfig, WORKER_SYSTEM_PROMPT, type WorkerProgressEvent, type WorkerResult, assembleContext, assembleWorkerContext, buildLeafSummary, buildOodaSnapshot, buildOrchestratorToolEntries, buildWorkerToolEntries, cloneForTrace, describeSummary, dispatch, done, expandSummary, formatDispatchForPrompt, formatOodaSnapshotForPrompt, formatReadEpisodeResult, formatTranscriptTrace, historyRead, history_expand, history_overview, history_read, history_search, normalizeReadEpisodeArgs, recallDirect, runWorker, toModelMessages, toolSchemasFromRegistry };
|
|
796
|
+
export { AnyTool, type ArcConfig, type ArcEvent, ArcLoop, type ArcRunResult, type ArcTraceEvent, type Artifact, type ArtifactStore, type DispatchRecord, type DispatchTier, type ExpectedArtifact, type ExpectedOutputContract, FsArtifactStore, FsTranscriptStore, MemoryArtifactStore, MemoryMessageStore, MemoryScratchPad, MemorySessionStore, MemorySummaryDAG, MemoryTranscriptStore, MemoryVectorIndex, type MessageStore, ModelFactory, type OodaSnapshot, type OrchestratorContext, type ReadEpisodeArgs, type ReadEpisodeDetail, type RunWorkerConfig, type ScratchPad, type SessionMeta, type SessionSnapshot, type SessionStore, type StoredMessage, type SummaryDAG, type SummaryNode, type Tool, ToolProvider, ToolResult, ToolResultArtifact, type TraceToolCall, type Transcript, type TranscriptStore, type Tuple, type VectorIndex, type WorkerProgressEvent, type WorkerResult, cloneForTrace, formatDispatchForPrompt };
|