@loicngr/kobo 1.7.6 → 1.7.8

package/dist/server/services/agent/engines/codex/event-mapper.js

@@ -0,0 +1,473 @@
+import { nanoid } from 'nanoid';
+// ── QUOTA_PATTERN ─────────────────────────────────────────────────────────────
+//
+// Loose enough to catch wording drift across OpenAI/Codex quota messages.
+// Patterns covered:
+//   - "rate limit reached" / "rate_limit exceeded"
+//   - "quota exceeded" / "insufficient_quota" / "insufficient quota"
+//   - "out of extra usage" / "out of usage"
+//   - "usage limit exceeded"
+export const QUOTA_PATTERN = /rate[_ ]limit|quota|usage limit|insufficient[_ ]quota|out of (extra )?usage/i;
+export function createMapperState(opts) {
+    return {
+        sessionStartedEmitted: false,
+        openMessages: new Map(),
+        sawErrorResult: false,
+        sawTurnInterrupted: false,
+        quotaErrorEmitted: false,
+        // Optional explicit prefix for deterministic testing; production code path
+        // generates a fresh nanoid-based prefix per engine.start() call.
+        sessionPrefix: opts?.sessionPrefix ?? `cdx_${nanoid(10)}`,
+    };
+}
+// ── tryEmitQuota ──────────────────────────────────────────────────────────────
+/**
+ * Emit an error/quota event exactly once per stream, regardless of which
+ * surface detected the quota condition. Also sets sawErrorResult so the engine
+ * can surface session:ended with reason='error'.
+ *
+ * Exported so the engine's stderr path can share the same one-shot guard.
+ */
+export function tryEmitQuota(state, emit, message) {
+    if (state.quotaErrorEmitted)
+        return;
+    state.quotaErrorEmitted = true;
+    state.sawErrorResult = true;
+    emit({ kind: 'error', category: 'quota', message });
+}
+// ── Internal helpers ──────────────────────────────────────────────────────────
+/** Push-array variant of tryEmitQuota for use inside handler functions. */
+function tryEmitQuotaInline(state, events, message) {
+    tryEmitQuota(state, (ev) => events.push(ev), message);
+}
+/**
+ * Scope item ids by a per-session prefix. Codex restarts item numbering
+ * (item_0, item_1, …) on each resume, so a fresh prefix prevents the client
+ * store from deduping the second turn's item_0 against the first.
+ */
+function scopedId(state, itemId) {
+    return `${state.sessionPrefix}_${itemId}`;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Emit session:started exactly once for this session.
+ * Idempotent — subsequent calls for the same threadId are no-ops.
+ */
+export function emitSessionStarted(threadId, state) {
+    if (state.sessionStartedEmitted)
+        return [];
+    state.sessionStartedEmitted = true;
+    state.sessionId = threadId;
+    return [{ kind: 'session:started', engineSessionId: threadId }];
+}
+/**
+ * Handle item/started notifications from the app-server.
+ */
+export function handleItemStarted(item, state) {
+    const events = [];
+    if (item.type === 'agentMessage') {
+        const text = item.text ?? '';
+        const messageId = scopedId(state, item.id);
+        state.openMessages.set(messageId, { sawText: text.length > 0 });
+        events.push({ kind: 'message:text', messageId, text, streaming: true });
+        return events;
+    }
+    if (item.type === 'commandExecution') {
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name: 'Bash',
+            input: { command: item.command },
+        });
+        return events;
+    }
+    if (item.type === 'fileChange') {
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name: 'Edit',
+            input: codexFileChangeToInput(item.changes ?? []),
+        });
+        return events;
+    }
+    if (item.type === 'mcpToolCall') {
+        const name = `mcp__${item.server}__${item.tool}`;
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name,
+            input: item.arguments,
+        });
+        return events;
+    }
+    if (item.type === 'webSearch') {
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name: 'WebSearch',
+            input: { query: item.query },
+        });
+        return events;
+    }
+    if (item.type === 'collabAgentToolCall') {
+        const toolCallId = scopedId(state, item.id);
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId,
+            name: 'Task',
+            input: {
+                codex_tool: item.tool,
+                description: item.prompt ?? item.tool,
+                prompt: item.prompt,
+                model: item.model,
+                sender_thread_id: item.senderThreadId,
+                receiver_thread_ids: item.receiverThreadIds,
+            },
+        });
+        events.push({
+            kind: 'subagent:progress',
+            toolCallId,
+            status: 'running',
+            description: item.prompt ?? item.tool,
+            taskType: item.tool,
+        });
+        return events;
+    }
+    if (item.type === 'dynamicToolCall') {
+        const name = item.namespace ? `${item.namespace}__${item.tool}` : item.tool;
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name,
+            input: item.arguments ?? {},
+        });
+        return events;
+    }
+    if (item.type === 'imageView') {
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name: 'Read',
+            input: { file_path: item.path },
+        });
+        return events;
+    }
+    if (item.type === 'imageGeneration') {
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name: 'ImageGeneration',
+            input: { revisedPrompt: item.revisedPrompt },
+        });
+        return events;
+    }
+    if (item.type === 'enteredReviewMode' || item.type === 'exitedReviewMode') {
+        const label = item.type === 'enteredReviewMode' ? 'review:start' : 'review:end';
+        events.push({
+            kind: 'message:thinking',
+            messageId: scopedId(state, item.id),
+            text: `[${label}] ${item.review}`,
+        });
+        return events;
+    }
+    if (item.type === 'contextCompaction') {
+        events.push({ kind: 'session:compacted' });
+        return events;
+    }
+    return events;
+}
+/**
+ * Handle item/completed notifications from the app-server.
+ */
+export function handleItemCompleted(item, state) {
+    const events = [];
+    if (item.type === 'agentMessage') {
+        const text = item.text ?? '';
+        const messageId = scopedId(state, item.id);
+        const open = state.openMessages.get(messageId);
+        // Skip the final emit when deltas already streamed the text — the client
+        // accumulates per-delta and would double-append on a fresh push.
+        const alreadyStreamed = open?.sawText === true;
+        if (!alreadyStreamed) {
+            events.push({ kind: 'message:text', messageId, text, streaming: false });
+        }
+        if (text.includes('[BRAINSTORM_COMPLETE]')) {
+            events.push({ kind: 'session:brainstorm-complete' });
+        }
+        if (QUOTA_PATTERN.test(text)) {
+            tryEmitQuotaInline(state, events, text);
+        }
+        events.push({ kind: 'message:end', messageId });
+        state.openMessages.delete(messageId);
+        return events;
+    }
+    if (item.type === 'reasoning') {
+        const text = [...(item.summary ?? []), ...(item.content ?? [])].join('\n');
+        events.push({ kind: 'message:thinking', messageId: scopedId(state, item.id), text });
+        return events;
+    }
+    if (item.type === 'commandExecution') {
+        events.push({
+            kind: 'tool:result',
+            toolCallId: scopedId(state, item.id),
+            output: { aggregated_output: item.aggregatedOutput ?? '', exit_code: item.exitCode },
+            isError: item.status === 'failed',
+        });
+        return events;
+    }
+    if (item.type === 'fileChange') {
+        events.push({
+            kind: 'tool:result',
+            toolCallId: scopedId(state, item.id),
+            output: { changes: item.changes ?? [], status: item.status },
+            isError: item.status === 'failed',
+        });
+        return events;
+    }
+    if (item.type === 'mcpToolCall') {
+        events.push({
+            kind: 'tool:result',
+            toolCallId: scopedId(state, item.id),
+            output: item.result ?? item.error ?? null,
+            isError: item.status === 'failed',
+        });
+        return events;
+    }
+    if (item.type === 'webSearch') {
+        events.push({
+            kind: 'tool:result',
+            toolCallId: scopedId(state, item.id),
+            output: { query: item.query },
+            isError: false,
+        });
+        return events;
+    }
+    if (item.type === 'collabAgentToolCall') {
+        const toolCallId = scopedId(state, item.id);
+        events.push({
+            kind: 'tool:result',
+            toolCallId,
+            output: {
+                codex_tool: item.tool,
+                status: item.status,
+                agents_states: item.agentsStates,
+            },
+            isError: item.status === 'failed',
+        });
+        events.push({
+            kind: 'subagent:progress',
+            toolCallId,
+            status: 'done',
+            description: item.prompt ?? item.tool,
+            taskType: item.tool,
+        });
+        return events;
+    }
+    if (item.type === 'dynamicToolCall') {
+        events.push({
+            kind: 'tool:result',
+            toolCallId: scopedId(state, item.id),
+            output: { contentItems: item.contentItems ?? [], success: item.success, durationMs: item.durationMs },
+            isError: item.status === 'failed' || item.success === false,
+        });
+        return events;
+    }
+    if (item.type === 'imageView') {
+        events.push({
+            kind: 'tool:result',
+            toolCallId: scopedId(state, item.id),
+            output: { file_path: item.path },
+            isError: false,
+        });
+        return events;
+    }
+    if (item.type === 'imageGeneration') {
+        events.push({
+            kind: 'tool:result',
+            toolCallId: scopedId(state, item.id),
+            output: { savedPath: item.savedPath, result: item.result, revisedPrompt: item.revisedPrompt },
+            isError: false,
+        });
+        return events;
+    }
+    if (item.type === 'plan') {
+        // Codex's `plan` is a markdown blob, not a structured list — parse bullets.
+        events.push({
+            kind: 'tool:call',
+            messageId: '',
+            toolCallId: scopedId(state, item.id),
+            name: 'TodoWrite',
+            input: { todos: parseCodexPlanText(item.text) },
+        });
+        return events;
+    }
+    if (item.type === 'error') {
+        if (QUOTA_PATTERN.test(item.message)) {
+            tryEmitQuotaInline(state, events, item.message);
+        }
+        else {
+            state.sawErrorResult = true;
+            events.push({ kind: 'error', category: 'other', message: item.message });
+        }
+        return events;
+    }
+    return events;
+}
+/**
+ * Map `item/agentMessage/delta` to a `message:text` increment.
+ * Marks `sawText` so the eventual `item/completed` doesn't re-emit the full
+ * text (the client accumulates per-delta — re-emit would double-append).
+ */
+export function handleAgentMessageDelta(delta, state) {
+    const messageId = scopedId(state, delta.itemId);
+    if (delta.delta.length > 0) {
+        const open = state.openMessages.get(messageId);
+        if (open) {
+            open.sawText = true;
+        }
+        else {
+            state.openMessages.set(messageId, { sawText: true });
+        }
+    }
+    return [{ kind: 'message:text', messageId, text: delta.delta, streaming: true }];
+}
+/**
+ * Handle `turn/completed`. Emits an `error` on `status=failed`, flags
+ * `sawTurnInterrupted` on `status=interrupted`. Token usage arrives on the
+ * separate `thread/tokenUsage/updated` notification.
+ */
+export function handleTurnCompleted(n, state) {
+    const events = [];
+    const { status, error } = n.turn;
+    if (status === 'failed') {
+        const msg = error?.message ?? 'turn failed';
+        if (QUOTA_PATTERN.test(msg)) {
+            tryEmitQuotaInline(state, events, msg);
+        }
+        else {
+            state.sawErrorResult = true;
+            events.push({ kind: 'error', category: 'other', message: msg });
+        }
+    }
+    else if (status === 'interrupted') {
+        // Engine reads this to emit `session:ended reason='killed'` when the
+        // turn was interrupted server-side without throwing.
+        state.sawTurnInterrupted = true;
+    }
+    return events;
+}
+/**
+ * Map `account/rateLimits/updated` to a `rate_limit` AgentEvent for the
+ * QuotaFooter. Translates Codex's unix-seconds `resetsAt` to ISO-8601.
+ */
+export function handleRateLimitsUpdated(payload, state) {
+    const p = payload;
+    const rl = p?.rateLimits;
+    if (!rl)
+        return [];
+    const buckets = [];
+    const toBucket = (id, win) => {
+        if (!win)
+            return;
+        const bucket = {
+            id,
+            usedPct: Math.max(0, Math.min(100, win.usedPercent)),
+        };
+        if (rl.limitName)
+            bucket.label = rl.limitName;
+        if (typeof win.resetsAt === 'number' && Number.isFinite(win.resetsAt)) {
+            bucket.resetsAt = new Date(win.resetsAt * 1000).toISOString();
+        }
+        buckets.push(bucket);
+    };
+    toBucket('primary', rl.primary ?? null);
+    toBucket('secondary', rl.secondary ?? null);
+    if (buckets.length === 0)
+        return [];
+    const reached = typeof rl.rateLimitReachedType === 'string' && rl.rateLimitReachedType.length > 0;
+    const maxPct = Math.max(...buckets.map((b) => b.usedPct));
+    const status = reached
+        ? 'rejected'
+        : maxPct >= 80
+            ? 'allowed_warning'
+            : 'allowed';
+    const events = [{ kind: 'rate_limit', info: { buckets, status } }];
+    if (reached) {
+        tryEmitQuotaInline(state, events, `Codex rate limit reached: ${rl.rateLimitReachedType}`);
+    }
+    return events;
+}
+// ── FileChange normalisation ──────────────────────────────────────────────────
+/**
+ * Normalise Codex's `fileChange` to the Claude-style `tool:call` input the
+ * renderer expects (`file_path` + unified `diff`). Without `file_path` the
+ * UI falls back to dumping raw JSON.
+ */
+export function codexFileChangeToInput(changes) {
+    if (changes.length === 0) {
+        return { file_path: '', diff: '', changes: [] };
+    }
+    const first = changes[0];
+    const kind = first.kind.type;
+    const movePath = first.kind.type === 'update' ? first.kind.move_path : null;
+    return {
+        file_path: first.path,
+        diff: first.diff,
+        change_kind: kind,
+        ...(movePath != null ? { move_path: movePath } : {}),
+        changes,
+    };
+}
+// ── Plan parsing ──────────────────────────────────────────────────────────────
+const BULLET_LINE = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/;
+const HEADING_LINE = /^\s*#{1,6}\s/;
+/**
+ * Split a markdown `plan` blob into individual todo items.
+ * Bullets (`-`, `*`, `+`, `1.`, `1)`) become items; headings are dropped;
+ * untagged continuation lines fold into the previous item.
+ */
+export function parseCodexPlanText(text) {
+    const lines = text.split('\n');
+    const items = [];
+    let current = null;
+    const flush = () => {
+        if (current != null) {
+            const trimmed = current.trim();
+            if (trimmed.length > 0)
+                items.push(trimmed);
+            current = null;
+        }
+    };
+    for (const raw of lines) {
+        if (HEADING_LINE.test(raw)) {
+            flush();
+            continue;
+        }
+        const match = raw.match(BULLET_LINE);
+        if (match) {
+            flush();
+            current = match[1].trim();
+            continue;
+        }
+        if (current != null) {
+            const cont = raw.trim();
+            current = cont.length > 0 ? `${current} ${cont}` : current;
+        }
+    }
+    flush();
+    if (items.length === 0) {
+        const trimmed = text.trim();
+        if (trimmed.length === 0)
+            return [];
+        return [{ content: trimmed, status: 'pending' }];
+    }
+    return items.map((content) => ({ content, status: 'pending' }));
+}

