esoul-sdk 0.18.0 → 0.19.0

package/bin/esoul-device-program.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// The process an app's PROGRAM runs in (computer-apps.md §4.1). The runtime
+// starts it with an IPC channel, inside the link's sandbox, and relays:
+//
+//   runtime → here   { t: "init", ctx }                       once, first
+//                    { t: "msg", id, topic, data }            a message from the app
+//                    { t: "opResult", id, ok, result, error } the answer to p.op
+//                    { t: "stop" }                            stop cleanly
+//   here → runtime   { t: "started" } | { t: "status", text, progress, ready }
+//                    { t: "op", id, name, args, key }         call one of the app's ops
+//                    { t: "msgResult", id, ok, result, error }
+//                    { t: "log", line } | { t: "fatal", error }
+//
+// Plain JavaScript with no imports beyond node: — it runs from any copy of the
+// package with nothing built. The program's entry may be TypeScript; the
+// runtime starts Node with type stripping for a .ts entry.
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
+import { format } from "node:util";
+
+const [programDir, entry] = process.argv.slice(2);
+if (!programDir || !entry || typeof process.send !== "function") {
+  console.error("usage: started by esoul-device with an IPC channel: esoul-device-program <program-dir> <entry>");
+  process.exit(2);
+}
+const send = (m) => {
+  try {
+    process.send(m);
+  } catch {
+    /* the runtime is gone; the process exits with it */
+  }
+};
+const handlers = new Map();
+const pendingOps = new Map();
+const timers = new Set();
+let nextId = 1;
+let program = null;
+let stopping = false;
+
+const logLine = (...a) => send({ t: "log", line: format(...a).slice(0, 4000) });
+console.log = logLine;
+console.info = logLine;
+console.warn = (...a) => logLine("warn:", ...a);
+console.error = (...a) => logLine("error:", ...a);
+
+function api(ctx) {
+  return Object.freeze({
+    computer: Object.freeze({ ...ctx.computer }),
+    appName: ctx.appName,
+    programDir,
+    dataDir: ctx.dataDir,
+    workspaceRoot: ctx.workspaceRoot ?? null,
+    config: Object.freeze({ ...ctx.config }),
+    status(text, extra = {}) {
+      send({ t: "status", text: String(text).slice(0, 300), progress: typeof extra.progress === "number" ? Math.max(0, Math.min(1, extra.progress)) : undefined, ready: extra.ready === true ? true : undefined });
+    },
+    op(name, args, opts = {}) {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        pendingOps.set(id, { resolve, reject });
+        send({ t: "op", id, name: String(name), args: args ?? null, key: opts.key ?? null });
+      });
+    },
+    on(topic, handler) {
+      if (typeof handler !== "function") throw new TypeError(`p.on("${topic}") needs a function`);
+      handlers.set(String(topic), handler);
+    },
+    every(ms, fn) {
+      const period = Math.max(1000, Number(ms) || 0);
+      let busy = false;
+      const tick = async () => {
+        if (busy || stopping) return;
+        busy = true;
+        try {
+          await fn();
+        } catch (e) {
+          logLine(`error: every(${period}) failed: ${e?.stack ?? e}`);
+        } finally {
+          busy = false;
+        }
+      };
+      const t = setInterval(tick, period);
+      timers.add(t);
+      return () => {
+        clearInterval(t);
+        timers.delete(t);
+      };
+    },
+    log: logLine,
+  });
+}
+
+async function stop(code = 0) {
+  if (stopping) return;
+  stopping = true;
+  for (const t of timers) clearInterval(t);
+  try {
+    await program?.stop?.();
+  } catch (e) {
+    logLine(`error: stop failed: ${e?.stack ?? e}`);
+  }
+  setTimeout(() => process.exit(code), 50);
+}
+
+process.on("message", async (m) => {
+  if (!m || typeof m !== "object") return;
+  if (m.t === "init") {
+    try {
+      const mod = await import(pathToFileURL(join(programDir, entry)).href);
+      program = mod.default ?? mod.program;
+      if (!program || typeof program.start !== "function") throw new Error(`${entry} must export default { start(p) { … } }`);
+      await program.start(api(m.ctx));
+      send({ t: "started" });
+    } catch (e) {
+      send({ t: "fatal", error: String(e?.stack ?? e).slice(0, 4000) });
+      setTimeout(() => process.exit(1), 50);
+    }
+    return;
+  }
+  if (m.t === "opResult") {
+    const p = pendingOps.get(m.id);
+    if (!p) return;
+    pendingOps.delete(m.id);
+    if (m.ok) p.resolve(m.result);
+    else p.reject(new Error(m.error ?? "the op failed"));
+    return;
+  }
+  if (m.t === "msg") {
+    const h = handlers.get(m.topic);
+    if (!h) {
+      send({ t: "msgResult", id: m.id, ok: false, error: `this program has no handler for "${m.topic}" (p.on("${m.topic}", …))` });
+      return;
+    }
+    try {
+      const result = await h(m.data);
+      send({ t: "msgResult", id: m.id, ok: true, result: result === undefined ? null : result });
+    } catch (e) {
+      send({ t: "msgResult", id: m.id, ok: false, error: String(e?.message ?? e).slice(0, 2000) });
+    }
+    return;
+  }
+  if (m.t === "stop") void stop(0);
+});
+process.on("disconnect", () => void stop(0));
+process.on("SIGTERM", () => void stop(0));
+process.on("unhandledRejection", (e) => logLine(`error: unhandled rejection: ${e?.stack ?? e}`));

