@carlonicora/nextjs-jsonapi 1.113.0 → 1.115.0

package/src/features/assistant/data/Assistant.ts

@@ -4,6 +4,7 @@ import { AssistantInput, AssistantInterface } from "./AssistantInterface";
 export class Assistant extends AbstractApiData implements AssistantInterface {
   private _title?: string;
   private _messageCount?: number;
+  private _engine?: string;
 
   get title(): string {
     return this._title ?? "";
@@ -13,9 +14,14 @@ export class Assistant extends AbstractApiData implements AssistantInterface {
     return this._messageCount ?? 0;
   }
 
+  get engine(): string | undefined {
+    return this._engine;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
     this._title = data.jsonApi.attributes?.title;
+    this._engine = data.jsonApi.attributes?.engine;
     const fromMeta = data.jsonApi.meta?.messageCount;
     const fromAttrs = data.jsonApi.attributes?.messageCount;
     this._messageCount = typeof fromMeta === "number" ? fromMeta : typeof fromAttrs === "number" ? fromAttrs : 0;

package/src/features/assistant/data/AssistantInterface.ts

@@ -10,4 +10,6 @@ export type AssistantInput = {
 export interface AssistantInterface extends ApiDataInterface {
   get title(): string;
   get messageCount(): number;
+  /** Agent engine the thread runs on — `"operator"` or undefined (responder). */
+  get engine(): string | undefined;
 }

package/src/features/assistant/data/AssistantService.ts

@@ -31,6 +31,20 @@ export class AssistantService extends AbstractService {
     });
   }
 
+  /**
+   * Creates an assistant whose first turn runs on the operator engine
+   * (durable checkpointing + approval gates). Mirrors `create()` against the
+   * standalone operator module's create route (`POST operator`).
+   */
+  static async createOperator(params: AssistantInput): Promise<AssistantInterface> {
+    return this.callApi({
+      type: Modules.Assistant,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: "operator" }).generate(),
+      input: params,
+    });
+  }
+
   /**
    * Sends a new user message to an existing assistant thread. The agent turn
    * runs synchronously; the response is a two-element list: [user, assistant].
@@ -63,6 +77,30 @@ export class AssistantService extends AbstractService {
     });
   }
 
+  /**
+   * Operator-engine variant of `appendMessage()`. Targets
+   * `POST operator/:assistantId/assistant-messages`; the turn may freeze on a
+   * destructive tool call, in which case the returned list ends with an
+   * `approval-request` assistant message linked to a pending AssistantAction.
+   */
+  static async appendMessageOperator(params: {
+    assistantId: string;
+    content: string;
+  }): Promise<AssistantMessageInterface[]> {
+    const message = new AssistantMessage();
+    return this.callApi<AssistantMessageInterface[]>({
+      type: Modules.AssistantMessage,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: "operator",
+        id: params.assistantId,
+        childEndpoint: Modules.AssistantMessage,
+      }).generate(),
+      input: message.createAppendMessageJsonApi({ content: params.content }),
+      overridesJsonApiCreation: true,
+    });
+  }
+
   static async rename(params: { id: string; title: string }): Promise<void> {
     await this.callApi({
       type: Modules.Assistant,

package/src/features/assistant/data/__tests__/Assistant.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { Assistant } from "../Assistant";
+
+describe("Assistant model", () => {
+  it("rehydrates engine from attributes (operator thread)", () => {
+    const assistant = new Assistant().rehydrate({
+      jsonApi: { type: "assistants", id: "a-1", attributes: { title: "T", engine: "operator" } },
+      included: [],
+    });
+    expect(assistant.engine).toBe("operator");
+    expect(assistant.title).toBe("T");
+  });
+
+  it("leaves engine undefined when the attribute is absent (responder thread)", () => {
+    const assistant = new Assistant().rehydrate({
+      jsonApi: { type: "assistants", id: "a-2", attributes: { title: "T" } },
+      included: [],
+    });
+    expect(assistant.engine).toBeUndefined();
+  });
+
+  it("preserves engine through dehydrate/rehydrate round-trips", () => {
+    const original = new Assistant().rehydrate({
+      jsonApi: { type: "assistants", id: "a-3", attributes: { title: "T", engine: "operator" } },
+      included: [],
+    });
+    const roundTripped = new Assistant().rehydrate(original.dehydrate());
+    expect(roundTripped.engine).toBe("operator");
+  });
+});

package/src/features/assistant-message/AssistantMessageModule.ts

@@ -21,8 +21,10 @@ export const AssistantMessageModule = (factory: ModuleFactory) =>
             `suggestedQuestions`,
             `inputTokens`,
             `outputTokens`,
+            `messageType`,
             `references`,
             `citations`,
+            `action`,
           ]),
           createJsonApiInclusion("chunks", [`content`, `nodeId`, `nodeType`, `imagePath`, `source`]),
           createJsonApiInclusion("users", [`name`, `avatar`]),

package/src/features/assistant-message/components/MessageItem.tsx

@@ -2,20 +2,36 @@
 
 import { useTranslations } from "next-intl";
 import { Sparkles, AlertCircle } from "lucide-react";
+import type { ReactNode } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import type { AssistantMessageInterface } from "../data/AssistantMessageInterface";
 import { MessageSourcesContainer } from "./parts/MessageSourcesContainer";
 
+/**
+ * Render slot for `approval-request` messages. The approval card lives in the
+ * consuming app (it depends on the app-registered AssistantAction module), so
+ * the chat renderer receives it as a function instead of importing it.
+ */
+export type ApprovalActionRenderer = (message: AssistantMessageInterface) => ReactNode;
+
 interface Props {
   message: AssistantMessageInterface;
   isLatestAssistant: boolean;
   onSelectFollowUp: (q: string) => void;
   failedMessageIds?: Set<string>;
   onRetry?: (tempId: string) => void;
+  renderApprovalAction?: ApprovalActionRenderer;
 }
 
-export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, failedMessageIds, onRetry }: Props) {
+export function MessageItem({
+  message,
+  isLatestAssistant,
+  onSelectFollowUp,
+  failedMessageIds,
+  onRetry,
+  renderApprovalAction,
+}: Props) {
   const t = useTranslations();
   const isUser = message.role === "user";
   const isFailed = isUser && !!failedMessageIds?.has(message.id);
@@ -39,6 +55,8 @@ export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, fail
     );
   }
 
