@agentproto/runtime 0.1.0

package/dist/heartbeat-COGpMrJS.d.ts

@@ -0,0 +1,120 @@
+import { ConversationStore } from './conversations.js';
+
+/**
+ * In-process event bus for the runtime gateway. Anything the daemon
+ * does that an external observer might want to watch (heartbeat fired,
+ * conversation turn appended, boot completed, …) flows through here.
+ *
+ * The HTTP server's `/events` SSE stream subscribes to it and forwards
+ * each event as a `data: <json>\n\n` frame. Tests and embedded usage
+ * subscribe directly via `events.on()`.
+ */
+interface BootEvent {
+    type: "boot";
+    at: string;
+    workspace: string;
+    registered: readonly string[];
+}
+interface HeartbeatFiredEvent {
+    type: "heartbeat-fired";
+    at: string;
+    agent: string;
+    conversationId: string;
+    prompt: string;
+    reply: string;
+    durationMs: number;
+}
+interface HeartbeatErrorEvent {
+    type: "heartbeat-error";
+    at: string;
+    agent?: string;
+    error: string;
+}
+interface ConvTurnEvent {
+    type: "conv-turn-appended";
+    at: string;
+    conversationId: string;
+    role: "user" | "assistant";
+    contentPreview: string;
+}
+/**
+ * One log line from a supervised tunnel provider (cloudflared today).
+ * Surfaced verbatim so users can debug "why didn't my remote URL come
+ * up" by tailing /events.
+ */
+interface RemoteLogEvent {
+    type: "remote-log";
+    at: string;
+    line: string;
+}
+type RuntimeEvent = BootEvent | HeartbeatFiredEvent | HeartbeatErrorEvent | ConvTurnEvent | RemoteLogEvent;
+interface RuntimeEvents {
+    on<E extends RuntimeEvent["type"]>(type: E, handler: (ev: Extract<RuntimeEvent, {
+        type: E;
+    }>) => void): () => void;
+    onAny(handler: (ev: RuntimeEvent) => void): () => void;
+    emit(ev: RuntimeEvent): void;
+}
+
+/**
+ * HEARTBEAT.md autonomy loop.
+ *
+ * A workspace can ship a `HEARTBEAT.md` at its root. Frontmatter:
+ *
+ *   schema: heartbeat/v1
+ *   agent: <id>           (matches `<workspace>/.agents/<id>/AGENT.md`)
+ *   every: "60s"          (Ns | Nm | Nh | Nd; cron support TODO)
+ *   enabled: true         (default true; set false to register-but-skip)
+ *   conversation: heartbeat-{date}   (templated id; defaults to per-day)
+ *
+ * Body = the prompt body the agent receives each tick. Reread fresh
+ * on every tick so editing HEARTBEAT.md takes effect without restart.
+ *
+ * Ticks resolve the agent via the injected `buildAgent` callback,
+ * call `agent.generate(prompt)`, and append the prompt + reply to a
+ * conversation (default: daily-rolling `heartbeat-YYYY-MM-DD`).
+ *
+ * When the file is missing, frontmatter is invalid, `enabled: false`,
+ * or the resolved agent has no usable model — the runner skips the
+ * tick silently and emits a `heartbeat-error` event. The daemon
+ * stays up.
+ */
+
+interface HeartbeatAgent {
+    generate(prompt: string): Promise<{
+        text: string;
+    }>;
+}
+interface BuildHeartbeatAgent {
+    (id: string): Promise<HeartbeatAgent | null>;
+}
+interface HeartbeatRunnerOptions {
+    workspace: string;
+    conversations: ConversationStore;
+    events: RuntimeEvents;
+    /** Resolves a heartbeat-runnable agent from its workspace id. */
+    buildAgent: BuildHeartbeatAgent;
+    /** Filename inside the workspace root. Default `HEARTBEAT.md`. */
+    filename?: string;
+    /** Skip ticks while this returns false. Default: always true. */
+    shouldFire?: () => boolean;
+    /** Override clock for tests. */
+    now?: () => Date;
+}
+interface HeartbeatRunner {
+    /** Start the timer loop. Idempotent. */
+    start(): void;
+    /** Stop the timer loop. Pending ticks finish out. */
+    stop(): void;
+    /** Force-fire one tick now (used by `POST /heartbeat/tick`). */
+    fireNow(): Promise<void>;
+}
+declare function startHeartbeat(opts: HeartbeatRunnerOptions): HeartbeatRunner;
+/**
+ * Parse `Ns | Nm | Nh | Nd` into milliseconds. Returns `null` if the
+ * string doesn't match. (AIP-41 supports more units, but the daemon's
+ * heartbeat sticks to coarse durations to keep ticks observable.)
+ */
+declare function parseDuration(input: string): number | null;
+
+export { type BuildHeartbeatAgent as B, type HeartbeatAgent as H, type RuntimeEvent as R, type HeartbeatRunner as a, type RuntimeEvents as b, type HeartbeatRunnerOptions as c, parseDuration as p, startHeartbeat as s };

