@forwardimpact/outpost 3.0.3

package/src/scheduler.js

@@ -0,0 +1,195 @@
+/**
+ * Scheduler — cron matching, shouldWake logic, wake orchestration.
+ */
+
+/** Maximum time an agent can be "active" before being considered stale (35 min). */
+const MAX_AGENT_RUNTIME_MS = 35 * 60_000;
+
+// --- Cron matching (pure functions) ------------------------------------------
+
+/**
+ * @param {string} field
+ * @param {number} value
+ * @returns {boolean}
+ */
+export function matchField(field, value) {
+  if (field === "*") return true;
+  if (field.startsWith("*/")) return value % parseInt(field.slice(2)) === 0;
+  return field.split(",").some((part) => {
+    if (part.includes("-")) {
+      const [lo, hi] = part.split("-").map(Number);
+      return value >= lo && value <= hi;
+    }
+    return parseInt(part) === value;
+  });
+}
+
+/**
+ * @param {string} expr
+ * @param {Date} d
+ * @returns {boolean}
+ */
+export function cronMatches(expr, d) {
+  const [min, hour, dom, month, dow] = expr.trim().split(/\s+/);
+  return (
+    matchField(min, d.getMinutes()) &&
+    matchField(hour, d.getHours()) &&
+    matchField(dom, d.getDate()) &&
+    matchField(month, d.getMonth() + 1) &&
+    matchField(dow, d.getDay())
+  );
+}
+
+/**
+ * @param {Date} d
+ * @returns {number}
+ */
+export function floorToMinute(d) {
+  const t = d.getTime();
+  return t - (t % 60_000);
+}
+
+/**
+ * @param {Object} agent
+ * @param {Object} agentState
+ * @param {Date} now
+ * @returns {boolean}
+ */
+export function shouldWake(agent, agentState, now) {
+  if (agent.enabled === false) return false;
+  if (agentState.status === "active") return false;
+  const { schedule } = agent;
+  if (!schedule) return false;
+  const lastWoke = agentState.lastWokeAt
+    ? new Date(agentState.lastWokeAt)
+    : null;
+
+  if (schedule.type === "cron") {
+    if (lastWoke && floorToMinute(lastWoke) === floorToMinute(now))
+      return false;
+    return cronMatches(schedule.expression, now);
+  }
+  if (schedule.type === "interval") {
+    const ms = (schedule.minutes || 5) * 60_000;
+    return !lastWoke || now.getTime() - lastWoke.getTime() >= ms;
+  }
+  if (schedule.type === "once") {
+    return !agentState.lastWokeAt && now >= new Date(schedule.runAt);
+  }
+  return false;
+}
+
+/**
+ * @param {Object} schedule
+ * @param {Object} agentState
+ * @param {Date} now
+ * @returns {string|null}
+ */
+function nextWakeInterval(schedule, agentState, now) {
+  const ms = (schedule.minutes || 5) * 60_000;
+  const lastWoke = agentState.lastWokeAt
+    ? new Date(agentState.lastWokeAt)
+    : null;
+  if (!lastWoke) return now.toISOString();
+  return new Date(lastWoke.getTime() + ms).toISOString();
+}
+
+/**
+ * @param {Object} schedule
+ * @param {Date} now
+ * @returns {string|null}
+ */
+function nextWakeCron(schedule, now) {
+  const limit = 24 * 60;
+  const start = new Date(floorToMinute(now) + 60_000);
+  for (let i = 0; i < limit; i++) {
+    const candidate = new Date(start.getTime() + i * 60_000);
+    if (cronMatches(schedule.expression, candidate)) {
+      return candidate.toISOString();
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Object} agent
+ * @param {Object} agentState
+ * @param {Date} now
+ * @returns {string|null}
+ */
+export function computeNextWakeAt(agent, agentState, now) {
+  if (agent.enabled === false) return null;
+  const { schedule } = agent;
+  if (!schedule) return null;
+
+  if (schedule.type === "interval")
+    return nextWakeInterval(schedule, agentState, now);
+  if (schedule.type === "cron") return nextWakeCron(schedule, now);
+  if (schedule.type === "once")
+    return agentState.lastWokeAt ? null : schedule.runAt;
+  return null;
+}
+
+/**
+ * @param {Object} agentState
+ * @param {string} error
+ */
+export function failAgent(agentState, error) {
+  Object.assign(agentState, {
+    status: "failed",
+    startedAt: null,
+    lastWokeAt: new Date().toISOString(),
+    lastError: String(error).slice(0, 500),
+  });
+}
+
+// --- Scheduler class ---------------------------------------------------------
+
+/** Orchestrate periodic agent wakes by evaluating schedules and delegating to AgentRunner. */
+export class Scheduler {
+  #loadConfig;
+  #stateManager;
+  #agentRunner;
+  #log;
+
+  /**
+   * @param {Function} loadConfig - Returns scheduler config
+   * @param {import('./state-manager.js').StateManager} stateManager
+   * @param {import('./agent-runner.js').AgentRunner} agentRunner
+   * @param {Function} logFn
+   */
+  constructor(loadConfig, stateManager, agentRunner, logFn) {
+    if (!loadConfig) throw new Error("loadConfig is required");
+    if (!stateManager) throw new Error("stateManager is required");
+    if (!agentRunner) throw new Error("agentRunner is required");
+    if (!logFn) throw new Error("logFn is required");
+    this.#loadConfig = loadConfig;
+    this.#stateManager = stateManager;
+    this.#agentRunner = agentRunner;
+    this.#log = logFn;
+  }
+
+  /**
+   * Reset any agents exceeding max runtime, reload config, then wake each agent whose schedule is due.
+   */
+  async wakeDueAgents() {
+    const config = this.#loadConfig();
+    const state = this.#stateManager.load();
+    const now = new Date();
+
+    this.#stateManager.resetStaleAgents(
+      state,
+      { reason: "Exceeded maximum runtime", maxAge: MAX_AGENT_RUNTIME_MS },
+      this.#log,
+    );
+
+    let wokeAny = false;
+    for (const [name, agent] of Object.entries(config.agents)) {
+      if (shouldWake(agent, state.agents[name] || {}, now)) {
+        await this.#agentRunner.wake(name, agent, state, config.env);
+        wokeAny = true;
+      }
+    }
+    if (!wokeAny) this.#log("No agents due.");
+  }
+}

package/src/socket-server.js

@@ -0,0 +1,336 @@
+/**
+ * SocketServer — Unix socket IPC for daemon communication.
+ */
+
+import { createServer } from "node:net";
+import { createConnection } from "node:net";
+import { createLogger } from "@forwardimpact/libtelemetry";
+import {
+  existsSync,
+  unlinkSync,
+  chmodSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+
+const logger = createLogger("outpost");
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { computeNextWakeAt } from "./scheduler.js";
+
+/** Unix-socket IPC server that handles status queries, wake requests, and shutdown commands. */
+export class SocketServer {
+  #socketPath;
+  #agentRunner;
+  #stateManager;
+  #log;
+  #loadConfig;
+  #cacheDir;
+  #daemonStartedAt;
+  #server;
+
+  /**
+   * @param {string} socketPath
+   * @param {import('./scheduler.js').Scheduler} scheduler
+   * @param {import('./agent-runner.js').AgentRunner} agentRunner
+   * @param {import('./state-manager.js').StateManager} stateManager
+   * @param {Function} loadConfig
+   * @param {Function} logFn
+   * @param {string} cacheDir
+   * @param {number} daemonStartedAt
+   */
+  constructor(
+    socketPath,
+    scheduler,
+    agentRunner,
+    stateManager,
+    loadConfig,
+    logFn,
+    cacheDir,
+    daemonStartedAt,
+  ) {
+    if (!socketPath) throw new Error("socketPath is required");
+    if (!scheduler) throw new Error("scheduler is required");
+    if (!agentRunner) throw new Error("agentRunner is required");
+    if (!stateManager) throw new Error("stateManager is required");
+    if (!loadConfig) throw new Error("loadConfig is required");
+    if (!logFn) throw new Error("logFn is required");
+    if (!cacheDir) throw new Error("cacheDir is required");
+    this.#socketPath = socketPath;
+    this.#agentRunner = agentRunner;
+    this.#stateManager = stateManager;
+    this.#loadConfig = loadConfig;
+    this.#log = logFn;
+    this.#cacheDir = cacheDir;
+    this.#daemonStartedAt = daemonStartedAt;
+  }
+
+  /**
+   * @param {import('node:net').Socket} socket
+   * @param {Object} data
+   */
+  #send(socket, data) {
+    try {
+      socket.write(JSON.stringify(data) + "\n");
+    } catch {}
+  }
+
+  /**
+   * @param {string} p
+   * @returns {string}
+   */
+  #expandPath(p) {
+    return p.startsWith("~/") ? join(homedir(), p.slice(2)) : resolve(p);
+  }
+
+  /**
+   * Find the most recently modified file in a directory matching a filter.
+   * @param {string} dir
+   * @param {(name: string) => boolean} filter
+   * @returns {string|null}
+   */
+  #latestFileByMtime(dir, filter) {
+    const matches = readdirSync(dir).filter(filter);
+    if (matches.length === 0) return null;
+    let latest = join(dir, matches[0]);
+    let latestMtime = statSync(latest).mtimeMs;
+    for (let i = 1; i < matches.length; i++) {
+      const p = join(dir, matches[i]);
+      const mt = statSync(p).mtimeMs;
+      if (mt > latestMtime) {
+        latest = p;
+        latestMtime = mt;
+      }
+    }
+    return latest;
+  }
+
+  /**
+   * Resolve briefing file for an agent
+   * @param {string} agentName
+   * @param {Object} agentConfig
+   * @returns {string|null}
+   */
+  #resolveBriefingFile(agentName, agentConfig) {
+    const stateDir = join(this.#cacheDir, "state");
+    if (existsSync(stateDir)) {
+      const prefix = agentName.replace(/-/g, "_") + "_";
+      const found = this.#latestFileByMtime(
+        stateDir,
+        (f) => f.startsWith(prefix) && f.endsWith(".md"),
+      );
+      if (found) return found;
+    }
+
+    if (agentConfig.kb) {
+      const dir = join(
+        this.#expandPath(agentConfig.kb),
+        "knowledge",
+        "Briefings",
+      );
+      if (existsSync(dir)) {
+        const files = readdirSync(dir)
+          .filter((f) => f.endsWith(".md"))
+          .sort()
+          .reverse();
+        if (files.length > 0) return join(dir, files[0]);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * @param {import('node:net').Socket} socket
+   */
+  #handleStatusRequest(socket) {
+    const config = this.#loadConfig();
+    const state = this.#stateManager.load();
+    const now = new Date();
+    const agents = {};
+
+    for (const [name, agent] of Object.entries(config.agents)) {
+      const as = state.agents[name] || {};
+      agents[name] = {
+        enabled: agent.enabled !== false,
+        status: as.status || "never-woken",
+        lastWokeAt: as.lastWokeAt || null,
+        nextWakeAt: computeNextWakeAt(agent, as, now),
+        lastAction: as.lastAction || null,
+        lastDecision: as.lastDecision || null,
+        wakeCount: as.wakeCount || 0,
+        lastError: as.lastError || null,
+        kbPath: agent.kb ? this.#expandPath(agent.kb) : null,
+        briefingFile: this.#resolveBriefingFile(name, agent),
+      };
+      if (as.startedAt) agents[name].startedAt = as.startedAt;
+    }
+
+    this.#send(socket, {
+      type: "status",
+      uptime: this.#daemonStartedAt
+        ? Math.floor((Date.now() - this.#daemonStartedAt) / 1000)
+        : 0,
+      agents,
+    });
+  }
+
+  /**
+   * @param {import('node:net').Socket} socket
+   * @param {string} line
+   */
+  #handleMessage(socket, line) {
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      this.#send(socket, { type: "error", message: "Invalid JSON" });
+      return;
+    }
+
+    if (request.type === "status") return this.#handleStatusRequest(socket);
+
+    if (request.type === "shutdown") {
+      this.#log("Shutdown requested via socket.");
+      this.#send(socket, { type: "ack", command: "shutdown" });
+      socket.end();
+      this.#agentRunner.killActiveChildren();
+      process.exit(0);
+    }
+
+    if (request.type === "wake") {
+      if (!request.agent) {
+        this.#send(socket, { type: "error", message: "Missing agent name" });
+        return;
+      }
+      const config = this.#loadConfig();
+      const agent = config.agents[request.agent];
+      if (!agent) {
+        this.#send(socket, {
+          type: "error",
+          message: `Agent not found: ${request.agent}`,
+        });
+        return;
+      }
+      this.#send(socket, {
+        type: "ack",
+        command: "wake",
+        agent: request.agent,
+      });
+      const state = this.#stateManager.load();
+      this.#agentRunner
+        .wake(request.agent, agent, state, config.env)
+        .catch(() => {});
+      return;
+    }
+
+    this.#send(socket, {
+      type: "error",
+      message: `Unknown request type: ${request.type}`,
+    });
+  }
+
+  /**
+   * Remove any existing socket file, bind the server, and register SIGTERM/SIGINT handlers to kill active children before exit.
+   * @returns {import('node:net').Server}
+   */
+  start() {
+    try {
+      unlinkSync(this.#socketPath);
+    } catch {}
+
+    this.#server = createServer((socket) => {
+      let buffer = "";
+      socket.on("data", (data) => {
+        buffer += data.toString();
+        let idx;
+        while ((idx = buffer.indexOf("\n")) !== -1) {
+          const line = buffer.slice(0, idx).trim();
+          buffer = buffer.slice(idx + 1);
+          if (line) this.#handleMessage(socket, line);
+        }
+      });
+      socket.on("error", () => {});
+    });
+
+    this.#server.listen(this.#socketPath, () => {
+      chmodSync(this.#socketPath, 0o600);
+      this.#log(`Socket server listening on ${this.#socketPath}`);
+    });
+
+    this.#server.on("error", (err) => {
+      this.#log(`Socket server error: ${err.message}`);
+    });
+
+    const cleanup = () => {
+      this.#agentRunner.killActiveChildren();
+      this.#server.close();
+      try {
+        unlinkSync(this.#socketPath);
+      } catch {}
+      process.exit(0);
+    };
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+
+    return this.#server;
+  }
+
+  /**
+   * Stop the socket server
+   */
+  stop() {
+    if (this.#server) {
+      this.#server.close();
+    }
+    try {
+      unlinkSync(this.#socketPath);
+    } catch {}
+  }
+}
+
+/**
+ * Connect to the daemon socket and request graceful shutdown.
+ * @param {string} socketPath
+ * @returns {Promise<boolean>}
+ */
+export async function requestShutdown(socketPath) {
+  if (!existsSync(socketPath)) {
+    logger.info("Daemon not running (no socket).");
+    return false;
+  }
+
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => {
+      logger.info("Shutdown timed out.");
+      socket.destroy();
+      resolve(false);
+    }, 5000);
+
+    const socket = createConnection(socketPath, () => {
+      socket.write(JSON.stringify({ type: "shutdown" }) + "\n");
+    });
+
+    let buffer = "";
+    socket.on("data", (data) => {
+      buffer += data.toString();
+      if (buffer.includes("\n")) {
+        clearTimeout(timeout);
+        logger.info("Daemon stopped.");
+        socket.destroy();
+        resolve(true);
+      }
+    });
+
+    socket.on("error", () => {
+      clearTimeout(timeout);
+      logger.info("Daemon not running (connection refused).");
+      resolve(false);
+    });
+
+    socket.on("close", () => {
+      clearTimeout(timeout);
+      resolve(true);
+    });
+  });
+}

