@nodeint/migent 0.1.3 → 0.1.5

package/dist/commands/skill.js

@@ -1,20 +1,21 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { printError } from "../display.js";
+import { isDirectory, isFile } from "../fs-utils.js";
 const SKILL_RELATIVE = path.join(".agents", "skills", "migent");
 const STATE_FILENAME = ".migent-template.json";
 const TEMPLATE_VERSION = 1;
+const MANAGED = ["SKILL.md", "references/schema-config.yaml", "references/schema-workflow.yaml"];
 export function installSkill(workspace) {
     const skillDirectory = path.join(workspace, SKILL_RELATIVE);
     if (existsSync(skillDirectory)) {
         printError(`${displayPath(skillDirectory, workspace)} already exists; use \`migent skill update\`.`);
         return 1;
     }
-    const content = templateContent();
     mkdirSync(skillDirectory, { recursive: true });
-    writeManagedSkill(skillDirectory, content);
+    writeManagedSkill(skillDirectory, readTemplate());
     process.stdout.write(`Installed ${displayPath(skillDirectory, workspace)}\n`);
     return 0;
 }
@@ -31,32 +32,56 @@ export function updateSkill(workspace, options = {}) {
         printError("Existing Migent skill is not managed by Migent; move it aside and run `migent skill install`.");
         return 1;
     }
-    const current = readFileSync(skillPath, "utf8");
     const installedDigest = state.content_sha256;
