hammerkit 1.27.0-next.2 → 1.27.0-next.21

package/build.schema.json

@@ -289,6 +289,9 @@
                     ],
                     "description": "network the task or service reaches besides its needs: open (default), none or { allow: [hosts or host:port] }"
                   },
+                  "args": {
+                    "type": "boolean"
+                  },
                   "runner": {
                     "type": "string",
                     "minLength": 1
@@ -370,6 +373,9 @@
                   "network": {
                     "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/network"
                   },
+                  "args": {
+                    "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/args"
+                  },
                   "runner": {
                     "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/runner"
                   },
@@ -511,6 +517,9 @@
                   "network": {
                     "$ref": "#/definitions/hammerkit/properties/tasks/additionalProperties/anyOf/0/properties/network",
                     "description": "network the task or service reaches besides its needs: open (default), none or { allow: [hosts or host:port] }"
+                  },
+                  "args": {
+                    "type": "boolean"
                   }
                 },
                 "required": [
@@ -586,6 +595,24 @@
               {
                 "type": "string"
               },
+              {
+                "type": "object",
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Build file or directory, relative to the including file"
+                  },
+                  "with": {
+                    "$ref": "#/definitions/hammerkit/properties/envs",
+                    "description": "Environment values for the current build task\nhttps://hammerkit.dev/docs/build-file/environment-variables"
+                  }
+                },
+                "required": [
+                  "path"
+                ],
+                "additionalProperties": false
+              },
               {
                 "type": "object",
                 "properties": {

package/dist/cache/backends/registry-cache-backend.js

@@ -5,6 +5,7 @@ const crypto_1 = require("crypto");
 const os_1 = require("os");
 const path_1 = require("path");
 const tar_1 = require("tar");
+const tar_2 = require("../../utils/tar");
 const registry_reference_1 = require("./registry/registry-reference");
 const registry_client_1 = require("./registry/registry-client");
 const MAX_TAG_LENGTH = 128;
@@ -74,8 +75,7 @@ function createRegistryCacheBackend(spec) {
                 const layerFile = (0, path_1.join)(dir, 'layer.tar');
                 const files = (await environment.file.listFiles(from)).sort();
                 // portable + mtime-free so identical entries produce identical digests
-                // `noMtime` is supported by tar 6 but missing from its type definitions
-                await (0, tar_1.create)({ file: layerFile, cwd: from, portable: true, noMtime: true }, files);
+                await (0, tar_2.packArchive)({ file: layerFile, cwd: from, portable: true, noMtime: true }, files);
                 const layer = await (0, registry_client_1.digestFile)(layerFile);
                 const config = Buffer.from(JSON.stringify({
                     architecture: 'amd64',

package/dist/cache/explain.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.explainWorkTree = exports.explainTask = exports.describeCause = void 0;
+const work_task_1 = require("../planner/work-task");
 const state_key_1 = require("../executer/scheduler/state-key");
 const work_task_cache_description_1 = require("../optimizer/work-task-cache-description");
 const get_cache_directory_1 = require("../optimizer/get-cache-directory");
@@ -157,6 +158,22 @@ async function explainTask(item, defaultCacheMethod, environment, memo = new Map
         visiting.delete(item.id());
         return explanation;
     }
+    // Mirrors executeWorkTask: an aggregate is never looked up itself, and is reported
+    // cached when all its dependencies were. What changed is in its dependencies.
+    if ((0, work_task_1.isAggregateTask)(item.data)) {
+        const causes = [];
+        for (const dep of item.deps) {
+            const depExplanation = await explainTask(dep, defaultCacheMethod, environment, memo, visiting);
+            if (depExplanation.status !== 'hit') {
+                causes.push({ kind: 'dependency-changed', identifier: dep.name });
+            }
+        }
+        const status = causes.length === 0 ? 'hit' : 'miss';
+        const explanation = { taskId: item.id(), taskName: item.name, status, causes };
+        memo.set(item.id(), explanation);
+        visiting.delete(item.id());
+        return explanation;
+    }
     const runtimeStateKey = await safeCurrentStateKey(item, environment);
     const hasEntry = await safeHas(item, stateKey, environment);
     const predictedHit = runtimeStateKey === stateKey || hasEntry;

package/dist/cli.js

@@ -79,6 +79,7 @@ class Cli {
                         explain: options?.explain ?? false,
                         cacheReadOnly: options?.cacheReadOnly ?? false,
                         timeout: options?.timeout ?? null,
+                        maxTimeout: options?.maxTimeout ?? null,
                         skipDeps: options?.skipDeps ?? true,
                         wait: options?.wait ?? 'ready',
                         resourceCheck: options?.resourceCheck ?? true,

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/deadline.js

@@ -1,14 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withDeadline = void 0;
+exports.withDeadline = exports.getTaskTimeout = void 0;
 const abort_event_1 = require("../utils/abort-event");
+// How long a task may run: its own `timeout`, else the run's default (`--timeout`), and
+// never longer than the run's cap (`--max-timeout`), which also covers tasks with a
+// longer timeout of their own. A caller can shorten a task this way, never extend it.
+function getTaskTimeout(own, run) {
+    const timeout = own ?? run.timeout;
+    if (run.maxTimeout === null) {
+        return timeout;
+    }
+    return timeout === null ? run.maxTimeout : Math.min(timeout, run.maxTimeout);
+}
+exports.getTaskTimeout = getTaskTimeout;
+// the longest delay of setTimeout: Node fires a longer one after 1 ms
+const MAX_TIMER_MS = 2 ** 31 - 1;
 // An abort signal that follows `parent` and additionally fires after `timeout`
-// ms, so a task deadline reuses the runtimes' existing abort/cleanup path.
+// ms, so a task deadline reuses the runtimes' existing abort/cleanup path. A
+// timeout beyond what a timer can wait (about 24.8 days) sets no deadline.
 function withDeadline(parent, timeout) {
     const controller = new AbortController();
     let expired = false;
     const parentListener = (0, abort_event_1.listenOnAbort)(parent, () => controller.abort());
-    const timer = timeout === null
+    const timer = timeout === null || timeout > MAX_TIMER_MS
         ? null
         : setTimeout(() => {
             expired = true;

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/executer/event-cache.js

@@ -8,6 +8,8 @@ const execute_docker_1 = require("./execute-docker");
 const plan_work_tasks_1 = require("../planner/utils/plan-work-tasks");
 const get_cache_directory_1 = require("../optimizer/get-cache-directory");
 const path_1 = require("path");
+const crypto_1 = require("crypto");
+const claim_layout_1 = require("../kubernetes/claim-layout");
 const move_files_1 = require("../file/move-files");
 const work_instance_id_1 = require("../planner/work-instance-id");
 async function restoreCache(environment, path, workTree) {
@@ -43,8 +45,24 @@ function* getArchivePaths(task, path) {
         }
     }
     else {
-        for (const generate of task.generates.filter((g) => !g.inherited)) {
-            const generateId = (0, path_1.relative)(task.cwd, generate.path).split(path_1.sep).join('-');
+        // `a-b` and `a/b` flatten alike: of those, the least deep (then the first in sorted
+        // order) keeps the name, the others' names carry a hash of their relative path, so a
+        // store and a restore in another directory or order find the same archive
+        const generates = task.generates
+            .filter((g) => !g.inherited)
+            .map((generate) => ({ generate, rel: (0, path_1.relative)(task.cwd, generate.path).split(path_1.sep).join(path_1.posix.sep) }));
+        const holders = new Map();
+        for (const { rel } of [...generates].sort((a, b) => (0, claim_layout_1.byDepth)(a.rel, b.rel))) {
+            const id = rel.split(path_1.posix.sep).join('-');
+            if (!holders.has(id)) {
+                holders.set(id, rel);
+            }
+        }
+        for (const { generate, rel } of generates) {
+            let generateId = rel.split(path_1.posix.sep).join('-');
+            if (holders.get(generateId) !== rel) {
+                generateId += '-' + (0, crypto_1.createHash)('sha256').update(rel).digest('hex').slice(0, 12);
+            }
             yield {
                 filename: (0, path_1.join)(path, generateId + '-generates.tgz'),
                 path: generate.path,

package/dist/executer/execute-work-task.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeWorkTask = void 0;
+const work_task_1 = require("../planner/work-task");
 const states_1 = require("./states");
 const abort_1 = require("./abort");
 const log_1 = require("../log");
@@ -12,7 +13,8 @@ const archive_task_entry_1 = require("./archive-task-entry");
 const units_1 = require("../utils/units");
 async function pushToBackend(work, environment, cacheState, options) {
     const { resolved, stateKey, provable } = cacheState;
-    if (resolved.method === 'none' || !provable) {
+    // an aggregate has nothing to store, see checkCacheState
+    if (resolved.method === 'none' || !provable || (0, work_task_1.isAggregateTask)(work.data)) {
         return;
     }
     if (options.cacheReadOnly) {
@@ -29,7 +31,7 @@ async function pushToBackend(work, environment, cacheState, options) {
     }
 }
 // A task without cmds only groups its dependencies (`ci: { deps: [test, build] }`).
-// Having no src of its own it is never a cache hit, so its dependencies are
+// It is never a cache hit itself (see checkCacheState), so its dependencies are
 // always checked and their outputs restored. When every one of them was a hit,
 // nothing ran: report the group as cached too. Reporting only, the cache
 // decision is untouched.
@@ -94,7 +96,7 @@ dependents = null) {
                     stateKey: cacheState.stateKey,
                     started,
                 });
-                const timeout = work.data.timeout ?? options.timeout;
+                const timeout = (0, deadline_1.getTaskTimeout)(work.data.timeout, options);
                 const deadline = (0, deadline_1.withDeadline)(abort, timeout);
                 try {
                     await work.runtime.execute(environment, {

package/dist/executer/execution-steps.js

@@ -9,6 +9,7 @@ const work_task_1 = require("../planner/work-task");
 const work_service_1 = require("../planner/work-service");
 const get_container_binds_1 = require("./get-container-binds");
 const assert_item_paths_1 = require("../planner/utils/assert-item-paths");
+const log_1 = require("../log");
 // The files a server run works on: its checkout, or a sandbox. Somebody else wrote them.
 function hostedRoot(environment) {
     return environment.hosted ? environment.cwd : undefined;
@@ -66,10 +67,27 @@ async function prepareMounts(item, environment) {
             continue;
         }
         if ((0, path_1.extname)(mount.localPath)) {
-            await environment.file.writeFile(mount.localPath, '');
+            try {
+                await environment.file.writeFile(mount.localPath, '');
+            }
+            catch (e) {
+                // Docker would make a directory there
+                throw new Error(`mount ${mount.localPath} does not exist and can't be created (${(0, log_1.getErrorMessage)(e)})`);
+            }
         }
         else {
-            await environment.file.createDirectory(mount.localPath);
+            try {
+                await environment.file.createDirectory(mount.localPath);
+            }
+            catch (e) {
+                // on a server a root-owned directory in the run's files could break its cleanup
+                if (environment.hosted) {
+                    throw e;
+                }
+                // hammerkit may run in a container whose file system is not the one of the Docker
+                // host: Docker creates the missing directory of a bind on its own
+                item.status.write('warn', `can't create ${mount.localPath} (${(0, log_1.getErrorMessage)(e)}), Docker creates it on its host as root`);
+            }
         }
     }
     if ((0, work_task_1.isContainerWorkTask)(item.data)) {
@@ -89,8 +107,11 @@ exports.prepareMounts = prepareMounts;
 async function setUserPermissions(item, container, environment) {
     if (item.data.user) {
         // On a server only the volumes: a chown as the container's root on a path of the host
-        // would follow a link a task put there after the binds were checked
-        const binds = (0, get_container_binds_1.getContainerBinds)(item).filter((bind) => !environment.hosted || !(0, path_1.isAbsolute)(bind.localPath));
+        // would follow a link a task put there after the binds were checked. Never a mount: it
+        // is a path of the host the build file names, such as /var/run/docker.sock, whose owner
+        // is not hammerkit's to change
+        const mounted = new Set(item.data.mounts.map((mount) => mount.containerPath));
+        const binds = (0, get_container_binds_1.getContainerBinds)(item).filter((bind) => !mounted.has(bind.containerPath) && (!environment.hosted || !(0, path_1.isAbsolute)(bind.localPath)));
         if (!environment.hosted) {
             await (0, set_user_permission_1.setUserPermission)(item.data.cwd, item.status, environment, container, item.data.user);
         }

package/dist/executer/reset-work-tree.js

@@ -5,6 +5,10 @@ const state_1 = require("./state");
 function resetWorkTree(workTree, type) {
     return {
         tasks: Object.entries(workTree.tasks).reduce((tasks, [key, task]) => {
+            // down only stops services: a task it selects names the services it needs
+            if (type === 'down') {
+                return tasks;
+            }
             task.state = new state_1.State({
                 type: 'pending',
                 stateKey: null,

package/dist/executer/scheduler/enqueue-next.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkCacheState = exports.UNCACHED_STATE_KEY = void 0;
 const work_item_1 = require("../../planner/work-item");
+const work_task_1 = require("../../planner/work-task");
 const get_cache_directory_1 = require("../../optimizer/get-cache-directory");
 const cache_metadata_1 = require("../cache-metadata");
 const work_task_cache_description_1 = require("../../optimizer/work-task-cache-description");
@@ -35,6 +36,12 @@ options = {}) {
         item.status.write('debug', `${item.name} always runs, it or one of its dependencies has no src files`);
         return { cached: false, stateKey, resolved, provable };
     }
+    // An aggregate runs nothing, so running it costs nothing, and it is never a hit itself:
+    // asked for, it still has its dependencies checked and their outputs restored. Its key
+    // counts for what depends on it, and it is reported cached when they all were.
+    if ((0, work_item_1.isWorkTaskItem)(item) && (0, work_task_1.isAggregateTask)(item.data)) {
+        return { cached: false, stateKey, resolved, provable };
+    }
     if ((0, work_item_1.isWorkTaskItem)(item)) {
         const runtimeStateKey = await item.runtime.currentStateKey(environment);
         if (runtimeStateKey === stateKey) {

package/dist/executer/scheduler/state-key.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeStateKey = exports.combineStateKeys = exports.resolveEffective = void 0;
-const crypto_1 = require("crypto");
+exports.computeStateKey = exports.combineStateKeys = exports.isOwnProvable = exports.resolveEffective = void 0;
 const get_work_cache_stats_1 = require("../../optimizer/get-work-cache-stats");
+const work_task_1 = require("../../planner/work-task");
 // The state-key engine is shared by the scheduler's hit/miss decision
 // (`checkCacheState`) and the read-only cache-explain engine, so a prediction
 // can never diverge from the decision it predicts — there is one implementation.
@@ -21,9 +21,14 @@ exports.resolveEffective = resolveEffective;
 // whose `src` entries all match no file (a typo, a moved path). Services are not
 // affected.
 function isOwnProvable(item, unmatched) {
+    if ((0, work_task_1.isAggregateTask)(item.data)) {
+        // it runs nothing and reads nothing: what its dependencies prove is all there is
+        return true;
+    }
     // unmatched ⊆ declared, so this is also false when nothing is declared
     return unmatched.length < item.data.src.filter((src) => !src.inherited).length;
 }
+exports.isOwnProvable = isOwnProvable;
 // Fold a task's own state key together with the state keys of its dependencies.
 // A change anywhere in the dependency subtree must change the resulting key, so
 // that a downstream task is invalidated when an upstream source changes — even
@@ -34,9 +39,7 @@ function combineStateKeys(ownKey, depKeys) {
     }
     // Sort so the key is independent of dependency declaration order.
     const sorted = [...depKeys].sort();
-    return (0, crypto_1.createHash)('md5')
-        .update([ownKey, ...sorted].join(','))
-        .digest('hex');
+    return (0, get_work_cache_stats_1.stateKeyDigest)([ownKey, ...sorted].join(','));
 }
 exports.combineStateKeys = combineStateKeys;
 // `none` only disables the cache *check* for a task; its sources still influence
@@ -72,7 +75,41 @@ async function computeStateKey(item, defaultCacheMethod, environment, memo = new
         depKeys.push(effective.stateKey);
         provable = provable && effective.provable;
     }
+    // what a task that needs a service passed against: the sources of the service and of the
+    // tasks it depends on (its definition is in the task id, getWorkServiceCacheIdentity)
+    for (const need of item.needs) {
+        const effective = await resolveNeedStateKey(need.service, defaultCacheMethod, environment, memo);
+        depKeys.push(`${need.name}=${effective.stateKey}`);
+    }
     return { stateKey: combineStateKeys(ownKey, depKeys), stats, resolved, provable, unmatched };
 }
 exports.computeStateKey = computeStateKey;
+// A needed service's sources folded with the state keys of its dependencies and needs. It
+// does not make the task that needs it unprovable: a dependency without `src` (resetting the
+// service's data, say) is skipped with the service when the task is a cache hit.
+async function resolveNeedStateKey(service, defaultCacheMethod, environment, memo) {
+    const memoKey = `need\0${service.name}`;
+    const existing = memo.get(memoKey);
+    if (existing !== undefined) {
+        return existing;
+    }
+    // services that need each other in a loop fail to plan (checkForLoop): this only has to end
+    memo.set(memoKey, { stateKey: 'loop', provable: true });
+    const resolved = resolveEffective(service, defaultCacheMethod);
+    const { stats } = await (0, get_work_cache_stats_1.getWorkItemCacheStats)(service, environment);
+    const keys = [];
+    for (const dep of service.deps) {
+        keys.push((await resolveEffectiveStateKey(dep, defaultCacheMethod, environment, memo)).stateKey);
+    }
+    for (const need of service.needs) {
+        const effective = await resolveNeedStateKey(need.service, defaultCacheMethod, environment, memo);
+        keys.push(`${need.name}=${effective.stateKey}`);
+    }
+    const effective = {
+        stateKey: combineStateKeys((0, get_work_cache_stats_1.getStateKey)(stats, concreteMethod(resolved, defaultCacheMethod)), keys),
+        provable: true,
+    };
+    memo.set(memoKey, effective);
+    return effective;
+}
 //# sourceMappingURL=state-key.js.map

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)) {
@@ -39,8 +49,12 @@ async function connectSandbox(environment, options, log = () => undefined) {
     if (!bundle_1.HASH_PATTERN.test(options.build)) {
         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) };
+    const server = (0, host_config_1.getRegisteredServer)(config, name);
+    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,