tarsk 0.6.87 → 0.6.89

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).

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

@@ -0,0 +1,174 @@
+/**
+ * grep — success/empty/pagination copy in the Skill; host runs path-safe ripgrep.
+ */
+
+export const description =
+  "Search file contents (not paths; use find for path globs) with regex (ripgrep-compatible). Content mode defaults to match lines only (-C 0); pass -C 3 (or -A/-B/context) when you need nearby lines for a unique edit hunk. output_mode: content (default; -A/-B/-C/context/-n apply here, -n defaults true), files_with_matches, count. Scope with path; glob for name/extension (*.ts, **/*.tsx)—not a path substitute. type = rg --type. head_limit default 25 (0=unlimited); offset skips. multiline: . matches newlines. Respects .gitignore. For many hits→reads, prefer one run_js over serial turns.";
+
+export const parameters = {
+  type: "object",
+  required: ["pattern"],
+  properties: {
+    pattern: { type: "string" },
+    path: { type: "string" },
+    glob: {
+      description: "name/extension filter, e.g. *.ts. Prefer path for a directory.",
+      type: "string",
+    },
+    output_mode: {
+      anyOf: [
+        { const: "content", type: "string" },
+        { const: "files_with_matches", type: "string" },
+        { const: "count", type: "string" },
+      ],
+    },
+    "-B": { type: "number" },
+    "-A": { type: "number" },
+    "-C": {
+      description: "Lines of context around each match (default 0 = match lines only).",
+      type: "number",
+    },
+    context: {
+      description: "Alias for -C (default 0 = match lines only).",
+      type: "number",
+    },
+    "-n": { type: "boolean" },
+    "-i": { type: "boolean" },
+    type: { type: "string" },
+    head_limit: { type: "number" },
+    offset: { type: "number" },
+    multiline: {
+      description: ". matches newlines",
+      type: "boolean",
+    },
+  },
+};
+
+const LITERAL_FALLBACK_NOTICE = "[Pattern was not valid regex; searched as a literal string]";
+/** Matches shared MAX_GREP_CONTENT_CONTEXT — Skill-owned notice copy. */
+const MAX_GREP_CONTENT_CONTEXT = 2;
+
+function emptyMatchText(pathScopedGlob) {
+  if (pathScopedGlob) {
+    return (
+      "No matches found. Tip: prefer path for file/directory scope " +
+      '(e.g. path="app/components") and extension globs like "*.tsx" or "**/*.ts"; ' +
+      "path-prefixed globs can miss matches depending on the search root."
+    );
+  }
+  return "No matches found";
+}
+
+function formatLimitInfo(appliedLimit, appliedOffset) {
+  const parts = [];
+  if (appliedLimit !== undefined) parts.push(`limit: ${appliedLimit}`);
+  if (appliedOffset) parts.push(`offset: ${appliedOffset}`);
+  return parts.join(", ");
+}
+
+function formatBudgetNotice(budget) {
+  const parts = [];
+  if (budget.contextClamped) {
+    parts.push(`Context limited to ${MAX_GREP_CONTENT_CONTEXT} lines per side.`);
+  }
+  if (budget.headLimitScaled && budget.headLimit) {
+    parts.push(`Output line budget scaled to ${budget.headLimit}.`);
+  }
+  if (parts.length === 0) return "";
+  return `[${parts.join(" ")}]`;
+}
+
+function formatSkippedNotice(skippedPaths) {
+  if (!skippedPaths || skippedPaths.length === 0) return undefined;
+  return `[Skipped missing path(s): ${skippedPaths.join(", ")}]`;
+}
+
+function buildPrefix(searchedAsLiteral, skippedPaths) {
+  const notices = [];
+  if (searchedAsLiteral) notices.push(LITERAL_FALLBACK_NOTICE);
+  const skipped = formatSkippedNotice(skippedPaths);
+  if (skipped) notices.push(skipped);
+  return notices.length > 0 ? `${notices.join("\n")}\n` : "";
+}
+
+function formatContent(result, context) {
+  const emptyText = emptyMatchText(result.pathScopedGlob);
+  if (result.lines.length === 0) return emptyText;
+
+  const compressed = context.util.compressGrepContent(result.lines);
+  let text = compressed.applied ? `${compressed.banner}\n${compressed.text}` : compressed.text;
+  const budgetNotice = formatBudgetNotice(result.budget);
+  if (budgetNotice) text += `\n\n${budgetNotice}`;
+  const limitInfo = formatLimitInfo(result.appliedLimit, result.appliedOffset);
+  if (limitInfo) text += `\n\n[Showing results with pagination = ${limitInfo}]`;
+  return text;
+}
+
+function formatCount(result, context) {
+  const emptyText = emptyMatchText(result.pathScopedGlob);
+  if (result.lines.length === 0) return emptyText;
+
+  const compressed = context.util.compressGrepCount(result.lines);
+  let text = compressed.applied ? `${compressed.banner}\n${compressed.text}` : compressed.text;
+  const totalMatches = result.totalMatches ?? 0;
+  const fileCount = result.fileCount ?? 0;
+  const occurrenceLabel = totalMatches === 1 ? "occurrence" : "occurrences";
+  const fileLabel = fileCount === 1 ? "file" : "files";
+  text += `\n\nFound ${totalMatches} total ${occurrenceLabel} across ${fileCount} ${fileLabel}.`;
+  const limitInfo = formatLimitInfo(result.appliedLimit, result.appliedOffset);
+  if (limitInfo) text += ` with pagination = ${limitInfo}`;
+  return text;
+}
+
+function formatFiles(result, context) {
+  const emptyText = emptyMatchText(result.pathScopedGlob);
+  if (result.lines.length === 0) {
+    return emptyText === "No matches found"
+      ? "No files found"
+      : emptyText.replace("No matches found", "No files found");
+  }
+
+  const fileLabel = result.lines.length === 1 ? "file" : "files";
+  const compressed = context.util.compressGrepFiles(result.lines);
+  const listing = compressed.applied ? `${compressed.banner}\n${compressed.text}` : compressed.text;
+  const limitInfo = formatLimitInfo(result.appliedLimit, result.appliedOffset);
+  return `Found ${result.lines.length} ${fileLabel}${limitInfo ? ` ${limitInfo}` : ""}\n${listing}`;
+}
+
+/** @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.fs.grep(args, { signal: options?.signal });
+
+  let body;
+  if (result.mode === "count") {
+    body = formatCount(result, context);
+  } else if (result.mode === "files_with_matches") {
+    body = formatFiles(result, context);
+  } else {
+    body = formatContent(result, context);
+  }
+
+  const truncation = context.util.truncateHead(body);
+  const trailing = truncation.truncated
+    ? `\n\n[${context.util.formatSize(context.util.maxBytes)} limit reached]`
+    : "";
+  const text = `${buildPrefix(result.searchedAsLiteral, result.skippedPaths)}${truncation.content}${trailing}`;
+
+  const details = {
+    mode: result.mode,
+  };
+  if (result.mode === "content") details.numLines = result.lines.length;
+  if (result.mode === "count") {
+    details.numFiles = result.fileCount;
+    details.numMatches = result.totalMatches;
+  }
+  if (result.mode === "files_with_matches") details.numFiles = result.lines.length;
+  if (result.appliedLimit !== undefined) details.appliedLimit = result.appliedLimit;
+  if (result.appliedOffset !== undefined) details.appliedOffset = result.appliedOffset;
+  if (truncation.truncated) details.truncation = truncation;
+
+  return {
+    content: [{ type: "text", text }],
+    details,
+  };
+}

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

@@ -0,0 +1,15 @@
+---
+name: tarsk-history
+description: >-
+  Tarsk Tool skill publishing: history.
+version: 2.0.0
+tools:
+  - history
+deferred-tools:
+  - history
+disable-model-invocation: true
+---
+
+# tarsk-history
+
+Publishes: history.

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

@@ -0,0 +1,68 @@
+/**
+ * history Tool — logic in the Skill; transcript store is context.history (host).
+ */
+
+export const description =
+  "Search and read the complete durable agent transcript, including content outside the current model context window. Use search to find exact earlier instructions, tool results, commands, errors, or decisions, then read an entry by id for more detail. Reads are paged by character offset. Search the current conversation by default; set allConversations only when older conversations in this thread are relevant.";
+
+export const parameters = {
+  type: "object",
+  required: ["op"],
+  properties: {
+    op: {
+      anyOf: [
+        { const: "search", type: "string" },
+        { const: "read", type: "string" },
+      ],
+    },
+    query: { description: "Text to find for search", type: "string" },
+    entryId: { description: "Entry id returned by search", type: "string" },
+    offset: { minimum: 0, description: "Character offset for read", type: "integer" },
+    limit: { minimum: 1, maximum: 25, type: "integer" },
+    allConversations: {
+      description: "Search every conversation in this thread",
+      type: "boolean",
+    },
+  },
+};
+
+function textResult(text) {
+  return {
+    content: [{ type: "text", text }],
+    details: undefined,
+  };
+}
+
+function requireValue(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${field} is required for this operation`);
+  }
+  return value;
+}
+
+/** @param {Record<string, unknown>} args @param {import("../../../../src/tools/agent-runtime/types.js").AgentRuntime} context */
+export async function execute(args, context) {
+  if (!context.history.available) {
+    return textResult("Conversation history is unavailable for this session.");
+  }
+
+  if (args.op === "search") {
+    const results = await context.history.search({
+      query: requireValue(args.query, "query"),
+      allConversations: Boolean(args.allConversations),
+      limit: typeof args.limit === "number" ? args.limit : undefined,
+    });
+    return textResult(JSON.stringify(results));
+  }
+
+  if (args.op === "read") {
+    const result = await context.history.read({
+      entryId: requireValue(args.entryId, "entryId"),
+      allConversations: Boolean(args.allConversations),
+      offset: typeof args.offset === "number" ? args.offset : undefined,
+    });
+    return textResult(result ? JSON.stringify(result) : "History entry not found.");
+  }
+
+  throw new Error(`Unknown history op: ${String(args.op)}`);
+}