@fdcn/sourcefed 0.3.2 → 0.3.5

package/dist/data/core/references/commands.md

@@ -14,7 +14,7 @@ sourcefed monitor start --id ID [--target-kind KIND] [--target-id ID]
 sourcefed monitor remove --id ID --yes [--target-kind KIND] [--target-id ID]
 sourcefed monitor events [--target-kind KIND] [--target-id ID]
 sourcefed monitor follow [--target-kind KIND] [--target-id ID]
-sourcefed monitor ack --event-id ID[,ID...] [--target-kind KIND] [--target-id ID]
+sourcefed monitor ack --event-id ID [--event-id ID...] [--target-kind KIND] [--target-id ID]
 sourcefed monitor sources
 sourcefed skills [list]                     List bundled skills
 sourcefed skills get <name> [--full]        Output skill content (--full adds references)

package/dist/guidance.md

@@ -1,71 +1,20 @@
-# sourcefed — monitoring guidance
+# sourcefed monitors
 
-sourcefed is a monitor service. It lets you create **monitors** that watch a Jira issue, GitHub
-PR, or Slack thread and route NEW events into the host session where the monitor was created.
-The OpenCode and Pi adapters drive the Sourcefed daemon client (`@sourcefed/daemon`) for
-monitor tools and event delivery; the same daemon can be served through MCP (`@sourcefed/mcp`)
-or driven directly by the CLI.
+Monitors watch a Jira issue, GitHub PR, or Slack thread and bring new events into this session.
 
-All transports speak the same daemon JSON protocol over HTTP (`POST /rpc` +
-`GET /events` SSE). The MCP adapter adds the 2026 resource-subscription flow
-(`subscriptions/listen`, `notifications/resources/updated`, `monitor_events_ack`)
-on top. When `SOURCEFED_DAEMON_URL` is unset, the OpenCode and Pi adapters
-spawn one local HTTP daemon automatically (if none is running) and connect to it.
+Create one with `monitor_create` when:
 
-## When to create a monitor
+- you work on a Jira ticket: `{ name: "<key>", sourceType: "jira", issueKey: "PROJ-123" }`
+  (new comments, edits, status, assignee, priority, labels);
+- your branch has a PR: `{ name: "<pr>", sourceType: "github", repo: "owner/name", prNumber: 42 }`
+  (reviews, comments, CI failures, conflicts, merge or close);
+- you were given a Slack thread: `{ name: "<thread>", sourceType: "slack", threadUrl: "<url>" }`
+  (new messages; read-only, never replies).
 
-- **You found or are working on a Jira ticket** → create a Jira monitor for its issue key. You
-  will be notified of new comments, description edits, and summary/status/assignee/priority/label changes.
-- **You are on a branch with an active PR (or just opened one)** → create a GitHub monitor for
-  `repo#prNumber`. You will be notified of new reviews (including bot reviews), PR and
-  line-level comments, CI failures, merge conflicts, and the PR being merged or closed.
-- **You were given a Slack thread** → create a Slack monitor for the thread URL. It is
-  detect-only: it reads new messages and routes notifications into this session, but never replies.
+Keep the default `pollIntervalSec` unless the work is time-sensitive (min 15).
+`monitor_list`, `monitor_status { id }` and `monitor_stop { id }` act on this session's monitors.
+GitHub monitors end when the PR merges.
 
