@ghl-ai/aw 0.1.93 → 0.2.0

package/hooks/aw-usage/hooks/aw-usage-telemetry-send.js

@@ -5,12 +5,18 @@
  *
  * Spawned by sendAsync() in aw-usage-telemetry.js with { detached: true }.
  * This script runs independently after the parent hook process exits.
+ *
+ * B7: an event that fails (network error, timeout, HTTP 5xx) goes to the
+ * local queue (~/.aw/telemetry/queue/, lib/aw-usage-queue.js). After the next
+ * successful POST, queued events are resent oldest first with their original
+ * event_id, so the server's unique index drops any duplicate.
  */
 
 'use strict';
 
 const https = require('https');
 const http = require('http');
+const queue = require('../lib/aw-usage-queue');
 
 const DEFAULT_URL = 'https://services.leadconnectorhq.com/agentic-workspace/api/telemetry/usage-events';
 const TIMEOUT_MS = 10_000;
@@ -49,6 +55,59 @@ function post(url, body) {
   });
 }
 
+// Network error, timeout, 5xx, or the server asking to come back later.
+function isRetryable(status) {
+  return status === null || status === 408 || status === 429 || status >= 500;
+}
+
+async function tryPost(post, body) {
+  try {
+    return await post(body);
+  } catch (err) {
+    // Network error or timeout: one stderr line, no event content.
+    process.stderr.write(`[aw-telemetry] send failed: ${err.message}\n`);
+    return null;
+  }
+}
+
+// One file at a time, so a claim is never older than one POST and another
+// sender cannot release it as stale mid-drain.
+async function drainQueue(post, queueDir) {
+  for (let sent = 0; sent < queue.MAX_DRAIN_PER_RUN; sent++) {
+    const [claimed] = queue.claimBatch({ dir: queueDir, limit: 1 });
+    if (!claimed) return;
+    const queuedEvent = queue.readClaimedEvent(claimed);
+    // A corrupt file can never be sent: drop it.
+    const status = queuedEvent ? await tryPost(post, JSON.stringify(queuedEvent)) : 200;
+    const failed = isRetryable(status);
+    queue.settle(claimed, !failed);
+    if (failed) return;
+  }
+}
+
+/**
+ * POST one event; queue it when it fails, drain the queue when it succeeds.
+ * @param {{ event: object, body?: string, post: (body: string) => Promise<number>, queueDir?: string }} opts
+ */
+async function sendWithQueue({ event, body = JSON.stringify(event), post, queueDir = queue.QUEUE_DIR }) {
+  const status = await tryPost(post, body);
+  if (isRetryable(status)) {
+    // v1 senders have no event_id; enqueue refuses those.
+    queue.enqueue(event, { dir: queueDir });
+    return;
+  }
+  if (status >= 200 && status < 300) await drainQueue(post, queueDir);
+}
+
+function parseEvent(eventJson) {
+  try {
+    return JSON.parse(eventJson);
+  } catch {
+    // Not JSON: still POSTed as given (server answers 400), never queued.
+    return null;
+  }
+}
+
 async function main() {
   const eventJson = process.argv[2];
   if (!eventJson) {
@@ -71,14 +130,15 @@ async function main() {
     ? `${baseUrl.replace(/\/+$/, '')}/telemetry/usage-events`
     : DEFAULT_URL;
 
-  try {
-    await post(url, eventJson);
-  } catch (err) {
-    // Non-blocking — log and exit cleanly.
-    process.stderr.write(`[aw-telemetry] send failed: ${err.message}\n`);
-  }
+  await sendWithQueue({ event: parseEvent(eventJson), body: eventJson, post: (body) => post(url, body) });
 
   process.exit(0);
 }
 
-main();
+if (require.main === module) {
+  // Detached process: a failure here must not leave a non-zero exit behind; the event
+  // is lost exactly as it was before the queue existed.
+  main().catch(() => process.exit(0));
+}
+
+module.exports = { sendWithQueue };

package/hooks/aw-usage/lib/aw-usage-commands.js

@@ -0,0 +1,122 @@
+/**
+ * AW Usage Telemetry — typed command recognition (B2).
+ *
+ *   extractTypedCommands(input) — every command the user typed in one prompt,
+ *                                 as { raw_name, command_form, namespace }
+ *   commandKey(name)            — the command with its form removed (`plan`)
+ *   isSdlcStageCommand(command) — v1 is_sdlc_stage rule on the stripped name
+ *
+ * Only the command name and how it was typed leave the laptop, never the rest
+ * of the prompt (spec decision 6). The server maps raw names to the catalog.
+ *
+ * | Form                         | Typed             | raw_name           | command_form |
+ * |------------------------------|-------------------|--------------------|--------------|
+ * | namespaced slash (v1, start) | /aw:plan, /tdd    | aw:plan, tdd       | slash_ns     |
+ * | Cursor slash / menu pick     | /aw-plan          | /aw-plan           | slash        |
+ * | Cursor command folder        | /aw/plan          | aw:plan            | slash        |
+ * | Codex dollar                 | $aw-plan          | $aw-plan           | dollar       |
+ * | Codex prompts (older Codex)  | /prompts:aw-plan  | /prompts:aw-plan   | prompts      |
+ * | Cursor @ pick                | @aw-plan          | aw-plan            | attach       |
+ *
+ * Only the namespaced form must open the prompt; the others count anywhere
+ * after the start or whitespace, outside fenced code blocks, with a name of
+ * at most 40 characters.
+ */
+
+'use strict';
+
+const NAMESPACED_PREFIXES = ['aw', 'caveman', 'codex', 'graphify', 'rtk', 'lean-ctx'];
+const BARE_SLASH_COMMANDS = new Set([
+  'tdd', 'diagnose', 'grill-me', 'grill-with-docs', 'triage', 'to-prd', 'zoom-out',
+]);
+// `/aw:` sub-commands that count as SDLC stages so the funnel can group by stage.
+const AW_SDLC_STAGES = new Set([
+  'plan', 'build', 'execute', 'test', 'verify', 'review',
+  'deploy', 'ship', 'tdd', 'investigate', 'feature',
+]);
+
+const NAMESPACED_AT_START = new RegExp(`^\\/((?:${NAMESPACED_PREFIXES.join('|')})(?::[a-z0-9-]+)?)(?=\\s|$)`, 'i');
+const BARE_AT_START = /^\/([a-z][a-z0-9-]*)(?=\s|$)/i;
+// A longer "name" is pasted text, not a command; it is never sent.
+const MAX_NAME_LENGTH = 40;
+const FENCED_CODE = /```[\s\S]*?(?:```|$)/g;
+const ANYWHERE_FORMS = [
+  { pattern: /(?<=^|\s)\/aw-([a-z0-9-]+)\b/gi, form: 'slash', rawName: name => `/aw-${name}` },
+  { pattern: /(?<=^|\s)\/aw\/([a-z0-9-]+)\b/gi, form: 'slash', rawName: name => `aw:${name}` },
+  { pattern: /(?<=^|\s)\$aw-([a-z0-9-]+)\b/gi, form: 'dollar', rawName: name => `$aw-${name}` },
+  { pattern: /(?<=^|\s)\/prompts:aw-([a-z0-9-]+)\b/gi, form: 'prompts', rawName: name => `/prompts:aw-${name}` },
+  { pattern: /(?<=^|\s)@aw-([a-z0-9-]+)\b/gi, form: 'attach', rawName: name => `aw-${name}` },
+];
+
+function promptText(input) {
+  if (typeof input === 'string') return input;
+  for (const candidate of [input?.prompt, input?.user_prompt, input?.message, input?.text]) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate;
+  }
+  return '';
+}
+
+function commandKey(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/^[/$]/, '')
+    .replace(/^prompts:/, '')
+    .replace(/^aw:/, '')
+    .replace(/^aw-/, '');
+}
+
+function namespacedAtStart(prompt) {
+  const match = prompt.match(NAMESPACED_AT_START);
+  if (match) {
+    const rawName = match[1].toLowerCase();
+    const colon = rawName.indexOf(':');
+    return { raw_name: rawName, command_form: 'slash_ns', namespace: colon > 0 ? rawName.slice(0, colon) : null };
+  }
+  const bare = prompt.match(BARE_AT_START);
+  if (bare && BARE_SLASH_COMMANDS.has(bare[1].toLowerCase())) {
+    return { raw_name: bare[1].toLowerCase(), command_form: 'slash_ns', namespace: null };
+  }
+  return null;
+}
+
+function anywhereMatches(prompt) {
+  const found = [];
+  for (const { pattern, form, rawName } of ANYWHERE_FORMS) {
+    for (const match of prompt.matchAll(pattern)) {
+      if (match[1].length > MAX_NAME_LENGTH) continue;
+      found.push({ index: match.index, command: { raw_name: rawName(match[1].toLowerCase()), command_form: form, namespace: 'aw' } });
+    }
+  }
+  return found.sort((a, b) => a.index - b.index).map(entry => entry.command);
+}
+
+function extractTypedCommands(input) {
+  // Commands inside fenced code blocks are quoted, not typed.
+  const prompt = promptText(input).replace(FENCED_CODE, ' ').trim();
+  if (!prompt) return [];
+
+  const first = namespacedAtStart(prompt);
+  const commands = first ? [first] : [];
+  const seen = new Set(commands.map(command => command.raw_name));
+  const startKey = first ? commandKey(first.raw_name) : null;
+
+  for (const command of anywhereMatches(prompt)) {
+    if (seen.has(command.raw_name)) continue;
+    // `/aw:plan … $aw-plan` is one command typed twice.
+    if (startKey && commandKey(command.raw_name) === startKey) continue;
+    seen.add(command.raw_name);
+    commands.push(command);
+  }
+  return commands;
+}
+
+function isSdlcStageCommand(command) {
+  return command?.namespace === 'aw' && AW_SDLC_STAGES.has(commandKey(command.raw_name));
+}
+
+module.exports = {
+  AW_SDLC_STAGES,
+  extractTypedCommands,
+  commandKey,
+  isSdlcStageCommand,
+};

