@stage-labs/metro 0.1.0-beta.279 → 0.1.0-beta.280

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.279",
+  "version": "0.1.0-beta.280",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.279",
+  "version": "0.1.0-beta.280",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

package/runtime/node_modules/@metro-labs/core/package.json

@@ -13,6 +13,7 @@
     "./automation-types": "./src/automation-types.ts",
     "./call": "./src/call.ts",
     "./secure-fs": "./src/secure-fs.ts",
+    "./skill-source": "./src/skill-source.ts",
     "./version": "./src/version.ts",
     "./train-error": "./src/train-error.ts",
     "./trains/protocol": "./src/protocol.ts",

package/runtime/node_modules/@metro-labs/core/src/skill-source.ts

@@ -0,0 +1,96 @@
+import { join } from 'node:path';
+import { isRecord } from './is-record.js';
+
+export const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const SKILL_HASH = /^[a-f0-9]{64}$/;
+export const SKILL_COMMIT = /^[a-f0-9]{40}$/;
+export const SKILL_FILE_MAX = 256 * 1024;
+export const SKILL_TOTAL_MAX = 8 * 1024 * 1024;
+export const SKILL_FILES_MAX = 256;
+export const SKILL_MANIFEST_MAX = 128 * 1024;
+
+export interface SkillSource {
+  repository: string;
+  ref: string;
+  folder: string;
+}
+
+export interface SkillFile {
+  path: string;
+  size: number;
+  sha256: string;
+  executable?: boolean;
+}
+
+export interface SkillGeneration {
+  id: string;
+  source: (SkillSource & { repositoryId: number; commit: string }) | null;
+  createdAt: string;
+  skills: { name: string; description: string }[];
+  files: SkillFile[];
+}
+
+export interface SkillActivation {
+  generation: string | null;
+  loading: string | null;
+  rollback?: string | null;
+  appliedAt: string | null;
+  problem: string | null;
+  shadowed: string[];
+}
+
+export const skillSourceRoot = (claudeDir: string): string => join(claudeDir, 'metro-github');
+export const skillRelease = (root: string, id: string): string => {
+  if (!SKILL_HASH.test(id)) throw new Error('Invalid skills generation.');
+  return join(root, 'releases', id);
+};
+
+export function skillPath(path: string): boolean {
+  const parts = path.split('/');
+  return path.length <= 240 && parts.length >= 2 && parts.length <= 8 && SKILL_NAME.test(parts[0] ?? '') &&
+    parts.every((part) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(part)) &&
+    !parts.slice(1, -1).includes('SKILL.md') && !(parts.length > 2 && parts.at(-1) === 'SKILL.md');
+}
+
+function manifestSkill(value: unknown): SkillGeneration['skills'][number] {
+  if (!isRecord(value) || typeof value.name !== 'string' || !SKILL_NAME.test(value.name) || typeof value.description !== 'string' || value.description.length > 1024) throw new Error('Invalid skill name or description.');
+  return { name: value.name, description: value.description };
+}
+
+function fileSize(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > SKILL_FILE_MAX) throw new Error('Invalid skills file size.');
+  return value;
+}
+
+function manifestFile(value: unknown): SkillFile {
+  if (!isRecord(value)) throw new Error('Invalid skills file.');
+  if (typeof value.path !== 'string' || !skillPath(value.path) || typeof value.sha256 !== 'string' || !SKILL_HASH.test(value.sha256)) throw new Error('Invalid skills file path or hash.');
+  return { path: value.path, size: fileSize(value.size), sha256: value.sha256, ...(value.executable === true ? { executable: true } : {}) };
+}
+
+function manifestSource(s: unknown): SkillGeneration['source'] {
+  if (s === null) return null;
+  if (!isRecord(s) || typeof s.repository !== 'string' || typeof s.ref !== 'string' || typeof s.folder !== 'string' || typeof s.repositoryId !== 'number' || typeof s.commit !== 'string' || !SKILL_COMMIT.test(s.commit)) throw new Error('Invalid skills provenance.');
+  return { repository: s.repository, ref: s.ref, folder: s.folder, repositoryId: s.repositoryId, commit: s.commit };
+}
+
+function checkFiles(skills: SkillGeneration['skills'], files: SkillFile[]): void {
+  if (files.reduce((sum, file) => sum + file.size, 0) > SKILL_TOTAL_MAX || new Set(files.map((f) => f.path.toLowerCase())).size !== files.length || new Set(skills.map((s) => s.name)).size !== skills.length) throw new Error('Duplicate or oversized skills files.');
+  if (files.some((f) => !skills.some((s) => f.path.startsWith(`${s.name}/`))) || skills.some((s) => !files.some((f) => f.path === `${s.name}/SKILL.md`))) throw new Error('Every skill needs its own SKILL.md.');
+}
+
+function boundedGeneration(generation: SkillGeneration): SkillGeneration {
+  if (Buffer.byteLength(JSON.stringify(generation)) > SKILL_MANIFEST_MAX) throw new Error('Skills manifest is too large.');
+  return generation;
+}
+
+export function skillGeneration(raw: unknown): SkillGeneration {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || !SKILL_HASH.test(raw.id) || typeof raw.createdAt !== 'string' || !Array.isArray(raw.skills) || !Array.isArray(raw.files)) throw new Error('Invalid skills manifest.');
+  if (raw.skills.length > 64 || raw.files.length > SKILL_FILES_MAX) throw new Error('Skills manifest is too large.');
+  const skills = raw.skills.map(manifestSkill);
+  const files = raw.files.map(manifestFile);
+  const source = manifestSource(raw.source);
+  checkFiles(skills, files);
+  if (source === null) checkFiles([], files);
+  return boundedGeneration({ id: raw.id, source, createdAt: raw.createdAt, skills, files });
+}

