hammerkit 1.27.0-next.9 → 2.0.0-next.2

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,34 @@ 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 };
+                },
+            });
+        }
+        register({
+            name: 'check',
+            label: 'check',
+            description: sandbox_client_1.CHECK_DESCRIPTION,
+            promptSnippet: 'Run a task as a check that CI verifies after the push',
+            parameters: {
+                type: 'object',
+                properties: { task: { type: 'string', description: 'The name of the task' } },
+                required: ['task'],
+            },
+            execute: async (_id, params, signal) => {
+                const text = await (0, sandbox_client_1.runCheck)(await client(), params.task, signal);
+                return { content: [{ type: 'text', text }], details: { task: params.task } };
+            },
+        });
         pi.on('session_start', async (_event, ctx) => {
             try {
                 const sandbox = await client();

package/dist/harness/sandbox-client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.quotePosix = exports.fetchFailure = exports.toSandboxPath = exports.checkSandboxPath = exports.exitCodeOf = exports.followRun = exports.submitRun = exports.FINAL_RUN_STATES = exports.oneAtATime = exports.SandboxClient = exports.SandboxClientError = void 0;
+exports.quotePosix = exports.fetchFailure = exports.toSandboxPath = exports.checkSandboxPath = exports.exitCodeOf = exports.readRunLog = exports.getRun = exports.followRun = exports.getMoveTarget = exports.submitRun = exports.FINAL_RUN_STATES = exports.oneAtATime = exports.SandboxClient = exports.listPublishedTasks = exports.runCheck = exports.CHECK_DESCRIPTION = exports.SandboxClientError = void 0;
 const path_1 = require("path");
 const token_source_1 = require("../remote/token-source");
 // a write carries up to 32 MiB
@@ -16,6 +16,48 @@ class SandboxClientError extends Error {
     }
 }
 exports.SandboxClientError = SandboxClientError;
+// What the agent is told of a check, on each harness.
+exports.CHECK_DESCRIPTION = 'Run a task as a check before you push, such as test or e2e: it runs on a copy of the files a push ' +
+    'would commit (what .gitignore leaves out is not there, so dependencies are installed by the tasks ' +
+    'the build file names), and when it passes, CI verifies it for that commit instead of running it. ' +
+    'Push without changing files afterwards, or the check no longer counts for the files that changed.';
+// A check, run to its end, in a few lines: how it went and the last lines of a failure.
+async function runCheck(client, task, signal) {
+    const ran = await client.runTask(task, { check: true, signal });
+    const result = ran.result;
+    const lines = [
+        result?.status === 'succeeded' || result?.status === 'cached'
+            ? `check ${task} passed (run ${ran.run.id}${result.status === 'cached' ? ', from the cache' : ''}): CI can verify it for a push of these files`
+            : `check ${task} did not pass (run ${ran.run.id}: ${result?.status ?? ran.run.state}${result?.exitCode !== undefined ? `, exit code ${result.exitCode}` : ''})`,
+    ];
+    const error = result?.error ?? ran.run.error;
+    if (error) {
+        lines.push(`error: ${error}`);
+    }
+    if (result && result.status !== 'succeeded' && result.status !== 'cached' && result.lastLog.length > 0) {
+        lines.push('last lines:', ...result.lastLog);
+    }
+    return lines.join('\n');
+}
+exports.runCheck = runCheck;
+/**
+ * The tasks of a published version, without its services, as `GET /v1/definitions/<hash>`
+ * answers them.
+ */
+async function listPublishedTasks(connection, hash) {
+    const version = await json(await call(connection, 'GET', `/v1/definitions/${hash}`));
+    return version.tasks.map((name) => {
+        const plan = version.plan?.[name];
+        const args = version.arguments?.[name];
+        return {
+            name,
+            ...(plan?.description ? { description: plan.description } : {}),
+            ...(plan && plan.command !== undefined ? { command: plan.command } : {}),
+            ...(args !== undefined ? { args } : {}),
+        };
+    });
+}
+exports.listPublishedTasks = listPublishedTasks;
 /**
  * A caller's sandbox on a hammerkit server, over its HTTP API: the raw read, write and
  * stat that harnesses plug their own tools into, the typed endpoints for clients without
@@ -34,6 +76,10 @@ class SandboxClient {
     get id() {
         return this.sandbox.id;
     }
+    // the tasks of the published version that run on the sandbox
+    tasks() {
+        return listPublishedTasks(this.connection, this.build.hash);
+    }
     static async create(connection, repo, ref) {
         return json(await call(connection, 'POST', '/v1/sandboxes', { body: { repo, ref } }));
     }
@@ -115,12 +161,13 @@ class SandboxClient {
             runOptions.args = options.args;
         }
         if (options.timeoutSeconds) {
-            runOptions.timeout = `${Math.max(1, Math.ceil(options.timeoutSeconds))}s`;
+            // a cap: it also shortens a shell task that sets a longer timeout of its own
+            runOptions.maxTimeout = `${Math.max(1, Math.ceil(options.timeoutSeconds))}s`;
         }
         const submitted = await submitRun(this.connection, {
             definition: this.build.hash,
             tasks: [task],
-            source: { type: 'sandbox', id: this.id },
+            source: { type: 'sandbox', id: this.id, ...(options.check ? { check: true } : {}) },
             options: runOptions,
         });
         const followed = await followRun(this.connection, submitted, {
@@ -138,11 +185,68 @@ 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.
      */
     async exec(command, cwd, options = {}) {
+        if (!this.build.shell) {
+            throw new SandboxClientError('there is no shell on this sandbox (HAMMERKIT_SHELL is empty), run a task instead');
+        }
         // on its own line: `cd dir && a; b` would run b in the root when dir is missing
         const script = cwd && cwd !== '.' ? `cd -- ${quotePosix(cwd)} || exit 1\n${command}` : command;
         // a shell task in a container without `mounts: [.]` runs in an empty directory: the
@@ -203,25 +307,47 @@ function oneAtATime() {
 exports.oneAtATime = oneAtATime;
 // a run that is over, its state does not change any more
 exports.FINAL_RUN_STATES = ['succeeded', 'failed', 'cancelled', 'rejected'];
-// Submits a run, as `POST /v1/runs` takes it, and answers it as the server queued it or
-// holds it for an approval.
 async function submitRun(connection, request) {
     return json(await call(connection, 'POST', '/v1/runs', { body: request }));
 }
 exports.submitRun = submitRun;
 /**
  * Follows a run to its end: its log as it grows, and its state. A signal cancels the run
- * on the server and fails the follow.
+ * on the server and fails the follow. A service run that moved to another commit is followed
+ * from where its log was until it is there; a signal leaves it be, it was up before.
  */
+/** The commit a service run that moved was submitted to move to */
+function getMoveTarget(submitted) {
+    if (!submitted.moved) {
+        return undefined;
+    }
+    return submitted.moving?.commit ?? (submitted.source.type === 'ref' ? submitted.source.commit : undefined);
+}
+exports.getMoveTarget = getMoveTarget;
+// A service run is up; one that moved is where the move took it: up or asleep at the commit,
+// or back where it was, once it does not move there anymore
+function isThere(run, submitted) {
+    if (!submitted.moved) {
+        return run.state === 'up' && !run.moving;
+    }
+    if (run.moving?.commit === getMoveTarget(submitted)) {
+        return false;
+    }
+    return run.state === 'up' || run.state === 'asleep';
+}
 async function followRun(connection, submitted, options = {}) {
     const path = `/v1/runs/${encodeURIComponent(submitted.id)}`;
     let cancelling;
     const cancel = () => {
-        cancelling ?? (cancelling = call(connection, 'POST', `${path}/cancel`).catch(() => undefined));
+        if (!submitted.moved) {
+            cancelling ?? (cancelling = call(connection, 'POST', `${path}/cancel`).catch(() => undefined));
+        }
     };
-    options.signal?.addEventListener('abort', cancel, { once: true });
+    if (!options.detach) {
+        options.signal?.addEventListener('abort', cancel, { once: true });
+    }
     const lines = [];
-    let from = 1;
+    let from = submitted.moved?.logFrom ?? 1;
     let truncated = false;
     const add = (line) => {
         lines.push(line);
@@ -244,37 +370,29 @@ async function followRun(connection, submitted, options = {}) {
         let run = submitted;
         let waitingSaid = false;
         for (;;) {
+            if (options.signal?.aborted && options.detach) {
+                break;
+            }
             if (options.signal?.aborted) {
                 // the process may exit after this, so the cancel has to reach the server first
                 cancel();
                 let timer;
                 await Promise.race([cancelling, new Promise((resolve) => (timer = setTimeout(resolve, CANCEL_WAIT_MS)))]);
                 clearTimeout(timer);
-                throw new SandboxClientError('the run was cancelled');
+                throw new SandboxClientError(submitted.moved ? 'stopped following the run, it moves on without' : 'the run was cancelled');
             }
             if (run.state === 'awaiting-approval' && !waitingSaid) {
                 waitingSaid = true;
                 options.onWaiting?.(run);
             }
             await readLog();
-            if (exports.FINAL_RUN_STATES.includes(run.state)) {
+            if (exports.FINAL_RUN_STATES.includes(run.state) || (options.untilUp && isThere(run, submitted))) {
                 break;
             }
             run = await json(await call(connection, 'GET', path, { query: { wait: POLL_WAIT } }));
         }
         if (truncated) {
-            // the end of a long log is kept in the results
-            const tasks = options.task !== undefined ? [options.task] : Object.keys(run.results ?? {});
-            for (const task of tasks) {
-                const result = run.results?.[task];
-                if (!result) {
-                    continue;
-                }
-                const said = options.task !== undefined ? 'the last lines were' : `the last lines of ${task} were`;
-                for (const text of [`… the server cut the log off at its limit, ${said}:`, ...result.lastLog]) {
-                    add({ line: 0, task, stream: 'stdout', text });
-                }
-            }
+            truncatedEnd(run, options.task).forEach(add);
         }
         return { run, lines, truncated };
     }
@@ -283,6 +401,59 @@ async function followRun(connection, submitted, options = {}) {
     }
 }
 exports.followRun = followRun;
+// The end of a log the server cut off at its limit: the last lines of each task, which its
+// results keep.
+function truncatedEnd(run, only) {
+    const lines = [];
+    const tasks = only !== undefined ? [only] : Object.keys(run.results ?? {});
+    for (const task of tasks) {
+        const result = run.results?.[task];
+        if (!result) {
+            continue;
+        }
+        const said = only !== undefined ? 'the last lines were' : `the last lines of ${task} were`;
+        for (const text of [`… the server cut the log off at its limit, ${said}:`, ...result.lastLog]) {
+            lines.push({ line: 0, task, stream: 'stdout', text });
+        }
+    }
+    return lines;
+}
+// A run as the server keeps it, or null when it keeps none the caller may see.
+async function getRun(connection, id) {
+    const response = await call(connection, 'GET', `/v1/runs/${encodeURIComponent(id)}`, { missing: true });
+    return response.status === 404 ? null : json(response);
+}
+exports.getRun = getRun;
+/**
+ * Reads the log of a run as it is now, every line or the last `tail` of them, of one task or
+ * of all: also of a run that ended, as long as the server keeps it.
+ */
+async function readRunLog(connection, run, query, onLine) {
+    const path = `/v1/runs/${encodeURIComponent(run.id)}/logs`;
+    if (query.tail !== undefined) {
+        const page = await json(await call(connection, 'GET', path, { query: { task: query.task, tail: query.tail } }));
+        page.lines.forEach(onLine);
+        return { truncated: page.truncated };
+    }
+    let from = 1;
+    let truncated = false;
+    for (;;) {
+        const page = await json(await call(connection, 'GET', path, { query: { task: query.task, from, limit: 1000 } }));
+        truncated = page.truncated;
+        for (const line of page.lines) {
+            onLine(line);
+            from = line.line + 1;
+        }
+        if (!page.next) {
+            break;
+        }
+    }
+    if (truncated) {
+        truncatedEnd(run, query.task).forEach(onLine);
+    }
+    return { truncated };
+}
+exports.readRunLog = readRunLog;
 function exitCodeOf(result) {
     if (!result) {
         return null;

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