toolnexus 0.23.0 → 0.25.0

package/src/toolconcurrency.ts

@@ -0,0 +1,67 @@
+/**
+ * Tool scheduling (SPEC §8 "Tool scheduling"): the calls of one model response run in emitted
+ * order as consecutive runs — safe calls overlap under a cap, each unsafe call runs alone.
+ */
+import type { Tool } from "./types.js"
+
+/** The cap when neither the option nor TOOLNEXUS_MAX_TOOL_CONCURRENCY sets one. */
+export const DEFAULT_MAX_TOOL_CONCURRENCY = 10
+
+/** option > env TOOLNEXUS_MAX_TOOL_CONCURRENCY > 10. Non-positive or non-numeric values fall back. */
+export function resolveMaxToolConcurrency(option?: number): number {
+  if (typeof option === "number" && Number.isInteger(option) && option > 0) return option
+  const raw = typeof process !== "undefined" ? process.env.TOOLNEXUS_MAX_TOOL_CONCURRENCY : undefined
+  if (raw !== undefined && /^\s*[+]?\d+\s*$/.test(raw)) {
+    const n = Number.parseInt(raw, 10)
+    if (n > 0) return n
+  }
+  return DEFAULT_MAX_TOOL_CONCURRENCY
+}
+
+/** Whether a call to `tool` with `args` may run alongside other safe calls. The tool's own
+ * predicate wins; otherwise only a tool whose hints say readOnly is safe. */
+export function isConcurrencySafe(tool: Tool, args: Record<string, unknown>): boolean {
+  if (tool.concurrencySafe) return tool.concurrencySafe(args)
+  return tool.hints?.readOnly === true
+}
+
+/** Runs `fn` over `items` in emitted order: safe items overlap (at most `cap`), an unsafe item
+ * waits for everything before it and runs alone. Results keep item order. The first failure
+ * stops new items from starting and is rethrown once the running ones settle. */
+export async function scheduleCalls<T, R>(
+  items: T[],
+  safe: (item: T) => boolean,
+  cap: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const out = new Array<R>(items.length)
+  const running = new Set<Promise<void>>()
+  let failed: { e: unknown } | undefined
+  for (let i = 0; i < items.length && !failed; i++) {
+    const item = items[i]
+    if (!safe(item)) {
+      await Promise.all(running)
+      if (failed) break
+      try {
+        out[i] = await fn(item)
+      } catch (e) {
+        failed = { e }
+      }
+      continue
+    }
+    while (running.size >= cap) await Promise.race(running)
+    if (failed) break
+    const p: Promise<void> = fn(item).then(
+      (r) => {
+        out[i] = r
+      },
+      (e) => {
+        if (!failed) failed = { e }
+      },
+    ).finally(() => running.delete(p))
+    running.add(p)
+  }
+  await Promise.all(running)
+  if (failed) throw failed.e
+  return out
+}

package/src/toolkit.ts

@@ -8,9 +8,11 @@ import { loadSkills, type SkillDef, type SkillSource } from "./skill.js"
 import { selectBuiltins, type BuiltinsConfig } from "./builtin.js"
 import { agentTools, parseAgentsConfig, type Agent } from "./a2a.js"
 import { startA2AServer, type A2AConfig, type OnTask, type ServeHandle } from "./serve.js"
-import { type MCPServeConfig, type OnCall } from "./mcpserve.js"
+import { serveLocalMcp, type LocalMcpServer, type MCPServeConfig, type OnCall } from "./mcpserve.js"
+import { createMcpHandler, type McpHandler, type McpHandlerConfig } from "./mcphandler.js"
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.js"
 import type { Client } from "./client.js"
+import type { Media } from "./media.js"
 
 export interface ToolkitOptions {
   mcpConfig?: string | object
@@ -31,6 +33,8 @@ export interface ToolkitOptions {
   /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
   skillSampleLimit?: number
   extraTools?: Tool[]
+  /** Media generation (§7G): registers `media.tools()` (source "media"). */
+  media?: Media
   /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
   builtins?: BuiltinsConfig
   /** Remote A2A agents — each advertised skill becomes a tool (source:"a2a"). */
@@ -45,6 +49,10 @@ export interface ToolkitOptions {
   /** §2 Gap 3. Bounds the MCP load: each connect/list is capped by the server timeout and the
    * whole load aborts promptly if this signal fires. Omit ⇒ unbounded as before. */
   signal?: AbortSignal
+  /** §2A.1a where MCP OAuth tokens live (default: in memory, per load). */
+  tokenStore?: import("./mcp2026/auth.js").TokenStore
+  /** §2A.1a how `auto` MCP OAuth opens the authorization URL (default: the OS opener). */
+  openUrl?: (url: string) => unknown | Promise<unknown>
 }
 
 export class Toolkit {
@@ -80,12 +88,13 @@ export class Toolkit {
   }
 
   static async create(opts: ToolkitOptions = {}): Promise<Toolkit> {
-    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal }) : undefined
+    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal, tokenStore: opts.tokenStore, openUrl: opts.openUrl, disableTools: opts.disableTools }) : undefined
     // Skills come from directories, in-memory data, and/or a lazy provider (§3,
     // S1). The provider is resolved here (create() is async) and merged with the
     // data list; a provider failure is isolated so other sources still load.
     let skill: SkillSource | undefined
