@refleet-it/runner 0.1.186

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dawid Cichoń
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @refleet-it/runner
+
+A runner is a worker that claims code-modernisation jobs from the [Refleet](https://refleet.it)
+API, checks out the target GitLab repository, lets an AI coding agent do the work and opens the
+result as a merge request. This package runs that loop on your own machine, with an agent you
+already have installed.
+
+## Requirements
+
+- Node.js 22 or newer
+- `git` on `PATH`
+- at least one supported agent CLI, authenticated:
+  - [Claude Code](https://docs.claude.com/en/docs/claude-code) (`claude`) — needs `ANTHROPIC_API_KEY`
+  - [Kiro CLI](https://kiro.dev/docs/cli/) (`kiro-cli`) — needs `KIRO_API_KEY`
+
+The runner registers one Runner per agent it detects at startup, so a machine with both shows up
+twice in Refleet.
+
+## Install
+
+```bash
+npm install -g @refleet-it/runner
+```
+
+## Connect and run
+
+```bash
+refleet-runner login    # API URL, email, password → mints an API key and stores it locally
+refleet-runner run
+```
+
+`login` keeps its API key in `~/.config/refleet/runner.json` (`XDG_CONFIG_HOME` is honoured).
+Anything headless — a server, a container, CI — should instead set `REFLEET_API_URL` and
+`REFLEET_API_KEY` directly; when both are set they take precedence over the stored login.
+
+```bash
+refleet-runner whoami   # which credentials are in effect, and whether they still work
+refleet-runner logout   # revokes the stored key on the server and forgets it locally
+```
+
+`run` has no idle mode: without credentials it exits immediately, and a job in progress is
+finished before `SIGINT`/`SIGTERM` stop it. Keep it alive with whatever supervisor you already use;
+a minimal systemd unit:
+
+```ini
+[Unit]
+Description=Refleet runner
+After=network-online.target
+
+[Service]
+ExecStart=/usr/bin/env refleet-runner run
+Environment=REFLEET_API_URL=https://refleet.it/api
+Environment=REFLEET_API_KEY=…
+Environment=ANTHROPIC_API_KEY=…
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+```
+
+## Configuration
+
+| Variable                                                        | Default                    | Meaning                                                         |
+| --------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------- |
+| `RUNNER_NAME`                                                   | the machine's hostname     | Prefix for this runner's name in Refleet (`<name>-<engine>`)   |
+| `REFLEET_API_URL`, `REFLEET_API_KEY`                            | from `login`               | Where and as whom to poll                                       |
+| `HEARTBEAT_INTERVAL_SECONDS`                                    | `30`                       | How often it reports itself alive                               |
+| `POLL_INTERVAL_SECONDS`                                         | `10`                       | How often it asks for work                                      |
+| `WORKSPACE_CACHE_DIR`                                           | `~/.cache/refleet/workspace` | Where cloned repositories are cached                          |
+| `WORKSPACE_CACHE_MAX_SIZE_MB`                                   | `5120`                     | Least-recently-used checkouts are evicted past this             |
+| `ANTHROPIC_API_KEY`, `KIRO_API_KEY`                             | —                          | Credentials for the agents this runner should offer             |
+| `CLAUDE_AVAILABLE_MODELS`, `KIRO_AVAILABLE_MODELS`              | —                          | Comma-separated model ids offered in Refleet's model dropdown   |
+| `CLAUDE_MODEL`, `CLAUDE_QUALIFICATION_MODEL`                    | —                          | Override the model, generally and for qualification runs        |
+| `CLAUDE_ALLOWED_TOOLS`, `CLAUDE_QUALIFICATION_ALLOWED_TOOLS`    | —                          | Restrict the tools the agent may use                            |
+| `CLAUDE_PERMISSION_MODE`, `CLAUDE_EXTRA_ARGS`, `CLAUDE_ADD_DIRS` | —                         | Passed through to the Claude CLI                                |
+| `CLAUDE_SKIP_PERMISSIONS`                                       | `true`                     | Headless runs have nobody to approve prompts                    |
+| `REFLEET_CLAUDE_PATH`, `REFLEET_KIRO_PATH`                      | —                          | Pin an explicit executable instead of looking it up on `PATH`   |
+
+GitLab access needs no configuration here: before each job the runner fetches the organisation's
+GitLab URL and token from Refleet (set up once in Settings → Connect GitLab) and passes the token
+per git invocation, never writing it into the cached checkout.
+
+## Docker
+
+The same loop ships as a container image with both agents pre-installed —
+`registry.gitlab.com/slipway1/slipway/runner-agent`. See the
+[runner installation guide](https://gitlab.com/slipway1/slipway/-/blob/main/docs/runner/installation.md).
+
+## License
+
+MIT

package/dist/backend-client.js

@@ -0,0 +1,76 @@
+export class BackendRequestError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+function baseUrl(apiUrl) {
+    return apiUrl.replace(/\/+$/, '');
+}
+/**
+ * POST /identity/login — the same endpoint the frontend's own login form uses.
+ * Maps the two failure modes LoginController documents (see
+ * backend/.../Auth/Login/LoginController.php) to messages a CLI user acts on
+ * directly instead of a bare HTTP status.
+ */
+export async function login(apiUrl, email, password, fetchFn = fetch) {
+    const response = await fetchFn(`${baseUrl(apiUrl)}/identity/login`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+    });
+    if (429 === response.status) {
+        throw new BackendRequestError('too many failed login attempts — try again in a minute', response.status);
+    }
+    if (401 === response.status || 422 === response.status) {
+        throw new BackendRequestError('invalid email or password', response.status);
+    }
+    if (!response.ok) {
+        throw new BackendRequestError(`login failed (status ${String(response.status)})`, response.status);
+    }
+    const body = (await response.json());
+    const jwtToken = body.token?.jwtToken;
+    if (!jwtToken) {
+        throw new BackendRequestError('login succeeded but the response had no JWT');
+    }
+    return { jwtToken };
+}
+/** POST /identity/api-keys, authenticated with the short-lived JWT from login(). */
+export async function createApiKey(apiUrl, jwtToken, name, fetchFn = fetch) {
+    const response = await fetchFn(`${baseUrl(apiUrl)}/identity/api-keys`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${jwtToken}` },
+        body: JSON.stringify({ name }),
+    });
+    if (!response.ok) {
+        throw new BackendRequestError(`failed to create an API key (status ${String(response.status)})`, response.status);
+    }
+    return (await response.json());
+}
+/**
+ * DELETE /identity/api-keys/{id}. Accepts the API key itself as auth (Security
+ * resolves ApiKeyAuthenticator and JwtAuthenticator to the same AccountUser), so
+ * `logout` never needs to re-prompt for a password just to revoke its own key.
+ * A 404 (already revoked/deleted) is treated as success so this stays idempotent.
+ */
+export async function revokeApiKey(apiUrl, apiKey, apiKeyId, fetchFn = fetch) {
+    const response = await fetchFn(`${baseUrl(apiUrl)}/identity/api-keys/${apiKeyId}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!response.ok && 404 !== response.status) {
+        throw new BackendRequestError(`failed to revoke the API key (status ${String(response.status)})`, response.status);
+    }
+}
+/** GET /identity/api-keys — used by `whoami` as a live validity/connectivity check. */
+export async function listApiKeys(apiUrl, apiKey, fetchFn = fetch) {
+    const response = await fetchFn(`${baseUrl(apiUrl)}/identity/api-keys`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!response.ok) {
+        throw new BackendRequestError(`failed to list API keys (status ${String(response.status)})`, response.status);
+    }
+    const body = (await response.json());
+    return body.apiKeys;
+}

package/dist/backends/claude.js

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import { AgentExecutionError } from './types.js';
+/**
+ * Builds the `claude` CLI argument list for one job kind. Ported 1:1 from
+ * runner/claude/entrypoint.sh's build_claude_args/build_kind_claude_args: qualification
+ * jobs are a read-only yes/no decision (must not modify the checkout) and default to
+ * read-only tools + an optional cheaper model, while change jobs get whatever
+ * model/tool access the operator configured for CLAUDE_MODEL/CLAUDE_ALLOWED_TOOLS.
+ *
+ * Unlike the bash version, this always adds --output-format stream-json so the output
+ * is structured NDJSON instead of the CLI's human-oriented text — see extractFinalText.
+ */
+export function buildClaudeArgs(kind, modelOverride, env) {
+    const args = [];
+    const permissionMode = env.CLAUDE_PERMISSION_MODE;
+    if (permissionMode) {
+        args.push('--permission-mode', permissionMode);
+    }
+    // Defaults to true: headless (`claude -p`, no TTY) has no one to interactively
+    // approve Edit/Write/Bash prompts, so without this the agent can only report that
+    // it lacks permission instead of acting.
+    const skipPermissions = env.CLAUDE_SKIP_PERMISSIONS ?? 'true';
+    if ('true' === skipPermissions) {
+        args.push('--dangerously-skip-permissions');
+    }
+    if (env.CLAUDE_ADD_DIRS) {
+        args.push('--add-dir', ...splitCsv(env.CLAUDE_ADD_DIRS));
+    }
+    if (env.CLAUDE_EXTRA_ARGS) {
+        args.push(...env.CLAUDE_EXTRA_ARGS.split(/\s+/).filter(Boolean));
+    }
+    const isQualification = 'qualification' === kind;
+    const model = modelOverride ||
+        (isQualification ? env.CLAUDE_QUALIFICATION_MODEL || env.CLAUDE_MODEL : env.CLAUDE_MODEL);
+    const allowedToolsCsv = isQualification
+        ? env.CLAUDE_QUALIFICATION_ALLOWED_TOOLS || env.CLAUDE_ALLOWED_TOOLS || 'Read,Grep,Glob'
+        : env.CLAUDE_ALLOWED_TOOLS;
+    if (model) {
+        args.push('--model', model);
+    }
+    if (allowedToolsCsv) {
+        args.push('--allowedTools', ...splitCsv(allowedToolsCsv));
+    }
+    args.push('--output-format', 'stream-json', '--verbose');
+    return args;
+}
+function splitCsv(value) {
+    return value
+        .split(',')
+        .map(part => part.trim())
+        .filter(Boolean);
+}
+/**
+ * Extracts the agent's final text from `claude --output-format stream-json` NDJSON
+ * output. The CLI's own closing `type: "result"` event carries the complete final
+ * answer in `.result`; if the process exits before emitting one (or on an older CLI
+ * that omits it), falls back to concatenating every streamed assistant text block.
+ *
+ * Non-JSON lines are skipped rather than failing the whole parse — stray log lines on
+ * stdout should not sink an otherwise-successful run.
+ */
+export function extractFinalText(lines) {
+    const assistantTextParts = [];
+    let resultText = null;
+    let isError = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if ('' === trimmed) {
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if ('result' === event.type) {
+            resultText = event.result ?? resultText;
+            isError = event.is_error ?? isError;
+            continue;
+        }
+        if ('assistant' === event.type && 'assistant' === event.message?.role) {
+            for (const block of event.message.content ?? []) {
+                if ('text' === block.type && block.text) {
+                    assistantTextParts.push(block.text);
+                }
+            }
+        }
+    }
+    const output = resultText ?? assistantTextParts.join('');
+    return { output, isError };
+}
+export class ClaudeBackend {
+    executablePath;
+    env;
+    spawnFn;
+    constructor(executablePath = 'claude', env = process.env, spawnFn = spawn) {
+        this.executablePath = executablePath;
+        this.env = env;
+        this.spawnFn = spawnFn;
+    }
+    async execute(prompt, opts) {
+        const args = ['-p', prompt, ...buildClaudeArgs(opts.kind, opts.model, this.env)];
+        const lines = await new Promise((resolve, reject) => {
+            const collected = [];
+            let buffer = '';
+            const child = this.spawnFn(this.executablePath, args, {
+                cwd: opts.cwd,
+                stdio: ['ignore', 'pipe', 'inherit'],
+            });
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => {
+                buffer += chunk;
+                const parts = buffer.split('\n');
+                buffer = parts.pop() ?? '';
+                collected.push(...parts);
+            });
+            child.on('error', err => {
+                reject(new AgentExecutionError(`failed to start claude: ${err.message}`));
+            });
+            child.on('close', code => {
+                if ('' !== buffer) {
+                    collected.push(buffer);
+                }
+                if (0 !== code) {
+                    reject(new AgentExecutionError(`claude exited with status ${String(code)}`));
+                    return;
+                }
+                resolve(collected);
+            });
+        });
+        const { output, isError } = extractFinalText(lines);
+        if (isError) {
+            throw new AgentExecutionError(output || 'claude reported an error with no message');
+        }
+        if ('' === output.trim()) {
+            throw new AgentExecutionError('claude produced no output');
+        }
+        return { output };
+    }
+}

package/dist/backends/kiro.js

@@ -0,0 +1,224 @@
+import { spawn } from 'node:child_process';
+import { AgentExecutionError } from './types.js';
+/**
+ * Pulls the ACP session id out of a `session/new` (or `session/load`) response.
+ * Pure/testable in isolation from the actual JSON-RPC transport.
+ */
+export function extractSessionId(result) {
+    if (!result || 'object' !== typeof result) {
+        return null;
+    }
+    const value = result.sessionId;
+    return 'string' === typeof value && '' !== value ? value : null;
+}
+/**
+ * Picks which option to reply with when kiro-cli asks for tool-use permission via a
+ * peer-initiated `session/request_permission` request — this runner is headless (no
+ * human present to click "allow"), so it always auto-approves, preferring
+ * "allow_always" over "allow_once" to avoid re-prompting for the rest of the turn.
+ * Falls back to the first offered option if neither is present (schema guarantees at
+ * least one), so a run never hangs waiting for a human that isn't there.
+ */
+export function selectAutoApproveOptionId(options) {
+    const allowAlways = options.find(option => 'allow_always' === option.kind);
+    if (allowAlways) {
+        return allowAlways.optionId;
+    }
+    const allowOnce = options.find(option => 'allow_once' === option.kind);
+    if (allowOnce) {
+        return allowOnce.optionId;
+    }
+    return options[0]?.optionId ?? null;
+}
+/**
+ * Pulls streamed text out of a `session/update` notification. ACP's sessionUpdate
+ * carries several variants (agent_message_chunk, agent_thought_chunk, tool_call, ...)
+ * — only agent_message_chunk text blocks contribute to the final answer; everything
+ * else (tool calls, thinking) is narration we don't need for a one-shot RunnerJob.
+ *
+ * Best-effort against the publicly documented ACP notification shape — verify against
+ * the installed kiro-cli version if this ever comes back empty for a run that clearly
+ * produced output.
+ */
+export function extractUpdateText(params) {
+    if (!params || 'object' !== typeof params) {
+        return null;
+    }
+    const update = params.update;
+    if (!update || 'object' !== typeof update) {
+        return null;
+    }
+    const { sessionUpdate, content } = update;
+    if ('agent_message_chunk' !== sessionUpdate || !content || 'object' !== typeof content) {
+        return null;
+    }
+    const { type, text } = content;
+    return 'text' === type && 'string' === typeof text ? text : null;
+}
+/**
+ * Minimal ACP JSON-RPC 2.0 client over a child process's stdio: newline-delimited
+ * JSON in both directions. Three kinds of incoming message: a response to one of our
+ * requests (`id` + `result`/`error`), a peer-initiated request we must answer (`id` +
+ * `method` — kiro-cli asking something of us, e.g. session/request_permission), or a
+ * notification (`method`, no `id`). Mirrors the shape of multica's hermesClient
+ * (server/pkg/agent/hermes.go), scoped down to what a single request/session/prompt
+ * turn needs.
+ */
+class AcpConnection {
+    child;
+    onNotification;
+    nextId = 1;
+    pending = new Map();
+    buffer = '';
+    constructor(child, onNotification) {
+        this.child = child;
+        this.onNotification = onNotification;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => this.handleData(chunk));
+        child.on('close', () => this.rejectAllPending(new AgentExecutionError('kiro-cli process exited')));
+        child.on('error', err => this.rejectAllPending(new AgentExecutionError(`kiro-cli process error: ${err.message}`)));
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.send({ jsonrpc: '2.0', id, method, params }, err => {
+                if (err) {
+                    this.pending.delete(id);
+                    reject(new AgentExecutionError(`failed to write to kiro-cli: ${err.message}`));
+                }
+            });
+        });
+    }
+    send(message, cb) {
+        this.child.stdin.write(`${JSON.stringify(message)}\n`, cb);
+    }
+    handleData(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            this.handleLine(line);
+        }
+    }
+    handleLine(line) {
+        const trimmed = line.trim();
+        if ('' === trimmed) {
+            return;
+        }
+        let message;
+        try {
+            message = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        const hasId = 'number' === typeof message.id;
+        const hasMethod = 'string' === typeof message.method;
+        if (hasId && hasMethod) {
+            this.handlePeerRequest(message.id, message.method, message.params);
+            return;
+        }
+        if (hasId) {
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                return;
+            }
+            this.pending.delete(message.id);
+            if (message.error) {
+                pending.reject(new AgentExecutionError(`kiro-cli error ${message.error.code}: ${message.error.message}`));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if (hasMethod) {
+            this.onNotification(message.method, message.params);
+        }
+    }
+    /**
+     * Answers a request kiro-cli sent to us. This runner runs headless with no human to
+     * approve anything, so the only peer request it understands — session/request_permission
+     * — is always auto-approved (see selectAutoApproveOptionId). Any other peer request
+     * gets a JSON-RPC "method not found" error rather than being left unanswered, so
+     * kiro-cli never blocks forever waiting for a reply we were never going to send.
+     */
+    handlePeerRequest(id, method, params) {
+        if ('session/request_permission' === method) {
+            const options = params?.options ?? [];
+            const optionId = selectAutoApproveOptionId(options);
+            const outcome = optionId ? { outcome: 'selected', optionId } : { outcome: 'cancelled' };
+            this.send({ jsonrpc: '2.0', id, result: { outcome } });
+            return;
+        }
+        this.send({ jsonrpc: '2.0', id, error: { code: -32601, message: `unhandled peer request: ${method}` } });
+    }
+    rejectAllPending(error) {
+        for (const pending of this.pending.values()) {
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+export class KiroBackend {
+    executablePath;
+    env;
+    spawnFn;
+    constructor(executablePath = 'kiro-cli', env = process.env, spawnFn = spawn) {
+        this.executablePath = executablePath;
+        this.env = env;
+        this.spawnFn = spawnFn;
+    }
+    async execute(prompt, opts) {
+        // `--trust-all-tools` is documented for kiro-cli's standalone --no-interactive
+        // headless mode, not for `acp` — passing an unrecognized flag risks a hard
+        // startup failure there. Auto-approval in ACP mode instead goes through the
+        // protocol-native session/request_permission (see AcpConnection.handlePeerRequest).
+        const child = this.spawnFn(this.executablePath, ['acp'], {
+            cwd: opts.cwd,
+            env: this.env,
+            stdio: ['pipe', 'pipe', 'inherit'],
+        });
+        const chunks = [];
+        const connection = new AcpConnection(child, (method, params) => {
+            if ('session/update' === method) {
+                const text = extractUpdateText(params);
+                if (text) {
+                    chunks.push(text);
+                }
+            }
+        });
+        try {
+            await connection.request('initialize', {
+                protocolVersion: 1,
+                clientInfo: { name: 'slipway-agent-runner', version: '0.1.0' },
+                clientCapabilities: {},
+            });
+            const sessionResult = await connection.request('session/new', {
+                cwd: opts.cwd,
+                mcpServers: [],
+            });
+            const sessionId = extractSessionId(sessionResult);
+            if (null === sessionId) {
+                throw new AgentExecutionError('kiro-cli session/new returned no session ID');
+            }
+            if (opts.model) {
+                await connection.request('session/set_model', { sessionId, modelId: opts.model });
+            }
+            await connection.request('session/prompt', {
+                sessionId,
+                prompt: [{ type: 'text', text: prompt }],
+            });
+        }
+        finally {
+            child.stdin.end();
+            child.kill();
+        }
+        const output = chunks.join('').trim();
+        if ('' === output) {
+            throw new AgentExecutionError('kiro-cli produced no output');
+        }
+        return { output };
+    }
+}

package/dist/backends/types.js

@@ -0,0 +1,2 @@
+export class AgentExecutionError extends Error {
+}