@ai-setting/roy-plugin-task-show 0.6.11 → 0.8.4

package/README.md

@@ -23,6 +23,14 @@ When loaded into a `roy-agent` host, this plugin:
 4. Serves the visualization on a local HTTP server (default
    `http://127.0.0.1:7788/`) — index page, per-task detail page, and the
    `/api/events` SSE stream.
+5. **v0.7.0+ — Task lifecycle pipeline.** The per-task detail page now
+   also renders a vertical timeline of the task's own operation history
+   (`create`, `progress`, `milestone`, `problem`, `solution`, `decision`,
+   `review`, `completed`). The data comes from `roy-agent tasks get <id>
+   --operations --json`, served by a new endpoint `GET
+   /api/tasks/:id/operations`. See
+   [Task lifecycle pipeline (v0.7.0+)](#task-lifecycle-pipeline-v070) for
+   details.
 
 The result: every task gets a clickable link the user can open in a
 browser. Once open, the page **stays in sync** with the running agent
@@ -224,6 +232,31 @@ healthy.
 
 ## Changelog
 
+### v0.6.12 — Task lifecycle pipeline integration fix (2026-07-24)
+
+**For end users**: `npm install` as usual — no host-side change required.
+Re-published as a patch release to fix a regression in the v0.7.0-pre
+"Task lifecycle pipeline" feature where the page rendered the pipeline
+panel but never actually populated it with operations.
+
+- `renderOperationsPipeline(input)` now accepts `input.taskId` and emits
+  `data-task-id="<id>"` on the `<section data-pipeline-root>` element
+  (empty, populated, and error states). Non-numeric ids are silently
+  dropped, so bad input cannot break HTML attribute quoting.
+- `renderTaskPage()` in `src/server.ts` now passes `taskId: session.taskId`
+  so every `/task/<id>` response carries the attribute and the client-side
+  `boot()` no longer silently bails out.
+- Client-side defense in depth: `boot()` in `public/task-operations.js`
+  falls back to `document.body.dataset.taskId` when the section is missing
+  the attribute, and `renderPipelineHtml` / `renderErrorHtml` preserve
+  the attribute across `swapIn()` calls.
+
+12 new TDD cases in `test/task-operations-browser-integration.test.ts`
+(happy-dom browser integration + unit + server boot). New
+`scripts/verify-task-operations-browser.ts` boots a real Playwright
+Chromium against `TaskShowServer` + the real `roy-agent` CLI and asserts
+7 op-node cards are rendered for Task #2388. All 161 tests pass.
+
 ### v0.6.11 — Mermaid SVG regression fix (2026-07-24)
 
 **For end users**: `npm install` as usual — no host-side change required.
@@ -713,4 +746,91 @@ broadcast.
 
 ## License
 
-MIT
+MIT
+## Task lifecycle pipeline (v0.7.0+)
+
+In addition to the tool-call flow (the existing Mermaid diagram), every
+`/task/:id` page now includes a **Task lifecycle pipeline** section that
+shows the task's own operation history — the create / progress / milestone /
+problem / solution / decision / review / completed events that the
+`roy-agent tasks` CLI records for that task.
+
+### Where the data comes from
+
+The plugin spawns `roy-agent tasks get <id> --operations --json` (via
+discrete argv — no shell string), parses the `{ task, operations }`
+envelope, and serves a stable schema from the new endpoint:
+
+```
+GET /api/tasks/:id/operations
+→ 200 {
+    task: { id, title, status, priority, type, progress?, createdAt, updatedAt, tags, projectPath? },
+    operations: [
+      { id, sequence, milestoneType, title, description, timestamp, sessionShort }
+    ],
+    fetchedAt: ISO8601,
+    stale: boolean
+  }
+→ 404 { error: "not_found", id }      // CLI reported "Task not found"
+→ 400 { error: "bad_id", id }          // invalid task id
+→ 503 { error: "cli_failed", id }      // CLI exited with non-zero status
+→ 500 { error: "internal_error", id }  // unexpected exception
+```
+
+The CLI is invoked safely:
+
+- Arg array form: `["node", "<cliPath>", "tasks", "get", "<id>",
+  "--operations", "--json"]`. Shell metacharacters in the task id are
+  never interpreted.
+- Wall-clock timeout (`cliTimeoutMs`, default 5 s).
+- Max stdout bytes (`cliMaxBytes`, default 1 MiB).
+- Stderr is captured so the CLI's `✗ Task not found: <id>` message is
+  mapped to HTTP 404.
+
+### Caching & dedup
+
+A TTL cache (default 5 s) coalesces concurrent requests for the same
+task id and limits how often the plugin spawns the host CLI. Stale
+entries are served with `stale: true` while a background refresh runs.
+
+### Polling
+
+For active tasks, the page polls `/api/tasks/:id/operations` every 5 s.
+The client merges new operations into the existing timeline by id
+(idempotent — no duplicates) and stops polling once the task reaches a
+terminal status (`completed` / `failed` / `cancelled`). On any CLI
+failure the page shows a "Retry" button and applies exponential backoff
+up to 30 s.
+
+### Security
+
+- Task ids are validated as positive integers in the safe range.
+- All operation titles, descriptions, and process notes are HTML-escaped.
+- `processDescription` and `current_status` are stripped from public
+  responses (only safe fields reach the browser).
+- The full session id is shortened to 8 hex chars (`sessionShort`).
+
+### Configuration
+
+| Key | Default | Purpose |
+|---|---|---|
+| `royAgentCliPath` | auto-detect | Absolute path to the `roy-agent` executable. |
+| `operationsCacheTtlMs` | 5000 | TTL for parsed envelopes. |
+| `maxOperations` | 200 | Hard cap on operations per task. |
+| `maxDescriptionChars` | 2000 | Per-description char cap. |
+| `cliTimeoutMs` | 5000 | Wall-clock timeout for the CLI spawn. |
+| `cliMaxBytes` | 1048576 | Maximum stdout bytes. |
+
+### CLI path resolution
+
+The plugin auto-detects the `roy-agent` CLI from these locations
+(first match wins):
+
+1. `cfg.royAgentCliPath` (explicit override).
+2. `$ROY_AGENT_CLI` environment variable.
+3. `<cwd>/../roy-agent/packages/cli/dist/bin/roy-agent.js`
+   (sibling-repo layout — the typical dev setup).
+4. The monorepo layout
+   (`<pluginDist>/../../../../packages/cli/dist/bin/roy-agent.js`).
+5. `roy-agent` on PATH (fallback).
+

package/dist/cli-tasks-adapter.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview CLI adapter for `roy-agent tasks get <id> --operations --json`.
+ *
+ * Design goals:
+ *   - Spawn the host CLI as a discrete arg array — never via shell string.
+ *   - Enforce a wall-clock timeout and a maximum stdout size.
+ *   - Locate the leading `{` in stdout to skip INFO/log lines the real
+ *     CLI emits before its JSON envelope.
+ *   - Validate the parsed envelope against a stable schema.
+ *   - Sort operations ascending by timestamp and assign `sequence` numbers.
+ *   - Truncate over-long descriptions defensively.
+ *   - Surface typed errors so callers can map them to HTTP status codes.
+ *
+ * The adapter is intentionally narrow: it knows nothing about HTTP, the
+ * collector, or the frontend. The `runner` is injectable so tests never
+ * need a real subprocess.
+ */
+import type { TaskShowConfig } from "./types.js";
+export type CanonicalMilestoneType = "create" | "progress" | "milestone" | "problem" | "solution" | "decision" | "review" | "completed" | "unknown";
+/** Subset of the CLI's `task` payload that we surface to the UI. */
+export interface TaskMetadata {
+    id: number;
+    title: string;
+    status: string;
+    priority: string;
+    type: string;
+    progress?: number;
+    createdAt: string;
+    updatedAt: string;
+    tags: string[];
+    projectPath?: string;
+}
+/** One row in the operations pipeline. */
+export interface OperationRecord {
+    id: number;
+    /** 1-based sequence number, ascending by timestamp. */
+    sequence: number;
+    /** Canonical milestone type (or 'unknown' if the CLI emits an unknown value). */
+    milestoneType: CanonicalMilestoneType;
+    title: string;
+    description: string;
+    processDescription: string;
+    timestamp: string;
+    /** Truncated session id for display; the full id is never exposed. */
+    sessionShort: string;
+}
+export interface TaskOperationsEnvelope {
+    task: TaskMetadata;
+    operations: OperationRecord[];
+}
+export interface CachedEnvelope {
+    task: TaskMetadata;
+    operations: OperationRecord[];
+    /** When the source data was last fetched (ISO 8601). */
+    fetchedAt: string;
+    /** True if the cache entry is past TTL but still served. */
+    stale: boolean;
+}
+export interface AdapterRunnerResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export type AdapterRunner = (args: string[]) => Promise<AdapterRunnerResult>;
+export interface AdapterOptions {
+    /** Absolute path to the `roy-agent` executable. */
+    cliPath: string;
+    /** Mockable subprocess runner (defaults to `defaultRunner`). */
+    runner?: AdapterRunner;
+    /** Wall-clock timeout (default 5000 ms). */
+    timeoutMs?: number;
+    /** Maximum stdout bytes to keep (default 1 MiB). */
+    maxBytes?: number;
+    /** TaskShowConfig for maxOperations / maxDescriptionChars. */
+    cfg: TaskShowConfig;
+}
+/** Source interface used by OperationsCache and the HTTP layer. */
+export interface TaskOperationsSource {
+    getTaskOperations(taskId: number): Promise<TaskOperationsEnvelope>;
+}
+export declare class AdapterError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    readonly exitCode?: number;
+    constructor(message: string, opts?: {
+        code?: string;
+        exitCode?: number;
+        cause?: unknown;
+    });
+}
+export declare class TaskNotFoundError extends AdapterError {
+    readonly taskId: number;
+    constructor(message: string, taskId: number);
+}
+export declare class ParseError extends AdapterError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class TimeoutError extends AdapterError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class SchemaError extends AdapterError {
+    constructor(message: string);
+}
+export declare function assertValidTaskId(id: unknown): asserts id is number;
+/**
+ * Default subprocess runner. We deliberately avoid `shell: true` to keep
+ * argv as a literal array — no shell metacharacter interpretation. The
+ * `AbortController` enforces the wall-clock timeout by killing the child.
+ */
+export declare const defaultRunner: AdapterRunner;
+/** Build the argv array. Pure function — easy to unit-test. */
+export declare function buildTasksGetArgs(cliPath: string, taskId: number): string[];
+/**
+ * Locate the first top-level `{` in stdout and return everything from
+ * there to the end. Tolerant of:
+ *   - INFO / log lines printed before the JSON envelope
+ *   - mixed CRLF / LF
+ *   - `✗ Task not found: N` lines (handled separately by exit code)
+ */
+export declare function extractJsonEnvelope(stdout: string): string;
+/**
+ * Map any string to a CanonicalMilestoneType. Unknown values fall back
+ * to 'unknown' (with the original string preserved under `title` if we
+ * ever want to display it).
+ */
+export declare function canonicalMilestoneType(raw: unknown): CanonicalMilestoneType;
+/** Shorten a session id like `session_392d70e0-07bc-4a41-8669-ece72f325aad`
+ * to `s_392d70e0` (12 chars max, never leaks the full UUID). */
+export declare function shortSessionId(raw: unknown): string;
+/**
+ * Run `roy-agent tasks get <id> --operations --json` and return a parsed
+ * envelope. Errors are typed so the HTTP layer can map them to status codes.
+ *
+ * Pass `runner: defaultRunner` in production. Tests pass a `fixedRunner`.
+ */
+export declare function runTasksGetOperations(taskId: number, options: AdapterOptions): Promise<TaskOperationsEnvelope>;
+/**
+ * Convenience wrapper used by OperationsCache: a `TaskOperationsSource`
+ * whose `getTaskOperations(taskId)` returns the parsed envelope or throws.
+ */
+export declare function makeTaskOperationsSource(opts: AdapterOptions): TaskOperationsSource;
+//# sourceMappingURL=cli-tasks-adapter.d.ts.map

