@axplusb/kepler 0.0.1 → 1.0.0

package/src/core/session.mjs

@@ -0,0 +1,143 @@
+/**
+ * Session Manager — save, resume, and teleport sessions.
+ *
+ * Sessions are stored at ~/.claude/projects/<hash>/session.json
+ * and contain conversation history, token usage, and metadata.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+
+export class SessionManager {
+    constructor(projectDir = process.cwd()) {
+        this.projectDir = projectDir;
+        this.sessionId = `sess_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+        this.conversationId = null;
+        this.startedAt = new Date().toISOString();
+    }
+
+    /**
+     * Get the session storage directory for the current project.
+     */
+    getSessionDir() {
+        const hash = crypto.createHash('sha256')
+            .update(this.projectDir)
+            .digest('hex')
+            .slice(0, 16);
+
+        return path.join(os.homedir(), '.claude', 'projects', hash);
+    }
+
+    /**
+     * Save the current session state.
+     * @param {object} state - agent loop state to save
+     */
+    save(state) {
+        const dir = this.getSessionDir();
+        fs.mkdirSync(dir, { recursive: true });
+
+        const session = {
+            id: this.sessionId,
+            conversationId: this.conversationId,
+            projectDir: this.projectDir,
+            startedAt: this.startedAt,
+            savedAt: new Date().toISOString(),
+            model: state.model,
+            turnCount: state.turnCount,
+            tokenUsage: state.tokenUsage,
+            messages: state.messages,
+            systemPrompt: state.systemPrompt,
+        };
+
+        const filePath = path.join(dir, 'session.json');
+        fs.writeFileSync(filePath, JSON.stringify(session, null, 2));
+        return filePath;
+    }
+
+    /**
+     * Resume a saved session.
+     * @param {object} state - agent loop state to restore into
+     * @returns {boolean} true if session was restored
+     */
+    resume(state) {
+        const dir = this.getSessionDir();
+        const filePath = path.join(dir, 'session.json');
+
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const session = JSON.parse(raw);
+
+            state.messages = session.messages || [];
+            state.turnCount = session.turnCount || 0;
+            state.tokenUsage = session.tokenUsage || { input: 0, output: 0 };
+            if (session.model) state.model = session.model;
+
+            this.sessionId = session.id;
+            this.conversationId = session.conversationId;
+            this.startedAt = session.startedAt;
+
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Export session for teleport (transfer between machines).
+     * @param {object} state - agent loop state
+     * @returns {string} base64-encoded session data
+     */
+    exportForTeleport(state) {
+        const session = {
+            id: this.sessionId,
+            projectDir: this.projectDir,
+            messages: state.messages,
+            turnCount: state.turnCount,
+            model: state.model,
+            exportedAt: new Date().toISOString(),
+        };
+
+        return Buffer.from(JSON.stringify(session)).toString('base64');
+    }
+
+    /**
+     * Import a teleported session.
+     * @param {string} data - base64-encoded session data
+     * @param {object} state - agent loop state to restore into
+     */
+    importFromTeleport(data, state) {
+        const session = JSON.parse(Buffer.from(data, 'base64').toString());
+        state.messages = session.messages || [];
+        state.turnCount = session.turnCount || 0;
+        if (session.model) state.model = session.model;
+        this.sessionId = `sess_teleport_${Date.now()}`;
+    }
+
+    /**
+     * Get session info.
+     */
+    info() {
+        return {
+            id: this.sessionId,
+            conversationId: this.conversationId,
+            projectDir: this.projectDir,
+            startedAt: this.startedAt,
+            sessionDir: this.getSessionDir(),
+        };
+    }
+
+    /**
+     * Delete the saved session.
+     */
+    clear() {
+        const filePath = path.join(this.getSessionDir(), 'session.json');
+        try {
+            fs.unlinkSync(filePath);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+}

package/src/core/settings-sync.mjs

@@ -0,0 +1,85 @@
+/**
+ * Settings Sync — fetch user settings from Tarang web and cache locally.
+ *
+ * Syncs: gateway_type, model preferences, configured providers.
+ * Cached in ~/.orca/config.json alongside auth token.
+ */
+
+import { resolveWebUrl } from './backend-url.mjs';
+
+/**
+ * Fetch user settings from the web API using CLI token.
+ * @param {string} token - CLI auth token (orca_xxx)
+ * @returns {Promise<Object|null>} Settings object or null on failure
+ */
+export async function fetchRemoteSettings(token) {
+    if (!token) return null;
+
+    const webUrl = resolveWebUrl();
+    const url = `${webUrl}/api/cli/settings`;
+
+    try {
+        const resp = await fetch(url, {
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            signal: AbortSignal.timeout(10_000),
+        });
+
+        if (!resp.ok) {
+            if (resp.status === 401) {
+                process.stderr.write('\x1b[33mSettings sync: token expired or invalid. Run `orca login` to re-authenticate.\x1b[0m\n');
+            }
+            return null;
+        }
+
+        return await resp.json();
+    } catch (err) {
+        // Network error — silently fail, use cached settings
+        return null;
+    }
+}
+
+/**
+ * Merge remote settings into local config.
+ * Remote settings override local only for fields that are set.
+ * @param {Object} localConfig - Current ~/.orca/config.json content
+ * @param {Object} remote - Settings from fetchRemoteSettings()
+ * @returns {Object} Merged config to save
+ */
+export function mergeRemoteSettings(localConfig, remote) {
+    if (!remote) return localConfig;
+
+    const merged = { ...localConfig };
+
+    // Gateway type
+    if (remote.gateway_type) {
+        merged.gateway_type = remote.gateway_type;
+    }
+
+    // Model preferences
+    if (remote.models) {
+        merged.models = {
+            ...(merged.models || {}),
+            ...Object.fromEntries(
+                Object.entries(remote.models).filter(([, v]) => v != null)
+            ),
+        };
+    }
+
+    // Configured providers list (informational)
+    if (remote.configured_providers) {
+        merged.configured_providers = remote.configured_providers;
+    }
+
+    // Gateway config (non-secret, e.g. azure endpoint, aws region)
+    if (remote.gateway_config && Object.keys(remote.gateway_config).length > 0) {
+        merged.gateway_config = remote.gateway_config;
+    }
+
+    // Timestamp
+    merged.last_synced_at = new Date().toISOString();
+
+    return merged;
+}

package/src/core/stagnation.mjs

@@ -0,0 +1,57 @@
+export const DEFAULT_STAGNATION_THRESHOLD = 3;
+
+function canonicalize(value) {
+    if (Array.isArray(value)) return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.keys(value)
+                .sort()
+                .map(key => [key, canonicalize(value[key])]),
+        );
+    }
+    return value;
+}
+
+export function createStagnationTracker({
+    enabled = true,
+    threshold = DEFAULT_STAGNATION_THRESHOLD,
+} = {}) {
+    const effectiveThreshold = Number.isInteger(threshold) && threshold >= 2
+        ? threshold
+        : DEFAULT_STAGNATION_THRESHOLD;
+    let previousSignature = null;
+    let consecutiveCount = 0;
+
+    return {
+        record(tool, input) {
+            if (!enabled) return { detected: false, count: 0 };
+
+            const signature = JSON.stringify({
+                tool,
+                input: canonicalize(input || {}),
+            });
+            if (signature === previousSignature) {
+                consecutiveCount++;
+            } else {
+                previousSignature = signature;
+                consecutiveCount = 1;
+            }
+
+            return {
+                detected: consecutiveCount >= effectiveThreshold,
+                count: consecutiveCount,
+            };
+        },
+
+        reset() {
+            previousSignature = null;
+            consecutiveCount = 0;
+        },
+    };
+}
+
+export function stagnationMessage(tool, count) {
+    return `STAGNATION WARNING: Tool "${tool}" was called ${count} consecutive times ` +
+        `with identical arguments. The duplicate call was skipped. Review the previous ` +
+        `result, change the arguments, try another tool, or finish the task.`;
+}

