@liy/agent-runner 0.1.0

package/README.md

@@ -0,0 +1,290 @@
+# @liy/agent-runner
+
+Sprite-local Task Agent Runner for Mote remote task execution.
+
+`agent-runner` is a production-mode executable. It expects the same contract used
+inside a Sprite Scratchpad:
+
+- a task spec JSON file
+- a reachable Mote Task Control Channel WebSocket
+- a configured harness executable such as Pi or Codex
+- terminal completion written to `state/completion.json`
+
+The runner uses the `rpcUrl` from `task-spec.json` exactly as supplied.
+
+It does not provide a fake control channel or a separate dev mode.
+
+## Build
+
+From the repository root:
+
+```bash
+pnpm --dir ./agent-runner build
+```
+
+This builds `dist/` and marks `dist/bin/agent-runner.js` executable.
+
+To build as part of the full workspace:
+
+```bash
+pnpm build
+```
+
+## Run
+
+From the repository root:
+
+```bash
+pnpm agent-runner -- --task-spec /absolute/path/to/state/task-spec.json
+```
+
+From this package:
+
+```bash
+pnpm --dir ./agent-runner start -- --task-spec /absolute/path/to/state/task-spec.json
+```
+
+Directly from the built executable:
+
+```bash
+./agent-runner/dist/bin/agent-runner.js --task-spec /absolute/path/to/state/task-spec.json
+```
+
+For a globally linked local binary:
+
+```bash
+pnpm dev:link-agent-runner
+agent-runner --task-spec /absolute/path/to/state/task-spec.json
+```
+
+## CLI Options
+
+```text
+agent-runner --task-spec <path> [--config <path>]
+```
+
+- `--task-spec <path>`: path to the host-authored task spec JSON file. Relative paths are resolved from the current working directory.
+- `--config <path>`: optional local-debug override for the runner config path. The Sprite default is `/home/sprite/.config/mote/agent-runner.json`.
+- `--help`, `-h`: print command help.
+
+## Runner Config
+
+The runner fails fast when its config file is missing or invalid. The Sprite
+baseline setup script writes the default config to:
+
+```text
+/home/sprite/.config/mote/agent-runner.json
+```
+
+Default Pi POC config:
+
+```json
+{
+  "defaultHarness": "pi",
+  "harnesses": {
+    "pi": {
+      "driver": "pi-rpc",
+      "command": "pi",
+      "provider": "deepseek",
+      "defaultModel": "deepseek-v4-flash",
+      "thinking": "high",
+      "secretEnv": ["DEEPSEEK_API_KEY"]
+    }
+  }
+}
+```
+
+## Task Spec
+
+The task spec is written by `mote-node` in production at:
+
+```text
+<workspace>/state/task-spec.json
+```
+
+An editable Pi RPC example lives at:
+
+```text
+agent-runner/examples/task-spec.pi-rpc.json
+```
+
+Minimal shape:
+
+```json
+{
+  "taskId": "aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa",
+  "workspaceDir": "/absolute/workspace",
+  "rpcUrl": "ws://127.0.0.1:3900/execute-task/tasks/aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa/rpc",
+  "userQuery": {
+    "queryText": "Why did yield change?"
+  },
+  "intent": {
+    "kind": "diagnosis"
+  },
+  "task": {
+    "title": "Investigate yield drivers",
+    "context": "Use approved tools only."
+  },
+  "toolProvisioning": {
+    "tools": []
+  },
+  "agentRunner": {
+    "harness": "pi",
+    "model": "deepseek-v4-flash"
+  },
+  "endpoints": {
+    "llmBaseUrl": "https://api.deepseek.com"
+  }
+}
+```
+
+The runner validates:
+
+- `workspaceDir` is absolute
+- `rpcUrl` is present
+- optional `agentRunner.harness` and `agentRunner.model` are strings
+- configured runner endpoints are HTTP(S) URLs
+- secret-like keys do not appear in the spec
+
+The current Fly Sprite Pi POC does not require or provision MCP. Future task
+specs may include `endpoints.mcpBaseUrl` again when MCP integration returns.
+
+## Harness Options
+
+Harness options live in the runner config. The task spec may only select
+`agentRunner.harness` and `agentRunner.model`; when either value is absent the
+runner uses `defaultHarness` and the selected harness `defaultModel`.
+
+### `pi-rpc`
+
+Pi RPC driver for Pi-backed task execution.
+
+Required fields:
+
+- `driver`: `"pi-rpc"`
+- `command`: executable name or absolute path, usually `"pi"`
+- `provider`: provider passed to Pi, for example `"deepseek"`
+- `model`: model passed to Pi, for example `"deepseek-v4-flash"`
+
+Optional fields:
+
+- `thinking`: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, or `"xhigh"`. Defaults to `"high"` inside the Pi RPC driver when absent.
+- `args`: extra vetted Pi flags appended after driver-owned flags.
+- `secretEnv`: required provider secret env vars passed through to Pi after the host explicitly forwards them to the runner process.
+
+The Pi RPC driver owns these flags and rejects duplicates in `args`:
+
+```text
+--mode
+--provider
+--model
+--thinking
+--no-extensions
+--no-prompt-templates
+--no-themes
+```
+
+It currently spawns Pi like:
+
+```text
+pi --mode rpc --provider deepseek --model deepseek-v4-flash --thinking high --no-extensions --no-prompt-templates --no-themes
+```
+
+The driver writes one Pi RPC `prompt` command to stdin, parses Pi stdout as
+byte-buffered JSONL, forwards Pi events as `task.progress`, and cancels with
+Pi `abort`, then `SIGTERM`, then `SIGKILL` after five seconds.
+
+Direct DeepSeek token example:
+
+```bash
+export DEEPSEEK_API_KEY=...
+agent-runner --task-spec /absolute/path/to/state/task-spec.json --config /absolute/path/to/agent-runner.json
+```
+
+Direct provider-token passthrough is a temporary risk-bearing path. The harness
+must never print, log, persist, or include that token in task artifacts. Mote
+still needs a gateway that protects LLM access tokens before this runtime is
+treated as production-safe.
+
+### `codex-jsonl`
+
+Codex JSONL driver preserving the existing line-oriented Codex behavior.
+
+Required fields:
+
+- `driver`: `"codex-jsonl"`
+- `command`: executable name or absolute path, usually `"codex"`
+
+Optional fields:
+
+- `args`: command arguments, for example `["exec", "--json", "--ephemeral"]`
+- `defaultModel`: model name exposed to the harness as `MOTE_TASK_MODEL` unless the task spec overrides it
+
+Example:
+
+```json
+{
+  "driver": "codex-jsonl",
+  "command": "codex",
+  "args": ["exec", "--json", "--ephemeral"],
+  "defaultModel": "gpt-5"
+}
+```
+
+## Runtime Contract
+
+The harness must write terminal completion to:
+
+```text
+<workspace>/state/completion.json
+```
+
+Completion shape:
+
+```json
+{
+  "status": "completed",
+  "summary": "Short result summary",
+  "artifactIds": []
+}
+```
+
+`status` must be one of:
+
+- `completed`
+- `partial`
+- `failed`
+- `cancelled`
+
+Artifacts referenced by `artifactIds` must live under:
+
+```text
+<workspace>/artifacts/<artifactId>/artifact.json
+```
+
+Dataset artifacts must also include:
+
+```text
+<workspace>/artifacts/<artifactId>/data.csv
+```
+
+`state/completion.json` is authoritative. Harness stdout/stderr and RPC events
+are progress telemetry only.
+
+## Local Production Smoke Checklist
+
+To run locally without Sprite leasing, you still need production-equivalent
+inputs:
+
+1. Start or provide a Mote API server with execute-task RPC routes.
+2. Create a task in the execute-task store.
+3. Create a workspace with `state/` and `artifacts/`.
+4. Write `state/task-spec.json` with a reachable `rpcUrl`.
+5. Ensure the harness command is on `PATH`.
+6. Run `agent-runner --task-spec ...`.
+
+For most local checks, use the test suite:
+
+```bash
+pnpm --dir ./agent-runner test
+```

package/dist/bin/agent-runner.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Parse CLI args, run the task agent, and set the process exit code.
+ *
+ * @param argv - CLI argv after the executable name.
+ */
+export declare function main(argv?: string[]): Promise<void>;
+/**
+ * Read the `--task-spec` command-line argument.
+ *
+ * @param argv - CLI argv after the executable name.
+ * @returns Resolved task spec path.
+ */
+export declare function readTaskSpecArg(argv: string[]): string;
+/**
+ * Read the optional `--config` command-line argument.
+ *
+ * @param argv - CLI argv after the executable name.
+ * @returns Resolved config path when provided.
+ */
+export declare function readConfigPathArg(argv: string[]): string | undefined;
+/**
+ * Decide whether this invocation should print command help.
+ *
+ * @param argv - CLI argv after the executable name.
+ * @returns Whether help was requested or no arguments were provided.
+ */
+export declare function shouldPrintHelp(argv: string[]): boolean;
+/**
+ * Format production-mode CLI help.
+ *
+ * @returns Help text.
+ */
+export declare function formatHelp(): string;