sofia-cli 0.1.1

package/dist/src/loop/conversationLoop.js

@@ -0,0 +1,227 @@
+import { createActivityEvent } from '../shared/events.js';
+import { renderMarkdown } from '../shared/markdownRenderer.js';
+import { createNoOpSpinner } from '../shared/activitySpinner.js';
+import { phaseSummarize } from './phaseSummarizer.js';
+// ── ConversationLoop ─────────────────────────────────────────────────────────
+export class ConversationLoop {
+    aborted = false;
+    session;
+    client;
+    io;
+    handler;
+    onEvent;
+    onSessionUpdate;
+    initialMessage;
+    spinner;
+    constructor(options) {
+        this.client = options.client;
+        this.io = options.io;
+        this.session = { ...options.session };
+        this.handler = options.phaseHandler;
+        this.onEvent = options.onEvent ?? (() => { });
+        this.onSessionUpdate = options.onSessionUpdate ?? (async () => { });
+        this.initialMessage = options.initialMessage;
+        this.spinner = options.spinner ?? createNoOpSpinner();
+    }
+    /** Run the conversation loop for the current phase. */
+    async run() {
+        this.setupSignalHandler();
+        let systemPrompt = this.handler.buildSystemPrompt(this.session);
+        // FR-007b, FR-007c: Inject phase boundary instruction to prevent LLM drift
+        systemPrompt += `\n\nYou are in the ${this.handler.phase} phase. Do NOT introduce or begin the next phase. The user will be offered a decision gate when this phase is complete.`;
+        // Inject prior conversation history into the system prompt when resuming
+        // so the LLM has context from previous turns in this phase.
+        const priorTurns = (this.session.turns ?? []).filter((t) => t.phase === this.handler.phase);
+        if (priorTurns.length > 0) {
+            const historyBlock = priorTurns.map((t) => `[${t.role}]: ${t.content}`).join('\n\n');
+            systemPrompt += `\n\n## Previous conversation history\n\n${historyBlock}`;
+        }
+        const references = this.handler.getReferences?.(this.session) ?? [];
+        const sessionOpts = { systemPrompt, references };
+        const conversationSession = await this.client.createSession(sessionOpts);
+        this.emitEvent(createActivityEvent(`Starting ${this.handler.phase} phase`));
+        // Auto-start: send initial message to LLM before waiting for user input
+        if (this.initialMessage) {
+            const response = await this.streamResponse(conversationSession, {
+                role: 'user',
+                content: this.initialMessage,
+            });
+            const now = new Date().toISOString();
+            const turns = this.session.turns ?? [];
+            turns.push({
+                phase: this.handler.phase,
+                sequence: turns.length + 1,
+                role: 'user',
+                content: this.initialMessage,
+                timestamp: now,
+            }, {
+                phase: this.handler.phase,
+                sequence: turns.length + 2,
+                role: 'assistant',
+                content: response,
+                timestamp: now,
+            });
+            const updates = this.handler.extractResult(this.session, response);
+            this.session = {
+                ...this.session,
+                ...updates,
+                turns,
+                updatedAt: now,
+            };
+            // Run async post-extraction hook if present (e.g., discovery enrichment)
+            if (this.handler.postExtract) {
+                const postUpdates = await this.handler.postExtract(this.session);
+                this.session = { ...this.session, ...postUpdates, updatedAt: new Date().toISOString() };
+            }
+            await this.onSessionUpdate(this.session);
+        }
+        // Main conversation loop
+        while (!this.aborted) {
+            const userInput = await this.io.readInput(`[${this.handler.phase}] > `);
+            if (userInput === null) {
+                // EOF / Ctrl+D — treat as "done" signal
+                break;
+            }
+            const trimmed = userInput.trim();
+            if (trimmed.toLowerCase() === 'done' || trimmed === '') {
+                // Check if handler considers the phase complete
+                if (this.handler.isComplete?.(this.session, '') !== false) {
+                    break;
+                }
+                // Otherwise continue the conversation
+            }
+            // Send user message and stream response
+            const response = await this.streamResponse(conversationSession, {
+                role: 'user',
+                content: trimmed,
+            });
+            // Accumulate turn history
+            const now = new Date().toISOString();
+            const turns = this.session.turns ?? [];
+            turns.push({
+                phase: this.handler.phase,
+                sequence: turns.length + 1,
+                role: 'user',
+                content: trimmed,
+                timestamp: now,
+            }, {
+                phase: this.handler.phase,
+                sequence: turns.length + 2,
+                role: 'assistant',
+                content: response,
+                timestamp: now,
+            });
+            // Extract structured data from the response
+            const updates = this.handler.extractResult(this.session, response);
+            this.session = {
+                ...this.session,
+                ...updates,
+                turns,
+                updatedAt: now,
+            };
+            // Run async post-extraction hook if present (e.g., discovery enrichment)
+            if (this.handler.postExtract) {
+                const postUpdates = await this.handler.postExtract(this.session);
+                this.session = { ...this.session, ...postUpdates, updatedAt: new Date().toISOString() };
+            }
+            // Persist after every turn (FR-039a)
+            await this.onSessionUpdate(this.session);
+        }
+        // FR-006: Post-phase summarization fallback
+        // If structured data wasn't extracted during conversation, try a dedicated summarization call
+        try {
+            const summarizationUpdates = await phaseSummarize(this.client, this.handler.phase, this.session, this.handler);
+            if (Object.keys(summarizationUpdates).length > 0) {
+                this.session = {
+                    ...this.session,
+                    ...summarizationUpdates,
+                    updatedAt: new Date().toISOString(),
+                };
+                await this.onSessionUpdate(this.session);
+            }
+        }
+        catch {
+            // Summarization failure is non-fatal
+        }
+        return this.session;
+    }
+    /** Stream response from the LLM and render incrementally. */
+    async streamResponse(session, message) {
+        const chunks = [];
+        let firstTextDelta = true;
+        // Start "Thinking..." spinner before sending
+        this.spinner.startThinking();
+        try {
+            for await (const event of session.send(message)) {
+                // Check if user pressed Ctrl+C during streaming
+                if (this.aborted)
+                    break;
+                this.emitEvent(event);
+                if (event.type === 'TextDelta') {
+                    // Stop spinner on first text output
+                    if (firstTextDelta) {
+                        this.spinner.stop();
+                        firstTextDelta = false;
+                    }
+                    chunks.push(event.text);
+                    if (!this.io.isJsonMode) {
+                        // Render markdown for TTY, raw for non-TTY
+                        if (this.io.isTTY) {
+                            this.io.write(renderMarkdown(event.text, { isTTY: true }));
+                        }
+                        else {
+                            this.io.write(event.text);
+                        }
+                    }
+                }
+                else if (event.type === 'Activity') {
+                    this.io.writeActivity(event.message);
+                }
+                else if (event.type === 'ToolCall') {
+                    this.spinner.startToolCall(event.toolName);
+                }
+                else if (event.type === 'ToolResult') {
+                    const summary = typeof event.result === 'string'
+                        ? event.result
+                        : JSON.stringify(event.result).slice(0, 120);
+                    this.spinner.completeToolCall(event.toolName, summary);
+                    this.io.writeToolSummary(event.toolName, summary);
+                    // Resume thinking spinner in case more processing follows
+                    this.spinner.startThinking();
+                }
+            }
+        }
+        finally {
+            // Always stop spinner — prevents cursor-hidden state on errors
+            this.spinner.stop();
+        }
+        const fullResponse = chunks.join('');
+        // In JSON mode, output the full rendered response
+        if (this.io.isJsonMode) {
+            this.io.write(JSON.stringify({ phase: this.handler.phase, content: fullResponse }));
+        }
+        else {
+            this.io.write('\n');
+        }
+        return fullResponse;
+    }
+    emitEvent(event) {
+        this.onEvent(event);
+    }
+    setupSignalHandler() {
+        const handler = () => {
+            this.aborted = true;
+            this.emitEvent(createActivityEvent('Ctrl+C received — finishing current turn'));
+        };
+        // Avoid MaxListenersExceededWarning when many loops are created in tests
+        const current = process.listenerCount('SIGINT');
+        if (current >= 10) {
+            process.setMaxListeners(current + 1);
+        }
+        process.once('SIGINT', handler);
+    }
+    /** Get the current session state. */
+    getSession() {
+        return { ...this.session };
+    }
+}

