tarsk 0.6.87 → 0.6.88

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)}`);
+}

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

@@ -0,0 +1,232 @@
+---
+name: tarsk-improve
+description: >-
+  End-of-session review that improves Tarsk built-in Tool skills from this chat
+  or prior runs in tarsk.db, then applies the small description/schema/execute
+  fixes that clear the worth bar. In an ordinary project it exports bundled
+  tarsk-* Skills into .agents/skills and edits those copies. In the Tarsk
+  checkout the built-ins are the repo's own files: it copies nothing and edits
+  cli/bundled-skills/tarsk-* directly. At the end it prunes project copies that
+  still match bundled. Use when the user says improve tools, /tarsk-improve,
+  learn from this session, or reduce tool failures/turns/tokens after a chat.
+version: 2.2.1
+disable-model-invocation: true
+when_to_use: >-
+  At the end of a chat (or when reviewing recent sessions) to improve shipped
+  Tool skills from real failures, retries, or turn/token waste — not mid-task
+  opportunistic edits.
+---
+
+# Improve Tarsk Tool skills (`tarsk-improve`)
+
+Turn this conversation (or recent sessions) into **small fixes to built-in Tool
+skills**. Edit whichever copy the Tool loader resolves for this repo:
+
+- **Ordinary project:** the project export under `.agents/skills/tarsk-*`
+  (step 0 copies it in).
+- **The Tarsk checkout itself:** `cli/bundled-skills/tarsk-*` directly. Here the
+  built-ins are the repo's own files, so step 0 copies nothing and
+  `.agents/skills/tarsk-*` must stay absent.
+
+This skill ships with Tarsk and works in any repo. It is **user-invoked**
+(`disable-model-invocation`) — run at the end of a session, not mid-task.
+
+## Goal
+
+Cut repeated tool failures, serial multi-hop that should be one `run_js`, noisy
+defaults, and misleading schemas/descriptions — by patching the Tool skill that
+publishes that tool.
+
+Every change must clear the **worth bar** before it is made:
+
+- One of: cuts wasted turns significantly, cuts tokens significantly, fixes a
+  bug the tool itself causes — or a new Tool skill would be a significant gain.
+- Likely to recur: the waste affects or plausibly will affect multiple
+  sessions, not one call pattern from a single chat.
+- Tool copy stays token-efficient: edited `description` / parameter text is
+  the same length or shorter.
+- Nothing clearing the bar is a valid outcome too: end the run with that
+  result and nothing patched.
+
+## Scope
+
+**In scope**
+
+- Bundled Tool skills: `.agents/skills/tarsk-*/` in a user project (must exist
+  after step 0), or `cli/bundled-skills/tarsk-*/` in the Tarsk checkout
+- `description`, `parameters`, and `execute` in `scripts/{tool}.js`
+- Packaging rules in the `tarsk-agent` skill
+
+**Out of scope**
+
+- User project skills/rules/`AGENTS.md` that are not `tarsk-*` Tool skills
+- Mid-task workarounds (system prompt already covers those)
+- Large Tarsk product refactors unrelated to a Tool skill surface
+
+## Required workflow
+
+Copy and track:
+
+```
+Improve progress:
+- [ ] 0. Export tarsk-* into .agents/skills (Tarsk checkout: copies nothing)
+- [ ] 1. Summarize this session / recent runs
+- [ ] 2. Diagnose Tool skill gaps
+- [ ] 3. Assess by the worth bar (no ask; no-change is a valid result)
+- [ ] 4. Patch the one resolvable copy (read tarsk-agent first)
+- [ ] 5. Report what changed and the expected improvement
+- [ ] 6. Prune project copies that still match bundled
+```
+
+### 0. Export before any edit (user projects)
+
+From the project / thread root:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/ensure-exported.ts
+```
+
+If that path is missing (skill not yet exported), run from the bundled copy and
+point at the project:
+
+```bash
+bun <path-to-bundled-skills>/tarsk-improve/scripts/ensure-exported.ts --project-skills .agents/skills
+```
+
+Or set `TARSK_BUNDLED_SKILLS` to the bundled-skills directory.
+
+**In the Tarsk checkout the script copies nothing** — it prints:
+
+```
+Tarsk checkout: the built-ins are this repo's own files, so nothing was copied.
+Edit cli/bundled-skills/tarsk-* directly (/…/cli/bundled-skills).
+```
+
+Then edit `cli/bundled-skills/tarsk-*/` in place. Never create
+`.agents/skills/tarsk-*` copies in this repo, and read "Editable Tool skills
+(none)" as the expected result, not as a failure.
+
+**Hard rule (user projects):** Only edit paths listed under "Editable Tool
+skills" in the script output (under `.agents/skills/…`). If a Tool skill is
+missing there, re-run the export command above. The host never creates project
+copies on chat load; it only prunes copies that match bundled, so export before
+editing.
+
+### 1. Summarize
+
+Prefer the **current conversation** when the user is wrapping up this chat:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/summarize-session.ts --conversation <id>
+```
+
+Otherwise recent waste:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/summarize-session.ts --since 24h
+```
+
+Do not dump raw `entries` JSON. Use `history` only for a specific failure quote.
+
+### 2. Diagnose
+
+Map waste to a **Tool skill** (package that publishes the tool), not only a tool
+name:
+
+| Signal                        | Likely fix                                          |
+| ----------------------------- | --------------------------------------------------- |
+| Same tool fails repeatedly    | Clearer errors, validation, safer defaults          |
+| grep→read loops / serial hops | Description bias to `run_js`; tighten tool guidance |
+| Huge results / token spikes   | Default `select`, truncation, preview copy          |
+| Wrong tool chosen often       | Description / when_to_use / schema shape            |
+| Retries with identical args   | Idempotent messaging or “already applied” guidance  |
+
+Read [references/signals.md](references/signals.md) when patterns are unclear.
+
+### 3. Assess by the worth bar — then implement, no gate
+
+Keep the plan short, state one grouped reason the changes clear the bar, and go
+straight into step 4 in the same turn. Do not ask which items to implement; the
+bar decides. List below-bar candidates as skipped, one line each. If nothing
+clears the bar, "no changes needed" is the correct result: say it in one line
+and skip patching.
+
+```markdown
+## Improve plan
+
+**Runs:** <this conversation / since …>
+**Export:** <copied N; editable Tool skills — or Tarsk checkout: edit bundled>
+
+### Findings
+
+1. …
+2. …
+
+### Changes to make (ROI order)
+
+1. `tarsk-<skill>` / `scripts/<tool>.js` — …
+2. …
+
+### Why these clear the bar (one group)
+
+<Short plain wording: what the runs waste in turns/tokens, how often, and why
+it will keep recurring across sessions — one paragraph for the whole batch, not
+one reason per item.>
+
+### Skipped (below the bar)
+
+1. <finding> — <one line: single-session only / cost already small / …>
+```
+
+### 4. Implement
+
+1. Read the `tarsk-agent` skill (packaging + `context.*` contract).
+2. Edit the resolved copy only: `.agents/skills/tarsk-<name>/` (user project) or
+   `cli/bundled-skills/tarsk-<name>/` (Tarsk checkout).
+3. Prefer the smallest change: `description` / `parameters` / `execute`. Keep
+   copy the same length or shorter — fold new guidance into existing lines
+   instead of adding sentences.
+4. Bump the Skill `version` patch (or minor) in that package's `SKILL.md` when
+   you intentionally change behavior so future major exports do not silently
+   clobber without a decision.
+5. If `edit`/`write` returns `[tool-skill-load]` with a revert, the bad script
+   was restored automatically — fix the reported error and retry; do not leave
+   a broken Tool skill on disk.
+6. In a user project do **not** hand-edit `cli/bundled-skills/` or any other
+   built-in tree; the project export is the only edit surface there.
+
+### 5. Report
+
+List files changed, which Tool each affects, and one expected-improvement line
+for the batch in plain wording a curious non-developer can follow (fewer
+retries, smaller output, no more needless blocks). Point back to the plan's
+group reason for why, instead of repeating it. When nothing was patched, one
+line: what was reviewed and why no change cleared the bar. Then how to verify:
+re-run the failing call pattern in a new turn; Tool skill reload picks up script
+mtime.
+
+In the Tarsk checkout there is no upstream step: the files you edited under
+`cli/bundled-skills/tarsk-*` are the built-ins that ship.
+
+### 6. Prune unchanged copies (required in user projects)
+
+Delete project copies that still match bundled so the repo only keeps Tool
+skills that actually changed:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/ensure-exported.ts --prune
+```
+
+`removed` lists the copies that matched bundled; `kept` lists the ones you
+changed. The host also prunes on chat load, so untouched copies never persist.
+In the Tarsk checkout this only cleans up legacy copies; `removed: (none)` with
+`kept: 0` is the expected result.
+
+## Script index
+
+| Script                      | Role                                                                                         |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| `ensure-exported.ts`        | Export `tarsk-*` for editing (skips the Tarsk checkout); `--prune` deletes copies that match |
+| `export-tool-skills-lib.ts` | Shared export/prune rules (also used by the host)                                            |
+| `summarize-session.ts`      | Waste-ranked run summary from `tarsk.db`                                                     |
+| `durable-runs.ts`           | Shared DB reader (imported by summarize-session)                                             |

package/dist/bundled-skills/tarsk-improve/references/signals.md

@@ -0,0 +1,16 @@
+# Signals → Tool skill fixes
+
+Use the summarize-session output. Prefer product-facing Tool skill edits over
+telling the model to “try harder.”
+
+| Pattern in runs                                | Prefer editing                                           |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| Same `tool` fails with the same args           | Error text / validation in that tool’s `execute`         |
+| Many turns of grep → read → grep               | `run_js` description + tool descriptions that bias chain |
+| Large `largest tool results` on read/bash/grep | Defaults for `select` / truncation / preview copy        |
+| Tool chosen when another was right             | `description` disambiguation                             |
+| `retried a failed call unchanged`              | Clearer “already done / change approach” messaging       |
+| Browser / MCP flailing                         | Deferred tool descriptions; deferral list clarity        |
+
+Always resolve the Tool name to its Skill package under
+`.agents/skills/tarsk-*/SKILL.md` (`tools:` list) before editing.