hammerkit 1.27.0-next.3 → 1.27.0-next.30

package/dist/harness/opencode.js

@@ -9,35 +9,69 @@ const url_1 = require("url");
 const connect_1 = require("./connect");
 const format_1 = require("./format");
 const sandbox_client_1 = require("./sandbox-client");
+const task_tools_1 = require("./task-tools");
+const service_tools_1 = require("./service-tools");
 const DEFAULT_READ_LINES = 2000;
 const LIST_LIMIT = 100;
 const SEARCH_LIMIT = 100;
 /**
  * The tools of opencode on a hammerkit sandbox: `read`, `write`, `edit`, `apply_patch`,
  * `bash`, `grep`, `glob` and `list` with the parameters of opencode's own, which a plugin replaces
- * by registering tools of the same name, and `push`, which takes the work out as a branch. opencode resolves paths against its directory,
- * which stands for the root of the sandbox. `schema` is the zod of opencode
+ * by registering tools of the same name, `run_task` and `run_logs` for the tasks of the build
+ * file, and `push`, which takes the work out as a branch. opencode resolves paths against its
+ * directory, which stands for the root of the sandbox. `schema` is the zod of opencode
  * (`tool.schema` of `@opencode-ai/plugin`), so it reads the parameters as its own.
  */
 function hammerkitOpencodePlugin(schema, settings = {}) {
-    return async (input) => ({ tool: createOpencodeTools(schema, lazySandbox(input.directory, settings)) });
+    return async (input) => {
+        const harness = connectHarness(input.directory, settings);
+        const tasks = await harness.tasks();
+        return { tool: createOpencodeTools(schema, harness.client, { tasks, shell: harness.shell }) };
+    };
 }
 exports.hammerkitOpencodePlugin = hammerkitOpencodePlugin;
