@xyit/wellspring 0.0.0-stage → 1.0.0

package/src/service/control.ts

@@ -0,0 +1,155 @@
+/*
+ * 服务进程控制：pid 文件 + 跨进程停止。
+ * 只有 wellspring start 会写服务记录；wellspring stop 读取后发送 SIGTERM。
+ */
+
+import { join } from "node:path"
+
+import { readJsonIfExists, removePath, statIfExists, writeJsonAtomic } from "../platform/file.ts"
+import { getPaths, type ResolvedPaths } from "../platform/path.ts"
+
+export interface ServiceRecord {
+    readonly version: 1
+    readonly pid: number
+    readonly startedAt: string
+    readonly cwd: string
+}
+
+export class ServiceNotRunningError extends Error {
+    constructor() {
+        super("没有正在运行的 Wellspring 服务")
+        this.name = "ServiceNotRunningError"
+    }
+}
+
+export class ServiceAlreadyRunningError extends Error {
+    readonly pid: number
+
+    constructor(pid: number) {
+        super(`Wellspring 服务已在运行（pid ${pid}）`)
+        this.name = "ServiceAlreadyRunningError"
+        this.pid = pid
+    }
+}
+
+export class ServiceStopTimeoutError extends Error {
+    readonly pid: number
+
+    constructor(pid: number) {
+        super(`等待服务退出超时（pid ${pid}）`)
+        this.name = "ServiceStopTimeoutError"
+        this.pid = pid
+    }
+}
+
+export function serviceRecordFile(paths: ResolvedPaths = getPaths()): string {
+    return join(paths.dataDir, "service.json")
+}
+
+export async function readServiceRecord(
+    paths: ResolvedPaths = getPaths(),
+): Promise<ServiceRecord | null> {
+    const value = await readJsonIfExists<Partial<ServiceRecord>>(serviceRecordFile(paths))
+    if (
+        value === null ||
+        typeof value.pid !== "number" ||
+        !Number.isInteger(value.pid) ||
+        value.pid <= 0
+    ) {
+        return null
+    }
+    return {
+        version: 1,
+        pid: value.pid,
+        startedAt: typeof value.startedAt === "string" ? value.startedAt : "",
+        cwd: typeof value.cwd === "string" ? value.cwd : "",
+    }
+}
+
+export async function writeServiceRecord(
+    record: Omit<ServiceRecord, "version">,
+    paths: ResolvedPaths = getPaths(),
+): Promise<void> {
+    await writeJsonAtomic(serviceRecordFile(paths), { version: 1, ...record })
+}
+
+/** 只清理属于指定 pid 的记录，避免误删后来的服务 */
+export async function clearServiceRecord(
+    pid: number,
+    paths: ResolvedPaths = getPaths(),
+): Promise<void> {
+    const current = await readServiceRecord(paths)
+    if (current !== null && current.pid !== pid) {
+        return
+    }
+    await removePath(serviceRecordFile(paths))
+}
+
+export function isProcessAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false
+        }
+        return true
+    }
+}
+
+export interface StopServiceOptions {
+    readonly timeoutMs?: number
+    readonly pollMs?: number
+}
+
+/** 停止当前服务：SIGTERM → 轮询等待退出 → 清理 pid 文件 */
+export async function stopService(
+    paths: ResolvedPaths = getPaths(),
+    options: StopServiceOptions = {},
+): Promise<number> {
+    const record = await readServiceRecord(paths)
+    if (record === null) {
+        throw new ServiceNotRunningError()
+    }
+    if (!isProcessAlive(record.pid)) {
+        await clearServiceRecord(record.pid, paths)
+        throw new ServiceNotRunningError()
+    }
+
+    try {
+        process.kill(record.pid, "SIGTERM")
+    } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            await clearServiceRecord(record.pid, paths)
+            throw new ServiceNotRunningError()
+        }
+        throw error
+    }
+
+    const timeoutMs = options.timeoutMs ?? 5_000
+    const pollMs = options.pollMs ?? 100
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollMs))
+        if (!isProcessAlive(record.pid)) {
+            await clearServiceRecord(record.pid, paths)
+            return record.pid
+        }
+    }
+    throw new ServiceStopTimeoutError(record.pid)
+}
+
+/** start 前检查：已有存活服务则报错，残留记录直接清掉 */
+export async function assertServiceStartable(paths: ResolvedPaths = getPaths()): Promise<void> {
+    const record = await readServiceRecord(paths)
+    if (record === null) {
+        return
+    }
+    if (isProcessAlive(record.pid)) {
+        throw new ServiceAlreadyRunningError(record.pid)
+    }
+    const shown = await statIfExists(serviceRecordFile(paths))
+    if (shown !== null) {
+        await clearServiceRecord(record.pid, paths)
+    }
+}

package/src/session/compress.ts

