twinclaw 1.0.0

package/src/types/api.ts

@@ -0,0 +1,252 @@
+import type { IncidentRecord, IncidentTimelineEntry } from './incident.js';
+import type {
+    PersonaStateSnapshot,
+    PersonaStateUpdateResult,
+} from './persona-state.js';
+import type {
+    LocalStateBackupDiagnostics,
+    LocalStateRestoreRequest,
+    LocalStateRestoreResult,
+    LocalStateSnapshotManifest,
+} from './local-state-backup.js';
+import type {
+    RuntimeBudgetAction,
+    RuntimeBudgetEvent,
+    RuntimeBudgetLimits,
+    RuntimeBudgetProfile,
+    RuntimeBudgetSeverity,
+    RuntimeUsageAggregate,
+    RuntimeProviderUsageAggregate,
+} from './runtime-budget.js';
+import type { ModelRoutingFallbackMode, ModelRoutingTelemetrySnapshot } from './model-routing.js';
+
+export interface ApiEnvelope<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+    correlationId?: string;
+    timestamp: string;
+}
+
+// ── Config / Env Validation ──────────────────────────────────────────────────
+
+export interface ConfigIssueData {
+    key: string;
+    class: 'missing_required' | 'missing_conditional' | 'format_error';
+    message: string;
+    remediation: string;
+}
+
+export interface ConfigValidationData {
+    ok: boolean;
+    presentKeys: string[];
+    issues: ConfigIssueData[];
+    activeFeatures: string[];
+    fatalIssues: ConfigIssueData[];
+    validatedAt: string;
+}
+
+// ── Health ──────────────────────────────────────────────────────────────────
+
+export interface HealthData {
+    status: 'ok' | 'degraded';
+    uptimeSec: number;
+    memoryUsageMb: number;
+    heartbeat: { running: boolean };
+    skills: { builtin: number; mcp: number; total: number };
+    skillPackages: {
+        installed: number;
+        active: number;
+        blocked: number;
+        warnings: string[];
+        violations: Array<{
+            packageName: string;
+            version: string;
+            code: string;
+            message: string;
+            remediation: string;
+        }>;
+    };
+    secrets?: {
+        status: 'ok' | 'degraded';
+        missingRequired: string[];
+        expired: string[];
+        warnings: string[];
+        total: number;
+        active: number;
+        dueForRotation: string[];
+    };
+    budget?: {
+        severity: RuntimeBudgetSeverity;
+        profile: RuntimeBudgetProfile;
+        pacingDelayMs: number;
+        manualProfile: RuntimeBudgetProfile | null;
+        daily: RuntimeUsageAggregate;
+        session: RuntimeUsageAggregate;
+        providers: RuntimeProviderUsageAggregate[];
+    };
+    routing?: ModelRoutingTelemetrySnapshot;
+    backups?: {
+        status: 'ok' | 'degraded';
+        lastSnapshotAt: string | null;
+        lastRestoreAt: string | null;
+        validationFailureCount: number;
+        recommendationCount: number;
+    };
+    mcpServers: Array<{
+        id: string;
+        name: string;
+        state: string;
+        toolCount: number;
+        health?: {
+            circuit: string;
+            failureCount: number;
+            remainingCooldownMs: number;
+        };
+    }>;
+}
+
+// ── Browser ─────────────────────────────────────────────────────────────────
+
+export interface BrowserSnapshotRequest {
+    url?: string;
+    fullPage?: boolean;
+}
+
+export interface BrowserReferenceMapEntry {
+    ref: string;
+    selector: string;
+    role: string;
+    name: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+
+export interface BrowserSnapshotData {
+    snapshotId: string;
+    screenshotPath: string;
+    viewport: { width: number; height: number };
+    accessibilityTree: string;
+    references: BrowserReferenceMapEntry[];
+}
+
+export interface BrowserClickRequest {
+    ref?: string;
+    snapshotId?: string;
+    selector?: string;
+    x?: number;
+    y?: number;
+}
+
+export interface BrowserClickData {
+    clicked: true;
+    method: 'reference' | 'selector' | 'coordinates';
+    detail: string;
+    ref?: string;
+    snapshotId?: string;
+}
+
+// ── Webhook Callback ────────────────────────────────────────────────────────
+
+export interface WebhookCallbackPayload {
+    eventType: string;
+    taskId: string;
+    status: 'completed' | 'failed' | 'progress';
+    result?: unknown;
+    error?: string;
+}
+
+export interface WebhookCallbackData {
+    accepted: true;
+    eventType: string;
+    taskId: string;
+    outcome?: 'accepted' | 'duplicate';
+}
+
+// ── Incident Self-Healing ────────────────────────────────────────────────────
+
+export interface IncidentCurrentData {
+    safeMode: boolean;
+    incidents: IncidentRecord[];
+}
+
+export interface IncidentHistoryData {
+    incidents: IncidentRecord[];
+    timeline: IncidentTimelineEntry[];
+}
+
+// ── Persona State ─────────────────────────────────────────────────────────────
+
+export type PersonaStateData = PersonaStateSnapshot;
+
+export interface PersonaStateUpdateRequest {
+    expectedRevision: string;
+    soul: string;
+    identity: string;
+    user: string;
+}
+
+export type PersonaStateUpdateData = PersonaStateUpdateResult;
+
+export interface PersonaStateErrorDiagnostics {
+    hints: string[];
+    latestRevision?: string;
+}
+
+// ── Local State Backup & Recovery ─────────────────────────────────────────────
+
+export interface LocalStateSnapshotRequest {
+    retentionLimit?: number;
+}
+
+export interface LocalStateSnapshotData {
+    snapshot: LocalStateSnapshotManifest;
+}
+
+export interface LocalStateRestoreData {
+    request: LocalStateRestoreRequest;
+    result: LocalStateRestoreResult;
+}
+
+export interface LocalStateBackupDiagnosticsData {
+    diagnostics: LocalStateBackupDiagnostics;
+}
+
+// ── Runtime Budget Governance ────────────────────────────────────────────────
+
+export interface BudgetStateData {
+    sessionId: string;
+    manualProfile: RuntimeBudgetProfile | null;
+    limits: RuntimeBudgetLimits;
+    daily: RuntimeUsageAggregate;
+    session: RuntimeUsageAggregate;
+    providers: RuntimeProviderUsageAggregate[];
+    directive: {
+        profile: RuntimeBudgetProfile;
+        severity: RuntimeBudgetSeverity;
+        actions: RuntimeBudgetAction[];
+        pacingDelayMs: number;
+        blockedModelIds: string[];
+        blockedProviders: string[];
+        reason: string;
+        evaluatedAt: string;
+    };
+    recentEvents: RuntimeBudgetEvent[];
+}
+
+// ── Model Routing Telemetry ───────────────────────────────────────────────────
+
+export type RoutingTelemetryData = ModelRoutingTelemetrySnapshot;
+
+export interface RoutingModeUpdateRequest {
+    mode: ModelRoutingFallbackMode;
+}
+
+export interface RoutingModeUpdateData {
+    message: string;
+    snapshot: ModelRoutingTelemetrySnapshot;
+}

package/src/types/blessed-contrib.d.ts

@@ -0,0 +1,4 @@
+declare module 'blessed-contrib' {
+    const contrib: any;
+    export default contrib;
+}

package/src/types/context-budget.ts

@@ -0,0 +1,76 @@
+import type { Message } from '../core/types.js';
+
+export interface ContextBudgetConfig {
+  totalBudgetTokens: number;
+  systemBudgetTokens: number;
+  historyBudgetTokens: number;
+  memoryBudgetTokens: number;
+  delegationBudgetTokens: number;
+  lifecycleBudgetTokens: number;
+  hotMessageLimit: number;
+  warmMessageLimit: number;
+  memoryTopKMin: number;
+  memoryTopKMax: number;
+  tokensPerMemoryItem: number;
+  maxSummaryEntries: number;
+  summarySnippetChars: number;
+}
+
+export interface IndexedConversationMessage {
+  index: number;
+  message: Message;
+}
+
+export interface ContextSectionResult {
+  label: string;
+  content: string;
+  originalTokens: number;
+  usedTokens: number;
+  wasCompacted: boolean;
+  wasOmitted: boolean;
+  note?: string;
+}
+
+export interface ContextHistoryStats {
+  totalHistoryMessages: number;
+  hotMessages: number;
+  warmMessages: number;
+  archivedMessages: number;
+  hotTokens: number;
+  warmSummaryTokens: number;
+  archivedSummaryTokens: number;
+  historyBudgetTokens: number;
+  memoryBudgetTokens: number;
+  memoryTopK: number;
+  wasCompacted: boolean;
+}
+
+export interface ContextHistoryPlan {
+  hotHistory: Message[];
+  warmSummary: string;
+  archivedSummary: string;
+  memoryTopK: number;
+  diagnostics: string[];
+  stats: ContextHistoryStats;
+}
+
+export interface RuntimeContextStats {
+  memoryTokens: number;
+  delegationTokens: number;
+  warmTokens: number;
+  archivedTokens: number;
+  totalTokens: number;
+  wasCompacted: boolean;
+}
+
+export interface RuntimeContextPlan {
+  runtimeContext: string;
+  diagnostics: string[];
+  sections: {
+    memory: ContextSectionResult;
+    delegation: ContextSectionResult;
+    warm: ContextSectionResult;
+    archived: ContextSectionResult;
+  };
+  stats: RuntimeContextStats;
+}

package/src/types/doctor.ts

@@ -0,0 +1,29 @@
+export type DoctorCheckKind = 'binary' | 'env-var' | 'filesystem' | 'service-endpoint' | 'channel-auth' | 'config-schema';
+
+export type DoctorSeverity = 'critical' | 'warning' | 'info';
+
+export interface DoctorCheck {
+  kind: DoctorCheckKind;
+  name: string;
+  description: string;
+  severity: DoctorSeverity;
+  remediation: string;
+}
+
+export interface DoctorCheckResult {
+  check: DoctorCheck;
+  passed: boolean;
+  /** Masked or descriptive actual value when relevant. */
+  actual?: string;
+  message: string;
+}
+
+export type DoctorStatus = 'ok' | 'degraded' | 'critical';
+
+export interface DoctorReport {
+  status: DoctorStatus;
+  results: DoctorCheckResult[];
+  checkedAt: string;
+  passed: number;
+  failed: number;
+}

package/src/types/file-watcher.ts

@@ -0,0 +1,26 @@
+/** Types of filesystem changes the watcher emits. */
+export type FileEventType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir';
+
+/** Normalized filesystem event payload. */
+export interface FileEvent {
+    type: FileEventType;
+    /** Absolute path of the affected file or directory. */
+    path: string;
+    /** ISO-8601 timestamp when the event was detected. */
+    timestamp: string;
+}
+
+/** Callback invoked when a watched filesystem event occurs. */
+export type FileEventListener = (event: FileEvent) => Promise<void> | void;
+
+/** Configuration for a watched directory entry. */
+export interface WatchTarget {
+    /** Unique label for this watch (e.g. 'workspace', 'identity'). */
+    id: string;
+    /** Absolute path to the directory to monitor. */
+    directory: string;
+    /** Glob patterns to include. If omitted, all files are watched. */
+    include?: string[];
+    /** Glob patterns to exclude (e.g. 'node_modules/**'). */
+    exclude?: string[];
+}

package/src/types/incident.ts

@@ -0,0 +1,57 @@
+export type IncidentType =
+  | 'queue_backpressure'
+  | 'callback_failure_storm'
+  | 'context_budget_degradation'
+  | 'model_routing_instability';
+
+export type IncidentSeverity = 'warning' | 'critical';
+
+export type IncidentStatus = 'active' | 'remediating' | 'escalated' | 'resolved';
+
+export type IncidentRemediationAction =
+  | 'none'
+  | 'throttle'
+  | 'drain'
+  | 'failover'
+  | 'retry_window_adjustment'
+  | 'halt_safe_mode';
+
+export interface IncidentEvidence {
+  signal: string;
+  observedValue: number;
+  threshold: number;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IncidentRecord {
+  id: string;
+  incidentType: IncidentType;
+  severity: IncidentSeverity;
+  status: IncidentStatus;
+  summary: string;
+  evidence: IncidentEvidence[];
+  remediationAction: IncidentRemediationAction;
+  remediationAttempts: number;
+  cooldownUntil: string | null;
+  escalated: boolean;
+  recommendedActions: string[];
+  createdAt: string;
+  updatedAt: string;
+  resolvedAt: string | null;
+}
+
+export interface IncidentTimelineEntry {
+  id: string;
+  incidentId: string;
+  incidentType: IncidentType;
+  eventType: string;
+  detail: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface CallbackOutcomeCounts {
+  accepted: number;
+  duplicate: number;
+  rejected: number;
+}

package/src/types/local-state-backup.ts

@@ -0,0 +1,121 @@
+import type { JobSnapshot } from './scheduler.js';
+
+export type LocalStateBackupTrigger = 'manual' | 'scheduled';
+
+export type LocalStateBackupScope =
+  | 'identity'
+  | 'memory'
+  | 'runtime-db'
+  | 'config'
+  | 'policy-profiles'
+  | 'mcp-config'
+  | 'skill-packages';
+
+export type LocalStateEntryKind = 'file' | 'directory';
+
+export type LocalStateRestoreStatus = 'dry-run' | 'restored' | 'failed';
+
+export interface LocalStateSnapshotEntry {
+  id: string;
+  scope: LocalStateBackupScope;
+  relativePath: string;
+  kind: LocalStateEntryKind;
+  exists: boolean;
+  checksum: string | null;
+  fileCount: number;
+  byteSize: number;
+}
+
+export interface LocalStateSnapshotManifest {
+  manifestVersion: 1;
+  snapshotId: string;
+  trigger: LocalStateBackupTrigger;
+  createdAt: string;
+  retentionLimit: number;
+  entries: LocalStateSnapshotEntry[];
+}
+
+export interface LocalStateSnapshotRecord {
+  snapshotId: string;
+  trigger: LocalStateBackupTrigger;
+  status: 'ready' | 'failed' | 'pruned';
+  scopes: LocalStateBackupScope[];
+  entryCount: number;
+  manifestPath: string;
+  checksum: string | null;
+  detail: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface LocalStateValidationIssue {
+  entryId: string;
+  message: string;
+}
+
+export interface LocalStateValidationResult {
+  snapshotId: string;
+  scopes: LocalStateBackupScope[];
+  entries: LocalStateSnapshotEntry[];
+  issues: LocalStateValidationIssue[];
+}
+
+export interface LocalStateRestoreOptions {
+  snapshotId?: string;
+  dryRun?: boolean;
+  scopes?: LocalStateBackupScope[];
+}
+
+export interface LocalStateRestoreResult {
+  status: LocalStateRestoreStatus;
+  snapshotId: string;
+  dryRun: boolean;
+  scopes: LocalStateBackupScope[];
+  restoredPaths: string[];
+  skippedPaths: string[];
+  validationErrors: string[];
+  rollbackApplied: boolean;
+  startedAt: string;
+  completedAt: string;
+}
+
+export interface LocalStateRestoreEvent {
+  id: string;
+  snapshotId: string | null;
+  outcome: LocalStateRestoreStatus;
+  dryRun: boolean;
+  scopes: LocalStateBackupScope[];
+  restoredPaths: string[];
+  skippedPaths: string[];
+  validationErrors: string[];
+  rollbackApplied: boolean;
+  detail: string | null;
+  createdAt: string;
+}
+
+export interface LocalStateBackupDiagnostics {
+  status: 'ok' | 'degraded';
+  scheduler: {
+    enabled: boolean;
+    jobId: string;
+    job: JobSnapshot | null;
+    cronExpression: string;
+  };
+  lastSnapshotAt: string | null;
+  lastRestoreAt: string | null;
+  validationFailureCount: number;
+  snapshots: LocalStateSnapshotRecord[];
+  restoreEvents: LocalStateRestoreEvent[];
+  recommendations: string[];
+}
+
+export interface LocalStateSnapshotRequest {
+  retentionLimit?: number;
+}
+
+export interface LocalStateRestoreRequest {
+  snapshotId?: string;
+  dryRun?: boolean;
+  scopes?: LocalStateBackupScope[];
+}
+

package/src/types/mcp.ts

@@ -0,0 +1,106 @@
+import type { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+
+/** JSON Schema object for describing tool parameters. */
+export interface JsonSchema {
+    type: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    description?: string;
+    items?: JsonSchema;
+    enum?: string[];
+    default?: unknown;
+    [key: string]: unknown;
+}
+
+/** Capability scope limiting the operations an MCP tool can perform. */
+export type McpCapabilityScope = 'read-only' | 'write-limited' | 'high-risk' | 'unclassified';
+
+/** Configuration for capability scopes on an MCP server. */
+export interface McpServerCapabilities {
+    /** Default scope for tools that aren't explicitly configured. @default 'unclassified' -> blocks by default */
+    defaultScope?: McpCapabilityScope;
+    /** Map of explicit tool names to their granted capability scope. */
+    tools?: Record<string, McpCapabilityScope>;
+}
+
+/** Transport mechanism for connecting to an MCP server. */
+export type McpTransportType = 'stdio' | 'sse';
+
+/** Configuration for a single MCP server connection. */
+export interface McpServerConfig {
+    /** Unique identifier for this server (e.g. 'github', 'filesystem'). */
+    id: string;
+    /** Human-readable name for display. */
+    name: string;
+    /** Description of what this server provides. */
+    description: string;
+    /** Transport type. Currently only 'stdio' is implemented. */
+    transport: McpTransportType;
+    /** Command to launch the server (e.g. 'npx', 'node'). */
+    command: string;
+    /** Arguments to pass to the command. */
+    args: string[];
+    /** Optional environment variables to set for the subprocess. */
+    env?: Record<string, string>;
+    /** Whether to auto-connect this server on startup. @default true */
+    autoConnect?: boolean;
+    /** Whether this server is currently enabled. @default true */
+    enabled?: boolean;
+    /** Explicit capability scopes for this server. */
+    capabilities?: McpServerCapabilities;
+}
+
+/** Top-level configuration file shape for MCP servers. */
+export interface McpConfig {
+    servers: McpServerConfig[];
+}
+
+/** Represents a tool discovered from an MCP server. */
+export interface McpDiscoveredTool {
+    /** Which MCP server this tool came from. */
+    serverId: string;
+    /** The raw MCP tool metadata from list_tools(). */
+    mcpTool: McpTool;
+}
+
+/** Connection state for an MCP server. */
+export type McpConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+/** Health circuit state for an MCP server. */
+export type McpCircuitState = 'closed' | 'open' | 'half-open';
+
+/** Health metrics for an MCP server. */
+export interface McpHealthMetrics {
+    failureCount: number;
+    latencySpikes: number;
+    timeoutCount: number;
+    lastFailureTime: string | null;
+    consecutiveSuccesses: number;
+}
+
+/** Read-only snapshot of an MCP server's health. */
+export interface McpHealthSnapshot {
+    state: McpCircuitState;
+    metrics: McpHealthMetrics;
+    remainingCooldownMs: number;
+}
+
+/** Read-only snapshot of an MCP server's status. */
+export interface McpServerSnapshot {
+    id: string;
+    name: string;
+    state: McpConnectionState;
+    toolCount: number;
+    lastError: string | null;
+    health: McpHealthSnapshot;
+}
+
+/**
+ * Minimal audit interface for MCP scope enforcement.
+ * Implemented by McpClientAdapter — typed here to break the circular dependency
+ * between lane-executor/skills and the services layer.
+ */
+export interface McpScopeAuditAdapter {
+    auditScopeBlock(sessionId: string | null, toolName: string, scope: string, reason: string): void;
+    auditScopeAllow(sessionId: string | null, toolName: string, scope: string): void;
+}