@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/docs/identity.md

@@ -0,0 +1,193 @@
+# Agent Identity & Persona
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** CC v3.1 sprint-562 (Livrable E, 2026-05-14)
+
+An `AgentPersona` is a structured description of how an agent communicates — tone, formality, domain expertise, and response-shape preferences. The persona travels from Brain Tier 3 (semantic storage) through the CC server as a system-prompt prefix, and can be overridden locally via `~/.preste/persona.yaml`.
+
+## Quick start
+
+```typescript
+import {
+  buildPersonaPromptBlock,
+  mergePersona,
+  DEFAULT_PERSONA,
+  validatePersona,
+} from "@vauban-org/agent-sdk";
+import type { AgentPersona } from "@vauban-org/agent-sdk";
+
+const persona: AgentPersona = {
+  identity: {
+    name: "ARCHITECT",
+    role: "Senior Cairo/TypeScript engineer",
+    tone: "concise",
+    formality: "technical",
+    language: "en",
+  },
+  domain_expertise: ["Starknet", "TypeScript", "ZK proofs"],
+  communication: {
+    acknowledgment_style: "minimal",
+    explain_reasoning: "on_error",
+  },
+};
+
+const systemPrompt =
+  "You are an agent in the Vauban ecosystem." +
+  buildPersonaPromptBlock(persona);
+```
+
+The `buildPersonaPromptBlock` call appends the block only when actionable fields are present — it is safe to concatenate unconditionally.
+
+---
+
+## `AgentPersona` schema
+
+All fields are optional. Zod validation enforces the limits below; `PersonaSchema.parse(input)` throws on violation.
+
+```typescript
+interface AgentPersona {
+  identity?: {
+    name?: string;       // max 64 chars
+    role?: string;       // max 256 chars
+    tone?: "concise" | "detailed" | "pedagogical";
+    formality?: "casual" | "formal" | "technical";
+    language?: string;   // BCP 47, e.g. "en", "fr-FR"
+  };
+  traits?: string[];           // max 16 items, max 64 chars each
+  domain_expertise?: string[]; // max 32 items, max 128 chars each
+  communication?: {
+    max_response_length?: number;
+    use_analogies?: boolean;
+    explain_reasoning?: "always" | "on_error" | "never";
+    acknowledgment_style?: "minimal" | "detailed" | "none";
+  };
+}
+```
+
+`DEFAULT_PERSONA` is applied before any user-defined value:
+
+```typescript
+const DEFAULT_PERSONA: AgentPersona = {
+  identity: { tone: "concise", formality: "technical", language: "en" },
+  traits: [],
+  domain_expertise: [],
+  communication: { explain_reasoning: "on_error", acknowledgment_style: "minimal" },
+};
+```
+
+---
+
+## `buildPersonaPromptBlock(persona)`
+
+Converts an `AgentPersona` to a compact system-prompt block bounded by `--- persona ---` / `--- end persona ---` markers.
+
+```typescript
+import { buildPersonaPromptBlock } from "@vauban-org/agent-sdk";
+
+const block = buildPersonaPromptBlock({
+  identity: { name: "SCRIBE", tone: "pedagogical", formality: "formal" },
+  domain_expertise: ["technical writing", "API documentation"],
+  communication: { explain_reasoning: "always" },
+});
+
+// block ===
+// \n--- persona ---
+// You are SCRIBE.
+// Communication style: pedagogical, formal.
+// Domain expertise: technical writing, API documentation.
+// Always explain your reasoning step by step.
+// --- end persona ---
+```
+
+**Properties:**
+
+- Returns `""` when the persona has no actionable fields — safe for unconditional concatenation.
+- `language` field only emits an instruction when it differs from `"en"`.
+- Empty `traits` / `domain_expertise` arrays produce no output.
+- The leading `\n` ensures correct spacing when appended to an existing system prompt.
+
+---
+
+## Merge semantics
+
+`mergePersona(base, local)` applies `local` on top of `base` field-by-field. Brain Tier 3 is the base; `~/.preste/persona.yaml` is the local override.
+
+```typescript
+import { mergePersona, DEFAULT_PERSONA } from "@vauban-org/agent-sdk";
+
+const brainPersona: AgentPersona = {
+  identity: { name: "BUILDER", tone: "concise" },
+  domain_expertise: ["Cairo", "TypeScript"],
+};
+
+const localOverride: AgentPersona = {
+  identity: { tone: "detailed" },       // overrides tone only
+  domain_expertise: ["Rust"],           // REPLACES the array entirely
+};
+
+const resolved = mergePersona(
+  mergePersona(DEFAULT_PERSONA, brainPersona),
+  localOverride,
+);
+// resolved.identity.name === "BUILDER"  (from brainPersona)
+// resolved.identity.tone === "detailed" (from localOverride)
+// resolved.domain_expertise === ["Rust"] (array replaced, not extended)
+```
+
+!!! warning "Array replacement semantics"
+    `traits` and `domain_expertise` are **replaced**, not extended. If you want to extend the Brain-stored array, concatenate before calling `mergePersona`:
+    ```typescript
+    const extended = mergePersona(base, {
+      ...local,
+      domain_expertise: [...(base.domain_expertise ?? []), ...(local.domain_expertise ?? [])],
+    });
+    ```
+
+---
+
+## System-level injection (CC server)
+
+Set `CC_AGENT_PERSONA_JSON` on the CC server to inject the persona as a system message prefix for every agent call, without modifying agent code.
+
+**Generate the env value:**
+
+```bash
+echo '{"identity":{"name":"ARCHITECT","role":"Senior Cairo/TypeScript engineer","tone":"concise","formality":"technical"},"domain_expertise":["Starknet","TypeScript","ZK proofs"],"communication":{"acknowledgment_style":"minimal","explain_reasoning":"on_error"}}' | base64 -w0
+```
+
+```bash
+export CC_AGENT_PERSONA_JSON="<base64 output>"
+```
+
+The CC server decodes, validates via `PersonaSchema.parse`, and calls `buildPersonaPromptBlock` before prepending to each agent system message.
+
+---
+
+## CLI persona management
+
+The `preste persona` sub-command manages the local `~/.preste/persona.yaml` override file.
+
+```bash
+preste persona show                                         # display resolved persona (Brain + local merge)
+preste persona set --name ARCHITECT --role "..." --tone concise --formality technical
+preste persona export persona.yaml                          # write to YAML file
+preste persona import persona.yaml                          # load from YAML file (validates schema)
+preste persona reset                                        # delete ~/.preste/persona.yaml (revert to Brain-only)
+```
+
+`preste persona show` prints the fully-resolved persona (Brain base + local override + defaults) and the rendered `buildPersonaPromptBlock` output so you can inspect what the model will receive.
+
+---
+
+## Validation
+
+```typescript
+import { validatePersona } from "@vauban-org/agent-sdk";
+
+try {
+  const persona = validatePersona(untrustedInput);
+} catch (err) {
+  // ZodError — inspect err.issues for field-level messages
+}
+```
+
+`validatePersona` wraps `PersonaSchema.parse` and throws `ZodError` on invalid input. Call it at ingestion boundaries (e.g., when loading `~/.preste/persona.yaml` or deserializing from Brain).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vauban-org/agent-sdk",
-  "version": "0.17.4",
+  "version": "1.2.0",
   "description": "Vauban agent primitives: loop, budget, routing, HITL, permissions, tracking, durable execution",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,11 @@
       "import": "./dist/proof/index.js",
       "default": "./dist/proof/index.js"
     },