-## How to create one
-
-Use the `monitor_create` tool:
-
-- Jira: `monitor_create({ name: "<key>", sourceType: "jira", issueKey: "PROJ-12345" })`
-- GitHub: `monitor_create({ name: "<pr>", sourceType: "github", repo: "owner/name", prNumber: 42 })`
-- Slack: `monitor_create({ name: "<thread>", sourceType: "slack", threadUrl: "<slack-thread-url>" })`
-
-GitHub and Slack use webhook delivery when configured and fall back to polling when unavailable.
-Jira always uses polling. Slack monitors are
-always detect-only and never reply. You can lower
-`pollIntervalSec` (min 15) for time-sensitive work, but prefer the default to avoid hammering APIs.
-Actionable events trigger an agent turn. Stable all-passing CI is suppressed to avoid notification noise; other informational events are added as context only.
-
-The abstract `Monitor` consolidates transport fallback and recovery and composes whichever
-generic `PollMonitor` and `WebhookMonitor` transports a source exposes as class attributes.
-Each provider is its own package (`@sourcefed/provider-{jira,github,slack}`) with monitor and
-event modules; the built-in registry (`SOURCE_MAP`) is composed by the daemon, which imports
-the provider packages directly. Jira exposes only polling;
-GitHub and Slack expose both. Do not add source-specific transport branches to tools,
-scheduling, or the daemon.
-
-## Skills
-
-The CLI bundles skills that teach agents how to use sourcefed, in the agent-browser style: a
-thin discovery stub points at CLI-served content that always matches the installed version.
-
-```bash
-sourcefed skills           # list available skills
-sourcefed skills get core  # load the core usage guide (--full adds references)
-```
-
-## Lifecycle
-
-- Monitors belong to the target that created them; list, status, and stop only affect that target's monitors.
-- `monitor_list` — see monitors created by this session.
-- `monitor_status { id }` — detail on one of this session's monitors.
-- `monitor_stop { id }` — stop routing events for one of this session's monitors.
-- GitHub monitors remove themselves after the PR is merged. Jira monitors remove themselves when
-  `SOURCEFED_JIRA_TERMINAL_STATUS` matches the issue status; leave it unset to disable automatic Jira removal.
-
-## When an event arrives
-
-Events are fed into your session as a message (e.g. a new review comment, a CI failure, a Jira
-status change). Treat it like any new input: read it, decide whether it needs action, and act
-(or tell the user it needs a decision). If the event is non-actionable (e.g. CI all-passing),
-acknowledge it and move on — do not fabricate work from it.
+An event arrives as a message. Act on it if it needs action, or tell the user it needs a
+decision; acknowledge an informational one (such as CI passing) and move on. Never invent work
+from it. `sourcefed skills get core` has the full guide.

package/dist/mcp.js

@@ -1,7 +1,7 @@
 import {
   decodeTarget,
   encodeTarget
-} from "./chunk-QPDTUNFA.js";
+} from "./chunk-X3BZSHKZ.js";
 import {
   __export
 } from "./chunk-MLKGABMK.js";

package/dist/opencode.js

@@ -1,10 +1,13 @@
+import {
+  eventToText
+} from "./chunk-BNLZQKEB.js";
 import {
   SOURCE_TYPES,
   connectDaemonClient,
   daemonCommand,
   daemonEnvironment,
   spawnLocalDaemon
-} from "./chunk-QPDTUNFA.js";
+} from "./chunk-X3BZSHKZ.js";
 import "./chunk-MLKGABMK.js";
 
 // packages/sourcefed/src/server.ts
