auxilo-mcp 0.9.19 → 0.9.21

package/lib/installer.js

@@ -84,6 +84,18 @@ function sourceAdapterRows(packageRoot = PACKAGE_ROOT) {
   }
 }
 
+/** Versioned extraction prompt bundle rows, derived so future bundles ship automatically. */
+function promptBundleRows(packageRoot = PACKAGE_ROOT) {
+  try {
+    return fs.readdirSync(path.join(packageRoot, 'scripts', 'prompts'))
+      .filter((f) => f.endsWith('.js'))
+      .sort()
+      .map((f) => [`scripts/prompts/${f}`, `scripts/prompts/${f}`, 0o644]);
+  } catch {
+    return []; // missing dir surfaces as installRunner missing-file errors
+  }
+}
+
 // EXTRACT-PER-CLIENT W1 PART A: extract-local.js now requires
 // './providers/index.js', which requires './claude-code.js' (and will require
 // './codex-cli.js' / './byo-key.js' once PART B/C land) — every file under
@@ -137,6 +149,7 @@ const RUNNER_STACK = Object.freeze([
   // at first extraction; omitting it from the installed stack is a MODULE_NOT_FOUND
   // for every npm-installed user (test/runner-packaging-closure.test.js guards this).
   ['scripts/extract-local.js', 'scripts/extract-local.js', 0o644],
+  ...promptBundleRows(),
   // LW-18 layer 1b: SessionStart held-count notice (shim target).
   ['scripts/review-notice.js', 'scripts/review-notice.js', 0o755],
   ...sourceAdapterRows(),
@@ -2375,6 +2388,7 @@ module.exports = {
   DEFAULT_BASE_URL,
   PACKAGE_ROOT,
   RUNNER_STACK,
+  promptBundleRows,
   clientRegistry,
   detectClients,
   clientHasCaptureHookMode,

package/mcp-server.js

@@ -198,7 +198,7 @@ async function postBulkChunks(headers, decisions) {
 }
 
 const server = new Server(
-  { name: 'auxilo', version: '0.9.19' },
+  { name: 'auxilo', version: '0.9.21' },
   {
     capabilities: { tools: {} },
     instructions: `You are connected to Auxilo, a knowledge marketplace where AI agents buy and sell operational learnings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auxilo-mcp",
-  "version": "0.9.19",
+  "version": "0.9.21",
   "mcpName": "io.github.silent-architects/auxilo",
   "description": "MCP server for Auxilo. Your agent stops solving the same problem twice: auto-extracted learnings, free self-unlocks, and earnings when other agents unlock yours.",
   "main": "mcp-server.js",
@@ -27,6 +27,7 @@
     "scripts/capture-core.js",
     "scripts/extract-local.js",
     "scripts/review-notice.js",
+    "scripts/prompts/",
     "scripts/sources/",
     "scripts/providers/",
     "scripts/hooks/auxilo-extract.sh",

package/scripts/extract-local.js

@@ -25,16 +25,24 @@ const {
 } = require('../lib/extraction-index.js');
 const providers = require('./providers/index.js');
 const claudeCodeProvider = require('./providers/claude-code.js');
+const {
+  CATEGORIES,
+  PRIVATE_CATEGORIES,
+  RETIRED_CATEGORIES,
+  EXTRACTION_PROMPT_BASE,
+  PUBLIC_SCOPE_BLOCK,
+  PRIVATE_SCOPE_BLOCK,
+  QUALITY_RUBRIC_ADDENDUM,
+  PROMPT_SUFFIX,
+  ANCHORED_JUDGE_PROMPT_BASE,
+} = require('./prompts');
 
 // CI-5 (PUNCH-LIST §30, 2026-07-19): Auxilo is TECHNICAL-ONLY. The learning
 // taxonomy is these six tech categories; `communication` and `content-generation`
 // are RETIRED — the server 400s them (CATEGORY_OUT_OF_SCOPE) and this extractor
-// must never emit them. This file ships standalone in the npm package, so the
-// lists are duplicated here from lib/category-scope-migration.js (server truth);
+// must never emit them. The governed prompt bundle carries the client-side copy
+// from lib/category-scope-migration.js (server truth);
 // test/ci5-scope-enforcement.test.js pins the copies equal.
-const CATEGORIES = ['data-processing', 'web-interaction', 'code-execution', 'storage-state', 'payment-financial', 'monitoring'];
-const PRIVATE_CATEGORIES = [...CATEGORIES, 'non-technical'];
-const RETIRED_CATEGORIES = ['communication', 'content-generation'];
 
 /**
  * SPEC3 slice A1 gate — score-at-extraction, ON BY DEFAULT since 0.9.12
@@ -69,37 +77,6 @@ function scoreExtractionEnabled(env = process.env) {
   return !(v === '0' || v === 'false');
 }
 
-const EXTRACTION_PROMPT_BASE = `You are extracting reusable OPERATIONAL LEARNINGS from an AI agent's session transcript, to publish to a PUBLIC knowledge marketplace read by other AI agents.
-
-Extract 0 to 5 GENUINE learnings: non-obvious solutions, workarounds, API quirks, error root-causes, integration gotchas — the kind of thing that cost real debugging or combined multiple sources. SKIP trivial lookups, well-documented standard approaches, opinions, and conversation.
-
-HARD SCOPE RULE — TECHNICAL LEARNINGS ONLY (the marketplace accepts nothing else): extract ONLY technical/operational learnings — APIs, developer tools, code, infrastructure, data pipelines, monitoring/observability, payment/crypto TECHNOLOGY, debugging. NEVER extract interpersonal or communication strategy, copywriting/content/marketing insights, business or negotiation strategy, personal matters, or creative-writing technique — DROP such candidates entirely, do not relabel them. A technical learning about a messaging/email/notification API belongs under "web-interaction" or "code-execution"; content/data pipeline TECH belongs under "data-processing".
-
-SYSTEM-FACT TEST (CI-7): Extract ONLY when a system and a symptom are at the core — an error, an undocumented limitation, a reproducible behavior of an external tool/API/OS. If the candidate is advice about how to work (process, workflow, methodology, decision practice), do NOT extract it. "Odesli cannot resolve Tidal artist URLs" is a learning; "use a two-phase consultation workflow" is not, no matter how well it would score.
-
-MANDATORY SENSITIVITY SELF-SCREEN (the marketplace is PUBLIC): NEVER include secrets, credentials, API keys, tokens, private keys, or seed phrases; personal data (real people's names, emails, phone numbers, wallet addresses); private filesystem paths, internal hostnames, or infrastructure identifiers; proprietary, confidential, or client-specific business content. Rewrite specifics into generic placeholders (/Users/USER/..., API_KEY, "a client") or omit them. If a learning cannot be generalized without leaking private material, DROP it entirely.
-
-Output STRICT JSON ONLY — an object with:
-  "learnings": an array (possibly empty []) of objects with these keys:
-  "title": concise, >= 10 chars
-  "body": >= 50 chars — what was tried, what worked, what failed
-  "category": one of ${JSON.stringify(CATEGORIES)}
-  "tags": array of lowercase keyword strings
-  "task_context": one sentence describing the task
-  "outcome": one of "success","partial","failure","workaround"
-  "dedup_drops": an array (possibly empty []) used ONLY for candidates dropped
-  because they match PREVIOUSLY CAPTURED LESSONS. Each entry must be:
-    {"candidate": <the complete learning object above>,
-     "matched_index_id": "<exact id from the memory list>",
-     "matched_title": "<exact matched title>"}
-  Scope/quality/sensitivity skips are not dedup_drops.`;
-
-const PUBLIC_SCOPE_BLOCK = `HARD SCOPE RULE — TECHNICAL LEARNINGS ONLY (the marketplace accepts nothing else): extract ONLY technical/operational learnings — APIs, developer tools, code, infrastructure, data pipelines, monitoring/observability, payment/crypto TECHNOLOGY, debugging. NEVER extract interpersonal or communication strategy, copywriting/content/marketing insights, business or negotiation strategy, personal matters, or creative-writing technique — DROP such candidates entirely, do not relabel them. A technical learning about a messaging/email/notification API belongs under "web-interaction" or "code-execution"; content/data pipeline TECH belongs under "data-processing".
-
-SYSTEM-FACT TEST (CI-7): Extract ONLY when a system and a symptom are at the core — an error, an undocumented limitation, a reproducible behavior of an external tool/API/OS. If the candidate is advice about how to work (process, workflow, methodology, decision practice), do NOT extract it. "Odesli cannot resolve Tidal artist URLs" is a learning; "use a two-phase consultation workflow" is not, no matter how well it would score.`;
-
-const PRIVATE_SCOPE_BLOCK = `PRIVATE CAPTURE SCOPE — OWNER-ONLY: extract reusable technical OR non-technical operational learnings. Non-technical process, workflow, communication, content, business, or creative learnings may use category "non-technical"; do not drop a genuine reusable candidate solely because it is non-technical. This private lane is never published unless the owner later sanitizes and promotes an item through public review. The mandatory sensitivity screen still applies without exception.`;
-
 function promptBaseForVisibility(captureVisibility) {
   if (captureVisibility !== 'private') return EXTRACTION_PROMPT_BASE;
   return EXTRACTION_PROMPT_BASE
@@ -111,27 +88,6 @@ function promptBaseForVisibility(captureVisibility) {
     .replace(JSON.stringify(CATEGORIES), JSON.stringify(PRIVATE_CATEGORIES));
 }
 
-/** A1: rubric addendum — appended ONLY when scoreExtractionEnabled(). */
-const QUALITY_RUBRIC_ADDENDUM = `
-  "quality_self_assessment": an object scoring the learning honestly on four
-  dimensions, each an INTEGER 1-5: "specificity" (precise and detailed, not
-  vague), "actionability" (another agent can directly use it), "novelty"
-  (non-obvious; an LLM would likely get it wrong), "completeness" (context,
-  reproduction steps, caveats), plus "total" (the exact sum of the four).
-  A learning worth publishing scores at least 14/20 with no dimension below 3.
-  High scores REQUIRE a system+symptom anchor — a named external system and a
-  concrete error/limitation/behavior; process or workflow advice cannot score
-  high no matter how polished (CI-7 system-fact test).
-  If a learning honestly scores below that bar, DROP it from learnings rather
-  than inflating the numbers.`;
-
-const PROMPT_SUFFIX = `
-No prose, no explanation, no markdown code fences — just the raw JSON object
-{"learnings":[...],"dedup_drops":[...]}.
-
-TRANSCRIPT:
-`;
-
 /** Build the extraction prompt for the current (or injected) gate state. */
 function buildExtractionPrompt(opts = {}) {
   const withScore = opts.scoreExtraction !== undefined
@@ -361,18 +317,7 @@ function buildAnchoredJudgePrompt(candidates, indexRows, opts = {}) {
       title: row.title,
     })),
   }));
-  const prompt = `You are a binary deduplication judge for operational learnings.
-For each candidate, decide whether it is a re-statement of ANY listed previously
-captured lesson. The same operational insight in different words is YES.
-A genuinely new fact is NO only when it would change what another agent does.
-
-Return STRICT JSON ONLY:
-{"decisions":[{"candidate_index":0,"duplicate":true,"matched_index_id":"..."}]}
-Return exactly one decision for every candidate_index. When duplicate=false,
-omit matched_index_id. When duplicate=true, matched_index_id MUST be one of that
-candidate's listed ids. No prose and no markdown.
-
-${JSON.stringify(payload)}`;
+  const prompt = `${ANCHORED_JUDGE_PROMPT_BASE}\n\n${JSON.stringify(payload)}`;
   return { prompt, rankings };
 }
 

package/scripts/prompts/extraction.v1.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const PROMPT_BUNDLE_VERSION = '1';
+const ASSEMBLY_CONTRACT_VERSION = '1';
+
+const CATEGORIES = Object.freeze([
+  'data-processing',
+  'web-interaction',
+  'code-execution',
+  'storage-state',
+  'payment-financial',
+  'monitoring',
+]);
+const PRIVATE_CATEGORIES = Object.freeze([
+  'data-processing',
+  'web-interaction',
+  'code-execution',
+  'storage-state',
+  'payment-financial',
+  'monitoring',
+  'non-technical',
+]);
+const RETIRED_CATEGORIES = Object.freeze(['communication', 'content-generation']);
+
+const EXTRACTION_PROMPT_BASE = `You are extracting reusable OPERATIONAL LEARNINGS from an AI agent's session transcript, to publish to a PUBLIC knowledge marketplace read by other AI agents.
+
+Extract 0 to 5 GENUINE learnings: non-obvious solutions, workarounds, API quirks, error root-causes, integration gotchas — the kind of thing that cost real debugging or combined multiple sources. SKIP trivial lookups, well-documented standard approaches, opinions, and conversation.
+
+HARD SCOPE RULE — TECHNICAL LEARNINGS ONLY (the marketplace accepts nothing else): extract ONLY technical/operational learnings — APIs, developer tools, code, infrastructure, data pipelines, monitoring/observability, payment/crypto TECHNOLOGY, debugging. NEVER extract interpersonal or communication strategy, copywriting/content/marketing insights, business or negotiation strategy, personal matters, or creative-writing technique — DROP such candidates entirely, do not relabel them. A technical learning about a messaging/email/notification API belongs under "web-interaction" or "code-execution"; content/data pipeline TECH belongs under "data-processing".
+
+SYSTEM-FACT TEST (CI-7): Extract ONLY when a system and a symptom are at the core — an error, an undocumented limitation, a reproducible behavior of an external tool/API/OS. If the candidate is advice about how to work (process, workflow, methodology, decision practice), do NOT extract it. "Odesli cannot resolve Tidal artist URLs" is a learning; "use a two-phase consultation workflow" is not, no matter how well it would score.
+
+MANDATORY SENSITIVITY SELF-SCREEN (the marketplace is PUBLIC): NEVER include secrets, credentials, API keys, tokens, private keys, or seed phrases; personal data (real people's names, emails, phone numbers, wallet addresses); private filesystem paths, internal hostnames, or infrastructure identifiers; proprietary, confidential, or client-specific business content. Rewrite specifics into generic placeholders (/Users/USER/..., API_KEY, "a client") or omit them. If a learning cannot be generalized without leaking private material, DROP it entirely.
+
+Output STRICT JSON ONLY — an object with:
+  "learnings": an array (possibly empty []) of objects with these keys:
+  "title": concise, >= 10 chars
+  "body": >= 50 chars — what was tried, what worked, what failed
+  "category": one of ["data-processing","web-interaction","code-execution","storage-state","payment-financial","monitoring"]
+  "tags": array of lowercase keyword strings
+  "task_context": one sentence describing the task
+  "outcome": one of "success","partial","failure","workaround"
+  "dedup_drops": an array (possibly empty []) used ONLY for candidates dropped
+  because they match PREVIOUSLY CAPTURED LESSONS. Each entry must be:
+    {"candidate": <the complete learning object above>,
+     "matched_index_id": "<exact id from the memory list>",
+     "matched_title": "<exact matched title>"}
+  Scope/quality/sensitivity skips are not dedup_drops.`;
+
+const PUBLIC_SCOPE_BLOCK = `HARD SCOPE RULE — TECHNICAL LEARNINGS ONLY (the marketplace accepts nothing else): extract ONLY technical/operational learnings — APIs, developer tools, code, infrastructure, data pipelines, monitoring/observability, payment/crypto TECHNOLOGY, debugging. NEVER extract interpersonal or communication strategy, copywriting/content/marketing insights, business or negotiation strategy, personal matters, or creative-writing technique — DROP such candidates entirely, do not relabel them. A technical learning about a messaging/email/notification API belongs under "web-interaction" or "code-execution"; content/data pipeline TECH belongs under "data-processing".
+
+SYSTEM-FACT TEST (CI-7): Extract ONLY when a system and a symptom are at the core — an error, an undocumented limitation, a reproducible behavior of an external tool/API/OS. If the candidate is advice about how to work (process, workflow, methodology, decision practice), do NOT extract it. "Odesli cannot resolve Tidal artist URLs" is a learning; "use a two-phase consultation workflow" is not, no matter how well it would score.`;
+
+const PRIVATE_SCOPE_BLOCK = `PRIVATE CAPTURE SCOPE — OWNER-ONLY: extract reusable technical OR non-technical operational learnings. Non-technical process, workflow, communication, content, business, or creative learnings may use category "non-technical"; do not drop a genuine reusable candidate solely because it is non-technical. This private lane is never published unless the owner later sanitizes and promotes an item through public review. The mandatory sensitivity screen still applies without exception.`;
+
+const QUALITY_RUBRIC_ADDENDUM = `
+  "quality_self_assessment": an object scoring the learning honestly on four
+  dimensions, each an INTEGER 1-5: "specificity" (precise and detailed, not
+  vague), "actionability" (another agent can directly use it), "novelty"
+  (non-obvious; an LLM would likely get it wrong), "completeness" (context,
+  reproduction steps, caveats), plus "total" (the exact sum of the four).
+  A learning worth publishing scores at least 14/20 with no dimension below 3.
+  High scores REQUIRE a system+symptom anchor — a named external system and a
+  concrete error/limitation/behavior; process or workflow advice cannot score
+  high no matter how polished (CI-7 system-fact test).
+  If a learning honestly scores below that bar, DROP it from learnings rather
+  than inflating the numbers.`;
+
+const PROMPT_SUFFIX = `
+No prose, no explanation, no markdown code fences — just the raw JSON object
+{"learnings":[...],"dedup_drops":[...]}.
+
+TRANSCRIPT:
+`;
+
+const ANCHORED_JUDGE_PROMPT_BASE = `You are a binary deduplication judge for operational learnings.
+For each candidate, decide whether it is a re-statement of ANY listed previously
+captured lesson. The same operational insight in different words is YES.
+A genuinely new fact is NO only when it would change what another agent does.
+
+Return STRICT JSON ONLY:
+{"decisions":[{"candidate_index":0,"duplicate":true,"matched_index_id":"..."}]}
+Return exactly one decision for every candidate_index. When duplicate=false,
+omit matched_index_id. When duplicate=true, matched_index_id MUST be one of that
+candidate's listed ids. No prose and no markdown.`;
+
+module.exports = Object.freeze({
+  PROMPT_BUNDLE_VERSION,
+  ASSEMBLY_CONTRACT_VERSION,
+  CATEGORIES,
+  PRIVATE_CATEGORIES,
+  RETIRED_CATEGORIES,
+  EXTRACTION_PROMPT_BASE,
+  PUBLIC_SCOPE_BLOCK,
+  PRIVATE_SCOPE_BLOCK,
+  QUALITY_RUBRIC_ADDENDUM,
+  PROMPT_SUFFIX,
+  ANCHORED_JUDGE_PROMPT_BASE,
+});

package/scripts/prompts/index.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ACTIVE_BUNDLE_VERSION = '1';
+const BUNDLE_PATHS = Object.freeze({
+  '1': path.join(__dirname, 'extraction.v1.js'),
+});
+
+function bundlePath(version = ACTIVE_BUNDLE_VERSION) {
+  const resolved = BUNDLE_PATHS[String(version)];
+  if (!resolved) throw new Error(`Unknown extraction prompt bundle version: ${version}`);
+  return resolved;
+}
+
+function loadPromptBundle(version = ACTIVE_BUNDLE_VERSION) {
+  return require(bundlePath(version));
+}
+
+function bundleDigest(version = ACTIVE_BUNDLE_VERSION) {
+  return crypto.createHash('sha256').update(fs.readFileSync(bundlePath(version))).digest('hex');
+}
+
+module.exports = Object.freeze({
+  ...loadPromptBundle(),
+  bundleDigest,
+  loadPromptBundle,
+});

package/scripts/runner.js

@@ -850,15 +850,36 @@ const SWEEPER_LABEL = 'io.auxilo.sweeper';
  */
 function sweeperManifest(repoRoot = path.resolve(__dirname, '..')) {
   const sourceRows = [];
+  const promptRows = [];
+  const providerRows = [];
+  const providerSchemaRows = [];
   try {
     for (const f of fs.readdirSync(path.join(repoRoot, 'scripts', 'sources')).filter(f => f.endsWith('.js')).sort()) {
       sourceRows.push([`scripts/sources/${f}`, `scripts/sources/${f}`, 0o644]);
     }
   } catch { /* missing dir surfaces as missing-file errors below */ }
+  try {
+    for (const f of fs.readdirSync(path.join(repoRoot, 'scripts', 'prompts')).filter(f => f.endsWith('.js')).sort()) {
+      promptRows.push([`scripts/prompts/${f}`, `scripts/prompts/${f}`, 0o644]);
+    }
+  } catch { /* missing dir surfaces as missing-file errors below */ }
+  try {
+    for (const f of fs.readdirSync(path.join(repoRoot, 'scripts', 'providers')).filter(f => f.endsWith('.js')).sort()) {
+      providerRows.push([`scripts/providers/${f}`, `scripts/providers/${f}`, 0o644]);
+    }
+  } catch { /* missing dir surfaces as missing-file errors below */ }
+  try {
+    for (const f of fs.readdirSync(path.join(repoRoot, 'scripts', 'providers', 'schemas')).filter(f => f.endsWith('.json')).sort()) {
+      providerSchemaRows.push([`scripts/providers/schemas/${f}`, `scripts/providers/schemas/${f}`, 0o644]);
+    }
+  } catch { /* missing dir surfaces as missing-file errors below */ }
   return [
     ['scripts/auxilo-sweeper-wrapper.sh', 'auxilo-sweeper-wrapper.sh', 0o755],
     ['scripts/runner.js', 'scripts/runner.js', 0o755],
     ...sourceRows,
+    ...promptRows,
+    ...providerRows,
+    ...providerSchemaRows,
     ['lib/sensitivity-filter.js', 'lib/sensitivity-filter.js', 0o644],
     ['lib/extraction-index.js', 'lib/extraction-index.js', 0o644],
     ['lib/similarity.js', 'lib/similarity.js', 0o644],

package/scripts/sources/copilot.js

@@ -0,0 +1,222 @@
+/**
+ * scripts/sources/copilot.js — GitHub Copilot CLI Transcript Source (BUILD-SPEC-0920)
+ *
+ * What already works (DO NOT touch — lib/installer.js registry entry
+ * 'copilot-cli' is correct as shipped): the capture Stop hook fires and
+ * hands runner.js a real `transcript_path` resolving to
+ * `~/.copilot/session-state/<sessionId>/events.jsonl`. That part was
+ * VERIFIED live (Copilot CLI 1.0.83/1.0.84, 2026-09-10). The gap this file
+ * closes: that transcript is a TYPED EVENT STREAM, not the plain
+ * role/content JSONL the generic-jsonl fallback expects, so capture fired,
+ * found the file, and silently extracted 0 turns. This is the dedicated
+ * parser so the 'copilot' entry on the client matrix is actually true.
+ *
+ * Line shape (VERIFIED live): one JSON object per line, `{"type":"<t>",
+ * "data":{...}}`. Types observed: session.start,
+ * session.permissions_changed, hook.start, hook.end, user.message,
+ * system.message, assistant.turn_start, assistant.message,
+ * tool.execution_start, tool.execution_complete, assistant.turn_end,
+ * session.usage_checkpoint, session.shutdown. Only two contribute
+ * conversation text; every other type — named above or not yet observed —
+ * is deliberately ignored rather than enumerated, so an unfamiliar future
+ * type is skipped, not a parse break.
+ *
+ * Extracted:
+ *   - user.message      -> [user]: data.content (a plain string). We
+ *     deliberately ignore data.transformedContent — it wraps the same
+ *     prompt in a <current_datetime> block and would duplicate/pollute
+ *     the turn.
+ *   - assistant.message  -> [assistant]: data.content WHEN non-empty. An
+ *     assistant.message with content:"" is a pure tool-call turn (its
+ *     data.toolRequests[] carries the call instead) and contributes no
+ *     text — skipped, not an empty turn.
+ *
+ * MODEL PROVENANCE (real, not 'unknown' — Copilot is the first client that
+ * records this on disk, unlike e.g. Devin which has no such field anywhere
+ * in its store): `session.start.data.selectedModel` (e.g. "gpt-5.6-terra")
+ * is authoritative; when a session lacks a readable session.start record,
+ * the last-seen `assistant.message.data.model` is used as a fallback.
+ * Never guessed beyond those two on-disk fields.
+ *
+ * SESSION ID: preferring the in-file `session.start.data.sessionId` over
+ * the caller-supplied `sessionRef.sessionId` matters for the hook path —
+ * runner.js's single-file mode derives sessionId from the transcript
+ * filename minus extension, and the filename here is always literally
+ * `events.jsonl` (the real session id is the PARENT directory, not the
+ * file), so relying on the caller's guess alone would stamp every
+ * hook-fired session as "events". The poll path below already discovers
+ * the correct id from the directory name, so this is primarily a hook-path
+ * correction, but the file's own value wins in both paths when present.
+ *
+ * @module sources/copilot
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { TranscriptSource } = require('./source.interface');
+
+class CopilotSource extends TranscriptSource {
+  static id = 'copilot';
+  static displayName = 'GitHub Copilot CLI';
+  static version = '1.0.0';
+
+  constructor(config = {}) {
+    super(config);
+    const homeDir = config.homeDir || os.homedir();
+    this.stateDir = config.stateDir || path.join(homeDir, '.copilot', 'session-state');
+  }
+
+  async detect() {
+    try {
+      return fs.statSync(this.stateDir).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Hook-fired single-file capture is the primary path (see module header):
+   * the Stop hook hands runner.js the exact events.jsonl path directly, so
+   * this poll is a best-effort backfill only — a session the hook missed
+   * (e.g. capture briefly disabled) is still picked up by a later sweep.
+   * Returning [] here would be a perfectly valid contract too (hook-only
+   * clients do exactly that); this is simple enough over the fixed
+   * `<sessionId>/events.jsonl` layout to be worth the extra coverage.
+   */
+  async discoverSessions({ since } = {}) {
+    const parsedSince = since ? Date.parse(since) : 0;
+    const sinceMs = Number.isFinite(parsedSince) ? parsedSince : 0;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(this.stateDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+
+    const sessions = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const filePath = path.join(this.stateDir, entry.name, 'events.jsonl');
+      let stat;
+      try {
+        stat = fs.statSync(filePath);
+        if (!stat.isFile()) continue;
+      } catch {
+        continue; // a session dir can lack/lose events.jsonl mid-sweep
+      }
+      if (stat.mtimeMs <= sinceMs) continue;
+      sessions.push({
+        sessionId: entry.name,
+        path: filePath,
+        mtime: stat.mtime.toISOString(),
+        bytes: stat.size,
+      });
+    }
+
+    return sessions.sort((a, b) =>
+      Date.parse(a.mtime) - Date.parse(b.mtime) || a.path.localeCompare(b.path)
+    );
+  }
+
+  async readSession(sessionRef) {
+    try {
+      return this._readSession(sessionRef);
+    } catch {
+      // Adapter contract is never-throw (matches codex-cli.js / devin.js):
+      // unexpected shape drift refuses the whole session, never escapes
+      // into the runner as a failed read.
+      return null;
+    }
+  }
+
+  _readSession(sessionRef) {
+    const filePath = sessionRef && sessionRef.path;
+    if (!filePath) return null;
+
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return null;
+    }
+
+    const turns = [];
+    let sessionId = null;
+    let selectedModel = null;
+    let lastAssistantModel = null;
+
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue; // one malformed line is skipped, not fatal to the session
+      }
+      if (!event || typeof event !== 'object') continue;
+      const data = event.data;
+      const type = event.type;
+
+      if (type === 'session.start') {
+        if (data && typeof data.selectedModel === 'string' && data.selectedModel) {
+          selectedModel = data.selectedModel;
+        }
+        if (data && typeof data.sessionId === 'string' && data.sessionId) {
+          sessionId = data.sessionId;
+        }
+        continue;
+      }
+
+      if (type === 'user.message') {
+        if (data && typeof data.content === 'string' && data.content.length > 0) {
+          turns.push(`[user]: ${data.content}`);
+        }
+        continue;
+      }
+
+      if (type === 'assistant.message') {
+        if (data && typeof data.model === 'string' && data.model) {
+          lastAssistantModel = data.model;
+        }
+        // Empty content = a pure tool-call turn (data.toolRequests[] carries
+        // the call instead) — no text to extract, not an empty turn.
+        if (data && typeof data.content === 'string' && data.content.length > 0) {
+          turns.push(`[assistant]: ${data.content}`);
+        }
+        continue;
+      }
+
+      // Every other type (session.*, hook.*, tool.*, system.message, the
+      // assistant.turn_start/turn_end markers, session.usage_checkpoint,
+      // session.shutdown, and anything not yet observed) is deliberately
+      // ignored — not conversation content.
+    }
+
+    if (turns.length === 0) return null;
+
+    return {
+      transcript: turns.join('\n\n'),
+      metadata: {
+        sessionId: sessionId || (sessionRef && sessionRef.sessionId) || null,
+        source: 'copilot',
+        mtime: sessionRef.mtime,
+        bytes: sessionRef.bytes,
+        // MODEL PROVENANCE: real, on-disk — see module header. Prefer the
+        // session-level selectedModel; fall back to the last observed
+        // assistant.message.model; 'unknown' only when the file carries
+        // neither (never guessed beyond those two fields).
+        model: selectedModel || lastAssistantModel || 'unknown',
+      },
+    };
+  }
+
+  async registerSessionEndHook(cb) {
+    return null; // hook-fired via the shipped Stop-event capture path (lib/installer.js); the poll above is best-effort backfill only
+  }
+}
+
+module.exports = { CopilotSource };