skillar 0.0.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +250 -2
  3. package/dist/analysis/finding.js +190 -0
  4. package/dist/analysis/tree.js +157 -0
  5. package/dist/analysis/usage.js +394 -0
  6. package/dist/api/flows.js +285 -0
  7. package/dist/api/routes.js +192 -0
  8. package/dist/api/security.js +86 -0
  9. package/dist/api/sse.js +55 -0
  10. package/dist/api/static.js +33 -0
  11. package/dist/catalog/fields.js +159 -0
  12. package/dist/catalog/index.js +133 -0
  13. package/dist/catalog/scanner.js +204 -0
  14. package/dist/catalog/uri.js +43 -0
  15. package/dist/catalog/watcher.js +59 -0
  16. package/dist/cli/config-writer.js +255 -0
  17. package/dist/cli/doctor.js +268 -0
  18. package/dist/cli/eval.js +64 -0
  19. package/dist/cli/export-import.js +68 -0
  20. package/dist/cli/init.js +272 -0
  21. package/dist/cli/main.js +165 -0
  22. package/dist/cli/open.js +24 -0
  23. package/dist/cli/serve.js +147 -0
  24. package/dist/config.js +92 -0
  25. package/dist/dashboard/assets/app.js +354 -0
  26. package/dist/dashboard/assets/chunk-5DFWNJC2.js +1 -0
  27. package/dist/dashboard/assets/chunk-S6B2HJQA.js +17 -0
  28. package/dist/dashboard/assets/styles.css +542 -0
  29. package/dist/dashboard/index.html +15 -0
  30. package/dist/fs-watchdog.js +35 -0
  31. package/dist/herdr/client.js +205 -0
  32. package/dist/herdr/sync.js +342 -0
  33. package/dist/ingest/attribution.js +80 -0
  34. package/dist/ingest/hooks.js +168 -0
  35. package/dist/ingest/identity.js +4 -0
  36. package/dist/ingest/mcp-recorder.js +41 -0
  37. package/dist/ingest/otlp-traces.js +106 -0
  38. package/dist/ingest/otlp.js +314 -0
  39. package/dist/ingest/pipeline.js +119 -0
  40. package/dist/ingest/redact.js +36 -0
  41. package/dist/ingest/runtimes.js +25 -0
  42. package/dist/mcp/dispatch.js +54 -0
  43. package/dist/mcp/http.js +112 -0
  44. package/dist/mcp/legacy.js +61 -0
  45. package/dist/mcp/pagination.js +17 -0
  46. package/dist/mcp/protocol.js +121 -0
  47. package/dist/mcp/skills-extension.js +77 -0
  48. package/dist/mcp/stdio-proxy.js +108 -0
  49. package/dist/mcp/tools.js +59 -0
  50. package/dist/packs/claude-code.js +176 -0
  51. package/dist/packs/codex.js +207 -0
  52. package/dist/packs/cursor.js +97 -0
  53. package/dist/packs/gajae.js +7 -0
  54. package/dist/packs/gemini.js +90 -0
  55. package/dist/packs/json-config.js +55 -0
  56. package/dist/packs/omo.js +154 -0
  57. package/dist/packs/openclaw.js +132 -0
  58. package/dist/packs/registry.js +13 -0
  59. package/dist/search/fts.js +61 -0
  60. package/dist/search/fusion.js +50 -0
  61. package/dist/search/guidance.js +7 -0
  62. package/dist/search/index.js +74 -0
  63. package/dist/search/lexical.js +69 -0
  64. package/dist/server.js +267 -0
  65. package/dist/store/automation.js +18 -0
  66. package/dist/store/db.js +134 -0
  67. package/dist/store/execution.js +157 -0
  68. package/dist/store/export.js +269 -0
  69. package/dist/store/index.js +14 -0
  70. package/dist/store/migrations/002_tracing.sql +94 -0
  71. package/dist/store/migrations/003_tracing_indexes.sql +11 -0
  72. package/dist/store/migrations/004_load_reconciliation.sql +50 -0
  73. package/dist/store/migrations/005_execution_boundaries.sql +6 -0
  74. package/dist/store/migrations/006_recording_order.sql +72 -0
  75. package/dist/store/queries.js +643 -0
  76. package/dist/store/schema.sql +96 -0
  77. package/dist/store/workflow.js +250 -0
  78. package/dist/store/writes.js +315 -0
  79. package/dist/types.js +1 -0
  80. package/dist/version.js +19 -0
  81. package/dist/workflow/compare.js +68 -0
  82. package/dist/workflow/routes.js +100 -0
  83. package/dist/workflow/spec.js +40 -0
  84. package/docs/execution-ownership.md +98 -0
  85. package/docs/mcp-conformance.md +156 -0
  86. package/docs/skill-tracing.md +294 -0
  87. package/package.json +46 -3
  88. package/packs/claude-code/README.md +5 -0
  89. package/packs/claude-code/settings.template.json +34 -0
  90. package/packs/codex/README.md +8 -0
  91. package/packs/codex/config.template.toml +12 -0
  92. package/packs/cursor/hooks.example.json +8 -0
  93. package/packs/cursor/mcp.example.json +8 -0
  94. package/packs/gajae/extension/discovery.md +5 -0
  95. package/packs/gajae/extension/index.js +52 -0
  96. package/packs/gemini/settings.example.json +16 -0
  97. package/packs/hook-post.mjs +37 -0
  98. package/packs/omo/extension/discovery.md +5 -0
  99. package/packs/omo/extension/index.js +52 -0
  100. package/packs/openclaw/.codex-plugin/plugin.json +11 -0
  101. package/packs/openclaw/.mcp.json +12 -0
  102. package/packs/openclaw/hooks/skillar-discovery/HOOK.md +8 -0
  103. package/packs/openclaw/hooks/skillar-discovery/handler.js +30 -0
  104. package/packs/openclaw/index.mjs +55 -0
  105. package/packs/openclaw/openclaw.plugin.json +22 -0
  106. package/packs/openclaw/package.json +11 -0
  107. package/packs/openclaw/skillar.json +1 -0
  108. package/src/store/migrations/002_tracing.sql +94 -0
  109. package/src/store/migrations/003_tracing_indexes.sql +11 -0
  110. package/src/store/migrations/004_load_reconciliation.sql +50 -0
  111. package/src/store/migrations/005_execution_boundaries.sql +6 -0
  112. package/src/store/migrations/006_recording_order.sql +72 -0
  113. package/src/store/schema.sql +96 -0
  114. package/src/store/task-types.json +15 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 changeroa
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,3 +1,251 @@
1
- # skillar
1
+ <h1 align="center">skillar</h1>
2
+ <p align="center"><strong>Find your local skills. See how your agents use them.</strong></p>
3
+ <p align="center"><a href="https://github.com/changeroa/skillar/blob/main/README.md">Project overview</a> · <a href="https://github.com/changeroa/skillar/blob/main/README.ko.md">한국어</a></p>
4
+ <p align="center">
5
+ <a href="https://www.npmjs.com/package/skillar"><img src="https://img.shields.io/npm/v/skillar?color=c44b2b&amp;label=npm" alt="npm version"></a>
6
+ <a href="https://github.com/changeroa/skillar/blob/main/local/package.json"><img src="https://img.shields.io/badge/Node.js-%E2%89%A524.15-333333" alt="Node.js 24.15 or newer"></a>
7
+ <a href="https://github.com/changeroa/skillar/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-333333" alt="MIT license"></a>
8
+ </p>
9
+ <p align="center"><img src="https://raw.githubusercontent.com/changeroa/skillar/main/docs/assets/gisul-workshop.png" width="960" alt="An articulated arm selects an instruction card from a cabinet and brings it to a workbench. Black ink and vermilion on warm ivory."></p>
2
10
 
