twinclaw 1.0.0

package/src/types/messaging.ts

@@ -0,0 +1,35 @@
+/** Supported messaging platforms. */
+export type Platform = 'telegram' | 'whatsapp';
+
+/** A normalized inbound message from any supported platform. */
+export interface InboundMessage {
+  platform: Platform;
+  /** The sender's user ID as a string (platform-specific). */
+  senderId: string;
+  /** The destination chat/channel ID used for reply routing. */
+  chatId: string | number;
+  /** Transcribed or raw text content of the message. */
+  text?: string;
+  /** Absolute path to a downloaded audio file, if the message is a voice note. */
+  audioFilePath?: string;
+  /** Original platform payload, kept for platform-specific extensions. */
+  rawPayload: unknown;
+}
+
+/** A normalized outbound response to be sent back to the user. */
+export interface OutboundMessage {
+  platform: Platform;
+  chatId: string | number;
+  /** Plain-text response. */
+  text?: string;
+  /** Encoded audio buffer for a voice reply (mp3). */
+  audioBuffer?: Buffer;
+}
+
+/**
+ * Contract for the core gateway that processes normalized messages.
+ * Implemented by the core_persona track; imported here as a dependency boundary.
+ */
+export interface GatewayHandler {
+  processMessage(message: InboundMessage): Promise<string>;
+}

package/src/types/model-routing.ts

@@ -0,0 +1,61 @@
+export type ModelRoutingFallbackMode = 'intelligent_pacing' | 'aggressive_fallback';
+
+export type ModelRoutingEventType =
+  | 'attempt'
+  | 'success'
+  | 'failure'
+  | 'rate_limit'
+  | 'cooldown_set'
+  | 'cooldown_wait'
+  | 'cooldown_skip'
+  | 'failover'
+  | 'mode_change';
+
+export interface ModelRoutingCooldownSnapshot {
+  modelId: string;
+  modelName: string;
+  provider: string;
+  reason: string;
+  remainingMs: number;
+  until: string;
+}
+
+export interface ModelRoutingUsageSnapshot {
+  modelId: string;
+  modelName: string;
+  provider: string;
+  attempts: number;
+  successes: number;
+  failures: number;
+  rateLimits: number;
+  lastUsedAt: string | null;
+  lastError: string | null;
+}
+
+export interface ModelRoutingEventSnapshot {
+  id: string;
+  type: ModelRoutingEventType;
+  modelId: string | null;
+  modelName: string | null;
+  provider: string | null;
+  fallbackMode: ModelRoutingFallbackMode;
+  detail: string;
+  createdAt: string;
+}
+
+export interface ModelRoutingTelemetrySnapshot {
+  fallbackMode: ModelRoutingFallbackMode;
+  preferredModelId: string | null;
+  currentModelId: string | null;
+  currentModelName: string | null;
+  totalRequests: number;
+  totalFailures: number;
+  consecutiveFailures: number;
+  failoverCount: number;
+  lastError: string | null;
+  lastFailureAt: string | null;
+  activeCooldowns: ModelRoutingCooldownSnapshot[];
+  usage: ModelRoutingUsageSnapshot[];
+  recentEvents: ModelRoutingEventSnapshot[];
+  operatorGuidance: string[];
+}

package/src/types/mvp-gate.ts

