@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/markers.ts

@@ -0,0 +1,178 @@
+/**
+ * Response marker parsing for agent replies.
+ *
+ * Claude can embed special markers in its response text to trigger side-effect
+ * actions. Markers are stripped from the visible message before posting.
+ *
+ * Supported markers:
+ *   [silent]                        — skip posting
+ *   [upload:/path/to/file]          — upload a file
+ *   [speak:text]                    — synthesize speech and upload audio file
+ *   [react:emoji1,emoji2]           — add emoji reactions
+ *   [plan:url]                      — post a "View plan" link to the channel/thread
+ *   [skip-reason:text]              — tag a machine-readable reason for a silent
+ *                                      dispatch; parsed independently of [silent]
+ *                                      (does not require it to also be present),
+ *                                      but only meaningful when it is — the
+ *                                      loop orchestrator uses it as the
+ *                                      skipRun() reason on a [silent] dispatch,
+ *                                      falling back to "command:no-work" when
+ *                                      absent (see agent/src/coding/loop-orchestrator.ts)
+ *
+ * Malformed markers are logged and left in the cleaned text (not crashed on).
+ */
+
+interface SilentMarker {
+  type: "silent";
+}
+
+interface UploadMarker {
+  type: "upload";
+  path: string;
+}
+
+interface SpeakMarker {
+  type: "speak";
+  text: string;
+}
+
+interface ReactMarker {
+  type: "react";
+  emojis: string[];
+}
+
+interface PlanMarker {
+  type: "plan";
+  url: string;
+}
+
+interface SkipReasonMarker {
+  type: "skip-reason";
+  reason: string;
+}
+
+export type Marker =
+  | SilentMarker
+  | UploadMarker
+  | SpeakMarker
+  | ReactMarker
+  | PlanMarker
+  | SkipReasonMarker;
+
+interface ParseMarkersResult {
+  cleaned: string;
+  markers: Marker[];
+}
+
+// Regex patterns — greedy non-nested matching.
+// [silent] must appear at the end of the response so meta-discussion of the
+// marker (e.g. "Use [silent] to skip posting") doesn't accidentally silence it.
+const SILENT_REGEX = /\[silent\]\s*$/i;
+const UPLOAD_REGEX = /\[upload:([^\]]+)\]/gi;
+const SPEAK_REGEX = /\[speak:([\s\S]*?)\]/gi;
+const REACT_REGEX = /\[react:([^\]]+)\]/gi;
+const PLAN_REGEX = /\[plan:([^\]]+)\]/gi;
+const SKIP_REASON_REGEX = /\[skip-reason:([^\]]+)\]/gi;
+
+/**
+ * Parse all response markers from text.
+ * Returns the cleaned text (markers stripped) and an ordered list of markers found.
+ * Malformed markers are logged and left in the cleaned text.
+ */
+export function parseMarkers(text: string): ParseMarkersResult {
+  const markers: Marker[] = [];
+  let cleaned = text;
+
+  // [skip-reason:text] — stripped before the [silent] end-anchor check below
+  // so [silent] is still recognized regardless of whether [skip-reason:...]
+  // appears before or after it in the raw text (DBV-1.1).
+  cleaned = cleaned.replace(SKIP_REASON_REGEX, (_match, reasonRaw: string) => {
+    const reason = reasonRaw.trim();
+    if (!reason) {
+      console.warn(
+        "[markers] malformed [skip-reason:] marker — empty reason, leaving in text:",
+        _match,
+      );
+      return _match;
+    }
+    markers.push({ type: "skip-reason", reason });
+    return "";
+  });
+  SKIP_REASON_REGEX.lastIndex = 0;
+  cleaned = cleaned.trim();
+
+  // [silent]
+  if (SILENT_REGEX.test(cleaned)) {
+    markers.push({ type: "silent" });
+    cleaned = cleaned.replace(SILENT_REGEX, "").trim();
+  }
+
+  // [upload:/path]
+  cleaned = cleaned.replace(UPLOAD_REGEX, (_match, pathRaw: string) => {
+    const path = pathRaw.trim();
+    if (!path) {
+      console.warn(
+        "[markers] malformed [upload:] marker — empty path, leaving in text:",
+        _match,
+      );
+      return _match;
+    }
+    markers.push({ type: "upload", path });
+    return "";
+  });
+  UPLOAD_REGEX.lastIndex = 0;
+  cleaned = cleaned.trim();
+
+  // [speak:text]
+  cleaned = cleaned.replace(SPEAK_REGEX, (_match, textRaw: string) => {
+    const text = textRaw.trim();
+    if (!text) {
+      console.warn(
+        "[markers] malformed [speak:] marker — empty text, leaving in text:",
+        _match,
+      );
+      return _match;
+    }
+    markers.push({ type: "speak", text });
+    return "";
+  });
+  SPEAK_REGEX.lastIndex = 0;
+  cleaned = cleaned.trim();
+
+  // [react:emoji1,emoji2,...]
+  cleaned = cleaned.replace(REACT_REGEX, (_match, raw: string) => {
+    const emojis = raw
+      .split(",")
+      .map((e) => e.trim())
+      .filter(Boolean);
+    if (emojis.length === 0) {
+      console.warn(
+        "[markers] malformed [react:] marker — empty emoji list, leaving in text:",
+        _match,
+      );
+      return _match;
+    }
+    markers.push({ type: "react", emojis });
+    return "";
+  });
+  REACT_REGEX.lastIndex = 0;
+  cleaned = cleaned.trim();
+
+  // [plan:url]
+  cleaned = cleaned.replace(PLAN_REGEX, (_match, urlRaw: string) => {
+    const url = urlRaw.trim();
+    if (!url) {
+      console.warn(
+        "[markers] malformed [plan:] marker — empty url, leaving in text:",
+        _match,
+      );
+      return _match;
+    }
+    markers.push({ type: "plan", url });
+    return "";
+  });
+  PLAN_REGEX.lastIndex = 0;
+  cleaned = cleaned.trim();
+
+  return { cleaned, markers };
+}

