@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/tasks/task-store.js

@@ -0,0 +1,388 @@
+import { scrubSecrets, stripUnsafeChars } from "../types.js";
+import { defaultJitter, realClock, runPollLoop, } from "./poll-loop.js";
+/**
+ * Name the pending work without letting a broken hook cost the row. The label
+ * is cosmetic, but it is read before the task is recorded, so a throw here
+ * would abort registration entirely and reproduce the invisible-progress bug
+ * this store exists to avoid. An unlabelled row is the safe fallback.
+ */
+function pendingLabelOf(type, input) {
+    try {
+        return type.pendingLabel?.(input);
+    }
+    catch {
+        return undefined;
+    }
+}
+const TASK_FAILURE_MAX_LENGTH = 500;
+function sanitizeTaskFailure(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const safe = stripUnsafeChars(scrubSecrets(raw)).trim();
+    const fallback = safe || "Task kickoff failed";
+    return fallback.length > TASK_FAILURE_MAX_LENGTH
+        ? `${fallback.slice(0, TASK_FAILURE_MAX_LENGTH)}...`
+        : fallback;
+}
+/**
+ * Per-session registry + lifecycle owner for background tasks.
+ *
+ * Owns:
+ *   - The registered `TaskType` table (`register` / `getType`).
+ *   - The in-memory `Map<taskId, RunningTask>` of live + recently-finished tasks.
+ *   - One `AbortController` per task that drives the loop.
+ *   - Status change subscribers (peer push, in-memory `waitFor`).
+ *
+ * Does NOT yet handle:
+ *   - On-disk persistence — that lives in `persistence.ts` and wraps the store.
+ *   - Peer push or `<background_tasks>` block — those subscribe to `onStatus`.
+ *
+ * A task exists from the moment it is started, not from the moment its
+ * `type.start` returns. Kickoff can take a while, and the store is what
+ * every watcher reads, so a task that is still starting is still listed and
+ * still reported as running. `start` folds the label, handle, and real
+ * initial status in once the kickoff hands them over.
+ *
+ * Cancellation:
+ *   - `cancel(taskId)` aborts the loop, calls `type.cancel?.()`, emits
+ *     `{ state: "cancelled" }`. Errors from `type.cancel` are logged and
+ *     swallowed so cancellation always succeeds locally. A cancel during
+ *     kickoff settles locally right away; the `type.cancel?.()` half waits
+ *     for the handle the kickoff is still fetching.
+ *   - `cancelAll()` cancels every currently-running task.
+ *   - `dispose()` aborts all loops without changing task state — used on
+ *     FSM teardown so a restart can rehydrate the same on-disk records.
+ */
+export class TaskStore {
+    clock;
+    jitter;
+    generateId;
+    types = new Map();
+    tasks = new Map();
+    controllers = new Map();
+    listeners = new Set();
+    // Tasks whose `type.start` has not returned yet, so they have no external
+    // handle to cancel with. `cancel` records the intent locally and `start`
+    // does the external half once the handle arrives.
+    kickingOff = new Set();
+    disposed = false;
+    constructor(options = {}) {
+        this.clock = options.clock ?? realClock;
+        this.jitter = options.jitter ?? defaultJitter;
+        this.generateId = options.generateId ?? generateUlid;
+    }
+    register(type) {
+        this.types.set(type.name, type);
+    }
+    getType(name) {
+        return this.types.get(name);
+    }
+    /**
+     * Start a new task of the given type. Returns the generated `taskId`
+     * and the type's `initialStatus` (or `{ state: "running" }` if absent).
+     *
+     * `ownerUserId` is optional metadata that gets stored on the task so
+     * the LLM-facing read tools can filter cross-user access (see
+     * `isTaskAccessibleTo`). Pass the JWT-derived userId when authentic.
+     */
+    async start(typeName, input, opts, options = {}) {
+        if (this.disposed) {
+            throw new Error("TaskStore disposed");
+        }
+        const type = this.types.get(typeName);
+        if (!type) {
+            throw new Error(`unknown task type: ${typeName}`);
+        }
+        // The task is recorded and announced before `type.start` runs. Kickoff
+        // can be slow — the dev-database types upload the working directory and
+        // wait on the lifecycle API — and a task nobody can see yet reads to the
+        // user as nothing happening at all. Everything the kickoff later tells us
+        // (label, handle, real initial status) is folded into this same task id,
+        // so watchers update a row instead of gaining a second one.
+        const taskId = this.generateId();
+        const task = {
+            taskId,
+            taskType: typeName,
+            externalHandle: undefined,
+            label: pendingLabelOf(type, input),
+            startedAt: new Date(this.clock.now()).toISOString(),
+            state: "running",
+            ownerUserId: options.ownerUserId,
+        };
+        this.tasks.set(taskId, task);
+        this.kickingOff.add(taskId);
+        const controller = new AbortController();
+        this.controllers.set(taskId, controller);
+        this.emit(taskId, { state: "running" }, task);
+        let startResult;
+        try {
+            startResult = (await type.start(input, opts, controller.signal));
+        }
+        catch (error) {
+            // The row is already on screen, so it has to be closed out here. Left
+            // alone it would sit at "running" until the conversation ended.
+            this.kickingOff.delete(taskId);
+            this.controllers.delete(taskId);
+            this.applyStatus(taskId, {
+                state: "failed",
+                error: sanitizeTaskFailure(error),
+            });
+            throw error;
+        }
+        this.kickingOff.delete(taskId);
+        task.externalHandle = startResult.externalHandle;
+        if (startResult.label !== undefined) {
+            task.label = startResult.label;
+        }
+        // Cancelled while the kickoff was in flight. The external system was
+        // still reached, so tell it to stand down now that there is a handle to
+        // do it with, and report what the task actually is rather than
+        // reviving it with the status the kickoff was about to hand back.
+        if (task.state === "cancelled") {
+            await this.cancelExternal(type, startResult.externalHandle);
+            return {
+                taskId,
+                initialStatus: { state: "cancelled" },
+                label: task.label,
+            };
+        }
+        const initialStatus = startResult.initialStatus ?? {
+            state: "running",
+        };
+        this.applyStatus(taskId, initialStatus);
+        // Already-terminal initialStatus → no poll loop needed.
+        if (initialStatus.state === "running") {
+            void this.spawnPollLoop(taskId, type, controller);
+        }
+        else {
+            this.controllers.delete(taskId);
+        }
+        return {
+            taskId,
+            initialStatus,
+            label: task.label,
+        };
+    }
+    get(taskId) {
+        return this.tasks.get(taskId);
+    }
+    list() {
+        return [...this.tasks.values()];
+    }
+    hasActiveTasks() {
+        for (const task of this.tasks.values()) {
+            if (task.state === "running")
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Abort the task's poll loop, call `type.cancel` if defined, mark the
+     * task as cancelled, and fire one cancelled status event. Safe to call
+     * on already-terminal tasks (no-op).
+     */
+    async cancel(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task || task.state !== "running")
+            return;
+        const controller = this.controllers.get(taskId);
+        controller?.abort();
+        this.controllers.delete(taskId);
+        const type = this.types.get(task.taskType);
+        // Mid-kickoff there is no handle yet. `start` picks the external cancel
+        // up as soon as one exists, so the local state can settle now.
+        if (!this.kickingOff.has(taskId)) {
+            await this.cancelExternal(type, task.externalHandle);
+        }
+        const status = { state: "cancelled" };
+        this.applyStatus(taskId, status);
+    }
+    async cancelExternal(type, externalHandle) {
+        if (!type?.cancel)
+            return;
+        try {
+            await type.cancel(externalHandle);
+        }
+        catch {
+            // Best-effort; the loop is already aborted locally regardless.
+        }
+    }
+    async cancelAll() {
+        const ids = [...this.tasks.entries()]
+            .filter(([, t]) => t.state === "running")
+            .map(([id]) => id);
+        await Promise.all(ids.map((id) => this.cancel(id)));
+    }
+    /**
+     * Resolves with the terminal status as soon as the task leaves
+     * `running` state. Rejects with a TimeoutError after `timeoutMs` if
+     * the task is still running.
+     */
+    waitFor(taskId, timeoutMs, abortSignal) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            return Promise.reject(new Error(`unknown task: ${taskId}`));
+        }
+        if (task.state !== "running") {
+            return Promise.resolve(this.snapshotStatus(task));
+        }
+        if (abortSignal?.aborted) {
+            return Promise.reject(new DOMException("Aborted", "AbortError"));
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                cleanup();
+                reject(new DOMException("Aborted", "AbortError"));
+            };
+            const onStatus = (id, status) => {
+                if (id !== taskId)
+                    return;
+                if (status.state === "running")
+                    return;
+                cleanup();
+                resolve(status);
+            };
+            const timeoutAbort = new AbortController();
+            const cleanup = () => {
+                this.listeners.delete(onStatus);
+                timeoutAbort.abort();
+                abortSignal?.removeEventListener("abort", onAbort);
+            };
+            this.listeners.add(onStatus);
+            abortSignal?.addEventListener("abort", onAbort, { once: true });
+            this.clock
+                .sleep(timeoutMs, timeoutAbort.signal)
+                .then(() => {
+                cleanup();
+                reject(new Error(`timeout waiting for task ${taskId}`));
+            })
+                .catch(() => {
+                // Aborted by cleanup() — terminal status already delivered.
+            });
+        });
+    }
+    /**
+     * Register a listener for task status changes. Returns an unsubscribe
+     * function.
+     */
+    onStatus(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Aborts every in-flight loop without changing task state. */
+    dispose() {
+        this.disposed = true;
+        for (const controller of this.controllers.values())
+            controller.abort();
+        this.controllers.clear();
+        this.listeners.clear();
+    }
+    /**
+     * Summary used by the peer push and the `<background_tasks>` block.
+     * Never includes `result`.
+     */
+    summarize(task) {
+        const startedAtMs = Date.parse(task.startedAt);
+        return {
+            taskId: task.taskId,
+            taskType: task.taskType,
+            label: task.label,
+            state: task.state,
+            message: task.message,
+            ageMs: Math.max(0, this.clock.now() - startedAtMs),
+            completedAt: task.state === "running"
+                ? undefined
+                : new Date(this.clock.now()).toISOString(),
+            error: task.error,
+            detail: task.detail,
+        };
+    }
+    async spawnPollLoop(taskId, type, controller) {
+        const task = this.tasks.get(taskId);
+        if (!task)
+            return;
+        try {
+            await runPollLoop({
+                type,
+                handle: task.externalHandle,
+                signal: controller.signal,
+                clock: this.clock,
+                jitter: this.jitter,
+                onStatus: (status) => this.applyStatus(taskId, status),
+            });
+        }
+        finally {
+            this.controllers.delete(taskId);
+        }
+    }
+    applyStatus(taskId, status) {
+        if (this.disposed)
+            return;
+        const task = this.tasks.get(taskId);
+        if (!task)
+            return;
+        if (task.state !== "running")
+            return; // already terminal, ignore late updates
+        task.state = status.state;
+        task.message = "message" in status ? status.message : task.message;
+        task.result =
+            status.state === "completed"
+                ? status.result
+                : undefined;
+        task.error =
+            status.state === "failed"
+                ? status.error
+                : undefined;
+        task.detail =
+            status.state === "failed"
+                ? status.detail
+                : undefined;
+        this.emit(taskId, status, task);
+    }
+    emit(taskId, status, task) {
+        for (const listener of this.listeners) {
+            try {
+                listener(taskId, status, task);
+            }
+            catch {
+                // Listener must not break the loop.
+            }
+        }
+    }
+    snapshotStatus(task) {
+        switch (task.state) {
+            case "running":
+                return { state: "running", message: task.message };
+            case "completed":
+                return { state: "completed", result: task.result };
+            case "failed":
+                return {
+                    state: "failed",
+                    error: task.error ?? "unknown error",
+                    ...(task.detail !== undefined ? { detail: task.detail } : {}),
+                };
+            case "cancelled":
+                return { state: "cancelled" };
+        }
+    }
+}
+/**
+ * ULID generator (Crockford base32, 26 chars). Lexically sortable; no
+ * dependency added. Not collision-free under heavy concurrent use within
+ * the same millisecond, but more than sufficient for human-scale task
+ * spawns.
+ */
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function generateUlid(now = Date.now(), random = Math.random) {
+    let ts = now;
+    const tsChars = [];
+    for (let i = 0; i < 10; i++) {
+        tsChars.unshift(CROCKFORD[ts % 32]);
+        ts = Math.floor(ts / 32);
+    }
+    let randomPart = "";
+    for (let i = 0; i < 16; i++) {
+        randomPart += CROCKFORD[Math.floor(random() * 32)];
+    }
+    return tsChars.join("") + randomPart;
+}
+//# sourceMappingURL=task-store.js.map

