@orbit-intelligence/orbit-agent 0.3.12

package/dist/src/core/llm/secrets.js

@@ -0,0 +1,121 @@
+/**
+ * Provider credential handling.
+ *
+ * SECURITY: keys are read ONLY from environment variables or the optional,
+ * git-ignored, 0600 `keys.json`. They are never written to config.json,
+ * never logged, and never included in generated artifacts.
+ */
+import { readFileSync, existsSync, chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { keysPath, configDir } from '../../utils/platform.js';
+const ENV_LABELS = {
+    orbitx: ['ORBITX_TOKEN', 'ORBITX_API_KEY'],
+    groq: ['GROQ_API_KEY'],
+    gemini: ['GEMINI_API_KEY'],
+    openrouter: ['OPENROUTER_API_KEY'],
+};
+// The setup wizard calls providers three times in quick succession; don't
+// re-read + re-parse + re-chmod the keys file on every lookup.
+const KEYS_CACHE_MS = 2000;
+let keysCache = null;
+function readKeysFile() {
+    const now = Date.now();
+    if (keysCache && now - keysCache.at < KEYS_CACHE_MS)
+        return keysCache.data;
+    const path = keysPath();
+    if (!existsSync(path)) {
+        keysCache = { data: {}, at: now };
+        return {};
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        // best-effort tighten perms so other apps can't read it
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            /* ignore */
+        }
+        keysCache = { data: raw, at: now };
+        return raw;
+    }
+    catch {
+        keysCache = { data: {}, at: now };
+        return {};
+    }
+}
+function invalidateKeysCache() {
+    keysCache = null;
+}
+function fromEnv(provider) {
+    const labels = ENV_LABELS[provider];
+    if (!labels)
+        return [];
+    const keys = [];
+    for (const label of labels) {
+        const direct = process.env[label];
+        if (direct && !keys.includes(direct))
+            keys.push(direct);
+        // allow GROQ_API_KEY_1.._9 rotation
+        for (let i = 1; i <= 9; i++) {
+            const rotated = process.env[`${label}_${i}`];
+            if (rotated && !keys.includes(rotated))
+                keys.push(rotated);
+        }
+    }
+    return keys;
+}
+export function isImportableDirectly(p) {
+    return p === 'groq' || p === 'gemini' || p === 'openrouter' || p === 'openai';
+}
+export function getProviderSecrets(provider) {
+    const envKeys = fromEnv(provider);
+    if (envKeys.length > 0)
+        return { provider, keys: envKeys, source: 'env' };
+    const file = readKeysFile();
+    const fileKeys = file[provider] ?? [];
+    if (fileKeys.length > 0)
+        return { provider, keys: fileKeys, source: 'file' };
+    return null;
+}
+export function hasAnySecrets() {
+    for (const p of ['orbitx', 'groq', 'gemini', 'openrouter']) {
+        if (getProviderSecrets(p))
+            return true;
+    }
+    return false;
+}
+export function maskSecret(key) {
+    if (key.length <= 8)
+        return '•'.repeat(Math.min(key.length, 8));
+    return `${key.slice(0, 4)}••••••••${key.slice(-4)}`;
+}
+export function describeProvidersAvailable() {
+    const out = [];
+    for (const p of ['orbitx', 'groq', 'gemini', 'openrouter']) {
+        const s = getProviderSecrets(p);
+        if (s && s.keys[0])
+            out.push({ provider: p, masked: maskSecret(s.keys[0]), source: s.source });
+    }
+    return out;
+}
+/**
+ * Persist provider keys to the git-ignored keys.json (0600), merging over any
+ * existing keys so a re-run of the wizard never wipes other providers.
+ */
+export function writeKeys(provider, keys) {
+    const trimmed = keys.map((k) => k.trim()).filter(Boolean);
+    if (trimmed.length === 0)
+        return 'no keys provided';
+    const existing = readKeysFile();
+    existing[provider] = trimmed;
+    try {
+        mkdirSync(configDir(), { recursive: true });
+        writeFileSync(keysPath(), JSON.stringify(existing, null, 2), 'utf8');
+        chmodSync(keysPath(), 0o600);
+        invalidateKeysCache();
+        return null;
+    }
+    catch (err) {
+        return err.message;
+    }
+}

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

