hammerkit 1.27.0-next.14 → 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/mcp.js

@@ -5,6 +5,7 @@ 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 };
@@ -241,6 +242,15 @@ function createMcpTools(client, options = {}) {
                 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;

package/dist/harness/opencode.js

@@ -10,6 +10,7 @@ const connect_1 = require("./connect");
 const format_1 = require("./format");
 const sandbox_client_1 = require("./sandbox-client");
 const task_tools_1 = require("./task-tools");
+const service_tools_1 = require("./service-tools");
 const DEFAULT_READ_LINES = 2000;
 const LIST_LIMIT = 100;
 const SEARCH_LIMIT = 100;
@@ -66,6 +67,9 @@ exports.OPENCODE_TOOLS = [
     'run_logs',
     'push',
     'list',
+    'services_up',
+    'endpoint_get',
+    'services_stop',
 ];
 /**
  * The plugin as the file `harness/opencode.ts` exports it: it takes the zod of opencode from
@@ -151,6 +155,9 @@ exports.OPENCODE_V2_TOOLS = [
     'run_task',
     'run_logs',
     'push',
+    'services_up',
+    'endpoint_get',
+    'services_stop',
 ];
 // the tools of opencode 2 that work on this machine and have no stand-in on a sandbox
 exports.OPENCODE_V2_LOCAL_TOOLS = [
@@ -268,6 +275,7 @@ function createOpencodeV2Tools(client, directory, options = {}) {
             branch: text('The branch to push to, created when it does not exist'),
             message: text('The commit message'),
         }, ['branch', 'message']), same),
+        ...service_tools_1.SERVICE_TOOLS.map((service) => tool(service.name, service.name, { ...(0, service_tools_1.serviceToolSchema)(service), additionalProperties: false }, same)),
     ];
 }
 exports.createOpencodeV2Tools = createOpencodeV2Tools;
@@ -287,6 +295,19 @@ function createOpencodeTools(z, client, options = {}) {
     ]));
 }
 exports.createOpencodeTools = createOpencodeTools;
+// services_up, endpoint_get and services_stop, with their parameters for the zod of opencode 1
+function opencodeServiceTools(client) {
+    return Object.fromEntries(service_tools_1.SERVICE_TOOLS.map((tool) => [
+        tool.name,
+        {
+            description: tool.description,
+            args: (z) => (0, service_tools_1.serviceToolArgs)(tool, z),
+            async execute(args, context) {
+                return { title: tool.title, output: await tool.call(await client(), args, context.abort) };
+            },
+        },
+    ]));
+}
 function opencodeTools(client, options = {}) {
     const shell = options.shell ?? connect_1.DEFAULT_SHELL_TASK;
     const tasks = Object.fromEntries((0, task_tools_1.createTaskTools)(options.tasks, shell || undefined).map((task) => [
@@ -553,6 +574,7 @@ function opencodeTools(client, options = {}) {
                 return lines.join('\n');
             },
         },
+        ...opencodeServiceTools(client),
     });
 }
 // opencode runs the tool calls of a step in parallel, they reach the sandbox one at a time in their order

package/dist/harness/pi.js

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

package/dist/harness/sandbox-client.js

@@ -161,6 +161,60 @@ class SandboxClient {
             exitCode: exitCodeOf(result),
         };
     }
+    /**
+     * Starts services of the published build file on the sandbox, or on a branch of its
+     * repository, and follows them until they are up: the run then holds their endpoints
+     * until its ttl ends or it is stopped. A signal cancels the run.
+     */
+    async up(request, options = {}) {
+        if (options.signal?.aborted) {
+            throw new SandboxClientError('the run was cancelled');
+        }
+        const submitted = await submitRun(this.connection, {
+            definition: this.build.hash,
+            services: request.services,
+            endpoints: request.endpoints ?? [],
+            ...(request.ttl ? { ttl: request.ttl } : {}),
+            ...(request.sleepTtl ? { sleepTtl: request.sleepTtl } : {}),
+            ...(request.name ? { name: request.name } : {}),
+            source: request.branch
+                ? { type: 'ref', repo: this.sandbox.repo, ref: request.branch }
+                : { type: 'sandbox', id: this.id },
+        });
+        return followRun(this.connection, submitted, { signal: options.signal, untilUp: true });
+    }
+    // Stops a run: a service run takes its services and endpoints down.
+    async stop(id) {
+        return json(await call(this.connection, 'POST', `/v1/runs/${encodeURIComponent(id)}/cancel`));
+    }
+    /**
+     * A page of an endpoint of a service run, as the caller sees it: only at an address the
+     * server gave the run, so the token goes to the server and nowhere else.
+     */
+    async fetchEndpoint(id, path, service, signal) {
+        const run = await this.getRun(id);
+        const endpoint = run.up?.endpoints.find((candidate) => service === undefined || candidate.service === service);
+        if (!endpoint) {
+            throw new SandboxClientError(run.up
+                ? `${id} has no endpoint${service ? ` of ${service}` : ''}, it has ${run.up.endpoints.map((candidate) => `${candidate.service}:${candidate.port}`).join(', ') || 'none'}`
+                : `${id} is not a service run`);
+        }
+        const url = new URL(path.startsWith('/') ? path : `/${path}`, endpoint.url);
+        if (url.origin !== new URL(endpoint.url).origin) {
+            throw new SandboxClientError(`${path} is not a path of ${endpoint.url}`);
+        }
+        const response = await fetch(url, {
+            headers: { 'hammerkit-authorization': `Bearer ${await this.connection.token()}` },
+            redirect: 'manual',
+            signal: AbortSignal.any([AbortSignal.timeout(TIMEOUT_MS), ...(signal ? [signal] : [])]),
+        });
+        return {
+            url: url.toString(),
+            status: response.status,
+            type: response.headers.get('content-type') ?? '',
+            body: await response.text(),
+        };
+    }
     /**
      * A shell command on the sandbox: the shell task of the build file with the command as
      * its argument. `cwd` is a directory of the sandbox, `''` for its root.
@@ -283,7 +337,7 @@ async function followRun(connection, submitted, options = {}) {
                 options.onWaiting?.(run);
             }
             await readLog();
-            if (exports.FINAL_RUN_STATES.includes(run.state)) {
+            if (exports.FINAL_RUN_STATES.includes(run.state) || (options.untilUp && run.state === 'up')) {
                 break;
             }
             run = await json(await call(connection, 'GET', path, { query: { wait: POLL_WAIT } }));

package/dist/harness/service-tools.js

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

package/dist/kubernetes/ensure-kubernetes-service-exists.js

@@ -28,7 +28,9 @@ async function ensureKubernetesServiceExists(instance, env, service) {
             ...(headless
                 ? {}
                 : {
+                    // a Service of more than one port needs a name for each
                     ports: service.data.ports.map((port) => ({
+                        name: `tcp-${port.hostPort ?? port.containerPort}`,
                         port: port.hostPort ?? port.containerPort,
                         targetPort: port.containerPort,
                     })),

package/dist/planner/utils/parse-work-port.js

@@ -8,7 +8,10 @@ function parseWorkPort(port) {
         return { containerPort: port, hostPort: port };
     }
     else if (parts.length === 2) {
-        return { containerPort: parsePort(parts[1], false), hostPort: parsePort(parts[0], true) };
+        // `0:80` is not published, as an empty host port: 0 (a free port) is for the endpoints
+        // of a server only
+        const hostPort = parsePort(parts[0], true);
+        return { containerPort: parsePort(parts[1], false), hostPort: hostPort === 0 ? null : hostPort };
     }
     else {
         throw new Error(`invalid port ${port}`);

package/dist/remote/remote-work-commands.js

@@ -13,6 +13,8 @@ const annotations_1 = require("./annotations");
 const server_client_1 = require("./server-client");
 const bundle_text_1 = require("./bundle-text");
 const sandbox_client_1 = require("../harness/sandbox-client");
+const units_1 = require("../utils/units");
+const service_tools_1 = require("../harness/service-tools");
 const path_1 = require("path");
 const RUN_ID = /^run_[A-Za-z0-9_-]{16}$/;
 // what the publisher said about where a version comes from, one line
@@ -97,6 +99,21 @@ function describePlan(plan) {
 exports.describePlan = describePlan;
 function registerWorkCommands(remote, context) {
     const { environment, buildFile, getServer, guarded, passthrough, fail } = context;
+    // the ref a run starts from: what the options name, else the checkout here
+    const refSource = async (options) => {
+        const checkout = options.repo && options.ref ? {} : await (0, annotations_1.readCheckout)((0, path_1.dirname)(buildFile));
+        const repo = options.repo ?? checkout.repo;
+        const ref = options.ref ?? checkout.branch;
+        // the commit checked out here is the code meant, when the ref is the branch it is on
+        const commit = options.commit ?? (options.ref ? undefined : checkout.commit);
+        if (!repo) {
+            throw new Error('name the repository with --repo, the checkout here has no origin it can be told by');
+        }
+        if (!ref) {
+            throw new Error('name the branch or tag with --ref, the checkout here is on no branch');
+        }
+        return { type: 'ref', repo, ref, ...(commit ? { commit } : {}) };
+    };
     const connect = async (name) => {
         const chosen = await getServer(name);
         // a CI job or an agent brings its own token, a person signs in
@@ -147,17 +164,8 @@ function registerWorkCommands(remote, context) {
         if (!bundle_1.HASH_PATTERN.test(definition)) {
             throw new Error(`${(0, server_client_1.printable)(definition)} is not the hash of a published version (sha256:...)`);
         }
-        const checkout = options.repo && options.ref ? {} : await (0, annotations_1.readCheckout)((0, path_1.dirname)(buildFile));
-        const repo = options.repo ?? checkout.repo;
-        const ref = options.ref ?? checkout.branch;
-        // the commit checked out here is the code meant, when the ref is the branch it is on
-        const commit = options.commit ?? (options.ref ? undefined : checkout.commit);
-        if (!repo) {
-            throw new Error('name the repository with --repo, the checkout here has no origin it can be told by');
-        }
-        if (!ref) {
-            throw new Error('name the branch or tag with --ref, the checkout here is on no branch');
-        }
+        const source = await refSource(options);
+        const ref = source.ref;
         const { name: serverName, server } = await getServer(options.server);
         const connection = { url: server.url, ...(0, token_source_1.getTokenSource)(environment, serverName, server) };
         const runOptions = {};
@@ -174,7 +182,7 @@ function registerWorkCommands(remote, context) {
             submitted = await (0, sandbox_client_1.submitRun)(connection, {
                 definition,
                 tasks,
-                source: { type: 'ref', repo, ref, ...(commit ? { commit } : {}) },
+                source,
                 options: runOptions,
             });
         }
@@ -211,6 +219,84 @@ function registerWorkCommands(remote, context) {
         const exitCode = failed?.exitCode && failed.exitCode > 0 ? failed.exitCode : 1;
         fail(`${(0, server_client_1.printable)(run.id)} ${run.state}${run.error ? `: ${(0, server_client_1.printable)(run.error)}` : ''}`, exitCode);
     }));
+    remote
+        .command('up <services...>')
+        .description('start services of a published build file on a server from a git ref and keep them up until their ttl ends, ' +
+        'with their endpoints at addresses of their own behind the sign-in of the server')
+        .addOption(new commander_1.Option('--server <name>', 'the server to run on; the default of remote use when left out'))
+        .addOption(new commander_1.Option('--endpoint <service:port>', 'publish this port of a service, such as web:8080; may be given more than once').argParser(collectOption))
+        .addOption(new commander_1.Option('--ttl <duration>', 'how long they stay once ready, such as 2h, then they are removed; the server default when left out'))
+        .addOption(new commander_1.Option('--sleep-ttl <duration>', 'how long they stay up without a request, such as 30m, then they sleep until the next request wakes them; ' +
+        'the server default when left out'))
+        .addOption(new commander_1.Option('--name <name>', 'a later run of yours with the same name replaces this one and keeps its addresses; the branch when left out'))
+        .addOption(new commander_1.Option('--build <hash>', 'the published version to run (sha256:...), or HAMMERKIT_BUILD; the hash of the build file here when left out'))
+        .addOption(new commander_1.Option('--repo <host/path>', 'the repository; origin of the checkout here when left out'))
+        .addOption(new commander_1.Option('--ref <ref>', 'the branch or tag to start; the branch checked out here when left out'))
+        .addOption(new commander_1.Option('--commit <sha>', 'the commit the ref has to be at; the commit checked out here when --ref is left out'))
+        .addOption(new commander_1.Option('--env <name>', 'the environment of the build file, as --env of run'))
+        .action(guarded('Remote up was not successful', async (services, options) => {
+        const named = options.build ?? environment.processEnvs.HAMMERKIT_BUILD;
+        const definition = named ?? (0, bundle_1.hashBundle)(await (0, collect_bundle_1.collectBundle)(buildFile, environment));
+        if (!bundle_1.HASH_PATTERN.test(definition)) {
+            throw new Error(`${(0, server_client_1.printable)(definition)} is not the hash of a published version (sha256:...)`);
+        }
+        const endpoints = (options.endpoint ?? []).map(service_tools_1.parseEndpoint);
+        const source = await refSource(options);
+        const { name: serverName, server } = await getServer(options.server);
+        const connection = { url: server.url, ...(0, token_source_1.getTokenSource)(environment, serverName, server) };
+        const submitted = await (0, sandbox_client_1.submitRun)(connection, {
+            definition,
+            services,
+            endpoints,
+            ...(options.ttl ? { ttl: options.ttl } : {}),
+            ...(options.sleepTtl ? { sleepTtl: options.sleepTtl } : {}),
+            ...(options.name ? { name: options.name } : {}),
+            source,
+            options: options.env ? { env: options.env } : {},
+        });
+        environment.stdout.write(`${(0, server_client_1.printable)(submitted.id)} on ${serverName}: ${services.map(server_client_1.printable).join(', ')} from ${(0, server_client_1.printable)(source.ref)}${submitted.source.type === 'ref' ? ` at ${(0, server_client_1.printable)(submitted.source.commit)}` : ''}\n`);
+        const followed = await (0, sandbox_client_1.followRun)(connection, submitted, {
+            signal: environment.abortCtrl.signal,
+            untilUp: true,
+            onLine: (line) => environment.stdout.write(`[${(0, server_client_1.printable)(line.task)}] ${printableLine(line.text)}\n`),
+            onWaiting: (run) => {
+                for (const approval of run.approvals ?? []) {
+                    environment.stdout.write(`waiting until somebody who uses ${(0, server_client_1.printable)(approval.account)} approves it, before ${(0, server_client_1.printable)(approval.expiresAt)}: hammerkit remote approve ${(0, server_client_1.printable)(run.id)}\n`);
+                }
+            },
+        });
+        const run = followed.run;
+        if (run.state !== 'up') {
+            fail(`${(0, server_client_1.printable)(run.id)} ${run.state}${run.error ? `: ${(0, server_client_1.printable)(run.error)}` : ''}`, 1);
+        }
+        environment.stdout.write(`${(0, server_client_1.printable)(run.id)} is up until ${(0, server_client_1.printable)(run.expiresAt ?? '-')}${run.up?.sleepTtl ? `, asleep after ${(0, units_1.formatDuration)(run.up.sleepTtl)} without a request` : ''}\n`);
+        for (const endpoint of run.up?.endpoints ?? []) {
+            environment.stdout.write(`  ${(0, server_client_1.printable)(endpoint.service)}:${endpoint.port}  ${(0, server_client_1.printable)(endpoint.url)}\n`);
+        }
+        environment.stdout.write(`extend it with: hammerkit remote extend ${(0, server_client_1.printable)(run.id)} 8h, stop it with: hammerkit remote stop ${(0, server_client_1.printable)(run.id)}\n`);
+    }));
+    remote
+        .command('extend <run> <ttl> [server]')
+        .description('keep a service run that is up for this long from now, such as 8h, at most the maxTtl of the server')
+        .action(guarded('Remote extend was not successful', async (id, ttl, name) => {
+        if (!RUN_ID.test(id)) {
+            throw new Error(`${(0, server_client_1.printable)(id)} is not a run id (run_...)`);
+        }
+        const { name: serverName, server, token } = await connect(name);
+        const run = (await (0, server_client_1.callServer)(server, token, 'POST', `/v1/runs/${id}/extend`, { ttl })).body;
+        environment.stdout.write(`${(0, server_client_1.printable)(run.id)} on ${serverName} stays up until ${(0, server_client_1.printable)(run.expiresAt ?? '-')}\n`);
+    }));
+    remote
+        .command('stop <run> [server]')
+        .description('stop a run: a service run takes its services and endpoints down')
+        .action(guarded('Remote stop was not successful', async (id, name) => {
+        if (!RUN_ID.test(id)) {
+            throw new Error(`${(0, server_client_1.printable)(id)} is not a run id (run_...)`);
+        }
+        const { name: serverName, server, token } = await connect(name);
+        const run = (await (0, server_client_1.callServer)(server, token, 'POST', `/v1/runs/${id}/cancel`)).body;
+        environment.stdout.write(`${(0, server_client_1.printable)(run.id)} on ${serverName}: ${run.state === 'up' || run.state === 'running' ? 'stopping' : (0, server_client_1.printable)(run.state)}\n`);
+    }));
     remote
         .command('versions [server]')
         .description('list the published versions of build files on a server, newest first, with where they come from')

package/dist/schema/work-scope-parser.js

@@ -117,12 +117,18 @@ function matchesTaskWorkScope(task, scope) {
     if ((0, work_scope_1.isContextTaskFilter)(scope)) {
         return task.name === scope.taskName;
     }
+    if (scope.serviceNames) {
+        return false;
+    }
     return (0, label_values_1.appliesToLabels)(task.data.labels, scope);
 }
 function matchesServiceWorkScope(service, scope) {
     if ((0, work_scope_1.isContextTaskFilter)(scope)) {
         return false;
     }
+    if (scope.serviceNames) {
+        return scope.serviceNames.includes(service.name);
+    }
     return (0, label_values_1.appliesToLabels)(service.labels, scope);
 }
 //# sourceMappingURL=work-scope-parser.js.map