failproofai 1.0.7-beta.1 → 1.0.7

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

@@ -0,0 +1,117 @@
+/**
+ * Close what is still open when the process exits.
+ *
+ * A run killed mid-flight — every rolling deploy, every `docker stop`, a
+ * Kubernetes eviction — used to leave its `agent_start` without an `agent_end`
+ * and its `tool_use` without a `tool_result`. The dashboard renders those as
+ * running forever and the run is never handed to evaluation. Python gets this
+ * for free: its SIGTERM recipe raises `SystemExit`, which unwinds every
+ * `with agent(...)` block. JavaScript has no unwinding through a pending
+ * `await`, so the event namespace, the scopes and the adapters' trackers
+ * register closers here and the writer's `exit` listener runs them before its
+ * final synchronous flush.
+ *
+ * Everything closes most recently opened first, across every owner — the
+ * order it would have closed in had it returned.
+ *
+ * Only on `exit`. A `flushSync()` called while the process carries on closes
+ * nothing — the runs it would close are still running.
+ */
+
+/** Something still open when the process exits, and how to close it. */
+export interface OpenItem {
+  /** When it opened, in the event clock's microseconds (`clock.ts`). */
+  opened: number;
+  close(exitCode: number): void;
+}
+
+/** Returns what its owner still has open. Called once, at exit. */
+export type ExitCollector = () => OpenItem[];
+
+const collectors = new Set<ExitCollector>();
+
+/**
+ * The uncaught exception that is taking the process down, if one is. Without
+ * it, a run killed by a crash was closed with "the process exited (code 1)"
+ * and the exception itself was nowhere in the trace. Read through
+ * `uncaughtExceptionMonitor`, which observes without handling: the process
+ * still crashes exactly as it would have.
+ */
+let fatal: { error: unknown } | null = null;
+let monitoring = false;
+
+function monitorFatal(): void {
+  if (monitoring) return;
+  monitoring = true;
+  process.on("uncaughtExceptionMonitor", (error) => {
+    fatal ??= { error };
+  });
+}
+
+/** The uncaught exception the process is exiting on, or undefined. */
+export function fatalError(): unknown {
+  return fatal?.error;
+}
+
+/** @internal For tests. */
+export function resetFatal(): void {
+  fatal = null;
+}
+
+/** Register a collector; returns its unregister function. */
+export function onProcessExit(collector: ExitCollector): () => void {
+  monitorFatal();
+  collectors.add(collector);
+  return () => {
+    collectors.delete(collector);
+  };
+}
+
+/**
+ * Close everything still open, most recently opened first, across every
+ * owner. One ordering, not one per owner: a tool that ran a sub-agent opened
+ * before that sub-agent, so the sub-agent — and its model call, opened after
+ * it — must close first. Closing all tools before all agents showed a
+ * `delegate_writer` tool finishing while the writer it started still ran.
+ */
+export function runExitClosers(exitCode: number): void {
+  const items: OpenItem[] = [];
+  for (const collector of collectors) {
+    try {
+      items.push(...collector());
+    } catch {
+      // A collector that throws must not cost the others.
+    }
+  }
+  items.sort((a, b) => b.opened - a.opened);
+  for (const item of items) {
+    try {
+      item.close(exitCode);
+    } catch {
+      // Swallowed: an exception thrown inside `process.on("exit")` prints a
+      // stack into the host's stderr and would skip the final flush.
+    }
+  }
+}
+
+/** `: <Class>: <message>` of the fatal exception, for the closing messages. */
+export function fatalSuffix(): string {
+  if (fatal === null) return "";
+  const error = fatal.error;
+  if (error instanceof Error) {
+    const name = error.name && error.name !== "Error" ? error.name : error.constructor?.name || "Error";
+    return ` on an uncaught ${name}: ${error.message}`;
+  }
+  return ` on an uncaught ${String(error)}`;
+}
+
+/** The error an agent is closed with when the process exits under it. */
+export class ProcessExit extends Error {
+  readonly exitCode: number;
+
+  constructor(exitCode: number, what: string) {
+    super(`the process exited (code ${exitCode})${fatalSuffix()} while ${what} was still running`);
+    this.name = "ProcessExit";
+    this.exitCode = exitCode;
+  }
+}

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

