@voybio/ace-swarm 2.4.4 → 2.4.7

package/dist/goal-engine.d.ts

@@ -0,0 +1,155 @@
+/**
+ * ACE Goal Engine (WS-F).
+ *
+ * `startGoal("<objective>")` compiles a plan with ACE's own planner, then a
+ * self-paced driver loop (`runGoal`) executes it step-by-step under evidence-
+ * gated completion. A goal can leave `executing` only through one of four
+ * control-flow paths — evidence-gated success, budget exhaustion, operator
+ * stop, or an escalated blocker — so "declaring success by prose" is
+ * structurally impossible (there is no code path from a model message to
+ * `status: "done"`).
+ *
+ * That guarantee rests on the success contract carrying at least one
+ * machine-checkable obligation. A contract with none is refused at `startGoal`
+ * and again at verify time with `contract_uncheckable`, never satisfied
+ * vacuously — see {@link enforceableObligationCount}.
+ *
+ * This composes existing organs rather than forking a second orchestrator:
+ *   - planning:   proposePlan → validatePlan (blocking) → createTaskPlan
+ *   - execution:  getReadyTaskSteps / applyBridgeResultToStep / amendTaskPlan
+ *                 (the supervisor's own step primitives), one step per tick
+ *   - completion: the same artifact-existence check the ModelBridge false-
+ *                 completion gate uses, run against the compiled success contract
+ *
+ * The single new mechanism is the goal record + tick/budget policy. All side
+ * effects (spawning a step, running a verification command, checking an
+ * artifact, sleeping, posting) are injectable so the engine is driven
+ * hermetically in tests with a stub bridge.
+ */
+import type { BridgeResult } from "./model-bridge.js";
+import { type TaskPlan, type TaskStep } from "./orchestrator-supervisor.js";
+import type { ProposePlanResult } from "./plan-proposal.js";
+import { GoalRepository, type GoalEscalationKind, type GoalRecord, type SuccessContract } from "./store/repositories/goal-repository.js";
+export type { GoalRecord, GoalStatus, GoalBudgets, SuccessContract, } from "./store/repositories/goal-repository.js";
+export interface CompiledPlan {
+    proposal: ProposePlanResult;
+    verdict: {
+        ok: boolean;
+        score: number;
+        blocking_findings: string[];
+    };
+}
+export interface GoalEngineDeps {
+    workspaceRoot?: string;
+    /** Millisecond clock (injectable so budgets/heartbeats are deterministic). */
+    now?: () => number;
+    /** Executes one plan step. Default: local ModelBridge via runLocalModelTask. */
+    spawnStep?: (step: TaskStep, plan: TaskPlan, goal: GoalRecord) => Promise<BridgeResult>;
+    /** Compiles an objective into a validated proposal. Default: proposePlan+validatePlan. */
+    compilePlan?: (objective: string) => Promise<CompiledPlan>;
+    /** Runs a verification command; ok === (exit 0). Default: exec in workspace. */
+    runVerification?: (command: string, workspaceRoot: string) => Promise<{
+        ok: boolean;
+        output: string;
+    }>;
+    /** Returns true when an expected artifact exists. Default: fs existence check. */
+    artifactExists?: (path: string, workspaceRoot: string) => boolean;
+    /** Cooperative sleep between ticks. Default: real timer. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Status-event sink. Default: appendStatusEventSafe. */
+    emitStatusEvent?: (input: {
+        status: string;
+        summary: string;
+        payload: Record<string, unknown>;
+    }) => Promise<void>;
+    /** Vericify process-post sink. Default: appendVericifyProcessPostSafe. */
+    appendProcessPost?: (input: {
+        kind: GoalEscalationKind | "progress" | "completion";
+        summary: string;
+        reason_code?: string;
+        evidence_refs?: string[];
+    }) => Promise<void>;
+}
+export interface StartGoalOptions {
+    budget_hours?: number;
+    max_ticks?: number;
+    max_replans?: number;
+    plan_only?: boolean;
+    goal_id?: string;
+    /** Shell commands that must exit 0 before the goal can reach `done`. */
+    verify_commands?: string[];
+}
+interface ResolvedDeps {
+    workspaceRoot: string;
+    repo: GoalRepository;
+    now: () => number;
+    spawnStep: NonNullable<GoalEngineDeps["spawnStep"]>;
+    compilePlan: NonNullable<GoalEngineDeps["compilePlan"]>;
+    runVerification: NonNullable<GoalEngineDeps["runVerification"]>;
+    artifactExists: NonNullable<GoalEngineDeps["artifactExists"]>;
+    sleep: NonNullable<GoalEngineDeps["sleep"]>;
+    emitStatusEvent: NonNullable<GoalEngineDeps["emitStatusEvent"]>;
+    appendProcessPost: NonNullable<GoalEngineDeps["appendProcessPost"]>;
+}
+/**
+ * The number of machine-checkable obligations in a contract. Zero means the
+ * only thing standing between the model and `status: "done"` is the model's own
+ * assertion — which is exactly what this engine exists to prevent.
+ *
+ * `gate_ids` is excluded: nothing populates it yet (see goal-repository.ts).
+ */
+export declare function enforceableObligationCount(contract: SuccessContract): number;
+export interface StartGoalResult {
+    ok: boolean;
+    goal: GoalRecord;
+    reason_code?: string;
+    blocking_findings?: string[];
+}
+export declare function startGoal(objective: string, options?: StartGoalOptions, deps?: GoalEngineDeps): Promise<StartGoalResult>;
+export interface TickGoalResult {
+    goal: GoalRecord;
+    plan: TaskPlan;
+    progressed: boolean;
+    step_id?: string;
+    step_status?: TaskStep["status"];
+}
+export declare function tickGoal(goalId: string, deps?: GoalEngineDeps): Promise<TickGoalResult>;
+export interface ContractCheckResult {
+    ok: boolean;
+    missing_artifacts: string[];
+    missing_evidence_refs: string[];
+    failed_commands: string[];
+    /** True when the contract carries zero enforceable obligations. Never `ok`. */
+    uncheckable: boolean;
+}
+export declare function checkSuccessContract(d: ResolvedDeps, goal: GoalRecord): Promise<ContractCheckResult>;
+export interface RunGoalResult {
+    goal: GoalRecord;
+    plan?: TaskPlan;
+}
+export declare function runGoal(goalId: string, deps?: GoalEngineDeps): Promise<RunGoalResult>;
+export declare function resumeGoal(goalId: string, deps?: GoalEngineDeps): Promise<RunGoalResult>;
+export declare function stopGoal(goalId: string, deps?: GoalEngineDeps): GoalRecord;
+export interface GoalStatusView {
+    goal: GoalRecord;
+    plan?: TaskPlan;
+    ready_steps: string[];
+    plan_status?: string;
+}
+export declare function getGoalStatus(goalId: string, deps?: GoalEngineDeps): GoalStatusView | undefined;
+export declare function listGoals(filter?: {
+    status?: GoalRecord["status"];
+}, deps?: GoalEngineDeps): import("./store/repositories/goal-repository.js").GoalIndexEntry[];
+export declare class UnknownGoalError extends Error {
+    readonly goal_id: string;
+    readonly name = "UnknownGoalError";
+    constructor(goal_id: string);
+}
+/** A goal whose state cannot be revived by re-running it. Reported, not thrown, at the CLI. */
+export declare class GoalNotResumableError extends Error {
+    readonly goal_id: string;
+    readonly message: string;
+    readonly name = "GoalNotResumableError";
+    constructor(goal_id: string, message: string);
+}
+//# sourceMappingURL=goal-engine.d.ts.map