@meandmyagents/agent-runner 0.1.1 → 0.1.3

package/README.md

@@ -3,24 +3,38 @@
 Local visible-session runner for MeAndMyAgents.
 
 ```bash
-npm exec --yes --registry=https://registry.npmjs.org/ --package=@meandmyagents/agent-runner@latest -- meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex
+npm exec --yes --registry=https://registry.npmjs.org/ --package=@meandmyagents/agent-runner@latest -- meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex-app
 ```
 
 The runner polls the cheap `/api/agent/events` endpoint with an agent-bound key.
-When work exists, it claims the wake event and launches a visible Codex or Claude
-CLI session in the task project path. It injects that same key into the child
-process as `MAA_API_KEY`, so one Mac can run several agent profiles without
-sharing identity. The launched agent uses MCP to start, complete, and drain the
-remaining actionable cards.
+When work exists, it claims the wake event and launches a visible Codex Desktop
+thread or Claude CLI session in the task project path. Codex app threads get the
+agent key in their per-thread MCP config, so one Mac can run several agent
+profiles without sharing identity. The launched agent uses MCP to start,
+complete, and drain the remaining actionable cards.
 
-On macOS, `--launcher codex` will also look for the bundled Codex app executable
+Use `--launcher codex-app` for Codex Desktop. It opens a Codex app-server
+controlled thread with approval policy `never` and sandbox
+`danger-full-access`, then waits for that turn to finish before polling again.
+Claude is launched with `--permission-mode bypassPermissions`. The runner prompt
+also includes the effective workflow instructions saved in MeAndMyAgents, tells
+the agent not to wait for human answers, and tells it to verify, commit, and
+push code changes before calling `complete_task`.
+
+On macOS, `--launcher codex-app` will look for the bundled Codex app executable
 at `/Applications/Codex.app/Contents/Resources/codex` when `codex` is not on
 `PATH`. If your launcher lives somewhere else, pass it explicitly:
 
 ```bash
-meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex --command /Applications/Codex.app/Contents/Resources/codex
+meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex-app --command /Applications/Codex.app/Contents/Resources/codex
 ```
 
 ```bash
 meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher claude --once
 ```
