micode 0.8.3 → 0.8.5

package/src/octto/session/waiter.ts

@@ -0,0 +1,139 @@
+// src/octto/session/waiter.ts
+// Immutable waiter management for async response handling
+
+export interface Waiters<K, T> {
+  register: (key: K, callback: (data: T) => void) => () => void;
+  notifyFirst: (key: K, data: T) => void;
+  notifyAll: (key: K, data: T) => void;
+  has: (key: K) => boolean;
+  count: (key: K) => number;
+  clear: (key: K) => void;
+}
+
+/**
+ * Create a waiter registry for async response handling.
+ * Each operation creates a new array rather than mutating in place.
+ *
+ * @typeParam K - Key type (e.g., string for question_id or session_id)
+ * @typeParam T - Data type passed to waiter callbacks
+ */
+export function createWaiters<K, T>(): Waiters<K, T> {
+  const waiters = new Map<K, Array<(data: T) => void>>();
+
+  return {
+    /**
+     * Register a waiter callback for a key.
+     * Returns a cleanup function to remove this specific waiter.
+     */
+    register(key: K, callback: (data: T) => void): () => void {
+      // Create new array with callback appended (immutable)
+      const current = waiters.get(key) || [];
+      waiters.set(key, [...current, callback]);
+
+      // Return cleanup function that removes this specific callback
+      return () => {
+        const callbacks = waiters.get(key);
+        if (!callbacks) return;
+
+        const idx = callbacks.indexOf(callback);
+        if (idx >= 0) {
+          // Create new array without this callback (immutable)
+          const remaining = [...callbacks.slice(0, idx), ...callbacks.slice(idx + 1)];
+          if (remaining.length === 0) {
+            waiters.delete(key);
+          } else {
+            waiters.set(key, remaining);
+          }
+        }
+      };
+    },
+
+    /**
+     * Notify only the first waiter for a key and remove it.
+     * Other waiters remain registered for subsequent notifications.
+     */
+    notifyFirst(key: K, data: T): void {
+      const callbacks = waiters.get(key);
+      if (!callbacks || callbacks.length === 0) return;
+
+      const [first, ...rest] = callbacks;
+      first(data);
+
+      // Set new array without first element (immutable)
+      if (rest.length === 0) {
+        waiters.delete(key);
+      } else {
+        waiters.set(key, rest);
+      }
+    },
+
+    /**
+     * Notify all waiters for a key and remove them all.
+     */
+    notifyAll(key: K, data: T): void {
+      const callbacks = waiters.get(key);
+      if (!callbacks) return;
+
+      try {
+        for (const callback of callbacks) {
+          try {
+            callback(data);
+          } catch (error) {
+            console.error("Waiter notifyAll failed", error);
+            break;
+          }
+        }
+      } finally {
+        waiters.delete(key);
+      }
+    },
+
+    /**
+     * Check if there are any waiters for a key.
+     */
+    has(key: K): boolean {
+      const callbacks = waiters.get(key);
+      return callbacks !== undefined && callbacks.length > 0;
+    },
+
+    /**
+     * Get the number of waiters for a key.
+     */
+    count(key: K): number {
+      return waiters.get(key)?.length ?? 0;
+    },
+
+    /**
+     * Remove all waiters for a key without notifying them.
+     */
+    clear(key: K): void {
+      waiters.delete(key);
+    },
+  };
+}
+
+/**
+ * Result of waiting for a response
+ */
+export type WaitResult<T> = { ok: true; data: T } | { ok: false; reason: "timeout" };
+
+/**
+ * Wait for a response with timeout.
+ * Registers a waiter and returns a promise that resolves when notified or times out.
+ */
+export function waitForResponse<K, T>(waiters: Waiters<K, T>, key: K, timeoutMs: number): Promise<WaitResult<T>> {
+  return new Promise((resolve) => {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let cleanup: (() => void) | undefined;
+
+    cleanup = waiters.register(key, (data) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      resolve({ ok: true, data });
+    });
+
+    timeoutId = setTimeout(() => {
+      if (cleanup) cleanup();
+      resolve({ ok: false, reason: "timeout" });
+    }, timeoutMs);
+  });
+}

package/src/octto/state/index.ts

@@ -0,0 +1,5 @@
+// src/octto/state/index.ts
+
+export * from "./persistence";
+export * from "./store";
+export * from "./types";

