invokora 0.1.0

package/dist/cli/mcp/responses_session.js

@@ -0,0 +1,233 @@
+import { createBackendInvocationError, createBackendInvocationErrorFromPayload, parseJsonResponse } from './errors.js';
+import { McpSessionStore, replayInputForSession } from './session_store.js';
+const COMPACT_CONTEXT_WINDOW_TOKENS = 400_000;
+const COMPACT_MAX_OUTPUT_TOKENS = 128_000;
+const COMPACT_REPLAY_BUDGET_TOKENS = COMPACT_CONTEXT_WINDOW_TOKENS - COMPACT_MAX_OUTPUT_TOKENS;
+const APPROX_CHARS_PER_TOKEN = 4;
+const DEFAULT_COMPACT_AFTER_CHARS = COMPACT_REPLAY_BUDGET_TOKENS * APPROX_CHARS_PER_TOKEN;
+export async function runResponsesChatSession(options) {
+    await reportProgress(options.progressReporter, 10, 'Preparing MCP session...');
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const store = options.sessionStore ?? new McpSessionStore();
+    const session = store.loadOrCreate(options.sessionID);
+    const appendedMessages = normalizeMessages(options.messages);
+    if (options.model?.trim()) {
+        session.model = options.model.trim();
+    }
+    else if (!session.model && options.defaultModel?.trim()) {
+        session.model = options.defaultModel.trim();
+    }
+    if (options.reason) {
+        session.reason = options.reason;
+    }
+    else if (!session.reason && options.defaultReason) {
+        session.reason = options.defaultReason;
+    }
+    session.metadata = { client_surface: 'mcp', session_id: session.session_id };
+    await compactSessionIfNeeded(fetchImpl, options, session);
+    session.messages.push(...appendedMessages);
+    session.updated_at = new Date().toISOString();
+    const payload = buildResponsesPayload(session, replayInputForSession(session));
+    await reportProgress(options.progressReporter, 35, 'Calling Invokora Responses...');
+    const response = await postResponses(fetchImpl, options.backendBaseUrl, options.apiKey, payload, options);
+    if (response.output_text && response.output_text.trim()) {
+        session.messages.push({ role: 'assistant', content: response.output_text });
+    }
+    session.last_response_id = response.id;
+    session.model = response.model ?? session.model;
+    session.updated_at = new Date().toISOString();
+    await reportProgress(options.progressReporter, 95, 'Saving MCP session...');
+    store.save(session);
+    await reportProgress(options.progressReporter, 100, 'Done.');
+    return {
+        session_id: session.session_id,
+        response_id: response.id,
+        model: response.model ?? session.model ?? '',
+        output_text: response.output_text ?? '',
+        ...(response.usage ? { usage: response.usage } : {}),
+        ...(response.charge ? { charge: response.charge } : {}),
+    };
+}
+function normalizeMessages(messages) {
+    if (messages.length === 0) {
+        throw new Error('messages must not be empty');
+    }
+    const normalized = messages.map((message) => ({
+        role: message.role,
+        content: message.content,
+    }));
+    const last = normalized[normalized.length - 1];
+    if (last.role !== 'user' || last.content.trim() === '') {
+        throw new Error('messages must end with a non-empty user message');
+    }
+    for (const message of normalized) {
+        if ((message.role !== 'user' && message.role !== 'assistant') || message.content.trim() === '') {
+            throw new Error('messages only support non-empty user and assistant text');
+        }
+    }
+    return normalized;
+}
+function buildResponsesPayload(session, input) {
+    return {
+        ...(session.model ? { model: session.model } : {}),
+        ...(session.reason ? { reasoning: { effort: session.reason } } : {}),
+        input,
+        stream: true,
+        metadata: { client_surface: 'mcp', session_id: session.session_id },
+    };
+}
+async function compactSessionIfNeeded(fetchImpl, options, session) {
+    const compactAfterChars = options.compactAfterChars ?? DEFAULT_COMPACT_AFTER_CHARS;
+    const replayInput = replayInputForSession(session);
+    if (JSON.stringify(replayInput).length < compactAfterChars || replayInput.length < 4) {
+        return;
+    }
+    try {
+        await reportProgress(options.progressReporter, 20, 'Compacting long MCP session...');
+        const item = await postCompact(fetchImpl, options.backendBaseUrl, options.apiKey, {
+            ...(session.model ? { model: session.model } : {}),
+            input: replayInput,
+            metadata: { client_surface: 'mcp', session_id: session.session_id },
+        }, options.signal);
+        session.compacted_item = item;
+        session.messages = [];
+        session.last_response_id = undefined;
+    }
+    catch (error) {
+        if (options.signal?.aborted) {
+            throw error;
+        }
+        // 压缩失败不能静默丢上下文；保留完整 session，后续 request body 超限时由后端暴露明确错误。
+    }
+}
+async function postResponses(fetchImpl, backendBaseUrl, apiKey, payload, options) {
+    const url = new URL('/v1/responses', backendBaseUrl);
+    const response = await fetchImpl(url.toString(), {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(payload),
+        signal: options.signal,
+    });
+    if (!response.ok) {
+        throw createBackendInvocationError(response.status, await parseJsonResponse(response));
+    }
+    if ((response.headers.get('content-type') ?? '').includes('text/event-stream')) {
+        return parseResponsesSSE(response, response.status, options.progressReporter);
+    }
+    return (await parseJsonResponse(response));
+}
+async function postCompact(fetchImpl, backendBaseUrl, apiKey, payload, signal) {
+    const url = new URL('/v1/responses/compact', backendBaseUrl);
+    const response = await fetchImpl(url.toString(), {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(payload),
+        signal,
+    });
+    const responseBody = await parseJsonResponse(response);
+    if (!response.ok) {
+        throw createBackendInvocationError(response.status, responseBody);
+    }
+    const body = responseBody;
+    const direct = body && body.type === 'compaction' ? body : undefined;
+    const fromField = body?.compaction;
+    const fromOutput = body?.output?.find((item) => item.type === 'compaction');
+    const item = direct ?? fromField ?? fromOutput;
+    if (!item) {
+        throw new Error('compact response did not include a compaction item');
+    }
+    return item;
+}
+async function parseResponsesSSE(response, status, progressReporter) {
+    if (!response.body) {
+        return parseResponsesSSEText(await response.text(), status, progressReporter);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const state = { generating: false, deltaEvents: 0 };
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        buffer += decoder.decode(value, { stream: !done });
+        buffer = buffer.replace(/\r\n/g, '\n');
+        let boundary = buffer.indexOf('\n\n');
+        while (boundary >= 0) {
+            const event = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            await processResponsesSSEEvent(event, status, state, progressReporter);
+            boundary = buffer.indexOf('\n\n');
+        }
+        if (done) {
+            break;
+        }
+    }
+    const remaining = buffer.trim();
+    if (remaining) {
+        await processResponsesSSEEvent(remaining, status, state, progressReporter);
+    }
+    return completedResponseOrThrow(state.completed, status);
+}
+async function parseResponsesSSEText(text, status, progressReporter) {
+    const state = { generating: false, deltaEvents: 0 };
+    for (const event of text.replace(/\r\n/g, '\n').split(/\n\n+/)) {
+        await processResponsesSSEEvent(event, status, state, progressReporter);
+    }
+    return completedResponseOrThrow(state.completed, status);
+}
+async function processResponsesSSEEvent(event, status, state, progressReporter) {
+    const payload = event
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('data:'))
+        .map((line) => line.slice('data:'.length).trim())
+        .join('\n')
+        .trim();
+    if (!payload || payload === '[DONE]') {
+        return;
+    }
+    let data;
+    try {
+        data = JSON.parse(payload);
+    }
+    catch {
+        return;
+    }
+    if (data.type === 'error' || data.type === 'response.failed' || data.error) {
+        throw createBackendInvocationErrorFromPayload(status, data.error ?? { message: data.message ?? 'Responses SSE error' });
+    }
+    if (data.type === 'response.output_text.delta') {
+        state.deltaEvents += 1;
+        if (!state.generating) {
+            state.generating = true;
+            await reportProgress(progressReporter, 45, 'Invokora is generating a response...');
+        }
+        else if (state.deltaEvents % 25 === 0) {
+            await reportProgress(progressReporter, Math.min(90, 45 + Math.floor(state.deltaEvents / 25)), 'Still generating...');
+        }
+        return;
+    }
+    if (data.type === 'response.completed' && data.response) {
+        state.completed = data.response;
+        await reportProgress(progressReporter, 90, 'Invokora response received.');
+    }
+}
+function completedResponseOrThrow(completed, status) {
+    if (!completed?.id) {
+        throw new Error(`Responses SSE stream ended without response.completed: HTTP ${status}`);
+    }
+    return completed;
+}
+async function reportProgress(progressReporter, progress, message) {
+    try {
+        await progressReporter?.report({ progress, total: 100, message });
+    }
+    catch {
+        // progress 只是客户端体验信号，不能改变 chat tool 的业务结果。
+    }
+}