3
- This name is reserved for an upcoming changeroa project. No usable code is published yet.
11
+ skillar is a local skill router for coding agents. One daemon on `127.0.0.1` indexes your existing `SKILL.md` folders, serves them over MCP, and records searches and reads in a local dashboard. Skill files stay in place.
12
+
13
+ [Install](#install) · [Connect your agents](#connect-your-agents) · [Settings](#settings) · [MCP reference](#skills-over-mcp)
14
+
15
+ ## Install
16
+
17
+ Requires **Node.js 24.15+** on **macOS or Linux**.
18
+
19
+ > **Existing gisool installation?** Follow the [safe migration guide](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md) **before installing**. The packages share the `gisool` executable, so a direct global install fails with `EEXIST`. Preserve your state and perform the controlled package handoff; do not use `--force`.
20
+
21
+ For a fresh installation:
22
+
23
+ ```sh
24
+ npm install -g skillar
25
+ skillar init --dry-run # review configuration and service changes
26
+ skillar init # connect detected runtimes and start the background service
27
+ skillar open # view the local dashboard
28
+ ```
29
+
30
+ The package installs `skillar` and the compatibility command `gisool`. For source installation, see [Develop](#develop).
31
+
32
+ ## What you get
33
+
34
+ | Capability | How it works |
35
+ | --- | --- |
36
+ | Local discovery | `search_skills` returns ranked candidates from skill roots already on your machine. |
37
+ | On-demand reads | Hosts read the chosen `SKILL.md` and supporting files with MCP `resources/read`. |
38
+ | Session history | Review searches, loads, supporting reads, native-use observations, and dashboard flows. |
39
+ | Reversible setup | Preview configuration changes, keep per-run backups, and roll back with `init`. |
40
+
41
+ ## Supported runtimes
42
+
43
+ | Runtime | `--runtime` ID |
44
+ | --- | --- |
45
+ | Claude Code | `claude-code` |
46
+ | Codex | `codex` |
47
+ | Gemini CLI | `gemini` |
48
+ | Cursor | `cursor` |
49
+ | OmO | `omo` |
50
+ | Gajae Code | `gajae` |
51
+ | OpenClaw | `openclaw` |
52
+
53
+ Packs configure MCP endpoints and runtime-specific telemetry or capture hooks. Capture coverage varies by runtime; the [tracing guide](https://github.com/changeroa/skillar/blob/main/local/docs/skill-tracing.md) documents what is observed and the herdr requirement for pane/session tracing.
54
+
55
+ Both modern MCP revision **2026-07-28** and the legacy `initialize` handshake are supported. Reading skill bodies requires a host resource reader. See the [protocol reference](#skills-over-mcp) for compatibility and transport limits.
56
+
57
+ ## Connect your agents
58
+
59
+ Preview what would change, without writing anything:
60
+
61
+ ```sh
62
+ skillar init --dry-run
63
+ ```
64
+
65
+ The dry run prints a diff for each runtime configuration it would change and the service it would install.
66
+ Depending on the runtime, changes include MCP registration, telemetry export, or capture hooks. Then apply it:
67
+
68
+ ```sh
69
+ skillar init # every detected runtime
70
+ skillar init --runtime codex,claude-code
71
+ skillar init --no-service # do not install the LaunchAgent / systemd user unit
72
+ ```
73
+
74
+ Every run backs up the files it changes under `~/.skillar/backups/`. Undo with:
75
+
76
+ ```sh
77
+ skillar init --rollback # newest run
78
+ skillar init --rollback --all # every run
79
+ ```
80
+
81
+ ## Run
82
+
83
+ `skillar init` installs a LaunchAgent (macOS) or systemd user unit (Linux) that keeps the daemon running. To run it in
84
+ the foreground instead:
85
+
86
+ ```sh
87
+ skillar serve # default port 8799
88
+ skillar serve --port 8800
89
+ ```
90
+
91
+ Open the dashboard (sessions, per-session trace, flow, and weekday-by-hour heatmap):
92
+
93
+ ```sh
94
+ skillar open # opens the browser
95
+ skillar open --print # prints the URL only
96
+ ```
97
+
98
+ Manage the background service:
99
+
100
+ ```sh
101
+ skillar service status
102
+ skillar service install
103
+ skillar service remove
104
+ ```
105
+
106
+ Check the installation:
107
+
108
+ ```sh
109
+ skillar doctor # service, daemon, token mode, FTS5, roots, index freshness, hooks, backups
110
+ skillar doctor --json
111
+ ```
112
+
113
+ Measure search quality against recorded or hand-written cases:
114
+
115
+ ```sh
116
+ skillar eval
117
+ skillar eval --cases cases.json --json
118
+ ```
119
+
120
+ ## Skill tracing
121
+
122
+ herdr is required for skill tracing; `skillar doctor` checks its socket connection. skillar joins agent sessions
123
+ to panes and compares observed skill use with registered workflows without restricting agents.
124
+ See [Skill tracing](https://github.com/changeroa/skillar/blob/main/local/docs/skill-tracing.md) for capture details, attribution limits, and the orchestrator protocol.
125
+
126
+ ## Export and import
127
+
128
+ Move your skillar setup (skill roots, config, eval cases, aliases) to another machine:
129
+
130
+ ```sh
131
+ skillar export ~/skillar-backup # settings only
132
+ skillar export ~/skillar-backup --with-history # also sessions, events, and loads
133
+ skillar import ~/skillar-backup --dry-run # preview what would be added
134
+ skillar import ~/skillar-backup # merge; existing keys are kept
135
+ ```
136
+
137
+ Import never overwrites existing settings. Run `skillar init` afterwards to connect the runtimes on the new machine.
138
+
139
+ ## Settings
140
+
141
+ `~/.skillar/config.json` (created on first run, mode 0600). `SKILLAR_HOME` selects a different home; it does not move existing data. Legacy home/database selection follows the [migration guide](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md#local-state-and-configuration).
142
+
143
+ Example settings:
144
+
145
+ ```json
146
+ {
147
+ "port": 8799,
148
+ "captureLevel": "full",
149
+ "retentionDays": null,
150
+ "roots": [{ "id": "agents", "path": "~/.agents/skills" }],
151
+ "runtimes": {}
152
+ }
153
+ ```
154
+
155
+ - `captureLevel` controls how prompt and search text is stored:
156
+ - `full` (default): the text as sent.
157
+ - `redacted`: recognized secrets (tokens, keys, passwords) are masked and the text is cut to 2048 characters.
158
+ - `metadata`: no text at all, only its SHA-256 digest and length. The dashboard shows "prompt not captured".
159
+ - `retentionDays`: `null` keeps history forever; a number deletes sessions older than that many days at startup and
160
+ once a day.
161
+ - `roots`: skill folders to index in place. Defaults cover `~/.agents/skills`, `~/.claude/skills`, `~/.codex/skills`,
162
+ `~/.gemini/skills`, `~/.omo/agent/skills`, `~/.gjc/agent/skills`, `~/.openclaw/skills`, and `~/iyen-skills/skills`.
163
+ skillar never copies or edits skill files.
164
+
165
+ Restart the daemon after editing the config.
166
+
167
+ ## Files
168
+
169
+ | Path | Purpose |
170
+ | --- | --- |
171
+ | `~/.skillar/config.json` | settings above (paths below show a fresh installation) |
172
+ | `~/.skillar/token` | bearer token (0600) shared with the runtime configs |
173
+ | `~/.skillar/skillar.db` | SQLite store: skills index, sessions, events, loads; legacy `gisool.db` stays in place |
174
+ | `~/.skillar/logs/daemon.log` | daemon log, rotated at 5 MB |
175
+ | `~/.skillar/backups/` | per-run backups used by `skillar init --rollback` |
176
+
177
+ ## Privacy
178
+
179
+ The local daemon stores its index and telemetry locally and does not upload captured telemetry. Connected agents and their model providers handle data separately. It listens on `127.0.0.1` only; MCP, ingest, and API requests require the local bearer token (the dashboard also uses a local authenticated cookie). Prompts, search queries, and skill usage are stored in the selected local SQLite store.
180
+
181
+ Capture defaults to `full`. Use the [settings](#settings) to select `redacted` or `metadata` and set retention. Redaction masks recognized secret patterns; it does not guarantee every secret is removed. Capture levels do not anonymize session IDs or paths.
182
+
183
+ ## Skills over MCP
184
+
185
+ The server implements stable SEP-2640: `server/discover` advertises `tools`, `resources`, and
186
+ `extensions["io.modelcontextprotocol/skills"]`. `search_skills` is the only tool. Use it to choose a candidate,
187
+ then read the returned `SKILL.md` URI through the host's resource reader on this server. Relative references
188
+ resolve against the skill root (the directory containing `SKILL.md`); supporting files are read only as needed.
189
+ `skills/list` and `skills/get` provide verbatim frontmatter and complete per-file SHA-256/size manifests.
190
+ The optional directory-read feature is not advertised; directories can be inferred from the manifest.
191
+
192
+ For modern requests, every call, including `server/discover`, carries `params._meta` with
193
+ `io.modelcontextprotocol/protocolVersion: "2026-07-28"` and
194
+ `io.modelcontextprotocol/clientCapabilities: {}`. Include `io.modelcontextprotocol/clientInfo`
195
+ with `{name, version}` for runtime attribution. HTTP additionally requires `MCP-Protocol-Version`,
196
+ `Mcp-Method`, and (for tool calls and resource reads) `Mcp-Name`, matching the body.
197
+ Use `Accept: application/json, text/event-stream` and the bearer token.
198
+ Modern requests need no initialization handshake or protocol session; GET and DELETE on `/mcp` return 405.
199
+ The stdio proxy forwards modern requests unchanged.
200
+
201
+ ### Legacy clients (before 2026-07-28)
202
+
203
+ The server is dual-era. A request without modern `_meta` and without a modern `MCP-Protocol-Version` header
204
+ is served under legacy semantics: `initialize` negotiates the requested revision (or answers `2025-11-25`
205
+ for unknown ones) with the same capabilities and instructions as `server/discover`. Over HTTP it returns an
206
+ `Mcp-Session-Id` whose only state is `clientInfo` for runtime attribution; unknown session IDs (e.g. after a
207
+ daemon restart) are served anonymously instead of rejected. Over stdio the proxy keeps `clientInfo` for the
208
+ process. Legacy results omit `resultType`, `ttlMs`, `cacheScope`, and the `serverInfo` `_meta`; legacy HTTP
209
+ errors are JSON-RPC errors with status 200. `ping` and an empty `resources/templates/list` are answered.
210
+ The deprecated HTTP+SSE transport (GET stream) is not offered, so 2024-11-05 clients connect over stdio.
211
+
212
+ All cacheable results include `resultType: "complete"`, `ttlMs: 60000`, and `cacheScope: "private"`.
213
+ List methods use opaque `cursor`/`nextCursor` pagination. The search tool uses its own `offset`/`limit`.
214
+ Tool schemas use JSON Schema 2020-12. Search is limited to 120 invocations per minute per daemon.
215
+
216
+ The catalog rejects invalid Agent Skills names/frontmatter and skills above 512 files or 16 MiB.
217
+ Manifests include dotfiles, dependencies, and nested skills. Skills containing symlinks or other non-regular
218
+ entries are rejected rather than served incompletely. Duplicate names are retained at distinct URIs so
219
+ hosts can disambiguate their configured roots.
220
+
221
+ A `resources/read` of a published `SKILL.md` is recorded as a dashboard `load` observation; other files
222
+ produce `read_file` observations. These do **not** activate skills, confer approval, or grant execution permissions.
223
+ Hosts own origin binding, integrity verification, consent, and activation. To join reads to a search, send
224
+ its `trace_id` as `_meta["app.skillar/traceId"]`; ordinary vendor session metadata also preserves attribution.
225
+ No prior read or connection is required. A changed file fails closed until the catalog refreshes; the host
226
+ refreshes `skills/get` and verifies against the new manifest before use.
227
+
228
+ For Codex builds with gated modern support, enable `features.mcp_2026_07_28` for third-party HTTP servers;
229
+ the separate hosted Apps flag does not apply to skillar. Client-wide experimental flags are not edited by the pack.
230
+
231
+ ## Develop
232
+
233
+ From a repository checkout (run these at the repository root):
234
+
235
+ ```sh
236
+ npm --prefix local ci
237
+ npm --prefix local run build
238
+ npm link ./local # make the built CLI available locally
239
+ npm --prefix local run typecheck
240
+ npm --prefix local test # unit tests plus test/e2e, which spawns the real daemon in a sandbox HOME
241
+ node local/bench/search.mjs --check
242
+ node local/bench/mcp-mutations.mjs # each regression is injected in memory; files stay unchanged
243
+ ```
244
+
245
+ Architecture: [daemon and storage design](https://github.com/changeroa/skillar/blob/main/docs/skillar.md).
246
+
247
+ ## More documentation
248
+
249
+ [Project overview](https://github.com/changeroa/skillar/blob/main/README.md) · [Upgrade & compatibility](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md) · [MIT license](https://github.com/changeroa/skillar/blob/main/LICENSE)
250
+
251
+ The former personal Cloudflare deployment is retired. The local CLI needs no hosted service; separate registry and organization deployment context is covered in the [project documentation](https://github.com/changeroa/skillar/blob/main/README.md#remote-registry-and-team-distribution).
@@ -0,0 +1,190 @@
1
+ import { flowTree, sessionTree } from "./tree.js";
2
+ const LABELS = ["found_top1", "found_lower", "loaded_outside_results", "native_without_search",
3
+ "searched_none_used", "no_search"];
4
+ const str = (value) => (typeof value === "string" && value !== "" ? value : null);
5
+ const dirOf = (uri) => uri.split("/").at(-2) ?? "";
6
+ function candidateOf(value) {
7
+ if (typeof value !== "object" || value === null)
8
+ return null;
9
+ const row = value;
10
+ const uri = str(row.uri);
11
+ if (uri === null || typeof row.rank !== "number")
12
+ return null;
13
+ return { uri, name: str(row.name) ?? dirOf(uri), rank: row.rank, digest: str(row.digest) ?? "" };
14
+ }
15
+ function abstainedOf(value) {
16
+ if (typeof value !== "object" || value === null)
17
+ return null;
18
+ const row = value;
19
+ const reason = str(row.reason);
20
+ return reason === null ? null : { reason: reason, hint: str(row.hint) ?? "" };
21
+ }
22
+ /** R1 of the duplicate research: candidates whose SKILL.md digest is identical are copies of one skill and share one
23
+ * rank, so a distinct skill behind two copies is rank 2, not rank 3. Candidates without a digest stand alone. */
24
+ function collapse(candidates) {
25
+ const byDigest = new Map();
26
+ const groups = [];
27
+ for (const candidate of [...candidates].sort((a, b) => a.rank - b.rank || a.uri.localeCompare(b.uri))) {
28
+ const known = candidate.digest === "" ? undefined : byDigest.get(candidate.digest);
29
+ if (known) {
30
+ known.push(candidate);
31
+ continue;
32
+ }
33
+ const group = [candidate];
34
+ if (candidate.digest !== "")
35
+ byDigest.set(candidate.digest, group);
36
+ groups.push(group);
37
+ }
38
+ return groups.map((members, i) => ({ rank: i + 1, members }));
39
+ }
40
+ function searchOf(event) {
41
+ const raw = Array.isArray(event.data.candidates) ? event.data.candidates : [];
42
+ return { query: str(event.data.query) ?? event.text ?? "", abstained: abstainedOf(event.data.abstained),
43
+ groups: collapse(raw.flatMap((value) => candidateOf(value) ?? [])) };
44
+ }
45
+ function usedSkillOf(event, digestOf) {
46
+ if (event.kind !== "load" && event.kind !== "native_skill")
47
+ return null;
48
+ const uri = event.skillUri ?? str(event.data.uri) ?? str(event.data.skillUri);
49
+ const name = str(event.data.name) ?? (uri === null ? "" : dirOf(uri));
50
+ const loadId = str(event.data.loadId);
51
+ return { uri, name, via: event.kind === "load" ? "load" : "native", loadId, digest: digestOf?.({ uri, loadId }) ?? null };
52
+ }
53
+ const matchesUri = (candidate, used) => used.uri !== null && candidate.uri === used.uri;
54
+ const matchesName = (candidate, used) => used.name !== "" && (candidate.name === used.name || dirOf(candidate.uri) === used.name);
55
+ /** missedLater asks whether a search surfaced a skill at all, which todo 7 words as its uri or its name; this is
56
+ * deliberately looser than the identity a rank needs. */
57
+ const matches = (candidate, used) => matchesUri(candidate, used) || matchesName(candidate, used);
58
+ /** A rank belongs to the skill the search actually returned: the same uri, or a candidate with the same SKILL.md
59
+ * digest, which R1 defines as a copy of that skill. A shared name is never proof of identity, so a known uri the
60
+ * search did not return stays unranked even when a same-named variant was a candidate. A native activation reports
61
+ * only a name, so it takes a rank when every candidate carrying that name is one collapsed skill. */
62
+ function rankIn(search, used) {
63
+ if (search === null)
64
+ return null;
65
+ const byUri = search.groups.find((group) => group.members.some((member) => matchesUri(member, used)));
66
+ if (byUri)
67
+ return byUri.rank;
68
+ const byDigest = used.digest === null ? undefined
69
+ : search.groups.find((group) => group.members.some((member) => member.digest === used.digest));
70
+ if (byDigest)
71
+ return byDigest.rank;
72
+ if (used.uri !== null)
73
+ return null;
74
+ const named = search.groups.filter((group) => group.members.some((member) => matchesName(member, used)));
75
+ return named.length === 1 ? named[0].rank : null;
76
+ }
77
+ /** Label precedence: the strongest evidence of where the used skills came from wins, so a turn that used a native
78
+ * skill before searching and then loaded the top hit reads as found_top1 while `nativeWithoutSearch` stays true. */
79
+ function labelOf(searched, used, nativeWithoutSearch) {
80
+ if (used.some((skill) => skill.rankInSearch === 1))
81
+ return "found_top1";
82
+ if (used.some((skill) => skill.rankInSearch !== null))
83
+ return "found_lower";
84
+ if (nativeWithoutSearch)
85
+ return "native_without_search";
86
+ if (used.length > 0)
87
+ return "loaded_outside_results";
88
+ return searched ? "searched_none_used" : "no_search";
89
+ }
90
+ /** Reads one turn in event order: a search updates what the next use can be ranked against, so a turn with several
91
+ * searches ranks each load against the latest search before it. `later` holds the turns after this one in the session.
92
+ */
93
+ export function analyzeTurn(turn, later = [], digestOf) {
94
+ const searches = [];
95
+ const used = [];
96
+ const abstentions = [];
97
+ let latest = null;
98
+ let nativeWithoutSearch = false;
99
+ for (const event of turn.events) {
100
+ if (event.kind === "search") {
101
+ latest = searchOf(event);
102
+ searches.push(latest);
103
+ if (latest.abstained !== null)
104
+ abstentions.push(latest.abstained);
105
+ continue;
106
+ }
107
+ const skill = usedSkillOf(event, digestOf);
108
+ if (skill === null)
109
+ continue;
110
+ if (skill.via === "native" && latest === null)
111
+ nativeWithoutSearch = true;
112
+ used.push({ uri: skill.uri, name: skill.name, via: skill.via, ts: event.ts, rankInSearch: rankIn(latest, skill) });
113
+ }
114
+ // One row per candidate uri; when several searches returned it, the latest search's ranks are the reported ones.
115
+ const candidates = new Map();
116
+ for (const search of searches) {
117
+ for (const group of search.groups) {
118
+ for (const member of group.members) {
119
+ candidates.set(member.uri, { uri: member.uri, name: member.name, rank: group.rank, rawRank: member.rank, copies: group.members.length });
120
+ }
121
+ }
122
+ }
123
+ const surfaced = searches.flatMap((search) => search.groups.flatMap((group) => group.members));
124
+ const missedLater = new Map();
125
+ if (searches.length > 0) {
126
+ for (const next of later) {
127
+ for (const event of next.events) {
128
+ const skill = usedSkillOf(event);
129
+ if (skill === null || surfaced.some((candidate) => matches(candidate, skill)))
130
+ continue;
131
+ const key = skill.uri ?? skill.name;
132
+ if (!missedLater.has(key))
133
+ missedLater.set(key, { uri: skill.uri, name: skill.name, via: skill.via, turnId: next.id, ts: event.ts });
134
+ }
135
+ }
136
+ }
137
+ return { turnId: turn.id, searched: searches.length > 0, queries: searches.map((search) => search.query),
138
+ candidates: [...candidates.values()].sort((a, b) => a.rank - b.rank || a.rawRank - b.rawRank || a.uri.localeCompare(b.uri)),
139
+ loadedSkills: used, abstained: abstentions.length > 0, abstentions,
140
+ nativeWithoutSearch, missedLater: [...missedLater.values()], label: labelOf(searches.length > 0, used, nativeWithoutSearch) };
141
+ }
142
+ export function aggregateFindings(turns) {
143
+ const labels = Object.fromEntries(LABELS.map((label) => [label, 0]));
144
+ const ranks = [];
145
+ let abstainedSearches = 0;
146
+ let abstainedTurns = 0;
147
+ for (const turn of turns) {
148
+ labels[turn.label] += 1;
149
+ abstainedSearches += turn.abstentions.length;
150
+ if (turn.abstained)
151
+ abstainedTurns += 1;
152
+ for (const skill of turn.loadedSkills)
153
+ if (skill.rankInSearch !== null)
154
+ ranks.push(skill.rankInSearch);
155
+ }
156
+ return { turns: turns.length, labels, abstainedSearches, abstainedTurns,
157
+ meanRank: ranks.length === 0 ? null : ranks.reduce((sum, rank) => sum + rank, 0) / ranks.length };
158
+ }
159
+ export function analyzeSession(tree, digestOf) {
160
+ const turns = tree.turns.map((turn, i) => analyzeTurn(turn, tree.turns.slice(i + 1), digestOf));
161
+ return { sessionId: tree.id, turns, aggregate: aggregateFindings(turns) };
162
+ }
163
+ /** The SKILL.md digest of what a load actually read, taken from the resource list stored with that load. It is the
164
+ * same digest a candidate carries, so a load of an identical copy under another uri is recognised as that skill. */
165
+ export function loadedDigests(store) {
166
+ return ({ uri, loadId }) => (uri === null || loadId === null
167
+ ? undefined
168
+ : store.getLoad(loadId)?.resources.find((resource) => resource.uri === uri)?.digest);
169
+ }
170
+ export function sessionFinding(store, sessionId) {
171
+ const tree = sessionTree(store, sessionId);
172
+ return tree ? analyzeSession(tree, loadedDigests(store)) : undefined;
173
+ }
174
+ export function flowFinding(store, flowOrWorkspaceId) {
175
+ const flow = flowTree(store, flowOrWorkspaceId);
176
+ if (!flow)
177
+ return undefined;
178
+ const sessions = new Map();
179
+ const digestOf = loadedDigests(store);
180
+ for (const tab of flow.tabs) {
181
+ for (const pane of tab.panes) {
182
+ for (const link of pane.sessions) {
183
+ if (link.session !== null && !sessions.has(link.session.id))
184
+ sessions.set(link.session.id, analyzeSession(link.session, digestOf));
185
+ }
186
+ }
187
+ }
188
+ const list = [...sessions.values()];
189
+ return { id: flow.id, sessions: list, aggregate: aggregateFindings(list.flatMap((session) => session.turns)) };
190
+ }
@@ -0,0 +1,157 @@
1
+ import { scopeSession } from "../store/execution.js";
2
+ const PROMPT_JOIN_WINDOW_MS = 5_000;
3
+ /** Pure assembly: prompt pairs precede keyless timestamp membership; row order breaks equal-time event ties.
4
+ * A boundary at the same timestamp wins over the preceding turn, independent of ingest order.
5
+ */
6
+ export function assembleSession(data) {
7
+ // These are local accumulators, never cached or written back to the store.
8
+ const boundaries = new Map();
9
+ const add = (id, startedAt, basis) => {
10
+ const old = boundaries.get(id);
11
+ if (!old || startedAt < old.startedAt)
12
+ boundaries.set(id, { id, startedAt, basis });
13
+ };
14
+ if (data.runtime === "codex") {
15
+ for (const span of data.spans) {
16
+ if (span.name === "codex.turn_input" && span.turnKey !== undefined && span.startMs !== undefined) {
17
+ add(span.turnKey, span.startMs, "reported");
18
+ }
19
+ }
20
+ }
21
+ const prompts = data.events.filter((e) => e.kind === "prompt");
22
+ // Collect every reported boundary before considering fallbacks, including telemetry received after a hook.
23
+ for (const prompt of prompts) {
24
+ if (prompt.turnKey !== null && !boundaries.has(prompt.turnKey))
25
+ add(prompt.turnKey, prompt.ts, "reported");
26
+ }
27
+ const reportedBoundaries = [...boundaries.values()].sort((a, b) => a.startedAt - b.startedAt || a.id.localeCompare(b.id));
28
+ const pairedPrompts = new Map();
29
+ if (data.runtime === "claude-code" || data.runtime === "codex") {
30
+ for (const boundary of reportedBoundaries) {
31
+ const reference = prompts.find((p) => p.turnKey === boundary.id);
32
+ const strength = (prompt) => {
33
+ if (!reference)
34
+ return 0; // Codex turn_input spans carry identity and time, not prompt content.
35
+ if (reference.text !== null && prompt.text !== null && reference.text !== prompt.text)
36
+ return -1;
37
+ const length = reference.textLength ?? reference.data.promptLength;
38
+ const observedLength = prompt.textLength ?? prompt.data.promptLength;
39
+ if (typeof length === "number" && typeof observedLength === "number" && length !== observedLength)
40
+ return -1;
41
+ if (reference.text !== null && prompt.text !== null)
42
+ return 2;
43
+ return typeof length === "number" && length === observedLength ? 1 : 0;
44
+ };
45
+ // Each boundary consumes one observation, and each observation can be consumed only once.
46
+ // Exclude contradictory capture; prefer captured identity, then nearest time, with earlier ties.
47
+ const match = prompts.filter((p) => p.turnKey === null && !pairedPrompts.has(p.id) &&
48
+ Math.abs(boundary.startedAt - p.ts) <= PROMPT_JOIN_WINDOW_MS && strength(p) >= 0)
49
+ .sort((a, b) => strength(b) - strength(a) ||
50
+ Math.abs(boundary.startedAt - a.ts) - Math.abs(boundary.startedAt - b.ts) ||
51
+ a.ts - b.ts || a.id.localeCompare(b.id))[0];
52
+ if (match)
53
+ pairedPrompts.set(match.id, boundary.id);
54
+ }
55
+ }
56
+ for (const prompt of prompts) {
57
+ if (prompt.turnKey === null && !pairedPrompts.has(prompt.id)) {
58
+ add(`prompt:${prompt.id}`, prompt.ts, "inferred_time");
59
+ }
60
+ }
61
+ const ordered = [...boundaries.values()].sort((a, b) => a.startedAt - b.startedAt || a.id.localeCompare(b.id));
62
+ const newestFirst = [...ordered].reverse();
63
+ const byTurn = new Map();
64
+ const unassignedEvents = [];
65
+ for (const event of data.events) {
66
+ let key = event.turnKey ?? pairedPrompts.get(event.id) ?? null;
67
+ let basis = "reported";
68
+ if (key === null && event.kind === "tool_call") {
69
+ const joined = data.spans.filter((s) => s.turnKey !== undefined &&
70
+ ((event.callId !== null && s.callId === event.callId) ||
71
+ (event.spanId !== null && s.spanId === event.spanId && s.traceId === event.data.otelTraceId)));
72
+ const keys = new Set(joined.map((s) => s.turnKey));
73
+ if (keys.size === 1)
74
+ key = joined[0]?.turnKey ?? null;
75
+ basis = "span_join";
76
+ }
77
+ if (key === null) {
78
+ key = newestFirst.find((b) => b.startedAt <= event.ts)?.id ?? null;
79
+ basis = "inferred_time";
80
+ }
81
+ // A reported key without a known boundary is not silently relabelled as a different turn.
82
+ if (key === null || !boundaries.has(key)) {
83
+ unassignedEvents.push(event);
84
+ continue;
85
+ }
86
+ const list = byTurn.get(key) ?? [];
87
+ list.push({ event, basis });
88
+ byTurn.set(key, list);
89
+ }
90
+ const lastTs = data.events.at(-1)?.ts ?? data.startedAt;
91
+ const turns = ordered.map((boundary, i) => {
92
+ const endedAt = ordered[i + 1]?.startedAt ?? data.endedAt ?? lastTs;
93
+ const events = [];
94
+ const active = new Map();
95
+ for (const { event, basis } of byTurn.get(boundary.id) ?? []) {
96
+ const name = typeof event.data.name === "string" ? event.data.name : "";
97
+ const uri = event.skillUri ?? (typeof event.data.uri === "string" ? event.data.uri : null);
98
+ if (event.kind === "load" || event.kind === "native_skill") {
99
+ const skillName = name || uri?.split("/").at(-2) || "unknown";
100
+ const skill = uri ?? skillName;
101
+ // Native and MCP observations of the same named skill are one activation, not two co-active skills.
102
+ const existing = [...active.values()].find((s) => s.skill === skill || (s.name === skillName && (s.uri === null || uri === null)));
103
+ if (!existing) {
104
+ const activation = { ...event, basis, attribution: "no_skill", skills: [] };
105
+ active.set(skill, { id: event.id, skill, uri, name: skillName, startedAt: event.ts, endedAt, activation, events: [] });
106
+ }
107
+ else if (existing.uri === null && uri !== null) {
108
+ existing.uri = uri;
109
+ }
110
+ }
111
+ const reported = event.kind === "llm_call" && typeof event.data.skillName === "string" ? event.data.skillName : null;
112
+ const action = event.kind === "tool_call" || event.kind === "llm_call";
113
+ const skills = reported !== null ? [reported] : action ? [...active.keys()] : [];
114
+ const assigned = { ...event, basis, skills,
115
+ attribution: reported !== null ? "reported" : skills.length > 1 ? "co_active" : skills.length === 1 ? "single" : "no_skill" };
116
+ events.push(assigned);
117
+ if (action) {
118
+ for (const span of active.values()) {
119
+ if (reported === null || span.name === reported || span.skill === reported)
120
+ span.events.push(assigned);
121
+ }
122
+ }
123
+ }
124
+ const skillSpans = [...active.values()];
125
+ return { ...boundary, endedAt, events, skillSpans };
126
+ });
127
+ return { id: data.id, runtime: data.runtime, startedAt: data.startedAt, endedAt: data.endedAt, turns, unassignedEvents };
128
+ }
129
+ export function sessionTree(store, sessionId) {
130
+ const data = store.treeSessionData(sessionId);
131
+ return data ? assembleSession(data) : undefined;
132
+ }
133
+ export function flowTree(store, flowOrWorkspaceId, scope = store.flowEventScope(flowOrWorkspaceId)) {
134
+ const data = store.treeFlowData(flowOrWorkspaceId, scope);
135
+ if (!data)
136
+ return undefined;
137
+ const sessions = new Map();
138
+ for (const link of data.links) {
139
+ if (link.sessionId !== null && !sessions.has(link.sessionId)) {
140
+ const input = store.treeSessionData(link.sessionId, scope);
141
+ const session = input ? assembleSession(input) : null;
142
+ sessions.set(link.sessionId, session && scope ? scopeSession(session, scope) : session);
143
+ }
144
+ }
145
+ return { id: data.id, workspaceId: data.workspaceId, label: data.label, registered: data.registered,
146
+ tabs: data.tabs.map((tab) => ({ ...tab, panes: data.panes.filter((p) => p.tabId === tab.id).map((pane) => ({
147
+ ...pane, sessions: data.links.filter((l) => l.paneId === pane.id).map((link) => ({ ...link,
148
+ basis: link.source === "inferred:cwd_time" ? "inferred" : "reported",
149
+ session: link.sessionId === null ? null : sessions.get(link.sessionId) ?? null })),
150
+ })) })) };
151
+ }
152
+ export function outsideHerdr(store, opts) {
153
+ return { id: "outside-herdr", sessions: store.outsideHerdrSessionIds(opts).flatMap((id) => {
154
+ const session = sessionTree(store, id);
155
+ return session ? [session] : [];
156
+ }) };
157
+ }