@tulip-systems/ai 0.11.0

package/dist/tools/lib/definitions.client.mjs

@@ -0,0 +1,21 @@
+//#region src/tools/lib/definitions.client.ts
+/**
+* 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" />,
+* });
+* ```
+*/
+function defineToolClient(definition) {
+	return definition;
+}
+
+//#endregion
+export { defineToolClient };

package/dist/tools/lib/definitions.d.mts

@@ -0,0 +1,16 @@
+import { ToolContext, TulipToolDefinition, TulipToolSet } from "./types.mjs";
+import "server-cli-only";
+
+//#region src/tools/lib/definitions.d.ts
+/**
+ * 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.
+ */
+declare function defineTool<const TName extends string, TInput, TOutput, TContext extends ToolContext = ToolContext>(definition: TulipToolDefinition<TName, TInput, TOutput, TContext>): TulipToolDefinition<TName, TInput, TOutput, TContext>;
+/**
+ * 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.
+ */
+declare function defineToolSet<const TTools extends TulipToolSet>(tools: TTools): TTools;
+//#endregion
+export { defineTool, defineToolSet };

package/dist/tools/lib/definitions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.mts","names":[],"sources":["../../../src/tools/lib/definitions.ts"],"mappings":";;;;iBAIgB,UAAA,+DAIG,WAAA,GAAc,WAAA,CAAA,CAC/B,UAAA,EAAY,mBAAA,CAAoB,KAAA,EAAO,MAAA,EAAQ,OAAA,EAAS,QAAA,IAAS,mBAAA,CAAA,KAAA,EAAA,MAAA,EAAA,OAAA,EAAA,QAAA;AAAA,iBAInD,aAAA,sBAAmC,YAAA,CAAA,CAAc,KAAA,EAAO,MAAA,GAAM,MAAA"}

package/dist/tools/lib/definitions.mjs

@@ -0,0 +1,20 @@
+import "server-cli-only";
+
+//#region src/tools/lib/definitions.ts
+/**
+* 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.
+*/
+function defineTool(definition) {
+	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.
+*/
+function defineToolSet(tools) {
+	return tools;
+}
+
+//#endregion
+export { defineTool, defineToolSet };

package/dist/tools/lib/definitions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.mjs","names":[],"sources":["../../../src/tools/lib/definitions.ts"],"sourcesContent":["import \"server-cli-only\";\n\nimport type { ToolContext, TulipToolDefinition, TulipToolSet } from \"../types.js\";\n\nexport function defineTool<\n  const TName extends string,\n  TInput,\n  TOutput,\n  TContext extends ToolContext = ToolContext,\n>(definition: TulipToolDefinition<TName, TInput, TOutput, TContext>) {\n  return definition;\n}\n\nexport function defineToolSet<const TTools extends TulipToolSet>(tools: TTools) {\n  return tools;\n}\n"],"mappings":";;;AAIA,SAAgB,WAKd,YAAmE;AACnE,QAAO;;AAGT,SAAgB,cAAiD,OAAe;AAC9E,QAAO"}

package/dist/tools/lib/resolvers.d.mts

@@ -0,0 +1,41 @@
+import { McpToolResult } from "../../mcp/types.mjs";
+import { ToolAudit, ToolConfirmation, ToolContext, ToolDisplay, TulipToolDefinition, TulipToolSet } from "../types.mjs";
+import "server-cli-only";
+import { Tool } from "ai";
+
+//#region src/tools/lib/resolvers.d.ts
+type AgentToolResolverOptions = {
+  title?: string;
+  description?: string;
+  permissions?: string[];
+  confirmation?: ToolConfirmation;
+  audit?: ToolAudit;
+  ui?: ToolDisplay;
+};
+type MCPToolResolverOptions<TInput, TOutput> = {
+  title?: string;
+  description?: string;
+  content?: (options: {
+    input: TInput;
+    output: TOutput;
+  }) => McpToolResult | Promise<McpToolResult>;
+};
+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>;
+};
+declare function resolveAgentTool<TInput, TOutput, TContext extends ToolContext>(definition: TulipToolDefinition<string, TInput, TOutput, TContext>, options?: AgentToolResolverOptions): Tool<TInput, TOutput, TContext>;
+declare function resolveAgentToolSet<TTools extends TulipToolSet>(tools: TTools, options?: Partial<Record<keyof TTools, AgentToolResolverOptions>>): {
+  [k: string]: Tool<unknown, unknown, ToolContext>;
+};
+declare function resolveMCPTool<TInput, TOutput>(definition: TulipToolDefinition<string, TInput, TOutput>, options?: MCPToolResolverOptions<TInput, TOutput>): ResolvedMCPTool<TInput, TOutput>;
+//#endregion
+export { AgentToolResolverOptions, MCPToolResolverOptions, ResolvedMCPTool, resolveAgentTool, resolveAgentToolSet, resolveMCPTool };
+//# sourceMappingURL=resolvers.d.mts.map

