glirastes 0.3.2 → 0.5.0

package/dist/cjs/server/testing/zod-introspect.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Schema introspection helpers (Zod v3/v4 and generated JSON Schema).
+ *
+ * Centralizes all access to Zod's internal `_zod.def` representation so the
+ * test-suite generators (`edge-cases.ts`, `schema-consistency.ts`) don't each
+ * reach into internals independently. If a future Zod version changes its
+ * internal shape, only this file — covered by `zod-introspect.test.ts` — needs
+ * updating, and the unit tests will catch a silent regression (introspection
+ * returning nothing) instead of letting it ship as a green-but-empty suite.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSchemaType = getSchemaType;
+exports.isOptional = isOptional;
+exports.unwrap = unwrap;
+exports.getBaseType = getBaseType;
+exports.getObjectShape = getObjectShape;
+exports.getEnumValues = getEnumValues;
+exports.getArrayElement = getArrayElement;
+exports.getArrayMax = getArrayMax;
+exports.hasStringFormat = hasStringFormat;
+exports.isUuidString = isUuidString;
+const ZOD_3_TYPES = {
+    ZodArray: 'array',
+    ZodBoolean: 'boolean',
+    ZodCatch: 'catch',
+    ZodDefault: 'default',
+    ZodDiscriminatedUnion: 'union',
+    ZodEffects: 'effects',
+    ZodEnum: 'enum',
+    ZodLazy: 'lazy',
+    ZodNativeEnum: 'enum',
+    ZodNullable: 'nullable',
+    ZodNumber: 'number',
+    ZodObject: 'object',
+    ZodOptional: 'optional',
+    ZodPipeline: 'pipe',
+    ZodReadonly: 'readonly',
+    ZodString: 'string',
+    ZodTuple: 'tuple',
+    ZodUnion: 'union',
+};
+const JSON_SCHEMA_NODE = Symbol('glirastes.json-schema-node');
+const JSON_SCHEMA_REQUIRED = Symbol('glirastes.json-schema-required');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function jsonSchemaRef(schema) {
+    if (!isRecord(schema))
+        return undefined;
+    const marked = schema;
+    if (marked[JSON_SCHEMA_NODE]) {
+        return marked;
+    }
+    if (isRecord(schema.jsonSchema)) {
+        return {
+            [JSON_SCHEMA_NODE]: schema.jsonSchema,
+            [JSON_SCHEMA_REQUIRED]: true,
+        };
+    }
+    if (!('_def' in schema)
+        && !('_zod' in schema)
+        && ('type' in schema
+            || 'enum' in schema
+            || 'properties' in schema
+            || 'anyOf' in schema
+            || 'oneOf' in schema)) {
+        return {
+            [JSON_SCHEMA_NODE]: schema,
+            [JSON_SCHEMA_REQUIRED]: true,
+        };
+    }
+    return undefined;
+}
+function jsonAllowsNull(node) {
+    if (node.nullable === true)
+        return true;
+    if (Array.isArray(node.type) && node.type.includes('null'))
+        return true;
+    for (const branchKey of ['anyOf', 'oneOf']) {
+        const branches = node[branchKey];
+        if (Array.isArray(branches)
+            && branches.some((branch) => isRecord(branch) && branch.type === 'null')) {
+            return true;
+        }
+    }
+    return false;
+}
+function unwrapJsonRef(ref) {
+    const node = ref[JSON_SCHEMA_NODE];
+    for (const branchKey of ['anyOf', 'oneOf']) {
+        const branches = node[branchKey];
+        if (Array.isArray(branches)) {
+            const branch = branches.find((candidate) => isRecord(candidate) && candidate.type !== 'null');
+            if (isRecord(branch)) {
+                return {
+                    [JSON_SCHEMA_NODE]: branch,
+                    [JSON_SCHEMA_REQUIRED]: ref[JSON_SCHEMA_REQUIRED],
+                };
+            }
+        }
+    }
+    return ref;
+}
+function jsonSchemaType(ref) {
+    const node = unwrapJsonRef(ref)[JSON_SCHEMA_NODE];
+    if (Array.isArray(node.enum))
+        return 'enum';
+    if (Array.isArray(node.type)) {
+        return node.type.find((value) => value !== 'null');
+    }
+    return typeof node.type === 'string' ? node.type : undefined;
+}
+/** Read and normalize Zod v3/v4 internal schema definitions. */
+function getDef(schema) {
+    const v4 = schema?._zod?.def;
+    if (v4)
+        return v4;
+    const v3 = schema?._def;
+    if (!v3)
+        return undefined;
+    return {
+        ...v3,
+        type: ZOD_3_TYPES[v3.typeName] ?? v3.typeName,
+        element: v3.type,
+        entries: v3.values
+            ? Object.fromEntries(v3.values.map((value) => [value, value]))
+            : v3.values,
+        in: v3.in ?? v3.schema,
+    };
+}
+/** Wrapper types that hold their inner schema in `def.innerType`. */
+const WRAPPER_TYPES = new Set([
+    'optional',
+    'nullable',
+    'default',
+    'prefault',
+    'catch',
+    'readonly',
+    'nonoptional',
+]);
+/** The normalized Zod v4 type tag (e.g. 'object', 'string', 'array', 'enum'). */
+function getSchemaType(schema) {
+    const json = jsonSchemaRef(schema);
+    if (json)
+        return jsonSchemaType(json);
+    return getDef(schema)?.type;
+}
+/**
+ * True if the field is optional, nullable, or has a default — i.e. an input
+ * is not strictly required to provide a concrete value. Matches the historical
+ * behaviour of the edge-case generator, which skips the "rejects missing"
+ * boundary test for any of these.
+ */
+function isOptional(schema) {
+    const json = jsonSchemaRef(schema);
+    if (json) {
+        const node = json[JSON_SCHEMA_NODE];
+        return (!json[JSON_SCHEMA_REQUIRED]
+            || 'default' in node
+            || jsonAllowsNull(node));
+    }
+    const type = getSchemaType(schema);
+    return (type === 'optional' ||
+        type === 'default' ||
+        type === 'prefault' ||
+        type === 'nullable');
+}
+/** Strip optional/nullable/default/pipe wrappers to the base schema. */
+function unwrap(schema) {
+    const json = jsonSchemaRef(schema);
+    if (json)
+        return unwrapJsonRef(json);
+    const def = getDef(schema);
+    const type = def?.type;
+    if (WRAPPER_TYPES.has(type))
+        return unwrap(def.innerType);
+    if (type === 'pipe')
+        return unwrap(def.in);
+    if (type === 'effects')
+        return unwrap(def.schema);
+    return schema;
+}
+/** The base Zod type tag after unwrapping (e.g. an optional string → 'string'). */
+function getBaseType(schema) {
+    return getSchemaType(unwrap(schema));
+}
+/**
+ * The field map of an object schema, unwrapping optional/default/pipe wrappers.
+ * Returns null for non-object schemas.
+ */
+function getObjectShape(schema) {
+    const json = jsonSchemaRef(schema);
+    if (json) {
+        const node = unwrapJsonRef(json)[JSON_SCHEMA_NODE];
+        if (jsonSchemaType(json) !== 'object' || !isRecord(node.properties)) {
+            return null;
+        }
+        const required = new Set(Array.isArray(node.required)
+            ? node.required.filter((field) => typeof field === 'string')
+            : []);
+        return Object.fromEntries(Object.entries(node.properties)
+            .filter((entry) => isRecord(entry[1]))
+            .map(([field, child]) => [
+            field,
+            {
+                [JSON_SCHEMA_NODE]: child,
+                [JSON_SCHEMA_REQUIRED]: required.has(field),
+            },
+        ]));
+    }
+    const def = getDef(schema);
+    if (!def)
+        return null;
+    if (def.type === 'object') {
+        return (typeof def.shape === 'function' ? def.shape() : def.shape);
+    }
+    if (WRAPPER_TYPES.has(def.type) && def.innerType) {
+        return getObjectShape(def.innerType);
+    }
+    if (def.type === 'pipe' && def.in) {
+        return getObjectShape(def.in);
+    }
+    if (def.type === 'effects' && def.schema) {
+        return getObjectShape(def.schema);
+    }
+    return null;
+}
+/** The string members of an enum schema (after unwrapping). */
+function getEnumValues(schema) {
+    const json = jsonSchemaRef(schema);
+    if (json) {
+        const values = unwrapJsonRef(json)[JSON_SCHEMA_NODE].enum;
+        return Array.isArray(values)
+            ? values.filter((value) => typeof value === 'string')
+            : [];
+    }
+    const def = getDef(unwrap(schema));
+    if (def?.type !== 'enum')
+        return [];
+    return Object.values(def.entries).filter((v) => typeof v === 'string');
+}
+/** The element schema of an array (after unwrapping), or null. */
+function getArrayElement(schema) {
+    const json = jsonSchemaRef(schema);
+    if (json) {
+        const node = unwrapJsonRef(json)[JSON_SCHEMA_NODE];
+        return isRecord(node.items)
+            ? {
+                [JSON_SCHEMA_NODE]: node.items,
+                [JSON_SCHEMA_REQUIRED]: true,
+            }
+            : null;
+    }
+    const def = getDef(unwrap(schema));
+    return def?.type === 'array' ? def.element : null;
+}
+/** The `.max(n)` length constraint on an array schema, or null. */
+function getArrayMax(schema) {
+    const json = jsonSchemaRef(schema);
+    if (json) {
+        const maximum = unwrapJsonRef(json)[JSON_SCHEMA_NODE].maxItems;
+        return typeof maximum === 'number' ? maximum : null;
+    }
+    const def = getDef(unwrap(schema));
+    if (def?.type !== 'array')
+        return null;
+    if (def.maxLength?.value !== undefined) {
+        return def.maxLength.value;
+    }
+    for (const check of def.checks ?? []) {
+        const cd = check?._zod?.def;
+        if (cd?.check === 'max_length')
+            return cd.maximum;
+    }
+    return null;
+}
+/** True if a string schema carries the given format check (e.g. 'uuid'). */
+function hasStringFormat(schema, format) {
+    const json = jsonSchemaRef(schema);
+    if (json) {
+        const node = unwrapJsonRef(json)[JSON_SCHEMA_NODE];
+        return jsonSchemaType(json) === 'string' && node.format === format;
+    }
+    const def = getDef(unwrap(schema));
+    if (def?.type !== 'string')
+        return false;
+    return (def.checks ?? []).some((check) => {
+        const cd = check?._zod?.def;
+        return ((cd?.check === 'string_format' && cd?.format === format)
+            || check?.kind === format);
+    });
+}
+/** True if a string schema is a UUID. */
+function isUuidString(schema) {
+    return hasStringFormat(schema, 'uuid');
+}

