@pi-harness/pi-harness 0.1.1

package/packages/core/src/stdio.ts

@@ -0,0 +1,88 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { PiHarnessLaunch, PiRuntimeService } from "./services.js";
+
+export interface PiHarnessStdio {
+  readPrompt(): Promise<string>;
+  writeOutput(text: string): void;
+  writeError(text: string): void;
+}
+
+export interface PiHarnessApplication {
+  run(): Promise<number>;
+}
+
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    piHarnessStdio: PiHarnessStdio;
+    piApplication: PiHarnessApplication;
+  }
+}
+
+export function provideStdioContext(context: Context, stdio: PiHarnessStdio): () => void {
+  return context.provide("piHarnessStdio", stdio);
+}
+
+function promptFromArgs(args: readonly string[]): string | undefined {
+  if (args.length === 0) return undefined;
+  if (args[0] === "--prompt") {
+    const prompt = args[1];
+    if (prompt === undefined) throw new Error("--prompt requires a value");
+    if (args.length > 2) throw new Error("--prompt accepts exactly one value");
+    return prompt;
+  }
+  if (args[0]?.startsWith("--prompt=")) return args[0].slice("--prompt=".length);
+  if (args.some((arg) => arg.startsWith("-"))) throw new Error(`Unknown stdio option: ${args.find((arg) => arg.startsWith("-")) ?? ""}`);
+  return args.join(" ");
+}
+
+export class StdioApplication implements PiHarnessApplication {
+  readonly #runtime: PiRuntimeService;
+  readonly #launch: PiHarnessLaunch;
+  readonly #stdio: PiHarnessStdio;
+  #running = false;
+
+  constructor(runtime: PiRuntimeService, launch: PiHarnessLaunch, stdio: PiHarnessStdio) {
+    this.#runtime = runtime;
+    this.#launch = launch;
+    this.#stdio = stdio;
+  }
+
+  writeSessionEvent(event: AgentSessionEvent): void {
+    if (!this.#running) return;
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") this.#stdio.writeOutput(event.assistantMessageEvent.delta);
+  }
+
+  async run(): Promise<number> {
+    if (this.#running) throw new Error("stdio application is already running");
+    this.#running = true;
+    try {
+      let prompt: string;
+      try {
+        prompt = promptFromArgs(this.#launch.args) ?? await this.#stdio.readPrompt();
+      } catch (error) {
+        this.#stdio.writeError(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+      }
+      if (prompt.trim().length === 0) {
+        this.#stdio.writeError("Prompt is empty\n");
+        return 2;
+      }
+      try {
+        await this.#runtime.prompt(prompt);
+      } catch (error) {
+        this.#stdio.writeError(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+      }
+      const lastMessage = this.#runtime.session.messages.at(-1);
+      if (lastMessage?.role === "assistant" && (lastMessage.stopReason === "error" || lastMessage.stopReason === "aborted")) {
+        this.#stdio.writeError(`${lastMessage.errorMessage ?? `Request ${lastMessage.stopReason}`}\n`);
+        return 1;
+      }
+      this.#stdio.writeOutput("\n");
+      return 0;
+    } finally {
+      this.#running = false;
+    }
+  }
+}

package/packages/core/test/boot.test.ts

@@ -0,0 +1,86 @@
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, describe, expect, test } from "vitest";
+import { bootHarness, type BootedHarness } from "../src/boot.js";
+
+const booted: BootedHarness[] = [];
+
+afterEach(async () => {
+  await Promise.all(booted.splice(0).map(async (harness) => harness.dispose()));
+});
+
+async function createProfile(entries: unknown[]): Promise<{ directory: string; profilePath: string }> {
+  const directory = await mkdtemp(join(tmpdir(), "pi-harness-boot-"));
+  const profilePath = join(directory, "cordis.yml");
+  await writeFile(profilePath, JSON.stringify(entries), "utf8");
+  return { directory, profilePath };
+}
+
+async function createPlugin(directory: string, name: string, source: string): Promise<string> {
+  const path = join(directory, `${name}.mjs`);
+  await writeFile(path, source, "utf8");
+  return pathToFileURL(path).href;
+}
+
+describe("bootHarness", () => {
+  test("loads a profile and activates its plugin", async () => {
+    const profile = await createProfile([]);
+    const plugin = await createPlugin(profile.directory, "provider", `export default function provider(ctx, config) { ctx.provide("fixtureValue", config.value); }`);
+    await writeFile(profile.profilePath, JSON.stringify([{ name: plugin, config: { value: "active" } }]), "utf8");
+
+    const harness = await bootHarness({ configPath: profile.profilePath });
+    booted.push(harness);
+
+    expect(harness.context.get("fixtureValue")).toBe("active");
+  });
+
+  test("fails loudly when a plugin module cannot be resolved", async () => {
+    const profile = await createProfile([{ name: "./missing-plugin.mjs" }]);
+
+    await expect(bootHarness({ configPath: profile.profilePath })).rejects.toThrow(/missing-plugin\.mjs/);
+  });
+
+  test("reports plugins left pending by unresolved injections", async () => {
+    const profile = await createProfile([]);
+    const plugin = await createPlugin(profile.directory, "consumer", `export default { inject: ["serviceThatDoesNotExist"], apply() {} };`);
+    await writeFile(profile.profilePath, JSON.stringify([{ name: plugin }]), "utf8");
+
+    await expect(bootHarness({ configPath: profile.profilePath })).rejects.toThrow(/serviceThatDoesNotExist/);
+  });
+
+  test("disposes already-active plugins when a later activation fails", async () => {
+    const profile = await createProfile([]);
+    const markerPath = join(profile.directory, "lifecycle.txt");
+    const owner = await createPlugin(profile.directory, "owner", `import { appendFileSync, writeFileSync } from "node:fs"; export default function owner(ctx, config) { writeFileSync(config.markerPath, "started"); ctx.provide("fixtureOwnerReady", true); ctx.effect(() => () => appendFileSync(config.markerPath, ":disposed")); }`);
+    const failure = await createPlugin(profile.directory, "failure", `export default { inject: ["fixtureOwnerReady"], apply() { throw new Error("fixture activation failed"); } };`);
+    await writeFile(profile.profilePath, JSON.stringify([{ name: owner, config: { markerPath } }, { name: failure }]), "utf8");
+
+    await expect(bootHarness({ configPath: profile.profilePath })).rejects.toThrow(/fixture activation failed/);
+    await expect(readFile(markerPath, "utf8")).resolves.toBe("started:disposed");
+  });
+
+  test("does not rewrite a profile when a nested group rolls back", async () => {
+    const profile = await createProfile([]);
+    const active = await createPlugin(profile.directory, "active", `export default function active(ctx) { ctx.provide("fixtureNestedReady", true); }`);
+    const failure = await createPlugin(profile.directory, "nested-failure", `export default { inject: ["fixtureNestedReady"], apply() { throw new Error("nested activation failed"); } };`);
+    const source = JSON.stringify([{ id: "fixture-group", name: "cordis:group", group: true, config: [{ id: "active", name: active }, { id: "nested-failure", name: failure }] }]);
+    await writeFile(profile.profilePath, source, "utf8");
+
+    await expect(bootHarness({ configPath: profile.profilePath })).rejects.toThrow(/nested activation failed/);
+
+    await expect(readFile(profile.profilePath, "utf8")).resolves.toBe(source);
+  });
+
+  test("forwards Cordis full-reload requests to the host", async () => {
+    const profile = await createProfile([]);
+    let reloads = 0;
+    const harness = await bootHarness({ configPath: profile.profilePath, onFullReload() { reloads += 1; } });
+    booted.push(harness);
+
+    harness.context.loader.exit();
+
+    expect(reloads).toBe(1);
+  });
+});

package/packages/core/test/profile.test.ts

@@ -0,0 +1,39 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, test } from "vitest";
+import { resolveProfileConfig } from "../src/profile.js";
+
+async function createProfiles(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "pi-harness-profiles-"));
+  await mkdir(join(root, "default"));
+  await writeFile(join(root, "default", "cordis.yml"), "[]\n", "utf8");
+  return root;
+}
+
+describe("resolveProfileConfig", () => {
+  test("resolves the default built-in profile", async () => {
+    const profilesDir = await createProfiles();
+
+    await expect(resolveProfileConfig({ profilesDir })).resolves.toBe(join(profilesDir, "default", "cordis.yml"));
+  });
+
+  test("resolves an explicit config path from the invoking directory", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "pi-harness-config-"));
+    await writeFile(join(cwd, "custom.yml"), "[]\n", "utf8");
+
+    await expect(resolveProfileConfig({ configPath: "custom.yml", cwd })).resolves.toBe(resolve(cwd, "custom.yml"));
+  });
+
+  test("rejects profile names that can escape the profiles directory", async () => {
+    const profilesDir = await createProfiles();
+
+    await expect(resolveProfileConfig({ profile: "../outside", profilesDir })).rejects.toThrow(/invalid profile name/i);
+  });
+
+  test("rejects a missing profile with its resolved path", async () => {
+    const profilesDir = await createProfiles();
+
+    await expect(resolveProfileConfig({ profile: "missing", profilesDir })).rejects.toThrow(join(profilesDir, "missing", "cordis.yml"));
+  });
+});

