AGENTS.md@packages/omo-senpi/plugin git:20261019.4f0c5ebA

Immutable. This exact content never changes and is served at /api/v1/blob/2d46c498adc1c2f7.

# omo-senpi plugin

The single Pi package `@code-yeongyu/omo-senpi`: one generated extension entry, generated skills, a tracked DAG runtime, and the scripts that build, stage, sync, and install all of it. Local-path installs only (`senpi install <abs-path-to-here>`); `git:`/`npm:` installs are unsupported because `extensions/` and `skills/` are generated build outputs.

## STRUCTURE

| Path | Purpose |
|------|---------|
| `package.json` | Pi manifest: `pi.extensions = ["./extensions/omo.js"]`, deliberately NO `pi.skills` (bundled skills are contributed at runtime by `src/components/bundled-skills` via `resources_discover` so `disabled_skills` can hide them; a manifest entry loads unfiltered on the launcher `--extension` path), `imports["#omo-task-runtime"] = "./extensions/omo-task.js"`, `imports["#omo-computer-use-runtime"] = "./extensions/omo-computer-use.js"`, `imports["#omo-memory-doctor-runtime"] = "./extensions/omo-memory-doctor.js"`, `imports["#omo-memory-memfs-runtime"] = "./extensions/omo-memory-memfs.js"`, `imports["#omo-memory-palace-runtime"] = "./extensions/omo-memory-palace.js"` (the dev package maps that specifier to `src/extension/omo-task.ts`). `files` ships extensions, skills, skills-conditional, runtime, `scripts/install.mjs`, README, NOTICE, LICENSE. |
| `extensions/` | Generated, gitignored, minified single-line bundles. Eleven artifacts: `omo.js` (main entry from `src/extension/bundled-index.ts`; exports `composeOmoSenpiExtension`, default export, `omoSenpiComponents`), `omo-task.js` (`createTaskComponent`; initializes `globalThis.__zod_globalConfig`/`__zod_globalRegistry`), `omo-member.js` (team member extension, built from `packages/senpi-task/src/team/member-extension/index.ts`), `memory-run-supervisor.mjs` (memory reflection supervisor), `gateway-store-worker.mjs` (the thread gateway store's worker thread, loaded by `new Worker()` beside `omo.js` because a bundler cannot inline a worker entry), `gateway-rules-extension.mjs` (the `gateway_rules` store extension ops module the store worker imports by file URL), `omo-init-deep-advisor.js`, `omo-computer-use.js` (computer-use implementation, `createComputerUseRuntime`; loaded on first use), `omo-side-panel.js` (side-panel implementation, `createSidePanelController`; loaded on the first session with the panel on), `omo-memory-doctor.js` (the `/doctor` health checks, loaded on first invocation), `omo-memory-memfs.js` (the `/memfs` maintenance handlers, loaded on first invocation); plus persona sources `dream-persona.md`, `facts-persona.md`, `kibitzer-persona.md`, `reflection-persona.md`, and `assets.generated.json` (the computer-use prelude texts, staged from `senpi-desktop-prelude/src/assets.generated.json` and read beside the bundle at runtime through memoized getters, #9113). |
| `skills/` | Generated by `plugin/scripts/sync-skills.mjs` from the native `skills/` pool, the component-owned `ulw-loop`, and the repo `shared-skills` pool. Gitignored except the tracked senpi-local `init-deep`/`onboarding` overrides; the README lists all 19 shipped skills. |
| `skills-conditional/` | Generated by `plugin/scripts/stage-x-search-skill.mjs` from `src/components/x-search/skill/SKILL.md`. Gitignored. Must not join `pi.skills`: the x-search skill is contributed at runtime via `resources_discover` only when an xAI credential exists. `files` still ships the directory so the bundled extension can resolve `../skills-conditional/x-search/SKILL.md`, and the payload allowlists in `script/build-omo-native.ts` / `script/build-omo-binary.ts` plus the required-artifact lists must keep it too — the npm payload shipped without it until 2026-09-04. Staging builds receive the copy in `$OMO_SENPI_PLUGIN_OUTPUT`. |
| `runtime/dag/` | Tracked DAG runtime shipped with the plugin. `sdk.js` exports `define`, `start`, `attach`, `snapshot`, `wait`, `cancel`, `retry`, `send`, `amend` (run lifecycle, snapshot/wait, messaging, amendment); `library.js` validates library names (`^[A-Za-z0-9][A-Za-z0-9._-]*$`) and loads definitions from configured library dirs (the `dag-library` skill's save target). `runtime/agent-toolkit/` and `runtime/ast-grep-mcp/` are staged, gitignored vendored runtimes. `runtime/thread-sdk/sdk.js` is the tracked, generated thread SDK (`createThreadSdk`) the `omo thread` CLI imports; it runs the gateway store on `extensions/gateway-store-worker.mjs`. |
| `scripts/` | Hand-authored build/stage/sync/install pipeline. Own AGENTS.md. |

## WHERE TO LOOK

| Task | Location |
|------|----------|
| Bundle stale or wrong | `plugin/scripts/AGENTS.md` + `build-extension.mjs --check`; never debug the bundle itself |
| DAG orchestration API | `runtime/dag/sdk.js`; named/reusable dags via `runtime/dag/library.js` |
| Install behavior / launchers | `plugin/scripts/AGENTS.md` (`install.mjs`, `build-install.mjs`) and `../src/install/` |
| Shipped-skill list, disable flags, LSP migration | `README.md` (six `lsp_*` tools always registered; project `.pi/lsp-client.json` command/env entries ignored for safety) |
| Conditional x-search skill stale or missing | `plugin/scripts/stage-x-search-skill.mjs` (`--check` verifies the staged copy matches source); never add it to `pi.skills` |

## CONVENTIONS

- Dag RPC wire payloads are snake_case (`run_id`, `node_id`); the JavaScript API is camelCase (`runId`, `nodeIds`). Deliberate wire/API boundary.
- Bundles carry `// omo:<fingerprint>` build markers; freshness checks compare markers and source digests, and paths inside artifacts are made portable at build time.

## ANTI-PATTERNS

- NEVER hand-edit anything under `extensions/`, `skills/`, `skills-conditional/`, or the staged `runtime/` dirs; regenerate via `plugin/scripts/` (`build-extension.mjs`, `sync-skills.mjs`, `stage-x-search-skill.mjs`, the other stage scripts). Generated hook text repeats this: "Do not edit by hand - regenerated on startup". Do not add credential-gated skills to `pi.skills`.
- Treat bundles as opaque: minified one-liners up to ~870KB with minifier-local symbol names; LSP diagnostics on them are noise. Source of truth is `../src/` plus the build scripts.
- Do not widen the Pi manifest surface without keeping `../src/package-shape.test.ts` and `../src/plugin-manifest.test.ts` green.

## COMMANDS

```bash
node plugin/scripts/build-extension.mjs [--check]   # all six artifacts; --check verifies freshness
bun run test:senpi                                   # repo gate: build + stage + typecheck + test
```

The `/memfs` registrar remains synchronous; its handlers are loaded on first invocation from `src/components/memory/commands/memfs-runtime.ts` via `#omo-memory-memfs-runtime`, mapped to `extensions/omo-memory-memfs.js` in the published plugin. Build freshness, required artifacts and bundle audits include this sidecar.

The `/palace` and `/people` registrars remain synchronous (same names, descriptions and argument hints); the palace HTML generator, its collectors and the `/people` runtime load on the first invocation of either command from `src/components/memory/palace/runtime.ts` via `#omo-memory-palace-runtime`, mapped to `extensions/omo-memory-palace.js` in the published plugin. One import is shared per process; a failed load is not cached and is reported as an actionable error (reinstall omo, then start a new session) instead of an unhandled rejection. Build freshness, required artifacts and bundle audits include this sidecar.

The onboarding session-history scan (transcript discovery, parsing, digests) loads on the first `omo.onboarding.projects`/`omo.onboarding.sessions` call or `onboarding_session_history` tool run from `src/components/onboarding/session-history/runtime.ts` via `#omo-session-history-runtime`, mapped to `extensions/omo-session-history.js` in the published plugin. The RPC methods and the tool still register synchronously; one import is shared per process, and a failed load is not cached and is reported as an actionable error (reinstall omo, then start a new session). Build freshness, required artifacts and bundle audits include this sidecar.

The live thread RPC client is loaded on the first asynchronous thread/gateway operation via `#omo-thread-client-runtime` (`src/components/thread/live-surface.ts` in source, `extensions/omo-thread-client.js` in the plugin). The component still registers tools, the store and lifecycle handlers synchronously; the registrar captures the operator socket before loading. One runtime promise/client is shared per facade, including concurrent operations and load failures. Build freshness, required installation artifacts and bundle purity include this sidecar.

The persisted recall terms (store codec, persistence, save gate, term transfer) load on the first corpus load from `src/components/memory/recall-store-runtime.ts` via `#omo-recall-store-runtime`, mapped to `extensions/omo-recall-store.js` in the published plugin (memory-core `termStore` loader, `recall-store-runtime-loader.ts`). The entry bundle keeps only the index accessors it hands the store. One import is shared per process; a failed load is not cached and recall falls back to tokenizing. Build freshness, required artifacts and bundle audits include this sidecar.