package/dist/tools/lib/resolvers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolvers.d.mts","names":[],"sources":["../../../src/tools/lib/resolvers.ts"],"mappings":";;;;;;KAaY,wBAAA;EACV,KAAA;EACA,WAAA;EACA,WAAA;EACA,YAAA,GAAe,gBAAA;EACf,KAAA,GAAQ,SAAA;EACR,EAAA,GAAK,WAAA;AAAA;AAAA,KAGK,sBAAA;EACV,KAAA;EACA,WAAA;EACA,OAAA,IAAW,OAAA;IAAW,KAAA,EAAO,MAAA;IAAQ,MAAA,EAAQ,OAAA;EAAA,MAAc,aAAA,GAAgB,OAAA,CAAQ,aAAA;AAAA;AAAA,KAGzE,eAAA;EACV,IAAA;EACA,KAAA;EACA,WAAA;EACA,WAAA,EAAa,mBAAA,SAA4B,MAAA,EAAQ,OAAA;EACjD,YAAA,GAAe,mBAAA,SAA4B,MAAA,EAAQ,OAAA;EACnD,aAAA,GAAgB,OAAA;IACd,KAAA,EAAO,MAAA;IACP,MAAA,EAAQ,OAAA;EAAA,MACJ,OAAA,CAAQ,aAAA;AAAA;AAAA,iBAGA,gBAAA,mCAAmD,WAAA,CAAA,CACjE,UAAA,EAAY,mBAAA,SAA4B,MAAA,EAAQ,OAAA,EAAS,QAAA,GACzD,OAAA,GAAS,wBAAA,GACR,IAAA,CAAK,MAAA,EAAQ,OAAA,EAAS,QAAA;AAAA,iBAgBT,mBAAA,gBAAmC,YAAA,CAAA,CACjD,KAAA,EAAO,MAAA,EACP,OAAA,GAAS,OAAA,CAAQ,MAAA,OAAa,MAAA,EAAQ,wBAAA;EAAA;;iBAUxB,cAAA,iBAAA,CACd,UAAA,EAAY,mBAAA,SAA4B,MAAA,EAAQ,OAAA,GAChD,OAAA,GAAS,sBAAA,CAAuB,MAAA,EAAQ,OAAA,IACvC,eAAA,CAAgB,MAAA,EAAQ,OAAA"}

package/dist/tools/lib/resolvers.mjs

@@ -0,0 +1,43 @@
+import "server-cli-only";
+import { tool } from "ai";
+
+//#region src/tools/lib/resolvers.ts
+function resolveAgentTool(definition, options = {}) {
+	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) }
+	});
+}
+function resolveAgentToolSet(tools, options = {}) {
+	return Object.fromEntries(Object.entries(tools).map(([name, definition]) => [name, resolveAgentTool(definition, options[name])]));
+}
+function resolveMCPTool(definition, options = {}) {
+	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)
+	};
+}
+function getSerializableToolMetadata(definition, options) {
+	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
+	};
+}
+
+//#endregion
+export { resolveAgentTool, resolveAgentToolSet, resolveMCPTool };
+//# sourceMappingURL=resolvers.mjs.map