package/packages/core/test/profiles.integration.test.ts

@@ -0,0 +1,93 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { bootHarness, type BootedHarness } from "../src/boot.js";
+import { resolveProfileConfig } from "../src/profile.js";
+import { provideLaunchContext } from "../src/services.js";
+import { provideStdioContext } from "../src/stdio.js";
+
+const booted: BootedHarness[] = [];
+
+afterEach(async () => {
+  await Promise.all(booted.splice(0).map(async (harness) => harness.dispose()));
+});
+
+async function bootProfile(profile: string): Promise<{ harness: BootedHarness; cwd: string }> {
+  const cwd = await mkdtemp(join(tmpdir(), "pi-harness-profile-cwd-"));
+  const agentDir = await mkdtemp(join(tmpdir(), "pi-harness-profile-agent-"));
+  const configPath = await resolveProfileConfig({ profile });
+  const harness = await bootHarness({
+    configPath,
+    prepare(context) {
+      provideLaunchContext(context, { cwd, agentDir, args: [], requestExit() {} });
+      provideStdioContext(context, { readPrompt() { return Promise.resolve(""); }, writeOutput() {}, writeError() {} });
+    },
+  });
+  booted.push(harness);
+  return { harness, cwd };
+}
+
+describe("packaged profiles", () => {
+  test("boots the default production profile without HMR", async () => {
+    const { harness } = await bootProfile("default");
+    const names = [...harness.context.loader.entries()].map((entry) => entry.options.name);
+
+    expect(harness.context.get("piModels")?.model.provider).toBe("deepseek");
+    expect(harness.context.get("piApplication")).toBeDefined();
+    expect(harness.context.get("hmr")).toBeUndefined();
+    expect(names).not.toContain("@deepseek-ai/cordis-plugin-hmr");
+  });
+
+  test("boots the development profile with logger, timer, and HMR plugins", async () => {
+    const { harness, cwd } = await bootProfile("development");
+    const entries = [...harness.context.loader.entries()];
+    const names = entries.map((entry) => entry.options.name);
+    const timer = entries.find((entry) => entry.options.name === "@deepseek-ai/cordis-plugin-timer");
+    const hmr = entries.find((entry) => entry.options.name === "@deepseek-ai/cordis-plugin-hmr");
+
+    expect(timer?.fiber?.ctx.get("timer")).toBeDefined();
+    expect(hmr?.fiber?.ctx.get("hmr")).toMatchObject({ baseDir: cwd });
+    expect(names).toEqual(expect.arrayContaining(["@deepseek-ai/cordis-plugin-logger-console", "@deepseek-ai/cordis-plugin-timer", "@deepseek-ai/cordis-plugin-hmr"]));
+  });
+
+  test("activates an external tool plugin before the runtime through Cordis injection", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "pi-harness-custom-cwd-"));
+    const agentDir = await mkdtemp(join(tmpdir(), "pi-harness-custom-agent-"));
+    const configPath = join(cwd, "cordis.yml");
+    const plugins = {
+      models: import.meta.resolve("@pi-harness/core/plugins/models"),
+      resources: import.meta.resolve("@pi-harness/core/plugins/resources"),
+      model: import.meta.resolve("@pi-harness/core/plugins/model"),
+      session: import.meta.resolve("@pi-harness/core/plugins/session"),
+      tools: import.meta.resolve("@pi-harness/core/plugins/tools"),
+      hello: import.meta.resolve("@pi-harness/plugin-hello"),
+      runtime: import.meta.resolve("@pi-harness/core/plugins/runtime"),
+      stdio: import.meta.resolve("@pi-harness/core/plugins/stdio"),
+    };
+    await writeFile(configPath, JSON.stringify([
+      { id: "models", name: plugins.models, config: { provider: "deepseek", model: "deepseek-v4-flash", refreshOnCreate: false } },
+      { id: "resources", name: plugins.resources, config: { noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true } },
+      { id: "model", name: plugins.model, config: {} },
+      { id: "session", name: plugins.session, config: { storage: "memory" } },
+      { id: "tools", name: plugins.tools, config: { names: [] } },
+      { id: "hello", name: plugins.hello, config: {} },
+      { id: "runtime", name: plugins.runtime, inject: ["piHelloTool"], config: { thinkingLevel: "medium" } },
+      { id: "stdio", name: plugins.stdio, config: {} },
+    ]), "utf8");
+    const harness = await bootHarness({
+      configPath,
+      prepare(context) {
+        provideLaunchContext(context, { cwd, agentDir, args: [], requestExit() {} });
+        provideStdioContext(context, { readPrompt() { return Promise.resolve(""); }, writeOutput() {}, writeError() {} });
+      },
+    });
+    booted.push(harness);
+
+    expect(harness.context.get("piTools")?.snapshot().customTools.map((tool) => tool.name)).toEqual(["hello"]);
+    const sessionTools = harness.context.get("piRuntime")?.session.getAllTools();
+    expect(sessionTools).toHaveLength(1);
+    expect(sessionTools?.[0]?.name).toBe("hello");
+    expect(sessionTools?.[0]?.sourceInfo.source).toBe("sdk");
+  });
+});

