@lunora/mcp 1.0.0-alpha.21 → 1.0.0-alpha.23

package/README.md

@@ -40,14 +40,16 @@ Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-sa
 
 ## Tools
 
-| Tool                         | Description                                                                                                    |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `lunora_list_functions`      | List the deployment's public functions (queries, mutations, actions) with their kinds.                         |
-| `lunora_list_tables`         | List the deployment's `.global()` tables with their row counts.                                                |
-| `lunora_get_function_schema` | Return a function's argument descriptors and kind by path, so a caller can construct a valid arguments object. |
-| `lunora_run_query`           | Run a query and return its result. Read-only.                                                                  |
-| `lunora_run_mutation`        | Run a mutation and return its result. Writes data — use with care.                                             |
-| `lunora_run_action`          | Run an action and return its result. May call external services.                                               |
+| Tool                         | Description                                                                                                                                                   |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lunora_list_functions`      | List the deployment's public functions (queries, mutations, actions) with their kinds.                                                                        |
+| `lunora_list_tables`         | List the deployment's `.global()` tables with their row counts.                                                                                               |
+| `lunora_get_function_schema` | Return a function's argument descriptors and kind by path, so a caller can construct a valid arguments object.                                                |
+| `lunora_run_query`           | Run a query and return its result. Read-only.                                                                                                                 |
+| `lunora_run_mutation`        | Run a mutation and return its result. Writes data — use with care.                                                                                            |
+| `lunora_run_action`          | Run an action and return its result. May call external services.                                                                                              |
+| `agent_<name>`               | Start a durable [`@lunora/agent`](https://www.npmjs.com/package/@lunora/agent) run and await its answer. One tool per exposed agent. Requires agents enabled. |
+| `lunora_agent_status`        | Poll a running agent by `threadKey` and return its answer once finished. Requires agents enabled.                                                             |
 
 ### Recommended agent flow
 
@@ -105,6 +107,36 @@ const server = createLunoraMcpServer({ url: "https://app.example.workers.dev", t
 await server.connect(myTransport);
 ```
 
+## Expose an agent
+
+A deployment's durable [`@lunora/agent`](https://www.npmjs.com/package/@lunora/agent) agents can be fronted as MCP tools. This is **opt-in and fail-closed**, mirroring `allowWrites`: starting an agent run is a side effect, so the agent tools are omitted from the advertised list _and_ refused at dispatch unless you explicitly enable them. `@lunora/mcp` takes no dependency on `@lunora/agent` — it reaches the agent's public `agents:agentRun` mutation over RPC like any other function.
+
+Enable it with two env vars (or the matching `createLunoraMcpServer` options):
+
+- `LUNORA_MCP_ALLOW_AGENTS` — set to `1`/`true`/`yes`/`on` to expose the agent tools. Default: agents disabled.
+- `LUNORA_MCP_AGENTS` — a `;`-separated list of `name:description` pairs selecting which agents to expose, e.g. `"support:Support questions;billing:Billing help"`.
+- `LUNORA_MCP_AGENT_TIMEOUT_MS` (optional) — wall-clock budget a single `agent_<name>` call awaits before returning a pending result to poll.
+
+```jsonc
+{
+    "mcpServers": {
+        "lunora": {
+            "command": "lunora-mcp",
+            "env": {
+                "LUNORA_URL": "https://app.example.workers.dev",
+                "LUNORA_ADMIN_TOKEN": "...",
+                "LUNORA_MCP_ALLOW_AGENTS": "1",
+                "LUNORA_MCP_AGENTS": "support:Support questions;billing:Billing help",
+            },
+        },
+    },
+}
+```
+
+Each exposed agent gets an `agent_<name>` tool taking `prompt` (required), an optional `threadKey` (reuse to continue a conversation; omit to start a new thread), and an optional `title`. The tool starts a durable run and awaits it up to the timeout budget; if the run outlasts the budget it returns a pending result whose `threadKey` you feed to the generic `lunora_agent_status` tool to poll for the final answer.
+
+Runs are **owner-scoped** to the identity the configured token resolves to. Grant a **least-privilege** token mapped to a bot identity so an agent's threads stay isolated per deployment — never the admin token.
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs)**.
 
 ## Related
