@lamplitisles/dsh-nanocodex 0.1.0-beta.0

package/vendor/nanocodex-tools/tools/standard.mjs

@@ -0,0 +1,458 @@
+import { IMAGE_DESCRIPTION, WEB_DESCRIPTION } from "./standardDescriptions.mjs";
+import { namedTool } from "./namedTool.mjs";
+import { toolResult } from "../runtime/code-runtime.mjs";
+
+export { namedTool };
+
+const MAX_VIEW_IMAGE_BYTES = 10 * 1024 * 1024;
+const DEFAULT_WEB_URL = "/api/tools/web-search";
+const DEFAULT_IMAGE_URL = "/api/tools/image-generation";
+
+export function web(options = {}) {
+  const request = jsonRequester(options, DEFAULT_WEB_URL);
+  return namedTool("web__run", {
+    supportsParallelToolCalls: true,
+    description: WEB_DESCRIPTION,
+    parameters: webParameters,
+    outputSchema: { type: "string" },
+    async handler(input, context) {
+      const commands = normalizeWebCommands(input);
+      const result = requireObject(await request({
+        commands,
+        session_id: context.sessionId,
+        model: context.model,
+      }, context.signal), "web__run response");
+      return requireString(result.output, "web__run response.output");
+    },
+  });
+}
+
+export function imageGeneration(options = {}) {
+  const request = jsonRequester(options, DEFAULT_IMAGE_URL);
+  const recentImages = options.recentImages ?? (() => []);
+  const rememberImage = options.rememberImage ?? (() => {});
+  return namedTool("image_gen__imagegen", {
+    description: IMAGE_DESCRIPTION,
+    parameters: {
+      type: "object",
+      properties: {
+        prompt: { type: "string" },
+        referenced_image_paths: {
+          type: ["array", "null"],
+          items: { type: "string" },
+          maxItems: 5,
+        },
+        num_last_images_to_include: {
+          type: ["integer", "null"],
+          minimum: 1,
+          maximum: 5,
+        },
+      },
+      required: ["prompt"],
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        image_url: { type: "string" },
+        output_hint: { type: "string" },
+      },
+      required: ["image_url"],
+      additionalProperties: true,
+    },
+    async handler(input, context) {
+      const args = requireObject(input, "image_gen__imagegen");
+      const prompt = requireString(args.prompt, "image_gen__imagegen.prompt");
+      const paths = optionalStringArray(args.referenced_image_paths);
+      const count = optionalInteger(args.num_last_images_to_include);
+      if (paths.length > 5) throw new Error("referenced_image_paths accepts at most 5 paths");
+      if (paths.length && count !== undefined) {
+        throw new Error("provide referenced_image_paths or num_last_images_to_include, not both");
+      }
+      if (count !== undefined && (count < 1 || count > 5)) {
+        throw new Error("num_last_images_to_include must be between 1 and 5");
+      }
+      const images = paths.length
+        ? await Promise.all(paths.map((path) => workspaceImage(options.workspace, path)))
+        : count === undefined ? [] : recentImages(context.sessionId, count);
+      if (count !== undefined && images.length !== count) {
+        throw new Error(`requested ${count} recent images, but only ${images.length} are available`);
+      }
+      const result = requireObject(
+        await request({ images, prompt }, context.signal),
+        "image_gen__imagegen response",
+      );
+      const imageUrl = requireString(result.image_url, "image_gen__imagegen response.image_url");
+      rememberImage(context.sessionId, imageUrl);
+      return result;
+    },
+  });
+}
+
+export function viewImage(options) {
+  return namedTool("view_image", {
+    supportsParallelToolCalls: true,
+    description: "View a local image file from the filesystem when visual inspection is needed. Use this for images already available on disk.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Local filesystem path to an image file." },
+        detail: { type: "string", enum: ["high", "original"], description: "Image detail level. Defaults to `high`; use `original` to preserve exact resolution." },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        image_url: { type: "string", description: "Data URL for the loaded image." },
+        detail: { type: "string", enum: ["high", "original"], description: "Image detail hint returned by view_image. Returns `high` for default resized behavior or `original` when original resolution is preserved." },
+      },
+      required: ["image_url", "detail"],
+      additionalProperties: false,
+    },
+    async handler(input) {
+      const args = requireObject(input, "view_image");
+      const path = requireString(args.path, "view_image.path");
+      const detail = args.detail === undefined ? "high" : args.detail;
+      if (detail !== "high" && detail !== "original") {
+        throw new Error("view_image.detail must be high or original");
+      }
+      const bytes = await options.workspace.readFile(path);
+      if (bytes.byteLength > MAX_VIEW_IMAGE_BYTES) {
+        throw new Error("view_image input exceeds 10 MiB");
+      }
+      const mimeType = imageMimeType(bytes);
+      if (!mimeType) throw new Error("view_image supports PNG, JPEG, GIF, and WebP files");
+      const result = { detail, image_url: `data:${mimeType};base64,${base64(bytes)}` };
+      return toolResult([{
+        type: "input_image",
+        image_url: result.image_url,
+        detail,
+      }], result, { value: result });
+    },
+  });
+}
+
+export function updatePlan() {
+  const plans = new Map();
+  return namedTool("update_plan", {
+    description: "Update the current task plan. At most one step may be in progress.",
+    parameters: {
+      type: "object",
+      properties: {
+        explanation: { type: "string" },
+        plan: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              step: { type: "string" },
+              status: { type: "string", enum: ["pending", "in_progress", "completed"] },
+            },
+            required: ["step", "status"],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ["plan"],
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: "object",
+      properties: { updated: { type: "boolean", const: true } },
+      required: ["updated"],
+      additionalProperties: false,
+    },
+    async handler(input, context) {
+      const value = requireObject(input, "update_plan");
+      if (!Array.isArray(value.plan)) throw new Error("update_plan.plan must be an array");
+      const active = value.plan.filter((item) =>
+        typeof item === "object" && item !== null && item.status === "in_progress"
+      );
+      if (active.length > 1) throw new Error("at most one plan step may be in_progress");
+      plans.set(context.sessionId, structuredClone(value));
+      return { updated: true };
+    },
+    releaseSession(sessionId) {
+      plans.delete(sessionId);
+    },
+    dispose() {
+      plans.clear();
+    },
+  });
+}
+
+function jsonRequester(options, defaultUrl) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("tool options must be an object");
+  }
+  const url = options.url ?? defaultUrl;
+  if (typeof url !== "string" && !(url instanceof URL)) {
+    throw new TypeError("tool url must be a string or URL");
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new TypeError("tool fetch must be a function");
+  const headers = Object.freeze({
+    "content-type": "application/json",
+    ...options.headers,
+  });
+  return async (body, signal) => {
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      // These adapters commonly carry caller-owned bearer credentials.
+      // Never let fetch forward them to a redirect target.
+      redirect: "manual",
+      signal,
+    });
+    if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+      throw new Error("tool endpoint redirects are not allowed");
+    }
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok) {
+      const message = typeof payload?.error === "string" ? payload.error : `HTTP ${response.status}`;
+      throw new Error(message);
+    }
+    return payload;
+  };
+}
+
+function normalizeWebCommands(input) {
+  const value = requireObject(input, "web__run");
+  const commands = Object.keys(value).length === 1 && value.commands !== undefined
+    ? requireObject(value.commands, "web__run.commands")
+    : value;
+  const normalized = { ...commands };
+  for (const operation of [
+    "search_query",
+    "image_query",
+    "open",
+    "click",
+    "find",
+    "finance",
+    "weather",
+    "sports",
+    "time",
+  ]) {
+    const command = normalized[operation];
+    if (command === undefined || Array.isArray(command)) continue;
+    if (typeof command === "object" && command !== null) {
+      normalized[operation] = [command];
+      continue;
+    }
+    if (typeof command === "string" && (operation === "search_query" || operation === "image_query")) {
+      normalized[operation] = [{ q: command }];
+      continue;
+    }
+    if (typeof command === "string" && operation === "open") {
+      normalized.open = [{ ref_id: command }];
+    }
+  }
+  const operationCount = [
+    "search_query",
+    "image_query",
+    "open",
+    "click",
+    "find",
+    "finance",
+    "weather",
+    "sports",
+    "time",
+  ].reduce((count, operation) => count + (Array.isArray(normalized[operation])
+    ? normalized[operation].length
+    : 0), 0);
+  if (!operationCount) throw new Error("web__run requires at least one operation");
+  const queryCount = Array.isArray(normalized.search_query) ? normalized.search_query.length : 0;
+  if (queryCount > 4) throw new Error("web__run accepts at most 4 search queries");
+  if (queryCount === 4 && normalized.response_length !== "medium" && normalized.response_length !== "long") {
+    throw new Error("web__run requires response_length medium or long for 4 search queries");
+  }
+  return normalized;
+}
+
+function requireObject(value, name) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${name} requires an object`);
+  }
+  return value;
+}
+
+function requireString(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} must be a non-empty string`);
+  return value;
+}
+
+function optionalInteger(value) {
+  if (value === undefined || value === null) return undefined;
+  if (!Number.isInteger(value)) throw new Error("num_last_images_to_include must be an integer");
+  return value;
+}
+
+function optionalStringArray(value) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim())) {
+    throw new Error("referenced_image_paths must be an array of non-empty strings");
+  }
+  return value;
+}
+
+async function workspaceImage(workspace, path) {
+  if (!workspace || typeof workspace.readFile !== "function") {
+    throw new Error("referenced_image_paths requires an image-generation workspace");
+  }
+  const bytes = await workspace.readFile(path);
+  if (bytes.byteLength > MAX_VIEW_IMAGE_BYTES) {
+    throw new Error(`${path} exceeds the 10 MiB image limit`);
+  }
+  const mimeType = imageMimeType(bytes);
+  if (!mimeType) throw new Error(`${path} is not a supported image`);
+  return `data:${mimeType};base64,${base64(bytes)}`;
+}
+
+function imageMimeType(bytes) {
+  if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return "image/png";
+  if (startsWith(bytes, [0xff, 0xd8, 0xff])) return "image/jpeg";
+  if (startsWith(bytes, [0x47, 0x49, 0x46, 0x38])) return "image/gif";
+  if (startsWith(bytes, [0x52, 0x49, 0x46, 0x46])
+    && startsWith(bytes.subarray(8), [0x57, 0x45, 0x42, 0x50])) return "image/webp";
+  return undefined;
+}
+
+function startsWith(bytes, signature) {
+  return signature.every((value, index) => bytes[index] === value);
+}
+
+function base64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 32_768) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 32_768));
+  }
+  return btoa(binary);
+}
+
+const query = {
+  description: "Search query with optional domain and recency filters.",
+  type: "object",
+  properties: {
+    q: { type: "string" },
+    recency: { type: "integer" },
+    domains: { type: "array", items: { type: "string" } },
+  },
+  required: ["q"],
+  additionalProperties: false,
+};
+
+const webParameters = {
+  type: "object",
+  properties: {
+    search_query: {
+      type: "array",
+      description: "Query the internet search engine for a given list of queries.",
+      maxItems: 4,
+      items: query,
+    },
+    image_query: {
+      type: "array",
+      description: "Query the image search engine for source pages and captions.",
+      items: query,
+    },
+    open: {
+      type: "array",
+      description: "Open pages by reference id or URL.",
+      items: {
+        type: "object",
+        properties: { ref_id: { type: "string" }, lineno: { type: "integer" } },
+        required: ["ref_id"],
+        additionalProperties: false,
+      },
+    },
+    click: {
+      type: "array",
+      description: "Open numbered links from previously opened pages.",
+      items: {
+        type: "object",
+        properties: { ref_id: { type: "string" }, id: { type: "integer" } },
+        required: ["ref_id", "id"],
+        additionalProperties: false,
+      },
+    },
+    find: {
+      type: "array",
+      description: "Find text patterns in pages.",
+      items: {
+        type: "object",
+        properties: { ref_id: { type: "string" }, pattern: { type: "string" } },
+        required: ["ref_id", "pattern"],
+        additionalProperties: false,
+      },
+    },
+    finance: {
+      type: "array",
+      description: "Look up prices for stock symbols and other assets.",
+      items: {
+        type: "object",
+        properties: {
+          ticker: { type: "string" },
+          type: { type: "string", enum: ["equity", "fund", "crypto", "index"] },
+          market: { type: "string" },
+        },
+        required: ["ticker", "type"],
+        additionalProperties: false,
+      },
+    },
+    weather: {
+      type: "array",
+      description: "Look up weather forecasts.",
+      items: {
+        type: "object",
+        properties: {
+          location: { type: "string" },
+          start: { type: "string" },
+          duration: { type: "integer" },
+        },
+        required: ["location"],
+        additionalProperties: false,
+      },
+    },
+    sports: {
+      type: "array",
+      description: "Look up sports schedules and standings.",
+      items: {
+        type: "object",
+        properties: {
+          fn: { type: "string", enum: ["schedule", "standings"] },
+          league: {
+            type: "string",
+            enum: ["nba", "wnba", "nfl", "nhl", "mlb", "epl", "ncaamb", "ncaawb", "ipl"],
+          },
+          team: { type: "string" },
+          opponent: { type: "string" },
+          date_from: { type: "string" },
+          date_to: { type: "string" },
+          num_games: { type: "integer" },
+          locale: { type: "string" },
+        },
+        required: ["fn", "league"],
+        additionalProperties: false,
+      },
+    },
+    time: {
+      type: "array",
+      description: "Get time for the given UTC offsets.",
+      items: {
+        type: "object",
+        properties: { utc_offset: { type: "string" } },
+        required: ["utc_offset"],
+        additionalProperties: false,
+      },
+    },
+    response_length: {
+      type: "string",
+      description: "Set the length of the returned response.",
+      enum: ["short", "medium", "long"],
+    },
+  },
+  additionalProperties: false,
+};

