nemo-fabric-adapters-pi 0.0.0 → 0.3.0-beta.2

package/README.md

@@ -1,9 +1,148 @@
-# nemo-fabric-adapters-pi
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 
-This `0.0.0` release is an inert registry bootstrap for the
-`nemo-fabric-adapters-pi` package name. It contains no runtime code and is not a
-supported NVIDIA NeMo Fabric adapter release.
+# NVIDIA NeMo Fabric Pi Adapter
 
-Supported releases are published from the
-[NVIDIA NeMo Fabric repository](https://github.com/NVIDIA/NeMo-Fabric) through
-npm trusted publishing.
+This package provides a Pi harness adapter for NVIDIA NeMo Fabric. It embeds the
+Pi SDK in the Node process of the adapter and maps one NeMo Fabric runtime to one
+in-memory Pi session.
+
+The adapter supports:
+
+- One explicit Pi-known model selected from the `default` role or the sole
+  configured role
+- Runtime API-key credentials named by `models.<role>.api_key_env`
+- Optional `models.<role>.base_url`
+- Optional replacement system instructions
+- Tool allow and block policy
+- NeMo Fabric custom tools loaded through normalized `tools.definitions`
+- Explicit normalized `skills.paths`
+- Explicit local `.ts` or `.js` extension files contained by the NeMo Fabric
+  workspace
+- Slash commands registered by those explicit extensions
+- Ordered plain-text invocations with a `{ "response": "..." }` terminal
+  output
+
+Ambient Pi settings, context files, packages, extensions, skills, prompts,
+themes, model files, credentials, and session files are disabled. Explicitly
+configured extensions are trusted code.
+
+## Install the Adapter
+
+Pi 0.84.x requires Node.js 22.19.0 or newer.
+
+### Install for Consumers
+
+Install the adapter in the project that owns the NeMo Fabric configuration,
+then install the compatible Pi SDK harness version selected by that project:
+
+```bash
+npm install nemo-fabric-adapters-pi
+npm install @earendil-works/pi-ai@^0.84.2 @earendil-works/pi-coding-agent@^0.84.2
+```
+
+The adapter declares the Pi packages as optional peers. Installing the adapter
+alone does not install a harness, and starting it without compatible Pi packages
+returns `pi_harness_unavailable`.
+
+### Install for Source Development
+
+For focused Pi development in the NeMo Fabric source tree, install the Pi
+adapter workspace and its pinned harness from the repository root:
+
+```bash
+just install-typescript-pi
+```
+
+To install and build all maintained TypeScript workspaces instead, run:
+
+```bash
+just build-typescript
+```
+
+The full build installs its own dependencies, so you do not need to run
+`just install-typescript-pi` first.
+
+## Configure the Adapter
+
+The npm package includes its adapter descriptor as `pi.fabric-adapter.json`.
+NeMo Fabric descriptor discovery is path-based. Point discovery at the installed
+descriptor and select the Pi adapter with the Python SDK:
+
+```python
+from nemo_fabric import DiscoveryConfig, HarnessConfig
+
+discovery = DiscoveryConfig(
+    local_paths=[
+        "./node_modules/nemo-fabric-adapters-pi/pi.fabric-adapter.json"
+    ]
+)
+harness = HarnessConfig(adapter_id="nvidia.fabric.pi")
+```
+
+For a source build, set `discovery.local_paths` to
+`adapters/typescript/pi/pi.fabric-adapter.json` instead.
+
+## Custom Tool Modules
+
+The adapter accepts custom tools with `kind: "module"`. The `ref` is a
+workspace-relative JavaScript or TypeScript file with an optional named export,
+for example `tools/review.ts#createTool`. Without a fragment, the adapter uses
+the default export.
+
+The export is called with `{ name, settings, workspace }` and must return a Pi
+`ToolDefinition` whose name matches the normalized `tools.definitions` key.
+Tool modules are trusted executable code. Their real paths must remain inside
+the NeMo Fabric workspace, and their names may not replace Pi built-in or
+extension tools. The following configuration registers a custom tool module:
+
+```json
+{
+  "tools": {
+    "definitions": {
+      "review_context": {
+        "kind": "module",
+        "ref": "tools/review-context.ts#createTool",
+        "settings": {"format": "brief"}
+      }
+    },
+    "enabled": ["read", "review_context"]
+  }
+}
+```
+
+## Run the Code-Review Example
+
+The maintained code-review example exercises the Pi adapter with an explicit
+NeMo Fabric skill and an example-specific tool policy. After building the
+TypeScript packages, inspect the plan from the repository root:
+
+```bash
+.venv/bin/python -m examples.code_review_agent --variant pi --plan
+```
+
+Refer to the
+[code-review example](../../../examples/code_review_agent/README.md) for the
+live NVIDIA-backed run command. Relay and MCP are not currently supported.
+
+## Dependency Rationale
+
+`@earendil-works/pi-coding-agent` provides the native Pi session, resources,
+skills, extensions, and tools. Using the SDK keeps these integration points in
+process; maintaining a second JSON-RPC translation was rejected for the bundled
+adapter. `@earendil-works/pi-ai` supplies Pi's model catalog and credential
+store, which the coding-agent SDK expects. Both packages are optional peer
+dependencies so deployments control the compatible harness version. Exact
+0.84.2 development dependencies keep repository builds and tests reproducible.
+
+`jiti` loads explicitly configured, trusted JavaScript and TypeScript tool
+modules. Native Node.js loading cannot execute TypeScript modules, while a
+custom transpiler would duplicate this focused loader. The adapter contract
+package supplies normalized types, and `nemo-fabric-adapters-common` supplies
+the shared lifecycle host; copying either surface into the Pi package would
+create divergent implementations.
+
+`typescript` and `@types/node` are exact-pinned build inputs and are absent from
+the published production dependency graph.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Process runner referenced by the adapter descriptor and npm binary. It
+// validates the Node.js host, then composes the shared lifecycle transport with
+// the Pi runtime while deferring SDK loading until startup.
+import { createRequire } from "node:module";
+import { serve } from "nemo-fabric-adapters-common";
+import { assertSupportedNodeVersion } from "./node-version.js";
+const manifest = createRequire(import.meta.url)("../package.json");
+assertSupportedNodeVersion(process.versions.node, manifest.engines?.node);
+await serve(async () => {
+    const [{ PiSdkSessionFactory }, { PiAdapterRuntime }] = await Promise.all([
+        import("./pi-sdk.js"),
+        import("./runtime.js"),
+    ]);
+    return new PiAdapterRuntime(new PiSdkSessionFactory());
+});

package/dist/node-version.d.ts

@@ -0,0 +1 @@
+export declare function assertSupportedNodeVersion(current: string, requirement: unknown): void;

package/dist/node-version.js

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+function parseVersion(value, label) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    if (match === null) {
+        throw new Error(`${label} must be a semantic version`);
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] !== undefined,
+    };
+}
+function isOlderThan(actual, minimum) {
+    for (const part of ["major", "minor", "patch"]) {
+        const actualPart = actual[part];
+        const minimumPart = minimum[part];
+        if (actualPart !== minimumPart) {
+            return actualPart < minimumPart;
+        }
+    }
+    return false;
+}
+export function assertSupportedNodeVersion(current, requirement) {
+    if (typeof requirement !== "string") {
+        throw new Error("The Pi package must declare a Node.js engine requirement");
+    }
+    const minimumMatch = /^>=(\d+\.\d+\.\d+)$/.exec(requirement);
+    if (minimumMatch?.[1] === undefined) {
+        throw new Error(`The Pi adapter cannot enforce Node.js engine requirement ${requirement}`);
+    }
+    const actual = parseVersion(current, "The current Node.js version");
+    const minimum = parseVersion(minimumMatch[1], "The minimum Node.js version");
+    if (actual.prerelease || isOlderThan(actual, minimum)) {
+        throw new Error(`The Pi adapter requires Node.js ${requirement}; current runtime is ${current}`);
+    }
+}

