@vauban-org/agent-sdk 1.0.0 → 1.3.0

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 ---`;
+}

package/src/identity/persona-schema.ts

@@ -0,0 +1,127 @@
+/**
+ * AgentPersona schema — Sprint CC v3.1 (Livrable E).
+ *
+ * Persona is a structured description of how an agent should communicate:
+ * tone, formality, language, domain expertise, response shape preferences.
+ * Stored in Brain Tier 3 (semantic) per agent + override locally via
+ * `.cc/persona.yaml`.
+ *
+ * The schema is intentionally minimal — additive evolution preferred over
+ * breaking changes. All fields are optional; the resolved persona is the
+ * merge of (1) Brain-stored persona, (2) local overrides, (3) defaults.
+ *
+ * Spec reference:
+ *   - Plan canonical v3.1 §Livrable E
+ *   - ADR-ECO-034 §"AgentPersona via Brain Tier 3 semantic"
+ *
+ * @public
+ */
+
+import { z } from "zod";
+
+export const PersonaTone = z.enum(["concise", "detailed", "pedagogical"]);
+export type PersonaTone = z.infer<typeof PersonaTone>;
+
+export const PersonaFormality = z.enum(["casual", "formal", "technical"]);
+export type PersonaFormality = z.infer<typeof PersonaFormality>;
+
+export const PersonaExplainReasoning = z.enum(["always", "on_error", "never"]);
+export type PersonaExplainReasoning = z.infer<typeof PersonaExplainReasoning>;
+
+export const PersonaAcknowledgmentStyle = z.enum([
+  "minimal",
+  "detailed",
+  "none",
+]);
+export type PersonaAcknowledgmentStyle = z.infer<
+  typeof PersonaAcknowledgmentStyle
+>;
+
+// ─── Schemas ────────────────────────────────────────────────────────────────
+
+const IdentitySchema = z
+  .object({
+    name: z.string().min(1).max(64).optional(),
+    role: z.string().min(1).max(256).optional(),
+    tone: PersonaTone.optional(),
+    formality: PersonaFormality.optional(),
+    /** BCP 47 language tag (e.g. "en", "fr-FR"). Free-form on purpose. */
+    language: z.string().min(2).max(16).optional(),
+  })
+  .strict();
+
+const CommunicationSchema = z
+  .object({
+    max_response_length: z.number().int().positive().max(100_000).optional(),
+    use_analogies: z.boolean().optional(),
+    explain_reasoning: PersonaExplainReasoning.optional(),
+    acknowledgment_style: PersonaAcknowledgmentStyle.optional(),
+  })
+  .strict();
+
+export const PersonaSchema = z
+  .object({
+    identity: IdentitySchema.optional(),
+    traits: z.array(z.string().min(1).max(64)).max(16).optional(),
+    domain_expertise: z.array(z.string().min(1).max(128)).max(32).optional(),
+    communication: CommunicationSchema.optional(),
+  })
+  .strict();
+
+export type AgentPersona = z.infer<typeof PersonaSchema>;
+
+// ─── Defaults ──────────────────────────────────────────────────────────────
+
+export const DEFAULT_PERSONA: AgentPersona = {
+  identity: {
+    tone: "concise",
+    formality: "technical",
+    language: "en",
+  },
+  traits: [],
+  domain_expertise: [],
+  communication: {
+    explain_reasoning: "on_error",
+    acknowledgment_style: "minimal",
+  },
+};
+
+// ─── Merge ────────────────────────────────────────────────────────────────
+
+/**
+ * Deep-merge two personas. `local` wins over `base` field-by-field.
+ *
+ * Arrays (traits, domain_expertise) follow override semantics: a `local` array
+ * REPLACES the `base` array entirely. To extend rather than override, the
+ * caller must concatenate before calling `mergePersona`.
+ *
+ * The merge is total (no Zod validation here — callers should validate
+ * inputs and the result separately). This makes mergePersona suitable for
+ * progressive composition where intermediate values may not yet satisfy
+ * the schema.
+ */
+export function mergePersona(
+  base: AgentPersona,
+  local: AgentPersona
+): AgentPersona {
+  return {
+    identity: {
+      ...base.identity,
+      ...local.identity,
+    },
+    traits: local.traits ?? base.traits,
+    domain_expertise: local.domain_expertise ?? base.domain_expertise,
+    communication: {
+      ...base.communication,
+      ...local.communication,
+    },
+  };
+}
+
+/**
+ * Validate a persona object against the schema. Returns the parsed result
+ * (with Zod typing) or throws a typed error.
+ */
+export function validatePersona(input: unknown): AgentPersona {
+  return PersonaSchema.parse(input);
+}

package/src/index.ts

@@ -105,10 +105,39 @@ export { createAgentRunTracker } from "./tracking/agent-run-tracker.js";
 export type {
   AgentRunTracker,
   AgentRunStartInput,
-  AgentRunStepDelta,
   AgentRunFinish,
   DbClient,
 } from "./tracking/agent-run-tracker.js";
+
+// ─── Telemetry — sovereign multi-sink observability (ADR-ECO-039) ────────────
+export {
+  NOOP_TELEMETRY_SINK,
+  TelemetrySinkError,
+  createTelemetryBus,
+  stdoutTelemetrySink,
+  localSqliteTelemetrySink,
+  otlpTelemetrySink,
+} from "./telemetry/index.js";
+export type {
+  TelemetrySink,
+  TelemetryRunStart,
+  TelemetryRunStep,
+  TelemetryRunFinish,
+  TelemetryRunStatus,
+  TelemetryBusOptions,
+  TelemetryCounters,
+  TelemetryLogger,
+  StdoutTelemetrySinkOptions,
+  LocalSqliteTelemetrySinkOptions,
+  OtlpTelemetrySinkOptions,
+} from "./telemetry/index.js";
+
+// Re-export legacy AgentRunStepDelta + AgentRunFinalStatus (kept for backward
+// compat with `AgentRunTracker` consumers, e.g. command-center/src/tracking).
+export type {
+  AgentRunStepDelta,
+  AgentRunFinalStatus,
+} from "./tracking/agent-run-tracker.js";
 export { createBullMQRunner, BullMQRunner } from "./durable/bullmq-runner.js";
 export type {
   BullMQRunnerConfig,
@@ -186,8 +215,156 @@ export type {
   // Price feed port (plan v6 §3.4)
   PricePort,
   PriceEntry,
+  // WorkflowRuntime port (A-4 DBOS-TS adapter, S3 spec)
+  WorkflowRuntimePort,
+  WorkflowContext,
+  WorkflowRun,
+  WorkflowHandler,
+  WorkflowStatus,
+  JournalEntry,
+  StepKind,
+  StepStatus,
+  StepOpts,
+  EventFilter,
+  ChildWorkflowOpts,
+  StartWorkflowOpts,
+  ResumeWorkflowOpts,
+  SendSignalOpts,
+  JournalMigrator,
+  MigrationResult,
+  // Compliance Contract port (G-2 Cedar pivot, S5 spec)
+  ComplianceContractPort,
+  ComplianceContract,
+  ComplianceRule,
+  ComplianceGate,
+  ComplianceAuditResult,
+  ComplianceViolation,
+  ManifestValidationResult,
+  PolicyConflict,
+  CapabilityInvocation,
+  TenantContext,
+  LegalBasisRef,
+  LegalBasisDecl,
+  LegalBasisDomain,
+  Jurisdiction,
+  DataClass,
+  ComplianceMode,
+  EnforcementLevel,
+  RuleSource,
+} from "./ports/index.js";
+export {
+  noopLogger,
+  InvalidTargetError,
+  BrainUnavailableError,
+  BrainRateLimitError,
+  OutcomeWriteError,
+  LoggerFlushError,
+  DbConnectionLostError,
+  DbQueryTimeoutError,
+  EventPublishError,
+  LLMProviderError,
+  LLMRateLimitError,
+  // WorkflowRuntime errors
+  WorkflowNotFoundError,
+  WorkflowNonDeterminismError,
+  WorkflowSignalTimeoutError,
+  WorkflowLeaseConflictError,
+  WorkflowVersionMismatchError,
+  // Compliance Contract errors + constants
+  CompliancePolicyError,
+  ComplianceEvaluationTimeoutError,
+  SUPPORTED_JURISDICTIONS_V0,
+} from "./ports/index.js";
+
+// 8g. Sprint-636 V2.1 — 9 new ports (manifest, tenant, federation, delegation, products, observability, privacy)
+export type {
+  ManifestRegistryPort,
+  Manifest,
+  RegistrationResult,
+  TenantContextPort,
+  DegradedMetrics,
+  FederationPort,
+  FederationMessage,
+  ContentClaim,
+  FederationMessageHeader,
+  AgentRef,
+  TransportMeta,
+  MessageId as FederationMessageId,
+  ReceiveOpts as FederationReceiveOpts,
+  FederationVerifyResult,
+  DelegationPort,
+  DelegationClaim,
+  CapabilityScope,
+  BastionActionPort,
+  BastionActionContext,
+  BastionTenantId,
+  ClientPolicy,
+  SwapParams,
+  SwapResult,
+  DepositParams,
+  DepositResult,
+  WithdrawParams,
+  WithdrawResult,
+  TransferParams,
+  TransferResult,
+  PolicyValidation,
+  VFinanceActionPort,
+  VFActionContext,
+  MarketSignal,
+  SolvencyClaim,
+  TradeRecord,
+  TradeClaim,
+  StrategyRunInput,
+  StrategyRunClaim,
+  PortfolioId,
+  ProofGrade,
+  CitadelActionPort,
+  CitadelActionContext,
+  AgentTier,
+  TaskStatus,
+  TaskRef,
+  SprintInput,
+  SprintRef,
+  VerificationEvidence,
+  SealedSprintClaim,
+  DecisionInput,
+  DecisionClaim,
+  ObservabilityPort,
+  PrivacyPort,
+} from "./ports/index.js";
+export {
+  ManifestNotFoundError,
+  ManifestSignatureInvalidError,
+  ManifestVersionConflictError,
+  ManifestComplianceConflictError,
+  ManifestValidationError,
+  TenantNotFoundError,
+  DegradedModeExhaustedError,
+  InvalidGlacisAttestationError,
+  FederationSignatureInvalidError,
+  FederationRoutingError,
+  FederationDelegationChainError,
+  DelegationNotNarrowingError,
+  DelegationExpiredError,
+  DelegationRevokedError,
+  DelegationChainTooDeepError,
+  BastionPolicyViolationError,
+  BastionInsufficientFundsError,
+  BastionSlippageExceededError,
+  BastionContractError,
+  BastionTransferUnauthorizedError,
+  VFOracleQuorumError,
+  VFProofGradeMismatchError,
+  VFAnchoringForbiddenError,
+  VFProofGenerationError,
+  CitadelTierViolationError,
+  CitadelTaskRefNotFoundError,
+  CitadelSprintNotActiveError,
+  CitadelInvalidStateTransitionError,
+  NoopObservabilityPort,
+  NoopPrivacyAdapter,
+  PrivacyNoopWarning,
 } 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";
@@ -339,6 +516,58 @@ export type {
   BulkheadStats,
 } from "./resilience/index.js";
 
+// 12b. Retry primitives — RetryConfig, retry(), RetryContext + 4 presets (SDK v1.2.0 — sprint-680)
+export {
+  retry,
+  RetryContext,
+  RetryExhaustedError,
+  calculateDelay,
+  shouldRetry,
+  RETRY_TRANSIENT,
+  RETRY_AGGRESSIVE,
+  RETRY_PATIENT,
+  NO_RETRY,
+} from "./retry/index.js";
+export type { RetryConfig, RetryOptions, SleepFn } from "./retry/index.js";
+
+// 12d. SkillContext extensions — secrets audit, progress, time tracking (SDK v1.2.0 — sprint-685)
+export {
+  InMemorySecretsAccessor,
+  NOOP_SECRETS,
+  SecretNotFoundError,
+  createSkillContext,
+} from "./orchestration/ooda/skills.js";
+export type {
+  SecretsAccessor,
+  ProgressCallback,
+  CreateSkillContextOptions,
+} from "./orchestration/ooda/skills.js";
+
+// 12c. Container execution protocol — uniform contract for binary/container automations (SDK v1.2.0 — sprint-684)
+export {
+  PROTOCOL_ENV,
+  DEFAULT_PROTOCOL_MODE,
+  ProtocolParseError,
+  buildProtocolEnv,
+  parseProtocolOutput,
+  parseStderrLogs,
+} from "./container/protocol.js";
+export type {
+  ProtocolStatus,
+  ProtocolResult,
+  ExecutionResult,
+} from "./container/protocol.js";
+export { ContainerRuntime } from "./container/runtime.js";
+export type {
+  ContainerRuntimeOptions,
+  ContainerExecutionOptions,
+  BinaryExecutionOptions,
+  SandboxExecutor,
+  SandboxJob,
+  SandboxResult,
+  SpawnFn as ContainerSpawnFn,
+} from "./container/runtime.js";
+
 // 13. Outcomes module (SDK v0.5.1 — Sprint-522)
 export * from "./outcomes/index.js";
 
@@ -606,8 +835,70 @@ export type {
   MAVAggregation,
   BonMavOptions,
 } from "./compute/strategies/bon-mav.js";
+export { treeOfThoughtsStrategy } from "./compute/strategies/tree-of-thoughts.js";
+export type {
+  ToTConfig,
+  ToTSearchPolicy,
+} from "./compute/strategies/tree-of-thoughts.js";
+export { mixtureOfAgentsStrategy } from "./compute/strategies/mixture-of-agents.js";
+export type { MoAConfig } from "./compute/strategies/mixture-of-agents.js";
+export {
+  estimateDifficulty,
+  extractFeatures,
+  recommendStrategy,
+} from "./compute/difficulty-estimator.js";
+export type {
+  DifficultyClass,
+  TaskFeatures,
+} from "./compute/difficulty-estimator.js";
 export { assertVerifierResult } from "./compute/verifier.js";
 export type { Verifier, VerifierResult } from "./compute/verifier.js";
+export {
+  runTwoPhaseOrient,
+  TwoPhaseOrientError,
+} from "./compute/strategies/two-phase-orient.js";
+export type {
+  TwoPhaseOrientConfig,
+  TwoPhaseOrientResult,
+} from "./compute/strategies/two-phase-orient.js";
+
+// 33b. mesh.delegate() — intent-based dispatch + capability attenuation (sprint-585)
+export {
+  meshDelegate,
+  createMeshDelegate,
+  DelegateAttenuationError,
+} from "./mesh/delegate.js";
+export type {
+  DelegateOptions,
+  DelegateResult,
+  DelegateChunk,
+} from "./mesh/delegate.js";
+export {
+  DefaultMeshDispatcher,
+  MeshDispatchError,
+  DeadlineExceededError as MeshDeadlineExceededError,
+  defaultClassifier as meshDefaultClassifier,
+} from "./mesh/dispatcher.js";
+export type {
+  MeshDispatcher,
+  DispatchIntent,
+  DispatchResult,
+  DispatcherConfig,
+} from "./mesh/dispatcher.js";
+export {
+  attenuateScope,
+  buildToken as buildAttenuatedToken,
+  parseToken as parseAttenuatedToken,
+  scopeAllows,
+} from "./mesh/attenuation.js";
+export type {
+  AttenuatedToken,
+  MeshCapabilityScope,
+} from "./mesh/attenuation.js";
+export type {
+  MeshAgentKind,
+  DelegationLink as MeshDelegationLink,
+} from "./mesh/types.js";
 
 // 34. BrainPort eviction policies (sprint-580 Sprint A)
 export {
@@ -723,3 +1014,78 @@ export type {
 } from "./types/agent.js";
 export { toSdkEscalationLevel } from "./types/escalation-mapping.js";
 export type { SdkEscalationLevel } from "./types/escalation-mapping.js";
+
+// 41. Formal verification (sprint-587) — Z3 4-state SAFE/UNSAFE/UNKNOWN/SKIPPED
+export {
+  formalVerify,
+  DEFAULT_POLICIES,
+  applyPolicy,
+  AXIOM_SPECS,
+  compileToSmt,
+} from "./verify/formal/index.js";
+export type {
+  ConsumerMode,
+  FormalVerifyResult,
+  FormalVerifyState,
+  AxiomPolicy,
+  AxiomSpec,
+  PolicyAction,
+  PolicyDecision,
+  VerifyContext,
+  OnUnknown,
+  OnUnsafe,
+  Condition,
+  FormalSolver,
+  FormalVerifyDecision,
+} from "./verify/formal/index.js";
+
+// AgentPersona (CC v3.1 — Livrable E)
+export {
+  DEFAULT_PERSONA,
+  mergePersona,
+  PersonaSchema,
+  validatePersona,
+} from "./identity/persona-schema.js";
+export type {
+  AgentPersona,
+  PersonaTone,
+  PersonaFormality,
+  PersonaExplainReasoning,
+  PersonaAcknowledgmentStyle,
+} from "./identity/persona-schema.js";
+export {
+  PERSONA_BRAIN_CATEGORY,
+  personaTags,
+  savePersonaToBrain,
+  loadPersonaFromBrain,
+  loadPersonaFromFile,
+  savePersonaToFile,
+  resolvePersona,
+} from "./identity/agent-persona.js";
+export type {
+  ResolvePersonaOptions,
+  ResolvedPersona,
+} from "./identity/agent-persona.js";
+
+// Persona prompt builder (CC v3.1 — Livrable E)
+export { buildPersonaPromptBlock } from "./identity/persona-prompt.js";
+
+// EpisodicMemory RRF (CC v3.1 — Livrable F)
+// cosineSimilarity already exported via sprint-564:C3 above
+export type { EpisodicMemoryEntry } from "./ports/brain.js";
+export {
+  recencyScore,
+  scoreEntries,
+  recallEpisodicRrf,
+  DEFAULT_RRF_WEIGHTS,
+  DEFAULT_RECENCY_HALFLIFE_MS,
+} from "./memory/episodic-rrf.js";
+export type {
+  RrfWeights,
+  RrfOptions,
+  ScoreComponents,
+  ScoredEntry,
+  RrfScorers,
+  EpisodicCosineFn,
+  RecallRrfOptions,
+} from "./memory/episodic-rrf.js";