@brutal-ai/schema 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @brutal-ai/schema
 
-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 report schema and report_feedback tool. See [Brutal](https://github.com/cldixon/brutal).

package/index.d.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+/**
+ * The report schema and the canonical tool definition. Every surface (HTTP API, MCP, a future
+ * SDK and CLI) validates against these, so an agent in any language can define the tool from
+ * `toolDefinition()` and POST to the API.
+ */
+export declare const KINDS: readonly ["bug", "friction", "missing_capability", "confusing_output", "latency", "eval_candidate", "other"];
+export declare const IMPACTS: readonly ["blocked", "worked_around", "minor"];
+export declare const STATUSES: readonly ["new", "triaged", "linked", "fixed", "verified", "wont_fix"];
+export type Kind = (typeof KINDS)[number];
+export type Impact = (typeof IMPACTS)[number];
+export type Status = (typeof STATUSES)[number];
+/** What the agent supplies: its judgment. Kept small so models fill it reliably. */
+export declare const agentInput: {
+    kind: z.ZodEnum<{
+        bug: "bug";
+        friction: "friction";
+        missing_capability: "missing_capability";
+        confusing_output: "confusing_output";
+        latency: "latency";
+        eval_candidate: "eval_candidate";
+        other: "other";
+    }>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    details: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    impact: z.ZodOptional<z.ZodEnum<{
+        blocked: "blocked";
+        worked_around: "worked_around";
+        minor: "minor";
+    }>>;
+    user_impact: z.ZodOptional<z.ZodString>;
+};
+export declare const AgentInput: z.ZodObject<{
+    kind: z.ZodEnum<{
+        bug: "bug";
+        friction: "friction";
+        missing_capability: "missing_capability";
+        confusing_output: "confusing_output";
+        latency: "latency";
+        eval_candidate: "eval_candidate";
+        other: "other";
+    }>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    details: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    impact: z.ZodOptional<z.ZodEnum<{
+        blocked: "blocked";
+        worked_around: "worked_around";
+        minor: "minor";
+    }>>;
+    user_impact: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentInput = z.infer<typeof AgentInput>;
+/** One recorded tool call, attached by the integration, never written by the agent. */
+export declare const ToolCall: z.ZodObject<{
+    name: z.ZodString;
+    args: z.ZodOptional<z.ZodUnknown>;
+    status: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+    }>>;
+    latency_ms: z.ZodOptional<z.ZodNumber>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ToolCall = z.infer<typeof ToolCall>;
+/** What the integration supplies: context, never asked of the agent. */
+export declare const Context: z.ZodObject<{
+    conversation_id: z.ZodOptional<z.ZodString>;
+    turn_id: z.ZodOptional<z.ZodString>;
+    app_version: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    deploy_id: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    agent_name: z.ZodOptional<z.ZodString>;
+    trace_id: z.ZodOptional<z.ZodString>;
+    user_id: z.ZodOptional<z.ZodString>;
+    sdk: z.ZodOptional<z.ZodString>;
+    sdk_version: z.ZodOptional<z.ZodString>;
+    recent_tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        args: z.ZodOptional<z.ZodUnknown>;
+        status: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+        }>>;
+        latency_ms: z.ZodOptional<z.ZodNumber>;
+        result: z.ZodOptional<z.ZodUnknown>;
+        error: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Context = z.infer<typeof Context>;
+/** The body of `POST /v1/reports`: the agent's fields, plus the integration's `context`. */
+export declare const ReportInput: z.ZodObject<{
+    kind: z.ZodEnum<{
+        bug: "bug";
+        friction: "friction";
+        missing_capability: "missing_capability";
+        confusing_output: "confusing_output";
+        latency: "latency";
+        eval_candidate: "eval_candidate";
+        other: "other";
+    }>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    details: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    impact: z.ZodOptional<z.ZodEnum<{
+        blocked: "blocked";
+        worked_around: "worked_around";
+        minor: "minor";
+    }>>;
+    user_impact: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodObject<{
+        conversation_id: z.ZodOptional<z.ZodString>;
+        turn_id: z.ZodOptional<z.ZodString>;
+        app_version: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        deploy_id: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        agent_name: z.ZodOptional<z.ZodString>;
+        trace_id: z.ZodOptional<z.ZodString>;
+        user_id: z.ZodOptional<z.ZodString>;
+        sdk: z.ZodOptional<z.ZodString>;
+        sdk_version: z.ZodOptional<z.ZodString>;
+        recent_tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            args: z.ZodOptional<z.ZodUnknown>;
+            status: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                ok: "ok";
+            }>>;
+            latency_ms: z.ZodOptional<z.ZodNumber>;
+            result: z.ZodOptional<z.ZodUnknown>;
+            error: z.ZodOptional<z.ZodString>;
+            at: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReportInput = z.infer<typeof ReportInput>;
+/** The body of `PATCH /v1/reports/:id`. */
+export declare const ReportUpdate: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        new: "new";
+        triaged: "triaged";
+        linked: "linked";
+        fixed: "fixed";
+        verified: "verified";
+        wont_fix: "wont_fix";
+    }>>;
+    issue_url: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+}, z.core.$strip>;
+export type ReportUpdate = z.infer<typeof ReportUpdate>;
+/** A stored report, as the read API returns it. */
+export interface Report extends AgentInput {
+    id: string;
+    status: Status;
+    issue_url: string | null;
+    context: Context;
+    created_at: string;
+    updated_at: string;
+}
+export declare const TOOL_NAME = "report_feedback";
+export declare const TOOL_VERSION = "2026-11-05";
+/** The tool's wording is where most of the product's quality lives: version it with TOOL_VERSION. */
+export declare const TOOL_DESCRIPTION: string;
+/** What the tool answers. It never fails the agent's turn. */
+export declare const TOOL_ACK = "Feedback recorded.";
+/** The canonical tool definition, in the shape most model APIs take (name, description, JSON Schema). */
+export declare function toolDefinition(): {
+    name: string;
+    version: string;
+    description: string;
+    input_schema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        kind: z.ZodEnum<{
+            bug: "bug";
+            friction: "friction";
+            missing_capability: "missing_capability";
+            confusing_output: "confusing_output";
+            latency: "latency";
+            eval_candidate: "eval_candidate";
+            other: "other";
+        }>;
+        title: z.ZodString;
+        summary: z.ZodString;
+        details: z.ZodOptional<z.ZodString>;
+        tool_name: z.ZodOptional<z.ZodString>;
+        impact: z.ZodOptional<z.ZodEnum<{
+            blocked: "blocked";
+            worked_around: "worked_around";
+            minor: "minor";
+        }>>;
+        user_impact: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};

package/index.js

@@ -0,0 +1,80 @@
+// packages/schema/src/index.ts
+import { z } from "zod";
+var KINDS = [
+  "bug",
+  "friction",
+  "missing_capability",
+  "confusing_output",
+  "latency",
+  "eval_candidate",
+  "other"
+];
+var IMPACTS = ["blocked", "worked_around", "minor"];
+var STATUSES = ["new", "triaged", "linked", "fixed", "verified", "wont_fix"];
+var agentInput = {
+  kind: z.enum(KINDS).describe("What sort of report this is."),
+  title: z.string().min(1).max(100).describe("A short title, under 100 characters."),
+  summary: z.string().min(1).max(500).describe("What happened, in one or two sentences."),
+  details: z.string().max(1e4).optional().describe("What you tried, what you expected, what you got, and a suggested fix."),
+  tool_name: z.string().max(200).optional().describe("The tool the report is about, if any."),
+  impact: z.enum(IMPACTS).optional().describe("blocked: could not finish; worked_around: finished another way; minor."),
+  user_impact: z.string().max(1000).optional().describe("How the end user was affected, if at all.")
+};
+var AgentInput = z.object(agentInput);
+var ToolCall = z.object({
+  name: z.string().max(200),
+  args: z.unknown().optional(),
+  status: z.enum(["ok", "error"]).optional(),
+  latency_ms: z.number().nonnegative().optional(),
+  result: z.unknown().optional(),
+  error: z.string().max(4000).optional(),
+  at: z.string().optional()
+});
+var Context = z.object({
+  conversation_id: z.string().max(200),
+  turn_id: z.string().max(200),
+  app_version: z.string().max(100),
+  branch: z.string().max(200),
+  deploy_id: z.string().max(200),
+  environment: z.string().max(100),
+  model: z.string().max(200),
+  agent_name: z.string().max(200),
+  trace_id: z.string().max(200),
+  user_id: z.string().max(200),
+  sdk: z.string().max(100),
+  sdk_version: z.string().max(100),
+  recent_tool_calls: z.array(ToolCall).max(50)
+}).partial();
+var ReportInput = AgentInput.extend({ context: Context.optional() });
+var ReportUpdate = z.object({
+  status: z.enum(STATUSES),
+  issue_url: z.url({ protocol: /^https?$/ }).max(2000).nullable()
+}).partial();
+var TOOL_NAME = "report_feedback";
+var TOOL_VERSION = "2026-11-05";
+var TOOL_DESCRIPTION = "Use this to privately tell the developers of this application about problems or notable tasks. " + "The user does not see this call. Report when: a tool errors, rejects a reasonable input, " + "returns results that look wrong or suspiciously empty, cannot express what the user asked, " + "or is slow; the UI or input makes the task harder; or the task is unusually interesting or " + "hard and would make a good evaluation case (kind: eval_candidate). Be specific: name the " + "tool, what you tried, what you expected and what happened. Report once per distinct issue, " + "then continue helping the user. Never include secrets or personal data beyond what is " + "needed to reproduce.";
+var TOOL_ACK = "Feedback recorded.";
+function toolDefinition() {
+  return {
+    name: TOOL_NAME,
+    version: TOOL_VERSION,
+    description: TOOL_DESCRIPTION,
+    input_schema: z.toJSONSchema(AgentInput)
+  };
+}
+export {
+  AgentInput,
+  Context,
+  IMPACTS,
+  KINDS,
+  ReportInput,
+  ReportUpdate,
+  STATUSES,
+  TOOL_ACK,
+  TOOL_DESCRIPTION,
+  TOOL_NAME,
+  TOOL_VERSION,
+  ToolCall,
+  agentInput,
+  toolDefinition
+};

package/package.json

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