@mininglamp-oss/octo-runtime-client 0.0.0-stage → 1.1.11

package/dist/client.js

@@ -0,0 +1,465 @@
+import net from "node:net";
+import { assertIpcEndpoint } from "./runtime-path.js";
+import { randomUUID } from "node:crypto";
+import { assertHostFrame, assertHostFrameIdentity, assertHostRunReceipt, assertKernelStatus, createInputInvoke, identifyInvokeInput, isHostTerminal, HOST_RPC_MAX_LINE_BYTES, INVOKE_REQUEST_MAX_BYTES } from "@mininglamp-oss/octo-runtime-protocol";
+import { KernelError } from "./types.js";
+import { InvocationRegistry } from "./invocation-lifecycle.js";
+import { markSubmissionRejected } from "./submission-error.js";
+/**
+ * 连接本机 socket/Windows Pipe，返回不拥有 Kernel 进程的客户端。
+ * 独立应用显式连接已有服务；原生 SDK 服务宿主使用 kernel.client。
+ * Kernel/Extra 服务内部也复用本函数构造 RPC 客户端，不要求 SDK 调用方额外 attach。
+ * invoke 提供登记、取消和尾流观察；关闭连接或迭代器不会隐式取消已接纳 Run。
+ */
+export function attachKernel(options) {
+    const endpoint = options.endpoint;
+    assertIpcEndpoint(endpoint);
+    const sockets = new Set();
+    let closed = false;
+    const open = async (signal, timeout = 5000) => {
+        if (closed)
+            throw new KernelError("CLIENT_CLOSED");
+        if (sockets.size >= 32)
+            throw new KernelError("CLIENT_CAPACITY_EXHAUSTED");
+        signal?.throwIfAborted();
+        const socket = net.createConnection(endpoint);
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+        socket.on("error", () => { });
+        const abort = () => socket.destroy(new KernelError("SUBSCRIPTION_ABORTED"));
+        signal?.addEventListener("abort", abort, { once: true });
+        socket.once("close", () => signal?.removeEventListener("abort", abort));
+        await new Promise((resolve, reject) => {
+            const finish = (error) => {
+                clearTimeout(timer);
+                socket.off("connect", connected);
+                socket.off("error", failed);
+                socket.off("close", disconnected);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const connected = () => finish();
+            const failed = (error) => finish(error);
+            const disconnected = () => finish(new KernelError(closed ? "CLIENT_CLOSED" : "CONNECTION_CLOSED"));
+            const timer = setTimeout(() => {
+                socket.destroy();
+                finish(new KernelError("KERNEL_UNAVAILABLE"));
+            }, Math.min(5000, timeout));
+            socket.once("connect", connected);
+            socket.once("error", failed);
+            socket.once("close", disconnected);
+        }).catch(() => {
+            socket.destroy();
+            throw new KernelError(closed ? "CLIENT_CLOSED" : "KERNEL_UNAVAILABLE");
+        });
+        return socket;
+    };
+    const exchange = async (method, params = {}, timeout = 5000, signal, beforeSend, sent) => {
+        const until = Date.now() + timeout;
+        const socket = await open(signal, timeout);
+        const timer = setTimeout(() => socket.destroy(new KernelError("KERNEL_TIMEOUT")), Math.max(1, until - Date.now()));
+        const id = randomUUID();
+        try {
+            signal?.throwIfAborted();
+            beforeSend?.();
+            send(socket, id, method, params);
+            sent?.();
+            for await (const value of lines(socket))
+                return response(value, id);
+            throw new KernelError(closed ? "CLIENT_CLOSED" : "CONNECTION_CLOSED");
+        }
+        catch (error) {
+            if (closed)
+                throw new KernelError("CLIENT_CLOSED");
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            socket.destroy();
+        }
+    };
+    const query = async (key, expectedInstance, deadline = Date.now() + 5000, signal) => {
+        const info = (await exchange("agent_run.get", {
+            key: lookupForKey(key),
+            kernel_instance_id: expectedInstance
+        }, remaining(deadline), signal));
+        assertHostRunReceipt(receiptFor(info.ref));
+        if (expectedInstance !== undefined && info.ref.kernel_instance_id !== expectedInstance)
+            throw new KernelError("KERNEL_INSTANCE_CHANGED");
+        if (!sameLookup(info.ref, key))
+            throw new KernelError("RUN_IDENTITY_MISMATCH");
+        if (info.terminal) {
+            assertHostFrame(info.terminal);
+            assertHostFrameIdentity(info.terminal, receiptFor(info.ref));
+            if (!isHostTerminal(info.terminal))
+                throw new KernelError("HOST_FRAME_INVALID");
+        }
+        registry.reconcile(info.ref, info.terminal);
+        return info;
+    };
+    const cancel = async (ref, reason, deadline = Date.now() + 5000, signal) => {
+        try {
+            const result = (await exchange("agent_run.cancel", { ref, reason }, remaining(deadline), signal));
+            if (typeof result?.accepted !== "boolean")
+                throw new KernelError("OPERATION_OUTCOME_UNKNOWN");
+            return result;
+        }
+        catch (error) {
+            if (error instanceof KernelError &&
+                !["CONNECTION_CLOSED", "KERNEL_TIMEOUT", "SUBSCRIPTION_ABORTED"].includes(error.code))
+                throw error;
+            throw new KernelError("OPERATION_OUTCOME_UNKNOWN");
+        }
+    };
+    const registry = new InvocationRegistry({ get: query, cancel });
+    const control = async (method, params) => {
+        try {
+            await exchange(method, params);
+        }
+        catch (error) {
+            if (error instanceof KernelError &&
+                !["CONNECTION_CLOSED", "KERNEL_TIMEOUT"].includes(error.code))
+                throw error;
+            throw new KernelError("OPERATION_OUTCOME_UNKNOWN");
+        }
+    };
+    const client = {
+        topology: "kernel-ipc",
+        ownership: "attached",
+        invocations: registry,
+        invoke: createInputInvoke(async function* (input, environment = {}) {
+            if (closed)
+                throw new KernelError("CLIENT_CLOSED");
+            environment.signal?.throwIfAborted();
+            const request = identifyInvokeInput(input);
+            const record = registry.begin(lookupFor(request));
+            // signal 属于执行控制，不传给 subscribe：取消后仍须读到 Provider 会话更新与真实终态。
+            const abort = () => {
+                void registry.cancel(record, "caller_aborted").catch(() => undefined);
+            };
+            environment.signal?.addEventListener("abort", abort, { once: true });
+            try {
+                let ref;
+                try {
+                    ref = (await submit(request, environment, record)).ref;
+                    registry.accepted(record, ref);
+                }
+                catch (error) {
+                    registry.rejected(record, error);
+                    throw error;
+                }
+                // 终态会释放登记，但 yield 后的业务持久化/投递仍由消费者负责，owner 不能据此提前 close。
+                let terminal = false;
+                for await (const frame of client.subscribe(ref)) {
+                    terminal = isHostTerminal(frame);
+                    if (request.protocol_mode === "canonical" &&
+                        frame.kind === "control" &&
+                        frame.control.type === "error") {
+                        const snapshot = await query(ref, ref.kernel_instance_id).catch(() => undefined);
+                        if (snapshot?.terminal?.kind === "control" &&
+                            snapshot.terminal.control.type === "state" &&
+                            snapshot.terminal.control.state === "lost")
+                            throw new KernelError("RUN_OUTCOME_UNKNOWN");
+                    }
+                    yield frame;
+                    if (terminal &&
+                        frame.kind === "control" &&
+                        frame.control.type === "state" &&
+                        frame.control.state === "lost")
+                        throw new KernelError("RUN_OUTCOME_UNKNOWN");
+                }
+                if (!terminal)
+                    throw new KernelError("HOST_ENDED_WITHOUT_TERMINAL");
+                // 调用观察绑定首次控制结果；后续显式 Stop 成功不能抹去原来的 ACK 未知或失败。
+                if (record.firstCancelTask)
+                    await record.firstCancelTask;
+            }
+            catch (error) {
+                registry.interrupted(record, error);
+                throw error;
+            }
+            finally {
+                environment.signal?.removeEventListener("abort", abort);
+                registry.interrupted(record);
+            }
+        }),
+        cancelInvocation: async (id, reason) => registry.cancel(registry.active(id), reason, { explicit: true }),
+        respondInteraction: async (id, response) => client.respond(registry.ref(id), response),
+        respondNativeInteraction: async (id, response) => client.respondNative(registry.ref(id), response),
+        status: async () => {
+            const value = (await exchange("status"));
+            if (!value || typeof value !== "object" || typeof value.ipc_version !== "number")
+                throw new KernelError("INVALID_RESPONSE");
+            // 包版本不参与 wire 兼容判断；submit 复用此既有查询，拒绝后不会发起执行。
+            if (value.ipc_version !== 1)
+                throw new KernelError("KERNEL_IPC_VERSION_UNSUPPORTED");
+            try {
+                // 与服务端/doctor 共用快照白名单；仍保持客户端的受控错误与版本拒绝顺序。
+                assertKernelStatus(value);
+            }
+            catch {
+                throw new KernelError("INVALID_RESPONSE");
+            }
+            return value;
+        },
+        list: async () => (await exchange("adapter.list")),
+        get: query,
+        submit: (input, environment) => submit(input, environment),
+        async *subscribe(ref, afterSeq = 0, signal) {
+            // 断线仅续读同一实例、同一流的连续序号；不能把恢复观察变成再次执行 Provider。
+            let after = afterSeq;
+            let repair = 0;
+            let repairUntil;
+            while (true) {
+                signal?.throwIfAborted();
+                if (closed)
+                    throw new KernelError("CLIENT_CLOSED");
+                let socket;
+                let timer;
+                try {
+                    if (repairUntil !== undefined && Date.now() >= repairUntil)
+                        throw new KernelError("KERNEL_UNAVAILABLE");
+                    socket = await open(signal, repairUntil === undefined ? 5000 : Math.max(1, repairUntil - Date.now()));
+                    const current = socket;
+                    timer = setTimeout(() => current.destroy(new KernelError("KERNEL_TIMEOUT")), repairUntil === undefined ? 5000 : Math.max(1, Math.min(5000, repairUntil - Date.now())));
+                    const id = randomUUID();
+                    send(socket, id, "agent_run.subscribe", { ref, after_seq: after });
+                    let acknowledged = false;
+                    let terminalAt;
+                    for await (const value of lines(socket)) {
+                        if (!acknowledged) {
+                            const info = response(value, id);
+                            if (info.ref.kernel_instance_id !== ref.kernel_instance_id)
+                                throw new KernelError("KERNEL_INSTANCE_CHANGED");
+                            assertHostRunReceipt(receiptFor(info.ref));
+                            if (!sameLookup(info.ref, ref) ||
+                                info.ref.stream_id !== ref.stream_id ||
+                                info.ref.protocol !== ref.protocol)
+                                throw new KernelError("RUN_IDENTITY_MISMATCH");
+                            acknowledged = true;
+                            clearTimeout(timer);
+                            if (info.terminal) {
+                                assertHostFrame(info.terminal);
+                                assertHostFrameIdentity(info.terminal, receiptFor(ref));
+                                if (!isHostTerminal(info.terminal))
+                                    throw new KernelError("HOST_FRAME_INVALID");
+                                registry.reconcile(info.ref, info.terminal);
+                                terminalAt = info.latest_seq;
+                            }
+                            if (terminalAt !== undefined && after >= terminalAt)
+                                return;
+                            continue;
+                        }
+                        const notification = value;
+                        if (notification.method === "agent_run.stream_error")
+                            throw new KernelError(notification.params?.code ?? "STREAM_FAILED");
+                        if (notification.method !== "agent_run.event" ||
+                            notification.params?.kernel_instance_id !== ref.kernel_instance_id)
+                            throw new KernelError("HOST_FRAME_INVALID");
+                        const frame = notification.params.event;
+                        assertHostFrame(frame);
+                        assertHostFrameIdentity(frame, receiptFor(ref));
+                        if (frame.seq !== after + 1 || notification.params.seq !== frame.seq)
+                            throw new KernelError("STREAM_GAP");
+                        after = frame.seq;
+                        registry.observe(ref, frame);
+                        yield frame;
+                        if (isHostTerminal(frame))
+                            return;
+                    }
+                    throw new KernelError("CONNECTION_CLOSED");
+                }
+                catch (error) {
+                    if (closed)
+                        throw new KernelError("CLIENT_CLOSED");
+                    signal?.throwIfAborted();
+                    if (!(error instanceof KernelError) &&
+                        error instanceof Error &&
+                        "code" in error &&
+                        typeof error.code === "string")
+                        throw new KernelError(error.code);
+                    if (error instanceof KernelError &&
+                        !["CONNECTION_CLOSED", "KERNEL_UNAVAILABLE", "KERNEL_TIMEOUT"].includes(error.code))
+                        throw error;
+                    if (repair >= 3)
+                        throw new KernelError("KERNEL_UNAVAILABLE");
+                    repairUntil ??= Date.now() + 10_000;
+                    if (Date.now() >= repairUntil)
+                        throw new KernelError("KERNEL_UNAVAILABLE");
+                    await new Promise((resolve) => setTimeout(resolve, [100, 250, 500][repair++]));
+                }
+                finally {
+                    clearTimeout(timer);
+                    socket?.destroy();
+                }
+            }
+        },
+        cancel,
+        respond: (ref, response) => control("agent_run.respond", { ref, response }),
+        respondNative: (ref, response) => control("agent_run.native.respond", { ref, response }),
+        close() {
+            closed = true;
+            registry.close();
+            for (const socket of sockets)
+                socket.destroy();
+        }
+    };
+    async function submit(input, environment = {}, record) {
+        if (closed)
+            throw new KernelError("CLIENT_CLOSED");
+        environment.signal?.throwIfAborted();
+        if (environment.streamLimits !== undefined)
+            throw new KernelError("KERNEL_STREAM_LIMITS_UNSUPPORTED");
+        const request = identifyInvokeInput(input);
+        const requestLine = JSON.stringify({
+            jsonrpc: "2.0",
+            id: "0".repeat(36),
+            method: "agent_run.invoke",
+            params: { input: request, executionEnvOverrides: environment.executionEnvOverrides }
+        });
+        if (Buffer.byteLength(requestLine) + 1 > INVOKE_REQUEST_MAX_BYTES)
+            throw new KernelError("INVOKE_REQUEST_TOO_LARGE");
+        const instance = (await client.status()).kernel_instance_id;
+        environment.signal?.throwIfAborted();
+        if (record)
+            record.instance = instance;
+        let ref;
+        let submitted = false;
+        try {
+            const result = (await exchange("agent_run.invoke", {
+                input: request,
+                executionEnvOverrides: environment.executionEnvOverrides,
+                kernel_instance_id: instance
+            }, 30_000, 
+            // 请求发出后中断等待会让接纳结果不明；先取得/查询 ACK，再按原身份请求取消。
+            undefined, () => {
+                environment.signal?.throwIfAborted();
+                if (record)
+                    registry.assertSubmission();
+            }, () => {
+                submitted = true;
+                if (record)
+                    record.submitted = true;
+            }));
+            assertHostRunReceipt(result.receipt);
+            if (result.kernel_instance_id !== instance)
+                throw new KernelError("KERNEL_INSTANCE_CHANGED");
+            ref = { ...result.receipt, kernel_instance_id: result.kernel_instance_id };
+            if (!sameLookup(ref, lookupFor(request)))
+                throw new KernelError("RUN_IDENTITY_MISMATCH");
+        }
+        catch (error) {
+            if (!submitted)
+                throw error;
+            markSubmissionRejected(error, instance);
+            if (error instanceof KernelError &&
+                !["KERNEL_TIMEOUT", "CONNECTION_CLOSED"].includes(error.code))
+                throw error;
+            // ACK 丢失后只按原身份查询，不重新提交，避免创建第二次执行。
+            const key = lookupFor(request);
+            let recovered;
+            const until = Date.now() + 10_000;
+            for (const delay of [100, 250, 500]) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                if (Date.now() >= until)
+                    break;
+                try {
+                    recovered = (await query(key, instance, Math.min(until, Date.now() + 5000))).ref;
+                    break;
+                }
+                catch (queryError) {
+                    if (queryError instanceof KernelError &&
+                        ["KERNEL_INSTANCE_CHANGED", "RUN_IDENTITY_MISMATCH"].includes(queryError.code))
+                        throw queryError;
+                }
+            }
+            if (!recovered)
+                throw new KernelError("ACCEPTANCE_UNKNOWN");
+            ref = recovered;
+        }
+        if (!record && environment.signal?.aborted)
+            await client.cancel(ref, "caller_aborted");
+        return { ref };
+    }
+    return client;
+}
+function remaining(deadline) {
+    const timeout = deadline - Date.now();
+    if (timeout <= 0)
+        throw new KernelError("KERNEL_TIMEOUT");
+    return timeout;
+}
+function receiptFor(ref) {
+    const { kernel_instance_id: _instance, ...receipt } = ref;
+    void _instance;
+    return receipt;
+}
+function lookupForKey(key) {
+    return {
+        run_id: key.run_id,
+        invocation_id: key.invocation_id,
+        agent_session_id: key.agent_session_id,
+        session_generation: key.session_generation,
+        protocol_mode: key.protocol_mode
+    };
+}
+function sameLookup(left, right) {
+    return (left.run_id === right.run_id &&
+        left.invocation_id === right.invocation_id &&
+        left.agent_session_id === right.agent_session_id &&
+        left.session_generation === right.session_generation &&
+        left.protocol_mode === right.protocol_mode);
+}
+function lookupFor(input) {
+    return {
+        run_id: input.runId,
+        invocation_id: input.invocationId,
+        agent_session_id: input.sessionId,
+        session_generation: input.sessionGeneration ?? 0,
+        protocol_mode: input.protocol_mode ?? "native"
+    };
+}
+function send(socket, id, method, params) {
+    const line = `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
+    if (Buffer.byteLength(line) > INVOKE_REQUEST_MAX_BYTES)
+        throw new KernelError("INVOKE_REQUEST_TOO_LARGE");
+    socket.write(line);
+}
+function response(value, id) {
+    const reply = value;
+    if (reply.id !== id)
+        throw new KernelError("INVALID_RESPONSE");
+    if (reply.error)
+        throw new KernelError(typeof reply.error.data?.code === "string" ? reply.error.data.code : "KERNEL_REQUEST_FAILED", reply.error.data);
+    return reply.result;
+}
+async function* lines(socket) {
+    let pending = Buffer.alloc(0);
+    try {
+        for await (const chunk of socket) {
+            const bytes = chunk;
+            pending = pending.length ? Buffer.concat([pending, bytes]) : bytes;
+            let offset;
+            while ((offset = pending.indexOf(10)) >= 0) {
+                if (offset > HOST_RPC_MAX_LINE_BYTES)
+                    throw new KernelError("HOST_FRAME_TOO_LARGE");
+                const line = pending.subarray(0, offset);
+                pending = pending.subarray(offset + 1);
+                yield JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+            }
+            if (pending.length > HOST_RPC_MAX_LINE_BYTES)
+                throw new KernelError("HOST_FRAME_TOO_LARGE");
+        }
+        if (pending.length)
+            throw new KernelError("CONNECTION_CLOSED");
+    }
+    catch (error) {
+        if (error instanceof KernelError)
+            throw error;
+        if (error instanceof Error && /^[A-Z][A-Z0-9_]+$/.test(error.message))
+            throw new KernelError(error.message);
+        throw new KernelError("CONNECTION_CLOSED");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { attachKernel } from "./client.js";
+export * from "./types.js";
+export { AsyncQuestionReply, type AsyncQuestionReplyResult } from "./async-question-reply.js";
+export { isInvocationNotSubmitted } from "./submission-error.js";
+export { RuntimeHomeError, assertIpcEndpoint } from "./runtime-path.js";
+export type { InvokeInput, InvokeEnvironment, HostFrame, CanonicalEvent, InteractionResponse, NativeInteractionResponse, HostedAdapterMetadata } from "@mininglamp-oss/octo-runtime-protocol";

package/dist/index.js

@@ -0,0 +1,6 @@
+// 只连接宿主提供的服务；不拥有 Kernel、Adapter、Home 或业务状态。
+export { attachKernel } from "./client.js";
+export * from "./types.js";
+export { AsyncQuestionReply } from "./async-question-reply.js";
+export { isInvocationNotSubmitted } from "./submission-error.js";
+export { RuntimeHomeError, assertIpcEndpoint } from "./runtime-path.js";

package/dist/internal.d.ts

@@ -0,0 +1,4 @@
+export * from "./runtime-path.js";
+export * from "./invocation-lifecycle.js";
+export * from "./submission-error.js";
+export * from "./startup-diagnostics.js";

package/dist/internal.js

@@ -0,0 +1,5 @@
+// 仅供同版本完整 Runtime 装配；普通应用使用根入口与 /protocol。
+export * from "./runtime-path.js";
+export * from "./invocation-lifecycle.js";
+export * from "./submission-error.js";
+export * from "./startup-diagnostics.js";

package/dist/invocation-lifecycle.d.ts

@@ -0,0 +1,59 @@
+import { type HostFrame } from "@mininglamp-oss/octo-runtime-protocol";
+import { type KernelInvocationRecord, type KernelInvocationLifecycle, type KernelInvocationDrainResult, type LookupKey, type RunRef, type RunSnapshot } from "./types.js";
+export interface TrackedInvocation {
+    key: LookupKey;
+    ref?: RunRef;
+    instance?: string;
+    submitted: boolean;
+    phase: KernelInvocationRecord["phase"];
+    cancellation: KernelInvocationRecord["cancellation"];
+    lastSeq: number;
+    observationError?: string;
+    reason?: string;
+    cancelTask?: Promise<{
+        accepted: boolean;
+    }>;
+    /** 原 invoke 观察首次控制结果；新的显式 Stop 不得覆盖已经发生的控制失败。 */
+    firstCancelTask?: Promise<{
+        accepted: boolean;
+    }>;
+    admitted: Promise<void>;
+    settleAdmission(): void;
+    admissionError?: Error;
+}
+/**
+ * 每个 client 独立保存 invoke 的身份、取消和观察状态；执行与断线恢复由 client.ts 负责。
+ * 最多登记 128 项，不缓存正文；未知结果继续占用额度，不能通过删除记录伪造排空成功。
+ */
+export declare class InvocationRegistry implements KernelInvocationLifecycle {
+    #private;
+    private readonly transport;
+    constructor(transport: {
+        get(key: LookupKey, instance: string, deadline: number, signal: AbortSignal): Promise<RunSnapshot>;
+        cancel(ref: RunRef, reason: string, deadline: number, signal: AbortSignal): Promise<{
+            accepted: boolean;
+        }>;
+    });
+    begin(key: LookupKey): TrackedInvocation;
+    assertSubmission(): void;
+    accepted(record: TrackedInvocation, ref: RunRef, terminal?: HostFrame): void;
+    reconcile(ref: RunRef, terminal?: HostFrame): void;
+    rejected(record: TrackedInvocation, error: unknown): void;
+    observe(ref: RunRef, frame: HostFrame): void;
+    interrupted(record: TrackedInvocation, error?: unknown): void;
+    active(id: string): TrackedInvocation;
+    ref(id: string): RunRef;
+    cancel(record: TrackedInvocation, reason?: string, { explicit }?: {
+        explicit?: boolean;
+    }): Promise<{
+        accepted: boolean;
+    }>;
+    snapshot(): readonly KernelInvocationRecord[];
+    stopAdmission(): void;
+    close(): void;
+    drain(options: {
+        deadline: number;
+        reason: string;
+    }): Promise<KernelInvocationDrainResult>;
+}
+export declare function errorCode(error: unknown): string;