@kortix/sdk 0.9.98

package/dist/server.js

@@ -0,0 +1,122 @@
+/**
+ * `@kortix/sdk/server` — Node/Bun-only request-scoped config isolation for
+ * "Kortix as a Backend": a third-party server process that wraps Kortix on
+ * behalf of multiple end users/tenants concurrently.
+ *
+ * NEVER import this subpath from a browser bundle. It statically imports
+ * `config-node.ts`, which statically imports `node:async_hooks` — most
+ * browser bundlers choke if that appears anywhere in their graph. The root
+ * `@kortix/sdk` entry point and `@kortix/sdk/react` never import this file,
+ * so a web host's bundle is unaffected either way; this subpath exists
+ * specifically for the non-browser "backend" case.
+ *
+ * Why this exists: `configureKortix()`/`createKortix()` (the root `@kortix/sdk`
+ * seam) store the platform config — crucially, the bearer token getter — in a
+ * single process-wide module-global (see `platform/config.ts`). That's fine
+ * for a host with exactly one config for its whole lifetime (a browser tab, a
+ * CLI, a single-tenant server). It is UNSAFE for a server process handling
+ * concurrent requests on behalf of different users: two in-flight requests
+ * racing through `configureKortix()` with different tokens clobber each
+ * other — whichever call landed last wins for every other in-flight request
+ * (see the warning on `ServerTokenOptions` in
+ * `platform/projects-client/shared.ts`).
+ *
+ * `runWithKortix`/`createScopedKortix` fix that using Node's
+ * `AsyncLocalStorage`: the config passed to one call is visible ONLY inside
+ * that call's async continuation (every `await` inside it), correctly
+ * isolated from any other concurrent call in the same process.
+ */
+import { createKortix } from './kortix.js';
+import { runScoped, runWithKortix, getScopedConfig } from './platform/config-node.js';
+export { runWithKortix, getScopedConfig };
+const MAX_WRAP_DEPTH = 12;
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Recursively wrap every function (including function-valued getters)
+ * reachable from `value` so calling it runs inside `runScoped(config, ...)`.
+ * Also wraps a wrapped function's OWN return value (sync, or the resolved
+ * value of a returned Promise) — this is what makes id-bound handles minted
+ * AT CALL TIME (`kortix.project(id)`, `kortix.session(pid, sid)`) come back
+ * fully scoped too, not just the static shape of `createKortix()`'s top-level
+ * return.
+ *
+ * Recurses into plain objects/arrays only — class instances and built-ins
+ * (`Error`/`Date`/`Map`/`Set`/`Blob`/`Response`/async iterables/…) pass
+ * through untouched, so this never mis-clones a vendor object whose
+ * correctness depends on its prototype/internal slots (e.g. the escape-hatch
+ * `OpencodeClient` from `.runtime`, or a `Response`/Blob returned by a file
+ * read). A depth cap + a per-branch `WeakSet` guards against accidental
+ * cycles or pathologically deep payloads.
+ */
+function wrapScoped(value, config, seen, depth = 0) {
+    if (depth > MAX_WRAP_DEPTH)
+        return value;
+    if (typeof value === 'function') {
+        const fn = value;
+        const wrapped = (...args) => {
+            const result = runScoped(config, () => fn(...args));
+            if (result instanceof Promise) {
+                return result.then((resolved) => wrapScoped(resolved, config, new WeakSet(), 0));
+            }
+            return wrapScoped(result, config, new WeakSet(), 0);
+        };
+        return wrapped;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+        return value.map((item) => wrapScoped(item, config, seen, depth + 1));
+    }
+    if (isPlainObject(value)) {
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+        const out = {};
+        for (const key of Object.keys(value)) {
+            const desc = Object.getOwnPropertyDescriptor(value, key);
+            if (desc.get) {
+                Object.defineProperty(out, key, {
+                    enumerable: true,
+                    get: () => wrapScoped(desc.get.call(value), config, new WeakSet(), 0),
+                });
+            }
+            else {
+                out[key] = wrapScoped(desc.value, config, seen, depth + 1);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Same shape as `createKortix(config)`, but every method call — including
+ * calls reached through `.project(id)`/`.session(pid, sid)` handles minted at
+ * call time — automatically runs inside `runWithKortix(config, ...)`. This
+ * handle never writes to (or is affected by) the process-global config
+ * singleton other `createKortix()`/`configureKortix()` callers in the same
+ * process share. Safe to construct one per incoming request in a multi-tenant
+ * server:
+ *
+ *   import { createScopedKortix } from '@kortix/sdk/server';
+ *
+ *   app.get('/projects', async (req, res) => {
+ *     const kortix = createScopedKortix({ backendUrl, getToken: () => tokenFor(req) });
+ *     res.json(await kortix.projects.list());
+ *   });
+ *
+ * Two concurrent requests each calling `createScopedKortix` with a different
+ * token never see each other's config, even though both run in the same
+ * process — unlike two concurrent `createKortix()` calls, which share (and
+ * race on) the global singleton.
+ */
+export function createScopedKortix(config) {
+    const inner = createKortix(config, { global: false });
+    return wrapScoped(inner, config, new WeakSet());
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/session/health.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Session runtime health — `GET /kortix/health` on the session's runtime.
+ *
+ * The host asks a session whether its runtime is ready; it never reasons about
+ * "the sandbox" directly. This is the liveness probe used to gate "runtime
+ * active" vs "OpenCode ready". The runtime-ready parsing rule lives here so
+ * every consumer interprets a payload identically. It never throws on a non-ok
+ * HTTP status — it surfaces `status`/`ok` so the caller applies its own failure
+ * thresholds.
+ *
+ * NOTE: the legacy `GET /kortix/ports` endpoint is intentionally NOT wrapped —
+ * the current agent server (rewritten 2026-05) serves no such route; port
+ * mappings come from the platform API, and live port access is the
+ * `/proxy/:port/*` reverse proxy (see `./url`).
+ */
+export type SessionHealthResponse = {
+    status?: string;
+    runtimeReady?: boolean;
+    version?: string;
+    opencode?: string | boolean;
+    boot_error?: string | null;
+    reason?: string | null;
+    message?: string | null;
+};
+export interface SessionHealthResult {
+    /** HTTP status of the probe (0 when there is no active runtime URL). */
+    status: number;
+    ok: boolean;
+    /** Parsed health body, or null when the response wasn't JSON. */
+    health: SessionHealthResponse | null;
+    /** Raw response text — useful for non-ok diagnostics. */
+    body: string;
+}
+/** Whether a health payload indicates the OpenCode runtime is ready. */
+export declare function isRuntimeReady(health: SessionHealthResponse | null): boolean;
+/**
+ * `GET /kortix/health` — returns the HTTP status plus the parsed body. Never
+ * throws on a non-ok status; callers decide what a given status means.
+ *
+ * `runtimeUrl` OMITTED (`undefined`) falls back to the module-global "active"
+ * runtime, for callers that don't scope to a specific session. Passing `null`
+ * or `''` EXPLICITLY means "this session has no resolved runtime yet" and
+ * short-circuits to the graceful `{ status: 0, ok: false }` shape WITHOUT
+ * falling back to the active runtime — a per-session handle (e.g.
+ * `kortix.session(pid, sid).health()`) must never silently probe whichever
+ * DIFFERENT session's sandbox happens to be globally active.
+ */
+export declare function getSessionHealth(runtimeUrl?: string | null, init?: RequestInit): Promise<SessionHealthResult>;
+//# sourceMappingURL=health.d.ts.map

package/dist/session/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/session/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAU5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,EAC1B,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,mBAAmB,CAAC,CAgB9B"}

package/dist/session/health.js

@@ -0,0 +1,57 @@
+/**
+ * Session runtime health — `GET /kortix/health` on the session's runtime.
+ *
+ * The host asks a session whether its runtime is ready; it never reasons about
+ * "the sandbox" directly. This is the liveness probe used to gate "runtime
+ * active" vs "OpenCode ready". The runtime-ready parsing rule lives here so
+ * every consumer interprets a payload identically. It never throws on a non-ok
+ * HTTP status — it surfaces `status`/`ok` so the caller applies its own failure
+ * thresholds.
+ *
+ * NOTE: the legacy `GET /kortix/ports` endpoint is intentionally NOT wrapped —
+ * the current agent server (rewritten 2026-05) serves no such route; port
+ * mappings come from the platform API, and live port access is the
+ * `/proxy/:port/*` reverse proxy (see `./url`).
+ */
+import { authenticatedFetch } from '../platform/auth.js';
+import { getActiveOpenCodeUrl } from '../state/server-store/active.js';
+/** Whether a health payload indicates the OpenCode runtime is ready. */
+export function isRuntimeReady(health) {
+    if (!health)
+        return false;
+    if (health.runtimeReady !== undefined)
+        return health.runtimeReady === true;
+    if (health.opencode !== undefined)
+        return health.opencode === 'ok' || health.opencode === true;
+    return (health.status !== 'starting' &&
+        health.status !== 'down' &&
+        health.status !== 'error');
+}
+/**
+ * `GET /kortix/health` — returns the HTTP status plus the parsed body. Never
+ * throws on a non-ok status; callers decide what a given status means.
+ *
+ * `runtimeUrl` OMITTED (`undefined`) falls back to the module-global "active"
+ * runtime, for callers that don't scope to a specific session. Passing `null`
+ * or `''` EXPLICITLY means "this session has no resolved runtime yet" and
+ * short-circuits to the graceful `{ status: 0, ok: false }` shape WITHOUT
+ * falling back to the active runtime — a per-session handle (e.g.
+ * `kortix.session(pid, sid).health()`) must never silently probe whichever
+ * DIFFERENT session's sandbox happens to be globally active.
+ */
+export async function getSessionHealth(runtimeUrl, init) {
+    const url = (runtimeUrl === undefined ? getActiveOpenCodeUrl() : runtimeUrl) || null;
+    if (!url)
+        return { status: 0, ok: false, health: null, body: '' };
+    const res = await authenticatedFetch(`${url}/kortix/health`, { method: 'GET', ...init }, { retryOnAuthError: false });
+    const body = await res.text().catch(() => '');
+    let health = null;
+    try {
+        health = body ? JSON.parse(body) : null;
+    }
+    catch {
+        health = null;
+    }
+    return { status: res.status, ok: res.ok, health, body };
+}
+//# sourceMappingURL=health.js.map

package/dist/session/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/session/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAsBpE,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAAC,MAAoC;IACjE,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,YAAY,KAAK,IAAI,CAAC;IAC3E,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC/B,OAAO,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC;IAC9D,OAAO,CACL,MAAM,CAAC,MAAM,KAAK,UAAU;QAC5B,MAAM,CAAC,MAAM,KAAK,MAAM;QACxB,MAAM,CAAC,MAAM,KAAK,OAAO,CAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,UAA0B,EAC1B,IAAkB;IAElB,MAAM,GAAG,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;IACrF,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAClE,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAClC,GAAG,GAAG,gBAAgB,EACtB,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAC1B,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAC5B,CAAC;IACF,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,IAAI,MAAM,GAAiC,IAAI,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAA2B,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1D,CAAC"}

package/dist/session/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@kortix/sdk/session` — a session's runtime surface.
+ *
+ * The host thinks in sessions, never in sandboxes: a session owns its runtime,
+ * so health + preview/proxy URLs hang off the session. Most hosts reach these
+ * through the `createKortix(...).session(pid, sid)` handle (`.health()`,
+ * `.previewUrl()`, `.proxyUrl()`); these named exports exist for stateless use
+ * (e.g. detecting/parsing localhost URLs in agent output during rendering).
+ *
+ * Verified against the current agent server (rewritten 2026-05): proxy/preview/
+ * web-proxy URL building (`/proxy/:port`, `/web-proxy`, path + subdomain forms),
+ * the `/kortix/health` liveness probe, and the preview-proxy auth helpers. Dead
+ * legacy endpoints (`/kortix/ports`, `/env` CRUD, `/kortix/services`, the board)
+ * are excluded.
+ */
+export * from './url.js';
+export * from './health.js';
+export * from './preview.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/session/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@kortix/sdk/session` — a session's runtime surface.
+ *
+ * The host thinks in sessions, never in sandboxes: a session owns its runtime,
+ * so health + preview/proxy URLs hang off the session. Most hosts reach these
+ * through the `createKortix(...).session(pid, sid)` handle (`.health()`,
+ * `.previewUrl()`, `.proxyUrl()`); these named exports exist for stateless use
+ * (e.g. detecting/parsing localhost URLs in agent output during rendering).
+ *
+ * Verified against the current agent server (rewritten 2026-05): proxy/preview/
+ * web-proxy URL building (`/proxy/:port`, `/web-proxy`, path + subdomain forms),
+ * the `/kortix/health` liveness probe, and the preview-proxy auth helpers. Dead
+ * legacy endpoints (`/kortix/ports`, `/env` CRUD, `/kortix/services`, the board)
+ * are excluded.
+ */
+export * from './url.js';
+export * from './health.js';
+export * from './preview.js';
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/session/preview.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Preview-proxy auth helpers (pure).
+ *
+ * A host hook drives the cookie/token exchange against the preview proxy; these
+ * helpers decide the auth endpoint and the token-append rule so the proxy auth
+ * scheme lives in exactly one place. They target the current proxy surface:
+ * path-based `/v1/p/{sandbox}/{port}/…`, the daemon `/proxy/{port}/…`, and the
+ * subdomain `p{port}-{sandbox}.{host}/…` form.
+ */
+/**
+ * Resolve the `POST /…/p/auth` endpoint that sets the `__preview_session`
+ * cookie for a given preview URL. Returns null when the URL isn't a trusted
+ * preview-proxy URL.
+ */
+export declare function buildPreviewAuthEndpoint(previewUrl: string, serverUrl?: string): string | null;
+/**
+ * Subdomain preview form: `p{port}-{sandbox}.{host}/…`. These can't use the
+ * host-only `/v1/p/` session cookie (it never reaches the preview subdomain),
+ * so they authenticate via a one-shot `?token` on the first request.
+ */
+export declare function isSubdomainPreviewUrl(candidateUrl: string): boolean;
+/** Append a one-shot `?token` to a (subdomain) preview URL. */
+export declare function appendPreviewToken(previewUrl: string, token: string): string;
+//# sourceMappingURL=preview.d.ts.map

package/dist/session/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/session/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6CH;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAMf;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAMnE;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ5E"}

package/dist/session/preview.js

@@ -0,0 +1,85 @@
+/**
+ * Preview-proxy auth helpers (pure).
+ *
+ * A host hook drives the cookie/token exchange against the preview proxy; these
+ * helpers decide the auth endpoint and the token-append rule so the proxy auth
+ * scheme lives in exactly one place. They target the current proxy surface:
+ * path-based `/v1/p/{sandbox}/{port}/…`, the daemon `/proxy/{port}/…`, and the
+ * subdomain `p{port}-{sandbox}.{host}/…` form.
+ */
+function derivePreviewAuthEndpoint(candidateUrl) {
+    try {
+        const url = new URL(candidateUrl);
+        if (/^\/proxy\/\d+(?:\/|$)/.test(url.pathname)) {
+            return `${url.origin}/v1/p/auth`;
+        }
+        const previewIndex = url.pathname.indexOf('/p/');
+        if (previewIndex !== -1) {
+            return `${url.origin}${url.pathname.slice(0, previewIndex)}/p/auth`;
+        }
+        return `${url.origin}/v1/p/auth`;
+    }
+    catch {
+        return null;
+    }
+}
+function isPreviewProxyUrl(candidateUrl, serverUrl) {
+    try {
+        const url = new URL(candidateUrl);
+        const path = url.pathname;
+        const isPreviewPath = /^\/v1\/p\/[^/]+\/\d+(?:\/|$)/.test(path) ||
+            /^\/proxy\/\d+(?:\/|$)/.test(path);
+        if (!isPreviewPath)
+            return false;
+        const trustedOrigins = new Set();
+        if (serverUrl) {
+            try {
+                trustedOrigins.add(new URL(serverUrl).origin);
+            }
+            catch { }
+        }
+        if (typeof window !== 'undefined') {
+            trustedOrigins.add(window.location.origin);
+        }
+        return trustedOrigins.size === 0 || trustedOrigins.has(url.origin);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the `POST /…/p/auth` endpoint that sets the `__preview_session`
+ * cookie for a given preview URL. Returns null when the URL isn't a trusted
+ * preview-proxy URL.
+ */
+export function buildPreviewAuthEndpoint(previewUrl, serverUrl) {
+    if (!isPreviewProxyUrl(previewUrl, serverUrl))
+        return null;
+    return ((serverUrl ? derivePreviewAuthEndpoint(serverUrl) : null) ??
+        derivePreviewAuthEndpoint(previewUrl));
+}
+/**
+ * Subdomain preview form: `p{port}-{sandbox}.{host}/…`. These can't use the
+ * host-only `/v1/p/` session cookie (it never reaches the preview subdomain),
+ * so they authenticate via a one-shot `?token` on the first request.
+ */
+export function isSubdomainPreviewUrl(candidateUrl) {
+    try {
+        return /^p\d+-[^.]+\./.test(new URL(candidateUrl).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** Append a one-shot `?token` to a (subdomain) preview URL. */
+export function appendPreviewToken(previewUrl, token) {
+    try {
+        const u = new URL(previewUrl);
+        u.searchParams.set('token', token);
+        return u.toString();
+    }
+    catch {
+        return previewUrl;
+    }
+}
+//# sourceMappingURL=preview.js.map

package/dist/session/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../src/session/preview.ts"],"names":[],"mappings":"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"}

package/dist/session/url.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Sandbox URL detection and rewriting utilities.
+ *
+ * Detects localhost URLs in agent output (e.g. "Website is live at http://localhost:8080")
+ * and rewrites them to subdomain-based preview URLs (like ngrok):
+ *
+ *   http://p{port}-{sandboxId}.localhost:{backendPort}/{path}
+ *
+ * The subdomain scheme means the proxied app thinks it's at root `/` — absolute
+ * paths, Service Workers, WebSocket connections all work without any rewriting.
+ * Auth is handled via a cookie set on the first `?token=` authenticated request.
+ */
+export interface DetectedLocalhostUrl {
+    /** The original full URL found in text (e.g. "http://localhost:8080/api/docs") */
+    originalUrl: string;
+    /** The port number */
+    port: number;
+    /** The path portion after the port (e.g. "/api/docs") */
+    path: string;
+    /** Start index in the source text */
+    startIndex: number;
+    /** End index in the source text */
+    endIndex: number;
+    /** Whether the URL was found inside a markdown code block or inline code span */
+    inCodeBlock: boolean;
+}
+export interface ParsedLocalhostUrl {
+    /** Canonicalized localhost URL (http(s)://localhost:PORT/path?query#hash) */
+    originalUrl: string;
+    /** Parsed port number */
+    port: number;
+    /** Parsed path + query + hash (always starts with /) */
+    path: string;
+}
+/** Options for proxy URL generation */
+export interface SubdomainUrlOptions {
+    /** Sandbox ID (the sandbox's external id — the Daytona sandbox ID). */
+    sandboxId: string;
+    /** Backend port (e.g. 8008) — the port kortix-api listens on */
+    backendPort: number;
+    /**
+     * The public-facing API base URL (e.g. 'https://e2e-test.kortix.cloud/v1').
+     * When the user's browser is NOT on localhost, path-based proxy URLs are
+     * generated from this:
+     *   https://e2e-test.kortix.cloud/v1/p/{sandboxId}/{port}/{path}
+     *
+     * This makes proxy URLs work on VPS/self-hosted deployments where
+     * *.localhost subdomain DNS resolution isn't available.
+     */
+    apiBaseUrl: string;
+}
+export declare function isAppRouteUrl(rawUrl: string | undefined): boolean;
+/**
+ * Parse a localhost URL in one place so all consumers share identical rules.
+ *
+ * Handles a special case: `http://localhost:8000/proxy/{port}/{path}` URLs
+ * from inside the sandbox (Kortix Master). These are rewritten to appear as
+ * `localhost:{port}/{path}` so they get proxied correctly.
+ */
+export declare function parseLocalhostUrl(rawUrl: string | undefined): ParsedLocalhostUrl | null;
+/**
+ * Detect all localhost URLs in a text string.
+ * Tags each result with `inCodeBlock` so consumers can render URLs found
+ * inside markdown code blocks / inline code differently (e.g. compact chips
+ * instead of full preview cards with iframes).
+ */
+export declare function detectLocalhostUrls(text: string): DetectedLocalhostUrl[];
+/**
+ * Check if a string contains any localhost URLs worth rewriting.
+ */
+export declare function hasLocalhostUrls(text: string): boolean;
+/**
+ * Build a preview proxy URL for a sandbox service port.
+ *
+ * Both modes are proxy URLs — neither connects to the user's raw localhost.
+ * The provider is irrelevant; the only thing that matters is whether kortix-api
+ * is running on the user's local machine, because that determines whether
+ * *.localhost DNS can reach it.
+ *
+ *   - **Subdomain** (backend local): `http://p{port}-{sandboxId}.localhost:{backendPort}/{path}`
+ *     Transparent mode — the proxied app thinks it's at root `/`. Only works
+ *     when kortix-api is on 127.0.0.1.
+ *
+ *   - **Path-based** (backend remote): `{apiBaseUrl}/p/{sandboxId}/{port}/{path}`
+ *     Goes through Caddy → API → sandbox. Used for all deployed setups.
+ *
+ * @example
+ *   // Local dev:      → 'http://p3210-sb-abc123.localhost:8008/viewer.html'
+ *   // Deployed back:  → 'https://e2e-test.kortix.cloud/v1/p/sb-abc123/3210/viewer.html'
+ */
+export declare function rewriteLocalhostUrl(port: number, path: string, subdomainOpts: SubdomainUrlOptions): string;
+/**
+ * Build the proxy base URL for a given port (without path).
+ * Used for opening preview tabs.
+ */
+export declare function getProxyBaseUrl(port: number, subdomainOpts: SubdomainUrlOptions): string;
+/**
+ * Check if a URL is a localhost URL that we can proxy.
+ * Excludes infrastructure ports AND the current app's own port so we never
+ * rewrite the frontend's own navigation links.
+ * Also excludes URLs that are already subdomain preview URLs.
+ */
+export declare function isProxiableLocalhostUrl(url: string): boolean;
+/**
+ * If the given URL points to localhost:PORT, rewrite it through the sandbox
+ * proxy layer. Returns the original URL unchanged when it doesn't match or
+ * targets an excluded infrastructure port.
+ *
+ * This is the catch-all intended for use inside markdown renderers so that
+ * every `<a href>`, `<img src>`, etc. that references a sandbox service
+ * automatically gets proxied.
+ */
+export declare function proxyLocalhostUrl(url: string | undefined, subdomainOpts: SubdomainUrlOptions): string | undefined;
+/**
+ * Build the internal (container-side) localhost URL for a given port + path.
+ * This is what the user sees as the "real" address inside the sandbox.
+ *
+ * @example toInternalUrl(8080, '/api/docs') → 'http://localhost:8080/api/docs'
+ */
+export declare function toInternalUrl(port: number, path?: string): string;
+/**
+ * Parse a preview proxy URL back to its components.
+ * Handles both subdomain and path-based formats:
+ *
+ * Subdomain: http://p3210-sb-abc123.localhost:8008/viewer.html
+ * Path:      https://e2e-test.kortix.cloud/v1/p/sb-abc123/3210/viewer.html
+ */
+export declare function parseSubdomainUrl(url: string): {
+    port: number;
+    sandboxId: string;
+    backendPort: number;
+    path: string;
+} | null;
+/**
+ * Try to reverse-map a proxy URL back to its internal localhost equivalent.
+ *
+ * Handles `http://p{port}-{sandboxId}.localhost:{backendPort}/{path}` →
+ * `http://localhost:{port}{path}`.
+ *
+ * Returns null if the URL can't be reverse-mapped.
+ */
+export declare function proxyUrlToInternal(proxyUrl: string): string | null;
+/**
+ * Check if a URL is already a preview proxy URL (subdomain or path-based).
+ * Use this to prevent double-proxying.
+ */
+export declare function isPreviewUrl(url: string): boolean;
+/**
+ * Build a web proxy URL that routes through the Kortix Master (port 8000)
+ * which hosts the /web-proxy/ forward proxy.
+ *
+ * The web proxy lives on Kortix Master, NOT the OpenCode server, so we
+ * construct a URL targeting port 8000 via the standard sandbox preview proxy.
+ */
+export declare function buildWebProxyUrl(targetUrl: string, subdomainOpts: SubdomainUrlOptions): string | null;
+export declare function parseWebProxyUrl(proxyUrl: string): string | null;
+export declare function isWebProxyUrl(url: string): boolean;
+export declare function isExternalUrl(rawUrl: string): boolean;
+export declare function normalizeExternalInput(input: string): string | null;
+//# sourceMappingURL=url.d.ts.map

package/dist/session/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/session/url.ts"],"names":[],"mappings":"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"}