@9thprotocol/agent-core 0.1.0

package/dist/model/openrouter.d.ts

@@ -0,0 +1,61 @@
+import type { UsageTotals } from "../types.js";
+/** Non-2xx from OpenRouter or the platform proxy, with the platform's error code when present. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export interface RawToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export type ChatMessage = {
+    role: "system" | "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: RawToolCall[];
+} | {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+};
+export interface ToolSchema {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface AssistantResult {
+    message: Extract<ChatMessage, {
+        role: "assistant";
+    }>;
+    usage: UsageTotals;
+    finishReason: string | null;
+}
+export type StreamEvent = {
+    type: "delta";
+    text: string;
+} | {
+    type: "done";
+    result: AssistantResult;
+};
+/** One streaming chat completion with tool support. Yields text deltas, then `done`. */
+export declare function streamChat(opts: {
+    apiKey: string;
+    model: string;
+    messages: ChatMessage[];
+    tools: ToolSchema[];
+    signal?: AbortSignal;
+    /** Override the OpenRouter base URL (e.g. the 9th Protocol metering proxy). */
+    baseUrl?: string;
+    /** Extra top-level body fields (e.g. platform `context`). */
+    extraBody?: Record<string, unknown>;
+}): AsyncGenerator<StreamEvent>;

package/dist/model/openrouter.js

@@ -0,0 +1,135 @@
+const BASE = "https://openrouter.ai/api/v1";
+/** Non-2xx from OpenRouter or the platform proxy, with the platform's error code when present. */
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * Anthropic models honor prompt caching via cache_control breakpoints; marking the
+ * system prompt caches the stable prefix (cache reads are 5-10x cheaper than input).
+ */
+function withCaching(model, messages) {
+    if (!model.startsWith("anthropic/"))
+        return messages;
+    return messages.map((m) => m.role === "system"
+        ? {
+            role: "system",
+            content: [
+                { type: "text", text: m.content, cache_control: { type: "ephemeral" } },
+            ],
+        }
+        : m);
+}
+/** One streaming chat completion with tool support. Yields text deltas, then `done`. */
+export async function* streamChat(opts) {
+    const res = await fetch(`${opts.baseUrl ?? BASE}/chat/completions`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            "Content-Type": "application/json",
+            "X-Title": "9th Protocol",
+        },
+        signal: opts.signal,
+        body: JSON.stringify({
+            model: opts.model,
+            messages: withCaching(opts.model, opts.messages),
+            tools: opts.tools,
+            stream: true,
+            usage: { include: true },
+            ...opts.extraBody,
+        }),
+    });
+    if (!res.ok || !res.body) {
+        const text = await res.text();
+        let code;
+        let message = text;
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.error === "string")
+                code = parsed.error;
+            if (typeof parsed.message === "string")
+                message = parsed.message;
+        }
+        catch {
+            // non-JSON error body
+        }
+        throw new ApiError(res.status, `${res.status}: ${message}`, code);
+    }
+    let text = "";
+    let finishReason = null;
+    const usage = { inputTokens: 0, cachedTokens: 0, outputTokens: 0, requests: 1 };
+    const calls = [];
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const reader = res.body.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line.startsWith("data: "))
+                continue; // ignore comments/keepalives
+            const payload = line.slice(6);
+            if (payload === "[DONE]")
+                continue;
+            let chunk;
+            try {
+                chunk = JSON.parse(payload);
+            }
+            catch {
+                continue; // partial/garbled line, skip
+            }
+            const choice = chunk.choices?.[0];
+            if (choice?.delta?.content) {
+                text += choice.delta.content;
+                yield { type: "delta", text: choice.delta.content };
+            }
+            for (const tc of choice?.delta?.tool_calls ?? []) {
+                const i = tc.index ?? 0;
+                let slot = calls[i];
+                if (!slot) {
+                    slot = { id: "", name: "", args: "" };
+                    calls[i] = slot;
+                }
+                if (tc.id)
+                    slot.id = tc.id;
+                if (tc.function?.name)
+                    slot.name = tc.function.name;
+                if (tc.function?.arguments)
+                    slot.args += tc.function.arguments;
+            }
+            if (choice?.finish_reason)
+                finishReason = choice.finish_reason;
+            if (chunk.usage) {
+                usage.inputTokens = chunk.usage.prompt_tokens ?? 0;
+                usage.outputTokens = chunk.usage.completion_tokens ?? 0;
+                usage.cachedTokens = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+            }
+        }
+    }
+    const tool_calls = calls
+        .filter((c) => Boolean(c && c.id && c.name))
+        .map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } }));
+    yield {
+        type: "done",
+        result: {
+            message: {
+                role: "assistant",
+                content: text || null,
+                ...(tool_calls.length ? { tool_calls } : {}),
+            },
+            usage,
+            finishReason,
+        },
+    };
+}
+//# sourceMappingURL=openrouter.js.map

