@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/agent-binding.js

@@ -0,0 +1,343 @@
+import { z } from 'zod';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const ADAPTER_ID_PATTERN = /^codesdd-agent-[a-z0-9][a-z0-9-]*$/;
+const agentProviderSchema = z.enum([
+    'codex',
+    'opencode',
+    'claude-code',
+    'cloudcode',
+    'deepagents',
+    'fake',
+]);
+const agentTaskKindSchema = z.enum([
+    'planning',
+    'review',
+    'validation',
+    'implementation',
+    'reverse-engineering',
+    'plugin-execution',
+    'adr-governance',
+    'quality-witness',
+    'documentation-sync',
+]);
+const adapterStatusSchema = z.enum(['active', 'disabled', 'experimental']);
+const trustTierSchema = z.enum(['enterprise-approved', 'local-dev', 'experimental', 'blocked']);
+const riskTierSchema = z.enum(['low', 'medium', 'high', 'critical']);
+const TRUST_RANK = {
+    'enterprise-approved': 3,
+    'local-dev': 2,
+    experimental: 1,
+    blocked: 0,
+};
+const RISK_RANK = {
+    low: 4,
+    medium: 3,
+    high: 2,
+    critical: 1,
+};
+export const agentBindingCapabilitySchema = z.object({
+    task_kind: agentTaskKindSchema,
+    description: z.string().min(20),
+    read_only: z.boolean(),
+    edits: z.boolean(),
+    background: z.boolean(),
+    worktree_isolation: z.boolean(),
+    mcp: z.boolean(),
+    skills: z.boolean(),
+    structured_evidence: z.boolean(),
+    risk_tier: riskTierSchema.default('medium'),
+});
+export const agentBindingAdapterSchema = z
+    .object({
+    schema_version: z.literal(1).default(1),
+    id: z.string().regex(ADAPTER_ID_PATTERN),
+    provider: agentProviderSchema,
+    label: z.string().min(2),
+    status: adapterStatusSchema.default('active'),
+    execution: z.object({
+        mode: z.enum(['local-cli', 'cloud', 'test-double']),
+        command: z.string().min(1).optional(),
+        args: z.array(z.string()).default([]),
+        network: z.enum(['disabled', 'restricted', 'enabled']).default('disabled'),
+        evidence_contract: z.string().min(1).default('agent-evidence/v1'),
+    }),
+    capabilities: z.array(agentBindingCapabilitySchema).min(1),
+    governance: z.object({
+        owner: z.string().min(2),
+        trust_tier: trustTierSchema,
+        approval: z.enum(['none', 'maintainer', 'architecture-board', 'security']).default('maintainer'),
+        notes: z.array(z.string()).default([]),
+    }),
+})
+    .superRefine((adapter, context) => {
+    const seen = new Set();
+    for (const [index, capability] of adapter.capabilities.entries()) {
+        if (seen.has(capability.task_kind)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['capabilities', index, 'task_kind'],
+                message: `Duplicate agent capability: ${capability.task_kind}.`,
+            });
+        }
+        seen.add(capability.task_kind);
+    }
+    if (adapter.execution.mode !== 'test-double' && !adapter.execution.command) {
+        context.addIssue({
+            code: 'custom',
+            path: ['execution', 'command'],
+            message: 'Non-test agent adapters must declare an execution command.',
+        });
+    }
+});
+export const agentBindingResolutionRequestSchema = z.object({
+    schema_version: z.literal(1).default(1),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    task_kind: agentTaskKindSchema,
+    provider: agentProviderSchema.optional(),
+    allowed_providers: z
+        .array(agentProviderSchema)
+        .default(['codex', 'opencode', 'claude-code', 'cloudcode', 'deepagents', 'fake']),
+    statuses: z.array(adapterStatusSchema).default(['active']),
+    trust_tiers: z.array(trustTierSchema).default(['enterprise-approved', 'local-dev', 'experimental']),
+    require_edits: z.boolean().default(false),
+    require_background: z.boolean().default(false),
+    require_worktree_isolation: z.boolean().default(false),
+    require_mcp: z.boolean().default(false),
+    require_skills: z.boolean().default(false),
+    require_structured_evidence: z.boolean().default(true),
+    created_at: z.string().datetime().optional(),
+});
+export const agentBindingCandidateSchema = z.object({
+    adapter_ref: z.object({
+        id: z.string().regex(ADAPTER_ID_PATTERN),
+        provider: agentProviderSchema,
+        label: z.string().min(2),
+    }),
+    task_kind: agentTaskKindSchema,
+    rank: z.number().int().nonnegative(),
+    reasons: z.array(z.string()).default([]),
+});
+export const agentBindingResolutionSchema = z.object({
+    schema_version: z.literal(1),
+    created_at: z.string().datetime(),
+    status: z.enum(['resolved', 'fallback']),
+    request: agentBindingResolutionRequestSchema,
+    selected: agentBindingCandidateSchema.optional(),
+    candidates: z.array(agentBindingCandidateSchema).default([]),
+    reasons: z.array(z.string()).default([]),
+    fallback: z
+        .object({
+        strategy: z.enum(['manual-agent-selection', 'local-human-execution', 'no-compatible-agent']),
+        message: z.string().min(1),
+    })
+        .optional(),
+});
+export function builtInAgentBindingAdapters() {
+    return [
+        createAdapter('codesdd-agent-codex-local', 'codex', 'Codex Local', 'local-cli', 'codex', {
+            background: true,
+            worktree_isolation: true,
+            mcp: true,
+            trust_tier: 'enterprise-approved',
+        }),
+        createAdapter('codesdd-agent-opencode-cli', 'opencode', 'OpenCode CLI', 'local-cli', 'opencode', {
+            background: false,
+            worktree_isolation: false,
+            mcp: false,
+            trust_tier: 'local-dev',
+        }),
+        createAdapter('codesdd-agent-claude-code-cli', 'claude-code', 'Claude Code CLI', 'local-cli', 'claude', {
+            background: false,
+            worktree_isolation: false,
+            mcp: true,
+            trust_tier: 'local-dev',
+        }),
+        createAdapter('codesdd-agent-cloudcode', 'cloudcode', 'Claude Code CloudCode', 'cloud', 'cloudcode', {
+            background: true,
+            worktree_isolation: true,
+            mcp: true,
+            trust_tier: 'enterprise-approved',
+            network: 'restricted',
+        }),
+        createAdapter('codesdd-agent-deepagents', 'deepagents', 'DeepAgents Governed Runtime', 'local-cli', 'codesdd-agent-run', {
+            background: true,
+            worktree_isolation: true,
+            mcp: true,
+            trust_tier: 'enterprise-approved',
+            network: 'restricted',
+        }),
+        createAdapter('codesdd-agent-fake-test', 'fake', 'Fake Deterministic Agent', 'test-double', undefined, {
+            background: false,
+            worktree_isolation: true,
+            mcp: false,
+            trust_tier: 'experimental',
+        }),
+    ];
+}
+export function resolveAgentBindingAdapter(adapters, request) {
+    const parsedAdapters = adapters.map((adapter) => agentBindingAdapterSchema.parse(adapter));
+    const parsedRequest = agentBindingResolutionRequestSchema.parse(request);
+    const createdAt = parsedRequest.created_at ?? new Date().toISOString();
+    const reasons = [];
+    const candidates = parsedAdapters.flatMap((adapter) => buildCandidate(adapter, parsedRequest, reasons));
+    const sortedCandidates = candidates.sort(compareCandidates);
+    const [selected] = sortedCandidates;
+    if (!selected) {
+        return agentBindingResolutionSchema.parse({
+            schema_version: 1,
+            created_at: createdAt,
+            status: 'fallback',
+            request: {
+                ...parsedRequest,
+                created_at: createdAt,
+            },
+            reasons: reasons.length > 0 ? reasons : ['No compatible agent adapter was found.'],
+            candidates: [],
+            fallback: {
+                strategy: 'no-compatible-agent',
+                message: 'Continue with manual execution or configure a compatible agent adapter before delegating work.',
+            },
+        });
+    }
+    return agentBindingResolutionSchema.parse({
+        schema_version: 1,
+        created_at: createdAt,
+        status: 'resolved',
+        request: {
+            ...parsedRequest,
+            created_at: createdAt,
+        },
+        selected,
+        candidates: sortedCandidates,
+        reasons: [
+            `Resolved ${parsedRequest.task_kind} to ${selected.adapter_ref.id} (${selected.adapter_ref.provider}).`,
+            ...selected.reasons,
+        ],
+    });
+}
+function createAdapter(id, provider, label, mode, command, options) {
+    return agentBindingAdapterSchema.parse({
+        schema_version: 1,
+        id,
+        provider,
+        label,
+        execution: {
+            mode,
+            command,
+            args: [],
+            network: options.network ?? 'disabled',
+            evidence_contract: 'agent-evidence/v1',
+        },
+        capabilities: [
+            capability('planning', true, false, options, 'low'),
+            capability('review', true, false, options, 'low'),
+            capability('validation', true, false, options, 'medium'),
+            capability('implementation', false, true, options, 'high'),
+            capability('reverse-engineering', true, false, options, 'medium'),
+            capability('plugin-execution', false, true, options, 'high'),
+            capability('adr-governance', false, true, options, 'medium'),
+            capability('quality-witness', true, false, options, 'medium'),
+            capability('documentation-sync', false, true, options, 'medium'),
+        ],
+        governance: {
+            owner: 'platform-engineering',
+            trust_tier: options.trust_tier,
+            approval: provider === 'fake' ? 'none' : 'maintainer',
+            notes: [`${label} adapter is declarative and non-executing in FEAT-0150.`],
+        },
+    });
+}
+function capability(taskKind, readOnly, edits, options, riskTier) {
+    return agentBindingCapabilitySchema.parse({
+        task_kind: taskKind,
+        description: `${taskKind} capability advertised by the agent binding adapter.`,
+        read_only: readOnly,
+        edits,
+        background: options.background,
+        worktree_isolation: options.worktree_isolation,
+        mcp: options.mcp,
+        skills: true,
+        structured_evidence: true,
+        risk_tier: riskTier,
+    });
+}
+function buildCandidate(adapter, request, reasons) {
+    const capability = adapter.capabilities.find((candidate) => candidate.task_kind === request.task_kind);
+    const rejectionReasons = collectRejectionReasons(adapter, capability, request);
+    if (rejectionReasons.length > 0) {
+        reasons.push(...rejectionReasons.map((reason) => `${adapter.id}/${request.task_kind}: ${reason}`));
+        return [];
+    }
+    const resolvedCapability = capability;
+    return [
+        agentBindingCandidateSchema.parse({
+            adapter_ref: {
+                id: adapter.id,
+                provider: adapter.provider,
+                label: adapter.label,
+            },
+            task_kind: resolvedCapability.task_kind,
+            rank: rankCandidate(adapter, resolvedCapability, request),
+            reasons: candidateReasons(adapter, resolvedCapability),
+        }),
+    ];
+}
+function collectRejectionReasons(adapter, capability, request) {
+    const reasons = [];
+    if (request.provider && adapter.provider !== request.provider) {
+        reasons.push(`provider ${adapter.provider} does not match requested provider ${request.provider}.`);
+    }
+    if (!request.allowed_providers.includes(adapter.provider)) {
+        reasons.push(`provider ${adapter.provider} is not allowed.`);
+    }
+    if (!request.statuses.includes(adapter.status)) {
+        reasons.push(`status ${adapter.status} is not eligible.`);
+    }
+    if (!request.trust_tiers.includes(adapter.governance.trust_tier)) {
+        reasons.push(`trust tier ${adapter.governance.trust_tier} is not eligible.`);
+    }
+    if (!capability) {
+        reasons.push(`task kind ${request.task_kind} is not advertised.`);
+        return reasons;
+    }
+    if (request.require_edits && !capability.edits) {
+        reasons.push('edits are required but not supported.');
+    }
+    if (request.require_background && !capability.background) {
+        reasons.push('background execution is required but not supported.');
+    }
+    if (request.require_worktree_isolation && !capability.worktree_isolation) {
+        reasons.push('worktree isolation is required but not supported.');
+    }
+    if (request.require_mcp && !capability.mcp) {
+        reasons.push('MCP support is required but not supported.');
+    }
+    if (request.require_skills && !capability.skills) {
+        reasons.push('skill support is required but not supported.');
+    }
+    if (request.require_structured_evidence && !capability.structured_evidence) {
+        reasons.push('structured evidence is required but not supported.');
+    }
+    return reasons;
+}
+function candidateReasons(adapter, capability) {
+    return [
+        `${adapter.label} supports ${capability.task_kind} with ${capability.edits ? 'edit' : 'read-only'} scope.`,
+    ];
+}
+function rankCandidate(adapter, capability, request) {
+    const providerRank = request.provider && adapter.provider === request.provider ? 100_000 : 0;
+    const trustRank = TRUST_RANK[adapter.governance.trust_tier] * 1_000;
+    const isolationRank = capability.worktree_isolation ? 200 : 0;
+    const backgroundRank = capability.background ? 100 : 0;
+    const mcpRank = capability.mcp ? 50 : 0;
+    const riskRank = RISK_RANK[capability.risk_tier] * 10;
+    return providerRank + trustRank + isolationRank + backgroundRank + mcpRank + riskRank;
+}
+function compareCandidates(left, right) {
+    if (right.rank !== left.rank) {
+        return right.rank - left.rank;
+    }
+    return left.adapter_ref.id.localeCompare(right.adapter_ref.id);
+}
+//# sourceMappingURL=agent-binding.js.map

