@tleblancureta/proto 0.1.0

package/core-web/src/lib/api.ts

@@ -0,0 +1,231 @@
+import { GATEWAY_URL, INTERNAL_SECRET as SECRET, WS_URL } from './config'
+
+export interface StreamEvent {
+  type: 'init' | 'text' | 'tool_use' | 'tool_result' | 'result' | 'error' | 'thinking' | 'auth' | 'pong' | 'shell_refresh'
+  text?: string
+  tool?: string
+  args?: Record<string, unknown>
+  content?: string
+  message?: string
+  session_id?: string
+  duration_ms?: number
+  cost_usd?: number
+  status?: string
+}
+
+type EventHandler = (event: StreamEvent) => void
+
+class ProtoSocket {
+  private ws: WebSocket | null = null
+  private authenticated = false
+  private messageHandler: EventHandler | null = null
+  private shellRefreshHandler: (() => void) | null = null
+  private connectPromise: Promise<void> | null = null
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private pingTimer: ReturnType<typeof setInterval> | null = null
+  private reconnectDelay = 3000
+  private static readonly MAX_RECONNECT_DELAY = 60000
+
+  connect(): Promise<void> {
+    if (this.ws?.readyState === WebSocket.OPEN && this.authenticated) {
+      return Promise.resolve()
+    }
+
+    if (this.connectPromise) return this.connectPromise
+
+    this.connectPromise = new Promise((resolve, reject) => {
+      this.ws = new WebSocket(WS_URL)
+
+      this.ws.onopen = () => {
+        // Authenticate
+        this.ws!.send(JSON.stringify({ type: 'auth', secret: SECRET }))
+      }
+
+      this.ws.onmessage = (e) => {
+        try {
+          const event: StreamEvent = JSON.parse(e.data)
+
+          if (event.type === 'auth' && event.status === 'ok') {
+            this.authenticated = true
+            this.connectPromise = null
+            this.reconnectDelay = 3000 // reset on successful auth
+            // Start keepalive ping every 25s to prevent idle disconnects
+            if (this.pingTimer) clearInterval(this.pingTimer)
+            this.pingTimer = setInterval(() => {
+              if (this.ws?.readyState === WebSocket.OPEN) {
+                try { this.ws.send(JSON.stringify({ type: 'ping' })) } catch {}
+              }
+            }, 25000)
+            resolve()
+            return
+          }
+
+          if (event.type === 'shell_refresh') {
+            this.shellRefreshHandler?.()
+            return
+          }
+
+          if (event.type === 'pong') return
+
+          this.messageHandler?.(event)
+        } catch {}
+      }
+
+      this.ws.onclose = () => {
+        this.authenticated = false
+        this.connectPromise = null
+        if (this.pingTimer) { clearInterval(this.pingTimer); this.pingTimer = null }
+        // Synthesize an error event ONLY if a stream is in flight (handler set)
+        // so the chat turn can reset. Fire only once then clear.
+        if (this.messageHandler) {
+          try { this.messageHandler({ type: 'error', message: 'Conexion perdida. Reintenta.' }) } catch {}
+          this.messageHandler = null
+        }
+        // Auto-reconnect with exponential backoff (3s → 6s → 12s → ... → 60s max)
+        if (!this.reconnectTimer) {
+          this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null
+            this.connect().catch(() => {})
+          }, this.reconnectDelay)
+          this.reconnectDelay = Math.min(this.reconnectDelay * 2, ProtoSocket.MAX_RECONNECT_DELAY)
+        }
+      }
+
+      this.ws.onerror = () => {
+        this.connectPromise = null
+        try { this.messageHandler?.({ type: 'error', message: 'Error de conexion WebSocket' }) } catch {}
+        reject(new Error('WebSocket connection failed'))
+      }
+
+      // Timeout
+      setTimeout(() => {
+        if (!this.authenticated) {
+          this.connectPromise = null
+          reject(new Error('WebSocket auth timeout'))
+        }
+      }, 10000)
+    })
+
+    return this.connectPromise
+  }
+
+  onMessage(handler: EventHandler) {
+    this.messageHandler = handler
+  }
+
+  onShellRefresh(handler: () => void) {
+    this.shellRefreshHandler = handler
+  }
+
+  async send(data: any) {
+    await this.connect()
+    this.ws?.send(JSON.stringify(data))
+  }
+
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN && this.authenticated
+  }
+
+  disconnect() {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.ws?.close()
+    this.ws = null
+    this.authenticated = false
+  }
+}
+
+// Singleton
+export const protoSocket = new ProtoSocket()
+
+/** @deprecated Use protoSocket instead. */
+export const hermesSocket = protoSocket
+
+// Chat request params
+interface ChatParams {
+  company_id: string
+  user_id: string
+  message: string
+  session_key?: string
+  enabled_skills?: string[]
+  company_context?: string
+}
+
+/**
+ * Send a chat message via WebSocket. Events come through protoSocket.onMessage().
+ */
+export async function sendChatWs(params: ChatParams) {
+  await protoSocket.send({ type: 'chat', channel: 'web', ...params })
+}
+
+/**
+ * Reset the Claude CLI session for a company so the next message starts
+ * a fresh conversation (no --resume history).
+ */
+export async function resetSession(companyId: string, sessionKey = 'web') {
+  try {
+    await fetch(`${GATEWAY_URL}/reset`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Internal-Secret': SECRET },
+      body: JSON.stringify({ company_id: companyId, session_key: sessionKey }),
+    })
+  } catch {}
+}
+
+/**
+ * Legacy: Send chat via REST (blocking).
+ */
+export async function sendChat(params: ChatParams) {
+  const res = await fetch(`${GATEWAY_URL}/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Internal-Secret': SECRET },
+    body: JSON.stringify({ channel: 'web', ...params }),
+  })
+  if (!res.ok) throw new Error(`Error ${res.status}`)
+  return res.json()
+}
+
+/**
+ * Legacy: SSE stream (kept for fallback).
+ */
+export function streamChat(
+  params: ChatParams,
+  onEvent: (event: StreamEvent) => void,
+): AbortController {
+  const controller = new AbortController()
+
+  fetch(`${GATEWAY_URL}/chat/stream`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Internal-Secret': SECRET },
+    body: JSON.stringify({ channel: 'web', ...params }),
+    signal: controller.signal,
+  }).then(async (res) => {
+    if (!res.ok) { onEvent({ type: 'error', message: `Error ${res.status}` }); return }
+    const reader = res.body?.getReader()
+    if (!reader) return
+    const decoder = new TextDecoder()
+    let buffer = ''
+    let gotResult = false
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      const lines = buffer.split('\n')
+      buffer = lines.pop() || ''
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          try {
+            const event = JSON.parse(line.slice(6))
+            if (event.type === 'result' || event.type === 'error') gotResult = true
+            onEvent(event)
+          } catch {}
+        }
+      }
+    }
+    if (!gotResult) onEvent({ type: 'result', text: '' })
+  }).catch((err) => {
+    if (err.name !== 'AbortError') onEvent({ type: 'error', message: err.message })
+  })
+
+  return controller
+}

package/core-web/src/lib/config.ts

@@ -0,0 +1,14 @@
+/**
+ * Centralized frontend config. Every module that needs the gateway URL or
+ * the internal secret should import from here — do NOT read
+ * `import.meta.env.VITE_*` directly, so the default values stay in sync.
+ */
+
+export const GATEWAY_URL: string =
+  (import.meta.env.VITE_GATEWAY_URL as string) || 'http://localhost:8092'
+
+export const INTERNAL_SECRET: string =
+  (import.meta.env.VITE_INTERNAL_SECRET as string) || ''
+
+/** WebSocket endpoint, derived from GATEWAY_URL. */
+export const WS_URL: string = GATEWAY_URL.replace(/^http/, 'ws') + '/ws'

package/core-web/src/lib/define-widget.ts

@@ -0,0 +1,71 @@
+/**
+ * defineWidget — declarative shell widget definition.
+ *
+ * App code declares widgets as data instead of hardcoding a switch in Shell.
+ * Each widget provides a `render(instance, ctx)` function that returns the
+ * React node, pulling whatever it needs from the shared ShellContext.
+ *
+ * The `ShellContext` interface below contains the framework-level fields every
+ * widget receives. Apps extend it via TypeScript module augmentation to add
+ * their own fields (cart state, app-specific callbacks, etc).
+ *
+ * Example augmentation in an app:
+ *
+ *   declare module 'proto/web' {
+ *     interface ShellContext {
+ *       cartItems: CartItem[]
+ *       addToCart: (item: CartItem) => void
+ *     }
+ *   }
+ */
+import type { ReactNode } from 'react'
+import type { ActiveEntity, WidgetInstance } from '../components/shell/types'
+
+export interface ShellContext {
+  companyId: string
+  refreshKey: number
+  activeEntity: ActiveEntity | null
+
+  onSendToChat: (message: string) => void
+  onActivateEntity?: (e: ActiveEntity) => void
+  onDeactivateEntity?: () => void
+  onCloseTab?: (e: ActiveEntity) => void
+
+  /** Force widgets to re-fetch without a full shell reload. */
+  triggerLocalRefresh: () => void
+}
+
+export type WidgetCategory = 'general' | 'cockpit'
+
+export interface WidgetSize {
+  w: number
+  h: number
+  minW: number
+  minH: number
+}
+
+export interface WidgetDefinition {
+  type: string
+  title: string
+  icon?: string
+  category: WidgetCategory
+  defaultSize?: WidgetSize
+  render: (instance: WidgetInstance, ctx: ShellContext) => ReactNode
+}
+
+export function defineWidget(def: WidgetDefinition): WidgetDefinition {
+  return def
+}
+
+export type WidgetRegistry = Map<string, WidgetDefinition>
+
+export function buildWidgetRegistry(defs: readonly WidgetDefinition[]): WidgetRegistry {
+  const map: WidgetRegistry = new Map()
+  for (const def of defs) {
+    if (map.has(def.type)) {
+      console.warn(`[defineWidget] duplicate widget type: ${def.type}`)
+    }
+    map.set(def.type, def)
+  }
+  return map
+}

package/core-web/src/lib/drag.ts

@@ -0,0 +1,45 @@
+export interface DragContext {
+  type: string
+  id: string
+  label: string
+  meta?: string
+  agentContext: {
+    entity: string
+    id: string
+    summary: Record<string, any>
+  }
+}
+
+export function setDragData(e: React.DragEvent, ctx: DragContext) {
+  e.dataTransfer.setData('application/proto', JSON.stringify(ctx))
+  e.dataTransfer.effectAllowed = 'copy'
+}
+
+export function getDragData(e: React.DragEvent): DragContext | null {
+  try {
+    const raw = e.dataTransfer.getData('application/proto')
+    return raw ? JSON.parse(raw) : null
+  } catch { return null }
+}
+
+export function hasDragData(e: React.DragEvent): boolean {
+  return e.dataTransfer.types.includes('application/proto')
+}
+
+/**
+ * Build structured context for the agent.
+ * Injected as context prefix, not as user message text.
+ */
+export function buildAgentPrompt(ctx: DragContext): string {
+  const { entity, id, summary } = ctx.agentContext
+  const lines = Object.entries(summary)
+    .filter(([_, v]) => v != null && v !== '')
+    .map(([k, v]) => `  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`)
+
+  return [
+    `[CONTEXTO: El usuario selecciono un ${entity}]`,
+    `ID: ${id}`,
+    ...lines,
+    `[Consulta datos actualizados con los tools MCP si necesitas mas detalle. No repitas info que ya tienes.]`,
+  ].join('\n')
+}

package/core-web/src/lib/supabase.ts

@@ -0,0 +1,6 @@
+import { createClient } from '@supabase/supabase-js'
+
+const url = import.meta.env.VITE_SUPABASE_URL as string
+const anonKey = import.meta.env.VITE_SUPABASE_ANON_KEY as string
+
+export const supabase = createClient(url, anonKey)

package/core-web/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/core-web/src/lib/widgetCache.ts

@@ -0,0 +1,29 @@
+/**
+ * Tiny in-memory cache for cockpit widget data.
+ *
+ * Keyed by `${widgetName}:${entityId}`. Lives for the page session.
+ *
+ * Usage pattern in widgets:
+ *   const [data, setData] = useState(() => cacheGet(key))
+ *   useEffect(() => {
+ *     fetch().then(d => { cacheSet(key, d); setData(d) })
+ *   }, [id, refreshKey])
+ *
+ * If cached, the widget renders instantly with stale data, then silently
+ * swaps to fresh data when the fetch resolves. No skeleton on re-visits.
+ */
+
+const store = new Map<string, unknown>()
+
+export function cacheGet<T>(key: string): T | undefined {
+  return store.get(key) as T | undefined
+}
+
+export function cacheSet<T>(key: string, value: T): void {
+  store.set(key, value)
+}
+
+export function cacheClear(key?: string): void {
+  if (key) store.delete(key)
+  else store.clear()
+}

package/core-web/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/dist/core-mcp/src/app.d.ts

@@ -0,0 +1,40 @@
+import { type ToolDefinition } from './define-tool.js';
+import type { EntityDefinition } from '../../core-shared/src/index.js';
+import type { WorkflowDefinition } from '../../core-shared/src/index.js';
+export interface ProtoMcpOptions {
+    /** App name (used in MCP server metadata). */
+    name: string;
+    version?: string;
+    /**
+     * Directory containing tool files. Each .ts/.js file should export
+     * default an array of ToolDefinition objects.
+     * Defaults to ./tools (relative to the calling file).
+     */
+    toolsDir?: string;
+    /**
+     * Path to entities barrel (e.g. ./entities/index.ts).
+     * Should export `ENTITIES` as an array of EntityDefinition.
+     * If omitted, auto-detected from ./entities/index.
+     */
+    entitiesPath?: string;
+    /**
+     * Path to workflow definition file, or an already-imported WorkflowDefinition.
+     * If omitted, auto-detected from ./workflows/*.
+     */
+    workflow?: string | WorkflowDefinition;
+    /** Extra tools to register alongside auto-discovered ones. */
+    extraTools?: ToolDefinition[];
+    /** Extra entities to register alongside auto-discovered ones. */
+    extraEntities?: EntityDefinition[];
+}
+export declare function createProtoMcp(opts: ProtoMcpOptions): Promise<{
+    /** Run as stdio subprocess (for Claude Code CLI). */
+    stdio(): Promise<void>;
+    /** Run as HTTP server (for Docker / standalone). */
+    http(httpOpts?: {
+        port?: number;
+    }): Promise<void>;
+    /** Get tool count (for smoke tests). */
+    readonly toolCount: number;
+}>;
+//# sourceMappingURL=app.d.ts.map

package/dist/core-mcp/src/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../core-mcp/src/app.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAKrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAExE,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAAA;IAEtC,8DAA8D;IAC9D,UAAU,CAAC,EAAE,cAAc,EAAE,CAAA;IAE7B,iEAAiE;IACjE,aAAa,CAAC,EAAE,gBAAgB,EAAE,CAAA;CACnC;AAwED,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe;IAyCtD,qDAAqD;;IAMrD,oDAAoD;oBAC9B;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;IASvC,wCAAwC;;GAM3C"}

package/dist/core-mcp/src/app.js

@@ -0,0 +1,141 @@
+/**
+ * createProtoMcp — single-call factory that builds a fully-wired MCP app.
+ *
+ * Auto-discovers tools, entities, and workflows from the app directory.
+ * The developer only writes tool files (export default [...]) and optionally
+ * entities/index + workflows — everything else is handled by the framework.
+ *
+ * Usage:
+ *
+ *   // app/mcp.ts (stdio)
+ *   import { createProtoMcp } from 'proto/mcp'
+ *   const app = await createProtoMcp({ name: 'my-app' })
+ *   await app.stdio()
+ *
+ *   // app/mcp-http.ts (HTTP)
+ *   import { createProtoMcp } from 'proto/mcp'
+ *   const app = await createProtoMcp({ name: 'my-app' })
+ *   await app.http({ port: 8093 })
+ */
+import { readdirSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createMcpServer, runStdio, runHttp } from './index.js';
+import { registerTools } from './define-tool.js';
+import { registerUiTools } from './tools/ui.js';
+import { registerEntityTools } from './entity-tools.js';
+import { registerWorkflowTools } from './workflow-tools.js';
+async function loadToolsFromDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter(f => (f.endsWith('.ts') || f.endsWith('.js')) && f !== 'index.ts' && f !== 'index.js');
+    const allTools = [];
+    for (const file of files) {
+        const fullPath = join(dir, file);
+        const mod = await import(pathToFileURL(fullPath).href);
+        const tools = mod.default;
+        if (Array.isArray(tools)) {
+            allTools.push(...tools);
+        }
+    }
+    return allTools;
+}
+async function loadEntities(dirOrBarrel) {
+    // Try barrel file first (index.ts/index.js)
+    for (const ext of ['.ts', '.js']) {
+        const p = dirOrBarrel + ext;
+        if (existsSync(p)) {
+            const mod = await import(pathToFileURL(p).href);
+            return mod.ENTITIES || mod.default || [];
+        }
+    }
+    // Auto-discover individual entity files from the directory
+    const dir = dirname(dirOrBarrel);
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter(f => (f.endsWith('.ts') || f.endsWith('.js')) && f !== 'index.ts' && f !== 'index.js');
+    const entities = [];
+    for (const file of files) {
+        const mod = await import(pathToFileURL(join(dir, file)).href);
+        if (mod.default && typeof mod.default === 'object' && 'name' in mod.default) {
+            entities.push(mod.default);
+        }
+    }
+    return entities;
+}
+async function loadWorkflow(basePath) {
+    if (!existsSync(basePath))
+        return null;
+    const files = readdirSync(basePath).filter(f => (f.endsWith('.ts') || f.endsWith('.js')) && !f.startsWith('_'));
+    if (files.length === 0)
+        return null;
+    // Load the first workflow file found
+    const mod = await import(pathToFileURL(join(basePath, files[0])).href);
+    return mod.default || null;
+}
+function resolveAppDir(callerUrl) {
+    if (callerUrl) {
+        return dirname(callerUrl.replace('file://', ''));
+    }
+    return process.cwd();
+}
+export async function createProtoMcp(opts) {
+    // Resolve paths relative to cwd (app root)
+    const appDir = process.cwd();
+    const toolsDir = opts.toolsDir
+        ? resolve(appDir, opts.toolsDir)
+        : resolve(appDir, 'app', 'tools');
+    const entitiesPath = opts.entitiesPath
+        ? resolve(appDir, opts.entitiesPath)
+        : resolve(appDir, 'app', 'entities', 'index');
+    const workflowsDir = resolve(appDir, 'app', 'workflows');
+    // Load everything
+    const tools = await loadToolsFromDir(toolsDir);
+    const entities = await loadEntities(entitiesPath);
+    const extraTools = opts.extraTools || [];
+    const extraEntities = opts.extraEntities || [];
+    const allTools = [...tools, ...extraTools];
+    const allEntities = [...entities, ...extraEntities];
+    let workflow = null;
+    if (opts.workflow) {
+        workflow = typeof opts.workflow === 'string'
+            ? await loadWorkflow(resolve(appDir, opts.workflow)).then(w => w)
+            : opts.workflow;
+    }
+    else {
+        workflow = await loadWorkflow(workflowsDir);
+    }
+    function buildServer() {
+        const server = createMcpServer({ name: opts.name, version: opts.version });
+        registerUiTools(server);
+        if (allTools.length > 0)
+            registerTools(server, allTools);
+        if (allEntities.length > 0)
+            registerEntityTools(server, allEntities);
+        if (workflow)
+            registerWorkflowTools(server, workflow);
+        return server;
+    }
+    return {
+        /** Run as stdio subprocess (for Claude Code CLI). */
+        async stdio() {
+            const server = buildServer();
+            await runStdio(server);
+        },
+        /** Run as HTTP server (for Docker / standalone). */
+        async http(httpOpts) {
+            const port = httpOpts?.port || parseInt(process.env.MCP_PORT || '8093', 10);
+            await runHttp({
+                port,
+                displayName: opts.name,
+                buildServer,
+            });
+        },
+        /** Get tool count (for smoke tests). */
+        get toolCount() {
+            const server = buildServer();
+            return Object.keys(server._registeredTools).length;
+        },
+    };
+}
+//# sourceMappingURL=app.js.map

package/dist/core-mcp/src/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../../core-mcp/src/app.ts"],"names":[],"mappings":"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"}

package/dist/core-mcp/src/define-tool.d.ts

@@ -0,0 +1,70 @@
+/**
+ * defineTool — declarative MCP tool definition.
+ *
+ * App code declares tools as data instead of calling server.tool() directly.
+ * The framework later registers them via registerTools(), giving us a
+ * single place to wrap handlers with context injection, error normalization,
+ * logging, metrics, etc.
+ *
+ * Example (app-space):
+ *
+ *   import { defineTool } from 'proto/mcp'
+ *   import { z } from 'zod'
+ *
+ *   export default [
+ *     defineTool({
+ *       name: 'create_thing',
+ *       description: 'Creates a thing.',
+ *       schema: { name: z.string() },
+ *       handler: async (args) => {
+ *         // ... do work ...
+ *         return { content: [{ type: 'text', text: 'ok' }] }
+ *       },
+ *     }),
+ *   ]
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+/**
+ * Minimal MCP tool response shape. Tools that need structured agent responses
+ * should use the `agent()` / `agentErr()` helpers from @proto/core-mcp and
+ * return their output. Index signature matches the MCP SDK's tool callback
+ * return type (allows fields like `_meta`, `isError`, etc.).
+ */
+export interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    [key: string]: unknown;
+}
+/**
+ * Handler signature. Receives validated args (inferred from the Zod schema)
+ * and must return an MCP-shaped result. Throwing is allowed — the framework
+ * wraps the handler in try/catch and returns a normalized error response.
+ */
+export type ToolHandler<S extends z.ZodRawShape> = (args: z.infer<z.ZodObject<S>>) => Promise<ToolResult> | ToolResult;
+/**
+ * Declarative tool definition. `schema` is a Zod raw shape (the same object
+ * you'd pass as the third argument to `server.tool()` today).
+ */
+export interface ToolDefinition<S extends z.ZodRawShape = z.ZodRawShape> {
+    name: string;
+    description: string;
+    schema: S;
+    handler: ToolHandler<S>;
+}
+/**
+ * Identity helper with type inference. Pass a definition object, get it back
+ * unchanged. Use in default exports of app/tools files:
+ *
+ *   export default [defineTool({ ... }), defineTool({ ... })]
+ */
+export declare function defineTool<S extends z.ZodRawShape>(def: ToolDefinition<S>): ToolDefinition<S>;
+/**
+ * Register an array of tool definitions on a server instance. Wraps each
+ * handler in a try/catch that emits a normalized error response if the tool
+ * throws.
+ */
+export declare function registerTools(server: McpServer, defs: readonly ToolDefinition[]): void;
+//# sourceMappingURL=define-tool.d.ts.map

package/dist/core-mcp/src/define-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../../core-mcp/src/define-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,IAAI,CACjD,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAC1B,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAA;AAErC;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,CAAC,CAAA;IACT,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAChD,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GACrB,cAAc,CAAC,CAAC,CAAC,CAEnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,SAAS,cAAc,EAAE,GAC9B,IAAI,CA0BN"}