package/dist/cli/mcp/schemas.d.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import type { ReasoningEffort } from '../types.js';
+import type { ProgressReporter } from './progress.js';
+export declare const SKILZ_CHAT_TOOL = "chat";
+export declare const ReasoningEffortSchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    xhigh: "xhigh";
+}>;
+export type ChatReason = ReasoningEffort;
+export declare const ChatToolInputSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+    }>>;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export declare const ChatToolOutputSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    response_id: z.ZodOptional<z.ZodString>;
+    model: z.ZodString;
+    output_text: z.ZodString;
+    usage: z.ZodOptional<z.ZodObject<{
+        input_tokens: z.ZodNumber;
+        output_tokens: z.ZodNumber;
+        cache_read_input_tokens: z.ZodNumber;
+    }, z.core.$strip>>;
+    charge: z.ZodOptional<z.ZodObject<{
+        charge_ref: z.ZodOptional<z.ZodString>;
+        product_id: z.ZodOptional<z.ZodString>;
+        billing_mode: z.ZodOptional<z.ZodString>;
+        skill_fee_cents: z.ZodNumber;
+        skill_fee_microusd: z.ZodNumber;
+        model_fee_cents: z.ZodNumber;
+        model_fee_microcents: z.ZodOptional<z.ZodNumber>;
+        model_fee_microusd: z.ZodNumber;
+        total_fee_cents: z.ZodNumber;
+        total_fee_microusd: z.ZodNumber;
+        wallet_hold_cents: z.ZodNumber;
+        wallet_hold_microusd: z.ZodNumber;
+        charge_status: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export declare const BackendErrorResponseSchema: z.ZodObject<{
+    request_id: z.ZodOptional<z.ZodString>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type ChatToolInput = z.infer<typeof ChatToolInputSchema>;
+export type ChatToolOutput = z.infer<typeof ChatToolOutputSchema>;
+export type ToolTextContent = {
+    type: 'text';
+    text: string;
+};
+export type ToolResult<TStructured extends Record<string, unknown> = Record<string, unknown>> = {
+    content: ToolTextContent[];
+    structuredContent?: TStructured;
+    isError?: true;
+};
+export type ChatToolResult = ToolResult<ChatToolOutput>;
+export type ResponsesCompleteResponse = {
+    id?: string;
+    model?: string;
+    output_text?: string;
+    usage?: ChatToolOutput['usage'];
+    charge?: ChatToolOutput['charge'];
+    error?: {
+        code?: string;
+        message?: string;
+    };
+};
+export type ChatViaBackendOptions = {
+    backendBaseUrl: string;
+    authToken?: string;
+    refreshToken?: string;
+    apiKey?: string;
+    defaultModel?: string;
+    defaultReason?: ReasoningEffort;
+    fetchImpl?: typeof fetch;
+    sessionStore?: import('./session_store.js').McpSessionStore;
+    compactAfterChars?: number;
+    progressReporter?: ProgressReporter;
+    signal?: AbortSignal;
+};
+export type HandleChatToolOptions = ChatViaBackendOptions;
+export type StartStdioServerOptions = ChatViaBackendOptions;

package/dist/cli/mcp/schemas.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+export const SKILZ_CHAT_TOOL = 'chat';
+export const ReasoningEffortSchema = z.enum(['low', 'medium', 'high', 'xhigh']);
+const NonBlankStringSchema = z.string().refine((value) => value.trim().length > 0, {
+    message: 'Too small: expected string to have >=1 characters',
+});
+const MessageSchema = z.object({
+    role: z.enum(['user', 'assistant']).describe('Conversation role. The final message sent to chat must be user.'),
+    content: NonBlankStringSchema.describe('Plain text message content.'),
+});
+export const ChatToolInputSchema = z
+    .object({
+    session_id: z
+        .string()
+        .trim()
+        .optional()
+        .describe('Local MCP chat session id. Omit to create a new local session.'),
+    model: z.string().trim().optional().describe('Optional model override.'),
+    reason: ReasoningEffortSchema.optional().describe('Optional reasoning effort override: low, medium, high, or xhigh.'),
+    messages: z
+        .array(MessageSchema)
+        .min(1)
+        .describe('New plain-text user/assistant messages to append to the local MCP chat session. Last message must be role=user.'),
+})
+    .strict();
+export const ChatToolOutputSchema = z
+    .object({
+    session_id: z.string(),
+    response_id: z.string().optional(),
+    model: z.string(),
+    output_text: z.string(),
+    usage: z
+        .object({
+        input_tokens: z.number().int(),
+        output_tokens: z.number().int(),
+        cache_read_input_tokens: z.number().int(),
+    })
+        .optional(),
+    charge: z
+        .object({
+        charge_ref: z.string().optional(),
+        product_id: z.string().optional(),
+        billing_mode: z.string().optional(),
+        skill_fee_cents: z.number().int(),
+        skill_fee_microusd: z.number().int(),
+        model_fee_cents: z.number().int(),
+        model_fee_microcents: z.number().int().optional(),
+        model_fee_microusd: z.number().int(),
+        total_fee_cents: z.number().int(),
+        total_fee_microusd: z.number().int(),
+        wallet_hold_cents: z.number().int(),
+        wallet_hold_microusd: z.number().int(),
+        charge_status: z.string().optional(),
+    })
+        .optional(),
+})
+    .strict();
+export const BackendErrorResponseSchema = z
+    .object({
+    request_id: z.string().optional(),
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+    }),
+})
+    .strict();

