@causyne/agent 1.10.12 → 1.10.17

package/src/types/contracts.ts

@@ -0,0 +1,263 @@
+/**
+ * Shared compile-time contracts for the incremental TypeScript migration.
+ *
+ * This module deliberately exports types only. Runtime data entering from a
+ * model, MCP server, plugin, config file, subprocess, or filesystem still has
+ * to be validated before it is treated as one of these shapes.
+ */
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type JsonObject = { [key: string]: JsonValue };
+
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface TextContentBlock {
+  type: 'text';
+  text: string;
+}
+
+export interface ImageContentBlock {
+  type: 'image_url';
+  image_url: {
+    url: string;
+    detail?: 'auto' | 'low' | 'high';
+  };
+}
+
+export interface AudioContentBlock {
+  type: 'input_audio';
+  input_audio: {
+    data: string;
+    format: string;
+  };
+}
+
+export type MessageContent = string | Array<TextContentBlock | ImageContentBlock | AudioContentBlock | JsonObject>;
+
+export interface AgentMessage {
+  role: MessageRole;
+  content: MessageContent;
+  name?: string;
+  tool_call_id?: string;
+  cacheAnchor?: string;
+  spillPath?: string;
+}
+
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens?: number;
+}
+
+export interface ProviderResponse {
+  content: string;
+  usage: TokenUsage;
+  reasoning?: string;
+  toolCalls?: ToolCall[];
+}
+
+export interface ProviderChatOptions {
+  temperature?: number;
+  maxTokens?: number;
+  jsonMode?: boolean;
+  tools?: ToolSchema[];
+  signal?: AbortSignal;
+}
+
+export interface JsonSchema {
+  type?: string | string[];
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: JsonPrimitive[];
+  additionalProperties?: boolean | JsonSchema;
+}
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  parameters: JsonSchema;
+}
+
+export interface ToolCall {
+  id?: string;
+  name: string;
+  arguments: JsonObject;
+}
+
+export interface ToolExecutionContext {
+  workspace: string;
+  signal?: AbortSignal;
+  taskId?: string;
+  sessionId?: string;
+}
+
+export interface ToolSuccess<T extends JsonValue = JsonValue> {
+  success: true;
+  result: T;
+  metadata?: JsonObject;
+}
+
+export interface ToolFailure {
+  success: false;
+  error: string;
+  code?: string;
+  metadata?: JsonObject;
+}
+
+export type ToolResult<T extends JsonValue = JsonValue> = ToolSuccess<T> | ToolFailure;
+
+export interface ToolModule<TArguments extends JsonObject = JsonObject, TResult extends JsonValue = JsonValue> {
+  schema: ToolSchema;
+  execute(arguments_: TArguments, context?: ToolExecutionContext): Promise<ToolResult<TResult>> | ToolResult<TResult>;
+}
+
+export type RiskLevel = 'safe' | 'moderate' | 'dangerous' | 'extreme' | 'forbidden';
+
+export interface SandboxDecision {
+  allowed: boolean;
+  risk: RiskLevel;
+  reason?: string;
+}
+
+export type ApprovalChoice = 'deny' | 'allow_once' | 'allow_always';
+
+export interface ApprovalDecision {
+  choice: ApprovalChoice;
+  toolName: string;
+  reason?: string;
+}
+
+export type HookEvent = 'PreToolUse' | 'PostToolUse';
+
+export interface HookRule {
+  event: HookEvent;
+  command: string[];
+  name?: string;
+  tool?: string;
+  tools?: string[];
+  timeoutMs?: number;
+  enabled?: boolean;
+}
+
+export interface HookDecision {
+  denied: boolean;
+  messages: string[];
+  reason?: string;
+}
+
+export type PlanFailureClass =
+  | 'not_found'
+  | 'permission'
+  | 'timeout'
+  | 'network'
+  | 'rate_limited'
+  | 'invalid_args'
+  | 'syntax'
+  | 'exit_nonzero'
+  | 'failed';
+
+export interface PlanStep {
+  tool: string;
+  note: string;
+  ok: boolean;
+  why?: PlanFailureClass;
+}
+
+export interface PlanTemplate {
+  id: string;
+  archetype: string;
+  keywords: string[];
+  steps: PlanStep[];
+  uses: number;
+  wins: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PlanMatch {
+  template: PlanTemplate;
+  similarity: number;
+  matchType: 'exact' | 'fuzzy';
+  telemetry: {
+    keywordCount: number;
+    lookupMs: number;
+  };
+}
+
+export type PluginCapability = 'workspace:read' | 'workspace:write' | 'network' | 'subprocess';
+
+export interface PluginToolManifest {
+  name: string;
+  description: string;
+  parameters: JsonSchema;
+  entry: string;
+  export?: string;
+  capabilities?: PluginCapability[];
+  timeoutMs?: number;
+}
+
+export interface PluginSkillManifest {
+  id: string;
+  name?: string;
+  description: string;
+  file: string;
+}
+
+export interface PluginManifest {
+  schemaVersion: 1;
+  name: string;
+  version: string;
+  description: string;
+  capabilities?: PluginCapability[];
+  tools?: PluginToolManifest[];
+  skills?: PluginSkillManifest[];
+}
+
+export interface AgentProfileManifest {
+  schemaVersion: 1;
+  name: string;
+  description: string;
+  instructions: string;
+  toolScope: string[];
+  maxSteps?: number;
+  maxTokens?: number;
+}
+
+export interface TaskPhase {
+  name: string;
+  tools: string[];
+  note: string;
+}
+
+export interface TaskPackScore {
+  name: string;
+  score: number;
+}
+
+export type TaskConfidence = 'low' | 'medium' | 'high';
+
+export interface WorkspaceContext {
+  framework?: string;
+  projectType?: string;
+  designSystem?: string;
+  keyFiles?: string[];
+}
+
+export interface TaskShape {
+  archetype: string;
+  archetypeLabel: string;
+  packs: TaskPackScore[];
+  phases: TaskPhase[];
+  confidence: TaskConfidence;
+}
+
+export type AgentEvent =
+  | { type: 'model.started'; provider: string; model: string }
+  | { type: 'model.delta'; text: string }
+  | { type: 'tool.requested'; call: ToolCall }
+  | { type: 'tool.completed'; callId?: string; result: ToolResult }
+  | { type: 'approval.required'; toolName: string; risk: RiskLevel; reason?: string }
+  | { type: 'session.notice'; message: string };

package/src/utils/paths.d.ts

@@ -0,0 +1,3 @@
+/** Runtime declarations for the retained JavaScript path boundary. */
+export function resolveUserPath(input: string): string;
+export function causyneHome(): string;

package/src/version.d.ts

@@ -0,0 +1 @@
+export function getPackageVersion(): string;

package/src/mcp/jsonRpc.js

@@ -1,165 +0,0 @@
-
-
-import { spawn } from 'child_process';
-
-const DEFAULT_TIMEOUT_MS = 30000;
-
-/**
- * A JSON-RPC channel over a child process's stdin/stdout.
- *
- * MCP frames stdio traffic as newline-delimited JSON. stderr is deliberately
- * NOT parsed — servers use it for human-readable logging, and treating it as
- * protocol is how a chatty server becomes a hang.
- */
-export class StdioChannel {
-  constructor({ command, args = [], env = {}, cwd }) {
-    this.command = command;
-    this.args = args;
-    this.env = env;
-    this.cwd = cwd;
-    this.child = null;
-    this.buffer = '';
-    this.pending = new Map();
-    this.nextId = 1;
-    this.notificationHandler = null;
-    this.stderrTail = [];
-  }
-
-  async open() {
-    this.child = spawn(this.command, this.args, {
-      cwd: this.cwd || process.cwd(),
-      env: { ...process.env, ...this.env },
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-
-    this.child.stdout.setEncoding('utf-8');
-    this.child.stdout.on('data', chunk => this.#ingest(chunk));
-
-    // Kept only so a failure can be explained. Bounded, because a server that
-    
-    this.child.stderr.setEncoding('utf-8');
-    this.child.stderr.on('data', chunk => {
-      this.stderrTail.push(String(chunk));
-      if (this.stderrTail.length > 20) this.stderrTail.shift();
-    });
-
-    this.child.on('exit', code => this.#failAll(new Error(`server exited (code ${code})${this.lastError()}`)));
-    this.child.on('error', err => this.#failAll(err));
-
-    // Surface a command that does not exist as an error rather than a timeout.
-    await new Promise((resolve, reject) => {
-      const onError = (err) => reject(err);
-      this.child.once('error', onError);
-      setTimeout(() => { this.child.removeListener('error', onError); resolve(); }, 150);
-    });
-  }
-
-  lastError() {
-    const tail = this.stderrTail.join('').trim();
-    return tail ? `: ${tail.slice(-400)}` : '';
-  }
-
-  #ingest(chunk) {
-    this.buffer += chunk;
-    let newline;
-    while ((newline = this.buffer.indexOf('\n')) !== -1) {
-      const line = this.buffer.slice(0, newline).trim();
-      this.buffer = this.buffer.slice(newline + 1);
-      if (!line) continue;
-      let frame;
-      try { frame = JSON.parse(line); } catch (e) { continue; }
-      this.#dispatch(frame);
-    }
-  }
-
-  #dispatch(frame) {
-    if (frame.id !== undefined && this.pending.has(frame.id)) {
-      const { resolve, reject, timer } = this.pending.get(frame.id);
-      this.pending.delete(frame.id);
-      clearTimeout(timer);
-      if (frame.error) reject(new Error(frame.error.message || 'JSON-RPC error'));
-      else resolve(frame.result);
-      return;
-    }
-    if (frame.method && this.notificationHandler) {
-      try { this.notificationHandler(frame); } catch (e) {}
-    }
-  }
-
-  #failAll(error) {
-    for (const [, { reject, timer }] of this.pending) {
-      clearTimeout(timer);
-      reject(error);
-    }
-    this.pending.clear();
-  }
-
-  send(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    if (!this.child || this.child.killed) return Promise.reject(new Error('channel is closed'));
-    const id = this.nextId++;
-    const frame = { jsonrpc: '2.0', id, method, params: params ?? {} };
-
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error(`${method} timed out after ${timeoutMs} ms`));
-      }, timeoutMs);
-      this.pending.set(id, { resolve, reject, timer });
-      try {
-        this.child.stdin.write(JSON.stringify(frame) + '\n');
-      } catch (e) {
-        clearTimeout(timer);
-        this.pending.delete(id);
-        reject(e);
-      }
-    });
-  }
-
-  notify(method, params) {
-    if (!this.child || this.child.killed) return;
-    try {
-      this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params: params ?? {} }) + '\n');
-    } catch (e) {}
-  }
-
-  close() {
-    this.#failAll(new Error('channel closed'));
-    try { if (this.child) this.child.kill('SIGTERM'); } catch (e) {}
-    this.child = null;
-  }
-}
-
-/** A JSON-RPC channel over HTTP POST. One request, one response, no session. */
-export class HttpChannel {
-  constructor({ url, headers = {} }) {
-    this.url = url;
-    this.headers = headers;
-    this.nextId = 1;
-    this.notificationHandler = null;
-  }
-
-  async open() {
-    // Nothing to open. Validate the URL now so a typo fails at connect time
-    // rather than on the first tool call.
-    const parsed = new URL(this.url);
-    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-      throw new Error(`unsupported transport protocol: ${parsed.protocol}`);
-    }
-  }
-
-  async send(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    const response = await fetch(this.url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', ...this.headers },
-      body: JSON.stringify({ jsonrpc: '2.0', id: this.nextId++, method, params: params ?? {} }),
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!response.ok) throw new Error(`HTTP ${response.status} from ${this.url}`);
-    const frame = await response.json();
-    if (frame.error) throw new Error(frame.error.message || 'JSON-RPC error');
-    return frame.result;
-  }
-
-  notify() { /* HTTP transport has no notification channel */ }
-  close() { /* nothing to close */ }
-}