cueloop 0.1.0-alpha.8 → 0.1.0-alpha.81

package/package.json

@@ -1,37 +1,44 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.81",
+  "description": "Terminal review surface for coding agents: annotate plans and diffs, return a message, send structured feedback back",
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
   "license": "Apache-2.0",
-  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/cli"
+  },
   "bin": {
     "cueloop": "./src/main.ts"
   },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "exports": {
     ".": "./src/main.ts"
   },
-  "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.8",
-    "@cueloop/daemon": "0.1.0-alpha.8",
-    "@cueloop/client": "0.1.0-alpha.8"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "engines": {
-    "bun": ">=1.3.0"
+  "scripts": {
+    "build:binary": "bun build --compile --minify --external cpu-features ./src/main.ts --outfile dist/cueloop"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mmurakaru/cueloop.git",
-    "directory": "packages/cli"
-  },
-  "homepage": "https://github.com/mmurakaru/cueloop#readme",
-  "bugs": {
-    "url": "https://github.com/mmurakaru/cueloop/issues"
+  "dependencies": {
+    "@cueloop/adapters": "0.1.0-alpha.81",
+    "@cueloop/client": "0.1.0-alpha.81",
+    "@cueloop/daemon": "0.1.0-alpha.81",
+    "@cueloop/schema": "0.1.0-alpha.81",
+    "@modelcontextprotocol/server": "2.0.0",
+    "@valibot/to-json-schema": "1.4.0",
+    "valibot": "^1.4.2"
   },
-  "description": "Terminal review surface for coding agents: annotate plans and diffs, return a verdict, send structured feedback back"
-}
+  "engines": {
+    "bun": ">=1.3.0"
+  }
+}

package/src/actions-command.ts

@@ -0,0 +1,49 @@
+/**
+ * `cueloop actions list [--session <id>]` - print the quick-action vocabulary
+ * (the same presets a human picks in the marker popover) so a review-side agent
+ * can reference one by name or index via `session annotate --action`. With
+ * `--session`, the vocabulary comes from that session's repo (matching what
+ * `--action` will resolve); otherwise from the caller's cwd. JSON on stdout.
+ */
+
+import { loadConfig } from "@cueloop/client/config";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { parseArgs, stringFlag } from "./args";
+
+export async function actionsCommand(argv: string[]): Promise<number> {
+  const { positional, flags } = parseArgs(argv);
+  const primitive = positional[0] ?? "list";
+
+  if (primitive !== "list") {
+    console.error("usage: cueloop actions list [--session <id>]");
+
+    return 2;
+  }
+  const role = stringFlag(flags, "role") === "agent" ? "agent" : undefined;
+  const repoRoot = await repoRootForSession(stringFlag(flags, "session"), role);
+  const actions = loadConfig({ repoRoot }).actions;
+  const numbered = actions.map((action, index) => ({
+    index: index + 1,
+    prompt: action.prompt,
+    metadata: action.metadata,
+  }));
+
+  console.log(JSON.stringify(numbered, null, 2));
+
+  return 0;
+}
+
+/** The repo the given session lives in, or the caller's cwd when no session is named. */
+async function repoRootForSession(
+  sessionId: string | undefined,
+  role: "agent" | undefined,
+): Promise<string> {
+  if (sessionId === undefined) return process.cwd();
+  const client = await DaemonClient.connect({ autostart: true, role });
+
+  try {
+    return (await client.sessionGet(sessionId)).workspace.repoRoot;
+  } finally {
+    client.close();
+  }
+}

package/src/args.ts

@@ -1,5 +1,7 @@
 /** Tiny flag parser: --key value, --key=value, boolean --flag, positionals. */
 