package/dist/tools/lib/resolvers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolvers.mjs","names":[],"sources":["../../../src/tools/lib/resolvers.ts"],"sourcesContent":["import \"server-cli-only\";\n\nimport { type Tool, type ToolExecuteFunction, tool } from \"ai\";\nimport type { McpToolResult } from \"../../mcp/types.js\";\nimport type {\n  ToolAudit,\n  ToolConfirmation,\n  ToolContext,\n  ToolDisplay,\n  TulipToolDefinition,\n  TulipToolSet,\n} from \"../types.js\";\n\nexport type AgentToolResolverOptions = {\n  title?: string;\n  description?: string;\n  permissions?: string[];\n  confirmation?: ToolConfirmation;\n  audit?: ToolAudit;\n  ui?: ToolDisplay;\n};\n\nexport type MCPToolResolverOptions<TInput, TOutput> = {\n  title?: string;\n  description?: string;\n  content?: (options: { input: TInput; output: TOutput }) => McpToolResult | Promise<McpToolResult>;\n};\n\nexport type ResolvedMCPTool<TInput = unknown, TOutput = unknown> = {\n  name: string;\n  title: string;\n  description: string;\n  inputSchema: TulipToolDefinition<string, TInput, TOutput>[\"inputSchema\"];\n  outputSchema?: TulipToolDefinition<string, TInput, TOutput>[\"outputSchema\"];\n  resolveResult: (options: {\n    input: TInput;\n    output: TOutput;\n  }) => Promise<McpToolResult | undefined>;\n};\n\nexport function resolveAgentTool<TInput, TOutput, TContext extends ToolContext>(\n  definition: TulipToolDefinition<string, TInput, TOutput, TContext>,\n  options: AgentToolResolverOptions = {},\n): Tool<TInput, TOutput, TContext> {\n  return tool({\n    title: options.title ?? definition.title,\n    description: options.description ?? definition.description,\n    inputSchema: definition.inputSchema,\n    outputSchema: definition.outputSchema,\n    contextSchema: definition.contextSchema,\n    execute: definition.execute,\n    metadata: {\n      tulip: getSerializableToolMetadata(definition, options),\n    },\n  } as unknown as Tool<TInput, TOutput, TContext> & {\n    execute: ToolExecuteFunction<TInput, TOutput, TContext>;\n  });\n}\n\nexport function resolveAgentToolSet<TTools extends TulipToolSet>(\n  tools: TTools,\n  options: Partial<Record<keyof TTools, AgentToolResolverOptions>> = {},\n) {\n  return Object.fromEntries(\n    Object.entries(tools).map(([name, definition]) => [\n      name,\n      resolveAgentTool(definition, options[name]),\n    ]),\n  );\n}\n\nexport function resolveMCPTool<TInput, TOutput>(\n  definition: TulipToolDefinition<string, TInput, TOutput>,\n  options: MCPToolResolverOptions<TInput, TOutput> = {},\n): ResolvedMCPTool<TInput, TOutput> {\n  return {\n    name: definition.name,\n    title: options.title ?? definition.title,\n    description: options.description ?? definition.description,\n    inputSchema: definition.inputSchema,\n    outputSchema: definition.outputSchema,\n    resolveResult: async (resultOptions) => options.content?.(resultOptions),\n  };\n}\n\nfunction getSerializableToolMetadata(\n  definition: Pick<TulipToolDefinition, \"name\" | \"title\" | \"description\">,\n  options: AgentToolResolverOptions,\n) {\n  return {\n    name: definition.name,\n    title: options.title ?? definition.title,\n    description: options.description ?? definition.description,\n    permissions: options.permissions,\n    confirmation: options.confirmation,\n    audit: options.audit,\n    ui: options.ui,\n  };\n}\n"],"mappings":";;;;AAwCA,SAAgB,iBACd,YACA,UAAoC,EAAE,EACL;AACjC,QAAO,KAAK;EACV,OAAO,QAAQ,SAAS,WAAW;EACnC,aAAa,QAAQ,eAAe,WAAW;EAC/C,aAAa,WAAW;EACxB,cAAc,WAAW;EACzB,eAAe,WAAW;EAC1B,SAAS,WAAW;EACpB,UAAU,EACR,OAAO,4BAA4B,YAAY,QAAQ,EACxD;EACF,CAEC;;AAGJ,SAAgB,oBACd,OACA,UAAmE,EAAE,EACrE;AACA,QAAO,OAAO,YACZ,OAAO,QAAQ,MAAM,CAAC,KAAK,CAAC,MAAM,gBAAgB,CAChD,MACA,iBAAiB,YAAY,QAAQ,MAAM,CAC5C,CAAC,CACH;;AAGH,SAAgB,eACd,YACA,UAAmD,EAAE,EACnB;AAClC,QAAO;EACL,MAAM,WAAW;EACjB,OAAO,QAAQ,SAAS,WAAW;EACnC,aAAa,QAAQ,eAAe,WAAW;EAC/C,aAAa,WAAW;EACxB,cAAc,WAAW;EACzB,eAAe,OAAO,kBAAkB,QAAQ,UAAU,cAAc;EACzE;;AAGH,SAAS,4BACP,YACA,SACA;AACA,QAAO;EACL,MAAM,WAAW;EACjB,OAAO,QAAQ,SAAS,WAAW;EACnC,aAAa,QAAQ,eAAe,WAAW;EAC/C,aAAa,QAAQ;EACrB,cAAc,QAAQ;EACtB,OAAO,QAAQ;EACf,IAAI,QAAQ;EACb"}

package/dist/tools/lib/types.client.d.mts

@@ -0,0 +1,13 @@
+import { ToolChatPart } from "../../chat/lib/types.mjs";
+import { ReactNode } from "react";
+
+//#region src/tools/lib/types.client.d.ts
+type ToolClientSource = {
+  name: string;
+};
+type ToolClientDefinition<TTool extends ToolClientSource = ToolClientSource> = {
+  toolName: TTool["name"];
+  render: (part: ToolChatPart) => ReactNode;
+};
+//#endregion
+export { ToolClientDefinition, ToolClientSource };

