@pasko70/pibo 1.16.6 → 2.0.0

package/dist/plugins/registry.js

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
+import { normalizeToolProfile } from "../core/profiles.js";
 import { listInstalledCliToolAgentContexts } from "../tools/registry.js";
 import { listPiPackages } from "../pi-packages/store.js";
+import { AgentRuntimeAdapterRegistry } from "../agent-runtime/registry.js";
 function getWebAppRoutes(app) {
     return [
         { label: "mountPath", prefix: app.mountPath },
@@ -18,7 +20,20 @@ function validateWebRoute(appName, label, prefix) {
 function webRoutesOverlap(left, right) {
     return left === right || left === "/" || right === "/" || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
 }
+function toolIsPortable(tool) {
+    if (tool.definition)
+        return tool.definition.portable !== false;
+    if (!tool.createDefinition)
+        return true;
+    try {
+        return tool.createDefinition({}).portable !== false;
+    }
+    catch {
+        return false;
+    }
+}
 export class PiboPluginRegistry {
+    agentRuntimes = new AgentRuntimeAdapterRegistry();
     tools = new Map();
     subagents = new Map();
     skills = new Map();
@@ -52,8 +67,51 @@ export class PiboPluginRegistry {
         this.pluginNames.set(plugin.id, plugin.name ?? plugin.id);
         plugin.register(this.createApi(plugin.id));
     }
+    registerAgentRuntimeDriver(driver) {
+        this.agentRuntimes.registerDriver(driver);
+    }
+    registerAgentRuntimeInstance(instance) {
+        return this.agentRuntimes.registerInstance(instance);
+    }
+    getAgentRuntimeAdapter(instanceId) {
+        return this.agentRuntimes.getInstance(instanceId);
+    }
+    requireAgentRuntimeAdapter(instanceId) {
+        return this.agentRuntimes.requireInstance(instanceId);
+    }
+    openAgentRuntimeSession(instanceId, input) {
+        return this.agentRuntimes.openSession(instanceId, input);
+    }
+    getAgentRuntimeInstanceIds() {
+        return this.agentRuntimes.getInstanceIds();
+    }
+    inspectAgentRuntimeInstances() {
+        return this.agentRuntimes.inspectInstances();
+    }
+    getAgentRuntimeAuthStatus(runtimeInstanceId) {
+        return this.agentRuntimes.getAuthStatus(runtimeInstanceId);
+    }
+    startAgentRuntimeAuth(runtimeInstanceId, input) {
+        return this.agentRuntimes.startAuth(runtimeInstanceId, input);
+    }
+    completeAgentRuntimeAuth(runtimeInstanceId, input) {
+        return this.agentRuntimes.completeAuth(runtimeInstanceId, input);
+    }
+    cancelAgentRuntimeAuth(runtimeInstanceId, input) {
+        return this.agentRuntimes.cancelAuth(runtimeInstanceId, input);
+    }
+    logoutAgentRuntimeAuth(runtimeInstanceId, input) {
+        return this.agentRuntimes.logoutAuth(runtimeInstanceId, input);
+    }
+    disposeAgentRuntimeAuth() {
+        return this.agentRuntimes.disposeAuth();
+    }
+    validateAgentRuntimeProfile(profile, workspace) {
+        return this.agentRuntimes.validateProfile({ profile, workspace });
+    }
     registerTool(tool) {
-        this.addUnique(this.tools, tool.name, tool, "tool");
+        const normalized = normalizeToolProfile(tool);
+        this.addUnique(this.tools, normalized.name, normalized, "tool");
     }
     registerTools(tools) {
         for (const tool of tools) {
@@ -187,6 +245,8 @@ export class PiboPluginRegistry {
                 name: profile.name,
                 description: profile.description,
                 aliases: [...(profile.aliases ?? [])],
+                runtimeInstanceId: sessionContext.runtimeInstanceId,
+                runtimeOptions: structuredClone(sessionContext.runtimeOptions),
                 nativeTools: sessionContext.tools.filter((tool) => tool.enabled !== false).map((tool) => tool.name),
                 skills: sessionContext.skills.filter((skill) => skill.enabled !== false).map((skill) => skill.name),
                 contextFiles: sessionContext.contextFiles.filter((contextFile) => contextFile.enabled !== false).map(contextFileKey),
@@ -212,11 +272,13 @@ export class PiboPluginRegistry {
     }
     getCapabilityCatalog() {
         return {
+            agentRuntimes: this.agentRuntimes.getInstanceInfos(),
             nativeTools: [...this.tools.values()].map((tool) => ({
                 name: tool.name,
                 description: tool.description,
                 yieldable: tool.yieldable !== false,
                 hasDefinition: tool.definition !== undefined || tool.createDefinition !== undefined,
+                portable: toolIsPortable(tool),
                 pluginId: tool.pluginId,
                 pluginName: tool.pluginId ? this.pluginNames.get(tool.pluginId) : undefined,
                 ...(tool.providerTool ? { providerTool: tool.providerTool } : {}),
@@ -248,7 +310,7 @@ export class PiboPluginRegistry {
             packages: [
                 {
                     name: "pibo-run-control",
-                    description: "Expose pibo_run_* tools as one package for yielded native tools and subagents.",
+                    description: "Expose pibo_run_* for Pibo-managed tools and subagents; private harness-native tools require explicit runtime capability.",
                     toolNames: [
                         "pibo_run_start",
                         "pibo_run_list",
@@ -350,6 +412,8 @@ export class PiboPluginRegistry {
             pluginId: pkg.pluginId ?? pluginId,
         });
         return {
+            registerAgentRuntimeDriver: (driver) => this.registerAgentRuntimeDriver(driver),
+            registerAgentRuntimeInstance: (instance) => this.registerAgentRuntimeInstance(instance),
             registerTool: (tool) => this.registerTool(withPluginToolContext(tool)),
             registerTools: (tools) => this.registerTools(tools.map(withPluginToolContext)),
             registerSubagent: (subagent) => this.registerSubagent(subagent),

package/dist/runs/tools.js

@@ -1,5 +1,6 @@
-import { StringEnum, Type } from "@earendil-works/pi-ai";
-import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { piboStringEnum } from "../tools/schema.js";
+import { definePiboTool } from "../tools/contract.js";
 import { foregroundServiceWarning, hasMeaningfulTimeoutOutput, isConfiguredTimeoutError, PiboRunExecutionTimeoutError, resolveRunTimeoutMs } from "./lifecycle.js";
 import { PiboRunResourceLimitError, prepareYieldedRunExecution } from "./resource-isolation.js";
 function resultText(prefix, value) {
@@ -29,16 +30,16 @@ function requireTool(tools, name) {
 export function createRunToolDefinitions(yieldableTools, controller) {
     const toolNames = yieldableTools.map((tool) => tool.name);
     return [
-        defineTool({
+        definePiboTool({
             name: "pibo_run_start",
-            label: "Pibo Run Start",
+            title: "Pibo Run Start",
             description: "Start a yieldable tool as a yielded run. The run records its configured timeout and classifies lifetime expiry separately from command failure. Use detached only for intentional fire-and-forget work.",
             promptSnippet: "Use pibo_run_start to run a yieldable tool in the background. It returns a runId. Use pibo_run_read for completed results and pibo_run_wait/status/list/cancel/ack to manage runs.",
             executionMode: "parallel",
-            parameters: Type.Object({
-                toolName: StringEnum(toolNames, { description: "Yieldable tool name to start" }),
+            inputSchema: Type.Object({
+                toolName: piboStringEnum(toolNames, { description: "Yieldable tool name to start" }),
                 arguments: Type.Any({ description: "Arguments object for the selected tool" }),
-                completionPolicy: Type.Optional(StringEnum(["tracked", "detached"], {
+                completionPolicy: Type.Optional(piboStringEnum(["tracked", "detached"], {
                     description: "tracked reminds this agent about completion; detached is fire-and-forget and creates no automatic reminders.",
                     default: "tracked",
                 })),
@@ -87,13 +88,13 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                 };
             },
         }),
-        defineTool({
+        definePiboTool({
             name: "pibo_run_list",
-            label: "Pibo Run List",
+            title: "Pibo Run List",
             description: "List yielded runs owned by this agent session.",
             promptSnippet: "Use pibo_run_list to inspect yielded runs owned by this session.",
             executionMode: "parallel",
-            parameters: Type.Object({
+            inputSchema: Type.Object({
                 includeConsumed: Type.Optional(Type.Boolean({ description: "Include already read, cancelled, or acknowledged runs" })),
                 includeDetached: Type.Optional(Type.Boolean({ description: "Include fire-and-forget detached runs" })),
             }),
@@ -108,13 +109,13 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                 };
             },
         }),
-        defineTool({
+        definePiboTool({
             name: "pibo_run_status",
-            label: "Pibo Run Status",
+            title: "Pibo Run Status",
             description: "Read compact status for one yielded run.",
             promptSnippet: "Use pibo_run_status to inspect one yielded run without reading its full result.",
             executionMode: "parallel",
-            parameters: Type.Object({
+            inputSchema: Type.Object({
                 runId: Type.String({ description: "Run id returned by pibo_run_start" }),
             }),
             async execute(_toolCallId, params) {
@@ -125,13 +126,13 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                 };
             },
         }),
-        defineTool({
+        definePiboTool({
             name: "pibo_run_wait",
-            label: "Pibo Run Wait",
+            title: "Pibo Run Wait",
             description: "Wait a bounded time for a yielded run. Timeout is normal and does not mean failure.",
             promptSnippet: "Use pibo_run_wait when blocked on a run. Timeout is normal; call again or continue other work.",
             executionMode: "parallel",
-            parameters: Type.Object({
+            inputSchema: Type.Object({
                 runId: Type.String({ description: "Run id returned by pibo_run_start" }),
                 timeoutMs: Type.Optional(Type.Number({ description: "Maximum wait time in milliseconds, clamped to 300000" })),
             }),
@@ -150,13 +151,13 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                 };
             },
         }),
-        defineTool({
+        definePiboTool({
             name: "pibo_run_read",
-            label: "Pibo Run Read",
+            title: "Pibo Run Read",
             description: "Read the terminal result, timeout reason, or error for a yielded run.",
             promptSnippet: "Use pibo_run_read to retrieve a completed, failed, or timed_out run result. Reading terminal tracked runs consumes reminders.",
             executionMode: "parallel",
-            parameters: Type.Object({
+            inputSchema: Type.Object({
                 runId: Type.String({ description: "Run id returned by pibo_run_start" }),
             }),
             async execute(_toolCallId, params) {
@@ -168,13 +169,13 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                 };
             },
         }),
-        defineTool({
+        definePiboTool({
             name: "pibo_run_cancel",
-            label: "Pibo Run Cancel",
+            title: "Pibo Run Cancel",
             description: "Cancel a yielded run if possible and suppress future reminders.",
             promptSnippet: "Use pibo_run_cancel when a yielded run is no longer needed.",
             executionMode: "parallel",
-            parameters: Type.Object({
+            inputSchema: Type.Object({
                 runId: Type.String({ description: "Run id returned by pibo_run_start" }),
             }),
             async execute(_toolCallId, params) {
@@ -185,13 +186,13 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                 };
             },
         }),
-        defineTool({
+        definePiboTool({
             name: "pibo_run_ack",
-            label: "Pibo Run Ack",
+            title: "Pibo Run Ack",
             description: "Acknowledge a yielded run update and suppress reminders for its current state.",
             promptSnippet: "Use pibo_run_ack when you intentionally do not need to read a completed result or do not need more reminders for the current running state.",
             executionMode: "parallel",
-            parameters: Type.Object({
+            inputSchema: Type.Object({
                 runId: Type.String({ description: "Run id returned by pibo_run_start" }),
             }),
             async execute(_toolCallId, params) {

package/dist/session-ui/terminalRows.js

@@ -226,8 +226,8 @@ function createAssistantMessageRow(node) {
         lines: [],
         sourceNodeIds: [node.id],
         startedAt: node.startedAt,
-        completedAt: node.source === "transcript" ? node.completedAt : undefined,
-        durationMs: node.source === "transcript" ? node.durationMs : undefined,
+        completedAt: node.source === "transcript" || node.source === "product-history" ? node.completedAt : undefined,
+        durationMs: node.source === "transcript" || node.source === "product-history" ? node.durationMs : undefined,
         output: stringValue(node.output) || stringValue(node.summary) || "",
         error: node.error,
         payloadRefs: node.payloadRefs,

package/dist/sessions/pibo-data-store.js

@@ -1,6 +1,26 @@
 import { ChatDataIngestService } from "../data/ingest-service.js";
 import { PiboDataStore } from "../data/pibo-store.js";
 import { createPiboSession, matchesFindInput, } from "./store.js";
+import { createLegacyPiRuntimeSessionBinding, nextRuntimeSessionBinding, RuntimeSessionBindingConflictError, } from "./runtime-binding.js";
+const SESSION_SELECT = `
+	SELECT
+		s.*,
+		b.pibo_session_id AS binding_pibo_session_id,
+		b.runtime_instance_id AS binding_runtime_instance_id,
+		b.runtime_adapter_id AS binding_runtime_adapter_id,
+		b.native_session_id AS binding_native_session_id,
+		b.binding_state AS binding_state,
+		b.protocol AS binding_protocol,
+		b.protocol_version AS binding_protocol_version,
+		b.adapter_version AS binding_adapter_version,
+		b.locator_json AS binding_locator_json,
+		b.metadata_json AS binding_metadata_json,
+		b.revision AS binding_revision,
+		b.created_at AS binding_created_at,
+		b.updated_at AS binding_updated_at
+	FROM sessions s
+	LEFT JOIN session_runtime_bindings b ON b.pibo_session_id = s.id
+`;
 export class PiboDataSessionStore {
     dataStore;
     db;
@@ -17,15 +37,15 @@ export class PiboDataSessionStore {
         this.db = this.dataStore.db;
     }
     get(id) {
-        const row = this.db.prepare("SELECT * FROM sessions WHERE id = ? AND deleted_at IS NULL").get(id);
+        const row = this.db.prepare(`${SESSION_SELECT} WHERE s.id = ? AND s.deleted_at IS NULL`).get(id);
         return row ? sessionFromRow(row) : undefined;
     }
     list() {
-        return this.db.prepare("SELECT * FROM sessions WHERE deleted_at IS NULL ORDER BY updated_at DESC").all().map(sessionFromRow);
+        return this.db.prepare(`${SESSION_SELECT} WHERE s.deleted_at IS NULL ORDER BY s.updated_at DESC`).all().map(sessionFromRow);
     }
     create(input) {
         const session = createPiboSession(input);
-        this.insertSession(session);
+        this.dataStore.transaction(() => this.insertSession(session));
         const created = this.get(session.id);
         if (!created)
             throw new Error(`Failed to create Pibo session "${session.id}"`);
@@ -68,7 +88,7 @@ export class PiboDataSessionStore {
 				updated_at = ?,
 				last_activity_at = MAX(last_activity_at, ?)
 			WHERE id = ? AND deleted_at IS NULL
-		`).run(updated.piSessionId, rootSessionId(updated), updated.parentId ?? null, updated.originId ?? null, updated.profile, updated.activeModel ? JSON.stringify(updated.activeModel) : null, updated.workspace ?? null, updated.title ?? "Untitled Session", JSON.stringify(updated.metadata ?? {}), updated.updatedAt, updated.updatedAt, id);
+		`).run(updated.piSessionId || null, rootSessionId(updated), updated.parentId ?? null, updated.originId ?? null, updated.profile, updated.activeModel ? JSON.stringify(updated.activeModel) : null, updated.workspace ?? null, updated.title ?? "Untitled Session", JSON.stringify(updated.metadata ?? {}), updated.updatedAt, updated.updatedAt, id);
         return this.get(id);
     }
     delete(id) {
@@ -76,50 +96,90 @@ export class PiboDataSessionStore {
         return Number(result.changes ?? 0) > 0;
     }
     find(input) {
-        const clauses = ["deleted_at IS NULL"];
+        const clauses = ["s.deleted_at IS NULL"];
         const values = [];
         if (input.ids !== undefined) {
             if (input.ids.length === 0)
                 return [];
-            clauses.push(`id IN (${input.ids.map(() => "?").join(", ")})`);
+            clauses.push(`s.id IN (${input.ids.map(() => "?").join(", ")})`);
             values.push(...input.ids);
         }
         if (input.channel !== undefined) {
-            clauses.push("channel = ?");
+            clauses.push("s.channel = ?");
             values.push(input.channel);
         }
         if (input.kind !== undefined) {
-            clauses.push("kind = ?");
+            clauses.push("s.kind = ?");
             values.push(input.kind);
         }
         if (input.parentId !== undefined) {
             if (input.parentId === null)
-                clauses.push("parent_id IS NULL");
+                clauses.push("s.parent_id IS NULL");
             else {
-                clauses.push("parent_id = ?");
+                clauses.push("s.parent_id = ?");
                 values.push(input.parentId);
             }
         }
         if (input.originId !== undefined) {
-            clauses.push("origin_id = ?");
+            clauses.push("s.origin_id = ?");
             values.push(input.originId);
         }
         if (input.profile !== undefined) {
-            clauses.push("profile = ?");
+            clauses.push("s.profile = ?");
             values.push(input.profile);
         }
         if (input.activeModel !== undefined) {
             if (input.activeModel === null)
-                clauses.push("active_model_json IS NULL");
+                clauses.push("s.active_model_json IS NULL");
             else
-                clauses.push("active_model_json IS NOT NULL");
+                clauses.push("s.active_model_json IS NOT NULL");
         }
-        const rows = this.db.prepare(`SELECT * FROM sessions WHERE ${clauses.join(" AND ")} ORDER BY updated_at DESC`).all(...values);
+        const rows = this.db.prepare(`${SESSION_SELECT} WHERE ${clauses.join(" AND ")} ORDER BY s.updated_at DESC`).all(...values);
         return rows.map(sessionFromRow).filter((session) => matchesFindInput(session, input));
     }
+    getRuntimeBinding(id) {
+        const session = this.get(id);
+        return session?.runtimeBinding ? structuredClone(session.runtimeBinding) : undefined;
+    }
+    updateRuntimeBinding(id, binding, options = {}) {
+        return this.dataStore.transaction(() => {
+            const current = this.getRuntimeBinding(id);
+            if (!current)
+                return undefined;
+            const currentRevision = current.revision ?? 1;
+            const updated = nextRuntimeSessionBinding(current, { ...structuredClone(binding), piboSessionId: id }, options);
+            const result = this.db.prepare(`
+				UPDATE session_runtime_bindings SET
+					runtime_instance_id = ?,
+					runtime_adapter_id = ?,
+					native_session_id = ?,
+					binding_state = ?,
+					protocol = ?,
+					protocol_version = ?,
+					adapter_version = ?,
+					locator_json = ?,
+					metadata_json = ?,
+					revision = ?,
+					updated_at = ?
+				WHERE pibo_session_id = ? AND revision = ?
+			`).run(updated.runtimeInstanceId, updated.adapterId, updated.nativeSessionId ?? null, updated.state, updated.protocol ?? null, updated.protocolVersion ?? null, updated.adapterVersion ?? null, updated.locator ? JSON.stringify(updated.locator) : null, JSON.stringify(updated.metadata ?? {}), updated.revision, updated.updatedAt, id, currentRevision);
+            if (Number(result.changes ?? 0) === 0) {
+                const actual = this.getRuntimeBinding(id);
+                throw new RuntimeSessionBindingConflictError(id, currentRevision, actual?.revision ?? 0);
+            }
+            this.db.prepare(`
+				UPDATE sessions SET pi_session_id = ?, updated_at = ?, last_activity_at = MAX(last_activity_at, ?)
+				WHERE id = ? AND deleted_at IS NULL
+			`).run(updated.adapterId === "pi" ? updated.nativeSessionId ?? null : null, updated.updatedAt, updated.updatedAt, id);
+            return this.getRuntimeBinding(id);
+        });
+    }
     getTelemetryStore() {
         return this.dataStore.telemetry;
     }
+    getPayloadStore() {
+        return this.dataStore.payloads;
+    }
     recoverInterruptedRuntimeState(input = {}) {
         const at = input.at ?? new Date().toISOString();
         const runsBySession = groupRunsByController(input.recoveredRuns ?? []);
@@ -196,7 +256,30 @@ export class PiboDataSessionStore {
         ];
         this.db.prepare(`
 			INSERT INTO sessions (${columns.join(", ")}) VALUES (${columns.map(() => "?").join(", ")})
-		`).run(session.id, session.piSessionId, roomIdFromMetadata(session.metadata), rootSessionId(session), session.parentId ?? null, session.originId ?? null, session.channel, session.kind, session.profile, session.activeModel ? JSON.stringify(session.activeModel) : null, session.workspace ?? null, session.title ?? "Untitled Session", previewText(session.title ?? "") ?? null, "idle", JSON.stringify(session.metadata ?? {}), session.createdAt, session.updatedAt, session.updatedAt);
+		`).run(session.id, session.piSessionId || null, roomIdFromMetadata(session.metadata), rootSessionId(session), session.parentId ?? null, session.originId ?? null, session.channel, session.kind, session.profile, session.activeModel ? JSON.stringify(session.activeModel) : null, session.workspace ?? null, session.title ?? "Untitled Session", previewText(session.title ?? "") ?? null, "idle", JSON.stringify(session.metadata ?? {}), session.createdAt, session.updatedAt, session.updatedAt);
+        this.upsertRuntimeBinding(session.runtimeBinding ?? createLegacyPiRuntimeSessionBinding(session.id, session.piSessionId, session.createdAt));
+    }
+    upsertRuntimeBinding(binding) {
+        this.db.prepare(`
+			INSERT INTO session_runtime_bindings (
+				pibo_session_id, runtime_instance_id, runtime_adapter_id, native_session_id,
+				binding_state, protocol, protocol_version, adapter_version, locator_json,
+				metadata_json, revision, created_at, updated_at
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(pibo_session_id) DO UPDATE SET
+				runtime_instance_id = excluded.runtime_instance_id,
+				runtime_adapter_id = excluded.runtime_adapter_id,
+				native_session_id = excluded.native_session_id,
+				binding_state = excluded.binding_state,
+				protocol = excluded.protocol,
+				protocol_version = excluded.protocol_version,
+				adapter_version = excluded.adapter_version,
+				locator_json = excluded.locator_json,
+				metadata_json = excluded.metadata_json,
+				revision = excluded.revision,
+				created_at = excluded.created_at,
+				updated_at = excluded.updated_at
+		`).run(binding.piboSessionId, binding.runtimeInstanceId, binding.adapterId, binding.nativeSessionId ?? null, binding.state, binding.protocol ?? null, binding.protocolVersion ?? null, binding.adapterVersion ?? null, binding.locator ? JSON.stringify(binding.locator) : null, JSON.stringify(binding.metadata ?? {}), binding.revision ?? 1, binding.createdAt ?? new Date().toISOString(), binding.updatedAt ?? binding.createdAt ?? new Date().toISOString());
     }
 }
 export function createDefaultPiboDataSessionStore() {
@@ -255,6 +338,7 @@ function sessionFromRow(row) {
     return {
         id: row.id,
         piSessionId: row.pi_session_id ?? "",
+        runtimeBinding: runtimeBindingFromRow(row),
         channel: row.channel,
         kind: row.kind,
         profile: row.profile,
@@ -268,6 +352,31 @@ function sessionFromRow(row) {
         updatedAt: row.updated_at,
     };
 }
+function runtimeBindingFromRow(row) {
+    if (!row.binding_runtime_instance_id || !row.binding_runtime_adapter_id || !row.binding_state) {
+        return createLegacyPiRuntimeSessionBinding(row.id, row.pi_session_id ?? undefined, row.created_at);
+    }
+    return {
+        piboSessionId: row.binding_pibo_session_id ?? row.id,
+        runtimeInstanceId: row.binding_runtime_instance_id,
+        adapterId: row.binding_runtime_adapter_id,
+        nativeSessionId: row.binding_native_session_id ?? undefined,
+        state: isRuntimeBindingState(row.binding_state) ? row.binding_state : "error",
+        protocol: row.binding_protocol ?? undefined,
+        protocolVersion: row.binding_protocol_version ?? undefined,
+        adapterVersion: row.binding_adapter_version ?? undefined,
+        locator: row.binding_locator_json
+            ? parseJsonObject(row.binding_locator_json)
+            : undefined,
+        metadata: parseJsonObject(row.binding_metadata_json),
+        revision: row.binding_revision ?? 1,
+        createdAt: row.binding_created_at ?? row.created_at,
+        updatedAt: row.binding_updated_at ?? row.updated_at,
+    };
+}
+function isRuntimeBindingState(value) {
+    return value === "unbound" || value === "bound" || value === "missing" || value === "error";
+}
 function parseJsonObject(json) {
     if (!json)
         return {};

package/dist/sessions/runtime-binding.js

@@ -0,0 +1,107 @@
+import { DEFAULT_AGENT_RUNTIME_INSTANCE_ID } from "../core/profiles.js";
+export class RuntimeSessionBindingConflictError extends Error {
+    piboSessionId;
+    expectedRevision;
+    actualRevision;
+    constructor(piboSessionId, expectedRevision, actualRevision) {
+        super(`Runtime binding for Pibo session "${piboSessionId}" changed concurrently (expected revision ${expectedRevision}, actual revision ${actualRevision}).`);
+        this.piboSessionId = piboSessionId;
+        this.expectedRevision = expectedRevision;
+        this.actualRevision = actualRevision;
+        this.name = "RuntimeSessionBindingConflictError";
+    }
+}
+export class RuntimeSessionBindingTransitionError extends Error {
+    piboSessionId;
+    constructor(piboSessionId, message) {
+        super(`Invalid runtime binding transition for Pibo session "${piboSessionId}": ${message}`);
+        this.piboSessionId = piboSessionId;
+        this.name = "RuntimeSessionBindingTransitionError";
+    }
+}
+export function createInitialRuntimeSessionBinding(piboSessionId, input, now = new Date().toISOString()) {
+    if (!input.runtimeInstanceId.trim()) {
+        throw new RuntimeSessionBindingTransitionError(piboSessionId, "runtime instance id is required");
+    }
+    if (!input.adapterId.trim()) {
+        throw new RuntimeSessionBindingTransitionError(piboSessionId, "runtime adapter id is required");
+    }
+    const nativeSessionId = normalizedOptionalString(input.nativeSessionId);
+    if ((input.state === "bound" || input.state === "missing") && !nativeSessionId) {
+        throw new RuntimeSessionBindingTransitionError(piboSessionId, `${input.state} state requires a native session id`);
+    }
+    return {
+        piboSessionId,
+        runtimeInstanceId: input.runtimeInstanceId,
+        adapterId: input.adapterId,
+        nativeSessionId,
+        state: input.state ?? "unbound",
+        protocol: normalizedOptionalString(input.protocol),
+        protocolVersion: normalizedOptionalString(input.protocolVersion),
+        adapterVersion: normalizedOptionalString(input.adapterVersion),
+        locator: input.locator ? structuredClone(input.locator) : undefined,
+        metadata: input.metadata ? structuredClone(input.metadata) : {},
+        revision: 1,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+export function createLegacyPiRuntimeSessionBinding(piboSessionId, piSessionId, now = new Date().toISOString()) {
+    const nativeSessionId = normalizedOptionalString(piSessionId);
+    return createInitialRuntimeSessionBinding(piboSessionId, {
+        runtimeInstanceId: DEFAULT_AGENT_RUNTIME_INSTANCE_ID,
+        adapterId: "pi",
+        nativeSessionId,
+        state: nativeSessionId ? "bound" : "unbound",
+        protocol: "pi-sdk",
+    }, now);
+}
+export function nextRuntimeSessionBinding(current, next, options = {}, now = new Date().toISOString()) {
+    const currentRevision = current.revision ?? 1;
+    if (options.expectedRevision !== undefined && currentRevision !== options.expectedRevision) {
+        throw new RuntimeSessionBindingConflictError(current.piboSessionId, options.expectedRevision, currentRevision);
+    }
+    assertRuntimeSessionBindingTransition(current, next, options);
+    return {
+        ...structuredClone(next),
+        piboSessionId: current.piboSessionId,
+        revision: currentRevision + 1,
+        createdAt: current.createdAt ?? now,
+        updatedAt: now,
+    };
+}
+export function assertRuntimeSessionBindingTransition(current, next, options = {}) {
+    const mode = options.mode ?? "normal";
+    if (!next.runtimeInstanceId.trim()) {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, "runtime instance id is required");
+    }
+    if (!next.adapterId.trim()) {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, "runtime adapter id is required");
+    }
+    if ((current.runtimeInstanceId !== next.runtimeInstanceId || current.adapterId !== next.adapterId)
+        && mode !== "rebind") {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, "changing the runtime instance or adapter requires rebind mode");
+    }
+    if (current.state === "unbound" && next.state === "bound" && options.expectedRevision === undefined) {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, "unbound to bound requires an expected revision");
+    }
+    if ((current.state === "missing" || current.state === "error") && next.state === "bound" && mode === "normal") {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, `${current.state} to bound requires repair or rebind mode`);
+    }
+    if (current.state === "bound" && next.state === "unbound" && mode !== "rebind") {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, "bound to unbound requires rebind mode");
+    }
+    if (current.state === "bound"
+        && next.state === "bound"
+        && current.nativeSessionId !== next.nativeSessionId
+        && mode !== "rebind") {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, "changing a bound native session id requires rebind mode");
+    }
+    if ((next.state === "bound" || next.state === "missing") && !normalizedOptionalString(next.nativeSessionId)) {
+        throw new RuntimeSessionBindingTransitionError(current.piboSessionId, `${next.state} state requires a native session id`);
+    }
+}
+function normalizedOptionalString(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}