akm-cli 0.8.7 → 0.8.14

package/dist/workflows/db.js

@@ -1,10 +1,11 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import path from "node:path";
-import { getWorkflowDbPath } from "../core/paths";
+import { getWorkflowDbPath } from "../core/paths.js";
+import { openDatabase } from "../storage/database.js";
+import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
 /**
  * workflow.db — Durable SQLite database for workflow run state.
  *
@@ -44,8 +45,12 @@ export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const db = new Database(dbPath);
+    const db = openDatabase(dbPath);
     db.exec("PRAGMA journal_mode = WAL");
+    // #589: 30 s busy timeout, matching index.db / state.db. Without it the
+    // default is 0 ms, so any concurrent writer fails immediately with
+    // SQLITE_BUSY.
+    db.exec("PRAGMA busy_timeout = 30000");
     db.exec("PRAGMA foreign_keys = ON");
     ensureBaseSchema(db);
     runMigrations(db);
@@ -102,6 +107,13 @@ function ensureBaseSchema(db) {
       ON workflow_run_steps(run_id, sequence_index);
   `);
 }
+// ── Migration engine ─────────────────────────────────────────────────────────
+//
+// The runner itself (ensureMigrationsTable + runMigrations) lives in the shared
+// engine at src/storage/engines/sqlite-migrations.ts. This module owns its own
+// MIGRATIONS array plus the pre-versioning `bootstrap` hook, and delegates
+// application to that shared runner. The {@link Migration} interface is imported
+// from there.
 /**
  * All workflow.db migrations in application order. New migrations are
  * APPENDED — never inserted in the middle or reordered.
@@ -121,29 +133,50 @@ const MIGRATIONS = [
         ON workflow_runs(scope_key, workflow_ref, status);
     `,
     },
+    // ── Migration 002 — record agent harness + session identity ──────────────────
+    //
+    // Persists the agent harness identifier (e.g. "claude-code", "opencode") and
+    // the platform-native session id that owns each workflow run. This is the
+    // first concrete slice of #501 / #506: capturing *who* is driving a run so a
+    // future (separately-approved) monitor can correlate workflow runs with
+    // session activity. Both columns are nullable — runs started outside an agent
+    // harness, and all pre-existing runs, simply have NULL identity.
+    {
+        id: "002-add-agent-identity",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN agent_harness TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN agent_session_id TEXT;
+
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_agent_session
+        ON workflow_runs(agent_harness, agent_session_id);
+    `,
+    },
+    // ── Migration 003 — check-in arming + per-step summary (#506) ────────────────
+    //
+    // Builds on the agent identity recorded by migration 002. Arms a file-signal
+    // check-in (a timestamp, NOT a background thread — see
+    // docs/technical/workflow-agent-checkin-adr.md) so a stalled run can be
+    // re-targeted with a `continue` directive, and adds a per-step `summary`
+    // column so step/workflow completion can capture and validate a required
+    // summary of work done. Both columns are nullable.
+    {
+        id: "003-checkin-and-step-summary",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN checkin_armed_at TEXT;
+      ALTER TABLE workflow_run_steps ADD COLUMN summary TEXT;
+    `,
+    },
 ];
 /**
  * Stable id of the scope_key migration. Exported for bootstrap detection and
  * tests.
  */
 const SCOPE_KEY_MIGRATION_ID = "001-add-scope-key";
