@deftai/directive-core 0.89.0 → 0.90.0

package/dist/tool-events/summarize.js

@@ -0,0 +1,93 @@
+/**
+ * Aggregate tool-event classifications into counts, anomalies, and status lines (#2967).
+ * Pure: no I/O.
+ */
+import { classifyToolEvent } from "./classify.js";
+import { TOOL_EVENT_BUCKETS, } from "./types.js";
+export function emptyBucketCounts() {
+    return {
+        explore: 0,
+        commit: 0,
+        verify: 0,
+        coordinate: 0,
+        unknown: 0,
+    };
+}
+/** Count classified buckets for a sequence of tool events. */
+export function countToolEventBuckets(events) {
+    const counts = {
+        explore: 0,
+        commit: 0,
+        verify: 0,
+        coordinate: 0,
+        unknown: 0,
+    };
+    for (const event of events) {
+        const { bucket } = classifyToolEvent(event);
+        counts[bucket] += 1;
+    }
+    return counts;
+}
+/**
+ * Detect operator-facing anomalies from bucket counts.
+ *
+ * Rules (conservative — only fire when the mix is clearly wrong):
+ * - commit-without-explore: commit > 0 and explore === 0
+ * - verify-skipped: commit > 0 and verify === 0 (ship without gates)
+ * - explore-only: explore > 0, commit === 0, verify === 0, and total >= 3
+ *   (thrash / stuck-reading signal; small explore-only sessions stay quiet)
+ */
+export function detectToolEventAnomalies(counts) {
+    const anomalies = [];
+    const total = counts.explore + counts.commit + counts.verify + counts.coordinate + counts.unknown;
+    if (counts.commit > 0 && counts.explore === 0) {
+        anomalies.push({
+            code: "commit-without-explore",
+            message: `commit-without-explore: ${counts.commit} commit event(s) with 0 explore`,
+        });
+    }
+    if (counts.commit > 0 && counts.verify === 0) {
+        anomalies.push({
+            code: "verify-skipped",
+            message: `verify-skipped: ${counts.commit} commit event(s) with 0 verify`,
+        });
+    }
+    if (counts.explore > 0 && counts.commit === 0 && counts.verify === 0 && total >= 3) {
+        anomalies.push({
+            code: "explore-only",
+            message: `explore-only: ${counts.explore} explore event(s) with 0 commit and 0 verify (possible thrash)`,
+        });
+    }
+    return anomalies;
+}
+/**
+ * Compact status line for swarm monitor / review-cycle batch brief.
+ * Example: `tools: explore=3 commit=2 verify=1 coordinate=0 unknown=0`
+ */
+export function formatToolEventStatusLine(counts) {
+    const parts = TOOL_EVENT_BUCKETS.map((b) => `${b}=${counts[b]}`);
+    return `tools: ${parts.join(" ")}`;
+}
+/**
+ * One-line anomaly suffix for status surfaces.
+ * Empty string when no anomalies.
+ */
+export function formatToolEventAnomalyLine(anomalies) {
+    if (anomalies.length === 0)
+        return "";
+    return `anomalies: ${anomalies.map((a) => a.code).join(",")}`;
+}
+/**
+ * Full summary for a tool-event sequence — counts, anomalies, status line.
+ * When anomalies exist, statusLine appends `| anomalies: …`.
+ */
+export function summarizeToolEvents(events) {
+    const counts = countToolEventBuckets(events);
+    const anomalies = detectToolEventAnomalies(counts);
+    const total = counts.explore + counts.commit + counts.verify + counts.coordinate + counts.unknown;
+    const base = formatToolEventStatusLine(counts);
+    const anomalyLine = formatToolEventAnomalyLine(anomalies);
+    const statusLine = anomalyLine.length > 0 ? `${base} | ${anomalyLine}` : base;
+    return { total, counts, anomalies, statusLine };
+}
+//# sourceMappingURL=summarize.js.map

package/dist/tool-events/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool-event taxonomy types for explore/commit/verify classification (#2967).
+ * Pure types only — no I/O.
+ */
+/** Deterministic activity buckets for swarm/review operator skim. */
+export type ToolEventBucket = "explore" | "commit" | "verify" | "coordinate" | "unknown";
+/** All buckets in stable report order (unknown last). */
+export declare const TOOL_EVENT_BUCKETS: readonly ToolEventBucket[];
+/**
+ * Minimal tool-event input. Prefer tool name + coarse args; never require
+ * full host payloads. Shell tools should pass `command` when known.
+ */
+export interface ToolEventInput {
+    /** Host tool name (e.g. `Read`, `Shell`, `Write`, `Task`). */
+    readonly name: string;
+    /**
+     * Coarse args bag — common keys: `command`, `cmd`, `path`, `file_path`,
+     * `query`, `pattern`. Values may be strings or other JSON-ish primitives.
+     */
+    readonly args?: Readonly<Record<string, unknown>> | null;
+    /**
+     * Explicit shell/command string when not nested under `args`.
+     * Wins over `args.command` / `args.cmd` when both are set.
+     */
+    readonly command?: string | null;
+}
+/** Result of classifying one tool event. */
+export interface ClassifyToolEventResult {
+    readonly bucket: ToolEventBucket;
+    /** Stable machine-oriented reason code for tests and debug. */
+    readonly reason: string;
+}
+/** Per-bucket event counts (always includes every bucket key). */
+export type ToolEventBucketCounts = Readonly<Record<ToolEventBucket, number>>;
+/**
+ * Operator-facing anomaly codes derived from a sequence of classified events.
+ * Detection is conservative: only fire when the mix is clearly wrong.
+ */
+export type ToolEventAnomalyCode = "commit-without-explore" | "verify-skipped" | "explore-only";
+export interface ToolEventAnomaly {
+    readonly code: ToolEventAnomalyCode;
+    readonly message: string;
+}
+/** Aggregate summary for monitor status lines and batch briefs. */
+export interface ToolEventSummary {
+    readonly total: number;
+    readonly counts: ToolEventBucketCounts;
+    readonly anomalies: readonly ToolEventAnomaly[];
+    /** Compact one-liner: `tools: explore=3 commit=2 verify=1 coordinate=0 unknown=0`. */
+    readonly statusLine: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tool-events/types.js

@@ -0,0 +1,13 @@
+/**
+ * Tool-event taxonomy types for explore/commit/verify classification (#2967).
+ * Pure types only — no I/O.
+ */
+/** All buckets in stable report order (unknown last). */
+export const TOOL_EVENT_BUCKETS = [
+    "explore",
+    "commit",
+    "verify",
+    "coordinate",
+    "unknown",
+];
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.89.0",
+  "version": "0.90.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -263,6 +263,10 @@
       "types": "./dist/swarm/index.d.ts",
       "default": "./dist/swarm/index.js"
     },
+    "./tool-events": {
+      "types": "./dist/tool-events/index.d.ts",
+      "default": "./dist/tool-events/index.js"
+    },
     "./review-monitor": {
       "types": "./dist/review-monitor/index.d.ts",
       "default": "./dist/review-monitor/index.js"
@@ -330,8 +334,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.89.0",
-    "@deftai/directive-types": "^0.89.0",
+    "@deftai/directive-content": "^0.90.0",
+    "@deftai/directive-types": "^0.90.0",
     "archiver": "^8.0.0"
   },
   "scripts": {