infinicode 2.3.5 → 2.4.0

package/dist/kernel/agents/backends/parse-utils.js

@@ -0,0 +1,72 @@
+/**
+ * OpenKernel — Backend output parsing helpers
+ *
+ * Third-party CLIs emit different JSON shapes (and different versions change
+ * them), so parsing is deliberately defensive: try JSON, pull the common
+ * fields, and always fall back to raw text. Nothing here throws.
+ */
+export function tryJson(line) {
+    const s = line.trim();
+    if (!s || (s[0] !== '{' && s[0] !== '['))
+        return null;
+    try {
+        const v = JSON.parse(s);
+        return v && typeof v === 'object' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function str(v) {
+    return typeof v === 'string' && v.length ? v : undefined;
+}
+/** Append a line to an accumulating text body. */
+export function appendLine(acc, line) {
+    return acc ? `${acc}\n${line}` : line;
+}
+/**
+ * Pull assistant text out of a wide range of JSON event shapes:
+ * Anthropic/Claude content arrays, plain `content` strings, and the usual
+ * `text`/`response`/`result`/`message` fields other CLIs use.
+ */
+export function extractText(obj) {
+    const msg = obj.message;
+    const content = (msg?.content ?? obj.content);
+    if (Array.isArray(content)) {
+        const parts = content
+            .map(c => (c && typeof c === 'object' && c.type === 'text'
+            ? str(c.text)
+            : undefined))
+            .filter((t) => !!t);
+        if (parts.length)
+            return parts.join('');
+    }
+    if (typeof content === 'string' && content.length)
+        return content;
+    for (const k of ['text', 'response', 'result', 'output', 'answer']) {
+        const t = str(obj[k]);
+        if (t)
+            return t;
+    }
+    if (msg) {
+        const t = str(msg.text) ?? str(msg.content);
+        if (t)
+            return t;
+    }
+    return undefined;
+}
+const UUID_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+/** Common session-id keys across the CLIs, plus a bare-UUID fallback. */
+export function extractSessionId(obj) {
+    return (str(obj.session_id) ??
+        str(obj.sessionID) ??
+        str(obj.sessionId) ??
+        str(obj.thread_id) ??
+        str(obj.conversation_id) ??
+        str(obj.session) ??
+        str(obj.id));
+}
+export function sessionIdFromText(line) {
+    const m = line.match(UUID_RE);
+    return m ? m[0] : undefined;
+}

package/dist/kernel/agents/backends/profiles.d.ts

@@ -0,0 +1,67 @@
+/**
+ * OpenKernel — Coder profiles
+ *
+ * A *profile* is a named, reusable coder configuration: which backend CLI to
+ * run (claude / codex / opencode / gemini), which model, and any extra args/env.
+ * Profiles are what the rotation engine (see `rotation.ts`) chooses between, so
+ * the orchestrator can say "run this on the `deep` profile" or "rotate across
+ * the cheap tier" without hard-coding a backend + model at every call site.
+ *
+ * Profiles carry lightweight cost/speed/quality metadata so a policy tier
+ * (free-first / fastest / highest-quality / …) can order them, plus `tags` a
+ * task-type router can match against.
+ *
+ * Config lives under `coder` in the node config; anything omitted falls back to
+ * the built-in defaults below so the mesh works out of the box.
+ */
+import type { BackendId } from './types.js';
+/** A named coder configuration the rotation engine can select. */
+export interface CoderProfile {
+    /** Stable name, e.g. "deep", "cheap". Filled in by the loader from the map key. */
+    name: string;
+    /** Which CLI backend runs it. */
+    backend: BackendId;
+    /** Model id in that backend's native format (e.g. "opus", "gpt-5-codex"). */
+    model?: string;
+    /** Extra CLI args appended for this profile (via the backend's ARGS env). */
+    args?: string[];
+    /** Extra process env for this profile. */
+    env?: Record<string, string>;
+    /** Relative $ per task — lower is cheaper. Used by cost policies. */
+    cost?: number;
+    /** Relative throughput — higher is faster. Used by the `fastest` policy. */
+    speed?: number;
+    /** Relative capability — higher is stronger. Used by `highest-quality`. */
+    quality?: number;
+    /** Task-type tags this profile is a good fit for (matched by the router). */
+    tags?: string[];
+}
+export type RotationStrategy = 'auto' | 'tasktype' | 'policy' | 'roundrobin' | 'fallback';
+export type CoderPolicy = 'free-first' | 'cheapest' | 'fastest' | 'highest-quality' | 'balanced';
+/** The `coder` config block. Everything is optional; defaults fill the gaps. */
+export interface CoderConfig {
+    profiles: Record<string, CoderProfile>;
+    /** Default ordered profile names used by roundrobin/fallback. */
+    rotation: string[];
+    /** Default strategy when a caller doesn't specify one. */
+    strategy: RotationStrategy;
+    /** Default policy when strategy resolves to policy ordering. */
+    policy: CoderPolicy;
+    /** Task-type → ordered profile names (task-type routing). */
+    routes: Record<string, string[]>;
+    /** Fallback profile when nothing else matches. */
+    defaultProfile: string;
+}
+/**
+ * Built-in profiles — one per backend plus a couple of tiers. Models are the
+ * common ids; override in config for your accounts. `cost`/`speed`/`quality`
+ * are relative (1–10) and only used to order policy tiers.
+ */
+export declare const DEFAULT_PROFILES: Record<string, CoderProfile>;
+/**
+ * Merge a raw `coder` config object (from node config) over the built-in
+ * defaults, filling `name` from the map key. Safe to call with `undefined`.
+ */
+export declare function loadCoderConfig(raw?: Partial<CoderConfig> & {
+    profiles?: Record<string, Partial<CoderProfile>>;
+}): CoderConfig;

package/dist/kernel/agents/backends/profiles.js

@@ -0,0 +1,48 @@
+/**
+ * Built-in profiles — one per backend plus a couple of tiers. Models are the
+ * common ids; override in config for your accounts. `cost`/`speed`/`quality`
+ * are relative (1–10) and only used to order policy tiers.
+ */
+export const DEFAULT_PROFILES = {
+    deep: { name: 'deep', backend: 'claude', model: 'opus', cost: 9, speed: 4, quality: 10, tags: ['refactor', 'architecture', 'debug', 'hard'] },
+    fast: { name: 'fast', backend: 'claude', model: 'sonnet', cost: 5, speed: 7, quality: 8, tags: ['edit', 'feature', 'test'] },
+    precise: { name: 'precise', backend: 'codex', model: 'gpt-5-codex', cost: 6, speed: 6, quality: 8, tags: ['precision', 'polyglot', 'fix'] },
+    cheap: { name: 'cheap', backend: 'gemini', model: 'gemini-2.5-flash', cost: 1, speed: 9, quality: 6, tags: ['bulk', 'docs', 'boilerplate', 'cheap'] },
+    oss: { name: 'oss', backend: 'opencode', cost: 2, speed: 6, quality: 6, tags: ['fallback', 'oss'] },
+};
+/** Default rotation across all four backends (balances cost + capability). */
+const DEFAULT_ROTATION = ['fast', 'precise', 'cheap', 'oss', 'deep'];
+/** Sensible task-type routes → ordered profiles (head is primary, rest fallback). */
+const DEFAULT_ROUTES = {
+    refactor: ['deep', 'precise', 'fast'],
+    architecture: ['deep', 'fast'],
+    debug: ['deep', 'precise', 'fast'],
+    feature: ['fast', 'precise', 'deep'],
+    edit: ['fast', 'cheap', 'precise'],
+    test: ['fast', 'precise'],
+    docs: ['cheap', 'fast'],
+    bulk: ['cheap', 'oss', 'fast'],
+    boilerplate: ['cheap', 'oss'],
+    fix: ['precise', 'fast', 'deep'],
+};
+/**
+ * Merge a raw `coder` config object (from node config) over the built-in
+ * defaults, filling `name` from the map key. Safe to call with `undefined`.
+ */
+export function loadCoderConfig(raw) {
+    const profiles = {};
+    const merged = { ...DEFAULT_PROFILES, ...(raw?.profiles ?? {}) };
+    for (const [key, p] of Object.entries(merged)) {
+        if (!p?.backend)
+            continue; // a profile must name a backend
+        profiles[key] = { ...(DEFAULT_PROFILES[key] ?? {}), ...p, name: key, backend: p.backend };
+    }
+    return {
+        profiles,
+        rotation: (raw?.rotation ?? DEFAULT_ROTATION).filter(n => profiles[n]),
+        strategy: raw?.strategy ?? 'auto',
+        policy: raw?.policy ?? 'balanced',
+        routes: { ...DEFAULT_ROUTES, ...(raw?.routes ?? {}) },
+        defaultProfile: raw?.defaultProfile && profiles[raw.defaultProfile] ? raw.defaultProfile : (profiles['fast'] ? 'fast' : Object.keys(profiles)[0]),
+    };
+}

package/dist/kernel/agents/backends/registry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenKernel — Agent Backend registry + built-in CLI specs
+ *
+ * Holds the executors a node can route a task to. 'kernel' (the native path) is
+ * always present and handled inline by the Federation manager; the CLI backends
+ * are advertised only when their binary is actually installed, so the mesh's
+ * compute-router won't send a `claude` task to a node without Claude Code.
+ *
+ * Each CLI is invoked in headless / non-interactive mode. Flags are the stable
+ * public ones for each tool; a device can override the binary or append args via
+ * env (INFINICODE_<CLI>_BIN / INFINICODE_<CLI>_ARGS) without a code change.
+ */
+import type { AgentBackend, BackendId } from './types.js';
+import { type CliBackendSpec } from './cli-backend.js';
+declare const CLAUDE_SPEC: CliBackendSpec;
+declare const OPENCODE_SPEC: CliBackendSpec;
+declare const CODEX_SPEC: CliBackendSpec;
+declare const GEMINI_SPEC: CliBackendSpec;
+export declare class AgentBackendRegistry {
+    private map;
+    register(backend: AgentBackend): this;
+    get(id: BackendId): AgentBackend | undefined;
+    /** True if this node can run `id` (the native kernel, or an installed CLI). */
+    has(id: BackendId): boolean;
+    all(): AgentBackend[];
+    /** Backend ids runnable here — 'kernel' plus every installed CLI. */
+    availableIds(): BackendId[];
+}
+/** Registry seeded with the built-in CLI backends (availability checked lazily). */
+export declare function createDefaultBackendRegistry(): AgentBackendRegistry;
+export { CLAUDE_SPEC, OPENCODE_SPEC, CODEX_SPEC, GEMINI_SPEC };

package/dist/kernel/agents/backends/registry.js

@@ -0,0 +1,174 @@
+import { CliAgentBackend } from './cli-backend.js';
+import { tryJson, extractText, extractSessionId, sessionIdFromText } from './parse-utils.js';
+// ── Claude Code ──────────────────────────────────────────────────────────────
+// `claude -p` = headless print mode. stream-json emits JSONL: a system/init
+// object carrying session_id, assistant messages, then a terminal `result`.
+const CLAUDE_SPEC = {
+    id: 'claude',
+    displayName: 'Claude Code',
+    bin: 'claude',
+    binEnv: 'INFINICODE_CLAUDE_BIN',
+    extraArgsEnv: 'INFINICODE_CLAUDE_ARGS',
+    runArgs: (prompt, task) => [
+        '-p', prompt,
+        ...(task.model ? ['--model', task.model] : []),
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--dangerously-skip-permissions',
+    ],
+    resumeArgs: (sessionId, message, task) => [
+        '--resume', sessionId,
+        '-p', message,
+        ...(task.model ? ['--model', task.model] : []),
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--dangerously-skip-permissions',
+    ],
+    parseLine: (line, acc) => {
+        const obj = tryJson(line);
+        if (!obj)
+            return;
+        const sid = extractSessionId(obj);
+        if (sid)
+            acc.sessionId = sid;
+        if (obj.type === 'result') {
+            const t = extractText(obj);
+            if (t)
+                acc.content = t;
+            if (obj.is_error === true)
+                acc.isError = true;
+            if (typeof obj.subtype === 'string' && obj.subtype !== 'success')
+                acc.isError = true;
+        }
+    },
+};
+// ── OpenCode ─────────────────────────────────────────────────────────────────
+// `opencode run "<task>" --format json` — non-interactive, resumable by session.
+const OPENCODE_SPEC = {
+    id: 'opencode',
+    displayName: 'OpenCode',
+    bin: 'opencode',
+    binEnv: 'INFINICODE_OPENCODE_BIN',
+    extraArgsEnv: 'INFINICODE_OPENCODE_ARGS',
+    runArgs: (prompt, task) => [
+        'run', prompt,
+        '--format', 'json',
+        ...(task.model ? ['--model', task.model] : []),
+        '--dangerously-skip-permissions',
+    ],
+    resumeArgs: (sessionId, message, task) => [
+        'run', message,
+        '--format', 'json',
+        '--session', sessionId,
+        ...(task.model ? ['--model', task.model] : []),
+        '--dangerously-skip-permissions',
+    ],
+    parseLine: (line, acc) => {
+        const obj = tryJson(line);
+        if (!obj)
+            return;
+        const sid = extractSessionId(obj);
+        if (sid)
+            acc.sessionId ??= sid;
+        const t = extractText(obj);
+        if (t)
+            acc.content = t;
+        if (obj.error)
+            acc.isError = true;
+    },
+};
+// ── Codex ────────────────────────────────────────────────────────────────────
+// `codex exec "<prompt>"` = non-interactive. Output shape varies by version, so
+// parse defensively: JSON when present, otherwise accumulate text + sniff a UUID.
+const CODEX_SPEC = {
+    id: 'codex',
+    displayName: 'Codex',
+    bin: 'codex',
+    binEnv: 'INFINICODE_CODEX_BIN',
+    extraArgsEnv: 'INFINICODE_CODEX_ARGS',
+    runArgs: (prompt, task) => ['exec', ...(task.model ? ['--model', task.model] : []), prompt],
+    resumeArgs: (sessionId, message) => ['exec', 'resume', sessionId, message],
+    parseLine: (line, acc) => {
+        const obj = tryJson(line);
+        if (obj) {
+            const sid = extractSessionId(obj);
+            if (sid)
+                acc.sessionId ??= sid;
+            const t = extractText(obj);
+            if (t)
+                acc.content = t;
+            if (obj.error || obj.is_error === true)
+                acc.isError = true;
+            return;
+        }
+        const sid = sessionIdFromText(line);
+        if (sid)
+            acc.sessionId ??= sid;
+        acc.content = acc.content ? `${acc.content}\n${line}` : line;
+    },
+};
+// ── Gemini ───────────────────────────────────────────────────────────────────
+// `gemini -p "<prompt>"` = non-interactive. `-y` (yolo) auto-approves tool
+// actions. Output is plain text by default, so parse defensively: JSON when a
+// tool version emits it, otherwise accumulate the printed answer.
+const GEMINI_SPEC = {
+    id: 'gemini',
+    displayName: 'Gemini CLI',
+    bin: 'gemini',
+    binEnv: 'INFINICODE_GEMINI_BIN',
+    extraArgsEnv: 'INFINICODE_GEMINI_ARGS',
+    runArgs: (prompt, task) => [
+        ...(task.model ? ['-m', task.model] : []),
+        '-y',
+        '-p', prompt,
+    ],
+    parseLine: (line, acc) => {
+        const obj = tryJson(line);
+        if (obj) {
+            const sid = extractSessionId(obj);
+            if (sid)
+                acc.sessionId ??= sid;
+            const t = extractText(obj);
+            if (t)
+                acc.content = t;
+            if (obj.error || obj.is_error === true)
+                acc.isError = true;
+            return;
+        }
+        acc.content = acc.content ? `${acc.content}\n${line}` : line;
+    },
+};
+export class AgentBackendRegistry {
+    map = new Map();
+    register(backend) {
+        this.map.set(backend.id, backend);
+        return this;
+    }
+    get(id) {
+        return this.map.get(id);
+    }
+    /** True if this node can run `id` (the native kernel, or an installed CLI). */
+    has(id) {
+        if (id === 'kernel')
+            return true;
+        const b = this.map.get(id);
+        return !!b && b.available();
+    }
+    all() {
+        return [...this.map.values()];
+    }
+    /** Backend ids runnable here — 'kernel' plus every installed CLI. */
+    availableIds() {
+        const cli = this.all().filter(b => b.available()).map(b => b.id);
+        return ['kernel', ...cli];
+    }
+}
+/** Registry seeded with the built-in CLI backends (availability checked lazily). */
+export function createDefaultBackendRegistry() {
+    return new AgentBackendRegistry()
+        .register(new CliAgentBackend(CLAUDE_SPEC))
+        .register(new CliAgentBackend(OPENCODE_SPEC))
+        .register(new CliAgentBackend(CODEX_SPEC))
+        .register(new CliAgentBackend(GEMINI_SPEC));
+}
+export { CLAUDE_SPEC, OPENCODE_SPEC, CODEX_SPEC, GEMINI_SPEC };

package/dist/kernel/agents/backends/rotation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OpenKernel — Coder rotation engine
+ *
+ * Turns a dispatch request into an *ordered chain* of concrete backend configs.
+ * The four strategies are not alternatives you pick between — they compose:
+ *
+ *   1. task-type routing / policy tier  → choose WHICH profiles and their order
+ *   2. round-robin                      → choose WHERE in that set to start
+ *   3. fallback                         → the returned order IS the retry chain
+ *
+ * The caller runs the head; if it fails, it walks to the next entry. Because an
+ * uninstalled backend simply reports "not available" (a failure), availability
+ * filtering falls out of fallback for free — no need to know remote state here.
+ */
+import type { BackendId } from './types.js';
+import type { CoderConfig, CoderPolicy, RotationStrategy } from './profiles.js';
+/** What the orchestrator asks for. All fields optional — defaults come from config. */
+export interface SelectRequest {
+    /** Force a strategy; otherwise config.strategy (default 'auto'). */
+    strategy?: RotationStrategy;
+    /** Pin an explicit profile by name (still yields config fallbacks behind it). */
+    profile?: string;
+    /** Pin an explicit backend (legacy path — no rotation, exact behaviour as before). */
+    backend?: BackendId;
+    /** Model override applied to the chain head. */
+    model?: string;
+    /** Task-type key for routing (e.g. 'refactor', 'docs'). */
+    taskType?: string;
+    /** Policy tier for ordering when strategy is policy/auto. */
+    policy?: CoderPolicy;
+}
+/** A concrete, directly-runnable backend selection. */
+export interface ResolvedBackend {
+    backend: BackendId;
+    model?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    profileName?: string;
+}
+/** Per-node round-robin cursor, keyed by candidate-set signature. */
+export declare class RotationState {
+    private cursors;
+    /** Advance and return the starting offset for a candidate set of length `len`. */
+    next(key: string, len: number): number;
+}
+/**
+ * Build the ordered backend chain for a request. The head is what to run; the
+ * remainder is the fallback order. Always returns at least one entry (falls back
+ * to the config default profile, then any profile, then a bare 'claude').
+ */
+export declare function selectChain(cfg: CoderConfig, req: SelectRequest, state: RotationState): ResolvedBackend[];

package/dist/kernel/agents/backends/rotation.js

@@ -0,0 +1,107 @@
+/** Per-node round-robin cursor, keyed by candidate-set signature. */
+export class RotationState {
+    cursors = new Map();
+    /** Advance and return the starting offset for a candidate set of length `len`. */
+    next(key, len) {
+        if (len <= 0)
+            return 0;
+        const cur = this.cursors.get(key) ?? 0;
+        this.cursors.set(key, (cur + 1) % len);
+        return cur % len;
+    }
+}
+function profileToBackend(p) {
+    return { backend: p.backend, model: p.model, args: p.args, env: p.env, profileName: p.name };
+}
+/** Order profile names by a policy tier (returns a fresh array). */
+function orderByPolicy(names, profiles, policy) {
+    const val = (n) => {
+        const p = profiles[n];
+        if (!p)
+            return -Infinity;
+        switch (policy) {
+            case 'free-first':
+            case 'cheapest': return -(p.cost ?? 5); // lower cost first
+            case 'fastest': return (p.speed ?? 5); // higher speed first
+            case 'highest-quality': return (p.quality ?? 5); // higher quality first
+            case 'balanced': return (p.quality ?? 5) + (p.speed ?? 5) - (p.cost ?? 5);
+        }
+    };
+    return [...names].sort((a, b) => val(b) - val(a));
+}
+/** Rotate a list so it starts at `offset` (wrapping), preserving relative order. */
+function rotate(list, offset) {
+    if (list.length <= 1)
+        return [...list];
+    const i = ((offset % list.length) + list.length) % list.length;
+    return [...list.slice(i), ...list.slice(0, i)];
+}
+/** De-dupe by backend+model+profile so the chain never retries the identical config. */
+function dedupe(chain) {
+    const seen = new Set();
+    const out = [];
+    for (const r of chain) {
+        const key = `${r.backend}|${r.model ?? ''}|${r.profileName ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(r);
+    }
+    return out;
+}
+/**
+ * Build the ordered backend chain for a request. The head is what to run; the
+ * remainder is the fallback order. Always returns at least one entry (falls back
+ * to the config default profile, then any profile, then a bare 'claude').
+ */
+export function selectChain(cfg, req, state) {
+    const { profiles } = cfg;
+    // 1. Explicit backend pin — legacy exact behaviour, no rotation.
+    if (req.backend && req.backend !== 'kernel') {
+        return [{ backend: req.backend, model: req.model, profileName: undefined }];
+    }
+    // 2. Explicit profile pin — that profile first, then the rotation list behind it.
+    if (req.profile && profiles[req.profile]) {
+        const head = profileToBackend(profiles[req.profile]);
+        if (req.model)
+            head.model = req.model;
+        const rest = cfg.rotation.map(n => profiles[n]).filter(Boolean).map(profileToBackend);
+        return dedupe([head, ...rest]);
+    }
+    const strategy = req.strategy ?? cfg.strategy;
+    // 3. Determine the candidate set + its base order.
+    let names;
+    const routeNames = req.taskType ? cfg.routes[req.taskType] : undefined;
+    if ((strategy === 'tasktype' || strategy === 'auto') && routeNames?.length) {
+        names = routeNames.filter(n => profiles[n]);
+    }
+    else if (strategy === 'policy' || (strategy === 'auto' && req.policy)) {
+        names = orderByPolicy(cfg.rotation, profiles, req.policy ?? cfg.policy);
+    }
+    else {
+        names = cfg.rotation.filter(n => profiles[n]);
+    }
+    if (!names.length)
+        names = Object.keys(profiles);
+    // 4. Round-robin: advance the entry point across the candidate set. Applied for
+    //    roundrobin explicitly, and for 'auto' when neither routing nor policy pinned
+    //    a deliberate head (i.e. we're just cycling the default rotation).
+    const rotateEntry = strategy === 'roundrobin' ||
+        (strategy === 'auto' && !routeNames?.length && !req.policy);
+    if (rotateEntry) {
+        const offset = state.next(names.join(','), names.length);
+        names = rotate(names, offset);
+    }
+    // 5. Map to concrete backends; apply model override to the head only.
+    const chain = names.map(n => profileToBackend(profiles[n]));
+    if (req.model && chain[0])
+        chain[0] = { ...chain[0], model: req.model };
+    const deduped = dedupe(chain);
+    if (deduped.length)
+        return deduped;
+    // 6. Last-resort fallbacks.
+    const def = profiles[cfg.defaultProfile];
+    if (def)
+        return [profileToBackend(def)];
+    return [{ backend: 'claude', model: req.model }];
+}

package/dist/kernel/agents/backends/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * OpenKernel — Agent Backend types
+ *
+ * A backend is *who actually runs a dispatched task* on a node. The mesh's
+ * default backend is the local kernel (`kernel.execute`), but a node can also
+ * run a third-party coding CLI — Claude Code, Codex, OpenCode — as the executor.
+ * That is what lets a task dispatched across the mesh be fulfilled by a real
+ * external agent, and (with a persisted session id) lets those agents be
+ * messaged again later.
+ *
+ * Everything here is transport-agnostic: the Federation manager owns spawning +
+ * streaming; a backend just knows how to drive one CLI and parse its output.
+ */
+import type { Capability } from '../../types.js';
+/** Identifier of a backend. 'kernel' is the built-in native path. */
+export type BackendId = 'kernel' | 'claude' | 'codex' | 'opencode' | 'gemini' | (string & {});
+/** A unit of work handed to a backend. */
+export interface BackendTask {
+    prompt: string;
+    capabilities?: Capability[];
+    /** Optional model hint (provider/model or a CLI-native model id). */
+    model?: string;
+    /** Extra CLI args for this run (e.g. from a coder profile). Appended verbatim. */
+    args?: string[];
+    /** Resume an existing CLI session instead of starting fresh. */
+    sessionId?: string;
+}
+/** A streamed activity fragment emitted while a backend runs. */
+export interface BackendFrame {
+    kind: 'log' | 'event' | 'output' | 'error';
+    text?: string;
+    data?: unknown;
+}
+/** Context passed to a backend run — where to stream, how to cancel. */
+export interface BackendRunContext {
+    runId: string;
+    /** Called for each activity fragment (streamed up the mesh SSE feed). */
+    onFrame: (frame: BackendFrame) => void;
+    /** Abort the underlying process. */
+    signal?: AbortSignal;
+    /** Working directory for the spawned CLI (defaults to process.cwd()). */
+    cwd?: string;
+    /** Persistent device role, prepended to the prompt so the agent is in-character. */
+    rolePreamble?: string;
+}
+/** Terminal result of a backend run. */
+export interface BackendRunResult {
+    status: 'completed' | 'failed';
+    /** The CLI's native session id — enables resume + later messaging. */
+    sessionId?: string;
+    /** Final assistant text, if captured. */
+    content?: string;
+    error?: string;
+}
+/** Drives one executor (a CLI or the native kernel). */
+export interface AgentBackend {
+    id: BackendId;
+    displayName: string;
+    /** True when this backend can run here (e.g. the CLI is on PATH). Sync + cheap. */
+    available(): boolean;
+    /** Run a task to completion, streaming frames along the way. */
+    run(task: BackendTask, ctx: BackendRunContext): Promise<BackendRunResult>;
+    /** Send a follow-up message into an existing session (mailbox — slice 2). */
+    send?(sessionId: string, message: string, ctx: BackendRunContext): Promise<BackendRunResult>;
+    /** Best-effort stop of a running session. */
+    stop?(sessionId: string): Promise<void>;
+}

package/dist/kernel/agents/backends/types.js

@@ -0,0 +1 @@
+export {};

package/dist/kernel/agents/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * OpenKernel — Agents public API
+ *
+ * How a task actually gets run on a node: the native kernel, or a third-party
+ * coding CLI acting as the executor (so a mesh-dispatched task can be fulfilled
+ * by Claude Code, Codex, or OpenCode).
+ */
+export * from './backends/index.js';

package/dist/kernel/agents/index.js

@@ -0,0 +1,8 @@
+/**
+ * OpenKernel — Agents public API
+ *
+ * How a task actually gets run on a node: the native kernel, or a third-party
+ * coding CLI acting as the executor (so a mesh-dispatched task can be fulfilled
+ * by Claude Code, Codex, or OpenCode).
+ */
+export * from './backends/index.js';