svamp-cli 0.2.97 → 0.2.100

package/README.md

@@ -107,15 +107,17 @@ svamp session spawn claude -d <path> --deny-read /etc --allow-write /tmp/work
 svamp session spawn claude -d <path> --allow-domain api.anthropic.com
 ```
 
-#### Ralph Loop (Iterative Task Automation)
+#### Loop (Self-Verifying Iterative Automation)
 
 ```bash
-svamp session ralph-start <id> "<task>" [--promise DONE] [--max 10] [--cooldown 1]
-svamp session ralph-cancel <id>
-svamp session ralph-status <id>
+svamp session loop-start <id> "<task>" [--criteria "..."] [--oracle "cmd"] [--max 20] [--evaluator on|off]
+svamp session loop-cancel <id>
+svamp session loop-status <id>
 ```
 
-The Ralph Loop enables agents to iterate on tasks with verifiable completion. Each iteration the agent works toward a goal and signals completion via `<promise>DONE</promise>`.
+The loop iterates a task until it's *objectively* done: a Claude Code `Stop`-hook gate keeps the agent
+working until an **oracle** (a real pass/fail command) passes AND an **independent evaluator** subagent
+confirms completion. Task/plan/progress live in a git-visible `LOOP.md`. Powered by the `loop` skill.
 
 ### Machine Management
 

package/bin/skills/loop/IMPLEMENTATION_PROGRESS.md

@@ -0,0 +1,49 @@
+# Loops, Routines & Channels — implementation status
+
+Branch: `loop-engineering-phase1`. Design docs: `docs/loops-and-routines-design.md`, `docs/channels-design.md`.
+
+This consolidates the work into one accurate picture: what's built, how it was verified, and the single remaining step (deploy + UI QA).
+
+---
+
+## 1. Loop engine — DONE (tested + live-E2E + 2 adversarial reviews)
+Skill-first loop with a harness-enforced completion gate. Files in `skills/loop/`.
+- **`SKILL.md`** — loop-engineering protocol (actor ≠ judge; oracle + isolated evaluator).
+- **`bin/stop-gate.mjs`** — Claude Code `Stop` hook: blocks the turn ending unless the **oracle exits 0 AND a fingerprint-fresh evaluator verdict says "done."** Bounded by clamped `max_iterations` (hard ceiling 200), runtime budget, and token budget (summed from the transcript). Appends a per-iteration audit trail.
+- **`bin/state-fp.mjs`** — working-tree fingerprint (git diff, or filesystem walk incl. symlink targets for non-git dirs) tying a verdict to the exact code it judged.
+- **`bin/inject-loop.mjs`** (SessionStart/UserPromptSubmit) · **`bin/precompact.mjs`** (PreCompact handoff) · **`bin/loop-init.mjs`** (generates LOOP.md + `.claude/settings.json` hooks + optional `loop-evaluator` agent) · **`bin/loop-status.mjs`** (timeline reader).
+- **Tests:** `test/test-loop-gate.mjs` (29) — all pass. **Live-verified** in real svamp sessions: happy path, **early-quit blocked**, isolated evaluator subagent, full regression.
+- Skill↔gate↔inject **contract verified consistent** (verdict path/fields/`state_fp` command all agree).
+
+## 2. Routines — DONE (tested + live-E2E)
+Session-scoped triggers → message/loop actions. `skills/loop/bin/routine-*.mjs` (JS engine + supervised server) and `packages/svamp-cli/src/routine/*.ts` (daemon).
+- Triggers: schedule (cron, tz-aware tick **and** catch-up), webhook (capability URL, GET/POST), manual. Actions: message | loop. Overlap (queue/skip/replace concurrent-guard), daily_cap (reserve-before-deliver), missed-run catch-up.
+- `svamp routine add/list/remove/enable/disable/run-now/serve`; daemon RPC (`hyphaSessionService`, 10 runtime tests); frontend **Routines tab**.
+- **Tests:** routine-core, routine-engine (26), cli routine (18), cli routine-rpc (10) — all pass. **Live-verified**: webhook → templated message delivered into a real session.
+
+## 3. Channels — DONE (tested + live-E2E both transports + 2 security reviews)
+External / agent-to-agent inbound endpoints. `skills/loop/bin/channel-*.mjs` + `packages/svamp-cli/src/channel/store.ts`.
+- Identity: per-key (verified) / caller-supplied (unverified) / fixed / Hypha `context.user` (opt-in `hypha_allow`, deny-by-default, anonymous rejected). Default **XML provenance template** (all values XML-escaped + control-chars stripped → no forgery/tag-breakout). Auto-generated **skill** per channel.
+- Transports: **Hypha `svamp-channels` service** (verified identity, no key) **and** HTTP `/channel/<id>` (+ `/skill.md`, bearer key). Delivers as a **plain single-tag message**. Actions: **message and loop** (loop seeds `loop-init` + kickoff).
+- `hypha channel list/describe/send` CLI client; daemon RPC (10 runtime tests); frontend **Channels tab**.
+- **Tests:** channel-core (32), cli channel-rpc (10) — all pass. **Live-verified**: HTTP per-key (`from=alice verified`), Hypha (`from=<hypha-user> verified`, no key), loop-action (loop seeded + work completed).
+
+## Verification summary
+All feature suites green; **svamp-cli + svamp-app + hypha-cli typecheck 0 errors**. Standalone/skill parts live-E2E-verified. Daemon RPC runtime-verified via `createSessionStore`. Two adversarial review rounds each on the loop gate and channels (caught + fixed 3 CRITICAL block-forever bugs and a CRITICAL provenance-forgery hole); daemon-code review confirmed no destabilization. Review has **converged** (latest pass found nothing).
+
+---
+
+## The ONE remaining step — deploy + UI QA (must be done from a SEPARATE session)
+The daemon RPC + the three frontend tabs (Routines / Channels / Loop-monitor) are typecheck-clean and production-bundle clean, but their **live rendering + RPC round-trip have not been visually confirmed** — and this repo has no component-render test infra (UI is verified by deploy/manual). Activating them restarts the daemon hosting this loop session, so it is **deliberately not done here**. To finish:
+```
+yarn workspace svamp-cli build && svamp daemon restart   # activates routine/channel RPC
+./deploy/quick-deploy.sh                                  # ships the web UI
+```
+Then open a session → input → settings and confirm the **Routines / Channels / Loop-monitor** tabs render and round-trip. The standalone engines need no deploy — `node skills/loop/bin/loop-init.mjs …`, `svamp routine …`, and the supervised channel/routine servers already work today.
+
+## Deferred (by design or low-risk-to-leave)
+- **await-reply (channels v1.1)** — request/response; v1 is async (two channels), per the design decision.
+- **Loop gate on an already-running session** — hooks load at Claude startup, so looping a live session is best-effort (self-contained kickoff); full enforcement needs a fresh/restarted session.
+- **#4/#6/#11 concurrency edges** — cross-process lost-update / git↔walk fp flip / store last-writer-wins. Low-likelihood for the single-session loop; a forced fix needs locking that could itself cause block-forever, so documented rather than fixed.
+- **Token/cost budget in USD** — token budget (from transcript) is implemented; USD cost would need daemon usage accounting.
+</content>

package/bin/skills/loop/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: loop
+version: 0.2.0
+description: Run a task as a reliable, self-verifying loop — iterate until objective exit conditions are met, with an independent evaluator instead of self-judging. Use when a task needs repeated iterations until "done" (fix until tests pass, refactor until clean, build until a spec is met, autonomous long-running work).
+---
+
+# Loop — loop engineering for long-running, self-verifying agents
+
+This skill turns a task into a **loop**: the agent iterates until the work is *objectively* done, not until the agent *feels* done. It is built on one hard-won lesson from loop engineering — **the thing that decides "done" must be independent of the thing doing the work.**
+
+## Why loops, and why this design
+
+Prompting an agent turn-by-turn doesn't scale to long or autonomous work. Loop engineering is the shift from *running the agent yourself* to *designing the system that runs it*. A good loop has a small number of durable parts, and most of the leverage is in **the loop, not the prompt**.
+
+The failure this design exists to prevent is **early quitting**: a model asked to judge its own output will confidently declare success on mediocre or incomplete work, and models also tend to "wrap up" as they approach context limits ("context anxiety"). Trusting the actor to say `DONE` is the single biggest source of unreliable loops.
+
+So this loop is built on these principles:
+
+1. **Actor ≠ judge.** The agent doing the work never decides completion. An *independent* evaluator — a fresh, skeptical agent that only sees the artifacts, not your reasoning — does. Calibrating a separate evaluator toward skepticism is far more reliable than asking yourself to be self-critical.
+2. **Verification needs an oracle.** The strongest signal is something *outside any model* that returns a hard yes/no: a test suite, a build, a linter, a type-check, a script. The loop runs the oracle itself; you cannot fake it.
+3. **State lives on disk, not in context.** *The model forgets; the repo doesn't.* The task, plan, and progress live in **`LOOP.md`** in the project — readable and editable by both you and the human, surviving compaction, restarts, and fresh sessions. It is your durable memory and your self-improving harness.
+4. **The harness enforces, the prompt only requests.** Completion is gated by a Claude Code **`Stop` hook** that the runtime *obeys* — it physically refuses to let the turn end until the exit conditions hold. This is what makes the loop reliable rather than aspirational.
+5. **Bounded by construction.** Every loop has a `max_iterations` and a token/cost budget so it cannot run away.
+6. **Stay auditable.** Every iteration leaves a trail (oracle result, evaluator verdict, progress notes) so a human can review *why* it stopped, not just *that* it stopped. Build the loop like someone who intends to stay the engineer.
+
+These principles are stable even as models get stronger. As the actor improves, you simply lean on lighter scaffolding (e.g. trust longer continuous context, fewer resets) — but *independent verification of "done"* and *durable on-disk state* remain correct regardless of model capability. Don't reimplement what the runtime already gives you (subagents, compaction, worktrees, usage accounting); compose them.
+
+## The loop, in one picture
+
+```
+read LOOP.md ─► do real work on the task ─► update LOOP.md progress
+      ▲                                              │
+      │                                  (think you're done?)
+      │                                              ▼
+      │                         run ORACLE  +  spawn independent EVALUATOR
+      │                                              │
+   Stop hook blocks ◄── not done ── GATE ── done ──► loop ends
+   (oracle/verdict fails)
+```
+
+Each turn is one iteration. When you try to end your turn, the gate re-checks the exit conditions. If they don't hold, you are sent back with specific feedback. You converge by *fixing the blocking issue*, not by re-asserting that you're done.
+
+## Exit conditions (what "done" means)
+
+The loop ends only when **all** configured conditions hold:
+- **Oracle passes** — the configured command exits 0. The gate runs it; do not stub or fake it.
+- **Independent evaluator says "done"** (when enabled) — a *fresh* verdict tied to the *current* code state. A verdict written before later edits is stale and rejected.
+
+## Your protocol each iteration
+
+1. **Read `LOOP.md`.** It holds the task, success criteria, plan, and progress. (It is auto-injected each turn.)
+2. **Make real progress** on the task. Prefer the smallest change that advances a success criterion.
+3. **Keep `LOOP.md` current** — refine the plan, append what you did, what passed, what's left. This is the memory the *next* iteration (or a post-restart fresh session) relies on. You may restructure it; you may **not** weaken the success criteria to make quitting easier (that's visible in git and to the human).
+4. **Run the oracle yourself** to check you're actually passing before claiming done.
+5. **When you believe it's complete, get an independent verdict — do not grade yourself:**
+   - Spawn a fresh subagent with the `Task` tool (use the `loop-evaluator` agent if present, otherwise an inline *skeptical reviewer* prompt). Give it **only** the goal (from `LOOP.md`), the current diff, and the oracle output — never your chain of thought.
+   - It returns `{"verdict":"done"|"continue","reason":...,"guidance":...}`. It should default to `continue` on any doubt.
+   - Record it to `.claude/loop/evaluator-verdict.json`, adding the current state fingerprint:
+     `{"verdict":"done","reason":"...","guidance":"...","state_fp":"<output of: node .claude/loop/bin/state-fp.mjs>"}`
+6. **End your turn.** The Stop gate verifies oracle + fresh verdict and either ends the loop or sends you back with the exact blocking reason. Address that reason next iteration.
+
+If you're blocked by something genuinely outside the task (missing secret, ambiguous requirement, external outage), record it clearly in `LOOP.md` so the human sees it on review.
+
+## Setting up a loop
+
+Initialise the loop scaffolding in a project (idempotent):
+
+```bash
+node <skill>/bin/loop-init.mjs <project-dir> \
+  --task "Make the failing auth tests pass without weakening them" \
+  --criteria "All auth tests pass; no test was weakened or skipped" \
+  --oracle "npm test --silent" \
+  --evaluator on \
+  --max 20
+```
+
+This generates: `LOOP.md` (task/criteria/progress), `.claude/loop/loop.config.json`, machine state in `.claude/loop/loop-state.json`, the `Stop`/`SessionStart` hooks in `.claude/settings.json`, and (optionally) a materialised `.claude/agents/loop-evaluator.md` skeptical reviewer. Re-running with new flags retunes a live loop.
+
+## Anatomy (files & ownership)
+
+| File | Owner | Purpose |
+|---|---|---|
+| `LOOP.md` | you + human | task · success criteria · plan · progress (durable memory, git-visible) |
+| `.claude/loop/loop.config.json` | config | oracle command, evaluator on/off + model, max_iterations |
+| `.claude/loop/loop-state.json` | the gate | iteration, phase, last oracle/eval result (machine state — don't hand-edit) |
+| `.claude/loop/evaluator-verdict.json` | written from the evaluator subagent | latest verdict + state fingerprint |
+| `.claude/settings.json` (hooks) | generated | `Stop` gate + `SessionStart`/`UserPromptSubmit` LOOP.md injection |
+| `.claude/agents/loop-evaluator.md` | generated (optional) | skeptical reviewer persona + model |
+
+## Tuning & extending (future-proofing)
+
+- **No oracle?** Lean fully on the evaluator (weaker — prefer adding *some* objective check, even a smoke script).
+- **Stronger judgment?** Point the evaluator at a stronger model via `--model`.
+- **Cheaper?** Disable the evaluator (`--evaluator off`) and rely on the oracle alone for purely objective tasks.
+- **Different exit logic** (scores/thresholds, FINISH/REFINE/PIVOT strategies, multi-dimensional rubrics): the verdict file is just JSON and the gate reads it — richer verdicts can be added without changing the protocol.
+- **Triggers & lifecycle** (run on a schedule, on a webhook, via an API; pause/resume): handled by the surrounding routine layer, not this skill — the loop itself stays a pure iterate-until-done engine.
+- **Compaction handoff**: progress in `LOOP.md` is the handoff artifact; a `PreCompact` hook can flush it automatically for very long runs.
+
+The contract that must never change: **work is decided done by something other than the worker, and the loop's memory lives on disk.** Everything else is tunable.

package/bin/skills/loop/bin/channel-core.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// channel-core.mjs — transport-agnostic core for Channels (external / agent-to-agent
+// inbound endpoints). Project-folder config + identity resolution + default XML
+// template + skill generation. Used by both the HTTP and Hypha transports.
+// See docs/channels-design.md.
+import { mkdirSync, writeFileSync, renameSync, readdirSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { renderTemplate } from './routine-core.mjs';
+
+const genId = () => 'c_' + randomBytes(5).toString('hex');
+const genKey = () => 'ck_' + randomBytes(18).toString('base64url');
+
+// Default message template: XML carrying provenance so the agent always knows
+// who sent it, through which channel, and whether the identity is verified.
+export const DEFAULT_TEMPLATE =
+`<inbound-message from="\${sender.name}" sender-type="\${sender.kind}" verified="\${sender.verified}" channel="\${channel.name}" call-id="\${call.id}" at="\${now}">
+\${body.message}
+</inbound-message>`;
+
+// ---- store (project folder: <dir>/.svamp/channels/<id>.json) ------------
+export class ChannelStore {
+  constructor(projectDir) { this.dir = join(projectDir, '.svamp', 'channels'); mkdirSync(this.dir, { recursive: true }); }
+  _path(id) { return join(this.dir, `${id}.json`); }
+  list() {
+    return readdirSync(this.dir).filter((f) => f.endsWith('.json')).map((f) => {
+      try { return JSON.parse(readFileSync(join(this.dir, f), 'utf8')); } catch { return null; }
+    }).filter(Boolean);
+  }
+  get(id) { try { return JSON.parse(readFileSync(this._path(id), 'utf8')); } catch { return null; } }
+  save(channel) {
+    const c = { enabled: true, bind: 'active', template: DEFAULT_TEMPLATE, action: { kind: 'message' },
+      identity: { mode: 'per-key', callers: [] }, last_calls: [], ...channel };
+    if (!c.id) c.id = genId();
+    const errs = validateChannel(c);
+    if (errs.length) throw new Error('invalid channel: ' + errs.join('; '));
+    const tmp = this._path(c.id) + '.tmp';
+    writeFileSync(tmp, JSON.stringify(c, null, 2));
+    renameSync(tmp, this._path(c.id));
+    return c;
+  }
+  remove(id) { const p = this._path(id); if (existsSync(p)) { rmSync(p); return true; } return false; }
+  addCaller(id, name, kind = 'agent') {
+    const c = this.get(id); if (!c) return null;
+    c.identity.callers = c.identity.callers || [];
+    const caller = { name, kind, key: genKey() };
+    c.identity.callers.push(caller);
+    this.save(c);
+    return caller;
+  }
+  recordCall(id, entry) {
+    const c = this.get(id); if (!c) return null;
+    c.last_calls = [{ at: new Date().toISOString(), ...entry }, ...(c.last_calls || [])].slice(0, 30);
+    return this.save(c);
+  }
+}
+
+export function validateChannel(c) {
+  const errs = [];
+  if (!c || typeof c !== 'object') return ['channel must be an object'];
+  if (!c.name) errs.push('name required');
+  const m = c.identity?.mode;
+  if (!['per-key', 'caller-supplied', 'fixed'].includes(m)) errs.push('identity.mode must be per-key|caller-supplied|fixed');
+  if (m === 'fixed' && !c.identity.fixed?.name) errs.push('identity.fixed.name required for fixed mode');
+  if (!['message', 'loop'].includes(c.action?.kind)) errs.push('action.kind must be message|loop');
+  if (c.bind !== 'active' && !(c.bind && c.bind.tag) && !(c.bind && c.bind.session)) errs.push('bind must be "active", {tag}, or {session}');
+  // Security: a keyless/open channel + loop action = unauthenticated task injection.
+  if (c.action?.kind === 'loop' && m === 'caller-supplied' && !c.identity?.shared_key)
+    errs.push('a caller-supplied channel without a shared_key may not use a loop action (unauthenticated task injection)');
+  // Defense-in-depth: single-line, no XML metachars on operator-set strings that
+  // land in the trust tag and/or the served skill markdown (frontmatter breakout).
+  const unsafe = /[<>"'&\r\n]/;
+  if (unsafe.test(c.name || '')) errs.push('name must be single-line and not contain < > " \' &');
+  if (c.description && unsafe.test(c.description)) errs.push('description must be single-line and not contain < > " \' &');
+  if (c.skill?.name && unsafe.test(c.skill.name)) errs.push('skill.name must be single-line and not contain < > " \' &');
+  if (c.skill?.description && unsafe.test(c.skill.description)) errs.push('skill.description must be single-line and not contain < > " \' &');
+  if (m === 'fixed' && c.identity.fixed?.name && unsafe.test(c.identity.fixed.name)) errs.push('identity.fixed.name must not contain < > " \' & or newlines');
+  for (const cl of (c.identity?.callers || [])) if (unsafe.test(cl.name || '')) errs.push(`caller name "${cl.name}" must not contain < > " ' & or newlines`);
+  return errs;
+}
+
+// ---- identity resolution ------------------------------------------------
+// Returns { sender:{name,kind,verified} } or { error } (401/403-ish).
+export function resolveSender(channel, { key, from, hyphaUser, hyphaWorkspace, hyphaAnonymous } = {}) {
+  const id = channel.identity || {};
+  // Hypha-authenticated caller: honored ONLY when the channel EXPLICITLY opts in
+  // via a non-empty hypha_allow (deny-by-default — never allow-all when unset, and
+  // never override a configured per-key/fixed mode). ANONYMOUS Hypha callers are
+  // NOT verified identities, so they never take this branch (even with '*').
+  if (hyphaUser && !hyphaAnonymous && Array.isArray(id.hypha_allow) && id.hypha_allow.length) {
+    if (id.hypha_allow.includes('*') || id.hypha_allow.includes(hyphaUser) || (hyphaWorkspace && id.hypha_allow.includes(hyphaWorkspace)))
+      return { sender: { name: hyphaUser, kind: 'agent', verified: true } };
+    return { error: 'caller not in hypha_allow' };
+  }
+  if (id.mode === 'fixed') return { sender: { ...id.fixed, verified: true } };
+  if (id.mode === 'per-key') {
+    const caller = (id.callers || []).find((c) => c.key && c.key === key);
+    if (!caller) return { error: 'invalid or missing key' };
+    return { sender: { name: caller.name, kind: caller.kind, verified: true } };
+  }
+  if (id.mode === 'caller-supplied') {
+    if (id.shared_key && key !== id.shared_key) return { error: 'invalid key' };
+    return { sender: { name: from || 'anonymous', kind: 'user', verified: false } };
+  }
+  return { error: 'unsupported identity mode' };
+}
+
+// ---- render the injected message ----------------------------------------
+// XML-escape EVERY interpolated value. The <inbound-message from=… verified=…>
+// tag is the agent's entire trust signal, and from/message are caller-controlled
+// — without escaping a caller could forge verified="true" or inject a second tag
+// (provenance forgery / tag breakout). Escaping neutralizes < > " ' &.
+const MAX_BODY = 16 * 1024;
+export function xmlEscape(s) {
+  return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+// Strip control chars (incl. newlines) — for single-line ATTRIBUTE values, so an
+// attacker-controlled name can't smuggle extra lines into the trust header.
+const stripControl = (s) => String(s ?? '').replace(/[\x00-\x1f\x7f]/g, ' ');
+export function renderMessage(channel, { sender = {}, body = {}, query = {}, callId, now }) {
+  const obj = (v) => (typeof v === 'object' && v !== null ? JSON.stringify(v) : v);
+  const escVal = (v) => xmlEscape(obj(v));                 // element content (multi-line ok)
+  const escAttr = (v) => xmlEscape(stripControl(obj(v)));  // attribute position (single-line)
+  const bodyEsc = {};
+  for (const [k, v] of Object.entries(body)) bodyEsc[k] = k === 'message' ? escVal(String(v ?? '').slice(0, MAX_BODY)) : escAttr(v);
+  const queryEsc = {};
+  for (const [k, v] of Object.entries(query)) if (k !== 'key') queryEsc[k] = escAttr(v); // never echo the secret
+  const ctx = {
+    sender: { name: escAttr(sender.name), kind: escAttr(sender.kind), verified: sender.verified === true },
+    body: bodyEsc, query: queryEsc,
+    channel: { name: escAttr(channel.name), id: escAttr(channel.id) },
+    call: { id: escAttr(callId) }, now: escAttr(now || new Date().toISOString()),
+  };
+  return renderTemplate(channel.template || DEFAULT_TEMPLATE, ctx);
+}
+
+// ---- skill (how external agents call this channel) ----------------------
+export function generateSkillBody(channel, urlBase) {
+  const url = `${urlBase || 'https://<svamp-tunnel>'}/channel/${channel.id}`;
+  return `---
+name: ${channel.skill?.name || channel.name}
+description: ${channel.skill?.description || channel.description || `Send a message to the "${channel.name}" channel.`}
+---
+# ${channel.name}
+${channel.description || ''}
+
+This is a self-contained guide for messaging another agent. Share this skill
+(or its URL, \`${url}/skill.md\`) with an agent and it will know how to reach me.
+
+**Hypha RPC (preferred, verified identity — no key needed):**
+\`get_service("<ws>/<machine>:channels").send({ channel: "${channel.id}", message: "..." })\`
+
+**HTTP:** \`POST ${url}\` with header \`Authorization: Bearer <your-key>\`
+Body: \`{ "message": "<your message>", "from": "<your name>" }\`
+
+Your identity is attached automatically; the receiving agent sees an
+\`<inbound-message from="...">\` tag. Keep messages self-contained.`;
+}
+
+export { genId, genKey };

package/bin/skills/loop/bin/channel-server.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// channel-server.mjs — serve a project's Channels over BOTH transports:
+//   • Hypha RPC: registers a `channels` service (type svamp-channels) with
+//     list/describe/send; caller identity = verified context.user.
+//   • HTTP: POST /channel/<id> (Bearer key), GET /channel/<id>[/skill.md].
+// Delivery: renders the channel template and injects it into the bound session
+// via `svamp session send`. Config from the project folder (.svamp/channels/).
+//
+// Env: CHANNEL_PROJECT_DIR (default cwd), CHANNEL_SESSION (default bind target),
+//      CHANNEL_HTTP_PORT (default 8733), CHANNEL_URL_BASE (for skill URLs),
+//      HYPHA_SERVER_URL / HYPHA_TOKEN / HYPHA_WORKSPACE (from ~/.hypha/.env).
+import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { ChannelStore, resolveSender, renderMessage, generateSkillBody, validateChannel } from './channel-core.mjs';
+import { renderTemplate } from './routine-core.mjs';
+
+const LOOP_INIT = join(dirname(fileURLToPath(import.meta.url)), 'loop-init.mjs');
+
+const PROJECT = resolve(process.env.CHANNEL_PROJECT_DIR || process.cwd());
+const DEFAULT_SESSION = process.env.CHANNEL_SESSION || null;
+const URL_BASE = process.env.CHANNEL_URL_BASE || `http://localhost:${process.env.CHANNEL_HTTP_PORT || 8733}`;
+const store = new ChannelStore(PROJECT);
+const callId = () => 'call_' + randomBytes(5).toString('hex');
+
+// svamp binary (override for repo build, e.g. SVAMP_BIN="node …/dist/cli.js").
+const SVAMP = (process.env.SVAMP_BIN || 'svamp').split(' ');
+
+function targetSession(channel) {
+  if (channel.bind && channel.bind.session) return channel.bind.session;   // explicit pin (standalone)
+  return DEFAULT_SESSION;   // 'active' resolution is the daemon's job; standalone uses the configured session
+}
+
+// Inject the channel message as a PLAIN user message (`session send --plain`) so
+// the agent sees a single `<inbound-message>` provenance tag — not the inbox
+// `<svamp-message>` envelope. (Daemon-native channels do this in-process.)
+async function deliver(channel, sender, body, query) {
+  const sid = targetSession(channel);
+  if (!sid) return { ok: false, error: 'no bound session (set CHANNEL_SESSION or channel.bind.session)' };
+  const id = callId();
+  try {
+    if (channel.action?.kind === 'loop') {
+      // Start a loop in the bound session's project dir, seeded by the caller's
+      // request. (Loop-action channels require auth — validateChannel forbids the
+      // keyless caller-supplied case — so the caller-influenced task is gated.)
+      // CAVEAT: the Stop-GATE only enforces if the session's Claude process started
+      // AFTER the .claude/settings.json hooks existed (hooks load at startup). When
+      // we loop-init an ALREADY-RUNNING session, the gate isn't active for that
+      // process, so the kickoff is self-contained (task + read-LOOP.md + iterate)
+      // and the work still gets done; full gate enforcement needs a fresh/restarted
+      // session (which daemon-native delivery would do). We mark status accordingly.
+      const dir = resolve(channel.action.loop?.dir || PROJECT);
+      const ctx = { sender, body, query, channel: { name: channel.name, id: channel.id }, call: { id }, now: new Date().toISOString() };
+      const task = (channel.action.task_template ? renderTemplate(channel.action.task_template, ctx) : body.message) || '(task from channel)';
+      const labelled = `[via channel "${channel.name}" from ${sender.name}${sender.verified ? '' : ' (unverified)'}] ${task}`;
+      const initArgs = [LOOP_INIT, dir, '--task', labelled];
+      const oracle = channel.action.loop?.oracle;
+      if (oracle) initArgs.push('--oracle', oracle);
+      initArgs.push('--evaluator', channel.action.loop?.evaluator || 'off');
+      execFileSync(process.execPath, initArgs, { stdio: 'pipe' });
+      // Self-contained kickoff (works whether or not the Stop hook is active on the
+      // running process): the task + how to verify + iterate.
+      const kickoff = `🔁 Loop request via channel "${channel.name}".\nRead LOOP.md and work the task below until it is genuinely complete${oracle ? ` and the oracle passes: \`${oracle}\`` : ''}. Update LOOP.md progress as you go.\n\nTask: ${labelled}`;
+      execFileSync(SVAMP[0], [...SVAMP.slice(1), 'session', 'send', sid, kickoff, '--plain'], { stdio: 'pipe' });
+      store.recordCall(channel.id, { sender: sender.name, verified: sender.verified, callId: id, outcome: 'loop-started' });
+      return { ok: true, call_id: id, status: 'loop-started' };
+    }
+    const message = renderMessage(channel, { sender, body, query, callId: id });
+    execFileSync(SVAMP[0], [...SVAMP.slice(1), 'session', 'send', sid, message, '--plain'], { stdio: 'pipe' });
+    store.recordCall(channel.id, { sender: sender.name, verified: sender.verified, callId: id, outcome: 'delivered' });
+    return { ok: true, call_id: id, status: 'accepted' };
+  } catch (e) {
+    store.recordCall(channel.id, { sender: sender.name, verified: sender.verified, callId: id, outcome: 'error' });
+    return { ok: false, error: String(e?.message || e) };
+  }
+}
+
+const channelView = (c) => ({ id: c.id, name: c.name, description: c.description, identity: { mode: c.identity?.mode }, action: c.action?.kind });
+
+// ── Hypha RPC service ────────────────────────────────────────────────────
+async function registerHypha() {
+  const token = process.env.HYPHA_TOKEN;
+  const serverUrl = process.env.HYPHA_SERVER_URL || 'https://hypha.aicell.io';
+  if (!token) { console.error('[channels] no HYPHA_TOKEN — skipping Hypha registration (HTTP only)'); return null; }
+  const { hyphaWebsocketClient } = await import('hypha-rpc');
+  const server = await hyphaWebsocketClient.connectToServer({ server_url: serverUrl, token, workspace: process.env.HYPHA_WORKSPACE || undefined, logger: null });
+  const svc = await server.registerService({
+    id: 'channels',
+    name: 'Svamp Channels',
+    type: 'svamp-channels',
+    config: { visibility: 'public', require_context: true },
+    async list() { return store.list().filter((c) => c.enabled !== false).map(channelView); },
+    async describe(kwargs = {}) {
+      const c = store.get(kwargs.channel); if (!c) return { error: 'not found' };
+      return { ...channelView(c), skill: { body: generateSkillBody(c, URL_BASE) } };
+    },
+    async send(kwargs = {}, context) {
+      const c = store.get(kwargs.channel);
+      if (!c || c.enabled === false) return { error: 'channel not found' };
+      const user = context?.user?.email || context?.user?.id;
+      const r = resolveSender(c, { hyphaUser: user, hyphaAnonymous: context?.user?.is_anonymous === true, hyphaWorkspace: context?.ws || context?.user?.scope?.current_workspace, from: kwargs.from });
+      if (r.error) return { error: r.error };
+      return deliver(c, r.sender, { message: kwargs.message }, {});
+    },
+  });
+  console.log(`[channels] registered Hypha service: ${svc.id} (type svamp-channels)`);
+  return server;
+}
+
+// ── HTTP transport ───────────────────────────────────────────────────────
+function startHttp(port) {
+  const server = createServer((req, res) => {
+    const u = new URL(req.url, URL_BASE);
+    if (u.pathname === '/' || u.pathname === '/health') { res.writeHead(200).end('channels ok'); return; }
+    if (u.pathname === '/channels') {
+      res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(store.list().filter(c => c.enabled !== false).map(channelView)));
+      return;
+    }
+    let m = u.pathname.match(/^\/channel\/([\w.-]+)\/skill\.md$/);
+    if (m) { const c = store.get(m[1]); if (!c) { res.writeHead(404).end('not found'); return; }
+      res.writeHead(200, { 'content-type': 'text/markdown' }).end(generateSkillBody(c, URL_BASE)); return; }
+    m = u.pathname.match(/^\/channel\/([\w.-]+)$/);
+    if (!m) { res.writeHead(404).end('not found'); return; }
+    const c = store.get(m[1]);
+    if (!c || c.enabled === false) { res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'channel not found' })); return; }
+    if (req.method === 'GET' && !u.searchParams.get('message')) {
+      res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ...channelView(c), skill_url: `${URL_BASE}/channel/${c.id}/skill.md` })); return;
+    }
+    let chunks = '';
+    req.on('data', (d) => { chunks += d; if (chunks.length > 1e6) req.destroy(); });
+    req.on('end', async () => {
+      let body = {}; try { body = chunks ? JSON.parse(chunks) : {}; } catch {}
+      const key = (req.headers.authorization || '').replace(/^Bearer\s+/i, '') || u.searchParams.get('key');
+      const message = body.message ?? u.searchParams.get('message');
+      const r = resolveSender(c, { key, from: body.from || u.searchParams.get('from') });
+      if (r.error) { res.writeHead(401, { 'content-type': 'application/json' }).end(JSON.stringify({ error: r.error })); return; }
+      const out = await deliver(c, r.sender, { message }, Object.fromEntries(u.searchParams));
+      res.writeHead(out.ok ? 200 : 500, { 'content-type': 'application/json' }).end(JSON.stringify(out));
+    });
+  });
+  server.listen(port, () => console.log(`[channels] HTTP on ${URL_BASE} (POST /channel/<id>)`));
+  return server;
+}
+
+const port = Number(process.env.CHANNEL_HTTP_PORT) || 8733;
+const http = startHttp(port);
+const hyphaServer = await registerHypha().catch((e) => { console.error('[channels] Hypha registration failed:', e?.message || e); return null; });
+console.log(`[channels] serving ${store.list().length} channel(s) from ${PROJECT}`);
+process.on('SIGINT', () => { http.close(); hyphaServer?.disconnect?.(); process.exit(0); });

package/bin/skills/loop/bin/inject-loop.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// inject-loop.mjs — Claude Code `SessionStart` / `UserPromptSubmit` hook.
+// Injects the current LOOP.md plus the loop protocol so every iteration starts
+// from the latest task/plan/progress without any daemon re-injection.
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROJECT = resolve(HERE, '..', '..', '..');
+const LOOP_DIR = join(PROJECT, '.claude', 'loop');
+
+function readJSON(p, f) { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return f; } }
+const cfg = readJSON(join(LOOP_DIR, 'loop.config.json'), null);
+const state = readJSON(join(LOOP_DIR, 'loop-state.json'), { active: false });
+if (!cfg || state.active === false) process.exit(0); // no active loop -> inject nothing
+
+let loopMd = '';
+const loopPath = join(PROJECT, cfg.loop_file || 'LOOP.md');
+if (existsSync(loopPath)) loopMd = readFileSync(loopPath, 'utf8');
+
+const evaluatorOn = cfg.evaluator?.enabled !== false;
+const oracleCmd = cfg.oracle?.command || cfg.oracle?.test || cfg.oracle?.build || cfg.oracle || null;
+
+const protocol = `# 🔁 LOOP MODE IS ACTIVE
+
+You are running inside a loop. Each turn is one iteration. Work toward completing the task described in LOOP.md below. You CANNOT end the loop by simply saying you are done — a Stop gate independently re-checks the exit conditions and will send you back to work if they are not met.
+
+**Exit conditions (all must hold before the loop ends):**
+${oracleCmd ? `1. The oracle command must pass: \`${oracleCmd}\` (exit 0). The gate runs this itself — do not fake it.\n` : '1. (No oracle configured.)\n'}${evaluatorOn ? `2. An INDEPENDENT evaluator must judge the work \"done\". Before you finish: spawn a fresh subagent (Task tool) named/acting as \`loop-evaluator\` with a skeptical reviewer prompt; give it ONLY the goal (from LOOP.md), the current diff, and the oracle output. Have IT decide. Then record its verdict to \`.claude/loop/evaluator-verdict.json\`:\n   {"verdict":"done"|"continue","reason":"...","guidance":"...","state_fp":"<output of: node .claude/loop/bin/state-fp.mjs>"}\n   Do NOT grade your own work — the verdict must come from the subagent, and it is only valid for the exact code state it reviewed.\n` : ''}
+
+**Each iteration:** read LOOP.md → make real progress on the task → update the Progress section of LOOP.md → run/verify the oracle → (if you believe it's done) get the evaluator verdict → end your turn to be re-checked. Keep LOOP.md current; it is your durable memory across iterations and restarts.
+
+---
+## LOOP.md
+${loopMd || '(LOOP.md not found — create it with the task and a Progress section.)'}
+`;
+
+// SessionStart/UserPromptSubmit: stdout is added to the model's context.
+process.stdout.write(protocol);
+process.exit(0);