package/dist/tools/lib/types.d.mts

@@ -0,0 +1,33 @@
+import { FlexibleSchema, ToolExecuteFunction, ToolExecutionOptions } from "ai";
+
+//#region src/tools/lib/types.d.ts
+type ToolContext = Record<string, unknown>;
+type ToolConfirmation = false | {
+  required?: boolean;
+  title?: string;
+  description?: string;
+  destructive?: boolean;
+};
+type ToolAudit = {
+  action: string;
+  resource?: string;
+  severity?: "low" | "medium" | "high";
+};
+type ToolDisplay = {
+  label?: string;
+  description?: string;
+  icon?: string;
+};
+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>;
+};
+type TulipToolSet = Record<string, TulipToolDefinition>;
+type TulipToolExecutionOptions<TContext extends ToolContext = ToolContext> = ToolExecutionOptions<TContext>;
+//#endregion
+export { ToolAudit, ToolConfirmation, ToolContext, ToolDisplay, TulipToolDefinition, TulipToolExecutionOptions, TulipToolSet };

package/dist/tools/resolvers/agent.server.d.mts

@@ -0,0 +1,27 @@
+import { ToolAudit, ToolConfirmation, ToolContext, ToolDisplay, TulipToolDefinition, TulipToolSet } from "../lib/types.mjs";
+import "server-cli-only";
+import { Tool } from "ai";
+
+//#region src/tools/resolvers/agent.server.d.ts
+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.
+ */
+declare function resolveAgentTool<TInput, TOutput, TContext extends ToolContext>(definition: TulipToolDefinition<string, TInput, TOutput, TContext>, options?: AgentToolResolverOptions): Tool<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.
+ */
+declare function resolveAgentToolSet<TTools extends TulipToolSet>(tools: TTools, options?: Partial<Record<keyof TTools, AgentToolResolverOptions>>): {
+  [k: string]: Tool<unknown, unknown, ToolContext>;
+};
+//#endregion
+export { AgentToolResolverOptions, resolveAgentTool, resolveAgentToolSet };

package/dist/tools/resolvers/agent.server.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.server.d.mts","names":[],"sources":["../../../src/tools/resolvers/agent.server.ts"],"mappings":";;;;;KAYY,wBAAA;EACV,KAAA;EACA,WAAA;EACA,WAAA;EACA,YAAA,GAAe,gBAAA;EACf,KAAA,GAAQ,SAAA;EACR,EAAA,GAAK,WAAA;AAAA;AAAA,iBAGS,gBAAA,mCAAmD,WAAA,CAAA,CACjE,UAAA,EAAY,mBAAA,SAA4B,MAAA,EAAQ,OAAA,EAAS,QAAA,GACzD,OAAA,GAAS,wBAAA,GACR,IAAA,CAAK,MAAA,EAAQ,OAAA,EAAS,QAAA;AAAA,iBAgBT,mBAAA,gBAAmC,YAAA,CAAA,CACjD,KAAA,EAAO,MAAA,EACP,OAAA,GAAS,OAAA,CAAQ,MAAA,OAAa,MAAA,EAAQ,wBAAA;EAAA"}

package/dist/tools/resolvers/agent.server.mjs

@@ -0,0 +1,44 @@
+import "server-cli-only";
+import { tool } from "ai";
+
+//#region src/tools/resolvers/agent.server.ts
+/**
+* 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.
+*/
+function resolveAgentTool(definition, options = {}) {
+	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) }
+	});
+}
+/**
+* Resolves a named set of Tulip tools into AI SDK tools.
+* Per-tool resolver options can override labels, permissions, confirmation, audit, or UI metadata.
+*/
+function resolveAgentToolSet(tools, options = {}) {
+	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, options) {
+	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
+	};
+}
+
+//#endregion
+export { resolveAgentTool, resolveAgentToolSet };

