@werewolf-solutions/dev 0.0.0-stage → 0.1.1

package/src/draft.js

@@ -0,0 +1,80 @@
+/**
+ * One draft from the website agent, shared by the local worker and the remote runner:
+ * generate with the chosen runner, check it against the checklist with the same runner,
+ * and regenerate once if the check found problems. Moved from the server's
+ * services/siteBuilder/agentDraft.js; the repo's local agent uses this copy too.
+ */
+const { runAgent } = require('./agents');
+const { extractJson, sanitizeFiles } = require('./contract');
+
+const TICK_MS = 30 * 1000;
+const seconds = (since) => `${Math.round((Date.now() - since) / 1000)}s`;
+const kb = (value) => `${(Buffer.byteLength(String(value || '')) / 1024).toFixed(1)}KB`;
+
+// One call to the model, with a "still working" line every 30s so a long run doesn't look stuck.
+async function ask({ run, prompt, images = [], cwd, log, label, step }) {
+  const started = Date.now();
+  log(`${label}: ${step}: asking ${run.provider} ${run.model}${run.effort ? ` (${run.effort})` : ''}, prompt ${kb(prompt)}${images.length ? `, ${images.length} screenshot(s)` : ''}…`);
+  const timer = setInterval(() => log(`${label}: ${step}: still waiting for ${run.provider} (${seconds(started)})`), TICK_MS);
+  try {
+    const reply = await runAgent({ ...run, prompt, images, cwd });
+    log(`${label}: ${step}: reply after ${seconds(started)}, ${kb(reply)}`);
+    return reply;
+  } catch (error) {
+    log(`${label}: ${step}: ${run.provider} failed after ${seconds(started)}: ${error.message}`);
+    throw error;
+  } finally {
+    clearInterval(timer);
+  }
+}
+
+async function generate({ run, prompt, images, workspace, log = () => {}, label = 'draft', step = 'generate' }) {
+  const once = async (text, attempt) => {
+    const reply = await ask({ run, prompt: text, images, cwd: workspace, log, label, step: attempt });
+    const all = sanitizeFiles(extractJson(reply).files);
+    // Owner photos already live in assets/; generated files never replace them.
+    const files = all.filter((file) => !file.path.startsWith('assets/'));
+    if (files.length < all.length) log(`${label}: ${attempt}: dropped ${all.length - files.length} file(s) under assets/`);
+    log(`${label}: ${attempt}: ${files.length} file(s): ${files.map((file) => `${file.path} ${kb(file.content)}`).join(', ')}`);
+    return files;
+  };
+  try { return await once(prompt, step); }
+  catch (error) {
+    log(`${label}: ${step}: unusable reply (${error.message}); asking once more for JSON only`);
+    return once(`${prompt}\n\nYour previous attempt failed with: "${error.message}". Output ONLY the JSON object this time.`, `${step} (retry)`);
+  }
+}
+
+async function selfCheck({ run, files, checklist, workspace, log = () => {}, label = 'draft' }) {
+  const index = files.find((file) => file.path === 'index.html')?.content || '';
+  const prompt = [
+    'You review a generated small-business website against a checklist. Be strict but practical.',
+    'Respond with ONLY JSON: {"pass": true|false, "problems": ["..."]}. List at most 6 concrete problems; empty when it passes.',
+    '', 'Checklist:', ...checklist.map((item) => `- ${item}`),
+    '', `Files: ${files.map((file) => file.path).join(', ')}`,
+    '', 'index.html:', index.slice(0, 60000),
+  ].join('\n');
+  try {
+    const verdict = extractJson(await ask({ run, prompt, cwd: workspace, log, label, step: 'self-check' }));
+    return { pass: verdict.pass === true, problems: Array.isArray(verdict.problems) ? verdict.problems.map(String).slice(0, 6) : [] };
+  } catch (error) {
+    log(`${label}: self-check skipped: ${error.message}`);
+    return { pass: true, problems: [] };
+  }
+}
+
+async function buildDraft({ run, prompt, checklist, images = [], workspace, log = () => {}, label = 'draft' }) {
+  const started = Date.now();
+  let files = await generate({ run, prompt, images, workspace, log, label });
+  const check = await selfCheck({ run, files, checklist, workspace, log, label });
+  if (!check.pass && check.problems.length) {
+    log(`${label}: self-check found ${check.problems.length} problem(s), regenerating once:\n${check.problems.map((item) => `    - ${item}`).join('\n')}`);
+    files = await generate({ run, prompt: `${prompt}\n\nA review of your first draft found these problems. Fix all of them:\n${check.problems.map((item) => `- ${item}`).join('\n')}`, images, workspace, log, label, step: 'regenerate' });
+  } else {
+    log(`${label}: self-check passed`);
+  }
+  log(`${label}: draft built in ${seconds(started)}`);
+  return files;
+}
+
+module.exports = { generate, selfCheck, buildDraft };

