packages coding agent refinement

Refinement

Active contributors: Mario Zechner, kt, Armin Ronacher

Purpose

Refinement is the self-improving continual-harness subsystem of Prime Agent. Instead of summarizing the conversation like compaction, it emits precise create, update, or delete edits to a persistent, editable layer of reusable state: prompt notes, memories, skills, and subagent specs. This lets Prime Agent improve reusable behavior outside the token history. The core lives in packages/coding-agent/src/core/refinement/refinement.ts (the dir exports through packages/coding-agent/src/core/refinement/index.ts). The /refine slash command is parsed in packages/coding-agent/src/core/slash-commands.ts.

The harness has two scopes. Local entries live under the session artifact directory (harness/harness_state.json) and belong to one session. Global entries live under ~/.prime/agent/harness/ and persist across sessions. The base system prompt is immutable and is never rewritten; refinement edits only supplemental state. Rollback restores before/after snapshots recorded per edit.

Directory layout

packages/coding-agent/src/core/
├── refinement/
│   ├── index.ts            # Re-exports refinement.ts
│   └── refinement.ts       # Harness state, planning, applying, rollback, auto-review
├── agent-observe.ts        # Read-only agent family observation host handlers
├── autonomous.ts           # Bounded autonomous continuations and quality gates
├── goals.ts                # Persistent thread goal state and context prompts
├── cron-jobs.ts            # Scheduled jobs, heartbeats, and RLM heartbeats
└── slash-commands.ts       # /refine option parsing and session commands

packages/coding-agent/skills/
└── refine/                 # Kernel-side interface to refinement

Key abstractions

Type	Path	Description
HarnessState	packages/coding-agent/src/core/refinement/refinement.ts	Schema, per-kind entry maps (prompt, memory, skill, subagent), and refinement history.
HarnessEntry	packages/coding-agent/src/core/refinement/refinement.ts	A persisted prompt/memory/skill/subagent entry with id, content, reference, arguments, scope, version.
RefinementKind / RefinementAction	packages/coding-agent/src/core/refinement/refinement.ts	Entry kind and the create/update/delete action.
RefinementProposal	packages/coding-agent/src/core/refinement/refinement.ts	Model-produced JSON with summary, rationale, expected outcome, and edits.
RefinementResult	packages/coding-agent/src/core/refinement/refinement.ts	Applied edits, harness-state path, optional rollbackOf, scope.
RefinementEdit	packages/coding-agent/src/core/refinement/refinement.ts	One create/update/delete edit with content, reference, arguments, metadata, reason.
AppliedRefinementEdit	packages/coding-agent/src/core/refinement/refinement.ts	An edit with the before/after entry and whether it applied.
RefineOptions	packages/coding-agent/src/core/refinement/refinement.ts	instructions, rollbackId, and global scope flag.
RefinementPlan	packages/coding-agent/src/core/refinement/refinement.ts	Proposal plus the baseline state captured before planning.
RefineCommandOptions	packages/coding-agent/src/core/slash-commands.ts	Parsed /refine arguments.

How it works

flowchart LR
    cmd["/refine or await refine.run()"]
    plan["planRefinement: model pass over trajectory + harness overview"]
    apply["applyRefinementProposal: apply edits with snapshot checks"]
    save["saveHarnessState: atomic write"]
    prompt["formatHarnessStateForPrompt -> system prompt rebuild"]
    rollback["/refine rollback <id>"]

    cmd --> plan --> apply --> save --> prompt
    rollback --> plan
    apply -. "recorded before/after snapshots" .-> rollback

Loading

The /refine command accepts free instructions, a --global flag for the cross-session store, and a rollback <refinement-id> subcommand. parseRefineCommandOptions in packages/coding-agent/src/core/slash-commands.ts handles this; the kernel-side refine skill (in packages/coding-agent/skills/refine/SKILL.md) schedules refinement that runs when the current turn ends.

planRefinement builds a user prompt from the current harness overview, recent refinement history, and the last 80k characters of the serialized conversation, then calls completeSimple against the selected model with the REFINEMENT_SYSTEM_PROMPT. The result is parsed strictly: JSON fenced blocks and brace slicing are recovered, truncated replies are diagnosed, and malformed output fails cleanly. The proposal is returned without mutating state, so callers can re-read the shared harness_state.json immediately before applying to reject edits whose target changed during planning.

applyRefinementProposal validates each edit, applies create/update/delete against the target store, records before/after snapshots and bumped versions, and appends a refinement history event. It refuses to edit base_system_prompt and requires skills to carry a Python reference and arguments contract. saveHarnessState writes atomically via a temp file and rename. mergeHarnessStates combines the global and local stores for the prompt overview, prefixing local ids with local: when they collide with global entries.

Rollback inverts an applied result's edits: updates become restores of the before entry, creates become deletes, and deletes become recreates. planRefinement with rollbackId finds the target in history and returns a rollback proposal. Global refinements append to refinements.jsonl so they can be rolled back from any session; local refinements are recorded in the session JSONL.