@@ -0,0 +1,99 @@
+// ─── MVP Gate Criterion IDs ──────────────────────────────────────────────────
+
+/**
+ * Hard-gate IDs block the "go" verdict if they fail.
+ * Advisory IDs produce warnings only.
+ */
+export type MvpHardGateId =
+  | 'build'
+  | 'tests'
+  | 'api-health'
+  | 'config-schema'
+  | 'vault-health'
+  | 'interface-readiness'
+  | 'npm-commands'
+  | 'installer-smoke'
+  | 'onboarding-smoke';
+
+export type MvpAdvisoryId = 'dist-artifact' | 'test-coverage' | 'doctor-readiness';
+
+export type MvpCriterionId = MvpHardGateId | MvpAdvisoryId;
+
+export type MvpCriterionClass = 'hard-gate' | 'advisory';
+
+export type MvpCheckStatus = 'passed' | 'failed' | 'skipped';
+
+export type TriageSeverity = 'blocker' | 'advisory';
+
+export type MvpGateVerdict = 'go' | 'no-go' | 'advisory-only';
+
+// ─── Per-Check Result ────────────────────────────────────────────────────────
+
+export interface MvpCheckResult {
+  id: MvpCriterionId;
+  class: MvpCriterionClass;
+  status: MvpCheckStatus;
+  detail: string;
+  startedAt: string;
+  completedAt: string;
+  durationMs: number;
+  command?: string;
+  artifacts?: string[];
+}
+
+// ─── Smoke Scenarios ─────────────────────────────────────────────────────────
+
+/**
+ * A smoke scenario is a deterministic, side-effect-free static check of a
+ * critical runtime asset or configuration file.
+ */
+export interface MvpSmokeScenario {
+  id: string;
+  label: string;
+  pass: boolean;
+  detail: string;
+}
+
+// ─── Failure Triage ──────────────────────────────────────────────────────────
+
+/**
+ * Maps a failing check to its owning track/agent and a concrete next-action.
+ */
+export interface TriageEntry {
+  checkId: MvpCriterionId;
+  severity: TriageSeverity;
+  ownerTrack: string;
+  detail: string;
+  nextAction: string;
+}
+
+// ─── Gate Report ─────────────────────────────────────────────────────────────
+
+export interface MvpGateReport {
+  reportVersion: 1;
+  reportId: string;
+  generatedAt: string;
+  verdict: MvpGateVerdict;
+  hardGatePassed: boolean;
+  checks: MvpCheckResult[];
+  failedHardGates: MvpCheckResult[];
+  advisoryFailures: MvpCheckResult[];
+  smokeScenarios: MvpSmokeScenario[];
+  triage: TriageEntry[];
+  summary: string;
+  reportPath: string;
+  markdownPath: string;
+}
+
+// ─── Service Options ─────────────────────────────────────────────────────────
+
+export interface MvpGateOptions {
+  /**
+   * URL of the health endpoint. If not provided, defaults to localhost:18789/health.
+   */
+  healthUrl?: string;
+  /**
+   * If true, skip the api-health hard gate entirely.
+   */
+  skipHealth?: boolean;
+}

package/src/types/orchestration.ts

@@ -0,0 +1,65 @@
+export type OrchestrationJobState =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+/** Constraints applied to delegated sub-agent work. */
+export interface DelegationConstraints {
+  toolBudget: number;
+  timeoutMs: number;
+  maxTurns: number;
+}
+
+/** Work brief for one delegated sub-agent. */
+export interface DelegationBrief {
+  /** Stable node identifier within the delegation graph. */
+  id: string;
+  /** Upstream node IDs that must complete successfully first. */
+  dependsOn?: string[];
+  title: string;
+  objective: string;
+  scopedContext: string;
+  expectedOutput: string;
+  constraints: DelegationConstraints;
+}
+
+/** Context package prepared by the gateway for delegated jobs. */
+export interface DelegationScope {
+  sessionId: string;
+  memoryContext: string;
+  recentMessages: Array<{
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+  }>;
+}
+
+/** One delegation request can spawn multiple jobs under the same parent turn. */
+export interface DelegationRequest {
+  sessionId: string;
+  parentMessage: string;
+  scope: DelegationScope;
+  briefs: DelegationBrief[];
+}
+
+export interface OrchestrationJobSnapshot {
+  id: string;
+  sessionId: string;
+  parentMessage: string;
+  brief: DelegationBrief;
+  state: OrchestrationJobState;
+  attempt: number;
+  createdAt: string;
+  updatedAt: string;
+  startedAt?: string;
+  completedAt?: string;
+  output?: string;
+  error?: string;
+}
+
+export interface DelegationExecutionResult {
+  jobs: OrchestrationJobSnapshot[];
+  summary: string;
+  hasFailures: boolean;
+}

package/src/types/persona-state.ts