package/dist/cli/mcp/server.d.ts

@@ -0,0 +1,4 @@
+export { InvokoraMcpApp, createMcpServer, resolveBackendBaseUrl, startStdioServer } from './app.js';
+export { chatViaBackend, handleChatTool, } from './tool_handlers.js';
+export { BackendErrorResponseSchema, ChatToolInputSchema, ChatToolOutputSchema, SKILZ_CHAT_TOOL, } from './schemas.js';
+export type { ChatToolInput, ChatToolOutput, ChatToolResult, ChatViaBackendOptions, HandleChatToolOptions, ResponsesCompleteResponse, StartStdioServerOptions, ToolTextContent, ToolResult, } from './schemas.js';

package/dist/cli/mcp/server.js

@@ -0,0 +1,3 @@
+export { InvokoraMcpApp, createMcpServer, resolveBackendBaseUrl, startStdioServer } from './app.js';
+export { chatViaBackend, handleChatTool, } from './tool_handlers.js';
+export { BackendErrorResponseSchema, ChatToolInputSchema, ChatToolOutputSchema, SKILZ_CHAT_TOOL, } from './schemas.js';

package/dist/cli/mcp/session_store.d.ts

@@ -0,0 +1,32 @@
+import type { ReasoningEffort } from '../types.js';
+export type ChatMessage = {
+    role: 'user' | 'assistant';
+    content: string;
+};
+export type ResponsesInputItem = {
+    role: 'user' | 'assistant';
+    content: string;
+} | {
+    type: 'compaction';
+    [key: string]: unknown;
+};
+export type McpChatSession = {
+    session_id: string;
+    messages: ChatMessage[];
+    compacted_item?: Record<string, unknown>;
+    last_response_id?: string;
+    model?: string;
+    reason?: ReasoningEffort;
+    metadata?: Record<string, unknown>;
+    updated_at: string;
+};
+export declare class McpSessionStore {
+    private readonly baseDir;
+    constructor(baseDir?: string);
+    createSessionID(): string;
+    loadOrCreate(sessionID?: string): McpChatSession;
+    save(session: McpChatSession): void;
+    sessionPath(sessionID: string): string;
+}
+export declare function replayInputForSession(session: McpChatSession): ResponsesInputItem[];
+export declare function validateSessionID(sessionID: string): void;

