@rynx-ai/daemon 0.1.11-beta.3 → 0.1.11-beta.31

package/dist/plugin-host-rpc.js

@@ -1,11 +1,15 @@
 import { createHash, randomUUID } from "node:crypto";
 import { realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import { AgentRuntimeError, agentSpecSchema, resolvedExecutionSnapshotSchema, sessionWorkspaceSnapshotSchema, SteerController, } from "@rynx-ai/core";
+import { AgentRuntimeError, agentSpecSchema, resolvedExecutionSnapshotSchema, sessionWorkspaceSnapshotSchema, } from "@rynx-ai/core";
 import { PLUGIN_HOST_MAX_ACTIVE_RUNS, } from "@rynx-ai/plugin-sdk";
+import { parseRuntimeBrowserRequestHeadersGetParams, parseRuntimeBrowserRequestHeadersSetParams, } from "@rynx-ai/protocol/runtime-browser";
+import { SessionBrowserServiceError, } from "@rynx-ai/server";
 import { PluginRunnerError } from "@rynx-ai/plugin-runner";
 import { ensurePluginSessionLaunch, replayPluginSessionLaunch, SessionLaunchOperationConflictError, SessionLaunchOperationTargetDeletedError, } from "./session-launch-operations.js";
 import { createControlLink } from "./control-link-store.js";
+import { issueSessionPortalTicket, revokeSessionPortalGrant, } from "./session-portal-grant-store.js";
+import { claimSessionTimelineProjection, completeSessionTimelineProjection, } from "./session-timeline-projection-store.js";
 const MAX_MESSAGE_LENGTH = 1_000_000;
 /** Leaves ample room for the RPC envelope below the runner's 1 MiB line cap. */
 export const MAX_PLUGIN_HOST_EVENT_BYTES = 512 * 1024;
@@ -13,31 +17,59 @@ const MAX_PLUGIN_RUN_FINAL_RESPONSE_BYTES = 64 * 1024;
 const MAX_DELTA_CHUNK_CODE_UNITS = 64 * 1024;
 const SESSION_INTERACTION_RESOLUTION_MAX_BYTES = 128 * 1024;
 const AGENT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
-const METHOD_CAPABILITY = {
-    "installation.proof.sign": "installation.proof",
-    "agent.catalog.list": "agent.catalog.read",
-    "agent.catalog.get": "agent.catalog.read",
-    "agent.execution.resolve": "agent.catalog.read",
-    "session.ensure": "session.provision",
-    "session.run": "conversation.run",
-    "session.steer": "conversation.run",
-    "session.interrupt": "session.cancel",
-    "session.interaction.resolve": "conversation.run",
-    "session.models": "runtime.catalog.read",
-    "session.binding.get": "session.binding.read",
-    "session.binding.list": "session.binding.read",
-    "session.binding.find": "session.binding.read",
-    "session.goal.get": "session.goal.read",
-    "session.goal.set": "session.goal.write",
-    "session.goal.clear": "session.goal.write",
-    "session.fork": "session.fork",
-    "session.meta.get": "session.meta.read",
-    "session.meta.list": "session.meta.read",
-    "session.meta.setTitle": "session.meta.title.write",
-    "control.link.issue": "control-link.issue",
-};
 /**
- * One authenticated plugin's capability-gated Host RPC surface.
+ * Buffers messages that arrive while the first `session.run` is still bringing
+ * up its native Turn. Once Core subscribes, later messages are delivered
+ * through the same input channel. After that subscription closes, this Run no
+ * longer accepts input; the caller waits for release and opens the next Run.
+ */
+class PluginRunInputController {
+    listener;
+    pending = new Map();
+    subscribed = false;
+    closed = false;
+    enqueue(text) {
+        if (this.closed || (this.subscribed && !this.listener)) {
+            return { accepted: false, cancel: () => undefined };
+        }
+        if (this.listener) {
+            this.listener(text);
+            return { accepted: true, cancel: () => undefined };
+        }
+        const token = Symbol("plugin-run-input");
+        this.pending.set(token, text);
+        return {
+            accepted: true,
+            cancel: () => {
+                this.pending.delete(token);
+            },
+        };
+    }
+    subscribe(listener) {
+        if (this.closed)
+            return () => undefined;
+        if (this.listener) {
+            throw new Error("plugin Run input already has a subscriber");
+        }
+        this.subscribed = true;
+        this.listener = listener;
+        const queued = [...this.pending.values()];
+        this.pending.clear();
+        for (const text of queued)
+            listener(text);
+        return () => {
+            if (this.listener === listener)
+                this.listener = undefined;
+        };
+    }
+    close() {
+        this.closed = true;
+        this.listener = undefined;
+        this.pending.clear();
+    }
+}
+/**
+ * One authenticated plugin's Host RPC surface.
  *
  * This adapter is deliberately the only place that maps public string methods
  * to trusted runtime objects. The runner receives neither this class nor its
@@ -49,7 +81,6 @@ export class PluginHostRpc {
     daemonInstanceId;
     productVersion;
     cliVersion;
-    capabilities;
     services;
     managedWorkspaceRoot;
     emit;
@@ -65,7 +96,6 @@ export class PluginHostRpc {
         this.daemonInstanceId = requiredString(options.daemonInstanceId, "daemonInstanceId", 128);
         this.productVersion = requiredString(options.productVersion, "productVersion", 128);
         this.cliVersion = requiredString(options.cliVersion, "cliVersion", 128);
-        this.capabilities = new Set(options.capabilities);
         this.services = options.services;
         this.managedWorkspaceRoot = options.managedWorkspaceRoot
             ? path.resolve(options.managedWorkspaceRoot)
@@ -89,15 +119,27 @@ export class PluginHostRpc {
                     publicKey: this.services.installationProof.publicKey,
                 },
                 protocolVersion: 1,
-                capabilities: [...this.capabilities],
+                capabilities: {
+                    sessionRunContent: true,
+                    sessionRunFiles: true,
+                    ...(this.services.sessionTimeline
+                        ? { sessionTimelineProjectText: true }
+                        : {}),
+                    ...(this.services.sessionBrowserRequestHeaders
+                        ? { sessionBrowserRequestHeaders: true }
+                        : {}),
+                    ...(this.services.sessionPortal
+                        ? {
+                            sessionPortalEmbedOrigin: true,
+                            sessionPortalGrantRevocation: true,
+                        }
+                        : {}),
+                },
+                ...(this.services.sessionPortal
+                    ? { sessionPortal: { ...this.services.sessionPortal } }
+                    : {}),
             };
         }
-        const capability = METHOD_CAPABILITY[method];
-        if (!capability)
-            throw new PluginHostCallError("METHOD_NOT_FOUND", `unknown host method: ${method}`);
-        if (!this.capabilities.has(capability)) {
-            throw new PluginHostCallError("CAPABILITY_NOT_DECLARED", `host method ${method} is missing manifest capability ${capability}`);
-        }
         try {
             switch (method) {
                 case "installation.proof.sign": {
@@ -118,8 +160,8 @@ export class PluginHostRpc {
                     return await this.ensureSession(params);
                 case "session.run":
                     return await this.runSession(params, signal);
-                case "session.steer":
-                    return this.steerSession(params);
+                case "session.activity.get":
+                    return await this.sessionActivity(params);
                 case "session.interrupt":
                     return await this.interruptRun(params);
                 case "session.interaction.resolve":
@@ -149,8 +191,31 @@ export class PluginHostRpc {
                     return this.services.sessionRegistry.list().filter((session) => this.isOwned(session));
                 case "session.meta.setTitle":
                     return this.setSessionTitle(params);
+                case "session.browser.requestHeaders.get":
+                    return await this.getSessionBrowserRequestHeaders(params);
+                case "session.browser.requestHeaders.set":
+                    return await this.setSessionBrowserRequestHeaders(params);
                 case "control.link.issue":
                     return this.issueControlLink(params);
+                case "session.portal.plugin.issue": {
+                    const input = record(params);
+                    return this.issueSessionPortalLink("plugin_sessions", requiredSessionPortalAccess(input), undefined, optionalSessionPortalEmbedOrigin(input.embedOrigin), optionalString(input.grantHandle, "grantHandle", 128));
+                }
+                case "session.portal.session.issue": {
+                    const input = record(params);
+                    const sessionId = requiredSessionId(input);
+                    this.ownedSession(sessionId);
+                    return this.issueSessionPortalLink("single_session", requiredSessionPortalAccess(input), sessionId, optionalSessionPortalEmbedOrigin(input.embedOrigin), optionalString(input.grantHandle, "grantHandle", 128));
+                }
+                case "session.portal.grant.revoke": {
+                    const grantHandle = requiredString(record(params).grantHandle, "grantHandle", 128);
+                    return revokeSessionPortalGrant({
+                        pluginId: this.principalId,
+                        grantHandle,
+                    });
+                }
+                case "session.timeline.projectText":
+                    return await this.projectTimelineText(params);
                 default:
                     throw new PluginHostCallError("METHOD_NOT_FOUND", `unknown host method: ${method}`);
             }
@@ -319,17 +384,86 @@ export class PluginHostRpc {
         const input = record(params);
         const sessionId = requiredSessionId(input);
         const operationId = optionalString(input.operationId, "operationId", 512);
-        const session = this.ownedSession(sessionId);
-        if (operationId && this.activeRunsByOperation.has(operationId)) {
-            throw new PluginHostCallError("RUN_ALREADY_ACTIVE", `operation already has an active run: ${operationId}`, true);
+        const hasMessage = input.message !== undefined;
+        const hasContent = input.content !== undefined;
+        if (hasMessage === hasContent) {
+            throw new PluginHostCallError("INVALID_PARAMS", "provide exactly one of message or content");
         }
-        if (this.activeSessionRuns.has(sessionId)) {
-            throw new PluginHostCallError("RUN_ALREADY_ACTIVE", `session already has an active run: ${sessionId}`, true);
+        const message = hasMessage
+            ? requiredText(input.message, "message", MAX_MESSAGE_LENGTH)
+            : undefined;
+        const collaborationMode = optionalCollaborationMode(input.collaborationMode);
+        let session = this.ownedSession(sessionId);
+        if (operationId) {
+            const replayed = this.activeRunsByOperation.get(operationId);
+            if (replayed) {
+                if (replayed.sessionId !== sessionId) {
+                    throw new PluginHostCallError("RUN_ALREADY_ACTIVE", `operation already belongs to another active Session: ${operationId}`, true);
+                }
+                return await waitForHostPromise(replayed.started, signal);
+            }
         }
+        const active = this.activeSessionRuns.get(sessionId);
+        if (active) {
+            if (hasContent) {
+                // Native steering currently accepts text only. Preserve the attachment
+                // as a new Turn after the active response reaches its terminal edge.
+                await waitForHostPromise(active.settled, signal);
+                throwIfHostCallAborted(signal);
+                return await this.runSessionAdmitted(params, signal);
+            }
+            const queued = active.input.enqueue(message);
+            if (!queued.accepted) {
+                // The response reached its terminal boundary before Host cleanup won
+                // the scheduling race. Wait for that old Run to leave the Session slot,
+                // then submit this message as a new Turn with a new response identity.
+                await waitForHostPromise(active.settled, signal);
+                throwIfHostCallAborted(signal);
+                return await this.runSessionAdmitted(params, signal);
+            }
+            if (operationId) {
+                active.operationIds.add(operationId);
+                this.activeRunsByOperation.set(operationId, active);
+            }
+            try {
+                // Reuse the current Run identity. Core already owns its response stream;
+                // the buffered input will become turn/steer once that stream subscribes.
+                return await waitForHostPromise(active.started, signal);
+            }
+            catch (error) {
+                queued.cancel();
+                if (operationId && this.activeRunsByOperation.get(operationId) === active) {
+                    this.activeRunsByOperation.delete(operationId);
+                    active.operationIds.delete(operationId);
+                }
+                throw error;
+            }
+        }
+        const modelProvided = input.model !== undefined;
+        const requestedModel = input.model === null || input.model === ""
+            ? null
+            : optionalString(input.model, "model", 256);
+        const reasoningEffortProvided = input.reasoningEffort !== undefined;
+        const requestedReasoningEffort = input.reasoningEffort === null || input.reasoningEffort === ""
+            ? null
+            : optionalString(input.reasoningEffort, "reasoningEffort", 64);
         if (this.activeRuns.size >= PLUGIN_HOST_MAX_ACTIVE_RUNS) {
             throw new PluginHostCallError("RUN_LIMIT", "plugin has too many active session runs", true);
         }
-        const message = requiredText(input.message, "message", MAX_MESSAGE_LENGTH);
+        const nextModel = modelProvided ? requestedModel ?? null : session.execution.model;
+        const nextReasoningEffort = reasoningEffortProvided
+            ? requestedReasoningEffort ?? null
+            : session.execution.reasoningEffort;
+        if (nextModel !== session.execution.model ||
+            nextReasoningEffort !== session.execution.reasoningEffort) {
+            await this.services.sessionExecution.update({
+                sessionId,
+                model: nextModel,
+                reasoningEffort: nextReasoningEffort,
+            });
+            session = this.ownedSession(sessionId);
+        }
+        const content = hasContent ? await pluginRunContent(input.content) : undefined;
         const abort = new AbortController();
         const cancel = () => abort.abort(signal?.reason);
         if (signal?.aborted) {
@@ -337,15 +471,35 @@ export class PluginHostRpc {
             throwIfHostCallAborted(signal);
         }
         signal?.addEventListener("abort", cancel, { once: true });
-        const steer = new SteerController();
+        const runInput = new PluginRunInputController();
         const runId = randomUUID();
+        let resolveStarted;
+        let rejectStarted;
+        const startedResult = new Promise((resolve, reject) => {
+            resolveStarted = resolve;
+            rejectStarted = reject;
+        });
+        // The initiating RPC observes startup directly below. This promise exists
+        // for concurrent/replayed calls, so retain its rejection without creating
+        // an unhandled-rejection when there are none.
+        void startedResult.catch(() => undefined);
+        let resolveSettled;
+        const settled = new Promise((resolve) => {
+            resolveSettled = resolve;
+        });
         const run = {
             runId,
             sessionId,
-            operationId,
+            operationIds: new Set(operationId ? [operationId] : []),
             interruptRequested: false,
             abort,
-            steer,
+            input: runInput,
+            started: startedResult,
+            startupSettled: false,
+            resolveStarted,
+            rejectStarted,
+            settled,
+            resolveSettled,
         };
         this.activeRuns.set(runId, run);
         this.activeSessionRuns.set(sessionId, run);
@@ -353,16 +507,23 @@ export class PluginHostRpc {
             this.activeRunsByOperation.set(operationId, run);
         let started;
         try {
-            started = await this.services.conversationRuntime.runLive({
-                message,
-                threadId: sessionId,
-                workspace: session.workspace,
-                execution: session.execution,
+            started = await this.services.sessionRuns.startRun(sessionId, message !== undefined
+                ? {
+                    message,
+                    clientMessageId: operationId ?? `plugin_run_${runId}`,
+                }
+                : {
+                    content: content,
+                    clientMessageId: operationId ?? `plugin_run_${runId}`,
+                }, {
                 signal: abort.signal,
-                steer,
+                steer: runInput,
+                ...(collaborationMode ? { collaborationMode } : {}),
             });
         }
         catch (error) {
+            run.startupSettled = true;
+            run.rejectStarted(error);
             this.releaseRun(run);
             throw error;
         }
@@ -371,20 +532,30 @@ export class PluginHostRpc {
         }
         if (signal?.aborted || this.disposed || this.activeRuns.get(runId) !== run) {
             abort.abort(signal?.reason);
+            const error = signal?.aborted
+                ? new PluginHostCallError("REQUEST_CANCELLED", "plugin host request was cancelled")
+                : new PluginHostCallError("HOST_CLOSED", "plugin host is closed");
+            run.startupSettled = true;
+            run.rejectStarted(error);
             this.releaseRun(run);
             throwIfHostCallAborted(signal);
-            throw new PluginHostCallError("HOST_CLOSED", "plugin host is closed");
+            throw error;
         }
-        // Let the RPC transport write the request response before stream events are
-        // emitted. `runLive` has already subscribed, so no agent event is lost.
-        setImmediate(() => void this.pumpRun(run, started.generator));
-        return {
+        run.responseId = started.responseId;
+        const result = {
             runId,
+            responseId: started.responseId,
             sessionId,
             provider: started.provider,
             model: started.model,
             authSource: started.authSource,
         };
+        run.startupSettled = true;
+        run.resolveStarted(result);
+        // Let the RPC transport write the request response before stream events are
+        // emitted. `runLive` has already subscribed, so no agent event is lost.
+        setImmediate(() => void this.pumpRun(run, started.generator));
+        return result;
     }
     async pumpRun(run, generator) {
         let terminalFailure;
@@ -403,6 +574,16 @@ export class PluginHostRpc {
                 for (const projected of projectSessionEvent(run, event)) {
                     await this.emit(projected);
                 }
+                try {
+                    const fileEvent = await this.projectSessionFileEvent(run, event);
+                    if (fileEvent)
+                        await this.emit(fileEvent);
+                }
+                catch {
+                    // File delivery is an optional projection of a canonical event. A
+                    // missing borrowed path must not turn an otherwise successful native
+                    // Turn into session.run.failed or stop consuming its event stream.
+                }
                 terminalFailure = sessionRunFailure(event);
                 if (terminalFailure)
                     break;
@@ -465,28 +646,83 @@ export class PluginHostRpc {
             this.releaseRun(run);
         }
     }
+    async projectSessionFileEvent(run, event) {
+        const input = jsonRecord(event);
+        if (input?.type !== "response.output_item.done")
+            return undefined;
+        const item = jsonRecord(input.item);
+        if (item?.type !== "function_call_output")
+            return undefined;
+        const data = jsonRecord(item.data);
+        const image = jsonRecord(data?.generatedImage);
+        if (!image || typeof image.mediaType !== "string")
+            return undefined;
+        let filePath;
+        if (typeof image.path === "string" && path.isAbsolute(image.path)) {
+            filePath = image.path;
+        }
+        else if (typeof image.resourceId === "string") {
+            filePath = await this.services.sessionFiles.resolveResourcePath(run.sessionId, image.resourceId);
+        }
+        else {
+            return undefined;
+        }
+        return {
+            event: "session.run.file",
+            payload: {
+                runId: run.runId,
+                responseId: typeof item.responseId === "string"
+                    ? item.responseId
+                    : run.responseId,
+                sessionId: run.sessionId,
+                itemId: typeof item.id === "string" ? item.id : "unknown",
+                filename: typeof image.filename === "string" && image.filename
+                    ? image.filename
+                    : path.basename(filePath),
+                mediaType: image.mediaType,
+                path: filePath,
+            },
+        };
+    }
     releaseRun(run) {
+        run.input.close();
+        if (!run.startupSettled) {
+            run.startupSettled = true;
+            run.rejectStarted(new PluginHostCallError("HOST_CLOSED", "plugin Host closed the active Run"));
+        }
         if (this.activeRuns.get(run.runId) === run)
             this.activeRuns.delete(run.runId);
         if (this.activeSessionRuns.get(run.sessionId) === run) {
             this.activeSessionRuns.delete(run.sessionId);
         }
-        if (run.operationId && this.activeRunsByOperation.get(run.operationId) === run) {
-            this.activeRunsByOperation.delete(run.operationId);
+        for (const operationId of run.operationIds) {
+            if (this.activeRunsByOperation.get(operationId) === run) {
+                this.activeRunsByOperation.delete(operationId);
+            }
         }
-    }
-    steerSession(params) {
-        const input = record(params);
-        const run = this.activeRun(input);
-        const text = requiredText(input.text, "text", MAX_MESSAGE_LENGTH);
-        return { delivered: run.steer.send(text) };
+        run.resolveSettled();
     }
     async interruptRun(params) {
         const input = record(params);
-        const run = this.activeRunByIdentity(input);
-        const forceAfterMs = optionalPositiveNumber(input.forceAfterMs, "forceAfterMs");
-        if (forceAfterMs !== undefined && forceAfterMs > 30_000) {
-            throw new PluginHostCallError("INVALID_PARAMS", "forceAfterMs must not exceed 30000");
+        const sessionId = optionalString(input.sessionId, "sessionId", 128);
+        const runId = optionalString(input.runId, "runId", 128);
+        const operationId = optionalString(input.operationId, "operationId", 512);
+        if ((sessionId ? 1 : 0) + (runId ? 1 : 0) + (operationId ? 1 : 0) !== 1) {
+            throw new PluginHostCallError("INVALID_PARAMS", "exactly one of sessionId, runId, or operationId is required");
+        }
+        let run;
+        if (sessionId) {
+            this.ownedSession(sessionId);
+            run = this.activeSessionRuns.get(sessionId);
+            if (!run) {
+                const interrupted = this.services.interruptSession
+                    ? Promise.resolve().then(() => this.services.interruptSession(sessionId))
+                    : Promise.resolve(false);
+                return { interrupted: await interrupted };
+            }
+        }
+        else {
+            run = this.activeRunByIdentity(input);
         }
         if (run.interruptResult) {
             return { interrupted: await run.interruptResult };
@@ -506,9 +742,7 @@ export class PluginHostRpc {
                 // effort and cannot prove that native execution stopped.
                 return false;
             });
-        const interruptResult = forceAfterMs === undefined
-            ? graceful
-            : forceStoppedInterrupt(graceful, forceAfterMs, () => this.services.terminateSession?.(run.sessionId) ?? Promise.resolve(false));
+        const interruptResult = graceful;
         run.interruptResult = interruptResult;
         try {
             const interrupted = await interruptResult;
@@ -526,6 +760,17 @@ export class PluginHostRpc {
             throw error;
         }
     }
+    async sessionActivity(params) {
+        const sessionId = requiredSessionId(params);
+        this.ownedSession(sessionId);
+        const snapshot = structuredClone(await this.services.sessionActivity(sessionId));
+        const waiting = snapshot.pendingInteractions.length > 0;
+        return {
+            status: waiting ? "waiting" : snapshot.status,
+            activeResponseIds: snapshot.activeResponseIds,
+            pendingInteractions: snapshot.pendingInteractions,
+        };
+    }
     async interruptWon(run) {
         if (!run.interruptRequested)
             return false;
@@ -533,13 +778,6 @@ export class PluginHostRpc {
             return true;
         return run.interruptResult.catch(() => false);
     }
-    activeRun(input) {
-        const runId = requiredString(input.runId, "runId", 128);
-        const run = this.activeRuns.get(runId);
-        if (!run)
-            throw new PluginHostCallError("RUN_NOT_FOUND", `active run not found: ${runId}`);
-        return run;
-    }
     activeRunByIdentity(input) {
         const runId = optionalString(input.runId, "runId", 128);
         const operationId = optionalString(input.operationId, "operationId", 512);
@@ -633,6 +871,36 @@ export class PluginHostRpc {
         this.services.sessionRegistry.setTitle(sessionId, title);
         return { updated: true };
     }
+    async getSessionBrowserRequestHeaders(params) {
+        let input;
+        try {
+            input = parseRuntimeBrowserRequestHeadersGetParams(params);
+        }
+        catch {
+            throw new PluginHostCallError("INVALID_PARAMS", "Session Browser request headers parameters are invalid");
+        }
+        this.ownedSession(input.sessionId);
+        const service = this.services.sessionBrowserRequestHeaders;
+        if (!service) {
+            throw new PluginHostCallError("METHOD_NOT_FOUND", "Session Browser request headers are unsupported by this Host");
+        }
+        return await service.getRequestHeaders(input);
+    }
+    async setSessionBrowserRequestHeaders(params) {
+        let input;
+        try {
+            input = parseRuntimeBrowserRequestHeadersSetParams(params);
+        }
+        catch {
+            throw new PluginHostCallError("INVALID_PARAMS", "Session Browser request headers parameters are invalid");
+        }
+        this.ownedSession(input.sessionId);
+        const service = this.services.sessionBrowserRequestHeaders;
+        if (!service) {
+            throw new PluginHostCallError("METHOD_NOT_FOUND", "Session Browser request headers are unsupported by this Host");
+        }
+        return await service.setRequestHeaders(input);
+    }
     resolveAgentExecution(params) {
         const input = record(params);
         const defaultAgent = optionalAgentId(input.defaultAgent, "defaultAgent");
@@ -652,6 +920,56 @@ export class PluginHostRpc {
             ...(ttlSeconds === undefined ? {} : { ttlMs: ttlSeconds * 1_000 }),
         });
     }
+    issueSessionPortalLink(scope, access, sessionId, embedOrigin, grantHandle) {
+        if (!this.services.sessionPortal) {
+            throw new PluginHostCallError("HOST_CALL_FAILED", "the Session Portal is not configured");
+        }
+        return issueSessionPortalTicket({
+            pluginId: this.principalId,
+            scope,
+            access,
+            ...(sessionId ? { sessionId } : {}),
+            ...(embedOrigin ? { embedOrigin } : {}),
+            ...(grantHandle ? { grantHandle } : {}),
+        });
+    }
+    async projectTimelineText(params) {
+        const sessionTimeline = this.services.sessionTimeline;
+        if (!sessionTimeline) {
+            throw new PluginHostCallError("HOST_CALL_FAILED", "Session timeline projection is unavailable");
+        }
+        const input = record(params);
+        const sessionId = requiredSessionId(input);
+        this.ownedSession(sessionId);
+        const projection = claimSessionTimelineProjection({
+            pluginId: this.principalId,
+            sessionId,
+            projectionId: requiredString(input.projectionId, "projectionId", 256),
+            ...(input.responseId === undefined
+                ? {}
+                : { responseId: requiredString(input.responseId, "responseId", 256) }),
+            text: requiredText(input.text, "text", 64 * 1024),
+        });
+        if (!(await sessionTimeline.hasItem(sessionId, projection.itemId))) {
+            await sessionTimeline.projectText({
+                sessionId,
+                responseId: projection.responseId,
+                itemId: projection.itemId,
+                text: projection.text,
+            });
+        }
+        completeSessionTimelineProjection({
+            pluginId: this.principalId,
+            sessionId,
+            projectionId: projection.projectionId,
+        });
+        return {
+            projectionId: projection.projectionId,
+            responseId: projection.responseId,
+            itemId: projection.itemId,
+            disposition: projection.disposition,
+        };
+    }
     ownedSession(sessionId) {
         const session = this.services.sessionRegistry.get(sessionId);
         if (!session || !this.isOwned(session)) {
@@ -678,6 +996,24 @@ function throwIfHostCallAborted(signal) {
         return;
     throw new PluginHostCallError("REQUEST_CANCELLED", "plugin host request was cancelled");
 }
+async function waitForHostPromise(promise, signal) {
+    throwIfHostCallAborted(signal);
+    if (!signal)
+        return await promise;
+    return await new Promise((resolve, reject) => {
+        const aborted = () => {
+            reject(new PluginHostCallError("REQUEST_CANCELLED", "plugin host request was cancelled"));
+        };
+        signal.addEventListener("abort", aborted, { once: true });
+        void promise.then((value) => {
+            signal.removeEventListener("abort", aborted);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", aborted);
+            reject(error);
+        });
+    });
+}
 export class PluginHostCallError extends PluginRunnerError {
     retryable;
     data;
@@ -694,12 +1030,30 @@ export class PluginHostCallError extends PluginRunnerError {
 function toHostCallError(error) {
     if (error instanceof PluginHostCallError)
         return error;
+    if (error instanceof SessionBrowserServiceError) {
+        if (error.code === "revision_mismatch") {
+            return new PluginHostCallError("REVISION_CONFLICT", "Session Browser request headers changed since they were read");
+        }
+        if (error.code === "invalid_request") {
+            return new PluginHostCallError("INVALID_PARAMS", "Session Browser request headers parameters are invalid");
+        }
+        if (error.code === "not_found") {
+            return new PluginHostCallError("SESSION_NOT_FOUND", "plugin session not found");
+        }
+        return new PluginHostCallError("HOST_CALL_FAILED", "Session Browser request headers operation failed");
+    }
     if (error instanceof AgentRuntimeError && error.code === "live_unavailable") {
         // ConversationRuntime emits this code only before injectMessage is called:
         // the native live Session (including its exact Skill environment) could
         // not be brought up, so callers may fail without quarantining capacity.
         return new PluginHostCallError("LIVE_SESSION_UNAVAILABLE", error.message, false);
     }
+    if (error instanceof AgentRuntimeError) {
+        // Native lifecycle failures already carry a stable phase code. Preserve it
+        // across the plugin-host boundary instead of erasing it behind the generic
+        // HOST_CALL_FAILED wrapper.
+        return new PluginHostCallError(error.code, error.message, false);
+    }
     if (error instanceof SessionLaunchOperationConflictError) {
         return new PluginHostCallError(error.code, error.message, false);
     }
@@ -717,7 +1071,10 @@ function sessionLaunchSelection(value) {
     const agent = optionalAgentId(input.agent, "session.agent");
     const config = input.config === undefined ? undefined : agentSpecSchema.parse(input.config);
     const provider = optionalRuntimeValue(input.provider);
-    const model = optionalString(input.model, "session.model", 256);
+    const modelProvided = input.model !== undefined;
+    const model = input.model === null || input.model === ""
+        ? null
+        : optionalString(input.model, "session.model", 256);
     const reasoningEffort = optionalString(input.reasoningEffort, "session.reasoningEffort", 128);
     const title = optionalString(input.title, "session.title", 1_000);
     if (Number(Boolean(projectId)) + Number(Boolean(managedCwd)) + Number(Boolean(workspace)) > 1) {
@@ -736,7 +1093,7 @@ function sessionLaunchSelection(value) {
         ...(agent ? { agent } : {}),
         ...(config ? { config } : {}),
         ...(provider ? { provider } : {}),
-        ...(model ? { model } : {}),
+        ...(modelProvided ? { model: model ?? null } : {}),
         ...(reasoningEffort ? { reasoningEffort } : {}),
         ...(title ? { title } : {}),
     };
@@ -768,6 +1125,114 @@ function sessionExecutionSnapshot(value) {
 function requiredSessionId(params) {
     return requiredString(record(params).sessionId, "sessionId", 512);
 }
+async function pluginRunContent(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 256) {
+        throw new PluginHostCallError("INVALID_PARAMS", "content must be a non-empty array with at most 256 parts");
+    }
+    return Promise.all(value.map(async (entry, index) => {
+        const input = record(entry);
+        if (input.type === "input_text") {
+            return {
+                type: "input_text",
+                text: requiredText(input.text, `content[${index}].text`, MAX_MESSAGE_LENGTH),
+            };
+        }
+        if (input.type !== "input_image" && input.type !== "input_file") {
+            throw new PluginHostCallError("INVALID_PARAMS", `content[${index}].type is invalid`);
+        }
+        const suppliedPath = requiredPathString(input.path, `content[${index}].path`, 16_384);
+        if (!path.isAbsolute(suppliedPath)) {
+            throw new PluginHostCallError("INVALID_PARAMS", `content[${index}].path must be absolute`);
+        }
+        let resolvedPath;
+        let fileSize;
+        try {
+            resolvedPath = await realpath(suppliedPath);
+            const metadata = await stat(resolvedPath);
+            if (!metadata.isFile())
+                throw new Error("not a regular file");
+            fileSize = metadata.size;
+        }
+        catch (error) {
+            throw new PluginHostCallError("INVALID_PARAMS", `content[${index}].path is not a readable regular file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const filename = input.type === "input_file"
+            ? requiredString(input.filename, `content[${index}].filename`, 255)
+            : optionalString(input.filename, `content[${index}].filename`, 255) ??
+                path.basename(resolvedPath);
+        if (input.type === "input_image") {
+            return {
+                type: "input_image",
+                path: resolvedPath,
+                filename,
+                mediaType: pluginImageMediaType(input.mediaType, resolvedPath, `content[${index}].mediaType`),
+                byteLength: fileSize,
+            };
+        }
+        return {
+            type: "input_file",
+            path: resolvedPath,
+            filename,
+            mediaType: pluginMediaType(input.mediaType ?? "application/octet-stream", `content[${index}].mediaType`),
+            byteLength: fileSize,
+        };
+    }));
+}
+function pluginImageMediaType(value, filePath, label) {
+    const inferred = (() => {
+        switch (path.extname(filePath).toLowerCase()) {
+            case ".png": return "image/png";
+            case ".jpg":
+            case ".jpeg": return "image/jpeg";
+            case ".webp": return "image/webp";
+            case ".gif": return "image/gif";
+            case ".svg": return "image/svg+xml";
+            default: return undefined;
+        }
+    })();
+    const mediaType = value === undefined ? inferred : pluginMediaType(value, label);
+    if (mediaType !== "image/png" &&
+        mediaType !== "image/jpeg" &&
+        mediaType !== "image/webp" &&
+        mediaType !== "image/gif" &&
+        mediaType !== "image/svg+xml") {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is not a supported image type`);
+    }
+    return mediaType;
+}
+function pluginMediaType(value, label) {
+    if (typeof value !== "string") {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} must be a media type`);
+    }
+    const mediaType = value.trim().toLowerCase();
+    if (mediaType.length === 0 ||
+        mediaType.length > 255 ||
+        !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mediaType)) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is invalid`);
+    }
+    return mediaType;
+}
+function requiredSessionPortalAccess(params) {
+    const access = record(params).access;
+    if (access === "read_only" || access === "read_write")
+        return access;
+    throw new PluginHostCallError("INVALID_PARAMS", "access must be read_only or read_write");
+}
+function optionalSessionPortalEmbedOrigin(value) {
+    if (value === undefined)
+        return undefined;
+    const candidate = requiredString(value, "embedOrigin", 512);
+    try {
+        const parsed = new URL(candidate);
+        if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+            parsed.origin !== candidate)
+            throw new Error("invalid origin");
+        return parsed.origin;
+    }
+    catch {
+        throw new PluginHostCallError("INVALID_PARAMS", "embedOrigin must be an exact http(s) origin");
+    }
+}
 function sessionInteractionResolution(value) {
     const input = record(value);
     const keys = Object.keys(input);
@@ -810,6 +1275,13 @@ function sessionInteractionResolution(value) {
 function optionalRuntime(params) {
     return optionalRuntimeValue(record(params).runtime);
 }
+function optionalCollaborationMode(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "plan" || value === "default")
+        return value;
+    throw new PluginHostCallError("INVALID_PARAMS", "collaborationMode must be plan or default");
+}
 function optionalRuntimeValue(value) {
     if (value === undefined || value === null || value === "")
         return undefined;