@nocobase/portal-template-default 1.0.1 → 1.0.3

package/src/extensions/nocobase-ai/providers/frontend-tool-registry.tsx

@@ -0,0 +1,231 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type PropsWithChildren,
+} from "react";
+import type { AIToolCallInvocationContext, AIToolInvokerMap } from "./types";
+
+export type AIFrontendToolPermission = "ASK" | "ALLOW";
+
+export type AIFrontendToolRegistration<
+  TArgs = unknown,
+  TResult = unknown,
+> = {
+  name: string;
+  title?: string;
+  description: string;
+  permission?: AIFrontendToolPermission;
+  inputSchema?: Record<string, unknown>;
+  execute: (args: TArgs) => TResult | Promise<TResult>;
+};
+
+export type AIFrontendToolManifest = {
+  id: string;
+  blockUid: string;
+  name: string;
+  title?: string;
+  description: string;
+  permission: AIFrontendToolPermission;
+  inputSchema: Record<string, unknown>;
+};
+
+type AIFrontendToolEntry = {
+  token: symbol;
+  manifest: AIFrontendToolManifest;
+  execute: (args: unknown) => unknown | Promise<unknown>;
+};
+
+const TOOL_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+const cloneManifest = (
+  manifest: AIFrontendToolManifest
+): AIFrontendToolManifest => structuredClone(manifest);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+export function defineAIFrontendTool<TArgs, TResult>(
+  registration: AIFrontendToolRegistration<TArgs, TResult>
+) {
+  return registration;
+}
+
+export class AIFrontendToolRegistry {
+  private readonly tools = new Map<string, AIFrontendToolEntry>();
+
+  register(contextId: string, registration: AIFrontendToolRegistration) {
+    if (!contextId.trim()) {
+      throw new Error("Frontend Tool context id is required");
+    }
+    if (!TOOL_NAME_PATTERN.test(registration.name)) {
+      throw new Error(
+        "Frontend Tool name must start with a letter and contain only letters, numbers, underscores, or hyphens"
+      );
+    }
+    if (!registration.description.trim()) {
+      throw new Error("Frontend Tool description is required");
+    }
+    if (typeof registration.execute !== "function") {
+      throw new Error("Frontend Tool execute must be a function");
+    }
+    if (
+      registration.inputSchema !== undefined &&
+      !isRecord(registration.inputSchema)
+    ) {
+      throw new Error("Frontend Tool inputSchema must be an object");
+    }
+    if (
+      registration.permission !== undefined &&
+      registration.permission !== "ASK" &&
+      registration.permission !== "ALLOW"
+    ) {
+      throw new Error("Frontend Tool permission must be ASK or ALLOW");
+    }
+
+    const id = `${contextId}:${registration.name}`;
+    if (this.tools.has(id)) {
+      throw new Error(
+        `Frontend Tool "${registration.name}" is already registered for context "${contextId}"`
+      );
+    }
+    const token = Symbol(id);
+    let inputSchema: Record<string, unknown>;
+    try {
+      inputSchema = structuredClone(
+        registration.inputSchema ?? { type: "object", properties: {} }
+      );
+    } catch {
+      throw new Error("Frontend Tool inputSchema must be serializable");
+    }
+    const manifest: AIFrontendToolManifest = {
+      id,
+      blockUid: contextId,
+      name: registration.name,
+      title: registration.title,
+      description: registration.description,
+      permission: registration.permission ?? "ASK",
+      inputSchema,
+    };
+    this.tools.set(id, {
+      token,
+      manifest,
+      execute: registration.execute as (
+        args: unknown
+      ) => unknown | Promise<unknown>,
+    });
+    return () => {
+      if (this.tools.get(id)?.token === token) this.tools.delete(id);
+    };
+  }
+
+  list(contextId: string) {
+    return [...this.tools.values()]
+      .filter((entry) => entry.manifest.blockUid === contextId)
+      .map((entry) => cloneManifest(entry.manifest));
+  }
+
+  getManifest(toolId: string) {
+    const manifest = this.tools.get(toolId)?.manifest;
+    return manifest ? cloneManifest(manifest) : undefined;
+  }
+
+  async execute(toolId: string, args: unknown) {
+    const entry = this.tools.get(toolId);
+    if (!entry) throw new Error(`Frontend Tool "${toolId}" is unavailable`);
+    const result = await entry.execute(args);
+    try {
+      structuredClone(result);
+      JSON.stringify(result);
+    } catch {
+      throw new Error(
+        `Frontend Tool "${toolId}" returned a non-serializable result`
+      );
+    }
+    return result;
+  }
+}
+
+const AIFrontendToolRegistryContext =
+  createContext<AIFrontendToolRegistry | null>(null);
+
+export function AIFrontendToolRegistryProvider({
+  children,
+}: PropsWithChildren) {
+  const registry = useMemo(() => new AIFrontendToolRegistry(), []);
+  return (
+    <AIFrontendToolRegistryContext.Provider value={registry}>
+      {children}
+    </AIFrontendToolRegistryContext.Provider>
+  );
+}
+
+export function useAIFrontendToolRegistry() {
+  const registry = useContext(AIFrontendToolRegistryContext);
+  if (!registry) {
+    throw new Error(
+      "useAIFrontendToolRegistry must be used inside AIFrontendToolRegistryProvider"
+    );
+  }
+  return registry;
+}
+
+export function useOptionalAIFrontendToolRegistry() {
+  return useContext(AIFrontendToolRegistryContext);
+}
+
+const errorResult = (error: unknown) => ({
+  status: "error" as const,
+  content: error instanceof Error ? error.message : String(error),
+});
+
+const getToolId = (input: unknown) =>
+  input && typeof input === "object" && !Array.isArray(input)
+    ? (input as { toolId?: unknown }).toolId
+    : undefined;
+
+const isToolAllowed = (
+  toolId: string,
+  context: AIToolCallInvocationContext
+) => context.allowedFrontendToolIds?.includes(toolId) === true;
+
+export function createFrontendToolInvokers(
+  registry: AIFrontendToolRegistry
+): AIToolInvokerMap {
+  return {
+    loadFrontendTool: async (input, context) => {
+      const toolId = getToolId(input);
+      if (typeof toolId !== "string" || !toolId) {
+        return errorResult("Frontend Tool id is required");
+      }
+      if (!isToolAllowed(toolId, context)) {
+        return errorResult(
+          `Frontend Tool "${toolId}" is not available in this conversation context`
+        );
+      }
+      return (
+        registry.getManifest(toolId) ??
+        errorResult(`Frontend Tool "${toolId}" is unavailable`)
+      );
+    },
+    executeFrontendTool: async (input, context) => {
+      const params =
+        input && typeof input === "object" && !Array.isArray(input)
+          ? (input as { toolId?: unknown; args?: unknown })
+          : {};
+      if (typeof params.toolId !== "string" || !params.toolId) {
+        return errorResult("Frontend Tool id is required");
+      }
+      if (!isToolAllowed(params.toolId, context)) {
+        return errorResult(
+          `Frontend Tool "${params.toolId}" is not available in this conversation context`
+        );
+      }
+      try {
+        return await registry.execute(params.toolId, params.args ?? {});
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  };
+}

package/src/extensions/nocobase-ai/providers/index.ts

@@ -0,0 +1,61 @@
+export {
+  AIProvider,
+  useAI,
+  useGlobalAIChatController,
+  type AIProviderProps,
+} from "./ai-provider";
+export { AIChatProvider, type AIChatProviderProps } from "./chat-provider";
+export {
+  useAIChat,
+  useAIChatBase,
+  useAIChatMessages,
+  useAIChatStatus,
+  type AIChatBaseContextValue,
+  type AIChatContextValue,
+  type AIChatMessagesContextValue,
+  type AIChatStatusContextValue,
+} from "./chat-context";
+export {
+  createAIChatController,
+  useAIChatController,
+  useAIChatControllerState,
+  type AIChatController,
+  type AIChatControllerSnapshot,
+} from "./chat-controller";
+export { NocoBaseChatTransport } from "./chat-transport";
+export { getAIEmployeeAvatar } from "./avatars";
+export { findAIModel, getAIModelKey, groupAIModels } from "./model";
+export type { AIModelGroup } from "./model";
+export {
+  AIFormRegistry,
+  AIFormRegistryProvider,
+  createFormFillerInvoker,
+  useAIFormRegistry,
+  type AIFormField,
+  type AIFormFillResult,
+  type AIFormFillSkippedField,
+  type AIFormTarget,
+} from "./form-registry";
+export {
+  AIFrontendToolRegistry,
+  AIFrontendToolRegistryProvider,
+  createFrontendToolInvokers,
+  defineAIFrontendTool,
+  useAIFrontendToolRegistry,
+  useOptionalAIFrontendToolRegistry,
+  type AIFrontendToolManifest,
+  type AIFrontendToolPermission,
+  type AIFrontendToolRegistration,
+} from "./frontend-tool-registry";
+export {
+  AIPageContextResolverProvider,
+  AIPageContextScope,
+  createAIPageContextReference,
+  getAIWorkContextRequiredTools,
+  getAIWorkContextToolScope,
+  mergeAIRequiredTools,
+  useAIPageContextScope,
+  useAIPageContextResolver,
+  type AIPageContextResolver,
+} from "./page-context";
+export type * from "./types";

package/src/extensions/nocobase-ai/providers/model.ts

@@ -0,0 +1,32 @@
+import type { AIModel } from "./types";
+
+export type AIModelGroup = {
+  key: string;
+  label: string;
+  models: AIModel[];
+};
+
+export function getAIModelKey(model: AIModel) {
+  return model.llmService ? `${model.llmService}:${model.value}` : model.value;
+}
+
+export function findAIModel(models: AIModel[], key: string) {
+  return models.find((model) => getAIModelKey(model) === key);
+}
+
+export function groupAIModels(models: AIModel[]): AIModelGroup[] {
+  const groups = new Map<string, AIModelGroup>();
+
+  for (const model of models) {
+    const key = model.llmService ?? "__models__";
+    const group = groups.get(key) ?? {
+      key,
+      label: model.llmServiceTitle ?? model.llmService ?? "Models",
+      models: [],
+    };
+    group.models.push(model);
+    groups.set(key, group);
+  }
+
+  return Array.from(groups.values());
+}

package/src/extensions/nocobase-ai/providers/page-context.tsx

@@ -0,0 +1,136 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type PropsWithChildren,
+} from "react";
+import type {
+  AIEmployeeTask,
+  AIWorkContextItem,
+} from "./types";
+
+export type AIPageContextResolver = (
+  items: AIWorkContextItem[]
+) => Promise<AIWorkContextItem[]>;
+
+const AIPageContextResolverContext = createContext<
+  AIPageContextResolver | undefined
+>(undefined);
+
+export function AIPageContextResolverProvider({
+  resolve,
+  children,
+}: PropsWithChildren<{ resolve: AIPageContextResolver }>) {
+  return (
+    <AIPageContextResolverContext.Provider value={resolve}>
+      {children}
+    </AIPageContextResolverContext.Provider>
+  );
+}
+
+export const useAIPageContextResolver = () =>
+  useContext(AIPageContextResolverContext);
+
+const EMPTY_PAGE_CONTEXT: AIWorkContextItem[] = [];
+const AIPageContextScopeContext = createContext(EMPTY_PAGE_CONTEXT);
+
+export function AIPageContextScope({
+  context,
+  mode = "replace",
+  children,
+}: PropsWithChildren<{
+  context: AIWorkContextItem | AIWorkContextItem[];
+  mode?: "replace" | "append";
+}>) {
+  const inheritedContext = useContext(AIPageContextScopeContext);
+  const value = useMemo(
+    () => {
+      const ownContext = Array.isArray(context) ? context : [context];
+      if (mode !== "append") return ownContext;
+      const combined = [...inheritedContext, ...ownContext];
+      return combined.filter((item, index) => {
+        if (!item.id) return true;
+        return (
+          combined.findLastIndex(
+            (candidate) =>
+              candidate.type === item.type && candidate.id === item.id
+          ) === index
+        );
+      });
+    },
+    [context, inheritedContext, mode]
+  );
+  return (
+    <AIPageContextScopeContext.Provider value={value}>
+      {children}
+    </AIPageContextScopeContext.Provider>
+  );
+}
+
+export const useAIPageContextScope = () =>
+  useContext(AIPageContextScopeContext);
+
+export function createAIPageContextReference({
+  id,
+  title,
+  kind,
+}: {
+  id: string;
+  title: string;
+  kind?: string;
+}): AIWorkContextItem {
+  return {
+    type: "page-element",
+    id,
+    title,
+    ...(kind ? { kind } : {}),
+  };
+}
+
+const isFormContext = (item: AIWorkContextItem) => {
+  if (item.kind === "form") return true;
+  if (!item.content || typeof item.content !== "object") return false;
+  const content = item.content as Record<string, unknown>;
+  return typeof content.form === "string" && Array.isArray(content.fields);
+};
+
+export function getAIWorkContextRequiredTools(items: AIWorkContextItem[]) {
+  return items.some(isFormContext) ? ["formFiller"] : [];
+}
+
+export function getAIWorkContextToolScope(items: AIWorkContextItem[]) {
+  const frontendToolIds = new Set<string>();
+  const formIds = new Set<string>();
+  for (const item of items) {
+    if (Array.isArray(item.frontendTools)) {
+      for (const tool of item.frontendTools) {
+        if (
+          tool &&
+          typeof tool === "object" &&
+          typeof (tool as { id?: unknown }).id === "string"
+        ) {
+          frontendToolIds.add((tool as { id: string }).id);
+        }
+      }
+    }
+    if (isFormContext(item)) {
+      const form = (item.content as { form?: unknown } | undefined)?.form;
+      if (typeof form === "string" && form) formIds.add(form);
+    }
+  }
+  return {
+    allowedFrontendToolIds: [...frontendToolIds],
+    allowedFormIds: [...formIds],
+  };
+}
+
+export function mergeAIRequiredTools(
+  skillSettings: AIEmployeeTask["skillSettings"],
+  requiredTools: string[]
+): AIEmployeeTask["skillSettings"] {
+  if (!requiredTools.length) return skillSettings;
+  return {
+    ...skillSettings,
+    tools: [...new Set([...(skillSettings?.tools ?? []), ...requiredTools])],
+  };
+}

package/src/extensions/nocobase-ai/providers/stream-coalescer.ts

@@ -0,0 +1,60 @@
+export type StreamCoalescerOptions<Key, Value> = {
+  interval: number;
+  maxSize: number;
+  getSize: (value: Value) => number;
+  merge: (current: Value, incoming: Value) => Value;
+  onFlush: (key: Key, value: Value) => void;
+};
+
+type PendingValue<Value> = {
+  value: Value;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+export class StreamCoalescer<Key, Value> {
+  private readonly pending = new Map<Key, PendingValue<Value>>();
+
+  constructor(private readonly options: StreamCoalescerOptions<Key, Value>) {}
+
+  push(key: Key, value: Value) {
+    const existing = this.pending.get(key);
+    if (existing) {
+      existing.value = this.options.merge(existing.value, value);
+      if (this.options.getSize(existing.value) >= this.options.maxSize) {
+        this.flush(key);
+      }
+      return;
+    }
+
+    const timer = setTimeout(() => this.flush(key), this.options.interval);
+    this.pending.set(key, { value, timer });
+    if (this.options.getSize(value) >= this.options.maxSize) {
+      this.flush(key);
+    }
+  }
+
+  has(key: Key) {
+    return this.pending.has(key);
+  }
+
+  flush(key: Key) {
+    const pending = this.pending.get(key);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.pending.delete(key);
+    this.options.onFlush(key, pending.value);
+  }
+
+  flushAll() {
+    for (const key of [...this.pending.keys()]) {
+      this.flush(key);
+    }
+  }
+
+  clear() {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+    }
+    this.pending.clear();
+  }
+}

package/src/extensions/nocobase-ai/providers/stream-event-utils.ts

@@ -0,0 +1,82 @@
+import type { NocoBaseStreamEvent } from "./stream-parser";
+
+export type NocoBaseToolCall = {
+  id?: string;
+  index?: number;
+  name?: string;
+  args?: unknown;
+  input?: unknown;
+  output?: unknown;
+  content?: unknown;
+  status?: string;
+  invokeStatus?: string;
+  invokeStartTime?: unknown;
+  invokeEndTime?: unknown;
+  messageId?: string;
+  willInterrupt?: boolean;
+  auto?: boolean;
+  selectedSuggestion?: string;
+};
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+export const toolCallsFromEvent = (event: NocoBaseStreamEvent) => {
+  if (Array.isArray(event.body)) return event.body as NocoBaseToolCall[];
+  if (!isRecord(event.body) || !Array.isArray(event.body.toolCalls)) return [];
+  return event.body.toolCalls as NocoBaseToolCall[];
+};
+
+export const parseToolInput = (input: unknown) => {
+  if (typeof input !== "string") return input;
+  try {
+    return JSON.parse(input) as unknown;
+  } catch {
+    return input;
+  }
+};
+
+const completedToolStatus = new Set(["success", "done", "confirmed"]);
+const failedToolStatus = new Set(["error", "failed", "rejected"]);
+const pendingInvokeStatus = new Set([
+  "interrupted",
+  "waiting",
+  "pending",
+  "running",
+]);
+
+export const getToolCallState = (toolCall: NocoBaseToolCall) => {
+  const invokeStatus = String(toolCall.invokeStatus ?? "").toLowerCase();
+  const resultStatus = String(toolCall.status ?? "").toLowerCase();
+  const failed =
+    failedToolStatus.has(invokeStatus) || failedToolStatus.has(resultStatus);
+  const completed =
+    !failed &&
+    (completedToolStatus.has(invokeStatus) ||
+      (!invokeStatus && completedToolStatus.has(resultStatus)));
+  return {
+    invokeStatus,
+    resultStatus,
+    failed,
+    completed,
+    pending: !failed && !completed && pendingInvokeStatus.has(invokeStatus),
+  };
+};
+
+export const getToolProviderMetadata = (toolCall: NocoBaseToolCall) => {
+  const { invokeStatus, resultStatus } = getToolCallState(toolCall);
+  return {
+    nocobase: {
+      requiresApproval:
+        (invokeStatus === "interrupted" ||
+          (!invokeStatus && toolCall.willInterrupt === true)) &&
+        toolCall.auto !== true,
+      autoApprove: invokeStatus === "interrupted" && toolCall.auto === true,
+      invokeStatus,
+      ...(typeof toolCall.selectedSuggestion === "string"
+        ? { selectedSuggestion: toolCall.selectedSuggestion }
+        : {}),
+      status: resultStatus,
+    },
+  };
+};

package/src/extensions/nocobase-ai/providers/stream-parser.ts

@@ -0,0 +1,61 @@
+import {
+  createParser,
+  type EventSourceMessage,
+  type ParseError,
+} from "eventsource-parser";
+
+export type NocoBaseStreamEvent = {
+  type: string;
+  body?: unknown;
+  sessionId?: string;
+  from?: string;
+  username?: string;
+  errorName?: string;
+};
+
+const MAX_SSE_BUFFER_SIZE = 16 * 1024 * 1024;
+
+export async function* parseNocoBaseSSE(
+  stream: ReadableStream<Uint8Array>
+): AsyncGenerator<NocoBaseStreamEvent> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  const events: EventSourceMessage[] = [];
+  let parseError: ParseError | undefined;
+  const parser = createParser({
+    maxBufferSize: MAX_SSE_BUFFER_SIZE,
+    onEvent: (event) => events.push(event),
+    onError: (error) => {
+      parseError = error;
+    },
+  });
+
+  const drainEvents = function* () {
+    while (events.length) {
+      const event = events.shift();
+      if (!event) continue;
+      const payload = event.data.trim();
+      if (!payload || payload === "[DONE]") continue;
+      yield JSON.parse(payload) as NocoBaseStreamEvent;
+    }
+  };
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (value) parser.feed(decoder.decode(value, { stream: true }));
+      if (parseError) throw parseError;
+      yield* drainEvents();
+      if (!done) continue;
+
+      const remainder = decoder.decode();
+      if (remainder) parser.feed(remainder);
+      parser.reset({ consume: true });
+      if (parseError) throw parseError;
+      yield* drainEvents();
+      return;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}