package/src/state-manager.js

@@ -0,0 +1,126 @@
+/**
+ * StateManager — load/save state.json, reset stale agents.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Persist and query agent scheduler state from a JSON file on disk. */
+export class StateManager {
+  #statePath;
+  #fs;
+
+  /**
+   * @param {string} statePath - Path to state.json
+   * @param {{ readFileSync: Function, writeFileSync: Function, mkdirSync: Function }} fs
+   */
+  constructor(statePath, fs) {
+    if (!statePath) throw new Error("statePath is required");
+    if (!fs) throw new Error("fs is required");
+    this.#statePath = statePath;
+    this.#fs = fs;
+  }
+
+  /**
+   * Read and parse state from disk; on any read or parse error, write a fresh empty state and return it.
+   * @returns {Object}
+   */
+  load() {
+    try {
+      const raw = JSON.parse(this.#fs.readFileSync(this.#statePath, "utf8"));
+      if (!raw || typeof raw !== "object" || !raw.agents) {
+        const state = { agents: {} };
+        this.save(state);
+        return state;
+      }
+      return raw;
+    } catch {
+      const state = { agents: {} };
+      this.save(state);
+      return state;
+    }
+  }
+
+  /**
+   * Save state to disk
+   * @param {Object} state
+   */
+  save(state) {
+    this.#fs.mkdirSync(dirname(this.#statePath), { recursive: true });
+    this.#fs.writeFileSync(
+      this.#statePath,
+      JSON.stringify(state, null, 2) + "\n",
+    );
+  }
+
+  /**
+   * Reset agents stuck in "active" state.
+   * @param {Object} state
+   * @param {{ reason: string, maxAge?: number }} opts
+   * @param {Function} logFn
+   * @returns {number} Number of agents reset
+   */
+  resetStaleAgents(state, { reason, maxAge }, logFn) {
+    let resetCount = 0;
+    for (const [name, as] of Object.entries(state.agents)) {
+      if (as.status !== "active") continue;
+      if (maxAge && as.startedAt) {
+        const elapsed = Date.now() - new Date(as.startedAt).getTime();
+        if (elapsed < maxAge) continue;
+      }
+      logFn(`Resetting stale agent: ${name} (${reason})`);
+      Object.assign(as, {
+        status: "interrupted",
+        startedAt: null,
+        lastError: reason,
+      });
+      resetCount++;
+    }
+    if (resetCount > 0) this.save(state);
+    return resetCount;
+  }
+
+  /**
+   * Parse Decision:/Action: lines from agent output and update state.
+   * @param {Object} agentState
+   * @param {string} stdout
+   * @param {string} agentName
+   * @param {string} cacheDir - Cache directory for state files
+   */
+  updateAgentState(agentState, stdout, agentName, cacheDir) {
+    const lines = stdout.split("\n");
+    const decisionLine = lines.find((l) => l.startsWith("Decision:"));
+    const actionLine = lines.find((l) => l.startsWith("Action:"));
+
+    Object.assign(agentState, {
+      status: "idle",
+      startedAt: null,
+      lastWokeAt: new Date().toISOString(),
+      lastDecision: decisionLine
+        ? decisionLine.slice(10).trim()
+        : stdout.slice(0, 200),
+      lastAction: actionLine ? actionLine.slice(8).trim() : null,
+      lastError: null,
+      wakeCount: (agentState.wakeCount || 0) + 1,
+    });
+
+    // Save output as briefing fallback
+    const stateDir = join(cacheDir, "state");
+    this.#fs.mkdirSync(stateDir, { recursive: true });
+    const prefix = agentName.replace(/-/g, "_");
+    this.#fs.writeFileSync(join(stateDir, `${prefix}_last_output.md`), stdout);
+  }
+}
+
+/**
+ * Create a StateManager with real fs dependencies
+ * @param {string} statePath
+ * @returns {StateManager}
+ */
+export function createStateManager(statePath) {
+  return new StateManager(statePath, {
+    readFileSync,
+    writeFileSync,
+    mkdirSync,
+  });
+}