package/dist/tools/resolvers/agent.server.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.server.mjs","names":[],"sources":["../../../src/tools/resolvers/agent.server.ts"],"sourcesContent":["import \"server-cli-only\";\n\nimport { type Tool, type ToolExecuteFunction, tool } from \"ai\";\nimport type {\n  ToolAudit,\n  ToolConfirmation,\n  ToolContext,\n  ToolDisplay,\n  TulipToolDefinition,\n  TulipToolSet,\n} from \"../types.js\";\n\nexport type AgentToolResolverOptions = {\n  title?: string;\n  description?: string;\n  permissions?: string[];\n  confirmation?: ToolConfirmation;\n  audit?: ToolAudit;\n  ui?: ToolDisplay;\n};\n\nexport function resolveAgentTool<TInput, TOutput, TContext extends ToolContext>(\n  definition: TulipToolDefinition<string, TInput, TOutput, TContext>,\n  options: AgentToolResolverOptions = {},\n): Tool<TInput, TOutput, TContext> {\n  return tool({\n    title: options.title ?? definition.title,\n    description: options.description ?? definition.description,\n    inputSchema: definition.inputSchema,\n    outputSchema: definition.outputSchema,\n    contextSchema: definition.contextSchema,\n    execute: definition.execute,\n    metadata: {\n      tulip: getSerializableToolMetadata(definition, options),\n    },\n  } as unknown as Tool<TInput, TOutput, TContext> & {\n    execute: ToolExecuteFunction<TInput, TOutput, TContext>;\n  });\n}\n\nexport function resolveAgentToolSet<TTools extends TulipToolSet>(\n  tools: TTools,\n  options: Partial<Record<keyof TTools, AgentToolResolverOptions>> = {},\n) {\n  return Object.fromEntries(\n    Object.entries(tools).map(([name, definition]) => [\n      name,\n      resolveAgentTool(definition, options[name]),\n    ]),\n  );\n}\n\nfunction getSerializableToolMetadata(\n  definition: Pick<TulipToolDefinition, \"name\" | \"title\" | \"description\">,\n  options: AgentToolResolverOptions,\n) {\n  return {\n    name: definition.name,\n    title: options.title ?? definition.title,\n    description: options.description ?? definition.description,\n    permissions: options.permissions,\n    confirmation: options.confirmation,\n    audit: options.audit,\n    ui: options.ui,\n  };\n}\n"],"mappings":";;;;AAqBA,SAAgB,iBACd,YACA,UAAoC,EAAE,EACL;AACjC,QAAO,KAAK;EACV,OAAO,QAAQ,SAAS,WAAW;EACnC,aAAa,QAAQ,eAAe,WAAW;EAC/C,aAAa,WAAW;EACxB,cAAc,WAAW;EACzB,eAAe,WAAW;EAC1B,SAAS,WAAW;EACpB,UAAU,EACR,OAAO,4BAA4B,YAAY,QAAQ,EACxD;EACF,CAEC;;AAGJ,SAAgB,oBACd,OACA,UAAmE,EAAE,EACrE;AACA,QAAO,OAAO,YACZ,OAAO,QAAQ,MAAM,CAAC,KAAK,CAAC,MAAM,gBAAgB,CAChD,MACA,iBAAiB,YAAY,QAAQ,MAAM,CAC5C,CAAC,CACH;;AAGH,SAAS,4BACP,YACA,SACA;AACA,QAAO;EACL,MAAM,WAAW;EACjB,OAAO,QAAQ,SAAS,WAAW;EACnC,aAAa,QAAQ,eAAe,WAAW;EAC/C,aAAa,QAAQ;EACrB,cAAc,QAAQ;EACtB,OAAO,QAAQ;EACf,IAAI,QAAQ;EACb"}

package/dist/tools/resolvers/mcp.server.d.mts

@@ -0,0 +1,31 @@
+import { TulipToolDefinition } from "../lib/types.mjs";
+import { McpToolResult } from "../../mcp/lib/types.mjs";
+import "server-cli-only";
+
+//#region src/tools/resolvers/mcp.server.d.ts
+type MCPToolResolverOptions<TInput, TOutput> = {
+  title?: string;
+  description?: string;
+  content?: (options: {
+    input: TInput;
+    output: TOutput;
+  }) => McpToolResult | Promise<McpToolResult>;
+};
+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.
+ */
+declare function resolveMCPTool<TInput, TOutput>(definition: TulipToolDefinition<string, TInput, TOutput>, options?: MCPToolResolverOptions<TInput, TOutput>): ResolvedMCPTool<TInput, TOutput>;
+//#endregion
+export { MCPToolResolverOptions, ResolvedMCPTool, resolveMCPTool };

package/dist/tools/resolvers/mcp.server.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.server.d.mts","names":[],"sources":["../../../src/tools/resolvers/mcp.server.ts"],"mappings":";;;;;KAKY,sBAAA;EACV,KAAA;EACA,WAAA;EACA,OAAA,IAAW,OAAA;IAAW,KAAA,EAAO,MAAA;IAAQ,MAAA,EAAQ,OAAA;EAAA,MAAc,aAAA,GAAgB,OAAA,CAAQ,aAAA;AAAA;AAAA,KAGzE,eAAA;EACV,IAAA;EACA,KAAA;EACA,WAAA;EACA,WAAA,EAAa,mBAAA,SAA4B,MAAA,EAAQ,OAAA;EACjD,YAAA,GAAe,mBAAA,SAA4B,MAAA,EAAQ,OAAA;EACnD,aAAA,GAAgB,OAAA;IACd,KAAA,EAAO,MAAA;IACP,MAAA,EAAQ,OAAA;EAAA,MACJ,OAAA,CAAQ,aAAA;AAAA;AAAA,iBAGA,cAAA,iBAAA,CACd,UAAA,EAAY,mBAAA,SAA4B,MAAA,EAAQ,OAAA,GAChD,OAAA,GAAS,sBAAA,CAAuB,MAAA,EAAQ,OAAA,IACvC,eAAA,CAAgB,MAAA,EAAQ,OAAA"}