@@ -0,0 +1,186 @@
+/**
+ * Telemetry for AI agents: emit events, spool them, let the daemon ship them.
+ *
+ * Three surfaces, in the order most people meet them:
+ *
+ * * **Scopes** — `session()`, `agent()`, `toolCall()`. They bind run identity
+ *   and, for the latter two, bracket a run with its own events. Callback form
+ *   by default; a `using`-compatible `.open()` for the cases a callback cannot
+ *   express.
+ * * **Adapters** — `instrument()`. Wires LangChain/LangGraph, the Vercel AI
+ *   SDK, Mastra and LlamaIndex.TS to the scopes above.
+ * * **`event.*`** — the 15 event methods, for anything the adapters do not
+ *   cover.
+ *
+ * `sessionId` and `agentId` are optional on every event method: omitted, they
+ * resolve from the enclosing scope. Nothing bound and nothing passed is an
+ * error, never a silent drop — ingest skips an event with no session and
+ * answers 200.
+ *
+ * ## Shutdown
+ *
+ * Buffered events are flushed on `process.on("exit")` automatically. A process
+ * that is killed by a signal never reaches that, and Node's default for SIGTERM
+ * is to terminate without running exit handlers — so a containerised agent
+ * loses whatever the last interval had not yet written. Installing a signal
+ * handler from a library would change the process's behaviour (a listener
+ * suppresses Node's default termination), so this package will not do it for
+ * you. Two lines, at your own startup:
+ *
+ *     for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143]] as const) {
+ *       process.once(signal, () => { failproofai.flushSync(); process.exit(code); });
+ *     }
+ *
+ * 128 + the signal number, so an orchestrator sees a termination rather than a
+ * success. On the way out, anything still open — a tool, a hook, a model call,
+ * an agent, including those an adapter opened — is closed with a `ProcessExit`
+ * error, so an interrupted run never renders as running forever.
+ */
+
+import { setEnvironment, rejectComma } from "./environment.js";
+import type { EventNamespace } from "./events.js";
+import { setBaseDir } from "./resolver.js";
+import { runtime } from "./runtime.js";
+import { VERSION } from "./version.js";
+import { flushAllNow, flushAllSync, validatedInterval } from "./writer.js";
+
+export { VERSION as version };
+
+export { current, propagate, DEFAULT_AGENT_ID } from "./context.js";
+export type { Identity } from "./context.js";
+
+export { session, agent, toolCall, AUTO, ToolCall } from "./scopes.js";
+export type {
+  AgentOptions,
+  AgentScope,
+  ParentId,
+  SessionOptions,
+  SessionScope,
+  ToolCallOptions,
+  ToolCallScope,
+} from "./scopes.js";
+
+export type {
+  AgentEndOptions,
+  AgentPauseOptions,
+  AgentResumeOptions,
+  AgentStartOptions,
+  ErrorOptions,
+  HookCompletedOptions,
+  HookTriggeredOptions,
+  HumanInputOptions,
+  HumanInterruptOptions,
+  HumanPauseOptions,
+  HumanWaitOptions,
+  ModelRequestOptions,
+  ModelResponseOptions,
+  ToolResultOptions,
+  ToolUseOptions,
+} from "./events.js";
+
+export { setLogger, setLogLevel } from "./logger.js";
+export type { Logger, LogLevel } from "./logger.js";
+
+export {
+  available as availableFrameworks,
+  activeFrameworks,
+  instrument,
+  uninstrument,
+} from "./integrations/index.js";
+export type { FrameworkName, InstrumentOptions } from "./integrations/index.js";
+
+export interface ConfigureOptions {
+  /**
+   * Override the spool root. Omitted, it resolves to
+   * `~/.failproofai/custom-agents` (honouring `$FAILPROOFAI_HOME`, which moves
+   * the umbrella but cannot take the spool outside it — the `custom-agents`
+   * segment is always appended).
+   *
+   * This is the ONLY way to spool anywhere else. No environment variable
+   * redirects it, because a redirect with no confirmation and no error means
+   * batches land in a directory nothing reads, and an unread spool is
+   * indistinguishable from an idle one.
+   */
+  baseDir?: string | null;
+  /** Seconds between flush cycles. Default 0.5 (500 ms). */
+  flushInterval?: number;
+  /**
+   * Deployment environment label (e.g. "production", "staging"). Can also be
+   * set with `AGENTEYE_ENVIRONMENT`. Defaults to "dev" when neither is set.
+   */
+  environment?: string | null;
+}
+
+/**
+ * Configure the SDK. Call once at startup, before any `event.*` call.
+ *
+ * Throws if `flushInterval` is not a finite number greater than zero, or if
+ * `environment` contains a comma.
+ *
+ * BOTH validations run before ANY of it is applied, so a rejected call leaves
+ * the SDK exactly as it was rather than with a new `baseDir` and the old
+ * interval. Applying as we went meant
+ * `configure({ baseDir, environment: "prod,eu" })` threw having already moved
+ * the spool — precisely the half-applied state a caller who wraps startup in a
+ * `try/catch` (a reasonable thing to do for a telemetry library that must not
+ * crash the agent) was left shipping from.
+ */
+export function configure(options: ConfigureOptions = {}): void {
+  const flushInterval = validatedInterval(options.flushInterval ?? 0.5);
+  if (options.environment) rejectComma(options.environment, "configure({ environment })");
+  setBaseDir(options.baseDir ?? null);
+  runtime.writer.setFlushInterval(flushInterval);
+  setEnvironment(options.environment ?? null);
+}
+
+/**
+ * The 15 event methods.
+ *
+ * A forwarding view of the process-wide namespace rather than a direct
+ * reference, so a test can replace `runtime.event` with a recording namespace
+ * and every call site — including the adapters and the scopes — picks it up.
+ */
+export const event: EventNamespace = new Proxy(Object.create(null) as EventNamespace, {
+  get(_target, property) {
+    const value = (runtime.event as unknown as Record<PropertyKey, unknown>)[property];
+    return typeof value === "function"
+      ? (value as (...args: unknown[]) => unknown).bind(runtime.event)
+      : value;
+  },
+  has(_target, property) {
+    return property in (runtime.event as unknown as object);
+  },
+});
+
+/**
+ * Write everything buffered, now.
+ *
+ * Awaitable, so a short-lived script or a serverless handler can guarantee its
+ * events reached disk before returning — the interval alone does not, and a
+ * function that returns immediately after its last event routinely exits before
+ * the next cycle.
+ */
+export async function flush(): Promise<void> {
+  await flushAllNow();
+}
+
+/**
+ * The synchronous flush, for a signal handler or an `exit` listener, where
+ * awaiting is not possible. Blocks; use `flush()` anywhere else.
+ */
+export function flushSync(): void {
+  flushAllSync();
+}
+
+// The per-framework call-site helpers live on subpaths rather than here:
+//
+//     import { telemetry, wrapModel } from "@failproofai/sdk/ai";
+//     import { wrapTool, workflow }    from "@failproofai/sdk/mastra";
+//     import { langchainHandler }      from "@failproofai/sdk/langchain";
+//     import { Evaluator }             from "@failproofai/sdk/evaluator";
+//
+// Re-exporting them here would make `import "@failproofai/sdk"` evaluate every
+// adapter module in the package — cheap, since none of them imports its
+// framework at module scope, but it is exactly the creep that ends with the
+// root import pulling in half the ecosystem. A subpath costs one line at the
+// call site and keeps that impossible.