@openparachute/agent 0.1.2 → 0.2.2

package/src/jobs.ts

@@ -0,0 +1,266 @@
+/**
+ * Scheduled-job model + VAULT-NATIVE store for the runner (design
+ * `2026-06-17-runner-scheduled-agent-turns.md`).
+ *
+ * A scheduled job is "an automated human": send message M to agent (channel) A on
+ * schedule S. The runner does NOT execute anything — it authors an inbound
+ * `#agent/message/inbound` note on a schedule, and the existing vault trigger →
+ * agent-turn → outbound flow does the rest.
+ *
+ * STORAGE IS VAULT-NATIVE (Aaron's call, 2026-06-17): a job IS a `#agent/job`
+ * note in the TARGET channel's vault — durable, queryable, and renderable by any
+ * surface, converging with the blueprint's "vault as the spine" and the future
+ * `tag:job` idea. There is NO jobs.json. The vault note I/O lives on
+ * `VaultTransport` (it owns the vault URL + token + encoding); this module is the
+ * thin, storage-agnostic FACADE that keeps the same read-all / upsert / remove
+ * interface the runner + API call. Token handling is never duplicated here.
+ *
+ * `metadata` on the note is all string-typed (the vault stores metadata as
+ * strings): `{ channel, cron, tz?, enabled, createdAt, lastRunAt?, lastStatus? }`.
+ * `nextRunAt` is NOT persisted — the runner computes it in memory each tick.
+ *
+ * `validateJob` is the pure gate the API runs before writing: slug-shaped id, a
+ * known channel that's a VAULT transport, and a parseable cron.
+ */
+
+import { parseCron, CronParseError } from "./cron.ts";
+import { VaultTransport } from "./transports/vault.ts";
+import type { Channel } from "./registry.ts";
+
+/** A job's schedule: a 5-field cron expr + optional IANA tz (default daemon-local). */
+export interface JobSchedule {
+  /** 5-field cron: `min hour dom mon dow`. */
+  cron: string;
+  /** IANA timezone (e.g. "America/Los_Angeles"). Optional — default daemon-local. */
+  tz?: string;
+}
+
+/**
+ * One scheduled job. The in-memory shape the runner + API operate on; persisted as
+ * a `#agent/job` vault note (see the store below). `id` is the slug (also the
+ * `runner:<id>` sender provenance + the note path segment).
+ */
+export interface Job {
+  /** The operator-facing slug (typed on create; addresses the job in `/api/jobs/:id`). */
+  id: string;
+  /**
+   * The vault note id/path that addresses the persisted note for PATCH/DELETE.
+   * Absent on a freshly-created in-memory `Job` (set after `upsert` / on `listAll`).
+   * The runner + UI key off `id` (the slug); the store uses `noteId` for I/O.
+   */
+  noteId?: string;
+  /** The channel to inject into — MUST be a vault channel. */
+  channel: string;
+  /** The message text written as the inbound note content (= the job note's content). */
+  message: string;
+  /** When to fire. */
+  schedule: JobSchedule;
+  /** Whether the runner considers this job (default true on create). */
+  enabled: boolean;
+  /** ISO timestamp the job was created. */
+  createdAt: string;
+  /** ISO timestamp of the most recent fire (set by the runner; persisted via PATCH). */
+  lastRunAt?: string;
+  /** "ok" or "error: <detail>" from the most recent fire (persisted via PATCH). */
+  lastStatus?: string;
+  /** ISO timestamp of the next scheduled fire — COMPUTED IN MEMORY, never persisted. */
+  nextRunAt?: string;
+}
+
+/** A slug: alphanumeric, dash, underscore (same shape as channel names). */
+const SLUG_RE = /^[a-zA-Z0-9_-]+$/;
+
+/** The result of validating a candidate job. `ok:false` carries an operator-facing reason. */
+export type JobValidation = { ok: true } | { ok: false; error: string };
+
+/**
+ * Validate a candidate job before it's persisted. The API runs this and maps an
+ * `ok:false` to a 400. Pure (no vault I/O) — `isVaultChannel(name)` is injected:
+ *   - returns `true`  → known + vault,
+ *   - returns `false` → known but NOT vault,
+ *   - returns `null`  → unknown channel.
+ *
+ * Checks, in order: id slug → non-empty message → parseable cron → valid tz (if
+ * present) → channel known AND vault (the inject path is "write an inbound note,"
+ * which only a vault transport supports).
+ */
+export function validateJob(
+  candidate: {
+    id?: unknown;
+    channel?: unknown;
+    message?: unknown;
+    schedule?: unknown;
+    enabled?: unknown;
+  },
+  isVaultChannel: (name: string) => boolean | null,
+): JobValidation {
+  if (typeof candidate.id !== "string" || !SLUG_RE.test(candidate.id)) {
+    return { ok: false, error: "id must be a slug (alphanumeric, dash, underscore)" };
+  }
+  if (typeof candidate.message !== "string" || candidate.message.trim().length === 0) {
+    return { ok: false, error: "message must be a non-empty string" };
+  }
+  const sched = candidate.schedule as { cron?: unknown; tz?: unknown } | undefined;
+  if (!sched || typeof sched.cron !== "string" || sched.cron.trim().length === 0) {
+    return { ok: false, error: "schedule.cron must be a non-empty cron expression" };
+  }
+  try {
+    parseCron(sched.cron);
+  } catch (err) {
+    const msg = err instanceof CronParseError ? err.message : String(err);
+    return { ok: false, error: `invalid schedule.cron: ${msg}` };
+  }
+  if (sched.tz !== undefined) {
+    if (typeof sched.tz !== "string" || sched.tz.length === 0) {
+      return { ok: false, error: "schedule.tz must be a non-empty IANA timezone string" };
+    }
+    try {
+      // Construct a formatter to validate the zone — throws RangeError if invalid.
+      new Intl.DateTimeFormat("en-US", { timeZone: sched.tz });
+    } catch {
+      return { ok: false, error: `invalid schedule.tz: "${sched.tz}" is not a known IANA timezone` };
+    }
+  }
+  if (typeof candidate.channel !== "string" || candidate.channel.length === 0) {
+    return { ok: false, error: "channel must be a non-empty string" };
+  }
+  const vault = isVaultChannel(candidate.channel);
+  if (vault === null) {
+    return { ok: false, error: `unknown channel "${candidate.channel}"` };
+  }
+  if (vault === false) {
+    return {
+      ok: false,
+      error: `channel "${candidate.channel}" is not a vault channel — scheduled jobs require a vault-backed agent (the runner injects an inbound note)`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Resolve a channel name to its live `VaultTransport`, or null if the channel is
+ * unknown or not vault-backed. Shared by the store + the runner's discovery so the
+ * "is this a vault channel?" check is one implementation.
+ */
+export function vaultTransportFor(
+  channels: Map<string, Channel>,
+  name: string,
+): VaultTransport | null {
+  const t = channels.get(name)?.transport;
+  return t instanceof VaultTransport ? t : null;
+}
+
+/**
+ * The vault-native job store. Same read-all / upsert / remove interface the file
+ * store had, now backed by `#agent/job` vault notes via the channel's
+ * `VaultTransport`. Each method resolves the target channel's vault transport (the
+ * channel carries the vault binding + write token) and delegates the I/O to it.
+ *
+ * `listAll` queries every UNIQUE vault among the live vault-channels once and maps
+ * each job note to a `Job`, routing by `metadata.channel`. A job note whose
+ * `channel` no longer names a live vault channel is still RETURNED (so the API/UI
+ * can show + let the operator delete a stale job), but the runner's discovery
+ * (which composes on top) skips firing it.
+ */
+export class VaultJobStore {
+  constructor(private readonly channels: Map<string, Channel>) {}
+
+  /**
+   * List all scheduled jobs across every vault the live channels point at. We
+   * query each DISTINCT vault transport once (dedup by vault URL + name), then map
+   * job notes to `Job`s. A note read from one vault may target ANY channel on that
+   * vault (routing is by `metadata.channel`), so we keep every well-formed job
+   * note. De-dup by job id across vaults isn't needed — ids are namespaced by the
+   * channel's vault in practice — but if two notes share an id we keep both (the
+   * runner routes each by its own `channel`).
+   */
+  async listAll(): Promise<Job[]> {
+    // Dedup the vaults we query by vault IDENTITY (origin + name), NOT transport
+    // instance: many channels each construct their OWN VaultTransport pointing at the
+    // SAME vault, so instance-identity dedup misses and the same job notes come back
+    // once per channel sharing that vault. Key on `vaultKey()`. (Caught live
+    // 2026-06-18: one job listed 3x with three channels on the default vault.)
+    const seen = new Set<string>();
+    const transports: VaultTransport[] = [];
+    for (const ch of this.channels.values()) {
+      if (ch.transport instanceof VaultTransport && !seen.has(ch.transport.vaultKey())) {
+        seen.add(ch.transport.vaultKey());
+        transports.push(ch.transport);
+      }
+    }
+    const jobs: Job[] = [];
+    for (const t of transports) {
+      const notes = await t.listJobNotes();
+      for (const n of notes) {
+        jobs.push({
+          id: n.id, // the operator-facing slug (metadata.jobId)
+          noteId: n.noteId, // the vault note id/path — for PATCH/DELETE
+          channel: n.channel,
+          message: n.message,
+          schedule: { cron: n.cron, ...(n.tz ? { tz: n.tz } : {}) },
+          enabled: n.enabled,
+          createdAt: n.createdAt ?? "",
+          ...(n.lastRunAt ? { lastRunAt: n.lastRunAt } : {}),
+          ...(n.lastStatus ? { lastStatus: n.lastStatus } : {}),
+        });
+      }
+    }
+    return jobs;
+  }
+
+  /**
+   * Create or replace a job (by slug id) as a `#agent/job` note in its target
+   * channel's vault. Throws if the target channel isn't a live vault channel
+   * (the API validates this first, so it's a guard, not the primary check).
+   * Returns the persisted job with its `noteId` filled in (the `id` stays the slug).
+   */
+  async upsert(job: Job): Promise<Job> {
+    const t = vaultTransportFor(this.channels, job.channel);
+    if (!t) {
+      throw new Error(`cannot store job "${job.id}": channel "${job.channel}" is not a live vault channel`);
+    }
+    const { id: noteId } = await t.upsertJobNote({
+      id: job.id,
+      message: job.message,
+      channel: job.channel,
+      cron: job.schedule.cron,
+      ...(job.schedule.tz ? { tz: job.schedule.tz } : {}),
+      enabled: job.enabled,
+      createdAt: job.createdAt,
+      ...(job.lastRunAt ? { lastRunAt: job.lastRunAt } : {}),
+      ...(job.lastStatus ? { lastStatus: job.lastStatus } : {}),
+    });
+    return { ...job, noteId }; // id stays the slug; noteId addresses the persisted note.
+  }
+
+  /**
+   * Delete a job by its vault note id/path. The job lives in ITS channel's vault,
+   * so we need that channel to resolve the right transport. The API passes the
+   * job's `noteId` + channel (it has the job in hand from a prior list). Throws on
+   * a non-ok vault response.
+   */
+  async remove(noteId: string, channel: string): Promise<void> {
+    const t = vaultTransportFor(this.channels, channel);
+    if (!t) {
+      throw new Error(`cannot delete job in channel "${channel}": not a live vault channel`);
+    }
+    await t.deleteJobNote(noteId);
+  }
+
+  /**
+   * PATCH a job's bookkeeping (lastRunAt / lastStatus / enabled) onto its vault
+   * note. Used by the runner after a fire. Throws on a non-ok vault response (the
+   * runner swallows it — status persistence is best-effort).
+   */
+  async patch(
+    noteId: string,
+    channel: string,
+    fields: { lastRunAt?: string; lastStatus?: string; enabled?: boolean },
+  ): Promise<void> {
+    const t = vaultTransportFor(this.channels, channel);
+    if (!t) {
+      throw new Error(`cannot patch job in channel "${channel}": not a live vault channel`);
+    }
+    await t.patchJobNote(noteId, fields);
+  }
+}

package/src/mcp-http.test.ts

@@ -0,0 +1,265 @@
+/**
+ * HTTP MCP tests — the per-channel session registry, the wake push, write-scope
+ * enforcement on tool dispatch, and the daemon's /mcp/<channel> auth gate.
+ *
+ * Like daemon.test.ts these need NO live hub: the no-token path in requireScope
+ * short-circuits before any JWKS fetch, and the registry/push/tool tests drive
+ * the in-memory session set directly with fake servers + a fake transport.
+ */
+import { describe, test, expect, afterEach, beforeAll, afterAll } from "bun:test";
+import {
+  pushToChannel,
+  pushPermissionVerdict,
+  mcpSessionCount,
+  assertMcpSdkStreamContract,
+  _resetSessionsForTest,
+} from "./mcp-http.ts";
+import { createFetchHandler } from "./daemon.ts";
+import { ClientRegistry } from "./routing.ts";
+import { HttpUiTransport } from "./transports/http-ui.ts";
+import type { Channel } from "./registry.ts";
+import type { Transport, ReplyArgs } from "./transport.ts";
+
+// ---------------------------------------------------------------------------
+// Registry + wake — drive the session set directly via a registration shim.
+//
+// pushToChannel iterates the channel's session set and calls
+// server.notification. We register fake sessions by reaching the same internal
+// maps the way handleMcp's onsessioninitialized would. Since those maps are
+// module-private, we exercise them through the public surface: register via a
+// tiny test-only re-entry that mirrors registerSession. To keep this hermetic
+// without exporting internals, we register by spinning handleMcp is overkill;
+// instead we assert push reaches a registered session through a captured
+// server.notification. We use the exported _registerForTest below.
+// ---------------------------------------------------------------------------
+
+import { _registerSessionForTest, _unregisterSessionForTest } from "./mcp-http.ts";
+
+interface FakeServer {
+  notes: Array<{ method: string; params: unknown }>;
+}
+
+function fakeSession(): { server: { notification: (n: unknown) => void }; captured: FakeServer } {
+  const captured: FakeServer = { notes: [] };
+  const server = {
+    notification(n: unknown) {
+      captured.notes.push(n as { method: string; params: unknown });
+    },
+  };
+  return { server, captured };
+}
+
+afterEach(() => {
+  _resetSessionsForTest();
+});
+
+describe("per-channel MCP session registry + wake push", () => {
+  test("pushToChannel reaches a session on A and NOT one on B", () => {
+    const a = fakeSession();
+    const b = fakeSession();
+    _registerSessionForTest("A", "sid-a", a.server as never, ["agent:read", "agent:write"]);
+    _registerSessionForTest("B", "sid-b", b.server as never, ["agent:read"]);
+
+    const delivered = pushToChannel("A", "hello A", { foo: "bar" });
+    expect(delivered).toBe(1);
+    expect(a.captured.notes).toHaveLength(1);
+    expect(a.captured.notes[0]!.method).toBe("notifications/claude/agent");
+    expect((a.captured.notes[0]!.params as { content: string }).content).toBe("hello A");
+    // Source is stamped + caller meta merged.
+    expect((a.captured.notes[0]!.params as { meta: Record<string, string> }).meta).toMatchObject({
+      source: "parachute-agent",
+      foo: "bar",
+    });
+    // B got nothing.
+    expect(b.captured.notes).toHaveLength(0);
+  });
+
+  test("two sessions on the same channel both get the wake", () => {
+    const a1 = fakeSession();
+    const a2 = fakeSession();
+    _registerSessionForTest("A", "sid-a1", a1.server as never, ["agent:read"]);
+    _registerSessionForTest("A", "sid-a2", a2.server as never, ["agent:read"]);
+    expect(mcpSessionCount("A")).toBe(2);
+    const delivered = pushToChannel("A", "broadcast", {});
+    expect(delivered).toBe(2);
+    expect(a1.captured.notes).toHaveLength(1);
+    expect(a2.captured.notes).toHaveLength(1);
+  });
+
+  test("pushPermissionVerdict pushes the permission method", () => {
+    const a = fakeSession();
+    _registerSessionForTest("A", "sid-a", a.server as never, ["agent:read"]);
+    const delivered = pushPermissionVerdict("A", { request_id: "r1", behavior: "allow" });
+    expect(delivered).toBe(1);
+    expect(a.captured.notes[0]!.method).toBe("notifications/claude/agent/permission");
+    expect(a.captured.notes[0]!.params).toMatchObject({ request_id: "r1", behavior: "allow" });
+  });
+
+  test("push to an unknown channel delivers to nobody (0)", () => {
+    expect(pushToChannel("nope", "x", {})).toBe(0);
+    expect(pushPermissionVerdict("nope", { request_id: "r", behavior: "deny" })).toBe(0);
+  });
+
+  test("a streamless session (registered, no live GET stream) is NOT counted as delivered", () => {
+    // The bug this guards: a session that POSTed `initialize` but hasn't opened (or
+    // has dropped) its standalone GET stream is registered, but the SDK silently
+    // drops any notification to it. If pushToChannel counted it, the daemon would
+    // advance the channel's delivery mark and the message would be lost.
+    const a = fakeSession();
+    _registerSessionForTest("A", "sid-streamless", a.server as never, ["agent:read"], {
+      streamless: true,
+    });
+    expect(mcpSessionCount("A")).toBe(1); // it IS registered…
+    expect(pushToChannel("A", "into the void", {})).toBe(0); // …but NOT deliverable
+    expect(a.captured.notes).toHaveLength(0); // not even attempted
+    // Permission verdicts honor the same gate.
+    expect(pushPermissionVerdict("A", { request_id: "r", behavior: "allow" })).toBe(0);
+  });
+
+  test("pushToChannel counts only the live-stream sessions in a mixed set", () => {
+    const live = fakeSession();
+    const dead = fakeSession();
+    _registerSessionForTest("A", "sid-live", live.server as never, ["agent:read"]);
+    _registerSessionForTest("A", "sid-streamless", dead.server as never, ["agent:read"], {
+      streamless: true,
+    });
+    expect(mcpSessionCount("A")).toBe(2); // both registered
+    expect(pushToChannel("A", "hi", {})).toBe(1); // only the one with a live stream
+    expect(live.captured.notes).toHaveLength(1);
+    expect(dead.captured.notes).toHaveLength(0);
+  });
+
+  test("the installed MCP SDK still keys the standalone GET stream as we expect (contract guard)", () => {
+    // If this fails, the SDK renamed the internal sessionHasLivePushStream reads —
+    // HTTP-MCP delivery would silently break. Catch it here, not in production.
+    expect(assertMcpSdkStreamContract()).toBe(true);
+  });
+
+  test("mcpSessionCount tracks registration + reset", () => {
+    expect(mcpSessionCount("A")).toBe(0);
+    const a = fakeSession();
+    _registerSessionForTest("A", "sid-a", a.server as never, ["agent:read"]);
+    expect(mcpSessionCount("A")).toBe(1);
+    _resetSessionsForTest();
+    expect(mcpSessionCount("A")).toBe(0);
+  });
+
+  test("unregister cleans up the session and drops the empty channel set (no leak)", () => {
+    _registerSessionForTest("A", "sid-a1", fakeSession().server as never, ["agent:read"]);
+    _registerSessionForTest("A", "sid-a2", fakeSession().server as never, ["agent:read"]);
+    expect(mcpSessionCount("A")).toBe(2);
+    _unregisterSessionForTest("A", "sid-a1");
+    expect(mcpSessionCount("A")).toBe(1); // the other session survives
+    _unregisterSessionForTest("A", "sid-a2");
+    expect(mcpSessionCount("A")).toBe(0); // empty set removed — no orphaned channel entry
+    // a push to the now-cleaned channel reaches nobody
+    expect(pushToChannel("A", "hi", {})).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tool dispatch — a reply tool call routes to the channel's transport.
+// ---------------------------------------------------------------------------
+
+describe("tool dispatch routes to the channel's transport + enforces write scope", () => {
+  function fakeTransport(): { transport: Transport; replies: ReplyArgs[] } {
+    const replies: ReplyArgs[] = [];
+    const transport: Transport = {
+      kind: "fake",
+      async start() {},
+      async stop() {},
+      async reply(args: ReplyArgs) {
+        replies.push(args);
+        return { sent: ["msg-1"] };
+      },
+    };
+    return { transport, replies };
+  }
+
+  test("a write-scoped reply call reaches transport.reply with the channel + args", async () => {
+    const { transport, replies } = fakeTransport();
+    const { callReplyTool } = await import("./mcp-http.ts");
+    const result = await callReplyTool("A", transport, ["agent:read", "agent:write"], {
+      text: "hi there",
+      chat_id: "42",
+    });
+    expect(result.isError).toBeUndefined();
+    expect(replies).toHaveLength(1);
+    expect(replies[0]).toMatchObject({ channel: "A", text: "hi there", meta: { chat_id: "42" } });
+  });
+
+  test("a read-only token cannot call reply (write scope enforced)", async () => {
+    const { transport, replies } = fakeTransport();
+    const { callReplyTool } = await import("./mcp-http.ts");
+    const result = await callReplyTool("A", transport, ["agent:read"], { text: "blocked" });
+    expect(result.isError).toBe(true);
+    expect(replies).toHaveLength(0);
+    expect((result.content[0] as { text: string }).text).toContain("agent:write");
+  });
+
+  test("DUAL-ACCEPT: a pre-rename token with the LEGACY channel:write scope can still call reply", async () => {
+    // The write-tool gate must dual-accept (grantsScope), not raw-includes — else
+    // a pre-rename token connects + is woken but silently can't send (channel#…).
+    const { transport, replies } = fakeTransport();
+    const { callReplyTool } = await import("./mcp-http.ts");
+    const result = await callReplyTool("A", transport, ["channel:read", "channel:write"], {
+      text: "legacy-send",
+    });
+    expect(result.isError).toBeUndefined();
+    expect(replies).toHaveLength(1);
+    expect(replies[0]).toMatchObject({ channel: "A", text: "legacy-send" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Daemon auth gate — POST /mcp/<channel> with no bearer → 401 (pre-JWKS).
+// ---------------------------------------------------------------------------
+
+describe("daemon /mcp/<channel> auth gate", () => {
+  let server: ReturnType<typeof Bun.serve>;
+  let base: string;
+
+  beforeAll(async () => {
+    const registry = new ClientRegistry();
+    const transport = new HttpUiTransport({ channel: "ui1" });
+    await transport.start({ channel: "ui1", emit: () => {}, emitPermissionVerdict: () => {} });
+    const channels = new Map<string, Channel>([
+      ["ui1", { name: "ui1", transport, entry: { name: "ui1", transport: "http-ui" } }],
+    ]);
+    server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      idleTimeout: 0,
+      fetch: createFetchHandler(channels, registry),
+    });
+    base = `http://127.0.0.1:${server.port}`;
+  });
+
+  afterAll(() => {
+    server.stop(true);
+  });
+
+  test("POST /mcp/ui1 with an initialize body and no bearer → 401", async () => {
+    const res = await fetch(`${base}/mcp/ui1`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "t", version: "0" } },
+      }),
+    });
+    expect(res.status).toBe(401);
+    expect(((await res.json()) as { error: string }).error).toBe("unauthorized");
+  });
+
+  test("POST /mcp/unknown-channel → 404 (channel miss, before auth body)", async () => {
+    const res = await fetch(`${base}/mcp/does-not-exist`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }),
+    });
+    expect(res.status).toBe(404);
+  });
+});