@devosurf/tesser-sdk 0.1.0-alpha.0

package/src/internal/retry.ts

@@ -0,0 +1,57 @@
+// Retry policy resolution — one implementation so the in-process TestEngine and the
+// durable server engine schedule identical retries (ADR-0008 fidelity).
+
+import type { RetryPolicy } from "../automation.js";
+import { parseDuration } from "./duration.js";
+
+export interface ResolvedRetryPolicy {
+  maxAttempts: number;
+  type: "exponential" | "fixed";
+  baseMs: number;
+  maxMs: number;
+  jitter: boolean;
+}
+
+export const DEFAULT_STEP_RETRY: ResolvedRetryPolicy = {
+  maxAttempts: 3,
+  type: "exponential",
+  baseMs: 1000,
+  maxMs: 3_600_000,
+  jitter: true,
+};
+
+export function resolveRetryPolicy(
+  policy: RetryPolicy | undefined,
+  fallback: ResolvedRetryPolicy = DEFAULT_STEP_RETRY,
+): ResolvedRetryPolicy {
+  if (!policy) return fallback;
+  const backoff = policy.backoff;
+  if (backoff === undefined) return { ...fallback, maxAttempts: policy.maxAttempts };
+  if (typeof backoff === "string") {
+    return { ...fallback, maxAttempts: policy.maxAttempts, type: backoff };
+  }
+  return {
+    maxAttempts: policy.maxAttempts,
+    type: backoff.type,
+    baseMs: backoff.base !== undefined ? parseDuration(backoff.base, "retry.backoff.base") : fallback.baseMs,
+    maxMs: backoff.max !== undefined ? parseDuration(backoff.max, "retry.backoff.max") : fallback.maxMs,
+    jitter: backoff.jitter ?? fallback.jitter,
+  };
+}
+
+/** Delay before the NEXT attempt, or null when attempts are exhausted.
+ *  `attempt` is the 1-based attempt that just failed. */
+export function nextRetryDelayMs(
+  policy: ResolvedRetryPolicy,
+  attempt: number,
+  retryAfterMs?: number | undefined,
+  random: () => number = Math.random,
+): number | null {
+  if (attempt >= policy.maxAttempts) return null;
+  let delay =
+    policy.type === "fixed" ? policy.baseMs : policy.baseMs * Math.pow(2, attempt - 1);
+  delay = Math.min(delay, policy.maxMs);
+  if (policy.jitter) delay = delay * (0.5 + random() * 0.5);
+  if (retryAfterMs !== undefined) delay = Math.max(delay, retryAfterMs);
+  return Math.round(delay);
+}

package/src/internal/standard-schema.ts

@@ -0,0 +1,92 @@
+// Standard Schema v1 (https://standardschema.dev) — the spec interface, declared by us so
+// the SDK stays zero-dependency and no third-party name appears in our surface (ADR-0004).
+// Zod / Valibot / ArkType all implement `~standard`.
+
+import { TerminalError } from "../errors.js";
+
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+  interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  interface Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+  interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+}
+
+export interface ValidationIssue {
+  message: string;
+  path: string;
+}
+
+/** Validation failures are terminal — bad input never retries (ADR-0002 semantics). */
+export class SchemaValidationError extends TerminalError {
+  constructor(
+    readonly what: string,
+    readonly issues: ValidationIssue[],
+  ) {
+    super(
+      `${what} failed validation: ` +
+        issues.map((i) => (i.path === "$" ? i.message : `${i.path}: ${i.message}`)).join("; "),
+    );
+    this.name = "SchemaValidationError";
+  }
+}
+
+function pathToString(path: StandardSchemaV1.Issue["path"]): string {
+  if (!path || path.length === 0) return "$";
+  return (
+    "$." +
+    path
+      .map((seg) => String(typeof seg === "object" && seg !== null && "key" in seg ? seg.key : seg))
+      .join(".")
+  );
+}
+
+export function isSchema(value: unknown): value is StandardSchemaV1 {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "~standard" in value &&
+    typeof (value as Record<string, unknown>)["~standard"] === "object"
+  );
+}
+
+/** Validate `value` against a Standard Schema; throws SchemaValidationError on failure. */
+export async function validateSchema<T>(
+  schema: StandardSchemaV1<unknown, T>,
+  value: unknown,
+  what: string,
+): Promise<T> {
+  let result = schema["~standard"].validate(value);
+  if (result instanceof Promise) result = await result;
+  if (result.issues) {
+    throw new SchemaValidationError(
+      what,
+      result.issues.map((i) => ({ message: i.message, path: pathToString(i.path) })),
+    );
+  }
+  return result.value;
+}

package/src/internal/webhook-verify.ts

@@ -0,0 +1,49 @@
+// Declared-scheme webhook signature verification (ADR-0013): crypto an agent can get
+// wrong, implemented once. Used by the server ingress and by the testing harness.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { InboundWebhookEvent, VerifyScheme } from "../connector/index.js";
+
+const SLACK_TOLERANCE_MS = 5 * 60 * 1000;
+
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+
+function header(req: InboundWebhookEvent, name: string): string | undefined {
+  return req.headers[name.toLowerCase()];
+}
+
+export async function verifyInboundEvent(
+  scheme: VerifyScheme,
+  req: InboundWebhookEvent,
+  secret: string,
+  nowMs = Date.now(),
+): Promise<boolean> {
+  switch (scheme.kind) {
+    case "none":
+      return true;
+    case "hmacSha256": {
+      const provided = header(req, scheme.header);
+      if (!provided) return false;
+      const digest = createHmac("sha256", secret).update(req.rawBody).digest(scheme.encoding);
+      const expected = (scheme.prefix ?? "") + digest;
+      return safeEqual(provided, expected);
+    }
+    case "slackSigning": {
+      const ts = header(req, "x-slack-request-timestamp");
+      const provided = header(req, "x-slack-signature");
+      if (!ts || !provided) return false;
+      const age = Math.abs(nowMs - Number(ts) * 1000);
+      if (!Number.isFinite(age) || age > SLACK_TOLERANCE_MS) return false;
+      const base = `v0:${ts}:${Buffer.from(req.rawBody).toString("utf8")}`;
+      const expected = "v0=" + createHmac("sha256", secret).update(base).digest("hex");
+      return safeEqual(provided, expected);
+    }
+    case "custom":
+      return scheme.verify(req, secret);
+  }
+}

package/src/operators.ts

