@agentteams/runner 0.0.46

package/dist/utils/runner-cleanup.test.js

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { mock } from "node:test";
+import { logger } from "../logger.js";
+import { runCleanup } from "./runner-cleanup.js";
+const makeAuthDir = async () => {
+    return await mkdtemp(join(tmpdir(), "runner-cleanup-test-"));
+};
+const touchAge = async (filePath, ageMs) => {
+    const target = new Date(Date.now() - ageMs);
+    await utimes(filePath, target, target);
+};
+test.afterEach(() => {
+    mock.restoreAll();
+});
+test("runCleanup ignores missing log and history directories", async () => {
+    const authPath = await makeAuthDir();
+    try {
+        await runCleanup(authPath);
+    }
+    finally {
+        await rm(authPath, { recursive: true, force: true });
+    }
+});
+test("runCleanup deletes only files older than each directory TTL", async () => {
+    const authPath = await makeAuthDir();
+    const logDir = join(authPath, ".agentteams", "runner", "log");
+    const historyDir = join(authPath, ".agentteams", "runner", "history");
+    try {
+        await mkdir(logDir, { recursive: true });
+        await mkdir(historyDir, { recursive: true });
+        const oldLog = join(logDir, "old.log");
+        const freshLog = join(logDir, "fresh.log");
+        const oldHistory = join(historyDir, "old.md");
+        const freshHistory = join(historyDir, "fresh.md");
+        await writeFile(oldLog, "old");
+        await writeFile(freshLog, "fresh");
+        await writeFile(oldHistory, "old");
+        await writeFile(freshHistory, "fresh");
+        await touchAge(oldLog, 2 * 24 * 60 * 60 * 1000);
+        await touchAge(freshLog, 12 * 60 * 60 * 1000);
+        await touchAge(oldHistory, 4 * 24 * 60 * 60 * 1000);
+        await touchAge(freshHistory, 2 * 24 * 60 * 60 * 1000);
+        await runCleanup(authPath);
+        await assert.rejects(() => import("node:fs/promises").then(({ stat }) => stat(oldLog)));
+        await assert.rejects(() => import("node:fs/promises").then(({ stat }) => stat(oldHistory)));
+        await import("node:fs/promises").then(async ({ stat }) => {
+            await stat(freshLog);
+            await stat(freshHistory);
+        });
+    }
+    finally {
+        await rm(authPath, { recursive: true, force: true });
+    }
+});
+test("runCleanup logs a warning and continues when an expired file cannot be deleted", async () => {
+    const authPath = await makeAuthDir();
+    const logDir = join(authPath, ".agentteams", "runner", "log");
+    const historyDir = join(authPath, ".agentteams", "runner", "history");
+    const warnings = [];
+    mock.method(logger, "warn", (message, meta) => {
+        warnings.push({ message, meta });
+    });
+    try {
+        await mkdir(logDir, { recursive: true });
+        await mkdir(historyDir, { recursive: true });
+        const lockedFile = join(logDir, "locked.log");
+        const historyFile = join(historyDir, "history.md");
+        await writeFile(lockedFile, "locked");
+        await writeFile(historyFile, "history");
+        await touchAge(lockedFile, 2 * 24 * 60 * 60 * 1000);
+        await touchAge(historyFile, 4 * 24 * 60 * 60 * 1000);
+        await runCleanup(authPath, {
+            unlink: async (filePath) => {
+                if (filePath === lockedFile) {
+                    throw new Error("file is locked");
+                }
+                await import("node:fs/promises").then(async ({ unlink }) => unlink(filePath));
+            }
+        });
+        assert.equal(warnings.length >= 1, true);
+        await import("node:fs/promises").then(async ({ stat }) => {
+            await stat(lockedFile);
+            await assert.rejects(() => stat(historyFile));
+        });
+    }
+    finally {
+        await rm(authPath, { recursive: true, force: true });
+    }
+});
+//# sourceMappingURL=runner-cleanup.test.js.map

package/dist/utils/runner-cleanup.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-cleanup.test.js","sourceRoot":"","sources":["../../src/utils/runner-cleanup.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/runner-history.d.ts

@@ -0,0 +1,6 @@
+type RunnerHistoryPaths = {
+    currentHistoryPath: string | null;
+    parentHistoryPath: string | null;
+};
+export declare const resolveRunnerHistoryPaths: (authPath: string | null, triggerId: string, parentTriggerId: string | null) => RunnerHistoryPaths;
+export {};

package/dist/utils/runner-history.js

@@ -0,0 +1,13 @@
+import { join } from "node:path";
+const historyDirectory = (authPath) => join(authPath, ".agentteams", "runner", "history");
+const historyFilePath = (authPath, triggerId) => join(historyDirectory(authPath), `${triggerId}.md`);
+export const resolveRunnerHistoryPaths = (authPath, triggerId, parentTriggerId) => {
+    if (!authPath) {
+        return { currentHistoryPath: null, parentHistoryPath: null };
+    }
+    return {
+        currentHistoryPath: historyFilePath(authPath, triggerId),
+        parentHistoryPath: parentTriggerId ? historyFilePath(authPath, parentTriggerId) : null
+    };
+};
+//# sourceMappingURL=runner-history.js.map

