@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.
Files changed (71) hide show
  1. package/README.md +6 -11
  2. package/dist/adapters/adk-sdk.d.ts +3 -3
  3. package/dist/adapters/adk-sdk.js +6 -8
  4. package/dist/adapters/adk-sdk.js.map +1 -1
  5. package/dist/adapters/claude-agent-sdk.d.ts +3 -3
  6. package/dist/adapters/claude-agent-sdk.js +22 -23
  7. package/dist/adapters/claude-agent-sdk.js.map +1 -1
  8. package/dist/adapters/mock.d.ts +2 -3
  9. package/dist/adapters/openai-agents-sdk.d.ts +3 -3
  10. package/dist/adapters/openai-agents-sdk.js +6 -5
  11. package/dist/adapters/openai-agents-sdk.js.map +1 -1
  12. package/dist/chunk-2INQL5TG.js +298 -0
  13. package/dist/chunk-2INQL5TG.js.map +1 -0
  14. package/dist/chunk-3CLWG72V.js +47 -0
  15. package/dist/chunk-3CLWG72V.js.map +1 -0
  16. package/dist/chunk-3DDB34BU.js +237 -0
  17. package/dist/chunk-3DDB34BU.js.map +1 -0
  18. package/dist/chunk-ABXDSTUV.js +685 -0
  19. package/dist/chunk-ABXDSTUV.js.map +1 -0
  20. package/dist/{chunk-3H3PVPPF.js → chunk-F5R46S7I.js} +151 -204
  21. package/dist/chunk-F5R46S7I.js.map +1 -0
  22. package/dist/chunk-FKAI54OM.js +234 -0
  23. package/dist/chunk-FKAI54OM.js.map +1 -0
  24. package/dist/chunk-KTVMMG33.js +1111 -0
  25. package/dist/chunk-KTVMMG33.js.map +1 -0
  26. package/dist/chunk-MSVIEEGR.js +269 -0
  27. package/dist/chunk-MSVIEEGR.js.map +1 -0
  28. package/dist/chunk-VJXGCWSZ.js +36 -0
  29. package/dist/chunk-VJXGCWSZ.js.map +1 -0
  30. package/dist/claude-bundles/full.js +311 -309
  31. package/dist/claude-bundles/lean.js +6 -6
  32. package/dist/claude-bundles/prompt.js +17 -0
  33. package/dist/generator/index.d.ts +2 -2
  34. package/dist/generator/index.js +8 -7
  35. package/dist/guardrail-hooks-CB23nhZV.d.ts +202 -0
  36. package/dist/hook-protocol-CFnNudiV.d.ts +96 -0
  37. package/dist/hooks-lite-CoWWnCRH.d.ts +428 -0
  38. package/dist/index-BlSepCSZ.d.ts +296 -0
  39. package/dist/index.d.ts +785 -105
  40. package/dist/index.js +2235 -659
  41. package/dist/index.js.map +1 -1
  42. package/dist/lib/claude-native/hooks-lite.d.ts +3 -26
  43. package/dist/lib/claude-native/hooks-lite.js +18 -36
  44. package/dist/lib/claude-native/hooks-prompt.d.ts +5 -0
  45. package/dist/lib/claude-native/hooks-prompt.js +33 -0
  46. package/dist/lib/claude-native/hooks-prompt.js.map +1 -0
  47. package/dist/lib/claude-native/index.d.ts +56 -214
  48. package/dist/lib/claude-native/index.js +79 -280
  49. package/dist/lib/claude-native/index.js.map +1 -1
  50. package/dist/{navigation-context-D_E1NIUf.d.ts → navigation-context-B-RpUg3_.d.ts} +1 -1
  51. package/dist/navigation-index-prompt-CbrS5laO.d.ts +43 -0
  52. package/dist/{task-runner-CLc8iTzy.d.ts → task-runner-GWoI7_71.d.ts} +100 -478
  53. package/dist/workspace-user-prompt-submit-D11Iu0zO.d.ts +269 -0
  54. package/package.json +15 -6
  55. package/dist/chunk-3H3PVPPF.js.map +0 -1
  56. package/dist/chunk-DBM5XN67.js +0 -354
  57. package/dist/chunk-DBM5XN67.js.map +0 -1
  58. package/dist/chunk-KXGUWBGK.js +0 -370
  59. package/dist/chunk-KXGUWBGK.js.map +0 -1
  60. package/dist/chunk-LDCQZPDG.js +0 -11
  61. package/dist/chunk-LDCQZPDG.js.map +0 -1
  62. package/dist/chunk-N4KNGDYY.js +0 -1963
  63. package/dist/chunk-N4KNGDYY.js.map +0 -1
  64. package/dist/chunk-NMX4C6LC.js +0 -332
  65. package/dist/chunk-NMX4C6LC.js.map +0 -1
  66. package/dist/chunk-QVH5KKBR.js +0 -374
  67. package/dist/chunk-QVH5KKBR.js.map +0 -1
  68. package/dist/context-DKkamYX_.d.ts +0 -31
  69. package/dist/guardrail-hooks-slK-z0Dz.d.ts +0 -83
  70. package/dist/index-LqEvaRk-.d.ts +0 -299
  71. package/dist/workspace-pre-tool-use-C6nidc0q.d.ts +0 -333
