@aaac/runtime 0.1.55 → 0.2.1
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 +2189 -634
- 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-DfIEorkU.d.ts → task-runner-GWoI7_71.d.ts} +100 -493
- 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,475 +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,
|
|
452
|
-
/**
|
|
453
|
-
* Agent the step runs as (a task's `target_agent`). Guardrail hooks are fixed at
|
|
454
|
-
* adapter construction, so an agent-scoped factory returns a distinct adapter per
|
|
455
|
-
* agent (#269). Ignored by factories that do not scope guardrails.
|
|
456
|
-
*/
|
|
457
|
-
agentId?: string) => SdkAdapter | Promise<SdkAdapter>;
|
|
458
|
-
/** Accepts either a single adapter (serial/shared) or a factory (parallel-safe). */
|
|
459
|
-
type AdapterOrFactory = SdkAdapter | SdkAdapterFactory | ModelAwareSdkAdapterFactory;
|
|
460
|
-
/** Specification for what a step receives from a dependency. */
|
|
461
|
-
interface ReceiveSpec {
|
|
462
|
-
/** The task id of the dependency step to receive from. If omitted, alias is used as task id. */
|
|
463
|
-
readonly from?: string;
|
|
464
|
-
/** 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. */
|
|
465
|
-
readonly path?: string;
|
|
466
|
-
}
|
|
467
|
-
interface DelegateStep {
|
|
468
|
-
readonly type: "delegate";
|
|
469
|
-
readonly task: string;
|
|
470
|
-
readonly from_agent: string;
|
|
471
|
-
readonly description: string;
|
|
472
|
-
readonly optional: boolean;
|
|
473
|
-
readonly max_retries: number;
|
|
474
|
-
readonly max_follow_ups?: number;
|
|
475
|
-
readonly depends_on?: readonly string[];
|
|
476
|
-
readonly instruction?: string;
|
|
477
|
-
readonly receives?: Record<string, ReceiveSpec>;
|
|
478
|
-
readonly retry?: {
|
|
479
|
-
readonly condition: string;
|
|
480
|
-
readonly fix_task: string;
|
|
481
|
-
readonly revalidate_task?: string;
|
|
482
|
-
};
|
|
483
|
-
}
|
|
484
|
-
interface GateStep {
|
|
485
|
-
readonly type: "gate";
|
|
486
|
-
readonly gate_kind: string;
|
|
487
|
-
readonly description: string;
|
|
488
|
-
readonly depends_on?: readonly string[];
|
|
489
|
-
}
|
|
490
|
-
/**
|
|
491
|
-
* Evaluate step — runs a task that returns a convergence-envelope, then either
|
|
492
|
-
* proceeds (verdict=pass) or loops back to `loop_to` with feedback injected
|
|
493
|
-
* (verdict=fail, iteration < max_iterations), or applies `on_exhausted`.
|
|
494
|
-
*/
|
|
495
|
-
interface EvaluateStep {
|
|
496
|
-
readonly type: "evaluate";
|
|
497
|
-
readonly task: string;
|
|
498
|
-
readonly from_agent: string;
|
|
499
|
-
readonly evaluator_agent?: string;
|
|
500
|
-
readonly description?: string;
|
|
501
|
-
readonly loop_to: string;
|
|
502
|
-
readonly max_iterations: number;
|
|
503
|
-
readonly inject_as?: string;
|
|
504
|
-
readonly on_exhausted?: "abort" | "fail_partial" | "escalate";
|
|
505
|
-
readonly depends_on?: readonly string[];
|
|
506
|
-
}
|
|
507
|
-
/**
|
|
508
|
-
* Payload returned by an evaluate task in a convergence-envelope handoff.
|
|
509
|
-
* The runtime reads `verdict` to decide whether to proceed or loop back.
|
|
510
|
-
*/
|
|
511
|
-
interface ConvergenceEnvelopePayload {
|
|
512
|
-
/** "pass" means quality gate passed; "fail" triggers a loop-back. */
|
|
513
|
-
readonly verdict: "pass" | "fail";
|
|
514
|
-
/** Human-readable feedback injected into the next iteration via `inject_as`. */
|
|
515
|
-
readonly feedback?: string;
|
|
516
|
-
}
|
|
517
|
-
/** Typed handoff envelope produced by an evaluate task. */
|
|
518
|
-
type ConvergenceEnvelope = HandoffInput<"convergence-envelope", ConvergenceEnvelopePayload>;
|
|
519
|
-
type WorkflowStep = DelegateStep | GateStep | EvaluateStep;
|
|
520
|
-
interface WorkflowContractLike {
|
|
521
|
-
readonly id: string;
|
|
522
|
-
readonly description: string;
|
|
523
|
-
readonly steps: readonly WorkflowStep[];
|
|
524
|
-
}
|
|
525
|
-
interface WorkflowRunOptions {
|
|
526
|
-
user_request: string;
|
|
527
|
-
/** Override max follow-up attempts per step (lightweight output-format correction). Default: 2 */
|
|
528
|
-
maxFollowUps?: number;
|
|
529
|
-
/** Override max full retry attempts per step. Default: from DSL step.max_retries */
|
|
530
|
-
maxRetries?: number;
|
|
531
|
-
/** Variables propagated to every TaskContext in the workflow (from WorkflowInvocation.context). */
|
|
532
|
-
variables?: Record<string, unknown>;
|
|
533
|
-
onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
|
|
534
|
-
onStepComplete?: (event: StepCompleteEvent) => void;
|
|
535
|
-
onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
|
|
536
|
-
/**
|
|
537
|
-
* Writable stream for real-time progress output during agent execution.
|
|
538
|
-
* Intermediate events from adapters are formatted and written here.
|
|
539
|
-
* Typical value: process.stderr.
|
|
540
|
-
*/
|
|
541
|
-
progressOutput?: {
|
|
542
|
-
write(chunk: string): unknown;
|
|
543
|
-
};
|
|
544
|
-
/**
|
|
545
|
-
* Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
|
|
546
|
-
* When undefined, no spans are emitted (observer is optional — no-op).
|
|
547
|
-
* Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
|
|
548
|
-
*/
|
|
549
|
-
observer?: ObserverEmitFn;
|
|
550
|
-
/**
|
|
551
|
-
* Optional toolchain-check observation config. When set together with `observer`,
|
|
552
|
-
* runWorkflow runs the configured toolchain checks AFTER the workflow body (a
|
|
553
|
-
* single post-run observation pass) and emits one toolchain.execution span per
|
|
554
|
-
* check, correlated to this run's agent.session span.
|
|
555
|
-
*
|
|
556
|
-
* OBSERVATION ONLY (non-destructive): the checks never alter the WorkflowResult
|
|
557
|
-
* — a failing check does not fail the workflow. `observer` and `parentSpanId`
|
|
558
|
-
* are injected by runWorkflow; callers supply `toolchainsPath` (+ optional
|
|
559
|
-
* artifactsPath/cwd/policy actions).
|
|
560
|
-
*/
|
|
561
|
-
toolchain?: RunToolchainChecksOptions;
|
|
562
|
-
/**
|
|
563
|
-
* In-process library tools to register with every task in this workflow.
|
|
564
|
-
* Passed through to each runTask() call. Adapters convert these to their
|
|
565
|
-
* native tool format (Claude MCP, OpenAI function tools, ADK tools).
|
|
566
|
-
*/
|
|
567
|
-
libraryTools?: LibraryToolRegistry;
|
|
568
|
-
/**
|
|
569
|
-
* Resolves adapter + model for execution envelopes (agent.session / agent.subagent).
|
|
570
|
-
* When undefined, envelopes omit adapter/model (observer spans lack gen_ai attrs).
|
|
571
|
-
*/
|
|
572
|
-
resolveModelMeta?: (modelClass?: ModelClass) => ResolvedModel;
|
|
573
|
-
/**
|
|
574
|
-
* Request each step's adapter from the factory scoped to the step's agent, so
|
|
575
|
-
* per-agent guardrails apply to the agent actually doing the work (#269). Set by
|
|
576
|
-
* executeWorkflow when the resolved component has per-agent guardrail rules;
|
|
577
|
-
* without it, adapters are shared exactly as before.
|
|
578
|
-
*/
|
|
579
|
-
perAgentAdapters?: boolean;
|
|
580
|
-
}
|
|
581
|
-
/** Typed handoff envelope for workflow input. */
|
|
582
|
-
interface HandoffInput<TType extends string = string, TPayload = unknown> {
|
|
583
|
-
readonly type: TType;
|
|
584
|
-
readonly version?: number;
|
|
585
|
-
readonly payload: TPayload;
|
|
586
|
-
}
|
|
587
|
-
/**
|
|
588
|
-
* Standard runtime invocation envelope. SDK-specific options (openaiThreadId,
|
|
589
|
-
* sessionId, etc.) belong on the adapter constructor — not here.
|
|
590
|
-
*/
|
|
591
|
-
interface WorkflowInvocation<THandoffType extends string = string, TPayload = unknown> {
|
|
592
|
-
workflow: string;
|
|
593
|
-
/** Structured typed handoff input. Takes precedence over user_request if both are set. */
|
|
594
|
-
handoff?: HandoffInput<THandoffType, TPayload>;
|
|
595
|
-
/** Simple string input (convenience shorthand). */
|
|
596
|
-
user_request?: string;
|
|
597
|
-
runtime?: {
|
|
598
|
-
maxFollowUps?: number;
|
|
599
|
-
maxRetries?: number;
|
|
600
|
-
timeoutMs?: number;
|
|
601
|
-
readonly?: boolean;
|
|
602
|
-
dryRun?: boolean;
|
|
603
|
-
};
|
|
604
|
-
hooks?: {
|
|
605
|
-
onStepComplete?: (event: StepCompleteEvent) => void;
|
|
606
|
-
onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
|
|
607
|
-
onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
|
|
608
|
-
};
|
|
609
|
-
/**
|
|
610
|
-
* Writable stream for real-time progress output during agent execution.
|
|
611
|
-
* Intermediate events from adapters are formatted and written here.
|
|
612
|
-
* Typical value: process.stderr.
|
|
613
|
-
*/
|
|
614
|
-
progressOutput?: {
|
|
615
|
-
write(chunk: string): unknown;
|
|
616
|
-
};
|
|
617
|
-
context?: {
|
|
618
|
-
cwd?: string;
|
|
619
|
-
environment?: "local" | "ci" | "remote";
|
|
620
|
-
artifacts?: Record<string, string>;
|
|
621
|
-
variables?: Record<string, unknown>;
|
|
622
|
-
};
|
|
623
|
-
/**
|
|
624
|
-
* Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
|
|
625
|
-
* When undefined, no spans are emitted (observer is optional — no-op).
|
|
626
|
-
* Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
|
|
627
|
-
*/
|
|
628
|
-
observer?: ObserverEmitFn;
|
|
629
|
-
/**
|
|
630
|
-
* Optional toolchain-check observation config (see WorkflowRunOptions.toolchain).
|
|
631
|
-
* OBSERVATION ONLY — never changes the workflow outcome.
|
|
632
|
-
*/
|
|
633
|
-
toolchain?: RunToolchainChecksOptions;
|
|
634
|
-
/**
|
|
635
|
-
* In-process library tools to register with every task in this workflow.
|
|
636
|
-
* Created once per execution and shared across all steps.
|
|
637
|
-
*/
|
|
638
|
-
libraryTools?: LibraryToolRegistry;
|
|
639
|
-
/**
|
|
640
|
-
* Resolves adapter + model for execution envelopes. Injected by executeWorkflow;
|
|
641
|
-
* not typically set by external callers.
|
|
642
|
-
*/
|
|
643
|
-
resolveModelMeta?: (modelClass?: ModelClass) => ResolvedModel;
|
|
644
|
-
/** See WorkflowRunOptions.perAgentAdapters (#269). Injected by executeWorkflow. */
|
|
645
|
-
perAgentAdapters?: boolean;
|
|
646
|
-
}
|
|
647
|
-
interface StepResult {
|
|
648
|
-
step_index: number;
|
|
649
|
-
task_id?: string;
|
|
650
|
-
gate_kind?: string;
|
|
651
|
-
outcome: TaskOutcome | {
|
|
652
|
-
status: "gate_approved";
|
|
653
|
-
} | {
|
|
654
|
-
status: "gate_rejected";
|
|
655
|
-
} | {
|
|
656
|
-
status: "skipped";
|
|
657
|
-
};
|
|
658
|
-
follow_ups_used: number;
|
|
659
|
-
retries_used: number;
|
|
660
|
-
elapsed_ms: number;
|
|
661
|
-
/** Resolved model_class for delegate/evaluate steps (from task registry). */
|
|
662
|
-
model_class?: ModelClass;
|
|
663
|
-
/** Concrete adapter name used for this step's LLM calls. */
|
|
664
|
-
adapter?: string;
|
|
665
|
-
/** Concrete model name used for this step's LLM calls. */
|
|
666
|
-
model?: string;
|
|
667
|
-
}
|
|
668
|
-
interface StepCompleteEvent {
|
|
669
|
-
workflow_id: string;
|
|
670
|
-
step_index: number;
|
|
671
|
-
step_type: "delegate" | "gate" | "evaluate";
|
|
672
|
-
task_id?: string;
|
|
673
|
-
gate_kind?: string;
|
|
674
|
-
outcome_status: string;
|
|
675
|
-
follow_ups_used: number;
|
|
676
|
-
retries_used: number;
|
|
677
|
-
elapsed_ms: number;
|
|
678
|
-
}
|
|
679
|
-
interface WorkflowResult {
|
|
680
|
-
workflow_id: string;
|
|
681
|
-
status: "completed" | "escalated" | "gate_rejected" | "error";
|
|
682
|
-
steps: StepResult[];
|
|
683
|
-
total_elapsed_ms: number;
|
|
684
|
-
escalation_reason?: string;
|
|
685
|
-
error_message?: string;
|
|
686
|
-
}
|
|
687
|
-
interface WorkflowRegistries {
|
|
688
|
-
workflowRegistry?: Record<string, WorkflowContractLike>;
|
|
689
|
-
taskRegistry?: Record<string, TaskContractLike>;
|
|
690
|
-
agentRegistry?: Record<string, AgentContractLike>;
|
|
691
|
-
handoffSchemas?: Record<string, z.ZodType>;
|
|
692
|
-
}
|
|
693
|
-
/** @deprecated Use the WorkflowInvocation overload for typed handoff input. */
|
|
694
|
-
declare function runWorkflow(adapter: AdapterOrFactory, workflowId: string, options: WorkflowRunOptions, registries?: WorkflowRegistries): Promise<WorkflowResult>;
|
|
695
|
-
/** Structured invocation with typed handoff envelope. */
|
|
696
|
-
declare function runWorkflow(adapter: AdapterOrFactory, invocation: WorkflowInvocation, registries?: WorkflowRegistries): Promise<WorkflowResult>;
|
|
697
|
-
declare function buildGateEvaluationPrompt(step: GateStep, priorContext: string): string;
|
|
698
|
-
declare function parseGateEvaluationResponse(response: string): boolean;
|
|
699
|
-
|
|
700
|
-
/**
|
|
701
|
-
* BoundResolver — runtime binding + policy resolution with per-agent isolation.
|
|
702
|
-
*
|
|
703
|
-
* Resolves artifact composition and guardrail/policy in one pass at runtime,
|
|
704
|
-
* producing a per-agent scoped ResolvedComponent. Reuses existing
|
|
705
|
-
* resolveArtifacts(), buildGuardrailContext(), and agent scope resolution.
|
|
706
|
-
*/
|
|
707
|
-
|
|
708
|
-
interface ArtifactBindingConfig {
|
|
709
|
-
source: string;
|
|
710
|
-
mappings?: Record<string, string>;
|
|
711
|
-
}
|
|
712
|
-
interface BoundResolveOptions {
|
|
713
|
-
/** Component identifier — used for cache keying. */
|
|
714
|
-
id: string;
|
|
715
|
-
/** Pre-resolved DSL (e.g. embedded from codegen). */
|
|
716
|
-
embeddedDsl?: Record<string, unknown>;
|
|
717
|
-
/** Path to DSL file — resolved via agent-contracts when no embeddedDsl. */
|
|
718
|
-
dslPath?: string;
|
|
719
|
-
/** Paths to software binding YAML files (guardrail_impl, etc.). */
|
|
720
|
-
bindingPaths?: string[];
|
|
721
|
-
/** Active guardrail policy name from DSL guardrail_policies. */
|
|
722
|
-
activeGuardrailPolicy?: string;
|
|
723
|
-
/** Artifact binding config — composed via resolveArtifacts() (lib/artifact-resolver). */
|
|
724
|
-
artifactBinding?: ArtifactBindingConfig;
|
|
725
|
-
/** Path substitutions for artifact binding. */
|
|
726
|
-
paths?: Record<string, string>;
|
|
727
|
-
/** Path to toolchain-contracts.yaml. */
|
|
728
|
-
toolchainContractsPath?: string;
|
|
729
|
-
}
|
|
730
|
-
interface ResolvedToolchain {
|
|
731
|
-
id: string;
|
|
732
|
-
kind: "library" | "cli" | "component";
|
|
733
|
-
description?: string;
|
|
734
|
-
module?: string;
|
|
735
|
-
command?: string;
|
|
736
|
-
cli_contract?: string;
|
|
737
|
-
component_contract?: string;
|
|
738
|
-
artifacts: {
|
|
739
|
-
consumes: string[];
|
|
740
|
-
produces: string[];
|
|
741
|
-
};
|
|
742
|
-
operations?: string[];
|
|
743
|
-
source: "toolchain-contracts" | "agent-contracts" | "merged";
|
|
744
|
-
}
|
|
745
|
-
interface ResolvedComponent {
|
|
746
|
-
id: string;
|
|
747
|
-
dsl: Record<string, unknown>;
|
|
748
|
-
registries: WorkflowRegistries;
|
|
749
|
-
guardrails: {
|
|
750
|
-
perAgent: Map<string, GuardrailRuleData>;
|
|
751
|
-
};
|
|
752
|
-
diagnostics: Array<{
|
|
753
|
-
path?: string;
|
|
754
|
-
message: string;
|
|
755
|
-
severity?: string;
|
|
756
|
-
}>;
|
|
757
|
-
toolchains?: Record<string, ResolvedToolchain>;
|
|
758
|
-
toolchainsByAgent?: Map<string, ResolvedToolchain[]>;
|
|
759
|
-
}
|
|
760
|
-
/**
|
|
761
|
-
* Effective guardrail IDs for an agent: entity-side bindings ∪ scope-side bindings.
|
|
762
|
-
*/
|
|
763
|
-
declare function getEffectiveGuardrailIds(dsl: Record<string, unknown>, agentId: string): Set<string>;
|
|
764
|
-
declare function guardrailContextToRuleData(ctx: GuardrailContext, effectiveIds?: Set<string>): GuardrailRuleData;
|
|
765
|
-
declare function buildPerAgentGuardrails(dsl: Record<string, unknown>, guardrailCtx: GuardrailContext): Map<string, GuardrailRuleData>;
|
|
766
|
-
declare function deriveToolchainsForAgents(dsl: Record<string, unknown>, toolchains: Record<string, ResolvedToolchain>): Map<string, ResolvedToolchain[]>;
|
|
767
|
-
declare class BoundResolver {
|
|
768
|
-
private readonly cache;
|
|
769
|
-
/**
|
|
770
|
-
* Resolve binding + policy in one pass. Results are cached by component id.
|
|
771
|
-
*/
|
|
772
|
-
resolve(opts: BoundResolveOptions): Promise<ResolvedComponent>;
|
|
773
|
-
/** Clear cached components (e.g. for testing). */
|
|
774
|
-
clearCache(): void;
|
|
775
|
-
}
|
|
776
|
-
/** Get guardrail rules for a specific agent from a ResolvedComponent. */
|
|
777
|
-
declare function getGuardrailRulesForAgent(component: ResolvedComponent, agentId: string): GuardrailRuleData | undefined;
|
|
778
|
-
|
|
779
309
|
/**
|
|
780
310
|
* Candidate Agents — backend-neutral bridge for LLM-internal routing (model B)
|
|
781
311
|
*
|
|
@@ -801,7 +331,7 @@ interface CandidateAgent {
|
|
|
801
331
|
name: string;
|
|
802
332
|
/** When to use this agent — the routing hint shown to the delegating LLM. */
|
|
803
333
|
description: string;
|
|
804
|
-
/** The agent's system prompt
|
|
334
|
+
/** The agent's system prompt — everything the DSL declares about its work. */
|
|
805
335
|
prompt: string;
|
|
806
336
|
/** Optional allowed tool names (omit to inherit from the parent agent). */
|
|
807
337
|
tools?: string[];
|
|
@@ -809,11 +339,26 @@ interface CandidateAgent {
|
|
|
809
339
|
model?: string;
|
|
810
340
|
}
|
|
811
341
|
/**
|
|
812
|
-
* Render an agent contract into its system-prompt string: the
|
|
813
|
-
*
|
|
342
|
+
* Render an agent contract into its system-prompt string: everything the DSL
|
|
343
|
+
* declares about how the agent must work.
|
|
814
344
|
*
|
|
815
|
-
*
|
|
816
|
-
*
|
|
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.
|
|
817
362
|
*/
|
|
818
363
|
declare function renderAgentSystemPrompt(agent: AgentContractLike): string;
|
|
819
364
|
interface BuildCandidateAgentsOptions {
|
|
@@ -824,7 +369,17 @@ interface BuildCandidateAgentsOptions {
|
|
|
824
369
|
* candidates to these agent ids. Omit to allow every non-entry agent.
|
|
825
370
|
*/
|
|
826
371
|
allowedAgentIds?: readonly string[];
|
|
827
|
-
|
|
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[]>;
|
|
828
383
|
}
|
|
829
384
|
/**
|
|
830
385
|
* Build the candidate sub-agent set from an agent registry.
|
|
@@ -873,6 +428,63 @@ interface AgentContractLike {
|
|
|
873
428
|
* isolated tool set instead of inheriting the parent agent's tools.
|
|
874
429
|
*/
|
|
875
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
|
+
}[];
|
|
876
488
|
}
|
|
877
489
|
interface TaskContractLike {
|
|
878
490
|
readonly id: string;
|
|
@@ -880,7 +492,7 @@ interface TaskContractLike {
|
|
|
880
492
|
readonly target_agent: string;
|
|
881
493
|
readonly result_handoff: string;
|
|
882
494
|
readonly completion_criteria: readonly string[];
|
|
883
|
-
readonly model_class?:
|
|
495
|
+
readonly model_class?: ModelClass;
|
|
884
496
|
/**
|
|
885
497
|
* When true, the adapter may enable Dynamic Workflow tools (e.g. Claude's
|
|
886
498
|
* Workflow tool) so the agent can internally parallelise sub-tasks.
|
|
@@ -1146,18 +758,6 @@ declare function zodSchemaToPromptDescription(schema: z.ZodType): string;
|
|
|
1146
758
|
* nested objects and arrays up to a configurable depth.
|
|
1147
759
|
*/
|
|
1148
760
|
declare function zodSchemaToYamlExample(schema: z.ZodType, maxDepth?: number): string;
|
|
1149
|
-
/**
|
|
1150
|
-
* Duck-type check: does `value` look like a ProjectNavigationIndex?
|
|
1151
|
-
* Requires a `system` object and an `artifacts` record.
|
|
1152
|
-
*/
|
|
1153
|
-
declare function isNavigationIndex(value: unknown): value is Record<string, unknown>;
|
|
1154
|
-
/**
|
|
1155
|
-
* Render the Level 1 navigation index as a compact prompt section — a
|
|
1156
|
-
* human-readable SUMMARY of artifacts (type, authority, edit policy, key
|
|
1157
|
-
* relations and owning agents), NOT a raw JSON dump. Gives the agent a map of
|
|
1158
|
-
* the project's artifacts so it can navigate before acting.
|
|
1159
|
-
*/
|
|
1160
|
-
declare function renderNavigationIndexPrompt(navigationIndex: Record<string, unknown>): string;
|
|
1161
761
|
/** Collect analyzer.* tool ids from a wired library tool registry. */
|
|
1162
762
|
declare function collectAnalyzerToolIds(registry?: LibraryToolRegistry): string[];
|
|
1163
763
|
/**
|
|
@@ -1185,8 +785,9 @@ interface PromptBuilderOptions {
|
|
|
1185
785
|
/**
|
|
1186
786
|
* Build a prompt split into static (cacheable) and dynamic (per-invocation) parts.
|
|
1187
787
|
*
|
|
1188
|
-
* Static (system):
|
|
1189
|
-
* 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.
|
|
1190
791
|
*
|
|
1191
792
|
* Dynamic (user): User Request, Handoff Input, Prior Context,
|
|
1192
793
|
* Relevant Files, Acceptance Criteria.
|
|
@@ -1205,6 +806,12 @@ declare function runTask(adapter: SdkAdapter, taskId: string, context: TaskConte
|
|
|
1205
806
|
revalidate_task?: string;
|
|
1206
807
|
};
|
|
1207
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[]>;
|
|
1208
815
|
}): Promise<TaskRunResult>;
|
|
1209
816
|
|
|
1210
|
-
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 };
|