# Community seed desk

Three complete, independent stages for the current custom OMP 18.0.7 extension API. Load **one stage at a time**: each intentionally owns `/seeds`. No stage imports a sibling. The inventory and every reservation are fictional; nothing contacts a seed library or changes physical stock.

## Prerequisites

- Bun 1.3.14 or newer and the workbook's matching custom `omp` build on `PATH`.
- Stages 1 and 2 have no runtime package dependencies. Stage 3 imports the matching `@oh-my-pi/omptype` and `@oh-my-pi/pi-tui` packages for persisted-data validation and optional text rendering. Its `package.json` pins 18.0.7; run `bun install` inside that stage when using a standalone download. If those custom packages are not published in your registry, use the matching source checkout's installed workspace packages instead; do not silently substitute an upstream build.
- Launch with `omp`, not `bun index.ts`: an extension exports a factory, not a CLI.

## 1. Humans and machines meet the desk

From this downloaded `seed-desk` directory:

```sh
SEED_DESK="$PWD"
LAB="$(mktemp -d)"
mkdir -p "$LAB/work" "$LAB/agent"
cd "$LAB/work"
PI_CODING_AGENT_DIR="$LAB/agent" PI_PROFILE= omp --no-extensions --no-skills -e "$SEED_DESK/01-welcome/index.ts"
```

In the composer enter `/seeds welcome`, then `/seeds hours`. Type `/seeds wel` to see a completion. Once `welcome` is complete, the extension returns `null` rather than trapping Enter in a completion loop. Restart the same invocation with `--seed-quiet` to suppress only the startup notice.

The read-only `seed_welcome` tool exists from this first stage. A machine calls `{"op":"discover"}` to inspect operations, topics and quiet status, or `{"op":"inspect","topic":"hours"}` to read the same opening hours as the slash command. The agent cannot invoke `/seeds` itself: both interfaces share the underlying text instead. Headless command hosts receive a custom message with `triggerTurn: false`, not a hidden notification or a provider call.

## 2. The agent interface expands into an inventory query

Exit stage 1; keep the shell variables above:

```sh
PI_CODING_AGENT_DIR="$LAB/agent" PI_PROFILE= omp --no-extensions --no-skills -e "$SEED_DESK/02-catalog/index.ts"
```

Try `/seeds query`, `/seeds query herb`, and `/seeds inspect basil-genovese`. Both the slash interface and `seed_catalog` use `catalog.ts`; the herb query returns only Genovese basil with eight fictional packets.

Tool examples for an authorized model session or an SDK host:

```json
{"op":"query","family":"herb"}
```

```json
{"op":"inspect","id":"basil-genovese"}
```

The tool returns human-readable `content` plus typed `details` with the seed records. Unknown inspect IDs throw; cancellation uses the provided `AbortSignal`. A model session needs your normal provider setup and can incur provider charges; the private workbook proof uses no provider.

## 3. Reservations become guarded session state

For a standalone download, first install the stage-3 dependencies as described above. Then launch:

```sh
PI_CODING_AGENT_DIR="$LAB/agent" PI_PROFILE= omp --no-extensions --no-skills -e "$SEED_DESK/03-reservations/index.ts" --session "$LAB/seed-session.jsonl"
```

1. `/seeds query` shows fictional availability and a revision.
2. `/seeds reserve basil-genovese 2` asks for confirmation. Cancel once: nothing changes. Confirm a second time: this branch now reserves two fictional packets.
3. Agent acts start disabled. `/seeds agent on` asks the human to authorize session-local agent reservations. The tool cannot grant itself permission.
4. A machine calls `seed_desk` with `{"op":"discover"}` for capabilities, then `{"op":"query"}` for IDs, availability, and the current revision. `{"op":"inspect","id":"basil-genovese"}` reads one item.
5. Copy the **actual** returned revision into an act:

```json
{"op":"act","action":"reserve","id":"bean-scarlet","packets":1,"expectedRevision":"COPY_THE_LATEST_RETURNED_REVISION"}
```

The uppercase value is an instruction to replace it, not a usable token. A successful act returns the new revision and updated seed. Reusing the old token refuses with `details.ok: false` and `details.code: "stale-revision"`. Query before deciding whether to retry. `action: "release"` removes held fictional packets; it cannot release more than this branch holds.

6. `/seeds agent off` revokes permission. Human reserve/release commands still work through confirmation.
7. Exit and repeat the same invocation with the same `--session` path. State is reconstructed from real custom session entries. Navigate the session tree to before a reservation: that reservation disappears on the active branch, while the original sibling retains its own state.

### Boundaries worth keeping

- `appendEntry` stores extension state, not model-visible conversation. Ordinary session persistence handles disk writes; the API does not return an fsync receipt.
- Reconstruction uses `getBranch()`, never all session entries. Every request reconstructs; lifecycle events also refresh the UI status. No process-global reservation cache exists.
- Revision = session ID + latest seed-state entry ID. Unrelated conversation does not stale the token; sibling state entries and other sessions do. Permission changes also advance the revision.
- Tool approval is `write` for the whole mixed-operation tool. OMP's host approval policy and the story's human permission are separate gates. Neither is a sandbox against arbitrary extensions or general shell tools.
- No asynchronous work occurs between revision validation and append. A human dialog **does** await; its handler reconstructs and checks the revision again before committing.
- Invalid IDs, quantities, insufficient fictional availability, excess release, stale revisions, and malformed stored snapshots refuse without appending state. Cancellation before commit changes nothing. After a completed commit, cancellation cannot undo it: query before retrying.
- Without UI, queries still work and authorized tool acts still work. Human state-changing commands refuse rather than silently approving a missing dialog.
- Notifications and `workbook:seed-desk:changed` events describe session-local changes. They do not start an agent turn. Optional tool rendering does not replace complete `content` and `details`.
- Branch inheritance is deliberate: a branch includes its ancestor's reservations and permission grants. A new session starts empty with agent permission off. Separate sessions/processes do not coordinate stock.
- This is not a real inventory system, transactional multi-user store, payment system, or durable delivery service.

## Proof status

The separate private `proof/core` harness exercises actual loader/runner/wrapper seams and JSONL session persistence, with simulated UI confirmation responses only. Its report names observed invariants and unexercised surfaces. It does not load a model or use a fake provider. This source handoff does not claim the harness has run; use the workbook's published evidence report for executed coverage. Real terminal Enter behavior and visual rendering require separate interactive proof.