skillfid 0.1.0

package/src/cli.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+import { buildDataset, loadDataset, recalibrateDataset } from './dataset.js';
+import { evaluateBaseline, evaluateDataset } from './evaluation.js';
+import { OperationJournal } from './journal.js';
+import { createProgressReporter } from './progress.js';
+import { generateEvaluationReport } from './report.js';
+
+const VERSION = '0.6.0';
+let activeProgressReporter;
+
+const HELP = `skillfid: evaluate how faithfully agent skills apply their source documentation
+
+Examples:
+  skillfid dataset build --corpus ./corpus --json
+  skillfid dataset recalibrate --dataset ./datasets/ds_abc123 --json
+  skillfid dataset verify --dataset ./datasets/ds_abc123 --json
+  skillfid eval baseline --dataset ./datasets/ds_abc123 --json
+  skillfid eval run --dataset ./datasets/ds_abc123 --skill ./skill --json
+  skillfid eval report --run ./runs/run_abc123 --dataset ./datasets/ds_abc123
+  skillfid operation status --work-dir .work/eval --json
+
+Usage:
+  skillfid [--json] [--quiet] dataset build --corpus <dir> [options]
+  skillfid [--json] [--quiet] dataset recalibrate --dataset <dir> [options]
+  skillfid [--json] [--quiet] dataset verify --dataset <dir>
+  skillfid [--json] [--quiet] eval baseline --dataset <dir> [options]
+  skillfid [--json] [--quiet] eval run --dataset <dir> --skill <dir> [options]
+  skillfid [--json] [--quiet] eval report --run <dir> --dataset <dir> [options]
+  skillfid [global-options] operation status --work-dir <dir> [--operation-id <id>]
+
+Global options:
+  --json                    Print a stable JSON object to stdout
+  --quiet                   Suppress progress on stderr
+  --agent                   Bounded agent progress (alias: --progress agent)
+  --progress <mode>         auto, human, agent, json, or quiet (default: auto)
+  --progress-interval <sec> Agent snapshot interval (default: 30)
+  -h, --help                Show help; valid after any command
+  --version                 Print the version
+
+Build options:
+  --corpus <dir>            Markdown corpus directory (required)
+  --output-dir <dir>        Dataset output directory (default: datasets)
+  --work-dir <dir>          Isolated working directory (default: .work/dataset)
+  --model <name>            Copilot model (default: gpt-5.6-sol)
+  --judge-model <name>      Oracle calibration judge (default: --model)
+  --reasoning-effort <name> Reasoning effort (default: medium)
+  --timeout <seconds>       Per-Copilot-call timeout (default: 600)
+  --timeout-retries <count> Retries after a session timeout (default: 1)
+  --max-attempts <count>    Attempts to repair malformed JSON (default: 3)
+  --clean-residual-passes <count> Consecutive clean inventory passes (default: 1)
+  --max-residual-passes <count>   Maximum inventory/audit passes (default: 3)
+  --concurrency <count>     Parallel Copilot calls (default: 10; no maximum)
+  --resume                  Reuse matching work from a prior attempt (default)
+  --fresh                   Start from scratch without deleting prior state
+
+Recalibration options:
+  --dataset <dir>           Published schema v6 dataset directory (required)
+  --output-dir <dir>        Dataset output directory (default: datasets)
+  --work-dir <dir>          Isolated working directory (default: .work/recalibrate)
+  --model <name>            Oracle model (default: source dataset)
+  --judge-model <name>      Calibration judge (default: source dataset)
+  --reasoning-effort <name> Reasoning effort (default: source dataset)
+  --timeout <seconds>       Per-Copilot-call timeout (default: 600)
+  --timeout-retries <count> Retries after a session timeout (default: 1)
+  --max-attempts <count>    Attempts to repair malformed JSON (default: 3)
+  --concurrency <count>     Parallel Copilot calls (default: 10; no maximum)
+  --resume                  Reuse matching work from a prior attempt (default)
+  --fresh                   Start from scratch without deleting prior state
+
+Baseline options:
+  --dataset <dir>           Published schema v6 dataset directory (required)
+  --output-dir <dir>        Baseline output directory (default: baselines)
+  --work-dir <dir>          Isolated working directory (default: .work/baseline)
+  --model <name>            Subject model (default: dataset calibration)
+  --judge-model <name>      Judge model (default: dataset calibration)
+  --reasoning-effort <name> Reasoning effort (default: dataset calibration)
+  --trials <count>          Trials per question (default: 3)
+  --timeout <seconds>       Per-Copilot-call timeout (default: 600)
+  --timeout-retries <count> Retries after a session timeout (default: 1)
+  --concurrency <count>     Parallel Copilot calls (default: 10; no maximum)
+  --resume                  Reuse matching work from a prior attempt (default)
+  --fresh                   Start from scratch without deleting prior state
+
+Evaluation options:
+  --dataset <dir>           Published schema v6 dataset directory (required)
+  --skill <dir>             Skill directory containing SKILL.md (required)
+  --baseline-dir <dir>      Reusable baseline directory (default: baselines)
+  --output-dir <dir>        Run output directory (default: runs)
+  --work-dir <dir>          Isolated working directory (default: .work/eval)
+  --model <name>            Subject model (default: dataset calibration)
+  --judge-model <name>      Judge model (default: dataset calibration)
+  --reasoning-effort <name> Reasoning effort (default: dataset calibration)
+  --skill-invocation <mode> Skill invocation: auto or explicit (default: auto)
+  --trials <count>          Trials per question and condition (default: 3)
+  --timeout <seconds>       Per-Copilot-call timeout (default: 600)
+  --timeout-retries <count> Retries after a session timeout (default: 1)
+  --concurrency <count>     Parallel Copilot calls (default: 10; no maximum)
+  --resume                  Reuse matching work from a prior attempt (default)
+  --fresh                   Start from scratch without deleting prior state
+
+Report options:
+  --run <dir>               Completed evaluation run directory (required)
+  --dataset <dir>           Dataset used by the evaluation run (required)
+  -o, --output <file>       HTML output file (default: <run>/report.html)
+  --title <text>            Report title (default: Skill evaluation)
+
+Prerequisites:
+  Node.js 24+ and GitHub Copilot CLI authenticated for Copilot access.
+
+JSON success schemas:
+  dataset build:  {"datasetPath":string,"status":"created"}
+  dataset recalibrate: {"datasetPath":string,"sourceDatasetId":string,"status":"created"}
+  dataset verify: {"datasetId":string,"evidenceRecords":number,"questions":number,"valid":true}
+  eval baseline:  {"baselinePath":string,"status":"completed"}
+  eval run:       {"runPath":string,"status":"completed"}
+  eval report:    {"reportPath":string,"status":"created"}
+  operation status: {"journalPath":string,"operations":[...]}
+
+I/O contract:
+  Primary output goes to stdout. Progress and errors go to stderr.
+
+Exit codes:
+  0  Success
+  1  Runtime, validation, authentication, or Copilot failure
+  2  Invalid command or option
+  130 Interrupted by Ctrl-C
+`;
+
+const commonOptions = {
+  json: { type: 'boolean', default: false },
+  quiet: { type: 'boolean', default: false },
+  help: { type: 'boolean', short: 'h', default: false },
+  version: { type: 'boolean', default: false },
+};
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.includes('--version')) { process.stdout.write(`${VERSION}\n`); return; }
+  if (!argv.length || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') { process.stdout.write(HELP); return; }
+  const globals = extractGlobals(argv);
+  const progressReporter = createProgressReporter({ mode: globals.progressMode, intervalSeconds: globals.progressInterval });
+  activeProgressReporter = progressReporter;
+  const progress = (message) => progressReporter.report(message);
+  try {
+    return await runCommand(globals, progress);
+  } finally {
+    progressReporter.close();
+    if (activeProgressReporter === progressReporter) activeProgressReporter = undefined;
+  }
+}
+
+async function runCommand(globals, progress) {
+  const [group, command, ...commandArgs] = globals.args;
+  if (group === 'dataset' && command === 'build') {
+    const values = options(commandArgs, { corpus: { type: 'string' }, 'output-dir': stringOption('datasets'), 'work-dir': stringOption('.work/dataset'), model: stringOption('gpt-5.6-sol'), 'judge-model': { type: 'string' }, 'reasoning-effort': stringOption('medium'), timeout: stringOption('600'), 'timeout-retries': stringOption('1'), 'max-attempts': stringOption('3'), 'clean-residual-passes': stringOption('1'), 'max-residual-passes': stringOption('3'), concurrency: stringOption('10'), resume: { type: 'boolean' }, fresh: { type: 'boolean', default: false } });
+    required(values, 'corpus', 'dataset build');
+    const datasetPath = await buildDataset({ corpusPath: values.corpus, outputRoot: values['output-dir'], workRoot: values['work-dir'], options: { model: values.model, judgeModel: values['judge-model'] ?? values.model, reasoningEffort: values['reasoning-effort'], timeoutSeconds: positiveNumber(values.timeout, '--timeout'), timeoutRetries: nonNegativeInteger(values['timeout-retries'], '--timeout-retries'), maxAttempts: positiveInteger(values['max-attempts'], '--max-attempts'), cleanResidualPasses: positiveInteger(values['clean-residual-passes'], '--clean-residual-passes'), maxResidualPasses: positiveInteger(values['max-residual-passes'], '--max-residual-passes'), concurrency: positiveInteger(values.concurrency, '--concurrency'), resume: resolveResume(values) }, progress });
+    output({ datasetPath, status: 'created' }, globals.json, `Output: ${displayPath(datasetPath)}`);
+    return;
+  }
+  if (group === 'dataset' && command === 'recalibrate') {
+    const values = options(commandArgs, { dataset: { type: 'string' }, 'output-dir': stringOption('datasets'), 'work-dir': stringOption('.work/recalibrate'), model: { type: 'string' }, 'judge-model': { type: 'string' }, 'reasoning-effort': { type: 'string' }, timeout: stringOption('600'), 'timeout-retries': stringOption('1'), 'max-attempts': stringOption('3'), concurrency: stringOption('10'), resume: { type: 'boolean' }, fresh: { type: 'boolean', default: false } });
+    required(values, 'dataset', 'dataset recalibrate');
+    const source = await loadDataset(values.dataset);
+    const datasetPath = await recalibrateDataset({ datasetPath: values.dataset, outputRoot: values['output-dir'], workRoot: values['work-dir'], options: { model: values.model, judgeModel: values['judge-model'] ?? values.model, reasoningEffort: values['reasoning-effort'], timeoutSeconds: positiveNumber(values.timeout, '--timeout'), timeoutRetries: nonNegativeInteger(values['timeout-retries'], '--timeout-retries'), maxAttempts: positiveInteger(values['max-attempts'], '--max-attempts'), concurrency: positiveInteger(values.concurrency, '--concurrency'), resume: resolveResume(values) }, progress });
+    output({ datasetPath, sourceDatasetId: source.datasetId, status: 'created' }, globals.json, `Output: ${displayPath(datasetPath)}`);
+    return;
+  }
+  if (group === 'dataset' && command === 'verify') {
+    const values = options(commandArgs, { dataset: { type: 'string' } });
+    required(values, 'dataset', 'dataset verify');
+    progress({ type: 'start', workflow: 'verification', title: 'Verifying dataset', current: 'Reading manifest', progress: { done: 0, total: 7, label: 'integrity checks passed' } });
+    const dataset = await loadDataset(values.dataset, { progress: ({ done, total, current }) => progress({ type: 'update', workflow: 'verification', current, progress: { done, total, label: 'integrity checks passed' } }) });
+    progress({ type: 'complete', workflow: 'verification', title: 'Dataset verified', summary: [`${dataset.questions.length} question${dataset.questions.length === 1 ? '' : 's'}, ${dataset.evidence.length} evidence record${dataset.evidence.length === 1 ? '' : 's'}`] });
+    output({ datasetId: dataset.datasetId, evidenceRecords: dataset.evidence.length, questions: dataset.questions.length, valid: true }, globals.json, `Dataset is valid\n  Questions: ${dataset.questions.length}\n  Evidence records: ${dataset.evidence.length}`);
+    return;
+  }
+  if (group === 'operation' && command === 'status') {
+    const values = options(commandArgs, { 'work-dir': { type: 'string' }, 'operation-id': { type: 'string' } });
+    required(values, 'work-dir', 'operation status');
+    const journalPath = path.resolve(values['work-dir'], 'operations.sqlite');
+    progress({ type: 'start', workflow: 'status', title: 'Reading operation status', current: 'Opening operation journal', progress: { done: 0, total: 1, label: 'journals read' } });
+    try { await access(journalPath); }
+    catch { throw new Error(`Operation journal not found: ${journalPath}`); }
+    const journal = await OperationJournal.open(journalPath, { readOnly: true });
+    try {
+      const operations = (values['operation-id'] ? [journal.getOperation(values['operation-id'])].filter(Boolean) : journal.listOperations()).map((operation) => {
+        const jobs = journal.listJobs(operation.operationId);
+        const lastActivityAt = Math.max(operation.updatedAt, ...jobs.map((job) => job.updatedAt));
+        const counts = journal.jobCounts(operation.operationId);
+        const expiredLeases = jobs.filter((job) => job.status === 'running' && job.leaseExpiresAt <= Date.now()).length;
+        const health = operation.status === 'running' && counts.running > 0 && expiredLeases === counts.running ? 'stalled' : operation.status;
+        return { ...operation, jobs: counts, lastActivityAt, health };
+      });
+      if (values['operation-id'] && !operations.length) throw new Error(`Operation not found: ${values['operation-id']}`);
+      progress({ type: 'complete', workflow: 'status', title: 'Operation status ready', summary: [`${operations.length} operation${operations.length === 1 ? '' : 's'} found`] });
+      output({ journalPath, operations }, globals.json, formatOperationStatus(operations));
+      return;
+    } finally { journal.close(); }
+  }
+  if (group === 'eval' && command === 'report') {
+    const values = options(commandArgs, { run: { type: 'string' }, dataset: { type: 'string' }, output: { type: 'string', short: 'o' }, title: stringOption('Skill evaluation') });
+    required(values, 'run', 'eval report'); required(values, 'dataset', 'eval report');
+    progress({ type: 'start', workflow: 'report', title: 'Generating report', current: 'Reading evaluation artifacts', progress: { done: 0, total: 1, label: 'reports generated' } });
+    const reportPath = await generateEvaluationReport({ runPath: values.run, datasetPath: values.dataset, outputPath: values.output, title: values.title });
+    progress({ type: 'complete', workflow: 'report', title: 'Report generated', summary: [displayPath(reportPath)] });
+    output({ reportPath, status: 'created' }, globals.json, `Output: ${displayPath(reportPath)}`);
+    return;
+  }
+  if (group === 'eval' && command === 'baseline') {
+    const values = options(commandArgs, { dataset: { type: 'string' }, 'output-dir': stringOption('baselines'), 'work-dir': stringOption('.work/baseline'), model: { type: 'string' }, 'judge-model': { type: 'string' }, 'reasoning-effort': { type: 'string' }, trials: stringOption('3'), timeout: stringOption('600'), 'timeout-retries': stringOption('1'), concurrency: stringOption('10'), resume: { type: 'boolean' }, fresh: { type: 'boolean', default: false } });
+    required(values, 'dataset', 'eval baseline');
+    const baselinePath = await evaluateBaseline({ datasetPath: values.dataset, outputRoot: values['output-dir'], workRoot: values['work-dir'], options: { model: values.model, judgeModel: values['judge-model'], reasoningEffort: values['reasoning-effort'], trialsPerQuestion: positiveInteger(values.trials, '--trials'), timeoutSeconds: positiveNumber(values.timeout, '--timeout'), timeoutRetries: nonNegativeInteger(values['timeout-retries'], '--timeout-retries'), concurrency: positiveInteger(values.concurrency, '--concurrency'), resume: resolveResume(values) }, progress });
+    output({ baselinePath, status: 'completed' }, globals.json, `Output: ${displayPath(baselinePath)}`);
+    return;
+  }
+  if (group === 'eval' && command === 'run') {
+    const values = options(commandArgs, { dataset: { type: 'string' }, skill: { type: 'string' }, 'baseline-dir': stringOption('baselines'), 'output-dir': stringOption('runs'), 'work-dir': stringOption('.work/eval'), model: { type: 'string' }, 'judge-model': { type: 'string' }, 'reasoning-effort': { type: 'string' }, 'skill-invocation': stringOption('auto'), trials: stringOption('3'), timeout: stringOption('600'), 'timeout-retries': stringOption('1'), concurrency: stringOption('10'), resume: { type: 'boolean' }, fresh: { type: 'boolean', default: false } });
+    required(values, 'dataset', 'eval run'); required(values, 'skill', 'eval run');
+    const runPath = await evaluateDataset({ datasetPath: values.dataset, skillPath: values.skill, baselineRoot: values['baseline-dir'], outputRoot: values['output-dir'], workRoot: values['work-dir'], options: { model: values.model, judgeModel: values['judge-model'], reasoningEffort: values['reasoning-effort'], skillInvocation: choice(values['skill-invocation'], '--skill-invocation', ['auto', 'explicit']), trialsPerQuestion: positiveInteger(values.trials, '--trials'), timeoutSeconds: positiveNumber(values.timeout, '--timeout'), timeoutRetries: nonNegativeInteger(values['timeout-retries'], '--timeout-retries'), concurrency: positiveInteger(values.concurrency, '--concurrency'), resume: resolveResume(values) }, progress });
+    output({ runPath, status: 'completed' }, globals.json, `Output: ${displayPath(runPath)}`);
+    return;
+  }
+  throw new UsageError(`Unknown command: ${[group, command].filter(Boolean).join(' ') || '(none)'}. Valid commands: dataset build, dataset recalibrate, dataset verify, eval baseline, eval run, eval report, operation status.`);
+}
+
+class UsageError extends Error { constructor(message) { super(message); this.exitCode = 2; } }
+
+function extractGlobals(argv) {
+  const args = [];
+  let json = false; let quiet = false; let agent = false; let progressMode; let progressInterval = 30;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') json = true;
+    else if (arg === '--quiet') quiet = true;
+    else if (arg === '--agent') agent = true;
+    else if (arg === '--progress' || arg === '--progress-interval') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) throw new UsageError(`Option ${arg} requires a value.`);
+      index += 1;
+      if (arg === '--progress') progressMode = value;
+      else progressInterval = positiveNumber(value, '--progress-interval');
+    }
+    else if (arg.startsWith('--progress=')) progressMode = arg.slice('--progress='.length);
+    else if (arg.startsWith('--progress-interval=')) progressInterval = positiveNumber(arg.slice('--progress-interval='.length), '--progress-interval');
+    else args.push(arg);
+  }
+  if (!['auto', 'human', 'agent', 'json', 'quiet'].includes(progressMode ?? 'auto')) throw new UsageError(`Invalid --progress value ${JSON.stringify(progressMode)}. Valid values: auto, human, agent, json, quiet.`);
+  if (quiet && progressMode && progressMode !== 'quiet') throw new UsageError('--quiet conflicts with a non-quiet --progress mode.');
+  if (agent && progressMode && progressMode !== 'agent') throw new UsageError('--agent conflicts with a non-agent --progress mode.');
+  return { args, json, progressMode: quiet ? 'quiet' : agent ? 'agent' : progressMode ?? 'auto', progressInterval };
+}
+
+function options(args, commandOptions) {
+  try { return parseArgs({ args, options: { ...commonOptions, ...commandOptions }, strict: true, allowPositionals: false }).values; }
+  catch (error) { throw new UsageError(`${error.message}. Run 'skillfid --help' for valid options.`); }
+}
+
+function stringOption(defaultValue) { return { type: 'string', default: defaultValue }; }
+function required(values, name, command) { if (!values[name]) throw new UsageError(`Missing required option --${name} for '${command}'.`); }
+function positiveInteger(value, name) { const number = Number(value); if (!Number.isInteger(number) || number < 1) throw new UsageError(`Invalid ${name} value ${JSON.stringify(value)}. Expected a positive integer.`); return number; }
+function nonNegativeInteger(value, name) { const number = Number(value); if (!Number.isInteger(number) || number < 0) throw new UsageError(`Invalid ${name} value ${JSON.stringify(value)}. Expected a non-negative integer.`); return number; }
+function positiveNumber(value, name) { const number = Number(value); if (!Number.isFinite(number) || number <= 0) throw new UsageError(`Invalid ${name} value ${JSON.stringify(value)}. Expected a positive number.`); return number; }
+function choice(value, name, validValues) { if (!validValues.includes(value)) throw new UsageError(`Invalid ${name} value ${JSON.stringify(value)}. Valid values: ${validValues.join(', ')}.`); return value; }
+function resolveResume(values) { if (values.resume && values.fresh) throw new UsageError('Options --resume and --fresh cannot be used together.'); return !values.fresh; }
+
+function output(value, json, plain = undefined) {
+  process.stdout.write(json ? `${JSON.stringify(value)}\n` : `${plain ?? JSON.stringify(value, null, 2)}\n`);
+}
+
+function displayPath(value) {
+  const relative = path.relative(process.cwd(), value);
+  return relative && !relative.startsWith('..') ? relative : value;
+}
+
+function formatOperationStatus(operations) {
+  if (!operations.length) return 'No operations found.';
+  return ['Operations', ...operations.map((operation) => {
+    const jobs = operation.jobs;
+    const total = jobs.pending + jobs.running + jobs.completed + jobs.failed;
+    const activity = operation.health === 'completed' ? `finished ${formatAge(operation.updatedAt)}` : `last activity ${formatAge(operation.lastActivityAt)}`;
+    return `  ${operation.kind}  ${operation.health}  ${jobs.completed}/${total} jobs complete${jobs.failed ? `, ${jobs.failed} failed` : ''} · ${activity}`;
+  })].join('\n');
+}
+
+function formatAge(timestamp) {
+  const seconds = Math.max(0, Math.round((Date.now() - timestamp) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  return `${hours}h ago`;
+}
+
+export function resumeCommand(argv) {
+  if (!isResumableCommand(argv)) return undefined;
+  const args = argv.filter((arg) => arg !== '--fresh' && !arg.startsWith('--fresh='));
+  if (!args.includes('--resume')) args.push('--resume');
+  return `npm start -- ${args.map(shellArgument).join(' ')}`;
+}
+
+export function interruptionMessage(argv) {
+  const command = resumeCommand(argv);
+  if (!command) return 'Interrupted.\n';
+  const title = argv.some((arg, index) => arg === 'dataset' && argv[index + 1] === 'recalibrate') ? 'Recalibration interrupted' : argv.some((arg, index) => arg === 'eval' && argv[index + 1] === 'baseline') ? 'Baseline interrupted' : argv.includes('dataset') ? 'Extraction interrupted' : 'Evaluation interrupted';
+  return `${title}\nAny completed work was saved.\n\nRun this command to continue:\n${command}\n`;
+}
+
+function isResumableCommand(argv) {
+  return argv.some((arg, index) => (arg === 'dataset' && ['build', 'recalibrate'].includes(argv[index + 1])) || (arg === 'eval' && ['baseline', 'run'].includes(argv[index + 1])));
+}
+
+function shellArgument(value) {
+  return /^[A-Za-z0-9_./:@=+-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  let interrupted = false;
+  process.once('SIGINT', () => { interrupted = true; activeProgressReporter?.close(); process.stderr.write(interruptionMessage(process.argv.slice(2))); process.exitCode = 130; });
+  main().catch((error) => {
+    if (interrupted) return;
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exitCode = error.exitCode ?? 1;
+  });
+}

package/src/concurrency.js

@@ -0,0 +1,77 @@
+export class AsyncLimiter {
+  constructor(limit = 10, onChange = undefined) {
+    if (!Number.isInteger(limit) || limit < 1) throw new Error('Concurrency must be a positive integer');
+    if (onChange !== undefined && typeof onChange !== 'function') throw new Error('onChange must be a function');
+    this.limit = limit;
+    this.onChange = onChange;
+    this.active = 0;
+    this.queue = [];
+    this.completed = 0;
+    this.failed = 0;
+  }
+
+  get stats() {
+    return { limit: this.limit, active: this.active, queued: this.queue.length, completed: this.completed, failed: this.failed };
+  }
+
+  run(task) {
+    if (typeof task !== 'function') throw new Error('Limited task must be a function');
+    return new Promise((resolve, reject) => {
+      this.queue.push({ task, resolve, reject });
+      this.#drain();
+      this.#notify();
+    });
+  }
+
+  #drain() {
+    while (this.active < this.limit && this.queue.length) {
+      const { task, resolve, reject } = this.queue.shift();
+      this.active += 1;
+      Promise.resolve().then(task).then((value) => {
+        this.completed += 1;
+        this.active -= 1;
+        this.#drain();
+        this.#notify();
+        resolve(value);
+      }, (error) => {
+        this.failed += 1;
+        this.active -= 1;
+        this.#drain();
+        this.#notify();
+        reject(error);
+      });
+    }
+  }
+
+  #notify() {
+    this.onChange?.(this.stats);
+  }
+}
+
+export async function mapConcurrent(items, limit, task) {
+  if (!Array.isArray(items)) throw new TypeError('Concurrent items must be an array');
+  if (!Number.isInteger(limit) || limit < 1) throw new Error('Concurrency must be a positive integer');
+  if (typeof task !== 'function') throw new TypeError('Concurrent task must be a function');
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  let failure;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (!failure && nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      try { results[index] = await task(items[index], index); }
+      catch (error) { failure ??= error; }
+    }
+  });
+  await Promise.all(workers);
+  if (failure) throw failure;
+  return results;
+}
+
+export function limitRunner(runner, limiter) {
+  return {
+    run: (...args) => limiter.run(() => runner.run(...args)),
+    listSkills: (...args) => limiter.run(() => runner.listSkills(...args)),
+    version: (...args) => limiter.run(() => runner.version(...args)),
+  };
+}

