qlogicagent 2.13.5 → 2.13.7

package/dist/runtime/infra/background-tasks.d.ts

@@ -1,115 +0,0 @@
-/**
- * BackgroundTaskManager — the single registry for all background execution.
- *
- * Every background unit of work (forked agent, backgrounded shell command,
- * dream consolidation) registers here so that:
- *   1. The TaskStore holds its lifecycle state (task.updated notifications fire)
- *   2. The LLM can query status/output via the task tool ("output" action)
- *   3. Completion is queued as a <task_notification> for the next turn
- *   4. Cancellation actually kills the underlying process / aborts the agent
- *
- * This is the ONLY producer surface for TaskStore background tasks.
- * Do not register tasks into the store directly from feature code.
- */
-import type { LocalAgentTaskState, LocalBashTaskState, TaskState } from "../tasks/task-types.js";
-import { type TaskStore } from "./task-runtime.js";
-/** Result contract for a background agent runner. */
-export interface AgentRunOutcome {
-    ok: boolean;
-    output?: string;
-    error?: string;
-}
-/** Structural handle for a backgrounded shell process (avoids skills-layer import). */
-export interface BashTaskHandle {
-    kill(): void;
-    result: Promise<{
-        code: number;
-        stdout: string;
-        stderr: string;
-    }>;
-    taskOutput: {
-        taskId: string;
-        path: string;
-    };
-}
-export interface StartAgentTaskOptions {
-    agentName: string;
-    label: string;
-    depth: number;
-    maxTurns: number;
-    parentTaskId?: string;
-    /** The actual work. Receives the task's own abort signal and task id. */
-    run(signal: AbortSignal, taskId: string): Promise<AgentRunOutcome>;
-}
-export interface RegisterBashTaskOptions {
-    command: string;
-    cwd: string;
-    label?: string;
-    pid?: number;
-    handle: BashTaskHandle;
-}
-export interface TaskOutputSnapshot {
-    task: TaskState;
-    /** Current output: final result for terminal tasks, live tail for running bash tasks. */
-    output: string;
-    running: boolean;
-}
-/**
- * Control surface for a task whose EXECUTION lives outside this manager — e.g. a
- * team-member subprocess owned by AgentProcessManager. The manager holds the task
- * in the unified panel (list/output/cancel) and routes those three actions here;
- * lifecycle settlement is driven by the owner via settleExternalTask().
- */
-export interface ExternalTaskControl {
-    /** Kill / tear down the external executor (invoked by `task cancel`). */
-    cancel(): void;
-    /** Optional live status snapshot for `task output` while the task runs. */
-    readStatus?(): string;
-}
-export declare class BackgroundTaskManager {
-    private readonly store;
-    private readonly controllers;
-    private readonly bashHandles;
-    private readonly externalControls;
-    private readonly settledListeners;
-    constructor(store: TaskStore);
-    /** Subscribe to natural task settlement (completed/failed). Returns unregister fn. */
-    onTaskSettled(listener: (task: TaskState) => void): () => void;
-    private fireSettled;
-    /**
-     * Start a background forked agent. Registers a local_agent task,
-     * floats the runner, and settles the task when the runner finishes.
-     */
-    startAgentTask(opts: StartAgentTaskOptions): LocalAgentTaskState;
-    /**
-     * Register an already-backgrounded shell command. The handle's result
-     * promise settles the task; live output is readable from outputPath.
-     */
-    registerBashTask(opts: RegisterBashTaskOptions): LocalBashTaskState;
-    /**
-     * Register a task whose executor lives OUTSIDE this manager (team-member
-     * subprocess). It joins the unified panel immediately; `task output` calls
-     * control.readStatus(), `task cancel` calls control.cancel(). The owner MUST
-     * drive settlement via settleExternalTask() when the executor exits.
-     */
-    registerExternalTask(task: TaskState, control: ExternalTaskControl): void;
-    /**
-     * Settle an external task (owner observed exit / teardown). Idempotent: a task
-     * already terminal (e.g. cancelled by the user just before its process exited)
-     * is left untouched. Drops the control entry either way.
-     */
-    settleExternalTask(taskId: string, lifecycle: "completed" | "failed" | "cancelled", output?: string): void;
-    private settle;
-    getTask(taskId: string): TaskState | undefined;
-    listTasks(): TaskState[];
-    /**
-     * Read a task's output. For running bash tasks this reads the live
-     * output file; for everything else it returns the stored final output.
-     */
-    readOutput(taskId: string): Promise<TaskOutputSnapshot | null>;
-    /**
-     * Cancel a running task: kills the shell process / aborts the agent,
-     * then marks the task cancelled. Returns false if not found or already terminal.
-     */
-    cancelTask(taskId: string): boolean;
-}

