@tonbo/cli 0.0.4 → 0.0.6

package/README.md

@@ -7,25 +7,32 @@ npm install --global @tonbo/cli
 tonbo --version
 ```
 
-The V1 CLI deploys a PI-based Agent directly from a local directory without requiring Git or Tonbo calls in the Agent source. Add one JSON declaration at the directory root:
-
-```json
-{
-  "version": 1,
-  "execution": {
-    "mode": "managed",
-    "runtime": "pi"
-  },
-  "inference": {
-    "model": "claude-sonnet-4-5"
-  },
-  "session_capture": {
-    "adapter": "pi-jsonl-v3"
-  }
-}
+The V1 CLI deploys a PI-based Agent directly from a local directory without requiring Git or Tonbo calls in the Agent source. Initialize the current directory interactively:
+
+```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>
+```
+
+The generated `.tonbo` is TOML:
+
+```toml
+version = 1
+
+[agent]
+runtime = "pi"
+
+[agent.driver]
+kind = "native"
+
+[inference]
+model = "claude-sonnet-4-5"
 ```
 
-Then authenticate, bind the directory and deploy its current contents:
+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:
 
 ```console
 tonbo login
@@ -56,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

@@ -2,10 +2,12 @@ import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { TonboApi } from "./api.js";
 import { AuthClient } from "./auth.js";
-import { deployCommand, runCommand, loginCommand, projectCreateCommand, projectUseCommand, sshCommand, sshKeyAddCommand, sshKeyRemoveCommand, secretListCommand, secretRemoveCommand, secretSetCommand, } from "./commands.js";
+import { deployCommand, initCommand, runCommand, loginCommand, projectCreateCommand, projectUseCommand, sshCommand, sshKeyAddCommand, sshKeyRemoveCommand, secretListCommand, secretRemoveCommand, secretSetCommand, } from "./commands.js";
 import { FileConfigStore } from "./config.js";
 import { FileCredentialStore } from "./credentials.js";
+import { DECLARATION_FILENAME } from "./declaration.js";
 import { silentProgress, TerminalProgress } from "./progress.js";
+import { terminalPrompt } from "./prompt.js";
 import { readDefaultSshPublicKeys } from "./ssh-key.js";
 const packageVersion = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 export function createDependencies(json = false) {
@@ -17,6 +19,7 @@ export function createDependencies(json = false) {
         config: new FileConfigStore(),
         cwd: () => process.cwd(),
         defaultSshPublicKeys: readDefaultSshPublicKeys,
+        interactive: () => !json && process.stdin.isTTY === true && process.stderr.isTTY === true,
         output: (value) => {
             if (json)
                 console.log(JSON.stringify(value));
@@ -24,6 +27,7 @@ export function createDependencies(json = false) {
                 console.log(value.message ?? value);
         },
         progress: json ? silentProgress : new TerminalProgress(process.stderr),
+        prompt: terminalPrompt,
         secretValue: async (name, fromEnvironment) => {
             const environmentName = fromEnvironment ?? name;
             const value = process.env[environmentName];
@@ -39,6 +43,15 @@ export function createProgram(dependencies = createDependencies) {
         .description("Deploy a persistent Project Agent to Tonbo.")
         .version(packageVersion.version)
         .option("--json", "print machine-readable JSON");
+    program
+        .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
         .command("login")
         .description("sign in through the browser and store the session in the user config")

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

@@ -10,8 +10,10 @@ export interface CommandDependencies {
     config: ConfigStore;
     cwd: () => string;
     defaultSshPublicKeys: typeof readDefaultSshPublicKeys;
+    interactive: () => boolean;
     output: (value: unknown) => void;
     progress: ProgressReporter;
+    prompt: (question: string) => Promise<string>;
     executable?: () => string;
     secretValue: (name: string, fromEnvironment?: string) => Promise<string>;
 }
@@ -20,6 +22,13 @@ export declare function resolveProject(deps: CommandDependencies, selector?: str
     project: ProjectSummary;
 }>;
 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>;
 export declare function loginCommand(deps: CommandDependencies): Promise<void>;
 export declare function sshKeyAddCommand(deps: CommandDependencies, path: string): Promise<void>;
 export declare function sshKeyRemoveCommand(deps: CommandDependencies, fingerprint: string): Promise<void>;

package/dist/src/commands.js

@@ -1,4 +1,6 @@
-import { buildRevision, loadDeclaration } from "./declaration.js";
+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";
 import { launchProjectSsh } from "./ssh.js";
@@ -36,6 +38,65 @@ export function selectProject(projects, selector) {
         throw new Error(`Project ${selector} is not active.`);
     return matches[0];
 }
+export async function initCommand(deps, options) {
+    const root = deps.cwd();
+    const exists = await declarationExists(root);
+    let overwrite = options.force === true;
+    if (exists && !overwrite) {
+        if (!deps.interactive())
+            throw new Error(`${DECLARATION_FILENAME} already exists. Pass --force to replace it.`);
+        const answer = (await deps.prompt(`Replace existing ${DECLARATION_FILENAME}? [y/N] `))
+            .trim()
+            .toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            deps.output({ message: `Kept existing ${DECLARATION_FILENAME}.` });
+            return;
+        }
+        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 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}.${shapeHint}\nNext: tonbo project create <slug>`,
+        declaration,
+        path: path.join(root, DECLARATION_FILENAME),
+    });
+}
 export async function loginCommand(deps) {
     try {
         const tokens = await deps.auth.login((event) => reportLoginProgress(deps.progress, event));
@@ -121,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);
@@ -13,7 +14,7 @@ function validationMessage(label, errors) {
 export function parseDeclaration(value) {
     const candidate = structuredClone(value);
     if (!validateDeclaration(candidate)) {
-        throw new Error(validationMessage(".tonbo", validateDeclaration.errors));
+        throw new Error(validationMessage(".tonbo TOML", validateDeclaration.errors));
     }
     return candidate;
 }

package/dist/src/declaration.d.ts

@@ -1,4 +1,10 @@
 import { parseDeclaration } from "./contracts.js";
-import type { ManagedRevisionSpec, SourceBundle } from "./types.js";
-export declare function loadDeclaration(declarationRoot: string): Promise<import("./types.js").TonboDeclaration>;
+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, 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>;
+export declare function loadDeclaration(declarationRoot: string): Promise<TonboDeclaration>;
 export declare function buildRevision(declaration: ReturnType<typeof parseDeclaration>, source: SourceBundle): ManagedRevisionSpec;

package/dist/src/declaration.js

@@ -1,30 +1,95 @@
-import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { lstat, open, readFile, rename, rm } from "node:fs/promises";
 import path from "node:path";
+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, driver = { kind: "native" }, buildCommand) {
+    return parseDeclaration({
+        version: 1,
+        agent: { runtime: "pi", driver },
+        inference: { model: model.trim() },
+        ...(buildCommand ? { build: { command: buildCommand } } : {}),
+    });
+}
+export function renderDeclaration(declaration) {
+    return `# Tonbo Project Agent configuration.\n${stringify(declaration)}`;
+}
+export async function declarationExists(root) {
+    const filename = path.join(root, DECLARATION_FILENAME);
+    try {
+        const metadata = await lstat(filename);
+        if (metadata.isSymbolicLink() || !metadata.isFile())
+            throw new Error(`${filename} must be a regular file.`);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function saveDeclaration(root, declaration, overwrite) {
+    const filename = path.join(root, DECLARATION_FILENAME);
+    const exists = await declarationExists(root);
+    if (exists && !overwrite)
+        throw new Error(`${DECLARATION_FILENAME} already exists. Pass --force to replace it.`);
+    const contents = renderDeclaration(declaration);
+    if (!overwrite) {
+        const handle = await open(filename, "wx", 0o644).catch((error) => {
+            if (error.code === "EEXIST")
+                throw new Error(`${DECLARATION_FILENAME} already exists. Pass --force to replace it.`);
+            throw error;
+        });
+        try {
+            await handle.writeFile(contents, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return;
+    }
+    const temporary = path.join(root, `.${DECLARATION_FILENAME}.${process.pid}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o644);
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, filename);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 export async function loadDeclaration(declarationRoot) {
-    const filename = path.join(declarationRoot, ".tonbo");
+    const filename = path.join(declarationRoot, DECLARATION_FILENAME);
     let parsed;
     try {
-        parsed = JSON.parse(await readFile(filename, "utf8"));
+        parsed = parse(await readFile(filename, "utf8"));
     }
     catch (error) {
         if (error.code === "ENOENT")
-            throw new Error(`No .tonbo declaration found at ${filename}.`);
-        throw new Error(`Could not read ${filename} as JSON.`, { cause: error });
+            throw new Error(`No ${DECLARATION_FILENAME} declaration found at ${filename}.`);
+        throw new Error(`Could not read ${filename} as TOML.`, { cause: error });
     }
     return parseDeclaration(parsed);
 }
 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/prompt.d.ts

@@ -0,0 +1 @@
+export declare function terminalPrompt(question: string): Promise<string>;

package/dist/src/prompt.js

@@ -0,0 +1,10 @@
+import { createInterface } from "node:readline/promises";
+export async function terminalPrompt(question) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await prompt.question(`? ${question}`);
+    }
+    finally {
+        prompt.close();
+    }
+}

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.4",
+  "version": "0.0.6",
   "description": "Deploy one persistent Agent per Project from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {
@@ -33,6 +33,7 @@
     "ajv": "8.20.0",
     "commander": "^14.0.3",
     "ignore": "^7.0.5",
+    "smol-toml": "1.6.1",
     "tar-stream": "^3.1.7"
   },
   "devDependencies": {