@xingular/harness 2.1.1 → 3.0.0

package/src/tree/materialise.ts

@@ -0,0 +1,122 @@
+// Turning a harness tree into what a Pi session receives: always-on prompt sections (c1–c4),
+// the skills folder Pi advertises natively (c6), the scripts folder named in the prompt (c7),
+// subagent definitions (c5), and plugin extensions that are trusted (c8).
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { invalid } from '../core/errors'
+import * as store from './store'
+import { GUARDRAILS, MEMORY, PI_SURFACE, SYSTEM_PROMPT, TOOL_GUIDANCE, patterns, type Tree } from './surface'
+import { readTree } from './tree'
+import type { TreeTrust } from './trust'
+
+/** Where the tree's own sections sit among the application's (identity 10, role 20). */
+export const TREE_SECTION_ORDER = { system: 25, guardrails: 40, memory: 45, subagents: 64, scripts: 66 } as const
+
+/** Which harness a session runs. */
+export type HarnessChoice =
+  /** A scope's head, or one of its versions. */
+  | { scope: string; version?: string | null }
+  /** A tree on disk, such as a refinement candidate. It is read, never written. */
+  | { dir: string; scope?: string | null }
+
+export interface SubagentDefinition {
+  name: string
+  description: string
+  instructions: string
+}
+
+export interface Materialised {
+  scope: string | null
+  /** The fingerprint of the tree that ran. */
+  fingerprint: string
+  /** The tree's folder; scripts and skills are read from it in place. */
+  dir: string
+  tree: Tree
+  sections: { id: string; title: string; body: string; order: number }[]
+  /** The tool guidance, added after the tool groups. */
+  toolGuidance: string
+  skillPaths: string[]
+  extensionPaths: string[]
+  /** Plugin files that did not load because their code is not trusted. */
+  untrustedPlugins: string[]
+  subagents: SubagentDefinition[]
+}
+
+function frontmatter(text: string, field: string): string | null {
+  const m = new RegExp(`^${field}:\\s*(.+)$`, 'm').exec(text.slice(0, 600))
+  return m?.[1]?.trim() ?? null
+}
+
+function bodyAfterFrontmatter(text: string): string {
+  const m = /^---\n[\s\S]*?\n---\n?/.exec(text)
+  return (m ? text.slice(m[0].length) : text).trim()
+}
+
+/** Finds the tree a choice names. */
+export function resolve(root: string, choice: HarnessChoice): { scope: string | null; dir: string; fingerprint: string; tree: Tree } {
+  if ('dir' in choice) {
+    if (!existsSync(choice.dir)) throw invalid('That harness folder does not exist.')
+    const tree = readTree(PI_SURFACE, choice.dir)
+    return { scope: choice.scope ?? null, dir: choice.dir, fingerprint: store.fingerprint(tree), tree }
+  }
+  const fp = choice.version ?? store.head(root, choice.scope)?.fingerprint
+  if (!fp) throw invalid(`The harness '${choice.scope}' has no version yet.`)
+  const dir = store.versionPath(root, choice.scope, fp)
+  return { scope: choice.scope, dir, fingerprint: fp, tree: store.readVersion(root, choice.scope, fp) }
+}
+
+export interface MaterialiseOptions {
+  trust?: TreeTrust | null
+  /** Load improver-written plugin code without trust (refinement probes, when the person allowed it). */
+  probeCode?: boolean
+  /** Whether the session can start subagents; when it cannot, c5 is not described. */
+  subagents?: boolean
+}
+
+export function materialise(root: string, choice: HarnessChoice, options: MaterialiseOptions = {}): Materialised {
+  const { scope, dir, fingerprint, tree } = resolve(root, choice)
+  const r = patterns(PI_SURFACE)
+  const sections: Materialised['sections'] = []
+  const add = (id: string, title: string, body: string | undefined, order: number) => {
+    if (body?.trim()) sections.push({ id, title, body: body.trim(), order })
+  }
+  add('system', 'Instructions', tree[SYSTEM_PROMPT], TREE_SECTION_ORDER.system)
+  add('guardrails', 'Guardrails', tree[GUARDRAILS], TREE_SECTION_ORDER.guardrails)
+  add('memory', 'Memory', tree[MEMORY], TREE_SECTION_ORDER.memory)
+
+  const subagents: SubagentDefinition[] = []
+  for (const rel of Object.keys(tree).sort()) {
+    const m = r.subagent.exec(rel)
+    if (!m) continue
+    const text = tree[rel]!
+    subagents.push({ name: m[1]!, description: frontmatter(text, 'description') ?? '', instructions: bodyAfterFrontmatter(text) })
+  }
+  if (subagents.length && options.subagents !== false) {
+    add('subagents', 'Subagents', `Start one with spawn_subagent and agent set to its name. Each works in its own context and returns text.\n${subagents.map((agent) => `- ${agent.name} — ${agent.description}`).join('\n')}`, TREE_SECTION_ORDER.subagents)
+  }
+
+  const scripts = Object.keys(tree).filter((rel) => r.script.test(rel)).map((rel) => rel.slice('scripts/'.length)).sort()
+  if (scripts.length) {
+    add('scripts', 'Scripts', `Your helper scripts are in ${join(dir, 'scripts')}: ${scripts.join(', ')}. Run a .py one with python3 and a .mjs one with node, giving its full path. When instructions say \`scripts/<name>\`, they mean this folder.`, TREE_SECTION_ORDER.scripts)
+  }
+
+  const skillPaths = existsSync(join(dir, 'skills')) && readdirSync(join(dir, 'skills')).length ? [join(dir, 'skills')] : []
+  const extensionPaths: string[] = []
+  const untrustedPlugins: string[] = []
+  for (const rel of Object.keys(tree).filter((path) => r.plugin.test(path)).sort()) {
+    const trusted = options.trust?.has((options.trust.review({ [rel]: tree[rel]! })[0]?.hash) ?? '') ?? false
+    if (trusted || options.probeCode) extensionPaths.push(join(dir, rel))
+    else untrustedPlugins.push(rel)
+  }
+  return { scope, fingerprint, dir, tree, sections, toolGuidance: (tree[TOOL_GUIDANCE] ?? '').trim(), skillPaths, extensionPaths, untrustedPlugins, subagents }
+}
+
+/** One subagent's definition from the tree a run used. */
+export function subagentOf(dir: string, name: string): SubagentDefinition | null {
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) return null
+  const path = join(dir, 'sub_agents', name, 'AGENT.md')
+  if (!existsSync(path)) return null
+  const text = readFileSync(path, 'utf8')
+  return { name, description: frontmatter(text, 'description') ?? '', instructions: bodyAfterFrontmatter(text) }
+}

