tarsk 0.6.87 → 0.6.88

package/dist/bundled-skills/email-me/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: email-me
+description: Use when the user asks "email me".
+version: 1.0.0
+tools:
+  - email_me
+---
+# Email me
+
+Sends an email to the signed-in Tarsk user.
+
+- Put the information the user wants into `body`. Keep `subject` short.
+- Call `email_me` once, then report its answer.
+- When it reports that no one is signed in, ask the user to log in to Tarsk.
+  Do not call the tool again until the user is signed in.

package/dist/bundled-skills/email-me/scripts/__tests__/email_me.test.js

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { execute } from "../email_me.js";
+
+function contextReturning(result) {
+  const calls = [];
+  return {
+    calls,
+    email: {
+      async sendToSelf(message) {
+        calls.push(message);
+        return result;
+      },
+    },
+  };
+}
+
+void test("asks the user to log in to Tarsk when no account is signed in", async () => {
+  const context = contextReturning({ status: "not-signed-in" });
+
+  const result = await execute({ body: "The build is green." }, context);
+
+  assert.match(result.content[0].text, /log in to Tarsk/i);
+  assert.equal(context.calls.length, 1);
+});
+
+void test("sends the requested subject and body and names the address", async () => {
+  const context = contextReturning({ status: "sent", to: "owner@example.com" });
+
+  const result = await execute(
+    { subject: "Status", body: "The build is green." },
+    context,
+  );
+
+  assert.deepEqual(context.calls, [{ subject: "Status", body: "The build is green." }]);
+  assert.match(result.content[0].text, /owner@example\.com/);
+});
+
+void test("defaults the subject when none is given", async () => {
+  const context = contextReturning({ status: "sent", to: "owner@example.com" });
+
+  await execute({ body: "The build is green." }, context);
+
+  assert.equal(context.calls[0].subject, "Message from Tarsk");
+});
+
+void test("reports a failed send with the service message", async () => {
+  const context = contextReturning({ status: "failed", message: "rate limited" });
+
+  const result = await execute({ body: "The build is green." }, context);
+
+  assert.match(result.content[0].text, /rate limited/);
+  assert.equal(context.calls.length, 1);
+});
+
+void test("refuses an empty body without sending", async () => {
+  const context = contextReturning({ status: "sent", to: "owner@example.com" });
+
+  const result = await execute({ body: "   " }, context);
+
+  assert.match(result.content[0].text, /body/i);
+  assert.equal(context.calls.length, 0);
+});

package/dist/bundled-skills/email-me/scripts/email_me.js

@@ -0,0 +1,45 @@
+export const description =
+  'Send an email to the signed-in Tarsk user. Use when the user says "email me".';
+
+export const parameters = {
+  type: "object",
+  properties: {
+    subject: { type: "string", description: "Short subject line for the email" },
+    body: {
+      type: "string",
+      description: "Email body: the information the user asked to include",
+    },
+  },
+  required: ["body"],
+};
+
+export async function execute(args, context) {
+  const subject = String(args.subject ?? "").trim() || "Message from Tarsk";
+  const body = String(args.body ?? "").trim();
+  if (!body) {
+    return {
+      content: [{ type: "text", text: "email_me: `body` is empty. Put the information to send in `body`." }],
+    };
+  }
+
+  const result = await context.email.sendToSelf({ subject, body });
+
+  if (result.status === "not-signed-in") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No Tarsk account is signed in. Please log in to Tarsk and ask again.",
+        },
+      ],
+    };
+  }
+
+  if (result.status === "failed") {
+    return {
+      content: [{ type: "text", text: `The email was not sent: ${result.message}` }],
+    };
+  }
+
+  return { content: [{ type: "text", text: `Email sent to ${result.to}.` }] };
+}

