@openchamber/sdk 2.5.0 → 2.5.2

package/dist/service-provider-schemas.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { BROWSER_CONTROL_ACTIONS } from './service-providers.js';
+import { BROWSER_CONTROL_ACTIONS, SOURCE_CONTROL_OUTBOUND_BODY_MAX, SOURCE_CONTROL_OUTBOUND_METHODS, SOURCE_CONTROL_OUTBOUND_REQUEST_HEADERS, SOURCE_CONTROL_PROVIDER_ERROR_MESSAGE_MAX, SOURCE_CONTROL_PROVIDER_METHODS, SOURCE_CONTROL_PROVIDER_RESPONSE_MAX, SOURCE_CONTROL_PROVIDER_TARGET_MAX, } from './service-providers.js';
 /**
  * Host-side parse of what a browser provider answers. `data` stays whatever
  * the service produced: the host hands it to the agent as is, and only
@@ -10,3 +10,223 @@ export const browserProviderResultSchema = z.union([
     z.object({ ok: z.literal(false), error: z.string().min(1).max(2_000) }),
 ]);
 export const browserControlActionSchema = z.enum(BROWSER_CONTROL_ACTIONS);
+/*
+ * Host-side parse of what a source-control provider answers. Every answer is
+ * checked as an envelope. Answers OpenChamber acts on (who an account is,
+ * where a head lives, what a mutation targets and did) are checked deeply;
+ * reads OpenChamber only hands to the UI, which parses those DTOs itself, are
+ * checked for being a JSON object or array within the size cap, so the two
+ * parsers never drift apart. A failed parse is a malformed answer, never an
+ * empty one.
+ */
+const text = z.string().min(1).max(1_024);
+const optionalText = z.string().max(1_024).optional();
+const positiveInteger = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const nonNegativeInteger = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const commitSha = z.string().regex(/^[0-9a-fA-F]{40}$/).transform((sha) => sha.toLowerCase());
+const projectRef = z.object({ id: text, owner: text, name: text }).strict();
+const errorSchema = z.object({
+    message: z.string().min(1).max(SOURCE_CONTROL_PROVIDER_ERROR_MESSAGE_MAX),
+    status: z.number().int().min(400).max(599).optional(),
+    code: z.string().regex(/^[A-Z_]{1,64}$/).optional(),
+}).strict();
+const envelopeSchema = z.union([
+    z.object({ ok: z.literal(true), data: z.json() }).strict(),
+    z.object({ ok: z.literal(false), error: errorSchema }).strict(),
+]);
+const forgeUserSchema = z.object({
+    id: positiveInteger,
+    login: z.string().min(1).max(256),
+    name: optionalText,
+    email: optionalText,
+    avatarUrl: z.string().max(2_048).optional(),
+});
+const verifySchema = z.object({ user: forgeUserSchema });
+const probeSchema = z.object({
+    supported: z.boolean(),
+    version: z.string().max(128).optional(),
+    message: z.string().max(SOURCE_CONTROL_PROVIDER_ERROR_MESSAGE_MAX).optional(),
+});
+const changeRequestHeadSchema = z.object({
+    project: projectRef,
+    headSha: commitSha,
+    headBranch: text,
+    headOwner: text,
+});
+/**
+ * The shape only; OpenChamber also checks that `endpoint` is https on the
+ * instance origin and names `sourceProject`, and that `headSha` is the head it
+ * expected.
+ */
+const changeRequestSourceSchema = z.object({
+    sourceProject: projectRef,
+    targetProject: projectRef,
+    classification: z.enum(['same-repository', 'contributor-fork']),
+    headSha: commitSha,
+    headRef: z.string().regex(/^refs\/heads\/\S+$/).max(1_024),
+    endpoint: z.string().min(1).max(2_048),
+});
+/** Exactly the target keys OpenChamber's mutation store accepts. */
+const mutationTargetSchema = z.object({
+    repositoryId: text,
+    bindingRevision: nonNegativeInteger,
+    primaryRemote: text,
+    project: projectRef,
+    number: positiveInteger.optional(),
+    head: text.optional(),
+    base: text.optional(),
+    headSha: text.optional(),
+}).strict();
+const jsonObject = z.record(z.string(), z.json());
+const mutationResolutionSchema = z.object({
+    providerTarget: jsonObject.refine((target) => JSON.stringify(target).length <= SOURCE_CONTROL_PROVIDER_TARGET_MAX, { message: `providerTarget is at most ${SOURCE_CONTROL_PROVIDER_TARGET_MAX} characters of JSON` }),
+    target: mutationTargetSchema,
+}).strict();
+/** Exactly the result keys OpenChamber's mutation store accepts. */
+const mutationResultSchema = z.object({
+    project: projectRef.optional(),
+    number: positiveInteger.optional(),
+    head: text.optional(),
+    base: text.optional(),
+    headSha: text.optional(),
+    state: text.optional(),
+    merged: z.boolean().optional(),
+    outcome: z.enum(['queued', 'merging']).optional(),
+    stacked: z.boolean().optional(),
+    ready: z.boolean().optional(),
+    commented: z.boolean().optional(),
+    failureStatus: z.number().int().min(400).max(599).optional(),
+    failureCode: text.optional(),
+}).strict();
+const reconcileSchema = z.object({
+    state: z.enum(['succeeded', 'failed', 'outcome-unknown']),
+    result: mutationResultSchema.optional(),
+}).strict();
+const LIVE_SUMMARIES_MAX = 50;
+const liveChangeRequestSummarySchema = z.object({
+    owner: text,
+    repo: text,
+    number: positiveInteger,
+    state: z.enum(['open', 'closed', 'merged']),
+    draft: z.boolean(),
+    title: z.string().max(4_096),
+    mergeable: z.boolean().nullable(),
+    mergeableState: z.string().max(64).nullable(),
+    checks: z.object({ state: z.string().max(64) }).passthrough().nullable(),
+    headSha: z.string().max(128).optional(),
+    base: z.string().max(1_024).optional(),
+});
+const liveIssueSummarySchema = z.object({
+    owner: text,
+    repo: text,
+    number: positiveInteger,
+    title: z.string().max(4_096),
+    state: z.enum(['open', 'completed', 'not_planned']),
+});
+const liveSummariesSchema = z.object({
+    summaries: z.array(liveChangeRequestSummarySchema).max(LIVE_SUMMARIES_MAX),
+    issueSummaries: z.array(liveIssueSummarySchema).max(LIVE_SUMMARIES_MAX),
+});
+const identitySchema = z.object({ provider: text, instance: text }).passthrough();
+const projectSchema = z.object({ provider: text, instance: text, id: text, owner: text, name: text, url: text }).passthrough();
+const STACK_LAYERS_MAX = 50;
+/** Change requests stacked on one another, bottom layer first (`PullRequestStack` in the UI). */
+const changeRequestStackSchema = z.object({
+    number: positiveInteger.nullable(),
+    base: text,
+    layers: z.array(z.object({
+        number: positiveInteger,
+        title: z.string().max(4_096),
+        url: text,
+        state: z.enum(['open', 'closed', 'merged']),
+        draft: z.boolean(),
+        head: text,
+    }).passthrough()).max(STACK_LAYERS_MAX),
+}).passthrough();
+/**
+ * The local branch tip as a change-based host sees it: its sha, the change id
+ * its commit message carries (null when none), and the revision number it was
+ * uploaded as (null when this commit is not on the host yet).
+ */
+const localRevisionSchema = z.object({
+    sha: commitSha,
+    changeId: z.string().min(1).max(128).nullable(),
+    uploadedAs: positiveInteger.nullable(),
+}).strict();
+/** The status OpenChamber caches per branch and shows on every badge. */
+const changeRequestStatusSchema = z.object({
+    identity: identitySchema,
+    fetchedAt: z.number().optional(),
+    project: projectSchema.nullable(),
+    branch: z.string().min(1).max(1_024),
+    changeRequest: z.object({
+        provider: text,
+        instance: text,
+        id: text,
+        number: positiveInteger,
+        project: projectSchema,
+        title: z.string().max(4_096),
+        url: text,
+        state: z.enum(['open', 'closed', 'merged']),
+        draft: z.boolean(),
+        base: text,
+        head: text,
+    }).passthrough().nullable(),
+    ci: z.object({ summary: z.object({ state: z.string().max(64) }).passthrough() }).passthrough().nullable().optional(),
+    canMerge: z.boolean().optional(),
+    defaultBranch: z.string().max(1_024).nullable().optional(),
+    resolvedRemoteName: z.string().max(1_024).nullable().optional(),
+    localRevision: localRevisionSchema.optional(),
+    stack: changeRequestStackSchema.nullable().optional(),
+}).strict();
+/** A read OpenChamber passes on unread: a JSON object or array within the response cap. */
+const passThroughSchema = z.union([jsonObject, z.array(z.json())]).refine((value) => JSON.stringify(value).length <= SOURCE_CONTROL_PROVIDER_RESPONSE_MAX, { message: 'answer is larger than the response cap' });
+const dataSchemas = {
+    'auth.verify': verifySchema,
+    'auth.probe': probeSchema,
+    changeRequestStatus: changeRequestStatusSchema,
+    listChangeRequests: passThroughSchema,
+    changeRequestContext: passThroughSchema,
+    listIssues: passThroughSchema,
+    getIssue: passThroughSchema,
+    issueComments: passThroughSchema,
+    projectUpstream: passThroughSchema,
+    projectBranches: passThroughSchema,
+    listLabels: passThroughSchema,
+    listReviewerCandidates: passThroughSchema,
+    readChangeRequestPatch: passThroughSchema,
+    readChangeRequestFile: passThroughSchema,
+    liveSummaries: liveSummariesSchema,
+    readChangeRequestHead: changeRequestHeadSchema,
+    resolveChangeRequestSource: changeRequestSourceSchema,
+    'mutation.resolveTarget': mutationResolutionSchema,
+    'mutation.perform': mutationResultSchema,
+    'mutation.reconcile': reconcileSchema,
+};
+/** What a service sends OpenChamber's outbound proxy; checked before anything reaches the forge. */
+const outboundRequestSchema = z.object({
+    method: z.enum(SOURCE_CONTROL_OUTBOUND_METHODS),
+    path: z.string().min(1).max(2_048).regex(/^\/(?!\/)/),
+    query: z.record(z.string().max(256), z.string().max(2_048)).optional(),
+    headers: z.partialRecord(z.enum(SOURCE_CONTROL_OUTBOUND_REQUEST_HEADERS), z.string().max(1_024)).optional(),
+    body: z.string().max(SOURCE_CONTROL_OUTBOUND_BODY_MAX).optional(),
+}).strict();
+/** Wire 1 of the source-control role, as the host parses it. `data[method]` checks an `ok: true` answer's `data`. */
+export const sourceControlProviderSchemasV1 = {
+    envelope: envelopeSchema,
+    error: errorSchema,
+    forgeUser: forgeUserSchema,
+    probe: probeSchema,
+    changeRequestHead: changeRequestHeadSchema,
+    changeRequestSource: changeRequestSourceSchema,
+    mutationTarget: mutationTargetSchema,
+    mutationResolution: mutationResolutionSchema,
+    mutationResult: mutationResultSchema,
+    reconcile: reconcileSchema,
+    liveSummaries: liveSummariesSchema,
+    changeRequestStatus: changeRequestStatusSchema,
+    passThrough: passThroughSchema,
+    outboundRequest: outboundRequestSchema,
+    data: dataSchemas,
+};
+export const sourceControlProviderMethodSchema = z.enum(SOURCE_CONTROL_PROVIDER_METHODS);

