@xemahq/biome-sdk 0.1.1

package/src/adapter/lib/provider-module.ts

@@ -0,0 +1,140 @@
+import type {
+  AdapterKindRef,
+  CredentialKind,
+  ProviderOnboardingManifest,
+} from '@xemahq/kernel-contracts/connector';
+
+import type { OutboundActionHandler } from './action';
+import type { ResourceLister } from './resource';
+import type {
+  EventMapper,
+  IdempotencyKeyExtractor,
+  WebhookOrgResolver,
+  WebhookVerifier,
+} from './webhook';
+
+/**
+ * Closed-grammar OAuth + AppInstall config blobs the adapter-sdk
+ * surfaces to the registry. Concrete shapes intentionally narrow —
+ * biome manifests declare the values; the registry MAY ship them to
+ * the install wizard for "Connect <provider>" UX.
+ */
+export interface OAuthAppConfig {
+  readonly clientIdEnvVar: string;
+  readonly clientSecretEnvVar: string;
+  readonly authorizationUrl: string;
+  readonly tokenUrl: string;
+  readonly scopes: readonly string[];
+}
+
+export interface AppInstallConfig {
+  readonly appIdEnvVar: string;
+  readonly privateKeyEnvVar: string;
+  /** URL template (e.g. `https://github.com/apps/{slug}/installations/new`). */
+  readonly installUrlTemplate: string;
+}
+
+/**
+ * The single contract a biome-contributed integration adapter must
+ * implement. The same shape is used by:
+ *  - **first-party** biomes loaded in-process inside
+ *    `integration-adapters-api` (compiled JS, ESLint-quarantined from
+ *    importing provider SDKs outside the biome's own folder);
+ *  - **third-party** biomes deployed as `biome-adapter-host`
+ *    sidecars exposing the same interface over HTTP/gRPC.
+ *
+ * Registry-side code never branches on hosting topology — the
+ * adapter-host service adapts both behind a common `ProviderRegistry`
+ * interface.
+ *
+ * Declared by biomes under `xema.ships.modules.integrationProviders[]`
+ * (one module per `(adapterKind, provider)` pair). The biome manifest
+ * cross-validator (`packages/biome-host-sdk`) checks that every
+ * provider declared here actually has a matching `adapterKinds[]`
+ * registration (built-in or biome-contributed) before the host
+ * accepts the manifest.
+ */
+export interface IntegrationProviderModule {
+  // ── Identity ──
+  readonly adapterKind: AdapterKindRef;
+  /** Unique slug across the platform (e.g. `linear`, `stripe`). */
+  readonly provider: string;
+  /** Human-readable display name used by install UX + admin pages. */
+  readonly displayName: string;
+
+  // ── Webhook ingress ──
+  readonly webhook: {
+    readonly verifier: WebhookVerifier;
+    readonly eventMapper: EventMapper;
+    readonly idempotencyKeyExtractor: IdempotencyKeyExtractor;
+    /**
+     * Derives `(orgId, orgIntegrationId)` from the raw event. Optional
+     * because the legacy controllers do tenant resolution before
+     * handing off; new providers MUST declare it for the registry-
+     * driven router to dispatch.
+     */
+    readonly orgResolver?: WebhookOrgResolver;
+  };
+
+  // ── Credential ──
+  readonly credentialKind: CredentialKind;
+  readonly oauthConfig?: OAuthAppConfig;
+  readonly appConfig?: AppInstallConfig;
+
+  // ── Resource discovery (install UX) ──
+  readonly resources: Readonly<Record<string, ResourceLister>>;
+
+  // ── Outbound actions (activities) ──
+  readonly actions: Readonly<Record<string, OutboundActionHandler>>;
+
+  // ── Install-wizard onboarding metadata ──
+  /**
+   * Provider-declared install-UX manifest (display name, description,
+   * icon, credential field schema OR app-install launch copy). The
+   * frontend renders the "Connect <provider>" surface from this object
+   * alone — there is no hardcoded PROVIDER_INFO map in the UI.
+   *
+   * Required: every provider, first-party or biome-contributed, MUST
+   * declare an onboarding manifest. The remote-sidecar wrapper carries
+   * it through `SidecarManifestResponse.onboarding` so third-party
+   * adapters are first-class.
+   */
+  readonly onboarding: ProviderOnboardingManifest;
+}
+
+/**
+ * Tiny builder that nudges biome authors toward a stable shape and
+ * gives the registry a single import point for hosting-aware
+ * registration. Intentionally not a class — staying value-typed means
+ * sidecar serialization is trivial.
+ */
+export function defineIntegrationProvider<T extends IntegrationProviderModule>(
+  module: T,
+): T {
+  return module;
+}
+
+/**
+ * Biome-contributed AdapterKind declaration. Owned by the manifest
+ * `xema.ships.modules.adapterKinds[]` slot; consumed at boot by
+ * `integration-adapters-api`'s registry to register a path schema +
+ * entityKind enum for the new kind. The kernel enforces semver-versioned
+ * envelope schemas: once published, a kind's envelope schema may add
+ * fields but not remove/retype existing ones (Phase 7 §7.1).
+ */
+export interface AdapterKindDeclaration {
+  readonly kind: AdapterKindRef;
+  readonly version: string;
+  /**
+   * Closed list of entity kinds the adapter kind narrows over (e.g.
+   * for SCM: `['push', 'change_request', 'issue', ...]`). The
+   * `FilterExpr` path checker uses this to scope `$envelope` paths.
+   */
+  readonly entityKinds: readonly string[];
+  /**
+   * Per-entityKind allowed `$envelope.*` paths (dot-delimited). Same
+   * shape `integration-contracts`' built-in envelope schema uses; the
+   * registry merges these into the path-checker map at boot.
+   */
+  readonly envelopePaths: Readonly<Record<string, readonly string[]>>;
+}

