@memberjunction/ai-agents 5.40.2 → 5.41.0

package/dist/realtime/realtime-tool-broker.d.ts

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview Topology-agnostic broker that executes a single realtime tool call server-side.
+ *
+ * The {@link RealtimeToolBroker} owns the *tool-execution* half of a realtime session: given a
+ * provider {@link RealtimeToolCall}, it routes the call (the stable `invoke-target-agent` tool →
+ * delegate to the target agent; every other tool → an injected tool executor), owns the per-call
+ * {@link AbortController} so barge-in can cancel an in-flight delegated run, and serializes the
+ * success/error result into the exact JSON the model expects as a `tool_response`.
+ *
+ * **Why factor this out.** Both audio topologies must execute a realtime tool call *identically*:
+ * the **server-bridged** path ({@link RealtimeSessionRunner}, where the provider socket lives on the
+ * server) and the **client-direct** path (where the browser owns the socket and relays tool calls
+ * back to a server resolver). Keeping one broker guarantees the two paths produce byte-for-byte
+ * identical tool results, including structured errors for spoken-error-handling. The broker is the
+ * single tool-execution path both topologies share.
+ *
+ * **Dependency injection.** Every collaborator that would otherwise pull in `BaseAgent`, metadata,
+ * or the database is injected via {@link RealtimeToolBrokerDeps}, keeping the broker fully
+ * unit-testable against mocks.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { RealtimeToolCall } from '@memberjunction/ai';
+import { AgentExecutionProgressCallback } from '@memberjunction/ai-core-plus';
+/**
+ * The stable name of the primary tool every Realtime Co-Agent registers with the realtime provider.
+ *
+ * Per the plan's design rule, the realtime-registered tool set is **target-independent**: the
+ * co-agent always exposes this single `invoke-target-agent` tool, and the specific target is a
+ * runtime parameter passed *inside* the call — never a different tool per target. This keeps the
+ * provider contract identical across targets (and is what lets a pre-provisioned, fixed-tool
+ * provider like Eleven Labs fit the same model later).
+ */
+export declare const INVOKE_TARGET_AGENT_TOOL_NAME = "invoke-target-agent";
+/**
+ * A request to delegate work to the target agent, derived from an `invoke-target-agent` tool call.
+ */
+export interface DelegateToTargetRequest {
+    /** The provider-assigned call ID, used to correlate the eventual tool result. */
+    CallID: string;
+    /**
+     * The raw arguments JSON string the model emitted for the call (e.g. the natural-language
+     * request to hand to the target agent). The delegate parses this into the target's expected
+     * input shape.
+     */
+    Arguments: string;
+    /**
+     * Abort signal owned by the broker for this specific delegated call. On barge-in
+     * ({@link RealtimeToolBroker.AbortInFlight}), the broker aborts the controller behind this
+     * signal so a stale delegated result is never narrated into a conversation that has moved on.
+     */
+    AbortSignal: AbortSignal;
+    /**
+     * Optional progress callback the CALLER wants threaded into the delegated agent run's
+     * `onProgress` (in addition to any host-level callback the delegate already wires). The
+     * server-bridged {@link import('./realtime-session-runner.js').RealtimeSessionRunner} supplies
+     * this so it can narrate the delegated run's progress over the live provider socket
+     * (`SendContextNote` / `RequestSpokenUpdate`). Delegates that run agents should invoke it
+     * alongside their own progress plumbing; delegates without progress support may ignore it.
+     */
+    OnProgress?: AgentExecutionProgressCallback;
+}
+/**
+ * One artifact a delegated target-agent run produced, surfaced to the transport layer (and into
+ * the serialized tool result as `artifacts: [{ artifactId, artifactVersionId, name }]`) so the
+ * client call overlay can open it in an artifact tab while the model narrates the outcome.
+ */
+export interface DelegatedRunArtifact {
+    /** The `MJ: Artifacts` row id. */
+    ArtifactID: string;
+    /** The `MJ: Artifact Versions` row id of the version this run produced. */
+    ArtifactVersionID: string;
+    /** The artifact's display name (tab title in the call overlay). */
+    Name: string;
+}
+/**
+ * The result of a delegated target-agent run, fed back to the realtime model as a tool response.
+ */
+export interface DelegatedResult {
+    /** The provider call ID this result corresponds to. */
+    CallID: string;
+    /** Whether the delegated run completed successfully. */
+    Success: boolean;
+    /**
+     * The textual outcome to narrate (on success) or the error to surface (on failure). The
+     * driver feeds this back to the model as the `tool_response` so it can speak the outcome.
+     */
+    Output: string;
+    /**
+     * When the delegated run paused awaiting user feedback (an interactive target agent, e.g.
+     * Query Builder confirming a task graph), this carries the paused run's id so the transport
+     * layer can persist it and resume the SAME run on the user's next answer (rather than starting
+     * a fresh run). Absent when the run completed (or failed) without pausing. The {@link Output} in
+     * this case is the agent's clarifying QUESTION, and {@link Success} is `true` (a valid
+     * intermediate outcome).
+     */
+    PausedRunID?: string;
+    /**
+     * ID of the delegated target-agent run (`MJ: AI Agent Runs`), when one was created. Serialized
+     * into the tool result as `runId` so client developer tooling (the call overlay's dev links)
+     * can open the underlying run record. Absent when the delegation failed before a run existed.
+     */
+    RunID?: string;
+    /**
+     * Artifacts the delegated run produced (when artifact creation is enabled for the target and
+     * the run returned a payload). Serialized into the tool result as `artifacts` so the call
+     * overlay can auto-open them in artifact tabs. Absent/empty when the run produced none.
+     */
+    Artifacts?: DelegatedRunArtifact[];
+}
+/**
+ * A non-target tool call routed to the injected {@link RealtimeToolBrokerDeps.ExecuteTool} handler.
+ * This is any tool other than `invoke-target-agent` (e.g. a UI/control tool such as `ShowChart`, or
+ * a fast server/client tool the co-agent was given directly).
+ */
+export interface ToolExecutionResult {
+    /** The provider call ID this result corresponds to. */
+    CallID: string;
+    /** Whether the tool executed successfully. */
+    Success: boolean;
+    /** The textual result to feed back to the model as the tool response. */
+    Output: string;
+}
+/**
+ * Verbose-aware status logging callback.
+ */
+export type RealtimeStatusLogger = (message: string, verboseOnly?: boolean) => void;
+/**
+ * Error logging callback.
+ */
+export type RealtimeErrorLogger = (error: Error | string) => void;
+/**
+ * The serialized outcome of executing a realtime tool call.
+ *
+ * {@link RealtimeToolBroker.ExecuteToolCall} returns this so the *transport* layer (server-bridged
+ * session or client-direct resolver) can feed {@link ExecutedToolCall.ResultJson} back to the model
+ * (e.g. via `IRealtimeSession.SendToolResult`) without knowing anything about how the result was
+ * produced.
+ */
+export interface ExecutedToolCall {
+    /**
+     * The JSON-stringified tool result, shaped exactly as the model expects: `{ success, output }`
+     * on success or `{ success: false, error }` on failure (consistent structured errors so the
+     * model can narrate the failure — spoken-error-handling).
+     */
+    ResultJson: string;
+    /** Whether the tool/delegation completed successfully. */
+    Success: boolean;
+    /**
+     * When the delegated target-agent run paused awaiting user feedback, this surfaces the paused
+     * run's id (propagated from {@link DelegatedResult.PausedRunID}) so the transport layer can
+     * persist it and resume that run on the user's next answer. Absent for non-delegation tools and
+     * for delegated runs that completed without pausing.
+     */
+    PausedRunID?: string;
+    /**
+     * ID of the delegated target-agent run (propagated from {@link DelegatedResult.RunID}) — also
+     * embedded in {@link ResultJson} as `runId`. Absent for non-delegation tools and for
+     * delegations that failed before a run was created.
+     */
+    RunID?: string;
+    /**
+     * Artifacts the delegated run produced (propagated from {@link DelegatedResult.Artifacts}) —
+     * also embedded in {@link ResultJson} as `artifacts: [{ artifactId, artifactVersionId, name }]`.
+     * Absent for non-delegation tools and for delegations that produced no artifacts.
+     */
+    Artifacts?: DelegatedRunArtifact[];
+}
+/**
+ * The injected collaborators the broker needs to execute a tool call.
+ *
+ * Each member is a seam that decouples the broker from `BaseAgent`/metadata/DB so it can be
+ * exercised with mocks. In production, the {@link RealtimeSessionRunner} (and, in P5b, the
+ * client-direct server resolver) constructs these from `BaseAgent`-backed implementations.
+ */
+export interface RealtimeToolBrokerDeps {
+    /**
+     * Runs the target agent for an `invoke-target-agent` tool call. The broker creates and owns a
+     * fresh {@link AbortController} per delegated call and passes its signal in via
+     * {@link DelegateToTargetRequest.AbortSignal}; barge-in aborts it. In production this is backed
+     * by `BaseAgent.ExecuteSubAgent` (top-level target only — sub-agents are not exposed).
+     */
+    DelegateToTarget: (request: DelegateToTargetRequest) => Promise<DelegatedResult>;
+    /**
+     * Executes a non-target tool call (any tool other than `invoke-target-agent`). In production
+     * this routes to the co-agent's server/client/UI tool execution under the session's context
+     * user.
+     */
+    ExecuteTool: (call: RealtimeToolCall) => Promise<ToolExecutionResult>;
+    /** Optional verbose-aware status logger. */
+    LogStatus?: RealtimeStatusLogger;
+    /** Optional error logger. */
+    LogError?: RealtimeErrorLogger;
+}
+/**
+ * Executes a single realtime tool call server-side, identically across both audio topologies.
+ *
+ * Construct with a {@link RealtimeToolBrokerDeps}, then call {@link ExecuteToolCall} per provider
+ * tool call. The broker routes the call, owns the abort controller for an in-flight delegated run,
+ * and returns the serialized {@link ExecutedToolCall} the transport layer relays back to the model.
+ */
+export declare class RealtimeToolBroker {
+    private deps;
+    /** The abort controller for the currently in-flight delegated run, if any. */
+    private currentDelegationController;
+    /**
+     * @param deps The injected collaborators that execute tool calls.
+     */
+    constructor(deps: RealtimeToolBrokerDeps);
+    /**
+     * Executes a realtime tool call and returns its serialized result.
+     *
+     * Routes `invoke-target-agent` → {@link RealtimeToolBrokerDeps.DelegateToTarget} (creating and
+     * owning a per-call {@link AbortController} so {@link AbortInFlight} can cancel it on barge-in),
+     * and every other tool → {@link RealtimeToolBrokerDeps.ExecuteTool}. Always resolves with an
+     * {@link ExecutedToolCall} — failures are serialized as structured errors rather than thrown, so
+     * the model always receives a consistent `tool_response`.
+     *
+     * @param call The tool-call request emitted by the model.
+     * @returns The serialized result the transport layer relays back to the model.
+     */
+    ExecuteToolCall(call: RealtimeToolCall): Promise<ExecutedToolCall>;
+    /**
+     * Aborts the in-flight delegated run's controller (if any).
+     *
+     * Called by the transport layer on barge-in so a stale delegated result is never narrated into a
+     * conversation that has moved on. Safe no-op when no delegation is in flight.
+     */
+    AbortInFlight(): void;
+    /**
+     * Delegates an `invoke-target-agent` call to the target agent, owning a fresh
+     * {@link AbortController} so {@link AbortInFlight} can cancel the in-flight run on barge-in.
+     *
+     * @param call The `invoke-target-agent` tool call.
+     * @returns The serialized delegation result (or structured error).
+     */
+    private runInvokeTarget;
+    /**
+     * Routes a non-target tool call to the injected tool executor.
+     *
+     * @param call The tool call (any tool other than `invoke-target-agent`).
+     * @returns The serialized tool result (or structured error).
+     */
+    private runOtherTool;
+    /**
+     * Serializes a successful tool/delegation outcome to the model's expected `tool_response` shape.
+     *
+     * @param success Whether the tool/delegation completed successfully.
+     * @param output The textual outcome (narration on success, error text on failure).
+     * @param pausedRunID When the delegated run paused awaiting feedback, the paused run's id to
+     *   surface for resumption. Omitted for completed runs and non-delegation tools.
+     * @param runID ID of the delegated agent run, when one was created. Embedded in the JSON as
+     *   `runId` so the client overlay's developer tooling can link to the run record. Omitted for
+     *   non-delegation tools.
+     * @param artifacts Artifacts the delegated run produced. Embedded in the JSON as
+     *   `artifacts: [{ artifactId, artifactVersionId, name }]` so the client overlay can open
+     *   them in artifact tabs. Omitted when absent or empty.
+     * @returns The serialized result.
+     */
+    private serializeResult;
+    /**
+     * Serializes a thrown error to a structured error `tool_response` so the model can narrate the
+     * failure (consistent with the plan's spoken-error-handling) rather than leaving the call
+     * unanswered.
+     *
+     * @param error The thrown error or message.
+     * @returns The serialized error result (always `Success: false`).
+     */
+    private serializeError;
+    /**
+     * Logs an error via the injected logger (if any), prefixed with the failing operation.
+     *
+     * @param error The thrown error or message.
+     * @param operation A short description of what was being attempted.
+     */
+    private logError;
+}
+//# sourceMappingURL=realtime-tool-broker.d.ts.map