package/src/tree/seed.ts

@@ -0,0 +1,123 @@
+// A first harness tree for a caller that had none, built from what shaped it before harness
+// trees existed: its instructions (c1), the rules switched on for it (c2), its memory blocks and
+// the person's own block (c3), and the skills switched on for it (c6). Read straight from the
+// files an earlier harness left in the data root; nothing there is changed.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import * as frontmatter from '../core/frontmatter'
+import * as attachments from '../plugins/attachments'
+import { GUARDRAILS, MEMORY, PI_SURFACE, SYSTEM_PROMPT, TOOL_GUIDANCE, type Tree } from './surface'
+import { alwaysOnText, autotrigger, validate } from './tree'
+
+export interface SeedInput {
+  /** The caller whose rules, skills and memory blocks to carry over. */
+  agentId?: string | null
+  projectId?: string | null
+  /** The caller's own instructions. */
+  instructions?: string
+}
+
+function body(text: string): string {
+  return (frontmatter.parse(text)?.body ?? text).trim()
+}
+
+function read(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+function folders(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((name) => !name.startsWith('.')).sort()
+  } catch {
+    return []
+  }
+}
+
+/** Where an earlier Wiki kept memory blocks: in place, or where they were moved aside. */
+function blocksDir(root: string): string | null {
+  if (existsSync(join(root, 'wiki', 'blocks'))) return join(root, 'wiki', 'blocks')
+  const moved = folders(join(root, 'legacy')).filter((name) => name.startsWith('wiki-')).reverse()
+  for (const name of moved) if (existsSync(join(root, 'legacy', name, 'blocks'))) return join(root, 'legacy', name, 'blocks')
+  return null
+}
+
+function skillName(stem: string): string {
+  return stem.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[-_]+|-+$/g, '').slice(0, 64) || 'skill'
+}
+
+/** The legacy pieces for a caller, before they are put together. */
+export function legacyPieces(root: string, input: SeedInput): { rules: string[]; skills: Record<string, string>; memory: string[] } {
+  const choices = attachments.load(root)
+  const scope = { agentId: input.agentId ?? null, projectId: input.projectId ?? null }
+  const on = (id: string) => attachments.attached(choices, [id], scope, false)
+
+  const rules: string[] = []
+  const rulesDir = join(root, 'registry', 'rules')
+  for (const name of folders(rulesDir)) {
+    const stem = name.replace(/\.md$/, '')
+    const path = name.endsWith('.md') ? join(rulesDir, name) : join(rulesDir, name, 'SKILL.md')
+    const text = read(path)
+    if (text && on(`rules/${stem}`)) rules.push(body(text))
+  }
+
+  const skills: Record<string, string> = {}
+  const skillsDir = join(root, 'registry', 'skills')
+  for (const name of folders(skillsDir)) {
+    const stem = name.replace(/\.md$/, '')
+    let path = join(skillsDir, name)
+    try {
+      if (statSync(path).isDirectory()) path = join(path, 'SKILL.md')
+    } catch {
+      continue
+    }
+    const text = read(path)
+    if (!text || !on(`skills/${stem}`)) continue
+    const slug = skillName(stem)
+    const parsed = frontmatter.parse(text)
+    const description = typeof parsed?.front.description === 'string' && parsed.front.description.trim() ? parsed.front.description.trim() : `the ${slug} workflow applies`
+    skills[`skills/${slug}/SKILL.md`] = `---\nname: ${slug}\ndescription: ${description.replace(/\n/g, ' ')}\n---\n${body(text)}\n`
+  }
+
+  const memory: string[] = []
+  const blocks = blocksDir(root)
+  if (blocks) {
+    const user = read(join(blocks, 'shared', 'user.md'))
+    if (user && body(user)) memory.push(`## About the person\n\n${body(user)}`)
+    if (input.agentId && /^[A-Za-z0-9_-]+$/.test(input.agentId)) {
+      for (const [file, title] of [['persona.md', 'Persona'], ['notes.md', 'Notes']] as const) {
+        const text = read(join(blocks, 'agents', input.agentId, file))
+        if (text && body(text)) memory.push(`## ${title}\n\n${body(text)}`)
+      }
+    }
+  }
+  return { rules, skills, memory }
+}
+
+/**
+ * Builds a valid seed tree. Rules become guardrails, blocks become memory, and every skill gets a
+ * trigger line. When the always-on text would be over the cap, memory is shortened first, then
+ * guardrails; nothing else is dropped.
+ */
+export function seedTree(root: string, input: SeedInput): Tree {
+  const pieces = legacyPieces(root, input)
+  const tree: Tree = {
+    [SYSTEM_PROMPT]: (input.instructions ?? '').trim() ? `${input.instructions!.trim()}\n` : '',
+    [GUARDRAILS]: pieces.rules.length ? `${pieces.rules.join('\n\n')}\n` : '',
+    [MEMORY]: pieces.memory.length ? `${pieces.memory.join('\n\n')}\n` : '',
+    [TOOL_GUIDANCE]: '',
+    ...pieces.skills
+  }
+  const cap = PI_SURFACE.alwaysOnMax - 2_000
+  for (const rel of [MEMORY, GUARDRAILS, SYSTEM_PROMPT]) {
+    const over = alwaysOnText(PI_SURFACE, tree).length - cap
+    if (over > 0) tree[rel] = `${tree[rel]!.slice(0, Math.max(0, tree[rel]!.length - over - 40)).trimEnd()}\n\n(Shortened when this harness was created.)\n`
+  }
+  autotrigger(PI_SURFACE, tree)
+  validate(PI_SURFACE, tree, { compileScripts: false })
+  return tree
+}

package/src/tree/store.ts

@@ -0,0 +1,193 @@
+// Versioned harness trees. Each scope (an opaque id the application chooses, such as one per
+// agent) has content-addressed versions, a head, and a lineage that says where each version came
+// from. A run uses the head it started with; a change makes a new version and never edits one.
+//
+//   <data>/harnesses/<scope>/versions/<fingerprint>/tree/<rel>
+//   <data>/harnesses/<scope>/versions/<fingerprint>/version.json
+//   <data>/harnesses/<scope>/head.json
+//   <data>/harnesses/<scope>/lineage.jsonl
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { HarnessError, invalid, notFound } from '../core/errors'
+import { appendLine, now, readJson, readText, safeId, writeJson } from '../core/fs'
+import { PI_SURFACE, type SurfaceSpec, type Tree } from './surface'
+import { diffSummary, readTree, validate, writeTree, type TreeCensus, type TreeDiff, type ValidateOptions } from './tree'
+
+/** A stable digest of a tree: the same files with the same text give the same value. */
+export function fingerprint(tree: Tree): string {
+  const hash = createHash('sha1')
+  for (const rel of Object.keys(tree).sort()) {
+    hash.update(rel)
+    hash.update('\0')
+    hash.update(tree[rel]!)
+    hash.update('\0')
+  }
+  return hash.digest('hex').slice(0, 16)
+}
+
+export type VersionSource =
+  | { kind: 'seed'; note?: string }
+  | { kind: 'edit'; note?: string; components?: string[] }
+  | { kind: 'refinement'; refineId: string; label: string; note?: string }
+  | { kind: 'import'; note?: string }
+  | { kind: 'restore'; from: string; note?: string }
+
+export interface VersionRecord {
+  fingerprint: string
+  parent: string | null
+  source: VersionSource
+  createdAt: string
+  census: TreeCensus
+}
+
+export interface Head {
+  fingerprint: string
+  updatedAt: string
+}
+
+export function harnessesDir(root: string): string {
+  return join(root, 'harnesses')
+}
+
+function scopeDir(root: string, scope: string): string {
+  return join(harnessesDir(root), safeId(scope))
+}
+
+function versionDir(root: string, scope: string, fp: string): string {
+  if (!/^[0-9a-f]{16}$/.test(fp)) throw invalid('Invalid harness version.')
+  return join(scopeDir(root, scope), 'versions', fp)
+}
+
+export function scopes(root: string): string[] {
+  try {
+    return readdirSync(harnessesDir(root), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort()
+  } catch {
+    return []
+  }
+}
+
+export function head(root: string, scope: string): Head | null {
+  return readJson<Head>(join(scopeDir(root, scope), 'head.json'))
+}
+
+export function exists(root: string, scope: string, fp: string): boolean {
+  return existsSync(join(versionDir(root, scope, fp), 'version.json'))
+}
+
+export function readVersion(root: string, scope: string, fp: string, surface: SurfaceSpec = PI_SURFACE): Tree {
+  const dir = join(versionDir(root, scope, fp), 'tree')
+  if (!existsSync(dir)) throw notFound('That harness version')
+  return readTree(surface, dir)
+}
+
+export function versionRecord(root: string, scope: string, fp: string): VersionRecord | null {
+  return readJson<VersionRecord>(join(versionDir(root, scope, fp), 'version.json'))
+}
+
+/** Where a version's files are on disk, for a run that loads them. */
+export function versionPath(root: string, scope: string, fp: string): string {
+  return join(versionDir(root, scope, fp), 'tree')
+}
+
+/** The head tree, or null when the scope has none yet. */
+export function headTree(root: string, scope: string, surface: SurfaceSpec = PI_SURFACE): { fingerprint: string; tree: Tree } | null {
+  const current = head(root, scope)
+  return current ? { fingerprint: current.fingerprint, tree: readVersion(root, scope, current.fingerprint, surface) } : null
+}
+
+/** Every version recorded for a scope, newest first. */
+export function lineage(root: string, scope: string): VersionRecord[] {
+  const text = readText(join(scopeDir(root, scope), 'lineage.jsonl')) ?? ''
+  const out: VersionRecord[] = []
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      out.push(JSON.parse(line) as VersionRecord)
+    } catch {
+      // A torn final line is skipped; the version files are the record.
+    }
+  }
+  return out.reverse()
+}
+
+export interface CommitOptions {
+  /** Move the head to the new version (the default). */
+  moveHead?: boolean
+  surface?: SurfaceSpec
+  validate?: ValidateOptions
+}
+
+/**
+ * Saves `tree` as a version of `scope`. An invalid tree is refused with every problem listed.
+ * Saving a tree that already exists records nothing new but can still move the head.
+ */
+export function commit(root: string, scope: string, tree: Tree, source: VersionSource, options: CommitOptions = {}): VersionRecord {
+  const surface = options.surface ?? PI_SURFACE
+  let census: TreeCensus
+  try {
+    census = validate(surface, tree, options.validate)
+  } catch (error) {
+    throw new HarnessError('harness_invalid', error instanceof Error ? error.message : String(error), 'Fix the listed problems and save again.')
+  }
+  const fp = fingerprint(tree)
+  const parent = head(root, scope)?.fingerprint ?? null
+  let record = versionRecord(root, scope, fp)
+  if (!record) {
+    writeTree(surface, tree, join(versionDir(root, scope, fp), 'tree'), { stubs: false })
+    record = { fingerprint: fp, parent, source, createdAt: now(), census }
+    writeJson(join(versionDir(root, scope, fp), 'version.json'), record)
+    appendLine(join(scopeDir(root, scope), 'lineage.jsonl'), JSON.stringify(record))
+  }
+  if (options.moveHead !== false) writeJson(join(scopeDir(root, scope), 'head.json'), { fingerprint: fp, updatedAt: now() } satisfies Head)
+  return record
+}
+
+/** Gives a scope its first version, unless it already has a head. */
+export function seed(root: string, scope: string, tree: Tree, note?: string, surface: SurfaceSpec = PI_SURFACE): Head {
+  const current = head(root, scope)
+  if (current) return current
+  commit(root, scope, tree, { kind: 'seed', note }, { surface })
+  return head(root, scope)!
+}
+
+/** Points the head at an earlier version. The version must exist. */
+export function restore(root: string, scope: string, fp: string, note?: string): Head {
+  if (!exists(root, scope, fp)) throw notFound('That harness version')
+  const from = head(root, scope)?.fingerprint ?? fp
+  writeJson(join(scopeDir(root, scope), 'head.json'), { fingerprint: fp, updatedAt: now() } satisfies Head)
+  appendLine(join(scopeDir(root, scope), 'restores.jsonl'), JSON.stringify({ to: fp, from, note: note ?? null, at: now() }))
+  return head(root, scope)!
+}
+
+export interface FileDiff {
+  path: string
+  before: string | null
+  after: string | null
+}
+
+/** What changed between two versions, file by file. */
+export function compare(root: string, scope: string, from: string, to: string, surface: SurfaceSpec = PI_SURFACE): { summary: TreeDiff; files: FileDiff[] } {
+  const a = readVersion(root, scope, from, surface)
+  const b = readVersion(root, scope, to, surface)
+  const summary = diffSummary(surface, a, b)
+  const files = [...summary.added, ...summary.removed, ...summary.modified].sort().map((path) => ({ path, before: a[path] ?? null, after: b[path] ?? null }))
+  return { summary, files }
+}
+
+/** Reads a tree folder made outside the harness, such as an export or a hand-written one. */
+export function importFolder(dir: string, surface: SurfaceSpec = PI_SURFACE): { tree: Tree; rejected: string[] } {
+  const rejected: string[] = []
+  const tree = readTree(surface, dir, rejected)
+  return { tree, rejected }
+}
+
+/** Reads one file of a tree on disk; used by callers that only need one component. */
+export function readComponentFile(root: string, scope: string, fp: string, rel: string): string | null {
+  try {
+    return readFileSync(join(versionPath(root, scope, fp), rel), 'utf8')
+  } catch {
+    return null
+  }
+}