+  const isApprovalRequest = message.messageType === "approval-request" && !!renderApprovalAction;
+
   return (
     <div className="flex min-w-0 max-w-[78%] flex-col gap-1.5">
       <div className="text-muted-foreground flex items-center gap-2 pl-1 text-xs">
@@ -47,9 +65,13 @@ export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, fail
         </span>
         <span>{t("features.assistant.agent_name")}</span>
       </div>
-      <div className="bg-muted text-foreground rounded-2xl rounded-bl-sm px-3.5 py-2.5 text-sm leading-relaxed">
-        <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.content}</ReactMarkdown>
-      </div>
+      {isApprovalRequest ? (
+        renderApprovalAction(message)
+      ) : (
+        <div className="bg-muted text-foreground rounded-2xl rounded-bl-sm px-3.5 py-2.5 text-sm leading-relaxed">
+          <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.content}</ReactMarkdown>
+        </div>
+      )}
       <MessageSourcesContainer
         message={message}
         isLatestAssistant={isLatestAssistant}

package/src/features/assistant-message/components/MessageList.tsx

@@ -1,16 +1,17 @@
 "use client";
 
 import { AssistantMessageInterface } from "../data/AssistantMessageInterface";
-import { MessageItem } from "./MessageItem";
+import { MessageItem, type ApprovalActionRenderer } from "./MessageItem";
 
 interface Props {
   messages: AssistantMessageInterface[];
   onSelectFollowUp: (q: string) => void;
   failedMessageIds?: Set<string>;
   onRetry?: (tempId: string) => void;
+  renderApprovalAction?: ApprovalActionRenderer;
 }
 