package/dist/cjs/stt/index.d.ts

@@ -0,0 +1,5 @@
+export { SttSessionController, type SttProviderAdapter, type SttProviderConnection, type SttProviderEvents, type SttSessionControllerOptions, type SttSessionPhase, type SttSessionSnapshot, } from '../react/stt/controller.js';
+export { RecordedSttAdapter, encodeWav, type RecordedSttAdapterOptions, } from '../react/stt/recorded.js';
+export { DeepgramSttAdapter, createDeepgramSegmentParser, type DeepgramSttAdapterOptions, } from '../react/stt/deepgram.js';
+export { applySttSegment, createSttTranscript, type SttSegment, type SttTranscript, } from '../react/stt/segments.js';
+export { createStreamAnalyser, type StreamAnalyser, } from '../react/stt/waveform.js';

package/dist/cjs/stt/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStreamAnalyser = exports.createSttTranscript = exports.applySttSegment = exports.createDeepgramSegmentParser = exports.DeepgramSttAdapter = exports.encodeWav = exports.RecordedSttAdapter = exports.SttSessionController = void 0;
+var controller_js_1 = require("../react/stt/controller.js");
+Object.defineProperty(exports, "SttSessionController", { enumerable: true, get: function () { return controller_js_1.SttSessionController; } });
+var recorded_js_1 = require("../react/stt/recorded.js");
+Object.defineProperty(exports, "RecordedSttAdapter", { enumerable: true, get: function () { return recorded_js_1.RecordedSttAdapter; } });
+Object.defineProperty(exports, "encodeWav", { enumerable: true, get: function () { return recorded_js_1.encodeWav; } });
+var deepgram_js_1 = require("../react/stt/deepgram.js");
+Object.defineProperty(exports, "DeepgramSttAdapter", { enumerable: true, get: function () { return deepgram_js_1.DeepgramSttAdapter; } });
+Object.defineProperty(exports, "createDeepgramSegmentParser", { enumerable: true, get: function () { return deepgram_js_1.createDeepgramSegmentParser; } });
+var segments_js_1 = require("../react/stt/segments.js");
+Object.defineProperty(exports, "applySttSegment", { enumerable: true, get: function () { return segments_js_1.applySttSegment; } });
+Object.defineProperty(exports, "createSttTranscript", { enumerable: true, get: function () { return segments_js_1.createSttTranscript; } });
+var waveform_js_1 = require("../react/stt/waveform.js");
+Object.defineProperty(exports, "createStreamAnalyser", { enumerable: true, get: function () { return waveform_js_1.createStreamAnalyser; } });

