@devosurf/tesser-sdk 0.1.0-alpha.0

package/src/connector/index.ts

@@ -0,0 +1,529 @@
+// Connector authoring contract (ADR-0012) + connector-defined triggers (ADR-0013).
+// Auth is declared once and injected as a pre-authed ctx.http — the author never names a
+// token. Actions are typed calls returning OUR mapped stable shape. Triggers are typed
+// constructors symmetric to actions; the runtime owns delivery/registration/dedup.
+
+import type { Connector, Logger, Schema } from "../automation.js";
+import type { HarnessDef, HarnessRunRequest, HarnessRunResult } from "../harnesses.js";
+import type { NormalizedModelRequest, NormalizedModelResponse } from "../operators.js";
+import type { ConnectorTrigger } from "../triggers.js";
+import type { ClassifyError, TesserHttp } from "../internal/http.js";
+import type { StandardSchemaV1 } from "../internal/standard-schema.js";
+
+/** Any Standard Schema, keeping both its input (pre-parse: defaults optional) and
+ *  output (post-parse) types. Callers supply the INPUT shape; handlers receive OUTPUT. */
+export type AnySchema = StandardSchemaV1<any, any>;
+export type SchemaIn<S> = S extends StandardSchemaV1<infer I, any> ? I : never;
+export type SchemaOut<S> = S extends StandardSchemaV1<any, infer O> ? O : never;
+
+// ---- Provider facts (the Catalog entry shape; inline facts are promoted by codegen, ADR-0012) ----
+
+export interface OAuth2ProviderFacts {
+  authorizeUrl: string;
+  tokenUrl: string;
+  /** How the client authenticates at the token endpoint. Default "body". */
+  clientAuth?: "body" | "basic";
+  /** Scope list separator quirk. Default " ". */
+  scopeSeparator?: string;
+  /** Use PKCE on the auth-code flow. Default true (harmless where unsupported is false). */
+  pkce?: boolean;
+  /** Extra params some providers require (e.g. Google access_type=offline&prompt=consent). */
+  extraAuthorizeParams?: Record<string, string>;
+  extraTokenParams?: Record<string, string>;
+  /** Providers that rotate refresh tokens on every refresh. */
+  rotatesRefreshToken?: boolean;
+}
+
+export interface ProviderFacts {
+  id: string;
+  displayName?: string;
+  /** Default API base URL for connectors behind this provider. */
+  baseUrl?: string;
+  oauth2?: OAuth2ProviderFacts;
+  docsUrl?: string;
+}
+
+// ---- Auth declarations (declared once; placement applied by the runtime, ADR-0012) ----
+
+export interface OAuth2Auth {
+  readonly kind: "oauth2";
+  readonly provider?: string;
+  readonly scopes: readonly string[];
+  readonly flow: "auth_code" | "client_credentials";
+  readonly describe?: string;
+}
+
+export interface ApiKeyAuth {
+  readonly kind: "apiKey";
+  readonly in: "header" | "query";
+  readonly name: string;
+  readonly prefix?: string;
+  readonly describe?: string;
+}
+
+export interface BasicAuth {
+  readonly kind: "basic";
+  readonly describe?: string;
+}
+
+export interface CustomAuth {
+  readonly kind: "custom";
+  readonly describe?: string;
+  /** Field names the connect page collects (empty = connection is instantly ready). */
+  readonly fields?: readonly string[];
+  /** Programmatic signer — receives the outbound request and the credential fields. */
+  readonly sign: (
+    req: { url: URL; headers: Headers },
+    fields: Readonly<Record<string, string>>,
+  ) => void | Promise<void>;
+}
+
+export type AuthDecl = OAuth2Auth | ApiKeyAuth | BasicAuth | CustomAuth;
+
+export function oauth2(opts: {
+  provider?: string;
+  scopes: readonly string[];
+  flow?: "auth_code" | "client_credentials";
+  describe?: string;
+}): OAuth2Auth {
+  return Object.freeze({
+    kind: "oauth2" as const,
+    scopes: Object.freeze([...opts.scopes]),
+    flow: opts.flow ?? "auth_code",
+    ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
+    ...(opts.describe !== undefined ? { describe: opts.describe } : {}),
+  });
+}
+
+export function apiKey(opts: {
+  in?: "header" | "query";
+  name?: string;
+  prefix?: string;
+  describe?: string;
+}): ApiKeyAuth {
+  return Object.freeze({
+    kind: "apiKey" as const,
+    in: opts?.in ?? "header",
+    name: opts?.name ?? "Authorization",
+    ...(opts?.prefix !== undefined ? { prefix: opts.prefix } : {}),
+    ...(opts?.describe !== undefined ? { describe: opts.describe } : {}),
+  });
+}
+
+export function basic(opts?: { describe?: string }): BasicAuth {
+  return Object.freeze({
+    kind: "basic" as const,
+    ...(opts?.describe !== undefined ? { describe: opts.describe } : {}),
+  });
+}
+
+export function customAuth(opts: {
+  describe?: string;
+  fields?: readonly string[];
+  sign: CustomAuth["sign"];
+}): CustomAuth {
+  return Object.freeze({
+    kind: "custom" as const,
+    sign: opts.sign,
+    ...(opts.describe !== undefined ? { describe: opts.describe } : {}),
+    ...(opts.fields !== undefined ? { fields: Object.freeze([...opts.fields]) } : {}),
+  });
+}
+
+// ---- Actions (ADR-0012): non-durable, run inside the caller's Step ----
+
+/** Runtime-resolved, log-masked credential reference — the escape hatch for non-standard
+ *  placement. Prefer ctx.http, which attaches the credential by declared placement. */
+export interface AuthRef {
+  readonly kind: AuthDecl["kind"];
+  /** Which mode of a named auth map this connection used (undefined for single-auth). */
+  readonly mode?: string;
+  /** Credential fields (e.g. access_token, api_key, username, password). Values are
+   *  masked in logs by the runtime. */
+  readonly fields: Readonly<Record<string, string>>;
+}
+
+export interface ActionCtx {
+  /** Pre-authed, base-URL'd client. Status → RetryableError/TerminalError per ADR-0012. */
+  readonly http: TesserHttp;
+  readonly auth: AuthRef;
+  /** Auto-derived (runId + step + occurrence); attach to provider idempotency headers. */
+  readonly idempotencyKey?: string;
+  readonly logger: Logger;
+}
+
+export interface ModelProviderSpec {
+  readonly aliases?: Record<string, string>;
+  readonly call: (ctx: ActionCtx, request: NormalizedModelRequest) => Promise<NormalizedModelResponse>;
+}
+
+export interface HarnessProviderSpec {
+  readonly adapter: string;
+  readonly run: (
+    ctx: ActionCtx,
+    request: HarnessRunRequest<unknown>,
+    def: HarnessDef,
+  ) => Promise<HarnessRunResult<unknown>>;
+}
+
+/** I = caller-facing input (schema input type), PI = parsed input handed to run,
+ *  O = validated output. */
+export interface ActionDef<I, PI, O> {
+  readonly __action: true;
+  readonly describe?: string;
+  readonly input: StandardSchemaV1<I, PI>;
+  readonly output: Schema<O>;
+  /** Reads retry freely; writes retry only with an idempotency key (derived, ADR-0012). */
+  readonly safety: "read" | "write";
+  /** Explicit override of derived retry-safety. */
+  readonly retrySafe?: boolean;
+  readonly classifyError?: ClassifyError;
+  readonly run: (ctx: ActionCtx, input: PI) => Promise<O>;
+}
+
+export type AnyAction = ActionDef<any, any, any>;
+export type ActionsTree = { [key: string]: AnyAction | ActionsTree };
+
+export function action<IS extends AnySchema, OS extends AnySchema>(def: {
+  describe?: string;
+  input: IS;
+  output: OS;
+  safety?: "read" | "write";
+  retrySafe?: boolean;
+  classifyError?: ClassifyError;
+  /** Receives the PARSED input (defaults applied); returns the value `output` validates. */
+  run: (ctx: ActionCtx, input: SchemaOut<IS>) => Promise<SchemaIn<OS>>;
+}): ActionDef<SchemaIn<IS>, SchemaOut<IS>, SchemaOut<OS>> {
+  if (!def?.input || !def?.output || typeof def?.run !== "function") {
+    throw new TypeError("action: requires { input, output, run }");
+  }
+  return Object.freeze({
+    __action: true as const,
+    input: def.input,
+    output: def.output,
+    safety: def.safety ?? "write",
+    run: def.run,
+    ...(def.describe !== undefined ? { describe: def.describe } : {}),
+    ...(def.retrySafe !== undefined ? { retrySafe: def.retrySafe } : {}),
+    ...(def.classifyError !== undefined ? { classifyError: def.classifyError } : {}),
+  }) as never;
+}
+
+export function isAction(node: unknown): node is AnyAction {
+  return typeof node === "object" && node !== null && (node as AnyAction).__action === true;
+}
+
+// ---- Webhook receive (connector-level, ADR-0013) ----
+
+export interface InboundWebhookEvent {
+  readonly headers: Record<string, string>;
+  readonly query: Record<string, string>;
+  readonly rawBody: Uint8Array;
+  /** Parsed JSON body, or undefined when the body is not JSON. */
+  readonly json: unknown;
+}
+
+export type VerifyScheme =
+  | {
+      kind: "hmacSha256";
+      header: string;
+      prefix?: string;
+      encoding: "hex" | "base64";
+    }
+  | { kind: "slackSigning" }
+  | {
+      kind: "custom";
+      verify: (req: InboundWebhookEvent, secret: string) => boolean | Promise<boolean>;
+    }
+  | { kind: "none" };
+
+export const verify = {
+  hmacSha256(opts: { header: string; prefix?: string; encoding?: "hex" | "base64" }): VerifyScheme {
+    return Object.freeze({
+      kind: "hmacSha256" as const,
+      header: opts.header,
+      encoding: opts.encoding ?? "hex",
+      ...(opts.prefix !== undefined ? { prefix: opts.prefix } : {}),
+    });
+  },
+  slackSigning(): VerifyScheme {
+    return Object.freeze({ kind: "slackSigning" as const });
+  },
+  custom(fn: (req: InboundWebhookEvent, secret: string) => boolean | Promise<boolean>): VerifyScheme {
+    return Object.freeze({ kind: "custom" as const, verify: fn });
+  },
+  none(): VerifyScheme {
+    return Object.freeze({ kind: "none" as const });
+  },
+};
+
+export interface IdentifiedEvent {
+  /** Provider event name a trigger's `event` matches against (e.g. "issues", "message"). */
+  event: string;
+  /** Provider delivery id used for dedup; fall back to a payload hash when absent. */
+  deliveryId?: string;
+  /** Provider-side account identity (team id, installation id) to resolve the Connection. */
+  connectionHint?: string;
+  /** The payload handed to the trigger's map(); defaults to the request JSON. */
+  payload?: unknown;
+}
+
+export interface WebhookReceive {
+  verify: VerifyScheme;
+  /** Pull event name / delivery id / connection identity out of any inbound request.
+   *  Return null for requests that are not events (the runtime 400s them). */
+  identify: (req: InboundWebhookEvent) => IdentifiedEvent | null;
+  /** Endpoint-verification handshakes (e.g. Slack url_verification): return the response
+   *  body to answer with, or null when the request is a normal event. */
+  challenge?: (req: InboundWebhookEvent) => string | null;
+}
+
+// ---- Connector triggers (ADR-0013) ----
+
+export interface RegistrationTarget {
+  /** Our ingress URL — stable per automation+trigger; never changes on redeploy. */
+  url: string;
+  /** The signing secret (we generate it in auto mode; the human pastes it in manual mode). */
+  secret: string;
+}
+
+export interface AutoRegistration<I> {
+  mode: "auto";
+  /** Create the provider-side hook using the brokered token (ctx.http). */
+  create: (
+    ctx: ActionCtx,
+    reg: RegistrationTarget,
+    params: I,
+  ) => Promise<{ externalId?: string; state?: unknown } | void>;
+  /** Remove the provider-side hook on undeploy (no orphaned hooks). */
+  destroy?: (
+    ctx: ActionCtx,
+    reg: { externalId?: string; state?: unknown },
+    params: I,
+  ) => Promise<void>;
+}
+
+export interface ManualRegistration<I> {
+  mode: "manual";
+  /** Connect-page copy: exact steps, with the ingress URL + secret available to interpolate. */
+  instructions: (reg: RegistrationTarget, params: I) => string;
+}
+
+export interface WebhookTriggerDecl<IS extends AnySchema = AnySchema, OS extends AnySchema = AnySchema> {
+  readonly __trigger: "webhook";
+  readonly describe?: string;
+  readonly input: IS;
+  readonly output: OS;
+  /** Which identified provider event this trigger consumes. */
+  readonly event: string;
+  /** Raw provider payload → our stable typed payload; return null to skip (fine filter). */
+  readonly map: (
+    payload: unknown,
+    params: SchemaOut<IS>,
+  ) => SchemaIn<OS> | null | Promise<SchemaIn<OS> | null>;
+  readonly register: AutoRegistration<SchemaOut<IS>> | ManualRegistration<SchemaOut<IS>>;
+}
+
+export interface PollTriggerDecl<
+  IS extends AnySchema = AnySchema,
+  OS extends AnySchema = AnySchema,
+  Item = unknown,
+> {
+  readonly __trigger: "poll";
+  readonly describe?: string;
+  readonly input: IS;
+  readonly output: OS;
+  /** Connector-declared cadence; automation-author override is clamped to `floor`. */
+  readonly interval?: { default: string; floor?: string };
+  /** Which way the provider's natural list reads. New items fire oldest-first either way.
+   *  Default "newest-first" (how most list APIs sort). */
+  readonly order?: "newest-first" | "oldest-first";
+  /** Return the provider's natural current list — no cursor bookkeeping (runtime-owned
+   *  windowed seen-set). Opt into cursor mode by returning { items, nextCursor }. */
+  readonly poll: (
+    ctx: ActionCtx,
+    params: SchemaOut<IS>,
+    cursor: unknown,
+  ) => Promise<Item[] | { items: Item[]; nextCursor?: unknown }>;
+  readonly dedupeKey: (item: Item) => string;
+  /** Raw item → stable typed payload (default: identity). */
+  readonly map?: (item: Item, params: SchemaOut<IS>) => SchemaIn<OS> | Promise<SchemaIn<OS>>;
+}
+
+export type AnyTriggerDecl = WebhookTriggerDecl<AnySchema, AnySchema> | PollTriggerDecl<AnySchema, AnySchema, any>;
+export type TriggersDecl = Record<string, AnyTriggerDecl>;
+
+export const trigger = {
+  webhook<IS extends AnySchema, OS extends AnySchema>(def: {
+    describe?: string;
+    input: IS;
+    output: OS;
+    event: string;
+    map: (
+      payload: unknown,
+      params: SchemaOut<IS>,
+    ) => SchemaIn<OS> | null | Promise<SchemaIn<OS> | null>;
+    register: AutoRegistration<SchemaOut<IS>> | ManualRegistration<SchemaOut<IS>>;
+  }): WebhookTriggerDecl<IS, OS> {
+    if (!def?.input || !def?.output || !def?.event || typeof def?.map !== "function" || !def?.register) {
+      throw new TypeError("trigger.webhook: requires { input, output, event, map, register }");
+    }
+    return Object.freeze({ __trigger: "webhook" as const, ...def });
+  },
+  poll<IS extends AnySchema, OS extends AnySchema, Item = SchemaIn<OS>>(def: {
+    describe?: string;
+    input: IS;
+    output: OS;
+    interval?: { default: string; floor?: string };
+    order?: "newest-first" | "oldest-first";
+    poll: (
+      ctx: ActionCtx,
+      params: SchemaOut<IS>,
+      cursor: unknown,
+    ) => Promise<Item[] | { items: Item[]; nextCursor?: unknown }>;
+    dedupeKey: (item: Item) => string;
+    map?: (item: Item, params: SchemaOut<IS>) => SchemaIn<OS> | Promise<SchemaIn<OS>>;
+  }): PollTriggerDecl<IS, OS, Item> {
+    if (!def?.input || !def?.output || typeof def?.poll !== "function" || typeof def?.dedupeKey !== "function") {
+      throw new TypeError("trigger.poll: requires { input, output, poll, dedupeKey }");
+    }
+    return Object.freeze({ __trigger: "poll" as const, ...def });
+  },
+};
+
+// ---- defineConnector ----
+
+/** Optional-arg ergonomics: when every field is optional (or has a default), the call
+ *  needs no argument at all. */
+type ClientFn<I, O> = undefined extends I
+  ? (input?: I) => Promise<O>
+  : Record<string, never> extends I
+    ? (input?: I) => Promise<O>
+    : (input: I) => Promise<O>;
+
+export type ClientFromActions<A> = {
+  readonly [K in keyof A]: A[K] extends ActionDef<infer I, any, infer O>
+    ? ClientFn<I, O>
+    : A[K] extends ActionsTree
+      ? ClientFromActions<A[K]>
+      : never;
+};
+
+export type TriggerConstructors<T extends TriggersDecl> = {
+  readonly [K in keyof T]: (
+    params: SchemaIn<T[K]["input"]> & { connection?: string } & (T[K] extends { __trigger: "poll" }
+        ? { every?: string }
+        : Record<never, never>),
+  ) => ConnectorTrigger<SchemaOut<T[K]["output"]>>;
+};
+
+export interface ConnectorSpec<A extends ActionsTree, T extends TriggersDecl> {
+  id: string;
+  describe?: string;
+  /** Provider id referencing the Catalog, or inline facts (promoted by codegen, ADR-0012). */
+  provider?: string | ProviderFacts;
+  /** API base URL; defaults to the provider's. */
+  baseUrl?: string;
+  /** One declaration, or a named map for multiple modes (e.g. { oauth, token }). */
+  auth: AuthDecl | Record<string, AuthDecl>;
+  /** Headers every ctx.http request carries (e.g. Accept/API-version/User-Agent). */
+  defaultHeaders?: Record<string, string>;
+  /** Provider idempotency header — when declared, the runtime auto-attaches ctx.idempotencyKey. */
+  idempotencyHeader?: string;
+  actions: A;
+  triggers?: T;
+  /** Direct model-call capability (ADR-0016). Runtime-owned; not exposed as ctx.connections actions. */
+  modelProvider?: ModelProviderSpec;
+  /** Sandboxed external runner capability (ADR-0019). Runtime-owned; not exposed as an Action. */
+  harnessProvider?: HarnessProviderSpec;
+  /** Required when any trigger is webhook-strategy. */
+  webhook?: WebhookReceive;
+  /** Sample outputs by dotted action path (and `trigger:<id>` for trigger payloads) —
+   *  powers auto-mocked tests (ADR-0008) and connect-page previews. */
+  samples?: Record<string, unknown>;
+}
+
+/** The full connector object: the automation-facing Connector<client> plus trigger
+ *  constructors plus the raw spec for build-time extraction. */
+export interface ConnectorInstance<A extends ActionsTree, T extends TriggersDecl>
+  extends Connector<ClientFromActions<A>> {
+  readonly triggers: TriggerConstructors<T>;
+  /** Build-time/manifest access to the declaration — not for automation code. */
+  readonly __connector: ConnectorSpec<A, T>;
+  /** Narrowed override so `.perUser()` keeps the trigger constructors. */
+  perUser(): ConnectorInstance<A, T>;
+}
+
+const CONNECTOR_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const AUTH_KINDS = new Set(["oauth2", "apiKey", "basic", "custom"]);
+
+function isAuthDecl(v: unknown): v is AuthDecl {
+  return typeof v === "object" && v !== null && AUTH_KINDS.has((v as AuthDecl).kind);
+}
+
+export function defineConnector<
+  A extends ActionsTree,
+  T extends TriggersDecl = Record<string, never>,
+>(spec: ConnectorSpec<A, T>): ConnectorInstance<A, T> {
+  if (!CONNECTOR_ID.test(spec?.id ?? "")) {
+    throw new TypeError(`defineConnector: id "${String(spec?.id)}" must be kebab-case`);
+  }
+  if (!spec.auth || (!isAuthDecl(spec.auth) && Object.values(spec.auth).every((a) => !isAuthDecl(a)))) {
+    throw new TypeError(`defineConnector(${spec.id}): auth must be oauth2/apiKey/basic/customAuth (or a named map)`);
+  }
+  if ((!spec.actions || Object.keys(spec.actions).length === 0) && !spec.modelProvider && !spec.harnessProvider) {
+    throw new TypeError(`defineConnector(${spec.id}): at least one action, modelProvider, or harnessProvider is required`);
+  }
+  const normalized = { ...spec, actions: (spec.actions ?? ({} as A)) } as ConnectorSpec<A, T>;
+  const triggers = normalized.triggers ?? ({} as T);
+  const hasWebhookTrigger = Object.values(triggers).some((t) => t.__trigger === "webhook");
+  if (hasWebhookTrigger && !normalized.webhook) {
+    throw new TypeError(
+      `defineConnector(${spec.id}): webhook-strategy triggers require the connector-level webhook { verify, identify }`,
+    );
+  }
+
+  const constructors: Record<string, (params: Record<string, unknown>) => ConnectorTrigger<unknown>> = {};
+  for (const [triggerId, decl] of Object.entries(triggers)) {
+    void decl;
+    constructors[triggerId] = (params) => {
+      // `connection` and `every` are reserved platform params, not provider filters.
+      const { connection, every, ...rest } = params ?? {};
+      return Object.freeze({
+        kind: "connector" as const,
+        connectorId: normalized.id,
+        triggerId,
+        params: rest,
+        ...(connection !== undefined ? { connectionKey: String(connection) } : {}),
+        ...(every !== undefined ? { every: String(every) } : {}),
+      });
+    };
+  }
+
+  function make(scope: "workspace" | "per_user"): ConnectorInstance<A, T> {
+    const instance = {
+      id: normalized.id,
+      scope,
+      triggers: Object.freeze({ ...constructors }) as TriggerConstructors<T>,
+      __connector: normalized,
+      perUser(): ConnectorInstance<A, T> {
+        return make("per_user");
+      },
+    };
+    return Object.freeze(instance) as unknown as ConnectorInstance<A, T>;
+  }
+
+  return make("workspace");
+}
+
+export function isConnector(value: unknown): value is ConnectorInstance<ActionsTree, TriggersDecl> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { id?: unknown }).id === "string" &&
+    typeof (value as { __connector?: unknown }).__connector === "object"
+  );
+}
+
+export type { ClassifyError, TesserHttp } from "../internal/http.js";
+export type { Schema } from "../automation.js";

