AGENTS.md@packages/omo-senpi/plugin git:20261008.65255dcA

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

# 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"` (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.