octto 0.1.0

package/dist/session/browser.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Opens the default browser to the specified URL.
+ * Detects platform and uses appropriate command.
+ */
+export declare function openBrowser(url: string): Promise<void>;

package/dist/session/index.d.ts

@@ -0,0 +1,4 @@
+export type { SessionStore, SessionStoreOptions } from "./sessions";
+export { createSessionStore } from "./sessions";
+export type { Answer, AskCodeAnswer, AskFileAnswer, AskImageAnswer, AskTextAnswer, BaseConfig, ConfirmAnswer, EmojiReactAnswer, PickManyAnswer, PickOneAnswer, QuestionAnswers, QuestionConfig, QuestionType, RankAnswer, RateAnswer, ReviewAnswer, ShowOptionsAnswer, SliderAnswer, ThumbsAnswer, } from "./types";
+export { QUESTION_TYPES, QUESTIONS, STATUSES, WS_MESSAGES } from "./types";

package/dist/session/server.d.ts

@@ -0,0 +1,10 @@
+import type { Server } from "bun";
+import type { SessionStore } from "./sessions";
+interface WsData {
+    sessionId: string;
+}
+export declare function createServer(sessionId: string, store: SessionStore): Promise<{
+    server: Server<WsData>;
+    port: number;
+}>;
+export {};

package/dist/session/sessions.d.ts

@@ -0,0 +1,23 @@
+import type { ServerWebSocket } from "bun";
+import { type BaseConfig, type EndSessionOutput, type GetAnswerInput, type GetAnswerOutput, type GetNextAnswerInput, type GetNextAnswerOutput, type ListQuestionsOutput, type PushQuestionOutput, type QuestionType, type Session, type StartSessionInput, type StartSessionOutput, type WsClientMessage } from "./types";
+export interface SessionStoreOptions {
+    /** Skip opening browser - useful for tests */
+    skipBrowser?: boolean;
+}
+export interface SessionStore {
+    startSession: (input: StartSessionInput) => Promise<StartSessionOutput>;
+    endSession: (sessionId: string) => Promise<EndSessionOutput>;
+    pushQuestion: (sessionId: string, type: QuestionType, config: BaseConfig) => PushQuestionOutput;
+    getAnswer: (input: GetAnswerInput) => Promise<GetAnswerOutput>;
+    getNextAnswer: (input: GetNextAnswerInput) => Promise<GetNextAnswerOutput>;
+    cancelQuestion: (questionId: string) => {
+        ok: boolean;
+    };
+    listQuestions: (sessionId?: string) => ListQuestionsOutput;
+    handleWsConnect: (sessionId: string, ws: ServerWebSocket<unknown>) => void;
+    handleWsDisconnect: (sessionId: string) => void;
+    handleWsMessage: (sessionId: string, message: WsClientMessage) => void;
+    getSession: (sessionId: string) => Session | undefined;
+    cleanup: () => Promise<void>;
+}
+export declare function createSessionStore(options?: SessionStoreOptions): SessionStore;

package/dist/session/types.d.ts