package/dist/runtime/infra/background-tasks.js

@@ -1,249 +0,0 @@
-/**
- * BackgroundTaskManager — the single registry for all background execution.
- *
- * Every background unit of work (forked agent, backgrounded shell command,
- * dream consolidation) registers here so that:
- *   1. The TaskStore holds its lifecycle state (task.updated notifications fire)
- *   2. The LLM can query status/output via the task tool ("output" action)
- *   3. Completion is queued as a <task_notification> for the next turn
- *   4. Cancellation actually kills the underlying process / aborts the agent
- *
- * This is the ONLY producer surface for TaskStore background tasks.
- * Do not register tasks into the store directly from feature code.
- */
-import { readFile } from "node:fs/promises";
-import { generateTaskId, isTerminalLifecycle } from "./task-runtime.js";
-/** Max chars of output retained on the task state / returned to the LLM. */
-const MAX_TASK_RESULT_CHARS = 30_000;
-function tail(text, limit = MAX_TASK_RESULT_CHARS) {
-    if (text.length <= limit)
-        return text;
-    return `... [truncated ${text.length - limit} chars] ...\n${text.slice(-limit)}`;
-}
-export class BackgroundTaskManager {
-    store;
-    controllers = new Map();
-    bashHandles = new Map();
-    externalControls = new Map();
-    settledListeners = new Set();
-    constructor(store) {
-        this.store = store;
-    }
-    /** Subscribe to natural task settlement (completed/failed). Returns unregister fn. */
-    onTaskSettled(listener) {
-        this.settledListeners.add(listener);
-        return () => this.settledListeners.delete(listener);
-    }
-    fireSettled(taskId) {
-        const task = this.store.getTask(taskId);
-        if (!task)
-            return;
-        for (const listener of this.settledListeners) {
-            try {
-                listener(task);
-            }
-            catch { /* non-blocking */ }
-        }
-    }
-    /**
-     * Start a background forked agent. Registers a local_agent task,
-     * floats the runner, and settles the task when the runner finishes.
-     */
-    startAgentTask(opts) {
-        const task = {
-            taskId: generateTaskId("local_agent"),
-            type: "local_agent",
-            label: opts.label,
-            permissionRole: "worker",
-            isolation: "shared",
-            lifecycle: "running",
-            depth: opts.depth,
-            maxTurns: opts.maxTurns,
-            tokenBudget: 0,
-            startedAt: Date.now(),
-            parentTaskId: opts.parentTaskId,
-            agentName: opts.agentName,
-            systemPrompt: "",
-            allowedTools: [],
-        };
-        this.store.registerTask(task);
-        const ac = new AbortController();
-        this.controllers.set(task.taskId, ac);
-        void opts.run(ac.signal, task.taskId)
-            .then((outcome) => {
-            this.settle(task.taskId, {
-                lifecycle: outcome.ok ? "completed" : "failed",
-                output: outcome.output ? tail(outcome.output) : undefined,
-                error: outcome.error,
-            });
-        })
-            .catch((err) => {
-            this.settle(task.taskId, {
-                lifecycle: "failed",
-                error: err instanceof Error ? err.message : String(err),
-            });
-        })
-            .finally(() => {
-            this.controllers.delete(task.taskId);
-        });
-        return task;
-    }
-    /**
-     * Register an already-backgrounded shell command. The handle's result
-     * promise settles the task; live output is readable from outputPath.
-     */
-    registerBashTask(opts) {
-        const task = {
-            taskId: opts.handle.taskOutput.taskId,
-            type: "local_bash",
-            label: opts.label ?? opts.command.slice(0, 80),
-            permissionRole: "worker",
-            isolation: "shared",
-            lifecycle: "running",
-            depth: 0,
-            maxTurns: 1,
-            tokenBudget: 0,
-            startedAt: Date.now(),
-            command: opts.command,
-            cwd: opts.cwd,
-            pid: opts.pid,
-            outputPath: opts.handle.taskOutput.path,
-        };
-        this.store.registerTask(task);
-        this.bashHandles.set(task.taskId, opts.handle);
-        void opts.handle.result
-            .then((result) => {
-            const current = this.store.getTask(task.taskId);
-            if (!current || isTerminalLifecycle(current.lifecycle))
-                return; // e.g. cancelled
-            const combined = [result.stdout, result.stderr ? `[stderr]\n${result.stderr}` : ""]
-                .filter(Boolean).join("\n");
-            this.store.updateTask(task.taskId, (t) => ({
-                ...t,
-                lifecycle: result.code === 0 ? "completed" : "failed",
-                exitCode: result.code,
-                output: tail(combined),
-                error: result.code === 0 ? undefined : `exit code ${result.code}`,
-                endedAt: Date.now(),
-            }));
-            this.fireSettled(task.taskId);
-        })
-            .catch((err) => {
-            this.settle(task.taskId, {
-                lifecycle: "failed",
-                error: err instanceof Error ? err.message : String(err),
-            });
-        })
-            .finally(() => {
-            this.bashHandles.delete(task.taskId);
-        });
-        return task;
-    }
-    /**
-     * Register a task whose executor lives OUTSIDE this manager (team-member
-     * subprocess). It joins the unified panel immediately; `task output` calls
-     * control.readStatus(), `task cancel` calls control.cancel(). The owner MUST
-     * drive settlement via settleExternalTask() when the executor exits.
-     */
-    registerExternalTask(task, control) {
-        this.store.registerTask(task);
-        this.externalControls.set(task.taskId, control);
-    }
-    /**
-     * Settle an external task (owner observed exit / teardown). Idempotent: a task
-     * already terminal (e.g. cancelled by the user just before its process exited)
-     * is left untouched. Drops the control entry either way.
-     */
-    settleExternalTask(taskId, lifecycle, output) {
-        this.externalControls.delete(taskId);
-        const existing = this.store.getTask(taskId);
-        if (!existing || isTerminalLifecycle(existing.lifecycle))
-            return;
-        this.store.updateTask(taskId, (t) => ({
-            ...t,
-            lifecycle,
-            ...(output != null ? { output } : {}),
-            endedAt: Date.now(),
-        }));
-        this.fireSettled(taskId);
-    }
-    settle(taskId, patch) {
-        const existing = this.store.getTask(taskId);
-        // Already terminal (e.g. cancelled while the runner was finishing): drop
-        // the late result silently — no state flip, no settled notification.
-        if (!existing || isTerminalLifecycle(existing.lifecycle))
-            return;
-        this.store.updateTask(taskId, (t) => ({ ...t, ...patch, endedAt: Date.now() }));
-        this.fireSettled(taskId);
-    }
-    getTask(taskId) {
-        return this.store.getTask(taskId);
-    }
-    listTasks() {
-        return this.store.getAllTasks();
-    }
-    /**
-     * Read a task's output. For running bash tasks this reads the live
-     * output file; for everything else it returns the stored final output.
-     */
-    async readOutput(taskId) {
-        const task = this.store.getTask(taskId);
-        if (!task)
-            return null;
-        const running = !isTerminalLifecycle(task.lifecycle);
-        if (running && task.type === "local_bash" && task.outputPath) {
-            let live = "";
-            try {
-                live = await readFile(task.outputPath, "utf-8");
-            }
-            catch {
-                live = "";
-            }
-            return { task, output: tail(live), running };
-        }
-        // Externally-owned task (team member): synthesize a live status snapshot.
-        if (running) {
-            const external = this.externalControls.get(taskId);
-            if (external?.readStatus) {
-                return { task, output: external.readStatus(), running };
-            }
-        }
-        return { task, output: task.output ?? "", running };
-    }
-    /**
-     * Cancel a running task: kills the shell process / aborts the agent,
-     * then marks the task cancelled. Returns false if not found or already terminal.
-     */
-    cancelTask(taskId) {
-        const task = this.store.getTask(taskId);
-        if (!task || isTerminalLifecycle(task.lifecycle))
-            return false;
-        const handle = this.bashHandles.get(taskId);
-        if (handle) {
-            try {
-                handle.kill();
-            }
-            catch { /* already dead */ }
-            this.bashHandles.delete(taskId);
-        }
-        const controller = this.controllers.get(taskId);
-        if (controller) {
-            controller.abort("cancelled");
-            this.controllers.delete(taskId);
-        }
-        const external = this.externalControls.get(taskId);
-        if (external) {
-            try {
-                external.cancel();
-            }
-            catch { /* already torn down */ }
-            this.externalControls.delete(taskId);
-        }
-        this.store.updateTask(taskId, (t) => ({
-            ...t,
-            lifecycle: "cancelled",
-            endedAt: Date.now(),
-        }));
-        return true;
-    }
-}