package/dist/bundled-skills/handoff/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: handoff
+description: use if user asks for handoff
+argument-hint: "Optional focus for the new chat"
+---
+
+# Handoff
+
+When the user asks for a handoff or invokes this skill, create a new chat in the current project. Do not only write a summary or a temporary handoff file.
+
+Prepare a concise, self-contained first message for the new chat. Include the original ask, decisions and constraints, relevant verified facts, completed work, current state, important paths or links, checks and their outcomes, and unfinished work. Keep details that the next agent needs; do not repeat artifacts that can be referenced by path or URL. Do not include secrets.
+
+If the user provides a focus for the next chat, make it the new chat's primary task. Keep the prior task context that supports that focus, and distinguish facts from assumptions.
+
+List the exact skill references that were used or referenced in this conversation under a "Skills carried forward" section in the first message. Use /name for project or global skills and //name for bundled skills. Do not invent references. The handoff operation copies the current chat's enabled and disabled skill settings and adds a link to the source chat; the listed references preserve explicit skill uses that are not part of those settings.
+
+Choose a short title that describes the focus. Start the new chat by calling context.chat.startHandoff with the title, complete first-message prompt, and skill names. Use context.chat.normalizeTitle to normalize the title. Do not say the new chat started unless the call succeeds.
+
+After success, give the user a markdown link to the new chat using the returned URL. If the launch fails after creating a chat, show the recovery link from the error and state that the first message did not start.

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