@@ -0,0 +1,219 @@
+import type { ServerWebSocket } from "bun";
+import type { AskCodeConfig, AskFileConfig, AskImageConfig, AskTextConfig, ConfirmConfig, EmojiReactConfig, PickManyConfig, PickOneConfig, RankConfig, RateConfig, ReviewSectionConfig, ShowDiffConfig, ShowOptionsConfig, ShowPlanConfig, SliderConfig, ThumbsConfig } from "../types";
+export declare const STATUSES: {
+    readonly PENDING: "pending";
+    readonly ANSWERED: "answered";
+    readonly CANCELLED: "cancelled";
+    readonly TIMEOUT: "timeout";
+    readonly NONE_PENDING: "none_pending";
+};
+export type QuestionStatus = (typeof STATUSES)[Exclude<keyof typeof STATUSES, "NONE_PENDING">];
+export interface Question {
+    id: string;
+    sessionId: string;
+    type: QuestionType;
+    config: BaseConfig;
+    status: QuestionStatus;
+    createdAt: Date;
+    answeredAt?: Date;
+    response?: Answer;
+    /** True if this answer was already returned via get_next_answer */
+    retrieved?: boolean;
+}
+export declare const QUESTIONS: {
+    readonly PICK_ONE: "pick_one";
+    readonly PICK_MANY: "pick_many";
+    readonly CONFIRM: "confirm";
+    readonly RANK: "rank";
+    readonly RATE: "rate";
+    readonly ASK_TEXT: "ask_text";
+    readonly ASK_IMAGE: "ask_image";
+    readonly ASK_FILE: "ask_file";
+    readonly ASK_CODE: "ask_code";
+    readonly SHOW_DIFF: "show_diff";
+    readonly SHOW_PLAN: "show_plan";
+    readonly SHOW_OPTIONS: "show_options";
+    readonly REVIEW_SECTION: "review_section";
+    readonly THUMBS: "thumbs";
+    readonly EMOJI_REACT: "emoji_react";
+    readonly SLIDER: "slider";
+};
+export type QuestionType = (typeof QUESTIONS)[keyof typeof QUESTIONS];
+export declare const QUESTION_TYPES: ("pick_one" | "pick_many" | "confirm" | "rank" | "rate" | "ask_text" | "ask_image" | "ask_file" | "ask_code" | "show_diff" | "show_plan" | "show_options" | "review_section" | "thumbs" | "emoji_react" | "slider")[];
+export interface PickOneAnswer {
+    selected: string;
+}
+export interface PickManyAnswer {
+    selected: string[];
+}
+export interface ConfirmAnswer {
+    choice: "yes" | "no" | "cancel";
+}
+export interface ThumbsAnswer {
+    choice: "up" | "down";
+}
+export interface EmojiReactAnswer {
+    emoji: string;
+}
+export interface AskTextAnswer {
+    text: string;
+}
+export interface SliderAnswer {
+    value: number;
+}
+export interface RankAnswer {
+    ranking: Array<{
+        id: string;
+        rank: number;
+    }>;
+}
+export interface RateAnswer {
+    ratings: Record<string, number>;
+}
+export interface AskCodeAnswer {
+    code: string;
+}
+export interface AskImageAnswer {
+    images: Array<{
+        name: string;
+        data: string;
+        type: string;
+    }>;
+}
+export interface AskFileAnswer {
+    files: Array<{
+        name: string;
+        data: string;
+        type: string;
+    }>;
+}
+export interface ReviewAnswer {
+    decision: string;
+    feedback?: string;
+}
+export interface ShowOptionsAnswer {
+    selected: string;
+    feedback?: string;
+}
+export type Answer = PickOneAnswer | PickManyAnswer | ConfirmAnswer | ThumbsAnswer | EmojiReactAnswer | AskTextAnswer | SliderAnswer | RankAnswer | RateAnswer | AskCodeAnswer | AskImageAnswer | AskFileAnswer | ReviewAnswer | ShowOptionsAnswer;
+export interface QuestionAnswers {
+    [QUESTIONS.PICK_ONE]: PickOneAnswer;
+    [QUESTIONS.PICK_MANY]: PickManyAnswer;
+    [QUESTIONS.CONFIRM]: ConfirmAnswer;
+    [QUESTIONS.THUMBS]: ThumbsAnswer;
+    [QUESTIONS.EMOJI_REACT]: EmojiReactAnswer;
+    [QUESTIONS.ASK_TEXT]: AskTextAnswer;
+    [QUESTIONS.SLIDER]: SliderAnswer;
+    [QUESTIONS.RANK]: RankAnswer;
+    [QUESTIONS.RATE]: RateAnswer;
+    [QUESTIONS.ASK_CODE]: AskCodeAnswer;
+    [QUESTIONS.ASK_IMAGE]: AskImageAnswer;
+    [QUESTIONS.ASK_FILE]: AskFileAnswer;
+    [QUESTIONS.SHOW_DIFF]: ReviewAnswer;
+    [QUESTIONS.SHOW_PLAN]: ReviewAnswer;
+    [QUESTIONS.REVIEW_SECTION]: ReviewAnswer;
+    [QUESTIONS.SHOW_OPTIONS]: ShowOptionsAnswer;
+}
+export type QuestionConfig = PickOneConfig | PickManyConfig | ConfirmConfig | RankConfig | RateConfig | AskTextConfig | AskImageConfig | AskFileConfig | AskCodeConfig | ShowDiffConfig | ShowPlanConfig | ShowOptionsConfig | ReviewSectionConfig | ThumbsConfig | EmojiReactConfig | SliderConfig;
+/** Config type for transit - accepts both strict QuestionConfig and loose objects */
+export type BaseConfig = QuestionConfig | {
+    question?: string;
+    context?: string;
+    [key: string]: unknown;
+};
+export interface Session {
+    id: string;
+    title?: string;
+    port: number;
+    url: string;
+    createdAt: Date;
+    questions: Map<string, Question>;
+    wsConnected: boolean;
+    server?: ReturnType<typeof Bun.serve>;
+    wsClient?: ServerWebSocket<unknown>;
+}
+export interface InitialQuestion {
+    type: QuestionType;
+    config: BaseConfig;
+}
+export interface StartSessionInput {
+    title?: string;
+    /** Initial questions to display immediately when browser opens */
+    questions?: InitialQuestion[];
+}
+export interface StartSessionOutput {
+    session_id: string;
+    url: string;
+    /** IDs of initial questions if any were provided */
+    question_ids?: string[];
+}
+export interface EndSessionOutput {
+    ok: boolean;
+}
+export interface PushQuestionOutput {
+    question_id: string;
+}
+export interface GetAnswerInput {
+    question_id: string;
+    block?: boolean;
+    timeout?: number;
+}
+export interface GetAnswerOutput {
+    completed: boolean;
+    status: QuestionStatus;
+    response?: Answer;
+    reason?: "timeout" | "cancelled" | "pending";
+}
+export interface GetNextAnswerInput {
+    session_id: string;
+    block?: boolean;
+    timeout?: number;
+}
+export type AnswerStatus = (typeof STATUSES)[keyof typeof STATUSES];
+export interface GetNextAnswerOutput {
+    completed: boolean;
+    question_id?: string;
+    question_type?: QuestionType;
+    status: AnswerStatus;
+    response?: Answer;
+    reason?: typeof STATUSES.TIMEOUT | typeof STATUSES.NONE_PENDING;
+}
+export interface ListQuestionsOutput {
+    questions: Array<{
+        id: string;
+        type: QuestionType;
+        status: QuestionStatus;
+        createdAt: string;
+        answeredAt?: string;
+    }>;
+}
+export declare const WS_MESSAGES: {
+    readonly QUESTION: "question";
+    readonly CANCEL: "cancel";
+    readonly END: "end";
+    readonly RESPONSE: "response";
+    readonly CONNECTED: "connected";
+};
+export interface WsQuestionMessage {
+    type: "question";
+    id: string;
+    questionType: QuestionType;
+    config: BaseConfig;
+}
+export interface WsCancelMessage {
+    type: "cancel";
+    id: string;
+}
+export interface WsEndMessage {
+    type: "end";
+}
+export interface WsResponseMessage {
+    type: "response";
+    id: string;
+    answer: Answer;
+}
+export interface WsConnectedMessage {
+    type: "connected";
+}
+export type WsServerMessage = WsQuestionMessage | WsCancelMessage | WsEndMessage;
+export type WsClientMessage = WsResponseMessage | WsConnectedMessage;