package/dist/realtime/realtime-tool-broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-tool-broker.d.ts","sourceRoot":"","sources":["../../src/realtime/realtime-tool-broker.ts"],"names":[],"mappings":"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"}

package/dist/realtime/realtime-tool-broker.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Topology-agnostic broker that executes a single realtime tool call server-side.
+ *
+ * The {@link RealtimeToolBroker} owns the *tool-execution* half of a realtime session: given a
+ * provider {@link RealtimeToolCall}, it routes the call (the stable `invoke-target-agent` tool →
+ * delegate to the target agent; every other tool → an injected tool executor), owns the per-call
+ * {@link AbortController} so barge-in can cancel an in-flight delegated run, and serializes the
+ * success/error result into the exact JSON the model expects as a `tool_response`.
+ *
+ * **Why factor this out.** Both audio topologies must execute a realtime tool call *identically*:
+ * the **server-bridged** path ({@link RealtimeSessionRunner}, where the provider socket lives on the
+ * server) and the **client-direct** path (where the browser owns the socket and relays tool calls
+ * back to a server resolver). Keeping one broker guarantees the two paths produce byte-for-byte
+ * identical tool results, including structured errors for spoken-error-handling. The broker is the
+ * single tool-execution path both topologies share.
+ *
+ * **Dependency injection.** Every collaborator that would otherwise pull in `BaseAgent`, metadata,
+ * or the database is injected via {@link RealtimeToolBrokerDeps}, keeping the broker fully
+ * unit-testable against mocks.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+/**
+ * The stable name of the primary tool every Realtime Co-Agent registers with the realtime provider.
+ *
+ * Per the plan's design rule, the realtime-registered tool set is **target-independent**: the
+ * co-agent always exposes this single `invoke-target-agent` tool, and the specific target is a
+ * runtime parameter passed *inside* the call — never a different tool per target. This keeps the
+ * provider contract identical across targets (and is what lets a pre-provisioned, fixed-tool
+ * provider like Eleven Labs fit the same model later).
+ */
+export const INVOKE_TARGET_AGENT_TOOL_NAME = 'invoke-target-agent';
+/**
+ * Executes a single realtime tool call server-side, identically across both audio topologies.
+ *
+ * Construct with a {@link RealtimeToolBrokerDeps}, then call {@link ExecuteToolCall} per provider
+ * tool call. The broker routes the call, owns the abort controller for an in-flight delegated run,
+ * and returns the serialized {@link ExecutedToolCall} the transport layer relays back to the model.
+ */
+export class RealtimeToolBroker {
+    /**
+     * @param deps The injected collaborators that execute tool calls.
+     */
+    constructor(deps) {
+        /** The abort controller for the currently in-flight delegated run, if any. */
+        this.currentDelegationController = null;
+        this.deps = deps;
+    }
+    /**
+     * Executes a realtime tool call and returns its serialized result.
+     *
+     * Routes `invoke-target-agent` → {@link RealtimeToolBrokerDeps.DelegateToTarget} (creating and
+     * owning a per-call {@link AbortController} so {@link AbortInFlight} can cancel it on barge-in),
+     * and every other tool → {@link RealtimeToolBrokerDeps.ExecuteTool}. Always resolves with an
+     * {@link ExecutedToolCall} — failures are serialized as structured errors rather than thrown, so
+     * the model always receives a consistent `tool_response`.
+     *
+     * @param call The tool-call request emitted by the model.
+     * @returns The serialized result the transport layer relays back to the model.
+     */
+    async ExecuteToolCall(call) {
+        if (call.ToolName === INVOKE_TARGET_AGENT_TOOL_NAME) {
+            return this.runInvokeTarget(call);
+        }
+        return this.runOtherTool(call);
+    }
+    /**
+     * Aborts the in-flight delegated run's controller (if any).
+     *
+     * Called by the transport layer on barge-in so a stale delegated result is never narrated into a
+     * conversation that has moved on. Safe no-op when no delegation is in flight.
+     */
+    AbortInFlight() {
+        if (this.currentDelegationController) {
+            this.currentDelegationController.abort();
+            this.currentDelegationController = null;
+        }
+    }
+    /**
+     * Delegates an `invoke-target-agent` call to the target agent, owning a fresh
+     * {@link AbortController} so {@link AbortInFlight} can cancel the in-flight run on barge-in.
+     *
+     * @param call The `invoke-target-agent` tool call.
+     * @returns The serialized delegation result (or structured error).
+     */
+    async runInvokeTarget(call) {
+        const controller = new AbortController();
+        this.currentDelegationController = controller;
+        try {
+            const result = await this.deps.DelegateToTarget({
+                CallID: call.CallID,
+                Arguments: call.Arguments,
+                AbortSignal: controller.signal
+            });
+            return this.serializeResult(result.Success, result.Output, result.PausedRunID, result.RunID, result.Artifacts);
+        }
+        catch (error) {
+            this.logError(error, 'delegating to target agent');
+            return this.serializeError(error);
+        }
+        finally {
+            // Only clear if this is still the active controller (a later delegation may have replaced it).
+            if (this.currentDelegationController === controller) {
+                this.currentDelegationController = null;
+            }
+        }
+    }
+    /**
+     * Routes a non-target tool call to the injected tool executor.
+     *
+     * @param call The tool call (any tool other than `invoke-target-agent`).
+     * @returns The serialized tool result (or structured error).
+     */
+    async runOtherTool(call) {
+        try {
+            const result = await this.deps.ExecuteTool(call);
+            return this.serializeResult(result.Success, result.Output);
+        }
+        catch (error) {
+            this.logError(error, `executing tool '${call.ToolName}'`);
+            return this.serializeError(error);
+        }
+    }
+    /**
+     * Serializes a successful tool/delegation outcome to the model's expected `tool_response` shape.
+     *
+     * @param success Whether the tool/delegation completed successfully.
+     * @param output The textual outcome (narration on success, error text on failure).
+     * @param pausedRunID When the delegated run paused awaiting feedback, the paused run's id to
+     *   surface for resumption. Omitted for completed runs and non-delegation tools.
+     * @param runID ID of the delegated agent run, when one was created. Embedded in the JSON as
+     *   `runId` so the client overlay's developer tooling can link to the run record. Omitted for
+     *   non-delegation tools.
+     * @param artifacts Artifacts the delegated run produced. Embedded in the JSON as
+     *   `artifacts: [{ artifactId, artifactVersionId, name }]` so the client overlay can open
+     *   them in artifact tabs. Omitted when absent or empty.
+     * @returns The serialized result.
+     */
+    serializeResult(success, output, pausedRunID, runID, artifacts) {
+        const payload = { success, output };
+        if (runID) {
+            payload.runId = runID;
+        }
+        const hasArtifacts = artifacts != null && artifacts.length > 0;
+        if (hasArtifacts) {
+            payload.artifacts = artifacts.map(a => ({
+                artifactId: a.ArtifactID,
+                artifactVersionId: a.ArtifactVersionID,
+                name: a.Name
+            }));
+        }
+        return {
+            ResultJson: JSON.stringify(payload),
+            Success: success,
+            PausedRunID: pausedRunID,
+            RunID: runID,
+            Artifacts: hasArtifacts ? artifacts : undefined
+        };
+    }
+    /**
+     * Serializes a thrown error to a structured error `tool_response` so the model can narrate the
+     * failure (consistent with the plan's spoken-error-handling) rather than leaving the call
+     * unanswered.
+     *
+     * @param error The thrown error or message.
+     * @returns The serialized error result (always `Success: false`).
+     */
+    serializeError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ResultJson: JSON.stringify({ success: false, error: message }), Success: false };
+    }
+    /**
+     * Logs an error via the injected logger (if any), prefixed with the failing operation.
+     *
+     * @param error The thrown error or message.
+     * @param operation A short description of what was being attempted.
+     */
+    logError(error, operation) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.deps.LogError?.(`RealtimeToolBroker error while ${operation}: ${message}`);
+    }
+}
+//# sourceMappingURL=realtime-tool-broker.js.map