package/dist/server/services/agent/engines/codex/jsonrpc/peer.js

@@ -0,0 +1,60 @@
+import { createJsonRpcTransport } from './transport.js';
+export function createJsonRpcPeer(opts) {
+    let nextId = 1;
+    const pending = new Map();
+    const transport = createJsonRpcTransport({
+        stdin: opts.stdin,
+        stdout: opts.stdout,
+        onError: opts.onError ?? (() => { }),
+        onMessage(msg) {
+            // Response to one of our requests
+            if (msg.id != null && (msg.result !== undefined || msg.error !== undefined)) {
+                const slot = pending.get(msg.id);
+                if (!slot)
+                    return;
+                pending.delete(msg.id);
+                if (msg.error) {
+                    slot.reject(new Error(`JSON-RPC error ${msg.error.code}: ${msg.error.message}`));
+                }
+                else {
+                    slot.resolve(msg.result);
+                }
+                return;
+            }
+            // Server-initiated request (has id + method)
+            if (msg.id != null && msg.method) {
+                opts.onServerRequest(msg.id, msg.method, msg.params);
+                return;
+            }
+            // Notification (no id)
+            if (msg.method) {
+                opts.onNotification(msg.method, msg.params);
+            }
+        },
+    });
+    return {
+        request(method, params) {
+            const id = nextId++;
+            return new Promise((resolve, reject) => {
+                pending.set(id, { resolve: (v) => resolve(v), reject });
+                transport.send({ jsonrpc: '2.0', id, method, params });
+            });
+        },
+        notify(method, params) {
+            transport.send({ jsonrpc: '2.0', method, params });
+        },
+        respond(id, result) {
+            transport.send({ jsonrpc: '2.0', id, result });
+        },
+        respondError(id, code, message) {
+            transport.send({ jsonrpc: '2.0', id, error: { code, message } });
+        },
+        close() {
+            transport.close();
+            const err = new Error('peer closed');
+            for (const slot of pending.values())
+                slot.reject(err);
+            pending.clear();
+        },
+    };
+}