package/dist/heartbeat.d.ts

@@ -0,0 +1,2 @@
+import './conversations.js';
+export { B as BuildHeartbeatAgent, H as HeartbeatAgent, a as HeartbeatRunner, c as HeartbeatRunnerOptions, p as parseDuration, s as startHeartbeat } from './heartbeat-COGpMrJS.js';

package/dist/heartbeat.mjs

@@ -0,0 +1,185 @@
+import matter from 'gray-matter';
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+
+/**
+ * @agentproto/runtime v0.1.0-alpha
+ * Long-running gateway: MCP server + HTTP transport + HEARTBEAT autonomy + conversation persistence over a workspace dir.
+ */
+
+function startHeartbeat(opts) {
+  const filename = opts.filename ?? "HEARTBEAT.md";
+  const path = join(opts.workspace, filename);
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  let timer = null;
+  let currentEveryMs = null;
+  let firing = false;
+  async function load() {
+    if (!existsSync(path)) return null;
+    let source;
+    try {
+      source = await readFile(path, "utf8");
+    } catch {
+      return null;
+    }
+    const parsed = matter(source);
+    const fm = parsed.data;
+    const agent = typeof fm.agent === "string" ? fm.agent : null;
+    if (!agent) return null;
+    const enabled = fm.enabled === void 0 ? true : Boolean(fm.enabled);
+    const everyRaw = typeof fm.every === "string" ? fm.every : "60s";
+    const everyMs = parseDuration(everyRaw);
+    if (!everyMs) return null;
+    const conversationTemplate = typeof fm.conversation === "string" ? fm.conversation : "heartbeat-{date}";
+    return {
+      agent,
+      everyMs,
+      enabled,
+      conversationTemplate,
+      body: parsed.content.trim()
+    };
+  }
+  async function tick() {
+    if (firing) return;
+    if (opts.shouldFire && !opts.shouldFire()) return;
+    firing = true;
+    let agentId;
+    try {
+      const hb = await load();
+      if (!hb || !hb.enabled) return;
+      agentId = hb.agent;
+      const agent = await opts.buildAgent(hb.agent);
+      if (!agent) {
+        opts.events.emit({
+          type: "heartbeat-error",
+          at: now().toISOString(),
+          agent: hb.agent,
+          error: `buildAgent('${hb.agent}') returned null`
+        });
+        return;
+      }
+      if (!hb.body) {
+        opts.events.emit({
+          type: "heartbeat-error",
+          at: now().toISOString(),
+          agent: hb.agent,
+          error: "HEARTBEAT.md body is empty"
+        });
+        return;
+      }
+      const conversationId = expandTemplate(hb.conversationTemplate, now());
+      await opts.conversations.open(conversationId, { agent: hb.agent });
+      const startedAt = now();
+      await opts.conversations.appendTurn(
+        conversationId,
+        "user",
+        hb.body,
+        { at: startedAt.toISOString(), attribution: "heartbeat" }
+      );
+      opts.events.emit({
+        type: "conv-turn-appended",
+        at: startedAt.toISOString(),
+        conversationId,
+        role: "user",
+        contentPreview: preview(hb.body)
+      });
+      const t0 = Date.now();
+      const reply = await agent.generate(hb.body);
+      const durationMs = Date.now() - t0;
+      const finishedAt = now();
+      await opts.conversations.appendTurn(
+        conversationId,
+        "assistant",
+        reply.text,
+        { at: finishedAt.toISOString(), attribution: hb.agent }
+      );
+      opts.events.emit({
+        type: "conv-turn-appended",
+        at: finishedAt.toISOString(),
+        conversationId,
+        role: "assistant",
+        contentPreview: preview(reply.text)
+      });
+      opts.events.emit({
+        type: "heartbeat-fired",
+        at: finishedAt.toISOString(),
+        agent: hb.agent,
+        conversationId,
+        prompt: hb.body,
+        reply: reply.text,
+        durationMs
+      });
+      if (currentEveryMs !== null && currentEveryMs !== hb.everyMs) {
+        reschedule(hb.everyMs);
+      }
+    } catch (err) {
+      opts.events.emit({
+        type: "heartbeat-error",
+        at: now().toISOString(),
+        agent: agentId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    } finally {
+      firing = false;
+    }
+  }
+  function reschedule(everyMs) {
+    if (timer) clearInterval(timer);
+    currentEveryMs = everyMs;
+    timer = setInterval(() => {
+      void tick();
+    }, everyMs);
+  }
+  return {
+    start() {
+      if (timer) return;
+      void load().then((hb) => {
+        const everyMs = hb?.everyMs ?? 6e4;
+        reschedule(everyMs);
+      });
+    },
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+        currentEveryMs = null;
+      }
+    },
+    async fireNow() {
+      await tick();
+    }
+  };
+}
+var DURATION_RE = /^(\d+)\s*(s|m|h|d)$/;
+function parseDuration(input) {
+  const trimmed = input.trim();
+  const match = trimmed.match(DURATION_RE);
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  switch (match[2]) {
+    case "s":
+      return n * 1e3;
+    case "m":
+      return n * 6e4;
+    case "h":
+      return n * 36e5;
+    case "d":
+      return n * 864e5;
+    default:
+      return null;
+  }
+}
+function expandTemplate(template, when) {
+  const date = when.toISOString().slice(0, 10);
+  return template.replace(/\{date\}/g, date);
+}
+function preview(text, max = 120) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+
+export { parseDuration, startHeartbeat };
+//# sourceMappingURL=heartbeat.mjs.map
+//# sourceMappingURL=heartbeat.mjs.map

