@causyne/agent 1.10.13 → 1.10.18

package/src/tui/ask.js

@@ -25,7 +25,7 @@
 
 import readline from 'readline';
 import { ChatPrompt, isInteractive } from './prompt.js';
-import { SelectLayer, InputLayer, ConfirmLayer } from './dialogs.js';
+import { SelectLayer, InputLayer, ConfirmLayer, DecisionLayer } from './dialogs.js';
 
 /**
  * Run one layer on a temporary prompt host.
@@ -162,3 +162,43 @@ export async function askConfirm(message) {
   const raw = await fallbackQuestion(`${message} [y/N]`);
   return /^y(es)?$/i.test(String(raw).trim());
 }
+
+/**
+ * Ask for a durable product or architecture choice.
+ *
+ * This remains separate from permissions: choosing an implementation direction
+ * never grants a tool the right to mutate files or execute a command.
+ */
+export async function askDecision(request = {}) {
+  const options = Array.isArray(request.options) ? request.options : [];
+
+  if (canAskInPanel()) {
+    const answer = await hostOneLayer((resolve) => new DecisionLayer({
+      request,
+      onAnswer: resolve
+    }));
+    if (answer !== undefined) return answer;
+  }
+
+  const custom = { id: '__custom__', label: 'Type your own answer', description: '' };
+  const selected = await askSelect({
+    title: request.header || 'Decision required',
+    items: [...options, custom]
+  });
+  if (!selected) return null;
+  if (selected.id === custom.id) {
+    const label = await askText({
+      title: request.question || 'Describe the direction you want',
+      lines: request.reason ? [request.reason] : [],
+      validate: (value) => String(value).trim() ? null : 'An answer is required.'
+    });
+    if (!label) return null;
+    return { requestId: request.id, optionId: null, label: String(label).trim(), custom: true };
+  }
+  return {
+    requestId: request.id,
+    optionId: selected.id,
+    label: selected.label,
+    custom: false
+  };
+}

package/src/tui/chatRenderer.js

