@luckydraw/cumulus 0.31.66 → 1.0.0

package/docs/agentic-harness-primer.md

@@ -0,0 +1,283 @@
+# Cumulus Agentic Harness — A Primer (for OSS models like Kimi)
+
+> A plain-language explanation of how Cumulus turns a _plain_ language model into an
+> _agent_ that can read files, run tools, ask questions, and work through multi-step
+> tasks — without relying on the Claude CLI. No code; concepts only.
+
+---
+
+## 1. Why this exists
+
+Cumulus originally drove every turn by spawning Anthropic's `claude` command-line
+tool. That CLI hides a lot of machinery: it decides when to call tools, when to stop,
+how to stream output, how to recover from truncation. It only works with Claude.
+
+The **agentic harness** is Cumulus owning that machinery itself. It is a single loop
+that can drive _any_ model — Claude through its API, or an open-weight model like
+**Kimi**, **GLM**, or **DeepSeek** served over HuggingFace — through the same
+tool-using, multi-step behavior. The model supplies intelligence; the harness supplies
+the structure that makes that intelligence _agentic_.
+
+The one-sentence version:
+
+> **The harness repeatedly asks the model "what next?", does whatever the model asks
+> for, feeds the result back, and repeats — until the model says it's finished.**
+
+---
+
+## 2. The core loop
+
+Everything centers on one cycle. Think of it as a conversation between the **harness**
+(the orchestrator) and the **model** (the brain):
+
+1. **Ask the model.** The harness sends the system prompt, the conversation so far, and
+   the list of available tools. It streams the model's reply back token by token, so the
+   user sees text appear live.
+2. **Look at _why_ the model stopped.** Every model reply ends with a _stop reason_. Two
+   matter most:
+   - _"I want to use a tool."_ → the harness must run the tool(s) and continue.
+   - _"I'm done"_ (or any other reason) → the harness exits the loop and the turn ends.
+3. **Run the requested tools.** If the model asked to use one or more tools, the harness
+   executes them, capturing each result (or error).
+4. **Feed results back.** The tool results are added to the conversation as the next
+   message, exactly as if a user had pasted them in.
+5. **Repeat from step 1.** The model now sees the results and decides the next move —
+   another tool, more tools, or a final answer.
+
+This repeats until the model stops asking for tools. A single user message can therefore
+trigger many internal round-trips (read a file → search it → edit it → confirm), all
+invisible to the user except for the streamed narration.
+
+```
+user message
+   │
+   ▼
+┌──────────────────────────────────────────────┐
+│  ask model  →  stream reply  →  stop reason?  │◄────┐
+└──────────────────────────────────────────────┘     │
+   │ "use tools"            │ "done"                  │
+   ▼                        ▼                         │
+ run tools             finish turn                    │
+   │                                                  │
+   └──── feed results back as a new message ──────────┘
+```
+
+### A worked example
+
+User asks: _"What PDF library does `read_file` use?"_
+
+- **Round 1** — model: "I should read the tool handler." → asks for `read_file`.
+  Harness runs it, returns the file summary + chunk list.
+- **Round 2** — model: "The relevant part is chunk 3." → asks for `read_content_chunk`.
+  Harness returns that chunk.
+- **Round 3** — model now has what it needs → writes the final answer, stop reason "done".
+  Loop exits.
+
+Three round-trips, one user-visible answer.
+
+---
+
+## 3. The provider abstraction
+
+The loop never talks to a specific model vendor directly. It talks to a **provider** — a
+thin adapter that knows how to (a) send a request and (b) stream back events. Swapping
+the model is just swapping the provider:
+
+| Provider             | Used for                                    | Notes                            |
+| -------------------- | ------------------------------------------- | -------------------------------- |
+| **Claude (default)** | `model: "claude"` threads                   | The historical path.             |
+| **HuggingFace**      | Open-weight models (Kimi, GLM, DeepSeek, …) | OpenAI-compatible streaming API. |
+
+Because the loop only depends on the abstract provider contract, **everything in this
+primer applies identically to Kimi and to Claude.** The harness doesn't special-case the
+model — it special-cases _behaviors_ (truncation, tool support), which is what the rest
+of this document describes.
+
+---
+
+## 4. Tools: eager vs. deferred (the ToolSearch trick)
+
+Models pay a token cost for every tool definition you show them. Cumulus exposes _many_
+tools (file reading, content search, inter-agent messaging, email, scheduling, media
+upload, …). Sending every full schema on every turn would waste thousands of tokens each
+round-trip and crowd the context.
+
+The harness solves this with a **two-tier tool system**:
+
+- **Eager tools (~10).** The handful used constantly. Their full definitions are sent on
+  every turn so the model can call them instantly.
+- **Deferred tools (everything else).** Only their _name and one-line description_ are
+  listed — not their full schema. They are real, callable tools; they just aren't
+  "loaded" yet.
+
+When the model wants a deferred tool, it first calls a special tool named **ToolSearch**,
+which returns the full schema for the tool(s) it named. Now the model can call the tool
+for real.
+
+```
+deferred list (cheap):   "- send_email: send an email via Resend"
+        │
+        ▼  model calls ToolSearch("select:send_email")
+full schema returned (expensive, but only when needed)
+        │
+        ▼  model now calls send_email with correct arguments
+```
+
+Two ways to query ToolSearch:
+
+- **Exact lookup** — `select:tool_a,tool_b` returns those specific schemas.
+- **Keyword search** — plain words fuzzy-match against tool names and descriptions.
+
+**Crucial detail for OSS models:** the deferred schemas are _re-deferred every turn_ —
+they are never permanently accumulated into the context. This keeps the per-turn token
+count **flat** no matter how many tools exist or how long the task runs. For a model with
+a smaller or pricier context window, this is what keeps long agentic sessions affordable.
+
+> Practical note: a tool a model "doesn't see" may simply be deferred, not missing.
+> The correct move is always to call ToolSearch first, never to assume a capability is
+> unavailable.
+
+---
+
+## 5. Running tools: concurrent and bounded
+
+When the model requests several tools in one turn, the harness runs them **all at once**
+rather than one after another, then collects every result before replying. Independent
+reads and searches finish in parallel instead of stacking up.
+
+Each tool result is also **size-bounded**: anything enormous (over ~100 KB) is truncated
+before being handed back to the model, so one giant output can't blow up the context.
+Errors are captured too — a failing tool returns an error message flagged as an error,
+which the model can read and react to, rather than crashing the turn.
+
+---
+
+## 6. Surviving truncation (escalation & stitching)
+
+Open-weight models, like all models, have an output-length ceiling per reply. When a
+reply hits that ceiling it gets cut off mid-thought — the stop reason is _"ran out of
+room."_ The harness handles this automatically, and the user ideally never notices. There
+are two cases:
+
+**Case A — cut off mid-sentence (plain text).**
+The harness keeps the partial text, then sends a follow-up instruction: _"you were cut
+off; continue exactly where you left off, here are your last ~200 characters, don't
+repeat anything."_ Because the original text stream is still open, the continuation flows
+in seamlessly. This is called **continuation stitching**.
+
+**Case B — cut off mid-tool-call.**
+If the cutoff landed inside a tool request, the tool arguments are now incomplete and
+unusable. The harness **discards** that broken attempt entirely and **retries the whole
+turn** with a larger output budget.
+
+In both cases the budget grows along a fixed **escalation schedule** — roughly _16k →
+32k → 65k tokens_ — giving the model progressively more room. Safety caps stop this from
+running forever:
+
+| Guardrail                           | Purpose                                              |
+| ----------------------------------- | ---------------------------------------------------- |
+| Max continuations (~3)              | Don't retry/continue endlessly.                      |
+| Max cumulative output (~65k tokens) | Cap total tokens spent stitching one reply.          |
+| Per-model output ceiling            | Never request more than the model actually supports. |
+
+The escalation never exceeds what the specific model can produce — Kimi's ceiling is
+respected just as Claude's is.
+
+---
+
+## 7. Pausing to ask the user a question
+
+Sometimes the model genuinely needs a human decision mid-task (which approach? confirm
+this destructive step?). For this there is a special tool, **AskUserQuestion**.
+
+When the model calls it, the loop does something unusual: it **pauses and returns
+control to the caller**, packaging up everything needed to resume later — the
+conversation so far, which question is outstanding, and any _other_ tool results from the
+same turn (those still run normally; only the question blocks progress).
+
+The application shows the user the question (single choice, multi-select, or a small
+carousel of questions, optionally with free-text). When the user answers, the harness is
+called again with that answer slotted in as the tool's result, and the loop **resumes
+exactly where it left off** — no work redone, no context lost.
+
+So the lifecycle has three states, not two:
+
+```
+running ──► done
+   │
+   └──► needs_input ──(user answers)──► running ──► done
+```
+
+---
+
+## 8. Working step-by-step: "todo mode"
+
+Cumulus encourages the model to track multi-step work in `<todo>` checklists. Left
+unchecked, some models — especially eager open-weight ones — try to do _everything_ in
+one giant reply, batching many tool calls and huge output into a single turn. That is
+hard to follow and easy to truncate.
+
+When the harness detects todo-tracking is active, it **caps the output budget per turn**
+(to a few thousand tokens). This nudges the model to work in smaller increments: do a
+step, report progress, update the checklist, take the next step. The effect is steadier,
+more legible execution and fewer runaway responses.
+
+---
+
+## 9. What this means for an OSS model like Kimi
+
+If you are running Kimi (or GLM, DeepSeek, etc.) inside this harness, here is the mental
+model to operate by:
+
+- **You are in a loop.** Your reply isn't the end — if you request a tool, you'll be
+  asked again with the result. Don't try to guess tool outputs; ask for the tool and wait.
+- **Stop cleanly when finished.** End without requesting a tool and the loop ends. If you
+  keep requesting tools, the loop keeps going (up to a turn limit, ~30).
+- **Use ToolSearch before exotic tools.** Only the ~10 core tools are pre-loaded. For
+  anything else, call ToolSearch by exact name or keyword first to get its schema, then
+  call it. A tool not shown is _deferred_, not absent.
+- **Emit complete tool calls.** A tool request cut off halfway is thrown away and the
+  turn is retried — wasted effort. Prefer smaller, complete requests over one massive
+  batch.
+- **Truncation is recoverable, but avoid it.** If you're cut off you'll be asked to
+  continue, but working in smaller steps (see todo mode) avoids the round-trips entirely.
+- **Ask when genuinely unsure.** AskUserQuestion is a real escape hatch for decisions you
+  shouldn't make alone. It pauses the whole task safely.
+- **Tool calling is the main reliability variable.** The single biggest difference
+  between a strong agentic run and a weak one on open models is disciplined, well-formed
+  tool use: correct tool names, valid arguments, one clear intent per call.
+
+---
+
+## 10. The whole thing in one picture
+
+```
+            ┌─────────────────────────────────────────────┐
+            │                 THE HARNESS                  │
+            │                                              │
+ user msg ─►│  build prompt + eager tools + deferred list  │
+            │                     │                        │
+            │                     ▼                        │
+            │            ask model via PROVIDER            │ ◄── Claude OR Kimi/GLM/…
+            │              (stream tokens out)             │
+            │                     │                        │
+            │              why did it stop?                │
+            │        ┌────────────┼─────────────┐          │
+            │     tool_use      max_tokens     done        │
+            │        │             │             │         │
+            │   run tools      escalate /     finish turn  │
+            │  (concurrent)     stitch /          │        │
+            │        │           retry           exit      │
+            │        ▼             │                       │
+            │  feed results back ──┘                       │
+            │        │                                     │
+            │        └──────────► loop again               │
+            │                                              │
+            │   (AskUserQuestion → pause → resume later)   │
+            └─────────────────────────────────────────────┘
+```
+
+**In short:** the model is the brain; the harness is the nervous system. The harness
+makes any capable model — Claude or open-weight — behave as a reliable, tool-using,
+multi-step agent, while quietly handling the unglamorous realities of token budgets,
+truncation, concurrency, and human-in-the-loop pauses.