package/dist/pi-sdk.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentToolDefinition } from "nemo-fabric-adapter-contract";
+import { type AdapterStartInput } from "nemo-fabric-adapters-common";
+import type { PiSessionFactory, PiSessionHandle } from "./runtime.js";
+export declare function resolveCustomTools(workspace: string, definitions: Record<string, AgentToolDefinition>): Promise<ToolDefinition[]>;
+export declare class PiSdkSessionFactory implements PiSessionFactory {
+    create(input: AdapterStartInput): Promise<PiSessionHandle>;
+}

package/dist/pi-sdk.js

@@ -0,0 +1,466 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Pi SDK integration boundary. It translates normalized adapter configuration
+// into a controlled in-memory Pi session, including model credentials, skills,
+// extensions, custom tools, and workspace containment.
+import { realpath, stat } from "node:fs/promises";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createJiti } from "jiti/static";
+import { LifecycleError } from "nemo-fabric-adapters-common";
+const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"]);
+const TOOL_MODULE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]);
+const PI_HARNESS_INSTALL_COMMAND = "npm install @earendil-works/pi-ai@^0.84.2 @earendil-works/pi-coding-agent@^0.84.2";
+function isMissingModuleError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error.code === "ERR_MODULE_NOT_FOUND" || error.code === "MODULE_NOT_FOUND"));
+}
+async function loadPiSdk() {
+    let ai;
+    let codingAgent;
+    try {
+        [ai, codingAgent] = await Promise.all([
+            import("@earendil-works/pi-ai"),
+            import("@earendil-works/pi-coding-agent"),
+        ]);
+    }
+    catch (error) {
+        if (isMissingModuleError(error)) {
+            throw new LifecycleError("pi_harness_unavailable", `The Pi SDK harness is not installed. Install a compatible harness with: ${PI_HARNESS_INSTALL_COMMAND}`);
+        }
+        throw new LifecycleError("pi_harness_load_failed", "The installed Pi SDK harness could not be loaded");
+    }
+    if (typeof ai.InMemoryCredentialStore !== "function" ||
+        typeof codingAgent.createAgentSession !== "function" ||
+        typeof codingAgent.DefaultResourceLoader !== "function" ||
+        typeof codingAgent.ModelRuntime !== "function" ||
+        typeof codingAgent.SessionManager !== "function" ||
+        typeof codingAgent.SettingsManager !== "function") {
+        throw new LifecycleError("pi_harness_incompatible", "The installed Pi SDK harness does not expose the APIs required by this adapter");
+    }
+    return {
+        InMemoryCredentialStore: ai.InMemoryCredentialStore,
+        createAgentSession: codingAgent.createAgentSession,
+        DefaultResourceLoader: codingAgent.DefaultResourceLoader,
+        ModelRuntime: codingAgent.ModelRuntime,
+        SessionManager: codingAgent.SessionManager,
+        SettingsManager: codingAgent.SettingsManager,
+    };
+}
+function selectModel(config) {
+    const entries = Object.entries(config.models ?? {});
+    if (entries.length === 0) {
+        throw new LifecycleError("pi_model_required", "The Pi adapter requires one configured model");
+    }
+    const selected = config.models?.default ?? (entries.length === 1 ? entries[0]?.[1] : undefined);
+    if (selected === undefined) {
+        throw new LifecycleError("pi_model_ambiguous", "Configure a default model role when the Pi adapter receives multiple models");
+    }
+    return selected;
+}
+function harnessSettings(config) {
+    const raw = config.harness?.settings;
+    const extensions = raw?.extensions;
+    if (extensions === undefined) {
+        return { extensions: [] };
+    }
+    if (!Array.isArray(extensions)) {
+        throw new LifecycleError("pi_invalid_settings", "Pi extension settings do not match the adapter schema");
+    }
+    const values = [];
+    for (const entry of extensions) {
+        if (typeof entry !== "string") {
+            throw new LifecycleError("pi_invalid_settings", "Pi extension settings do not match the adapter schema");
+        }
+        values.push(entry);
+    }
+    return { extensions: values };
+}
+function containedBy(root, candidate) {
+    const path = relative(root, candidate);
+    return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function resolveToolModule(workspace, reference) {
+    const match = /^(?<path>[^#]+?)(?:#(?<export>[A-Za-z_$][\w$]*))?$/.exec(reference);
+    const configuredPath = match?.groups?.path;
+    if (configuredPath === undefined || isAbsolute(configuredPath)) {
+        throw new LifecycleError("pi_tool_ref_invalid", "Pi tool module references must use a workspace-relative path with an optional export fragment");
+    }
+    let candidate;
+    try {
+        candidate = await realpath(resolve(workspace, configuredPath));
+    }
+    catch {
+        throw new LifecycleError("pi_tool_module_not_found", "A configured Pi tool module does not exist");
+    }
+    if (!containedBy(workspace, candidate)) {
+        throw new LifecycleError("pi_tool_module_outside_workspace", "Pi tool modules must be contained by the workspace");
+    }
+    if (!(await stat(candidate)).isFile() || !TOOL_MODULE_EXTENSIONS.has(extname(candidate))) {
+        throw new LifecycleError("pi_tool_module_invalid", "Pi tool modules must be JavaScript or TypeScript files");
+    }
+    return { path: candidate, exportName: match?.groups?.export ?? "default" };
+}
+function validateToolDefinition(name, value) {
+    if (!isRecord(value) ||
+        value.name !== name ||
+        typeof value.label !== "string" ||
+        value.label.length === 0 ||
+        typeof value.description !== "string" ||
+        value.description.length === 0 ||
+        !isRecord(value.parameters) ||
+        typeof value.execute !== "function") {
+        throw new LifecycleError("pi_tool_factory_invalid", "A Pi tool factory returned an invalid tool definition or a mismatched tool name", { metadata: { tool: name } });
+    }
+    return value;
+}
+export async function resolveCustomTools(workspace, definitions) {
+    const jiti = createJiti(import.meta.url, { interopDefault: false });
+    const tools = [];
+    for (const [name, definition] of Object.entries(definitions)) {
+        if (PI_BUILTIN_TOOL_NAMES.has(name)) {
+            throw new LifecycleError("pi_tool_collision", "A Fabric tool definition collides with a Pi built-in tool", {
+                metadata: { tool: name },
+            });
+        }
+        if (definition.kind !== "module") {
+            throw new LifecycleError("pi_tool_kind_unsupported", "Pi supports only module tool definitions");
+        }
+        const moduleReference = await resolveToolModule(workspace, definition.ref);
+        let loaded;
+        try {
+            loaded = await jiti.import(moduleReference.path);
+        }
+        catch {
+            throw new LifecycleError("pi_tool_module_load_failed", "A configured Pi tool module could not be loaded", {
+                metadata: { tool: name },
+            });
+        }
+        const factory = isRecord(loaded) ? loaded[moduleReference.exportName] : undefined;
+        if (typeof factory !== "function") {
+            throw new LifecycleError("pi_tool_factory_missing", "A configured Pi tool module export is not a factory", {
+                metadata: { tool: name },
+            });
+        }
+        let tool;
+        try {
+            tool = await factory({
+                name,
+                settings: definition.settings ?? {},
+                workspace,
+            });
+        }
+        catch {
+            throw new LifecycleError("pi_tool_factory_failed", "A configured Pi tool factory failed", {
+                metadata: { tool: name },
+            });
+        }
+        tools.push(validateToolDefinition(name, tool));
+    }
+    return tools;
+}
+function extensionToolNames(resourceLoader) {
+    return resourceLoader
+        .getExtensions()
+        .extensions.flatMap((extension) => Array.from(extension.tools.keys()));
+}
+function rejectToolCollisions(customTools, configuredExtensionTools) {
+    const customNames = new Set(customTools.map((tool) => tool.name));
+    const seenExtensionNames = new Set();
+    for (const name of configuredExtensionTools) {
+        if (PI_BUILTIN_TOOL_NAMES.has(name) || customNames.has(name) || seenExtensionNames.has(name)) {
+            throw new LifecycleError("pi_tool_collision", "Two configured Pi tool sources use the same tool name", {
+                metadata: { tool: name },
+            });
+        }
+        seenExtensionNames.add(name);
+    }
+}
+async function resolveExtensionPaths(workspace, configured) {
+    const resolved = [];
+    for (const entry of configured) {
+        if (isAbsolute(entry)) {
+            throw new LifecycleError("pi_extension_outside_workspace", "Pi extension paths must be workspace-relative");
+        }
+        let candidate;
+        try {
+            candidate = await realpath(resolve(workspace, entry));
+        }
+        catch {
+            throw new LifecycleError("pi_extension_not_found", "A configured Pi extension path does not exist");
+        }
+        if (!containedBy(workspace, candidate)) {
+            throw new LifecycleError("pi_extension_outside_workspace", "Pi extension path resolves outside the workspace");
+        }
+        const info = await stat(candidate);
+        if (!info.isFile() || (!candidate.endsWith(".ts") && !candidate.endsWith(".js"))) {
+            throw new LifecycleError("pi_unsupported_extension", "Pi extensions must be .ts or .js files");
+        }
+        resolved.push(candidate);
+    }
+    return resolved;
+}
+async function resolveSkillPaths(baseDir, configured) {
+    const resolved = [];
+    for (const entry of configured) {
+        let candidate;
+        try {
+            candidate = await realpath(resolve(baseDir, entry));
+        }
+        catch {
+            throw new LifecycleError("pi_skill_not_found", "A configured NeMo Fabric skill path does not exist");
+        }
+        let info;
+        try {
+            info = await stat(candidate);
+        }
+        catch {
+            throw new LifecycleError("pi_skill_not_found", "A configured NeMo Fabric skill path does not exist");
+        }
+        if (!info.isDirectory()) {
+            throw new LifecycleError("pi_skill_invalid", "NeMo Fabric skill paths must be directories");
+        }
+        try {
+            if (!(await stat(join(candidate, "SKILL.md"))).isFile()) {
+                throw new Error("not a file");
+            }
+        }
+        catch {
+            throw new LifecycleError("pi_skill_invalid", "NeMo Fabric skill directories must contain a SKILL.md file");
+        }
+        resolved.push(candidate);
+    }
+    return resolved;
+}
+function credentialValue(input, name) {
+    return input.runtimeContext.environment.env?.[name] ?? process.env[name];
+}
+function promptText(message) {
+    if (!Array.isArray(message.content)) {
+        return "";
+    }
+    return message.content
+        .filter((block) => {
+        return (typeof block === "object" &&
+            block !== null &&
+            "type" in block &&
+            block.type === "text" &&
+            "text" in block &&
+            typeof block.text === "string");
+    })
+        .map((block) => block.text)
+        .join("");
+}
+function unsupportedSessionAction(name) {
+    throw new LifecycleError("pi_unsupported_session_operation", `Pi session operation ${name} is not supported`);
+}
+class PiSdkSessionHandle {
+    session;
+    state;
+    stopped = false;
+    constructor(session, state) {
+        this.session = session;
+        this.state = state;
+    }
+    async prompt(text) {
+        let accepted = false;
+        let finalAssistant;
+        const unsubscribe = this.session.subscribe((event) => {
+            if (event.type === "message_end" && event.message.role === "assistant") {
+                finalAssistant = event.message;
+            }
+        });
+        try {
+            await this.session.prompt(text, {
+                expandPromptTemplates: true,
+                source: "interactive",
+                preflightResult: (result) => {
+                    accepted = result;
+                },
+            });
+        }
+        finally {
+            unsubscribe();
+        }
+        return {
+            accepted,
+            text: finalAssistant === undefined ? undefined : promptText(finalAssistant),
+            stopReason: finalAssistant?.stopReason,
+            errorMessage: finalAssistant?.errorMessage,
+            shutdownRequested: this.state.shutdownRequested,
+        };
+    }
+    async stop() {
+        if (this.stopped) {
+            return;
+        }
+        this.stopped = true;
+        let failure;
+        try {
+            await this.session.abort();
+        }
+        catch (error) {
+            failure = error;
+        }
+        try {
+            await this.session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+        }
+        catch (error) {
+            failure ??= error;
+        }
+        try {
+            this.session.dispose();
+        }
+        catch (error) {
+            failure ??= error;
+        }
+        if (failure !== undefined) {
+            throw failure;
+        }
+    }
+}
+export class PiSdkSessionFactory {
+    async create(input) {
+        const systemInstruction = input.config.instructions?.system;
+        if (systemInstruction?.mode === "append") {
+            throw new LifecycleError("unsupported_system_instruction_mode", "Pi does not support instructions.system.mode='append'; supported modes: replace", {
+                metadata: {
+                    field: "instructions.system.mode",
+                    mode: systemInstruction.mode,
+                    supported_modes: ["replace"],
+                },
+            });
+        }
+        const pi = await loadPiSdk();
+        let workspace;
+        try {
+            workspace = await realpath(resolve(input.runtimeContext.environment.workspace ?? input.baseDir));
+            if (!(await stat(workspace)).isDirectory()) {
+                throw new Error("not a directory");
+            }
+        }
+        catch {
+            throw new LifecycleError("pi_workspace_invalid", "The Fabric runtime workspace must be a directory");
+        }
+        const selected = selectModel(input.config);
+        const apiKeyEnv = selected.api_key_env;
+        if (apiKeyEnv === undefined || apiKeyEnv === null || apiKeyEnv.length === 0) {
+            throw new LifecycleError("pi_api_key_env_required", "The selected Pi model requires api_key_env");
+        }
+        const apiKey = credentialValue(input, apiKeyEnv);
+        if (apiKey === undefined || apiKey.length === 0) {
+            throw new LifecycleError("pi_credential_missing", `Credential environment variable ${apiKeyEnv} is not set`);
+        }
+        const settings = pi.SettingsManager.inMemory({}, { projectTrusted: false });
+        const extensionPaths = await resolveExtensionPaths(workspace, harnessSettings(input.config).extensions);
+        const skillPaths = await resolveSkillPaths(input.baseDir, input.config.skills?.paths ?? []);
+        const customTools = await resolveCustomTools(workspace, input.config.tools?.definitions ?? {});
+        const agentDir = join(workspace, ".fabric-pi");
+        const resourceLoader = new pi.DefaultResourceLoader({
+            cwd: workspace,
+            agentDir,
+            settingsManager: settings,
+            additionalExtensionPaths: extensionPaths,
+            additionalSkillPaths: skillPaths,
+            noExtensions: true,
+            noSkills: true,
+            noPromptTemplates: true,
+            noThemes: true,
+            noContextFiles: true,
+            systemPrompt: systemInstruction?.content,
+        });
+        await resourceLoader.reload();
+        const extensionErrors = resourceLoader.getExtensions().errors;
+        if (extensionErrors.length > 0) {
+            throw new LifecycleError("pi_extension_load_failed", "One or more configured Pi extensions failed to load", {
+                metadata: { count: extensionErrors.length },
+            });
+        }
+        rejectToolCollisions(customTools, extensionToolNames(resourceLoader));
+        const skillDiagnostics = resourceLoader.getSkills().diagnostics;
+        const blockingSkillDiagnostics = skillDiagnostics.filter((diagnostic) => diagnostic.type === "error" || diagnostic.type === "collision");
+        for (const diagnostic of skillDiagnostics.filter((entry) => entry.type === "warning")) {
+            process.stderr.write(`Pi skill warning: ${diagnostic.message}\n`);
+        }
+        if (blockingSkillDiagnostics.length > 0) {
+            throw new LifecycleError("pi_skill_load_failed", "One or more configured NeMo Fabric skills failed to load", {
+                metadata: { count: blockingSkillDiagnostics.length },
+            });
+        }
+        const credentials = new pi.InMemoryCredentialStore();
+        const modelRuntime = await pi.ModelRuntime.create({
+            credentials,
+            modelsPath: null,
+            allowModelNetwork: false,
+            refreshOnCreate: false,
+        });
+        await modelRuntime.setRuntimeApiKey(selected.provider, apiKey);
+        const catalogModel = modelRuntime.getModel(selected.provider, selected.model);
+        if (catalogModel === undefined) {
+            throw new LifecycleError("pi_model_unknown", "The selected provider and model are not present in Pi's catalog");
+        }
+        const model = selected.base_url ? { ...catalogModel, baseUrl: selected.base_url } : catalogModel;
+        const enabled = input.config.tools?.enabled;
+        const blocked = input.config.tools?.blocked ?? [];
+        const state = { shutdownRequested: false };
+        const { session } = await pi.createAgentSession({
+            cwd: workspace,
+            agentDir,
+            model,
+            modelRuntime,
+            resourceLoader,
+            sessionManager: pi.SessionManager.inMemory(workspace),
+            settingsManager: settings,
+            customTools,
+            tools: enabled === null ? undefined : enabled,
+            excludeTools: blocked,
+        });
+        const handle = new PiSdkSessionHandle(session, state);
+        try {
+            const blockedNames = new Set(blocked);
+            const availableNames = new Set(session.getAllTools().map((tool) => tool.name));
+            const missing = (enabled ?? []).filter((name) => !blockedNames.has(name) && !availableNames.has(name));
+            if (missing.length > 0) {
+                throw new LifecycleError("pi_tool_missing", "One or more enabled tools are not registered", {
+                    metadata: { tools: missing },
+                });
+            }
+            const commandContextActions = {
+                waitForIdle: () => session.waitForIdle(),
+                newSession: async () => unsupportedSessionAction("newSession"),
+                fork: async () => unsupportedSessionAction("fork"),
+                navigateTree: async () => unsupportedSessionAction("navigateTree"),
+                switchSession: async () => unsupportedSessionAction("switchSession"),
+                reload: async () => unsupportedSessionAction("reload"),
+            };
+            await session.bindExtensions({
+                mode: "print",
+                commandContextActions,
+                abortHandler: () => {
+                    void session.abort();
+                },
+                shutdownHandler: () => {
+                    state.shutdownRequested = true;
+                    void session.abort();
+                },
+                onError: () => {
+                    process.stderr.write("Pi extension handler failed\n");
+                },
+            });
+            return handle;
+        }
+        catch (error) {
+            try {
+                await handle.stop();
+            }
+            catch {
+                process.stderr.write("Pi session cleanup failed after adapter startup error\n");
+            }
+            throw error;
+        }
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,26 @@
+import type { AgentRunRequest, AgentRunResult, RuntimeContext } from "nemo-fabric-adapter-contract";
+import { type AdapterRuntime, type AdapterStartInput } from "nemo-fabric-adapters-common";
+export type PiStopReason = "stop" | "length" | "toolUse" | "error" | "aborted" | string;
+export interface PiPromptOutcome {
+    accepted: boolean;
+    text?: string;
+    stopReason?: PiStopReason;
+    errorMessage?: string;
+    shutdownRequested?: boolean;
+}
+export interface PiSessionHandle {
+    prompt(text: string): Promise<PiPromptOutcome>;
+    stop(): Promise<void>;
+}
+export interface PiSessionFactory {
+    create(input: AdapterStartInput): Promise<PiSessionHandle>;
+}
+export declare class PiAdapterRuntime implements AdapterRuntime {
+    private readonly factory;
+    private session?;
+    private unusable;
+    constructor(factory: PiSessionFactory);
+    start(input: AdapterStartInput): Promise<void>;
+    invoke(request: AgentRunRequest, _context: RuntimeContext): Promise<AgentRunResult>;
+    stop(): Promise<void>;
+}

package/dist/runtime.js

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { LifecycleError } from "nemo-fabric-adapters-common";
+function failed(code, message) {
+    return {
+        status: "failed",
+        output: null,
+        error: { code, message, retryable: false },
+    };
+}
+export class PiAdapterRuntime {
+    factory;
+    session;
+    unusable = false;
+    constructor(factory) {
+        this.factory = factory;
+    }
+    async start(input) {
+        if (this.session !== undefined) {
+            throw new LifecycleError("pi_already_started", "Pi adapter runtime is already started");
+        }
+        this.session = await this.factory.create(input);
+        this.unusable = false;
+    }
+    async invoke(request, _context) {
+        if (this.session === undefined) {
+            throw new LifecycleError("pi_not_started", "Pi adapter runtime is not started");
+        }
+        if (this.unusable) {
+            throw new LifecycleError("pi_runtime_unusable", "Pi adapter runtime cannot accept another invocation");
+        }
+        if (typeof request.input !== "string") {
+            return failed("pi_unsupported_input", "The Pi adapter accepts only plain-text input");
+        }
+        const outcome = await this.session.prompt(request.input);
+        if (!outcome.accepted) {
+            return failed("pi_prompt_rejected", "Pi rejected the prompt before starting an agent run");
+        }
+        if (outcome.shutdownRequested || outcome.stopReason === "aborted") {
+            if (outcome.shutdownRequested) {
+                this.unusable = true;
+            }
+            return {
+                status: "cancelled",
+                output: null,
+                error: {
+                    code: outcome.shutdownRequested ? "pi_extension_shutdown" : "pi_aborted",
+                    message: outcome.shutdownRequested
+                        ? "A Pi extension requested adapter shutdown"
+                        : "The Pi invocation was aborted",
+                    retryable: false,
+                },
+            };
+        }
+        if (outcome.stopReason === "error") {
+            return failed("pi_model_error", outcome.errorMessage || "The Pi model invocation failed");
+        }
+        if (outcome.text === undefined || outcome.text.length === 0) {
+            return failed("pi_no_assistant_response", "Pi completed without a final assistant text response");
+        }
+        return { status: "succeeded", output: { response: outcome.text } };
+    }
+    async stop() {
+        const session = this.session;
+        this.session = undefined;
+        this.unusable = false;
+        if (session !== undefined) {
+            await session.stop();
+        }
+    }
+}

package/package.json

@@ -1,14 +1,67 @@
 {
   "name": "nemo-fabric-adapters-pi",
-  "version": "0.0.0",
-  "description": "Registry bootstrap for the NVIDIA NeMo Fabric Pi TypeScript adapter package.",
+  "version": "0.3.0-beta.2",
+  "description": "Pi SDK harness adapter for NVIDIA NeMo Fabric.",
   "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./descriptor": "./pi.fabric-adapter.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "nemo-fabric-adapters-pi": "dist/cli.js"
+  },
   "files": [
+    "dist",
+    "pi.fabric-adapter.json",
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "pack:check": "npm run build && node ../scripts/check-package.mjs",
+    "prepack": "npm run build",
+    "test": "npm run clean && npm run build && node --test test/*.test.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NVIDIA/NeMo-Fabric.git",
+    "directory": "adapters/typescript/pi"
+  },
+  "bugs": {
+    "url": "https://github.com/NVIDIA/NeMo-Fabric/issues"
+  },
+  "homepage": "https://github.com/NVIDIA/NeMo-Fabric/tree/main/adapters/typescript/pi#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "jiti": "2.7.0",
+    "nemo-fabric-adapter-contract": "0.3.0-beta.2",
+    "nemo-fabric-adapters-common": "0.3.0-beta.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@types/node": "24.12.4",
+    "typescript": "5.9.3"
   }
 }

package/pi.fabric-adapter.json

@@ -0,0 +1,70 @@
+{
+  "contract_version": "fabric.adapter/v1alpha2",
+  "adapter_id": "nvidia.fabric.pi",
+  "adapter_kind": "process",
+  "runner": {
+    "command": "node",
+    "script": "dist/cli.js"
+  },
+  "requirements": {
+    "binaries": ["node"]
+  },
+  "config": {
+    "accepts": [
+      "models",
+      "models.base_url",
+      "instructions.system",
+      "tools.definitions",
+      "tools.enabled",
+      "tools.blocked",
+      "skills"
+    ],
+    "system_instruction_modes": ["replace"]
+  },
+  "settings_schema": {
+    "type": "object",
+    "properties": {
+      "extensions": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        },
+        "uniqueItems": true
+      }
+    },
+    "additionalProperties": false
+  },
+  "model_schema": {
+    "type": "object",
+    "properties": {
+      "provider": {"type": "string", "minLength": 1},
+      "model": {"type": "string", "minLength": 1},
+      "api_key_env": {"type": "string", "minLength": 1},
+      "base_url": {"type": ["string", "null"], "format": "uri"}
+    },
+    "required": ["provider", "model", "api_key_env"],
+    "additionalProperties": false
+  },
+  "tool_definition_schema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "kind": {"const": "module"},
+      "ref": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^#]+(?:#[A-Za-z_$][A-Za-z0-9_$]*)?$"
+      },
+      "settings": {"type": "object"}
+    },
+    "required": ["kind", "ref"],
+    "additionalProperties": false
+  },
+  "capabilities": {
+    "streaming": false,
+    "cancellation": false,
+    "updates": false,
+    "service": false
+  }
+}