package/runtime/node_modules/@metro-labs/daemon/src/boot/boot.ts

@@ -32,6 +32,7 @@ import { followRelease } from '../metro-user/root-follow.js';
 import { unwatchSession, watchSession } from '../claude/session.js';
 import { liveEvents, memoryRoutine, tryClaudeSetup } from '../claude/setup.js';
 import { tryMemoryJob } from '../claude/memory-routine.js';
+import { githubSkills } from '../claude/github-skills.js';
 import { applyLocalOwner } from './local-owner.js';
 import { installBearerSessions } from '../routes/bearer.js';
 import { ensureLocalAgent, localOwner } from '../agents/file-admin.js';
@@ -195,6 +196,7 @@ async function startClaude(): Promise<void> {
       log.warn({ err: errMsg(err) }, 'plugin: could not ensure the Claude Code plugin');
     });
   tryClaudeSetup();
+  try { githubSkills().watch(); } catch { log.warn('github-skills: saved source could not be loaded'); }
   tryMemoryJob(memoryRoutine());
   watchSession();
 }

package/runtime/node_modules/@metro-labs/daemon/src/claude/api.ts

@@ -3,6 +3,8 @@ import { errMsg, log } from '@metro-labs/core/log';
 import { apiFailure, apiSession, requireAdmin, cors, readJsonBody, sendJson, type ApiSession } from '@metro-labs/http/api-http';
 import { ApiError } from '@metro-labs/http/api-error';
 import { isRecord } from '@metro-labs/core/is-record';
+import { githubSkillsAnswer } from './github-api.js';
+import { githubSkills, type GitHubSkills } from './github-skills.js';
 import { listClaudeSettings, SETTINGS_MAX, writeClaudeSettings } from './settings.js';
 import {
   createClaudeSkill,
@@ -60,6 +62,7 @@ export interface ClaudeApiDeps extends SetupApiDeps {
   login?: LoginDeps;
   claudeLogins?: ClaudeLoginDeps;
   version?: VersionDeps;
+  skillSource?: GitHubSkills;
 }
 
 function projectOf(query: URLSearchParams): string {
@@ -132,7 +135,7 @@ async function created(req: IncomingMessage, path: string, dir: string): Promise
   return createClaudeSkill(body.name, typeof body.text === 'string' ? body.text : undefined, dir);
 }
 
-const ADMIN_ONLY = /^\/api\/claude\/(login|session|version|setup)(\/|$)/;
+const ADMIN_ONLY = /^\/api\/claude\/(login|session|version|setup|skill-source)(\/|$)/;
 const LOGIN = 'login';
 const SESSION = 'session';
 const SETUP = 'setup';
@@ -220,15 +223,37 @@ const SINGLETONS: Record<string, (req: IncomingMessage, deps: ClaudeApiDeps, ses
   [VERSION]: versionAnswer,
 };
 
+function skillsAnswer(req: IncomingMessage, path: string, search: string, dir: string, source: GitHubSkills): unknown {
+  const segments = parts(path);
+  if (req.method === 'GET' && segments.length === 1) {
+    const listing = source.listing();
+    return { skills: [...listClaudeSkills(dir), ...listing.rows], skillSource: listing.skillSource };
+  }
+  const item = decodeURIComponent(segments[1] ?? '');
+  if (segments.length === 2 && item.startsWith('github:')) {
+    if (req.method !== 'GET') throw new ApiError('GitHub skills are read-only here. Edit the repository or remove its source.', 409);
+    return source.read(item);
+  }
+  return fileAnswer(req, path, search, dir);
+}
+
+const sourceOf = (deps: ClaudeApiDeps): GitHubSkills => deps.skillSource ?? githubSkills();
+
+function fileAnswer(req: IncomingMessage, path: string, search: string, dir: string): unknown {
+  if (req.method === 'PUT') return writeAnswer(req, path, search, dir);
+  if (req.method === 'POST') return created(req, path, dir);
+  return answer(req.method ?? 'GET', path, new URLSearchParams(search), dir);
+}
+
 function routed(req: IncomingMessage, path: string, search: string, deps: ClaudeApiDeps, session: ApiSession): unknown {
   const dir = (deps.dir ?? claudeDir)();
   const [head = '', item = ''] = parts(path);
   if (head === LOGIN) return loginAnswer(req, item, deps);
+  if (head === 'skill-source' && parts(path).length === 1) return githubSkillsAnswer(req, deps.skillSource);
+  if (head === 'skills') return skillsAnswer(req, path, search, dir, sourceOf(deps));
   const single = item === '' ? SINGLETONS[head] : undefined;
   if (single !== undefined) return single(req, deps, session);
-  if (req.method === 'PUT') return writeAnswer(req, path, search, dir);
-  if (req.method === 'POST') return created(req, path, dir);
-  return answer(req.method ?? 'GET', path, new URLSearchParams(search), dir);
+  return fileAnswer(req, path, search, dir);
 }
 
 const TEXT = 'text/plain; charset=utf-8';
@@ -276,7 +301,7 @@ export function handleClaudeRequest(
         sendJson(req, res, 200, sessionSnapshot(deps.session));
         return;
       }
-      if (req.method !== 'GET' && ADMIN_ONLY.test(path)) requireAdmin(session);
+      if (req.method !== 'GET' && ADMIN_ONLY.test(path.replace(/\/{2,}/g, '/'))) requireAdmin(session);
       if (await streamed(req, res, path, search, (deps.dir ?? claudeDir)())) return;
       sendJson(req, res, 200, await routed(req, path, search, deps, session));
     })

