# paimon

**Repository Path**: wenkc0127/paimon

## Basic Information

- **Project Name**: paimon
- **Description**: light-weight coding agent based on pi sdk, with a modified subagent workflow.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Paimon

Paimon is being built in small, verifiable stages. The current repository
implements stages 0–4: a single-workspace Main Agent, Supervisor planning,
isolated Executor candidates, canonical Diff/patch generation, delivery
confirmation, Apply/reconcile, explicit Git commit/push controls, and the
Reviewer/check/recovery boundary. GUI, OAuth, and a Fake Provider remain out
of scope.
The authoritative product design is
[`PAIMON_AGENT_DESIGN.md`](./PAIMON_AGENT_DESIGN.md).

## Prerequisites

- Windows (the first-release target)
- Node.js `>=22.19.0`
- npm or pnpm

The project pins the Pi SDK packages to `0.84.4`:

- `@earendil-works/pi-coding-agent`
- `@earendil-works/pi-ai`
- `@earendil-works/pi-agent-core`
- `@earendil-works/pi-client`
- `@earendil-works/pi-protocol`
- `@earendil-works/pi-telemetry`
- `@earendil-works/pi-tui`

Install from the repository root with `pnpm install` (or `npm install` if you
are maintaining a local npm-only setup). No separate Pi RPC process is needed:
Paimon imports the SDK directly in the Node process; no separate Pi RPC
process is required.

## Stage 1: single-workspace Main Agent

Check the formal TOML/catalog configuration without starting an Agent:

```powershell
npm run paimon -- config
```

Run the explicit connectivity probe. It uses the Main Agent's role-scoped
fallback chain (each entry may name a different Provider and catalog):

```powershell
npm run paimon:connectivity -- --jsonl
```

The probe stops at the first successful assistant response and records every
attempt, elapsed time, failure category, effective thinking level, Provider,
and selected model. Normal Main Agent, Explainer, and Executor calls use their
own `[roles.<role].fallback_models]` list after the configured failure count;
entries may cross Provider boundaries. Authentication, permission, path, and
schema failures are never silently hidden by fallback.

Register and select a trusted workspace. `--yes` is required for workspace
changes in a non-interactive shell:

```powershell
npm run paimon -- workspace add C:\Projects\example --label example --yes
npm run paimon -- workspace
npm run paimon -- status
```

Start or continue a Main Agent conversation:

```powershell
npm run paimon -- chat
npm run paimon -- chat --message "请概览当前工作区的目录结构。"
npm run paimon -- chat --new --message "这是一个新的会话。"
```

Append `--jsonl` to any command for one structured JSON object per
line. `paimon chat` emits streaming `text_delta`, tool, and completion events
in this form.

The Main Agent has these workspace-relative inspection tools:

- `workspace_inspect`
- `workspace_list`
- `workspace_find`
- `workspace_grep`
- `workspace_read`

For Main Agent direct editing, `write` and `edit` are also exposed. They accept
only workspace-relative UTF-8 text paths and reject
absolute paths, `..` escapes, symbolic-link components, `.paimon`, `.git`,
`config/config.toml`, and the credentials store. `write` replaces a complete
file; `edit` performs unique exact `oldText`/`newText` replacements. Each edit
stores a before/after snapshot, patch, metadata record, and append-only event
under `.paimon/direct-edits/` and `.paimon/direct-edit-events.jsonl`. These
tools do not expose shell execution or arbitrary filesystem access. Explainer
can read the selected workspace and run only read-only Bash queries; its
`edit`/`write` tools are restricted to its own
`.paimon/.explainer/<run>/<round>/<invocation>` draft directory. It cannot
modify target workspace files or other role/runtime data. `/subflow` and
`--workflow` remain Supervisor controls.

## Stage 2: Supervisor planning workflow

The stage 2 planning control plane is owned by a local Paimon Host over a Windows named
pipe using versioned, length-prefixed JSON frames. CLI and Main Agent calls use
the same Supervisor service; clients never write `state.json` or Pi sessions
directly. The Host is started on demand and remains alive after `run` returns.

