@9thprotocol/agent-core 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+9th Protocol — Proprietary License
+
+Copyright (c) 2026 9th Protocol. All rights reserved.
+
+This software and its source code are the property of 9th Protocol.
+It is licensed, not sold. You may install and use the unmodified
+package for its intended purpose. You may not copy, modify, merge,
+publish, distribute, sublicense, decompile, or reverse engineer it,
+or use it to build a competing agent product, without a separate
+written license from 9th Protocol.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED. IN NO EVENT SHALL 9TH PROTOCOL BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE.
+
+Contact: licensing@9thprotocol.com

package/README.md

@@ -0,0 +1,10 @@
+# @9thprotocol/agent-core
+
+The 9th Protocol agent engine: agent loop, tools, permissions, sub-agents,
+context management, model routing. Proprietary — see [LICENSE](./LICENSE).
+
+This is the engine behind [`9p`](https://www.npmjs.com/package/@9thprotocol/cli),
+the 9th Protocol terminal coding agent. It is published closed-source; use the
+CLI directly unless you have a written integration agreement.
+
+Node 22+ required.

package/dist/compaction.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Context compaction. Keep a long session inside the model's context window.
+ *
+ * Without this, a session that runs long enough eventually sends more tokens
+ * than the model accepts and every subsequent turn fails. Compaction summarises
+ * the older part of the conversation into one message and keeps recent turns
+ * verbatim, so work continues instead of dying.
+ *
+ * The subtle constraint is **tool-call pairing**: an assistant message carrying
+ * `tool_calls` must be followed by a `tool` message for every one of those ids.
+ * Cutting the history at an arbitrary index orphans tool results (or leaves
+ * dangling calls) and the provider rejects the request outright. Everything here
+ * cuts only at boundaries where the remainder is self-contained.
+ */
+import type { ChatMessage } from "./model/openrouter.js";
+/** Fallback when the model's real context length is unknown. */
+export declare const DEFAULT_CONTEXT_TOKENS = 200000;
+/** Compact once estimated usage passes this share of the window. */
+export declare const COMPACT_THRESHOLD = 0.7;
+/**
+ * Rough token estimate: ~4 chars per token.
+ *
+ * Deliberately not a real tokenizer. That would mean shipping model-specific
+ * vocabularies for 18 models. This drives a *threshold*, and erring high just
+ * compacts slightly early, which is harmless.
+ */
+export declare function estimateTokens(messages: ChatMessage[]): number;
+/**
+ * Pick the latest safe cut point that still leaves a useful amount of recent
+ * history verbatim.
+ *
+ * Walks backwards accumulating tokens until the kept tail fills its share of
+ * the window, then snaps *backwards* to the nearest safe boundary. Snapping
+ * backwards (keeping more) rather than forwards guarantees we never cut into an
+ * exchange to hit a token target.
+ *
+ * Returns 0 when no safe boundary exists. Nothing is compacted rather than
+ * risking a malformed request.
+ */
+export declare function findCutpoint(messages: ChatMessage[], contextTokens?: number): number;
+/** Render a slice as plain text for the summariser. */
+export declare function renderTranscript(messages: ChatMessage[]): string;
+/**
+ * The instruction given to the summariser model.
+ *
+ * BYOK only. In platform mode the API assembles this from `context.mode`
+ * ("compaction"), the same rule as every other prompt (PLAN.md §1.3), and the
+ * client sends the bare transcript. Keep the two in step: the copy the server
+ * uses lives in `api/src/prompts/system.ts`.
+ */
+export declare function summaryPrompt(transcript: string): string;
+export interface CompactionPlan {
+    /** Messages to summarise (already excludes the system prefix). */
+    toSummarise: ChatMessage[];
+    /** Messages kept verbatim after the summary. */
+    kept: ChatMessage[];
+    /** Leading system messages, preserved as-is. */
+    systemPrefix: ChatMessage[];
+    beforeTokens: number;
+}
+/**
+ * Decide what to compact. Returns null when compaction isn't possible or worth
+ * it. The caller should carry on unchanged.
+ */
+export declare function planCompaction(messages: ChatMessage[], contextTokens?: number): CompactionPlan | null;
+/** Rebuild the message list around a completed summary. */
+export declare function applyCompaction(plan: CompactionPlan, summary: string): ChatMessage[];
+/** Should we compact before the next request? */
+export declare function shouldCompact(messages: ChatMessage[], contextTokens: number): boolean;

package/dist/compaction.js

@@ -0,0 +1,174 @@
+/** Fallback when the model's real context length is unknown. */
+export const DEFAULT_CONTEXT_TOKENS = 200_000;
+/** Compact once estimated usage passes this share of the window. */
+export const COMPACT_THRESHOLD = 0.7;
+/**
+ * Share of the window reserved for verbatim recent history. The rest is
+ * summarised. Token-based rather than a message count: a session can be six
+ * messages long and still overflow (reading a few large files does it), and a
+ * fixed "keep the last N messages" rule can never compact that case.
+ */
+const KEEP_RECENT_SHARE = 0.3;
+/** Always keep at least this many messages verbatim, however large they are. */
+const KEEP_RECENT_MIN = 4;
+/** Never compact below this many messages; there's nothing worth summarising. */
+const MIN_TO_COMPACT = 4;
+/**
+ * Rough token estimate: ~4 chars per token.
+ *
+ * Deliberately not a real tokenizer. That would mean shipping model-specific
+ * vocabularies for 18 models. This drives a *threshold*, and erring high just
+ * compacts slightly early, which is harmless.
+ */
+export function estimateTokens(messages) {
+    let chars = 0;
+    for (const m of messages) {
+        chars += typeof m.content === "string" ? m.content.length : 0;
+        if (m.role === "assistant" && m.tool_calls) {
+            for (const tc of m.tool_calls) {
+                chars += tc.function.name.length + tc.function.arguments.length;
+            }
+        }
+    }
+    return Math.ceil(chars / 4);
+}
+/**
+ * True when `messages[0..index)` can be cut away without orphaning anything -
+ * i.e. `messages[index]` starts a fresh exchange rather than continuing one.
+ *
+ * A `tool` message always belongs to the assistant turn before it, so a cut
+ * landing on one would strand it. An assistant message may itself be the reply
+ * being answered by following tool results, so only `user` messages (and the
+ * very end) are safe boundaries.
+ */
+function isSafeCut(messages, index) {
+    if (index <= 0 || index >= messages.length)
+        return false;
+    return messages[index].role === "user";
+}
+/**
+ * Pick the latest safe cut point that still leaves a useful amount of recent
+ * history verbatim.
+ *
+ * Walks backwards accumulating tokens until the kept tail fills its share of
+ * the window, then snaps *backwards* to the nearest safe boundary. Snapping
+ * backwards (keeping more) rather than forwards guarantees we never cut into an
+ * exchange to hit a token target.
+ *
+ * Returns 0 when no safe boundary exists. Nothing is compacted rather than
+ * risking a malformed request.
+ */
+export function findCutpoint(messages, contextTokens = DEFAULT_CONTEXT_TOKENS) {
+    const keepBudget = Math.max(1, contextTokens * KEEP_RECENT_SHARE);
+    let kept = 0;
+    let boundary = messages.length;
+    for (let i = messages.length - 1; i > 0; i--) {
+        kept += estimateTokens([messages[i]]);
+        const keptEnough = messages.length - i >= KEEP_RECENT_MIN;
+        if (kept >= keepBudget && keptEnough) {
+            boundary = i;
+            break;
+        }
+        boundary = i;
+    }
+    // Snap backwards to a boundary that leaves the tail self-contained.
+    for (let i = boundary; i > 0; i--) {
+        if (isSafeCut(messages, i))
+            return i;
+    }
+    return 0;
+}
+/** Leading system messages are configuration, never conversation. Never cut. */
+function systemPrefixLength(messages) {
+    let i = 0;
+    while (i < messages.length && messages[i].role === "system")
+        i++;
+    return i;
+}
+/** Render a slice as plain text for the summariser. */
+export function renderTranscript(messages) {
+    const lines = [];
+    for (const m of messages) {
+        if (m.role === "system")
+            continue;
+        if (m.role === "user") {
+            lines.push(`USER: ${m.content}`);
+        }
+        else if (m.role === "assistant") {
+            if (m.content)
+                lines.push(`ASSISTANT: ${m.content}`);
+            for (const tc of m.tool_calls ?? []) {
+                lines.push(`ASSISTANT CALLED ${tc.function.name}(${truncate(tc.function.arguments, 400)})`);
+            }
+        }
+        else {
+            lines.push(`TOOL RESULT: ${truncate(m.content, 800)}`);
+        }
+    }
+    return lines.join("\n");
+}
+function truncate(s, max) {
+    return s.length > max ? `${s.slice(0, max)}…[truncated]` : s;
+}
+/**
+ * The instruction given to the summariser model.
+ *
+ * BYOK only. In platform mode the API assembles this from `context.mode`
+ * ("compaction"), the same rule as every other prompt (PLAN.md §1.3), and the
+ * client sends the bare transcript. Keep the two in step: the copy the server
+ * uses lives in `api/src/prompts/system.ts`.
+ */
+export function summaryPrompt(transcript) {
+    return `Summarise this coding-session transcript so another agent can pick up the work with no other context.
+
+Preserve, in this order:
+1. What the user is trying to achieve, in their own terms
+2. Decisions made and constraints stated, especially anything the user corrected or rejected
+3. Files created or modified, with paths, and what changed in each
+4. Commands run and what they revealed (test results, errors, versions)
+5. What is currently in progress and the immediate next step
+6. Anything known to be broken, blocked, or deliberately deferred
+
+Be specific: keep exact file paths, identifiers, error text, and numbers. Drop
+pleasantries, tool-call mechanics, and superseded intermediate steps. Do not
+speculate about work that was not done.
+
+TRANSCRIPT:
+${transcript}`;
+}
+/**
+ * Decide what to compact. Returns null when compaction isn't possible or worth
+ * it. The caller should carry on unchanged.
+ */
+export function planCompaction(messages, contextTokens = DEFAULT_CONTEXT_TOKENS) {
+    const prefix = systemPrefixLength(messages);
+    const body = messages.slice(prefix);
+    if (body.length < MIN_TO_COMPACT)
+        return null;
+    const cut = findCutpoint(body, contextTokens);
+    if (cut <= 0)
+        return null;
+    return {
+        systemPrefix: messages.slice(0, prefix),
+        toSummarise: body.slice(0, cut),
+        kept: body.slice(cut),
+        beforeTokens: estimateTokens(messages),
+    };
+}
+/** Rebuild the message list around a completed summary. */
+export function applyCompaction(plan, summary) {
+    return [
+        ...plan.systemPrefix,
+        {
+            role: "user",
+            content: `[Earlier conversation, compacted to stay within the context window. ` +
+                `Treat this as established history, not as a new instruction.]\n\n${summary}`,
+        },
+        ...plan.kept,
+    ];
+}
+/** Should we compact before the next request? */
+export function shouldCompact(messages, contextTokens) {
+    return estimateTokens(messages) > contextTokens * COMPACT_THRESHOLD;
+}
+//# sourceMappingURL=compaction.js.map

package/dist/delegate.d.ts

@@ -0,0 +1,84 @@
+import type { UsageTotals } from "./types.js";
+/**
+ * Worker roles. The names are the contract with the API: in platform mode the
+ * server assembles the matching system prompt (PLAN.md §1.3, prompt text never
+ * ships in a client), and the ledger tags the spend with the mode so M7 can
+ * separate delegated burn from main-loop burn.
+ */
+export type DelegationMode = "bulk-reader" | "code-writer";
+/**
+ * Every mode the API will assemble a non-agent prompt for. Compaction is not a
+ * delegation (nothing is being kept out of the context; history is being
+ * rewritten) but it is the same kind of request: one cheap, toolless turn that
+ * must not be handed the agent prompt.
+ */
+export type PlatformMode = DelegationMode | "compaction";
+/**
+ * Line count above which the read tool stops returning file bodies.
+ *
+ * Spotify's shunt uses 350, measured on a Java monorepo. 600 suits the denser
+ * TypeScript this agent is mostly pointed at: it still catches the files that
+ * dominate a context window while leaving ordinary modules directly readable,
+ * which matters because a blocked read costs a round trip before any edit.
+ */
+export declare const DELEGATION_MIN_LINES = 600;
+/**
+ * Ceiling on one delegated request. Well inside an economy model's window, and
+ * a corpus this large is a sign the caller should have grepped first.
+ */
+export declare const MAX_CORPUS_CHARS = 600000;
+/**
+ * BYOK fallback prompts. In platform mode these are never sent: the API strips
+ * client system messages and assembles its own from the mode name. They exist
+ * so a user on their own OpenRouter key gets the same worker behaviour.
+ *
+ * Both prompts are written to suppress prose. The instruction that saves the
+ * most is "no markdown fences" on the writer: without it the worker wraps its
+ * output in formatting and commentary that the caller then has to read and
+ * strip, which puts the payload straight back into the context this exists to
+ * protect.
+ */
+export declare const WORKER_PROMPTS: Record<DelegationMode, string>;
+export interface DelegationResult {
+    text: string;
+    usage: UsageTotals;
+}
+/**
+ * One ephemeral worker turn. Toolless by construction: a worker that could call
+ * tools would be a sub-agent, with a sub-agent's cost.
+ */
+export declare function delegate(opts: {
+    apiKey: string;
+    model: string;
+    mode: DelegationMode;
+    message: string;
+    cwd: string;
+    sessionId: string;
+    platform?: {
+        baseUrl: string;
+    };
+    signal?: AbortSignal;
+}): Promise<DelegationResult>;
+/**
+ * Wrap each file in a tagged block so the worker sees clear boundaries, and
+ * number the lines so it can cite positions the caller can then read directly.
+ * Those citations are what make a delegated read usable as the setup for a
+ * targeted edit rather than a dead end.
+ */
+export declare function buildReadCorpus(files: Array<{
+    path: string;
+    content: string;
+}>, question: string): string;
+/** Spec first, then the references whose conventions the output must match. */
+export declare function buildWriteCorpus(spec: string, references: Array<{
+    path: string;
+    content: string;
+}>): string;
+/**
+ * Workers wrap output in fences despite being told not to, often enough that
+ * stripping them is cheaper than a retry. Only whole fence lines go: a fence
+ * indented inside a string literal or a docstring is content.
+ */
+export declare function stripFences(s: string): string;
+/** Rough parity with `estimateTokens`, for reporting what stayed out of context. */
+export declare function estimateCorpusTokens(chars: number): number;

package/dist/delegate.js

@@ -0,0 +1,135 @@
+/**
+ * Delegation: I/O-heavy work runs on an economy worker model, in its own
+ * request, and only the answer comes back into the session's context.
+ *
+ * The premise is that most of what the agent does is not reasoning. Reading a
+ * 4,000-line file to answer one question about it, or writing the twentieth
+ * test that copies the nineteen next to it, is transport. Paying frontier
+ * rates for it is bad enough once; the file is then resent on every following
+ * turn, so an 8k-token read is an 8k-token tax for the rest of the session.
+ *
+ * Two things make this different from spawning an explore sub-agent:
+ *
+ *   1. A sub-agent holds a conversation and returns prose. A delegation is one
+ *      shot: one request, structured bullets or a file on disk, nothing kept.
+ *   2. The corpus never enters the parent's history at all, so asking a second
+ *      question about the same files costs the parent nothing.
+ *
+ * Enforcement lives in the read tool (see `tools/fs-tools.ts`), not in the
+ * system prompt. Advice about which tool to use is a suggestion the model is
+ * free to skip on a busy turn; a tool that refuses to return the body is not.
+ *
+ * Worker burn is billed like any other request and rolls into the session's
+ * usage, so a delegation is cheaper, never free. Below `DELEGATION_MIN_LINES`
+ * the round trip costs more than the tokens it saves.
+ */
+import { streamChat } from "./model/openrouter.js";
+/**
+ * Line count above which the read tool stops returning file bodies.
+ *
+ * Spotify's shunt uses 350, measured on a Java monorepo. 600 suits the denser
+ * TypeScript this agent is mostly pointed at: it still catches the files that
+ * dominate a context window while leaving ordinary modules directly readable,
+ * which matters because a blocked read costs a round trip before any edit.
+ */
+export const DELEGATION_MIN_LINES = 600;
+/**
+ * Ceiling on one delegated request. Well inside an economy model's window, and
+ * a corpus this large is a sign the caller should have grepped first.
+ */
+export const MAX_CORPUS_CHARS = 600_000;
+/**
+ * BYOK fallback prompts. In platform mode these are never sent: the API strips
+ * client system messages and assembles its own from the mode name. They exist
+ * so a user on their own OpenRouter key gets the same worker behaviour.
+ *
+ * Both prompts are written to suppress prose. The instruction that saves the
+ * most is "no markdown fences" on the writer: without it the worker wraps its
+ * output in formatting and commentary that the caller then has to read and
+ * strip, which puts the payload straight back into the context this exists to
+ * protect.
+ */
+export const WORKER_PROMPTS = {
+    "bulk-reader": "You are a precise code analyst. Read the provided files and answer the question concisely. Output structured bullets only. No greetings, no prose, no preamble, no closing summary. Lead every bullet with the exact name, type, or line number. Use nested bullets for detail. Cite line numbers as path:line, taken from the numbers in the input. Skip anything the caller did not ask for. If the files do not answer the question, say so in one bullet rather than guessing.",
+    "code-writer": "You generate code files from a spec and reference files. Match the reference's patterns, conventions, naming, imports, and style exactly. Output only the code: no explanation, no commentary, no markdown fences. If the spec is ambiguous, choose whatever matches the reference.",
+};
+/**
+ * One ephemeral worker turn. Toolless by construction: a worker that could call
+ * tools would be a sub-agent, with a sub-agent's cost.
+ */
+export async function delegate(opts) {
+    if (opts.message.length > MAX_CORPUS_CHARS) {
+        throw new Error(`request is ${opts.message.length} chars, over the ${MAX_CORPUS_CHARS} limit. Send fewer or smaller files.`);
+    }
+    // Platform mode: the server writes the system prompt from `context.mode`.
+    // BYOK: there is no server, so carry the prompt locally.
+    const messages = opts.platform
+        ? [{ role: "user", content: opts.message }]
+        : [
+            { role: "system", content: WORKER_PROMPTS[opts.mode] },
+            { role: "user", content: opts.message },
+        ];
+    let text = "";
+    let usage = { inputTokens: 0, cachedTokens: 0, outputTokens: 0, requests: 0 };
+    for await (const ev of streamChat({
+        apiKey: opts.apiKey,
+        model: opts.model,
+        messages,
+        tools: [],
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(opts.platform
+            ? {
+                baseUrl: opts.platform.baseUrl,
+                extraBody: {
+                    context: { cwd: opts.cwd, sessionId: opts.sessionId, mode: opts.mode },
+                },
+            }
+            : {}),
+    })) {
+        if (ev.type === "done") {
+            text = ev.result.message.content ?? "";
+            usage = ev.result.usage;
+        }
+    }
+    if (!text.trim())
+        throw new Error(`the ${opts.mode} worker returned nothing`);
+    return { text: text.trim(), usage };
+}
+/**
+ * Wrap each file in a tagged block so the worker sees clear boundaries, and
+ * number the lines so it can cite positions the caller can then read directly.
+ * Those citations are what make a delegated read usable as the setup for a
+ * targeted edit rather than a dead end.
+ */
+export function buildReadCorpus(files, question) {
+    const blocks = files.map((f) => {
+        const numbered = f.content
+            .split("\n")
+            .map((line, i) => `${i + 1}\t${line}`)
+            .join("\n");
+        return `<file path="${f.path}">\n${numbered}\n</file>`;
+    });
+    return `${blocks.join("\n\n")}\n\nQuestion: ${question}\n`;
+}
+/** Spec first, then the references whose conventions the output must match. */
+export function buildWriteCorpus(spec, references) {
+    const blocks = references.map((r) => `<reference path="${r.path}">\n${r.content}\n</reference>`);
+    return `Spec: ${spec}\n\n${blocks.join("\n\n")}\n`;
+}
+/**
+ * Workers wrap output in fences despite being told not to, often enough that
+ * stripping them is cheaper than a retry. Only whole fence lines go: a fence
+ * indented inside a string literal or a docstring is content.
+ */
+export function stripFences(s) {
+    return s
+        .split("\n")
+        .filter((line) => !/^```/.test(line))
+        .join("\n")
+        .trim();
+}
+/** Rough parity with `estimateTokens`, for reporting what stayed out of context. */
+export function estimateCorpusTokens(chars) {
+    return Math.ceil(chars / 4);
+}
+//# sourceMappingURL=delegate.js.map

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @9thprotocol/agent-core, the agent engine.
+ * Loop + core tools + permission modes + streaming (M1); platform transport (M2);
+ * sub-agents, ask_user, 9P.md memory, skills, MCP client (M3).
+ * Next: Auto router, context compaction, Ink TUI/VS Code hosts (M5).
+ */
+export declare const AGENT_CORE_VERSION = "0.1.0";
+export { AgentSession } from "./session.js";
+export { CORE_TOOLS } from "./tools/registry.js";
+export { McpManager } from "./mcp.js";
+export { loadSkills, skillMessage, type Skill } from "./skills.js";
+export { loadMemory } from "./memory.js";
+export { loadProjectConfig, resolveVault, saveProjectConfig, scaffoldVault, vaultProtocol, type ProjectConfig, } from "./vault.js";
+export { ApiError } from "./model/openrouter.js";
+export { DELEGATION_MIN_LINES, MAX_CORPUS_CHARS, WORKER_PROMPTS, buildReadCorpus, buildWriteCorpus, delegate, estimateCorpusTokens, stripFences, type DelegationMode, type DelegationResult, type PlatformMode, } from "./delegate.js";
+export { COMPACT_THRESHOLD, DEFAULT_CONTEXT_TOKENS, estimateTokens, planCompaction, shouldCompact, } from "./compaction.js";
+export { AUTO_MODEL, classify, route, workerModel, type RouteDecision, type RouteInput, type RouterBias, type RouterCandidate, type TaskComplexity, } from "./model/router.js";
+export type { AgentEvent, AskUserHandler, DelegationTotals, AskUserQuestion, PermissionDecider, PermissionMode, PermissionRequest, SessionOptions, ToolCallRequest, UsageTotals, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @9thprotocol/agent-core, the agent engine.
+ * Loop + core tools + permission modes + streaming (M1); platform transport (M2);
+ * sub-agents, ask_user, 9P.md memory, skills, MCP client (M3).
+ * Next: Auto router, context compaction, Ink TUI/VS Code hosts (M5).
+ */
+export const AGENT_CORE_VERSION = "0.1.0";
+export { AgentSession } from "./session.js";
+export { CORE_TOOLS } from "./tools/registry.js";
+export { McpManager } from "./mcp.js";
+export { loadSkills, skillMessage } from "./skills.js";
+export { loadMemory } from "./memory.js";
+export { loadProjectConfig, resolveVault, saveProjectConfig, scaffoldVault, vaultProtocol, } from "./vault.js";
+export { ApiError } from "./model/openrouter.js";
+export { DELEGATION_MIN_LINES, MAX_CORPUS_CHARS, WORKER_PROMPTS, buildReadCorpus, buildWriteCorpus, delegate, estimateCorpusTokens, stripFences, } from "./delegate.js";
+export { COMPACT_THRESHOLD, DEFAULT_CONTEXT_TOKENS, estimateTokens, planCompaction, shouldCompact, } from "./compaction.js";
+export { AUTO_MODEL, classify, route, workerModel, } from "./model/router.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp.d.ts

@@ -0,0 +1,13 @@
+import type { ToolDef } from "./tools/types.js";
+/**
+ * Connects configured stdio MCP servers and exposes their tools as
+ * `mcp__<server>__<tool>` ToolDefs (kind "exec", permission-gated like bash).
+ */
+export declare class McpManager {
+    readonly tools: ToolDef[];
+    readonly servers: string[];
+    private clients;
+    static fromCwd(cwd: string): Promise<McpManager>;
+    private connect;
+    close(): Promise<void>;
+}

package/dist/mcp.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+/** Merge ~/.9p/mcp.json and <cwd>/.9p/mcp.json (project wins per server name). */
+function loadConfig(cwd) {
+    const merged = {};
+    for (const file of [
+        path.join(os.homedir(), ".9p", "mcp.json"),
+        path.join(cwd, ".9p", "mcp.json"),
+    ]) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+            Object.assign(merged, parsed.mcpServers ?? {});
+        }
+        catch {
+            // absent or invalid, skip
+        }
+    }
+    return merged;
+}
+/**
+ * Connects configured stdio MCP servers and exposes their tools as
+ * `mcp__<server>__<tool>` ToolDefs (kind "exec", permission-gated like bash).
+ */
+export class McpManager {
+    tools = [];
+    servers = [];
+    clients = [];
+    static async fromCwd(cwd) {
+        const manager = new McpManager();
+        for (const [name, cfg] of Object.entries(loadConfig(cwd))) {
+            try {
+                await manager.connect(name, cfg);
+            }
+            catch (err) {
+                console.error(`mcp: failed to connect "${name}": ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        return manager;
+    }
+    async connect(serverName, cfg) {
+        const client = new Client({ name: "9p", version: "0.1.0" });
+        const transport = new StdioClientTransport({
+            command: cfg.command,
+            args: cfg.args ?? [],
+            env: { ...process.env, ...cfg.env },
+        });
+        await client.connect(transport);
+        this.clients.push(client);
+        this.servers.push(serverName);
+        const { tools } = await client.listTools();
+        for (const t of tools) {
+            this.tools.push({
+                name: `mcp__${serverName}__${t.name}`,
+                description: t.description ?? `${t.name} (MCP: ${serverName})`,
+                kind: "exec",
+                parameters: t.inputSchema ?? { type: "object" },
+                summarize: (input) => `mcp ${serverName}.${t.name}(${JSON.stringify(input).slice(0, 80)})`,
+                run: async (input) => {
+                    const result = await client.callTool({ name: t.name, arguments: input });
+                    const content = (result.content ?? []);
+                    const text = content
+                        .map((c) => (c.type === "text" ? (c.text ?? "") : `[${c.type}]`))
+                        .join("\n");
+                    if (result.isError)
+                        throw new Error(text || "MCP tool error");
+                    return text || "[no output]";
+                },
+            });
+        }
+    }
+    async close() {
+        await Promise.allSettled(this.clients.map((c) => c.close()));
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/dist/memory.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Memory context loaded every session: 9P.md standing instructions (global
+ * ~/.9p/9P.md, then project 9P.md, project wins by appearing last), plus the
+ * vault protocol when the project links an Obsidian-style vault. The vault's
+ * *content* is never bulk-loaded, the agent navigates it with tools.
+ */
+export declare function loadMemory(cwd: string): string;

package/dist/memory.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveVault, vaultProtocol } from "./vault.js";
+const MEMORY_CAP = 8000; // chars, memory must never dominate the context window
+/**
+ * Memory context loaded every session: 9P.md standing instructions (global
+ * ~/.9p/9P.md, then project 9P.md, project wins by appearing last), plus the
+ * vault protocol when the project links an Obsidian-style vault. The vault's
+ * *content* is never bulk-loaded, the agent navigates it with tools.
+ */
+export function loadMemory(cwd) {
+    const sources = [
+        ["Global memory", path.join(os.homedir(), ".9p", "9P.md")],
+        ["Project memory", path.join(cwd, "9P.md")],
+    ];
+    const parts = [];
+    for (const [label, file] of sources) {
+        try {
+            const text = fs.readFileSync(file, "utf8").trim();
+            if (text)
+                parts.push(`### ${label} (${file})\n${text}`);
+        }
+        catch {
+            // absent, fine
+        }
+    }
+    const vault = resolveVault(cwd);
+    if (vault)
+        parts.push(vaultProtocol(vault));
+    return parts.join("\n\n").slice(0, MEMORY_CAP);
+}
+//# sourceMappingURL=memory.js.map