@orbit-intelligence/orbit-agent 0.3.12

package/dist/src/core/orchestration/session.js

@@ -0,0 +1,204 @@
+import { AgentRuntime } from './runtime.js';
+import { Messenger } from './messenger.js';
+import { SharedContext } from './shared-context.js';
+import { createDispatcher, truncate } from './dispatcher.js';
+const MAX_BUDGET_COUNT = 6;
+const QUIESCENCE_STEPS = 400;
+const LEAD_PROMPT_BASE = `You are a Lead agent in a multi-agent session. Other lead agents (your peers) are full agents with their own models and goals. Coordinate with them instead of working entirely alone: use agent_message to propose/ask/agree, agent_interrupt to halt a peer heading the wrong way, and read_shared/note_shared to stay in sync. You may delegate self-contained work to specialized role agents via delegate_task (single or parallel). When the work is done, stop — do not invent follow-up tasks.`;
+/**
+ * OrchestrationSession — serialized driver for one user turn across a team of
+ * lead agents. Leads' loops run concurrently; the messenger coordinates
+ * hand-offs (parked waiters resume when their reply lands). The driver drains
+ * mailboxes between runs and ends the turn once no agent has work left.
+ */
+export class OrchestrationSession {
+    opts;
+    messenger;
+    shared;
+    runtimes = new Map();
+    leadIds = [];
+    roleIds = new Set();
+    jobs = new Map();
+    statuses = new Map();
+    busy = false;
+    roleDispatcher;
+    get status() {
+        return this.statuses;
+    }
+    get agentIds() {
+        return this.leadIds;
+    }
+    get sharedContext() {
+        return this.shared;
+    }
+    constructor(opts) {
+        this.opts = opts;
+        this.shared = new SharedContext();
+        this.messenger = new Messenger({
+            getAgentIds: () => [...this.leadIds, ...this.roleIds],
+            onMessage: (msg) => this.onTraffic(msg),
+            onParked: (id) => this.setStatus(id, 'waiting'),
+            onUnparked: (id) => this.setStatus(id, 'thinking'),
+        });
+        const leads = opts.config.leads.slice(0, Math.max(1, opts.config.maxLeadAgents ?? 2));
+        for (let i = 0; i < leads.length; i++) {
+            const lead = leads[i];
+            const id = leadIdFor(lead.name, i);
+            const rt = new AgentRuntime({
+                identity: { id, name: lead.name },
+                label: `Lead ${i + 1} · ${lead.name}`,
+                systemPrompt: [opts.baseSystemPrompt, LEAD_PROMPT_BASE, lead.systemPrompt].filter(Boolean).join('\n\n'),
+                model: lead.model,
+                providers: opts.providers,
+                strategy: opts.strategy,
+                tools: opts.registry,
+                permissions: opts.permissions,
+                messenger: this.messenger,
+                shared: this.shared,
+                cwd: opts.cwd,
+                delegate: (req) => this.dispatchRole(req),
+                maxIterations: 16,
+                maxDelegations: MAX_BUDGET_COUNT,
+                contextBudgetTokens: opts.contextBudgetTokens ?? 48_000,
+                toolTimeoutMs: opts.config.toolTimeoutMs ?? 30_000,
+                streamTimeoutMs: opts.config.streamTimeoutMs ?? 120_000,
+                maxTokensPerSecond: opts.maxTokensPerSecond,
+                reasoning: opts.reasoning,
+                bus: opts.bus,
+            });
+            this.runtimes.set(id, rt);
+            this.leadIds.push(id);
+            this.setStatus(id, 'idle');
+        }
+        this.roleDispatcher = createDispatcher({
+            roles: opts.roles,
+            providers: opts.providers,
+            strategy: opts.strategy,
+            permissions: opts.permissions,
+            registry: opts.registry,
+            cwd: opts.cwd,
+            leakWindowSize: 200,
+            defaultModel: opts.defaultModel,
+            maxIterations: 12,
+            contextBudgetTokens: opts.contextBudgetTokens ?? 48_000,
+            toolTimeoutMs: opts.config.toolTimeoutMs ?? 30_000,
+            streamTimeoutMs: opts.config.streamTimeoutMs ?? 120_000,
+            reasoning: opts.reasoning,
+            bus: opts.bus,
+            registerRole: (id) => this.roleIds.add(id),
+            unregisterRole: (id) => this.roleIds.delete(id),
+        });
+    }
+    runtime(id) {
+        return this.runtimes.get(id);
+    }
+    /** Run one user turn across the team; resolves when the team is quiescent. */
+    async handleUser(text) {
+        if (this.busy)
+            return;
+        this.busy = true;
+        try {
+            this.shared.recordActivity({ kind: 'activity', text: truncate(text, 300), to: 'all', from: 'user' });
+            this.opts.bus.emit('onSessionStatus', `user → all agents: ${truncate(text, 80)}`);
+            for (const id of this.leadIds)
+                this.startRun(id, text);
+            await this.quiesce();
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    /** Abort one agent's in-flight run (used by cancellation UI). */
+    abortAgent(id) {
+        this.runtimes.get(id)?.abort();
+    }
+    startRun(id, input) {
+        if (this.jobs.has(id))
+            return;
+        const rt = this.runtimes.get(id);
+        if (!rt)
+            return;
+        this.setStatus(id, 'thinking');
+        const p = (async () => {
+            let interrupted = false;
+            try {
+                const res = await rt.run(input);
+                interrupted = res.interrupted ?? false;
+                this.setStatus(id, interrupted ? 'interrupted' : 'done');
+            }
+            catch (err) {
+                this.setStatus(id, 'error');
+                this.opts.bus.emit('onError', err);
+            }
+            finally {
+                this.jobs.delete(id);
+                // Lost-wakeup guard: mail may have arrived while this run was busy.
+                // Resume an agent that was NOT aborted/interrupted, on actionable mail.
+                if (!interrupted && this.hasActionableMail(id))
+                    this.startRun(id, this.drainMailbox(id));
+            }
+        })();
+        this.jobs.set(id, p);
+    }
+    drainMailbox(id) {
+        const msgs = this.messenger.takePending(id);
+        if (msgs.length === 0)
+            return '(no pending messages)';
+        const parts = msgs.map((m) => {
+            const kind = m.kind === 'interrupt' ? 'INTERRUPT' : m.kind.toUpperCase();
+            const from = m.from === 'user' ? 'user' : `@${m.from}`;
+            return `<${kind} from ${from}>\n${m.content}\n</${kind}>`;
+        });
+        return `[New messages for you]\n\n${parts.join('\n\n')}`;
+    }
+    onTraffic(msg) {
+        this.shared.recordMessage(msg);
+        this.opts.bus.emit('onAgentMessage', msg);
+        if (!this.leadIds.includes(msg.to))
+            return;
+        if (msg.kind === 'interrupt') {
+            this.runtimes.get(msg.to)?.abort();
+            return;
+        }
+        // Wake an idle lead so it can act on the incoming message immediately.
+        if (!this.jobs.has(msg.to) && this.messenger.hasPending(msg.to)) {
+            this.startRun(msg.to, this.drainMailbox(msg.to));
+        }
+    }
+    /** Actionable mail excludes interrupt notices (those are handled by abort). */
+    hasActionableMail(id) {
+        return this.messenger.pendingOf(id).some((m) => m.kind !== 'interrupt');
+    }
+    async dispatchRole(req) {
+        return this.roleDispatcher(req);
+    }
+    async quiesce() {
+        let budget = QUIESCENCE_STEPS;
+        while (budget-- > 0) {
+            await this.waitForAll();
+            const next = this.leadIds.filter((id) => !this.jobs.has(id) && this.hasActionableMail(id));
+            if (next.length === 0)
+                break;
+            for (const id of next)
+                this.startRun(id, this.drainMailbox(id));
+        }
+        for (const id of this.leadIds) {
+            if (!this.jobs.has(id))
+                this.setStatus(id, 'idle');
+        }
+    }
+    async waitForAll() {
+        while (this.jobs.size > 0) {
+            await Promise.allSettled([...this.jobs.values()]);
+        }
+    }
+    setStatus(id, status) {
+        this.statuses.set(id, status);
+        const rt = this.runtimes.get(id);
+        this.opts.bus.emit('onAgentStatus', { id, name: rt?.identity.name ?? id, status });
+    }
+}
+function leadIdFor(name, index) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    return `lead_${slug || String(index + 1)}`;
+}

package/dist/src/core/orchestration/shared-context.js

@@ -0,0 +1,88 @@
+const MAX_FACTS_BYTES = 1600;
+const JOURNAL_WINDOW = 40;
+export class SharedContext {
+    facts = [];
+    journal = [];
+    opts;
+    constructor(opts = {}) {
+        this.opts = {
+            maxFactsBytes: opts.maxFactsBytes ?? MAX_FACTS_BYTES,
+            journalWindow: opts.journalWindow ?? JOURNAL_WINDOW,
+        };
+    }
+    get factCount() {
+        return this.facts.length;
+    }
+    get journalCount() {
+        return this.journal.length;
+    }
+    getFacts() {
+        return [...this.facts];
+    }
+    /** Recent journal as plain text lines (used by read_shared). */
+    getJournal(depth) {
+        return this.dump(depth ?? JOURNAL_WINDOW * 2).journal.join('\n');
+    }
+    addFact(fact) {
+        if (!fact.trim())
+            return;
+        this.facts.push(fact.trim());
+        let total = this.facts.join('\n').length;
+        while (total > this.opts.maxFactsBytes && this.facts.length > 1) {
+            this.facts.shift();
+            total = this.facts.join('\n').length;
+        }
+    }
+    recordActivity(entry) {
+        this.journal.push({ ...entry, id: `j_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`, createdAt: Date.now() });
+    }
+    recordMessage(msg) {
+        this.recordActivity({
+            kind: 'agent-message',
+            text: msg.content,
+            to: msg.to,
+            from: msg.from,
+        });
+    }
+    recordTask(task, verb) {
+        this.recordActivity({ kind: 'task', text: `[${verb}] ${task.role}${task.result ? `: ${truncate(task.result, 200)}` : ''}`, to: task.from });
+    }
+    /** Relevance-scoped excerpt for a given agent id. */
+    excerptFor(agentId, includeFacts = true) {
+        const parts = [];
+        if (includeFacts && this.facts.length > 0) {
+            parts.push(`# Shared project facts\n${this.facts.map((f) => `- ${f}`).join('\n')}`);
+        }
+        const own = this.journal.filter((e) => e.to === agentId || e.to === 'all');
+        // Recent window is visibility-scoped: non-message activity (task outcomes,
+        // activity log) plus messages actually addressed to this agent. Peer-addressed
+        // messages must never leak into another agent's excerpt.
+        const window = this.journal
+            .filter((e) => e.kind !== 'agent-message' || e.to === agentId || e.to === 'all')
+            .slice(-this.opts.journalWindow);
+        const merged = mergeByDate(own.filter((e) => !window.includes(e)), window);
+        if (merged.length > 0) {
+            const lines = merged.map((e) => {
+                const who = e.from ? `@${e.from}` : 'activity';
+                const at = e.to ? ` → ${e.to === 'all' ? 'all' : `@${e.to}`}` : '';
+                return `- [${e.kind}] ${who}${at}: ${e.text}`;
+            });
+            parts.push(`# Shared activity\n${lines.join('\n')}`);
+        }
+        return parts.join('\n\n');
+    }
+    /** Full journal + facts (used by the read_shared tool) — callers should bound reads. */
+    dump(maxEntries) {
+        const journal = this.journal.slice(-(maxEntries ?? this.journal.length));
+        return {
+            facts: [...this.facts],
+            journal: journal.map((e) => `[${e.kind}]${e.from ? ` @${e.from}` : ''}${e.to ? ` → @${e.to}` : ''}: ${e.text}`),
+        };
+    }
+}
+function mergeByDate(a, b) {
+    return [...a, ...b].sort((x, y) => x.createdAt - y.createdAt);
+}
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n)}…`;
+}

package/dist/src/core/orchestration/tools.js

@@ -0,0 +1,187 @@
+import { builtInRoleIds } from './roles.js';
+/** Register the orchestration-only tools into a shared tool registry (idempotent). */
+export function registerOrchestrationTools(registry, delegate) {
+    registry.register(createAgentMessageTool());
+    registry.register(createAgentInterruptTool());
+    for (const t of createSharedContextTools())
+        registry.register(t);
+    registry.register(createDelegateTaskTool(delegate));
+}
+export const ROLE_HINT = `role: one of ${builtInRoleIds.join(', ')} (a custom role word is also allowed).`;
+/** Boss-level communication: send a message to another agent, optionally waiting for its reply. */
+export function createAgentMessageTool() {
+    return {
+        name: 'agent_message',
+        description: 'Send a message to another agent in this session and (optionally) wait for its reply. Use to collaborate: propose changes, ask for input, raise concerns, request the peer inspect something. When wait=true your run parks until the peer replies or the timeout elapses — the peer processes your message in parallel.',
+        parameters: {
+            type: 'object',
+            properties: {
+                to: { type: 'string', description: 'Target agent id or name (e.g. "atl_1" or "Atlas"). Pass "all" to broadcast.' },
+                content: { type: 'string', description: 'The message body.' },
+                wait: { type: 'boolean', description: 'Park until the peer replies. Default false.' },
+                replyTimeoutMs: { type: 'number', description: 'Max wait in ms when wait=true (default 60000).' },
+            },
+            required: ['to', 'content'],
+        },
+        async run(args, ctx) {
+            const to = String(args.to ?? '');
+            const content = String(args.content ?? '').trim();
+            if (!content)
+                return { content: 'Error: empty message.', isError: true };
+            if (!ctx.agent)
+                return { content: 'Error: agent messaging is unavailable outside an orchestration session.', isError: true };
+            try {
+                ctx.agent.send(to, content, 'message');
+            }
+            catch (err) {
+                return { content: `Error: ${err.message}`, isError: true };
+            }
+            if (args.wait === true) {
+                const timeout = Math.min(Number(args.replyTimeoutMs ?? 60_000), 300_000);
+                const reply = await ctx.agent.waitForReply(to, timeout);
+                return { content: `[agent_message] delivered to @${to}; reply received:\n${reply}` };
+            }
+            return { content: `[agent_message] delivered to @${to}.` };
+        },
+    };
+}
+/** Halt another agent's current work; it will process your reason next. */
+export function createAgentInterruptTool() {
+    return {
+        name: 'agent_interrupt',
+        description: 'Interrupt another agent immediately. Its current run is aborted and your reason is delivered as its next input. Use when a peer is going in a direction that will cause damage or waste: warn precisely, then continue your own reasoning.',
+        parameters: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Target agent id or name.' },
+                reason: { type: 'string', description: 'Concise reason, referencing concrete facts (file, behavior).' },
+            },
+            required: ['target', 'reason'],
+        },
+        async run(args, ctx) {
+            const target = String(args.target ?? '');
+            const reason = String(args.reason ?? '').trim();
+            if (!reason)
+                return { content: 'Error: empty reason.', isError: true };
+            if (!ctx.agent)
+                return { content: 'Error: agent messaging is unavailable outside an orchestration session.', isError: true };
+            try {
+                ctx.agent.interrupt(target, reason);
+            }
+            catch (err) {
+                return { content: `Error: ${err.message}`, isError: true };
+            }
+            return { content: `[agent_interrupt] @${target} interrupted.` };
+        },
+    };
+}
+/** Read the shared orchestration context on demand. */
+export function createSharedContextTools() {
+    const readTool = {
+        name: 'read_shared',
+        description: 'Read the shared orchestration context: project facts other agents have recorded and the recent shared activity journal (messages, task outcomes). Use when you need awareness of what peers decided or reported. Scoped reads only; the excerpt is bounded.',
+        parameters: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['auto', 'all', 'facts', 'journal'], description: 'auto = facts + recent journal (default).' },
+                depth: { type: 'number', description: 'How many recent journal entries to include (default 40, max 200).' },
+            },
+        },
+        async run(args, ctx) {
+            if (!ctx.shared)
+                return { content: 'Error: shared context is unavailable outside an orchestration session.', isError: true };
+            const scope = String(args.scope ?? 'auto');
+            const depth = Math.min(Number(args.depth ?? 40), 200);
+            if (scope === 'all') {
+                return { content: ctx.shared.getJournal(depth) };
+            }
+            if (scope === 'journal') {
+                return { content: ctx.shared.getJournal(depth) };
+            }
+            if (scope === 'facts') {
+                const facts = ctx.shared.getFacts();
+                return { content: facts.length ? facts.map((f) => `- ${f}`).join('\n') : '(no shared facts yet)' };
+            }
+            return { content: ctx.shared.getExcerptForSelf() };
+        },
+    };
+    const noteTool = {
+        name: 'note_shared',
+        description: 'Record a short, durable project fact into the shared context (e.g. "state manager changed to zustand", "deploy script uses produce.sh"). Facts persist for the session and are visible to all agents — use sparingly for decisions worth remembering.',
+        parameters: {
+            type: 'object',
+            properties: {
+                fact: { type: 'string', description: 'One short fact (under ~140 chars).' },
+            },
+            required: ['fact'],
+        },
+        async run(args, ctx) {
+            if (!ctx.shared)
+                return { content: 'Error: shared context is unavailable outside an orchestration session.', isError: true };
+            const fact = String(args.fact ?? '').trim();
+            if (!fact)
+                return { content: 'Error: empty fact.', isError: true };
+            ctx.shared.addFact(fact);
+            return { content: '[note_shared] recorded.' };
+        },
+    };
+    return [readTool, noteTool];
+}
+/** Schema-only tool; execution is intercepted by AgentLoop.runDelegation. */
+export function createDelegateTaskTool(delegate) {
+    return {
+        name: 'delegate_task',
+        description: `Dispatch work to a specialized role agent. You (the lead) decide the role, the exact task, and whether to run several role agents in parallel. The role agent is a full agent: it has the same tool access as you and an isolated context seeded with your task, and returns a structured summary. Roles: ${builtInRoleIds.join(', ')}. Parallel: use the 'parallel' array to run several independent role agents concurrently. Do NOT delegate work you should just do yourself.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                role: { type: 'string', description: ROLE_HINT },
+                task: { type: 'string', description: 'Self-contained, specific assignment. Include file paths, constraints, and definition of done.' },
+                files: { type: 'array', items: { type: 'string' }, description: 'Relevant files to bound scope.' },
+                parallel: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            role: { type: 'string', description: ROLE_HINT },
+                            task: { type: 'string', description: 'Self-contained assignment.' },
+                            files: { type: 'array', items: { type: 'string' } },
+                        },
+                        required: ['role', 'task'],
+                    },
+                    description: 'Run multiple independent role agents concurrently. Each returns its own summary.',
+                },
+            },
+            oneOf: [
+                { required: ['role', 'task'] },
+                { required: ['parallel'] },
+            ],
+        },
+        async run(args, ctx) {
+            if (!delegate)
+                return { content: 'Error: delegation is unavailable in this context.', isError: true };
+            return runDelegationSchemas(delegate, args, ctx);
+        },
+    };
+}
+async function runDelegationSchemas(delegate, args, _ctx) {
+    const jobs = [];
+    const parallelRaw = Array.isArray(args.parallel) ? args.parallel : [];
+    if (parallelRaw.length > 0) {
+        for (const p of parallelRaw) {
+            jobs.push({ role: String(p.role ?? ''), task: String(p.task ?? ''), files: Array.isArray(p.files) ? p.files.map(String) : undefined });
+        }
+    }
+    else {
+        jobs.push({ role: String(args.role ?? ''), task: String(args.task ?? ''), files: Array.isArray(args.files) ? args.files.map(String) : undefined });
+    }
+    const invalid = jobs.find((j) => !j.task.trim());
+    if (invalid)
+        return { content: 'Error: delegate_task requires a non-empty task for every job.', isError: true };
+    const results = await Promise.all(jobs.map((j) => delegate(j)));
+    const owns = results.every((r) => r.ok);
+    const lines = results
+        .map((r, i) => `<delegated-${jobs[i].role} ok="${r.ok}">\n${r.summary}\n</delegated-${jobs[i].role}>`)
+        .join('\n\n');
+    return { content: lines, isError: !owns };
+}