package/dist/ai-service/tasks/task-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-store.js","sourceRoot":"","sources":["../../../src/ai-service/tasks/task-store.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/tasks/test-utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Test-only helpers for the tasks subsystem. Not exported from index;
+ * production code must not import from here.
+ */
+/**
+ * Deterministic clock used by `task-store.test.ts` and `poll-loop.test.ts`.
+ *
+ * Tests advance time by calling `tick(ms)`. Any `sleep` waiters whose
+ * deadline has passed resolve synchronously after the tick, in deadline
+ * order, in microtasks (`Promise.resolve().then(...)`), so test code can
+ * `await` between ticks without flushing setImmediate / process.nextTick.
+ *
+ * Aborting the supplied signal rejects the waiter with the standard
+ * `DOMException` of name "AbortError", matching the runtime behavior we
+ * need from the real clock.
+ */
+interface FakeClock {
+    now: () => number;
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+    tick: (ms: number) => Promise<void>;
+}
+export declare function createFakeClock(initialNow?: number): FakeClock;
+export {};
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/ai-service/tasks/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/ai-service/tasks/test-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,UAAU,SAAS;IACjB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,wBAAgB,eAAe,CAAC,UAAU,SAAI,GAAG,SAAS,CAoDzD"}

package/dist/ai-service/tasks/test-utils.js

