@tulip-systems/ai 0.11.0

package/src/mcp/lib/content.ts

@@ -0,0 +1,131 @@
+import type { McpResourceContent, McpToolResult } from "./types";
+
+/**
+ * Creates a plain text MCP tool result.
+ *
+ * @example
+ * ```ts
+ * resolveMCPTool(getStatus, {
+ *   content: ({ output }) => text(`Status: ${output.status}`),
+ * });
+ * ```
+ */
+export function text(value: string, options?: { isError?: boolean }): McpToolResult {
+  return {
+    content: [{ type: "text", text: value }],
+    isError: options?.isError,
+  };
+}
+
+/**
+ * Creates a JSON MCP tool result with structured content preserved for clients that support it.
+ *
+ * @example
+ * ```ts
+ * resolveMCPTool(createProspect, {
+ *   content: ({ output }) => json(output, { label: "Created prospect:" }),
+ * });
+ * ```
+ */
+export function json<TValue>(
+  value: TValue,
+  options?: { label?: string; isError?: boolean },
+): McpToolResult<TValue> {
+  const serialized = JSON.stringify(value, null, 2);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: options?.label ? `${options.label}\n\n${serialized}` : serialized,
+      },
+    ],
+    structuredContent: value,
+    isError: options?.isError,
+  };
+}
+
+/**
+ * Creates an MCP resource result for text, blob, or URI-backed resources.
+ *
+ * @example
+ * ```ts
+ * resolveMCPTool(getInvoice, {
+ *   content: ({ output }) =>
+ *     resource({ uri: output.uri, mimeType: "application/pdf" }),
+ * });
+ * ```
+ */
+export function resource(value: McpResourceContent["resource"]): McpToolResult {
+  return {
+    content: [{ type: "resource", resource: value }],
+  };
+}
+
+/**
+ * Creates a markdown table MCP result and keeps the original rows as structured content.
+ *
+ * @example
+ * ```ts
+ * resolveMCPTool(listCustomers, {
+ *   content: ({ output }) =>
+ *     table(output.customers, {
+ *       title: "Customers",
+ *       columns: ["id", "name"],
+ *     }),
+ * });
+ * ```
+ */
+export function table<TRow extends Record<string, unknown>>(
+  rows: TRow[],
+  options?: {
+    columns?: Array<keyof TRow & string>;
+    emptyText?: string;
+    title?: string;
+  },
+): McpToolResult<{ columns: string[]; rows: TRow[] }> {
+  const columns = options?.columns ?? getColumns(rows);
+
+  if (rows.length === 0 || columns.length === 0) {
+    return {
+      content: [{ type: "text", text: options?.emptyText ?? "No results." }],
+      structuredContent: { columns, rows },
+    };
+  }
+
+  const header = `| ${columns.join(" | ")} |`;
+  const separator = `| ${columns.map(() => "---").join(" | ")} |`;
+  const body = rows.map(
+    (row) => `| ${columns.map((column) => formatCell(row[column])).join(" | ")} |`,
+  );
+  const table = [header, separator, ...body].join("\n");
+
+  return {
+    content: [{ type: "text", text: options?.title ? `${options.title}\n\n${table}` : table }],
+    structuredContent: { columns, rows },
+  };
+}
+
+function getColumns<TRow extends Record<string, unknown>>(rows: TRow[]) {
+  return Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
+}
+
+function formatCell(value: unknown) {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (typeof value === "object") {
+    return escapeMarkdownTableCell(JSON.stringify(value));
+  }
+
+  return escapeMarkdownTableCell(String(value));
+}
+
+function escapeMarkdownTableCell(value: string) {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}

package/src/mcp/lib/types.ts

@@ -0,0 +1,28 @@
+export type McpTextContent = {
+  type: "text";
+  text: string;
+};
+
+export type McpImageContent = {
+  type: "image";
+  data: string;
+  mimeType: string;
+};
+
+export type McpResourceContent = {
+  type: "resource";
+  resource: {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+  };
+};
+
+export type McpContent = McpTextContent | McpImageContent | McpResourceContent;
+
+export type McpToolResult<TStructuredContent = unknown> = {
+  content: McpContent[];
+  structuredContent?: TStructuredContent;
+  isError?: boolean;
+};

package/src/styles.css

