agent-code-runner-sandbox

A minimal TypeScript toolkit for building agent runners with:

• explicit sandbox policy
• resource locks
• delivery validation
• small demo worker

This repository is not a full production runner. It is a clean public extraction of a few patterns that matter in real agentic execution systems.

It is part of a small public code series:

• agent-code-playbook-kit for process IR and compiled runtime playbooks
• agent-code-observer-mcp for semantic tool surfaces and MCP bridging
• agent-code-a2ui-contracts for structured rich-answer contracts
• org-aware-agents for the docs-first architecture layer

Why this exists

Many "agent runners" jump directly from model output to side effects.

That is not enough for production use.

A safer runner needs at least:

• bounded command execution
• bounded HTTP access
• resource locks to avoid conflicting jobs
• explicit delivery rules for what counts as done

What is included

• src/sandbox.ts — allowlisted exec and http
• src/locks.ts — in-process lock manager with capacity support
• src/delivery.ts — delivery-policy validation for result artifacts
• src/worker.ts — small demo worker that runs JSON-defined jobs
• test/*.test.ts — focused tests for the core building blocks

Quick start

npm install
npm test
npm run build
npm run demo

Example job

The demo job:

• acquires locks
• runs an allowlisted node command
• validates the result against a delivery policy

See examples/job.json.

Design principles

• fail closed
• make side effects explicit
• keep execution boundaries machine-readable
• validate "done" instead of trusting prose

Background

These patterns come from production work on agent execution systems where permissions, approvals, audit, and bounded execution matter more than raw model cleverness.

Related repos

• org-aware-agents
• agent-code-playbook-kit
• agent-code-observer-mcp
• agent-code-a2ui-contracts