@vincemakes/kiso-runtime 0.45.3 → 0.46.0

package/dist/tasks/journal.js

@@ -0,0 +1,124 @@
+/**
+ * ADR-0058 §6 — the task journal: execution truth for work that no longer
+ * sits inside a tool call.
+ *
+ * One append-only JSONL file per task. Every record that gates an external
+ * effect is DURABLE — written and fsynced — before the effect may begin:
+ * `planned` before the runner is spawned, `command_started` before the
+ * command runs, `terminal` before the task counts as ended. That is what
+ * lets `verdictOf` read a crash honestly: an absent record proves its effect
+ * never began; a present one proves only that it may have.
+ *
+ * The session log is conversation truth and never records a process
+ * lifecycle; this journal never records what the model knows. Neither
+ * decides the other's facts. `result_claimed` (ADR-0058 Amendment 7) is no
+ * exception: it says which tool execution took a transition over — so the
+ * delivery never notices it — not that the model saw it; that is the
+ * session log's, a durable successful tool_result for that execution.
+ */
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, writeSync } from "node:fs";
+/** Append one record and fsync it before returning — the write-ahead step. */
+export function appendRecord(file, record) {
+    const fd = openSync(file, "a");
+    try {
+        writeSync(fd, `${JSON.stringify(record)}\n`);
+        if (process.platform === "win32")
+            syncFile(file);
+        else
+            fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Windows: an append handle cannot be flushed (FlushFileBuffers needs
+ *  write access, which append mode drops), and the append must stay an
+ *  append (the runner and the manager both write the journal) — so the
+ *  flush goes through a read-write handle of its own. */
+export function syncFile(file) {
+    const fd = openSync(file, "r+");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** fsync a directory, so a file created in it survives a power loss too. */
+export function fsyncDir(dir) {
+    // Windows opens no directory as a file, so the entry is not flushed
+    // here: a process crash loses nothing, but the entry's power-loss
+    // ordering is not the guarantee POSIX's directory fsync gives (the
+    // Windows durability contract is P6's to state)
+    if (process.platform === "win32")
+        return;
+    const fd = openSync(dir, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** A journal that is not a sequence of records with at most a torn tail. */
+export class TaskJournalCorruptError extends Error {
+    file;
+    line;
+    constructor(file, line) {
+        super(`task journal ${file} is corrupt at line ${line} — a record follows an unreadable one`);
+        this.name = "TaskJournalCorruptError";
+        this.file = file;
+        this.line = line;
+    }
+}
+/** Every complete record, in order. A torn LAST line (a write cut by a
+ *  crash) is not a record: it is dropped, never guessed at. An unreadable
+ *  line with a record after it is corruption, and it fails loudly — the
+ *  verdicts are inferences from what is present, so nothing is skipped. */
+export function readRecords(file) {
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "")
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            if (lines.slice(i + 1).some((l) => l.trim() !== ""))
+                throw new TaskJournalCorruptError(file, i + 1);
+        }
+    }
+    return out;
+}
+/** How long a `planned` without a runner may wait for its runner to speak
+ *  before it counts as never run — the runner's first act is its record. */
+export const RUNNER_START_WINDOW_MS = 30_000;
+export function verdictOf(records, runnerAlive, now = Date.now()) {
+    const has = (type) => records.some((r) => r.type === type);
+    const terminal = records.find((r) => r.type === "terminal");
+    if (terminal !== undefined)
+        return {
+            kind: "ended",
+            exitCode: terminal.exitCode,
+            signal: terminal.signal,
+            stopped: has("stop_requested"),
+            ...(terminal.error !== undefined ? { error: terminal.error } : {}),
+        };
+    const planned = records.find((r) => r.type === "planned");
+    if (planned === undefined)
+        return { kind: "not_run" };
+    if (has("command_started"))
+        return runnerAlive ? { kind: "running", ready: has("ready") } : { kind: "unknown" };
+    if (has("runner_started"))
+        return runnerAlive ? { kind: "starting" } : { kind: "not_run" };
+    return now - planned.ts < RUNNER_START_WINDOW_MS ? { kind: "starting" } : { kind: "not_run" };
+}
+/** The recorded runner identity, if the runner has spoken. */
+export function runnerOf(records) {
+    const r = records.find((x) => x.type === "runner_started");
+    return r === undefined ? undefined : { pid: r.pid, startedAt: r.startedAt };
+}

package/dist/tasks/manager.d.ts

@@ -0,0 +1,219 @@
+/**
+ * ADR-0058 §6 — the TaskManager: one per session, the only door to a
+ * session's tasks.
+ *
+ * It owns the task directory (`<store root>/<session>.tasks/<id>/`, holding
+ * `journal.jsonl` and `output.log`), allocates ids (`t1`, `t2`, … — stable
+ * across restarts, read off the directory), writes the kiso-side records
+ * durably, and classifies every task from its journal plus a verified
+ * runner identity. It never spawns a process itself: a BACKEND does (the
+ * process backend lives with the shell, in tools-node), and any number of
+ * hosts reach tasks through this one manager — never by searching for a
+ * child process themselves.
+ *
+ * Two ways in: `start` — a runner owns the command (background work, it
+ * survives kiso); `adopt` — a foreground shell command promoted past its
+ * wait, which the kiso process that spawned it keeps owning. An adopted
+ * task's runner IS that kiso process: if kiso crashes the journal reads
+ * `unknown`, never ended, never re-run (ADR-0058 3b, D1).
+ *
+ * What it does not do (later steps): tell the model (3c), or decide whether
+ * an idle session wakes (3c).
+ */
+import type { AbortSignalLike } from "@vincemakes/kiso-core";
+import { type ClaimedTransition, type TaskAgent, type TaskProfile, type TaskState } from "./journal.js";
+/** Whether a recorded runner is still that process (ADR-0058 §6):
+ *  "verified" — the pid is live AND its OS start time is the recorded one;
+ *  "gone" — no such process, or another process holds the pid;
+ *  "unverifiable" — the pid is live but whose it is cannot be told (no
+ *  start time recorded, or none readable now). Only "verified" is the
+ *  runner: "when identity cannot be verified, the verdict is the gone row". */
+export type RunnerIdentity = "verified" | "gone" | "unverifiable";
+/** A backend runs one kind of task. The manager has already made `planned`
+ *  durable; the backend spawns the runner, which records itself. */
+export interface TaskBackend {
+    /** Spawn the runner for the task in `dir`; resolve once `runner_started`
+     *  is on disk (reject if the runner never speaks). */
+    spawn(spec: {
+        readonly dir: string;
+        readonly env: Readonly<Record<string, string | undefined>>;
+    }): Promise<void>;
+    identify(pid: number, startedAt: string): RunnerIdentity;
+    /** Signal a VERIFIED runner to stop (a sooner path than the journal's
+     *  `stop_requested`, which the runner watches; a no-op where signals
+     *  would kill the runner outright). */
+    signalStop(pid: number): void;
+}
+export interface TaskStartOptions {
+    readonly command: string;
+    readonly cwd: string;
+    readonly profile?: TaskProfile;
+    /** The runner's environment. The shell's own policy (stripped
+     *  credentials) is applied by the caller; nothing of it is written down. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The tool invocation that started the task, when one did. */
+    readonly executionId?: string;
+    /** A literal substring of the output that means "ready" (ADR-0058 §3). */
+    readonly readyWhen?: string;
+    /** ADR-0058 3d: start `file` with exactly `args` — no shell; `command`
+     *  is then the label. Given the task's directory, before it is planned. */
+    readonly exec?: (dir: string) => {
+        readonly file: string;
+        readonly args: readonly string[];
+    };
+    /** ADR-0058 §5: the task is a child agent (its role and session). */
+    readonly agent?: TaskAgent;
+}
+export interface TaskInfo {
+    readonly id: string;
+    readonly command: string;
+    readonly profile: TaskProfile;
+    /** "process": a runner owns it; "foreground": a promoted command its kiso owns. */
+    readonly backend: "process" | "foreground";
+    /** The tool invocation that started it, when one did. */
+    readonly executionId?: string;
+    /** Who asked for its stop, when someone did. */
+    readonly stoppedBy?: "person" | "model" | "exit";
+    /** An agent task's role and child session (ADR-0058 §5). */
+    readonly agent?: TaskAgent;
+    readonly state: TaskState;
+    readonly outputPath: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    /** ADR-0058 Amendment 7: the transitions a tool execution took over —
+     *  its result reports them, so they are never noticed. */
+    readonly claims?: readonly {
+        readonly transition: ClaimedTransition;
+        readonly executionId: string;
+    }[];
+}
+/** The name a task's end (or its runner's vanishing, or a start that never
+ *  ran) has for the model — as a notice says it, and as a claim records it. */
+export declare function endTransitionOf(task: TaskInfo): Exclude<ClaimedTransition, "ready"> | null;
+/** What `awaitSettled` saw: settled — the target reached (or any end);
+ *  claimed — taken over for the calling execution, so never announced. */
+export interface TaskSettled {
+    readonly info: TaskInfo;
+    readonly settled: boolean;
+    readonly claimed: boolean;
+}
+export interface TaskAdoptOptions {
+    readonly command: string;
+    readonly cwd: string;
+    /** The tool invocation that ran the command. */
+    readonly executionId?: string;
+    readonly readyWhen?: string;
+    /** The process that owns the command from now on — the caller itself:
+     *  its pid and OS start time ("" when it cannot be read). */
+    readonly runner: {
+        readonly pid: number;
+        readonly startedAt: string;
+    };
+    /** True when the ready line is what promoted it. */
+    readonly ready?: boolean;
+    /** Stop the command. The owner then reports `ended` or `unconfirmed`. */
+    readonly stop: () => void;
+}
+/** The owner's side of an adopted task: every record it writes is durable. */
+export interface AdoptedTask {
+    readonly id: string;
+    readonly outputPath: string;
+    ready(match: string): void;
+    ended(exitCode: number | null, signal: string | null): void;
+    /** A stop left these pids alive: no terminal — the task stays `unknown`. */
+    unconfirmed(pids: readonly number[]): void;
+}
+/** Who moved a running foreground command to the background (3e). */
+export type DetachBy = "person" | "steer";
+/** A running foreground execution that can become a task now (ADR-0058
+ *  §2 ways 3 and 4; 3e). Its owner registers it while it runs. */
+export interface Detachable {
+    /** When the command started (ms since the epoch): a steer detaches
+     *  only a command old enough (ADR-0057 §5; 3e D1). */
+    readonly startedAt: number;
+    /** Promote it now — the owner's own promotion (3b), with the reason. */
+    detach(by: DetachBy): void;
+}
+/** What changed, reported once each: the ready signal, the end, the runner
+ *  vanishing without an end, or a start that never ran. */
+export type TaskTransition = "ready" | "ended" | "unknown" | "not_run";
+export type TaskListener = (task: TaskInfo, transition: TaskTransition) => void;
+export interface TaskManagerOptions {
+    /** `<store root>/<session>.tasks` */
+    readonly root: string;
+    readonly backend: TaskBackend;
+    /** A first listener — the same as `subscribe` right after construction. */
+    readonly onTransition?: TaskListener;
+    /** How often live tasks are re-read. Default 500 ms. */
+    readonly pollMs?: number;
+    /** How long a live runner's identity is reused before it is checked
+     *  again. Default 5 s. Each check starts a process (`ps`; a PowerShell
+     *  on win32), so it is not repeated on every read; the journal still is,
+     *  so an end is seen at once. The cost: a runner that dies WITHOUT a
+     *  terminal keeps reading as `running` for up to this long after it
+     *  died (its cached verdict is still "verified"), then `unknown`. */
+    readonly identifyEveryMs?: number;
+}
+export declare class TaskManager {
+    #private;
+    readonly root: string;
+    constructor(options: TaskManagerOptions);
+    /** Hear every transition (delivery, the terminal, telemetry — any number
+     *  of them). Returns the unsubscribe. */
+    subscribe(listener: TaskListener): () => void;
+    /** Start a task. `planned` is durable before the runner is spawned. */
+    start(options: TaskStartOptions): Promise<TaskInfo>;
+    /** A running foreground command becomes a task this process owns:
+     *  `planned`, the owner's identity and `command_started` are durable
+     *  before this returns. The command is already running; nothing is
+     *  spawned. */
+    adopt(options: TaskAdoptOptions): AdoptedTask;
+    /** Every task of the session, oldest first. */
+    list(): TaskInfo[];
+    get(id: string): TaskInfo | undefined;
+    /** Stop a live task: `stop_requested` is durable first — the runner
+     *  watches its journal for it — then a VERIFIED runner is also signalled.
+     *  An unverifiable one is never signalled (its pid may be a stranger's
+     *  now); the record alone reaches it if it is ours. False when there is
+     *  nothing that could be stopped. */
+    stop(id: string, by: "person" | "model" | "exit"): boolean;
+    /** ADR-0058 Amendment 7: wait up to `ms` for task `id` to reach `until`
+     *  — "end" (ended, unknown, never run) or "ready" (ready, or any end) —
+     *  on behalf of a tool call whose result will report it. While it waits
+     *  the watcher never announces this task. What it observes is CLAIMED
+     *  for `executionId` — the caller's own execution: `result_claimed` is
+     *  durable first, then the transition counts as seen, so it is never
+     *  announced. A timeout, an abort, no execution id, an agent task (its
+     *  end belongs to its group, 3d) or a claim that cannot be written
+     *  claim nothing: the transition is announced as before. */
+    awaitSettled(id: string, until: "end" | "ready", ms: number, opts?: {
+        readonly executionId?: string;
+        readonly signal?: AbortSignalLike;
+    }): Promise<TaskSettled>;
+    /** 3e: a running foreground command that can become a task now —
+     *  registered by its owner while it runs; returns the unregister. Every
+     *  detach goes through here (ADR-0058 §6): the person's key, a steer. */
+    registerDetachable(executionId: string, detachable: Detachable): () => void;
+    /** Detach one registered execution. It is unregistered BEFORE it is
+     *  asked, so a second detach — two steers, a key racing a pending
+     *  auto-detach — is a no-op: one promotion, one task. */
+    detach(executionId: string, by: DetachBy): boolean;
+    /** Detach every registered execution; the ids that were detached. */
+    detachAll(by: DetachBy): string[];
+    /** What can be detached now, with when each started. */
+    detachable(): {
+        readonly executionId: string;
+        readonly startedAt: number;
+    }[];
+    /** A clean exit: stop every live task — or, `which: "moved"`, only the
+     *  ones this process owns (promoted foreground commands; a runner's task
+     *  is left running) — and wait for their terminals, up to `graceMs`.
+     *  Returns the ids still without a terminal: a stop REQUESTED, never
+     *  confirmed (3e). */
+    stopAll(by?: "person" | "exit", graceMs?: number, which?: "all" | "moved"): Promise<string[]>;
+    /** Start watching: every task is classified now (no transition for what
+     *  it already is), and live ones are re-read until they settle. */
+    observe(): void;
+    /** Stop watching. Tasks keep running. */
+    close(): void;
+}