@kortix/sdk 0.9.98

package/dist/kortix.js

@@ -0,0 +1,772 @@
+/**
+ * createKortix — the single opinionated entry point to the Kortix data layer.
+ *
+ * One client. Every action a method. The host app imports ONLY from `@kortix/sdk`
+ * — never `@opencode-ai/sdk`, never `backendApi`/`authenticatedFetch` directly.
+ *
+ *   const kortix = createKortix({ getToken });
+ *   await kortix.projects.list();
+ *   await kortix.project(pid).secrets.upsert({ name, value });
+ *   const s = kortix.session(pid, sid);
+ *   await s.start();
+ *   s.runtime.session.prompt({ sessionID: sid, parts });   // typed opencode, via the SDK
+ *
+ * REST methods are direct references to the platform client, so they keep their
+ * exact types with zero re-typing. The `project()`/`session()` handles bind ids
+ * for ergonomics. Reactive data still comes from `@kortix/sdk/react` hooks.
+ */
+import * as F from './files/client.js';
+import { getClient, getClientForUrl } from './opencode/client.js';
+import { ApiError } from './platform/api/errors.js';
+import { configureKortix, platformConfig } from './platform/config.js';
+import * as P from './platform/projects-client/index.js';
+import { getSessionHealth } from './session/health.js';
+import { proxyLocalhostUrl, rewriteLocalhostUrl } from './session/url.js';
+import { setCurrentRuntime } from './state/current-runtime.js';
+import { clearSessionRuntime, getSessionRuntime, } from './state/session-runtime-registry.js';
+import { getSandboxUrlForExternalId } from './state/server-store/url-helpers.js';
+import { openEventStream, } from './state/event-stream.js';
+/** The opencode runtime client for the currently-active sandbox (set by the host). */
+function runtime() {
+    return getClient();
+}
+/**
+ * Thrown by a session handle's runtime-scoped operations (`.runtime`,
+ * `.health()`, `.previewUrl()`, `.proxyUrl()`) when called before the handle
+ * has resolved its own sandbox runtime. These never fall back to whatever
+ * sandbox happens to be globally active (a different session's runtime) —
+ * the caller must resolve THIS handle's runtime first.
+ */
+/**
+ * Dedupes concurrent `ensureReady()` calls that would otherwise both drive a
+ * `/start` long-poll for the SAME (projectId, sessionId) — e.g. two session
+ * handles for the same session (or the facade racing the React `useSession`
+ * hook) both calling `ensureReady()`/`start()` before either has resolved a
+ * runtime. Keyed by `${projectId}\n${sessionId}` (not the process-global
+ * "active runtime" — every other handle for a DIFFERENT session gets its own
+ * entry and is unaffected). Cleared on settle (success or failure) so a
+ * transient failure doesn't wedge the key — the next call issues a fresh
+ * `/start` instead of replaying a stale rejected promise forever.
+ */
+const inFlightSessionStarts = new Map();
+export class SessionNotReadyError extends Error {
+    constructor(action) {
+        super(`Session runtime not ready — call \`await session.ensureReady()\` (it drives \`start()\` to completion and resolves this session's own sandbox runtime) before calling \`${action}\`.`);
+        this.name = 'SessionNotReadyError';
+    }
+}
+export function createKortix(config, opts) {
+    // Wire the platform seam once. All wrapped functions read it.
+    //
+    // `opts.global === false` (used by `@kortix/sdk/server`'s `createScopedKortix`)
+    // skips the process-wide write entirely — that caller relies solely on the
+    // `AsyncLocalStorage` scope `createScopedKortix` wraps every method call in,
+    // so this returned facade never touches (or is affected by) the module-global
+    // singleton other concurrent `createKortix()` calls in the same process share.
+    configureKortix(config, opts);
+    /**
+     * Parse `backendUrl` for its port (used by the subdomain preview scheme).
+     * `backendUrl` is normally absolute, but the BFF pattern — a Next.js API
+     * route (or any same-origin proxy) fronting the real Kortix API — legitimately
+     * configures it as a relative path like `/api/kortix`. `new URL()` throws on
+     * a bare relative string (no base to resolve against). In a browser that's
+     * recoverable: resolve it against the page's own origin. Server-side there
+     * is no implicit origin, so a relative `backendUrl` is a real misconfiguration
+     * — fail loudly instead of silently defaulting to port 80.
+     */
+    function parseBackendUrlForPort(apiBaseUrl) {
+        try {
+            return new URL(apiBaseUrl);
+        }
+        catch {
+            if (typeof window !== 'undefined' && window.location?.origin) {
+                try {
+                    return new URL(apiBaseUrl, window.location.origin);
+                }
+                catch {
+                    return null;
+                }
+            }
+            throw new ApiError(`Kortix SDK: backendUrl must be an absolute URL outside the browser (got ${JSON.stringify(apiBaseUrl)}). Relative paths like "/api/kortix" only resolve against a page origin — configure an absolute backendUrl for server-side hosts.`, { code: 'INVALID_BACKEND_URL' });
+        }
+    }
+    /**
+     * Resolve the proxy/preview URL context (sandboxId + api base) from config +
+     * a THIS-handle's own resolved sandbox id, so a session's `previewUrl`/
+     * `proxyUrl` never make the host name a sandbox — and never reads whichever
+     * sandbox happens to be globally active (which may belong to a different
+     * session handle).
+     */
+    function resolvePreviewOptsForSandbox(sandboxId) {
+        // Read the LIVE platform config, not the `config` captured at
+        // `createKortix()` time: a host may re-point the seam after creation
+        // (calling `configureKortix()` again — e.g. the whitelabel app switching
+        // its `backendUrl` to a same-origin BFF proxy once it learns wrapper mode
+        // is on), and preview/proxy URLs must follow the reconfigured base like
+        // every other call path already does.
+        const apiBaseUrl = platformConfig().backendUrl ?? config.backendUrl;
+        let backendPort = 80;
+        const u = parseBackendUrlForPort(apiBaseUrl);
+        if (u) {
+            backendPort = u.port ? Number(u.port) : u.protocol === 'https:' ? 443 : 80;
+        }
+        return { sandboxId, backendPort, apiBaseUrl };
+    }
+    /** Account-scoped operations. */
+    const accounts = {
+        list: P.listAccounts,
+        get: P.getAccount,
+        create: P.createAccount,
+        updateName: P.updateAccountName,
+        leave: P.leaveAccount,
+        members: P.listAccountMembers,
+        invite: P.inviteAccountMember,
+        removeMember: P.removeAccountMember,
+        updateMemberRole: P.updateAccountMemberRole,
+        invites: P.listAccountInvites,
+        /** Cancel a pending account invite (accountId still known/scoped). */
+        cancelInvite: P.cancelAccountInvite,
+        /** Resend a pending account invite (accountId still known/scoped). */
+        resendInvite: P.resendAccountInvite,
+        /** CLI PAT minting — account-scoped personal access tokens (`kortix_pat_...`). */
+        tokens: {
+            list: P.listAccountTokens,
+            create: P.createAccountToken,
+            revoke: P.revokeAccountToken,
+        },
+        /** Enterprise audit log — events + CSV/JSONL export + SIEM webhooks. */
+        audit: {
+            log: P.listAccountAudit,
+            export: P.exportAccountAudit,
+            webhooks: {
+                list: P.listAccountAuditWebhooks,
+                create: P.createAccountAuditWebhook,
+                update: P.updateAccountAuditWebhook,
+                remove: P.removeAccountAuditWebhook,
+            },
+        },
+    };
+    /**
+     * Billing read surface — credits, subscription, tier, and transaction
+     * history for entitlement-gating + a billing/usage UI. Checkout/portal/
+     * credit-purchase/subscription MUTATIONS stay app-owned (Stripe flows) —
+     * this is reads only.
+     */
+    const billing = {
+        accountState: P.getAccountState,
+        accountStateMinimal: P.getAccountStateMinimal,
+        transactions: P.listBillingTransactions,
+        transactionsSummary: P.getBillingTransactionsSummary,
+        creditBreakdown: P.getBillingCreditBreakdown,
+        usageHistory: P.getBillingUsageHistory,
+        tierConfigurations: P.getBillingTierConfigurations,
+        /** Stripe checkout — start a subscription and confirm it post-redirect. */
+        checkout: {
+            createSession: (input) => P.createCheckoutSession(input),
+            confirmSession: (sessionId, accountId) => P.confirmCheckoutSession(sessionId, accountId),
+        },
+        /** Manage an existing subscription (portal, cancel/reactivate, downgrade). */
+        subscription: {
+            createPortalSession: (returnUrl, accountId) => P.createPortalSession(returnUrl, accountId),
+            cancel: (feedback, accountId) => P.cancelSubscription(feedback, accountId),
+            reactivate: (accountId) => P.reactivateSubscription(accountId),
+            scheduleDowngrade: (targetTierKey, commitmentType, accountId) => P.scheduleDowngrade(targetTierKey, commitmentType, accountId),
+            cancelScheduledChange: (accountId) => P.cancelScheduledChange(accountId),
+            prorationPreview: (newPriceId, accountId) => P.getProrationPreview(newPriceId, accountId),
+        },
+        /** One-off credit purchases + recurring auto-topup configuration. */
+        credits: {
+            purchase: (input) => P.purchaseCredits(input),
+            autoTopupSettings: (accountId) => P.getAutoTopupSettings(accountId),
+            configureAutoTopup: (input) => P.configureAutoTopup(input),
+        },
+    };
+    /**
+     * Account-invite lifecycle reached by invite token alone — accept/decline/
+     * describe are called by the invitee (who may not be an account member, or
+     * even signed into this account, yet), so they take only `inviteId` and
+     * genuinely don't fit account- or project-scoping.
+     */
+    const accountInvites = {
+        describe: P.describeAccountInvite,
+        accept: P.acceptAccountInvite,
+        decline: P.declineAccountInvite,
+    };
+    /** Top-level project operations (not bound to an id). */
+    const projects = {
+        list: P.listProjects,
+        listForAccount: P.listProjectsForAccount,
+        get: P.getProject,
+        detail: P.getProjectDetail,
+        create: P.createProject,
+        /** Create a project backed by a brand-new Kortix-managed GitHub repo. */
+        createRepo: P.createProjectRepo,
+        provision: P.provisionProject,
+        update: P.updateProject,
+        archive: P.archiveProject,
+        llmCatalog: P.getProjectLlmCatalog,
+        sandboxHealth: P.getProjectSandboxHealth,
+        sandboxTemplates: P.listProjectSandboxTemplates,
+        sessions: P.listProjectSessions,
+        createSession: P.createProjectSession,
+    };
+    /** GitHub App installation + repository linking — account-scoped, not project-scoped. */
+    const github = {
+        linkRepository: P.linkRepository,
+        getInstallation: P.getGitHubInstallation,
+        listInstallations: P.listGitHubInstallations,
+        listRepositories: P.listGitHubRepositories,
+        saveInstallation: P.saveGitHubInstallation,
+        deleteInstallation: P.deleteGitHubInstallation,
+    };
+    /** Public share links for a sandbox port (`/v1/p/share`) — sandbox-scoped, not project-scoped. */
+    const sandboxShares = {
+        list: P.listSandboxShares,
+        create: P.createSandboxShare,
+        revoke: P.revokeSandboxShare,
+    };
+    /** Deployment-wide flag: is the easy-connect (Pipedream) provider configured? Not project-scoped. */
+    const connectStatus = P.getConnectStatus;
+    /**
+     * Public marketplace catalog browse (`/v1/marketplace/*`) — top-level and
+     * distinct from `project(id).marketplace`, which is install-scoped (commits
+     * an item onto a specific project's branch). This is read-only browsing +
+     * the authed "add a marketplace source" surface.
+     */
+    const marketplace = {
+        items: (options) => P.listMarketplaceCatalogItems(options),
+        item: (id) => P.getMarketplaceCatalogItem(id),
+        itemFile: (id, path) => P.getMarketplaceCatalogItemFile(id, path),
+        marketplaces: () => P.listMarketplaces(),
+        featured: () => P.listFeaturedMarketplaces(),
+        sources: {
+            list: () => P.listMarketplaceSources(),
+            add: (input) => P.addMarketplaceSource(input),
+            remove: (id) => P.removeMarketplaceSource(id),
+        },
+    };
+    /** Id-bound handle for a single project: every sub-resource, projectId pre-applied. */
+    function project(projectId) {
+        return {
+            get: (opts) => P.getProject(projectId, opts),
+            detail: () => P.getProjectDetail(projectId),
+            update: (input) => P.updateProject(projectId, input),
+            archive: () => P.archiveProject(projectId),
+            llmCatalog: () => P.getProjectLlmCatalog(projectId),
+            sandboxHealth: () => P.getProjectSandboxHealth(projectId),
+            onboardingComplete: (...a) => P.setProjectOnboardingComplete(projectId, ...a),
+            /** Project-scoped CLI PATs (auto-minted at session-create as `KORTIX_TOKEN`; can also be minted by hand). */
+            tokens: {
+                list: () => P.listProjectCliTokens(projectId),
+                create: (input) => P.createProjectCliToken(projectId, input),
+                revoke: (tokenId) => P.revokeProjectCliToken(projectId, tokenId),
+            },
+            /** Agent-minted setup links — hand a human a link to enter a secret value or 1-click connect an app. */
+            setupLinks: {
+                requestSecret: (input) => P.requestProjectSecret(projectId, input),
+                requestConnector: (input) => P.requestProjectConnector(projectId, input),
+            },
+            /** Validate a `kortix.toml` manifest's raw TOML text server-side (same schema `kortix ship`/CR-merge use). */
+            validateManifest: (raw) => P.validateProjectManifest(projectId, raw),
+            /** Mint a fresh scoped git push token for a managed project (409 for BYO repos). */
+            gitToken: () => P.getProjectGitToken(projectId),
+            /** Marketplace install/updates — commits an item's files (+ lock) straight onto the default branch. */
+            marketplace: {
+                list: () => P.listInstalledMarketplaceItems(projectId),
+                install: (id) => P.installMarketplaceItem(projectId, id),
+                updates: () => P.getMarketplaceUpdates(projectId),
+                update: (name) => P.updateMarketplaceItem(projectId, name),
+                updateAll: () => P.updateAllMarketplaceItems(projectId),
+                remove: (name) => P.removeMarketplaceItem(projectId, name),
+            },
+            /** `registry.*` — compatibility alias of `marketplace.*` (identical server-side handlers). */
+            registry: {
+                list: () => P.listInstalledRegistryItems(projectId),
+                install: (id) => P.installRegistryItem(projectId, id),
+                updates: () => P.getRegistryUpdates(projectId),
+                update: (name) => P.updateRegistryItem(projectId, name),
+                updateAll: () => P.updateAllRegistryItems(projectId),
+                remove: (name) => P.removeRegistryItem(projectId, name),
+            },
+            secrets: {
+                list: () => P.listProjectSecrets(projectId),
+                upsert: (input) => P.upsertProjectSecret(projectId, input),
+                remove: (name) => P.deleteProjectSecret(projectId, name),
+                setPersonal: (...a) => P.setPersonalProjectSecret(projectId, ...a),
+                removePersonal: (name) => P.deletePersonalProjectSecret(projectId, name),
+                setGitCredential: (input) => P.upsertProjectGitCredential(projectId, input),
+                /** Device-code OAuth flow to connect a subscription-backed provider (e.g. ChatGPT). */
+                startProviderOAuth: (...a) => P.startProjectProviderOAuth(projectId, ...a),
+                pollProviderOAuth: (...a) => P.pollProjectProviderOAuth(projectId, ...a),
+            },
+            access: {
+                list: () => P.listProjectAccess(projectId),
+                invite: (...a) => P.inviteProjectMember(projectId, ...a),
+                update: (...a) => P.updateProjectAccess(projectId, ...a),
+                revoke: (userId) => P.revokeProjectAccess(projectId, userId),
+                pendingInvites: () => P.listPendingProjectInvites(projectId),
+                resendInvite: (...a) => P.resendPendingProjectInvite(projectId, ...a),
+                revokeInvite: (...a) => P.revokePendingProjectInvite(projectId, ...a),
+                requests: () => P.listProjectAccessRequests(projectId),
+                approveRequest: (...a) => P.approveProjectAccessRequest(projectId, ...a),
+                rejectRequest: (...a) => P.rejectProjectAccessRequest(projectId, ...a),
+                groupGrants: () => P.listProjectGroupGrants(projectId),
+                attachGroupGrant: (...a) => P.attachGroupToProject(projectId, ...a),
+                updateGroupGrant: (...a) => P.updateProjectGroupGrant(projectId, ...a),
+                detachGroupGrant: (groupId) => P.detachGroupFromProject(projectId, groupId),
+                /** Per-resource (agent/skill/secret) grants to a member or a group. */
+                resourceGrants: {
+                    list: () => P.listProjectResourceGrants(projectId),
+                    create: (input) => P.createProjectResourceGrant(projectId, input),
+                    remove: (grantId) => P.deleteProjectResourceGrant(projectId, grantId),
+                },
+            },
+            connectors: {
+                list: () => P.listConnectors(projectId),
+                config: (...a) => P.getConnectorConfig(projectId, ...a),
+                create: (...a) => P.createConnector(projectId, ...a),
+                remove: (...a) => P.deleteConnector(projectId, ...a),
+                sync: () => P.syncConnectors(projectId),
+                setName: (...a) => P.setConnectorName(projectId, ...a),
+                setCredentialMode: (...a) => P.setConnectorCredentialMode(projectId, ...a),
+                setCredential: (...a) => P.setConnectorCredential(projectId, ...a),
+                setSensitive: (...a) => P.setConnectorSensitive(projectId, ...a),
+                policies: {
+                    get: (...a) => P.getConnectorPolicies(projectId, ...a),
+                    set: (...a) => P.setConnectorPolicies(projectId, ...a),
+                },
+                /** Easy-connect (Pipedream): app catalog + connect/finalize handshake. */
+                pipedream: {
+                    listApps: (...a) => P.listPipedreamApps(projectId, ...a),
+                    connect: (...a) => P.pipedreamConnect(projectId, ...a),
+                    finalize: (...a) => P.pipedreamFinalize(projectId, ...a),
+                },
+            },
+            policies: {
+                list: () => P.listProjectPolicies(projectId),
+                set: (...a) => P.setProjectPolicies(projectId, ...a),
+            },
+            triggers: {
+                list: () => P.listProjectTriggers(projectId),
+                create: (...a) => P.createProjectTrigger(projectId, ...a),
+                update: (...a) => P.updateProjectTrigger(projectId, ...a),
+                remove: (...a) => P.deleteProjectTrigger(projectId, ...a),
+                fire: (...a) => P.fireProjectTrigger(projectId, ...a),
+                setActivation: (...a) => P.setProjectTriggersActivation(projectId, ...a),
+            },
+            files: {
+                list: (options) => P.listProjectFiles(projectId, options),
+                read: (path, ref) => P.readProjectFile(projectId, path, ref),
+                search: (...a) => P.searchProjectFiles(projectId, ...a),
+                archive: (...a) => P.fetchProjectArchive(projectId, ...a),
+                history: (...a) => P.getProjectFileHistory(projectId, ...a),
+            },
+            git: {
+                commits: () => P.listProjectCommits(projectId),
+                commit: (sha) => P.getProjectCommit(projectId, sha),
+                commitDiff: (sha) => P.getProjectCommitDiff(projectId, sha),
+                branches: () => P.listProjectBranches(projectId),
+                versionDiff: (...a) => P.getVersionDiff(projectId, ...a),
+                /** Invite a GitHub user as a collaborator on a Kortix-managed repo. */
+                inviteCollaborator: (...a) => P.inviteRepoCollaborator(projectId, ...a),
+            },
+            changeRequests: {
+                list: () => P.listChangeRequests(projectId),
+                get: (crId) => P.getChangeRequest(projectId, crId),
+                diff: (crId) => P.getChangeRequestDiff(projectId, crId),
+                mergePreview: (crId) => P.getChangeRequestMergePreview(projectId, crId),
+                open: (...a) => P.openChangeRequest(projectId, ...a),
+                merge: (...a) => P.mergeChangeRequest(projectId, ...a),
+                close: (...a) => P.closeChangeRequest(projectId, ...a),
+                reopen: (...a) => P.reopenChangeRequest(projectId, ...a),
+                /** Request changes on a CR (Review Center) — records feedback + optionally delivers it back to the originating session. */
+                requestChanges: (...a) => P.requestChangesOnChangeRequest(projectId, ...a),
+            },
+            sessions: {
+                list: () => P.listProjectSessions(projectId),
+                create: (input) => P.createProjectSession(projectId, input),
+            },
+            /** Review Center — the per-project human-in-the-loop inbox (change requests, tool approvals, agent outputs/decisions). */
+            review: {
+                list: (params) => P.listReviewItems(projectId, params),
+                get: (reviewItemId) => P.getReviewItem(projectId, reviewItemId),
+                submit: (input) => P.submitReviewItem(projectId, input),
+                act: (...a) => P.actReviewItem(projectId, ...a),
+                bulkAct: (input) => P.bulkActReviewItems(projectId, input),
+            },
+            /** The manager inbox of executor-gated actions awaiting approve/deny (APPROVE / ASK / BLOCK). */
+            approvals: {
+                list: (options) => P.listPendingApprovals(projectId, options),
+                resolve: (...a) => P.resolveApproval(projectId, ...a),
+                sessionsNeedingInput: (options) => P.listSessionsNeedingInput(projectId, options),
+            },
+            /** Gateway observability — LLM request logs, cost/latency rollups, budgets, gateway API keys. */
+            gateway: {
+                logs: (opts) => P.listGatewayLogs(projectId, opts),
+                log: (logId) => P.getGatewayLog(projectId, logId),
+                overview: (days) => P.getGatewayOverview(projectId, days),
+                series: (days) => P.getGatewaySeries(projectId, days),
+                breakdown: (days) => P.getGatewayBreakdown(projectId, days),
+                sessions: (days) => P.getGatewaySessions(projectId, days),
+                errors: (days) => P.getGatewayErrors(projectId, days),
+                budgets: () => P.getGatewayBudgets(projectId),
+                setBudget: (input) => P.setGatewayBudget(projectId, input),
+                deleteBudget: (budgetId) => P.deleteGatewayBudget(projectId, budgetId),
+                keys: () => P.getGatewayKeys(projectId),
+                createKey: (name) => P.createGatewayKey(projectId, name),
+                revokeKey: (keyId) => P.revokeGatewayKey(projectId, keyId),
+                /** Run one prompt against up to 6 models side by side (a model-comparison playground). */
+                playground: (prompt, models) => P.runGatewayPlayground(projectId, prompt, models),
+            },
+            /** Slack + email + Meet channel integrations. */
+            channels: {
+                slack: {
+                    installation: () => P.getSlackInstallation(projectId),
+                    connect: (input) => P.connectSlack(projectId, input),
+                    mode: () => P.getSlackMode(projectId),
+                    manifest: () => P.getSlackManifest(projectId),
+                    disconnect: () => P.disconnectSlack(projectId),
+                    /** Download a Slack-hosted file through the server-side proxy (bot token stays server-side). */
+                    getFile: (url) => P.getSlackChannelFile(projectId, url),
+                    /** Upload a file to Slack through the server-side 3-step external-upload proxy. */
+                    uploadFile: (input) => P.uploadSlackChannelFile(projectId, input),
+                },
+                email: {
+                    installation: (connectorSlug) => P.getEmailInstallation(projectId, connectorSlug),
+                    mode: () => P.getEmailMode(projectId),
+                    connect: (input) => P.connectEmail(projectId, input),
+                    disconnect: (connectorSlug) => P.disconnectEmail(projectId, connectorSlug),
+                    updatePolicy: (...a) => P.updateEmailPolicy(projectId, ...a),
+                },
+                meet: {
+                    voices: () => P.getMeetVoices(projectId),
+                    setVoice: (voice) => P.setMeetVoice(projectId, voice),
+                    setBotName: (name) => P.setMeetBotName(projectId, name),
+                    previewVoice: (voiceId) => P.previewMeetVoice(projectId, voiceId),
+                    /** Make the meeting bot speak text (text → ElevenLabs → Recall `output_audio`). */
+                    speak: (botId, text, voice) => P.speakInMeeting(projectId, botId, text, voice),
+                },
+            },
+            /** Project apps/deployments — the `/projects/:id/apps/*` family. */
+            apps: {
+                list: () => P.listProjectApps(projectId),
+                create: (input) => P.createProjectApp(projectId, input),
+                update: (...a) => P.updateProjectApp(projectId, ...a),
+                remove: (slug) => P.deleteProjectApp(projectId, slug),
+                deploy: (slug) => P.deployProjectApp(projectId, slug),
+                stop: (slug) => P.stopProjectApp(projectId, slug),
+                logs: (slug) => P.getProjectAppLogs(projectId, slug),
+                /** @deprecated Use `updateExperimentalFeature('apps', enabled)` — kept for parity with the underlying client. */
+                updateConfig: (input) => P.updateAppsConfig(projectId, input),
+            },
+            /** Toggle an experimental feature (Customize → Settings → Experimental). Pass `enabled: null` to clear the override. */
+            updateExperimentalFeature: (...a) => P.updateExperimentalFeature(projectId, ...a),
+            /** Default model preferences (account/agent/project scope, gateway-resolved). */
+            modelDefaults: {
+                get: () => P.getModelDefaults(projectId),
+                set: (input) => P.setModelDefault(projectId, input),
+                clear: (params) => P.clearModelDefault(projectId, params),
+            },
+            /** Sandbox templates + snapshot builds — Dockerfile/image/warm-pool config, beyond `sandboxHealth`/`sandboxTemplates`. */
+            sandbox: {
+                list: () => P.listProjectSandboxes(projectId),
+                snapshots: () => P.listProjectSnapshots(projectId),
+                rebuildSnapshot: (slug) => P.rebuildProjectSnapshot(projectId, slug),
+                fixWithAgent: () => P.fixSandboxWithAgent(projectId),
+                createTemplate: (input) => P.createSandboxTemplate(projectId, input),
+                updateTemplate: (...a) => P.updateSandboxTemplate(projectId, ...a),
+                removeTemplate: (templateId) => P.deleteSandboxTemplate(projectId, templateId),
+                buildTemplate: (templateId) => P.buildSandboxTemplate(projectId, templateId),
+                /** Pin/clear the per-project sandbox provider (null = follow the platform default). */
+                setProvider: (provider) => P.updateProjectSandboxProvider(projectId, provider),
+            },
+            /** Bind specific secrets + connectors to an agent (the inheritance pyramid's declaration step). */
+            setAgentScope: (...a) => P.setAgentScope(projectId, ...a),
+            session: (sessionId) => session(projectId, sessionId),
+        };
+    }
+    /** Id-bound handle for a single session: lifecycle (REST) + runtime (opencode). */
+    function session(projectId, sessionId) {
+        // Opinionated-action state, scoped to THIS handle. The opencode runtime is
+        // keyed by the OpenCode session id (resolved server-side at /start), NOT the
+        // Kortix `sessionId` — they differ. We resolve+cache it once (including the
+        // resolved runtime URL + sandbox id), and remember a chosen model so `send`
+        // carries it. Every runtime-scoped operation below reads ONLY this cached
+        // record — never the module-global "currently active" runtime — so two
+        // session handles pointed at two different sandboxes never cross wires.
+        let _ready = null;
+        let _model;
+        let _agent;
+        /**
+         * Adopt an already-resolved runtime for THIS (projectId, sessionId) from
+         * the shared session-runtime registry, if this handle hasn't resolved one
+         * itself yet. This is what lets a brand-new `kortix.session(pid, sid)`
+         * handle — e.g. a one-off poll tick, or a handle created independently of
+         * the one that actually drove `/start` — use a session another handle (or
+         * the React `useSession` hook) already brought up, instead of throwing
+         * `SessionNotReadyError` or re-provisioning.
+         */
+        function tryResolveReady() {
+            if (_ready)
+                return _ready;
+            const cached = getSessionRuntime(projectId, sessionId);
+            if (cached)
+                _ready = cached;
+            return _ready;
+        }
+        /**
+         * Make this session's runtime reachable and return its OpenCode session id
+         * (plus this handle's own resolved runtime URL + sandbox id). Idempotent:
+         * adopts the registry entry if another handle already resolved this
+         * session; otherwise `start` provisions/resumes the sandbox (long-poll
+         * until ready) — which itself populates the registry on success — and we
+         * cache the resolved runtime for THIS handle. Also points the app's shared
+         * "current runtime" store there, for React hosts that still read it.
+         */
+        async function ensureReady() {
+            const cached = tryResolveReady();
+            if (cached)
+                return cached;
+            // Dedup concurrent starts for this (projectId, sessionId) — see
+            // `inFlightSessionStarts`'s doc comment. If another call (this handle or
+            // a different one) already kicked off `/start`, ride its result instead
+            // of issuing a second POST.
+            const key = `${projectId}\n${sessionId}`;
+            const inFlight = inFlightSessionStarts.get(key);
+            if (inFlight) {
+                _ready = await inFlight;
+                return _ready;
+            }
+            const startPromise = (async () => {
+                const started = await P.startProjectSession(projectId, sessionId, 30_000);
+                if (!started ||
+                    started.stage !== 'ready' ||
+                    !started.sandbox ||
+                    !started.opencode_session_id) {
+                    throw new ApiError(`Session runtime not ready (stage: ${started?.stage ?? 'unknown'})`, {
+                        code: 'RUNTIME_UNAVAILABLE',
+                    });
+                }
+                const externalId = started.sandbox.external_id;
+                if (!externalId) {
+                    throw new ApiError('Session sandbox has no external_id — cannot resolve its runtime URL', {
+                        code: 'RUNTIME_UNAVAILABLE',
+                    });
+                }
+                const runtimeUrl = getSandboxUrlForExternalId(externalId);
+                // Point the app's shared runtime store at this session too, so React
+                // hosts (which read the global current-runtime) keep working — but this
+                // handle's own operations never read it back, only `_ready` below.
+                setCurrentRuntime(runtimeUrl, externalId);
+                return { opencodeSessionId: started.opencode_session_id, runtimeUrl, sandboxId: externalId };
+            })();
+            inFlightSessionStarts.set(key, startPromise);
+            try {
+                _ready = await startPromise;
+                return _ready;
+            }
+            finally {
+                if (inFlightSessionStarts.get(key) === startPromise) {
+                    inFlightSessionStarts.delete(key);
+                }
+            }
+        }
+        /** Throw `SessionNotReadyError` if neither this handle nor the registry has resolved a runtime yet. */
+        function requireReady(action) {
+            const ready = tryResolveReady();
+            if (!ready)
+                throw new SessionNotReadyError(action);
+            return ready;
+        }
+        /** Clear this handle's cached runtime + the shared registry entry (restart/delete). */
+        function forgetReady() {
+            _ready = null;
+            clearSessionRuntime(projectId, sessionId);
+        }
+        return {
+            // ── lifecycle (Kortix REST) ──────────────────────────────────────────
+            get: (opts) => P.getProjectSession(projectId, sessionId, opts),
+            update: (input) => P.updateProjectSession(projectId, sessionId, input),
+            delete: () => {
+                // A deleted session's sandbox is gone — never let a later handle for
+                // this (projectId, sessionId) resolve a runtime that no longer exists.
+                forgetReady();
+                return P.deleteProjectSession(projectId, sessionId);
+            },
+            start: (...a) => P.startProjectSession(projectId, sessionId, ...a),
+            restart: () => {
+                // Restart may re-provision a DIFFERENT sandbox — a stale cached/
+                // registered runtime would route subsequent calls at a dead box.
+                forgetReady();
+                return P.restartProjectSession(projectId, sessionId);
+            },
+            stop: () => {
+                forgetReady();
+                return P.stopProjectSession(projectId, sessionId);
+            },
+            setSharing: (intent) => P.setProjectSessionSharing(projectId, sessionId, intent),
+            previews: () => P.getSessionPreviewCandidates(projectId, sessionId),
+            commit: (input) => P.commitSessionChanges(projectId, sessionId, input),
+            publicShares: {
+                list: () => P.listSessionPublicShares(projectId, sessionId),
+                create: (...a) => P.createSessionPublicShare(projectId, sessionId, ...a),
+                revoke: (...a) => P.revokeSessionPublicShare(projectId, sessionId, ...a),
+            },
+            /** Per-session audit trail of executor-gated agent actions. */
+            audit: (limit, options) => P.getSessionAudit(projectId, sessionId, limit, options),
+            /** Compact server-side transcript read (text + tool calls, no tool inputs/outputs) — callable with project-scoped session tokens. */
+            transcript: (options) => P.getSessionTranscript(projectId, sessionId, options),
+            /**
+             * Resolve THIS handle's own runtime (idempotent): provisions/resumes the
+             * sandbox (long-poll until ready) and caches the resolved OpenCode session
+             * id + runtime URL + sandbox id for every other call on this handle. Call
+             * this (or `send`/`abort`, which call it internally) before `.runtime`,
+             * `.health()`, `.previewUrl()`, or `.proxyUrl()` — those throw
+             * `SessionNotReadyError` instead of falling back to whatever sandbox
+             * happens to be globally active.
+             */
+            ensureReady,
+            // ── runtime health + preview (the session owns its runtime) ──────────
+            /**
+             * Liveness/readiness of THIS session's runtime (`GET /kortix/health`).
+             * Unlike `.previewUrl()`/`.proxyUrl()`/`.runtime`, this never throws
+             * `SessionNotReadyError` — a health poller (e.g. a header dot ticking
+             * every 15s on a fresh inline handle) needs to be callable BEFORE the
+             * session has ever resolved a runtime. It degrades to the same graceful
+             * `{ status: 0, ok: false }` shape `getSessionHealth` already returns for
+             * "no URL yet", instead of forcing every caller to guard with `ensureReady()`.
+             */
+            health: (init) => getSessionHealth(tryResolveReady()?.runtimeUrl ?? null, init),
+            /** Proxy/preview URL for a port THIS session's runtime exposes. */
+            previewUrl: (port, path = '/') => rewriteLocalhostUrl(port, path, resolvePreviewOptsForSandbox(requireReady('previewUrl').sandboxId)),
+            /** Rewrite a localhost URL the agent printed into a reachable proxy URL. */
+            proxyUrl: (url) => proxyLocalhostUrl(url, resolvePreviewOptsForSandbox(requireReady('proxyUrl').sandboxId)),
+            // ── agent actions (opinionated wrappers over the runtime) ────────────
+            // These do the right thing end-to-end for scripts/non-React hosts: ensure
+            // the runtime is up, resolve the OpenCode session id, and act through a
+            // client bound to THIS handle's own runtime URL (never the module-global
+            // "active" one, so parallel handles on different sandboxes never cross
+            // wires). React hosts use `@kortix/sdk/react` hooks instead, which bind to
+            // the same resolved id reactively (see the white-label reference app).
+            /** Pick the model `send` will use for subsequent prompts (until changed). */
+            setModel: (model) => {
+                _model = model;
+            },
+            /** Pick the agent `send` will use for subsequent prompts (until changed). */
+            setAgent: (agent) => {
+                _agent = agent;
+            },
+            /**
+             * Provision/resume if needed, then send a text prompt to the agent. A
+             * per-call `{ model, agent }` overrides the sticky setModel/setAgent
+             * choices for this message only.
+             */
+            send: async (text, opts) => {
+                const { opencodeSessionId, runtimeUrl } = await ensureReady();
+                const model = opts?.model ?? _model;
+                const agent = opts?.agent ?? _agent;
+                return getClientForUrl(runtimeUrl).session.prompt({
+                    sessionID: opencodeSessionId,
+                    parts: [{ type: 'text', text }],
+                    ...(model ? { model } : {}),
+                    ...(agent ? { agent } : {}),
+                });
+            },
+            /** Abort the agent's current run in this session. */
+            abort: async () => {
+                const { opencodeSessionId, runtimeUrl } = await ensureReady();
+                return getClientForUrl(runtimeUrl).session.abort({ sessionID: opencodeSessionId });
+            },
+            /**
+             * Live SSE stream of THIS session's runtime events (message/part
+             * updates, session status, permissions/questions, lsp diagnostics, …).
+             * A thin facade over the framework-free `openEventStream` primitive
+             * (`@kortix/sdk`'s `openEventStream`, also used verbatim by
+             * `@kortix/sdk/react`'s `useOpenCodeEventStream`): resolves THIS
+             * handle's own runtime first (`ensureReady()`), then connects a client
+             * bound to that runtime URL — never the module-global "active" one, so
+             * two session handles on two different sandboxes never cross wires.
+             * Framework-free — safe to call from a server-side "Kortix as a
+             * Backend" wrapper (Node/Bun), a worker, a CLI, or any non-React host.
+             *
+             * Handles connect/reconnect/backoff, a 15s heartbeat watchdog, and
+             * event coalescing internally. Call `handle.close()` to stop.
+             *
+             *   const handle = await session.stream({ onEvent: (e) => console.log(e) });
+             *   // later
+             *   handle.close();
+             */
+            stream: async (opts) => {
+                const { runtimeUrl } = await ensureReady();
+                return openEventStream({
+                    client: getClientForUrl(runtimeUrl),
+                    onEvent: opts.onEvent,
+                    onGapRehydrate: opts.onGapRehydrate,
+                    signal: opts.signal,
+                });
+            },
+            // ── runtime (opencode v2, THIS session's own sandbox) ────────────────
+            // The typed opencode client, reached ONLY through the SDK. The host never
+            // imports `@opencode-ai/sdk`. Opinionated wrappers (prompt/abort/setModel
+            // with server-owned side-effects) layer on top of this as they land.
+            get runtime() {
+                return getClientForUrl(requireReady('runtime').runtimeUrl);
+            },
+            /**
+             * Workspace file operations (daemon `/file` + `/find`) bound to THIS
+             * session's own resolved runtime — never the module-global "active"
+             * sandbox the top-level `@kortix/sdk` `files` export follows. Fixes a
+             * cross-session bleed: a host juggling multiple open sessions (e.g. a
+             * server wrapping several concurrent agent sessions) that called the
+             * global `files.list()` while a DIFFERENT session was "active" would
+             * silently read/write the wrong sandbox. Each call here auto-provisions
+             * via `ensureReady()` (same as `send`/`abort`/`stream`), then runs
+             * against this handle's own runtime URL. Same 12-op surface as the
+             * global `files` namespace, built from the same parameterized core
+             * (`@kortix/sdk/files`'s exports all take an optional trailing
+             * `baseUrl` — this just always supplies THIS session's).
+             */
+            files: {
+                list: async (dirPath) => F.listFiles(dirPath, (await ensureReady()).runtimeUrl),
+                read: async (filePath) => F.readFile(filePath, (await ensureReady()).runtimeUrl),
+                readBlob: async (filePath) => F.readBlob(filePath, (await ensureReady()).runtimeUrl),
+                status: async () => F.getFileStatus((await ensureReady()).runtimeUrl),
+                findFiles: async (query, options) => F.findFiles(query, options, (await ensureReady()).runtimeUrl),
+                findText: async (pattern) => F.findText(pattern, (await ensureReady()).runtimeUrl),
+                upload: async (file, targetPath, filename) => F.uploadFile(file, targetPath, filename, (await ensureReady()).runtimeUrl),
+                create: async (filePath) => F.createFile(filePath, (await ensureReady()).runtimeUrl),
+                copy: async (sourcePath, destPath) => F.copyFile(sourcePath, destPath, (await ensureReady()).runtimeUrl),
+                remove: async (filePath) => F.deleteFile(filePath, (await ensureReady()).runtimeUrl),
+                mkdir: async (dirPath) => F.mkdir(dirPath, (await ensureReady()).runtimeUrl),
+                rename: async (from, to) => F.renameFile(from, to, (await ensureReady()).runtimeUrl),
+            },
+        };
+    }
+    return {
+        /** The platform config in effect (for diagnostics). */
+        config,
+        accounts,
+        /** Account-invite lifecycle reached by invite token alone (accept/decline/describe). */
+        accountInvites,
+        projects,
+        project,
+        session,
+        /** GitHub App installation + repository linking (account-scoped). */
+        github,
+        /** Billing read surface — credits/subscription/tier/transactions (not project-scoped). */
+        billing,
+        /** Public share links for a sandbox port (`/v1/p/share`, sandbox-scoped). */
+        sandboxShares,
+        /** Speech-to-text transcription (`/transcription` — not project-scoped). */
+        transcribe: P.transcribeAudio,
+        /** Deployment-wide Pipedream/easy-connect availability flag (not project-scoped). */
+        connectStatus,
+        /** Public marketplace catalog browse + sources (`/v1/marketplace/*`, not project-scoped). */
+        marketplace,
+        /** The pasted-API-key UX check — `GET /accounts/me`, never throws. */
+        validateToken: P.validateToken,
+        /** Escape hatch: the typed opencode client for the active sandbox. */
+        runtime,
+    };
+}
+//# sourceMappingURL=kortix.js.map