package/dist/cjs/sync/app-setup-client.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { AppSetupAssessmentModeSchema, type AppSetupArtifact, type AppSetupStatus } from '../contracts/app-setup.js';
+export interface AppSetupRun {
+    runId: string;
+    appId: string;
+    status: AppSetupStatus;
+    progress?: {
+        completed: number;
+        total: number;
+    };
+    artifactDigest?: string;
+    updatedAt: string;
+}
+export interface CreateAppSetupRun {
+    runId: string;
+    assessmentMode: z.infer<typeof AppSetupAssessmentModeSchema>;
+    discoveryDigest: string;
+}
+export interface UpdateAppSetupStatus {
+    status: AppSetupStatus;
+    progress?: {
+        completed: number;
+        total: number;
+    };
+}
+export interface AppSetupSyncOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export declare class AppSetupClient {
+    private readonly options;
+    constructor(options: {
+        baseUrl: string;
+        setupApiKey: string;
+        appId: string;
+        fetchImpl?: typeof fetch;
+    });
+    createRun(input: CreateAppSetupRun, signal?: AbortSignal): Promise<AppSetupRun>;
+    updateStatus(runId: string, update: UpdateAppSetupStatus): Promise<AppSetupRun>;
+    uploadArtifact(value: unknown, signal?: AbortSignal): Promise<AppSetupRun>;
+    syncArtifact(value: unknown, options?: AppSetupSyncOptions): Promise<AppSetupRun>;
+    getRun(runId: string): Promise<AppSetupRun>;
+    private request;
+    private url;
+}
+export type { AppSetupArtifact };

