@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:

pnpm --dir ./agent-runner build

This builds dist/ and marks dist/bin/agent-runner.js executable.

To build as part of the full workspace:

pnpm build

Run

From the repository root:

pnpm agent-runner -- --task-spec /absolute/path/to/state/task-spec.json

From this package:

pnpm --dir ./agent-runner start -- --task-spec /absolute/path/to/state/task-spec.json

Directly from the built executable:

./agent-runner/dist/bin/agent-runner.js --task-spec /absolute/path/to/state/task-spec.json

For a globally linked local binary:

pnpm dev:link-agent-runner
agent-runner --task-spec /absolute/path/to/state/task-spec.json

CLI Options

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:

/home/sprite/.config/mote/agent-runner.json

Default Pi POC config:

{
  "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:

<workspace>/state/task-spec.json

An editable Pi RPC example lives at:

agent-runner/examples/task-spec.pi-rpc.json

Minimal shape:

{
  "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

Provisioned Fly Sprite Pi baselines install the Pi MCP adapter extension. Task specs may include endpoints.mcpBaseUrl again when MCP integration returns to the host-side task contract.

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"
• defaultModel: model passed to Pi when the task spec does not select one, 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:

--mode
--provider
--model
--thinking
--no-prompt-templates
--no-themes

It currently spawns Pi like:

pi --mode rpc --provider deepseek --model deepseek-v4-flash --thinking high --no-prompt-templates --no-themes

The driver writes one Pi RPC prompt command to stdin, parses Pi stdout as byte-buffered JSONL, forwards native Pi records as pi.event or pi.extension_ui_request, routes malformed stdout/stderr as harness.stdout/harness.stderr, and cancels with Pi abort, then SIGTERM, then SIGKILL after five seconds.

Direct DeepSeek token example:

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:

{
  "driver": "codex-jsonl",
  "command": "codex",
  "args": ["exec", "--json", "--ephemeral"],
  "defaultModel": "gpt-5"
}

Runtime Contract

The harness must write terminal completion to:

<workspace>/state/completion.json

Completion shape:

{
  "status": "completed",
  "summary": "Short result summary",
  "artifactIds": []
}

status must be one of:

• completed
• partial
• failed
• cancelled

Artifacts referenced by artifactIds must live under:

<workspace>/artifacts/<artifactId>/artifact.json

Dataset artifacts must also include:

<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:

pnpm --dir ./agent-runner test