package/dist/model/router.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `Auto` model routing, PLAN.md §5.5.
+ *
+ * v1 is pure heuristics, deliberately: the spec allows either a cheap classifier
+ * model or heuristics, and heuristics cost no extra call, add no latency, and
+ * cannot themselves fail. The classifier upgrade slots in behind `route()`
+ * without touching callers.
+ *
+ * The router only ever *proposes*; the API still enforces plan gating, so a
+ * locked pick would be rejected server-side. Hence `locked` candidates are
+ * filtered out before ranking rather than trusted to fail gracefully.
+ */
+export declare const AUTO_MODEL = "auto";
+export type RouterBias = "economy" | "balanced" | "quality";
+export type TaskComplexity = "trivial" | "normal" | "complex";
+export type ModelTier = "economy" | "standard" | "premium";
+export interface RouterCandidate {
+    id: string;
+    tier: ModelTier;
+    /** True when the user's plan cannot use this model (from GET /v1/models). */
+    locked?: boolean;
+    /** Context window, used to decide when to compact. */
+    contextLength?: number | null;
+}
+export interface RouteInput {
+    /** The user's message for this turn. */
+    text: string;
+    bias?: RouterBias;
+    /** Plan mode means "think, don't edit". Always treated as complex work. */
+    planMode?: boolean;
+    /** Explore sub-agents are read-only searchers; they never need a strong model. */
+    subagent?: "explore" | "general";
+    /** Catalog with per-plan locks. Empty = BYOK, where every id is fair game. */
+    available?: RouterCandidate[];
+}
+export interface RouteDecision {
+    model: string;
+    complexity: TaskComplexity;
+    reason: string;
+}
+/** What hosts show for an Auto session that has not routed a turn yet. */
+export declare const FALLBACK_DISPLAY_MODEL = "moonshotai/kimi-k2.7-code";
+/** Classify how much model the turn deserves. Exported for tests and debugging. */
+export declare function classify(text: string, planMode?: boolean): TaskComplexity;
+/**
+ * Choose a model for one turn.
+ *
+ * Order of precedence: explore sub-agents are pinned to economy, then bias
+ * shifts the classified complexity, then the ladder is filtered by plan locks.
+ */
+export declare function route(input: RouteInput): RouteDecision;
+/**
+ * Model for delegated I/O work (see `delegate.ts`).
+ *
+ * Reuses the trivial ladder rather than naming a model of its own, so the
+ * cheapest usable model stays defined in exactly one place and plan locks are
+ * honoured for free. Bulk reading and boilerplate are the definition of a
+ * trivial turn, which is why the ladder is already correct for it.
+ */
+export declare function workerModel(available?: RouterCandidate[]): string;

package/dist/model/router.js

