@j1nn0/agent-progress-pi

What it is

@j1nn0/agent-progress-pi is a minimal Pi harness adapter for recording caller-declared milestone sets and asking the Progress core whether the declared work is moving forward. It provides one slash-command namespace for a human and four explicit tools for the model. The adapter keeps the complete current set, the cumulative baseline, and the distinction between an unestablished baseline and an established empty baseline.

Relationship to the core

@j1nn0/agent-progress is the harness-agnostic core primitive. All progress judgment comes from its judgeProgress(...) function. The adapter never compares milestone sets itself and never implements a second progress policy. It only maintains the caller-declared current set and cumulative baseline, builds the core input with the correct missing-baseline semantics, displays the returned verdict, and persists state.

The adapter is tested against Pi 0.84.2. Its Pi peer dependency intentionally remains wide.

Installation

Install the published adapter from the registry:

pi install npm:@j1nn0/agent-progress-pi

Add -l to install it project-locally instead of for your user.

From a local checkout

Build from the repository root, then install the package by absolute path:

PACKAGE_DIR=/abs/path/to/agent-primitives/packages/agent-progress-pi
pnpm install
pnpm --filter @j1nn0/agent-progress-pi build
pi install "$PACKAGE_DIR" -l

For a one-run load without installing it in Pi settings:

pi -e "$PACKAGE_DIR/dist/extension.js"

The package manifest also advertises ./dist/extension.js through Pi's pi.extensions entry.

Commands

The extension registers exactly one command namespace, /agent-progress:

/agent-progress status
/agent-progress add <milestone>
/agent-progress withdraw <milestone>
/agent-progress judge
/agent-progress clear --yes

status shows the complete currently declared set, the recorded baseline size, and whether a baseline has been established. add and withdraw accept one milestone token. Adding an already-declared identifier or withdrawing an unknown identifier warns and does nothing. Extra arguments are rejected rather than silently ignored.

add and withdraw are state mutations only. They never judge and never change the cumulative baseline. judge is explicit: it passes the complete currently declared set to judgeProgress(...) and reports the core's verdict. It rejects extra arguments. clear requires --yes; without confirmation it warns and does nothing.

The current set is complete, not a per-round delta. After withdrawing an identifier, adding a different identifier and judging can report both progress and withdrawnMilestones. A withdrawal removes the identifier from the declared set only; it never removes it from the monotonic cumulative baseline. If that identifier is declared again later, the core still reports no_progress because it was already recorded.

Tools

The model can use exactly these four tools:

• agent_progress_get — read the current declared set, baseline size, and baseline status.
• agent_progress_add_milestone — add one caller-declared opaque milestone identifier to the current set.
• agent_progress_withdraw_milestone — withdraw one identifier from the current set only.
• agent_progress_judge — compare the complete current set with the cumulative baseline through the Progress core.

Tool values are caller-declared. The tools do not infer, verify, or assert milestone meaning, truth, progress, evidence, or completion. The judge tool specifically reports whether the declared set strictly grew; it does not inspect milestone meaning or verify that a milestone was worth reaching.

Explicit judgment and the current-set model

The adapter does not judge after every mutation or on every turn. A caller explicitly adds and withdraws identifiers, then explicitly invokes judge. The first judge omits the previous property because no baseline has been established, so the core returns unknown with reason missing_baseline. That call establishes the baseline from the returned recordedMilestones.

Later judges pass the cumulative recordedMilestones as previous, including when it is an empty array. An established-but-empty baseline is real information: it is not unknown, and a non-empty current set can produce progress. A judge that produces no_progress without changing the baseline does not append another state entry.

Milestone identifier stability is the caller's responsibility. Identifiers are opaque and are never trimmed, normalized, rewritten, sorted, or generated by this adapter. The caller must supply the same identifier when it means the same milestone and must supply the complete set currently being declared.

Persistence and sessions

Successful state changes append a custom Pi session entry with custom type agent-progress-state:

{
  schemaVersion: 1,
  hasBaseline: false,
  currentMilestones: [],
  recordedMilestones: []
}

currentMilestones is the complete declared set in insertion order. recordedMilestones is the cumulative baseline returned by the core's latest judge. hasBaseline records whether a judge has ever established a baseline; it is never inferred from array emptiness.

The adapter appends only after a new add, a successful withdraw, a judge that first establishes a baseline or grows the cumulative baseline, or a confirmed clear --yes that changes state. Duplicate adds, unknown withdrawals, no-op judges, unconfirmed clears, and loading never append entries. The verdict itself is not persisted as history.

On every session_start, the adapter reads the current branch, selects the newest matching agent-progress-state entry, and validates it strictly. A malformed newest entry produces one warning and a fresh state; the adapter does not repair it, fall back to an older entry, or append a replacement while loading. A new session with no matching entry starts with an empty declared set and no baseline. Resuming a session restores both the current set and the cumulative baseline.

When hasBaseline is false, the next judge omits previous entirely. When it is true, the next judge passes previous: { milestones: recordedMilestones }, even if that array is empty. This preserves the distinction between “never judged” and “judged from nothing.”

There is no filesystem or cross-session persistence beyond Pi's own session entries.

Coexistence with Context Guard Pi and Agent State Pi

This adapter can be loaded alongside @j1nn0/agent-context-guard-pi and @j1nn0/agent-state-pi. It uses the independent command name /agent-progress, the agent_progress_* tool names, and the agent-progress-state session-entry type. It has no dependency on either adapter, and it does not depend on @j1nn0/agent-state or @j1nn0/agent-context-guard. The adapters keep separate commands, tools, and persisted entries.

An application or another adapter may choose milestone identifiers from Agent State or another source, but that extraction is caller-owned. This package accepts plain caller-supplied identifiers and observations; it does not read Agent State or Context Guard data.

Deliberate limits

This package has:

• no automatic milestone extraction from prompts, responses, tool output, or Agent State;
• no automatic identifier generation, normalization, or judgment;
• no per-turn context injection or model/provider calls;
• no attempt counts, consecutive-no_progress counting, escalation, retry policy, or backoff;
• no completion verification or evidence checking;
• no network calls, MCP integration, telemetry, or global state; and
• no progress policy separate from judgeProgress(...).

Those boundaries leave attempt counting, repeated-stall handling, and escalation to a future Retry Guard. Evidence may verify whether a milestone was earned, but Progress does not. A newly declared identifier is judged as progress according to the core contract even when another component must still verify what it means.

Limitations

Version 0.1 judges only declared-set growth. It cannot tell you whether a milestone was worth reaching, whether an identifier is meaningful, whether the caller's observation is honest, or whether a completion claim is supported. A caller that declares meaningless new identifiers will register progress.

The adapter does not replace the core's cumulative loop: callers must keep declaring the complete current set and must use the returned cumulative baseline through the adapter's explicit judge operation. State is local to the active Pi session, and the cumulative baseline grows until the caller deliberately starts fresh with clear --yes.