Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
currentCliCommandName,
currentDesktopProduct,
piToolNamespace,
} from '@inkeep/open-knowledge-core';
import {
buildManagedServerEntry,
type McpInstallOptions,
PI_MANAGED_FILE_ENTRY_COMMAND,
piExtensionDevHeader,
piExtensionOwnershipMarker,
piExtensionVersionSentinel,
} from '../commands/editors.ts';
export function isOwnPiExtensionSource(text: string): boolean {
const product = currentDesktopProduct();
const firstLine = text.split(/\r?\n/, 1)[0] ?? '';
if (firstLine === piExtensionDevHeader(product)) return true;
const marker = piExtensionOwnershipMarker(product);
return firstLine.startsWith(marker) && /^-v\d+$/.test(firstLine.slice(marker.length));
}
export function isPiExtensionSourceUpToDate(text: string): boolean {
return text.startsWith(piExtensionVersionSentinel(currentDesktopProduct()));
}
export function isOwnPiManagedFileEntry(entry: unknown): boolean {
if (typeof entry !== 'object' || entry === null) return false;
const e = entry as Record<string, unknown>;
if (e.command !== PI_MANAGED_FILE_ENTRY_COMMAND || !Array.isArray(e.args)) return false;
const text = e.args[0];
return typeof text === 'string' && isOwnPiExtensionSource(text);
}
export function makePiManagedFileEntry(text: string): Record<string, unknown> {
return { command: PI_MANAGED_FILE_ENTRY_COMMAND, args: [text] };
}
export function buildPiExtensionSource(options: McpInstallOptions = {}): string {
const dev = options.mode === 'dev';
const product = currentDesktopProduct();
const header = dev ? piExtensionDevHeader(product) : piExtensionVersionSentinel(product);
const toolPrefix = `${piToolNamespace(product)}_`;
const launchers = {
unix: buildManagedServerEntry({ ...options, platformName: 'darwin' }),
win32: buildManagedServerEntry({ ...options, platformName: 'win32' }),
};
return `${header}
/**
* Open Knowledge bridge for Pi — MANAGED FILE, written by \`${currentCliCommandName()} init\`.
* Hand edits are overwritten whenever OK re-syncs this project; remove it
* with \`${currentCliCommandName()} deinit\` (or delete the file) to disconnect Pi from OK.
*
* On session start it spawns Open Knowledge's MCP stdio server via OK's
* resilient launcher (bundle, then npx, then version-manager probes), performs
* the MCP handshake, and registers each MCP tool as a Pi tool under an
* \`${toolPrefix}\` prefix (Pi has no MCP namespacing; the prefix keeps OK's \`edit\` /
* \`write\` from shadowing Pi's built-in tools).
*/
import { spawn } from "node:child_process";
import type { ChildProcessWithoutNullStreams } from "node:child_process";
const LAUNCHERS = ${JSON.stringify(launchers, null, 2)} as const;
const TOOL_PREFIX = ${JSON.stringify(toolPrefix)};
// First contact may cold-install the CLI through npx — allow a generous window.
const INIT_TIMEOUT_MS = 120000;
const STDERR_TAIL_LIMIT = 2000;
interface McpContentItem {
type: string;
text?: string;
}
interface McpToolInfo {
name: string;
description?: string;
inputSchema?: Record<string, unknown>;
}
interface PendingRequest {
resolve: (value: Record<string, unknown>) => void;
reject: (err: Error) => void;
}
class OkMcpClient {
private child: ChildProcessWithoutNullStreams;
private pending = new Map<number, PendingRequest>();
private nextId = 1;
private buffer = "";
private stderrTail = "";
alive = true;
constructor(cwd: string, onExit: () => void) {
const launcher = process.platform === "win32" ? LAUNCHERS.win32 : LAUNCHERS.unix;
const env: Record<string, string | undefined> = { ...process.env };
const launcherEnv = (launcher as { env?: Record<string, string> }).env;
if (launcherEnv) Object.assign(env, launcherEnv);
this.child = spawn(launcher.command, [...launcher.args], {
cwd,
env,
stdio: ["pipe", "pipe", "pipe"],
// Inline (not the withHiddenWindowsConsole helper): this spawn lives in the
// GENERATED Pi extension source, which must stay dependency-free (Pi loads
// it with jiti; no npm packages resolve). Hide the console on Windows anyway.
windowsHide: true,
});
this.child.stdout.setEncoding("utf8");
this.child.stdout.on("data", (chunk: string) => this.onStdout(chunk));
this.child.stderr.setEncoding("utf8");
this.child.stderr.on("data", (chunk: string) => {
this.stderrTail = (this.stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
});
// A write buffered before the pipe breaks surfaces as an 'error' on stdin
// (not on the child); unhandled it would crash Pi's extension host.
// Swallow it — the exit handler owns teardown.
this.child.stdin.on("error", () => {});
const fail = () => {
if (!this.alive) return;
this.alive = false;
const err = new Error(
"Open Knowledge MCP server exited" +
(this.stderrTail ? ": " + this.stderrTail.trim() : ""),
);
for (const p of this.pending.values()) p.reject(err);
this.pending.clear();
onExit();
};
this.child.on("exit", fail);
this.child.on("error", fail);
}
private onStdout(chunk: string): void {
this.buffer += chunk;
let newline = this.buffer.indexOf("\\n");
while (newline !== -1) {
const line = this.buffer.slice(0, newline).trim();
this.buffer = this.buffer.slice(newline + 1);
if (line.startsWith("{")) {
try {
this.onMessage(JSON.parse(line) as Record<string, unknown>);
} catch {
// Non-JSON noise on stdout is ignored; framing recovers on the next line.
}
}
newline = this.buffer.indexOf("\\n");
}
}
private onMessage(msg: Record<string, unknown>): void {
const id = msg.id;
if (typeof msg.method === "string") {
// Server-initiated request (e.g. roots/list). This bridge declares no
// client capabilities, so decline rather than leave the server hanging.
if (id !== undefined && id !== null) {
this.send({
jsonrpc: "2.0",
id,
error: { code: -32601, message: "Method not supported by the OK Pi bridge" },
});
}
return;
}
if (typeof id !== "number") return;
const pending = this.pending.get(id);
if (!pending) return;
this.pending.delete(id);
const error = msg.error as { message?: string } | undefined;
if (error) {
pending.reject(new Error(error.message || "Open Knowledge MCP error"));
return;
}
pending.resolve((msg.result ?? {}) as Record<string, unknown>);
}
private send(msg: Record<string, unknown>): void {
// Buffered stdout can still dispatch onMessage replies after close() ends
// stdin; writing then would raise ERR_STREAM_WRITE_AFTER_END unhandled.
if (!this.alive) return;
this.child.stdin.write(JSON.stringify(msg) + "\\n");
}
request(
method: string,
params: Record<string, unknown>,
opts: { timeoutMs?: number; signal?: AbortSignal } = {},
): Promise<Record<string, unknown>> {
if (!this.alive) return Promise.reject(new Error("Open Knowledge MCP server is not running"));
const id = this.nextId++;
return new Promise<Record<string, unknown>>((resolve, reject) => {
let timer: ReturnType<typeof setTimeout> | undefined;
let onAbort: (() => void) | undefined;
const cleanup = () => {
if (timer !== undefined) clearTimeout(timer);
if (onAbort && opts.signal) opts.signal.removeEventListener("abort", onAbort);
this.pending.delete(id);
};
const done: PendingRequest = {
resolve: (value) => {
cleanup();
resolve(value);
},
reject: (err) => {
cleanup();
reject(err);
},
};
this.pending.set(id, done);
if (opts.timeoutMs) {
timer = setTimeout(() => {
done.reject(new Error(method + " timed out after " + opts.timeoutMs + "ms"));
}, opts.timeoutMs);
}
if (opts.signal) {
onAbort = () => {
this.notify("notifications/cancelled", { requestId: id, reason: "aborted" });
done.reject(new Error("Cancelled"));
};
if (opts.signal.aborted) {
onAbort();
return;
}
opts.signal.addEventListener("abort", onAbort, { once: true });
}
this.send({ jsonrpc: "2.0", id, method, params });
});
}
notify(method: string, params: Record<string, unknown>): void {
if (!this.alive) return;
this.send({ jsonrpc: "2.0", method, params });
}
close(): void {
this.alive = false;
for (const p of this.pending.values()) {
p.reject(new Error("Open Knowledge MCP client closed"));
}
this.pending.clear();
// ok mcp exits on stdin EOF; the delayed kill is a backstop.
try {
this.child.stdin.end();
} catch {
// Already gone.
}
const child = this.child;
setTimeout(() => {
try {
child.kill();
} catch {
// Already gone.
}
}, 2000).unref();
}
}
/** JSON Schema pass-through: Pi validates plain JSON Schema parameters. */
function toParameters(inputSchema: Record<string, unknown> | undefined): Record<string, unknown> {
if (!inputSchema || typeof inputSchema !== "object") {
return { type: "object", properties: {} };
}
const schema = { ...inputSchema };
delete schema.$schema;
return schema;
}
function contentText(content: unknown): string {
if (!Array.isArray(content)) return "";
return (content as McpContentItem[])
.filter((item) => item && item.type === "text" && typeof item.text === "string")
.map((item) => item.text as string)
.join("\\n");
}
export default function okBridge(pi: {
on(event: string, handler: (event: unknown, ctx: unknown) => unknown): void;
registerTool(definition: Record<string, unknown>): void;
}) {
let client: OkMcpClient | null = null;
let starting: Promise<OkMcpClient> | null = null;
let sessionCwd = process.cwd();
const registeredTools = new Set<string>();
async function ensureClient(): Promise<OkMcpClient> {
if (client && client.alive) return client;
if (starting) return starting;
starting = (async () => {
const next = new OkMcpClient(sessionCwd, () => {
if (client === next) client = null;
});
try {
await next.request(
"initialize",
{
protocolVersion: "2025-06-18",
capabilities: {},
clientInfo: { name: "pi", version: "1.0.0" },
},
{ timeoutMs: INIT_TIMEOUT_MS },
);
} catch (err) {
// A timed-out initialize rejects the request while the child may
// still be running; tear it down so retries don't stack orphans.
next.close();
throw err;
}
next.notify("notifications/initialized", {});
client = next;
return next;
})();
try {
return await starting;
} finally {
starting = null;
}
}
async function registerOkTools(): Promise<number> {
const mcp = await ensureClient();
const listed = await mcp.request("tools/list", {}, { timeoutMs: INIT_TIMEOUT_MS });
const tools = Array.isArray(listed.tools) ? (listed.tools as McpToolInfo[]) : [];
for (const tool of tools) {
const name = TOOL_PREFIX + tool.name;
if (registeredTools.has(name)) continue;
registeredTools.add(name);
pi.registerTool({
name,
label: "OK " + tool.name,
description: tool.description || "Open Knowledge " + tool.name + " tool.",
parameters: toParameters(tool.inputSchema),
execute: async (
_toolCallId: string,
params: Record<string, unknown>,
signal: AbortSignal | undefined,
) => {
const live = await ensureClient();
const result = await live.request(
"tools/call",
{ name: tool.name, arguments: params ?? {} },
{ signal },
);
const text = contentText(result.content);
if (result.isError) {
throw new Error(text || "Open Knowledge tool " + tool.name + " failed");
}
return {
content: [{ type: "text", text }],
details: result.structuredContent,
};
},
});
}
return tools.length;
}
pi.on("session_start", async (_event, ctx) => {
const cwd = (ctx as { cwd?: string } | undefined)?.cwd;
if (typeof cwd === "string" && cwd.length > 0) sessionCwd = cwd;
try {
await registerOkTools();
} catch (err) {
const ui = (ctx as { ui?: { notify?: (m: string, level: string) => void } } | undefined)?.ui;
try {
ui?.notify?.(
"Open Knowledge tools unavailable: " + (err instanceof Error ? err.message : String(err)),
"warning",
);
} catch {
// Non-interactive mode; the failure will resurface on first tool use.
}
}
});
pi.on("session_shutdown", async () => {
const pending = starting;
starting = null;
const current = client;
client = null;
current?.close();
// An in-flight ensureClient would otherwise assign a live client after
// shutdown; await it and tear that one down too.
if (pending) {
try {
(await pending).close();
} catch {
// Initialization failed — its catch path already closed the client.
}
}
});
}
`;
}