package/src/copilot-sdk.js

@@ -0,0 +1,137 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+import { approveAll, CopilotClient, RuntimeConnection } from '@github/copilot-sdk';
+
+export class CopilotSdkRunError extends Error {}
+
+export class CopilotSdkRunner {
+  constructor(config = {}, dependencies = {}) {
+    this.config = {
+      model: 'gpt-5.6-sol',
+      reasoningEffort: 'medium',
+      timeoutSeconds: 600,
+      maxTimeoutRetries: 1,
+      isolatedHome: undefined,
+      progress: undefined,
+      ...config,
+    };
+    this.createClient = dependencies.createClient ?? ((options) => new CopilotClient(options));
+    this.clientPromise = undefined;
+  }
+
+  async run(workspace, prompt) {
+    const startedAt = performance.now();
+    const client = await this.#client();
+    const skillDirectories = await projectSkillDirectories(workspace);
+    const invocation = explicitSkillInvocation(prompt, skillDirectories);
+    for (let attempt = 0; attempt <= this.config.maxTimeoutRetries; attempt += 1) {
+      const session = await client.createSession({
+        availableTools: ['builtin:*'],
+        excludedTools: ['shell', 'write', 'url'],
+        enableConfigDiscovery: false,
+        enableSessionStore: false,
+        enableSkills: skillDirectories.length > 0,
+        memory: { enabled: false },
+        model: this.config.model,
+        onPermissionRequest: approveAll,
+        reasoningEffort: this.config.reasoningEffort,
+        skillDirectories,
+        skipCustomInstructions: true,
+        workingDirectory: path.resolve(workspace),
+        ...(invocation ? {
+          agent: 'skillfid-explicit',
+          customAgents: [{ name: 'skillfid-explicit', prompt: 'Answer the user directly and follow the preloaded skill instructions.', skills: [invocation.name], tools: null }],
+        } : {}),
+      });
+      try {
+        const response = await session.sendAndWait({ prompt: invocation?.prompt ?? prompt }, this.config.timeoutSeconds * 1000);
+        const answer = response?.data.content?.trim();
+        if (!answer) throw new CopilotSdkRunError('Copilot SDK returned no assistant message');
+        return { answer, stderr: '', exitCode: 0, durationSeconds: (performance.now() - startedAt) / 1000 };
+      } catch (error) {
+        if (!isTimeout(error) || attempt === this.config.maxTimeoutRetries) throw new CopilotSdkRunError(error instanceof Error ? error.message : String(error), { cause: error });
+        this.config.progress?.({ type: 'retry', message: `Copilot timed out after ${this.config.timeoutSeconds} seconds; retrying (timeout retry ${attempt + 1}/${this.config.maxTimeoutRetries})`, details: { workspace: path.basename(workspace), attempt: attempt + 1, maxAttempts: this.config.maxTimeoutRetries } });
+      } finally {
+        await session.disconnect();
+      }
+    }
+    throw new CopilotSdkRunError('Copilot SDK timeout attempts exhausted');
+  }
+
+  async listSkills(workspace) {
+    const client = await this.#client();
+    const skillDirectories = await projectSkillDirectories(workspace);
+    const session = await client.createSession({
+      availableTools: [],
+      enableConfigDiscovery: false,
+      enableSessionStore: false,
+      enableSkills: skillDirectories.length > 0,
+      memory: { enabled: false },
+      onPermissionRequest: approveAll,
+      skillDirectories,
+      skipCustomInstructions: true,
+      workingDirectory: path.resolve(workspace),
+    });
+    try {
+      const result = await session.rpc.skills.list();
+      return result.skills.map((skill) => ({ ...skill, source: skillDirectories.includes(path.dirname(skill.path ?? '')) ? 'project' : skill.source }));
+    } finally {
+      await session.disconnect();
+    }
+  }
+
+  async version() {
+    const status = await (await this.#client()).getStatus();
+    return `GitHub Copilot CLI ${status.version}.`;
+  }
+
+  async close() {
+    if (!this.clientPromise) return;
+    let client;
+    try { client = await this.clientPromise; }
+    catch { this.clientPromise = undefined; return; }
+    this.clientPromise = undefined;
+    await client.forceStop();
+  }
+
+  async #client() {
+    this.clientPromise ??= this.#startClient();
+    return this.clientPromise;
+  }
+
+  async #startClient() {
+    const options = {
+      baseDirectory: this.config.isolatedHome ? path.resolve(this.config.isolatedHome) : undefined,
+      logLevel: 'error',
+    };
+    if (this.config.executable) options.connection = RuntimeConnection.forStdio({ path: path.resolve(this.config.executable) });
+    const client = this.createClient(options);
+    await client.start();
+    return client;
+  }
+}
+
+async function projectSkillDirectories(workspace) {
+  const root = path.resolve(workspace, '.github', 'skills');
+  let entries;
+  try { entries = await readdir(root, { withFileTypes: true }); }
+  catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => path.join(root, entry.name)).sort();
+}
+
+function explicitSkillInvocation(prompt, skillDirectories) {
+  const match = /^\/([^\s]+)\s*(?:\n+|$)/.exec(prompt);
+  if (!match) return undefined;
+  const directory = skillDirectories.find((item) => path.basename(item) === match[1]);
+  if (!directory) return undefined;
+  return { name: match[1], prompt: prompt.slice(match[0].length) };
+}
+
+function isTimeout(error) {
+  return error instanceof Error && /timeout|timed out/i.test(error.message);
+}