@@ -0,0 +1,61 @@
+export const PERSONA_DOCUMENT_KEYS = ['soul', 'identity', 'user'] as const;
+
+export type PersonaDocumentKey = (typeof PERSONA_DOCUMENT_KEYS)[number];
+
+export interface PersonaStateSnapshot {
+  revision: string;
+  updatedAt: string;
+  soul: string;
+  identity: string;
+  user: string;
+}
+
+export interface PersonaStateUpdateInput {
+  expectedRevision: unknown;
+  soul: unknown;
+  identity: unknown;
+  user: unknown;
+}
+
+export interface PersonaStateValidatedUpdateInput {
+  expectedRevision: string;
+  soul: string;
+  identity: string;
+  user: string;
+}
+
+export interface PersonaStateUpdateDiagnostics {
+  outcome: 'updated' | 'noop';
+  changedDocuments: PersonaDocumentKey[];
+  warnings: string[];
+}
+
+export interface PersonaStateUpdateResult {
+  state: PersonaStateSnapshot;
+  diagnostics: PersonaStateUpdateDiagnostics;
+}
+
+export class PersonaValidationError extends Error {
+  readonly hints: string[];
+
+  constructor(hints: string[]) {
+    super('Persona state validation failed.');
+    this.name = 'PersonaValidationError';
+    this.hints = hints;
+  }
+}
+
+export class PersonaConflictError extends Error {
+  readonly latestRevision: string;
+  readonly hints: string[];
+
+  constructor(latestRevision: string) {
+    super('Persona state is stale. Reload and retry.');
+    this.name = 'PersonaConflictError';
+    this.latestRevision = latestRevision;
+    this.hints = [
+      'Reload persona state before saving again.',
+      'Re-apply your edits on top of the latest revision.',
+    ];
+  }
+}

package/src/types/policy.ts

@@ -0,0 +1,27 @@
+export type PolicyAction = 'allow' | 'deny' | 'require_approval';
+
+export interface PolicyRule {
+    /** The name of the skill to match. Can be '*' to match any skill. */
+    skillName: string;
+    /** The action to take if this rule matches. */
+    action: PolicyAction;
+    /** Optional reason explaining the policy rule. */
+    reason?: string;
+}
+
+export interface PolicyProfile {
+    id: string;
+    /** 
+     * What to do if no rule matches. 
+     * If 'fallback', it defers to the next profile in the chain (e.g., global default).
+     */
+    defaultAction: PolicyAction | 'fallback';
+    rules: PolicyRule[];
+}
+
+export interface PolicyDecision {
+    action: PolicyAction;
+    reason: string;
+    skillName: string;
+    profileId: string;
+}

package/src/types/reasoning-graph.ts

@@ -0,0 +1,58 @@
+export type ReasoningNodeType = 'entity' | 'fact' | 'task' | 'artifact';
+
+export type ReasoningEdgeRelation =
+  | 'supports'
+  | 'contradicts'
+  | 'depends_on'
+  | 'derived_from';
+
+export interface ReasoningNodeUpsertInput {
+  nodeId: string;
+  claimKey: string;
+  nodeType: ReasoningNodeType;
+  sourceRole: string;
+  canonicalText: string;
+  polarity: 1 | -1;
+  confidence: number;
+  sessionId: string;
+}
+
+export interface ReasoningEdgeUpsertInput {
+  edgeId: string;
+  fromNodeId: string;
+  toNodeId: string;
+  relation: ReasoningEdgeRelation;
+  weight: number;
+  provenance: string;
+}
+
+export interface MemoryProvenanceRow {
+  memoryRowId: number;
+  nodeId: string;
+  claimKey: string;
+  nodeType: ReasoningNodeType;
+  polarity: 1 | -1;
+  canonicalText: string;
+  updatedAt: string;
+  supportsCount: number;
+  contradictsCount: number;
+  dependsCount: number;
+  derivedCount: number;
+}
+
+export interface ReasoningEdgeRow {
+  edgeId: string;
+  fromNodeId: string;
+  toNodeId: string;
+  relation: ReasoningEdgeRelation;
+  weight: number;
+  provenance: string;
+  updatedAt: string;
+}
+
+export interface EvidenceAwareMemoryContext {
+  context: string;
+  diagnostics: string[];
+  conflictCount: number;
+  hitCount: number;
+}

package/src/types/release.ts

