@tonbo/cli 0.0.5 → 0.0.6

package/README.md

@@ -11,6 +11,7 @@ The V1 CLI deploys a PI-based Agent directly from a local directory without requ
 
 ```console
 tonbo init
+? Agent shape: [1] PI project  [2] PI Package project  [3] PI SDK app [1]:
 ? Inference model [claude-sonnet-4-5]:
 Created .tonbo.
 Next: tonbo project create <slug>
@@ -21,15 +22,14 @@ The generated `.tonbo` is TOML:
 ```toml
 version = 1
 
-[execution]
-mode = "managed"
+[agent]
 runtime = "pi"
 
+[agent.driver]
+kind = "native"
+
 [inference]
 model = "claude-sonnet-4-5"
-
-[session_capture]
-adapter = "pi-jsonl-v3"
 ```
 
 For automation, use `tonbo init --model <model>`; an existing declaration requires interactive confirmation or `--force`. Then authenticate, bind the directory and deploy its current contents:
@@ -63,9 +63,61 @@ ssh my-project@tonbo.sh
 
 The SSH username selects the globally unique Project; the signed public key identifies the Tonbo user and is checked against Project membership and IAM at connection time. The shell and HTTP turns may coexist on the singleton runtime, allowing the shell to observe the Agent while it works. Session writer fencing protects durable conversation history; ordinary workspace files retain Linux process concurrency semantics.
 
-The platform injects scoped inference access and the managed PI runtime writes the declared session format through the session-aware filesystem. Do not put a model-provider API key or a Tonbo credential in `.tonbo`.
+The platform injects scoped inference access and owns PI Session capture. Do not put a model-provider API key or a Tonbo credential in `.tonbo`.
+
+Deploy snapshots regular files under `.tonbo`, excluding `.git`, `node_modules`, PI package caches, local environment files and patterns in `.tonboignore`. Equal contents produce the same revision. Coding tools start in the persistent Artifacts workspace, while `AGENTS.md` and trusted `.pi` extensions, skills, prompts and settings load from the uploaded revision.
+
+## Supported PI project shapes
+
+### 1. Project-local Agent
+
+Keep the normal PI project layout. Tonbo runs the same `AGENTS.md`, `.pi/APPEND_SYSTEM.md`, `.pi/settings.json`, `.pi/extensions`, `.pi/skills` and `.pi/prompts` that local `pi` loads:
+
+```console
+pi
+tonbo init
+tonbo project create my-agent
+tonbo deploy
+tonbo run "Start the task."
+```
+
+### 2. PI Package project
+
+Use PI's project-local package declaration as the single source of truth. Install an immutable package reference locally, verify it with PI, and deploy the project; Tonbo excludes `.pi/npm` and `.pi/git` caches and restores packages inside the isolated runtime:
+
+```console
+pi install -l npm:@acme/my-pi-agent@1.2.3
+pi
+tonbo init
+tonbo deploy
+```
+
+Remote npm packages must use an exact version. Git packages must use a full 40-character commit, for example `git:github.com/acme/my-pi-agent@0123456789abcdef0123456789abcdef01234567`. Movable tags, branches, ranges and `latest` fail deployment.
+
+### 3. PI SDK app
+
+Choose `PI SDK app` in `tonbo init`, or declare a command driver directly:
+
+```toml
+version = 1
+
+[agent]
+runtime = "pi"
+secrets = ["GITHUB_TOKEN"]
+
+[agent.driver]
+kind = "command"
+protocol = "pi-rpc-v1"
+command = ["node", "dist/agent.mjs"]
+
+[build]
+command = ["npm", "run", "build"]
+
+[inference]
+model = "claude-sonnet-4-5"
+```
 
-Deploy snapshots regular files under `.tonbo`, excluding `.git`, `node_modules`, local environment files and patterns in `.tonboignore`. Equal contents produce the same revision. Coding tools start in the persistent Artifacts workspace, while `.pi` extensions, skills and prompts load from the uploaded revision.
+`tonbo deploy` runs the build command before creating the source snapshot. The entrypoint must keep stdout exclusively for PI RPC and send logs to stderr. It receives `PI_CODING_AGENT_MODULE`, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, `TONBO_PI_SESSION_FILE`, `TONBO_PI_SESSION_ID`, `TONBO_PI_PROVIDER`, `TONBO_PI_MODEL` and `TONBO_PI_RPC_PROTOCOL`. Load the platform PI SDK from `PI_CODING_AGENT_MODULE`, open `TONBO_PI_SESSION_FILE`, create an `AgentSessionRuntime`, and pass it to `runRpcMode()`. This lets the app customize tools and runtime services without forking PI while preserving Tonbo's durable Session and Turn protocol.
 
 For a non-interactive invocation, provide a current Tonbo CLI OAuth access token and an explicit Project:
 

package/dist/src/app.js

@@ -47,6 +47,9 @@ export function createProgram(dependencies = createDependencies) {
         .command("init")
         .description("interactively create a Tonbo Agent declaration in this directory")
         .option("--model <model>", "inference model")
+        .option("--driver <driver>", "PI driver: native or command")
+        .option("--agent-entry <file>", "Node entry file for the command driver")
+        .option("--build-command <argv...>", "build command argv for the command driver")
         .option("--force", `replace an existing ${DECLARATION_FILENAME}`)
         .action(async (options) => initCommand(dependencies(program.opts().json), options));
     program

package/dist/src/build.d.ts

@@ -0,0 +1 @@
+export declare function runBuildCommand(root: string, command: string[]): Promise<void>;

package/dist/src/build.js

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+export async function runBuildCommand(root, command) {
+    if (command.length === 0)
+        throw new Error("Build command must not be empty.");
+    await new Promise((resolve, reject) => {
+        const child = spawn(command[0], command.slice(1), {
+            cwd: root,
+            env: process.env,
+            // Command output is progress, not the CLI result. Keep stdout available
+            // for the single JSON document emitted by `tonbo --json deploy`.
+            stdio: ["inherit", process.stderr, process.stderr],
+        });
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`Build command failed${signal ? ` with signal ${signal}` : ` with status ${code}`}.`));
+        });
+    });
+}

package/dist/src/commands.d.ts

@@ -23,6 +23,9 @@ export declare function resolveProject(deps: CommandDependencies, selector?: str
 }>;
 export declare function selectProject(projects: ProjectSummary[], selector: string): ProjectSummary;
 export declare function initCommand(deps: CommandDependencies, options: {
+    agentEntry?: string;
+    buildCommand?: string[];
+    driver?: "native" | "command";
     force?: boolean;
     model?: string;
 }): Promise<void>;

package/dist/src/commands.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { runBuildCommand } from "./build.js";
 import { buildRevision, createDeclaration, declarationExists, DECLARATION_FILENAME, DEFAULT_INFERENCE_MODEL, loadDeclaration, saveDeclaration, } from "./declaration.js";
 import { buildSourceBundle, findDeclarationRoot } from "./source.js";
 import { readSshPublicKey } from "./ssh-key.js";
@@ -53,15 +54,45 @@ export async function initCommand(deps, options) {
         }
         overwrite = true;
     }
+    let driver = options.driver;
+    if (driver !== undefined && driver !== "native" && driver !== "command") {
+        throw new Error("--driver must be native or command.");
+    }
+    let shape = driver === "command" ? "sdk" : "project";
+    if (!driver && deps.interactive()) {
+        const answer = (await deps.prompt("Agent shape: [1] PI project  [2] PI Package project  [3] PI SDK app [1]: ")).trim();
+        if (!["", "1", "2", "3"].includes(answer)) {
+            throw new Error("Agent shape must be 1, 2, or 3.");
+        }
+        shape = answer === "2" ? "package" : answer === "3" ? "sdk" : "project";
+        driver = shape === "sdk" ? "command" : "native";
+    }
+    driver ||= "native";
+    if (driver === "native" && (options.agentEntry || options.buildCommand)) {
+        throw new Error("--agent-entry and --build-command require --driver command.");
+    }
+    let entry = options.agentEntry?.trim();
+    if (driver === "command" && !entry && deps.interactive()) {
+        entry = (await deps.prompt("PI SDK entry file [dist/agent.mjs]: ")).trim();
+    }
+    entry ||= "dist/agent.mjs";
     let model = options.model?.trim();
     if (!model && deps.interactive()) {
         model = (await deps.prompt(`Inference model [${DEFAULT_INFERENCE_MODEL}]: `)).trim();
     }
     model ||= DEFAULT_INFERENCE_MODEL;
-    const declaration = createDeclaration(model);
+    const buildCommand = driver === "command" ? (options.buildCommand ?? ["npm", "run", "build"]) : undefined;
+    const declaration = createDeclaration(model, driver === "native"
+        ? { kind: "native" }
+        : { kind: "command", protocol: "pi-rpc-v1", command: ["node", entry] }, buildCommand);
     await saveDeclaration(root, declaration, overwrite);
+    const shapeHint = shape === "package"
+        ? "\nPI packages stay in .pi/settings.json; use exact npm versions or Git commits."
+        : shape === "sdk"
+            ? `\nBuild: ${buildCommand?.join(" ")}\nEntrypoint: node ${entry}`
+            : "";
     deps.output({
-        message: `${exists ? "Updated" : "Created"} ${DECLARATION_FILENAME}.\nNext: tonbo project create <slug>`,
+        message: `${exists ? "Updated" : "Created"} ${DECLARATION_FILENAME}.${shapeHint}\nNext: tonbo project create <slug>`,
         declaration,
         path: path.join(root, DECLARATION_FILENAME),
     });
@@ -151,6 +182,8 @@ export async function projectCreateCommand(deps, slug, name) {
 export async function deployCommand(deps, selector) {
     const root = await findDeclarationRoot(deps.cwd());
     const declaration = await loadDeclaration(root);
+    if (declaration.build)
+        await runBuildCommand(root, declaration.build.command);
     const source = await buildSourceBundle(root);
     const oauthToken = await deps.auth.accessToken();
     let binding = await deps.config.getBinding(root);

package/dist/src/contracts.js

@@ -1,8 +1,9 @@
 import { Ajv2020 } from "ajv/dist/2020.js";
-import { declarationSchema, kubernetesProfilesSchema, projectServiceSchema, revisionSchema, } from "./generated/contracts.js";
+import { declarationSchema, kubernetesProfilesSchema, piAgentSchema, projectServiceSchema, revisionSchema, } from "./generated/contracts.js";
 const ajv = new Ajv2020({ allErrors: true, useDefaults: true });
 ajv.addKeyword({ keyword: "x-tonbo-profiles" });
 ajv.addSchema(kubernetesProfilesSchema);
+ajv.addSchema(piAgentSchema);
 ajv.addSchema(projectServiceSchema);
 const validateDeclaration = ajv.compile(declarationSchema);
 const validateRevision = ajv.compile(revisionSchema);

package/dist/src/declaration.d.ts

@@ -2,7 +2,7 @@ import { parseDeclaration } from "./contracts.js";
 import type { ManagedRevisionSpec, SourceBundle, TonboDeclaration } from "./types.js";
 export declare const DECLARATION_FILENAME = ".tonbo";
 export declare const DEFAULT_INFERENCE_MODEL = "claude-sonnet-4-5";
-export declare function createDeclaration(model?: string): TonboDeclaration;
+export declare function createDeclaration(model?: string, driver?: TonboDeclaration["agent"]["driver"], buildCommand?: string[]): TonboDeclaration;
 export declare function renderDeclaration(declaration: TonboDeclaration): string;
 export declare function declarationExists(root: string): Promise<boolean>;
 export declare function saveDeclaration(root: string, declaration: TonboDeclaration, overwrite: boolean): Promise<void>;

package/dist/src/declaration.js

@@ -5,12 +5,12 @@ import { parse, stringify } from "smol-toml";
 import { assertManagedRevision, parseDeclaration } from "./contracts.js";
 export const DECLARATION_FILENAME = ".tonbo";
 export const DEFAULT_INFERENCE_MODEL = "claude-sonnet-4-5";
-export function createDeclaration(model = DEFAULT_INFERENCE_MODEL) {
+export function createDeclaration(model = DEFAULT_INFERENCE_MODEL, driver = { kind: "native" }, buildCommand) {
     return parseDeclaration({
         version: 1,
-        execution: { mode: "managed", runtime: "pi" },
+        agent: { runtime: "pi", driver },
         inference: { model: model.trim() },
-        session_capture: { adapter: "pi-jsonl-v3" },
+        ...(buildCommand ? { build: { command: buildCommand } } : {}),
     });
 }
 export function renderDeclaration(declaration) {
@@ -83,14 +83,13 @@ export async function loadDeclaration(declarationRoot) {
 export function buildRevision(declaration, source) {
     const spec = {
         version: 1,
-        execution: declaration.execution,
+        agent: declaration.agent,
         source: {
             format: source.format,
             sha256: source.sha256,
             size_bytes: source.size_bytes,
         },
         inference: declaration.inference,
-        session_capture: { adapter: declaration.session_capture.adapter },
         ...(declaration.service ? { service: declaration.service } : {}),
     };
     assertManagedRevision(spec);

package/dist/src/generated/contracts.d.ts

@@ -1,3 +1,59 @@
+export declare const piAgentSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://contracts.tonbo.dev/agents/pi-agent-v1.schema.json";
+    readonly title: "PI Agent v1";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["runtime", "driver"];
+    readonly properties: {
+        readonly runtime: {
+            readonly const: "pi";
+        };
+        readonly secrets: {
+            readonly type: "array";
+            readonly maxItems: 32;
+            readonly uniqueItems: true;
+            readonly items: {
+                readonly type: "string";
+                readonly pattern: "^[A-Z_][A-Z0-9_]{0,127}$";
+            };
+        };
+        readonly driver: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly const: "native";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "protocol", "command"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly const: "command";
+                    };
+                    readonly protocol: {
+                        readonly const: "pi-rpc-v1";
+                    };
+                    readonly command: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly maxItems: 64;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 1024;
+                        };
+                    };
+                };
+            }];
+        };
+    };
+};
 export declare const projectServiceSchema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://contracts.tonbo.dev/agents/project-service-v1.schema.json";
@@ -52,23 +108,13 @@ export declare const declarationSchema: {
     readonly title: "Tonbo Project Agent declaration v1";
     readonly type: "object";
     readonly additionalProperties: false;
-    readonly required: readonly ["version", "execution", "session_capture"];
+    readonly required: readonly ["version", "agent"];
     readonly properties: {
         readonly version: {
             readonly const: 1;
         };
-        readonly execution: {
-            readonly type: "object";
-            readonly additionalProperties: false;
-            readonly required: readonly ["mode", "runtime"];
-            readonly properties: {
-                readonly mode: {
-                    readonly const: "managed";
-                };
-                readonly runtime: {
-                    readonly const: "pi";
-                };
-            };
+        readonly agent: {
+            readonly $ref: "https://contracts.tonbo.dev/agents/pi-agent-v1.schema.json";
         };
         readonly inference: {
             readonly type: "object";
@@ -85,13 +131,20 @@ export declare const declarationSchema: {
                 };
             };
         };
-        readonly session_capture: {
+        readonly build: {
             readonly type: "object";
             readonly additionalProperties: false;
-            readonly required: readonly ["adapter"];
+            readonly required: readonly ["command"];
             readonly properties: {
-                readonly adapter: {
-                    readonly const: "pi-jsonl-v3";
+                readonly command: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: 64;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 1024;
+                    };
                 };
             };
         };
@@ -106,23 +159,13 @@ export declare const revisionSchema: {
     readonly title: "Managed Project revision v1";
     readonly type: "object";
     readonly additionalProperties: false;
-    readonly required: readonly ["version", "execution", "source", "inference", "session_capture"];
+    readonly required: readonly ["version", "agent", "source", "inference"];
     readonly properties: {
         readonly version: {
             readonly const: 1;
         };
-        readonly execution: {
-            readonly type: "object";
-            readonly additionalProperties: false;
-            readonly required: readonly ["mode", "runtime"];
-            readonly properties: {
-                readonly mode: {
-                    readonly const: "managed";
-                };
-                readonly runtime: {
-                    readonly const: "pi";
-                };
-            };
+        readonly agent: {
+            readonly $ref: "https://contracts.tonbo.dev/agents/pi-agent-v1.schema.json";
         };
         readonly source: {
             readonly type: "object";
@@ -155,16 +198,6 @@ export declare const revisionSchema: {
                 };
             };
         };
-        readonly session_capture: {
-            readonly type: "object";
-            readonly additionalProperties: false;
-            readonly required: readonly ["adapter"];
-            readonly properties: {
-                readonly adapter: {
-                    readonly const: "pi-jsonl-v3";
-                };
-            };
-        };
         readonly service: {
             readonly $ref: "https://contracts.tonbo.dev/agents/project-service-v1.schema.json";
         };

package/dist/src/generated/contracts.js

@@ -1,5 +1,73 @@
-// Generated from contracts/agents/project-service-v1.schema.json and contracts/agents/kubernetes-profiles-v1.schema.json and contracts/agents/tonbo-declaration-v1.schema.json and contracts/agents/managed-revision-v1.schema.json and contracts/agents/source-bundle-v1.json and contracts/agents/pi-session-v1.json.
+// Generated from contracts/agents/pi-agent-v1.schema.json and contracts/agents/project-service-v1.schema.json and contracts/agents/kubernetes-profiles-v1.schema.json and contracts/agents/tonbo-declaration-v1.schema.json and contracts/agents/managed-revision-v1.schema.json and contracts/agents/source-bundle-v1.json and contracts/agents/pi-session-v1.json.
 // Run pnpm generate:contracts after changing a canonical Agent contract.
+export const piAgentSchema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://contracts.tonbo.dev/agents/pi-agent-v1.schema.json",
+    "title": "PI Agent v1",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "runtime",
+        "driver"
+    ],
+    "properties": {
+        "runtime": {
+            "const": "pi"
+        },
+        "secrets": {
+            "type": "array",
+            "maxItems": 32,
+            "uniqueItems": true,
+            "items": {
+                "type": "string",
+                "pattern": "^[A-Z_][A-Z0-9_]{0,127}$"
+            }
+        },
+        "driver": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "kind"
+                    ],
+                    "properties": {
+                        "kind": {
+                            "const": "native"
+                        }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "kind",
+                        "protocol",
+                        "command"
+                    ],
+                    "properties": {
+                        "kind": {
+                            "const": "command"
+                        },
+                        "protocol": {
+                            "const": "pi-rpc-v1"
+                        },
+                        "command": {
+                            "type": "array",
+                            "minItems": 1,
+                            "maxItems": 64,
+                            "items": {
+                                "type": "string",
+                                "minLength": 1,
+                                "maxLength": 1024
+                            }
+                        }
+                    }
+                }
+            ]
+        }
+    }
+};
 export const projectServiceSchema = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://contracts.tonbo.dev/agents/project-service-v1.schema.json",
@@ -60,28 +128,14 @@ export const declarationSchema = {
     "additionalProperties": false,
     "required": [
         "version",
-        "execution",
-        "session_capture"
+        "agent"
     ],
     "properties": {
         "version": {
             "const": 1
         },
-        "execution": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-                "mode",
-                "runtime"
-            ],
-            "properties": {
-                "mode": {
-                    "const": "managed"
-                },
-                "runtime": {
-                    "const": "pi"
-                }
-            }
+        "agent": {
+            "$ref": "https://contracts.tonbo.dev/agents/pi-agent-v1.schema.json"
         },
         "inference": {
             "type": "object",
@@ -100,15 +154,22 @@ export const declarationSchema = {
                 }
             }
         },
-        "session_capture": {
+        "build": {
             "type": "object",
             "additionalProperties": false,
             "required": [
-                "adapter"
+                "command"
             ],
             "properties": {
-                "adapter": {
-                    "const": "pi-jsonl-v3"
+                "command": {
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": 64,
+                    "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                    }
                 }
             }
         },
@@ -125,30 +186,16 @@ export const revisionSchema = {
     "additionalProperties": false,
     "required": [
         "version",
-        "execution",
+        "agent",
         "source",
-        "inference",
-        "session_capture"
+        "inference"
     ],
     "properties": {
         "version": {
             "const": 1
         },
-        "execution": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-                "mode",
-                "runtime"
-            ],
-            "properties": {
-                "mode": {
-                    "const": "managed"
-                },
-                "runtime": {
-                    "const": "pi"
-                }
-            }
+        "agent": {
+            "$ref": "https://contracts.tonbo.dev/agents/pi-agent-v1.schema.json"
         },
         "source": {
             "type": "object",
@@ -187,18 +234,6 @@ export const revisionSchema = {
                 }
             }
         },
-        "session_capture": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": [
-                "adapter"
-            ],
-            "properties": {
-                "adapter": {
-                    "const": "pi-jsonl-v3"
-                }
-            }
-        },
         "service": {
             "$ref": "https://contracts.tonbo.dev/agents/project-service-v1.schema.json"
         }

package/dist/src/source.d.ts

@@ -1,4 +1,5 @@
 import type { SourceBundle } from "./types.js";
+export declare function validatePiPackages(root: string): Promise<void>;
 export declare function findDeclarationRoot(start: string): Promise<string>;
 /**
  * Build one deterministic local-source snapshot. Git metadata and timestamps

package/dist/src/source.js

@@ -15,7 +15,76 @@ const DEFAULT_IGNORES = [
     "!.env.example",
     ".tonbo-cache/",
     ".tonbo-system/",
+    ".pi/npm/",
+    ".pi/git/",
 ];
+const EXACT_NPM_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const GIT_COMMIT = /^[0-9a-f]{40}$/i;
+function packageSource(value, index) {
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object" && "source" in value && typeof value.source === "string")
+        return value.source;
+    throw new Error(`.pi/settings.json packages[${index}] must be a source string or object.`);
+}
+async function validatePackageSource(root, source) {
+    if (source.startsWith("npm:")) {
+        const specifier = source.slice(4);
+        const separator = specifier.lastIndexOf("@");
+        if (separator <= 0 || !EXACT_NPM_VERSION.test(specifier.slice(separator + 1))) {
+            throw new Error(`PI package ${source} must pin an exact npm version, for example npm:my-agent@1.2.3.`);
+        }
+        return;
+    }
+    if (source.startsWith("git:")) {
+        const separator = source.lastIndexOf("@");
+        if (separator <= "git:".length || !GIT_COMMIT.test(source.slice(separator + 1))) {
+            throw new Error(`PI package ${source} must pin a full 40-character Git commit.`);
+        }
+        return;
+    }
+    if (source.startsWith("./") || source.startsWith("../")) {
+        const settingsDirectory = path.join(root, ".pi");
+        const resolved = path.resolve(settingsDirectory, source);
+        const relative = path.relative(root, resolved);
+        if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new Error(`Local PI package ${source} resolves outside the deployed project.`);
+        }
+        let metadata;
+        try {
+            metadata = await lstat(resolved);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new Error(`Local PI package ${source} does not exist.`);
+            }
+            throw error;
+        }
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+            throw new Error(`Local PI package ${source} must resolve to a real project directory.`);
+        }
+        return;
+    }
+    throw new Error(`PI package ${source} must use an exact npm version, a full Git commit, or a project-local path.`);
+}
+export async function validatePiPackages(root) {
+    const filename = path.join(root, ".pi", "settings.json");
+    let settings;
+    try {
+        settings = JSON.parse(await readFile(filename, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new Error(`Could not read ${filename} as JSON.`, { cause: error });
+    }
+    if (!settings || typeof settings !== "object" || !("packages" in settings))
+        return;
+    const packages = settings.packages;
+    if (!Array.isArray(packages))
+        throw new Error(`${filename} packages must be an array.`);
+    await Promise.all(packages.map((value, index) => validatePackageSource(root, packageSource(value, index))));
+}
 export async function findDeclarationRoot(start) {
     let candidate = path.resolve(start);
     for (;;) {
@@ -103,6 +172,7 @@ function addEntry(pack, file, contents) {
  */
 export async function buildSourceBundle(root) {
     const resolvedRoot = path.resolve(root);
+    await validatePiPackages(resolvedRoot);
     const files = await collectFiles(resolvedRoot);
     const payloadBytes = files.reduce((total, file) => total + file.size, 0);
     if (payloadBytes > MAX_BUNDLE_BYTES) {

package/dist/src/types.d.ts

@@ -1,14 +1,11 @@
 export interface TonboDeclaration {
     version: 1;
-    execution: {
-        mode: "managed";
-        runtime: "pi";
-    };
+    agent: PiAgent;
     inference: {
         model: string;
     };
-    session_capture: {
-        adapter: "pi-jsonl-v3";
+    build?: {
+        command: string[];
     };
     service?: {
         command: string[];
@@ -20,10 +17,7 @@ export interface TonboDeclaration {
 }
 export interface ManagedRevisionSpec {
     version: 1;
-    execution: {
-        mode: "managed";
-        runtime: "pi";
-    };
+    agent: PiAgent;
     source: {
         format: "tar-v1";
         sha256: string;
@@ -32,9 +26,6 @@ export interface ManagedRevisionSpec {
     inference: {
         model: string;
     };
-    session_capture: {
-        adapter: "pi-jsonl-v3";
-    };
     service?: {
         command: string[];
         secrets?: string[];
@@ -43,6 +34,17 @@ export interface ManagedRevisionSpec {
         };
     };
 }
+export type PiAgent = {
+    runtime: "pi";
+    secrets?: string[];
+    driver: {
+        kind: "native";
+    } | {
+        kind: "command";
+        protocol: "pi-rpc-v1";
+        command: string[];
+    };
+};
 export interface SourceBundle {
     bytes: Buffer;
     format: "tar-v1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Deploy one persistent Agent per Project from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {