Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
// The ⌘M composer's `/` catalog for one node: the agent's measured built-ins
// (@shared/chat-catalog), custom command files and SKILL.md skills — read from THIS machine's disk
// for a local node, or from the node's HOST in ONE ssh round trip for an SSH-project node. Served
// by `chat:catalog` in both shells (registerChatCatalogIpc); the phone gets the same catalog as an
// optional field on `chat.status`.
//
// Where each agent looks (measured 2026-09-30, see docs):
// - claude: `<configDir>/commands/**/*.md` and `<cwd>/.claude/commands/**/*.md` (a subfolder is a
// `dir:name` namespace; the description is the frontmatter `description`, else the first body
// line), and `<configDir>/skills/*/SKILL.md` + `<cwd>/.claude/skills/*/SKILL.md` (the name is the
// frontmatter `name`, else the folder; `user-invocable: false` hides it). `<configDir>` is the
// managed or linked account's dir when the node is bound to one — it REPLACES `~/.claude`, it
// does not add to it — else `~/.claude`.
// Locally also (measured 2026-11-05 on 2.1.318, see `claudeLocalExtras`): the skills claude.ai
// syncs to `<configDir>/skills/synced/<bucket>/<name>/SKILL.md` (listed as `/<name>`), and every
// ENABLED plugin's skills and commands (listed as `/<plugin>:<name>`), and `skillOverrides` "off"
// hides a user, project or synced skill.
// - gemini: `~/.gemini/commands/**/*.toml` and `<cwd>/.gemini/commands/**/*.toml` (the shipped
// custom-commands reference: subfolders are `:` namespaces, `description` is optional).
// - every other agent: built-ins only. Their custom-command and skill locations were not measured,
// and a guessed location lists commands the CLI does not have.
//
// Cost: nothing is polled. A read happens when a composer asks (the first `/` of a composer mount,
// then again only after the renderer's short freshness window). Locally every directory listing is
// cached by the directory's mtime and every file head by (mtime, size), so an unchanged tree costs
// one `stat` per entry and no reads.
import { constants as fsConstants, promises as fsp } from 'fs'
import os from 'os'
import path from 'path'
import { IPC } from '../shared/ipc'
import { capabilityAgentId } from '../shared/agents/config'
import {
CHAT_CATALOG_MAX_ENTRIES,
builtinSlashCommands,
catalogDescription,
catalogName,
mergeCatalogEntries,
type ChatCatalog,
type ChatCatalogEntry,
type ChatCatalogScope
} from '../shared/chat-catalog'
import { posixQuote, quoteRemotePath } from '../shared/ssh'
import { platform } from './platform'
import { claudeConfigDirFor } from './claude-config-dir'
import { isSafeAccountId, remoteAccountConfigDir } from './claude-accounts-core'
/** Per root: at most this many files are looked at, this deep, this much of each is read. */
export const CATALOG_ROOT_MAX_FILES = 200
export const CATALOG_COMMAND_MAX_DEPTH = 3
export const CATALOG_HEAD_BYTES = 4096
// `skills` = a SKILL.md in each folder of `dir`; `skill-dir` = `dir` itself is one skill folder (a
// plugin manifest may list skill folders one by one); `synced-skills` = `dir/<bucket>/<name>/SKILL.md`
// (claude.ai's sync).
export type CatalogRootKind = 'md-commands' | 'toml-commands' | 'skills' | 'skill-dir' | 'synced-skills'
export interface CatalogRoot {
kind: CatalogRootKind
scope: Exclude<ChatCatalogScope, 'builtin'>
/** A local absolute path, or (remote) a path the remote shell resolves — `~/…` or absolute. */
dir: string
/**
* PROJECT roots only: the node's cwd. A project's command and skill folders are whatever the
* repository holds, and a symlink committed there (`notes.md -> ~/.git-credentials`) would put the
* first line of a file OUTSIDE the project into the menu — and into the phone's catalog. So for a
* project root no symlink is followed at any level (entries are lstat'ed, files opened
* O_NOFOLLOW; remotely `find -P` and `[ -L ]`), and the root itself must resolve inside `within`.
* User roots (the person's own config dir) are followed: that is how shared system skills reach
* an account dir.
*/
within?: string
/** A plugin's name: every entry of the root is listed as `<prefix>:<name>`. */
prefix?: string
/** `skillOverrides` "off" may hide this root's skills. Measured: it hides a user, project or synced
* skill and has no effect on a plugin's. */
overridable?: boolean
}
export interface ChatCatalogQuery {
agentId: string | undefined
accountId: string | undefined
cwd: string | undefined
}
/** Claude's config dir for a node: the bound account's dir, else `~/.claude`. Null for an account id
* that is not safe or not known — never the system dir in its place, which would list another
* identity's commands under this node. */
function claudeCatalogConfigDir(accountId: string | undefined, opts: { remote: boolean; home: string }): string | null {
if (accountId === undefined || accountId === '') return opts.remote ? '~/.claude' : path.join(opts.home, '.claude')
if (!isSafeAccountId(accountId)) return null
if (opts.remote) return remoteAccountConfigDir(accountId)
try {
return claudeConfigDirFor(accountId)
} catch {
return null
}
}
/** The roots a node's agent reads, in PRECEDENCE order (project before user). */
export function catalogRoots(q: ChatCatalogQuery, opts: { remote: boolean; home?: string }): CatalogRoot[] {
const base = q.agentId ? capabilityAgentId(q.agentId) : ''
const home = opts.home ?? os.homedir()
const cwd = typeof q.cwd === 'string' && q.cwd.trim() ? q.cwd : undefined
const join = (a: string, ...b: string[]) => (opts.remote ? [a.replace(/\/+$/, ''), ...b].join('/') : path.join(a, ...b))
const roots: CatalogRoot[] = []
if (base === 'claude') {
const configDir = claudeCatalogConfigDir(q.accountId, { remote: opts.remote, home })
if (cwd) {
roots.push({ kind: 'md-commands', scope: 'project', dir: join(cwd, '.claude', 'commands'), within: cwd })
roots.push({ kind: 'skills', scope: 'project', dir: join(cwd, '.claude', 'skills'), within: cwd, overridable: true })
}
if (configDir) {
roots.push({ kind: 'md-commands', scope: 'user', dir: join(configDir, 'commands') })
roots.push({ kind: 'skills', scope: 'user', dir: join(configDir, 'skills'), overridable: true })
}
} else if (base === 'gemini') {
if (cwd) roots.push({ kind: 'toml-commands', scope: 'project', dir: join(cwd, '.gemini', 'commands'), within: cwd })
roots.push({ kind: 'toml-commands', scope: 'user', dir: opts.remote ? '~/.gemini/commands' : path.join(home, '.gemini', 'commands') })
}
return roots
}
// ── Parsers (pure) ──────────────────────────────────────────────────────────────────────────────
/** `---` frontmatter as flat `key: value` pairs (quotes stripped) plus the body after it. Only the
* scalar keys the catalog reads are meaningful; anything nested is ignored, never interpreted. */
export function parseFrontmatter(text: string): { fields: Record<string, string>; body: string } {
const t = text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n')
const fields: Record<string, string> = Object.create(null)
if (!t.startsWith('---\n')) return { fields, body: t }
const end = t.indexOf('\n---', 4)
if (end < 0) return { fields, body: t }
for (const line of t.slice(4, end).split('\n')) {
const m = /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line)
if (!m) continue
let v = m[2].trim()
if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1)
// YAML's single-quoted scalar escapes a quote by doubling it (`'the project''s build'`).
else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1).replace(/''/g, "'")
fields[m[1].toLowerCase()] = v
}
const after = t.indexOf('\n', end + 1)
return { fields, body: after < 0 ? '' : t.slice(after + 1) }
}
function firstBodyLine(body: string): string {
for (const line of body.split('\n')) {
const s = line.replace(/^#+\s*/, '').trim()
if (s) return s
}
return ''
}
/** `git/commit.md` → `git:commit`. Null when any segment is not a typeable name. A `SKILL.md` inside
* a claude commands folder names its FOLDER (`review/SKILL.md` → `review`, measured against the
* 2.1.285 loader: a file matching `skill.md`, any case, takes the joined folder path); one at the
* top of the root has no folder and is no command. */
export function commandNameFromRel(rel: string, ext: '.md' | '.toml'): string | null {
const norm = rel.replace(/\\/g, '/')
if (!norm.toLowerCase().endsWith(ext)) return null
if (ext === '.md' && /(^|\/)skill\.md$/i.test(norm)) {
const dirs = norm.split('/').slice(0, -1)
if (!dirs.length || dirs.some((p) => !p || p === '.' || p === '..')) return null
return catalogName(dirs.join(':'))
}
const parts = norm.slice(0, -ext.length).split('/')
if (parts.some((p) => !p || p === '.' || p === '..')) return null
return catalogName(parts.join(':'))
}
export function markdownCommandEntry(rel: string, text: string, scope: CatalogRoot['scope']): ChatCatalogEntry | null {
const name = commandNameFromRel(rel, '.md')
if (!name) return null
const { fields, body } = parseFrontmatter(text)
return { name, description: catalogDescription(fields.description || firstBodyLine(body)), kind: 'command', scope }
}
export function skillEntry(dirName: string, text: string, scope: CatalogRoot['scope']): ChatCatalogEntry | null {
const { fields } = parseFrontmatter(text)
if ((fields['user-invocable'] ?? '').toLowerCase() === 'false') return null
const name = catalogName(fields.name || dirName)
if (!name) return null
return { name, description: catalogDescription(fields.description), kind: 'skill', scope }
}
/** The one TOML field read: a single-line `description = "…"` (or '…'). Anything else — a
* multi-line string, an escape we do not model — degrades to no description, never a guess. */
export function tomlCommandEntry(rel: string, text: string, scope: CatalogRoot['scope']): ChatCatalogEntry | null {
const name = commandNameFromRel(rel, '.toml')
if (!name) return null
const m = /^\s*description\s*=\s*(?:"((?:[^"\\\n]|\\.)*)"|'([^'\n]*)')\s*$/m.exec(text.replace(/\r\n/g, '\n'))
const raw = m ? (m[1] !== undefined ? m[1].replace(/\\(["\\])/g, '$1') : m[2]) : ''
return { name, description: catalogDescription(raw), kind: 'command', scope }
}
/** One file of one root → its entry (or null). */
export function entryFor(root: CatalogRoot, rel: string, text: string): ChatCatalogEntry | null {
const e =
root.kind === 'md-commands'
? markdownCommandEntry(rel, text, root.scope)
: root.kind === 'toml-commands'
? tomlCommandEntry(rel, text, root.scope)
: skillEntry(rel, text, root.scope)
if (e === null || root.prefix === undefined) return e
const name = catalogName(`${root.prefix}:${e.name}`)
return name === null ? null : { ...e, name }
}
/** Built-ins last, custom entries in root order (project first), deduped. */
export function assembleCatalog(agentId: string | undefined, perRoot: readonly ChatCatalogEntry[][], partial: boolean): ChatCatalog {
const project: ChatCatalogEntry[] = []
const user: ChatCatalogEntry[] = []
for (const list of perRoot) for (const e of list) (e.scope === 'project' ? project : user).push(e)
const entries = mergeCatalogEntries(project, user, builtinSlashCommands(agentId))
return { version: 1, entries, ...(partial ? { partial: true } : {}) }
}
// ── Local reader (mtime-cached) ─────────────────────────────────────────────────────────────────
const CACHE_MAX = 4000
const dirCache = new Map<string, { mtimeMs: number; entries: { name: string; dir: boolean }[] }>()
const headCache = new Map<string, { mtimeMs: number; size: number; text: string }>()
function bounded<K, V>(m: Map<K, V>, k: K, v: V): void {
if (m.size >= CACHE_MAX) m.clear()
m.set(k, v)
}
/** Test seam: forget every cached listing and head. */
export function resetChatCatalogCache(): void {
dirCache.clear()
headCache.clear()
}
/** A directory's entries, from cache while the directory's mtime is unchanged. `follow` = symlinks
* are followed (user roots); otherwise a symlink is no entry at all and the directory itself must
* not be one (project roots). `null` = the directory does not exist (or is a refused link); a
* failure other than absence throws (→ `partial`). */
async function listLocalDir(dir: string, follow: boolean): Promise<{ name: string; dir: boolean }[] | null> {
let st
try {
st = await (follow ? fsp.stat(dir) : fsp.lstat(dir))
} catch (e) {
if ((e as NodeJS.ErrnoException).code === 'ENOENT' || (e as NodeJS.ErrnoException).code === 'ENOTDIR') return null
throw e
}
if (!st.isDirectory()) return null
const key = `${follow ? 'f' : 'n'}:${dir}`
const hit = dirCache.get(key)
if (hit && hit.mtimeMs === st.mtimeMs) return hit.entries
const names = (await fsp.readdir(dir)).sort().slice(0, CATALOG_ROOT_MAX_FILES * 2)
const entries: { name: string; dir: boolean }[] = []
for (const name of names) {
try {
const s = await (follow ? fsp.stat(path.join(dir, name)) : fsp.lstat(path.join(dir, name)))
if (s.isDirectory()) entries.push({ name, dir: true })
else if (s.isFile()) entries.push({ name, dir: false })
} catch {
/* a dangling link is no entry */
}
}
bounded(dirCache, key, { mtimeMs: st.mtimeMs, entries })
return entries
}
// Absent on Windows, where a project symlink is rare and needs privilege to create; the lstat'ed
// listing above is the guard there.
const O_NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0
async function readLocalHead(file: string, follow: boolean): Promise<string | null> {
try {
// Open FIRST and stat the handle: the (mtime, size) the cache is keyed on then describes the very
// bytes read, never a file swapped in between a path stat and the open. A project file is opened
// O_NOFOLLOW, so a symlink swapped in after the listing fails the open instead of being read.
const fh = await fsp.open(file, follow ? fsConstants.O_RDONLY : fsConstants.O_RDONLY | O_NOFOLLOW)
try {
const st = await fh.stat()
if (!st.isFile()) return null
const hit = headCache.get(file)
if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) return hit.text
const buf = Buffer.alloc(Math.min(CATALOG_HEAD_BYTES, st.size))
const { bytesRead } = await fh.read(buf, 0, buf.length, 0)
const text = buf.subarray(0, bytesRead).toString('utf8')
bounded(headCache, file, { mtimeMs: st.mtimeMs, size: st.size, text })
return text
} finally {
await fh.close()
}
} catch {
return null
}
}
/** The (rel, file) pairs a root holds: `<name>/SKILL.md` for skills, command files up to the depth
* cap otherwise. Bounded by `CATALOG_ROOT_MAX_FILES`. */
async function localRootFiles(root: CatalogRoot): Promise<{ rel: string; file: string }[] | null> {
const follow = root.within === undefined
if (!follow) {
// The root must resolve inside the project (`.claude -> /elsewhere` leaves it). A root that does
// not exist is simply absent.
let real: string
let realWithin: string
try {
real = await fsp.realpath(root.dir)
realWithin = await fsp.realpath(root.within!)
} catch {
return null
}
if (real !== realWithin && !real.startsWith(realWithin.endsWith(path.sep) ? realWithin : realWithin + path.sep)) return null
}
if (root.kind === 'skill-dir') return [{ rel: path.basename(root.dir), file: path.join(root.dir, 'SKILL.md') }]
const top = await listLocalDir(root.dir, follow)
if (!top) return null
const out: { rel: string; file: string }[] = []
if (root.kind === 'synced-skills') {
for (const bucket of top) {
if (!bucket.dir || bucket.name.startsWith('.')) continue
const skills = await listLocalDir(path.join(root.dir, bucket.name), follow).catch(() => null)
for (const e of skills ?? []) {
if (out.length >= CATALOG_ROOT_MAX_FILES) return out
if (e.dir && !e.name.startsWith('.')) out.push({ rel: e.name, file: path.join(root.dir, bucket.name, e.name, 'SKILL.md') })
}
}
return out
}
if (root.kind === 'skills') {
for (const e of top) {
if (out.length >= CATALOG_ROOT_MAX_FILES) break
if (e.dir && !e.name.startsWith('.')) out.push({ rel: e.name, file: path.join(root.dir, e.name, 'SKILL.md') })
}
return out
}
const ext = root.kind === 'md-commands' ? '.md' : '.toml'
const walk = async (dir: string, rel: string, entries: { name: string; dir: boolean }[], depth: number): Promise<void> => {
for (const e of entries) {
if (out.length >= CATALOG_ROOT_MAX_FILES) return
if (e.name.startsWith('.')) continue
const r = rel ? `${rel}/${e.name}` : e.name
if (e.dir) {
if (depth + 1 >= CATALOG_COMMAND_MAX_DEPTH) continue
const sub = await listLocalDir(path.join(dir, e.name), follow).catch(() => null)
if (sub) await walk(path.join(dir, e.name), r, sub, depth + 1)
} else if (e.name.toLowerCase().endsWith(ext)) out.push({ rel: r, file: path.join(dir, e.name) })
}
}
await walk(root.dir, '', top, 0)
return out
}
export async function buildLocalCatalog(q: ChatCatalogQuery, opts: { home?: string } = {}): Promise<ChatCatalog> {
const extras = await claudeLocalExtras(q, opts.home ?? os.homedir())
const roots = [...catalogRoots(q, { remote: false, home: opts.home }), ...extras.roots]
let partial = false
const perRoot = await Promise.all(
roots.map(async (root) => {
let files: { rel: string; file: string }[] | null
try {
files = await localRootFiles(root)
} catch {
partial = true
return []
}
const out: ChatCatalogEntry[] = []
for (const f of files ?? []) {
const text = await readLocalHead(f.file, root.within === undefined)
if (text === null) continue
const e = entryFor(root, f.rel, text)
if (e !== null && !(root.overridable === true && skillTurnedOff(e, root, extras.overrides))) out.push(e)
}
return out
})
)
return assembleCatalog(q.agentId, perRoot, partial)
}
// ── Plugins, synced skills and skill overrides (claude, local) ───────────────────────────────────
//
// MEASURED 2026-11-05 on Claude Code 2.1.318 (its own `/` menu, fresh sessions, test settings passed
// with `--settings`):
// - A plugin's skills and commands are listed as `/<plugin>:<name>` when the plugin is in
// `<configDir>/plugins/installed_plugins.json` AND `enabledPlugins["<plugin>@<marketplace>"]` is
// true. A disabled one lists nothing; a plugin that is only in the cache lists nothing; an install
// of scope `project` / `local` lists only in the folder it was installed for. The files are read
// from the install's `installPath` (older cached versions beside it are not).
// - claude.ai-synced skills (`<configDir>/skills/synced/<bucket>/<name>/SKILL.md`) are listed as
// `/<name>`.
// - `skillOverrides: { "<name>": "off" }` hides a user, project or synced skill (for a synced one
// `"anthropic-skills:<name>"` works too); `name-only` and `user-invocable-only` keep it in the
// menu; nothing hides a PLUGIN's skill this way. Settings are merged user < project < local, as
// for every other setting.
/** Bounds on what is read from settings: at most this many plugins, files this large. */
export const CATALOG_PLUGINS_MAX = 64
const SETTINGS_MAX_BYTES = 1024 * 1024
/** A synced skill's other spelling in `skillOverrides` (both measured to work). */
const SYNCED_OVERRIDE_PREFIX = 'anthropic-skills:'
interface ClaudeExtras {
roots: CatalogRoot[]
/** skillOverrides, merged; only "off" is acted on. */
overrides: Map<string, string>
}
function skillTurnedOff(e: ChatCatalogEntry, root: CatalogRoot, overrides: Map<string, string>): boolean {
if (e.kind !== 'skill') return false
if (overrides.get(e.name) === 'off') return true
return root.kind === 'synced-skills' && overrides.get(`${SYNCED_OVERRIDE_PREFIX}${e.name}`) === 'off'
}
/** A small JSON object file, or null (absent, too large, not JSON, not an object, or — `follow`
* false, a project file — a symlink). */
async function readLocalJson(file: string, follow: boolean): Promise<Record<string, unknown> | null> {
try {
const fh = await fsp.open(file, follow ? fsConstants.O_RDONLY : fsConstants.O_RDONLY | O_NOFOLLOW)
try {
const st = await fh.stat()
if (!st.isFile() || st.size > SETTINGS_MAX_BYTES) return null
const v: unknown = JSON.parse((await fh.readFile()).toString('utf8'))
return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null
} finally {
await fh.close()
}
} catch {
return null
}
}
const recordOf = (v: unknown): Record<string, unknown> =>
v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {}
/** The paths a manifest field names (a string or a list of strings), each resolved inside `root`. */
function manifestPaths(v: unknown, root: string, fallback: string): string[] {
const raw = v === undefined ? [fallback] : typeof v === 'string' ? [v] : Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []
const out: string[] = []
for (const r of raw as string[]) {
const abs = path.resolve(root, r)
const rel = path.relative(root, abs)
if (rel.startsWith('..') || path.isAbsolute(rel)) continue
out.push(abs)
}
return out
}
/** The extra roots and the skill overrides of a LOCAL claude node. Never throws: a file that cannot
* be read adds nothing. */
export async function claudeLocalExtras(q: ChatCatalogQuery, home: string): Promise<ClaudeExtras> {
const none: ClaudeExtras = { roots: [], overrides: new Map() }
if (q.agentId === undefined || capabilityAgentId(q.agentId) !== 'claude') return none
const configDir = claudeCatalogConfigDir(q.accountId, { remote: false, home })
if (configDir === null) return none
const cwd = typeof q.cwd === 'string' && q.cwd.trim() !== '' ? q.cwd : undefined
const settings = [
await readLocalJson(path.join(configDir, 'settings.json'), true),
...(cwd === undefined
? []
: [
await readLocalJson(path.join(cwd, '.claude', 'settings.json'), false),
await readLocalJson(path.join(cwd, '.claude', 'settings.local.json'), false)
])
]
const enabled = new Map<string, boolean>()
const overrides = new Map<string, string>()
for (const s of settings) {
for (const [k, v] of Object.entries(recordOf(s?.enabledPlugins))) if (typeof v === 'boolean') enabled.set(k, v)
for (const [k, v] of Object.entries(recordOf(s?.skillOverrides))) if (typeof v === 'string') overrides.set(k, v)
}
const roots: CatalogRoot[] = [{ kind: 'synced-skills', scope: 'user', dir: path.join(configDir, 'skills', 'synced'), overridable: true }]
const installed = recordOf((await readLocalJson(path.join(configDir, 'plugins', 'installed_plugins.json'), true))?.plugins)
let count = 0
for (const [key, installs] of Object.entries(installed)) {
if (enabled.get(key) !== true || !Array.isArray(installs)) continue
if (++count > CATALOG_PLUGINS_MAX) break
const install = installs.map(recordOf).find((i) => {
if (i.scope === 'user' || i.scope === undefined) return true
return cwd !== undefined && typeof i.projectPath === 'string' && path.resolve(i.projectPath) === path.resolve(cwd)
})
const installPath = install?.installPath
if (typeof installPath !== 'string' || !path.isAbsolute(installPath)) continue
const manifest = await readLocalJson(path.join(installPath, '.claude-plugin', 'plugin.json'), true)
const prefix = catalogName(manifest?.name) ?? catalogName(key.split('@')[0])
if (prefix === null) continue
for (const dir of manifestPaths(manifest?.skills, installPath, 'skills')) {
// A listed folder is one skill when it holds a SKILL.md, else a folder of skills.
const one = await fsp
.stat(path.join(dir, 'SKILL.md'))
.then((st) => st.isFile())
.catch(() => false)
roots.push({ kind: one ? 'skill-dir' : 'skills', scope: 'user', dir, prefix })
}
for (const dir of manifestPaths(manifest?.commands, installPath, 'commands')) roots.push({ kind: 'md-commands', scope: 'user', dir, prefix })
}
return { roots, overrides }
}
// ── Remote reader (one ssh round trip) ──────────────────────────────────────────────────────────
// Record marker at the start of a line. Every file's bytes go through `tr -d` of the marker byte, so
// a hostile file cannot forge a record boundary (it could at most add its own entries, which it can
// already do by being another file in that directory).
const RS = '\u001e'
/**
* One POSIX sh line listing every root's files with the head of each. Output, per file:
* `<RS>F <rootIndex> <rel>\n<first CATALOG_HEAD_BYTES bytes, RS removed>\n`
* and `<RS>E <rootIndex>` for a root that exists but could not be listed. A missing root prints
* nothing. `find -L` follows linked skill/command folders; `-maxdepth` bounds a link loop.
*/
export function remoteCatalogCommand(roots: readonly CatalogRoot[]): string {
const parts = roots.map((root, i) => {
const d = quoteRemotePath(root.dir)
const project = root.within !== undefined
const emit = `printf '\\036F ${i} %s\\n' "$r"; head -c ${CATALOG_HEAD_BYTES} "$f" 2>/dev/null | tr -d '\\036'; printf '\\n'`
// A PROJECT root must resolve inside the node's cwd (`pwd -P` of both — POSIX, BSD and GNU alike),
// and nothing under it is followed: `find -P`, and `[ -L ]` on the skill folder and its SKILL.md.
// A user root follows links (`find -L`; the glob follows a linked skill folder).
const inside = project
? `w=$(cd ${quoteRemotePath(root.within!)} 2>/dev/null && pwd -P) && r0=$(cd "$d" 2>/dev/null && pwd -P) && case "$r0/" in "$w"/*) true;; *) false;; esac`
: 'true'
const noLinks = project ? `[ -L "\${f%/SKILL.md}" ] && continue; [ -L "$f" ] && continue; ` : ''
if (root.kind === 'skills') {
return (
`d=${d}; if [ -d "$d" ] && ${inside}; then n=0; for f in "$d"/*/SKILL.md; do ${noLinks}[ -f "$f" ] || continue; ` +
`n=$((n+1)); [ "$n" -le ${CATALOG_ROOT_MAX_FILES} ] || break; r=\${f%/SKILL.md}; r=\${r##*/}; ${emit}; done; fi`
)
}
const ext = root.kind === 'md-commands' ? '*.md' : '*.toml'
return (
`d=${d}; if [ -d "$d" ] && ${inside}; then { find ${project ? '-P' : '-L'} "$d" -maxdepth ${CATALOG_COMMAND_MAX_DEPTH} -type f -name ${posixQuote(ext)} 2>/dev/null || printf '\\036E ${i}\\n'; } ` +
`| head -n ${CATALOG_ROOT_MAX_FILES} | while IFS= read -r f; do case "$f" in "$(printf '\\036')"E*) printf '%s\\n' "$f"; continue;; esac; r=\${f#"$d"/}; ${emit}; done; fi`
)
})
return parts.join('; ') + '; exit 0'
}
/** The remote command's output → the entries per root, plus whether a root failed. */
export function parseRemoteCatalog(stdout: string, roots: readonly CatalogRoot[]): { perRoot: ChatCatalogEntry[][]; partial: boolean } {
const perRoot: ChatCatalogEntry[][] = roots.map(() => [])
let partial = false
const records = stdout.split(`\n${RS}`)
if (records[0].startsWith(RS)) records[0] = records[0].slice(1)
else records.shift() // anything before the first record is not ours (a noisy login shell)
for (const rec of records) {
const nl = rec.indexOf('\n')
const head = nl < 0 ? rec : rec.slice(0, nl)
const m = /^([FE]) (\d+)(?: (.*))?$/.exec(head)
if (!m) continue
const i = Number(m[2])
const root = roots[i]
if (!root) continue
if (m[1] === 'E') {
partial = true
continue
}
const rel = m[3] ?? ''
// Dot entries are skipped like the local walk skips them; `..` or an absolute path is not ours.
if (!rel || rel.startsWith('/') || rel.split('/').some((seg) => !seg || seg.startsWith('.'))) continue
if (perRoot[i].length >= CATALOG_ROOT_MAX_FILES) continue
const e = entryFor(root, rel, nl < 0 ? '' : rec.slice(nl + 1))
if (e) perRoot[i].push(e)
}
return { perRoot, partial }
}
export interface RemoteCatalogRunner {
/** Run `cmd` on the node's host. `null` = not a remote node after all / no master. */
(nodeId: string, cmd: string): Promise<{ code: number; stdout: string } | null>
}
export async function buildRemoteCatalog(q: ChatCatalogQuery & { nodeId: string }, run: RemoteCatalogRunner): Promise<ChatCatalog> {
const roots = catalogRoots(q, { remote: true })
if (!roots.length) return assembleCatalog(q.agentId, [], false)
let res: { code: number; stdout: string } | null = null
try {
res = await run(q.nodeId, remoteCatalogCommand(roots))
} catch {
res = null
}
// The host could not be asked: built-ins only, and say the list is short.
if (!res || res.code !== 0) return assembleCatalog(q.agentId, [], true)
const { perRoot, partial } = parseRemoteCatalog(res.stdout, roots)
return assembleCatalog(q.agentId, perRoot, partial)
}
// ── Registration (both shells) ──────────────────────────────────────────────────────────────────
export interface ChatCatalogDeps {
/** From the SHELL's own records, never the renderer's arguments. Absent (Server Edition) = no
* node is remote, which is correct there: it runs on the host it reads. */
isRemoteNode?(nodeId: string): boolean
/** The remote leg. A remote node with no runner answers built-ins only (`partial`), never a read
* of THIS machine's disk for a node whose files are on another one. */
runRemote?: RemoteCatalogRunner
/** Test seam for the local home directory. */
home?: string
}
const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined)
export async function readChatCatalog(
args: { nodeId?: unknown; agentId?: unknown; accountId?: unknown; cwd?: unknown },
deps: ChatCatalogDeps = {}
): Promise<ChatCatalog> {
const q: ChatCatalogQuery = { agentId: str(args.agentId), accountId: str(args.accountId), cwd: str(args.cwd) }
const nodeId = str(args.nodeId)
if (nodeId && deps.isRemoteNode?.(nodeId)) {
if (!deps.runRemote) return assembleCatalog(q.agentId, [], true)
return buildRemoteCatalog({ ...q, nodeId }, deps.runRemote)
}
return buildLocalCatalog(q, { home: deps.home })
}
export function registerChatCatalogIpc(deps: ChatCatalogDeps = {}): void {
platform().handle(
IPC.chatCatalog,
(nodeId: unknown, agentId: unknown, accountId: unknown, cwd: unknown): Promise<ChatCatalog> =>
readChatCatalog({ nodeId, agentId, accountId, cwd }, deps).then((c) =>
c.entries.length > CHAT_CATALOG_MAX_ENTRIES ? { ...c, entries: c.entries.slice(0, CHAT_CATALOG_MAX_ENTRIES) } : c
)
)
}