peen

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2026 License: MIT

README

peen

Peen is one stateful coding agent, exposed over HTTP. A JSON request carries one message; Peen creates or resumes a durable session, runs the configured agent through Elelem, and returns either the final JSON answer or a live Server-Sent Events stream. Every turn, message, and event is recorded in SQLite, so a session survives a process restart. A message accepted into an already active turn keeps its delivery state only in memory until its next provider round; after a restart clients retry it.

Peen also acts as a small file-based agent harness. It starts with embedded operating rules and skills, then resolves layered AGENTS.md files, Agent Skills, and named child agents from the directories around the current message's workspace. The agent reads and edits files and runs shell commands with the same access as the operating-system user running the process: no sandbox, no allowlist, no approval step. Read Security before you point this at anything you care about.

Contents

Quick start

Requires Docker (the make targets build and test through Docker images) and an OpenAI-compatible, Anthropic-compatible, or Z.ai Coding upstream to point at.

cp .env.example .env
# Edit .env: set PEEN_UPSTREAMS, PEEN_DEFAULT_MODEL, and the API key
# environment variable PEEN_UPSTREAMS references.

Build a static binary with Docker and run it as a bare process. .env.example defaults PEEN_CONFIG_DIR and PEEN_WORKING_DIR to container paths (/data/peen, /workspace); for a bare process, point them at writable local directories instead:

make build
set -a && source .env && set +a
export PEEN_CONFIG_DIR="$PWD/.peen/config"
export PEEN_WORKING_DIR="$PWD/.peen/workspace"
mkdir -p "$PEEN_CONFIG_DIR" "$PEEN_WORKING_DIR"
./build/peen run
curl -s http://localhost:8080/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{"message":"list the files in the current directory"}'

Add -H 'Accept: text/event-stream' for the live event stream instead of the final JSON answer. See Docker deployment for running the same thing as a container with durable mounted state, and docs/peen/deployment.md for go install and source-build paths.

Other useful targets: make test-unit, make test-integration, make test-api (containerized, exercises the real HTTP stack against a scripted provider), make test-execution-forms (source and local-install process contracts), make test-real (runs a paid, isolated end-to-end coding fixture against zai/glm-5.3-flash by default), and make lint. Run make help for the complete list.

make test-real starts the actual Peen binary inside its own Docker container, with no Docker socket, a disposable layered workspace, a private SQLite state, and a per-run API token. The live model must load a skill, launch a read-only child agent, read and patch a small Go project, run its test, trigger hooks and events, and satisfy durable transcript, audit-log, and outbound-context checks. The forwarding check keeps only in-memory marker matches, so it never writes prompts or credentials to logs. Set PEEN_TEST_DEFAULT_MODEL to run this scenario against another configured provider/model without changing the live-test default or deployment default.

Provider configuration

PEEN_UPSTREAMS is a JSON array of named providers:

[
  {"name":"aigate","provider":"openai","baseUrl":"https://aigate.example/v1","apiKeyEnv":"AIGATE_TOKEN"},
  {"name":"zai","provider":"zai-coding","baseUrl":"https://api.z.ai/api/coding/paas/v4","apiKeyEnv":"ZAI_TOKEN"}
]

Each entry has a unique name, a provider type (openai, anthropic, or zai-coding), an optional baseUrl, and an optional apiKeyEnv. zai-coding uses Z.ai's Coding endpoint and preserves its thinking state through tool rounds. apiKeyEnv names an environment variable read at startup, so the credential never appears in PEEN_UPSTREAMS itself, in a config dump, or in a log line, and it can be rotated without touching the upstream list.

A model is addressed as <upstream-name>/<model-id>, split on only the first slash, so a provider's own model ID can itself contain slashes. Peen never invents or aliases a model name: at startup it builds one driver per upstream and calls its ListModels API, and only IDs the provider actually returns get registered. PEEN_DEFAULT_MODEL and PEEN_COMPACTION_MODEL (defaults to PEEN_DEFAULT_MODEL) must each resolve to a discovered model whose context window is at least PEEN_MAX_CONTEXT_TOKENS, or the process refuses to start. A discovery failure on an upstream neither setting selects is logged, and only that one upstream stays unavailable.