package/dist/src/loop/phaseSummarizer.js

@@ -0,0 +1,87 @@
+import { loadSummarizationPrompt } from '../prompts/promptLoader.js';
+// ── Phase → session field mapping ────────────────────────────────────────────
+const PHASE_SESSION_FIELD = {
+    Discover: 'businessContext',
+    Ideate: 'ideas',
+    Design: 'evaluation',
+    Select: 'selection',
+    Plan: 'plan',
+    Develop: 'poc',
+};
+/**
+ * Check whether a phase needs post-phase summarization.
+ * Returns true if the session field for this phase is null/undefined.
+ */
+export function needsSummarization(phase, session) {
+    const fieldName = PHASE_SESSION_FIELD[phase];
+    if (!fieldName)
+        return false;
+    const value = session[fieldName];
+    return value === undefined || value === null;
+}
+/**
+ * Build a concatenated transcript from conversation turns for a specific phase.
+ */
+export function buildPhaseTranscript(phase, session) {
+    const turns = (session.turns ?? []).filter((t) => t.phase === phase);
+    if (turns.length === 0)
+        return '';
+    return turns.map((t) => `[${t.role}]: ${t.content}`).join('\n\n');
+}
+/**
+ * Post-phase summarization call.
+ *
+ * If the expected structured field for `phase` is still null after the
+ * conversation loop, makes a one-shot LLM call to extract it from the
+ * full transcript.
+ *
+ * Returns partial session updates (may be empty if extraction still fails).
+ * Never throws — summarization is a best-effort fallback.
+ */
+export async function phaseSummarize(client, phase, session, handler) {
+    // Skip if field is already populated
+    if (!needsSummarization(phase, session)) {
+        return {};
+    }
+    // Build the transcript
+    const transcript = buildPhaseTranscript(phase, session);
+    if (!transcript) {
+        return {};
+    }
+    try {
+        // Load the phase-specific summarization prompt
+        const systemPrompt = await loadSummarizationPrompt(phase);
+        // Create a new session for the summarization call (avoids polluting context)
+        const summarizationSession = await client.createSession({ systemPrompt });
+        // Send the transcript as a single user message and collect the full response
+        const chunks = [];
+        for await (const event of summarizationSession.send({
+            role: 'user',
+            content: transcript,
+        })) {
+            if (event.type === 'TextDelta') {
+                chunks.push(event.text);
+            }
+        }
+        const response = chunks.join('');
+        // Extract structured data using the phase handler's extractResult
+        const updates = handler.extractResult(session, response);
+        // For Design phase, also extract Mermaid diagram (FR-007a)
+        // Store in plan.architectureNotes if available (session schema doesn't have
+        // a dedicated architectureDiagram field)
+        if (phase === 'Design') {
+            const mermaidMatch = response.match(/```mermaid\s*\n([\s\S]*?)\n```/);
+            if (mermaidMatch) {
+                const diagram = mermaidMatch[1].trim();
+                if (!updates.plan) {
+                    updates.plan = { milestones: [], architectureNotes: diagram };
+                }
+            }
+        }
+        return updates;
+    }
+    catch {
+        // Summarization failure is non-fatal — log and return empty
+        return {};
+    }
+}

