@vauban-org/agent-sdk 0.17.1 → 0.17.2

package/src/events/catalogue.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { AgentStartedV1 } from "./schemas/agent.started.v1.js";
+import { AgentCompletedV1 } from "./schemas/agent.completed.v1.js";
+import { AgentFailedV1 } from "./schemas/agent.failed.v1.js";
+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 { 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";
+import { VaubanVaultRebalanceProposedV1 } from "./schemas/vauban.vault.rebalance_proposed.v1.js";
+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 { 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";
+
+export const EventSchemas = {
+  "agent.started": AgentStartedV1,
+  "agent.completed": AgentCompletedV1,
+  "agent.failed": AgentFailedV1,
+  "agent.hitl_requested": AgentHitlRequestedV1,
+  "agent.hitl_resolved": AgentHitlResolvedV1,
+  "incident.slo_burn": IncidentSloBurnV1,
+  "incident.detected": IncidentDetectedV1,
+  "forge.lead.qualified": ForgeLeadQualifiedV1,
+  "forge.outreach.sent": ForgeOutreachSentV1,
+  "forge.policy.triggered": ForgePolicyTriggeredV1,
+  "vauban.vault.rebalance_proposed": VaubanVaultRebalanceProposedV1,
+  "vauban.vault.rebalanced": VaubanVaultRebalancedV1,
+  "glacis.identity.verified": GlacisIdentityVerifiedV1,
+  "citadel.sprint.closed": CitadelSprintClosedV1,
+  "brain.skill.extracted": BrainSkillExtractedV1,
+  "cc.cost.recorded": CcCostRecordedV1,
+  "cc.cost.anomaly_detected": CcCostAnomalyDetectedV1,
+  "tenant.provisioned": TenantProvisionedV1,
+  "tenant.budget.exceeded": TenantBudgetExceededV1,
+} as const;
+
+export type EventType =
+  | { type: "agent.started"; payload: z.infer<typeof AgentStartedV1> }
+  | { type: "agent.completed"; payload: z.infer<typeof AgentCompletedV1> }
+  | { type: "agent.failed"; payload: z.infer<typeof AgentFailedV1> }
+  | {
+      type: "agent.hitl_requested";
+      payload: z.infer<typeof AgentHitlRequestedV1>;
+    }
+  | {
+      type: "agent.hitl_resolved";
+      payload: z.infer<typeof AgentHitlResolvedV1>;
+    }
+  | { type: "incident.slo_burn"; payload: z.infer<typeof IncidentSloBurnV1> }
+  | { type: "incident.detected"; payload: z.infer<typeof IncidentDetectedV1> }
+  | {
+      type: "forge.lead.qualified";
+      payload: z.infer<typeof ForgeLeadQualifiedV1>;
+    }
+  | {
+      type: "forge.outreach.sent";
+      payload: z.infer<typeof ForgeOutreachSentV1>;
+    }
+  | {
+      type: "forge.policy.triggered";
+      payload: z.infer<typeof ForgePolicyTriggeredV1>;
+    }
+  | {
+      type: "vauban.vault.rebalance_proposed";
+      payload: z.infer<typeof VaubanVaultRebalanceProposedV1>;
+    }
+  | {
+      type: "vauban.vault.rebalanced";
+      payload: z.infer<typeof VaubanVaultRebalancedV1>;
+    }
+  | {
+      type: "glacis.identity.verified";
+      payload: z.infer<typeof GlacisIdentityVerifiedV1>;
+    }
+  | {
+      type: "citadel.sprint.closed";
+      payload: z.infer<typeof CitadelSprintClosedV1>;
+    }
+  | {
+      type: "brain.skill.extracted";
+      payload: z.infer<typeof BrainSkillExtractedV1>;
+    }
+  | { type: "cc.cost.recorded"; payload: z.infer<typeof CcCostRecordedV1> }
+  | {
+      type: "cc.cost.anomaly_detected";
+      payload: z.infer<typeof CcCostAnomalyDetectedV1>;
+    }
+  | { type: "tenant.provisioned"; payload: z.infer<typeof TenantProvisionedV1> }
+  | {
+      type: "tenant.budget.exceeded";
+      payload: z.infer<typeof TenantBudgetExceededV1>;
+    };
+
+export type EventTypeName = keyof typeof EventSchemas;
+
+export function resolveSchema(
+  type: string
+): z.ZodObject<z.ZodRawShape> | undefined {
+  return (EventSchemas as Record<string, z.ZodObject<z.ZodRawShape>>)[type];
+}
+
+export function validateEvent(
+  type: string,
+  payload: unknown
+): { valid: boolean; error?: string } {
+  const schema = resolveSchema(type);
+  if (!schema) {
+    return { valid: false, error: `Unknown event type: ${type}` };
+  }
+  const result = schema.safeParse(payload);
+  if (result.success) return { valid: true };
+  return { valid: false, error: result.error.message };
+}

package/src/events/index.ts

@@ -0,0 +1,20 @@
+export * from "./catalogue.js";
+export { AgentStartedV1 } from "./schemas/agent.started.v1.js";
+export { AgentCompletedV1 } from "./schemas/agent.completed.v1.js";
+export { AgentFailedV1 } from "./schemas/agent.failed.v1.js";
+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 { 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";
+export { VaubanVaultRebalanceProposedV1 } from "./schemas/vauban.vault.rebalance_proposed.v1.js";
+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 { 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";

package/src/events/schemas/agent.completed.v1.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const AgentCompletedV1 = z
+  .object({
+    agentName: z.string(),
+    runId: z.string().uuid(),
+    outputs: z.unknown(),
+    durationMs: z.number().int().positive(),
+    costUsd: z.number().nonnegative(),
+  })
+  .strict();

package/src/events/schemas/agent.failed.v1.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const AgentFailedV1 = z
+  .object({
+    agentName: z.string(),
+    runId: z.string().uuid(),
+    error: z.string(),
+    retryCount: z.number().int().nonnegative(),
+  })
+  .strict();

package/src/events/schemas/agent.hitl_requested.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const AgentHitlRequestedV1 = z
+  .object({
+    approvalId: z.string().uuid(),
+    question: z.string(),
+    deadline: z.string().datetime(),
+  })
+  .strict();

package/src/events/schemas/agent.hitl_resolved.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const AgentHitlResolvedV1 = z
+  .object({
+    approvalId: z.string().uuid(),
+    decision: z.enum(["approved", "rejected"]),
+    by: z.string(),
+  })
+  .strict();

package/src/events/schemas/agent.started.v1.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const AgentStartedV1 = z
+  .object({
+    agentName: z.string(),
+    runId: z.string().uuid(),
+    inputs: z.unknown(),
+    tenantId: z.string().uuid().optional(),
+  })
+  .strict();

package/src/events/schemas/brain.skill.extracted.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const BrainSkillExtractedV1 = z
+  .object({
+    skillId: z.string(),
+    agentSource: z.string(),
+    confidence: z.number().min(0).max(1),
+  })
+  .strict();

package/src/events/schemas/cc.cost.anomaly_detected.v1.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const CcCostAnomalyDetectedV1 = z
+  .object({
+    agent: z.string(),
+    expected: z.number(),
+    actual: z.number(),
+    period: z.string(),
+  })
+  .strict();

package/src/events/schemas/cc.cost.recorded.v1.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const CcCostRecordedV1 = z
+  .object({
+    agent: z.string(),
+    costUsd: z.number().nonnegative(),
+    tokens: z.number().int().nonnegative(),
+    model: z.string(),
+    tenantId: z.string().uuid().optional(),
+  })
+  .strict();

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

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const CitadelSprintClosedV1 = z
+  .object({
+    sprintId: z.string(),
+    completed: z.number().int().nonnegative(),
+    carryOver: z.number().int().nonnegative(),
+  })
+  .strict();

package/src/events/schemas/forge.lead.qualified.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const ForgeLeadQualifiedV1 = z
+  .object({
+    leadId: z.string().uuid(),
+    score: z.number().min(0).max(100),
+    source: z.enum(["inbound", "outbound", "referral"]),
+  })
+  .strict();

package/src/events/schemas/forge.outreach.sent.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const ForgeOutreachSentV1 = z
+  .object({
+    leadId: z.string().uuid(),
+    channel: z.enum(["email", "linkedin", "x", "telegram"]),
+    content: z.string(),
+  })
+  .strict();

package/src/events/schemas/forge.policy.triggered.v1.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const ForgePolicyTriggeredV1 = z
+  .object({
+    policyId: z.string(),
+    context: z.record(z.unknown()),
+  })
+  .strict();

package/src/events/schemas/glacis.identity.verified.v1.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const GlacisIdentityVerifiedV1 = z
+  .object({
+    userId: z.string().uuid(),
+    method: z.enum(["zk_passport", "zk_email", "world_id"]),
+  })
+  .strict();

package/src/events/schemas/incident.detected.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const IncidentDetectedV1 = z
+  .object({
+    source: z.string(),
+    severity: z.enum(["low", "medium", "high", "critical"]),
+    summary: z.string(),
+  })
+  .strict();

package/src/events/schemas/incident.slo_burn.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const IncidentSloBurnV1 = z
+  .object({
+    slo: z.string(),
+    burnRate: z.number(),
+    severity: z.enum(["low", "medium", "high", "critical"]),
+  })
+  .strict();

package/src/events/schemas/tenant.budget.exceeded.v1.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const TenantBudgetExceededV1 = z
+  .object({
+    tenantId: z.string().uuid(),
+    period: z.string(),
+    amountUsd: z.number(),
+    limitUsd: z.number(),
+  })
+  .strict();

package/src/events/schemas/tenant.provisioned.v1.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const TenantProvisionedV1 = z
+  .object({
+    tenantId: z.string().uuid(),
+    plan: z.enum(["starter", "team", "pro", "enterprise"]),
+    virtualKey: z.string(),
+  })
+  .strict();

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

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const VaubanVaultRebalanceProposedV1 = z
+  .object({
+    vaultId: z.string(),
+    currentRatio: z.number(),
+    targetRatio: z.number(),
+  })
+  .strict();

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

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const VaubanVaultRebalancedV1 = z
+  .object({
+    vaultId: z.string(),
+    txHash: z.string(),
+  })
+  .strict();

package/src/index.ts

@@ -183,9 +183,15 @@ export type {
   ChatMessage,
   ChatUsage,
   StreamDelta,
+  // Price feed port (plan v6 §3.4)
+  PricePort,
+  PriceEntry,
 } from "./ports/index.js";
 export { noopLogger, InvalidTargetError } from "./ports/index.js";
 
+// 8f. EventBusPort + CloudEvent (plan v6 §3.3 — sprint-618)
+export type { EventBusPort, CloudEvent } from "./ports/event-bus.js";
+
 // 8b. LLM adapters — BYOM concrete implementations
 export { LiteLLMAdapter } from "./adapters/llm/litellm.js";
 export type { LiteLLMAdapterConfig } from "./adapters/llm/litellm.js";
@@ -700,6 +706,14 @@ export {
   publishAllSignals,
 } from "./constitution/index.js";
 
+// 40. Events catalogue — 19 versioned Zod schemas (sprint-619:quick-4, plan v6 §4.2-4.3)
+export {
+  EventSchemas,
+  resolveSchema,
+  validateEvent,
+} from "./events/catalogue.js";
+export type { EventType, EventTypeName } from "./events/catalogue.js";
+
 // 39. Shared agent types — promoted from Forge (Vague 1.B.1)
 export type {
   EscalationLevel,

package/src/ports/index.ts

@@ -46,3 +46,5 @@ export type {
   ChatResponse,
   StreamDelta,
 } from "./llm-provider.js";
+
+export type { PricePort, PriceEntry } from "./price.js";

package/src/ports/messaging.contract.test.ts

@@ -128,7 +128,7 @@ describe("TelegramChannel", () => {
     await channel.sendAlert("critical", "Down", "All gone");
     expect(vi.mocked(fetch)).toHaveBeenCalledOnce();
     const [url, init] = vi.mocked(fetch).mock.calls[0] as [string, RequestInit];
-    expect(url).toContain("/bot tok/sendMessage");
+    expect(url).toContain("/bottok/sendMessage");
     const body = JSON.parse(init.body as string) as Record<string, string>;
     expect(body["chat_id"]).toBe("42");
     expect(body["text"]).toContain("🚨");

package/src/ports/price.ts

@@ -0,0 +1,22 @@
+/**
+ * PricePort — asset price feed contract.
+ *
+ * Host injects a concrete adapter (e.g., BastionPriceAdapter → Pragma)
+ * so agents never depend on a specific price oracle or API.
+ *
+ * Design: mirrors BrainPort pattern — interface-only, no impl in SDK.
+ */
+
+export interface PriceEntry {
+  asset: string;
+  priceUsd: number;
+  source: string;
+  fetchedAt: string; // ISO
+}
+
+export interface PricePort {
+  /** Get current price in USD. Returns null if unavailable or stale. */
+  getPrice(asset: string): Promise<number | null>;
+  /** Get prices for multiple assets in one round-trip when possible. */
+  getPrices(assets: string[]): Promise<Record<string, number | null>>;
+}