package/src/mcpRunner.js

@@ -0,0 +1,251 @@
+/**
+ * `werewolf-dev mcp` with a runner token: the one connection a developer sets up. Their harness
+ * (Claude Code, Codex, Cursor, any MCP client) starts it, and it offers everything this machine
+ * has: the harness itself, plus the claude and codex CLIs and Ollama when they are installed.
+ * The developer picks on the developer page:
+ *
+ * - a CLI with a model and effort: this process builds it in the background, as the runner
+ *   would, without the harness doing anything;
+ * - the harness: the run waits until the harness calls next_website_job, builds it with its own
+ *   model and submits it.
+ *
+ * Either way the draft is held for review. Starting, accepting and sending back stay in the
+ * browser, so a person still reviews every draft before the owner sees it. When the harness
+ * closes, unfinished runs go back to the queue and the connection says it is leaving.
+ * Spec: .notes/impl-website-runner-package.md §3
+ *
+ * The MCP SDK and zod are passed in (startRunnerMcp), so the session itself needs no install.
+ */
+const os = require('os');
+const { problemOf } = require('./api');
+const { createRemoteRunner, describeIdle, uploadDraft } = require('./runner');
+const { sanitizeFiles } = require('./contract');
+const { version } = require('../package.json');
+
+const CLIENT = { name: '@werewolf-solutions/dev', version };
+
+// The harness's name from the MCP handshake (e.g. "claude-code"), used as the run's model.
+const harnessName = (info) => String(info?.name || '').replace(/[^\w.-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'mcp';
+
+const harnessOffer = (name) => [{
+  id: 'harness', label: `${name} via MCP`, available: true,
+  models: [{ id: name, label: name, efforts: [] }], defaultModel: name, defaultEffort: '',
+}];
+
+// The background loop takes every run this connection offers except the harness's own.
+const cliProviders = (offered) => offered.filter((runner) => runner.id !== 'harness' && runner.available).map((runner) => runner.id);
+
+/**
+ * `listRunners` and `buildDraft` are the runner's (src/agents.js, src/draft.js) unless given:
+ * the CLIs on this machine, and how a draft is built with one.
+ */
+function createHarnessSession({ api, token, fetch, host = os.hostname(), clientInfo = CLIENT, log = () => {}, listRunners, buildDraft, exec }) {
+  let name = 'mcp';
+  const worker = createRemoteRunner({
+    api, token, fetch, host, clientInfo, log, exec, kind: 'mcp',
+    listRunners: listRunners || ((env) => require('./agents').listRunners({ env: env || process.env, exec })),
+    buildDraft: buildDraft || ((...args) => require('./draft').buildDraft(...args)),
+    extraRunners: () => harnessOffer(name),
+    claimProviders: cliProviders,
+  });
+  const { client, connection, heartbeat } = worker;
+  // Harness runs this session claimed and hasn't finished, by request id.
+  const claimed = new Map();
+
+  // Is this a runner token? A business key (or any key without website_agent) gets a 403 at
+  // the check-in; it keeps the business tools. Any other failure is a real problem.
+  const detect = async () => {
+    try { return await heartbeat(); } catch (error) {
+      if (error.response?.status === 403) return null;
+      throw error;
+    }
+  };
+
+  const setHarness = (info) => { name = harnessName(info); return heartbeat(); };
+
+  // Check in every 30s while the harness is open (keeps the offer live and claimed runs from
+  // going stale), and build the CLI runs started for this connection. Returns stop().
+  const start = (options = {}) => {
+    let stopped = false;
+    worker.loop({ ...options, shouldStop: () => stopped })
+      .catch((error) => log(`stopped building in the background: ${error.message}`));
+    return () => { stopped = true; };
+  };
+
+  const listRequests = async () => {
+    const { data } = await client.get('/developers/website-requests');
+    return (data.data?.requests || []).filter((request) => request.status === 'pending').map((request) => ({
+      requestId: String(request._id),
+      business: request.business?.name || '',
+      kind: request.kind,
+      state: request.agent?.state || 'waiting',
+      ...(request.agent?.run?.provider ? { run: `${request.agent.run.provider} ${request.agent.run.model || ''}`.trim() } : {}),
+      ...(request.agent?.error ? { error: request.agent.error } : {}),
+      ...(request.agent?.previewPath ? { preview: `${client.baseURL.replace(/\/api\/v1$/, '')}${request.agent.previewPath}` } : {}),
+      createdAt: request.createdAt,
+    }));
+  };
+
+  const nextJob = async () => {
+    const { data } = await client.post('/developers/website-agent/claim', { connection, providers: ['harness'] });
+    const job = data.data?.job;
+    if (!job) return { job: null, idle: describeIdle(data.data?.idle) };
+    claimed.set(job.requestId, job);
+    return { job };
+  };
+
+  const claimedJob = (requestId) => {
+    const job = claimed.get(String(requestId || ''));
+    if (!job) throw new Error('This session has not claimed that request. Call next_website_job first and use the requestId it returns.');
+    return job;
+  };
+
+  // The server checks the files again; this catches the usual mistakes before the upload.
+  const submit = async ({ requestId, files }) => {
+    const job = claimedJob(requestId);
+    const all = sanitizeFiles(files);
+    const kept = all.filter((file) => !file.path.startsWith('assets/'));
+    const result = await uploadDraft(client, job, kept);
+    claimed.delete(job.requestId);
+    return { ...result, files: kept.length, dropped: all.length - kept.length };
+  };
+
+  const fail = async ({ requestId, error }) => {
+    const job = claimedJob(requestId);
+    const { data } = await client.post(`/developers/website-requests/${job.requestId}/agent/failed`, { error: String(error || 'The harness could not build it').slice(0, 300) });
+    claimed.delete(job.requestId);
+    return { retry: Boolean(data.data?.retry) };
+  };
+
+  // The harness closed with runs still claimed: hand them back, as the runner does on Ctrl+C,
+  // the one building in the background included.
+  const release = async (reason = 'The harness session ended before the draft was submitted') => {
+    const jobs = [...claimed.values()];
+    claimed.clear();
+    const background = worker.busy() ? worker.release(reason).then(() => 1, () => 0) : Promise.resolve(0);
+    await Promise.allSettled(jobs.map((job) => client.post(`/developers/website-requests/${job.requestId}/agent/failed`, { error: reason }, { timeout: 5000 })));
+    return jobs.length + await background;
+  };
+
+  return { client, connection, heartbeat, detect, setHarness, start, disconnect: worker.disconnect, listRequests, nextJob, submit, fail, release, claimed, busy: worker.busy, harness: () => name };
+}
+
+const textResult = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] });
+const failure = (error) => ({ isError: true, content: [{ type: 'text', text: problemOf(error) }] });
+
+// What the harness reads with a claimed run: how to hand the result back, then the brief.
+function jobContent(job) {
+  const intro = [
+    `Website job for ${job.businessName} (requestId ${job.requestId}, ${job.kind === 'changes' ? 'changes to the current draft' : job.kind}).`,
+    '',
+    'Build the website from the brief below, using only what the brief gives you. Do not write the site into local files or the current project; it goes back to the server.',
+    'The brief asks for a {"files":[{"path","content"}]} JSON object. Instead of replying with it, call submit_website_draft with this requestId and that files list. index.html is required; files under assets/ are dropped (the owner\'s photos live there).',
+    'Before you submit, check your files against every checklist item at the end and fix what fails.',
+    'If you cannot build it, call report_website_failure with the reason.',
+    job.images?.length ? `${job.images.length} screenshot(s) of the business's current site follow the brief.` : '',
+    '',
+    '──── brief ────',
+    job.prompt,
+    '',
+    '──── checklist ────',
+    ...(job.checklist || []).map((item) => `- ${item}`),
+  ].filter((line, index, lines) => line !== '' || lines[index - 1] !== '');
+  return [
+    { type: 'text', text: intro.join('\n') },
+    ...(job.images || []).map((image) => ({ type: 'image', data: image.data, mimeType: image.mediaType || 'image/png' })),
+  ];
+}
+
+function registerRunnerTools(server, session, z) {
+  server.registerTool('list_website_requests', {
+    title: 'List my website requests',
+    description: 'The open website requests assigned to you, with business, kind and run state (waiting, queued, building, review, failed). Read-only. Start a run on the developer page, choosing "via MCP" as the runner, then call next_website_job.',
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  }, async () => {
+    try { return textResult(await session.listRequests()); } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('next_website_job', {
+    title: 'Take the next website job',
+    description: 'Claim the next website run you started on the developer page for this harness. Returns the requestId, the full brief, the checklist and screenshots of the current site. Build only from the brief, check the result against the checklist, then call submit_website_draft. With nothing queued, says why.',
+    inputSchema: {},
+  }, async () => {
+    try {
+      const { job, idle } = await session.nextJob();
+      return job ? { content: jobContent(job) } : textResult(`Nothing to build: ${idle}.`);
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('submit_website_draft', {
+    title: 'Submit a website draft',
+    description: 'Upload the files you built for a job from next_website_job. The draft is held for your review on the developer page; the business owner sees nothing until you accept it there. files is the same [{path, content}] list the brief describes and must include index.html. Returns the preview link.',
+    inputSchema: {
+      requestId: z.string().describe('The requestId from next_website_job'),
+      files: z.array(z.object({ path: z.string(), content: z.string() })).min(1).describe('The complete site, e.g. [{ "path": "index.html", "content": "<!doctype html>…" }]'),
+    },
+  }, async ({ requestId, files }) => {
+    try {
+      const result = await session.submit({ requestId, files });
+      return textResult([
+        `Draft uploaded (${result.files} file(s)${result.dropped ? `, ${result.dropped} under assets/ dropped` : ''}) and held for your review.`,
+        result.previewUrl ? `Preview: ${result.previewUrl}` : '',
+        'Accept it or send it back on the developer page.',
+      ].filter(Boolean).join('\n'));
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('report_website_failure', {
+    title: 'Report a failed website job',
+    description: 'Give a claimed job back when you cannot build it, with the reason. The server queues it once more, then marks it failed on the developer page.',
+    inputSchema: {
+      requestId: z.string().describe('The requestId from next_website_job'),
+      error: z.string().describe('What went wrong, in one or two sentences'),
+    },
+  }, async ({ requestId, error }) => {
+    try {
+      const { retry } = await session.fail({ requestId, error });
+      return textResult(retry ? 'Reported. The run is queued again; next_website_job will hand it out once more.' : 'Reported. The run is marked failed on the developer page.');
+    } catch (caught) { return failure(caught); }
+  });
+}
+
+// The MCP server with the runner tools. The harness says who it is in the handshake; the
+// run is offered under that name from then on.
+function createRunnerServer({ session, McpServer, z, log = () => {} }) {
+  const server = new McpServer({ name: 'werewolf-dev', version });
+  registerRunnerTools(server, session, z);
+  server.server.oninitialized = () => {
+    session.setHarness(server.server.getClientVersion()).catch((error) => log(`check-in failed: ${problemOf(error)}`));
+  };
+  return server;
+}
+
+/**
+ * Serve the runner tools on stdio when `token` is a runner token. Returns false for any
+ * other key, so the caller serves the business tools instead.
+ */
+async function startRunnerMcp({ api, token, McpServer, StdioServerTransport, z, log = (line) => console.error(`[werewolf-dev mcp] ${line}`) }) {
+  const session = createHarnessSession({ api, token, log });
+  const me = await session.detect();
+  if (!me) return false;
+  const server = createRunnerServer({ session, McpServer, z, log });
+  const stop = session.start();
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    stop();
+    const released = await session.release().catch(() => 0);
+    if (released) log(`handed ${released} unfinished run(s) back to the server`);
+    await session.disconnect().catch(() => {});
+    process.exit(0);
+  };
+  process.stdin.on('end', shutdown);
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, shutdown);
+  await server.connect(new StdioServerTransport());
+  log(`signed in to ${session.client.baseURL} as ${me.developer?.name || 'developer'}; website runner tools ready`);
+  return true;
+}
+
+module.exports = { createHarnessSession, createRunnerServer, registerRunnerTools, startRunnerMcp, harnessName, jobContent };

package/src/runner.js

@@ -0,0 +1,168 @@
+/**
+ * The website runner: the website agent on a developer's own machine, building briefs from
+ * staging or production through the public API. It signs in with the developer's runner token
+ * and never touches a database. Moved here from the server's services/siteBuilder/remoteRunner.js.
+ *
+ * Loop: check in (what this machine can run) → claim the next run the developer started on the
+ * developer page → build the draft locally → upload it held for review → report the result.
+ */
+const crypto = require('crypto');
+const fs = require('fs/promises');
+const os = require('os');
+const path = require('path');
+const { createClient, problemOf } = require('./api');
+const { version } = require('../package.json');
+
+const POLL_MS = 20 * 1000;
+const HEARTBEAT_MS = 30 * 1000;
+const CLIENT = { name: '@werewolf-solutions/dev', version };
+
+const IDLE_REMINDER_MS = 5 * 60 * 1000;
+const kb = (value) => `${(Buffer.byteLength(String(value || '')) / 1024).toFixed(1)}KB`;
+
+// One line on why there is nothing to build, from the server's idle summary.
+function describeIdle(idle = {}) {
+  const mine = idle.mine || {};
+  const parts = Object.entries(mine).filter(([, count]) => count).map(([state, count]) => `${count} ${state === 'review' ? 'waiting for your review' : state}`);
+  let line = parts.length ? `your open requests: ${parts.join(', ')}` : 'no open website requests are assigned to you';
+  if (!mine.queued) line += '. Press Start on one of your requests on the developer page';
+  if (idle.localQueued) line += `. ${idle.localQueued} run(s) are queued for the local website agent account; this runner only builds requests assigned to you, those need: npm run website-agent`;
+  return line;
+}
+
+// Upload a built draft held for review, then tell the server the run is done. Shared with the
+// MCP runner tools, where the developer's harness built the files.
+async function uploadDraft(client, job, files) {
+  const upload = await client.post(`/businesses/${job.businessId}/builder/projects/${job.projectId}/revisions`, {
+    files, prompt: `Website runner: ${job.kind} request ${job.requestId}`, provider: `runner:${job.run.provider}:${job.run.model}`.slice(0, 40), holdForReview: true,
+  });
+  const candidate = upload.data?.data?.revision?._id;
+  if (!candidate) throw new Error('The upload returned no draft');
+  const finished = await client.post(`/developers/website-requests/${job.requestId}/agent/finished`, { candidate });
+  const previewPath = finished.data?.data?.previewPath;
+  return { candidate, previewPath, previewUrl: previewPath ? `${client.baseURL.replace(/\/api\/v1$/, '')}${previewPath}` : null };
+}
+
+// `exec`: the --exec command, for runs the developer started with "Your command".
+// The MCP server reuses this as its background worker: `kind: 'mcp'`, `extraRunners` adds the
+// harness to the offer, and `claimProviders` keeps the loop to the CLI runs (the harness takes
+// its own runs when asked).
+function createRemoteRunner({
+  api, token, fetch, listRunners, buildDraft, log = () => {}, host = os.hostname(), exec, clientInfo = CLIENT,
+  kind = 'runner', extraRunners = () => [], claimProviders = null, connection = crypto.randomUUID(),
+}) {
+  const client = createClient({ api, token, fetch });
+
+  // One id per process: the server keeps each connection's offer apart, matches claims to it,
+  // and keeps this connection's claims alive while it checks in.
+  let offered = [];
+  const heartbeat = async () => {
+    const runners = [...await listRunners(), ...extraRunners()];
+    const { data } = await client.post('/developers/website-agent/heartbeat', { runners, host, connection, kind, client: clientInfo });
+    offered = runners;
+    return { ...data.data, offered: runners };
+  };
+
+  // Tell the server this connection is going, so the developer page updates at once.
+  const disconnect = () => client.post('/developers/website-agent/disconnect', { connection }, { timeout: 5000 });
+
+  // The run being built right now, so stopping the runner can hand it back.
+  let active = null;
+
+  // One claimed run, start to finish. Failures go back to the server, which retries once.
+  const runJob = async (job) => {
+    active = job;
+    const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'website-runner-'));
+    const label = job.businessName || job.requestId;
+    const started = Date.now();
+    try {
+      log(`${label}: claimed request ${job.requestId} (${job.kind === 'changes' ? 'changes' : job.kind})`);
+      log(`${label}: run ${job.run.provider} ${job.run.model}${job.run.effort ? ` ${job.run.effort}` : ''}; prompt ${kb(job.prompt)}, ${job.checklist?.length || 0} checklist item(s), ${job.images?.length || 0} screenshot(s); workspace ${workspace}`);
+      const files = await buildDraft({ run: { ...job.run, exec }, prompt: job.prompt, checklist: job.checklist, images: job.images || [], workspace, log, label });
+      log(`${label}: uploading ${files.length} file(s), ${kb(files.map((file) => file.content).join(''))}, held for your review…`);
+      const { candidate, previewUrl } = await uploadDraft(client, job, files);
+      log(`${label}: draft ${candidate} ready for your review after ${Math.round((Date.now() - started) / 1000)}s${previewUrl ? `: ${previewUrl}` : ''}. Accept it or send it back on the developer page.`);
+      return { ok: true, candidate };
+    } catch (error) {
+      const message = problemOf(error).slice(0, 300);
+      log(`${label}: failed: ${message}`);
+      await client.post(`/developers/website-requests/${job.requestId}/agent/failed`, { error: message })
+        .then(() => log(`${label}: reported the failure; the server retries once, then marks the run failed`))
+        .catch((reportError) => log(`could not report the failure: ${problemOf(reportError)}`));
+      return { ok: false, error: message };
+    } finally {
+      active = null;
+      await fs.rm(workspace, { recursive: true, force: true });
+    }
+  };
+
+  // Hands the current run back when the runner is stopped mid-build, so it isn't left claimed.
+  // The server counts it as a failed attempt and requeues it once.
+  const release = async (reason = 'The runner was stopped before it finished') => {
+    if (!active) return false;
+    await client.post(`/developers/website-requests/${active.requestId}/agent/failed`, { error: reason }, { timeout: 5000 });
+    return true;
+  };
+
+  // Claim and build at most one run. Returns null when there is nothing to do. The idle reason
+  // is logged when it changes, and again every 5 minutes so a quiet runner still looks alive.
+  let lastIdle = '';
+  let lastIdleAt = 0;
+  const tick = async () => {
+    const providers = claimProviders ? claimProviders(offered) : null;
+    if (providers && !providers.length) return null;
+    const { data } = await client.post('/developers/website-agent/claim', { connection, ...(providers ? { providers } : {}) });
+    const job = data.data?.job;
+    if (job) { lastIdle = ''; return runJob(job); }
+    const line = describeIdle(data.data?.idle);
+    if (line !== lastIdle || Date.now() - lastIdleAt >= IDLE_REMINDER_MS) {
+      log(`nothing to build: ${line}`);
+      lastIdle = line;
+      lastIdleAt = Date.now();
+    }
+    return null;
+  };
+
+  const loop = async ({ shouldStop = () => false, pollMs = POLL_MS, heartbeatMs = HEARTBEAT_MS, retryMs = 5000 } = {}) => {
+    log(`connecting to ${client.baseURL} as ${host}…`);
+    // The server may be restarting (nodemon) or not up yet: keep trying for a couple of
+    // minutes. A refused token is final.
+    let me;
+    for (let attempt = 1; ; attempt += 1) {
+      try { me = await heartbeat(); break; }
+      catch (error) {
+        if (error.response || attempt >= 24 || shouldStop()) throw new Error(`could not sign in: ${problemOf(error)}`);
+        log(`server not answering (${problemOf(error)}); retrying in 5s`);
+        await new Promise((resolve) => setTimeout(resolve, retryMs));
+      }
+    }
+    log(`signed in as ${me.developer?.name || 'developer'}. Offering:`);
+    for (const runner of me.offered) {
+      log(`  ${runner.label || runner.id}: ${runner.available ? `${runner.models.length} model(s)${runner.defaultModel ? `, default ${runner.defaultModel}` : ''}` : `unavailable (${runner.reason || 'not installed'})`}`);
+    }
+    log(`checking for runs every ${pollMs / 1000}s and checking in every ${heartbeatMs / 1000}s (Ctrl+C to stop)`);
+    let checkInFailing = false;
+    const timer = setInterval(() => {
+      heartbeat()
+        .then(() => { if (checkInFailing) log('check-in working again'); checkInFailing = false; })
+        .catch((error) => { checkInFailing = true; log(`check-in failed: ${problemOf(error)}`); });
+    }, heartbeatMs);
+    try {
+      while (!shouldStop()) {
+        let result = null;
+        try { result = await tick(); }
+        catch (error) {
+          if (error.response?.status === 401 || error.response?.status === 403) throw new Error(`The server refused the runner token: ${problemOf(error)}`);
+          log(`claim failed: ${problemOf(error)}`);
+        }
+        if (!result && !shouldStop()) await new Promise((resolve) => setTimeout(resolve, pollMs));
+      }
+    } finally {
+      clearInterval(timer);
+    }
+  };
+
+  return { client, connection, heartbeat, disconnect, tick, runJob, loop, release, busy: () => Boolean(active) };
+}
+
+module.exports = { createRemoteRunner, describeIdle, uploadDraft };