@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
package/dist/index.d.ts CHANGED
@@ -1,15 +1,52 @@
1
- import { b as SdkFunctionTool, O as ObserverEmitFn, c as TaskContext, d as TaskOutcome, e as AgentContractLike, f as TaskContractLike, P as PromptBuilderOptions, W as WorkflowResult, S as SdkAdapter, g as WorkflowRegistries, H as HandoffInput, h as StepCompleteEvent, i as StepResult, D as DelegateStep, j as MemoryStore, M as MemoryRef, R as ResolvedComponent, k as ArtifactBindingConfig, l as RunToolchainChecksOptions, m as ModelMappingConfig, n as TaskRunResult, L as LibraryToolRegistry, o as ResolvedToolchain, p as LibraryToolDefinition } from './task-runner-CLc8iTzy.js';
2
- export { q as AdapterOrFactory, A as AdapterSendOptions, a as AgentExecutionRequest, r as AgentProgressEvent, B as BoundResolveOptions, s as BoundResolver, C as CacheConfig, t as CandidateAgent, u as ConvergenceEnvelope, v as ConvergenceEnvelopePayload, E as EnvelopeParams, w as EvaluateStep, G as GateStep, I as InMemoryStore, x as InnerSpanOptions, y as ModelAwareSdkAdapterFactory, z as ModelClass, F as ModelResolver, J as ModelResolverOptions, K as OBSERVABILITY_ENV_VARS, N as ObservabilityIds, Q as ReceiveSpec, U as ResolvedModel, V as RetryDecision, X as SdkAdapterFactory, Y as SplitPrompt, Z as TaskRunOptions, T as TokenUsage, _ as ToolchainCheckResult, $ as ToolchainManifest, a0 as ToolchainManifestSchema, a1 as WorkflowContractLike, a2 as WorkflowInvocation, a3 as WorkflowRunOptions, a4 as WorkflowStep, a5 as buildCandidateAgents, a6 as buildGateEvaluationPrompt, a7 as buildObservabilityEnv, a8 as buildPerAgentGuardrails, a9 as buildRetryFollowUp, aa as buildSdkFunctionTools, ab as buildSplitTaskPrompt, ac as buildTaskPrompt, ad as collectAnalyzerToolIds, ae as createExecutionEnvelope, af as createLibraryToolRegistry, ag as createModelResolver, ah as createRegistryFromSdkTools, ai as deriveToolchainsForAgents, aj as emitIterationClose, ak as emitIterationMetric, al as emitIterationOpen, am as emitLlmTurnClose, an as emitLlmTurnOpen, ao as emitSessionClose, ap as emitSessionOpen, aq as emitSubagentClose, ar as emitSubagentOpen, as as emitToolExecClose, at as emitToolExecOpen, au as emitToolchainClose, av as emitToolchainOpen, aw as extractStructuredResult, ax as getEffectiveGuardrailIds, ay as getGuardrailRulesForAgent, az as guardrailContextToRuleData, aA as isNavigationIndex, aB as parseGateEvaluationResponse, aC as renderAgentSystemPrompt, aD as renderAnalyzerExplorationMandatePrompt, aE as renderNavigationIndexPrompt, aF as runTask, aG as runToolchainChecks, aH as runWorkflow, aI as serializeObserverEmit, aJ as shouldInjectAnalyzerExplorationMandate, aK as zodSchemaToPromptDescription, aL as zodSchemaToYamlExample } from './task-runner-CLc8iTzy.js';
3
- import { G as GuardrailHooks, H as HookResponse, b as GuardrailCheckResult } from './guardrail-hooks-slK-z0Dz.js';
4
- export { c as GuardrailCheckFunctions, d as GuardrailRule, a as GuardrailRuleData, e as HookContext, f as createGuardrailHooks, g as createGuardrailHooksForAgent, h as createGuardrailHooksFromRules, i as getBlockingViolations, j as getWarnings, k as hasBlockingViolation } from './guardrail-hooks-slK-z0Dz.js';
1
+ import { b as SdkFunctionTool, O as ObserverEmitFn, c as ObservabilityIds, S as SdkAdapter, d as TaskOutcome, e as TaskContractLike, f as AgentContractLike, g as TaskContext, L as LibraryToolRegistry, P as PromptBuilderOptions, h as MemoryStore, M as MemoryRef, i as TaskRunResult } from './task-runner-GWoI7_71.js';
2
+ export { A as AdapterSendOptions, a as AgentExecutionRequest, j as AgentProgressEvent, C as CacheConfig, k as CandidateAgent, E as EnvelopeParams, I as InMemoryStore, l as InnerSpanOptions, m as LibraryToolDefinition, n as OBSERVABILITY_ENV_VARS, R as RetryDecision, o as SplitPrompt, p as TaskRunOptions, T as TokenUsage, q as buildCandidateAgents, r as buildObservabilityEnv, s as buildRetryFollowUp, t as buildSdkFunctionTools, u as buildSplitTaskPrompt, v as buildTaskPrompt, w as collectAnalyzerToolIds, x as createExecutionEnvelope, y as createLibraryToolRegistry, z as createRegistryFromSdkTools, B as emitIterationClose, D as emitIterationMetric, F as emitIterationOpen, G as emitLlmTurnClose, H as emitLlmTurnOpen, J as emitSessionClose, K as emitSessionOpen, N as emitSubagentClose, Q as emitSubagentOpen, U as emitToolExecClose, V as emitToolExecOpen, W as emitToolchainClose, X as emitToolchainOpen, Y as extractStructuredResult, Z as renderAgentSystemPrompt, _ as renderAnalyzerExplorationMandatePrompt, $ as runTask, a0 as serializeObserverEmit, a1 as shouldInjectAnalyzerExplorationMandate, a2 as zodSchemaToPromptDescription, a3 as zodSchemaToYamlExample } from './task-runner-GWoI7_71.js';
3
+ import { ProjectModelMapping, ModelClass, ComponentIR, OperationIR } from '@aaac/contracts';
4
+ export { ModelClass } from '@aaac/contracts';
5
5
  import { z } from 'zod';
6
- import { OperationIR, ComponentIR } from '@aaac/contracts';
6
+ import { b as GuardrailCheckFunctions, a as GuardrailRuleData, G as GuardrailHooks, H as HookResponse, c as GuardrailCheckResult } from './guardrail-hooks-CB23nhZV.js';
7
+ export { d as GuardrailAction, e as GuardrailRule, f as HookContext, U as UNRESOLVED_GUARDRAIL_ACTION, g as createGuardrailHooks, h as createGuardrailHooksFromRules, i as getBlockingViolations, j as getWarnings, k as hasBlockingViolation } from './guardrail-hooks-CB23nhZV.js';
8
+ import { G as GuardrailContext, P as ProgressLogConfig, R as ResolvedConfig, a as GuardrailDiagnostic } from './index-BlSepCSZ.js';
9
+ export { b as PROJECT_CONFIG_FILENAME } from './index-BlSepCSZ.js';
7
10
  import { OtelEmitter } from '@aaac/observability';
8
11
  export { ExecutionEnvelope } from '@aaac/observability';
9
- import { R as ResolvedConfig } from './index-LqEvaRk-.js';
10
- export { P as PROJECT_CONFIG_FILENAME } from './index-LqEvaRk-.js';
11
- export { a as NavigationContext, N as NavigationContextOptions, b as buildNavigationContext } from './navigation-context-D_E1NIUf.js';
12
- import './context-DKkamYX_.js';
12
+ export { a as NavigationContext, N as NavigationContextOptions, b as buildNavigationContext } from './navigation-context-B-RpUg3_.js';
13
+ export { i as isNavigationIndex, r as renderNavigationIndexPrompt } from './navigation-index-prompt-CbrS5laO.js';
14
+
15
+ /**
16
+ * ModelResolver — resolves a model_class to a concrete adapter + model pair.
17
+ *
18
+ * Resolution priority (highest wins):
19
+ * 1. AGENT_RUNTIME_MODEL_<CLASS> env var (class name upper-cased)
20
+ * 2. AGENT_RUNTIME_MODEL env var (catch-all fallback)
21
+ * 3. project.yaml model_mapping.<class>
22
+ * 4. CLI --adapter + adapter default model
23
+ */
24
+
25
+ interface ResolvedModel {
26
+ adapter: string;
27
+ model?: string;
28
+ }
29
+ interface ModelResolver {
30
+ resolve(modelClass: ModelClass | undefined): ResolvedModel;
31
+ }
32
+ /**
33
+ * The `model_mapping` section this resolver reads, as declared by
34
+ * @aaac/contracts — restating its shape here is what forced every caller to
35
+ * bridge the two with an `as`.
36
+ */
37
+ type ModelMappingConfig = ProjectModelMapping;
38
+ interface ModelResolverOptions {
39
+ modelMapping?: ModelMappingConfig;
40
+ fallbackAdapter: string;
41
+ fallbackModel?: string;
42
+ env?: Record<string, string | undefined>;
43
+ /**
44
+ * When set, always use this adapter name. Model is still resolved per class
45
+ * from mapping / env (e.g. CLI `--adapter mock` with project model_mapping).
46
+ */
47
+ pinnedAdapter?: string;
48
+ }
49
+ declare function createModelResolver(options: ModelResolverOptions): ModelResolver;
13
50
 