POST /v1/messages also accepts an optional per-message model field that overrides the default for that one call. It must already be a discovered provider/model reference; it is not sticky and does not change what later messages in the same session use.

For Z.ai Coding, use zai/glm-5.3 for the main coding turn and zai/glm-5.3-flash for lightweight work. Peen does not infer task difficulty; the caller selects the model for each turn.

The full list of tunables (context, tool, and event limits) is in .env.example and docs/peen/configuration.md.

The configuration directory

PEEN_CONFIG_DIR holds both the harness's base layer and Peen's durable state:

<config-dir>/
  AGENTS.md
  SYSTEM.md
  APPEND_SYSTEM.md
  COMPACTION.md
  .agents/
    skills/<skill-name>/SKILL.md
    agents/<agent-name>.md
    events/<event-type>.md
    hooks.yaml
  hook-state/<session-id>/
  peen.db

Every file here is optional; a missing one is normal, not an error.

Peen always ships an embedded operating-rules block and planning and freshness skills. It applies those before the configuration directory layer without materializing them as files. A configuration or workspace skill with the same name replaces its embedded version.

  • AGENTS.md: project instructions applied to every turn. Peen keeps each layer's block in order, from the embedded base through the workspace layer.
  • SYSTEM.md: replaces Peen's built-in default system prompt entirely.
  • APPEND_SYSTEM.md: appended after whichever prompt is active.
  • COMPACTION.md: replaces the built-in summarization prompt, read only when PEEN_COMPACTION_MODE=summarize; a change takes effect after restart.
  • .agents/skills/<name>/SKILL.md: an Agent Skill, loaded in full through use_skill when the model needs it. A same-named later layer replaces an earlier skill.
  • .agents/agents/<name>.md: a named child agent launch_agent can run by name. Its optional allowed-tools frontmatter is an enforced comma-separated tool allowlist.
  • .agents/events/<type>.md: a handler for one session event type.
  • .agents/hooks.yaml: ordered lifecycle actions that can deny an operation, run a direct executable, add model context, or publish a session event. See docs/peen/hooks.md.
  • hook-state/<session-id>/: private persistent state for command hooks in that session. Peen creates the directory tree with mode 0700.
  • peen.db: the SQLite database. Peen creates PEEN_CONFIG_DIR itself (mode 0700) if it does not exist yet, and the database file at 0600. It refuses a symlinked config directory or database path.

Full layering and file format details: docs/peen/configuration.md.

HTTP API

Every operation is under /v1. Full request and response shapes: docs/peen/http-api.md.

Method Path Purpose
POST /v1/messages Run one agent turn, or queue a plain message for an active session. JSON or SSE, selected by Accept.
GET /v1/ws?sessionId=<uuid> Open a synchronized WebSocket view of one existing session and send or receive agent events.
GET /v1/messages List stored conversation messages, paginated.
GET /v1/session Read session details.
POST /v1/session/cancel Request cancellation of the active turn.
GET /v1/session/events List the session's pending events.
POST /v1/session/events Report an event to the session from outside.
GET /v1/session/jobs List the commands this session has started.
GET /v1/session/jobs/{jobId}/output Read a bounded window of one job's output.
POST /v1/session/jobs/{jobId}/signal Stop one running job.
GET /v1/session/agents List the child agent runs this session has started.
GET /v1/session/agents/{agentRunId}/messages Follow what one child agent run is doing.
POST /v1/session/agents/{agentRunId}/cancel Cancel one child agent run without ending its parent turn.

Two probe endpoints sit outside /v1 and outside authentication, because an orchestrator health-checking the service has no bearer token to present:

Method Path Purpose
GET /healthz Liveness. Returns 200 {"status":"ok"} while the process is serving.
GET /ready Readiness. Same answer, and that is accurate: the database is opened, migrated, and integrity-checked before the listener exists, so a process that failed any of those has no listener to probe.