package/runtime/node_modules/@metro-labs/daemon/src/claude/github-api.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage } from 'node:http';
+import { readJsonBody } from '@metro-labs/http/api-http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { githubSkills, type GitHubSkills } from './github-skills.js';
+
+export async function githubSkillsAnswer(req: IncomingMessage, source: GitHubSkills = githubSkills()): Promise<object> {
+  if (req.method === 'GET') return source.view();
+  if (req.method === 'PUT') return source.configure(await readJsonBody(req, 4096));
+  if (req.method === 'DELETE') return source.remove();
+  if (req.method === 'POST') { await source.sync(true); return source.view(); }
+  throw new ApiError('method not allowed', 405);
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/github-fetch.ts

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { SKILL_COMMIT, SKILL_FILE_MAX, SKILL_FILES_MAX, SKILL_TOTAL_MAX, skillPath, type SkillSource } from '@metro-labs/core/skill-source';
+
+export class GitHubFailure extends Error {
+  constructor(message: string, readonly retryAt = Date.now() + 60_000, readonly rateLimited = false) { super(message); }
+}
+
+export interface GitHubSnapshot {
+  repositoryId: number;
+  commit: string;
+  etag: string | null;
+  files: Map<string, Buffer>;
+  executables?: string[];
+}
+
+interface Entry { path: string; mode: string; type: string; sha: string; size: number }
+type Request = (url: string, init: RequestInit) => Promise<Response>;
+const API = 'https://api.github.com/repos/';
+const RESPONSE_MAX = 2 * 1024 * 1024;
+
+async function boundedJson(response: Response, text: boolean): Promise<unknown> {
+  if (response.body === null) throw new GitHubFailure('GitHub returned an empty response.');
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > RESPONSE_MAX) throw new GitHubFailure('GitHub returned too much data. Choose a smaller skills folder.');
+      chunks.push(value);
+    }
+    const body = Buffer.concat(chunks).toString('utf8');
+    return text ? body.trim() : JSON.parse(body) as unknown;
+  } finally { await reader.cancel().catch(() => undefined); }
+}
+
+function refused(response: Response): GitHubFailure {
+  const retry = Number(response.headers.get('retry-after'));
+  const reset = Number(response.headers.get('x-ratelimit-reset')) * 1000;
+  if (response.status === 429 || (response.status === 403 && (response.headers.get('x-ratelimit-remaining') === '0' || retry > 0))) {
+    return new GitHubFailure('GitHub rate limit reached. Sync will retry later.', Math.max(Date.now() + 60_000, Date.now() + (Number.isFinite(retry) ? retry * 1000 : 0), Number.isFinite(reset) ? reset : 0), true);
+  }
+  if ([401, 403, 404].includes(response.status)) return new GitHubFailure('GitHub access was refused. Check the repository, ref, token expiry and organization approval. The loaded skills are kept.', Date.now() + 15 * 60_000);
+  return new GitHubFailure('GitHub could not provide the skills. The loaded skills are kept.');
+}
+
+function headers(token: string, etag: string | null | undefined, shaOnly: boolean): Record<string, string> {
+  return { Authorization: `Bearer ${token}`, Accept: shaOnly ? 'application/vnd.github.sha' : 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', ...(etag ? { 'If-None-Match': etag } : {}) };
+}
+
+export class GitHubReader {
+  private readonly base: string;
+  private count = 0;
+  private readonly signal = AbortSignal.timeout(120_000);
+  constructor(private readonly source: SkillSource, private readonly token: string, private readonly request: Request = fetch) {
+    this.base = `${API}${source.repository}`;
+  }
+
+  private async get(path: string, etag?: string | null, shaOnly = false): Promise<{ data: unknown; etag: string | null; unchanged: boolean }> {
+    if (++this.count > SKILL_FILES_MAX + 12) throw new GitHubFailure('The skills folder needs too many GitHub requests.');
+    let response: Response;
+    try {
+      response = await this.request(`${this.base}${path}`, {
+        headers: headers(this.token, etag, shaOnly),
+        redirect: 'manual', signal: AbortSignal.any([this.signal, AbortSignal.timeout(20_000)]),
+      });
+    } catch { throw new GitHubFailure('GitHub is unreachable. The loaded skills are kept.'); }
+    if (response.status === 304) return { data: null, etag: etag ?? null, unchanged: true };
+    if (!response.ok) { await response.body?.cancel(); throw refused(response); }
+    try { return { data: await boundedJson(response, shaOnly), etag: response.headers.get('etag'), unchanged: false }; }
+    catch (err) { if (err instanceof GitHubFailure) throw err; throw new GitHubFailure('GitHub returned invalid skills data.'); }
+  }
+
+  private async tree(sha: string, recursive: boolean): Promise<Entry[]> {
+    const { data } = await this.get(`/git/trees/${sha}${recursive ? '?recursive=1' : ''}`);
+    if (!isRecord(data) || data.truncated !== false || !Array.isArray(data.tree) || data.tree.length > 4096) throw new GitHubFailure('The GitHub tree is incomplete or too large. Choose a smaller skills folder.');
+    return data.tree.map((raw: unknown) => {
+      if (!isRecord(raw) || typeof raw.path !== 'string' || typeof raw.mode !== 'string' || typeof raw.type !== 'string' || typeof raw.sha !== 'string' || !SKILL_COMMIT.test(raw.sha)) throw new GitHubFailure('GitHub returned an invalid tree.');
+      return { path: raw.path, mode: raw.mode, type: raw.type, sha: raw.sha, size: typeof raw.size === 'number' ? raw.size : 0 };
+    });
+  }
+
+  private async folder(tree: string): Promise<string> {
+    let sha = tree;
+    for (const segment of this.source.folder.split('/').filter(Boolean)) {
+      const entry = (await this.tree(sha, false)).find((row) => row.path === segment);
+      if (entry?.mode !== '040000' || entry.type !== 'tree') throw new GitHubFailure('The selected skills folder is missing or is not a regular directory.');
+      sha = entry.sha;
+    }
+    return sha;
+  }
+
+  private async blob(entry: Entry): Promise<Buffer> {
+    const { data } = await this.get(`/git/blobs/${entry.sha}`);
+    if (!isRecord(data) || data.encoding !== 'base64' || typeof data.content !== 'string' || data.size !== entry.size) throw new GitHubFailure('GitHub returned an invalid skill file.');
+    const encoded = data.content.replace(/\n/g, '');
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw new GitHubFailure('GitHub returned an invalid skill file.');
+    const bytes = Buffer.from(encoded, 'base64');
+    const hash = createHash('sha1').update(`blob ${bytes.byteLength}\0`).update(bytes).digest('hex');
+    if (bytes.byteLength !== entry.size || hash !== entry.sha) throw new GitHubFailure('A skill file has an unexpected size or Git object hash.');
+    return bytes;
+  }
+
+  private async repository(expected: number | null): Promise<number> {
+    const repo = (await this.get('')).data;
+    if (!isRecord(repo) || typeof repo.id !== 'number' || typeof repo.full_name !== 'string' || repo.full_name.toLowerCase() !== this.source.repository.toLowerCase() || (expected !== null && repo.id !== expected)) throw new GitHubFailure('The GitHub repository identity changed. Reconnect it explicitly.');
+    return repo.id;
+  }
+
+  async snapshot(repositoryId: number | null, commit: string | null, etag: string | null): Promise<GitHubSnapshot | null> {
+    const id = await this.repository(repositoryId);
+    const resolved = await this.get(`/commits/${encodeURIComponent(this.source.ref)}`, etag, true);
+    if (resolved.unchanged) return null;
+    if (typeof resolved.data !== 'string' || !SKILL_COMMIT.test(resolved.data)) throw new GitHubFailure('GitHub did not resolve an immutable commit.');
+    if (resolved.data === commit) return null;
+    const data = immutableCommit((await this.get(`/git/commits/${resolved.data}`)).data);
+    if (data.sha !== resolved.data) throw new GitHubFailure('GitHub returned a different commit.');
+    const entries = checkedEntries(await this.tree(await this.folder(data.tree), true));
+    const files = await this.blobs(entries);
+    return { repositoryId: id, commit: data.sha, etag: resolved.etag, files, executables: entries.filter((entry) => entry.mode === '100755').map((entry) => entry.path) };
+  }
+
+  private async blobs(entries: Entry[]): Promise<Map<string, Buffer>> {
+    const queue = [...entries];
+    const files = new Map<string, Buffer>();
+    const worker = async (): Promise<void> => {
+      for (let entry = queue.shift(); entry !== undefined; entry = queue.shift()) files.set(entry.path, await this.blob(entry));
+    };
+    try { await Promise.all(Array.from({ length: Math.min(4, queue.length) }, worker)); }
+    catch (err) { queue.length = 0; throw err; }
+    return files;
+  }
+}
+
+function immutableCommit(data: unknown): { sha: string; tree: string } {
+  if (!isRecord(data) || typeof data.sha !== 'string' || !SKILL_COMMIT.test(data.sha) || !isRecord(data.tree) || typeof data.tree.sha !== 'string' || !SKILL_COMMIT.test(data.tree.sha)) throw new GitHubFailure('GitHub did not resolve an immutable commit.');
+  return { sha: data.sha, tree: data.tree.sha };
+}
+
+function regularFile(entry: Entry): void {
+  if (entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) throw new GitHubFailure('Symlinks, submodules and special files are not supported in skills.');
+  if (!skillPath(entry.path) || entry.size < 0 || entry.size > SKILL_FILE_MAX || !Number.isInteger(entry.size)) throw new GitHubFailure('A skills path or file size is not supported. Use skill-name/SKILL.md and regular resources, up to 256 KiB each.');
+}
+
+function checkedEntries(entries: Entry[]): Entry[] {
+  const files: Entry[] = [];
+  let total = 0;
+  for (const entry of entries) {
+    if (entry.mode === '040000' && entry.type === 'tree') continue;
+    regularFile(entry);
+    total += entry.size;
+    files.push(entry);
+  }
+  if (files.length > SKILL_FILES_MAX || total > SKILL_TOTAL_MAX) throw new GitHubFailure('Skills exceed 256 files or 8 MiB.');
+  if (new Set(files.map((entry) => entry.path.toLowerCase())).size !== files.length) throw new GitHubFailure('Skills contain duplicate file paths.');
+  return files;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/github-skills.ts

@@ -0,0 +1,257 @@
+import { existsSync, readFileSync as readLocal, statSync as statLocal } from 'node:fs';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { SKILL_HASH, SKILL_MANIFEST_MAX, skillGeneration, skillRelease, skillSourceRoot, type SkillGeneration } from '@metro-labs/core/skill-source';
+import { ApiError } from '@metro-labs/http/api-error';
+import { readFileSync, statSync } from '../agent-user/agent-fs.js';
+import { receiveHomeFile, writeHomeText } from '../agent-user/home-fs.js';
+import { agentsDir } from '../agents/files.js';
+import { claudeDir } from './files.js';
+import { readSetupState } from './setup-state.js';
+import { GitHubFailure, GitHubReader } from './github-fetch.js';
+import { githubSource, validatedGeneration } from './github-validate.js';
+import type { ClaudeSkill } from './skills.js';
+
+type Configuration = ReturnType<typeof githubSource>;
+interface Stored {
+  source: Configuration | null;
+  prepared: SkillGeneration | null;
+  etag: string | null;
+  checkedAt: string | null;
+  retryAt: number;
+  problem: string | null;
+  rateLimit: number;
+  repositoryId: number | null;
+}
+export interface GitHubSkillsDeps {
+  agents: string;
+  claude: string;
+  sdk(): boolean;
+  request?: (url: string, init: RequestInit) => Promise<Response>;
+}
+const EMPTY: Stored = { source: null, prepared: null, etag: null, checkedAt: null, retryAt: 0, problem: null, rateLimit: 0, repositoryId: null };
+const savedString = (value: unknown): string | null => typeof value === 'string' ? value : null;
+const savedNumber = (value: unknown): number => typeof value === 'number' && Number.isFinite(value) ? value : 0;
+
+function readStored(path: string): Stored {
+  if (!existsSync(path)) return { ...EMPTY };
+  try {
+    if (statLocal(path).size > SKILL_MANIFEST_MAX * 2) throw new Error('size');
+    const raw: unknown = JSON.parse(readLocal(path, 'utf8'));
+    if (!isRecord(raw)) throw new Error('shape');
+    return {
+      source: raw.source === null ? null : githubSource(raw.source),
+      prepared: raw.prepared === null ? null : skillGeneration(raw.prepared),
+      etag: savedString(raw.etag), checkedAt: savedString(raw.checkedAt),
+      retryAt: savedNumber(raw.retryAt), rateLimit: savedNumber(raw.rateLimit), problem: savedString(raw.problem),
+      repositoryId: typeof raw.repositoryId === 'number' ? raw.repositoryId : null,
+    };
+  } catch { throw new Error('The saved GitHub skills source is unreadable. Restore it before changing the source.'); }
+}
+
+function agentJson(path: string): unknown {
+  try {
+    if (statSync(path).size > SKILL_MANIFEST_MAX) return null;
+    return JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  } catch { return null; }
+}
+
+export class GitHubSkills {
+  private readonly path: string;
+  readonly root: string;
+  private stored: Stored = { ...EMPTY };
+  private unreadable = false;
+  private busy = false;
+  private epoch = 0;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly deps: GitHubSkillsDeps) {
+    this.path = join(deps.agents, 'github-skills.json');
+    this.root = skillSourceRoot(deps.claude);
+    try { this.stored = readStored(this.path); }
+    catch { this.unreadable = true; }
+  }
+
+  private readable(): void {
+    if (!this.unreadable) return;
+    this.stored = readStored(this.path);
+    this.unreadable = false;
+  }
+
+  private save(): void {
+    this.readable();
+    writeSecure(this.path, JSON.stringify(this.stored));
+  }
+
+  private activation(): { generation: string | null; appliedAt: string | null; problem: string | null; shadowed: string[] } {
+    const raw = agentJson(join(this.root, 'status.json'));
+    if (!isRecord(raw)) return { generation: null, appliedAt: null, problem: null, shadowed: [] };
+    return {
+      generation: typeof raw.generation === 'string' && SKILL_HASH.test(raw.generation) ? raw.generation : null,
+      appliedAt: typeof raw.appliedAt === 'string' ? raw.appliedAt : null,
+      problem: typeof raw.problem === 'string' ? raw.problem.slice(0, 300) : null,
+      shadowed: Array.isArray(raw.shadowed) ? raw.shadowed.filter((name): name is string => typeof name === 'string').slice(0, 64) : [],
+    };
+  }
+
+  private loaded(activation = this.activation()): SkillGeneration | null {
+    const id = activation.generation;
+    if (id === null) return null;
+    try { return skillGeneration(agentJson(join(skillRelease(this.root, id), 'manifest.json'))); }
+    catch { return null; }
+  }
+
+  view(activation = this.activation(), loaded = this.loaded(activation)): object {
+    const { source, prepared, checkedAt, problem } = this.stored;
+    return {
+      supported: this.deps.sdk(),
+      source: source === null ? null : { repository: source.repository, ref: source.ref, folder: source.folder, hasToken: true },
+      checking: this.busy, checkedAt, problem: this.unreadable ? 'The saved GitHub source is unreadable. Restore its configuration before changing it. Local skills are still available.' : problem,
+      prepared: prepared === null ? null : { generation: prepared.id, source: prepared.source, skillCount: prepared.skills.length },
+      loaded: loaded?.source ?? null, activation,
+      pending: prepared !== null && prepared.id !== activation.generation,
+    };
+  }
+
+  listing(): { rows: ClaudeSkill[]; skillSource: object } {
+    const activation = this.activation();
+    const loaded = this.loaded(activation);
+    return { rows: this.rows(activation, loaded), skillSource: this.view(activation, loaded) };
+  }
+
+  rows(activation = this.activation(), loaded = this.loaded(activation)): ClaudeSkill[] {
+    if (loaded === null) return [];
+    const shadowed = activation.shadowed;
+    return loaded.skills.map((skill) => ({
+      id: `github:${skill.name}`, name: skill.name, title: skill.name, description: skill.description,
+      path: join(skillRelease(this.root, loaded.id), 'skills', skill.name, 'SKILL.md'), editable: false,
+      updatedAt: loaded.createdAt, managed: true, shadowed: shadowed.includes(skill.name),
+    }));
+  }
+
+  read(id: string): ClaudeSkill & { text: string } {
+    const row = this.rows().find((skill) => skill.id === id);
+    if (row === undefined) throw new ApiError('no such skill', 404);
+    if (statSync(row.path).size > 256 * 1024) throw new ApiError('The managed skill changed on disk. Sync it again.', 409);
+    return { ...row, text: readFileSync(row.path, 'utf8') };
+  }
+
+  async configure(raw: unknown): Promise<object> {
+    if (!this.deps.sdk()) throw new ApiError('GitHub skills require the Agent SDK runner. Local skills are unchanged.', 409);
+    if (this.busy) throw new ApiError('A skills sync is already running. Try again when it finishes.', 409);
+    const source = githubSource(raw);
+    this.readable();
+    const loaded = this.loaded();
+    this.epoch += 1;
+    this.stored = { ...this.stored, source, prepared: loaded, etag: null, retryAt: 0, problem: null, repositoryId: null };
+    if (loaded === null) await this.publish(validatedGeneration(null, null), new Map(), this.epoch);
+    else { this.save(); this.offer(); }
+    await this.sync(true);
+    return this.view();
+  }
+
+  async remove(): Promise<object> {
+    this.readable();
+    this.epoch += 1;
+    this.stored = { ...EMPTY };
+    this.save();
+    await this.publish(validatedGeneration(null, null), new Map(), this.epoch);
+    return this.view();
+  }
+
+  private waiting(force: boolean): boolean {
+    if (Date.now() < this.stored.rateLimit) return true;
+    if (force) return false;
+    return Date.now() < this.stored.retryAt || (this.stored.prepared !== null && this.stored.prepared.id !== this.activation().generation);
+  }
+
+  private reader(source: Configuration, known: SkillGeneration['source'], force: boolean): ReturnType<GitHubReader['snapshot']> {
+    return new GitHubReader(source, source.token, this.deps.request).snapshot(this.stored.repositoryId, force ? null : known?.commit ?? null, force ? null : this.stored.etag);
+  }
+
+  private async fetch(source: Configuration, epoch: number, force: boolean): Promise<void> {
+    const previous = this.stored.prepared?.source;
+    const same = previous?.repository === source.repository && previous.ref === source.ref && previous.folder === source.folder;
+    const known = same ? previous : null;
+    const snapshot = await this.reader(source, known, force);
+    if (epoch !== this.epoch) return;
+    if (snapshot !== null) {
+      const generation = validatedGeneration(source, snapshot);
+      this.stored.etag = snapshot.etag;
+      this.stored.repositoryId = snapshot.repositoryId;
+      await this.publish(generation, snapshot.files, epoch);
+      if (epoch !== this.epoch) return;
+    }
+    this.stored.checkedAt = new Date().toISOString();
+    this.stored.problem = null;
+    this.stored.retryAt = Date.now() + 60_000;
+  }
+
+  async sync(force = false): Promise<void> {
+    if (force && !this.deps.sdk()) throw new ApiError('GitHub skills require the Agent SDK runner. Local skills are unchanged.', 409);
+    this.readable();
+    this.offer();
+    const source = this.stored.source;
+    if (source === null || this.busy || !this.deps.sdk() || this.waiting(force)) return;
+    const epoch = this.epoch;
+    this.busy = true;
+    try { await this.fetch(source, epoch, force); }
+    catch (err) {
+      if (epoch !== this.epoch) return;
+      this.failure(err);
+    } finally {
+      this.busy = false;
+      this.save();
+    }
+  }
+
+  private failure(err: unknown): void {
+    this.stored.problem = err instanceof GitHubFailure ? err.message : 'The repository failed skill validation or staging. Keep one folder per skill, safe metadata and regular files. The loaded skills are kept.';
+    this.stored.retryAt = err instanceof GitHubFailure ? err.retryAt : Date.now() + 5 * 60_000;
+    if (err instanceof GitHubFailure && err.rateLimited) this.stored.rateLimit = err.retryAt;
+    this.stored.checkedAt = new Date().toISOString();
+  }
+
+  private offer(): void {
+    const generation = this.stored.prepared;
+    if (generation === null) return;
+    const pending = agentJson(join(this.root, 'pending.json'));
+    if (isRecord(pending) && pending.id === generation.id) return;
+    writeHomeText(join(this.root, 'pending.json'), JSON.stringify(generation), 0o600);
+  }
+
+  private async publish(generation: SkillGeneration, files: Map<string, Buffer>, epoch: number): Promise<void> {
+    const release = skillRelease(this.root, generation.id);
+    const deadline = Date.now() + 120_000;
+    for (const [path, bytes] of files) {
+      if (epoch !== this.epoch) return;
+      if (Date.now() > deadline) throw new Error('Staging skills timed out.');
+      const mode = generation.files.find((file) => file.path === path)?.executable === true ? 0o700 : 0o600;
+      await receiveHomeFile(join(release, 'skills', path), Readable.from(bytes), mode);
+    }
+    if (epoch !== this.epoch) return;
+    writeHomeText(join(release, 'manifest.json'), JSON.stringify(generation), 0o600);
+    this.stored.prepared = generation;
+    this.save();
+    this.offer();
+  }
+
+  watch(): void {
+    if (this.timer !== null) return;
+    const tick = (): void => {
+      this.sync().catch(() => { log.warn('github-skills: could not save sync state'); });
+      this.timer = setTimeout(tick, 60_000 + Math.floor(Math.random() * 5_000));
+      this.timer.unref();
+    };
+    tick();
+  }
+}
+
+let current: GitHubSkills | null = null;
+export function githubSkills(): GitHubSkills {
+  current ??= new GitHubSkills({ agents: agentsDir(), claude: claudeDir(), sdk: () => readSetupState(agentsDir()).runner === 'sdk' });
+  return current;
+}