@@ -0,0 +1,115 @@
+export type ReleaseCheckId =
+  | 'build'
+  | 'tests'
+  | 'api-health'
+  | 'interface-readiness';
+
+export type ReleaseCheckStatus = 'passed' | 'failed';
+
+export interface ReleaseCheckResult {
+  id: ReleaseCheckId;
+  status: ReleaseCheckStatus;
+  detail: string;
+  command?: string;
+  startedAt: string;
+  completedAt: string;
+  durationMs: number;
+}
+
+export interface PreflightResult {
+  passed: boolean;
+  checks: ReleaseCheckResult[];
+  failedChecks: ReleaseCheckResult[];
+}
+
+export interface SnapshotAssetRecord {
+  key: string;
+  relativePath: string;
+  kind: 'file' | 'directory';
+  exists: boolean;
+  sourcePath: string;
+  snapshotPath: string;
+}
+
+export interface RuntimeSnapshotMetadata {
+  snapshotId: string;
+  releaseId: string;
+  createdAt: string;
+  retentionLimit: number;
+  assets: SnapshotAssetRecord[];
+  metadataPath: string;
+}
+
+export interface ArtifactPointer {
+  id: string;
+  path: string;
+  exists: boolean;
+}
+
+export type ReleaseManifestStatus = 'ready' | 'blocked' | 'rolled_back';
+
+export interface ReleaseManifest {
+  manifestVersion: 1;
+  releaseId: string;
+  generatedAt: string;
+  appVersion: string;
+  gitCommit: string | null;
+  status: ReleaseManifestStatus;
+  preflight: PreflightResult;
+  snapshot?: {
+    snapshotId: string;
+    metadataPath: string;
+  };
+  artifacts: ArtifactPointer[];
+  diagnostics: string[];
+  manifestPath: string;
+}
+
+export interface CommandExecutionResult {
+  ok: boolean;
+  exitCode: number;
+  output: string;
+  durationMs: number;
+}
+
+export type CommandRunner = (command: string, cwd: string) => Promise<CommandExecutionResult>;
+
+export interface HealthProbeResult {
+  ok: boolean;
+  detail: string;
+  statusCode?: number;
+  payloadStatus?: string;
+}
+
+export type HealthProbe = (url: string) => Promise<HealthProbeResult>;
+
+export type RollbackStatus = 'restored' | 'noop' | 'failed';
+
+export interface RollbackResult {
+  status: RollbackStatus;
+  snapshotId: string;
+  startedAt: string;
+  completedAt: string;
+  restoredAssets: string[];
+  skippedAssets: string[];
+  healthCheck: ReleaseCheckResult;
+  diagnostics: string[];
+}
+
+export type DrillStatus = 'passed' | 'failed';
+
+export interface DrillResult {
+  status: DrillStatus;
+  drillId: string;
+  startedAt: string;
+  completedAt: string;
+  simulatedFailure: boolean;
+  snapshotRestored: boolean;
+  preflightResult: PreflightResult | null;
+  rollbackResult: RollbackResult | null;
+  integrityCheck: {
+    passed: boolean;
+    issues: string[];
+  };
+  diagnostics: string[];
+}

package/src/types/reliability.ts

@@ -0,0 +1,43 @@
+/** Delivery lifecycle states for outbound messages in the persistent queue. */
+export type DeliveryState = 'queued' | 'dispatching' | 'sent' | 'failed' | 'dead_letter';
+
+/** A single tracked outbound delivery attempt. */
+export interface DeliveryAttempt {
+    attemptNumber: number;
+    startedAt: string;
+    completedAt?: string;
+    error?: string;
+    durationMs?: number;
+}
+
+/** Full delivery record for a single outbound message. */
+export interface DeliveryRecord {
+    id: string;
+    platform: string;
+    chatId: string | number;
+    textPayload: string;
+    state: DeliveryState;
+    attempts: DeliveryAttempt[];
+    createdAt: string;
+    nextAttemptAt?: string;
+    resolvedAt?: string;
+}
+
+/** Summary telemetry counters for reliability reporting. */
+export interface ReliabilityMetrics {
+    totalSent: number;
+    totalFailed: number;
+    totalRetries: number;
+    averageAttempts: number;
+    /** Delivery records for the most recent N sends. */
+    recentRecords: DeliveryRecord[];
+}
+
+/** Callback reconciliation payload from an async interface operation. */
+export interface CallbackReconciliation {
+    taskId: string;
+    platform: string;
+    status: 'delivered' | 'failed' | 'expired';
+    detail?: string;
+    reconciledAt: string;
+}

package/src/types/runtime-budget.ts

