@devosurf/tesser-sdk 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,36 @@
+# @devosurf/tesser-sdk
+
+The authoring SDK. One durable-function primitive; durability comes only from `ctx.step()`.
+
+> Status: **implemented.** Zero runtime dependencies; schemas through the Standard Schema interface (zod / valibot / arktype all fit). Connector *authoring* lives at `@devosurf/tesser-sdk/connector`; runtime/tooling machinery at `@devosurf/tesser-sdk/internal` (deliberately outside the stable facade). The compact agent-facing reference is [`llms.txt`](./llms.txt).
+
+```ts
+import { defineAutomation, onSchedule } from "@devosurf/tesser-sdk";
+import { github, slack } from "@devosurf/tesser-connectors";
+import { z } from "zod";
+
+export default defineAutomation({
+  id: "daily-digest",
+  trigger: onSchedule({ cron: "0 9 * * *", tz: "America/New_York" }),
+  connections: { github, slack },
+  output: z.object({ posted: z.boolean(), count: z.number() }),
+
+  run: async (_input, ctx) => {
+    // Plain TS control flow. Durability ONLY from ctx.step().
+    const issues = await ctx.step("fetch-open-issues", () =>
+      ctx.connections.github.issues.list({ state: "open", labels: ["bug"] }),
+    );
+    if (issues.length === 0) return { posted: false, count: 0 };
+
+    await ctx.step("post-to-slack", () =>
+      ctx.connections.slack.chat.postMessage({
+        channel: "#eng-standup",
+        text: `:bug: ${issues.length} open bugs today`,
+      }),
+    );
+    return { posted: true, count: issues.length };
+  },
+});
+```
+
+The agent never sees a token — `ctx.connections.*` are injected by the credential broker at call time (ADR-0004). To require a credential that may not exist yet, declare it on the def — `connections: { stripe }` for a connector, or `secrets: { … }` for a raw value; if it's missing on the target instance, deploy halts and a human is handed a connect link (ADR-0005, ADR-0010).

package/llms.txt