package/dist/service-providers.d.ts

@@ -10,7 +10,7 @@
  */
 /** Route on the service loopback the host posts every action to. */
 export declare const BROWSER_PROVIDER_PATH = "/browser-control";
-export declare const BROWSER_CONTROL_ACTIONS: readonly ['browser.open', 'browser.snapshot', 'browser.click', 'browser.type', 'browser.scroll', 'browser.back', 'browser.forward', 'browser.inspect', 'browser.capture', 'browser.resize', 'browser.close'];
+export declare const BROWSER_CONTROL_ACTIONS: readonly ['browser.open', 'browser.snapshot', 'browser.click', 'browser.type', 'browser.select', 'browser.scroll', 'browser.back', 'browser.forward', 'browser.inspect', 'browser.capture', 'browser.resize', 'browser.close'];
 export type BrowserControlAction = (typeof BROWSER_CONTROL_ACTIONS)[number];
 export declare const BROWSER_VIEWPORT_MODES: readonly ['mobile', 'tablet', 'desktop', 'fill'];
 export type BrowserViewportMode = (typeof BROWSER_VIEWPORT_MODES)[number];
@@ -48,6 +48,15 @@ export type BrowserTypeParameters = BrowserTabTarget & {
     value: string;
     submit: boolean;
 };
