tarsk 0.6.87 → 0.6.88

package/dist/bundled-skills/tarsk-find/scripts/find.js

@@ -0,0 +1,78 @@
+/**
+ * find — formatting in the Skill; secure glob via context.fs (host).
+ */
+
+export const description =
+  "Find files by path glob (not file contents; use grep for text). Paths are relative to the search dir. Read the file directly when its path is known. `dir/{a,b}.tsx` is shallow — use `**/` for nested. Grouped as `dir/: file1, file2`. Truncated to 1000 results / 50KB.";
+
+export const parameters = {
+  type: "object",
+  required: ["pattern"],
+  properties: {
+    pattern: {
+      description: "Glob pattern, e.g. '*.ts' or '**/*.json'",
+      type: "string",
+    },
+    path: {
+      description: "Directory to search (default: current directory)",
+      type: "string",
+    },
+    limit: {
+      description: "Maximum results (default: 1000)",
+      type: "number",
+    },
+  },
+};
+
+/** @param {Record<string, unknown>} args @param {import("../../../../src/tools/agent-runtime/types.js").AgentRuntime} context @param {{ signal?: AbortSignal }} [options] */
+export async function execute(args, context, options) {
+  const pattern = String(args.pattern ?? "");
+  const searchDir = typeof args.path === "string" ? args.path : undefined;
+  const limit = typeof args.limit === "number" ? args.limit : undefined;
+
+  const result = await context.util.withAbort(options?.signal, async function runFind() {
+    return context.fs.glob(pattern, {
+      path: searchDir,
+      limit,
+      signal: options?.signal,
+    });
+  });
+
+  if (result.paths.length === 0) {
+    return {
+      content: [{ type: "text", text: "No files found matching pattern" }],
+      details: undefined,
+    };
+  }
+
+  const compressed = context.util.compressFindPaths(result.paths);
+  const truncation = context.util.truncateHead(compressed.text, {
+    maxLines: Number.MAX_SAFE_INTEGER,
+  });
+  let resultOutput = truncation.content;
+  const details = {};
+  const notices = [];
+
+  if (compressed.applied) {
+    resultOutput = `${compressed.banner}\n${resultOutput}`;
+  }
+
+  if (result.resultLimitReached) {
+    notices.push(
+      `${result.limit} results limit reached. Use limit=${result.limit * 2} for more, or refine pattern`,
+    );
+    details.resultLimitReached = result.limit;
+  }
+  if (truncation.truncated) {
+    notices.push(`${context.util.formatSize(context.util.maxBytes)} limit reached`);
+    details.truncation = truncation;
+  }
+  if (notices.length > 0) {
+    resultOutput += `\n\n[${notices.join(". ")}]`;
+  }
+
+  return {
+    content: [{ type: "text", text: resultOutput }],
+    details: Object.keys(details).length > 0 ? details : undefined,
+  };
+}

package/dist/bundled-skills/tarsk-find-images/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: tarsk-find-images
+description: >-
+  Tarsk Tool skill publishing: find_images.
+version: 2.0.0
+tools:
+  - find_images
+deferred-tools:
+  - find_images
+disable-model-invocation: true
+---
+
+# tarsk-find-images
+
+Publishes: find_images.
+
+Success/error copy in `scripts/find_images.js`. Host
+`context.images.searchAndSave` (network + cwd-safe save).

package/dist/bundled-skills/tarsk-find-images/scripts/find_images.js