package/dist/realtime/realtime-tool-broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-tool-broker.js","sourceRoot":"","sources":["../../src/realtime/realtime-tool-broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;AA6KnE;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IAM3B;;OAEG;IACH,YAAY,IAA4B;QANxC,8EAA8E;QACtE,gCAA2B,GAA2B,IAAI,CAAC;QAM/D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,eAAe,CAAC,IAAsB;QAC/C,IAAI,IAAI,CAAC,QAAQ,KAAK,6BAA6B,EAAE,CAAC;YAClD,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACI,aAAa;QAChB,IAAI,IAAI,CAAC,2BAA2B,EAAE,CAAC;YACnC,IAAI,CAAC,2BAA2B,CAAC,KAAK,EAAE,CAAC;YACzC,IAAI,CAAC,2BAA2B,GAAG,IAAI,CAAC;QAC5C,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,eAAe,CAAC,IAAsB;QAChD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,IAAI,CAAC,2BAA2B,GAAG,UAAU,CAAC;QAC9C,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC;gBAC5C,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,WAAW,EAAE,UAAU,CAAC,MAAM;aACjC,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACnH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAC,CAAC;YACnD,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;gBAAS,CAAC;YACP,+FAA+F;YAC/F,IAAI,IAAI,CAAC,2BAA2B,KAAK,UAAU,EAAE,CAAC;gBAClD,IAAI,CAAC,2BAA2B,GAAG,IAAI,CAAC;YAC5C,CAAC;QACL,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,YAAY,CAAC,IAAsB;QAC7C,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;YAC1D,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACK,eAAe,CACnB,OAAgB,EAChB,MAAc,EACd,WAAoB,EACpB,KAAc,EACd,SAAkC;QAElC,MAAM,OAAO,GAKT,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACxB,IAAI,KAAK,EAAE,CAAC;YACR,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;QAC1B,CAAC;QACD,MAAM,YAAY,GAAG,SAAS,IAAI,IAAI,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAC/D,IAAI,YAAY,EAAE,CAAC;YACf,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACpC,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;gBACtC,IAAI,EAAE,CAAC,CAAC,IAAI;aACf,CAAC,CAAC,CAAC;QACR,CAAC;QACD,OAAO;YACH,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YACnC,OAAO,EAAE,OAAO;YAChB,WAAW,EAAE,WAAW;YACxB,KAAK,EAAE,KAAK;YACZ,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;SAClD,CAAC;IACN,CAAC;IAED;;;;;;;OAOG;IACK,cAAc,CAAC,KAAc;QACjC,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9F,CAAC;IAED;;;;;OAKG;IACK,QAAQ,CAAC,KAAc,EAAE,SAAiB;QAC9C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,kCAAkC,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;CACJ"}

