From a1937d40042ac22eddc0930a189b3484506e0a46 Mon Sep 17 00:00:00 2001 From: foo-ogawa Date: Sun, 7 Jun 2026 02:26:10 +0900 Subject: [PATCH] feat: migrate orchestrator to runtime executeTask API Closes #31 Co-authored-by: Cursor --- esbuild.bundle.mjs | 22 +- package-lock.json | 46 +- package.json | 4 +- src/agents/orchestrator.ts | 131 +--- src/generated/dsl/.manifest.json | 7 +- src/generated/dsl/dsl-data.ts | 1041 ++++++++++++++++++++++++++++++ src/generated/dsl/index.ts | 1 + 7 files changed, 1090 insertions(+), 162 deletions(-) create mode 100644 src/generated/dsl/dsl-data.ts diff --git a/esbuild.bundle.mjs b/esbuild.bundle.mjs index 2bd6e8e..1fb8409 100644 --- a/esbuild.bundle.mjs +++ b/esbuild.bundle.mjs @@ -15,27 +15,7 @@ const externalSdks = [ const resolveRuntimeDynamicImports = { name: "resolve-runtime-dynamic-imports", - setup(build) { - build.onLoad({ filter: /agents[\\/]orchestrator\.ts$/ }, async (args) => { - let contents = readFileSync(args.path, "utf8"); - // Replace obfuscated RUNTIME_PKG with literal package name - contents = contents.replace( - /const RUNTIME_PKG = \["agent-contracts",\s*"runtime"\]\.join\("-"\);/, - 'const RUNTIME_PKG = "agent-contracts-runtime";', - ); - // Replace dynamic imports with literal strings - contents = contents.replace( - /await import\(RUNTIME_PKG\)/g, - 'await import("agent-contracts-runtime")', - ); - // Replace template-literal adapter imports - contents = contents.replace( - /await import\(`\$\{runtimePkg\}\/adapters\/([^`]+)`\)/g, - 'await import("agent-contracts-runtime/adapters/$1")', - ); - return { contents, loader: "ts" }; - }); - }, + setup(_build) {}, }; const inlineBuildTimeConstants = { diff --git a/package-lock.json b/package-lock.json index 5ce12ed..48cf0b0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "micro-contracts", - "version": "0.17.6", + "version": "0.17.8", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "micro-contracts", - "version": "0.17.6", + "version": "0.17.8", "license": "MIT", "bin": { "micro-contracts": "dist/micro-contracts.bundle.mjs" @@ -17,9 +17,9 @@ "@openai/agents": "^0.11.1", "@types/js-yaml": "^4.0.9", "@types/node": "^20.11.0", - "agent-contracts": "^0.33.1", + "agent-contracts": "^0.34.12", "agent-contracts-analyzer": "file:vendor/agent-contracts-analyzer-0.1.1.tgz", - "agent-contracts-runtime": "^0.36.0", + "agent-contracts-runtime": "^0.36.6", "chalk": "^5.3.0", "cli-contracts": "^0.32.0", "commander": "^12.1.0", @@ -1480,9 +1480,9 @@ } }, "node_modules/agent-contracts": { - "version": "0.33.1", - "resolved": "https://registry.npmjs.org/agent-contracts/-/agent-contracts-0.33.1.tgz", - "integrity": "sha512-WPWSdpmfXKP2HvsWQlT5wDYTDzW/t4z7931/yAPGFhQrZoSdhT6Qo/hFM/yO+Dogea4Hm6E4OGu/NW1TqNhr3A==", + "version": "0.34.12", + "resolved": "https://registry.npmjs.org/agent-contracts/-/agent-contracts-0.34.12.tgz", + "integrity": "sha512-Zm3O4Fl7FbPmNktlDHaFBgDb7cgpcsOb0+TiJoGiHNt+FFQ4HPbCVUtQmfwsvTKUBhzV+BjlV4FiPh7ejuMvKw==", "dev": true, "license": "MIT", "bin": { @@ -1539,19 +1539,6 @@ } } }, - "node_modules/agent-contracts-analyzer/node_modules/agent-contracts": { - "version": "0.34.2", - "resolved": "https://registry.npmjs.org/agent-contracts/-/agent-contracts-0.34.2.tgz", - "integrity": "sha512-RM2GMpzClQKsdNmZIPKqSNZ/F12H5FYU2sr/1eNtZQSWzuZRsW2KFOB73/a5rbd7famf0YOfdxxSJQUXGHLcfQ==", - "dev": true, - "license": "MIT", - "bin": { - "agent-contracts": "dist/agent-contracts.bundle.mjs" - }, - "engines": { - "node": ">=20.0.0" - } - }, "node_modules/agent-contracts-analyzer/node_modules/commander": { "version": "14.0.3", "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz", @@ -1563,9 +1550,9 @@ } }, "node_modules/agent-contracts-runtime": { - "version": "0.36.0", - "resolved": "https://registry.npmjs.org/agent-contracts-runtime/-/agent-contracts-runtime-0.36.0.tgz", - "integrity": "sha512-e5Yj1/wqQ6hP6KlGXDv0yvuKzNOav2dYLGqPbvZtBkxaSuk79KoXAmOcqiz63SXLsQ3Mlld8m1T7ahrsP1C4Ww==", + "version": "0.36.6", + "resolved": "https://registry.npmjs.org/agent-contracts-runtime/-/agent-contracts-runtime-0.36.6.tgz", + "integrity": "sha512-jxeC4df6gH73NflVdXxdjKFli06u5Zc3soIpDmS+MYyUap33CM99VKcgljH3zZyaGf7tIo5jSWbEJRh+Mqb9Jg==", "dev": true, "license": "MIT", "dependencies": { @@ -1600,19 +1587,6 @@ } } }, - "node_modules/agent-contracts-runtime/node_modules/agent-contracts": { - "version": "0.34.2", - "resolved": "https://registry.npmjs.org/agent-contracts/-/agent-contracts-0.34.2.tgz", - "integrity": "sha512-RM2GMpzClQKsdNmZIPKqSNZ/F12H5FYU2sr/1eNtZQSWzuZRsW2KFOB73/a5rbd7famf0YOfdxxSJQUXGHLcfQ==", - "dev": true, - "license": "MIT", - "bin": { - "agent-contracts": "dist/agent-contracts.bundle.mjs" - }, - "engines": { - "node": ">=20.0.0" - } - }, "node_modules/ajv": { "version": "8.20.0", "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz", diff --git a/package.json b/package.json index a913163..bdd67f3 100644 --- a/package.json +++ b/package.json @@ -71,9 +71,9 @@ "@openai/agents": "^0.11.1", "@types/js-yaml": "^4.0.9", "@types/node": "^20.11.0", - "agent-contracts": "^0.33.1", + "agent-contracts": "^0.34.12", "agent-contracts-analyzer": "file:vendor/agent-contracts-analyzer-0.1.1.tgz", - "agent-contracts-runtime": "^0.36.0", + "agent-contracts-runtime": "^0.36.6", "chalk": "^5.3.0", "cli-contracts": "^0.32.0", "commander": "^12.1.0", diff --git a/src/agents/orchestrator.ts b/src/agents/orchestrator.ts index 62d719f..489d51c 100644 --- a/src/agents/orchestrator.ts +++ b/src/agents/orchestrator.ts @@ -1,128 +1,59 @@ -import { resolve } from "node:path"; +import { resolvedDsl } from "../generated/dsl/dsl-data.js"; import type { AuditConfig, AuditOptions, AuditRunResult, TaskId } from "./types.js"; export const EXIT_RUNTIME_MISSING = 11; export const EXIT_ADAPTER_ERROR = 12; -// eslint-disable-next-line @typescript-eslint/no-explicit-any -async function createAdapter(runtimePkg: string, name: string, config: AuditConfig): Promise { - switch (name) { - case "mock": { - const mod = await import(`${runtimePkg}/adapters/mock`); - return new mod.MockAdapter(); - } - case "claude": { - const mod = await import(`${runtimePkg}/adapters/claude-agent-sdk`); - return new mod.ClaudeAgentSdkAdapter({ - model: config.model, - tools: ["Read", "Glob", "Grep"], - permissionMode: "bypassPermissions", - }); - } - case "openai": { - const mod = await import(`${runtimePkg}/adapters/openai-agents-sdk`); - return new mod.OpenAIAgentsSdkAdapter({ - model: config.model ?? "o3-mini", - maxTurns: 1, - }); - } - case "gemini": { - const mod = await import(`${runtimePkg}/adapters/adk-sdk`); - return new mod.AdkSdkAdapter({ - apiKey: process.env.GEMINI_API_KEY, - model: config.model ?? "gemini-2.5-pro", - temperature: config.temperature, - }); - } - default: - throw new Error( - `Unsupported adapter: "${name}". ` + - "Available: mock, claude, openai, gemini.", - ); - } -} - export async function runAgentTask( userRequest: string, taskId: TaskId, auditConfig: AuditConfig, options: AuditOptions, ): Promise { - const RUNTIME_PKG = ["agent-contracts", "runtime"].join("-"); - - // eslint-disable-next-line @typescript-eslint/no-explicit-any - let runTask: (...args: any[]) => Promise; - // eslint-disable-next-line @typescript-eslint/no-explicit-any - let createProgressSink: (...args: any[]) => { write: (chunk: string) => void; close: () => void }; // eslint-disable-next-line @typescript-eslint/no-explicit-any - let agentRegistry: any, taskRegistry: any, handoffSchemas: any; - + let executeTask: (taskId: string, options: any) => Promise; try { - const runtime = await import(RUNTIME_PKG); - runTask = runtime.runTask; - createProgressSink = runtime.createProgressSink; + const runtime = await import("agent-contracts-runtime"); + executeTask = runtime.executeTask; } catch { throw Object.assign( new Error( "agent-contracts-runtime is not installed. " + - "Install it to use this command, or use --show-prompt to inspect the prompt.\n" + - " npm install agent-contracts-runtime", + "Install it to use this command, or use --show-prompt to inspect the prompt.\n" + + " npm install agent-contracts-runtime", ), { exitCode: EXIT_RUNTIME_MISSING }, ); } + let result; try { - const dsl = await import("../generated/dsl/index.js"); - agentRegistry = dsl.agentRegistry; - taskRegistry = dsl.taskRegistry; - handoffSchemas = dsl.handoffSchemas; - } catch { - agentRegistry = {}; - taskRegistry = {}; - handoffSchemas = {}; - } - - const adapterName = auditConfig.adapter ?? "mock"; - let adapter; - try { - adapter = await createAdapter(RUNTIME_PKG, adapterName, auditConfig); - } catch (err) { - throw Object.assign(err as Error, { exitCode: EXIT_ADAPTER_ERROR }); - } - - const progressSink = options.logFile - ? createProgressSink({ stderr: true, file: resolve(options.logFile), naming: "single" }) - : createProgressSink({ stderr: true }); - - try { - const result = await runTask(adapter, taskId, { - user_request: userRequest, - }, { + result = await executeTask(taskId, { + request: userRequest, + adapter: auditConfig.adapter ?? "mock", + model: auditConfig.model, + dsl: resolvedDsl, + logFile: options.logFile, maxFollowUps: 3, maxRetries: 1, - progressOutput: progressSink, - agentRegistry, - taskRegistry, - handoffSchemas, }); - - const outcome = result.outcome; - return { - taskId, - data: outcome.status === "success" ? outcome.data : null, - raw: (outcome.raw as string) ?? "", - prompt: userRequest, - status: outcome.status as AuditRunResult["status"], - errorMessage: - outcome.status === "error" ? outcome.message : - outcome.status === "escalation" ? outcome.reason : - outcome.status === "validation_error" ? outcome.errors?.message : - undefined, - followUpsUsed: result.follow_ups_used, - retriesUsed: result.retries_used, - }; - } finally { - progressSink.close(); + } catch (err) { + throw Object.assign(err as Error, { exitCode: EXIT_ADAPTER_ERROR }); } + + const outcome = result.outcome; + return { + taskId, + data: outcome.status === "success" ? (outcome.data ?? null) : null, + raw: outcome.raw ?? "", + prompt: userRequest, + status: outcome.status as AuditRunResult["status"], + errorMessage: + outcome.status === "error" ? outcome.message : + outcome.status === "escalation" ? outcome.reason : + outcome.status === "validation_error" ? outcome.errors?.message : + undefined, + followUpsUsed: result.follow_ups_used, + retriesUsed: result.retries_used, + }; } diff --git a/src/generated/dsl/.manifest.json b/src/generated/dsl/.manifest.json index 3c1e9b8..d7b6595 100644 --- a/src/generated/dsl/.manifest.json +++ b/src/generated/dsl/.manifest.json @@ -1,12 +1,13 @@ { - "generated_at": "2026-06-03T09:09:31.255Z", + "generated_at": "2026-06-06T17:25:21.763Z", "dsl_hash": "1c2b11132ad90a541a922748e466a4676face316dd693e03a1ef258c7d526d0e", - "generation_input_hash": "1c2b11132ad90a541a922748e466a4676face316dd693e03a1ef258c7d526d0e", + "generation_input_hash": "e2af5f5a1c268e244b1dba78076f0233e43dc1027a67a791e4ca70820c92b74c", "files": [ "../src/generated/dsl/agents.ts", "../src/generated/dsl/tasks.ts", "../src/generated/dsl/workflows.ts", "../src/generated/dsl/handoffs.ts", - "../src/generated/dsl/index.ts" + "../src/generated/dsl/index.ts", + "../src/generated/dsl/dsl-data.ts" ] } diff --git a/src/generated/dsl/dsl-data.ts b/src/generated/dsl/dsl-data.ts new file mode 100644 index 0000000..3c72511 --- /dev/null +++ b/src/generated/dsl/dsl-data.ts @@ -0,0 +1,1041 @@ +/** + * AUTO-GENERATED by agent-contracts-runtime. DO NOT EDIT. + * + * Regenerate via: npx agent-runtime generate + */ + +export const resolvedDsl: Record = { + "version": 1, + "system": { + "id": "micro-contracts", + "name": "Micro-Contracts Agent System", + "default_workflow_order": [ + "openapi-audit", + "published-review", + "overlay-proposal", + "guardrails-audit" + ] + }, + "agents": { + "openapi-design-reviewer": { + "role_name": "OpenAPI Design Reviewer", + "purpose": "Review OpenAPI specifications for design quality, module boundary alignment, and operational readiness in contract-first TypeScript web/API systems. Identifies semantic issues that static linting cannot detect by considering service decomposition, dependency graphs, overlay coverage, and public API surface exposure.", + "mode": "read-only", + "can_read_artifacts": [ + "openapi-spec-input", + "config-source", + "overlay-definitions", + "lint-results-input", + "deps-graph-input", + "published-spec-input", + "guardrails-config-input", + "cli-contract-source" + ], + "can_write_artifacts": [], + "can_invoke_agents": [], + "can_execute_tools": [], + "can_return_handoffs": [ + "openapi-audit-result", + "published-review-result", + "overlay-proposal-result", + "guardrails-audit-result" + ], + "responsibilities": [ + "Evaluate path design and feature module boundary alignment using x-micro-contracts-service grouping", + "Detect request/response schema bloat and overly coupled resource models", + "Verify x-micro-contracts-service and operationId consistency within modules", + "Assess CRUD-heavy APIs vs use-case-oriented design and suggest improvements", + "Detect public API surface leakage of internal types via x-micro-contracts-non-exportable analysis", + "Evaluate backward compatibility risks in published API changes", + "Propose cross-cutting overlays for auth, tenancy, rate limiting, and audit logging patterns", + "Verify overlay proposals do not conflict with existing overlay definitions", + "Check guardrails.yaml drift detection and OpenAPI lint rule coverage", + "Use module dependency graph (deps command output) for cross-module analysis" + ], + "constraints": [ + "Do not modify OpenAPI specs, overlays, config files, or any source artifacts", + "Do not claim an API design is sound without citing specific structural evidence", + "Prefer actionable recommendations over abstract design principles", + "Reference micro-contracts lint rules and extension names when findings overlap", + "Consider multi-module architecture when evaluating cross-cutting concerns", + "Output must conform to AgentAuditResult schema (summary, riskLevel, findings, recommendedActions, metadata)", + "Each finding must include a recommendation when severity is warning or above" + ], + "rules": [ + { + "id": "R-OAR-001", + "description": "Operations without x-micro-contracts-service are flagged as unclassified and may indicate missing module assignment", + "severity": "mandatory" + }, + { + "id": "R-OAR-002", + "description": "Schemas referenced by published endpoints must not carry x-micro-contracts-non-exportable", + "severity": "mandatory" + }, + { + "id": "R-OAR-003", + "description": "Overlay proposals must not conflict with existing overlay definitions in the shared overlays directory", + "severity": "mandatory" + }, + { + "id": "R-OAR-004", + "description": "Response schemas with more than 20 top-level properties are flagged as potential bloat", + "severity": "recommended" + }, + { + "id": "R-OAR-005", + "description": "Modules with more than 3 cross-module schema references are flagged for coupling review", + "severity": "recommended" + }, + { + "id": "R-OAR-006", + "description": "Generated file patterns in guardrails.yaml must cover all output directories configured in modules", + "severity": "mandatory" + } + ], + "escalation_criteria": [ + { + "condition": "OpenAPI specification cannot be parsed or is structurally invalid", + "action": "stop_and_report" + }, + { + "condition": "Configuration file references missing modules or specs", + "action": "stop_and_report" + } + ] + } + }, + "tasks": { + "audit-openapi-design": { + "description": "Audit OpenAPI specification design quality and module boundary alignment", + "target_agent": "openapi-design-reviewer", + "model_class": "standard", + "allowed_from_agents": [ + "openapi-design-reviewer" + ], + "workflow": "openapi-audit", + "input_artifacts": [ + "openapi-spec-input", + "config-source", + "overlay-definitions", + "lint-results-input", + "deps-graph-input" + ], + "invocation_handoff": "openapi-audit-request", + "result_handoff": "openapi-audit-result", + "responsibilities": [ + "Evaluate all paths for module boundary alignment", + "Check operationId and x-micro-contracts-service consistency", + "Detect schema bloat and excessive coupling", + "Assess CRUD vs use-case-oriented design", + "Review overlay usage and cross-cutting concerns" + ], + "completion_criteria": [ + "All paths and operations have been evaluated for design quality", + "Findings classified by category (design_quality, responsibility_boundary, api_bloat, dependency_coupling)", + "Module boundary alignment explicitly assessed", + "Recommendations reference specific paths and operations", + "Output conforms to AgentAuditResult schema" + ] + }, + "audit-published-api": { + "description": "Review published API surface for internal type leakage and compatibility", + "target_agent": "openapi-design-reviewer", + "model_class": "standard", + "allowed_from_agents": [ + "openapi-design-reviewer" + ], + "workflow": "published-review", + "input_artifacts": [ + "openapi-spec-input", + "published-spec-input", + "config-source", + "deps-graph-input" + ], + "invocation_handoff": "openapi-audit-request", + "result_handoff": "published-review-result", + "responsibilities": [ + "Compare master spec against published spec for leakage", + "Identify schemas with x-micro-contracts-non-exportable that appear in published surface", + "Assess backward compatibility of published endpoint changes", + "Enumerate published endpoints with their operation details" + ], + "completion_criteria": [ + "All published endpoints enumerated with operationId, path, method", + "Leaked internal types identified with referencing context", + "Backward compatibility risks assessed for each published endpoint", + "Output conforms to PublishedReviewResult schema (publishedEndpoints, leakedInternalTypes)" + ] + }, + "propose-overlay-candidates": { + "description": "Propose cross-cutting overlay candidates for the API specification", + "target_agent": "openapi-design-reviewer", + "model_class": "standard", + "allowed_from_agents": [ + "openapi-design-reviewer" + ], + "workflow": "overlay-proposal", + "input_artifacts": [ + "openapi-spec-input", + "overlay-definitions", + "config-source" + ], + "invocation_handoff": "openapi-audit-request", + "result_handoff": "overlay-proposal-result", + "responsibilities": [ + "Identify endpoints needing cross-cutting concerns (auth, tenancy, rate limit, audit log)", + "Generate overlay candidates with endpoint, type, rationale, and suggested config", + "Verify proposals do not conflict with existing overlay definitions", + "Group candidates by overlay type for batch application" + ], + "completion_criteria": [ + "Candidate overlays identified for endpoints lacking cross-cutting concerns", + "Each candidate includes endpoint, overlayType, rationale, and suggestedConfig", + "No conflicts with existing overlay definitions confirmed", + "Output conforms to OverlayProposalResult schema (overlayCandidates)" + ] + }, + "audit-guardrails-coverage": { + "description": "Audit guardrails.yaml for drift detection and lint rule coverage", + "target_agent": "openapi-design-reviewer", + "model_class": "fast", + "allowed_from_agents": [ + "openapi-design-reviewer" + ], + "workflow": "guardrails-audit", + "input_artifacts": [ + "guardrails-config-input", + "config-source", + "openapi-spec-input" + ], + "invocation_handoff": "openapi-audit-request", + "result_handoff": "guardrails-audit-result", + "responsibilities": [ + "Verify generated file patterns cover all configured output directories", + "Check that drift detection covers all generated artifact types", + "Verify OpenAPI lint rules are configured for all spec files", + "Identify uncovered paths in guardrails configuration" + ], + "completion_criteria": [ + "All configured output directories checked against guardrails generated patterns", + "Covered and uncovered paths explicitly listed", + "Lint rule coverage for each spec file assessed", + "Output conforms to GuardrailsAuditResult schema (coveredPaths, uncoveredPaths)" + ] + } + }, + "handoff_types": { + "openapi-audit-request": { + "version": 1, + "description": "Request to execute an OpenAPI design review task", + "schema": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Identifier of the task to execute" + }, + "context": { + "type": "string", + "description": "Built context string from OpenAPI specs, config, overlays, lint results, and deps graph" + } + }, + "required": [ + "task_id", + "context" + ] + } + }, + "openapi-audit-result": { + "version": 1, + "description": "Result of an OpenAPI design audit task. Schema mirrors cli-contract.yaml#/components/schemas/OpenApiAuditResult.", + "schema": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "medium", + "high", + "critical" + ] + }, + "findings": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "severity": { + "type": "string", + "enum": [ + "info", + "warning", + "error", + "critical" + ] + }, + "category": { + "type": "string" + }, + "target": { + "type": "string" + }, + "location": { + "type": "string" + }, + "message": { + "type": "string" + }, + "recommendation": { + "type": "string" + }, + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "evidence": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "file", + "command", + "schema", + "diff", + "stdout", + "stderr", + "text" + ] + }, + "target": { + "type": "string" + }, + "location": { + "type": "string" + }, + "excerpt": { + "type": "string" + } + } + } + }, + "details": { + "type": "object", + "additionalProperties": true + } + }, + "required": [ + "severity", + "category", + "message" + ] + } + }, + "recommendedActions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "run_command", + "edit_file", + "review", + "confirm", + "block", + "ignore" + ] + }, + "title": { + "type": "string" + }, + "command": { + "type": "string" + }, + "target": { + "type": "string" + }, + "rationale": { + "type": "string" + } + }, + "required": [ + "kind", + "title" + ] + } + }, + "metadata": { + "type": "object", + "properties": { + "tool": { + "type": "string" + }, + "command": { + "type": "string" + }, + "version": { + "type": "string" + }, + "generatedAt": { + "type": "string" + }, + "adapter": { + "type": "string" + }, + "model": { + "type": "string" + } + } + } + }, + "required": [ + "summary", + "riskLevel", + "findings" + ] + } + }, + "published-review-result": { + "version": 1, + "description": "Result of published API review task. Schema mirrors cli-contract.yaml#/components/schemas/PublishedReviewResult.", + "schema": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "medium", + "high", + "critical" + ] + }, + "findings": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { + "type": "string", + "enum": [ + "info", + "warning", + "error", + "critical" + ] + }, + "category": { + "type": "string" + }, + "message": { + "type": "string" + }, + "recommendation": { + "type": "string" + } + }, + "required": [ + "severity", + "category", + "message" + ] + } + }, + "publishedEndpoints": { + "type": "array", + "items": { + "type": "object", + "properties": { + "operationId": { + "type": "string" + }, + "path": { + "type": "string" + }, + "method": { + "type": "string" + } + }, + "required": [ + "operationId", + "path", + "method" + ] + } + }, + "leakedInternalTypes": { + "type": "array", + "items": { + "type": "object", + "properties": { + "schemaName": { + "type": "string" + }, + "referencedBy": { + "type": "string" + }, + "reason": { + "type": "string" + } + }, + "required": [ + "schemaName", + "referencedBy", + "reason" + ] + } + }, + "recommendedActions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "run_command", + "edit_file", + "review", + "confirm", + "block", + "ignore" + ] + }, + "title": { + "type": "string" + }, + "command": { + "type": "string" + }, + "target": { + "type": "string" + }, + "rationale": { + "type": "string" + } + }, + "required": [ + "kind", + "title" + ] + } + }, + "metadata": { + "type": "object", + "properties": { + "tool": { + "type": "string" + }, + "command": { + "type": "string" + }, + "version": { + "type": "string" + }, + "generatedAt": { + "type": "string" + }, + "adapter": { + "type": "string" + }, + "model": { + "type": "string" + } + } + } + }, + "required": [ + "summary", + "riskLevel", + "findings", + "publishedEndpoints", + "leakedInternalTypes" + ] + } + }, + "overlay-proposal-result": { + "version": 1, + "description": "Result of overlay proposal task. Schema mirrors cli-contract.yaml#/components/schemas/OverlayProposalResult.", + "schema": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "medium", + "high", + "critical" + ] + }, + "findings": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { + "type": "string", + "enum": [ + "info", + "warning", + "error", + "critical" + ] + }, + "category": { + "type": "string" + }, + "message": { + "type": "string" + }, + "recommendation": { + "type": "string" + } + }, + "required": [ + "severity", + "category", + "message" + ] + } + }, + "overlayCandidates": { + "type": "array", + "items": { + "type": "object", + "properties": { + "endpoint": { + "type": "string" + }, + "overlayType": { + "type": "string", + "enum": [ + "auth", + "tenancy", + "rateLimit", + "auditLog", + "custom" + ] + }, + "rationale": { + "type": "string" + }, + "suggestedConfig": { + "type": "object", + "additionalProperties": true + } + }, + "required": [ + "endpoint", + "overlayType", + "rationale" + ] + } + }, + "recommendedActions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "run_command", + "edit_file", + "review", + "confirm", + "block", + "ignore" + ] + }, + "title": { + "type": "string" + }, + "command": { + "type": "string" + }, + "target": { + "type": "string" + }, + "rationale": { + "type": "string" + } + }, + "required": [ + "kind", + "title" + ] + } + }, + "metadata": { + "type": "object", + "properties": { + "tool": { + "type": "string" + }, + "command": { + "type": "string" + }, + "version": { + "type": "string" + }, + "generatedAt": { + "type": "string" + }, + "adapter": { + "type": "string" + }, + "model": { + "type": "string" + } + } + } + }, + "required": [ + "summary", + "riskLevel", + "findings", + "overlayCandidates" + ] + } + }, + "guardrails-audit-result": { + "version": 1, + "description": "Result of guardrails coverage audit task. Schema mirrors cli-contract.yaml#/components/schemas/GuardrailsAuditResult.", + "schema": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "riskLevel": { + "type": "string", + "enum": [ + "low", + "medium", + "high", + "critical" + ] + }, + "findings": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { + "type": "string", + "enum": [ + "info", + "warning", + "error", + "critical" + ] + }, + "category": { + "type": "string" + }, + "message": { + "type": "string" + }, + "recommendation": { + "type": "string" + } + }, + "required": [ + "severity", + "category", + "message" + ] + } + }, + "coveredPaths": { + "type": "array", + "items": { + "type": "string" + } + }, + "uncoveredPaths": { + "type": "array", + "items": { + "type": "string" + } + }, + "recommendedActions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "run_command", + "edit_file", + "review", + "confirm", + "block", + "ignore" + ] + }, + "title": { + "type": "string" + }, + "command": { + "type": "string" + }, + "target": { + "type": "string" + }, + "rationale": { + "type": "string" + } + }, + "required": [ + "kind", + "title" + ] + } + }, + "metadata": { + "type": "object", + "properties": { + "tool": { + "type": "string" + }, + "command": { + "type": "string" + }, + "version": { + "type": "string" + }, + "generatedAt": { + "type": "string" + }, + "adapter": { + "type": "string" + }, + "model": { + "type": "string" + } + } + } + }, + "required": [ + "summary", + "riskLevel", + "findings", + "coveredPaths", + "uncoveredPaths" + ] + } + } + }, + "artifacts": { + "openapi-spec-input": { + "type": "document", + "description": "OpenAPI specification file(s) loaded from config modules (ephemeral input)", + "authority": "derived" + }, + "config-source": { + "type": "document", + "description": "micro-contracts.config.yaml configuration (ephemeral input)", + "authority": "derived" + }, + "overlay-definitions": { + "type": "document", + "description": "Overlay YAML files from shared and module-specific overlay directories (ephemeral input)", + "authority": "derived" + }, + "lint-results-input": { + "type": "document", + "description": "Spectral lint results for the target OpenAPI spec (ephemeral input)", + "authority": "derived" + }, + "deps-graph-input": { + "type": "document", + "description": "Module dependency graph from deps command analysis (ephemeral input)", + "authority": "derived" + }, + "published-spec-input": { + "type": "document", + "description": "Published (public-facing) OpenAPI spec for comparison with master spec (ephemeral input)", + "authority": "derived" + }, + "guardrails-config-input": { + "type": "document", + "description": "guardrails.yaml configuration for coverage analysis (ephemeral input)", + "authority": "derived" + }, + "cli-contract-source": { + "type": "document", + "description": "cli-contract.yaml for reference (ephemeral input)", + "authority": "derived" + } + }, + "guardrails": { + "output-schema-conformance": { + "description": "Ensure all agent outputs conform to AgentAuditResult schema. Validation is performed at runtime via Zod schema in handoff definition.", + "scope": { + "agents": [ + "openapi-design-reviewer" + ], + "tasks": [ + "audit-openapi-design", + "audit-published-api", + "propose-overlay-candidates", + "audit-guardrails-coverage" + ] + }, + "rationale": "Structured output conformance is critical for CLI parsing and downstream tooling integration." + }, + "no-file-modification": { + "description": "Agent must never modify OpenAPI specs, overlays, config, or any source files. Agent operates in read-only mode for analysis only.", + "scope": { + "agents": [ + "openapi-design-reviewer" + ] + }, + "rationale": "openapi-design-reviewer is a static analysis agent. File modification capabilities have been moved to artifact-contracts." + }, + "confidence-threshold": { + "description": "Findings with confidence below 0.5 must include an explicit uncertainty disclaimer in their recommendation.", + "scope": { + "tasks": [ + "audit-openapi-design", + "audit-published-api", + "propose-overlay-candidates", + "audit-guardrails-coverage" + ] + }, + "rationale": "Low-confidence findings without disclaimers may mislead operators into applying unnecessary changes to API design." + } + }, + "guardrail_policies": { + "openapi-review-policy": { + "description": "Policy governing OpenAPI design review operations. Groups all guardrails applicable to the openapi-design-reviewer agent.", + "rules": [ + { + "guardrail": "output-schema-conformance", + "severity": "critical", + "action": "block" + }, + { + "guardrail": "no-file-modification", + "severity": "critical", + "action": "block" + }, + { + "guardrail": "confidence-threshold", + "severity": "warning", + "action": "warn" + } + ] + } + }, + "workflow": { + "openapi-audit": { + "description": "Audit OpenAPI design quality and module boundary alignment", + "trigger": "cli-command", + "entry_conditions": [ + "OpenAPI specification and config are available" + ], + "steps": [ + { + "type": "delegate", + "task": "audit-openapi-design", + "from_agent": "openapi-design-reviewer" + } + ] + }, + "published-review": { + "description": "Review published API surface for internal leakage and compatibility", + "trigger": "cli-command", + "entry_conditions": [ + "Both master and published specs are available" + ], + "steps": [ + { + "type": "delegate", + "task": "audit-published-api", + "from_agent": "openapi-design-reviewer" + } + ] + }, + "overlay-proposal": { + "description": "Propose cross-cutting overlay candidates", + "trigger": "cli-command", + "entry_conditions": [ + "OpenAPI specification and existing overlays are available" + ], + "steps": [ + { + "type": "delegate", + "task": "propose-overlay-candidates", + "from_agent": "openapi-design-reviewer" + } + ] + }, + "guardrails-audit": { + "description": "Audit guardrails configuration for drift and lint coverage", + "trigger": "cli-command", + "entry_conditions": [ + "guardrails.yaml configuration exists" + ], + "steps": [ + { + "type": "delegate", + "task": "audit-guardrails-coverage", + "from_agent": "openapi-design-reviewer" + } + ] + } + }, + "_guardrailRules": { + "commandRules": [], + "fileRules": [ + { + "guardrail_id": "no-file-modification", + "pattern": "spec/**/openapi/**/*.yaml", + "action": "block", + "message": "Modifying OpenAPI specs is forbidden. openapi-design-reviewer operates in read-only analysis mode." + }, + { + "guardrail_id": "no-file-modification", + "pattern": "**/*.overlay.yaml", + "action": "block", + "message": "Modifying overlay files is forbidden. openapi-design-reviewer operates in read-only analysis mode." + }, + { + "guardrail_id": "no-file-modification", + "pattern": "micro-contracts.config.yaml", + "action": "block", + "message": "Modifying micro-contracts config is forbidden. openapi-design-reviewer operates in read-only analysis mode." + }, + { + "guardrail_id": "no-file-modification", + "pattern": "**/guardrails.yaml", + "action": "block", + "message": "Modifying guardrails config is forbidden. openapi-design-reviewer operates in read-only analysis mode." + } + ], + "contentRules": [] + } +} as const; diff --git a/src/generated/dsl/index.ts b/src/generated/dsl/index.ts index e27e54f..755bbb7 100644 --- a/src/generated/dsl/index.ts +++ b/src/generated/dsl/index.ts @@ -11,3 +11,4 @@ export type { TaskContract } from "./tasks.js"; export { handoffSchemas, handoffs } from "./handoffs.js"; export type { HandoffTypeId, HandoffEnvelope } from "./handoffs.js"; export { workflowRegistry } from "./workflows.js"; +export { resolvedDsl } from "./dsl-data.js";