AGENTS.md@packages/plugin-kit git:20260801.c20ee9aA

Immutable. This exact content is served forever at /api/v1/blob/cb08dd6cc8a7f313.

# AGENTS.md - packages/plugin-kit

> Local entry for `packages/plugin-kit`.
> Repository harness entry: `../../harness/README.md`.

## Module Positioning

`pulse-coder-plugin-kit` is the umbrella package for engine plugins and plugin infrastructure. It currently contains five reusable subsystems, each behind its own subpath export:

- Worktree binding (`/worktree`): file-backed worktree records, scope-to-worktree bindings, `AsyncLocalStorage` run context, and a prompt-injection engine plugin.
- Vault binding (`/vault`): file-backed per-project/per-tenant workspace directories, vault resolution, prompt injection, and the optional `vault_inspect` tool.
- Devtools (`/devtools`): run, LLM, tool, compaction, hook timing, prompt snapshot, token/cost, tool-stat, error, and cache timeline diagnostics.
- Memory (`/memory`): host-side memory service, engine plugin integration, daily-log extraction, semantic/keyword recall, embeddings (carries the `better-sqlite3` native dep). Formerly `packages/memory-plugin`.
- Langfuse (`/langfuse`): optional observability engine plugin. Formerly `packages/langfuse-plugin`.

This package should expose reusable infrastructure primitives and engine plugins. Host-specific policy should stay in the host app or plugin using the kit.

## Knowledge Navigation

| Task | Read |
|---|---|
| Package overview | `README.md` |
| Public exports | `src/index.ts`, `src/worktree.ts`, `src/vault.ts`, `src/devtools.ts` (+ subpath entries `src/memory/index.ts`, `src/langfuse/index.ts`) |
| Worktree contracts | `src/worktree/types.ts`, `src/worktree/service.ts`, `src/worktree/integration.ts` |
| Vault contracts | `src/vault/types.ts`, `src/vault/service.ts`, `src/vault/integration.ts`, `src/vault/tools.ts` |
| Devtools contracts | `src/devtools/index.ts` |
| Memory module (invariants, layered storage, embeddings) | `harness/knowledge/memory.md` |
| Langfuse module (privacy defaults, flushing contract) | `harness/knowledge/langfuse.md` |
| Build/export shape | `package.json`, `tsup.config.ts`, `tsconfig.json` |

## Local Constraints

- Keep utilities host-neutral and reusable.
- Do not commit secrets, vault contents, worktree state, prompt snapshots, or host-local runtime data from `~/.pulse-coder/*`.
- Export path changes are public contract changes; coordinate with consumers.
- Worktree behavior should be conservative around user changes and branch state.
- Vault paths are for artifacts/config/logs, not a substitute for git worktree paths.
- Devtools may capture user text, prompts, tool inputs/outputs, and generated text. Keep redaction and `saveUserText`/prompt capture options intact when changing diagnostics.
- Services use file-backed JSON with queued writes in-process; do not assume cross-process locking without adding it deliberately.
- Memory: semantic recall must degrade safely when embeddings/SQLite are unavailable; preserve daily-log quality gates/quotas/dedupe; layered storage layout and legacy `state.json` migration are compatibility contracts (detail: `harness/knowledge/memory.md`).
- Langfuse: stays optional; credentials env-only; `saveUserText`/`saveLLMOutput` default ENABLED (privacy is a host decision); never block the loop on flushing (detail: `harness/knowledge/langfuse.md`).

## Common Commands

For docs-only changes, use the harness docs rule: check referenced paths and commands.

```bash
SKIP_DTS=1 pnpm --filter pulse-coder-plugin-kit build
pnpm --filter pulse-coder-plugin-kit test
```

`test` runs the real memory specs (`src/memory/service.test.ts`, `src/memory/integration.test.ts`); the former `--passWithNoTests` flag is gone. Coverage is memory-only — worktree/vault/devtools/langfuse still have no specs, so green ≠ coverage there. `typecheck` is listed in harness validation, but currently fails locally with TS6059 `rootDir` errors from engine source imports plus deep Zod/FlexibleSchema type instantiation errors in `src/devtools/index.ts` and `src/vault/tools.ts`. Default `build` runs declaration generation, so use the skipped-DTS build only as a JS packaging smoke until the TypeScript boundary is fixed.

## Key Files

- `src/index.ts`: umbrella public exports.
- `src/worktree.ts`, `src/worktree/index.ts`: worktree subpath exports.
- `src/worktree/service.ts`: `FileWorktreePluginService`, worktree CRUD, and scope binding state.
- `src/worktree/integration.ts`: worktree engine plugin and run context adapter.
- `src/vault.ts`, `src/vault/index.ts`: vault subpath exports.
- `src/vault/service.ts`: `FileVaultPluginService` and vault directory/index management.
- `src/vault/integration.ts`: vault engine plugin, resolver, prompt injection, and inspect-tool registration.
- `src/vault/tools.ts`: `vault_inspect` tool implementation.
- `src/devtools.ts`, `src/devtools/index.ts`: devtools store, engine plugin, run lookup tool, stats, errors, prompt snapshots, and cache timeline analysis.
- `src/memory/service.ts`, `src/memory/integration.ts`: memory service, engine hooks, and tools (see `harness/knowledge/memory.md`).
- `src/langfuse/index.ts`: Langfuse plugin factory and options.
- `package.json`: package exports and build behavior.