+import * as v from "valibot";
+
 export interface ParsedArgs {
   positional: string[];
   flags: Record<string, string | boolean>;
@@ -8,18 +10,22 @@ export interface ParsedArgs {
 export function parseArgs(argv: string[]): ParsedArgs {
   const positional: string[] = [];
   const flags: Record<string, string | boolean> = {};
+
   for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]!;
-    if (!a.startsWith("--")) {
-      positional.push(a);
+    const argument = argv[i]!;
+
+    if (!argument.startsWith("--")) {
+      positional.push(argument);
       continue;
     }
-    const eq = a.indexOf("=");
-    if (eq !== -1) {
-      flags[a.slice(2, eq)] = a.slice(eq + 1);
+    const equalsIndex = argument.indexOf("=");
+
+    if (equalsIndex !== -1) {
+      flags[argument.slice(2, equalsIndex)] = argument.slice(equalsIndex + 1);
     } else {
-      const key = a.slice(2);
+      const key = argument.slice(2);
       const next = argv[i + 1];
+
       if (next !== undefined && !next.startsWith("--")) {
         flags[key] = next;
         i++;
@@ -28,10 +34,15 @@ export function parseArgs(argv: string[]): ParsedArgs {
       }
     }
   }
+
   return { positional, flags };
 }
 
-export function flagStr(flags: Record<string, string | boolean>, key: string): string | undefined {
-  const v = flags[key];
-  return typeof v === "string" ? v : undefined;
+export function stringFlag(
+  flags: Record<string, string | boolean>,
+  key: string,
+): string | undefined {
+  const result = v.safeParse(v.string(), flags[key]);
+
+  return result.success ? result.output : undefined;
 }

package/src/codex-hook-command.ts

@@ -0,0 +1,21 @@
+import { CodexHookInputSchema, runCodexHook } from "@cueloop/adapters/codex/hook";
+import * as v from "valibot";
+
+/** Read one Codex lifecycle event and return its optional tool rewrite. */
+export async function codexHookCommand(): Promise<number> {
+  try {
+    const input = v.parse(
+      CodexHookInputSchema,
+      JSON.parse(await new Response(Bun.stdin.stream()).text()),
+    );
+    const output = runCodexHook(input);
+
+    if (output) console.log(JSON.stringify(output));
+
+    return 0;
+  } catch (error) {
+    console.error(`cueloop Codex hook failed: ${String(error)}`);
+
+    return 1;
+  }
+}

package/src/codex-mcp-command.ts

@@ -0,0 +1,104 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { toJsonSchema } from "@valibot/to-json-schema";
+import * as v from "valibot";
+import { createCodexDeliveryService } from "@cueloop/adapters/codex/delivery-service";
+import { createCodexSessionRegistry } from "@cueloop/adapters/codex/session-registry";
+import { runHarnessBridge } from "@cueloop/adapters/harness-bridge";
+import { cueloopHome } from "@cueloop/daemon/paths";
+import { WORKFLOW_KINDS } from "@cueloop/schema";
+import { CLI_VERSION } from "./version";
+
+const OpenThreadInputSchema = v.object({
+  workflow: v.picklist(WORKFLOW_KINDS),
+  content: v.optional(v.string()),
+  proposal: v.optional(v.string()),
+  pullRequestReference: v.optional(v.string()),
+  title: v.optional(v.string()),
+  harnessSessionId: v.pipe(v.string(), v.minLength(1)),
+  cwd: v.string(),
+  hookToken: v.pipe(v.string(), v.minLength(1)),
+});
+const RefineCorpusInputSchema = v.object({});
+
+function mcpInputSchema<TSchema extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>(
+  schema: TSchema,
+) {
+  const convert = () => toJsonSchema(schema);
+
+  return {
+    ...schema,
+    "~standard": {
+      ...schema["~standard"],
+      jsonSchema: { input: convert, output: convert },
+    },
+  };
+}
+
+/** Expose the shared Thread workflows to a standard Codex session. */
+export function createCodexMcpServer(home = cueloopHome()): McpServer {
+  const server = new McpServer({ name: "cueloop", version: CLI_VERSION });
+  const sessions = createCodexSessionRegistry(home);
+
+  server.registerTool(
+    "open_thread",
+    {
+      description:
+        "Submit or revise a cueloop Thread for plan, reply, prototype, diff, review, or refine.",
+      inputSchema: mcpInputSchema(OpenThreadInputSchema),
+    },
+    async (input) => {
+      try {
+        if (!sessions.authorized(input.harnessSessionId, input.cwd, input.hookToken)) {
+          throw new Error(
+            "cueloop Codex session is not authorized; trust the plugin hooks and restart Codex",
+          );
+        }
+        const { hookToken: _hookToken, ...threadInput } = input;
+        const result = await runHarnessBridge(
+          { operation: "open", harness: "codex", ...threadInput },
+          home,
+        );
+
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { isError: true, content: [{ type: "text", text: String(error) }] };
+      }
+    },
+  );
+  server.registerTool(
+    "refine_corpus",
+    {
+      description: "Analyze past cueloop Threads before proposing a refine writeback.",
+      inputSchema: mcpInputSchema(RefineCorpusInputSchema),
+    },
+    async () => {
+      try {
+        const result = await runHarnessBridge({ operation: "refine" }, home);
+
+        return {
+          content: [{ type: "text", text: result.operation === "refine" ? result.report : "" }],
+        };
+      } catch (error) {
+        return { isError: true, content: [{ type: "text", text: String(error) }] };
+      }
+    },
+  );
+
+  return server;
+}
+
+/** Keep the MCP transport and durable Codex Message poller alive together. */
+export async function codexMcpCommand(): Promise<number> {
+  const delivery = createCodexDeliveryService();
+
+  delivery.start();
+  const server = serveStdio(() => createCodexMcpServer(), {
+    onerror: (error) => console.error(`cueloop Codex MCP: ${String(error)}`),
+  });
+  await new Promise<void>((resolve) => process.stdin.once("end", resolve));
+  delivery.stop();
+  await server.close();
+
+  return 0;
+}

package/src/daemon-control.test.ts

@@ -0,0 +1,68 @@
+/**
+ * `cueloop stop`'s primitive against a real detached daemon: stopping it clears
+ * the socket and pid so the next launch autostarts a fresh one (the self-heal
+ * `cueloop update` relies on), and stopping when none runs is a no-op.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { pidPath, socketPath } from "@cueloop/daemon/paths";
+import { restartCommand, stopDaemon } from "./daemon-control";
+
+let home: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-stop-"));
+});
+afterEach(async () => {
+  await stopDaemon(home).catch(() => undefined);
+  rmSync(home, { recursive: true, force: true });
+});
+
+test("stopDaemon stops a running daemon and clears its socket and pid", async () => {
+  // Arrange - a real detached daemon owns the home
+  const client = await DaemonClient.connect({ home, autostart: true });
+
+  client.close();
+  expect(existsSync(socketPath(home))).toBe(true);
+
+  // Act
+  const stopped = await stopDaemon(home);
+
+  // Assert - it reported a stop, and the daemon released its socket and pid
+  expect(stopped).toBe(true);
+  expect(existsSync(socketPath(home))).toBe(false);
+  expect(existsSync(pidPath(home))).toBe(false);
+}, 60_000);
+
+test("stopDaemon reports nothing to stop when no daemon is running", async () => {
+  expect(await stopDaemon(home)).toBe(false);
+});
+
+test("restartCommand replaces the daemon and reconnects", async () => {
+  const previousHome = process.env.CUELOOP_HOME;
+  const first = await DaemonClient.connect({ home, autostart: true });
+  const firstPid = (await first.ping()).pid;
+
+  first.close();
+  process.env.CUELOOP_HOME = home;
+
+  try {
+    expect(await restartCommand()).toBe(0);
+
+    const restarted = await DaemonClient.connect({ home, autostart: false });
+
+    try {
+      expect((await restarted.ping()).pid).not.toBe(firstPid);
+      expect(existsSync(socketPath(home))).toBe(true);
+    } finally {
+      restarted.close();
+    }
+  } finally {
+    if (previousHome === undefined) delete process.env.CUELOOP_HOME;
+    else process.env.CUELOOP_HOME = previousHome;
+  }
+}, 60_000);

package/src/daemon-control.ts

@@ -0,0 +1,104 @@
+/**
+ * Local daemon control: `cueloop stop` and `cueloop restart`, and the
+ * `stopDaemon` primitive `cueloop update` calls so a newer binary is not left
+ * talking to the old-version daemon (which refuses the handshake).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import * as v from "valibot";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { cueloopHome, pidPath, socketPath } from "@cueloop/daemon/paths";
+
+const ProcessIdSchema = v.pipe(
+  v.string(),
+  v.transform((raw) => Number(raw.trim())),
+  v.integer(),
+  v.minValue(1),
+);
+
+/** Signal the daemon through its pid file; callers only reach this while a socket proves it is live. */
+function signalDaemonByProcessId(home: string): boolean {
+  const path = pidPath(home);
+
+  if (!existsSync(path)) return false;
+  let raw: string;
+
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return false;
+  }
+  const parsed = v.safeParse(ProcessIdSchema, raw);
+
+  if (!parsed.success) return false;
+  try {
+    process.kill(parsed.output);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True once the stopped daemon has released its socket; false if it is still there at the deadline. */
+async function waitForSocketGone(home: string): Promise<boolean> {
+  const path = socketPath(home);
+  const deadline = Date.now() + 5_000;
+
+  while (Date.now() < deadline) {
+    if (!existsSync(path)) return true;
+    await Bun.sleep(50);
+  }
+
+  return !existsSync(path);
+}
+
+/**
+ * Stop the daemon that owns `home`, returning true once its socket is released.
+ * A live daemon is stopped by the owner-gated shutdown request, or, when it
+ * refuses the handshake (a version mismatch), by signalling its pid - safe
+ * because the socket proves the pid file is current. A home with no socket has
+ * no live daemon to stop, so its pid file is never trusted.
+ */
+export async function stopDaemon(home = cueloopHome()): Promise<boolean> {
+  if (!existsSync(socketPath(home))) return false;
+  try {
+    const client = await DaemonClient.connect({ home, autostart: false });
+
+    await client.shutdown();
+    client.close();
+  } catch {
+    if (!signalDaemonByProcessId(home)) return false;
+  }
+
+  return waitForSocketGone(home);
+}
+
+/** `cueloop stop` - stop the local daemon. */
+export async function stopCommand(): Promise<number> {
+  const home = cueloopHome();
+
+  if (!existsSync(socketPath(home))) {
+    console.log("no cueloop daemon is running");
+
+    return 0;
+  }
+  const stopped = await stopDaemon(home);
+
+  console.log(stopped ? "cueloop daemon stopped" : "cueloop daemon did not stop in time");
+
+  return stopped ? 0 : 1;
+}
+
+/** `cueloop restart` - stop the local daemon, then autostart a fresh one. */
+export async function restartCommand(): Promise<number> {
+  const home = cueloopHome();
+
+  await stopDaemon(home);
+  const client = await DaemonClient.connect({ home, autostart: true });
+
+  client.close();
+  console.log("cueloop daemon restarted");
+
+  return 0;
+}

package/src/dev-command.ts

@@ -0,0 +1,112 @@
+/**
+ * `cueloop dev`: open the TUI against an isolated dev home seeded once with a
+ * plan and a diff under this repo's project plus a standalone reply thread, so
+ * the Projects and Threads sidebar and the thread view are populated without a
+ * live agent. It never touches the real ~/.cueloop home.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { resolveWorkspace } from "@cueloop/daemon/thread-review";
+
+/** Bump whenever the seed content below changes, so a long-lived dev home refreshes instead of keeping
+ *  stale threads (an old seed's diff had no files, which showed as "No changes"). */
+const SEED_VERSION = 2;
+const SEED_TITLES = new Set([
+  "Read the repository",
+  "Review the accent change",
+  "A standalone thought",
+]);
+
+const SEED_PLAN = `# Read the repository
+
+A seeded plan so \`cueloop dev\` always has a thread to open.
+
+## Steps
+- open the thread view
+- move the cursor into the agent's text
+- type to leave a comment
+`;
+
+const SEED_REPLY = `A standalone thought, not tied to any repository.
+
+It lands under Threads in the sidebar rather than a project.
+`;
+
+const SEED_DIFF_PATH = "packages/client/src/theme.ts";
+const SEED_DIFF_OLD = '  accent: "#f5a3a3",\n';
+const SEED_DIFF_NEW = '  accent: "#cba6f7",\n';
+const SEED_DIFF = `diff --git a/${SEED_DIFF_PATH} b/${SEED_DIFF_PATH}
+--- a/${SEED_DIFF_PATH}
++++ b/${SEED_DIFF_PATH}
+@@ -1 +1 @@
+-${SEED_DIFF_OLD.trimEnd()}
++${SEED_DIFF_NEW.trimEnd()}
+`;
+
+async function seedDevSessions(client: DaemonClient): Promise<void> {
+  // the current repo carries a root commit, so its threads gather under a project
+  const project = await resolveWorkspace(process.cwd());
+  // a non-repo directory has no root commit, so its thread stays standalone
+  const standalone = await resolveWorkspace(tmpdir());
+
+  await client.sessionCreate(project, {
+    type: "plan",
+    content: SEED_PLAN,
+    meta: { title: "Read the repository" },
+  });
+  await client.sessionCreate(project, {
+    type: "diff",
+    content: SEED_DIFF,
+    meta: { title: "Review the accent change" },
+    files: [
+      {
+        path: SEED_DIFF_PATH,
+        oldContents: SEED_DIFF_OLD,
+        newContents: SEED_DIFF_NEW,
+        status: "modified",
+      },
+    ],
+  });
+  await client.sessionCreate(standalone, {
+    type: "reply",
+    content: SEED_REPLY,
+    meta: { title: "A standalone thought" },
+  });
+}
+
+/** Seed the dev home, refreshing the seed threads when SEED_VERSION moved on so a stale home never
+ *  keeps an old seed (which is why an aged home showed "No changes" - its diff thread had no files). */
+async function refreshDevSeed(client: DaemonClient, home: string): Promise<void> {
+  const versionFile = join(home, ".seed-version");
+  const stored = existsSync(versionFile) ? Number(readFileSync(versionFile, "utf8").trim()) : 0;
+  const existing = await client.sessionList();
+  if (existing.length > 0 && stored === SEED_VERSION) return;
+
+  await Promise.all(
+    existing
+      .filter((thread) => SEED_TITLES.has(thread.artifact.meta.title ?? ""))
+      .map((thread) => client.sessionDelete(thread.id)),
+  );
+  await seedDevSessions(client);
+  mkdirSync(dirname(versionFile), { recursive: true });
+  writeFileSync(versionFile, String(SEED_VERSION));
+}
+
+/** `cueloop dev`: seed an isolated dev home (refreshing a stale seed), then open the TUI on it. */
+export async function devCommand(): Promise<number> {
+  const home = (process.env.CUELOOP_HOME ??= join(homedir(), ".cueloop-dev"));
+
+  const client = await DaemonClient.connect({ autostart: true });
+  try {
+    await refreshDevSeed(client, home);
+  } finally {
+    client.close();
+  }
+
+  const { runClient } = await import("@cueloop/client");
+
+  return runClient({});
+}

package/src/harness-command.ts

@@ -0,0 +1,16 @@
+import { runHarnessBridge } from "@cueloop/adapters/harness-bridge";
+
+export async function harnessCommand(): Promise<number> {
+  try {
+    const request = JSON.parse(await new Response(Bun.stdin.stream()).text());
+    const response = await runHarnessBridge(request);
+
+    console.log(JSON.stringify(response));
+
+    return 0;
+  } catch (error) {
+    console.error(`cueloop harness bridge failed: ${String(error)}`);
+
+    return 1;
+  }
+}