cognitive-modules 0.6.0

package/src/types.ts

@@ -0,0 +1,184 @@
+/**
+ * Cognitive Runtime - Core Types
+ * Version 2.1 - With envelope format, tools policy, failure contract
+ */
+
+// Provider interface - all LLM providers implement this
+export interface Provider {
+  name: string;
+  invoke(params: InvokeParams): Promise<InvokeResult>;
+  isConfigured(): boolean;
+}
+
+export interface InvokeParams {
+  messages: Message[];
+  jsonSchema?: object;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface InvokeResult {
+  content: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+// Module types (v2.1)
+export interface CognitiveModule {
+  // Core identity
+  name: string;
+  version: string;
+  responsibility: string;
+  
+  // Constraints
+  excludes: string[];
+  constraints?: ModuleConstraints;
+  
+  // Unified policies (v2.1)
+  policies?: ModulePolicies;
+  
+  // Tools policy
+  tools?: ToolsPolicy;
+  
+  // Output contract
+  output?: OutputContract;
+  
+  // Failure contract
+  failure?: FailureContract;
+  
+  // Runtime requirements
+  runtimeRequirements?: RuntimeRequirements;
+  
+  // Execution context
+  context?: 'fork' | 'main';
+  
+  // Prompt (from prompt.md or MODULE.md body)
+  prompt: string;
+  
+  // Schemas
+  inputSchema?: object;
+  outputSchema?: object;
+  errorSchema?: object;
+  
+  // Metadata
+  location: string;
+  format: 'v1' | 'v2';  // v1 = MODULE.md, v2 = module.yaml + prompt.md
+}
+
+export interface ModuleConstraints {
+  no_network?: boolean;
+  no_side_effects?: boolean;
+  no_file_write?: boolean;
+  no_inventing_data?: boolean;
+  behavior_equivalence_false_max_confidence?: number;
+}
+
+export interface ModulePolicies {
+  network?: 'allow' | 'deny';
+  filesystem_write?: 'allow' | 'deny';
+  side_effects?: 'allow' | 'deny';
+  code_execution?: 'allow' | 'deny';
+}
+
+export interface ToolsPolicy {
+  policy?: 'allow_by_default' | 'deny_by_default';
+  allowed: string[];
+  denied?: string[];
+}
+
+export interface OutputContract {
+  format?: 'json_strict' | 'json_lenient' | 'text';
+  envelope?: boolean;  // v2.1: Use {ok, data/error} wrapper
+  require?: string[];
+  require_confidence?: boolean;
+  require_rationale?: boolean;
+  require_behavior_equivalence?: boolean;
+}
+
+export interface FailureContract {
+  contract?: 'error_union' | 'throw';
+  partial_allowed?: boolean;
+  must_return_error_schema?: boolean;
+  schema?: object;
+}
+
+export interface RuntimeRequirements {
+  structured_output?: boolean;
+  max_input_tokens?: number;
+  preferred_capabilities?: string[];
+}
+
+// Envelope response format (v2.1)
+export interface EnvelopeSuccess<T = unknown> {
+  ok: true;
+  data: T;
+}
+
+export interface EnvelopeError {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+  };
+  partial_data?: unknown;
+}
+
+export type EnvelopeResponse<T = unknown> = EnvelopeSuccess<T> | EnvelopeError;
+
+// Module result types
+export interface ModuleResultData {
+  [key: string]: unknown;
+  confidence: number;
+  rationale: string;
+  behavior_equivalence?: boolean;
+}
+
+export interface ModuleResult {
+  ok: boolean;
+  data?: ModuleResultData;
+  error?: {
+    code: string;
+    message: string;
+  };
+  partial_data?: unknown;
+  raw?: string;
+}
+
+// Legacy result format (for backward compatibility)
+export interface LegacyModuleResult {
+  output: unknown;
+  confidence: number;
+  rationale: string;
+  behaviorEquivalence?: boolean;
+  raw?: string;
+}
+
+// Command types
+export interface CommandContext {
+  cwd: string;
+  provider: Provider;
+  verbose?: boolean;
+}
+
+export interface CommandResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+
+// Module input (clean, no CLI pollution)
+export interface ModuleInput {
+  code?: string;
+  query?: string;
+  language?: string;
+  options?: Record<string, unknown>;
+  [key: string]: unknown;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}