@work-graph/cli 0.2.0

package/vendor/src/workGraphPromoteReadyApi.mjs

@@ -0,0 +1,115 @@
+import {
+  persistWorkItemUpdateToRepo,
+  readWorkItemsFromRepo,
+} from './intentTreeWorkItems.mjs';
+import {
+  evaluateCharterPreflightForPromoteFromRepo,
+} from './charterPreflightPromoteGate.mjs';
+import {
+  evaluatePromoteReadyEligibility,
+  transitionStatus,
+} from './workGraphRuntime.mjs';
+
+export const PROMOTE_READY_RESPONSE_SCHEMA = 'operator.promote-ready.response.v1';
+
+export function parsePromoteReadyRequestBody(rawBody) {
+  if (rawBody === undefined || rawBody === null) {
+    return {};
+  }
+
+  if (typeof rawBody === 'string' && rawBody.trim() === '') {
+    return {};
+  }
+
+  const body = typeof rawBody === 'string' ? JSON.parse(rawBody) : rawBody;
+
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw new TypeError('promote-ready body must be a JSON object');
+  }
+
+  return body;
+}
+
+export function buildPromoteReadyResponse(result) {
+  return {
+    schema: PROMOTE_READY_RESPONSE_SCHEMA,
+    ok: Boolean(result.ok),
+    error: result.error ?? null,
+    workId: result.workId ?? null,
+    previousStatus: result.previousStatus ?? null,
+    newStatus: result.newStatus ?? null,
+    unsatisfiedDependencies: result.unsatisfiedDependencies ?? [],
+    currentStatus: result.currentStatus ?? null,
+    persistedBacklog: Boolean(result.persistedBacklog),
+    persistBacklogError: result.persistBacklogError ?? null,
+    charterPreflight: result.charterPreflight ?? null,
+    charterViolations: result.charterViolations ?? [],
+    item: result.item ?? null,
+  };
+}
+
+export async function executePromoteReady(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const body = parsePromoteReadyRequestBody(options.body ?? {});
+  const workId = String(body.workId ?? body.taskId ?? '').trim();
+
+  if (workId === '') {
+    return buildPromoteReadyResponse({ ok: false, error: 'work_id_required' });
+  }
+
+  const items = await readWorkItemsFromRepo({ ...options, cwd });
+  const item = items.find((entry) => entry.id === workId);
+  if (!item) {
+    return buildPromoteReadyResponse({ ok: false, error: 'task_not_found', workId });
+  }
+
+  const charterPreflight = options.skipCharterPreflight === true
+    ? { ok: true, skipped: true }
+    : await evaluateCharterPreflightForPromoteFromRepo(item, options);
+
+  const eligibility = evaluatePromoteReadyEligibility(items, workId, {
+    charterPreflight: options.skipCharterPreflight === true ? undefined : charterPreflight,
+  });
+
+  if (!eligibility.ok) {
+    return buildPromoteReadyResponse(eligibility);
+  }
+
+  const previousStatus = eligibility.item.status;
+  let updatedItem = transitionStatus(eligibility.item, 'ready', {
+    evidence: `promote-ready: ${previousStatus}→ready via operator board`,
+  });
+
+  let persistedBacklog = false;
+  let persistBacklogError = null;
+
+  if (body.persistBacklog !== false && options.persistBacklog !== false) {
+    try {
+      await persistWorkItemUpdateToRepo({
+        ...options,
+        cwd,
+        item: updatedItem,
+      });
+      persistedBacklog = true;
+    } catch (error) {
+      persistBacklogError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  const ok = persistBacklogError === null && (persistedBacklog || body.persistBacklog === false || options.persistBacklog === false);
+
+  return buildPromoteReadyResponse({
+    ok,
+    error: persistBacklogError ? 'persist_failed' : null,
+    workId,
+    previousStatus,
+    newStatus: updatedItem.status,
+    persistedBacklog,
+    persistBacklogError,
+    item: {
+      id: updatedItem.id,
+      title: updatedItem.title,
+      status: updatedItem.status,
+    },
+  });
+}

package/vendor/src/workGraphRecoveryPolicy.mjs

@@ -0,0 +1,124 @@
+export const RECOVERY_PRESETS = {
+  WORKER_FAILED_FIRST: 'worker_failed_first',
+  WORKER_FAILED_REPEATED: 'worker_failed_repeated',
+  ENV_BLOCKER: 'env_blocker',
+  VERIFICATION_FAILED: 'verification_failed',
+  RATE_LIMIT_RETRY: 'rate_limit_retry',
+  NO_CLAIMABLE_TASK: 'no_claimable_task',
+  SUCCEEDED: 'succeeded',
+};
+
+export const RECOVERY_ACTIONS = {
+  RETRY_READY: 'retry_ready',
+  STAY_BLOCKED: 'stay_blocked',
+  STAY_VERIFY: 'stay_verify',
+  ESCALATE_HUMAN: 'escalate_human',
+  NOOP: 'noop',
+};
+
+const DEFAULT_MAX_RETRIES = 2;
+
+export function classifyFailure(output, context = {}) {
+  if (context.noClaimableTask) {
+    return 'no_task';
+  }
+
+  if (!output || output.status === 'succeeded') {
+    return 'succeeded';
+  }
+
+  const reason = String(output.failureReason || output.transitionRequest?.reason || '').toLowerCase();
+
+  if (reason.includes('go') || reason.includes('env') || reason.includes('eaddrinuse') || reason.includes('toolchain')) {
+    return 'env_blocker';
+  }
+
+  if (reason.includes('policy') || reason.includes('denied') || reason.includes('unsupported')) {
+    return 'policy_denied';
+  }
+
+  if (reason.includes('rate limit') || reason.includes('429')) {
+    return 'rate_limit';
+  }
+
+  if (reason.includes('verify') || reason.includes('test:') || context.taskStatus === 'verify') {
+    return 'verification_failed';
+  }
+
+  return 'model_failure';
+}
+
+export function suggestRecovery(failureClass, context = {}) {
+  const retryCount = Number(context.retryCount ?? 0);
+  const maxRetries = Number(context.maxRetries ?? DEFAULT_MAX_RETRIES);
+  const taskStatus = context.taskStatus ?? '';
+
+  if (failureClass === 'succeeded') {
+    return {
+      preset: RECOVERY_PRESETS.SUCCEEDED,
+      action: taskStatus === 'verify' ? RECOVERY_ACTIONS.STAY_VERIFY : RECOVERY_ACTIONS.NOOP,
+      reason: 'worker run succeeded',
+      retryAdvice: '',
+    };
+  }
+
+  if (failureClass === 'no_task') {
+    return {
+      preset: RECOVERY_PRESETS.NO_CLAIMABLE_TASK,
+      action: RECOVERY_ACTIONS.NOOP,
+      reason: 'no claimable ready task in snapshot',
+      retryAdvice: 'add ready WorkItem or resolve dependencies',
+    };
+  }
+
+  if (failureClass === 'env_blocker') {
+    return {
+      preset: RECOVERY_PRESETS.ENV_BLOCKER,
+      action: RECOVERY_ACTIONS.STAY_BLOCKED,
+      reason: 'environment blocker detected',
+      retryAdvice: 'fix environment gate and rerun tick',
+    };
+  }
+
+  if (failureClass === 'rate_limit') {
+    return {
+      preset: RECOVERY_PRESETS.RATE_LIMIT_RETRY,
+      action: RECOVERY_ACTIONS.RETRY_READY,
+      reason: 'rate limit detected; schedule retry with backoff',
+      retryAdvice: 'wait and rerun daemon tick',
+    };
+  }
+
+  if (failureClass === 'verification_failed') {
+    return {
+      preset: RECOVERY_PRESETS.VERIFICATION_FAILED,
+      action: RECOVERY_ACTIONS.RETRY_READY,
+      reason: 'verification gate failed',
+      retryAdvice: 'fix failing verification command and rerun tick',
+    };
+  }
+
+  if (retryCount >= maxRetries) {
+    return {
+      preset: RECOVERY_PRESETS.WORKER_FAILED_REPEATED,
+      action: RECOVERY_ACTIONS.ESCALATE_HUMAN,
+      reason: `worker failed ${retryCount + 1} times`,
+      retryAdvice: 'review worker-run evidence and narrow task scope or switch provider',
+    };
+  }
+
+  return {
+    preset: RECOVERY_PRESETS.WORKER_FAILED_FIRST,
+    action: failureClass === 'policy_denied' ? RECOVERY_ACTIONS.STAY_BLOCKED : RECOVERY_ACTIONS.RETRY_READY,
+    reason: failureClass === 'policy_denied' ? 'worker policy denied execution' : 'first worker failure',
+    retryAdvice: 'retry daemon tick after adjusting worker input or task scope',
+  };
+}
+
+export function buildRecoverySuggestionFromWorkerOutput(output, context = {}) {
+  const failureClass = classifyFailure(output, context);
+  return {
+    failureClass,
+    ...suggestRecovery(failureClass, context),
+  };
+}

package/vendor/src/workGraphRunnerQueueProjection.mjs

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import { readWorkerRunJournal } from './agentWorkerLiveLoop.mjs';
+import { readWorkItemsFromRepo } from './intentTreeWorkItems.mjs';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+export const RUNNER_QUEUE_PROJECTION_SCHEMA = 'workgraph.runner.queue.projection.v1';
+export const RUNNER_QUEUE_SQLITE_DDL = `
+CREATE TABLE IF NOT EXISTS workgraph_runner_queue_v1 (
+  task_id TEXT PRIMARY KEY,
+  status TEXT NOT NULL,
+  priority TEXT NOT NULL DEFAULT 'medium',
+  retry_count INTEGER NOT NULL DEFAULT 0,
+  next_run_at TEXT,
+  last_run_id TEXT,
+  last_run_status TEXT,
+  provider_id TEXT,
+  policy_hash TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`.trim();
+
+export function computeRunnerQueuePolicyHash(item) {
+  const payload = JSON.stringify({
+    id: item.id,
+    status: item.status,
+    dependsOn: [...(item.dependsOn ?? [])].sort(compareText),
+    priority: item.priority ?? 'medium',
+  });
+
+  return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+
+export function indexWorkerRunsByTaskId(entries) {
+  const byTask = new Map();
+
+  for (const entry of entries ?? []) {
+    if (!entry || typeof entry.taskId !== 'string' || entry.taskId.trim() === '') {
+      continue;
+    }
+
+    const existing = byTask.get(entry.taskId);
+    if (!existing || String(entry.recordedAt ?? '') > String(existing.recordedAt ?? '')) {
+      byTask.set(entry.taskId, entry);
+    }
+  }
+
+  return byTask;
+}
+
+export function buildRunnerQueueProjectionFromItems(items, options = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const journalByTask = indexWorkerRunsByTaskId(options.workerRuns ?? []);
+  const runnableStatuses = new Set(options.runnableStatuses ?? ['ready', 'claimed', 'verify', 'in_progress']);
+  const recordedAt = options.recordedAt ?? new Date(0).toISOString();
+
+  const rows = items
+    .filter((item) => runnableStatuses.has(item.status))
+    .map((item) => {
+      const lastRun = journalByTask.get(item.id);
+      return {
+        taskId: item.id,
+        title: item.title,
+        status: item.status,
+        priority: item.priority ?? 'medium',
+        retryCount: Number(lastRun?.retryCount ?? 0),
+        nextRunAt: item.status === 'ready' ? recordedAt : null,
+        lastRunId: lastRun?.runId ?? null,
+        lastRunStatus: lastRun?.status ?? null,
+        providerId: lastRun?.provider ?? null,
+        policyHash: computeRunnerQueuePolicyHash(item),
+        ownerRole: item.ownerRole ?? '',
+        dependsOn: [...(item.dependsOn ?? [])].sort(compareText),
+      };
+    })
+    .sort((left, right) => compareText(left.taskId, right.taskId));
+
+  return {
+    schema: RUNNER_QUEUE_PROJECTION_SCHEMA,
+    recordedAt,
+    source: options.source ?? 'workgraph.snapshot.v1',
+    rows,
+    summary: {
+      total: rows.length,
+      ready: rows.filter((row) => row.status === 'ready').length,
+      claimed: rows.filter((row) => row.status === 'claimed').length,
+      withLastRun: rows.filter((row) => row.lastRunId).length,
+    },
+    sqlite: {
+      ddl: RUNNER_QUEUE_SQLITE_DDL,
+      optional: true,
+      rebuildPolicy: 'delete-db-and-rebuild-from-step-canonical',
+    },
+  };
+}
+
+export async function syncRunnerQueueProjectionToSqlite(projection, options = {}) {
+  if (!projection || projection.schema !== RUNNER_QUEUE_PROJECTION_SCHEMA) {
+    throw new TypeError('projection must be workgraph.runner.queue.projection.v1');
+  }
+
+  let DatabaseSync;
+  try {
+    ({ DatabaseSync } = await import('node:sqlite'));
+  } catch {
+    return {
+      ok: false,
+      skipped: true,
+      reason: 'node:sqlite is not available in this runtime',
+      rowCount: 0,
+    };
+  }
+
+  const dbPath = options.dbPath;
+  if (!dbPath) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: 'dbPath is required for sqlite sync',
+      rowCount: 0,
+    };
+  }
+
+  const db = new DatabaseSync(dbPath);
+  try {
+    db.exec(RUNNER_QUEUE_SQLITE_DDL);
+    const upsert = db.prepare(`
+      INSERT INTO workgraph_runner_queue_v1 (
+        task_id, status, priority, retry_count, next_run_at,
+        last_run_id, last_run_status, provider_id, policy_hash, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(task_id) DO UPDATE SET
+        status=excluded.status,
+        priority=excluded.priority,
+        retry_count=excluded.retry_count,
+        next_run_at=excluded.next_run_at,
+        last_run_id=excluded.last_run_id,
+        last_run_status=excluded.last_run_status,
+        provider_id=excluded.provider_id,
+        policy_hash=excluded.policy_hash,
+        updated_at=excluded.updated_at
+    `);
+
+    for (const row of projection.rows) {
+      upsert.run(
+        row.taskId,
+        row.status,
+        row.priority,
+        row.retryCount,
+        row.nextRunAt,
+        row.lastRunId,
+        row.lastRunStatus,
+        row.providerId,
+        row.policyHash,
+        projection.recordedAt,
+      );
+    }
+
+    return {
+      ok: true,
+      skipped: false,
+      reason: '',
+      rowCount: projection.rows.length,
+      dbPath,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export async function readRunnerQueueProjectionFromRepo(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const items = await readWorkItemsFromRepo({ ...options, cwd });
+  const workerRuns = await readWorkerRunJournal({
+    cwd,
+    journalPath: options.journalPath ?? 'work/worker-runs.jsonl',
+  });
+
+  return buildRunnerQueueProjectionFromItems(items, {
+    workerRuns,
+    recordedAt: options.recordedAt,
+    source: options.source ?? (options.backlogPath ?? 'intent/index.bvc'),
+  });
+}