micode 0.8.3 → 0.8.5

package/src/tools/octto/session.ts

@@ -0,0 +1,114 @@
+// src/tools/octto/session.ts
+import { tool } from "@opencode-ai/plugin/tool";
+
+import type { SessionStore } from "../../octto/session";
+import type { OcttoSessionTracker, OcttoTools } from "./types";
+
+export function createSessionTools(sessions: SessionStore, tracker?: OcttoSessionTracker): OcttoTools {
+  const start_session = tool({
+    description: `Start an interactive octto session with initial questions.
+Opens a browser window with questions already displayed - no waiting.
+REQUIRED: You MUST provide at least 1 question. Will fail without questions.`,
+    args: {
+      title: tool.schema.string().optional().describe("Session title (shown in browser)"),
+      questions: tool.schema
+        .array(
+          tool.schema.object({
+            type: tool.schema
+              .enum([
+                "pick_one",
+                "pick_many",
+                "confirm",
+                "ask_text",
+                "ask_image",
+                "ask_file",
+                "ask_code",
+                "show_diff",
+                "show_plan",
+                "show_options",
+                "review_section",
+                "thumbs",
+                "slider",
+                "rank",
+                "rate",
+                "emoji_react",
+              ])
+              .describe("Question type"),
+
+            config: tool.schema
+              .looseObject({
+                question: tool.schema.string().optional(),
+                context: tool.schema.string().optional(),
+              })
+              .describe("Question config (varies by type)"),
+          }),
+        )
+        .describe("REQUIRED: Initial questions to display when browser opens. Must have at least 1."),
+    },
+    execute: async (args, context) => {
+      // ENFORCE: questions are required
+      if (!args.questions || args.questions.length === 0) {
+        return `## ERROR: questions parameter is REQUIRED
+
+start_session MUST include questions. Browser should open with questions ready.
+
+Example:
+\`\`\`
+start_session(
+  title="Design Session",
+  questions=[
+    {type: "pick_one", config: {question: "What language?", options: [{id: "go", label: "Go"}]}},
+    {type: "ask_text", config: {question: "Any constraints?"}}
+  ]
+)
+\`\`\`
+
+Please call start_session again WITH your prepared questions.`;
+      }
+
+      try {
+        const result = await sessions.startSession({ title: args.title, questions: args.questions });
+        tracker?.onCreated?.(context.sessionID, result.session_id);
+
+        let output = `## Session Started
+
+| Field | Value |
+|-------|-------|
+| Session ID | ${result.session_id} |
+| URL | ${result.url} |
+`;
+
+        if (result.question_ids && result.question_ids.length > 0) {
+          output += `| Questions | ${result.question_ids.length} loaded |\n\n`;
+          output += `**Question IDs:** ${result.question_ids.join(", ")}\n\n`;
+          output += `Browser opened with ${result.question_ids.length} questions ready.\n`;
+          output += `Use get_next_answer(session_id, block=true) to get answers as user responds.`;
+        } else {
+          output += `\nBrowser opened. Use question tools to push questions.`;
+        }
+
+        return output;
+      } catch (error) {
+        return `Failed to start session: ${error instanceof Error ? error.message : String(error)}`;
+      }
+    },
+  });
+
+  const end_session = tool({
+    description: `End an interactive octto session.
+Closes the browser window and cleans up resources.`,
+    args: {
+      session_id: tool.schema.string().describe("Session ID to end"),
+    },
+    execute: async (args, context) => {
+      const result = await sessions.endSession(args.session_id);
+      if (result.ok) {
+        tracker?.onEnded?.(context.sessionID, args.session_id);
+        return `Session ${args.session_id} ended successfully.`;
+      }
+      return `Failed to end session ${args.session_id}. It may not exist.`;
+    },
+  });
+
+  return { start_session, end_session };
+}

package/src/tools/octto/types.ts

@@ -0,0 +1,21 @@
+// src/tools/octto/types.ts
+
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+
+// Using `any` to avoid exposing zod types in declaration files.
+// The actual tools are typesafe via zod schemas.
+export interface OcttoTool {
+  description: string;
+  args: any;
+  execute: (args: any, context: ToolContext) => Promise<string>;
+}
+
+export type OcttoTools = Record<string, OcttoTool>;
+
+export type OpencodeClient = ReturnType<typeof createOpencodeClient>;
+
+export interface OcttoSessionTracker {
+  onCreated?: (parentSessionId: string, octtoSessionId: string) => void;
+  onEnded?: (parentSessionId: string, octtoSessionId: string) => void;
+}

package/src/tools/octto/utils.ts