@@ -0,0 +1,171 @@
+/**
+ * `Auto` model routing, PLAN.md §5.5.
+ *
+ * v1 is pure heuristics, deliberately: the spec allows either a cheap classifier
+ * model or heuristics, and heuristics cost no extra call, add no latency, and
+ * cannot themselves fail. The classifier upgrade slots in behind `route()`
+ * without touching callers.
+ *
+ * The router only ever *proposes*; the API still enforces plan gating, so a
+ * locked pick would be rejected server-side. Hence `locked` candidates are
+ * filtered out before ranking rather than trusted to fail gracefully.
+ */
+export const AUTO_MODEL = "auto";
+/**
+ * Preference ladders per complexity, best-first, from PLAN.md §5.5's routing
+ * table. Ids must exist in the catalog (api/src/constants/models.ts).
+ */
+const LADDERS = {
+    trivial: [
+        "z-ai/glm-4.7-flash",
+        "qwen/qwen3-coder-flash",
+        "google/gemini-2.5-flash",
+        "z-ai/glm-4.7",
+        "moonshotai/kimi-k2.7-code",
+    ],
+    normal: [
+        "moonshotai/kimi-k2.7-code",
+        "z-ai/glm-4.7",
+        "qwen/qwen3-coder",
+        "deepseek/deepseek-v3.2",
+        "minimax/minimax-m2.5",
+    ],
+    // Sonnet 5 leads on cost-per-quality: ~$11.80 for a heavy session against
+    // ~$17.70 for Kimi K3, for at least comparable coding output. K3 is
+    // deliberately absent from every Auto ladder. It is the one model whose price
+    // surprises people (frontier-priced despite being open), so Auto never spends
+    // a user's window on it. Max users can still pick it explicitly via /model.
+    complex: [
+        "anthropic/claude-sonnet-5",
+        "openai/gpt-5.3-codex",
+        "google/gemini-2.5-pro",
+        "z-ai/glm-5.2",
+        "moonshotai/kimi-k2.7-code",
+    ],
+};
+/** Only reached on `quality` bias for genuinely hard turns, Max-plan territory. */
+const PREMIUM_LADDER = [
+    "anthropic/claude-fable-5",
+    "anthropic/claude-opus-4.8",
+    "anthropic/claude-opus-4.8-fast",
+];
+/** Last-resort pick when nothing in a ladder is available (also the BYOK anchor). */
+const FALLBACK_MODEL = "moonshotai/kimi-k2.7-code";
+/** What hosts show for an Auto session that has not routed a turn yet. */
+export const FALLBACK_DISPLAY_MODEL = FALLBACK_MODEL;
+const COMPLEX_PATTERNS = [
+    /\brefactor/i,
+    /\barchitect/i,
+    /\bdesign\b/i,
+    /\bdebug/i,
+    /\bmigrat/i,
+    /\binvestigat/i,
+    /\brewrite/i,
+    /\broot cause/i,
+    /\brace condition/i,
+    /\bmemory leak/i,
+    /\bperformance\b/i,
+    /\bsecurity\b/i,
+    /\bwhy (is|does|are|did)\b/i,
+    /\bmulti[- ]file/i,
+    /\bacross (the )?(codebase|repo|project)/i,
+    /\bplan\b/i,
+];
+const TRIVIAL_PATTERNS = [
+    /\brename\b/i,
+    /\btypo/i,
+    /\badd a comment/i,
+    /\bformat\b/i,
+    /\bbump (the )?version/i,
+    /\bwhat (is|does|are)\b/i,
+    /\bone[- ]liner/i,
+    /\blint\b/i,
+];
+const LONG_PROMPT_CHARS = 600;
+/**
+ * Deliberately tight. Real feature asks are short ("add a logout button to the
+ * settings page") and must not fall to a flash model on length alone, genuinely
+ * trivial work is caught by TRIVIAL_PATTERNS instead. This only catches terse
+ * imperatives like "run the tests".
+ */
+const SHORT_PROMPT_CHARS = 30;
+/** Classify how much model the turn deserves. Exported for tests and debugging. */
+export function classify(text, planMode = false) {
+    if (planMode)
+        return "complex";
+    const trimmed = text.trim();
+    const complexHits = COMPLEX_PATTERNS.filter((p) => p.test(trimmed)).length;
+    const trivialHits = TRIVIAL_PATTERNS.filter((p) => p.test(trimmed)).length;
+    // An explicit complex signal outranks brevity: "debug this" is three words.
+    if (complexHits > 0)
+        return "complex";
+    if (trimmed.length >= LONG_PROMPT_CHARS)
+        return "complex";
+    if (trivialHits > 0 && trimmed.length < LONG_PROMPT_CHARS)
+        return "trivial";
+    if (trimmed.length <= SHORT_PROMPT_CHARS)
+        return "trivial";
+    return "normal";
+}
+const ORDER = ["trivial", "normal", "complex"];
+function shift(complexity, steps) {
+    const i = ORDER.indexOf(complexity) + steps;
+    return ORDER[Math.max(0, Math.min(ORDER.length - 1, i))];
+}
+/** First ladder entry the user can actually use. */
+function pick(ladder, available) {
+    if (!available.length)
+        return ladder[0] ?? null; // BYOK: no lock data, take the best
+    const usable = new Set(available.filter((m) => !m.locked).map((m) => m.id));
+    return ladder.find((id) => usable.has(id)) ?? null;
+}
+/**
+ * Choose a model for one turn.
+ *
+ * Order of precedence: explore sub-agents are pinned to economy, then bias
+ * shifts the classified complexity, then the ladder is filtered by plan locks.
+ */
+export function route(input) {
+    const available = input.available ?? [];
+    const bias = input.bias ?? "balanced";
+    // Explore sub-agents read and summarise; a frontier model here is pure burn.
+    if (input.subagent === "explore") {
+        return {
+            model: pick(LADDERS.trivial, available) ?? FALLBACK_MODEL,
+            complexity: "trivial",
+            reason: "explore sub-agent. Read-only search, economy tier",
+        };
+    }
+    const base = classify(input.text, input.planMode);
+    const adjusted = bias === "economy" ? shift(base, -1) : bias === "quality" ? shift(base, 1) : base;
+    // Quality bias on genuinely hard turns is the only path to premium models.
+    if (bias === "quality" && base === "complex") {
+        const premium = pick(PREMIUM_LADDER, available);
+        if (premium) {
+            return {
+                model: premium,
+                complexity: "complex",
+                reason: "complex turn, quality bias, premium tier",
+            };
+        }
+    }
+    const model = pick(LADDERS[adjusted], available) ?? FALLBACK_MODEL;
+    const biasNote = bias === "balanced" ? "" : `, ${bias} bias`;
+    return {
+        model,
+        complexity: adjusted,
+        reason: `${base} task${biasNote}${input.planMode ? " (plan mode)" : ""}`,
+    };
+}
+/**
+ * Model for delegated I/O work (see `delegate.ts`).
+ *
+ * Reuses the trivial ladder rather than naming a model of its own, so the
+ * cheapest usable model stays defined in exactly one place and plan locks are
+ * honoured for free. Bulk reading and boilerplate are the definition of a
+ * trivial turn, which is why the ladder is already correct for it.
+ */
+export function workerModel(available) {
+    return pick(LADDERS.trivial, available ?? []) ?? FALLBACK_MODEL;
+}
+//# sourceMappingURL=router.js.map

