@luckydraw/cumulus 1.0.39 → 1.0.41

package/dist/gateway/worker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Task 179 — the invisible background worker.
+ *
+ * Karl asked whether every thread should have "some kind of system co-thread for
+ * doing this kind of work, but that it wouldn't necessarily be visible in the
+ * threads UI", and answered his own poll with "yes — build it as a general
+ * facility, Refresh is just the first user."
+ *
+ * A co-thread is the wrong engine for it, on four grounded counts: its writes
+ * land in its own git worktree on its own branch (task 143 P4), it is drawn in
+ * the sidebar under its master, it shares the master's stored content in BOTH
+ * directions — so a worker that reads a whole file pours it into the master's
+ * memory — and only a thread already mid-turn can create one, which a button
+ * click is not.
+ *
+ * So this is not a chat thread at all. It is a gateway-owned one-shot model call
+ * with no conversation, no history and no sidebar row — `runOneShotModel` plus
+ * the two things that make it a *facility* rather than a bare call:
+ *
+ *   1. **One job per `{thread, kind}` at a time.** A second request while one is
+ *      in flight is REFUSED, not queued. Two Refreshes racing on one `Tasks.md`
+ *      is the exact failure the whole task exists to prevent, and a queue would
+ *      merely delay it.
+ *   2. **A status push** (`running | done | failed`) to whoever is watching, so a
+ *      button can spin without the UI inventing a second notion of "busy".
+ *
+ * It deliberately never touches `threadBusy`. That flag drives the sidebar dots
+ * (task 146), the stall check (task 164) and the deferred-message drain (task
+ * 144); a worker that set it would make the sidebar claim a turn was running,
+ * suppress a real stall check, and drain a user's queued message into nothing.
+ */
+import { type OneShotModelContext } from './one-shot-model.js';
+/**
+ * What a worker run is for. A closed union, not a free string: the key is half of
+ * the in-flight identity, so a typo would silently buy a second concurrent slot
+ * on the same thread — the one thing this module exists to deny.
+ */
+export type WorkerKind = 'tasks-refresh';
+export type WorkerState = 'running' | 'done' | 'failed';
+export interface WorkerStatus {
+    threadName: string;
+    kind: WorkerKind;
+    state: WorkerState;
+    /** Present on `failed`, and on `done` when there is something worth saying. */
+    detail?: string;
+}
+/** Thrown by {@link runWorker} when this `{thread, kind}` is already working. */
+export declare class WorkerBusyError extends Error {
+    constructor(kind: WorkerKind);
+}
+/** Thrown when the model produced no answer at all (spawn failure, timeout, empty). */
+export declare class WorkerNoAnswerError extends Error {
+    constructor();
+}
+export declare function isWorkerRunning(threadName: string, kind: WorkerKind): boolean;
+/**
+ * Where worker progress goes. Registered by the webchat adapter at startup for
+ * the same reason `setThreadActivityListener` and `setUserQueueDelivery` are:
+ * only the adapter can reach the sockets, and this module must not know they
+ * exist.
+ */
+type WorkerStatusListener = (status: WorkerStatus) => void;
+export declare function setWorkerStatusListener(fn: WorkerStatusListener | undefined): void;
+export interface RunWorkerOptions {
+    /** Configured worker model id (`workerModel`), resolved against both catalogs. */
+    model?: string;
+    context?: OneShotModelContext;
+    timeoutMs?: number;
+    maxTokens?: number;
+}
+/**
+ * Run one prompt as this thread's `kind` worker and return the model's raw text.
+ *
+ * Throws {@link WorkerBusyError} if that slot is taken and
+ * {@link WorkerNoAnswerError} if the model produced nothing — both before any
+ * caller-visible side effect, so a refused run leaves no trace.
+ *
+ * The slot is released in a `finally`, so a caller that throws while INTERPRETING
+ * the answer (which is where task 179's guard rails live) still frees the button.
+ */
+export declare function runWorker(threadName: string, kind: WorkerKind, prompt: string, opts?: RunWorkerOptions): Promise<string>;
+/** Announce the end of a worker run. Separate from {@link runWorker} because the
+ * caller — not this module — knows whether interpreting the answer succeeded. */
+export declare function reportWorkerResult(threadName: string, kind: WorkerKind, state: 'done' | 'failed', detail?: string): void;
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/gateway/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/gateway/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,CAAC;AAEzC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,UAAU;CAI7B;AAED,uFAAuF;AACvF,qBAAa,mBAAoB,SAAQ,KAAK;;CAK7C;AAQD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAE7E;AAED;;;;;GAKG;AACH,KAAK,oBAAoB,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;AAG3D,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAElF;AAmBD,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAYD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;iFACiF;AACjF,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,GAAG,QAAQ,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAEN"}

package/dist/gateway/worker.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",