@@ -0,0 +1,4 @@
+// src/tools/octto/utils.ts
+// Re-export ID generation utilities from octto/session for convenience
+
+export { generateBrainstormId, generateQuestionId, generateSessionId } from "../../octto/session/utils";

package/src/tools/pty/manager.ts

@@ -20,13 +20,19 @@ export class PTYManager {
     const env = { ...process.env, ...opts.env } as Record<string, string>;
     const title = opts.title ?? (`${opts.command} ${args.join(" ")}`.trim() || `Terminal ${id.slice(-4)}`);
 
-    const ptyProcess: IPty = spawn(opts.command, args, {
-      name: "xterm-256color",
-      cols: 120,
-      rows: 40,
-      cwd: workdir,
-      env,
-    });
+    let ptyProcess: IPty;
+    try {
+      ptyProcess = spawn(opts.command, args, {
+        name: "xterm-256color",
+        cols: 120,
+        rows: 40,
+        cwd: workdir,
+        env,
+      });
+    } catch (e) {
+      const errorMsg = e instanceof Error ? e.message : String(e);
+      throw new Error(`Failed to spawn PTY for command "${opts.command}": ${errorMsg}`);
+    }
 
     const buffer = new RingBuffer();
     const session: PTYSession = {

package/src/tools/spawn-agent.ts

@@ -63,9 +63,7 @@ For parallel execution, call spawn_agent multiple times in ONE message.`,
 
         // Find the last assistant message
         const messages = messagesResp.data || [];
-        const lastAssistant = messages
-          .filter((m) => m.info?.role === "assistant")
-          .pop();
+        const lastAssistant = messages.filter((m) => m.info?.role === "assistant").pop();
 
         const result =
           lastAssistant?.parts

package/src/utils/config.ts

@@ -0,0 +1,123 @@
+// src/utils/config.ts
+// Centralized configuration constants
+// Organized by domain for easy discovery and maintenance
+
+/**
+ * Application configuration constants.
+ * All values are compile-time constants - no runtime configuration.
+ */
+export const config = {
+  /**
+   * Auto-compaction settings
+   */
+  compaction: {
+    /** Trigger compaction when context usage exceeds this ratio */
+    threshold: 0.5,
+    /** Minimum time between compaction attempts (ms) */
+    cooldownMs: 30_000,
+    /** Maximum time to wait for compaction to complete (ms) */
+    timeoutMs: 120_000,
+  },
+
+  /**
+   * Context window monitoring settings
+   */
+  contextWindow: {
+    /** Show warning when context usage exceeds this ratio */
+    warningThreshold: 0.7,
+    /** Show critical warning when context usage exceeds this ratio */
+    criticalThreshold: 0.85,
+    /** Minimum time between warning toasts (ms) */
+    warningCooldownMs: 120_000,
+  },
+
+  /**
+   * Token estimation settings
+   */
+  tokens: {
+    /** Characters per token for estimation */
+    charsPerToken: 4,
+    /** Default context window limit (tokens) */
+    defaultContextLimit: 200_000,
+    /** Default max output tokens */
+    defaultMaxOutputTokens: 50_000,
+    /** Safety margin for output (ratio of remaining context) */
+    safetyMargin: 0.5,
+    /** Lines to preserve when truncating output */
+    preserveHeaderLines: 3,
+  },
+
+  /**
+   * File path patterns and directories
+   */
+  paths: {
+    /** Directory for ledger files */
+    ledgerDir: "thoughts/ledgers",
+    /** Prefix for ledger filenames */
+    ledgerPrefix: "CONTINUITY_",
+    /** Context files to inject from project root */
+    rootContextFiles: ["ARCHITECTURE.md", "CODE_STYLE.md", "README.md"] as readonly string[],
+    /** Context files to collect when walking up directories */
+    dirContextFiles: ["README.md"] as readonly string[],
+    /** Pattern to match plan files */
+    planPattern: /thoughts\/shared\/plans\/.*\.md$/,
+    /** Pattern to match ledger files */
+    ledgerPattern: /thoughts\/ledgers\/CONTINUITY_.*\.md$/,
+  },
+
+  /**
+   * Timeout settings
+   */
+  timeouts: {
+    /** BTCA command timeout (ms) */
+    btcaMs: 120_000,
+    /** Success toast duration (ms) */
+    toastSuccessMs: 3000,
+    /** Warning toast duration (ms) */
+    toastWarningMs: 4000,
+    /** Error toast duration (ms) */
+    toastErrorMs: 5000,
+  },
+
+  /**
+   * Various limits
+   */
+  limits: {
+    /** File size threshold for triggering extraction (bytes) */
+    largeFileBytes: 100 * 1024,
+    /** Max lines to return without extraction */
+    maxLinesNoExtract: 200,
+    /** Max lines in PTY buffer */
+    ptyMaxBufferLines: 50_000,
+    /** Default read limit for PTY */
+    ptyDefaultReadLimit: 500,
+    /** Max line length for PTY output */
+    ptyMaxLineLength: 2000,
+    /** Max matches to show from ast-grep */
+    astGrepMaxMatches: 100,
+    /** Context cache TTL (ms) */
+    contextCacheTtlMs: 30_000,
+    /** Max entries in context cache */
+    contextCacheMaxSize: 100,
+  },
+
+  /**
+   * Octto (browser-based brainstorming) settings
+   */
+  octto: {
+    /** Answer timeout (ms) - 5 minutes */
+    answerTimeoutMs: 5 * 60 * 1000,
+    /** Review timeout (ms) - 10 minutes */
+    reviewTimeoutMs: 10 * 60 * 1000,
+    /** Max iterations in brainstorm loop */
+    maxIterations: 50,
+    /** Max follow-up questions per branch */
+    maxQuestions: 15,
+    /** State directory for brainstorm sessions */
+    stateDir: "thoughts/brainstorms",
+    /** Bind address for brainstorm server */
+    bindAddress: "127.0.0.1",
+    /** Allow overriding bind address for remote access */
+    allowRemoteBind: false,
+  },
+} as const;

package/src/utils/errors.ts

@@ -0,0 +1,57 @@
+// src/utils/errors.ts
+// Unified error handling utilities
+// Used by tools and hooks for consistent error formatting and logging
+
+/**
+ * Safely extract error message from unknown error type.
+ * Handles Error instances, strings, and other types.
+ */
+export function extractErrorMessage(e: unknown): string {
+  if (e instanceof Error) {
+    return e.message;
+  }
+  return String(e);
+}
+
+/**
+ * Format error message for tool responses (LLM-facing).
+ * @param message - The error message
+ * @param context - Optional context about what operation failed
+ */
+export function formatToolError(message: string, context?: string): string {
+  if (context && context.trim()) {
+    return `Error (${context}): ${message}`;
+  }
+  return `Error: ${message}`;
+}
+
+/**
+ * Execute a function and log any errors without throwing.
+ * Use for non-critical operations that shouldn't fail the main flow.
+ * @param module - Module name for log prefix
+ * @param fn - Function to execute
+ * @returns Result or undefined if error occurred
+ */
+export function catchAndLog<T>(module: string, fn: () => T): T | undefined {
+  try {
+    return fn();
+  } catch (e) {
+    console.error(`[${module}] ${extractErrorMessage(e)}`);
+    return undefined;
+  }
+}
+
+/**
+ * Async version of catchAndLog.
+ * @param module - Module name for log prefix
+ * @param fn - Async function to execute
+ * @returns Result or undefined if error occurred
+ */
+export async function catchAndLogAsync<T>(module: string, fn: () => Promise<T>): Promise<T | undefined> {
+  try {
+    return await fn();
+  } catch (e) {
+    console.error(`[${module}] ${extractErrorMessage(e)}`);
+    return undefined;
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,50 @@
+// src/utils/logger.ts
+// Standardized logging with module prefixes
+// Used across hooks and tools for consistent log formatting
+
+/**
+ * Logger with standardized [module] prefix format.
+ *
+ * Usage:
+ *   log.info("my-hook", "Processing file");
+ *   log.error("my-tool", "Failed to read", error);
+ *   log.debug("my-module", "Verbose info"); // Only when DEBUG env set
+ */
+export const log = {
+  /**
+   * Debug level - only outputs when DEBUG environment variable is set.
+   */
+  debug(module: string, message: string): void {
+    if (process.env.DEBUG) {
+      console.log(`[${module}] ${message}`);
+    }
+  },
+
+  /**
+   * Info level - general informational messages.
+   */
+  info(module: string, message: string): void {
+    console.log(`[${module}] ${message}`);
+  },
+
+  /**
+   * Warning level - non-fatal issues.
+   */
+  warn(module: string, message: string): void {
+    console.warn(`[${module}] ${message}`);
+  },
+
+  /**
+   * Error level - errors that were caught and handled.
+   * @param module - Module name for prefix
+   * @param message - Error description
+   * @param error - Optional error object for additional context
+   */
+  error(module: string, message: string, error?: unknown): void {
+    if (error !== undefined) {
+      console.error(`[${module}] ${message}`, error);
+    } else {
+      console.error(`[${module}] ${message}`);
+    }
+  },
+};