package/dist/permissions.d.ts

@@ -0,0 +1,5 @@
+import type { PermissionMode } from "./types.js";
+import type { ToolKind } from "./tools/types.js";
+export type Gate = "allow" | "ask" | "deny";
+/** Which gate a tool kind hits under each permission mode. */
+export declare function gateFor(kind: ToolKind, mode: PermissionMode): Gate;

package/dist/permissions.js

@@ -0,0 +1,16 @@
+/** Which gate a tool kind hits under each permission mode. */
+export function gateFor(kind, mode) {
+    if (kind === "read")
+        return "allow";
+    switch (mode) {
+        case "bypass":
+            return "allow";
+        case "plan":
+            return "deny"; // plan mode is read-only
+        case "accept-edits":
+            return kind === "mutate" ? "allow" : "ask";
+        case "default":
+            return "ask";
+    }
+}
+//# sourceMappingURL=permissions.js.map

package/dist/prompt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * System prompt, written from scratch in our own words (PLAN.md §1.3).
+ * In Milestone 2 this moves server-side (assembled per request by the API).
+ */
+export declare function buildSystemPrompt(cwd: string, memory?: string): string;

package/dist/prompt.js

@@ -0,0 +1,31 @@
+/**
+ * System prompt, written from scratch in our own words (PLAN.md §1.3).
+ * In Milestone 2 this moves server-side (assembled per request by the API).
+ */
+export function buildSystemPrompt(cwd, memory) {
+    const memoryBlock = memory
+        ? `\n\nStanding instructions from the user's 9P.md memory files, follow them:\n${memory}`
+        : "";
+    return `You are 9p, the 9th Protocol coding agent. You help engineers build, debug, and modify real codebases directly from their terminal.
+
+Working directory: ${cwd}
+Platform: ${process.platform}
+Today's date: ${new Date().toISOString().slice(0, 10)}
+
+How you work:
+- Investigate before acting. Locate relevant files with glob/grep, read them, and only then edit. Never guess at file contents or APIs, look them up.
+- Prefer small, targeted edits over rewriting files. Match the surrounding code's style, naming, and conventions; add comments only where intent isn't obvious from the code.
+- Verify your changes when possible: run the project's tests, typechecker, linter, or a quick command. Report results honestly, if something fails, show the failure instead of claiming success.
+- When a command errors, read the error and adapt. Don't repeat an identical failing call.
+- Finish the job. If a step is missing information, gather it with your tools rather than asking when you can find out yourself.
+
+Constraints:
+- Stay inside the working directory unless the user points you elsewhere.
+- Destructive operations (rm -rf, git reset --hard, force pushes, dropping data) are off-limits unless the user explicitly asks for them.
+- Never invent tool output, file contents, or command results.
+
+Style:
+- Your prose is rendered in a terminal: plain text, short paragraphs, no heavy markdown.
+- Lead with the outcome, then the essentials. Skip filler and restating the question.${memoryBlock}`;
+}
+//# sourceMappingURL=prompt.js.map