14
51
  /**
15
52
  * Analyzer Bridge — integrates artifact-contracts-analyzer as a standard
@@ -95,8 +132,17 @@ interface AnalyzerBridge {
95
132
  }
96
133
  declare function createAnalyzerBridge(options: AnalyzerBridgeOptions): AnalyzerBridge;
97
134
  /**
98
- * Duck-type check: does `value` look like a ContextPack?
99
- * Checks for the `entries` array and `metadata` object with expected fields.
135
+ * The single gate between untyped analyzer output and the `ContextPack` type
136
+ * declared above. Whatever passes may be walked without further guarding; what
137
+ * fails is not a ContextPack and none of it may be read as one.
138
+ *
139
+ * Every declared field is checked, including the ones no caller reads today,
140
+ * because the predicate's return type — not the set of fields some caller
141
+ * happens to dereference — is what it promises. Checking a subset promises a
142
+ * `ContextPack` while verifying something weaker, and the difference surfaces
143
+ * as a TypeError one dereference away: `{ entries: [null], metadata: {
144
+ * totalTokens, budgetTokens } }` satisfied an `entries`-is-an-array check and
145
+ * threw in both callers (#326).
100
146
  */
101
147
  declare function isContextPack(value: unknown): value is ContextPack;
102
148
  /**
@@ -105,6 +151,362 @@ declare function isContextPack(value: unknown): value is ContextPack;
105
151
  */
106
152
  declare function renderContextPackPrompt(pack: ContextPack): string;
107
153
 