package/dist/utils/runner-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-history.js","sourceRoot":"","sources":["../../src/utils/runner-history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAOjC,MAAM,gBAAgB,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAElG,MAAM,eAAe,GAAG,CAAC,QAAgB,EAAE,SAAiB,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,GAAG,SAAS,KAAK,CAAC,CAAC;AAErH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,QAAuB,EACvB,SAAiB,EACjB,eAA8B,EACV,EAAE;IACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAC/D,CAAC;IAED,OAAO;QACL,kBAAkB,EAAE,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC;QACxD,iBAAiB,EAAE,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI;KACvF,CAAC;AACJ,CAAC,CAAC"}

package/dist/utils/runner-history.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/runner-history.test.js

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import test from "node:test";
+import { resolveRunnerHistoryPaths } from "./runner-history.js";
+test("resolveRunnerHistoryPaths returns null paths when authPath is missing", () => {
+    assert.deepEqual(resolveRunnerHistoryPaths(null, "trigger-1", "parent-1"), {
+        currentHistoryPath: null,
+        parentHistoryPath: null
+    });
+});
+test("resolveRunnerHistoryPaths returns current and parent history paths", () => {
+    const authPath = join("workspace", "auth");
+    assert.deepEqual(resolveRunnerHistoryPaths(authPath, "trigger-1", "parent-1"), {
+        currentHistoryPath: join(authPath, ".agentteams", "runner", "history", "trigger-1.md"),
+        parentHistoryPath: join(authPath, ".agentteams", "runner", "history", "parent-1.md")
+    });
+});
+test("resolveRunnerHistoryPaths omits parent path when parent trigger is absent", () => {
+    const authPath = join("workspace", "auth");
+    assert.deepEqual(resolveRunnerHistoryPaths(authPath, "trigger-1", null), {
+        currentHistoryPath: join(authPath, ".agentteams", "runner", "history", "trigger-1.md"),
+        parentHistoryPath: null
+    });
+});
+//# sourceMappingURL=runner-history.test.js.map

package/dist/utils/runner-history.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-history.test.js","sourceRoot":"","sources":["../../src/utils/runner-history.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,IAAI,CAAC,uEAAuE,EAAE,GAAG,EAAE;IACjF,MAAM,CAAC,SAAS,CAAC,yBAAyB,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE;QACzE,kBAAkB,EAAE,IAAI;QACxB,iBAAiB,EAAE,IAAI;KACxB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,oEAAoE,EAAE,GAAG,EAAE;IAC9E,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,CAAC,SAAS,CAAC,yBAAyB,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE;QAC7E,kBAAkB,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,CAAC;QACtF,iBAAiB,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,CAAC;KACrF,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,2EAA2E,EAAE,GAAG,EAAE;IACrF,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,CAAC,SAAS,CAAC,yBAAyB,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;QACvE,kBAAkB,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,CAAC;QACtF,iBAAiB,EAAE,IAAI;KACxB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@agentteams/runner",
+  "version": "0.0.46",
+  "description": "AgentRunner - Background runner that polls and executes AI agent tasks",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentrunner": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx watch src/index.ts",
+    "test": "tsx --test \"src/**/*.test.ts\"",
+    "start": "node dist/index.js",
+    "init": "node dist/index.js init",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rlarua/AgentTeams-runner.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rlarua/AgentTeams-runner/issues"
+  },
+  "homepage": "https://agentteams.run",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "agentteams",
+    "runner",
+    "ai-agent",
+    "automation"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}

package/readme.md