@@ -211,6 +211,7 @@ export class ChatRenderer {
     this.spinnerIndex = 0;
     this.currentStatus = '';
     this.pendingApprovals = new Map();
+    this.latestPlan = [];
     this.status = new StatusLine();
     this.turnStartedAt = null;
 
@@ -548,9 +549,34 @@ export class ChatRenderer {
   onAgentPlan(msg) {
     if (!Array.isArray(msg.plan) || msg.plan.length === 0) return;
     const plan = msg.plan.slice();
+    this.latestPlan = plan;
+    if (this.onPlanChange) this.onPlanChange(plan);
     this.frame('plan', () => this.renderPlan(plan), { items: plan.length });
   }
 
+  onDecisionRequest(msg) {
+    if (this.dialogWillAsk) return;
+    const request = msg.request || {};
+    this.frame('approval', () => {
+      this.write();
+      this.write(`${paint('accent', GLYPHS.arrow)} ${bold(safeDisplay(request.header || 'decision required'))}`);
+      for (const row of wrapBlock(safeDisplay(request.question || ''), Math.max(20, this.width() - 4))) this.write(`  ${row}`);
+      this.write();
+    }, { kind: request.kind || 'other' });
+  }
+
+  onDecisionResult(msg) {
+    const request = msg.request || {};
+    const answer = msg.answer;
+    this.frame('approval', () => {
+      if (!answer) {
+        this.write(`  ${paint('muted', 'decision dismissed')}  ${safeDisplay(request.header || '')}`);
+        return;
+      }
+      this.write(`  ${paint('success', GLYPHS.check)} ${bold(safeDisplay(answer.label || ''))}${answer.custom ? dim('  custom choice') : ''}`);
+    }, { kind: request.kind || 'other', answered: Boolean(answer) });
+  }
+
   renderPlan(plan) {
     const width = this.width();
     this.write();
@@ -940,6 +966,8 @@ export class ChatRenderer {
       case 'step_error':       this.onStepError(msg); return true;
       case 'checkpoint':       this.onCheckpoint(msg); return true;
       case 'approval_request': this.onApprovalRequest(msg); return true;
+      case 'decision_request': this.onDecisionRequest(msg); return true;
+      case 'decision_result':  this.onDecisionResult(msg); return true;
       case 'error':            this.onError(msg); return true;
       case 'budget_warning':   this.onBudgetWarning(msg); return true;
       case 'notice':           this.onNotice(msg); return true;

package/src/tui/dialogs.js

@@ -489,6 +489,97 @@ export class ApprovalLayer extends Layer {
   }
 }
 
+/** A structured product or architecture choice, separate from permissions. */
+export class DecisionLayer extends Layer {
+  constructor(options = {}) {
+    super({ width: options.width || 82, height: options.height || 24, ...options });
+    this.request = options.request || {};
+    this.onAnswer = options.onAnswer || null;
+    this.options = Array.isArray(this.request.options) ? this.request.options.slice(0, 4) : [];
+    this.selected = 0;
+    this.customIndex = this.options.length;
+    this.customMode = false;
+    this.editor = new LineEditor();
+    this.answered = false;
+    this.title = safeDisplay(this.request.header || 'decision required');
+    this.footer = `↑↓ choose  ${GLYPHS.dot}  enter select  ${GLYPHS.dot}  esc cancel`;
+  }
+
+  preferredHeight() {
+    const questionRows = wrap(safeDisplay(this.request.question || ''), Math.max(20, this.width - 6)).length;
+    const reasonRows = wrap(safeDisplay(this.request.reason || ''), Math.max(20, this.width - 6)).length;
+    return Math.min(this.height, questionRows + reasonRows + (this.options.length * 2) + 7);
+  }
+
+  body(width, height) {
+    const rows = [];
+    rows.push(...wrap(bold(safeDisplay(this.request.question || 'Choose a direction')), width).slice(0, 4));
+    if (this.request.reason) rows.push(...wrap(dim(safeDisplay(this.request.reason)), width).slice(0, 3));
+    rows.push('');
+
+    for (const [index, option] of this.options.entries()) {
+      const selected = index === this.selected;
+      const marker = selected ? paint('accent', GLYPHS.arrow) : paint('muted', GLYPHS.dot);
+      rows.push(`${marker} ${selected ? bold(safeDisplay(option.label || '')) : safeDisplay(option.label || '')}`);
+      if (option.description) rows.push(`  ${dim(truncate(safeDisplay(option.description), Math.max(1, width - 2), GLYPHS.ellipsis))}`);
+    }
+
+    const customSelected = this.selected === this.customIndex;
+    rows.push(`${customSelected ? paint('accent', GLYPHS.arrow) : paint('muted', GLYPHS.dot)} ${customSelected ? bold('Type your own answer') : 'Type your own answer'}`);
+    if (this.customMode) {
+      const value = this.editor.getText();
+      rows.push(`${paint('accent', `${GLYPHS.arrow} `)}${value || dim('Describe the direction you want')}`);
+      this.cursor = { x: 2 + visibleWidth(value.slice(0, this.editor.col)), y: rows.length - 1 };
+      this.footer = `enter submit  ${GLYPHS.dot}  esc choices`;
+    } else {
+      this.cursor = null;
+      this.footer = `↑↓ choose  ${GLYPHS.dot}  enter select  ${GLYPHS.dot}  esc cancel`;
+    }
+    return rows.slice(0, height);
+  }
+
+  key(event) {
+    if (!event) return null;
+    if (this.customMode) {
+      if (event.name === 'escape') { this.customMode = false; return 'handled'; }
+      if (event.name === 'enter' || event.name === 'return') {
+        const label = this.editor.getText().replace(/\s+/g, ' ').trim();
+        if (!label) return 'handled';
+        this.answer({ requestId: this.request.id, optionId: null, label, custom: true });
+        return 'close';
+      }
+      if (event.name === 'backspace') { this.editor.backspace(); return 'handled'; }
+      if (event.name === 'delete') { this.editor.deleteForward(); return 'handled'; }
+      if (event.name === 'left') { this.editor.moveLeft(); return 'handled'; }
+      if (event.name === 'right') { this.editor.moveRight(); return 'handled'; }
+      if (event.name === 'home') { this.editor.moveHome(); return 'handled'; }
+      if (event.name === 'end') { this.editor.moveEnd(); return 'handled'; }
+      if (event.name === 'paste') { this.editor.insert(event.text); return 'handled'; }
+      if (event.name === 'char') { this.editor.insert(event.text); return 'handled'; }
+      return 'handled';
+    }
+
+    if (event.name === 'escape') { this.answer(null); return 'close'; }
+    const count = this.options.length + 1;
+    if (event.name === 'up') { this.selected = (this.selected - 1 + count) % count; return 'handled'; }
+    if (event.name === 'down') { this.selected = (this.selected + 1) % count; return 'handled'; }
+    if (event.name === 'enter' || event.name === 'return') {
+      if (this.selected === this.customIndex) { this.customMode = true; return 'handled'; }
+      const option = this.options[this.selected];
+      if (!option) return 'handled';
+      this.answer({ requestId: this.request.id, optionId: option.id, label: option.label, custom: false });
+      return 'close';
+    }
+    return 'handled';
+  }
+
+  answer(value = null) {
+    if (this.answered) return;
+    this.answered = true;
+    if (this.onAnswer) this.onAnswer(value);
+  }
+}
+
 /** A yes/no confirm, for destructive commands that are not tool approvals. */
 export class ConfirmLayer extends Layer {
   constructor(options = {}) {

package/src/tui/prompt.js

@@ -26,7 +26,7 @@ import { barBlock, GUTTER } from './block.js';
 import { visibleWidth, truncate, wrapBlock, shortenHome, safeDisplay } from './text.js';
 import { pickExample, fitHints } from './banner.js';
 import { panelRows } from './overlay.js';
-import { commandPalette, skillPicker, ApprovalLayer, ConfirmLayer, HomeLayer, TextLayer } from './dialogs.js';
+import { commandPalette, skillPicker, ApprovalLayer, DecisionLayer, ConfirmLayer, HomeLayer, TextLayer } from './dialogs.js';
 import { describeTool } from './toolDisplay.js';
 
 const CTRL_C_WINDOW_MS = 2000;
@@ -264,6 +264,7 @@ export class ChatPrompt {
       this.statusMessage = message;
       this.scheduleDraw();
     };
+    renderer.onPlanChange = () => this.scheduleDraw();
   }
 
   /**
@@ -321,6 +322,26 @@ export class ChatPrompt {
     return visibleWidth(full) > width ? truncate(full, width, GLYPHS.ellipsis) : full;
   }
 
+  /** Persistent checklist shown outside the chat transcript. */
+  planRows(width) {
+    const plan = this.renderer && Array.isArray(this.renderer.latestPlan) ? this.renderer.latestPlan : [];
+    if (plan.length === 0) return [];
+    const completed = plan.filter(item => item.status === 'completed').length;
+    const rows = [`${bold(paint('accent', 'implementation plan'))}  ${dim(`${completed}/${plan.length}`)}`];
+    const limit = Math.min(plan.length, 5);
+    for (const item of plan.slice(0, limit)) {
+      const mark = item.status === 'completed'
+        ? paint('success', GLYPHS.check)
+        : item.status === 'in_progress'
+          ? paint('accent', GLYPHS.arrow)
+          : paint('muted', GLYPHS.dot);
+      rows.push(`  ${mark} ${truncate(safeDisplay(item.text || item.step || ''), Math.max(8, width - 5), GLYPHS.ellipsis)}`);
+    }
+    if (plan.length > limit) rows.push(`  ${dim(`${GLYPHS.ellipsis} ${plan.length - limit} more`)}`);
+    rows.push('');
+    return rows;
+  }
+
   startTick() {
     if (this.tickTimer) return;
     this.tickTimer = setInterval(() => {
@@ -456,6 +477,13 @@ export class ChatPrompt {
     });
   }
 
+  /** Ask for a durable implementation choice, with a free-form option. */
+  decide(request = {}) {
+    return new Promise((resolve) => {
+      this.openLayer(new DecisionLayer({ request, onAnswer: resolve }));
+    });
+  }
+
   /** A plain yes/no, for the questions that are not tool approvals. */
   confirm(message, options = {}) {
     return new Promise((resolve) => {
@@ -1136,12 +1164,13 @@ export class ChatPrompt {
     const status = this.statusRow(width);
     const gap = status.length > 0 ? new Array(FOOTER_GAP).fill('') : [];
 
+    const planRows = this.planRows(width);
     const all = this.clampRows(
-      boxRows.concat(pickerRows, noticeRows, gap, status), width
+      planRows.concat(boxRows, pickerRows, noticeRows, gap, status), width
     );
 
     // Park the cursor where the user is typing, not at the end of the picker.
-    this.present(all, caretRow + padTop, layout.cursorCol + inset);
+    this.present(all, planRows.length + caretRow + padTop, layout.cursorCol + inset);
   }
 
   /**

package/src/tui/toolDisplay.js

@@ -82,7 +82,6 @@ const TOOL_DISPLAY = new Map([
   ['code_verify_syntax',  (a) => ({ verb: 'verify', detail: pathDetail(firstString(a, ['path', 'file_path'])) })],
 
   ['memory_write',  (a) => ({ verb: 'remember', detail: firstString(a, ['fact', 'key', 'project']) })],
-  ['TodoWrite',     (a) => ({ verb: 'plan',     detail: countDetail(a.todos, 'item') })],
   ['update_plan',   (a) => ({ verb: 'plan',     detail: countDetail(a.plan, 'step') })],
   ['tool_search',   (a) => ({ verb: 'discover', detail: firstString(a, ['query', 'description']) })],
   ['fs_read_skill', (a) => ({ verb: 'skill',    detail: firstString(a, ['id', 'skillId', 'domain']) })],

package/src/types/contracts.js

@@ -0,0 +1,8 @@
+/**
+ * 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 {};

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;