Skip to content
toolnexusv0.27.0

API Reference — JavaScript

Package toolnexus (npm). See the combined API Reference for every symbol shown in eight-language synced tabs.

Toolkit

Section titled “Toolkit”
  • createToolkit(opts: ToolkitOptions): Promise<Toolkit> — the aggregator.
  • ToolkitOptions: mcpConfig, skillsDir, skills, skillProvider, skillsFilter, skillSampleLimit, builtins, agents, extraTools, waitFor, disableTools, disableSkills, signal.
  • Equivalents: create_toolkit (py) · CreateToolkit (go) · Toolkit.create (java) · Toolkit.CreateAsync (c#) · Toolnexus.create_toolkit (elixir).

Skills

Section titled “Skills”
  • loadSkills(input: string | string[] | LoadSkillsOptions): SkillSource
  • listSkills(input): SkillInventory — { skills, skipped }; skip reasons missing-name · malformed-frontmatter · duplicate-name · unreadable.
  • SkillDef { name, description?, content, resources?, base? }
  • LoadSkillsOptions { dirs?, skills?, filter?, sampleLimit? }
  • Equivalents: load_skills / list_skills (py) · LoadSkills / LoadSkillsWith / ListSkills (go) · SkillSource.load / loadWith / listSkills (java) · SkillSource.Load / LoadWith / ListSkills (c#) · Toolnexus.Skill.load / Toolnexus.Skill.list (elixir).

MCP · Adapters · Client

Section titled “MCP · Adapters · Client”
  • loadMcp(config): Promise<McpSource>
  • toOpenAI(tk) · toAnthropic(tk) · toGemini(tk)
  • createClient(opts): Client → client.ask(prompt, tk), client.stream(...).

Tools you build — native, HTTP, built-ins

Section titled “Tools you build — native, HTTP, built-ins”
  • defineTool({ name, description, inputSchema?, run }) — your function as a Tool. Decorator sugar: @tool(description, { name?, inputSchema? }) + collectTools(obj).
  • httpTool({ name, description, method, url, headers?, query?, body?, resultMode?, timeout? }) — an endpoint as a Tool.
  • builtins toggle → ten built-ins: bash · read · write · edit · grep · glob · webfetch · question · apply_patch · todowrite.
  • Equivalents: define_tool/tool · http_tool (py) · NativeTool/NativeToolReflect · HTTPTool (go) · NativeTool.of · HttpTool.of (java) · NativeTool.Of · HttpTool.Of (c#) · Toolnexus.Native.define_tool · Toolnexus.Http.tool (elixir).

Sub-agents & teams

Section titled “Sub-agents & teams”
  • agents.agent(name, spec): Agent — spec { does, uses?, soul?, soulFile?, team?, budget?, model?, waitFor? }.
  • agent.run(prompt, opts): Promise<AgentRunResult> — { status, text, totalTokens, turns, runtime }.
  • agent.asTool(opts): Tool (delegate as one tool) · composeSoul(dir): { soul, found }.
  • Equivalents: agent / .run / .as_tool / compose_soul (py) · agents.New / .Run / .AsTool / ComposeSoul (go) · Agents.agent / .run / .asTool / Agents.composeSoul (java) · new Agent / .RunAsync / .AsTool / Home.ComposeSoul (c#) · Agents.agent / Agents.run / Agents.as_tool / Agents.compose_soul (elixir).

A2A — serve & remote agents

Section titled “A2A — serve & remote agents”
  • tk.serve(addr, { client, a2a, onTask?, mcp?, onCall? }): Promise<ServeHandle> — expose the toolkit; handle.url, handle.stop().
  • agent({ card, headers?, timeout?, pollEvery? }) + createToolkit({ agents }) / tk.addAgent(cardUrl) — consume a peer’s skills as <agent>_<skill> tools.
  • Equivalents: serve / add_agent (py) · Serve / AddAgent (go) · serve / addAgent (java) · ServeAsync / AddAgentAsync (c#) · Toolkit.serve / Toolkit.add_agent (elixir).

Suspension & the human loop

Section titled “Suspension & the human loop”
  • waitFor?: (req: Request) => Promise<Answer> (toolkit option).
  • Request { id, kind, prompt, url?, data?, expiresAt? } · Answer { id, ok, data?, reason? }.
  • pending({ kind, prompt, url?, data? }): ToolResult · authRequired(url, prompt?) · pendingOf(result): Request | undefined.
  • Equivalents: wait_for / pending / auth_required / pending_of (py) · WaitFor / Pending / AuthRequired / PendingOf (go) · waitFor / ToolResult.pending / authRequired / pendingOf (java) · WithWaitFor / ToolResult.Pending / AuthRequired / PendingOf (c#) · wait_for / ToolResult.pending? (elixir).

Media generation

Section titled “Media generation”

Guide: Media generation · recipe: Generate images, video and speech · SPEC §7G.

  • loadMediaStyle(path: string): MediaStyle — read one style JSON file.
  • createMedia(styles: MediaStyle | MediaStyle[], opts?: MediaOptions): Media — a verb resolves to the first style that declares it.
  • MediaOptions { onProgress?: (p: MediaProgress) => void, fetch?: typeof fetch } — MediaProgress { verb, jobId, status } fires after every poll; fetch is the injected transport (default: global fetch).
  • Verbs, each (input: XArgs & MediaCallOptions): Promise<MediaResult>: image(ImageArgs { prompt, width?, height?, aspectRatio?, seed? }) · video(VideoArgs { prompt, image?, seconds?, aspectRatio? }) · speech(SpeechArgs { text, voice? }) · transcribe(TranscribeArgs { audio }) · cloneVoice(CloneVoiceArgs { name, samples }) · talking(TalkingArgs { image, audio }).
  • MediaCallOptions { providerOptions?, signal?: AbortSignal } — providerOptions top-level keys overwrite the request body last.
  • generate(verb: MediaVerb | string, args, callOpts?: MediaCallOptions): Promise<MediaResult> — the raw call.
  • MediaResult { files: MediaFile[], text?, jobId?, status } · MediaFile { type: "image" | "audio" | "file", mimeType, url }.
  • media.tools(): Tool[] — generate_image … talking_video (source "media"), one per supported verb; or pass createToolkit({ media }).
  • RunResult.files: RunFile[] — { type, mimeType, url?, data?, name?, from, callId }, in call order; the same parts are on toolCalls[].parts.
  • Errors: the function face throws Error with the exact §7G message; a media tool never throws (isError: true, message as output). An aborted signal rejects with signal.reason (or an AbortError). MEDIA_VERBS exports the canonical verb table.
  • Equivalents: create_media (py) · CreateMedia (go) · Media.create (java) · Media.Create (c#) · Toolnexus.Media.new (elixir) · toolnexus.media/create-media (clojure) · create_media (rust).