@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/src/events/catalogue.ts

@@ -6,6 +6,7 @@ import { AgentHitlRequestedV1 } from "./schemas/agent.hitl_requested.v1.js";
 import { AgentHitlResolvedV1 } from "./schemas/agent.hitl_resolved.v1.js";
 import { IncidentSloBurnV1 } from "./schemas/incident.slo_burn.v1.js";
 import { IncidentDetectedV1 } from "./schemas/incident.detected.v1.js";
+import { ForgeInboxReplyClassifiedV1 } from "./schemas/forge.inbox.reply_classified.v1.js";
 import { ForgeLeadQualifiedV1 } from "./schemas/forge.lead.qualified.v1.js";
 import { ForgeOutreachSentV1 } from "./schemas/forge.outreach.sent.v1.js";
 import { ForgePolicyTriggeredV1 } from "./schemas/forge.policy.triggered.v1.js";
@@ -13,11 +14,19 @@ import { VaubanVaultRebalanceProposedV1 } from "./schemas/vauban.vault.rebalance
 import { VaubanVaultRebalancedV1 } from "./schemas/vauban.vault.rebalanced.v1.js";
 import { GlacisIdentityVerifiedV1 } from "./schemas/glacis.identity.verified.v1.js";
 import { CitadelSprintClosedV1 } from "./schemas/citadel.sprint.closed.v1.js";
+import { CitadelSprintAnalyzedV1 } from "./schemas/citadel.sprint.analyzed.v1.js";
 import { BrainSkillExtractedV1 } from "./schemas/brain.skill.extracted.v1.js";
 import { CcCostRecordedV1 } from "./schemas/cc.cost.recorded.v1.js";
 import { CcCostAnomalyDetectedV1 } from "./schemas/cc.cost.anomaly_detected.v1.js";
 import { TenantProvisionedV1 } from "./schemas/tenant.provisioned.v1.js";
 import { TenantBudgetExceededV1 } from "./schemas/tenant.budget.exceeded.v1.js";