@@ -0,0 +1,47 @@
+/*
+ * 会话段编解码。
+ * 每轮一个 zstd frame：解压后是 JSONL 事件流，一行一个事件。
+ */
+
+import { zstdCompressSync, zstdDecompressSync } from "node:zlib"
+
+import type { SessionEvent } from "./types.ts"
+
+export function encodeEvents(events: readonly SessionEvent[]): Buffer {
+    const text = `${events.map((event) => JSON.stringify(event)).join("\n")}\n`
+    return zstdCompressSync(Buffer.from(text, "utf8"))
+}
+
+export function decodeEvents(data: Buffer): SessionEvent[] {
+    let text: string
+    try {
+        text = zstdDecompressSync(data).toString("utf8")
+    } catch (error) {
+        throw new Error("会话段解压失败", { cause: error })
+    }
+
+    const events: SessionEvent[] = []
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim()
+        if (trimmed === "") {
+            continue
+        }
+        let parsed: unknown
+        try {
+            parsed = JSON.parse(trimmed)
+        } catch (error) {
+            throw new Error("会话段包含无法解析的行", { cause: error })
+        }
+        if (
+            typeof parsed !== "object" ||
+            parsed === null ||
+            typeof (parsed as { type?: unknown }).type !== "string" ||
+            typeof (parsed as { seq?: unknown }).seq !== "number" ||
+            typeof (parsed as { time?: unknown }).time !== "number"
+        ) {
+            throw new Error("会话事件缺少 type/seq/time")
+        }
+        events.push(parsed as SessionEvent)
+    }
+    return events
+}

package/src/session/index.ts

@@ -0,0 +1,8 @@
+/*
+ * 会话层入口。
+ */
+
+export * from "./compress.ts"
+export * from "./replay.ts"
+export * from "./store.ts"
+export * from "./types.ts"

package/src/session/registry.ts

@@ -0,0 +1,17 @@
+// 活跃会话注册表
+
+import type { Session } from "./session.ts"
+
+const sessions = new Map<string, Session>()
+
+export function registerSession(session: Session): void {
+    sessions.set(session.id, session)
+}
+
+export function unregisterSession(id: string): void {
+    sessions.delete(id)
+}
+
+export function getSession(id: string): Session | null {
+    return sessions.get(id) ?? null
+}

package/src/session/replay.ts

@@ -0,0 +1,132 @@
+/*
+ * 会话回放：把事件流还原成对话轮次与 Chat Completions 消息。
+ */
+
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions"
+
+import type {
+    ContentPart,
+    SessionEvent,
+    SessionMessageRecord,
+    SessionMode,
+    SessionTurn,
+} from "./types.ts"
+
+export function contentText(parts: readonly ContentPart[] | undefined): string {
+    if (parts === undefined) {
+        return ""
+    }
+    let text = ""
+    for (const part of parts) {
+        if (part.type === "text") {
+            text += part.text
+        }
+    }
+    return text
+}
+
+function messageOf(event: SessionEvent): SessionMessageRecord | null {
+    const message = event.data["message"]
+    if (typeof message !== "object" || message === null) {
+        return null
+    }
+    return message as SessionMessageRecord
+}
+
+/** 按 turn/start 分组；没有 turn 边界的事件归到当前组 */
+export function groupTurns(events: readonly SessionEvent[]): SessionTurn[] {
+    const turns: SessionTurn[] = []
+    let current: SessionTurn | null = null
+
+    for (const event of events) {
+        if (event.type === "turn/start") {
+            const turn =
+                typeof event.data["turn"] === "number" ? event.data["turn"] : turns.length + 1
+            const mode =
+                event.data["mode"] === "run" ? "run" : event.data["mode"] === "chat" ? "chat" : null
+            current = { turn, mode, events: [] }
+            turns.push(current)
+        }
+        if (current === null) {
+            const turn = typeof event.data["turn"] === "number" ? event.data["turn"] : 1
+            const mode =
+                event.data["mode"] === "run" ? "run" : event.data["mode"] === "chat" ? "chat" : null
+            current = { turn, mode, events: [] }
+            turns.push(current)
+        }
+        current.events.push(event)
+    }
+    return turns
+}
+
+export function lastTurnNumber(events: readonly SessionEvent[]): number {
+    let max = 0
+    for (const event of events) {
+        const turn = event.data["turn"]
+        if (typeof turn === "number" && turn > max) {
+            max = turn
+        }
+    }
+    return max
+}
+
+export function lastSeq(events: readonly SessionEvent[]): number {
+    let max = -1
+    for (const event of events) {
+        if (event.seq > max) {
+            max = event.seq
+        }
+    }
+    return max
+}
+
+/** 历史事件 → 模型消息；保留 assistant tool_calls 与 tool 结果 */
+export function toChatMessages(events: readonly SessionEvent[]): ChatCompletionMessageParam[] {
+    const messages: ChatCompletionMessageParam[] = []
+    for (const event of events) {
+        if (event.type === "tool/result") {
+            const callId = event.data["callId"]
+            const content = event.data["content"]
+            if (typeof callId === "string" && typeof content === "string") {
+                messages.push({ role: "tool", tool_call_id: callId, content })
+            }
+            continue
+        }
+
+        const message = messageOf(event)
+        if (message === null) {
+            continue
+        }
+        const text = contentText(message.content)
+        if (event.type === "user/message" && message.role === "user") {
+            if (text !== "") {
+                messages.push({ role: "user", content: text })
+            }
+            continue
+        }
+        if (event.type === "assistant/message" && message.role === "assistant") {
+            const toolCalls = message.content.filter(
+                (part): part is Extract<ContentPart, { type: "tool-call" }> =>
+                    part.type === "tool-call",
+            )
+            if (toolCalls.length > 0) {
+                messages.push({
+                    role: "assistant",
+                    content: text === "" ? null : text,
+                    tool_calls: toolCalls.map((call) => ({
+                        id: call.id,
+                        type: "function" as const,
+                        function: { name: call.name, arguments: call.arguments },
+                    })),
+                })
+            } else if (text !== "") {
+                messages.push({ role: "assistant", content: text })
+            }
+        }
+    }
+    return messages
+}
+
+export function turnModeLabel(mode: SessionMode | null): string {
+    return mode === "run" ? "run" : "chat"
+}

