hammerkit 1.27.0-next.2 → 1.27.0-next.20

package/dist/harness/sandbox-client.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.quotePosix = exports.fetchFailure = exports.toSandboxPath = exports.checkSandboxPath = exports.exitCodeOf = exports.oneAtATime = exports.SandboxClient = exports.SandboxClientError = void 0;
+exports.quotePosix = exports.fetchFailure = exports.toSandboxPath = exports.checkSandboxPath = exports.exitCodeOf = exports.followRun = 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
 const TIMEOUT_MS = 60000;
 // a run is asked for this long at a time, the log is read in between
 const POLL_WAIT = '1s';
+// a cancelled run waits this long for the server to take the cancel, before it gives up
+const CANCEL_WAIT_MS = 10000;
 class SandboxClientError extends Error {
     constructor(message, status) {
         super(message);
@@ -14,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
@@ -32,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 } }));
     }
@@ -113,80 +161,92 @@ 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 json(await call(this.connection, 'POST', '/v1/runs', {
-            body: {
-                definition: this.build.hash,
-                tasks: [task],
-                source: { type: 'sandbox', id: this.id },
-                options: runOptions,
-            },
-        }));
-        const path = `/v1/runs/${encodeURIComponent(submitted.id)}`;
-        const cancel = () => {
-            call(this.connection, 'POST', `${path}/cancel`).catch(() => undefined);
-        };
-        options.signal?.addEventListener('abort', cancel, { once: true });
-        const lines = [];
-        let from = 1;
-        let truncated = false;
-        const readLog = async () => {
-            for (;;) {
-                const page = await json(await call(this.connection, 'GET', `${path}/logs`, { query: { task, from, limit: 1000 } }));
-                truncated = page.truncated;
-                for (const line of page.lines) {
-                    lines.push(line.text);
-                    options.onLine?.(line.text);
-                    from = line.line + 1;
-                }
-                if (!page.next) {
-                    return;
-                }
-            }
+        const submitted = await submitRun(this.connection, {
+            definition: this.build.hash,
+            tasks: [task],
+            source: { type: 'sandbox', id: this.id, ...(options.check ? { check: true } : {}) },
+            options: runOptions,
+        });
+        const followed = await followRun(this.connection, submitted, {
+            task,
+            signal: options.signal,
+            onLine: options.onLine ? (line) => options.onLine?.(line.text) : undefined,
+            onWaiting: options.onWaiting,
+        });
+        const result = followed.run.results?.[task];
+        return {
+            run: followed.run,
+            result,
+            output: followed.lines.map((line) => line.text).join('\n'),
+            truncated: followed.truncated,
+            exitCode: exitCodeOf(result),
         };
-        try {
-            let run = submitted;
-            let waitingSaid = false;
-            for (;;) {
-                if (options.signal?.aborted) {
-                    throw new SandboxClientError('the run was cancelled');
-                }
-                if (run.state === 'awaiting-approval' && !waitingSaid) {
-                    waitingSaid = true;
-                    options.onWaiting?.(run);
-                }
-                await readLog();
-                if (['succeeded', 'failed', 'cancelled', 'rejected'].includes(run.state)) {
-                    break;
-                }
-                run = await json(await call(this.connection, 'GET', path, { query: { wait: POLL_WAIT } }));
-            }
-            const result = run.results?.[task];
-            if (truncated && result) {
-                // the end of a long log is kept in the result
-                for (const line of ['… the server cut the log off at its limit, the last lines were:', ...result.lastLog]) {
-                    lines.push(line);
-                    options.onLine?.(line);
-                }
-            }
-            return {
-                run,
-                result,
-                output: lines.join('\n'),
-                truncated,
-                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`);
         }
-        finally {
-            options.signal?.removeEventListener('abort', cancel);
+        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
@@ -245,6 +305,88 @@ 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.
+ */
+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));
+    };
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    const lines = [];
+    let from = 1;
+    let truncated = false;
+    const add = (line) => {
+        lines.push(line);
+        options.onLine?.(line);
+    };
+    const readLog = async () => {
+        for (;;) {
+            const page = await json(await call(connection, 'GET', `${path}/logs`, { query: { task: options.task, from, limit: 1000 } }));
+            truncated = page.truncated;
+            for (const line of page.lines) {
+                add(line);
+                from = line.line + 1;
+            }
+            if (!page.next) {
+                return;
+            }
+        }
+    };
+    try {
+        let run = submitted;
+        let waitingSaid = false;
+        for (;;) {
+            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');
+            }
+            if (run.state === 'awaiting-approval' && !waitingSaid) {
+                waitingSaid = true;
+                options.onWaiting?.(run);
+            }
+            await readLog();
+            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 } }));
+        }
+        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 });
+                }
+            }
+        }
+        return { run, lines, truncated };
+    }
+    finally {
+        options.signal?.removeEventListener('abort', cancel);
+    }
+}
+exports.followRun = followRun;
 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