package/dist/realtime/whiteboard-channel-server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Server-side channel plugin for the live Whiteboard — the reference
+ * `BaseRealtimeChannelServer` implementation, paired with the browser's
+ * `RealtimeWhiteboardChannel` client plugin through the seeded `MJ: AI Agent Channels` row
+ * (`Name: 'Whiteboard'`, `ServerPluginClass: 'WhiteboardChannelServer'`,
+ * `ClientPluginClass: 'RealtimeWhiteboardChannel'`).
+ *
+ * Deliberately small and honest about its job: the whiteboard executes entirely client-side, so
+ * the server half's real value is guarding the **persisted state of record** — the
+ * `MJ: AI Agent Session Channels.Config` blob a future resume rehydrates through the client
+ * plugin's `RestoreState`. This plugin validates that every save the client lands is parseable
+ * board JSON (flagging corrupt payloads loudly instead of discovering them at the next resume)
+ * and normalizes valid payloads to a canonical compact serialization.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { BaseRealtimeChannelServer } from '@memberjunction/ai';
+/**
+ * Server half of the Whiteboard interactive channel. One instance per realtime session (created
+ * by `RealtimeChannelServerHost` from the channel registry — never construct directly).
+ *
+ * Behavior on each landed state save ({@link OnChannelStateSave}):
+ *  - payload parses to a JSON **object** → persist the canonical compact re-serialization
+ *    (`JSON.stringify(parsed)`), or the original when already canonical;
+ *  - payload is malformed JSON or a non-object (array/primitive) → log loudly and keep the
+ *    original unchanged — persistence is never blocked, and the client's `RestoreState` contract
+ *    is tolerant of bad payloads, so flag-don't-drop is the safe posture.
+ */
+export declare class WhiteboardChannelServer extends BaseRealtimeChannelServer {
+    /** Matches the seeded `MJ: AI Agent Channels` row's `Name`. */
+    get ChannelName(): string;
+    /**
+     * Validates + canonicalizes a landed board-state save (see the class doc for the contract).
+     *
+     * @param stateJson The serialized board scene the client submitted.
+     * @returns The compact canonical JSON when the payload is a valid object and differs from the
+     *   input; `null` (= keep the original) otherwise.
+     */
+    OnChannelStateSave(stateJson: string): Promise<string | null>;
+    /** Flags a corrupt board payload — kept loud so it is caught before the next resume, not at it. */
+    private logInvalidState;
+}
+/**
+ * Tree-shaking prevention for {@link WhiteboardChannelServer}'s `@RegisterClass` registration.
+ * Called from a static code path in the server host (MJServer's `agentSessions` module) so the
+ * registration always executes — mirroring every other `Load...()` in the realtime stack.
+ */
+export declare function LoadWhiteboardChannelServer(): void;
+//# sourceMappingURL=whiteboard-channel-server.d.ts.map