154
+ /**
155
+ * Toolchain Checker — runs check commands defined in toolchain-contracts
156
+ * and returns structured pass/fail results.
157
+ *
158
+ * Each toolchain may declare a `checks` map (checkType → shell command).
159
+ * This module iterates all checks, executes them via subprocess, and
160
+ * returns a ToolchainCheckResult[].
161
+ *
162
+ * For "drift" check types, a manifest-based fast path is available:
163
+ * if a .toolchain-manifest.json exists and the toolchain_id matches,
164
+ * the command execution can be skipped when the source hash is current.
165
+ */
166
+
167
+ declare const ToolchainManifestSchema: z.ZodObject<{
168
+ schema: z.ZodString;
169
+ toolchain_id: z.ZodString;
170
+ generated_at: z.ZodString;
171
+ source_hash: z.ZodString;
172
+ output_hash: z.ZodString;
173
+ source_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
174
+ output_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
175
+ files: z.ZodOptional<z.ZodArray<z.ZodObject<{
176
+ path: z.ZodString;
177
+ hash: z.ZodString;
178
+ }, z.core.$strip>>>;
179
+ }, z.core.$strip>;
180
+ type ToolchainManifest = z.infer<typeof ToolchainManifestSchema>;
181
+ interface ToolchainCheckResult {
182
+ toolchainId: string;
183
+ checkType: string;
184
+ status: "pass" | "fail" | "skip" | "error";
185
+ action: "block" | "warn" | "shadow";
186
+ message?: string;
187
+ durationMs?: number;
188
+ }
189
+ interface RunToolchainChecksOptions {
190
+ /** Absolute path to toolchain-contracts YAML */
191
+ toolchainsPath: string;
192
+ /** Absolute path to artifact-contracts YAML (optional, for manifest fast path) */
193
+ artifactsPath?: string;
194
+ /** Working directory for subprocess execution */
195
+ cwd?: string;
196
+ /** Filter: only run these check types */
197
+ checkTypes?: string[];
198
+ /** Filter: only run checks for these toolchain IDs */
199
+ toolchainFilter?: string[];
200
+ /** Policy-resolved action per check type. Key = check type, value = action. Special key "_default" for fallback. */
201
+ checkTypeActions?: Record<string, "block" | "warn" | "shadow">;
202
+ /** Default action when no policy match */
203
+ defaultAction?: "block" | "warn" | "shadow";
204
+ /**
205
+ * Optional observer emit function. When provided, each check execution emits a
206
+ * toolchain.execution span (open before the check, close after) so the check is
207
+ * recorded on the agent axis. No-op when undefined (observer is optional).
208
+ * This is OBSERVATION ONLY — emitting spans never alters the returned results
209
+ * nor the resolved action, so workflow success/failure semantics are unchanged.
210
+ */
211
+ observer?: ObserverEmitFn;
212
+ /** Parent span id (typically the enclosing agent.session run_id) for correlation. */
213
+ parentSpanId?: string;
214
+ /** Component id recorded on toolchain.execution spans (agent.component_id). */
215
+ componentId?: string;
216
+ /**
217
+ * Observability correlation ids propagated to spawned check subprocesses as
218
+ * AAAC_SESSION_ID / AAAC_TRACE_ID / AAAC_RUN_ID (#115). A check that spawns
219
+ * `git commit`/`git push` lets the resulting git `post-commit` hook attribute
220
+ * its promotion.* events back to this session. No-op when undefined.
221
+ */
222
+ observabilityIds?: ObservabilityIds;
223
+ }
224
+ declare function runToolchainChecks(options: RunToolchainChecksOptions): Promise<ToolchainCheckResult[]>;
225
+
226
+ /**
227
+ * Workflow Runner — orchestrates a DSL workflow as a sequence of task executions
228
+ *
229
+ * Programmatic control flow that replaces LLM-driven step interpretation:
230
+ *
231
+ * 1. Load workflow contract (ordered steps)
232
+ * 2. Run plugin beforeWorkflow hooks
233
+ * 3. For each step:
234
+ * - delegate → call task-runner with followUp/retry recovery
235
+ * - gate → pause and wait for user input
236
+ * 4. Validate each result against handoff schema
237
+ * 5. Accumulate context between steps
238
+ * 6. Run plugin afterWorkflow hooks
239
+ */
240
+
241
+ /**
242
+ * A factory that creates independent SdkAdapter instances.
243
+ * Used by runWorkflow to allocate one adapter per parallel step,
244
+ * avoiding session-level serialization in stateful SDK adapters.
245
+ */
246
+ type SdkAdapterFactory = () => SdkAdapter;
247
+ /**
248
+ * Model-aware adapter factory. Accepts a model_class and returns an adapter
249
+ * configured for that capability level (possibly a different provider/model).
250
+ */
251
+ type ModelAwareSdkAdapterFactory = (modelClass?: ModelClass,
252
+ /**
253
+ * Agent the step runs as (a task's `target_agent`). Guardrail hooks are fixed at
254
+ * adapter construction, so an agent-scoped factory returns a distinct adapter per
255
+ * agent (#269). Ignored by factories that do not scope guardrails.
256
+ */
257
+ agentId?: string) => SdkAdapter | Promise<SdkAdapter>;
258
+ /** Accepts either a single adapter (serial/shared) or a factory (parallel-safe). */
259
+ type AdapterOrFactory = SdkAdapter | SdkAdapterFactory | ModelAwareSdkAdapterFactory;
260
+ /** Specification for what a step receives from a dependency. */
261
+ interface ReceiveSpec {
262
+ /** The task id of the dependency step to receive from. If omitted, alias is used as task id. */
263
+ readonly from?: string;
264
+ /** 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. */
265
+ readonly path?: string;
266
+ }
267
+ interface DelegateStep {
268
+ readonly type: "delegate";
269
+ readonly task: string;
270
+ readonly from_agent: string;
271
+ readonly description: string;
272
+ readonly optional: boolean;
273
+ readonly max_retries: number;
274
+ readonly max_follow_ups?: number;
275
+ readonly depends_on?: readonly string[];
276
+ readonly instruction?: string;
277
+ readonly receives?: Record<string, ReceiveSpec>;
278
+ readonly retry?: {
279
+ readonly condition: string;
280
+ readonly fix_task: string;
281
+ readonly revalidate_task?: string;
282
+ };
283
+ }
284
+ interface GateStep {
285
+ readonly type: "gate";
286
+ readonly gate_kind: string;
287
+ readonly description: string;
288
+ readonly depends_on?: readonly string[];
289
+ }
290
+ /**
291
+ * Evaluate step — runs a task that returns a convergence-envelope, then either
292
+ * proceeds (verdict=pass) or loops back to `loop_to` with feedback injected
293
+ * (verdict=fail, iteration < max_iterations), or applies `on_exhausted`.
294
+ */
295
+ interface EvaluateStep {
296
+ readonly type: "evaluate";
297
+ readonly task: string;
298
+ readonly from_agent: string;
299
+ readonly evaluator_agent?: string;
300
+ readonly description?: string;
301
+ readonly loop_to: string;
302
+ readonly max_iterations: number;
303
+ readonly inject_as?: string;
304
+ readonly on_exhausted?: "abort" | "fail_partial" | "escalate";
305
+ readonly depends_on?: readonly string[];
306
+ }
307
+ /**
308
+ * Payload returned by an evaluate task in a convergence-envelope handoff.
309
+ * The runtime reads `verdict` to decide whether to proceed or loop back.
310
+ */
311
+ interface ConvergenceEnvelopePayload {
312
+ /** "pass" means quality gate passed; "fail" triggers a loop-back. */
313
+ readonly verdict: "pass" | "fail";
314
+ /** Human-readable feedback injected into the next iteration via `inject_as`. */
315
+ readonly feedback?: string;
316
+ }
317
+ /** Typed handoff envelope produced by an evaluate task. */
318
+ type ConvergenceEnvelope = HandoffInput<"convergence-envelope", ConvergenceEnvelopePayload>;
319
+ type WorkflowStep = DelegateStep | GateStep | EvaluateStep;
320
+ interface WorkflowContractLike {
321
+ readonly id: string;
322
+ readonly description: string;
323
+ readonly steps: readonly WorkflowStep[];
324
+ }
325
+ interface WorkflowRunOptions {
326
+ user_request: string;
327
+ /** Override max follow-up attempts per step (lightweight output-format correction). Default: 2 */
328
+ maxFollowUps?: number;
329
+ /** Override max full retry attempts per step. Default: from DSL step.max_retries */
330
+ maxRetries?: number;
331
+ /** Variables propagated to every TaskContext in the workflow (from WorkflowInvocation.context). */
332
+ variables?: Record<string, unknown>;
333
+ onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
334
+ onStepComplete?: (event: StepCompleteEvent) => void;
335
+ onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
336
+ /**
337
+ * Writable stream for real-time progress output during agent execution.
338
+ * Intermediate events from adapters are formatted and written here.
339
+ * Typical value: process.stderr.
340
+ */
341
+ progressOutput?: {
342
+ write(chunk: string): unknown;
343
+ };
344
+ /**
345
+ * Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
346
+ * When undefined, no spans are emitted (observer is optional — no-op).
347
+ * Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
348
+ */
349
+ observer?: ObserverEmitFn;
350
+ /**
351
+ * Optional toolchain-check observation config. When set together with `observer`,
352
+ * runWorkflow runs the configured toolchain checks AFTER the workflow body (a
353
+ * single post-run observation pass) and emits one toolchain.execution span per
354
+ * check, correlated to this run's agent.session span.
355
+ *
356
+ * OBSERVATION ONLY (non-destructive): the checks never alter the WorkflowResult
357
+ * — a failing check does not fail the workflow. `observer` and `parentSpanId`
358
+ * are injected by runWorkflow; callers supply `toolchainsPath` (+ optional
359
+ * artifactsPath/cwd/policy actions).
360
+ */
361
+ toolchain?: RunToolchainChecksOptions;
362
+ /**
363
+ * In-process library tools to register with every task in this workflow.
364
+ * Passed through to each runTask() call. Adapters convert these to their
365
+ * native tool format (Claude MCP, OpenAI function tools, ADK tools).
366
+ */
367
+ libraryTools?: LibraryToolRegistry;
368
+ /**
369
+ * Each agent's effective tool grant — the executing component's
370
+ * `ComponentScope.toolsByAgent` (#338). Passed through to each runTask()
371
+ * call, which is where an agent's candidate tool list is built.
372
+ */
373
+ toolsByAgent?: Map<string, string[]>;
374
+ /**
375
+ * Resolves adapter + model for execution envelopes (agent.session / agent.subagent).
376
+ * When undefined, envelopes omit adapter/model (observer spans lack gen_ai attrs).
377
+ */
378
+ resolveModelMeta?: (modelClass?: ModelClass) => ResolvedModel;
379
+ /**
380
+ * Request each step's adapter from the factory scoped to the step's agent, so
381
+ * per-agent guardrails apply to the agent actually doing the work (#269). Set
382
+ * by executeWorkflow when the run has ANY guardrail to enforce — the rules a
383
+ * binding resolved per agent, or the process's plugin guardrails, which are
384
+ * the same for every agent yet reach a step's adapter only through this
385
+ * scoping (#332). Without it, adapters are shared exactly as before.
386
+ */
387
+ perAgentAdapters?: boolean;
388
+ }
389
+ /** Typed handoff envelope for workflow input. */
390
+ interface HandoffInput<TType extends string = string, TPayload = unknown> {
391
+ readonly type: TType;
392
+ readonly version?: number;
393
+ readonly payload: TPayload;
394
+ }
395
+ /**
396
+ * Standard runtime invocation envelope. SDK-specific options (openaiThreadId,
397
+ * sessionId, etc.) belong on the adapter constructor — not here.
398
+ */
399
+ interface WorkflowInvocation<THandoffType extends string = string, TPayload = unknown> {
400
+ workflow: string;
401
+ /** Structured typed handoff input. Takes precedence over user_request if both are set. */
402
+ handoff?: HandoffInput<THandoffType, TPayload>;
403
+ /** Simple string input (convenience shorthand). */
404
+ user_request?: string;
405
+ runtime?: {
406
+ maxFollowUps?: number;
407
+ maxRetries?: number;
408
+ timeoutMs?: number;
409
+ readonly?: boolean;
410
+ dryRun?: boolean;
411
+ };
412
+ hooks?: {
413
+ onStepComplete?: (event: StepCompleteEvent) => void;
414
+ onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
415
+ onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
416
+ };
417
+ /**
418
+ * Writable stream for real-time progress output during agent execution.
419
+ * Intermediate events from adapters are formatted and written here.
420
+ * Typical value: process.stderr.
421
+ */
422
+ progressOutput?: {
423
+ write(chunk: string): unknown;
424
+ };
425
+ context?: {
426
+ cwd?: string;
427
+ environment?: "local" | "ci" | "remote";
428
+ artifacts?: Record<string, string>;
429
+ variables?: Record<string, unknown>;
430
+ };
431
+ /**
432
+ * Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
433
+ * When undefined, no spans are emitted (observer is optional — no-op).
434
+ * Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
435
+ */
436
+ observer?: ObserverEmitFn;
437
+ /**
438
+ * Optional toolchain-check observation config (see WorkflowRunOptions.toolchain).
439
+ * OBSERVATION ONLY — never changes the workflow outcome.
440
+ */
441
+ toolchain?: RunToolchainChecksOptions;
442
+ /**
443
+ * In-process library tools to register with every task in this workflow.
444
+ * Created once per execution and shared across all steps.
445
+ */
446
+ libraryTools?: LibraryToolRegistry;
447
+ /** See WorkflowRunOptions.toolsByAgent (#338). Injected by executeWorkflow. */
448
+ toolsByAgent?: Map<string, string[]>;
449
+ /**
450
+ * Resolves adapter + model for execution envelopes. Injected by executeWorkflow;
451
+ * not typically set by external callers.
452
+ */
453
+ resolveModelMeta?: (modelClass?: ModelClass) => ResolvedModel;
454
+ /** See WorkflowRunOptions.perAgentAdapters (#269). Injected by executeWorkflow. */
455
+ perAgentAdapters?: boolean;
456
+ }
457
+ interface StepResult {
458
+ step_index: number;
459
+ task_id?: string;
460
+ gate_kind?: string;
461
+ outcome: TaskOutcome | {
462
+ status: "gate_approved";
463
+ } | {
464
+ status: "gate_rejected";
465
+ } | {
466
+ status: "skipped";
467
+ };
468
+ follow_ups_used: number;
469
+ retries_used: number;
470
+ elapsed_ms: number;
471
+ /** Resolved model_class for delegate/evaluate steps (from task registry). */
472
+ model_class?: ModelClass;
473
+ /** Concrete adapter name used for this step's LLM calls. */
474
+ adapter?: string;
475
+ /** Concrete model name used for this step's LLM calls. */
476
+ model?: string;
477
+ }
478
+ interface StepCompleteEvent {
479
+ workflow_id: string;
480
+ step_index: number;
481
+ step_type: "delegate" | "gate" | "evaluate";
482
+ task_id?: string;
483
+ gate_kind?: string;
484
+ outcome_status: string;
485
+ follow_ups_used: number;
486
+ retries_used: number;
487
+ elapsed_ms: number;
488
+ }
489
+ interface WorkflowResult {
490
+ workflow_id: string;
491
+ status: "completed" | "escalated" | "gate_rejected" | "error";
492
+ steps: StepResult[];
493
+ total_elapsed_ms: number;
494
+ escalation_reason?: string;
495
+ error_message?: string;
496
+ }
497
+ interface WorkflowRegistries {
498
+ workflowRegistry?: Record<string, WorkflowContractLike>;
499
+ taskRegistry?: Record<string, TaskContractLike>;
500
+ agentRegistry?: Record<string, AgentContractLike>;
501
+ handoffSchemas?: Record<string, z.ZodType>;
502
+ }
503
+ /** @deprecated Use the WorkflowInvocation overload for typed handoff input. */
504
+ declare function runWorkflow(adapter: AdapterOrFactory, workflowId: string, options: WorkflowRunOptions, registries?: WorkflowRegistries): Promise<WorkflowResult>;
505
+ /** Structured invocation with typed handoff envelope. */
506
+ declare function runWorkflow(adapter: AdapterOrFactory, invocation: WorkflowInvocation, registries?: WorkflowRegistries): Promise<WorkflowResult>;
507
+ declare function buildGateEvaluationPrompt(step: GateStep, priorContext: string): string;
508
+ declare function parseGateEvaluationResponse(response: string): boolean;
509
+
108
510
  /**
109
511
  * Virtual workflow entry step — materializes WorkflowInvocation input as a
110
512
  * DAG-addressable output so downstream steps can use depends_on / receives.
@@ -250,11 +652,164 @@ declare class PluginRegistry {
250
652
  evaluateCommandGuardrails(command: string): GuardrailResult[];
251
653
  evaluateFilePathGuardrails(filePath: string): GuardrailResult[];
252
654
  evaluateFileContentGuardrails(filePath: string, content: string): GuardrailResult[];
655
+ /**
656
+ * Whether `guardrailChecks()` would supply anything.
657
+ *
658
+ * The execution layer has to know this BEFORE it builds hooks, because it
659
+ * decides whether hooks exist at all and the source it gets back is three
660
+ * closures either way, indistinguishable from an empty one. It gated on the
661
+ * resolved rules instead, so a project whose ONLY guardrails came from a
662
+ * plugin got no hooks and its plugin was consulted nowhere (#332).
663
+ *
664
+ * The question is asked of the three EVALUATORS, not of `customGuardrails`
665
+ * itself, because that is what the three aggregators above ask: each skips a
666
+ * plugin whose own method is absent, so `customGuardrails: {}` — legal under
667
+ * the type — contributes to no check. Answering `true` for it would report a
668
+ * source that grades nothing, and the execution layer would give a project
669
+ * one adapter per agent to carry hooks with nothing in them.
670
+ *
671
+ * Answering it belongs here for the same reason `guardrailChecks` does: the
672
+ * shape of `AgentPlugin.customGuardrails` is this module's to know, and it is
673
+ * read nowhere else.
674
+ */
675
+ hasGuardrails(): boolean;
676
+ /**
677
+ * These plugins' `customGuardrails`, as a check source `createGuardrailHooks`
678
+ * takes alongside the rules a software binding resolved.
679
+ *
680
+ * The evaluator used to reach for the `pluginRegistry` singleton itself. That
681
+ * is an ambient dependency pointing the wrong way — a shared leaf module
682
+ * reaching up into an application-level registry — and it had a measurable
683
+ * price, because `guardrail-hooks` is on the LEAN graph: a class gets no
684
+ * per-method tree-shaking, so the whole registry, task and workflow hooks
685
+ * included, was 1,481 B of the 12,496 B `check-artifact-edit` parses on every
686
+ * single tool call (#331). Handing the source in reverses the edge (this
687
+ * module knows the evaluator's shape; the evaluator knows nothing of plugins)
688
+ * and takes the class off that graph entirely.
689
+ *
690
+ * WHO passes it is the whole design, so it is stated here rather than left to
691
+ * be inferred from call sites:
692
+ *
693
+ * - The EXECUTION layer does — `execute.ts`, for the hooks it hands each
694
+ * agent's adapter. That is the process `loadPlugins` ran in
695
+ * (`project-runtime.ts` → `plugin-loader.ts`), and plugin guardrails guard
696
+ * what this runtime itself executes, exactly like every other
697
+ * `AgentPlugin` hook, all of which the task and workflow runners consume.
698
+ * - The HOOK routes do NOT — the two Claude Code PreToolUse bins and
699
+ * `guard evaluate`. Those answer "may this editor do this?", and they have
700
+ * to answer it identically or a project's rule means one thing in a Claude
701
+ * Code session and another under `guard evaluate` (#316). Two of the three
702
+ * CANNOT consult plugins at any price: they run on the lean bundle, which
703
+ * deliberately excludes the project-manifest resolver, so the `plugins:`
704
+ * list that `loadPlugins` needs is unreachable there — the shipped lean
705
+ * bundle contains neither this class nor any `loadPlugins` or `register`
706
+ * caller, so those processes hold no registry to consult at all. Feeding
707
+ * the third one a source the other two structurally lack is what would
708
+ * split the verdict; passing none keeps the three equal by construction
709
+ * instead of by the accident of no project declaring a plugin.
710
+ *
711
+ * The closures consult `this.plugins` when a check runs, not when the source
712
+ * is built. That is not a promise that a plugin registering later is picked
713
+ * up: the caller asks `hasGuardrails()` first and never comes back for the
714
+ * source when the answer was no, so a registration after that point reaches
715
+ * no hooks. What holds instead is the order — `loadPlugins` runs once, while
716
+ * `createProjectRuntime` builds the runtime, before anything can execute.
717
+ */
718
+ guardrailChecks(): GuardrailCheckFunctions;
253
719
  runBeforeWorkflow(workflowId: string, userRequest: string): Promise<void>;