Start a run and observe the asynchronous Explainer:

```powershell
npm run paimon -- run --message "为项目增加状态查询接口" --jsonl
npm run paimon -- await <run-id> --timeout-ms 30000 --jsonl
npm run paimon -- status <run-id> --jsonl
npm run paimon -- plan <run-id> --jsonl
```

`plan` returns the current `plan_hash`, `state_version` and one-time
`confirmation_id`. To edit and approve a plan in a non-interactive shell:

```powershell
npm run paimon -- edit-plan <run-id> --plan-file .\revised-plan.md --yes --jsonl
npm run paimon -- plan <run-id> --jsonl
npm run paimon -- approve-plan <run-id> --confirmation-id <id> `
  --plan-hash <sha256> --state-version <n> --yes --jsonl
```

If Explainer requests clarification, submit the structured answers only after
the user has decided them:

```powershell
npm run paimon -- clarification-resolve <run-id> `
  --answers '[{"id":"Q-001","answer":"..."}]' --yes --jsonl
```

Each workspace may keep multiple versioned workflow configurations. The
active configuration is selected atomically; existing runs retain the config
snapshot they started with:

```powershell
npm run paimon -- workflow-config list --jsonl
npm run paimon -- workflow-config show --jsonl
npm run paimon -- workflow-config save .\workflow-config.json --activate --yes --jsonl
npm run paimon -- workflow-config activate strict --yes --jsonl
```

Workflow configuration files live under
`.paimon/workflow-config.json` and `.paimon/workflow-configs/`. They can
select role prompts, fixed role tool profiles and workflow policies, but they
cannot change protocol path boundaries, credentials protection, or state-machine
gates. Executor and Reviewer use the frozen run snapshot
for its role prompt, model/thinking override, acceptance visibility, and
command permission mode.

The authoritative run evidence is under
`<workspace>/.paimon/runs/<run-id>/`: `request.json`, `plan.md`, `state.json`,
`events.jsonl`, `run-meta.json`, and the Explainer session under
`.paimon/sessions/subagents/<run-id>/<round>/<invocation-id>.jsonl`.
Explainer working drafts are separately retained under
`.paimon/.explainer/<run-id>/<round>/<invocation-id>/`; the matching event
records its tool profile, logical/actual tools, draft path and file manifest.
The three fixed role roots `.explainer`, `.executor` and `.reviewer` are
created lazily. Explainer, Executor, and Reviewer are enabled. Reviewer runs
in a one-shot sandbox containing only `request.json`, `candidate-code/`, and
`diff.json`; its draft files are kept under its own invocation directory.
`request.json` intentionally excludes raw source request, assumptions, open
questions, risk flags, policy and parent contract hash. Every event has a
contiguous `event_seq`; plan approval is bound to confirmation, plan hash and
state version. Editing a plan invalidates the previous confirmation.

`clarification.resolve` records answers, preserves input hashes, and invokes
Explainer again.

## Stage 3: isolated Executor and delivery

Plan approval creates an isolated candidate outside the source workspace. Git
workspaces prefer a detached worktree and overlay the startup dirty snapshot;
non-Git workspaces use a controlled copy. The frozen execution base remains
under the run directory so later source-workspace changes cannot rewrite the
canonical patch.

After Executor completes, Supervisor recomputes the Diff and blocks empty,
out-of-scope, disallowed-extension, or binary changes. Fetching a Diff creates
a one-time delivery confirmation. Candidate changes rotate that confirmation;
Apply also revalidates candidate hashes and the target delivery base.

Executor permission requests stop the active Pi invocation immediately. The
first request is retained, remaining batched tools do not execute, and the
Supervisor restores the invocation checkpoint only after the tool loop has
settled. Exact command/file grants are recovered from user approval events
for the same run, round, approved plan and contract; granting a second action
or restarting Host no longer forgets the first grant. New plans invalidate
these grants. In `permission_highrisk`, revising a file created by the run is
not treated as overwriting a pre-existing user file. Deterministic read-only
probes (`pwd`, directory/file inspection, `grep`/`cat`/`head`, `find` without
write actions, read-only `git status`/`rev-parse`, and safe pipelines or stderr
discarding) are recognized as low risk, including probes that first `cd` into
the candidate. They do not trigger a new invocation; absolute paths outside
the candidate and shell write/redirection forms remain blocked or gated.