package/src/adapter/lib/resource.ts

@@ -0,0 +1,52 @@
+import type { MintedToken, ResourceRef } from '@xemahq/kernel-contracts/connector';
+
+import type { Result } from './result';
+
+/**
+ * "List provider-side resources of a given type" contract. Wired
+ * through `GET /adapters/:provider/resources/:type` by the registry.
+ * The install-wizard's resource-picker widgets bind to a
+ * `ResourceTypeRef = { adapterKind, provider, type }` — same code
+ * path for every provider in the registry.
+ *
+ * Streamed via `AsyncIterable` so wide enumerations (GitHub orgs with
+ * thousands of repos, Confluence spaces) page server-side without
+ * blowing past HTTP response timeouts. Implementations MUST yield
+ * pages of bounded size — the registry attaches a `Cursor` header to
+ * propagate continuation between calls.
+ */
+export interface ResourceLister {
+  readonly type: string;
+  list(input: ResourceListInput): AsyncIterable<Result<ResourceListItem>>;
+}
+
+export interface ResourceListInput {
+  readonly credential: MintedToken;
+  readonly query?: string;
+  readonly parentResource?: ResourceRef;
+  readonly cursor?: string;
+  /** Soft cap; producers MAY return fewer rows. */
+  readonly pageSize?: number;
+}
+
+export interface ResourceListItem {
+  /** Provider-opaque id stored in `BiomeInstallationResource.selector`. */
+  readonly id: string;
+  /** Human-readable label rendered by the install wizard. */
+  readonly label: string;
+  /** Optional secondary description (e.g. repo description, channel topic). */
+  readonly description?: string;
+  /**
+   * Free-form metadata the install wizard MAY display (branch count,
+   * member count, last-activity timestamp). Provider-opaque to the
+   * platform — never used for routing or authorization.
+   */
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+
+/** Registry-level reference: which provider's resource type. */
+export interface ResourceTypeRef {
+  readonly adapterKind: string;
+  readonly provider: string;
+  readonly type: string;
+}

package/src/adapter/lib/result.ts

@@ -0,0 +1,53 @@
+/**
+ * Tiny `Result<T, E>` envelope used by adapter-sdk contracts.
+ *
+ * Rationale: `WebhookVerifier.verify` and `EventMapper.map` run on a
+ * per-request hot path inside `integration-adapters-api`. Throwing
+ * across the in-process / sidecar boundary loses the typed error
+ * shape and bloats the receiving span with a stack trace. Returning
+ * `Result` keeps the contract symmetric across both hosting topologies
+ * and lets the receiver translate the typed error into a structured
+ * 4xx / 5xx without `instanceof` chains.
+ *
+ * Stays in this package (not platform-common) so the Kernel boundary
+ * holds: `@xemahq/adapter-sdk` MUST have zero runtime deps beyond
+ * `@xemahq/kernel-contracts/connector`.
+ */
+export type Result<T, E = AdapterError> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });
+
+/**
+ * Closed-set error reasons producers can surface to the registry.
+ * Receiver decides HTTP code; adapters MUST NOT throw raw `Error`s
+ * across the registry boundary.
+ */
+export type AdapterErrorReason =
+  | 'verification-failed'
+  | 'malformed-payload'
+  | 'unsupported-event'
+  | 'rate-limited'
+  | 'upstream-unavailable'
+  | 'unauthorized'
+  | 'not-found'
+  | 'internal';
+
+export interface AdapterError {
+  readonly reason: AdapterErrorReason;
+  readonly message: string;
+  /** Optional pointer to the offending field path inside the payload. */
+  readonly path?: string;
+  /** Provider-opaque retry hint, in seconds, when reason='rate-limited'. */
+  readonly retryAfterSec?: number;
+}
+
+export function adapterError(
+  reason: AdapterErrorReason,
+  message: string,
+  extra?: Pick<AdapterError, 'path' | 'retryAfterSec'>,
+): AdapterError {
+  return { reason, message, ...extra };
+}