@@ -0,0 +1 @@
+@source ".";

package/src/tools/entry.client.ts

@@ -0,0 +1,7 @@
+"use client";
+
+/**
+ * Lib
+ */
+export * from "./lib/definitions.client";
+export * from "./lib/types.client";

package/src/tools/entry.server.ts

@@ -0,0 +1,11 @@
+/**
+ * Lib
+ */
+export * from "./lib/definitions";
+export * from "./lib/types";
+
+/**
+ * Resolvers
+ */
+export * from "./resolvers/agent.server";
+export * from "./resolvers/mcp.server";

package/src/tools/lib/definitions.client.ts

@@ -0,0 +1,21 @@
+import type { ToolClientDefinition, ToolClientSource } from "./types.client";
+
+/**
+ * Defines how a server-side tool should be rendered in client chat UI.
+ * Use `import type` with the server tool to keep client bundles free of server code.
+ *
+ * @example
+ * ```tsx
+ * import type { webSearchTool } from "./tool.server";
+ *
+ * export const webSearchToolClient = defineToolClient<typeof webSearchTool>({
+ *   toolName: "web_search",
+ *   render: (part) => <ToolCallCard part={part} title="Web Search" />,
+ * });
+ * ```
+ */
+export function defineToolClient<const TTool extends ToolClientSource>(
+  definition: ToolClientDefinition<TTool>,
+) {
+  return definition;
+}

package/src/tools/lib/definitions.ts

@@ -0,0 +1,24 @@
+import "server-cli-only";
+
+import type { ToolContext, TulipToolDefinition, TulipToolSet } from "./types";
+
+/**
+ * Defines the canonical Tulip tool shape without binding it to a specific transport.
+ * Resolvers adapt this definition for agents, MCP, UI, auditing, or permissions later.
+ */
+export function defineTool<
+  const TName extends string,
+  TInput,
+  TOutput,
+  TContext extends ToolContext = ToolContext,
+>(definition: TulipToolDefinition<TName, TInput, TOutput, TContext>) {
+  return definition;
+}
+
+/**
+ * Groups multiple Tulip tool definitions while preserving their literal names and types.
+ * Use this before resolving a shared set of tools for an agent or MCP endpoint.
+ */
+export function defineToolSet<const TTools extends TulipToolSet>(tools: TTools) {
+  return tools;
+}

package/src/tools/lib/types.client.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from "react";
+import type { ToolChatPart } from "../../chat/lib/types";
+
+export type ToolClientSource = {
+  name: string;
+};
+
+export type ToolClientDefinition<TTool extends ToolClientSource = ToolClientSource> = {
+  toolName: TTool["name"];
+  render: (part: ToolChatPart) => ReactNode;
+};

package/src/tools/lib/types.ts

@@ -0,0 +1,44 @@
+import type { FlexibleSchema, ToolExecuteFunction, ToolExecutionOptions } from "ai";
+
+export type ToolContext = Record<string, unknown>;
+
+export type ToolConfirmation =
+  | false
+  | {
+      required?: boolean;
+      title?: string;
+      description?: string;
+      destructive?: boolean;
+    };
+
+export type ToolAudit = {
+  action: string;
+  resource?: string;
+  severity?: "low" | "medium" | "high";
+};
+
+export type ToolDisplay = {
+  label?: string;
+  description?: string;
+  icon?: string;
+};
+
+export type TulipToolDefinition<
+  TName extends string = string,
+  TInput = unknown,
+  TOutput = unknown,
+  TContext extends ToolContext = ToolContext,
+> = {
+  name: TName;
+  title: string;
+  description: string;
+  inputSchema: FlexibleSchema<TInput>;
+  outputSchema?: FlexibleSchema<TOutput>;
+  contextSchema?: FlexibleSchema<TContext>;
+  execute: ToolExecuteFunction<TInput, TOutput, TContext>;
+};
+
+export type TulipToolSet = Record<string, TulipToolDefinition>;
+
+export type TulipToolExecutionOptions<TContext extends ToolContext = ToolContext> =
+  ToolExecutionOptions<TContext>;

package/src/tools/resolvers/agent.server.ts

