@rowan-agent/agent 0.28.0 → 0.30.0

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/index.d.ts CHANGED
@@ -1,3399 +1,5 @@
1
1
  import * as _rowan_agent_models from '@rowan-agent/models';
2
- import { ContentBlock, ModelRef, LlmTokenUsage, LlmContentPart, ScopeRef, ToolCallStatus, JsonValue as JsonValue$1, ToolProgress, ToolCallContent, ToolCallLocation, JsonObject as JsonObject$1, ToolKind, ModelConfig, StreamFn, ToolAnnotations, ThinkingLevel, ToolCall as ToolCall$1, ToolCallUpdate } from '@rowan-agent/models';
3
- export { ModelConfig, ModelRef, ProviderCallContext, ProviderConfig, ProviderModelConfig, ProviderStreamFn, ScopeRef, StreamFn, ThinkingLevel, ToolAnnotations, ToolCall, ToolCallContent, ToolCallLocation, ToolCallOptions, ToolCallOutcome, ToolCallStatus, ToolCallUpdate, ToolDefinitionSummary, ToolKind, ToolProgress } from '@rowan-agent/models';
4
- import Type from 'typebox';
5
-
6
- type ModelInvokeOutput = {
7
- text: string;
8
- contentBlocks: ContentBlock[];
9
- toolCalls: ToolCall[];
10
- stopReason?: string;
11
- model?: ModelRef;
12
- usage?: LlmTokenUsage;
13
- };
14
- type InternalModelLoopOptions = {
15
- prompt: string;
16
- tools?: readonly string[];
17
- maxToolRounds?: number;
18
- };
19
- /** Execution capabilities for a phase — operates on PhaseContext. */
20
- type PhaseExecution = {
21
- invokeModel(context: PhaseContext, options?: {
22
- output?: "reply" | "internal";
23
- }): Promise<ModelInvokeOutput>;
24
- runInternalModelLoop(context: PhaseContext, options: InternalModelLoopOptions): Promise<ModelInvokeOutput>;
25
- reportStatus(status: PhaseStatus): Promise<void>;
26
- executeTools(context: AgentContext, toolCalls: readonly ToolCall[], contentBlocks?: readonly ContentBlock[], meta?: {
27
- model?: ModelRef;
28
- usage?: LlmTokenUsage;
29
- }): Promise<readonly ToolResult[]>;
30
- interaction: RunInteractionDriver;
31
- /** Message lifecycle manager for streaming updates from programmatic phases */
32
- messages: PhaseMessageManager;
33
- };
34
- /** Message lifecycle manager for streaming updates */
35
- type PhaseMessageManager = {
36
- /** Get all visible messages in the transcript */
37
- visible(): AgentMessage[];
38
- /** Reserve the eventual message identity before stream deltas arrive. */
39
- reserve(role: "assistant" | "tool", metadata?: Record<string, unknown>): string;
40
- /** Start a new message stream, returns message id */
41
- start(role: "assistant" | "tool", content: AgentMessage["content"], metadata?: Record<string, unknown>): string;
42
- /** Stream a text delta */
43
- update(messageId: string, delta: string): Promise<void>;
44
- /** Replace the active message content with model-native content parts */
45
- replaceContent(messageId: string, content: string | LlmContentPart[]): void;
46
- /** End the message stream, appends to transcript */
47
- end(messageId: string, meta?: {
48
- model?: ModelRef;
49
- usage?: LlmTokenUsage;
50
- }): Promise<void>;
51
- /** Drop an unstarted stream that produced no content. */
52
- discard(messageId: string): void;
53
- };
54
-
55
- type PhaseRegistrySelection = Readonly<{
56
- entryPhaseId: string | null;
57
- phaseIds: readonly string[];
58
- }>;
59
- type AgentDefinition = Readonly<{
60
- name: string;
61
- description: string;
62
- prompt: string;
63
- tools?: readonly string[];
64
- skills?: readonly string[];
65
- /** Host-supplied Skills private to this Agent Definition/Bundle. */
66
- bundledSkills?: readonly Skill[];
67
- phases?: PhaseRegistrySelection;
68
- contexts?: readonly string[];
69
- model?: ModelRef;
70
- }>;
71
- /** Parse one Markdown definition using the same frontmatter vocabulary as Phase resources. */
72
- declare function parseAgentDefinition(raw: string): AgentDefinition;
73
-
74
- type ResourceKind = "agent" | "tool" | "skill" | "phase";
75
- type ResourceSourceId = string;
76
- /** Rowan-native contribution aliases. Hosts may adapt their domain handlers to
77
- * these existing Tool/Phase lifecycles without importing host Scope types. */
78
- type ToolContribution = Tool$1;
79
- type PhaseContribution = Phase;
80
- type ResourceView = Readonly<{
81
- agents: readonly ResourceSourceId[];
82
- tools: readonly ResourceSourceId[];
83
- skills: readonly ResourceSourceId[];
84
- phases: readonly ResourceSourceId[];
85
- }>;
86
- type ResourceRef = Readonly<{
87
- kind: ResourceKind;
88
- sourceId: ResourceSourceId;
89
- name: string;
90
- }>;
91
- type ResourceDiagnostic = Readonly<{
92
- kind: "invalid" | "missing" | "collision";
93
- sourceId: ResourceSourceId;
94
- message: string;
95
- path?: string;
96
- }>;
97
- type LoadResult = Readonly<{
98
- revision: string;
99
- registered: readonly ResourceRef[];
100
- skipped: readonly ResourceDiagnostic[];
101
- }>;
102
- type LoadInput<T> = Readonly<{
103
- sourceId: ResourceSourceId;
104
- directory?: string;
105
- values?: readonly T[];
106
- }>;
107
- type ResolvedResourceView = Readonly<{
108
- agents: readonly AgentDefinition[];
109
- tools: readonly Tool$1[];
110
- skills: readonly Skill[];
111
- phases: readonly Phase[];
112
- revisions: Readonly<Record<ResourceKind, readonly string[]>>;
113
- refs: Readonly<Record<ResourceKind, readonly ResourceRef[]>>;
114
- }>;
115
- type ResourceRegistryErrorCode = "invalid_source_id" | "invalid_resource_name" | "resource_collision" | "resource_input_missing" | "resource_directory_not_supported" | "unknown_resource_source" | "implicit_source_protected";
116
- declare class ResourceRegistryError extends Error {
117
- readonly code: ResourceRegistryErrorCode;
118
- constructor(code: ResourceRegistryErrorCode, message: string);
119
- }
120
- type RegistryValue = AgentDefinition | Tool$1 | Skill | Phase;
121
- /**
122
- * Runtime Resource Registry source transaction and view resolver.
123
- *
124
- * Directory normalization is intentionally added by the typed loader slice;
125
- * this first module owns only the atomic source/revision/collision semantics.
126
- */
127
- declare class ResourceRegistry {
128
- private readonly sources;
129
- /** Sources registered by the bootstrap boundary (currently Extensions). */
130
- private readonly implicitSources;
131
- private revisionSequence;
132
- loadAgents(input: LoadInput<AgentDefinition>): Promise<LoadResult>;
133
- loadSkills(input: LoadInput<Skill>): Promise<LoadResult>;
134
- loadPhases(input: LoadInput<Phase>): Promise<LoadResult>;
135
- loadTools(input: Readonly<{
136
- sourceId: ResourceSourceId;
137
- values: readonly ToolContribution[];
138
- }>): Promise<LoadResult>;
139
- unload(input: Readonly<{
140
- kind: ResourceKind;
141
- sourceId: ResourceSourceId;
142
- }>): Promise<LoadResult>;
143
- resolveView(view: ResourceView): ResolvedResourceView;
144
- /** Mark one already-loaded source as implicit for every Resource View. */
145
- protected markImplicit(kind: ResourceKind, sourceId: ResourceSourceId): void;
146
- /** Bootstrap-only helper for replacing an implicit contribution source. */
147
- protected replaceImplicit<T extends RegistryValue>(kind: ResourceKind, sourceId: ResourceSourceId, values: readonly T[]): Promise<LoadResult>;
148
- protected hasImplicit(kind: ResourceKind, sourceId: ResourceSourceId): boolean;
149
- private withImplicit;
150
- private collect;
151
- private commit;
152
- private resolveKind;
153
- private resolveRevisions;
154
- private resolveRefs;
155
- private sourcesFor;
156
- private nextRevision;
157
- }
158
-
159
- /**
160
- * EventBus — simple pub/sub for inter-extension communication.
161
- *
162
- * Extensions can emit and subscribe to arbitrary events via `api.events`.
163
- * This allows extensions to coordinate without direct coupling.
164
- *
165
- * @example
166
- * ```typescript
167
- * // Extension A
168
- * api.events.on("my-plugin:ready", (data) => {
169
- * console.log("Plugin ready:", data);
170
- * });
171
- *
172
- * // Extension B
173
- * api.events.emit("my-plugin:ready", { version: "1.0" });
174
- * ```
175
- */
176
- type Listener = (...args: unknown[]) => void;
177
- interface EventBus {
178
- /** Subscribe to an event. Returns unsubscribe function. */
179
- on(event: string, listener: Listener): () => void;
180
- /** Emit an event to all subscribers. */
181
- emit(event: string, ...args: unknown[]): void;
182
- /** Remove all listeners for an event, or all listeners if no event specified. */
183
- off(event?: string): void;
184
- /** Check if there are listeners for an event. */
185
- has(event: string): boolean;
186
- /** Get listener count for an event. */
187
- count(event: string): number;
188
- }
189
-
190
- /**
191
- * @module extensions/context
192
- *
193
- * Extension context types — runtime state and phase execution context.
194
- *
195
- * For ExtensionAPI and createExtensionAPI, see ./api.ts
196
- */
197
-
198
- /**
199
- * Runtime context available to extensions during event handler execution.
200
- *
201
- * Provides access to agent state, working directory, and utility methods.
202
- * Values are resolved lazily via getters, so changes via `runner.bind()` are
203
- * reflected immediately without recreating the context.
204
- *
205
- * @example
206
- * ```typescript
207
- * api.hooks.on("before_tool_call", (event, ctx) => {
208
- * console.log(`cwd: ${ctx.cwd}`);
209
- * if (ctx.isIdle()) { ... }
210
- * });
211
- * ```
212
- */
213
- interface ExtensionContext {
214
- /** Current working directory */
215
- cwd: string;
216
- /** Abort signal — fires when the agent operation is cancelled */
217
- signal: AbortSignal | undefined;
218
- /** Whether the agent is currently idle (not streaming) */
219
- isIdle(): boolean;
220
- /** Abort the current agent operation */
221
- abort(): void;
222
- /**
223
- * Execute a shell command.
224
- *
225
- * @param command - The command to run
226
- * @param args - Command arguments
227
- * @param options - Execution options (cwd, env, timeout, signal)
228
- * @returns Execution result with exitCode, stdout, stderr
229
- */
230
- exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
231
- /** Extension manifest from package.json `rowan` field */
232
- manifest?: ExtensionManifest;
233
- /** Current model ID, if available */
234
- modelId?: string;
235
- /** Get current system prompt */
236
- getSystemPrompt?(): string;
237
- /** Set/override the system prompt */
238
- setSystemPrompt?(prompt: string): void;
239
- /** Get the full message history */
240
- getMessages?(): Array<{
241
- role: string;
242
- content: string;
243
- }>;
244
- /** Append a message to the history */
245
- addMessage?(role: "user" | "assistant" | "system", content: string): void;
246
- /** Get all available tools */
247
- getAvailableTools?(): Array<{
248
- name: string;
249
- description: string;
250
- }>;
251
- /** Get all available skills */
252
- getAvailableSkills?(): Array<{
253
- name: string;
254
- description: string;
255
- }>;
256
- /** Get skill content by name */
257
- getSkillContent?(skillName: string): string;
258
- /** Get all available phase names */
259
- getAvailablePhases?(): string[];
260
- /** Get phase content by name */
261
- getPhaseContent?(phaseName: string): string;
262
- }
263
- /**
264
- * Utility functions available to extensions.
265
- */
266
- interface ExtensionUtils {
267
- /**
268
- * Generate unique ID.
269
- * @param prefix - ID prefix
270
- * @returns Format: `{prefix}_{timestamp}_{counter}`
271
- */
272
- createId(prefix: string): string;
273
- /**
274
- * JSON serialization (with indentation).
275
- * @param value - Value to serialize
276
- * @returns JSON string
277
- */
278
- formatJson(value: unknown): string;
279
- }
280
-
281
- declare class InMemoryExtensionHost implements ExtensionHost {
282
- private readonly configs;
283
- private readonly agentState;
284
- private readonly globalState;
285
- private readonly listeners;
286
- extendApi?(extensionId: string): HostApiExtension | undefined;
287
- constructor(options?: {
288
- configs?: Record<string, Record<string, JsonObject>>;
289
- agentState?: Record<string, Record<string, Record<string, JsonValue>>>;
290
- globalState?: Record<string, Record<string, JsonValue>>;
291
- extendApi?: (extensionId: string) => HostApiExtension | undefined;
292
- });
293
- setConfig(extensionId: string, config: JsonObject | null, scope?: ScopeRef): void;
294
- getConfig(extensionId: string, scope?: ScopeRef): JsonObject | null;
295
- onConfigChanged(listener: (extensionId: string, scope: ScopeRef) => void): () => void;
296
- notifyConfigChanged(extensionId: string, scope?: ScopeRef): void;
297
- getAgentState(extensionId: string, agentId: string, key: string): JsonValue | undefined;
298
- setAgentState(extensionId: string, agentId: string, key: string, value: JsonValue): void;
299
- deleteAgentState(extensionId: string, agentId: string, key: string): void;
300
- getGlobalState(extensionId: string, key: string): JsonValue | undefined;
301
- setGlobalState(extensionId: string, key: string, value: JsonValue): void;
302
- deleteGlobalState(extensionId: string, key: string): void;
303
- }
304
-
305
- /**
306
- * Extension runner — manages extension loading and hook execution.
307
- *
308
- * Architecture reference: PI's ExtensionRunner
309
- * - Per-extension tracking via Extension objects
310
- * - Shared ExtensionRuntime with invalidate/assertActive
311
- * - Direct `on()` API for hook registration
312
- * - Error listener pattern for structured error handling
313
- * - Tool registration support
314
- */
315
-
316
- /** The Resource Source an Extension registration lands in: Global (`[]`) is `rowan.extensions`, any other Scope `rowan.extensions:<scopeToKey(scope)>`. */
317
- declare function extensionSourceId(scope?: ScopeRef): string;
318
- type ExtensionRunnerOptions = {
319
- entryPhaseId?: string | null;
320
- cwd?: string;
321
- host?: ExtensionHost;
322
- };
323
- /**
324
- * Manages extensions and provides hooks for the agent loop.
325
- *
326
- * Features:
327
- * - Per-extension tracking (handlers, tools, phases)
328
- * - Shared runtime with lifecycle protection (invalidate/assertActive)
329
- * - Error listener pattern for structured error handling
330
- * - Direct hook API and extension-loaded hook API
331
- * - Tool registration for LLM-callable tools
332
- * - EventBus for inter-extension communication
333
- *
334
- * @example
335
- * ```ts
336
- * const runner = createExtensionRunner();
337
- *
338
- * // Direct hook registration
339
- * const unsub = runner.on("before_tool_call", (event) => {
340
- * return { allow: false, reason: "Blocked" };
341
- * });
342
- *
343
- * // Error handling
344
- * runner.onError((error) => {
345
- * console.error(`Extension error in ${error.extensionPath}:`, error.error);
346
- * });
347
- *
348
- * // Load extensions
349
- * await runner.loadExtensions(extensions);
350
- * runner.bind();
351
- * ```
352
- */
353
- declare class ExtensionRunner {
354
- readonly hooks: HooksManager;
355
- readonly runtime: ExtensionRuntime;
356
- readonly events: EventBus;
357
- readonly host: ExtensionHost;
358
- private readonly cwd;
359
- private readonly abortController;
360
- private _idle;
361
- private readonly extensions;
362
- private readonly runState;
363
- private readonly configChangeListeners;
364
- private readonly hostUnsubscribers;
365
- private readonly phases;
366
- private _phaseCache;
367
- private readonly skills;
368
- private readonly pendingProviders;
369
- private bound;
370
- private readonly errorListeners;
371
- private readonly capabilityListeners;
372
- private readonly resourceChangeListeners;
373
- /** Current agent context — set by the agent before each phase */
374
- currentContext?: AgentContext;
375
- constructor(options?: ExtensionRunnerOptions);
376
- /** Whether the agent is currently idle (not streaming). */
377
- get isIdle(): boolean;
378
- /** Set idle state — called by the agent loop. */
379
- setIdle(idle: boolean): void;
380
- /** Abort signal for the current runner instance. */
381
- get signal(): AbortSignal;
382
- /** Abort the current runner operation. */
383
- abort(): void;
384
- /**
385
- * Register an error listener.
386
- * Returns an unsubscribe function.
387
- */
388
- onError(listener: ExtensionErrorListener): () => void;
389
- /**
390
- * Emit a structured extension error to all listeners.
391
- */
392
- emitError(error: ExtensionError): void;
393
- /**
394
- * Mark all extension contexts as stale.
395
- * After calling this, any captured ExtensionAPI or ExtensionContext will throw
396
- * on use. Used during runtime replacement or reload.
397
- */
398
- invalidate(message?: string): void;
399
- /**
400
- * Subscribe to a specific hook event type.
401
- * Returns an unsubscribe function.
402
- *
403
- * @example
404
- * ```ts
405
- * const unsub = runner.on("before_tool_call", (event) => {
406
- * return { allow: false, reason: "Blocked" };
407
- * });
408
- * unsub(); // Cancel subscription
409
- * ```
410
- */
411
- on<K extends HookEventType>(type: K, handler: HookHandler<K>): () => void;
412
- /**
413
- * Load and initialize extensions.
414
- * Creates Extension tracking objects and calls each factory with an ExtensionAPI.
415
- */
416
- loadExtensions(extensions: LoadedExtension[]): Promise<void>;
417
- /** Dispose all active Extensions in reverse activation order. */
418
- close(): Promise<void>;
419
- get extensionHost(): ExtensionHost;
420
- notifyConfigChanged(extensionId: string, scope: ScopeRef): Promise<void>;
421
- getRunState(runId: string, extensionId: string, key: string): JsonValue | undefined;
422
- setRunState(runId: string, extensionId: string, key: string, value: JsonValue): void;
423
- deleteRunState(runId: string, extensionId: string, key: string): void;
424
- dropRunState(runId: string): void;
425
- /** Get all registered tools from all extensions. */
426
- getAllRegisteredTools(): RegisteredTool[];
427
- /**
428
- * Get a tool definition by name. Returns undefined if not found.
429
- */
430
- getToolDefinition(toolName: string): RegisteredTool["definition"] | undefined;
431
- /** Get all contributed capabilities across all extensions. */
432
- getCapabilities(): readonly ExtensionCapability[];
433
- /**
434
- * Subscribe to capability changes (contributions added, removed, or extensions disposed).
435
- * Returns an unsubscribe function.
436
- */
437
- onCapabilitiesChanged(listener: (capabilities: readonly ExtensionCapability[]) => void): () => void;
438
- /**
439
- * Subscribe to resource changes (tools, phases, skills registered, unregistered, or disposed).
440
- * Used by RuntimeBootstrapRegistry to re-commit implicit sources after activation.
441
- */
442
- onResourceChange(listener: (kind: "tool" | "phase" | "skill") => Promise<void> | void): () => void;
443
- private notifyResourceChange;
444
- triggerUiAction(event: {
445
- contributionId: string;
446
- actionId: string;
447
- scope?: ScopeRef;
448
- }): void;
449
- getPhase(name: string): Phase | undefined;
450
- getPhases(): Phase[];
451
- getRegisteredPhases(): readonly RegisteredPhase[];
452
- createPhaseRegistry(input?: {
453
- entryPhaseId?: string | null;
454
- }): PhaseRegistry;
455
- /** Adapt an extension RegisteredPhase to the core Phase type. */
456
- adaptToPhase(reg: RegisteredPhase): Phase;
457
- getSkills(): Skill[];
458
- getRegisteredSkills(): readonly RegisteredSkill[];
459
- /**
460
- * Bind the runner — flushes pending provider registrations and
461
- * replaces runtime stubs with real implementations.
462
- */
463
- bind(): void;
464
- /**
465
- * Generic emit — fire-and-forget for any event type.
466
- */
467
- emit<K extends HookEventType>(eventType: K, event: Parameters<HookHandler<K>>[0]): Promise<void>;
468
- /**
469
- * Unified hook emission — returns the first non-undefined result.
470
- */
471
- private emitHook;
472
- emitBeforePhase(phaseId: string, input: PhaseContext): Promise<{
473
- abort?: any;
474
- skip?: any;
475
- input?: PhaseContext;
476
- }>;
477
- emitAfterPhase(phaseId: string, output: PhaseOutput): Promise<{
478
- abort?: any;
479
- retry?: PhaseContext;
480
- output?: PhaseOutput;
481
- }>;
482
- emitBeforePrompt(phaseId: string, input: PhaseContext): Promise<PhaseContext>;
483
- emitRunStart(event: {
484
- runId: string;
485
- agentId: string;
486
- metadata: Readonly<Record<string, unknown>>;
487
- turn: JsonObject;
488
- }): Promise<void>;
489
- emitRunEnd(event: {
490
- runId: string;
491
- agentId: string;
492
- outcome: unknown;
493
- }): Promise<void>;
494
- emitBeforeToolCall(tool: Tool, args: unknown, context?: {
495
- runId?: string;
496
- agentId?: string;
497
- toolCallId?: string;
498
- metadata?: Readonly<Record<string, unknown>>;
499
- agentMetadata?: Readonly<Record<string, unknown>>;
500
- answer?: unknown;
501
- scope?: ScopeRef;
502
- turn?: JsonObject;
503
- }): Promise<BeforeToolCallResult>;
504
- emitAfterToolCall(tool: Tool, result: ToolResult, context?: {
505
- runId?: string;
506
- agentId?: string;
507
- toolCallId?: string;
508
- metadata?: Readonly<Record<string, unknown>>;
509
- scope?: ScopeRef;
510
- turn?: JsonObject;
511
- }): Promise<ToolResult>;
512
- /**
513
- * Create an ExtensionAPI for a specific extension.
514
- * Registration methods write to the extension tracking object.
515
- * Action methods delegate to the shared runtime.
516
- */
517
- private createExtensionAPI;
518
- private registerTool;
519
- private unregisterTool;
520
- private contributeCapability;
521
- private notifyCapabilitiesChanged;
522
- private registerPhase;
523
- private registerPhaseDefinition;
524
- private unregisterPhase;
525
- private loadRegisteredPhase;
526
- private registerSkill;
527
- private registerSkillDefinition;
528
- private unregisterSkill;
529
- private loadRegisteredSkill;
530
- private registerProvider;
531
- private unregisterProvider;
532
- private flushPendingProviders;
533
- private getRegisteredPhase;
534
- private collectRegisteredPhases;
535
- private rollbackExtension;
536
- private disposeExtension;
537
- }
538
-
539
- type ToolCallPresentationInput = Readonly<{
540
- status: ToolCallStatus;
541
- args: JsonValue$1;
542
- progress?: ToolProgress;
543
- result?: ToolExecutionResult;
544
- }>;
545
- type ToolCallPresentationOutput = {
546
- title?: string;
547
- content?: ToolCallContent[];
548
- locations?: ToolCallLocation[];
549
- _meta?: JsonObject$1;
550
- };
551
- type ToolCallMergeTarget = {
552
- title?: string;
553
- kind?: ToolKind;
554
- status?: ToolCallStatus;
555
- locations?: ToolCallLocation[];
556
- content?: ToolCallContent[];
557
- rawInput?: JsonValue$1;
558
- rawOutput?: JsonValue$1;
559
- _meta?: JsonObject$1;
560
- };
561
- type ToolCallMergePatch = {
562
- title?: string;
563
- kind?: ToolKind;
564
- status?: ToolCallStatus;
565
- locations?: ToolCallLocation[];
566
- content?: ToolCallContent[];
567
- rawInput?: JsonValue$1;
568
- rawOutput?: JsonValue$1;
569
- _meta?: JsonObject$1;
570
- };
571
- declare function mergeToolCall<T extends ToolCallMergeTarget>(target: T, patch: ToolCallMergePatch): T;
572
-
573
- type ExtensionContribution = LoadedExtension;
574
- type ExtensionLoadInput = LoadInput<ExtensionContribution>;
575
- type ExtensionActivationError = Readonly<{
576
- path: string;
577
- error: string;
578
- }>;
579
- type ExtensionActivationResult = Readonly<{
580
- active: readonly string[];
581
- errors: readonly ExtensionActivationError[];
582
- revision?: string;
583
- registered?: readonly string[];
584
- skipped?: readonly ResourceDiagnostic[];
585
- }>;
586
- type ExtensionLifetimeErrorCode = "extensions_frozen" | "extensions_closed";
587
- declare class ExtensionLifetimeError extends Error {
588
- readonly code: ExtensionLifetimeErrorCode;
589
- constructor(code: ExtensionLifetimeErrorCode, message: string);
590
- }
591
- /** Runtime-global Extension activation and lifetime boundary. */
592
- declare class RuntimeExtensionLifetime {
593
- private readonly runner;
594
- private frozen;
595
- private closed;
596
- constructor(options?: {
597
- cwd?: string;
598
- host?: ExtensionHost;
599
- });
600
- activate(extensions: readonly LoadedExtension[]): Promise<ExtensionActivationResult>;
601
- tools(): readonly RegisteredTool[];
602
- phases(): readonly Phase[];
603
- registeredPhases(): readonly RegisteredPhase[];
604
- skills(): readonly Skill[];
605
- registeredSkills(): readonly RegisteredSkill[];
606
- get extensionRunner(): ExtensionRunner;
607
- get extensionHost(): ExtensionHost;
608
- onResourceChange(listener: (kind: "tool" | "phase" | "skill") => Promise<void> | void): () => void;
609
- dropRunState(runId: string): void;
610
- close(): Promise<void>;
611
- }
612
- /** Bootstrap-only Registry facade; its Extension method disappears after init. */
613
- declare class RuntimeBootstrapRegistry extends ResourceRegistry {
614
- private readonly extensions;
615
- private readonly knownSources;
616
- private commitQueue;
617
- constructor(extensions?: RuntimeExtensionLifetime);
618
- private recommit;
619
- get extensionHost(): ExtensionHost;
620
- /** Install Rowan-owned implicit resources before any host source is read. */
621
- ensureCoreResources(): Promise<void>;
622
- loadExtensions(input: readonly LoadedExtension[] | ExtensionLoadInput): Promise<ExtensionActivationResult>;
623
- get extensionRunner(): ExtensionRunner;
624
- get extensionTools(): readonly RegisteredTool[];
625
- get extensionPhases(): readonly Phase[];
626
- closeExtensions(): Promise<void>;
627
- }
628
-
629
- type DefinitionLayer = Readonly<{
630
- description?: string;
631
- prompt?: string;
632
- model?: ModelRef;
633
- tools?: readonly string[];
634
- skills?: readonly string[];
635
- phases?: PhaseRegistrySelection;
636
- }>;
637
- type AgentConfiguration = Readonly<{
638
- identity: string;
639
- definition: Readonly<{
640
- name: string;
641
- layer?: DefinitionLayer;
642
- }>;
643
- resourceView: ResourceView;
644
- contexts?: readonly ContextCandidate[];
645
- /** Trusted Host-owned Contexts rendered as durable user messages. */
646
- additionalContexts?: readonly ContextCandidate[];
647
- cwd?: string;
648
- maxAttempts?: number;
649
- model: ModelConfig | ModelRef;
650
- stream?: StreamFn;
651
- }>;
652
- type ConfigurationSnapshot = Readonly<{
653
- identity: string;
654
- definition: AgentDefinition;
655
- resources: Readonly<{
656
- tools: readonly Tool$1[];
657
- skills: readonly Skill[];
658
- phases?: PhaseRegistry;
659
- revisions: Readonly<Record<ResourceKind, readonly string[]>>;
660
- refs: Readonly<Record<ResourceKind, readonly ResourceRef[]>>;
661
- }>;
662
- contexts: readonly ContextCandidate[];
663
- additionalContexts: readonly ContextCandidate[];
664
- resourceView: ResourceView;
665
- cwd?: string;
666
- maxAttempts?: number;
667
- model: ModelConfig | ModelRef;
668
- stream?: StreamFn;
669
- }>;
670
- /** Resolve one Definition request into one immutable, source-qualified snapshot. */
671
- declare function resolveConfigurationSnapshot(registry: ResourceRegistry, input: AgentConfiguration): ConfigurationSnapshot;
672
- /** Whether one stored configuration is already a resolved snapshot. A snapshot
673
- * is used as it stands; a request is resolved against the current sources. */
674
- declare function isConfigurationSnapshot(config: AgentConfiguration | ConfigurationSnapshot): config is ConfigurationSnapshot;
675
-
676
- type UserInput = string | Readonly<{
677
- content: UserContent;
678
- metadata?: Metadata;
679
- thinkingLevel?: ThinkingLevel;
680
- providerOptions?: JsonObject;
681
- }>;
682
- type HistorySeed = readonly Message[];
683
- type ContextStatus = Readonly<{
684
- tokens: number;
685
- contextWindow: number;
686
- percent: number;
687
- thresholdTokens: number;
688
- estimated: boolean;
689
- coveredThrough?: Readonly<{
690
- messageId: MessageId;
691
- sequence: number;
692
- }>;
693
- }>;
694
- type ContextCompactionRecord = Readonly<{
695
- id: string;
696
- agentId: AgentId;
697
- summary: string;
698
- coveredThrough?: Readonly<{
699
- messageId: MessageId;
700
- sequence: number;
701
- }>;
702
- instructions?: string;
703
- createdAt: string;
704
- }>;
705
- /** Who is calling which tool, without the ability to ask or suspend. Hosts that
706
- * describe a call before it runs (for example to build a confirmation) only
707
- * have this much. */
708
- type ToolCallContext = Readonly<{
709
- agentId: AgentId;
710
- runId: RunId;
711
- /** Opaque JSON metadata captured from the Agent and Run records. Rowan does
712
- * not interpret host/domain fields. */
713
- agentMetadata?: Metadata;
714
- runMetadata?: Metadata;
715
- toolCallId: ToolCallId;
716
- /** The model's id for this call, matching `tool_call_delta` events; absent when a host runs the tool itself. */
717
- providerToolCallId?: string;
718
- scope?: ScopeRef;
719
- turn?: JsonObject;
720
- reportProgress(progress: ToolProgress): void;
721
- }>;
722
- type ToolInvocationContext = ToolCallContext & Readonly<{
723
- interaction: RunInteractionDriver;
724
- }>;
725
-
726
- type Tool$1 = Readonly<{
727
- name: string;
728
- /** Rowan-owned Core Tool; Core Tools bypass Definition/Phase filtering. */
729
- core?: boolean;
730
- description: string;
731
- parameters: Type.TSchema;
732
- promptSnippet?: string;
733
- promptGuidelines?: readonly string[];
734
- kind?: ToolKind;
735
- annotations?: ToolAnnotations;
736
- _meta?: JsonObject;
737
- present?(call: ToolCallPresentationInput): {
738
- title?: string;
739
- content?: ToolCallContent[];
740
- locations?: ToolCallLocation[];
741
- _meta?: JsonObject;
742
- } | undefined | void | Promise<{
743
- title?: string;
744
- content?: ToolCallContent[];
745
- locations?: ToolCallLocation[];
746
- _meta?: JsonObject;
747
- } | undefined | void>;
748
- execute(args: JsonValue, context: ToolInvocationContext, signal: AbortSignal): Promise<ToolExecutionResult>;
749
- }>;
750
- type BeforeToolCallDecision = Readonly<{
751
- allow: true;
752
- }> | Readonly<{
753
- allow: false;
754
- reason: string;
755
- }> | Readonly<{
756
- interaction: RunInteractionRequest;
757
- }>;
758
- type BeforeToolCall = (input: Readonly<{
759
- tool: Tool$1;
760
- args: JsonValue;
761
- context: ToolInvocationContext;
762
- signal: AbortSignal;
763
- answer?: JsonValue;
764
- }>) => BeforeToolCallDecision | Promise<BeforeToolCallDecision>;
765
- type AfterToolCall = (input: Readonly<{
766
- tool: Tool$1;
767
- result: ToolExecutionResult;
768
- context: ToolInvocationContext;
769
- signal: AbortSignal;
770
- }>) => ToolExecutionResult | Promise<ToolExecutionResult>;
771
- type InvocationSource = "auto" | "implicit" | "external";
772
- type InvocationCatalogEntry = Readonly<{
773
- kind: "phase" | "skill";
774
- name: string;
775
- description: string;
776
- input?: Phase["input"];
777
- core?: boolean;
778
- disableAutoInvocation: boolean;
779
- disableImplicitInvocation: boolean;
780
- filePath: string;
781
- }>;
782
- type AgentRecord = Readonly<{
783
- id: AgentId;
784
- metadata?: Metadata;
785
- currentConfigToken?: ConfigToken;
786
- currentConfigIdentity?: string;
787
- createdAt: string;
788
- activatedAt?: string;
789
- updatedAt: string;
790
- }>;
791
- type AgentDeletionRequest = Readonly<{
792
- agentId: AgentId;
793
- expectedRunIds: readonly RunId[];
794
- confirmation: "agent-delete-v1";
795
- }>;
796
- type ExecutionToken = Readonly<{
797
- runId: RunId;
798
- ownerEpoch: number;
799
- executionId: ExecutionId;
800
- }>;
801
- type ExecutionCheckpoint = Readonly<{
802
- codec: string;
803
- version: number;
804
- data: JsonValue;
805
- }>;
806
- type OwnerLease = Readonly<{
807
- ownerId: string;
808
- token: OwnerToken;
809
- epoch: number;
810
- expiresAt: string;
811
- }>;
812
- type RunClaim = Readonly<{
813
- run: RunRecord;
814
- execution: ExecutionToken;
815
- history: readonly Message[];
816
- }>;
817
- type ToolCallReservation = Readonly<{
818
- providerToolCallId: string;
819
- name: string;
820
- args: JsonValue;
821
- toolCallId?: ToolCallId;
822
- title?: string;
823
- kind?: ToolKind;
824
- locations?: ToolCallLocation[];
825
- content?: ToolCallContent[];
826
- _meta?: JsonObject;
827
- }>;
828
- type ToolCommit = Readonly<{
829
- run: RunRecord;
830
- toolCall: ToolCallSnapshot;
831
- }>;
832
- type ToolBatchCommit = Readonly<{
833
- run: RunRecord;
834
- toolCalls: readonly ToolCallSnapshot[];
835
- }>;
836
- type EntryPhaseSpec = Readonly<{
837
- phase: string;
838
- payload?: JsonValue;
839
- }>;
840
- type RunRecord = Readonly<{
841
- id: RunId;
842
- agentId: AgentId;
843
- agentSequence: number;
844
- readySequence: number;
845
- revision: number;
846
- state: RunState;
847
- input: UserInput;
848
- scope?: ScopeRef;
849
- cwd?: string;
850
- initialMessageId?: MessageId;
851
- invalidatedBy?: Readonly<{
852
- messageId: MessageId;
853
- messageRevision: number;
854
- }>;
855
- metadata?: Metadata;
856
- phasePayload?: JsonValue;
857
- entryPhases?: readonly EntryPhaseSpec[];
858
- pinnedConfigToken?: ConfigToken;
859
- checkpoint?: ExecutionCheckpoint;
860
- currentPhaseId?: string;
861
- openInteractions?: readonly RunInteraction[];
862
- interactionAnswers?: Readonly<Record<string, JsonValue>>;
863
- execution?: ExecutionToken;
864
- outcome?: Outcome$1;
865
- failure?: RunFailure;
866
- cancellationReason?: string;
867
- createdAt: string;
868
- updatedAt: string;
869
- }>;
870
- type MessageRevisionResult = Readonly<{
871
- message: UserMessage & Readonly<{
872
- messageRevision: number;
873
- }>;
874
- replacementRun: RunRecord;
875
- invalidatedRunIds: readonly RunId[];
876
- affectedToolCallIds: readonly ToolCallId[];
877
- effectDigest?: string;
878
- }>;
879
- type RetentionResult = Readonly<{
880
- deletedRunIds: readonly RunId[];
881
- deletedToolCallIds: readonly ToolCallId[];
882
- deletedEventCount: number;
883
- retentionFloor: EventCursor;
884
- skipped?: "active_consumers" | "no_eligible_events";
885
- }>;
886
- type AgentSummary = Readonly<{
887
- id: AgentId;
888
- metadata?: Metadata;
889
- currentConfigIdentity?: string;
890
- createdAt: string;
891
- activatedAt: string;
892
- updatedAt: string;
893
- }>;
894
- type RunSummary = Readonly<{
895
- id: RunId;
896
- agentId: AgentId;
897
- agentSequence: number;
898
- state: RunState;
899
- metadata?: Metadata;
900
- createdAt: string;
901
- updatedAt: string;
902
- }>;
903
- type Page<T, Cursor> = Readonly<{
904
- items: readonly T[];
905
- next?: Cursor;
906
- }>;
907
- type RunSnapshotBase = Readonly<{
908
- runId: RunId;
909
- agentId: AgentId;
910
- agentSequence: number;
911
- revision: number;
912
- input: UserInput;
913
- scope?: ScopeRef;
914
- cwd?: string;
915
- metadata?: Metadata;
916
- /** Effective entry Phase payload the Run started with (defaults filled). */
917
- phasePayload?: JsonValue;
918
- entryPhases?: readonly EntryPhaseSpec[];
919
- messageCount: number;
920
- toolCallCount: number;
921
- currentPhaseId?: string;
922
- createdAt: string;
923
- updatedAt: string;
924
- cursor: EventCursor;
925
- }>;
926
- type RunSnapshot = RunSnapshotBase & (Readonly<{
927
- state: "queued" | "running";
928
- currentPhaseId?: string;
929
- interactions?: readonly RunInteraction[];
930
- }> | Readonly<{
931
- state: "input_required";
932
- interactions: readonly RunInteraction[];
933
- answers: Readonly<Record<string, JsonValue>>;
934
- }> | Readonly<{
935
- state: "completed";
936
- outcome: Outcome$1;
937
- output?: AssistantMessage;
938
- }> | Readonly<{
939
- state: "failed";
940
- failure: RunFailure;
941
- }> | Readonly<{
942
- state: "cancelled";
943
- reason?: string;
944
- }>);
945
- type RunBoundary = Readonly<{
946
- type: "input_required";
947
- interactions: readonly RunInteraction[];
948
- answers: Readonly<Record<string, JsonValue>>;
949
- }> | Readonly<{
950
- type: "completed";
951
- outcome: Outcome$1;
952
- output?: AssistantMessage;
953
- }> | Readonly<{
954
- type: "failed";
955
- failure: RunFailure;
956
- }> | Readonly<{
957
- type: "cancelled";
958
- reason?: string;
959
- }>;
960
- type ConfigResolution = Readonly<{
961
- kind: "available";
962
- config: AgentConfiguration | ConfigurationSnapshot;
963
- } | {
964
- kind: "deferred";
965
- retryAfterMs?: number;
966
- } | {
967
- kind: "unavailable";
968
- reason: string;
969
- }>;
970
- type ConfigPutResult = Readonly<{
971
- kind: "stored";
972
- token: string;
973
- } | {
974
- kind: "identity_conflict";
975
- }>;
976
- interface ConfigProvider {
977
- put(input: {
978
- agentId: AgentId;
979
- agentMetadata?: Metadata;
980
- config: AgentConfiguration | ConfigurationSnapshot;
981
- operationId: string;
982
- signal: AbortSignal;
983
- }): Promise<ConfigPutResult>;
984
- resolve(input: {
985
- agentId: AgentId;
986
- agentMetadata?: Metadata;
987
- token: ConfigToken;
988
- signal: AbortSignal;
989
- }): Promise<ConfigResolution>;
990
- }
991
- interface OwnedStore {
992
- readonly lease: OwnerLease;
993
- reserveAgent(input: {
994
- idempotencyKey: string;
995
- metadata?: Metadata;
996
- configIdentity?: string;
997
- historySeed?: HistorySeed;
998
- }): Promise<AgentRecord>;
999
- activateAgent(agentId: AgentId, configToken?: ConfigToken, configIdentity?: string): Promise<AgentRecord>;
1000
- updateAgentConfigToken(input: {
1001
- agentId: AgentId;
1002
- token: ConfigToken;
1003
- configIdentity?: string;
1004
- idempotencyKey: string;
1005
- }): Promise<AgentRecord>;
1006
- deleteAgent(input: AgentDeletionRequest): Promise<void>;
1007
- reviseMessage(input: {
1008
- agentId: AgentId;
1009
- messageId: MessageId;
1010
- expectedMessageRevision: number;
1011
- content: UserContent;
1012
- operationId: string;
1013
- effectDigestConfirmation?: string;
1014
- }): Promise<MessageRevisionResult>;
1015
- compact(input?: {
1016
- now?: string;
1017
- retentionMs?: number;
1018
- }): Promise<RetentionResult>;
1019
- contextStatus(agentId: AgentId, contextWindow: number): Promise<ContextStatus>;
1020
- contextMessages(agentId: AgentId, recentTokenBudget?: number): Promise<readonly Message[]>;
1021
- commitContextCompaction(record: ContextCompactionRecord): Promise<ContextCompactionRecord>;
1022
- createRun(input: {
1023
- agentId: AgentId;
1024
- input: UserInput;
1025
- metadata?: Metadata;
1026
- scope?: ScopeRef;
1027
- cwd?: string;
1028
- phasePayload?: JsonValue;
1029
- entryPhases?: readonly EntryPhaseSpec[];
1030
- pinnedConfigToken?: ConfigToken;
1031
- idempotencyKey: string;
1032
- }): Promise<RunRecord>;
1033
- claimRun(input: {
1034
- runId: RunId;
1035
- expectedRevision: number;
1036
- executionId?: ExecutionId;
1037
- messageId?: MessageId;
1038
- configToken?: ConfigToken;
1039
- additionalContexts?: readonly ContextCandidate[];
1040
- }): Promise<RunClaim>;
1041
- failQueuedRun(input: {
1042
- runId: RunId;
1043
- expectedRevision: number;
1044
- failure: QueuedRunFailure;
1045
- }): Promise<RunRecord>;
1046
- commitPhaseEntered(input: {
1047
- runId: RunId;
1048
- execution: ExecutionToken;
1049
- expectedRevision: number;
1050
- phaseId: string;
1051
- visit: number;
1052
- }): Promise<RunRecord>;
1053
- commitPhaseOutput(input: {
1054
- runId: RunId;
1055
- execution: ExecutionToken;
1056
- expectedRevision: number;
1057
- message: AssistantMessage;
1058
- }): Promise<RunRecord>;
1059
- commitInputRequired(input: {
1060
- runId: RunId;
1061
- execution: ExecutionToken;
1062
- expectedRevision: number;
1063
- phase: string;
1064
- prompt?: AssistantMessage;
1065
- checkpoint: ExecutionCheckpoint;
1066
- interactions?: readonly RunInteraction[];
1067
- interactionAnswers?: Readonly<Record<string, JsonValue>>;
1068
- pendingToolCallIds?: readonly ToolCallId[];
1069
- }): Promise<RunRecord>;
1070
- answerInteraction(input: {
1071
- runId: RunId;
1072
- interactionId: string;
1073
- expectedRevision: number;
1074
- input?: JsonValue;
1075
- cancel?: boolean;
1076
- }): Promise<RunRecord>;
1077
- commitOutcome(input: {
1078
- runId: RunId;
1079
- execution: ExecutionToken;
1080
- expectedRevision: number;
1081
- outcome?: Outcome$1;
1082
- failure?: RunFailure;
1083
- output?: AssistantMessage;
1084
- }): Promise<RunRecord>;
1085
- reserveToolCall(input: {
1086
- runId: RunId;
1087
- execution: ExecutionToken;
1088
- expectedRevision: number;
1089
- requestMessageId: MessageId;
1090
- name: string;
1091
- args: JsonValue;
1092
- toolCallId?: ToolCallId;
1093
- providerToolCallId?: string;
1094
- title?: string;
1095
- kind?: ToolKind;
1096
- locations?: ToolCallLocation[];
1097
- content?: ToolCallContent[];
1098
- _meta?: JsonObject;
1099
- model?: ModelRef;
1100
- usage?: LlmTokenUsage;
1101
- }): Promise<ToolCommit>;
1102
- reserveToolCalls(input: {
1103
- runId: RunId;
1104
- execution: ExecutionToken;
1105
- expectedRevision: number;
1106
- requestMessageId: MessageId;
1107
- calls: readonly ToolCallReservation[];
1108
- /** The model response's blocks, so the request message keeps what preceded the Tool Calls. */
1109
- contentBlocks?: readonly ContentBlock[];
1110
- model?: ModelRef;
1111
- usage?: LlmTokenUsage;
1112
- }): Promise<ToolBatchCommit>;
1113
- startToolCall(input: {
1114
- runId: RunId;
1115
- execution: ExecutionToken;
1116
- expectedRevision: number;
1117
- toolCallId: ToolCallId;
1118
- title?: string;
1119
- kind?: ToolKind;
1120
- locations?: ToolCallLocation[];
1121
- content?: ToolCallContent[];
1122
- _meta?: JsonObject;
1123
- }): Promise<ToolCommit>;
1124
- suspendToolCall(input: {
1125
- runId: RunId;
1126
- execution: ExecutionToken;
1127
- expectedRevision: number;
1128
- toolCallId: ToolCallId;
1129
- }): Promise<ToolCommit>;
1130
- commitToolResult(input: {
1131
- runId: RunId;
1132
- execution: ExecutionToken;
1133
- expectedRevision: number;
1134
- toolCallId: ToolCallId;
1135
- result: ToolExecutionResult;
1136
- state: "completed" | "failed" | "indeterminate";
1137
- reason?: string;
1138
- title?: string;
1139
- kind?: ToolKind;
1140
- content?: ToolCallContent[];
1141
- locations?: ToolCallLocation[];
1142
- rawOutput?: JsonValue;
1143
- _meta?: JsonObject;
1144
- }): Promise<ToolCommit>;
1145
- cancelRun(input: {
1146
- runId: RunId;
1147
- expectedRevision?: number;
1148
- reason?: string;
1149
- output?: AssistantMessage;
1150
- }): Promise<RunRecord>;
1151
- recordToolCall(input: {
1152
- runId: RunId;
1153
- execution?: ExecutionToken;
1154
- update: ToolCall$1 | ToolCallUpdate;
1155
- external?: boolean;
1156
- contentIndex?: number;
1157
- }): Promise<DurableRunEvent>;
1158
- snapshotRun(runId: RunId): Promise<RunSnapshot>;
1159
- history(agentId: AgentId): Promise<readonly Message[]>;
1160
- listAgents(): Promise<readonly AgentRecord[]>;
1161
- listRuns(input?: {
1162
- agentId?: AgentId;
1163
- states?: readonly RunState[];
1164
- }): Promise<readonly RunRecord[]>;
1165
- listEvents(input?: {
1166
- after?: EventCursor;
1167
- }): Promise<readonly DurableRunEvent[]>;
1168
- openConsumer(consumerId: string): Promise<ConsumerRegistration>;
1169
- advanceConsumerCheckpoint(input: {
1170
- consumerId: string;
1171
- cursor: EventCursor;
1172
- }): Promise<void>;
1173
- renewOwner(leaseMs: number): Promise<OwnerLease>;
1174
- sealAndReleaseOwner(): Promise<void>;
1175
- }
1176
- interface DurableStore {
1177
- openOwner(input: {
1178
- ownerId: string;
1179
- leaseMs: number;
1180
- }): Promise<OwnedStore>;
1181
- }
1182
- type AgentRuntimeOptions = Readonly<{
1183
- store: DurableStore;
1184
- configs?: ConfigProvider;
1185
- concurrency?: number;
1186
- bootstrap?: (registry: RuntimeBootstrapRegistry) => void | Promise<void>;
1187
- host?: ExtensionHost;
1188
- sessionFiles?: Readonly<{
1189
- dir: string;
1190
- }>;
1191
- /** @internal Private / testing parameter to override retry delay */
1192
- retryDelayMs?: number;
1193
- }>;
1194
- type DurableConsumer = Readonly<{
1195
- caughtUp: Promise<void>;
1196
- done: Promise<void>;
1197
- stop(): void;
1198
- }>;
1199
- interface AgentRun {
1200
- readonly id: RunId;
1201
- snapshot(): Promise<RunSnapshot>;
1202
- observe(options?: {
1203
- after?: EventCursor;
1204
- signal?: AbortSignal;
1205
- }): AsyncIterable<RunEvent>;
1206
- wait(options?: {
1207
- signal?: AbortSignal;
1208
- }): Promise<RunBoundary>;
1209
- respondInteraction(input: {
1210
- interactionId: string;
1211
- input?: JsonValue;
1212
- cancel?: boolean;
1213
- }): Promise<void>;
1214
- cancel(reason?: string): Promise<RunBoundary>;
1215
- }
1216
- interface AgentRuntime$1 {
1217
- readonly host: ExtensionHost;
1218
- loadAgents(input: LoadInput<AgentDefinition>): Promise<LoadResult>;
1219
- loadSkills(input: LoadInput<Skill>): Promise<LoadResult>;
1220
- loadPhases(input: LoadInput<Phase>): Promise<LoadResult>;
1221
- loadTools(input: Readonly<{
1222
- sourceId: string;
1223
- values: readonly Tool$1[];
1224
- }>): Promise<LoadResult>;
1225
- unload(input: Readonly<{
1226
- kind: ResourceKind;
1227
- sourceId: string;
1228
- }>): Promise<LoadResult>;
1229
- createAgent(config: AgentConfiguration, options?: {
1230
- idempotencyKey?: string;
1231
- metadata?: Metadata;
1232
- historySeed?: HistorySeed;
1233
- }): Promise<AgentId>;
1234
- updateAgentConfig(agentId: AgentId, config: AgentConfiguration, options: {
1235
- idempotencyKey: string;
1236
- }): Promise<void>;
1237
- deleteAgent(input: AgentDeletionRequest): Promise<void>;
1238
- revise(agentId: AgentId, input: {
1239
- messageId: MessageId;
1240
- expectedMessageRevision: number;
1241
- content: UserContent;
1242
- operationId: string;
1243
- effectDigestConfirmation?: string;
1244
- }): Promise<MessageRevisionResult>;
1245
- compact(input?: {
1246
- now?: string;
1247
- retentionMs?: number;
1248
- }): Promise<RetentionResult>;
1249
- start(agentId: AgentId, input: UserInput, options: {
1250
- idempotencyKey: string;
1251
- metadata?: Metadata;
1252
- scope?: ScopeRef;
1253
- cwd?: string;
1254
- phasePayload?: JsonValue;
1255
- entryPhases?: ReadonlyArray<EntryPhaseSpec>;
1256
- }): Promise<AgentRun>;
1257
- run(runId: RunId): AgentRun;
1258
- contextStatus(agentId: AgentId, options?: {
1259
- contextWindow?: number;
1260
- }): Promise<ContextStatus>;
1261
- compactContext(agentId: AgentId, options?: {
1262
- input?: UserInput;
1263
- instructions?: string;
1264
- idempotencyKey?: string;
1265
- }): Promise<AgentRun>;
1266
- runPhase(agentId: AgentId, options: {
1267
- phase: string;
1268
- payload?: JsonValue;
1269
- input?: UserInput;
1270
- yieldToInput?: boolean;
1271
- idempotencyKey?: string;
1272
- }): Promise<AgentRun>;
1273
- listInvocations(agentId: AgentId, options: {
1274
- source: InvocationSource;
1275
- }): Promise<readonly InvocationCatalogEntry[]>;
1276
- history(agentId: AgentId): Promise<readonly Message[]>;
1277
- listAgents(input?: {
1278
- after?: AgentListCursor;
1279
- limit?: number;
1280
- }): Promise<Page<AgentSummary, AgentListCursor>>;
1281
- listRuns(input?: {
1282
- agentId?: AgentId;
1283
- states?: readonly RunState[];
1284
- after?: RunListCursor;
1285
- limit?: number;
1286
- }): Promise<Page<RunSummary, RunListCursor>>;
1287
- consume(input: {
1288
- consumerId: string;
1289
- signal: AbortSignal;
1290
- onEvent(event: DurableRunEvent, context: Readonly<{
1291
- signal: AbortSignal;
1292
- }>): void | Promise<void>;
1293
- }): Promise<DurableConsumer>;
1294
- listCapabilities(): readonly ExtensionCapability[];
1295
- onCapabilitiesChanged(listener: (capabilities: readonly ExtensionCapability[]) => void): () => void;
1296
- triggerUiAction(event: {
1297
- contributionId: string;
1298
- actionId: string;
1299
- scope?: ScopeRef;
1300
- }): void;
1301
- close(): Promise<void>;
1302
- }
1303
- type ConsumerRegistration = Readonly<{
1304
- cursor?: EventCursor;
1305
- waterline: EventCursor;
1306
- }>;
1307
-
1308
- interface ExtensionStateStore {
1309
- get(key: string): Promise<JsonValue | undefined>;
1310
- set(key: string, value: JsonValue): Promise<void>;
1311
- delete(key: string): Promise<void>;
1312
- }
1313
- interface ExtensionHost {
1314
- getConfig(extensionId: string, scope?: ScopeRef): Promise<JsonObject | null> | JsonObject | null;
1315
- onConfigChanged?(listener: (extensionId: string, scope: ScopeRef) => void): (() => void) | void;
1316
- getAgentState(extensionId: string, agentId: string, key: string): Promise<JsonValue | undefined> | JsonValue | undefined;
1317
- setAgentState(extensionId: string, agentId: string, key: string, value: JsonValue): Promise<void> | void;
1318
- deleteAgentState(extensionId: string, agentId: string, key: string): Promise<void> | void;
1319
- getGlobalState(extensionId: string, key: string): Promise<JsonValue | undefined> | JsonValue | undefined;
1320
- setGlobalState(extensionId: string, key: string, value: JsonValue): Promise<void> | void;
1321
- deleteGlobalState(extensionId: string, key: string): Promise<void> | void;
1322
- /**
1323
- * Called once per extension load. The returned namespaces are merged into that extension's `api`
1324
- * (a name already used by Rowan's own API is an error). `dispose` runs when the extension is
1325
- * unloaded, reloaded or fails activation, so the host can drop everything that extension registered.
1326
- */
1327
- extendApi?(extensionId: string): HostApiExtension | undefined;
1328
- }
1329
- interface HostApiExtension {
1330
- readonly namespaces: Readonly<Record<string, unknown>>;
1331
- dispose?(): void;
1332
- }
1333
- type ExtensionToolContribution = {
1334
- kind: "tool";
1335
- name: string;
1336
- description: string;
1337
- };
1338
- type ExtensionCapabilityContribution = ExtensionToolContribution;
1339
- type ExtensionCapability = {
1340
- extensionId: string;
1341
- kind: "tool";
1342
- name: string;
1343
- description: string;
1344
- };
1345
- interface SourceInfo {
1346
- source: string;
1347
- baseDir?: string;
1348
- displayName?: string;
1349
- }
1350
- /** A loaded directory Bundle used by an extension. */
1351
- type PhaseDefinition = Phase;
1352
- /** Register a Phase by directory path or Phase object; PHASE.md and direct child Skills are loaded atomically when a path is supplied. */
1353
- type PhaseRegistration = string | Phase;
1354
- type RegisteredPhase = {
1355
- definition: PhaseDefinition;
1356
- source: {
1357
- extensionPath: string;
1358
- };
1359
- sourceId: string;
1360
- scope?: ScopeRef;
1361
- };
1362
- /** Register a Skill directory (containing SKILL.md) or a Skill object. Registering an existing name replaces it. */
1363
- type SkillRegistration = string | Skill;
1364
- type RegisteredSkill = {
1365
- definition: Skill;
1366
- source: {
1367
- extensionPath: string;
1368
- };
1369
- sourceId: string;
1370
- scope?: ScopeRef;
1371
- };
1372
- /**
1373
- * Tool definition for registering LLM-callable tools via `api.tools.register()`.
1374
- *
1375
- * @example
1376
- * ```typescript
1377
- * api.tools.register({
1378
- * name: "search_docs",
1379
- * description: "Search documentation",
1380
- * parameters: { type: "object", properties: { query: { type: "string" } } },
1381
- * execute: async (args, ctx) => {
1382
- * return { content: [{ type: "text", text: "result" }] };
1383
- * },
1384
- * });
1385
- * ```
1386
- */
1387
- interface ToolDefinition {
1388
- /** Tool name (used in LLM tool calls) */
1389
- name: string;
1390
- /** Description for LLM */
1391
- description: string;
1392
- /** Parameter schema (JSON Schema) */
1393
- parameters: Record<string, unknown>;
1394
- /** Optional: one-line snippet shown in the system prompt tool list */
1395
- promptSnippet?: string;
1396
- /** Optional: additional guidelines appended to system prompt */
1397
- promptGuidelines?: string[];
1398
- kind?: ToolKind;
1399
- annotations?: ToolAnnotations;
1400
- _meta?: JsonObject;
1401
- present?: (call: {
1402
- status: ToolCallStatus;
1403
- args: JsonValue;
1404
- progress?: ToolProgress;
1405
- result?: ToolExecutionResult;
1406
- }) => {
1407
- title?: string;
1408
- content?: ToolCallContent[];
1409
- locations?: ToolCallLocation[];
1410
- _meta?: JsonObject;
1411
- } | undefined | void | Promise<{
1412
- title?: string;
1413
- content?: ToolCallContent[];
1414
- locations?: ToolCallLocation[];
1415
- _meta?: JsonObject;
1416
- } | undefined | void>;
1417
- /** Execute the tool */
1418
- execute: (args: unknown, context: ToolInvocationContext, signal?: AbortSignal) => Promise<ToolExecutionResult>;
1419
- /** Optional: per-tool execution mode override */
1420
- executionMode?: "sequential" | "parallel";
1421
- }
1422
-
1423
- /**
1424
- * Registered tool with source metadata.
1425
- */
1426
- interface RegisteredTool {
1427
- definition: ToolDefinition;
1428
- sourceInfo: SourceInfo;
1429
- sourceId: string;
1430
- scope?: ScopeRef;
1431
- }
1432
- /**
1433
- * Structured extension error with attribution.
1434
- */
1435
- interface ExtensionError {
1436
- /** Path of the extension that caused the error */
1437
- extensionPath: string;
1438
- /** Event or operation that caused the error */
1439
- event: string;
1440
- /** Error message */
1441
- error: string;
1442
- /** Optional stack trace */
1443
- stack?: string;
1444
- }
1445
- /** Error listener callback type. */
1446
- type ExtensionErrorListener = (error: ExtensionError) => void;
1447
- type ExecOptions = {
1448
- /** Working directory for the command. Defaults to cwd passed to runtime. */
1449
- cwd?: string;
1450
- /** Environment variables to add/override. */
1451
- env?: Record<string, string>;
1452
- /** Timeout in milliseconds. */
1453
- timeout?: number;
1454
- /** AbortSignal for cancellation. */
1455
- signal?: AbortSignal;
1456
- };
1457
- type ExecResult = {
1458
- exitCode: number;
1459
- stdout: string;
1460
- stderr: string;
1461
- };
1462
- /**
1463
- * Shared runtime state created by loader, used during registration and runtime.
1464
- * All ExtensionAPI instances reference this shared state.
1465
- *
1466
- * It only owns the lifetime guard shared by captured Extension API objects.
1467
- */
1468
- interface ExtensionRuntime {
1469
- /** Throws when this extension instance is stale after runtime replacement. */
1470
- assertActive: () => void;
1471
- /** Marks this extension instance as stale after runtime replacement or reload. */
1472
- invalidate: (message?: string) => void;
1473
- }
1474
- /**
1475
- * Result of loading extensions from filesystem.
1476
- * The runner takes these and creates Extension tracking objects.
1477
- */
1478
- type LoadExtensionsResult = {
1479
- extensions: LoadedExtension[];
1480
- errors: Array<{
1481
- path: string;
1482
- error: string;
1483
- }>;
1484
- };
1485
- /**
1486
- * Pre-initialization extension form — factory + metadata.
1487
- * Runner.loadExtensions() calls the factory and creates the full Extension object.
1488
- */
1489
- interface LoadedExtension {
1490
- id?: string;
1491
- path: string;
1492
- name: string;
1493
- factory: ExtensionFactory;
1494
- manifest?: ExtensionManifest;
1495
- }
1496
- /** Extension manifest from package.json `rowan` field. */
1497
- interface ExtensionManifest {
1498
- id?: string;
1499
- entry?: string;
1500
- name?: string;
1501
- }
1502
-
1503
- /**
1504
- * Extension API object passed to extension factory function.
1505
- *
1506
- * @example
1507
- * ```typescript
1508
- * export default function(api: ExtensionAPI) {
1509
- * // api provides all extension APIs
1510
- * }
1511
- * ```
1512
- */
1513
- interface ExtensionAPI {
1514
- /** Hook events — subscribe or unsubscribe. */
1515
- hooks: {
1516
- /**
1517
- * Subscribe to a hook event.
1518
- *
1519
- * @param eventType - Hook type, e.g. "before_tool_call"
1520
- * @param handler - Hook handler, can return result to modify behavior
1521
- */
1522
- on<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
1523
- /** Unsubscribe from a hook event. */
1524
- off<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
1525
- };
1526
- /** Extension configuration — read own layered config or listen for changes. */
1527
- config: {
1528
- /** Get the extension's own effective configuration block. */
1529
- get(scope?: ScopeRef): Promise<JsonObject | null>;
1530
- /** Listen for configuration changes for a scope. */
1531
- changed(handler: (scope: ScopeRef) => void): void;
1532
- };
1533
- /** Extension state — scoped to run (in-memory) or agent (durable) or global (durable). */
1534
- state: {
1535
- /** Run-scoped in-memory state; dropped when the Run ends. */
1536
- run(runId: string): ExtensionStateStore;
1537
- /** Agent-scoped durable state; persisted with the Agent record. */
1538
- agent(agentId: string): ExtensionStateStore;
1539
- /** Extension-scoped durable state; survives process restarts. */
1540
- global(): ExtensionStateStore;
1541
- };
1542
- /** Tool capabilities — register and unregister custom tools. */
1543
- tools: {
1544
- /** Register a custom LLM-callable tool. */
1545
- register(tool: ToolDefinition, scope?: ScopeRef): Promise<void>;
1546
- /** Unregister a previously registered tool by name. */
1547
- unregister(toolName: string, scope?: ScopeRef): Promise<void>;
1548
- };
1549
- /** Capability contributions — advertise tools or features to the host. */
1550
- capabilities: {
1551
- /** Contribute a capability to the host. Returns a disposer to remove the contribution. */
1552
- contribute(contribution: ExtensionCapabilityContribution): () => void;
1553
- };
1554
- /** Model provider registration. */
1555
- providers: {
1556
- /** Register a model provider. Registering with an existing id replaces it. */
1557
- register(config: _rowan_agent_models.ProviderConfig): void;
1558
- /** Unregister a model provider by id. */
1559
- unregister(id: string): void;
1560
- };
1561
- /** Phase execution capabilities — provides Phase In/Out, phase identity, phase routing, and registration. */
1562
- phases: {
1563
- /** Register a Phase directory bundle or Phase object. */
1564
- register(phase: PhaseRegistration, scope?: ScopeRef): Promise<void>;
1565
- /** Unregister a previously registered phase by name. */
1566
- unregister(phaseName: string, scope?: ScopeRef): Promise<void> | void;
1567
- /** Phase In: get payload from previous phase */
1568
- getPayload(): unknown;
1569
- /** Phase Out: set payload for next phase */
1570
- setPayload(payload: unknown): void;
1571
- /** Phase Out: set outcome message */
1572
- setMessage(message: string): void;
1573
- /** Get current phase name */
1574
- getCurrentPhase(): string;
1575
- /** Set next phase (lower priority than PHASE.md target) */
1576
- setNextPhase(phaseName: string): void;
1577
- /** Get the next phase set by setNextPhase */
1578
- getNextPhase(): string | undefined;
1579
- /** Get the message set by setMessage */
1580
- getMessage(): string | undefined;
1581
- };
1582
- /** Skill capabilities — register and unregister standalone skills. */
1583
- skills: {
1584
- /** Register a Skill directory (containing SKILL.md) or a Skill object. Registering an existing name replaces it. */
1585
- register(skill: SkillRegistration, scope?: ScopeRef): Promise<void>;
1586
- /** Unregister a previously registered Skill by name. */
1587
- unregister(skillName: string, scope?: ScopeRef): Promise<void> | void;
1588
- };
1589
- /** Extension manifest from package.json `rowan` field. */
1590
- manifest?: ExtensionManifest;
1591
- /** Utility functions. */
1592
- utils: ExtensionUtils;
1593
- /** Runtime context — cwd, signal, exec, message access, etc. */
1594
- context: ExtensionContext;
1595
- /** Shared event bus for inter-extension communication. */
1596
- events: EventBus;
1597
- }
1598
- /**
1599
- * Extension factory function.
1600
- * Receives ExtensionAPI for registering hooks, phases, and providers.
1601
- */
1602
- type ExtensionDisposer = () => void | Promise<void>;
1603
- type ExtensionFactoryResult = void | ExtensionDisposer;
1604
- type ExtensionFactory = (api: ExtensionAPI) => ExtensionFactoryResult | Promise<ExtensionFactoryResult>;
1605
-
1606
- type PhaseStatusState = "running" | "completed";
1607
- /** Normalized status event exposed to Runtime consumers. */
1608
- type PhaseStatus = Readonly<{
1609
- state: PhaseStatusState;
1610
- /** Stable consumer-facing status identifier, e.g. `compacting`. */
1611
- kind: string;
1612
- /** Optional human-readable detail for UI/status consumers. */
1613
- message?: string;
1614
- /** Structured status payload. */
1615
- payload?: unknown;
1616
- }>;
1617
- /** Unified phase output — model-driven routing is optional; programmatic phases may normalize omission to stop. */
1618
- type PhaseOutput = {
1619
- /** User-visible assistant message. */
1620
- message?: string;
1621
- /** Final status update for non-conversational consumers. */
1622
- status?: PhaseStatus;
1623
- /** Route to next phase, or "continue" to re-execute current phase, or "stop" to end. Undefined means no model route. */
1624
- route?: string;
1625
- /** Phase name that produced this output */
1626
- phase?: string;
1627
- /** Tool calls from the model invocation (used by framework for route extraction) */
1628
- toolCalls?: Array<{
1629
- id: string;
1630
- name: string;
1631
- args: unknown;
1632
- }>;
1633
- /** Route reason extracted from route tool call (for hooks to inspect) */
1634
- routeReason?: string;
1635
- /** Structured data from this phase, passed to the next phase */
1636
- payload?: unknown;
1637
- };
1638
- /** Phase machine state — tracks position and inter-phase data */
1639
- interface PhaseState {
1640
- current: string;
1641
- available: string[];
1642
- iterations: number;
1643
- payload?: unknown;
1644
- }
1645
- type PhaseInvocation = {
1646
- mode: "serial";
1647
- instanceId: string;
1648
- } | {
1649
- mode: "parallel";
1650
- instanceId: string;
1651
- groupId: string;
1652
- index: number;
1653
- count: number;
1654
- sourcePhaseId: string;
1655
- };
1656
- /** Durable identity of the Run execution currently invoking a Phase. */
1657
- type PhaseExecutionIdentity = Readonly<{
1658
- agentId: string;
1659
- runId: string;
1660
- executionId: string;
1661
- /** Original durable Run input, before any Phase-local interpretation. */
1662
- input?: UserContent;
1663
- /** Opaque metadata captured at the durable boundary; Rowan does not decode it. */
1664
- agentMetadata?: Readonly<Record<string, unknown>>;
1665
- runMetadata?: Readonly<Record<string, unknown>>;
1666
- scope?: _rowan_agent_models.ScopeRef;
1667
- cwd?: string;
1668
- }>;
1669
- /** Everything a phase needs to execute */
1670
- interface PhaseContext {
1671
- systemPrompt: string;
1672
- messages: AgentMessage[];
1673
- /** Phase-filtered tools */
1674
- tools: Tool[];
1675
- /** Phase-filtered skills */
1676
- skills: Skill[];
1677
- /** Phase machine state */
1678
- state: PhaseState;
1679
- /** Identity and dispatch metadata for this phase execution */
1680
- readonly invocation: PhaseInvocation;
1681
- /** Durable Run identity for cross-store integrations and idempotent commands. */
1682
- readonly execution: PhaseExecutionIdentity;
1683
- /** Additional guideline bullets appended to the system prompt */
1684
- promptGuidelines?: string[];
1685
- /** Text to append after the system prompt */
1686
- appendSystemPrompt?: string;
1687
- }
1688
- /** JSON-safe structural defaults declared by a Phase's `input` mapping. */
1689
- type PhaseInput = Readonly<Record<string, JsonValue>>;
1690
- /** JSON-safe option metadata exposed to a host Settings surface. */
1691
- interface SettingsOption {
1692
- value: string;
1693
- label: string;
1694
- description?: string;
1695
- disabled?: boolean;
1696
- }
1697
- interface SettingsBadge {
1698
- label: string;
1699
- tone?: "neutral" | "success" | "review" | "danger";
1700
- }
1701
- interface SettingsItem {
1702
- id: string;
1703
- title: string;
1704
- description?: string;
1705
- badges?: readonly SettingsBadge[];
1706
- }
1707
- type SettingsControl = {
1708
- type: "boolean";
1709
- path: string;
1710
- label: string;
1711
- description?: string;
1712
- } | {
1713
- type: "number";
1714
- path: string;
1715
- label: string;
1716
- description?: string;
1717
- min?: number;
1718
- max?: number;
1719
- step?: number;
1720
- unit?: string;
1721
- scale?: number;
1722
- } | {
1723
- type: "select";
1724
- path: string;
1725
- label: string;
1726
- description?: string;
1727
- options: readonly SettingsOption[];
1728
- } | {
1729
- type: "text";
1730
- path: string;
1731
- label: string;
1732
- description?: string;
1733
- placeholder?: string;
1734
- format?: "string" | "string-array" | "key-value";
1735
- multiline?: boolean;
1736
- } | {
1737
- type: "collection";
1738
- path: string;
1739
- label: string;
1740
- description?: string;
1741
- items: readonly SettingsItem[];
1742
- fields: readonly SettingsControl[];
1743
- add?: {
1744
- label: string;
1745
- idLabel?: string;
1746
- fields: readonly SettingsControl[];
1747
- };
1748
- removeLabel?: string;
1749
- };
1750
- interface SettingsSection {
1751
- id: string;
1752
- title: string;
1753
- description?: string;
1754
- controls: readonly SettingsControl[];
1755
- }
1756
- /** Declarative, host-neutral Settings surface. */
1757
- interface SettingsDefinition {
1758
- description?: string;
1759
- sections: readonly SettingsSection[];
1760
- }
1761
- /**
1762
- * Loaded Phase object
1763
- */
1764
- interface Phase {
1765
- /** Unique phase identity and display name. */
1766
- name: string;
1767
- /** Rowan-owned built-in Phase; built-ins are never filtered or disabled. */
1768
- core?: boolean;
1769
- /** Description */
1770
- description: string;
1771
- /** Restricted tools (undefined = all tools available) */
1772
- tools?: string[];
1773
- /** Skills bundled directly inside this phase directory. Inline phases may omit this (equivalent to []). */
1774
- skills?: Skill[];
1775
- /** Forced next phase */
1776
- target?: string;
1777
- /** Additional system-prompt guidance while this Phase is in the auto route catalog. */
1778
- promptGuidelines?: string[];
1779
- /** Structural JSON-safe input defaults */
1780
- input?: PhaseInput;
1781
- /** If true, phase gets a fresh context when executed in parallel */
1782
- isolated?: boolean;
1783
- /** Path to PHASE.md file */
1784
- filePath: string;
1785
- /** Phase directory path */
1786
- baseDir: string;
1787
- /** PHASE.md body content */
1788
- content: string;
1789
- /** Model override for this phase (resolved from frontmatter) */
1790
- model?: ModelRef;
1791
- /** Do not automatically inject this Phase into the model route catalog/context. */
1792
- disableAutoInvocation?: boolean;
1793
- /** Do not expose this Phase to direct user invocation. */
1794
- disableImplicitInvocation?: boolean;
1795
- /** ExtensionAPI factory function used for registration or programmatic execution. */
1796
- factory?: (api: ExtensionAPI) => Promise<void>;
1797
- /** Direct run function */
1798
- run?: (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
1799
- }
1800
- /**
1801
- * Phase registry containing all loaded phases
1802
- */
1803
- interface PhaseRegistry {
1804
- /** Map of phase name to Phase object */
1805
- phases: Map<string, Phase>;
1806
- /** Entry phase name (null until Agent applies its default phase) */
1807
- entryPhaseId: string | null;
1808
- }
1809
-
1810
- interface BeforePhaseEvent {
1811
- type: "before_phase";
1812
- phaseId: string;
1813
- input: PhaseContext;
1814
- }
1815
- interface AfterPhaseEvent {
1816
- type: "after_phase";
1817
- phaseId: string;
1818
- output: PhaseOutput;
1819
- }
1820
- interface BeforePromptEvent {
1821
- type: "before_prompt";
1822
- phaseId: string;
1823
- input: PhaseContext;
1824
- }
1825
- interface BeforeToolCallEvent {
1826
- type: "before_tool_call";
1827
- tool: Tool;
1828
- args: unknown;
1829
- readonly runId?: string;
1830
- readonly agentId?: string;
1831
- readonly toolCallId?: string;
1832
- readonly metadata?: Readonly<Record<string, unknown>>;
1833
- /** The invoking Agent's metadata, as the Tool's own call context carries it. */
1834
- readonly agentMetadata?: Readonly<Record<string, unknown>>;
1835
- readonly answer?: unknown;
1836
- readonly scope?: ScopeRef;
1837
- readonly turn?: JsonObject;
1838
- }
1839
- interface AfterToolCallEvent {
1840
- type: "after_tool_call";
1841
- tool: Tool;
1842
- result: ToolResult;
1843
- readonly runId?: string;
1844
- readonly agentId?: string;
1845
- readonly toolCallId?: string;
1846
- readonly metadata?: Readonly<Record<string, unknown>>;
1847
- readonly scope?: ScopeRef;
1848
- readonly turn?: JsonObject;
1849
- }
1850
- interface RunStartEvent {
1851
- type: "run_start";
1852
- runId: string;
1853
- agentId: string;
1854
- metadata: Readonly<Record<string, unknown>>;
1855
- turn: JsonObject;
1856
- }
1857
- interface RunEndEvent {
1858
- type: "run_end";
1859
- runId: string;
1860
- agentId: string;
1861
- outcome: unknown;
1862
- }
1863
- type HookEvent = BeforePhaseEvent | AfterPhaseEvent | BeforePromptEvent | BeforeToolCallEvent | AfterToolCallEvent | RunStartEvent | RunEndEvent;
1864
- interface BeforePhaseResult {
1865
- abort?: Outcome;
1866
- skip?: {
1867
- route: string;
1868
- message: string;
1869
- };
1870
- input?: PhaseContext;
1871
- }
1872
- interface AfterPhaseResult {
1873
- abort?: Outcome;
1874
- retry?: PhaseContext;
1875
- output?: PhaseOutput;
1876
- }
1877
- interface BeforePromptResult {
1878
- input?: PhaseContext;
1879
- }
1880
- interface BeforeToolCallResult {
1881
- allow?: boolean;
1882
- reason?: string;
1883
- interaction?: RunInteractionRequest;
1884
- }
1885
- interface AfterToolCallResult {
1886
- result?: ToolResult;
1887
- }
1888
- interface HookResultMap {
1889
- before_phase: BeforePhaseResult | undefined;
1890
- after_phase: AfterPhaseResult | undefined;
1891
- before_prompt: BeforePromptResult | undefined;
1892
- before_tool_call: BeforeToolCallResult | undefined;
1893
- after_tool_call: AfterToolCallResult | undefined;
1894
- run_start: void;
1895
- run_end: void;
1896
- }
1897
- type HookEventType = HookEvent["type"];
1898
- type HookHandler<K extends HookEventType> = (event: Extract<HookEvent, {
1899
- type: K;
1900
- }>) => HookResultMap[K] | Promise<HookResultMap[K]> | void | Promise<void>;
1901
- declare class HooksManager {
1902
- private handlers;
1903
- on<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
1904
- off<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
1905
- emit<K extends HookEventType>(eventType: K, event: Extract<HookEvent, {
1906
- type: K;
1907
- }>): Promise<void>;
1908
- emitFirst<K extends HookEventType>(eventType: K, event: Extract<HookEvent, {
1909
- type: K;
1910
- }>): Promise<HookResultMap[K] | undefined>;
1911
- }
1912
-
1913
- type ToolContext = Pick<AgentContext, "skills"> & {
1914
- toolCallId: string;
1915
- interaction?: RunInteractionDriver;
1916
- };
1917
- type ToolExecutionMode = "sequential" | "parallel";
1918
- type Tool<TArgs = unknown> = {
1919
- name: string;
1920
- /** Rowan-owned Core Tool; Core Tools bypass Phase filtering. */
1921
- core?: boolean;
1922
- description: string;
1923
- parameters: Type.TSchema;
1924
- /** One-line snippet shown in the system prompt tool list. */
1925
- promptSnippet?: string;
1926
- /** Additional guidelines appended to the system prompt when this tool is active. */
1927
- promptGuidelines?: string[];
1928
- /** Whether this tool can run concurrently with others. Default: "parallel". */
1929
- executionMode?: ToolExecutionMode;
1930
- _meta?: JsonObject$1;
1931
- execute(args: TArgs, context: ToolContext, signal?: AbortSignal): Promise<ToolResult>;
1932
- };
1933
- /** Context snapshot passed into the low-level agent loop. */
1934
- type AgentContext = {
1935
- /** System prompt included with the request. */
1936
- systemPrompt: string;
1937
- /** Transcript visible to the model. */
1938
- messages: AgentMessage[];
1939
- /** Tools available for this run. */
1940
- tools: Tool[];
1941
- /** Skills available for this run. */
1942
- skills: Skill[];
1943
- /** Custom phases for this run. Agent normalizes this with the built-in default phase. */
1944
- phases?: PhaseRegistry;
1945
- cwd?: string;
1946
- };
1947
-
1948
- type LoopMetrics = {
1949
- /** Number of phase iterations executed. */
1950
- iterations: number;
1951
- /** Phase transition history. */
1952
- phaseTransitions: Array<{
1953
- from: string;
1954
- to: string;
1955
- ts: string;
1956
- }>;
1957
- /** Number of times compaction was triggered. */
1958
- compactionCount: number;
1959
- /** Number of retry attempts due to transient errors. */
1960
- retryCount: number;
1961
- /** Loop start timestamp. */
1962
- startedAt: string;
1963
- /** Loop start time as epoch ms (for duration calculation). */
1964
- startedAtMs: number;
1965
- /** Loop end timestamp (set on completion). */
1966
- endedAt?: string;
1967
- /** Total wall-clock duration in ms. */
1968
- durationMs?: number;
1969
- };
1970
- type ExecutionState = {
1971
- currentPhase: string;
1972
- attempt: number;
1973
- metrics: LoopMetrics;
1974
- status: "idle" | "running" | "suspended" | "completed" | "aborted" | "failed";
1975
- initialPhasePayload?: JsonValue;
1976
- entryPhases?: readonly EntryPhaseSpec[];
1977
- continuation?: ExecutionContinuationState;
1978
- runInteractions?: RunInteractionState;
1979
- phaseInteractions?: RunInteractionState;
1980
- };
1981
- type ExecutionContinuationState = {
1982
- isContinuing: boolean;
1983
- previousPayload?: unknown;
1984
- previousResults: Array<{
1985
- name: string;
1986
- output?: unknown;
1987
- }>;
1988
- pendingInstruction?: string;
1989
- previousPhaseMessageId?: string;
1990
- };
1991
-
1992
- type RunInteractionKind = "user_input" | "permission" | "elicitation" | "confirmation";
1993
- type RunInteractionStatus = "pending" | "answered" | "replied" | "cancelled";
1994
- type RunInteraction = Readonly<{
1995
- id: string;
1996
- phase: string;
1997
- kind: RunInteractionKind;
1998
- prompt: string;
1999
- payload?: JsonValue;
2000
- createdAt: string;
2001
- status: RunInteractionStatus;
2002
- answer?: JsonValue;
2003
- reply?: string;
2004
- /** The Run is only waiting for the next user message, not asking a question. */
2005
- turnBoundary?: true;
2006
- toolCallId?: string;
2007
- result?: Readonly<{
2008
- answered?: string;
2009
- replied?: string;
2010
- cancelled?: string;
2011
- }>;
2012
- }>;
2013
- type RunInteractionRequest = Readonly<{
2014
- id?: string;
2015
- kind: RunInteractionKind;
2016
- prompt: string;
2017
- payload?: JsonValue;
2018
- toolCallId?: string;
2019
- result?: Readonly<{
2020
- answered?: string;
2021
- replied?: string;
2022
- cancelled?: string;
2023
- }>;
2024
- }>;
2025
- type RunInteractionState = Readonly<{
2026
- requests: readonly RunInteraction[];
2027
- answers: Readonly<Record<string, JsonValue>>;
2028
- checkpoint?: JsonValue;
2029
- }>;
2030
- type RunInteractionDriver = Readonly<{
2031
- signal: AbortSignal;
2032
- request(input: RunInteractionRequest): RunInteraction;
2033
- pending(): readonly RunInteraction[];
2034
- answers(): ReadonlyMap<string, JsonValue>;
2035
- checkpoint(): JsonValue | undefined;
2036
- clearCheckpoint(): void;
2037
- answer?(id: string, value: JsonValue): void;
2038
- clearAnswer?(id: string): void;
2039
- suspend(input?: Readonly<{
2040
- checkpoint?: JsonValue;
2041
- }>): never;
2042
- }>;
2043
- declare class RunInteractionCancelledError extends Error {
2044
- readonly code: "run_interaction_cancelled";
2045
- constructor(message?: string);
2046
- }
2047
- declare class RunInteractionBoundary extends Error {
2048
- readonly state: ExecutionState;
2049
- readonly interactions: readonly RunInteraction[];
2050
- constructor(state: ExecutionState, interactions: readonly RunInteraction[]);
2051
- }
2052
-
2053
- declare const opaqueIdBrand: unique symbol;
2054
- type OpaqueId<Kind extends string> = string & {
2055
- readonly [opaqueIdBrand]: Kind;
2056
- };
2057
- type AgentId = OpaqueId<"AgentId">;
2058
- type RunId = OpaqueId<"RunId">;
2059
- type MessageId = OpaqueId<"MessageId">;
2060
- type ToolCallId = OpaqueId<"ToolCallId">;
2061
- type EventId = OpaqueId<"EventId">;
2062
- type ExecutionId = OpaqueId<"ExecutionId">;
2063
- type OutcomeId = OpaqueId<"OutcomeId">;
2064
- type ConfigToken = OpaqueId<"ConfigToken">;
2065
- type OwnerToken = OpaqueId<"OwnerToken">;
2066
- type EventCursor = OpaqueId<"EventCursor">;
2067
- type AgentListCursor = OpaqueId<"AgentListCursor">;
2068
- type RunListCursor = OpaqueId<"RunListCursor">;
2069
- type JsonPrimitive = null | boolean | number | string;
2070
- type JsonValue = JsonPrimitive | readonly JsonValue[] | {
2071
- readonly [key: string]: JsonValue;
2072
- };
2073
- type JsonObject = Readonly<Record<string, JsonValue>>;
2074
- type Metadata = JsonObject;
2075
- type TextContent = Readonly<{
2076
- type: "text";
2077
- text: string;
2078
- }>;
2079
- type ImageContent = Readonly<{
2080
- type: "image";
2081
- data: string;
2082
- mimeType: string;
2083
- }>;
2084
- type ThinkingContent = Readonly<{
2085
- type: "thinking";
2086
- thinking: string;
2087
- signature?: string;
2088
- }>;
2089
- type ToolUseContent = Readonly<{
2090
- type: "tool_use";
2091
- toolCallId: ToolCallId;
2092
- /** Provider/model correlation, retained only to reconstruct the next request. */
2093
- providerToolCallId?: string;
2094
- name: string;
2095
- input: JsonValue;
2096
- }>;
2097
- type ToolExecutionResult = Readonly<{
2098
- ok: true;
2099
- content: JsonValue;
2100
- structuredContent?: JsonValue;
2101
- isError?: boolean;
2102
- }> | Readonly<{
2103
- ok: false;
2104
- content: JsonValue;
2105
- error: string;
2106
- structuredContent?: JsonValue;
2107
- isError?: boolean;
2108
- }> | Readonly<{
2109
- content: readonly ContentBlock[];
2110
- structuredContent?: JsonValue;
2111
- isError?: boolean;
2112
- ok?: boolean;
2113
- error?: string;
2114
- }>;
2115
- type DurableToolResult = Readonly<{
2116
- toolCallId: ToolCallId;
2117
- toolName: string;
2118
- }> & ToolExecutionResult;
2119
- type ToolResultContent = Readonly<{
2120
- type: "tool_result";
2121
- toolCallId: ToolCallId;
2122
- /** Provider/model correlation, retained only to reconstruct the next request. */
2123
- providerToolCallId?: string;
2124
- result: ToolExecutionResult;
2125
- }>;
2126
- type UserContent = string | readonly (TextContent | ImageContent)[];
2127
- type AssistantContent = string | readonly (TextContent | ThinkingContent | ToolUseContent)[];
2128
- type ToolMessageContent = readonly [ToolResultContent, ...ToolResultContent[]];
2129
- type MessageContent = UserContent | AssistantContent | ToolMessageContent;
2130
- type MessageBase = Readonly<{
2131
- id: MessageId;
2132
- agentId: AgentId;
2133
- runId: RunId;
2134
- /** Monotonic active revision. Omitted on legacy/initial messages and read as 0. */
2135
- messageRevision?: number;
2136
- metadata?: Metadata;
2137
- sequenceWithinRun: number;
2138
- createdAt: string;
2139
- }>;
2140
- type ContextCandidate = Readonly<{
2141
- name: string;
2142
- value: JsonValue;
2143
- }>;
2144
- type UserMessage = MessageBase & Readonly<{
2145
- role: "user";
2146
- content: UserContent;
2147
- contexts?: readonly ContextCandidate[];
2148
- }>;
2149
- type AssistantMessage = MessageBase & Readonly<{
2150
- role: "assistant";
2151
- content: AssistantContent;
2152
- interrupted?: boolean;
2153
- model?: ModelRef;
2154
- usage?: LlmTokenUsage;
2155
- }>;
2156
- type ToolMessage = MessageBase & Readonly<{
2157
- role: "tool";
2158
- content: ToolMessageContent;
2159
- }>;
2160
- type InteractionRecord = MessageBase & Readonly<{
2161
- role: "interaction";
2162
- interactionId: string;
2163
- kind: "user_input" | "permission" | "elicitation" | "confirmation";
2164
- prompt: string;
2165
- phase: string;
2166
- status: "answered" | "replied" | "cancelled";
2167
- answer?: JsonValue;
2168
- reply?: string;
2169
- toolCallId?: ToolCallId;
2170
- result?: Readonly<{
2171
- answered?: string;
2172
- replied?: string;
2173
- cancelled?: string;
2174
- }>;
2175
- }>;
2176
- type Message = UserMessage | AssistantMessage | ToolMessage | InteractionRecord;
2177
- type Outcome$1 = Readonly<{
2178
- id: OutcomeId;
2179
- message: string;
2180
- payload?: JsonValue;
2181
- toolResults?: readonly DurableToolResult[];
2182
- }>;
2183
- type RunState = "queued" | "running" | "input_required" | "completed" | "failed" | "cancelled";
2184
- type WithdrawnUserInput = Readonly<{
2185
- messageId: MessageId;
2186
- content: UserContent;
2187
- }>;
2188
- type RunFailure = Readonly<{
2189
- code: "configuration_unavailable";
2190
- message: string;
2191
- withdrawnInput?: WithdrawnUserInput;
2192
- }> | Readonly<{
2193
- code: "checkpoint_incompatible";
2194
- message: string;
2195
- expected: Readonly<{
2196
- codec: string;
2197
- versions: readonly number[];
2198
- }>;
2199
- actual: Readonly<{
2200
- codec: string;
2201
- version: number;
2202
- }>;
2203
- withdrawnInput?: WithdrawnUserInput;
2204
- }> | Readonly<{
2205
- code: "runtime_interrupted";
2206
- message: string;
2207
- ownerEpoch: number;
2208
- withdrawnInput?: WithdrawnUserInput;
2209
- }> | Readonly<{
2210
- code: "tool_indeterminate";
2211
- message: string;
2212
- toolCallIds: readonly [ToolCallId, ...ToolCallId[]];
2213
- withdrawnInput?: WithdrawnUserInput;
2214
- }> | Readonly<{
2215
- code: "execution_failed";
2216
- message: string;
2217
- details?: JsonValue;
2218
- withdrawnInput?: WithdrawnUserInput;
2219
- }>;
2220
- type QueuedRunFailure = Extract<RunFailure, {
2221
- code: "configuration_unavailable" | "checkpoint_incompatible";
2222
- }>;
2223
- type RunningRunFailure = Extract<RunFailure, {
2224
- code: "runtime_interrupted" | "tool_indeterminate" | "execution_failed";
2225
- }>;
2226
- type ToolCallState = ToolCallStatus;
2227
- type ToolCallSnapshot = ToolCall$1 & Readonly<{
2228
- id: ToolCallId;
2229
- providerToolCallId?: string;
2230
- agentId?: AgentId;
2231
- runId?: RunId;
2232
- executionId?: ExecutionId;
2233
- requestMessageId?: MessageId;
2234
- name?: string;
2235
- args?: JsonValue;
2236
- state?: ToolCallStatus;
2237
- result?: DurableToolResult;
2238
- resultMessageId?: MessageId;
2239
- reason?: string;
2240
- external?: boolean;
2241
- contentIndex?: number;
2242
- createdAt?: string;
2243
- updatedAt?: string;
2244
- }>;
2245
- type DurableEventBase = Readonly<{
2246
- id: EventId;
2247
- schemaVersion: 1;
2248
- cursor: EventCursor;
2249
- durability: "durable";
2250
- agentId: AgentId;
2251
- runId: RunId;
2252
- runRevision: number;
2253
- metadata?: Metadata;
2254
- createdAt: string;
2255
- }>;
2256
- type PhaseEntered = DurableEventBase & Readonly<{
2257
- kind: "phase_entered";
2258
- executionId: ExecutionId;
2259
- phaseId: string;
2260
- visit: number;
2261
- }>;
2262
- type MessageCommitted = DurableEventBase & Readonly<{
2263
- kind: "message_committed";
2264
- message: Message;
2265
- }>;
2266
- type MessageRevised = DurableEventBase & Readonly<{
2267
- kind: "message_revised";
2268
- message: UserMessage;
2269
- previousRevision: number;
2270
- invalidatedRunIds: readonly RunId[];
2271
- targetRunId: RunId;
2272
- cutoffSequenceWithinRun: number;
2273
- }>;
2274
- type RunStateChanged = DurableEventBase & (Readonly<{
2275
- kind: "run_state_changed";
2276
- from: null;
2277
- to: "queued";
2278
- }> | Readonly<{
2279
- kind: "run_state_changed";
2280
- from: "input_required";
2281
- to: "queued";
2282
- }> | Readonly<{
2283
- kind: "run_state_changed";
2284
- from: "queued";
2285
- to: "running";
2286
- }> | Readonly<{
2287
- kind: "run_state_changed";
2288
- from: "running";
2289
- to: "input_required";
2290
- interactions: readonly RunInteraction[];
2291
- answers: Readonly<Record<string, JsonValue>>;
2292
- }> | Readonly<{
2293
- kind: "run_state_changed";
2294
- from: "running";
2295
- to: "completed";
2296
- outcome: Outcome$1;
2297
- output?: AssistantMessage;
2298
- }> | Readonly<{
2299
- kind: "run_state_changed";
2300
- from: "queued";
2301
- to: "failed";
2302
- failure: QueuedRunFailure;
2303
- withdrawnInput?: WithdrawnUserInput;
2304
- }> | Readonly<{
2305
- kind: "run_state_changed";
2306
- from: "running";
2307
- to: "failed";
2308
- failure: RunningRunFailure;
2309
- withdrawnInput?: WithdrawnUserInput;
2310
- }> | Readonly<{
2311
- kind: "run_state_changed";
2312
- from: "queued" | "running" | "input_required";
2313
- to: "cancelled";
2314
- reason?: string;
2315
- }>);
2316
- type ToolStateChanged = (DurableEventBase & Readonly<{
2317
- kind: "tool_state_changed";
2318
- transition: Readonly<{
2319
- from: ToolCallStatus | null;
2320
- to: ToolCallStatus;
2321
- }>;
2322
- toolCall: ToolCall$1;
2323
- external?: boolean;
2324
- /** For a provider-reported call: assistant content blocks streamed before it. */
2325
- contentIndex?: number;
2326
- }>) | Readonly<{
2327
- kind: "tool_state_changed";
2328
- durability: "transient";
2329
- runId: RunId;
2330
- executionId?: ExecutionId;
2331
- transition: Readonly<{
2332
- from: ToolCallStatus | null;
2333
- to: ToolCallStatus;
2334
- }>;
2335
- toolCall: ToolCall$1 | ToolCallUpdate;
2336
- external?: boolean;
2337
- contentIndex?: number;
2338
- }>;
2339
- type DurableRunEvent = PhaseEntered | MessageCommitted | MessageRevised | RunStateChanged | Extract<ToolStateChanged, {
2340
- durability: "durable";
2341
- }>;
2342
- type MessageDelta = Readonly<{
2343
- kind: "message_delta";
2344
- durability: "transient";
2345
- runId: RunId;
2346
- executionId: ExecutionId;
2347
- messageId: MessageId;
2348
- offset: number;
2349
- text: string;
2350
- }>;
2351
- type ThinkingDelta = Readonly<{
2352
- kind: "thinking_delta";
2353
- durability: "transient";
2354
- runId: RunId;
2355
- executionId: ExecutionId;
2356
- messageId: MessageId;
2357
- blockIndex: number;
2358
- offset: number;
2359
- text: string;
2360
- }>;
2361
- type ToolCallDelta = Readonly<{
2362
- kind: "tool_call_delta";
2363
- durability: "transient";
2364
- runId: RunId;
2365
- executionId: ExecutionId;
2366
- messageId: MessageId;
2367
- providerToolCallId: string;
2368
- toolName: string;
2369
- arguments: string;
2370
- args: JsonValue | undefined;
2371
- }>;
2372
- type PhaseStatusEvent = Readonly<{
2373
- kind: "phase_status";
2374
- durability: "transient";
2375
- runId: RunId;
2376
- executionId: ExecutionId;
2377
- phaseId: string;
2378
- status: PhaseStatus;
2379
- }>;
2380
- type ModelRetry = Readonly<{
2381
- kind: "model_retry";
2382
- durability: "transient";
2383
- runId: RunId;
2384
- executionId: ExecutionId;
2385
- attempt: number;
2386
- maxRetries: number;
2387
- delayMs: number;
2388
- error: string;
2389
- }>;
2390
- type LiveInteractionEvent = Readonly<{
2391
- kind: "live_interaction";
2392
- durability: "transient";
2393
- runId: RunId;
2394
- executionId?: ExecutionId;
2395
- interaction: RunInteraction;
2396
- }>;
2397
- type RunEvent = DurableRunEvent | MessageDelta | ThinkingDelta | ToolCallDelta | PhaseStatusEvent | ModelRetry | LiveInteractionEvent | Extract<ToolStateChanged, {
2398
- durability: "transient";
2399
- }>;
2400
-
2401
- type AgentMessage = {
2402
- id: string;
2403
- role: "system" | "user" | "assistant" | "tool";
2404
- content: string | LlmContentPart[];
2405
- createdAt: string;
2406
- metadata?: Record<string, unknown> & {
2407
- phase?: string;
2408
- };
2409
- contexts?: readonly ContextCandidate[];
2410
- model?: ModelRef;
2411
- usage?: LlmTokenUsage;
2412
- };
2413
- type Skill = {
2414
- name: string;
2415
- description: string;
2416
- /** Absolute path to the SKILL.md file */
2417
- filePath: string;
2418
- /** Directory containing the SKILL.md file */
2419
- baseDir: string;
2420
- /** Full body content of the SKILL.md (after frontmatter) */
2421
- content: string;
2422
- /** Do not automatically inject this Skill into the model Context. */
2423
- disableAutoInvocation?: boolean;
2424
- /** Do not expose this Skill to direct user invocation. */
2425
- disableImplicitInvocation?: boolean;
2426
- /** @deprecated Use disableAutoInvocation; kept only for old in-memory callers during cutover. */
2427
- disableModelInvocation?: boolean;
2428
- };
2429
- type Outcome = {
2430
- id: string;
2431
- message: string;
2432
- /** Publish this outcome's message as an assistant message before completing the run. */
2433
- display?: boolean;
2434
- payload?: unknown;
2435
- toolResults?: Array<{
2436
- toolCallId: string;
2437
- toolName: string;
2438
- ok: boolean;
2439
- content: unknown;
2440
- error?: string;
2441
- }>;
2442
- };
2443
- type ToolCall = {
2444
- id: string;
2445
- name: string;
2446
- args: unknown;
2447
- };
2448
- type ToolResult = {
2449
- toolCallId: string;
2450
- toolName: string;
2451
- ok: boolean;
2452
- content: unknown;
2453
- error?: string;
2454
- structuredContent?: unknown;
2455
- isError?: boolean;
2456
- };
2457
-
2458
- /**
2459
- * `root` anchors relative paths and the Bash working directory. It is not a
2460
- * filesystem sandbox: core Tools use the permissions of the host process.
2461
- */
2462
- type CoreToolContext = {
2463
- root?: string;
2464
- /** Directory for complete Tool Result spill files. */
2465
- archiveDir?: string;
2466
- maxReadBytes?: number;
2467
- maxReadLines?: number;
2468
- bashTimeoutMs?: number;
2469
- maxBashOutputBytes?: number;
2470
- };
2471
-
2472
- declare class AgentRuntime implements AgentRuntime$1 {
2473
- private readonly concurrency;
2474
- private readonly owned;
2475
- private readonly commands;
2476
- private readonly storeIncarnation;
2477
- private readonly activeAgents;
2478
- private readonly executions;
2479
- private readonly executionDone;
2480
- private readonly cancellationRequested;
2481
- private readonly cancellationReasons;
2482
- private readonly autoCompactionRuns;
2483
- private readonly consumers;
2484
- private readonly transientEvents;
2485
- readonly host: ExtensionHost;
2486
- private readonly resources;
2487
- private readonly startedRuns;
2488
- private readonly liveInteractions;
2489
- private heartbeat?;
2490
- private pumping;
2491
- private closed;
2492
- private readonly retryDelayMs?;
2493
- private constructor();
2494
- static init(options: AgentRuntimeOptions): Promise<AgentRuntime>;
2495
- private publishLiveInteraction;
2496
- private cancelLiveInteractions;
2497
- private handleRunEnd;
2498
- loadAgents(input: LoadInput<AgentDefinition>): Promise<LoadResult>;
2499
- loadSkills(input: LoadInput<Skill>): Promise<LoadResult>;
2500
- loadPhases(input: LoadInput<Phase>): Promise<LoadResult>;
2501
- loadTools(input: Readonly<{
2502
- sourceId: string;
2503
- values: readonly Tool$1[];
2504
- }>): Promise<LoadResult>;
2505
- unload(input: Readonly<{
2506
- kind: ResourceKind;
2507
- sourceId: string;
2508
- }>): Promise<LoadResult>;
2509
- createAgent(config: AgentConfiguration, options?: {
2510
- idempotencyKey?: string;
2511
- metadata?: Metadata;
2512
- historySeed?: HistorySeed;
2513
- }): Promise<AgentId>;
2514
- updateAgentConfig(agentId: AgentId, config: AgentConfiguration, options: {
2515
- idempotencyKey: string;
2516
- }): Promise<void>;
2517
- deleteAgent(input: AgentDeletionRequest): Promise<void>;
2518
- revise(agentId: AgentId, input: {
2519
- messageId: MessageId;
2520
- expectedMessageRevision: number;
2521
- content: UserContent;
2522
- operationId: string;
2523
- effectDigestConfirmation?: string;
2524
- }): Promise<MessageRevisionResult>;
2525
- compact(input?: {
2526
- now?: string;
2527
- retentionMs?: number;
2528
- }): Promise<Readonly<{
2529
- deletedRunIds: readonly RunId[];
2530
- deletedToolCallIds: readonly ToolCallId[];
2531
- deletedEventCount: number;
2532
- retentionFloor: EventCursor;
2533
- skipped?: "active_consumers" | "no_eligible_events";
2534
- }>>;
2535
- contextStatus(agentId: AgentId, options?: {
2536
- contextWindow?: number;
2537
- }): Promise<ContextStatus>;
2538
- runPhase(agentId: AgentId, options: {
2539
- phase: string;
2540
- payload?: JsonValue;
2541
- input?: UserInput;
2542
- yieldToInput?: boolean;
2543
- idempotencyKey?: string;
2544
- }): Promise<AgentRun>;
2545
- compactContext(agentId: AgentId, options?: {
2546
- input?: UserInput;
2547
- instructions?: string;
2548
- idempotencyKey?: string;
2549
- }): Promise<AgentRun>;
2550
- start(agentId: AgentId, input: UserInput, options: {
2551
- idempotencyKey: string;
2552
- metadata?: Metadata;
2553
- scope?: ScopeRef;
2554
- cwd?: string;
2555
- phasePayload?: JsonValue;
2556
- entryPhases?: ReadonlyArray<EntryPhaseSpec>;
2557
- }): Promise<AgentRun>;
2558
- run(runId: RunId): AgentRun;
2559
- listAgents(input?: {
2560
- after?: AgentListCursor;
2561
- limit?: number;
2562
- }): Promise<Page<AgentSummary, AgentListCursor>>;
2563
- listRuns(input?: {
2564
- agentId?: AgentId;
2565
- states?: readonly RunState[];
2566
- after?: RunListCursor;
2567
- limit?: number;
2568
- }): Promise<Page<RunSummary, RunListCursor>>;
2569
- listInvocations(agentId: AgentId, options: {
2570
- source: InvocationSource;
2571
- }): Promise<readonly InvocationCatalogEntry[]>;
2572
- consume(input: {
2573
- consumerId: string;
2574
- signal: AbortSignal;
2575
- onEvent(event: DurableRunEvent, context: Readonly<{
2576
- signal: AbortSignal;
2577
- }>): void | Promise<void>;
2578
- }): Promise<DurableConsumer>;
2579
- listCapabilities(): readonly ExtensionCapability[];
2580
- onCapabilitiesChanged(listener: (capabilities: readonly ExtensionCapability[]) => void): () => void;
2581
- triggerUiAction(event: {
2582
- contributionId: string;
2583
- actionId: string;
2584
- scope?: ScopeRef;
2585
- }): void;
2586
- private liveInteract;
2587
- close(): Promise<void>;
2588
- snapshot(runId: RunId): Promise<RunSnapshot>;
2589
- history(agentId: AgentId): Promise<readonly Message[]>;
2590
- respondInteraction(runId: RunId, input: {
2591
- interactionId: string;
2592
- input?: JsonValue;
2593
- cancel?: boolean;
2594
- }): Promise<void>;
2595
- cancel(runId: RunId, reason?: string): Promise<RunBoundary>;
2596
- private pump;
2597
- private execute;
2598
- private failQueued;
2599
- private resolveContextWindow;
2600
- private executeTool;
2601
- private executeToolBatch;
2602
- private executeAndCommitTool;
2603
- private foldToolInteractionRecords;
2604
- private requireAgent;
2605
- private archiveDirFor;
2606
- private runConsumer;
2607
- observe(runId: RunId, options?: {
2608
- after?: EventCursor;
2609
- signal?: AbortSignal;
2610
- }): AsyncIterable<RunEvent>;
2611
- wait(runId: RunId, options?: {
2612
- signal?: AbortSignal;
2613
- }): Promise<RunBoundary>;
2614
- private assertOpen;
2615
- /** Resolve one stored configuration to the snapshot this execution uses. A
2616
- * stored snapshot is already source-qualified and is used as it stands. */
2617
- private resolveConfig;
2618
- private startHeartbeat;
2619
- }
2620
-
2621
- type Mutable<T> = {
2622
- -readonly [Key in keyof T]: T[Key];
2623
- };
2624
- type StoredAgent = Mutable<AgentRecord>;
2625
- type StoredRun = Mutable<RunRecord>;
2626
- type StoredToolCall = {
2627
- id: ToolCallId;
2628
- providerToolCallId?: string;
2629
- agentId: AgentId;
2630
- runId: RunId;
2631
- executionId?: ExecutionId;
2632
- requestMessageId?: MessageId;
2633
- name?: string;
2634
- args?: JsonValue;
2635
- state?: ToolCallState;
2636
- toolCallId: string;
2637
- title: string;
2638
- kind: ToolKind;
2639
- status: ToolCallStatus;
2640
- content?: ToolCallContent[];
2641
- locations?: ToolCallLocation[];
2642
- rawInput?: JsonValue;
2643
- rawOutput?: JsonValue;
2644
- _meta?: JsonObject;
2645
- external?: boolean;
2646
- contentIndex?: number;
2647
- result?: DurableToolResult;
2648
- resultMessageId?: MessageId;
2649
- reason?: string;
2650
- createdAt: string;
2651
- updatedAt: string;
2652
- };
2653
- type IdempotencyReceipt = {
2654
- payload: string;
2655
- result: unknown;
2656
- };
2657
- type StoreMutationRecorder = {
2658
- onAgentUpsert(agent: StoredAgent): void;
2659
- onAgentDelete(agentId: AgentId): void;
2660
- onRunUpsert(run: StoredRun): void;
2661
- onRunDelete(runId: RunId): void;
2662
- onMessageInsert(message: Message): void;
2663
- onMessageDelete(messageId: MessageId): void;
2664
- onToolCallUpsert(toolCall: StoredToolCall): void;
2665
- onToolCallDelete(toolCallId: ToolCallId): void;
2666
- onEventAppend(event: DurableRunEvent): void;
2667
- onEventsTruncate(deletedEventIds: string[]): void;
2668
- onIdempotencyUpsert(scope: string, receipt: IdempotencyReceipt): void;
2669
- onIdempotencyDelete(scope: string): void;
2670
- onOperationReceiptUpsert(key: string, receipt: IdempotencyReceipt): void;
2671
- onOperationReceiptDelete(key: string): void;
2672
- onConsumerCheckpointUpsert(consumerId: string, cursor: EventCursor): void;
2673
- onConsumerCheckpointDelete(consumerId: string): void;
2674
- onContextCompactionUpsert(agentId: AgentId, record: ContextCompactionRecord): void;
2675
- onRetentionFloorChange(floor: number): void;
2676
- };
2677
- type InMemoryStoreState = Readonly<{
2678
- incarnation: string;
2679
- agents: readonly AgentRecord[];
2680
- runs: readonly RunRecord[];
2681
- messages: readonly Message[];
2682
- toolCalls: readonly ToolCallSnapshot[];
2683
- events: readonly DurableRunEvent[];
2684
- idempotency: readonly (readonly [string, IdempotencyReceipt])[];
2685
- operationReceipts: readonly (readonly [string, IdempotencyReceipt])[];
2686
- historySeeds?: readonly (readonly [AgentId, readonly Message[]])[];
2687
- consumerCheckpoints?: readonly (readonly [string, EventCursor])[];
2688
- retentionFloor?: number;
2689
- nextAgentSequence: readonly (readonly [AgentId, number])[];
2690
- nextReadySequence: readonly (readonly [AgentId, number])[];
2691
- eventSequence: number;
2692
- contextCompactions?: readonly (readonly [AgentId, ContextCompactionRecord])[];
2693
- }>;
2694
- declare class InMemoryStore implements DurableStore {
2695
- private readonly incarnation;
2696
- private readonly agents;
2697
- private readonly runs;
2698
- private readonly messages;
2699
- private readonly toolCalls;
2700
- private readonly events;
2701
- private readonly idempotency;
2702
- private readonly operationReceipts;
2703
- private readonly historySeeds;
2704
- private readonly consumerCheckpoints;
2705
- private readonly nextAgentSequence;
2706
- private readonly nextReadySequence;
2707
- private owner?;
2708
- private ownerEpoch;
2709
- private eventSequence;
2710
- private retentionFloor;
2711
- private readonly contextCompactions;
2712
- private recorder?;
2713
- private readonly runReceiptKeys;
2714
- constructor(options?: {
2715
- incarnation?: string;
2716
- });
2717
- setChangeRecorder(recorder?: StoreMutationRecorder): void;
2718
- private touchAgent;
2719
- private touchRun;
2720
- private storeMessage;
2721
- private storeToolCall;
2722
- private appendEvent;
2723
- inferRunIdForReceipt(key: string, payload: string): RunId | undefined;
2724
- dropRunOperationReceipts(runId: RunId): void;
2725
- compactTerminalReceipts(): number;
2726
- static fromState(state: InMemoryStoreState): InMemoryStore;
2727
- exportState(): InMemoryStoreState;
2728
- exportMetadata(): Record<string, unknown>;
2729
- attachOwner(lease: OwnerLease): void;
2730
- interruptOwner(ownerEpoch: number, message?: string): void;
2731
- openOwner(input: {
2732
- ownerId: string;
2733
- leaseMs: number;
2734
- }): Promise<OwnedStore>;
2735
- assertOwner(lease: OwnerLease, requireLive?: boolean): void;
2736
- renewOwner(lease: OwnerLease, leaseMs: number): OwnerLease;
2737
- releaseOwner(lease: OwnerLease): void;
2738
- reserveAgent(lease: OwnerLease, input: {
2739
- idempotencyKey: string;
2740
- metadata?: Metadata;
2741
- configIdentity?: string;
2742
- historySeed?: HistorySeed;
2743
- }): AgentRecord;
2744
- activateAgent(lease: OwnerLease, agentId: AgentId, configToken?: ConfigToken, configIdentity?: string): AgentRecord;
2745
- updateAgentConfigToken(lease: OwnerLease, input: {
2746
- agentId: AgentId;
2747
- token: ConfigToken;
2748
- configIdentity?: string;
2749
- idempotencyKey: string;
2750
- }): AgentRecord;
2751
- deleteAgent(lease: OwnerLease, input: AgentDeletionRequest): void;
2752
- reviseMessage(lease: OwnerLease, input: {
2753
- agentId: AgentId;
2754
- messageId: MessageId;
2755
- expectedMessageRevision: number;
2756
- content: UserContent;
2757
- operationId: string;
2758
- effectDigestConfirmation?: string;
2759
- }): MessageRevisionResult;
2760
- private commitInteractionRecord;
2761
- createRun(lease: OwnerLease, input: {
2762
- agentId: AgentId;
2763
- input: UserInput;
2764
- metadata?: Metadata;
2765
- scope?: ScopeRef;
2766
- cwd?: string;
2767
- phasePayload?: JsonValue;
2768
- entryPhases?: readonly EntryPhaseSpec[];
2769
- pinnedConfigToken?: ConfigToken;
2770
- idempotencyKey: string;
2771
- }): RunRecord;
2772
- claimRun(lease: OwnerLease, input: {
2773
- runId: RunId;
2774
- expectedRevision: number;
2775
- executionId?: ExecutionId;
2776
- messageId?: MessageId;
2777
- configToken?: ConfigToken;
2778
- additionalContexts?: readonly ContextCandidate[];
2779
- }): RunClaim;
2780
- failQueuedRun(lease: OwnerLease, input: {
2781
- runId: RunId;
2782
- expectedRevision: number;
2783
- failure: Extract<RunFailure, {
2784
- code: "configuration_unavailable" | "checkpoint_incompatible";
2785
- }>;
2786
- }): RunRecord;
2787
- commitPhaseEntered(lease: OwnerLease, input: {
2788
- runId: RunId;
2789
- execution: ExecutionToken;
2790
- expectedRevision: number;
2791
- phaseId: string;
2792
- visit: number;
2793
- }): RunRecord;
2794
- /** Commit a parallel Phase's reply while its Run is still running. */
2795
- commitPhaseOutput(lease: OwnerLease, input: {
2796
- runId: RunId;
2797
- execution: ExecutionToken;
2798
- expectedRevision: number;
2799
- message: AssistantMessage;
2800
- }): RunRecord;
2801
- commitInputRequired(lease: OwnerLease, input: {
2802
- runId: RunId;
2803
- execution: ExecutionToken;
2804
- expectedRevision: number;
2805
- phase: string;
2806
- prompt?: AssistantMessage;
2807
- checkpoint: ExecutionCheckpoint;
2808
- interactions?: readonly RunInteraction[];
2809
- interactionAnswers?: Readonly<Record<string, JsonValue>>;
2810
- pendingToolCallIds?: readonly ToolCallId[];
2811
- }): RunRecord;
2812
- answerInteraction(lease: OwnerLease, input: {
2813
- runId: RunId;
2814
- interactionId: string;
2815
- expectedRevision: number;
2816
- input?: JsonValue;
2817
- cancel?: boolean;
2818
- }): RunRecord;
2819
- reserveToolCall(lease: OwnerLease, input: {
2820
- runId: RunId;
2821
- execution: ExecutionToken;
2822
- expectedRevision: number;
2823
- requestMessageId: MessageId;
2824
- name: string;
2825
- args: JsonValue;
2826
- toolCallId?: ToolCallId;
2827
- providerToolCallId?: string;
2828
- model?: ModelRef;
2829
- usage?: LlmTokenUsage;
2830
- }): ToolCommit;
2831
- reserveToolCalls(lease: OwnerLease, input: {
2832
- runId: RunId;
2833
- execution: ExecutionToken;
2834
- expectedRevision: number;
2835
- requestMessageId: MessageId;
2836
- calls: readonly ToolCallReservation[];
2837
- /** The model response's blocks, so the request message keeps what preceded the Tool Calls. */
2838
- contentBlocks?: readonly ContentBlock[];
2839
- model?: ModelRef;
2840
- usage?: LlmTokenUsage;
2841
- }): ToolBatchCommit;
2842
- startToolCall(lease: OwnerLease, input: {
2843
- runId: RunId;
2844
- execution: ExecutionToken;
2845
- expectedRevision: number;
2846
- toolCallId: ToolCallId;
2847
- title?: string;
2848
- kind?: ToolKind;
2849
- locations?: ToolCallLocation[];
2850
- content?: ToolCallContent[];
2851
- _meta?: JsonObject;
2852
- }): ToolCommit;
2853
- suspendToolCall(lease: OwnerLease, input: {
2854
- runId: RunId;
2855
- execution: ExecutionToken;
2856
- expectedRevision: number;
2857
- toolCallId: ToolCallId;
2858
- }): ToolCommit;
2859
- commitToolResult(lease: OwnerLease, input: {
2860
- runId: RunId;
2861
- execution: ExecutionToken;
2862
- expectedRevision: number;
2863
- toolCallId: ToolCallId;
2864
- result: ToolExecutionResult;
2865
- state: "completed" | "failed" | "indeterminate";
2866
- reason?: string;
2867
- title?: string;
2868
- kind?: ToolKind;
2869
- content?: ToolCallContent[];
2870
- locations?: ToolCallLocation[];
2871
- rawOutput?: JsonValue;
2872
- _meta?: JsonObject;
2873
- }): ToolCommit;
2874
- commitOutcome(lease: OwnerLease, input: {
2875
- runId: RunId;
2876
- execution: ExecutionToken;
2877
- expectedRevision: number;
2878
- outcome?: Outcome$1;
2879
- failure?: RunFailure;
2880
- output?: AssistantMessage;
2881
- }): RunRecord;
2882
- cancelRun(lease: OwnerLease, input: {
2883
- runId: RunId;
2884
- expectedRevision?: number;
2885
- reason?: string;
2886
- output?: AssistantMessage;
2887
- }): RunRecord;
2888
- recordToolCall(lease: OwnerLease, input: {
2889
- runId: RunId;
2890
- execution?: ExecutionToken;
2891
- update: ToolCall$1 | ToolCallUpdate;
2892
- external?: boolean;
2893
- contentIndex?: number;
2894
- }): DurableRunEvent;
2895
- snapshotRun(lease: OwnerLease, runId: RunId): RunSnapshot;
2896
- listAgents(lease: OwnerLease): readonly AgentRecord[];
2897
- listRuns(lease: OwnerLease, input?: {
2898
- agentId?: AgentId;
2899
- states?: readonly RunState[];
2900
- }): readonly RunRecord[];
2901
- listEvents(lease: OwnerLease, input?: {
2902
- after?: EventCursor;
2903
- }): readonly DurableRunEvent[];
2904
- openConsumer(lease: OwnerLease, consumerId: string): ConsumerRegistration;
2905
- advanceConsumerCheckpoint(lease: OwnerLease, input: {
2906
- consumerId: string;
2907
- cursor: EventCursor;
2908
- }): void;
2909
- compact(lease: OwnerLease, input?: {
2910
- now?: string;
2911
- retentionMs?: number;
2912
- }): RetentionResult;
2913
- private replay;
2914
- private writeReceipt;
2915
- private replayOperation;
2916
- private writeOperationReceipt;
2917
- /**
2918
- * A Claim receipt exists for idempotent replay of one live Execution Attempt
2919
- * and carries that Attempt's history. Dropping it when the Attempt ends keeps
2920
- * one history snapshot per Agent instead of one per Attempt.
2921
- */
2922
- private dropClaimReceipt;
2923
- /**
2924
- * A new owner fences the Execution Attempts of the previous one, so no Claim
2925
- * receipt from before the takeover can be replayed. Sweeping them reclaims
2926
- * the history snapshots a store accumulated while no Attempt ended under
2927
- * this Runtime.
2928
- */
2929
- dropSettledClaimReceipts(): void;
2930
- private requireAgent;
2931
- private requireRun;
2932
- private requireToolCall;
2933
- private assertNoOpenTools;
2934
- private interruptToolCall;
2935
- private assertState;
2936
- private assertRevision;
2937
- private assertExecution;
2938
- private nextSequence;
2939
- private nextReady;
2940
- private nextMessageSequence;
2941
- private messagesForRun;
2942
- private withdrawUserInputIfNoOutput;
2943
- history(lease: OwnerLease, agentId: AgentId): readonly Message[];
2944
- contextStatus(lease: OwnerLease, agentId: AgentId, contextWindow: number): ContextStatus;
2945
- contextMessages(lease: OwnerLease, agentId: AgentId, recentTokenBudget?: number): readonly Message[];
2946
- commitContextCompaction(lease: OwnerLease, record: ContextCompactionRecord): ContextCompactionRecord;
2947
- private activeHistory;
2948
- private appendMessage;
2949
- private appendTransition;
2950
- private appendToolTransition;
2951
- private baseEvent;
2952
- private cursorForRun;
2953
- private parseCursor;
2954
- }
2955
-
2956
- declare class SqliteStore implements DurableStore {
2957
- private readonly database;
2958
- private readonly archiveRoot;
2959
- private readonly mirroredEventIds;
2960
- private readonly mirroredCompactionIds;
2961
- private mirroredAgents;
2962
- private closed;
2963
- private configured;
2964
- private cachedMemory?;
2965
- private cachedOwner?;
2966
- private isLegacyState;
2967
- private stmtUpsertAgent?;
2968
- private stmtDeleteAgent?;
2969
- private stmtUpsertRun?;
2970
- private stmtDeleteRun?;
2971
- private stmtInsertMessage?;
2972
- private stmtDeleteMessage?;
2973
- private stmtUpsertToolCall?;
2974
- private stmtDeleteToolCall?;
2975
- private stmtInsertEvent?;
2976
- private stmtDeleteEvent?;
2977
- private stmtUpsertIdempotency?;
2978
- private stmtDeleteIdempotency?;
2979
- private stmtUpsertCheckpoint?;
2980
- private stmtDeleteCheckpoint?;
2981
- private stmtUpdateMeta?;
2982
- private stmtUpdateState?;
2983
- constructor(filename?: string);
2984
- openOwner(input: {
2985
- ownerId: string;
2986
- leaseMs: number;
2987
- }): Promise<OwnedStore>;
2988
- close(): void;
2989
- exportState(): InMemoryStoreState;
2990
- /** Filesystem location owned by this Store for one Agent's readable archive. */
2991
- contextArchiveDir(agentId: AgentId): string;
2992
- reserveAgent(lease: OwnerLease, input: {
2993
- idempotencyKey: string;
2994
- metadata?: Metadata;
2995
- configIdentity?: string;
2996
- historySeed?: HistorySeed;
2997
- }): Promise<AgentRecord>;
2998
- activateAgent(lease: OwnerLease, agentId: AgentId, configToken?: ConfigToken, configIdentity?: string): Promise<AgentRecord>;
2999
- updateAgentConfigToken(lease: OwnerLease, input: {
3000
- agentId: AgentId;
3001
- token: ConfigToken;
3002
- configIdentity?: string;
3003
- idempotencyKey: string;
3004
- }): Promise<AgentRecord>;
3005
- deleteAgent(lease: OwnerLease, input: AgentDeletionRequest): Promise<void>;
3006
- reviseMessage(lease: OwnerLease, input: {
3007
- agentId: AgentId;
3008
- messageId: MessageId;
3009
- expectedMessageRevision: number;
3010
- content: UserContent;
3011
- operationId: string;
3012
- effectDigestConfirmation?: string;
3013
- }): Promise<MessageRevisionResult>;
3014
- contextStatus(lease: OwnerLease, agentId: AgentId, contextWindow: number): Promise<ContextStatus>;
3015
- contextMessages(lease: OwnerLease, agentId: AgentId, recentTokenBudget?: number): Promise<readonly Message[]>;
3016
- commitContextCompaction(lease: OwnerLease, record: ContextCompactionRecord): Promise<ContextCompactionRecord>;
3017
- createRun(lease: OwnerLease, input: {
3018
- agentId: AgentId;
3019
- input: UserInput;
3020
- metadata?: Metadata;
3021
- scope?: ScopeRef;
3022
- cwd?: string;
3023
- phasePayload?: JsonValue;
3024
- entryPhases?: readonly EntryPhaseSpec[];
3025
- pinnedConfigToken?: ConfigToken;
3026
- idempotencyKey: string;
3027
- }): Promise<RunRecord>;
3028
- claimRun(lease: OwnerLease, input: {
3029
- runId: RunId;
3030
- expectedRevision: number;
3031
- executionId?: ExecutionId;
3032
- messageId?: MessageId;
3033
- configToken?: ConfigToken;
3034
- additionalContexts?: readonly ContextCandidate[];
3035
- }): Promise<RunClaim>;
3036
- failQueuedRun(lease: OwnerLease, input: {
3037
- runId: RunId;
3038
- expectedRevision: number;
3039
- failure: Extract<RunFailure, {
3040
- code: "configuration_unavailable" | "checkpoint_incompatible";
3041
- }>;
3042
- }): Promise<RunRecord>;
3043
- commitPhaseEntered(lease: OwnerLease, input: {
3044
- runId: RunId;
3045
- execution: ExecutionToken;
3046
- expectedRevision: number;
3047
- phaseId: string;
3048
- visit: number;
3049
- }): Promise<RunRecord>;
3050
- commitPhaseOutput(lease: OwnerLease, input: {
3051
- runId: RunId;
3052
- execution: ExecutionToken;
3053
- expectedRevision: number;
3054
- message: AssistantMessage;
3055
- }): Promise<RunRecord>;
3056
- commitInputRequired(lease: OwnerLease, input: {
3057
- runId: RunId;
3058
- execution: ExecutionToken;
3059
- expectedRevision: number;
3060
- phase: string;
3061
- prompt?: AssistantMessage;
3062
- checkpoint: ExecutionCheckpoint;
3063
- interactions?: readonly RunInteraction[];
3064
- interactionAnswers?: Readonly<Record<string, JsonValue>>;
3065
- pendingToolCallIds?: readonly ToolCallId[];
3066
- }): Promise<RunRecord>;
3067
- answerInteraction(lease: OwnerLease, input: {
3068
- runId: RunId;
3069
- interactionId: string;
3070
- expectedRevision: number;
3071
- input?: JsonValue;
3072
- cancel?: boolean;
3073
- }): Promise<RunRecord>;
3074
- commitOutcome(lease: OwnerLease, input: {
3075
- runId: RunId;
3076
- execution: ExecutionToken;
3077
- expectedRevision: number;
3078
- outcome?: Outcome$1;
3079
- failure?: RunFailure;
3080
- output?: AssistantMessage;
3081
- }): Promise<RunRecord>;
3082
- reserveToolCall(lease: OwnerLease, input: {
3083
- runId: RunId;
3084
- execution: ExecutionToken;
3085
- expectedRevision: number;
3086
- requestMessageId: MessageId;
3087
- name: string;
3088
- args: JsonValue;
3089
- toolCallId?: ToolCallId;
3090
- providerToolCallId?: string;
3091
- title?: string;
3092
- kind?: ToolKind;
3093
- locations?: ToolCallLocation[];
3094
- content?: ToolCallContent[];
3095
- _meta?: JsonObject;
3096
- model?: _rowan_agent_models.ModelRef;
3097
- usage?: _rowan_agent_models.LlmTokenUsage;
3098
- }): Promise<ToolCommit>;
3099
- reserveToolCalls(lease: OwnerLease, input: {
3100
- runId: RunId;
3101
- execution: ExecutionToken;
3102
- expectedRevision: number;
3103
- requestMessageId: MessageId;
3104
- calls: readonly ToolCallReservation[];
3105
- contentBlocks?: readonly ContentBlock[];
3106
- model?: _rowan_agent_models.ModelRef;
3107
- usage?: _rowan_agent_models.LlmTokenUsage;
3108
- }): Promise<ToolBatchCommit>;
3109
- startToolCall(lease: OwnerLease, input: {
3110
- runId: RunId;
3111
- execution: ExecutionToken;
3112
- expectedRevision: number;
3113
- toolCallId: ToolCallId;
3114
- title?: string;
3115
- kind?: ToolKind;
3116
- locations?: ToolCallLocation[];
3117
- content?: ToolCallContent[];
3118
- _meta?: JsonObject;
3119
- }): Promise<ToolCommit>;
3120
- suspendToolCall(lease: OwnerLease, input: {
3121
- runId: RunId;
3122
- execution: ExecutionToken;
3123
- expectedRevision: number;
3124
- toolCallId: ToolCallId;
3125
- }): Promise<ToolCommit>;
3126
- commitToolResult(lease: OwnerLease, input: {
3127
- runId: RunId;
3128
- execution: ExecutionToken;
3129
- expectedRevision: number;
3130
- toolCallId: ToolCallId;
3131
- result: ToolExecutionResult;
3132
- state: "completed" | "failed" | "indeterminate";
3133
- reason?: string;
3134
- title?: string;
3135
- kind?: ToolKind;
3136
- content?: ToolCallContent[];
3137
- locations?: ToolCallLocation[];
3138
- rawOutput?: JsonValue;
3139
- _meta?: JsonObject;
3140
- }): Promise<ToolCommit>;
3141
- cancelRun(lease: OwnerLease, input: {
3142
- runId: RunId;
3143
- expectedRevision?: number;
3144
- reason?: string;
3145
- output?: AssistantMessage;
3146
- }): Promise<RunRecord>;
3147
- recordToolCall(lease: OwnerLease, input: {
3148
- runId: RunId;
3149
- execution?: ExecutionToken;
3150
- update: ToolCall$1 | ToolCallUpdate;
3151
- external?: boolean;
3152
- contentIndex?: number;
3153
- }): Promise<DurableRunEvent>;
3154
- snapshotRun(lease: OwnerLease, runId: RunId): Promise<RunSnapshot>;
3155
- history(lease: OwnerLease, agentId: AgentId): Promise<readonly Message[]>;
3156
- listAgents(lease: OwnerLease): Promise<readonly AgentRecord[]>;
3157
- listRuns(lease: OwnerLease, input?: {
3158
- agentId?: AgentId;
3159
- states?: readonly RunState[];
3160
- }): Promise<readonly RunRecord[]>;
3161
- listEvents(lease: OwnerLease, input?: {
3162
- after?: EventCursor;
3163
- }): Promise<readonly DurableRunEvent[]>;
3164
- openConsumer(lease: OwnerLease, consumerId: string): Promise<ConsumerRegistration>;
3165
- advanceConsumerCheckpoint(lease: OwnerLease, input: {
3166
- consumerId: string;
3167
- cursor: EventCursor;
3168
- }): Promise<void>;
3169
- compact(lease: OwnerLease, input?: {
3170
- now?: string;
3171
- retentionMs?: number;
3172
- }): Promise<RetentionResult>;
3173
- renewOwner(lease: OwnerLease, leaseMs: number): Promise<OwnerLease>;
3174
- sealAndReleaseOwner(lease: OwnerLease): Promise<void>;
3175
- private read;
3176
- private write;
3177
- private invoke;
3178
- private ensureSchema;
3179
- private isCurrentSchema;
3180
- private configure;
3181
- private catalog;
3182
- private readOwner;
3183
- private writeOwner;
3184
- private readState;
3185
- private loadTableBackedState;
3186
- private ensureTableBackedStorage;
3187
- private getStmtUpsertAgent;
3188
- private getStmtDeleteAgent;
3189
- private getStmtUpsertRun;
3190
- private getStmtDeleteRun;
3191
- private getStmtInsertMessage;
3192
- private getStmtDeleteMessage;
3193
- private getStmtUpsertToolCall;
3194
- private getStmtDeleteToolCall;
3195
- private getStmtInsertEvent;
3196
- private getStmtDeleteEvent;
3197
- private getStmtUpsertIdempotency;
3198
- private getStmtDeleteIdempotency;
3199
- private getStmtUpsertCheckpoint;
3200
- private getStmtDeleteCheckpoint;
3201
- private getStmtUpdateMeta;
3202
- private getStmtUpdateState;
3203
- private persistChanges;
3204
- private writeFullStateToTables;
3205
- private mirrorChanges;
3206
- /** Append the semantic durable event mirror and remove deleted Agent sidecars. */
3207
- private mirrorInitialState;
3208
- private requireMatchingOwner;
3209
- private immediateTransaction;
3210
- private readTransaction;
3211
- private assertOpen;
3212
- }
3213
-
3214
- /** A deterministic provider for tests and embedded hosts without a separate registry. */
3215
- declare class InMemoryConfigProvider implements ConfigProvider {
3216
- private readonly entries;
3217
- private readonly operations;
3218
- put(input: {
3219
- agentId: AgentId;
3220
- agentMetadata?: Metadata;
3221
- config: AgentConfiguration | ConfigurationSnapshot;
3222
- operationId: string;
3223
- signal: AbortSignal;
3224
- }): Promise<ConfigPutResult>;
3225
- resolve(input: {
3226
- agentId: AgentId;
3227
- agentMetadata?: Metadata;
3228
- token: ConfigToken;
3229
- signal: AbortSignal;
3230
- }): Promise<ConfigResolution>;
3231
- }
3232
- declare function brandConfigToken(raw: unknown): ConfigToken;
3233
-
3234
- type RuntimeErrorCode = "invalid_argument" | "runtime_closed" | "runtime_already_owned" | "runtime_ownership_lost" | "agent_not_found" | "run_not_found" | "run_state_conflict" | "context_busy" | "message_history_compacted" | "message_revision_conflict" | "tool_effect_confirmation_required" | "input_request_conflict" | "idempotency_conflict" | "configuration_unavailable" | "checkpoint_incompatible" | "consumer_already_active" | "invalid_cursor" | "store_unavailable" | "unsupported_store_version";
3235
- type RuntimeErrorDetails = {
3236
- invalid_argument: Readonly<{
3237
- argument: string;
3238
- reason: string;
3239
- }>;
3240
- runtime_closed: null;
3241
- runtime_already_owned: Readonly<{
3242
- expiresAt: string;
3243
- retryAfterMs: number;
3244
- }>;
3245
- runtime_ownership_lost: Readonly<{
3246
- reason: "expired" | "released" | "epoch_advanced";
3247
- expectedEpoch: number;
3248
- actualEpoch: number;
3249
- expiresAt?: string;
3250
- }>;
3251
- agent_not_found: Readonly<{
3252
- agentId: AgentId;
3253
- }>;
3254
- run_not_found: Readonly<{
3255
- runId: RunId;
3256
- }>;
3257
- run_state_conflict: Readonly<{
3258
- runId: RunId;
3259
- expected: readonly RunState[];
3260
- actual: RunState;
3261
- }>;
3262
- context_busy: Readonly<{
3263
- agentId: AgentId;
3264
- runId?: RunId;
3265
- actual: RunState;
3266
- }>;
3267
- message_history_compacted: Readonly<{
3268
- agentId: AgentId;
3269
- messageId: MessageId;
3270
- }>;
3271
- message_revision_conflict: Readonly<{
3272
- agentId: AgentId;
3273
- messageId: MessageId;
3274
- expected: number;
3275
- actual: number;
3276
- }>;
3277
- tool_effect_confirmation_required: Readonly<{
3278
- agentId: AgentId;
3279
- messageId: MessageId;
3280
- effectDigest: string;
3281
- toolCallIds: readonly ToolCallId[];
3282
- }>;
3283
- input_request_conflict: Readonly<{
3284
- runId: RunId;
3285
- interactionId?: string;
3286
- requestId?: string;
3287
- reason: "not_found" | "wrong_run" | "different_answer";
3288
- }>;
3289
- idempotency_conflict: Readonly<{
3290
- scope: "create_agent" | "update_agent_config" | "start_run";
3291
- idempotencyKey: string;
3292
- }>;
3293
- configuration_unavailable: Readonly<{
3294
- agentId: AgentId;
3295
- runId?: RunId;
3296
- retryable: boolean;
3297
- reason: string;
3298
- }>;
3299
- checkpoint_incompatible: Readonly<{
3300
- runId: RunId;
3301
- expected: Readonly<{
3302
- codec: string;
3303
- versions: readonly number[];
3304
- }>;
3305
- actual: Readonly<{
3306
- codec: string;
3307
- version: number;
3308
- }>;
3309
- }>;
3310
- consumer_already_active: Readonly<{
3311
- consumerId: string;
3312
- }>;
3313
- invalid_cursor: Readonly<{
3314
- cursorType: "agent_list" | "run_list" | "event";
3315
- reason: "malformed" | "wrong_store" | "wrong_collection" | "filter_mismatch" | "beyond_waterline" | "expired";
3316
- }>;
3317
- store_unavailable: Readonly<{
3318
- operation: string;
3319
- retryable: boolean;
3320
- reason: string;
3321
- }>;
3322
- unsupported_store_version: Readonly<{
3323
- found: string | null;
3324
- supported: string;
3325
- }>;
3326
- };
3327
- type AnyRuntimeError = {
3328
- [Code in RuntimeErrorCode]: RuntimeError<Code>;
3329
- }[RuntimeErrorCode];
3330
- declare class RuntimeError<Code extends RuntimeErrorCode = RuntimeErrorCode> extends Error {
3331
- readonly code: Code;
3332
- readonly details: RuntimeErrorDetails[Code];
3333
- constructor(code: Code, details: RuntimeErrorDetails[Code], message?: Code);
3334
- }
3335
- declare function isRuntimeError(value: unknown): value is AnyRuntimeError;
3336
-
3337
- declare function loadSkill(path: string): Promise<Skill>;
3338
- declare function loadSkills(targetPath: string): Promise<Skill[]>;
3339
-
3340
- /**
3341
- * Load a single phase from a PHASE.md file or phase directory.
3342
- *
3343
- * If a directory is provided, the loader reads its PHASE.md.
3344
- */
3345
- declare function loadPhase(targetPath: string): Promise<Phase>;
3346
- /**
3347
- * Load all phases from the target directory.
3348
- *
3349
- * Scans for subdirectories containing PHASE.md files.
3350
- * Returns PhaseRegistry with entryPhaseId:
3351
- * - null by default (caller must explicitly set to start from a specific phase)
3352
- * - Set to a specific phase name to start from that phase
3353
- *
3354
- * When entryPhaseId is null, Agent normalizes the registry to start from its default phase.
3355
- */
3356
- declare function loadPhases(targetPath: string): Promise<PhaseRegistry>;
3357
-
3358
- declare const DEFAULT_PHASE_ID = "default";
3359
- declare const STOP_PHASE_ID = "stop";
3360
- declare const COMPACT_PHASE_ID = "compact";
3361
- declare function createDefaultPhase(): Phase;
3362
- declare function createStopPhase(): Phase;
3363
- declare function createCompactPhase(): Phase;
3364
- declare function createCorePhases(): Phase[];
3365
-
3366
- /**
3367
- * Extension loader — discovers and loads extensions from the filesystem.
3368
- *
3369
- * Uses the new LoadedExtension type that works with ExtensionRunner.
3370
- */
3371
-
3372
- /**
3373
- * Load extensions from the exact target path.
3374
- *
3375
- * If the target is a directory with its own extension entry, load that extension.
3376
- * Otherwise, scan its immediate children for extension packages/files.
3377
- */
3378
- declare function loadExtensionsFromPath(path: string): Promise<{
3379
- extensions: LoadedExtension[];
3380
- errors: Array<{
3381
- path: string;
3382
- error: string;
3383
- }>;
3384
- }>;
3385
-
3386
- /** Parsed frontmatter result */
3387
- interface FrontmatterResult<T = Record<string, unknown>> {
3388
- frontmatter: T;
3389
- body: string;
3390
- }
3391
- /**
3392
- * Parse YAML frontmatter from markdown content.
3393
- * Parse YAML frontmatter and return the markdown body after the closing delimiter.
3394
- */
3395
- declare function parseFrontmatter<T = Record<string, unknown>>(raw: string): FrontmatterResult<T>;
3396
-
3397
- declare function createCoreTools(input?: CoreToolContext): Tool$1[];
3398
-
3399
- export { type AfterToolCall, type AgentConfiguration, type AgentDefinition, type AgentId, type AgentListCursor, type AgentRecord, type AgentRun, AgentRuntime, type AgentRuntimeOptions, type AgentSummary, type AnyRuntimeError, type AssistantContent, type AssistantMessage, type BeforeToolCall, COMPACT_PHASE_ID, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type ContextCompactionRecord, type ContextStatus, type CoreToolContext, DEFAULT_PHASE_ID, type DefinitionLayer, type DurableConsumer, type DurableRunEvent, type DurableStore, type DurableToolResult, type EntryPhaseSpec, type EventCursor, type EventId, type ExecutionCheckpoint, type ExecutionId, type ExecutionToken, type ExtensionAPI, type ExtensionActivationError, type ExtensionActivationResult, type ExtensionCapability, type ExtensionCapabilityContribution, type ExtensionContribution, type ExtensionDisposer, type ExtensionFactory, type ExtensionFactoryResult, type ExtensionHost, ExtensionLifetimeError, type ExtensionLifetimeErrorCode, type ExtensionLoadInput, type ExtensionStateStore, type ExtensionToolContribution, type FrontmatterResult, type HistorySeed, type HookEvent, type HookEventType, type HookHandler, type HostApiExtension, InMemoryConfigProvider, InMemoryExtensionHost, InMemoryStore, type InteractionRecord, type InternalModelLoopOptions, type InvocationCatalogEntry, type InvocationSource, type JsonObject, type JsonPrimitive, type JsonValue, type LiveInteractionEvent, type LoadExtensionsResult, type LoadInput, type LoadResult, type LoadedExtension, type Message, type MessageBase, type MessageCommitted, type MessageContent, type MessageDelta, type MessageId, type MessageRevised, type MessageRevisionResult, type Metadata, type ModelInvokeOutput, type ModelRetry, type OpaqueId, type Outcome$1 as Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecution, type PhaseExecutionIdentity, type PhaseInput, type PhaseInvocation, type PhaseMessageManager, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseState, type PhaseStatus, type PhaseStatusState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, type RetentionResult, type RunBoundary, type RunClaim, type RunEndEvent, type RunEvent, type RunFailure, type RunId, type RunInteraction, RunInteractionBoundary, RunInteractionCancelledError, type RunInteractionDriver, type RunInteractionKind, type RunInteractionRequest, type RunInteractionState, type RunInteractionStatus, type RunListCursor, type RunRecord, type RunSnapshot, type RunStartEvent, type RunState, type RunStateChanged, type RunSummary, RuntimeBootstrapRegistry, RuntimeError, type RuntimeErrorCode, type RuntimeErrorDetails, RuntimeExtensionLifetime, STOP_PHASE_ID, type SettingsBadge, type SettingsControl, type SettingsDefinition, type SettingsItem, type SettingsOption, type SettingsSection, type Skill, type SkillRegistration, SqliteStore, type TextContent, type ThinkingContent, type ThinkingDelta, type Tool$1 as Tool, type ToolCallContext, type ToolCallDelta, type ToolCallId, type ToolCallPresentationInput, type ToolCallPresentationOutput, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, type WithdrawnUserInput, brandConfigToken, createCompactPhase, createCorePhases, createCoreTools, createDefaultPhase, createStopPhase, extensionSourceId, isConfigurationSnapshot, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhase, loadPhases, loadSkill, loadSkills, mergeToolCall, parseAgentDefinition, parseFrontmatter, resolveConfigurationSnapshot };
2
+ export { _rowan_agent_models as models };
3
+ export { ScopeRef } from '@rowan-agent/models';
4
+ export { aO as AfterToolCall, g as AgentId, q as AgentListCursor, o as AgentRun, s as AgentSummary, aP as AssistantContent, a4 as AssistantMessage, aQ as BeforeToolCall, a0 as ContextCandidate, X as ContextCompactionRecord, C as ContextStatus, x as DurableConsumer, D as DurableRunEvent, aR as EventBus, m as EventCursor, aS as EventId, aT as ExecOptions, aU as ExecResult, aV as ExtensionAPI, aW as ExtensionAgentConsumerDisposer, aX as ExtensionAgentsAPI, y as ExtensionCapability, aY as ExtensionCapabilityContribution, aZ as ExtensionContext, a_ as ExtensionDisposer, a$ as ExtensionFactory, b0 as ExtensionFactoryResult, b1 as ExtensionStateStore, b2 as ExtensionToolContribution, b3 as HookEvent, b4 as HookEventType, b5 as HookHandler, b6 as InternalModelLoopOptions, J as JsonObject, b7 as JsonPrimitive, a as JsonValue, b8 as LiveInteractionEvent, B as Message, b9 as MessageBase, ba as MessageCommitted, bb as MessageContent, bc as MessageDelta, i as MessageId, bd as MessageRevised, j as MessageRevisionResult, be as ModelInvokeOutput, r as Page, P as Phase, bf as PhaseContext, bg as PhaseExecution, bh as PhaseExecutionIdentity, bi as PhaseInput, bj as PhaseInvocation, bk as PhaseMessageManager, bl as PhaseOutput, bm as PhaseRegistration, bn as PhaseRunHandler, bo as PhaseState, bp as PhaseStatus, bq as PhaseStatusState, F as RunBoundary, br as RunEndEvent, G as RunEvent, a2 as RunFailure, k as RunId, a6 as RunInteraction, bs as RunInteractionBoundary, bt as RunInteractionCancelledError, bu as RunInteractionDriver, bv as RunInteractionKind, bw as RunInteractionRequest, bx as RunInteractionState, by as RunInteractionStatus, u as RunListCursor, z as RunSnapshot, bz as RunStartEvent, t as RunState, bA as RunStateChanged, v as RunSummary, bB as SettingsBadge, bC as SettingsControl, bD as SettingsDefinition, bE as SettingsItem, bF as SettingsOption, bG as SettingsSection, bH as SkillRegistration, bI as TextContent, bJ as ThinkingContent, bK as ThinkingDelta, bL as ToolCallContext, bM as ToolCallDelta, l as ToolCallId, bN as ToolCallPhase, bO as ToolCallPresentationInput, bP as ToolCallPresentationOutput, Y as ToolCallSnapshot, V as ToolCallState, bQ as ToolDefinition, aa as ToolExecutionResult, bR as ToolInvocationContext, bS as ToolMessage, bT as ToolMessageContent, bU as ToolResultContent, bV as ToolStateChanged, bW as ToolUseContent, U as UserContent, n as UserInput, bX as UserMessage, bY as WithdrawnUserInput } from './index-CMFf6UJI.js';
5
+ import 'typebox';