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

package/dist/docker/item-network.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeOrphanedNetworks = exports.removeItemNetworks = exports.getNetworkHostConfig = exports.removeItemNetwork = exports.prepareItemNetwork = exports.checkNetworkLimitSupport = exports.getProxyNetworkName = exports.getRunNetworkName = exports.getItemNetworkName = void 0;
+exports.removeOrphanedNetworks = exports.removeItemNetworks = exports.getNetworkHostConfig = exports.getPortBinding = exports.removeItemNetwork = exports.prepareItemNetwork = exports.checkNetworkLimitSupport = exports.getProxyNetworkName = exports.getRunNetworkName = exports.getItemNetworkName = void 0;
 const readline_1 = require("readline");
 const stream_1 = require("stream");
 const work_service_1 = require("../planner/work-service");
@@ -258,7 +258,7 @@ options) {
         await removeItemNetwork(docker, name);
         throw e;
     }
-    const publish = (options.publish ?? []).filter((port) => !!port.hostPort);
+    const publish = (options.publish ?? []).filter((port) => port.hostPort !== null);
     return {
         options: {
             mode: name,
@@ -272,8 +272,9 @@ options) {
                     await docker.getNetwork(getProxyNetworkName(name)).connect({ Container: container.id });
                 }
                 if (publish.length > 0) {
-                    await startPortRelay(docker, item, environment, name, container, publish, options);
+                    return await startPortRelay(docker, item, environment, name, container, publish, options);
                 }
+                return undefined;
             }
             catch (e) {
                 await removeItemNetwork(docker, name);
@@ -374,12 +375,13 @@ async function startPortRelay(docker, item, environment, networkName, service, p
         ExposedPorts: Object.fromEntries(ports.map((port) => [`${port.containerPort}/tcp`, {}])),
         HostConfig: {
             ...HELPER_HOST_CONFIG,
-            PortBindings: Object.fromEntries(ports.map((port) => [`${port.containerPort}/tcp`, [{ HostPort: `${port.hostPort}` }]])),
+            PortBindings: Object.fromEntries(ports.map((port) => [`${port.containerPort}/tcp`, [getPortBinding(port)]])),
         },
     });
     await docker.getNetwork(networkName).connect({ Container: container.id });
     await container.start();
-    item.status.write('debug', `ports ${ports.map((port) => port.hostPort).join(', ')} published by a relay`);
+    item.status.write('debug', `ports ${ports.map((port) => port.hostPort || 'any').join(', ')} published by a relay`);
+    return container;
 }
 // The network, its proxy network, its proxy and relay, and every endpoint on
 // them: what an earlier run left behind, or what the item used.
@@ -429,6 +431,12 @@ async function removeNetwork(docker, name) {
         }
     }
 }
+// A port of the host for a port of a container: a free one for 0, on one address of it
+// when the port names one.
+function getPortBinding(port) {
+    return { HostPort: port.hostPort ? `${port.hostPort}` : '', ...(port.hostIp ? { HostIp: port.hostIp } : {}) };
+}
+exports.getPortBinding = getPortBinding;
 function getNetworkHostConfig(network) {
     return {
         ...(network.mode ? { NetworkMode: network.mode } : {}),

package/dist/executer/docker-service.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dockerService = exports.buildServiceCreateOptions = void 0;
+exports.dockerService = exports.buildServiceCreateOptions = exports.readPublishedPorts = void 0;
 const work_service_1 = require("../planner/work-service");
 const run_labels_1 = require("../docker/run-labels");
 const service_hostname_1 = require("../planner/utils/service-hostname");
@@ -22,6 +22,28 @@ const work_healthcheck_1 = require("../planner/work-healthcheck");
 const docker_resources_1 = require("./docker-resources");
 const egress_proxy_1 = require("../network/egress-proxy");
 const HEALTHCHECK_INTERVAL_MS = 1000;
+// Where docker published the ports of a container (or of its relay), for those that asked
+// for a free one.
+async function readPublishedPorts(container, ports) {
+    const wanted = ports.filter((port) => port.hostPort === 0);
+    if (wanted.length === 0) {
+        return [];
+    }
+    const bound = (await container.inspect()).NetworkSettings.Ports ?? {};
+    return wanted.flatMap((port) => {
+        const binding = bound[`${port.containerPort}/tcp`]?.find((candidate) => candidate.HostPort);
+        return binding
+            ? [
+                {
+                    containerPort: port.containerPort,
+                    host: port.hostIp ?? (binding.HostIp && binding.HostIp !== '0.0.0.0' ? binding.HostIp : '127.0.0.1'),
+                    port: Number(binding.HostPort),
+                },
+            ]
+            : [];
+    });
+}
+exports.readPublishedPorts = readPublishedPorts;
 function buildServiceCreateOptions(item, options, network, secrets, resources = {}) {
     const envs = (0, replace_env_variables_1.getEnvironmentVariables)(item.data.envs);
     const command = (0, work_service_1.getServiceCommand)(item.data);
@@ -58,12 +80,9 @@ function buildServiceCreateOptions(item, options, network, secrets, resources =
             // collide with another run on the same host. A limited service's are
             // published by its relay.
             PortBindings: options.publishPorts && !network.relayPorts
-                ? item.data.ports
-                    .filter((p) => !!p.hostPort)
-                    .reduce((map, port) => {
-                    map[`${port.containerPort}/tcp`] = [{ HostPort: `${port.hostPort}` }];
-                    return map;
-                }, {})
+                ? Object.fromEntries(item.data.ports
+                    .filter((p) => p.hostPort !== null)
+                    .map((port) => [`${port.containerPort}/tcp`, [(0, item_network_1.getPortBinding)(port)]]))
                 : {},
             ...resources,
         },
@@ -90,16 +109,18 @@ async function dockerService(docker, item, options, environment) {
         const resources = await (0, docker_resources_1.resolveDockerResources)(docker, item.data.resources, item.status);
         await (0, execution_steps_1.refuseHostLinks)(item, environment);
         container = await docker.createContainer(buildServiceCreateOptions(item, options, network.options, secrets, resources));
-        await network.connect(container);
+        const relay = await network.connect(container);
         const stream = await container.attach({ stream: true, stdout: true, stderr: true });
         (0, stream_1.logStream)(item.status, stream);
         await container.start();
+        const published = options.publishPorts ? await readPublishedPorts(relay ?? container, item.data.ports) : [];
         if (!item.data.healthcheck || !options.waitForReady) {
             options.state.set({
                 type: 'running',
                 dns: { containerId: container.id },
                 stateKey: options.stateKey,
                 remote: null,
+                ...(published.length > 0 ? { published } : {}),
             });
         }
         else {
@@ -125,6 +146,7 @@ async function dockerService(docker, item, options, environment) {
                     dns: { containerId: container.id },
                     stateKey: options.stateKey,
                     remote: null,
+                    ...(published.length > 0 ? { published } : {}),
                 });
             }
         }

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,8 @@ 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");
+const service_tools_1 = require("./service-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 +27,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 +194,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 ' +
@@ -315,9 +242,30 @@ function createMcpTools(client) {
                 return `pushed ${pushed.commit} to ${pushed.branch}`;
             },
         },
+        ...service_tools_1.SERVICE_TOOLS.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: (0, service_tools_1.serviceToolSchema)(tool),
+            annotations: { title: tool.title, readOnlyHint: tool.name === 'endpoint_get', openWorldHint: false },
+            async call(args, signal) {
+                return tool.call(await client(), args, signal);
+            },
+        })),
     ]);
 }
 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)();