package/dist/cli-tasks-adapter.d.ts.map

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

package/dist/cli-tasks-adapter.js

@@ -0,0 +1,379 @@
+/**
+ * @fileoverview CLI adapter for `roy-agent tasks get <id> --operations --json`.
+ *
+ * Design goals:
+ *   - Spawn the host CLI as a discrete arg array — never via shell string.
+ *   - Enforce a wall-clock timeout and a maximum stdout size.
+ *   - Locate the leading `{` in stdout to skip INFO/log lines the real
+ *     CLI emits before its JSON envelope.
+ *   - Validate the parsed envelope against a stable schema.
+ *   - Sort operations ascending by timestamp and assign `sequence` numbers.
+ *   - Truncate over-long descriptions defensively.
+ *   - Surface typed errors so callers can map them to HTTP status codes.
+ *
+ * The adapter is intentionally narrow: it knows nothing about HTTP, the
+ * collector, or the frontend. The `runner` is injectable so tests never
+ * need a real subprocess.
+ */
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+export class AdapterError extends Error {
+    code;
+    cause;
+    exitCode;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "AdapterError";
+        this.code = opts.code ?? "adapter_error";
+        if (opts.exitCode !== undefined)
+            this.exitCode = opts.exitCode;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+export class TaskNotFoundError extends AdapterError {
+    taskId;
+    constructor(message, taskId) {
+        super(message, { code: "not_found" });
+        this.name = "TaskNotFoundError";
+        this.taskId = taskId;
+    }
+}
+export class ParseError extends AdapterError {
+    constructor(message, cause) {
+        super(message, { code: "parse_error", cause });
+        this.name = "ParseError";
+    }
+}
+export class TimeoutError extends AdapterError {
+    constructor(message, cause) {
+        super(message, { code: "timeout", cause });
+        this.name = "TimeoutError";
+    }
+}
+export class SchemaError extends AdapterError {
+    constructor(message) {
+        super(message, { code: "schema_error" });
+        this.name = "SchemaError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Task id validator
+// ---------------------------------------------------------------------------
+export function assertValidTaskId(id) {
+    if (typeof id !== "number" || !Number.isFinite(id)) {
+        throw new AdapterError(`task id must be a finite number (got ${String(id)})`, { code: "bad_id" });
+    }
+    if (!Number.isInteger(id)) {
+        throw new AdapterError(`task id must be an integer (got ${id})`, { code: "bad_id" });
+    }
+    if (id <= 0) {
+        throw new AdapterError(`task id must be positive (got ${id})`, { code: "bad_id" });
+    }
+    if (id > Number.MAX_SAFE_INTEGER) {
+        throw new AdapterError(`task id out of safe range (got ${id})`, { code: "bad_id" });
+    }
+}
+// ---------------------------------------------------------------------------
+// Default runner — spawns the CLI as discrete args with timeout & byte cap
+// ---------------------------------------------------------------------------
+/**
+ * Default subprocess runner. We deliberately avoid `shell: true` to keep
+ * argv as a literal array — no shell metacharacter interpretation. The
+ * `AbortController` enforces the wall-clock timeout by killing the child.
+ */
+export const defaultRunner = async (args) => {
+    // Lazy import so this file stays test-friendly when the runner is mocked.
+    const { spawn } = await import("node:child_process");
+    const executable = args[0];
+    const argv = args.slice(1);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const chunks = [];
+        const stderrChunks = [];
+        let totalBytes = 0;
+        const MAX_BYTES_DEFAULT = 1024 * 1024; // 1 MiB; the real CLI is well under this.
+        let truncated = false;
+        const child = spawn(executable, argv, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* ignore */
+            }
+            const err = new Error("CLI spawn timed out");
+            err.name = "AbortError";
+            reject(err);
+        }, 30_000); // default; honored by callers who pass timeoutMs via wrapper
+        child.stdout.on("data", (buf) => {
+            totalBytes += buf.length;
+            if (totalBytes > MAX_BYTES_DEFAULT) {
+                truncated = true;
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore */
+                }
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve({
+                        stdout: Buffer.concat(chunks).toString("utf8"),
+                        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                        exitCode: 0,
+                    });
+                }
+                return;
+            }
+            chunks.push(buf);
+        });
+        // The real CLI emits "✗ Task not found: <id>" to stderr. We keep
+        // it so the adapter can detect not-found and map it to 404.
+        child.stderr.on("data", (buf) => {
+            stderrChunks.push(buf);
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                stdout: Buffer.concat(chunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                exitCode: code ?? 0,
+            });
+        });
+    });
+};
+/** Build the argv array. Pure function — easy to unit-test. */
+export function buildTasksGetArgs(cliPath, taskId) {
+    // The CLI is bundled for Node — its dist has a `#!/usr/bin/env node`
+    // shebang. We invoke it through whatever runtime is available; on
+    // dev machines that is usually `bun` (TS loader), but `bun` has known
+    // TS decorator bugs that crash the CLI. Prefer `node` when available
+    // and fall back to `bun`. If neither is on PATH we still hand back
+    // a best-effort argv that the OS spawn will resolve.
+    const lower = cliPath.toLowerCase();
+    const looksLikeScript = lower.endsWith(".js") || lower.endsWith(".ts") || lower.endsWith(".mjs") || lower.endsWith(".cjs");
+    if (looksLikeScript) {
+        const runtime = pickScriptRuntime();
+        return [runtime, cliPath, "tasks", "get", String(taskId), "--operations", "--json"];
+    }
+    return [cliPath, "tasks", "get", String(taskId), "--operations", "--json"];
+}
+/**
+ * Pick the best script runtime. Cached on first call.
+ *   - `node` is preferred (matches the CLI's shebang).
+ *   - `bun` is the fallback when running under bun's test runner.
+ */
+let cachedRuntime = null;
+function pickScriptRuntime() {
+    if (cachedRuntime)
+        return cachedRuntime;
+    // Prefer an explicit env override
+    if (process.env?.TASK_SHOW_CLI_RUNTIME) {
+        cachedRuntime = process.env.TASK_SHOW_CLI_RUNTIME;
+        return cachedRuntime;
+    }
+    // Cheap heuristic: Node is preferred.
+    cachedRuntime = "node";
+    return cachedRuntime;
+}
+// ---------------------------------------------------------------------------
+// stdout → JSON envelope
+// ---------------------------------------------------------------------------
+/**
+ * Locate the first top-level `{` in stdout and return everything from
+ * there to the end. Tolerant of:
+ *   - INFO / log lines printed before the JSON envelope
+ *   - mixed CRLF / LF
+ *   - `✗ Task not found: N` lines (handled separately by exit code)
+ */
+export function extractJsonEnvelope(stdout) {
+    const start = stdout.indexOf("{");
+    if (start < 0) {
+        throw new ParseError("stdout contains no JSON object");
+    }
+    return stdout.slice(start);
+}
+/**
+ * Map any string to a CanonicalMilestoneType. Unknown values fall back
+ * to 'unknown' (with the original string preserved under `title` if we
+ * ever want to display it).
+ */
+export function canonicalMilestoneType(raw) {
+    const known = [
+        "create",
+        "progress",
+        "milestone",
+        "problem",
+        "solution",
+        "decision",
+        "review",
+        "completed",
+    ];
+    if (typeof raw === "string" && known.includes(raw)) {
+        return raw;
+    }
+    return "unknown";
+}
+/** Truncate a string defensively. */
+function clip(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, Math.max(0, max - 1)) + "…";
+}
+/** Shorten a session id like `session_392d70e0-07bc-4a41-8669-ece72f325aad`
+ * to `s_392d70e0` (12 chars max, never leaks the full UUID). */
+export function shortSessionId(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return "";
+    // strip the well-known prefix if present
+    let id = raw;
+    if (id.startsWith("session_"))
+        id = id.slice("session_".length);
+    // take the first 8 hex chars (or all if shorter)
+    const clean = id.replace(/[^a-zA-Z0-9]/g, "");
+    return "s_" + clean.slice(0, 8);
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Run `roy-agent tasks get <id> --operations --json` and return a parsed
+ * envelope. Errors are typed so the HTTP layer can map them to status codes.
+ *
+ * Pass `runner: defaultRunner` in production. Tests pass a `fixedRunner`.
+ */
+export async function runTasksGetOperations(taskId, options) {
+    assertValidTaskId(taskId);
+    const runner = options.runner ?? defaultRunner;
+    const args = buildTasksGetArgs(options.cliPath, taskId);
+    // Apply the caller's timeout by wrapping the runner.
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const maxBytes = options.maxBytes ?? 1024 * 1024;
+    let raw;
+    try {
+        raw = await withTimeout(runner(args), timeoutMs);
+    }
+    catch (err) {
+        if (err?.name === "AbortError" || /timeout|abort/i.test(String(err?.message ?? ""))) {
+            throw new TimeoutError(`CLI timeout after ${timeoutMs}ms`, err);
+        }
+        if (err instanceof AdapterError)
+            throw err;
+        throw new AdapterError(`CLI runner failed: ${err?.message ?? String(err)}`, { cause: err });
+    }
+    if (raw.stdout.length > maxBytes) {
+        throw new AdapterError(`CLI stdout exceeded maxBytes=${maxBytes} (got ${raw.stdout.length})`, { code: "oversize" });
+    }
+    // Order matters: first try to parse the envelope; only treat as "not
+    // found" when stdout OR stderr literally says so AND we cannot extract
+    // a valid JSON object. Many CLIs print migration / OTel logs that
+    // include the phrase "not found" in unrelated contexts.
+    let parsed;
+    try {
+        const jsonText = extractJsonEnvelope(raw.stdout);
+        parsed = JSON.parse(jsonText);
+    }
+    catch (err) {
+        if (/task not found/i.test(raw.stdout) || /task not found/i.test(raw.stderr ?? "")) {
+            throw new TaskNotFoundError(`Task not found: ${taskId}`, taskId);
+        }
+        if (raw.exitCode !== 0) {
+            throw new AdapterError(`CLI exited with code ${raw.exitCode} and no parseable JSON envelope`, { code: "cli_failed", exitCode: raw.exitCode });
+        }
+        if (err instanceof ParseError || err instanceof SchemaError)
+            throw err;
+        throw new ParseError("Failed to parse CLI JSON envelope", err);
+    }
+    if (raw.exitCode !== 0 && !parsed) {
+        throw new AdapterError(`CLI exited with code ${raw.exitCode}`, { code: "cli_failed", exitCode: raw.exitCode });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SchemaError("envelope root is not an object");
+    }
+    if (!parsed.task || typeof parsed.task !== "object") {
+        throw new SchemaError("envelope missing `task` object");
+    }
+    if (!Array.isArray(parsed.operations)) {
+        throw new SchemaError("envelope missing `operations` array");
+    }
+    if (parsed.task.id !== taskId) {
+        throw new SchemaError(`envelope task.id=${parsed.task.id} does not match requested ${taskId}`);
+    }
+    // Normalize into our shape.
+    const maxOps = options.cfg.maxOperations ?? 200;
+    const maxDesc = options.cfg.maxDescriptionChars ?? 2000;
+    const normalized = parsed.operations
+        .map((op) => ({
+        id: Number(op?.id ?? 0),
+        sequence: 0, // assigned after sort
+        milestoneType: canonicalMilestoneType(op?.milestoneType ?? op?.actionType),
+        title: String(op?.milestoneTitle ?? op?.actionTitle ?? ""),
+        description: clip(String(op?.milestoneDescription ?? op?.actionDescription ?? ""), maxDesc),
+        processDescription: clip(String(op?.processDescription ?? ""), maxDesc),
+        timestamp: String(op?.timestamp ?? ""),
+        sessionShort: shortSessionId(op?.sessionId),
+    }))
+        .filter((o) => Number.isFinite(o.id) && o.id > 0)
+        .sort((a, b) => a.timestamp.localeCompare(b.timestamp))
+        .slice(-maxOps)
+        .map((o, idx) => ({ ...o, sequence: idx + 1 }));
+    const task = {
+        id: Number(parsed.task.id),
+        title: String(parsed.task.title ?? ""),
+        status: String(parsed.task.status ?? "unknown"),
+        priority: String(parsed.task.priority ?? "medium"),
+        type: String(parsed.task.type ?? "normal"),
+        progress: typeof parsed.task.progress === "number" ? parsed.task.progress : undefined,
+        createdAt: String(parsed.task.createdAt ?? ""),
+        updatedAt: String(parsed.task.updatedAt ?? ""),
+        tags: Array.isArray(parsed.task.tags) ? parsed.task.tags.map((t) => String(t)) : [],
+        projectPath: typeof parsed.task.project_path === "string" ? parsed.task.project_path : undefined,
+    };
+    return { task, operations: normalized };
+}
+/** Wrap a promise with a wall-clock timeout. */
+function withTimeout(p, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const err = new Error(`timed out after ${ms}ms`);
+            err.name = "AbortError";
+            reject(err);
+        }, ms);
+    });
+    return Promise.race([p, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+/**
+ * Convenience wrapper used by OperationsCache: a `TaskOperationsSource`
+ * whose `getTaskOperations(taskId)` returns the parsed envelope or throws.
+ */
+export function makeTaskOperationsSource(opts) {
+    return {
+        async getTaskOperations(taskId) {
+            return runTasksGetOperations(taskId, opts);
+        },
+    };
+}
+//# sourceMappingURL=cli-tasks-adapter.js.map