package/dist/cli/mcp/session_store.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { MCP_SESSION_DIR } from '../constants.js';
+const SESSION_ID_PATTERN = /^[A-Za-z0-9._-]{1,120}$/;
+export class McpSessionStore {
+    baseDir;
+    constructor(baseDir = MCP_SESSION_DIR) {
+        this.baseDir = baseDir;
+    }
+    createSessionID() {
+        return randomUUID();
+    }
+    loadOrCreate(sessionID) {
+        const id = sessionID?.trim() || this.createSessionID();
+        validateSessionID(id);
+        const path = this.sessionPath(id);
+        if (!existsSync(path)) {
+            return { session_id: id, messages: [], updated_at: new Date(0).toISOString() };
+        }
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed.session_id !== id || !Array.isArray(parsed.messages)) {
+            throw new Error(`Invalid MCP chat session: ${path}`);
+        }
+        return parsed;
+    }
+    save(session) {
+        validateSessionID(session.session_id);
+        const path = this.sessionPath(session.session_id);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+        try {
+            writeFileSync(tmpPath, JSON.stringify(session, null, 2) + '\n', { mode: 0o600 });
+            renameSync(tmpPath, path);
+        }
+        catch (error) {
+            rmSync(tmpPath, { force: true });
+            throw error;
+        }
+    }
+    sessionPath(sessionID) {
+        validateSessionID(sessionID);
+        return join(this.baseDir, `${sessionID}.json`);
+    }
+}
+export function replayInputForSession(session) {
+    const input = [];
+    if (session.compacted_item) {
+        input.push(session.compacted_item);
+    }
+    input.push(...session.messages.map((message) => ({ role: message.role, content: message.content })));
+    return input;
+}
+export function validateSessionID(sessionID) {
+    if (!SESSION_ID_PATTERN.test(sessionID)) {
+        throw new Error('session_id must be 1-120 chars and contain only letters, numbers, dot, underscore, or dash');
+    }
+}