package/dist/tools/resolvers/mcp.server.mjs

@@ -0,0 +1,20 @@
+import "server-cli-only";
+
+//#region src/tools/resolvers/mcp.server.ts
+/**
+* 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.
+*/
+function resolveMCPTool(definition, options = {}) {
+	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)
+	};
+}
+
+//#endregion
+export { resolveMCPTool };

package/dist/tools/resolvers/mcp.server.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.server.mjs","names":[],"sources":["../../../src/tools/resolvers/mcp.server.ts"],"sourcesContent":["import \"server-cli-only\";\n\nimport type { McpToolResult } from \"../../mcp/types.js\";\nimport type { TulipToolDefinition } from \"../types.js\";\n\nexport type MCPToolResolverOptions<TInput, TOutput> = {\n  title?: string;\n  description?: string;\n  content?: (options: { input: TInput; output: TOutput }) => McpToolResult | Promise<McpToolResult>;\n};\n\nexport type ResolvedMCPTool<TInput = unknown, TOutput = unknown> = {\n  name: string;\n  title: string;\n  description: string;\n  inputSchema: TulipToolDefinition<string, TInput, TOutput>[\"inputSchema\"];\n  outputSchema?: TulipToolDefinition<string, TInput, TOutput>[\"outputSchema\"];\n  resolveResult: (options: {\n    input: TInput;\n    output: TOutput;\n  }) => Promise<McpToolResult | undefined>;\n};\n\nexport function resolveMCPTool<TInput, TOutput>(\n  definition: TulipToolDefinition<string, TInput, TOutput>,\n  options: MCPToolResolverOptions<TInput, TOutput> = {},\n): ResolvedMCPTool<TInput, TOutput> {\n  return {\n    name: definition.name,\n    title: options.title ?? definition.title,\n    description: options.description ?? definition.description,\n    inputSchema: definition.inputSchema,\n    outputSchema: definition.outputSchema,\n    resolveResult: async (resultOptions) => options.content?.(resultOptions),\n  };\n}\n"],"mappings":";;;AAuBA,SAAgB,eACd,YACA,UAAmD,EAAE,EACnB;AAClC,QAAO;EACL,MAAM,WAAW;EACjB,OAAO,QAAQ,SAAS,WAAW;EACnC,aAAa,QAAQ,eAAe,WAAW;EAC/C,aAAa,WAAW;EACxB,cAAc,WAAW;EACzB,eAAe,OAAO,kBAAkB,QAAQ,UAAU,cAAc;EACzE"}

package/dist/tools/server.d.mts

@@ -0,0 +1,5 @@
+import { ToolAudit, ToolConfirmation, ToolContext, ToolDisplay, TulipToolDefinition, TulipToolExecutionOptions, TulipToolSet } from "./lib/types.mjs";
+import { defineTool, defineToolSet } from "./lib/definitions.mjs";
+import { AgentToolResolverOptions, resolveAgentTool, resolveAgentToolSet } from "./resolvers/agent.server.mjs";
+import { MCPToolResolverOptions, ResolvedMCPTool, resolveMCPTool } from "./resolvers/mcp.server.mjs";
+export { AgentToolResolverOptions, MCPToolResolverOptions, ResolvedMCPTool, ToolAudit, ToolConfirmation, ToolContext, ToolDisplay, TulipToolDefinition, TulipToolExecutionOptions, TulipToolSet, defineTool, defineToolSet, resolveAgentTool, resolveAgentToolSet, resolveMCPTool };

package/dist/tools/server.mjs

@@ -0,0 +1,5 @@
+import { defineTool, defineToolSet } from "./lib/definitions.mjs";
+import { resolveAgentTool, resolveAgentToolSet } from "./resolvers/agent.server.mjs";
+import { resolveMCPTool } from "./resolvers/mcp.server.mjs";
+
+export { defineTool, defineToolSet, resolveAgentTool, resolveAgentToolSet, resolveMCPTool };

package/dist/tools/types.d.mts

