@polderlabs/bizar 5.4.0 → 5.5.0

package/plugins/bizar/src/hooks/memory-inject.ts

@@ -0,0 +1,247 @@
+/**
+ * plugins/bizar/src/hooks/memory-inject.ts
+ *
+ * Session-start memory injection hook.
+ *
+ * Fires on `session.created` event, searches the memory vault for
+ * relevant context based on the user's initial message, and queues a
+ * Memory Context injection into the system prompt via
+ * `experimental.chat.system.transform`.
+ *
+ * Key design decisions:
+ *   - Fires ONCE per session (idempotent via `ctx._memoryInjectedSessions`)
+ *   - Uses the first user message text as the search query
+ *   - Reads top 3 results and injects a "## Memory Context" section
+ *   - Skips if no results found (no empty section)
+ *   - Configurable via `settings.memory.injectOnSessionStart` (default true)
+ *   - Non-blocking: memory search is fire-and-forget
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import type { Logger } from "../logger.js";
+
+/** How many memory results to inject at most */
+const MAX_INJECT_RESULTS = 3;
+
+/**
+ * Resolve the dashboard server port. Returns null if not available.
+ */
+export async function resolveDashboardPort(): Promise<number | null> {
+  const portFile = join(homedir(), ".config", "bizar", "dashboard.port");
+  if (existsSync(portFile)) {
+    try {
+      const raw = readFileSync(portFile, "utf8").trim();
+      const n = parseInt(raw, 10);
+      if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
+    } catch {
+      // fall through
+    }
+  }
+  const envPort = process.env.BIZAR_DASHBOARD_PORT;
+  if (envPort) {
+    const n = parseInt(envPort, 10);
+    if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
+  }
+  return null;
+}
+
+/**
+ * Search memory vault via the dashboard API.
+ * Returns up to `limit` results.
+ */
+async function searchMemory(
+  port: number,
+  query: string,
+  limit = 5,
+): Promise<Array<{ path: string | null; snippet: string; score: number }>> {
+  try {
+    // Try semantic first, then fall back to FTS
+    const baseUrl = `http://127.0.0.1:${port}`;
+
+    // Semantic search via LightRAG
+    const semRes = await fetch(`${baseUrl}/api/memory/semantic-search`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query, limit, sources: ["lightrag", "obsidian"] }),
+    });
+
+    if (semRes.ok) {
+      const data = (await semRes.json()) as {
+        results?: Array<{
+          relPath?: string | null;
+          snippet?: string;
+          score?: number;
+        }>;
+      };
+      if (data.results && data.results.length > 0) {
+        return (data.results).map((r) => ({
+          path: r.relPath ?? null,
+          snippet: typeof r.snippet === "string" ? r.snippet.slice(0, 500) : String(r.snippet ?? ""),
+          score: typeof r.score === "number" ? r.score : 1,
+        }));
+      }
+    }
+
+    // Fall back to FTS
+    const ftsRes = await fetch(
+      `${baseUrl}/api/memory/search?q=${encodeURIComponent(query)}&limit=${limit}`,
+      { method: "GET" },
+    );
+    if (ftsRes.ok) {
+      const data = (await ftsRes.json()) as {
+        results?: Array<{ relPath?: string; snippet?: string; score?: number }>;
+      };
+      if (data.results) {
+        return data.results.map((r) => ({
+          path: r.relPath ?? null,
+          snippet: typeof r.snippet === "string" ? r.snippet.slice(0, 500) : String(r.snippet ?? ""),
+          score: typeof r.score === "number" ? r.score : 0,
+        }));
+      }
+    }
+  } catch {
+    // non-fatal: memory injection should not break session start
+  }
+  return [];
+}
+
+/**
+ * Extract a search query from the first user message.
+ * Uses a simple heuristic: first 50 chars + key nouns.
+ */
+function buildSearchQuery(messageText: string): string {
+  // Strip /commands, whitespace, quotes
+  const cleaned = messageText.replace(/^[\/\s"\']+/, "").trim();
+  // Take first meaningful chunk (up to 80 chars)
+  const core = cleaned.slice(0, 80).split(/[.\n!?]/)[0] ?? cleaned;
+  return core || cleaned.slice(0, 50);
+}
+
+/**
+ * Format a memory result as a markdown section for injection.
+ */
+function formatMemoryContext(
+  results: Array<{ path: string | null; snippet: string; score: number }>,
+): string {
+  const lines = ["## Memory Context\n"];
+  lines.push(
+    `_Automatically injected from the Bizar Memory vault. ${results.length} relevant note(s) found._\n`,
+  );
+  for (const r of results.slice(0, MAX_INJECT_RESULTS)) {
+    if (r.path) {
+      lines.push(`### ${r.path}`);
+    } else {
+      lines.push("### (semantic match)");
+    }
+    lines.push(`_${r.score > 0 ? `score: ${r.score.toFixed(2)}` : "full-text match"}_\n`);
+    lines.push(r.snippet);
+    lines.push("\n---\n");
+  }
+  return lines.join("\n");
+}
+
+export interface MemoryInjectDeps {
+  /** Set of sessionIds that have already been injected (cleared on session.deleted). */
+  injectedSessions: Set<string>;
+  worktree: string;
+  logger: Logger;
+  /** If false, skip injection entirely (configurable via settings). */
+  enabled: boolean;
+}
+
+/**
+ * Build the session-start memory injection logic.
+ * Call this from the `event` hook for `session.created` events.
+ *
+ * Usage in index.ts `event` hook:
+ *   const memoryInjectDeps = { injectedSessions, worktree, logger, enabled: true };
+ *   const { memoryInject } = createMemoryInject(memoryInjectDeps);
+ *   // in event handler:
+ *   if (type === "session.created") {
+ *     memoryInject(sessionID, userMessageText).catch(() => {});
+ *   }
+ *
+ * The `injectedSessions` Set is also checked/cleared in `session.deleted`.
+ */
+export function createMemoryInject(deps: MemoryInjectDeps) {
+  const { injectedSessions, logger } = deps;
+
+  /**
+   * Fire memory search and queue the result for injection.
+   * Safe to await or fire-and-forget — errors are swallowed.
+   */
+  async function memoryInject(
+    sessionID: string,
+    userMessageText: string,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (!deps.enabled) return;
+    if (injectedSessions.has(sessionID)) return;
+
+    // Mark injected BEFORE the async work so we don't double-fire
+    // even if the request races.
+    injectedSessions.add(sessionID);
+
+    try {
+      const port = await resolveDashboardPort();
+      if (!port) return;
+
+      const query = buildSearchQuery(userMessageText);
+      if (!query) return;
+
+      const results = await searchMemory(port, query, 5);
+      if (results.length === 0) return;
+
+      const context = formatMemoryContext(results);
+
+      // We can't directly push to output.system here (we're in the `event` hook).
+      // Instead, we use the `pendingInjections` map in the RuntimeContext
+      // (same mechanism used for loop guard injections).
+      // The `experimental.chat.system.transform` hook already checks this map.
+      // We store it under a special marker so the transform hook can distinguish it.
+      // But wait — pendingInjections only holds ONE message at a time.
+      // We need a separate mechanism... Actually, looking at the transform hook:
+      //   const pending = ctx.pendingInjections.get(sessionID);
+      //   if (pending) { output.system.push(pending); ctx.pendingInjections.delete(sessionID); }
+      // This only allows ONE injection at a time.
+      //
+      // Alternative: use a separate Map for memory injections.
+      // The transform hook checks ctx._memoryInjections.get(sessionID) separately.
+      //
+      // Since we control both the injection (here) and the hook (in index.ts),
+      // we can add a second map. Let's use ctx._memoryPendingInjections.
+
+      // Signal that we have memory to inject by setting a flag.
+      // The actual injection happens in experimental.chat.system.transform.
+      // We use a module-level store that the transform hook reads.
+      _pendingMemoryContext.set(sessionID, context);
+    } catch (err) {
+      // Non-fatal: don't let a failed memory injection break session start.
+      logger.debug(
+        `bizar: memory-inject failed for session ${sessionID}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  return { memoryInject };
+}
+
+/**
+ * Module-level store for pending memory context injections.
+ * The `experimental.chat.system.transform` hook reads this and injects
+ * the queued context into the system prompt.
+ */
+export const _pendingMemoryContext = new Map<string, string>();
+
+/**
+ * Retrieve and clear any pending memory context for a session.
+ * Called from `experimental.chat.system.transform`.
+ */
+export function popMemoryContext(sessionID: string): string | null {
+  const ctx = _pendingMemoryContext.get(sessionID);
+  _pendingMemoryContext.delete(sessionID);
+  return ctx ?? null;
+}

package/plugins/bizar/src/hooks/memory-write-on-end.ts

@@ -0,0 +1,188 @@
+/**
+ * plugins/bizar/src/hooks/memory-write-on-end.ts
+ *
+ * Session-end memory write hook.
+ *
+ * Fires on `session.idle` (natural completion) or `session.error` events.
+ * Writes an automated session summary to the memory vault at:
+ *   sessions/<date>-<session-id>.md
+ *
+ * Key design decisions:
+ *   - Configurable: `settings.memory.writeOnSessionEnd` (default true)
+ *   - Non-blocking: write is fire-and-forget (success logged, failure warned)
+ *   - Idempotent: if the same session fires multiple terminal events,
+ *     only the first write succeeds (check if note already exists via API)
+ *   - Uses the dashboard API (POST /api/memory/notes) for consistency
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import type { Logger } from "../logger.js";
+
+const SESSION_NOTES_PREFIX = "sessions/";
+
+export interface MemoryWriteOnEndDeps {
+  worktree: string;
+  logger: Logger;
+  enabled: boolean;
+}
+
+/**
+ * Resolve the dashboard server port. Returns null if not available.
+ */
+export async function resolveDashboardPort(): Promise<number | null> {
+  const portFile = join(homedir(), ".config", "bizar", "dashboard.port");
+  if (existsSync(portFile)) {
+    try {
+      const raw = readFileSync(portFile, "utf8").trim();
+      const n = parseInt(raw, 10);
+      if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
+    } catch {
+      // fall through
+    }
+  }
+  const envPort = process.env.BIZAR_DASHBOARD_PORT;
+  if (envPort) {
+    const n = parseInt(envPort, 10);
+    if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
+  }
+  return null;
+}
+
+interface SessionEndInfo {
+  sessionID: string;
+  agent: string;
+  startedAt: number;
+  endedAt: number;
+  status: "idle" | "error" | "killed";
+  error?: string;
+}
+
+/**
+ * Build a session summary note body.
+ */
+function buildSessionSummary(
+  info: SessionEndInfo,
+  conversationPreview: string,
+): string {
+  const durationMin = Math.round((info.endedAt - info.startedAt) / 60_000);
+  const started = new Date(info.startedAt).toISOString();
+  const ended = new Date(info.endedAt).toISOString();
+
+  const lines: string[] = [
+    `# Session Summary: ${info.sessionID.slice(0, 8)}…`,
+    "",
+    `**Agent:** ${info.agent}`,
+    `**Started:** ${started}`,
+    `**Ended:** ${ended}`,
+    `**Duration:** ~${durationMin} min`,
+    `**Status:** ${info.status}${info.error ? ` — ${info.error}` : ""}`,
+    "",
+    "## Conversation Preview",
+    "",
+    conversationPreview.slice(0, 2000),
+    "",
+    "## Key Decisions",
+    "",
+    "- *(add your key decisions here)*",
+    "",
+    "## Tools Used",
+    "",
+    "- *(tools used during this session)*",
+    "",
+    "## Errors / Issues",
+    info.error ? `\n${info.error}\n` : "- *(no errors)*",
+  ];
+
+  return lines.join("\n");
+}
+
+/**
+ * Write a session summary note to the memory vault.
+ */
+async function writeSessionSummary(
+  port: number,
+  info: SessionEndInfo,
+  conversationPreview: string,
+  worktree: string,
+  logger: Logger,
+): Promise<void> {
+  const date = new Date(info.startedAt).toISOString().slice(0, 10); // YYYY-MM-DD
+  const slug = `${date}-${info.sessionID.slice(0, 8)}.md`;
+  const relPath = `${SESSION_NOTES_PREFIX}${slug}`;
+
+  const body = buildSessionSummary(info, conversationPreview);
+
+  const payload = {
+    path: relPath,
+    frontmatter: {
+      type: "session-summary",
+      session_id: info.sessionID,
+      started_at: new Date(info.startedAt).toISOString(),
+      ended_at: new Date(info.endedAt).toISOString(),
+      duration_minutes: Math.round((info.endedAt - info.startedAt) / 60_000),
+      agent: info.agent,
+      project: worktree.split("/").pop() ?? "unknown",
+      tags: ["auto-generated"],
+      status: info.status,
+    },
+    body,
+  };
+
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/memory/notes`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    if (res.ok || res.status === 409) {
+      // 409 = already exists (idempotent)
+      logger.debug(`bizar: session summary written for ${info.sessionID.slice(0, 8)}`);
+    } else {
+      const text = await res.text().catch(() => "");
+      logger.warn(`bizar: session summary write failed for ${info.sessionID.slice(0, 8)}: HTTP ${res.status} — ${text.slice(0, 200)}`);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`bizar: session summary write failed for ${info.sessionID.slice(0, 8)}: ${msg}`);
+  }
+}
+
+/**
+ * Create the session-end memory write hook.
+ *
+ * Usage in index.ts `event` hook:
+ *   const { memoryWriteOnEnd } = createMemoryWriteOnEnd(deps);
+ *   if (type === "session.idle" || type === "session.error") {
+ *     memoryWriteOnEnd(sessionID, eventPayload).catch(() => {});
+ *   }
+ */
+export function createMemoryWriteOnEnd(deps: MemoryWriteOnEndDeps) {
+  const { logger } = deps;
+
+  /** Sessions that have already been written (idempotency). */
+  const _writtenSessions = new Set<string>();
+
+  async function memoryWriteOnEnd(
+    sessionID: string,
+    info: SessionEndInfo,
+    conversationPreview: string,
+  ): Promise<void> {
+    if (!deps.enabled) return;
+    if (_writtenSessions.has(sessionID)) return;
+    _writtenSessions.add(sessionID);
+
+    const port = await resolveDashboardPort();
+    if (!port) {
+      logger.debug(`bizar: session-end memory write skipped — dashboard not running`);
+      return;
+    }
+
+    await writeSessionSummary(port, info, conversationPreview, deps.worktree, logger);
+  }
+
+  return { memoryWriteOnEnd };
+}

package/plugins/bizar/src/opencode-runner.ts

@@ -51,7 +51,13 @@ import { createWriteStream, mkdirSync, existsSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Subprocess } from "bun";
 
-export type AgentState = "starting" | "running" | "done" | "failed" | "killed";
+export type AgentState =
+  | "starting"
+  | "running"
+  | "paused"
+  | "done"
+  | "failed"
+  | "killed";
 
 export interface AgentStatus {
   state: AgentState;
@@ -373,6 +379,86 @@ export function killAgent(
   return { ok: true };
 }
 
+/**
+ * v5.x — Pause a tracked agent by sending SIGSTOP. POSIX only —
+ * Windows has no signal model and returns `ok: false`. Idempotent
+ * against an exited process (returns `ok: true` with a note).
+ *
+ * The agent's `state` flips to `"paused"` so {@link getStatus}
+ * reflects the new lifecycle accurately.
+ */
+export function pauseAgent(
+  processId: number,
+): { ok: boolean; error?: string } {
+  if (process.platform === "win32") {
+    return { ok: false, error: "pause unsupported on win32" };
+  }
+  const rec = agents.get(processId);
+  if (!rec) return { ok: false, error: "no such process" };
+  if (rec.status.endedAt !== undefined) return { ok: true, error: "already_exited" };
+  if (rec.status.state === "paused") return { ok: true };
+  try {
+    rec.proc.kill("SIGSTOP");
+    rec.status.state = "paused";
+    return { ok: true };
+  } catch (err: unknown) {
+    return {
+      ok: false,
+      error: `SIGSTOP failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/**
+ * v5.x — Resume a paused agent by sending SIGCONT. POSIX only. No-op
+ * against an exited process.
+ */
+export function resumeAgent(
+  processId: number,
+): { ok: boolean; error?: string } {
+  if (process.platform === "win32") {
+    return { ok: false, error: "resume unsupported on win32" };
+  }
+  const rec = agents.get(processId);
+  if (!rec) return { ok: false, error: "no such process" };
+  if (rec.status.endedAt !== undefined) return { ok: true, error: "already_exited" };
+  if (rec.status.state !== "paused") return { ok: true };
+  try {
+    rec.proc.kill("SIGCONT");
+    rec.status.state = "running";
+    return { ok: true };
+  } catch (err: unknown) {
+    return {
+      ok: false,
+      error: `SIGCONT failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/**
+ * v5.x — Liveness check for a previously spawned PID. Uses
+ * `process.kill(pid, 0)` which sends no signal — it just probes the
+ * process table. Returns `false` for unknown / exited PIDs and on
+ * permission errors.
+ *
+ * NOTE: this is a separate registry from the in-memory `agents` map.
+ * After a plugin restart, the in-memory map is empty but the
+ * underlying PID may still be alive. The function probes the OS, so
+ * it answers the underlying question even when the agent record has
+ * been forgotten.
+ */
+export function isAlive(processId: number): boolean {
+  if (!Number.isFinite(processId) || processId <= 0) return false;
+  try {
+    // Signal 0 = probe only. Returns true if the process exists and
+    // we have permission to signal it.
+    process.kill(processId, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * List every tracked agent. Used by the plugin's startup to reconcile
  * state and by tests.

package/plugins/bizar/src/tools/bg-pause.ts

@@ -0,0 +1,77 @@
+/**
+ * plugins/bizar/src/tools/bg-pause.ts
+ *
+ * v5.x — `bizar_pause` tool. Sends SIGSTOP to a running background
+ * agent's subprocess (POSIX only). The InstanceManager flips the
+ * in-memory status to `"paused"` and persists the change.
+ *
+ * The companion tool `bizar_resume` ({@link ./bg-resume.ts}) reverses
+ * the action via SIGCONT.
+ *
+ * Odin-only — same auth model as the rest of the bg tools.
+ */
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+
+import type { InstanceManager } from "../background.js";
+import type { Logger } from "../logger.js";
+
+export interface BgPauseDeps {
+  instanceManager: InstanceManager;
+  logger: Logger;
+}
+
+export function createBgPauseTool(deps: BgPauseDeps) {
+  return tool({
+    description:
+      "Pause a running background agent by sending SIGSTOP to its subprocess. " +
+      "Only Odin may pause. No-op on already-paused instances. " +
+      "POSIX only — on Windows this returns an `unsupported_on_win32` error.",
+    args: {
+      instanceId: z
+        .string()
+        .min(1)
+        .describe("Instance id returned by bizar_spawn_background."),
+    },
+    execute: async (rawArgs, ctx) => {
+      if (ctx.agent !== "odin") {
+        return {
+          output: JSON.stringify({
+            error:
+              "Only Odin can pause background agents. Use bizar_status to inspect or ask Odin to pause.",
+          }),
+        };
+      }
+      const args = rawArgs as { instanceId: string };
+      try {
+        const result = await deps.instanceManager.pause(args.instanceId);
+        if (!result.ok) {
+          return {
+            output: JSON.stringify({
+              error: result.error || "pause failed",
+              instanceId: args.instanceId,
+            }),
+          };
+        }
+        return {
+          output: JSON.stringify({
+            instanceId: args.instanceId,
+            status: "paused",
+          }),
+        };
+      } catch (err: unknown) {
+        deps.logger.warn(
+          `bizar: pause(${args.instanceId}) threw: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        return {
+          output: JSON.stringify({
+            error: `pause threw: ${err instanceof Error ? err.message : String(err)}`,
+            instanceId: args.instanceId,
+          }),
+        };
+      }
+    },
+  });
+}