withruntime 0.21.0 → 0.33.0

package/dist/agents-file.d.ts

@@ -0,0 +1,19 @@
+import type { AgentsSource } from "./agents-deploy.js";
+export declare const AGENTS_FILE = "runtime.yml";
+/** Reads a runtime.yml for `agents().deploy`. YAML mistakes are
+ * refused here with their line; the agents' fields are checked by deploy. */
+export declare function loadAgentsFile(path?: string): AgentsSource;
+/** The largest runtime.yml read: 256 KiB. */
+export declare const AGENTS_FILE_MAX_BYTES: number;
+/** runtime.yml's text, parsed. `folder` is where `instructionsFile` is read
+ * from; without it, instructionsFile is refused. At most 256 KiB, and no
+ * anchors or aliases: a document of aliases of aliases ("billion laughs")
+ * would grow past every cap once expanded, so none is expanded at all. */
+export declare function parseAgentsFile(text: string, file?: string, folder?: string): AgentsSource;
+/** A starter `agents:` section for `runtime agents init`. */
+export declare function starterAgents(options: {
+    name: string;
+    template: string;
+    use?: "support" | "team";
+    instructionsFile?: string;
+}): string;

package/dist/agents-file.js

@@ -0,0 +1,135 @@
+/* runtime.yml on disk: read, parsed as YAML, with the line of each field for
+   messages and a reader for `instructionsFile` that stays inside the file's
+   folder. Node and Bun only (a browser gets agents/browser.ts, which leaves
+   it out, and the browser field maps it to a stub); the
+   check and the plan are agents-deploy.ts's. */
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { isMap, isNode, isScalar, isSeq, LineCounter, parseDocument, visit } from "yaml";
+import { RuntimeError } from "./errors.js";
+import { AGENT_USES, agentTemplate } from "./products/agents.js";
+export const AGENTS_FILE = "runtime.yml";
+/** Reads a runtime.yml for `agents().deploy`. YAML mistakes are
+ * refused here with their line; the agents' fields are checked by deploy. */
+export function loadAgentsFile(path = AGENTS_FILE) {
+    const full = resolve(path);
+    if (!existsSync(full))
+        throw new RuntimeError({
+            message: `${path} is not there.`,
+            code: "invalid_file",
+            status: 0,
+            hint: "Write one with `runtime agents init --template claude-code`, or pass --file.",
+            details: { file: path },
+        });
+    // Its size before a byte is read: a runtime.yml is a few KiB.
+    if (statSync(full).size > AGENTS_FILE_MAX_BYTES)
+        throw tooBig(path);
+    return parseAgentsFile(readFileSync(full, "utf8"), path, dirname(full));
+}
+/** The largest runtime.yml read: 256 KiB. */
+export const AGENTS_FILE_MAX_BYTES = 256 * 1024;
+const tooBig = (file) => new RuntimeError({
+    message: `${file} is over 256 KiB; a runtime.yml is a few KiB.`,
+    code: "invalid_file",
+    status: 0,
+    hint: "Keep long instructions in a file of their own and name it in instructionsFile.",
+    details: { file },
+});
+const refused = (file, message, hint) => new RuntimeError({ message, code: "invalid_file", status: 0, hint, details: { file } });
+/** runtime.yml's text, parsed. `folder` is where `instructionsFile` is read
+ * from; without it, instructionsFile is refused. At most 256 KiB, and no
+ * anchors or aliases: a document of aliases of aliases ("billion laughs")
+ * would grow past every cap once expanded, so none is expanded at all. */
+export function parseAgentsFile(text, file = AGENTS_FILE, folder) {
+    if (text.length > AGENTS_FILE_MAX_BYTES || Buffer.byteLength(text) > AGENTS_FILE_MAX_BYTES)
+        throw tooBig(file);
+    const lines = new LineCounter();
+    const doc = parseDocument(text, { lineCounter: lines, prettyErrors: true, uniqueKeys: true });
+    if (doc.errors.length)
+        throw refused(file, doc.errors
+            .map((e) => {
+            const at = e.linePos?.[0];
+            const said = e.message.split("\n")[0].replace(/ at line \d+, column \d+:?$/, "");
+            return `${file}${at ? `:${at.line}:${at.col}` : ""}: ${said}`;
+        })
+            .join("\n"), "runtime.yml is YAML; fix the line named and run it again. Nothing was changed.");
+    // Parsing keeps an alias as a node; only toJS would expand it.
+    let alias;
+    visit(doc, {
+        Alias(_, node) {
+            alias = node.range ? lines.linePos(node.range[0]).line : 0;
+            return visit.BREAK;
+        },
+    });
+    if (alias !== undefined)
+        throw refused(file, `${file}${alias ? `:${alias}` : ""}: anchors and aliases (&name, *name) are not taken in runtime.yml.`, "Write each value out where it is used. Nothing was changed.");
+    const config = doc.toJS({ maxAliasCount: 0 });
+    // The line of the deepest key the path reaches: a field's own, or for a
+    // missing one, its agent's name.
+    const line = (path) => {
+        let node = doc.contents;
+        let found;
+        const at = (n) => isNode(n) && n.range ? (found = lines.linePos(n.range[0]).line) : undefined;
+        for (const part of path) {
+            if (isMap(node)) {
+                const pair = node.items.find((p) => (isScalar(p.key) ? p.key.value : p.key) === part);
+                if (!pair)
+                    break;
+                at(pair.key);
+                node = pair.value;
+            }
+            else if (isSeq(node) && typeof part === "number" && node.items[part] !== undefined) {
+                node = node.items[part];
+                at(node);
+            }
+            else
+                break;
+        }
+        return found;
+    };
+    return {
+        file,
+        config,
+        line,
+        ...(folder === undefined ? {} : { readFile: (name) => readInside(folder, name) }),
+    };
+}
+/** A file inside `folder`, never outside it, through a link included. */
+function readInside(folder, name) {
+    const root = realpathSync(folder);
+    const target = realpathSync(resolve(root, name));
+    const rel = relative(root, target);
+    if (rel === "" || rel.startsWith(`..${sep}`) || rel === ".." || resolve(rel) === rel)
+        throw new Error(`${name} is outside ${folder}`);
+    return readFileSync(target, "utf8");
+}
+/** A starter `agents:` section for `runtime agents init`. */
+export function starterAgents(options) {
+    const t = agentTemplate(options.template);
+    const words = options.instructionsFile
+        ? `    instructionsFile: ${options.instructionsFile}${pad(options.instructionsFile.length + 18)}# its instructions, read from the repo`
+        : `    instructions: |\n      You work on this repository. Say what you changed and why.`;
+    const use = options.use
+        ? `    use: ${options.use}${pad(options.use.length + 5)}# ${AGENT_USES[options.use].title.toLowerCase()}: its size and bounds`
+        : `    # use: team                  # or support: a size and bounds for that use`;
+    return [
+        "# Runtime Agents. `runtime agents deploy` makes your account's agents match",
+        "# this section; `runtime agents deploy --dry-run` shows what it would change.",
+        "agents:",
+        `  ${options.name}:`,
+        `    template: ${options.template}${pad(options.template.length + 10)}# ${t.title}: its command, and its model key's secret`,
+        words,
+        use,
+        "    # vcpu: 4                    # the default size: 4 vCPU, 8 GiB",
+        "    # memoryMiB: 8192",
+        "    # maxSessionDollars: 5       # the default budgets: a session stops at $5,",
+        "    # maxDayDollars: 100         # and the agent starts nothing new past $100 a day",
+        "    # triggers:",
+        "    #   - kind: schedule",
+        '    #     config: { cron: "0 9 * * 1-5", input: "Triage the new issues." }',
+        `# Its model key, stored once as an egress secret the sandbox never sees:`,
+        `#   printf %s "$${t.apiKeySecret}" | runtime secrets set ${t.apiKeySecret} --host ${t.apiKeyHost}`,
+        "",
+    ].join("\n");
+}
+const pad = (used) => " ".repeat(Math.max(1, 29 - used));

