@aaac/runtime 0.1.54 → 0.2.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/README.md +6 -11
- package/dist/adapters/adk-sdk.d.ts +3 -3
- package/dist/adapters/adk-sdk.js +6 -8
- package/dist/adapters/adk-sdk.js.map +1 -1
- package/dist/adapters/claude-agent-sdk.d.ts +3 -3
- package/dist/adapters/claude-agent-sdk.js +22 -23
- package/dist/adapters/claude-agent-sdk.js.map +1 -1
- package/dist/adapters/mock.d.ts +2 -3
- package/dist/adapters/openai-agents-sdk.d.ts +3 -3
- package/dist/adapters/openai-agents-sdk.js +6 -5
- package/dist/adapters/openai-agents-sdk.js.map +1 -1
- package/dist/chunk-2INQL5TG.js +298 -0
- package/dist/chunk-2INQL5TG.js.map +1 -0
- package/dist/chunk-3CLWG72V.js +47 -0
- package/dist/chunk-3CLWG72V.js.map +1 -0
- package/dist/chunk-3DDB34BU.js +237 -0
- package/dist/chunk-3DDB34BU.js.map +1 -0
- package/dist/chunk-ABXDSTUV.js +685 -0
- package/dist/chunk-ABXDSTUV.js.map +1 -0
- package/dist/{chunk-3H3PVPPF.js → chunk-F5R46S7I.js} +151 -204
- package/dist/chunk-F5R46S7I.js.map +1 -0
- package/dist/chunk-FKAI54OM.js +234 -0
- package/dist/chunk-FKAI54OM.js.map +1 -0
- package/dist/chunk-KTVMMG33.js +1111 -0
- package/dist/chunk-KTVMMG33.js.map +1 -0
- package/dist/chunk-MSVIEEGR.js +269 -0
- package/dist/chunk-MSVIEEGR.js.map +1 -0
- package/dist/chunk-VJXGCWSZ.js +36 -0
- package/dist/chunk-VJXGCWSZ.js.map +1 -0
- package/dist/claude-bundles/full.js +311 -309
- package/dist/claude-bundles/lean.js +6 -6
- package/dist/claude-bundles/prompt.js +17 -0
- package/dist/generator/index.d.ts +2 -2
- package/dist/generator/index.js +8 -7
- package/dist/guardrail-hooks-CB23nhZV.d.ts +202 -0
- package/dist/hook-protocol-CFnNudiV.d.ts +96 -0
- package/dist/hooks-lite-CoWWnCRH.d.ts +428 -0
- package/dist/index-BlSepCSZ.d.ts +296 -0
- package/dist/index.d.ts +785 -105
- package/dist/index.js +2235 -659
- package/dist/index.js.map +1 -1
- package/dist/lib/claude-native/hooks-lite.d.ts +3 -26
- package/dist/lib/claude-native/hooks-lite.js +18 -36
- package/dist/lib/claude-native/hooks-prompt.d.ts +5 -0
- package/dist/lib/claude-native/hooks-prompt.js +33 -0
- package/dist/lib/claude-native/hooks-prompt.js.map +1 -0
- package/dist/lib/claude-native/index.d.ts +56 -214
- package/dist/lib/claude-native/index.js +79 -280
- package/dist/lib/claude-native/index.js.map +1 -1
- package/dist/{navigation-context-D_E1NIUf.d.ts → navigation-context-B-RpUg3_.d.ts} +1 -1
- package/dist/navigation-index-prompt-CbrS5laO.d.ts +43 -0
- package/dist/{task-runner-CLc8iTzy.d.ts → task-runner-GWoI7_71.d.ts} +100 -478
- package/dist/workspace-user-prompt-submit-D11Iu0zO.d.ts +269 -0
- package/package.json +15 -6
- package/dist/chunk-3H3PVPPF.js.map +0 -1
- package/dist/chunk-DBM5XN67.js +0 -354
- package/dist/chunk-DBM5XN67.js.map +0 -1
- package/dist/chunk-KXGUWBGK.js +0 -370
- package/dist/chunk-KXGUWBGK.js.map +0 -1
- package/dist/chunk-LDCQZPDG.js +0 -11
- package/dist/chunk-LDCQZPDG.js.map +0 -1
- package/dist/chunk-N4KNGDYY.js +0 -1963
- package/dist/chunk-N4KNGDYY.js.map +0 -1
- package/dist/chunk-NMX4C6LC.js +0 -332
- package/dist/chunk-NMX4C6LC.js.map +0 -1
- package/dist/chunk-QVH5KKBR.js +0 -374
- package/dist/chunk-QVH5KKBR.js.map +0 -1
- package/dist/context-DKkamYX_.d.ts +0 -31
- package/dist/guardrail-hooks-slK-z0Dz.d.ts +0 -83
- package/dist/index-LqEvaRk-.d.ts +0 -299
- package/dist/workspace-pre-tool-use-C6nidc0q.d.ts +0 -333
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import {
|
|
3
|
-
import { a as GuardrailRuleData } from './guardrail-hooks-slK-z0Dz.js';
|
|
2
|
+
import { ModelClass } from '@aaac/contracts';
|
|
4
3
|
import { EmitInput, ExecutionEnvelope, AttrValue, CanonicalLink } from '@aaac/observability';
|
|
5
4
|
|
|
6
5
|
/**
|
|
@@ -307,460 +306,6 @@ declare function createLibraryToolRegistry(): LibraryToolRegistry;
|
|
|
307
306
|
*/
|
|
308
307
|
declare function createRegistryFromSdkTools(tools: SdkFunctionTool[]): LibraryToolRegistry;
|
|
309
308
|
|
|
310
|
-
/**
|
|
311
|
-
* ModelResolver — resolves a model_class to a concrete adapter + model pair.
|
|
312
|
-
*
|
|
313
|
-
* Resolution priority (highest wins):
|
|
314
|
-
* 1. AGENT_RUNTIME_MODEL_{FAST|STANDARD|THINKING} env var
|
|
315
|
-
* 2. AGENT_RUNTIME_MODEL env var (catch-all fallback)
|
|
316
|
-
* 3. agents.conf.yaml model_mapping.<class>
|
|
317
|
-
* 4. CLI --adapter + adapter default model
|
|
318
|
-
*/
|
|
319
|
-
type ModelClass = "fast" | "standard" | "thinking";
|
|
320
|
-
interface ResolvedModel {
|
|
321
|
-
adapter: string;
|
|
322
|
-
model?: string;
|
|
323
|
-
}
|
|
324
|
-
interface ModelResolver {
|
|
325
|
-
resolve(modelClass: ModelClass | undefined): ResolvedModel;
|
|
326
|
-
}
|
|
327
|
-
interface ModelMappingConfig {
|
|
328
|
-
fast?: {
|
|
329
|
-
adapter: string;
|
|
330
|
-
model?: string;
|
|
331
|
-
};
|
|
332
|
-
standard?: {
|
|
333
|
-
adapter: string;
|
|
334
|
-
model?: string;
|
|
335
|
-
};
|
|
336
|
-
thinking?: {
|
|
337
|
-
adapter: string;
|
|
338
|
-
model?: string;
|
|
339
|
-
};
|
|
340
|
-
}
|
|
341
|
-
interface ModelResolverOptions {
|
|
342
|
-
modelMapping?: ModelMappingConfig;
|
|
343
|
-
fallbackAdapter: string;
|
|
344
|
-
fallbackModel?: string;
|
|
345
|
-
env?: Record<string, string | undefined>;
|
|
346
|
-
/**
|
|
347
|
-
* When set, always use this adapter name. Model is still resolved per class
|
|
348
|
-
* from mapping / env (e.g. CLI `--adapter mock` with project model_mapping).
|
|
349
|
-
*/
|
|
350
|
-
pinnedAdapter?: string;
|
|
351
|
-
}
|
|
352
|
-
declare function createModelResolver(options: ModelResolverOptions): ModelResolver;
|
|
353
|
-
|
|
354
|
-
/**
|
|
355
|
-
* Toolchain Checker — runs check commands defined in toolchain-contracts
|
|
356
|
-
* and returns structured pass/fail results.
|
|
357
|
-
*
|
|
358
|
-
* Each toolchain may declare a `checks` map (checkType → shell command).
|
|
359
|
-
* This module iterates all checks, executes them via subprocess, and
|
|
360
|
-
* returns a ToolchainCheckResult[].
|
|
361
|
-
*
|
|
362
|
-
* For "drift" check types, a manifest-based fast path is available:
|
|
363
|
-
* if a .toolchain-manifest.json exists and the toolchain_id matches,
|
|
364
|
-
* the command execution can be skipped when the source hash is current.
|
|
365
|
-
*/
|
|
366
|
-
|
|
367
|
-
declare const ToolchainManifestSchema: z.ZodObject<{
|
|
368
|
-
schema: z.ZodString;
|
|
369
|
-
toolchain_id: z.ZodString;
|
|
370
|
-
generated_at: z.ZodString;
|
|
371
|
-
source_hash: z.ZodString;
|
|
372
|
-
output_hash: z.ZodString;
|
|
373
|
-
source_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
374
|
-
output_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
375
|
-
files: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
376
|
-
path: z.ZodString;
|
|
377
|
-
hash: z.ZodString;
|
|
378
|
-
}, z.core.$strip>>>;
|
|
379
|
-
}, z.core.$strip>;
|
|
380
|
-
type ToolchainManifest = z.infer<typeof ToolchainManifestSchema>;
|
|
381
|
-
interface ToolchainCheckResult {
|
|
382
|
-
toolchainId: string;
|
|
383
|
-
checkType: string;
|
|
384
|
-
status: "pass" | "fail" | "skip" | "error";
|
|
385
|
-
action: "block" | "warn" | "shadow";
|
|
386
|
-
message?: string;
|
|
387
|
-
durationMs?: number;
|
|
388
|
-
}
|
|
389
|
-
interface RunToolchainChecksOptions {
|
|
390
|
-
/** Absolute path to toolchain-contracts YAML */
|
|
391
|
-
toolchainsPath: string;
|
|
392
|
-
/** Absolute path to artifact-contracts YAML (optional, for manifest fast path) */
|
|
393
|
-
artifactsPath?: string;
|
|
394
|
-
/** Working directory for subprocess execution */
|
|
395
|
-
cwd?: string;
|
|
396
|
-
/** Filter: only run these check types */
|
|
397
|
-
checkTypes?: string[];
|
|
398
|
-
/** Filter: only run checks for these toolchain IDs */
|
|
399
|
-
toolchainFilter?: string[];
|
|
400
|
-
/** Policy-resolved action per check type. Key = check type, value = action. Special key "_default" for fallback. */
|
|
401
|
-
checkTypeActions?: Record<string, "block" | "warn" | "shadow">;
|
|
402
|
-
/** Default action when no policy match */
|
|
403
|
-
defaultAction?: "block" | "warn" | "shadow";
|
|
404
|
-
/**
|
|
405
|
-
* Optional observer emit function. When provided, each check execution emits a
|
|
406
|
-
* toolchain.execution span (open before the check, close after) so the check is
|
|
407
|
-
* recorded on the agent axis. No-op when undefined (observer is optional).
|
|
408
|
-
* This is OBSERVATION ONLY — emitting spans never alters the returned results
|
|
409
|
-
* nor the resolved action, so workflow success/failure semantics are unchanged.
|
|
410
|
-
*/
|
|
411
|
-
observer?: ObserverEmitFn;
|
|
412
|
-
/** Parent span id (typically the enclosing agent.session run_id) for correlation. */
|
|
413
|
-
parentSpanId?: string;
|
|
414
|
-
/** Component id recorded on toolchain.execution spans (agent.component_id). */
|
|
415
|
-
componentId?: string;
|
|
416
|
-
/**
|
|
417
|
-
* Observability correlation ids propagated to spawned check subprocesses as
|
|
418
|
-
* AAAC_SESSION_ID / AAAC_TRACE_ID / AAAC_RUN_ID (#115). A check that spawns
|
|
419
|
-
* `git commit`/`git push` lets the resulting git `post-commit` hook attribute
|
|
420
|
-
* its promotion.* events back to this session. No-op when undefined.
|
|
421
|
-
*/
|
|
422
|
-
observabilityIds?: ObservabilityIds;
|
|
423
|
-
}
|
|
424
|
-
declare function runToolchainChecks(options: RunToolchainChecksOptions): Promise<ToolchainCheckResult[]>;
|
|
425
|
-
|
|
426
|
-
/**
|
|
427
|
-
* Workflow Runner — orchestrates a DSL workflow as a sequence of task executions
|
|
428
|
-
*
|
|
429
|
-
* Programmatic control flow that replaces LLM-driven step interpretation:
|
|
430
|
-
*
|
|
431
|
-
* 1. Load workflow contract (ordered steps)
|
|
432
|
-
* 2. Run plugin beforeWorkflow hooks
|
|
433
|
-
* 3. For each step:
|
|
434
|
-
* - delegate → call task-runner with followUp/retry recovery
|
|
435
|
-
* - gate → pause and wait for user input
|
|
436
|
-
* 4. Validate each result against handoff schema
|
|
437
|
-
* 5. Accumulate context between steps
|
|
438
|
-
* 6. Run plugin afterWorkflow hooks
|
|
439
|
-
*/
|
|
440
|
-
|
|
441
|
-
/**
|
|
442
|
-
* A factory that creates independent SdkAdapter instances.
|
|
443
|
-
* Used by runWorkflow to allocate one adapter per parallel step,
|
|
444
|
-
* avoiding session-level serialization in stateful SDK adapters.
|
|
445
|
-
*/
|
|
446
|
-
type SdkAdapterFactory = () => SdkAdapter;
|
|
447
|
-
/**
|
|
448
|
-
* Model-aware adapter factory. Accepts a model_class and returns an adapter
|
|
449
|
-
* configured for that capability level (possibly a different provider/model).
|
|
450
|
-
*/
|
|
451
|
-
type ModelAwareSdkAdapterFactory = (modelClass?: ModelClass) => SdkAdapter | Promise<SdkAdapter>;
|
|
452
|
-
/** Accepts either a single adapter (serial/shared) or a factory (parallel-safe). */
|
|
453
|
-
type AdapterOrFactory = SdkAdapter | SdkAdapterFactory | ModelAwareSdkAdapterFactory;
|
|
454
|
-
/** Specification for what a step receives from a dependency. */
|
|
455
|
-
interface ReceiveSpec {
|
|
456
|
-
/** The task id of the dependency step to receive from. If omitted, alias is used as task id. */
|
|
457
|
-
readonly from?: string;
|
|
458
|
-
/** JSONPath-like dotted path to extract from the step result (e.g. "$.changed_files"). Simplified: just use dot notation like "changed_files" or "checks_performed". If omitted, entire result is received. */
|
|
459
|
-
readonly path?: string;
|
|
460
|
-
}
|
|
461
|
-
interface DelegateStep {
|
|
462
|
-
readonly type: "delegate";
|
|
463
|
-
readonly task: string;
|
|
464
|
-
readonly from_agent: string;
|
|
465
|
-
readonly description: string;
|
|
466
|
-
readonly optional: boolean;
|
|
467
|
-
readonly max_retries: number;
|
|
468
|
-
readonly max_follow_ups?: number;
|
|
469
|
-
readonly depends_on?: readonly string[];
|
|
470
|
-
readonly instruction?: string;
|
|
471
|
-
readonly receives?: Record<string, ReceiveSpec>;
|
|
472
|
-
readonly retry?: {
|
|
473
|
-
readonly condition: string;
|
|
474
|
-
readonly fix_task: string;
|
|
475
|
-
readonly revalidate_task?: string;
|
|
476
|
-
};
|
|
477
|
-
}
|
|
478
|
-
interface GateStep {
|
|
479
|
-
readonly type: "gate";
|
|
480
|
-
readonly gate_kind: string;
|
|
481
|
-
readonly description: string;
|
|
482
|
-
readonly depends_on?: readonly string[];
|
|
483
|
-
}
|
|
484
|
-
/**
|
|
485
|
-
* Evaluate step — runs a task that returns a convergence-envelope, then either
|
|
486
|
-
* proceeds (verdict=pass) or loops back to `loop_to` with feedback injected
|
|
487
|
-
* (verdict=fail, iteration < max_iterations), or applies `on_exhausted`.
|
|
488
|
-
*/
|
|
489
|
-
interface EvaluateStep {
|
|
490
|
-
readonly type: "evaluate";
|
|
491
|
-
readonly task: string;
|
|
492
|
-
readonly from_agent: string;
|
|
493
|
-
readonly evaluator_agent?: string;
|
|
494
|
-
readonly description?: string;
|
|
495
|
-
readonly loop_to: string;
|
|
496
|
-
readonly max_iterations: number;
|
|
497
|
-
readonly inject_as?: string;
|
|
498
|
-
readonly on_exhausted?: "abort" | "fail_partial" | "escalate";
|
|
499
|
-
readonly depends_on?: readonly string[];
|
|
500
|
-
}
|
|
501
|
-
/**
|
|
502
|
-
* Payload returned by an evaluate task in a convergence-envelope handoff.
|
|
503
|
-
* The runtime reads `verdict` to decide whether to proceed or loop back.
|
|
504
|
-
*/
|
|
505
|
-
interface ConvergenceEnvelopePayload {
|
|
506
|
-
/** "pass" means quality gate passed; "fail" triggers a loop-back. */
|
|
507
|
-
readonly verdict: "pass" | "fail";
|
|
508
|
-
/** Human-readable feedback injected into the next iteration via `inject_as`. */
|
|
509
|
-
readonly feedback?: string;
|
|
510
|
-
}
|
|
511
|
-
/** Typed handoff envelope produced by an evaluate task. */
|
|
512
|
-
type ConvergenceEnvelope = HandoffInput<"convergence-envelope", ConvergenceEnvelopePayload>;
|
|
513
|
-
type WorkflowStep = DelegateStep | GateStep | EvaluateStep;
|
|
514
|
-
interface WorkflowContractLike {
|
|
515
|
-
readonly id: string;
|
|
516
|
-
readonly description: string;
|
|
517
|
-
readonly steps: readonly WorkflowStep[];
|
|
518
|
-
}
|
|
519
|
-
interface WorkflowRunOptions {
|
|
520
|
-
user_request: string;
|
|
521
|
-
/** Override max follow-up attempts per step (lightweight output-format correction). Default: 2 */
|
|
522
|
-
maxFollowUps?: number;
|
|
523
|
-
/** Override max full retry attempts per step. Default: from DSL step.max_retries */
|
|
524
|
-
maxRetries?: number;
|
|
525
|
-
/** Variables propagated to every TaskContext in the workflow (from WorkflowInvocation.context). */
|
|
526
|
-
variables?: Record<string, unknown>;
|
|
527
|
-
onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
|
|
528
|
-
onStepComplete?: (event: StepCompleteEvent) => void;
|
|
529
|
-
onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
|
|
530
|
-
/**
|
|
531
|
-
* Writable stream for real-time progress output during agent execution.
|
|
532
|
-
* Intermediate events from adapters are formatted and written here.
|
|
533
|
-
* Typical value: process.stderr.
|
|
534
|
-
*/
|
|
535
|
-
progressOutput?: {
|
|
536
|
-
write(chunk: string): unknown;
|
|
537
|
-
};
|
|
538
|
-
/**
|
|
539
|
-
* Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
|
|
540
|
-
* When undefined, no spans are emitted (observer is optional — no-op).
|
|
541
|
-
* Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
|
|
542
|
-
*/
|
|
543
|
-
observer?: ObserverEmitFn;
|
|
544
|
-
/**
|
|
545
|
-
* Optional toolchain-check observation config. When set together with `observer`,
|
|
546
|
-
* runWorkflow runs the configured toolchain checks AFTER the workflow body (a
|
|
547
|
-
* single post-run observation pass) and emits one toolchain.execution span per
|
|
548
|
-
* check, correlated to this run's agent.session span.
|
|
549
|
-
*
|
|
550
|
-
* OBSERVATION ONLY (non-destructive): the checks never alter the WorkflowResult
|
|
551
|
-
* — a failing check does not fail the workflow. `observer` and `parentSpanId`
|
|
552
|
-
* are injected by runWorkflow; callers supply `toolchainsPath` (+ optional
|
|
553
|
-
* artifactsPath/cwd/policy actions).
|
|
554
|
-
*/
|
|
555
|
-
toolchain?: RunToolchainChecksOptions;
|
|
556
|
-
/**
|
|
557
|
-
* In-process library tools to register with every task in this workflow.
|
|
558
|
-
* Passed through to each runTask() call. Adapters convert these to their
|
|
559
|
-
* native tool format (Claude MCP, OpenAI function tools, ADK tools).
|
|
560
|
-
*/
|
|
561
|
-
libraryTools?: LibraryToolRegistry;
|
|
562
|
-
/**
|
|
563
|
-
* Resolves adapter + model for execution envelopes (agent.session / agent.subagent).
|
|
564
|
-
* When undefined, envelopes omit adapter/model (observer spans lack gen_ai attrs).
|
|
565
|
-
*/
|
|
566
|
-
resolveModelMeta?: (modelClass?: ModelClass) => ResolvedModel;
|
|
567
|
-
}
|
|
568
|
-
/** Typed handoff envelope for workflow input. */
|
|
569
|
-
interface HandoffInput<TType extends string = string, TPayload = unknown> {
|
|
570
|
-
readonly type: TType;
|
|
571
|
-
readonly version?: number;
|
|
572
|
-
readonly payload: TPayload;
|
|
573
|
-
}
|
|
574
|
-
/**
|
|
575
|
-
* Standard runtime invocation envelope. SDK-specific options (openaiThreadId,
|
|
576
|
-
* sessionId, etc.) belong on the adapter constructor — not here.
|
|
577
|
-
*/
|
|
578
|
-
interface WorkflowInvocation<THandoffType extends string = string, TPayload = unknown> {
|
|
579
|
-
workflow: string;
|
|
580
|
-
/** Structured typed handoff input. Takes precedence over user_request if both are set. */
|
|
581
|
-
handoff?: HandoffInput<THandoffType, TPayload>;
|
|
582
|
-
/** Simple string input (convenience shorthand). */
|
|
583
|
-
user_request?: string;
|
|
584
|
-
runtime?: {
|
|
585
|
-
maxFollowUps?: number;
|
|
586
|
-
maxRetries?: number;
|
|
587
|
-
timeoutMs?: number;
|
|
588
|
-
readonly?: boolean;
|
|
589
|
-
dryRun?: boolean;
|
|
590
|
-
};
|
|
591
|
-
hooks?: {
|
|
592
|
-
onStepComplete?: (event: StepCompleteEvent) => void;
|
|
593
|
-
onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
|
|
594
|
-
onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
|
|
595
|
-
};
|
|
596
|
-
/**
|
|
597
|
-
* Writable stream for real-time progress output during agent execution.
|
|
598
|
-
* Intermediate events from adapters are formatted and written here.
|
|
599
|
-
* Typical value: process.stderr.
|
|
600
|
-
*/
|
|
601
|
-
progressOutput?: {
|
|
602
|
-
write(chunk: string): unknown;
|
|
603
|
-
};
|
|
604
|
-
context?: {
|
|
605
|
-
cwd?: string;
|
|
606
|
-
environment?: "local" | "ci" | "remote";
|
|
607
|
-
artifacts?: Record<string, string>;
|
|
608
|
-
variables?: Record<string, unknown>;
|
|
609
|
-
};
|
|
610
|
-
/**
|
|
611
|
-
* Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
|
|
612
|
-
* When undefined, no spans are emitted (observer is optional — no-op).
|
|
613
|
-
* Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
|
|
614
|
-
*/
|
|
615
|
-
observer?: ObserverEmitFn;
|
|
616
|
-
/**
|
|
617
|
-
* Optional toolchain-check observation config (see WorkflowRunOptions.toolchain).
|
|
618
|
-
* OBSERVATION ONLY — never changes the workflow outcome.
|
|
619
|
-
*/
|
|
620
|
-
toolchain?: RunToolchainChecksOptions;
|
|
621
|
-
/**
|
|
622
|
-
* In-process library tools to register with every task in this workflow.
|
|
623
|
-
* Created once per execution and shared across all steps.
|
|
624
|
-
*/
|
|
625
|
-
libraryTools?: LibraryToolRegistry;
|
|
626
|
-
/**
|
|
627
|
-
* Resolves adapter + model for execution envelopes. Injected by executeWorkflow;
|
|
628
|
-
* not typically set by external callers.
|
|
629
|
-
*/
|
|
630
|
-
resolveModelMeta?: (modelClass?: ModelClass) => ResolvedModel;
|
|
631
|
-
}
|
|
632
|
-
interface StepResult {
|
|
633
|
-
step_index: number;
|
|
634
|
-
task_id?: string;
|
|
635
|
-
gate_kind?: string;
|
|
636
|
-
outcome: TaskOutcome | {
|
|
637
|
-
status: "gate_approved";
|
|
638
|
-
} | {
|
|
639
|
-
status: "gate_rejected";
|
|
640
|
-
} | {
|
|
641
|
-
status: "skipped";
|
|
642
|
-
};
|
|
643
|
-
follow_ups_used: number;
|
|
644
|
-
retries_used: number;
|
|
645
|
-
elapsed_ms: number;
|
|
646
|
-
/** Resolved model_class for delegate/evaluate steps (from task registry). */
|
|
647
|
-
model_class?: ModelClass;
|
|
648
|
-
/** Concrete adapter name used for this step's LLM calls. */
|
|
649
|
-
adapter?: string;
|
|
650
|
-
/** Concrete model name used for this step's LLM calls. */
|
|
651
|
-
model?: string;
|
|
652
|
-
}
|
|
653
|
-
interface StepCompleteEvent {
|
|
654
|
-
workflow_id: string;
|
|
655
|
-
step_index: number;
|
|
656
|
-
step_type: "delegate" | "gate" | "evaluate";
|
|
657
|
-
task_id?: string;
|
|
658
|
-
gate_kind?: string;
|
|
659
|
-
outcome_status: string;
|
|
660
|
-
follow_ups_used: number;
|
|
661
|
-
retries_used: number;
|
|
662
|
-
elapsed_ms: number;
|
|
663
|
-
}
|
|
664
|
-
interface WorkflowResult {
|
|
665
|
-
workflow_id: string;
|
|
666
|
-
status: "completed" | "escalated" | "gate_rejected" | "error";
|
|
667
|
-
steps: StepResult[];
|
|
668
|
-
total_elapsed_ms: number;
|
|
669
|
-
escalation_reason?: string;
|
|
670
|
-
error_message?: string;
|
|
671
|
-
}
|
|
672
|
-
interface WorkflowRegistries {
|
|
673
|
-
workflowRegistry?: Record<string, WorkflowContractLike>;
|
|
674
|
-
taskRegistry?: Record<string, TaskContractLike>;
|
|
675
|
-
agentRegistry?: Record<string, AgentContractLike>;
|
|
676
|
-
handoffSchemas?: Record<string, z.ZodType>;
|
|
677
|
-
}
|
|
678
|
-
/** @deprecated Use the WorkflowInvocation overload for typed handoff input. */
|
|
679
|
-
declare function runWorkflow(adapter: AdapterOrFactory, workflowId: string, options: WorkflowRunOptions, registries?: WorkflowRegistries): Promise<WorkflowResult>;
|
|
680
|
-
/** Structured invocation with typed handoff envelope. */
|
|
681
|
-
declare function runWorkflow(adapter: AdapterOrFactory, invocation: WorkflowInvocation, registries?: WorkflowRegistries): Promise<WorkflowResult>;
|
|
682
|
-
declare function buildGateEvaluationPrompt(step: GateStep, priorContext: string): string;
|
|
683
|
-
declare function parseGateEvaluationResponse(response: string): boolean;
|
|
684
|
-
|
|
685
|
-
/**
|
|
686
|
-
* BoundResolver — runtime binding + policy resolution with per-agent isolation.
|
|
687
|
-
*
|
|
688
|
-
* Resolves artifact composition and guardrail/policy in one pass at runtime,
|
|
689
|
-
* producing a per-agent scoped ResolvedComponent. Reuses existing
|
|
690
|
-
* resolveArtifacts(), buildGuardrailContext(), and agent scope resolution.
|
|
691
|
-
*/
|
|
692
|
-
|
|
693
|
-
interface ArtifactBindingConfig {
|
|
694
|
-
source: string;
|
|
695
|
-
mappings?: Record<string, string>;
|
|
696
|
-
}
|
|
697
|
-
interface BoundResolveOptions {
|
|
698
|
-
/** Component identifier — used for cache keying. */
|
|
699
|
-
id: string;
|
|
700
|
-
/** Pre-resolved DSL (e.g. embedded from codegen). */
|
|
701
|
-
embeddedDsl?: Record<string, unknown>;
|
|
702
|
-
/** Path to DSL file — resolved via agent-contracts when no embeddedDsl. */
|
|
703
|
-
dslPath?: string;
|
|
704
|
-
/** Paths to software binding YAML files (guardrail_impl, etc.). */
|
|
705
|
-
bindingPaths?: string[];
|
|
706
|
-
/** Active guardrail policy name from DSL guardrail_policies. */
|
|
707
|
-
activeGuardrailPolicy?: string;
|
|
708
|
-
/** Artifact binding config — composed via resolveArtifacts() (lib/artifact-resolver). */
|
|
709
|
-
artifactBinding?: ArtifactBindingConfig;
|
|
710
|
-
/** Path substitutions for artifact binding. */
|
|
711
|
-
paths?: Record<string, string>;
|
|
712
|
-
/** Path to toolchain-contracts.yaml. */
|
|
713
|
-
toolchainContractsPath?: string;
|
|
714
|
-
}
|
|
715
|
-
interface ResolvedToolchain {
|
|
716
|
-
id: string;
|
|
717
|
-
kind: "library" | "cli" | "component";
|
|
718
|
-
description?: string;
|
|
719
|
-
module?: string;
|
|
720
|
-
command?: string;
|
|
721
|
-
cli_contract?: string;
|
|
722
|
-
component_contract?: string;
|
|
723
|
-
artifacts: {
|
|
724
|
-
consumes: string[];
|
|
725
|
-
produces: string[];
|
|
726
|
-
};
|
|
727
|
-
operations?: string[];
|
|
728
|
-
source: "toolchain-contracts" | "agent-contracts" | "merged";
|
|
729
|
-
}
|
|
730
|
-
interface ResolvedComponent {
|
|
731
|
-
id: string;
|
|
732
|
-
dsl: Record<string, unknown>;
|
|
733
|
-
registries: WorkflowRegistries;
|
|
734
|
-
guardrails: {
|
|
735
|
-
perAgent: Map<string, GuardrailRuleData>;
|
|
736
|
-
};
|
|
737
|
-
diagnostics: Array<{
|
|
738
|
-
path?: string;
|
|
739
|
-
message: string;
|
|
740
|
-
severity?: string;
|
|
741
|
-
}>;
|
|
742
|
-
toolchains?: Record<string, ResolvedToolchain>;
|
|
743
|
-
toolchainsByAgent?: Map<string, ResolvedToolchain[]>;
|
|
744
|
-
}
|
|
745
|
-
/**
|
|
746
|
-
* Effective guardrail IDs for an agent: entity-side bindings ∪ scope-side bindings.
|
|
747
|
-
*/
|
|
748
|
-
declare function getEffectiveGuardrailIds(dsl: Record<string, unknown>, agentId: string): Set<string>;
|
|
749
|
-
declare function guardrailContextToRuleData(ctx: GuardrailContext, effectiveIds?: Set<string>): GuardrailRuleData;
|
|
750
|
-
declare function buildPerAgentGuardrails(dsl: Record<string, unknown>, guardrailCtx: GuardrailContext): Map<string, GuardrailRuleData>;
|
|
751
|
-
declare function deriveToolchainsForAgents(dsl: Record<string, unknown>, toolchains: Record<string, ResolvedToolchain>): Map<string, ResolvedToolchain[]>;
|
|
752
|
-
declare class BoundResolver {
|
|
753
|
-
private readonly cache;
|
|
754
|
-
/**
|
|
755
|
-
* Resolve binding + policy in one pass. Results are cached by component id.
|
|
756
|
-
*/
|
|
757
|
-
resolve(opts: BoundResolveOptions): Promise<ResolvedComponent>;
|
|
758
|
-
/** Clear cached components (e.g. for testing). */
|
|
759
|
-
clearCache(): void;
|
|
760
|
-
}
|
|
761
|
-
/** Get guardrail rules for a specific agent from a ResolvedComponent. */
|
|
762
|
-
declare function getGuardrailRulesForAgent(component: ResolvedComponent, agentId: string): GuardrailRuleData | undefined;
|
|
763
|
-
|
|
764
309
|
/**
|
|
765
310
|
* Candidate Agents — backend-neutral bridge for LLM-internal routing (model B)
|
|
766
311
|
*
|
|
@@ -786,7 +331,7 @@ interface CandidateAgent {
|
|
|
786
331
|
name: string;
|
|
787
332
|
/** When to use this agent — the routing hint shown to the delegating LLM. */
|
|
788
333
|
description: string;
|
|
789
|
-
/** The agent's system prompt
|
|
334
|
+
/** The agent's system prompt — everything the DSL declares about its work. */
|
|
790
335
|
prompt: string;
|
|
791
336
|
/** Optional allowed tool names (omit to inherit from the parent agent). */
|
|
792
337
|
tools?: string[];
|
|
@@ -794,11 +339,26 @@ interface CandidateAgent {
|
|
|
794
339
|
model?: string;
|
|
795
340
|
}
|
|
796
341
|
/**
|
|
797
|
-
* Render an agent contract into its system-prompt string: the
|
|
798
|
-
*
|
|
342
|
+
* Render an agent contract into its system-prompt string: everything the DSL
|
|
343
|
+
* declares about how the agent must work.
|
|
799
344
|
*
|
|
800
|
-
*
|
|
801
|
-
*
|
|
345
|
+
* The ONE renderer of a declared agent for every Claude surface — the in-process
|
|
346
|
+
* system prompt (`buildSplitTaskPrompt`), the SDK candidate agents
|
|
347
|
+
* (`buildCandidateAgents`), and the Claude Code subagent body
|
|
348
|
+
* (`claude-materialize/agent-render.ts`) — so one DSL agent cannot be described
|
|
349
|
+
* differently depending on which of them a prompt came through.
|
|
350
|
+
*
|
|
351
|
+
* That is also why the sections below are not a subset. It rendered role,
|
|
352
|
+
* responsibilities, constraints and rules and stopped there, so an agent's
|
|
353
|
+
* anti-patterns, escalation criteria, authority boundaries, audit checklist and
|
|
354
|
+
* prose sections reached no Claude surface at all while the Cursor binding
|
|
355
|
+
* rendered every one of them: the dev-team architect's "issue-fix AC Derivation"
|
|
356
|
+
* procedure was in the Cursor prompt and in no Claude prompt (#349). Nothing
|
|
357
|
+
* failed — a prompt that is missing an instruction is still a valid prompt.
|
|
358
|
+
*
|
|
359
|
+
* Permissions are NOT here: they are the file-form's `permissionSections`, which
|
|
360
|
+
* an agent receiving only its own `.claude/agents/*.md` needs and an in-process
|
|
361
|
+
* agent has enforced around it by the runtime.
|
|
802
362
|
*/
|
|
803
363
|
declare function renderAgentSystemPrompt(agent: AgentContractLike): string;
|
|
804
364
|
interface BuildCandidateAgentsOptions {
|
|
@@ -809,7 +369,17 @@ interface BuildCandidateAgentsOptions {
|
|
|
809
369
|
* candidates to these agent ids. Omit to allow every non-entry agent.
|
|
810
370
|
*/
|
|
811
371
|
allowedAgentIds?: readonly string[];
|
|
812
|
-
|
|
372
|
+
/**
|
|
373
|
+
* Each agent's effective tool grant — `ComponentScope.toolsByAgent`
|
|
374
|
+
* (component-scope.ts), the one place `tools[*].invokable_by`,
|
|
375
|
+
* `agents[*].can_execute_tools` and the toolchains derived for the agent are
|
|
376
|
+
* resolved into names. Read, not recomputed: this function used to merge
|
|
377
|
+
* `can_execute_tools` with the derived toolchain ids itself, which is the
|
|
378
|
+
* same statement in a second place — and the two read `can_execute_tools` in
|
|
379
|
+
* different namespaces until #337 made them agree. An agent absent from the
|
|
380
|
+
* map gets no `tools`, i.e. inherits the parent agent's.
|
|
381
|
+
*/
|
|
382
|
+
toolsByAgent?: Map<string, string[]>;
|
|
813
383
|
}
|
|
814
384
|
/**
|
|
815
385
|
* Build the candidate sub-agent set from an agent registry.
|
|
@@ -858,6 +428,63 @@ interface AgentContractLike {
|
|
|
858
428
|
* isolated tool set instead of inheriting the parent agent's tools.
|
|
859
429
|
*/
|
|
860
430
|
readonly can_execute_tools?: readonly string[];
|
|
431
|
+
/**
|
|
432
|
+
* The agent is the entry/orchestrator role: it dispatches work to other
|
|
433
|
+
* agents and is never itself a delegation target. Materializing it as a
|
|
434
|
+
* Claude Code subagent would contradict `buildCandidateAgents`, which
|
|
435
|
+
* excludes the entry agent from the candidate set.
|
|
436
|
+
*/
|
|
437
|
+
readonly dispatch_only?: boolean;
|
|
438
|
+
/**
|
|
439
|
+
* Declared artifact and handoff permissions. Optional like every other
|
|
440
|
+
* non-universal field on this duck-typed contract; `buildAgentRegistry`
|
|
441
|
+
* always populates them, and absent is indistinguishable from empty (unlike
|
|
442
|
+
* `can_invoke_agents`, where presence itself restricts the candidate set).
|
|
443
|
+
*/
|
|
444
|
+
readonly can_read_artifacts?: readonly string[];
|
|
445
|
+
readonly can_write_artifacts?: readonly string[];
|
|
446
|
+
readonly can_return_handoffs?: readonly string[];
|
|
447
|
+
readonly can_perform_validations?: readonly string[];
|
|
448
|
+
/**
|
|
449
|
+
* The rest of what a DSL agent declares about how it must work: the failure
|
|
450
|
+
* shapes it must avoid, when it must stop and escalate, the decisions it owns,
|
|
451
|
+
* the checklist an audit of its output runs, and its free-form prose sections.
|
|
452
|
+
*
|
|
453
|
+
* They are on this contract for the same reason `rules` is — they are
|
|
454
|
+
* mandatory instructions to the agent, and a renderer cannot carry what the
|
|
455
|
+
* contract does not hold. None of them reached any Claude surface while the
|
|
456
|
+
* Cursor binding rendered all five, so one DSL produced two harnesses telling
|
|
457
|
+
* an agent different things about its own obligations (#349).
|
|
458
|
+
*
|
|
459
|
+
* `x-authority` / `x-audit-checklist` are `x-` prefixed in the DSL document
|
|
460
|
+
* and plain here, as `x-optional` / `x-instruction` / `x-receives` already are
|
|
461
|
+
* on `DelegateStep`: the prefix is a fact about the document, not about this
|
|
462
|
+
* runtime's interfaces (see `buildWorkflowStep`, `dsl-context.ts`).
|
|
463
|
+
*/
|
|
464
|
+
readonly anti_patterns?: readonly string[];
|
|
465
|
+
readonly escalation_criteria?: readonly {
|
|
466
|
+
readonly condition: string;
|
|
467
|
+
readonly action: string;
|
|
468
|
+
}[];
|
|
469
|
+
readonly authority?: {
|
|
470
|
+
readonly can_decide?: readonly string[];
|
|
471
|
+
readonly cannot_decide?: readonly string[];
|
|
472
|
+
};
|
|
473
|
+
readonly audit_checklist?: readonly {
|
|
474
|
+
readonly section: string;
|
|
475
|
+
readonly checks: readonly string[];
|
|
476
|
+
}[];
|
|
477
|
+
/**
|
|
478
|
+
* Already expanded: a `sections[]` entry may name a list the DSL holds
|
|
479
|
+
* (`list: agents`) rather than carry prose, and resolving that needs the whole
|
|
480
|
+
* document, which `buildAgentRegistry` has and a renderer taking one agent
|
|
481
|
+
* does not. `expandDslSection` (@aaac/contracts) is the one expansion, shared
|
|
482
|
+
* with the Cursor binding.
|
|
483
|
+
*/
|
|
484
|
+
readonly sections?: readonly {
|
|
485
|
+
readonly title: string;
|
|
486
|
+
readonly content: string;
|
|
487
|
+
}[];
|
|
861
488
|
}
|
|
862
489
|
interface TaskContractLike {
|
|
863
490
|
readonly id: string;
|
|
@@ -865,7 +492,7 @@ interface TaskContractLike {
|
|
|
865
492
|
readonly target_agent: string;
|
|
866
493
|
readonly result_handoff: string;
|
|
867
494
|
readonly completion_criteria: readonly string[];
|
|
868
|
-
readonly model_class?:
|
|
495
|
+
readonly model_class?: ModelClass;
|
|
869
496
|
/**
|
|
870
497
|
* When true, the adapter may enable Dynamic Workflow tools (e.g. Claude's
|
|
871
498
|
* Workflow tool) so the agent can internally parallelise sub-tasks.
|
|
@@ -1131,18 +758,6 @@ declare function zodSchemaToPromptDescription(schema: z.ZodType): string;
|
|
|
1131
758
|
* nested objects and arrays up to a configurable depth.
|
|
1132
759
|
*/
|
|
1133
760
|
declare function zodSchemaToYamlExample(schema: z.ZodType, maxDepth?: number): string;
|
|
1134
|
-
/**
|
|
1135
|
-
* Duck-type check: does `value` look like a ProjectNavigationIndex?
|
|
1136
|
-
* Requires a `system` object and an `artifacts` record.
|
|
1137
|
-
*/
|
|
1138
|
-
declare function isNavigationIndex(value: unknown): value is Record<string, unknown>;
|
|
1139
|
-
/**
|
|
1140
|
-
* Render the Level 1 navigation index as a compact prompt section — a
|
|
1141
|
-
* human-readable SUMMARY of artifacts (type, authority, edit policy, key
|
|
1142
|
-
* relations and owning agents), NOT a raw JSON dump. Gives the agent a map of
|
|
1143
|
-
* the project's artifacts so it can navigate before acting.
|
|
1144
|
-
*/
|
|
1145
|
-
declare function renderNavigationIndexPrompt(navigationIndex: Record<string, unknown>): string;
|
|
1146
761
|
/** Collect analyzer.* tool ids from a wired library tool registry. */
|
|
1147
762
|
declare function collectAnalyzerToolIds(registry?: LibraryToolRegistry): string[];
|
|
1148
763
|
/**
|
|
@@ -1170,8 +785,9 @@ interface PromptBuilderOptions {
|
|
|
1170
785
|
/**
|
|
1171
786
|
* Build a prompt split into static (cacheable) and dynamic (per-invocation) parts.
|
|
1172
787
|
*
|
|
1173
|
-
* Static (system):
|
|
1174
|
-
* Completion Criteria, Output Format / Schema, Recovery
|
|
788
|
+
* Static (system): the agent's declaration (`renderAgentSystemPrompt`), Task
|
|
789
|
+
* description, Completion Criteria, Output Format / Schema, Recovery
|
|
790
|
+
* Instructions.
|
|
1175
791
|
*
|
|
1176
792
|
* Dynamic (user): User Request, Handoff Input, Prior Context,
|
|
1177
793
|
* Relevant Files, Acceptance Criteria.
|
|
@@ -1190,6 +806,12 @@ declare function runTask(adapter: SdkAdapter, taskId: string, context: TaskConte
|
|
|
1190
806
|
revalidate_task?: string;
|
|
1191
807
|
};
|
|
1192
808
|
libraryTools?: LibraryToolRegistry;
|
|
809
|
+
/**
|
|
810
|
+
* Each agent's effective tool grant, from the executing component's
|
|
811
|
+
* `ComponentScope.toolsByAgent` (#338). Travels with `agentRegistry`
|
|
812
|
+
* because the two are consumed together, by `buildCandidateAgents` below.
|
|
813
|
+
*/
|
|
814
|
+
toolsByAgent?: Map<string, string[]>;
|
|
1193
815
|
}): Promise<TaskRunResult>;
|
|
1194
816
|
|
|
1195
|
-
export {
|
|
817
|
+
export { runTask as $, type AdapterSendOptions as A, emitIterationClose as B, type CacheConfig as C, emitIterationMetric as D, type EnvelopeParams as E, emitIterationOpen as F, emitLlmTurnClose as G, emitLlmTurnOpen as H, InMemoryStore as I, emitSessionClose as J, emitSessionOpen as K, type LibraryToolRegistry as L, type MemoryRef as M, emitSubagentClose as N, type ObserverEmitFn as O, type PromptBuilderOptions as P, emitSubagentOpen as Q, type RetryDecision as R, type SdkAdapter as S, type TokenUsage as T, emitToolExecClose as U, emitToolExecOpen as V, emitToolchainClose as W, emitToolchainOpen as X, extractStructuredResult as Y, renderAgentSystemPrompt as Z, renderAnalyzerExplorationMandatePrompt as _, type AgentExecutionRequest as a, serializeObserverEmit as a0, shouldInjectAnalyzerExplorationMandate as a1, zodSchemaToPromptDescription as a2, zodSchemaToYamlExample as a3, type SdkFunctionTool as b, type ObservabilityIds as c, type TaskOutcome as d, type TaskContractLike as e, type AgentContractLike as f, type TaskContext as g, type MemoryStore as h, type TaskRunResult as i, type AgentProgressEvent as j, type CandidateAgent as k, type InnerSpanOptions as l, type LibraryToolDefinition as m, OBSERVABILITY_ENV_VARS as n, type SplitPrompt as o, type TaskRunOptions as p, buildCandidateAgents as q, buildObservabilityEnv as r, buildRetryFollowUp as s, buildSdkFunctionTools as t, buildSplitTaskPrompt as u, buildTaskPrompt as v, collectAnalyzerToolIds as w, createExecutionEnvelope as x, createLibraryToolRegistry as y, createRegistryFromSdkTools as z };
|