tarsk 0.6.87 → 0.6.88

package/dist/bundled-skills/tarsk-connect-mcp/scripts/connect_mcp.js

@@ -0,0 +1,119 @@
+export const description =
+  "Connect a remote MCP server during this conversation. Ask for its name, URL, HTTP transport, and whether it needs OAuth; save it to the project, sign in if needed, and discover its tools. The tools are available on the next message in this conversation.";
+
+export const parameters = {
+  type: "object",
+  properties: {},
+};
+
+const questions = [
+  {
+    header: "Server name",
+    question: "What name should I use for this MCP server in the project?",
+  },
+  {
+    header: "Server URL",
+    question:
+      "What is the remote MCP server URL? Do not include credentials, tokens, or query parameters in the URL.",
+  },
+  {
+    header: "Transport",
+    question: "Which HTTP transport does this MCP server use?",
+    options: [
+      {
+        label: "Streamable HTTP (Recommended)",
+        description: "Use the current MCP HTTP transport.",
+      },
+      { label: "Server-Sent Events (SSE)", description: "Use the legacy SSE transport." },
+    ],
+  },
+  {
+    header: "Sign-in",
+    question: "Does this MCP server require browser-based OAuth sign-in?",
+    options: [
+      { label: "No OAuth", description: "Connect without starting a sign-in flow." },
+      { label: "OAuth", description: "Open the server's sign-in page in your browser." },
+    ],
+  },
+];
+
+function answerText(answer) {
+  return Array.isArray(answer) ? (answer[0] ?? "") : (answer ?? "");
+}
+
+function parseAnswers(answers) {
+  const serverName = answerText(answers[0]).trim();
+  const url = answerText(answers[1]).trim();
+  if (!serverName || !url) return null;
+  const transportAnswer = answerText(answers[2]);
+  const oauthAnswer = answerText(answers[3]);
+  return {
+    serverName,
+    url,
+    transport: transportAnswer.toLowerCase().includes("sse") ? "sse" : "streamableHttp",
+    useOAuth: oauthAnswer.toLowerCase() === "oauth",
+  };
+}
+
+function textResult(text) {
+  return { content: [{ type: "text", text }], details: undefined };
+}
+
+function formatConnectedResult(result) {
+  if (result.state !== "ok") {
+    return (
+      "Saved " +
+      result.serverName +
+      ", but tool discovery returned " +
+      result.state +
+      ": " +
+      (result.error ?? "no details") +
+      ". Check the URL, transport, and sign-in settings."
+    );
+  }
+  if (result.tools.length === 0) {
+    return (
+      "Connected to " +
+      result.serverName +
+      ". It did not report any tools. The server configuration is saved in this project."
+    );
+  }
+  return formatDiscoveredTools(result);
+}
+
+function formatDiscoveredTools(result) {
+  const authText = result.authenticated ? " and completed OAuth sign-in" : "";
+  return (
+    "Connected to " +
+    result.serverName +
+    authText +
+    ". Discovered tools: " +
+    result.tools.join(", ") +
+    ". The tool set is fixed for this run, so these tools will be available on your next message in this conversation. Then search for " +
+    result.serverName +
+    " and use the matching tool."
+  );
+}
+
+async function connectAndFormat(context, input, options) {
+  try {
+    const result = await context.mcp.connectRemoteServer(input, options);
+    return textResult(formatConnectedResult(result));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return textResult("Could not connect to " + input.serverName + ": " + message);
+  }
+}
+
+/** @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) {
+  void args;
+  const answers = await context.ask.wait(questions, options);
+  const input = parseAnswers(answers);
+  if (!input) {
+    return textResult(
+      "Connection cancelled. A server name and URL are required; no configuration was saved.",
+    );
+  }
+  return connectAndFormat(context, input, options);
+}

package/dist/bundled-skills/tarsk-create-project/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: tarsk-create-project
+description: >-
+  Create a web application from the scaffold templates shown in Tarsk Create Project.
+  Use this when the user asks to create a new scaffolded application or project.
+version: 1.0.0
+tools:
+  - create_project
+deferred-tools:
+  - create_project
+disable-model-invocation: true
+---
+
+# Create a project
+
+This skill runs only when the user invokes it or explicitly requests it. Guide the user through creating a scaffolded web application with the same template catalog and project creation path as the Create Project UI.
+
+1. Call create_project with action list_templates. Use only the returned template type and variation names. Do not invent options.
+2. Use ask_user to ask which application type they want, unless they already named a type that matches an available option. Show the available types and short descriptions.
+3. Use ask_user to ask which variation they want within that type, unless they already chose one. Show only variations for that type.
+4. Use ask_user to ask for the project name, unless they already provided one.
+5. Create the project with the selected template ID and name. Use Bun as the package manager unless the user asks for another supported manager. Do not ask for a second confirmation after the user has provided these choices.
+6. Report success only after the tool confirms it. If it returns an error or cancellation, report that result and do not claim the project exists.
+
+Do not use this workflow for cloning a repository, opening an existing folder, or creating a blank folder project. Those are separate Create Project UI modes.

package/dist/bundled-skills/tarsk-create-project/scripts/__tests__/create_project.test.js

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { execute } from "../create_project.js";
+
+function contextWithProjects(projects) {
+  return { projects };
+}
+
+void test("lists only the host scaffold catalog", async () => {
+  const calls = { list: 0, create: 0 };
+  const context = contextWithProjects({
+    async listScaffoldTemplates() {
+      calls.list += 1;
+      return [
+        {
+          id: "react-starter",
+          typeName: "React",
+          variationName: "Starter",
+          description: "React app",
+        },
+      ];
+    },
+    async createScaffoldProject() {
+      calls.create += 1;
+      return { ok: true, projectId: "project-1", projectName: "Demo", threadId: "thread-1" };
+    },
+  });
+
+  const result = await execute({ action: "list_templates" }, context);
+
+  assert.deepEqual(JSON.parse(result.content[0].text), {
+    templates: [
+      {
+        id: "react-starter",
+        typeName: "React",
+        variationName: "Starter",
+        description: "React app",
+      },
+    ],
+  });
+  assert.deepEqual(calls, { list: 1, create: 0 });
+});
+
+void test("creates the chosen template with the default package manager", async () => {
+  const calls = [];
+  const options = { signal: new AbortController().signal };
+  const context = contextWithProjects({
+    async listScaffoldTemplates() {
+      return [];
+    },
+    async createScaffoldProject(input, receivedOptions) {
+      calls.push({ input, receivedOptions });
+      return { ok: true, projectId: "project-1", projectName: "Demo", threadId: "thread-1" };
+    },
+  });
+
+  const result = await execute(
+    { action: "create", projectName: " Demo ", templateId: "react-starter" },
+    context,
+    options,
+  );
+
+  assert.deepEqual(calls, [
+    {
+      input: { projectName: "Demo", templateId: "react-starter", packageManager: "bun" },
+      receivedOptions: options,
+    },
+  ]);
+  assert.deepEqual(JSON.parse(result.content[0].text), {
+    ok: true,
+    projectName: "Demo",
+    projectId: "project-1",
+    threadId: "thread-1",
+  });
+});
+
+void test("rejects incomplete creation requests without creating a project", async () => {
+  let createCount = 0;
+  const context = contextWithProjects({
+    async listScaffoldTemplates() {
+      return [];
+    },
+    async createScaffoldProject() {
+      createCount += 1;
+      return { ok: true, projectId: "project-1", projectName: "Demo", threadId: "thread-1" };
+    },
+  });
+
+  const result = await execute({ action: "create", projectName: "Demo" }, context);
+
+  assert.match(result.content[0].text, /templateId is required/i);
+  assert.equal(createCount, 0);
+});

package/dist/bundled-skills/tarsk-create-project/scripts/create_project.js

@@ -0,0 +1,88 @@
+/** Create Project UI scaffold workflow, exposed only by explicit skill invocation. */
+
+export const description =
+  "List Tarsk web-app scaffold types and variations, or create a project from a selected built-in template. Use list_templates first. Creating a project runs the selected template and package-manager setup commands.";
+
+export const parameters = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      enum: ["list_templates", "create"],
+      description:
+        "List available templates, or create one after the user chooses its type, variation, and project name.",
+    },
+    projectName: {
+      type: "string",
+      description: "Required for create. The project name the user chose.",
+    },
+    templateId: {
+      type: "string",
+      description: "Required for create. The id of a template returned by list_templates.",
+    },
+    packageManager: {
+      type: "string",
+      enum: ["bun", "npm", "pnpm", "yarn"],
+      description: "Package manager for the scaffold and dependency installation. Defaults to bun.",
+    },
+  },
+  required: ["action"],
+  additionalProperties: false,
+};
+
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+function resolveCreateInput(args) {
+  if (typeof args.projectName !== "string" || !args.projectName.trim()) {
+    return { error: "Error: projectName is required for create" };
+  }
+  if (typeof args.templateId !== "string" || !args.templateId.trim()) {
+    return { error: "Error: templateId is required for create" };
+  }
+  return {
+    input: {
+      projectName: args.projectName.trim(),
+      templateId: args.templateId.trim(),
+      packageManager: args.packageManager ?? "bun",
+    },
+  };
+}
+
+function formatCreateResult(result) {
+  if (!result.ok) return textResult("Project creation was cancelled.");
+  return textResult(
+    JSON.stringify({
+      ok: true,
+      projectName: result.projectName,
+      projectId: result.projectId,
+      threadId: result.threadId,
+    }),
+  );
+}
+
+function formatError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return textResult("Error: " + message);
+}
+
+export async function execute(args, context, options) {
+  if (args.action === "list_templates") {
+    try {
+      const templates = await context.projects.listScaffoldTemplates();
+      return textResult(JSON.stringify({ templates }));
+    } catch (error) {
+      return formatError(error);
+    }
+  }
+  if (args.action !== "create") return textResult("Error: action must be list_templates or create");
+  const resolved = resolveCreateInput(args);
+  if (resolved.error) return textResult(resolved.error);
+  try {
+    const result = await context.projects.createScaffoldProject(resolved.input, options);
+    return formatCreateResult(result);
+  } catch (error) {
+    return formatError(error);
+  }
+}

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