package/dist/session/waiter.d.ts

@@ -0,0 +1,31 @@
+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 declare function createWaiters<K, T>(): Waiters<K, T>;
+/**
+ * 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 declare function waitForResponse<K, T>(waiters: Waiters<K, T>, key: K, timeoutMs: number): Promise<WaitResult<T>>;

package/dist/state/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./persistence";
+export * from "./store";
+export * from "./types";

package/dist/state/persistence.d.ts

@@ -0,0 +1,8 @@
+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[]>;
+}
+export declare function createStatePersistence(baseDir?: string): StatePersistence;

package/dist/state/store.d.ts

@@ -0,0 +1,14 @@
+import type { Answer } from "@/session";
+import { 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 declare function createStateStore(baseDir?: string): StateStore;

package/dist/state/types.d.ts

@@ -0,0 +1,43 @@
+import type { Answer, BaseConfig, QuestionType } from "@/session";
+export declare const BRANCH_STATUSES: {
+    readonly EXPLORING: "exploring";
+    readonly DONE: "done";
+};
+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;
+    };
+}

package/dist/tools/brainstorm.d.ts

@@ -0,0 +1,3 @@
+import type { SessionStore } from "@/session";
+import type { OcttoTools, OpencodeClient } from "./types";
+export declare function createBrainstormTools(sessions: SessionStore, client: OpencodeClient): OcttoTools;

package/dist/tools/extractor.d.ts

@@ -0,0 +1,2 @@
+import type { Answer, QuestionType } from "@/session";
+export declare function extractAnswerSummary(type: QuestionType, answer: Answer): string;

package/dist/tools/factory.d.ts

@@ -0,0 +1,16 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import type { BaseConfig, QuestionType, SessionStore } from "@/session";
+import type { OcttoTool, OcttoTools } from "./types";
+type ArgsSchema = Parameters<typeof tool>[0]["args"];
+interface QuestionToolConfig<T> {
+    type: QuestionType;
+    description: string;
+    args: ArgsSchema;
+    validate?: (args: T) => string | null;
+    toConfig: (args: T) => BaseConfig;
+}
+export declare function createQuestionToolFactory(sessions: SessionStore): <T extends {
+    session_id: string;
+}>(config: QuestionToolConfig<T>) => OcttoTool;
+export declare function createPushQuestionTool(sessions: SessionStore): OcttoTools;
+export {};

package/dist/tools/formatters.d.ts

@@ -0,0 +1,6 @@
+import type { BrainstormState, Branch } from "@/state";
+export declare function formatBranchFinding(branch: Branch): string;
+export declare function formatBranchStatus(branch: Branch): string;
+export declare function formatFindings(state: BrainstormState): string;
+export declare function formatFindingsList(state: BrainstormState): string;
+export declare function formatQASummary(branch: Branch): string;

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { SessionStore } from "@/session";
+import type { OcttoTools, OpencodeClient } from "./types";
+export declare function createOcttoTools(sessions: SessionStore, client: OpencodeClient): OcttoTools;

package/dist/tools/processor.d.ts

@@ -0,0 +1,4 @@
+import type { Answer, SessionStore } from "@/session";
+import { type StateStore } from "@/state";
+import type { OpencodeClient } from "./types";
+export declare function processAnswer(stateStore: StateStore, sessions: SessionStore, sessionId: string, browserSessionId: string, questionId: string, answer: Answer, client: OpencodeClient): Promise<void>;

package/dist/tools/questions.d.ts

@@ -0,0 +1,3 @@
+import type { SessionStore } from "@/session";
+import type { OcttoTools } from "./types";
+export declare function createQuestionTools(sessions: SessionStore): OcttoTools;

package/dist/tools/responses.d.ts

@@ -0,0 +1,3 @@
+import { type SessionStore } from "@/session";
+import type { OcttoTools } from "./types";
+export declare function createResponseTools(sessions: SessionStore): OcttoTools;

package/dist/tools/session.d.ts

@@ -0,0 +1,3 @@
+import type { SessionStore } from "@/session";
+import type { OcttoTools } from "./types";
+export declare function createSessionTools(sessions: SessionStore): OcttoTools;

package/dist/tools/types.d.ts

@@ -0,0 +1,9 @@
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+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>;

package/dist/tools/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function generateSessionId(): string;
+export declare function generateQuestionId(): string;