@@ -0,0 +1,181 @@
+import type { Schema, Serializable } from "./automation.js";
+
+export interface ModelSettingsV1 {
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  reasoning?: { effort?: "low" | "medium" | "high" };
+}
+
+export interface ModelDef {
+  readonly __model: true;
+  readonly connection: string;
+  readonly alias: string;
+  readonly settings?: ModelSettingsV1;
+}
+
+export function model(def: {
+  connection: string;
+  alias: string;
+  settings?: ModelSettingsV1;
+}): ModelDef {
+  if (!def || typeof def.connection !== "string" || def.connection.length === 0) {
+    throw new TypeError("model: connection must name a declared connection");
+  }
+  if (typeof def.alias !== "string" || def.alias.length === 0) {
+    throw new TypeError("model: alias must be a non-empty string");
+  }
+  validateSettings(def.settings, `model(${def.alias})`);
+  return Object.freeze({
+    __model: true as const,
+    connection: def.connection,
+    alias: def.alias,
+    ...(def.settings !== undefined ? { settings: Object.freeze({ ...def.settings }) } : {}),
+  });
+}
+
+export interface OperatorDef<TInput = unknown, TOutput = unknown> {
+  readonly __operator: true;
+  readonly input: Schema<TInput>;
+  readonly output: Schema<TOutput>;
+  readonly model: string;
+  readonly instructions: string;
+  readonly tools: readonly string[];
+  readonly maxTurns: number;
+}
+
+export type ModelMap = Record<string, ModelDef>;
+export type OperatorMap = Record<string, OperatorDef<any, any>>;
+export type OperatorInput<O> = O extends OperatorDef<infer I, any> ? I : never;
+export type OperatorOutput<O> = O extends OperatorDef<any, infer Out> ? Out : never;
+
+export type Operators<O extends OperatorMap = OperatorMap> = {
+  readonly [K in keyof O]: (input: OperatorInput<O[K]>) => Promise<OperatorOutput<O[K]>>;
+};
+
+export interface ModelBudget {
+  tokens: number;
+  outputTokens: number;
+}
+
+export interface AutomationBudget {
+  models?: ModelBudget;
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const TOOL_PATH = /^[A-Za-z_$][A-Za-z0-9_$]*(\.[A-Za-z_$][A-Za-z0-9_$]*)+$/;
+
+export function defineOperator<I, O>(def: {
+  input: Schema<I>;
+  output: Schema<O>;
+  model: string;
+  instructions: string;
+  tools?: readonly string[];
+  maxTurns?: number;
+}): OperatorDef<I, O> {
+  if (!def?.input) throw new TypeError("defineOperator: input schema is required");
+  if (!def.output) throw new TypeError("defineOperator: output schema is required");
+  if (typeof def.model !== "string" || !IDENT.test(def.model)) {
+    throw new TypeError("defineOperator: model must name a model key, e.g. \"smart\"");
+  }
+  if (typeof def.instructions !== "string" || def.instructions.trim().length === 0) {
+    throw new TypeError("defineOperator: instructions must be a non-empty string");
+  }
+  const tools = [...(def.tools ?? [])];
+  for (const t of tools) {
+    if (typeof t !== "string" || !TOOL_PATH.test(t)) {
+      throw new TypeError(`defineOperator: tool ${JSON.stringify(t)} must be a dotted Action path like "gmail.messages.get"`);
+    }
+  }
+  const maxTurns = def.maxTurns ?? 4;
+  if (!Number.isInteger(maxTurns) || maxTurns < 1 || maxTurns > 50) {
+    throw new TypeError("defineOperator: maxTurns must be an integer between 1 and 50");
+  }
+  return Object.freeze({
+    __operator: true as const,
+    input: def.input,
+    output: def.output,
+    model: def.model,
+    instructions: def.instructions,
+    tools: Object.freeze(tools),
+    maxTurns,
+  });
+}
+
+function validateSettings(settings: ModelSettingsV1 | undefined, what: string): void {
+  if (settings === undefined) return;
+  if (
+    settings.maxOutputTokens !== undefined &&
+    (!Number.isInteger(settings.maxOutputTokens) || settings.maxOutputTokens < 1)
+  ) {
+    throw new TypeError(`${what}: settings.maxOutputTokens must be a positive integer`);
+  }
+  if (
+    settings.temperature !== undefined &&
+    (typeof settings.temperature !== "number" || settings.temperature < 0 || settings.temperature > 2)
+  ) {
+    throw new TypeError(`${what}: settings.temperature must be between 0 and 2`);
+  }
+  if (settings.topP !== undefined && (typeof settings.topP !== "number" || settings.topP < 0 || settings.topP > 1)) {
+    throw new TypeError(`${what}: settings.topP must be between 0 and 1`);
+  }
+  const effort = settings.reasoning?.effort;
+  if (effort !== undefined && effort !== "low" && effort !== "medium" && effort !== "high") {
+    throw new TypeError(`${what}: settings.reasoning.effort must be low, medium, or high`);
+  }
+}
+
+export function isModelDef(value: unknown): value is ModelDef {
+  return typeof value === "object" && value !== null && (value as ModelDef).__model === true;
+}
+
+export function isOperatorDef(value: unknown): value is OperatorDef<any, any> {
+  return typeof value === "object" && value !== null && (value as OperatorDef).__operator === true;
+}
+
+export interface ModelUsage {
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens?: number;
+}
+
+export interface ModelToolDescriptor {
+  name: string;
+  path: string;
+  description?: string;
+  inputSchema?: Serializable;
+}
+
+export interface ModelMessage {
+  role: "user" | "assistant" | "tool";
+  content: string;
+  toolCallId?: string;
+}
+
+export interface ModelToolCall {
+  id: string;
+  name: string;
+  input: Serializable;
+}
+
+export interface NormalizedModelRequest {
+  operatorKey: string;
+  modelKey: string;
+  alias: string;
+  instructions: string;
+  input: Serializable;
+  messages: ModelMessage[];
+  tools: ModelToolDescriptor[];
+  settings?: ModelSettingsV1;
+  outputJsonSchema?: Serializable;
+}
+
+export interface NormalizedModelResponse {
+  content?: string;
+  output?: Serializable;
+  toolCalls?: ModelToolCall[];
+  usage: ModelUsage;
+  provider?: string;
+  model?: string;
+  raw?: Serializable;
+}

package/src/triggers.ts

@@ -0,0 +1,79 @@
+// Triggers: prebuilt, typed constructors (ADR-0001). Exactly one per automation. The
+// constructor carries plain-data config so the build extracts it without running anything.
+
+import type { EventDefinition } from "./events.js";
+import type { StandardSchemaV1 } from "./internal/standard-schema.js";
+
+export interface Trigger<TInput> {
+  readonly kind: "webhook" | "schedule" | "event" | "connector";
+  /** Phantom for inference; never set. */
+  readonly _input?: TInput;
+}
+
+export interface WebhookTrigger<T> extends Trigger<T> {
+  readonly kind: "webhook";
+  readonly input?: StandardSchemaV1<unknown, T>;
+  readonly respond: "async" | "sync";
+}
+
+export interface ScheduleTrigger extends Trigger<void> {
+  readonly kind: "schedule";
+  readonly cron: string;
+  readonly tz?: string;
+}
+
+export interface EventTrigger<T> extends Trigger<T> {
+  readonly kind: "event";
+  readonly event: EventDefinition<T>;
+}
+
+/** A Trigger contributed by a Connector (ADR-0013) — produced by
+ *  `<connector>.triggers.<name>(params)`, never constructed by hand. */
+export interface ConnectorTrigger<T> extends Trigger<T> {
+  readonly kind: "connector";
+  readonly connectorId: string;
+  readonly triggerId: string;
+  readonly params: Record<string, unknown>;
+  /** Names the binding in the automation's `connections` map; auto-bound when unambiguous. */
+  readonly connectionKey?: string;
+  /** Poll cadence override (reserved `every` param) — clamped to the connector's floor. */
+  readonly every?: string;
+}
+
+/** Inbound webhook. Route is auto-derived from project + automation id. Responds 202 with a
+ *  runId by default; `respond: "sync"` waits for and returns the handler's output. `input`
+ *  validates the body; raw headers / bytes (for HMAC) arrive on ctx.request. */
+export function onWebhook<T = unknown>(opts?: {
+  input?: StandardSchemaV1<unknown, T>;
+  respond?: "async" | "sync";
+}): WebhookTrigger<T> {
+  const trigger: WebhookTrigger<T> = {
+    kind: "webhook",
+    respond: opts?.respond ?? "async",
+    ...(opts?.input !== undefined ? { input: opts.input } : {}),
+  };
+  return Object.freeze(trigger);
+}
+
+// Light shape check only — strict parsing (ranges, day-of-week names, tz) happens at build.
+const CRON_SHAPE = /^\s*\S+(\s+\S+){4,5}\s*$/;
+
+export function onSchedule(opts: { cron: string; tz?: string }): ScheduleTrigger {
+  if (typeof opts?.cron !== "string" || !CRON_SHAPE.test(opts.cron)) {
+    throw new TypeError(
+      `onSchedule: cron "${String(opts?.cron)}" — expected 5 (or 6) space-separated fields, e.g. "0 9 * * *"`,
+    );
+  }
+  return Object.freeze({
+    kind: "schedule" as const,
+    cron: opts.cron.trim(),
+    ...(opts.tz !== undefined ? { tz: opts.tz } : {}),
+  });
+}
+
+export function onEvent<T>(event: EventDefinition<T>): EventTrigger<T> {
+  if (typeof event?.name !== "string" || event.schema === undefined) {
+    throw new TypeError("onEvent: pass an EventDefinition created by defineEvent(...)");
+  }
+  return Object.freeze({ kind: "event" as const, event });
+}