twinclaw 1.0.0

package/src/types/secret-vault.ts

@@ -0,0 +1,62 @@
+export type SecretScope = 'api' | 'model' | 'messaging' | 'runtime' | 'storage' | 'integration';
+
+export type SecretSource = 'env' | 'vault' | 'runtime';
+
+export type SecretLifecycleStatus = 'active' | 'revoked' | 'expired';
+
+export interface SecretMetadata {
+  name: string;
+  scope: SecretScope;
+  source: SecretSource;
+  required: boolean;
+  rotationWindowHours: number;
+  warningWindowHours: number;
+  lastRotatedAt: string | null;
+  expiresAt: string | null;
+  revokedAt: string | null;
+  status: SecretLifecycleStatus;
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SecretSetInput {
+  name: string;
+  value: string;
+  scope?: SecretScope;
+  source?: SecretSource;
+  required?: boolean;
+  rotationWindowHours?: number;
+  warningWindowHours?: number;
+  expiresAt?: string | null;
+}
+
+export interface SecretRotateInput {
+  name: string;
+  nextValue: string;
+  reason?: string;
+  rotationWindowHours?: number;
+  warningWindowHours?: number;
+  expiresAt?: string | null;
+}
+
+export interface SecretRevokeInput {
+  name: string;
+  reason?: string;
+}
+
+export interface SecretHealthReport {
+  missingRequired: string[];
+  expired: string[];
+  warnings: string[];
+  hasIssues: boolean;
+}
+
+export interface SecretDiagnostics {
+  health: SecretHealthReport;
+  total: number;
+  active: number;
+  revoked: number;
+  expired: number;
+  dueForRotation: string[];
+}

package/src/types/skill-packages.ts

@@ -0,0 +1,81 @@
+import type { McpServerConfig } from './mcp.js';
+
+export interface SkillPackageMetadata {
+  displayName: string;
+  description: string;
+  deprecated?: boolean;
+  deprecationMessage?: string;
+}
+
+export interface SkillPackageCompatibility {
+  node?: string;
+  runtimeApi?: string;
+  requiredTools?: string[];
+}
+
+export interface SkillPackageManifest {
+  name: string;
+  version: string;
+  metadata: SkillPackageMetadata;
+  dependencies?: Record<string, string>;
+  compatibility?: SkillPackageCompatibility;
+  server: McpServerConfig;
+}
+
+export interface SkillPackageCatalog {
+  packages: SkillPackageManifest[];
+}
+
+export interface SkillPackageLockEntry {
+  name: string;
+  version: string;
+  dependencies: Record<string, string>;
+  checksum: string;
+  integrity: string;
+  installedAt: string;
+}
+
+export interface SkillPackageLockfile {
+  version: 1;
+  generatedAt: string;
+  packages: Record<string, SkillPackageLockEntry>;
+}
+
+export type SkillPackageViolationCode =
+  | 'missing-manifest'
+  | 'version-conflict'
+  | 'node-incompatible'
+  | 'runtime-api-incompatible'
+  | 'missing-required-tool'
+  | 'missing-dependency'
+  | 'duplicate-server-id';
+
+export interface SkillPackageViolation {
+  packageName: string;
+  version: string;
+  code: SkillPackageViolationCode;
+  message: string;
+  remediation: string;
+}
+
+export interface SkillPackageDiagnostics {
+  installed: SkillPackageLockEntry[];
+  warnings: string[];
+  violations: SkillPackageViolation[];
+  activePackageCount: number;
+  blockedPackageCount: number;
+}
+
+export interface SkillPackageActivationPlan {
+  servers: McpServerConfig[];
+  diagnostics: SkillPackageDiagnostics;
+}
+
+export interface SkillPackageMutationResult {
+  action: 'install' | 'upgrade' | 'uninstall';
+  packageName: string;
+  version?: string;
+  changed: boolean;
+  diagnostics: SkillPackageDiagnostics;
+}
+

package/src/types/sqlite-vec.d.ts

@@ -0,0 +1,5 @@
+declare module 'sqlite-vec' {
+    import { Database } from 'better-sqlite3';
+    export function load(db: Database): void;
+    export function serializeFloat32(value: number[]): Uint8Array;
+}

package/src/types/websocket.ts

@@ -0,0 +1,122 @@
+// ── Close Codes ────────────────────────────────────────────────────────────────
+
+/** Deterministic close codes for WebSocket control-plane lifecycle events. */
+export const WsCloseCode = {
+    /** Authentication token missing or invalid. */
+    AuthFailed: 4001,
+    /** Client did not complete auth handshake within the required window. */
+    AuthRequired: 4002,
+    /** Subscription request contains an unrecognised topic. */
+    InvalidSubscription: 4003,
+    /** Client failed to respond to ping heartbeats (stale). */
+    StaleConnection: 4004,
+    /** Server is shutting down gracefully. */
+    ServerShutdown: 4005,
+} as const;
+
+export type WsCloseCode = (typeof WsCloseCode)[keyof typeof WsCloseCode];
+
+// ── Event Topics ───────────────────────────────────────────────────────────────
+
+/** All subscribable runtime event topics. */
+export type WsEventTopic = 'health' | 'reliability' | 'incidents' | 'routing';
+
+// ── Inbound Messages (client → server) ────────────────────────────────────────
+
+/** First message a client MUST send to authenticate the session. */
+export interface WsAuthMessage {
+    type: 'auth';
+    /** Must equal the configured API_SECRET. */
+    token: string;
+}
+
+/** Subscribe to one or more event topics (sent after auth_ok). */
+export interface WsSubscribeMessage {
+    type: 'subscribe';
+    topics: WsEventTopic[];
+}
+
+/** Client-initiated ping to keep the connection alive. */
+export interface WsPingMessage {
+    type: 'ping';
+}
+
+export type WsInboundMessage = WsAuthMessage | WsSubscribeMessage | WsPingMessage;
+
+// ── Outbound Messages (server → client) ────────────────────────────────────────
+
+/** Sent after a successful authentication handshake. */
+export interface WsAuthOkMessage {
+    type: 'auth_ok';
+    clientId: string;
+    ts: string;
+}
+
+/** Acknowledgement for a successful subscription request. */
+export interface WsSubscribedMessage {
+    type: 'subscribed';
+    topics: WsEventTopic[];
+    ts: string;
+}
+
+/** Server-originated error notification. */
+export interface WsErrorMessage {
+    type: 'error';
+    code: number;
+    message: string;
+    ts: string;
+}
+
+/** Response to a client ping. */
+export interface WsPongMessage {
+    type: 'pong';
+    ts: string;
+}
+
+// ── Event Envelope ─────────────────────────────────────────────────────────────
+
+/**
+ * Versioned, typed wrapper for all runtime state update events.
+ *
+ * Every event emitted over the WebSocket channel is wrapped in this envelope
+ * so consumers can version-check, sequence, and timestamp inbound frames.
+ */
+export interface WsEventEnvelope<T = unknown> {
+    type: 'event';
+    /** Schema version — increment when the envelope shape changes. */
+    v: 1;
+    topic: WsEventTopic;
+    /** Monotonically increasing sequence number per hub instance. */
+    seq: number;
+    /** ISO-8601 server-side emission timestamp. */
+    ts: string;
+    payload: T;
+}
+
+// ── Snapshot Payload ───────────────────────────────────────────────────────────
+
+/**
+ * Initial full-state snapshot dispatched to a client immediately after it
+ * subscribes. Only topics the client subscribed to are populated.
+ */
+export interface WsSnapshotPayload {
+    type: 'snapshot';
+    v: 1;
+    ts: string;
+    health?: unknown;
+    reliability?: unknown;
+    incidents?: unknown;
+    routing?: unknown;
+}
+
+// ── Hub Diagnostics ────────────────────────────────────────────────────────────
+
+/** Operator-facing metrics for the WebSocket hub. */
+export interface WsHubMetrics {
+    activeClients: number;
+    totalConnections: number;
+    authFailures: number;
+    droppedEvents: number;
+    staleCleaned: number;
+    lastEventAt: string | null;
+}