@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/plugin-host-rpc.js

@@ -0,0 +1,878 @@
+import { createHash, randomUUID } from "node:crypto";
+import { AgentRuntimeError, agentSpecSchema, SteerController, } from "@rynx-ai/core";
+import { PLUGIN_HOST_MAX_ACTIVE_RUNS, } from "@rynx-ai/plugin-sdk";
+import { PluginRunnerError } from "@rynx-ai/plugin-runner";
+import { ensurePluginSessionLaunch, SessionLaunchOperationConflictError, SessionLaunchOperationTargetDeletedError, } from "./session-launch-operations.js";
+import { createControlLink } from "./control-link-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;
+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.
+ *
+ * This adapter is deliberately the only place that maps public string methods
+ * to trusted runtime objects. The runner receives neither this class nor its
+ * dependencies; it receives JSON responses and canonical session events.
+ */
+export class PluginHostRpc {
+    pluginId;
+    daemonInstanceId;
+    grants;
+    services;
+    emit;
+    activeRuns = new Map();
+    activeSessionRuns = new Map();
+    activeRunsByOperation = new Map();
+    disposed = false;
+    constructor(options) {
+        this.pluginId = requiredString(options.pluginId, "pluginId", 64);
+        this.daemonInstanceId = requiredString(options.daemonInstanceId, "daemonInstanceId", 128);
+        this.grants = new Set(options.grants);
+        this.services = options.services;
+        this.emit = options.emit;
+    }
+    async call(method, params) {
+        if (this.disposed)
+            throw new PluginHostCallError("HOST_CLOSED", "plugin host is closed");
+        if (method === "host.info") {
+            return {
+                pluginId: this.pluginId,
+                installationId: this.services.installationId,
+                daemonInstanceId: this.daemonInstanceId,
+                installationProof: {
+                    algorithm: this.services.installationProof.algorithm,
+                    publicKey: this.services.installationProof.publicKey,
+                },
+                protocolVersion: 1,
+                grants: [...this.grants],
+            };
+        }
+        const capability = METHOD_CAPABILITY[method];
+        if (!capability)
+            throw new PluginHostCallError("METHOD_NOT_FOUND", `unknown host method: ${method}`);
+        if (!this.grants.has(capability)) {
+            throw new PluginHostCallError("CAPABILITY_DENIED", `host method ${method} requires capability ${capability}`);
+        }
+        try {
+            switch (method) {
+                case "installation.proof.sign": {
+                    const challenge = requiredString(record(params).challenge, "challenge", 16_384);
+                    return {
+                        algorithm: this.services.installationProof.algorithm,
+                        publicKey: this.services.installationProof.publicKey,
+                        signature: this.services.installationProof.sign(this.pluginId, challenge),
+                    };
+                }
+                case "agent.catalog.list":
+                    return await this.services.agentCatalog.list();
+                case "agent.catalog.get":
+                    return await this.services.agentCatalog.get(requiredAgentId(record(params).id, "id"));
+                case "agent.execution.resolve":
+                    return await this.resolveAgentExecution(params);
+                case "session.ensure":
+                    return this.ensureSession(params);
+                case "session.run":
+                    return await this.runSession(params);
+                case "session.steer":
+                    return this.steerSession(params);
+                case "session.interrupt":
+                    return await this.interruptRun(params);
+                case "session.interaction.resolve":
+                    return await this.resolveSessionInteraction(params);
+                case "session.models":
+                    return await this.services.capabilities.listModels(optionalRuntime(params));
+                case "session.binding.get":
+                    return await this.getBinding(params);
+                case "session.binding.list":
+                    return await this.listBindings();
+                case "session.binding.find":
+                    return await this.findBinding(params);
+                case "session.goal.get":
+                    return await this.withOwnedSession(params, (id) => this.services.capabilities.getGoal(id));
+                case "session.goal.set": {
+                    const input = record(params);
+                    const objective = requiredText(input.objective, "objective", 100_000);
+                    return await this.withOwnedSession(input, (id) => this.services.capabilities.setGoal(id, objective));
+                }
+                case "session.goal.clear":
+                    return await this.withOwnedSession(params, (id) => this.services.capabilities.clearGoal(id));
+                case "session.fork":
+                    return await this.forkSession(params);
+                case "session.meta.get":
+                    return this.ownedSession(requiredSessionId(params));
+                case "session.meta.list":
+                    return this.services.sessionRegistry.list().filter((session) => this.isOwned(session));
+                case "session.meta.setTitle":
+                    return this.setSessionTitle(params);
+                case "control.link.issue":
+                    return this.issueControlLink(params);
+                default:
+                    throw new PluginHostCallError("METHOD_NOT_FOUND", `unknown host method: ${method}`);
+            }
+        }
+        catch (error) {
+            throw toHostCallError(error);
+        }
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const runs = [...this.activeRuns.values()];
+        this.activeRuns.clear();
+        this.activeSessionRuns.clear();
+        this.activeRunsByOperation.clear();
+        for (const run of runs) {
+            run.interruptRequested = true;
+            if (run.interruptResult && await run.interruptResult.catch(() => false))
+                continue;
+            if (this.services.interruptSession) {
+                await this.services.interruptSession(run.sessionId).catch(() => false);
+            }
+            else {
+                run.abort.abort();
+            }
+        }
+    }
+    ensureSession(params) {
+        const input = record(params);
+        const scopeId = requiredString(input.scopeId, "scopeId", 512);
+        const operationId = requiredString(input.operationId, "operationId", 512);
+        const session = sessionLaunchMeta(input.session);
+        const requestHash = hashCanonicalJson(session);
+        return ensurePluginSessionLaunch({
+            pluginId: this.pluginId,
+            scopeId,
+            operationId,
+            requestHash,
+            session,
+        });
+    }
+    async runSession(params) {
+        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);
+        }
+        if (this.activeSessionRuns.has(sessionId)) {
+            throw new PluginHostCallError("RUN_ALREADY_ACTIVE", `session already has an active run: ${sessionId}`, true);
+        }
+        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 abort = new AbortController();
+        const steer = new SteerController();
+        const runId = randomUUID();
+        const run = {
+            runId,
+            sessionId,
+            operationId,
+            interruptRequested: false,
+            abort,
+            steer,
+        };
+        this.activeRuns.set(runId, run);
+        this.activeSessionRuns.set(sessionId, run);
+        if (operationId)
+            this.activeRunsByOperation.set(operationId, run);
+        let started;
+        try {
+            started = await this.services.conversationRuntime.runLive({
+                message,
+                threadId: sessionId,
+                provider: optionalRuntimeValue(input.provider),
+                model: optionalString(input.model, "model", 256) ?? session.model,
+                reasoningEffort: optionalString(input.reasoningEffort, "reasoningEffort", 128) ?? session.reasoningEffort,
+                cwd: optionalString(input.cwd, "cwd", 16_384),
+                agentName: optionalAgentId(input.agent, "agent") ?? session.agent,
+                agentSpec: session.config,
+                signal: abort.signal,
+                steer,
+                developerInstructions: optionalString(input.developerInstructions, "developerInstructions", 200_000),
+            });
+        }
+        catch (error) {
+            this.releaseRun(run);
+            throw error;
+        }
+        if (this.disposed || this.activeRuns.get(runId) !== run) {
+            this.releaseRun(run);
+            throw new PluginHostCallError("HOST_CLOSED", "plugin host is closed");
+        }
+        // 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 {
+            runId,
+            sessionId,
+            provider: started.provider,
+            model: started.model,
+            authSource: started.authSource,
+        };
+    }
+    async pumpRun(run, generator) {
+        let terminalFailure;
+        try {
+            for await (const event of generator) {
+                if (this.disposed || this.activeRuns.get(run.runId) !== run)
+                    return;
+                if (await this.interruptWon(run))
+                    return;
+                if (this.disposed || this.activeRuns.get(run.runId) !== run)
+                    return;
+                const finalResponse = topLevelAssistantResponse(event);
+                if (finalResponse !== undefined) {
+                    run.finalAssistantResponse = truncateUtf8(finalResponse, MAX_PLUGIN_RUN_FINAL_RESPONSE_BYTES);
+                }
+                for (const projected of projectSessionEvent(run, event)) {
+                    await this.emit(projected);
+                }
+                terminalFailure = sessionRunFailure(event);
+                if (terminalFailure)
+                    break;
+            }
+            if (!this.disposed &&
+                this.activeRuns.get(run.runId) === run &&
+                !(await this.interruptWon(run))) {
+                if (terminalFailure) {
+                    await this.emit({
+                        event: "session.run.failed",
+                        payload: {
+                            runId: run.runId,
+                            sessionId: run.sessionId,
+                            error: terminalFailure,
+                        },
+                    });
+                }
+                else {
+                    await this.emit({
+                        event: "session.run.completed",
+                        payload: {
+                            runId: run.runId,
+                            sessionId: run.sessionId,
+                            ...(run.finalAssistantResponse
+                                ? { finalResponse: run.finalAssistantResponse }
+                                : {}),
+                        },
+                    });
+                }
+            }
+        }
+        catch (error) {
+            if (!this.disposed &&
+                this.activeRuns.get(run.runId) === run &&
+                !(await this.interruptWon(run))) {
+                const failure = toHostCallError(error);
+                if (failure.code === "INTERACTION_EVENT_TOO_LARGE") {
+                    // A blocking control-flow event must never be projected lossily. End
+                    // the native Turn before telling the plugin it failed, otherwise the
+                    // invisible waiter would keep the daemon slot occupied forever.
+                    const interrupted = (await this.services.interruptSession?.(run.sessionId).catch(() => false)) ?? false;
+                    if (!interrupted)
+                        run.abort.abort();
+                }
+                await Promise.resolve(this.emit({
+                    event: "session.run.failed",
+                    payload: {
+                        runId: run.runId,
+                        sessionId: run.sessionId,
+                        error: {
+                            code: failure.code,
+                            message: truncateUtf8(failure.message, 16 * 1024),
+                            retryable: failure.retryable,
+                        },
+                    },
+                })).catch(() => undefined);
+            }
+        }
+        finally {
+            this.releaseRun(run);
+        }
+    }
+    releaseRun(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);
+        }
+    }
+    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) };
+    }
+    async interruptRun(params) {
+        const input = record(params);
+        const run = this.activeRunByIdentity(input);
+        if (run.interruptResult) {
+            return { interrupted: await run.interruptResult };
+        }
+        // Serialize cancellation with stream projection. Events observed while
+        // the authoritative stop is pending wait for its result: true suppresses
+        // them, while false/error lets genuine native progress/terminal continue.
+        run.interruptRequested = true;
+        const interruptResult = this.services.interruptSession
+            // ConversationRuntime wires AbortSignal to this same native operation.
+            // Invoke it directly once so this boolean is the authoritative result;
+            // aborting first would trigger a duplicate, unobserved interrupt.
+            ? Promise.resolve().then(() => this.services.interruptSession(run.sessionId))
+            : Promise.resolve().then(() => {
+                run.abort.abort();
+                // Without a result-bearing Host interrupt, AbortSignal is best
+                // effort and cannot prove that native execution stopped.
+                return false;
+            });
+        run.interruptResult = interruptResult;
+        try {
+            const interrupted = await interruptResult;
+            if (!interrupted && this.activeRuns.get(run.runId) === run) {
+                run.interruptRequested = false;
+                run.interruptResult = undefined;
+            }
+            return { interrupted };
+        }
+        catch (error) {
+            if (this.activeRuns.get(run.runId) === run) {
+                run.interruptRequested = false;
+                run.interruptResult = undefined;
+            }
+            throw error;
+        }
+    }
+    async interruptWon(run) {
+        if (!run.interruptRequested)
+            return false;
+        if (!run.interruptResult)
+            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);
+        if ((runId ? 1 : 0) + (operationId ? 1 : 0) !== 1) {
+            throw new PluginHostCallError("INVALID_PARAMS", "exactly one of runId or operationId is required");
+        }
+        const run = runId
+            ? this.activeRuns.get(runId)
+            : this.activeRunsByOperation.get(operationId);
+        if (!run) {
+            throw new PluginHostCallError("RUN_NOT_FOUND", `active run not found: ${runId ?? operationId}`);
+        }
+        return run;
+    }
+    async getBinding(params) {
+        const sessionId = requiredSessionId(params);
+        this.ownedSession(sessionId);
+        return await this.services.sessionStore.get(sessionId);
+    }
+    async listBindings() {
+        const owned = new Set(this.services.sessionRegistry.list().filter((session) => this.isOwned(session)).map((session) => session.id));
+        return (await this.services.sessionStore.listAll()).filter((binding) => owned.has(binding.localThreadId));
+    }
+    async findBinding(params) {
+        const input = record(params);
+        const runtimeSessionId = requiredString(input.runtimeSessionId, "runtimeSessionId", 512);
+        const binding = await this.services.sessionStore.findByCodexSessionId(runtimeSessionId);
+        if (!binding)
+            return null;
+        this.ownedSession(binding.localThreadId);
+        return binding;
+    }
+    async withOwnedSession(params, run) {
+        const sessionId = requiredSessionId(params);
+        this.ownedSession(sessionId);
+        return await run(sessionId);
+    }
+    async resolveSessionInteraction(params) {
+        const input = record(params);
+        const sessionId = requiredSessionId(input);
+        this.ownedSession(sessionId);
+        const interactionId = requiredString(input.interactionId, "interactionId", 512);
+        const resolution = sessionInteractionResolution(input.resolution);
+        const resolve = this.services.resolveSessionInteraction;
+        if (!resolve) {
+            return { disposition: "not_found" };
+        }
+        return await resolve(sessionId, interactionId, resolution);
+    }
+    async forkSession(params) {
+        const input = record(params);
+        const fromSessionId = requiredString(input.fromSessionId, "fromSessionId", 512);
+        const toSessionId = requiredString(input.toSessionId, "toSessionId", 512);
+        this.ownedSession(fromSessionId);
+        this.ownedSession(toSessionId);
+        return await this.services.capabilities.forkSession(fromSessionId, toSessionId);
+    }
+    setSessionTitle(params) {
+        const input = record(params);
+        const sessionId = requiredSessionId(input);
+        this.ownedSession(sessionId);
+        const title = requiredText(input.title, "title", 1_000);
+        this.services.sessionRegistry.setTitle(sessionId, title);
+        return { updated: true };
+    }
+    resolveAgentExecution(params) {
+        const input = record(params);
+        const defaultAgent = optionalAgentId(input.defaultAgent, "defaultAgent");
+        return this.services.agentCatalog.resolveExecution({
+            ...(defaultAgent ? { defaultAgent } : {}),
+            session: sessionExecutionSnapshot(input.session),
+        });
+    }
+    issueControlLink(params) {
+        const input = record(params);
+        const sessionId = requiredSessionId(input);
+        this.ownedSession(sessionId);
+        const ttlSeconds = optionalPositiveNumber(input.ttlSeconds, "ttlSeconds");
+        return createControlLink({
+            pluginId: this.pluginId,
+            sessionId,
+            ...(ttlSeconds === undefined ? {} : { ttlMs: ttlSeconds * 1_000 }),
+        });
+    }
+    ownedSession(sessionId) {
+        const session = this.services.sessionRegistry.get(sessionId);
+        if (!session || !this.isOwned(session)) {
+            throw new PluginHostCallError("SESSION_NOT_FOUND", `plugin session not found: ${sessionId}`);
+        }
+        return session;
+    }
+    isOwned(session) {
+        return session.source === `plugin:${this.pluginId}`;
+    }
+}
+export class PluginHostCallError extends PluginRunnerError {
+    retryable;
+    data;
+    constructor(code, message, retryable = false, data) {
+        super(code, message, {
+            retryable,
+            ...(data === undefined ? {} : { data }),
+        });
+        this.retryable = retryable;
+        this.data = data;
+        this.name = "PluginHostCallError";
+    }
+}
+function toHostCallError(error) {
+    if (error instanceof PluginHostCallError)
+        return error;
+    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 SessionLaunchOperationConflictError) {
+        return new PluginHostCallError(error.code, error.message, false);
+    }
+    if (error instanceof SessionLaunchOperationTargetDeletedError) {
+        return new PluginHostCallError(error.code, error.message, false, { sessionId: error.sessionId });
+    }
+    return new PluginHostCallError("HOST_CALL_FAILED", error instanceof Error ? error.message : String(error));
+}
+function sessionLaunchMeta(value) {
+    const input = record(value);
+    assertJsonValue(input, "session");
+    const agent = optionalAgentId(input.agent, "session.agent");
+    const config = input.config === undefined ? undefined : agentSpecSchema.parse(input.config);
+    const model = optionalString(input.model, "session.model", 256);
+    const reasoningEffort = optionalString(input.reasoningEffort, "session.reasoningEffort", 128);
+    const title = optionalString(input.title, "session.title", 1_000);
+    return {
+        ...(agent ? { agent } : {}),
+        ...(config ? { config } : {}),
+        ...(model ? { model } : {}),
+        ...(reasoningEffort ? { reasoningEffort } : {}),
+        ...(title ? { title } : {}),
+    };
+}
+function sessionExecutionSnapshot(value) {
+    const input = record(value);
+    const runtime = optionalRuntimeValue(input.runtime);
+    const model = optionalString(input.model, "session.model", 256);
+    const reasoningEffort = optionalString(input.reasoningEffort, "session.reasoningEffort", 128);
+    const agent = optionalAgentId(input.agent, "session.agent");
+    return {
+        ...(runtime ? { runtime } : {}),
+        ...(model ? { model } : {}),
+        ...(reasoningEffort ? { reasoningEffort } : {}),
+        ...(agent ? { agent } : {}),
+    };
+}
+function requiredSessionId(params) {
+    return requiredString(record(params).sessionId, "sessionId", 512);
+}
+function sessionInteractionResolution(value) {
+    const input = record(value);
+    const keys = Object.keys(input);
+    if (keys.some((key) => key !== "actionId" && key !== "answers")) {
+        throw new PluginHostCallError("INVALID_PARAMS", "resolution contains unknown fields");
+    }
+    const actionId = requiredString(input.actionId, "resolution.actionId", 256);
+    if (input.answers === undefined)
+        return { actionId };
+    const answersInput = record(input.answers);
+    const entries = Object.entries(answersInput);
+    if (entries.length > 64) {
+        throw new PluginHostCallError("INVALID_PARAMS", "resolution.answers has too many fields");
+    }
+    const answers = {};
+    for (const [key, answer] of entries) {
+        if (!key || key.length > 256) {
+            throw new PluginHostCallError("INVALID_PARAMS", "resolution answer id is invalid");
+        }
+        if (typeof answer === "string") {
+            if (answer.length > 65_536) {
+                throw new PluginHostCallError("INVALID_PARAMS", `resolution.answers.${key} is too long`);
+            }
+            answers[key] = answer;
+            continue;
+        }
+        if (!Array.isArray(answer) ||
+            answer.length > 64 ||
+            answer.some((item) => typeof item !== "string" || item.length > 65_536)) {
+            throw new PluginHostCallError("INVALID_PARAMS", `resolution.answers.${key} must be a bounded string array`);
+        }
+        answers[key] = [...answer];
+    }
+    const resolution = { actionId, answers };
+    if (jsonBytes(resolution) > SESSION_INTERACTION_RESOLUTION_MAX_BYTES) {
+        throw new PluginHostCallError("INVALID_PARAMS", "resolution is too large");
+    }
+    return resolution;
+}
+function optionalRuntime(params) {
+    return optionalRuntimeValue(record(params).runtime);
+}
+function optionalRuntimeValue(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (value === "codex" || value === "traex" || value === "claude")
+        return value;
+    throw new PluginHostCallError("INVALID_PARAMS", "runtime must be codex, traex, or claude");
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new PluginHostCallError("INVALID_PARAMS", "host call params must be an object");
+    }
+    return value;
+}
+function requiredString(value, label, maxLength) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is required`);
+    }
+    if (value.length > maxLength) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is too long`);
+    }
+    return value.trim();
+}
+function requiredText(value, label, maxLength) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is required`);
+    }
+    if (value.length > maxLength) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is too long`);
+    }
+    return value;
+}
+function optionalString(value, label, maxLength) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} must be a string`);
+    }
+    if (value.length > maxLength) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is too long`);
+    }
+    return value;
+}
+function requiredAgentId(value, label) {
+    const id = requiredString(value, label, 64);
+    if (!AGENT_ID_PATTERN.test(id)) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} is not a valid agent id`);
+    }
+    return id;
+}
+function optionalAgentId(value, label) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    return requiredAgentId(value, label);
+}
+function optionalPositiveNumber(value, label) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} must be a positive number`);
+    }
+    return value;
+}
+function assertJsonValue(value, label, seen = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} must contain finite JSON numbers`);
+    }
+    if (typeof value !== "object") {
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} must contain JSON data only`);
+    }
+    if (seen.has(value))
+        throw new PluginHostCallError("INVALID_PARAMS", `${label} must not be cyclic`);
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertJsonValue(item, `${label}[${index}]`, seen));
+    }
+    else {
+        for (const [key, item] of Object.entries(value)) {
+            if (item === undefined)
+                continue;
+            assertJsonValue(item, `${label}.${key}`, seen);
+        }
+    }
+    seen.delete(value);
+}
+function hashCanonicalJson(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+}
+/**
+ * Project a canonical event onto the bounded plugin transport:
+ *
+ * - delta events are split into semantically equivalent delta events;
+ * - blocking interaction events must fit losslessly or fail the native Turn;
+ * - other oversized events are shape-preservingly compacted and marked;
+ * - if structural overhead alone is too large, a digest reference is emitted.
+ *
+ * The authoritative, unmodified event remains in the daemon's canonical
+ * session log. The reference is therefore a loss marker for a presentation
+ * plugin, not a replacement for host persistence.
+ */
+function projectSessionEvent(run, event) {
+    const direct = sessionHostEvent(run, event);
+    if (jsonBytes(direct) <= MAX_PLUGIN_HOST_EVENT_BYTES)
+        return [direct];
+    const input = jsonRecord(event);
+    if (isSessionInteractionEvent(input?.type)) {
+        throw new PluginHostCallError("INTERACTION_EVENT_TOO_LARGE", `canonical ${String(input?.type)} exceeds the lossless plugin transport budget`, false, { bytes: jsonBytes(direct), limit: MAX_PLUGIN_HOST_EVENT_BYTES });
+    }
+    if (typeof input?.delta === "string") {
+        const chunks = splitCodeUnits(input.delta, MAX_DELTA_CHUNK_CODE_UNITS);
+        const originalBytes = jsonBytes(event);
+        const projected = chunks.map((delta, index) => sessionHostEvent(run, { ...input, delta }, {
+            strategy: "chunk",
+            index,
+            count: chunks.length,
+            originalBytes,
+        }));
+        if (projected.every((item) => jsonBytes(item) <= MAX_PLUGIN_HOST_EVENT_BYTES)) {
+            return projected;
+        }
+    }
+    const originalJson = JSON.stringify(event);
+    const originalBytes = Buffer.byteLength(originalJson, "utf8");
+    const reference = createHash("sha256").update(originalJson).digest("hex");
+    const attempts = [
+        { stringBytes: 64 * 1024, arrayItems: 256, objectKeys: 256 },
+        { stringBytes: 16 * 1024, arrayItems: 64, objectKeys: 128 },
+        { stringBytes: 4 * 1024, arrayItems: 16, objectKeys: 64 },
+        { stringBytes: 1_024, arrayItems: 4, objectKeys: 32 },
+        { stringBytes: 256, arrayItems: 1, objectKeys: 16 },
+    ];
+    for (const limits of attempts) {
+        const compacted = compactJson(event, limits, 0);
+        const candidate = sessionHostEvent(run, compacted, {
+            strategy: "truncate",
+            originalBytes,
+            reference,
+        });
+        if (jsonBytes(candidate) <= MAX_PLUGIN_HOST_EVENT_BYTES)
+            return [candidate];
+    }
+    return [{
+            event: "session.run.event.reference",
+            payload: {
+                runId: run.runId,
+                sessionId: run.sessionId,
+                eventType: typeof input?.type === "string" ? input.type : "unknown",
+                originalBytes,
+                reference,
+                reason: "canonical event exceeded the plugin transport budget",
+            },
+        }];
+}
+function isSessionInteractionEvent(type) {
+    return type === "session.interaction.requested" ||
+        type === "session.interaction.resolved" ||
+        type === "session.interaction.cancelled";
+}
+/** Select only the last finalized, top-level assistant response. */
+function topLevelAssistantResponse(event) {
+    const input = jsonRecord(event);
+    if (input?.type !== "response.output_item.done")
+        return undefined;
+    const item = jsonRecord(input.item);
+    if (item?.type !== "message" || item.parentToolCallId !== undefined)
+        return undefined;
+    const data = jsonRecord(item.data);
+    if (data?.role !== "assistant" || data.isMeta === true || !Array.isArray(data.content)) {
+        return undefined;
+    }
+    const text = data.content
+        .map((part) => jsonRecord(part))
+        .filter((part) => part?.type === "output_text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("")
+        .trim();
+    return text || undefined;
+}
+function sessionRunFailure(event) {
+    const input = jsonRecord(event);
+    if (input?.type !== "response.failed")
+        return undefined;
+    const error = jsonRecord(input.error);
+    const code = typeof error?.code === "string" && error.code.trim()
+        ? error.code
+        : "RUNTIME_TURN_FAILED";
+    const message = typeof error?.message === "string" && error.message.trim()
+        ? error.message
+        : "Runtime Turn failed";
+    return {
+        code: truncateUtf8(code, 256),
+        message: truncateUtf8(message, 16 * 1024),
+        retryable: false,
+    };
+}
+function sessionHostEvent(run, event, delivery) {
+    return {
+        event: "session.run.event",
+        payload: {
+            runId: run.runId,
+            sessionId: run.sessionId,
+            event,
+            ...(delivery ? { delivery } : {}),
+        },
+    };
+}
+function jsonRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function splitCodeUnits(value, maxCodeUnits) {
+    const chunks = [];
+    let offset = 0;
+    while (offset < value.length) {
+        let end = Math.min(value.length, offset + maxCodeUnits);
+        if (end < value.length && isHighSurrogate(value.charCodeAt(end - 1)))
+            end -= 1;
+        if (end === offset)
+            end += 1;
+        chunks.push(value.slice(offset, end));
+        offset = end;
+    }
+    return chunks.length > 0 ? chunks : [""];
+}
+function compactJson(value, limits, depth) {
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string")
+        return truncateUtf8(value, limits.stringBytes);
+    if (depth >= 32)
+        return null;
+    if (Array.isArray(value)) {
+        return value
+            .slice(0, limits.arrayItems)
+            .map((item) => compactJson(item, limits, depth + 1));
+    }
+    if (typeof value === "object" && value !== null) {
+        const output = {};
+        for (const [key, item] of Object.entries(value).slice(0, limits.objectKeys)) {
+            if (item !== undefined)
+                output[key] = compactJson(item, limits, depth + 1);
+        }
+        return output;
+    }
+    return null;
+}
+function truncateUtf8(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    const marker = "…[truncated]";
+    const markerBytes = Buffer.byteLength(marker, "utf8");
+    if (maxBytes <= markerBytes)
+        return marker.slice(0, Math.max(0, maxBytes));
+    const target = maxBytes - markerBytes;
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        let middle = Math.ceil((low + high) / 2);
+        if (middle < value.length && isHighSurrogate(value.charCodeAt(middle - 1)))
+            middle -= 1;
+        if (middle <= low)
+            middle = low + 1;
+        if (Buffer.byteLength(value.slice(0, middle), "utf8") <= target)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    if (low < value.length && isHighSurrogate(value.charCodeAt(low - 1)))
+        low -= 1;
+    return `${value.slice(0, Math.max(0, low))}${marker}`;
+}
+function isHighSurrogate(value) {
+    return value >= 0xd800 && value <= 0xdbff;
+}