package/docs/conditional-continuation.md

@@ -0,0 +1,167 @@
+# Conditional Thread Continuation — the Watcher-with-Deadline Pattern
+
+**Status:** Adopted convention (Karl, 2026-07-26). No gateway code — this pattern composes
+two primitives that already exist. A more robust gateway-native mechanism is sketched at
+the end for when this outgrows convention.
+
+## The problem
+
+A thread kicks off something long-running with an uncertain finish time — a compile, a
+test suite, a deploy, a download. The thread should continue **the moment the outcome is
+known** (success _or_ failure), not after an arbitrary sleep, and not by burning a
+scheduled AI turn every N minutes to poll ("did it finish yet?" cron turns dilute thread
+history — the exact failure class tasks 088–092 fixed).
+
+## The two primitives
+
+### 1. `POST /api/agents/inject` — immediate continuation
+
+Any process with a valid gateway API key can inject a message into a thread. The thread
+starts a new turn immediately; if it's mid-stream, the message queues and delivers at
+busy→idle (the task 100 unified queue). Exact shape (verified against
+`server.ts handleAgentInject`):
+
+```bash
+curl -s -X POST http://localhost:8090/api/agents/inject \
+  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
+  -d '{"targets": "THREAD_NAME", "sender": "build-watcher", "message": "..."}'
+```
+
+- `targets` (string or array) and `sender` and `message` are required. There is no
+  `target`/`from` — those names will 400.
+- Auth: `X-API-Key: <key>` or `Authorization: Bearer <key>`.
+- On thundercat, a key is readable from the gateway config:
+  `KEY=$(jq -r '.apiKeys[0]' "${CUMULUS_DIR:-$HOME/.cumulus}/gateway.config.json")`
+  Read it through `$CUMULUS_DIR`, never as a literal `~/.cumulus` — a hard-coded path
+  points a sandboxed run (tests, a second gateway) straight at the production gateway
+  with the production admin key (task 111).
+
+### 2. `schedule_trigger` MCP tool — the time-based floor
+
+Available in every thread (gateway-agents MCP). `{id, trigger: "once", at: "<ISO datetime>",
+message}` fires one injection at a fixed time then auto-removes; `trigger: "cron"` +
+`cron` recurs (1-minute resolution). Persisted in thread config — **survives gateway
+restarts**, which the watcher does not. Companions: `list_schedules`, `cancel_schedule`.
+
+## The pattern
+
+**Watcher for immediacy, one-shot schedule for the guarantee.** The condition-watcher
+doesn't need to live in the gateway: the thread's Claude subprocess runs on the same
+machine and can leave a detached process behind.
+
+### Step 1 — detach the job with a watcher wrapper
+
+For a _process-exit_ condition (the common case — build/test/deploy), the wrapper simply
+runs the job and fires when it exits, success or error:
+
+```bash
+KEY=$(jq -r '.apiKeys[0]' "${CUMULUS_DIR:-$HOME/.cumulus}/gateway.config.json")
+nohup sh -c '
+  npm run build > /tmp/build.log 2>&1
+  rc=$?
+  curl -s -X POST http://localhost:8090/api/agents/inject \
+    -H "X-API-Key: '"$KEY"'" -H "Content-Type: application/json" \
+    -d "{\"targets\":\"cumulus\",\"sender\":\"build-watcher\",
+         \"message\":\"[watcher] Build finished, exit $rc. Log: /tmp/build.log. First: cancel_schedule(\\\"build-deadline\\\").\"}"
+' >/dev/null 2>&1 &
+```
+
+For a condition that isn't a process exit (file appears, port answers, log line shows up),
+put an `until` loop before the curl:
+
+```bash
+until <check-command>; do sleep 5; done   # e.g. curl -sf http://localhost:3000/health
+```
+
+Guidelines:
+
+- **`>/dev/null 2>&1 &`** — redirecting _both_ streams is what makes the watcher survive
+  the Claude turn ending, and it is the only part that does. The turn's subprocess exits
+  at turn end; anything still holding its inherited stdout/stderr pipes is killed by
+  SIGPIPE (exit 141) on the next write. `nohup` alone does not save it (it ignores SIGHUP,
+  the wrong signal, and only auto-redirects when stdout is a terminal — here it is a pipe),
+  and neither does `setsid` (nothing is signalling the process group). Prefer a real log
+  file over `/dev/null` when the woken turn will need to diagnose. Surviving the turn is
+  all this buys — the watcher is still unsupervised and does NOT survive a machine reboot;
+  that's what step 2 is for.
+- **Always report failure too.** The wrapper fires on _outcome_, not on _success_ —
+  include the exit code and a log path so the woken turn can diagnose without re-running.
+- **Tell the woken turn to cancel the deadline** (put it in the message, as above) so the
+  fallback never double-fires.
+- Name the `sender` after the condition (`build-watcher`, `deploy-watcher`) — it prefixes
+  the injected message and reads clearly in history.
+- **Do not reply to the watcher.** Injected messages carry a "Reply using
+  `send_to_agent(...)`" footer intended for agent-to-agent traffic. A watcher is a script,
+  not an agent, so replying to it mints an empty thread named after the sender and burns a
+  turn in it. Measured while verifying task 109: a woken turn replied to `job-watcher` and
+  a `job-watcher` thread appeared on disk. Act on the report instead.
+
+### Step 2 — set the deadline fallback
+
+In the same turn that spawns the watcher, set a one-shot schedule as the floor:
+
+```
+schedule_trigger({
+  id: "build-deadline",
+  trigger: "once",
+  at: "<now + generous timeout, ISO 8601>",
+  message: "[deadline] The build watcher never reported back. Check /tmp/build.log and whether the process is still running."
+})
+```
+
+Why this matters: the watcher is an unsupervised background process. If the machine
+reboots, the gateway is restarted mid-job, or the script dies, the thread would otherwise
+wait forever. The schedule persists in thread config, so the thread is _guaranteed_ to
+wake — worst case at the deadline, best case the instant the condition fires.
+
+### Step 3 — on wake, cancel the other leg
+
+- Watcher fired → first action: `cancel_schedule("build-deadline")`.
+- Deadline fired → check the log/process manually; kill any orphaned watcher
+  (`pkill -f build-watcher-marker` if you tagged the command line).
+
+### Anti-pattern: cron polling turns
+
+Do **not** use `schedule_trigger` with `trigger: "cron"` to poll a condition every N
+minutes. Each poll burns a full AI turn and appends "checked, nothing yet" noise to
+thread history, degrading retrieval quality for every future turn. Cron is for genuinely
+periodic work (weekly reports, drip follow-ups), not condition-waiting.
+
+## Known limitations of this pattern
+
+These are accepted trade-offs of the convention, and the reason a robust version may be
+worth building later:
+
+1. **No supervision** — the watcher is a bare background process; nothing restarts it.
+   The deadline fallback bounds the damage but adds latency in the failure case.
+2. **No visibility** — there is no `list_watches`; a pending watcher is invisible to the
+   thread, the user, and the dashboard. You can't enumerate or cancel what you can't see.
+3. **Key in the script** — the watcher needs a gateway API key in its environment/command
+   line. On thundercat (single-user box) this is acceptable; it would not be under
+   namespace-scoped multi-tenant use (task 097 P7).
+4. **Reboot amnesia** — schedules survive restarts, watchers don't. After a reboot only
+   the deadline leg remains.
+
+## Later: the robust version (`await_condition`, gateway-native)
+
+If condition-waiting becomes a recurring pattern, the honest fix is a first-class
+gateway watcher living beside `scheduler.ts` (per Rule #2 it needs a task doc before any
+implementation). Sketch:
+
+- **Tool:** `await_condition({id, check, interval, timeout, message})` — the gateway
+  polls `check` (a shell predicate) every `interval` seconds and injects `message` the
+  moment it exits 0. `timeout` fires a "condition never came true" injection instead of
+  waiting forever.
+- **Persistence:** watches stored in thread config like schedules → survive gateway
+  restarts and machine reboots (poll loop resumes on startup). This alone removes
+  limitations 1, 2, and 4.
+- **Visibility:** `list_watches` / `cancel_watch` companions, same shape as
+  `list_schedules` / `cancel_schedule`; dashboard can surface pending watches.
+- **Reuse:** fires through the same `sendMessage` path as the scheduler, so queueing,
+  busy→idle drain, and history semantics are identical to today's injections.
+- **Design question to settle in the task doc:** the predicate is the gateway executing a
+  configured shell command. Fine for admin threads on a single-user box; under P7
+  namespace scoping it needs an allowlist or per-namespace opt-in before scoped keys can
+  create watches.
+
+Until then: watcher + deadline, as above.