@brainpilot/runtime 0.0.1

package/dist/agent-factory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent session factories.
+ *
+ *  - `mockAgentFactory`: deterministic, no API. Used when BP_MOCK=1.
+ *  - `realAgentFactory`: wraps `@earendil-works/pi-coding-agent`'s AgentSession.
+ *
+ * `selectFactory()` picks based on env (BP_MOCK).
+ *
+ * Real factory notes (confirmed against installed Pi SDK v0.79):
+ *   - `createAgentSession({ cwd, tools, customTools, sessionManager, ... })`
+ *     returns `{ session }`.
+ *   - `session.subscribe(cb)` streams `AgentSessionEvent`s; `session.prompt()`,
+ *     `session.abort()`, `session.dispose()`.
+ *   - `SystemTool` is adapted to Pi's `defineTool` (params is a plain JSON
+ *     schema, which `defineTool` accepts — verified empirically).
+ */
+import type { AgentSessionFactory } from "./types.js";
+export declare function isMockMode(): boolean;
+export declare const mockAgentFactory: AgentSessionFactory;
+/**
+ * Wrap the real Pi SDK. Imported lazily so mock-mode tests never load the SDK
+ * (and never need API credentials).
+ */
+export declare const realAgentFactory: AgentSessionFactory;
+export declare function selectFactory(): AgentSessionFactory;
+//# sourceMappingURL=agent-factory.d.ts.map

package/dist/agent-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-factory.d.ts","sourceRoot":"","sources":["../src/agent-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAA2C,MAAM,YAAY,CAAC;AAI/F,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,eAAO,MAAM,gBAAgB,EAAE,mBAE9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,mBAsC9B,CAAC;AAEF,wBAAgB,aAAa,IAAI,mBAAmB,CAEnD"}

package/dist/agent-factory.js

@@ -0,0 +1,90 @@
+import { MockAgentSession } from "./mock-agent.js";
+import { resolveGatewayModel } from "./pi-provider.js";
+export function isMockMode() {
+    return process.env.BP_MOCK === "1" || process.env.BP_MOCK === "true";
+}
+export const mockAgentFactory = async ({ sessionId, agentName, systemTools }) => {
+    return new MockAgentSession({ sessionId, agentName, systemTools });
+};
+/**
+ * Wrap the real Pi SDK. Imported lazily so mock-mode tests never load the SDK
+ * (and never need API credentials).
+ */
+export const realAgentFactory = async (params) => {
+    const sdk = (await import("@earendil-works/pi-coding-agent"));
+    const { createAgentSession, defineTool, SessionManager, DefaultResourceLoader, getAgentDir } = sdk;
+    const customTools = params.systemTools.map((t) => adaptTool(defineTool, t));
+    const agentDir = getAgentDir();
+    // Target a custom Anthropic-compatible gateway when ANTHROPIC_BASE_URL is set
+    // (Pi ignores that env var on its own). Returns {} for the default endpoint.
+    const { model, modelRegistry } = resolveGatewayModel(sdk, agentDir);
+    // `createAgentSession` has NO `systemPrompt`/`instructions` option — the
+    // per-role persona is injected through a DefaultResourceLoader. We use
+    // `appendSystemPrompt` (NOT `systemPrompt`) so Pi's built-in tool-calling
+    // guidance is preserved and our role persona is appended after it. Custom
+    // loaders are NOT auto-reloaded by the SDK, so we must reload() before use.
+    const resourceLoader = new DefaultResourceLoader({
+        cwd: params.cwd,
+        agentDir,
+        appendSystemPrompt: params.systemPrompt ? [params.systemPrompt] : [],
+    });
+    await resourceLoader.reload();
+    const { session } = await createAgentSession({
+        cwd: params.cwd,
+        tools: params.allowedToolNames,
+        customTools,
+        resourceLoader,
+        sessionManager: SessionManager.open(params.historyPath),
+        ...(model ? { model } : {}),
+        ...(modelRegistry ? { modelRegistry } : {}),
+    });
+    return new RealAgentSession(session);
+};
+export function selectFactory() {
+    return isMockMode() ? mockAgentFactory : realAgentFactory;
+}
+/** Adapt a BrainPilot SystemTool to a Pi `defineTool` definition. */
+function adaptTool(defineTool, tool) {
+    return defineTool({
+        name: tool.name,
+        // `label` is a REQUIRED field on Pi's ToolDefinition (UI display name).
+        label: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        execute: async (_toolCallId, params) => {
+            const res = await tool.execute(params ?? {});
+            // Pi's AgentToolResult has NO `isError`; failures are signalled by
+            // THROWING. Surface our SystemToolResult.isError as a thrown error so
+            // the agent sees a failed tool call (→ tool_execution_end isError →
+            // system_message warning in MasAgent).
+            if (res.isError) {
+                const text = res.content.map((c) => c.text).join("\n");
+                throw new Error(text || `${tool.name} failed`);
+            }
+            return { content: res.content, details: {} };
+        },
+    });
+}
+/** Thin adapter implementing IAgentSession over the real Pi AgentSession. */
+class RealAgentSession {
+    s;
+    constructor(s) {
+        this.s = s;
+    }
+    get sessionId() {
+        return this.s.sessionId;
+    }
+    subscribe(listener) {
+        return this.s.subscribe((e) => listener(e));
+    }
+    prompt(text) {
+        return this.s.prompt(text);
+    }
+    abort() {
+        return this.s.abort();
+    }
+    dispose() {
+        this.s.dispose();
+    }
+}
+//# sourceMappingURL=agent-factory.js.map

