@minko-ai/minko 0.1.0 → 0.1.1

package/dist/sandbox/index.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+const DEFAULT_IMAGE = 'debian:bookworm-slim';
+export function resolveSandbox(config) {
+    const sandbox = config?.sandbox;
+    if (!sandbox || sandbox.mode !== 'docker') {
+        return null;
+    }
+    return {
+        mode: 'docker',
+        image: sandbox.image && sandbox.image.length > 0 ? sandbox.image : DEFAULT_IMAGE,
+        network: sandbox.network === true,
+        extraArgs: sandbox.extraArgs ?? [],
+        allowFallback: sandbox.allowFallback === true,
+    };
+}
+/** Builds `docker run` arguments with the workspace mounted at /workspace. */
+export function dockerArgs(options, command, cwd) {
+    const workspace = path.resolve(cwd);
+    return [
+        'run',
+        '--rm',
+        '-i',
+        '-v', workspace + ':/workspace',
+        '-w', '/workspace',
+        ...(options.network ? [] : ['--network', 'none']),
+        ...options.extraArgs,
+        options.image,
+        'sh',
+        '-lc',
+        command,
+    ];
+}
+let dockerProbe = null;
+export function dockerAvailable() {
+    if (dockerProbe !== null) {
+        return dockerProbe;
+    }
+    try {
+        const result = spawnSync('docker', ['version', '--format', '{{.Server.Version}}'], {
+            timeout: 3_000,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        dockerProbe = result.status === 0;
+    }
+    catch {
+        dockerProbe = false;
+    }
+    return dockerProbe;
+}
+/** Test seam for environments where Docker availability changes. */
+export function resetDockerProbeForTests() {
+    dockerProbe = null;
+}

package/dist/sdk/server.js

@@ -0,0 +1,150 @@
+import readline from 'node:readline';
+import { SessionStore } from "../session/store.js";
+import { ApprovalTokenStore } from "../agent/approvalTokens.js";
+import { readVersion } from "../util/version.js";
+import { SdkSession } from "./session.js";
+/** NDJSON JSON-RPC server for programmatic Minko sessions. */
+export class SdkServer {
+    store;
+    cwd;
+    config;
+    getProvider;
+    approvalStore;
+    onEvent;
+    busy = new Set();
+    constructor(options) {
+        this.store = options.store ?? new SessionStore();
+        this.cwd = options.cwd ?? process.cwd();
+        this.config = options.config;
+        this.getProvider = options.getProvider;
+        this.approvalStore = options.approvalStore ?? new ApprovalTokenStore();
+        this.onEvent = options.onEvent ?? (() => { });
+    }
+    async handle(message) {
+        const method = typeof message.method === 'string' ? message.method : '';
+        const id = message.id;
+        const params = message.params !== null && typeof message.params === 'object'
+            ? message.params : {};
+        if (method === 'initialize') {
+            return result(id, {
+                protocolVersion: '1',
+                serverInfo: { name: 'minko-sdk', version: readVersion() },
+                capabilities: { chat: true, streaming: true, sessions: true },
+            });
+        }
+        if (method === 'session.create') {
+            const cwd = typeof params.cwd === 'string' && params.cwd.trim().length > 0
+                ? params.cwd.trim() : this.cwd;
+            const model = typeof params.model === 'string' && params.model.trim().length > 0
+                ? params.model.trim() : 'sdk';
+            const meta = this.store.create(cwd, model);
+            return result(id, { session: meta });
+        }
+        if (method === 'session.list') {
+            return result(id, { sessions: this.store.list() });
+        }
+        if (method === 'session.get') {
+            const sessionId = typeof params.session === 'string' ? params.session : '';
+            const record = this.store.load(sessionId);
+            if (!record) {
+                return error(id, -32602, 'session not found: ' + sessionId);
+            }
+            return result(id, record);
+        }
+        if (method === 'session.delete') {
+            const sessionId = typeof params.session === 'string' ? params.session : '';
+            return result(id, { ok: this.store.delete(sessionId) });
+        }
+        if (method === 'chat') {
+            const sessionId = typeof params.session === 'string' ? params.session : '';
+            const text = typeof params.text === 'string' ? params.text : '';
+            if (text.trim().length === 0) {
+                return error(id, -32602, 'text is required');
+            }
+            if (this.busy.has(sessionId)) {
+                return error(id, -32603, 'session is busy');
+            }
+            const record = this.store.load(sessionId);
+            if (!record) {
+                return error(id, -32602, 'session not found: ' + sessionId);
+            }
+            this.busy.add(sessionId);
+            try {
+                const session = new SdkSession({
+                    store: this.store,
+                    record,
+                    provider: this.getProvider(),
+                    config: this.config,
+                    approval: params.approval === 'auto' ? 'auto' : 'ask',
+                    approvalStore: this.approvalStore,
+                    onEvent: (event) => this.onEvent(id ?? null, event),
+                });
+                const outcome = await session.chat(text);
+                return result(id, {
+                    text: outcome.text,
+                    usage: outcome.usage,
+                    messages: outcome.messages,
+                    session: record.meta,
+                });
+            }
+            catch (caught) {
+                return error(id, -32603, caught instanceof Error ? caught.message : String(caught));
+            }
+            finally {
+                this.busy.delete(sessionId);
+            }
+        }
+        if (method === 'shutdown') {
+            return result(id, null);
+        }
+        if (method === 'exit') {
+            return null;
+        }
+        if (id !== undefined && id !== null) {
+            return error(id, -32601, 'method not found: ' + method);
+        }
+        return null;
+    }
+}
+export async function runSdkServer(options) {
+    const server = new SdkServer({
+        ...options,
+        onEvent: (requestId, event) => {
+            const payload = JSON.stringify({
+                jsonrpc: '2.0',
+                method: 'minko.event',
+                params: { requestId, event },
+            });
+            process.stdout.write(payload + '\n');
+            options.onEvent?.(requestId, event);
+        },
+    });
+    process.stderr.write('Minko SDK 已启动（NDJSON JSON-RPC，stdout 只输出协议消息）\n');
+    const rl = readline.createInterface({ input: process.stdin });
+    for await (const line of rl) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const response = await server.handle(message);
+        if (response) {
+            process.stdout.write(JSON.stringify(response) + '\n');
+        }
+        if (message.method === 'shutdown' || message.method === 'exit') {
+            break;
+        }
+    }
+    return 0;
+}
+function result(id, value) {
+    return { jsonrpc: '2.0', id, result: value };
+}
+function error(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}

package/dist/sdk/session.js

@@ -0,0 +1,104 @@
+import { runAgent } from "../agent/loop.js";
+import { createPlanTools } from "../agent/plan.js";
+import { createMemoryTools, defaultMemoryDir, loadMemoryContext, } from "../agent/memory.js";
+import { ApprovalTokenStore } from "../agent/approvalTokens.js";
+import { loadProjectContext } from "../agent/context.js";
+import { systemPrompt } from "../agent/prompt.js";
+import { ALL_TOOLS } from "../tools/registry.js";
+import { titleFromMessages } from "../session/store.js";
+import { TurnRecorder } from "../session/recorder.js";
+/** One persistent Minko session driven programmatically. */
+export class SdkSession {
+    store;
+    record;
+    provider;
+    config;
+    approval;
+    approve;
+    approvalStore;
+    onEvent;
+    constructor(options) {
+        this.store = options.store;
+        this.record = options.record;
+        this.provider = options.provider;
+        this.config = options.config;
+        this.approval = options.approval ?? 'ask';
+        this.approve = options.approve ?? (async () => false);
+        this.approvalStore = options.approvalStore ?? new ApprovalTokenStore();
+        this.onEvent = options.onEvent ?? (() => { });
+    }
+    async chat(text, signal = new AbortController().signal) {
+        const prompt = text.trim();
+        if (prompt.length === 0) {
+            throw new Error('text is required');
+        }
+        const history = this.record.messages;
+        history.push({ role: 'user', content: prompt });
+        this.record.meta.title = titleFromMessages(history);
+        this.store.save(this.record.meta, history);
+        const recorder = new TurnRecorder(this.store, this.record.meta, history);
+        const cwd = this.record.meta.cwd;
+        const system = systemPrompt({
+            cwd,
+            project: loadProjectContext(cwd),
+            planMode: this.record.meta.planMode,
+            memory: loadMemoryContext(defaultMemoryDir()),
+        });
+        const tools = [
+            ...ALL_TOOLS,
+            ...createPlanTools(this.record.meta),
+            ...createMemoryTools(defaultMemoryDir()),
+        ];
+        try {
+            const outcome = await runAgent({
+                provider: this.provider,
+                tools,
+                messages: [{ role: 'system', content: system }, ...history],
+                cwd,
+                signal,
+                approval: this.approval,
+                power: this.config?.power ?? 'restricted',
+                permissions: this.config?.permissions,
+                toolHooks: this.config?.hooks,
+                planState: this.record.meta,
+                config: this.config,
+                approvalStore: this.approvalStore,
+                maxRounds: 40,
+                hooks: {
+                    onText: (delta) => this.onEvent({ type: 'text', text: delta }),
+                    onReasoning: (delta) => this.onEvent({ type: 'reasoning', text: delta }),
+                    onToolStart: (call, args) => this.onEvent({ type: 'tool_start', call, args }),
+                    onToolEnd: (call, result) => this.onEvent({
+                        type: 'tool_end',
+                        call,
+                        ok: result.ok,
+                        output: result.output,
+                        ms: result.ms,
+                    }),
+                    approve: this.approval === 'auto' ? async () => true : this.approve,
+                    onNotice: (notice) => this.onEvent({ type: 'notice', text: notice }),
+                    onAssistantMessage: (message) => recorder.record(message),
+                },
+            });
+            const messages = outcome.messages.filter((message) => message.role !== 'system');
+            this.record.messages = messages;
+            this.record.meta.title = titleFromMessages(messages);
+            recorder.commit(messages);
+            this.onEvent({ type: 'done', usage: outcome.usage });
+            const last = [...messages]
+                .reverse()
+                .find((message) => message.role === 'assistant' && message.content.length > 0);
+            return {
+                text: last && last.role === 'assistant' ? last.content : '',
+                usage: outcome.usage,
+                messages: messages.length,
+            };
+        }
+        catch (error) {
+            this.record.messages = recorder.snapshot();
+            this.record.meta.title = titleFromMessages(this.record.messages);
+            recorder.recover();
+            throw error;
+        }
+    }
+}

package/dist/session/liveness.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const STALE_MS = 60_000;
+const HEARTBEAT_MS = 15_000;
+export function statusFile(dir, id) {
+    if (!/^[A-Za-z0-9._-]+$/.test(id)) {
+        throw new Error('非法的会话 id');
+    }
+    return path.join(dir, id + '.status.json');
+}
+export function writeStatus(dir, status) {
+    // Invalid ids must fail loudly; filesystem problems are only advisory.
+    const file = statusFile(dir, status.sessionId);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const payload = JSON.stringify(status);
+        const temporary = file + '.tmp';
+        fs.writeFileSync(temporary, payload, 'utf8');
+        try {
+            fs.renameSync(temporary, file);
+        }
+        catch {
+            fs.writeFileSync(file, payload, 'utf8');
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch {
+        // Liveness is advisory; never break a turn over it.
+    }
+}
+export function readStatus(dir, id) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(statusFile(dir, id), 'utf8'));
+        if (raw.sessionId !== id) {
+            return null;
+        }
+        if (raw.status !== 'idle' && raw.status !== 'running' && raw.status !== 'waiting_approval') {
+            return null;
+        }
+        if (typeof raw.pid !== 'number' || typeof raw.updatedAt !== 'string') {
+            return null;
+        }
+        return {
+            sessionId: id,
+            status: raw.status,
+            pid: raw.pid,
+            updatedAt: raw.updatedAt,
+            ...(typeof raw.title === 'string' ? { title: raw.title } : {}),
+            ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function clearStatus(dir, id) {
+    try {
+        fs.unlinkSync(statusFile(dir, id));
+    }
+    catch { /* already gone */ }
+}
+export function listStatuses(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const statuses = [];
+    for (const name of names) {
+        if (!name.endsWith('.status.json')) {
+            continue;
+        }
+        const status = readStatus(dir, name.slice(0, -'.status.json'.length));
+        if (status) {
+            statuses.push(status);
+        }
+    }
+    statuses.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    return statuses;
+}
+export function isLive(status, now = Date.now(), staleMs = STALE_MS) {
+    if (!status) {
+        return false;
+    }
+    const updated = Date.parse(status.updatedAt);
+    return Number.isFinite(updated) && now - updated <= staleMs;
+}
+export function statusLabel(status) {
+    switch (status) {
+        case 'running': return '正在跑';
+        case 'waiting_approval': return '等确认';
+        case 'idle': return '空闲';
+        default: return '离线';
+    }
+}
+/** Keeps one session's status file fresh while the terminal is open. */
+export class SessionHeartbeat {
+    dir;
+    meta;
+    status = 'idle';
+    timer = null;
+    constructor(dir, meta) {
+        this.dir = dir;
+        this.meta = meta;
+    }
+    start() {
+        this.persist();
+        if (this.timer) {
+            return;
+        }
+        this.timer = setInterval(() => this.persist(), HEARTBEAT_MS);
+        this.timer.unref?.();
+    }
+    setStatus(status) {
+        this.status = status;
+        this.persist();
+    }
+    /** Point the heartbeat at a new session after /new or /fork. */
+    retarget(meta) {
+        if (meta.id !== this.meta.id) {
+            clearStatus(this.dir, this.meta.id);
+        }
+        this.meta = meta;
+        this.persist();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        clearStatus(this.dir, this.meta.id);
+    }
+    persist() {
+        writeStatus(this.dir, {
+            sessionId: this.meta.id,
+            status: this.status,
+            pid: process.pid,
+            updatedAt: new Date().toISOString(),
+            title: this.meta.title,
+            cwd: this.meta.cwd,
+        });
+    }
+}

package/dist/session/recorder.js

@@ -0,0 +1,49 @@
+import { repairTranscript } from "../agent/transcript.js";
+/**
+ * Persists a turn after every assistant/tool message. A crash or an interrupt
+ * therefore leaves a readable session instead of losing the whole turn.
+ */
+export class TurnRecorder {
+    store;
+    meta;
+    base;
+    turn = [];
+    /** Last persistence error, if the disk became unavailable mid-turn. */
+    lastError = null;
+    constructor(store, meta, base) {
+        this.store = store;
+        this.meta = meta;
+        this.base = base.slice();
+    }
+    record(message) {
+        this.turn.push(message);
+        this.persist();
+    }
+    snapshot() {
+        return [...this.base, ...this.turn];
+    }
+    /** Repairs unanswered tool calls, persists the result and makes it the new base. */
+    recover() {
+        const repaired = repairTranscript(this.snapshot()).messages;
+        this.base = repaired;
+        this.turn = [];
+        this.persist();
+        return repaired;
+    }
+    /** Stores the final transcript (which may include a compaction summary). */
+    commit(finalMessages) {
+        this.base = finalMessages.slice();
+        this.turn = [];
+        this.persist();
+    }
+    persist() {
+        try {
+            this.store.save(this.meta, this.snapshot());
+            this.lastError = null;
+        }
+        catch (error) {
+            // A full disk or a read-only home must not kill the conversation.
+            this.lastError = error;
+        }
+    }
+}

package/dist/session/store.js

@@ -0,0 +1,171 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { sessionsDir } from "../config/paths.js";
+import { repairTranscript } from "../agent/transcript.js";
+/** Sessions live in ~/.minko/sessions/<id>.jsonl: one meta line, then messages. */
+export class SessionStore {
+    dir;
+    /** True once a write failed and the store moved to the temp fallback. */
+    fallback = false;
+    constructor(dir = sessionsDir()) {
+        this.dir = dir;
+    }
+    fileFor(id) {
+        if (!/^[A-Za-z0-9._-]+$/.test(id)) {
+            throw new Error('非法的会话 id');
+        }
+        return path.join(this.dir, id + '.jsonl');
+    }
+    create(cwd, model, id) {
+        const now = new Date().toISOString();
+        const meta = {
+            id: id ?? newSessionId(),
+            title: '新会话',
+            cwd,
+            model,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.write(meta, []);
+        return meta;
+    }
+    save(meta, messages) {
+        this.write({ ...meta, updatedAt: new Date().toISOString() }, messages);
+    }
+    /** Copies a session into a new branch; the source is left untouched. */
+    fork(id, name) {
+        const source = this.load(id);
+        if (!source) {
+            return null;
+        }
+        const now = new Date().toISOString();
+        const label = name?.trim() ?? '';
+        const meta = {
+            ...source.meta,
+            id: newSessionId(),
+            title: label.length > 0 ? label : source.meta.title + '（分支）',
+            createdAt: now,
+            updatedAt: now,
+            forkedFrom: source.meta.id,
+            forkName: label.length > 0 ? label : undefined,
+        };
+        const messages = structuredClone(source.messages);
+        this.save(meta, messages);
+        return { meta, messages };
+    }
+    load(id) {
+        const file = this.fileFor(id);
+        if (!fs.existsSync(file)) {
+            return null;
+        }
+        const lines = fs.readFileSync(file, 'utf8').split('\n');
+        let meta = null;
+        const messages = [];
+        for (const line of lines) {
+            if (line.trim().length === 0) {
+                continue;
+            }
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (record.type === 'meta' && record.meta) {
+                meta = record.meta;
+            }
+            else if (record.type === 'message' && record.message) {
+                messages.push(record.message);
+            }
+        }
+        if (!meta) {
+            return null;
+        }
+        return { meta, messages: repairTranscript(messages).messages };
+    }
+    list() {
+        if (!fs.existsSync(this.dir)) {
+            return [];
+        }
+        const metas = [];
+        for (const name of fs.readdirSync(this.dir)) {
+            if (!name.endsWith('.jsonl')) {
+                continue;
+            }
+            const record = this.load(name.slice(0, -6));
+            if (record) {
+                metas.push(record.meta);
+            }
+        }
+        metas.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return metas;
+    }
+    latest(cwd) {
+        const candidates = this.list();
+        if (cwd === undefined) {
+            return candidates.length > 0 ? candidates[0] : null;
+        }
+        const resolved = path.resolve(cwd);
+        return candidates.find((meta) => path.resolve(meta.cwd) === resolved) ?? null;
+    }
+    delete(id) {
+        const file = this.fileFor(id);
+        if (!fs.existsSync(file)) {
+            return false;
+        }
+        fs.unlinkSync(file);
+        return true;
+    }
+    write(meta, messages) {
+        const lines = [JSON.stringify({ type: 'meta', meta })];
+        for (const message of messages) {
+            lines.push(JSON.stringify({ type: 'message', message }));
+        }
+        const payload = lines.join('\n') + '\n';
+        try {
+            this.writeTo(this.dir, meta.id, payload);
+        }
+        catch (error) {
+            const fallback = fallbackSessionsDir();
+            if (this.dir === fallback) {
+                throw error;
+            }
+            this.dir = fallback;
+            this.fallback = true;
+            this.writeTo(fallback, meta.id, payload);
+        }
+    }
+    writeTo(dir, id, payload) {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, id + '.jsonl'), payload, 'utf8');
+    }
+}
+/** Some locked-down Windows profiles reject writes entirely; use temp then. */
+export function fallbackSessionsDir() {
+    let user = 'user';
+    try {
+        user = os.userInfo().username || 'user';
+    }
+    catch {
+        user = 'user';
+    }
+    return path.join(os.tmpdir(), 'minko-' + user, 'sessions');
+}
+export function newSessionId(now = new Date()) {
+    const pad = (value, width = 2) => String(value).padStart(width, '0');
+    const stamp = String(now.getFullYear())
+        + pad(now.getMonth() + 1) + pad(now.getDate()) + '-'
+        + pad(now.getHours()) + pad(now.getMinutes()) + pad(now.getSeconds());
+    const random = Math.random().toString(36).slice(2, 6);
+    return stamp + '-' + random;
+}
+export function titleFromMessages(messages) {
+    const first = messages.find((message) => message.role === 'user');
+    if (!first || first.role !== 'user') {
+        return '新会话';
+    }
+    const line = first.content.replace(/\s+/g, ' ').trim();
+    return line.length > 40 ? line.slice(0, 40) + '…' : (line || '新会话');
+}