package/hooks/aw-usage/lib/aw-usage-envelope.js

@@ -0,0 +1,121 @@
+/**
+ * AW Usage Telemetry — v2 event envelope helpers.
+ *
+ *   newEventId()                      — UUID v4; the server dedupes resends on it
+ *   readHookVersion(pkgPath)          — `version` stamped by the aw CLI into ~/.aw/aw-usage/package.json
+ *   nextSeq(sessionId, { sessionsDir }) — 1, 2, 3 … per session, or null when it cannot be taken safely
+ *   withFileLock(lockPath, fn)        — run fn while holding a lock folder; shared by seq,
+ *                                       stage history and the session activity index
+ *
+ * Telemetry is best-effort: when a lock or a file cannot be used, the helpers
+ * return null / { ok: false } and the event is still sent without the field.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+
+const DEFAULT_PKG_PATH = path.join(__dirname, '..', 'package.json');
+const SESSION_DIR = path.join(os.homedir(), '.aw', 'telemetry', 'sessions');
+const SAFE_FILE_NAME = /^[A-Za-z0-9._-]{1,200}$/;
+const SEQ_LOCK_WAIT_MS = 200;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+
+function newEventId() {
+  return crypto.randomUUID();
+}
+
+function readHookVersion(pkgPath = DEFAULT_PKG_PATH) {
+  try {
+    const version = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version;
+    return typeof version === 'string' && version ? version : null;
+  } catch {
+    // No stamped package.json (running from the repo, or an old install): omit hook_version.
+    return null;
+  }
+}
+
+function sleepSync(ms) {
+  Atomics.wait(sleepCell, 0, 0, ms);
+}
+
+// Only one waiter can rename the stale lock away, so two waiters never both
+// remove it (and one of them a lock the other just took).
+function removeStaleLock(lockPath, staleMs) {
+  try {
+    if (Date.now() - fs.statSync(lockPath).mtimeMs <= staleMs) return;
+    const doomed = `${lockPath}.stale-${process.pid}-${crypto.randomUUID()}`;
+    fs.renameSync(lockPath, doomed);
+    fs.rmSync(doomed, { recursive: true, force: true });
+  } catch {
+    // Lock vanished or another waiter took it over; the next mkdir decides.
+  }
+}
+
+function withFileLock(lockPath, fn, { waitMs = 50, staleMs = 5000 } = {}) {
+  const deadline = Date.now() + waitMs;
+  let acquired = false;
+  while (!acquired) {
+    try {
+      fs.mkdirSync(lockPath);
+      acquired = true;
+    } catch (error) {
+      if (error.code !== 'EEXIST') return { ok: false };
+      removeStaleLock(lockPath, staleMs);
+      if (Date.now() >= deadline) return { ok: false };
+      sleepSync(5);
+    }
+  }
+  try {
+    return { ok: true, value: fn() };
+  } finally {
+    // fn is a few small file operations, far below staleMs, so the lock is still ours.
+    fs.rmSync(lockPath, { recursive: true, force: true });
+  }
+}
+
+function sessionFileName(sessionId) {
+  return SAFE_FILE_NAME.test(sessionId) && !/^\.+$/.test(sessionId)
+    ? sessionId
+    : crypto.createHash('sha256').update(sessionId).digest('hex').slice(0, 32);
+}
+
+function readCounter(seqPath) {
+  try {
+    const value = Number.parseInt(fs.readFileSync(seqPath, 'utf8'), 10);
+    return Number.isInteger(value) && value > 0 ? value : 0;
+  } catch {
+    // First event of the session: no counter file yet.
+    return 0;
+  }
+}
+
+function nextSeq(sessionId, { sessionsDir = SESSION_DIR } = {}) {
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  const seqPath = path.join(sessionsDir, `${sessionFileName(sessionId)}.seq`);
+  try {
+    fs.mkdirSync(sessionsDir, { recursive: true, mode: 0o700 });
+    // Cursor runs several hooks at once for one tool call; wait as long as
+    // the session and stage locks do, so seq is not dropped under that load.
+    const result = withFileLock(`${seqPath}.lock`, () => {
+      const seq = readCounter(seqPath) + 1;
+      fs.writeFileSync(seqPath, String(seq), { mode: 0o600 });
+      return seq;
+    }, { waitMs: SEQ_LOCK_WAIT_MS });
+    return result.ok ? result.value : null;
+  } catch {
+    // Telemetry folder not writable: the event is sent without seq.
+    return null;
+  }
+}
+
+module.exports = {
+  newEventId,
+  readHookVersion,
+  nextSeq,
+  withFileLock,
+  sessionFileName,
+};

package/hooks/aw-usage/lib/aw-usage-queue.js

@@ -0,0 +1,168 @@
+/**
+ * AW Usage Telemetry — local resend queue (B7).
+ *
+ * The sender puts an event here when the POST fails (network error, timeout,
+ * HTTP 5xx) and drains the folder after the next successful POST. Each event
+ * is one file `<enqueued-at-ms>-<event_id>.json`, so concurrent detached
+ * senders never corrupt each other and no lock is needed: a sender claims a
+ * file by renaming it to `.sending`, and only one rename can win.
+ *
+ * Queued events hold the same fields the sender already has (including
+ * github_email / account_email), so the folder is 0700 and files are 0600.
+ * Bounded: at most MAX_QUEUED files and MAX_AGE_MS old; oldest dropped first.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const QUEUE_DIR = path.join(os.homedir(), '.aw', 'telemetry', 'queue');
+const MAX_QUEUED = 500;
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_DRAIN_PER_RUN = 50;
+const CLAIM_STALE_MS = 60 * 1000;
+const EVENT_ID = /^[A-Za-z0-9-]{1,64}$/;
+const QUEUED = '.json';
+const CLAIMED = '.sending';
+
+function listQueue(dir) {
+  try {
+    return fs.readdirSync(dir).filter(name => name.endsWith(QUEUED) || name.endsWith(CLAIMED)).sort();
+  } catch {
+    // No queue folder yet: nothing queued.
+    return [];
+  }
+}
+
+function enqueuedAt(name) {
+  const value = Number.parseInt(name, 10);
+  return Number.isFinite(value) ? value : 0;
+}
+
+function removeQuietly(filePath) {
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+    // Already removed by another sender or by trim.
+  }
+}
+
+function trim({ dir = QUEUE_DIR, now = Date.now(), maxQueued = MAX_QUEUED, maxAgeMs = MAX_AGE_MS } = {}) {
+  const kept = [];
+  for (const name of listQueue(dir)) {
+    if (now - enqueuedAt(name) > maxAgeMs) removeQuietly(path.join(dir, name));
+    else kept.push(name);
+  }
+  for (const name of kept.slice(0, Math.max(0, kept.length - maxQueued))) {
+    removeQuietly(path.join(dir, name));
+  }
+}
+
+// The folder holds PII, so it must be a real folder owned by this user, not a link.
+function ensureQueueDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(dir);
+  if (!stat.isDirectory() || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) {
+    throw new Error('queue folder is not a directory owned by this user');
+  }
+  fs.chmodSync(dir, 0o700);
+}
+
+/** Queue one event for a later resend. Returns false when it was not queued. */
+function enqueue(event, { dir = QUEUE_DIR, now = Date.now(), maxQueued = MAX_QUEUED, maxAgeMs = MAX_AGE_MS } = {}) {
+  const eventId = event && typeof event === 'object' ? event.event_id : null;
+  if (typeof eventId !== 'string' || !EVENT_ID.test(eventId)) return false;
+  try {
+    ensureQueueDir(dir);
+    fs.writeFileSync(path.join(dir, `${now}-${eventId}${QUEUED}`), JSON.stringify(event), { mode: 0o600, flag: 'wx' });
+  } catch {
+    // Queue folder unusable (not writable, a link, another owner): the event is dropped,
+    // as it was before the queue existed.
+    return false;
+  }
+  trim({ dir, now, maxQueued, maxAgeMs });
+  return true;
+}
+
+function claimFile(dir, name, now) {
+  const from = path.join(dir, name);
+  const to = path.join(dir, name.slice(0, -QUEUED.length) + CLAIMED);
+  try {
+    fs.renameSync(from, to);
+  } catch {
+    // Another sender claimed it first.
+    return null;
+  }
+  try {
+    const claimedAt = new Date(now);
+    fs.utimesSync(to, claimedAt, claimedAt);
+  } catch {
+    // Claim keeps its old mtime: another sender may release it early; the server dedupes on event_id.
+  }
+  return to;
+}
+
+function releaseStaleClaim(dir, name, now) {
+  const from = path.join(dir, name);
+  try {
+    if (now - fs.statSync(from).mtimeMs <= CLAIM_STALE_MS) return null;
+    const to = path.join(dir, name.slice(0, -CLAIMED.length) + QUEUED);
+    fs.renameSync(from, to);
+    return path.basename(to);
+  } catch {
+    // Settled or reclaimed by another sender meanwhile.
+    return null;
+  }
+}
+
+/** Claim up to `limit` queued events, oldest first. Returns the claimed file paths. */
+function claimBatch({ dir = QUEUE_DIR, limit = MAX_DRAIN_PER_RUN, now = Date.now() } = {}) {
+  // Expired events are never resent, even when no new failure ran trim().
+  trim({ dir, now });
+  const claimed = [];
+  for (const name of listQueue(dir)) {
+    if (claimed.length >= limit) break;
+    // A sender that died mid-drain leaves `.sending` files behind; release them after a minute.
+    const queuedName = name.endsWith(CLAIMED) ? releaseStaleClaim(dir, name, now) : name;
+    if (!queuedName) continue;
+    const claimedPath = claimFile(dir, queuedName, now);
+    if (claimedPath) claimed.push(claimedPath);
+  }
+  return claimed;
+}
+
+function readClaimedEvent(claimedPath) {
+  try {
+    return JSON.parse(fs.readFileSync(claimedPath, 'utf8'));
+  } catch {
+    // Corrupt or vanished file: the caller settles it as sent so it is not retried forever.
+    return null;
+  }
+}
+
+/** ok: the event reached the server, delete it. Not ok: put it back for a later run. */
+function settle(claimedPath, ok) {
+  if (ok) {
+    removeQuietly(claimedPath);
+    return;
+  }
+  try {
+    fs.renameSync(claimedPath, claimedPath.slice(0, -CLAIMED.length) + QUEUED);
+  } catch {
+    // Removed by trim meanwhile: nothing to put back.
+  }
+}
+
+module.exports = {
+  QUEUE_DIR,
+  MAX_QUEUED,
+  MAX_AGE_MS,
+  MAX_DRAIN_PER_RUN,
+  enqueue,
+  trim,
+  claimBatch,
+  settle,
+  readClaimedEvent,
+};

