pikiloop 0.4.0

package/dist/agent/mcp/session-server.js

@@ -0,0 +1,229 @@
+/**
+ * mcp-session-server.ts — MCP server process for pikiloop session bridge.
+ *
+ * Spawned by the agent CLI (claude/codex/gemini) via --mcp-config or codex mcp add.
+ * Communicates with the agent over stdio using the MCP protocol (JSON-RPC 2.0).
+ *
+ * Supports two stdio transports (auto-detected from first byte):
+ *   - Content-Length framing (Claude, Gemini — standard MCP/LSP)
+ *   - Newline-delimited JSON (Codex)
+ *
+ * Context is injected via environment variables:
+ *   MCP_WORKSPACE_PATH — absolute path to the session workspace
+ *   MCP_STAGED_FILES   — JSON array of staged file relative paths
+ *   MCP_CALLBACK_URL   — HTTP URL for the pikiloop callback server
+ *
+ * Tools are defined in src/tools/ — each module exports definitions + handlers.
+ */
+import path from 'node:path';
+import { createRetainedLogSink, writeScopedLog } from '../../core/logging.js';
+import { workspaceTools } from './tools/workspace.js';
+import { goalTools } from './tools/goal.js';
+import { awaitResumeTools } from './tools/await-resume.js';
+import { askUserTools } from './tools/ask-user.js';
+// ---------------------------------------------------------------------------
+// Logging — writes to stderr + file so it doesn't interfere with stdio MCP transport
+// ---------------------------------------------------------------------------
+const _logSink = (() => {
+    try {
+        const ws = process.env.MCP_WORKSPACE_PATH || '';
+        if (!ws)
+            return null;
+        const dir = path.dirname(ws);
+        return createRetainedLogSink(path.join(dir, 'mcp-server.log'));
+    }
+    catch {
+        return null;
+    }
+})();
+function log(msg, level = 'debug') {
+    if (!writeScopedLog('mcp-server', msg, { level, stream: 'stderr' }))
+        return;
+    _logSink?.(`[mcp-server ${new Date().toTimeString().slice(0, 8)}] ${msg}\n`);
+}
+function summarizeArgs(args, max = 200) {
+    let text = '';
+    try {
+        text = JSON.stringify(args);
+    }
+    catch {
+        text = String(args);
+    }
+    if (!text)
+        return '{}';
+    return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 3)).trimEnd()}...`;
+}
+// ---------------------------------------------------------------------------
+// Context from environment
+// ---------------------------------------------------------------------------
+const ctx = {
+    workspace: process.env.MCP_WORKSPACE_PATH || '',
+    workdir: process.env.MCP_WORKDIR || undefined,
+    stagedFiles: (() => {
+        try {
+            return JSON.parse(process.env.MCP_STAGED_FILES || '[]');
+        }
+        catch {
+            return [];
+        }
+    })(),
+    callbackUrl: process.env.MCP_CALLBACK_URL || '',
+};
+log(`started workspace=${ctx.workspace} stagedFiles=${ctx.stagedFiles.length} callbackUrl=${ctx.callbackUrl ? 'set' : 'MISSING'}`);
+// ---------------------------------------------------------------------------
+// Tool registry — collect all tool modules
+// ---------------------------------------------------------------------------
+// `MCP_TOOLS_AVAILABLE` lists tool families the bridge has wired up. Codex
+// has a native `/goal` implementation and native user-input, so it skips
+// `goalTools` and never receives `ask-user` via the bridge.
+const AVAILABLE = new Set((process.env.MCP_TOOLS_AVAILABLE || '').split(',').map(s => s.trim()).filter(Boolean));
+const IS_CODEX = process.env.MCP_AGENT === 'codex';
+const TOOL_MODULES = [
+    ...(AVAILABLE.has('workspace') ? [workspaceTools] : []),
+    ...(IS_CODEX ? [] : [goalTools]),
+    // Codex parks/resumes via its own native goal machinery; the pikiloop
+    // awaiting marker is for the `claude -p`-style drivers whose turn process
+    // exits at `result`.
+    ...(IS_CODEX ? [] : [awaitResumeTools]),
+    ...(AVAILABLE.has('ask-user') ? [askUserTools] : []),
+];
+const ALL_TOOLS = TOOL_MODULES.flatMap(m => m.tools);
+/** Lookup: tool name → module that handles it. */
+const TOOL_HANDLERS = new Map();
+for (const mod of TOOL_MODULES) {
+    for (const t of mod.tools) {
+        TOOL_HANDLERS.set(t.name, mod);
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP protocol — auto-detect transport format
+// ---------------------------------------------------------------------------
+/** 'framed' = Content-Length (Claude/Gemini), 'ndjson' = newline-delimited (Codex) */
+let transport = null;
+function send(msg) {
+    const body = JSON.stringify(msg);
+    if (transport === 'ndjson') {
+        process.stdout.write(body + '\n');
+    }
+    else {
+        process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+    }
+}
+function respond(id, result) {
+    send({ jsonrpc: '2.0', id, result });
+}
+function respondError(id, code, message) {
+    send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+// ---------------------------------------------------------------------------
+// Stdio reader — auto-detecting Content-Length framed vs NDJSON
+// ---------------------------------------------------------------------------
+let buffer = '';
+function processFramed() {
+    while (true) {
+        const headerEnd = buffer.indexOf('\r\n\r\n');
+        if (headerEnd < 0)
+            break;
+        const header = buffer.slice(0, headerEnd);
+        const match = header.match(/Content-Length:\s*(\d+)/i);
+        if (!match) {
+            buffer = buffer.slice(headerEnd + 4);
+            continue;
+        }
+        const len = parseInt(match[1], 10);
+        const bodyStart = headerEnd + 4;
+        if (buffer.length < bodyStart + len)
+            break;
+        const body = buffer.slice(bodyStart, bodyStart + len);
+        buffer = buffer.slice(bodyStart + len);
+        try {
+            handleMessage(JSON.parse(body));
+        }
+        catch { /* ignore parse errors */ }
+    }
+}
+function processNdjson() {
+    while (true) {
+        const newlineIdx = buffer.indexOf('\n');
+        if (newlineIdx < 0)
+            break;
+        const line = buffer.slice(0, newlineIdx).trim();
+        buffer = buffer.slice(newlineIdx + 1);
+        if (!line)
+            continue;
+        try {
+            handleMessage(JSON.parse(line));
+        }
+        catch { /* ignore parse errors */ }
+    }
+}
+function processBuffer() {
+    if (transport === null) {
+        const trimmed = buffer.trimStart();
+        if (!trimmed)
+            return;
+        transport = trimmed[0] === '{' ? 'ndjson' : 'framed';
+    }
+    if (transport === 'ndjson')
+        processNdjson();
+    else
+        processFramed();
+}
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    processBuffer();
+});
+process.stdin.on('end', () => process.exit(0));
+// ---------------------------------------------------------------------------
+// Message dispatcher
+// ---------------------------------------------------------------------------
+function handleMessage(msg) {
+    const { id, method, params } = msg;
+    switch (method) {
+        case 'initialize':
+            log(`initialize protocolVersion=${params?.protocolVersion || '?'}`);
+            respond(id, {
+                protocolVersion: params?.protocolVersion || '2024-11-05',
+                capabilities: { tools: {} },
+                serverInfo: { name: 'pikiloop-session', version: '1.0.0' },
+            });
+            break;
+        case 'notifications/initialized':
+            log('initialized notification received');
+            break;
+        case 'tools/list':
+            log(`tools/list → ${ALL_TOOLS.length} tools: ${ALL_TOOLS.map(t => t.name).join(', ')}`);
+            respond(id, { tools: ALL_TOOLS });
+            break;
+        case 'tools/call': {
+            const name = params?.name;
+            const args = params?.arguments || {};
+            const mod = TOOL_HANDLERS.get(name);
+            if (!mod) {
+                log(`tools/call UNKNOWN tool="${name}"`, 'warn');
+                respondError(id, -32601, `Unknown tool: ${name}`);
+                break;
+            }
+            const argsSummary = summarizeArgs(args);
+            log(`tools/call tool="${name}" args=${argsSummary}`);
+            const callStart = Date.now();
+            void Promise.resolve(mod.handle(name, args, ctx)).then(result => {
+                const elapsed = Date.now() - callStart;
+                const text = result.content?.[0]?.text || '';
+                log(`tools/call tool="${name}" ${result.isError ? 'ERROR' : 'OK'} ${elapsed}ms args=${argsSummary} result=${text.slice(0, 150)}`);
+                respond(id, result);
+            }, err => {
+                const elapsed = Date.now() - callStart;
+                log(`tools/call tool="${name}" EXCEPTION ${elapsed}ms args=${argsSummary} error=${err?.message || err}`, 'warn');
+                respond(id, { content: [{ type: 'text', text: `Tool error: ${err?.message || err}` }], isError: true });
+            });
+            break;
+        }
+        default:
+            if (id !== undefined) {
+                log(`unknown method="${method}"`, 'warn');
+                respondError(id, -32601, `Method not found: ${method}`);
+            }
+    }
+}

package/dist/agent/mcp/tools/ask-user.js

@@ -0,0 +1,113 @@
+/**
+ * tools/ask-user.ts — im_ask_user: block the current turn and route a question
+ * to the user via IM or dashboard. Used in place of Claude's native
+ * `AskUserQuestion`, which is unusable in `-p` mode.
+ */
+import http from 'node:http';
+import { toolResult, toolLog } from './types.js';
+const tools = [
+    {
+        name: 'im_ask_user',
+        description: 'Ask the user a question and block until they reply. Equivalent to '
+            + '`AskUserQuestion`, routed through the IM channel or dashboard. '
+            + 'Supply `options` whenever the answer is enumerable so the user can '
+            + 'tap a choice. Use only when you genuinely need user input to '
+            + 'proceed; for routine clarifications, pick a sensible default and '
+            + 'continue.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: { type: 'string', description: 'Question text shown to the user.' },
+                header: { type: 'string', description: 'Optional short header (≤ 24 chars).' },
+                hint: { type: 'string', description: 'Optional helper text shown alongside the question.' },
+                options: {
+                    type: 'array',
+                    description: 'Predefined choices. Omit for a freeform answer.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: { type: 'string', description: 'Option label, returned verbatim if selected.' },
+                            description: { type: 'string', description: 'Optional secondary description.' },
+                        },
+                        required: ['label'],
+                    },
+                },
+                allow_freeform: {
+                    type: 'boolean',
+                    description: 'When options are supplied, also accept freeform text (default true).',
+                },
+            },
+            required: ['question'],
+        },
+    },
+];
+async function handleAskUser(args, ctx) {
+    const question = typeof args?.question === 'string' ? args.question.trim() : '';
+    const header = typeof args?.header === 'string' ? args.header.trim() : '';
+    const hint = typeof args?.hint === 'string' ? args.hint.trim() : '';
+    const allowFreeform = args?.allow_freeform == null ? true : !!args.allow_freeform;
+    const rawOptions = Array.isArray(args?.options) ? args.options : [];
+    const options = rawOptions
+        .map((o) => ({
+        label: typeof o?.label === 'string' ? o.label.trim() : '',
+        description: typeof o?.description === 'string' ? o.description.trim() : '',
+    }))
+        .filter(o => o.label);
+    if (!question) {
+        toolLog('im_ask_user', 'ERROR missing question');
+        return toolResult('Error: "question" is required', true);
+    }
+    if (!ctx.callbackUrl) {
+        toolLog('im_ask_user', 'ERROR no callback URL');
+        return toolResult('Error: MCP callback URL is not configured', true);
+    }
+    toolLog('im_ask_user', `question="${question.slice(0, 160)}" options=${options.length} freeform=${allowFreeform}`);
+    try {
+        const response = await callbackAskUser(ctx.callbackUrl, { question, header, hint, allowFreeform, options });
+        if (response.ok) {
+            const answer = (response.answer || '').trim();
+            toolLog('im_ask_user', `OK answer="${answer.slice(0, 160)}"`);
+            return toolResult(answer || '(no response)');
+        }
+        toolLog('im_ask_user', `FAILED ${response.error || 'unknown error'}`);
+        return toolResult(`Failed to get user response: ${response.error || 'unknown error'}`, true);
+    }
+    catch (e) {
+        toolLog('im_ask_user', `ERROR ${e.message}`);
+        return toolResult(`Error asking user: ${e.message}`, true);
+    }
+}
+function callbackAskUser(callbackUrl, body) {
+    const payload = JSON.stringify(body);
+    const url = new URL('/ask-user', callbackUrl);
+    return new Promise((resolve, reject) => {
+        const req = http.request(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+        }, res => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk; });
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch {
+                    resolve({ ok: false, error: 'invalid callback response' });
+                }
+            });
+        });
+        req.on('error', e => reject(e));
+        // User reply has no upper bound — never time out the socket.
+        req.setTimeout(0);
+        req.write(payload);
+        req.end();
+    });
+}
+export const askUserTools = {
+    tools,
+    handle(name, args, ctx) {
+        if (name === 'im_ask_user')
+            return handleAskUser(args, ctx);
+        return toolResult(`Unknown ask-user tool: ${name}`, true);
+    },
+};

package/dist/agent/mcp/tools/await-resume.js

@@ -0,0 +1,77 @@
+/**
+ * tools/await-resume.ts — "waiting for background work" marker MCP tool.
+ *
+ *   await_background — Lets the model declare that this turn is ending while
+ *                      detached/background work it launched keeps running, and
+ *                      it intends to report back later. Purely a UI hint: it
+ *                      changes nothing about execution, it only lets the
+ *                      dashboard show a "waiting" state instead of "completed"
+ *                      for the interval until the session next runs.
+ *
+ * State lives at <sessionRoot>/awaiting.json; this server resolves the session
+ * root from MCP_WORKSPACE_PATH (which points to <sessionRoot>/workspace). The
+ * parent reads & clears it (see agent/await-resume.ts) — clearing happens
+ * automatically the next time the session runs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { toolResult, toolLog } from './types.js';
+const AWAIT_FILE = 'awaiting.json';
+const MAX_REASON_CHARS = 280;
+const tools = [
+    {
+        name: 'await_background',
+        description: [
+            'Mark this session as waiting on detached background work.',
+            'Call this ONLY when you are ending your turn while work you launched keeps running detached from this turn (a daemon, a build/install that must survive a restart, a long external job) and you intend to report back on it in a later turn.',
+            'This is a passive status hint for the dashboard — it does NOT change how you run, does NOT keep the turn open, and does NOT wake you when the work finishes. Do not call it for ordinary tool calls or foreground work, and do not call it just because a task is large.',
+            'The marker is cleared automatically the next time this session runs, so you never need to clear it yourself.',
+        ].join('\n'),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                reason: {
+                    type: 'string',
+                    description: 'Short, human-readable note on what is still running and what you will report back (e.g. "rebuilding + restarting pikiloop, will confirm after it comes back up").',
+                },
+            },
+            required: ['reason'],
+        },
+    },
+];
+function sessionRootFromCtx(ctx) {
+    const workspace = path.resolve(ctx.workspace || '');
+    if (!workspace)
+        return '';
+    return path.basename(workspace) === 'workspace' ? path.dirname(workspace) : workspace;
+}
+function handleAwaitBackground(args, ctx) {
+    const reason = typeof args?.reason === 'string' ? args.reason.trim().slice(0, MAX_REASON_CHARS) : '';
+    toolLog('await_background', `reason=${reason.slice(0, 80) || '(empty)'}`);
+    if (!reason) {
+        return toolResult('Error: `reason` must be a non-empty description of the background work being awaited.', true);
+    }
+    const root = sessionRootFromCtx(ctx);
+    if (!root)
+        return toolResult('Error: MCP workspace path is not configured', true);
+    const file = path.join(root, AWAIT_FILE);
+    try {
+        fs.mkdirSync(root, { recursive: true });
+        const tmp = `${file}.tmp-${process.pid}-${Date.now().toString(36)}`;
+        fs.writeFileSync(tmp, JSON.stringify({ reason, since: new Date().toISOString() }, null, 2));
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        return toolResult(`Error: failed to write awaiting marker: ${err?.message || err}`, true);
+    }
+    return toolResult('Marked this session as waiting on background work. The dashboard will show a "waiting" state until the session next runs (which clears the marker). Reminder: this does not wake you — you must resume the turn yourself or be re-prompted.');
+}
+export const awaitResumeTools = {
+    tools,
+    handle(name, args, ctx) {
+        switch (name) {
+            case 'await_background': return handleAwaitBackground(args, ctx);
+            default: return toolResult(`Unknown await tool: ${name}`, true);
+        }
+    },
+};

package/dist/agent/mcp/tools/goal.js

@@ -0,0 +1,144 @@
+/**
+ * tools/goal.ts — Persistent thread goal MCP tools.
+ *
+ *   goal_get    — Returns the current goal (objective, status, usage, budget).
+ *   goal_update — Lets the model mark the goal complete after a completion audit.
+ *                 The schema only accepts `status: "complete"`. Pause / resume /
+ *                 clear / budget_limited transitions are user- or runtime-controlled
+ *                 and not exposed to the model.
+ *
+ * Goal state lives at <sessionRoot>/goal.json; this server resolves the session
+ * root from MCP_WORKSPACE_PATH (which points to <sessionRoot>/workspace).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { toolResult, toolLog } from './types.js';
+// ---------------------------------------------------------------------------
+// Tool definitions — descriptions match Codex's analogous `get_goal` / `update_goal`
+// behaviour but use the pikiloop tool name.
+// ---------------------------------------------------------------------------
+const tools = [
+    {
+        name: 'goal_get',
+        description: 'Get the current goal for this session, including objective, status, token and elapsed-time usage, token budget, and tokens remaining.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'goal_update',
+        description: [
+            'Update the existing goal.',
+            'Use this tool only to mark the goal achieved.',
+            'Set status to `complete` only when the objective has actually been achieved and no required work remains.',
+            'Do not mark a goal complete merely because its budget is nearly exhausted or because you are stopping work.',
+            'You cannot use this tool to pause, resume, or budget-limit a goal; those status changes are controlled by the user or system.',
+            'When marking a budgeted goal achieved with status `complete`, report the final token usage from the tool result to the user.',
+        ].join('\n'),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    enum: ['complete'],
+                    description: 'Required. Set to "complete" only when the objective is achieved and no required work remains.',
+                },
+            },
+            required: ['status'],
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Path resolution — workspace → session root → goal.json
+// ---------------------------------------------------------------------------
+function sessionRootFromCtx(ctx) {
+    const workspace = path.resolve(ctx.workspace || '');
+    if (!workspace)
+        return '';
+    return path.basename(workspace) === 'workspace' ? path.dirname(workspace) : workspace;
+}
+function goalPathFromCtx(ctx) {
+    const root = sessionRootFromCtx(ctx);
+    if (!root)
+        return '';
+    return path.join(root, 'goal.json');
+}
+function readGoalFile(file) {
+    if (!file || !fs.existsSync(file))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeGoalFile(file, goal) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${Date.now().toString(36)}`;
+    fs.writeFileSync(tmp, JSON.stringify({ ...goal, updatedAt: new Date().toISOString() }, null, 2));
+    fs.renameSync(tmp, file);
+}
+function serialize(goal) {
+    return {
+        goal_id: goal.goalId,
+        objective: goal.objective,
+        status: goal.status,
+        token_budget: goal.tokenBudget,
+        tokens_used: goal.tokensUsed,
+        time_used_seconds: goal.timeUsedSeconds,
+        remaining_tokens: goal.tokenBudget != null ? Math.max(0, goal.tokenBudget - goal.tokensUsed) : null,
+        created_at: goal.createdAt,
+        updated_at: goal.updatedAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+function handleGoalGet(ctx) {
+    const file = goalPathFromCtx(ctx);
+    toolLog('goal_get', `file=${file || '(unresolved)'}`);
+    if (!file)
+        return toolResult('Error: MCP workspace path is not configured', true);
+    const goal = readGoalFile(file);
+    if (!goal)
+        return toolResult(JSON.stringify({ goal: null }, null, 2));
+    return toolResult(JSON.stringify({ goal: serialize(goal) }, null, 2));
+}
+function handleGoalUpdate(args, ctx) {
+    const status = typeof args?.status === 'string' ? args.status : '';
+    toolLog('goal_update', `status=${status}`);
+    if (status !== 'complete') {
+        return toolResult('Error: goal_update only accepts status "complete". Pause, resume, and budget-limited status changes are controlled by the user or system.', true);
+    }
+    const file = goalPathFromCtx(ctx);
+    if (!file)
+        return toolResult('Error: MCP workspace path is not configured', true);
+    const goal = readGoalFile(file);
+    if (!goal) {
+        return toolResult('Error: no goal is currently set for this session', true);
+    }
+    if (goal.status === 'complete') {
+        return toolResult(JSON.stringify({ goal: serialize(goal), note: 'already complete' }, null, 2));
+    }
+    const next = { ...goal, status: 'complete' };
+    writeGoalFile(file, next);
+    return toolResult(JSON.stringify({
+        goal: serialize(next),
+        completion_budget_report: goal.tokenBudget != null
+            ? `tokens used: ${goal.tokensUsed} of ${goal.tokenBudget}`
+            : `tokens used: ${goal.tokensUsed}`,
+    }, null, 2));
+}
+// ---------------------------------------------------------------------------
+// Module export
+// ---------------------------------------------------------------------------
+export const goalTools = {
+    tools,
+    handle(name, args, ctx) {
+        switch (name) {
+            case 'goal_get': return handleGoalGet(ctx);
+            case 'goal_update': return handleGoalUpdate(args, ctx);
+            default: return toolResult(`Unknown goal tool: ${name}`, true);
+        }
+    },
+};

package/dist/agent/mcp/tools/types.js

@@ -0,0 +1,12 @@
+/**
+ * MCP tool type definitions and helper utilities.
+ */
+import { writeScopedLog } from '../../../core/logging.js';
+/** Helper to build a text tool result. */
+export function toolResult(text, isError = false) {
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+}
+/** Shared logger for tool modules — writes to stderr to avoid interfering with stdio MCP transport. */
+export function toolLog(tool, msg) {
+    writeScopedLog(`tool:${tool}`, msg, { level: 'debug', stream: 'stderr' });
+}