@@ -0,0 +1,18 @@
+---
+name: tarsk-edit
+description: >-
+  Tarsk Tool skill publishing: edit.
+version: 3.0.1
+tools:
+  - edit
+disable-model-invocation: true
+---
+
+# tarsk-edit
+
+Publishes: edit.
+
+Success / skip / after-proof copy lives in `scripts/edit.js` (tune for tokens).
+
+Host `context.fs.applyEdit`: path lock, cwd containment, hunk matching, write,
+structured proof lines + after-window body.

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

@@ -0,0 +1,118 @@
+/**
+ * edit — model-facing copy lives here (malleable).
+ * Host: context.fs.applyEdit (path lock, cwd check, hunk apply).
+ */
+
+export const description =
+  "Replace exact text (unique unless replaceAll/line/occurrenceIndex). oldText and newText must differ. Prefer in-place edits over insert-before-anchor; insert retries duplicate lines and are skipped when already present. To append, copy the last unique lines into oldText (never empty oldText or newText alone); use write only to replace the entire file. On an ambiguous match, choose a listed site with occurrenceIndex or line — never both (do not assume the first). After apply, a numbered after-window (~30 lines) surrounds the change; do not re-read the file unless the next hunk is outside that window. Parallelize independent files. Concurrent edits to the same path are serialized; prefer one replacements call.";
+
+export const parameters = {
+  type: "object",
+  required: ["path"],
+  properties: {
+    path: { type: "string" },
+    oldText: { type: "string" },
+    newText: { type: "string" },
+    replaceAll: { type: "boolean" },
+    replacements: {
+      minItems: 1,
+      description: "batch hunks, applied in order",
+      type: "array",
+      items: {
+        type: "object",
+        required: ["oldText", "newText"],
+        properties: {
+          oldText: { type: "string" },
+          newText: { type: "string" },
+          replaceAll: { type: "boolean" },
+          line: { description: "1-based start line", minimum: 1, type: "integer" },
+          occurrenceIndex: {
+            description: "1-based; first match is 1",
+            minimum: 1,
+            type: "integer",
+          },
+        },
+      },
+    },
+    line: { description: "1-based start line", minimum: 1, type: "integer" },
+    occurrenceIndex: {
+      description: "1-based; first match is 1",
+      minimum: 1,
+      type: "integer",
+    },
+  },
+};
+
+/** Format apply outcomes for the model — edit to tune tokens / next-hunk guidance. */
+function formatEditApplyForModel(outcome) {
+  if (outcome.status === "aborted") {
+    return { content: [], details: undefined };
+  }
+  if (outcome.status === "reverted_tool_skill_load_failed") {
+    return {
+      content: [{ type: "text", text: outcome.message }],
+      details: undefined,
+      isError: true,
+    };
+  }
+  if (outcome.status === "unchanged_already_applied") {
+    if (outcome.proved) {
+      const block = outcome.afterProofLines.join("\n");
+      const text = block
+        ? `already applied (skipped): ${outcome.path}\n${block}`
+        : `already applied (skipped): ${outcome.path}`;
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          diff: "",
+          replacementCount: 0,
+          afterProof: outcome.afterProofLines,
+          proved: true,
+        },
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `already applied (skipped): ${outcome.path}, but newText is not on disk ` +
+            `(${JSON.stringify(outcome.missing)}). File was not changed. Last lines:\n${outcome.fileTail}\n` +
+            `To append, copy the last unique lines into oldText and put those same lines plus the suffix in newText.`,
+        },
+      ],
+      details: {
+        diff: "",
+        replacementCount: 0,
+        afterProof: outcome.afterProofLines,
+        proved: false,
+      },
+    };
+  }
+  const hunkLabel = outcome.hunkCount === 1 ? "text" : `${outcome.hunkCount} hunks`;
+  const snapNotice = outcome.lineSnaps.length > 0 ? `\n${outcome.lineSnaps.join("\n")}` : "";
+  let summary = `Successfully replaced ${hunkLabel} in ${outcome.path}.${snapNotice}`;
+  if (outcome.proved) {
+    const block = outcome.afterProofLines.join("\n");
+    if (block) summary = `${summary}\n${block}`;
+  } else {
+    summary =
+      `${summary}\n` +
+      `after-proof warning: could not find ${JSON.stringify(outcome.missing)} as a contiguous substring; ` +
+      `the file was still written. Do not re-apply the same hunk.`;
+  }
+  let text = outcome.afterWindow ? `${summary}\n${outcome.afterWindow}` : summary;
+  if (outcome.syntaxDiagnostics) {
+    text = `${text}\n\n${outcome.syntaxDiagnostics}`;
+  }
+  return {
+    content: [{ type: "text", text }],
+    details: outcome.details,
+  };
+}
+
+/** @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 outcome = await context.fs.applyEdit(args, { signal: options?.signal });
+  return formatEditApplyForModel(outcome);
+}

package/dist/bundled-skills/tarsk-execute-skill-script/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: tarsk-execute-skill-script
+description: >-
+  Tarsk Tool skill publishing: execute_skill_script.
+version: 2.0.0
+tools:
+  - execute_skill_script
+deferred-tools:
+  - execute_skill_script
+disable-model-invocation: true
+---
+
+# tarsk-execute-skill-script
+
+Publishes: execute_skill_script.
+
+STDOUT/STDERR / miss / cancel / timeout copy in
+`scripts/execute_skill_script.js`. Host `context.skillsCatalog.executeScript`
+returns structured capture (permission gate + sandbox + spawn).

package/dist/bundled-skills/tarsk-execute-skill-script/scripts/execute_skill_script.js

@@ -0,0 +1,77 @@
+/**
+ * execute_skill_script — STDOUT/STDERR / miss copy in the Skill; host holds
+ * permission gate, sandbox, and spawn.
+ */
+
+export const description =
+  "Execute a script from an activated skill. Skills provide executable scripts in their scripts/ directory.";
+
+export const parameters = {
+  type: "object",
+  required: ["skillName", "scriptName"],
+  properties: {
+    skillName: {
+      description: "Name of the skill",
+      type: "string",
+    },
+    scriptName: {
+      description: "Name of the script to execute (without path)",
+      type: "string",
+    },
+    args: {
+      description: "Arguments to pass to the script",
+      type: "array",
+      items: {
+        type: "string",
+      },
+    },
+    timeout: {
+      description: "Timeout in seconds (default: 30)",
+      type: "number",
+    },
+  },
+};
+
+function formatOk(result) {
+  const parts = [];
+  if (result.stdout) {
+    parts.push(`STDOUT:\n${result.stdout}`);
+  }
+  if (result.stderr) {
+    parts.push(`STDERR:\n${result.stderr}`);
+  }
+  parts.push(`Exit code: ${result.exitCode}`);
+  return `${parts.join("\n")}\n`;
+}
+
+function formatError(result) {
+  switch (result.reason) {
+    case "skill_not_found":
+      return `Skill not found: ${result.skillName}. Available skills: ${result.available.join(", ")}`;
+    case "no_scripts":
+      return `Skill '${result.skillName}' has no scripts directory`;
+    case "invalid_path":
+      return `Invalid script path: ${result.scriptName}`;
+    case "script_not_found":
+      return result.available.length > 0
+        ? `Script '${result.scriptName}' not found in skill '${result.skillName}'. Available scripts: ${result.available.join(", ")}`
+        : `Script '${result.scriptName}' not found in skill '${result.skillName}'`;
+    case "cancelled":
+      return "Failed to execute script: Script execution cancelled";
+    case "timeout":
+      return `Failed to execute script: Script execution timed out after ${result.timeoutSeconds}s`;
+    case "execute_error":
+      return `Failed to execute script: ${result.message}`;
+    default:
+      return "Failed to execute script";
+  }
+}
+
+/** @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 result = await context.skillsCatalog.executeScript(args, options);
+  return {
+    content: [{ type: "text", text: result.ok ? formatOk(result) : formatError(result) }],
+    details: undefined,
+  };
+}

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

@@ -0,0 +1,18 @@
+---
+name: tarsk-fetch
+description: >-
+  Tarsk Tool skill publishing: fetch.
+version: 2.0.0
+tools:
+  - fetch
+deferred-tools:
+  - fetch
+disable-model-invocation: true
+---
+
+# tarsk-fetch
+
+Publishes: fetch.
+
+Result JSON in `scripts/fetch.js`. Host `context.web.fetch` (allowlist + extract).
+Progress notices still emit from the host during the request.

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

@@ -0,0 +1,38 @@
+/**
+ * fetch — progress/result JSON copy in the Skill; host holds allowlist + extract.
+ */
+
+export const description =
+  "Fetch public HTTP(S) URL; extract/summarize via prompt. Read-only—not for auth/private pages (use MCP/browser). Unknown domains need permission; docs sites pre-approved.";
+
+export const parameters = {
+  type: "object",
+  required: ["url", "prompt"],
+  properties: {
+    url: {
+      description: "HTTP(S) URL to fetch",
+      type: "string",
+    },
+    prompt: {
+      description: "What to extract or summarize",
+      type: "string",
+    },
+  },
+};
+
+/** @param {Record<string, unknown>} args @param {import("../../../../src/tools/agent-runtime/types.js").AgentRuntime} context @param {{ signal?: AbortSignal, onUpdate?: Function, toolCallId?: string }} [options] */
+export async function execute(args, context, options) {
+  const result = await context.web.fetch(args, options);
+  if (result.status === "aborted") {
+    return { content: [], details: undefined };
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ ...result.details, result: result.result }),
+      },
+    ],
+    details: result.details,
+  };
+}

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

@@ -0,0 +1,16 @@
+---
+name: tarsk-find
+description: >-
+  Tarsk Tool skill publishing: find.
+version: 2.0.0
+tools:
+  - find
+disable-model-invocation: true
+---
+
+# tarsk-find
+
+Publishes: find.
+
+Formatting lives in `scripts/find.js`. Secure glob (cwd check, home denial,
+ignore list) is `context.fs.glob`; listing compression is `context.util`.