package/hooks/aw-usage/lib/aw-usage-skill-source.js

@@ -0,0 +1,138 @@
+/**
+ * AW Usage Telemetry — how a skill was reached and where its file came from (B1, B6).
+ *
+ *   skillOrigin({ name } | { path })      — 'aw' | 'other' | null (P11)
+ *   skillSourceFields(source, input, skill) — payload fields for a skill_invoked event
+ *   shellSkillReads(command)              — every SKILL.md a shell command reads
+ *   cursorProbeSkillReads(tool, toolInput) — B6 probe: a SKILL.md path given to a tool
+ *                                           this hook does not know
+ *
+ * skill_origin rule (P11):
+ * - Skill tool: `aw` for `aw:<x>`, `other` for any other namespace, omitted for a bare name.
+ * - File or shell read: `aw` when the SKILL.md is under ~/.aw-ecc/, ~/.aw/,
+ *   ~/.claude/plugins/cache/aw-marketplace/, or is a destinationPath in
+ *   ~/.cursor/ecc-install-state.json or ~/.codex/ecc-install-state.json
+ *   (those folders mix AW and other skills; the install state lists what AW
+ *   copied). Otherwise `other`. No skill list lives in the hook (spec decision 1).
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const MAX_STATE_BYTES = 2 * 1024 * 1024;
+const INSTALL_STATE_FILES = [['.cursor', 'ecc-install-state.json'], ['.codex', 'ecc-install-state.json']];
+const AW_ROOTS = [['.aw-ecc'], ['.aw'], ['.claude', 'plugins', 'cache', 'aw-marketplace']];
+// B6 probe skips tools whose skill reads are already counted, and search tools:
+// Cursor Greps for `**/<name>/SKILL.md` before reading it, which is not a load.
+const PROBE_SKIPPED_TOOLS = new Set(['Read', 'Bash', 'Shell', 'Skill', 'Grep', 'Glob']);
+const SKILL_FILE = /(?<=^|[\s'"`;|&<>()=])((?:[^\s'"`;|&<>()]*\/)?skills\/([A-Za-z0-9._:-]+)\/SKILL\.md)(?![\w.-])/g;
+
+const listedCache = new Map();
+
+function toForwardSlashes(value) {
+  return String(value).replace(/\\/g, '/');
+}
+
+function expandHome(filePath, home) {
+  const match = filePath.match(/^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/);
+  return match ? path.join(home, filePath.slice(match[0].length)) : filePath;
+}
+
+function readInstallState(statePath) {
+  try {
+    if (fs.statSync(statePath).size > MAX_STATE_BYTES) return [];
+    const operations = JSON.parse(fs.readFileSync(statePath, 'utf8'))?.operations;
+    return Array.isArray(operations) ? operations.map(op => op?.destinationPath).filter(p => typeof p === 'string') : [];
+  } catch {
+    // Missing, too big or not JSON: nothing is listed, so the skill counts as `other`.
+    return [];
+  }
+}
+
+// Install-state files are read once per process.
+function listedSkillPaths(home) {
+  if (!listedCache.has(home)) {
+    const listed = new Set();
+    for (const segments of INSTALL_STATE_FILES) {
+      for (const destination of readInstallState(path.join(home, ...segments))) {
+        if (/\/SKILL\.md$/i.test(toForwardSlashes(destination))) listed.add(toForwardSlashes(path.normalize(destination)));
+      }
+    }
+    listedCache.set(home, listed);
+  }
+  return listedCache.get(home);
+}
+
+function originFromPath(filePath, home) {
+  const absolute = toForwardSlashes(path.normalize(expandHome(filePath, home)));
+  const underAwRoot = AW_ROOTS.some(segments => absolute.startsWith(`${toForwardSlashes(path.join(home, ...segments))}/`));
+  return underAwRoot || listedSkillPaths(home).has(absolute) ? 'aw' : 'other';
+}
+
+function originFromName(name) {
+  const colon = String(name).indexOf(':');
+  if (colon <= 0) return null;
+  return name.slice(0, colon).toLowerCase() === 'aw' ? 'aw' : 'other';
+}
+
+/** @param {{ name?: string, path?: string }} skill */
+function skillOrigin(skill, { home = os.homedir() } = {}) {
+  if (typeof skill?.path === 'string' && skill.path) return originFromPath(skill.path, home);
+  if (typeof skill?.name === 'string' && skill.name) return originFromName(skill.name);
+  return null;
+}
+
+/**
+ * @param {'skill_tool'|'file_read'|'shell_read'|'other_tool'} source
+ * @param {object} input hook input
+ * @param {{ name?: string, path?: string }} skill
+ */
+function skillSourceFields(source, input, skill, opts = {}) {
+  const origin = skillOrigin(skill, opts);
+  return {
+    source,
+    tool_name: input?.tool_name || 'unknown',
+    ...(typeof input?.tool_use_id === 'string' && input.tool_use_id ? { tool_use_id: input.tool_use_id } : {}),
+    ...(origin ? { skill_origin: origin } : {}),
+  };
+}
+
+/** Every distinct skill whose SKILL.md appears in the text, first-seen order. */
+function shellSkillReads(text) {
+  const reads = [];
+  const seen = new Set();
+  for (const match of toForwardSlashes(text || '').matchAll(SKILL_FILE)) {
+    if (seen.has(match[2])) continue;
+    seen.add(match[2]);
+    reads.push({ name: match[2], path: match[1] });
+  }
+  return reads;
+}
+
+function shellSkillNames(command) {
+  return shellSkillReads(command).map(read => read.name);
+}
+
+function stringsToDepth(value, depth) {
+  if (typeof value === 'string') return [value];
+  if (depth === 0 || !value || typeof value !== 'object') return [];
+  return Object.values(value).flatMap(child => stringsToDepth(child, depth - 1));
+}
+
+// B6 probe: remove in the release after the one that ships it
+// (https://app.clickup.com/t/14zhcp5e0b5).
+function cursorProbeSkillReads(toolName, toolInput) {
+  if (!toolName || PROBE_SKIPPED_TOOLS.has(toolName)) return [];
+  return shellSkillReads(stringsToDepth(toolInput, 2).join('\n'));
+}
+
+module.exports = {
+  skillOrigin,
+  skillSourceFields,
+  shellSkillReads,
+  shellSkillNames,
+  cursorProbeSkillReads,
+};