@@ -0,0 +1,90 @@
+# @devosurf/tesser-sdk — the authoring surface (for agents)
+
+One file = one automation. Write ordinary async TypeScript. THE ONE DURABILITY RULE:
+wrap every side effect (connector call, any external I/O, emit) in `ctx.step("name", fn)`.
+Suspensions (ctx.sleep / ctx.waitForSignal) are NOT side effects — never put them in a step.
+
+## Define an automation
+
+    import { defineAutomation, onSchedule, secret } from "@devosurf/tesser-sdk";
+    import { github, slack } from "@devosurf/tesser-connectors";
+    import { z } from "zod";
+
+    export default defineAutomation({
+      id: "daily-digest",                                   // kebab-case, = its directory name
+      trigger: onSchedule({ cron: "0 9 * * *", tz: "UTC" }),// exactly ONE trigger
+      connections: { github, slack },                       // typed map; mirrored on ctx.connections
+      secrets: { signingKey: secret({ describe: "…" }) },   // raw values; mirrored on ctx.secrets
+      input: z.object({ … }).optional(),                    // validates trigger payload
+      output: z.object({ … }),                              // validates the return value
+      retry: { maxAttempts: 3 },                            // default step retry policy
+      concurrency: { limit: 1, key: (i) => i.userId, onConflict: "queue" }, // or "drop"
+      run: async (input, ctx) => { …; return …; },
+    });
+
+## Triggers (pick one)
+
+    onWebhook({ input: zodSchema, respond: "async" | "sync" })   // POST /hooks/<project>/<id>
+    onSchedule({ cron: "0 9 * * *", tz: "America/New_York" })
+    onEvent(eventDef)                                            // project-scoped events
+    <connector>.triggers.<name>({ ...params, connection: "key"?, every: "5m"? })
+      // e.g. github.triggers.issueOpened({ repo: "acme/api" })
+      // `connection` names the connections-map entry when ambiguous; `every` overrides
+      // poll cadence (clamped to the connector's floor). Payload becomes the run input.
+
+## ctx — the runtime-injected context
+
+    await ctx.step("name", () => …, {            // THE durable checkpoint
+      retry: { maxAttempts: 5, backoff: { type: "exponential", base: "1s", max: "1h" } },
+      timeout: "30s",
+      idempotencyKey: "custom",                  // default: runId + step + occurrence
+      undo: (result) => …,                       // saga: runs in REVERSE on terminal failure
+    });
+    // Step results are journaled: must be plain data (string/number/boolean/null/bigint/
+    // Date/Map/Set/Uint8Array/arrays/objects). Returning a function/handle throws.
+    // The same step name in a loop is fine — occurrences are auto-disambiguated.
+    // Completed steps NEVER re-execute across retries/crashes/resumes.
+
+    ctx.connections.<key>.<…>.<action>(input)    // pre-authed typed connector calls —
+                                                 // ONLY inside a step; broker injects tokens
+    ctx.secrets.<key>                            // string value, masked in logs
+    await ctx.sleep("2h")                        // durable timer, zero idle cost
+    await ctx.waitForSignal("approval", { schema, timeout: "2d" })  // null on timeout
+    await ctx.emit(eventDef, payload)            // broadcast event — call INSIDE a step
+    ctx.request                                  // { headers, query, rawBody } (webhook only)
+    ctx.logger.info|warn|error(msg, meta?)
+    ctx.run                                      // { id, attempt, automationId }
+
+## Events (project-scoped)
+
+    export const invoicePaid = defineEvent("invoice.paid", z.object({ id: z.string() }));
+    // emitter:  await ctx.emit(invoicePaid, { id });   (inside a step)
+    // listener: trigger: onEvent(invoicePaid)          (payload = run input)
+
+## Errors control retries
+
+    throw new RetryableError("throttled", { retryAfterMs: 30_000 });  // retry (default for throws)
+    throw new TerminalError("bad input");                             // stop now; undos run
+    // Non-retry-safe connector WRITES never auto-retry unless the step sets `retry`.
+
+## Testing (colocate index.test.ts; `tesser test`)
+
+    import { createTest } from "@devosurf/tesser-testing";
+    const t = createTest({ automation });
+    const { result, steps, calls, status } = await t.run({
+      input: …,
+      mocks: { "step-name": (input) => mockedConnectorResult },  // step code still runs
+      connections: { slack: { chat: { postMessage: fn } } },     // or mock whole actions
+      signals: { approval: { approved: true } },
+      journal: [{ name: "step", result: recorded }],             // replay: skip execution
+    });
+    // Unmocked connector calls auto-mock from connector samples / output schemas.
+    // Time skips: crons, sleeps, retry backoff resolve instantly.
+
+## Rules that bite
+
+- Side effects outside ctx.step throw at run time. Wrap them.
+- Don't catch errors you didn't throw (suspension signals unwind through your code).
+- Step names: stable strings, no "$" prefix; steps never nest.
+- Deploy halts if a declared connection/secret is missing — a human completes a connect
+  link; you only poll `tesser connect --status`. You never see credential values.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@devosurf/tesser-sdk",
+  "version": "0.1.0-alpha.0",
+  "description": "Tesser authoring SDK — define automations as typed TypeScript.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./connector": "./src/connector/index.ts",
+    "./internal": "./src/internal/index.ts"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ]
+}

package/src/automation.ts