package/dist/scripts/compaction-live.d.ts

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

package/dist/scripts/compaction-live.js

@@ -0,0 +1,80 @@
+/**
+ * Live compaction check: force a real session past the threshold, then confirm
+ * the provider ACCEPTS the compacted history and the agent keeps working.
+ *
+ * The offline checks prove the message list stays well-formed. Only this proves
+ * the provider agrees.
+ *
+ *   PLATFORM_URL=... PLATFORM_TOKEN=... node dist/scripts/compaction-live.js
+ */
+import { AgentSession } from "../session.js";
+const platformUrl = process.env.PLATFORM_URL;
+const token = process.env.PLATFORM_TOKEN;
+if (!platformUrl || !token) {
+    console.error("Set PLATFORM_URL + PLATFORM_TOKEN");
+    process.exit(1);
+}
+const session = new AgentSession({
+    apiKey: token,
+    model: "z-ai/glm-4.7-flash",
+    cwd: process.cwd(),
+    mode: "bypass",
+    platform: { baseUrl: platformUrl },
+    // Tiny window so a handful of turns trips the threshold. Run this in a
+    // directory with real files, or the history never grows enough to compact.
+    contextTokens: Number(process.env.COMPACT_CONTEXT_TOKENS ?? 1500),
+    maxTurnsPerMessage: 6,
+});
+// Reading real files is what makes history genuinely large, which is the
+// situation compaction exists for. A window this size then forces a compaction
+// where the summary is much smaller than what it replaces.
+const prompts = [
+    "Read session.ts and say DONE1.",
+    "Read compaction.ts and say DONE2.",
+    "Read types.ts and say DONE3.",
+    "What was the FIRST file I asked you to read in this conversation? Answer with just the filename.",
+];
+let compactions = 0;
+let shrank = false;
+let lastText = "";
+let failed = false;
+for (const [i, prompt] of prompts.entries()) {
+    lastText = "";
+    let error = "";
+    for await (const ev of session.send(prompt)) {
+        if (ev.type === "compacted") {
+            compactions++;
+            if (ev.afterTokens < ev.beforeTokens)
+                shrank = true;
+            const pct = Math.round((1 - ev.afterTokens / ev.beforeTokens) * 100);
+            console.log(`⊙ compacted ~${ev.beforeTokens} → ~${ev.afterTokens} tokens (${pct}% smaller)`);
+        }
+        if (ev.type === "text_delta")
+            lastText += ev.text;
+        if (ev.type === "error")
+            error = ev.message;
+    }
+    if (error) {
+        console.log(`✗ turn ${i + 1} errored: ${error.slice(0, 160)}`);
+        failed = true;
+        break;
+    }
+    console.log(`✓ turn ${i + 1} ok (~${session.contextTokens} tokens), ${lastText.trim().slice(0, 60).replace(/\n/g, " ")}`);
+}
+console.log(`\ncompactions: ${compactions}`);
+if (!failed && compactions === 0) {
+    console.log("✗ never compacted. The threshold did not trip, nothing was proven");
+    failed = true;
+}
+if (!failed && !shrank) {
+    console.log("✗ compaction ran but never reduced the context");
+    failed = true;
+}
+// The last prompt asks about the earliest exchange, which by then exists only
+// inside the summary. A sensible answer means compaction preserved meaning.
+if (!failed) {
+    console.log(`\nrecall-after-compaction answer:\n  ${lastText.trim().slice(0, 300)}`);
+}
+console.log(`\n${failed ? "FAILED" : "live compaction OK"}`);
+process.exit(failed ? 1 : 0);
+//# sourceMappingURL=compaction-live.js.map

package/dist/scripts/compaction-smoke.d.ts

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