+import { VaubanVaultAnalyzedV1 } from "./schemas/vauban.vault.analyzed.v1.js";
+import { VaubanGoalCheckedV1 } from "./schemas/vauban.goal.checked.v1.js";
+import { VaubanRebalancingCheckedV1 } from "./schemas/vauban.rebalancing.checked.v1.js";
+import { VaubanTaxCheckedV1 } from "./schemas/vauban.tax.checked.v1.js";
+import { VaubanVaultCompoundedV1 } from "./schemas/vauban.vault.compounded.v1.js";
+import { VaubanFinanceForecastGeneratedV1 } from "./schemas/vauban-finance.forecast.generated.v1.js";
+import { VaubanFinanceTradeExecutedV1 } from "./schemas/vauban-finance.trade.executed.v1.js";
 
 export const EventSchemas = {
   "agent.started": AgentStartedV1,
@@ -27,13 +36,22 @@ export const EventSchemas = {
   "agent.hitl_resolved": AgentHitlResolvedV1,
   "incident.slo_burn": IncidentSloBurnV1,
   "incident.detected": IncidentDetectedV1,
+  "forge.inbox.reply_classified": ForgeInboxReplyClassifiedV1,
   "forge.lead.qualified": ForgeLeadQualifiedV1,
   "forge.outreach.sent": ForgeOutreachSentV1,
   "forge.policy.triggered": ForgePolicyTriggeredV1,
   "vauban.vault.rebalance_proposed": VaubanVaultRebalanceProposedV1,
   "vauban.vault.rebalanced": VaubanVaultRebalancedV1,
+  "vauban.vault.analyzed": VaubanVaultAnalyzedV1,
+  "vauban.goal.checked": VaubanGoalCheckedV1,
+  "vauban.rebalancing.checked": VaubanRebalancingCheckedV1,
+  "vauban.tax.checked": VaubanTaxCheckedV1,
+  "vauban.vault.compounded": VaubanVaultCompoundedV1,
+  "vauban-finance.forecast.generated": VaubanFinanceForecastGeneratedV1,
+  "vauban-finance.trade.executed": VaubanFinanceTradeExecutedV1,
   "glacis.identity.verified": GlacisIdentityVerifiedV1,
   "citadel.sprint.closed": CitadelSprintClosedV1,
+  "citadel.sprint.analyzed": CitadelSprintAnalyzedV1,
   "brain.skill.extracted": BrainSkillExtractedV1,
   "cc.cost.recorded": CcCostRecordedV1,
   "cc.cost.anomaly_detected": CcCostAnomalyDetectedV1,
@@ -55,6 +73,10 @@ export type EventType =
     }
   | { type: "incident.slo_burn"; payload: z.infer<typeof IncidentSloBurnV1> }
   | { type: "incident.detected"; payload: z.infer<typeof IncidentDetectedV1> }
+  | {
+      type: "forge.inbox.reply_classified";
+      payload: z.infer<typeof ForgeInboxReplyClassifiedV1>;
+    }
   | {
       type: "forge.lead.qualified";
       payload: z.infer<typeof ForgeLeadQualifiedV1>;
@@ -83,6 +105,10 @@ export type EventType =
       type: "citadel.sprint.closed";
       payload: z.infer<typeof CitadelSprintClosedV1>;
     }
+  | {
+      type: "citadel.sprint.analyzed";
+      payload: z.infer<typeof CitadelSprintAnalyzedV1>;
+    }
   | {
       type: "brain.skill.extracted";
       payload: z.infer<typeof BrainSkillExtractedV1>;
@@ -96,6 +122,34 @@ export type EventType =
   | {
       type: "tenant.budget.exceeded";
       payload: z.infer<typeof TenantBudgetExceededV1>;
+    }
+  | {
+      type: "vauban.vault.analyzed";
+      payload: z.infer<typeof VaubanVaultAnalyzedV1>;
+    }
+  | {
+      type: "vauban.goal.checked";
+      payload: z.infer<typeof VaubanGoalCheckedV1>;
+    }
+  | {
+      type: "vauban.rebalancing.checked";
+      payload: z.infer<typeof VaubanRebalancingCheckedV1>;
+    }
+  | {
+      type: "vauban.tax.checked";
+      payload: z.infer<typeof VaubanTaxCheckedV1>;
+    }
+  | {
+      type: "vauban.vault.compounded";
+      payload: z.infer<typeof VaubanVaultCompoundedV1>;
+    }
+  | {
+      type: "vauban-finance.forecast.generated";
+      payload: z.infer<typeof VaubanFinanceForecastGeneratedV1>;
+    }
+  | {
+      type: "vauban-finance.trade.executed";
+      payload: z.infer<typeof VaubanFinanceTradeExecutedV1>;
     };
 
 export type EventTypeName = keyof typeof EventSchemas;

package/src/events/index.ts

@@ -6,6 +6,7 @@ export { AgentHitlRequestedV1 } from "./schemas/agent.hitl_requested.v1.js";
 export { AgentHitlResolvedV1 } from "./schemas/agent.hitl_resolved.v1.js";
 export { IncidentSloBurnV1 } from "./schemas/incident.slo_burn.v1.js";
 export { IncidentDetectedV1 } from "./schemas/incident.detected.v1.js";
+export { ForgeInboxReplyClassifiedV1 } from "./schemas/forge.inbox.reply_classified.v1.js";
 export { ForgeLeadQualifiedV1 } from "./schemas/forge.lead.qualified.v1.js";
 export { ForgeOutreachSentV1 } from "./schemas/forge.outreach.sent.v1.js";
 export { ForgePolicyTriggeredV1 } from "./schemas/forge.policy.triggered.v1.js";
@@ -13,8 +14,16 @@ export { VaubanVaultRebalanceProposedV1 } from "./schemas/vauban.vault.rebalance
 export { VaubanVaultRebalancedV1 } from "./schemas/vauban.vault.rebalanced.v1.js";
 export { GlacisIdentityVerifiedV1 } from "./schemas/glacis.identity.verified.v1.js";
 export { CitadelSprintClosedV1 } from "./schemas/citadel.sprint.closed.v1.js";
+export { CitadelSprintAnalyzedV1 } from "./schemas/citadel.sprint.analyzed.v1.js";
 export { BrainSkillExtractedV1 } from "./schemas/brain.skill.extracted.v1.js";
 export { CcCostRecordedV1 } from "./schemas/cc.cost.recorded.v1.js";
 export { CcCostAnomalyDetectedV1 } from "./schemas/cc.cost.anomaly_detected.v1.js";
 export { TenantProvisionedV1 } from "./schemas/tenant.provisioned.v1.js";
 export { TenantBudgetExceededV1 } from "./schemas/tenant.budget.exceeded.v1.js";
+export { VaubanVaultAnalyzedV1 } from "./schemas/vauban.vault.analyzed.v1.js";
+export { VaubanGoalCheckedV1 } from "./schemas/vauban.goal.checked.v1.js";
+export { VaubanRebalancingCheckedV1 } from "./schemas/vauban.rebalancing.checked.v1.js";
+export { VaubanTaxCheckedV1 } from "./schemas/vauban.tax.checked.v1.js";
+export { VaubanVaultCompoundedV1 } from "./schemas/vauban.vault.compounded.v1.js";
+export { VaubanFinanceForecastGeneratedV1 } from "./schemas/vauban-finance.forecast.generated.v1.js";
+export { VaubanFinanceTradeExecutedV1 } from "./schemas/vauban-finance.trade.executed.v1.js";

package/src/events/schemas/citadel.sprint.analyzed.v1.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+const SprintInsightV1 = z
+  .object({
+    type: z.string(),
+    severity: z.enum(["info", "warning", "error", "critical"]),
+    metric: z.string(),
+    description: z.string(),
+  })
+  .strict();
+
+export const CitadelSprintAnalyzedV1 = z
+  .object({
+    sprintId: z.string(),
+    healthScore: z.number().int().min(0).max(100),
+    overallSeverity: z.enum(["info", "warning", "error", "critical"]),
+    insights: z.array(SprintInsightV1),
+    blockers: z.array(z.string()),
+    recommendations: z.array(z.string()),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/forge.inbox.reply_classified.v1.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+export const ForgeInboxReplyClassifiedV1 = z
+  .object({
+    uid: z.string(),
+    from: z.string(),
+    subject: z.string(),
+    type: z.enum(["INTERESTED", "NOT_INTERESTED", "BOUNCE", "SPAM", "OTHER"]),
+    priority: z.enum(["HIGH", "MEDIUM", "LOW"]),
+    signal: z.string(),
+    nextAction: z.string(),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/vauban-finance.forecast.generated.v1.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const VaubanFinanceForecastGeneratedV1 = z
+  .object({
+    scenarioId: z.string(),
+    successRate: z.number().min(0).max(1),
+    paramVelocity: z.number(),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/vauban-finance.trade.executed.v1.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+export const VaubanFinanceTradeExecutedV1 = z
+  .object({
+    symbol: z.string(),
+    direction: z.enum(["long", "short", "hold"]),
+    quantity: z.number(),
+    conviction: z.number().min(0).max(1),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/vauban.goal.checked.v1.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const VaubanGoalCheckedV1 = z
+  .object({
+    goalId: z.string(),
+    successRate: z.number(),
+    alertLevel: z.enum(["none", "warning", "critical"]),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/vauban.rebalancing.checked.v1.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const VaubanRebalancingCheckedV1 = z
+  .object({
+    portfolioId: z.string(),
+    maxDrift: z.number(),
+    alertLevel: z.enum(["none", "warning", "critical"]),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/vauban.tax.checked.v1.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const VaubanTaxCheckedV1 = z
+  .object({
+    userId: z.string(),
+    rulesTriggered: z.array(z.string()),
+    alertLevel: z.enum(["none", "warning", "critical"]),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/vauban.vault.analyzed.v1.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const VaubanVaultAnalyzedV1 = z
+  .object({
+    vaultId: z.string(),
+    tvlUsd: z.number(),
+    anomalies: z.array(
+      z.object({
+        type: z.string(),
+        severity: z.enum(["info", "warning", "error", "critical"]),
+        metric: z.string(),
+        current: z.union([z.string(), z.number()]),
+        expected: z.union([z.string(), z.number()]),
+        description: z.string(),
+      })
+    ),
+    overallSeverity: z.enum(["info", "warning", "error", "critical"]),
+    timestamp: z.string(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/events/schemas/vauban.vault.compounded.v1.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+export const VaubanVaultCompoundedV1 = z
+  .object({
+    vaultId: z.string(),
+    compoundedAt: z.string(),
+    rewardsUsd: z.number(),
+    caller: z.string(),
+    txHash: z.string().optional(),
+    schemaVersion: z.string(),
+  })
+  .strict();

package/src/identity/agent-persona.ts

@@ -0,0 +1,203 @@
+/**
+ * AgentPersona — load, save, and resolve a per-agent persona.
+ *
+ * Pipeline:
+ *   1. Resolve persona for agent X
+ *   2. base = DEFAULT_PERSONA
+ *   3. brain = loadFromBrain(X) (Tier 3 semantic memory query)
+ *   4. local = loadFromFile(`.cc/persona.yaml`) — optional
+ *   5. effective = merge(base, brain, local)
+ *
+ * Brain entries use category `agent-persona`, tags `["persona", agentId]`.
+ * The latest entry per agent wins (Brain query returns entries sorted by
+ * recency).
+ *
+ * @see ./persona-schema.ts
+ * @public
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type { SemanticMemoryPort } from "../ports/brain.js";
+import {
+  DEFAULT_PERSONA,
+  mergePersona,
+  PersonaSchema,
+  validatePersona,
+  type AgentPersona,
+} from "./persona-schema.js";
+
+export const PERSONA_BRAIN_CATEGORY = "agent-persona";
+
+/** Tags used to query/archive a persona for a given agent. */
+export function personaTags(agentId: string): string[] {
+  return ["persona", agentId];
+}
+
+// ─── Brain layer ────────────────────────────────────────────────────────────
+
+/**
+ * Save (archive) a persona for an agent in Brain Tier 3 (semantic).
+ *
+ * The persona is serialized as JSON in the `content` field — keep this
+ * structured so future queries can parse it deterministically. Tags include
+ * the agent id so per-agent retrieval is precise.
+ *
+ * Returns the archived entry id, or null when the brain port returns null
+ * (e.g. replay mode, no brain configured).
+ */
+export async function savePersonaToBrain(
+  brain: SemanticMemoryPort,
+  agentId: string,
+  persona: AgentPersona
+): Promise<string | null> {
+  validatePersona(persona);
+  // Wrap the JSON body with a discoverable header line — FTS-backed Brain
+  // backends use the query string as a keyword filter, so the content MUST
+  // contain the literal "persona" + agent id for `query("persona ...")` hits.
+  const content = `persona for agent ${agentId}\n${JSON.stringify(persona)}`;
+  const entry = await brain.archive({
+    content,
+    content_type: "persona",
+    category: PERSONA_BRAIN_CATEGORY,
+    tags: personaTags(agentId),
+    metadata: { agent_id: agentId, schema_version: 1 },
+  });
+  return entry?.id ?? null;
+}
+
+/**
+ * Extract the JSON body from a persona Brain entry (strips the header line).
+ * Returns null if the content doesn't follow the wrapper format.
+ */
+function extractPersonaJson(content: string): string | null {
+  const nl = content.indexOf("\n");
+  if (nl === -1) {
+    // Backward-compat: legacy entries stored raw JSON.
+    return content;
+  }
+  return content.slice(nl + 1);
+}
+
+/**
+ * Query Brain for the latest persona for an agent.
+ *
+ * Returns the parsed persona or `null` if no entry is found (or if the
+ * latest entry's content does not parse).
+ */
+export async function loadPersonaFromBrain(
+  brain: SemanticMemoryPort,
+  agentId: string
+): Promise<AgentPersona | null> {
+  const results = await brain.query("persona", {
+    category: PERSONA_BRAIN_CATEGORY,
+    tags: personaTags(agentId),
+    limit: 5,
+  });
+  if (results.length === 0) return null;
+  // Prefer the most recent entry by created_at if available.
+  const sorted = [...results].sort((a, b) => {
+    const ta = a.created_at ? Date.parse(a.created_at) : 0;
+    const tb = b.created_at ? Date.parse(b.created_at) : 0;
+    return tb - ta;
+  });
+  for (const entry of sorted) {
+    const json = extractPersonaJson(entry.content);
+    if (!json) continue;
+    try {
+      const parsed = JSON.parse(json) as unknown;
+      const validated = PersonaSchema.safeParse(parsed);
+      if (validated.success) return validated.data;
+    } catch {
+      // skip malformed entry, try next
+    }
+  }
+  return null;
+}
+
+// ─── File layer ─────────────────────────────────────────────────────────────
+
+/**
+ * Load a persona from a YAML file. Returns null if the file is missing or
+ * the content does not validate. Throws only on filesystem errors other
+ * than ENOENT.
+ */
+export async function loadPersonaFromFile(
+  path: string
+): Promise<AgentPersona | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    throw err;
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch {
+    return null;
+  }
+  const result = PersonaSchema.safeParse(parsed);
+  return result.success ? result.data : null;
+}
+
+/**
+ * Persist a persona to a YAML file (overwrites). Validates first.
+ */
+export async function savePersonaToFile(
+  path: string,
+  persona: AgentPersona
+): Promise<void> {
+  const validated = validatePersona(persona);
+  const yaml = stringifyYaml(validated, { indent: 2 });
+  await writeFile(path, yaml, "utf-8");
+}
+
+// ─── Resolution ─────────────────────────────────────────────────────────────
+
+export interface ResolvePersonaOptions {
+  agentId: string;
+  brain?: SemanticMemoryPort;
+  localPath?: string;
+}
+
+export interface ResolvedPersona {
+  effective: AgentPersona;
+  /** Layers actually applied, in order (latest wins). */
+  layers: Array<"defaults" | "brain" | "local">;
+}
+
+/**
+ * Resolve the effective persona for an agent.
+ *
+ * Composition order (each layer overrides the previous):
+ *   1. DEFAULT_PERSONA
+ *   2. Brain entry (Tier 3 semantic, optional)
+ *   3. Local `.cc/persona.yaml` (optional)
+ *
+ * The returned `layers` array documents which sources contributed, useful
+ * for diagnostics (e.g. `cc persona show --explain`).
+ */
+export async function resolvePersona(
+  opts: ResolvePersonaOptions
+): Promise<ResolvedPersona> {
+  const layers: ResolvedPersona["layers"] = ["defaults"];
+  let effective: AgentPersona = DEFAULT_PERSONA;
+  if (opts.brain) {
+    const fromBrain = await loadPersonaFromBrain(opts.brain, opts.agentId);
+    if (fromBrain) {
+      effective = mergePersona(effective, fromBrain);
+      layers.push("brain");
+    }
+  }
+  if (opts.localPath) {
+    const fromFile = await loadPersonaFromFile(opts.localPath);
+    if (fromFile) {
+      effective = mergePersona(effective, fromFile);
+      layers.push("local");
+    }
+  }
+  return { effective, layers };
+}

package/src/identity/persona-prompt.ts

@@ -0,0 +1,84 @@
+/**
+ * buildPersonaPromptBlock — converts an AgentPersona into a system-prompt block.
+ *
+ * The output is a compact, model-neutral instruction block that can be prepended
+ * to any system prompt. It is intentionally terse — LLMs handle short, directive
+ * blocks better than verbose persona descriptions.
+ *
+ * Format contract:
+ *   - Starts with a blank line so callers can safely concatenate to an existing
+ *     system prompt with `${base}\n${buildPersonaPromptBlock(persona)}`.
+ *   - Empty fields are omitted — the function never emits empty bullet points.
+ *   - The block is bounded by `--- persona ---` / `--- end persona ---` markers
+ *     for easy parsing / stripping in tests and audits.
+ *
+ * @public
+ */
+
+import type { AgentPersona } from "./persona-schema.js";
+
+/**
+ * Build a system-prompt instruction block from a resolved `AgentPersona`.
+ *
+ * Returns an empty string if the persona has no actionable fields, so
+ * callers can unconditionally concatenate without emitting noise.
+ */
+export function buildPersonaPromptBlock(persona: AgentPersona): string {
+  const lines: string[] = [];
+
+  const { identity, traits, domain_expertise, communication } = persona;
+
+  if (identity?.name) {
+    lines.push(`You are ${identity.name}.`);
+  }
+  if (identity?.role) {
+    lines.push(`Role: ${identity.role}.`);
+  }
+
+  const styleLines: string[] = [];
+  if (identity?.tone) styleLines.push(identity.tone);
+  if (identity?.formality) styleLines.push(identity.formality);
+  if (styleLines.length) {
+    lines.push(`Communication style: ${styleLines.join(", ")}.`);
+  }
+
+  if (identity?.language && identity.language !== "en") {
+    lines.push(`Respond in ${identity.language}.`);
+  }
+
+  if (traits && traits.length > 0) {
+    lines.push(`Traits: ${traits.join(", ")}.`);
+  }
+
+  if (domain_expertise && domain_expertise.length > 0) {
+    lines.push(`Domain expertise: ${domain_expertise.join(", ")}.`);
+  }
+
+  if (communication?.max_response_length) {
+    lines.push(
+      `Keep responses under ${communication.max_response_length} characters.`
+    );
+  }
+
+  if (communication?.explain_reasoning === "always") {
+    lines.push("Always explain your reasoning step by step.");
+  } else if (communication?.explain_reasoning === "never") {
+    lines.push("Do not explain your reasoning. Emit results only.");
+  }
+
+  if (communication?.acknowledgment_style === "none") {
+    lines.push(
+      'Do not acknowledge the task. Skip preamble like "Sure," or "I will".'
+    );
+  } else if (communication?.acknowledgment_style === "minimal") {
+    lines.push("Skip task acknowledgment preamble. Go directly to output.");
+  }
+
+  if (communication?.use_analogies === false) {
+    lines.push("Do not use analogies.");
+  }
+
+  if (lines.length === 0) return "";
+
+  return `\n--- persona ---\n${lines.join("\n")}\n--- end persona ---`;
+}