254
720
  runAfterWorkflow(workflowId: string, result: WorkflowResult): Promise<void>;
255
721
  }
256
722
  declare const pluginRegistry: PluginRegistry;
257
723
 
724
+ /**
725
+ * BoundResolver — runtime binding + policy resolution with per-agent isolation.
726
+ *
727
+ * Resolves artifact composition and guardrail/policy in one pass at runtime,
728
+ * producing a per-agent scoped ResolvedComponent. Reuses existing
729
+ * resolveArtifacts(), buildGuardrailContext(), and agent scope resolution.
730
+ */
731
+
732
+ interface ArtifactBindingConfig {
733
+ source: string;
734
+ mappings?: Record<string, string>;
735
+ }
736
+ interface BoundResolveOptions {
737
+ /** Component identifier — used for cache keying. */
738
+ id: string;
739
+ /** Pre-resolved DSL (e.g. embedded from codegen). */
740
+ embeddedDsl?: Record<string, unknown>;
741
+ /** Path to DSL file — resolved via agent-contracts when no embeddedDsl. */
742
+ dslPath?: string;
743
+ /** Paths to software binding YAML files (guardrail_impl, etc.). */
744
+ bindingPaths?: string[];
745
+ /** Active guardrail policy name from DSL guardrail_policies. */
746
+ activeGuardrailPolicy?: string;
747
+ /** Artifact binding config — composed via resolveArtifacts() (lib/artifact-resolver). */
748
+ artifactBinding?: ArtifactBindingConfig;
749
+ /** Path substitutions for artifact binding. */
750
+ paths?: Record<string, string>;
751
+ /** Path to toolchain-contracts.yaml. */
752
+ toolchainContractsPath?: string;
753
+ }
754
+ interface ResolvedToolchain {
755
+ id: string;
756
+ kind: "library" | "cli" | "component";
757
+ description?: string;
758
+ module?: string;
759
+ command?: string;
760
+ cli_contract?: string;
761
+ component_contract?: string;
762
+ /**
763
+ * `info.id` of the component `component_contract` names, or undefined when
764
+ * the toolchain names no component.
765
+ *
766
+ * `component_contract` is a path relative to the toolchain-contracts file, so
767
+ * this is the only layer that can turn it into an identity — and the identity
768
+ * is what says whose namespace `operations` is written in (see
769
+ * `component-scope.ts`).
770
+ */
771
+ componentId?: string;
772
+ artifacts: {
773
+ consumes: string[];
774
+ produces: string[];
775
+ };
776
+ operations?: string[];
777
+ source: "toolchain-contracts" | "agent-contracts" | "merged";
778
+ }
779
+ interface ResolvedComponent {
780
+ id: string;
781
+ dsl: Record<string, unknown>;
782
+ registries: WorkflowRegistries;
783
+ guardrails: {
784
+ perAgent: Map<string, GuardrailRuleData>;
785
+ };
786
+ diagnostics: Array<{
787
+ path?: string;
788
+ message: string;
789
+ severity?: string;
790
+ }>;
791
+ toolchains?: Record<string, ResolvedToolchain>;
792
+ toolchainsByAgent?: Map<string, ResolvedToolchain[]>;
793
+ }
794
+ /**
795
+ * Effective guardrail IDs for an agent: entity-side bindings ∪ scope-side bindings.
796
+ */
797
+ declare function getEffectiveGuardrailIds(dsl: Record<string, unknown>, agentId: string): Set<string>;
798
+ declare function guardrailContextToRuleData(ctx: GuardrailContext, effectiveIds?: Set<string>): GuardrailRuleData;
799
+ declare function buildPerAgentGuardrails(dsl: Record<string, unknown>, guardrailCtx: GuardrailContext): Map<string, GuardrailRuleData>;
800
+ declare function deriveToolchainsForAgents(dsl: Record<string, unknown>, toolchains: Record<string, ResolvedToolchain>): Map<string, ResolvedToolchain[]>;
801
+ declare class BoundResolver {
802
+ private readonly cache;
803
+ /**
804
+ * Resolve binding + policy in one pass. Results are cached by component id.
805
+ */
806
+ resolve(opts: BoundResolveOptions): Promise<ResolvedComponent>;
807
+ /** Clear cached components (e.g. for testing). */
808
+ clearCache(): void;
809
+ }
810
+ /** Get guardrail rules for a specific agent from a ResolvedComponent. */
811
+ declare function getGuardrailRulesForAgent(component: ResolvedComponent, agentId: string): GuardrailRuleData | undefined;
812
+
258
813
  /**
259
814
  * Fluent Builder API for workflow invocation.
260
815
  *
@@ -298,41 +853,31 @@ declare class WorkflowBuilder {
298
853
  }
299
854
 
300
855
  /**
301
- * Plugin Loader — auto-discovers and registers user plugin files
856
+ * Plugin Loader — registers the plugin modules a project manifest declares.
302
857
  *
303
- * Discovery strategies (in priority order):
304
- * 1. Config-based: `plugins` array in agents.conf.yaml
305
- * 2. Convention-based: scan `src/plugins/` for files exporting AgentPlugin
858
+ * Discovery is the manifest and nothing else: `plugins:` in `project.yaml`
859
+ * lists the modules to load, and `createProjectRuntime` calls this once while
860
+ * building the runtime. Each path is dynamically import()'d and every export
861
+ * satisfying the AgentPlugin interface (an `id` string property) is registered
862
+ * with the pluginRegistry singleton, which the task runner, the workflow runner
863
+ * and `execute.ts` read at execution time. All three are in THIS process; the
864
+ * guardrail evaluator itself holds no reference to the registry, because it is
865
+ * shared with hook-bin processes this loader never runs in (#331).
306
866
  *
307
- * Each discovered module is dynamically import()'d. Exports that satisfy the
308
- * AgentPlugin interface (have an `id` string property) are registered with
309
- * the pluginRegistry singleton.
867
+ * A declared path that cannot be loaded throws: a plugin the manifest asks for
868
+ * and the runtime silently skips is indistinguishable from one that ran.
310
869
  */
