@tiptask/runner 0.7.0 → 0.8.0

package/README.md

@@ -23,10 +23,31 @@ of kind External. The key appears one time only, at creation.
 **2. Enable MCP** for the project, in Settings, MCP Server. MCP is off by default. The
 agent reads the issue and writes its result through it.
 
-**3. Give the coding agent the address of that server.** Claude Code, Oh My Pi, and Pi
+**3. Start the runner** in the folder the coding agent should work in:
+
+```bash
+npx -y @tiptask/runner
+```
+
+Without a `tiptask-runner.json` there, the runner asks for the instance URL, the key, the
+coding agent and the working folder. It checks that the URL is the TipTask API, and takes
+`<url>/api` when the API is there. It marks the coding agents that are installed. Then
+it writes `tiptask-runner.json`, writes `.mcp.json` for Claude Code, Pi and Oh My Pi, and
+starts. Run `npx -y @tiptask/runner init` to answer the questions again.
+
+The project shows the agent as online in a few seconds. Delegate an issue to the agent,
+or mention it in a comment. The task then starts in your terminal.
+
+`tiptask-runner.json` holds the key. Keep it out of git.
+
+### The same setup by hand
+
+A runner that a service manager starts has no terminal to ask in, so write the two files
+yourself.
+
+**Give the coding agent the address of the MCP server.** Claude Code, Oh My Pi, and Pi
 (through `pi-mcp-adapter`) read `.mcp.json` from the folder they run in. For the other
-CLIs, see
-[Coding agent setup](../../docs/runner.md).
+CLIs, see [Coding agent setup](https://gitlab.tma.com.vn/young-turtles/tiptask/-/blob/develop/docs/runner.md).
 
 ```json
 {
@@ -43,7 +64,7 @@ CLIs, see
 The runner sets `TIPTASK_API_KEY` for the command that it starts. The key thus stays in
 one file.
 
-**4. Write `tiptask-runner.json`** in the same folder:
+**Write `tiptask-runner.json`** in the same folder:
 
 ```json
 {
@@ -53,15 +74,6 @@ one file.
 }
 ```
 
-**5. Start it:**
-
-```bash
-npx -y @tiptask/runner
-```
-
-The project shows the agent as online in a few seconds. Delegate an issue to the agent,
-or mention it in a comment. The task then starts in your terminal.
-
 ## Which coding agent
 
 `agent` names a CLI that the runner knows. The runner then builds the command itself: the
@@ -78,7 +90,7 @@ flags for an unattended run, and the session resume. Every preset keeps a chat s
 | `omp`         | Oh My Pi           |
 
 Each preset needs the CLI's own MCP config.
-[Coding agent setup](../../docs/runner.md) holds
+[Coding agent setup](https://gitlab.tma.com.vn/young-turtles/tiptask/-/blob/develop/docs/runner.md) holds
 that file, and the notes for each CLI.
 
 `--agent` on the command line has priority over the file, except over an `agents` entry
@@ -232,8 +244,10 @@ example `http://localhost:4000`.
 
 ## Settings
 
-The runner reads `./tiptask-runner.json`. For a different file, give the path as an
-argument or in `TIPTASK_RUNNER_CONFIG`:
+The runner reads `./tiptask-runner.json`. Without it, and without `TIPTASK_URL` or
+`TIPTASK_API_KEY`, the runner asks the setup questions in a terminal and stops with an
+example file elsewhere. For a different file, give the path as an argument or in
+`TIPTASK_RUNNER_CONFIG`:
 
 ```bash
 npx -y @tiptask/runner /path/to/config.json

package/dist/cli.js

@@ -15,6 +15,9 @@ class RequestError extends Error {
   }
 }
 
+class NotApiError extends Error {
+}
+
 class Client {
   config;
   constructor(config) {
@@ -36,6 +39,9 @@ class Client {
     if (!res.ok) {
       throw new RequestError(res.status, `POST ${path} failed with ${res.status}: ${(await res.text()).slice(0, 200)}`);
     }
+    if (res.headers.get("content-type")?.includes("text/html")) {
+      throw new NotApiError(`${this.config.url} answered with a web page, not the TipTask API — set url to ` + `the API's address, often ${this.config.url}/api`);
+    }
     return res;
   }
   async claim() {
@@ -537,6 +543,165 @@ function startListener(port, agents, log) {
   });
 }
 