-    const currentDigest = digest(current);
-    if (installedDigest !== currentDigest && !options.force) {
+    if (typeof installedDigest !== "string") {
+        printError("Existing Migent skill is not managed by Migent; move it aside and run `migent skill install`.");
+        return 1;
+    }
+    const installed = readInstalled(skillDirectory);
+    if (hasLocalChanges(installed, installedDigest) && !options.force) {
         printError("Migent skill has local changes; rerun with `migent skill update --force` to replace them.");
         return 1;
     }
-    const content = templateContent();
-    if (current === content && installedDigest === currentDigest && state.template_version === TEMPLATE_VERSION) {
+    const template = readTemplate();
+    if (bundleDigest(installed) === bundleDigest(template) && state.template_version === TEMPLATE_VERSION) {
         process.stdout.write(`Already up to date: ${displayPath(skillDirectory, workspace)}\n`);
         return 0;
     }
-    writeManagedSkill(skillDirectory, content);
+    writeManagedSkill(skillDirectory, template);
     process.stdout.write(`Updated ${displayPath(skillDirectory, workspace)}\n`);
     return 0;
 }
-function templateContent() {
-    const nextToModule = fileURLToPath(new URL("../templates/migent/SKILL.md", import.meta.url));
-    return readFileSync(nextToModule, "utf8");
+function readTemplate() {
+    const root = fileURLToPath(new URL("../templates/migent/", import.meta.url));
+    return MANAGED.map((name) => [name, readFileSync(path.join(root, name), "utf8")]);
 }
-function writeManagedSkill(skillDirectory, content) {
-    writeFileSync(path.join(skillDirectory, "SKILL.md"), content, "utf8");
+function readInstalled(skillDirectory) {
+    const entries = [];
+    for (const name of MANAGED) {
+        const filePath = path.join(skillDirectory, name);
+        if (!isFile(filePath))
+            continue;
+        entries.push([name, readFileSync(filePath, "utf8")]);
+    }
+    return entries;
+}
+function hasLocalChanges(installed, installedDigest) {
+    if (bundleDigest(installed) === installedDigest)
+        return false;
+    const skill = installed.find(([name]) => name === "SKILL.md");
+    const references = installed.filter(([name]) => name !== "SKILL.md");
+    return !(skill !== undefined && references.length === 0 && skillOnlyDigest(skill[1]) === installedDigest);
+}
+function writeManagedSkill(skillDirectory, entries) {
+    for (const [name, content] of entries) {
+        const filePath = path.join(skillDirectory, name);
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        writeFileSync(filePath, content, "utf8");
+    }
     const state = {
         schema_version: 1,
         template_version: TEMPLATE_VERSION,
-        content_sha256: digest(content),
+        content_sha256: bundleDigest(entries),
     };
     writeFileSync(path.join(skillDirectory, STATE_FILENAME), `${JSON.stringify(state, null, 2)}\n`, "utf8");
 }
@@ -71,7 +96,17 @@ function readState(filePath) {
         return null;
     }
 }
-function digest(content) {
+function bundleDigest(entries) {
+    const hash = createHash("sha256");
+    for (const [name, content] of entries) {
+        hash.update(name);
+        hash.update("\0");
+        hash.update(content);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function skillOnlyDigest(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
 function displayPath(filePath, workspace) {
@@ -80,19 +115,3 @@ function displayPath(filePath, workspace) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isFile(filePath) {
-    try {
-        return statSync(filePath).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-function isDirectory(filePath) {
-    try {
-        return statSync(filePath).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}

package/dist/commands/watch.d.ts

@@ -1,7 +1,8 @@
-export declare function watchSession(workspace: string, sessionId: string, options?: {
+export declare function followSession(workspace: string, sessionId: string, options?: {
     once?: boolean;
     executionId?: string | null;
     untilTerminal?: boolean;
     jsonLines?: boolean;
     cursor?: number | null;
+    exitWhenDone?: boolean;
 }): Promise<number>;

package/dist/commands/watch.js

@@ -1,27 +1,43 @@
-import { openSync, readSync, closeSync, statSync } from "node:fs";
+import { openSync, readFileSync, readSync, closeSync, statSync } from "node:fs";
 import path from "node:path";
-import { CancellationRequested, ConfigurationError, SessionStore, log, raiseCancellation, readExecutionFile, watchSnapshot, } from "@nodeint/migent-kernel";
+import { CancellationRequested, ConfigurationError, corruptStatusMessage, SessionLock, SessionStore, log, readStatusFileState, readExecutionFile, statusDriftMessage, watchSnapshot, } from "@nodeint/migent-kernel";
 import { printNotice, printWatchEvent, printWatchSnapshot } from "../display.js";
+import { EXIT_BLOCKED, EXIT_CANCELLED, EXIT_OK } from "../exits.js";
+import { compareFollowLines, includeStreamLine, listStreamFiles, streamFollowStart, } from "../follow-log.js";
+import { isFile } from "../fs-utils.js";
+import { bindCancellationSignals, delay, throwIfCliCancelled } from "../signals.js";
+const SESSION_DONE_EXITS = {
+    completed: EXIT_OK,
+    blocked: EXIT_BLOCKED,
+    cancelled: EXIT_CANCELLED,
+};
 const TERMINAL_EXECUTION_STATUSES = new Set(["completed", "failed", "cancelled"]);
-export async function watchSession(workspace, sessionId, options = {}) {
+export async function followSession(workspace, sessionId, options = {}) {
     const once = options.once ?? false;
     const untilTerminal = options.untilTerminal ?? false;
     const jsonLines = options.jsonLines ?? false;
     const executionId = options.executionId ?? null;
     const cursor = options.cursor === undefined ? null : options.cursor;
-    if (once && untilTerminal)
-        throw new ConfigurationError("--once cannot be combined with --until.");
-    if (once && cursor !== null)
-        throw new ConfigurationError("--once cannot be combined with --cursor.");
-    if (untilTerminal && !executionId)
-        throw new ConfigurationError("--until requires --execution.");
-    if (cursor !== null && cursor < 0)
-        throw new ConfigurationError("--cursor must be >= 0.");
+    const exitWhenDone = options.exitWhenDone === true;
     const sessionDirectory = path.join(workspace, ".migent", "sessions", sessionId);
     const eventsPath = path.join(sessionDirectory, "events.jsonl");
-    if (!isFile(eventsPath))
+    const statusPath = path.join(sessionDirectory, "status.json");
+    if (readStatusFileState(statusPath).state === "corrupt") {
+        throw new ConfigurationError(corruptStatusMessage(statusPath));
+    }
+    if (!isFile(eventsPath) && !(once && isFile(path.join(sessionDirectory, "status.json")))) {
         throw new ConfigurationError(`No events found for session: ${sessionId}`);
-    new SessionStore(workspace).reapOrphanedExecutions(sessionId, "ignore");
+    }
+    // Reaping writes, so it needs the session lock. A live holder keeps the session; follow then tails read-only.
+    const reapLock = SessionLock.tryAcquire(sessionDirectory);
+    if (reapLock !== null) {
+        try {
+            new SessionStore(workspace).reapOrphanedExecutions(sessionId, "ignore");
+        }
+        finally {
+            reapLock.release();
+        }
+    }
     let executionPath = null;
     if (executionId !== null) {
         const resolved = path.join(sessionDirectory, "executions", executionId, "execution.json");
@@ -30,56 +46,54 @@ export async function watchSession(workspace, sessionId, options = {}) {
             throw new ConfigurationError(`No execution found: ${executionId}`);
     }
     if (once) {
+        const drift = statusDriftMessage(workspace, sessionId);
+        if (drift)
+            printNotice(drift);
         printSnapshot(sessionDirectory, executionId, jsonLines);
         return 0;
     }
-    let followCursor = cursor;
-    if (followCursor === null) {
-        const snapshot = printSnapshot(sessionDirectory, executionId, jsonLines);
-        followCursor = Number(snapshot.events_cursor ?? 0);
+    const tailOnly = cursor === null;
+    let followCursor = cursor ?? 0;
+    let streamOffsets = null;
+    if (cursor === null) {
+        // Snapshot and the notice can block. Capture offsets first so lines written then are still tailed.
+        streamOffsets = new Map(listStreamFiles(sessionDirectory).map((stream) => [stream, fileSize(stream)]));
+        followCursor = fileSize(eventsPath);
+        printSnapshot(sessionDirectory, executionId, jsonLines, followCursor);
     }
     printNotice(`Watching session ${sessionId}.`);
-    const onSigint = () => {
-        try {
-            raiseCancellation(2);
-        }
-        catch {
-            // The command loop observes the pending cancellation.
-        }
-    };
-    const onSigterm = () => {
-        try {
-            raiseCancellation(15);
-        }
-        catch {
-            // The command loop observes the pending cancellation.
-        }
-    };
-    process.on("SIGINT", onSigint);
-    process.on("SIGTERM", onSigterm);
-    const fd = openSync(eventsPath, "r");
+    const unbind = bindCancellationSignals();
+    const logs = openFollowLogs(sessionDirectory, eventsPath, followCursor, tailOnly, streamOffsets);
     try {
-        let position = followCursor;
-        let pending = "";
         for (;;) {
-            const read = readCompleteLines(fd, position, pending);
-            position = read.position;
-            pending = read.pending;
-            for (const line of read.lines)
-                emitWatchEvent(line, executionId, jsonLines);
-            if (read.lines.length > 0)
+            throwIfCliCancelled();
+            discoverStreams(sessionDirectory, logs);
+            const batch = readBatch(logs);
+            for (const item of batch)
+                emitWatchEvent(item.line, executionId, jsonLines);
+            if (batch.length > 0)
                 continue;
             if (untilTerminal) {
                 if (executionPath === null)
                     throw new ConfigurationError("--until requires --execution.");
                 const record = readExecutionFile(executionPath);
                 if (record !== null && TERMINAL_EXECUTION_STATUSES.has(String(record.status))) {
-                    const drained = readCompleteLines(fd, position, pending);
-                    for (const line of drained.lines)
-                        emitWatchEvent(line, executionId, jsonLines);
+                    const drained = readBatch(logs);
+                    for (const item of drained)
+                        emitWatchEvent(item.line, executionId, jsonLines);
                     return untilTerminalExitCode(record);
                 }
             }
+            if (exitWhenDone) {
+                const status = String(watchSnapshot(sessionDirectory, null).status ?? "");
+                const done = SESSION_DONE_EXITS[status];
+                if (done !== undefined) {
+                    const drained = readBatch(logs);
+                    for (const item of drained)
+                        emitWatchEvent(item.line, executionId, jsonLines);
+                    return done;
+                }
+            }
             await delay(250);
         }
     }
@@ -91,19 +105,26 @@ export async function watchSession(workspace, sessionId, options = {}) {
         throw error;
     }
     finally {
-        closeSync(fd);
-        process.off("SIGINT", onSigint);
-        process.off("SIGTERM", onSigterm);
+        for (const log of logs)
+            closeSync(log.fd);
+        unbind();
     }
 }
-function printSnapshot(sessionDirectory, executionId, jsonLines) {
+function printSnapshot(sessionDirectory, executionId, jsonLines, eventsCursor) {
     const snapshot = watchSnapshot(sessionDirectory, executionId);
+    if (eventsCursor !== undefined)
+        snapshot.events_cursor = eventsCursor;
     if (jsonLines)
-        process.stdout.write(`${JSON.stringify(snapshot)}\n`);
+        process.stdout.write(`${JSON.stringify(snapshotJson(snapshot))}\n`);
     else
         printWatchSnapshot(snapshot);
     return snapshot;
 }
+function snapshotJson(snapshot) {
+    const body = { ...snapshot };
+    delete body.task;
+    return body;
+}
 function emitWatchEvent(line, executionId, jsonLines) {
     let event;
     try {
@@ -129,10 +150,65 @@ function untilTerminalExitCode(record) {
             return 0;
         return 1;
     }
-    if (record.status === "failed" || record.status === "cancelled")
-        return 1;
     return 1;
 }
+function openFollowLogs(sessionDirectory, eventsPath, cursor, tailOnly, streamOffsets) {
+    const eventsText = !tailOnly && cursor > 0 ? readText(eventsPath) : "";
+    const logs = [openLog(eventsPath, cursor, null, "events")];
+    for (const stream of listStreamFiles(sessionDirectory)) {
+        const start = tailOnly
+            ? { offset: tailOffset(stream, streamOffsets), minTimestampMs: null }
+            : streamFollowStart(cursor, eventsText, fileSize(stream));
+        logs.push(openLog(stream, start.offset, start.minTimestampMs, "stream"));
+    }
+    return logs;
+}
+function tailOffset(stream, streamOffsets) {
+    if (streamOffsets === null)
+        return fileSize(stream);
+    return streamOffsets.get(stream) ?? 0;
+}
+function discoverStreams(sessionDirectory, logs) {
+    const known = new Set(logs.map((log) => log.path));
+    for (const stream of listStreamFiles(sessionDirectory)) {
+        if (known.has(stream))
+            continue;
+        logs.push(openLog(stream, 0, null, "stream"));
+    }
+}
+function readBatch(logs) {
+    const batch = [];
+    for (const log of logs) {
+        const read = readCompleteLines(log.fd, log.offset, log.pending);
+        log.offset = read.position;
+        log.pending = read.pending;
+        // A later poll can finish a torn line that is older than the cursor anchor.
+        const lines = read.lines.filter((line) => includeStreamLine(line, log.minTimestampMs));
+        for (const line of lines)
+            batch.push({ line, source: log.source, path: log.path });
+    }
+    batch.sort(compareFollowLines);
+    return batch;
+}
+function openLog(filePath, offset, minTimestampMs, source) {
+    return { path: filePath, fd: openSync(filePath, "r"), offset, pending: "", minTimestampMs, source };
+}
+function fileSize(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function readText(filePath) {
+    try {
+        return readFileSync(filePath, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
 function readCompleteLines(fd, position, pending) {
     const chunks = [];
     const buffer = Buffer.alloc(64 * 1024);
@@ -151,19 +227,6 @@ function readCompleteLines(fd, position, pending) {
     const rest = pieces.pop() ?? "";
     return { lines: pieces, pending: rest, position: offset };
 }
-function delay(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
-}
-function isFile(filePath) {
-    try {
-        return statSync(filePath).isFile();
-    }
-    catch {
-        return false;
-    }
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/commands/workspace-registry.js

@@ -2,6 +2,7 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { ServiceError, callService, endpointFromHome, ensureRegistryHome, startDetached } from "@nodeint/migent-registry";
 import { printError } from "../display.js";
+import { PACKAGE_VERSION } from "../version.js";
 import { findWorkspace, invocationCwdPath } from "../workspace.js";
 export const workspaceApi = {
     startDetached,
@@ -25,7 +26,7 @@ export async function runRegister(workspacePath, name) {
         }
         throw error;
     }
-    const body = { path: root, tool: { name: "migent", version: "0.1.0" } };
+    const body = { path: root, tool: { name: "migent", version: PACKAGE_VERSION } };
     if (name !== null)
         body.name = name;
     if (!path.isAbsolute(String(body.path))) {
@@ -88,6 +89,14 @@ async function finish(method, requestPath, endpoint, body) {
     }
     if (status === 200 || status === 201) {
         process.stdout.write(`${JSON.stringify(payload)}\n`);
+        if (method === "POST") {
+            const id = typeof payload.id === "string" && payload.id !== "" ? payload.id : "workspace";
+            process.stderr.write(`Registered ${id}.\n`);
+        }
+        else if (method === "DELETE") {
+            const id = requestPath.split("/").pop() ?? "workspace";
+            process.stderr.write(`Removed ${id}.\n`);
+        }
         return 0;
     }
     return statusExit(status, payload);

package/dist/display.js

@@ -1,4 +1,5 @@
 import { createRequire } from "node:module";
+import { sessionFields } from "./session-row.js";
 const require = createRequire(import.meta.url);
 const pc = require("picocolors");
 export function printError(message) {
@@ -45,8 +46,8 @@ export function printSessions(rows) {
         return;
     }
     for (const row of rows) {
-        const [, sessionId, workflowId, status, executionId, decision, outputs, task] = row;
-        process.stdout.write(`${sessionId ?? ""}  ${workflowId ?? ""}  ${status ?? ""}  ${executionId ?? ""}  ${decision ?? ""}  ${outputs ?? ""}  ${task ?? ""}\n`);
+        const fields = sessionFields(row);
+        process.stdout.write(`${fields.session}  ${fields.workflow}  ${fields.status}  ${fields.execution}  ${fields.decision}  ${fields.outputs}  ${fields.task}\n`);
     }
 }
 export function printAgent(result, role, provider, model) {
@@ -74,13 +75,24 @@ export function printWatchSnapshot(snapshot) {
     }
     if (typeof snapshot.task === "string" && snapshot.task)
         lines.push(["task", snapshot.task]);
-    const executionId = snapshot.execution_id;
-    const executionStatus = snapshot.execution_status ?? snapshot.latest_execution_status;
-    if (typeof executionId === "string" && executionId) {
-        const value = typeof executionStatus === "string" && executionStatus
-            ? `${executionId} · ${executionStatus}`
-            : executionId;
-        lines.push(["execution", value]);
+    const running = Array.isArray(snapshot.running_stages) ? snapshot.running_stages.filter(isRecord) : [];
+    if (running.length > 0) {
+        for (const stage of running) {
+            const stageId = typeof stage.stage_id === "string" && stage.stage_id ? stage.stage_id : "stage";
+            const executionId = typeof stage.execution_id === "string" ? stage.execution_id : "";
+            const summary = typeof stage.summary === "string" && stage.summary ? ` · ${stage.summary}` : "";
+            lines.push(["running", `${stageId} · ${executionId}${summary}`]);
+        }
+    }
+    else {
+        const executionId = snapshot.execution_id;
+        const executionStatus = snapshot.execution_status ?? snapshot.latest_execution_status;
+        if (typeof executionId === "string" && executionId) {
+            const value = typeof executionStatus === "string" && executionStatus
+                ? `${executionId} · ${executionStatus}`
+                : executionId;
+            lines.push(["execution", value]);
+        }
     }
     const outcome = snapshot.outcome;
     if (isRecord(outcome) && typeof outcome.status === "string") {

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class PromptCancelled extends Error {
+    constructor();
+}

package/dist/errors.js

@@ -0,0 +1,6 @@
+export class PromptCancelled extends Error {
+    constructor() {
+        super("Prompt cancelled.");
+        this.name = "PromptCancelled";
+    }
+}

package/dist/exits.d.ts

@@ -0,0 +1,10 @@
+export declare const EXIT_OK = 0;
+export declare const EXIT_BLOCKED = 1;
+export declare const EXIT_CONFIG = 2;
+export declare const EXIT_ATTEMPTS = 3;
+export declare const EXIT_REVISIONS = 4;
+export declare const EXIT_DISPATCHES = 5;
+export declare const EXIT_VERIFY = 6;
+export declare const EXIT_CANCELLED = 130;
+export declare const LOOP_EXITS: string[];
+export declare const STAGE_EXITS: string[];

package/dist/exits.js

@@ -0,0 +1,26 @@
+export const EXIT_OK = 0;
+export const EXIT_BLOCKED = 1;
+export const EXIT_CONFIG = 2;
+export const EXIT_ATTEMPTS = 3;
+export const EXIT_REVISIONS = 4;
+export const EXIT_DISPATCHES = 5;
+export const EXIT_VERIFY = 6;
+export const EXIT_CANCELLED = 130;
+export const LOOP_EXITS = [
+    `Exit ${EXIT_OK} when the session is completed.`,
+    `Exit ${EXIT_BLOCKED} when the session is blocked. session continue runs that stage again.`,
+    `Exit ${EXIT_CONFIG} on a configuration error.`,
+    `Exit ${EXIT_ATTEMPTS} when --attempts is spent. The session stays active.`,
+    `Exit ${EXIT_REVISIONS} when a route would exceed max_revisions. The session stays active.`,
+    `Exit ${EXIT_DISPATCHES} when --max-dispatches is spent. The session stays active.`,
+    `Exit ${EXIT_VERIFY} when verify fails max_verify times. The session stays active.`,
+    `Exit ${EXIT_CANCELLED} when cancelled. session continue resumes that execution.`,
+];
+export const STAGE_EXITS = [
+    `Exit ${EXIT_OK} when the stage outcome is complete, or the session is already completed.`,
+    `Exit ${EXIT_BLOCKED} when the stage is not complete, or the session is blocked.`,
+    `Exit ${EXIT_CONFIG} on a configuration error.`,
+    `Exit ${EXIT_REVISIONS} when a route would exceed max_revisions. The session stays active.`,
+    `Exit ${EXIT_VERIFY} when verify fails max_verify times. The session stays active.`,
+    `Exit ${EXIT_CANCELLED} when cancelled. session continue resumes that execution.`,
+];

package/dist/follow-log.d.ts

@@ -0,0 +1,29 @@
+export interface FollowLine {
+    line: string;
+    source: "events" | "stream";
+    path: string;
+}
+export interface StreamFollowStart {
+    offset: number;
+    /** Skip stream lines whose timestamp parses earlier than this. The floor stays for later polls. */
+    minTimestampMs: number | null;
+}
+/**
+ * Where to start reading one execution stream.
+ * `--cursor` is a byte offset into events.jsonl. Stream lines are selected by timestamp.
+ * A stream created after follow starts is not passed here: the caller reads it from offset 0.
+ */
+export declare function streamFollowStart(cursor: number | null, eventsText: string, streamSize: number): StreamFollowStart;
+export declare function includeStreamLine(line: string, minTimestampMs: number | null): boolean;
+export declare function compareFollowLines(left: FollowLine, right: FollowLine): number;
+/** Lines follow would emit for this cursor, including a stream that appeared after the start. */
+export declare function replayFollowLines(input: {
+    cursor: number | null;
+    eventsText: string;
+    streams: Array<{
+        path: string;
+        text: string;
+        appearedAfterStart?: boolean;
+    }>;
+}): string[];
+export declare function listStreamFiles(sessionDirectory: string): string[];