@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/ports/index.ts

@@ -6,7 +6,7 @@
  * via each agent's setXxxDeps() setter.
  */
 export type { LoggerPort } from "./logger.js";
-export { noopLogger } from "./logger.js";
+export { noopLogger, LoggerFlushError } from "./logger.js";
 
 export type {
   BrainPort,
@@ -25,13 +25,18 @@ export {
   InMemoryEpisodicMemory,
   InMemorySemanticMemory,
   InMemoryProceduralMemory,
+  BrainUnavailableError,
+  BrainRateLimitError,
 } from "./brain.js";
 
 export type { OutcomePort, AgentRunRef } from "./outcome.js";
+export { OutcomeWriteError } from "./outcome.js";
 
 export type { CloudEvent, EventBusPort } from "./event-bus.js";
+export { EventPublishError } from "./event-bus.js";
 
 export type { DbPort, DbClient } from "./db.js";
+export { DbConnectionLostError, DbQueryTimeoutError } from "./db.js";
 
 export type { AgentDescriptor, AgentRegistryPort } from "./agent-registry.js";
 
@@ -46,5 +51,185 @@ export type {
   ChatResponse,
   StreamDelta,
 } from "./llm-provider.js";
+export { LLMProviderError, LLMRateLimitError } from "./llm-provider.js";
 
 export type { PricePort, PriceEntry } from "./price.js";
+
+export type {
+  ComplianceContractPort,
+  ComplianceContract,
+  ComplianceRule,
+  ComplianceGate,
+  ComplianceAuditResult,
+  ComplianceViolation,
+  ManifestValidationResult,
+  PolicyConflict,
+  CapabilityInvocation,
+  TenantContext,
+  LegalBasisRef,
+  LegalBasisDecl,
+  LegalBasisDomain,
+  Jurisdiction,
+  DataClass,
+  ComplianceMode,
+  EnforcementLevel,
+  RuleSource,
+} from "./compliance-contract.js";
+export {
+  CompliancePolicyError,
+  ComplianceEvaluationTimeoutError,
+  SUPPORTED_JURISDICTIONS_V0,
+} from "./compliance-contract.js";
+
+export type {
+  WorkflowRuntimePort,
+  WorkflowContext,
+  WorkflowRun,
+  WorkflowHandler,
+  WorkflowStatus,
+  JournalEntry,
+  StepKind,
+  StepStatus,
+  StepOpts,
+  EventFilter,
+  ChildWorkflowOpts,
+  StartWorkflowOpts,
+  ResumeWorkflowOpts,
+  SendSignalOpts,
+  JournalMigrator,
+  MigrationResult,
+} from "./workflow-runtime.js";
+export {
+  WorkflowNotFoundError,
+  WorkflowNonDeterminismError,
+  WorkflowSignalTimeoutError,
+  WorkflowLeaseConflictError,
+  WorkflowVersionMismatchError,
+} from "./workflow-runtime.js";
+
+// ─── Sprint-636 V2.1 — 9 new ports (manifest, tenant, federation, delegation, products, observability, privacy)
+
+export type * from "./manifest-registry.js";
+export {
+  ManifestNotFoundError,
+  ManifestSignatureInvalidError,
+  ManifestVersionConflictError,
+  ManifestComplianceConflictError,
+  ManifestValidationError,
+} from "./manifest-registry.js";
+
+export type * from "./tenant-context.js";
+export {
+  TenantNotFoundError,
+  DegradedModeExhaustedError,
+  InvalidGlacisAttestationError,
+} from "./tenant-context.js";
+
+export type {
+  FederationPort,
+  FederationMessage,
+  FederationMessageHeader,
+  AgentRef,
+  ContentClaim,
+  TransportMeta,
+  MessageId,
+  ReceiveOpts,
+  VerifyResult as FederationVerifyResult,
+} from "./federation.js";
+export {
+  FederationSignatureInvalidError,
+  FederationRoutingError,
+  FederationDelegationChainError,
+} from "./federation.js";
+
+export type {
+  DelegationPort,
+  DelegationClaim,
+  CapabilityScope,
+  RootCapability,
+  VerifyChainResult,
+} from "./delegation.js";
+export {
+  DelegationNotNarrowingError,
+  DelegationExpiredError,
+  DelegationRevokedError,
+  DelegationChainTooDeepError,
+} from "./delegation.js";
+
+export type {
+  BastionActionPort,
+  SwapParams,
+  SwapResult,
+  DepositParams,
+  DepositResult,
+  WithdrawParams,
+  WithdrawResult,
+  TransferParams,
+  TransferResult,
+  PolicyValidation,
+  ClientPolicy,
+  TokenAddress,
+  VaultAddress,
+  TenantId as BastionTenantId,
+  ActionContext as BastionActionContext,
+} from "./bastion-action.js";
+export {
+  BastionPolicyViolationError,
+  BastionInsufficientFundsError,
+  BastionSlippageExceededError,
+  BastionContractError,
+  BastionTransferUnauthorizedError,
+} from "./bastion-action.js";
+
+export type {
+  VFinanceActionPort,
+  MarketSignal,
+  SolvencyClaim,
+  TradeRecord,
+  TradeClaim,
+  StrategyRunInput,
+  StrategyRunClaim,
+  PortfolioId,
+  ProofGrade,
+  ActionContext as VFActionContext,
+} from "./vauban-finance-action.js";
+export {
+  VFOracleQuorumError,
+  VFProofGradeMismatchError,
+  VFAnchoringForbiddenError,
+  VFProofGenerationError,
+} from "./vauban-finance-action.js";
+
+export type {
+  CitadelActionPort,
+  AgentTier,
+  SprintInput,
+  SprintRef,
+  TaskRef,
+  TaskStatus,
+  VerificationEvidence,
+  SealedSprintClaim,
+  DecisionInput,
+  DecisionClaim,
+  ActionContext as CitadelActionContext,
+} from "./citadel-action.js";
+export {
+  CitadelTierViolationError,
+  CitadelTaskRefNotFoundError,
+  CitadelSprintNotActiveError,
+  CitadelInvalidStateTransitionError,
+} from "./citadel-action.js";
+
+export type * from "./observability.js";
+export { NoopObservabilityPort } from "./observability.js";
+
+export type {
+  RevelationMask,
+  ZkProofInput,
+  VerifyResult as PrivacyVerifyResult,
+  Commitment,
+  SmtResult,
+  PrivacyContext,
+  PrivacyPort,
+} from "./privacy.js";
+export { NoopPrivacyAdapter, PrivacyNoopWarning } from "./privacy.js";

package/src/ports/llm-provider.ts

@@ -7,6 +7,10 @@
  *
  * Plan v6 §3.2 — canonical interface.
  *
+ * OTel instrumentation: import { createTracedLLMProviderPort } to wrap any
+ * LLMProviderPort implementation with OpenTelemetry spans per completion.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
  * @public
  */
 
@@ -66,3 +70,122 @@ export interface LLMProviderPort {
    */
   estimateCost?(req: ChatRequest): { usd: number };
 }
+
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+
+/**
+ * Base class for all LLM provider errors.
+ * Concrete implementations throw subclasses so callers can switch on error type.
+ */
+export class LLMProviderError extends Error {
+  /** The provider identifier (e.g. "groq", "litellm", "anthropic"). */
+  readonly provider: string;
+  /** The model that was being called (e.g. "llama-3.3-70b"). */
+  readonly model: string;
+
+  constructor(
+    message: string,
+    provider: string,
+    model: string,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = "LLMProviderError";
+    this.provider = provider;
+    this.model = model;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when the LLM provider returns 429 (rate limit exceeded).
+ * Callers should retry after the delay indicated in `retryAfterMs`
+ * or switch to a fallback provider.
+ */
+export class LLMRateLimitError extends LLMProviderError {
+  /** Retry-After delay in milliseconds. */
+  readonly retryAfterMs: number;
+
+  constructor(
+    message: string,
+    provider: string,
+    model: string,
+    retryAfterMs: number,
+    cause?: unknown
+  ) {
+    super(message, provider, model, cause);
+    this.name = "LLMRateLimitError";
+    this.retryAfterMs = retryAfterMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+// ─── OTel-traced wrapper ──────────────────────────────────────────────────────
+
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+const PORT_TRACER = trace.getTracer("vauban-agent-sdk.ports", "0.1.0");
+
+/**
+ * Wrap any LLMProviderPort implementation with OTel spans per complete() call.
+ * The span captures the model, provider, and token usage on success.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
+ * Usage:
+ *   const raw: LLMProviderPort = buildAnthropicAdapter(...);
+ *   const traced = createTracedLLMProviderPort(raw);
+ *   const resp = await traced.complete(req) // emits "llm-provider.complete" span
+ */
+export function createTracedLLMProviderPort(
+  impl: LLMProviderPort
+): LLMProviderPort {
+  return {
+    async complete(req) {
+      return PORT_TRACER.startActiveSpan(
+        "llm-provider.complete",
+        {
+          attributes: {
+            "gen_ai.request.model": req.model ?? "unknown",
+            "gen_ai.request.message_count": req.messages.length,
+            "vauban.port.name": "llm-provider",
+          },
+        },
+        async (span: Span) => {
+          try {
+            const resp = await impl.complete(req);
+            span.setAttributes({
+              "gen_ai.usage.input_tokens": resp.usage.inputTokens,
+              "gen_ai.usage.output_tokens": resp.usage.outputTokens,
+              "gen_ai.response.model": resp.model,
+              "gen_ai.response.finish_reasons": [resp.finishReason],
+            });
+            if (resp.usage.costUsd !== undefined) {
+              span.setAttribute("gen_ai.usage.cost_usd", resp.usage.costUsd);
+            }
+            span.setStatus({ code: SpanStatusCode.OK });
+            return resp;
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            span.setStatus({ code: SpanStatusCode.ERROR, message });
+            if (err instanceof Error) span.recordException(err);
+            throw err;
+          } finally {
+            span.end();
+          }
+        }
+      );
+    },
+
+    async *stream(req) {
+      if (!impl.stream) return;
+      for await (const chunk of impl.stream(req)) {
+        yield chunk;
+      }
+    },
+
+    estimateCost(req: ChatRequest): { usd: number } {
+      return impl.estimateCost?.(req) ?? { usd: 0 };
+    },
+  };
+}

package/src/ports/logger.ts

@@ -3,7 +3,17 @@
  *
  * Shape matches Pino's child-logger subset. Host wires any concrete
  * logger (pino, winston, console-shim) that implements these methods.
+ *
+ * OTel instrumentation: import { createTracedLoggerPort } to wrap any
+ * LoggerPort implementation with OpenTelemetry spans per log call.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
  */
+
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+const PORT_TRACER = trace.getTracer("vauban-agent-sdk.ports", "0.1.0");
+
 export interface LoggerPort {
   debug(objOrMsg: object | string, msg?: string): void;
   info(objOrMsg: object | string, msg?: string): void;
@@ -12,6 +22,29 @@ export interface LoggerPort {
   child?(bindings: Record<string, unknown>): LoggerPort;
 }
 
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+
+/**
+ * Thrown when the log transport fails to flush pending buffers (disk full,
+ * network timeout on remote sink, or backend refused connection).
+ * Callers may retry flush or discard pending entries depending on criticality.
+ */
+export class LoggerFlushError extends Error {
+  /** Number of log entries that could not be flushed. */
+  readonly pendingCount: number;
+
+  constructor(
+    message: string,
+    pendingCount: number,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = "LoggerFlushError";
+    this.pendingCount = pendingCount;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
 /**
  * noopLogger — convenience for tests where logs are not asserted.
  */
@@ -21,3 +54,74 @@ export const noopLogger: LoggerPort = {
   warn: () => {},
   error: () => {},
 };
+
+/**
+ * Wrap any LoggerPort implementation with OTel spans per log call.
+ * Each log level emits a short-lived span capturing the level and
+ * optional metadata. Gracefully degrades to noop spans when no OTel
+ * SDK is installed.
+ *
+ * Usage:
+ *   const raw: LoggerPort = pino();
+ *   const traced = createTracedLoggerPort(raw);
+ *   traced.info("boot") // emits "logger.info" span
+ */
+export function createTracedLoggerPort(impl: LoggerPort): LoggerPort {
+  function tracedLog(
+    level: string,
+    objOrMsg: object | string,
+    msg?: string
+  ): void {
+    PORT_TRACER.startActiveSpan(
+      `logger.${level}`,
+      {
+        attributes: {
+          "log.level": level,
+          "vauban.port.name": "logger",
+        },
+      },
+      (span: Span) => {
+        try {
+          const fn = (
+            impl as unknown as Record<string, (...args: unknown[]) => void>
+          )[level];
+          if (typeof fn !== "function") {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: `LoggerPort missing method: ${level}`,
+            });
+            return;
+          }
+          if (msg !== undefined) {
+            fn(objOrMsg, msg);
+          } else {
+            fn(objOrMsg);
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+        } catch (err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err instanceof Error ? err.message : String(err),
+          });
+        } finally {
+          span.end();
+        }
+      }
+    );
+  }
+
+  return {
+    debug: (objOrMsg: object | string, msg?: string) =>
+      tracedLog("debug", objOrMsg, msg),
+    info: (objOrMsg: object | string, msg?: string) =>
+      tracedLog("info", objOrMsg, msg),
+    warn: (objOrMsg: object | string, msg?: string) =>
+      tracedLog("warn", objOrMsg, msg),
+    error: (objOrMsg: object | string, msg?: string) =>
+      tracedLog("error", objOrMsg, msg),
+    child: impl.child
+      ? (bindings: Record<string, unknown>) =>
+          createTracedLoggerPort(impl.child!(bindings))
+      : undefined,
+  };
+}