hammerkit 1.27.0-next.13 → 1.27.0-next.14

package/dist/harness/connect.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getHarnessEnvironment = exports.connectSandbox = exports.harnessOptionsFromEnv = exports.DEFAULT_SHELL_TASK = void 0;
+exports.getHarnessEnvironment = exports.connectSandbox = exports.connectServer = exports.hasShell = exports.harnessOptionsFromEnv = exports.DEFAULT_SHELL_TASK = void 0;
 const get_file_context_1 = require("../file/get-file-context");
 const log_1 = require("../log");
 const work_item_status_1 = require("../planner/work-item-status");
@@ -20,11 +20,21 @@ function harnessOptionsFromEnv(env) {
         repo: value('HAMMERKIT_REPO'),
         ref: value('HAMMERKIT_REF'),
         build: value('HAMMERKIT_BUILD'),
-        shell: value('HAMMERKIT_SHELL'),
+        // set but empty is no shell, unset the default one
+        shell: env.HAMMERKIT_SHELL !== undefined ? env.HAMMERKIT_SHELL.trim() : undefined,
     };
 }
 exports.harnessOptionsFromEnv = harnessOptionsFromEnv;
-async function connectSandbox(environment, options, log = () => undefined) {
+// whether the clients offer a shell tool
+function hasShell(options) {
+    return options.shell !== '';
+}
+exports.hasShell = hasShell;
+/**
+ * The registered server a harness works on and the published version it runs, checked:
+ * what the clients need to list the tasks of the version before they take a sandbox.
+ */
+async function connectServer(environment, options) {
     const config = await (0, host_config_1.readHostConfig)(environment);
     const name = options.server ?? config.run.on;
     if (!name || !(0, host_config_1.hasServer)(config.servers, name)) {
@@ -40,7 +50,11 @@ async function connectSandbox(environment, options, log = () => undefined) {
         throw new Error(`${options.build} is not the hash of a published version (sha256:...), name it as hammerkit remote publish printed it (HAMMERKIT_BUILD or --build)`);
     }
     const server = config.servers[name];
-    const connection = { url: server.url, ...(0, token_source_1.getTokenSource)(environment, name, server) };
+    return { name, connection: { url: server.url, ...(0, token_source_1.getTokenSource)(environment, name, server) }, build: options.build };
+}
+exports.connectServer = connectServer;
+async function connectSandbox(environment, options, log = () => undefined) {
+    const { name, connection, build } = await connectServer(environment, options);
     let sandbox;
     if (options.sandbox) {
         sandbox = await sandbox_client_1.SandboxClient.get(connection, options.sandbox);
@@ -59,7 +73,7 @@ async function connectSandbox(environment, options, log = () => undefined) {
     else {
         throw new Error('name a sandbox (HAMMERKIT_SANDBOX or --sandbox), or a repository and ref to create one from (HAMMERKIT_REPO and HAMMERKIT_REF, or --repo and --ref)');
     }
-    return new sandbox_client_1.SandboxClient(connection, sandbox, { hash: options.build, shell: options.shell ?? exports.DEFAULT_SHELL_TASK });
+    return new sandbox_client_1.SandboxClient(connection, sandbox, { hash: build, shell: options.shell ?? exports.DEFAULT_SHELL_TASK });
 }
 exports.connectSandbox = connectSandbox;
 // A client that starts with a repository and ref takes a sandbox of the caller's of the same

package/dist/harness/mcp-command.js

@@ -6,6 +6,15 @@ const log_1 = require("../log");
 const version_1 = require("../version");
 const connect_1 = require("./connect");
 const mcp_1 = require("./mcp");
+const task_tools_1 = require("./task-tools");
+// the tasks run_task lists; a server that does not answer leaves them out, the tools still work
+async function listTasks(sandbox, log) {
+    const listing = await (0, task_tools_1.readTaskListing)(() => sandbox.tasks());
+    if (!Array.isArray(listing)) {
+        log(`the tasks of ${sandbox.build.hash} could not be listed: ${listing.error}`);
+    }
+    return listing;
+}
 // `hammerkit remote mcp`: a Model Context Protocol server on stdio for one sandbox of a
 // server. It lives under `remote`, which already is a command: a top-level `mcp` would hide a
 // task named `mcp`, since `hammerkit <task>` runs a task. Like the other `remote` commands it
@@ -21,20 +30,27 @@ function registerMcpCommand(remote, environment, input = process.stdin) {
         .addOption(new commander_1.Option('--repo <repo>', 'create a sandbox of this repository').env('HAMMERKIT_REPO'))
         .addOption(new commander_1.Option('--ref <ref>', 'at this branch').env('HAMMERKIT_REF'))
         .addOption(new commander_1.Option('--build <hash>', 'hash of the published version of the build file whose tasks run on it').env('HAMMERKIT_BUILD'))
-        .addOption(new commander_1.Option('--shell <task>', 'its task whose last command is a shell, like sh -c')
+        .addOption(new commander_1.Option('--shell <task>', "its task whose last command is a shell, like sh -c; '' for no bash tool")
         .env('HAMMERKIT_SHELL')
         .default(connect_1.DEFAULT_SHELL_TASK))
         .action(async (options) => {
         try {
             // stdout carries the protocol only, everything else goes to stderr
             const log = (line) => environment.stderr.write(`hammerkit remote mcp: ${line}\n`);
-            const sandbox = await (0, connect_1.connectSandbox)(environment, options, log);
+            // as the plugins read it: blank is no shell
+            const sandbox = await (0, connect_1.connectSandbox)(environment, { ...options, shell: options.shell.trim() }, log);
             log(`sandbox ${sandbox.id} of ${sandbox.sandbox.repo} at ${sandbox.sandbox.commit}`);
+            const shell = sandbox.build.shell;
             const instructions = `The tools work on hammerkit sandbox ${sandbox.id}, a checkout of ${sandbox.sandbox.repo} at ` +
-                `${sandbox.sandbox.commit} on a server. Paths are relative to its root. bash runs a command as the ` +
-                `task ${sandbox.build.shell} of the published build file ${sandbox.build.hash}, run_task runs its other ` +
-                'tasks; only the files are kept between commands. changes shows what changed since the fetch.';
-            const served = (0, mcp_1.serveMcp)(input, environment.stdout, (0, mcp_1.createMcpTools)(async () => sandbox), {
+                `${sandbox.sandbox.commit} on a server. Paths are relative to its root. ` +
+                (shell
+                    ? `bash runs a command as the task ${shell} of the published build file ${sandbox.build.hash}, ` +
+                        'run_task runs its other tasks; only the files are kept between commands. '
+                    : `run_task runs the tasks of the published build file ${sandbox.build.hash}; only the files are ` +
+                        'kept between runs. ') +
+                'changes shows what changed since the fetch.';
+            const tasks = await listTasks(sandbox, log);
+            const served = (0, mcp_1.serveMcp)(input, environment.stdout, (0, mcp_1.createMcpTools)(async () => sandbox, { tasks, shell: shell || false }), {
                 name: 'hammerkit',
                 version: (0, version_1.getVersion)(),
                 instructions,

package/dist/harness/mcp.js

@@ -4,6 +4,7 @@ exports.serveMcp = exports.createMcpTools = void 0;
 const readline_1 = require("readline");
 const format_1 = require("./format");
 const sandbox_client_1 = require("./sandbox-client");
+const task_tools_1 = require("./task-tools");
 // the newest first; a client asking for an older one gets it
 const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 const READ_ONLY = { readOnlyHint: true, openWorldHint: false };
@@ -25,40 +26,47 @@ const flag = (description) => ({ type: 'boolean', description });
 function sandboxPath(path) {
     return (path ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
 }
-function readLog(run, task) {
-    return `read more of the log with run_logs { "run": "${run}", "task": "${task}" }`;
-}
-function describeRun(task, ran) {
-    const result = ran.result;
-    const lines = [`run ${ran.run.id}: ${ran.run.state}`];
-    if (result) {
-        lines.push(`task ${task}: ${result.status}` +
-            (result.exitCode !== undefined ? `, exit code ${result.exitCode}` : '') +
-            (result.durationMs !== undefined ? `, ${result.durationMs} ms` : '') +
-            (result.cache?.hit ? ', from the cache' : ''));
-        if (result.error) {
-            lines.push(`error: ${result.error}`);
-        }
-        if (result.cache?.causes?.length) {
-            lines.push(`ran because: ${result.cache.causes.join('; ')}`);
-        }
-    }
-    else if (ran.run.error) {
-        lines.push(`error: ${ran.run.error}`);
-    }
-    if (result && result.lastLog.length > 0) {
-        lines.push('last lines:', ...result.lastLog);
-    }
-    lines.push(readLog(ran.run.id, task));
-    return lines.join('\n');
-}
 /**
  * The tools of `hammerkit remote mcp`, for chat clients and agents without file and shell tools of
  * their own. They take the shapes models are trained on: numbered reads with offset and
  * limit, exact-string replace, `apply_patch` or a git diff, ripgrep's parameters, a shell
- * command. Paths are relative to the root of the sandbox.
+ * command. Paths are relative to the root of the sandbox. `tasks` are the tasks the description
+ * of `run_task` lists; without `shell` there is no `bash`.
  */
-function createMcpTools(client) {
+function createMcpTools(client, options = {}) {
+    const [runTask, runLogs] = (0, task_tools_1.createTaskTools)(options.tasks, options.shell || undefined).map((tool) => fromTaskTool(tool, client));
+    const bash = {
+        name: 'bash',
+        description: 'Run a shell command on the sandbox and answer its output and exit code. It runs as the shell task of ' +
+            'the published build file, in its container and with its network; commands run one at a time, and ' +
+            'only the files are kept between them.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: text('The command'),
+                workdir: text('The directory to run it in, relative to the root of the sandbox'),
+                timeout: count('Stop the command after this many seconds', 1),
+            },
+            required: ['command'],
+        },
+        annotations: { title: 'Run a command' },
+        async call(args, signal) {
+            const sandbox = await client();
+            const ran = await sandbox.exec(args.command, sandboxPath(args.workdir), {
+                signal,
+                timeoutSeconds: args.timeout,
+            });
+            const output = (0, format_1.capOutput)(ran.output, (0, task_tools_1.readLogHint)(ran.run.id, sandbox.build.shell));
+            const lines = output ? [output, ''] : [];
+            if (ran.exitCode === null) {
+                lines.push(`hammerkit: ${ran.result?.error ?? ran.run.error ?? `the run ended ${ran.run.state}`}`);
+            }
+            else {
+                lines.push(`exit code ${ran.exitCode}`);
+            }
+            return lines.join('\n');
+        },
+    };
     return inOrder([
         {
             name: 'read',
@@ -185,91 +193,9 @@ function createMcpTools(client) {
                 return (0, format_1.formatTree)(await (await client()).tree({ path, glob: args.pattern, limit: 500 }));
             },
         },
-        {
-            name: 'bash',
-            description: 'Run a shell command on the sandbox and answer its output and exit code. It runs as the shell task of ' +
-                'the published build file, in its container and with its network; commands run one at a time, and ' +
-                'only the files are kept between them.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    command: text('The command'),
-                    workdir: text('The directory to run it in, relative to the root of the sandbox'),
-                    timeout: count('Stop the command after this many seconds', 1),
-                },
-                required: ['command'],
-            },
-            annotations: { title: 'Run a command' },
-            async call(args, signal) {
-                const sandbox = await client();
-                const ran = await sandbox.exec(args.command, sandboxPath(args.workdir), {
-                    signal,
-                    timeoutSeconds: args.timeout,
-                });
-                const output = (0, format_1.capOutput)(ran.output, readLog(ran.run.id, sandbox.build.shell));
-                const lines = output ? [output, ''] : [];
-                if (ran.exitCode === null) {
-                    lines.push(`hammerkit: ${ran.result?.error ?? ran.run.error ?? `the run ended ${ran.run.state}`}`);
-                }
-                else {
-                    lines.push(`exit code ${ran.exitCode}`);
-                }
-                return lines.join('\n');
-            },
-        },
-        {
-            name: 'run_task',
-            description: 'Run a task of the published build file on the sandbox, such as test or build, and answer how it went: ' +
-                'its status, exit code, why it was not taken from the cache, and its last lines. args are appended to ' +
-                'its last command, for example a test file.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    task: text('The name of the task'),
-                    args: { type: 'array', items: { type: 'string' }, description: 'Arguments for its last command' },
-                },
-                required: ['task'],
-            },
-            annotations: { title: 'Run a task' },
-            async call(args, signal) {
-                const ran = await (await client()).runTask(args.task, { args: args.args, signal });
-                return describeRun(args.task, ran);
-            },
-        },
-        {
-            name: 'run_logs',
-            description: 'Read the log of a run as numbered lines: one task, the last lines (tail), a range (from, limit) or ' +
-                'the lines that contain a text (grep, a fixed string) with lines of context around them.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    run: text('The id of the run'),
-                    task: text('Only the lines of this task'),
-                    tail: count('The last lines, or with grep the last matches', 1, 1000),
-                    from: count('The first line to read', 1),
-                    limit: count('How many lines to read', 1, 1000),
-                    grep: text('Only lines that contain this text'),
-                    ignore_case: flag('Ignore case in grep'),
-                    context: count('Lines before and after each match', 0, 20),
-                },
-                required: ['run'],
-            },
-            annotations: { title: 'Read the log of a run', ...READ_ONLY },
-            async call(args) {
-                const page = await (await client()).logs(args.run, {
-                    task: args.task,
-                    tail: args.tail,
-                    from: args.from,
-                    limit: args.limit,
-                    grep: args.grep,
-                    i: args.ignore_case,
-                    context: args.context,
-                });
-                const lines = page.lines.map((line) => `${line.line}${line.match === false ? '-' : ':'} ${args.task ? '' : `[${line.task}] `}${line.text}`);
-                lines.push('', `(${page.total} lines${args.grep ? ` searched, ${page.lines.filter((line) => line.match !== false).length} match here` : ''}${page.next ? `, read on with from ${page.next}` : ''}${page.truncated ? ', the server cut the log off at its limit' : ''})`);
-                return lines.join('\n');
-            },
-        },
+        ...(options.shell === false ? [] : [bash]),
+        runTask,
+        { ...runLogs, annotations: { ...runLogs.annotations, ...READ_ONLY } },
         {
             name: 'changes',
             description: 'What changed in the sandbox since the commit it was fetched at: a summary of the files, a diff, or a ' +
@@ -318,6 +244,18 @@ function createMcpTools(client) {
     ]);
 }
 exports.createMcpTools = createMcpTools;
+// a tool shared with the other harnesses, as an MCP tool
+function fromTaskTool(tool, client) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: (0, task_tools_1.taskToolSchema)(tool),
+        annotations: { title: tool.title },
+        async call(args, signal) {
+            return tool.call(await client(), args, signal);
+        },
+    };
+}
 // the calls of a client go to the sandbox one at a time, in the order the client sent them
 function inOrder(tools) {
     const inTurn = (0, sandbox_client_1.oneAtATime)();

package/dist/harness/opencode.js

@@ -9,35 +9,64 @@ 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 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',
+];
 /**
  * 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 +140,18 @@ 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',
+];
 // 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 +160,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 +209,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 +223,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 +241,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,6 +263,7 @@ 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'),
@@ -227,11 +280,28 @@ 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) {
+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 +407,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 +508,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.',

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 } }));
     }
@@ -144,6 +166,9 @@ class SandboxClient {
      * 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

package/dist/harness/task-tools.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskToolArgs = exports.taskToolSchema = exports.createTaskTools = exports.describeTasks = exports.describeRun = exports.readLogHint = exports.readTaskListing = exports.LIST_TASKS_MS = void 0;
+// the most tasks a description lists, and of a task's description or command it shows
+const MAX_LISTED = 40;
+const MAX_DESCRIPTION_CHARS = 200;
+const MAX_COMMAND_CHARS = 100;
+// how long a client waits for the tasks of the build file when it starts, it goes on without them
+exports.LIST_TASKS_MS = 15000;
+// The tasks of the published version, or why they could not be read within `ms`.
+async function readTaskListing(list, ms = exports.LIST_TASKS_MS) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no answer within ${ms / 1000} s`)), ms);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([list(), timeout]);
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+exports.readTaskListing = readTaskListing;
+// the hint at the end of a cut output or a result, for the model
+function readLogHint(run, task) {
+    return `read more of the log with run_logs { "run": "${run}", "task": "${task}" }`;
+}
+exports.readLogHint = readLogHint;
+// A run of a task in a few lines: how it went, why it ran, its last lines.
+function describeRun(task, ran) {
+    const result = ran.result;
+    const lines = [`run ${ran.run.id}: ${ran.run.state}`];
+    if (result) {
+        lines.push(`task ${task}: ${result.status}` +
+            (result.exitCode !== undefined ? `, exit code ${result.exitCode}` : '') +
+            (result.durationMs !== undefined ? `, ${result.durationMs} ms` : '') +
+            (result.cache?.hit ? ', from the cache' : ''));
+        if (result.error) {
+            lines.push(`error: ${result.error}`);
+        }
+        if (result.cache?.causes?.length) {
+            lines.push(`ran because: ${result.cache.causes.join('; ')}`);
+        }
+    }
+    else if (ran.run.error) {
+        lines.push(`error: ${ran.run.error}`);
+    }
+    if (result && result.lastLog.length > 0) {
+        lines.push('last lines:', ...result.lastLog);
+    }
+    lines.push(readLogHint(ran.run.id, task));
+    return lines.join('\n');
+}
+exports.describeRun = describeRun;
+/**
+ * The tasks for the model, one line each: what it is for (or its command, when the build
+ * file says nothing) and whether it takes arguments. `shell` is left out, the shell tool runs it.
+ */
+function describeTasks(listing, shell) {
+    if (listing === undefined) {
+        return '';
+    }
+    if (!Array.isArray(listing)) {
+        return `The tasks of the build file could not be listed (${listing.error}); name one as the build file does.`;
+    }
+    const tasks = listing.filter((task) => !shell || task.name !== shell);
+    if (tasks.length === 0) {
+        return 'The published build file has no tasks to run.';
+    }
+    const lines = tasks.slice(0, MAX_LISTED).map((task) => {
+        const parts = [`- ${task.name}`];
+        if (task.description) {
+            parts.push(`: ${cut(oneLine(task.description), MAX_DESCRIPTION_CHARS)}`);
+        }
+        else if (task.command) {
+            parts.push(`: runs \`${cut(oneLine(task.command), MAX_COMMAND_CHARS)}\``);
+        }
+        if (task.args === null) {
+            parts.push(' (takes args)');
+        }
+        else if (task.args !== undefined || task.command === null) {
+            parts.push(' (takes no args)');
+        }
+        return parts.join('');
+    });
+    if (tasks.length > MAX_LISTED) {
+        lines.push(`- and ${tasks.length - MAX_LISTED} more`);
+    }
+    return ['The tasks of the published build file:', ...lines].join('\n');
+}
+exports.describeTasks = describeTasks;
+function oneLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function cut(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+/**
+ * `run_task` and `run_logs`, with the tasks the description of `run_task` lists. Without a
+ * listing it names none, as the MCP tools before a version could be read.
+ */
+function createTaskTools(listing, shell) {
+    const tasks = describeTasks(listing, shell);
+    return [
+        {
+            name: 'run_task',
+            title: 'Run a task',
+            description: 'Run a task of the published build file on the sandbox, such as test or build, and answer how it went: ' +
+                'its status, exit code, why it was not taken from the cache, and its last lines. args are appended to ' +
+                'its last command, for example a test file. It runs in the container, with the network and the ' +
+                'options the build file gives the task.' +
+                (tasks ? `\n\n${tasks}` : ''),
+            parameters: {
+                task: { type: 'string', description: 'The name of the task' },
+                args: { type: 'string[]', description: 'Arguments for its last command' },
+            },
+            required: ['task'],
+            async call(client, args, signal) {
+                const ran = await client.runTask(args.task, { args: args.args?.length ? args.args : undefined, signal });
+                return describeRun(args.task, ran);
+            },
+        },
+        {
+            name: 'run_logs',
+            title: 'Read the log of a run',
+            description: 'Read the log of a run as numbered lines: one task, the last lines (tail), a range (from, limit) or ' +
+                'the lines that contain a text (grep, a fixed string) with lines of context around them.',
+            parameters: {
+                run: { type: 'string', description: 'The id of the run' },
+                task: { type: 'string', description: 'Only the lines of this task' },
+                tail: {
+                    type: 'integer',
+                    description: 'The last lines, or with grep the last matches',
+                    minimum: 1,
+                    maximum: 1000,
+                },
+                from: { type: 'integer', description: 'The first line to read', minimum: 1 },
+                limit: { type: 'integer', description: 'How many lines to read', minimum: 1, maximum: 1000 },
+                grep: { type: 'string', description: 'Only lines that contain this text' },
+                ignore_case: { type: 'boolean', description: 'Ignore case in grep' },
+                context: { type: 'integer', description: 'Lines before and after each match', minimum: 0, maximum: 20 },
+            },
+            required: ['run'],
+            async call(client, args) {
+                const page = await client.logs(args.run, {
+                    task: args.task || undefined,
+                    tail: args.tail || undefined,
+                    from: args.from || undefined,
+                    limit: args.limit || undefined,
+                    grep: args.grep || undefined,
+                    i: args.ignore_case || undefined,
+                    context: args.context || undefined,
+                });
+                const lines = page.lines.map((line) => `${line.line}${line.match === false ? '-' : ':'} ${args.task ? '' : `[${line.task}] `}${line.text}`);
+                lines.push('', `(${page.total} lines${args.grep ? ` searched, ${page.lines.filter((line) => line.match !== false).length} match here` : ''}${page.next ? `, read on with from ${page.next}` : ''}${page.truncated ? ', the server cut the log off at its limit' : ''})`);
+                return lines.join('\n');
+            },
+        },
+    ];
+}
+exports.createTaskTools = createTaskTools;
+// The parameters as a JSON schema, for MCP and opencode 2.
+function taskToolSchema(tool) {
+    return {
+        type: 'object',
+        properties: Object.fromEntries(Object.entries(tool.parameters).map(([name, parameter]) => {
+            if (parameter.type === 'string[]') {
+                return [name, { type: 'array', items: { type: 'string' }, description: parameter.description }];
+            }
+            if (parameter.type === 'integer') {
+                const { maximum } = parameter;
+                return [
+                    name,
+                    {
+                        type: 'integer',
+                        description: parameter.description,
+                        minimum: parameter.minimum,
+                        ...(maximum !== undefined ? { maximum } : {}),
+                    },
+                ];
+            }
+            return [name, { type: parameter.type, description: parameter.description }];
+        })),
+        required: tool.required,
+    };
+}
+exports.taskToolSchema = taskToolSchema;
+// The parameters with the zod of opencode 1.
+function taskToolArgs(tool, z) {
+    return Object.fromEntries(Object.entries(tool.parameters).map(([name, parameter]) => {
+        let type;
+        if (parameter.type === 'string[]') {
+            type = z.array(z.string());
+        }
+        else if (parameter.type === 'integer') {
+            type = z.number().int().min(parameter.minimum);
+            type = parameter.maximum !== undefined ? type.max(parameter.maximum) : type;
+        }
+        else {
+            type = parameter.type === 'boolean' ? z.boolean() : z.string();
+        }
+        return [name, (tool.required.includes(name) ? type : type.optional()).describe(parameter.description)];
+    }));
+}
+exports.taskToolArgs = taskToolArgs;
+//# sourceMappingURL=task-tools.js.map

package/dist/server/definitions-api.js

@@ -5,6 +5,7 @@ const zod_1 = require("zod");
 const bundle_1 = require("../remote/bundle");
 const definitions_1 = require("./definitions");
 const http_1 = require("./http");
+const run_plan_1 = require("./run-plan");
 const oauth_1 = require("./oauth");
 const policy_1 = require("./policy");
 const proposals_1 = require("./proposals");
@@ -19,7 +20,8 @@ const MAX_PUBLISH_BYTES = bundle_1.MAX_BUNDLE_BYTES * 2;
  *                                        `annotations`, which are not part of the hash
  *   GET  /v1/definitions                 the versions, newest first; `?<key>=<value>`
  *                                        keeps the ones with those annotations
- *   GET  /v1/definitions/<hash>          one version
+ *   GET  /v1/definitions/<hash>          one version, with `arguments`: per task null when
+ *                                        a run of it may pass arguments, else why not
  *   GET  /v1/definitions/<hash>/files    its files
  *   POST /v1/definitions/<hash>/yank     pull it back (body: optional {reason})
  *   POST /v1/definitions/<hash>/unyank   let it go on
@@ -72,7 +74,7 @@ async function handleDefinitions(config, store, proposals, log, principal, req,
         bundle ? (0, http_1.send)(res, 200, bundle) : (0, http_1.send)(res, 404, { error: 'not found' });
     }
     else {
-        (0, http_1.send)(res, 200, found);
+        (0, http_1.send)(res, 200, found.plan ? { ...found, arguments: (0, run_plan_1.describeArguments)(found.plan, config.runs) } : found);
     }
     return true;
 }

package/dist/server/plan.js

@@ -284,6 +284,7 @@ function toPlan(root, item) {
     const isTask = data.type === 'local-task' || data.type === 'container-task';
     return {
         kind: isTask ? 'task' : 'service',
+        ...(data.description ? { description: data.description } : {}),
         runtime: data.type === 'local-task' ? 'local' : 'docker',
         ...((0, work_task_1.isContainerWorkTask)(data) || (0, work_service_1.isContainerWorkService)(data) ? { image: data.image } : {}),
         cmds: 'cmds' in data ? data.cmds.map((cmd) => cmd.cmd) : 'cmd' in data && data.cmd ? [data.cmd.cmd] : [],

package/dist/server/run-plan.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.refuseArguments = exports.planRun = exports.getRunScopes = void 0;
+exports.describeArguments = exports.refuseArguments = exports.planRun = exports.getRunScopes = void 0;
 const parse_label_arguments_1 = require("../parser/parse-label-arguments");
 const plan_1 = require("./plan");
 function labels(values) {
@@ -87,4 +87,34 @@ function refuseArguments(run, plan, policy = {}) {
     return null;
 }
 exports.refuseArguments = refuseArguments;
+/**
+ * For each task of a version, whether a run of it alone may pass arguments: null when it may,
+ * else why not, as {@link refuseArguments} answers a run. The plan is the one of the whole
+ * version: a task's run is the task with its dependencies and services.
+ */
+function describeArguments(plan, policy = {}) {
+    const described = {};
+    for (const [name, entry] of Object.entries(plan)) {
+        if (entry.kind !== 'task') {
+            continue;
+        }
+        const run = {};
+        const visit = (item) => {
+            if (run[item] || !plan[item]) {
+                return;
+            }
+            run[item] = plan[item];
+            for (const next of [...plan[item].deps, ...plan[item].needs]) {
+                visit(next);
+            }
+        };
+        visit(name);
+        described[name] =
+            entry.command === null
+                ? `${name} has no command to take arguments`
+                : refuseArguments({ tasks: [name], options: { args: ['-'] } }, run, policy);
+    }
+    return described;
+}
+exports.describeArguments = describeArguments;
 //# sourceMappingURL=run-plan.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hammerkit",
   "description": "Containerized build tool with incremental caching that runs the same build file locally, in Docker and on Kubernetes.",
-  "version": "1.27.0-next.13",
+  "version": "1.27.0-next.14",
   "keywords": [
     "build",
     "build-tool",