@vauban-org/agent-sdk 0.16.0

package/src/budget/budget-state.ts

@@ -0,0 +1,234 @@
+/**
+ * budget-state — Per-run budget + coherence + compaction primitives for the
+ * Vauban agent loops.
+ *
+ * Scope:
+ *   - AgentBudgetState (mutable counters: steps, tokens, context window).
+ *   - CoherenceDetector: flags tool-call loops and stalls.
+ *   - compactToolLog: trims the middle of a long tool conversation.
+ *   - emergencyContextSummary: LLM-backed "last resort" fallback when the
+ *     context window passes 90% of its soft cap.
+ *
+ * Non-goals:
+ *   - Token counting / tokenizer accuracy (provider-router returns usage).
+ *   - Persistence of budget state (AgentRunTracker handles that).
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface AgentBudgetState {
+  stepCount: number;
+  maxSteps: number;
+  tokensBudget: {
+    input: number;
+    output: number;
+    usedInput: number;
+    usedOutput: number;
+  };
+  contextWindow: {
+    maxTokens: number;
+    currentTokens: number;
+  };
+  /** stepCount value at which compactToolLog should run. */
+  compactionTrigger: number;
+  /** 0..1 — live coherence score (1 = healthy, 0 = loop+stall). */
+  coherenceScore: number;
+}
+
+export interface CoherenceDetector {
+  check(
+    recentToolCalls: Array<{ name: string; args: unknown }>,
+    stepsWithoutTool: number,
+  ): { isLoop: boolean; isStall: boolean; score: number };
+}
+
+export type LogMessage = {
+  role: "user" | "assistant" | "tool" | "system";
+  content: string;
+  toolName?: string;
+};
+
+// ─── Defaults ─────────────────────────────────────────────────────────────
+
+const DEFAULT_BUDGET: AgentBudgetState = {
+  stepCount: 0,
+  maxSteps: 20,
+  tokensBudget: { input: 200_000, output: 50_000, usedInput: 0, usedOutput: 0 },
+  contextWindow: { maxTokens: 200_000, currentTokens: 0 },
+  compactionTrigger: 15,
+  coherenceScore: 1,
+};
+
+export function createBudgetState(
+  overrides?: Partial<AgentBudgetState>,
+): AgentBudgetState {
+  return {
+    stepCount: overrides?.stepCount ?? DEFAULT_BUDGET.stepCount,
+    maxSteps: overrides?.maxSteps ?? DEFAULT_BUDGET.maxSteps,
+    tokensBudget: {
+      ...DEFAULT_BUDGET.tokensBudget,
+      ...overrides?.tokensBudget,
+    },
+    contextWindow: {
+      ...DEFAULT_BUDGET.contextWindow,
+      ...overrides?.contextWindow,
+    },
+    compactionTrigger:
+      overrides?.compactionTrigger ?? DEFAULT_BUDGET.compactionTrigger,
+    coherenceScore: overrides?.coherenceScore ?? DEFAULT_BUDGET.coherenceScore,
+  };
+}
+
+// ─── CoherenceDetector ────────────────────────────────────────────────────
+
+/**
+ * Returns a detector that flags:
+ *   - loop   : last `loopDetectionWindow` tool calls have identical name + deep-equal args.
+ *   - stall  : `stepsWithoutTool >= stallThreshold` (assistant keeps answering
+ *              but never invokes a tool).
+ *
+ * Score: 1.0 if neither, 0.0 if both, 0.5 if exactly one.
+ */
+export function createCoherenceDetector(config?: {
+  loopDetectionWindow?: number;
+  stallThreshold?: number;
+}): CoherenceDetector {
+  const window = config?.loopDetectionWindow ?? 3;
+  const stallThreshold = config?.stallThreshold ?? 5;
+
+  if (window < 2) {
+    throw new Error(
+      "createCoherenceDetector: loopDetectionWindow must be >= 2",
+    );
+  }
+  if (stallThreshold < 1) {
+    throw new Error("createCoherenceDetector: stallThreshold must be >= 1");
+  }
+
+  return {
+    check(recentToolCalls, stepsWithoutTool) {
+      const isLoop = detectLoop(recentToolCalls, window);
+      const isStall = stepsWithoutTool >= stallThreshold;
+      let score = 1;
+      if (isLoop) score -= 0.5;
+      if (isStall) score -= 0.5;
+      if (score < 0) score = 0;
+      return { isLoop, isStall, score };
+    },
+  };
+}
+
+function detectLoop(
+  calls: Array<{ name: string; args: unknown }>,
+  windowSize: number,
+): boolean {
+  if (calls.length < windowSize) return false;
+  const window = calls.slice(-windowSize);
+  const first = window[0];
+  if (!first) return false;
+  const firstKey = `${first.name}:${stableStringify(first.args)}`;
+  for (let i = 1; i < window.length; i++) {
+    const c = window[i];
+    if (!c) return false;
+    if (`${c.name}:${stableStringify(c.args)}` !== firstKey) return false;
+  }
+  return true;
+}
+
+/** JSON.stringify with sorted keys so {a:1,b:2} and {b:2,a:1} compare equal. */
+function stableStringify(v: unknown): string {
+  const seen = new WeakSet<object>();
+  const walk = (val: unknown): unknown => {
+    if (val === null || typeof val !== "object") return val;
+    if (seen.has(val as object)) return "[circular]";
+    seen.add(val as object);
+    if (Array.isArray(val)) return val.map(walk);
+    const obj = val as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    const out: Record<string, unknown> = {};
+    for (const k of keys) out[k] = walk(obj[k]);
+    return out;
+  };
+  try {
+    return JSON.stringify(walk(v));
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+// ─── compactToolLog ───────────────────────────────────────────────────────
+
+/**
+ * Keeps the first `keepFirst` and last `keepLast` messages; replaces the
+ * middle with a single system note describing how many steps were omitted.
+ *
+ * Guarantees:
+ *   - Returns a NEW array (does not mutate input).
+ *   - If log is already short enough, returns a copy unchanged.
+ *   - Never drops the very first user message (prompt context).
+ */
+export function compactToolLog(
+  log: LogMessage[],
+  opts?: { keepFirst?: number; keepLast?: number },
+): LogMessage[] {
+  const keepFirst = opts?.keepFirst ?? 2;
+  const keepLast = opts?.keepLast ?? 4;
+
+  if (keepFirst < 0 || keepLast < 0) {
+    throw new Error("compactToolLog: keepFirst and keepLast must be >= 0");
+  }
+
+  if (log.length <= keepFirst + keepLast) {
+    return log.slice();
+  }
+
+  const head = log.slice(0, keepFirst);
+  const tail = log.slice(log.length - keepLast);
+  const omitted = log.length - keepFirst - keepLast;
+
+  const summary: LogMessage = {
+    role: "system",
+    content: `… [${omitted} tool steps omitted for brevity]`,
+  };
+
+  return [...head, summary, ...tail];
+}
+
+// ─── emergencyContextSummary ──────────────────────────────────────────────
+
+/**
+ * Called when contextWindow.currentTokens > 0.9 * maxTokens. Uses the
+ * caller-provided `summarize` function (typically the provider-router's
+ * complete() wired as a one-shot prompt) to produce a short recap that
+ * replaces the bulk of the log.
+ *
+ * Recursion guard: `opts.recursion` MUST be false. If callers ever wire
+ * this into itself (e.g. summarize triggers another context summary), it
+ * throws — we refuse to recurse because the error path must be bounded.
+ */
+export async function emergencyContextSummary(
+  log: LogMessage[],
+  summarize: (prompt: string) => Promise<string>,
+  opts: { recursion: false },
+): Promise<string> {
+  if (opts.recursion !== false) {
+    throw new Error(
+      "emergencyContextSummary: recursion guard hit — opts.recursion must be false",
+    );
+  }
+
+  const transcript = log
+    .map((m) => `[${m.role}${m.toolName ? `:${m.toolName}` : ""}] ${m.content}`)
+    .join("\n");
+
+  const prompt = [
+    "You are compressing an agent conversation to save context tokens.",
+    "Summarize the key facts, decisions, tool outputs and pending work in ≤ 300 words.",
+    "Preserve anything an agent would need to continue the task.",
+    "",
+    "Transcript:",
+    transcript,
+  ].join("\n");
+
+  return summarize(prompt);
+}

package/src/budget/index.ts

@@ -0,0 +1,11 @@
+export {
+  createBudgetState,
+  createCoherenceDetector,
+  compactToolLog,
+  emergencyContextSummary,
+} from "./budget-state.js";
+export type {
+  AgentBudgetState,
+  CoherenceDetector,
+  LogMessage,
+} from "./budget-state.js";

package/src/clients/agents.ts

@@ -0,0 +1,140 @@
+/**
+ * AgentsClient — REST client for /api/agents endpoints.
+ *
+ * Wraps:
+ *   POST /api/agents/execute  → AgentsClient.execute()
+ *   GET  /api/agents          → AgentsClient.listRegistry()
+ *
+ * Authentication: Bearer token injected via getToken() on every request.
+ * Timeout: 30s for execute (agent calls can be slow), 10s for reads.
+ *
+ * Sprint: command-center:sprint-524:quick-9
+ */
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface AgentExecuteInput {
+  agentId: string;
+  taskType: string;
+  description: string;
+  archiveToBrain?: boolean;
+}
+
+export interface AgentExecuteResult {
+  runId: string;
+  runUrl: string;
+  status: string;
+}
+
+export interface AgentRegistryEntry {
+  agentId: string;
+  type: string;
+  status: string;
+}
+
+export interface AgentsClient {
+  execute(input: AgentExecuteInput): Promise<AgentExecuteResult>;
+  listRegistry(): Promise<{ agents: AgentRegistryEntry[] }>;
+}
+
+export interface AgentsClientOptions {
+  baseUrl: string;
+  getToken: () => Promise<string>;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function buildHeaders(
+  getToken: () => Promise<string>,
+): Promise<Record<string, string>> {
+  const token = await getToken();
+  return {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${token}`,
+  };
+}
+
+/**
+ * Parse the backend /api/agents/execute response into AgentExecuteResult.
+ *
+ * The backend execute endpoint is synchronous and does not assign a run UUID today.
+ * We synthesise a deterministic runId from a timestamp + random suffix so the
+ * caller always gets a stable reference for UI links.
+ */
+function parseExecuteResponse(
+  raw: Record<string, unknown>,
+  base: string,
+): AgentExecuteResult {
+  const runId =
+    typeof raw.runId === "string"
+      ? raw.runId
+      : `exec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const runUrl = `${base}/runs/${runId}`;
+  const status =
+    typeof raw.status === "string"
+      ? raw.status
+      : raw.error !== undefined
+        ? "failed"
+        : "completed";
+  return { runId, runUrl, status };
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createAgentsClient(opts: AgentsClientOptions): AgentsClient {
+  const base = opts.baseUrl.replace(/\/$/, "");
+
+  return {
+    async execute(input: AgentExecuteInput): Promise<AgentExecuteResult> {
+      const headers = await buildHeaders(opts.getToken);
+
+      const res = await fetch(`${base}/api/agents/execute`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          agentType: input.agentId,
+          taskType: input.taskType,
+          description: input.description,
+          archive: input.archiveToBrain ?? false,
+        }),
+        signal: AbortSignal.timeout(30_000),
+      });
+
+      if (!res.ok) {
+        const body = await res.text().catch(() => String(res.status));
+        throw new Error(`AgentsClient.execute failed (${res.status}): ${body}`);
+      }
+
+      const raw = (await res.json()) as Record<string, unknown>;
+      return parseExecuteResponse(raw, base);
+    },
+
+    async listRegistry(): Promise<{ agents: AgentRegistryEntry[] }> {
+      const headers = await buildHeaders(opts.getToken);
+
+      const res = await fetch(`${base}/api/agents`, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!res.ok) {
+        const body = await res.text().catch(() => String(res.status));
+        throw new Error(
+          `AgentsClient.listRegistry failed (${res.status}): ${body}`,
+        );
+      }
+
+      const raw = (await res.json()) as {
+        agents?: Array<{ type?: string; displayName?: string }>;
+      };
+      const agents: AgentRegistryEntry[] = (raw.agents ?? []).map((a) => ({
+        agentId: typeof a.type === "string" ? a.type : "unknown",
+        type: typeof a.type === "string" ? a.type : "unknown",
+        status: "active",
+      }));
+
+      return { agents };
+    },
+  };
+}

package/src/clients/index.ts

@@ -0,0 +1,6 @@
+/**
+ * REST clients barrel — SDK v0.8.2 (sprint-524:quick-9)
+ */
+export * from "./agents.js";
+export * from "./pipelines.js";
+export * from "./messaging-adapters.js";

package/src/clients/messaging-adapters.ts

@@ -0,0 +1,173 @@
+/**
+ * Messaging adapters — thin client-side wrappers for Telegram and Slack slash commands.
+ *
+ * Parses /run, /pipeline, /status commands and dispatches to AgentsClient or
+ * PipelinesClient. Mirrors the server-side shape of agent-trigger-shared.ts
+ * (sprint-524:quick-3) but calls REST clients instead of direct DB/execute().
+ *
+ * Supported commands:
+ *   /run <agentId> <task description…>   → AgentsClient.execute()
+ *   /pipeline <name>                     → PipelinesClient.run()
+ *   /status <runId>                      → PipelinesClient.status()
+ *
+ * Sprint: command-center:sprint-524:quick-9
+ */
+
+import type { AgentsClient } from "./agents.js";
+import type { PipelinesClient } from "./pipelines.js";
+
+// ─── Context types ────────────────────────────────────────────────────────────
+
+export interface TelegramTriggerContext {
+  chatId: string;
+  from?: { username?: string };
+}
+
+export interface SlackTriggerContext {
+  userId: string;
+  channelId: string;
+}
+
+// ─── Result type ──────────────────────────────────────────────────────────────
+
+export interface MessagingTriggerResult {
+  replyText: string;
+  runId?: string;
+}
+
+// ─── Command parser ───────────────────────────────────────────────────────────
+
+interface ParsedCommand {
+  verb: string;
+  args: string[];
+}
+
+function parseCommand(command: string, args: string[]): ParsedCommand {
+  // Normalise: strip leading slash if present (e.g. Telegram /run vs "run")
+  const verb = command.replace(/^\//, "").toLowerCase();
+  return { verb, args };
+}
+
+// ─── Shared dispatch ──────────────────────────────────────────────────────────
+
+async function dispatch(
+  agents: AgentsClient,
+  pipelines: PipelinesClient,
+  verb: string,
+  args: string[],
+): Promise<MessagingTriggerResult> {
+  switch (verb) {
+    case "run": {
+      if (args.length < 2) {
+        return {
+          replyText:
+            "Usage: /run <agentId> <task description>\nExample: /run ARCHITECT analyse auth flow",
+        };
+      }
+      const agentId = args[0];
+      const description = args.slice(1).join(" ");
+      const result = await agents.execute({
+        agentId,
+        taskType: "messaging-trigger",
+        description,
+        archiveToBrain: false,
+      });
+      return {
+        replyText: `Agent ${agentId} started. Status: ${result.status}\nTrack: ${result.runUrl}`,
+        runId: result.runId,
+      };
+    }
+
+    case "pipeline": {
+      if (args.length < 1) {
+        return {
+          replyText:
+            "Usage: /pipeline <name>\nExample: /pipeline daily-digest",
+        };
+      }
+      const name = args[0];
+      const result = await pipelines.run({ name });
+      return {
+        replyText: `Pipeline "${name}" queued. Run ID: ${result.runId}\nStatus: ${result.statusUrl}`,
+        runId: result.runId,
+      };
+    }
+
+    case "status": {
+      if (args.length < 1) {
+        return { replyText: "Usage: /status <runId>" };
+      }
+      const pipelineId = args[0];
+      const result = await pipelines.status(pipelineId);
+      return {
+        replyText: `Run ${pipelineId}: ${result.status} (${result.progress}%)`,
+        runId: pipelineId,
+      };
+    }
+
+    default: {
+      const known = ["/run", "/pipeline", "/status"].join(", ");
+      return {
+        replyText: `Unknown command: /${verb}\nAvailable: ${known}`,
+      };
+    }
+  }
+}
+
+// ─── Telegram adapter ─────────────────────────────────────────────────────────
+
+/**
+ * Handle a Telegram message command on behalf of a bound user.
+ *
+ * @param agents      - AgentsClient instance (already authenticated)
+ * @param pipelines   - PipelinesClient instance (already authenticated)
+ * @param ctx         - Telegram context (chatId, optional username)
+ * @param command     - Command verb, with or without leading "/" (e.g. "run" or "/run")
+ * @param args        - Remaining tokens after the command
+ */
+export async function triggerFromTelegram(
+  agents: AgentsClient,
+  pipelines: PipelinesClient,
+  ctx: TelegramTriggerContext,
+  command: string,
+  args: string[],
+): Promise<MessagingTriggerResult> {
+  const { verb, args: normalised } = parseCommand(command, args);
+  try {
+    return await dispatch(agents, pipelines, verb, normalised);
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      replyText: `Error (chat ${ctx.chatId}): ${msg}`,
+    };
+  }
+}
+
+// ─── Slack adapter ────────────────────────────────────────────────────────────
+
+/**
+ * Handle a Slack slash command on behalf of a bound user.
+ *
+ * @param agents      - AgentsClient instance (already authenticated)
+ * @param pipelines   - PipelinesClient instance (already authenticated)
+ * @param ctx         - Slack context (userId, channelId)
+ * @param command     - Command verb, with or without leading "/" (e.g. "run" or "/run")
+ * @param args        - Remaining tokens after the command
+ */
+export async function triggerFromSlack(
+  agents: AgentsClient,
+  pipelines: PipelinesClient,
+  ctx: SlackTriggerContext,
+  command: string,
+  args: string[],
+): Promise<MessagingTriggerResult> {
+  const { verb, args: normalised } = parseCommand(command, args);
+  try {
+    return await dispatch(agents, pipelines, verb, normalised);
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      replyText: `Error (user ${ctx.userId}): ${msg}`,
+    };
+  }
+}