@@ -0,0 +1,33 @@
+import { FlexibleSchema, ToolExecuteFunction, ToolExecutionOptions } from "ai";
+
+//#region src/tools/types.d.ts
+type ToolContext = Record<string, unknown>;
+type ToolConfirmation = false | {
+  required?: boolean;
+  title?: string;
+  description?: string;
+  destructive?: boolean;
+};
+type ToolAudit = {
+  action: string;
+  resource?: string;
+  severity?: "low" | "medium" | "high";
+};
+type ToolDisplay = {
+  label?: string;
+  description?: string;
+  icon?: string;
+};
+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>;
+};
+type TulipToolSet = Record<string, TulipToolDefinition>;
+type TulipToolExecutionOptions<TContext extends ToolContext = ToolContext> = ToolExecutionOptions<TContext>;
+//#endregion
+export { ToolAudit, ToolConfirmation, ToolContext, ToolDisplay, TulipToolDefinition, TulipToolExecutionOptions, TulipToolSet };

package/dist/tools/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/tools/types.ts"],"mappings":";;;KAEY,WAAA,GAAc,MAAA;AAAA,KAEd,gBAAA;EAGN,QAAA;EACA,KAAA;EACA,WAAA;EACA,WAAA;AAAA;AAAA,KAGM,SAAA;EACV,MAAA;EACA,QAAA;EACA,QAAA;AAAA;AAAA,KAGU,WAAA;EACV,KAAA;EACA,WAAA;EACA,IAAA;AAAA;AAAA,KAGU,mBAAA,sFAIO,WAAA,GAAc,WAAA;EAE/B,IAAA,EAAM,KAAA;EACN,KAAA;EACA,WAAA;EACA,WAAA,EAAa,cAAA,CAAe,MAAA;EAC5B,YAAA,GAAe,cAAA,CAAe,OAAA;EAC9B,aAAA,GAAgB,cAAA,CAAe,QAAA;EAC/B,OAAA,EAAS,mBAAA,CAAoB,MAAA,EAAQ,OAAA,EAAS,QAAA;AAAA;AAAA,KAGpC,YAAA,GAAe,MAAA,SAAe,mBAAA;AAAA,KAE9B,yBAAA,kBAA2C,WAAA,GAAc,WAAA,IACnE,oBAAA,CAAqB,QAAA"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tulip-systems/ai",
+  "version": "0.11.0",
+  "type": "module",
+  "sideEffects": false,
+  "license": "AGPL-3.0",
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.2",
+    "@orpc/server": "^1.14.2",
+    "@types/react": "19.2.14",
+    "ai": "^7.0.9",
+    "publint": "^0.3.20",
+    "react": "19.2.6",
+    "tsdown": "^0.20.3",
+    "typescript": "5.9.3",
+    "unrun": "^0.3.0",
+    "@tulip-systems/typescript-config": "0.0.0"
+  },
+  "dependencies": {
+    "lucide-react": "1.14.0",
+    "server-cli-only": "^0.3.2",
+    "tailwindcss": "4.3.0",
+    "vitest": "4.1.5",
+    "@tulip-systems/core": "0.11.0"
+  },
+  "peerDependencies": {
+    "@orpc/server": "^1.14.2",
+    "ai": "^7.0.9",
+    "react": "19.2.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./agents/server": "./dist/agents/server.mjs",
+    "./chat": "./dist/chat.mjs",
+    "./chat/client": "./dist/chat/client.mjs",
+    "./chat/server": "./dist/chat/server.mjs",
+    "./mcp/server": "./dist/mcp/server.mjs",
+    "./tools/client": "./dist/tools/client.mjs",
+    "./tools/server": "./dist/tools/server.mjs",
+    "./package.json": "./package.json",
+    "./styles.css": "./src/styles.css"
+  },
+  "scripts": {
+    "dev": "tsdown --config tsdown.config.ts --config-loader unrun --watch",
+    "build": "tsdown --config tsdown.config.ts --config-loader unrun",
+    "release:build": "pnpm run build",
+    "lint": "biome check",
+    "format": "biome format --write",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist"
+  }
+}

package/src/agents/entry.server.ts

@@ -0,0 +1,7 @@
+/**
+ * Lib
+ */
+export * from "./lib/definitions.server";
+export * from "./lib/delegation.server";
+export * from "./lib/instructions.server";
+export * from "./lib/types";

package/src/agents/lib/definitions.server.ts

@@ -0,0 +1,14 @@
+import "server-cli-only";
+
+import { ToolLoopAgent } from "ai";
+import type { AgentSettings, CreatedAgent } from "./types";
+
+/**
+ * Creates an AI SDK tool-loop agent with Tulip's package-level entrypoint.
+ * This keeps applications from importing the underlying agent implementation directly.
+ */
+export function createAgent(settings: AgentSettings): CreatedAgent {
+  return new ToolLoopAgent(
+    settings as ConstructorParameters<typeof ToolLoopAgent>[0],
+  ) as CreatedAgent;
+}