File tools validate the actual target before creating its parent directories,
including root-level files. Non-Git copies do not inherit an ancestor Git
repository's ignore rules. Reviewer checks use the same Git Bash shell as the
ordinary bash tool, not Windows cmd.exe, and cannot query an ancestor Git repo.

```powershell
npm run paimon -- diff <run-id> --jsonl
npm run paimon -- approve-delivery <run-id> --confirmation-id <id> `
  --diff-hash <sha256> --state-version <n> --action export --yes --jsonl
npm run paimon -- approve-delivery <run-id> --confirmation-id <id> `
  --diff-hash <sha256> --state-version <n> --action apply --yes --jsonl
npm run paimon -- reconcile <run-id> --jsonl
```

For a clean Git run whose delivery was applied, commit and push remain separate
explicit operations. Commit refuses pre-existing dirty overlap, unrelated
changes, or pre-staged files.

```powershell
npm run paimon -- commit <run-id> --diff-hash <sha256> `
  --state-version <n> --message "feat: apply result" --yes --jsonl
npm run paimon -- push <run-id> --commit <sha> --state-version <n> `
  --remote origin --branch <branch> --yes --jsonl
```

Application state is deliberately separate from source configuration:

```text
<paimon-root>/workspaces.json               # registered workspace index
<workspace>/.paimon/workspace.json          # workspace metadata
<workspace>/.paimon/sessions/index.json     # session navigation index
<workspace>/.paimon/sessions/main/*.jsonl   # Pi Main Agent transcripts
```

`workspaces.json`, `data/`, and all `.paimon` data are ignored by Git. Removing
a workspace through the CLI only removes its root index entry; it never deletes
the workspace's `.paimon` files. The user can delete those files manually when
needed.

## Stage 4: Reviewer, checks, and recovery

After Executor completes, Supervisor recomputes the canonical Diff and starts a
fresh Reviewer invocation. Reviewer receives the three logical inputs recorded
in `reviewer-input-manifest.json`, can inspect the read-only candidate package,
and can write only its own draft area. The `reviewer_decision` script tool
accepts `pass` or `decline`; a decline must choose `revise` or `block`. The
tool then fills the strict design fields (`review_id`, `F-###`, `AC-###`,
`CHK-###`, input hashes, and the structured `revision_input`/`block_reason`).
Check output is injected by the deterministic Check Runner rather than
trusted from model text.

```powershell
npm run paimon -- review <run-id> --jsonl
npm run paimon -- resume <run-id> --yes --jsonl
npm run paimon -- pause <run-id> --state-version <n> --yes --jsonl
npm run paimon -- retry <run-id> --state-version <n> --yes --jsonl
```

Reviewer `pass` enters `passed` and then `awaiting_delivery` only when all
recorded checks and acceptance assessments pass. `revise` creates a new logical
round and gives the next Explainer only the structured revision projection;
`block` or failed checks remain blocked. Schema/protocol errors and heartbeat
timeouts are persisted as `recovering`; resume creates a new invocation from
the same frozen inputs. Pause aborts a live Pi session when possible, preserves
the Executor checkpoint, and restores the prior state on resume. A missing
`fallback_after_failures`/`null` means no automatic role-model switch; when a
positive threshold and matching `fallback_on` category are configured, the
role-scoped fallback list is attempted automatically in order and may name
models from another Provider. There is no approval pause for fallback.

## Stage 5: desktop GUI

The stage-5 desktop client lives in `packages/gui` and uses Tauri 2 with
React/TypeScript. The Rust shell speaks the same length-prefixed Windows named
pipe protocol as the CLI; the webview never reads Pi sessions, `state.json`,
`events.jsonl`, credentials, or workspace files directly.