-/**
- * Create the migrations table if it does not exist. Called unconditionally on
- * every open so a fresh database bootstraps correctly.
- */
-function ensureMigrationsTable(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS schema_migrations (
-      id         TEXT    PRIMARY KEY,
-      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
-    );
-  `);
-}
 /**
  * Detect whether a column exists on a given table.
  */
 function hasColumn(db, table, column) {
-    const rows = db.query(`PRAGMA table_info(${table})`).all();
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
     return rows.some((r) => r.name === column);
 }
 /**
@@ -171,24 +204,13 @@ function bootstrapPreVersioningDb(db) {
 /**
  * Apply every pending migration in a single transaction per migration.
  *
- * Each migration is applied in its own transaction so a failure in migration N
- * does not roll back already-applied migrations 1..N-1. The migration row is
- * inserted AFTER the DDL succeeds — a crash mid-migration leaves no row and
- * the migration is retried on next open.
+ * Delegates to the shared SQLite migration engine, passing the
+ * `bootstrapPreVersioningDb` hook so databases created before this file gained
+ * migration tracking back-fill their scope_key row instead of re-running the
+ * ALTER.
  *
  * Called automatically by {@link openWorkflowDatabase}.
  */
 export function runMigrations(db) {
-    ensureMigrationsTable(db);
-    bootstrapPreVersioningDb(db);
-    const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
-    const applied = new Set(appliedRows.map((r) => r.id));
-    for (const migration of MIGRATIONS) {
-        if (applied.has(migration.id))
-            continue;
-        db.transaction(() => {
-            db.exec(migration.up);
-            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
-        })();
-    }
+    runSqliteMigrations(db, MIGRATIONS, { bootstrap: bootstrapPreVersioningDb });
 }

package/dist/workflows/parser.js

@@ -11,10 +11,10 @@
  * line spans, accumulating `WorkflowError`s rather than throwing.
  */
 import { parse as yamlParse } from "yaml";
-import { parseFrontmatterBlock } from "../core/frontmatter";
-import { parseMarkdownToc } from "../core/markdown";
-import { WORKFLOW_SCHEMA_VERSION, } from "./schema";
-import { runSemanticChecks } from "./validator";
+import { parseFrontmatterBlock } from "../core/asset/frontmatter.js";
+import { parseMarkdownToc } from "../core/asset/markdown.js";
+import { WORKFLOW_SCHEMA_VERSION, } from "./schema.js";
+import { runSemanticChecks } from "./validator.js";
 const WORKFLOW_TITLE_PREFIX = "Workflow:";
 const STEP_PREFIX = "Step:";
 const STEP_ID_LINE = /^Step ID:\s+(.+?)\s*$/;

package/dist/workflows/renderer.js

@@ -9,11 +9,11 @@
  * uses the flat `WorkflowStepDefinition` type for backwards compatibility)
  * and into search hints for the indexer.
  */
-import { makeAssetRef } from "../core/asset-ref";
-import { UsageError } from "../core/errors";
-import { registerMetadataContributor } from "../indexer/metadata-contributors";
-import { cacheWorkflowDocument } from "./document-cache";
-import { parseWorkflow } from "./parser";
+import { makeAssetRef } from "../core/asset/asset-ref.js";
+import { UsageError } from "../core/errors.js";
+import { registerMetadataContributor } from "../indexer/passes/metadata-contributors.js";
+import { parseWorkflow } from "./parser.js";
+import { cacheWorkflowDocument } from "./runtime/document-cache.js";
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }

package/dist/workflows/runtime/agent-identity.js

@@ -0,0 +1,56 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Resolve the agent harness + session identity for the current process.
+ *
+ * This is the first concrete slice of #501 / #506: capturing *who* is driving a
+ * workflow run so a future (separately-approved) monitor can correlate runs
+ * with session activity. It deliberately does NOT start any background thread,
+ * timer, or daemon — it only reads identity that the surrounding agent harness
+ * already exposes via the environment.
+ *
+ * Resolution is best-effort and environment-driven:
+ *   - harness:    AKM_AGENT_HARNESS, else inferred from a known harness env var.
+ *   - sessionId:  AKM_SESSION_ID, else the harness-native session env var.
+ *
+ * Explicit values passed to `startWorkflowRun` always win over the environment.
+ *
+ * @module workflows/agent-identity
+ */
+import { denormalizeRuntimeIdentity } from "../../integrations/harnesses/index.js";
+function firstNonEmpty(env, keys) {
+    for (const key of keys) {
+        const value = env[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+/**
+ * Best-effort resolution of the agent harness + session id from the process
+ * environment. Returns `{ harness: null, sessionId: null }` when nothing is
+ * detectable (e.g. a human running the CLI directly).
+ */
+export function resolveAgentIdentity(env = process.env) {
+    // Explicit override always wins.
+    let harness = firstNonEmpty(env, ["AKM_AGENT_HARNESS"]);
+    if (!harness) {
+        // Infer the harness from a harness-specific *session* env var. We only
+        // infer when a concrete session id is present: the bare "this process is
+        // Claude Code" flag does not mean a given run is owned by an agent session,
+        // so it must not silently stamp identity onto manual CLI invocations.
+        if (firstNonEmpty(env, ["CLAUDE_SESSION_ID"])) {
+            // Runtime identity for Claude Code is "claude-code" (vs the canonical
+            // config id "claude"). Derived from the unified registry's bridge (#562)
+            // so the persisted runtime string can't drift — still emits "claude-code".
+            harness = denormalizeRuntimeIdentity("claude");
+        }
+        else if (firstNonEmpty(env, ["OPENCODE_SESSION_ID"])) {
+            harness = denormalizeRuntimeIdentity("opencode");
+        }
+    }
+    const sessionId = firstNonEmpty(env, ["AKM_SESSION_ID", "CLAUDE_SESSION_ID", "OPENCODE_SESSION_ID"]);
+    return { harness, sessionId };
+}

package/dist/workflows/runtime/checkin.js

@@ -0,0 +1,57 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Agent check-in: a no-background-thread "continue" nudge for stalled workflow
+ * runs (#506).
+ *
+ * The design decision (see docs/technical/workflow-agent-checkin-adr.md)
+ * reconciles #506 (file/command-loop signal) with #501 (background thread) in
+ * favour of the former. There is intentionally NO timer or resident process
+ * here. Arming a check-in writes a timestamp (`checkin_armed_at`) on the run
+ * row; the next time the agent polls the engine via `workflow next`/`status`,
+ * {@link evaluateCheckin} is called to decide — purely from timestamps — whether
+ * the run looks stalled and a strong `continue` directive should be surfaced
+ * through the normal command output.
+ *
+ * @module workflows/checkin
+ */
+/**
+ * Default stall window. If a run has been active and untouched for at least
+ * this long since the later of its last update and its armed timestamp, the
+ * next poll surfaces a check-in directive.
+ */
+export const CHECKIN_STALL_MS = 90_000;
+function parseIso(value) {
+    if (!value)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Pure check-in evaluator. Returns a `continue` directive when an *active* run
+ * has been idle past the stall window, otherwise `null`. Deterministic in
+ * `now`, so it is trivially unit-testable and free of timer flakiness.
+ */
+export function evaluateCheckin(run, now = Date.now(), stallMs = CHECKIN_STALL_MS) {
+    if (run.status !== "active")
+        return null;
+    const updated = parseIso(run.updatedAt);
+    const armed = parseIso(run.checkinArmedAt);
+    // Never armed → no check-in (opt-in per run via startWorkflowRun).
+    if (armed === null)
+        return null;
+    const last = Math.max(updated ?? armed, armed);
+    const idleMs = now - last;
+    if (idleMs < stallMs)
+        return null;
+    return {
+        signal: "continue",
+        directive: "CONTINUE: this workflow run has stalled with no progress. Resume immediately — " +
+            "re-read the current step's instructions, finish the outstanding work, then call " +
+            "`akm workflow complete` with a summary. Do not stop until the step is complete.",
+        idleMs,
+        agentHarness: run.agentHarness ?? null,
+        agentSessionId: run.agentSessionId ?? null,
+    };
+}