agent-contracts-runtime
Version:
Runtime bridge for executing agent-contracts workflows on Agent SDKs
84 lines (82 loc) • 3.23 kB
TypeScript
/**
* SDK Guardrail Hook Bridge — generic adapter from guardrail check functions
* + plugin guardrails to SDK-compatible hook responses.
*
* Embedded guardrail rules are converted via createGuardrailHooksFromRules(),
* which delegates to createGuardrailHooks(). All hook logic lives here.
*/
interface GuardrailCheckResult {
guardrail_id: string;
passed: boolean;
action: "block" | "warn" | "shadow" | "info";
message: string;
}
interface HookResponse {
permission?: "deny";
user_message?: string;
agent_message?: string;
additionalContext?: string;
}
interface GuardrailRule {
guardrail_id: string;
pattern: string;
action: "block" | "warn" | "shadow" | "info";
message: string;
file_glob?: string;
exclude_glob?: string;
}
interface GuardrailRuleData {
commandRules: GuardrailRule[];
fileRules: GuardrailRule[];
contentRules: GuardrailRule[];
}
interface GuardrailCheckFunctions {
checkCommand: (command: string) => GuardrailCheckResult[];
checkFilePath: (filePath: string) => GuardrailCheckResult[];
checkContent: (filePath: string, content: string) => GuardrailCheckResult[];
}
interface HookContext {
/** Agent id for per-agent guardrail filtering. */
agentId?: string;
command?: string;
filePath?: string;
content?: string;
}
interface GuardrailHooks {
beforeShellExecution: (input: {
command?: string;
}) => HookResponse;
preToolUse: (input: {
tool_name?: string;
tool_input?: {
file_path?: string;
path?: string;
};
}) => HookResponse;
afterFileEdit: (input: {
file_path?: string;
content?: string;
}) => HookResponse;
runChecks: (ctx: HookContext) => GuardrailCheckResult[];
}
declare function getBlockingViolations(results: GuardrailCheckResult[]): GuardrailCheckResult[];
declare function getWarnings(results: GuardrailCheckResult[]): GuardrailCheckResult[];
declare function hasBlockingViolation(results: GuardrailCheckResult[]): boolean;
/**
* Create SDK hook functions from generated guardrail check functions.
*
* Merges DSL-generated checks with plugin-registered guardrails and
* returns hook functions in the format expected by the Claude SDK,
* plus a generic runChecks() for programmatic use.
*/
declare function createGuardrailHooks(checks: GuardrailCheckFunctions): GuardrailHooks;
/**
* Create SDK hook functions from embedded guardrail rule data.
*/
/**
* Create SDK hooks scoped to a single agent from a per-agent guardrail map.
* Returns empty-passing hooks when the agent has no rules in the map.
*/
declare function createGuardrailHooksForAgent(agentId: string, perAgent: Map<string, GuardrailRuleData>): GuardrailHooks;
declare function createGuardrailHooksFromRules(rules: GuardrailRuleData): GuardrailHooks;
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 };