@@ -1,6 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { G as GuardrailContext } from './context-DKkamYX_.js';
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 (role / purpose / responsibilities / constraints / rules). */
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 static
798
- * Role / Responsibilities / Constraints / Rules sections.
342
+ * Render an agent contract into its system-prompt string: everything the DSL
343
+ * declares about how the agent must work.
799
344
  *
800
- * Shared by `buildSplitTaskPrompt` (entry agent system prompt) and
801
- * `buildCandidateAgents` (each candidate's `prompt`) so both stay in sync.
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
- toolchainsByAgent?: Map<string, ResolvedToolchain[]>;
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?: "fast" | "standard" | "thinking";
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): Role, Responsibilities, Constraints, Rules, Task description,
1174
- * Completion Criteria, Output Format / Schema, Recovery Instructions.
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 { type ToolchainManifest as $, type AdapterSendOptions as A, type BoundResolveOptions as B, type CacheConfig as C, type DelegateStep as D, type EnvelopeParams as E, type ModelResolver as F, type GateStep as G, type HandoffInput as H, InMemoryStore as I, type ModelResolverOptions as J, OBSERVABILITY_ENV_VARS as K, type LibraryToolRegistry as L, type MemoryRef as M, type ObservabilityIds as N, type ObserverEmitFn as O, type PromptBuilderOptions as P, type ReceiveSpec as Q, type ResolvedComponent as R, type SdkAdapter as S, type TokenUsage as T, type ResolvedModel as U, type RetryDecision as V, type WorkflowResult as W, type SdkAdapterFactory as X, type SplitPrompt as Y, type TaskRunOptions as Z, type ToolchainCheckResult as _, type AgentExecutionRequest as a, ToolchainManifestSchema as a0, type WorkflowContractLike as a1, type WorkflowInvocation as a2, type WorkflowRunOptions as a3, type WorkflowStep as a4, buildCandidateAgents as a5, buildGateEvaluationPrompt as a6, buildObservabilityEnv as a7, buildPerAgentGuardrails as a8, buildRetryFollowUp as a9, isNavigationIndex as aA, parseGateEvaluationResponse as aB, renderAgentSystemPrompt as aC, renderAnalyzerExplorationMandatePrompt as aD, renderNavigationIndexPrompt as aE, runTask as aF, runToolchainChecks as aG, runWorkflow as aH, serializeObserverEmit as aI, shouldInjectAnalyzerExplorationMandate as aJ, zodSchemaToPromptDescription as aK, zodSchemaToYamlExample as aL, buildSdkFunctionTools as aa, buildSplitTaskPrompt as ab, buildTaskPrompt as ac, collectAnalyzerToolIds as ad, createExecutionEnvelope as ae, createLibraryToolRegistry as af, createModelResolver as ag, createRegistryFromSdkTools as ah, deriveToolchainsForAgents as ai, emitIterationClose as aj, emitIterationMetric as ak, emitIterationOpen as al, emitLlmTurnClose as am, emitLlmTurnOpen as an, emitSessionClose as ao, emitSessionOpen as ap, emitSubagentClose as aq, emitSubagentOpen as ar, emitToolExecClose as as, emitToolExecOpen as at, emitToolchainClose as au, emitToolchainOpen as av, extractStructuredResult as aw, getEffectiveGuardrailIds as ax, getGuardrailRulesForAgent as ay, guardrailContextToRuleData as az, type SdkFunctionTool as b, type TaskContext as c, type TaskOutcome as d, type AgentContractLike as e, type TaskContractLike as f, type WorkflowRegistries as g, type StepCompleteEvent as h, type StepResult as i, type MemoryStore as j, type ArtifactBindingConfig as k, type RunToolchainChecksOptions as l, type ModelMappingConfig as m, type TaskRunResult as n, type ResolvedToolchain as o, type LibraryToolDefinition as p, type AdapterOrFactory as q, type AgentProgressEvent as r, BoundResolver as s, type CandidateAgent as t, type ConvergenceEnvelope as u, type ConvergenceEnvelopePayload as v, type EvaluateStep as w, type InnerSpanOptions as x, type ModelAwareSdkAdapterFactory as y, type ModelClass as z };
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 };