@mostra/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @mostra/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Embed Mostra in a JavaScript host. `createMostra` starts your own Mostra instance for a home you
+choose, serves the ports you implement, and gives you the calls a host makes: publish, verify,
+wait, results, artifact state, live values, links and events.
+
+```ts
+import { createMostra } from "@mostra/sdk";
+
+const mostra = await createMostra({
+  home: "/var/lib/inbox/mostra",
+  client: { name: "inbox-app", version: "1.4.0" },
+  ports: {
+    submissions: {
+      async deliver(envelope) {
+        await db.saveOnce(envelope.submissionId, envelope.results);
+        return { accepted: true };
+      },
+    },
+  },
+});
+
+const receipt = await mostra.publish("/work/inbox");
+console.log(receipt.url);
+const outcome = await mostra.wait(receipt.artifactId, "submitted");
+const results = await mostra.results(receipt.artifactId);
+await mostra.close();
+```
+
+The first call downloads the runtime bundle this release pins (Node.js, Mostra's runtime and the
+packages artifacts use), checks every file against its SHA-256, fetches the browser `verify` uses
+and caches it all by digest. Later calls start at once, offline too. `MOSTRA_CACHE_DIR` moves the
+cache, `MOSTRA_BUNDLE_MIRROR` fetches from a mirror, and `MOSTRA_BUNDLE` uses a bundle you
+extracted yourself.
+
+Embedded use never sends telemetry. Node.js 22.19 or later; macOS and Linux on x64 and arm64.
+
+Part of [Mostra](https://github.com/mostra-dev/mostra), the agent artifact runtime. Apache-2.0.

package/dist/bundles.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "version": "0.2.0",
+  "release": "https://github.com/mostra-dev/mostra/releases/download/v0.2.0",
+  "assets": {
+    "darwin-arm64": {
+      "file": "mostra-0.2.0-darwin-arm64.tar.gz",
+      "sha256": "bf39299276a1b47aaf7f9e3b89cba64ccec6a9df354dcfd1448ea09967103fce",
+      "size": 198701927,
+      "unpackedSize": 781901193
+    },
+    "darwin-x64": {
+      "file": "mostra-0.2.0-darwin-x64.tar.gz",
+      "sha256": "201799fc7086076bed51b5e2e7eaa177416c417a12f0636b395a8207f6a81dde",
+      "size": 201773269,
+      "unpackedSize": 789999057
+    },
+    "linux-x64": {
+      "file": "mostra-0.2.0-linux-x64.tar.gz",
+      "sha256": "dd110f1b04fc6ff07da9f2c6d125b95f58775b5136b8d5f05da10d6865c85ea9",
+      "size": 205998068,
+      "unpackedSize": 792857549
+    },
+    "linux-arm64": {
+      "file": "mostra-0.2.0-linux-arm64.tar.gz",
+      "sha256": "2b24b16b84fa464467274f705c34efb527d3abb7e68cd0bfa7b8befb88e99186",
+      "size": 204102795,
+      "unpackedSize": 783165502
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,374 @@
+import { ArtifactRef, ArtifactSummary, BundleFiles, BundleInfo, BundlePins, BundlePlatform, BundleSetup, CapabilityLink, ControlsPolicy, DependencyPolicy, Diagnostic, DraftMirror, EventFilter, EventRecord, InstanceCapabilities, InstanceInfo, LivePushParams, LivePushResult, MethodDefinition, PortIdentityResolveParams, PortSecretsGetParams, PortTrustedControlsActivatedParams, PublishReceipt, Results, ResultsMarkdown, SourceRef, StateGetResult, StatePatchParams, StatePatchResult, SubmissionEnvelope, SubmissionPolicy, SubmissionsDeliverResult, SubmitChannel, VerifyVerdict, ViewUrlParams, ViewerSpec, WaitCondition, WaitResult } from "@mostra/protocol";
+//#region src/bundle/download.d.ts
+/** Progress of one download, in bytes. */
+interface DownloadProgress {
+  /** Bytes received so far. */
+  readonly received: number;
+  /** Bytes the pin says the archive has. */
+  readonly total: number;
+}
+/** A URL without credentials or a query, safe to print. */
+export declare function redactUrl(url: string): string;
+//#endregion
+//#region src/bundle/setup.d.ts
+/** The environment setup reads. */
+type Environment = Readonly<Record<string, string | undefined>>;
+/** An extracted bundle and what its `bundle.json` says. */
+interface Bundle {
+  /** Its root directory, holding `bundle.json`. */
+  readonly root: string;
+  /** Its parsed `bundle.json`. */
+  readonly info: BundleInfo;
+}
+/** One step of setup, for progress reports. */
+type SetupStep = "files" | "browser";
+/** Options of {@link setupBundle}. */
+interface SetupOptions {
+  /** The environment: `MOSTRA_OFFLINE`, proxies, Playwright's download mirror. */
+  readonly env?: Environment | undefined;
+  /** Gives up the browser's download. */
+  readonly signal?: AbortSignal | undefined;
+  /** Each step as it starts. */
+  readonly onStep?: ((step: SetupStep) => void) | undefined;
+  /** Skip checking the files, for a tree the caller checked a moment ago. */
+  readonly filesChecked?: boolean | undefined;
+}
+/** The directory Playwright's browsers live in, inside a bundle. */
+export declare function browsersDir(root: string): string;
+/** Whether `MOSTRA_OFFLINE` says Mostra is offline: any value but empty, `0`, `false` or `no`. */
+export declare function offline(env: Environment): boolean;
+/** Reads `bundle.json` at `root`. Throws `MOSTRA_ENV_BUNDLE_INVALID` when it isn't a bundle's. */
+export declare function readBundle(root: string): Promise<Bundle>;
+/** The setup marker, when it describes exactly this bundle. */
+export declare function readSetup(bundle: Bundle): Promise<BundleSetup | undefined>;
+/** What `checkTree` may find besides the listed files: the bundle's own records and browsers. */
+export declare function setupExtras(path: string): boolean;
+/** Checks the bundle's files; throws `MOSTRA_ENV_BUNDLE_INVALID` naming what differs. */
+export declare function checkFiles(bundle: Bundle): Promise<void>;
+/** The browser files that differ from the pin, relative to `browsers/`. */
+export declare function checkBrowser(bundle: Bundle): Promise<readonly string[]>;
+/**
+ * Makes the bundle at `root` ready: checks its files, fetches and checks the browser when it is
+ * missing or differs, and writes `.mostra-setup.json`. Idempotent: a ready bundle returns its
+ * marker after the checks. Throws `MOSTRA_ENV_BUNDLE_INVALID`, `MOSTRA_ENV_BUNDLE_UNAVAILABLE`
+ * (offline with no browser) or `MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`.
+ */
+export declare function setupBundle(root: string, options?: SetupOptions): Promise<BundleSetup>;
+//#endregion
+//#region src/bundle/cache.d.ts
+/** Where the cache is: `MOSTRA_CACHE_DIR`, else the platform's per-user cache directory. */
+export declare function cacheRoot(env: Environment, platform?: string): string;
+/** The directory a bundle with this archive digest lives in. */
+export declare function bundleDir(env: Environment, sha256: string): string;
+/** What an install reports while it works. */
+type InstallProgress = ({
+  readonly step: "download";
+} & DownloadProgress) | {
+  readonly step: "extract" | "lock";
+} | {
+  readonly step: SetupStep;
+};
+/** Options of {@link installPinned}. */
+interface InstallOptions {
+  /** The environment: the cache, mirror and offline variables, proxies. */
+  readonly env: Environment;
+  /** The platform whose archive to install. */
+  readonly platform: BundlePlatform;
+  /** Gives up the install; nothing partial is kept. */
+  readonly signal?: AbortSignal | undefined;
+  /** Each step, and the bytes received while downloading. */
+  readonly onProgress?: ((progress: InstallProgress) => void) | undefined;
+}
+/**
+ * The pinned bundle for this platform, ready to run: from the cache when it is there and ready,
+ * else installed. `MOSTRA_BUNDLE_MIRROR` replaces the release URL (files keep their names).
+ */
+export declare function installPinned(pins: BundlePins, options: InstallOptions): Promise<Bundle>;
+//#endregion
+//#region src/bundle/tree.d.ts
+/** The SHA-256 and size of one file, read as a stream. */
+export declare function hashFile(path: string): Promise<{
+  sha256: string;
+  size: number;
+}>;
+/** Whether a link's target is relative and resolves inside `root`. */
+export declare function linkStaysInside(root: string, path: string, target: string): boolean;
+/** Whether a manifest path is a plain relative path: no absolute start, no `.` or `..` segment. */
+export declare function safeRelative(path: string): boolean;
+/**
+ * The manifest of the tree under `root`: every regular file with its SHA-256, size and execute
+ * bit, every link with its target. Throws on anything else (a device, a socket, a link leaving
+ * the tree), which a bundle must never contain.
+ */
+export declare function describeTree(root: string, exclude?: (path: string) => boolean): Promise<BundleFiles>;
+/** What a check found: an empty list means the tree matches. Paths are relative to the root. */
+type TreeProblems = readonly string[];
+/**
+ * Checks the tree under `root` against `manifest`: each listed file present, regular, with its
+ * size, SHA-256 and execute bit; each link present with its target, staying inside; and nothing
+ * else besides what `allowExtra` accepts. Reports at most `limit` problems.
+ */
+export declare function checkTree(root: string, manifest: BundleFiles, options?: {
+  readonly allowExtra?: (path: string) => boolean;
+  readonly limit?: number;
+}): Promise<TreeProblems>;
+//#endregion
+//#region src/events.d.ts
+/** One page of events. */
+interface EventPage {
+  /** The events, in cursor order. */
+  readonly events: readonly EventRecord[];
+  /** Everything up to this cursor was examined: the cursor to resume after. */
+  readonly cursor: string;
+  /** Set when compaction removed events in this range (`MOSTRA_HOST_CURSOR_COMPACTED`). */
+  readonly compacted?: Diagnostic;
+}
+/** Options of a stream. */
+interface EventStreamOptions {
+  /** Which events: artifacts and type patterns. Default: every event. */
+  readonly filter?: EventFilter;
+  /** Start after this cursor. Default: a named stream's acknowledged cursor, else now. */
+  readonly after?: string;
+  /** A durable subscriber name: pages are acknowledged under it as they are handled. */
+  readonly name?: string;
+  /** Pages held before the subscription pauses. Default 16. */
+  readonly highWaterMark?: number;
+  /** Ends the stream. */
+  readonly signal?: AbortSignal;
+}
+//#endregion
+//#region src/runtime.d.ts
+/** A runtime to spawn: the Node.js to run it with and its entry points. */
+interface Runtime {
+  /** How it was found. */
+  readonly source: "bundle" | "override" | "development";
+  /** The Node.js executable: the bundle's own, or this process's for the others. */
+  readonly node: string;
+  /** `mostra-runtime`'s entry (`host`, `daemon`, `service`). */
+  readonly runtimeEntry: string;
+  /** The `mostra` CLI's entry, when this runtime has one. */
+  readonly cliEntry?: string;
+  /** The bundle, when the runtime is one. */
+  readonly bundle?: Bundle;
+}
+/** Options of {@link resolveRuntime}. */
+interface RuntimeOptions {
+  /** An extracted bundle to use, ahead of everything else. */
+  readonly bundle?: string | undefined;
+  /** The environment: `MOSTRA_BUNDLE`, `MOSTRA_RUNTIME_BIN`, the cache's variables. */
+  readonly env?: Environment | undefined;
+  /** Gives up a download or setup. */
+  readonly signal?: AbortSignal | undefined;
+  /** Progress of a download or setup, for a person waiting (the CLI prints it on stderr). */
+  readonly onProgress?: ((progress: InstallProgress) => void) | undefined;
+}
+/** The pins this build carries: `dist/bundles.json` (a test override applies only in a development checkout). */
+export declare function readPins(env: Environment): BundlePins | undefined;
+/** The bundle this package was installed into, if any: `<root>/lib/node_modules/@mostra/sdk`. */
+export declare function enclosingBundle(): string | undefined;
+/** A bundle's entry points as a runtime. */
+export declare function runtimeOf(bundle: Bundle): Runtime;
+/**
+ * Finds the runtime to spawn, downloading and setting up the pinned bundle when nothing nearer
+ * exists. Throws `MOSTRA_PLATFORM_UNSUPPORTED`, `MOSTRA_ENV_RUNTIME_MISSING` (a
+ * `MOSTRA_RUNTIME_BIN` that doesn't exist), `MOSTRA_ENV_BUNDLE_UNAVAILABLE`,
+ * `MOSTRA_ENV_BUNDLE_INVALID` or `MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`.
+ */
+export declare function resolveRuntime(options?: RuntimeOptions): Promise<Runtime>;
+//#endregion
+//#region src/mostra.d.ts
+/**
+ * The ports a host may serve (INTERFACES §7). Each is optional and has a standalone default;
+ * Mostra calls a port only on the instance this handle spawned, and every call is idempotent by
+ * its stable ID, so a port may see the same call again after a crash.
+ */
+interface Ports {
+  /**
+   * Names the person behind a link minted without a viewer, from the request's headers (D143):
+   * `{ ref, name? }` (one viewer per `ref`), or `null` for the home's local user. Answer within
+   * 5 s; a failure refuses the link rather than guess.
+   */
+  readonly identity?: {
+    resolve(request: PortIdentityResolveParams): ViewerSpec | null | Promise<ViewerSpec | null>;
+  };
+  /** Receives each submission once it is durable (D58, D105). Answer within 30 s. */
+  readonly submissions?: {
+    deliver(envelope: SubmissionEnvelope): SubmissionsDeliverResult | Promise<SubmissionsDeliverResult>;
+  };
+  /** Receives each viewer draft's latest revision, best effort, never retried (IN-06). */
+  readonly drafts?: {
+    mirror(draft: DraftMirror): void | Promise<void>;
+  };
+  /** Answers `secret()` first, before the home's store (D131); `null` falls back. */
+  readonly secrets?: {
+    get(request: PortSecretsGetParams): string | null | Promise<string | null>;
+  };
+  /** Decides each view's submit channels and trusted controls (D108). Answer within 5 s. */
+  readonly trustedControls?: {
+    policy(artifact: ArtifactSummary): ControlsPolicy | Promise<ControlsPolicy>;
+    activated?(event: PortTrustedControlsActivatedParams): void | Promise<void>;
+  };
+}
+/** Home settings a host chooses (INTERFACES §6 `HomeConfig`), kept in the home's `config.json`. */
+interface HomeSettings {
+  /** The submission policy for artifacts whose publish names none (D102). */
+  readonly submission?: SubmissionPolicy;
+  /** The channels that may submit (D40, D108); absent, both. */
+  readonly submitChannels?: readonly SubmitChannel[];
+  /** How packages enter an artifact's lockfile (D43, D95). */
+  readonly dependencies?: DependencyPolicy;
+}
+/** Options of {@link createMostra}. */
+interface MostraOptions {
+  /** The home this host owns (D45). Created 0700 when missing. */
+  readonly home: string;
+  /**
+   * Who the host is. The name owns the host's deliveries across restarts (D105), so keep it
+   * stable; it defaults to `mostra-sdk`.
+   */
+  readonly client?: {
+    readonly name: string;
+    readonly version?: string;
+  };
+  /** The ports this host serves. */
+  readonly ports?: Ports;
+  /**
+   * Whether submissions made while this host is away wait for it (D105): the registered ports
+   * are recorded as ports this host always provides. Default `true`; `false` leaves the home's
+   * record as it is.
+   */
+  readonly expectPorts?: boolean;
+  /** Home settings, kept in the home's `config.json` for every later client. */
+  readonly settings?: HomeSettings;
+  /** An extracted runtime bundle to use instead of the pinned one. */
+  readonly bundle?: string;
+  /** The gateway's bind address and URL host (D99); loopback by default. */
+  readonly bind?: string;
+  /** The host name URLs use, which a wildcard `bind` needs (D99). */
+  readonly urlHost?: string;
+  /** The instance's environment. Default: this process's. */
+  readonly env?: Environment;
+  /** Each line the instance logs (JSON, on its stderr). A callback that throws is ignored. */
+  readonly onLog?: (line: string) => void;
+  /** Progress of the first download or setup of the runtime bundle. A throw is ignored. */
+  readonly onProgress?: (progress: InstallProgress) => void;
+  /**
+   * An exception a port threw; the instance got `MOSTRA_HOST_INTERNAL_ERROR` and will retry. A
+   * callback that throws is ignored, and the instance is answered all the same.
+   */
+  readonly onPortError?: (error: unknown, method: string) => void;
+  /** Gives up finding the runtime and starting the instance. */
+  readonly signal?: AbortSignal;
+}
+/** How the instance ended. */
+interface InstanceExit {
+  /** Its exit code: 0 after a clean stop. */
+  readonly code: number | null;
+  /** The signal that ended it, if one did. */
+  readonly signal: NodeJS.Signals | null;
+}
+/** An artifact by ID (`art_…`), by source path, or as the protocol's reference. */
+type ArtifactInput = string | ArtifactRef;
+/** A host's handle on its instance. */
+interface Mostra {
+  /** The instance: release, home, platform, PID and mode. */
+  readonly instance: InstanceInfo;
+  /** What the instance serves. */
+  readonly capabilities: InstanceCapabilities;
+  /** The negotiated host protocol revision. */
+  readonly revision: string;
+  /** The session's warnings (an unsupported port, for example). */
+  readonly warnings: readonly Diagnostic[];
+  /** The runtime it runs on. */
+  readonly runtime: Runtime;
+  /** Resolves when the instance has exited, for whatever reason. */
+  readonly closed: Promise<InstanceExit>;
+  /** Calls any host protocol method by its definition from `@mostra/protocol`. */
+  call<P, R>(method: MethodDefinition<P, R>, params: P, options?: CallOptions): Promise<R>;
+  /** `artifact/publish`: verifies (D41) and publishes; durable before it resolves (H-07). */
+  publish(source: ArtifactInput, options?: {
+    readonly force?: boolean;
+    readonly policy?: SubmissionPolicy;
+    readonly requestId?: string;
+  }): Promise<PublishReceipt>;
+  /** `artifact/verify`: one verdict, never a publish (D138). */
+  verify(source: ArtifactInput, options?: {
+    readonly screenshots?: "on-failure" | "always" | "never";
+  }): Promise<VerifyVerdict>;
+  /**
+   * `wait` (IN-10, D103): until the condition holds or `timeoutMs` passes (default: the longest
+   * timer, about 24.8 days). `still_waiting` carries the cursor to wait from next; an aborted wait
+   * rejects with the signal's reason and loses nothing.
+   */
+  wait(artifact: ArtifactInput, until: WaitCondition, options?: {
+    readonly after?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+  }): Promise<WaitResult>;
+  /** `results/get`: a submission as JSON (the default) or Markdown (INTERFACES §8). */
+  results(artifact: ArtifactInput, options?: {
+    readonly submission?: string;
+    readonly format?: "json";
+  }): Promise<Results>;
+  /** `results/get` as Markdown, for an agent to read. */
+  results(artifact: ArtifactInput, options: {
+    readonly submission?: string;
+    readonly format: "md";
+  }): Promise<ResultsMarkdown>;
+  /** `state/get`: artifact-scoped fields (D63). */
+  getState(artifact: ArtifactInput, ids?: readonly string[]): Promise<StateGetResult>;
+  /** `state/patch`: writes artifact-scoped fields through compare-and-set (D63). */
+  patchState(artifact: ArtifactInput, patch: Omit<StatePatchParams, "artifact">): Promise<StatePatchResult>;
+  /** `live/push`: a live source's next value (D56). */
+  pushLive(artifact: ArtifactInput, push: Omit<LivePushParams, "artifact">): Promise<LivePushResult>;
+  /** `view/url`: a new capability link (D97). */
+  viewUrl(artifact: ArtifactInput, options?: Omit<ViewUrlParams, "artifact">): Promise<CapabilityLink>;
+  /**
+   * The events matching `options.filter`, page by page, in cursor order, with no gap across a
+   * pause (`events/subscribe`). With a `name`, each page is acknowledged when the next one is
+   * asked for, so a later stream of that name resumes after the last page handled.
+   */
+  events(options?: EventStreamOptions): AsyncIterable<EventPage>;
+  /** Ends the instance: its stdio closes, and it is stopped if it doesn't exit within 10 s. */
+  close(): Promise<InstanceExit>;
+}
+/** Options of one call. */
+interface CallOptions {
+  /** Gives up after this many milliseconds with `MOSTRA_HOST_TIMEOUT`. Default: none. */
+  readonly timeoutMs?: number;
+}
+/** The client name of an SDK host that names none. */
+export declare const SDK_CLIENT_NAME = "mostra-sdk";
+/** `art_…` is an artifact ID; anything else a source path, resolved against the working directory. */
+export declare function artifactRef(input: ArtifactInput): ArtifactRef & SourceRef;
+/**
+ * Spawns an instance for `home` and opens its session. Rejects with the instance's own diagnostic
+ * when it can't start (`MOSTRA_HOME_LOCKED`, `MOSTRA_PLATFORM_UNSUPPORTED` …), or with the
+ * runtime's (`MOSTRA_ENV_BUNDLE_*`) when no verified runtime can be found.
+ */
+export declare function createMostra(options: MostraOptions): Promise<Mostra>;
+//#endregion
+//#region src/platform.d.ts
+/** What the platform check reads: the running process by default. */
+interface PlatformFacts {
+  /** `process.platform`. */
+  readonly platform: string;
+  /** `process.arch`. */
+  readonly arch: string;
+  /** The glibc release on Linux, `undefined` on musl or elsewhere. */
+  readonly glibc?: string | undefined;
+}
+/** The facts of the running process, read once. */
+export declare function currentPlatform(): PlatformFacts;
+/**
+ * The bundle platform for these facts. Throws `MOSTRA_PLATFORM_UNSUPPORTED` for Windows, other
+ * architectures and Linux without glibc, whose libraries the bundle's Node.js and browser need.
+ */
+export declare function bundlePlatform(facts?: PlatformFacts): BundlePlatform;
+//#endregion
+//#region src/version.d.ts
+/** This SDK's release: the client version an SDK host reports by default. */
+export declare function sdkVersion(): string;
+//#endregion
+export type { ArtifactInput, Bundle, CallOptions, DownloadProgress, Environment, EventPage, EventStreamOptions, HomeSettings, InstallOptions, InstallProgress, InstanceExit, Mostra, MostraOptions, PlatformFacts, Ports, Runtime, RuntimeOptions, SetupOptions, SetupStep, TreeProblems };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/bundle/download.ts","../src/bundle/setup.ts","../src/bundle/cache.ts","../src/bundle/tree.ts","../src/events.ts","../src/runtime.ts","../src/mostra.ts","../src/platform.ts","../src/version.ts"],"mappings":"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"}