@@ -0,0 +1,188 @@
+# @agentteams/runner
+
+[![GitHub](https://img.shields.io/badge/GitHub-rlarua%2FAgentTeams--runner-blue?logo=github)](https://github.com/rlarua/AgentTeams-runner)
+[![Issues](https://img.shields.io/github/issues/rlarua/AgentTeams-runner)](https://github.com/rlarua/AgentTeams-runner/issues)
+
+A background runner that polls and executes AI agent tasks from the AgentTeams platform.
+
+## Prerequisites
+
+- Node.js `18` or later
+- AgentTeams API server running
+- A daemon token issued from the web UI (`x-daemon-token`)
+
+## Installation
+
+```bash
+npm install -g @agentteams/runner
+```
+
+Verify the installation:
+
+```bash
+agentrunner --help
+```
+
+## Quick Start
+
+### 1. Initialize
+
+```bash
+agentrunner init --token <DAEMON_TOKEN>
+```
+
+The `init` command:
+
+1. Saves the token to `~/.agentteams/daemon.json`
+2. Validates the token against the API server
+3. Registers an OS-level autostart service and starts the runner immediately
+   - **macOS**: `~/Library/LaunchAgents/run.agentteams.runner.plist` (launchd)
+   - **Linux**: `~/.config/systemd/user/agentrunner.service` (systemd)
+   - **Windows**: Startup folder `agentrunner-start.vbs`
+
+### Options
+
+- `--token <token>` — **Required**. Daemon token issued from the web UI
+- `--no-autostart` — Optional. Skip autostart registration (manual start only)
+
+Examples:
+
+```bash
+# Standard setup (with autostart)
+agentrunner init --token daemon_xxxxx
+
+# Token-only setup (no autostart)
+agentrunner init --token daemon_xxxxx --no-autostart
+```
+
+### 2. Start (`start`)
+
+```bash
+agentrunner start
+```
+
+Running without a subcommand defaults to `start`:
+
+```bash
+agentrunner
+```
+
+> If autostart was registered via `init`, you do not need to run `start` manually.
+> The OS will start the runner automatically on login/boot.
+
+### 3. Check Status (`status`)
+
+```bash
+agentrunner status
+```
+
+Shows whether the runner process is active and whether autostart is registered.
+
+Example output:
+
+```
+[...] INFO Daemon is running { pid: 12345 }
+[...] INFO Autostart is enabled { platform: 'launchd' }
+```
+
+### 4. Stop (`stop`)
+
+```bash
+agentrunner stop
+```
+
+Sends SIGTERM to the running process for a graceful shutdown.
+
+> If autostart is registered, the OS may restart the runner automatically.
+> Use `uninstall` to stop completely.
+
+### 5. Restart (`restart`)
+
+```bash
+agentrunner restart
+```
+
+Restarts the runner using the current environment:
+
+- If autostart is registered, AgentRunner restarts through the registered OS service.
+- If autostart is not registered, AgentRunner starts a new detached background process.
+
+### 6. Update (`update`)
+
+```bash
+agentrunner update
+```
+
+Updates the globally installed `@agentteams/runner` package to the latest npm version and then restarts the runner.
+
+### 7. Uninstall (`uninstall`)
+
+```bash
+agentrunner uninstall
+```
+
+Performs the following:
+
+1. Stops the running process
+2. Removes the autostart service and deletes the service file
+3. Cleans up the PID file
+
+## Configuration
+
+Settings are resolved in the following priority order at runtime.
+
+### Token
+
+1. `AGENTTEAMS_DAEMON_TOKEN` environment variable
+2. `daemonToken` in `~/.agentteams/daemon.json`
+
+### Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `POLLING_INTERVAL_MS` | `30000` (30s) | Polling interval for pending triggers |
+| `IDLE_TIMEOUT_MS` | `600000` (10min) | Primary timeout. Stops a runner when it produces no stdout/stderr for the configured idle window |
+| `TIMEOUT_MS` | `86400000` (24h) | Fail-safe timeout. Stops a runner only if it stays alive for the full wall-clock limit |
+| `RUNNER_CMD` | `opencode` | Command used to execute agent tasks |
+| `CODEX_SANDBOX_LEVEL` | `workspace-write` | Codex runner sandbox level. Allowed values: `workspace-write`, `off` |
+| `LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
+| `DAEMON_VERBOSE_RUNNER_LOGS` | `true` | When `false`, reduces runner stdout/stderr to start/stop/error only |
+| `DAEMON_PROMPT_LOG_MODE` | `preview` | Prompt logging: `off`, `length`, `preview`, `full` |
+
+AgentRunner defaults to an idle-timeout-first policy. In normal operation, `IDLE_TIMEOUT_MS` is the control that ends stalled runs, while `TIMEOUT_MS` remains a 24-hour fail-safe for runaway processes.
+
+If you set `CODEX_SANDBOX_LEVEL=off`, AgentRunner launches Codex with `--dangerously-bypass-approvals-and-sandbox`. Use this only when you explicitly want full git write access and accept the reduced safety boundary.
+
+## How It Works
+
+After `start`, the runner operates in the following loop:
+
+1. Polls for pending triggers periodically
+2. Claims a trigger
+3. Fetches runtime info (working directory, API key)
+4. Executes `RUNNER_CMD run "<prompt>"`
+5. Updates trigger status based on exit code, idle timeout, or the 24-hour fail-safe timeout
+
+If a process is already running for the same `agentConfigId`, new triggers are `REJECTED`.
+
+## Logs
+
+- **Runner logs**: console output (forwarded to OS log system when autostarted)
+  - **macOS**: `/tmp/agentrunner.log`, `/tmp/agentrunner-error.log`
+  - **Linux**: `journalctl --user -u agentrunner -f`
+  - **Windows**: check the Startup folder script and the spawned background process
+- **Task logs**: `<workdir>/.agentteams/daemonLog/daemon-<triggerId>.log`
+
+## Troubleshooting
+
+### `Missing token. Usage: agentrunner init --token <token> ...`
+
+The `--token` flag was not provided to `init`.
+
+### `Daemon token is missing. Run 'agentrunner init --token <token>' first.`
+
+No token found at runtime. Run `init` first or set the `AGENTTEAMS_DAEMON_TOKEN` environment variable.
+
+## License
+
+Apache-2.0