failproofai 1.0.7-beta.1 → 1.0.7

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

@@ -0,0 +1,238 @@
+/**
+ * `@failproofai/sdk` for runtimes with no filesystem: the Edge runtime (Next.js
+ * `export const runtime = "edge"`, Vercel Edge Functions), Cloudflare Workers,
+ * and browser bundles. Selected by the package's `exports` conditions
+ * (`edge-light`, `workerd`, `worker`, `browser`), so an application's own
+ * `import "@failproofai/sdk"` lands here without a code change.
+ *
+ * ## Why a separate build
+ *
+ * The real entry statically imports `node:fs`, `node:os`, `node:module` and
+ * `node:crypto`. An ES module cannot catch a failed static import, so in the
+ * Edge runtime the IMPORT itself failed — and because Next evaluates a route
+ * module while building, `next build` failed ("Native module not found:
+ * node:fs"), taking the whole application down over a telemetry import.
+ *
+ * ## What it does instead
+ *
+ * The same public surface, recording nothing: scopes run their bodies and
+ * return their values, `event.*` accepts and drops, `flush()` resolves,
+ * `instrument()` returns `[]`. The first use logs ONE line to stderr saying
+ * so. These runtimes are not a deployment target — the SDK ships beside the
+ * `failproofaid` daemon on a machine with a filesystem — so this build exists
+ * only so that a shared module importing the SDK cannot break an Edge route.
+ *
+ * Type declarations stay the real ones (the `types` condition), so code that
+ * compiles against Node compiles here too.
+ */
+
+import type { Identity } from "../context.js";
+import type { EventNamespace } from "../events.js";
+import type {
+  AgentFn,
+  AgentOptions,
+  SessionFn,
+  SessionOptions,
+  ToolCallFn,
+  ToolCallOptions,
+} from "../scopes.js";
+import { VERSION } from "../version.js";
+import { notice } from "./notice.js";
+
+export { VERSION as version };
+
+export const DEFAULT_AGENT_ID = "main";
+/** The same registered symbol as the Node build's, so comparisons still hold. */
+export const AUTO: unique symbol = Symbol.for("failproofai.AUTO") as never;
+
+// `Symbol.dispose` is not in every Edge runtime. A missing one must not become
+// the property key "undefined".
+const DISPOSE: symbol =
+  (Symbol as unknown as { dispose?: symbol }).dispose ?? Symbol.for("nodejs.dispose");
+
+let counter = 0;
+function newId(): string {
+  try {
+    const uuid = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto?.randomUUID?.();
+    if (typeof uuid === "string") return uuid.replace(/-/g, "");
+  } catch {
+    /* fall through */
+  }
+  counter += 1;
+  return `edge${Date.now().toString(16)}${counter.toString(16)}`;
+}
+
+const identityOf = (sessionId: string | null, agentId: string | null): Identity =>
+  Object.freeze({ sessionId, agentId, parentId: null, depth: agentId === null ? 0 : 1 });
+
+export function current(): Identity {
+  return identityOf(null, null);
+}
+
+export function propagate<Args extends unknown[], Result>(
+  fn: (...args: Args) => Result,
+): (...args: Args) => Result {
+  return fn;
+}
+
+/** The handle a `toolCall` body receives. Set `.output`; read `.id`. */
+export class ToolCall {
+  readonly id: string;
+  output: unknown = undefined;
+  private assigned = false;
+
+  constructor(toolCallId: string) {
+    this.id = toolCallId;
+    let stored: unknown;
+    Object.defineProperty(this, "output", {
+      get: () => stored,
+      set: (value: unknown) => {
+        stored = value;
+        this.assigned = true;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+
+  get outputAssigned(): boolean {
+    return this.assigned;
+  }
+}
+
+class Handle {
+  dispose(): void {}
+  fail(): void {}
+  [DISPOSE](): void {}
+}
+
+class SessionHandle extends Handle {
+  constructor(readonly id: string) {
+    super();
+  }
+}
+
+class AgentHandle extends Handle {
+  readonly identity: Identity;
+  constructor(
+    readonly agentId: string,
+    readonly sessionId: string,
+  ) {
+    super();
+    this.identity = identityOf(sessionId, agentId);
+  }
+}
+
+class ToolCallHandle extends Handle {
+  constructor(readonly call: ToolCall) {
+    super();
+  }
+}
+
+type Body<A, T> = (arg: A) => T;
+
+function split<O, A, T>(optionsOrBody: O | Body<A, T> | undefined, body: Body<A, T> | undefined) {
+  return typeof optionsOrBody === "function"
+    ? { options: {} as O, body: optionsOrBody as Body<A, T> }
+    : { options: (optionsOrBody ?? {}) as O, body: body! };
+}
+
+function sessionImpl<T>(optionsOrBody: SessionOptions | Body<string, T>, maybeBody?: Body<string, T>): T {
+  notice();
+  const { options, body } = split(optionsOrBody, maybeBody);
+  return body(options.sessionId ?? newId());
+}
+sessionImpl.open = (options: SessionOptions = {}) => {
+  notice();
+  return new SessionHandle(options.sessionId ?? newId());
+};
+
+function agentImpl<T>(
+  agentId: string,
+  optionsOrBody: AgentOptions | Body<Identity, T>,
+  maybeBody?: Body<Identity, T>,
+): T {
+  notice();
+  const { options, body } = split(optionsOrBody, maybeBody);
+  return body(identityOf(options.sessionId ?? null, agentId));
+}
+agentImpl.open = (agentId = DEFAULT_AGENT_ID, options: AgentOptions = {}) => {
+  notice();
+  return new AgentHandle(agentId, options.sessionId ?? newId());
+};
+
+function toolCallImpl<T>(
+  toolName: string,
+  optionsOrBody: ToolCallOptions | Body<ToolCall, T>,
+  maybeBody?: Body<ToolCall, T>,
+): T {
+  notice();
+  void toolName;
+  const { options, body } = split(optionsOrBody, maybeBody);
+  return body(new ToolCall(options.toolCallId ?? newId()));
+}
+toolCallImpl.open = (toolName: string, options: ToolCallOptions = {}) => {
+  void toolName;
+  notice();
+  return new ToolCallHandle(new ToolCall(options.toolCallId ?? newId()));
+};
+
+export const session = sessionImpl as unknown as SessionFn;
+export const agent = agentImpl as unknown as AgentFn;
+export const toolCall = toolCallImpl as unknown as ToolCallFn;
+
+const EVENT_METHODS = [
+  "toolUse",
+  "toolResult",
+  "modelRequest",
+  "modelResponse",
+  "agentStart",
+  "agentEnd",
+  "agentPause",
+  "agentResume",
+  "hookTriggered",
+  "hookCompleted",
+  "error",
+  "humanWait",
+  "humanInput",
+  "humanPause",
+  "humanInterrupt",
+] as const;
+
+/** The 15 event methods, each accepting its options and recording nothing. */
+export const event: EventNamespace = Object.freeze(
+  Object.fromEntries(EVENT_METHODS.map((name) => [name, () => notice()])),
+) as unknown as EventNamespace;
+
+export function configure(): void {
+  notice();
+}
+
+export function flush(): Promise<void> {
+  notice();
+  return Promise.resolve();
+}
+
+export function flushSync(): void {
+  notice();
+}
+
+export function setLogger(): void {}
+export function setLogLevel(): void {}
+
+export function instrument(): Promise<never[]> {
+  notice();
+  return Promise.resolve([]);
+}
+
+export function uninstrument(): never[] {
+  return [];
+}
+
+export function availableFrameworks(): never[] {
+  return [];
+}
+
+export function activeFrameworks(): never[] {
+  return [];
+}

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

@@ -0,0 +1,18 @@
+/** `@failproofai/sdk/langchain` for runtimes with no filesystem — see `./index.ts`. */
+
+import { noopAdapter } from "./adapter.js";
+import { notice } from "./notice.js";
+
+export const SESSION_METADATA_KEY = "failproofai_sdk_session_id";
+
+/**
+ * A callback handler with no callbacks. LangChain accepts any object as a
+ * handler (`BaseCallbackHandler.fromMethods`), so passing this where the Node
+ * build's handler goes is valid and inert.
+ */
+export function langchainHandler(): Record<string, unknown> {
+  notice();
+  return { name: "failproofai_noop" };
+}
+
+export const adapter = noopAdapter("langchain");

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

@@ -0,0 +1,12 @@
+/** `@failproofai/sdk/llamaindex` for runtimes with no filesystem — see `./index.ts`. */
+
+import { noopAdapter } from "./adapter.js";
+import { notice } from "./notice.js";
+
+/** Attaching to a LlamaIndex object records nothing here; returns a detach. */
+export function attach(): () => void {
+  notice();
+  return () => {};
+}
+
+export const adapter = noopAdapter("llamaindex");

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

@@ -0,0 +1,17 @@
+/** `@failproofai/sdk/mastra` for runtimes with no filesystem — see `./index.ts`. */
+
+import { noopAdapter } from "./adapter.js";
+import { notice } from "./notice.js";
+
+export function wrapTool<T>(tool: T): T {
+  notice();
+  return tool;
+}
+
+export function workflow<T>(workflowName: string, body: () => T): T {
+  void workflowName;
+  notice();
+  return body();
+}
+
+export const adapter = noopAdapter("mastra");

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

@@ -0,0 +1,33 @@
+/**
+ * The one line an Edge / Worker build says, once per isolate.
+ *
+ * Deliberately self-contained: it imports nothing, not even `logger.ts`,
+ * because that module reads environment variables at import time and a Cloudflare
+ * Worker without `nodejs_compat` has no `process` at all. Everything under
+ * `src/edge/` holds to the same rule — the whole point of these modules is that
+ * importing them cannot fail anywhere JavaScript runs.
+ */
+
+let said = false;
+
+export const EDGE_NOTICE =
+  "@failproofai/sdk loaded its no-op build: this runtime (an Edge / Worker runtime, " +
+  "or a browser bundle) has no filesystem for the local failproofaid spool, so NOTHING " +
+  "is recorded here; your code runs unchanged. Record from the Node.js runtime " +
+  '(Next.js: drop `export const runtime = "edge"` from the route).';
+
+/** Say it once. Never throws: a diagnostic must not take the host down. */
+export function notice(): void {
+  if (said) return;
+  said = true;
+  try {
+    console.warn(`[failproofai-sdk] ${EDGE_NOTICE}`);
+  } catch {
+    /* empty */
+  }
+}
+
+/** Forget that the notice was given (tests). */
+export function resetNotice(): void {
+  said = false;
+}

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

@@ -0,0 +1,75 @@
+import { logger } from "./logger.js";
+import { shared } from "./shared.js";
+
+const DEFAULT_ENVIRONMENT = "dev";
+
+
+/**
+ * Set once the comma warning below has been emitted. `getEnvironment()` runs
+ * from `build()`, i.e. once per event on the caller's own stack, and the
+ * warning had no once-flag at all in an early draft — so an
+ * `AGENTEYE_ENVIRONMENT` with a comma put one WARN line into the host
+ * application's log for every event emitted, for the life of the process. At
+ * the SDK's documented ceiling that is a logging-driven throughput collapse in
+ * a library whose first constraint is not to disrupt the host agent.
+ */
+let warnedComma = false;
+
+/**
+ * A comma in `environment` makes ingest skip EVERY event carrying it.
+ *
+ * The endpoint splits this field on commas to build its filter facets, so a
+ * line whose `environment` contains one is discarded — the whole line, not the
+ * field. It answers 200 with `{"accepted":0,"skipped":N}`, the daemon deletes
+ * the delivered batch, and the run that produced it is simply never in the
+ * dashboard: no exception here, nothing in the agent's output, and an empty
+ * session list that looks exactly like an agent nobody ran.
+ *
+ * `failproofaid` already refuses a comma in `collector.environment` for this
+ * reason (`crates/fpai-collect/src/config.rs`). The SDK is the other writer of
+ * the same field, so `AGENTEYE_ENVIRONMENT="prod,eu"` — a wholly reasonable
+ * thing to type — would silently throw away everything the process emitted.
+ */
+export function rejectComma(env: string, source: string): void {
+  if (env.includes(",")) {
+    throw new Error(
+      `environment must not contain a comma (got ${JSON.stringify(env)} from ${source}). ` +
+        "The ingest endpoint skips every event whose environment has one, so this would " +
+        "silently discard all telemetry from this process. Use a single label, e.g. 'prod-eu'.",
+    );
+  }
+}
+
+export function getEnvironment(): string {
+  const environment = shared().environment;
+  if (environment !== null) return environment;
+
+  const raw = process.env.AGENTEYE_ENVIRONMENT;
+  if (!raw) return DEFAULT_ENVIRONMENT;
+  if (raw.includes(",")) {
+    // Throwing here would blow up inside `build()` on an arbitrary event, far
+    // from the thing that set it, and take the caller's agent down with it — a
+    // telemetry library must not do that. Warn once and fall back to a label
+    // ingest will actually accept, so the events land under a visibly-wrong
+    // environment instead of vanishing.
+    if (!warnedComma) {
+      warnedComma = true;
+      logger.warn(
+        `AGENTEYE_ENVIRONMENT=${JSON.stringify(raw)} contains a comma, which makes the ingest ` +
+          `endpoint skip every event carrying it. Falling back to ${JSON.stringify(DEFAULT_ENVIRONMENT)}. ` +
+          "Use a single label, e.g. 'prod-eu'.",
+      );
+    }
+    return DEFAULT_ENVIRONMENT;
+  }
+  return raw;
+}
+
+export function setEnvironment(env: string | null | undefined): void {
+  if (env) rejectComma(env, "configure({ environment })");
+  shared().environment = env ? env : null;
+  // A new label means the env var may be worth complaining about again.
+  warnedComma = false;
+}
+
+export { DEFAULT_ENVIRONMENT };