@@ -18,26 +21,74 @@ import { Plugin } from "@opencode/plugin";
 // adapters/opencode/bridge.ts
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { Rpc } from "@opencode/plugin";
+var TARGET_KIND = "opencode-session";
+var GATE_TIMEOUT_MS = 3e3;
+var RESUBSCRIBE_MS = 15e3;
+var ChauffeurGate = Rpc.define({
+  id: "chauffeur",
+  methods: {
+    gate: {
+      input: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          // The monitor that produced the event, so the gate knows what it watches.
+          monitorID: { type: "string" },
+          source: { type: "string" },
+          kind: { type: "string" },
+          summary: { type: "string" },
+          body: { type: "string" },
+          actionable: { type: "boolean" }
+        },
+        required: ["sessionID", "source", "kind", "summary", "actionable"]
+      },
+      output: {
+        type: "object",
+        properties: { deliver: { type: "boolean" } },
+        required: ["deliver"]
+      }
+    }
+  },
+  events: {}
+});
 var activeBridge;
 var OpenCodeBridge = class {
-  constructor(session) {
+  constructor(session, rpc) {
     this.session = session;
+    this.rpc = rpc;
   }
   daemon;
   listeners = /* @__PURE__ */ new Map();
   lastAttemptAt = 0;
   lastError;
+  timer;
+  /**
+   * Chauffeur or the CLI can create a monitor for a session here at any time,
+   * without this bridge's tools, so check for new targets periodically too.
+   */
   async start() {
     await this.ensureDaemon();
+    this.timer = setInterval(() => void this.refresh(), RESUBSCRIBE_MS);
+    this.timer.unref?.();
   }
   async ensureTarget(sessionID) {
     await this.ensureDaemon();
-    if (this.listeners.has(sessionID)) return;
-    const target = this.target(sessionID);
-    const listener = await this.daemon.subscribe(target, async (events) => {
+    const existing = this.listeners.get(sessionID);
+    if (existing) {
+      await existing;
+      return;
+    }
+    const pending = this.daemon.subscribe(this.target(sessionID), async (events) => {
       await this.routeEvents(events);
     });
-    this.listeners.set(sessionID, listener);
+    this.listeners.set(sessionID, pending);
+    try {
+      await pending;
+    } catch (error) {
+      this.listeners.delete(sessionID);
+      throw error;
+    }
   }
   async callTool(name, arguments_, sessionID) {
     await this.ensureDaemon();
@@ -48,52 +99,109 @@ var OpenCodeBridge = class {
     return this.daemon.request(name.replace(/_/g, "."), { ...arguments_, target: this.target(sessionID) });
   }
   async close() {
-    for (const listener of this.listeners.values()) await listener.close();
+    clearInterval(this.timer);
+    this.timer = void 0;
+    for (const pending of this.listeners.values()) await pending.then((listener) => listener.close(), () => void 0);
     this.listeners.clear();
     await this.daemon?.close();
     this.daemon = void 0;
   }
+  async refresh() {
+    if (!this.daemon) return this.ensureDaemon();
+    await this.resubscribe();
+  }
   async ensureDaemon() {
     if (this.daemon) return;
     if (Date.now() - this.lastAttemptAt < 15e3) return;
     this.lastAttemptAt = Date.now();
     try {
-      const url = process.env.SOURCEFED_DAEMON_URL;
-      if (url) {
-        this.daemon = await connectDaemonClient({ name: "sourcefed-opencode", url });
-        return;
-      }
-      const local = daemonCommand(cliEntry());
-      const spawned = await spawnLocalDaemon({
-        command: local.command,
-        args: local.args,
-        env: daemonEnvironment()
-      });
-      this.daemon = await connectDaemonClient({ name: "sourcefed-opencode", url: spawned.url });
+      this.daemon = await connectDaemon();
+      void this.resubscribe();
     } catch (error) {
       this.lastError = error instanceof Error ? error.message : String(error);
       console.error(`[sourcefed] daemon unavailable: ${this.lastError}`);
     }
   }
-  // V2 `session.prompt` has no model field — the model is a session property and
-  // prompting does not reset it, so no model-reuse dance is needed. Actionable
-  // events prompt the agent; non-actionable ones inject a synthetic message that
-  // lands in the transcript without triggering a reply.
+  /**
+   * Monitors outlive this process, so after a restart nothing listens for their
+   * sessions until something subscribes. Subscribe every session that has an
+   * enabled monitor and still exists here; a deleted session is skipped, since
+   * delivering to it would fail and retry forever.
+   */
+  async resubscribe() {
+    try {
+      const { targets } = await this.daemon.request("monitor.targets", { kind: TARGET_KIND });
+      await Promise.all(targets.map((target) => this.resubscribeTarget(target.id)));
+    } catch (error) {
+      console.error(`[sourcefed] resubscribe failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async resubscribeTarget(sessionID) {
+    if (this.listeners.has(sessionID)) return;
+    const exists = await this.session.get({ sessionID }).then(() => true, () => false);
+    if (!exists) return;
+    await this.ensureTarget(sessionID).catch((error) => {
+      console.error(`[sourcefed] subscribe ${sessionID} failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+  }
+  // Every event arrives as a synthetic message, never as a user prompt, so it is
+  // not mistaken for the user's own words. Actionable events resume an idle
+  // agent; the rest wait in the transcript for the next turn.
   async routeEvents(events) {
     for (const queued of events) {
       const sessionID = queued.target.id;
-      const text = eventText(queued.event);
-      if (queued.event.actionable) {
-        await this.session.prompt({ sessionID, text });
-      } else {
-        await this.session.synthetic({ sessionID, text });
-      }
+      if (!await this.admitted(sessionID, queued)) continue;
+      await this.session.synthetic({
+        sessionID,
+        text: eventToText(queued.event),
+        description: `sourcefed ${queued.event.kind}`,
+        metadata: { sourcefed: { eventID: queued.id, monitorID: queued.monitorID, kind: queued.event.kind } },
+        resume: queued.event.actionable
+      });
+    }
+  }
+  /**
+   * Ask Chauffeur's gate, when it runs in this process. Only an explicit
+   * `deliver: false` withholds the event; no gate, an error, or a slow answer
+   * delivers.
+   */
+  async admitted(sessionID, queued) {
+    if (!this.rpc) return true;
+    const { event } = queued;
+    try {
+      const source = event.source?.type;
+      const reply = await this.rpc(ChauffeurGate).gate(
+        {
+          sessionID,
+          monitorID: queued.monitorID,
+          source: typeof source === "string" ? source : "unknown",
+          kind: event.kind,
+          summary: event.summary,
+          body: event.body ?? "",
+          actionable: event.actionable
+        },
+        { signal: AbortSignal.timeout(GATE_TIMEOUT_MS) }
+      );
+      return reply.deliver !== false;
+    } catch {
+      return true;
     }
   }
   target(sessionID) {
-    return { kind: "opencode-session", id: sessionID };
+    return { kind: TARGET_KIND, id: sessionID };
   }
 };
+async function connectDaemon() {
+  const url = process.env.SOURCEFED_DAEMON_URL;
+  if (url) return connectDaemonClient({ name: "sourcefed-opencode", url });
+  const local = daemonCommand(cliEntry());
+  const spawned = await spawnLocalDaemon({
+    command: local.command,
+    args: local.args,
+    env: daemonEnvironment()
+  });
+  return connectDaemonClient({ name: "sourcefed-opencode", url: spawned.url });
+}
 function cliEntry() {
   const bundled = fileURLToPath(new URL("./cli.js", import.meta.url));
   if (existsSync(bundled)) return bundled;
@@ -106,12 +214,6 @@ function getOpenCodeBridge() {
   if (!activeBridge) throw new Error("Sourcefed OpenCode bridge is not initialized");
   return activeBridge;
 }
-function eventText(event) {
-  const header = `[sourcefed monitor] ${event.summary}`;
-  return event.body ? `${header}
-
-${event.body}` : header;
-}
 
 // adapters/opencode/tool-result.ts
 async function callMonitorTool(name, arguments_, sessionID) {
@@ -219,7 +321,7 @@ var monitor_stop_default = definition5;
 
 // adapters/opencode/index.ts
 async function setupSourcefed(ctx) {
-  const bridge = new OpenCodeBridge(ctx.session);
+  const bridge = new OpenCodeBridge(ctx.session, ctx.rpc);
   setOpenCodeBridge(bridge);
   await bridge.start();
   await ctx.tool.transform((editor) => {
@@ -238,12 +340,13 @@ var opencode_default = Plugin.define({
 
 // packages/sourcefed/src/server.ts
 var guidance = readFileSync(fileURLToPath2(new URL("./guidance.md", import.meta.url)), "utf8");
+var heading = guidance.split("\n", 1)[0] ?? guidance;
 var server_default = Plugin2.define({
   id: "sourcefed",
   async setup(ctx) {
     const cleanup = await setupSourcefed(ctx);
     await ctx.session.hook("context", (event) => {
-      if (!event.system.some((part) => part.type === "text" && part.text.includes("sourcefed"))) {
+      if (!event.system.some((part) => part.type === "text" && part.text.includes(heading))) {
         event.system.push({ type: "text", text: guidance });
       }
     });

package/dist/pi.js

@@ -1,9 +1,12 @@
+import {
+  eventToText
+} from "./chunk-BNLZQKEB.js";
 import {
   connectDaemonClient,
   daemonCommand,
   daemonEnvironment,
   spawnLocalDaemon
-} from "./chunk-QPDTUNFA.js";
+} from "./chunk-X3BZSHKZ.js";
 import "./chunk-MLKGABMK.js";
 
 // adapters/pi/src/index.ts
@@ -248,9 +251,7 @@ async function routeEvents(pi, events) {
   for (const queued of events) {
     await pi.sendMessage({
       customType: "sourcefed-monitor",
-      content: `[sourcefed monitor] ${queued.event.summary}${queued.event.body ? `
-
-${queued.event.body}` : ""}`,
+      content: eventToText(queued.event),
       display: true,
       details: { actionable: queued.event.actionable, eventID: queued.id }
     }, { triggerTurn: queued.event.actionable, deliverAs: "steer" });

package/dist.dts/adapters/opencode/bridge.d.ts

@@ -1,18 +1,40 @@
-import type { Plugin } from "@opencode/plugin";
+import { type Plugin } from "@opencode/plugin";
 type SessionDomain = Plugin.Context["session"];
+type RpcDomain = Plugin.Context["rpc"];
 export declare class OpenCodeBridge {
     private readonly session;
+    private readonly rpc?;
     private daemon?;
     private readonly listeners;
     private lastAttemptAt;
     private lastError;
-    constructor(session: SessionDomain);
+    private timer;
+    constructor(session: SessionDomain, rpc?: RpcDomain | undefined);
+    /**
+     * Chauffeur or the CLI can create a monitor for a session here at any time,
+     * without this bridge's tools, so check for new targets periodically too.
+     */
     start(): Promise<void>;
     ensureTarget(sessionID: string): Promise<void>;
     callTool(name: string, arguments_: Record<string, unknown>, sessionID: string): Promise<unknown>;
     close(): Promise<void>;
+    private refresh;
     private ensureDaemon;
+    /**
+     * Monitors outlive this process, so after a restart nothing listens for their
+     * sessions until something subscribes. Subscribe every session that has an
+     * enabled monitor and still exists here; a deleted session is skipped, since
+     * delivering to it would fail and retry forever.
+     */
+    private resubscribe;
+    private resubscribeTarget;
     private routeEvents;
+    /**
+     * Ask Chauffeur's gate, when it runs in this process. Only an explicit
+     * `deliver: false` withholds the event; no gate, an error, or a slow answer
+     * delivers.
+     */
+    private admitted;
     private target;
 }
 export declare function setOpenCodeBridge(bridge: OpenCodeBridge): void;

package/dist.dts/adapters/opencode/bridge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist.dts/packages/cli/src/utils/flags.d.ts

@@ -1 +1,3 @@
 export declare function flag(args: string[], name: string): string | undefined;
+/** Every value of a repeatable flag, in order: `--name a --name b` gives `["a", "b"]`. */
+export declare function flags(args: string[], name: string): string[];

package/dist.dts/packages/cli/src/utils/flags.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist.dts/packages/daemon/src/daemon.d.ts

@@ -19,6 +19,11 @@ export declare class SourcefedDaemon {
     webhook(request: Request): Promise<Response>;
     createMonitor(target: MonitorTarget, input: DaemonCreateInput): Promise<DaemonResult>;
     listMonitors(target: MonitorTarget): Promise<DaemonResult>;
+    /**
+     * Every target of `kind` with an enabled monitor, so a host that restarts can
+     * resubscribe the sessions whose monitors outlived it.
+     */
+    listTargets(kind: string): Promise<MonitorTarget[]>;
     getMonitor(target: MonitorTarget, id: string): Promise<DaemonResult>;
     stopMonitor(target: MonitorTarget, id: string): Promise<DaemonResult>;
     startMonitor(target: MonitorTarget, id: string): Promise<DaemonResult>;

package/dist.dts/packages/daemon/src/forward.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist.dts/packages/daemon/src/gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist.dts/packages/daemon/src/utils/forward.d.ts

@@ -0,0 +1,32 @@
+import type { MonitorEvent, MonitorEventSink, MonitorRecord } from "@fdcn/sourcefed/core";
+export type ForwardOptions = {
+    url: string;
+    token?: string;
+    fetch?: typeof fetch;
+};
+/** The JSON body POSTed for each delivered event. */
+export type ForwardedEvent = {
+    target: MonitorRecord["target"];
+    monitorID: string;
+    source: MonitorRecord["source"];
+    event: MonitorEvent;
+};
+/** `SOURCEFED_FORWARD_URL` (and optional `SOURCEFED_FORWARD_TOKEN`), when set. */
+export declare function forwardFromEnv(): ForwardOptions | undefined;
+/**
+ * Delivers to `inner`, then POSTs a copy of each delivered event to another
+ * local consumer. Forwarding never blocks or fails delivery.
+ */
+export declare class ForwardingEventSink implements MonitorEventSink {
+    private readonly inner;
+    private readonly options;
+    constructor(inner: MonitorEventSink, options: ForwardOptions);
+    deliver(input: {
+        monitor: MonitorRecord;
+        event: MonitorEvent;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    private forward;
+}

package/dist.dts/packages/daemon/src/utils/gate.d.ts

@@ -0,0 +1,33 @@
+import type { MonitorEvent, MonitorEventSink, MonitorRecord } from "@fdcn/sourcefed/core";
+export type GateOptions = {
+    url: string;
+    token?: string;
+    fetch?: typeof fetch;
+};
+/** The JSON body POSTed for each event; the gate replies `{ "deliver": boolean }`. */
+export type GatedEvent = {
+    target: MonitorRecord["target"];
+    monitorID: string;
+    source: MonitorRecord["source"];
+    event: MonitorEvent;
+};
+/** `SOURCEFED_GATE_URL` (and optional `SOURCEFED_GATE_TOKEN`), when set. */
+export declare function gateFromEnv(): GateOptions | undefined;
+/**
+ * Asks another local consumer whether each event should reach the session.
+ * Only an explicit `{ "deliver": false }` withholds it; a failed, slow, or
+ * unclear answer delivers, so the gate can never lose an event.
+ */
+export declare class GatedEventSink implements MonitorEventSink {
+    private readonly inner;
+    private readonly options;
+    constructor(inner: MonitorEventSink, options: GateOptions);
+    deliver(input: {
+        monitor: MonitorRecord;
+        event: MonitorEvent;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    private withheld;
+}

package/dist.dts/providers/slack/src/poll/utils/slack-api.d.ts

@@ -1,8 +1,16 @@
+type SlackUser = {
+    id: string;
+    name: string;
+    real_name: string;
+};
 export declare function fetchSlackThread(channelId: string, threadTs: string): Promise<{
     messages: any[];
-    users: any[];
-} | undefined>;
+    users: SlackUser[];
+}>;
 export declare function fetchSlackDm(channelId: string): Promise<{
     messages: any[];
-    users: any[];
-} | undefined>;
+    users: SlackUser[];
+}>;
+/** Forget the cached user list, so a test starts from an empty cache. */
+export declare function resetSlackUsers(): void;
+export {};

package/dist.dts/providers/slack/src/poll/utils/slack-api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fdcn/sourcefed",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "Live Jira, GitHub, and Slack monitoring for agent hosts: CLI, daemon, MCP server, and host plugins.",
   "license": "MIT",
   "type": "module",