package/dist/agent-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-factory.js","sourceRoot":"","sources":["../src/agent-factory.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAsB,MAAM,kBAAkB,CAAC;AAE3E,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,MAAM,CAAC;AACvE,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAwB,KAAK,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,EAAE;IACnG,OAAO,IAAI,gBAAgB,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;AACrE,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAwB,KAAK,EAAE,MAAM,EAAE,EAAE;IACpE,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAqB,CAAC;IAClF,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,qBAAqB,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC;IAEnG,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;IAE5E,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAE/B,8EAA8E;IAC9E,6EAA6E;IAC7E,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,mBAAmB,CAClD,GAA+B,EAC/B,QAAQ,CACT,CAAC;IAEF,yEAAyE;IACzE,uEAAuE;IACvE,0EAA0E;IAC1E,0EAA0E;IAC1E,4EAA4E;IAC5E,MAAM,cAAc,GAAG,IAAI,qBAAqB,CAAC;QAC/C,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ;QACR,kBAAkB,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE;KACrE,CAAC,CAAC;IACH,MAAM,cAAc,CAAC,MAAM,EAAE,CAAC;IAE9B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,kBAAkB,CAAC;QAC3C,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,KAAK,EAAE,MAAM,CAAC,gBAAgB;QAC9B,WAAW;QACX,cAAc;QACd,cAAc,EAAE,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QACvD,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC,CAAC;IAEH,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAAC;AAC5D,CAAC;AAED,qEAAqE;AACrE,SAAS,SAAS,CAAC,UAA+B,EAAE,IAAgB;IAClE,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,wEAAwE;QACxE,KAAK,EAAE,IAAI,CAAC,IAAI;QAChB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,KAAK,EAAE,WAAmB,EAAE,MAA+B,EAAE,EAAE;YACtE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;YAC7C,mEAAmE;YACnE,sEAAsE;YACtE,oEAAoE;YACpE,uCAAuC;YACvC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACvD,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,SAAS,CAAC,CAAC;YACjD,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC/C,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,6EAA6E;AAC7E,MAAM,gBAAgB;IACS;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAC7C,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1B,CAAC;IACD,SAAS,CAAC,QAAmC;QAC3C,OAAO,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAiB,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,KAAK;QACH,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IACD,OAAO;QACL,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC;CACF"}

package/dist/event-bus.d.ts

