@aaac/runtime 0.1.6 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/adapters/adk-sdk.d.ts +2 -2
- package/dist/adapters/claude-agent-sdk.d.ts +2 -2
- package/dist/adapters/mock.d.ts +2 -1
- package/dist/adapters/openai-agents-sdk.d.ts +2 -2
- package/dist/generator/index.d.ts +91 -2
- package/dist/generator/index.js +131 -8
- package/dist/generator/index.js.map +1 -1
- package/dist/index.d.ts +5 -313
- package/dist/index.js +25 -3
- package/dist/index.js.map +1 -1
- package/dist/{task-runner-R-_kW3U6.d.ts → task-runner-Dw8oWJD6.d.ts} +437 -46
- package/package.json +1 -1
- package/dist/guardrail-hooks-C8G5NGsj.d.ts +0 -83
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
+
import { G as GuardrailContext } from './context-B_bekYiE.js';
|
|
2
3
|
import { EmitInput, ExecutionEnvelope } from '@aaac/observability';
|
|
3
4
|
|
|
4
5
|
/**
|
|
@@ -59,61 +60,125 @@ interface LibraryToolRegistry {
|
|
|
59
60
|
declare function createLibraryToolRegistry(): LibraryToolRegistry;
|
|
60
61
|
|
|
61
62
|
/**
|
|
62
|
-
*
|
|
63
|
+
* SDK Guardrail Hook Bridge — generic adapter from guardrail check functions
|
|
64
|
+
* + plugin guardrails to SDK-compatible hook responses.
|
|
63
65
|
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
66
|
+
* Embedded guardrail rules are converted via createGuardrailHooksFromRules(),
|
|
67
|
+
* which delegates to createGuardrailHooks(). All hook logic lives here.
|
|
68
|
+
*/
|
|
69
|
+
interface GuardrailCheckResult {
|
|
70
|
+
guardrail_id: string;
|
|
71
|
+
passed: boolean;
|
|
72
|
+
action: "block" | "warn" | "shadow" | "info";
|
|
73
|
+
message: string;
|
|
74
|
+
}
|
|
75
|
+
interface HookResponse {
|
|
76
|
+
permission?: "deny";
|
|
77
|
+
user_message?: string;
|
|
78
|
+
agent_message?: string;
|
|
79
|
+
additionalContext?: string;
|
|
80
|
+
}
|
|
81
|
+
interface GuardrailRule {
|
|
82
|
+
guardrail_id: string;
|
|
83
|
+
pattern: string;
|
|
84
|
+
action: "block" | "warn" | "shadow" | "info";
|
|
85
|
+
message: string;
|
|
86
|
+
file_glob?: string;
|
|
87
|
+
exclude_glob?: string;
|
|
88
|
+
}
|
|
89
|
+
interface GuardrailRuleData {
|
|
90
|
+
commandRules: GuardrailRule[];
|
|
91
|
+
fileRules: GuardrailRule[];
|
|
92
|
+
contentRules: GuardrailRule[];
|
|
93
|
+
}
|
|
94
|
+
interface GuardrailCheckFunctions {
|
|
95
|
+
checkCommand: (command: string) => GuardrailCheckResult[];
|
|
96
|
+
checkFilePath: (filePath: string) => GuardrailCheckResult[];
|
|
97
|
+
checkContent: (filePath: string, content: string) => GuardrailCheckResult[];
|
|
98
|
+
}
|
|
99
|
+
interface HookContext {
|
|
100
|
+
/** Agent id for per-agent guardrail filtering. */
|
|
101
|
+
agentId?: string;
|
|
102
|
+
command?: string;
|
|
103
|
+
filePath?: string;
|
|
104
|
+
content?: string;
|
|
105
|
+
}
|
|
106
|
+
interface GuardrailHooks {
|
|
107
|
+
beforeShellExecution: (input: {
|
|
108
|
+
command?: string;
|
|
109
|
+
}) => HookResponse;
|
|
110
|
+
preToolUse: (input: {
|
|
111
|
+
tool_name?: string;
|
|
112
|
+
tool_input?: {
|
|
113
|
+
file_path?: string;
|
|
114
|
+
path?: string;
|
|
115
|
+
};
|
|
116
|
+
}) => HookResponse;
|
|
117
|
+
afterFileEdit: (input: {
|
|
118
|
+
file_path?: string;
|
|
119
|
+
content?: string;
|
|
120
|
+
}) => HookResponse;
|
|
121
|
+
runChecks: (ctx: HookContext) => GuardrailCheckResult[];
|
|
122
|
+
}
|
|
123
|
+
declare function getBlockingViolations(results: GuardrailCheckResult[]): GuardrailCheckResult[];
|
|
124
|
+
declare function getWarnings(results: GuardrailCheckResult[]): GuardrailCheckResult[];
|
|
125
|
+
declare function hasBlockingViolation(results: GuardrailCheckResult[]): boolean;
|
|
126
|
+
/**
|
|
127
|
+
* Create SDK hook functions from generated guardrail check functions.
|
|
71
128
|
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
129
|
+
* Merges DSL-generated checks with plugin-registered guardrails and
|
|
130
|
+
* returns hook functions in the format expected by the Claude SDK,
|
|
131
|
+
* plus a generic runChecks() for programmatic use.
|
|
75
132
|
*/
|
|
76
|
-
|
|
133
|
+
declare function createGuardrailHooks(checks: GuardrailCheckFunctions): GuardrailHooks;
|
|
77
134
|
/**
|
|
78
|
-
* SDK
|
|
79
|
-
* to. Adapters translate this into their provider's native subagent shape.
|
|
135
|
+
* Create SDK hook functions from embedded guardrail rule data.
|
|
80
136
|
*/
|
|
81
|
-
interface CandidateAgent {
|
|
82
|
-
/** Agent id (used as the SDK subagent key / name). */
|
|
83
|
-
name: string;
|
|
84
|
-
/** When to use this agent — the routing hint shown to the delegating LLM. */
|
|
85
|
-
description: string;
|
|
86
|
-
/** The agent's system prompt (role / purpose / responsibilities / constraints / rules). */
|
|
87
|
-
prompt: string;
|
|
88
|
-
/** Optional allowed tool names (omit to inherit from the parent agent). */
|
|
89
|
-
tools?: string[];
|
|
90
|
-
/** Optional model id (omit to inherit from the parent agent). */
|
|
91
|
-
model?: string;
|
|
92
|
-
}
|
|
93
137
|
/**
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
* Shared by `buildSplitTaskPrompt` (entry agent system prompt) and
|
|
98
|
-
* `buildCandidateAgents` (each candidate's `prompt`) so both stay in sync.
|
|
138
|
+
* Create SDK hooks scoped to a single agent from a per-agent guardrail map.
|
|
139
|
+
* Returns empty-passing hooks when the agent has no rules in the map.
|
|
99
140
|
*/
|
|
100
|
-
declare function
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
entryAgentId?: string;
|
|
104
|
-
/**
|
|
105
|
-
* When provided (typically the entry agent's `can_invoke_agents`), restrict
|
|
106
|
-
* candidates to these agent ids. Omit to allow every non-entry agent.
|
|
107
|
-
*/
|
|
108
|
-
allowedAgentIds?: readonly string[];
|
|
109
|
-
}
|
|
141
|
+
declare function createGuardrailHooksForAgent(agentId: string, perAgent: Map<string, GuardrailRuleData>): GuardrailHooks;
|
|
142
|
+
declare function createGuardrailHooksFromRules(rules: GuardrailRuleData): GuardrailHooks;
|
|
143
|
+
|
|
110
144
|
/**
|
|
111
|
-
*
|
|
145
|
+
* ModelResolver — resolves a model_class to a concrete adapter + model pair.
|
|
112
146
|
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
147
|
+
* Resolution priority (highest wins):
|
|
148
|
+
* 1. AGENT_RUNTIME_MODEL_{FAST|STANDARD|THINKING} env var
|
|
149
|
+
* 2. AGENT_RUNTIME_MODEL env var (catch-all fallback)
|
|
150
|
+
* 3. agent-runtime.config.yaml model_mapping.<class>
|
|
151
|
+
* 4. CLI --adapter + adapter default model
|
|
115
152
|
*/
|
|
116
|
-
|
|
153
|
+
type ModelClass = "fast" | "standard" | "thinking";
|
|
154
|
+
interface ResolvedModel {
|
|
155
|
+
adapter: string;
|
|
156
|
+
model?: string;
|
|
157
|
+
}
|
|
158
|
+
interface ModelResolver {
|
|
159
|
+
resolve(modelClass: ModelClass | undefined): ResolvedModel;
|
|
160
|
+
}
|
|
161
|
+
interface ModelMappingConfig {
|
|
162
|
+
fast?: {
|
|
163
|
+
adapter: string;
|
|
164
|
+
model?: string;
|
|
165
|
+
};
|
|
166
|
+
standard?: {
|
|
167
|
+
adapter: string;
|
|
168
|
+
model?: string;
|
|
169
|
+
};
|
|
170
|
+
thinking?: {
|
|
171
|
+
adapter: string;
|
|
172
|
+
model?: string;
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
interface ModelResolverOptions {
|
|
176
|
+
modelMapping?: ModelMappingConfig;
|
|
177
|
+
fallbackAdapter: string;
|
|
178
|
+
fallbackModel?: string;
|
|
179
|
+
env?: Record<string, string | undefined>;
|
|
180
|
+
}
|
|
181
|
+
declare function createModelResolver(options: ModelResolverOptions): ModelResolver;
|
|
117
182
|
|
|
118
183
|
/**
|
|
119
184
|
* observability-bridge.ts
|
|
@@ -210,6 +275,332 @@ declare function emitToolchainOpen(observer: ObserverEmitFn | undefined, parentS
|
|
|
210
275
|
*/
|
|
211
276
|
declare function emitToolchainClose(observer: ObserverEmitFn | undefined, spanId: string, toolchainId: string, operation: string, durationMs: number, status: "success" | "failure", errorMessage?: string): void;
|
|
212
277
|
|
|
278
|
+
/**
|
|
279
|
+
* Workflow Runner — orchestrates a DSL workflow as a sequence of task executions
|
|
280
|
+
*
|
|
281
|
+
* Programmatic control flow that replaces LLM-driven step interpretation:
|
|
282
|
+
*
|
|
283
|
+
* 1. Load workflow contract (ordered steps)
|
|
284
|
+
* 2. Run plugin beforeWorkflow hooks
|
|
285
|
+
* 3. For each step:
|
|
286
|
+
* - delegate → call task-runner with followUp/retry recovery
|
|
287
|
+
* - gate → pause and wait for user input
|
|
288
|
+
* 4. Validate each result against handoff schema
|
|
289
|
+
* 5. Accumulate context between steps
|
|
290
|
+
* 6. Run plugin afterWorkflow hooks
|
|
291
|
+
*/
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* A factory that creates independent SdkAdapter instances.
|
|
295
|
+
* Used by runWorkflow to allocate one adapter per parallel step,
|
|
296
|
+
* avoiding session-level serialization in stateful SDK adapters.
|
|
297
|
+
*/
|
|
298
|
+
type SdkAdapterFactory = () => SdkAdapter;
|
|
299
|
+
/**
|
|
300
|
+
* Model-aware adapter factory. Accepts a model_class and returns an adapter
|
|
301
|
+
* configured for that capability level (possibly a different provider/model).
|
|
302
|
+
*/
|
|
303
|
+
type ModelAwareSdkAdapterFactory = (modelClass?: ModelClass) => SdkAdapter | Promise<SdkAdapter>;
|
|
304
|
+
/** Accepts either a single adapter (serial/shared) or a factory (parallel-safe). */
|
|
305
|
+
type AdapterOrFactory = SdkAdapter | SdkAdapterFactory | ModelAwareSdkAdapterFactory;
|
|
306
|
+
/** Specification for what a step receives from a dependency. */
|
|
307
|
+
interface ReceiveSpec {
|
|
308
|
+
/** The task id of the dependency step to receive from. If omitted, alias is used as task id. */
|
|
309
|
+
readonly from?: string;
|
|
310
|
+
/** 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. */
|
|
311
|
+
readonly path?: string;
|
|
312
|
+
}
|
|
313
|
+
interface DelegateStep {
|
|
314
|
+
readonly type: "delegate";
|
|
315
|
+
readonly task: string;
|
|
316
|
+
readonly from_agent: string;
|
|
317
|
+
readonly description: string;
|
|
318
|
+
readonly optional: boolean;
|
|
319
|
+
readonly max_retries: number;
|
|
320
|
+
readonly max_follow_ups?: number;
|
|
321
|
+
readonly depends_on?: readonly string[];
|
|
322
|
+
readonly instruction?: string;
|
|
323
|
+
readonly receives?: Record<string, ReceiveSpec>;
|
|
324
|
+
readonly retry?: {
|
|
325
|
+
readonly condition: string;
|
|
326
|
+
readonly fix_task: string;
|
|
327
|
+
readonly revalidate_task?: string;
|
|
328
|
+
};
|
|
329
|
+
}
|
|
330
|
+
interface GateStep {
|
|
331
|
+
readonly type: "gate";
|
|
332
|
+
readonly gate_kind: string;
|
|
333
|
+
readonly description: string;
|
|
334
|
+
readonly depends_on?: readonly string[];
|
|
335
|
+
}
|
|
336
|
+
type WorkflowStep = DelegateStep | GateStep;
|
|
337
|
+
interface WorkflowContractLike {
|
|
338
|
+
readonly id: string;
|
|
339
|
+
readonly description: string;
|
|
340
|
+
readonly steps: readonly WorkflowStep[];
|
|
341
|
+
}
|
|
342
|
+
interface WorkflowRunOptions {
|
|
343
|
+
user_request: string;
|
|
344
|
+
/** Override max follow-up attempts per step (lightweight output-format correction). Default: 2 */
|
|
345
|
+
maxFollowUps?: number;
|
|
346
|
+
/** Override max full retry attempts per step. Default: from DSL step.max_retries */
|
|
347
|
+
maxRetries?: number;
|
|
348
|
+
/** Variables propagated to every TaskContext in the workflow (from WorkflowInvocation.context). */
|
|
349
|
+
variables?: Record<string, unknown>;
|
|
350
|
+
onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
|
|
351
|
+
onStepComplete?: (event: StepCompleteEvent) => void;
|
|
352
|
+
onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
|
|
353
|
+
/**
|
|
354
|
+
* Writable stream for real-time progress output during agent execution.
|
|
355
|
+
* Intermediate events from adapters are formatted and written here.
|
|
356
|
+
* Typical value: process.stderr.
|
|
357
|
+
*/
|
|
358
|
+
progressOutput?: {
|
|
359
|
+
write(chunk: string): unknown;
|
|
360
|
+
};
|
|
361
|
+
/**
|
|
362
|
+
* Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
|
|
363
|
+
* When undefined, no spans are emitted (observer is optional — no-op).
|
|
364
|
+
* Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
|
|
365
|
+
*/
|
|
366
|
+
observer?: ObserverEmitFn;
|
|
367
|
+
}
|
|
368
|
+
/** Typed handoff envelope for workflow input. */
|
|
369
|
+
interface HandoffInput<TType extends string = string, TPayload = unknown> {
|
|
370
|
+
readonly type: TType;
|
|
371
|
+
readonly version?: number;
|
|
372
|
+
readonly payload: TPayload;
|
|
373
|
+
}
|
|
374
|
+
/**
|
|
375
|
+
* Standard runtime invocation envelope. SDK-specific options (openaiThreadId,
|
|
376
|
+
* sessionId, etc.) belong on the adapter constructor — not here.
|
|
377
|
+
*/
|
|
378
|
+
interface WorkflowInvocation<THandoffType extends string = string, TPayload = unknown> {
|
|
379
|
+
workflow: string;
|
|
380
|
+
/** Structured typed handoff input. Takes precedence over user_request if both are set. */
|
|
381
|
+
handoff?: HandoffInput<THandoffType, TPayload>;
|
|
382
|
+
/** Simple string input (convenience shorthand). */
|
|
383
|
+
user_request?: string;
|
|
384
|
+
runtime?: {
|
|
385
|
+
maxFollowUps?: number;
|
|
386
|
+
maxRetries?: number;
|
|
387
|
+
timeoutMs?: number;
|
|
388
|
+
readonly?: boolean;
|
|
389
|
+
dryRun?: boolean;
|
|
390
|
+
};
|
|
391
|
+
hooks?: {
|
|
392
|
+
onStepComplete?: (event: StepCompleteEvent) => void;
|
|
393
|
+
onGate?: (gateKind: string, description: string, stepResults: StepResult[]) => Promise<boolean>;
|
|
394
|
+
onOptionalStep?: (step: DelegateStep, context: TaskContext) => Promise<boolean>;
|
|
395
|
+
};
|
|
396
|
+
/**
|
|
397
|
+
* Writable stream for real-time progress output during agent execution.
|
|
398
|
+
* Intermediate events from adapters are formatted and written here.
|
|
399
|
+
* Typical value: process.stderr.
|
|
400
|
+
*/
|
|
401
|
+
progressOutput?: {
|
|
402
|
+
write(chunk: string): unknown;
|
|
403
|
+
};
|
|
404
|
+
context?: {
|
|
405
|
+
cwd?: string;
|
|
406
|
+
environment?: "local" | "ci" | "remote";
|
|
407
|
+
artifacts?: Record<string, string>;
|
|
408
|
+
variables?: Record<string, unknown>;
|
|
409
|
+
};
|
|
410
|
+
/**
|
|
411
|
+
* Optional observer emit function for agent-axis spans (agent.session, agent.subagent).
|
|
412
|
+
* When undefined, no spans are emitted (observer is optional — no-op).
|
|
413
|
+
* Pass EventCollector.emit.bind(collector) to wire up the full observability pipeline.
|
|
414
|
+
*/
|
|
415
|
+
observer?: ObserverEmitFn;
|
|
416
|
+
}
|
|
417
|
+
interface StepResult {
|
|
418
|
+
step_index: number;
|
|
419
|
+
task_id?: string;
|
|
420
|
+
gate_kind?: string;
|
|
421
|
+
outcome: TaskOutcome | {
|
|
422
|
+
status: "gate_approved";
|
|
423
|
+
} | {
|
|
424
|
+
status: "gate_rejected";
|
|
425
|
+
} | {
|
|
426
|
+
status: "skipped";
|
|
427
|
+
};
|
|
428
|
+
follow_ups_used: number;
|
|
429
|
+
retries_used: number;
|
|
430
|
+
elapsed_ms: number;
|
|
431
|
+
}
|
|
432
|
+
interface StepCompleteEvent {
|
|
433
|
+
workflow_id: string;
|
|
434
|
+
step_index: number;
|
|
435
|
+
step_type: "delegate" | "gate";
|
|
436
|
+
task_id?: string;
|
|
437
|
+
gate_kind?: string;
|
|
438
|
+
outcome_status: string;
|
|
439
|
+
follow_ups_used: number;
|
|
440
|
+
retries_used: number;
|
|
441
|
+
elapsed_ms: number;
|
|
442
|
+
}
|
|
443
|
+
interface WorkflowResult {
|
|
444
|
+
workflow_id: string;
|
|
445
|
+
status: "completed" | "escalated" | "gate_rejected" | "error";
|
|
446
|
+
steps: StepResult[];
|
|
447
|
+
total_elapsed_ms: number;
|
|
448
|
+
escalation_reason?: string;
|
|
449
|
+
error_message?: string;
|
|
450
|
+
}
|
|
451
|
+
interface WorkflowRegistries {
|
|
452
|
+
workflowRegistry?: Record<string, WorkflowContractLike>;
|
|
453
|
+
taskRegistry?: Record<string, TaskContractLike>;
|
|
454
|
+
agentRegistry?: Record<string, AgentContractLike>;
|
|
455
|
+
handoffSchemas?: Record<string, z.ZodType>;
|
|
456
|
+
}
|
|
457
|
+
/** @deprecated Use the WorkflowInvocation overload for typed handoff input. */
|
|
458
|
+
declare function runWorkflow(adapter: AdapterOrFactory, workflowId: string, options: WorkflowRunOptions, registries?: WorkflowRegistries): Promise<WorkflowResult>;
|
|
459
|
+
/** Structured invocation with typed handoff envelope. */
|
|
460
|
+
declare function runWorkflow(adapter: AdapterOrFactory, invocation: WorkflowInvocation, registries?: WorkflowRegistries): Promise<WorkflowResult>;
|
|
461
|
+
declare function buildGateEvaluationPrompt(step: GateStep, priorContext: string): string;
|
|
462
|
+
declare function parseGateEvaluationResponse(response: string): boolean;
|
|
463
|
+
|
|
464
|
+
/**
|
|
465
|
+
* BoundResolver — runtime binding + policy resolution with per-agent isolation.
|
|
466
|
+
*
|
|
467
|
+
* Resolves artifact binding and guardrail/policy in one pass at runtime,
|
|
468
|
+
* producing a per-agent scoped ResolvedComponent. Reuses existing
|
|
469
|
+
* resolveBound(), buildGuardrailContext(), and agent scope resolution.
|
|
470
|
+
*/
|
|
471
|
+
|
|
472
|
+
interface ArtifactBindingConfig {
|
|
473
|
+
source: string;
|
|
474
|
+
mappings?: Record<string, string>;
|
|
475
|
+
}
|
|
476
|
+
interface BoundResolveOptions {
|
|
477
|
+
/** Component identifier — used for cache keying. */
|
|
478
|
+
id: string;
|
|
479
|
+
/** Pre-resolved DSL (e.g. embedded from codegen). */
|
|
480
|
+
embeddedDsl?: Record<string, unknown>;
|
|
481
|
+
/** Path to DSL file — resolved via agent-contracts when no embeddedDsl. */
|
|
482
|
+
dslPath?: string;
|
|
483
|
+
/** Paths to software binding YAML files (guardrail_impl, etc.). */
|
|
484
|
+
bindingPaths?: string[];
|
|
485
|
+
/** Active guardrail policy name from DSL guardrail_policies. */
|
|
486
|
+
activeGuardrailPolicy?: string;
|
|
487
|
+
/** Artifact binding config — resolved via agent-contracts resolveBound(). */
|
|
488
|
+
artifactBinding?: ArtifactBindingConfig;
|
|
489
|
+
/** Path substitutions for artifact binding. */
|
|
490
|
+
paths?: Record<string, string>;
|
|
491
|
+
/** Path to toolchain-contracts.yaml. */
|
|
492
|
+
toolchainContractsPath?: string;
|
|
493
|
+
}
|
|
494
|
+
interface ResolvedToolchain {
|
|
495
|
+
id: string;
|
|
496
|
+
kind: "library" | "cli" | "component";
|
|
497
|
+
description?: string;
|
|
498
|
+
module?: string;
|
|
499
|
+
command?: string;
|
|
500
|
+
cli_contract?: string;
|
|
501
|
+
component_contract?: string;
|
|
502
|
+
artifacts: {
|
|
503
|
+
consumes: string[];
|
|
504
|
+
produces: string[];
|
|
505
|
+
};
|
|
506
|
+
operations?: string[];
|
|
507
|
+
source: "toolchain-contracts" | "agent-contracts" | "merged";
|
|
508
|
+
}
|
|
509
|
+
interface ResolvedComponent {
|
|
510
|
+
id: string;
|
|
511
|
+
dsl: Record<string, unknown>;
|
|
512
|
+
registries: WorkflowRegistries;
|
|
513
|
+
guardrails: {
|
|
514
|
+
perAgent: Map<string, GuardrailRuleData>;
|
|
515
|
+
};
|
|
516
|
+
diagnostics: Array<{
|
|
517
|
+
path?: string;
|
|
518
|
+
message: string;
|
|
519
|
+
severity?: string;
|
|
520
|
+
}>;
|
|
521
|
+
toolchains?: Record<string, ResolvedToolchain>;
|
|
522
|
+
toolchainsByAgent?: Map<string, ResolvedToolchain[]>;
|
|
523
|
+
}
|
|
524
|
+
/**
|
|
525
|
+
* Effective guardrail IDs for an agent: entity-side bindings ∪ scope-side bindings.
|
|
526
|
+
*/
|
|
527
|
+
declare function getEffectiveGuardrailIds(dsl: Record<string, unknown>, agentId: string): Set<string>;
|
|
528
|
+
declare function guardrailContextToRuleData(ctx: GuardrailContext, effectiveIds?: Set<string>): GuardrailRuleData;
|
|
529
|
+
declare function buildPerAgentGuardrails(dsl: Record<string, unknown>, guardrailCtx: GuardrailContext): Map<string, GuardrailRuleData>;
|
|
530
|
+
declare function deriveToolchainsForAgents(dsl: Record<string, unknown>, toolchains: Record<string, ResolvedToolchain>): Map<string, ResolvedToolchain[]>;
|
|
531
|
+
declare class BoundResolver {
|
|
532
|
+
private readonly cache;
|
|
533
|
+
/**
|
|
534
|
+
* Resolve binding + policy in one pass. Results are cached by component id.
|
|
535
|
+
*/
|
|
536
|
+
resolve(opts: BoundResolveOptions): Promise<ResolvedComponent>;
|
|
537
|
+
/** Clear cached components (e.g. for testing). */
|
|
538
|
+
clearCache(): void;
|
|
539
|
+
}
|
|
540
|
+
/**
|
|
541
|
+
* Get guardrail rules for a specific agent from a ResolvedComponent.
|
|
542
|
+
* Falls back to embedded _guardrailRules when no per-agent rules exist.
|
|
543
|
+
*/
|
|
544
|
+
declare function getGuardrailRulesForAgent(component: ResolvedComponent, agentId: string, fallbackDsl?: Record<string, unknown>): GuardrailRuleData | undefined;
|
|
545
|
+
|
|
546
|
+
/**
|
|
547
|
+
* Candidate Agents — backend-neutral bridge for LLM-internal routing (model B)
|
|
548
|
+
*
|
|
549
|
+
* The runtime registers a set of *candidate sub-agents* with the SDK so the
|
|
550
|
+
* entry/main agent's LLM can delegate to them internally via the SDK's native
|
|
551
|
+
* subagent mechanism:
|
|
552
|
+
*
|
|
553
|
+
* - Claude `Options.agents: Record<string, AgentDefinition>`
|
|
554
|
+
* - OpenAI `Agent.handoffs: Agent[]`
|
|
555
|
+
* - ADK `LlmAgent.subAgents: BaseAgent[]`
|
|
556
|
+
*
|
|
557
|
+
* `CandidateAgent` is the common, SDK-independent contract. Each adapter maps it
|
|
558
|
+
* onto its provider's native shape. The selection rule (which agents become
|
|
559
|
+
* candidates) lives here so all adapters stay backend-agnostic.
|
|
560
|
+
*/
|
|
561
|
+
|
|
562
|
+
/**
|
|
563
|
+
* SDK-independent description of a sub-agent the entry agent's LLM may delegate
|
|
564
|
+
* to. Adapters translate this into their provider's native subagent shape.
|
|
565
|
+
*/
|
|
566
|
+
interface CandidateAgent {
|
|
567
|
+
/** Agent id (used as the SDK subagent key / name). */
|
|
568
|
+
name: string;
|
|
569
|
+
/** When to use this agent — the routing hint shown to the delegating LLM. */
|
|
570
|
+
description: string;
|
|
571
|
+
/** The agent's system prompt (role / purpose / responsibilities / constraints / rules). */
|
|
572
|
+
prompt: string;
|
|
573
|
+
/** Optional allowed tool names (omit to inherit from the parent agent). */
|
|
574
|
+
tools?: string[];
|
|
575
|
+
/** Optional model id (omit to inherit from the parent agent). */
|
|
576
|
+
model?: string;
|
|
577
|
+
}
|
|
578
|
+
/**
|
|
579
|
+
* Render an agent contract into its system-prompt string: the static
|
|
580
|
+
* Role / Responsibilities / Constraints / Rules sections.
|
|
581
|
+
*
|
|
582
|
+
* Shared by `buildSplitTaskPrompt` (entry agent system prompt) and
|
|
583
|
+
* `buildCandidateAgents` (each candidate's `prompt`) so both stay in sync.
|
|
584
|
+
*/
|
|
585
|
+
declare function renderAgentSystemPrompt(agent: AgentContractLike): string;
|
|
586
|
+
interface BuildCandidateAgentsOptions {
|
|
587
|
+
/** The entry/main agent id. Excluded from the candidate set. */
|
|
588
|
+
entryAgentId?: string;
|
|
589
|
+
/**
|
|
590
|
+
* When provided (typically the entry agent's `can_invoke_agents`), restrict
|
|
591
|
+
* candidates to these agent ids. Omit to allow every non-entry agent.
|
|
592
|
+
*/
|
|
593
|
+
allowedAgentIds?: readonly string[];
|
|
594
|
+
toolchainsByAgent?: Map<string, ResolvedToolchain[]>;
|
|
595
|
+
}
|
|
596
|
+
/**
|
|
597
|
+
* Build the candidate sub-agent set from an agent registry.
|
|
598
|
+
*
|
|
599
|
+
* Selection rule: every agent EXCEPT the entry agent; if `allowedAgentIds` is
|
|
600
|
+
* given, further restrict to that allow-list.
|
|
601
|
+
*/
|
|
602
|
+
declare function buildCandidateAgents(agentRegistry: Record<string, AgentContractLike>, opts?: BuildCandidateAgentsOptions): CandidateAgent[];
|
|
603
|
+
|
|
213
604
|
/**
|
|
214
605
|
* Task Runner — runs a single DSL task via an SDK agent
|
|
215
606
|
*
|
|
@@ -524,4 +915,4 @@ declare function runTask(adapter: SdkAdapter, taskId: string, context: TaskConte
|
|
|
524
915
|
libraryTools?: LibraryToolRegistry;
|
|
525
916
|
}): Promise<TaskRunResult>;
|
|
526
917
|
|
|
527
|
-
export { type AdapterSendOptions as A,
|
|
918
|
+
export { type WorkflowStep as $, type AdapterSendOptions as A, type BoundResolveOptions as B, type CacheConfig as C, type DelegateStep as D, type EnvelopeParams as E, type ModelResolver as F, type GuardrailHooks as G, type HandoffInput as H, InMemoryStore as I, type ModelResolverOptions as J, type ReceiveSpec as K, type LibraryToolRegistry as L, type MemoryRef as M, type ResolvedModel as N, type ObserverEmitFn as O, type PromptBuilderOptions as P, type RetryDecision as Q, type ResolvedComponent as R, type SdkAdapter as S, type TaskContext as T, type SdkAdapterFactory as U, type SplitPrompt as V, type WorkflowResult as W, type TaskRunOptions as X, type WorkflowContractLike as Y, type WorkflowInvocation as Z, type WorkflowRunOptions as _, type AgentExecutionRequest as a, buildCandidateAgents as a0, buildGateEvaluationPrompt as a1, buildPerAgentGuardrails as a2, buildRetryFollowUp as a3, buildSplitTaskPrompt as a4, buildTaskPrompt as a5, createExecutionEnvelope as a6, createGuardrailHooks as a7, createGuardrailHooksForAgent as a8, createGuardrailHooksFromRules as a9, createLibraryToolRegistry as aa, createModelResolver as ab, deriveToolchainsForAgents as ac, emitSessionClose as ad, emitSessionOpen as ae, emitSubagentClose as af, emitSubagentOpen as ag, emitToolchainClose as ah, emitToolchainOpen as ai, extractStructuredResult as aj, getBlockingViolations as ak, getEffectiveGuardrailIds as al, getGuardrailRulesForAgent as am, getWarnings as an, guardrailContextToRuleData as ao, hasBlockingViolation as ap, parseGateEvaluationResponse as aq, renderAgentSystemPrompt as ar, runTask as as, runWorkflow as at, zodSchemaToPromptDescription as au, zodSchemaToYamlExample as av, type TaskOutcome as b, type AgentContractLike as c, type TaskContractLike as d, type WorkflowRegistries as e, type StepCompleteEvent as f, type StepResult as g, type GuardrailRuleData as h, type MemoryStore as i, type ArtifactBindingConfig as j, type TaskRunResult as k, type ResolvedToolchain as l, type LibraryToolDefinition as m, type AdapterOrFactory as n, type AgentProgressEvent as o, BoundResolver as p, type CandidateAgent as q, type GateStep as r, type GuardrailCheckFunctions as s, type GuardrailCheckResult as t, type GuardrailRule as u, type HookContext as v, type HookResponse as w, type ModelAwareSdkAdapterFactory as x, type ModelClass as y, type ModelMappingConfig as z };
|
package/package.json
CHANGED
|
@@ -1,83 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* SDK Guardrail Hook Bridge — generic adapter from guardrail check functions
|
|
3
|
-
* + plugin guardrails to SDK-compatible hook responses.
|
|
4
|
-
*
|
|
5
|
-
* Embedded guardrail rules are converted via createGuardrailHooksFromRules(),
|
|
6
|
-
* which delegates to createGuardrailHooks(). All hook logic lives here.
|
|
7
|
-
*/
|
|
8
|
-
interface GuardrailCheckResult {
|
|
9
|
-
guardrail_id: string;
|
|
10
|
-
passed: boolean;
|
|
11
|
-
action: "block" | "warn" | "shadow" | "info";
|
|
12
|
-
message: string;
|
|
13
|
-
}
|
|
14
|
-
interface HookResponse {
|
|
15
|
-
permission?: "deny";
|
|
16
|
-
user_message?: string;
|
|
17
|
-
agent_message?: string;
|
|
18
|
-
additionalContext?: string;
|
|
19
|
-
}
|
|
20
|
-
interface GuardrailRule {
|
|
21
|
-
guardrail_id: string;
|
|
22
|
-
pattern: string;
|
|
23
|
-
action: "block" | "warn" | "shadow" | "info";
|
|
24
|
-
message: string;
|
|
25
|
-
file_glob?: string;
|
|
26
|
-
exclude_glob?: string;
|
|
27
|
-
}
|
|
28
|
-
interface GuardrailRuleData {
|
|
29
|
-
commandRules: GuardrailRule[];
|
|
30
|
-
fileRules: GuardrailRule[];
|
|
31
|
-
contentRules: GuardrailRule[];
|
|
32
|
-
}
|
|
33
|
-
interface GuardrailCheckFunctions {
|
|
34
|
-
checkCommand: (command: string) => GuardrailCheckResult[];
|
|
35
|
-
checkFilePath: (filePath: string) => GuardrailCheckResult[];
|
|
36
|
-
checkContent: (filePath: string, content: string) => GuardrailCheckResult[];
|
|
37
|
-
}
|
|
38
|
-
interface HookContext {
|
|
39
|
-
/** Agent id for per-agent guardrail filtering. */
|
|
40
|
-
agentId?: string;
|
|
41
|
-
command?: string;
|
|
42
|
-
filePath?: string;
|
|
43
|
-
content?: string;
|
|
44
|
-
}
|
|
45
|
-
interface GuardrailHooks {
|
|
46
|
-
beforeShellExecution: (input: {
|
|
47
|
-
command?: string;
|
|
48
|
-
}) => HookResponse;
|
|
49
|
-
preToolUse: (input: {
|
|
50
|
-
tool_name?: string;
|
|
51
|
-
tool_input?: {
|
|
52
|
-
file_path?: string;
|
|
53
|
-
path?: string;
|
|
54
|
-
};
|
|
55
|
-
}) => HookResponse;
|
|
56
|
-
afterFileEdit: (input: {
|
|
57
|
-
file_path?: string;
|
|
58
|
-
content?: string;
|
|
59
|
-
}) => HookResponse;
|
|
60
|
-
runChecks: (ctx: HookContext) => GuardrailCheckResult[];
|
|
61
|
-
}
|
|
62
|
-
declare function getBlockingViolations(results: GuardrailCheckResult[]): GuardrailCheckResult[];
|
|
63
|
-
declare function getWarnings(results: GuardrailCheckResult[]): GuardrailCheckResult[];
|
|
64
|
-
declare function hasBlockingViolation(results: GuardrailCheckResult[]): boolean;
|
|
65
|
-
/**
|
|
66
|
-
* Create SDK hook functions from generated guardrail check functions.
|
|
67
|
-
*
|
|
68
|
-
* Merges DSL-generated checks with plugin-registered guardrails and
|
|
69
|
-
* returns hook functions in the format expected by the Claude SDK,
|
|
70
|
-
* plus a generic runChecks() for programmatic use.
|
|
71
|
-
*/
|
|
72
|
-
declare function createGuardrailHooks(checks: GuardrailCheckFunctions): GuardrailHooks;
|
|
73
|
-
/**
|
|
74
|
-
* Create SDK hook functions from embedded guardrail rule data.
|
|
75
|
-
*/
|
|
76
|
-
/**
|
|
77
|
-
* Create SDK hooks scoped to a single agent from a per-agent guardrail map.
|
|
78
|
-
* Returns empty-passing hooks when the agent has no rules in the map.
|
|
79
|
-
*/
|
|
80
|
-
declare function createGuardrailHooksForAgent(agentId: string, perAgent: Map<string, GuardrailRuleData>): GuardrailHooks;
|
|
81
|
-
declare function createGuardrailHooksFromRules(rules: GuardrailRuleData): GuardrailHooks;
|
|
82
|
-
|
|
83
|
-
export { type GuardrailHooks as G, type HookContext as H, type GuardrailRuleData as a, type GuardrailCheckFunctions as b, type GuardrailCheckResult as c, type GuardrailRule as d, type HookResponse as e, createGuardrailHooks as f, createGuardrailHooksForAgent as g, createGuardrailHooksFromRules as h, getBlockingViolations as i, getWarnings as j, hasBlockingViolation as k };
|