Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Skill resolver docs: bench wording matches the nine-round bench; key-files index covers the lane turn settings, Codex SessionStart, pi and cursor, and the new resolver files
garrytanbecbe34e3d60
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.mdindex 23c49003fa..2e03303791 100644--- a/docs/architecture/key-files/skills.md+++ b/docs/architecture/key-files/skills.md@@ -57,15 +57,19 @@ Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under- `src/core/skills/resolver/session.ts` — session state (`sessions/<sha256(scope, harness, id)>.json`: ids and counters only), `commitSession` under a short lease, file and id caps, 7-day GC with a per-run work bound; every commit (sync or async) then starts an async GC pass after it settles, at most once per `GC_INTERVAL_MS` (10 min) per home by the mtime of `logs/session-gc.stamp`, so new sessions keep deduping past `MAX_SESSION_FILES`.- `src/core/skills/resolver/handle.ts` — `openCatalog(catalogs, opts)`, the warm handle for long-lived hosts: keeps each catalog's receipt and open `IndexReader` and the settings, re-stats `receipt.json`, `index.bin` and `config.json` once per turn and reloads only what changed; turns run `resolve.ts` `runTurn`, so output, `pending`, `commit()` and errors equal `resolveSkills` apart from `meta.timing_ms` (`test/skill-resolver-runtime.test.ts`).- `src/core/skills/resolver/build-thread.ts` — `buildSkillIndexOffThread`: `buildSkillIndex` in a `node:worker_threads` Worker whose entry is the module's own URL (in the Node bundle, the bundle), run by a top-level guard keyed on `BUILD_THREAD_MARKER` in `workerData`; no worker file ships; a `ResolverError` comes back with its code, message, fix and context. The hook lane never reaches it (`test/skill-resolver-module-graph.test.ts`).-- `src/core/skills/resolver/block.ts` — the `<relevant_skills>` block: header, one JSON-quoted line per suggestion (id, name, path for codex and openclaw, summary unless names-only), one load line per harness or `--load-hint`, cut at whole lines to 400 tokens by `estimateTokens`.+- `src/core/skills/resolver/block.ts` — the `<relevant_skills>` block: header, one JSON-quoted line per suggestion (id, name, path for codex, openclaw, pi and cursor, summary unless names-only), one load line per harness or `--load-hint`, cut at whole lines to 400 tokens by `estimateTokens`.- `src/core/skills/resolver/lock.ts` — ownership leases (O_EXCL create, random token, expiry; reclaimed only after expiry; release and renewal check the token).-- `src/core/skills/resolver/config.ts` — `skills.resolver.session_token_budget` (0 or 100-50,000, default 2,000) and `auto_rebuild` / `GBRAIN_SKILLS_NO_AUTOREBUILD=1`, read straight from `config.json`.+- `src/core/skills/resolver/config.ts` — `skills.resolver.session_token_budget` (0 or 100-50,000, default 2,000) and `auto_rebuild` / `GBRAIN_SKILLS_NO_AUTOREBUILD=1`, read straight from `config.json`; the lane's turn settings `top_k` (1-8, default 5), `min_match`, `pinned` (sent to resolve as exclude) and `per_harness.<harness>.{top_k,min_match}` (falling back to the global keys) through `laneTurnSettings` and the validators `validateTopK`, `validateMinMatch` and `validatePinned` (a bad value anywhere in the section is `skill_resolver_config_invalid`).+- `src/core/skills/resolver/limits.ts` — the shared limits and names: `TOP_K_DEFAULT` (5), `TOP_K_MAX` (8), `EXCLUDE_MAX` (1,024) and `MATCH_STRENGTHS` (`named`, then the field strengths from `name` to `body`), exported from the library.+- `src/core/skills/resolver/daily-log.ts` — the lane and resolver logs under `skill-index/logs/`: one file per UTC day (`lane-<day>.jsonl`, `resolver-<day>.log`), kept 14 days, capped at 2 MB a day; the first write of a day deletes older files and the undated legacy file. Never turn text.- `src/core/skills/resolver/paths.ts` — `resolverHome` (GBRAIN_HOME convention), catalog-name rule and confinement under `skill-index/`, the fixed file names.- `src/core/skills/resolver/errors.ts` — `ResolverError` codes (rows in `src/core/error-registry.ts`), `USAGE_CODES` (exit 2).- `src/core/skills/resolver/fsutil.ts` — temp-file, fsync and rename writes; bounded reads.- `src/core/skill-description.ts` — `oneLineDescription` (frontmatter description, block scalars folded, else the first body paragraph), shared by `skill-catalog.ts`, `bundled.ts` and the bundled source.+- `src/core/skills/resolver/lane-worker.ts` — starts the hook lane's worker thread (`hook-worker.ts`) once per process; the CLI's lane fast path (`src/cli.ts`) calls it before loading the lane so the worker starts beside the CLI, and the lane takes that worker. Imports only `worker_threads`; in a compiled binary the worker path comes from the binary's `import.meta.url`. Null when the worker cannot start (the lane then reports `skill_resolver_internal`).+- `src/core/skills/resolver/catalog-files.ts` — the catalog files the turn path reads: a catalog's receipt, the list of built catalogs and the sliced stat freshness check (`listingKey`, which also hashes each symlink's target) over a directory catalog's fingerprint. No source parser, so the hook worker loads only what a turn needs; `build.ts` and `sources.ts` import it.- `src/core/skills/resolver/hook-lane.ts` + `hook-worker.ts` + `hook-input.ts` — the hook lane (`GBRAIN_HOOK_LANE=skill-resolver`, dispatched first in `src/commands/hook.ts` after the `GBRAIN_HOOKS=0` check; `--harness claude-code|codex|hermes`): per-harness wire shapes in `LANE_IO` (Claude Code and Codex: top-level `prompt` in, `hookSpecificOutput.additionalContext` out; Hermes `pre_llm_call`: `extra.user_message` in through `readJsonFields`, the streaming reader over `Bun.stdin` that keeps only the named string paths and skips any history size unbuffered, `{"context"}` out; Hermes has no owner carrier and no compaction event), async config/stdin/carrier reads on the main thread, ranking in a worker (source: `hook-worker.ts` beside it; compiled binary: the second build entrypoint at `WORKER_SRC_PATH`, so every `bun build --compile` that ships a binary lists it), a 50 ms deadline that exits the process with no output and no commit, the commit (`commitSessionAsync`) on the main thread after delivery, the payload budget (`skills.resolver.lane_payload_chars`, dropped whole as `payload_dropped`), the one-owner rule (first carrier entry whose home has the lane on), the SessionStart compaction reset, the catalogs (each only once its receipt exists, else outcome `no_catalog`: `<harness>-user`, `claude-code-plugins`, then the project catalog: `claude-code-project-<root hash>` over `.claude/skills`, or `codex-project-<dir-list hash>` over each `.agents/skills` from the `.git` root down to cwd, root first, without `~/.agents/skills`; built by a detached `skills index build`, stamp-limited to once a minute) and the daily lane log (`daily-log.ts`: `skill-index/logs/lane-<date>.jsonl`, kept 14 days). Test seams: `GBRAIN_TEST_SKILL_LANE_STALL`, `GBRAIN_TEST_SKILL_LANE_DEADLINE_MS`. Pinned by `test/skill-resolver-hook-lane.test.ts`.-- `src/core/setup/skill-resolver-{lane,hook,config,setup}.ts` — `setup <claude-code|codex> --skill-loading resolve|off` and `--remove`: the lane identity leaf (marker `skill-resolver-v1`, which every other lane's ownership and yield test excludes), the Claude Code entries and the Codex group plus its `config.toml` trust (`inspectSkillResolverHook`: absent, wired, untrusted, or outdated when UserPromptSubmit lacks its SessionStart entry; sync rewrites it), the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten; a non-object `per_harness` entry reads as unset and set/unset replace it), and the build-then-write order (≥1 skill or `skill_resolver_setup_incomplete`). Pinned by `test/setup-skill-resolver.test.ts`.+- `src/core/setup/skill-resolver-{lane,hook,config,setup}.ts` — `setup <claude-code|codex> --skill-loading resolve|off` and `--remove`: the lane identity leaf (marker `skill-resolver-v1`, which every other lane's ownership and yield test excludes), the Claude Code entries and the Codex UserPromptSubmit and SessionStart groups, each trusted in `config.toml` (`inspectSkillResolverHook`: absent, wired, untrusted, or outdated when UserPromptSubmit lacks its SessionStart entry; sync rewrites it), the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten; a non-object `per_harness` entry reads as unset and set/unset replace it), and the build-then-write order (≥1 skill or `skill_resolver_setup_incomplete`). Pinned by `test/setup-skill-resolver.test.ts`.- `src/commands/doctor/checks/skill-resolver.ts` — doctor `skill_resolver` (emitted by the `harness_wiring` entry, whose details carry the same view): hook state (an `outdated` hook warns with `gbrain setup <harness> --skill-loading resolve`), each catalog's content-tier freshness, recent lane outcomes and error codes; silent when nothing of the resolver exists.- `src/commands/skill-resolver.ts` — the CLI (`src/cli/commands/skill-resolver.ts` dispatches; `src/cli/command-route.ts` routes only `skills index`, `skills resolve` and `skills library` here, so plain `gbrain skills` stays `list_skills`). Exit 0, 1 (runtime error), 0 with `--fail-open`, 2 (usage); commits a session turn only after stdout is written. Pinned by `test/skill-resolver-cli.test.ts` and `test/skill-resolver-guide.test.ts`.- `scripts/bench-skill-resolver.ts` — the latency bars (cold turn p95: 10 ms at 1,000 skills, 40 ms at 7,500), enforced by `.github/workflows/skill-resolver-bench.yml` on a 2-vCPU runner.diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.mdindex 2b2917ad7b..6db5004b36 100644--- a/docs/guides/skill-resolver.md+++ b/docs/guides/skill-resolver.md@@ -301,8 +301,8 @@ deletes a catalog; deleting `skill-index/` removes everything.Preregistered bars: a cold turn (index opened again, ranked, one freshnessslice) at p95 10 ms with 1,000 skills and 40 ms with 7,500 skills on 2 vCPUs.-`bun scripts/bench-skill-resolver.ts` measures it in three rounds of 300 turns-and judges the median round's p95, so one burst of host stalls on a shared+`bun scripts/bench-skill-resolver.ts` runs one discarded warm-up round, then+nine rounds of 100 turns, and judges the median round's p95, so one burst of host stalls on a sharedrunner does not decide it; the `Skill resolver bench` workflow enforces it onpull requests that touch the resolver.