cueloop 0.1.0-alpha.10 → 0.1.0-alpha.101

package/package.json

@@ -1,37 +1,45 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.101",
+  "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.10",
-    "@cueloop/daemon": "0.1.0-alpha.10",
-    "@cueloop/client": "0.1.0-alpha.10"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "engines": {
-    "bun": ">=1.3.0"
+  "scripts": {
+    "build:binary": "bun build --compile --bytecode --format=esm --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.101",
+    "@cueloop/client": "0.1.0-alpha.101",
+    "@cueloop/daemon": "0.1.0-alpha.101",
+    "@cueloop/extension-api": "0.1.0-alpha.101",
+    "@cueloop/schema": "0.1.0-alpha.101",
+    "@modelcontextprotocol/server": "2.1.0",
+    "@valibot/to-json-schema": "1.8.0",
+    "valibot": "^1.5.0"
   },
-  "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/agent-harness.ts

@@ -0,0 +1,32 @@
+import { createPiHarness } from "@cueloop/adapters/pi/durable-harness";
+import { cueloopHome } from "@cueloop/daemon";
+import { createFxHarness } from "@cueloop/adapters/fx/harness";
+import { loadConfig } from "@cueloop/client/config";
+import type { AgentHarnessAdapter } from "@cueloop/schema";
+
+/** Select a locally installed harness; unsupported providers fail before a daemon starts. */
+export function configuredAgentHarness(): AgentHarnessAdapter | undefined {
+  const id = process.env.CUELOOP_AGENT_HARNESS ?? "pi";
+
+  if (id === "pi") return createPiHarness({ home: cueloopHome() });
+
+  if (id !== "fx") throw new Error(`Thread agent harness is not installed: ${id}`);
+
+  return fxHarness();
+}
+
+/** Resolve the experimental Thread agent flag from user and workspace TOML. */
+export function threadAgentEnabled(repoRoot: string): boolean {
+  return loadConfig({ repoRoot }).experimental.threadAgent;
+}
+
+export function installedAgentHarnesses() {
+  return {
+    pi: createPiHarness({ home: cueloopHome() }),
+    fx: fxHarness(),
+  };
+}
+
+function fxHarness(): AgentHarnessAdapter {
+  return createFxHarness({ command: [process.env.CUELOOP_FX_EXECUTABLE ?? "fx", "acp"] });
+}

package/src/args.ts

@@ -1,26 +1,32 @@
 /** 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>;
 }
 
-export function parseArgs(argv: string[]): ParsedArgs {
+export function parseArgs(argv: string[], booleanFlags: readonly 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("--")) {
+
+      if (!booleanFlags.includes(key) && next !== undefined && !next.startsWith("--")) {
         flags[key] = next;
         i++;
       } else {
@@ -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-delivery-worker-command.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonServer } from "@cueloop/daemon";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { createCodexSessionRegistry } from "@cueloop/adapters/codex/session-registry";
+import { runHarnessBridge } from "@cueloop/adapters/harness-bridge";
+import { startCodexDeliveryWorker } from "./codex-delivery-worker-command";
+
+const home = mkdtempSync(join(tmpdir(), "cueloop-codex-worker-"));
+const server = new DaemonServer({ home, idleExitMs: 0 });
+const codexBin = join(home, "codex");
+let worker: ReturnType<typeof Bun.spawn> | undefined;
+
+afterEach(async () => {
+  worker?.kill();
+  await worker?.exited;
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+test("a Codex reply is delivered without an MCP transport", async () => {
+  server.start();
+  writeFileSync(codexBin, '#!/bin/sh\nprintf "%s" "$5" > delivered.txt\n');
+  chmodSync(codexBin, 0o755);
+  createCodexSessionRegistry(home).activate("codex-session-1");
+  const opened = await runHarnessBridge(
+    {
+      operation: "open",
+      harness: "codex",
+      harnessSessionId: "codex-session-1",
+      cwd: home,
+      workflow: "plan",
+      content: "# Wait for feedback",
+    },
+    home,
+  );
+
+  if (opened.operation !== "open") throw new Error("expected open Thread");
+  const previousCodexBin = process.env.CUELOOP_CODEX_BIN;
+
+  // A reused PID belonging to this test process must not impersonate the worker.
+  writeFileSync(join(home, "codex-delivery-worker.pid"), String(process.pid));
+  process.env.CUELOOP_CODEX_BIN = codexBin;
+  worker = startCodexDeliveryWorker(home, [
+    process.execPath,
+    "run",
+    import.meta.dir + "/main.ts",
+    "codex-delivery-worker",
+  ]);
+  if (previousCodexBin === undefined) delete process.env.CUELOOP_CODEX_BIN;
+  else process.env.CUELOOP_CODEX_BIN = previousCodexBin;
+  expect(worker).toBeDefined();
+  const deadline = Date.now() + 5000;
+
+  while (!existsSync(join(home, "codex-delivery-worker.pid")) && Date.now() < deadline)
+    await Bun.sleep(20);
+  expect(existsSync(join(home, "codex-delivery-worker.pid"))).toBe(true);
+  const client = await DaemonClient.connect({ home });
+
+  try {
+    await client.sessionSendMessage(opened.threadId, "approved", "Continue after MCP exit.");
+    const deliveryPath = join(home, "delivered.txt");
+    const delivered = () =>
+      existsSync(deliveryPath) &&
+      readFileSync(deliveryPath, "utf8").includes("Continue after MCP exit.");
+
+    // Shell redirection creates the file before printf writes the delivered message.
+    while (!delivered() && Date.now() < deadline) await Bun.sleep(20);
+    expect(delivered()).toBe(true);
+  } finally {
+    client.close();
+  }
+});

package/src/codex-delivery-worker-command.ts

@@ -0,0 +1,99 @@
+import { closeSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { createCodexDeliveryService } from "@cueloop/adapters/codex/delivery-service";
+import { createCodexSessionRegistry } from "@cueloop/adapters/codex/session-registry";
+import { cueloopHome } from "@cueloop/daemon/paths";
+
+const EMPTY_SESSION_GRACE_MS = 30_000;
+
+function claimWorker(path: string): boolean {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const descriptor = openSync(path, "wx", 0o600);
+
+      writeSync(descriptor, String(process.pid));
+      closeSync(descriptor);
+
+      return true;
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+      const before = statSync(path);
+      const owner = Number(readFileSync(path, "utf8"));
+
+      if (Number.isSafeInteger(owner) && owner > 0) {
+        try {
+          process.kill(owner, 0);
+          const command = Bun.spawnSync(["ps", "-p", String(owner), "-o", "command="], {
+            stdout: "pipe",
+            stderr: "ignore",
+          });
+
+          if (
+            command.exitCode === 0 &&
+            /(?:^|\s)codex-delivery-worker(?:\s|$)/.test(command.stdout.toString())
+          )
+            return false;
+        } catch (cause) {
+          if (!(cause instanceof Error && "code" in cause && cause.code === "ESRCH")) return false;
+        }
+      } else if (Date.now() - before.mtimeMs < 5_000) {
+        return false;
+      }
+      if (statSync(path).ino !== before.ino) return false;
+      unlinkSync(path);
+    }
+  }
+
+  return false;
+}
+
+/** Run durable Codex Message delivery after the MCP transport has closed. */
+export async function codexDeliveryWorkerCommand(): Promise<number> {
+  const home = cueloopHome();
+  const lockPath = join(home, "codex-delivery-worker.pid");
+
+  if (!claimWorker(lockPath)) return 0;
+  const sessions = createCodexSessionRegistry(home);
+  const delivery = createCodexDeliveryService({
+    home,
+    codexBin: process.env.CUELOOP_CODEX_BIN,
+  });
+  let emptySince: number | undefined;
+
+  try {
+    delivery.start();
+    while (true) {
+      await Bun.sleep(1000);
+      emptySince = sessions.list().length === 0 ? (emptySince ?? Date.now()) : undefined;
+
+      if (emptySince !== undefined && Date.now() - emptySince >= EMPTY_SESSION_GRACE_MS) break;
+    }
+  } finally {
+    delivery.stop();
+    if (readFileSync(lockPath, "utf8") === String(process.pid)) unlinkSync(lockPath);
+  }
+
+  return 0;
+}
+
+/** The child owns the poller, so MCP transport shutdown does not stop delivery. */
+export function startCodexDeliveryWorker(
+  home: string,
+  command = [...process.argv.slice(0, -1), "codex-delivery-worker"],
+): ReturnType<typeof Bun.spawn> | undefined {
+  try {
+    const child = Bun.spawn(command, {
+      env: { ...process.env, CUELOOP_HOME: home },
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+      detached: true,
+    });
+
+    child.unref();
+
+    return child;
+  } catch (error) {
+    console.error(`cueloop Codex delivery worker: ${String(error)}`);
+  }
+}

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,94 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { toStandardJsonSchema } 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";
+import { startCodexDeliveryWorker } from "./codex-delivery-worker-command";
+
+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({});
+
+/** 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: toStandardJsonSchema(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,
+        );
+
+        if (result.operation === "open") startCodexDeliveryWorker(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: toStandardJsonSchema(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-command.ts

@@ -0,0 +1,57 @@
+import { OwnerAgentRelay } from "@cueloop/adapters/owner-agent-relay";
+/** Compose the local daemon with its installed harness adapters at the CLI boundary. */
+export async function daemonCommand(argv: string[]): Promise<number> {
+  const { DaemonServer } = await import("@cueloop/daemon");
+  // Explicit foreground never idle-exits; --autostart (a re-exec from the client)
+  // takes the normal idle-exit, matching the source main.ts entry.
+  const envIdle = process.env.CUELOOP_IDLE_EXIT_MS;
+  let idleExitMs: number | undefined = 0;
+
+  if (argv.includes("--autostart")) idleExitMs = envIdle ? Number(envIdle) : undefined;
+  const { configuredAgentHarness, installedAgentHarnesses, threadAgentEnabled } =
+    await import("./agent-harness");
+  let relay: OwnerAgentRelay | undefined;
+  const server = new DaemonServer({
+    onEvent: (event) => {
+      relay?.notify(event);
+      if (event.event !== "agent.updated") relay?.update(server.core.sessionList());
+    },
+    idleExitMs,
+    threadAgent: {
+      enabled: true,
+      enabledForThread: (thread) => threadAgentEnabled(thread.workspace.repoRoot),
+      adapter: configuredAgentHarness(),
+      adapters: installedAgentHarnesses(),
+    },
+  });
+  const path = server.start();
+
+  if (path === null) {
+    console.error("a cueloop daemon already owns this home - nothing to do");
+
+    return 1;
+  }
+  server.resumeAgents();
+  relay = new OwnerAgentRelay({
+    home: server.home,
+    enabled: (thread) => threadAgentEnabled(thread.workspace.repoRoot),
+    onError: (error) => console.error("[agent relay]", error),
+  });
+  relay.update(server.core.sessionList());
+  console.log(`cueloop daemon (foreground) on ${path}`);
+  const stop = async () => {
+    relay?.stop();
+    await server.shutdown();
+    process.exit(0);
+  };
+
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  process.once("exit", () => {
+    relay?.stop();
+    server.stop();
+  });
+  await new Promise(() => {}); // run until signalled
+
+  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);