-export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRetry }: Props) {
+export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRetry, renderApprovalAction }: Props) {
   const ordered = [...messages].sort((a, b) => a.position - b.position);
 
   let lastAssistantIndex = -1;
@@ -31,6 +32,7 @@ export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRe
           onSelectFollowUp={onSelectFollowUp}
           failedMessageIds={failedMessageIds}
           onRetry={onRetry}
+          renderApprovalAction={renderApprovalAction}
         />
       ))}
     </div>

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -1,6 +1,11 @@
 import { v4 as uuidv4 } from "uuid";
 import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
-import { AssistantMessageInput, AssistantMessageInterface, AssistantMessageRole } from "./AssistantMessageInterface";
+import {
+  AssistantMessageInput,
+  AssistantMessageInterface,
+  AssistantMessageRole,
+  AssistantMessageType,
+} from "./AssistantMessageInterface";
 import { resolveReferenceableModules } from "../../assistant/utils/resolveReferenceableModules";
 import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInterface";
 
@@ -14,6 +19,8 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
   private _references?: ApiDataInterface[];
   private _citations?: (ChunkInterface & ChunkRelationshipMeta)[];
   private _isOptimistic = false;
+  private _messageType?: AssistantMessageType;
+  private _actionId?: string;
 
   get role(): AssistantMessageRole {
     return this._role ?? "assistant";
@@ -51,6 +58,14 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     return this._isOptimistic;
   }
 
+  get messageType(): AssistantMessageType {
+    return this._messageType ?? "text";
+  }
+
+  get actionId(): string | undefined {
+    return this._actionId;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
     const attrs = data.jsonApi.attributes ?? {};
@@ -60,6 +75,11 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     this._suggestedQuestions = Array.isArray(attrs.suggestedQuestions) ? attrs.suggestedQuestions : [];
     this._inputTokens = attrs.inputTokens;
     this._outputTokens = attrs.outputTokens;
+    this._messageType = attrs.messageType as AssistantMessageType | undefined;
+    // The AssistantAction module is app-registered, so only the raw
+    // relationship id is exposed (no hydration of the included resource here).
+    const actionRelationship = data.jsonApi.relationships?.action?.data;
+    this._actionId = Array.isArray(actionRelationship) ? actionRelationship[0]?.id : actionRelationship?.id;
     const refs = this._readIncludedPolymorphic<ApiDataInterface>(data, "references", resolveReferenceableModules());
     this._references = Array.isArray(refs) ? refs : refs ? [refs] : [];
     if (data.jsonApi.relationships?.citations?.data) {

package/src/features/assistant-message/data/AssistantMessageInterface.ts

@@ -3,6 +3,14 @@ import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInt
 
 export type AssistantMessageRole = "user" | "assistant" | "system";
 
+/**
+ * "text" is the default chat message; "approval-request" marks the message
+ * created while an operator run is frozen on a destructive tool call,
+ * awaiting human approval (linked AssistantAction via the `action`
+ * relationship).
+ */
+export type AssistantMessageType = "text" | "approval-request";
+
 export type AssistantMessageInput = {
   id: string;
   role: AssistantMessageRole;
@@ -21,4 +29,12 @@ export interface AssistantMessageInterface extends ApiDataInterface {
   get references(): ApiDataInterface[];
   get citations(): (ChunkInterface & ChunkRelationshipMeta)[];
   get isOptimistic(): boolean;
+  get messageType(): AssistantMessageType;
+  /**
+   * Id of the AssistantAction linked through the `action` relationship.
+   * Only present on `approval-request` messages. Exposed as a raw id (not a
+   * hydrated model) because the AssistantAction module is registered by the
+   * consuming app, not by this library.
+   */
+  get actionId(): string | undefined;
 }