@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/dist/plugins/session-bridge.js

@@ -1,32 +1,91 @@
+import { createHash } from "node:crypto";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
+import { EmptyConfig } from "../config.js";
 const bridgeVersion = 1;
 const maxMessages = 100;
 const maxMessageChars = 16_000;
 const maxTotalChars = 64_000;
+const maxContentParts = 1_000;
+const maxAttachments = 100;
+const maxSessionIdChars = 256;
+const maxCwdChars = 4_096;
+const maxModelFieldChars = 256;
+const maxMimeTypeChars = 128;
+const maxPackageBytes = 256 * 1024;
+const maxPackageChars = 256 * 1024;
+const maxAttachmentMarkerChars = 256;
+const maxDuplicateScanEntries = 10_000;
+const maxOperationErrorChars = 2_000;
 const bridgeType = "pi-harness/session-bridge";
 const roles = new Set(["user", "assistant", "toolResult", "system", "other"]);
+const emptyParameterNames = new Set();
+const previewParameterNames = new Set(["package"]);
+const importParameterNames = new Set(["package", "confirm"]);
+function cloneSource(source) {
+    return { sessionId: source.sessionId, cwd: source.cwd, ...(source.model === undefined ? {} : { model: { ...source.model } }) };
+}
+function contentPart(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Object.values(descriptors).some((descriptor) => !("value" in descriptor)))
+        return undefined;
+    return {
+        type: descriptors.type?.value,
+        text: descriptors.text?.value,
+        mimeType: descriptors.mimeType?.value,
+    };
+}
+function mimeType(value) {
+    if (typeof value !== "string" || value.length > maxMimeTypeChars)
+        return "image/unknown";
+    const normalized = value.trim();
+    return /^[a-z0-9][a-z0-9!#$&^_.+-]{0,63}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,63}$/iu.test(normalized) ? normalized : "image/unknown";
+}
 function textContent(content) {
     if (typeof content === "string")
-        return { text: content, imageTypes: [] };
+        return { text: content.slice(0, maxMessageChars), imageTypes: [] };
     if (!Array.isArray(content))
         return { text: "", imageTypes: [] };
     const text = [];
     const imageTypes = [];
-    for (const item of content) {
-        if (item === null || typeof item !== "object")
+    let textChars = 0;
+    for (const item of content.slice(0, maxContentParts)) {
+        const value = contentPart(item);
+        if (value === undefined)
             continue;
-        const value = item;
-        if (value.type === "text" && typeof value.text === "string")
-            text.push(value.text);
-        if (value.type === "image")
-            imageTypes.push(typeof value.mimeType === "string" && value.mimeType.trim() !== "" ? value.mimeType : "image/unknown");
+        if (value.type === "text" && typeof value.text === "string" && textChars < maxMessageChars) {
+            const separator = text.length === 0 ? 0 : 1;
+            const retained = value.text.slice(0, Math.max(0, maxMessageChars - textChars - separator));
+            if (retained !== "") {
+                text.push(retained);
+                textChars += separator + retained.length;
+            }
+        }
+        if (value.type === "image" && imageTypes.length < maxAttachments)
+            imageTypes.push(mimeType(value.mimeType));
     }
     return { text: text.join("\n"), imageTypes };
 }
 function role(value) {
     return typeof value === "string" && roles.has(value) ? value : "other";
 }
+function dataPropertyDescriptors(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Object.values(descriptors).some((descriptor) => !("value" in descriptor)))
+        throw new Error(`${label} must use data properties`);
+    return descriptors;
+}
+function boundedSourceText(value, label, maximum) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`${label} must be a non-empty string`);
+    if (value.includes("\0"))
+        throw new Error(`${label} must not contain NUL characters`);
+    return value.slice(0, maximum);
+}
 const previewTextLimit = 1_000;
 const previewListLimit = 8;
 function boundedPreviewText(value) {
@@ -62,33 +121,142 @@ export function buildHandoffPreview(packageValue) {
     const nextStep = boundedPreviewText(userMessages.at(-1)?.text ?? "Continue from the current state after reviewing this preview.");
     return { goal, currentState, decisions, keyFiles: extractKeyFiles(packageValue.messages), nextStep };
 }
+function serializedBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function fitSerializedPackage(packageValue) {
+    if (serializedBytes(packageValue) <= maxPackageBytes)
+        return packageValue;
+    const messages = packageValue.messages.map((message) => ({ ...message, text: "" }));
+    const bounded = { ...packageValue, messages };
+    let remainingBytes = maxPackageBytes - serializedBytes(bounded);
+    if (remainingBytes < 0)
+        throw new Error("Session Bridge package metadata exceeds the serialized byte limit");
+    let exhausted = false;
+    for (let index = 0; index < messages.length && !exhausted; index += 1) {
+        const retained = [];
+        for (const character of packageValue.messages[index]?.text ?? "") {
+            const characterBytes = Buffer.byteLength(JSON.stringify(character), "utf8") - 2;
+            if (characterBytes > remainingBytes) {
+                exhausted = true;
+                break;
+            }
+            retained.push(character);
+            remainingBytes -= characterBytes;
+        }
+        const message = messages[index];
+        if (message !== undefined)
+            message.text = retained.join("");
+    }
+    if (serializedBytes(bounded) > maxPackageBytes)
+        throw new Error("Session Bridge package exceeds the serialized byte limit");
+    return bounded;
+}
 export function buildBridgePackage(source, input) {
+    const sourceDescriptors = dataPropertyDescriptors(source, "Session Bridge source");
+    const sessionId = boundedSourceText(sourceDescriptors.sessionId?.value, "Session Bridge source sessionId", maxSessionIdChars);
+    const cwd = boundedSourceText(sourceDescriptors.cwd?.value, "Session Bridge source cwd", maxCwdChars);
+    const rawModel = sourceDescriptors.model?.value;
+    let model;
+    if (rawModel !== undefined) {
+        const modelDescriptors = dataPropertyDescriptors(rawModel, "Session Bridge source model");
+        model = {
+            provider: boundedSourceText(modelDescriptors.provider?.value, "Session Bridge model provider", maxModelFieldChars),
+            modelId: boundedSourceText(modelDescriptors.modelId?.value, "Session Bridge model id", maxModelFieldChars),
+        };
+    }
     const messages = [];
     const unresolvedAttachments = [];
     let totalChars = 0;
     for (const [index, message] of input.slice(-maxMessages).entries()) {
-        const content = textContent(message.content);
+        const descriptors = message !== null && typeof message === "object" ? Object.getOwnPropertyDescriptors(message) : {};
+        const safe = Object.values(descriptors).every((descriptor) => "value" in descriptor);
+        const content = textContent(safe ? descriptors.content?.value : undefined);
         const text = content.text.slice(0, maxMessageChars);
         if (text !== "")
             totalChars += text.length;
         const boundedText = totalChars > maxTotalChars ? text.slice(0, Math.max(0, maxTotalChars - (totalChars - text.length))) : text;
-        messages.push({ role: role(message.role), text: boundedText, hasImages: content.imageTypes.length > 0 });
-        for (const type of content.imageTypes)
+        messages.push({ role: role(safe ? descriptors.role?.value : undefined), text: boundedText, hasImages: content.imageTypes.length > 0 });
+        for (const type of content.imageTypes) {
+            if (unresolvedAttachments.length === maxAttachments)
+                break;
             unresolvedAttachments.push(`message-${index + 1}:${type}`);
+        }
         if (totalChars >= maxTotalChars)
             break;
     }
-    return {
+    return fitSerializedPackage({
         version: bridgeVersion,
-        source: { sessionId: source.sessionId, cwd: source.cwd, ...(source.model === undefined ? {} : { model: { ...source.model } }) },
+        source: { sessionId, cwd, ...(model === undefined ? {} : { model }) },
         createdAt: new Date().toISOString(),
         messageCount: messages.length,
         messages,
         unresolvedAttachments,
-    };
+    });
+}
+function assertKeys(value, allowed, label) {
+    const names = new Set(allowed);
+    const unknown = Object.keys(value).filter((key) => !names.has(key));
+    if (unknown.length > 0)
+        throw new Error(`${label} contains unknown properties: ${unknown.join(", ")}`);
+}
+function requiredText(value, label, maximum) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum)
+        throw new Error(`${label} must contain 1-${maximum} characters`);
+    if (value.includes("\0"))
+        throw new Error(`${label} must not contain NUL characters`);
+    return value;
+}
+function isIsoTimestamp(value) {
+    if (typeof value !== "string" || value.length > 64)
+        return false;
+    try {
+        return new Date(value).toISOString() === value;
+    }
+    catch {
+        return false;
+    }
+}
+function parameterDescriptors(value, names) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Session Bridge parameters must be an object");
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw new Error("Session Bridge parameters must be a plain object");
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !names.has(key)))
+        throw new Error("Session Bridge parameters contain an unknown property");
+    if (Object.values(descriptors).some((descriptor) => !("value" in descriptor)))
+        throw new Error("Session Bridge parameters must use data properties");
+    return descriptors;
+}
+function packageParameter(value, required) {
+    if (value === undefined && !required)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error("Session Bridge package must be a non-empty string");
+    if (value.length > maxPackageChars)
+        throw new Error("Session Bridge package exceeds the character limit");
+    return value;
+}
+function throwIfCancelled(signal) {
+    if (signal.aborted)
+        throw new Error("Session Bridge operation was cancelled", { cause: signal.reason });
+}
+function boundedError(error) {
+    if (typeof error === "string")
+        return error.slice(0, maxOperationErrorChars);
+    if (error !== null && typeof error === "object") {
+        const descriptor = Object.getOwnPropertyDescriptor(error, "message");
+        if (descriptor !== undefined && "value" in descriptor && typeof descriptor.value === "string")
+            return descriptor.value.slice(0, maxOperationErrorChars);
+    }
+    return "Unknown Session Bridge error";
 }
 export function parseBridgePackage(raw) {
-    if (Buffer.byteLength(raw, "utf8") > 256 * 1024)
+    if (typeof raw !== "string")
+        throw new Error("Session bridge package must be a string");
+    if (Buffer.byteLength(raw, "utf8") > maxPackageBytes)
         throw new Error("Session bridge package exceeds the 256 KiB limit");
     let value;
     try {
@@ -100,14 +268,18 @@ export function parseBridgePackage(raw) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         throw new Error("Session bridge package must be an object");
     const packageValue = value;
+    assertKeys(packageValue, ["version", "source", "createdAt", "messageCount", "messages", "unresolvedAttachments"], "Session bridge package");
     if (packageValue.version !== bridgeVersion)
         throw new Error("Session bridge package version must be 1");
     const source = packageValue.source;
     if (source === null || typeof source !== "object" || Array.isArray(source))
         throw new Error("Session bridge package source is required");
     const sourceValue = source;
-    if (typeof sourceValue.sessionId !== "string" || typeof sourceValue.cwd !== "string")
-        throw new Error("Session bridge package source requires sessionId and cwd");
+    assertKeys(sourceValue, ["sessionId", "cwd", "model"], "Session bridge package source");
+    const sessionId = requiredText(sourceValue.sessionId, "Session bridge source sessionId", maxSessionIdChars);
+    const cwd = requiredText(sourceValue.cwd, "Session bridge source cwd", maxCwdChars);
+    if (!isIsoTimestamp(packageValue.createdAt))
+        throw new Error("Session bridge package createdAt must be an ISO timestamp");
     const messages = packageValue.messages;
     if (!Array.isArray(messages) || messages.length > maxMessages)
         throw new Error(`Session bridge package must contain 0-${maxMessages} messages`);
@@ -116,6 +288,7 @@ export function parseBridgePackage(raw) {
         if (message === null || typeof message !== "object" || Array.isArray(message))
             throw new Error(`Session bridge message ${index + 1} is invalid`);
         const item = message;
+        assertKeys(item, ["role", "text", "hasImages"], `Session bridge message ${index + 1}`);
         if (typeof item.role !== "string" ||
             !roles.has(item.role) ||
             typeof item.text !== "string" ||
@@ -127,34 +300,49 @@ export function parseBridgePackage(raw) {
             throw new Error("Session bridge message text exceeds the 64 KiB limit");
         return { role: item.role, text: item.text, hasImages: item.hasImages };
     });
+    if (!Number.isSafeInteger(packageValue.messageCount) || packageValue.messageCount !== normalized.length)
+        throw new Error("Session bridge package messageCount must match the messages array");
     const rawAttachments = packageValue.unresolvedAttachments;
-    if (!Array.isArray(rawAttachments))
-        throw new Error("Session bridge attachment markers are invalid");
-    const attachments = rawAttachments.filter((item) => typeof item === "string" && item.length <= 256);
-    if (attachments.length !== rawAttachments.length)
+    if (!Array.isArray(rawAttachments) || rawAttachments.length > maxAttachments)
         throw new Error("Session bridge attachment markers are invalid");
+    const attachments = [];
+    const seenAttachments = new Set();
+    for (const item of rawAttachments) {
+        if (typeof item !== "string" || item.length === 0 || item.length > maxAttachmentMarkerChars || seenAttachments.has(item))
+            throw new Error("Session bridge attachment markers are invalid");
+        const match = /^message-([1-9]\d{0,2}):(.+)$/u.exec(item);
+        const messageIndex = match === null ? 0 : Number(match[1]);
+        const attachmentType = match?.[2];
+        if (match === null ||
+            messageIndex > normalized.length ||
+            normalized[messageIndex - 1]?.hasImages !== true ||
+            attachmentType === undefined ||
+            mimeType(attachmentType) !== attachmentType)
+            throw new Error("Session bridge attachment markers are invalid");
+        seenAttachments.add(item);
+        attachments.push(item);
+    }
     const model = sourceValue.model;
-    const modelRecord = model !== null && typeof model === "object" && !Array.isArray(model) ? model : undefined;
-    const provider = typeof modelRecord?.provider === "string" ? modelRecord.provider : undefined;
-    const modelId = typeof modelRecord?.modelId === "string" ? modelRecord.modelId : undefined;
-    const normalizedModel = provider === undefined || modelId === undefined ? undefined : { provider, modelId };
-    const sessionId = sourceValue.sessionId;
-    const cwd = sourceValue.cwd;
+    let normalizedModel;
+    if (model !== undefined) {
+        if (model === null || typeof model !== "object" || Array.isArray(model))
+            throw new Error("Session bridge source model is invalid");
+        const modelRecord = model;
+        assertKeys(modelRecord, ["provider", "modelId"], "Session bridge source model");
+        normalizedModel = {
+            provider: requiredText(modelRecord.provider, "Session bridge model provider", maxModelFieldChars),
+            modelId: requiredText(modelRecord.modelId, "Session bridge model id", maxModelFieldChars),
+        };
+    }
     return {
         version: bridgeVersion,
         source: { sessionId, cwd, ...(normalizedModel === undefined ? {} : { model: normalizedModel }) },
-        createdAt: typeof packageValue.createdAt === "string" ? packageValue.createdAt : "",
+        createdAt: packageValue.createdAt,
         messageCount: normalized.length,
         messages: normalized,
         unresolvedAttachments: [...attachments],
     };
 }
-function sessionMessages(manager) {
-    return manager.buildSessionContext().messages.map((message) => {
-        const value = message;
-        return { role: value.role, content: value.content };
-    });
-}
 function importedText(packageValue) {
     const model = packageValue.source.model === undefined ? "unknown model" : `${packageValue.source.model.provider}/${packageValue.source.model.modelId}`;
     const lines = [`Session handoff from ${packageValue.source.sessionId} (${packageValue.source.cwd})`, `Source model: ${model}`, ""];
@@ -168,34 +356,99 @@ function importedText(packageValue) {
         lines.push(`Unresolved attachments: ${packageValue.unresolvedAttachments.join(", ")}`);
     return lines.join("\n").trim();
 }
+function bridgeDigest(packageValue) {
+    return createHash("sha256").update(JSON.stringify(packageValue)).digest("hex");
+}
+function importedBridgeDigest(entry) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+        return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(entry);
+    if (descriptors.type?.value !== "custom_message" || descriptors.customType?.value !== bridgeType)
+        return undefined;
+    const details = descriptors.details?.value;
+    if (details === null || typeof details !== "object" || Array.isArray(details))
+        return undefined;
+    const digestDescriptor = Object.getOwnPropertyDescriptor(details, "digest");
+    return digestDescriptor !== undefined && "value" in digestDescriptor && typeof digestDescriptor.value === "string" ? digestDescriptor.value : undefined;
+}
+function wasImported(manager, digest) {
+    const entries = manager.getEntries();
+    const start = Math.max(0, entries.length - maxDuplicateScanEntries);
+    for (let index = entries.length - 1; index >= start; index -= 1)
+        if (importedBridgeDigest(entries[index]) === digest)
+            return true;
+    return false;
+}
 export default {
     name: "pi-session-bridge",
     inject: ["piSession", "piPluginUi", "piTools"],
+    Config: EmptyConfig,
     apply(context) {
+        const lifecycle = new AbortController();
         let latest;
         let latestPreview;
-        const exportCurrentSession = () => {
-            const manager = context.get("piRuntime")?.session.sessionManager ?? context.piSession.manager;
+        let status = { state: "idle" };
+        let currentPreviewCache;
+        let currentPreviewManager;
+        let currentPreviewDirty = true;
+        const activeManager = () => context.get("piRuntime")?.session.sessionManager ?? context.piSession.manager;
+        const exportCurrentSession = (manager = activeManager()) => {
             const current = manager.buildSessionContext();
             const model = current.model === null ? undefined : current.model;
-            return buildBridgePackage({ sessionId: manager.getSessionId(), cwd: manager.getCwd(), ...(model === undefined ? {} : { model }) }, sessionMessages(manager));
+            return buildBridgePackage({ sessionId: manager.getSessionId(), cwd: manager.getCwd(), ...(model === undefined ? {} : { model }) }, current.messages);
+        };
+        const currentPreview = () => {
+            const manager = activeManager();
+            if (currentPreviewCache === undefined || currentPreviewDirty || manager !== currentPreviewManager) {
+                currentPreviewCache = buildHandoffPreview(exportCurrentSession(manager));
+                currentPreviewManager = manager;
+                currentPreviewDirty = false;
+            }
+            return structuredClone(currentPreviewCache);
+        };
+        const invalidatePreview = context.on("pi/session-event", () => {
+            currentPreviewDirty = true;
+        });
+        const runOperation = (operation, callerSignal, action) => {
+            const operationSignal = callerSignal === undefined ? lifecycle.signal : AbortSignal.any([callerSignal, lifecycle.signal]);
+            status = { state: "running", operation };
+            return Promise.resolve()
+                .then(() => action(operationSignal))
+                .then((result) => {
+                status = { state: "completed", operation, at: new Date().toISOString() };
+                return result;
+            }, (error) => {
+                status = {
+                    state: operationSignal.aborted ? "cancelled" : "failed",
+                    operation,
+                    at: new Date().toISOString(),
+                    error: boundedError(error),
+                };
+                throw error;
+            });
         };
         const unregisterExport = context.piTools.register(defineTool({
             name: "session_bridge_export",
             label: "Export session handoff",
             description: "Export the active conversation as a bounded, reviewable handoff package without modifying the source session.",
             promptSnippet: "export the current session as a handoff package",
-            parameters: Type.Object({}),
-            execute() {
-                const packageValue = exportCurrentSession();
-                latest = {
-                    direction: "export",
-                    sessionId: packageValue.source.sessionId,
-                    messages: packageValue.messageCount,
-                    attachments: packageValue.unresolvedAttachments.length,
-                    at: packageValue.createdAt,
-                };
-                return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(packageValue) }], details: packageValue });
+            parameters: Type.Object({}, { additionalProperties: false }),
+            executionMode: "sequential",
+            execute(_toolCallId, rawParams, signal) {
+                return runOperation("export", signal, (operationSignal) => {
+                    parameterDescriptors(rawParams, emptyParameterNames);
+                    throwIfCancelled(operationSignal);
+                    const packageValue = exportCurrentSession();
+                    throwIfCancelled(operationSignal);
+                    latest = {
+                        direction: "export",
+                        sessionId: packageValue.source.sessionId,
+                        messages: packageValue.messageCount,
+                        attachments: packageValue.unresolvedAttachments.length,
+                        at: packageValue.createdAt,
+                    };
+                    return { content: [{ type: "text", text: JSON.stringify(packageValue) }], details: packageValue };
+                });
             },
         }));
         const unregisterPreview = context.piTools.register(defineTool({
@@ -203,14 +456,23 @@ export default {
             label: "Preview session handoff",
             description: "Create a bounded five-part handoff preview without creating a target session or changing the source session.",
             promptSnippet: "preview the current session handoff before migration",
-            parameters: Type.Object({ package: Type.Optional(Type.String({ description: "Optional JSON produced by session_bridge_export" })) }),
-            execute(_toolCallId, params) {
-                const packageValue = params.package === undefined ? exportCurrentSession() : parseBridgePackage(params.package);
-                const preview = buildHandoffPreview(packageValue);
-                latestPreview = { source: packageValue.source, preview, at: new Date().toISOString() };
-                return Promise.resolve({
-                    content: [{ type: "text", text: `Prepared a five-part handoff preview for ${packageValue.source.sessionId}.` }],
-                    details: { source: packageValue.source, preview },
+            parameters: Type.Object({
+                package: Type.Optional(Type.String({ description: "Optional JSON produced by session_bridge_export", minLength: 1, maxLength: maxPackageChars })),
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            execute(_toolCallId, rawParams, signal) {
+                return runOperation("preview", signal, (operationSignal) => {
+                    const descriptors = parameterDescriptors(rawParams, previewParameterNames);
+                    throwIfCancelled(operationSignal);
+                    const packageText = packageParameter(descriptors.package?.value, false);
+                    const packageValue = packageText === undefined ? exportCurrentSession() : parseBridgePackage(packageText);
+                    throwIfCancelled(operationSignal);
+                    const preview = buildHandoffPreview(packageValue);
+                    latestPreview = { source: cloneSource(packageValue.source), preview: structuredClone(preview), at: new Date().toISOString() };
+                    return {
+                        content: [{ type: "text", text: `Prepared a five-part handoff preview for ${packageValue.source.sessionId}.` }],
+                        details: { source: cloneSource(packageValue.source), preview: structuredClone(preview) },
+                    };
                 });
             },
         }));
@@ -219,42 +481,93 @@ export default {
             label: "Import session handoff",
             description: "Validate a handoff package and append it to the current session as a visible context message; the source session remains untouched.",
             promptSnippet: "import a validated session handoff package",
-            parameters: Type.Object({ package: Type.String({ description: "JSON produced by session_bridge_export" }) }),
-            execute(_toolCallId, params) {
-                const packageValue = parseBridgePackage(params.package);
-                context.piSession.manager.appendCustomMessageEntry(bridgeType, importedText(packageValue), true, {
-                    source: packageValue.source,
-                    messageCount: packageValue.messageCount,
-                });
-                latest = {
-                    direction: "import",
-                    sessionId: packageValue.source.sessionId,
-                    messages: packageValue.messageCount,
-                    attachments: packageValue.unresolvedAttachments.length,
-                    at: new Date().toISOString(),
-                };
-                return Promise.resolve({
-                    content: [{ type: "text", text: `Imported ${packageValue.messageCount} handoff message(s).` }],
-                    details: { imported: true, source: packageValue.source, messages: packageValue.messageCount },
+            parameters: Type.Object({
+                package: Type.String({ description: "JSON produced by session_bridge_export", minLength: 1, maxLength: maxPackageChars }),
+                confirm: Type.Boolean({ description: "Must be true to append the handoff to the current LLM context" }),
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            execute(_toolCallId, rawParams, signal) {
+                return runOperation("import", signal, (operationSignal) => {
+                    const descriptors = parameterDescriptors(rawParams, importParameterNames);
+                    throwIfCancelled(operationSignal);
+                    if (descriptors.confirm?.value !== true)
+                        throw new Error("Session Bridge import requires confirm=true");
+                    const packageText = packageParameter(descriptors.package?.value, true);
+                    const packageValue = parseBridgePackage(packageText);
+                    throwIfCancelled(operationSignal);
+                    const targetManager = activeManager();
+                    const digest = bridgeDigest(packageValue);
+                    if (wasImported(targetManager, digest))
+                        throw new Error("This Session Bridge handoff was already imported into the active session");
+                    targetManager.appendCustomMessageEntry(bridgeType, importedText(packageValue), true, {
+                        source: cloneSource(packageValue.source),
+                        messageCount: packageValue.messageCount,
+                        digest,
+                    });
+                    currentPreviewDirty = true;
+                    latest = {
+                        direction: "import",
+                        sessionId: packageValue.source.sessionId,
+                        messages: packageValue.messageCount,
+                        attachments: packageValue.unresolvedAttachments.length,
+                        at: new Date().toISOString(),
+                    };
+                    return {
+                        content: [{ type: "text", text: `Imported ${packageValue.messageCount} handoff message(s).` }],
+                        details: { imported: true, source: cloneSource(packageValue.source), messages: packageValue.messageCount },
+                    };
                 });
             },
         }));
-        const disposePanel = context.piPluginUi.register({
-            id: "session-bridge-panel",
-            pluginId: "@pi-harness/core/plugins/session-bridge",
-            title: "Session Bridge",
-            description: "导出或导入可审查的会话交接包，不改写源会话树。",
-            icon: "⇄",
-            read: () => ({
-                latest: latest ?? null,
-                latestPreview: latestPreview ?? null,
-                currentPreview: buildHandoffPreview(exportCurrentSession()),
-                formatVersion: bridgeVersion,
-                maxMessages,
-                maxTotalChars,
-            }),
-        });
+        let disposePanel;
+        try {
+            disposePanel = context.piPluginUi.register({
+                id: "session-bridge-panel",
+                pluginId: "@pi-harness/core/plugins/session-bridge",
+                title: "Session Bridge",
+                description: "导出或导入可审查的会话交接包，不改写源会话树。",
+                icon: "⇄",
+                read: () => ({
+                    latest: latest === undefined ? null : { ...latest },
+                    latestPreview: latestPreview === undefined
+                        ? null
+                        : { source: cloneSource(latestPreview.source), preview: structuredClone(latestPreview.preview), at: latestPreview.at },
+                    status: { ...status },
+                    currentPreview: currentPreview(),
+                    formatVersion: bridgeVersion,
+                    maxMessages,
+                    maxTotalChars,
+                    limits: {
+                        packageBytes: maxPackageBytes,
+                        packageCharacters: maxPackageChars,
+                        messages: maxMessages,
+                        messageCharacters: maxMessageChars,
+                        totalMessageCharacters: maxTotalChars,
+                        contentParts: maxContentParts,
+                        attachments: maxAttachments,
+                        attachmentMarkerCharacters: maxAttachmentMarkerChars,
+                        sessionIdCharacters: maxSessionIdChars,
+                        cwdCharacters: maxCwdChars,
+                        modelFieldCharacters: maxModelFieldChars,
+                        previewTextCharacters: previewTextLimit,
+                        previewListItems: previewListLimit,
+                        duplicateScanEntries: maxDuplicateScanEntries,
+                        operationErrorCharacters: maxOperationErrorChars,
+                    },
+                }),
+            });
+        }
+        catch (error) {
+            lifecycle.abort(new Error("Session Bridge plugin activation failed", { cause: error }));
+            invalidatePreview();
+            unregisterExport();
+            unregisterImport();
+            unregisterPreview();
+            throw error;
+        }
         context.effect(() => () => {
+            lifecycle.abort(new Error("Session Bridge plugin was disposed"));
+            invalidatePreview();
             unregisterExport();
             unregisterImport();
             unregisterPreview();