@@ -0,0 +1,85 @@
+export type RuntimeBudgetProfile = 'economy' | 'balanced' | 'performance';
+
+export type RuntimeBudgetSeverity = 'ok' | 'warning' | 'hard_limit';
+
+export type RuntimeBudgetAction =
+  | 'none'
+  | 'intelligent_pacing'
+  | 'provider_cooldown'
+  | 'fallback_tightening'
+  | 'prefer_local_model';
+
+export type RuntimeUsageStage = 'success' | 'failure' | 'skipped';
+
+export interface RuntimeBudgetLimits {
+  dailyRequestLimit: number;
+  dailyTokenLimit: number;
+  sessionRequestLimit: number;
+  sessionTokenLimit: number;
+  providerRequestLimit: number;
+  providerTokenLimit: number;
+  warningRatio: number;
+  warningPacingMs: number;
+  hardLimitPacingMs: number;
+  providerCooldownMs: number;
+}
+
+export interface RuntimeUsageAggregate {
+  requestCount: number;
+  requestTokens: number;
+  responseTokens: number;
+  failureCount: number;
+  skippedCount: number;
+}
+
+export interface RuntimeProviderUsageAggregate extends RuntimeUsageAggregate {
+  providerId: string;
+}
+
+export interface RuntimeBudgetDirective {
+  profile: RuntimeBudgetProfile;
+  severity: RuntimeBudgetSeverity;
+  actions: RuntimeBudgetAction[];
+  pacingDelayMs: number;
+  blockedModelIds: string[];
+  blockedProviders: string[];
+  reason: string;
+  evaluatedAt: string;
+}
+
+export interface RuntimeBudgetEvent {
+  id: string;
+  sessionId: string | null;
+  severity: RuntimeBudgetSeverity;
+  profile: RuntimeBudgetProfile;
+  action: RuntimeBudgetAction;
+  reason: string;
+  detail: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface RuntimeBudgetSnapshot {
+  sessionId: string;
+  manualProfile: RuntimeBudgetProfile | null;
+  limits: RuntimeBudgetLimits;
+  daily: RuntimeUsageAggregate;
+  session: RuntimeUsageAggregate;
+  providers: RuntimeProviderUsageAggregate[];
+  directive: RuntimeBudgetDirective;
+  recentEvents: RuntimeBudgetEvent[];
+}
+
+export interface RuntimeUsageEvent {
+  id: string;
+  sessionId: string | null;
+  modelId: string;
+  providerId: string;
+  profile: RuntimeBudgetProfile;
+  stage: RuntimeUsageStage;
+  requestTokens: number;
+  responseTokens: number;
+  latencyMs: number;
+  statusCode: number | null;
+  error: string | null;
+  createdAt: string;
+}

package/src/types/scheduler.ts

@@ -0,0 +1,47 @@
+/** Status of a registered scheduled job. */
+export type JobStatus = 'idle' | 'running' | 'stopped' | 'error';
+
+/** Configuration required to register a new repeating job. */
+export interface JobConfig {
+    /** Unique human-readable identifier for this job (e.g. 'daily-heartbeat'). */
+    id: string;
+    /** A cron expression defining the schedule (node-cron format). */
+    cronExpression: string;
+    /** Human-readable description of what this job does. */
+    description: string;
+    /** The async callback to execute on each tick. */
+    handler: () => Promise<void> | void;
+    /**
+     * If true, the job will start immediately upon registration.
+     * @default true
+     */
+    autoStart?: boolean;
+}
+
+/** Read-only snapshot of a registered job's state. */
+export interface JobSnapshot {
+    id: string;
+    cronExpression: string;
+    description: string;
+    status: JobStatus;
+    lastRunAt: Date | null;
+    lastError: string | null;
+}
+
+/**
+ * Event types emitted by the job scheduler.
+ * - 'job:start'  — fired just before a job handler executes.
+ * - 'job:done'   — fired after a job handler completes successfully.
+ * - 'job:error'  — fired when a job handler throws.
+ */
+export type SchedulerEventType = 'job:start' | 'job:done' | 'job:error';
+
+export interface SchedulerEvent {
+    type: SchedulerEventType;
+    jobId: string;
+    timestamp: Date;
+    error?: string;
+}
+
+/** Callback signature for scheduler event listeners. */
+export type SchedulerEventListener = (event: SchedulerEvent) => void;