package/src/agents/lib/delegation.server.ts

@@ -0,0 +1,33 @@
+import "server-cli-only";
+
+import { defineTool } from "../../tools/lib/definitions";
+import type { ToolContext } from "../../tools/lib/types";
+import type { DelegateToAgentToolOptions } from "./types";
+
+/**
+ * Defines a Tulip tool that delegates work to another agent and returns its result.
+ * Resolve the returned definition with `resolveAgentTool()` before passing it to an agent.
+ */
+export function delegateToAgentTool<
+  const TName extends string,
+  TInput extends Record<string, unknown>,
+  TOutput = { summary: string },
+  TContext extends ToolContext = ToolContext,
+>(options: DelegateToAgentToolOptions<TName, TInput, TOutput, TContext>) {
+  return defineTool({
+    name: options.name,
+    title: options.title,
+    description: options.description,
+    inputSchema: options.inputSchema,
+    outputSchema: options.outputSchema,
+    contextSchema: options.contextSchema,
+    async execute(input, { abortSignal }) {
+      const result = await options.agent.generate({
+        prompt: options.prompt ? options.prompt(input) : String(input.task ?? ""),
+        abortSignal,
+      });
+
+      return options.output ? options.output(result, input) : ({ summary: result.text } as TOutput);
+    },
+  });
+}

package/src/agents/lib/instructions.server.ts

@@ -0,0 +1,37 @@
+import "server-cli-only";
+
+import { readFileSync } from "node:fs";
+
+const instructionCache = new Map<string, string>();
+
+export type LoadAgentInstructionsOptions = {
+  path?: string;
+};
+
+/**
+ * Loads an agent's always-on instructions from a file next to the agent module.
+ * Pass `import.meta.url` from the agent file so relative paths resolve from that agent folder.
+ * Defaults to `./instructions.md`.
+ */
+export function loadAgentInstructions(
+  importMetaUrl: string,
+  options: LoadAgentInstructionsOptions = {},
+) {
+  const instructionUrl = new URL(options.path ?? "./instructions.md", importMetaUrl);
+  const cacheKey = instructionUrl.href;
+  const cached = instructionCache.get(cacheKey);
+
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  try {
+    const instructions = readFileSync(instructionUrl, "utf-8");
+    instructionCache.set(cacheKey, instructions);
+    return instructions;
+  } catch (error) {
+    throw new Error(`Unable to load agent instructions from ${instructionUrl.pathname}.`, {
+      cause: error,
+    });
+  }
+}

package/src/agents/lib/types.ts

@@ -0,0 +1,32 @@
+import type { Agent, Experimental_AgentSettings, FlexibleSchema, ToolSet } from "ai";
+import type { ToolContext, TulipToolDefinition } from "../../tools/lib/types";
+
+export type AgentSettings = Experimental_AgentSettings;
+
+export type CreatedAgent<TTools extends ToolSet = ToolSet> = Agent<
+  never,
+  TTools,
+  Record<string, unknown>,
+  never
+>;
+
+export type DelegationTargetAgent = {
+  generate(options: { prompt: string; abortSignal?: AbortSignal }): PromiseLike<{ text: string }>;
+};
+
+export type DelegateToAgentToolOptions<
+  TName extends string,
+  TInput extends Record<string, unknown>,
+  TOutput,
+  TContext extends ToolContext = ToolContext,
+> = Pick<
+  TulipToolDefinition<TName, TInput, TOutput, TContext>,
+  "name" | "title" | "description"
+> & {
+  agent: DelegationTargetAgent;
+  inputSchema: FlexibleSchema<TInput>;
+  outputSchema?: FlexibleSchema<TOutput>;
+  contextSchema?: FlexibleSchema<TContext>;
+  prompt?: (input: TInput) => string;
+  output?: (result: { text: string }, input: TInput) => TOutput;
+};

package/src/chat/components/agent-activity.client.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import { cn } from "@tulip-systems/core/lib";
+
+export type AgentActivityProps = {
+  className?: string;
+};
+
+/**
+ * Small typing indicator for an agent that is currently streaming a response.
+ */
+export function AgentActivity({ className }: AgentActivityProps) {
+  return (
+    <div className={cn("flex h-7 w-fit items-center gap-1 px-1", className)}>
+      <span className="sr-only">Assistant is responding</span>
+      <span className="size-1.5 animate-pulse rounded-full bg-muted-foreground/50 [animation-delay:-0.3s]" />
+      <span className="size-1.5 animate-pulse rounded-full bg-muted-foreground/50 [animation-delay:-0.15s]" />
+      <span className="size-1.5 animate-pulse rounded-full bg-muted-foreground/50" />
+    </div>
+  );
+}