@theokit/sdk 5.13.0 → 5.15.0

package/dist/chunk-6CXRYPG7.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/memory/dreaming/diary.ts","../src/internal/memory/migrate-sqlite-to-lance.ts"],"names":["join","readFile","replaceFileAtomic","createHash","defaultIndexPath","existsSync","openMemoryDb","ConfigurationError","resolveMemoryRoot","lanceStoragePath","redactSecrets","rmSync","mkdirSync","LanceIndex","renameSync"],"mappings":"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","file":"chunk-6CXRYPG7.cjs","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { replaceFileAtomic } from \"../../persistence/atomic-write.js\";\nimport type { MemoryRoot } from \"../storage/memory-root.js\";\n\n/**\n * Dream-diary append (ADR D7).\n *\n * Diary lives at `.theokit/memory/dream-diary.md` and grows with one entry\n * per sweep. Each entry is content-hashed so the same input produces the\n * same entry — idempotency contract.\n *\n * Writes go through `replaceFileAtomic` (EC-3 of edge-case review) so a\n * crash mid-write can never leave a half-written diary.\n *\n * Shared with `@theokit/sdk-memory`; see the memory-store barrel.\n */\n\nexport interface DiaryEntry {\n  timestampMs: number;\n  factsBefore: number;\n  factsAfter: number;\n  duplicatesRemoved: number;\n  clustersCreated: number;\n  notesWritten: number;\n}\n\n/** `<memory root>/dream-diary.md`. Takes the RESOLVED ROOT — see `storage/memory-root.ts` (#463). */\nexport function diaryPath(root: MemoryRoot): string {\n  return join(root, \"dream-diary.md\");\n}\n\n/**\n * One diary entry as the markdown that gets appended: a timestamp heading, the short entry hash,\n * and the counts the sweep produced. The hash is what makes a re-run recognisable as the same\n * sweep rather than a new one.\n */\nexport function renderDiaryEntry(entry: DiaryEntry): string {\n  const stamp = new Date(entry.timestampMs).toISOString();\n  const hash = entryHash(entry).slice(0, 8);\n  return [\n    `## ${stamp}`,\n    \"\",\n    `- entry-hash: ${hash}`,\n    `- facts before: ${entry.factsBefore}`,\n    `- facts after: ${entry.factsAfter}`,\n    `- duplicates removed: ${entry.duplicatesRemoved}`,\n    `- clusters created: ${entry.clustersCreated}`,\n    `- notes written: ${entry.notesWritten}`,\n    \"\",\n  ].join(\"\\n\");\n}\n\n/**\n * Append one sweep's entry to `<memory root>/dream-diary.md`, creating the file with its header\n * when this is the first sweep. The diary is a human-readable record of what dreaming changed —\n * consolidations are otherwise invisible, because they alter the notes rather than announce\n * themselves.\n */\nexport async function appendDiaryEntry(root: MemoryRoot, entry: DiaryEntry): Promise<void> {\n  const path = diaryPath(root);\n  let raw = \"\";\n  try {\n    raw = await readFile(path, \"utf8\");\n  } catch {\n    raw = \"# Dream Diary\\n\\n\";\n  }\n  const next = `${raw.endsWith(\"\\n\") ? raw : `${raw}\\n`}${renderDiaryEntry(entry)}`;\n  await replaceFileAtomic(path, next);\n}\n\n/**\n * A stable hash of one entry's counts, so two sweeps that did the same work read as the same work.\n * Rendered truncated in the entry; the full value is what callers compare.\n */\nexport function entryHash(entry: DiaryEntry): string {\n  return createHash(\"sha256\")\n    .update(\n      [\n        entry.factsBefore,\n        entry.factsAfter,\n        entry.duplicatesRemoved,\n        entry.clustersCreated,\n        entry.notesWritten,\n      ].join(\"|\"),\n    )\n    .digest(\"hex\");\n}\n","import { existsSync, mkdirSync, renameSync, rmSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nimport { ConfigurationError } from \"../../errors.js\";\nimport { redactSecrets } from \"../security/index.js\";\nimport { defaultIndexPath, openMemoryDb } from \"./index-db.js\";\nimport { LanceIndex, lanceStoragePath } from \"./lance-index.js\";\nimport { type MemoryRoot, resolveMemoryRoot } from \"./storage/memory-root.js\";\n\n/**\n * Migrate Memory.index from SQLite to LanceDB (ADR D44).\n *\n * EC-3 MUST FIX: validation uses NFC unicode normalization on both sides.\n *\n * Shared with `@theokit/sdk-memory` through the memory-store barrel (#463).\n */\n\nexport interface MigrateOptions {\n  cwd: string;\n  /**\n   * Absolute path (or `~/`-prefixed) of the memory root to migrate, when the agent that wrote it\n   * set `memory.directory`. Defaults to `<cwd>/.theokit/memory` (#463).\n   */\n  directory?: string;\n  dryRun?: boolean;\n  batchSize?: number;\n  /** Inject for tests; defaults to console.log. */\n  logger?: (msg: string) => void;\n}\n\nexport interface MigrateResult {\n  countSqlite: number;\n  countLance: number;\n  /** Set when validation succeeded (or dryRun); false on validation failure. */\n  validated: boolean;\n  /** Per-fact compare results (size = sample count, up to 10). */\n  sampleComparisons: ReadonlyArray<{ id: string; match: boolean }>;\n  /** Lance storage location (final, after migration). */\n  lancePath: string;\n  /** Was the migration committed (false for dry-run). */\n  committed: boolean;\n}\n\n/**\n * One row of the SQLite memory index, as the Lance migration reads it: the chunk plus the tenant\n * columns the target table needs. Shared with `@theokit/sdk-memory`, which migrates the same table.\n */\nexport interface SqliteFactRow {\n  id: string;\n  path: string;\n  source: \"memory\" | \"sessions\" | \"wiki\";\n  start_line: number;\n  end_line: number;\n  text: string;\n  namespace?: string | null;\n  scope?: string | null;\n  user_id?: string | null;\n}\n\n/**\n * Read all facts from the SQLite memory index. Returns empty array if the\n * SQLite db file does not exist (workspace never used Memory).\n *\n * Shared with `@theokit/sdk-memory` through the memory-store barrel, so it carries no visibility\n * tag — naming that tag in this block would delete the function below it (#463).\n */\nexport async function readAllSqliteFacts(root: MemoryRoot): Promise<SqliteFactRow[]> {\n  const dbPath = defaultIndexPath(root);\n  if (!existsSync(dbPath)) return [];\n  const db = await openMemoryDb({ filePath: dbPath });\n  try {\n    // SQLite schema: chunks table holds the facts. Schema may vary; we\n    // probe column existence and fall back to safe defaults.\n    const stmt = db.prepare(\"SELECT id, path, source, start_line, end_line, text FROM chunks\");\n    const rows = stmt.all() as Array<{\n      id: string;\n      path: string;\n      source: \"memory\" | \"sessions\" | \"wiki\";\n      start_line: number;\n      end_line: number;\n      text: string;\n    }>;\n    return rows.map((r) => ({\n      ...r,\n      namespace: \"default\",\n      scope: \"agent\",\n      user_id: \"default\",\n    }));\n  } finally {\n    db.close();\n  }\n}\n\n/**\n * Compare two strings via NFC normalization (EC-3 MUST FIX). Required\n * because SQLite/Lance native bindings can normalize unicode differently\n * (NFC vs NFD), producing false negatives on facts with accents/emojis.\n *\n * @internal\n */\nfunction nfcEqual(a: string, b: string): boolean {\n  return a.normalize(\"NFC\") === b.normalize(\"NFC\");\n}\n\n/**\n * Refuse a `batchSize` the loop below cannot make progress with, before anything is migrated.\n *\n * The loop is `for (let i = 0; i < facts.length; i += batchSize)`, so the three ways this goes wrong\n * are all silent and all different:\n *\n *  - 0 or negative: `i` never advances past the guard. The migration SPINS FOREVER, calling\n *    `addFacts([])` and writing a \"Migrated x/y\" line every iteration — a hang with unbounded output,\n *    which is the worst shape a failure can take because it looks like work.\n *  - NaN (`Number(\"abc\")`): `i += NaN` makes the guard false on the first check, zero facts move, and\n *    the caller is told \"Validation FAILED. SQLite preserved.\" A typo in an argument is reported as a\n *    migration failure.\n *  - a fraction: `slice` truncates and the loop still terminates, but the batch boundaries stop\n *    matching the number the caller asked for.\n *\n * Validated HERE rather than only in the CLI that motivated the finding, because the CLI is a wrapper\n * over this function and a programmatic caller reaches it with no wrapper at all.\n *\n * @internal\n */\nfunction assertUsableBatchSize(batchSize: number | undefined): void {\n  if (batchSize === undefined) return;\n  if (!Number.isInteger(batchSize) || batchSize < 1) {\n    throw new ConfigurationError(\n      `migrateSqliteToLance: batchSize must be a whole number of at least 1; received ${String(batchSize)}.`,\n      { code: \"invalid_batch_size\" },\n    );\n  }\n}\n\n/**\n * Run the migration. Writes Lance to `<cwd>/.theokit/memory/lance-new/`\n * first, validates round-trip, then renames to `lance/` on success.\n * SQLite db is preserved (CLI prompts user to delete).\n *\n * @internal\n */\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: migration is a single transaction (read → write → validate → commit-or-rollback); splitting harms atomicity reasoning.\nexport async function migrateSqliteToLance(opts: MigrateOptions): Promise<MigrateResult> {\n  assertUsableBatchSize(opts.batchSize);\n  const cwd = opts.cwd;\n  // One resolution, reused by every path this migration touches (#463).\n  const memoryRoot = resolveMemoryRoot(cwd, { directory: opts.directory });\n  const finalPath = lanceStoragePath(memoryRoot);\n  const newPath = join(memoryRoot, \"lance-new\");\n  // T1.4 (ADR D68): wrap logger so any fact text containing secrets is\n  // masked before reaching the destination (console or user-supplied sink).\n  // Caller-supplied loggers cannot bypass — by design (D70).\n  const rawLog = opts.logger ?? ((m: string) => console.log(m));\n  const log = (m: string) => rawLog(redactSecrets(m));\n\n  // EC: destination exists → typed error.\n  if (existsSync(finalPath)) {\n    throw new ConfigurationError(\n      `Destination already exists: ${finalPath}. Remove it manually (\\`rm -rf ${finalPath}\\`) and re-run.`,\n      { code: \"migration_destination_exists\" },\n    );\n  }\n  if (existsSync(newPath)) {\n    // Leftover from a previous failed/interrupted migration. Safe to delete.\n    log(`Removing stale ${newPath} from a previous run...`);\n    rmSync(newPath, { recursive: true, force: true });\n  }\n\n  log(`Reading SQLite facts from ${cwd}/.theokit/memory/index.sqlite ...`);\n  const sqliteFacts = await readAllSqliteFacts(memoryRoot);\n  log(`SQLite has ${sqliteFacts.length} facts.`);\n  if (sqliteFacts.length === 0) {\n    return {\n      countSqlite: 0,\n      countLance: 0,\n      validated: true,\n      sampleComparisons: [],\n      lancePath: finalPath,\n      committed: false,\n    };\n  }\n\n  // Reuse the embedding runtime configured in the workspace? For v1.2 we\n  // require the caller to pass embedding explicitly via env. The migration\n  // path is documented as: \"set OPENAI_API_KEY (or similar) before running.\"\n  // Here we ship a placeholder embedder that uses a deterministic\n  // content-hash — sufficient for migration validation; consumers should\n  // re-embed on first real query after migration if needed.\n  const placeholderEmbedding = {\n    id: \"migration-placeholder\",\n    model: \"deterministic-hash\",\n    dimension: 8,\n    embed: async (texts: ReadonlyArray<string>) => {\n      // Simple deterministic hash → 8-dim vector (migration validation only).\n      return texts.map((t) => {\n        const arr = new Array(8).fill(0);\n        for (let i = 0; i < t.length; i += 1) {\n          arr[i % 8] += t.charCodeAt(i);\n        }\n        return arr.map((x) => x / 1000);\n      });\n    },\n    stats: () => ({ cacheHits: 0, cacheMisses: 0, httpCalls: 0, retries: 0 }),\n  };\n\n  mkdirSync(newPath, { recursive: true });\n  log(`Writing Lance index to ${newPath} ...`);\n\n  const lance = await LanceIndex.open({\n    cwd,\n    embedding: placeholderEmbedding,\n    storagePath: newPath,\n  });\n\n  const batchSize = opts.batchSize ?? 100;\n  for (let i = 0; i < sqliteFacts.length; i += batchSize) {\n    const batch = sqliteFacts.slice(i, i + batchSize).map((f) => ({\n      id: f.id,\n      text: f.text,\n      source: f.source,\n      namespace: f.namespace ?? \"default\",\n      scope: f.scope ?? \"agent\",\n      user_id: f.user_id ?? \"default\",\n      timestamp: 0,\n    }));\n    await lance.addFacts(batch);\n    log(`  Migrated ${Math.min(i + batchSize, sqliteFacts.length)}/${sqliteFacts.length}`);\n  }\n\n  // Validation: count + sample compare (10 random) with NFC normalization.\n  const lanceCount = await lance.countFacts(\"default\");\n  log(`Lance has ${lanceCount} facts (expected ${sqliteFacts.length}).`);\n\n  const sampleSize = Math.min(10, sqliteFacts.length);\n  const sampleComparisons: { id: string; match: boolean }[] = [];\n  for (let i = 0; i < sampleSize; i += 1) {\n    const sqliteFact = sqliteFacts[Math.floor((i * sqliteFacts.length) / sampleSize)];\n    if (sqliteFact === undefined) continue;\n    // Search Lance for this fact's text — best-effort round-trip.\n    const hits = await lance.search(sqliteFact.text, {\n      namespace: sqliteFact.namespace ?? \"default\",\n      limit: 1,\n    });\n    // EC-3: compare with NFC normalization.\n    const hit = hits[0];\n    const match = hit !== undefined && nfcEqual(hit.text, sqliteFact.text);\n    sampleComparisons.push({ id: sqliteFact.id, match });\n  }\n\n  const allMatch = sampleComparisons.every((c) => c.match);\n  const countMatch = lanceCount === sqliteFacts.length;\n  const validated = allMatch && countMatch;\n\n  await lance.close();\n\n  if (opts.dryRun === true) {\n    log(\"Dry-run mode — discarding Lance staging dir.\");\n    rmSync(newPath, { recursive: true, force: true });\n    return {\n      countSqlite: sqliteFacts.length,\n      countLance: lanceCount,\n      validated,\n      sampleComparisons,\n      lancePath: finalPath,\n      committed: false,\n    };\n  }\n\n  if (!validated) {\n    log(\"Validation FAILED — leaving SQLite intact, removing Lance staging dir.\");\n    rmSync(newPath, { recursive: true, force: true });\n    return {\n      countSqlite: sqliteFacts.length,\n      countLance: lanceCount,\n      validated: false,\n      sampleComparisons,\n      lancePath: finalPath,\n      committed: false,\n    };\n  }\n\n  // Atomic commit via rename.\n  renameSync(newPath, finalPath);\n  log(`Migration committed to ${finalPath}.`);\n  return {\n    countSqlite: sqliteFacts.length,\n    countLance: lanceCount,\n    validated: true,\n    sampleComparisons,\n    lancePath: finalPath,\n    committed: true,\n  };\n}\n"]}