package/src/core/stream-client.mjs

@@ -0,0 +1,367 @@
+/**
+ * TarangStreamClient — SSE consumer for Tarang backend.
+ *
+ * Replaces OCC's agent-loop.mjs. Instead of calling the LLM API directly,
+ * this client POSTs to the Tarang backend, parses the SSE stream, intercepts
+ * tool_request/tool_call events (executes locally, POSTs callback), and
+ * yields all other events to the caller for rendering.
+ *
+ * Phase 2: handles all 22 event types. Approval flow integrated.
+ */
+
+import { sendCallback, sendSkippedCallback, sendApprovalDecision } from './callback-client.mjs';
+import { ApprovalManager } from './approval.mjs';
+
+export const EVENT_TYPES = Object.freeze({
+    // Phase 1 — handled
+    STATUS: 'status',
+    TOOL_REQUEST: 'tool_request',
+    TOOL_CALL: 'tool_call',
+    PLAN: 'plan',
+    ERROR: 'error',
+    COMPLETE: 'complete',
+    // Phase 2 — stubbed
+    SESSION_INFO: 'session_info',
+    TOOL_DONE: 'tool_done',
+    THINKING: 'thinking',
+    PHASE_UPDATE: 'phase_update',
+    PHASE_SUMMARY: 'phase_summary',
+    PHASE_START: 'phase_start',
+    WORKER_UPDATE: 'worker_update',
+    WORKER_START: 'worker_start',
+    WORKER_DONE: 'worker_done',
+    DELEGATION: 'delegation',
+    CHANGE: 'change',
+    CONTENT: 'content',
+    CONTENT_PARTIAL: 'content_partial',
+    TOOL_RESULT: 'tool_result',
+    SUB_AGENT_START: 'sub_agent_start',
+    SUB_AGENT_TOOL: 'sub_agent_tool',
+    SUB_AGENT_COMPLETE: 'sub_agent_complete',
+    STAGNATION: 'stagnation',
+    CANCELLED: 'cancelled',
+    PAUSED: 'paused',
+    RESUMED: 'resumed',
+    PAUSE_INSTRUCTION: 'pause_instruction',
+    // HITL approval events (from framework)
+    APPROVAL_REQUIRED: 'approval_required',
+    APPROVAL_GRANTED: 'approval_granted',
+    APPROVAL_DENIED: 'approval_denied',
+});
+
+export class TarangStreamClient {
+    /**
+     * @param {Object} opts
+     * @param {string} opts.baseUrl - Tarang backend URL
+     * @param {string} opts.token - CLI auth token
+     * @param {Object} opts.toolExecutor - { execute(name, args) }
+     * @param {boolean} [opts.verbose=false]
+     */
+    constructor({ baseUrl, token, toolExecutor, verbose = false, approvalManager = null }) {
+        this.baseUrl = (baseUrl || '').replace(/\/$/, '');
+        this.token = token;
+        this.toolExecutor = toolExecutor;
+        this.verbose = verbose;
+        this.approval = approvalManager || new ApprovalManager();
+        this.currentTaskId = null;
+        this.sessionId = null;  // Set by backend on first turn, reused on subsequent turns
+        this._cancelled = false;
+        this._paused = false;
+    }
+
+    /**
+     * Execute an instruction via SSE stream.
+     * Yields parsed events. Client-side tool requests are shown, executed
+     * locally, callback-posted, then followed by a local tool_result event.
+     *
+     * @param {string} instruction
+     * @param {Object} [context={}]
+     * @param {string} [model]
+     * @yields {{ type: string, data: Object }}
+     */
+    async *execute(instruction, context = {}, messages = null) {
+        this._cancelled = false;
+
+        const url = `${this.baseUrl}/api/execute`;
+        const body = { instruction, context };
+        if (messages && messages.length > 0) body.messages = messages;
+        if (this.sessionId) body.session_id = this.sessionId;
+
+        const headers = {
+            'Accept': 'text/event-stream',
+            'Content-Type': 'application/json',
+        };
+        if (this.token) headers['Authorization'] = `Bearer ${this.token}`;
+
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            });
+        } catch (err) {
+            yield { type: EVENT_TYPES.ERROR, data: { message: `Network error: ${err.message}. Check your connection or use --local mode.`, fatal: true } };
+            return;
+        }
+
+        if (response.status === 401) {
+            yield { type: EVENT_TYPES.ERROR, data: { message: 'Authentication failed. Run `orca login` to re-authenticate.', fatal: true } };
+            return;
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => 'Unknown error');
+            yield { type: EVENT_TYPES.ERROR, data: { message: `Backend error ${response.status}: ${text}`, fatal: true } };
+            return;
+        }
+
+        // Grab task ID from response header
+        this.currentTaskId = response.headers.get('X-Task-ID') || null;
+
+        // Parse SSE stream
+        for await (const { event, data } of this._parseSSE(response)) {
+            if (this._cancelled) {
+                yield { type: EVENT_TYPES.STATUS, data: { message: 'Cancelled by user.' } };
+                return;
+            }
+
+            // Capture session_id from backend (first turn creates it, subsequent turns reuse)
+            if (event === EVENT_TYPES.SESSION_INFO && data?.session_id) {
+                this.sessionId = data.session_id;
+            }
+
+            // Framework HITL: approval_required — show menu, POST decision
+            if (event === EVENT_TYPES.APPROVAL_REQUIRED) {
+                yield { type: event, data }; // Show to user (renders "Approval needed: write_file")
+                const approvalEvent = await this._handleApprovalRequired(data);
+                if (approvalEvent) yield approvalEvent;
+                continue;
+            }
+
+            // Framework HITL: approval result events — yield for rendering
+            if (event === EVENT_TYPES.APPROVAL_GRANTED || event === EVENT_TYPES.APPROVAL_DENIED) {
+                yield { type: event, data };
+                continue;
+            }
+
+            // Tool requests — show to user, then execute locally and POST callback
+            // NOTE: With framework HITL enabled, tool_call events no longer carry
+            // require_approval — the framework handles that via approval_required above.
+            // This path remains for backwards compatibility with older backends.
+            if (event === EVENT_TYPES.TOOL_REQUEST || event === EVENT_TYPES.TOOL_CALL) {
+                yield { type: event, data }; // Show tool call to user first
+                if (data?.server_side) continue;
+                const toolEvent = await this._handleToolRequest(data);
+                if (toolEvent) yield toolEvent;
+                continue;
+            }
+
+            // All other events yielded to caller
+            yield { type: event, data };
+        }
+    }
+
+    /**
+     * Parse SSE from a fetch Response using ReadableStream.
+     * @param {Response} response
+     * @yields {{ event: string, data: Object }}
+     */
+    async *_parseSSE(response) {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let currentEvent = 'message';
+        let currentData = [];
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop(); // keep incomplete last line
+
+                for (const line of lines) {
+                    const trimmed = line.trim();
+
+                    if (!trimmed) {
+                        // Empty line = event boundary
+                        if (currentData.length > 0) {
+                            const rawData = currentData.join('\n');
+                            let parsed;
+                            try {
+                                parsed = JSON.parse(rawData);
+                            } catch {
+                                parsed = { message: rawData };
+                            }
+                            yield { event: currentEvent, data: parsed };
+                        }
+                        currentEvent = 'message';
+                        currentData = [];
+                    } else if (trimmed.startsWith('event:')) {
+                        currentEvent = trimmed.slice(6).trim();
+                    } else if (trimmed.startsWith('data:')) {
+                        currentData.push(trimmed.slice(5).trim());
+                    }
+                    // ignore other fields (id:, retry:, comments)
+                }
+            }
+
+            // Flush remaining
+            if (currentData.length > 0) {
+                const rawData = currentData.join('\n');
+                let parsed;
+                try {
+                    parsed = JSON.parse(rawData);
+                } catch {
+                    parsed = { message: rawData };
+                }
+                yield { event: currentEvent, data: parsed };
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    }
+
+    /**
+     * Handle a tool_call event: execute tool locally, POST result via callback.
+     *
+     * Approval is handled by the framework (HITL) BEFORE this is called.
+     * By the time a tool_call arrives here, it's already approved.
+     *
+     * @param {Object} data - { call_id, tool, args }
+     * @returns {Object} local tool result event to yield
+     */
+    async _handleToolRequest(data) {
+        const { call_id, request_id, tool, args } = data;
+        const callId = call_id || request_id;
+        const toolName = tool;
+
+        if (this.verbose) {
+            process.stderr.write(`\x1b[2m[tool] ${toolName}(${JSON.stringify(args).slice(0, 80)}...)\x1b[0m\n`);
+        }
+
+        // Execute tool locally — framework already approved this
+        const startTime = Date.now();
+        let result;
+        try {
+            result = await this.toolExecutor.execute(toolName, args || {});
+        } catch (err) {
+            result = { success: false, output: `Tool execution error: ${err.message}` };
+        }
+        const durationMs = Date.now() - startTime;
+
+        if (this.verbose) {
+            const status = result.success ? 'OK' : 'FAIL';
+            process.stderr.write(`\x1b[2m[tool] ${toolName} → ${status} (${durationMs}ms)\x1b[0m\n`);
+        }
+
+        // POST callback to backend
+        if (this.currentTaskId && callId) {
+            await sendCallback(this.baseUrl, this.token, this.currentTaskId, callId, result);
+        }
+
+        return {
+            type: EVENT_TYPES.TOOL_RESULT,
+            data: {
+                ...result,
+                call_id: callId,
+                tool: toolName,
+                args: args || {},
+                duration_ms: durationMs,
+            },
+        };
+    }
+
+    /**
+     * Handle framework HITL approval_required event.
+     * Shows the same approval menu as tool_call, but POSTs the decision
+     * to /api/approval_callback instead of skipping the tool.
+     *
+     * @param {Object} data - { tool_id, tool, args, risk, reason }
+     * @returns {Object|null} optional status event to yield
+     */
+    async _handleApprovalRequired(data) {
+        const { tool_id, tool, args, risk, reason } = data;
+
+        if (this.verbose) {
+            process.stderr.write(`\x1b[2m[hitl] Approval needed: ${tool} (${risk})\x1b[0m\n`);
+        }
+
+        // Use the same ApprovalManager for consistent UX
+        const { approved, reason: denyReason } = await this.approval.check(tool, args || {}, true);
+
+        // Map ApprovalManager decision to framework scope
+        let decision, scope;
+        if (approved) {
+            decision = 'grant';
+            // Determine scope from ApprovalManager state
+            if (this.approval.approveAll) {
+                scope = 'all';
+            } else if (this.approval.approvedToolTypes.has(tool)) {
+                scope = 'type';
+            } else {
+                scope = 'once';
+            }
+        } else {
+            decision = 'deny';
+            scope = 'once';
+        }
+
+        // POST decision to backend
+        if (this.currentTaskId && tool_id) {
+            await sendApprovalDecision(
+                this.baseUrl, this.token, this.currentTaskId,
+                tool_id, decision, scope, denyReason || '',
+            );
+        }
+
+        if (!approved) {
+            return {
+                type: EVENT_TYPES.STATUS,
+                data: { message: `Denied ${tool}: ${denyReason || 'rejected'}` },
+            };
+        }
+
+        return null; // Approved — framework continues with tool execution
+    }
+
+    /** Cancel the current stream. */
+    async cancel() {
+        this._cancelled = true;
+        if (this.currentTaskId) {
+            try {
+                await fetch(`${this.baseUrl}/api/cancel/${this.currentTaskId}`, {
+                    method: 'POST',
+                    headers: { 'Authorization': `Bearer ${this.token}` },
+                });
+            } catch { /* best effort */ }
+        }
+    }
+
+    /** Pause the current stream. */
+    async pause() {
+        if (this.currentTaskId) {
+            await fetch(`${this.baseUrl}/api/pause/${this.currentTaskId}`, {
+                method: 'POST',
+                headers: { 'Authorization': `Bearer ${this.token}` },
+            });
+        }
+    }
+
+    /** Resume a paused stream. */
+    async resume(instruction = null) {
+        if (this.currentTaskId) {
+            const body = instruction ? JSON.stringify({ instruction }) : undefined;
+            await fetch(`${this.baseUrl}/api/resume/${this.currentTaskId}`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.token}`,
+                    'Content-Type': 'application/json',
+                },
+                body,
+            });
+        }
+    }
+}