hammerkit 1.27.0-next.13 → 1.27.0-next.15

package/dist/harness/opencode.js

@@ -9,35 +9,68 @@ 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',
+    '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 +144,21 @@ 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',
+    '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 +167,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 +216,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 +230,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 +248,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 +270,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'].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 +288,41 @@ 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_task' ? `run ${args.task}` : `log of ${args.run}`, 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 +428,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 +529,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 +574,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,19 @@ 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 };
+                },
+            });
+        }
         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.followRun = exports.submitRun = exports.FINAL_RUN_STATES = exports.oneAtATime = exports.SandboxClient = exports.listPublishedTasks = 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,24 @@ class SandboxClientError extends Error {
     }
 }
 exports.SandboxClientError = SandboxClientError;
+/**
+ * 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 +52,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 } }));
     }
@@ -139,11 +161,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
@@ -258,7 +337,7 @@ 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 } }));

package/dist/harness/service-tools.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_TOOLS = exports.describeServiceRun = exports.parseEndpoint = exports.serviceToolArgs = exports.serviceToolSchema = void 0;
+// the most of a page an agent gets back
+const MAX_PAGE_CHARS = 20000;
+// The parameters as a JSON schema, for MCP, pi and opencode 2.
+function serviceToolSchema(tool) {
+    return {
+        type: 'object',
+        properties: Object.fromEntries(Object.entries(tool.parameters).map(([name, parameter]) => [
+            name,
+            parameter.type === 'string'
+                ? { type: 'string', description: parameter.description }
+                : { type: 'array', items: { type: 'string' }, description: parameter.description },
+        ])),
+        required: tool.required,
+    };
+}
+exports.serviceToolSchema = serviceToolSchema;
+// The parameters with the zod of opencode 1.
+function serviceToolArgs(tool, z) {
+    return Object.fromEntries(Object.entries(tool.parameters).map(([name, parameter]) => {
+        const type = parameter.type === 'string' ? z.string() : z.array(z.string());
+        return [name, (tool.required.includes(name) ? type : type.optional()).describe(parameter.description)];
+    }));
+}
+exports.serviceToolArgs = serviceToolArgs;
+// `web:8080` as the server takes an endpoint
+function parseEndpoint(value) {
+    const index = value.lastIndexOf(':');
+    const port = Number(value.slice(index + 1));
+    if (index <= 0 || !Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${value} is not an endpoint, write it as service:port, such as web:8080`);
+    }
+    return { service: value.slice(0, index), port };
+}
+exports.parseEndpoint = parseEndpoint;
+// How a service run stands, for an agent: where its endpoints are and until when.
+function describeServiceRun(run) {
+    const lines = [`run ${run.id}: ${run.state}${run.up ? ` (${run.up.name})` : ''}`];
+    if (run.state === 'up') {
+        lines.push(`up until ${run.expiresAt}, stop it with services_stop when it is no longer needed`);
+        if (run.up?.sleepTtl) {
+            lines.push('without a request for a while the services sleep, the next request wakes them');
+        }
+        for (const endpoint of run.up?.endpoints ?? []) {
+            lines.push(`${endpoint.service}:${endpoint.port} -> ${endpoint.url}`);
+        }
+        if ((run.up?.endpoints ?? []).length > 0) {
+            lines.push('a person opens these addresses in a browser and signs in; read a page yourself with endpoint_get');
+        }
+    }
+    else if (run.error) {
+        lines.push(`error: ${run.error}`);
+    }
+    for (const [task, result] of Object.entries(run.results ?? {})) {
+        if (result.status === 'failed') {
+            lines.push(`${task} failed${result.error ? `: ${result.error}` : ''}`, ...result.lastLog);
+        }
+    }
+    if (run.state !== 'up') {
+        lines.push(`read the log with run_logs { "run": "${run.id}" }`);
+    }
+    return lines.join('\n');
+}
+exports.describeServiceRun = describeServiceRun;
+exports.SERVICE_TOOLS = [
+    {
+        name: 'services_up',
+        title: 'Start services',
+        description: 'Start services of the published build file on the hammerkit server, with the files of the sandbox (or of ' +
+            'a branch), and keep them up for a person to look at: each endpoint (service:port) gets an address of its ' +
+            'own behind the sign-in of the server. Answers once they are up, with the addresses and until when they ' +
+            'stay. A second start with the same name replaces the first, so its addresses stay the same. A server on ' +
+            'Kubernetes starts services from a branch only: push the sandbox and pass branch.',
+        parameters: {
+            services: { type: 'string[]', description: 'The services to start, as the build file names them' },
+            endpoints: { type: 'string[]', description: 'The ports to publish, as service:port, such as web:8080' },
+            ttl: {
+                type: 'string',
+                description: 'How long they stay once ready, such as 2h, then they are removed; the server default when left out',
+            },
+            sleepTtl: {
+                type: 'string',
+                description: 'How long they stay up without a request, such as 30m, then they sleep until the next request wakes ' +
+                    'them (from a branch only); the server default when left out',
+            },
+            name: {
+                type: 'string',
+                description: 'Lower case letters, digits and -; the addresses carry it. The branch when left out',
+            },
+            branch: {
+                type: 'string',
+                description: 'Start from this pushed branch of the repository instead of the files of the sandbox',
+            },
+        },
+        required: ['services'],
+        async call(client, args, signal) {
+            const followed = await client.up({
+                services: args.services,
+                endpoints: (args.endpoints ?? []).map(parseEndpoint),
+                ttl: args.ttl || undefined,
+                sleepTtl: args.sleepTtl || undefined,
+                name: args.name || undefined,
+                branch: args.branch || undefined,
+            }, { signal });
+            return describeServiceRun(followed.run);
+        },
+    },
+    {
+        name: 'endpoint_get',
+        title: 'Read a page of an endpoint',
+        description: 'GET a path of an endpoint of a service run started with services_up, signed in as you, and answer its ' +
+            'status and body: to check that the app answers before a person opens it.',
+        parameters: {
+            run: { type: 'string', description: 'The id of the service run' },
+            path: { type: 'string', description: 'The path, such as / or /api/health' },
+            service: { type: 'string', description: 'The service of the endpoint, the first endpoint when left out' },
+        },
+        required: ['run', 'path'],
+        async call(client, args, signal) {
+            const page = await client.fetchEndpoint(args.run, args.path, args.service || undefined, signal);
+            const body = page.body.length > MAX_PAGE_CHARS
+                ? `${page.body.slice(0, MAX_PAGE_CHARS)}\n… (${page.body.length} characters, the first ${MAX_PAGE_CHARS} shown)`
+                : page.body;
+            return [`GET ${page.url}: ${page.status}${page.type ? ` (${page.type})` : ''}`, '', body].join('\n');
+        },
+    },
+    {
+        name: 'services_stop',
+        title: 'Stop services',
+        description: 'Stop a service run started with services_up: its services and endpoints go.',
+        parameters: { run: { type: 'string', description: 'The id of the service run' } },
+        required: ['run'],
+        async call(client, args) {
+            const run = await client.stop(args.run);
+            return `run ${run.id}: ${run.state === 'up' ? 'stopping' : run.state}`;
+        },
+    },
+];
+//# sourceMappingURL=service-tools.js.map