package/dist/cli/mcp/tool_handlers.d.ts

@@ -0,0 +1,3 @@
+import { type ChatToolInput, type ChatToolOutput, type ChatToolResult, type HandleChatToolOptions } from './schemas.js';
+export declare function handleChatTool(rawInput: unknown, options: HandleChatToolOptions): Promise<ChatToolResult>;
+export declare function chatViaBackend(input: ChatToolInput, options: HandleChatToolOptions): Promise<ChatToolOutput>;

package/dist/cli/mcp/tool_handlers.js

@@ -0,0 +1,26 @@
+import { createErrorResult, formatToolError, formatZodError } from './errors.js';
+import { InvokoraBackendClient } from './backend_client.js';
+import { ChatToolInputSchema, } from './schemas.js';
+export async function handleChatTool(rawInput, options) {
+    const parsedInput = ChatToolInputSchema.safeParse(rawInput);
+    if (!parsedInput.success) {
+        return createErrorResult(`Invalid tool input: ${formatZodError(parsedInput.error)}`);
+    }
+    const lastMessage = parsedInput.data.messages[parsedInput.data.messages.length - 1];
+    if (lastMessage?.role !== 'user') {
+        return createErrorResult('Invalid tool input: messages must end with role=user');
+    }
+    try {
+        const structuredContent = await chatViaBackend(parsedInput.data, options);
+        return {
+            content: [{ type: 'text', text: structuredContent.output_text }],
+            structuredContent,
+        };
+    }
+    catch (error) {
+        return createErrorResult(formatToolError(error));
+    }
+}
+export async function chatViaBackend(input, options) {
+    return new InvokoraBackendClient(options).chat(input);
+}

package/dist/cli/mcp_setup.d.ts

@@ -0,0 +1,33 @@
+import type { CliPrompts } from './prompts.js';
+import type { Config, McpServerConfig, McpTarget, ParsedMcpSetupArgs } from './types.js';
+export interface SetupTargetResult {
+    status: 'updated' | 'skipped';
+    path: string;
+}
+export declare class McpConfigService {
+    private readonly prompts;
+    constructor(prompts: Pick<CliPrompts, 'pickMcpTargets' | 'yesNo'>);
+    buildServerConfig(_config: Config): McpServerConfig;
+    parseSetupArgs(args: string[]): ParsedMcpSetupArgs;
+    resolveTargets(parsed: ParsedMcpSetupArgs): Promise<McpTarget[]>;
+    mapPathsToTargets(targets: McpTarget[], paths: string[]): Map<McpTarget, string>;
+    setupTargetConfig(params: {
+        target: McpTarget;
+        explicitPath?: string;
+        serverConfig: McpServerConfig;
+        yes: boolean;
+    }): Promise<SetupTargetResult>;
+    private resolveClientConfigPath;
+    private writeJsonMcpConfig;
+    private loadOrInitMcpConfig;
+    private upsertInvokoraServer;
+    private writeCodexMcpConfig;
+    private writeSecureFile;
+    private resolveSecureFileMode;
+    private renderCodexInvokoraSection;
+    private escapeTomlString;
+    private isLikelyJson;
+    private upsertTomlSection;
+    private isMcpTarget;
+    private uniqueTargets;
+}