@@ -0,0 +1,53 @@
+/**
+ * Test-only helpers for the tasks subsystem. Not exported from index;
+ * production code must not import from here.
+ */
+export function createFakeClock(initialNow = 0) {
+    let current = initialNow;
+    const waiters = [];
+    const settle = async () => {
+        while (true) {
+            waiters.sort((a, b) => a.deadline - b.deadline);
+            const next = waiters[0];
+            if (!next || next.deadline > current)
+                return;
+            waiters.shift();
+            next.cleanup();
+            next.resolve();
+            await Promise.resolve();
+        }
+    };
+    return {
+        now: () => current,
+        sleep: (ms, signal) => new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(new DOMException("Aborted", "AbortError"));
+                return;
+            }
+            const deadline = current + ms;
+            const entry = {
+                deadline,
+                resolve,
+                reject,
+                cleanup: () => {
+                    if (onAbort)
+                        signal?.removeEventListener("abort", onAbort);
+                },
+            };
+            const onAbort = () => {
+                const idx = waiters.indexOf(entry);
+                if (idx >= 0)
+                    waiters.splice(idx, 1);
+                entry.cleanup();
+                reject(new DOMException("Aborted", "AbortError"));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            waiters.push(entry);
+        }),
+        tick: async (ms) => {
+            current += ms;
+            await settle();
+        },
+    };
+}
+//# sourceMappingURL=test-utils.js.map