package/dist/server/services/agent/engines/codex/jsonrpc/transport.js

@@ -0,0 +1,31 @@
+export function createJsonRpcTransport(opts) {
+    let buffer = '';
+    opts.stdout.setEncoding?.('utf-8');
+    opts.stdout.on('data', (chunk) => {
+        buffer += chunk;
+        let nl = buffer.indexOf('\n');
+        while (nl >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            nl = buffer.indexOf('\n');
+            if (!line)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                opts.onMessage(parsed);
+            }
+            catch (err) {
+                opts.onError(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+    });
+    opts.stdout.on('error', opts.onError);
+    return {
+        send(msg) {
+            opts.stdin.write(`${JSON.stringify(msg)}\n`);
+        },
+        close() {
+            opts.stdin.end();
+        },
+    };
+}

package/dist/server/services/agent/engines/codex/options-builder.js

@@ -0,0 +1,81 @@
+const CODEX_KOBO_MCP_BRIEF = [
+    '[Kōbō MCP] This workspace exposes a dedicated MCP server named `kobo-tasks`. The Codex CLI surfaces its tools under the literal name `mcp__kobo-tasks__<tool>` — always use that full form when invoking them.',
+    'Plan mode: when running with a read-only sandbox, the read-only restriction applies to MCP tools too. Reads (`mcp__kobo-tasks__list_*`, `mcp__kobo-tasks__read_document`, `mcp__kobo-tasks__search_codebase`, `mcp__kobo-tasks__get_*`) are fine; mutations (`mcp__kobo-tasks__mark_task_done`, `mcp__kobo-tasks__log_thought`, `mcp__kobo-tasks__set_workspace_status`) must wait until the plan is approved.',
+    'Conventions — read these BEFORE starting work, not as a fallback:',
+    '• `mcp__kobo-tasks__list_tasks` first on any non-trivial turn, then `mcp__kobo-tasks__mark_task_done` as each item completes.',
+    '• `mcp__kobo-tasks__list_documents` / `mcp__kobo-tasks__read_document` to discover existing plans and specs under docs/ and .ai/thoughts/ before writing new ones.',
+    '• `mcp__kobo-tasks__log_thought` to persist notable decisions to `.ai/thoughts/<date>-<slug>.md`.',
+    '• `mcp__kobo-tasks__search_codebase` to recall prior chat history (conversations, not source — use shell tools for source).',
+    '• `mcp__kobo-tasks__get_workspace_info` / `mcp__kobo-tasks__get_git_info` / `mcp__kobo-tasks__get_notion_ticket` for context.',
+    '• `mcp__kobo-tasks__set_workspace_status` when the mission is done / blocked / idle.',
+    '• `mcp__kobo-tasks__schedule_wakeup` / `mcp__kobo-tasks__cancel_wakeup` to schedule (or cancel) a follow-up session.',
+    'Each tool carries its own "WHEN to use" guidance in its description — follow it.',
+].join('\n');
+export function buildCodexOptions(input) {
+    const isResume = input.resumeFromEngineSessionId !== undefined;
+    const threadParams = {
+        cwd: input.workingDir,
+        experimentalRawEvents: false,
+        persistExtendedHistory: false,
+    };
+    // Permission mode → (sandbox, approvalPolicy)
+    switch (input.agentPermissionMode) {
+        case 'plan':
+            threadParams.sandbox = 'read-only';
+            threadParams.approvalPolicy = 'never';
+            break;
+        case 'bypass':
+            threadParams.sandbox = 'workspace-write';
+            threadParams.approvalPolicy = 'never';
+            break;
+        case 'strict':
+            threadParams.sandbox = 'workspace-write';
+            threadParams.approvalPolicy = 'on-request';
+            break;
+        case 'interactive':
+            threadParams.sandbox = 'workspace-write';
+            threadParams.approvalPolicy = 'unless-trusted';
+            break;
+    }
+    // Model: omit when undefined or 'auto', let Codex use its default
+    if (input.model && input.model !== 'auto') {
+        threadParams.model = input.model;
+    }
+    // Effort: omit when undefined or 'auto'
+    if (input.effort && input.effort !== 'auto') {
+        threadParams.modelReasoningEffort = input.effort;
+    }
+    // `default_tools_approval_mode: 'auto'` pre-approves the namespace —
+    // without it Codex blocks every MCP tool call with "user cancelled".
+    if (input.mcpServers && input.mcpServers.length > 0) {
+        const mcpServersConfig = {};
+        for (const srv of input.mcpServers) {
+            mcpServersConfig[srv.name] = {
+                command: srv.command,
+                args: srv.args,
+                env: srv.env,
+                default_tools_approval_mode: 'auto',
+            };
+        }
+        threadParams.config = { mcp_servers: mcpServersConfig };
+    }
+    const effectivePrompt = isResume ? input.prompt : `${CODEX_KOBO_MCP_BRIEF}\n\n${input.prompt}`;
+    // Always emit collaborationMode — it's sticky server-side, so omitting it
+    // would leave a resumed thread stuck in the previous turn's mode. Plan also
+    // gates the `request_user_input` internal tool. Settings echo the resolved
+    // model/effort because collaborationMode takes precedence over them.
+    const collaborationMode = {
+        mode: input.agentPermissionMode === 'plan' ? 'plan' : 'default',
+        settings: {
+            model: threadParams.model ?? 'auto',
+            reasoning_effort: threadParams.modelReasoningEffort ?? null,
+            developer_instructions: null,
+        },
+    };
+    return {
+        threadParams,
+        input: [{ type: 'text', text: effectivePrompt }],
+        isResume,
+        collaborationMode,
+    };
+}

package/dist/server/services/agent/engines/codex/protocol/types.js

@@ -0,0 +1,11 @@
+/**
+ * Codex app-server JSON-RPC protocol — minimal type subset for Kōbō.
+ *
+ * Hand-written from the canonical generated bindings in
+ * docs/superpowers/plans/codex-generated-bindings/v2/
+ * and verified against the live wire capture (2026-05-11).
+ *
+ * Only the types needed by the Kōbō engine are included here.
+ * The full generated set (85+ files) is preserved in docs/ for reference.
+ */
+export {};