@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/orchestration/engine.d.ts

@@ -0,0 +1,82 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+import type { PhaseRunnerAgentManagerLike, WrfcWorktreeOps } from './phase-runner.js';
+import { type BudgetCeiling, type OrchestrationEventListener, type Phase, type PhaseResult, type PhaseSpec, type WorkItemSpec, type WorkItemUsage, type Workstream, type WorkstreamIsolation, type WorkstreamProvenance } from './types.js';
+import type { ConfigManager } from '../config/manager.js';
+import type { RuntimeEventBus } from '../runtime/events/index.js';
+export interface OrchestrationEngineDeps {
+    readonly agentManager: PhaseRunnerAgentManagerLike;
+    readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
+    readonly runtimeBus: RuntimeEventBus;
+    readonly projectRoot: string;
+    readonly sessionId?: string | undefined;
+    readonly createWorktree?: (() => WrfcWorktreeOps) | undefined;
+    readonly priceUsage?: ((model: string | undefined, usage: WorkItemUsage) => number | null) | undefined;
+    readonly skipClaimVerification?: boolean | undefined;
+    /** Bounds re-review cycles through a dynamically-inserted fix phase. Default 5 (mirrors WrfcController's default maxFixAttempts). */
+    readonly maxPhaseVisits?: number | undefined;
+    readonly now?: (() => number) | undefined;
+    /** Set false to skip wiring the debounced disk writer (tests that don't want filesystem side effects). Default true. */
+    readonly persist?: boolean | undefined;
+    /** Bounds how many KEPT (merge-conflict or dirty-after-fail/kill) worktrees a `worktree`-isolation workstream retains before oldest-first eviction. Default 20. Irrelevant to `shared`-isolation workstreams. */
+    readonly keptWorktreeCap?: number | undefined;
+}
+export interface CreateWorkstreamInput {
+    readonly id?: string | undefined;
+    readonly title: string;
+    readonly phases: readonly PhaseSpec[];
+    readonly items: readonly WorkItemSpec[];
+    readonly budget?: BudgetCeiling | undefined;
+    /**
+     * Where this workstream's item phases run their file changes. Omitted
+     * (the default) ⇒ `'shared'` — every existing caller's behavior is
+     * unchanged. See {@link WorkstreamIsolation} (types.ts) for the full
+     * contrast with `'worktree'` mode.
+     */
+    readonly isolation?: WorkstreamIsolation | undefined;
+    /**
+     * Workstream-level provenance (BIG-3 item 1). Set by `fromPlanProposal` when
+     * assembling from an approved PlanProposal; omitted by compat/`fromChainSpec`
+     * callers. Stored verbatim on the created Workstream.
+     */
+    readonly provenance?: WorkstreamProvenance | undefined;
+}
+export interface OrchestrationEngine {
+    createWorkstream(input: CreateWorkstreamInput): Workstream;
+    getWorkstream(id: string): Workstream | null;
+    listWorkstreams(): Workstream[];
+    insertPhase(workstreamId: string, afterOrdinal: number, spec: PhaseSpec): Phase | null;
+    /** Begin (or resume ticking) a workstream's pipeline. Idempotent — safe to call on an already-running workstream. */
+    start(workstreamId: string): void;
+    /** Abort a work item's in-flight agent (if any) and mark it terminally failed. Never affects sibling items. */
+    kill(itemId: string): boolean;
+    /**
+     * Replace (or clear, via `undefined`) a workstream's budget ceiling and
+     * immediately re-tick it, so any item already sitting in 'blocked-budget'
+     * gets reconsidered right away — the only recovery path for that state
+     * (see WorkItemState's 'blocked-budget' doc, types.ts). Returns false if
+     * the workstream doesn't exist.
+     */
+    updateBudget(workstreamId: string, ceiling: BudgetCeiling | undefined): boolean;
+    /**
+     * Reset a terminally-FAILED work item so it re-runs from its first phase —
+     * the documented recovery path (BIG-3 item 2) for a failed dependency and
+     * the dependents it left stuck in 'blocked-dependency'. updateBudget-style:
+     * mutates then immediately re-ticks, so the retry starts at once and any
+     * dependents unblock on the next tick after it passes. Returns false if the
+     * item doesn't exist or isn't in the 'failed' state (a passed or in-flight
+     * item is never disturbed).
+     */
+    retryItem(itemId: string): boolean;
+    getPhaseResults(workstreamId: string): readonly PhaseResult[];
+    serializeWorkstream(workstreamId: string): string | null;
+    /** Import a serialized snapshot (a full WorkstreamSnapshot JSON string, see persistence.ts). Refuses to overwrite a non-terminal in-memory workstream unless force=true. */
+    importWorkstream(snapshotJson: string, force?: boolean): boolean;
+    /** Import + start from the on-disk snapshot for one workstream id. */
+    resumeWorkstream(workstreamId: string): boolean;
+    /** Import + start every snapshot under .goodvibes/orchestration/. Returns the count resumed. */
+    resumeAllFromDisk(): number;
+    on(listener: OrchestrationEventListener): () => void;
+    dispose(): void;
+}
+export declare function createOrchestrationEngine(deps: OrchestrationEngineDeps): OrchestrationEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/platform/orchestration/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/engine.ts"],"names":[],"mappings":"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"}