+    "./proof/cert-verify": {
+      "types": "./dist/proof/cert-verify.d.ts",
+      "import": "./dist/proof/cert-verify.js",
+      "default": "./dist/proof/cert-verify.js"
+    },
     "./outcomes": {
       "types": "./dist/outcomes/index.d.ts",
       "import": "./dist/outcomes/index.js",
@@ -75,6 +80,21 @@
       "types": "./dist/hitl/callback-handlers.d.ts",
       "import": "./dist/hitl/callback-handlers.js",
       "default": "./dist/hitl/callback-handlers.js"
+    },
+    "./economy": {
+      "types": "./dist/economy/index.d.ts",
+      "import": "./dist/economy/index.js",
+      "default": "./dist/economy/index.js"
+    },
+    "./skill-manifest": {
+      "types": "./dist/skill-manifest/index.d.ts",
+      "import": "./dist/skill-manifest/index.js",
+      "default": "./dist/skill-manifest/index.js"
+    },
+    "./skill-loop": {
+      "types": "./dist/skill-loop/index.d.ts",
+      "import": "./dist/skill-loop/index.js",
+      "default": "./dist/skill-loop/index.js"
     }
   },
   "files": [
@@ -107,6 +127,7 @@
     "api:extract": "api-extractor run --local --verbose",
     "api:check": "api-extractor run",
     "depcruise": "depcruise src",
+    "docs": "typedoc",
     "prepublishOnly": "pnpm build && pnpm test"
   },
   "dependencies": {

package/src/adapters/llm/anthropic-direct.ts

@@ -8,6 +8,8 @@
  */
 
 import Anthropic from "@anthropic-ai/sdk";
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
 import type {
   ChatRequest,
   ChatResponse,
@@ -16,6 +18,11 @@ import type {
   StreamDelta,
 } from "../../ports/llm-provider.js";
 
+const ADAPTER_TRACER = trace.getTracer(
+  "vauban-agent-sdk.llm.anthropic",
+  "0.1.0"
+);
+
 export interface AnthropicDirectAdapterConfig {
   apiKey: string;
   /** Default model to use when ChatRequest.model is not specified. */
@@ -70,6 +77,50 @@ export class AnthropicDirectAdapter implements LLMProviderPort {
   }
 
   async complete(req: ChatRequest): Promise<ChatResponse> {
+    return ADAPTER_TRACER.startActiveSpan(
+      "llm-provider.complete",
+      {
+        attributes: {
+          "gen_ai.system": "anthropic",
+          "gen_ai.request.model": req.model ?? this.defaultModel,
+          "gen_ai.request.message_count": req.messages.length,
+          "vauban.port.name": "llm-provider",
+          "vauban.port.impl": "AnthropicDirectAdapter",
+        },
+      },
+      async (span: Span): Promise<ChatResponse> => {
+        try {
+          const response: ChatResponse = await this._doComplete(req);
+          span.setAttributes({
+            "gen_ai.usage.input_tokens": response.usage.inputTokens,
+            "gen_ai.usage.output_tokens": response.usage.outputTokens,
+            "gen_ai.response.model": response.model,
+            "gen_ai.response.finish_reasons": [response.finishReason],
+          });
+          if (response.usage.costUsd !== undefined) {
+            span.setAttribute("gen_ai.usage.cost_usd", response.usage.costUsd);
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          return response;
+        } catch (_err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "span wrapper caught exception",
+          });
+          return {
+            content: "",
+            usage: { inputTokens: 0, outputTokens: 0 },
+            model: req.model ?? this.defaultModel,
+            finishReason: "error" as const,
+          };
+        } finally {
+          span.end();
+        }
+      }
+    );
+  }
+
+  private async _doComplete(req: ChatRequest): Promise<ChatResponse> {
     const model = req.model ?? this.defaultModel;
 
     // Extract system message (Anthropic API separates system from messages)

package/src/adapters/llm/cascade.ts

@@ -12,6 +12,8 @@
  * BYOM: no default model hardcoded.
  */
 
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
 import type {
   ChatRequest,
   ChatResponse,
@@ -19,6 +21,8 @@ import type {
   StreamDelta,
 } from "../../ports/llm-provider.js";
 
+const ADAPTER_TRACER = trace.getTracer("vauban-agent-sdk.llm.cascade", "0.1.0");
+
 const ALL_FAIL_RESPONSE: ChatResponse = {
   content: "",
   usage: { inputTokens: 0, outputTokens: 0 },
@@ -51,26 +55,67 @@ export class CascadeAdapter implements LLMProviderPort {
   }
 
   async complete(req: ChatRequest): Promise<ChatResponse> {
-    for (const provider of this.providers) {
-      if (req.abortSignal?.aborted) {
-        return { ...ALL_FAIL_RESPONSE };
-      }
-
-      let response: ChatResponse;
-      try {
-        response = await provider.complete(req);
-      } catch {
-        // Unexpected throw — treat as failure, try next
-        continue;
-      }
-
-      if (response.finishReason !== "error") {
-        return response;
+    return ADAPTER_TRACER.startActiveSpan(
+      "llm-provider.complete",
+      {
+        attributes: {
+          "gen_ai.system": "cascade",
+          "gen_ai.request.model": req.model ?? "cascade",
+          "gen_ai.request.message_count": req.messages.length,
+          "vauban.port.name": "llm-provider",
+          "vauban.port.impl": "CascadeAdapter",
+          "vauban.cascade.provider_count": this.providers.length,
+        },
+      },
+      async (span: Span) => {
+        try {
+          let attemptCount = 0;
+          for (const provider of this.providers) {
+            attemptCount++;
+            if (req.abortSignal?.aborted) {
+              span.setAttribute("vauban.cascade.attempts", attemptCount);
+              span.setStatus({ code: SpanStatusCode.OK });
+              return { ...ALL_FAIL_RESPONSE };
+            }
+
+            let response: ChatResponse;
+            try {
+              response = await provider.complete(req);
+            } catch {
+              // Unexpected throw — treat as failure, try next
+              continue;
+            }
+
+            if (response.finishReason !== "error") {
+              span.setAttribute("vauban.cascade.attempts", attemptCount);
+              span.setAttributes({
+                "gen_ai.usage.input_tokens": response.usage.inputTokens,
+                "gen_ai.usage.output_tokens": response.usage.outputTokens,
+                "gen_ai.response.model": response.model,
+                "gen_ai.response.finish_reasons": [response.finishReason],
+              });
+              span.setStatus({ code: SpanStatusCode.OK });
+              return response;
+            }
+            // finishReason === "error" → try next provider
+          }
+          span.setAttribute("vauban.cascade.attempts", attemptCount);
+          span.setAttribute("vauban.cascade.all_failed", true);
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "all providers failed",
+          });
+          return { ...ALL_FAIL_RESPONSE };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          span.setStatus({ code: SpanStatusCode.ERROR, message });
+          if (err instanceof Error) span.recordException(err);
+          return { ...ALL_FAIL_RESPONSE };
+        } finally {
+          span.end();
+        }
       }
-      // finishReason === "error" → try next provider
-    }
-
-    return { ...ALL_FAIL_RESPONSE };
+    );
   }
 
   async *stream(req: ChatRequest): AsyncIterable<StreamDelta> {

package/src/adapters/llm/litellm.ts

@@ -9,6 +9,8 @@
  * No model string is hardcoded at module scope.
  */
 
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
 import type {
   ChatRequest,
   ChatResponse,
@@ -17,6 +19,8 @@ import type {
   StreamDelta,
 } from "../../ports/llm-provider.js";
 
+const ADAPTER_TRACER = trace.getTracer("vauban-agent-sdk.llm.litellm", "0.1.0");
+
 export interface LiteLLMAdapterConfig {
   baseUrl: string;
   apiKey?: string;
@@ -103,6 +107,51 @@ export class LiteLLMAdapter implements LLMProviderPort {
   }
 
   async complete(req: ChatRequest): Promise<ChatResponse> {
+    return ADAPTER_TRACER.startActiveSpan(
+      "llm-provider.complete",
+      {
+        attributes: {
+          "gen_ai.system": "litellm",
+          "gen_ai.request.model": req.model ?? this.defaultModel,
+          "gen_ai.request.message_count": req.messages.length,
+          "vauban.port.name": "llm-provider",
+          "vauban.port.impl": "LiteLLMAdapter",
+        },
+      },
+      async (span: Span): Promise<ChatResponse> => {
+        try {
+          const response: ChatResponse = await this._doComplete(req);
+          span.setAttributes({
+            "gen_ai.usage.input_tokens": response.usage.inputTokens,
+            "gen_ai.usage.output_tokens": response.usage.outputTokens,
+            "gen_ai.response.model": response.model,
+            "gen_ai.response.finish_reasons": [response.finishReason],
+          });
+          if (response.usage.costUsd !== undefined) {
+            span.setAttribute("gen_ai.usage.cost_usd", response.usage.costUsd);
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          return response;
+        } catch (_err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "span wrapper caught exception",
+          });
+          return {
+            content: "",
+            usage: { inputTokens: 0, outputTokens: 0 },
+            model: req.model ?? this.defaultModel,
+            finishReason: "error" as const,
+          };
+        } finally {
+          span.end();
+        }
+      }
+    );
+  }
+
+  /** Internal completion logic — extracted from complete() for span instrumentation. */
+  private async _doComplete(req: ChatRequest): Promise<ChatResponse> {
     const model = req.model ?? this.defaultModel;
     const body = {
       model,

package/src/compute/difficulty-estimator.ts

@@ -0,0 +1,111 @@
+/**
+ * src/compute/difficulty-estimator.ts
+ *
+ * Deterministic task-difficulty classifier + strategy recommender.
+ *
+ * NOT an LLM call — pure feature extraction + rule-based classification.
+ * Routes input difficulty → recommended compute strategy.
+ *
+ * @experimental Public-experimental API per `contract-stability.md` (sprint-582).
+ */
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export type DifficultyClass = "simple" | "standard" | "complex" | "reasoning";
+
+export interface TaskFeatures {
+  /** Character count of input. */
+  inputLength: number;
+  /** Input contains "step", "then", or "first…then" pattern. */
+  hasMultipleSteps: boolean;
+  /** Input contains "why", "explain", "reason", "prove", "deduce". */
+  requiresReasoning: boolean;
+  /** Input contains "create", "generate", "design", "imagine". */
+  requiresCreativity: boolean;
+  /** Input contains digits or math operators. */
+  hasNumerics: boolean;
+  /** Input references multiple entities ("A and B", "compare"). */
+  hasCrossReference: boolean;
+  /** Length of optional context/system prompt. */
+  contextLength: number;
+}
+
+// ─── Regex patterns (case-insensitive, word-bounded where useful) ───────────
+
+const RE_STEPS = /\b(step|steps|then|first|next|finally)\b/i;
+const RE_REASONING =
+  /\b(why|explain|explains|reason|reasons|prove|proves|deduce|deduces|infer|justify)\b/i;
+const RE_CREATIVITY = /\b(create|generate|design|imagine|invent|compose)\b/i;
+const RE_NUMERICS = /[0-9]|[+\-*/^=]/;
+const RE_CROSS_REF = /\b(compare|and|versus|vs\.?|both)\b/i;
+
+// ─── Feature extraction ──────────────────────────────────────────────────────
+
+/**
+ * Extract task features from input + optional context.
+ * Deterministic, side-effect free.
+ */
+export function extractFeatures(input: string, context?: string): TaskFeatures {
+  const inputLength = input.length;
+  const contextLength = context?.length ?? 0;
+
+  return {
+    inputLength,
+    hasMultipleSteps: RE_STEPS.test(input),
+    requiresReasoning: RE_REASONING.test(input),
+    requiresCreativity: RE_CREATIVITY.test(input),
+    hasNumerics: RE_NUMERICS.test(input),
+    hasCrossReference: RE_CROSS_REF.test(input),
+    contextLength,
+  };
+}
+
+// ─── Difficulty classification ───────────────────────────────────────────────
+
+/**
+ * Classify difficulty from task features.
+ *
+ * Decision tree (most specific first):
+ *   - requiresReasoning → "reasoning"
+ *   - inputLength > 500 OR hasMultipleSteps OR requiresCreativity → "complex"
+ *   - inputLength in [100, 500] OR hasNumerics → "standard"
+ *   - else → "simple"
+ */
+export function estimateDifficulty(features: TaskFeatures): DifficultyClass {
+  if (features.requiresReasoning) return "reasoning";
+  if (features.inputLength > 500 || features.hasMultipleSteps || features.requiresCreativity) {
+    return "complex";
+  }
+  if (features.inputLength >= 100 || features.hasNumerics) {
+    return "standard";
+  }
+  return "simple";
+}
+
+// ─── Strategy recommendation ─────────────────────────────────────────────────
+
+/**
+ * Recommend a compute strategy for a given difficulty class.
+ *
+ * Map (per Sprint A bench results + Sprint-582 spec):
+ *   simple     → single-shot
+ *   standard   → bon-mav
+ *   complex    → tree-of-thoughts
+ *   reasoning  → mixture-of-agents
+ */
+export function recommendStrategy(difficulty: DifficultyClass): string {
+  switch (difficulty) {
+    case "simple":
+      return "single-shot";
+    case "standard":
+      return "bon-mav";
+    case "complex":
+      return "tree-of-thoughts";
+    case "reasoning":
+      return "mixture-of-agents";
+    default: {
+      const _exhaustive: never = difficulty;
+      throw new Error(`recommendStrategy: unknown difficulty "${String(_exhaustive)}"`);
+    }
+  }
+}