package/vendor/nanocodex-tools/tools/standardDescriptions.mjs

@@ -0,0 +1,3 @@
+// Generated from the canonical Rust tool descriptions. Keep the parity test green.
+export const WEB_DESCRIPTION = "Tool for accessing the internet.\n\n\n---\n\n## Examples of different commands available in this tool\n\nExamples of different commands available in this tool:\n* `search_query`: {\"search_query\": [{\"q\": \"What is the capital of France?\"}, {\"q\": \"What is the capital of belgium?\"}]}. Searches the internet for a given query (and optionally with a domain or recency filter)\n* `image_query`: {\"image_query\":[{\"q\": \"waterfalls\"}]}. Finds image-search source pages and captions; it does not return model-visible image bytes.\n* `open`: {\"open\": [{\"ref_id\": \"turn0search0\"}, {\"ref_id\": \"https://www.openai.com\", \"lineno\": 120}]}\n* `click`: {\"click\": [{\"ref_id\": \"turn0fetch3\", \"id\": 17}]}\n* `find`: {\"find\": [{\"ref_id\": \"turn0fetch3\", \"pattern\": \"Annie Case\"}]}\n* `finance`: {\"finance\":[{\"ticker\":\"AMD\",\"type\":\"equity\",\"market\":\"USA\"}]}, {\"finance\":[{\"ticker\":\"BTC\",\"type\":\"crypto\",\"market\":\"\"}]}\n* `weather`: {\"weather\":[{\"location\":\"San Francisco, CA\"}]}\n* `sports`: {\"sports\":[{\"fn\":\"standings\",\"league\":\"nfl\"}, {\"fn\":\"schedule\",\"league\":\"nba\",\"team\":\"GSW\",\"date_from\":\"2025-02-24\"}]}\n* `time`: {\"time\":[{\"utc_offset\":\"+03:00\"}]}\n\n---\n\n## Usage hints\nTo use this tool efficiently:\n* Use multiple commands and queries in one call to get more results faster; e.g. {\"search_query\": [{\"q\": \"bitcoin news\"}], \"finance\":[{\"ticker\":\"BTC\",\"type\":\"crypto\",\"market\":\"\"}], \"find\": [{\"ref_id\": \"turn0search0\", \"pattern\": \"Annie Case\"}, {\"ref_id\": \"turn0search1\", \"pattern\": \"John Smith\"}]}\n* Use \"response_length\" to control the amount of returned text, and omit it for the service default.\n* Only write required parameters; do not write empty lists or nulls where they could be omitted.\n* `search_query` must have length at most 4 in each call. If it has length > 3, response_length must be medium or long\n* If you find yourself in a situation where you accidentally call the `web.run` tool, it's best just to send an empty query: {\"search_query\": [{\"q\": \"\"}]}.\n\n---\n\n## Decision boundary\n\nIf the user makes an explicit request to search the internet, find latest information, look up, etc (or to not do so), you must obey their request.\nWhen you make an assumption, always consider whether it is temporally stable; i.e. whether there's even a small (>10%) chance it has changed. If it is unstable, you must verify with browsing the internet for verification.\n\n<situations_where_you_must_browse_the_internet>\nBelow is a list of scenarios where browsing the internet MUST be used. PAY CLOSE ATTENTION: you MUST browse the internet in these cases. If you're unsure or on the fence, you MUST bias towards browsing the internet.\n- The information could have changed recently: for example news; prices; laws; schedules; product specs; sports scores; economic indicators; political/public/company figures (e.g. the question relates to 'the president of country A' or 'the CEO of company B', which might change over time); rules; regulations; standards; software libraries that could be updated; exchange rates; recommendations (i.e., recommendations about various topics or things might be informed by what currently exists / is popular / is safe / is unsafe / is in the zeitgeist / etc.); and many many many more categories -- again, if you're on the fence, you MUST browse the internet!\n  - For news queries, prioritize more recent events, ensuring you compare publish dates and the date that the event happened.\n- The user is seeking recommendations that could lead them to spend substantial time or money -- researching products, restaurants, travel plans, etc.\n- The user wants (or would benefit from) direct quotes, links, or precise source attribution.\n- A specific page, paper, dataset, PDF, or site is referenced and you haven't been given its contents.\n- You're unsure about a fact, the topic is niche or emerging, or you suspect there's at least a 10% chance you will incorrectly recall it\n- High-stakes accuracy matters (medical, legal, financial guidance). For these you generally should search by default because this information is highly temporally unstable\n- The user explicitly says to search, browse, verify, or look it up.\n</situations_where_you_must_browse_the_internet>\n\n---\n\n## Citations\n\nResults from `web.run` include internal reference IDs such as `turn2search5`. Use\nthose reference IDs only in calls to `web.run`; do not expose them in the final\nresponse.\n\nCite sources in the final response using Markdown links:\n\n- Cite a single source as `[descriptive source title](https://example.com/page)`.\n- Cite multiple sources with separate Markdown links, for example\n  `[first source](https://example.com/one), [second source](https://example.com/two)`.\n- Link directly to the page that supports the claim. Do not link to search result\n  pages or use bare URLs.\n\nFormatting of citations:\n\n- Place each citation as near as possible to the claim it supports, normally at\n  the end of the sentence or paragraph and after punctuation.\n- Do not place citations inside code fences.\n- Do not put citations on a line by themselves or collect all citations at the\n  end of the response.\n\nIf you browse the internet, cite statements supported by web sources. Each cited\nsource must directly support the associated claim. Prefer primary and\nauthoritative sources, and use sources from different domains when the response\nbenefits from multiple perspectives.\n\n---\n\n## Special cases\nIf these conflict with any other instructions, these should take precedence.\n\n<special_cases>\n- When the user asks for information about how to use OpenAI products, (ChatGPT, the OpenAI API, etc.), you should check the code in local env and only browse as fallback, when you browse restrict your sources to official OpenAI websites using the domains filter, unless otherwise requested.\n- When using search to answer technical questions, you must only rely on primary sources (research papers, official documentation, etc.)\n- Clearly indicate when you are making an inference from sources.\n</special_cases>\n\n---\n\n## Word limits\nResponses may not excessively quote or draw on a specific source. There are several limits here:\n- **Limit on verbatim quotes:**\n  - You may not quote more than 25 words verbatim from any single non-lyrical source, unless the source is reddit.\n  - For song lyrics, verbatim quotes must be limited to at most 10 words.\n  - Long quotes from reddit are allowed, as long as you indicate that those are direct quotes via a markdown blockquote starting with \">\", copy verbatim, and link the source.\n- **Word limits:**\n  - Each webpage source in the sources has a word limit label formatted like \"[wordlim N]\", in which N is the maximum number of words in the whole response that are attributed to that source. If omitted, the word limit is 200 words.\n  - Non-contiguous words derived from a given source must be counted to the word limit.\n  - The summarization limit N is a maximum for each source.\n  - When using multiple sources, their summarization limits add together. However, each article used must be relevant to the response.\n- **Copyright compliance:**\n  - You must avoid providing full articles, long verbatim passages, or extensive direct quotes due to copyright concerns.\n  - If the user asked for a verbatim quote, the response should provide a short compliant excerpt and then answer with paraphrases and summaries.\n  - Again, this limit does not apply to reddit content, as long as it's appropriately indicated that those are direct quotes and you link to the source.";
+export const IMAGE_DESCRIPTION = "The `image_gen.imagegen` tool enables image generation from descriptions and editing of existing images based on specific instructions. Use it when:\n\n- The user requests an image based on a scene description, such as a diagram, portrait, comic, meme, or any other visual.\n- The user wants to modify an attached or previously generated image with specific changes, including adding or removing elements, altering colors, improving quality/resolution, or transforming the style (e.g., cartoon, oil painting).\n\nGuidelines:\n- imagegen needs a few minutes to finish. In code-mode, use the first-line @exec directive to give the initial call 120 seconds and the same yield for any waits that follow. Once it finishes, return the image with generatedImage(result).\n- Omit both `referenced_image_paths` and `num_last_images_to_include` when generating a brand new image.\n- For edits, use `referenced_image_paths` when every target image has a local file path.\n- If you have not seen a local image yet, use `view_image` to inspect it before editing.\n- Use `num_last_images_to_include` only when at least one target image has no local file path.\n- Set `num_last_images_to_include` to the smallest number of recent conversation images that includes every target image, up to 5.\n- Never provide both `referenced_image_paths` and `num_last_images_to_include`.\n- If neither mechanism can include every target image, ask the user to attach the missing images again.\n- Directly generate the image without reconfirmation or clarification unless required images must be attached again.\n- Always use this tool for image editing unless the user explicitly requests otherwise. Do not use the `python` tool for image editing unless specifically instructed.";