package/dist/src/core/orchestration/types.js

@@ -0,0 +1,3 @@
+export function newId() {
+    return `o_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}

package/dist/src/core/permissions/index.js

@@ -0,0 +1,58 @@
+export class PermissionManager {
+    mode;
+    allowCommands;
+    denyCommands;
+    allowPaths;
+    denyPaths;
+    prompt;
+    constructor(config, prompt) {
+        this.mode = config.mode;
+        this.allowCommands = config.allowCommands ?? [];
+        this.denyCommands = config.denyCommands ?? [];
+        this.allowPaths = config.allowPaths ?? [];
+        this.denyPaths = config.denyPaths ?? [];
+        this.prompt = prompt ?? null;
+    }
+    async checkCommand(command) {
+        const trimmed = command.trim();
+        if (this.denyCommands.some((d) => matchesPrefix(d, trimmed)))
+            return 'deny';
+        if (this.mode === 'deny')
+            return 'deny';
+        if (this.allowCommands.some((a) => matchesPrefix(a, trimmed)))
+            return 'allow';
+        if (this.mode === 'allow')
+            return 'allow';
+        // ask
+        if (this.prompt) {
+            const ok = await this.prompt.ask(`Allow shell: ${command.slice(0, 80)}`);
+            return ok ? 'allow' : 'deny';
+        }
+        return 'deny';
+    }
+    async checkPath(path, op) {
+        if (this.denyPaths.some((d) => pathStartsWith(path, d)))
+            return 'deny';
+        if (op === 'read' && (this.mode === 'allow'))
+            return 'allow';
+        if (this.allowPaths.some((a) => pathStartsWith(path, a)))
+            return 'allow';
+        if (op === 'read')
+            return 'allow'; // reads are generally fine
+        if (this.mode === 'deny')
+            return 'deny';
+        if (this.mode === 'allow')
+            return 'allow';
+        if (this.prompt) {
+            const ok = await this.prompt.ask(`Allow writing: ${path}`);
+            return ok ? 'allow' : 'deny';
+        }
+        return 'deny';
+    }
+}
+function matchesPrefix(rule, value) {
+    return value === rule || value.startsWith(`${rule} `);
+}
+function pathStartsWith(value, rule) {
+    return value === rule || value.startsWith(rule.endsWith('/') ? rule : rule + '/');
+}

package/dist/src/core/project-context.js

@@ -0,0 +1,115 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, join, basename } from 'node:path';
+/**
+ * Project-scoped instruction loading, modeled on Agent Build / Claude Code:
+ *
+ *   - AGENTS.md / .orbit/AGENTS.md / CLAUDE.md — loaded from the current
+ *     directory, walking up toward the filesystem root. Every file is injected
+ *     into the system prompt so the agent inherits the project's conventions.
+ *   - .orbit/skills/*.md — named skill files the agent can invoke via
+ *     `/skill <name>` (or automatically if a skill named "always" is present).
+ *
+ * Files are read once at startup; the combined text is a stable part of the
+ * system prompt, so a later edit requires a restart to take effect.
+ */
+const CONVENTION_FILES = ['AGENTS.md', '.orbit/AGENTS.md', '.agents/AGENTS.md', 'CLAUDE.md'];
+const MAX_TOTAL_BYTES = 120_000;
+export function loadProjectContext(cwd) {
+    const files = [];
+    const bodies = [];
+    let total = 0;
+    collectUpward(cwd, (dir) => {
+        for (const name of CONVENTION_FILES) {
+            const p = join(dir, name);
+            if (files.includes(p))
+                continue;
+            const raw = readSafe(p);
+            if (raw === null)
+                continue;
+            files.push(p);
+            bodies.push(`## ${relLabel(p, cwd)}\n${raw.trim()}\n`);
+            total += raw.length;
+            if (total > MAX_TOTAL_BYTES)
+                return true; // stop climbing
+        }
+        return total > MAX_TOTAL_BYTES;
+    });
+    const skillsDir = findSkillsDir(cwd);
+    const skillBodies = {};
+    const skills = [];
+    if (skillsDir) {
+        for (const f of readdirSafe(skillsDir)) {
+            if (!f.endsWith('.md'))
+                continue;
+            const p = join(skillsDir, f);
+            const name = basename(f, '.md');
+            const body = readSafe(p);
+            if (body === null)
+                continue;
+            skillBodies[name] = body;
+            const summary = body.split('\n').find((l) => l.trim().startsWith('#') || l.trim() !== '')?.trim() ?? '';
+            skills.push({ name, path: p, summary: summary.slice(0, 120) });
+        }
+        skills.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    return { files, conventions: bodies.join('\n'), skills, skillBodies };
+}
+function collectUpward(start, visit) {
+    let dir = resolve(start);
+    for (let depth = 0; depth < 12; depth++) {
+        let stop = false;
+        try {
+            stop = visit(dir);
+        }
+        catch {
+            /* ignore unreadable dirs */
+        }
+        if (stop)
+            return;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return;
+        dir = parent;
+    }
+}
+function findSkillsDir(cwd) {
+    let dir = resolve(cwd);
+    for (let depth = 0; depth < 8; depth++) {
+        for (const candidate of ['.orbit/skills', '.agents/skills', 'skills']) {
+            const p = join(dir, candidate);
+            try {
+                const st = statSync(p);
+                if (st.isDirectory())
+                    return p;
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+function readSafe(p) {
+    try {
+        return readFileSync(p, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function readdirSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function relLabel(p, cwd) {
+    const rel = p.startsWith(cwd) ? p.slice(cwd.length).replace(/^\//, '') : p;
+    return rel || basename(p);
+}