@aipoch/open-science 0.0.0-stage → 1.0.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 AIPOCH
+
+   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,285 @@
-# Temporary Holding Version
+# @aipoch/open-science
 
-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.
+[AIPOCH Open-Science](https://github.com/aipoch/open-science) is an open-source, local-first,
+model-agnostic AI research workbench. Use scientific Agents, Python and R Notebooks, and
+scientific data connectors to turn research questions into reports, tables and figures.
+
+This package provides the **standalone CLI, local Web UI and Node.js SDK**. npm installs the
+matching platform package with the backend and resources; the desktop app is not required.
+
+## Install
+
+Install [Node.js](https://nodejs.org/) **22.13.0 or later**, then run:
+
+```bash
+npm install --global @aipoch/open-science
+open-science --help
+```
+
+Supported platforms are macOS Apple Silicon/Intel, Linux ARM64/x64 with glibc, and Windows x64.
+Linux musl (including Alpine) and Windows ARM64 are not supported by the published native packages.
+Keep npm optional dependencies enabled: they contain the platform runtime. If startup reports a
+missing native package, reinstall with `npm install --global @aipoch/open-science --include=optional`.
+
+Linux also needs working credential storage and Notebook sandbox prerequisites; see the
+[Linux setup requirements](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md#linux-prerequisites).
+Python/R and an Agent runtime/model provider are configured separately during setup.
+For installations that include Node itself, see the
+[Homebrew and Release archive options](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md).
+
+## Get started
+
+Start the local service and request its browser URL:
+
+```bash
+open-science start --no-open
+open-science url
+```
+
+Open the printed URL, complete the setup checks, configure an Agent runtime and model provider,
+and create your first research project. Set up a Python or R Notebook runtime if your work needs
+code execution. The URL contains a local authentication token; keep it private.
+For setup from the terminal, follow the
+[CLI first-run guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md#first-run-setup-codex).
+
+After setup, submit a task from the terminal:
+
+```bash
+open-science doctor --json
+open-science project create "First research" --json
+open-science run --project "First research" --prompt "Draft a research plan for comparing two analysis methods." --wait --jsonl
+```
+
+Confirm `ready: true` in the doctor output before submitting work. The CLI accepts a Project ID
+or an exact, unambiguous name; SDK calls use IDs. Closing the browser does not stop the service:
+
+```bash
+open-science status --json
+open-science stop
+```
+
+Stopping the service affects all connected clients. For automated tasks, review the
+[permissions and output options](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md)
+and the safety guidance below.
+
+## Update or uninstall
+
+Stop services started by this installation before replacing it. Use the same `--config-root`
+when stopping and restarting a custom profile.
+
+```bash
+open-science stop
+npm install --global @aipoch/open-science@latest
+open-science start --no-open
+```
+
+To uninstall, stop the service and run `npm uninstall --global @aipoch/open-science`.
+Uninstalling the npm package retains research data and credentials. Review
+[release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md)
+before changing versions; replacing program files does not reverse data migrations.
+
+## Documentation
+
+- [CLI guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md) - installation, daemon lifecycle, task automation, artifacts, and exit codes
+- [Product overview](https://github.com/aipoch/open-science#readme) - research workflows, screenshots and desktop downloads
+- [Report an issue](https://github.com/aipoch/open-science/issues) - bugs and feature requests
+- [Release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md) - stable interfaces, versioning, and data upgrades
+- [Intended use](https://github.com/aipoch/open-science/blob/main/docs/usage-scope.md) and [known limitations](https://github.com/aipoch/open-science/blob/main/docs/known-limitations.md) - workflow precautions, data disclosure, and execution boundaries
+
+## Safety and integration
+
+- **Scope:** Authenticated control of a local Open-Science service; the client does not provide an
+  independent execution sandbox or isolate the service's Agents and tools.
+- **Controls:** Requests use the service's permission profiles, existing grants, and host-owned
+  runtime controls. Disabling interactive permission prompts denies requests needing a human; it
+  does not erase previously granted authority.
+- **Remaining risks:** A successful automated run can modify allowed files, contact configured
+  services, or start remote jobs. A timeout or aborted wait stops observation, not the underlying run.
+  Research outputs still need scientific review.
+- **Safe integration:** Protect local service credentials, review the effective profile/grants and
+  recipients, and use isolated test data before unattended operation. Cancel explicitly and confirm
+  the resulting task/job state. Inspect downloaded or exported artifacts before sharing.
+
+## Browser-held package import
+
+Use `@aipoch/open-science/browser-import` to send a downloaded `.science` Blob to the desktop app.
+See the [browser integration guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/BROWSER_IMPORT.md) for the click flow, API, security contract,
+limits, and browser requirements. The desktop never downloads the online package URL.
+
+## SDK quick start
+
+Install the package in your Node.js project (a global CLI install does not make it importable):
+
+```bash
+npm install @aipoch/open-science
+```
+
+Start and configure the local service as above. Save the example in an `.mjs` file and run it
+with Node.js. It creates a Project and uses its ID for subsequent requests:
+
+```js
+import { connectToOpenScience } from '@aipoch/open-science'
+
+const client = await connectToOpenScience()
+const project = await client.createProject({ name: 'Evidence review' })
+const run = await client.startRun({
+  project: project.id,
+  prompt: 'Summarize the evidence.',
+  permissionProfile: 'auto',
+  permissionPrompts: 'none' // Deny requests that would require a human; keep existing permission rules.
+})
+const result = await client.waitForRun(run.id)
+console.log(result.output)
+```
+
+Session, Project-default, and global Agent-routing configuration use the same authenticated local
+API:
+
+```js
+const configuration = await client.getSessionConfiguration(run.sessionId)
+await client.updateSessionConfiguration(run.sessionId, {
+  expectedRevision: configuration.revision,
+  memoryEnabled: false
+})
+
+const defaults = await client.getProjectSessionDefaults(project.id)
+await client.updateProjectSessionDefaults(project.id, {
+  expectedUpdatedAt: defaults.updatedAt,
+  patch: { permissionProfile: 'auto' }
+})
+
+await client.updateAgentRouting({
+  framework: 'codex',
+  reviewer: { mode: 'inherit' },
+  subagent: { mode: 'inherit' }
+})
+
+const runtimes = await client.listRuntimes()
+```
+
+Session updates use `revision`; Project-default updates use `updatedAt`. Both reject stale writes.
+Project defaults are copied only when a Session is created, with precedence `startRun` request,
+Project defaults, application settings, then provider default. Agent-routing updates are atomic and
+never return provider credentials.
+
+Agent runtime listings expose only framework, readiness, version, and managed/external source. They
+do not expose executable paths.
+
+SDK requests have a 30-second default deadline that remains active while the response body is being
+consumed. Override the client default with `requestTimeoutMs`, or pass `{ signal, timeoutMs }` as the
+final options argument to an individual request method. `downloadArtifact` keeps the deadline active
+while its returned `Response` body is streaming. `waitForRun` applies its overall `timeoutMs` and
+caller signal to every in-flight polling request as well as the delay between polls. Each poll is
+bounded by the smaller of the client's `requestTimeoutMs` and the remaining total wait budget.
+A request timeout fails the wait immediately; it does not silently retry. Without a total
+`timeoutMs`, waiting has no overall deadline. `pollIntervalMs` defaults to 250 and must be a finite
+positive number.
+
+Aborting or timing out a wait stops only the local observation. The Run may continue on the host;
+call `getRun(run.id)` to check it, or explicitly call `cancelRun(run.id)` to stop it. With
+`returnOnAttention: true`, a returned Run may still have `status: 'running'` and need a Plan decision before it can finish. Ordinary permissions do not populate Run attention.
+
+```js
+const waitController = new AbortController()
+const result = await client.waitForRun(run.id, {
+  timeoutMs: 120_000, // Total wait budget; each poll still has the client request deadline.
+  pollIntervalMs: 500,
+  returnOnAttention: true,
+  signal: waitController.signal // Aborts observation; does not call cancelRun.
+})
+console.log(result.status, result.attention)
+```
+
+For retry-safe project creation and Run starts, pass the same `idempotencyKey` in the final options
+argument on every attempt. The daemon replays the first response for up to 24 hours while it remains
+running; reusing a key with a different request body fails with `idempotency_conflict`. If the
+bounded replay registry is full, a new unique key fails with `idempotency_unavailable` rather than
+evicting an existing guarantee. A lost response after submission does not prove that the Run was
+not started. Retry with the original key and identical request while that daemon is still running,
+or query the known Run ID. The replay registry is process-local: a daemon restart loses it, so
+reusing a key after restart is not a durable exactly-once guarantee.
+
+The `project` request field and the `listSessions(projectId)` argument both require a Project ID.
+Project display names are not accepted as routing identifiers.
+
+SDK and HTTP callers must supply an absolute `cwd`. Open-Science canonicalizes and validates it,
+persists it as the Session working directory, and returns the effective path on every Run. Supplying
+`cwd` with `sessionId` is allowed only when both paths resolve to the same directory. Omit `cwd` to
+use a managed workspace. External working directories remain caller-owned and are never removed by
+Open-Science.
+
+For live automation feedback, subscribe before starting the Run. `run.progress` reports ordered
+provider-neutral phases and emits a progress heartbeat every ten seconds until the first visible
+provider output. This progress heartbeat describes Run activity; it is separate from the filtered
+connection heartbeat that keeps an otherwise-idle WebSocket alive. The timer starts after Task has
+prepared the Session and registered its Run; Session creation or resume time before registration is
+outside this event stream:
+
+```js
+const abortController = new AbortController()
+const events = client.events({ signal: abortController.signal })
+await events.ready
+
+const progress = (async () => {
+  for await (const event of events) {
+    if (event.type === 'run.progress') {
+      console.log(event.data.phase, event.data.elapsedMs, event.data.heartbeat)
+    }
+  }
+})()
+
+const observedRun = await client.startRun({
+  project: project.id,
+  prompt: 'Summarize the evidence.',
+  permissionProfile: 'auto'
+})
+const observedResult = await client.waitForRun(observedRun.id)
+abortController.abort()
+await progress
+console.log(observedResult.output)
+```
+
+`events.ready` rejects if the socket fails, closes, or receives no liveness frame before opening.
+After opening, the iterator fails with `timeout` when no event or connection heartbeat arrives for
+30 seconds. Pass `idleTimeoutMs` to change that connection-liveness window; it does not limit model,
+Notebook, permission-approval, or other Run duration. Connection heartbeats are control frames and
+are not yielded to consumers. Malformed frames and a consumer backlog above 1024 events terminate
+the iterator with `event_stream_invalid_message` or `event_stream_overflow` instead of throwing
+outside the iterator or growing memory without a bound.
+
+Every Run event includes top-level `sequence`, `runId`, `sessionId`, and `projectId` fields in
+addition to its existing `type` and `data`. After an established socket closes unexpectedly, the SDK
+reconnects with its last sequence and the daemon replays the retained suffix. Replay is bounded and
+process-local. If the daemon restarted or the suffix was evicted, the iterator yields
+`stream.resync-required` with reason `stream-changed` or `cursor-expired`; read the Run or Session
+through the HTTP API to restore authoritative state.
+
+Plan First runs can opt into actionable waiting with returnOnAttention. When the returned Run has
+attention.kind equal to plan-approval, use getSessionPlan and respondSessionPlan. Calling waitForRun
+without returnOnAttention keeps the original terminal-only behavior.
+
+Automatic review and Specialist binding reuse existing Session JSON fields. Delegation adds
+delegationPolicy with values allow or deny; an omitted historical value restores as allow.
+
+To stop a still-running task instead of waiting for it, cancel it explicitly. Cancellation waits for
+provider work and application finalization to drain before returning the terminal Run:
+
+```js
+const cancelled = await client.cancelRun(run.id)
+console.log(cancelled.status) // cancelled
+```
+
+The client discovers the local daemon and reads its authentication token from the Open-Science config
+directory. HTTP calls send the token in request headers. `events()` authenticates its WebSocket using
+a `token` URL query parameter; treat WebSocket URLs and request logs as sensitive. Tokens are
+not included in normal command output.
+
+### Automation new-session defaults
+
+`project session-defaults show|update` manages defaults for new Sessions created through the
+Task CLI/API. Explicit run options override these defaults. Existing Sessions and desktop New
+conversation drafts are not changed.
+
+`--provider-default-model` keeps following the provider-owned default instead of pinning the
+first model in its catalog. An explicit `--model` stays fixed. If a saved selection becomes
+unavailable, choose a replacement explicitly or wait for it to become available again.

package/appimage-launcher.mjs

@@ -0,0 +1,90 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+import { createHash, randomUUID } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { cp, lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join } from 'node:path'
+import { homedir } from 'node:os'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+// An AppImage mount belongs to the foreground CLI invocation. A detached server must never read
+// native libraries/resources from that disappearing mount. Retain only this immutable, hashed
+// installation payload in the user's cache; business settings and secrets stay in their usual roots.
+export async function stageAppImageCli(image, backend, nodeRuntime, cache) {
+  if (!isAbsolute(image)) throw new Error('Expected an absolute AppImage path.')
+  const digest = createHash('sha256')
+  for await (const bytes of createReadStream(image)) digest.update(bytes)
+  const identity = digest.digest('hex')
+  await mkdir(cache, { recursive: true, mode: 0o700 })
+  const info = await lstat(cache)
+  if (
+    !info.isDirectory() ||
+    (process.platform !== 'win32' && (info.mode & 0o022) !== 0) ||
+    (process.getuid && info.uid !== process.getuid())
+  )
+    throw new Error('AppImage CLI cache must be a directory owned by the current user.')
+  const destination = join(cache, identity)
+  const marker = JSON.stringify({ image: identity })
+  const valid = async () => {
+    try {
+      const info = await lstat(destination)
+      return (
+        info.isDirectory() &&
+        (process.platform === 'win32' || (info.mode & 0o022) === 0) &&
+        (!process.getuid || info.uid === process.getuid()) &&
+        (await readFile(join(destination, 'complete.json'), 'utf8')) === marker
+      )
+    } catch (error) {
+      if (error.code === 'ENOENT') return false
+      throw error
+    }
+  }
+  if (await valid()) return destination
+  const temporary = join(cache, `.${identity}-${randomUUID()}`)
+  await mkdir(temporary, { mode: 0o700 })
+  try {
+    await cp(backend, join(temporary, 'backend'), { recursive: true, dereference: true })
+    await cp(nodeRuntime, join(temporary, 'node-runtime'), { recursive: true, dereference: true })
+    await writeFile(join(temporary, 'complete.json'), marker, { flag: 'wx', mode: 0o600 })
+    try {
+      await rename(temporary, destination)
+    } catch (error) {
+      const exists =
+        ['EEXIST', 'ENOTEMPTY'].includes(error.code) ||
+        (process.platform === 'win32' && error.code === 'EPERM')
+      if (!exists || !(await valid())) throw error
+    }
+    return destination
+  } finally {
+    await rm(temporary, { recursive: true, force: true })
+  }
+}
+
+async function main() {
+  const backend = dirname(fileURLToPath(import.meta.url))
+  const payload = await stageAppImageCli(
+    process.argv[2],
+    backend,
+    join(backend, '../node-runtime'),
+    join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'open-science', 'appimage-cli')
+  )
+  const env = { ...process.env }
+  delete env.ELECTRON_RUN_AS_NODE
+  const child = spawn(
+    join(payload, 'node-runtime/node'),
+    [join(payload, 'backend/cli.mjs'), ...process.argv.slice(3)],
+    { env, stdio: 'inherit' }
+  )
+  child.once('error', (error) => {
+    console.error(error.message)
+    process.exitCode = 1
+  })
+  child.once('exit', (code) => {
+    process.exitCode = code ?? 1
+  })
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1])
+  await main().catch((error) => {
+    console.error(error.message)
+    process.exitCode = 1
+  })

package/browser-import.d.ts

@@ -0,0 +1,66 @@
+export type BrowserImportReadinessMode = 'attempts' | 'wait-for-launch'
+export type BrowserImportPhase = 'waiting-for-receiver' | 'transferring'
+export type BrowserImportProgress = { sentBytes: number; totalBytes: number }
+export type BrowserImportFailureCode =
+  | 'unsupported-browser'
+  | 'timeout'
+  | 'readiness-exhausted'
+  | 'incompatible'
+  | 'launch-failed'
+  | 'transfer-failed'
+  | 'cancelled'
+export class BrowserImportError extends Error {
+  readonly code: BrowserImportFailureCode
+  constructor(code: BrowserImportFailureCode, message: string)
+}
+/** Synchronous user-click launch request. Returning does not prove installation or delivery.
+ * Throws BrowserImportError: unsupported-browser (no navigation API), launch-failed (navigation threw). */
+export function launchOpenScience(): void
+export type BrowserImportDiscoveryOptions = {
+  signal?: AbortSignal
+  /** Must match the page origin. Inferred from location in browsers. */
+  origin?: string
+  /** A single configured endpoint, never a range to scan. Defaults to 49151. */
+  port?: number
+  timeoutMs?: number
+}
+export type BrowserImportUnavailable = {
+  /** unavailable also covers opaque CORS/local-network denials; it does not mean not installed. */
+  status: 'unavailable' | 'unsupported-browser' | 'incompatible' | 'timeout' | 'aborted'
+}
+/** Probes a running, reachable service, not installation/protocol registration. May prompt for
+ * local-network permission. Advisory only; the secret-bound handshake authenticates the receiver. */
+export function checkBrowserImportAvailability(
+  options?: BrowserImportDiscoveryOptions
+): Promise<{ status: 'available' } | BrowserImportUnavailable>
+export type BrowserImportTransfer = {
+  /** Contains a secret; never log or persist it. Browser policy may require a fresh user click. */
+  readonly url: string
+  /** Acknowledges receipt only, independently of destination selection and final import consent.
+   * Authenticated desktop cancellation throws code 'cancelled', terminal for this transfer.
+   * Keep the Blob and explicitly prepare a new transfer; never automatically retry cancellation. */
+  send(options?: {
+    signal?: AbortSignal
+    /** Waiting starts before readiness; transferring starts after identity verification, before bytes.
+     * No transferring event for an already-received package; cached receipts emit no events. */
+    onPhase?: (phase: BrowserImportPhase) => void
+    /** Acknowledged bytes only; first callback follows the first successful chunk acknowledgment. */
+    onProgress?: (progress: BrowserImportProgress) => void
+    /** Default attempts preserves the 1–5 attempt limit. wait-for-launch retries until the
+     * overall deadline or cancellation; it observes only this transfer's authenticated handshake. */
+    readinessMode?: BrowserImportReadinessMode
+    /** Readiness only; defaults to 120,000 ms. Capped at 120,000 ms in wait-for-launch,
+     * 300,000 ms in attempts mode. Timeout permits another send() on the same live transfer. */
+    readyTimeoutMs?: number
+    /** 1–5 attempts with 1,000 ms gaps; defaults to 5. Ignored in wait-for-launch mode. */
+    readinessAttempts?: number
+    /** Includes response body reads; defaults to 2,000 ms. Accepts up to 30,000 ms,
+     * clamped to 2,000 ms in wait-for-launch mode. Failed attempts have 1,000 ms gaps. */
+    attemptTimeoutMs?: number
+  }): Promise<{ received: true }>
+}
+/** Takes a complete browser-held Blob/File. Never fetches a remote package URL. */
+export function prepareBrowserImport(
+  file: Blob,
+  options?: { filename?: string; origin?: string; port?: number }
+): BrowserImportTransfer