agents-runtime

A local execution environment for LLM-produced TypeScript snippets. A long-lived Node.js "kernel" preloads internal dependencies and listens on a socket (Unix or TCP). The run-code CLI connects to that kernel, streams one JSON request, and prints the JSON response so agents or humans can shell out without worrying about project setup.

What it does

• Kernel (src/kernel.ts) – boots once per dev machine, keeps shared libraries (AWS SDK, @company/my-lib) warm, and executes transpiled snippets inside the same Node process.
• Runner (src/exec/runner.ts) – pure logic that wraps the snippet body, transpiles TS → JS, and runs it with injected globals.
• CLI (src/cli/run-code.ts) – tiny tool that accepts --code/--file, optional JSON --input, and forwards the request to the kernel via JSONL over a socket.

The contract for LLM code is simple: provide only the body of export async function main(input) { … }, use the injected globals, and return a JSON-serialisable value.

Getting started

npm install
npm run build
node dist/kernel.js            # or: npm run start:kernel

By default the kernel listens on /tmp/llm-kernel.sock. Override with LLM_KERNEL_SOCKET=/tmp/custom.sock or switch to TCP by setting LLM_KERNEL_SOCKET=tcp://127.0.0.1:9000.

Using the CLI

Once the kernel is running, invoke run-code directly or from tooling:

run-code \
  --code "return { greeting: `hi ${input.name}` };" \
  --input '{"name":"Panagiotis"}' \
  --socket /tmp/llm-kernel.sock \
  --timeout 5000

Available flags:

• --code <ts> – inline TypeScript body of async main.
• --file <path> – read the body from a file (mutually exclusive with --code).
• --input <json> – JSON passed as input; defaults to {}.
• --socket <path|tcp://host:port|host:port|port> – socket target; falls back to LLM_KERNEL_SOCKET or /tmp/llm-kernel.sock.
• --timeout <ms> – per-request execution timeout (overrides kernel default).

Success responses print prettified JSON to stdout with exit code 0. Failures print the error/stack to stderr and exit 1.

Protocol

Every request/response is a single JSON object terminated by \n:

// Request from CLI → kernel
{
  "id": "uuid",
  "code": "/* TS body of async main */",
  "input": { "jobId": "abc" },
  "timeoutMs": 5000
}

// Success response
{ "id": "uuid", "ok": true, "result": { "status": "done" } }

// Error response
{ "id": "uuid", "ok": false, "error": "message", "stack": "optional" }

Execution environment

• Snippet gets the body of export async function main(input) { … } prepended automatically.
• No import/export statements are allowed; use globals instead:
  • AwsS3 → namespace import of @aws-sdk/client-s3
  • MyLib → stubbed internal helper library (packages/my-lib)
• Return values must be JSON-safe; thrown errors become { ok: false } replies.
• Configure timeouts with LLM_KERNEL_TIMEOUT_MS (process-wide) or per request via timeoutMs / --timeout.

Project layout

src/
├─ kernel.ts              # socket server, request loop, timeout handling
├─ kernel.test.ts         # kernel integration tests (skipped if sockets unavailable)
├─ cli/
│  └─ run-code.ts         # CLI implementation
├─ cli/run-code.test.ts   # CLI integration tests
├─ exec/
│  ├─ runner.ts           # TS transpile + execution helper
│  └─ runner.test.ts      # runner unit tests
└─ types/
   ├─ endpoint.ts         # Unix/TCP endpoint parsing helpers
   └─ protocol.ts         # shared request/response types + guards
packages/
└─ my-lib                 # stub of the internal library exposed to snippets

Testing

npm test            # Vitest (unit + integration)

Kernel/CLI integration suites automatically skip if the environment forbids opening sockets (common in CI sandboxes). On a normal developer machine they spin up ephemeral TCP ports and exercise the real protocol end to end.

Configuration quick reference

Setting	Description
LLM_KERNEL_SOCKET	Socket to listen/connect to. Unix path or tcp://host:port.
LLM_KERNEL_TIMEOUT_MS	Default timeout enforced by the kernel (optional).
CLI --timeout	Overrides timeout for a single request.

Future work

• Hard cancellation (kill hung snippets after timeout instead of only reporting).
• Structured logs / metrics for kernel activity.
• Additional preloaded libraries or per-team presets.