@@ -0,0 +1,78 @@
+/**
+ * find_images — success/error copy in the Skill; host searches + saves.
+ */
+
+export const description =
+  "Find a stock image matching a search query. Returns a URL served by the Tarsk API and optionally saves the image to a file. " +
+  "Use this when the user needs an image and the user has not requested it be generated.";
+
+export const parameters = {
+  type: "object",
+  required: ["query"],
+  properties: {
+    query: {
+      description: "Image search query, e.g. 'sunset over mountains'",
+      type: "string",
+    },
+    size: {
+      description:
+        "Image size variant: original, large2x, large, medium (default), small, portrait, landscape, tiny",
+      type: "string",
+    },
+    save_to_file: {
+      description:
+        "File path relative to the project root to save the image to (e.g. 'assets/hero.jpg'). " +
+        "Parent directories are created automatically. " +
+        "If omitted the image is saved under .tarsk/tmp-images/.",
+      type: "string",
+    },
+  },
+};
+
+/** @param {Record<string, unknown>} args @param {import("../../../../src/tools/agent-runtime/types.js").AgentRuntime} context @param {{ signal?: AbortSignal }} [options] */
+export async function execute(args, context, options) {
+  const result = await context.images.searchAndSave(args, options);
+  if (!result.ok) {
+    if (result.reason === "aborted") {
+      return { content: [], details: undefined };
+    }
+    if (result.reason === "search_failed") {
+      return {
+        content: [{ type: "text", text: `Image search failed: ${result.message}` }],
+        details: undefined,
+      };
+    }
+    if (result.reason === "no_cwd") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Image search succeeded but no project directory is available to save the image.",
+          },
+        ],
+        details: undefined,
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Image was found but failed to save to "${result.message}"`,
+        },
+      ],
+      details: undefined,
+    };
+  }
+
+  const payload = {
+    contentType: result.contentType,
+    savedPath: result.savedPath,
+    sizeInBytes: result.sizeInBytes,
+  };
+  if (result.imageUrl) payload.imageUrl = result.imageUrl;
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    details: result.imageUrl ? { imageUrl: result.imageUrl } : undefined,
+  };
+}

package/dist/bundled-skills/tarsk-generate-image/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: tarsk-generate-image
+description: >-
+  Tarsk Tool skill publishing: generate_image.
+version: 2.0.0
+tools:
+  - generate_image
+deferred-tools:
+  - generate_image
+disable-model-invocation: true
+---
+
+# tarsk-generate-image
+
+Publishes: generate_image.
+
+Success/error copy in `scripts/generate_image.js`. Host
+`context.images.generate` (API keys + cwd-safe save).

package/dist/bundled-skills/tarsk-generate-image/scripts/generate_image.js

@@ -0,0 +1,55 @@
+/**
+ * generate_image — success/error copy in the Skill; host holds credentials + save.
+ */
+
+export const description =
+  "Generate an image from a text prompt. Returns a URL or base64 data for the generated image. Use this when the user asks you to create, draw, design, or generate an image. Use the save_to_file parameter to save the image directly to a file in the project (e.g. 'assets/hero.png').";
+
+export const parameters = {
+  type: "object",
+  required: ["prompt", "save_to_file"],
+  properties: {
+    prompt: {
+      description: "Image description",
+      type: "string",
+    },
+    model: {
+      description:
+        "Image model name or ID to use (e.g. 'dall-e-3', 'gpt-image-1', 'google/gemini-2.5-flash-image'). If omitted the first enabled image model is used.",
+      type: "string",
+    },
+    save_to_file: {
+      description:
+        "File path (relative to the project root) to save the generated image to, e.g. 'assets/logo.png' or 'docs/diagram.png'. The file and any parent directories will be created automatically. The image is also returned as data so it can be displayed.",
+      type: "string",
+    },
+  },
+};
+
+function stripImageBytes(payload) {
+  const next = { ...payload };
+  delete next.imageData;
+  delete next.image_data;
+  if (typeof next.imageUrl === "string" && next.imageUrl.startsWith("data:")) {
+    delete next.imageUrl;
+  }
+  return next;
+}
+
+/** @param {Record<string, unknown>} args @param {import("../../../../src/tools/agent-runtime/types.js").AgentRuntime} context @param {{ signal?: AbortSignal }} [options] */
+export async function execute(args, context, options) {
+  const result = await context.images.generate(args, options);
+  if (!result.ok) {
+    if (result.reason === "aborted") {
+      return { content: [], details: undefined };
+    }
+    return {
+      content: [{ type: "text", text: result.message }],
+      details: result.details,
+    };
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify(stripImageBytes(result.payload)) }],
+    details: result.details,
+  };
+}

package/dist/bundled-skills/tarsk-get-observation/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: tarsk-get-observation
+description: >-
+  Tarsk Tool skill publishing: get_observation.
+version: 2.0.2
+tools:
+  - get_observation
+disable-model-invocation: true
+---
+
+# tarsk-get-observation
+
+Publishes: get_observation.
+
+Paging, JSON-path selection, miss/continuation copy, and batching live in
+`scripts/get_observation.js` (edit to tune tokens / turn guidance).
+
+Host (`context.observations`): `resolveId`, `fetch`, `recordRetrieved`, `limits`
+— DB and telemetry only.

package/dist/bundled-skills/tarsk-get-observation/scripts/get_observation.js

@@ -0,0 +1,293 @@
+/**
+ * get_observation — paging, JSON path, and model copy live here (malleable).
+ * Host: context.observations resolveId / fetch / recordRetrieved (DB only).
+ */
+
+export const description =
+  "Page a narrow slice of a stored observation by ID (tool output or over-threshold user message). Never walk the whole body with repeated max pages — prefer path (JSON), a small limit, or re-run the producing tool with a tighter command. Default 40 lines; max 80 lines / 50.0KB per ID. Batch with ids (max 20) — ids wins over a stray id. offset/limit are stored-output line indexes, not source-file or grep line numbers. Do not use for read results — call read on the file. Extra or missing hex in the id is repaired. Thread-scoped.";
+
+export const parameters = {
+  type: "object",
+  properties: {
+    id: {
+      description:
+        "Observation ID from a tool-result or user-message preview (obs_ + 64 hex). Extra or missing hex is repaired.",
+      maxLength: 200,
+      minLength: 12,
+      type: "string",
+    },
+    ids: {
+      minItems: 1,
+      maxItems: 20,
+      description: "Batch retrieval; prefer this over parallel calls.",
+      type: "array",
+      items: {
+        description:
+          "Observation ID from a tool-result or user-message preview (obs_ + 64 hex). Extra or missing hex is repaired.",
+        maxLength: 200,
+        minLength: 12,
+        type: "string",
+      },
+    },
+    offset: { minimum: 1, type: "integer" },
+    limit: { maximum: 80, minimum: 1, type: "integer" },
+    path: { minLength: 1, maxLength: 500, type: "string" },
+  },
+};
+
+/** Keep miss guidance byte-stable so prompt-cache prefixes stay warm. */
+const MISS_RETRY =
+  "Thread-scoped: the id may be from another thread or expired. Re-run the producing tool or page a recent observation id; do not retry this id verbatim.";
+
+function resolveJsonSegment(path, segment, value) {
+  if (segment.length === 0) {
+    throw new Error(`JSON path "${path}" empty segment.`);
+  }
+  if (Array.isArray(value)) {
+    if (!/^\d+$/.test(segment)) {
+      throw new Error(`JSON path "${path}" expected an array index at "${segment}".`);
+    }
+    const index = Number(segment);
+    if (index >= value.length) {
+      throw new Error(`JSON path "${path}" array index ${index} is out of bounds.`);
+    }
+    return value[index];
+  }
+  if (value && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, segment)) {
+    return value[segment];
+  }
+  throw new Error(`JSON path "${path}" does not contain segment "${segment}".`);
+}
+
+function selectJsonPath(content, path) {
+  let value;
+  try {
+    value = JSON.parse(content);
+  } catch {
+    throw new Error("Observation content is not valid JSON; omit path to retrieve it by lines.");
+  }
+  for (const segment of path.split(".")) {
+    value = resolveJsonSegment(path, segment, value);
+  }
+  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}
+
+function resolveIds(args) {
+  // `ids` wins over a stray `id`: both keys together is a common habit, and
+  // failing the call costs a turn when the batch is already unambiguous.
+  if (Array.isArray(args.ids) && args.ids.length > 0) {
+    return args.ids.map(String);
+  }
+  if (typeof args.id === "string" && args.id) return [args.id];
+  throw new Error("Provide id or ids.");
+}
+
+function assembleBlock(id, lineRange, content, jsonPath, suffix) {
+  const parts = [
+    `<observation_data id="${id}" lines="${lineRange}">`,
+    jsonPath ? `[JSON path: ${jsonPath}]` : undefined,
+    content,
+    "</observation_data>",
+  ];
+  if (suffix !== undefined) parts.push(suffix);
+  return parts.filter((line) => line !== undefined).join("\n");
+}
+
+function lineByteLength(line) {
+  return Buffer.byteLength(line, "utf-8");
+}
+
+function formatOversizedLine(lineNumber, line, maxBytes, formatSize) {
+  return `Line ${lineNumber} is ${formatSize(lineByteLength(line))} and exceeds the ${formatSize(maxBytes)} retrieval limit (elided)`;
+}
+
+function nextReadableOffset(lines, fromOneIndexed, maxBytes) {
+  const start = Math.max(0, fromOneIndexed - 1);
+  for (let i = start; i < lines.length; i++) {
+    if (lineByteLength(lines[i] ?? "") <= maxBytes) return i + 1;
+  }
+  return undefined;
+}
+
+function formatContinuation(lines, offset, endLine, maxBytes, formatSize) {
+  const total = lines.length;
+  if (endLine >= total) {
+    return `\n\n[Showing lines ${offset}-${endLine} of ${total}.]`;
+  }
+  const nextLine = lines[endLine];
+  if (nextLine === undefined || lineByteLength(nextLine) <= maxBytes) {
+    return `\n\n[Showing lines ${offset}-${endLine} of ${total}. Use offset=${endLine + 1} to continue.]`;
+  }
+  const skipped = [];
+  let index = endLine;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (line === undefined || lineByteLength(line) <= maxBytes) break;
+    skipped.push(formatOversizedLine(index + 1, line, maxBytes, formatSize));
+    index += 1;
+  }
+  const skipNote = skipped.join(". ");
+  if (index < lines.length) {
+    return `\n\n[Showing lines ${offset}-${endLine} of ${total}. ${skipNote}. Use offset=${index + 1} to continue.]`;
+  }
+  return `\n\n[Showing lines ${offset}-${endLine} of ${total}. ${skipNote}.]`;
+}
+
+function pageOversizedStart(id, offset, lines, maxBytes, formatSize) {
+  const line = lines[offset - 1] ?? "";
+  const note = formatOversizedLine(offset, line, maxBytes, formatSize);
+  const nextOffset = nextReadableOffset(lines, offset + 1, maxBytes);
+  const continueHint = nextOffset ? ` Use offset=${nextOffset} to continue.` : "";
+  const text = [
+    `<observation_data id="${id}" lines="${offset}-${offset}">`,
+    `[${note}]`,
+    "</observation_data>",
+    "",
+    `[${note}.${continueHint}]`,
+  ].join("\n");
+  return { text, outputBytes: Buffer.byteLength(text, "utf-8") };
+}
+
+function pageObservation(stored, offset, limit, jsonPath, maxBytes, formatSize, truncateHead) {
+  if (stored.toolName === "read") {
+    const text =
+      `This observation came from read. Use the read tool on the original file ` +
+      `instead of get_observation (offset=${offset}). Do not page this stored output.`;
+    return { id: stored.id, text, outputBytes: Buffer.byteLength(text, "utf-8") };
+  }
+
+  const selected = jsonPath ? selectJsonPath(stored.content, jsonPath) : stored.content;
+  const lines = selected.split("\n");
+  const lineCount = lines.length;
+
+  if (lines.length > 0 && offset === lineCount + 1) {
+    const lastLine = lines[lineCount - 1] ?? "";
+    const text = [
+      `Offset ${offset} is one past the end of observation ${stored.id} (${lineCount === 1 ? "1 line" : `${lineCount} lines`} total). Showing the last line. There is no further page.`,
+      `<observation_data id="${stored.id}" lines="${lineCount}-${lineCount}">`,
+      lastLine,
+      "</observation_data>",
+    ].join("\n");
+    return { id: stored.id, text, outputBytes: Buffer.byteLength(text, "utf-8") };
+  }
+
+  if (offset > lineCount) {
+    const parts = [
+      `Offset ${offset} is beyond end of observation ${stored.id} (${lineCount === 1 ? "1 line" : `${lineCount} lines`} total).`,
+      "Observation offset is 1-indexed within the stored observation, not a source-file line number and not a character offset.",
+    ];
+    if (lineCount === 1) parts.push("This observation is a single line; there is no further page.");
+    else if (lineCount > 0)
+      parts.push(`Valid offsets are 1-${lineCount}. Use offset=1 to read from the start.`);
+    else parts.push("Observation is empty.");
+    if (stored.toolName === "read") {
+      parts.push(
+        `If you meant a source-file line, call read with that file's path and offset=${offset} instead of paging this observation.`,
+      );
+    }
+    const message = parts.join(" ");
+    if (lineCount === 1) {
+      const truncation = truncateHead(lines[0] ?? "", { maxBytes, maxLines: 1 });
+      const text = [message, assembleBlock(stored.id, "1-1", truncation.content, jsonPath)].join(
+        "\n",
+      );
+      return { id: stored.id, text, outputBytes: Buffer.byteLength(text, "utf-8") };
+    }
+    if (lineCount === 0) {
+      throw new Error(message);
+    }
+    const tailStart = Math.max(1, lineCount - limit + 1);
+    const tail = pageObservation(
+      stored,
+      tailStart,
+      limit,
+      jsonPath,
+      maxBytes,
+      formatSize,
+      truncateHead,
+    );
+    const text =
+      `${message}\n` +
+      `[Offset ${offset} is past the end; showing the last page (lines ${tailStart}-${lineCount}) instead.]\n\n` +
+      tail.text;
+    return { id: stored.id, text, outputBytes: Buffer.byteLength(text, "utf-8") };
+  }
+
+  const startIndex = offset - 1;
+  const selectedText = lines.slice(startIndex, startIndex + limit).join("\n");
+  const truncation = truncateHead(selectedText, { maxBytes, maxLines: limit });
+  if (truncation.firstLineExceedsLimit) {
+    return pageOversizedStart(stored.id, offset, lines, maxBytes, formatSize);
+  }
+  const endLine = offset + truncation.outputLines - 1;
+  const suffix = formatContinuation(lines, offset, endLine, maxBytes, formatSize);
+  const text = assembleBlock(
+    stored.id,
+    `${offset}-${endLine}`,
+    truncation.content,
+    jsonPath,
+    suffix,
+  );
+  return { id: stored.id, text, outputBytes: truncation.outputBytes };
+}
+
+/** @param {Record<string, unknown>} args @param {import("../../../../src/tools/agent-runtime/types.js").AgentRuntime} context */
+export async function execute(args, context) {
+  const { limits } = context.observations;
+  const rawIds = resolveIds(args);
+  const offset = typeof args.offset === "number" ? args.offset : 1;
+  const requestedLimit = typeof args.limit === "number" ? args.limit : limits.defaultLines;
+  const limit = Math.min(Math.max(1, requestedLimit), limits.maxLines);
+  const jsonPath = typeof args.path === "string" ? args.path : undefined;
+
+  const pages = [];
+  for (const rawId of rawIds) {
+    const resolved = await context.observations.resolveId(rawId);
+    if (!resolved.ok) {
+      if (resolved.reason === "ambiguous") {
+        throw new Error(
+          `Ambiguous observation ID prefix "${rawId}". Matches: ${(resolved.matches ?? []).join(", ")}. ${MISS_RETRY}`,
+        );
+      }
+      if (resolved.reason === "invalid") {
+        throw new Error(`Invalid observation ID. ${MISS_RETRY}`);
+      }
+      throw new Error(`Observation not found: ${rawId}. ${MISS_RETRY}`);
+    }
+    const stored = await context.observations.fetch(resolved.id);
+    if (!stored) {
+      throw new Error(`Observation not found: ${resolved.id}. ${MISS_RETRY}`);
+    }
+    pages.push(
+      pageObservation(
+        stored,
+        offset,
+        limit,
+        jsonPath,
+        limits.maxBytes,
+        context.util.formatSize,
+        context.util.truncateHead,
+      ),
+    );
+  }
+
+  for (const page of pages) {
+    await context.observations.recordRetrieved(page.outputBytes);
+  }
+
+  const output = pages.map((page) => page.text).join("\n\n");
+  const truncation = context.util.truncateHead(output, {
+    maxBytes: limits.maxBytes * Math.max(1, pages.length),
+    maxLines: limits.maxLines * Math.max(1, pages.length),
+  });
+
+  const details =
+    pages.length === 1
+      ? { observationId: pages[0].id, jsonPath, truncation }
+      : { observationIds: pages.map((page) => page.id), jsonPath, truncation };
+
+  return {
+    content: [{ type: "text", text: truncation.content }],
+    details,
+  };
+}

package/dist/bundled-skills/tarsk-grep/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: tarsk-grep
+description: >-
+  Tarsk Tool skill publishing: grep.
+version: 2.0.0
+tools:
+  - grep
+disable-model-invocation: true
+---
+
+# tarsk-grep
+
+Publishes: grep.
+
+Empty/pagination/banner copy in `scripts/grep.js`. Host `context.fs.grep`
+returns structured rows (cwd checks + ripgrep only).