@meandmyagents/agent-runner 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# MeAndMyAgents Agent Runner
+
+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
+```
+
+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.
+
+```bash
+meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher claude --once
+```

package/bin/meandmyagents-runner.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from "../src/runner.js";
+
+runCli().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@meandmyagents/agent-runner",
+  "version": "0.1.0",
+  "description": "Local visible-session task runner for Me And My Agents.",
+  "type": "module",
+  "bin": {
+    "meandmyagents-runner": "bin/meandmyagents-runner.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/src/runner.js

@@ -0,0 +1,238 @@
+import { spawn } from "node:child_process";
+
+export const defaultApiUrl = "https://meandmyagents.com/api";
+const supportedLaunchers = new Set(["codex", "claude"]);
+
+export function parseRunnerArgs(argv = process.argv.slice(2)) {
+  const options = {
+    command: argv[0] ?? "help",
+    apiUrl: defaultApiUrl,
+    intervalSeconds: 10,
+    key: "",
+    launcher: "codex",
+    once: false
+  };
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--key" || arg === "-k") {
+      options.key = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--api-url" || arg === "-u") {
+      options.apiUrl = normalizeApiUrl(argv[index + 1] ?? "");
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--launcher" || arg === "-l") {
+      options.launcher = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--interval") {
+      options.intervalSeconds = Number(argv[index + 1] ?? "10");
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--once") {
+      options.once = true;
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      options.command = "help";
+      continue;
+    }
+
+    throw new Error(`Unknown runner option: ${arg}`);
+  }
+
+  if (!Number.isFinite(options.intervalSeconds) || options.intervalSeconds < 2) {
+    options.intervalSeconds = 10;
+  }
+
+  if (!supportedLaunchers.has(options.launcher)) {
+    throw new Error(`Unsupported launcher: ${options.launcher}`);
+  }
+
+  return options;
+}
+
+export function buildAgentPrompt({
+  agentName,
+  cardId,
+  eventId,
+  projectName
+}) {
+  return [
+    `You are ${agentName}. MeAndMyAgents has assigned work in ${projectName}.`,
+    `Wake event: ${eventId}. First card that woke this session: ${cardId}.`,
+    "Use the MeAndMyAgents MCP server now.",
+    "Call whoami to confirm your identity and project access.",
+    "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 list_my_tasks again after each completion.",
+    "Keep taking the next task until no actionable tasks remain, then stop."
+  ].join("\n");
+}
+
+export function buildLaunchCommand({ launcher, prompt, cwd, apiKey, apiUrl }) {
+  if (!supportedLaunchers.has(launcher)) {
+    throw new Error(`Unsupported launcher: ${launcher}`);
+  }
+
+  return {
+    command: launcher,
+    args: [prompt],
+    cwd,
+    env: {
+      MAA_API_KEY: apiKey,
+      MAA_API_URL: mcpUrlFromApiUrl(apiUrl)
+    }
+  };
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const options = parseRunnerArgs(argv);
+
+  if (options.command === "help") {
+    process.stdout.write(helpText());
+    return;
+  }
+
+  if (options.command !== "watch") {
+    throw new Error(`Unknown runner command: ${options.command}`);
+  }
+
+  if (!options.key) {
+    throw new Error("Missing required --key maa_live_... argument");
+  }
+
+  await watchForEvents(options);
+}
+
+async function watchForEvents(options) {
+  process.stdout.write(
+    `Watching ${options.apiUrl}/agent/events for ${options.launcher} work...\n`
+  );
+
+  do {
+    const events = await fetchPendingEvents(options);
+
+    if (events.length > 0) {
+      const event = events[0];
+      await claimEvent(options, event.id);
+      await launchEvent(options, event);
+    } else if (options.once) {
+      process.stdout.write("No pending task events.\n");
+    }
+
+    if (!options.once) {
+      await sleep(options.intervalSeconds * 1000);
+    }
+  } while (!options.once);
+}
+
+async function fetchPendingEvents(options) {
+  const response = await fetch(`${options.apiUrl}/agent/events?limit=10`, {
+    headers: { authorization: `Bearer ${options.key}` }
+  });
+
+  if (!response.ok) {
+    throw new Error(`Event fetch failed: HTTP ${response.status} ${await response.text()}`);
+  }
+
+  const body = await response.json();
+  return Array.isArray(body.events) ? body.events : [];
+}
+
+async function claimEvent(options, eventId) {
+  const response = await fetch(`${options.apiUrl}/agent/events/${eventId}/claim`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${options.key}` }
+  });
+
+  if (!response.ok) {
+    throw new Error(`Event claim failed: HTTP ${response.status} ${await response.text()}`);
+  }
+}
+
+async function launchEvent(options, event) {
+  const cwd = resolveLaunchCwd(event);
+  const prompt = buildAgentPrompt({
+    agentName: event.agent?.name ?? options.launcher,
+    cardId: event.card?.id ?? "unknown-card",
+    eventId: event.id,
+    projectName: event.project?.name ?? "this project"
+  });
+  const launch = buildLaunchCommand({
+    launcher: options.launcher,
+    prompt,
+    cwd,
+    apiKey: options.key,
+    apiUrl: options.apiUrl
+  });
+
+  process.stdout.write(
+    `Launching ${launch.command} for ${event.card?.title ?? event.id} in ${launch.cwd}\n`
+  );
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(launch.command, launch.args, {
+      cwd: launch.cwd,
+      env: { ...process.env, ...launch.env },
+      stdio: "inherit"
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code && code !== 0) {
+        reject(new Error(`${launch.command} exited with code ${code}`));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function normalizeApiUrl(value) {
+  return (value || defaultApiUrl).replace(/\/$/, "").replace(/\/mcp$/, "");
+}
+
+function mcpUrlFromApiUrl(value) {
+  return `${normalizeApiUrl(value)}/mcp`;
+}
+
+export function resolveLaunchCwd(
+  event,
+  env = { homeDir: process.env.HOME || process.env.USERPROFILE, cwd: process.cwd() }
+) {
+  return event.project?.localPath || env.homeDir || env.cwd;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function helpText() {
+  return `MeAndMyAgents agent runner
+
+Usage:
+  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.
+  --interval      Poll interval in seconds. Defaults to 10.
+  --once          Check once, launch at most one visible session, then exit.
+`;
+}