Every operation except POST /v1/messages requires the X-Session-ID header and never creates a session; an unknown session returns 404. GET /v1/ws uses its required sessionId query parameter instead, because browser WebSocket clients cannot set X-Session-ID. It also never creates a session. Connections for the same session share one hub client, so every connected browser or client receives the same agent events. See the WebSocket contract. POST /v1/messages accepts an optional X-Session-ID to resume a session, or creates a new UUID session when it is missing. Every JSON or SSE response carries the resolved X-Session-ID and a generated X-Request-ID. Errors use one {code, message, details} envelope.

Bearer authentication

PEEN_API_TOKEN is empty by default, which disables authentication entirely. Set it to any non-empty value to require every request to carry Authorization: Bearer <PEEN_API_TOKEN>. The comparison is constant-time. A missing or wrong token returns 401.

Native browser WebSockets cannot set Authorization. For GET /v1/ws, they instead send peen.v1 and peen.bearer.<base64url-token> as subprotocols; the server selects peen.v1 and verifies the second value. Do not put the bearer token in a query parameter. Use wss:// outside local development.

/healthz and /ready are exempt. Everything under /v1 is not.

Metrics

Prometheus metrics are available at GET /metrics only through the separate PEEN_METRICS_LISTEN_ADDRESS listener, which defaults to 127.0.0.1:9090. This listener is loopback-only, unauthenticated, and never shares the public API surface. A scraper must run in Peen's network namespace. See the configuration reference.

Logging

LOG_LEVEL controls the structured records Peen writes to stdout. The audit sink retains debug-and-above records in PEEN_CONFIG_DIR/logs/YYYYMMDD-000000.log by default, using UTC and keeping 14 daily files. Set PEEN_LOG_DIRECTORY to override it. Correlated audit records show the resolved harness manifest, skill and hook activity, child-agent lifecycle, and tool outcomes. They contain identifiers, sizes, and SHA-256 digests, not raw prompts or tool output. Session storage and child-agent JSONL transcripts hold the sensitive verbatim trace for authorized debugging. ORM SQL statement previews are deliberately disabled because expanded statements can contain persisted sensitive content.

Workspaces

PEEN_WORKING_DIR is the default working directory for every message: Peen changes into it at startup, and it is what a message's tools and relative paths resolve against when no override is given.

A workspace field in the POST /v1/messages body overrides it for that one message only. It is never sticky: it does not change the session's default, and the next message without a workspace field uses PEEN_WORKING_DIR again. ~ expands to the running user's home directory, and the result must be an existing, readable directory. The workspace is a default directory, not a containment boundary: an absolute path outside it is accepted.

Before a file tool can overwrite, edit, move, delete, or patch an existing regular file, that file's contents must have been read in the current turn. Peen checks the observed content hash again under its mutation lock. A directory listing does not count as reading the file. New files and move destinations are checked for absence, then published with no-replace filesystem operations so a concurrently created target is never silently overwritten. edit_file handles exact replacements in one file. apply_patch handles strict coordinated updates, additions, deletions, and moves across files.

Compaction modes

PEEN_MAX_CONTEXT_TOKENS is the request budget Elelem enforces. When a request would exceed it, PEEN_COMPACTION_MODE picks how Peen responds:

  • drop-oldest (default): Elelem's built-in policy evicts the oldest complete conversation units from that one request. Nothing is written to the database, and the original transcript is untouched.
  • summarize: Peen replaces an old, completed prefix of the conversation with a generated summary and stores that replacement as an immutable compactions row.

In both modes the original messages and events rows are never deleted. GET /v1/messages always returns the real transcript, never a summary. A later compaction only ever supersedes the previous one; superseded rows stay in the database for inspection but no longer take part in prompt reconstruction.

Security

Read this before you deploy Peen anywhere it can reach something you do not want touched.

Peen's host tools, run_command most of all, run with exactly the access of the operating-system user running the process. There is no sandbox, no path allowlist, no secret-file denylist, and no approval or permission step before a tool runs. A file tool can read, write, or remove any path that user can touch, including .git/, .env, and SSH keys. run_command executes an arbitrary shell command immediately. This is a deliberate design choice, not a gap: the product is a coding agent with real access, and Docker, the container user, and the mounts you choose are the isolation boundary, not anything inside Peen itself.

