@skaile/workspaces 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,278 @@
 # Changelog
 
+## 1.5.0
+
+### Minor Changes
+
+- [#340](https://github.com/skaile-ai/workspaces/pull/340) [`cde9457`](https://github.com/skaile-ai/workspaces/commit/cde9457c22d7e58111156effec1d4f5a8b9c50ec) Thanks [@henkbla](https://github.com/henkbla)! - `app-sdk`: connection-param handshake, reconnect, and registration replay.
+
+  The embedded app needs three things to open its back-connection — the gateway
+  URL, its `appId`, and a session identity token. The token is a credential, and
+  the preview surface that serves the app is unauthenticated, so it must not ride
+  in the iframe `src`. `resolveAppConnectionParams()` obtains it over
+  `postMessage` instead: the app posts a `skaile_app_ready` ping to its embedder
+  and awaits a `skaile_app_params` reply, with both sides pinning the peer on
+  `event.origin` **and** `event.source`. The app learns the expected host origin
+  from a non-secret `skaileParentOrigin` query param — safe to leak precisely
+  because it is not a credential. `"*"` and `"null"` host origins are refused: an
+  unpinnable peer defeats the point of keeping the token out of the URL.
+
+  `createWebSocketAppTransport` now accepts a `SessionTokenProvider` for
+  `sessionToken` as well as a bare string. The gateway's token is **single-use**
+  (consumed at `app_hello`), so a reconnecting transport cannot replay the one it
+  opened with; a provider mints a fresh token per attempt. A bare string still
+  opens the socket synchronously.
+
+  `createSkaileApp` gains a `reconnect` policy (default
+  `{maxAttempts:5, baseMs:1000, maxMs:30000}`, or `false` to disable). It rebinds
+  after a dropped socket and **replays its capability registry**, since the
+  gateway deregisters an app's capabilities when its connection closes. It also
+  retries a _retryable_ `app_hello_nack` — the app boots independently of the
+  session's agent container and can win that race. A permanent refusal (bad token,
+  `appId` not permitted) is never retried, because retrying only burns tokens.
+  `AppHelloNackMessage` gains an optional `retryable` field to carry that
+  distinction, and the SDK surfaces it as `AppHandshakeRefusedError.retryable`.
+  New `onSessionChange(handler)` fires on every bind — including the initial
+  `connect()` — and with `null` whenever the connection drops.
+
+  Behaviour change for `1.4.0` consumers: reconnect is **on by default**, so a
+  dropped socket now re-dials instead of leaving the app inert. Pass
+  `reconnect: false` for the old single-shot behaviour. Purely additive otherwise
+  — new exports, a widened `sessionToken` type, and one new optional wire field.
+
+- [#344](https://github.com/skaile-ai/workspaces/pull/344) [`fdd6c6a`](https://github.com/skaile-ai/workspaces/commit/fdd6c6a2bf89b677274665edd31ba9c6f71e5408) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Wire `skaile library publish` / `register` / `yank` — first-party store publish
+
+  Publish a git-backed library you own (in-repo `skaile.manifest.yaml`) to the
+  store: `library publish <lib>` commits + pushes the library repo, registers +
+  syncs it as a store source (no sidecar — the in-repo manifest drives discovery),
+  and publishes its assets under the manifest's own `publisher` (no namespace
+  remap). `--asset <ref>` narrows to one asset; `--create-repo` provisions + links
+  a public `github.com/<you>/<lib>` via `gh` when the library has no remote;
+  `--dry-run` prints an offline plan. `register` skips the commit/push (already on
+  GitHub); `yank` unpublishes. Requires a public git remote + `store login`.
+
+  Extracts the shared store-interaction core (`publish-core.ts` `publishToStore`)
+  reused by both `library publish` and `source manifest publish`, so the two
+  front-ends can't drift on the register → sync → candidates → per-asset publish
+  sequence.
+
+- [#335](https://github.com/skaile-ai/workspaces/pull/335) [`84565e0`](https://github.com/skaile-ai/workspaces/commit/84565e09c4da6daab4f26d9402cefd42884588ce) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Sidecar authoring + consume bug fixes for third-party sources.
+
+  **Sidecar authoring (`skaile source manifest init` / `edit` + overlay read + add).** You can
+  now curate assets from a foreign GitHub repo you don't control by authoring a
+  `skaile.manifest.yaml` stored _outside_ that repo, then consume + `add` them under a clean
+  curated publisher.
+
+  - `skaile source manifest init <src> [--publisher <name>] [--dev] [--force]` — clone (if
+    needed), run discovery, and write a curated manifest to the local store catalog at
+    `~/.skaile/store/manifests/<slug>.yaml`. Publisher defaults to the source's GitHub org.
+    Every asset inherits the top-level publisher (no per-asset path-segment stamp).
+    Idempotent (won't overwrite without `--force`).
+  - `skaile source manifest edit <src>` — open the curated manifest in `$EDITOR` and
+    re-validate on save (warnings surfaced, never a hard fail).
+  - `skaile source add` / `source sync` apply the curated manifest as a **read overlay**:
+    the curated publisher + asset inventory win over raw glob discovery. `LocalCatalogSource`
+    gained a `sidecarManifestFile` option; discovery gained `loadMergedSourceConfigFromFile`
+    - a `sidecarManifestFile` discovery option; the library gained `writeCuratedManifest`.
+  - `skaile add` now resolves the curated publisher too: the provenance walker
+    (`buildProvenanceIndex`) reads the same curated store overlay (via a new
+    `SourceClone.overlayManifestPath`), so the ref `search --local` displays
+    (`skill:@lark/…`) is the ref `add` accepts and deploys.
+  - Store manifests are keyed by a collision-free `storeManifestSlug(url)`
+    (`<host>__<owner>__<repo>`), so two repos sharing a trailing name (`orgA/cli`,
+    `orgB/cli`) no longer collide on `cli.yaml`.
+
+  **Bug fix — publisher normalization (glob AND manifest paths).** Discovery stored
+  publishers _with_ a leading `@`, which the local ref formatter doubled into `@@scripts`
+  (glob) / made `@lark` assets un-addable (manifest/curated overlay). `DiscoveredAsset.publisher`
+  is now **bare** on every discovery path (glob + manifest, local-FS + virtual-tree), unifying
+  them; the single `@` scope sigil is re-added by the ref formatter, and refs carry exactly
+  one `@` across both modes. The internal `SourceConfig` layer (`publisher_default` /
+  `atPublisher`) is unchanged — the `@`-prefix is correct there.
+
+  **Bug fix — `search --local` reads the index (and unions the factory source).** It now
+  reads the index (`asset_definitions` via `listAssetDefs`) instead of re-scanning the repo
+  tree, so its result set and count match exactly what `source add`/`sync` wrote — no scanner
+  `kind:name` dedup collapsing same-named or multi-kind assets — and unions the bundled
+  first-party factory source (never indexed) so built-in skills still appear in a fresh
+  project.
+
+- [#339](https://github.com/skaile-ai/workspaces/pull/339) [`56776b2`](https://github.com/skaile-ai/workspaces/commit/56776b2c709d08d2aff0f46a19cd876db52db5b0) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Wire `skaile source manifest publish` and `yank` — the curator publish flow
+
+  `source manifest publish <src>` takes a locally-curated sidecar manifest (over a
+  foreign **public** GitHub repo), pushes it to a public "sidecar" repo you own,
+  then registers + syncs the source with the store and publishes each curated asset
+  under your namespace (default: your store username; `--as <ns>` to override, e.g.
+  a GitHub org you belong to). `--dry-run` prints an offline plan (no push, no store
+  calls). `yank` unpublishes the source's published assets; `propose` stays a stub.
+
+  Requires the store's self-service `sources.add` sidecar support (skaile-store#79)
+  and a deployed store backend. Mono-repo sidecars (`sidecar_path`) are a documented
+  follow-up.
+
+- [#338](https://github.com/skaile-ai/workspaces/pull/338) [`9e959ee`](https://github.com/skaile-ai/workspaces/commit/9e959eec7d3c935aaa3c6c0c001f366b2bdbd80c) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Sidecar authoring phase 3 — wire `skaile source manifest rebuild` / `verify`,
+  extend the init test-fixture filter, and fix key-aware legacy clone migration.
+
+  - **`source manifest rebuild <src>` (new verb).** Refreshes a curated manifest
+    after the upstream repo changed. **Merge is the default — curation is sacred:**
+    it updates the clone (`git pull --ff-only`, best-effort), re-runs discovery,
+    and matches existing↔discovered entries by repo-relative `root` path. Existing
+    entries whose root is still present are KEPT verbatim (all hand-edits
+    preserved: publisher, per-asset name/version/description); entries whose root
+    is gone upstream are DROPPED and reported (`removed (gone upstream): …`).
+    Freshly-discovered assets not already curated are NOT auto-added — they are
+    reported (`N new upstream asset(s) available (not added): … — add with
+\`skaile source manifest edit\``), so a curated foreign-repo sidecar never
+silently absorbs new upstream skills, and an asset the curator deliberately
+dropped stays dropped. Writes only when something changed (else `already up to
+    date`). `--overwrite`re-scans the full inventory with`init --force`
+    semantics, warning that curation is replaced.
+  - **`source manifest verify <src>` (new verb), read-only.** Checks each manifest
+    asset against the clone: `root`/`files` paths still exist upstream (missing →
+    error); a declared `sha256` on a **`files:` entry** recomputes to the same
+    deterministic composite hash (mismatch → error) — hashed exactly as discovery
+    does (repo-root anchored, files verbatim as repo-relative strings), so a
+    correctly-pinned hash verifies clean; a declared `sha256` on a `root:` entry is
+    **skipped with a warning** (discovery hashes only the per-kind filtered set, so
+    a whole-dir recompute would false-mismatch, and the writer never emits sha256
+    for `root:` entries); schema decodes cleanly (`decodeSkaileManifest`
+    diagnostics → warnings/errors); dependency refs parse (`parseAssetRef`;
+    malformed → warning). Prints a summary and exits 0 when there are no errors;
+    `--strict` forces a nonzero exit if there are any warnings. Writes nothing.
+  - **Extended init/rebuild test-fixture filter.** In addition to
+    `tests`/`test`/`__tests__`, the filter now also drops assets whose
+    repo-relative root contains a `testdata`, `fixtures`, or `__fixtures__` path
+    SEGMENT (exact segment), catching leaks like
+    `internal/qualitygate/skillscan/testdata/skills/lark-demo`. `init`/`rebuild`
+    path only; the general discovery walk (`source add`) is untouched.
+  - **Key-aware legacy clone migration.** `getGlobalCacheDir()` migration of a
+    legacy `~/.skaile/sources/<bare-name>` clone now re-derives the clone's true
+    cache key from its `origin` remote and lands it at
+    `<cacheRoot>/sources/<host>/<owner>/<repo>` (was: preserved the bare name, so a
+    URL-keyed lookup missed it and it lingered mis-placed). Non-clone leftovers
+    (the sidecar remainder) are untouched. New `mergeLegacyEntriesKeyed` primitive
+    in `@skaile/workspaces/core`.
+
+  `publish` / `propose` / `yank` remain stubs (they need the store publish
+  endpoint).
+
+- [#343](https://github.com/skaile-ai/workspaces/pull/343) [`a8c2036`](https://github.com/skaile-ai/workspaces/commit/a8c2036e64c069ee46ebab3ff48e37044856b326) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Fix `skaile store login` — Keycloak device flow + correct store URL
+
+  The CLI's store auth was broken against the deployed store: the default URL
+  (`store.skaile.ai`) is dead and the old `/api/auth/*` login endpoints return 404.
+  `store login` now runs the Keycloak Device Authorization Grant (RFC 8628) against
+  `SKAILE_KEYCLOAK_URL` (default `https://auth.skaile.ai`, realm `skaile-store`,
+  public client `skaile-store-cli`) — it prints a URL + code to approve in a
+  browser, caches the token at `~/.skaile/auth.json` (shared with `store/cli`), and
+  refreshes transparently. The default store API URL is now `https://api.skaile.store`;
+  `whoami` reads `/api/v1/me`; every `/api/v1/*` publisher call authorizes with a
+  fresh device-flow token. Overridable via `SKAILE_STORE_URL` / `SKAILE_KEYCLOAK_URL`
+  / `SKAILE_STORE_REALM` / `SKAILE_STORE_CLI_CLIENT`.
+
+  Note: live login requires a public `skaile-store-cli` client (device-grant
+  enabled) registered on the store's Keycloak realm.
+
+### Patch Changes
+
+- [#332](https://github.com/skaile-ai/workspaces/pull/332) [`bd6e8f7`](https://github.com/skaile-ai/workspaces/commit/bd6e8f710e42017dc07afa4ab00f4134a28a038e) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Four CLI UX papercuts from hands-on testing:
+
+  - `skaile run "<prompt>"` no longer crashes with a raw `spawn omp ENOENT` when the
+    configured driver's binary is missing. The single-shot chat path now catches the
+    failure and prints the bridge's actionable hint (the binary is not installed /
+    not on PATH) plus a suggestion to try `--driver claude-sdk`; unrelated errors
+    still surface their own message and a non-zero exit.
+  - `skaile source add` warns about a missing `sha256` by pointing at the real
+    `skaile source manifest rebuild` command instead of the non-existent
+    `skaile source build-manifest --write`.
+  - `skaile source remove` (without `--purge`) now tells the user how to reclaim the
+    leftover clone — pass `--purge` or run `skaile cache clean`.
+  - `skaile install <ref>` (pointer-only global install) adds a clarifying line that
+    it installed globally under `~/.skaile/libraries/installed/`, and that
+    `skaile add <ref>` is how to deploy the asset into the current project.
+
+- [#328](https://github.com/skaile-ai/workspaces/pull/328) [`e613124`](https://github.com/skaile-ai/workspaces/commit/e613124bc6d5f1a46f01504a1fc239a0a905379f) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Preset UX polish from hands-on testing: `preset validate` no longer emits a
+  spurious "required" warning for a required placeholder with no default (that is
+  exactly what `export --redact` produces — required-ness is enforced at apply, not
+  validate); `skaile init` next-steps now suggests `preset apply`; and the apply
+  env-var hint points users to `.env`/shell (not skaile.yaml) so a first-time user
+  applying a shared preset knows where the secret value goes.
+
+- [#330](https://github.com/skaile-ai/workspaces/pull/330) [`be69fb8`](https://github.com/skaile-ai/workspaces/commit/be69fb816125478d7f1d2d1cc3fea8162d3f0875) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Fix `skaile search` so its store leg reaches the live catalog. The store half now
+  goes through the shared catalog client (tRPC to `skaile.store`) instead of the dead
+  `store.skaile.ai` REST endpoint, surfaces `catalog.url: local` and failures
+  non-silently, and prints copyable `kind:@publisher/name#version` refs for both store
+  and local results.
+
+- [#337](https://github.com/skaile-ai/workspaces/pull/337) [`b0acd87`](https://github.com/skaile-ai/workspaces/commit/b0acd87f3128946fd48a120afabf5cfe262c42ef) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Collapse per-asset missing-sha256 advisories into one summary line.
+
+  Since `source manifest init` stopped writing per-asset `sha256` for `root:`
+  entries, `skaile source add` / `source sync` printed one
+  `Missing sha256 — computed <hash> …` advisory line per asset. For a curated
+  overlay with dozens of assets that was pure noise.
+
+  Discovery now tags each absent-sha256 warning with a machine-readable
+  `code: "missing_sha256"` (on `ReferenceWarning`) instead of relying on the
+  message text, and `LocalCatalogSource.sync()` counts those and emits exactly
+  one collapsed advisory:
+  `<n> asset(s): sha256 not pinned — auto-computed locally (pin only for store publish)`.
+  All other advisories (e.g. unknown-kind ghost-install) still print individually.
+  The fatal `ManifestHashMismatch` path for a DECLARED-but-wrong sha256 is
+  unchanged.
+
+- [#336](https://github.com/skaile-ai/workspaces/pull/336) [`1d2cf89`](https://github.com/skaile-ai/workspaces/commit/1d2cf8905cd67bd5b568b046d6aff49d01cdc16d) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Sidecar polish — five papercut fixes for the `skaile source manifest` sidecar
+  authoring flow, found consuming `github.com/larksuite/cli`.
+
+  - **`init` no longer writes per-asset `sha256`.** The init writer emitted the
+    discovery `sha256` (computed over the FILTERED per-kind file set) on each
+    `root:` entry; `source add` then re-walked the WHOLE root dir → a different
+    file set → a different composite hash → `ManifestHashMismatch`, failing every
+    asset. `init` now omits `sha256` for `root:`-mode entries (a missing hash is a
+    non-fatal advisory), so `source add` on init output indexes cleanly with zero
+    hash mismatches.
+  - **`init` skips test-fixture directories.** Assets whose repo-relative `root`
+    contains a `tests` / `test` / `__tests__` path segment are dropped from the
+    generated manifest (conservative, not repo-specific) so fixture "skills"
+    (`scripts/*/tests/*`, `tests/cli_e2e/*`) don't pollute the curated inventory.
+    `init`-path only; the general discovery walk (`source add`) is untouched.
+  - **`init` next-step hint prints a runnable command; `edit` accepts the store
+    slug.** The hint now echoes the exact `<src>` the user passed (the URL) instead
+    of a bare short name that mis-expanded to the skaile-ai org. `resolveSourceArg`
+    additionally accepts the collision-free store slug (`<host>__<owner>__<repo>`)
+    as an identifier, matched against existing `~/.skaile/store/manifests/<arg>.yaml`
+    before bare-name expansion. Full-URL resolution still works.
+  - **`edit` respects a full `$EDITOR` command.** `EDITOR="code --wait"` now spawns
+    `code` with args `["--wait", <file>]` (was treated as one binary and failed).
+    New `resolveEditorCommand` splits the editor value on whitespace and appends
+    the target last; unset falls back to `vi`.
+  - **`preset export` warns on machine-local sidecar overlays.** When a captured
+    source resolves through a curated store manifest on this machine, export now
+    warns that those assets may not resolve elsewhere until the sidecar is shared.
+
+- [#333](https://github.com/skaile-ai/workspaces/pull/333) [`d213d69`](https://github.com/skaile-ai/workspaces/commit/d213d696e308f5253c618df359e8aa0625be7c8a) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Four asset-consume UX papercuts from hands-on testing (foreign repo shipping a
+  `skaile.manifest.yaml`, added via `skaile source add`, deployed via `skaile add`):
+
+  - **P-A — publisher `@` normalization.** A manifest declaring `publisher: '@acme'`
+    is now stored as `acme` (the leading `@` is the scope sigil the ref formatter
+    adds automatically). Previously it indexed as `@@acme` and the asset was
+    un-addable. Both manifest read paths are covered: `decodeSkaileManifest` (index
+    side, emits a `warning` diagnostic) **and** `resolveSourcePublisher` / `scanRepo`
+    (the `skaile search --local` scan/display side, which previously rendered the
+    copyable ref as `@@acme`). Only a single leading `@` is stripped; bare names are
+    untouched.
+  - **P-B — missing `sha256` is an advisory, not an indexing failure.** A manifest
+    asset with no `sha256` (and an unknown asset kind) now flows through the
+    discovery `warnings` channel and surfaces as an `advisory` on
+    `LocalCatalogSource.sync()` — never on `errors`. `skaile source add` /
+    `source sync` no longer report a false "N asset(s) failed to index" or exit 1
+    in this case; the asset is indexed and deployable, and the advisory is printed
+    on its own info line.
+  - **P-C — dead command pointer removed.** The missing-`sha256` advisory no longer
+    points at the not-wired `skaile source manifest rebuild` stub; it now reads
+    "only needed for store publish; auto-computed locally".
+  - **P-E — search kind-miss message.** `skaile search <kind>` with no matches now
+    says `No "<kind>" assets found in this project's sources.` instead of the
+    misleading never-synced `Run \`skaile source sync\` first` hint.
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/app-sdk/index.js

@@ -30,6 +30,20 @@ var consoleLogger = {
 
 // app-sdk/src/app.ts
 var DEFAULT_HELLO_TIMEOUT_MS = 1e4;
+var DEFAULT_RECONNECT = {
+  maxAttempts: 5,
+  baseMs: 1e3,
+  maxMs: 3e4
+};
+var AppHandshakeRefusedError = class extends Error {
+  retryable;
+  constructor(reason, retryable) {
+    super(`app handshake refused: ${reason}`);
+    this.name = "AppHandshakeRefusedError";
+    this.retryable = retryable;
+  }
+};
+var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 function createSkaileApp(options) {
   const {
     appId,
@@ -38,11 +52,23 @@ function createSkaileApp(options) {
     helloTimeoutMs = DEFAULT_HELLO_TIMEOUT_MS,
     logger = noopLogger
   } = options;
+  const reconnectEnabled = options.reconnect !== false;
+  const policy = {
+    ...DEFAULT_RECONNECT,
+    ...options.reconnect === false ? {} : options.reconnect
+  };
   const registry = /* @__PURE__ */ new Map();
+  const sessionListeners = /* @__PURE__ */ new Set();
   let session = null;
+  let closed = false;
+  let connecting = false;
+  let subscribed = false;
+  let epoch = 0;
   let unsubscribeMessage = null;
   let unsubscribeDisconnect = null;
-  let abortHandshake = null;
+  let reconnectTimer;
+  let reconnectWake = null;
+  let pending = null;
   function toWire(cap) {
     return {
       name: cap.name,
@@ -61,6 +87,10 @@ function createSkaileApp(options) {
       render: cap.render
     };
   }
+  function setSession(next) {
+    session = next;
+    for (const h of sessionListeners) h(next);
+  }
   function registerCapability(cap) {
     registry.set(cap.name, cap);
     if (session) {
@@ -96,69 +126,146 @@ function createSkaileApp(options) {
       transport.send({ type: "capability_result", callId, result: { error: message } });
     }
   }
-  function connect() {
-    if (session) return Promise.resolve(session);
-    if (abortHandshake) return Promise.reject(new Error("app connect() is already in progress"));
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      let helloTimer;
-      const finishHandshake = () => {
-        if (helloTimer) clearTimeout(helloTimer);
-        abortHandshake = null;
-      };
-      const fail = (err) => {
-        if (settled) return;
-        settled = true;
-        finishHandshake();
-        reject(err);
-      };
-      abortHandshake = fail;
-      const onMessage = (message) => {
-        switch (message.type) {
-          case "app_hello_ack": {
+  function onMessage(message) {
+    switch (message.type) {
+      case "app_hello_ack": {
+        const bound = { sessionId: message.sessionId, userId: message.userId };
+        pending?.settle(null, bound);
+        return;
+      }
+      case "app_hello_nack":
+        pending?.settle(new AppHandshakeRefusedError(message.error, message.retryable === true));
+        return;
+      case "capability_invoked":
+        void handleInvocation(message.callId, message.name, message.input);
+        return;
+    }
+  }
+  function onDisconnect() {
+    if (pending) {
+      pending.settle(new Error("transport disconnected during handshake"));
+      return;
+    }
+    if (closed || !session) return;
+    logger.warn("app connection lost", { appId });
+    setSession(null);
+    if (!reconnectEnabled) return;
+    connecting = true;
+    const loopEpoch = epoch;
+    void reconnectLoop().finally(() => {
+      if (epoch === loopEpoch) connecting = false;
+    });
+  }
+  function ensureSubscribed() {
+    if (subscribed) return;
+    unsubscribeMessage = transport.onMessage(onMessage);
+    unsubscribeDisconnect = transport.onDisconnect(onDisconnect);
+    subscribed = true;
+  }
+  function performHandshake() {
+    ensureSubscribed();
+    return transport.connect().then(
+      () => new Promise((resolve, reject) => {
+        if (closed) {
+          reject(new Error("app closed during handshake"));
+          return;
+        }
+        let settled = false;
+        const timer = setTimeout(() => {
+          pending?.settle(new Error(`app handshake timed out after ${helloTimeoutMs}ms`));
+        }, helloTimeoutMs);
+        pending = {
+          settle: (err, bound) => {
             if (settled) return;
             settled = true;
-            finishHandshake();
-            session = { sessionId: message.sessionId, userId: message.userId };
-            logger.info("app connection established", { appId, sessionId: session.sessionId });
+            clearTimeout(timer);
+            pending = null;
+            if (err || !bound) {
+              reject(err ?? new Error("app handshake failed"));
+              return;
+            }
+            setSession(bound);
+            logger.info("app connection established", { appId, sessionId: bound.sessionId });
             const wire = Array.from(registry.values()).map(toWire);
             if (wire.length > 0) {
               transport.send({ type: "capability_register", capabilities: wire });
             }
-            resolve(session);
-            return;
+            resolve(bound);
           }
-          case "app_hello_nack":
-            fail(new Error(`app handshake refused: ${message.error}`));
-            return;
-          case "capability_invoked":
-            void handleInvocation(message.callId, message.name, message.input);
-            return;
+        };
+        transport.send({ type: "app_hello", appId, protocolVersion });
+      }),
+      (err) => Promise.reject(err instanceof Error ? err : new Error(String(err)))
+    );
+  }
+  const backoffMs = (attempt) => Math.min(policy.maxMs, policy.baseMs * 2 ** Math.max(0, attempt - 1));
+  async function reconnectLoop() {
+    const myEpoch = epoch;
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+      const wait = backoffMs(attempt);
+      logger.debug("scheduling app reconnect", { appId, attempt, waitMs: wait });
+      await new Promise((r) => {
+        reconnectWake = r;
+        reconnectTimer = setTimeout(r, wait);
+      });
+      reconnectWake = null;
+      if (closed || epoch !== myEpoch) {
+        logger.debug("app reconnect cancelled", { appId, attempt });
+        return;
+      }
+      try {
+        await performHandshake();
+        logger.info("app connection re-established", { appId });
+        return;
+      } catch (err) {
+        if (err instanceof AppHandshakeRefusedError && !err.retryable) {
+          logger.error("app reconnect refused permanently", { appId, error: err.message });
+          return;
         }
-      };
-      const onDisconnect = () => {
-        fail(new Error("transport disconnected during handshake"));
-      };
-      transport.connect().then(
-        () => {
-          if (settled) return;
-          unsubscribeMessage = transport.onMessage(onMessage);
-          unsubscribeDisconnect = transport.onDisconnect(onDisconnect);
-          helloTimer = setTimeout(() => {
-            fail(new Error(`app handshake timed out after ${helloTimeoutMs}ms`));
-          }, helloTimeoutMs);
-          transport.send({ type: "app_hello", appId, protocolVersion });
-        },
-        (err) => fail(err instanceof Error ? err : new Error(String(err)))
-      );
-    });
+        logger.warn("app reconnect attempt failed", {
+          appId,
+          attempt,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+    logger.error("app reconnect gave up", { appId, attempts: policy.maxAttempts });
+  }
+  async function connect() {
+    if (session) return session;
+    if (connecting) throw new Error("app connect() is already in progress");
+    connecting = true;
+    closed = false;
+    try {
+      for (let attempt = 1; ; attempt++) {
+        try {
+          return await performHandshake();
+        } catch (err) {
+          const transient = err instanceof AppHandshakeRefusedError && err.retryable;
+          if (!transient || !reconnectEnabled || attempt >= policy.maxAttempts || closed) {
+            throw err;
+          }
+          logger.debug("app handshake refused (retryable), retrying", { appId, attempt });
+          await delay(backoffMs(attempt));
+        }
+      }
+    } finally {
+      connecting = false;
+    }
   }
   async function close() {
-    abortHandshake?.(new Error("app closed during handshake"));
+    closed = true;
+    epoch++;
+    clearTimeout(reconnectTimer);
+    reconnectWake?.();
+    reconnectWake = null;
+    connecting = false;
+    pending?.settle(new Error("app closed during handshake"));
     unsubscribeMessage?.();
     unsubscribeDisconnect?.();
     unsubscribeMessage = null;
     unsubscribeDisconnect = null;
+    subscribed = false;
     session = null;
     await transport.disconnect();
   }
@@ -172,9 +279,84 @@ function createSkaileApp(options) {
       return session;
     },
     connect,
+    onSessionChange(handler) {
+      sessionListeners.add(handler);
+      return () => sessionListeners.delete(handler);
+    },
     close
   };
 }
+
+// app-sdk/src/connection-params.ts
+var PARENT_ORIGIN_QUERY_PARAM = "skaileParentOrigin";
+var DEFAULT_PARAMS_TIMEOUT_MS = 1e4;
+function readParentOriginFromQuery(search) {
+  const value = new URLSearchParams(search).get(PARENT_ORIGIN_QUERY_PARAM);
+  return value && value.length > 0 ? value : null;
+}
+function isParamsMessage(data, appId) {
+  if (!data || typeof data !== "object") return false;
+  const m = data;
+  return m.type === "skaile_app_params" && m.appId === appId && typeof m.url === "string" && m.url.trim().length > 0 && typeof m.token === "string" && m.token.trim().length > 0;
+}
+function resolveAppConnectionParams(options) {
+  const { appId, timeoutMs = DEFAULT_PARAMS_TIMEOUT_MS } = options;
+  const win = options.windowRef ?? globalThis.window ?? null;
+  if (!win) {
+    return Promise.reject(
+      new Error("resolveAppConnectionParams requires a window (pass `windowRef` off-browser)")
+    );
+  }
+  const parent = win.parent;
+  if (!parent || parent === win) {
+    return Promise.reject(
+      new Error("app is not embedded \u2014 no parent frame to request params from")
+    );
+  }
+  const parentOrigin = options.parentOrigin ?? readParentOriginFromQuery(win.location.search);
+  if (!parentOrigin) {
+    return Promise.reject(
+      new Error(
+        `cannot determine the host origin: pass \`parentOrigin\` or set the \`${PARENT_ORIGIN_QUERY_PARAM}\` query param`
+      )
+    );
+  }
+  if (parentOrigin === "*" || parentOrigin === "null") {
+    return Promise.reject(new Error(`refusing to use an unpinnable host origin: ${parentOrigin}`));
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      clearTimeout(timer);
+      win.removeEventListener("message", onMessage);
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(
+        new Error(`timed out after ${timeoutMs}ms waiting for connection params from the host`)
+      );
+    }, timeoutMs);
+    function onMessage(event) {
+      if (settled) return;
+      if (event.origin !== parentOrigin || event.source !== parent) return;
+      if (!isParamsMessage(event.data, appId)) return;
+      settled = true;
+      cleanup();
+      resolve({ url: event.data.url, appId, token: event.data.token });
+    }
+    win.addEventListener("message", onMessage);
+    const ready = { type: "skaile_app_ready", appId };
+    try {
+      parent.postMessage(ready, parentOrigin);
+    } catch (err) {
+      settled = true;
+      cleanup();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    }
+  });
+}
 function defineAppCapability(args) {
   const inputSchema = z.toJSONSchema(args.input, {
     target: "draft-07",
@@ -207,9 +389,7 @@ function defineAppCapability(args) {
 // app-sdk/src/ws-transport.ts
 var BEARER_SUBPROTOCOL_PREFIX = "skaile-bearer.";
 function encodeBearerSubprotocol(token) {
-  const bytes = new TextEncoder().encode(token);
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
+  const binary = String.fromCharCode(...new TextEncoder().encode(token));
   const b64 = btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
   return BEARER_SUBPROTOCOL_PREFIX + b64;
 }
@@ -227,9 +407,15 @@ function createWebSocketAppTransport(options) {
   const messageHandlers = /* @__PURE__ */ new Set();
   const disconnectHandlers = /* @__PURE__ */ new Set();
   function connect() {
+    if (typeof sessionToken === "function") {
+      return Promise.resolve(sessionToken()).then(openSocket);
+    }
+    return openSocket(sessionToken);
+  }
+  function openSocket(token) {
     return new Promise((resolve, reject) => {
       let opened = false;
-      const socket = new WebSocketImpl(url, [encodeBearerSubprotocol(sessionToken)]);
+      const socket = new WebSocketImpl(url, [encodeBearerSubprotocol(token)]);
       ws = socket;
       const timer = setTimeout(() => {
         if (opened) return;
@@ -290,6 +476,6 @@ function createWebSocketAppTransport(options) {
   };
 }
 
-export { DEFAULT_HELLO_TIMEOUT_MS, consoleLogger, createSkaileApp, createWebSocketAppTransport, defineAppCapability, noopLogger };
+export { AppHandshakeRefusedError, DEFAULT_HELLO_TIMEOUT_MS, DEFAULT_PARAMS_TIMEOUT_MS, PARENT_ORIGIN_QUERY_PARAM, consoleLogger, createSkaileApp, createWebSocketAppTransport, defineAppCapability, noopLogger, resolveAppConnectionParams };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map