@devosurf/tesser-sdk 0.1.0-alpha.0

package/src/index.ts

@@ -0,0 +1,75 @@
+// @devosurf/tesser-sdk — the authoring surface. One durable-function primitive; durability comes
+// ONLY from ctx.step() (ADR-0002). Deliberately small and stable: absorb churn in the
+// runtime, never here. Connector AUTHORING lives at @devosurf/tesser-sdk/connector.
+
+export {
+  defineAutomation,
+  secret,
+  type AutomationDef,
+  type Ctx,
+  type Schema,
+  type Serializable,
+  type Connector,
+  type ClientOf,
+  type SecretDef,
+  type ConnectionMap,
+  type SecretMap,
+  type Connections,
+  type Secrets,
+  type RetryPolicy,
+  type StepOpts,
+  type Logger,
+  type WebhookRequest,
+} from "./automation.js";
+
+export {
+  defineOperator,
+  model,
+  type AutomationBudget,
+  type ModelBudget,
+  type ModelDef,
+  type ModelMap,
+  type ModelSettingsV1,
+  type ModelUsage,
+  type NormalizedModelRequest,
+  type NormalizedModelResponse,
+  type ModelMessage,
+  type ModelToolCall,
+  type ModelToolDescriptor,
+  type OperatorDef,
+  type OperatorMap,
+  type OperatorInput,
+  type OperatorOutput,
+  type Operators,
+} from "./operators.js";
+
+export {
+  harness,
+  type HarnessArtifact,
+  type HarnessBudget,
+  type HarnessDef,
+  type HarnessMap,
+  type HarnessRunRequest,
+  type HarnessRunResult,
+  type Harnesses,
+} from "./harnesses.js";
+
+export {
+  onWebhook,
+  onSchedule,
+  onEvent,
+  type Trigger,
+  type WebhookTrigger,
+  type ScheduleTrigger,
+  type EventTrigger,
+  type ConnectorTrigger,
+} from "./triggers.js";
+
+export { defineEvent, type EventDefinition } from "./events.js";
+
+export {
+  RetryableError,
+  TerminalError,
+  isRetryableError,
+  isTerminalError,
+} from "./errors.js";

package/src/internal/client.ts

@@ -0,0 +1,66 @@
+// Builds the typed client tree handed to automations as ctx.connections.<name> and runs a
+// single Action with input/output validation. The runtime (server: broker-authed http;
+// testing: mocks/cassettes) supplies the invoke/ctx — the SDK owns the walking and the
+// validation so both sides behave identically.
+
+import type { ActionCtx, ActionsTree, AnyAction, ConnectorInstance, TriggersDecl } from "../connector/index.js";
+import { isAction } from "../connector/index.js";
+import { validateSchema } from "./standard-schema.js";
+
+export type InvokeAction = (
+  actionPath: string[],
+  def: AnyAction,
+  input: unknown,
+) => Promise<unknown>;
+
+export function buildConnectorClient(
+  connector: ConnectorInstance<ActionsTree, TriggersDecl>,
+  invoke: InvokeAction,
+): unknown {
+  function walk(tree: ActionsTree, path: string[]): Record<string, unknown> {
+    const node: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(tree)) {
+      const childPath = [...path, key];
+      if (isAction(child)) {
+        node[key] = (input: unknown) => invoke(childPath, child, input);
+      } else {
+        node[key] = walk(child as ActionsTree, childPath);
+      }
+    }
+    return Object.freeze(node);
+  }
+  return walk(connector.__connector.actions ?? {}, []);
+}
+
+/** Resolve an action by dotted path (used by webhook registrars and MCP exposure). */
+export function actionAtPath(
+  connector: ConnectorInstance<ActionsTree, TriggersDecl>,
+  path: string[],
+): AnyAction | undefined {
+  let node: ActionsTree | AnyAction | undefined = connector.__connector.actions ?? {};
+  for (const key of path) {
+    if (node === undefined || isAction(node)) return undefined;
+    node = (node as ActionsTree)[key];
+  }
+  return node !== undefined && isAction(node) ? node : undefined;
+}
+
+/** Validate input → run → validate OUR mapped output (never the raw provider response). */
+export async function runAction(
+  def: AnyAction,
+  ctx: ActionCtx,
+  rawInput: unknown,
+  what: string,
+): Promise<unknown> {
+  const input = await validateSchema(def.input, rawInput ?? {}, `${what} input`);
+  const result = await def.run(ctx, input);
+  return validateSchema(def.output, result, `${what} output`);
+}
+
+/** Derived retry-safety (ADR-0012): reads retry; writes retry only with an idempotency
+ *  key; explicit per-action override wins. */
+export function isRetrySafe(def: AnyAction, connectorHasIdempotencyHeader: boolean): boolean {
+  if (def.retrySafe !== undefined) return def.retrySafe;
+  if (def.safety === "read") return true;
+  return connectorHasIdempotencyHeader;
+}