package/dist/cjs/sync/app-setup-client.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppSetupClient = void 0;
+const zod_1 = require("zod");
+const app_setup_js_1 = require("../contracts/app-setup.js");
+const uuid = zod_1.z.uuid();
+const digest = zod_1.z.string().regex(/^sha256:(?:[A-Za-z0-9_-]{43}|[A-Za-z0-9+/]{43}=)$/);
+const progressSchema = zod_1.z.object({
+    completed: zod_1.z.number().int().nonnegative(),
+    total: zod_1.z.number().int().nonnegative(),
+}).strict().refine((progress) => progress.completed <= progress.total, 'Completed progress cannot exceed total progress');
+const runResponseSchema = zod_1.z.object({
+    runId: uuid,
+    appId: uuid,
+    status: app_setup_js_1.AppSetupStatusSchema,
+    progress: progressSchema.optional(),
+    artifactDigest: digest.optional(),
+    updatedAt: zod_1.z.iso.datetime({ offset: true }),
+}).strict();
+class AppSetupClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async createRun(input, signal) {
+        const body = zod_1.z.object({
+            runId: uuid,
+            assessmentMode: app_setup_js_1.AppSetupAssessmentModeSchema,
+            discoveryDigest: digest,
+        }).strict().parse(input);
+        return this.request('/runs', {
+            method: 'POST',
+            body: JSON.stringify(body),
+            signal,
+        }, body.runId);
+    }
+    async updateStatus(runId, update) {
+        const parsedRunId = uuid.parse(runId);
+        const body = zod_1.z.object({
+            status: app_setup_js_1.AppSetupStatusSchema,
+            progress: progressSchema.optional(),
+        }).strict().parse(update);
+        return this.request(`/runs/${encodeURIComponent(parsedRunId)}/status`, {
+            method: 'PATCH',
+            body: JSON.stringify(body),
+        }, parsedRunId);
+    }
+    async uploadArtifact(value, signal) {
+        const artifact = app_setup_js_1.AppSetupArtifactSchema.parse(value);
+        if (artifact.appId !== this.options.appId) {
+            throw new Error('App setup artifact targets a different app');
+        }
+        return this.request(`/runs/${encodeURIComponent(artifact.runId)}/artifact`, {
+            method: 'PUT',
+            body: JSON.stringify(artifact),
+            signal,
+        }, artifact.runId);
+    }
+    async syncArtifact(value, options = {}) {
+        const artifact = app_setup_js_1.AppSetupArtifactSchema.parse(value);
+        if (artifact.appId !== this.options.appId) {
+            throw new Error('App setup artifact targets a different app');
+        }
+        const timeoutMs = zod_1.z.number().int().positive().max(300_000).parse(options.timeoutMs ?? 30_000);
+        const controller = new AbortController();
+        let timedOut = false;
+        const cancel = () => { controller.abort(); };
+        if (options.signal?.aborted)
+            cancel();
+        else
+            options.signal?.addEventListener('abort', cancel, { once: true });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        try {
+            await this.createRun({
+                runId: artifact.runId,
+                assessmentMode: artifact.assessmentMode,
+                discoveryDigest: artifact.discoveryDigest,
+            }, controller.signal);
+            return await this.uploadArtifact(artifact, controller.signal);
+        }
+        catch (error) {
+            if (timedOut) {
+                throw new Error('Glirastes app setup request timed out');
+            }
+            if (options.signal?.aborted) {
+                throw new Error('Glirastes app setup request cancelled');
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', cancel);
+        }
+    }
+    async getRun(runId) {
+        const parsedRunId = uuid.parse(runId);
+        return this.request(`/runs/${encodeURIComponent(parsedRunId)}`, { method: 'GET' }, parsedRunId);
+    }
+    async request(path, init, expectedRunId) {
+        let response;
+        try {
+            response = await (this.options.fetchImpl ?? fetch)(this.url(path), {
+                ...init,
+                headers: {
+                    authorization: `Bearer ${this.options.setupApiKey}`,
+                    ...(init.body ? { 'content-type': 'application/json' } : {}),
+                },
+            });
+        }
+        catch {
+            throw new Error('Glirastes app setup request failed (network)');
+        }
+        if (!response.ok) {
+            throw new Error(`Glirastes app setup request failed (${response.status})`);
+        }
+        let value;
+        try {
+            value = await response.json();
+        }
+        catch {
+            throw new Error('Invalid Glirastes app setup response');
+        }
+        const parsed = runResponseSchema.safeParse(value);
+        if (!parsed.success
+            || parsed.data.appId !== this.options.appId
+            || parsed.data.runId !== expectedRunId) {
+            throw new Error('Invalid Glirastes app setup response');
+        }
+        return parsed.data;
+    }
+    url(path) {
+        return `${this.options.baseUrl.replace(/\/$/, '')}`
+            + `/v2/apps/${encodeURIComponent(this.options.appId)}`
+            + `/runtime-setup${path}`;
+    }
+}
+exports.AppSetupClient = AppSetupClient;