311
870
  interface PluginLoadResult {
871
+ /** Number of AgentPlugin exports registered across all loaded modules. */
312
872
  loaded: number;
873
+ /** Absolute paths of the modules that were imported. */
313
874
  files: string[];
314
- errors: Array<{
315
- file: string;
316
- error: string;
317
- }>;
318
875
  }
319
876
  /**
320
- * Load plugins from explicit paths (config-based discovery).
877
+ * Load and register every plugin module the project manifest declares.
878
+ * `paths` are manifest-relative; `baseDir` is the manifest's directory.
321
879
  */
322
- declare function loadPluginsFromPaths(paths: string[], baseDir: string): Promise<PluginLoadResult>;
323
- /**
324
- * Load plugins using convention-based directory scanning.
325
- * Scans `<projectDir>/src/plugins/` by default.
326
- */
327
- declare function loadPluginsFromDirectory(dir: string): Promise<PluginLoadResult>;
328
- /**
329
- * Auto-discover and load plugins. Uses config-based paths if provided,
330
- * otherwise falls back to convention-based scanning of src/plugins/.
331
- */
332
- declare function loadPlugins(options: {
333
- pluginPaths?: string[];
334
- projectDir: string;
335
- }): Promise<PluginLoadResult>;
880
+ declare function loadPlugins(paths: string[], baseDir: string): Promise<PluginLoadResult>;
336
881
 
337
882
  /**
338
883
  * Runtime DSL Context — builds WorkflowRegistries from embedded DSL data,
@@ -424,7 +969,16 @@ interface ProgressSinkOptions {
424
969
  * - "daily": {dir}/{base}-{YYYY-MM-DD}{ext}
425
970
  */
426
971
  naming?: "single" | "per-invocation" | "daily";
427
- /** Label for per-invocation naming (e.g. workflow ID). */
972
+ /**
973
+ * Identity of the invocation, used only by `per-invocation` naming. The
974
+ * timestamp in that name is second-granular, so this is what keeps two runs
975
+ * that start in the same second in separate files. `executeTask` /
976
+ * `executeWorkflow` pass the task / workflow id.
977
+ *
978
+ * It becomes a component of the resolved file name, so it must be usable as
979
+ * one — `pathSegmentForId` rejects anything that would resolve the log
980
+ * outside the directory `file` declares.
981
+ */
428
982
  label?: string;
429
983
  }
