@pasko70/pibo 2.5.2 → 3.0.1

package/context/pibo-native-tooling.md

@@ -11,6 +11,7 @@ Use Pibo-owned operator/debug CLI capabilities before ad hoc scripts:
 - `pibo debug pty ...` for real PTY-backed CLI/TUI smoke tests, scripted input, assertions, and raw/clean artifacts.
 
 For fast web research and lightweight navigation, prefer `pibo tools agent-browser`. For web development and UI validation, prefer Browser Use and pair it with Chrome DevTools/CDP or `pibo debug web ...` for console, network, DOM, performance, and render-state evidence. Use a headful Browser Use target for design, layout, responsive, focus, input, and screenshot validation; headless evidence alone is not sufficient for design acceptance. Start with `pibo tools show browser-use`, `pibo tools guide browser-use browser-use`, and `npm run dev -- mcp info chrome-devtools`; use `pibo tools show agent-browser` for the fast research path.
+To start and show a loopback development server without keeping the agent turn active, use `pibo preview expose <port> --session <ps_...> --command '<start-command>'`; do not keep Preview servers in yielded runs. Discover start, stop, restart, and removal with `pibo preview`.
 For interactive terminal debugging, start with `pibo debug pty --help`; prefer mocked/deterministic scenarios by default and use `--real-provider` only with bounded `--max-iterations`.
 
 Use `pibo skills --help` to manage user skills. This CLI covers user-installed skills only, not built-in or plugin-provided skills. Prefer `pibo skills list --json` when another agent will parse the result.

package/dist/agent-runtime/contract.js

@@ -1,4 +1,5 @@
 import { AgentRuntimeContractError } from "./errors.js";
+import { hasPendingNativeSession } from "../sessions/runtime-binding.js";
 export function validateAgentRuntimeSessionContract(session) {
     const errors = [];
     const capabilities = session.capabilities;
@@ -32,7 +33,7 @@ export function validateAgentRuntimeSessionContract(session) {
     if (binding.state === "bound" && !binding.nativeSessionId) {
         errors.push("a bound session requires binding.nativeSessionId");
     }
-    if (binding.state === "unbound" && binding.nativeSessionId) {
+    if (binding.state === "unbound" && binding.nativeSessionId && !hasPendingNativeSession(binding)) {
         errors.push("an unbound session must not expose binding.nativeSessionId");
     }
     return errors;

package/dist/agent-runtime/history.js

@@ -1 +1,53 @@
-export {};
+/**
+ * Build a structural complete-history claim for compatibility callers.
+ *
+ * This function does not grant reconciliation authority. Only an exact built-in
+ * adapter can bind a returned claim to its provider-local runtime registry.
+ */
+export function createCompleteHistoryReconciliationProof(entries, scopeId) {
+    const proofEntries = Object.freeze([...entries]);
+    return {
+        complete: true,
+        ...(scopeId ? { scopeId } : {}),
+        fullScope: {
+            entryCount: proofEntries.length,
+            digest: historyReconciliationDigest(proofEntries),
+        },
+        entries: proofEntries,
+    };
+}
+export function historyReconciliationDigest(entries) {
+    const mask = 0xffffffffffffffffn;
+    const prime = 0x100000001b3n;
+    const hashes = [
+        0xcbf29ce484222325n,
+        0x84222325cbf29ce4n,
+        0x9e3779b97f4a7c15n,
+        0x517cc1b727220a95n,
+    ];
+    for (const entry of entries) {
+        const signature = `${historyReconciliationEntrySignature(entry)}\n`;
+        for (let index = 0; index < signature.length; index += 1) {
+            const codeUnit = BigInt(signature.charCodeAt(index));
+            for (let hashIndex = 0; hashIndex < hashes.length; hashIndex += 1) {
+                hashes[hashIndex] = ((hashes[hashIndex] ^ codeUnit) * prime) & mask;
+            }
+        }
+    }
+    return hashes.map((hash) => hash.toString(16).padStart(16, "0")).join("");
+}
+export function historyReconciliationEntrySignature(entry) {
+    const { sequence: _pageLocalSequence, ...proofContent } = entry;
+    return stableHistoryJson(proofContent);
+}
+function stableHistoryJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableHistoryJson).join(",")}]`;
+    return `{${Object.entries(value)
+        .filter(([, child]) => child !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => `${JSON.stringify(key)}:${stableHistoryJson(child)}`)
+        .join(",")}}`;
+}

package/dist/agent-runtime/routed-session.js

@@ -12,7 +12,7 @@ const RUN_REMINDER_CAPABILITY_TOOLS = new Set([
 // Run reminders are autonomous service wakeups, so their provider/tool loop needs a deterministic boundary.
 const RUN_REMINDER_MAX_TOOL_EXECUTIONS = 64;
 const RUN_REMINDER_MAX_PROVIDER_ROUNDS = 64;
-const RUN_REMINDER_MAX_TOTAL_TOKENS = 2_000_000;
+const RUN_REMINDER_MAX_ACTIVE_TOKENS = 2_000_000;
 const RUN_REMINDER_MAX_DURATION_MS = 15 * 60 * 1000;
 const RUN_REMINDER_MAX_REPEATED_TOOL_CALLS = 12;
 function serializedToolArgs(value) {
@@ -48,10 +48,23 @@ function nativeSnapshotToPiCompatibility(session, snapshot) {
     };
 }
 function nativeOperationToPiCompatibility(session, piboSessionId, result) {
+    // Keep the legacy Pi-shaped result while allowing an adapter-native fork to
+    // describe a fresh branch that has no native session yet.
+    const current = result.current.nativeSessionId
+        ? nativeSnapshotToPiCompatibility(session, result.current)
+        : {
+            piSessionId: "",
+            leafId: result.current.leafId ?? null,
+            cwd: result.current.cwd,
+            sessionName: result.current.name,
+            parentSessionFile: result.current.parentLocator?.kind === "local-file"
+                ? result.current.parentLocator.value
+                : undefined,
+        };
     return {
         piboSessionId,
         previous: nativeSnapshotToPiCompatibility(session, result.previous),
-        current: nativeSnapshotToPiCompatibility(session, result.current),
+        current,
         cancelled: result.cancelled,
         selectedText: result.selectedText,
         editorText: result.editorText,
@@ -105,6 +118,8 @@ export class RuntimeRoutedSession {
     nextAssistantIndex = 0;
     activeThinkingIndex;
     nextThinkingIndex = 0;
+    sessionIdentityOperationInFlight = false;
+    forkCandidatesRequest;
     unsubscribe;
     constructor(piboSessionId, runtimeSession, emit, pluginRegistry, options = {}) {
         this.piboSessionId = piboSessionId;
@@ -115,8 +130,12 @@ export class RuntimeRoutedSession {
         this.runtime = runtimeSession.getNativeCompatibilityHandle?.() ?? runtimeSession;
         this.unsubscribe = runtimeSession.subscribe((event) => this.handleRuntimeEvent(event));
     }
-    enqueueMessage(event) {
+    enqueueMessage(event, onAccepted = () => { }) {
         this.assertActive();
+        if (this.sessionIdentityOperationInFlight && !this.forkCandidatesRequest) {
+            throw new Error("Pibo session cannot accept messages while a session identity operation is in progress.");
+        }
+        onAccepted();
         this.queue.push({ kind: "message", event });
         const output = {
             type: "message_queued",
@@ -163,18 +182,35 @@ export class RuntimeRoutedSession {
         this.assertActive();
         if (event.action === "compact")
             return this.enqueueCompactAction(event);
-        const result = await this.runAction(event);
-        if (isSessionOperationResult(result))
-            await this.options.onSessionOperation?.(result, event);
-        const output = {
-            type: "execution_result",
-            piboSessionId: this.piboSessionId,
-            eventId: event.id,
-            action: event.action,
-            result,
-        };
-        this.emit(output);
-        return output;
+        const changesSessionIdentity = event.action === "session.fork" || event.action === "session.clone";
+        if (changesSessionIdentity) {
+            this.assertSessionIdentityOperationIdle(event.action === "session.fork" ? "fork" : "clone");
+            this.sessionIdentityOperationInFlight = true;
+            this.notifyState();
+        }
+        try {
+            if (changesSessionIdentity)
+                await this.options.onBeforeSessionIdentityOperation?.(event);
+            const result = await this.runAction(event);
+            if (isSessionOperationResult(result))
+                await this.options.onSessionOperation?.(result, event);
+            const output = {
+                type: "execution_result",
+                piboSessionId: this.piboSessionId,
+                eventId: event.id,
+                action: event.action,
+                result,
+            };
+            this.emit(output);
+            return output;
+        }
+        finally {
+            if (changesSessionIdentity) {
+                this.sessionIdentityOperationInFlight = false;
+                this.notifyState();
+                this.startDrain();
+            }
+        }
     }
     getActiveMessage() {
         if (!this.activeMessage)
@@ -297,24 +333,54 @@ export class RuntimeRoutedSession {
             throw runtimeCapabilityError(this.runtimeSession, "native session listing");
         return (await listSessions()).map((info) => nativeSessionInfoToPiCompatibility(this.runtimeSession, info));
     }
-    getForkCandidates() {
+    async getForkCandidates() {
+        if (this.forkCandidatesRequest)
+            return await this.forkCandidatesRequest;
+        this.assertSessionIdentityOperationIdle("inspect fork candidates");
         const getForkCandidates = this.runtimeSession.controls?.getForkCandidates;
         if (!getForkCandidates)
             throw runtimeCapabilityError(this.runtimeSession, "native session fork candidates");
-        return getForkCandidates();
+        this.sessionIdentityOperationInFlight = true;
+        this.notifyState();
+        const request = Promise.resolve().then(async () => await getForkCandidates());
+        this.forkCandidatesRequest = request;
+        try {
+            return await request;
+        }
+        finally {
+            if (this.forkCandidatesRequest === request)
+                this.forkCandidatesRequest = undefined;
+            this.sessionIdentityOperationInFlight = false;
+            this.notifyState();
+            this.startDrain();
+        }
     }
     async forkSession(entryId) {
+        this.assertSessionWorkIdle("fork");
         const forkSession = this.runtimeSession.controls?.forkSession;
         if (!forkSession)
             throw runtimeCapabilityError(this.runtimeSession, "native session fork");
         return nativeOperationToPiCompatibility(this.runtimeSession, this.piboSessionId, await forkSession(entryId));
     }
     async cloneSession() {
+        this.assertSessionWorkIdle("clone");
         const cloneSession = this.runtimeSession.controls?.cloneSession;
         if (!cloneSession)
             throw runtimeCapabilityError(this.runtimeSession, "native session clone");
         return nativeOperationToPiCompatibility(this.runtimeSession, this.piboSessionId, await cloneSession());
     }
+    assertSessionIdentityOperationIdle(operation) {
+        if (this.sessionIdentityOperationInFlight) {
+            throw new Error(`Pibo session already has a session identity operation in progress; cannot ${operation}.`);
+        }
+        this.assertSessionWorkIdle(operation);
+    }
+    assertSessionWorkIdle(operation) {
+        const status = this.getStatus();
+        if (status.processing || status.streaming || status.queuedMessages > 0) {
+            throw new Error(`Pibo session must be idle to ${operation}.`);
+        }
+    }
     getSessionTree() {
         const getSessionTree = this.runtimeSession.controls?.getSessionTree;
         if (!getSessionTree)
@@ -521,7 +587,10 @@ export class RuntimeRoutedSession {
                     costUsd: event.usage.costUsd,
                     provenance: this.activeMessage?.provenance,
                 }));
-                this.trackRunReminderTurnGuard("usage", { totalTokens: event.usage.totalTokens });
+                this.trackRunReminderTurnGuard("usage", {
+                    totalTokens: event.usage.totalTokens,
+                    cacheReadTokens: event.usage.cacheReadTokens,
+                });
                 return;
             case "compaction_start":
                 this.emit(this.withActiveMessage({
@@ -605,13 +674,16 @@ export class RuntimeRoutedSession {
         }));
     }
     startDrain() {
-        if (this.drainPromise)
+        if (this.drainPromise || this.sessionIdentityOperationInFlight)
             return;
         const drain = this.drain();
         this.drainPromise = drain;
         void drain.finally(() => {
-            if (this.drainPromise === drain)
-                this.drainPromise = undefined;
+            if (this.drainPromise !== drain)
+                return;
+            this.drainPromise = undefined;
+            if (this.queue.length > 0 && !this.disposed)
+                this.startDrain();
         });
     }
     async drain() {
@@ -732,7 +804,7 @@ export class RuntimeRoutedSession {
             eventId: event.id,
             toolExecutions: 0,
             providerRounds: 0,
-            totalTokens: 0,
+            activeTokens: 0,
             toolSignatures: new Map(),
             tripped: false,
         };
@@ -755,11 +827,12 @@ export class RuntimeRoutedSession {
         if (!guard || guard.tripped || guard.eventId !== this.activeMessage?.id)
             return;
         if (type === "usage") {
-            const totalTokens = payload.totalTokens ?? 0;
-            guard.totalTokens += totalTokens;
+            const usage = payload;
+            const activeTokens = Math.max(0, (usage.totalTokens ?? 0) - (usage.cacheReadTokens ?? 0));
+            guard.activeTokens += activeTokens;
             guard.providerRounds += 1;
-            if (guard.totalTokens > RUN_REMINDER_MAX_TOTAL_TOKENS) {
-                this.tripRunReminderTurnGuard(guard, `exceeded ${RUN_REMINDER_MAX_TOTAL_TOKENS} total tokens`);
+            if (guard.activeTokens > RUN_REMINDER_MAX_ACTIVE_TOKENS) {
+                this.tripRunReminderTurnGuard(guard, `exceeded ${RUN_REMINDER_MAX_ACTIVE_TOKENS} active tokens`);
                 return;
             }
             if (guard.providerRounds > RUN_REMINDER_MAX_PROVIDER_ROUNDS) {
@@ -1007,6 +1080,7 @@ export class RuntimeRoutedSession {
             processing: this.processing,
             queuedMessages: this.queue.length,
             disposed: this.disposed,
+            sessionIdentityOperationInFlight: this.sessionIdentityOperationInFlight,
         });
     }
     resetContentIndices() {