package/packages/core/test/runtime-fixture.ts

@@ -0,0 +1,31 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { fauxProvider, type FauxProviderHandle, type FauxResponseStep } from "@earendil-works/pi-ai/providers/faux";
+import { provideLaunchContext } from "../src/services.js";
+import resourcesPlugin from "../src/plugins/resources.js";
+import runtimePlugin from "../src/plugins/runtime.js";
+import sessionPlugin from "../src/plugins/session.js";
+import toolsPlugin from "../src/plugins/tools.js";
+
+export async function createTestRuntimeContext(responses: FauxResponseStep[], toolNames: string[] = []): Promise<{ context: Context; faux: FauxProviderHandle }> {
+  const cwd = await mkdtemp(join(tmpdir(), "pi-harness-runtime-"));
+  const agentDir = await mkdtemp(join(tmpdir(), "pi-harness-runtime-agent-"));
+  const context = new Context();
+  provideLaunchContext(context, { cwd, agentDir, args: [], requestExit() {} });
+  const modelRuntime = await ModelRuntime.create({ refreshOnCreate: false, modelsPath: null });
+  const faux = fauxProvider({ provider: "pi-harness-test", models: [{ id: "deterministic" }] });
+  faux.setResponses(responses);
+  modelRuntime.registerNativeProvider(faux.provider);
+  const model = modelRuntime.getModel("pi-harness-test", "deterministic");
+  if (model === undefined) throw new Error("Faux model registration failed");
+  context.provide("piModelRuntime", { runtime: modelRuntime, provider: "pi-harness-test", model: "deterministic" });
+  await context.plugin(resourcesPlugin, { noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true });
+  context.provide("piModels", { runtime: modelRuntime, model });
+  await context.plugin(sessionPlugin, { storage: "memory" });
+  await context.plugin(toolsPlugin, { names: toolNames });
+  await context.plugin(runtimePlugin, { thinkingLevel: "off" });
+  return { context, faux };
+}

