@voybio/ace-swarm 0.2.5 → 2.4.1

package/dist/orchestrator-supervisor.d.ts

@@ -1,4 +1,5 @@
 import type { BridgeResult } from "./model-bridge.js";
+import type { LocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
 export type TaskStepStatus = "planned" | "running" | "done" | "failed" | "skipped" | "blocked";
 export type TaskPlanStatus = "planning" | "executing" | "reviewing" | "blocked" | "done" | "failed";
 export interface TaskStep {
@@ -14,6 +15,25 @@ export interface TaskStep {
     job_id?: string;
     handoff_id?: string;
     blocked_reason?: string;
+    upstream_outputs?: {
+        step_id: string;
+        result_summary: string;
+        evidence_refs: string[];
+    }[];
+    expected_output_class?: "plain_text_plan" | "tool_envelope" | "code_artifact" | "structural_edit_plan" | "qa_verdict";
+    expected_artifacts?: Array<{
+        path: string;
+        required?: boolean;
+        evidence_ref_kind?: "artifact" | "diff" | "hash" | "test" | "gate";
+    }>;
+    allowed_tools?: string[];
+    forbidden_patterns?: string[];
+    required_evidence_refs?: string[];
+    structural_edit_plan_required?: boolean;
+    structural_edit_waiver?: {
+        reason: string;
+        evidence_ref: string;
+    };
 }
 export interface TaskPlan {
     plan_id: string;
@@ -36,6 +56,14 @@ export interface TaskPlanAmendment {
     reorder_step_ids?: string[];
     execution_mode?: TaskPlan["execution_mode"];
     vcx_cursor?: string;
+    evidence_refs?: string[];
+}
+export type IntentVerificationOutcome = "ok" | "revisit_step" | "replan_required";
+export interface IntentVerificationResult {
+    outcome: IntentVerificationOutcome;
+    reason: string;
+    reason_code?: string;
+    uncovered_clauses?: string[];
 }
 export interface SupervisorHooks {
     spawnStep: (step: TaskStep, plan: TaskPlan) => Promise<BridgeResult>;
@@ -73,6 +101,26 @@ export interface SupervisorHooks {
         summary: string;
         step_id?: string;
     }) => Promise<void>;
+    verifyIntent?: (input: {
+        plan: TaskPlan;
+        step: TaskStep;
+        result: BridgeResult;
+        intent_contract: unknown;
+        vericify_delta?: unknown;
+    }) => Promise<IntentVerificationResult>;
+    recordIntentVerificationFailure?: (input: {
+        plan: TaskPlan;
+        step: TaskStep;
+        result: BridgeResult;
+        verification: IntentVerificationResult;
+        from: TaskStepStatus;
+        to: TaskStepStatus;
+    }) => Promise<void>;
+    /** Called when replan_required: returns an amendment to insert steps covering uncovered clauses. */
+    replanForClauses?: (input: {
+        plan: TaskPlan;
+        uncovered_clauses: string[];
+    }) => Promise<TaskPlanAmendment | undefined>;
 }
 export interface SupervisorRunResult {
     plan: TaskPlan;
@@ -80,6 +128,7 @@ export interface SupervisorRunResult {
     job_ids: string[];
     circuit_opened: boolean;
     final_gate?: unknown;
+    blocked_reason?: string;
 }
 export declare function deriveTaskPlanStatus(plan: TaskPlan): TaskPlanStatus;
 export declare function createTaskPlan(input: {
@@ -92,6 +141,13 @@ export declare function getReadyTaskSteps(plan: TaskPlan): TaskStep[];
 export declare function markTaskStepStatus(plan: TaskPlan, stepId: string, status: TaskStepStatus, patch?: Partial<Omit<TaskStep, "step_id" | "status">>): TaskPlan;
 export declare function applyBridgeResultToStep(plan: TaskPlan, stepId: string, result: BridgeResult): TaskPlan;
 export declare function amendTaskPlan(plan: TaskPlan, amendment: TaskPlanAmendment): TaskPlan;
+export declare function collectUpstreamOutputs(plan: TaskPlan, step: TaskStep): {
+    step_id: string;
+    result_summary: string;
+    evidence_refs: string[];
+}[];
+export declare function applyBridgeResultToStepWithTransition(plan: TaskPlan, stepId: string, result: BridgeResult, repo?: LocalModelRuntimeRepository): Promise<TaskPlan>;
+export declare function amendTaskPlanWithTransition(plan: TaskPlan, amendment: TaskPlanAmendment, repo?: LocalModelRuntimeRepository, reason?: string, reason_code?: string): Promise<TaskPlan>;
 export declare function promoteParallelGroupToScheduler(plan: TaskPlan, parallelGroup: string, owner?: string): Promise<{
     plan: TaskPlan;
     job_ids: string[];

package/dist/orchestrator-supervisor.js

@@ -212,6 +212,63 @@ export function amendTaskPlan(plan, amendment) {
         vcx_cursor: amendment.vcx_cursor ?? plan.vcx_cursor,
     });
 }
+export function collectUpstreamOutputs(plan, step) {
+    const dependencyOutputs = (step.depends_on ?? [])
+        .map((depId) => plan.steps.find((s) => s.step_id === depId))
+        .filter((dep) => dep?.status === "done")
+        .map((dep) => ({
+        step_id: dep.step_id,
+        result_summary: dep.result_summary ?? "",
+        evidence_refs: dep.evidence_refs ?? [],
+    }));
+    const carriedOutputs = (step.upstream_outputs ?? []).filter((output) => Boolean(output) &&
+        typeof output.step_id === "string" &&
+        typeof output.result_summary === "string" &&
+        Array.isArray(output.evidence_refs));
+    const merged = new Map();
+    for (const output of [...dependencyOutputs, ...carriedOutputs]) {
+        merged.set(output.step_id, output);
+    }
+    return [...merged.values()];
+}
+export async function applyBridgeResultToStepWithTransition(plan, stepId, result, repo) {
+    const updated = applyBridgeResultToStep(plan, stepId, result);
+    if (repo && plan.plan_id) {
+        const step = plan.steps.find((s) => s.step_id === stepId);
+        const updatedStep = updated.steps.find((s) => s.step_id === stepId);
+        if (step && updatedStep) {
+            await repo.appendTransitionRecord({
+                subject_kind: "plan_step",
+                subject_id: `${plan.plan_id}/${stepId}`,
+                from: step.status,
+                to: updatedStep.status,
+                reason: result.summary ?? "(bridge result applied)",
+                reason_code: updatedStep.status === "done"
+                    ? "step_completed"
+                    : updatedStep.status === "blocked"
+                        ? "step_blocked"
+                        : "step_failed",
+                evidence_refs: result.evidence_refs ?? [],
+            });
+        }
+    }
+    return updated;
+}
+export async function amendTaskPlanWithTransition(plan, amendment, repo, reason, reason_code) {
+    const updated = amendTaskPlan(plan, amendment);
+    if (repo && plan.plan_id) {
+        await repo.appendTransitionRecord({
+            subject_kind: "plan_step",
+            subject_id: plan.plan_id,
+            from: plan.status,
+            to: updated.status,
+            reason: reason ?? "(plan amended)",
+            reason_code: reason_code ?? "manual_amendment",
+            evidence_refs: amendment.evidence_refs ?? [],
+        });
+    }
+    return updated;
+}
 export async function promoteParallelGroupToScheduler(plan, parallelGroup, owner = "capability-ops") {
     const readySteps = getReadyTaskSteps(plan).filter((step) => step.parallel_group === parallelGroup);
     if (readySteps.length === 0) {
@@ -285,6 +342,10 @@ export async function superviseTaskPlan(inputPlan, hooks) {
     });
     const handoffIds = [];
     const jobIds = [];
+    // Intent verification loop counters (Task 7)
+    let replanCount = 0;
+    const stepRetryCount = new Map();
+    let intentContract = undefined;
     if (!plan.vcx_cursor && hooks.getVericifyContext) {
         const contextPacket = await hooks.getVericifyContext(plan);
         const vcxCursor = extractVcxCursor(contextPacket);
@@ -311,7 +372,10 @@ export async function superviseTaskPlan(inputPlan, hooks) {
             }
         }
         const currentStep = readySteps[0];
-        plan = markTaskStepStatus(plan, currentStep.step_id, "running");
+        const upstreamOutputs = collectUpstreamOutputs(plan, currentStep);
+        plan = markTaskStepStatus(plan, currentStep.step_id, "running", {
+            upstream_outputs: upstreamOutputs.length > 0 ? upstreamOutputs : undefined,
+        });
         await hooks.emitStatusEvent?.({
             status: "in_progress",
             summary: `Running ${currentStep.step_id}: ${currentStep.task}`,
@@ -347,6 +411,102 @@ export async function superviseTaskPlan(inputPlan, hooks) {
                 };
             }
         }
+        // ── Intent verification loop (Task 7) ────────────────────────────────
+        if (hooks.verifyIntent) {
+            const verificationStep = plan.steps.find((s) => s.step_id === currentStep.step_id) ?? currentStep;
+            const verification = await hooks.verifyIntent({
+                plan,
+                step: verificationStep,
+                result,
+                intent_contract: intentContract,
+                vericify_delta: vericifyDelta,
+            });
+            if (verification.outcome === "revisit_step") {
+                const retries = stepRetryCount.get(currentStep.step_id) ?? 0;
+                if (retries < 1) {
+                    stepRetryCount.set(currentStep.step_id, retries + 1);
+                    await hooks.recordIntentVerificationFailure?.({
+                        plan,
+                        step: verificationStep,
+                        result,
+                        verification,
+                        from: verificationStep.status,
+                        to: "planned",
+                    });
+                    // Re-queue the step by resetting it to planned with failure context as upstream
+                    const retryContext = {
+                        step_id: `${currentStep.step_id}-retry-context`,
+                        result_summary: `Intent verification requested revisit: ${verification.reason}`,
+                        evidence_refs: verification.uncovered_clauses ?? [],
+                    };
+                    plan = amendTaskPlan(plan, {
+                        update_steps: [{
+                                step_id: currentStep.step_id,
+                                patch: {
+                                    status: "planned",
+                                    result_summary: undefined,
+                                    upstream_outputs: [
+                                        ...(verificationStep.upstream_outputs ?? []),
+                                        retryContext,
+                                    ],
+                                },
+                            }],
+                    });
+                    // Do not call amendPlan this iteration — continue to next loop pass
+                    continue;
+                }
+                else {
+                    await hooks.recordIntentVerificationFailure?.({
+                        plan,
+                        step: verificationStep,
+                        result,
+                        verification,
+                        from: verificationStep.status,
+                        to: "blocked",
+                    });
+                    plan = amendTaskPlan(plan, {
+                        update_steps: [{
+                                step_id: currentStep.step_id,
+                                patch: {
+                                    status: "blocked",
+                                    blocked_reason: verification.reason_code
+                                        ? `Intent verification failed (${verification.reason_code}): ${verification.reason}`
+                                        : `Intent verification failed: ${verification.reason}`,
+                                },
+                            }],
+                    });
+                }
+            }
+            else if (verification.outcome === "replan_required") {
+                await hooks.recordIntentVerificationFailure?.({
+                    plan,
+                    step: verificationStep,
+                    result,
+                    verification,
+                    from: verificationStep.status,
+                    to: "planned",
+                });
+                if (replanCount >= 2) {
+                    const blockedPlan = { ...plan, status: "blocked" };
+                    return {
+                        plan: withDerivedStatus(blockedPlan),
+                        handoff_ids: handoffIds,
+                        job_ids: jobIds,
+                        circuit_opened: false,
+                        blocked_reason: "intent_drift_unresolvable",
+                    };
+                }
+                replanCount += 1;
+                const uncovered = verification.uncovered_clauses ?? [];
+                if (hooks.replanForClauses && uncovered.length > 0) {
+                    const replanAmendment = await hooks.replanForClauses({ plan, uncovered_clauses: uncovered });
+                    if (replanAmendment) {
+                        plan = amendTaskPlan(plan, replanAmendment);
+                    }
+                }
+            }
+        }
+        // ── End intent verification loop ─────────────────────────────────────
         const amended = await hooks.amendPlan?.({
             plan,
             step: plan.steps.find((step) => step.step_id === currentStep.step_id) ?? currentStep,
@@ -372,6 +532,24 @@ export async function superviseTaskPlan(inputPlan, hooks) {
     }
     if (plan.steps.length > 0 && plan.steps.every((step) => step.status === "done" || step.status === "skipped")) {
         const finalGate = await hooks.executeGates?.(plan);
+        if (finalGate && typeof finalGate === "object" && finalGate.ok === false) {
+            const blockedPlan = {
+                ...plan,
+                status: "blocked",
+            };
+            await hooks.contextSnapshot?.(blockedPlan);
+            await hooks.emitStatusEvent?.({
+                status: "blocked",
+                summary: `Task plan ${plan.plan_id} blocked by failing gates`,
+            });
+            return {
+                plan: blockedPlan,
+                handoff_ids: handoffIds,
+                job_ids: jobIds,
+                circuit_opened: false,
+                final_gate: finalGate,
+            };
+        }
         await hooks.contextSnapshot?.(plan);
         await hooks.emitStatusEvent?.({
             status: "done",

package/dist/plan-proposal.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Workstream J — Planner contract: propose_plan, validate_plan, loadAcceptanceTraceContract.
+ * Extracted to its own module so both tools-agent.ts and runtime-executor.ts can import without
+ * a circular dependency (tools-agent already imports from runtime-executor).
+ */
+export type OrchestratorPlanSource = "explicit_steps" | "orchestrator_default_step" | "planner_model" | "deterministic_fallback";
+export type ExpectedOutputClass = "plain_text_plan" | "tool_envelope" | "code_artifact" | "structural_edit_plan" | "qa_verdict";
+export interface ContractArtifactExpectation {
+    path: string;
+    required?: boolean;
+    evidence_ref_kind?: "artifact" | "diff" | "hash" | "test" | "gate";
+}
+export interface PlanProposalStep {
+    role: string;
+    task: string;
+    depends_on?: string[];
+    tool_scope?: string[];
+    acceptance_criteria: string[];
+    stop_condition?: string[];
+    expected_output_class?: ExpectedOutputClass;
+    expected_artifacts?: ContractArtifactExpectation[];
+    allowed_tools?: string[];
+    forbidden_patterns?: string[];
+    required_evidence_refs?: string[];
+    structural_edit_plan_required?: boolean;
+    structural_edit_waiver?: {
+        reason: string;
+        evidence_ref: string;
+    };
+}
+export interface PlanProposal {
+    intent_summary: string;
+    success_criteria: string[];
+    steps: PlanProposalStep[];
+}
+export interface PlanValidationVerdict {
+    ok: boolean;
+    score: number;
+    blocking_findings: string[];
+    soft_findings: string[];
+}
+export interface ProposePlanResult {
+    plan_id: string;
+    status: "planning";
+    intent_summary: string;
+    success_criteria: string[];
+    steps: PlanProposalStep[];
+    plan_source: OrchestratorPlanSource;
+}
+export interface AcceptanceTraceContractStep {
+    step_id: string;
+    role: string;
+    task: string;
+    depends_on: string[];
+    tool_scope: string[];
+    verification_role: string | null;
+    acceptance_criteria?: string[];
+    stop_condition?: string[];
+    expected_output_class?: ExpectedOutputClass;
+    expected_artifacts?: ContractArtifactExpectation[];
+    allowed_tools?: string[];
+    forbidden_patterns?: string[];
+    required_evidence_refs?: string[];
+    structural_edit_plan_required?: boolean;
+    structural_edit_waiver?: {
+        reason: string;
+        evidence_ref: string;
+    };
+}
+export interface AcceptanceTraceContract {
+    version: number;
+    generated_at: string;
+    plan_id: string;
+    task: string;
+    plan_source: string;
+    intent_summary?: string;
+    success_criteria?: string[];
+    validation_verdict?: PlanValidationVerdict;
+    policies: {
+        inserted_research_before_spec: boolean;
+        ship_fanout_enabled: boolean;
+    };
+    steps: AcceptanceTraceContractStep[];
+}
+export declare function lookupProposal(plan_id: string): ProposePlanResult | undefined;
+export declare function inferExpectedOutputClass(step: Pick<PlanProposalStep, "role" | "tool_scope">): ExpectedOutputClass;
+/**
+ * Lightweight synchronous variant used in runtime preflights.
+ * Skips the model bridge call entirely and returns the deterministic goal scaffold.
+ * This keeps the preflight free of network I/O that could delay session startup.
+ */
+export declare function proposePlanDeterministic(task: string): ProposePlanResult;
+export declare function proposePlan(task: string, sessionId?: string): Promise<ProposePlanResult>;
+export declare function validatePlan(input: {
+    plan_id?: string;
+    proposal?: ProposePlanResult;
+    sessionId?: string;
+}): Promise<PlanValidationVerdict & {
+    plan_id: string;
+}>;
+export declare function loadAcceptanceTraceContract(plan_id: string): AcceptanceTraceContract | undefined;
+export declare function persistAcceptanceTraceMapWithContract(input: {
+    plan_id: string;
+    task: string;
+    plan_source: string;
+    intent_summary?: string;
+    success_criteria?: string[];
+    validation_verdict?: PlanValidationVerdict;
+    policies: {
+        inserted_research_before_spec: boolean;
+        ship_fanout_enabled: boolean;
+    };
+    steps: AcceptanceTraceContractStep[];
+}): Promise<string>;
+//# sourceMappingURL=plan-proposal.d.ts.map