package/dist/realtime/whiteboard-channel-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whiteboard-channel-server.d.ts","sourceRoot":"","sources":["../../src/realtime/whiteboard-channel-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAI/D;;;;;;;;;;GAUG;AACH,qBACa,uBAAwB,SAAQ,yBAAyB;IAClE,+DAA+D;IAC/D,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;;;;;OAMG;IACmB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgBnF,mGAAmG;IACnG,OAAO,CAAC,eAAe;CAO1B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/realtime/whiteboard-channel-server.js

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Server-side channel plugin for the live Whiteboard — the reference
+ * `BaseRealtimeChannelServer` implementation, paired with the browser's
+ * `RealtimeWhiteboardChannel` client plugin through the seeded `MJ: AI Agent Channels` row
+ * (`Name: 'Whiteboard'`, `ServerPluginClass: 'WhiteboardChannelServer'`,
+ * `ClientPluginClass: 'RealtimeWhiteboardChannel'`).
+ *
+ * Deliberately small and honest about its job: the whiteboard executes entirely client-side, so
+ * the server half's real value is guarding the **persisted state of record** — the
+ * `MJ: AI Agent Session Channels.Config` blob a future resume rehydrates through the client
+ * plugin's `RestoreState`. This plugin validates that every save the client lands is parseable
+ * board JSON (flagging corrupt payloads loudly instead of discovering them at the next resume)
+ * and normalizes valid payloads to a canonical compact serialization.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseRealtimeChannelServer } from '@memberjunction/ai';
+import { RegisterClass } from '@memberjunction/global';
+import { LogError } from '@memberjunction/core';
+/**
+ * Server half of the Whiteboard interactive channel. One instance per realtime session (created
+ * by `RealtimeChannelServerHost` from the channel registry — never construct directly).
+ *
+ * Behavior on each landed state save ({@link OnChannelStateSave}):
+ *  - payload parses to a JSON **object** → persist the canonical compact re-serialization
+ *    (`JSON.stringify(parsed)`), or the original when already canonical;
+ *  - payload is malformed JSON or a non-object (array/primitive) → log loudly and keep the
+ *    original unchanged — persistence is never blocked, and the client's `RestoreState` contract
+ *    is tolerant of bad payloads, so flag-don't-drop is the safe posture.
+ */
+let WhiteboardChannelServer = class WhiteboardChannelServer extends BaseRealtimeChannelServer {
+    /** Matches the seeded `MJ: AI Agent Channels` row's `Name`. */
+    get ChannelName() {
+        return 'Whiteboard';
+    }
+    /**
+     * Validates + canonicalizes a landed board-state save (see the class doc for the contract).
+     *
+     * @param stateJson The serialized board scene the client submitted.
+     * @returns The compact canonical JSON when the payload is a valid object and differs from the
+     *   input; `null` (= keep the original) otherwise.
+     */
+    async OnChannelStateSave(stateJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(stateJson);
+        }
+        catch {
+            this.logInvalidState('is not valid JSON');
+            return null;
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            this.logInvalidState('is not a JSON object');
+            return null;
+        }
+        const canonical = JSON.stringify(parsed);
+        return canonical === stateJson ? null : canonical;
+    }
+    /** Flags a corrupt board payload — kept loud so it is caught before the next resume, not at it. */
+    logInvalidState(problem) {
+        const sessionID = this.Context?.AgentSessionID ?? 'unknown';
+        LogError(`[WhiteboardChannelServer] Board state save for session ${sessionID} ${problem} — ` +
+            'persisting the payload unchanged; a future resume will start with a fresh board.');
+    }
+};
+WhiteboardChannelServer = __decorate([
+    RegisterClass(BaseRealtimeChannelServer, 'WhiteboardChannelServer')
+], WhiteboardChannelServer);
+export { WhiteboardChannelServer };
+/**
+ * Tree-shaking prevention for {@link WhiteboardChannelServer}'s `@RegisterClass` registration.
+ * Called from a static code path in the server host (MJServer's `agentSessions` module) so the
+ * registration always executes — mirroring every other `Load...()` in the realtime stack.
+ */
+export function LoadWhiteboardChannelServer() {
+    // no-op — the import + call create a static reference bundlers cannot eliminate
+}
+//# sourceMappingURL=whiteboard-channel-server.js.map