The desktop client uses an adaptive floating/docked layout inspired by the
project's `frontend_reference.html`: a resizable workspace/session/run sidebar,
a centered conversation or run surface, and a resizable multi-pane run
inspector. The sidebars can float over content or reserve layout space; panel
mode, widths, theme, and split ratios are local UI preferences rather than
workflow state.

The shared composer switches explicitly between Main Agent chat and forced
workflow creation. Workflow mode can expand structured requirement,
constraint, and acceptance inputs while continuing to call the existing
`workflow.start` contract. The desktop slice also includes session
rename/archive/restore, plan and permission approval, pause/resume/retry/cancel,
cursor-based timeline continuation, colored canonical Diff and Reviewer
evidence views, patch export/Apply, and versioned workspace workflow editing
for role model/thinking/system prompts and execution/review policies.

The Main Agent Supervisor tool and the Host share strict operation payload
schemas and one dispatcher. The tool's `operation` stays in the named-pipe
frame, not in its business payload; `direct_request` and `commit_message`
are translated to `request` and `message` at the tool boundary. Invalid
inputs return `invalid_input` with complete field-level diagnostics under
`data.diagnostic.issues`, without echoing submitted values. A run-level
`blocked` or `failed` projection remains a successful control response and is
therefore still inspectable; only an envelope carrying structured `error`
represents a control-request failure. GUI/Host capability handshakes require
`workflow.executor-permission-v1` so a GUI upgrade does not silently reuse a
Host with the older response classification.

An opt-in real-model Markdown regression (with the current config/catalog)
is available after `pnpm build`:

```powershell
node dist/src/spike/workflow-markdown-smoke.js config/config.toml
```

It creates an isolated workspace under `data/smoke-runs/`, approves only its
own test plan and expected single-file delivery, never auto-approves tool
permissions, and retains evidence. Its 180-second observation budget is a
test limit, not a change to production workflow timeouts.

The configuration page also provides a credential-redacted Provider/model
editor. It can update endpoints and catalog model metadata and maintains one
ordered, cross-Provider fallback list per Main/Explainer/Executor/Reviewer
role. Saving is a two-step `config.update.preview` / confirmed `config.update`
operation: references and model capabilities are validated, existing
`config.toml`/catalog files are backed up under
`<paimon-root>/data/config-versions/`, writes are atomic with rollback, and
already-created runs retain their frozen configuration. Existing API keys are
never returned to the webview or control protocol. The page can run a real
connectivity probe and shows the ordered attempts without exposing the key.

The right-side “changes” pane is deliberately limited to paths already present
in the canonical Diff returned by the Host. The webview does not gain an
arbitrary workspace file browser, Reviewer chat, direct run-file access, or a
second source of truth for runtime state.

```powershell
npm run build
npm run gui:build
npm run gui:dev
```

`gui:dev` locates the repository root automatically and starts/connects the
same background Host used by the CLI. Set `PAIMON_ROOT` when launching the GUI
from outside the repository. Closing the window does not explicitly stop the
Host. Run updates use `workflow.await` with a persisted event cursor so a
temporary client disconnect can resume without parsing logs. Main session
navigation and filtered user/assistant history are available through Host
operations, including rename and archive/restore. Closing the main window hides
it to a simple tray menu; the user can show it again, quit only the GUI while
retaining Host, or explicitly quit both. An explicit Host quit is rejected with
`host_busy` while a Main Agent or subagent invocation is active, so it cannot
silently strand an in-progress run; pause/cancel the run first.

Build the Windows packages with:

```powershell
pnpm --filter @paimon/gui tauri build
```

The build emits MSI and NSIS packages under
`packages/gui/src-tauri/target/release/bundle/`. The installer contains a
single-file Node Host bundle plus a deliberately credential-free starter
configuration. NSIS defaults to current-user installation; the WiX MSI is the
standard per-machine alternative. On first installed launch, the Tauri shell initializes a
per-user application data root; on upgrade it replaces only the bundled Host
runtime and root version marker, preserving the user's `config.toml`, catalog,
workspace index, and every workspace-owned `.paimon` directory. This behavior
is covered by a temporary-directory first-install/upgrade Rust test. Node.js
22 or newer remains a runtime prerequisite for the packaged Host. Packages are
currently unsigned and automatic update is intentionally out of scope.