package/src/tree/surface.ts

@@ -0,0 +1,135 @@
+// The editable surface of a harness: the eight components a person or an improver may change,
+// where each lives in the tree, and the rules that keep a tree loadable by Pi.
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/core/tree.py`, `SurfaceSpec`). The
+// component numbering c1..c8 follows the paper: system prompt, guardrails, memory, tool
+// guidance, subagents, skills, scripts and plugins.
+
+/** A harness: relative path → file text, for every file on the editable surface. */
+export type Tree = Record<string, string>
+
+export type ComponentId = 'systemPrompt' | 'guardrails' | 'memory' | 'toolGuidance' | 'subagents' | 'skills' | 'scripts' | 'plugins'
+
+/** How a component reaches a run, grouped as the paper groups them. */
+export type ComponentGroup = 'context' | 'toolInterface' | 'orchestration' | 'middleware'
+
+export interface ComponentInfo {
+  id: ComponentId
+  /** c1..c8, as numbered in the paper. */
+  index: number
+  title: string
+  group: ComponentGroup
+  /** Where it lives: a file for an always-on component, a pattern for the others. */
+  path: string
+  /** When it is in a run's context. */
+  reach: 'always' | 'onDemand' | 'ownContext' | 'toolLoop'
+  description: string
+}
+
+export interface SurfaceSpec {
+  name: string
+  /** Files whose whole text is in every run's prompt. */
+  alwaysOn: readonly string[]
+  /** The most always-on characters a tree may carry. */
+  alwaysOnMax: number
+  alwaysOnCapReason: string
+  skillDir: string
+  /** Pi drops a skill whose frontmatter `name` differs from its folder. */
+  skillNameRule: 'must_match' | 'overrides_dir'
+  triggerHint: string
+  autotriggerFile: string
+  triggerLine: string
+  subagentDir: string
+  scriptDir: string
+  /** Script file extensions the surface accepts. */
+  scriptExtensions: readonly string[]
+  pluginDir: string
+  /** Short README files written beside each directory so an editor knows the form. */
+  stubs: readonly (readonly [string, string])[]
+  components: readonly ComponentInfo[]
+}
+
+export const SYSTEM_PROMPT = 'systemprompt.md'
+export const GUARDRAILS = 'guardrails.md'
+export const MEMORY = 'memory.md'
+export const TOOL_GUIDANCE = 'tool_guidance.md'
+
+/** The Pi surface: the one surface this harness runs. */
+export const PI_SURFACE: SurfaceSpec = {
+  name: 'pi',
+  alwaysOn: [SYSTEM_PROMPT, GUARDRAILS, MEMORY, TOOL_GUIDANCE],
+  alwaysOnMax: 24_000,
+  alwaysOnCapReason: 'every token here competes with the agent\'s own output budget on every run',
+  skillDir: 'skills',
+  skillNameRule: 'must_match',
+  triggerHint: 'Fix it by adding a trigger line naming `{name}` to systemprompt.md or guardrails.md, e.g. "When <the situation this skill handles>, load the `{name}` skill."',
+  autotriggerFile: GUARDRAILS,
+  triggerLine: '- When {desc}, load the `{name}` skill.',
+  subagentDir: 'sub_agents',
+  scriptDir: 'scripts',
+  scriptExtensions: ['.py', '.mjs'],
+  pluginDir: 'plugins',
+  stubs: [
+    ['scripts/README.md', '<!-- c7: deterministic helpers. Add one as scripts/<name>.py or scripts/<name>.mjs; the prompt names the folder they are staged in. -->\n'],
+    ['sub_agents/README.md', '<!-- c5: delegated subagents, started with `spawn_subagent` and `agent: "<name>"`, each in its OWN context. Add one as sub_agents/<name>/AGENT.md with a `description:` in its frontmatter. -->\n'],
+    ['plugins/README.md', '<!-- c8: Pi extensions. They act INSIDE the tool loop -- the only lever that can enforce something the model cannot skip. Add one as plugins/<name>.ts with a default export. New or changed code waits for the person to trust it. -->\n'],
+    ['skills/README.md', '<!-- c6: reusable workflows loaded on demand. Add one as skills/<name>/SKILL.md with frontmatter `name:` matching the folder and a `description:`. -->\n']
+  ],
+  components: [
+    { id: 'systemPrompt', index: 1, title: 'System prompt', group: 'context', path: SYSTEM_PROMPT, reach: 'always', description: 'Role and procedure.' },
+    { id: 'guardrails', index: 2, title: 'Guardrails', group: 'context', path: GUARDRAILS, reach: 'always', description: 'Standing rules the agent keeps on every run.' },
+    { id: 'memory', index: 3, title: 'Memory', group: 'context', path: MEMORY, reach: 'always', description: 'Durable, general facts about this kind of work.' },
+    { id: 'toolGuidance', index: 4, title: 'Tool guidance', group: 'toolInterface', path: TOOL_GUIDANCE, reach: 'always', description: 'How to use the tools well.' },
+    { id: 'subagents', index: 5, title: 'Subagents', group: 'orchestration', path: 'sub_agents/<name>/AGENT.md', reach: 'ownContext', description: 'Bounded helpers that run in their own context and return text.' },
+    { id: 'skills', index: 6, title: 'Skills', group: 'context', path: 'skills/<name>/SKILL.md', reach: 'onDemand', description: 'Reusable workflows loaded when a situation matches.' },
+    { id: 'scripts', index: 7, title: 'Scripts', group: 'toolInterface', path: 'scripts/<name>.py', reach: 'onDemand', description: 'Deterministic helpers the agent runs.' },
+    { id: 'plugins', index: 8, title: 'Plugins', group: 'middleware', path: 'plugins/<name>.ts', reach: 'toolLoop', description: 'Pi extensions that act inside the tool loop.' }
+  ]
+}
+
+const NAME = '[a-z0-9][a-z0-9_\\-]*'
+
+export interface SurfacePatterns {
+  skill: RegExp
+  skillScript: RegExp
+  subagent: RegExp
+  script: RegExp
+  scriptRef: RegExp
+  plugin: RegExp
+}
+
+const cache = new Map<string, SurfacePatterns>()
+
+function escape(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+export function patterns(surface: SurfaceSpec): SurfacePatterns {
+  const known = cache.get(surface.name)
+  if (known) return known
+  const skills = escape(surface.skillDir)
+  const scripts = escape(surface.scriptDir)
+  const extensions = surface.scriptExtensions.map((extension) => escape(extension.slice(1))).join('|')
+  const made: SurfacePatterns = {
+    skill: new RegExp(`^${skills}/(${NAME})/SKILL\\.md$`),
+    skillScript: new RegExp(`^${skills}/${NAME}/scripts/[A-Za-z0-9_.\\-]+$`),
+    subagent: new RegExp(`^${escape(surface.subagentDir)}/(${NAME})/AGENT\\.md$`),
+    script: new RegExp(`^${scripts}/[a-z0-9_][a-z0-9_]*\\.(?:${extensions})$`),
+    scriptRef: new RegExp(`(?:python3?|node)\\s+((?:${skills}/[\\w\\-]+/)?${scripts}/[\\w.\\-]+\\.(?:${extensions}))`, 'g'),
+    plugin: new RegExp(`^${escape(surface.pluginDir)}/(${NAME})\\.ts$`)
+  }
+  cache.set(surface.name, made)
+  return made
+}
+
+/** Which component a path belongs to, or null when it is off the surface. */
+export function componentOf(surface: SurfaceSpec, rel: string): ComponentId | null {
+  const found = surface.components.find((component) => component.path === rel)
+  if (found) return found.id
+  const r = patterns(surface)
+  if (r.skill.test(rel) || r.skillScript.test(rel)) return 'skills'
+  if (r.subagent.test(rel)) return 'subagents'
+  if (r.script.test(rel)) return 'scripts'
+  if (r.plugin.test(rel)) return 'plugins'
+  return null
+}