package/dist/realtime/whiteboard-channel-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whiteboard-channel-server.js","sourceRoot":"","sources":["../../src/realtime/whiteboard-channel-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;;;;;;;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD;;;;;;;;;;GAUG;AAEI,IAAM,uBAAuB,GAA7B,MAAM,uBAAwB,SAAQ,yBAAyB;IAClE,+DAA+D;IAC/D,IAAW,WAAW;QAClB,OAAO,YAAY,CAAC;IACxB,CAAC;IAED;;;;;;OAMG;IACa,KAAK,CAAC,kBAAkB,CAAC,SAAiB;QACtD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACL,IAAI,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC;YAC1C,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,eAAe,CAAC,sBAAsB,CAAC,CAAC;YAC7C,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACzC,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IAED,mGAAmG;IAC3F,eAAe,CAAC,OAAe;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,cAAc,IAAI,SAAS,CAAC;QAC5D,QAAQ,CACJ,0DAA0D,SAAS,IAAI,OAAO,KAAK;YAC/E,kFAAkF,CACzF,CAAC;IACN,CAAC;CACJ,CAAA;AArCY,uBAAuB;IADnC,aAAa,CAAC,yBAAyB,EAAE,yBAAyB,CAAC;GACvD,uBAAuB,CAqCnC;;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B;IACvC,gFAAgF;AACpF,CAAC"}