package/src/errors.ts

@@ -0,0 +1,46 @@
+// Errors control the retry policy (ADR-0002). Symbol branding keeps instanceof checks
+// honest across duplicated module instances (bundled server vs project artifact).
+
+const RETRYABLE = Symbol.for("tesser.error.retryable");
+const TERMINAL = Symbol.for("tesser.error.terminal");
+
+export interface RetryableErrorOptions {
+  cause?: unknown;
+  /** Hint from the provider (e.g. Retry-After) — the engine waits at least this long. */
+  retryAfterMs?: number | undefined;
+}
+
+/** Force a retry (also the default for an uncaught throw, up to maxAttempts). */
+export class RetryableError extends Error {
+  readonly retryAfterMs: number | undefined;
+
+  constructor(message: string, options?: RetryableErrorOptions) {
+    super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "RetryableError";
+    this.retryAfterMs = options?.retryAfterMs;
+    Object.defineProperty(this, RETRYABLE, { value: true });
+  }
+}
+
+/** Stop now — do not retry. On terminal failure, completed steps' `undo` run in reverse. */
+export class TerminalError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "TerminalError";
+    Object.defineProperty(this, TERMINAL, { value: true });
+  }
+}
+
+export function isRetryableError(err: unknown): err is RetryableError {
+  return (
+    err instanceof RetryableError ||
+    (typeof err === "object" && err !== null && RETRYABLE in err)
+  );
+}
+
+export function isTerminalError(err: unknown): err is TerminalError {
+  return (
+    err instanceof TerminalError ||
+    (typeof err === "object" && err !== null && TERMINAL in err)
+  );
+}

