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

package/dist/harness/task-tools.js

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

package/dist/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

package/dist/server/accounts-api.js

@@ -6,7 +6,7 @@ const policy_1 = require("./policy");
 /**
  * Who the caller is and what they may do:
  *
- *   GET /v1/me         identity, accounts with their level, repositories, the builds level and the sandbox grants
+ *   GET /v1/me         identity, accounts with their level, repositories, the builds level the sandbox and endpoint grants
  *   GET /v1/accounts   the accounts the caller has a level on, with what the operator says about them
  */
 async function handleAccounts(config, log, principal, req, res, url) {
@@ -32,6 +32,7 @@ async function handleAccounts(config, log, principal, req, res, url) {
             repos: grant.repos,
             builds: grant.builds,
             sandboxes: grant.sandboxes,
+            endpoints: grant.endpoints,
         });
         return true;
     }

package/dist/server/approvals-api.js

@@ -13,7 +13,7 @@ function toApprovalView(run) {
     return {
         id: run.id,
         state: run.state,
-        requestedBy: run.owner,
+        requestedBy: { iss: run.owner.iss, sub: run.owner.sub },
         createdAt: run.createdAt,
         definition: run.definition,
         tasks: run.tasks,

package/dist/server/definitions-api.js

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