package/src/adapter/lib/sidecar-contract.ts

@@ -0,0 +1,169 @@
+import type { ProviderOnboardingManifest } from '@xemahq/kernel-contracts/connector';
+
+import type { OutboundActionResult } from './action';
+import type { ResourceListItem } from './resource';
+import type { AdapterError, Result } from './result';
+import type { MappedEnvelope } from './webhook';
+
+/**
+ * HTTP contract spoken between `integration-adapters-api` (host) and a
+ * `biome-adapter-host` sidecar pod (one per third-party biome).
+ *
+ * The sidecar loads a single biome package's `IntegrationProviderModule`
+ * in its own Node process and exposes every method over HTTP. The host
+ * wraps the remote shape with `RemoteProviderModule` so the
+ * `ProviderRegistry` registers it just like any in-process module —
+ * topology stays invisible to call sites.
+ *
+ * Why HTTP and not gRPC: every Xema service already speaks HTTP +
+ * service-token auth. Adding a gRPC stack to the host service for one
+ * biome protocol would force CI, observability, and security tooling
+ * to grow a second protocol. The performance gap doesn't matter at the
+ * webhook arrival rates we expect (≤ 100 rps per biome).
+ *
+ * All endpoints carry `X-Biome-Id` for the receiving sidecar to
+ * cross-check its own module's id, plus a service token bound to the
+ * `(orgId, biomeInstallationId)` posture pinned at dispatch time.
+ *
+ * Errors: every method returns `Result<T>`. Sidecar failures
+ * (`upstream-unavailable`, `internal`) flow as typed errors instead of
+ * HTTP 5xx — the host's `RemoteProviderModule` translates HTTP layer
+ * faults into the same shape so the registry doesn't branch on
+ * topology.
+ */
+
+/** Provider metadata the host fetches once at registration time. */
+export interface SidecarManifestResponse {
+  readonly adapterKind: string;
+  readonly provider: string;
+  readonly displayName: string;
+  readonly credentialKind: string;
+  /** Sorted list of resource types the sidecar exposes via list. */
+  readonly resourceTypes: readonly string[];
+  /** Sorted list of action names the sidecar exposes via execute. */
+  readonly actionNames: readonly string[];
+  /** Signature of the verifier the sidecar will run (algorithm + header). */
+  readonly verifier: {
+    readonly algorithm: string;
+    readonly signatureHeader: string;
+    readonly secretSource: string;
+  };
+  /** True iff the loaded module declares `webhook.orgResolver`. */
+  readonly hasOrgResolver: boolean;
+  /**
+   * Install-wizard onboarding metadata the sidecar declares for itself.
+   * The host forwards this verbatim through `GET /adapters/providers` so
+   * third-party adapters render in the install UI without code changes
+   * on the host.
+   */
+  readonly onboarding: ProviderOnboardingManifest;
+}
+
+/** Body for `POST /verify`. Raw body is base64'd for JSON safety. */
+export interface SidecarVerifyRequest {
+  readonly rawBodyBase64: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly secret: string;
+}
+
+/** Body for `POST /map-event`. */
+export interface SidecarMapEventRequest {
+  readonly rawEvent: unknown;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+export type SidecarMapEventResponse =
+  | { readonly outcome: 'mapped'; readonly envelope: MappedEnvelope }
+  | { readonly outcome: 'ignored' };
+
+/** Body for `POST /idempotency-key`. */
+export interface SidecarIdempotencyKeyRequest {
+  readonly rawBody: unknown;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+export interface SidecarIdempotencyKeyResponse {
+  readonly key: string;
+}
+
+/**
+ * Body for `POST /resolve-org`. The host already resolved `(orgId,
+ * orgIntegrationId)` candidates via the `OrgIntegrationLookup` —
+ * sidecars don't get raw Prisma access, so they return whatever the
+ * payload yields and the host calls its lookup on the returned
+ * external identifier.
+ */
+export interface SidecarResolveOrgRequest {
+  readonly rawBody: unknown;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+export type SidecarResolveOrgResponse =
+  | {
+      readonly outcome: 'matched';
+      readonly externalInstallationId: string;
+    }
+  | { readonly outcome: 'unbound' };
+
+/** Body for `POST /resources/:type`. */
+export interface SidecarListResourcesRequest {
+  readonly credential: SidecarMintedToken;
+  readonly query?: string;
+  readonly pageSize?: number;
+  readonly parentResource?: { readonly type: string; readonly id: string };
+}
+
+export interface SidecarListResourcesResponse {
+  readonly items: readonly Result<ResourceListItem>[];
+}
+
+/** Body for `POST /actions/:action`. Mirrors the in-process signature. */
+export interface SidecarExecuteActionRequest {
+  readonly credential: SidecarMintedToken;
+  readonly params: unknown;
+}
+
+export type SidecarExecuteActionResponse = Result<OutboundActionResult, AdapterError>;
+
+/**
+ * Token shape the host passes through to sidecars. Stays narrow so a
+ * third-party sidecar can't accidentally peek at the raw credential.
+ * Matches the host-side `MintedToken` from `@xemahq/kernel-contracts/connector`
+ * but redeclared here to keep the SDK independent.
+ */
+export interface SidecarMintedToken {
+  readonly tokenType: string;
+  readonly accessToken: string;
+  readonly expiresAt?: string;
+  readonly providerHints?: Readonly<Record<string, string>>;
+}
+
+/**
+ * URL paths the sidecar host MUST serve. Centralized so the host's
+ * proxy adapter and the sidecar's NestJS controllers never drift.
+ * Keep these stable — operators script against them.
+ */
+export const SIDECAR_PATHS = {
+  Manifest: '/manifest',
+  Verify: '/webhook/verify',
+  MapEvent: '/webhook/map-event',
+  IdempotencyKey: '/webhook/idempotency-key',
+  ResolveOrg: '/webhook/resolve-org',
+  ListResources: (type: string): string => `/resources/${encodeURIComponent(type)}`,
+  ExecuteAction: (action: string): string => `/actions/${encodeURIComponent(action)}`,
+  Health: '/health',
+} as const;
+
+/**
+ * Headers every sidecar request carries. The host injects them; the
+ * sidecar validates them. `X-Biome-Id` is the cross-check that the
+ * sidecar's loaded module matches the host's expectation — if a
+ * sidecar is rebuilt around the wrong biome, the host's first call
+ * fails fast.
+ */
+export const SIDECAR_HEADERS = {
+  BiomeId: 'x-biome-id',
+  WorkflowRunId: 'x-workflow-run-id',
+  /** Service-token auth; sidecar verifies issuer + audience. */
+  Authorization: 'authorization',
+} as const;

package/src/adapter/lib/webhook.ts

@@ -0,0 +1,142 @@
+import type { Result } from './result';
+
+/**
+ * Webhook signature verification contract. The registry calls
+ * `verify` BEFORE attempting to parse the body — fail-fast on bad
+ * signatures so untrusted payloads never reach the event mapper.
+ *
+ * `secretSource` lets the registry know how to source the verifying
+ * material:
+ *   - `org-integration-secret`: the per-`OrgIntegration` encrypted
+ *     blob — the registry decrypts and passes the plaintext as
+ *     `input.secret`.
+ *   - `provider-shared`: a single platform-wide secret managed in
+ *     `integration-adapters-api` (used for providers that don't have
+ *     per-installation secrets, e.g. some SaaS shared webhook tokens).
+ */
+export interface WebhookVerifier {
+  readonly signatureHeader: string;
+  readonly algorithm: WebhookSignatureAlgorithm;
+  readonly secretSource: 'org-integration-secret' | 'provider-shared';
+  /**
+   * Pure verification function. Inputs are the raw body bytes plus the
+   * already-collected request headers (lower-cased keys) and the secret
+   * resolved from `secretSource`. Implementations MUST be constant-time
+   * for HMAC comparisons (use a library helper like `timingSafeEqual`).
+   */
+  verify(input: WebhookVerifyInput): Result<void>;
+}
+
+export type WebhookSignatureAlgorithm =
+  | 'hmac-sha256'
+  | 'hmac-sha1'
+  | 'ed25519'
+  | 'none';
+
+export interface WebhookVerifyInput {
+  readonly rawBody: Uint8Array;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly secret: string;
+}
+
+/**
+ * Canonical envelope payload + discriminators the registry persists
+ * + forwards to the owning domain service. `entityKind` MUST match
+ * one of the entityKinds the adapter declared in its manifest, and
+ * `payload` MUST conform to the canonical envelope schema for that
+ * `(adapterKind, entityKind)` pair (per `@xemahq/kernel-contracts/connector`).
+ *
+ * `null` means "ignore this delivery" — used for provider housekeeping
+ * events (e.g. GitHub `ping`) that shouldn't trigger any downstream
+ * workflow. Returning `null` is NOT a failure mode — the registry
+ * still records a `WebhookDelivery` row (for dedup audit) but does
+ * not forward to the domain service.
+ */
+export interface MappedEnvelope {
+  readonly entityKind: string;
+  readonly event: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  /** Provider-native id surfaced for cross-provider correlation. */
+  readonly externalId?: string;
+  /** Provider-native parent key (e.g. SCM repo full name). */
+  readonly externalSpaceKey?: string;
+  /**
+   * Optional per-envelope adapterKind override. Used by providers that
+   * span multiple adapter kinds on a single webhook URL (e.g. Atlassian
+   * mixes Confluence/documentation and Jira/tracker; GitLab mixes SCM
+   * and tracker). When unset, the registry uses the provider module's
+   * declared `adapterKind` from `IntegrationProviderModule`. When set,
+   * MUST be a kind registered with `registerEnvelopeSchema` so the
+   * forwarder routes to the right domain service.
+   */
+  readonly adapterKindOverride?: string;
+}
+
+/**
+ * Converts a raw provider event into the canonical envelope shape.
+ * Pure: no I/O, no network calls. Idempotent — the registry MAY
+ * replay deliveries when the outbox worker is catching up.
+ *
+ * Headers are surfaced because several providers (GitHub, Gitea,
+ * GitLab, Atlassian) put the event-type discriminator on a header
+ * (`x-github-event`, `x-gitea-event`, `x-gitlab-event`, …) rather
+ * than on the payload. Providers whose discriminator is already on
+ * the payload can ignore the second argument.
+ */
+export interface EventMapper {
+  map(input: EventMapperInput): Result<MappedEnvelope | null>;
+}
+
+export interface EventMapperInput {
+  readonly rawEvent: unknown;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+/**
+ * Pulls a deterministic dedup key from the raw event. Today this is
+ * the provider's delivery id header (e.g. GitHub's `x-github-delivery`)
+ * or a synthetic `{provider}:{event-id}` for providers that don't
+ * stamp one. MUST be stable across replays: the registry uses the key
+ * as the unique constraint on the `WebhookDelivery` table.
+ */
+export type IdempotencyKeyExtractor = (input: {
+  readonly rawBody: unknown;
+  readonly headers: Readonly<Record<string, string>>;
+}) => string;
+
+/**
+ * Derives `(orgId, orgIntegrationId)` from a raw provider event. This
+ * is what the registry-driven webhook router uses to scope incoming
+ * traffic to the right tenant — every provider has its own rule (GitHub
+ * uses `installation.id`, GitLab a project id, Slack a team id, etc.),
+ * so the module owns the mapping.
+ *
+ * Return `null` when the event lacks tenant context (housekeeping
+ * pings, provider-wide health-checks). The router treats `null` the
+ * same as a `null` event-mapper result — record the delivery for audit,
+ * forward nothing.
+ *
+ * Implementations call the registry's lookup helpers (passed in as
+ * `lookup`) instead of reaching into Prisma directly so the kernel
+ * stays free of persistence imports.
+ */
+export interface WebhookOrgResolver {
+  resolve(input: {
+    readonly rawBody: unknown;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly lookup: OrgIntegrationLookup;
+  }): Promise<{ orgId: string; orgIntegrationId: string } | null>;
+}
+
+export interface OrgIntegrationLookup {
+  /**
+   * Find the `OrgIntegration` row whose provider-native id matches the
+   * supplied `externalId`. Returns `null` for unbound installations so
+   * the router can skip the dispatch (and surface "unbound install"
+   * telemetry) instead of throwing.
+   */
+  byExternalInstallationId(
+    provider: string,
+    externalInstallationId: string,
+  ): Promise<{ orgId: string; orgIntegrationId: string } | null>;
+}

package/src/agent-workspace/index.ts

@@ -0,0 +1,7 @@
+export * from './lib/mount-source';
+export * from './lib/mount-resolver';
+export * from './lib/refid-resolver';
+export * from './lib/workspace-renderer';
+export * from './lib/registries';
+export * from './lib/errors';
+export * from './lib/resolvers';

package/src/agent-workspace/lib/errors/error-codes.ts

@@ -0,0 +1,44 @@
+/**
+ * Closed enum of every error this SDK + workspace-proxy mount endpoint can
+ * surface. Every enum value maps deterministically to an HTTP status via
+ * `mountResolverErrorHttpStatus()`.
+ *
+ * Adding a new code requires updating both the enum AND the status map in
+ * the same PR. CI is intentionally not enforcing this — readers should
+ * treat the map as the closed extension point.
+ */
+export enum MountResolverErrorCode {
+  // 4xx — caller faults
+  PlanInvalid = 'MOUNT_PLAN_INVALID',
+  PlanDuplicatePath = 'MOUNT_PLAN_DUPLICATE_PATH',
+  PlanSpecMismatch = 'MOUNT_PLAN_SPEC_MISMATCH',
+  ActorUnauthorized = 'MOUNT_ACTOR_UNAUTHORIZED',
+  ActorForbidden = 'MOUNT_ACTOR_FORBIDDEN',
+  SourceNotFound = 'MOUNT_SOURCE_NOT_FOUND',
+  PayloadTooLarge = 'MOUNT_PAYLOAD_TOO_LARGE',
+  // 5xx — proxy / upstream faults
+  UpstreamBadGateway = 'MOUNT_UPSTREAM_BAD_GATEWAY',
+  UpstreamUnavailable = 'MOUNT_UPSTREAM_UNAVAILABLE',
+  UpstreamTimeout = 'MOUNT_UPSTREAM_TIMEOUT',
+  InsufficientStorage = 'MOUNT_INSUFFICIENT_STORAGE',
+  Internal = 'MOUNT_INTERNAL',
+}
+
+const HTTP_STATUS_MAP: Readonly<Record<MountResolverErrorCode, number>> = {
+  [MountResolverErrorCode.PlanInvalid]: 400,
+  [MountResolverErrorCode.PlanDuplicatePath]: 409,
+  [MountResolverErrorCode.PlanSpecMismatch]: 422,
+  [MountResolverErrorCode.ActorUnauthorized]: 401,
+  [MountResolverErrorCode.ActorForbidden]: 403,
+  [MountResolverErrorCode.SourceNotFound]: 404,
+  [MountResolverErrorCode.PayloadTooLarge]: 413,
+  [MountResolverErrorCode.UpstreamBadGateway]: 502,
+  [MountResolverErrorCode.UpstreamUnavailable]: 503,
+  [MountResolverErrorCode.UpstreamTimeout]: 504,
+  [MountResolverErrorCode.InsufficientStorage]: 507,
+  [MountResolverErrorCode.Internal]: 500,
+};
+
+export function mountResolverErrorHttpStatus(code: MountResolverErrorCode): number {
+  return HTTP_STATUS_MAP[code];
+}

package/src/agent-workspace/lib/errors/index.ts

@@ -0,0 +1,3 @@
+export * from './error-codes';
+export * from './mount-plan-error';
+export * from './mount-resolver-error';

package/src/agent-workspace/lib/errors/mount-plan-error.ts

@@ -0,0 +1,29 @@
+import { MountResolverErrorCode } from './error-codes';
+
+/**
+ * Plan-validation faults — surfaced before any I/O begins. These are
+ * caller bugs (malformed plan, duplicate paths, spec mismatch). Workspace
+ * state is untouched.
+ */
+export abstract class MountPlanError extends Error {
+  abstract readonly code: MountResolverErrorCode;
+  readonly details: Readonly<Record<string, unknown>>;
+
+  constructor(message: string, details: Readonly<Record<string, unknown>> = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.details = details;
+  }
+}
+
+export class MountPlanInvalidError extends MountPlanError {
+  readonly code = MountResolverErrorCode.PlanInvalid;
+}
+
+export class MountPlanDuplicatePathError extends MountPlanError {
+  readonly code = MountResolverErrorCode.PlanDuplicatePath;
+}
+
+export class MountPlanWorkspaceSpecMismatchError extends MountPlanError {
+  readonly code = MountResolverErrorCode.PlanSpecMismatch;
+}