@@ -0,0 +1,372 @@
+---
+name: tarsk-agent
+description: >-
+  How to author, edit, and package Tarsk Tool skills: SKILL.md front matter,
+  scripts/{name}.js contract, Agent runtime (context), and export/resolution.
+  Use when creating or modifying a Tool skill, changing a tool
+  description/schema/execute, or asking what context.* APIs provide.
+version: 2.0.1
+when_to_use: >-
+  Before creating or editing any Skill under .agents/skills or cli/bundled-skills
+  that publishes tools, or when changing tool behavior, parameters, or descriptions.
+  Also when a tool repeatedly fails or a goal burned excessive turns/tokens due to
+  tool design (noisy output, missing select, serial multi-hop).
+---
+
+# Agent runtime & Tool skills (`tarsk-agent`)
+
+Read this before creating or editing a Tool skill. Tool skill scripts must not
+import modules (no `import` / `require`). They receive a `context` object (the
+Agent runtime) as the second argument to `execute`. Project scripts that import
+are rejected at load; use only `context.*`.
+
+## When to update a Tool skill
+
+Edit the project Tool skill (usually `.agents/skills/tarsk-<area>/`) when:
+
+- The same tool call fails repeatedly for a fixable reason (bad defaults, weak
+  validation message, schema that invites wrong args, brittle formatting).
+- Reaching the user's goal took excessive turns or tokens because of tool design
+  (dumping huge results instead of `select` / truncation, forcing grep→read
+  loops that belong in `run_js`, descriptions that send the model down a dead path).
+- A description or parameter shape no longer matches how the tool should be used.
+
+Prefer a small change to `description`, `parameters`, or `execute` over teaching
+the model a one-off workaround in chat. After edit, the next tool load picks it
+up. Do not invent host APIs — use `context.*` below.
+
+## Split of responsibility
+
+| Lives in                | Responsibility                                                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Tool skill scripts**  | Tool logic: description, parameters, orchestration, formatting, policy text the agent may edit                                            |
+| **CLI / Agent runtime** | Security and light host: cwd/path checks, permission gates, seatbelt, fetch allowlist, DB/network clients, truncate helpers, job registry |
+
+Prefer implementing behavior in `scripts/{name}.js` using `context` primitives.
+Heavy engines (edit matching, browser, shell spawn) stay behind dedicated
+`context.*` host APIs — never import Node modules or `cli/src`.
+
+### What you can change
+
+| Goal                                 | How                                                                      |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| Change Tool behavior the agent owns  | Edit `execute` / `description` / `parameters` in the Skill script        |
+| Need filesystem/shell/network safely | Call the matching **secure or light** `context.*` API (documented below) |
+
+## Package layout
+
+A Tool skill is a normal Skill whose front matter lists `tools`:
+
+```text
+.agents/skills/my-notes/          # project copy (edit here)
+  SKILL.md
+  scripts/
+    notes.js                      # one file per name in tools:
+```
+
+Tarsk-shipped defaults live under `cli/bundled-skills/tarsk-*`. To change one, **export**
+it into the Project’s `.agents/skills` (`tarsk-improve`’s `ensure-exported.ts`) and
+**edit the project copy** under `.agents/skills/…` so your changes stick. Chat load
+never creates copies — it only **prunes** project copies that still match bundled — so
+export before editing. The `tarsk-` prefix is a shipping convention for export only;
+any Skill with a `tools` array publishes Tools.
+
+### Front matter
+
+```yaml
+---
+name: my-notes # must match the directory name
+description: Short trigger text for humans and skill discovery
+version: 1.0.0 # semver; used by export
+tools:
+  - notes # model-facing Tool name(s)
+# deferred-tools:              # optional; subset of tools → behind tool_search
+#   - notes
+---
+```
+
+- `tools: [name, …]` — required for a Tool skill. Each name needs `scripts/{name}.js`.
+  Add the name here **before** creating the script: the write guard validates only
+  declared Tool scripts, so a file it does not know is an ordinary helper script
+  (it may import modules; it has no `description`/`parameters`/`execute` contract).
+- `deferred-tools` — optional subset of `tools`; omitted means all eager. Prefer deferring
+  rare tools (browser, jobs, images, web, observations, …) so schemas stay out of every
+  request; keep the coding core eager.
+- A deferred tool is reachable only through `tool_search`, which matches a tool's name and
+  `description` — never its `parameters`. Name every capability a model might search for
+  (for example `screenshot`, `capture`) in the script's `description`, or keyword search
+  cannot find the tool and the model concludes the capability does not exist.
+- Host injects a shared `select` parameter for `read` and `bash` at load time — do not
+  duplicate that schema in the Skill script.
+- Not the same as `allowed-tools` (that only restricts which existing Tools a Skill may use).
+- Directory name must equal front matter `name`.
+
+### Script contract
+
+Each `scripts/{name}.js` (or `.ts`) exports:
+
+- `description` — string shown to the model for this Tool
+- `parameters` — JSON Schema object for arguments
+- `execute(args, context, options?)` — returns
+  `{ content: [{ type: "text", text }], details? }`
+  (throw or return an error text on failure)
+
+The Tool **name** comes from the `tools` array, not from inside the file.
+A script not listed in `tools` is an ordinary skill script (`execute_skill_script`),
+not a model Tool.
+
+`options` (third argument): `{ signal?, onUpdate? }` for abort and streaming
+progress.
+
+## Where files live (export & resolution)
+
+1. **Resolution for a run:** Project `.agents/skills/<name>` if present, else
+   bundled `cli/bundled-skills/<name>`. Load never writes. Script imports are
+   cache-busted by mtime so edits apply on the next tool load. Project scripts
+   must not `import`/`require` modules (rejected at load).
+2. **Export (deliberate):** Run `tarsk-improve`’s `ensure-exported.ts` to copy
+   bundled Skills whose names start with `tarsk-` into `.agents/skills`:
+   - missing project copy → copy
+   - same `version` → leave
+   - bundled **major** > project major → overwrite
+   - otherwise (project ahead, or only minor/patch ahead) → leave project copy
+     Chat load never copies. It only **prunes** a project copy that is byte-identical
+     to bundled, so untouched packages never persist in the repo.
+3. **Where edits land:** in the Tarsk checkout the built-ins under
+   `cli/bundled-skills/tarsk-*` _are_ this repo's own files, so
+   `ensure-exported.ts` copies nothing and `.agents/skills/tarsk-*` stays absent —
+   edit `cli/bundled-skills/tarsk-*` directly. In any other repo do not hand-edit
+   `cli/bundled-skills/`; the project export is the edit surface.
+4. Bump `version` in front matter when you intentionally publish a new Skill
+   revision. A major bump on the bundled side can overwrite local copies.
+
+## Enable / disable
+
+- Tool skills are **enabled by default**.
+- Disabling the Skill (thread skill settings) hides every Tool in its `tools` array.
+- Project `disabledTools` still hides individual Tool names.
+- Disabling `tarsk-agent` does not remove Tools; the CLI always injects `context`.
+
+## `context` API
+
+### Identifiers
+
+| Field            | Meaning                           |
+| ---------------- | --------------------------------- |
+| `cwd`            | Working directory for the run     |
+| `projectId`      | Current Project id (may be empty) |
+| `threadId`       | Current Thread id                 |
+| `conversationId` | Current Conversation id           |
+| `messageId`      | Optional message id               |
+| `threadPath`     | Optional Thread checkout path     |
+
+### `context.notes`
+
+Project-scoped durable notes:
+
+- `list()` — note metadata
+- `read(name, offset?)` — paged content, or `null` if missing
+- `write(name, content)` — replace; empty content clears; metadata or `null` when cleared
+- `append(name, content)` — append a record
+- `search(query)` — name and content excerpts
+
+### `context.chat`
+
+- `titleMaxLength` — max characters for a chat title
+- `normalizeTitle(title)` — normalize a model-supplied title for storage
+
+### `context.mcp`
+
+```js
+await context.mcp.connectRemoteServer(
+  { serverName, url, transport: "streamableHttp" | "sse", useOAuth },
+  options,
+);
+// → { serverName, state, tools, authenticated, error? }
+```
+
+Saves and discovers a remote MCP server for the current project. The active run's tool set stays fixed; discovered MCP tools are available on the next message
+in the same conversation. Use the deferred `connect_mcp` Skill instead of calling
+this host API directly from user-facing replies. Never ask for bearer tokens.
+
+### `context.web`
+
+```js
+await context.web.search({ query, numResults, type, includeDomains, excludeDomains, signal });
+```
+
+### `context.email`
+
+```js
+await context.email.sendToSelf({ subject, body });
+// → { status: "sent", to } | { status: "not-signed-in" } | { status: "failed", message }
+```
+
+Sends an email to the signed-in Tarsk account (the auth service resolves the
+recipient from the sign-in token, so the mail can only reach that user's own
+address). The Skill formats every reply, including the signed-out "log in to
+Tarsk" copy.
+
+### `context.util`
+
+```js
+context.util.maxBytes;
+context.util.formatSize(bytes);
+context.util.truncateHead(text, { maxLines, maxBytes });
+context.util.compressFindPaths(paths); // { text, applied, banner }
+context.util.compressGrepContent(lines); // { text, applied, banner }
+context.util.compressGrepCount(lines);
+context.util.compressGrepFiles(lines);
+context.util.compressUnifiedDiffPreservingFootnotes(text); // { text, applied }
+await context.util.withAbort(signal, async (isAborted) => {
+  /* … */
+});
+```
+
+### `context.history`
+
+```js
+context.history.available
+await context.history.search({ query, allConversations?, limit? })
+await context.history.read({ entryId, allConversations?, offset? })
+```
+
+### `context.jobs`
+
+Owner-scoped background jobs (bash `run_in_background`). Kill is a privileged host op.
+
+```js
+context.jobs.available
+context.jobs.list()
+context.jobs.readOutput(jobId, { offsetLines?, limitLines? })
+context.jobs.kill(jobId) // { ok, outcome, status, exitCode } | { ok: false }
+```
+
+### `context.todos`
+
+Thread-scoped todos and progress.txt append:
+
+```js
+await context.todos.list()
+await context.todos.add(descriptions, assignedTo?)
+await context.todos.update(ids, { status?, assignedTo?, passes? })
+await context.todos.remove(ids)
+await context.todos.appendLearnings(text)
+```
+
+### `context.fs`
+
+Secure filesystem (cwd containment). Grow this as more file Tools migrate.
+
+```js
+await context.fs.writeText(path, content, { signal? })
+// → { path, absolutePath, previousBytes, nextBytes, supersession }
+await context.fs.glob(pattern, { path?, limit?, signal? })
+// → { paths, limit, resultLimitReached }
+await context.fs.applyEdit(args, { signal? }) // structured; Skill formats copy
+await context.fs.read(args, { signal?, onUpdate?, toolCallId? })
+// → structured (text/directory/image/unchanged/raw); Skill formats copy
+await context.fs.grep(args, { signal? })
+// → structured rows; Skill formats banners / empty tips / pagination
+```
+
+### `context.shell` / `context.ask` / `context.web.fetch`
+
+```js
+await context.shell.run(args, options)
+// → structured (completed | background | preformatted); Skill formats notices
+context.shell.resolveExit({
+  exitCode, executionCommand, outputText, fullOutput, threadId?,
+}) // soft-success / soft-fail classification (policy stays in host)
+context.ask.normalize(args); // coerce legacy ask_user shapes
+await context.ask.wait(questions, options); // blocking gate + credentials; needs toolCallId
+await context.web.fetch(args, options); // fetch (allowlist gate)
+```
+
+### `context.observations` (DB only)
+
+```js
+context.observations.limits;
+await context.observations.resolveId(rawId);
+await context.observations.fetch(id); // { id, content, toolName } | null
+await context.observations.recordRetrieved(bytes);
+```
+
+Paging and model copy live in the `get_observation` Skill.
+
+### Other host executors
+
+```js
+await context.images.searchAndSave(args, options); // structured; Skill formats
+await context.images.generate(args, options); // structured; Skill formats
+await context.projects.query(args); // structured; Skill formats
+await context.projects.launch(args); // structured; Skill formats
+await context.tasks.query(args); // structured; Skill formats
+await context.browser.run(args, options); // structured payload; Skill formats
+await context.js.run(args, options); // structured ok / trivial_read; Skill formats
+await context.skillsCatalog.read(args); // structured; Skill formats
+await context.skillsCatalog.executeScript(args, options); // structured; Skill formats
+await context.skillsCatalog.readReference(args); // structured; Skill formats
+```
+
+Every shipped Tool skill uses a dedicated API above (or pure script logic).
+`propose_branch` is Slack plan-chat only.
+
+## Worked example (new Tool skill)
+
+`.agents/skills/echo-tool/SKILL.md`:
+
+```yaml
+---
+name: echo-tool
+description: Echoes a message back via a small custom Tool.
+version: 1.0.0
+tools:
+  - echo_message
+---
+# Echo
+
+Publishes `echo_message`. See `tarsk-agent` for the runtime contract.
+```
+
+`.agents/skills/echo-tool/scripts/echo_message.js`:
+
+```js
+export const description =
+  "Echo a short message back to the conversation. Use for smoke-testing Tool skills.";
+
+export const parameters = {
+  type: "object",
+  properties: {
+    message: { type: "string", description: "Text to echo" },
+  },
+  required: ["message"],
+};
+
+export async function execute(args, context) {
+  const text = String(args.message ?? "");
+  return {
+    content: [{ type: "text", text: `echo (${context.cwd}): ${text}` }],
+    details: undefined,
+  };
+}
+```
+
+### Wrapping a host Tool (change description / formatting)
+
+`.agents/skills/tarsk-bash/scripts/bash.js` (project override after export):
+
+```js
+export const description = "/* your revised guidance for the model */";
+
+export const parameters = {/* keep or tighten the JSON Schema */};
+
+export async function execute(args, context, options) {
+  const structured = await context.shell.run(args, options);
+  // Format completed / background / preformatted + resolveExit — see bundled bash.js
+  // …
+}
+```
+
+After editing a project Tool skill, the next run reload picks it up (no restart
+required beyond the next tool load for that chat).