+// src/setup.ts
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+var DOCS_URL = "https://gitlab.tma.com.vn/young-turtles/tiptask/-/blob/develop/docs/runner.md";
+var AGENTS = {
+  claude: { label: "Claude Code", anchor: "claude-code" },
+  codex: { label: "Codex CLI", anchor: "codex" },
+  opencode: { label: "opencode", anchor: "opencode" },
+  antigravity: { label: "Antigravity CLI", anchor: "antigravity-cli" },
+  copilot: { label: "GitHub Copilot CLI", anchor: "github-copilot-cli" },
+  pi: { label: "Pi", anchor: "pi" },
+  omp: { label: "Oh My Pi", anchor: "oh-my-pi" }
+};
+var READS_MCP_JSON = ["claude", "pi", "omp"];
+var EXAMPLE = `{
+  "url": "https://your-tiptask-instance",
+  "apiKey": "the agent's key from Settings, AI agents",
+  "agent": "claude"
+}`;
+function needsSetup(configPath) {
+  return !existsSync(configPath) && !process.env.TIPTASK_API_KEY && !process.env.TIPTASK_URL;
+}
+function missingConfigMessage(configPath) {
+  return [
+    `no config found at ${resolve(configPath)}`,
+    "",
+    "Run `npx -y @tiptask/runner init` in a terminal, or write tiptask-runner.json:",
+    "",
+    EXAMPLE,
+    "",
+    `agent is one of: ${PRESET_NAMES.join(", ")}`,
+    `Guide: ${DOCS_URL}`
+  ].join(`
+`);
+}
+function installedAgents(path = process.env.PATH ?? "", platform = process.platform) {
+  const dirs = path.split(platform === "win32" ? ";" : ":").filter(Boolean);
+  const exts = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+  return PRESET_NAMES.filter((name) => dirs.some((dir) => exts.some((ext) => existsSync(join(dir, PRESETS[name].bin + ext)))));
+}
+async function apiUrlOf(url) {
+  for (const candidate of [url, `${url}/api`]) {
+    try {
+      const res = await fetch(`${candidate}/agent-runs/claim`, {
+        method: "POST",
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (res.headers.get("content-type")?.includes("application/json"))
+        return candidate;
+    } catch {}
+  }
+  return;
+}
+async function runSetup(configPath, options = {}, io = { input: process.stdin, output: process.stdout }) {
+  const rl = createInterface({ input: io.input, terminal: false });
+  const lines = rl[Symbol.asyncIterator]();
+  const say = (text = "") => io.output.write(`${text}
+`);
+  const ask = async (question, fallback = "") => {
+    io.output.write(fallback ? `? ${question} (${fallback}): ` : `? ${question}: `);
+    const next = await lines.next();
+    if (next.done)
+      throw new Error("setup was cancelled");
+    return next.value.trim() || fallback;
+  };
+  const yes = async (question, fallback) => /^y/i.test(await ask(`${question} (${fallback ? "Y/n" : "y/N"})`, fallback ? "y" : "n"));
+  try {
+    const file = resolve(configPath);
+    if (existsSync(file)) {
+      if (!await yes(`${file} exists. Replace it?`, false))
+        return false;
+    } else {
+      say(`TipTask runner setup — no tiptask-runner.json in ${dirname(file)}`);
+    }
+    say();
+    let url = "";
+    while (!url) {
+      const answer = (await ask("TipTask URL", "http://localhost:3000")).replace(/\/+$/, "");
+      if (!/^https?:\/\/\S+$/.test(answer))
+        continue;
+      const api = await apiUrlOf(answer);
+      if (api && api !== answer)
+        say(`  The TipTask API answers at ${api} — using that`);
+      if (api)
+        url = api;
+      else if (await yes(`No TipTask API answered at ${answer}. Use it anyway?`, false)) {
+        url = answer;
+      }
+    }
+    let apiKey = "";
+    while (!apiKey)
+      apiKey = await ask("Agent key (Settings, AI agents, your External agent's key)");
+    const installed = installedAgents(options.path);
+    say("? Coding agent:");
+    PRESET_NAMES.forEach((name, i) => {
+      const mark = installed.includes(name) ? "✓ installed" : "";
+      say(`    ${i + 1}) ${name.padEnd(12)} ${AGENTS[name].label.padEnd(19)} ${mark}`.trimEnd());
+    });
+    const preferred = PRESET_NAMES.find((name) => name === options.agent) ?? installed[0];
+    const fallback = String(preferred ? PRESET_NAMES.indexOf(preferred) + 1 : 1);
+    let agent;
+    while (!agent) {
+      const answer = await ask("  Choose", fallback);
+      agent = PRESET_NAMES.find((name, i) => answer === name || answer === String(i + 1));
+    }
+    let cwd = "";
+    while (!existsSync(cwd)) {
+      const answer = await ask("Folder the agent works in", process.cwd());
+      cwd = resolve(answer.replace(/^~(?=$|[\\/])/, homedir()));
+    }
+    say();
+    const config = {
+      url,
+      apiKey,
+      agent,
+      ...cwd === dirname(file) ? {} : { cwd }
+    };
+    await writeFile(file, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+    say(`✓ Wrote ${file} — it holds your key, keep it out of git`);
+    const mcpFile = join(cwd, ".mcp.json");
+    if (!READS_MCP_JSON.includes(agent)) {
+      say(`  ${AGENTS[agent].label} needs the TipTask MCP server in its own config:`);
+      say(`  ${DOCS_URL}#${AGENTS[agent].anchor}`);
+    } else if (existsSync(mcpFile)) {
+      say(`  ${mcpFile} exists — add the tiptask server to it: ${DOCS_URL}#${AGENTS[agent].anchor}`);
+    } else {
+      const mcp = {
+        mcpServers: {
+          tiptask: {
+            type: "http",
+            url: `${url}/mcp`,
+            headers: { Authorization: "Bearer ${TIPTASK_API_KEY}" }
+          }
+        }
+      };
+      await writeFile(mcpFile, `${JSON.stringify(mcp, null, 2)}
+`);
+      say(`✓ Wrote ${mcpFile} — ${AGENTS[agent].label} reads the TipTask MCP server from it`);
+    }
+    if (agent === "pi")
+      say("  Pi reads it through an extension: pi install npm:pi-mcp-adapter");
+    if (!installed.includes(agent)) {
+      say(`  ${PRESETS[agent].bin} is not on PATH — install and sign in to it first`);
+    }
+    say("  Enable MCP for the project in TipTask: Settings, MCP Server.");
+    say();
+    const start = await yes("Start the runner now?", true);
+    if (!start)
+      say("Start it later with: npx -y @tiptask/runner");
+    return start;
+  } finally {
+    rl.close();
+  }
+}
+
 // src/agui.ts
 var FLUSH_CHARS = 1500;
 var DELTA_LIMIT = 12000;
@@ -1137,9 +1302,9 @@ async function execute(config, task, opts = {}) {
   });
   child.stdin.on("error", () => {});
   child.stdin.end(stdinText(preset, task));
-  const exited = new Promise((resolve, reject) => {
+  const exited = new Promise((resolve2, reject) => {
     child.on("error", reject);
-    child.on("close", (exitCode, exitSignal) => resolve({ code: exitCode, signal: exitSignal }));
+    child.on("close", (exitCode, exitSignal) => resolve2({ code: exitCode, signal: exitSignal }));
   });
   let code;
   let signal;
@@ -1340,6 +1505,8 @@ async function drain(state, log2, concurrency, take, run, onEmpty) {
     try {
       item = await take();
     } catch (err) {
+      if (err instanceof NotApiError)
+        throw err;
       if (err instanceof RequestError && (err.status === 401 || err.status === 403))
         throw err;
       log2(`claim failed: ${String(err)}`);
@@ -1441,8 +1608,16 @@ function settle(name, work) {
   });
 }
 async function main() {
-  const cli = parseArgv(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  const init = argv[0] === "init";
+  const cli = parseArgv(init ? argv.slice(1) : argv);
   const configPath = cli.configPath ?? process.env.TIPTASK_RUNNER_CONFIG ?? "./tiptask-runner.json";
+  if (init || needsSetup(configPath)) {
+    if (!process.stdin.isTTY)
+      throw new Error(missingConfigMessage(configPath));
+    if (!await runSetup(configPath, { agent: cli.agent }))
+      return;
+  }
   const configs = await loadConfig(configPath, {
     agent: cli.agent,
     args: cli.args,
@@ -1452,7 +1627,7 @@ async function main() {
     process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
   }
   let stop;
-  const state = { stopping: false, stopped: new Promise((resolve) => stop = resolve) };
+  const state = { stopping: false, stopped: new Promise((resolve2) => stop = resolve2) };
   for (const signal of ["SIGINT", "SIGTERM"]) {
     process.on(signal, () => {
       if (state.stopping) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiptask/runner",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Runs an TipTask external agent's queued tasks and answers its chat on your own machine",
   "keywords": [
     "tiptask",