docs: update AGENTS guidance

2026-05-18 11:49:56 +09:00
parent c4dd21e1f3
commit 34e6af1ae6
16 changed files with 1648 additions and 24 deletions
@@ -0,0 +1,51 @@
+# src/hooks/auto-update-checker/ -- npm Update Detection
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+27 files. Session Tier hook on `session.created`. Checks the npm registry for newer plugin versions, compares against the installed version, and surfaces update availability via startup toasts. Caches results to avoid repeated registry fetches. Throttled per channel (`latest`, `next`, `beta`). Skips CLI run mode and subagent sessions.
+
+## FILE CATALOG
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel exports: hook factory, checker, cache invalidation, channel helpers |
+| `hook.ts` | `createAutoUpdateCheckerHook()` -- event handler, orchestrates startup toasts and background check |
+| `checker.ts` | Barrel for `checker/` subdir -- version resolution, local dev detection, package entry finding |
+| `cache.ts` | `invalidatePackage()` -- removes package from bun.lock, node_modules, and specifier cache |
+| `version-channel.ts` | `extractChannel()` -- resolves dist-tags and prerelease versions to npm channels |
+| `types.ts` | `UpdateCheckResult`, `AutoUpdateCheckerOptions`, `NpmDistTags` |
+| `constants.ts` | Registry URL, timeouts, cache paths, accepted package names |
+
+## SUBDIRECTORIES
+
+- `checker/` -- 11 files. Core version checking logic: `check-for-update.ts`, `latest-version.ts`, `local-dev-version.ts`, `plugin-entry.ts`, `cached-version.ts`, `pinned-version-updater.ts`, `sync-package-json.ts`, plus helpers.
+- `hook/` -- 9 files. Startup UX: `background-update-check.ts`, `deferred-startup-check.ts`, `startup-toasts.ts`, `update-toasts.ts`, `spinner-toast.ts`, `config-errors-toast.ts`, `connected-providers-status.ts`, `model-capabilities-status.ts`, `model-cache-warning.ts`.
+
+## CACHE
+
+File-based deduplication via `VERSION_FILE` in the OpenCode cache directory (`getOpenCodeCacheDir()`). Prevents excessive npm registry calls. `invalidatePackage()` forces a fresh check by purging the package from Bun's lockfile, node_modules, and specifier cache.
+
+## VERSION CHANNELS
+
+`extractChannel()` maps:
+- Dist-tags (`next`, `beta`) → channel name directly
+- Prerelease versions (`1.0.0-beta.1`) → channel from prerelease prefix (`alpha`, `beta`, `rc`, `canary`, `next`)
+- Stable versions → `latest`
+
+## INTEGRATION
+
+Registered in `create-session-hooks.ts` as `autoUpdateChecker`. Part of the Session Tier hook composition.
+
+## RELATED
+
+Three `zauc-mocks-*` directories in `src/hooks/` exist specifically to test this hook with mocked dependencies:
+- `zauc-mocks-cache/` -- tests cache invalidation paths
+- `zauc-mocks-hook/` -- tests hook orchestration with mocked submodules
+- `zauc-mocks-bg/` -- tests background check scheduling
+
+## CROSS-REFERENCES
+
+- Parent: [`src/hooks/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/hooks/AGENTS.md) -- Session Tier hook list
+- [`src/cli/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/cli/AGENTS.md) -- CLI uses the same npm dist-tag helpers
@@ -0,0 +1,45 @@
+# src/hooks/compaction-context-injector/ -- Post-Compaction Context Recovery
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Continuation Tier hook. Fires on `session.compacted` to re-inject critical context lost during context-window compaction. Prevents the agent from losing its bearings after OpenCode trims session history.
+
+## TIER + EVENT
+
+- **Tier:** Continuation
+- **Event:** `session.compacted` (primary), `session.idle`, `session.deleted`, `message.updated`, `message.part.delta`, `message.part.updated`
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `hook.ts` | `createCompactionContextInjector()` -- composes capture, restore, inject, event |
+| `recovery.ts` | `createRecoveryLogic()` -- rebuilds agent/model/tools after compaction |
+| `tail-monitor.ts` | Tracks assistant output to detect no-text tails |
+| `session-prompt-config-resolver.ts` | Walks session messages to resolve current agent/model/tools |
+| `validated-model.ts` | `validateCheckpointModel()` -- model validation |
+| `session-id.ts` | `resolveSessionID()`, `isCompactionAgent()` |
+| `recovery-prompt-config.ts` | `createExpectedRecoveryPromptConfig()`, `isPromptConfigRecovered()` |
+| `constants.ts` | `RECOVERY_COOLDOWN_MS`, `NO_TEXT_TAIL_THRESHOLD`, `RECENT_COMPACTION_WINDOW_MS` |
+| `types.ts` | `CompactionContextInjector` interface |
+| `compaction-context-prompt.ts` | `COMPACTION_CONTEXT_PROMPT` -- 8-section summary template |
+| `index.ts` / `index.test.ts` | Barrel export + tests |
+| `recovery.test.ts` / `session-prompt-config-resolver.test.ts` | Unit tests |
+
+## HOW IT WORKS
+
+1. **Capture:** Before compaction, saves agent/model/tools checkpoint via `setCompactionAgentConfigCheckpoint()`
+2. **Inject:** Returns `COMPACTION_CONTEXT_PROMPT` with active delegated session history
+3. **Recover:** On `session.compacted`, dispatches internal prompt to restore checkpointed config
+4. **Tail monitor:** Detects consecutive assistant messages with no text output; triggers recovery if recent compaction
+
+## INTEGRATION
+
+Registered in `create-continuation-hooks.ts` as `compactionContextInjector`.
+
+## DISTINCTION
+
+- **`compactionTodoPreserver`:** Preserves todos only (sibling Continuation hook)
+- **`anthropicContextWindowLimitRecovery`:** Prevents the limit preemptively (Session Tier)