package/dist/cjs/sync/capability-report.d.ts

@@ -0,0 +1,41 @@
+import { type AppSetupArtifact } from '../contracts/app-setup.js';
+/** `sha256:` plus 43 base64url characters, the form the Platform registers (P08b Task 9). */
+export declare const DISCOVERY_DIGEST_PATTERN: RegExp;
+/**
+ * Runner capability `policyRelaxations` (D16): the version of the relaxation
+ * rule this runner applies to signed Platform decisions (pinned, up to tier 2,
+ * never over a local lock of its code report). The Platform shows a stored
+ * relaxation of confirmation as effective only for environments whose runner
+ * reports it; everywhere else it stays pending.
+ */
+export declare const POLICY_RELAXATIONS_VERSION: 1;
+/**
+ * What a runner tells the Platform about the code it runs (spec 4.10.6): the
+ * committed, content-free setup artifact of that code. It describes tools and
+ * never enables any.
+ */
+export interface CapabilityReport {
+    artifact: AppSetupArtifact;
+    discoveryDigest: string;
+}
+export interface CapabilityReportResult {
+    discoveryDigest: string;
+    runId: string;
+    /** false: the Platform already held the artifact of this run. */
+    uploaded: boolean;
+}
+export declare function capabilityReportFrom(setupArtifact: unknown): CapabilityReport;
+/**
+ * Uploads the report through the app setup transport with the runner's
+ * app-bound runtime key. Run identities are content-derived, so a repeated
+ * upload of the same artifact names the same run; once the Platform holds its
+ * artifact, nothing more is sent.
+ */
+export declare function uploadCapabilityReport(options: {
+    baseUrl: string;
+    apiKey: string;
+    appId: string;
+    report: CapabilityReport;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<CapabilityReportResult>;

package/dist/cjs/sync/capability-report.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLICY_RELAXATIONS_VERSION = exports.DISCOVERY_DIGEST_PATTERN = void 0;
+exports.capabilityReportFrom = capabilityReportFrom;
+exports.uploadCapabilityReport = uploadCapabilityReport;
+const app_setup_js_1 = require("../contracts/app-setup.js");
+const app_setup_client_js_1 = require("./app-setup-client.js");
+/** `sha256:` plus 43 base64url characters, the form the Platform registers (P08b Task 9). */
+exports.DISCOVERY_DIGEST_PATTERN = /^sha256:[A-Za-z0-9_-]{43}$/;
+/**
+ * Runner capability `policyRelaxations` (D16): the version of the relaxation
+ * rule this runner applies to signed Platform decisions (pinned, up to tier 2,
+ * never over a local lock of its code report). The Platform shows a stored
+ * relaxation of confirmation as effective only for environments whose runner
+ * reports it; everywhere else it stays pending.
+ */
+exports.POLICY_RELAXATIONS_VERSION = 1;
+function capabilityReportFrom(setupArtifact) {
+    const artifact = app_setup_js_1.AppSetupArtifactSchema.parse(setupArtifact);
+    if (!exports.DISCOVERY_DIGEST_PATTERN.test(artifact.discoveryDigest)) {
+        throw new Error('The setup artifact discoveryDigest is not a sha256 digest');
+    }
+    return { artifact, discoveryDigest: artifact.discoveryDigest };
+}
+/**
+ * Uploads the report through the app setup transport with the runner's
+ * app-bound runtime key. Run identities are content-derived, so a repeated
+ * upload of the same artifact names the same run; once the Platform holds its
+ * artifact, nothing more is sent.
+ */
+async function uploadCapabilityReport(options) {
+    const { artifact } = options.report;
+    if (artifact.appId !== options.appId) {
+        throw new Error('Capability report targets a different app');
+    }
+    const client = new app_setup_client_js_1.AppSetupClient({
+        baseUrl: options.baseUrl,
+        setupApiKey: options.apiKey,
+        appId: options.appId,
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+    });
+    const run = await client.createRun({
+        runId: artifact.runId,
+        assessmentMode: artifact.assessmentMode,
+        discoveryDigest: artifact.discoveryDigest,
+    }, options.signal);
+    const result = { discoveryDigest: artifact.discoveryDigest, runId: artifact.runId };
+    if (run.artifactDigest)
+        return { ...result, uploaded: false };
+    await client.uploadArtifact(artifact, options.signal);
+    return { ...result, uploaded: true };
+}

package/dist/cjs/sync/connection-lookup.d.ts

@@ -0,0 +1,19 @@
+/** What the Platform answers for a runtime key (`GET /v1/runtime/connection`). */
+export interface ResolvedRuntimeConnection {
+    baseUrl: string;
+    appId: string;
+    environmentId: string;
+    runnerKey: string;
+}
+/**
+ * Asks the Platform which app, environment and runner a runtime key was
+ * issued for, so a connected app needs only `GLIRASTES_API_KEY`. Errors name
+ * the operation and status only (401 invalid key, 409
+ * `connection_key_unbound` for a key not issued by a pairing).
+ */
+export declare function lookupRuntimeConnection(options: {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<ResolvedRuntimeConnection>;

package/dist/cjs/sync/connection-lookup.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupRuntimeConnection = lookupRuntimeConnection;
+const url_js_1 = require("../contracts/url.js");
+const zod_1 = require("zod");
+const control_plane_client_js_1 = require("./control-plane-client.js");
+const RuntimeConnectionResponseSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    appId: zod_1.z.uuid(),
+    environmentId: zod_1.z.uuid(),
+    runnerKey: zod_1.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
+});
+// Only short, machine-readable codes are surfaced; anything else is dropped.
+const ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+async function errorCode(response) {
+    try {
+        const body = await response.json();
+        return typeof body?.code === 'string' && ERROR_CODE_PATTERN.test(body.code)
+            ? body.code
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Asks the Platform which app, environment and runner a runtime key was
+ * issued for, so a connected app needs only `GLIRASTES_API_KEY`. Errors name
+ * the operation and status only (401 invalid key, 409
+ * `connection_key_unbound` for a key not issued by a pairing).
+ */
+async function lookupRuntimeConnection(options) {
+    const response = await (options.fetchImpl ?? fetch)(`${(0, url_js_1.trimTrailingSlashes)(options.baseUrl)}/v1/runtime/connection`, {
+        method: 'GET',
+        headers: { 'x-api-key': options.apiKey, accept: 'application/json' },
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    if (!response.ok) {
+        throw new control_plane_client_js_1.RuntimeControlPlaneRequestError('connection', response.status, await errorCode(response));
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    const parsed = RuntimeConnectionResponseSchema.safeParse(body);
+    if (!parsed.success) {
+        throw new Error('Glirastes Control Plane connection response is invalid');
+    }
+    return {
+        baseUrl: options.baseUrl,
+        appId: parsed.data.appId,
+        environmentId: parsed.data.environmentId,
+        runnerKey: parsed.data.runnerKey,
+    };
+}