package/dist/device.d.ts

@@ -11,6 +11,8 @@
  *        const { commandId } = await d.run("train", { epochs: 3 });
  *   3. its UI shows the run live with useDeviceRun({ workspaceId, nodeId, commandId }).
  */
+import type { ProgramState } from "./machine/program-api.js";
+export type { ProgramState, ProgramStepState } from "./machine/program-api.js";
 export type DeviceRunStatus = "queued" | "claimed" | "running" | "done" | "expired" | "cancelled" | "lost";
 /** What an app's agents may reach on a computer through the shared command line. */
 export type WorkspaceGrant = {
@@ -56,6 +58,10 @@ export interface DeviceSummary {
     } | null;
     /** What this app's agents may reach on that computer (null = declared commands only). */
     workspace?: WorkspaceGrant | null;
+    /** Whether the owner approved this app's program on that computer. */
+    program?: boolean;
+    /** Where the app's program stands there (installing, setup, running, failed…), as the computer last reported it. */
+    programState?: ProgramState | null;
 }
 export interface DeviceRunStarted {
     commandId: string;
@@ -131,6 +137,25 @@ export interface Devices {
         commandId: string;
         status: DeviceRunStatus;
     }>;
+    /**
+     * The app's own program on one computer (plugin.json `device.program`,
+     * computer-apps.md §4.1). `send(topic, data)` hands the program a message;
+     * its `p.on(topic)` handler's return value is the answer. Waits up to
+     * `waitSeconds` (default 30, ≤ 55); with 0 it returns at once and the answer
+     * arrives on the run (`get`/`wait`).
+     */
+    program(linkId: string): {
+        send(topic: string, data?: unknown, opts?: {
+            waitSeconds?: number;
+        }): Promise<{
+            commandId: string;
+            status: DeviceRunStatus;
+            ok: boolean;
+            result: unknown;
+            error: string | null;
+        }>;
+        state(): Promise<ProgramState | null>;
+    };
 }
 /** The statuses a run ends in: done, expired, cancelled, lost. */
 export declare const DEVICE_RUN_TERMINAL: readonly DeviceRunStatus[];

package/dist/machine/capabilities.d.ts

@@ -64,12 +64,23 @@ export interface WorkspaceJobParams {
 }
 /** The shared command line, under grant ∩ ceiling, one working directory per named agent. */
 export declare function workspaceCapability(): Capability;
+/** The part of the program manager a message job needs (program-manager.ts). */
+export interface ProgramDelivery {
+    has(linkId: string): boolean;
+    deliver(linkId: string, topic: string, data: unknown, signal?: AbortSignal): Promise<{
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+    }>;
+}
+/** A message from the app to its program on this computer; the program's answer is the job's result. */
+export declare function programCapability(programs: ProgramDelivery | null): Capability;
 /** The capability table the runtime dispatches jobs through, by name. */
 export declare function registry(caps: Capability[]): Map<string, Capability>;
 /** What the hello announces: ["commands@1", "workspace@1"]. */
 export declare function announce(reg: Map<string, Capability>): string[];
 /** The capabilities this runtime is built with, as one registry (the supervisor dispatches through it). */
-export declare function builtInCapabilities(startRun: (job: Job, redact: string[], env: Record<string, string>) => Promise<void>): Map<string, Capability>;
+export declare function builtInCapabilities(startRun: (job: Job, redact: string[], env: Record<string, string>) => Promise<void>, programs?: ProgramDelivery | null): Map<string, Capability>;
 /**
  * What this runtime can do, said at CONNECT as well as in every hello, so the
  * platform knows it from the approval on: work asked for before the runtime's

package/dist/machine/capabilities.js

@@ -187,6 +187,40 @@ export function workspaceCapability() {
         },
     };
 }
+/** A message from the app to its program on this computer; the program's answer is the job's result. */
+export function programCapability(programs) {
+    return {
+        name: "program",
+        version: 1,
+        refuse(job, ctx) {
+            if (!programs)
+                return "this runtime runs no programs";
+            if (!ctx.link.commands?.program?.digest)
+                return "the owner has not approved a program for this app on this computer";
+            if (!programs.has(job.linkId))
+                return "the approved program is not installed here yet";
+            return null;
+        },
+        async start(job, ctx) {
+            markStart(ctx.home, job.commandId);
+            const ac = new AbortController();
+            ctx.signal.addEventListener("abort", () => ac.abort());
+            const up = new OutputUploader(ctx.client, job.commandId, job.output ?? resolveOutput({ mode: "final" }), () => ac.abort());
+            await ctx.client.call("POST", `/api/device/m/commands/${job.commandId}/started`, { startedAt: Date.now() }).catch(() => { });
+            void (async () => {
+                const r = await programs.deliver(job.linkId, job.name, job.params.data ?? null, ac.signal);
+                const outcome = r.ok ? { exitCode: 0, result: r.result ?? null } : { exitCode: 1, reason: r.error ?? "the program did not answer", result: null };
+                try {
+                    await up.finish(outcome);
+                    markDone(ctx.home, job.commandId);
+                }
+                catch (e) {
+                    ctx.log(`program message ${job.commandId}: could not report (${e.message}); it will be reported lost on restart`);
+                }
+            })();
+        },
+    };
+}
 /** The capability table the runtime dispatches jobs through, by name. */
 export function registry(caps) {
     return new Map(caps.map((c) => [c.name, c]));
@@ -196,8 +230,8 @@ export function announce(reg) {
     return [...reg.values()].map((c) => `${c.name}@${c.version}`);
 }
 /** The capabilities this runtime is built with, as one registry (the supervisor dispatches through it). */
-export function builtInCapabilities(startRun) {
-    return registry([commandsCapability({ startRun }), workspaceCapability()]);
+export function builtInCapabilities(startRun, programs = null) {
+    return registry([commandsCapability({ startRun }), workspaceCapability(), programCapability(programs)]);
 }
 /**
  * What this runtime can do, said at CONNECT as well as in every hello, so the

package/dist/machine/commands.d.ts

@@ -101,8 +101,48 @@ export interface ConfigKeySpec {
     required?: boolean;
     describe?: string;
 }
+/** One setup step of a program: argv (never a shell line), run once per program digest and declared inputs. */
+export interface SetupStepSpec {
+    /** lowercase id, unique in the program: `venv`, `torch`. */
+    id: string;
+    /** What the step does, in words, shown on the approval and in the progress list. */
+    describe: string;
+    /** argv run in the program's data folder; `{program}` stands for the program's own folder. */
+    run: string[];
+    /** Program files whose contents decide whether the step runs again (`device/requirements.txt`). */
+    inputs?: string[];
+    /** Default 1800 s, at most 6 h. */
+    timeoutSeconds?: number;
+}
+/**
+ * The app's own program on the computer (`computer-apps.md` §4.1): the files
+ * of `device/` shipped per app version, set up once, then started — at
+ * approval when `resident`, or when the app first sends it a message.
+ */
+export interface ProgramSpec {
+    /** The entry file, under `device/`: `device/main.ts`, `device/main.js`, `device/main.mjs`. */
+    main: string;
+    /** Kept running from approval on (a monitor), instead of started on the first message. */
+    resident?: boolean;
+    setup?: SetupStepSpec[];
+    /** argv that must exit 0 before the program counts as ready. */
+    selfTest?: {
+        run: string[];
+        timeoutSeconds?: number;
+    };
+    /** Filled in by the platform's build: the sha256 of the spec and every file. Never written by hand. */
+    digest?: string;
+    /** Filled in by the platform's build: the files' total size in bytes. */
+    size?: number;
+}
+/** A program's files: at most this many bytes in all (setup steps download the heavy things). */
+export declare const PROGRAM_MAX_BYTES: number;
+/** A program's files: at most this many. */
+export declare const PROGRAM_MAX_FILES = 200;
 export interface DeviceBlock {
     commands: Record<string, CommandSpec>;
+    /** The app's own program on the computer. */
+    program?: ProgramSpec;
     /** Values set ON THE MACHINE (`esoul-device config set`), never sent to the platform. */
     config?: Record<string, ConfigKeySpec>;
     /** Regexes applied to output on the machine before any byte leaves it. */
@@ -123,6 +163,8 @@ export declare class DeviceCommandError extends Error {
 }
 /** Every problem with a `device` block, in words an author can act on. Empty = valid. */
 export declare function deviceBlockProblems(block: unknown): string[];
+/** What is wrong with a program spec, in words (the platform's build adds `digest` and `size`). */
+export declare function programProblems(p: unknown): string[];
 export interface RenderedCommand {
     name: string;
     argv: string[];

package/dist/machine/commands.js

@@ -37,6 +37,11 @@ export function resolveOutput(spec) {
         tailMaxChars: keep === "head" ? 0 : OUTPUT_LIMITS.tailChars,
     };
 }
+/** A program's files: at most this many bytes in all (setup steps download the heavy things). */
+export const PROGRAM_MAX_BYTES = 2 * 1024 * 1024;
+/** A program's files: at most this many. */
+export const PROGRAM_MAX_FILES = 200;
+const SETUP_ID_RE = /^[a-z][a-z0-9-]{0,31}$/;
 /** What a command name may look like: lowercase, starts with a letter, up to 40 characters. */
 export const COMMAND_NAME_RE = /^[a-z][a-z0-9_-]{0,39}$/;
 const PARAM_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,39}$/;
@@ -65,10 +70,14 @@ export function deviceBlockProblems(block) {
     if (!block || typeof block !== "object")
         return ["device must be an object with `commands`"];
     const b = block;
-    if (!b.commands || typeof b.commands !== "object")
-        return ["device.commands must list at least one command"];
-    const names = Object.keys(b.commands);
-    if (names.length === 0)
+    if (b.program !== undefined)
+        out.push(...programProblems(b.program));
+    if (b.commands !== undefined && (typeof b.commands !== "object" || b.commands === null))
+        return [...out, "device.commands must be an object of named commands"];
+    if (!b.commands && !b.program)
+        return ["device must declare commands, a program, or both"];
+    const names = Object.keys(b.commands ?? {});
+    if (names.length === 0 && !b.program)
         out.push("device.commands must list at least one command");
     if (names.length > 64)
         out.push("device.commands lists more than 64 commands");
@@ -163,6 +172,49 @@ export function deviceBlockProblems(block) {
         out.push(`device.onAppDeleted must be "kill" or "finish"`);
     return out;
 }
+/** What is wrong with a program spec, in words (the platform's build adds `digest` and `size`). */
+export function programProblems(p) {
+    const out = [];
+    if (!p || typeof p !== "object")
+        return ["device.program must be an object with `main`"];
+    const g = p;
+    if (typeof g.main !== "string" || !/^device\/[A-Za-z0-9_./-]+\.(ts|js|mjs)$/.test(g.main) || g.main.split("/").includes(".."))
+        out.push("device.program.main must be a .ts, .js or .mjs file under device/ (device/main.ts)");
+    if (g.resident !== undefined && typeof g.resident !== "boolean")
+        out.push("device.program.resident must be true or false");
+    const argvOk = (a) => Array.isArray(a) && a.length > 0 && a.every((x) => typeof x === "string") && !!a[0];
+    const ids = new Set();
+    if (g.setup !== undefined) {
+        if (!Array.isArray(g.setup))
+            out.push("device.program.setup must be a list of steps");
+        else {
+            if (g.setup.length > 20)
+                out.push("device.program.setup has more than 20 steps");
+            g.setup.forEach((st, i) => {
+                const at = `device.program.setup[${i}]`;
+                if (!st || typeof st !== "object")
+                    return void out.push(`${at} must be an object`);
+                if (typeof st.id !== "string" || !SETUP_ID_RE.test(st.id))
+                    out.push(`${at}.id must match ${SETUP_ID_RE}`);
+                else if (ids.has(st.id))
+                    out.push(`${at}.id "${st.id}" is used twice`);
+                else
+                    ids.add(st.id);
+                if (typeof st.describe !== "string" || !st.describe.trim())
+                    out.push(`${at}.describe says what the step does, in words`);
+                if (!argvOk(st.run))
+                    out.push(`${at}.run must be a non-empty argv (a list of strings, never a shell line)`);
+                if (st.inputs !== undefined && (!Array.isArray(st.inputs) || st.inputs.some((f) => typeof f !== "string" || !f.startsWith("device/"))))
+                    out.push(`${at}.inputs must list program files under device/`);
+                if (st.timeoutSeconds !== undefined && !(Number.isInteger(st.timeoutSeconds) && st.timeoutSeconds > 0 && st.timeoutSeconds <= 6 * 3600))
+                    out.push(`${at}.timeoutSeconds must be a whole number of seconds up to 21600`);
+            });
+        }
+    }
+    if (g.selfTest !== undefined && (!g.selfTest || !argvOk(g.selfTest.run)))
+        out.push("device.program.selfTest.run must be a non-empty argv");
+    return out;
+}
 function checkValue(name, spec, v) {
     const k = kindOf(spec);
     const o = typeof spec === "object" ? spec : {};

package/dist/machine/digest.d.ts

@@ -1,8 +1,20 @@
-import type { CommandSpec, DeviceBlock } from "./commands.js";
+import type { CommandSpec, DeviceBlock, ProgramSpec } from "./commands.js";
 /** Stable digest of one command's spec — what the owner approved. */
 export declare function commandDigest(spec: CommandSpec): string;
-/** Every declared command's digest, by name — what an approval records. */
+/** Where an approval records the program's digest, beside the commands' (no command name can start with "@"). */
+export declare const PROGRAM_KEY = "@program";
+/** Every declared command's digest, by name, and the program's under `@program` — what an approval records. */
 export declare function commandDigests(block: DeviceBlock): Record<string, string>;
+/** The command names an approval covers (without the program's entry). */
+export declare function approvedCommandNames(approved: Record<string, string>): string[];
+/**
+ * The digest of a program: its spec (without the computed fields) and every
+ * file, sorted by path. Two builds of the same files give the same digest.
+ */
+export declare function programDigest(spec: Omit<ProgramSpec, "digest" | "size">, files: {
+    path: string;
+    content: Buffer | Uint8Array | string;
+}[]): string;
 /**
  * What an app update asks of the owner. Removing a command, or leaving one
  * untouched, needs nothing; ADDING a command or CHANGING one is new authority

package/dist/machine/digest.js

@@ -17,13 +17,35 @@ function stable(v) {
 export function commandDigest(spec) {
     return createHash("sha256").update(stable(spec)).digest("hex").slice(0, 32);
 }
-/** Every declared command's digest, by name — what an approval records. */
+/** Where an approval records the program's digest, beside the commands' (no command name can start with "@"). */
+export const PROGRAM_KEY = "@program";
+/** Every declared command's digest, by name, and the program's under `@program` — what an approval records. */
 export function commandDigests(block) {
     const out = {};
-    for (const [n, c] of Object.entries(block.commands))
+    for (const [n, c] of Object.entries(block.commands ?? {}))
         out[n] = commandDigest(c);
+    if (block.program?.digest)
+        out[PROGRAM_KEY] = block.program.digest;
     return out;
 }
+/** The command names an approval covers (without the program's entry). */
+export function approvedCommandNames(approved) {
+    return Object.keys(approved).filter((k) => k !== PROGRAM_KEY);
+}
+/**
+ * The digest of a program: its spec (without the computed fields) and every
+ * file, sorted by path. Two builds of the same files give the same digest.
+ */
+export function programDigest(spec, files) {
+    const h = createHash("sha256");
+    h.update("esoul-program/1\n");
+    h.update(stable({ main: spec.main, resident: !!spec.resident, setup: spec.setup ?? [], selfTest: spec.selfTest ?? null }));
+    for (const f of [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
+        h.update(`\n${f.path}\n`);
+        h.update(createHash("sha256").update(f.content).digest("hex"));
+    }
+    return h.digest("hex");
+}
 /**
  * What an app update asks of the owner. Removing a command, or leaving one
  * untouched, needs nothing; ADDING a command or CHANGING one is new authority
@@ -32,11 +54,18 @@ export function commandDigests(block) {
 export function newAuthority(approved, current) {
     const added = [];
     const changed = [];
-    for (const [n, c] of Object.entries(current.commands)) {
+    for (const [n, c] of Object.entries(current.commands ?? {})) {
         if (!(n in approved))
             added.push(n);
         else if (approved[n] !== commandDigest(c))
             changed.push(n);
     }
+    // A program is new authority the first time and whenever its files change.
+    if (current.program?.digest) {
+        if (!(PROGRAM_KEY in approved))
+            added.push("program");
+        else if (approved[PROGRAM_KEY] !== current.program.digest)
+            changed.push("program");
+    }
     return { added, changed };
 }

package/dist/machine/index.d.ts

@@ -8,12 +8,14 @@
  * <ConnectComputer/> (esoul-sdk/react) and call devices(ctx) (esoul-sdk/server).
  */
 export { PROTOCOL, H, MAX_SKEW_MS, canonical, signRequest, verifyRequest, generateDeviceKey, isPublicKey, connectCode, sha256Hex, type DeviceKeyPair, type VerifyFailure } from "./protocol.js";
-export { deviceBlockProblems, renderCommand, resolveOutput, DeviceCommandError, COMMAND_NAME_RE, DEFAULT_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS, OUTPUT_LIMITS, type DeviceBlock, type CommandSpec, type ParamSpec, type ConfigKeySpec, type OutputSpec, type ResolvedOutput, type RenderedCommand } from "./commands.js";
-export { commandDigest, commandDigests, newAuthority } from "./digest.js";
+export { deviceBlockProblems, programProblems, renderCommand, resolveOutput, DeviceCommandError, COMMAND_NAME_RE, DEFAULT_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS, OUTPUT_LIMITS, PROGRAM_MAX_BYTES, PROGRAM_MAX_FILES, type DeviceBlock, type CommandSpec, type ParamSpec, type ConfigKeySpec, type OutputSpec, type ResolvedOutput, type RenderedCommand, type ProgramSpec, type SetupStepSpec } from "./commands.js";
+export { commandDigest, commandDigests, newAuthority, programDigest, approvedCommandNames, PROGRAM_KEY } from "./digest.js";
+export { defineProgram, type Program, type ProgramApi, type ProgramState, type ProgramStepState } from "./program-api.js";
+export { createProgramManager, programPaths, programEnv, type ProgramManager, type ProgramManagerOptions } from "./program-manager.js";
 export { makeClient, DoorError, isTransient, type DoorClient, type CallTiming, type FetchLike } from "./client.js";
 export { connect, startSupervisor, type ConnectOptions, type ConnectResult, type SupervisorOptions } from "./supervisor.js";
 export { deviceHome, machineFingerprint, type LocalLink, type LocalState } from "./state.js";
 export { execute, openWorkspace, tokenize, sandboxFor, confinedArgv, AGENT_NAME_RE, type ShellResult as MachineShellResult, type ShellCall, type Workspace, type Sandbox } from "./shell.js";
 export { parseGrant, grantFromChoice, effectiveGrant, describeGrant, type WorkspaceGrant, type WorkspaceChoice } from "./grant.js";
 export { resolveInScope, applyEdits, applyPatch, parseUnifiedDiff, FileError, Journal, type Scope, type Edit, type HunkResult, type JournalEntry } from "./files.js";
-export { registry, announce, builtInCapabilities, RUNTIME_CAPABILITIES, commandsCapability, workspaceCapability, OutputUploader, type Capability, type Job, type JobContext, type JobOutcome } from "./capabilities.js";
+export { registry, announce, builtInCapabilities, RUNTIME_CAPABILITIES, commandsCapability, workspaceCapability, programCapability, OutputUploader, type ProgramDelivery, type Capability, type Job, type JobContext, type JobOutcome } from "./capabilities.js";

package/dist/machine/index.js

@@ -8,12 +8,14 @@
  * <ConnectComputer/> (esoul-sdk/react) and call devices(ctx) (esoul-sdk/server).
  */
 export { PROTOCOL, H, MAX_SKEW_MS, canonical, signRequest, verifyRequest, generateDeviceKey, isPublicKey, connectCode, sha256Hex } from "./protocol.js";
-export { deviceBlockProblems, renderCommand, resolveOutput, DeviceCommandError, COMMAND_NAME_RE, DEFAULT_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS, OUTPUT_LIMITS } from "./commands.js";
-export { commandDigest, commandDigests, newAuthority } from "./digest.js";
+export { deviceBlockProblems, programProblems, renderCommand, resolveOutput, DeviceCommandError, COMMAND_NAME_RE, DEFAULT_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS, OUTPUT_LIMITS, PROGRAM_MAX_BYTES, PROGRAM_MAX_FILES } from "./commands.js";
+export { commandDigest, commandDigests, newAuthority, programDigest, approvedCommandNames, PROGRAM_KEY } from "./digest.js";
+export { defineProgram } from "./program-api.js";
+export { createProgramManager, programPaths, programEnv } from "./program-manager.js";
 export { makeClient, DoorError, isTransient } from "./client.js";
 export { connect, startSupervisor } from "./supervisor.js";
 export { deviceHome, machineFingerprint } from "./state.js";
 export { execute, openWorkspace, tokenize, sandboxFor, confinedArgv, AGENT_NAME_RE } from "./shell.js";
 export { parseGrant, grantFromChoice, effectiveGrant, describeGrant } from "./grant.js";
 export { resolveInScope, applyEdits, applyPatch, parseUnifiedDiff, FileError, Journal } from "./files.js";
-export { registry, announce, builtInCapabilities, RUNTIME_CAPABILITIES, commandsCapability, workspaceCapability, OutputUploader } from "./capabilities.js";
+export { registry, announce, builtInCapabilities, RUNTIME_CAPABILITIES, commandsCapability, workspaceCapability, programCapability, OutputUploader } from "./capabilities.js";

package/dist/machine/program-api.d.ts

@@ -0,0 +1,101 @@
+/**
+ * What an app's program sees on the computer (computer-apps.md §4.1). Types
+ * only: a program imports them with `import type`, which disappears when Node
+ * runs the file, so the program needs nothing installed beside it.
+ *
+ * ```ts
+ * // device/main.ts
+ * import type { Program } from "esoul-sdk/machine";
+ *
+ * export default {
+ *   async start(p) {
+ *     p.every(60_000, async () => p.op("sample", { cpu: await cpuPercent() }));
+ *     p.on("sample-now", async () => ({ cpu: await cpuPercent() }));
+ *     p.status("Sampling every minute", { ready: true });
+ *   },
+ * } satisfies Program;
+ * ```
+ */
+/** The program's handle on the computer and on its app. */
+export interface ProgramApi {
+    /** This computer, as the runtime sees it. */
+    readonly computer: {
+        readonly hostname: string;
+        readonly platform: string;
+        readonly arch: string;
+        readonly cpus: number;
+        readonly memoryGb: number;
+    };
+    /** The app instance this program serves, by its name in the workspace. */
+    readonly appName: string | null;
+    /** The program's own files (read-only). */
+    readonly programDir: string;
+    /** A folder the program may write, kept across updates and restarts. */
+    readonly dataDir: string;
+    /** The folder the owner granted this app on this computer, when there is one. */
+    readonly workspaceRoot: string | null;
+    /** Values set on this computer with `esoul-device config set`; never sent to ExternalSoul. */
+    readonly config: Readonly<Record<string, string>>;
+    /**
+     * Say what the program is doing, in words, on the app's Computers card
+     * ("Sampling every minute"). `ready: true` marks the program ready.
+     * Coalesced: at most one report a second leaves the computer.
+     */
+    status(text: string, extra?: {
+        progress?: number;
+        ready?: boolean;
+    }): void;
+    /**
+     * Call one of the app's own ops, as the owner who approved this computer
+     * (the op sees `viewer.kind === "agent"` and `viewer.device`). Ops must be
+     * idempotent: a lost answer is retried.
+     */
+    op<T = unknown>(name: string, args?: unknown, opts?: {
+        key?: string;
+    }): Promise<T>;
+    /** Handle a message the app sends (`devices(ctx).program(linkId).send(topic, data)`); the return value is the answer. */
+    on(topic: string, handler: (data: unknown) => unknown | Promise<unknown>): void;
+    /** Run `fn` every `ms` (at least 1000); a slow run is never overlapped. Returns a stop function. */
+    every(ms: number, fn: () => unknown | Promise<unknown>): () => void;
+    /** A line in the program's log on the computer (console.log goes there too). */
+    log(...args: unknown[]): void;
+}
+/** An app's program: `start` is called once per process; `stop` before the process ends, when it ends cleanly. */
+export interface Program {
+    start(p: ProgramApi): void | Promise<void>;
+    stop?(): void | Promise<void>;
+}
+/** Identity helper for a program written in plain JavaScript (TypeScript can use `satisfies Program`). */
+export declare function defineProgram(program: Program): Program;
+/** One setup step, as the Computers card shows it. */
+export interface ProgramStepState {
+    id: string;
+    describe: string;
+    state: "pending" | "running" | "done" | "cached" | "failed";
+    startedAt?: number;
+    endedAt?: number;
+    detail?: string;
+}
+/**
+ * Where an app's program stands on one computer — what the runtime reports
+ * and the app's Computers card renders. `phase` moves forward
+ * installing → setup → self-test → running (or ready, for a program started
+ * by its first message); `failed` and `refused` say why in `error`.
+ */
+export interface ProgramState {
+    digest: string;
+    phase: "installing" | "setup" | "self-test" | "ready" | "starting" | "running" | "stopped" | "failed" | "refused";
+    steps: ProgramStepState[];
+    /** The program's own words from `p.status`. */
+    status?: {
+        text: string;
+        progress?: number;
+        ready?: boolean;
+        at: number;
+    } | null;
+    error?: string | null;
+    /** The last lines of the log, when something failed. */
+    logTail?: string[];
+    restarts: number;
+    updatedAt: number;
+}

package/dist/machine/program-api.js

@@ -0,0 +1,22 @@
+/**
+ * What an app's program sees on the computer (computer-apps.md §4.1). Types
+ * only: a program imports them with `import type`, which disappears when Node
+ * runs the file, so the program needs nothing installed beside it.
+ *
+ * ```ts
+ * // device/main.ts
+ * import type { Program } from "esoul-sdk/machine";
+ *
+ * export default {
+ *   async start(p) {
+ *     p.every(60_000, async () => p.op("sample", { cpu: await cpuPercent() }));
+ *     p.on("sample-now", async () => ({ cpu: await cpuPercent() }));
+ *     p.status("Sampling every minute", { ready: true });
+ *   },
+ * } satisfies Program;
+ * ```
+ */
+/** Identity helper for a program written in plain JavaScript (TypeScript can use `satisfies Program`). */
+export function defineProgram(program) {
+    return program;
+}