430
984
  interface ProgressSink {
@@ -468,6 +1022,14 @@ declare class AgentLogWriter {
468
1022
  private memoryStore;
469
1023
  constructor(options?: AgentLogWriterOptions);
470
1024
  getMemoryStore(): FileMemoryStore;
1025
+ /**
1026
+ * Where one run's event log lives. The writer and the reader must agree on
1027
+ * the name, so both derive it here rather than each spelling it out — and
1028
+ * with it, the check that keeps a run id inside `baseDir`.
1029
+ */
1030
+ private runLogPath;
1031
+ /** Where one run's handoff payload lives. Shared by the writer and reader. */
1032
+ private handoffPath;
471
1033
  writeRunEvent(runId: string, event: RunLogEvent): Promise<void>;
472
1034
  readRunLog(runId: string): Promise<RunLogEvent[]>;
473
1035
  writeHandoff(runId: string, step: string, data: unknown): Promise<void>;
@@ -500,6 +1062,73 @@ interface CreateAdapterOptions {
500
1062
  */
501
1063
  declare function createAdapter(name: string, options?: CreateAdapterOptions): Promise<SdkAdapter>;
502
1064
 
1065
+ interface OperationMemoryRefConfig {
1066
+ output?: boolean;
1067
+ input?: boolean;
1068
+ provider?: string;
1069
+ compat?: string;
1070
+ }
1071
+ interface MemoryStoreEntry {
1072
+ result: unknown;
1073
+ memoryRef: MemoryRef;
1074
+ }
1075
+ /**
1076
+ * The component an invocation is for: the IR that declares its operations and
1077
+ * the binding that dispatches them.
1078
+ *
1079
+ * `createRuntimeBinding` is the only place that holds both — it is handed the IR
1080
+ * and returns the binding — and `dispatchOperation` is the only call from here
1081
+ * into `ctx.runtime`. So this pair is how the execution path below learns which
1082
+ * component it is executing, which is what `createComponentScope` needs to scope
1083
+ * tools and guardrails to it (#338).
1084
+ */
1085
+ interface InvokedComponent {
1086
+ ir: ComponentIR;
1087
+ binding: RuntimeBinding;
1088
+ }
1089
+ interface AaacInvocationContext {
1090
+ runtime: AaacRuntime;
1091
+ /** The component whose operation is being dispatched. Set by createRuntimeBinding. */
1092
+ component?: InvokedComponent;
1093
+ policy?: AaacPolicy;
1094
+ observer?: AaacObserver;
1095
+ parentRunId?: string;
1096
+ abortSignal?: AbortSignal;
1097
+ memoryRef?: MemoryRef;
1098
+ memoryStore?: MemoryStore;
1099
+ logWriter?: AgentLogWriter;
1100
+ /** Populated when resuming from a previous memory_ref. */
1101
+ resumedState?: unknown;
1102
+ /** Current run ID for this invocation chain. */
1103
+ runId?: string;
1104
+ }
1105
+ interface AaacRuntime {
1106
+ runWorkflow(workflowId: string, options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext): Promise<unknown>;
1107
+ runTask(taskId: string, options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext): Promise<unknown>;
1108
+ }
1109
+ interface AaacPolicy {
1110
+ assertAllowed(operationName: string): void | Promise<void>;
1111
+ }
1112
+ interface AaacObserver {
1113
+ onOperationStart?(operationName: string, input: unknown): void;
1114
+ onOperationEnd?(operationName: string, output: unknown): void;
1115
+ onOperationError?(operationName: string, error: Error): void;
1116
+ /**
1117
+ * Emit an agent-axis event to the observability pipeline.
1118
+ * Structurally matches EventCollector.emit() from @aaac/observability.
1119
+ * Pass an EventCollector instance to wire up the full pipeline.
1120
+ * When undefined, emission is a no-op (observer is optional).
1121
+ */
1122
+ emit?: ObserverEmitFn;
1123
+ }
1124
+ type OperationHandler = (options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext) => Promise<unknown>;
1125
+ interface RuntimeBinding {
1126
+ execute(operationName: string, options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext): Promise<unknown>;
1127
+ getOperationNames(): string[];
1128
+ getOperationIR(name: string): OperationIR | undefined;
1129
+ }
1130
+ declare function createRuntimeBinding(component: ComponentIR, handlers?: Record<string, OperationHandler>): RuntimeBinding;
1131
+
503
1132
  /**
504
1133
  * High-level execution APIs — executeTask / executeWorkflow
505
1134
  *
@@ -520,12 +1149,30 @@ interface ExecuteOptions {
520
1149
  model?: string;
521
1150
  dsl: Record<string, unknown>;
522
1151
  projectDslPath?: string;
523
- logFile?: string;
1152
+ /**
1153
+ * Progress-log settings from the project manifest's `logging.progress_log`,
1154
+ * auto-wired by createProjectRuntime. Absent → stderr only.
1155
+ */
1156
+ progressLog?: ProgressLogConfig;
524
1157
  adapterOptions?: Partial<CreateAdapterOptions>;
525
1158
  maxFollowUps?: number;
526
1159
  maxRetries?: number;
527
1160
  /** Pre-resolved component from BoundResolver (skips runtime resolve). */
528
1161
  resolvedComponent?: ResolvedComponent;
1162
+ /**
1163
+ * The component whose operation is being executed, carried here by
1164
+ * `createProjectRuntime` from the invocation context `createRuntimeBinding`
1165
+ * built (component-binding.ts). It is what makes the run's `ComponentScope` a
1166
+ * scope of something: the component's operation names are one of the two
1167
+ * namespaces `toolsByAgent` resolves declarations in, and its id is what says
1168
+ * which toolchains write their `operations` in it (#338).
1169
+ *
1170
+ * Absent only when `executeTask` / `executeWorkflow` are called directly, by
1171
+ * a caller that named no component. The scope is still built — guardrails,
1172
+ * library tools and the tool-id namespace do not depend on the IR — with no
1173
+ * component operations to wire.
1174
+ */
1175
+ component?: InvokedComponent;
529
1176
  /** Component id for BoundResolver cache keying. */
530
1177
  componentId?: string;
531
1178
  /** Software binding paths for runtime guardrail resolution. */
@@ -544,12 +1191,16 @@ interface ExecuteOptions {
544
1191
  */
545
1192
  observer?: ObserverEmitFn;
546
1193
  /**
547
- * Optional toolchain-check observation config. When set together with `observer`,
548
- * the workflow runner runs these checks once post-run and emits one
549
- * toolchain.execution span per check (OBSERVATION ONLY — never changes the
550
- * workflow outcome). Auto-wired from project.yaml `toolchains` + `bindings.observability`
551
- * by createProjectRuntime; `observer`/`parentSpanId` are injected by runWorkflow.
552
- * Only consumed by executeWorkflow (toolchain checks are a run-level concern).
1194
+ * The project manifest's `toolchains:`, auto-wired by createProjectRuntime.
1195
+ *
1196
+ * Two consumers on this path, both driven from this one value:
1197
+ * - `resolveExecutionContext` hands `toolchainsPath` to `BoundResolver`,
1198
+ * which derives each agent's toolchains from the artifacts it may touch
1199
+ * and so decides what reaches `buildCandidateAgents` (#336).
1200
+ * - `runWorkflow` runs the declared `checks` once post-run and emits one
1201
+ * toolchain.execution span per check (OBSERVATION ONLY — never changes
1202
+ * the workflow outcome), which is why it also gates itself on `observer`.
1203
+ * `observer`/`parentSpanId` are injected there.
553
1204
  */
554
1205
  toolchain?: RunToolchainChecksOptions;
555
1206
  /** Per-class adapter/model mapping from project.yaml (used by executeWorkflow / executeTask). */
@@ -598,57 +1249,6 @@ interface ExecuteWorkflowOptions extends ExecuteOptions {
598
1249
  }
599
1250
  declare function executeWorkflow(workflowId: string, options: ExecuteWorkflowOptions): Promise<WorkflowResult>;
600
1251
 
601
- interface OperationMemoryRefConfig {
602
- output?: boolean;
603
- input?: boolean;
604
- provider?: string;
605
- compat?: string;
606
- }
607
- interface MemoryStoreEntry {
608
- result: unknown;
609
- memoryRef: MemoryRef;
610
- }
611
- interface AaacInvocationContext {
612
- runtime: AaacRuntime;
613
- policy?: AaacPolicy;
614
- observer?: AaacObserver;
615
- parentRunId?: string;
616
- abortSignal?: AbortSignal;
617
- memoryRef?: MemoryRef;
618
- memoryStore?: MemoryStore;
619
- logWriter?: AgentLogWriter;
620
- /** Populated when resuming from a previous memory_ref. */
621
- resumedState?: unknown;
622
- /** Current run ID for this invocation chain. */
623
- runId?: string;
624
- }
625
- interface AaacRuntime {
626
- runWorkflow(workflowId: string, options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext): Promise<unknown>;
627
- runTask(taskId: string, options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext): Promise<unknown>;
628
- }
629
- interface AaacPolicy {
630
- assertAllowed(operationName: string): void | Promise<void>;
631
- }
632
- interface AaacObserver {
633
- onOperationStart?(operationName: string, input: unknown): void;
634
- onOperationEnd?(operationName: string, output: unknown): void;
635
- onOperationError?(operationName: string, error: Error): void;
636
- /**
637
- * Emit an agent-axis event to the observability pipeline.
638
- * Structurally matches EventCollector.emit() from @aaac/observability.
639
- * Pass an EventCollector instance to wire up the full pipeline.
640
- * When undefined, emission is a no-op (observer is optional).
641
- */
642
- emit?: ObserverEmitFn;
643
- }
644
- type OperationHandler = (options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext) => Promise<unknown>;
645
- interface RuntimeBinding {
646
- execute(operationName: string, options: Record<string, unknown>, input: unknown, ctx: AaacInvocationContext): Promise<unknown>;
647
- getOperationNames(): string[];
648
- getOperationIR(name: string): OperationIR | undefined;
649
- }
650
- declare function createRuntimeBinding(component: ComponentIR, handlers?: Record<string, OperationHandler>): RuntimeBinding;
651
-
652
1252
  /**
653
1253
  * Standard project runtime — the reusable, CLI-facing `AaacRuntime` that every
654
1254
  * generated component CLI uses, so that NO caller hand-writes `ctx.runtime`.
@@ -720,20 +1320,79 @@ interface ProjectRuntime {
720
1320
  */
721
1321
  declare function createProjectRuntime(options: CreateProjectRuntimeOptions): Promise<ProjectRuntime>;
722
1322
 
1323
+ /**
1324
+ * The component id an invocation that named no component runs under. Shared
1325
+ * with `resolveExecutionContext` (lib/execute.ts), which keys `BoundResolver`
1326
+ * on the same value, so the scope's id and the resolved component's id are one
1327
+ * name and not two.
1328
+ */
1329
+ declare const DEFAULT_COMPONENT_ID = "default";
723
1330
  interface ComponentScope {
724
1331
  componentId: string;
725
- componentIR: ComponentIR;
726
- binding: RuntimeBinding;
1332
+ /**
1333
+ * Present when the invocation named a component — i.e. when it was dispatched
1334
+ * through a `createRuntimeBinding` binding, which is every invocation the
1335
+ * generated component client makes. Absent when `executeTask` /
1336
+ * `executeWorkflow` are called directly with no component to scope to; there
1337
+ * are then no operation names to wire and nothing to check them against.
1338
+ */
1339
+ componentIR?: ComponentIR;
1340
+ binding?: RuntimeBinding;
727
1341
  toolsByAgent: Map<string, string[]>;
728
- guardrailsByAgent: Map<string, unknown[]>;
1342
+ guardrailsByAgent: Map<string, GuardrailRuleData>;
729
1343
  libraryTools?: LibraryToolRegistry;
730
1344
  toolchainsByAgent?: Map<string, ResolvedToolchain[]>;
731
1345
  }
732
1346
  interface CreateComponentScopeOptions {
1347
+ /** The component whose operation is being executed (component-binding.ts). */
1348
+ component?: InvokedComponent;
1349
+ /**
1350
+ * The effective DSL — merged overlay, artifact-bound — that declares `tools`
1351
+ * and `agents`. It is where both halves of the tool-id namespace are written,
1352
+ * and it exists whether or not a software binding was resolved, so it is an
1353
+ * input of its own rather than a field read off `resolvedComponent`.
1354
+ */
1355
+ dsl?: Record<string, unknown>;
733
1356
  resolvedComponent?: ResolvedComponent;
734
- libraryToolDefs?: LibraryToolDefinition[];
1357
+ /**
1358
+ * The in-process tool registry this scope owns. Held rather than built: a
1359
+ * registry is constructed by `createLibraryToolRegistry` /
1360
+ * `createRegistryFromSdkTools` (lib/library-tool-binding.ts), and what §5.2 of
1361
+ * the architecture asks of the scope is that the registry be the calling
1362
+ * component's rather than a process-wide one.
1363
+ */
1364
+ libraryTools?: LibraryToolRegistry;
1365
+ }
1366
+ /**
1367
+ * A declaration that reaches `toolsByAgent` named something the namespace it is
1368
+ * written in does not contain.
1369
+ *
1370
+ * Two declarations reach it, each in its own namespace:
1371
+ *
1372
+ * - `toolchains[*].operations` of a toolchain naming THIS component — this
1373
+ * component's operation names (#335).
1374
+ * - `agents[*].can_execute_tools` — a tool id: a DSL `tools` key or the id of
1375
+ * a toolchain the resolver loaded (#337).
1376
+ *
1377
+ * Both used to be matched against the operation names and whatever missed was
1378
+ * dropped without a word: `agents/toolchain-contracts.yaml` could ask for
1379
+ * `audit-governance` while the operation is `auditGovernance`, and
1380
+ * `reflector.can_execute_tools: [observ-query]` — a correctly spelled tool id —
1381
+ * was thrown away for not being an operation name. Either way an agent shipped
1382
+ * a tool short and nothing failed.
1383
+ *
1384
+ * One error for both because there is one defect: a name that resolves to
1385
+ * nothing. It carries both namespaces so the reader can see which one the
1386
+ * offending line was meant to be written in.
1387
+ */
1388
+ declare class UnresolvedScopeDeclarationError extends Error {
1389
+ readonly componentId: string;
1390
+ readonly unresolved: string[];
1391
+ readonly operationNames: string[];
1392
+ readonly toolIds: string[];
1393
+ constructor(componentId: string, unresolved: string[], operationNames: string[], toolIds: string[]);
735
1394
  }
736
- declare function createComponentScope(componentIR: ComponentIR, binding: RuntimeBinding, options?: CreateComponentScopeOptions): ComponentScope;
1395
+ declare function createComponentScope(options?: CreateComponentScopeOptions): ComponentScope;
737
1396
 
738
1397
  /**
739
1398
  * Project artifact composition — the ONE place where the project manifest's
@@ -836,6 +1495,12 @@ interface GuardrailListEntry {
836
1495
  interface ListGuardrailsResult {
837
1496
  policy: string | undefined;
838
1497
  entries: GuardrailListEntry[];
1498
+ /**
1499
+ * Guardrail-configuration findings. An entry whose `action` is `unresolved`
1500
+ * is explained here — without them the report shows the symptom and hides
1501
+ * the cause (#293).
1502
+ */
1503
+ diagnostics: GuardrailDiagnostic[];
839
1504
  }
840
1505
  /**
841
1506
  * List all active guardrails and their enforcement settings.
@@ -883,6 +1548,7 @@ declare const ClaudeConfigSchema: z.ZodObject<{
883
1548
  output?: string | undefined;
884
1549
  template?: string | undefined;
885
1550
  } | undefined>>;
1551
+ agents: z.ZodDefault<z.ZodBoolean>;
886
1552
  }, z.core.$strip>>;
887
1553
  guard_command: z.ZodOptional<z.ZodString>;
888
1554
  component_id: z.ZodOptional<z.ZodString>;
@@ -891,12 +1557,25 @@ type ClaudeConfig = z.infer<typeof ClaudeConfigSchema>;
891
1557
  /** Parse and default-fill an opaque config payload from component.yaml. */
892
1558
  declare function parseClaudeConfig(raw: unknown): ClaudeConfig;
893
1559
 
894
- type FileAction = "created" | "updated" | "unchanged";
1560
+ /**
1561
+ * `deleted` is reported for a generated file removed because the DSL no longer
1562
+ * declares it (a stale `.claude/agents/*.md` is a live Claude Code subagent, so
1563
+ * leaving it behind is the very DSL/harness divergence this generator exists to
1564
+ * remove).
1565
+ */
1566
+ type FileAction = "created" | "updated" | "unchanged" | "deleted";
895
1567
  interface SyncOptions {
896
1568
  projectRoot: string;
897
1569
  /** Opaque config payload from component.yaml (validated here). */
898
1570
  config: unknown;
899
- /** Resolved agent DSL (plain object; the value the runtime embeds). */
1571
+ /**
1572
+ * The component's bundled `/$embedded/` DSL — the value the runtime embeds,
1573
+ * BEFORE any project overlay. What a project actually runs is this DSL
1574
+ * overlaid with its manifest's `agents:`, and resolving that overlay is this
1575
+ * module's job (`resolveDslSources`), not the caller's: the caller cannot know
1576
+ * the workspace members, and one caller resolving it differently from another
1577
+ * is exactly how `.claude/` came to disagree with the navigation index (#274).
1578
+ */
900
1579
  dsl: Record<string, unknown>;
901
1580
  /** When true, compute changes without writing. */
902
1581
  dryRun?: boolean;
@@ -909,9 +1588,10 @@ interface SyncResult {
909
1588
  }
910
1589
  interface CheckResult {
911
1590
  inSync: boolean;
1591
+ /** `orphaned` = present on disk inside a generated directory, absent from the DSL. */
912
1592
  drift: Array<{
913
1593
  path: string;
914
- reason: "missing" | "changed";
1594
+ reason: "missing" | "changed" | "orphaned";
915
1595
  }>;
916
1596
  }
917
1597
  /**
@@ -978,4 +1658,4 @@ declare function executePrompt(message: string, ir: ComponentIR, binding: Runtim
978
1658
  /** Package version string. */
979
1659
  declare const version: string;
980
1660
 
981
- export { type AaacInvocationContext, type AaacObserver, type AaacPolicy, type AaacRuntime, AgentContractLike, AgentLogWriter, type AgentLogWriterOptions, type AgentPlugin, type AnalyzeImpactInput, type AnalyzerBridge, type AnalyzerBridgeOptions, ArtifactBindingConfig, type ArtifactResolveOptions, type ArtifactResolveResult, type BuildCallGraphInput, type CheckResult as ClaudeCheckResult, type ClaudeConfig, type FileAction as ClaudeFileAction, type SyncOptions as ClaudeSyncOptions, type SyncResult as ClaudeSyncResult, type ComponentScope, type CreateAdapterOptions, type CreateComponentScopeOptions, type CreateProjectRuntimeOptions, DelegateStep, type DslContext, DslValidationError, type EvaluateGuardrailOptions, type EvaluateGuardrailResult, type ExecuteOptions, type ExecuteTaskOptions, type ExecuteWorkflowOptions, FileMemoryStore, type GenerateContextPackInput, type GuardStatusOptions, type GuardStatusResult, GuardrailCheckResult, GuardrailHooks, type GuardrailListEntry, type GuardrailResult, HandoffInput, HookResponse, LibraryToolDefinition, LibraryToolRegistry, type ListGuardrailsOptions, type ListGuardrailsResult, type LoadDslOptions, MemoryRef, MemoryStore, type MemoryStoreEntry, ModelMappingConfig, ObserverEmitFn, type OperationHandler, type OperationMemoryRefConfig, type OperationToolDef, type PermissionMode, type PluginLoadResult, PluginRegistry, type ProcessEditOptions, type ProcessTaskOptions, type ProcessWorkflowOptions, type ProgressSink, type ProgressSinkOptions, type ProjectRuntime, type PromptBuilderArgs, PromptBuilderOptions, type PromptExecuteOptions, type PromptResult, type RequiredEntities, type ResolvedAdapterSelection, ResolvedComponent, ResolvedToolchain, type RunLogEvent, RunToolchainChecksOptions, type Runtime, type RuntimeBinding, type RuntimeConfig, SdkAdapter, SdkFunctionTool, StepCompleteEvent, StepResult, TaskContext, TaskContractLike, type TaskHookContext, TaskOutcome, TaskRunResult, WORKFLOW_INPUT_STEP_ID, WorkflowBuilder, type WorkflowHookContext, type WorkflowInputHandoff, type WorkflowInputOutput, WorkflowRegistries, WorkflowResult, buildRegistriesFromDsl, buildWorkflowInputOutput, checkClaude, createAdapter, createAnalyzerBridge, createComponentScope, createProgressSink, createProjectRuntime, createRuntime, createRuntimeBinding, emitProcessEdit, emitProcessTaskClose, emitProcessTaskOpen, emitProcessWorkflowClose, emitProcessWorkflowOpen, evaluateGuardrail, executePrompt, executeTask, executeWorkflow, findProjectConfig, formatWorkflowInputContext, guardStatus, isContextPack, isFileEditTool, jsonSchemaToZod, listGuardrails, loadDslContext, loadPlugins, loadPluginsFromDirectory, loadPluginsFromPaths, operationsToTools, parseClaudeConfig, parseRouterResponse, pluginRegistry, renderContextPackPrompt, resolveArtifacts, stepDependsOnWorkflowInput, syncClaude, version };
1661
+ export { type AaacInvocationContext, type AaacObserver, type AaacPolicy, type AaacRuntime, type AdapterOrFactory, AgentContractLike, AgentLogWriter, type AgentLogWriterOptions, type AgentPlugin, type AnalyzeImpactInput, type AnalyzerBridge, type AnalyzerBridgeOptions, type ArtifactBindingConfig, type ArtifactResolveOptions, type ArtifactResolveResult, type BoundResolveOptions, BoundResolver, type BuildCallGraphInput, type CheckResult as ClaudeCheckResult, type ClaudeConfig, type FileAction as ClaudeFileAction, type SyncOptions as ClaudeSyncOptions, type SyncResult as ClaudeSyncResult, type ComponentScope, type ConvergenceEnvelope, type ConvergenceEnvelopePayload, type CreateAdapterOptions, type CreateComponentScopeOptions, type CreateProjectRuntimeOptions, DEFAULT_COMPONENT_ID, type DelegateStep, type DslContext, DslValidationError, type EvaluateGuardrailOptions, type EvaluateGuardrailResult, type EvaluateStep, type ExecuteOptions, type ExecuteTaskOptions, type ExecuteWorkflowOptions, FileMemoryStore, type GateStep, type GenerateContextPackInput, type GuardStatusOptions, type GuardStatusResult, GuardrailCheckFunctions, GuardrailCheckResult, GuardrailHooks, type GuardrailListEntry, type GuardrailResult, GuardrailRuleData, type HandoffInput, HookResponse, type InvokedComponent, LibraryToolRegistry, type ListGuardrailsOptions, type ListGuardrailsResult, type LoadDslOptions, MemoryRef, MemoryStore, type MemoryStoreEntry, type ModelAwareSdkAdapterFactory, type ModelMappingConfig, type ModelResolver, type ModelResolverOptions, ObservabilityIds, ObserverEmitFn, type OperationHandler, type OperationMemoryRefConfig, type OperationToolDef, type PermissionMode, type PluginLoadResult, PluginRegistry, type ProcessEditOptions, type ProcessTaskOptions, type ProcessWorkflowOptions, type ProgressSink, type ProgressSinkOptions, type ProjectRuntime, type PromptBuilderArgs, PromptBuilderOptions, type PromptExecuteOptions, type PromptResult, type ReceiveSpec, type RequiredEntities, type ResolvedAdapterSelection, type ResolvedComponent, type ResolvedModel, type ResolvedToolchain, type RunLogEvent, type RunToolchainChecksOptions, type Runtime, type RuntimeBinding, type RuntimeConfig, SdkAdapter, type SdkAdapterFactory, SdkFunctionTool, type StepCompleteEvent, type StepResult, TaskContext, TaskContractLike, type TaskHookContext, TaskOutcome, TaskRunResult, type ToolchainCheckResult, type ToolchainManifest, ToolchainManifestSchema, UnresolvedScopeDeclarationError, WORKFLOW_INPUT_STEP_ID, WorkflowBuilder, type WorkflowContractLike, type WorkflowHookContext, type WorkflowInputHandoff, type WorkflowInputOutput, type WorkflowInvocation, type WorkflowRegistries, type WorkflowResult, type WorkflowRunOptions, type WorkflowStep, buildGateEvaluationPrompt, buildPerAgentGuardrails, buildRegistriesFromDsl, buildWorkflowInputOutput, checkClaude, createAdapter, createAnalyzerBridge, createComponentScope, createModelResolver, createProgressSink, createProjectRuntime, createRuntime, createRuntimeBinding, deriveToolchainsForAgents, emitProcessEdit, emitProcessTaskClose, emitProcessTaskOpen, emitProcessWorkflowClose, emitProcessWorkflowOpen, evaluateGuardrail, executePrompt, executeTask, executeWorkflow, findProjectConfig, formatWorkflowInputContext, getEffectiveGuardrailIds, getGuardrailRulesForAgent, guardStatus, guardrailContextToRuleData, isContextPack, isFileEditTool, jsonSchemaToZod, listGuardrails, loadDslContext, loadPlugins, operationsToTools, parseClaudeConfig, parseGateEvaluationResponse, parseRouterResponse, pluginRegistry, renderContextPackPrompt, resolveArtifacts, runToolchainChecks, runWorkflow, stepDependsOnWorkflowInput, syncClaude, version };