skillar 0.0.0 → 0.2.0

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 +193 -1
  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,195 @@
1
1
  # skillar
2
2
 
3
- This name is reserved for an upcoming changeroa project. No usable code is published yet.
3
+ [Upgrade and compatibility notes](https://github.com/changeroa/skillar/blob/main/docs/migration-skillar.md).
4
+ skillar is a local skill router. One daemon on `127.0.0.1` indexes the `SKILL.md` folders already on your machine,
5
+ serves them over MCP through `search_skills` and standard `resources/read`, records which skills
6
+ each agent session searched, loaded, and read, and shows that history in a local dashboard.
7
+
8
+ Capture packs cover Claude Code, Codex, Gemini CLI, Cursor, OmO, Gajae Code, and OpenClaw.
9
+ MCP connections accept revision 2026-07-28 and, for older clients, the legacy `initialize` handshake
10
+ (revisions 2024-11-05 through 2025-11-25, e.g. clients built on `@modelcontextprotocol/sdk` 1.x). Reading skill
11
+ bodies needs a host resource reader. Packs configure endpoints and capture hooks only.
12
+
13
+ ## Skills over MCP
14
+
15
+ The server implements stable SEP-2640: `server/discover` advertises `tools`, `resources`, and
16
+ `extensions["io.modelcontextprotocol/skills"]`. `search_skills` is the only tool. Use it to choose a candidate,
17
+ then read the returned `SKILL.md` URI through the host's resource reader on this server. Relative references
18
+ resolve against the skill root (the directory containing `SKILL.md`); supporting files are read only as needed.
19
+ `skills/list` and `skills/get` provide verbatim frontmatter and complete per-file SHA-256/size manifests.
20
+ The optional directory-read feature is not advertised; directories can be inferred from the manifest.
21
+
22
+ Every request, including `server/discover`, carries `params._meta` with
23
+ `io.modelcontextprotocol/protocolVersion: "2026-07-28"` and
24
+ `io.modelcontextprotocol/clientCapabilities: {}`. Include `io.modelcontextprotocol/clientInfo`
25
+ with `{name, version}` for runtime attribution. HTTP additionally requires `MCP-Protocol-Version`,
26
+ `Mcp-Method`, and (for tool calls and resource reads) `Mcp-Name`, matching the body.
27
+ Use `Accept: application/json, text/event-stream` and the bearer token.
28
+ Modern requests need no initialization handshake or protocol session; GET and DELETE on `/mcp` return 405.
29
+ The stdio proxy forwards modern requests unchanged.
30
+
31
+ ### Legacy clients (before 2026-07-28)
32
+
33
+ The server is dual-era. A request without modern `_meta` and without a modern `MCP-Protocol-Version` header
34
+ is served under legacy semantics: `initialize` negotiates the requested revision (or answers `2025-11-25`
35
+ for unknown ones) with the same capabilities and instructions as `server/discover`. Over HTTP it returns an
36
+ `Mcp-Session-Id` whose only state is `clientInfo` for runtime attribution; unknown session IDs (e.g. after a
37
+ daemon restart) are served anonymously instead of rejected. Over stdio the proxy keeps `clientInfo` for the
38
+ process. Legacy results omit `resultType`, `ttlMs`, `cacheScope`, and the `serverInfo` `_meta`; legacy HTTP
39
+ errors are JSON-RPC errors with status 200. `ping` and an empty `resources/templates/list` are answered.
40
+ The deprecated HTTP+SSE transport (GET stream) is not offered, so 2024-11-05 clients connect over stdio.
41
+
42
+ All cacheable results include `resultType: "complete"`, `ttlMs: 60000`, and `cacheScope: "private"`.
43
+ List methods use opaque `cursor`/`nextCursor` pagination. The search tool uses its own `offset`/`limit`.
44
+ Tool schemas use JSON Schema 2020-12. Search is limited to 120 invocations per minute per daemon.
45
+
46
+ The catalog rejects invalid Agent Skills names/frontmatter and skills above 512 files or 16 MiB.
47
+ Manifests include dotfiles, dependencies, and nested skills. Skills containing symlinks or other non-regular
48
+ entries are rejected rather than served incompletely. Duplicate names are retained at distinct URIs so
49
+ hosts can disambiguate their configured roots.
50
+
51
+ A `resources/read` of a published `SKILL.md` is recorded as a dashboard `load` observation; other files
52
+ produce `read_file` observations. These do **not** activate skills, confer approval, or grant execution permissions.
53
+ Hosts own origin binding, integrity verification, consent, and activation. To join reads to a search, send
54
+ its `trace_id` as `_meta["app.skillar/traceId"]`; ordinary vendor session metadata also preserves attribution.
55
+ No prior read or connection is required. A changed file fails closed until the catalog refreshes; the host
56
+ refreshes `skills/get` and verifies against the new manifest before use.
57
+
58
+ For Codex builds with gated modern support, enable `features.mcp_2026_07_28` for third-party HTTP servers;
59
+ the separate hosted Apps flag does not apply to skillar. Client-wide experimental flags are not edited by the pack.
60
+
61
+ **Privacy: everything stays on this machine.** The daemon listens on `127.0.0.1` only, every MCP, ingest, and API
62
+ request needs the local bearer token, and nothing is sent to any remote service. Prompts, search queries, and skill
63
+ usage are stored in a SQLite database under `~/.skillar/`.
64
+
65
+ ## Install
66
+
67
+ Requires Node.js 24.15 or newer on macOS or Linux.
68
+
69
+ ```sh
70
+ npm --prefix local ci && npm --prefix local run build && npm link ./local
71
+ ```
72
+
73
+ This puts the `skillar` command on your `PATH`.
74
+
75
+ ## Connect your agents
76
+
77
+ Preview what would change, without writing anything:
78
+
79
+ ```sh
80
+ skillar init --dry-run
81
+ ```
82
+
83
+ The dry run prints a diff for every runtime config skillar would touch (MCP registration, OpenTelemetry export to the
84
+ daemon, capture hooks) and the service it would install. Then apply it:
85
+
86
+ ```sh
87
+ skillar init # every detected runtime
88
+ skillar init --runtime codex,claude-code
89
+ skillar init --no-service # do not install the LaunchAgent / systemd user unit
90
+ ```
91
+
92
+ Every run backs up the files it changes under `~/.skillar/backups/`. Undo with:
93
+
94
+ ```sh
95
+ skillar init --rollback # newest run
96
+ skillar init --rollback --all # every run
97
+ ```
98
+
99
+ ## Run
100
+
101
+ `skillar init` installs a LaunchAgent (macOS) or systemd user unit (Linux) that keeps the daemon running. To run it in
102
+ the foreground instead:
103
+
104
+ ```sh
105
+ skillar serve # default port 8799
106
+ skillar serve --port 8800
107
+ ```
108
+
109
+ Open the dashboard (sessions, per-session trace, flow, and weekday-by-hour heatmap):
110
+
111
+ ```sh
112
+ skillar open # opens the browser
113
+ skillar open --print # prints the URL only
114
+ ```
115
+
116
+ Check the installation:
117
+
118
+ ```sh
119
+ skillar doctor # service, daemon, token mode, FTS5, roots, index freshness, hooks, backups
120
+ skillar doctor --json
121
+ ```
122
+
123
+ Measure search quality against recorded or hand-written cases:
124
+
125
+ ```sh
126
+ skillar eval
127
+ skillar eval --cases cases.json --json
128
+ ```
129
+
130
+ ## Skill tracing
131
+
132
+ herdr is required for skill tracing; `skillar doctor` checks its socket connection. skillar joins agent sessions
133
+ to panes and compares observed skill use with registered workflows without restricting agents.
134
+ See [Skill tracing](docs/skill-tracing.md) for capture details, attribution limits, and the orchestrator protocol.
135
+
136
+ ## Export and import
137
+
138
+ Move your skillar setup (skill roots, config, eval cases, aliases) to another machine:
139
+
140
+ ```sh
141
+ skillar export ~/skillar-backup # settings only
142
+ skillar export ~/skillar-backup --with-history # also sessions, events, and loads
143
+ skillar import ~/skillar-backup --dry-run # preview what would be added
144
+ skillar import ~/skillar-backup # merge; existing keys are kept
145
+ ```
146
+
147
+ Import never overwrites existing settings. Run `skillar init` afterwards to connect the runtimes on the new machine.
148
+
149
+ ## Settings
150
+
151
+ `~/.skillar/config.json` (created on first run, mode 0600; `SKILLAR_HOME` moves the whole directory):
152
+
153
+ ```json
154
+ {
155
+ "port": 8799,
156
+ "captureLevel": "full",
157
+ "retentionDays": null,
158
+ "roots": [{ "id": "agents", "path": "~/.agents/skills" }],
159
+ "runtimes": {}
160
+ }
161
+ ```
162
+
163
+ - `captureLevel` controls how prompt and search text is stored:
164
+ - `full` (default): the text as sent.
165
+ - `redacted`: secrets (tokens, keys, passwords) are masked and the text is cut to 2048 characters.
166
+ - `metadata`: no text at all, only its SHA-256 digest and length. The dashboard shows "prompt not captured".
167
+ - `retentionDays`: `null` keeps history forever; a number deletes sessions older than that many days at startup and
168
+ once a day.
169
+ - `roots`: skill folders to index in place. Defaults cover `~/.agents/skills`, `~/.claude/skills`, `~/.codex/skills`,
170
+ `~/.gemini/skills`, `~/.omo/agent/skills`, `~/.gjc/agent/skills`, `~/.openclaw/skills`, and `~/iyen-skills/skills`.
171
+ skillar never copies or edits skill files.
172
+
173
+ Restart the daemon after editing the config.
174
+
175
+ ## Files
176
+
177
+ | Path | Purpose |
178
+ | --- | --- |
179
+ | `~/.skillar/config.json` | settings above |
180
+ | `~/.skillar/token` | bearer token (0600) shared with the runtime configs |
181
+ | `~/.skillar/skillar.db` | SQLite store: skills index, sessions, events, loads |
182
+ | `~/.skillar/logs/daemon.log` | daemon log, rotated at 5 MB |
183
+ | `~/.skillar/backups/` | per-run backups used by `skillar init --rollback` |
184
+
185
+ ## Develop
186
+
187
+ ```sh
188
+ npm --prefix local run build
189
+ npm --prefix local run typecheck
190
+ npm --prefix local test # unit tests plus test/e2e, which spawns the real daemon in a sandbox HOME
191
+ node local/bench/search.mjs --check
192
+ node local/bench/mcp-mutations.mjs # each regression is injected in memory; files stay unchanged
193
+ ```
194
+
195
+ Architecture: [docs/skillar.md](../docs/skillar.md).
@@ -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
+ }