## Stage 0 checks

The deterministic API probe makes no external network request (it uses a
loopback-only HTTP stream solely to prove cancellation):

```powershell
npm run spike:apis
```

It verifies the public `createAgentSession`, `prompt`, `subscribe`, `abort`,
`ModelRuntime`, `SessionManager`, `defineTool`/custom-tools, and
`createProvider` APIs. It also exercises a loopback HTTP stream that remains
open until `AgentSession.abort()` cancels it, and reopens a persisted JSONL
session file. The normal test suite is:

```powershell
npm test
npm run build
```

## Real Main Agent smoke test

Before the first real request, edit [`config/config.toml`](./config/config.toml):

1. Set `provider.primary.api` to `openai-responses` or
   `openai-completions`.
2. Set the actual compatible `base_url`.
3. Point each Provider's `catalog` at a catalog containing the model IDs used
   by its roles and role-scoped fallback entries. The checked-in configuration
   uses `primary/deepseek-flash`.
4. Either set the configured environment variable, for example in PowerShell,
   `$env:PAIMON_OPENAI_API_KEY = "..."`, or explicitly add `api_key` for a
   private local setup. The program never copies the key into session files,
   logs, catalog files, or diagnostics.

For the stage 0 SDK probe, run one prompt:

```powershell
npm run spike:smoke -- "用一句中文介绍你自己，并说明当前模型。"
```

When stdin is redirected, the command reads one prompt from stdin instead:

```powershell
"请简短回复：阶段 0 已连接。" | npm run spike:smoke
```

The smoke command uses an explicit cwd-bound ResourceLoader, disables Pi global
resource discovery, enables only the harmless `spike_status` custom tool, and
persists the Main Agent transcript under `<workspace>/.paimon/sessions/main`.
Press `Ctrl+C` during a request to exercise cancellation; the command reports a
cancelled request and retains the session evidence.

## Configuration shape

Stages 0–3 use the formal design shape:

```toml
[roles.main]
provider = "primary"
model = "deepseek-flash"
thinking = "max"
fallback_after_failures = 1
fallback_on = ["provider_timeout", "provider_5xx", "rate_limited", "model_unavailable"]
fallback_models = [
  { provider = "backup", model = "backup-model", reasoning_effort = "high" }
]

[provider.primary]
api = "openai-responses"
base_url = "https://api.example.com/v1"
catalog = "catalog/primary.json"
auth = "env:PAIMON_OPENAI_API_KEY"

[provider.backup]
api = "openai-completions"
base_url = "https://backup.example.com/v1"
catalog = "catalog/backup.json"
auth = "env:BACKUP_API_KEY"
```

Relative catalog paths are resolved relative to the TOML file; absolute paths
are also accepted. Legacy `[Main]`, `protocol`, `model_catalog`, and the
`...(subagents)` placeholder are rejected. The catalog requires `id`,
`supported_reasoning_levels`, and `context_window`; optional fields receive
the documented defaults. If a provider has duplicate model IDs, add the
matching catalog entry's `catalog_key` to `roles.main.catalog_key`.

For custom models, the adapter explicitly maps every catalog reasoning level
to the corresponding Pi level. This is required by Pi SDK `0.84.4` for the
extended `xhigh`/`max` levels; otherwise Pi intentionally clamps an undeclared
`max` request to `high`. The smoke output now reports both
`thinkingRequested` and `thinkingEffective`.

The repository does not embed an API key. If the configured environment
variable is missing from the process that launches the command, smoke exits
with a configuration diagnostic before making a request; start a new terminal
after changing Windows environment variables or set the variable in that
terminal explicitly.

If a Provider rejects a configured model for the current account or group,
Paimon records the failure category and follows only that role's explicitly
configured `fallback_models` chain. Add an allowed model to the referenced
Provider catalog and update the role binding or fallback list before retrying.