package/dist/heartbeat.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/heartbeat.ts"],"names":[],"mappings":"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","file":"heartbeat.mjs","sourcesContent":["/**\n * HEARTBEAT.md autonomy loop.\n *\n * A workspace can ship a `HEARTBEAT.md` at its root. Frontmatter:\n *\n *   schema: heartbeat/v1\n *   agent: <id>           (matches `<workspace>/.agents/<id>/AGENT.md`)\n *   every: \"60s\"          (Ns | Nm | Nh | Nd; cron support TODO)\n *   enabled: true         (default true; set false to register-but-skip)\n *   conversation: heartbeat-{date}   (templated id; defaults to per-day)\n *\n * Body = the prompt body the agent receives each tick. Reread fresh\n * on every tick so editing HEARTBEAT.md takes effect without restart.\n *\n * Ticks resolve the agent via the injected `buildAgent` callback,\n * call `agent.generate(prompt)`, and append the prompt + reply to a\n * conversation (default: daily-rolling `heartbeat-YYYY-MM-DD`).\n *\n * When the file is missing, frontmatter is invalid, `enabled: false`,\n * or the resolved agent has no usable model — the runner skips the\n * tick silently and emits a `heartbeat-error` event. The daemon\n * stays up.\n */\n\nimport matter from \"gray-matter\"\nimport { existsSync } from \"node:fs\"\nimport { readFile } from \"node:fs/promises\"\nimport { join } from \"node:path\"\nimport type { ConversationStore } from \"./conversations.js\"\nimport type { RuntimeEvents } from \"./events.js\"\n\nexport interface HeartbeatAgent {\n  generate(prompt: string): Promise<{ text: string }>\n}\n\nexport interface BuildHeartbeatAgent {\n  (id: string): Promise<HeartbeatAgent | null>\n}\n\nexport interface HeartbeatRunnerOptions {\n  workspace: string\n  conversations: ConversationStore\n  events: RuntimeEvents\n  /** Resolves a heartbeat-runnable agent from its workspace id. */\n  buildAgent: BuildHeartbeatAgent\n  /** Filename inside the workspace root. Default `HEARTBEAT.md`. */\n  filename?: string\n  /** Skip ticks while this returns false. Default: always true. */\n  shouldFire?: () => boolean\n  /** Override clock for tests. */\n  now?: () => Date\n}\n\nexport interface HeartbeatRunner {\n  /** Start the timer loop. Idempotent. */\n  start(): void\n  /** Stop the timer loop. Pending ticks finish out. */\n  stop(): void\n  /** Force-fire one tick now (used by `POST /heartbeat/tick`). */\n  fireNow(): Promise<void>\n}\n\ninterface ParsedHeartbeat {\n  agent: string\n  everyMs: number\n  enabled: boolean\n  conversationTemplate: string\n  body: string\n}\n\nexport function startHeartbeat(opts: HeartbeatRunnerOptions): HeartbeatRunner {\n  const filename = opts.filename ?? \"HEARTBEAT.md\"\n  const path = join(opts.workspace, filename)\n  const now = opts.now ?? (() => new Date())\n\n  let timer: NodeJS.Timeout | null = null\n  let currentEveryMs: number | null = null\n  let firing = false\n\n  async function load(): Promise<ParsedHeartbeat | null> {\n    if (!existsSync(path)) return null\n    let source: string\n    try {\n      source = await readFile(path, \"utf8\")\n    } catch {\n      return null\n    }\n    const parsed = matter(source)\n    const fm = parsed.data as Record<string, unknown>\n    const agent = typeof fm.agent === \"string\" ? fm.agent : null\n    if (!agent) return null\n    const enabled = fm.enabled === undefined ? true : Boolean(fm.enabled)\n    const everyRaw = typeof fm.every === \"string\" ? fm.every : \"60s\"\n    const everyMs = parseDuration(everyRaw)\n    if (!everyMs) return null\n    const conversationTemplate =\n      typeof fm.conversation === \"string\"\n        ? fm.conversation\n        : \"heartbeat-{date}\"\n    return {\n      agent,\n      everyMs,\n      enabled,\n      conversationTemplate,\n      body: parsed.content.trim(),\n    }\n  }\n\n  async function tick(): Promise<void> {\n    if (firing) return\n    if (opts.shouldFire && !opts.shouldFire()) return\n    firing = true\n    let agentId: string | undefined\n    try {\n      const hb = await load()\n      if (!hb || !hb.enabled) return\n      agentId = hb.agent\n      const agent = await opts.buildAgent(hb.agent)\n      if (!agent) {\n        opts.events.emit({\n          type: \"heartbeat-error\",\n          at: now().toISOString(),\n          agent: hb.agent,\n          error: `buildAgent('${hb.agent}') returned null`,\n        })\n        return\n      }\n      if (!hb.body) {\n        opts.events.emit({\n          type: \"heartbeat-error\",\n          at: now().toISOString(),\n          agent: hb.agent,\n          error: \"HEARTBEAT.md body is empty\",\n        })\n        return\n      }\n\n      const conversationId = expandTemplate(hb.conversationTemplate, now())\n      await opts.conversations.open(conversationId, { agent: hb.agent })\n\n      const startedAt = now()\n      await opts.conversations.appendTurn(\n        conversationId,\n        \"user\",\n        hb.body,\n        { at: startedAt.toISOString(), attribution: \"heartbeat\" },\n      )\n      opts.events.emit({\n        type: \"conv-turn-appended\",\n        at: startedAt.toISOString(),\n        conversationId,\n        role: \"user\",\n        contentPreview: preview(hb.body),\n      })\n\n      const t0 = Date.now()\n      const reply = await agent.generate(hb.body)\n      const durationMs = Date.now() - t0\n\n      const finishedAt = now()\n      await opts.conversations.appendTurn(\n        conversationId,\n        \"assistant\",\n        reply.text,\n        { at: finishedAt.toISOString(), attribution: hb.agent },\n      )\n      opts.events.emit({\n        type: \"conv-turn-appended\",\n        at: finishedAt.toISOString(),\n        conversationId,\n        role: \"assistant\",\n        contentPreview: preview(reply.text),\n      })\n      opts.events.emit({\n        type: \"heartbeat-fired\",\n        at: finishedAt.toISOString(),\n        agent: hb.agent,\n        conversationId,\n        prompt: hb.body,\n        reply: reply.text,\n        durationMs,\n      })\n\n      // Adapt the timer if `every` changed since we started.\n      if (currentEveryMs !== null && currentEveryMs !== hb.everyMs) {\n        reschedule(hb.everyMs)\n      }\n    } catch (err) {\n      opts.events.emit({\n        type: \"heartbeat-error\",\n        at: now().toISOString(),\n        agent: agentId,\n        error: err instanceof Error ? err.message : String(err),\n      })\n    } finally {\n      firing = false\n    }\n  }\n\n  function reschedule(everyMs: number): void {\n    if (timer) clearInterval(timer)\n    currentEveryMs = everyMs\n    timer = setInterval(() => {\n      void tick()\n    }, everyMs)\n  }\n\n  return {\n    start() {\n      if (timer) return\n      // Bootstrap interval from the file (or fall back to 60s if\n      // unreadable — first real tick will refresh from disk).\n      void load().then((hb) => {\n        const everyMs = hb?.everyMs ?? 60_000\n        reschedule(everyMs)\n      })\n    },\n    stop() {\n      if (timer) {\n        clearInterval(timer)\n        timer = null\n        currentEveryMs = null\n      }\n    },\n    async fireNow() {\n      await tick()\n    },\n  }\n}\n\n// ── helpers ──────────────────────────────────────────────────────────\n\nconst DURATION_RE = /^(\\d+)\\s*(s|m|h|d)$/\n\n/**\n * Parse `Ns | Nm | Nh | Nd` into milliseconds. Returns `null` if the\n * string doesn't match. (AIP-41 supports more units, but the daemon's\n * heartbeat sticks to coarse durations to keep ticks observable.)\n */\nexport function parseDuration(input: string): number | null {\n  const trimmed = input.trim()\n  const match = trimmed.match(DURATION_RE)\n  if (!match) return null\n  const n = Number(match[1])\n  if (!Number.isFinite(n) || n <= 0) return null\n  switch (match[2]) {\n    case \"s\":\n      return n * 1_000\n    case \"m\":\n      return n * 60_000\n    case \"h\":\n      return n * 3_600_000\n    case \"d\":\n      return n * 86_400_000\n    default:\n      return null\n  }\n}\n\n/**\n * Replace `{date}` with `YYYY-MM-DD` (UTC) in conversation templates.\n * Other tokens pass through unchanged — extend later if needed.\n */\nfunction expandTemplate(template: string, when: Date): string {\n  const date = when.toISOString().slice(0, 10)\n  return template.replace(/\\{date\\}/g, date)\n}\n\nfunction preview(text: string, max = 120): string {\n  const flat = text.replace(/\\s+/g, \" \").trim()\n  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat\n}\n"]}