package/dist/apps/index.d.ts

@@ -0,0 +1,10 @@
+/** `withruntime/apps`: Apps alone. An image served on copies that wake on a
+ * request and freeze when quiet. In a private beta.
+ *
+ *   import { apps } from "withruntime/apps";
+ *   const client = apps(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/apps.js";
+/** `runtime.apps` of a client made with `options`. */
+export declare function apps(options?: RuntimeOptions): Runtime["apps"];

package/dist/apps/index.js

@@ -0,0 +1,11 @@
+/** `withruntime/apps`: Apps alone. An image served on copies that wake on a
+ * request and freeze when quiet. In a private beta.
+ *
+ *   import { apps } from "withruntime/apps";
+ *   const client = apps(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.apps` of a client made with `options`. */
+export function apps(options) {
+    return new Runtime(options).apps;
+}

package/dist/apps-cli.d.ts

@@ -5,10 +5,12 @@ type Out = {
     write: (text: string) => void;
     error: (text: string) => void;
 };
-export declare const APP_HELP = "runtime apps <command>\n\n  An App serves your web server from an image or a build. Copies start when\n  requests come and stop when they end, between --min-copies and --max-copies.\n  In a private beta: outside it, each command says how to ask to join.\n\n  create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>\n         [--min-copies 0] [--concurrency 100] [--spares 2] [--port 8080]\n         [--health-path /healthz] [--label key=value]...\n                                              Make an App, waiting for its first deploy; prints its id\n  ls [--all]                                  Your Apps: state, live version, copies; --all, deleted too\n  get <app>                                   One App, in full (an id or its name)\n  update <app> [--name <name>] [--vcpu n] [--memory n] [--min-copies n] [--max-copies n]\n         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--label key=value]...\n                                              Change its settings\n  rm <app>                                    Delete it and stop its copies\n  deploy <app> (--image <image> | --build <buildId>) [--env KEY=VALUE]... [--keep-env]\n         [--port 8080] [--health-path /healthz] [--no-wait]\n                                              A new version. Waits until it is live, or says why it\n                                              failed; --no-wait prints the deploy's id at once.\n                                              --image: an image of yours (id, name, name:tag);\n                                              --build: a build that succeeded (runtime builds).\n                                              --env KEY alone sends KEY's value from your environment.\n                                              --keep-env keeps the last deploy's environment, sealed\n  deploys <app> [<deployId>] [--wait]         Each version's deploy: state and address; with an id,\n                                              that one (--wait: until it ends)\n  versions <app>                              Its versions; the live and previous ones keep saved copies\n  copies <app>                                Its copies now: version, region, state\n  rollback <app> [--no-wait]                  Put the previous version live again\n\nExamples\n  runtime apps create web --vcpu 1 --memory 512 --max-copies 3\n  runtime apps deploy web --image web:latest --env NODE_ENV=production\n  runtime apps rollback web\n";
+export declare const APP_HELP = "runtime apps <command>\n\n  An App serves your web server from an image or a build. Copies start when\n  requests come and stop when they end, between --min-copies and --max-copies.\n  In a private beta: outside it, each command says how to ask to join.\n\n  create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>\n         [--min-copies 0] [--concurrency 100] [--spares 2] [--port 8080]\n         [--health-path /healthz] [--health-fail 60] [--stop-grace 30] [--cdn on|off]\n         [--volume <volumeId>:<path>] [--label key=value]...\n                                              Make an App, waiting for its first deploy; prints its id.\n                                              --health-fail: seconds a live copy may fail its health\n                                              check before it is replaced. --stop-grace: seconds a\n                                              stopped copy has after SIGTERM. --volume mounts one\n                                              volume of yours at a path under /data, /mnt, /state,\n                                              /storage or /volumes, in the App's one copy: it needs\n                                              --max-copies 1 (--min-copies is then 1, --spares 0), and\n                                              each deploy stops the old copy before the new one boots\n  ls [--all]                                  Your Apps: state, live version, copies; --all, deleted too\n  get <app>                                   One App, in full (an id or its name)\n  update <app> [--name <name>] [--vcpu n] [--memory n] [--min-copies n] [--max-copies n]\n         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--health-fail n]\n         [--stop-grace n] [--volume <volumeId>:<path> | none] [--cdn on|off]\n         [--label key=value]...\n                                              Change its settings; --volume none takes the volume\n                                              away, only before its first deploy;\n                                              --cdn off sends visitors straight to Runtime's routers,\n                                              with nothing cached (on: Cloudflare's CDN in front)\n  rm <app>                                    Delete it and stop its copies\n  deploy <app> (--image <image> | --build <buildId>) [--env KEY=VALUE]... [--keep-env]\n         [--port 8080] [--health-path /healthz] [--no-wait]\n                                              A new version. Waits until it is live, or says why it\n                                              failed; --no-wait prints the deploy's id at once.\n                                              --image: an image of yours (id, name, name:tag);\n                                              --build: a build that succeeded (runtime builds).\n                                              --env KEY alone sends KEY's value from your environment.\n                                              --keep-env keeps the last deploy's environment, sealed\n  deploys <app> [<deployId>] [--wait]         Each version's deploy: state and address; with an id,\n                                              that one (--wait: until it ends)\n  versions <app>                              Its versions; the live and previous ones keep saved copies\n  copies <app>                                Its copies now: version, region, state\n  logs <app> [--follow] [--since 1h] [--version n] [--copy <copyId>] [--stream stdout|stderr]\n         [--limit 100] [--raw]                What its copies printed: the newest lines since --since\n                                              (a time, or 30s, 15m, 2h, 7d; kept 14 days), or with\n                                              --follow every line as it comes, until Ctrl-C. On a\n                                              terminal control characters show as \\uXXXX unless --raw\n  exec <app> [--copy <id>] [--root] [--cwd <dir>] [--env K=V]... [--timeout <ms>] [--trace-files <file.json>] -- <command>\n                                              Run a command in its live copy\n  cp <file> <app>:/<path> [--copy <id>]       Copy a file onto its live copy\n  cp <app>:/<path> <file> [--copy <id>]       Copy a file off it\n  exec and cp go to a serving copy of the live version unless --copy names\n  one. A copy holds the App's secrets, so only an owner's or admin's key\n  reaches into one. A file written to a copy lasts as long as that copy; a\n  deploy replaces its copies.\n  rollback <app> [--no-wait]                  Put the previous version live again\n  restart <app> [--no-wait]                   Start the live version afresh, as a deploy of its own;\n                                              with a volume, the old copy stops first and the\n                                              downtime is said\n\nExamples\n  runtime apps create web --vcpu 1 --memory 512 --max-copies 3\n  runtime apps deploy web --image web:latest --env NODE_ENV=production\n  runtime apps logs web --follow\n  runtime apps rollback web\n  runtime apps create db --vcpu 1 --memory 1024 --max-copies 1 --volume <volumeId>:/data\n";
+export declare const FUNCTION_HELP = "runtime functions <command>\n\n  A Function serves your HTTP handler from an image or a build, at its own\n  address. Copies start when calls come, up to --max-copies, and sleep when\n  they stop: an idle Function has no copy awake.\n  In a private beta: outside it, each command says how to ask to join.\n\n  create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>\n         [--concurrency 100] [--spares 2] [--port 8080]\n         [--health-path /healthz] [--health-fail 60] [--label key=value]...\n                                              Make a Function, waiting for its first deploy; prints its id.\n                                              --health-fail: seconds a live copy may fail its health\n                                              check before it is replaced\n  ls [--all]                                  Your Functions: state, live version, copies; --all, deleted too\n  get <function>                              One Function, in full (an id or its name)\n  update <function> [--name <name>] [--vcpu n] [--memory n] [--max-copies n]\n         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--health-fail n]\n         [--label key=value]...\n                                              Change its settings\n  rm <function>                               Delete it and stop its copies\n  deploy <function> (--image <image> | --build <buildId>) [--env KEY=VALUE]... [--keep-env]\n         [--port 8080] [--health-path /healthz] [--no-wait]\n                                              A new version. Waits until it is live, or says why it\n                                              failed; --no-wait prints the deploy's id at once.\n                                              --image: an image of yours (id, name, name:tag);\n                                              --build: a build that succeeded (runtime builds).\n                                              --env KEY alone sends KEY's value from your environment.\n                                              --keep-env keeps the last deploy's environment, sealed\n  deploys <function> [<deployId>] [--wait]    Each version's deploy: state and address; with an id,\n                                              that one (--wait: until it ends)\n  versions <function>                         Its versions; the live and previous ones keep saved copies\n  copies <function>                           Its copies now: version, region, state\n  logs <function> [--follow] [--since 1h] [--version n] [--copy <copyId>] [--stream stdout|stderr]\n         [--limit 100] [--raw]                What its copies printed: the newest lines since --since\n                                              (a time, or 30s, 15m, 2h, 7d; kept 14 days), or with\n                                              --follow every line as it comes, until Ctrl-C. On a\n                                              terminal control characters show as \\uXXXX unless --raw\n  rollback <function> [--no-wait]             Put the previous version live again\n  restart <function> [--no-wait]              Start the live version afresh, as a deploy of its own\n\nExamples\n  runtime functions create resize --vcpu 1 --memory 512 --max-copies 10\n  runtime functions deploy resize --image resize:latest\n  runtime functions logs resize --follow\n  runtime functions rollback resize\n";
 export declare const BUILD_HELP = "runtime builds <command>\n\n  A build turns a commit of a connected repository into a saved server an App\n  deploys. A push to the production branch builds and deploys by itself.\n  In a private beta: outside it, each command says how to ask to join.\n\n  repos connect <owner/name | https URL> --deploy <app name> [--branch main] [--no-previews]\n        [--root <folder>] [--install <command>] [--build <command>] [--start <command>]\n        [--port 8080] [--health-path /healthz] [--build-env KEY=VALUE]... [--name <name>]\n                                              Connect a repository; prints its id. --deploy takes an\n                                              App's name, or function:<name>. --start runs once the\n                                              build is done, with PORT set: the server the App deploys\n  repos ls                                    Connected repositories\n  repos change <repoId> [the options of connect but the repository]\n                                              Change its settings; its id and builds stay\n  repos disconnect <repoId>                   Stop building it; its builds stay\n  repos install                               A link to install Runtime's GitHub App, so a private\n                                              repository builds\n  create <repoId> [--ref main] [--branch <name>] [--name <name>]\n                                              Build a branch, tag or commit now; prints the build's id\n  run <repoId> [--ref main] [--branch <name>] [--name <name>] [--raw]\n                                              The same, then follows its log; exits 0 once it succeeds\n  ls [--repository <repoId>] [--commit <sha>] [--state <state>]...\n                                              Builds, oldest first; --commit: a full sha\n  get <buildId>                               One build: state, commit, step times, what it made\n  cancel <buildId>                            Stop a build that has not ended\n  logs <buildId> [--follow] [--raw]           Its last 200 lines, or every line as it comes until it\n                                              ends; on a terminal control characters show as \\uXXXX\n                                              unless --raw\n\nExamples\n  runtime builds repos connect acme/web --deploy web --start \"npm start\"\n  runtime builds run <repoId> --ref main\n  runtime builds ls --commit $(git rev-parse HEAD)\n";
 export declare const CONTAINER_HELP = "runtime containers <command>\n\n  A container runs one OCI image's process on its own microVM, billed at the\n  sandbox rates. It never sleeps unless --sleep; on exit it restarts when it\n  serves a port, else it stops (--on-exit sets either).\n  In a private beta: outside it, each command says how to ask to join.\n\n  create <image> --vcpu <1-16> --memory <128-65536> [--name <name>] [--label key=value]...\n         [--env KEY[=VALUE]]... [--entrypoint <program>] [--workdir /app] [--user <user>]\n         [--port <1-65535>] [--on-exit restart|stop] [--sleep] [-- <command...>]\n                                              Run it; prints its id. The image's digest is pinned.\n                                              --env KEY alone sends KEY's value from your environment.\n                                              --entrypoint drops the image's command; after --, the\n                                              command replaces the image's\n  ls [--all] [--state <state>]... [--label key=value]...\n                                              Your containers: all but deleting and deleted, unless\n                                              --all or --state\n  get <container>                             One container, in full (an id or its name): its\n                                              environment's names, never their values\n  update <container> [--name <name>] [--label key=value]...\n                                              Rename it or replace its labels\n  rm <container> [--wait]                     Delete it and stop its process; --wait: until deleted\n\nExamples\n  runtime containers create nginx:1.27 --vcpu 1 --memory 512 --name web\n  runtime containers create python:3.12 --vcpu 1 --memory 1024 -- python3 -m http.server 8000\n  runtime containers rm web --wait\n";
 export declare function appsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export declare function functionsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
 export declare function buildsCommand(argv: string[], out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
 export declare function containersCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
 export {};