package/src/events.ts

@@ -0,0 +1,25 @@
+// Events: defined once, reused for emit + onEvent (+ future await). Project-scoped (ADR-0011).
+
+import type { StandardSchemaV1 } from "./internal/standard-schema.js";
+
+export interface EventDefinition<T> {
+  readonly name: string;
+  readonly schema: StandardSchemaV1<unknown, T>;
+  /** Phantom for inference; never set. */
+  readonly _payload?: T;
+}
+
+const EVENT_NAME = /^[a-z][a-z0-9]*([.-][a-z0-9]+)*$/;
+
+/** Define an event once; reuse it for emit + trigger (no stringly-typed drift). */
+export function defineEvent<T>(
+  name: string,
+  schema: StandardSchemaV1<unknown, T>,
+): EventDefinition<T> {
+  if (!EVENT_NAME.test(name)) {
+    throw new TypeError(
+      `defineEvent: "${name}" — event names are lower-case dot/dash-separated, e.g. "invoice.paid"`,
+    );
+  }
+  return Object.freeze({ name, schema });
+}

package/src/harnesses.ts

@@ -0,0 +1,76 @@
+import type { Schema, Serializable } from "./automation.js";
+
+export interface HarnessDef {
+  readonly __harness: true;
+  readonly connection: string;
+  readonly sandbox: "none" | "repo-readonly" | "repo-write";
+  readonly permissions: "read-only" | "workspace-write";
+  readonly timeout?: string;
+  readonly maxOutputBytes?: number;
+}
+
+export interface HarnessBudget {
+  invocations: number;
+  wallClock?: string;
+}
+
+export type HarnessMap = Record<string, HarnessDef>;
+
+export interface HarnessRunRequest<TOutput = unknown> {
+  prompt: string;
+  input?: Serializable;
+  output: Schema<TOutput>;
+  timeout?: string;
+  maxOutputBytes?: number;
+}
+
+export interface HarnessArtifact extends Record<string, Serializable> {
+  name: string;
+  kind: "transcript" | "log" | "patch" | "file" | "screenshot" | "json";
+  bytes?: number;
+  path?: string;
+  content?: string;
+}
+
+export interface HarnessRunResult<TOutput = unknown> extends Record<string, Serializable> {
+  output: TOutput & Serializable;
+  status: "completed" | "failed";
+  exitCode?: number;
+  artifacts: HarnessArtifact[];
+  transcript?: string;
+  adapter: string;
+  raw?: Serializable;
+}
+
+export type Harnesses<H extends HarnessMap = HarnessMap> = {
+  readonly [K in keyof H]: {
+    run<TOutput>(request: HarnessRunRequest<TOutput>): Promise<HarnessRunResult<TOutput>>;
+  };
+};
+
+export function harness(def: {
+  connection: string;
+  sandbox?: "none" | "repo-readonly" | "repo-write";
+  permissions?: "read-only" | "workspace-write";
+  timeout?: string;
+  maxOutputBytes?: number;
+}): HarnessDef {
+  if (!def || typeof def.connection !== "string" || def.connection.length === 0) {
+    throw new TypeError("harness: connection must name a declared Harness connection");
+  }
+  if (def.maxOutputBytes !== undefined && (!Number.isInteger(def.maxOutputBytes) || def.maxOutputBytes < 1)) {
+    throw new TypeError("harness: maxOutputBytes must be a positive integer");
+  }
+  return Object.freeze({
+    __harness: true as const,
+    connection: def.connection,
+    sandbox: def.sandbox ?? "repo-readonly",
+    permissions: def.permissions ?? "read-only",
+    ...(def.timeout !== undefined ? { timeout: def.timeout } : {}),
+    ...(def.maxOutputBytes !== undefined ? { maxOutputBytes: def.maxOutputBytes } : {}),
+  });
+}
+
+export function isHarnessDef(value: unknown): value is HarnessDef {
+  return typeof value === "object" && value !== null && (value as HarnessDef).__harness === true;
+}