failproofai 1.0.7-beta.1 → 1.0.7-beta.2

package/.next/standalone/sdk/typescript/integration/fixtures/types/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "failproofai-it-types",
+  "private": true,
+  "description": "Integration fixture: the packed @failproofai/sdk's type declarations under every consumer tsconfig, on the newest and the oldest supported TypeScript. No \"type\" field on purpose: a .ts file here is CommonJS, as in a default `npm init` project.",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@types/node": "22.20.4",
+    "typescript": "5.9.3",
+    "typescript-min": "npm:typescript@5.4.5"
+  }
+}

package/.next/standalone/sdk/typescript/integration/fixtures/vanilla/agent.ts

@@ -0,0 +1,197 @@
+/**
+ * No framework — a real agent loop, hand-instrumented.
+ *
+ *     npm install @failproofai/sdk openai
+ *     OPENAI_API_KEY=… npx tsx examples/research-agent.ts
+ *
+ * A working tool-calling loop against the OpenAI API with no agent framework at
+ * all, instrumented by hand. The reference for "my agent is bespoke" — and the
+ * TypeScript twin of the Python SDK's `docs/manual/examples/research_agent.py`.
+ *
+ * Every hand-built agent already has three places this touches, whatever its
+ * functions are called:
+ *
+ *   1. where ONE RUN starts and ends      → failproofai.agent()          agent_start / agent_end
+ *   2. the ONE FUNCTION that calls a model → event.modelRequest/Response  one pair per model turn
+ *   3. the ONE FUNCTION that runs a tool   → failproofai.toolCall()       tool_use / tool_result
+ *
+ * Identity is ambient: everything inside `agent()` lands on its session, so
+ * nothing else in the program changes. The one rule: emit the pairs — a
+ * `model_request` with no `model_response` is a span the dashboard shows as
+ * running forever.
+ *
+ * Environment: OPENAI_API_KEY; optionally OPENAI_BASE_URL (any OpenAI-compatible
+ * endpoint) and MODEL (default gpt-4o-mini).
+ */
+import { randomUUID } from "node:crypto";
+
+import * as failproofai from "@failproofai/sdk";
+import OpenAI from "openai";
+import type { ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions";
+
+failproofai.configure({ environment: "examples" });
+
+const client = new OpenAI(); // reads OPENAI_API_KEY / OPENAI_BASE_URL
+const MODEL = process.env.MODEL ?? "gpt-4o-mini";
+
+// ---------------------------------------------------------------- the tools
+
+const PRICE: Record<string, number> = { widget: 42.0, gadget: 17.5 };
+const STOCK: Record<string, number> = { widget: 120, gadget: 0 };
+
+const TOOLS: ChatCompletionTool[] = [
+  {
+    type: "function",
+    function: {
+      name: "price_of",
+      description: "Unit price of an item. Valid: widget, gadget.",
+      parameters: { type: "object", properties: { item: { type: "string" } }, required: ["item"] },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "stock_of",
+      description: "Units in stock. Valid: widget, gadget.",
+      parameters: { type: "object", properties: { item: { type: "string" } }, required: ["item"] },
+    },
+  },
+];
+
+function runTool(name: string, args: { item?: string }): string {
+  const item = String(args.item ?? "").toLowerCase().trim();
+  const table = name === "price_of" ? PRICE : name === "stock_of" ? STOCK : null;
+  if (table === null) throw new Error(`unknown tool ${name}`);
+  if (!(item in table)) throw new Error(`unknown item ${JSON.stringify(item)}`);
+  return String(table[item]);
+}
+
+// ---------------------------------------------------------- edit site 2 of 3
+// The one function that calls the model. `requestId` pairs the two halves even
+// when calls overlap; `duration_ms` is yours to set — model events are not
+// timed for you. A failed call still closes its pair, with the error, before
+// rethrowing: the enclosing agent() then ends "failed". Only the provider call
+// sits in the `try`, so nothing but a failed call can reach the error path.
+
+async function callModel(messages: ChatCompletionMessageParam[]) {
+  const requestId = randomUUID();
+  const started = Date.now();
+  failproofai.event.modelRequest({
+    model: MODEL,
+    requestId,
+    // Role and content, plus the ids that link a tool result to the call that
+    // asked for it: what a reader of the trace needs, not the provider's full
+    // message objects.
+    messages: messages.map((m) => ({
+      role: m.role,
+      content: typeof m.content === "string" ? m.content : m.content == null ? "" : JSON.stringify(m.content),
+      ...(m.role === "tool" ? { tool_call_id: m.tool_call_id } : {}),
+      ...(m.role === "assistant" && m.tool_calls
+        ? { tool_calls: m.tool_calls.map((c) => ({ id: c.id, name: c.type === "function" ? c.function.name : c.type })) }
+        : {}),
+    })),
+    tools: TOOLS.flatMap((t) => (t.type === "function" ? [{ name: t.function.name, description: t.function.description ?? "" }] : [])),
+  });
+  let reply: OpenAI.Chat.Completions.ChatCompletion;
+  try {
+    reply = await client.chat.completions.create({ model: MODEL, messages, tools: TOOLS });
+  } catch (error) {
+    failproofai.event.modelResponse({
+      model: MODEL,
+      requestId,
+      stopReason: "error",
+      error: error instanceof Error ? `${error.constructor.name}: ${error.message}` : String(error),
+      duration_ms: Date.now() - started,
+    });
+    throw error;
+  }
+  const choice = reply.choices[0]!;
+  const calls = (choice.message.tool_calls ?? []).filter((c) => c.type === "function");
+  failproofai.event.modelResponse({
+    model: reply.model,
+    requestId,
+    role: choice.message.role,
+    content: choice.message.content ?? "",
+    stopReason: choice.finish_reason,
+    inputTokens: reply.usage?.prompt_tokens ?? null,
+    outputTokens: reply.usage?.completion_tokens ?? null,
+    duration_ms: Date.now() - started,
+    // What the model asked for, so a turn that is only tool calls is not blank —
+    // the field and shape the framework adapters write.
+    fw_tool_calls: calls.map((c) => ({ toolCallId: c.id, toolName: c.function.name, input: c.function.arguments })),
+  });
+  return choice.message;
+}
+
+// ---------------------------------------------------------- edit site 3 of 3
+// The one function that runs tools. Reuse the model's own tool-call id, so a
+// tool_use lines up with the tool_calls[] entry that asked for it. toolCall()
+// times it and records a throw as tool_result.error — then rethrows, and here
+// the loop turns that into a tool message so the model can recover.
+
+async function dispatch(call: { id: string; function: { name: string; arguments: string } }): Promise<string> {
+  // Malformed arguments from the model are still a tool call: recorded with the
+  // raw text as input and failed inside toolCall(), so the trace shows it and
+  // the model gets an error it can recover from — not a crashed run, and not a
+  // call that silently never appears.
+  let args: { item?: string } = {};
+  let malformed: unknown;
+  try {
+    const parsed: unknown = JSON.parse(call.function.arguments || "{}");
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new TypeError("tool arguments must be a JSON object");
+    }
+    args = parsed as { item?: string };
+  } catch (error) {
+    malformed = error;
+  }
+  try {
+    const input = malformed === undefined ? args : { arguments: call.function.arguments };
+    return await failproofai.toolCall(call.function.name, { toolCallId: call.id, input }, async () => {
+      if (malformed !== undefined) throw malformed;
+      return runTool(call.function.name, args);
+    });
+  } catch (error) {
+    return `error: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+// ---------------------------------------------------------- edit site 1 of 3
+// Where one run starts and ends. In a service, pass your own request or job id
+// as `sessionId`, so a session on the dashboard and a record in your own
+// database are the same string.
+
+async function main(): Promise<void> {
+  const question = process.argv[2] || "Price and stock for widget and gadget?";
+  const messages: ChatCompletionMessageParam[] = [
+    { role: "system", content: "Use the tools for every number. Be terse." },
+    { role: "user", content: question },
+  ];
+
+  let sessionId = "";
+  const answer = await failproofai.agent("inventory", { goal: question }, async (identity) => {
+    sessionId = identity.sessionId ?? "";
+    for (let turn = 0; turn < 6; turn++) {
+      // bounded: an unbounded agent loop is its own bug
+      const message = await callModel(messages);
+      const calls = (message.tool_calls ?? []).filter((c) => c.type === "function");
+      if (calls.length === 0) return message.content ?? "";
+      messages.push(message);
+      for (const call of calls) {
+        messages.push({ role: "tool", tool_call_id: call.id, content: await dispatch(call) });
+      }
+    }
+    return "(gave up after 6 turns)";
+  });
+
+  console.log(answer);
+  console.log(`session ${sessionId}`);
+}
+
+main()
+  .catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  })
+  // A short script must flush before it exits; a server flushes on its own.
+  .finally(() => failproofai.flush());

package/.next/standalone/sdk/typescript/integration/fixtures/vanilla/package-lock.json

@@ -0,0 +1,70 @@
+{
+  "name": "failproofai-it-vanilla",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "failproofai-it-vanilla",
+      "dependencies": {
+        "openai": "7.23.0"
+      },
+      "devDependencies": {
+        "@types/node": "22.20.4"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "22.20.4",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.4.tgz",
+      "integrity": "sha512-zJRE40jpHtKqE/C4fgHrAKQLJuSpzEnP9ff9Y7YtoR3Wd2pwqzlekDeEuUQXjRd+QCYnVnNwuJYmhdk9XV8gvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/openai": {
+      "version": "7.23.0",
+      "resolved": "https://registry.npmjs.org/openai/-/openai-7.23.0.tgz",
+      "integrity": "sha512-0ecOXnFSMNWZq6cUBcTV6Lf93y+fm8BH/+QzFvpoP1UGNOE5pnytRa6HAPGCw+3IS9SIAW7rc1M8yyzN1PiBAQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "peerDependencies": {
+        "@aws-sdk/credential-provider-node": ">=3.972.0 <4",
+        "@smithy/hash-node": ">=4.3.0 <5",
+        "@smithy/signature-v4": ">=5.4.0 <6",
+        "undici": ">=5 <9",
+        "ws": "^8.21.0",
+        "zod": "^3.25 || ^4.0"
+      },
+      "peerDependenciesMeta": {
+        "@aws-sdk/credential-provider-node": {
+          "optional": true
+        },
+        "@smithy/hash-node": {
+          "optional": true
+        },
+        "@smithy/signature-v4": {
+          "optional": true
+        },
+        "undici": {
+          "optional": true
+        },
+        "ws": {
+          "optional": true
+        },
+        "zod": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}

package/.next/standalone/sdk/typescript/integration/fixtures/vanilla/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "failproofai-it-vanilla",
+  "private": true,
+  "type": "module",
+  "description": "Integration fixture: a hand-instrumented agent with no framework (examples/research-agent.ts), on the real openai client, against the packed @failproofai/sdk.",
+  "dependencies": {
+    "openai": "7.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.4"
+  }
+}

package/.next/standalone/sdk/typescript/integration/fixtures/vanilla/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "files": ["agent.ts"]
+}

package/.next/standalone/sdk/typescript/integration/global-setup.ts

@@ -0,0 +1,29 @@
+import type { TestProject } from "vitest/node";
+
+import { fixtures, installFixture, packedTarball } from "./harness.js";
+
+declare module "vitest" {
+  export interface ProvidedContext {
+    tarball: string;
+  }
+}
+
+/**
+ * Pack the SDK once and install every fixture before any test runs.
+ *
+ * A fixture that fails to install FAILS the run. There is no skip: the Python
+ * SDK's integration job learned the hard way that "4 skipped" reads as green
+ * while testing nothing (`AGENTEYE_TESTS_REQUIRE_FRAMEWORKS`), and a harness
+ * whose only job is to prove the frameworks work cannot be allowed to pass
+ * without them.
+ */
+export default async function setup(project: TestProject): Promise<void> {
+  const tarball = packedTarball();
+  project.provide("tarball", tarball);
+  const only = process.env.FAILPROOFAI_IT_FIXTURES?.split(",").filter(Boolean);
+  await Promise.all(
+    fixtures()
+      .filter((name) => !only || only.includes(name))
+      .map((name) => installFixture(name, tarball)),
+  );
+}