-// the sandbox, connected on the first call of a tool and again after a failed connect
-function lazySandbox(directory, settings) {
+function connectHarness(directory, settings) {
     const environment = settings.environment ?? (0, connect_1.getHarnessEnvironment)(directory);
     const options = settings.options ?? (0, connect_1.harnessOptionsFromEnv)(environment.processEnvs);
     let connecting;
-    return () => {
+    const client = () => {
         if (!connecting) {
             connecting = settings.client ? settings.client() : (0, connect_1.connectSandbox)(environment, options);
             connecting.catch(() => (connecting = undefined));
         }
         return connecting;
     };
+    return {
+        client,
+        // the version is read without a sandbox, which the first call of a tool takes
+        tasks: () => (0, task_tools_1.readTaskListing)(async () => {
+            if (settings.client) {
+                return (await client()).tasks();
+            }
+            const server = await (0, connect_1.connectServer)(environment, options);
+            return (0, sandbox_client_1.listPublishedTasks)(server.connection, server.build);
+        }),
+        shell: options.shell ?? connect_1.DEFAULT_SHELL_TASK,
+    };
 }
 // the names of the tools of the plugin, which stand in for opencode's own
-exports.OPENCODE_TOOLS = ['read', 'write', 'edit', 'apply_patch', 'bash', 'grep', 'glob', 'push', 'list'];
+exports.OPENCODE_TOOLS = [
+    'read',
+    'write',
+    'edit',
+    'apply_patch',
+    'bash',
+    'grep',
+    'glob',
+    'run_task',
+    'run_logs',
+    'check',
+    'push',
+    'list',
+    'services_up',
+    'endpoint_get',
+    'services_stop',
+];
 /**
  * The plugin as the file `harness/opencode.ts` exports it: it takes the zod of opencode from
  * `@opencode-ai/plugin`, found next to hammerkit or else in the opencode directories of the
@@ -111,7 +145,22 @@ function packageEntry(manifest) {
     }
 }
 // the names of the tools of the plugin on opencode 2, which stand in for its own
-exports.OPENCODE_V2_TOOLS = ['read', 'write', 'edit', 'patch', 'shell', 'glob', 'grep', 'push'];
+exports.OPENCODE_V2_TOOLS = [
+    'read',
+    'write',
+    'edit',
+    'patch',
+    'shell',
+    'glob',
+    'grep',
+    'run_task',
+    'run_logs',
+    'check',
+    'push',
+    'services_up',
+    'endpoint_get',
+    'services_stop',
+];
 // the tools of opencode 2 that work on this machine and have no stand-in on a sandbox
 exports.OPENCODE_V2_LOCAL_TOOLS = [
     'opencode_worktree_create',
@@ -120,25 +169,31 @@ exports.OPENCODE_V2_LOCAL_TOOLS = [
 ];
 /**
  * The plugin for opencode 2: the tools of {@link createOpencodeV2Tools} in place of opencode's own,
- * and none of the worktree tools, which would make worktrees of this machine. opencode 2 takes a
- * plugin as an object with an id and a setup, it needs no package of opencode.
+ * and none of the worktree tools, which would make worktrees of this machine, nor its shell
+ * when there is no shell task. opencode 2 takes a plugin as an object with an id and a setup, it
+ * needs no package of opencode.
  */
 function hammerkitOpencodeV2Plugin(settings = {}) {
     return {
         id: 'hammerkit',
         async setup(context) {
             const directory = context.location.directory;
-            const tools = createOpencodeV2Tools(lazySandbox(directory, settings), directory);
+            const harness = connectHarness(directory, settings);
+            const tasks = await harness.tasks();
+            const tools = createOpencodeV2Tools(harness.client, directory, { tasks, shell: harness.shell });
             await context.tool.transform((editor) => {
                 for (const tool of tools) {
                     editor.add(tool);
                 }
-                for (const name of exports.OPENCODE_V2_LOCAL_TOOLS) {
+                for (const name of [...exports.OPENCODE_V2_LOCAL_TOOLS, ...(harness.shell ? [] : ['shell'])]) {
                     editor.remove(name);
                 }
             });
             // opencode describes the tool named shell anew for each request, as the shell of this machine
             const shell = tools.find((tool) => tool.name === 'shell');
+            if (!shell) {
+                return;
+            }
             for (const name of ['context', 'compaction', 'generate']) {
                 await context.session.hook(name, (request) => {
                     if (request.tools.shell) {
@@ -163,8 +218,9 @@ exports.hammerkitOpencodeEntry = hammerkitOpencodeEntry;
  * opencode 1 under their new names (`patch`, `shell`), paths as `path`, relative to `directory`
  * or absolute below it. opencode 2 has no `list`, `read` lists a directory.
  */
-function createOpencodeV2Tools(client, directory) {
-    const tools = opencodeTools(client);
+function createOpencodeV2Tools(client, directory, options = {}) {
+    const tools = opencodeTools(client, options);
+    const shell = options.shell ?? connect_1.DEFAULT_SHELL_TASK;
     const tool = (name, of, input, args, permission) => ({
         name,
         description: tools[of].description,
@@ -176,6 +232,7 @@ function createOpencodeV2Tools(client, directory) {
         },
     });
     const same = (input) => input;
+    const taskTools = Object.fromEntries((0, task_tools_1.createTaskTools)().map((task) => [task.name, task]));
     return [
         tool('read', 'read', object({
             path: text('The file or directory to read, relative to the project or absolute'),
@@ -193,11 +250,15 @@ function createOpencodeV2Tools(client, directory) {
             replaceAll: flag('Replace all occurrences of oldString (default false)'),
         }, ['path', 'oldString', 'newString']), ({ path, ...rest }) => ({ filePath: path, ...rest }), 'edit'),
         tool('patch', 'apply_patch', object({ patchText: text('The full patch text that describes all changes to be made') }, ['patchText']), same, 'edit'),
-        tool('shell', 'bash', object({
-            command: text('The command to execute'),
-            workdir: text('The directory to run the command in, relative to the project. Use this instead of cd.'),
-            timeout: count('Timeout in milliseconds, 0 for the default of the shell task'),
-        }, ['command']), ({ timeout, ...rest }) => ({ ...rest, timeout: timeout || undefined })),
+        ...(shell
+            ? [
+                tool('shell', 'bash', object({
+                    command: text('The command to execute'),
+                    workdir: text('The directory to run the command in, relative to the project. Use this instead of cd.'),
+                    timeout: count('Timeout in milliseconds, 0 for the default of the shell task'),
+                }, ['command']), ({ timeout, ...rest }) => ({ ...rest, timeout: timeout || undefined })),
+            ]
+            : []),
         tool('glob', 'glob', object({
             pattern: text('The glob pattern to match files against, like "**/*.ts"'),
             path: text('The directory to search in, the project by default'),
@@ -211,10 +272,12 @@ function createOpencodeV2Tools(client, directory) {
             caseSensitive: flag('Match case (default true)'),
             limit: count(`The maximum number of matching lines (default ${SEARCH_LIMIT})`),
         }, ['pattern']), same),
+        ...['run_task', 'run_logs', 'check'].map((name) => tool(name, name, { ...(0, task_tools_1.taskToolSchema)(taskTools[name]), additionalProperties: false }, same)),
         tool('push', 'push', object({
             branch: text('The branch to push to, created when it does not exist'),
             message: text('The commit message'),
         }, ['branch', 'message']), same),
+        ...service_tools_1.SERVICE_TOOLS.map((service) => tool(service.name, service.name, { ...(0, service_tools_1.serviceToolSchema)(service), additionalProperties: false }, same)),
     ];
 }
 exports.createOpencodeV2Tools = createOpencodeV2Tools;
@@ -227,11 +290,46 @@ const object = (properties, required) => ({
     required,
     additionalProperties: false,
 });
-function createOpencodeTools(z, client) {
-    return Object.fromEntries(Object.entries(opencodeTools(client)).map(([name, { args, ...tool }]) => [name, { ...tool, args: args(z) }]));
+function createOpencodeTools(z, client, options = {}) {
+    return Object.fromEntries(Object.entries(opencodeTools(client, options)).map(([name, { args, ...tool }]) => [
+        name,
+        { ...tool, args: args(z) },
+    ]));
 }
 exports.createOpencodeTools = createOpencodeTools;
-function opencodeTools(client) {
+// services_up, endpoint_get and services_stop, with their parameters for the zod of opencode 1
+function opencodeServiceTools(client) {
+    return Object.fromEntries(service_tools_1.SERVICE_TOOLS.map((tool) => [
+        tool.name,
+        {
+            description: tool.description,
+            args: (z) => (0, service_tools_1.serviceToolArgs)(tool, z),
+            async execute(args, context) {
+                return { title: tool.title, output: await tool.call(await client(), args, context.abort) };
+            },
+        },
+    ]));
+}
+function opencodeTools(client, options = {}) {
+    const shell = options.shell ?? connect_1.DEFAULT_SHELL_TASK;
+    const tasks = Object.fromEntries((0, task_tools_1.createTaskTools)(options.tasks, shell || undefined).map((task) => [
+        task.name,
+        {
+            description: task.description,
+            args: (z) => (0, task_tools_1.taskToolArgs)(task, z),
+            async execute(args, context) {
+                const output = await task.call(await client(), args, context.abort);
+                return {
+                    title: task.name === 'run_logs'
+                        ? `log of ${args.run}`
+                        : `${task.name === 'check' ? 'check' : 'run'} ${args.task}`,
+                    output,
+                };
+            },
+        },
+    ]));
+    // without a shell task bash still stands in for opencode's, which would run on this machine
+    const noShell = 'There is no shell on this hammerkit sandbox: run the tasks of the build file with run_task.';
     const where = (context, path) => (0, sandbox_client_1.toSandboxPath)(context.directory, path ?? context.directory);
     return inOrder({
         read: {
@@ -337,35 +435,43 @@ function opencodeTools(client) {
                 ].join('\n');
             },
         },
-        bash: {
-            description: 'Run a shell command on the hammerkit sandbox, as the shell task of the published build file, in its ' +
-                'container. Commands run one at a time and nothing is kept between them but the files. They start in ' +
-                'the root of the sandbox, where the paths of this machine do not exist: give them relative paths.',
-            args: (z) => ({
-                command: z.string().describe('The command to execute'),
-                timeout: z.number().int().min(1).optional().describe('Optional timeout in milliseconds'),
-                workdir: z
-                    .string()
-                    .optional()
-                    .describe("The working directory to run the command in. Defaults to the current directory. Use this instead of 'cd' commands."),
-            }),
-            async execute(args, context) {
-                const sandbox = await client();
-                const ran = await sandbox.exec(args.command, where(context, args.workdir), {
-                    signal: context.abort,
-                    timeoutSeconds: args.timeout ? args.timeout / 1000 : undefined,
-                });
-                const lines = [(0, format_1.capOutput)(ran.output, 'narrow the command down, for example with grep, head or tail')];
-                if (ran.exitCode === null) {
-                    lines.push(`hammerkit: ${ran.result?.error ?? ran.run.error ?? `the run ended ${ran.run.state}`}`);
-                }
-                else if (ran.exitCode !== 0) {
-                    lines.push(`Exit code: ${ran.exitCode}`);
-                }
-                context.metadata?.({ metadata: { exit: ran.exitCode, run: ran.run.id } });
-                return lines.filter((line) => line.length > 0).join('\n\n') || '(no output)';
+        bash: shell
+            ? {
+                description: 'Run a shell command on the hammerkit sandbox, as the shell task of the published build file, in its ' +
+                    'container. Commands run one at a time and nothing is kept between them but the files. They start in ' +
+                    'the root of the sandbox, where the paths of this machine do not exist: give them relative paths.',
+                args: (z) => ({
+                    command: z.string().describe('The command to execute'),
+                    timeout: z.number().int().min(1).optional().describe('Optional timeout in milliseconds'),
+                    workdir: z
+                        .string()
+                        .optional()
+                        .describe("The working directory to run the command in. Defaults to the current directory. Use this instead of 'cd' commands."),
+                }),
+                async execute(args, context) {
+                    const sandbox = await client();
+                    const ran = await sandbox.exec(args.command, where(context, args.workdir), {
+                        signal: context.abort,
+                        timeoutSeconds: args.timeout ? args.timeout / 1000 : undefined,
+                    });
+                    const lines = [(0, format_1.capOutput)(ran.output, (0, task_tools_1.readLogHint)(ran.run.id, shell))];
+                    if (ran.exitCode === null) {
+                        lines.push(`hammerkit: ${ran.result?.error ?? ran.run.error ?? `the run ended ${ran.run.state}`}`);
+                    }
+                    else if (ran.exitCode !== 0) {
+                        lines.push(`Exit code: ${ran.exitCode}`);
+                    }
+                    context.metadata?.({ metadata: { exit: ran.exitCode, run: ran.run.id } });
+                    return lines.filter((line) => line.length > 0).join('\n\n') || '(no output)';
+                },
+            }
+            : {
+                description: noShell,
+                args: (z) => ({ command: z.string().describe('The command to execute') }),
+                async execute() {
+                    throw new Error(noShell);
+                },
             },
-        },
         grep: {
             description: 'Search the files of the hammerkit sandbox with a regular expression (ripgrep). Returns the matching ' +
                 'lines with their file and line number.',
@@ -430,6 +536,7 @@ function opencodeTools(client) {
                 return lines.join('\n');
             },
         },
+        ...tasks,
         push: {
             description: 'Commit the changes of the hammerkit sandbox and push them to a branch of its repository, for review. ' +
                 'The server pushes only to the branches its operator allows; the sandbox is at the pushed commit afterwards.',
@@ -474,6 +581,7 @@ function opencodeTools(client) {
                 return lines.join('\n');
             },
         },
+        ...opencodeServiceTools(client),
     });
 }
 // opencode runs the tool calls of a step in parallel, they reach the sandbox one at a time in their order

package/dist/harness/pi.js

@@ -4,6 +4,7 @@ exports.hammerkitPiExtension = exports.createPiOperations = void 0;
 const path_1 = require("path");
 const connect_1 = require("./connect");
 const format_1 = require("./format");
+const service_tools_1 = require("./service-tools");
 const sandbox_client_1 = require("./sandbox-client");
 const IMAGE_TYPES = {
     '.png': 'image/png',
@@ -178,6 +179,34 @@ function hammerkitPiExtension(library, settings = {}) {
                 return { content: [{ type: 'text', text: `pushed ${pushed.commit} to ${pushed.branch}` }], details: pushed };
             },
         });
+        for (const tool of service_tools_1.SERVICE_TOOLS) {
+            register({
+                name: tool.name,
+                label: tool.name,
+                description: tool.description,
+                promptSnippet: tool.title,
+                parameters: (0, service_tools_1.serviceToolSchema)(tool),
+                execute: async (_id, params, signal) => {
+                    const text = await tool.call(await client(), params, signal ?? new AbortController().signal);
+                    return { content: [{ type: 'text', text }], details: undefined };
+                },
+            });
+        }
+        register({
+            name: 'check',
+            label: 'check',
+            description: sandbox_client_1.CHECK_DESCRIPTION,
+            promptSnippet: 'Run a task as a check that CI verifies after the push',
+            parameters: {
+                type: 'object',
+                properties: { task: { type: 'string', description: 'The name of the task' } },
+                required: ['task'],
+            },
+            execute: async (_id, params, signal) => {
+                const text = await (0, sandbox_client_1.runCheck)(await client(), params.task, signal);
+                return { content: [{ type: 'text', text }], details: { task: params.task } };
+            },
+        });
         pi.on('session_start', async (_event, ctx) => {
             try {
                 const sandbox = await client();

package/dist/harness/sandbox-client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.quotePosix = exports.fetchFailure = exports.toSandboxPath = exports.checkSandboxPath = exports.exitCodeOf = exports.followRun = exports.submitRun = exports.FINAL_RUN_STATES = exports.oneAtATime = exports.SandboxClient = exports.SandboxClientError = void 0;
+exports.quotePosix = exports.fetchFailure = exports.toSandboxPath = exports.checkSandboxPath = exports.exitCodeOf = exports.readRunLog = exports.getRun = exports.followRun = exports.submitRun = exports.FINAL_RUN_STATES = exports.oneAtATime = exports.SandboxClient = exports.listPublishedTasks = exports.runCheck = exports.CHECK_DESCRIPTION = exports.SandboxClientError = void 0;
 const path_1 = require("path");
 const token_source_1 = require("../remote/token-source");
 // a write carries up to 32 MiB
@@ -16,6 +16,48 @@ class SandboxClientError extends Error {
     }
 }
 exports.SandboxClientError = SandboxClientError;
+// What the agent is told of a check, on each harness.
+exports.CHECK_DESCRIPTION = 'Run a task as a check before you push, such as test or e2e: it runs on a copy of the files a push ' +
+    'would commit (what .gitignore leaves out is not there, so dependencies are installed by the tasks ' +
+    'the build file names), and when it passes, CI verifies it for that commit instead of running it. ' +
+    'Push without changing files afterwards, or the check no longer counts for the files that changed.';
+// A check, run to its end, in a few lines: how it went and the last lines of a failure.
+async function runCheck(client, task, signal) {
+    const ran = await client.runTask(task, { check: true, signal });
+    const result = ran.result;
+    const lines = [
+        result?.status === 'succeeded' || result?.status === 'cached'
+            ? `check ${task} passed (run ${ran.run.id}${result.status === 'cached' ? ', from the cache' : ''}): CI can verify it for a push of these files`
+            : `check ${task} did not pass (run ${ran.run.id}: ${result?.status ?? ran.run.state}${result?.exitCode !== undefined ? `, exit code ${result.exitCode}` : ''})`,
+    ];
+    const error = result?.error ?? ran.run.error;
+    if (error) {
+        lines.push(`error: ${error}`);
+    }
+    if (result && result.status !== 'succeeded' && result.status !== 'cached' && result.lastLog.length > 0) {
+        lines.push('last lines:', ...result.lastLog);
+    }
+    return lines.join('\n');
+}
+exports.runCheck = runCheck;
+/**
+ * The tasks of a published version, without its services, as `GET /v1/definitions/<hash>`
+ * answers them.
+ */
+async function listPublishedTasks(connection, hash) {
+    const version = await json(await call(connection, 'GET', `/v1/definitions/${hash}`));
+    return version.tasks.map((name) => {
+        const plan = version.plan?.[name];
+        const args = version.arguments?.[name];
+        return {
+            name,
+            ...(plan?.description ? { description: plan.description } : {}),
+            ...(plan && plan.command !== undefined ? { command: plan.command } : {}),
+            ...(args !== undefined ? { args } : {}),
+        };
+    });
+}
+exports.listPublishedTasks = listPublishedTasks;
 /**
  * A caller's sandbox on a hammerkit server, over its HTTP API: the raw read, write and
  * stat that harnesses plug their own tools into, the typed endpoints for clients without
@@ -34,6 +76,10 @@ class SandboxClient {
     get id() {
         return this.sandbox.id;
     }
+    // the tasks of the published version that run on the sandbox
+    tasks() {
+        return listPublishedTasks(this.connection, this.build.hash);
+    }
     static async create(connection, repo, ref) {
         return json(await call(connection, 'POST', '/v1/sandboxes', { body: { repo, ref } }));
     }
@@ -115,12 +161,13 @@ class SandboxClient {
             runOptions.args = options.args;
         }
         if (options.timeoutSeconds) {
-            runOptions.timeout = `${Math.max(1, Math.ceil(options.timeoutSeconds))}s`;
+            // a cap: it also shortens a shell task that sets a longer timeout of its own
+            runOptions.maxTimeout = `${Math.max(1, Math.ceil(options.timeoutSeconds))}s`;
         }
         const submitted = await submitRun(this.connection, {
             definition: this.build.hash,
             tasks: [task],
-            source: { type: 'sandbox', id: this.id },
+            source: { type: 'sandbox', id: this.id, ...(options.check ? { check: true } : {}) },
             options: runOptions,
         });
         const followed = await followRun(this.connection, submitted, {
@@ -138,11 +185,68 @@ class SandboxClient {
             exitCode: exitCodeOf(result),
         };
     }
+    /**
+     * Starts services of the published build file on the sandbox, or on a branch of its
+     * repository, and follows them until they are up: the run then holds their endpoints
+     * until its ttl ends or it is stopped. A signal cancels the run.
+     */
+    async up(request, options = {}) {
+        if (options.signal?.aborted) {
+            throw new SandboxClientError('the run was cancelled');
+        }
+        const submitted = await submitRun(this.connection, {
+            definition: this.build.hash,
+            services: request.services,
+            endpoints: request.endpoints ?? [],
+            ...(request.ttl ? { ttl: request.ttl } : {}),
+            ...(request.sleepTtl ? { sleepTtl: request.sleepTtl } : {}),
+            ...(request.name ? { name: request.name } : {}),
+            source: request.branch
+                ? { type: 'ref', repo: this.sandbox.repo, ref: request.branch }
+                : { type: 'sandbox', id: this.id },
+        });
+        return followRun(this.connection, submitted, { signal: options.signal, untilUp: true });
+    }
+    // Stops a run: a service run takes its services and endpoints down.
+    async stop(id) {
+        return json(await call(this.connection, 'POST', `/v1/runs/${encodeURIComponent(id)}/cancel`));
+    }
+    /**
+     * A page of an endpoint of a service run, as the caller sees it: only at an address the
+     * server gave the run, so the token goes to the server and nowhere else.
+     */
+    async fetchEndpoint(id, path, service, signal) {
+        const run = await this.getRun(id);
+        const endpoint = run.up?.endpoints.find((candidate) => service === undefined || candidate.service === service);
+        if (!endpoint) {
+            throw new SandboxClientError(run.up
+                ? `${id} has no endpoint${service ? ` of ${service}` : ''}, it has ${run.up.endpoints.map((candidate) => `${candidate.service}:${candidate.port}`).join(', ') || 'none'}`
+                : `${id} is not a service run`);
+        }
+        const url = new URL(path.startsWith('/') ? path : `/${path}`, endpoint.url);
+        if (url.origin !== new URL(endpoint.url).origin) {
+            throw new SandboxClientError(`${path} is not a path of ${endpoint.url}`);
+        }
+        const response = await fetch(url, {
+            headers: { 'hammerkit-authorization': `Bearer ${await this.connection.token()}` },
+            redirect: 'manual',
+            signal: AbortSignal.any([AbortSignal.timeout(TIMEOUT_MS), ...(signal ? [signal] : [])]),
+        });
+        return {
+            url: url.toString(),
+            status: response.status,
+            type: response.headers.get('content-type') ?? '',
+            body: await response.text(),
+        };
+    }
     /**
      * A shell command on the sandbox: the shell task of the build file with the command as
      * its argument. `cwd` is a directory of the sandbox, `''` for its root.
      */
     async exec(command, cwd, options = {}) {
+        if (!this.build.shell) {
+            throw new SandboxClientError('there is no shell on this sandbox (HAMMERKIT_SHELL is empty), run a task instead');
+        }
         // on its own line: `cd dir && a; b` would run b in the root when dir is missing
         const script = cwd && cwd !== '.' ? `cd -- ${quotePosix(cwd)} || exit 1\n${command}` : command;
         // a shell task in a container without `mounts: [.]` runs in an empty directory: the
@@ -219,7 +323,9 @@ async function followRun(connection, submitted, options = {}) {
     const cancel = () => {
         cancelling ?? (cancelling = call(connection, 'POST', `${path}/cancel`).catch(() => undefined));
     };
-    options.signal?.addEventListener('abort', cancel, { once: true });
+    if (!options.detach) {
+        options.signal?.addEventListener('abort', cancel, { once: true });
+    }
     const lines = [];
     let from = 1;
     let truncated = false;
@@ -244,6 +350,9 @@ async function followRun(connection, submitted, options = {}) {
         let run = submitted;
         let waitingSaid = false;
         for (;;) {
+            if (options.signal?.aborted && options.detach) {
+                break;
+            }
             if (options.signal?.aborted) {
                 // the process may exit after this, so the cancel has to reach the server first
                 cancel();
@@ -257,24 +366,13 @@ async function followRun(connection, submitted, options = {}) {
                 options.onWaiting?.(run);
             }
             await readLog();
-            if (exports.FINAL_RUN_STATES.includes(run.state)) {
+            if (exports.FINAL_RUN_STATES.includes(run.state) || (options.untilUp && run.state === 'up')) {
                 break;
             }
             run = await json(await call(connection, 'GET', path, { query: { wait: POLL_WAIT } }));
         }
         if (truncated) {
-            // the end of a long log is kept in the results
-            const tasks = options.task !== undefined ? [options.task] : Object.keys(run.results ?? {});
-            for (const task of tasks) {
-                const result = run.results?.[task];
-                if (!result) {
-                    continue;
-                }
-                const said = options.task !== undefined ? 'the last lines were' : `the last lines of ${task} were`;
-                for (const text of [`… the server cut the log off at its limit, ${said}:`, ...result.lastLog]) {
-                    add({ line: 0, task, stream: 'stdout', text });
-                }
-            }
+            truncatedEnd(run, options.task).forEach(add);
         }
         return { run, lines, truncated };
     }
@@ -283,6 +381,59 @@ async function followRun(connection, submitted, options = {}) {
     }
 }
 exports.followRun = followRun;
+// The end of a log the server cut off at its limit: the last lines of each task, which its
+// results keep.
+function truncatedEnd(run, only) {
+    const lines = [];
+    const tasks = only !== undefined ? [only] : Object.keys(run.results ?? {});
+    for (const task of tasks) {
+        const result = run.results?.[task];
+        if (!result) {
+            continue;
+        }
+        const said = only !== undefined ? 'the last lines were' : `the last lines of ${task} were`;
+        for (const text of [`… the server cut the log off at its limit, ${said}:`, ...result.lastLog]) {
+            lines.push({ line: 0, task, stream: 'stdout', text });
+        }
+    }
+    return lines;
+}
+// A run as the server keeps it, or null when it keeps none the caller may see.
+async function getRun(connection, id) {
+    const response = await call(connection, 'GET', `/v1/runs/${encodeURIComponent(id)}`, { missing: true });
+    return response.status === 404 ? null : json(response);
+}
+exports.getRun = getRun;
+/**
+ * Reads the log of a run as it is now, every line or the last `tail` of them, of one task or
+ * of all: also of a run that ended, as long as the server keeps it.
+ */
+async function readRunLog(connection, run, query, onLine) {
+    const path = `/v1/runs/${encodeURIComponent(run.id)}/logs`;
+    if (query.tail !== undefined) {
+        const page = await json(await call(connection, 'GET', path, { query: { task: query.task, tail: query.tail } }));
+        page.lines.forEach(onLine);
+        return { truncated: page.truncated };
+    }
+    let from = 1;
+    let truncated = false;
+    for (;;) {
+        const page = await json(await call(connection, 'GET', path, { query: { task: query.task, from, limit: 1000 } }));
+        truncated = page.truncated;
+        for (const line of page.lines) {
+            onLine(line);
+            from = line.line + 1;
+        }
+        if (!page.next) {
+            break;
+        }
+    }
+    if (truncated) {
+        truncatedEnd(run, query.task).forEach(onLine);
+    }
+    return { truncated };
+}
+exports.readRunLog = readRunLog;
 function exitCodeOf(result) {
     if (!result) {
         return null;