package/dist/bundled-skills/tarsk-ask-user/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: tarsk-ask-user
+description: >-
+  Tarsk Tool skill publishing: ask_user.
+version: 2.0.0
+tools:
+  - ask_user
+disable-model-invocation: true
+---
+
+# tarsk-ask-user
+
+Publishes: ask_user.
+
+Question policy text and answer formatting live in `scripts/ask_user.js`.
+
+Host (`context.ask`): `normalize` (legacy arg coercion) and `wait` (blocking
+gate + credential store). Secrets never return to the Skill.

package/dist/bundled-skills/tarsk-ask-user/scripts/ask_user.js

@@ -0,0 +1,101 @@
+/**
+ * ask_user — question policy + result formatting in the Skill.
+ * Host: context.ask.normalize / wait (blocking gate + credential store).
+ */
+
+export const description =
+  "Ask the user for clarification, confirmation, or a decision. Pass `questions` (all answered in one call). Options: `{ label, description }`; recommended first with `(Recommended)`; no `Other` (UI provides custom). Use `multiple: true` when needed. For HTTPS git auth failures, use `credential: { host }` (never ask for a token in chat or put one in a command).";
+
+export const parameters = {
+  type: "object",
+  properties: {
+    questions: {
+      minItems: 1,
+      type: "array",
+      items: {
+        type: "object",
+        required: ["question"],
+        properties: {
+          question: {
+            description:
+              "Clear, specific question to clarify requirements, confirm decisions, or gather preferences.",
+            type: "string",
+          },
+          header: {
+            description: "Optional short UI title above the question.",
+            type: "string",
+          },
+          options: {
+            type: "array",
+            items: {
+              type: "object",
+              required: ["label", "description"],
+              properties: {
+                label: { type: "string" },
+                description: {
+                  description: "Secondary text for this option; use an empty string when none.",
+                  type: "string",
+                },
+              },
+            },
+          },
+          multiple: {
+            description: "Allow multiple selections. Defaults to false.",
+            type: "boolean",
+          },
+          credential: {
+            description:
+              "Collect a Git username and token for this host in a secure dialog. The secret is stored globally for all projects and never shown to you.",
+            type: "object",
+            required: ["host"],
+            properties: {
+              host: {
+                description: 'HTTPS Git host that needs a credential, e.g. "github.com".',
+                type: "string",
+              },
+            },
+          },
+        },
+      },
+    },
+    question: {
+      description: "Legacy single-question form. Prefer `questions`.",
+      type: "string",
+    },
+    options: {
+      description: "Legacy string choices for the single question.",
+      type: "array",
+      items: { type: "string" },
+    },
+    context: {
+      description: "Legacy brief context for the single question.",
+      type: "string",
+    },
+  },
+};
+
+function answerText(answer) {
+  return Array.isArray(answer) ? answer.join(", ") : answer;
+}
+
+/** Format Q→A for the model; edit this to change turn shape / token use. */
+function formatAskUserResult(questions, answers) {
+  const lines = questions.map(function mapQuestion(question, i) {
+    const answer = answers[i] ?? "";
+    if (i === 0 && questions.length === 1) {
+      return answerText(answer);
+    }
+    return `${i + 1}. ${question.question}\n   Answer: ${answerText(answer)}`;
+  });
+  return lines.join("\n");
+}
+
+/** @param {Record<string, unknown>} args @param {import("../../../../src/tools/agent-runtime/types.js").AgentRuntime} context @param {{ signal?: AbortSignal, toolCallId?: string }} [options] */
+export async function execute(args, context, options) {
+  const questions = context.ask.normalize(args);
+  const answers = await context.ask.wait(questions, options);
+  return {
+    content: [{ type: "text", text: formatAskUserResult(questions, answers) }],
+    details: undefined,
+  };
+}

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

@@ -0,0 +1,17 @@
+---
+name: tarsk-bash
+description: >-
+  Tarsk Tool skill publishing: bash.
+version: 3.1.2
+tools:
+  - bash
+disable-model-invocation: true
+---
+
+# tarsk-bash
+
+Publishes: bash.
+
+Truncation / background / ignored-flag copy in `scripts/bash.js`. Host
+`context.shell.run` returns structured capture (permissions + seatbelt + exec +
+prepare). Exit soft-success classification via `context.shell.resolveExit`.