@@ -0,0 +1,258 @@
+// The one authoring primitive (ADR-0001) and the runtime-injected ctx surface.
+// Shape locked by the SDK grill — see docs/SCOPES.md §2 and ADR-0010/0011.
+
+import type { EventDefinition } from "./events.js";
+import type { HarnessBudget, HarnessMap, Harnesses } from "./harnesses.js";
+import { isHarnessDef } from "./harnesses.js";
+import type { StandardSchemaV1 } from "./internal/standard-schema.js";
+import type { AutomationBudget, ModelMap, OperatorMap, Operators } from "./operators.js";
+import { isModelDef, isOperatorDef } from "./operators.js";
+import type { Trigger } from "./triggers.js";
+
+/** A validation schema (Standard Schema — Zod / Valibot / ArkType). Our own name for the
+ *  spec interface; no third-party name in the surface (ADR-0004). */
+export type Schema<T> = StandardSchemaV1<unknown, T>;
+
+/** Values that can be journaled (persisted between steps). Returning anything else from a
+ *  step — a function, a stream, a live handle — is a compile (and runtime) error.
+ *  Date / Map / Set / bigint round-trip via an internal structured codec (ADR-0004). */
+export type Serializable =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | bigint
+  | Date
+  | Uint8Array
+  | Serializable[]
+  | ReadonlyArray<Serializable>
+  | Map<Serializable, Serializable>
+  | Set<Serializable>
+  | { [key: string]: Serializable };
+
+// ---- Connectors & secrets: declared on the def, mirrored on ctx (ADR-0004 / 0005 / 0010) ----
+
+/** A typed connector, imported from @devosurf/tesser-connectors. Identical on every Instance; holds
+ *  no credential. `.perUser()` selects per-end-user connection scope (default: workspace,
+ *  ADR-0005). */
+export interface Connector<TClient> {
+  readonly id: string;
+  readonly scope: "workspace" | "per_user";
+  /** Phantom for inference; never set. */
+  readonly _client?: TClient;
+  perUser(): Connector<TClient>;
+}
+
+export type ClientOf<C> = C extends Connector<infer T> ? T : never;
+
+/** A raw, non-connector secret declaration (ADR-0010): an API key, a webhook-signing secret.
+ *  Referenced by name on ctx.secrets; the value is injected at run time and masked in logs —
+ *  the author never sees it. The escape hatch for what a Connector can't cover. */
+export interface SecretDef {
+  readonly _secret: true;
+  readonly describe?: string;
+}
+
+export function secret(opts?: { describe?: string }): SecretDef {
+  return Object.freeze({
+    _secret: true as const,
+    ...(opts?.describe !== undefined ? { describe: opts.describe } : {}),
+  });
+}
+
+export type ConnectionMap = Record<string, Connector<unknown>>;
+export type SecretMap = Record<string, SecretDef>;
+
+/** Pre-authenticated typed connector clients; the broker injects the token at call time. */
+export type Connections<C extends ConnectionMap> = {
+  readonly [K in keyof C]: ClientOf<C[K]>;
+};
+/** Raw secret values, injected at run time, masked in logs. */
+export type Secrets<S extends SecretMap> = {
+  readonly [K in keyof S]: string;
+};
+
+// ---- ctx.step config ----
+
+export interface RetryPolicy {
+  maxAttempts: number;
+  backoff?:
+    | "exponential"
+    | "fixed"
+    | { type: "exponential" | "fixed"; base?: string; max?: string; jitter?: boolean };
+}
+
+export interface StepOpts<T> {
+  retry?: RetryPolicy;
+  timeout?: string;
+  /** Override the auto-derived (runId + name + occurrence) idempotency key for cross-run dedup. */
+  idempotencyKey?: string;
+  /** Opt-in saga rollback (ADR-0002): runs in reverse order if a later step fails terminally. */
+  undo?: (result: T) => unknown | Promise<unknown>;
+}
+
+export interface Logger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+}
+
+/** Raw inbound request — present only for webhook triggers (raw bytes are needed for HMAC). */
+export interface WebhookRequest {
+  readonly headers: Record<string, string>;
+  readonly query: Record<string, string>;
+  readonly rawBody: Uint8Array;
+}
+
+// ---- The runtime-injected context ----
+
+export interface Ctx<
+  C extends ConnectionMap = ConnectionMap,
+  S extends SecretMap = SecretMap,
+  O extends OperatorMap = OperatorMap,
+  H extends HarnessMap = HarnessMap,
+> {
+  /** The durable boundary. Wrap every side effect here; the output must be Serializable. (ADR-0002) */
+  step<T extends Serializable>(name: string, fn: () => Promise<T> | T, opts?: StepOpts<T>): Promise<T>;
+
+  /** Pre-authenticated typed connectors; tokens injected by the broker. (ADR-0004) */
+  readonly connections: Connections<C>;
+  /** Raw secret values, injected at run time, masked in logs. (ADR-0010) */
+  readonly secrets: Secrets<S>;
+  /** Automation-scoped Operator calls; each expands into model/tool Steps. */
+  readonly operators: Operators<O>;
+  /** Sandboxed external Harness runners. Call inside ctx.step. */
+  readonly harnesses: Harnesses<H>;
+
+  /** Durable timer — suspends the run at zero idle cost. Not a side effect → not in a step. */
+  sleep(duration: string): Promise<void>;
+  /** Durable suspend until an external Signal arrives (HITL, callbacks). Resolves null on timeout. */
+  waitForSignal<T>(name: string, opts: { schema: Schema<T>; timeout?: string }): Promise<T | null>;
+  /** Emit a Project-scoped Event (broadcast, at-least-once). A side effect → call inside a step. */
+  emit<T>(event: EventDefinition<T>, payload: T): Promise<void>;
+
+  /** Present only for webhook triggers. */
+  readonly request?: WebhookRequest;
+  readonly logger: Logger;
+  readonly run: { readonly id: string; readonly attempt: number; readonly automationId: string };
+}
+
+// ---- The one authoring primitive (ADR-0001) ----
+
+export interface AutomationDef<
+  TInput = unknown,
+  TOutput = unknown,
+  C extends ConnectionMap = ConnectionMap,
+  S extends SecretMap = SecretMap,
+  M extends ModelMap = ModelMap,
+  O extends OperatorMap = OperatorMap,
+  H extends HarnessMap = HarnessMap,
+> {
+  id: string;
+  trigger: Trigger<TInput>;
+  input?: Schema<TInput>;
+  output?: Schema<TOutput>;
+
+  /** Required connections — declared statically so the build extracts them WITHOUT running the
+   *  handler; mirrored on ctx.connections.<key>. (ADR-0005 / 0010) */
+  connections?: C;
+  /** Required raw secrets — same static-extraction guarantee; mirrored on ctx.secrets.<key>. */
+  secrets?: S;
+
+  /** Brokered direct LLM choices used by Operators. */
+  models?: M;
+  /** In-Automation LLM actors. Not deployable primitives. */
+  operators?: O;
+  /** Sandboxed external runners used only from deterministic Automation code. */
+  harnesses?: H;
+  /** Run-level operational caps. `budget.models` is mandatory when Operators are present. */
+  budget?: AutomationBudget & { harnesses?: HarnessBudget };
+
+  /** Operational config, co-located — no hidden GUI menus. `retry` is the per-run default; a
+   *  per-step `StepOpts.retry` overrides. Timeout is per-step only (durable waits make a
+   *  run-wide deadline meaningless). `onConflict` also covers schedule overlap. */
+  retry?: RetryPolicy;
+  concurrency?: {
+    limit: number;
+    key?: (input: TInput) => string;
+    onConflict?: "queue" | "drop";
+  };
+
+  run: (input: TInput, ctx: Ctx<C, S, O, H>) => Promise<TOutput>;
+}
+
+const AUTOMATION_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const TRIGGER_KINDS = new Set(["webhook", "schedule", "event", "connector"]);
+
+/** Define one complete automation. One file = one automation. */
+export function defineAutomation<
+  TInput,
+  TOutput,
+  C extends ConnectionMap = Record<string, never>,
+  S extends SecretMap = Record<string, never>,
+  M extends ModelMap = Record<string, never>,
+  O extends OperatorMap = Record<string, never>,
+  H extends HarnessMap = Record<string, never>,
+>(def: AutomationDef<TInput, TOutput, C, S, M, O, H>): AutomationDef<TInput, TOutput, C, S, M, O, H> {
+  if (!AUTOMATION_ID.test(def?.id ?? "")) {
+    throw new TypeError(
+      `defineAutomation: id "${String(def?.id)}" — ids are kebab-case ([a-z0-9-], max 64), e.g. "daily-digest"`,
+    );
+  }
+  if (!def.trigger || !TRIGGER_KINDS.has(def.trigger.kind)) {
+    throw new TypeError(
+      `defineAutomation(${def.id}): trigger must be onWebhook / onSchedule / onEvent or a connector trigger`,
+    );
+  }
+  if (typeof def.run !== "function") {
+    throw new TypeError(`defineAutomation(${def.id}): run must be an async function`);
+  }
+  for (const [key, conn] of Object.entries(def.connections ?? {})) {
+    if (typeof (conn as Connector<unknown>)?.id !== "string") {
+      throw new TypeError(
+        `defineAutomation(${def.id}): connections.${key} is not a connector — import it from @devosurf/tesser-connectors`,
+      );
+    }
+  }
+  for (const [key, sec] of Object.entries(def.secrets ?? {})) {
+    if ((sec as SecretDef)?._secret !== true) {
+      throw new TypeError(
+        `defineAutomation(${def.id}): secrets.${key} must be declared with secret({ describe })`,
+      );
+    }
+  }
+  for (const [key, m] of Object.entries(def.models ?? {})) {
+    if (!isModelDef(m)) {
+      throw new TypeError(`defineAutomation(${def.id}): models.${key} must be declared with model({ connection, alias })`);
+    }
+  }
+  for (const [key, op] of Object.entries(def.operators ?? {})) {
+    if (!isOperatorDef(op)) {
+      throw new TypeError(`defineAutomation(${def.id}): operators.${key} must be declared with defineOperator(...)`);
+    }
+  }
+  for (const [key, h] of Object.entries(def.harnesses ?? {})) {
+    if (!isHarnessDef(h)) {
+      throw new TypeError(`defineAutomation(${def.id}): harnesses.${key} must be declared with harness({ connection })`);
+    }
+  }
+  if (Object.keys(def.operators ?? {}).length > 0) {
+    const b = def.budget?.models;
+    if (
+      !b ||
+      !Number.isInteger(b.tokens) ||
+      b.tokens < 1 ||
+      !Number.isInteger(b.outputTokens) ||
+      b.outputTokens < 1
+    ) {
+      throw new TypeError(
+        `defineAutomation(${def.id}): budget.models with positive tokens and outputTokens is required when operators are declared`,
+      );
+    }
+  }
+  if (def.concurrency && (!Number.isInteger(def.concurrency.limit) || def.concurrency.limit < 1)) {
+    throw new TypeError(`defineAutomation(${def.id}): concurrency.limit must be a positive integer`);
+  }
+  return def;
+}