@@ -0,0 +1,78 @@
+import "server-cli-only";
+
+import { type Tool, type ToolExecuteFunction, tool } from "ai";
+import type {
+  ToolAudit,
+  ToolConfirmation,
+  ToolContext,
+  ToolDisplay,
+  TulipToolDefinition,
+  TulipToolSet,
+} from "../lib/types";
+
+export type AgentToolResolverOptions = {
+  title?: string;
+  description?: string;
+  permissions?: string[];
+  confirmation?: ToolConfirmation;
+  audit?: ToolAudit;
+  ui?: ToolDisplay;
+};
+
+/**
+ * Resolves a Tulip tool definition into an AI SDK tool for internal agents.
+ * Agent-specific metadata lives here so the base tool remains reusable by MCP and UI layers.
+ */
+export function resolveAgentTool<TInput, TOutput, TContext extends ToolContext>(
+  definition: TulipToolDefinition<string, TInput, TOutput, TContext>,
+  options: AgentToolResolverOptions = {},
+): Tool<TInput, TOutput, TContext> {
+  return tool({
+    title: options.title ?? definition.title,
+    description: options.description ?? definition.description,
+    inputSchema: definition.inputSchema,
+    outputSchema: definition.outputSchema,
+    contextSchema: definition.contextSchema,
+    execute: definition.execute,
+    metadata: {
+      tulip: getSerializableToolMetadata(definition, options),
+    },
+  } as unknown as Tool<TInput, TOutput, TContext> & {
+    execute: ToolExecuteFunction<TInput, TOutput, TContext>;
+  });
+}
+
+/**
+ * Resolves a named set of Tulip tools into AI SDK tools.
+ * Per-tool resolver options can override labels, permissions, confirmation, audit, or UI metadata.
+ */
+export function resolveAgentToolSet<TTools extends TulipToolSet>(
+  tools: TTools,
+  options: Partial<Record<keyof TTools, AgentToolResolverOptions>> = {},
+) {
+  return Object.fromEntries(
+    Object.entries(tools).map(([name, definition]) => [
+      name,
+      resolveAgentTool(definition, options[name]),
+    ]),
+  );
+}
+
+/**
+ * Produces serializable metadata that is attached to AI SDK tool calls.
+ * The chat UI and observability layers can read this without importing server-only code.
+ */
+function getSerializableToolMetadata(
+  definition: Pick<TulipToolDefinition, "name" | "title" | "description">,
+  options: AgentToolResolverOptions,
+) {
+  return {
+    name: definition.name,
+    title: options.title ?? definition.title,
+    description: options.description ?? definition.description,
+    permissions: options.permissions,
+    confirmation: options.confirmation,
+    audit: options.audit,
+    ui: options.ui,
+  };
+}

package/src/tools/resolvers/mcp.server.ts

@@ -0,0 +1,40 @@
+import "server-cli-only";
+
+import type { McpToolResult } from "../../mcp/lib/types";
+import type { TulipToolDefinition } from "../lib/types";
+
+export type MCPToolResolverOptions<TInput, TOutput> = {
+  title?: string;
+  description?: string;
+  content?: (options: { input: TInput; output: TOutput }) => McpToolResult | Promise<McpToolResult>;
+};
+
+export type ResolvedMCPTool<TInput = unknown, TOutput = unknown> = {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: TulipToolDefinition<string, TInput, TOutput>["inputSchema"];
+  outputSchema?: TulipToolDefinition<string, TInput, TOutput>["outputSchema"];
+  resolveResult: (options: {
+    input: TInput;
+    output: TOutput;
+  }) => Promise<McpToolResult | undefined>;
+};
+
+/**
+ * Resolves a Tulip tool definition into an MCP-facing tool descriptor.
+ * MCP-specific labels and content formatting live here instead of in the base tool definition.
+ */
+export function resolveMCPTool<TInput, TOutput>(
+  definition: TulipToolDefinition<string, TInput, TOutput>,
+  options: MCPToolResolverOptions<TInput, TOutput> = {},
+): ResolvedMCPTool<TInput, TOutput> {
+  return {
+    name: definition.name,
+    title: options.title ?? definition.title,
+    description: options.description ?? definition.description,
+    inputSchema: definition.inputSchema,
+    outputSchema: definition.outputSchema,
+    resolveResult: async (resultOptions) => options.content?.(resultOptions),
+  };
+}