package/dist/chunk-7WARNHWW.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/runtime/skills/skill-frontmatter.ts","../src/internal/runtime/skills/discover-skills.ts","../src/internal/runtime/system-prompt/escape.ts","../src/internal/runtime/skills/skills-block.ts"],"names":["ConfigurationError","parseSimpleYaml","readWorkspaceDir","safePathJoin","assertNoSymlinkEscape","join","readFile"],"mappings":"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","file":"chunk-7WARNHWW.cjs","sourcesContent":["import { ConfigurationError } from \"../../../errors.js\";\nimport { type FrontmatterValue, parseSimpleYaml } from \"../context/yaml-frontmatter.js\";\n\ntype StringFields = Record<string, string | undefined>;\n\n/** Narrow a FrontmatterValue to string; non-strings + undefined → undefined. */\nfunction asString(v: FrontmatterValue | undefined): string | undefined {\n  return typeof v === \"string\" ? v : undefined;\n}\n\n/** Coerce parser output to legacy string-only shape (skill schema is all-string). */\nfunction toStringFields(raw: Record<string, FrontmatterValue | undefined>): StringFields {\n  const out: StringFields = {};\n  for (const [k, v] of Object.entries(raw)) out[k] = asString(v);\n  return out;\n}\n\n/**\n * Strict skill frontmatter schema (ADR D10).\n *\n * Required: `name`, `description`.\n * Optional: `category`, `dependencies` (comma-separated string in the\n * simple-YAML dialect — parsed to `string[]`).\n *\n * Unknown fields are ignored (forward-compat). Malformed YAML or missing\n * required fields surface as `ConfigurationError` with one of the typed\n * codes below.\n *\n * @internal\n */\nexport interface SkillFrontmatter {\n  name: string;\n  description: string;\n  category?: string;\n  dependencies?: string[];\n  /**\n   * `disable-model-invocation: true` — the model is not told this skill exists.\n   *\n   * The SDK owns this boundary: a skill reaches the model through exactly one place,\n   * `buildSystemPromptContext`, so the declaration is enforceable here. It is a DISCLOSURE rule,\n   * not an execution rule — `skills.get(name)` still resolves it, because a caller naming a skill\n   * has already made the decision the field exists to keep away from the model.\n   */\n  disableModelInvocation?: boolean;\n  /**\n   * `user-invocable: false` — carried, deliberately not enforced here.\n   *\n   * This SDK has no user-facing invocation surface for skills; there is no slash command. Reading\n   * `agent.skills.list()` as \"the user\" would be a guess — a host may call it to build a picker or\n   * to introspect, and the two want opposite answers. So the declaration travels to the host that\n   * does know, instead of being discarded (the defect) or enforced against an invented boundary.\n   */\n  userInvocable?: boolean;\n}\n\n/**\n * Parse a SKILL.md file body into validated frontmatter.\n *\n * @throws ConfigurationError(code: \"missing_frontmatter\") — no `---` block at file head.\n * @throws ConfigurationError(code: \"schema_invalid\") — YAML malformed OR required field missing.\n *\n * @internal\n */\nexport function parseSkillFrontmatter(raw: string, fallbackName: string): SkillFrontmatter {\n  const parsed = extractAndParseFrontmatter(raw, fallbackName);\n  const fields = toStringFields(parsed);\n  const name = resolveName(fields, fallbackName);\n  ensureRequiredFields(fields, name);\n  return buildFrontmatter(fields, parsed, name);\n}\n\n/**\n * SE20 — return a SKILL.md's BODY (everything after the frontmatter block), trimmed.\n * When there is no frontmatter block, the whole file is the body. Reuses the same\n * frontmatter regex as {@link parseSkillFrontmatter} (DRY).\n */\nexport function stripSkillFrontmatter(raw: string): string {\n  const match = /^---\\s*\\n[\\s\\S]*?\\n---\\s*\\n/.exec(raw);\n  return (match === null ? raw : raw.slice(match[0].length)).trim();\n}\n\nfunction extractAndParseFrontmatter(\n  raw: string,\n  fallbackName: string,\n): Record<string, FrontmatterValue | undefined> {\n  const match = /^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n/.exec(raw);\n  if (match === null) {\n    throw new ConfigurationError(`Skill ${fallbackName} is missing frontmatter`, {\n      code: \"missing_frontmatter\",\n    });\n  }\n  const frontmatter = match[1] ?? \"\";\n  // EC-5: guard against syntactically invalid frontmatter so the loader\n  // surfaces schema_invalid rather than crashing.\n  try {\n    return parseSimpleYaml(frontmatter);\n  } catch (cause) {\n    const detail = cause instanceof Error ? cause.message : String(cause);\n    throw new ConfigurationError(\n      `Skill ${fallbackName} has malformed YAML frontmatter: ${detail}`,\n      { code: \"schema_invalid\", cause },\n    );\n  }\n}\n\nfunction resolveName(fields: StringFields, fallbackName: string): string {\n  if (hasContent(fields.name)) return fields.name;\n  if (hasContent(fallbackName)) return fallbackName;\n  throw new ConfigurationError(\"Skill at unknown path is missing required field: name\", {\n    code: \"schema_invalid\",\n  });\n}\n\nfunction ensureRequiredFields(fields: StringFields, name: string): void {\n  if (!hasContent(fields.description)) {\n    throw new ConfigurationError(`Skill ${name} is missing required field: description`, {\n      code: \"schema_invalid\",\n    });\n  }\n}\n\nfunction buildFrontmatter(\n  fields: StringFields,\n  parsed: Record<string, FrontmatterValue | undefined>,\n  name: string,\n): SkillFrontmatter {\n  const description = fields.description;\n  if (description === undefined) {\n    // ensureRequiredFields already threw; this is unreachable but satisfies TS\n    throw new ConfigurationError(`Skill ${name} missing description`, { code: \"schema_invalid\" });\n  }\n  const result: SkillFrontmatter = { name, description };\n  if (hasContent(fields.category)) result.category = fields.category;\n  const deps = parseDependencies(fields.dependencies);\n  if (deps !== undefined) result.dependencies = deps;\n  const disable = readAuthorizationFlag(parsed, \"disable-model-invocation\", name);\n  if (disable !== undefined) result.disableModelInvocation = disable;\n  const invocable = readAuthorizationFlag(parsed, \"user-invocable\", name);\n  if (invocable !== undefined) result.userInvocable = invocable;\n  return result;\n}\n\n/**\n * Read one boolean authorization flag, refusing a value this parser cannot represent.\n *\n * Unknown frontmatter keys are ignored here for forward compatibility, and that is right for\n * metadata. It is wrong for these two: the simple-YAML dialect coerces only the literals `true`\n * and `false`, so `disable-model-invocation: yes` — a valid YAML boolean — arrives as the STRING\n * `\"yes\"`, compares unequal to `true`, and the skill is disclosed to the model. The author wrote a\n * restriction and got the default.\n *\n * A restriction that fails open is worse than one that is absent, because the author stops looking.\n * So the value is refused and named, and the run stops on the line that caused it.\n */\nfunction readAuthorizationFlag(\n  parsed: Record<string, FrontmatterValue | undefined>,\n  key: string,\n  name: string,\n): boolean | undefined {\n  const value = parsed[key];\n  if (value === undefined) return undefined;\n  if (typeof value === \"boolean\") return value;\n  throw new ConfigurationError(\n    `Skill ${name}: \"${key}\" must be true or false (got ${JSON.stringify(value)}) — ` +\n      `this dialect reads only the literals \\`true\\` and \\`false\\`, and a value it cannot read ` +\n      `would leave the skill disclosed`,\n    { code: \"schema_invalid\" },\n  );\n}\n\nfunction parseDependencies(raw: string | undefined): string[] | undefined {\n  if (!hasContent(raw)) return undefined;\n  const deps = (raw as string)\n    .split(\",\")\n    .map((s) => s.trim())\n    .filter((s) => s.length > 0);\n  return deps.length > 0 ? deps : undefined;\n}\n\nfunction hasContent(value: string | undefined): value is string {\n  return value !== undefined && value.trim().length > 0;\n}\n","import { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { ConfigurationError } from \"../../../errors.js\";\nimport { assertNoSymlinkEscape, safePathJoin } from \"../../security/path-guard.js\";\nimport { readWorkspaceDir } from \"../config/workspace-dir.js\";\nimport { parseSkillFrontmatter, stripSkillFrontmatter } from \"./skill-frontmatter.js\";\n\n/**\n * A discovered skill's metadata. The skill BODY is never included — only the\n * strict frontmatter fields plus the resolved `source` path.\n *\n * Public via `@theokit/sdk/skills`.\n *\n * @public\n */\nexport interface Skill {\n  name: string;\n  description: string;\n  /** Absolute path to the discovered `SKILL.md`. */\n  source: string;\n  category?: string;\n  dependencies?: string[];\n  /** `disable-model-invocation: true` — the model is never told this skill exists. */\n  disableModelInvocation?: boolean;\n  /** `user-invocable: false` — carried for a host that has a picker; this SDK has no such surface. */\n  userInvocable?: boolean;\n}\n\n/**\n * Information passed to `onInvalidSkill` when a `SKILL.md` is present but its\n * frontmatter is malformed (missing required field or invalid YAML).\n *\n * @public\n */\nexport interface InvalidSkillInfo {\n  /** The skill directory name (used as the fallback skill name). */\n  name: string;\n  /** Absolute path to the offending `SKILL.md`. */\n  source: string;\n  /** Typed reason: `missing_frontmatter` or `schema_invalid`. */\n  code: string;\n  message: string;\n}\n\n/**\n * Options for {@link discoverSkills}.\n *\n * @public\n */\nexport interface DiscoverSkillsOptions {\n  /**\n   * Called once per directory that contains a `SKILL.md` with malformed\n   * frontmatter. The skill is excluded from the result; discovery continues\n   * (strict-frontmatter ADR / EC-5). A directory WITHOUT a `SKILL.md` is NOT a\n   * malformed skill and does not trigger this callback.\n   *\n   * Default: no-op (a library primitive must not write to the consumer's\n   * stderr by default).\n   */\n  onInvalidSkill?: (info: InvalidSkillInfo) => void;\n}\n\n/**\n * Discover `SKILL.md` skills under an arbitrary directory.\n *\n * For each immediate subdirectory `<dir>/<name>/` containing a `SKILL.md`, the\n * file's strict YAML frontmatter is parsed (`name`/`description` required;\n * `category`/`dependencies` optional). Malformed skills are skipped (optionally\n * reported via {@link DiscoverSkillsOptions.onInvalidSkill}); a subdirectory\n * whose realpath escapes `dir` (via symlink) is skipped (symlink-escape guard,\n * reusing `@theokit/sdk/path-safety`).\n *\n * NEVER throws: a missing, unreadable, or non-directory `dir` yields `[]`.\n *\n * Discovery order follows the filesystem `readdir` order (OS-dependent). Sort\n * the result before {@link buildSkillsBlock} if a stable block order matters.\n *\n * Public via `@theokit/sdk/skills`.\n *\n * @public\n */\nexport async function discoverSkills(\n  dir: string,\n  options?: DiscoverSkillsOptions,\n): Promise<Skill[]> {\n  let entries: Awaited<ReturnType<typeof readWorkspaceDir>>;\n  try {\n    entries = await readWorkspaceDir(dir, \"skills_read_error\", \"skills directory\");\n  } catch {\n    // never-throw contract: unreadable / not-a-directory → no skills (EC-1)\n    return [];\n  }\n\n  const skills: Skill[] = [];\n  for (const entry of entries) {\n    if (!entry.isDirectory()) continue;\n    let skillDir: string;\n    try {\n      skillDir = safePathJoin(dir, entry.name);\n      assertNoSymlinkEscape(skillDir, dir);\n    } catch {\n      continue;\n    }\n    const skillPath = join(skillDir, \"SKILL.md\");\n    let raw: string;\n    try {\n      raw = await readFile(skillPath, \"utf8\");\n    } catch {\n      // no SKILL.md in this subdir → not a skill, not an error (EC-2)\n      continue;\n    }\n    const skill = tryParseSkill(raw, entry.name, skillPath, options);\n    if (skill !== undefined) skills.push(skill);\n  }\n  return skills;\n}\n\nfunction tryParseSkill(\n  raw: string,\n  fallbackName: string,\n  source: string,\n  options: DiscoverSkillsOptions | undefined,\n): Skill | undefined {\n  try {\n    const frontmatter = parseSkillFrontmatter(raw, fallbackName);\n    const skill: Skill = {\n      name: frontmatter.name,\n      description: frontmatter.description,\n      source,\n    };\n    if (frontmatter.category !== undefined) skill.category = frontmatter.category;\n    if (frontmatter.dependencies !== undefined) skill.dependencies = frontmatter.dependencies;\n    // The authorization flags travel with the record. Dropping them here would reproduce the defect\n    // one layer down: the parser would read the declaration and the discovery result would not\n    // carry it, which is indistinguishable from never having parsed it.\n    if (frontmatter.disableModelInvocation !== undefined) {\n      skill.disableModelInvocation = frontmatter.disableModelInvocation;\n    }\n    if (frontmatter.userInvocable !== undefined) skill.userInvocable = frontmatter.userInvocable;\n    return skill;\n  } catch (cause) {\n    if (cause instanceof ConfigurationError) {\n      options?.onInvalidSkill?.({\n        name: fallbackName,\n        source,\n        code: cause.code ?? \"unknown\",\n        message: cause.message,\n      });\n      return undefined;\n    }\n    throw cause;\n  }\n}\n\n/**\n * Read the BODY of a discovered skill — everything after its frontmatter.\n *\n * A thin selector over {@link discoverSkills} rather than a second reader, which is the same\n * relationship `loadSubagentDefinition` has to `discoverSubagents` in the sibling domain: one\n * parser is the point.\n *\n * ## Why this exists rather than a field on `Skill`\n *\n * `Skill` documents that *\"the skill BODY is never included\"*. That is a written contract with no\n * written reason, and widening it on a guess about the reason is not a trade worth making — a\n * catalog you can put in a prompt without carrying every body is the likely intent, and this keeps\n * that shape intact for whoever relied on it.\n *\n * The body was never expensive to obtain: `discoverSkills` already reads each file in full and\n * discards everything but the frontmatter. What was missing was a door that hands it over.\n *\n * ## What it is for\n *\n * Turning a discovered skill into an inline one — `SkillsSettings.inline` requires `instructions`,\n * and without this the only route was to open `source` and split the frontmatter by hand. That is a\n * second implementation of this module's own convention, and it would fail SILENTLY if the format\n * moved: the frontmatter would land inside the instructions and nothing would say so.\n *\n * Reported by the `theocode` session, which needed exactly that to give an operator's\n * `~/.theokit/skills/` to an agent through the SDK's own parser.\n *\n * @param skill - a record returned by {@link discoverSkills}; its `source` is read.\n * @returns the trimmed body. A file that is all frontmatter yields an empty string.\n * @throws if `source` is unreadable — unlike discovery, which skips what it cannot read, a caller\n *   naming ONE skill has asked about that skill and an empty string would answer a question it did\n *   not ask.\n * @public\n */\nexport async function loadSkillInstructions(skill: Skill): Promise<string> {\n  return stripSkillFrontmatter(await readFile(skill.source, \"utf8\"));\n}\n","/**\n * Block-body XML escape (ADR D9 — prompt-injection defence).\n *\n * Order matters: `&` MUST be escaped first so subsequent `<`/`>` replacements\n * do not double-encode the `&` characters they introduce.\n *\n * @internal\n */\nexport const escapeBlockBody = (s: string): string =>\n  s.replace(/&/g, \"&amp;\").replace(/</g, \"&lt;\").replace(/>/g, \"&gt;\");\n","import { escapeBlockBody } from \"../system-prompt/escape.js\";\n\n/**\n * Render the `<skills>` system-prompt block from a skill list.\n *\n * Input is the structural subset `{ name, description }` — the skill BODY is\n * NOT in the type, so it cannot leak into the prompt. Both fields are passed\n * through `escapeBlockBody` to neutralise prompt-injection vectors hidden in\n * user-controlled SKILL.md frontmatter (injection-escape ADR).\n *\n * Returns `undefined` for an empty list so the caller can omit the block.\n *\n * Public via `@theokit/sdk/skills`.\n *\n * @public\n */\nexport function buildSkillsBlock(\n  skills: ReadonlyArray<{ name: string; description: string }>,\n): string | undefined {\n  if (skills.length === 0) return undefined;\n  const lines = skills.map(\n    (skill) => `  - ${escapeBlockBody(skill.name)}: ${escapeBlockBody(skill.description)}`,\n  );\n  return `<skills>\\n${lines.join(\"\\n\")}\\n</skills>`;\n}\n"]}