package/src/octto/state/persistence.ts

@@ -0,0 +1,65 @@
+// src/octto/state/persistence.ts
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { STATE_DIR } from "../constants";
+import type { BrainstormState } from "./types";
+
+export interface StatePersistence {
+  save: (state: BrainstormState) => Promise<void>;
+  load: (sessionId: string) => Promise<BrainstormState | null>;
+  delete: (sessionId: string) => Promise<void>;
+  list: () => Promise<string[]>;
+}
+
+function validateSessionId(sessionId: string): void {
+  if (!/^[a-zA-Z0-9_-]+$/.test(sessionId)) {
+    throw new Error(`Invalid session ID: ${sessionId}`);
+  }
+}
+
+export function createStatePersistence(baseDir = STATE_DIR): StatePersistence {
+  function getFilePath(sessionId: string): string {
+    validateSessionId(sessionId);
+    return join(baseDir, `${sessionId}.json`);
+  }
+
+  function ensureDir(): void {
+    if (!existsSync(baseDir)) {
+      mkdirSync(baseDir, { recursive: true });
+    }
+  }
+
+  return {
+    async save(state: BrainstormState): Promise<void> {
+      ensureDir();
+      const filePath = getFilePath(state.session_id);
+      state.updated_at = Date.now();
+      await Bun.write(filePath, JSON.stringify(state, null, 2));
+    },
+
+    async load(sessionId: string): Promise<BrainstormState | null> {
+      const filePath = getFilePath(sessionId);
+      if (!existsSync(filePath)) {
+        return null;
+      }
+      const content = await Bun.file(filePath).text();
+      return JSON.parse(content) as BrainstormState;
+    },
+
+    async delete(sessionId: string): Promise<void> {
+      const filePath = getFilePath(sessionId);
+      if (existsSync(filePath)) {
+        rmSync(filePath);
+      }
+    },
+
+    async list(): Promise<string[]> {
+      if (!existsSync(baseDir)) {
+        return [];
+      }
+      const files = readdirSync(baseDir);
+      return files.filter((f) => f.endsWith(".json")).map((f) => f.replace(".json", ""));
+    },
+  };
+}

package/src/octto/state/store.ts

@@ -0,0 +1,161 @@
+// src/octto/state/store.ts
+
+import { STATE_DIR } from "../constants";
+import type { Answer } from "../session";
+import { createStatePersistence } from "./persistence";
+import {
+  BRANCH_STATUSES,
+  type BrainstormState,
+  type Branch,
+  type BranchQuestion,
+  type CreateBranchInput,
+} from "./types";
+
+export interface StateStore {
+  createSession: (sessionId: string, request: string, branches: CreateBranchInput[]) => Promise<BrainstormState>;
+  getSession: (sessionId: string) => Promise<BrainstormState | null>;
+  setBrowserSessionId: (sessionId: string, browserSessionId: string) => Promise<void>;
+  addQuestionToBranch: (sessionId: string, branchId: string, question: BranchQuestion) => Promise<BranchQuestion>;
+  recordAnswer: (sessionId: string, questionId: string, answer: Answer) => Promise<void>;
+  completeBranch: (sessionId: string, branchId: string, finding: string) => Promise<void>;
+  getNextExploringBranch: (sessionId: string) => Promise<Branch | null>;
+  isSessionComplete: (sessionId: string) => Promise<boolean>;
+  deleteSession: (sessionId: string) => Promise<void>;
+}
+
+export function createStateStore(baseDir = STATE_DIR): StateStore {
+  const persistence = createStatePersistence(baseDir);
+
+  // Operation queue per session to prevent concurrent read-modify-write races
+  const operationQueues = new Map<string, Promise<void>>();
+
+  // Serialize operations for a given session
+  function withSessionLock<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+    const currentQueue = operationQueues.get(sessionId) ?? Promise.resolve();
+    const newOperation = currentQueue.then(operation, operation); // Run even if previous failed
+    operationQueues.set(
+      sessionId,
+      newOperation.then(
+        () => {},
+        () => {},
+      ),
+    ); // Ignore result for queue
+    return newOperation;
+  }
+
+  return {
+    async createSession(
+      sessionId: string,
+      request: string,
+      branchInputs: CreateBranchInput[],
+    ): Promise<BrainstormState> {
+      const branches: Record<string, Branch> = {};
+      const order: string[] = [];
+
+      for (const input of branchInputs) {
+        branches[input.id] = {
+          id: input.id,
+          scope: input.scope,
+          status: BRANCH_STATUSES.EXPLORING,
+          questions: [],
+          finding: null,
+        };
+        order.push(input.id);
+      }
+
+      const state: BrainstormState = {
+        session_id: sessionId,
+        browser_session_id: null,
+        request,
+        created_at: Date.now(),
+        updated_at: Date.now(),
+        branches,
+        branch_order: order,
+      };
+
+      await persistence.save(state);
+      return state;
+    },
+
+    async getSession(sessionId: string): Promise<BrainstormState | null> {
+      return persistence.load(sessionId);
+    },
+
+    async setBrowserSessionId(sessionId: string, browserSessionId: string): Promise<void> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+        state.browser_session_id = browserSessionId;
+        await persistence.save(state);
+      });
+    },
+
+    async addQuestionToBranch(sessionId: string, branchId: string, question: BranchQuestion): Promise<BranchQuestion> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+        if (!state.branches[branchId]) throw new Error(`Branch not found: ${branchId}`);
+
+        state.branches[branchId].questions.push(question);
+        await persistence.save(state);
+        return question;
+      });
+    },
+
+    async recordAnswer(sessionId: string, questionId: string, answer: Answer): Promise<void> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+
+        for (const branch of Object.values(state.branches)) {
+          const question = branch.questions.find((q) => q.id === questionId);
+          if (question) {
+            question.answer = answer;
+            question.answeredAt = Date.now();
+            await persistence.save(state);
+            return;
+          }
+        }
+        throw new Error(`Question not found: ${questionId}`);
+      });
+    },
+
+    async completeBranch(sessionId: string, branchId: string, finding: string): Promise<void> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+        if (!state.branches[branchId]) throw new Error(`Branch not found: ${branchId}`);
+
+        state.branches[branchId].status = BRANCH_STATUSES.DONE;
+        state.branches[branchId].finding = finding;
+        await persistence.save(state);
+      });
+    },
+
+    async getNextExploringBranch(sessionId: string): Promise<Branch | null> {
+      const state = await persistence.load(sessionId);
+      if (!state) return null;
+
+      for (const branchId of state.branch_order) {
+        const branch = state.branches[branchId];
+        if (branch.status === BRANCH_STATUSES.EXPLORING) {
+          return branch;
+        }
+      }
+      return null;
+    },
+
+    async isSessionComplete(sessionId: string): Promise<boolean> {
+      const state = await persistence.load(sessionId);
+      if (!state) return false;
+
+      return Object.values(state.branches).every((b) => b.status === BRANCH_STATUSES.DONE);
+    },
+
+    async deleteSession(sessionId: string): Promise<void> {
+      await withSessionLock(sessionId, async () => {
+        await persistence.delete(sessionId);
+      });
+    },
+  };
+}

package/src/octto/state/types.ts

@@ -0,0 +1,51 @@
+// src/octto/state/types.ts
+import type { Answer, BaseConfig, QuestionType } from "../session";
+
+export const BRANCH_STATUSES = {
+  EXPLORING: "exploring",
+  DONE: "done",
+} as const;
+
+export type BranchStatus = (typeof BRANCH_STATUSES)[keyof typeof BRANCH_STATUSES];
+
+export interface BranchQuestion {
+  id: string;
+  type: QuestionType;
+  text: string;
+  config: BaseConfig;
+  answer?: Answer;
+  answeredAt?: number;
+}
+
+export interface Branch {
+  id: string;
+  scope: string;
+  status: BranchStatus;
+  questions: BranchQuestion[];
+  finding: string | null;
+}
+
+export interface BrainstormState {
+  session_id: string;
+  browser_session_id: string | null;
+  request: string;
+  created_at: number;
+  updated_at: number;
+  branches: Record<string, Branch>;
+  branch_order: string[];
+}
+
+export interface CreateBranchInput {
+  id: string;
+  scope: string;
+}
+
+export interface BranchProbeResult {
+  done: boolean;
+  reason: string;
+  finding?: string;
+  question?: {
+    type: QuestionType;
+    config: BaseConfig;
+  };
+}