package/templates/.claude/agents/chief-of-staff.md

@@ -0,0 +1,58 @@
+---
+name: chief-of-staff
+description: >
+  The user's executive assistant. Creates daily briefings that synthesize
+  email, calendar, and knowledge graph state into actionable priorities.
+  Woken at key moments (morning, evening) by the Outpost scheduler.
+model: sonnet
+permissionMode: bypassPermissions
+skills:
+  - weekly-update
+---
+
+You are the chief of staff — the user's executive assistant. Each wake:
+synthesize what matters across email, calendar, and the knowledge graph into a
+single briefing.
+
+## Inputs
+
+Read all five sibling agents' triage files before writing — these are the
+authoritative current-state summaries:
+
+- `~/.cache/fit/outpost/state/postman_triage.md`
+- `~/.cache/fit/outpost/state/concierge_triage.md`
+- `~/.cache/fit/outpost/state/librarian_triage.md`
+- `~/.cache/fit/outpost/state/recruiter_triage.md`
+- `~/.cache/fit/outpost/state/head_hunter_triage.md`
+
+Plus directly: `knowledge/Goals/`, `knowledge/Priorities/`, `drafts/`,
+`~/.cache/fit/outpost/apple_calendar/`, and unchecked `- [ ]` items in
+`knowledge/`.
+
+## Routing
+
+| Trigger        | Output                                             |
+| -------------- | -------------------------------------------------- |
+| Before noon    | `knowledge/Briefings/{YYYY-MM-DD}-morning.md`      |
+| Noon or later  | `knowledge/Briefings/{YYYY-MM-DD}-evening.md`      |
+| Monday morning | also run `weekly-update` for the week's priorities |
+
+A briefing covers: today's schedule with prep status, top three priority actions
+linked to `[[Priorities/...]]`, goal progress, inbox snapshot (urgent / awaiting
+reply), open commitments, recruitment pipeline summary, and a heads-up section.
+Evening briefings replace "Priority Actions" with "What Happened Today" and
+"Still Outstanding".
+
+## Scope
+
+- This agent **synthesizes** — never duplicate work the other agents have
+  already triaged. Cite their findings, don't re-derive them.
+- Do not act on email, candidates, or transcripts directly — those belong to the
+  postman, recruiter, and concierge.
+
+## Output
+
+```
+Decision: {morning/evening} briefing — {key insight about today}
+Action: Created knowledge/Briefings/{YYYY-MM-DD}-{morning|evening}.md
+```