failproofai 1.0.7-beta.1 → 1.0.7

package/.next/standalone/sdk/typescript/scripts/release.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * The release scheme for `@failproofai/sdk`, and the only place it is written
+ * down.
+ *
+ * The publish workflow calls this rather than restating the arithmetic, for the
+ * same reason `scripts/python-version.py` exists on the Python side: a release
+ * rule spelled out in YAML is a release rule nothing can test.
+ *
+ * ## The scheme
+ *
+ * | from                  | next                    |
+ * |-----------------------|-------------------------|
+ * | beta `X.Y.Z-beta.N`   | `X.Y.Z-beta.(N+1)`      |
+ * | stable `X.Y.Z`        | `X.Y.(Z+1)-beta.0`      |
+ *
+ * The same rule `publish.yml` applies to the `failproofai` npm package. Unlike
+ * PyPI, npm HAS dist-tags, so a pre-release publishes behind `beta` and a bare
+ * `npm install @failproofai/sdk` never resolves it — which is why a prerelease
+ * here is a cheaper mistake than one on PyPI, and why the guard rails below are
+ * about not BURNING a version rather than about not shipping one.
+ *
+ * ## Commands
+ *
+ *   resolve            print the version in src/version.ts, and what follows it
+ *   write <version>    move src/version.ts and package.json to <version>
+ *   changelog <version> print that version's CHANGELOG section
+ *
+ * Node's standard library only: this runs in the preflight job, which installs
+ * nothing precisely so that no third-party code decides whether a release may
+ * proceed.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const VERSION_FILE = join(root, "src/version.ts");
+const MANIFEST_FILE = join(root, "package.json");
+const CHANGELOG_FILE = join(root, "CHANGELOG.md");
+
+/**
+ * Only canonical spellings are accepted.
+ *
+ * `1.2.3-beta.01`, `v1.2.3` and `1.2.3-beta` are all things a human types and
+ * npm stores as something else or refuses outright. Every consumer in the
+ * pipeline compares version STRINGS — this file, the tarball name, the dist-tag
+ * and the "is this published" query — so a spelling that round-trips
+ * differently is a release that half-succeeds.
+ */
+const CANONICAL = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-beta\.(0|[1-9]\d*))?$/;
+
+function fail(message) {
+  process.stderr.write(`release: ${message}\n`);
+  process.exit(1);
+}
+
+function readVersion() {
+  const source = readFileSync(VERSION_FILE, "utf8");
+  const match = /export const VERSION = "([^"]+)";/.exec(source);
+  if (match === null) fail(`could not find VERSION in ${VERSION_FILE}`);
+  return match[1];
+}
+
+function parse(version) {
+  const match = CANONICAL.exec(version);
+  if (match === null) {
+    fail(
+      `${version} is not a canonical version. This package uses X.Y.Z or ` +
+        "X.Y.Z-beta.N with no leading zeroes and no other pre-release kinds — " +
+        "anything else stores on npm as a different string than the one in the " +
+        "source, and the pipeline compares strings.",
+    );
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    beta: match[5] === undefined ? null : Number(match[5]),
+  };
+}
+
+function next(version) {
+  const { major, minor, patch, beta } = parse(version);
+  return beta === null
+    ? `${major}.${minor}.${patch + 1}-beta.0`
+    : `${major}.${minor}.${patch}-beta.${beta + 1}`;
+}
+
+/**
+ * The CHANGELOG section for `version`, which becomes the GitHub Release body.
+ *
+ * A release whose section is missing or empty is refused before anything is
+ * built. A published version nobody can read the changes for is a version that
+ * may as well not have shipped.
+ */
+function changelogSection(version) {
+  const lines = readFileSync(CHANGELOG_FILE, "utf8").split("\n");
+  const heading = new RegExp(`^## ${version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+  const start = lines.findIndex((line) => heading.test(line));
+  if (start === -1) {
+    fail(
+      `CHANGELOG.md has no "## ${version} — <date>" section. Add one before releasing; ` +
+        "it becomes the GitHub Release body.",
+    );
+  }
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((line) => line.startsWith("## "));
+  const body = (end === -1 ? rest : rest.slice(0, end)).join("\n").trim();
+  if (body === "") fail(`CHANGELOG.md's "## ${version}" section is empty.`);
+  return body;
+}
+
+function write(version) {
+  parse(version);
+  const source = readFileSync(VERSION_FILE, "utf8");
+  writeFileSync(
+    VERSION_FILE,
+    source.replace(/export const VERSION = "[^"]+";/, `export const VERSION = "${version}";`),
+  );
+  const manifest = readFileSync(MANIFEST_FILE, "utf8");
+  // A targeted replacement rather than a parse-and-re-serialise: rewriting the
+  // whole manifest would reformat every line and make the release commit
+  // unreadable in review.
+  const replaced = manifest.replace(/("version":\s*")[^"]+(")/, `$1${version}$2`);
+  if (replaced === manifest) fail("could not find a version field in package.json");
+  writeFileSync(MANIFEST_FILE, replaced);
+}
+
+function emit(name, value) {
+  const file = process.env.GITHUB_OUTPUT;
+  const multiline = value.includes("\n");
+  const line = multiline
+    ? `${name}<<__RELEASE_EOF__\n${value}\n__RELEASE_EOF__\n`
+    : `${name}=${value}\n`;
+  if (file) writeFileSync(file, line, { flag: "a" });
+  process.stdout.write(multiline ? `${name}:\n${value}\n` : `${name}=${value}\n`);
+}
+
+const [command, argument] = process.argv.slice(2);
+
+switch (command) {
+  case "resolve": {
+    const version = readVersion();
+    parse(version);
+    const manifest = JSON.parse(readFileSync(MANIFEST_FILE, "utf8"));
+    if (manifest.version !== version) {
+      fail(
+        `package.json says ${manifest.version} but src/version.ts says ${version}. ` +
+          "They are read by different consumers and must agree.",
+      );
+    }
+    emit("version", version);
+    emit("next_version", next(version));
+    emit("is_prerelease", String(parse(version).beta !== null));
+    emit("dist_tag", parse(version).beta === null ? "latest" : "beta");
+    emit("tag", `ts-sdk-v${version}`);
+    break;
+  }
+  case "write": {
+    if (!argument) fail("write needs a version");
+    write(argument);
+    process.stdout.write(`release: moved to ${argument}\n`);
+    break;
+  }
+  case "changelog": {
+    emit("body", changelogSection(argument ?? readVersion()));
+    break;
+  }
+  case "next": {
+    process.stdout.write(`${next(argument ?? readVersion())}\n`);
+    break;
+  }
+  default:
+    fail("usage: release.mjs resolve | write <version> | changelog [version] | next [version]");
+}

package/.next/standalone/sdk/typescript/src/clock.ts

@@ -0,0 +1,58 @@
+/**
+ * Event timestamps: wall-clock milliseconds, with the microsecond digits used
+ * to keep emission order inside a millisecond.
+ *
+ * The wire format has six fractional digits (the Python SDK writes real
+ * microseconds), and the dashboard orders a session's events by that field.
+ * JavaScript's wall clock resolves to the millisecond, and a fast agent emits
+ * `model_response`, `tool_use`, `tool_result` and the next `model_request`
+ * inside one — so with the last three digits always `000` they tied, and the
+ * dashboard showed a `tool_result` before its own `tool_use`.
+ *
+ * So each stamp is `max(wall µs, previous + 1)`. The digits below the
+ * millisecond are a sequence, not a measurement — nothing here claims a
+ * precision the clock does not have — and the millisecond part is still the
+ * wall clock. The sequence is process-wide and shared through `globalThis`, so
+ * the ESM and CommonJS copies of this package loaded into one process (the
+ * dual-package case the adapters already handle) cannot interleave two
+ * sequences.
+ *
+ * A wall clock that steps BACK (NTP, a VM resume) is followed, not fought: if
+ * the sequence is more than a second ahead of the wall, it re-anchors. Holding
+ * `previous + 1` instead would freeze every timestamp at the old time for as
+ * long as the step was — an hour's step, an hour of events stamped with one
+ * instant.
+ */
+
+const KEY = Symbol.for("@failproofai/sdk.clock");
+const MAX_LEAD_MICROS = 1_000_000;
+
+interface ClockState {
+  last: number;
+}
+
+function state(): ClockState {
+  const holder = globalThis as unknown as Record<symbol, ClockState | undefined>;
+  let found = holder[KEY];
+  if (found === undefined) {
+    found = { last: 0 };
+    holder[KEY] = found;
+  }
+  return found;
+}
+
+/** Microseconds since the epoch, strictly increasing within the process. */
+export function nowMicros(): number {
+  const clock = state();
+  const wall = Date.now() * 1000;
+  const next = wall > clock.last || clock.last - wall > MAX_LEAD_MICROS ? wall : clock.last + 1;
+  clock.last = next;
+  return next;
+}
+
+/** `2026-09-23T12:34:56.123456Z`: six fractional digits, as the ingest parser expects. */
+export function formatMicros(micros: number): string {
+  const ms = Math.floor(micros / 1000);
+  const sub = String(micros - ms * 1000).padStart(3, "0");
+  return `${new Date(ms).toISOString().slice(0, -1)}${sub}Z`;
+}

package/.next/standalone/sdk/typescript/src/context.ts

@@ -0,0 +1,214 @@
+/**
+ * Ambient run identity, carried on an `AsyncLocalStorage`.
+ *
+ * Without this the SDK would have no ambient session: every `event.*` call
+ * would take `sessionId` and `agentId` as required arguments and nothing would
+ * propagate them. Threading both through every function that might emit an
+ * event is what makes instrumentation sprawl into a diff nobody wants to
+ * review. `session()` / `agent()` bind them instead.
+ *
+ * ## Why `AsyncLocalStorage` and not a module-level variable
+ *
+ * An agent process runs many logical runs at once — a server handling
+ * concurrent requests, a supervisor fanning out to sub-agents. A plain variable
+ * is shared by all of them, so the last writer wins and every event after it is
+ * attributed to the wrong run. `AsyncLocalStorage` is Node's equivalent of
+ * Python's `contextvars`: the value follows the async call tree through
+ * `await`, `.then()`, timers and `EventEmitter` callbacks created inside the
+ * scope, and two concurrent branches see two different values.
+ *
+ * ## Why the stack is a frozen array
+ *
+ * `agentStack` is replaced, never mutated. A store object is shared BY
+ * REFERENCE with every async branch below it, so `push()` in one branch would
+ * mutate the value every sibling sees — which is exactly the cross-run event
+ * mixing this module exists to prevent, wearing an `AsyncLocalStorage` costume.
+ * It passes every single-branch test.
+ *
+ * There is deliberately no separate `agentId` slot: the top of the stack IS the
+ * current agent id, so the two cannot drift apart, and `parentId` is the entry
+ * beneath it.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import { logger } from "./logger.js";
+
+/**
+ * The agent id used when events are emitted with a session bound but no agent
+ * scope. "main" is the convention the skill and the reference integrations
+ * already teach, so an un-scoped event lands somewhere sensible rather than
+ * throwing.
+ */
+export const DEFAULT_AGENT_ID = "main";
+
+/** The run identity in scope. Never null — check `sessionId === null` instead. */
+export interface Identity {
+  readonly sessionId: string | null;
+  readonly agentId: string | null;
+  readonly parentId: string | null;
+  readonly depth: number;
+}
+
+export interface Store {
+  readonly sessionId: string | null;
+  readonly agentStack: readonly string[];
+}
+
+export const EMPTY_STORE: Store = Object.freeze({
+  sessionId: null,
+  agentStack: Object.freeze([]),
+});
+
+const storage = new AsyncLocalStorage<Store>();
+
+function read(): Store {
+  return storage.getStore() ?? EMPTY_STORE;
+}
+
+/**
+ * The identity bound to the current context.
+ *
+ * `current().sessionId === null` means nothing is bound — either no scope was
+ * entered, or this callback escaped the async context that entered one (see
+ * `propagate`).
+ */
+export function current(): Identity {
+  const { sessionId: sid, agentStack: stack } = read();
+  return {
+    sessionId: sid,
+    agentId: stack.length > 0 ? stack[stack.length - 1]! : null,
+    parentId: stack.length >= 2 ? stack[stack.length - 2]! : null,
+    depth: stack.length,
+  };
+}
+
+/** The bound session id, or null. Hot path — allocates no Identity. */
+export function sessionId(): string | null {
+  return read().sessionId;
+}
+
+/** The current agent id, falling back to `DEFAULT_AGENT_ID`. */
+export function agentId(): string {
+  const { agentStack: stack } = read();
+  return stack.length > 0 ? stack[stack.length - 1]! : DEFAULT_AGENT_ID;
+}
+
+/** The enclosing agent id, or null at depth 0 or 1. */
+export function parentAgentId(): string | null {
+  const { agentStack: stack } = read();
+  return stack.length >= 2 ? stack[stack.length - 2]! : null;
+}
+
+export function snapshot(): Store {
+  return read();
+}
+
+export function withSessionBound(store: Store, sid: string): Store {
+  return { sessionId: sid, agentStack: store.agentStack };
+}
+
+export function withAgentPushed(store: Store, aid: string): Store {
+  return { sessionId: store.sessionId, agentStack: Object.freeze([...store.agentStack, aid]) };
+}
+
+/** Run `fn` with `store` bound. The clean form: nothing to unwind, ever. */
+export function runWith<T>(store: Store, fn: () => T): T {
+  return storage.run(store, fn);
+}
+
+/**
+ * Bind `store` for the REMAINDER of the current async context and return what
+ * was bound before.
+ *
+ * This is the `using`-statement half of the API, and it is strictly weaker than
+ * `runWith`: the binding escapes upward into the caller's context, so it has to
+ * be undone by hand. `scopes.ts` does that in a `[Symbol.dispose]`, which the
+ * runtime guarantees runs at the end of the block — including on `throw` and
+ * `return`.
+ *
+ * The hazard it cannot fix is a scope entered in one async context and disposed
+ * in another: `enterWith` in the disposing context cannot reach the context the
+ * value was bound in, so the frame stays bound there. `noteCrossContextExit`
+ * below is how that gets reported.
+ */
+export function enterWith(store: Store): Store {
+  const previous = read();
+  storage.enterWith(store);
+  return previous;
+}
+
+/** Deduplicates the cross-context warning — it fires from a scope exit. */
+let warnedCrossContext = false;
+
+export function resetCrossContextWarning(): void {
+  warnedCrossContext = false;
+}
+
+/**
+ * Report, once, that a scope could not be unwound where it was entered.
+ *
+ * WARNING, not debug. The consequence is not cosmetic: the frame the scope
+ * pushed stays bound in whatever context it was set in, so identity is wrong
+ * for everything that follows there. The caller cannot discover that any other
+ * way — there is no exception, and the events look plausible.
+ */
+export function noteCrossContextExit(): void {
+  if (warnedCrossContext) return;
+  warnedCrossContext = true;
+  logger.warn(
+    "a scope was entered in one async context and exited in another, so its identity " +
+      "could not be unwound and later events in the entering context may be attributed " +
+      "to it. The usual cause is a `using` scope spanning a `yield` in an async " +
+      "generator; pass sessionId/agentId explicitly there, or use the callback form " +
+      "(`await agent('name', fn)`), which cannot reach this state.",
+  );
+}
+
+/**
+ * Remove ONE frame for `aid` from a stack, innermost first.
+ *
+ * The fallback for a scope that cannot be unwound by restoring the previous
+ * store. Removes a single occurrence rather than every match, because the same
+ * agent id may legitimately be on the stack twice (a recursive agent), and
+ * dropping both would corrupt the outer one to fix the inner.
+ */
+export function withAgentDiscarded(store: Store, aid: string): Store {
+  const stack = store.agentStack;
+  for (let i = stack.length - 1; i >= 0; i -= 1) {
+    if (stack[i] === aid) {
+      return {
+        sessionId: store.sessionId,
+        agentStack: Object.freeze([...stack.slice(0, i), ...stack.slice(i + 1)]),
+      };
+    }
+  }
+  return store;
+}
+
+/**
+ * Wrap `fn` so it runs with the identity bound *right now*.
+ *
+ *     queue.push(propagate(work));
+ *     emitter.on("done", propagate(onDone));
+ *     new Worker(url).on("message", propagate(handle));
+ *
+ * `AsyncLocalStorage` already follows `await`, `.then()`, `setTimeout` and any
+ * callback CREATED inside a scope, so most code needs nothing. This is for the
+ * cases where it genuinely cannot: a callback stored during one run and invoked
+ * during another (a module-level registry, a connection pool's handler), work
+ * handed to a `worker_threads` boundary, or anything re-entered from a native
+ * addon that does not carry async context.
+ *
+ * It snapshots VALUES rather than capturing the store object, so re-entering it
+ * twice — a retried job, a handler invoked per message — binds the same
+ * identity each time instead of inheriting whatever the previous call left.
+ */
+export function propagate<Args extends unknown[], Result>(
+  fn: (...args: Args) => Result,
+): (...args: Args) => Result {
+  const captured = snapshot();
+  return function failproofaiPropagated(this: unknown, ...args: Args): Result {
+    return storage.run(captured, () => fn.apply(this, args));
+  };
+}

package/.next/standalone/sdk/typescript/src/edge/adapter.ts

@@ -0,0 +1,18 @@
+/** A framework adapter that installs nothing — see `src/edge/index.ts`. */
+
+import { notice } from "./notice.js";
+
+export function noopAdapter(name: string): {
+  name: string;
+  install(): Promise<void>;
+  uninstall(): void;
+} {
+  return {
+    name,
+    install() {
+      notice();
+      return Promise.resolve();
+    },
+    uninstall() {},
+  };
+}

package/.next/standalone/sdk/typescript/src/edge/ai.ts

@@ -0,0 +1,116 @@
+/**
+ * `@failproofai/sdk/ai` for runtimes with no filesystem — see `./index.ts`.
+ *
+ * Every helper hands the Vercel AI SDK something it accepts and that records
+ * nothing: `telemetry()` returns telemetry settings with `isEnabled: false`,
+ * the middleware passes calls straight through, the wrappers return what they
+ * were given.
+ */
+
+import { noopAdapter } from "./adapter.js";
+import { notice } from "./notice.js";
+
+type AttributeValue = string | number | boolean | Array<string | number | boolean>;
+
+/** A span that records nothing, for a caller holding the tracer directly. */
+export class FailproofSpan {
+  readonly attributes: Record<string, AttributeValue> = {};
+  spanContext() {
+    return { traceId: "0".repeat(32), spanId: "0".repeat(16), traceFlags: 0 };
+  }
+  setAttribute(): this {
+    return this;
+  }
+  setAttributes(): this {
+    return this;
+  }
+  addEvent(): this {
+    return this;
+  }
+  addLink(): this {
+    return this;
+  }
+  addLinks(): this {
+    return this;
+  }
+  setStatus(): this {
+    return this;
+  }
+  updateName(): this {
+    return this;
+  }
+  recordException(): void {}
+  isRecording(): boolean {
+    return false;
+  }
+  end(): void {}
+}
+
+export class FailproofTracer {
+  startSpan(): FailproofSpan {
+    return new FailproofSpan();
+  }
+
+  startActiveSpan(_name: string, ...rest: unknown[]): unknown {
+    const fn = rest[rest.length - 1] as (span: FailproofSpan) => unknown;
+    return fn(new FailproofSpan());
+  }
+}
+
+export function telemetry(
+  options: { functionId?: string; metadata?: Record<string, AttributeValue> } = {},
+): { isEnabled: false; functionId?: string; metadata?: Record<string, AttributeValue> } {
+  notice();
+  return {
+    isEnabled: false,
+    ...(options.functionId === undefined ? {} : { functionId: options.functionId }),
+    ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+  };
+}
+
+export function tracer(): FailproofTracer {
+  notice();
+  return new FailproofTracer();
+}
+
+const ignore = (): void => {};
+
+/** The v7 telemetry integration, with every hook a no-op. */
+export const integration = Object.freeze({
+  onStart: ignore,
+  onLanguageModelCallStart: ignore,
+  onLanguageModelCallEnd: ignore,
+  onObjectStepStart: ignore,
+  onObjectStepEnd: ignore,
+  onEmbedStart: ignore,
+  onEmbedEnd: ignore,
+  onToolExecutionStart: ignore,
+  onToolExecutionEnd: ignore,
+  onEnd: ignore,
+});
+
+export function middleware() {
+  notice();
+  return {
+    specificationVersion: "v3" as const,
+    wrapGenerate: async <R>({ doGenerate }: { doGenerate: () => PromiseLike<R> }): Promise<R> => await doGenerate(),
+    wrapStream: async <R>({ doStream }: { doStream: () => PromiseLike<R> }): Promise<R> => await doStream(),
+  };
+}
+
+export function wrapModel<T>(model: T): Promise<T> {
+  notice();
+  return Promise.resolve(model);
+}
+
+export function wrapTool<T>(_toolName: string, tool: T): T {
+  notice();
+  return tool;
+}
+
+export function wrapTools<T>(tools: T): T {
+  notice();
+  return tools;
+}
+
+export const adapter = noopAdapter("ai");