Tool calls and their results are recorded verbatim in the session transcript and streamed live over SSE, exactly like any other message. If the agent reads a file containing a secret, or a command prints one to stdout, that secret now exists in the SQLite transcript and in whatever received the SSE stream. Peen does not scan for or redact secret-shaped content in tool output. Treat the transcript and the event stream at the same sensitivity level as the files and commands the agent can reach.

remove_path has exactly one built-in restriction, and it is a guard against a catastrophic typo, not a permission system: it refuses to remove the filesystem root or the current message's workspace directory itself. Every other path, including everything named above, is removable.

Run Peen as a non-root user, in a container, with only the mounts, network access, and capabilities the deployment actually needs. The production image does exactly this by default; see below.

Docker deployment

make docker-build builds the production image, tagged peen, from the multi-stage Dockerfile. The final image is Ubuntu, not scratch or distroless: run_command needs a real shell and the utilities an agent reaches for (git, curl, jq, ripgrep, ...), so the runtime image is the agent's toolbox, not just a binary carrier. It runs as a fixed non-root user, UID and GID 10001, under tini so run_command's child processes get reaped.

Peen keeps all durable state under PEEN_CONFIG_DIR and treats PEEN_WORKING_DIR as the default workspace. Mount both from the host so a container restart resumes existing sessions instead of starting over:

mkdir -p ./data/peen ./workspace
sudo chown 10001:10001 ./data/peen ./workspace

docker run --rm \
  --env-file .env \
  -p 8080:8080 \
  -v "$(pwd)/data/peen:/data/peen" \
  -v "$(pwd)/workspace:/workspace" \
  peen run

Both mounted directories must be owned by UID/GID 10001 before the container starts. Peen enforces private permissions on PEEN_CONFIG_DIR and peen.db on every startup, which requires owning them; a plain docker run -v auto-creates a missing bind-mount source as root, which fails that check. PEEN_WORKING_DIR must already exist: Peen changes into it during startup and does not create it.

Keep .env out of version control. It already is: both .env and .env.* are gitignored.

Further reading


Built with spite using https://github.com/psyb0t/servicepack

Directories

Path Synopsis
cmd
repogen command
internal
app
pkg/agent
Package agent owns Peen's transport-independent agent runtime.
Package agent owns Peen's transport-independent agent runtime.
pkg/auditlog
Package auditlog adds a durable JSON sink beside the process logger.
Package auditlog adds a durable JSON sink beside the process logger.
pkg/config
Package config loads Peen's deployment configuration from PEEN_ variables.
Package config loads Peen's deployment configuration from PEEN_ variables.
pkg/db
Package db opens Peen's SQLite database, applies its embedded migrations, and wires the generated gorm/gen repositories.
Package db opens Peen's SQLite database, applies its embedded migrations, and wires the generated gorm/gen repositories.
pkg/events
Package events carries typed notices about things that happened which the agent did not directly ask about: a process job ended, a child agent finished, or something outside Peen reported a change.
Package events carries typed notices about things that happened which the agent did not directly ask about: a process job ended, a child agent finished, or something outside Peen reported a change.
pkg/hooks
Package hooks runs validated layered hook actions at agent lifecycle points.
Package hooks runs validated layered hook actions at agent lifecycle points.
pkg/http/api
Package api provides primitives to interact with the openapi HTTP API.
Package api provides primitives to interact with the openapi HTTP API.
pkg/http/server
Package server exposes Peen's client-facing Serbewr HTTP API.
Package server exposes Peen's client-facing Serbewr HTTP API.
pkg/metrics
Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.
Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.
pkg/session
Package session owns Peen's durable transport-neutral session transcript.
Package session owns Peen's durable transport-neutral session transcript.
pkg
http/api/client
Package client provides primitives to interact with the openapi HTTP API.
Package client provides primitives to interact with the openapi HTTP API.
peen
Package peen is Peen's stable, supported programmatic entry point.
Package peen is Peen's stable, supported programmatic entry point.
tests
testinfra
Package testinfra is the extendable integration-test harness for a servicepack app.
Package testinfra is the extendable integration-test harness for a servicepack app.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL