p-spore 0.1.4 → 0.1.42

package/dist/pi/pi-runtime-adapter.js

@@ -1,7 +1,14 @@
-import { mkdir, realpath } from "node:fs/promises";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createSyntheticSourceInfo, ModelRuntime, SessionManager, SettingsManager, estimateTokens, findCutPoint, getLatestCompactionEntry, sessionEntryToContextMessages, } from "@earendil-works/pi-coding-agent";
+import { articleDraftFromToolUpdate, articleDraftFromUpdate } from "../articles/draft.js";
+import { ArticlePreviewBus } from "../articles/preview.js";
+import { publishedArticleValue } from "../articles/publish.js";
+import { resolveSessionFile } from "../sessions/session-file.js";
+import { toolInputText } from "../ui/shared/activity.js";
+import { boundToolResult, estimateTextTokens } from "./context-budget.js";
+const CONTEXT_RESUME_MESSAGE = "pspore-context-resume";
 export class PiRuntimeAdapter {
     #agentDir;
     #sessionRoot;
@@ -9,9 +16,12 @@ export class PiRuntimeAdapter {
     #resolveModel;
     #createTools;
     #createSkillPaths;
+    #createSkills;
     #toolGate;
     #clock;
     #idFactory;
+    #autoCompaction;
+    #articlePreviews = new ArticlePreviewBus((draft) => this.#publishArticleDraft(draft), () => this.#clock().getTime());
     #sessions = new Map();
     constructor(options, modelRuntime) {
         this.#agentDir = options.agentDir;
@@ -22,9 +32,11 @@ export class PiRuntimeAdapter {
                 ((ref, runtime) => (ref ? runtime.getModel(ref.provider, ref.model) : undefined));
         this.#createTools = options.createTools ?? (() => []);
         this.#createSkillPaths = options.createSkillPaths ?? (() => []);
+        this.#createSkills = options.createSkills ?? (() => []);
         this.#toolGate = options.toolGate;
         this.#clock = options.clock ?? (() => new Date());
         this.#idFactory = options.idFactory ?? randomUUID;
+        this.#autoCompaction = options.autoCompaction ? { ...options.autoCompaction } : undefined;
     }
     static async create(options) {
         await mkdir(options.agentDir, { recursive: true, mode: 0o700 });
@@ -37,6 +49,9 @@ export class PiRuntimeAdapter {
             }));
         return new PiRuntimeAdapter(options, modelRuntime);
     }
+    articlePreview(toolCallId) {
+        return this.#articlePreviews.get(toolCallId);
+    }
     async create(spec) {
         this.#assertNewSession(spec.sessionId);
         const normalized = await this.#normalizeSpec(spec);
@@ -48,7 +63,7 @@ export class PiRuntimeAdapter {
     async resume(spec) {
         this.#assertNewSession(spec.sessionId);
         const normalized = await this.#normalizeSpec(spec);
-        const sessionFile = await realpath(spec.sessionFile);
+        const sessionFile = await resolveSessionFile(spec.sessionFile, { allowMissing: true });
         const sessionDir = join(this.#sessionRoot, normalized.workspaceId);
         await mkdir(sessionDir, { recursive: true, mode: 0o700 });
         const sessionManager = SessionManager.open(sessionFile, sessionDir, normalized.cwd);
@@ -56,12 +71,14 @@ export class PiRuntimeAdapter {
     }
     async prompt(sessionId, input) {
         const record = this.#record(sessionId);
-        if (record.runtime.session.isStreaming) {
+        if (record.runtime.session.isStreaming || record.activeTask) {
             throw new Error(`Session ${sessionId} is busy; use steer or followUp`);
         }
         if (!input.trim()) {
             throw new Error("Prompt cannot be empty");
         }
+        record.abortRequested = false;
+        record.lastError = undefined;
         const commandId = this.#idFactory();
         let resolveAccepted;
         let rejectAccepted;
@@ -69,19 +86,74 @@ export class PiRuntimeAdapter {
             resolveAccepted = resolve;
             rejectAccepted = reject;
         });
-        const task = record.runtime.session
-            .prompt(input, {
-            source: "rpc",
-            preflightResult: (success) => {
-                if (success) {
-                    resolveAccepted({ accepted: true, commandId, acceptedAt: this.#clock().toISOString() });
+        // Own the logical task before any asynchronous compaction. Otherwise a
+        // restored session blocks prompt acceptance (and the serialized abort
+        // command behind it) for the entire summarization request.
+        const task = Promise.resolve()
+            .then(async () => {
+            if (this.#needsThresholdCompaction(record)) {
+                this.#startRun(record);
+                resolveAccepted({ accepted: true, commandId, acceptedAt: this.#clock().toISOString() });
+            }
+            await this.#compactAtConfiguredThreshold(record);
+            if (record.abortRequested) {
+                rejectAccepted(new Error("Prompt cancelled during context compaction"));
+                return;
+            }
+            await record.runtime.session.prompt(input, {
+                source: "rpc",
+                preflightResult: (success) => {
+                    if (success)
+                        resolveAccepted({ accepted: true, commandId, acceptedAt: this.#clock().toISOString() });
+                    else
+                        rejectAccepted(new Error("Pi rejected the prompt during preflight"));
+                },
+            });
+            while (!record.abortRequested) {
+                const resumeTask = record.compactionPending;
+                await this.#compactAtConfiguredThreshold(record);
+                if (record.abortRequested)
+                    break;
+                await this.#restoreHeldQueue(record);
+                record.compactionPending = false;
+                if (resumeTask) {
+                    await record.runtime.session.sendCustomMessage({
+                        customType: CONTEXT_RESUME_MESSAGE,
+                        content: "Continue the original user task after context compaction. Use the summary and retained tool results; do not repeat completed actions.",
+                        display: false,
+                    }, { triggerTurn: true });
                 }
                 else {
-                    rejectAccepted(new Error("Pi rejected the prompt during preflight"));
+                    // A message can arrive while the *final answer* is compacting too.
+                    // Start with that queued user input, rather than replying to the
+                    // already-completed original request again.
+                    const session = record.runtime.session;
+                    if (!session.pendingMessageCount)
+                        break;
+                    const queue = session.clearQueue();
+                    const nextInput = queue.steering.shift() ?? queue.followUp.shift();
+                    if (nextInput === undefined)
+                        break;
+                    for (const message of queue.steering)
+                        await session.steer(message);
+                    for (const message of queue.followUp)
+                        await session.followUp(message);
+                    await session.prompt(nextInput, { source: "rpc", expandPromptTemplates: false });
                 }
-            },
+            }
+            if (record.compactionPending) {
+                await this.#restoreHeldQueue(record);
+                record.compactionPending = false;
+            }
         })
-            .catch((error) => {
+            .catch(async (error) => {
+            await this.#restoreHeldQueue(record);
+            if (record.abortRequested) {
+                record.compactionPending = false;
+                rejectAccepted(new Error("Prompt cancelled during context compaction"));
+                return;
+            }
+            record.compactionPending = false;
             const normalizedError = toError(error);
             record.lastError = normalizedError.message;
             this.#emit(record, "runtime.error", { message: normalizedError.message }, false);
@@ -91,6 +163,9 @@ export class PiRuntimeAdapter {
             .finally(() => {
             if (record.activeTask === task) {
                 record.activeTask = undefined;
+                record.runStarted = false;
+                if (!record.lastError)
+                    this.#emit(record, "run.settled", {}, false);
             }
         });
         record.activeTask = task;
@@ -99,18 +174,57 @@ export class PiRuntimeAdapter {
     }
     async steer(sessionId, input) {
         const record = this.#record(sessionId);
+        if (record.compactionPending) {
+            record.heldQueue.steering.push(input);
+            this.#publishQueue(record);
+            return this.#accepted();
+        }
         await record.runtime.session.steer(input);
         return this.#accepted();
     }
     async followUp(sessionId, input) {
         const record = this.#record(sessionId);
+        if (record.compactionPending) {
+            record.heldQueue.followUp.push(input);
+            this.#publishQueue(record);
+            return this.#accepted();
+        }
         await record.runtime.session.followUp(input);
         return this.#accepted();
     }
+    async promoteFollowUp(sessionId, index) {
+        const record = this.#record(sessionId);
+        if (!Number.isSafeInteger(index) || index < 0 || index >= record.queue.followUp.length) {
+            throw new Error(`Follow-up queue index is out of range: ${index}`);
+        }
+        const selected = record.queue.followUp[index];
+        if (selected === undefined)
+            throw new Error(`Follow-up queue entry is unavailable: ${index}`);
+        if (record.compactionPending) {
+            record.heldQueue.followUp.splice(index, 1);
+            record.heldQueue.steering.push(selected);
+            this.#publishQueue(record);
+            return this.#accepted();
+        }
+        const queued = record.runtime.session.clearQueue();
+        for (const message of queued.steering)
+            await record.runtime.session.steer(message);
+        await record.runtime.session.steer(selected);
+        for (const [queuedIndex, message] of queued.followUp.entries()) {
+            if (queuedIndex !== index)
+                await record.runtime.session.followUp(message);
+        }
+        return this.#accepted();
+    }
     async abort(sessionId, _reason) {
-        await this.#record(sessionId).runtime.session.abort();
+        const record = this.#record(sessionId);
+        record.abortRequested = true;
+        record.runtime.session.abortCompaction();
+        await record.runtime.session.abort();
+        await record.activeTask?.catch(() => undefined);
     }
     async compact(sessionId, instructions) {
+        await this.abort(sessionId, "manual compaction");
         const session = this.#record(sessionId).runtime.session;
         if (instructions === undefined) {
             await session.compact();
@@ -126,23 +240,21 @@ export class PiRuntimeAdapter {
         const model = session.model;
         const sessionFile = session.sessionFile;
         const lastError = record.lastError;
+        // Counting entries walks the branch but renders no text, so session state
+        // stays cheap no matter how long the conversation has grown.
+        const entries = this.#branchEntries(record);
+        const firstUserText = this.#firstUserText(record, entries);
         return {
             sessionId,
             upstreamSessionId: session.sessionId,
             ...(sessionFile ? { sessionFile } : {}),
             cwd: record.runtime.cwd,
-            status: lastError ? "failed" : session.isStreaming ? "running" : "idle",
+            status: lastError ? "failed" : session.isStreaming || record.activeTask || record.thresholdCompaction ? "running" : "idle",
             ...(model ? { model: { provider: model.provider, model: model.id } } : {}),
             thinking: session.thinkingLevel,
-            messages: session.messages.map(toRuntimeMessage),
-            entries: session.sessionManager
-                .getBranch()
-                .filter((entry) => entry.type === "message")
-                .map((entry) => ({
-                id: entry.id,
-                role: entry.message.role,
-                text: messageText(entry.message),
-            })),
+            ...(session.model ? { context: this.#contextUsage(record) } : {}),
+            messageCount: entries.length,
+            ...(firstUserText === undefined ? {} : { firstUserText }),
             queue: {
                 steering: [...record.queue.steering],
                 followUp: [...record.queue.followUp],
@@ -187,6 +299,72 @@ export class PiRuntimeAdapter {
         }
         return this.#handle(record);
     }
+    /**
+     * A slice of the persisted branch, which keeps entries a compaction has
+     * already dropped from the model's context. Only the requested slice is
+     * rendered to text: doing that for the whole branch is what made every
+     * streamed token cost as much as the conversation was long.
+     */
+    transcript(sessionId, options) {
+        const record = this.#record(sessionId);
+        const entries = this.#branchEntries(record);
+        const limit = Math.max(0, options.limit);
+        const from = Math.min(Math.max(0, options.from ?? Math.max(0, entries.length - limit)), entries.length);
+        return {
+            from,
+            count: entries.length,
+            messages: entries.slice(from, from + limit).map(toBranchMessage),
+        };
+    }
+    /**
+     * One message's full text, sliced. The transcript on the wire is bounded per
+     * string, so a message longer than that ceiling arrives cut; this is how a
+     * client asks for the rest of it without widening the ceiling for everything.
+     */
+    transcriptMessage(sessionId, options) {
+        const record = this.#record(sessionId);
+        const entries = this.#branchEntries(record);
+        const index = options.id === undefined
+            ? options.index ?? -1
+            : entries.findIndex((entry) => entry.id === options.id);
+        const entry = index >= 0 ? entries[index] : undefined;
+        if (!entry) {
+            throw new Error(`Transcript message is unavailable: ${options.id ?? String(options.index)}`);
+        }
+        const message = toBranchMessage(entry);
+        const offset = Math.min(Math.max(0, options.offset ?? 0), message.text.length);
+        return {
+            ...(message.id === undefined ? {} : { id: message.id }),
+            index,
+            role: message.role,
+            offset,
+            length: message.text.length,
+            text: message.text.slice(offset, offset + Math.max(0, options.limit)),
+        };
+    }
+    /** The persisted branch's message entries, unrendered. */
+    branch(sessionId) {
+        return this.#branchEntries(this.#record(sessionId)).map(toBranchMessage);
+    }
+    #branchEntries(record) {
+        return record.runtime.session.sessionManager
+            .getBranch()
+            .filter((entry) => entry.type === "message");
+    }
+    #firstUserText(record, entries) {
+        if (record.firstUserText !== undefined)
+            return record.firstUserText || undefined;
+        const first = entries.find((entry) => asRecord(entry.message)["role"] === "user");
+        // Nothing is cached until a user message exists: a session snapshotted at
+        // creation has none yet, and caching that absence would leave it untitled
+        // for the rest of its life.
+        if (!first)
+            return undefined;
+        // Only ever used as a session title, so it never needs the whole message.
+        const text = messageText(first.message).trim().slice(0, 200);
+        record.firstUserText = text;
+        return text || undefined;
+    }
     async fork(sessionId, entryId, position = "at") {
         const record = this.#record(sessionId);
         const result = await record.runtime.fork(entryId, { position });
@@ -197,6 +375,8 @@ export class PiRuntimeAdapter {
     }
     async dispose(sessionId) {
         const record = this.#record(sessionId);
+        await this.abort(sessionId, "session disposed");
+        this.#articlePreviews.clearSession(sessionId);
         record.unsubscribe?.();
         record.listeners.clear();
         await record.runtime.dispose();
@@ -212,6 +392,7 @@ export class PiRuntimeAdapter {
             agentDir: this.#agentDir,
             sessionManager,
         });
+        await this.#materializeSessionManager(runtime.session.sessionManager);
         const record = {
             spec,
             runtime,
@@ -219,22 +400,61 @@ export class PiRuntimeAdapter {
             listeners: new Set(),
             activeTask: undefined,
             queue: { steering: [], followUp: [] },
+            thresholdCompaction: false,
+            compactionPending: false,
+            runStarted: false,
+            abortRequested: false,
+            heldQueue: { steering: [], followUp: [] },
             lastError: undefined,
+            streaming: undefined,
+            itemSequence: 0,
+            firstUserText: undefined,
         };
         this.#sessions.set(spec.sessionId, record);
         this.#bind(record, runtime.session, false);
-        runtime.setRebindSession(async (session) => this.#bind(record, session, true));
+        runtime.setRebindSession(async (session) => {
+            await this.#materializeSessionManager(session.sessionManager);
+            this.#bind(record, session, true);
+        });
         return this.#handle(record);
     }
+    async #materializeSessionManager(sessionManager) {
+        const sessionFile = sessionManager.getSessionFile();
+        if (!sessionFile)
+            return;
+        const contents = [sessionManager.getHeader(), ...sessionManager.getEntries()]
+            .map((entry) => JSON.stringify(entry))
+            .join("\n") + "\n";
+        try {
+            await writeFile(sessionFile, contents, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "EEXIST")
+                throw error;
+        }
+        sessionManager.setSessionFile(await resolveSessionFile(sessionFile));
+    }
     #runtimeFactory(spec) {
         return async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
             const policyExtension = this.#policyExtension(spec);
             const contextFiles = spec.contextFiles ? [...spec.contextFiles] : [];
             const skillPaths = [...await this.#createSkillPaths(spec.sessionId)].sort();
+            const resolvedSkills = [...await this.#createSkills(spec.sessionId)];
             const extensionFactories = policyExtension ? [policyExtension] : [];
             const services = await createAgentSessionServices({
                 cwd,
                 agentDir,
+                ...(this.#autoCompaction
+                    ? {
+                        settingsManager: SettingsManager.inMemory({
+                            compaction: {
+                                enabled: this.#autoCompaction.enabled,
+                                reserveTokens: this.#autoCompaction.reserveTokens,
+                                keepRecentTokens: this.#autoCompaction.keepRecentTokens,
+                            },
+                        }),
+                    }
+                    : {}),
                 modelRuntime: this.#modelRuntime,
                 resourceLoaderOptions: {
                     noExtensions: true,
@@ -243,6 +463,9 @@ export class PiRuntimeAdapter {
                     noThemes: true,
                     noContextFiles: true,
                     ...(skillPaths.length > 0 ? { additionalSkillPaths: skillPaths } : {}),
+                    ...(resolvedSkills.length > 0
+                        ? { skillsOverride: (base) => withResolvedSkills(base, resolvedSkills) }
+                        : {}),
                     ...(spec.systemPrompt ? { systemPrompt: spec.systemPrompt } : {}),
                     ...(extensionFactories.length > 0 ? { extensionFactories } : {}),
                     ...(contextFiles.length > 0
@@ -258,7 +481,13 @@ export class PiRuntimeAdapter {
             if (spec.model && !model) {
                 throw new Error(`Configured model is unavailable: ${spec.model.provider}/${spec.model.model}`);
             }
-            const customTools = [...this.#createTools(spec.sessionId)];
+            const customTools = this.#createTools(spec.sessionId, this.#modelRuntime).map((tool) => ({
+                ...tool,
+                execute: async (...args) => {
+                    const result = await tool.execute(...args);
+                    return { ...result, content: await boundToolResult(result.content, join(this.#sessionRoot, "artifacts", "tool-results")) };
+                },
+            }));
             const enabledTools = spec.enabledTools ? [...spec.enabledTools] : customTools.map((tool) => tool.name);
             const result = await createAgentSessionFromServices({
                 services,
@@ -321,6 +550,25 @@ export class PiRuntimeAdapter {
         record.upstreamSessionId = session.sessionId;
         record.lastError = undefined;
         record.queue = { steering: [], followUp: [] };
+        record.streaming = undefined;
+        record.firstUserText = undefined;
+        const previousStop = session.agent.shouldStopAfterTurn;
+        session.agent.shouldStopAfterTurn = async (turn, signal) => {
+            if (await previousStop?.(turn, signal))
+                return true;
+            if (signal?.aborted || record.abortRequested || !this.#autoCompaction?.enabled)
+                return false;
+            if (turn.toolResults.length === 0 && session.pendingMessageCount === 0)
+                return false;
+            if (this.#contextUsage(record).tokens < this.#compactionThreshold(record))
+                return false;
+            record.compactionPending = true;
+            // Pi drains queues at agent_end, so hold them outside the SDK until the
+            // context has been compacted. New user messages join this same queue.
+            record.heldQueue = { steering: [...session.getSteeringMessages()], followUp: [...session.getFollowUpMessages()] };
+            session.clearQueue();
+            return true;
+        };
         record.unsubscribe = session.subscribe((event) => this.#onPiEvent(record, event));
         if (replacement) {
             this.#emit(record, "session.replaced", { previousUpstreamSessionId, upstreamSessionId: session.sessionId }, false);
@@ -329,50 +577,88 @@ export class PiRuntimeAdapter {
     #onPiEvent(record, event) {
         switch (event.type) {
             case "agent_start":
-                this.#emit(record, "run.started", {}, false);
+                this.#startRun(record);
                 break;
             case "agent_settled":
-                this.#emit(record, "run.settled", {}, false);
+                this.#articlePreviews.clearSession(record.spec.sessionId);
+                // The adapter's logical task also includes automatic compaction and
+                // continuation. Publish settled only when that entire task finishes.
+                if (!record.activeTask)
+                    this.#emit(record, "run.settled", {}, false);
                 break;
-            case "message_start":
-                this.#emit(record, "message.started", messagePayload(event.message), false);
+            case "message_start": {
+                if (asRecord(event.message)["customType"] === CONTEXT_RESUME_MESSAGE)
+                    break;
+                const streaming = this.#beginItem(record, event.message);
+                this.#emit(record, "transcript.item.started", { item: this.#startedItem(streaming) }, false);
                 break;
+            }
             case "message_update": {
                 const update = event.assistantMessageEvent;
-                if (update.type === "text_delta") {
-                    this.#emit(record, "message.delta", { delta: update.delta }, true);
-                }
-                else if (update.type === "thinking_delta") {
-                    this.#emit(record, "message.thinking.delta", { delta: update.delta }, true);
+                if (update.type === "toolcall_delta" || update.type === "toolcall_end") {
+                    this.#noteArticleDraft(record, event.message, update);
                 }
+                if (update.type !== "text_delta" && update.type !== "thinking_delta")
+                    break;
+                const kind = update.type === "text_delta" ? "text" : "thinking";
+                // A delta with no started item would have nowhere to land; opening one
+                // keeps the stream addressable even if Pi skips the start event.
+                const streaming = record.streaming ?? this.#beginItem(record, event.message);
+                if (kind === "text")
+                    streaming.text += update.delta;
+                else
+                    streaming.thinking += update.delta;
+                this.#emit(record, "transcript.delta", { itemId: streaming.id, kind, delta: update.delta }, true);
                 break;
             }
-            case "message_end":
-                this.#emit(record, "message.completed", messagePayload(event.message), false);
+            case "message_end": {
+                if (asRecord(event.message)["customType"] === CONTEXT_RESUME_MESSAGE)
+                    break;
+                const item = this.#finishItem(record, event.message);
+                this.#emit(record, "transcript.item.finished", { item }, false);
                 break;
+            }
             case "tool_execution_start":
-                this.#emit(record, "tool.started", { toolCallId: event.toolCallId, toolName: event.toolName, input: event.args }, false);
+                this.#emit(record, "tool.started", {
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    input: publishedArticleValue(event.toolName, event.args),
+                }, false);
                 break;
-            case "tool_execution_update":
-                this.#emit(record, "tool.updated", { toolCallId: event.toolCallId, toolName: event.toolName, partialResult: event.partialResult }, true);
+            case "tool_execution_update": {
+                if (event.toolName === "article") {
+                    const draft = articleDraftFromToolUpdate(record.spec.sessionId, event.toolCallId, event.partialResult);
+                    if (draft) {
+                        this.#articlePreviews.note(draft, this.#clock().getTime());
+                        break;
+                    }
+                }
+                this.#emit(record, "tool.updated", { toolCallId: event.toolCallId, toolName: event.toolName, partialResult: publishedArticleValue(event.toolName, event.partialResult) }, true);
                 break;
+            }
             case "tool_execution_end":
+                this.#articlePreviews.clear(event.toolCallId);
                 this.#emit(record, "tool.completed", {
                     toolCallId: event.toolCallId,
                     toolName: event.toolName,
                     isError: event.isError,
-                    result: event.result,
+                    result: publishedArticleValue(event.toolName, event.result),
                 }, false);
                 break;
             case "queue_update":
-                record.queue = { steering: [...event.steering], followUp: [...event.followUp] };
-                this.#emit(record, "queue.updated", record.queue, false);
+                this.#publishQueue(record);
                 break;
             case "compaction_start":
-                this.#emit(record, "compaction.started", { reason: event.reason }, false);
+                this.#emit(record, "compaction.started", { reason: record.thresholdCompaction && event.reason === "manual" ? "token_threshold" : event.reason }, false);
                 break;
             case "compaction_end":
-                this.#emit(record, "compaction.completed", { reason: event.reason, aborted: event.aborted, willRetry: event.willRetry }, false);
+                this.#emit(record, "compaction.completed", {
+                    reason: record.thresholdCompaction && event.reason === "manual" ? "token_threshold" : event.reason,
+                    aborted: event.aborted,
+                    willRetry: event.willRetry,
+                    ...(event.errorMessage ? { errorMessage: event.errorMessage } : {}),
+                    ...(event.result ? { tokensBefore: event.result.tokensBefore, tokensAfter: event.result.estimatedTokensAfter } : {}),
+                }, false);
                 break;
             case "auto_retry_start":
                 this.#emit(record, "retry.started", { attempt: event.attempt, maxAttempts: event.maxAttempts, delayMs: event.delayMs }, false);
@@ -384,6 +670,60 @@ export class PiRuntimeAdapter {
                 break;
         }
     }
+    #beginItem(record, message) {
+        const candidate = asRecord(message);
+        const streaming = {
+            id: `${record.upstreamSessionId}:${++record.itemSequence}`,
+            role: typeof candidate["role"] === "string" ? candidate["role"] : "assistant",
+            text: messageText(message),
+            thinking: "",
+            startedAt: this.#clock().toISOString(),
+        };
+        record.streaming = streaming;
+        return streaming;
+    }
+    /**
+     * The item a `transcript.item.started` event announces. It is the same shape
+     * a finished item has — clients and the desktop's frame validator both read a
+     * `TranscriptItem` — only still open, so the status is `streaming`.
+     */
+    #startedItem(streaming) {
+        return {
+            id: streaming.id,
+            role: streaming.role,
+            text: streaming.text,
+            ...(streaming.thinking ? { thinking: streaming.thinking } : {}),
+            status: "streaming",
+            ts: streaming.startedAt,
+        };
+    }
+    #finishItem(record, message) {
+        const streaming = record.streaming ?? this.#beginItem(record, message);
+        record.streaming = undefined;
+        return {
+            ...toRuntimeMessage(message),
+            id: streaming.id,
+            status: "complete",
+            ts: streaming.startedAt,
+        };
+    }
+    #noteArticleDraft(record, message, update) {
+        const draft = articleDraftFromUpdate(record.spec.sessionId, update, message);
+        if (!draft)
+            return;
+        this.#articlePreviews.note(draft, this.#clock().getTime());
+    }
+    #publishArticleDraft(draft) {
+        const record = this.#sessions.get(draft.sessionId);
+        if (!record)
+            return;
+        this.#emit(record, "article.preview", {
+            toolCallId: draft.toolCallId,
+            ...(draft.title === undefined ? {} : { title: draft.title }),
+            ...(draft.articleId === undefined ? {} : { articleId: draft.articleId }),
+            chars: draft.content?.length ?? 0,
+        }, true);
+    }
     #emit(record, type, payload, transient) {
         const event = {
             id: this.#idFactory(),
@@ -425,6 +765,107 @@ export class PiRuntimeAdapter {
     #accepted() {
         return { accepted: true, commandId: this.#idFactory(), acceptedAt: this.#clock().toISOString() };
     }
+    #startRun(record) {
+        if (record.runStarted)
+            return;
+        record.runStarted = true;
+        this.#emit(record, "run.started", {}, false);
+    }
+    #needsThresholdCompaction(record) {
+        const settings = this.#autoCompaction;
+        if (!settings?.enabled)
+            return false;
+        const session = record.runtime.session;
+        if (record.abortRequested || session.messages.length === 0)
+            return false;
+        // A just-compacted leaf cannot be compacted again without new work.
+        if (session.sessionManager.getBranch().at(-1)?.type === "compaction")
+            return false;
+        return this.#contextUsage(record).tokens >= this.#compactionThreshold(record);
+    }
+    async #compactAtConfiguredThreshold(record) {
+        if (!this.#needsThresholdCompaction(record))
+            return;
+        const session = record.runtime.session;
+        if (session.messages.at(-1)?.role === "toolResult") {
+            // Pi never cuts at a tool result. Add an invisible, user-like boundary
+            // after the completed batch so even the first long task can be compacted.
+            await session.sendCustomMessage({
+                customType: CONTEXT_RESUME_MESSAGE,
+                content: "The tool batch above has finished. Preserve the original user request, completed actions, evidence and remaining work in the context summary.",
+                display: false,
+            });
+        }
+        // Pi deliberately keeps whole recent messages. A single large retained
+        // answer can still exceed our threshold, yet leave nothing new to summarize.
+        // Use its public cut-point rules to avoid reporting that normal no-op as a
+        // failed task ("Nothing to compact").
+        const entries = session.sessionManager.getBranch();
+        const previous = getLatestCompactionEntry(entries);
+        const start = previous ? Math.max(0, entries.findIndex((entry) => entry.id === previous.firstKeptEntryId)) : 0;
+        const cut = findCutPoint(entries, start, entries.length, session.settingsManager.getCompactionSettings().keepRecentTokens);
+        if (!entries.slice(start, cut.firstKeptEntryIndex).some((entry) => entry.type !== "compaction" && sessionEntryToContextMessages(entry).length > 0))
+            return;
+        record.thresholdCompaction = true;
+        try {
+            await record.runtime.session.compact();
+        }
+        finally {
+            record.thresholdCompaction = false;
+        }
+    }
+    #compactionThreshold(record) {
+        const settings = this.#autoCompaction;
+        if (!settings)
+            return Number.POSITIVE_INFINITY;
+        const limit = record.runtime.session.model?.contextWindow ?? Number.POSITIVE_INFINITY;
+        return Math.max(1, Math.min(settings.triggerTokens, limit - settings.reserveTokens));
+    }
+    #publishQueue(record) {
+        record.queue = {
+            steering: [...record.runtime.session.getSteeringMessages(), ...record.heldQueue.steering],
+            followUp: [...record.runtime.session.getFollowUpMessages(), ...record.heldQueue.followUp],
+        };
+        this.#emit(record, "queue.updated", record.queue, false);
+    }
+    async #restoreHeldQueue(record) {
+        while (record.heldQueue.steering.length || record.heldQueue.followUp.length) {
+            const queue = record.heldQueue;
+            record.heldQueue = { steering: [], followUp: [] };
+            for (const message of queue.steering)
+                await record.runtime.session.steer(message);
+            for (const message of queue.followUp)
+                await record.runtime.session.followUp(message);
+        }
+    }
+    #contextUsage(record) {
+        const session = record.runtime.session;
+        const usage = session.getContextUsage();
+        let tokens = usage?.tokens;
+        const lastUsageIndex = session.messages.findLastIndex((message) => message.role === "assistant"
+            && message.stopReason !== "error" && message.stopReason !== "aborted"
+            && (message.usage.input + message.usage.output + message.usage.cacheRead + message.usage.cacheWrite) > 0);
+        if (tokens === undefined || tokens === null || lastUsageIndex < 0) {
+            tokens = estimateTextTokens(session.systemPrompt)
+                + estimateTextTokens(JSON.stringify(session.agent.state.tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }))));
+            for (const message of session.messages) {
+                tokens += estimateMessageTokens(message);
+            }
+        }
+        else {
+            // Pi estimates messages after the latest measured usage as chars / 4.
+            // Correct only that unmeasured tail; never add the entire history again.
+            for (const message of session.messages.slice(lastUsageIndex + 1)) {
+                tokens += estimateMessageTokens(message) - estimateTokens(message);
+            }
+        }
+        return {
+            tokens,
+            window: usage?.contextWindow ?? session.model?.contextWindow ?? 0,
+            estimated: true,
+            ...(this.#autoCompaction?.enabled ? { triggerTokens: this.#compactionThreshold(record) } : {}),
+        };
+    }
     #handle(record) {
         const sessionFile = record.runtime.session.sessionFile;
         return {
@@ -434,19 +875,73 @@ export class PiRuntimeAdapter {
         };
     }
 }
+/**
+ * Adds skills resolved outside Pi to what Pi loaded from paths. A name Pi
+ * already has keeps its skill — the same first-wins rule Pi applies among its
+ * own paths — and the loser is reported the way Pi reports a collision.
+ */
+function withResolvedSkills(base, resolved) {
+    const skills = [...base.skills];
+    const diagnostics = [...base.diagnostics];
+    for (const skill of resolved) {
+        const winner = skills.find((candidate) => candidate.name === skill.name);
+        if (winner) {
+            diagnostics.push({
+                type: "collision",
+                message: `name "${skill.name}" collision`,
+                path: skill.filePath,
+                collision: { resourceType: "skill", name: skill.name, winnerPath: winner.filePath, loserPath: skill.filePath },
+            });
+            continue;
+        }
+        skills.push({
+            ...skill,
+            sourceInfo: createSyntheticSourceInfo(skill.filePath, { source: "local", scope: "user", baseDir: skill.baseDir }),
+        });
+    }
+    return { skills, diagnostics };
+}
+function toBranchMessage(entry) {
+    return { id: entry.id, ...toRuntimeMessage(entry.message) };
+}
 function toRuntimeMessage(message) {
     const candidate = asRecord(message);
+    const content = Array.isArray(candidate["content"]) ? candidate["content"].map(asRecord) : [];
+    const thinking = content.filter((block) => block["type"] === "thinking" && typeof block["thinking"] === "string")
+        .map((block) => block["thinking"]).join("\n");
+    const toolCalls = content.flatMap((block) => {
+        if (block["type"] !== "toolCall" || typeof block["id"] !== "string" || typeof block["name"] !== "string")
+            return [];
+        return [{ id: block["id"], name: block["name"], input: toolInputText(publishedArticleValue(block["name"], block["arguments"] ?? {})) }];
+    });
     return {
         role: typeof candidate["role"] === "string" ? candidate["role"] : "unknown",
         text: messageText(message),
+        ...(thinking ? { thinking } : {}),
+        ...(toolCalls.length ? { toolCalls } : {}),
+        ...(typeof candidate["toolCallId"] === "string" ? { toolCallId: candidate["toolCallId"] } : {}),
+        ...(typeof candidate["toolName"] === "string" ? { toolName: candidate["toolName"] } : {}),
+        ...(typeof candidate["isError"] === "boolean" ? { isError: candidate["isError"] } : {}),
     };
 }
-function messagePayload(message) {
-    const candidate = asRecord(message);
-    return {
-        role: typeof candidate["role"] === "string" ? candidate["role"] : "unknown",
-        text: messageText(message),
-    };
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function estimateMessageTokens(message) {
+    let prose = messageText(message);
+    if (message.role === "compactionSummary" || message.role === "branchSummary")
+        prose += message.summary;
+    if (message.role === "bashExecution")
+        prose += message.output;
+    if (message.role === "assistant") {
+        for (const block of message.content) {
+            if (block.type === "thinking")
+                prose += block.thinking;
+            if (block.type === "toolCall")
+                prose += block.name + JSON.stringify(block.arguments);
+        }
+    }
+    return Math.max(estimateTokens(message), estimateTextTokens(prose));
 }
 function messageText(message) {
     const candidate = asRecord(message);
@@ -463,12 +958,12 @@ function messageText(message) {
     return content
         .map((block) => {
         const value = asRecord(block);
-        if (typeof value["text"] === "string")
+        // Tool calls and hidden reasoning have dedicated runtime events. Mixing
+        // synthetic markers into assistant prose leaks strings such as
+        // `[tool:shell]` into Markdown and persisted history.
+        if ((value["type"] === undefined || value["type"] === "text") && typeof value["text"] === "string") {
             return value["text"];
-        if (typeof value["thinking"] === "string")
-            return value["thinking"];
-        if (value["type"] === "toolCall" && typeof value["name"] === "string")
-            return `[tool:${value["name"]}]`;
+        }
         return "";
     })
         .filter(Boolean)