package/src/corpus.js

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const HEADING_PATTERN = /^(#{1,6})\s+(.+?)\s*$/gm;
+
+export async function loadCorpus(corpusPath) {
+  const root = path.resolve(corpusPath);
+  let entries;
+  try {
+    entries = await markdownFiles(root);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+      throw new Error(`Corpus directory does not exist: ${corpusPath}`);
+    }
+    throw error;
+  }
+
+  if (entries.length === 0) {
+    throw new Error(`Corpus contains no Markdown files: ${corpusPath}`);
+  }
+
+  return Promise.all(entries.map(async (filePath) => {
+    const content = normalizeText(await readFile(filePath, 'utf8'));
+    return {
+      documentId: path.relative(root, filePath).split(path.sep).join('/'),
+      path: filePath,
+      revision: sha256(content),
+      content,
+    };
+  }));
+}
+
+export function splitDocument(document, maxChars = 12_000) {
+  if (maxChars < 500) {
+    throw new Error('maxChars must be at least 500');
+  }
+
+  const boundaries = [0];
+  for (const match of document.content.matchAll(HEADING_PATTERN)) {
+    if (match.index > 0) boundaries.push(match.index);
+  }
+  boundaries.push(document.content.length);
+
+  const sections = [];
+  for (let index = 0; index < boundaries.length - 1; index += 1) {
+    const start = boundaries[index];
+    const end = boundaries[index + 1];
+    const rawSection = document.content.slice(start, end);
+    if (!rawSection.trim()) continue;
+    HEADING_PATTERN.lastIndex = 0;
+    const headingMatch = HEADING_PATTERN.exec(rawSection);
+    const heading = headingMatch ? headingMatch[2].trim() : 'Preamble';
+    for (const [chunkStart, chunkEnd] of chunkBounds(rawSection, maxChars)) {
+      const absoluteStart = start + chunkStart;
+      const absoluteEnd = start + chunkEnd;
+      const content = document.content.slice(absoluteStart, absoluteEnd).trim();
+      if (!content) continue;
+      const sectionKey = `${document.documentId}:${absoluteStart}:${absoluteEnd}`;
+      sections.push({
+        sectionId: `sec_${sha256(sectionKey).slice(0, 16)}`,
+        documentId: document.documentId,
+        heading,
+        content,
+        start: absoluteStart,
+        end: absoluteEnd,
+      });
+    }
+  }
+  return sections;
+}
+
+export function corpusRevision(documents) {
+  return sha256(documents.map((document) => `${document.documentId}:${document.revision}`).join('\n'));
+}
+
+async function markdownFiles(root) {
+  const files = [];
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isDirectory()) files.push(...await markdownFiles(entryPath));
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(entryPath);
+  }
+  return files;
+}
+
+function chunkBounds(content, maxChars) {
+  const bounds = [];
+  let start = 0;
+  while (start < content.length) {
+    const targetEnd = Math.min(start + maxChars, content.length);
+    let end = targetEnd;
+    if (targetEnd < content.length) {
+      const paragraphBreak = content.lastIndexOf('\n\n', targetEnd - 1);
+      const lineBreak = content.lastIndexOf('\n', targetEnd - 1);
+      const candidate = Math.max(paragraphBreak + 2, lineBreak + 1);
+      if (candidate > start) end = candidate;
+    }
+    bounds.push([start, end]);
+    start = end;
+  }
+  return bounds;
+}
+
+function normalizeText(content) {
+  return `${content.replaceAll('\r\n', '\n').replaceAll('\r', '\n').trim()}\n`;
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}