package/dist/runtime/infra/background-tasks.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/runtime/infra/background-tasks.test.js

@@ -1,242 +0,0 @@
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterAll, describe, expect, it } from "vitest";
-import { BackgroundTaskManager } from "./background-tasks.js";
-import { TaskStore, buildTaskNotification, generateTaskId } from "./task-runtime.js";
-const tmpRoots = [];
-afterAll(() => {
-    for (const root of tmpRoots.splice(0))
-        rmSync(root, { recursive: true, force: true });
-});
-function waitFor(predicate, timeoutMs = 2_000) {
-    return new Promise((resolve, reject) => {
-        const start = Date.now();
-        const tick = () => {
-            if (predicate())
-                return resolve();
-            if (Date.now() - start > timeoutMs)
-                return reject(new Error("waitFor timeout"));
-            setTimeout(tick, 5);
-        };
-        tick();
-    });
-}
-describe("BackgroundTaskManager — agent tasks", () => {
-    it("registers a running local_agent task and settles it with output on completion", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const settled = [];
-        manager.onTaskSettled((task) => settled.push(task.taskId));
-        let release;
-        const gate = new Promise((resolve) => { release = resolve; });
-        const task = manager.startAgentTask({
-            agentName: "explore",
-            label: "scan the codebase",
-            depth: 1,
-            maxTurns: 50,
-            run: async () => {
-                await gate;
-                return { ok: true, output: "found 3 modules" };
-            },
-        });
-        // Immediately visible as running, id has the local_agent prefix
-        expect(task.taskId).toMatch(/^a[a-z0-9]{8}$/);
-        expect(store.getTask(task.taskId)?.lifecycle).toBe("running");
-        expect(settled).toHaveLength(0);
-        release();
-        await waitFor(() => store.getTask(task.taskId)?.lifecycle === "completed");
-        const final = store.getTask(task.taskId);
-        expect(final.output).toBe("found 3 modules");
-        expect(settled).toEqual([task.taskId]);
-        // The notification built from the settled task carries the result
-        const notification = buildTaskNotification(final, final.output ?? "");
-        expect(notification).toContain(task.taskId);
-        expect(notification).toContain("completed");
-        expect(notification).toContain("found 3 modules");
-    });
-    it("settles as failed when the runner rejects", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const task = manager.startAgentTask({
-            agentName: "code",
-            label: "broken work",
-            depth: 1,
-            maxTurns: 10,
-            run: async () => { throw new Error("transport exploded"); },
-        });
-        await waitFor(() => store.getTask(task.taskId)?.lifecycle === "failed");
-        expect(store.getTask(task.taskId)?.error).toBe("transport exploded");
-    });
-    it("cancelTask aborts the runner's signal and marks the task cancelled", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const settled = [];
-        manager.onTaskSettled((task) => settled.push(task.taskId));
-        let observedSignal;
-        const task = manager.startAgentTask({
-            agentName: "research",
-            label: "long research",
-            depth: 1,
-            maxTurns: 30,
-            run: (signal) => new Promise((resolve) => {
-                observedSignal = signal;
-                signal.addEventListener("abort", () => resolve({ ok: false, error: "aborted" }), { once: true });
-            }),
-        });
-        expect(manager.cancelTask(task.taskId)).toBe(true);
-        expect(observedSignal?.aborted).toBe(true);
-        expect(store.getTask(task.taskId)?.lifecycle).toBe("cancelled");
-        // Cancellation is terminal-by-cancel: the late runner result must not flip it
-        await new Promise((r) => setTimeout(r, 20));
-        expect(store.getTask(task.taskId)?.lifecycle).toBe("cancelled");
-        expect(settled).toHaveLength(0);
-        // Already-terminal cancel is refused
-        expect(manager.cancelTask(task.taskId)).toBe(false);
-    });
-});
-describe("BackgroundTaskManager — bash tasks", () => {
-    function fakeHandle(opts) {
-        return {
-            kill: opts.onKill ?? (() => { }),
-            result: opts.result,
-            taskOutput: { taskId: opts.taskId, path: opts.outputPath },
-        };
-    }
-    it("registers under the handle's task id and captures output on exit", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        let resolveResult;
-        const result = new Promise((r) => { resolveResult = r; });
-        const task = manager.registerBashTask({
-            command: "npm run build",
-            cwd: "C:/work",
-            handle: fakeHandle({ taskId: "b12345678", outputPath: "C:/tmp/none.output", result }),
-        });
-        expect(task.taskId).toBe("b12345678");
-        expect(store.getTask("b12345678")?.lifecycle).toBe("running");
-        resolveResult({ code: 0, stdout: "build ok", stderr: "" });
-        await waitFor(() => store.getTask("b12345678")?.lifecycle === "completed");
-        expect(store.getTask("b12345678")?.output).toContain("build ok");
-    });
-    it("marks non-zero exits failed and reads live output for running tasks", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const dir = mkdtempSync(join(tmpdir(), "qla-bg-test-"));
-        tmpRoots.push(dir);
-        const outputPath = join(dir, "live.output");
-        writeFileSync(outputPath, "server listening on :3000\n");
-        const pending = new Promise(() => { });
-        manager.registerBashTask({
-            command: "npm run dev",
-            cwd: dir,
-            handle: fakeHandle({ taskId: "b87654321", outputPath, result: pending }),
-        });
-        const snapshot = await manager.readOutput("b87654321");
-        expect(snapshot?.running).toBe(true);
-        expect(snapshot?.output).toContain("server listening on :3000");
-        let killed = false;
-        const store2 = new TaskStore();
-        const manager2 = new BackgroundTaskManager(store2);
-        manager2.registerBashTask({
-            command: "npm test",
-            cwd: dir,
-            handle: fakeHandle({
-                taskId: "baaaa1111",
-                outputPath,
-                result: new Promise(() => { }),
-                onKill: () => { killed = true; },
-            }),
-        });
-        expect(manager2.cancelTask("baaaa1111")).toBe(true);
-        expect(killed).toBe(true);
-        expect(store2.getTask("baaaa1111")?.lifecycle).toBe("cancelled");
-    });
-    it("readOutput returns null for unknown tasks", async () => {
-        const manager = new BackgroundTaskManager(new TaskStore());
-        expect(await manager.readOutput("b00000000")).toBeNull();
-    });
-});
-describe("BackgroundTaskManager — external tasks (team members)", () => {
-    function memberTask(label = "alice (researcher)") {
-        return {
-            taskId: generateTaskId("team_member"),
-            type: "team_member",
-            label,
-            permissionRole: "worker",
-            isolation: "worktree",
-            lifecycle: "running",
-            depth: 1,
-            maxTurns: 0,
-            tokenBudget: 0,
-            startedAt: Date.now(),
-            teamName: "research-pod",
-            agentName: "alice",
-            memberId: "team-research-pod-alice",
-        };
-    }
-    it("registers a team_member into the unified panel and reads live status", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const task = memberTask();
-        let cancelled = false;
-        manager.registerExternalTask(task, {
-            cancel: () => { cancelled = true; },
-            readStatus: () => "state=running · alive · lastTool=search",
-        });
-        // `t` prefix + visible in the panel list as running
-        expect(task.taskId).toMatch(/^t[a-z0-9]{8}$/);
-        expect(manager.listTasks().map((t) => t.taskId)).toContain(task.taskId);
-        // `task output` routes to readStatus() while running
-        const snapshot = await manager.readOutput(task.taskId);
-        expect(snapshot?.running).toBe(true);
-        expect(snapshot?.output).toBe("state=running · alive · lastTool=search");
-        expect(cancelled).toBe(false);
-    });
-    it("cancelTask invokes the external control and marks the task cancelled", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const task = memberTask();
-        let cancelled = false;
-        manager.registerExternalTask(task, { cancel: () => { cancelled = true; } });
-        expect(manager.cancelTask(task.taskId)).toBe(true);
-        expect(cancelled).toBe(true);
-        expect(store.getTask(task.taskId)?.lifecycle).toBe("cancelled");
-        // Already terminal → refused, and control is not invoked again
-        cancelled = false;
-        expect(manager.cancelTask(task.taskId)).toBe(false);
-        expect(cancelled).toBe(false);
-    });
-    it("settleExternalTask is idempotent vs. a prior cancel (late exit dropped)", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const settled = [];
-        manager.onTaskSettled((t) => settled.push(t.taskId));
-        const task = memberTask();
-        manager.registerExternalTask(task, { cancel: () => { } });
-        // User cancels first…
-        manager.cancelTask(task.taskId);
-        expect(store.getTask(task.taskId)?.lifecycle).toBe("cancelled");
-        // …then the killed process's onExit settles late — must NOT flip state or notify
-        manager.settleExternalTask(task.taskId, "failed", "exited (code=1)");
-        expect(store.getTask(task.taskId)?.lifecycle).toBe("cancelled");
-        expect(settled).toHaveLength(0);
-    });
-    it("settleExternalTask completes a still-running member and fires settled", async () => {
-        const store = new TaskStore();
-        const manager = new BackgroundTaskManager(store);
-        const settled = [];
-        manager.onTaskSettled((t) => settled.push(t.taskId));
-        const task = memberTask();
-        manager.registerExternalTask(task, { cancel: () => { }, readStatus: () => "live" });
-        manager.settleExternalTask(task.taskId, "completed", "exited (code=0)");
-        const final = store.getTask(task.taskId);
-        expect(final.lifecycle).toBe("completed");
-        expect(final.output).toBe("exited (code=0)");
-        expect(settled).toEqual([task.taskId]);
-        // After settle, readOutput falls back to stored output (control dropped)
-        const snapshot = await manager.readOutput(task.taskId);
-        expect(snapshot?.running).toBe(false);
-        expect(snapshot?.output).toBe("exited (code=0)");
-    });
-});

package/dist/runtime/infra/checkpoint-backend.d.ts

@@ -1,8 +0,0 @@
-/**
- * Local Checkpoint Backend — git-based shadow repo implementation.
- *
- * Creates and manages checkpoint snapshots in `<project>/.qlogicagent/checkpoints/<sessionId>/`
- * using a shadow git repository independent of the user's project .git.
- */
-import type { CheckpointBackend } from "../ports/checkpoint-contracts.js";
-export declare function createLocalCheckpointBackend(projectRoot: string, sessionId: string): CheckpointBackend;