package/src/session/session.ts

@@ -0,0 +1,134 @@
+// 会话门面：插件与宿主使用的 Session / SessionMessage
+
+import { randomUUID } from "node:crypto"
+
+import { emitOnMessage } from "../api/host/hooks.ts"
+import type { SessionStore, SessionData } from "./store.ts"
+import type { SessionMessageRecord } from "./types.ts"
+import { lastSeq, lastTurnNumber } from "./replay.ts"
+import { Workspace } from "../workspace/index.ts"
+
+export interface SessionMessageInput {
+    readonly sessionId: string
+    readonly content: string | readonly string[]
+    readonly type?: string
+}
+
+export class SessionMessage {
+    readonly sessionId: string
+    readonly content: string[]
+    readonly type: string
+
+    constructor(input: SessionMessageInput) {
+        this.sessionId = input.sessionId
+        this.content = typeof input.content === "string" ? [input.content] : [...input.content]
+        this.type = input.type ?? "message"
+    }
+}
+
+export class Session {
+    readonly id: string
+    readonly type: string
+    readonly metadata: Record<string, unknown>
+    readonly workspace: Workspace
+    readonly data: SessionData
+    readonly #store: SessionStore | null
+    readonly #queue: SessionMessage[] = []
+    #active = false
+    #stopRequested = false
+
+    constructor(data: SessionData, store: SessionStore | null = null) {
+        this.data = data
+        this.#store = store
+        this.id = data.meta.id
+        this.type = data.meta.type
+        this.metadata = data.meta.metadata
+        this.workspace = new Workspace(data.meta.workspace)
+    }
+
+    /** Agent 循环开始后，消息进入队列而不是直接落盘 */
+    begin(): void {
+        this.#active = true
+        this.#stopRequested = false
+    }
+
+    /** 请求停止本轮：循环在下一步之前收尾，不再调用模型 */
+    requestStop(): void {
+        this.#stopRequested = true
+    }
+
+    /** 本轮是否被要求停止 */
+    get stopRequested(): boolean {
+        return this.#stopRequested
+    }
+
+    end(): void {
+        this.#active = false
+    }
+
+    /** 是否有一轮正在跑；插话只在这个窗口内有效 */
+    get active(): boolean {
+        return this.#active
+    }
+
+    /** 取走运行期排队的消息 */
+    take(): SessionMessage[] {
+        return this.#queue.splice(0)
+    }
+
+    get events() {
+        return this.data.events
+    }
+
+    get turns() {
+        return this.data.turns
+    }
+
+    /** 发送消息并触发 onMessage */
+    async message(content: string | readonly string[], type = "message"): Promise<SessionMessage> {
+        const message = new SessionMessage({ sessionId: this.id, content, type })
+        await emitOnMessage({
+            sessionId: this.id,
+            mode: "chat",
+            turn: lastTurnNumber(this.data.events) + 1,
+            role: "user",
+            phase: "before",
+            content: message.content.join(""),
+            prompt: [],
+        })
+        if (this.#active || this.#store === null) {
+            this.#queue.push(message)
+            return message
+        }
+
+        const turn = lastTurnNumber(this.data.events) + 1
+        await this.#store.appendTurn(this.data, [
+            {
+                type: "user/message",
+                seq: lastSeq(this.data.events) + 1,
+                time: Date.now(),
+                data: {
+                    turn,
+                    message: {
+                        role: "user",
+                        content: [{ type: "text", text: message.content.join("") }],
+                        source: { kind: "plugin", type: message.type },
+                        id: randomUUID(),
+                    },
+                },
+            },
+        ])
+        return message
+    }
+
+    toJSON(): Record<string, unknown> {
+        return {
+            id: this.id,
+            type: this.type,
+            metadata: this.metadata,
+            workspace: this.workspace.root,
+        }
+    }
+}
+
+export type { SessionStore, SessionData, SessionMessageRecord }