package/src/internal/codec.ts

@@ -0,0 +1,135 @@
+// The structured codec carrying step results to/from the journal (ADR-0002).
+// An invisible internal (ADR-0004): authors only ever see plain values round-trip.
+//
+// Wire shape is JSON. Non-JSON serializables are tagged envelopes: {"$t": kind, "v": ...}.
+// A plain object that itself owns a "$t" key is wrapped as {"$t":"obj"} to stay unambiguous.
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export class NotSerializableError extends TypeError {
+  constructor(
+    readonly path: string,
+    readonly kind: string,
+  ) {
+    super(
+      `value at ${path} is not serializable (${kind}); step results are journaled and must be ` +
+        `plain data — string/number/boolean/null/bigint/Date/Array/Map/Set/Uint8Array/plain object`,
+    );
+    this.name = "NotSerializableError";
+  }
+}
+
+function describe(value: unknown): string {
+  if (typeof value === "function") return "a function";
+  if (typeof value === "symbol") return "a symbol";
+  if (value instanceof Promise) return "a Promise — await it inside the step";
+  const proto = Object.getPrototypeOf(value);
+  const ctor = proto?.constructor?.name;
+  return ctor ? `a ${ctor} instance — a live handle` : "an exotic object";
+}
+
+export function encodeJournal(value: unknown, path = "$"): JsonValue {
+  if (value === undefined) return { $t: "undef" };
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return value as string | boolean;
+  if (t === "number") {
+    const n = value as number;
+    if (Number.isFinite(n)) return n;
+    return { $t: "num", v: String(n) }; // NaN / Infinity / -Infinity
+  }
+  if (t === "bigint") return { $t: "bigint", v: (value as bigint).toString() };
+  if (t === "function" || t === "symbol") throw new NotSerializableError(path, describe(value));
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    return { $t: "date", v: Number.isNaN(ms) ? null : value.toISOString() };
+  }
+  if (value instanceof Map) {
+    return {
+      $t: "map",
+      v: [...value.entries()].map(([k, v], i) => [
+        encodeJournal(k, `${path}.<key ${i}>`),
+        encodeJournal(v, `${path}.<entry ${i}>`),
+      ]) as JsonValue,
+    };
+  }
+  if (value instanceof Set) {
+    return {
+      $t: "set",
+      v: [...value.values()].map((v, i) => encodeJournal(v, `${path}.<item ${i}>`)),
+    };
+  }
+  if (value instanceof Uint8Array) {
+    return { $t: "bytes", v: Buffer.from(value).toString("base64") };
+  }
+  if (Array.isArray(value)) {
+    return value.map((v, i) => encodeJournal(v, `${path}[${i}]`));
+  }
+  if (t === "object") {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      throw new NotSerializableError(path, describe(value));
+    }
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, JsonValue> = {};
+    for (const key of Object.keys(obj)) {
+      out[key] = encodeJournal(obj[key], `${path}.${key}`);
+    }
+    if (Object.prototype.hasOwnProperty.call(obj, "$t")) return { $t: "obj", v: out };
+    return out;
+  }
+  throw new NotSerializableError(path, describe(value));
+}
+
+export function decodeJournal(json: JsonValue): unknown {
+  if (json === null || typeof json !== "object") return json;
+  if (Array.isArray(json)) return json.map(decodeJournal);
+  const tag = (json as Record<string, JsonValue>)["$t"];
+  if (tag === undefined) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(json)) out[key] = decodeJournal((json as never)[key]);
+    return out;
+  }
+  const v = (json as Record<string, JsonValue>)["v"];
+  switch (tag) {
+    case "undef":
+      return undefined;
+    case "num":
+      return Number(v);
+    case "bigint":
+      return BigInt(v as string);
+    case "date":
+      return v === null ? new Date(NaN) : new Date(v as string);
+    case "map":
+      return new Map((v as JsonValue[]).map((e) => {
+        const [k, val] = e as [JsonValue, JsonValue];
+        return [decodeJournal(k), decodeJournal(val)] as const;
+      }));
+    case "set":
+      return new Set((v as JsonValue[]).map(decodeJournal));
+    case "bytes":
+      return new Uint8Array(Buffer.from(v as string, "base64"));
+    case "obj": {
+      const out: Record<string, unknown> = {};
+      const inner = v as Record<string, JsonValue>;
+      for (const key of Object.keys(inner)) out[key] = decodeJournal(inner[key] as JsonValue);
+      return out;
+    }
+    default:
+      throw new TypeError(`journal codec: unknown tag "${String(tag)}"`);
+  }
+}
+
+/** Stable JSON string for journal storage / content hashing (sorted object keys). */
+export function stableStringify(json: JsonValue): string {
+  if (json === null || typeof json !== "object") return JSON.stringify(json);
+  if (Array.isArray(json)) return `[${json.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(json).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify((json as never)[k])}`).join(",")}}`;
+}

package/src/internal/duration.ts

@@ -0,0 +1,57 @@
+// Duration strings ("30s", "1h30m", "250ms", "2d") used across step timeouts, retry
+// backoff, sleep, and trigger cadence. An invisible internal.
+
+const UNIT_MS: Record<string, number> = {
+  ms: 1,
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+  w: 604_800_000,
+};
+
+const PART = /(\d+(?:\.\d+)?)(ms|s|m|h|d|w)/g;
+
+export function parseDuration(input: string | number, what = "duration"): number {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input < 0) {
+      throw new TypeError(`${what}: expected a non-negative number of ms, got ${input}`);
+    }
+    return input;
+  }
+  const s = input.trim();
+  let total = 0;
+  let matchedLen = 0;
+  for (const m of s.matchAll(PART)) {
+    total += Number(m[1]) * (UNIT_MS[m[2] as string] as number);
+    matchedLen += (m[0] as string).length;
+  }
+  if (matchedLen === 0 || matchedLen !== s.replace(/\s+/g, "").length) {
+    throw new TypeError(
+      `${what}: "${input}" is not a duration — use forms like "250ms", "30s", "5m", "1h30m", "2d"`,
+    );
+  }
+  return Math.round(total);
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const units: Array<[string, number]> = [
+    ["w", UNIT_MS["w"] as number],
+    ["d", UNIT_MS["d"] as number],
+    ["h", UNIT_MS["h"] as number],
+    ["m", UNIT_MS["m"] as number],
+    ["s", 1000],
+  ];
+  let rest = ms;
+  let out = "";
+  for (const [unit, size] of units) {
+    const n = Math.floor(rest / size);
+    if (n > 0) {
+      out += `${n}${unit}`;
+      rest -= n * size;
+    }
+  }
+  if (rest > 0) out += `${rest}ms`;
+  return out;
+}

package/src/internal/harnesses.ts

@@ -0,0 +1,46 @@
+import { TerminalError } from "../errors.js";
+import type { AutomationDef, Ctx, Serializable } from "../automation.js";
+import type { HarnessDef, HarnessRunRequest, HarnessRunResult, Harnesses } from "../harnesses.js";
+import { encodeJournal, decodeJournal } from "./codec.js";
+import { validateSchema } from "./standard-schema.js";
+
+export interface HarnessCallInfo {
+  automationId: string;
+  harnessKey: string;
+  harness: HarnessDef;
+  request: HarnessRunRequest<unknown>;
+}
+
+export type HarnessCaller = (info: HarnessCallInfo) => Promise<HarnessRunResult<unknown>>;
+
+export function buildHarnesses(
+  def: AutomationDef<any, any, any, any, any, any, any>,
+  _ctx: Ctx<any, any, any, any>,
+  callHarness: HarnessCaller,
+): Harnesses<any> {
+  const out: Record<string, { run: (request: HarnessRunRequest<unknown>) => Promise<HarnessRunResult<unknown>> }> = {};
+  const harnesses = (def.harnesses ?? {}) as Record<string, HarnessDef>;
+  for (const [harnessKey, h] of Object.entries(harnesses)) {
+    out[harnessKey] = {
+      run: async (request) => {
+        if (!request || typeof request.prompt !== "string" || request.prompt.length === 0) {
+          throw new TerminalError(`harness.${harnessKey}: prompt is required`);
+        }
+        if (!request.output) throw new TerminalError(`harness.${harnessKey}: output schema is required`);
+        const raw = await callHarness({ automationId: def.id, harnessKey, harness: h, request });
+        const serial = toSerializable(raw, `harness.${harnessKey} result`) as unknown as HarnessRunResult<unknown>;
+        const output = await validateSchema(request.output, serial.output, `harness.${harnessKey} output`);
+        return { ...serial, output: toSerializable(output, `harness.${harnessKey} output`) as never };
+      },
+    };
+  }
+  return Object.freeze(out) as unknown as Harnesses<any>;
+}
+
+function toSerializable(value: unknown, what: string): Serializable {
+  try {
+    return decodeJournal(encodeJournal(value)) as Serializable;
+  } catch (cause) {
+    throw new TerminalError(`${what} is not serializable`, { cause });
+  }
+}

package/src/internal/http.ts

@@ -0,0 +1,179 @@
+// The pre-authed connector HTTP client (ADR-0012). The SDK owns the *mechanics* —
+// URL/base-URL handling, JSON encoding, status→Retryable/Terminal classification,
+// Retry-After, refresh-once on 401 — while the credential itself enters only through
+// the runtime-supplied `applyAuth` hook at call time (the broker boundary, ADR-0004).
+
+import { RetryableError, TerminalError } from "../errors.js";
+
+export interface HttpRequestOptions {
+  method?: string;
+  path?: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  headers?: Record<string, string>;
+  /** JSON-encoded unless `body` is a string / Uint8Array / URLSearchParams / FormData. */
+  body?: unknown;
+  /** Return the raw Response instead of the parsed body. */
+  raw?: boolean;
+  timeoutMs?: number;
+}
+
+export interface ProviderHttpError {
+  status: number;
+  bodySnippet: string;
+  url: string;
+}
+
+/** Classification override, per action (ADR-0012). Return an Error to throw it as-is. */
+export type ClassifyError = (
+  err: ProviderHttpError,
+) => "retry" | "terminal" | Error | undefined;
+
+export interface TesserHttpConfig {
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  defaultHeaders?: Record<string, string>;
+  /** Inject the credential into the outbound request. Supplied by the runtime, never by authors. */
+  applyAuth?: (req: { url: URL; headers: Headers }) => void | Promise<void>;
+  /** Broker refresh-once hook: called on 401; return true to retry the call once. */
+  onUnauthorized?: () => Promise<boolean>;
+  classifyError?: ClassifyError;
+  timeoutMs?: number;
+}
+
+export interface TesserHttp {
+  get(path: string, opts?: HttpRequestOptions): Promise<any>;
+  delete(path: string, opts?: HttpRequestOptions): Promise<any>;
+  post(path: string, body?: unknown, opts?: HttpRequestOptions): Promise<any>;
+  put(path: string, body?: unknown, opts?: HttpRequestOptions): Promise<any>;
+  patch(path: string, body?: unknown, opts?: HttpRequestOptions): Promise<any>;
+  request(opts: HttpRequestOptions & { path: string }): Promise<any>;
+}
+
+function parseRetryAfter(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const secs = Number(value);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+  const date = Date.parse(value);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return undefined;
+}
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+export function classifyStatus(status: number): "retry" | "terminal" | "ok" | "unauthorized" {
+  if (status >= 200 && status < 300) return "ok";
+  if (status === 401) return "unauthorized";
+  if (RETRYABLE_STATUS.has(status) || status >= 500) return "retry";
+  return "terminal";
+}
+
+export function createHttpClient(config: TesserHttpConfig): TesserHttp {
+  const fetchImpl = config.fetchImpl ?? fetch;
+
+  function buildUrl(path: string, query?: HttpRequestOptions["query"]): URL {
+    let url: URL;
+    if (/^https?:\/\//.test(path)) {
+      url = new URL(path);
+    } else {
+      if (!config.baseUrl) {
+        throw new TerminalError(`http: relative path "${path}" but the connector has no baseUrl`);
+      }
+      const base = config.baseUrl.endsWith("/") ? config.baseUrl : config.baseUrl + "/";
+      url = new URL(path.startsWith("/") ? path.slice(1) : path, base);
+    }
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined) url.searchParams.set(k, String(v));
+      }
+    }
+    return url;
+  }
+
+  async function exec(opts: HttpRequestOptions & { path: string }, isRetryAfter401 = false): Promise<any> {
+    const url = buildUrl(opts.path, opts.query);
+    const headers = new Headers(config.defaultHeaders);
+    headers.set("accept", headers.get("accept") ?? "application/json");
+    if (opts.headers) for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
+
+    type FetchBody = NonNullable<Parameters<typeof fetch>[1]> extends { body?: infer B }
+      ? B
+      : never;
+    let body: FetchBody | undefined;
+    if (opts.body !== undefined) {
+      if (
+        typeof opts.body === "string" ||
+        opts.body instanceof Uint8Array ||
+        opts.body instanceof URLSearchParams ||
+        (typeof FormData !== "undefined" && opts.body instanceof FormData)
+      ) {
+        body = opts.body as FetchBody;
+      } else {
+        body = JSON.stringify(opts.body);
+        if (!headers.has("content-type")) headers.set("content-type", "application/json");
+      }
+    }
+
+    await config.applyAuth?.({ url, headers });
+
+    const timeoutMs = opts.timeoutMs ?? config.timeoutMs ?? 30_000;
+    let res: Response;
+    try {
+      res = await fetchImpl(url, {
+        method: opts.method ?? "GET",
+        headers,
+        signal: AbortSignal.timeout(timeoutMs),
+        ...(body !== undefined ? { body } : {}),
+      });
+    } catch (cause) {
+      throw new RetryableError(`http: network failure for ${opts.method ?? "GET"} ${url.host}${url.pathname}`, {
+        cause,
+      });
+    }
+
+    // raw mode: the caller owns status handling entirely (e.g. the generic http connector).
+    if (opts.raw) return res;
+
+    const kind = classifyStatus(res.status);
+    if (kind === "ok") {
+      const text = await res.text();
+      if (text.length === 0) return null;
+      const contentType = res.headers.get("content-type") ?? "";
+      if (contentType.includes("json")) return JSON.parse(text);
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+
+    if (kind === "unauthorized" && !isRetryAfter401 && config.onUnauthorized) {
+      const refreshed = await config.onUnauthorized();
+      if (refreshed) return exec(opts, true);
+    }
+
+    const bodySnippet = (await res.text().catch(() => "")).slice(0, 600);
+    const providerErr: ProviderHttpError = { status: res.status, bodySnippet, url: url.toString() };
+    const overridden = config.classifyError?.(providerErr);
+    if (overridden instanceof Error) throw overridden;
+    const finalKind = overridden ?? (kind === "unauthorized" ? "terminal" : kind);
+
+    const message = `provider responded ${res.status} for ${opts.method ?? "GET"} ${url.pathname}${
+      bodySnippet ? ` — ${bodySnippet}` : ""
+    }`;
+    if (finalKind === "retry") {
+      throw new RetryableError(message, {
+        retryAfterMs: parseRetryAfter(res.headers.get("retry-after")),
+      });
+    }
+    throw new TerminalError(message);
+  }
+
+  return {
+    get: (path, opts) => exec({ ...opts, path, method: "GET" }),
+    delete: (path, opts) => exec({ ...opts, path, method: "DELETE" }),
+    post: (path, body, opts) => exec({ ...opts, path, body, method: "POST" }),
+    put: (path, body, opts) => exec({ ...opts, path, body, method: "PUT" }),
+    patch: (path, body, opts) => exec({ ...opts, path, body, method: "PATCH" }),
+    request: (opts) => exec(opts),
+  };
+}

package/src/internal/index.ts

@@ -0,0 +1,51 @@
+// @devosurf/tesser-sdk/internal — machinery shared by the runtime, the testing harness, the CLI
+// and codegen. NOT part of the authoring surface; absorb churn here, never in the facade.
+
+export {
+  encodeJournal,
+  decodeJournal,
+  stableStringify,
+  NotSerializableError,
+  type JsonValue,
+} from "./codec.js";
+export { parseDuration, formatDuration } from "./duration.js";
+export {
+  validateSchema,
+  isSchema,
+  SchemaValidationError,
+  type StandardSchemaV1,
+  type ValidationIssue,
+} from "./standard-schema.js";
+export {
+  createHttpClient,
+  classifyStatus,
+  type TesserHttp,
+  type TesserHttpConfig,
+  type HttpRequestOptions,
+  type ClassifyError,
+  type ProviderHttpError,
+} from "./http.js";
+export { verifyInboundEvent } from "./webhook-verify.js";
+export {
+  resolveRetryPolicy,
+  nextRetryDelayMs,
+  DEFAULT_STEP_RETRY,
+  type ResolvedRetryPolicy,
+} from "./retry.js";
+export {
+  buildConnectorClient,
+  actionAtPath,
+  runAction,
+  isRetrySafe,
+  type InvokeAction,
+} from "./client.js";
+export {
+  extractAutomationManifest,
+  extractConnectorManifest,
+  ManifestError,
+  type AutomationManifest,
+  type ConnectorManifest,
+  type TriggerManifest,
+} from "./manifest.js";
+export { buildOperators, toolName, type ModelCaller, type ModelCallInfo } from "./operators.js";
+export { buildHarnesses, type HarnessCaller, type HarnessCallInfo } from "./harnesses.js";