package/vendor/nanocodex-tools/tools/types.d.mts

@@ -0,0 +1,83 @@
+export type SubagentToolContext = Readonly<{
+  agentId: string;
+  parentAgentId: string | null;
+  sessionId: string;
+  role: string;
+  task: string;
+}>;
+
+export type ToolContext = Readonly<{
+  callId: string;
+  parentCallId: string;
+  sessionId: string;
+  model: string;
+  signal: AbortSignal;
+  subagent?: SubagentToolContext | undefined;
+}>;
+
+/** JSON Schema or other provider-owned JSON metadata used by a tool definition. */
+export type ToolJson = Readonly<Record<string, unknown>>;
+
+/** Grammar format for a Responses free-form custom tool. */
+export type CustomToolFormat = Readonly<{
+  type: "grammar";
+  syntax: string;
+  definition: string;
+}>;
+
+/** Exact function or grammar-constrained custom definition sent to the model. */
+export type ToolDefinition =
+  | Readonly<{
+    type: "function";
+    /** The router replaces this with the containing map or named-tool name. */
+    name?: string | undefined;
+    description: string;
+    strict: boolean;
+    defer_loading?: boolean | undefined;
+    async?: boolean | undefined;
+    parameters: ToolJson;
+    output_schema?: ToolJson | undefined;
+  }>
+  | Readonly<{
+    type: "custom";
+    /** The router replaces this with the containing map or named-tool name. */
+    name?: string | undefined;
+    description: string;
+    defer_loading?: boolean | undefined;
+    async?: boolean | undefined;
+    format: CustomToolFormat;
+  }>;
+
+export type Tool = Readonly<{
+  description: string;
+  supportsParallelToolCalls?: boolean | undefined;
+  parameters?: Record<string, unknown> | undefined;
+  outputSchema?: Record<string, unknown> | undefined;
+  /** Optional provider-native definition; its name is canonicalized by the router. */
+  definition?: ToolDefinition | undefined;
+  handler(input: unknown, context: ToolContext): unknown | Promise<unknown>;
+  releaseSession?(sessionId: string): void;
+  dispose?(): void | Promise<void>;
+}>;
+
+export type NamedTool = Tool & Readonly<{ name: string }>;
+export type ToolMap = Record<string, Tool>;
+
+export type WorkspaceEntry = Readonly<{
+  kind: "directory" | "file";
+  modifiedAt?: number | undefined;
+  path: string;
+  size?: number | undefined;
+}>;
+
+export type Workspace = Readonly<{
+  root: string;
+  list(path?: string, options?: {
+    recursive?: boolean | undefined;
+    maxEntries?: number | undefined;
+  }): Promise<readonly WorkspaceEntry[]>;
+  readFile(path: string): Promise<Uint8Array>;
+  writeFile(path: string, contents: string | ArrayBuffer | ArrayBufferView): Promise<void>;
+  remove(path: string, options?: { recursive?: boolean | undefined }): Promise<void>;
+  mkdir(path: string): Promise<void>;
+}>;

package/vendor/nanocodex-tools/tools/workspace.d.mts

@@ -0,0 +1,25 @@
+import type { ToolMap, Workspace, WorkspaceEntry } from "./types.mjs";
+
+export type { Workspace, WorkspaceEntry } from "./types.mjs";
+
+export type WorkspaceBackend = {
+  list(path: string, options: { recursive: boolean; maxEntries: number }): Promise<readonly WorkspaceEntry[]>;
+  readFile(path: string): Promise<Uint8Array | ArrayBuffer | ArrayBufferView>;
+  writeFile(path: string, contents: Uint8Array): Promise<void>;
+  remove(path: string, options: { recursive: boolean }): Promise<void>;
+  mkdir(path: string): Promise<void>;
+};
+
+export function createWorkspace(options: {
+  backend: WorkspaceBackend;
+  root?: string | undefined;
+}): Workspace;
+
+export function tools(workspace: Workspace, options?: {
+  maxEntries?: number | undefined;
+  maxReadBytes?: number | undefined;
+  maxWriteBytes?: number | undefined;
+}): ToolMap;
+
+export function normalizeRelativePath(path: string): string;
+export function resolveWorkspacePath(root: string, path: string): string;