humanish 0.137.0 → 0.139.0

package/dist/substrates/modal/sdk.d.ts

@@ -0,0 +1,112 @@
+/** Which Modal workspace and environment a call reaches. */
+export interface ModalConnection {
+    tokenId: string;
+    tokenSecret: string;
+    /** Modal's own default environment is used when unset. */
+    environment?: string;
+}
+/** The variables a Modal connection is read from, as Modal's own CLI and SDK name them. */
+export declare const MODAL_TOKEN_ID_ENV = "MODAL_TOKEN_ID";
+export declare const MODAL_TOKEN_SECRET_ENV = "MODAL_TOKEN_SECRET";
+/**
+ * The connection an env names, or undefined when either token is missing. The SDK would otherwise
+ * fall back to process.env and ~/.modal.toml, which a library caller's env may not match, and a
+ * release could then reach another workspace than the create.
+ */
+export declare function modalConnection(env: Readonly<Record<string, string | undefined>>): ModalConnection | undefined;
+export interface ModalReadStream extends AsyncIterable<string | Uint8Array> {
+    readText(): Promise<string>;
+    readBytes(): Promise<Uint8Array>;
+}
+export interface ModalProcess {
+    stdout: ModalReadStream;
+    stderr: ModalReadStream;
+    stdin: {
+        writeText(text: string): Promise<void>;
+        writeBytes(bytes: Uint8Array): Promise<void>;
+        /** End of input after what was written. */
+        close(): Promise<void>;
+    };
+    /** End of input at offset 0: it ends input only before anything was written. */
+    closeStdin(): Promise<void>;
+    wait(): Promise<number>;
+}
+export interface ModalExecParams {
+    mode?: "text" | "binary";
+    stdout?: "pipe" | "ignore";
+    stderr?: "pipe" | "ignore";
+    workdir?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}
+export interface ModalSandbox {
+    readonly sandboxId: string;
+    exec(command: string[], params?: ModalExecParams): Promise<ModalProcess>;
+    terminate(): Promise<void>;
+    /** The exit code once the sandbox has finished, null while it runs. */
+    poll(): Promise<number | null>;
+    /** Resolves with the exit code once the sandbox has finished. */
+    wait(): Promise<number>;
+    getTags(): Promise<Record<string, string>>;
+    tunnels(timeoutMs?: number): Promise<Record<number, {
+        url: string;
+    }>>;
+}
+export interface ModalSandboxCreateParams {
+    cpu?: number;
+    memoryMiB?: number;
+    timeoutMs?: number;
+    workdir?: string;
+    env?: Record<string, string>;
+    encryptedPorts?: number[];
+    blockNetwork?: boolean;
+    outboundCidrAllowlist?: string[];
+    outboundDomainAllowlist?: string[];
+    runtime?: "gvisor" | "vm";
+    tags?: Record<string, string>;
+}
+export interface ModalImage {
+    dockerfileCommands(commands: string[]): ModalImage;
+}
+export interface ModalClient {
+    apps: {
+        fromName(name: string, params?: {
+            environment?: string;
+            createIfMissing?: boolean;
+        }): Promise<{
+            appId: string;
+        }>;
+    };
+    images: {
+        fromRegistry(tag: string): ModalImage;
+    };
+    sandboxes: {
+        create(app: {
+            appId: string;
+        }, image: ModalImage, params?: ModalSandboxCreateParams): Promise<ModalSandbox>;
+        fromId(sandboxId: string): Promise<ModalSandbox>;
+        list(params?: {
+            appId?: string;
+            tags?: Record<string, string>;
+            environment?: string;
+        }): AsyncIterable<ModalSandbox>;
+    };
+    close?(): void;
+}
+export interface ModalModule {
+    ModalClient: new (params: ModalConnection) => ModalClient;
+}
+export declare function loadModalModule(): Promise<ModalModule>;
+/**
+ * `error` with the connection's tokens replaced in its message and stack. The SDK can quote a
+ * token, for instance when gRPC refuses one with a stray zero-width character as metadata, and a
+ * provider error reaches run warnings and reclaim receipts.
+ */
+export declare function withoutTokens(error: unknown, connection: ModalConnection): unknown;
+/**
+ * Whether `error` is Modal's answer that no sandbox has this id: a gRPC NOT_FOUND (code 5), which
+ * the SDK raises from the first call on a handle `fromId` returned for an unknown id.
+ */
+export declare function isModalNotFoundError(error: unknown): boolean;
+/** Modal ends a sandbox after 24 hours on every plan. */
+export declare const MODAL_MAX_SANDBOX_MS: number;

package/dist/substrates/modal/sdk.js

