@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/codeact/nodetool-api.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The `nodetool` object model — the agent-facing JS API for the CodeAct
+ * sandbox. Where an imported capability is the raw RPC surface, `nodetool.*` is the
+ * platform as objects: workflows, models, assets,
+ * jobs, collections, games, timelines, sketches, scripts, and storyboards, plus a
+ * bounded-concurrency `batch()` for fan-out (run a workflow once per CSV row,
+ * validate every timeline, render all boards).
+ *
+ * Every method is a thin wrapper over an existing belt tool, so permission
+ * gating, routing, and validation stay where they are. A method whose backing
+ * tool is missing from the belt throws a message naming the tool instead of a
+ * TypeError. The prelude assumes `CODEACT_PRELUDE` ran first (it uses
+ * the belt); `nodetool.workflows.open()` additionally uses `openWorkflow`
+ * from the graph-model prelude when that is loaded.
+ */
+/** Namespace → the belt tools that light it up (any one is enough). */
+export declare const NODETOOL_API_NAMESPACE_TOOLS: Record<string, readonly string[]>;
+/** Whether a belt carries anything the `nodetool` object model can drive. */
+export declare function hasNodetoolApiTools(toolNames: Iterable<string>): boolean;
+/**
+ * The belt tools the object model wraps — the ones the prompt should NOT
+ * also document as raw catalog signatures. One surface per capability: wrapped
+ * tools stay callable through the bridge, but the catalog documents only the
+ * `nodetool.*` form.
+ */
+export declare function nodetoolApiCoveredToolNames(toolNames: Iterable<string>): Set<string>;
+/**
+ * Guest-side prelude defining the global `nodetool`. Plain QuickJS-safe JS —
+ * no host bridges of its own; every effect goes through `__callBeltTool`.
+ */
+export declare const NODETOOL_API_PRELUDE = "\nconst nodetool = (() => {\n  // `__toolNames` is the belt, and the object model calls it through\n  // `__callBeltTool` rather than through a global belt object \u2014 there is no\n  // longer one for it to read.\n  const __belt = new Set(__toolNames);\n  const __has = (name) => __belt.has(name);\n  const __need = (name) => {\n    if (!__belt.has(name)) {\n      throw new Error(\n        'nodetool: tool \"' + name + '\" is not in this toolbelt, so this ' +\n        \"method is unavailable here. nodetool.searchTools() lists what is.\"\n      );\n    }\n    return __callBeltTool(name);\n  };\n  const __merge = (a, b) => Object.assign({}, a || {}, b || {});\n\n  /**\n   * A `create(name, opts)` call's arguments, however the caller spelled them.\n   * The documented form passes the name first, but a caller holding an options\n   * bag reaches for `create({name, ...})` \u2014 and that used to arrive at the tool\n   * as `name: {name: \"...\"}`, refused as \"name is required and must be a\n   * non-empty string\". The message described the argument, not the call, so\n   * there was nothing to correct against: a chat retried the same object shape\n   * three times before falling back to the positional form by accident. Both\n   * spellings are the same call, so both are accepted, and a name that is\n   * genuinely missing is named as the caller's own argument.\n   */\n  const __named = (nameOrOpts, opts, method) => {\n    const args =\n      nameOrOpts && typeof nameOrOpts === \"object\"\n        ? __merge(nameOrOpts, opts)\n        : __merge(opts, { name: nameOrOpts });\n    if (typeof args.name !== \"string\" || args.name.trim() === \"\") {\n      throw new Error(\n        \"nodetool.\" + method + \": a name is required. Pass it first \u2014 \" +\n        'nodetool.' + method + '(\"My name\", {...}) \u2014 or in the options ' +\n        'object as {name: \"My name\"}.'\n      );\n    }\n    return args;\n  };\n\n  /**\n   * A job id from either an id or a job/receipt object. `start()` answers with\n   * a record, and reaching for the wrong field on it used to reach the tool as\n   * `job_id: undefined`, which came back as \"Job undefined was not found\" \u2014\n   * a message about a job rather than about the call that asked for it.\n   */\n  const __jobId = (idOrJob, method) => {\n    if (typeof idOrJob === \"string\" && idOrJob) return idOrJob;\n    if (idOrJob && typeof idOrJob === \"object\") {\n      const id = idOrJob.job_id || idOrJob.id;\n      if (typeof id === \"string\" && id) return id;\n    }\n    throw new Error(\n      \"nodetool.jobs.\" + method + \": no job id. Pass the id string, or the \" +\n      \"record nodetool.workflows.start() returned (its id is job_id).\"\n    );\n  };\n\n  /** A generation id, or the record a generation capability answered with. */\n  const __generationId = (idOrRecord, method) => {\n    if (typeof idOrRecord === \"string\" && idOrRecord) return idOrRecord;\n    if (idOrRecord && typeof idOrRecord === \"object\") {\n      const id = idOrRecord.generation_id;\n      if (typeof id === \"string\" && id) return id;\n    }\n    throw new Error(\n      \"nodetool.generations.\" + method + \": no generation id. Pass the id \" +\n      \"string, or the record a generate* call returned (its id is generation_id).\"\n    );\n  };\n\n  /**\n   * Accept a GraphBuilder, a bare {nodes, edges}, or a workflow record \u2014\n   * the shared graph DSL core's normalizer.\n   */\n  const __graphJson = __graphJsonOf;\n\n  /**\n   * Build the args for a routed web-search tool. The tool routes across the\n   * configured backends host-side; `opts.provider` maps onto its `backend`\n   * pin (`aliases` translates the old guest names \u2014 \"default\", \"google\" \u2014\n   * onto the tool's backend enum; other values pass through).\n   */\n  const __webArgs = (opts, aliases, field, query) => {\n    const args = __merge(opts);\n    const provider = args.provider;\n    delete args.provider;\n    if (provider !== undefined) args.backend = aliases[provider] || provider;\n    args[field] = String(query === undefined || query === null ? \"\" : query);\n    return args;\n  };\n\n  /**\n   * Normalize a model reference to the {provider, model} pair the media\n   * tools take. Accepts a find/pick result ({provider, model_id}), a bare\n   * {provider, model|id}, or a \"provider/model_id\" string (split on the\n   * FIRST slash, so fal ids like \"fal_ai/fal-ai/flux/schnell\" work).\n   */\n  const __model = (m) => {\n    if (m && typeof m === \"object\") {\n      const id = m.model_id || m.model || m.id;\n      if (m.provider && id) return { provider: m.provider, model: id };\n    }\n    if (typeof m === \"string\" && m.indexOf(\"/\") > 0) {\n      return {\n        provider: m.slice(0, m.indexOf(\"/\")),\n        model: m.slice(m.indexOf(\"/\") + 1)\n      };\n    }\n    throw new Error(\n      \"nodetool: a model is required \u2014 pass a nodetool.models.find/pick \" +\n      'result, {provider, model_id}, or \"provider/model_id\". Use ' +\n      'await nodetool.models.pick(\"<capability>\") to resolve one.'\n    );\n  };\n\n  const api = {\n    /**\n     * Credentials, through the one bridge that has them.\n     *\n     * `getSecret` answers `undefined` for a secret nobody configured, which\n     * turns a missing key into a 401 three calls later. These throw at the\n     * point the credential was needed and name it.\n     */\n    secrets: {\n      /** A secret's value, or an error naming the one that is not set. */\n      async get(name) {\n        if (typeof name !== \"string\" || name === \"\") {\n          throw new Error(\"nodetool.secrets.get: a secret name is required\");\n        }\n        if (typeof getSecret !== \"function\") {\n          throw new Error(\n            'nodetool.secrets.get(\"' + name + '\"): this run has no secret store'\n          );\n        }\n        const value = await getSecret(name);\n        if (value === undefined || value === null || value === \"\") {\n          throw new Error(\n            'nodetool.secrets.get(\"' + name + '\"): not set. Add it under ' +\n            \"Settings > Secrets, or on the node's secret scope.\"\n          );\n        }\n        return value;\n      },\n      /** The value, or undefined \u2014 for a credential that is genuinely optional. */\n      async tryGet(name) {\n        if (typeof getSecret !== \"function\") return undefined;\n        const value = await getSecret(name);\n        return value === null || value === \"\" ? undefined : value;\n      },\n      /**\n       * The names this node declared, or null when it declared no scope and\n       * may read the whole store. Reading this is not the check: a name\n       * outside the scope is refused by the bridge, not by this list.\n       */\n      list() {\n        return typeof __secretScope === \"undefined\" || __secretScope === null\n          ? null\n          : __secretScope.slice();\n      }\n    },\n\n    /**\n     * NodeTool's own configuration, and the one way to get a credential set.\n     *\n     * `secrets` above reads; this asks. `requestSecret` sends no value and\n     * receives none \u2014 it opens a dialog where the user types the key, and\n     * answers only whether they saved one.\n     */\n    settings: {\n      /** Every non-secret setting, or one group's worth. */\n      list: (opts) => __need(\"list_settings\")(__merge(opts)),\n      /** One setting's value, resolved from this user then the environment. */\n      get: (key) => __need(\"get_setting\")({ key: key }),\n      /** Change one setting. Refuses a secret and anything undeclared. */\n      set: (key, value) => __need(\"set_setting\")({ key: key, value: value }),\n      /** Which credentials exist, never what they are. */\n      secrets: () => __need(\"list_secrets\")({}),\n      /** Ask the user to enter one, in a dialog you never see the contents of. */\n      requestSecret: (key, opts) =>\n        __need(\"request_secret\")(__merge(opts, { key: key }))\n    },\n\n    /**\n     * Find a tool the prompt lists by name only, or does not list at all.\n     * Takes the ToolSearch grammar (\"select:a,b\" for exact names, \"+term\" to\n     * require one) and returns each match's name, signature and description.\n     * Call it before calling a tool whose arguments you have not seen.\n     */\n    async searchTools(query, maxResults) {\n      if (typeof __searchTools !== \"function\") {\n        throw new Error(\n          \"nodetool.searchTools: this run has no tool catalog to search.\"\n        );\n      }\n      const r = await __searchTools(\n        String(query === undefined || query === null ? \"\" : query),\n        maxResults === undefined ? 5 : maxResults\n      );\n      if (!r || r.ok !== true) {\n        throw new Error(r && r.error ? r.error : \"nodetool.searchTools failed\");\n      }\n      return r.result;\n    },\n\n    /**\n     * What this action can import: the sandbox packs installed here, the\n     * modules each declares, the functions those export, and each pack's own\n     * documentation. A pack marked allowed:false is installed but off this\n     * session's allowlist \u2014 importing it is refused.\n     */\n    packs: (() => {\n      let cached = null;\n      const load = async (refresh) => {\n        if (cached === null || refresh === true) {\n          cached = await __need(\"list_sandbox_packages\")({});\n        }\n        return cached;\n      };\n      const packOf = (entry) => entry.packName;\n      return {\n        /**\n         * One entry per pack: {packName, description, allowed, kinds,\n         * specifiers}. Pass {refresh: true} to re-read the catalog.\n         */\n        async list(opts) {\n          const listing = await load(opts && opts.refresh);\n          const byPack = {};\n          const order = [];\n          for (const entry of listing.packages) {\n            const name = packOf(entry);\n            if (byPack[name] === undefined) {\n              byPack[name] = {\n                packName: name,\n                packVersion: entry.packVersion,\n                description: entry.description || \"\",\n                allowed: false,\n                kinds: [],\n                specifiers: []\n              };\n              order.push(name);\n            }\n            const pack = byPack[name];\n            if (!pack.description && entry.description) {\n              pack.description = entry.description;\n            }\n            if (entry.allowed) pack.allowed = true;\n            if (pack.kinds.indexOf(entry.kind) < 0) pack.kinds.push(entry.kind);\n            pack.specifiers.push(entry.specifier);\n          }\n          const packs = order.map((name) => byPack[name]);\n          if (listing.platform && listing.platform.length > 0) {\n            packs.push({\n              packName: \"@nodetool-ai/sandbox-nodetool\",\n              description:\n                \"NodeTool's own surface \u2014 the same gated calls as nodetool.*.\",\n              allowed: true,\n              kinds: [\"platform\"],\n              specifiers: listing.platform.map((entry) => entry.specifier)\n            });\n          }\n          return packs;\n        },\n        /**\n         * The importable module specifiers of one pack, each with its kind and\n         * whether this session allows it. Takes a pack name or any specifier\n         * inside the pack.\n         */\n        async modules(pack, opts) {\n          const listing = await load(opts && opts.refresh);\n          const name = String(pack === undefined || pack === null ? \"\" : pack);\n          const platform = (listing.platform || []).filter(\n            (entry) => entry.specifier === name || entry.specifier.indexOf(name) === 0\n          );\n          if (platform.length > 0) {\n            return platform.map((entry) => ({\n              specifier: entry.specifier,\n              kind: \"platform\",\n              allowed: true\n            }));\n          }\n          return listing.packages\n            .filter(\n              (entry) =>\n                packOf(entry) === name ||\n                entry.specifier === name ||\n                entry.specifier.indexOf(name + \"/\") === 0\n            )\n            .map((entry) => ({\n              specifier: entry.specifier,\n              kind: entry.kind,\n              description: entry.description,\n              allowed: entry.allowed\n            }));\n        },\n        /**\n         * The function names one module exports: {specifier, kind, exports,\n         * complete, note?}. A module whose exports cannot be read answers\n         * exports:null with the reason in note \u2014 read docs() instead of\n         * guessing.\n         */\n        exports(specifier) {\n          return __need(\"list_sandbox_packages\")({\n            specifier: String(specifier === undefined ? \"\" : specifier)\n          });\n        },\n        /** Returns a pack's SKILL.md as a markdown string. Untrusted docs retain their warning wrapper. */\n        async docs(specifier) {\n          const result = await __need(\"get_sandbox_package_docs\")({\n            specifier: String(specifier === undefined ? \"\" : specifier)\n          });\n          return result.documentation;\n        }\n      };\n    })(),\n\n    /** What this belt supports, namespace by namespace. */\n    capabilities() {\n      const caps = {};\n      const groups = __NT_NAMESPACE_TOOLS;\n      for (const ns of Object.keys(groups)) {\n        const present = groups[ns].filter(__has);\n        if (present.length > 0) caps[ns] = present;\n      }\n      return caps;\n    },\n\n    /**\n     * Bounded-concurrency map. Returns one settled entry per item:\n     * { ok, index, item, value | error }. Never throws; failures are entries.\n     * Respect the per-action tool-call budget: chunk large item lists across\n     * actions, persisting partial progress with `nodetool.memory.save`.\n     */\n    async batch(items, fn, opts) {\n      const list = Array.from(items);\n      const width = Math.max(\n        1,\n        Math.min(8, (opts && opts.concurrency) || 4)\n      );\n      const stopOnError = !!(opts && opts.stopOnError);\n      const results = new Array(list.length);\n      let next = 0;\n      let stopped = false;\n      const worker = async () => {\n        while (next < list.length && !stopped) {\n          const i = next++;\n          try {\n            results[i] = {\n              ok: true,\n              index: i,\n              item: list[i],\n              value: await fn(list[i], i)\n            };\n          } catch (e) {\n            results[i] = {\n              ok: false,\n              index: i,\n              item: list[i],\n              error: e && e.message ? e.message : String(e)\n            };\n            if (stopOnError) stopped = true;\n          }\n        }\n      };\n      const workers = [];\n      for (let w = 0; w < Math.min(width, list.length); w++) {\n        workers.push(worker());\n      }\n      await Promise.all(workers);\n      return results.filter((entry) => entry !== undefined);\n    },\n\n    nodes: {\n      /**\n       * Search the node catalog. `query` takes a string or an array of\n       * strings; `opts` passes n_results / input_type / output_type through.\n       * Answers { total, results }; a result's node type is on \"type\".\n       */\n      search: (query, opts) =>\n        __need(\"search_nodes\")(\n          __merge(opts, {\n            query: Array.isArray(query) ? query : [String(query)]\n          })\n        ),\n      /** Full metadata for ONE node type: properties, inputs, outputs. */\n      info: (type) => __need(\"get_node_info\")({ node_type: type }),\n      list: (opts) => __need(\"list_nodes\")(__merge(opts)),\n      /**\n       * The single-node harness: run ONE node by type with a property bag,\n       * no workflow needed. The cheap way to probe what a node does before\n       * wiring it into a graph.\n       */\n      run: (type, inputs) =>\n        __need(\"run_node\")({ node_type: type, inputs: inputs || {} })\n    },\n\n    agents: {\n      /**\n       * Run a sub-agent on a self-contained prompt and return its result.\n       * The child inherits this belt's tools but sees NONE of this\n       * conversation \u2014 put everything it needs into the prompt, and ask for\n       * JSON there when you want structure. Runs take real time and money;\n       * delegate work that benefits from a fresh focused context, not\n       * one-tool errands. Blocks until the child finishes; fan out with\n       * `Promise.all` or `nodetool.batch`.\n       */\n      run(prompt, opts) {\n        const text = String(prompt === undefined || prompt === null ? \"\" : prompt);\n        const description =\n          (opts && opts.description) ||\n          text.split(/\\s+/).slice(0, 6).join(\" \") ||\n          \"Subtask\";\n        return __need(\"run_subtask\")({ description: description, prompt: text });\n      },\n      /**\n       * Start a sub-agent WITHOUT blocking: returns\n       * `{subtask_id, status: \"running\"}` right away while the child works.\n       * Collect results later in the same action with `wait()` \u2014 results of\n       * subtasks you never wait for are lost to the turn.\n       */\n      start(prompt, opts) {\n        const text = String(prompt === undefined || prompt === null ? \"\" : prompt);\n        const description =\n          (opts && opts.description) ||\n          text.split(/\\s+/).slice(0, 6).join(\" \") ||\n          \"Subtask\";\n        return __need(\"start_subtask\")({ description: description, prompt: text });\n      },\n      /**\n       * Wait for background subagents started with `start()`. Pass\n       * `{ids: [...], timeoutMs}` to bound the block. Resolves with rows:\n       * `{subtask_id, status, result | error}`. Never end an action with\n       * unwaited subtasks whose results you still need.\n       */\n      wait(opts) {\n        return __need(\"wait_subtasks\")(\n          opts\n            ? {\n                ids: opts.ids,\n                timeout_ms: opts.timeoutMs\n              }\n            : {}\n        );\n      }\n    },\n\n    workflows: {\n      list: (opts) => __need(\"list_workflows\")(__merge(opts)),\n      get: (id) => __need(\"get_workflow\")({ workflow_id: id }),\n      create: (name, graph, opts) =>\n        __need(\"create_workflow\")(\n          __merge(__named(name, opts, \"workflows.create\"), {\n            graph: __graphJson(\n              graph === undefined && name && typeof name === \"object\"\n                ? name.graph\n                : graph\n            )\n          })\n        ),\n      versions: (id, opts) =>\n        __need(\"list_workflow_versions\")(__merge(opts, { workflow_id: id })),\n      getVersion: (id, version) =>\n        __need(\"get_workflow_version\")({ workflow_id: id, version: version }),\n      snapshot: (id, opts) =>\n        __need(\"create_workflow_version\")(__merge(opts, { workflow_id: id })),\n      restore: (id, version) =>\n        __need(\"restore_workflow_version\")({\n          workflow_id: id,\n          version: version\n        }),\n      deleteVersion: (id, version) =>\n        __need(\"delete_workflow_version\")({\n          workflow_id: id,\n          version: version\n        }),\n      run: (id, params, opts) =>\n        __need(\"run_workflow\")(\n          __merge(opts, { workflow_id: id, params: params || {} })\n        ),\n      /**\n       * Start a run and return a receipt \u2014 {job_id, id, status: \"running\"} \u2014\n       * without waiting for it. Pass it to nodetool.jobs.wait() and read the\n       * settled job's outputs.\n       */\n      start: (id, params) =>\n        __need(\"start_background_job\")({\n          workflow_id: id,\n          params: params || {}\n        }),\n      debug: (id, params, opts) =>\n        __need(\"debug_workflow\")(\n          __merge(opts, { workflow_id: id, params: params || {} })\n        ),\n      async validate(target) {\n        const report = await (typeof target === \"string\"\n          ? __need(\"validate_workflow\")({ workflow_id: target })\n          : __need(\"validate_workflow\")({ graph: __graphJson(target) }));\n        // A report with errors is a refusal, not data: throw so a caller\n        // that forgets to check report.ok cannot carry a broken graph into a\n        // paid run.\n        if (report && report.ok === false && Array.isArray(report.issues)) {\n          // report.ok is decided by the errors alone, so the throw lists the\n          // errors alone. Mixing in warnings and the \"untyped dynamic slot\"\n          // info notes buried one real problem under seven non-problems, and\n          // a model reading eight bullets rewrites eight things.\n          const errors = report.issues.filter(function (i) {\n            return i && i.severity === \"error\" && i.message;\n          });\n          const other = report.issues.length - errors.length;\n          const messages = (errors.length > 0 ? errors : report.issues)\n            .map(function (i) {\n              return i && i.message;\n            })\n            .filter(Boolean);\n          throw new Error(\n            \"Graph validation failed:\\n- \" +\n              messages.slice(0, 8).join(\"\\n- \") +\n              (errors.length > 0 && other > 0\n                ? \"\\n(\" +\n                  other +\n                  \" warning/info issue(s) not blocking; read report.issues\" +\n                  \" for them.)\"\n                : \"\")\n          );\n        }\n        return report;\n      },\n      /**\n       * Answer an escalation from an interactive run/debug. Action is one of\n       * the escalation's allowedActions; pass {outputs} with \"substitute\",\n       * {reason} with \"fail\", {apply_to: \"signature\"} to resolve every later\n       * failure with the same signature. Returns the NEXT escalation (answer\n       * it the same way) or the run's final report.\n       */\n      resolve: (sessionId, escalationId, action, opts) =>\n        __need(\"resolve_workflow_escalation\")(\n          __merge(opts, {\n            session_id: sessionId,\n            escalation_id: escalationId,\n            action: action\n          })\n        ),\n      /**\n       * One example workflow, graph included \u2014 a worked graph to read before\n       * authoring one. Name is \"<package>/<example>\", or pass the package\n       * separately as {package}.\n       */\n      example(name, opts) {\n        const explicit = (opts && (opts.package || opts.package_name)) || \"\";\n        let pkg = explicit;\n        let example = String(name || \"\");\n        if (!explicit) {\n          const slash = example.indexOf(\"/\");\n          if (slash > 0) {\n            pkg = example.slice(0, slash);\n            example = example.slice(slash + 1);\n          } else {\n            pkg = \"nodetool-base\";\n          }\n        }\n        if (!example) {\n          throw new Error(\n            \"nodetool.workflows.example: name an example \u2014 \" +\n            '\"<package>/<example>\", or (example, {package}). ' +\n            'nodetool.workflows.list({workflow_type: \"example\"}) lists them.'\n          );\n        }\n        return __need(\"get_example_workflow\")({\n          package_name: pkg,\n          example_name: example\n        });\n      },\n      open(id) {\n        if (typeof openWorkflow !== \"function\") {\n          // Thrown synchronously: a caller without await still sees it.\n          throw new Error(\n            \"nodetool.workflows.open: the graph editing tools (ui_*) are \" +\n            \"not in this toolbelt. Author a graph with the sandbox DSL \" +\n            \"package instead, then create() it.\"\n          );\n        }\n        return openWorkflow(id).catch((e) => {\n          const msg = e && e.message ? e.message : String(e);\n          // A browser bridge that is gone (window reloaded before the editor\n          // panel re-registered) used to surface as this bare sentence, which\n          // left one agent retrying the identical call for several turns.\n          if (/Frontend tool runtime state is not initialized/i.test(msg)) {\n            throw new Error(\n              \"nodetool.workflows.open: \" + msg +\n              \" The browser bridge answers nothing right now. Ask the user to \" +\n              \"open (or reload) the NodeTool workspace window and retry once \" +\n              \"the editor has loaded; meanwhile get_workflow still reads saved \" +\n              \"graphs and create_workflow saves new ones.\"\n            );\n          }\n          throw e;\n        });\n      }\n    },\n\n    models: {\n      find: (capability, opts) =>\n        __need(\"find_model\")(__merge(opts, { capability: capability })),\n      /**\n       * Resolve ONE model for a capability \u2014 the leaderboard's best for that\n       * task, ready to pass to nodetool.media.*. To put it in a node's model\n       * property, assign the result's \"ref\" field verbatim (the flat fields use\n       * \"model_id\"; the property wants \"id\"). Throws when no configured\n       * provider offers the capability.\n       */\n      async pick(capability, opts) {\n        const found = await __need(\"find_model\")(\n          __merge(opts, { capability: capability, limit: 1 })\n        );\n        const results = (found && found.results) || [];\n        if (results.length === 0) {\n          throw new Error(\n            'nodetool.models.pick: no configured model offers \"' +\n              capability +\n              '\"' +\n              (found && found.note ? \" \u2014 \" + found.note : \"\")\n          );\n        }\n        // A missed search must not resolve to an unrelated model \u2014 the caller\n        // asked for a named one.\n        if (found && found.query_matched === false) {\n          throw new Error(\n            \"nodetool.models.pick: no model matches \" +\n              JSON.stringify(opts && opts.query) +\n              \" for \" +\n              capability +\n              '. Call nodetool.models.find(\"' +\n              capability +\n              '\") to see what is configured.'\n          );\n        }\n        return results[0];\n      },\n      list: (opts) => __need(\"list_models\")(__merge(opts)),\n      /** One provider's own catalog. */\n      forProvider: (provider, opts) =>\n        __need(\"list_provider_models\")(__merge(opts, { provider: provider })),\n      /** One language-model roundtrip, with optional image references. */\n      generate: (prompt, model, opts) =>\n        __need(\"generate_text\")(\n          __merge(opts, __merge(__model(model), { prompt: prompt }))\n        )\n    },\n\n    media: {\n      generateImage: (prompt, model, opts) =>\n        __need(\"generate_image\")(\n          __merge(opts, __merge(__model(model), { prompt: prompt }))\n        ),\n      editImage: (inputFile, prompt, model, opts) =>\n        __need(\"edit_image\")(\n          __merge(\n            opts,\n            __merge(__model(model), { input_file: inputFile, prompt: prompt })\n          )\n        ),\n      /**\n       * Promote an image handle (or a generation result) to a durable asset.\n       * Bytes stay on the host; the guest only sees the asset:// ref.\n       */\n      toImage: (src, opts) => image.toAsset(src, opts),\n      /** Promote an audio handle to a durable asset. */\n      toAudio: (src, opts) => audio.toAsset(src, opts),\n      /** Promote a video handle to a durable asset. */\n      toVideo: (src, opts) => video.toAsset(src, opts),\n      generateVideo: (prompt, model, opts) =>\n        __need(\"generate_video\")(\n          __merge(opts, __merge(__model(model), { prompt: prompt }))\n        ),\n      animateImage: (inputFile, model, opts) =>\n        __need(\"animate_image\")(\n          __merge(opts, __merge(__model(model), { input_file: inputFile }))\n        ),\n      videoFromReferences: (referenceFiles, model, opts) =>\n        __need(\"generate_video_from_references\")(\n          __merge(\n            opts,\n            __merge(__model(model), { reference_files: referenceFiles })\n          )\n        ),\n      speak: (text, model, opts) =>\n        __need(\"generate_speech\")(\n          __merge(opts, __merge(__model(model), { text: text }))\n        ),\n      /** Music from a prompt \u2014 the counterpart of speak(). */\n      generateMusic: (prompt, model, opts) =>\n        __need(\"generate_music\")(\n          __merge(opts, __merge(__model(model), { prompt: prompt }))\n        ),\n      transcribe: (inputFile, model, opts) =>\n        __need(\"transcribe_audio\")(\n          __merge(opts, __merge(__model(model), { input_file: inputFile }))\n        ),\n      embed: (text, model, opts) =>\n        __need(\"embed_text\")(\n          __merge(opts, __merge(__model(model), { text: text }))\n        ),\n      /**\n       * Judge one image against the brief with a VISION chat model (pick\n       * \"generate_message\" on a vision-capable model). Returns a verdict plus\n       * directional defects \u2014 feed the fixes back into generateImage.\n       */\n      critique: (image, brief, model, opts) =>\n        __need(\"critique_image\")(\n          __merge(\n            opts,\n            __merge(__model(model), { image: image, brief: brief })\n          )\n        ),\n      /** Pick the best of 2-8 candidates by pairwise knockout. */\n      compare: (images, brief, model, opts) =>\n        __need(\"compare_images\")(\n          __merge(\n            opts,\n            __merge(__model(model), { images: images, brief: brief })\n          )\n        ),\n      /** Explainable adherence score: the brief as binary yes/no checks. */\n      scoreAdherence: (image, brief, model, opts) =>\n        __need(\"score_image_adherence\")(\n          __merge(\n            opts,\n            __merge(__model(model), { image: image, brief: brief })\n          )\n        ),\n      /**\n       * Read a video with a multimodal chat model (Gemini reads video\n       * natively). Returns `{text}` \u2014 the model's answer to `prompt`.\n       */\n      understandVideo: (video, prompt, model, opts) =>\n        __need(\"understand_video\")(\n          __merge(\n            opts,\n            __merge(__model(model), { video: video, prompt: prompt })\n          )\n        ),\n      /** Run ffmpeg on workspace files. `args` is argv after the binary name. */\n      ffmpeg: (args, opts) => __need(\"ffmpeg\")(__merge(opts, { args: args })),\n      /** Read a media file's format and streams with ffprobe. */\n      ffprobe: (path, opts) => __need(\"ffprobe\")(__merge(opts, { path: path })),\n      /** Download a video with yt-dlp. */\n      downloadVideo: (url, outputFile, opts) =>\n        __need(\"yt_dlp\")(__merge(opts, { url: url, output_file: outputFile }))\n    },\n\n    documents: {\n      convert: (inputFile, outputFile, opts) =>\n        __need(\"convert_document\")(\n          __merge(opts, { input_file: inputFile, output_file: outputFile })\n        ),\n      extractText: (inputFile, opts) =>\n        __need(\"extract_pdf_text\")(__merge(opts, { path: inputFile })),\n      extractTables: (inputFile, outputFile, opts) =>\n        __need(\"extract_pdf_tables\")(\n          __merge(opts, { path: inputFile, output_file: outputFile })\n        ),\n      markdownToPdf: (inputFile, outputFile, opts) =>\n        __need(\"convert_markdown_to_pdf\")(\n          __merge(opts, { input_file: inputFile, output_file: outputFile })\n        ),\n      pdfToMarkdown: (inputFile, outputFile, opts) =>\n        __need(\"convert_pdf_to_markdown\")(\n          __merge(opts, { input_file: inputFile, output_file: outputFile })\n        )\n    },\n\n    web: {\n      /**\n       * Search the web. `web_search` routes across the configured backends\n       * host-side; `opts.provider` pins one \u2014 \"default\", \"serpapi\",\n       * \"dataforseo\", \"brave\", \"apify\", \"openai\", \"google\" (grounded/Gemini).\n       */\n      search: (query, opts) =>\n        __need(\"web_search\")(\n          __webArgs(opts, { google: \"gemini\" }, \"query\", query)\n        ),\n      /** News articles. One `web_search` with search_type: \"news\". */\n      news: (query, opts) =>\n        __need(\"web_search\")(\n          __merge(__webArgs(opts, { google: \"serpapi\" }, \"query\", query), {\n            search_type: \"news\"\n          })\n        ),\n      /**\n       * Image results: title, page link, original image URL, thumbnail URL.\n       * Routes across the same backends as `search`/`news`, minus the two\n       * that answer with prose instead of results (openai, google/gemini).\n       */\n      images: (query, opts) =>\n        __need(\"image_search\")(__webArgs(opts, {}, \"query\", query)),\n      /** One HTTP request; returns the response body as text. */\n      fetch: (url, opts) => __need(\"http_request\")(__merge(opts, { url: url })),\n      /** Fetch a page and get its readable text (HTML stripped). */\n      browse: (url) => __need(\"browser\")({ url: url }),\n      /** Save a URL's bytes into the workspace. */\n      download: (url, outputFile) =>\n        __need(\"download_file\")({ url: url, output_file: outputFile }),\n      /** Render a page in a remote browser and save the PNG. */\n      screenshot: (url, outputFile) =>\n        __need(\"take_screenshot\")({\n          url: url,\n          output_file: outputFile || \"screenshot.png\"\n        })\n    },\n\n    memory: {\n      /** Remember something durably. Readable from every conversation. */\n      save: (content, opts) =>\n        __need(\"memory_save\")(__merge(opts, { content: content })),\n      list: (opts) => __need(\"memory_list\")(__merge(opts)),\n      /** Find memories by keyword. Every word must appear. */\n      search: (query, opts) =>\n        __need(\"memory_search\")(__merge(opts, { query: query })),\n      update: (memoryId, fields) =>\n        __need(\"memory_update\")(\n          __merge(fields, { memory_id: memoryId })\n        ),\n      remove: (memoryId) =>\n        __need(\"memory_delete\")({ memory_id: memoryId })\n    },\n\n    threads: {\n      /** Past conversations, most recently updated first. */\n      list: (opts) => __need(\"list_threads\")(__merge(opts)),\n      /** One thread and a page of its messages. */\n      get: (threadId, opts) =>\n        __need(\"get_thread\")(__merge(opts, { thread_id: threadId })),\n      /** The newest message in a thread, or undefined when it has none. */\n      last: (threadId) =>\n        __need(\"get_thread\")({\n          thread_id: threadId,\n          limit: 1,\n          newest_first: true\n        }).then((t) => (t && t.messages ? t.messages[0] : undefined)),\n      /** One message in full \u2014 untruncated content and every tool call. */\n      message: (messageId) =>\n        __need(\"get_message\")({ message_id: messageId })\n    },\n\n    shared: {\n      /** Metadata for every entry this run shares \u2014 no values. */\n      list: (opts) => __need(\"list_shared\")(__merge(opts)),\n      /** Full values for the keys you name; misses come back in `missing`. */\n      read: (keys) =>\n        __need(\"read_shared\")({\n          keys: Array.isArray(keys) ? keys : [keys]\n        }),\n      /** Publish under `shared:<key>` for the rest of this run to find. */\n      publish: (key, value, opts) =>\n        __need(\"share_result\")(__merge(opts, { key: key, value: value }))\n    },\n\n    email: {\n      search: (opts) => __need(\"search_email\")(__merge(opts)),\n      archive: (messageIds) =>\n        __need(\"archive_email\")({\n          message_ids: Array.isArray(messageIds) ? messageIds : [messageIds]\n        }),\n      label: (messageId, label) =>\n        __need(\"add_label_to_email\")({ message_id: messageId, label: label })\n    },\n\n    assets: {\n      list: (opts) => __need(\"list_assets\")(__merge(opts)),\n      /** Image assets as lightweight handles \u2014 feed an id to view_image. */\n      images: (opts) => __need(\"list_images\")(__merge(opts)),\n      search: (query, opts) =>\n        __need(\"asset_search\")(__merge(opts, { query: query })),\n      get: (id) => __need(\"get_asset\")({ asset_id: id }),\n      save: (name, opts) => __need(\"save_asset\")(__merge(opts, { name: name })),\n      read: (name, opts) => __need(\"read_asset\")(__merge(opts, { name: name }))\n    },\n\n    jobs: {\n      list: (opts) => __need(\"list_jobs\")(__merge(opts)),\n      /** The job row, including the run's outputs once it has settled. */\n      get: (id) => __need(\"get_job\")({ job_id: __jobId(id, \"get\") }),\n      logs: (id, opts) =>\n        __need(\"get_job_logs\")(__merge(opts, { job_id: __jobId(id, \"logs\") })),\n      /**\n       * Poll a background job until it settles, then return the job record.\n       * Terminal statuses are completed / failed / cancelled / error (the\n       * jobs API's own terminal set). Throws after timeoutMs, naming the job\n       * and the last status seen.\n       */\n      async wait(id, opts) {\n        const jobId = __jobId(id, \"wait\");\n        const pollMs = Math.max(1000, (opts && opts.pollMs) || 3000);\n        const timeoutMs = (opts && opts.timeoutMs) || 600000;\n        const terminal = [\"completed\", \"failed\", \"cancelled\", \"error\"];\n        const deadline = Date.now() + timeoutMs;\n        let status = \"unknown\";\n        for (;;) {\n          const job = await api.jobs.get(jobId);\n          status = (job && (job.status || job.state)) || \"unknown\";\n          if (terminal.indexOf(status) >= 0) return job;\n          if (Date.now() >= deadline) {\n            throw new Error(\n              \"nodetool.jobs.wait: job \" + jobId + \" did not finish within \" +\n              timeoutMs + \"ms (last status: \" + status + \"). Poll it with \" +\n              \"nodetool.jobs.get(id) or read nodetool.jobs.logs(id).\"\n            );\n          }\n          await sleep(pollMs);\n        }\n      }\n    },\n\n    runs: {\n      list: (opts) => __need(\"list_runs\")(__merge(opts)),\n      get: (id, opts) => __need(\"get_run\")(__merge(opts, { run_id: id })),\n      trace: (id, opts) => __need(\"get_run_trace\")(__merge(opts, { run_id: id })),\n      logs: (id, opts) => __need(\"get_run_logs\")(__merge(opts, { run_id: id })),\n      wait: (id, opts) => __need(\"await_run\")(__merge(opts, { run_id: id }))\n    },\n\n    generations: {\n      /** The record of every media generation: status, cost, assets. */\n      list: (opts) => __need(\"list_generations\")(__merge(opts)),\n      get: (id) =>\n        __need(\"get_generation\")({ generation_id: __generationId(id, \"get\") }),\n      /**\n       * Wait for a generation started with background: true to settle and\n       * return its record \u2014 cost and asset ids included.\n       */\n      wait: (id, opts) =>\n        __need(\"await_generation\")(\n          __merge(opts, { generation_id: __generationId(id, \"wait\") })\n        ),\n      cancel: (id) =>\n        __need(\"cancel_generation\")({\n          generation_id: __generationId(id, \"cancel\")\n        }),\n      /** Ask the provider what it billed, by request id, and update the row. */\n      reconcile: (id) =>\n        __need(\"reconcile_generation\")({\n          generation_id: __generationId(id, \"reconcile\")\n        }),\n      /**\n       * The provider's own record instead of this installation's: what it ran\n       * from any machine, at the price it billed. Not every provider keeps one.\n       */\n      fromProvider: (provider, opts) =>\n        __need(\"list_provider_generations\")(__merge(opts, { provider: provider })),\n      /** One provider-side generation by the provider's own request id. */\n      getFromProvider: (provider, requestId, opts) =>\n        __need(\"get_provider_generation\")(\n          __merge(opts, { provider: provider, request_id: requestId })\n        )\n    },\n\n    collections: {\n      list: () => __need(\"list_collections\")({}),\n      query: (collection, query, opts) =>\n        __need(\"query_collection\")(\n          __merge(opts, { collection: collection, query: query })\n        ),\n      /** Index one chunk under a source id (re-indexing the same id updates it). */\n      index: (text, sourceId, opts) =>\n        __need(\"vector_index\")(\n          __merge(opts, { text: text, source_id: sourceId })\n        ),\n      /** Index many at once: [{text, source_id, metadata?}, ...]. */\n      indexBatch: (chunks, opts) =>\n        __need(\"vector_batch_index\")(__merge(opts, { chunks: chunks })),\n      /** Semantic search over the indexed chunks. */\n      search: (text, opts) =>\n        __need(\"vector_text_search\")(__merge(opts, { text: text })),\n      /** Semantic + keyword search fused by reciprocal rank. */\n      hybridSearch: (text, opts) =>\n        __need(\"vector_hybrid_search\")(__merge(opts, { text: text }))\n    },\n\n    apps: {\n      list: (opts) => __need(\"list_apps\")(__merge(opts)),\n      get: (id) => __need(\"get_app\")({ application_id: id }),\n      /** Create an empty app and get its id back. */\n      create: (name, opts) =>\n        __need(\"create_app\")(__named(name, opts, \"apps.create\")),\n      /** Apply App Builder steps to a saved app, then save it. */\n      edit: (id, steps, opts) =>\n        __need(\"edit_app\")(\n          __merge(opts, { application_id: id, steps: steps })\n        ),\n      /** Validate + simulate a saved app. {run: false} is the free check. */\n      debug: (id, opts) =>\n        __need(\"debug_app\")(__merge(opts, { application_id: id }))\n    },\n\n    games: {\n      create: (name, opts) =>\n        __need(\"create_native_game\")(__named(name, opts, \"games.create\")),\n      get: (id, opts) => __need(\"get_native_game\")(__merge(opts, { game_id: id })),\n      edit: (id, ops, opts) => __need(\"edit_native_game\")(__merge(opts, { game_id: id, ops })),\n      setDocument: (id, document, opts) =>\n        __need(\"edit_native_game\")(__merge(opts, { game_id: id, ops: [{ op: \"set_document\", document }] })),\n      previewAuthoring: (id, opts) => __need(\"preview_native_game_authoring\")(__merge(opts, { game_id: id })),\n      applyAuthoring: (id, candidate) => __need(\"apply_native_game_authoring\")({ game_id: id, candidate }),\n      publish: (id, opts) => __need(\"publish_native_game\")(__merge(opts, { game_id: id })),\n      installAsset: (id, slot, binding, opts) =>\n        __need(\"install_native_game_asset\")(__merge(opts, { game_id: id, slot, binding })),\n      playtest: (id, opts) => __need(\"playtest_native_game\")(__merge(opts, { game_id: id })),\n      capture: (id, opts) => __need(\"capture_native_game_frame\")(__merge(opts, { game_id: id })),\n      generateAsset: (id, slot, kind, prompt, opts) =>\n        __need(\"generate_game_asset\")(__merge(opts, { game_id: id, slot, kind, prompt })),\n      build: (id, opts) => __need(\"build_native_game\")(__merge(opts, { game_id: id })),\n      listExamples: (opts) => __need(\"list_example_games\")(__merge(opts)),\n      getExample: (slug) => __need(\"get_example_game\")({ slug }),\n      installExample: (slug, opts) => __need(\"install_example_game\")(__merge(opts, { slug })),\n      autoplay: (id, opts) => __need(\"autoplay_native_game\")(__merge(opts, { game_id: id }))\n    },\n\n    timelines: {\n      list: (opts) => __need(\"list_timelines\")(__merge(opts)),\n      examples: {\n        list: (opts) => __need(\"list_example_timelines\")(__merge(opts)),\n        get: (slug, opts) =>\n          __need(\"get_example_timeline\")(__merge(opts, { slug: slug })),\n        source: (slug) =>\n          __need(\"get_example_timeline_source\")({ slug: slug })\n      },\n      create: (name, opts) =>\n        __need(\"create_timeline\")(__named(name, opts, \"timelines.create\")),\n      get: (id) => __need(\"get_timeline\")({ timeline_id: id }),\n      versions: (id, opts) =>\n        __need(\"list_timeline_versions\")(__merge(opts, { timeline_id: id })),\n      getVersion: (id, version) =>\n        __need(\"get_timeline_version\")({ timeline_id: id, version: version }),\n      /** Save the current state as a version. Options: {name}. */\n      snapshot: (id, opts) =>\n        __need(\"create_timeline_version\")(__merge(opts, { timeline_id: id })),\n      /** Alias of snapshot(), named after the create_timeline_version tool. */\n      createVersion: (id, opts) =>\n        __need(\"create_timeline_version\")(__merge(opts, { timeline_id: id })),\n      restore: (id, version) =>\n        __need(\"restore_timeline_version\")({\n          timeline_id: id,\n          version: version\n        }),\n      deleteVersion: (id, version) =>\n        __need(\"delete_timeline_version\")({\n          timeline_id: id,\n          version: version\n        }),\n      /** Options: {fps, width, height, tier, normalize}. normalize:true preflights authoring defaults for an inline document. */\n      validate: (target, opts) =>\n        typeof target === \"string\"\n          ? __need(\"validate_timeline\")(__merge(opts, { timeline_id: target }))\n          : __need(\"validate_timeline\")(__merge(opts, { document: target })),\n      /**\n       * Composited frames at chosen timecodes \u2014 the finished picture, with\n       * every track layered, animations sampled mid-flight and transitions\n       * part way through. Takes an id or an inline document, like validate().\n       * Options: {times_ms, count, width}.\n       */\n      preview: (target, opts) =>\n        typeof target === \"string\"\n          ? __need(\"preview_timeline_frame\")(\n              __merge(opts, { timeline_id: target })\n            )\n          : __need(\"preview_timeline_frame\")(\n              __merge(opts, { document: target })\n            ),\n      /**\n       * Per-frame pixel difference between two timelines, plus a side-by-side\n       * sheet. Each side is an id, {timeline_id, version} or a document.\n       * Options: {times_ms, range, width}.\n       */\n      compare: (a, b, opts) =>\n        __need(\"compare_timeline_frames\")(__merge(opts, { a: a, b: b })),\n      /** Apply document edits to a saved sequence, server-side. */\n      edit: (id, ops) => __need(\"edit_timeline\")({ timeline_id: id, ops: ops }),\n      /**\n       * Write a whole document at once. The document replaces the stored one,\n       * so send back what get() returned, changed. Validated before anything\n       * is written and snapshotted first, so a bad document is refused and a\n       * good one is undoable. Options: {fps, width, height,\n       * expected_updated_at, snapshot_name}.\n       *\n       * Bookkeeping you leave out is filled in rather than refused: a track's\n       * index (its position in the array), visible: true and locked: false; a\n       * clip's sourceType (generated when it names a prompt, workflow or\n       * binding, else imported), status \"generated\", locked: false and\n       * versions: []; animation ids (anim_1, anim_2, \u2026), clip and track\n       * effect ids (effect_1, effect_2, \u2026) and enabled: true; missing clip\n       * tracks inferred from mediaType; and markers: [].\n       * Anything you do send is kept as sent. fps/width/height on the document\n       * itself are read as the sequence's settings when the options omit them.\n       */\n      setDocument: (id, document, opts) =>\n        __need(\"set_timeline_document\")(\n          __merge(opts, { timeline_id: id, document: document })\n        ),\n      /**\n       * Drive a clip's motion from a piece of audio: measure the audio clip\n       * (id, name, or \"selected\") and write the result as keyframes onto\n       * targetClipId's own property, additive with anything hand-keyframed\n       * there. Options: {mode: \"envelope\"|\"beats\", output_range: [quiet,\n       * loud], sensitivity, attack_ms, release_ms, offset_ms, tolerance,\n       * max_points, frame_ms, max_seconds, replace}. property and\n       * output_range are required.\n       */\n      bakeAudioAnimation: (id, audioClipId, targetClipId, opts) =>\n        __need(\"bake_audio_animation\")(\n          __merge(opts, {\n            timeline_id: id,\n            audio_clip_id: audioClipId,\n            target_clip_id: targetClipId\n          })\n        ),\n      /**\n       * Render the finished cut as a job. Returns {job_id} immediately;\n       * {wait: true} blocks and returns the rendered asset. Options:\n       * {format, alpha, video_codec, bitrate, motion_blur_samples,\n       * shutter_angle, preview_scale, include_audio, wait, timeout_ms}.\n       */\n      render: (id, opts) =>\n        __need(\"render_timeline\")(__merge(opts, { timeline_id: id })),\n      /**\n       * Reusable templates \u2014 a group of clips with named parameters. The ones\n       * NodeTool ships and the ones this user saved, both listed by list().\n       * Insert one with edit(id, [{op: \"insert_composition\", composition_id,\n       * startMs, params}]).\n       */\n      compositions: {\n        /** Options: {source: \"shipped\" | \"user\", query, limit}. */\n        list: (opts) => __need(\"list_compositions\")(__merge(opts)),\n        get: (id) => __need(\"get_composition\")({ composition_id: id }),\n        /**\n         * Save a group on a timeline as a template. params names what varies:\n         * {\"<name>\": {type, default, path}}.\n         */\n        save: (timelineId, groupTarget, name, params, opts) =>\n          __need(\"save_composition\")(\n            __merge(opts, {\n              timeline_id: timelineId,\n              group_target: groupTarget,\n              name: name,\n              params: params\n            })\n          ),\n        remove: (id) => __need(\"delete_composition\")({ composition_id: id })\n      },\n      /**\n       * A timeline's authoring code \u2014 edit the script, not the JSON. `set`\n       * bakes `code` and merges the result into the document scene by\n       * scene: an untouched scene is replaced, a hand-edited one is kept and\n       * reported in `conflicts` unless `opts.force` overwrites it (`true`\n       * for every scene, or an array of scene names). `edit` applies\n       * exact-match string replacements to the stored code first (each\n       * `old` must match exactly once), then bakes and merges the same way.\n       * `rebake` reruns the stored code unchanged. `detach(id, names |\n       * \"all\")` stops tracking scenes \u2014 a later rebake never touches them\n       * again.\n       */\n      code: {\n        /** `{code, baked_at, scenes: [{name, group_id, edited}]}`. `code`\n         * is null when the timeline carries none. */\n        get: (id) => __need(\"get_timeline_code\")({ timeline_id: id }),\n        set: (id, code, opts) =>\n          __need(\"set_timeline_code\")(\n            __merge(opts, { timeline_id: id, code: code })\n          ),\n        edit: (id, edits, opts) =>\n          __need(\"edit_timeline_code\")(\n            __merge(opts, { timeline_id: id, edits: edits })\n          ),\n        rebake: (id, opts) =>\n          __need(\"rebake_timeline_code\")(__merge(opts, { timeline_id: id })),\n        detach: (id, scenes) =>\n          __need(\"detach_timeline_code\")({ timeline_id: id, scenes: scenes })\n      }\n    },\n\n    sketches: {\n      list: (opts) => __need(\"list_sketches\")(__merge(opts)),\n      /** Create a blank sketch. Pass {width, height} for the canvas size. */\n      create: (name, opts) =>\n        __need(\"create_sketch\")(__named(name, opts, \"sketches.create\")),\n      get: (id) => __need(\"get_sketch\")({ image_document_id: id }),\n      versions: (id, opts) =>\n        __need(\"list_sketch_versions\")(\n          __merge(opts, { image_document_id: id })\n        ),\n      getVersion: (id, version) =>\n        __need(\"get_sketch_version\")({\n          image_document_id: id,\n          version: version\n        }),\n      snapshot: (id, opts) =>\n        __need(\"create_sketch_version\")(\n          __merge(opts, { image_document_id: id })\n        ),\n      restore: (id, version) =>\n        __need(\"restore_sketch_version\")({\n          image_document_id: id,\n          version: version\n        }),\n      deleteVersion: (id, version) =>\n        __need(\"delete_sketch_version\")({\n          image_document_id: id,\n          version: version\n        }),\n      validate: (target) =>\n        typeof target === \"string\"\n          ? __need(\"validate_sketch\")({ image_document_id: target })\n          : __need(\"validate_sketch\")({ document: target }),\n      /** Apply layer-structure edits to a saved sketch, server-side. */\n      edit: (id, ops) =>\n        __need(\"edit_sketch\")({ image_document_id: id, ops: ops })\n    },\n\n    scripts: {\n      list: (opts) => __need(\"list_scripts\")(__merge(opts)),\n      /** Create an empty script. Pass {project_id} to place it. */\n      create: (name, opts) =>\n        __need(\"create_script\")(__named(name, opts, \"scripts.create\")),\n      get: (id) => __need(\"get_script\")({ script_id: id }),\n      voice: (id, opts) =>\n        __need(\"voice_script_lines\")(__merge(opts, { script_id: id })),\n      finish: (args) => __need(\"finish_storyboard\")(args),\n      previewDesign: (args) => __need(\"preview_storyboard_design\")(args),\n      assembleTimeline: (id, opts) =>\n        __need(\"assemble_script_timeline\")(__merge(opts, { script_id: id })),\n      /** Apply cast/line edits to a saved script, server-side. */\n      edit: (id, ops) => __need(\"edit_script\")({ script_id: id, ops: ops })\n    },\n\n    storyboards: {\n      list: (opts) => __need(\"list_storyboards\")(__merge(opts)),\n      /** Create a blank storyboard. Pass {brief, style, aspect_ratio} for board settings. */\n      create: (name, opts) =>\n        __need(\"create_storyboard\")(__named(name, opts, \"storyboards.create\")),\n      get: (id) => __need(\"get_storyboard\")({ storyboard_id: id }),\n      renderStills: (id, opts) =>\n        __need(\"render_storyboard_stills\")(\n          __merge(opts, { storyboard_id: id })\n        ),\n      renderClips: (id, opts) =>\n        __need(\"render_storyboard_clips\")(__merge(opts, { storyboard_id: id })),\n      reviseClip: (id, target, instruction, opts) =>\n        __need(\"revise_storyboard_clip\")(\n          __merge(opts, {\n            storyboard_id: id,\n            target: target,\n            instruction: instruction\n          })\n        ),\n      finish: (args) => __need(\"finish_storyboard\")(args),\n      previewDesign: (args) => __need(\"preview_storyboard_design\")(args),\n      assembleTimeline: (id, opts) =>\n        __need(\"assemble_storyboard_timeline\")(\n          __merge(opts, { storyboard_id: id })\n        ),\n      /** Apply shot-list edits to a saved board, server-side. */\n      edit: (id, ops) => __need(\"edit_storyboard\")({ storyboard_id: id, ops: ops })\n    }\n  };\n\n  /**\n   * Guest globals a caller reaches for under `nodetool.` \u2014 the namespaces that\n   * live at the top level of the sandbox rather than on the object model. Each\n   * value is the one sentence that sends the caller to the right place.\n   */\n  const __GUEST_GLOBALS = {\n    image: \"Probing and editing pixels is `image.*`; generating a picture is `nodetool.media.generateImage`.\",\n    audio: \"Sample-level work is `audio.*`; generating speech or music is `nodetool.media.generateSpeech`/`generateMusic`.\",\n    video: \"Frame and container work is `video.*`; generating a clip is `nodetool.media.generateVideo`, and probing or encoding a file with a host binary is `nodetool.media.ffprobe`/`ffmpeg`.\",\n    canvas: \"Drawing is `canvas.*`.\",\n    media: \"The bare `media.*` global holds byte helpers; the tools are `nodetool.media.*`.\",\n    format: \"Text and table formatting is `format.*`.\",\n    workspace: \"Run files are `workspace.*`; the library is `nodetool.assets.*`.\",\n    fetch: \"The network is the `fetch` global, or `nodetool.web.fetch`.\"\n  };\n\n  /**\n   * What a member that does not exist answers with: callable, and a namespace\n   * all the way down, so `nodetool.script.list()` reports the typo in\n   * `script` rather than bottoming out one hop later as\n   * `TypeError: not a function` \u2014 the message the whole guard exists to\n   * replace.\n   */\n  const __missing = (message) =>\n    new Proxy(function () {}, {\n      apply() {\n        throw new Error(message);\n      },\n      get(target, prop) {\n        if (typeof prop !== \"string\" || prop === \"then\") return target[prop];\n        return __missing(message);\n      }\n    });\n\n  /**\n   * The nearest member name to one that does not exist, comparing on letters\n   * and digits alone: `find_model` finds `find`, `assemble_timeline` finds\n   * `assembleTimeline`, `create_script` finds `create`.\n   */\n  const __nearest = (prop, names) => {\n    const flatten = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, \"\");\n    const want = flatten(prop);\n    let best = null;\n    for (const name of names) {\n      const have = flatten(name);\n      if (have === want) return name;\n      if (have.length === 0) continue;\n      const near = want.indexOf(have) === 0 || have.indexOf(want) === 0;\n      if (near && (best === null || have.length > flatten(best).length)) {\n        best = name;\n      }\n    }\n    return best;\n  };\n\n  /**\n   * Every namespace is guarded, so a member that does not exist answers with\n   * its own name instead of QuickJS's `TypeError: not a function`.\n   *\n   * The name a capability has on the belt is not the name it has here \u2014 the\n   * object model curates: `find_model` is `nodetool.models.find`,\n   * `create_script` is `nodetool.scripts.create`. A caller reaching for the\n   * belt spelling got a message that named neither the call it made nor the\n   * one it meant, and a bare `TypeError` reads like the sandbox is broken\n   * rather than like a typo: one chat took it as \"models are unavailable here\"\n   * and abandoned the namespace. An unknown member answers with a thrower\n   * rather than `undefined` \u2014 the shape `tools.<name>` already uses \u2014 so the\n   * report lands at the call, where the mistake is, and reads the same whether\n   * the missing half is the method or the namespace.\n   */\n  const __guard = (path, obj) =>\n    new Proxy(obj, {\n      get(target, prop) {\n        // Symbols, everything that really is there, and the handful of names\n        // the language itself reaches for pass straight through: `then` so\n        // awaiting a namespace cannot mistake it for a thenable, `toJSON` and\n        // `inspect` so logging one still prints it instead of throwing.\n        if (\n          typeof prop !== \"string\" ||\n          prop === \"then\" ||\n          prop === \"toJSON\" ||\n          prop === \"inspect\" ||\n          prop in target\n        ) {\n          return target[prop];\n        }\n        const names = Object.keys(target).sort();\n        const nearest = __nearest(prop, names);\n        // A name that is a *global* here reads as a missing namespace: the\n        // pixel and sample ops are `image.*`/`audio.*`/`video.*`, not\n        // `nodetool.video.*`, and a chat that took the miss at face value\n        // gave up on the operation instead of dropping the prefix.\n        const global = path === \"nodetool\" ? __GUEST_GLOBALS[prop] : undefined;\n        return __missing(\n          path + \".\" + prop + \" does not exist\" +\n            (global\n              ? \". `\" + prop + \"` is a global in this sandbox \u2014 call `\" +\n                prop + \".*` with no `nodetool.` prefix. \" + global\n              : nearest\n                ? \". Did you mean \" + path + \".\" + nearest + \"?\"\n                : \".\") +\n            \" \" + path + \" has: \" + names.join(\", \") + \".\" +\n            (path === \"nodetool\"\n              ? \"\"\n              : ' nodetool.searchTools(\"' + prop + '\") finds the tool ' +\n                \"behind a name if it is one.\")\n        );\n      }\n    });\n\n  for (const key of Object.keys(api)) {\n    const value = api[key];\n    if (value && typeof value === \"object\") {\n      api[key] = __guard(\"nodetool.\" + key, value);\n    }\n  }\n  return __guard(\"nodetool\", api);\n})();\n";
+/** The full prelude: namespace map, graph normalizer, API definition. */
+export declare const NODETOOL_API_PRELUDE_FULL: string;
+/** Guest names {@link NODETOOL_API_PRELUDE_FULL} defines. */
+export declare const NODETOOL_API_GLOBALS: readonly ["nodetool", "__NT_NAMESPACE_TOOLS", "__graphJsonOf"];
+/**
+ * Heading of the prompt section {@link buildNodetoolApiPromptSection} renders.
+ * `buildCodeActSystemPrompt` keys on it to know the `nodetool` object model is
+ * loaded — and then documents `nodetool.batch` as THE fan-out primitive
+ * instead of the bare-sandbox `parallelMap` helper.
+ */
+export declare const NODETOOL_API_SECTION_HEADER = "# The `nodetool` object model";
+interface NodetoolApiPromptOptions {
+    /**
+     * Whether this session can author graphs with `@nodetool-ai/sandbox-dsl` —
+     * the belt carries the three workflow verbs AND the pack is installed. The
+     * caller decides it (`withGraphDslPackage`), because only the caller knows
+     * the allowlist and the catalog.
+     */
+    graphDsl?: boolean;
+    /**
+     * Whether this session can call nodes directly with
+     * `@nodetool-ai/sandbox-flow` — the pack is installed and on the
+     * allowlist. The caller decides it (`withFlowPackage`).
+     */
+    nativeFlow?: boolean;
+}
+export declare function buildNodetoolApiPromptSection(toolNames: Iterable<string>, options?: NodetoolApiPromptOptions): string;
+export {};
+//# sourceMappingURL=nodetool-api.d.ts.map

package/dist/codeact/nodetool-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodetool-api.d.ts","sourceRoot":"","sources":["../../src/codeact/nodetool-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,uEAAuE;AACvE,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA8K1E,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAMxE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC1B,GAAG,CAAC,MAAM,CAAC,CASb;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,ok2DA02ChC,CAAC;AAOF,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,QAA+E,CAAC;AAEtH,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,YAC/B,UAAU,EACV,sBAAsB,EACtB,eAAe,CACP,CAAC;AA8QX;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,kCAAkC,CAAC;AAE3E,UAAU,wBAAwB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAqDD,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC3B,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAsDR"}