package/dist/core/sdd/agent-runtime-contract.d.ts

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+export declare const agentRuntimeProviderSchema: z.ZodEnum<{
+    codex: "codex";
+    opencode: "opencode";
+    deepagents: "deepagents";
+}>;
+export declare const agentRuntimeModeSchema: z.ZodEnum<{
+    validate: "validate";
+    "read-only": "read-only";
+    plan: "plan";
+    "apply-sandbox": "apply-sandbox";
+    "apply-approved": "apply-approved";
+}>;
+export declare const agentRuntimeSandboxSchema: z.ZodEnum<{
+    "read-only": "read-only";
+    "workspace-write": "workspace-write";
+    "danger-full-access": "danger-full-access";
+}>;
+export declare const agentRuntimeStatusSchema: z.ZodEnum<{
+    blocked: "blocked";
+    planned: "planned";
+}>;
+export declare const opencodeExecutionStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    blocked: "blocked";
+    planned: "planned";
+    failed: "failed";
+    skipped: "skipped";
+    running: "running";
+}>;
+export declare const agentRuntimeCommandPlanRequestSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+    feature_ref: z.ZodString;
+    provider: z.ZodEnum<{
+        codex: "codex";
+        opencode: "opencode";
+        deepagents: "deepagents";
+    }>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        validate: "validate";
+        "read-only": "read-only";
+        plan: "plan";
+        "apply-sandbox": "apply-sandbox";
+        "apply-approved": "apply-approved";
+    }>>;
+    instruction: z.ZodString;
+    cwd: z.ZodDefault<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    sandbox: z.ZodDefault<z.ZodEnum<{
+        "read-only": "read-only";
+        "workspace-write": "workspace-write";
+        "danger-full-access": "danger-full-access";
+    }>>;
+    output_schema: z.ZodOptional<z.ZodString>;
+    output_last_message: z.ZodOptional<z.ZodString>;
+    agent: z.ZodOptional<z.ZodString>;
+    session: z.ZodOptional<z.ZodString>;
+    files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    approval_grants: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        maintainer: "maintainer";
+        security: "security";
+        "architecture-board": "architecture-board";
+    }>>>;
+}, z.core.$strip>;
+export declare const agentRuntimeCommandPlanSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    created_at: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        planned: "planned";
+    }>;
+    request: z.ZodObject<{
+        schema_version: z.ZodDefault<z.ZodLiteral<1>>;
+        feature_ref: z.ZodString;
+        provider: z.ZodEnum<{
+            codex: "codex";
+            opencode: "opencode";
+            deepagents: "deepagents";
+        }>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            validate: "validate";
+            "read-only": "read-only";
+            plan: "plan";
+            "apply-sandbox": "apply-sandbox";
+            "apply-approved": "apply-approved";
+        }>>;
+        instruction: z.ZodString;
+        cwd: z.ZodDefault<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        sandbox: z.ZodDefault<z.ZodEnum<{
+            "read-only": "read-only";
+            "workspace-write": "workspace-write";
+            "danger-full-access": "danger-full-access";
+        }>>;
+        output_schema: z.ZodOptional<z.ZodString>;
+        output_last_message: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        session: z.ZodOptional<z.ZodString>;
+        files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        approval_grants: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            maintainer: "maintainer";
+            security: "security";
+            "architecture-board": "architecture-board";
+        }>>>;
+    }, z.core.$strip>;
+    provider: z.ZodEnum<{
+        codex: "codex";
+        opencode: "opencode";
+        deepagents: "deepagents";
+    }>;
+    command: z.ZodOptional<z.ZodObject<{
+        executable: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        stdin: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    evidence_contract: z.ZodEnum<{
+        "agent-runtime-v2/deepagents": "agent-runtime-v2/deepagents";
+        "agent-runtime-v2/codex-exec": "agent-runtime-v2/codex-exec";
+        "agent-runtime-v2/opencode-run": "agent-runtime-v2/opencode-run";
+    }>;
+    structured_output: z.ZodBoolean;
+    reasons: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    policy: z.ZodObject<{
+        direct_state_write_allowed: z.ZodLiteral<false>;
+        requires_codesdd_finalize: z.ZodLiteral<true>;
+        mutating_modes_require_approval: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const opencodeExecutionEvidenceSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    contract: z.ZodLiteral<"agent-runtime-v2/opencode-run">;
+    provider: z.ZodLiteral<"opencode">;
+    feature_ref: z.ZodString;
+    run_id: z.ZodString;
+    created_at: z.ZodString;
+    mode: z.ZodEnum<{
+        validate: "validate";
+        "read-only": "read-only";
+        plan: "plan";
+        "apply-sandbox": "apply-sandbox";
+        "apply-approved": "apply-approved";
+    }>;
+    status: z.ZodEnum<{
+        completed: "completed";
+        blocked: "blocked";
+        planned: "planned";
+        failed: "failed";
+        skipped: "skipped";
+        running: "running";
+    }>;
+    command: z.ZodObject<{
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        stdin: z.ZodOptional<z.ZodString>;
+        executable: z.ZodLiteral<"opencode">;
+    }, z.core.$strip>;
+    command_plan_ref: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodDefault<z.ZodString>;
+    exit_code: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    started_at: z.ZodOptional<z.ZodString>;
+    completed_at: z.ZodOptional<z.ZodString>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    structured_output: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stdout_excerpt: z.ZodOptional<z.ZodString>;
+    stderr_excerpt: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        ref: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    validations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    redactions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    risks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        summary: z.ZodString;
+        mitigation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    policy: z.ZodObject<{
+        direct_state_write_allowed: z.ZodLiteral<false>;
+        requires_codesdd_finalize: z.ZodLiteral<true>;
+        raw_secret_output_allowed: z.ZodLiteral<false>;
+        transcript_storage: z.ZodDefault<z.ZodEnum<{
+            forbidden: "forbidden";
+            "redacted-excerpts-only": "redacted-excerpts-only";
+        }>>;
+    }, z.core.$strip>;
+    finalize_intent: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AgentRuntimeProvider = z.infer<typeof agentRuntimeProviderSchema>;
+export type AgentRuntimeMode = z.infer<typeof agentRuntimeModeSchema>;
+export type AgentRuntimeCommandPlanRequest = z.infer<typeof agentRuntimeCommandPlanRequestSchema>;
+export type AgentRuntimeCommandPlan = z.infer<typeof agentRuntimeCommandPlanSchema>;
+export type OpenCodeExecutionEvidence = z.infer<typeof opencodeExecutionEvidenceSchema>;
+export type OpenCodeExecutionEvidenceInput = z.input<typeof opencodeExecutionEvidenceSchema>;
+export declare function buildAgentRuntimeCommandPlan(request: AgentRuntimeCommandPlanRequest, createdAt?: string): AgentRuntimeCommandPlan;
+export declare function buildOpenCodeExecutionEvidence(evidence: OpenCodeExecutionEvidenceInput): OpenCodeExecutionEvidence;
+export declare function buildAgentRuntimeJsonSchemas(): Record<string, unknown>;
+//# sourceMappingURL=agent-runtime-contract.d.ts.map