package/packages/core/test/runtime.test.ts

@@ -0,0 +1,54 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { fauxAssistantMessage } from "@earendil-works/pi-ai/providers/faux";
+import { afterEach, describe, expect, test } from "vitest";
+import { createTestRuntimeContext } from "./runtime-fixture.js";
+
+const contexts: Context[] = [];
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(async (context) => context.fiber.dispose()));
+});
+
+async function createRuntimeContext(): Promise<{ context: Context; responseText: string[]; callCount: () => number }> {
+  const { context, faux } = await createTestRuntimeContext([fauxAssistantMessage("deterministic response")]);
+  contexts.push(context);
+  const responseText: string[] = [];
+  context.piRuntime.session.subscribe((event) => {
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") responseText.push(event.assistantMessageEvent.delta);
+  });
+  return { context, responseText, callCount: () => faux.state.callCount };
+}
+
+describe("Pi runtime plugin", () => {
+  test("completes a deterministic Pi agent run", async () => {
+    const { context, responseText, callCount } = await createRuntimeContext();
+
+    await context.piRuntime.prompt("respond once");
+
+    expect(responseText.join("")).toBe("deterministic response");
+    expect(callCount()).toBe(1);
+  });
+
+  test("disposes the Pi session with its Cordis fiber", async () => {
+    const { context } = await createRuntimeContext();
+    const runtime = context.piRuntime;
+
+    await context.fiber.dispose();
+
+    await expect(runtime.prompt("too late")).rejects.toThrow(/disposed/);
+  });
+
+  test("replaces the active session through the Pi session runtime", async () => {
+    const { context } = await createRuntimeContext();
+    const before = context.piRuntime.session.sessionId;
+
+    await context.piRuntime.sessionRuntime.newSession();
+
+    expect(context.piRuntime.session.sessionId).not.toBe(before);
+    expect(context.piRuntime.session.messages).toEqual([]);
+  });
+
+  test("fails activation when configured core tools are unknown to Pi", async () => {
+    await expect(createTestRuntimeContext([], ["not-a-pi-tool"])).rejects.toThrow(/not-a-pi-tool/);
+  });
+});

package/packages/core/test/services.test.ts

@@ -0,0 +1,131 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { afterEach, describe, expect, test } from "vitest";
+import { PiToolRegistry, provideLaunchContext } from "../src/services.js";
+import modelPlugin from "../src/plugins/model.js";
+import modelsPlugin from "../src/plugins/models.js";
+import resourcesPlugin from "../src/plugins/resources.js";
+import sessionPlugin from "../src/plugins/session.js";
+import toolsPlugin from "../src/plugins/tools.js";
+
+const contexts: Context[] = [];
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(async (context) => context.fiber.dispose()));
+});
+
+async function createContext(): Promise<{ context: Context; cwd: string; agentDir: string }> {
+  const cwd = await mkdtemp(join(tmpdir(), "pi-harness-cwd-"));
+  const agentDir = await mkdtemp(join(tmpdir(), "pi-harness-agent-"));
+  const context = new Context();
+  contexts.push(context);
+  provideLaunchContext(context, { cwd, agentDir, args: [], requestExit() {} });
+  return { context, cwd, agentDir };
+}
+
+const modelConfig = { provider: "deepseek", model: "deepseek-v4-flash", refreshOnCreate: false } as const;
+const isolatedResources = { noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true } as const;
+
+describe("Pi domain plugins", () => {
+  test("fails activation when the selected model does not exist", async () => {
+    const { context } = await createContext();
+
+    await context.plugin(modelsPlugin, { provider: "missing-provider", model: "missing-model", refreshOnCreate: false });
+    await context.plugin(resourcesPlugin, isolatedResources);
+
+    await expect(context.plugin(modelPlugin)).rejects.toThrow(/missing-provider\/missing-model/);
+  });
+
+  test("activates a pending resources plugin after its models dependency", async () => {
+    const { context, cwd } = await createContext();
+    const pendingResources = context.plugin(resourcesPlugin, isolatedResources);
+
+    await context.plugin(modelsPlugin, modelConfig);
+    await pendingResources;
+
+    expect(context.get("piResources")?.cwd).toBe(cwd);
+    expect(context.get("piResources")?.modelRuntime).toBe(context.get("piModelRuntime")?.runtime);
+  });
+
+  test("isolates Pi model files under the configured agent directory", async () => {
+    const { context, agentDir } = await createContext();
+
+    await context.plugin(modelsPlugin, modelConfig);
+
+    const runtime = context.piModelRuntime.runtime as unknown as { modelsPath: string };
+    expect(runtime.modelsPath).toBe(join(agentDir, "models.json"));
+  });
+
+  test("selects models registered by Pi extensions after resource loading", async () => {
+    const { context, agentDir } = await createContext();
+    const extensionsDir = join(agentDir, "extensions");
+    await mkdir(extensionsDir, { recursive: true });
+    await writeFile(join(extensionsDir, "provider.ts"), `export default function (pi) { pi.registerProvider("extension-provider", { baseUrl: "https://example.invalid", apiKey: "test-key", api: "openai-completions", models: [{ id: "extension-model", name: "Extension Model", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 4096, maxTokens: 1024 }] }); }`, "utf8");
+
+    await context.plugin(modelsPlugin, { provider: "extension-provider", model: "extension-model", refreshOnCreate: false });
+    await context.plugin(resourcesPlugin, { ...isolatedResources, noExtensions: false });
+    await context.plugin(modelPlugin);
+
+    expect(context.piModels.model.id).toBe("extension-model");
+    expect(context.piModels.model.provider).toBe("extension-provider");
+  });
+
+  test("creates an in-memory session when configured", async () => {
+    const { context } = await createContext();
+
+    await context.plugin(sessionPlugin, { storage: "memory" });
+
+    expect(context.get("piSession")?.manager.isPersisted()).toBe(false);
+  });
+
+  test("creates a JSONL session in the configured directory", async () => {
+    const { context } = await createContext();
+    const directory = await mkdtemp(join(tmpdir(), "pi-harness-sessions-"));
+
+    await context.plugin(sessionPlugin, { storage: "jsonl", directory });
+
+    expect(context.get("piSession")?.manager.isPersisted()).toBe(true);
+    expect(context.get("piSession")?.manager.getSessionDir()).toBe(directory);
+  });
+
+  test("keeps the default JSONL session under the configured agent directory", async () => {
+    const { context, agentDir } = await createContext();
+
+    await context.plugin(sessionPlugin, { storage: "jsonl" });
+
+    expect(context.get("piSession")?.manager.getSessionDir()).toBe(join(agentDir, "sessions"));
+  });
+
+  test("contributes Pi's core tools through a lifecycle-owned registry", async () => {
+    const { context } = await createContext();
+
+    await context.plugin(toolsPlugin, { names: ["read", "bash", "edit", "write"] });
+
+    expect(context.get("piTools")?.snapshot()).toEqual({ names: ["read", "bash", "edit", "write"], customTools: [] });
+  });
+
+  test("rejects tool contributions while runtime owns a snapshot and accepts them after release", () => {
+    const tools = new PiToolRegistry();
+    const lateTool = defineTool({
+      name: "late",
+      label: "Late",
+      description: "A tool registered after runtime startup.",
+      parameters: Type.Object({}),
+      execute() {
+        return Promise.resolve({ content: [{ type: "text", text: "late" }], details: undefined });
+      },
+    });
+
+    const lease = tools.acquire();
+    expect(lease.names).toEqual([]);
+    expect(lease.customTools).toEqual([]);
+    expect(() => tools.register(lateTool)).toThrow(/leased/);
+
+    lease.release();
+    expect(() => tools.register(lateTool)).not.toThrow();
+  });
+});