@@ -0,0 +1,61 @@
+// The optional `modal` peer: a lazy loader and the structural subset of its JavaScript SDK that
+// humanish calls. Like @e2b/desktop it stays out of the published tarball, and these interfaces
+// keep its types out of humanish's own declarations.
+import { desktopPeerAdvice, humanishInstall } from "../e2b/peer-install.js";
+/** The variables a Modal connection is read from, as Modal's own CLI and SDK name them. */
+export const MODAL_TOKEN_ID_ENV = "MODAL_TOKEN_ID";
+export const MODAL_TOKEN_SECRET_ENV = "MODAL_TOKEN_SECRET";
+const MODAL_ENVIRONMENT_ENV = "MODAL_ENVIRONMENT";
+/**
+ * The connection an env names, or undefined when either token is missing. The SDK would otherwise
+ * fall back to process.env and ~/.modal.toml, which a library caller's env may not match, and a
+ * release could then reach another workspace than the create.
+ */
+export function modalConnection(env) {
+    const tokenId = env[MODAL_TOKEN_ID_ENV]?.trim();
+    const tokenSecret = env[MODAL_TOKEN_SECRET_ENV]?.trim();
+    if (!tokenId || !tokenSecret)
+        return undefined;
+    const environment = env[MODAL_ENVIRONMENT_ENV]?.trim();
+    return { tokenId, tokenSecret, ...(environment ? { environment } : {}) };
+}
+export async function loadModalModule() {
+    try {
+        return (await import("modal"));
+    }
+    catch (error) {
+        const value = error;
+        if (value.code === "ERR_MODULE_NOT_FOUND" && value.message?.includes("'modal'") === true) {
+            const { where, advice } = desktopPeerAdvice(humanishInstall(), "modal");
+            throw new Error(`Running on Modal requires the optional peer modal${where}. ${advice}`);
+        }
+        throw error;
+    }
+}
+/**
+ * `error` with the connection's tokens replaced in its message and stack. The SDK can quote a
+ * token, for instance when gRPC refuses one with a stray zero-width character as metadata, and a
+ * provider error reaches run warnings and reclaim receipts.
+ */
+export function withoutTokens(error, connection) {
+    if (!(error instanceof Error))
+        return error;
+    const tokens = [connection.tokenId, connection.tokenSecret];
+    const hide = (text) => tokens.reduce((hidden, token) => hidden.replaceAll(token, "[REDACTED_MODAL_TOKEN]"), text);
+    error.message = hide(error.message);
+    if (error.stack !== undefined)
+        error.stack = hide(error.stack);
+    return error;
+}
+/**
+ * Whether `error` is Modal's answer that no sandbox has this id: a gRPC NOT_FOUND (code 5), which
+ * the SDK raises from the first call on a handle `fromId` returned for an unknown id.
+ */
+export function isModalNotFoundError(error) {
+    if (error === null || typeof error !== "object")
+        return false;
+    const value = error;
+    return value.name === "NotFoundError" || value.code === 5;
+}
+/** Modal ends a sandbox after 24 hours on every plan. */
+export const MODAL_MAX_SANDBOX_MS = 24 * 60 * 60_000;

package/docs/architecture/terminal-product-route.md

@@ -28,7 +28,7 @@ fail-closed cross-validation, and forward-declared warnings.
 | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `subject.source`                  | `terminal-product`                                                                                                                                    |
 | `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                              |
-| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                  |
+| `execution.target`                | `e2b-terminal` (or absent → implied), or `modal-terminal` for a Modal sandbox                                                                         |
 | `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                         |
 | `execution.runtimeAuth`           | `openai-egress` (default) or opt-in `openai-env`; names-only durable evidence                                                                         |
 | `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                               |

package/docs/contracts/run-bundle.md

@@ -703,8 +703,11 @@ Dry runs omit `cost`. A live run that spends nothing records an explicit zero: n
 `breakdown` lines, `estimatedTotalUsd: 0`, `ratesAsOf: null` and `fullyEstimated: true`.
 A local scripted run (no model request, no hosted desktop) is such a run; a scripted run on
 a provisioned clone records the clone's desktop as a `laneId: subject` line. A live bundle
-without `cost` has an unmeasured spend. A live terminal run's `cost` prices the E2B terminal
-sandbox as a `desktop-minutes` line from its acquired-to-cleanup span and `e2b.getInfo` size.
+without `cost` has an unmeasured spend. A live terminal run's `cost` prices its shell sandbox
+as a `desktop-minutes` line from its acquired-to-cleanup span and size: E2B's report
+(`resourceSource: e2b.getInfo`), or the size humanish asked Modal for (`modal.create`), priced at
+Modal's sandbox rate. A computer-use run on `execution.target: modal-desktop` records each
+desktop's `providerResources[].provider` as `modal-desktop` and prices it the same way.
 Its Codex `model-tokens` line prices the agent's tokens from the model passed as `--model`
 (`actor.model`, else `gpt-5.6-sol`). Codex reports usage per turn, summed over the turn's
 requests, so the line prices every token at the base tier and carries

package/docs/contracts/schemas.md

@@ -336,10 +336,10 @@ The rest of this section names keys by their v3 spelling:
 - `subject.appUrl`: a loopback http(s) URL a computer-use actor drives, or (on the
   external-public shared-world route) the non-loopback public deployment used as the
   shared plane (with `publicTarget` + `allowPublicTargets`);
-- `execution`: where it runs (`local`, `e2b-desktop`, or `e2b-terminal`), plus
-  desktop device/resolution and timeouts. app-url subjects pair `e2b-desktop`
-  or `local` with a computer-use actor, or `local` (or absent) with a
-  scripted-browser actor; terminal-product subjects pair `e2b-terminal` (or absent → implied)
+- `execution`: where it runs (`local`, `e2b-desktop`, `e2b-terminal`, `modal-desktop` or
+  `modal-terminal`), plus desktop device/resolution and timeouts. app-url subjects pair
+  `e2b-desktop`, `modal-desktop` or `local` with a computer-use actor, or `local` (or absent) with a
+  scripted-browser actor; terminal-product subjects pair `e2b-terminal` or `modal-terminal` (or absent → `e2b-terminal`)
   with a registered terminal actor. clone and local-tree subjects require an
   explicit `e2b-desktop`: any other target, or none, fails to parse, and the
   computer-use and scripted-browser routes refuse it when a library caller skips
@@ -1297,7 +1297,7 @@ items: []
 Reserved: `humanish.substrate.v1` is named here for layering intent but has
 never shipped; no code emits or validates it. Substrate truth today lives
 inside run bundles (per-stream transport and status) and study execution config
-(`execution.target: local | e2b-desktop | e2b-terminal`). Do not emit this schema.
+(`execution.target: local | e2b-desktop | e2b-terminal | modal-desktop | modal-terminal`). Do not emit this schema.
 
 ## Serve Result And Reserved Control-Plane Namespace
 
@@ -1578,12 +1578,13 @@ Three new `.v1` schema tags ship, all additive and optional so
   lines remain readable.
   A desktop line's optional `desktop` object records `minutes`,
   `durationBasis: host-acquired-to-cleanup`, observed `resources` (`cpuCount`,
-  `memoryMiB`), `resourceSource: e2b.getInfo`, and `usdPerSecond` when priceable.
+  `memoryMiB`), `resourceSource` (`e2b.getInfo`, or `modal.create` for the size humanish asked
+  Modal for), and `usdPerSecond` when priceable.
   Failed metadata reads record `resourceUnavailableReason`; no resource guess is used.
   Resource metadata and missing/unsupported rates produce a null line. A kept or
   unconfirmed allocation adds `desktop_lifetime_incomplete` as a second null line.
   Live terminal-product runs emit the same summary: one `desktop-minutes` line for
-  the E2B shell sandbox (its acquired-to-cleanup span and `e2b.getInfo` size) and
+  the shell sandbox (its acquired-to-cleanup span and its `e2b.getInfo` or `modal.create` size) and
   one `model-tokens` line for the Codex participant, priced from the model the route passed
   to Codex (`gpt-5.6-sol` unless the study declares one) with `basis:
   aggregated_turns_base_rate`, or `null` with `no_token_usage`. Older terminal bundles record

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.137.0",
+  "version": "0.139.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -109,6 +109,7 @@
     "parse5": "^8.0.1",
     "playwright-core": "^1.63.0",
     "pngjs": "^7.0.0",
+    "smol-toml": "^1.9.0",
     "undici": "^8.11.2",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
@@ -120,6 +121,7 @@
     "axe-core": "4.14.0",
     "fast-check": "catalog:",
     "knip": "6.41.0",
+    "modal": "^0.11.1",
     "oxc-parser": "catalog:",
     "oxfmt": "0.73.0",
     "oxlint": "1.88.0",
@@ -130,11 +132,15 @@
     "vitest": "catalog:"
   },
   "peerDependencies": {
-    "@e2b/desktop": "^2.3.2"
+    "@e2b/desktop": "^2.3.2",
+    "modal": "^0.11.1"
   },
   "peerDependenciesMeta": {
     "@e2b/desktop": {
       "optional": true
+    },
+    "modal": {
+      "optional": true
     }
   },
   "engines": {