package/dist/ai-service/tasks/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.js","sourceRoot":"","sources":["../../../src/ai-service/tasks/test-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,MAAM,UAAU,eAAe,CAAC,UAAU,GAAG,CAAC;IAC5C,IAAI,OAAO,GAAG,UAAU,CAAC;IACzB,MAAM,OAAO,GAKR,EAAE,CAAC;IAER,MAAM,MAAM,GAAG,KAAK,IAAI,EAAE;QACxB,OAAO,IAAI,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;YAChD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YACxB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,GAAG,OAAO;gBAAE,OAAO;YAC7C,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO;QAClB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CACpB,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACpC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;gBAClD,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,GAAG,OAAO,GAAG,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG;gBACZ,QAAQ;gBACR,OAAO;gBACP,MAAM;gBACN,OAAO,EAAE,GAAG,EAAE;oBACZ,IAAI,OAAO;wBAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC7D,CAAC;aACF,CAAC;YACF,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,GAAG,IAAI,CAAC;oBAAE,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBACrC,KAAK,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;YACpD,CAAC,CAAC;YACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC;QACJ,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;YACjB,OAAO,IAAI,EAAE,CAAC;YACd,MAAM,MAAM,EAAE,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ai-service/tasks/types.d.ts

@@ -0,0 +1,143 @@
+import type { ToolExecutionOptions } from "ai";
+import type z from "zod";
+import type { BackgroundTaskSummary } from "@superblocksteam/library-shared/types";
+import type { PermissionLevel, ToolCategory } from "../agent/tools2/types.js";
+export type { BackgroundTaskSummary };
+/**
+ * Discriminated union describing the lifecycle state of a background task.
+ *
+ * Terminal states (completed/failed/cancelled) carry the data needed to
+ * report back to Clark or the user. `running` is the only non-terminal
+ * state; the poll loop only changes the state when it transitions away
+ * from running.
+ *
+ * NOTE: `result` is intentionally only present on `completed`. It is NEVER
+ * persisted to disk in v1 (see persistence.ts); the on-disk record only
+ * keeps `lastState` and a short `lastMessage`.
+ */
+export type TaskStatus<Result = unknown> = {
+    state: "running";
+    message?: string;
+} | {
+    state: "completed";
+    result: Result;
+}
+/**
+ * `error` is the short, plain-language reason shown in the chat checklist
+ * (no internal tool/infra jargon). Optional `detail` carries the fuller
+ * classified reason for Clark via checkTask/waitForTask (and the checklist
+ * row tooltip) — see ENG-4712 / Wylie review on #20678.
+ */
+ | {
+    state: "failed";
+    error: string;
+    detail?: string;
+} | {
+    state: "cancelled";
+};
+/**
+ * Schedule for the per-task polling loop. Each tick waits
+ * min(maxMs, previous * factor) before the next poll, with jitter applied
+ * inside the loop.
+ */
+export interface PollSchedule {
+    initialMs: number;
+    maxMs: number;
+    factor: number;
+}
+export declare const DEFAULT_POLL_SCHEDULE: PollSchedule;
+/**
+ * Returned by `TaskType.start`. The caller is the framework, not the LLM;
+ * the framework wraps this in the start-tool's response shape before
+ * returning it to the model.
+ */
+export interface StartResult<Handle> {
+    /** Opaque, serializable handle the framework will pass back to `poll`. */
+    externalHandle: Handle;
+    /** Short human-readable label for the UI and the `<background_tasks>` block. */
+    label?: string;
+    /** Initial status — usually `{ state: "running" }`. */
+    initialStatus?: TaskStatus<unknown>;
+}
+/**
+ * A background-task type definition. Authors implement this and pass it to
+ * `createBackgroundTaskFactory`, which produces a `ToolFactory` for the
+ * `start*` tool and registers the type with the `TaskStore`.
+ *
+ * Generic over:
+ * - `Input`: the LLM-facing arguments to the start tool.
+ * - `Handle`: the opaque, serializable identifier the external system
+ *   gives us back from `start`. Must round-trip through JSON.
+ * - `Result`: the (possibly-sensitive) payload returned when the task
+ *   reaches `completed`. Never persisted to disk in v1.
+ */
+export interface TaskType<Input, Handle, Result> {
+    /** Tool name exposed to the LLM (e.g. `startProvisionDatabase`). */
+    name: string;
+    /** Tool description handed to the LLM. */
+    description: string;
+    /** Tool category for the registry's middleware selection. */
+    category: ToolCategory;
+    /** Permission level for the generated `start*` tool. Defaults to ALLOW. */
+    defaultPermission?: PermissionLevel;
+    /** Schema for the LLM-facing input. */
+    inputSchema: z.ZodType<Input>;
+    /** Schema for the external handle, used to validate rehydrated state. */
+    externalHandleSchema: z.ZodType<Handle>;
+    /**
+     * Name the work from the tool input alone, before `start` has talked to
+     * anything. The framework shows this while the kickoff runs, so a type
+     * whose `start` is slow still gets a row the user can see right away.
+     * Return `undefined` (or omit the hook) when the input does not say
+     * enough to be worth showing; the row then waits for `start`'s label.
+     */
+    pendingLabel?: (input: Input) => string | undefined;
+    /**
+     * Kick the external system into action. Returns an opaque handle the
+     * framework persists and feeds back into `poll`.
+     */
+    start: (input: Input, opts: ToolExecutionOptions, signal?: AbortSignal) => Promise<StartResult<Handle>>;
+    /**
+     * Query the external system once. Implementations must respect `signal`
+     * to bail out when the task is cancelled.
+     */
+    poll: (handle: Handle, signal: AbortSignal) => Promise<TaskStatus<Result>>;
+    /**
+     * Best-effort cancel hook on the external system. Optional — when
+     * absent, cancellation is local-only (we stop polling).
+     */
+    cancel?: (handle: Handle) => Promise<void>;
+    /** Override the default exponential-backoff schedule. */
+    pollSchedule?: PollSchedule;
+    /** Format a `TaskStatus` for the LLM-facing tool response. */
+    formatStatus?: (status: TaskStatus<Result>) => string;
+}
+/**
+ * In-memory state for a single live task, owned by `TaskStore`. The
+ * `result` field is in-memory only.
+ */
+export interface RunningTask<Handle = unknown, Result = unknown> {
+    taskId: string;
+    taskType: string;
+    externalHandle: Handle;
+    label?: string;
+    startedAt: string;
+    state: TaskStatus<Result>["state"];
+    message?: string;
+    result?: Result;
+    /** Short user-facing failure reason (checklist row). */
+    error?: string;
+    /** Fuller agent/oncall-facing failure detail (tool results + tooltip). */
+    detail?: string;
+    /**
+     * Owner identity captured at `start()` time so cross-user / cross-peer
+     * inspection can be denied by the LLM-facing tools. `undefined` means
+     * "no owner recorded" — the local-dev path where no JWT is available
+     * — and is treated as accessible by any caller (back-compat).
+     *
+     * Identity comes from `parseJwt(clark.context.jwt).userId` when the
+     * AiService is wired up; tests pass the value through directly.
+     */
+    ownerUserId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ai-service/tasks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ai-service/tasks/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,IAAI,CAAC;AAC/C,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAEnF,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAM9E,YAAY,EAAE,qBAAqB,EAAE,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,GAAG,OAAO,IACnC;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxC;;;;;GAKG;GACD;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM;IACjC,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM;IAC7C,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,QAAQ,EAAE,YAAY,CAAC;IACvB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,uCAAuC;IACvC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,yEAAyE;IACzE,oBAAoB,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,SAAS,CAAC;IACpD;;;OAGG;IACH,KAAK,EAAE,CACL,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,oBAAoB,EAC1B,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAClC;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,yDAAyD;IACzD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC;CACvD;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/ai-service/tasks/types.js

@@ -0,0 +1,6 @@
+export const DEFAULT_POLL_SCHEDULE = {
+    initialMs: 2_000,
+    maxMs: 5 * 60_000,
+    factor: 1.5,
+};
+//# sourceMappingURL=types.js.map

package/dist/ai-service/tasks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/ai-service/tasks/types.ts"],"names":[],"mappings":"AAgDA,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,SAAS,EAAE,KAAK;IAChB,KAAK,EAAE,CAAC,GAAG,MAAM;IACjB,MAAM,EAAE,GAAG;CACZ,CAAC"}