@@ -0,0 +1,23 @@
+import type { AgUiEvent } from "@brainpilot/protocol";
+import type { EventListener } from "./types.js";
+export declare class EventBus {
+    private readonly opts;
+    private readonly listeners;
+    /** Ring buffer of recent events for late SSE subscribers / replay. */
+    private readonly buffer;
+    private readonly maxBuffer;
+    private writeChain;
+    constructor(opts?: {
+        persistPath?: string;
+        maxBuffer?: number;
+    });
+    subscribe(listener: EventListener): () => void;
+    /** Snapshot of buffered events (for SSE replay on connect). */
+    recent(): AgUiEvent[];
+    emit(event: AgUiEvent): void;
+    private persist;
+    /** Await all pending persistence writes (used by emergencySave). */
+    flush(): Promise<void>;
+    clear(): void;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qBAAa,QAAQ;IAQjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,UAAU,CAAoC;gBAGnC,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAK1E,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI;IAK9C,+DAA+D;IAC/D,MAAM,IAAI,SAAS,EAAE;IAIrB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAa5B,OAAO,CAAC,OAAO;IAWf,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,KAAK,IAAI,IAAI;CAId"}

package/dist/event-bus.js

@@ -0,0 +1,64 @@
+/**
+ * EventBus — per-session AG-UI event fan-out + optional jsonl persistence.
+ *
+ * The runtime is the sole producer of AG-UI events. Each SessionManager owns
+ * one bus per session; the HTTP SSE endpoint subscribes to stream events to
+ * clients. Events are also appended to `events.jsonl` for replay/recovery
+ * (§5 file ownership table).
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+export class EventBus {
+    opts;
+    listeners = new Set();
+    /** Ring buffer of recent events for late SSE subscribers / replay. */
+    buffer = [];
+    maxBuffer;
+    writeChain = Promise.resolve();
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.maxBuffer = opts.maxBuffer ?? 500;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Snapshot of buffered events (for SSE replay on connect). */
+    recent() {
+        return [...this.buffer];
+    }
+    emit(event) {
+        this.buffer.push(event);
+        if (this.buffer.length > this.maxBuffer)
+            this.buffer.shift();
+        for (const l of this.listeners) {
+            try {
+                l(event);
+            }
+            catch {
+                // A misbehaving listener must never break event fan-out.
+            }
+        }
+        if (this.opts.persistPath)
+            this.persist(event);
+    }
+    persist(event) {
+        const path = this.opts.persistPath;
+        // Serialize writes to avoid interleaving; swallow IO errors (best-effort).
+        this.writeChain = this.writeChain
+            .then(async () => {
+            await mkdir(dirname(path), { recursive: true });
+            await appendFile(path, JSON.stringify(event) + "\n", "utf8");
+        })
+            .catch(() => { });
+    }
+    /** Await all pending persistence writes (used by emergencySave). */
+    async flush() {
+        await this.writeChain;
+    }
+    clear() {
+        this.listeners.clear();
+        this.buffer.length = 0;
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,OAAO,QAAQ;IAQA;IAPF,SAAS,GAAG,IAAI,GAAG,EAAiB,CAAC;IACtD,sEAAsE;IACrD,MAAM,GAAgB,EAAE,CAAC;IACzB,SAAS,CAAS;IAC3B,UAAU,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEtD,YACmB,OAAqD,EAAE;QAAvD,SAAI,GAAJ,IAAI,CAAmD;QAExE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC;IACzC,CAAC;IAED,SAAS,CAAC,QAAuB;QAC/B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,+DAA+D;IAC/D,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,CAAC,KAAgB;QACnB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC7D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,CAAC,CAAC,KAAK,CAAC,CAAC;YACX,CAAC;YAAC,MAAM,CAAC;gBACP,yDAAyD;YAC3D,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;IAEO,OAAO,CAAC,KAAgB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAY,CAAC;QACpC,2EAA2E;QAC3E,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU;aAC9B,IAAI,CAAC,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/D,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACrB,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;CACF"}

package/dist/events.d.ts

@@ -0,0 +1,41 @@
+import type { AgUiEvent } from "@brainpilot/protocol";
+interface Ctx {
+    sessionId: string;
+    agentName?: string;
+    runId?: string;
+    threadId?: string;
+}
+export declare function newMessageId(): string;
+export declare function newRunId(): string;
+export declare const ev: {
+    runStarted(ctx: Ctx, parentRunId?: string): AgUiEvent;
+    runFinished(ctx: Ctx, result?: unknown): AgUiEvent;
+    runError(ctx: Ctx, message: string, code?: string): AgUiEvent;
+    textMessageStart(ctx: Ctx, messageId: string, role?: string): AgUiEvent;
+    textMessageContent(ctx: Ctx, messageId: string, delta: string): AgUiEvent;
+    textMessageEnd(ctx: Ctx, messageId: string): AgUiEvent;
+    reasoningMessageStart(ctx: Ctx, messageId: string): AgUiEvent;
+    reasoningMessageContent(ctx: Ctx, messageId: string, delta: string): AgUiEvent;
+    reasoningMessageEnd(ctx: Ctx, messageId: string): AgUiEvent;
+    toolCallStart(ctx: Ctx, toolCallId: string, toolName: string, parentMessageId?: string): AgUiEvent;
+    toolCallArgs(ctx: Ctx, toolCallId: string, delta: string): AgUiEvent;
+    toolCallEnd(ctx: Ctx, toolCallId: string): AgUiEvent;
+    toolCallResult(ctx: Ctx, toolCallId: string, content: string, isError?: boolean, messageId?: string): AgUiEvent;
+    agentStatusUpdate(ctx: Ctx, name: string, status: "idle" | "running" | "error" | "stopped", extra?: {
+        activeRunId?: string;
+        activeToolExecutions?: string[];
+        lastError?: {
+            message: string;
+            timestamp: string;
+            consecutiveCount: number;
+        };
+    }): AgUiEvent;
+    systemMessage(sessionId: string, level: "info" | "warning" | "error" | "fatal", message: string, opts?: {
+        agent?: string;
+        details?: string;
+        recoverable?: boolean;
+    }): AgUiEvent;
+    custom(ctx: Ctx, name: string, value: unknown): AgUiEvent;
+};
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAMtD,UAAU,GAAG;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgBD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AACD,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,eAAO,MAAM,EAAE;oBACG,GAAG,gBAAgB,MAAM,GAAG,SAAS;qBAGpC,GAAG,WAAW,OAAO,GAAG,SAAS;kBAGpC,GAAG,WAAW,MAAM,kBAA2B,SAAS;0BAGhD,GAAG,aAAa,MAAM,kBAAuB,SAAS;4BAGpD,GAAG,aAAa,MAAM,SAAS,MAAM,GAAG,SAAS;wBAGrD,GAAG,aAAa,MAAM,GAAG,SAAS;+BAG3B,GAAG,aAAa,MAAM,GAAG,SAAS;iCAGhC,GAAG,aAAa,MAAM,SAAS,MAAM,GAAG,SAAS;6BAGrD,GAAG,aAAa,MAAM,GAAG,SAAS;uBAGxC,GAAG,cAAc,MAAM,YAAY,MAAM,oBAAoB,MAAM,GAAG,SAAS;sBAShF,GAAG,cAAc,MAAM,SAAS,MAAM,GAAG,SAAS;qBAGnD,GAAG,cAAc,MAAM,GAAG,SAAS;wBAGhC,GAAG,cAAc,MAAM,WAAW,MAAM,iCAA+B,MAAM,GAAG,SAAS;2BAWtG,GAAG,QACF,MAAM,UACJ,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,UACxC;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;QAChC,SAAS,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,gBAAgB,EAAE,MAAM,CAAA;SAAE,CAAC;KAC9E,GACA,SAAS;6BAoBC,MAAM,SACV,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,WACpC,MAAM,SACR;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GACjE,SAAS;gBAYA,GAAG,QAAQ,MAAM,SAAS,OAAO,GAAG,SAAS;CAG1D,CAAC"}

package/dist/events.js

@@ -0,0 +1,119 @@
+/**
+ * AG-UI event constructors. Every outgoing event is built here so the wire
+ * shape (snake_case fields, UPPERCASE/snake_case `type`) matches
+ * `@brainpilot/protocol` exactly. We validate via `parseEvent` in tests.
+ *
+ * The protocol event envelope carries `session_id`, optional `run_id`,
+ * `thread_id`, `agent_name`, and `_ts`. We always inject `session_id` and
+ * `agent_name` + `_ts`; `run_id` when known.
+ */
+import { randomUUID } from "node:crypto";
+function ts() {
+    return new Date().toISOString();
+}
+function envelope(ctx) {
+    const e = { session_id: ctx.sessionId, _ts: ts() };
+    if (ctx.agentName !== undefined)
+        e.agent_name = ctx.agentName;
+    if (ctx.runId !== undefined)
+        e.run_id = ctx.runId;
+    if (ctx.threadId !== undefined)
+        e.thread_id = ctx.threadId;
+    return e;
+}
+export function newMessageId() {
+    return `msg_${randomUUID()}`;
+}
+export function newRunId() {
+    return `run_${randomUUID()}`;
+}
+export const ev = {
+    runStarted(ctx, parentRunId) {
+        return { type: "RUN_STARTED", ...envelope(ctx), parent_run_id: parentRunId };
+    },
+    runFinished(ctx, result) {
+        return { type: "RUN_FINISHED", ...envelope(ctx), result };
+    },
+    runError(ctx, message, code = "RUNTIME_ERROR") {
+        return { type: "RUN_ERROR", ...envelope(ctx), message, code };
+    },
+    textMessageStart(ctx, messageId, role = "assistant") {
+        return { type: "TEXT_MESSAGE_START", ...envelope(ctx), message_id: messageId, role };
+    },
+    textMessageContent(ctx, messageId, delta) {
+        return { type: "TEXT_MESSAGE_CONTENT", ...envelope(ctx), message_id: messageId, delta };
+    },
+    textMessageEnd(ctx, messageId) {
+        return { type: "TEXT_MESSAGE_END", ...envelope(ctx), message_id: messageId };
+    },
+    reasoningMessageStart(ctx, messageId) {
+        return { type: "REASONING_MESSAGE_START", ...envelope(ctx), message_id: messageId };
+    },
+    reasoningMessageContent(ctx, messageId, delta) {
+        return { type: "REASONING_MESSAGE_CONTENT", ...envelope(ctx), message_id: messageId, delta };
+    },
+    reasoningMessageEnd(ctx, messageId) {
+        return { type: "REASONING_MESSAGE_END", ...envelope(ctx), message_id: messageId };
+    },
+    toolCallStart(ctx, toolCallId, toolName, parentMessageId) {
+        return {
+            type: "TOOL_CALL_START",
+            ...envelope(ctx),
+            tool_call_id: toolCallId,
+            tool_call_name: toolName,
+            parent_message_id: parentMessageId,
+        };
+    },
+    toolCallArgs(ctx, toolCallId, delta) {
+        return { type: "TOOL_CALL_ARGS", ...envelope(ctx), tool_call_id: toolCallId, delta };
+    },
+    toolCallEnd(ctx, toolCallId) {
+        return { type: "TOOL_CALL_END", ...envelope(ctx), tool_call_id: toolCallId };
+    },
+    toolCallResult(ctx, toolCallId, content, isError = false, messageId) {
+        return {
+            type: "TOOL_CALL_RESULT",
+            ...envelope(ctx),
+            tool_call_id: toolCallId,
+            message_id: messageId ?? newMessageId(),
+            content,
+            is_error: isError,
+        };
+    },
+    agentStatusUpdate(ctx, name, status, extra) {
+        const e = {
+            type: "agent_status_update",
+            ...envelope({ ...ctx, agentName: name }),
+            name,
+            status,
+        };
+        if (extra?.activeRunId !== undefined)
+            e.active_run_id = extra.activeRunId;
+        if (extra?.activeToolExecutions && extra.activeToolExecutions.length)
+            e.active_tool_executions = extra.activeToolExecutions;
+        if (extra?.lastError) {
+            e.last_error = {
+                message: extra.lastError.message,
+                timestamp: extra.lastError.timestamp,
+                consecutive_count: extra.lastError.consecutiveCount,
+            };
+        }
+        return e;
+    },
+    systemMessage(sessionId, level, message, opts) {
+        return {
+            type: "system_message",
+            session_id: sessionId,
+            agent: opts?.agent,
+            level,
+            message,
+            details: opts?.details,
+            timestamp: ts(),
+            recoverable: opts?.recoverable ?? true,
+        };
+    },
+    custom(ctx, name, value) {
+        return { type: "CUSTOM", ...envelope(ctx), name, value };
+    },
+};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @brainpilot/runtime — Pi SDK multi-agent orchestration + STATE AUTHORITY.
+ *
+ * Public surface: SessionManager, MasAgent, Mailbox, GraphOfTrace, event
+ * helpers, agent factories, server bootstrap.
+ */
+export declare const RUNTIME_NAME = "@brainpilot/runtime";
+export { SessionManager } from "./session-manager.js";
+export type { SessionManagerOptions } from "./session-manager.js";
+export { MasAgent } from "./mas-agent.js";
+export type { AgentStatus, MasAgentOpts } from "./mas-agent.js";
+export { Mailbox } from "./mailbox.js";
+export type { MailboxMessage, MsgType } from "./mailbox.js";
+export { GraphOfTrace } from "./trace.js";
+export { EventBus } from "./event-bus.js";
+export { ev, newMessageId, newRunId } from "./events.js";
+export { MockAgentSession } from "./mock-agent.js";
+export { selectFactory, isMockMode, mockAgentFactory, realAgentFactory, } from "./agent-factory.js";
+export { allSystemTools, systemToolsForRole, systemToolNamesForRole, builtinToolNamesForRole, AGENT_TOOL_CONFIG, BUILTIN_TOOL_CONFIG, } from "./tools/system-tools.js";
+export type { ToolDeps } from "./tools/system-tools.js";
+export { createServer, startServer } from "./server.js";
+export type { StartServerOptions } from "./server.js";
+export { McpBridge, loadMcpServersConfig, defaultMcpConnect } from "./mcp-bridge.js";
+export type { McpServersConfig, McpServerSpec, McpClientLike, McpConnectFn } from "./mcp-bridge.js";
+export type { AgentRole, IAgentSession, AgentSessionFactory, PiAgentEvent, PiAssistantMessageEvent, SystemTool, SystemToolResult, EventListener, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EACL,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrF,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpG,YAAY,EACV,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,uBAAuB,EACvB,UAAU,EACV,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @brainpilot/runtime — Pi SDK multi-agent orchestration + STATE AUTHORITY.
+ *
+ * Public surface: SessionManager, MasAgent, Mailbox, GraphOfTrace, event
+ * helpers, agent factories, server bootstrap.
+ */
+export const RUNTIME_NAME = "@brainpilot/runtime";
+export { SessionManager } from "./session-manager.js";
+export { MasAgent } from "./mas-agent.js";
+export { Mailbox } from "./mailbox.js";
+export { GraphOfTrace } from "./trace.js";
+export { EventBus } from "./event-bus.js";
+export { ev, newMessageId, newRunId } from "./events.js";
+export { MockAgentSession } from "./mock-agent.js";
+export { selectFactory, isMockMode, mockAgentFactory, realAgentFactory, } from "./agent-factory.js";
+export { allSystemTools, systemToolsForRole, systemToolNamesForRole, builtinToolNamesForRole, AGENT_TOOL_CONFIG, BUILTIN_TOOL_CONFIG, } from "./tools/system-tools.js";
+export { createServer, startServer } from "./server.js";
+export { McpBridge, loadMcpServersConfig, defaultMcpConnect } from "./mcp-bridge.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EACL,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxD,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/mailbox.d.ts

@@ -0,0 +1,31 @@
+export type MsgType = "user_message" | "result_deliver" | "task_delegate" | "trace_event" | "system";
+export interface MailboxMessage {
+    fromAgent: string;
+    toAgent: string;
+    content: string;
+    msgType: MsgType;
+    timestamp: number;
+}
+export declare class Mailbox {
+    readonly sessionId: string;
+    private readonly baseDir?;
+    private readonly inboxes;
+    private writeChain;
+    constructor(sessionId: string, baseDir?: string | undefined);
+    private inbox;
+    /** Write a message to `toAgent`'s inbox (in-memory + persisted). */
+    write(msg: Omit<MailboxMessage, "timestamp"> & {
+        timestamp?: number;
+    }): Promise<void>;
+    /** Atomically drain `agent`'s inbox (returns messages, clears the box). */
+    read(agent: string): Promise<MailboxMessage[]>;
+    /** Non-destructive peek. */
+    peek(agent: string): readonly MailboxMessage[];
+    count(agent: string): number;
+    private inboxPath;
+    private persist;
+    /** Recover all persisted inboxes from disk into memory (crash recovery). */
+    recover(): Promise<void>;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=mailbox.d.ts.map

package/dist/mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../src/mailbox.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,OAAO,GACf,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,OAAO;IAKhB,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAL3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,UAAU,CAAoC;gBAG3C,SAAS,EAAE,MAAM,EACT,OAAO,CAAC,EAAE,MAAM,YAAA;IAGnC,OAAO,CAAC,KAAK;IASb,oEAAoE;IAC9D,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3F,2EAA2E;IACrE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAOpD,4BAA4B;IAC5B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE;IAI9C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI5B,OAAO,CAAC,SAAS;YAKH,OAAO;IAarB,4EAA4E;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/mailbox.js

@@ -0,0 +1,99 @@
+/**
+ * Mailbox — Principal↔Expert message bus (§5/§9).
+ *
+ * Single-process model: no fcntl needed. An in-memory per-agent inbox provides
+ * real-time delivery; each inbox is also persisted to
+ * `.bp/{sid}/mailbox/{agent}.json` so unread messages survive a crash (§12.1).
+ *
+ * Delivery semantics (ported from legacy `mailbox.py`): reading an inbox
+ * atomically drains it (avoids re-delivery). Writes append.
+ */
+import { mkdir, readFile, writeFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+export class Mailbox {
+    sessionId;
+    baseDir;
+    inboxes = new Map();
+    writeChain = Promise.resolve();
+    constructor(sessionId, baseDir) {
+        this.sessionId = sessionId;
+        this.baseDir = baseDir;
+    }
+    inbox(agent) {
+        let box = this.inboxes.get(agent);
+        if (!box) {
+            box = [];
+            this.inboxes.set(agent, box);
+        }
+        return box;
+    }
+    /** Write a message to `toAgent`'s inbox (in-memory + persisted). */
+    async write(msg) {
+        const full = { ...msg, timestamp: msg.timestamp ?? Date.now() };
+        this.inbox(full.toAgent).push(full);
+        await this.persist(full.toAgent);
+    }
+    /** Atomically drain `agent`'s inbox (returns messages, clears the box). */
+    async read(agent) {
+        const box = this.inbox(agent);
+        const out = box.splice(0, box.length);
+        if (out.length > 0)
+            await this.persist(agent);
+        return out;
+    }
+    /** Non-destructive peek. */
+    peek(agent) {
+        return [...this.inbox(agent)];
+    }
+    count(agent) {
+        return this.inbox(agent).length;
+    }
+    inboxPath(agent) {
+        if (!this.baseDir)
+            return undefined;
+        return join(this.baseDir, `${agent}.json`);
+    }
+    async persist(agent) {
+        const path = this.inboxPath(agent);
+        if (!path)
+            return;
+        const snapshot = [...this.inbox(agent)];
+        this.writeChain = this.writeChain
+            .then(async () => {
+            await mkdir(this.baseDir, { recursive: true });
+            await writeFile(path, JSON.stringify(snapshot, null, 2), "utf8");
+        })
+            .catch(() => { });
+        await this.writeChain;
+    }
+    /** Recover all persisted inboxes from disk into memory (crash recovery). */
+    async recover() {
+        if (!this.baseDir)
+            return;
+        let files;
+        try {
+            files = await readdir(this.baseDir);
+        }
+        catch {
+            return; // no mailbox dir yet
+        }
+        for (const f of files) {
+            if (!f.endsWith(".json"))
+                continue;
+            const agent = f.slice(0, -".json".length);
+            try {
+                const raw = await readFile(join(this.baseDir, f), "utf8");
+                const msgs = JSON.parse(raw);
+                if (Array.isArray(msgs) && msgs.length)
+                    this.inboxes.set(agent, msgs);
+            }
+            catch {
+                // skip corrupt inbox file
+            }
+        }
+    }
+    async flush() {
+        await this.writeChain;
+    }
+}
+//# sourceMappingURL=mailbox.js.map

package/dist/mailbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.js","sourceRoot":"","sources":["../src/mailbox.ts"],"names":[],"mappings":"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"}