@vibesdotdev/code-sessions 0.0.0-stage → 1.0.0-rc.1

package/dist/api/code-sessions.api-client.impl.js

@@ -0,0 +1,852 @@
+/**
+ * Code Sessions API Client — universal HTTP implementation.
+ *
+ * Cross-origin HTTP client against `${platformOrigin}/api/code-sessions/*`.
+ * Loaded in cli/browser/sveltekit/cloud scopes by the code-sessions plugin
+ * loader.
+ *
+ * Origin: explicit override, else the `platform` infra/service catalog origin.
+ *
+ * Authentication: `Authorization: Bearer <user-jwt>` (cli/ssr/cross-app), or
+ * same-origin `credentials: 'include'` in the browser. SSR never forwards a
+ * request cookie as a credential.
+ *
+ * Failures are typed (`CapabilityError` code and reason): a platform error
+ * status is a `CodeSessionsApiError` whose body is a bounded, redacted excerpt;
+ * an unreachable platform, an unreadable or malformed answer and every caller
+ * refusal carry their own reason. Every success body is parsed at this
+ * boundary before a caller sees it. Diagnostics go through the handed
+ * runtime's logger only.
+ *
+ * NEVER logs the bearer token.
+ */
+import { BaseRuntimeClient } from '@vibesdotdev/kernel/client';
+import { CapabilityError, CaughtFailureSchema, isCapabilityError } from '@vibesdotdev/kernel';
+import { serviceOrigin } from '@vibesdotdev/infra-core/service';
+import { resolveCallerBearer } from '@vibesdotdev/auth/caller-bearer';
+import { filterCodeExecutionHosts } from '@vibesdotdev/platform/hosts/schemas';
+import { AgentCodeSessionDescriptorSchema, resolveCodeSession } from '@vibesdotdev/agent-execution/code-session';
+import { getLogger } from '@vibesdotdev/logging';
+import { requestBoundary, CodeSessionCreateSchema, RunCommandRequestSchema, PushBranchRequestSchema, CreatePullRequestRequestSchema, SessionIdSchema, CodeSessionLinkSchema, ServiceAssertionSchema, HttpOptionsSchema, ListOptionsSchema, StartOptionsRequestSchema } from "../schemas/requests.js";
+import { resolveSessionCapability } from "../capability.js";
+import { attempt } from "../svelte/outcome.js";
+import { codeSessionPreparationSchema } from "../config/preparation.js";
+import { CodeSessionListEnvelopeSchema, CodeSessionRecordEnvelopeSchema, CreatePullRequestResponseSchema, PreparationEnvelopeSchema, PushBranchResponseSchema, RunCommandResponseSchema } from "./code-sessions.api-client.schemas.js";
+import { CodeSessionsApiError, CodeSessionsNotSignedInError } from "./code-sessions.api-client.types.js";
+const LOGGER_ID = 'code-sessions:api-client';
+const SERVICE_PREPARE_ROUTE = '/api/internal/code-sessions/prepare';
+function withLink(links, link) {
+    return [
+        ...(links ?? []).filter((candidate) => candidate.kind !== link.kind || candidate.id !== link.id || candidate.source !== link.source),
+        link
+    ];
+}
+/** True for the one resolution failure that means "no signed-in caller". */
+function isNotSignedIn(failure) {
+    return isCapabilityError(failure) && failure.code === 'AUTH_REQUIRED' && failure.reason === 'not-signed-in';
+}
+async function resolveOrigin(runtime) {
+    return (await serviceOrigin(runtime, 'platform')).replace(/\/$/, '');
+}
+/**
+ * Whether a browser runtime may ride its page's same-origin Platform session
+ * cookies. Only a browser surface does, and never the packaged Desktop
+ * renderer (`cef`), which renders from `file://` with neither a same-origin
+ * Platform session nor permission to probe the network speculatively. Cloud
+ * functionality is admitted there later through an explicit bearer-backed
+ * runtime client; local sessions remain independently available offline.
+ */
+export function canUseBrowserSessionCookies(scope) {
+    return scope.surface === 'browser' && scope.qualifiers.cef !== true;
+}
+/** One plain record of the caller's headers, names as given (a `Headers` instance reads lower-cased). */
+function headersInitToRecord(headers) {
+    if (headers instanceof Headers)
+        return Object.fromEntries(headers);
+    if (Array.isArray(headers))
+        return Object.fromEntries(headers.map(([name, value]) => [name, value]));
+    return Object.fromEntries(Object.entries(headers ?? {}));
+}
+function hasHeader(record, name) {
+    const lower = name.toLowerCase();
+    return Object.keys(record).some((key) => key.toLowerCase() === lower);
+}
+function omitCookieHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => key.toLowerCase() !== 'cookie'));
+}
+/** Last layer wins; names are matched case-insensitively so `Authorization` replaces `authorization`. */
+function mergeHeaders(...layers) {
+    const byName = new Map();
+    for (const layer of layers) {
+        for (const [key, value] of Object.entries(layer ?? {}))
+            byName.set(key.toLowerCase(), [key, value]);
+    }
+    return Object.fromEntries(byName.values());
+}
+function annotate(record) {
+    return {
+        ...record,
+        capability: resolveSessionCapability(record.hostTarget),
+        execution: 'platform'
+    };
+}
+function workspaceName(path) {
+    return (path
+        .replace(/[\\/]+$/, '')
+        .split(/[\\/]/)
+        .pop() || path);
+}
+function localRecordFromHandle(handle) {
+    const timestamp = handle.createdAt ?? new Date().toISOString();
+    return {
+        sessionId: handle.sessionId,
+        repositoryId: handle.repositoryId ?? null,
+        repositoryName: handle.workspaceOwnership === 'borrowed' ? workspaceName(handle.workspacePath) : null,
+        ephemeral: handle.ephemeral,
+        hostTarget: handle.hostTarget,
+        runtimeConfig: {},
+        status: 'active',
+        previewUrl: handle.previewUrl ?? null,
+        workspacePath: handle.workspacePath,
+        checkoutRef: null,
+        ownerType: 'local',
+        ownerId: null,
+        createdAt: timestamp,
+        lastActivityAt: timestamp,
+        capability: 'interactive',
+        execution: 'local'
+    };
+}
+function targetFromDescriptor(descriptor) {
+    const hostTarget = descriptor.hostTarget;
+    if (!hostTarget)
+        return null;
+    const execution = hostTarget.kind === 'host' && hostTarget.hostId === 'local' ? 'local' : 'platform';
+    return {
+        id: `${execution}:${descriptor.id}`,
+        name: execution === 'local'
+            ? 'This machine'
+            : hostTarget.kind === 'cloud'
+                ? 'Vibes cloud sandbox'
+                : descriptor.name,
+        description: execution === 'local'
+            ? 'Runs in the current TUI process on this machine.'
+            : (descriptor.description ?? `Runs with ${descriptor.name}.`),
+        hostTarget,
+        execution
+    };
+}
+/** A refused caller input: `INVALID_INPUT` with its reason. */
+function invalidInput(message, reason) {
+    return new CapabilityError(message, 'INVALID_INPUT', { reason });
+}
+/**
+ * Runtime port `VibesRuntime` (Runtime SPEC `./client`): the caller bearer
+ * reads `declaredScope`, which `RuntimeRef` does not carry, directly and
+ * through auth's `resolveCallerBearer` port.
+ */
+export class CodeSessionsApiClientConsumer extends BaseRuntimeClient {
+    originOverride = null;
+    tokenOverride = undefined;
+    httpOverrides = {};
+    serviceAssertion;
+    localSessions = new Map();
+    localSessionInFlight = null;
+    startOptionsInFlight = null;
+    constructor(descriptor = { id: 'code-sessions', kind: 'runtime/client' }, context, runtime) {
+        super(descriptor, context, runtime);
+    }
+    configureHttp(value) {
+        return this.configureHttpValidated(requestBoundary(HttpOptionsSchema).parse(value));
+    }
+    configureHttpValidated(overrides) {
+        if (overrides.origin !== undefined) {
+            this.originOverride = overrides.origin.replace(/\/$/, '');
+        }
+        if ('token' in overrides) {
+            this.tokenOverride = overrides.token ?? null;
+        }
+        this.httpOverrides = {
+            fetch: overrides.fetch,
+            headers: overrides.headers,
+            credentials: overrides.credentials
+        };
+    }
+    /** A request-scoped copy of this client on the same runtime. */
+    fork(overrides) {
+        const forked = new CodeSessionsApiClientConsumer(this.descriptor, undefined, this.runtime);
+        // Read the configured origin only when the caller does not supply it: an
+        // explicit value never depends on the host's environment. An explicit
+        // token (the caller's or this client's) carries over; otherwise the fork
+        // resolves the caller's bearer itself, per request.
+        const next = { ...overrides };
+        if (next.origin === undefined && this.originOverride !== null)
+            next.origin = this.originOverride;
+        if (!('token' in overrides) && this.tokenOverride !== undefined)
+            next.token = this.tokenOverride;
+        if (this.serviceAssertion) {
+            next.fetch ??= this.httpOverrides.fetch;
+            next.token = null;
+            next.headers = {};
+            next.credentials = 'omit';
+        }
+        forked.configureHttp(next);
+        forked.serviceAssertion = this.serviceAssertion;
+        return forked;
+    }
+    forRequest(value) {
+        return this.fork(requestBoundary(HttpOptionsSchema).parse(value));
+    }
+    forServiceRequest(input) {
+        return this.forServiceRequestValidated(requestBoundary(ServiceAssertionSchema, 'service-identity-invalid').parse(input));
+    }
+    forServiceRequestValidated(assertion) {
+        const { userId, organizationId } = assertion;
+        const forked = this.fork({
+            token: null,
+            headers: {},
+            credentials: 'omit',
+            fetch: this.httpOverrides.fetch
+        });
+        const serviceAssertion = { userId };
+        if (organizationId)
+            serviceAssertion.organizationId = organizationId;
+        forked.serviceAssertion = serviceAssertion;
+        return forked;
+    }
+    async prepare(input) {
+        return this.prepareValidated(requestBoundary(codeSessionPreparationSchema, 'preparation-input-invalid').parse(input));
+    }
+    async prepareValidated(data) {
+        if (!data.repositoryId && !data.createRepositoryIfMissing) {
+            throw invalidInput('Choose a repository or allow this Chat to create one.', 'repository-required');
+        }
+        const route = this.serviceAssertion ? SERVICE_PREPARE_ROUTE : '/api/code-sessions/prepare';
+        const payload = await this.requestJson('POST', route, PreparationEnvelopeSchema, data);
+        return payload.result;
+    }
+    /**
+     * True when a bearer is configured or the caller's bearer resolves. A
+     * signed-out caller is `false`; any other resolution failure propagates.
+     */
+    async isAuthenticated() {
+        return (await this.signedInBearer()) !== null;
+    }
+    noSessionHint() {
+        return new CodeSessionsNotSignedInError().message;
+    }
+    async canAttemptPlatformRequest() {
+        if (await this.signedInBearer())
+            return true;
+        // An explicitly configured origin marks an HTTP/request-scoped client.
+        // Its transport admission never depends on an ambient page global.
+        if (this.originOverride !== null)
+            return true;
+        return canUseBrowserSessionCookies(this.runtime.declaredScope);
+    }
+    async localSession() {
+        this.localSessionInFlight ??= this.resolveLocalSession();
+        return this.localSessionInFlight;
+    }
+    async resolveLocalSession() {
+        // Confirmed absence: a runtime that registers no code-session kind has no local plane.
+        if (!this.runtime.hasKind('agent/code-session'))
+            return null;
+        const resolved = await attempt(() => resolveCodeSession(this.runtime, { requiredHostTargetKind: 'host' }));
+        if (resolved.ok)
+            return resolved.value;
+        // Declared-optional: no resolvable local execution target means no local session.
+        const logger = getLogger(LOGGER_ID, this.runtime);
+        logger.warn('local code session unavailable', { error: resolved.failure });
+        return null;
+    }
+    async platformClient() {
+        if (!(await this.canAttemptPlatformRequest()))
+            return null;
+        const resolved = await attempt(() => this.runtime.query('runtime/client').withId('platform').resolve());
+        if (!resolved.ok) {
+            // Declared-optional: the platform client is degraded (`degraded: ['platform']`), not fatal.
+            const logger = getLogger(LOGGER_ID, this.runtime);
+            logger.warn('platform client unavailable', { error: resolved.failure });
+            return null;
+        }
+        const base = resolved.value;
+        const token = await this.signedInBearer();
+        const overrideHeaders = omitCookieHeaders(headersInitToRecord(this.httpOverrides.headers));
+        const bearer = {};
+        if (token && !hasHeader(overrideHeaders, 'authorization'))
+            bearer.Authorization = `Bearer ${token}`;
+        return base.forRequest({
+            origin: await this.resolveConfiguredOrigin(),
+            fetch: this.httpOverrides.fetch,
+            headers: mergeHeaders(bearer, overrideHeaders)
+        });
+    }
+    async rememberLocalHandle(handle, session) {
+        const impl = session ?? (await this.localSession());
+        if (!impl)
+            return null;
+        const projected = localRecordFromHandle(handle);
+        const existingLinks = this.localSessions.get(handle.sessionId)?.record.links;
+        const entry = {
+            record: existingLinks ? { ...projected, links: existingLinks } : projected,
+            session: impl
+        };
+        this.localSessions.set(handle.sessionId, entry);
+        return entry;
+    }
+    async discoverLocalSessions() {
+        const session = await this.localSession();
+        if (!session?.discover)
+            return;
+        for (const handle of await session.discover()) {
+            await this.rememberLocalHandle(handle, session);
+        }
+    }
+    async findLocalSession(sessionId) {
+        const known = this.localSessions.get(sessionId);
+        if (known)
+            return known;
+        const session = await this.localSession();
+        if (!session)
+            return null;
+        const attached = await attempt(() => session.attach(sessionId));
+        if (!attached.ok) {
+            // A local implementation that cannot attach an id has answered
+            // "not mine" — a MISS, never a failure of the lookup. Implementations
+            // word that refusal differently (the relay impl says `'<id>' is not a
+            // relay session id`), so a text match would send every cloud session
+            // viewed on a relay-resolving surface into a throw. The platform is the
+            // authoritative store for a session this client did not mint locally,
+            // so the miss falls through to it; the decline is reported here once.
+            const logger = getLogger(LOGGER_ID, this.runtime);
+            logger.warn('local attach declined; consulting the platform', { sessionId, error: attached.failure });
+            return null;
+        }
+        return this.rememberLocalHandle(attached.value, session);
+    }
+    /**
+     * The host's workspace, offered as the "current workspace" source. A host
+     * that binds no workspace (C1) offers none; any other failure propagates.
+     */
+    async runtimeWorkspacePath() {
+        try {
+            return await this.runtime.context('runtime/workspace-path');
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            // Confirmed absence of exactly this context, and only its unbound form.
+            if (CapabilityError.isAbsenceOf(failure, 'context', 'runtime/workspace-path') &&
+                isCapabilityError(failure) &&
+                failure.reason === 'workspace-unbound') {
+                return null;
+            }
+            throw failure;
+        }
+    }
+    async resolveStartTarget(descriptor) {
+        const resolved = await attempt(() => this.runtime.query('agent/code-session').withId(descriptor.id).resolve());
+        if (resolved.ok)
+            return true;
+        // Declared-optional: an unresolvable target is omitted from the options.
+        const logger = getLogger(LOGGER_ID, this.runtime);
+        logger.warn('code-session target did not resolve', { id: descriptor.id, error: resolved.failure });
+        return false;
+    }
+    async runtimeStartTargets() {
+        if (!this.runtime.hasKind('agent/code-session'))
+            return [];
+        const byExecutionTarget = new Map();
+        for (const registered of this.runtime.query('agent/code-session').descriptors()) {
+            const parsed = AgentCodeSessionDescriptorSchema.safeParse(registered);
+            if (!parsed.success) {
+                const logger = getLogger(LOGGER_ID, this.runtime);
+                logger.warn('code-session target descriptor is malformed; omitted', { error: parsed.error });
+                continue;
+            }
+            const descriptor = parsed.data;
+            if (descriptor.enabled === false)
+                continue;
+            const target = targetFromDescriptor(descriptor);
+            if (!target)
+                continue;
+            if (!(await this.resolveStartTarget(descriptor)))
+                continue;
+            const key = `${target.execution}:${target.hostTarget.kind}:${target.hostTarget.kind === 'host' ? target.hostTarget.hostId : 'cloud'}`;
+            if (!byExecutionTarget.has(key))
+                byExecutionTarget.set(key, target);
+        }
+        return [...byExecutionTarget.values()];
+    }
+    async getStartOptions(value) {
+        this.assertStandardAccess();
+        return this.getStartOptionsValidated(requestBoundary(StartOptionsRequestSchema).parse(value));
+    }
+    async getStartOptionsValidated(options) {
+        if (!options.force && this.startOptionsInFlight)
+            return this.startOptionsInFlight;
+        const load = async () => {
+            const degraded = [];
+            const targets = await this.runtimeStartTargets();
+            if (targets.length === 0)
+                degraded.push('runtime');
+            const platform = await this.platformClient();
+            let repositories = [];
+            if (await this.canAttemptPlatformRequest()) {
+                if (!platform) {
+                    degraded.push('platform');
+                }
+                else {
+                    const [hostsResult, repositoriesResult] = await Promise.allSettled([
+                        platform.hosts.list({ status: 'active', limit: 200, offset: 0 }),
+                        platform.repositories.list({ status: 'active', limit: 100, offset: 0 })
+                    ]);
+                    const logger = getLogger(LOGGER_ID, this.runtime);
+                    if (hostsResult.status === 'fulfilled') {
+                        for (const host of filterCodeExecutionHosts(hostsResult.value.results ?? [])) {
+                            const id = `platform:host:${host.hostId}`;
+                            if (targets.some((target) => target.id === id))
+                                continue;
+                            targets.push({
+                                id,
+                                name: host.name?.trim() || host.hostId,
+                                description: [
+                                    host.relayReachable ? 'Connected fleet host' : 'Active fleet host',
+                                    host.region
+                                ]
+                                    .filter(Boolean)
+                                    .join(' · '),
+                                hostTarget: { kind: 'host', hostId: host.hostId },
+                                execution: 'platform'
+                            });
+                        }
+                    }
+                    else {
+                        logger.warn('platform host list failed', { error: hostsResult.reason });
+                        degraded.push('hosts');
+                    }
+                    if (repositoriesResult.status === 'fulfilled') {
+                        repositories = repositoriesResult.value.results ?? [];
+                    }
+                    else {
+                        logger.warn('platform repository list failed', { error: repositoriesResult.reason });
+                        degraded.push('repositories');
+                    }
+                }
+            }
+            const localTargetIds = targets
+                .filter((target) => target.execution === 'local')
+                .map((target) => target.id);
+            const platformTargetIds = targets
+                .filter((target) => target.execution === 'platform')
+                .map((target) => target.id);
+            const workspacePath = await this.runtimeWorkspacePath();
+            const sources = [];
+            if (workspacePath && localTargetIds.length > 0) {
+                sources.push({
+                    id: 'workspace:current',
+                    name: workspaceName(workspacePath),
+                    description: `Current directory · ${workspacePath}`,
+                    compatibleTargetIds: localTargetIds,
+                    workspacePath
+                });
+            }
+            if (targets.length > 0) {
+                sources.push({
+                    id: 'workspace:ephemeral',
+                    name: 'New empty workspace',
+                    description: 'Creates a session-owned temporary Git workspace.',
+                    compatibleTargetIds: targets.map((target) => target.id),
+                    ephemeral: true
+                });
+            }
+            for (const repository of repositories) {
+                if (repository.status && repository.status !== 'active')
+                    continue;
+                sources.push({
+                    id: `repository:${repository.id}`,
+                    name: repository.name?.trim() || repository.id,
+                    description: 'Account repository',
+                    compatibleTargetIds: platformTargetIds,
+                    repositoryId: repository.id
+                });
+            }
+            const defaultTargetId = localTargetIds[0] ?? targets[0]?.id ?? null;
+            const defaultSourceId = sources.find((source) => defaultTargetId ? source.compatibleTargetIds.includes(defaultTargetId) : false)?.id ?? null;
+            return { targets, sources, defaultTargetId, defaultSourceId, degraded };
+        };
+        const pending = load().finally(() => {
+            if (this.startOptionsInFlight === pending)
+                this.startOptionsInFlight = null;
+        });
+        this.startOptionsInFlight = pending;
+        return pending;
+    }
+    async resolveConfiguredOrigin() {
+        if (this.originOverride)
+            return this.originOverride;
+        return resolveOrigin(this.runtime);
+    }
+    /**
+     * An explicit token wins; a browser host presents none (same-origin
+     * credentials); otherwise the caller's bearer from auth's `resolveCallerBearer`.
+     */
+    async resolveConfiguredToken() {
+        if (this.tokenOverride !== undefined)
+            return this.tokenOverride;
+        if (this.runtime.declaredScope.surface === 'browser')
+            return null;
+        return resolveCallerBearer(this.runtime);
+    }
+    /**
+     * The caller's bearer: a token, `null` when none is configured (a browser or
+     * anonymous caller), or the typed signed-out refusal carrying the resolution
+     * failure. Any other resolution failure propagates.
+     */
+    async callerBearer() {
+        try {
+            return await this.resolveConfiguredToken();
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            if (isNotSignedIn(failure))
+                return new CodeSessionsNotSignedInError({ cause: failure });
+            throw failure;
+        }
+    }
+    /** The configured bearer, `null` when the caller presents none or is signed out. */
+    async signedInBearer() {
+        const bearer = await this.callerBearer();
+        return bearer instanceof CodeSessionsNotSignedInError ? null : bearer;
+    }
+    requestCredentials() {
+        // A browser rides its session cookies automatically; CLI and SSR use a bearer.
+        if (this.httpOverrides.credentials)
+            return this.httpOverrides.credentials;
+        return this.runtime.declaredScope.surface === 'browser' ? 'include' : undefined;
+    }
+    /** Refuse before resolving either execution plane or dispatching a request. */
+    assertStandardAccess() {
+        if (this.serviceAssertion) {
+            throw invalidInput('Service code-session clients support owner-verified preparation only.', 'service-client-preparation-only');
+        }
+    }
+    /**
+     * One request to the platform: the response when it is ok, `null` when a
+     * failed status is the confirmed absence `absence` declares, otherwise a typed
+     * refusal. The bearer and service credential never reach a failure's text.
+     */
+    async send(method, path, body, absence = {}) {
+        if (path !== SERVICE_PREPARE_ROUTE)
+            this.assertStandardAccess();
+        const url = `${await this.resolveConfiguredOrigin()}${path}`;
+        const fetchFn = this.httpOverrides.fetch ?? fetch;
+        const credentialValues = [];
+        const headers = mergeHeaders({ Accept: 'application/json' }, body !== undefined ? { 'Content-Type': 'application/json' } : undefined, omitCookieHeaders(headersInitToRecord(this.httpOverrides.headers)));
+        // A signed-out caller sends no bearer; a configured origin may still
+        // carry the request (`canAttemptPlatformRequest`). An explicit
+        // Authorization on the request fork is left intact.
+        const token = await this.signedInBearer();
+        if (token)
+            credentialValues.push(token);
+        if (token && !hasHeader(headers, 'authorization'))
+            headers.Authorization = `Bearer ${token}`;
+        if (this.serviceAssertion) {
+            // The service credential comes only from the host's secrets/store (RC05);
+            // a typed failure (not set, no store, store failed) propagates as-is.
+            const service = await this.runtime.resolveCredential({ source: 'secret', key: 'VIBES_INTERNAL_SERVICE_TOKEN' });
+            if (!service.ok)
+                throw service.error;
+            credentialValues.push(service.value);
+            headers.Authorization = `Bearer ${service.value}`;
+            headers['x-vibes-user-id'] = this.serviceAssertion.userId;
+            if (this.serviceAssertion.organizationId) {
+                headers['x-vibes-organization-id'] = this.serviceAssertion.organizationId;
+            }
+        }
+        const init = { method, headers };
+        const credentials = this.requestCredentials();
+        if (credentials)
+            init.credentials = credentials;
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        let res;
+        try {
+            res = await fetchFn(url, init);
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            if (failure instanceof Error && failure.name === 'AbortError') {
+                throw new CapabilityError('The code-sessions request was cancelled.', 'CANCELLED', {
+                    reason: 'request-aborted',
+                    details: { method },
+                    cause: failure
+                });
+            }
+            // The URL (origin, path, any query) stays out of the message; the transport error rides as cause.
+            throw new CapabilityError('The platform could not be reached.', 'UNAVAILABLE', {
+                reason: 'platform-unreachable',
+                details: { method },
+                cause: failure
+            });
+        }
+        if (res.ok)
+            return res;
+        if (res.status === 401) {
+            if (absence.signedOutAsAbsent)
+                return null;
+            throw new CodeSessionsNotSignedInError();
+        }
+        if (res.status === 404 && absence.absentOn404)
+            return null;
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (error) {
+            throw new CapabilityError('The platform error response could not be read.', 'UNAVAILABLE', {
+                reason: 'platform-body-unreadable',
+                details: { status: res.status, method },
+                cause: CaughtFailureSchema.parse(error)
+            });
+        }
+        throw new CodeSessionsApiError(`code-sessions ${method} ${path} → ${res.status}`, res.status, text, false, {
+            method,
+            path,
+            redactions: credentialValues
+        });
+    }
+    /** The response body parsed by `schema`, or the typed `platform-response-invalid` refusal. */
+    async readJson(res, schema, method) {
+        let payload;
+        try {
+            payload = await res.json();
+        }
+        catch (error) {
+            throw new CapabilityError('The platform returned a response that is not JSON.', 'INTERNAL', {
+                reason: 'platform-response-invalid',
+                details: { status: res.status, method },
+                cause: CaughtFailureSchema.parse(error)
+            });
+        }
+        const parsed = schema.safeParse(payload);
+        if (!parsed.success) {
+            throw new CapabilityError('The platform returned an unexpected response.', 'INTERNAL', {
+                reason: 'platform-response-invalid',
+                details: { status: res.status, method },
+            });
+        }
+        return parsed.data;
+    }
+    async requestJson(method, path, schema, body) {
+        const res = await this.send(method, path, body);
+        if (!res) {
+            throw new CapabilityError('The platform answered without a response.', 'INTERNAL', {
+                reason: 'platform-response-invalid',
+                details: { method }
+            });
+        }
+        return this.readJson(res, schema, method);
+    }
+    async requestJsonUnlessAbsent(method, path, schema, absence) {
+        const res = await this.send(method, path, undefined, absence);
+        return res ? this.readJson(res, schema, method) : null;
+    }
+    async list(value) {
+        this.assertStandardAccess();
+        return this.listValidated(requestBoundary(ListOptionsSchema).parse(value));
+    }
+    async listValidated(options) {
+        await this.discoverLocalSessions();
+        const local = [...this.localSessions.values()]
+            .map((entry) => entry.record)
+            .filter((record) => !options?.status || record.status === options.status);
+        if (!(await this.canAttemptPlatformRequest()))
+            return local;
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set('status', options.status);
+        const qs = params.toString();
+        const path = `/api/code-sessions${qs ? `?${qs}` : ''}`;
+        const platform = await attempt(() => this.requestJsonUnlessAbsent('GET', path, CodeSessionListEnvelopeSchema, { signedOutAsAbsent: true }));
+        if (!platform.ok) {
+            // The local execution plane is independently useful. A cloud transport
+            // failure must not hide sessions already running on this machine; callers
+            // with no local records still receive the platform failure.
+            if (local.length === 0)
+                throw platform.failure;
+            const logger = getLogger(LOGGER_ID, this.runtime);
+            logger.warn('platform code-session list failed; showing local sessions only', { error: platform.failure });
+            return local;
+        }
+        if (!platform.value)
+            return local;
+        return [...local, ...platform.value.results.map(annotate)];
+    }
+    async get(value) {
+        this.assertStandardAccess();
+        const sessionId = requestBoundary(SessionIdSchema).parse(value);
+        const local = await this.findLocalSession(sessionId);
+        if (local)
+            return local.record;
+        return this.getOwned(sessionId);
+    }
+    /**
+     * PLATFORM-AUTHORITATIVE read: never consults the local plane.
+     *
+     * `get()` is local-plane-first, and the local relay implementation attaches
+     * any well-formed relay id via the service credential WITHOUT an ownership
+     * check — fine for a surface reading its own machine, but never evidence of
+     * ownership. Authorization decisions (e.g. binding an MCP caller to a code
+     * session) MUST use this method: the platform's `/api/code-sessions/[id]`
+     * route is owner-scoped and answers 404 for a foreign session. Fails closed
+     * with null only for absence or signed-out callers; transport failures propagate.
+     */
+    async getOwned(value) {
+        this.assertStandardAccess();
+        return this.getOwnedValidated(requestBoundary(SessionIdSchema).parse(value));
+    }
+    async getOwnedValidated(sessionId) {
+        if (!(await this.canAttemptPlatformRequest()))
+            return null;
+        const payload = await this.requestJsonUnlessAbsent('GET', `/api/code-sessions/${encodeURIComponent(sessionId)}`, CodeSessionRecordEnvelopeSchema, { absentOn404: true, signedOutAsAbsent: true });
+        return payload ? annotate(payload.result) : null;
+    }
+    async create(value) {
+        this.assertStandardAccess();
+        return this.createValidated(requestBoundary(CodeSessionCreateSchema).parse(value));
+    }
+    async createValidated(input) {
+        if (input.execution === 'local') {
+            const hostTarget = input.hostTarget ?? { kind: 'host', hostId: 'local' };
+            if (hostTarget.kind !== 'host' || hostTarget.hostId !== 'local') {
+                throw invalidInput('Local code sessions require hostTarget {kind:"host",hostId:"local"}.', 'local-host-target-required');
+            }
+            const session = await this.localSession();
+            if (!session) {
+                throw new CapabilityError('No local code-session implementation is registered.', 'NOT_FOUND', {
+                    reason: 'local-implementation-unregistered'
+                });
+            }
+            const initialize = { hostTarget };
+            if (input.sessionId)
+                initialize.sessionId = input.sessionId;
+            if (input.workspacePath)
+                initialize.workspacePath = input.workspacePath;
+            if (input.ephemeral)
+                initialize.ephemeral = true;
+            if (input.checkoutRef)
+                initialize.checkoutRef = input.checkoutRef;
+            if (input.runtimeConfig)
+                initialize.runtimeConfig = input.runtimeConfig;
+            if (input.initialEnv)
+                initialize.initialEnv = input.initialEnv;
+            if (input.exposedPorts)
+                initialize.exposedPorts = input.exposedPorts;
+            const handle = await session.initialize(initialize);
+            const record = {
+                ...localRecordFromHandle(handle),
+                runtimeConfig: input.runtimeConfig ?? {},
+                checkoutRef: input.checkoutRef ?? null
+            };
+            if (input.links)
+                record.links = input.links;
+            this.localSessions.set(record.sessionId, { record, session });
+            return record;
+        }
+        const { execution: _execution, ...platformInput } = input;
+        const payload = await this.requestJson('POST', '/api/code-sessions', CodeSessionRecordEnvelopeSchema, platformInput);
+        return annotate(payload.result);
+    }
+    async link(value, relationship) {
+        this.assertStandardAccess();
+        return this.linkValidated(requestBoundary(SessionIdSchema).parse(value), requestBoundary(CodeSessionLinkSchema).parse(relationship));
+    }
+    async linkValidated(sessionId, link) {
+        const local = this.localSessions.get(sessionId);
+        if (local) {
+            local.record = { ...local.record, links: withLink(local.record.links, link) };
+            return local.record;
+        }
+        const payload = await this.requestJson('PATCH', `/api/code-sessions/${encodeURIComponent(sessionId)}`, CodeSessionRecordEnvelopeSchema, { link });
+        return annotate(payload.result);
+    }
+    async run(value) {
+        this.assertStandardAccess();
+        const input = requestBoundary(RunCommandRequestSchema).parse(value);
+        const { sessionId, ...body } = input;
+        const local = await this.findLocalSession(sessionId);
+        if (local) {
+            const startedAt = new Date();
+            const result = await local.session.runCommand(sessionId, body);
+            const endedAt = new Date();
+            local.record = { ...local.record, lastActivityAt: endedAt.toISOString() };
+            return {
+                sessionId,
+                command: input.command,
+                ...result,
+                startedAt: startedAt.toISOString(),
+                endedAt: endedAt.toISOString()
+            };
+        }
+        return this.requestJson('POST', `/api/code-sessions/${encodeURIComponent(sessionId)}/run`, RunCommandResponseSchema, body);
+    }
+    async push(value) {
+        this.assertStandardAccess();
+        return this.pushValidated(requestBoundary(PushBranchRequestSchema).parse(value));
+    }
+    async pushValidated(input) {
+        const { sessionId, ...body } = input;
+        // No local-session shortcut on purpose — see the interface note. Publishing
+        // must go through the platform so the authority chain and the bound,
+        // revocable credential are not bypassable from a client.
+        return this.requestJson('POST', `/api/code-sessions/${encodeURIComponent(sessionId)}/push`, PushBranchResponseSchema, body);
+    }
+    async createPullRequest(value) {
+        this.assertStandardAccess();
+        return this.createPullRequestValidated(requestBoundary(CreatePullRequestRequestSchema).parse(value));
+    }
+    async createPullRequestValidated(input) {
+        const { sessionId, ...body } = input;
+        return this.requestJson('POST', `/api/code-sessions/${encodeURIComponent(sessionId)}/pull-request`, CreatePullRequestResponseSchema, body);
+    }
+    async delete(value) {
+        this.assertStandardAccess();
+        return this.deleteValidated(requestBoundary(SessionIdSchema).parse(value));
+    }
+    async deleteValidated(sessionId) {
+        const local = await this.findLocalSession(sessionId);
+        if (local) {
+            await local.session.teardown(sessionId);
+            this.localSessions.delete(sessionId);
+            return;
+        }
+        await this.send('DELETE', `/api/code-sessions/${encodeURIComponent(sessionId)}`, undefined);
+    }
+}
+export default CodeSessionsApiClientConsumer;
+/**
+ * Create a CodeSessionsApiClientConsumer configured for SSR use. It configures
+ * the client through the same public `configureHttp` path every request fork
+ * uses; it never touches private implementation fields.
+ *
+ * Usage:
+ *   const client = createSsrCodeSessionsClient(event.locals.runtime, {
+ *     origin: platformOrigin,
+ *     token: event.locals.sessionToken
+ *   });
+ *   const sessions = await client.list();
+ */
+export function createSsrCodeSessionsClient(runtime, opts) {
+    const client = new CodeSessionsApiClientConsumer({ id: 'code-sessions', kind: 'runtime/client' }, { runtime }, runtime);
+    const overrides = {
+        token: opts.token,
+        fetch: opts.fetch,
+        credentials: 'omit'
+    };
+    if (opts.origin)
+        overrides.origin = opts.origin;
+    client.configureHttp(overrides);
+    return client;
+}
+//# sourceMappingURL=code-sessions.api-client.impl.js.map