package/dist/src/mcp/mcpManager.js

@@ -0,0 +1,267 @@
+/**
+ * MCP Manager.
+ *
+ * Loads .vscode/mcp.json configuration, manages MCP server connections,
+ * lists available tools, classifies errors, and dispatches real MCP tool calls
+ * via the transport layer.
+ */
+import { readFile } from 'node:fs/promises';
+import { createTransport, StdioMcpTransport } from './mcpTransport.js';
+import { withRetry } from './retryPolicy.js';
+const ERROR_CODE_MAP = {
+    ECONNREFUSED: 'connection-refused',
+    ENOTFOUND: 'dns-failure',
+    ETIMEDOUT: 'timeout',
+    ECONNRESET: 'connection-refused',
+    ERR_TLS_CERT_ALTNAME_INVALID: 'auth-failure',
+};
+export function classifyMcpError(err) {
+    if (err instanceof Error) {
+        const code = err.code;
+        if (code && code in ERROR_CODE_MAP) {
+            return ERROR_CODE_MAP[code];
+        }
+        // AbortError from AbortController / fetch timeouts
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return 'timeout';
+        }
+        // Message-based timeout detection
+        if (/timed?\s*out/i.test(err.message)) {
+            return 'timeout';
+        }
+        if (err.message.includes('401') || err.message.includes('403')) {
+            return 'auth-failure';
+        }
+    }
+    return 'unknown';
+}
+// ── Config loader ────────────────────────────────────────────────────────────
+/**
+ * Load and normalize MCP configuration from a JSON file.
+ * Returns empty servers if the file doesn't exist.
+ */
+export async function loadMcpConfig(configPath) {
+    try {
+        const raw = await readFile(configPath, 'utf-8');
+        // Strip JSONC comments — only full-line // comments and block comments
+        // Avoid stripping // inside string values (e.g. URLs like https://)
+        const stripped = raw
+            .replace(/^\s*\/\/.*$/gm, '') // full-line // comments
+            .replace(/\/\*[\s\S]*?\*\//g, '') // block comments
+            .replace(/,(\s*[}\]])/g, '$1'); // trailing commas
+        const parsed = JSON.parse(stripped);
+        const servers = {};
+        if (parsed.servers && typeof parsed.servers === 'object') {
+            for (const [name, config] of Object.entries(parsed.servers)) {
+                const cfg = config;
+                if (cfg.url && typeof cfg.url === 'string') {
+                    servers[name] = {
+                        name,
+                        type: 'http',
+                        url: cfg.url,
+                        ...(cfg.headers && typeof cfg.headers === 'object'
+                            ? { headers: cfg.headers }
+                            : {}),
+                        ...(Array.isArray(cfg.tools) ? { tools: cfg.tools } : {}),
+                        ...(typeof cfg.timeout === 'number' ? { timeout: cfg.timeout } : {}),
+                    };
+                }
+                else if (cfg.command && typeof cfg.command === 'string') {
+                    servers[name] = {
+                        name,
+                        type: 'stdio',
+                        command: cfg.command,
+                        args: Array.isArray(cfg.args) ? cfg.args : [],
+                        ...(cfg.env && typeof cfg.env === 'object'
+                            ? { env: cfg.env }
+                            : {}),
+                        ...(typeof cfg.cwd === 'string' ? { cwd: cfg.cwd } : {}),
+                        ...(Array.isArray(cfg.tools) ? { tools: cfg.tools } : {}),
+                        ...(typeof cfg.timeout === 'number' ? { timeout: cfg.timeout } : {}),
+                    };
+                }
+            }
+        }
+        return { servers };
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return { servers: {} };
+        }
+        // Re-throw parse or other errors
+        throw err;
+    }
+}
+/**
+ * Convert sofIA's `McpConfig` to the shape expected by the Copilot SDK's
+ * `SessionConfig.mcpServers` (`Record<string, MCPServerConfig>`).
+ *
+ * This bridges `.vscode/mcp.json` → SDK `createSession({ mcpServers })`.
+ * The SDK types are `MCPLocalServerConfig` and `MCPRemoteServerConfig`.
+ */
+export function toSdkMcpServers(config) {
+    const result = {};
+    for (const [name, server] of Object.entries(config.servers)) {
+        if (server.type === 'stdio') {
+            result[name] = {
+                type: 'stdio',
+                command: server.command,
+                args: server.args,
+                tools: server.tools ?? ['*'],
+                ...(server.env ? { env: server.env } : {}),
+                ...(server.cwd ? { cwd: server.cwd } : {}),
+                ...(server.timeout ? { timeout: server.timeout } : {}),
+            };
+        }
+        else if (server.type === 'http') {
+            result[name] = {
+                type: 'http',
+                url: server.url,
+                tools: server.tools ?? ['*'],
+                ...(server.headers ? { headers: server.headers } : {}),
+                ...(server.timeout ? { timeout: server.timeout } : {}),
+            };
+        }
+    }
+    return result;
+}
+// ── Default Timeouts ─────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUTS = {
+    github: 60_000,
+    context7: 30_000,
+    azure: 30_000,
+    workiq: 30_000,
+    'microsoftdocs/mcp': 30_000,
+};
+const FALLBACK_TIMEOUT = 30_000;
+// ── McpManager ───────────────────────────────────────────────────────────────
+export class McpManager {
+    config;
+    connectedServers = new Set();
+    transports = new Map();
+    logger;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    /** List all configured server names. */
+    listServers() {
+        return Object.keys(this.config.servers);
+    }
+    /** Get configuration for a specific server. */
+    getServerConfig(name) {
+        return this.config.servers[name];
+    }
+    /** Check if a server is currently connected (available). */
+    isAvailable(name) {
+        return this.connectedServers.has(name);
+    }
+    /** Mark a server as connected. Used by the SDK integration layer. */
+    markConnected(name) {
+        if (this.config.servers[name]) {
+            this.connectedServers.add(name);
+        }
+    }
+    /** Mark a server as disconnected. */
+    markDisconnected(name) {
+        this.connectedServers.delete(name);
+    }
+    /** Get all server configs as an array. */
+    getAllConfigs() {
+        return Object.values(this.config.servers);
+    }
+    /**
+     * Call a tool on a named MCP server.
+     *
+     * Dispatches to the correct transport (stdio or HTTP), applies retry policy
+     * for transient errors, and normalizes the response.
+     *
+     * @param serverName The MCP server name (e.g., 'github', 'context7', 'azure')
+     * @param toolName The tool to call on that server
+     * @param args Arguments for the tool
+     * @param options Optional timeout and retry configuration
+     * @returns The tool response as a parsed object
+     */
+    async callTool(serverName, toolName, args, options) {
+        if (!this.isAvailable(serverName)) {
+            throw new Error(`MCP server '${serverName}' is not available`);
+        }
+        const serverConfig = this.config.servers[serverName];
+        if (!serverConfig) {
+            throw new Error(`Unknown MCP server: ${serverName}`);
+        }
+        // Get or create transport
+        const transport = this.getOrCreateTransport(serverName, serverConfig);
+        // Connect stdio transports on first use
+        if (transport instanceof StdioMcpTransport && !transport.isConnected()) {
+            await transport.connect();
+        }
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUTS[serverName] ?? FALLBACK_TIMEOUT;
+        try {
+            let response;
+            if (options?.retryOnTransient !== false) {
+                response = await withRetry(() => transport.callTool(toolName, args, timeoutMs), {
+                    serverName,
+                    toolName,
+                    logger: this.logger,
+                });
+            }
+            else {
+                response = await transport.callTool(toolName, args, timeoutMs);
+            }
+            // Normalize content to Record<string, unknown>
+            const content = response.content;
+            if (typeof content === 'string') {
+                // Try to parse JSON string; if not JSON, wrap as { text: content }
+                try {
+                    const parsed = JSON.parse(content);
+                    if (typeof parsed === 'object' && parsed !== null) {
+                        return parsed;
+                    }
+                    return { text: content };
+                }
+                catch {
+                    return { text: content };
+                }
+            }
+            return content;
+        }
+        catch (err) {
+            this.markDisconnected(serverName);
+            throw err;
+        }
+    }
+    /**
+     * Disconnect all cached transports and clear the registry.
+     */
+    async disconnectAll() {
+        const disconnections = [];
+        for (const transport of this.transports.values()) {
+            disconnections.push(transport.disconnect());
+        }
+        await Promise.allSettled(disconnections);
+        this.transports.clear();
+    }
+    /**
+     * Get or lazily create a transport for the given server.
+     */
+    getOrCreateTransport(serverName, config) {
+        let transport = this.transports.get(serverName);
+        if (!transport) {
+            const logger = this.logger ??
+                {
+                    info: () => { },
+                    warn: () => { },
+                    error: () => { },
+                    debug: () => { },
+                    trace: () => { },
+                    fatal: () => { },
+                    child: () => logger,
+                    level: 'silent',
+                };
+            transport = createTransport(config, logger);
+            this.transports.set(serverName, transport);
+        }
+        return transport;
+    }
+}