package/markers.unit.test.ts

@@ -0,0 +1,374 @@
+/**
+ * Unit tests for parseMarkers() in agent/src/runtime/markers.ts
+ *
+ * Pure function — no side effects, no mocks needed.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { parseMarkers } from "./markers.ts";
+
+// ─── [silent] ─────────────────────────────────────────────────────────────────
+
+describe("[silent] marker", () => {
+  test("detects [silent] and returns silent marker", () => {
+    const { markers } = parseMarkers("[silent]");
+    expect(markers).toHaveLength(1);
+    expect(markers[0].type).toBe("silent");
+  });
+
+  test("strips [silent] from cleaned text", () => {
+    const { cleaned } = parseMarkers("[silent]");
+    expect(cleaned).toBe("");
+  });
+
+  test("[silent] in middle does NOT trigger silent marker", () => {
+    const { cleaned, markers } = parseMarkers("before [silent] after");
+    expect(markers.some((m) => m.type === "silent")).toBe(false);
+    expect(cleaned).toBe("before [silent] after");
+  });
+
+  test("[silent] at end triggers silent marker and strips it", () => {
+    const { cleaned, markers } = parseMarkers("All done.\n[silent]");
+    expect(markers.some((m) => m.type === "silent")).toBe(true);
+    expect(cleaned).toBe("All done.");
+  });
+
+  test("[silent] at start without trailing position is NOT silent", () => {
+    const { markers } = parseMarkers("[silent] but also text");
+    expect(markers.some((m) => m.type === "silent")).toBe(false);
+  });
+
+  test("[silent] with trailing whitespace still triggers silent", () => {
+    const { markers } = parseMarkers("[silent]   \n  ");
+    expect(markers.some((m) => m.type === "silent")).toBe(true);
+  });
+
+  test("is case-insensitive", () => {
+    const { markers } = parseMarkers("[SILENT]");
+    expect(markers.some((m) => m.type === "silent")).toBe(true);
+  });
+
+  test("text without [silent] has no silent marker", () => {
+    const { markers } = parseMarkers("Hello world");
+    expect(markers.some((m) => m.type === "silent")).toBe(false);
+  });
+});
+
+// ─── [upload:...] ─────────────────────────────────────────────────────────────
+
+describe("[upload:...] marker", () => {
+  test("parses a file path", () => {
+    const { markers, cleaned } = parseMarkers(
+      "See attached [upload:/tmp/report.pdf]",
+    );
+    const uploadMarker = markers.find((m) => m.type === "upload");
+    expect(uploadMarker).toBeDefined();
+    expect((uploadMarker as { type: "upload"; path: string }).path).toBe(
+      "/tmp/report.pdf",
+    );
+    expect(cleaned).toBe("See attached");
+  });
+
+  test("parses multiple upload markers", () => {
+    const { markers } = parseMarkers("[upload:/tmp/a.pdf][upload:/tmp/b.png]");
+    const uploads = markers.filter((m) => m.type === "upload") as {
+      type: "upload";
+      path: string;
+    }[];
+    expect(uploads).toHaveLength(2);
+    expect(uploads[0].path).toBe("/tmp/a.pdf");
+    expect(uploads[1].path).toBe("/tmp/b.png");
+  });
+
+  test("strips upload marker from cleaned text", () => {
+    const { cleaned } = parseMarkers("Done [upload:/tmp/out.csv]");
+    expect(cleaned).not.toContain("[upload:");
+  });
+
+  test("malformed upload with empty path is left in text", () => {
+    const { cleaned, markers } = parseMarkers("[upload:]");
+    expect(cleaned).toContain("[upload:]");
+    expect(markers.some((m) => m.type === "upload")).toBe(false);
+  });
+
+  test("malformed upload with whitespace-only path is left in text", () => {
+    const { cleaned, markers } = parseMarkers("[upload:   ]");
+    expect(cleaned).toContain("[upload:   ]");
+    expect(markers.some((m) => m.type === "upload")).toBe(false);
+  });
+});
+
+// ─── [plan:url] ───────────────────────────────────────────────────────────────
+
+describe("[plan:url] marker", () => {
+  test("detects [plan:url] and returns plan marker with url", () => {
+    const { markers } = parseMarkers(
+      "Plan ready [plan:https://example.com/p/abc]",
+    );
+    const planMarker = markers.find((m) => m.type === "plan");
+    expect(planMarker).toBeDefined();
+    if (planMarker?.type === "plan") {
+      expect(planMarker.url).toBe("https://example.com/p/abc");
+    }
+  });
+
+  test("strips [plan:url] from cleaned text", () => {
+    const { cleaned } = parseMarkers("Done [plan:https://example.com/p/abc]");
+    expect(cleaned).toBe("Done");
+    expect(cleaned).not.toContain("[plan:");
+  });
+
+  test("malformed [plan:] with empty url is left in text and yields no marker", () => {
+    const { cleaned, markers } = parseMarkers("[plan:]");
+    expect(markers.some((m) => m.type === "plan")).toBe(false);
+    expect(cleaned).toContain("[plan:]");
+  });
+
+  test("[plan:url] mid-text is still parsed (markers can appear anywhere)", () => {
+    const { cleaned, markers } = parseMarkers(
+      "before [plan:https://example.com/p/xyz] after",
+    );
+    const planMarker = markers.find((m) => m.type === "plan");
+    expect(planMarker).toBeDefined();
+    if (planMarker?.type === "plan") {
+      expect(planMarker.url).toBe("https://example.com/p/xyz");
+    }
+    expect(cleaned).toBe("before  after");
+  });
+});
+
+// ─── Multiple markers ─────────────────────────────────────────────────────────
+
+describe("multiple markers in one response", () => {
+  test("parses upload + speak together", () => {
+    const { markers, cleaned } = parseMarkers(
+      "Here is the report [upload:/tmp/report.pdf][speak:report ready]",
+    );
+    expect(markers.some((m) => m.type === "upload")).toBe(true);
+    expect(markers.some((m) => m.type === "speak")).toBe(true);
+    expect(cleaned).toBe("Here is the report");
+  });
+
+  test("silent with other markers — silent must be at end", () => {
+    const { markers } = parseMarkers("[upload:/tmp/out.txt][silent]");
+    expect(markers.some((m) => m.type === "silent")).toBe(true);
+    expect(markers.some((m) => m.type === "upload")).toBe(true);
+  });
+
+  test("no text remaining when all content is markers", () => {
+    const { cleaned } = parseMarkers("[silent]");
+    expect(cleaned).toBe("");
+  });
+});
+
+// ─── No markers ───────────────────────────────────────────────────────────────
+
+describe("no markers", () => {
+  test("returns unchanged text when no markers present", () => {
+    const input = "Just a plain response with no markers.";
+    const { cleaned, markers } = parseMarkers(input);
+    expect(cleaned).toBe(input);
+    expect(markers).toHaveLength(0);
+  });
+
+  test("returns empty string for empty input", () => {
+    const { cleaned, markers } = parseMarkers("");
+    expect(cleaned).toBe("");
+    expect(markers).toHaveLength(0);
+  });
+});
+
+// ─── [speak:...] ──────────────────────────────────────────────────────────────
+
+describe("[speak:text] marker", () => {
+  test("parses [speak:text] and returns speak marker", () => {
+    const { markers } = parseMarkers("[speak:Hello there]");
+    expect(markers).toHaveLength(1);
+    expect(markers[0].type).toBe("speak");
+    if (markers[0].type === "speak") {
+      expect(markers[0].text).toBe("Hello there");
+    }
+  });
+
+  test("strips [speak:text] from cleaned text", () => {
+    const { cleaned } = parseMarkers("Response text [speak:Hello there]");
+    expect(cleaned).toBe("Response text");
+  });
+
+  test("handles multi-word speak text", () => {
+    const { markers } = parseMarkers("[speak:The answer is 42, my friend]");
+    expect(markers[0].type).toBe("speak");
+    if (markers[0].type === "speak") {
+      expect(markers[0].text).toBe("The answer is 42, my friend");
+    }
+  });
+
+  test("malformed [speak:] with empty text — left in cleaned text", () => {
+    const { cleaned, markers } = parseMarkers("[speak:]");
+    expect(markers.some((m) => m.type === "speak")).toBe(false);
+    expect(cleaned).toContain("[speak:]");
+  });
+
+  test("speak with surrounding text preserves other content", () => {
+    const { cleaned, markers } = parseMarkers(
+      "Here is my answer. [speak:Here is my answer]",
+    );
+    expect(cleaned).toBe("Here is my answer.");
+    expect(markers.some((m) => m.type === "speak")).toBe(true);
+  });
+});
+
+// ─── [react:...] ──────────────────────────────────────────────────────────────
+
+describe("[react:emoji] marker", () => {
+  test("parses single emoji and returns react marker", () => {
+    const { markers } = parseMarkers("Nice work! [react:thumbsup]");
+    const reactMarker = markers.find((m) => m.type === "react");
+    expect(reactMarker).toBeDefined();
+    if (reactMarker?.type === "react") {
+      expect(reactMarker.emojis).toEqual(["thumbsup"]);
+    }
+  });
+
+  test("strips [react:emoji] from cleaned text", () => {
+    const { cleaned } = parseMarkers("Done [react:white_check_mark]");
+    expect(cleaned).toBe("Done");
+    expect(cleaned).not.toContain("[react:");
+  });
+
+  test("parses comma-separated emojis", () => {
+    const { markers } = parseMarkers("[react:thumbsup,tada]");
+    const reactMarker = markers.find((m) => m.type === "react");
+    expect(reactMarker).toBeDefined();
+    if (reactMarker?.type === "react") {
+      expect(reactMarker.emojis).toEqual(["thumbsup", "tada"]);
+    }
+  });
+
+  test("parses three emojis", () => {
+    const { markers } = parseMarkers("All good [react:thumbsup,tada,rocket]");
+    const reactMarker = markers.find((m) => m.type === "react");
+    if (reactMarker?.type === "react") {
+      expect(reactMarker.emojis).toEqual(["thumbsup", "tada", "rocket"]);
+    }
+  });
+
+  test("trims whitespace from emoji names", () => {
+    const { markers } = parseMarkers("[react: thumbsup , tada ]");
+    const reactMarker = markers.find((m) => m.type === "react");
+    if (reactMarker?.type === "react") {
+      expect(reactMarker.emojis).toEqual(["thumbsup", "tada"]);
+    }
+  });
+
+  test("malformed [react:] with empty content is left in text", () => {
+    const { cleaned, markers } = parseMarkers("[react:]");
+    expect(markers.some((m) => m.type === "react")).toBe(false);
+    expect(cleaned).toContain("[react:]");
+  });
+
+  test("react marker coexists with other markers", () => {
+    const { markers, cleaned } = parseMarkers("Done [react:thumbsup][silent]");
+    expect(markers.some((m) => m.type === "react")).toBe(true);
+    expect(markers.some((m) => m.type === "silent")).toBe(true);
+    expect(cleaned).toBe("Done");
+  });
+});
+
+// ─── [skip-reason:text] ────────────────────────────────────────────────────
+
+describe("[skip-reason:text] marker", () => {
+  test("parses [skip-reason:text] and returns a skip-reason marker with the text", () => {
+    const { markers } = parseMarkers(
+      "Nothing to do.\n[silent]\n[skip-reason:deploy:bundle-incomplete:feat/x]",
+    );
+    const marker = markers.find((m) => m.type === "skip-reason");
+    expect(marker).toBeDefined();
+    if (marker?.type === "skip-reason") {
+      expect(marker.reason).toBe("deploy:bundle-incomplete:feat/x");
+    }
+  });
+
+  test("strips [skip-reason:text] from cleaned text", () => {
+    const { cleaned } = parseMarkers(
+      "Done [skip-reason:deploy:bundle-incomplete:feat/x]",
+    );
+    expect(cleaned).toBe("Done");
+    expect(cleaned).not.toContain("[skip-reason:");
+  });
+
+  test("malformed [skip-reason:] with empty text is left in cleaned text and yields no marker", () => {
+    const { cleaned, markers } = parseMarkers("[skip-reason:]");
+    expect(markers.some((m) => m.type === "skip-reason")).toBe(false);
+    expect(cleaned).toContain("[skip-reason:]");
+  });
+
+  test("malformed [skip-reason:] with whitespace-only text is left in cleaned text and yields no marker", () => {
+    const { cleaned, markers } = parseMarkers("[skip-reason:   ]");
+    expect(markers.some((m) => m.type === "skip-reason")).toBe(false);
+    expect(cleaned).toContain("[skip-reason:   ]");
+  });
+
+  test("parses independently of [silent] being present — no [silent] marker at all", () => {
+    const { markers } = parseMarkers(
+      "Some text [skip-reason:deploy:bundle-incomplete:feat/x]",
+    );
+    expect(markers.some((m) => m.type === "silent")).toBe(false);
+    const marker = markers.find((m) => m.type === "skip-reason");
+    expect(marker).toBeDefined();
+    if (marker?.type === "skip-reason") {
+      expect(marker.reason).toBe("deploy:bundle-incomplete:feat/x");
+    }
+  });
+
+  test("coexists with [silent] at the end of the response", () => {
+    const { markers, cleaned } = parseMarkers(
+      "Bundle gate blocked.\n[skip-reason:deploy:bundle-incomplete:feat/x]\n[silent]",
+    );
+    expect(markers.some((m) => m.type === "silent")).toBe(true);
+    const marker = markers.find((m) => m.type === "skip-reason");
+    expect(marker).toBeDefined();
+    if (marker?.type === "skip-reason") {
+      expect(marker.reason).toBe("deploy:bundle-incomplete:feat/x");
+    }
+    expect(cleaned).toBe("Bundle gate blocked.");
+  });
+
+  test("with multiple markers present, consumers reading markers.find(...) get the first (first-match-wins)", () => {
+    const { markers } = parseMarkers(
+      "[skip-reason:first-reason][skip-reason:second-reason]",
+    );
+    const skipReasonMarkers = markers.filter((m) => m.type === "skip-reason");
+    expect(skipReasonMarkers).toHaveLength(2);
+    const firstMatch = markers.find((m) => m.type === "skip-reason");
+    if (firstMatch?.type === "skip-reason") {
+      expect(firstMatch.reason).toBe("first-reason");
+    }
+  });
+
+  test("[silent] is still recognized when [skip-reason:...] appears AFTER it (order-independent)", () => {
+    const { markers, cleaned } = parseMarkers(
+      "Bundle gate blocked.\n[silent]\n[skip-reason:deploy:bundle-incomplete:feat/x]",
+    );
+    expect(markers.some((m) => m.type === "silent")).toBe(true);
+    const marker = markers.find((m) => m.type === "skip-reason");
+    expect(marker).toBeDefined();
+    if (marker?.type === "skip-reason") {
+      expect(marker.reason).toBe("deploy:bundle-incomplete:feat/x");
+    }
+    expect(cleaned).toBe("Bundle gate blocked.");
+  });
+
+  test("[silent] is recognized identically regardless of [skip-reason:...] ordering (before vs after)", () => {
+    const before = parseMarkers(
+      "Blocked.\n[skip-reason:deploy:bundle-incomplete:feat/x]\n[silent]",
+    );
+    const after = parseMarkers(
+      "Blocked.\n[silent]\n[skip-reason:deploy:bundle-incomplete:feat/x]",
+    );
+    expect(before.markers.some((m) => m.type === "silent")).toBe(true);
+    expect(after.markers.some((m) => m.type === "silent")).toBe(true);
+    expect(before.cleaned).toBe("Blocked.");
+    expect(after.cleaned).toBe("Blocked.");
+  });
+});

package/package.json

@@ -1,8 +1,42 @@
 {
   "name": "@app-vitals/agent-runtime",
-  "version": "0.0.1",
-  "description": "Placeholder reserving the package name. The real release is published from github.com/app-vitals/agent.",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/app-vitals/agent.git",
+    "directory": "runtime"
+  },
   "license": "MIT",
-  "repository": {"type": "git", "url": "git+https://github.com/app-vitals/agent.git"},
-  "publishConfig": {"access": "public"}
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    "./agent-extension": "./agent-extension.ts",
+    "./agent-repos-ref": "./agent-repos-ref.ts",
+    "./anthropic-federation-guard": "./anthropic-federation-guard.ts",
+    "./boot": "./boot.ts",
+    "./browser": "./browser.ts",
+    "./claude": "./claude.ts",
+    "./cleanup-after-days-ref": "./cleanup-after-days-ref.ts",
+    "./cleanup-merged-worktrees-ref": "./cleanup-merged-worktrees-ref.ts",
+    "./cli-args": "./cli-args.ts",
+    "./clock": "./clock.ts",
+    "./context-stamp": "./context-stamp.ts",
+    "./cron-failure-reporter": "./cron-failure-reporter.ts",
+    "./cron-handler": "./cron-handler.ts",
+    "./cron-run-reporter": "./cron-run-reporter.ts",
+    "./cutover-validate": "./cutover-validate.ts",
+    "./entrypoint": "./entrypoint.ts",
+    "./gh-helpers": "./gh-helpers.ts",
+    "./github-auth-deps": "./github-auth-deps.ts",
+    "./markers": "./markers.ts",
+    "./process-tree-kill": "./process-tree-kill.ts",
+    "./run-telemetry": "./run-telemetry.ts",
+    "./setup": "./setup.ts",
+    "./setup-github-auth": "./setup-github-auth.ts",
+    "./shipwright-runtime-client": "./shipwright-runtime-client.ts",
+    "./spawn-env": "./spawn-env.ts",
+    "./workspace-paths": "./workspace-paths.ts"
+  }
 }