-    if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined) {
+    const mcpSkills = mcp?.skills ?? []
+    if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined || mcpSkills.length > 0) {
       let providerDefs: SkillDef[] = []
       if (opts.skillProvider) {
         try {
@@ -95,7 +104,8 @@ export class Toolkit {
           providerDefs = []
         }
       }
-      const dataDefs = [...(opts.skills ?? []), ...providerDefs]
+      // §2.7 remote skills (MCP skills extension) join the same inventory, after local ones.
+      const dataDefs = [...(opts.skills ?? []), ...providerDefs, ...mcpSkills]
       // disableSkills is sugar over a skillsFilter drop-list: fold each name in as false
       // WITHOUT overriding an explicit skillsFilter entry (explicit entries win).
       const filter =
@@ -137,7 +147,7 @@ export class Toolkit {
         }),
       ),
     )
-    const agentToolsFlat = agentToolLists.flat()
+    const agentToolsFlat = [...agentToolLists.flat(), ...(opts.media ? opts.media.tools() : [])]
 
     // A2A inbound profile: a top-level `a2a` block on a parsed config object
     // (mirrors builtins/agents). serve() prefers its inline `a2a` over this.
@@ -218,6 +228,26 @@ export class Toolkit {
     })
   }
 
+  /**
+   * §7C.1 (ADR 0039). An embeddable streamable-HTTP MCP server as a Node request listener
+   * `(req, res) => void` (+ `notifyToolsChanged()`), to mount on the host's own server/router
+   * behind its own TLS, CORS and OAuth. Every policy is a hook in `cfg`; `serve()` is unchanged.
+   * Without `cfg.listTools` it exposes this toolkit's tools.
+   */
+  mcpHandler(cfg: McpHandlerConfig = {}): McpHandler {
+    return createMcpHandler(() => this.tools(), cfg)
+  }
+
+  /**
+   * SPEC §8C. Serves this toolkit for a local agent to call: the §7C MCP mapping (tool names
+   * verbatim, `skill` stays `skill`, optional `config` filter) on `127.0.0.1:<ephemeral>/mcp`
+   * behind a fresh 64-hex bearer token. The caller builds whatever `mcpServers` entry its agent
+   * accepts from `{url, token}`; `close()` stops it (idempotent).
+   */
+  asMcpServer(config?: MCPServeConfig): Promise<LocalMcpServer> {
+    return serveLocalMcp(this.tools(), config)
+  }
+
   async execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult> {
     const tool = this.byName.get(name)
     if (!tool) {

package/src/types.ts

@@ -12,7 +12,7 @@ export type JSONSchema = {
 
 import type { ContentPart } from "./content.js"
 
-export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "custom"
+export type ToolSource = "mcp" | "skill" | "builtin" | "native" | "http" | "a2a" | "media" | "custom"
 
 export interface ToolResult {
   output: string
@@ -25,6 +25,22 @@ export interface ToolResult {
    */
   parts?: ContentPart[]
   metadata?: Record<string, unknown>
+  /**
+   * Machine-readable result (MCP `structuredContent`, SPEC §1). Absent ⇒ byte-identical wire.
+   * When set and `output` is empty, MCP serve emits the JSON text of `structured` as the text block.
+   */
+  structured?: unknown
+  /** Protocol metadata for the wire result (MCP `_meta`, SPEC §1). Absent ⇒ omitted. */
+  meta?: Record<string, unknown>
+}
+
+/** MCP tool annotations (SPEC §1, §7C.1), sent verbatim on an MCP `tools/list` entry. */
+export interface ToolAnnotations {
+  title?: string
+  readOnlyHint?: boolean
+  destructiveHint?: boolean
+  idempotentHint?: boolean
+  openWorldHint?: boolean
 }
 
 export interface ToolContext {
@@ -35,6 +51,9 @@ export interface ToolContext {
   /** The model's id for this tool call, set by the client loop (§4C). A message's calls run
    * concurrently, so this is how a tool tells its sibling calls apart. Absent outside the loop. */
   callId?: string
+  /** Set by `toolkit.mcpHandler` (§7C.1): the inbound MCP request this call serves. Read it with
+   * `identityFrom(ctx)` / `requestFrom(ctx)` / `mcpSessionIdFrom(ctx)` / `mcpRequestMetaFrom(ctx)`. */
+  mcp?: import("./mcphandler.js").McpContext
 }
 
 /**
@@ -130,6 +149,13 @@ export interface Tool {
   /** What the tool may do (§4C). Builtins always carry hints; MCP tools carry them when the
    * server sends annotations. Advisory: a server can mislabel its tools. */
   hints?: ToolHints
+  /** Decides per call whether this tool may run alongside other safe calls of the same model
+   * response (SPEC §8 "Tool scheduling"). Absent ⇒ safe only when `hints.readOnly`. */
+  concurrencySafe?: (args: Record<string, unknown>) => boolean
+  /** JSON Schema of `ToolResult.structured` (SPEC §1); absent ⇒ omitted everywhere. */
+  outputSchema?: Record<string, unknown>
+  /** MCP annotations (§7C.1), verbatim on the MCP wire; absent ⇒ derived from `hints`, else omitted. */
+  annotations?: ToolAnnotations
 }
 
 export type McpStatus = "connected" | "disabled" | "failed"