+export type BrowserSelectParameters = BrowserTabTarget & {
+    selector: string;
+} & ({
+    label: string;
+    value?: never;
+} | {
+    value: string;
+    label?: never;
+});
 export type BrowserScrollParameters = BrowserTabTarget & {
     selector?: string;
     direction?: BrowserScrollDirection;
@@ -91,6 +100,9 @@ export type BrowserProviderRequest = ProviderRequestEnvelope & ({
 } | {
     action: 'browser.type';
     parameters: BrowserTypeParameters;
+} | {
+    action: 'browser.select';
+    parameters: BrowserSelectParameters;
 } | {
     action: 'browser.scroll';
     parameters: BrowserScrollParameters;
@@ -124,6 +136,12 @@ export type BrowserElementBounds = {
     width: number;
     height: number;
 };
+export type BrowserSnapshotOption = {
+    label: string;
+    value: string;
+    selected: boolean;
+    disabled: boolean;
+};
 /** One interactive element of a snapshot; absent fields mean empty or default. */
 export type BrowserSnapshotElement = {
     selector: string;
@@ -134,6 +152,9 @@ export type BrowserSnapshotElement = {
     role?: string;
     label?: string;
     disabled?: true;
+    options?: BrowserSnapshotOption[];
+    optionsTruncated?: boolean;
+    multiple?: boolean;
     missingAccessibleName?: true;
 };
 export type BrowserOpenData = {
@@ -184,6 +205,12 @@ export type BrowserTypeData = {
     selector: string;
     url: string;
 };
+export type BrowserSelectData = {
+    selector: string;
+    label: string;
+    value: string;
+    url: string;
+};
 export type BrowserScrollData = {
     scrollY: number;
     maxScrollY: number;
@@ -226,7 +253,7 @@ export type BrowserCloseData = {
     closed: true;
     tabId?: string;
 };
-export type BrowserProviderData = BrowserOpenData | BrowserSnapshotData | BrowserClickData | BrowserTypeData | BrowserScrollData | BrowserNavigationData | BrowserInspectData | BrowserCaptureData | BrowserResizeData | BrowserCloseData;
+export type BrowserProviderData = BrowserOpenData | BrowserSnapshotData | BrowserClickData | BrowserTypeData | BrowserSelectData | BrowserScrollData | BrowserNavigationData | BrowserInspectData | BrowserCaptureData | BrowserResizeData | BrowserCloseData;
 /**
  * What the service answers. `error` is read by the agent, so it should say
  * what to do differently ("No element matches #save"), not what broke inside.
@@ -247,4 +274,352 @@ export declare const isBrowserControlAction: (value: string) => value is Browser
  * not a browser action; answer it with HTTP 400.
  */
 export declare const readBrowserProviderRequest: (body: string) => BrowserProviderRequest | null;
+/** Route on the service loopback OpenChamber posts every source-control call to. */
+export declare const SOURCE_CONTROL_PROVIDER_PATH = "/source-control";
+/** The `v` of every request; a service answers a version it does not know with HTTP 400. */
+export declare const SOURCE_CONTROL_PROVIDER_WIRE_VERSION = 1;
+/**
+ * Every call OpenChamber forwards. `auth.verify` reads who a candidate token
+ * belongs to and `auth.probe` whether the instance is this forge; the fifteen
+ * reads take the shell's own input without the session; the three
+ * `mutation.*` steps are the part of a write the service owns, while
+ * OpenChamber owns the kind, the normalized input, its digest, the
+ * idempotency record and when each step runs.
+ */
+export declare const SOURCE_CONTROL_PROVIDER_METHODS: readonly ['auth.verify', 'auth.probe', 'changeRequestStatus', 'listChangeRequests', 'changeRequestContext', 'listIssues', 'getIssue', 'issueComments', 'projectUpstream', 'projectBranches', 'listLabels', 'listReviewerCandidates', 'readChangeRequestPatch', 'readChangeRequestFile', 'liveSummaries', 'readChangeRequestHead', 'resolveChangeRequestSource', 'mutation.resolveTarget', 'mutation.perform', 'mutation.reconcile'];
+export type SourceControlProviderMethod = (typeof SOURCE_CONTROL_PROVIDER_METHODS)[number];
+export type SourceControlMutationMethod = Extract<SourceControlProviderMethod, `mutation.${string}`>;
+export type SourceControlResourceMethod = Exclude<SourceControlProviderMethod, `auth.${string}` | SourceControlMutationMethod>;
+/** `changeRequestStatus` answers within the badge's own deadline; past it the last known status shows. */
+export declare const SOURCE_CONTROL_PROVIDER_STATUS_TIMEOUT_MS = 12000;
+export declare const SOURCE_CONTROL_PROVIDER_READ_TIMEOUT_MS = 20000;
+export declare const SOURCE_CONTROL_PROVIDER_MUTATION_TIMEOUT_MS = 30000;
+export declare const SOURCE_CONTROL_PROVIDER_AUTH_TIMEOUT_MS = 15000;
+/** Answers are read up to this many bytes, enough for a change request's patch or one file. */
+export declare const SOURCE_CONTROL_PROVIDER_RESPONSE_MAX = 8000000;
+/** Characters of `error.message` OpenChamber reads. */
+export declare const SOURCE_CONTROL_PROVIDER_ERROR_MESSAGE_MAX = 2000;
+/** No call for this long stops the service; the next call starts it again. */
+export declare const SOURCE_CONTROL_PROVIDER_IDLE_MS: number;
+/** Characters of a mutation's `providerTarget` JSON, which OpenChamber stores with the record. */
+export declare const SOURCE_CONTROL_PROVIDER_TARGET_MAX = 4096;
+/** How long OpenChamber waits for the service to answer `method`. */
+export declare const sourceControlProviderTimeoutMs: (method: SourceControlProviderMethod) => number;
+/**
+ * Environment variable with the base URL of OpenChamber's callback listener
+ * (`http://127.0.0.1:<port>`). Set only for a service that provides
+ * `source-control`; `createSourceControlForge` reads it.
+ */
+export declare const OPENCHAMBER_HOST_CALLBACK_URL = "OPENCHAMBER_HOST_CALLBACK_URL";
+/** Route on the callback listener a service sends a forge request to. */
+export declare const SOURCE_CONTROL_OUTBOUND_PATH = "/source-control/outbound";
+export declare const SOURCE_CONTROL_OUTBOUND_METHODS: readonly ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+export type SourceControlOutboundMethod = (typeof SOURCE_CONTROL_OUTBOUND_METHODS)[number];
+/** Request headers OpenChamber passes to the forge; it sets every other header itself. */
+export declare const SOURCE_CONTROL_OUTBOUND_REQUEST_HEADERS: readonly ['accept', 'content-type', 'if-none-match', 'range'];
+/** Response headers OpenChamber hands back, plus any starting with `SOURCE_CONTROL_OUTBOUND_RESPONSE_HEADER_PREFIX`. */
+export declare const SOURCE_CONTROL_OUTBOUND_RESPONSE_HEADERS: readonly ['content-type', 'link', 'etag', 'x-total-count', 'x-total', 'retry-after'];
+export declare const SOURCE_CONTROL_OUTBOUND_RESPONSE_HEADER_PREFIX = "x-ratelimit-";
+/** Characters of an outbound request body. */
+export declare const SOURCE_CONTROL_OUTBOUND_BODY_MAX = 1000000;
+/** Bytes of a forge answer OpenChamber reads; a longer one is refused whole. */
+export declare const SOURCE_CONTROL_OUTBOUND_RESPONSE_MAX = 8000000;
+/** One forge request may take this long; the call's own deadline may end it sooner. */
+export declare const SOURCE_CONTROL_OUTBOUND_TIMEOUT_MS = 20000;
+export type SourceControlJson = null | boolean | number | string | SourceControlJson[] | {
+    [key: string]: SourceControlJson;
+};
+export type SourceControlJsonObject = {
+    [key: string]: SourceControlJson;
+};
+/** The forge account a call acts as; `null` in `auth.verify` and `auth.probe`, before one is known. */
+export type SourceControlProviderUser = {
+    id: number;
+    login: string;
+};
+/**
+ * Who a call is for. `instance` is the normalized origin (`https://git.example.com`).
+ * `handle` is the capability for this one call: pass it to
+ * `createSourceControlForge(...).request`. It stops working when the call
+ * ends; never store it.
+ */
+export type SourceControlProviderSession = {
+    instance: string;
+    handle: string;
+    user: SourceControlProviderUser | null;
+};
+/**
+ * One call, as OpenChamber posts it. `provider` is the id OpenChamber gave this
+ * Git host (`ext-<panel.id>`): put it in every DTO's `provider` field.
+ * `input` was built and validated by OpenChamber; its shape per method is
+ * `SourceControlProviderInputs`.
+ */
+export type SourceControlProviderRequest = {
+    v: typeof SOURCE_CONTROL_PROVIDER_WIRE_VERSION;
+    requestId: string;
+    method: SourceControlProviderMethod;
+    provider: string;
+    session: SourceControlProviderSession | null;
+    input: SourceControlJsonObject;
+};
+export type SourceControlProjectSelector = {
+    owner: string;
+    name: string;
+};
+export type SourceControlProjectRef = {
+    id: string;
+    owner: string;
+    name: string;
+};
+/** The bound context OpenChamber validated: binding, account and the remote it reads through. */
+type ReadInput = {
+    context: SourceControlJsonObject;
+    directory: string;
+    remote: string;
+};
+type ListInput = ReadInput & {
+    page: number;
+    query?: string;
+    state: string;
+    people: string;
+};
+/**
+ * `revision` (a 40-hex commit sha) asks for one revision of the change
+ * request instead of its current one. OpenChamber sends it only to a host
+ * that declares `capabilities.revisions`.
+ */
+type RevisionInput = {
+    revision?: string;
+};
+/**
+ * The durable target of a mutation, exactly the keys OpenChamber stores:
+ * the binding it was made under and what it acts on.
+ */
+export type SourceControlMutationTarget = {
+    repositoryId: string;
+    bindingRevision: number;
+    primaryRemote: string;
+    project: SourceControlProjectRef;
+    number?: number;
+    head?: string;
+    base?: string;
+    headSha?: string;
+};
+/** `providerTarget` is the service's own coordinates for the write (≤ `SOURCE_CONTROL_PROVIDER_TARGET_MAX` bytes of JSON). */
+export type SourceControlMutationResolution = {
+    providerTarget: SourceControlJsonObject;
+    target: SourceControlMutationTarget;
+};
+/**
+ * `input` is the normalized input of the route. A `/pr/review` on a host that
+ * declares `capabilities.reviewModel: "votes"` carries `votes` (label name to
+ * score) and an optional `body` instead of `verdict`; OpenChamber sends `votes`
+ * to no other host.
+ */
+type MutationStepInput = {
+    route: string;
+    kind: string;
+    input: SourceControlJsonObject;
+    resolved: SourceControlMutationResolution;
+};
+/** What each method's `input` holds. */
+export type SourceControlProviderInputs = {
+    'auth.verify': Record<string, never>;
+    'auth.probe': Record<string, never>;
+    changeRequestStatus: ReadInput & {
+        branch: string;
+        force: boolean;
+    };
+    listChangeRequests: ListInput;
+    changeRequestContext: ReadInput & RevisionInput & {
+        number: number;
+        project?: SourceControlProjectSelector;
+        includeDiff: boolean;
+        includeCIDetails: boolean;
+        includeTimeline: boolean;
+    };
+    listIssues: ListInput;
+    getIssue: ReadInput & {
+        number: number;
+        project?: SourceControlProjectSelector;
+    };
+    issueComments: ReadInput & {
+        number: number;
+        project?: SourceControlProjectSelector;
+    };
+    projectUpstream: ReadInput;
+    projectBranches: ReadInput & {
+        project: SourceControlProjectSelector;
+    };
+    listLabels: ReadInput & {
+        project: SourceControlProjectSelector;
+    };
+    listReviewerCandidates: ReadInput & {
+        project: SourceControlProjectSelector;
+    };
+    readChangeRequestPatch: ReadInput & RevisionInput & {
+        number: number;
+        sourceRepo?: {
+            owner: string;
+            repo: string;
+        };
+    };
+    readChangeRequestFile: ReadInput & RevisionInput & {
+        number: number;
+        sourceRepo?: {
+            owner: string;
+            repo: string;
+        };
+        path: string;
+        previousPath?: string;
+        status?: string;
+    };
+    liveSummaries: {
+        refs: Array<{
+            owner: string;
+            repo: string;
+            number: number;
+        }>;
+        issueRefs: Array<{
+            owner: string;
+            repo: string;
+            number: number;
+        }>;
+    };
+    readChangeRequestHead: ReadInput & {
+        number: number;
+    };
+    resolveChangeRequestSource: ReadInput & {
+        project: SourceControlProjectRef;
+        number: number;
+        expectedHeadSha: string;
+    };
+    'mutation.resolveTarget': {
+        context: SourceControlJsonObject;
+        kind: string;
+        input: SourceControlJsonObject;
+        replayOf?: SourceControlJsonObject;
+    };
+    'mutation.perform': MutationStepInput;
+    'mutation.reconcile': MutationStepInput;
+};
+export type SourceControlForgeUser = {
+    id: number;
+    login: string;
+    name?: string;
+    email?: string;
+    avatarUrl?: string;
+};
+export type SourceControlVerifyData = {
+    user: SourceControlForgeUser;
+};
+export type SourceControlProbeData = {
+    supported: boolean;
+    version?: string;
+    message?: string;
+};
+export type SourceControlChangeRequestHead = {
+    project: SourceControlProjectRef;
+    headSha: string;
+    headBranch: string;
+    headOwner: string;
+};
+/** OpenChamber adds the context and the requested remote name; the service names where the head lives. */
+export type SourceControlChangeRequestSource = {
+    sourceProject: SourceControlProjectRef;
+    targetProject: SourceControlProjectRef;
+    classification: 'same-repository' | 'contributor-fork';
+    headSha: string;
+    headRef: string;
+    /** The head repository's HTTPS clone URL on the instance. */
+    endpoint: string;
+};
+/** Only these keys are stored with a finished mutation. */
+export type SourceControlMutationResult = {
+    project?: SourceControlProjectRef;
+    number?: number;
+    head?: string;
+    base?: string;
+    headSha?: string;
+    state?: string;
+    merged?: boolean;
+    outcome?: 'queued' | 'merging';
+    stacked?: boolean;
+    ready?: boolean;
+    commented?: boolean;
+    failureStatus?: number;
+    failureCode?: string;
+};
+export type SourceControlReconcileData = {
+    state: 'succeeded' | 'failed' | 'outcome-unknown';
+    result?: SourceControlMutationResult;
+};
+/**
+ * An answer. `error.status` is the HTTP status OpenChamber should treat the
+ * failure as (a 4xx the forge gave, say); a 401 only counts when OpenChamber's
+ * proxy saw the forge answer 401 itself. `error.code` is `[A-Z_]{1,64}`.
+ */
+export type SourceControlProviderError = {
+    message: string;
+    status?: number;
+    code?: string;
+};
+export type SourceControlProviderResult = {
+    ok: true;
+    data: SourceControlJson;
+} | {
+    ok: false;
+    error: SourceControlProviderError;
+};
+export declare const isSourceControlProviderMethod: (value: string) => value is SourceControlProviderMethod;
+/**
+ * A service's read of the body OpenChamber posted to
+ * `SOURCE_CONTROL_PROVIDER_PATH`. OpenChamber built and validated `input`, so
+ * this checks the envelope, not every field, and the service bundle needs no
+ * schema library. `null` is a body that is not a source-control call of this
+ * wire version; answer it with HTTP 400.
+ */
+export declare const readSourceControlProviderRequest: (body: string) => SourceControlProviderRequest | null;
+/** A request to the forge, relative to the call's instance origin. */
+export type SourceControlOutboundRequest = {
+    method: SourceControlOutboundMethod;
+    /** Starts with `/`; stays on the instance origin. */
+    path: string;
+    query?: Record<string, string>;
+    /** Only `SOURCE_CONTROL_OUTBOUND_REQUEST_HEADERS`; OpenChamber adds the token itself. */
+    headers?: Record<string, string>;
+    /** At most `SOURCE_CONTROL_OUTBOUND_BODY_MAX` characters. */
+    body?: string;
+};
+/** The forge's answer as OpenChamber relayed it: any status, the allowed headers, the body as text. */
+export type SourceControlOutboundResponse = {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+};
+/**
+ * OpenChamber refused the request (an expired handle, a path off the
+ * instance, a body too large), could not reach the forge, or did not answer.
+ * `status` is the callback listener's HTTP status, `0` when it gave none;
+ * `code` is its error code (`HOST_UNAVAILABLE` when there was no usable answer).
+ */
+export declare class SourceControlForgeError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+export type SourceControlForge = {
+    /** Sends `request` to the forge of the call `handle` belongs to, with the stored token when the call has one. */
+    request(handle: string, request: SourceControlOutboundRequest): Promise<SourceControlOutboundResponse>;
+};
+/**
+ * The service's way to the forge: OpenChamber's callback listener
+ * (`OPENCHAMBER_HOST_CALLBACK_URL`), which checks the handle, keeps the request
+ * on the instance origin and adds the token. Plain `fetch`, no dependencies.
+ * Throws `SourceControlForgeError` when OpenChamber refuses the request; a
+ * forge answer of any status, 401 included, resolves.
+ */
+export declare const createSourceControlForge: ({ env }: {
+    env: Record<string, string | undefined>;
+}) => SourceControlForge;
 export {};