@@ -0,0 +1,10 @@
+/** Prefixed model id like "groq/llama-3.3-70b-versatile". */
+export function splitModelId(id) {
+    const idx = id.indexOf('/');
+    if (idx <= 0)
+        return { provider: 'orbitx', model: id };
+    return { provider: id.slice(0, idx), model: id.slice(idx + 1) };
+}
+export function joinModelId(provider, model) {
+    return `${provider}/${model}`;
+}

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

@@ -0,0 +1,74 @@
+import { AutoRouter } from '../llm/router.js';
+import { ContextManager } from '../context/context-manager.js';
+import { EventBus } from '../events.js';
+import { AgentLoop } from '../agent/agent-loop.js';
+/**
+ * Roles whose prompts are READ-ONLY guards. The AgentLoop's `readOnly` flag
+ * force-blocks edit_file/write_file/git_add/git_commit while still allowing
+ * run_shell (gated by the permission policy) — matching the role prompts.
+ */
+export const READONLY_ROLES = new Set(['architect', 'reviewer', 'security', 'researcher']);
+export function createDispatcher(deps) {
+    let seq = 0;
+    return async (req) => {
+        const role = deps.roles.get(req.role);
+        if (!role) {
+            return { ok: false, summary: `unknown role: ${req.role} (known: ${deps.roles.list().map((r) => r.id).join(', ')})` };
+        }
+        const id = `role_${req.role}_${++seq}`;
+        deps.registerRole?.(id);
+        let ok = false;
+        let summary = '(role agent produced no summary)';
+        try {
+            const assignment = { role: req.role, task: req.task, files: req.files, cwd: deps.cwd };
+            const prompt = role.buildSystemPrompt(assignment);
+            const model = role.defaultModel ?? deps.defaultModel;
+            const candidates = model ? [model.primary, ...(model.fallback ?? [])].filter(Boolean) : [];
+            const router = new AutoRouter(deps.providers, candidates, deps.strategy);
+            deps.bus?.emit('onAgentStart', { role: req.role, task: truncate(req.task, 140) });
+            const subContext = new ContextManager(prompt);
+            const loop = new AgentLoop({
+                bus: deps.bus ?? new EventBus(),
+                router,
+                context: subContext,
+                tools: deps.registry,
+                permissions: deps.permissions,
+                systemPrompt: prompt,
+                maxIterations: deps.maxIterations ?? 12,
+                timeoutMs: deps.toolTimeoutMs ?? 30_000,
+                streamTimeoutMs: deps.streamTimeoutMs ?? 120_000,
+                contextBudgetTokens: deps.contextBudgetTokens ?? 48_000,
+                cwd: deps.cwd,
+                readOnly: READONLY_ROLES.has(req.role),
+                reasoning: deps.reasoning,
+            });
+            const res = await loop.run(req.task);
+            const last = lastAssistantMessage(subContext.history());
+            const hasSummary = Boolean(last?.content.trim());
+            summary = hasSummary ? last.content.trim() : 'role agent finished without a summary';
+            ok = !res.interrupted && hasSummary;
+            deps.bus?.emit('onAgentEnd', { role: req.role, ok, summary: truncate(summary, 200) });
+            return { ok, summary };
+        }
+        catch (err) {
+            summary = `role agent crashed: ${err.message}`;
+            ok = false;
+            deps.bus?.emit('onAgentEnd', { role: req.role, ok: false, summary });
+            return { ok, summary };
+        }
+        finally {
+            deps.unregisterRole?.(id);
+        }
+    };
+}
+function lastAssistantMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role === 'assistant' && m.content.trim())
+            return m;
+    }
+    return undefined;
+}
+export function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n)}…`;
+}

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

@@ -0,0 +1,139 @@
+import { newId } from './types.js';
+export class Messenger {
+    mailboxes = new Map();
+    pending = new Map();
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    agentIds() {
+        return this.opts.getAgentIds();
+    }
+    /** Deliver a message. Returns the stored message. */
+    send(from, to, content, kind = 'message', replyTo) {
+        const ids = this.agentIds();
+        if (!ids.includes(to)) {
+            throw new Error(`unknown target agent: ${to} (known: ${ids.join(', ')} or 'user')`);
+        }
+        const msg = { id: newId(), from, to, kind, content, createdAt: Date.now(), replyTo };
+        const box = this.mailboxes.get(to) ?? [];
+        box.push(msg);
+        this.mailboxes.set(to, box);
+        this.tryResolvePending(to, msg);
+        this.opts.onMessage?.(msg);
+        return msg;
+    }
+    /** Interrupt a target: if it is running it will be aborted by the caller. */
+    interrupt(target, reason, from = 'user') {
+        return this.send(from, target, reason, 'interrupt');
+    }
+    mailboxLength(target) {
+        return this.mailboxes.get(target)?.length ?? 0;
+    }
+    hasPending(target) {
+        return this.mailboxLength(target) > 0;
+    }
+    /** Drain the target's mailbox (delivered in FIFO order). */
+    takePending(target) {
+        const box = this.mailboxes.get(target) ?? [];
+        this.mailboxes.set(target, []);
+        return box;
+    }
+    /** Peek the target's mailbox without draining it. */
+    pendingOf(target) {
+        return [...(this.mailboxes.get(target) ?? [])];
+    }
+    /** Park the caller until a reply from `replyFrom` arrives or timeout. */
+    waitForReply(from, replyFrom, timeoutMs, signal) {
+        // Bookkeeping request only — NOT delivered to the target's mailbox (a bare
+        // 'status' ping would pollute the peer's context; the waiter is resolved by
+        // the peer's real reply referencing it or by anyone-newer traffic).
+        const requestMsg = {
+            id: newId(),
+            from,
+            to: replyFrom,
+            kind: 'status',
+            content: '',
+            createdAt: Date.now(),
+        };
+        return new Promise((resolve, reject) => {
+            const req = { id: requestMsg.id, from, requestMsg, resolve, reject, createdAt: Date.now() };
+            const list = this.pending.get(from) ?? [];
+            list.push(req);
+            this.pending.set(from, list);
+            this.opts.onParked?.(from);
+            const timer = setTimeout(() => this.settle(from, req, reject, new Error(`timeout waiting for reply from ${replyFrom}`)), timeoutMs);
+            const onAbort = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                this.settle(from, req, reject, new Error('cancelled while waiting for reply'));
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    settle(from, req, reject, err) {
+        const list = this.pending.get(from);
+        if (!list)
+            return;
+        const idx = list.indexOf(req);
+        if (idx < 0)
+            return;
+        list.splice(idx, 1);
+        if (list.length === 0)
+            this.pending.delete(from);
+        reject(err);
+        // only resolved by us, not a real reply — still let the driver know
+        // we shouldn't call onMessage here (no message); driver polls instead.
+        this.opts.onUnparked?.(from);
+    }
+    tryResolvePending(to, incoming) {
+        // Waiters park under the parked agent's id (the `from` of the original
+        // request). A message that lands in `to`'s mailbox resolves waiters whose
+        // parked agent == `to`, provided the sender is not the waiter itself.
+        // When the waiter attached `replyTo`, only that request matches.
+        const entries = [...this.pending.entries()];
+        let reserved = false;
+        for (const [waiterAgent, list] of entries) {
+            if (list.length === 0)
+                continue;
+            const matches = list.filter((req) => {
+                if (req.from !== waiterAgent || waiterAgent !== to)
+                    return false;
+                if (incoming.from === waiterAgent)
+                    return false;
+                return incoming.replyTo ? incoming.replyTo === req.id : true;
+            });
+            if (matches.length === 0)
+                continue;
+            for (const req of matches) {
+                const idx = list.indexOf(req);
+                if (idx >= 0)
+                    list.splice(idx, 1);
+                req.resolve(incoming);
+                this.opts.onUnparked?.(waiterAgent);
+            }
+            reserved = true;
+            if (list.length === 0)
+                this.pending.delete(waiterAgent);
+        }
+        // The reply was consumed by a waiting parker — do not redeliver it when
+        // the agent later drains its mailbox.
+        if (reserved) {
+            const box = this.mailboxes.get(to);
+            if (box) {
+                const ix = box.indexOf(incoming);
+                if (ix >= 0)
+                    box.splice(ix, 1);
+            }
+        }
+    }
+    /** Agents currently parked waiting on a reply. */
+    parkedAgents() {
+        const out = [];
+        for (const [id, list] of this.pending) {
+            if (list.length > 0)
+                out.push(id);
+        }
+        return out;
+    }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Dynamic agent role registry. Roles are definitions — id, label, prompt
+ * builder, optional default model — NOT hardcoded switches in the runtime.
+ * Built-in roles ship here; `registerRole()` adds custom ones at runtime so
+ * the set stays extensible without touching orchestration code.
+ */
+function basePrompt(label, assignment) {
+    const scope = assignment.files && assignment.files.length > 0
+        ? `\nRelevant files (focus here, do not wander):\n${assignment.files.map((f) => `  - ${f}`).join('\n')}`
+        : '';
+    return `You are orbit-agent's ${label} running as a terminal agent.
+
+# Operating environment
+Working directory: ${assignment.cwd}
+${scope}
+
+# Assignment
+${assignment.task}`;
+}
+function makeDef(id, label, description, body) {
+    return {
+        id,
+        label,
+        description,
+        buildSystemPrompt: (a) => `${basePrompt(label, a)}\n\n${body}`,
+    };
+}
+const READONLY_GUARD = `You are READ-ONLY. You cannot run shell commands or modify anything; only read, search, and inspect (including git status/diff/log).`;
+const VERIFY_RULES = `- Run the project's checks (tests, typecheck, build) yourself before claiming success.
+- Do not modify unrelated files. Do not commit unless the assignment says so.
+- If genuinely blocked, say exactly what and why.`;
+const ROLE_DEFS = [
+    makeDef('architect', 'Architect', 'Designs implementation plans. Explores the codebase and produces precise, minimal plans: exact files, exact changes, order, verification steps.', `# Your job
+You design the implementation plan. Explore the code, identify how things fit together, and produce a precise, minimal plan: exact files, exact changes, and the order and verification steps.
+
+# Rules
+- ${READONLY_GUARD}
+- Base plans on evidence you actually read, never guesses.
+- Prefer the smallest changes that satisfy the assignment.
+- End with a section "## Plan" listing concrete steps with file paths.
+- Keep the final answer under ~60 lines.`),
+    makeDef('frontend', 'Frontend Developer', 'Implements frontend / UI work (React, Vue, styling, components, UX).', `# Your job
+You implement frontend / UI changes. Read before you edit, preserve existing conventions, and verify builds.
+
+# Rules
+- Read before you edit. Never write content you have not verified against the current file.
+- Prefer edit_file over write_file for surgical changes.
+- ${VERIFY_RULES}
+- End with "## Summary" listing what you changed and the verification you ran.`),
+    makeDef('backend', 'Backend Developer', 'Implements backend / API / data-layer work (servers, databases, contracts).', `# Your job
+You implement backend / API / data-layer changes. Read before you edit, preserve existing conventions, and verify builds.
+
+# Rules
+- Read before you edit. Never write content you have not verified against the current file.
+- Prefer edit_file over write_file for surgical changes.
+- ${VERIFY_RULES}
+- End with "## Summary" listing what you changed and the verification you ran.`),
+    makeDef('researcher', 'Researcher', 'Investigates code, docs, and external info. Returns findings, not edits.', `# Your job
+Investigate and report back findings: how parts fit together, what a library does, current behavior, risks. Do NOT implement changes.
+
+# Rules
+- READ-ONLY for modifications; you may run shell commands to inspect (tests, git grep already available).
+- Cite evidence: file:line, command output, or doc quotes. Never guess.
+- Keep the final answer focused and under ~50 lines.`),
+    makeDef('debugger', 'Debugger', 'Reproduces bugs, narrows the root cause, and reports it with a prescribed fix.', `# Your job
+Reproduce the bug, narrow the root cause, and report it precisely with a recommended fix. You may add temporary diagnostics if needed, but focus on root-cause analysis.
+
+# Rules
+- Reproduce first. Capture the failing command and output verbatim.
+- Use bisecting/greps to isolate the cause. Verify your hypothesis with an experiment.
+- Report root cause with file:line and a concrete recommended fix. If you are unsure, say so.
+- End with "## Diagnosis" and "## Recommended fix". Keep it under ~50 lines.`),
+    makeDef('tester', 'Tester', 'Writes and runs tests for the given change and reports coverage gaps.', `# Your job
+Write and run tests covering the given change. Report results and coverage gaps.
+
+# Rules
+- Read the project's test setup before writing tests; follow its conventions exactly.
+- Run the full relevant suite and report pass/fail counts verbatim.
+- Do not modify production code unless the assignment explicitly says so.
+- End with "## Test results" and "## Gaps".`),
+    makeDef('reviewer', 'Reviewer', 'Independently reviews changes against the assignment and returns a PASS/FAIL verdict.', `# Your job
+Independently review the changes against the assignment. Find real problems: bugs, regressions, architectural issues, missing tests, style drift. Do NOT rubber-stamp.
+
+# Rules
+- You are READ-ONLY for file contents (no edit_file/write_file) but MAY run shell commands to verify (tests, typecheck, diff, log).
+- Verify claims: if code was changed, run the relevant checks and quote the output.
+- Report concrete, actionable findings: file:line where possible, and the exact fix.
+- End with "## Verdict": PASS or FAIL, and if FAIL, a short list of required fixes.`),
+    makeDef('security', 'Security Reviewer', 'Reviews changes for security issues (auth, injection, secrets, untrusted input).', `# Your job
+Review the given code for security issues: injection, broken auth/z, secret handling, unsafe deserialization, path traversal, SSRF, denial-of-service.
+
+# Rules
+- READ-ONLY; you may run inspection commands (grep, git diff/log) to trace data flow.
+- For each finding include severity (critical/high/medium/low), file:line, exploit sketch, and the concrete fix.
+- End with "## Verdict": PASS or FAIL, and if FAIL a short list of required fixes.`),
+];
+const DEFAULT_ROLE_MODELS = {};
+export class RoleRegistry {
+    roles = new Map();
+    constructor() {
+        for (const def of ROLE_DEFS) {
+            const d = DEFAULT_ROLE_MODELS[def.id];
+            this.register(def.id, def.label, def.description, def.buildSystemPrompt, d);
+        }
+    }
+    register(id, label, description, buildSystemPrompt, defaultModel) {
+        this.roles.set(id, { id, label, description, buildSystemPrompt, defaultModel });
+    }
+    registerRole(def) {
+        const existing = this.roles.get(def.id);
+        this.roles.set(def.id, { ...existing, ...def });
+    }
+    get(roleId) {
+        return this.roles.get(roleId);
+    }
+    has(roleId) {
+        return this.roles.has(roleId);
+    }
+    all() {
+        return [...this.roles.values()];
+    }
+    buildSystemPrompt(roleId, assignment) {
+        return this.roles.get(roleId)?.buildSystemPrompt(assignment) ?? null;
+    }
+    list() {
+        return this.all().map((d) => ({ id: d.id, label: d.label, description: d.description }));
+    }
+}
+export const builtInRoleIds = ROLE_DEFS.map((d) => d.id);

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

@@ -0,0 +1,122 @@
+import { AutoRouter } from '../llm/router.js';
+import { ContextManager } from '../context/context-manager.js';
+import { EventBus } from '../events.js';
+import { AgentLoop } from '../agent/agent-loop.js';
+const FORWARDED_EVENTS = [
+    'onUserMessage',
+    'onAssistantStart',
+    'onThinking',
+    'onToken',
+    'onToolStart',
+    'onToolUpdate',
+    'onToolEnd',
+    'onAssistantEnd',
+    'onError',
+    'onRoute',
+    'onStatus',
+    'onAgentStart',
+    'onAgentEnd',
+    'onContextSummary',
+];
+/**
+ * AgentRuntime — one full agent in an orchestration session.
+ * Owns a per-agent router (per-agent model assignment), an isolated
+ * ContextManager, its own EventBus that fans out to the public session bus,
+ * and an AgentLoop it can (re)start and abort per turn.
+ */
+export class AgentRuntime {
+    opts;
+    identity;
+    bus = new EventBus();
+    router;
+    context;
+    loop = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.identity = opts.identity;
+        this.router = new AutoRouter(opts.providers, concatCandidates(opts.model), opts.strategy);
+        this.context = new ContextManager(opts.systemPrompt);
+        if (opts.bus) {
+            for (const name of FORWARDED_EVENTS) {
+                this.bus.on(name, (arg) => opts.bus.emit(name, arg));
+            }
+        }
+    }
+    get label() {
+        return this.opts.label;
+    }
+    get modelId() {
+        return this.opts.model.primary;
+    }
+    get candidateList() {
+        return this.router.candidateList;
+    }
+    /** True while a loop is running (active or parked waiting for a reply). */
+    get isRunning() {
+        return this.loop !== null;
+    }
+    get mail() {
+        return this.opts.messenger.mailboxLength(this.identity.id);
+    }
+    async run(input) {
+        this.loop = new AgentLoop(this.loopOpts());
+        try {
+            return await this.loop.run(input);
+        }
+        finally {
+            this.loop = null;
+        }
+    }
+    abort() {
+        this.loop?.abort();
+    }
+    loopOpts() {
+        const o = this.opts;
+        return {
+            bus: this.bus,
+            router: this.router,
+            context: this.context,
+            tools: o.tools,
+            permissions: o.permissions,
+            systemPrompt: o.systemPrompt,
+            maxIterations: o.maxIterations ?? 16,
+            maxDelegations: o.maxDelegations ?? 6,
+            contextBudgetTokens: o.contextBudgetTokens ?? 48_000,
+            timeoutMs: o.toolTimeoutMs ?? 30_000,
+            streamTimeoutMs: o.streamTimeoutMs ?? 120_000,
+            cwd: o.cwd,
+            readOnly: o.readOnly ?? false,
+            delegate: o.delegate,
+            maxTokensPerSecond: o.maxTokensPerSecond,
+            reasoning: o.reasoning,
+            toolContextExtras: this.toolContextExtras(),
+        };
+    }
+    toolContextExtras() {
+        const id = this.identity.id;
+        const { messenger, shared } = this.opts;
+        return {
+            agent: {
+                send: (to, content, kind = 'message') => {
+                    const msg = messenger.send(id, to, content, kind);
+                    return String(msg.id);
+                },
+                waitForReply: (from, timeoutMs) => messenger.waitForReply(id, from, timeoutMs, this.loop?.runSignal).then((m) => m.content),
+                interrupt: (target, reason) => {
+                    messenger.interrupt(target, reason, id);
+                },
+            },
+            shared: {
+                getFacts: () => shared.getFacts(),
+                addFact: (fact) => {
+                    shared.addFact(fact);
+                },
+                getJournal: (depth) => shared.getJournal(depth),
+                getExcerptForSelf: () => shared.excerptFor(id),
+            },
+        };
+    }
+}
+function concatCandidates(model) {
+    return [model.primary, ...(model.fallback ?? [])].filter(Boolean);
+}