@brutal-ai/sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @brutal-ai/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Brutal's TypeScript SDK: the report_feedback tool and a recorder of recent tool calls. See [Brutal](https://github.com/cldixon/brutal).

package/index.d.ts

@@ -0,0 +1,106 @@
+import { type Context, type ReportInput, type ToolCall, toolDefinition } from "@brutal-ai/schema";
+/**
+ * The TypeScript SDK. Give the agent the `report_feedback` tool, wrap its other tools so their
+ * recent calls are recorded, and every report the agent files arrives with that context attached.
+ * The agent supplies only its judgment. Delivery never slows or fails the agent's turn.
+ *
+ *   const brutal = createBrutal({ endpoint, ingestKey, context: () => ({ app_version }) });
+ *   const convo = brutal.conversation(conversationId);
+ *   const search = convo.wrap("search_parts", searchParts);
+ *   tools: [brutal.anthropicTool(), …]; on a report_feedback call: await convo.handle(input)
+ */
+export interface BrutalOptions {
+    /** The Brutal Worker's URL, e.g. https://brutal.example.workers.dev. */
+    endpoint: string;
+    /** An ingest key: it can only submit reports. Keep it on the server. */
+    ingestKey: string;
+    /** Context added to every report: app version, branch, environment, model, agent name. */
+    context?: () => Partial<Context>;
+    /** Last chance to scrub a report before it leaves the app; return null to drop it. */
+    redact?: (report: ReportInput) => ReportInput | null;
+    /** How many recent tool calls to keep per conversation (default 20). */
+    maxRecentCalls?: number;
+    /** Characters kept of each recorded call's args and result (default 2000). */
+    maxFieldChars?: number;
+    /** How long a report may take before it is given up on (default 3000 ms). */
+    timeoutMs?: number;
+    /** Told when a report could not be delivered. Never thrown to the agent. */
+    onError?: (error: unknown) => void;
+    fetch?: typeof fetch;
+}
+export declare function createBrutal(options: BrutalOptions): {
+    report: (input: ReportInput) => Promise<boolean>;
+    conversation: (conversationId: string, extra?: Partial<Context>) => {
+        /** Records one tool call by hand. */
+        record: (call: ToolCall) => void;
+        /** Wraps a tool so each call is recorded with its args, result or error, and latency. */
+        wrap<A extends unknown[], R>(name: string, fn: (...args: A) => R | Promise<R>): (...args: A) => Promise<R>;
+        /** The recorded calls, oldest first. */
+        recent: () => ToolCall[];
+        /**
+         * Handles the agent's `report_feedback` call: validates its input, attaches the context
+         * and recent tool calls, sends it, and returns the line to give back to the agent. A bad
+         * input is still sent (as `other`), so the report is not lost to a model's mistake.
+         */
+        handle(input: unknown): Promise<string>;
+    };
+    /** The canonical tool: name, description, JSON Schema. */
+    definition: typeof toolDefinition;
+    /** The tool for the Anthropic Messages API (`tools: [...]`). */
+    anthropicTool(): {
+        name: string;
+        description: string;
+        input_schema: import("zod/v4/core").ZodStandardJSONSchemaPayload<import("zod").ZodObject<{
+            kind: import("zod").ZodEnum<{
+                bug: "bug";
+                friction: "friction";
+                missing_capability: "missing_capability";
+                confusing_output: "confusing_output";
+                latency: "latency";
+                eval_candidate: "eval_candidate";
+                other: "other";
+            }>;
+            title: import("zod").ZodString;
+            summary: import("zod").ZodString;
+            details: import("zod").ZodOptional<import("zod").ZodString>;
+            tool_name: import("zod").ZodOptional<import("zod").ZodString>;
+            impact: import("zod").ZodOptional<import("zod").ZodEnum<{
+                blocked: "blocked";
+                worked_around: "worked_around";
+                minor: "minor";
+            }>>;
+            user_impact: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>;
+    };
+    /**
+     * The tool for the Vercel AI SDK (`tools: { report_feedback: … }`): a zod schema, which the
+     * AI SDK takes as is, and an `execute` bound to one conversation.
+     */
+    aiSdkTool(conversationId: string, extra?: Partial<Context>): {
+        description: string;
+        inputSchema: import("zod").ZodObject<{
+            kind: import("zod").ZodEnum<{
+                bug: "bug";
+                friction: "friction";
+                missing_capability: "missing_capability";
+                confusing_output: "confusing_output";
+                latency: "latency";
+                eval_candidate: "eval_candidate";
+                other: "other";
+            }>;
+            title: import("zod").ZodString;
+            summary: import("zod").ZodString;
+            details: import("zod").ZodOptional<import("zod").ZodString>;
+            tool_name: import("zod").ZodOptional<import("zod").ZodString>;
+            impact: import("zod").ZodOptional<import("zod").ZodEnum<{
+                blocked: "blocked";
+                worked_around: "worked_around";
+                minor: "minor";
+            }>>;
+            user_impact: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>;
+        execute: (input: unknown) => Promise<string>;
+    };
+    toolName: string;
+};
+export type Brutal = ReturnType<typeof createBrutal>;

package/index.js

@@ -0,0 +1,163 @@
+// packages/sdk/src/index.ts
+import {
+  AgentInput,
+  TOOL_ACK,
+  TOOL_DESCRIPTION,
+  TOOL_NAME,
+  toolDefinition
+} from "@brutal-ai/schema";
+var MAX_CONVERSATIONS = 1000;
+var SDK_VERSION = "0.1.0";
+function createBrutal(options) {
+  const maxCalls = options.maxRecentCalls ?? 20;
+  const maxChars = options.maxFieldChars ?? 2000;
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const doFetch = options.fetch ?? fetch;
+  const endpoint = options.endpoint.replace(/\/+$/, "");
+  const buffers = new Map;
+  const clip = (value) => {
+    if (value === undefined)
+      return;
+    const text = typeof value === "string" ? value : safeJson(value);
+    return text.length > maxChars ? `${text.slice(0, maxChars)}… (${text.length} chars)` : value;
+  };
+  function bufferFor(conversationId) {
+    let buffer = buffers.get(conversationId);
+    if (buffer) {
+      buffers.delete(conversationId);
+    } else {
+      buffer = [];
+      if (buffers.size >= MAX_CONVERSATIONS) {
+        const oldest = buffers.keys().next().value;
+        if (oldest !== undefined)
+          buffers.delete(oldest);
+      }
+    }
+    buffers.set(conversationId, buffer);
+    return buffer;
+  }
+  function record(conversationId, call) {
+    const buffer = bufferFor(conversationId);
+    buffer.push({
+      ...call,
+      args: clip(call.args),
+      result: clip(call.result),
+      error: call.error?.slice(0, maxChars),
+      at: call.at ?? new Date().toISOString()
+    });
+    if (buffer.length > maxCalls)
+      buffer.splice(0, buffer.length - maxCalls);
+  }
+  async function report(input) {
+    try {
+      const shaped = options.redact ? options.redact(input) : input;
+      if (!shaped)
+        return false;
+      const body = JSON.stringify(shaped);
+      const deadline = AbortSignal.timeout(timeoutMs);
+      for (let attempt = 0;; attempt++) {
+        let res;
+        try {
+          res = await doFetch(`${endpoint}/v1/reports`, {
+            method: "POST",
+            headers: {
+              authorization: `Bearer ${options.ingestKey}`,
+              "content-type": "application/json"
+            },
+            body,
+            signal: deadline
+          });
+        } catch (error) {
+          if (attempt >= 1 || deadline.aborted)
+            throw error;
+          continue;
+        }
+        if (res.ok)
+          return true;
+        if (res.status < 500 || attempt >= 1) {
+          throw new Error(`brutal: ${res.status} ${await res.text()}`);
+        }
+      }
+    } catch (error) {
+      options.onError?.(error);
+      return false;
+    }
+  }
+  function conversation(conversationId, extra = {}) {
+    return {
+      record: (call) => record(conversationId, call),
+      wrap(name, fn) {
+        return async (...args) => {
+          const started = performance.now();
+          const shownArgs = args.length === 1 ? args[0] : args;
+          try {
+            const result = await fn(...args);
+            record(conversationId, {
+              name,
+              args: shownArgs,
+              status: "ok",
+              latency_ms: Math.round(performance.now() - started),
+              result
+            });
+            return result;
+          } catch (error) {
+            record(conversationId, {
+              name,
+              args: shownArgs,
+              status: "error",
+              latency_ms: Math.round(performance.now() - started),
+              error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+          }
+        };
+      },
+      recent: () => [...buffers.get(conversationId) ?? []],
+      async handle(input) {
+        const parsed = AgentInput.safeParse(input);
+        const agent = parsed.success ? parsed.data : {
+          kind: "other",
+          title: "Unparsed report_feedback call",
+          summary: "The agent's report did not match the tool's schema.",
+          details: safeJson(input).slice(0, 1e4)
+        };
+        await report({
+          ...agent,
+          context: {
+            ...options.context?.(),
+            ...extra,
+            conversation_id: conversationId,
+            recent_tool_calls: [...buffers.get(conversationId) ?? []],
+            sdk: "@brutal-ai/sdk",
+            sdk_version: SDK_VERSION
+          }
+        });
+        return TOOL_ACK;
+      }
+    };
+  }
+  return {
+    report,
+    conversation,
+    definition: toolDefinition,
+    anthropicTool() {
+      const { name, description, input_schema } = toolDefinition();
+      return { name, description, input_schema };
+    },
+    aiSdkTool(conversationId, extra = {}) {
+      const convo = conversation(conversationId, extra);
+      return { description: TOOL_DESCRIPTION, inputSchema: AgentInput, execute: convo.handle };
+    },
+    toolName: TOOL_NAME
+  };
+}
+function safeJson(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+export {
+  createBrutal
+};

package/package.json

@@ -1,6 +1,26 @@
 {
+  "version": "0.2.0",
+  "license": "MIT",
   "name": "@brutal-ai/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Brutal's TypeScript SDK: the report_feedback tool and a recorder of recent tool calls",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cldixon/brutal.git",
+    "directory": "packages/sdk"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@brutal-ai/schema": "0.2.0"
+  }
+}