+
+For legacy terminal Codex behavior, `--launcher codex` is still available.
+
+If the runner reports that Codex Desktop remote control is not ready, open Codex
+Desktop once and make sure the standalone Codex install is available. The runner
+calls `codex remote-control` for you before opening the app-server thread.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meandmyagents/agent-runner",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local visible-session task runner for Me And My Agents.",
   "type": "module",
   "bin": {

package/src/runner.js

@@ -3,7 +3,10 @@ import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 
 export const defaultApiUrl = "https://meandmyagents.com/api";
-const supportedLaunchers = new Set(["codex", "claude"]);
+const codexAppLauncher = "codex-app";
+const supportedLaunchers = new Set(["codex", codexAppLauncher, "claude"]);
+const codexAppClientVersion = "0.1.3";
+const codexAppRequestTimeoutMs = 30_000;
 
 export function parseRunnerArgs(argv = process.argv.slice(2)) {
   const options = {
@@ -77,17 +80,38 @@ export function buildAgentPrompt({
   agentName,
   cardId,
   eventId,
-  projectName
+  project,
+  projectName,
+  workflow
 }) {
+  const workflowInstructions = Array.isArray(workflow?.instructions)
+    ? workflow.instructions
+    : [];
+  const defaultBranch = project?.defaultBranch || "the default branch";
+  const codebaseLines = project?.repositoryUrl
+    ? [
+        `Repository: ${project.repositoryUrl}`,
+        `Default branch: ${defaultBranch}`,
+        project.localPath ? `Local checkout path: ${project.localPath}` : null,
+        `If you modify code, run verification, then commit and push to ${defaultBranch} before complete_task.`
+      ].filter(Boolean)
+    : ["This project has no repository URL, so treat it as non-code work unless list_my_tasks says otherwise."];
+
   return [
     `You are ${agentName}. MeAndMyAgents has assigned work in ${projectName}.`,
     `Wake event: ${eventId}. First card that woke this session: ${cardId}.`,
+    "This is an autonomous runner wake-up. Do not wait for a human answer.",
+    "If you are blocked, add a card comment explaining the blocker and stop; do not sit idle asking a question.",
     "Use the MeAndMyAgents MCP server now.",
     "Call whoami to confirm your identity and project access.",
+    "Follow these workflow rules from MeAndMyAgents:",
+    ...workflowInstructions.map((instruction) => `- ${instruction}`),
+    "Codebase context:",
+    ...codebaseLines.map((line) => `- ${line}`),
     "Call list_my_tasks, then start_task on the next actionable card before editing files.",
     "Work only in the task codebase.localPath and only when codebase.canModifyCode is true.",
     "Add comments with useful progress and completion summaries.",
-    "Call complete_task when a task is ready for human testing.",
+    "Call complete_task with a useful summary when a task is ready for human testing.",
     "Call list_my_tasks again after each completion.",
     "Keep taking the next task until no actionable tasks remain, then stop."
   ].join("\n");
@@ -105,9 +129,23 @@ export function buildLaunchCommand({
     throw new Error(`Unsupported launcher: ${launcher}`);
   }
 
+  if (launcher === codexAppLauncher) {
+    return {
+      type: codexAppLauncher,
+      command: launcherCommand || launcherExecutableName(launcher),
+      args: [],
+      cwd,
+      prompt,
+      env: {
+        MAA_API_KEY: apiKey,
+        MAA_API_URL: mcpUrlFromApiUrl(apiUrl)
+      }
+    };
+  }
+
   return {
-    command: launcherCommand || launcher,
-    args: [prompt],
+    command: launcherCommand || launcherExecutableName(launcher),
+    args: buildLauncherArgs({ launcher, prompt, cwd }),
     cwd,
     env: {
       MAA_API_KEY: apiKey,
@@ -116,6 +154,60 @@ export function buildLaunchCommand({
   };
 }
 
+export function buildCodexAppThreadStartParams({ cwd, apiKey, apiUrl }) {
+  return {
+    approvalPolicy: "never",
+    config: apiKey
+      ? {
+          mcp_servers: {
+            me_and_my_agents: {
+              enabled: true,
+              http_headers: { Authorization: `Bearer ${apiKey}` },
+              url: mcpUrlFromApiUrl(apiUrl)
+            }
+          }
+        }
+      : null,
+    cwd,
+    developerInstructions:
+      "This thread was opened by the MeAndMyAgents local runner. Treat the user prompt as an autonomous task wake-up and use the MeAndMyAgents MCP server for task state.",
+    sandbox: "danger-full-access",
+    serviceName: "MeAndMyAgents",
+    sessionStartSource: "startup",
+    threadSource: "user"
+  };
+}
+
+export function buildCodexAppTurnStartParams({ threadId, cwd, prompt }) {
+  return {
+    approvalPolicy: "never",
+    cwd,
+    input: [{ type: "text", text: prompt }],
+    sandboxPolicy: { type: "dangerFullAccess" },
+    threadId
+  };
+}
+
+function buildLauncherArgs({ launcher, prompt, cwd }) {
+  if (launcher === "codex") {
+    return [
+      "--ask-for-approval",
+      "never",
+      "--sandbox",
+      "danger-full-access",
+      "--cd",
+      cwd,
+      prompt
+    ];
+  }
+
+  if (launcher === "claude") {
+    return ["--permission-mode", "bypassPermissions", prompt];
+  }
+
+  return [prompt];
+}
+
 export async function runCli(argv = process.argv.slice(2)) {
   const options = parseRunnerArgs(argv);
 
@@ -187,7 +279,9 @@ async function launchEvent(options, event) {
     agentName: event.agent?.name ?? options.launcher,
     cardId: event.card?.id ?? "unknown-card",
     eventId: event.id,
-    projectName: event.project?.name ?? "this project"
+    project: event.project,
+    projectName: event.project?.name ?? "this project",
+    workflow: event.workflow
   });
   const launch = buildLaunchCommand({
     launcher: options.launcher,
@@ -205,6 +299,14 @@ async function launchEvent(options, event) {
     `Launching ${launch.command} for ${event.card?.title ?? event.id} in ${launch.cwd}\n`
   );
 
+  if (options.launcher === codexAppLauncher) {
+    await launchCodexAppSession(launch, {
+      apiKey: options.key,
+      apiUrl: options.apiUrl
+    });
+    return;
+  }
+
   await new Promise((resolve, reject) => {
     const child = spawn(launch.command, launch.args, {
       cwd: launch.cwd,
@@ -222,6 +324,269 @@ async function launchEvent(options, event) {
   });
 }
 
+async function launchCodexAppSession(launch, { apiKey, apiUrl }) {
+  await ensureCodexAppRemoteControl(launch);
+
+  const proxy = spawn(launch.command, ["app-server", "proxy"], {
+    cwd: launch.cwd,
+    env: { ...process.env, ...launch.env },
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  const connection = createCodexAppConnection(proxy);
+
+  try {
+    await connection.request("initialize", {
+      clientInfo: {
+        name: "meandmyagents-runner",
+        title: "MeAndMyAgents runner",
+        version: codexAppClientVersion
+      },
+      capabilities: { experimentalApi: true }
+    });
+
+    const threadResponse = await connection.request(
+      "thread/start",
+      buildCodexAppThreadStartParams({ cwd: launch.cwd, apiKey, apiUrl })
+    );
+    const threadId = threadResponse?.thread?.id;
+    if (!threadId) {
+      throw new Error("Codex app-server did not return a thread id.");
+    }
+
+    const turnResponse = await connection.request(
+      "turn/start",
+      buildCodexAppTurnStartParams({
+        threadId,
+        cwd: launch.cwd,
+        prompt: launch.prompt
+      })
+    );
+    const turnId = turnResponse?.turn?.id;
+    process.stdout.write(
+      `Codex app thread ${threadId}${turnId ? ` turn ${turnId}` : ""} started.\n`
+    );
+
+    const completion = await connection.waitForNotification((message) => {
+      if (message.method !== "turn/completed") return false;
+      if (message.params?.threadId !== threadId) return false;
+      return !turnId || message.params?.turn?.id === turnId;
+    });
+    const completedTurn = completion.params?.turn;
+    if (completedTurn?.status === "failed") {
+      const message = completedTurn.error?.message ?? "Codex app turn failed.";
+      throw new Error(message);
+    }
+  } finally {
+    connection.close();
+  }
+}
+
+async function ensureCodexAppRemoteControl(launch) {
+  try {
+    await runProcess({
+      command: launch.command,
+      args: ["remote-control"],
+      cwd: launch.cwd,
+      env: launch.env,
+      timeoutMs: codexAppRequestTimeoutMs
+    });
+  } catch (error) {
+    throw new Error(
+      [
+        "Codex Desktop remote control is not ready.",
+        String(error?.message ?? error),
+        "Open Codex Desktop, make sure the standalone Codex install is available, then run the runner again."
+      ].join("\n")
+    );
+  }
+}
+
+function createCodexAppConnection(child) {
+  const pending = new Map();
+  const notificationWaiters = new Set();
+  const notificationBacklog = [];
+  let stdoutBuffer = "";
+  let stderr = "";
+  let closed = false;
+
+  child.stdout.on("data", (chunk) => {
+    stdoutBuffer += chunk.toString("utf8");
+    stdoutBuffer = consumeCodexAppMessages(stdoutBuffer, (message) => {
+      if (Object.prototype.hasOwnProperty.call(message, "id")) {
+        const waiter = pending.get(message.id);
+        if (!waiter) return;
+        pending.delete(message.id);
+        clearTimeout(waiter.timer);
+        if (message.error) {
+          waiter.reject(new Error(message.error.message ?? "Codex app-server request failed."));
+        } else {
+          waiter.resolve(message.result);
+        }
+        return;
+      }
+
+      let handled = false;
+      for (const waiter of notificationWaiters) {
+        if (waiter.predicate(message)) {
+          notificationWaiters.delete(waiter);
+          clearTimeout(waiter.timer);
+          waiter.resolve(message);
+          handled = true;
+        }
+      }
+      if (!handled) {
+        notificationBacklog.push(message);
+        if (notificationBacklog.length > 100) notificationBacklog.shift();
+      }
+    });
+  });
+
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString("utf8");
+  });
+
+  child.once("error", (error) => {
+    rejectAll(error);
+  });
+
+  child.once("exit", (code) => {
+    closed = true;
+    if (code && code !== 0) {
+      rejectAll(new Error(`Codex app-server proxy exited with code ${code}: ${stderr}`));
+    }
+  });
+
+  let nextId = 1;
+
+  return {
+    request(method, params) {
+      if (closed) {
+        return Promise.reject(new Error("Codex app-server proxy is closed."));
+      }
+
+      const id = nextId;
+      nextId += 1;
+      const message = { id, method, params };
+
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`Codex app-server request timed out: ${method}`));
+        }, codexAppRequestTimeoutMs);
+        pending.set(id, { resolve, reject, timer });
+        child.stdin.write(`${JSON.stringify(message)}\n`);
+      });
+    },
+
+    waitForNotification(predicate) {
+      if (closed) {
+        return Promise.reject(new Error("Codex app-server proxy is closed."));
+      }
+
+      const existingIndex = notificationBacklog.findIndex(predicate);
+      if (existingIndex >= 0) {
+        const [message] = notificationBacklog.splice(existingIndex, 1);
+        return Promise.resolve(message);
+      }
+
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          notificationWaiters.delete(waiter);
+          reject(new Error("Timed out waiting for Codex app turn completion."));
+        }, Number(process.env.MAA_CODEX_APP_TURN_TIMEOUT_MS ?? 21_600_000));
+        const waiter = { predicate, resolve, reject, timer };
+        notificationWaiters.add(waiter);
+      });
+    },
+
+    close() {
+      closed = true;
+      child.kill("SIGTERM");
+    }
+  };
+
+  function rejectAll(error) {
+    for (const waiter of pending.values()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(error);
+    }
+    pending.clear();
+
+    for (const waiter of notificationWaiters) {
+      clearTimeout(waiter.timer);
+      waiter.reject(error);
+    }
+    notificationWaiters.clear();
+  }
+}
+
+function consumeCodexAppMessages(buffer, onMessage) {
+  let nextBuffer = buffer;
+
+  while (nextBuffer.length > 0) {
+    const contentLengthMatch = nextBuffer.match(/^Content-Length: (\d+)\r?\n\r?\n/i);
+    if (contentLengthMatch) {
+      const headerLength = contentLengthMatch[0].length;
+      const contentLength = Number(contentLengthMatch[1]);
+      if (nextBuffer.length < headerLength + contentLength) break;
+      emitJson(nextBuffer.slice(headerLength, headerLength + contentLength), onMessage);
+      nextBuffer = nextBuffer.slice(headerLength + contentLength);
+      continue;
+    }
+
+    const newlineIndex = nextBuffer.indexOf("\n");
+    if (newlineIndex === -1) break;
+    const line = nextBuffer.slice(0, newlineIndex).trim();
+    nextBuffer = nextBuffer.slice(newlineIndex + 1);
+    if (line) emitJson(line, onMessage);
+  }
+
+  return nextBuffer;
+}
+
+function emitJson(value, onMessage) {
+  try {
+    onMessage(JSON.parse(value));
+  } catch {
+    // Ignore non-JSON process output; request timeouts surface protocol failures.
+  }
+}
+
+async function runProcess({ command, args, cwd, env, timeoutMs }) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`${command} ${args.join(" ")} timed out.`));
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      if (code && code !== 0) {
+        reject(new Error(stderr || stdout || `${command} exited with code ${code}`));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
 export function resolveLauncherCommand({
   launcher,
   launcherCommand = "",
@@ -235,12 +600,18 @@ export function resolveLauncherCommand({
     throw new Error(`Unsupported launcher: ${launcher}`);
   }
 
-  if (isCommandOnPath(launcher, { pathEnv, platform, exists })) return launcher;
+  const executableName = launcherExecutableName(launcher);
 
-  const knownPath = knownLauncherPaths(launcher, platform, homeDir).find((path) =>
-    exists(path)
-  );
-  return knownPath ?? launcher;
+  if (isCommandOnPath(executableName, { pathEnv, platform, exists })) {
+    return executableName;
+  }
+
+  const knownPath = knownLauncherPaths(launcher, platform, homeDir).find((path) => exists(path));
+  return knownPath ?? executableName;
+}
+
+function launcherExecutableName(launcher) {
+  return launcher === codexAppLauncher ? "codex" : launcher;
 }
 
 function isCommandOnPath(command, { pathEnv, platform, exists }) {
@@ -258,12 +629,12 @@ function isCommandOnPath(command, { pathEnv, platform, exists }) {
 function knownLauncherPaths(launcher, platform, homeDir) {
   if (platform === "darwin") {
     const commonBinPaths = [
-      homeDir ? join(homeDir, ".local/bin", launcher) : "",
-      join("/opt/homebrew/bin", launcher),
-      join("/usr/local/bin", launcher)
+      homeDir ? join(homeDir, ".local/bin", launcherExecutableName(launcher)) : "",
+      join("/opt/homebrew/bin", launcherExecutableName(launcher)),
+      join("/usr/local/bin", launcherExecutableName(launcher))
     ].filter(Boolean);
 
-    if (launcher === "codex") {
+    if (launcher === "codex" || launcher === codexAppLauncher) {
       return [
         ...commonBinPaths,
         "/Applications/Codex.app/Contents/Resources/codex"
@@ -273,7 +644,7 @@ function knownLauncherPaths(launcher, platform, homeDir) {
     return commonBinPaths;
   }
 
-  return homeDir ? [join(homeDir, ".local/bin", launcher)] : [];
+  return homeDir ? [join(homeDir, ".local/bin", launcherExecutableName(launcher))] : [];
 }
 
 function normalizeApiUrl(value) {
@@ -299,13 +670,14 @@ function helpText() {
   return `MeAndMyAgents agent runner
 
 Usage:
+  meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex-app
   meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex
   meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher claude --once
 
 Options:
   --key, -k       Required agent-bound API key.
   --api-url, -u   API base URL. Defaults to ${defaultApiUrl}.
-  --launcher, -l  Visible CLI launcher: codex or claude.
+  --launcher, -l  Visible launcher: codex-app, codex, or claude.
   --command, -c   Optional explicit executable path, e.g. /Applications/Codex.app/Contents/Resources/codex.
   --interval      Poll interval in seconds. Defaults to 10.
   --once          Check once, launch at most one visible session, then exit.