Automatic refinement runs through a review gate. reviewAutoRefine asks the model whether a checkpoint (turn interval or compaction) warrants a /refine, defaulting to local scope. refineHarness is the end-to-end plan-then-apply entry point.

Persistent context in the prompt

formatHarnessStateForPrompt in packages/coding-agent/src/core/refinement/refinement.ts renders a compact # Continual Harness State overview: counts and truncated summaries per kind, the Python/rlm call contract, when to call await refine.run(), and recent refinement events. buildSystemPrompt in packages/coding-agent/src/core/system-prompt.ts appends this when a HarnessState is supplied, and gates the refine examples on the refine skill being present with IPython access.

Autonomous mode and goals

• packages/coding-agent/src/core/autonomous.ts implements bounded autonomous continuations: after each turn it decides whether to continue based on configured limits (maxContinuations, maxTurns, maxTokens, timeoutMs) and optional quality gates. Gates run shell commands and compare git worktree snapshots so a rerun after an unchanged failed gate is skipped. Terminal evidence and gate results drive the stop decision. The /autonomous slash command toggles it.
• packages/coding-agent/src/core/goals.ts models the persistent thread goal: GoalState with status, objective, token budget and usage accounting. Continuation, budget-limit, and objective-updated context prompts keep the model pursuing the goal across turns. The /goal command and the kernel-side goal skill drive it through host requests.

Scheduled and cron work

packages/coding-agent/src/core/cron-jobs.ts implements the scheduler. AgentCronJob covers once, cron, and interval schedules with sources cron, heartbeat, and rlm_heartbeat. AgentCronJobStore persists jobs (session scheduled-jobs.json), and AgentCronScheduler dispatches runs, honoring a steer/follow_up delivery mode and deferring heartbeats while the session is busy. parseHeartbeatCommand parses the /heartbeat command into status/pause/resume/clear/set actions. Agent-owned RLM heartbeats (rlm_heartbeat) are managed through AgentRlmHeartbeatController and the kernel-side rlm-heartbeat skill, and are separate from the user's visible heartbeat.

Agent observe

packages/coding-agent/src/core/agent-observe.ts backs the agent-observe skill: read-only host handlers (agent_observe.list, agent_observe.get, agent_observe.recent) expose family session summaries and bounded recent-message previews without mutating sessions. This is the observation counterpart to the messaging in the RLM runtime.

Integration points

• The /refine, /goal, /autonomous, /heartbeat, and /rlm-max-depth slash commands are session commands declared in packages/coding-agent/src/core/slash-commands.ts.
• buildSystemPrompt in packages/coding-agent/src/core/system-prompt.ts injects the harness overview.
• The refine, goal, rlm-heartbeat, agent-observe, and agent-message skills are the kernel-side host-bridge clients.
• The session runtime owns the actual goal state, cron scheduler, autonomous loop, and child registry; these files provide the state types, host handlers, and policy.
• Refinement history is surfaced as session custom entries (REFINEMENT_CUSTOM_TYPE), so rollback can be driven from the session transcript.

Entry points for modification

• To change the refine prompt or edit policy, edit packages/coding-agent/src/core/refinement/refinement.ts (REFINEMENT_SYSTEM_PROMPT, validateEdit, applyRefinementProposal).
• To change /refine argument parsing, edit parseRefineCommandOptions in packages/coding-agent/src/core/slash-commands.ts.
• To change the harness overview injected into prompts, edit formatHarnessStateForPrompt in packages/coding-agent/src/core/refinement/refinement.ts.
• To change autonomous limits or gates, edit packages/coding-agent/src/core/autonomous.ts.
• To change scheduling or heartbeat behavior, edit packages/coding-agent/src/core/cron-jobs.ts.

Key source files

File	Role
packages/coding-agent/src/core/refinement/refinement.ts	Harness state, planning, applying, rollback, auto-review.
packages/coding-agent/src/core/slash-commands.ts	/refine option parsing and session commands.
packages/coding-agent/src/core/system-prompt.ts	Injects the continual harness overview.
packages/coding-agent/src/core/autonomous.ts	Bounded autonomous continuations and quality gates.
packages/coding-agent/src/core/goals.ts	Persistent thread goal state and prompts.
packages/coding-agent/src/core/cron-jobs.ts	Scheduled jobs, heartbeats, RLM heartbeats.
packages/coding-agent/src/core/agent-observe.ts	Read-only agent family observation.

Related pages

• Package overview, SDK surface for the coding-agent package
• Session runtime, the runtime that owns goal, cron, and refinement state
• Slash commands, /refine, /goal, /autonomous, /heartbeat
• RLM runtime, rlm.harness state and agent messaging
• Skills, the skill entries refinement creates and the refine skill
• Patterns and conventions, repo rules