package/packages/core/test/stdio.test.ts

@@ -0,0 +1,87 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { fauxAssistantMessage } from "@earendil-works/pi-ai/providers/faux";
+import { afterEach, describe, expect, test } from "vitest";
+import { provideStdioContext, type PiHarnessStdio } from "../src/stdio.js";
+import stdioPlugin from "../src/plugins/stdio.js";
+import { createTestRuntimeContext } from "./runtime-fixture.js";
+
+const contexts: Context[] = [];
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(async (context) => context.fiber.dispose()));
+});
+
+function captureStdio(input: string): PiHarnessStdio & { output: string[]; errors: string[] } {
+  const output: string[] = [];
+  const errors: string[] = [];
+  return {
+    output,
+    errors,
+    readPrompt() {
+      return Promise.resolve(input);
+    },
+    writeOutput(text) {
+      output.push(text);
+    },
+    writeError(text) {
+      errors.push(text);
+    },
+  };
+}
+
+describe("stdio application plugin", () => {
+  test("reads one prompt and streams the assistant response", async () => {
+    const { context, faux } = await createTestRuntimeContext([fauxAssistantMessage("stdio response")]);
+    contexts.push(context);
+    const stdio = captureStdio("user prompt");
+    provideStdioContext(context, stdio);
+    await context.plugin(stdioPlugin);
+
+    const exitCode = await context.piApplication.run();
+
+    expect(exitCode).toBe(0);
+    expect(stdio.output.join("")).toBe("stdio response\n");
+    expect(stdio.errors).toEqual([]);
+    expect(faux.state.callCount).toBe(1);
+    expect(context.piRuntime.session.messages.some((message) => message.role === "user")).toBe(true);
+  });
+
+  test("returns a usage error without calling the model for an empty prompt", async () => {
+    const { context, faux } = await createTestRuntimeContext([fauxAssistantMessage("unused")]);
+    contexts.push(context);
+    const stdio = captureStdio("   ");
+    provideStdioContext(context, stdio);
+    await context.plugin(stdioPlugin);
+
+    const exitCode = await context.piApplication.run();
+
+    expect(exitCode).toBe(2);
+    expect(stdio.errors.join("")).toMatch(/prompt is empty/i);
+    expect(faux.state.callCount).toBe(0);
+  });
+
+  test("reports a settled provider error as a failed application run", async () => {
+    const { context } = await createTestRuntimeContext([fauxAssistantMessage("", { stopReason: "error", errorMessage: "provider failed" })]);
+    contexts.push(context);
+    const stdio = captureStdio("trigger error");
+    provideStdioContext(context, stdio);
+    await context.plugin(stdioPlugin);
+
+    const exitCode = await context.piApplication.run();
+
+    expect(exitCode).toBe(1);
+    expect(stdio.errors.join("")).toContain("provider failed");
+  });
+
+  test("reports non-error resource diagnostics instead of dropping them", async () => {
+    const { context } = await createTestRuntimeContext([]);
+    contexts.push(context);
+    (context.piResources.diagnostics as unknown as Array<{ type: "warning"; message: string }>).push({ type: "warning", message: "extension warning" });
+    const stdio = captureStdio("");
+    provideStdioContext(context, stdio);
+
+    await context.plugin(stdioPlugin);
+
+    expect(stdio.errors).toEqual(["Resource warning: extension warning\n"]);
+  });
+});

package/packages/core/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}

package/packages/host-webserver/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { Context } from "@deepseek-ai/cordis";
+export interface WebRoute {
+    readonly path: string;
+    readonly handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;
+}
+export interface WebServerConfig {
+    readonly host?: string;
+    readonly port?: number;
+}
+export interface WebServer {
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+    register(route: WebRoute): () => void;
+    registerFallback(handler: WebRoute["handler"]): () => void;
+    close(): Promise<void>;
+}
+declare module "@deepseek-ai/cordis" {
+    interface Context {
+        webServer: WebServer;
+    }
+}
+declare const _default: {
+    name: string;
+    apply(context: Context, config: WebServerConfig): Promise<void>;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map