@@ -112,6 +144,7 @@ await server.connect(myTransport);
 - [`@lunora/client`](https://www.npmjs.com/package/@lunora/client) — the HTTP RPC client backing every tool.
 - [`@lunora/cli`](https://www.npmjs.com/package/@lunora/cli) — deploy the app the server introspects and invokes.
 - [`@lunora/server`](https://www.npmjs.com/package/@lunora/server) — defines the queries, mutations, and actions the tools call.
+- [`@lunora/agent`](https://www.npmjs.com/package/@lunora/agent) — the durable agents the `agent_<name>` tools front over RPC.
 
 ## Supported Node.js Versions
 

package/dist/bin.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { connectStdio } from './packem_shared/connectStdio-mHv2dT3u.mjs';
+import { parseAgentsEnv } from './packem_shared/AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs';
+import { connectStdio } from './packem_shared/connectStdio-bkJcaXYE.mjs';
 
 const ENABLED_ENV_VALUES = /* @__PURE__ */ new Set(["1", "on", "true", "yes"]);
 const isEnvEnabled = (value) => value !== void 0 && ENABLED_ENV_VALUES.has(value.trim().toLowerCase());
@@ -21,8 +22,17 @@ const runBin = async (environment, dependencies = {}) => {
     writeError("lunora-mcp: LUNORA_URL environment variable is required\n");
     throw new BinError("LUNORA_URL environment variable is required", 1);
   }
+  const rawTimeout = Number(environment.LUNORA_MCP_AGENT_TIMEOUT_MS);
+  const agentMaxWaitMs = Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : void 0;
   try {
-    await connect({ allowWrites: isEnvEnabled(environment.LUNORA_MCP_ALLOW_WRITES), token: environment.LUNORA_ADMIN_TOKEN, url });
+    await connect({
+      agents: parseAgentsEnv(environment.LUNORA_MCP_AGENTS),
+      allowAgents: isEnvEnabled(environment.LUNORA_MCP_ALLOW_AGENTS),
+      allowWrites: isEnvEnabled(environment.LUNORA_MCP_ALLOW_WRITES),
+      token: environment.LUNORA_ADMIN_TOKEN,
+      url,
+      ...agentMaxWaitMs === void 0 ? {} : { agentMaxWaitMs }
+    });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     writeError(`lunora-mcp: failed to start — ${message}

package/dist/index.d.mts

@@ -1,19 +1,8 @@
+import { LunoraClient } from '@lunora/client';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { LunoraClient } from '@lunora/client';
 import { X402ChargeConfig, X402Price } from '@lunora/x402/charge';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-interface LunoraMcpServerOptions {
-  allowWrites?: boolean;
-  client?: LunoraClient;
-  fetch?: typeof fetch;
-  token?: string;
-  url?: string;
-}
-declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server;
-declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
-type McpFetchHandler = (request: Request) => Promise<Response>;
-declare const createMcpFetchHandler: (options: LunoraMcpServerOptions) => McpFetchHandler;
 interface ToolInputSchema {
   properties: Record<string, unknown>;
   required?: ReadonlyArray<string>;
@@ -35,6 +24,38 @@ declare const READ_ONLY_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
 declare const WRITE_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
 declare const toolDefinitions: (allowWrites: boolean) => ReadonlyArray<ToolDefinition>;
 declare const callTool: (client: LunoraClient, name: string, input: Record<string, unknown>, allowWrites?: boolean) => Promise<ToolResult>;
+interface McpAgentExposure {
+  description: string;
+  name: string;
+  toolName?: string;
+}
+declare const AGENT_STATUS_TOOL_NAME = "lunora_agent_status";
+declare const AGENT_RUN_INPUT_SCHEMA: ToolInputSchema;
+declare const parseAgentsEnv: (raw: string | undefined) => McpAgentExposure[];
+declare const agentToolDefinitions: (exposures: ReadonlyArray<McpAgentExposure>, allowAgents: boolean) => ReadonlyArray<ToolDefinition>;
+interface CallAgentToolOptions {
+  allowAgents: boolean;
+  exposures: ReadonlyArray<McpAgentExposure>;
+  maxWaitMs?: number;
+  pollIntervalMs?: number;
+  wait?: (ms: number) => Promise<void>;
+}
+declare const callAgentTool: (client: LunoraClient, name: string, input: Record<string, unknown>, options: CallAgentToolOptions) => Promise<ToolResult>;
+interface LunoraMcpServerOptions {
+  agentMaxWaitMs?: number;
+  agentPollIntervalMs?: number;
+  agents?: ReadonlyArray<McpAgentExposure>;
+  allowAgents?: boolean;
+  allowWrites?: boolean;
+  client?: LunoraClient;
+  fetch?: typeof fetch;
+  token?: string;
+  url?: string;
+}
+declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server;
+declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
+type McpFetchHandler = (request: Request) => Promise<Response>;
+declare const createMcpFetchHandler: (options: LunoraMcpServerOptions) => McpFetchHandler;
 type ToolHandler = (arguments_: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
 interface RegisterToolOptions {
   annotations?: Tool["annotations"];
@@ -59,4 +80,4 @@ interface PaidMcpServer {
   tool: (options: RegisterToolOptions, handler: ToolHandler) => void;
 }
 declare const createPaidMcpServer: (config: PaidMcpServerConfig) => PaidMcpServer;
-export { type LunoraMcpServerOptions, type McpFetchHandler, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, callTool, connectStdio, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, toolDefinitions };
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, type CallAgentToolOptions, type LunoraMcpServerOptions, type McpAgentExposure, type McpFetchHandler, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectStdio, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, parseAgentsEnv, toolDefinitions };

package/dist/index.d.ts

@@ -1,19 +1,8 @@
+import { LunoraClient } from '@lunora/client';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { LunoraClient } from '@lunora/client';
 import { X402ChargeConfig, X402Price } from '@lunora/x402/charge';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-interface LunoraMcpServerOptions {
-  allowWrites?: boolean;
-  client?: LunoraClient;
-  fetch?: typeof fetch;
-  token?: string;
-  url?: string;
-}
-declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server;
-declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
-type McpFetchHandler = (request: Request) => Promise<Response>;
-declare const createMcpFetchHandler: (options: LunoraMcpServerOptions) => McpFetchHandler;
 interface ToolInputSchema {
   properties: Record<string, unknown>;
   required?: ReadonlyArray<string>;
@@ -35,6 +24,38 @@ declare const READ_ONLY_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
 declare const WRITE_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
 declare const toolDefinitions: (allowWrites: boolean) => ReadonlyArray<ToolDefinition>;
 declare const callTool: (client: LunoraClient, name: string, input: Record<string, unknown>, allowWrites?: boolean) => Promise<ToolResult>;
+interface McpAgentExposure {
+  description: string;
+  name: string;
+  toolName?: string;
+}
+declare const AGENT_STATUS_TOOL_NAME = "lunora_agent_status";
+declare const AGENT_RUN_INPUT_SCHEMA: ToolInputSchema;
+declare const parseAgentsEnv: (raw: string | undefined) => McpAgentExposure[];
+declare const agentToolDefinitions: (exposures: ReadonlyArray<McpAgentExposure>, allowAgents: boolean) => ReadonlyArray<ToolDefinition>;
+interface CallAgentToolOptions {
+  allowAgents: boolean;
+  exposures: ReadonlyArray<McpAgentExposure>;
+  maxWaitMs?: number;
+  pollIntervalMs?: number;
+  wait?: (ms: number) => Promise<void>;
+}
+declare const callAgentTool: (client: LunoraClient, name: string, input: Record<string, unknown>, options: CallAgentToolOptions) => Promise<ToolResult>;
+interface LunoraMcpServerOptions {
+  agentMaxWaitMs?: number;
+  agentPollIntervalMs?: number;
+  agents?: ReadonlyArray<McpAgentExposure>;
+  allowAgents?: boolean;
+  allowWrites?: boolean;
+  client?: LunoraClient;
+  fetch?: typeof fetch;
+  token?: string;
+  url?: string;
+}
+declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server;
+declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
+type McpFetchHandler = (request: Request) => Promise<Response>;
+declare const createMcpFetchHandler: (options: LunoraMcpServerOptions) => McpFetchHandler;
 type ToolHandler = (arguments_: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
 interface RegisterToolOptions {
   annotations?: Tool["annotations"];
@@ -59,4 +80,4 @@ interface PaidMcpServer {
   tool: (options: RegisterToolOptions, handler: ToolHandler) => void;
 }
 declare const createPaidMcpServer: (config: PaidMcpServerConfig) => PaidMcpServer;
-export { type LunoraMcpServerOptions, type McpFetchHandler, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, callTool, connectStdio, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, toolDefinitions };
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, type CallAgentToolOptions, type LunoraMcpServerOptions, type McpAgentExposure, type McpFetchHandler, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectStdio, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, parseAgentsEnv, toolDefinitions };

package/dist/index.mjs

@@ -1,4 +1,5 @@
-export { createMcpFetchHandler } from './packem_shared/createMcpFetchHandler-CGqlLHxj.mjs';
-export { createPaidMcpServer } from './packem_shared/createPaidMcpServer-S7RdldZo.mjs';
-export { connectStdio, createLunoraMcpServer } from './packem_shared/connectStdio-mHv2dT3u.mjs';
-export { READ_ONLY_TOOL_DEFINITIONS, WRITE_TOOL_DEFINITIONS, callTool, toolDefinitions } from './packem_shared/READ_ONLY_TOOL_DEFINITIONS-B5x61zt4.mjs';
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, agentToolDefinitions, callAgentTool, parseAgentsEnv } from './packem_shared/AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs';
+export { createMcpFetchHandler } from './packem_shared/createMcpFetchHandler-DfzBSLrm.mjs';
+export { createPaidMcpServer } from './packem_shared/createPaidMcpServer-b-qp_aEF.mjs';
+export { connectStdio, createLunoraMcpServer } from './packem_shared/connectStdio-bkJcaXYE.mjs';
+export { READ_ONLY_TOOL_DEFINITIONS, WRITE_TOOL_DEFINITIONS, callTool, toolDefinitions } from './packem_shared/READ_ONLY_TOOL_DEFINITIONS-CWb_wFd5.mjs';

package/dist/packem_shared/AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs

@@ -0,0 +1,168 @@
+const AGENT_RUN_PATH = "agents:agentRun";
+const AGENT_THREAD_PATH = "agents:agentThread";
+const AGENT_MESSAGES_PATH = "agents:agentMessages";
+const AGENT_STATUS_TOOL_NAME = "lunora_agent_status";
+const TERMINAL_STATUSES = /* @__PURE__ */ new Set(["cancelled", "error", "idle"]);
+const DEFAULT_MAX_WAIT_MS = 6e4;
+const DEFAULT_POLL_INTERVAL_MS = 600;
+const AGENT_RUN_INPUT_SCHEMA = {
+  properties: {
+    prompt: { description: "The task or message for the agent.", type: "string" },
+    threadKey: { description: "Reuse to continue a conversation; omit to start a new thread.", type: "string" },
+    title: { description: "Optional thread title (first run only).", type: "string" }
+  },
+  required: ["prompt"],
+  type: "object"
+};
+const AGENT_STATUS_INPUT_SCHEMA = {
+  properties: {
+    threadKey: { description: "The thread key returned by an agent tool call.", type: "string" }
+  },
+  required: ["threadKey"],
+  type: "object"
+};
+const agentToolName = (exposure) => exposure.toolName ?? `agent_${exposure.name}`;
+const parseAgentsEnv = (raw) => {
+  if (raw === void 0) {
+    return [];
+  }
+  const exposures = [];
+  for (const entry of raw.split(";")) {
+    const trimmed = entry.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const separator = trimmed.indexOf(":");
+    if (separator <= 0) {
+      continue;
+    }
+    const name = trimmed.slice(0, separator).trim();
+    const description = trimmed.slice(separator + 1).trim();
+    if (name.length === 0 || description.length === 0) {
+      continue;
+    }
+    exposures.push({ description, name });
+  }
+  return exposures;
+};
+const agentToolDefinitions = (exposures, allowAgents) => {
+  if (allowAgents !== true || exposures.length === 0) {
+    return [];
+  }
+  const perAgent = exposures.map((exposure) => {
+    return {
+      description: `${exposure.description} Starts a durable agent run and returns its final answer.`,
+      inputSchema: AGENT_RUN_INPUT_SCHEMA,
+      name: agentToolName(exposure)
+    };
+  });
+  return [
+    ...perAgent,
+    {
+      description: "Check the status of a durable agent run (and its answer if finished) by its threadKey.",
+      inputSchema: AGENT_STATUS_INPUT_SCHEMA,
+      name: AGENT_STATUS_TOOL_NAME
+    }
+  ];
+};
+const isAgentToolName = (name, exposures) => name === AGENT_STATUS_TOOL_NAME || exposures.some((exposure) => agentToolName(exposure) === name);
+const freshThreadKey = () => `mcp-${crypto.randomUUID()}`;
+const reference = (path) => {
+  return { __lunoraRef: path };
+};
+const defaultWait = async (ms) => {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+};
+const ok = (value) => {
+  return { content: [{ text: JSON.stringify(value, void 0, 2), type: "text" }] };
+};
+const fail = (text) => {
+  return { content: [{ text, type: "text" }], isError: true };
+};
+const readString = (input, key) => {
+  const value = input[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+const finalAnswer = (messages) => {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const row = messages[index];
+    const toolCalls = row?.["toolCalls"];
+    const pending = Array.isArray(toolCalls) && toolCalls.length > 0;
+    if (row?.["role"] === "assistant" && !pending) {
+      return typeof row["content"] === "string" ? row["content"] : "";
+    }
+  }
+  return "";
+};
+const readThreadStatus = (thread) => {
+  if (thread !== null && typeof thread === "object" && typeof thread.status === "string") {
+    return thread.status;
+  }
+  return "unknown";
+};
+const readTerminal = async (client, threadKey, status, thread) => {
+  const messages = await client.query(reference(AGENT_MESSAGES_PATH), { key: threadKey });
+  if (status === "error") {
+    const error = thread !== null && typeof thread === "object" ? thread.error : void 0;
+    return ok({ error: typeof error === "string" ? error : "the agent run failed", status, threadKey });
+  }
+  return ok({ status, text: finalAnswer(messages), threadKey });
+};
+const callAgentStatus = async (client, input) => {
+  const threadKey = readString(input, "threadKey");
+  if (threadKey === void 0) {
+    return fail('"threadKey" is required and must be a non-empty string');
+  }
+  const thread = await client.query(reference(AGENT_THREAD_PATH), { key: threadKey });
+  const status = readThreadStatus(thread);
+  if (TERMINAL_STATUSES.has(status)) {
+    return readTerminal(client, threadKey, status, thread);
+  }
+  return ok({ status: status === "unknown" ? "running" : status, threadKey });
+};
+const callAgentTool = async (client, name, input, options) => {
+  try {
+    if (options.allowAgents !== true) {
+      return fail(`tool "${name}" is disabled: agent tools are off. Enable them with the LUNORA_MCP_ALLOW_AGENTS env var.`);
+    }
+    if (name === AGENT_STATUS_TOOL_NAME) {
+      return await callAgentStatus(client, input);
+    }
+    const exposure = options.exposures.find((candidate) => agentToolName(candidate) === name);
+    if (exposure === void 0) {
+      return fail(`agent tool "${name}" is not exposed by this MCP server`);
+    }
+    const prompt = readString(input, "prompt");
+    if (prompt === void 0) {
+      return fail('"prompt" is required and must be a non-empty string');
+    }
+    const threadKey = readString(input, "threadKey") ?? freshThreadKey();
+    const title = readString(input, "title");
+    const { id } = await client.mutation(reference(AGENT_RUN_PATH), {
+      agent: exposure.name,
+      input: prompt,
+      threadKey,
+      ...title === void 0 ? {} : { title }
+    });
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    const wait = options.wait ?? defaultWait;
+    const maxPolls = Math.max(1, Math.ceil(maxWaitMs / pollIntervalMs));
+    for (let attempt = 0; attempt < maxPolls; attempt += 1) {
+      const thread = await client.query(reference(AGENT_THREAD_PATH), { key: threadKey });
+      const status = readThreadStatus(thread);
+      if (TERMINAL_STATUSES.has(status)) {
+        return await readTerminal(client, threadKey, status, thread);
+      }
+      await wait(pollIntervalMs);
+    }
+    return ok({ hint: "call lunora_agent_status with this threadKey to poll for the answer", runId: id, status: "running", threadKey });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return fail(message);
+  }
+};
+
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, agentToolDefinitions, callAgentTool, finalAnswer, isAgentToolName, parseAgentsEnv };

package/dist/packem_shared/{READ_ONLY_TOOL_DEFINITIONS-B5x61zt4.mjs → READ_ONLY_TOOL_DEFINITIONS-CWb_wFd5.mjs}

@@ -66,23 +66,82 @@ const readFunctionPath = (input) => {
   }
   return functionPath;
 };
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const describeArgs = (value) => Array.isArray(value) ? "an array" : `a ${typeof value}`;
+const readArgumentsBag = (raw) => {
+  if (raw === void 0 || raw === null) {
+    return {};
+  }
+  if (typeof raw === "string") {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new LunoraError("BAD_REQUEST", `"args" must be a JSON object; received a string that is not valid JSON`);
+    }
+    if (!isPlainObject(parsed)) {
+      throw new LunoraError("BAD_REQUEST", `"args" must be a JSON object; the provided string decoded to ${describeArgs(parsed)}`);
+    }
+    return parsed;
+  }
+  if (!isPlainObject(raw)) {
+    throw new LunoraError("BAD_REQUEST", `"args" must be a JSON object, got ${describeArgs(raw)}`);
+  }
+  return raw;
+};
 const readRunArguments = (input) => {
   const functionPath = readFunctionPath(input);
-  const rawArguments = input.args;
-  const isPlainObject = typeof rawArguments === "object" && rawArguments !== null && !Array.isArray(rawArguments);
-  const args = isPlainObject ? rawArguments : {};
+  const args = readArgumentsBag(input.args);
   const shardKey = typeof input.shardKey === "string" && input.shardKey.length > 0 ? input.shardKey : void 0;
   return { args, functionPath, shardKey };
 };
 const reference = (functionPath) => {
   return { __lunoraRef: functionPath };
 };
+const bytesToBase64 = (bytes) => {
+  let binary = "";
+  const chunk = 32768;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+  }
+  return btoa(binary);
+};
+const jsonResultReplacer = (_key, value) => {
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value instanceof ArrayBuffer) {
+    return bytesToBase64(new Uint8Array(value));
+  }
+  if (ArrayBuffer.isView(value)) {
+    const view = value;
+    return bytesToBase64(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+  }
+  return value;
+};
 const ok = (value) => {
-  const text = value === void 0 ? "null" : JSON.stringify(value, void 0, 2);
+  const text = value === void 0 ? "null" : JSON.stringify(value, jsonResultReplacer, 2);
   return { content: [{ text, type: "text" }] };
 };
+const FUNCTIONS_CACHE_TTL_MS = 3e4;
+const functionsCache = /* @__PURE__ */ new WeakMap();
+const listFunctionsCached = (client) => {
+  const now = Date.now();
+  const cached = functionsCache.get(client);
+  if (cached !== void 0 && cached.expiresAt > now) {
+    return cached.promise;
+  }
+  const promise = client.listFunctions().catch((error) => {
+    if (functionsCache.get(client)?.promise === promise) {
+      functionsCache.delete(client);
+    }
+    throw error;
+  });
+  functionsCache.set(client, { expiresAt: now + FUNCTIONS_CACHE_TTL_MS, promise });
+  return promise;
+};
 const assertRunnable = async (client, functionPath, expectedKind) => {
-  const functions = await client.listFunctions();
+  const functions = await listFunctionsCached(client);
   const descriptor = functions.find((function_) => function_.path === functionPath);
   if (descriptor === void 0) {
     throw new LunoraError("NOT_FOUND", `function not found or not public: ${functionPath}`);
@@ -104,7 +163,7 @@ const callTool = async (client, name, input, allowWrites = false) => {
     switch (name) {
       case "lunora_get_function_schema": {
         const functionPath = readFunctionPath(input);
-        const functions = await client.listFunctions();
+        const functions = await listFunctionsCached(client);
         const descriptor = functions.find((function_) => function_.path === functionPath);
         if (descriptor === void 0) {
           return { content: [{ text: `function not found: ${functionPath}`, type: "text" }], isError: true };
@@ -112,7 +171,7 @@ const callTool = async (client, name, input, allowWrites = false) => {
         return ok({ args: descriptor.args ?? [], kind: descriptor.kind, path: descriptor.path });
       }
       case "lunora_list_functions": {
-        return ok(await client.listFunctions());
+        return ok(await listFunctionsCached(client));
       }
       case "lunora_list_tables": {
         return ok(await client.listGlobalTables());

package/dist/packem_shared/{connectStdio-mHv2dT3u.mjs → connectStdio-bkJcaXYE.mjs}

@@ -6,7 +6,8 @@ import { LunoraError } from '@lunora/errors';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { toolDefinitions, callTool } from './READ_ONLY_TOOL_DEFINITIONS-B5x61zt4.mjs';
+import { agentToolDefinitions, isAgentToolName, callAgentTool } from './AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs';
+import { toolDefinitions, callTool } from './READ_ONLY_TOOL_DEFINITIONS-CWb_wFd5.mjs';
 
 const resolveVersion = () => {
   try {
@@ -47,12 +48,21 @@ const resolveClient = (options) => {
 const createLunoraMcpServer = (options) => {
   const client = resolveClient(options);
   const allowWrites = options.allowWrites ?? false;
+  const allowAgents = options.allowAgents ?? false;
+  const agents = options.agents ?? [];
   const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, () => {
-    return { tools: [...toolDefinitions(allowWrites)] };
+    return { tools: [...toolDefinitions(allowWrites), ...agentToolDefinitions(agents, allowAgents)] };
   });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const result = await callTool(client, request.params.name, request.params.arguments ?? {}, allowWrites);
+    const { arguments: rawArguments, name } = request.params;
+    const input = rawArguments ?? {};
+    const result = isAgentToolName(name, agents) ? await callAgentTool(client, name, input, {
+      allowAgents,
+      exposures: agents,
+      ...options.agentMaxWaitMs === void 0 ? {} : { maxWaitMs: options.agentMaxWaitMs },
+      ...options.agentPollIntervalMs === void 0 ? {} : { pollIntervalMs: options.agentPollIntervalMs }
+    }) : await callTool(client, name, input, allowWrites);
     return result;
   });
   return server;

package/dist/packem_shared/{createMcpFetchHandler-CGqlLHxj.mjs → createMcpFetchHandler-DfzBSLrm.mjs}

@@ -1,5 +1,5 @@
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { createLunoraMcpServer } from './connectStdio-mHv2dT3u.mjs';
+import { createLunoraMcpServer } from './connectStdio-bkJcaXYE.mjs';
 
 const serveStateless = async (server, request, options) => {
   const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true, sessionIdGenerator: void 0 });

package/dist/packem_shared/{createPaidMcpServer-S7RdldZo.mjs → createPaidMcpServer-b-qp_aEF.mjs}

@@ -2,7 +2,7 @@ import { LunoraError } from '@lunora/errors';
 import { createChargeMiddleware } from '@lunora/x402/charge';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { serveStateless } from './createMcpFetchHandler-CGqlLHxj.mjs';
+import { serveStateless } from './createMcpFetchHandler-DfzBSLrm.mjs';
 
 const DEFAULT_SERVER_INFO = { name: "lunora-paid-mcp", version: "0.0.0" };
 const CALL_TOOL_METHOD = "tools/call";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/mcp",
-  "version": "1.0.0-alpha.21",
+  "version": "1.0.0-alpha.23",
   "description": "Model Context Protocol server exposing a Lunora deployment to AI agents",
   "keywords": [
     "ai-agents",
@@ -49,9 +49,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.20",
-    "@lunora/errors": "1.0.0-alpha.3",
-    "@lunora/x402": "1.0.0-alpha.1",
+    "@lunora/client": "1.0.0-alpha.21",
+    "@lunora/errors": "1.0.0-alpha.4",
+    "@lunora/x402": "1.0.0-alpha.2",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "engines": {