@eggjs/agent-runtime 4.0.2-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/AgentRuntime.d.ts

@@ -0,0 +1,46 @@
+import { SSEWriter } from "./SSEWriter.js";
+import { AgentStore, AgentStreamMessage, CreateRunInput, RunObject, ThreadObject, ThreadObjectWithMessages } from "@eggjs/tegg-types/agent-runtime";
+import { EggLogger } from "egg-logger";
+
+//#region src/AgentRuntime.d.ts
+declare const AGENT_RUNTIME: unique symbol;
+/**
+* The executor interface — only requires execRun so the runtime can delegate
+* execution back through the controller's prototype chain (AOP/mock friendly).
+*/
+interface AgentExecutor {
+  execRun(input: CreateRunInput, signal?: AbortSignal): AsyncGenerator<AgentStreamMessage>;
+}
+interface AgentRuntimeOptions {
+  executor: AgentExecutor;
+  store: AgentStore;
+  logger: EggLogger;
+}
+declare class AgentRuntime {
+  private static readonly TERMINAL_RUN_STATUSES;
+  private store;
+  private runningTasks;
+  private executor;
+  private logger;
+  constructor(options: AgentRuntimeOptions);
+  createThread(): Promise<ThreadObject>;
+  getThread(threadId: string): Promise<ThreadObjectWithMessages>;
+  private ensureThread;
+  syncRun(input: CreateRunInput, signal?: AbortSignal): Promise<RunObject>;
+  asyncRun(input: CreateRunInput): Promise<RunObject>;
+  streamRun(input: CreateRunInput, writer: SSEWriter): Promise<void>;
+  /**
+  * Consume the execRun async generator, emitting SSE message.delta events
+  * for each chunk and accumulating content blocks and token usage.
+  */
+  private consumeStreamMessages;
+  getRun(runId: string): Promise<RunObject>;
+  cancelRun(runId: string): Promise<RunObject>;
+  /** Wait for all in-flight background tasks to complete naturally (without aborting). */
+  waitForPendingTasks(): Promise<void>;
+  destroy(): Promise<void>;
+  /** Factory method — avoids the spread-arg type issue with dynamic delegation. */
+  static create(options: AgentRuntimeOptions): AgentRuntime;
+}
+//#endregion
+export { AGENT_RUNTIME, AgentExecutor, AgentRuntime, AgentRuntimeOptions };

package/dist/AgentRuntime.js

@@ -0,0 +1,298 @@
+import { newMsgId } from "./AgentStoreUtils.js";
+import { MessageConverter } from "./MessageConverter.js";
+import { RunBuilder } from "./RunBuilder.js";
+import { AgentConflictError, AgentObjectType, AgentSSEEvent, RunStatus } from "@eggjs/tegg-types/agent-runtime";
+
+//#region src/AgentRuntime.ts
+const AGENT_RUNTIME = Symbol("agentRuntime");
+var AgentRuntime = class AgentRuntime {
+	static TERMINAL_RUN_STATUSES = new Set([
+		RunStatus.Completed,
+		RunStatus.Failed,
+		RunStatus.Cancelled,
+		RunStatus.Expired
+	]);
+	store;
+	runningTasks;
+	executor;
+	logger;
+	constructor(options) {
+		this.executor = options.executor;
+		this.store = options.store;
+		if (!options.logger) throw new Error("AgentRuntimeOptions.logger is required");
+		this.logger = options.logger;
+		this.runningTasks = /* @__PURE__ */ new Map();
+	}
+	async createThread() {
+		const thread = await this.store.createThread();
+		return {
+			id: thread.id,
+			object: AgentObjectType.Thread,
+			createdAt: thread.createdAt,
+			metadata: thread.metadata ?? {}
+		};
+	}
+	async getThread(threadId) {
+		const thread = await this.store.getThread(threadId);
+		return {
+			id: thread.id,
+			object: AgentObjectType.Thread,
+			createdAt: thread.createdAt,
+			metadata: thread.metadata ?? {},
+			messages: thread.messages
+		};
+	}
+	async ensureThread(input) {
+		if (input.threadId) return {
+			threadId: input.threadId,
+			input
+		};
+		const thread = await this.store.createThread();
+		return {
+			threadId: thread.id,
+			input: {
+				...input,
+				threadId: thread.id
+			}
+		};
+	}
+	async syncRun(input, signal) {
+		const { threadId, input: resolvedInput } = await this.ensureThread(input);
+		input = resolvedInput;
+		const run = await this.store.createRun(input.input.messages, threadId, input.config, input.metadata);
+		const rb = RunBuilder.create(run, threadId);
+		const abortController = new AbortController();
+		if (signal) if (signal.aborted) abortController.abort();
+		else signal.addEventListener("abort", () => abortController.abort(), { once: true });
+		let resolveTask;
+		const taskPromise = new Promise((r) => {
+			resolveTask = r;
+		});
+		this.runningTasks.set(run.id, {
+			promise: taskPromise,
+			abortController
+		});
+		try {
+			await this.store.updateRun(run.id, rb.start());
+			const streamMessages = [];
+			for await (const msg of this.executor.execRun(input, abortController.signal)) {
+				if (abortController.signal.aborted) {
+					const latest = await this.store.getRun(run.id);
+					return RunBuilder.fromRecord(latest).snapshot();
+				}
+				streamMessages.push(msg);
+			}
+			const { output, usage } = MessageConverter.extractFromStreamMessages(streamMessages, run.id);
+			await this.store.appendMessages(threadId, [...MessageConverter.toInputMessageObjects(input.input.messages, threadId), ...output]);
+			await this.store.updateRun(run.id, rb.complete(output, usage));
+			return rb.snapshot();
+		} catch (err) {
+			if (abortController.signal.aborted) {
+				const latest = await this.store.getRun(run.id);
+				return RunBuilder.fromRecord(latest).snapshot();
+			}
+			try {
+				await this.store.updateRun(run.id, rb.fail(err));
+			} catch (storeErr) {
+				this.logger.error("[AgentRuntime] failed to update run status after syncRun error:", storeErr);
+			}
+			throw err;
+		} finally {
+			resolveTask();
+			this.runningTasks.delete(run.id);
+		}
+	}
+	async asyncRun(input) {
+		const { threadId, input: resolvedInput } = await this.ensureThread(input);
+		input = resolvedInput;
+		const run = await this.store.createRun(input.input.messages, threadId, input.config, input.metadata);
+		const rb = RunBuilder.create(run, threadId);
+		const abortController = new AbortController();
+		const queuedSnapshot = rb.snapshot();
+		let resolveTask;
+		const taskPromise = new Promise((r) => {
+			resolveTask = r;
+		});
+		this.runningTasks.set(run.id, {
+			promise: taskPromise,
+			abortController
+		});
+		(async () => {
+			try {
+				await this.store.updateRun(run.id, rb.start());
+				const streamMessages = [];
+				for await (const msg of this.executor.execRun(input, abortController.signal)) {
+					if (abortController.signal.aborted) return;
+					streamMessages.push(msg);
+				}
+				const currentRun = await this.store.getRun(run.id);
+				if (currentRun.status === RunStatus.Cancelling || currentRun.status === RunStatus.Cancelled) return;
+				const { output, usage } = MessageConverter.extractFromStreamMessages(streamMessages, run.id);
+				await this.store.appendMessages(threadId, [...MessageConverter.toInputMessageObjects(input.input.messages, threadId), ...output]);
+				await this.store.updateRun(run.id, rb.complete(output, usage));
+			} catch (err) {
+				if (!abortController.signal.aborted) try {
+					const currentRun = await this.store.getRun(run.id);
+					if (currentRun.status !== RunStatus.Cancelling && currentRun.status !== RunStatus.Cancelled) await this.store.updateRun(run.id, rb.fail(err));
+				} catch (storeErr) {
+					this.logger.error("[AgentRuntime] failed to update run status after error:", storeErr);
+				}
+				else this.logger.error("[AgentRuntime] execRun error during abort:", err);
+			} finally {
+				resolveTask();
+				this.runningTasks.delete(run.id);
+			}
+		})();
+		return queuedSnapshot;
+	}
+	async streamRun(input, writer) {
+		const abortController = new AbortController();
+		writer.onClose(() => abortController.abort());
+		const { threadId, input: resolvedInput } = await this.ensureThread(input);
+		input = resolvedInput;
+		const run = await this.store.createRun(input.input.messages, threadId, input.config, input.metadata);
+		const rb = RunBuilder.create(run, threadId);
+		let resolveTask;
+		const taskPromise = new Promise((r) => {
+			resolveTask = r;
+		});
+		this.runningTasks.set(run.id, {
+			promise: taskPromise,
+			abortController
+		});
+		writer.writeEvent(AgentSSEEvent.ThreadRunCreated, rb.snapshot());
+		await this.store.updateRun(run.id, rb.start());
+		writer.writeEvent(AgentSSEEvent.ThreadRunInProgress, rb.snapshot());
+		const msgId = newMsgId();
+		const msgObj = MessageConverter.createStreamMessage(msgId, run.id);
+		writer.writeEvent(AgentSSEEvent.ThreadMessageCreated, msgObj);
+		try {
+			const { content, usage, aborted } = await this.consumeStreamMessages(input, abortController.signal, writer, msgId);
+			if (aborted) {
+				rb.cancelling();
+				try {
+					await this.store.updateRun(run.id, rb.cancel());
+				} catch (storeErr) {
+					this.logger.error("[AgentRuntime] failed to write cancelled status during stream abort:", storeErr);
+				}
+				if (!writer.closed) writer.writeEvent(AgentSSEEvent.ThreadRunCancelled, rb.snapshot());
+				return;
+			}
+			const completedMsg = MessageConverter.completeMessage(msgObj, content);
+			writer.writeEvent(AgentSSEEvent.ThreadMessageCompleted, completedMsg);
+			const output = content.length > 0 ? [completedMsg] : [];
+			await this.store.appendMessages(threadId, [...MessageConverter.toInputMessageObjects(input.input.messages, threadId), ...output]);
+			await this.store.updateRun(run.id, rb.complete(output, usage));
+			writer.writeEvent(AgentSSEEvent.ThreadRunCompleted, rb.snapshot());
+		} catch (err) {
+			if (abortController.signal.aborted) {
+				rb.cancelling();
+				try {
+					await this.store.updateRun(run.id, rb.cancel());
+				} catch (storeErr) {
+					this.logger.error("[AgentRuntime] failed to write cancelled status during stream error:", storeErr);
+				}
+				if (!writer.closed) writer.writeEvent(AgentSSEEvent.ThreadRunCancelled, rb.snapshot());
+			} else {
+				try {
+					await this.store.updateRun(run.id, rb.fail(err));
+				} catch (storeErr) {
+					this.logger.error("[AgentRuntime] failed to update run status after error:", storeErr);
+				}
+				if (!writer.closed) writer.writeEvent(AgentSSEEvent.ThreadRunFailed, rb.snapshot());
+			}
+		} finally {
+			resolveTask();
+			this.runningTasks.delete(run.id);
+			if (!writer.closed) {
+				writer.writeEvent(AgentSSEEvent.Done, "[DONE]");
+				writer.end();
+			}
+		}
+	}
+	/**
+	* Consume the execRun async generator, emitting SSE message.delta events
+	* for each chunk and accumulating content blocks and token usage.
+	*/
+	async consumeStreamMessages(input, signal, writer, msgId) {
+		const content = [];
+		let promptTokens = 0;
+		let completionTokens = 0;
+		let hasUsage = false;
+		for await (const msg of this.executor.execRun(input, signal)) {
+			if (signal.aborted) return {
+				content,
+				usage: void 0,
+				aborted: true
+			};
+			if (msg.message) {
+				const contentBlocks = MessageConverter.toContentBlocks(msg.message);
+				content.push(...contentBlocks);
+				const delta = {
+					id: msgId,
+					object: AgentObjectType.ThreadMessageDelta,
+					delta: { content: contentBlocks }
+				};
+				writer.writeEvent(AgentSSEEvent.ThreadMessageDelta, delta);
+			}
+			if (msg.usage) {
+				hasUsage = true;
+				promptTokens += msg.usage.promptTokens ?? 0;
+				completionTokens += msg.usage.completionTokens ?? 0;
+			}
+		}
+		return {
+			content,
+			usage: hasUsage ? {
+				promptTokens,
+				completionTokens,
+				totalTokens: promptTokens + completionTokens
+			} : void 0,
+			aborted: false
+		};
+	}
+	async getRun(runId) {
+		const run = await this.store.getRun(runId);
+		return RunBuilder.fromRecord(run).snapshot();
+	}
+	async cancelRun(runId) {
+		const run = await this.store.getRun(runId);
+		if (AgentRuntime.TERMINAL_RUN_STATUSES.has(run.status)) throw new AgentConflictError(`Cannot cancel run with status '${run.status}'`);
+		const rb = RunBuilder.fromRecord(run);
+		await this.store.updateRun(runId, rb.cancelling());
+		const task = this.runningTasks.get(runId);
+		if (task) {
+			task.abortController.abort();
+			await task.promise.catch(() => {});
+		}
+		const freshRun = await this.store.getRun(runId);
+		if (AgentRuntime.TERMINAL_RUN_STATUSES.has(freshRun.status)) return RunBuilder.fromRecord(freshRun).snapshot();
+		try {
+			await this.store.updateRun(runId, rb.cancel());
+		} catch (err) {
+			this.logger.error("[AgentRuntime] failed to write cancelled state after cancelling:", err);
+			const fallback = await this.store.getRun(runId);
+			return RunBuilder.fromRecord(fallback).snapshot();
+		}
+		return rb.snapshot();
+	}
+	/** Wait for all in-flight background tasks to complete naturally (without aborting). */
+	async waitForPendingTasks() {
+		if (this.runningTasks.size) {
+			const pending = Array.from(this.runningTasks.values()).map((t) => t.promise);
+			await Promise.allSettled(pending);
+		}
+	}
+	async destroy() {
+		for (const task of this.runningTasks.values()) task.abortController.abort();
+		await this.waitForPendingTasks();
+		if (this.store.destroy) await this.store.destroy();
+	}
+	/** Factory method — avoids the spread-arg type issue with dynamic delegation. */
+	static create(options) {
+		return new AgentRuntime(options);
+	}
+};
+
+//#endregion
+export { AGENT_RUNTIME, AgentRuntime };

package/dist/AgentStoreUtils.d.ts

@@ -0,0 +1,7 @@
+//#region src/AgentStoreUtils.d.ts
+declare function nowUnix(): number;
+declare function newMsgId(): string;
+declare function newThreadId(): string;
+declare function newRunId(): string;
+//#endregion
+export { newMsgId, newRunId, newThreadId, nowUnix };

package/dist/AgentStoreUtils.js

@@ -0,0 +1,18 @@
+import crypto from "node:crypto";
+
+//#region src/AgentStoreUtils.ts
+function nowUnix() {
+	return Math.floor(Date.now() / 1e3);
+}
+function newMsgId() {
+	return `msg_${crypto.randomUUID()}`;
+}
+function newThreadId() {
+	return `thread_${crypto.randomUUID()}`;
+}
+function newRunId() {
+	return `run_${crypto.randomUUID()}`;
+}
+
+//#endregion
+export { newMsgId, newRunId, newThreadId, nowUnix };

package/dist/HttpSSEWriter.d.ts

@@ -0,0 +1,20 @@
+import { SSEWriter } from "./SSEWriter.js";
+import { ServerResponse } from "node:http";
+
+//#region src/HttpSSEWriter.d.ts
+declare class HttpSSEWriter implements SSEWriter {
+  private res;
+  private _closed;
+  private closeCallbacks;
+  private headersSent;
+  private readonly onResClose;
+  constructor(res: ServerResponse);
+  /** Lazily write headers on first event — avoids sending corrupt headers if constructor throws. */
+  private ensureHeaders;
+  writeEvent(event: string, data: unknown): void;
+  get closed(): boolean;
+  end(): void;
+  onClose(callback: () => void): void;
+}
+//#endregion
+export { HttpSSEWriter };

package/dist/HttpSSEWriter.js

@@ -0,0 +1,49 @@
+//#region src/HttpSSEWriter.ts
+var HttpSSEWriter = class {
+	res;
+	_closed = false;
+	closeCallbacks = [];
+	headersSent = false;
+	onResClose;
+	constructor(res) {
+		this.res = res;
+		this.onResClose = () => {
+			this._closed = true;
+			for (const cb of this.closeCallbacks) cb();
+			this.closeCallbacks.length = 0;
+		};
+		res.on("close", this.onResClose);
+	}
+	/** Lazily write headers on first event — avoids sending corrupt headers if constructor throws. */
+	ensureHeaders() {
+		if (this.headersSent) return;
+		this.headersSent = true;
+		this.res.writeHead(200, {
+			"content-type": "text/event-stream",
+			"cache-control": "no-cache",
+			connection: "keep-alive"
+		});
+	}
+	writeEvent(event, data) {
+		if (this._closed) return;
+		this.ensureHeaders();
+		this.res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+	}
+	get closed() {
+		return this._closed;
+	}
+	end() {
+		if (!this._closed) {
+			this._closed = true;
+			this.res.off("close", this.onResClose);
+			this.closeCallbacks.length = 0;
+			this.res.end();
+		}
+	}
+	onClose(callback) {
+		this.closeCallbacks.push(callback);
+	}
+};
+
+//#endregion
+export { HttpSSEWriter };

package/dist/MessageConverter.d.ts

@@ -0,0 +1,36 @@
+import { RunUsage } from "./RunBuilder.js";
+import { AgentStreamMessage, AgentStreamMessagePayload, CreateRunInput, MessageContentBlock, MessageObject } from "@eggjs/tegg-types/agent-runtime";
+
+//#region src/MessageConverter.d.ts
+declare class MessageConverter {
+  /**
+  * Convert an AgentStreamMessage's message payload into OpenAI MessageContentBlock[].
+  */
+  static toContentBlocks(msg: AgentStreamMessagePayload): MessageContentBlock[];
+  /**
+  * Build a completed MessageObject from an AgentStreamMessage payload.
+  */
+  static toMessageObject(msg: AgentStreamMessagePayload, runId?: string): MessageObject;
+  /**
+  * Extract MessageObjects and accumulated usage from AgentStreamMessage objects.
+  */
+  static extractFromStreamMessages(messages: AgentStreamMessage[], runId?: string): {
+    output: MessageObject[];
+    usage?: RunUsage;
+  };
+  /**
+  * Produce a completed copy of a streaming MessageObject with final content.
+  */
+  static completeMessage(msg: MessageObject, content: MessageContentBlock[]): MessageObject;
+  /**
+  * Create an in-progress MessageObject for streaming (before content is known).
+  */
+  static createStreamMessage(msgId: string, runId: string): MessageObject;
+  /**
+  * Convert input messages to MessageObjects for thread history.
+  * System messages are filtered out — they are transient instructions, not conversation history.
+  */
+  static toInputMessageObjects(messages: CreateRunInput["input"]["messages"], threadId?: string): MessageObject[];
+}
+//#endregion
+export { MessageConverter };

package/dist/MessageConverter.js

@@ -0,0 +1,123 @@
+import { newMsgId, nowUnix } from "./AgentStoreUtils.js";
+import { AgentObjectType, ContentBlockType, MessageRole, MessageStatus } from "@eggjs/tegg-types/agent-runtime";
+
+//#region src/MessageConverter.ts
+var MessageConverter = class MessageConverter {
+	/**
+	* Convert an AgentStreamMessage's message payload into OpenAI MessageContentBlock[].
+	*/
+	static toContentBlocks(msg) {
+		if (!msg) return [];
+		const content = msg.content;
+		if (typeof content === "string") return [{
+			type: ContentBlockType.Text,
+			text: {
+				value: content,
+				annotations: []
+			}
+		}];
+		if (Array.isArray(content)) return content.filter((part) => part.type === ContentBlockType.Text).map((part) => ({
+			type: ContentBlockType.Text,
+			text: {
+				value: part.text,
+				annotations: []
+			}
+		}));
+		return [];
+	}
+	/**
+	* Build a completed MessageObject from an AgentStreamMessage payload.
+	*/
+	static toMessageObject(msg, runId) {
+		return {
+			id: newMsgId(),
+			object: AgentObjectType.ThreadMessage,
+			createdAt: nowUnix(),
+			runId,
+			role: MessageRole.Assistant,
+			status: MessageStatus.Completed,
+			content: MessageConverter.toContentBlocks(msg)
+		};
+	}
+	/**
+	* Extract MessageObjects and accumulated usage from AgentStreamMessage objects.
+	*/
+	static extractFromStreamMessages(messages, runId) {
+		const output = [];
+		let promptTokens = 0;
+		let completionTokens = 0;
+		let hasUsage = false;
+		for (const msg of messages) {
+			if (msg.message) output.push(MessageConverter.toMessageObject(msg.message, runId));
+			if (msg.usage) {
+				hasUsage = true;
+				promptTokens += msg.usage.promptTokens ?? 0;
+				completionTokens += msg.usage.completionTokens ?? 0;
+			}
+		}
+		let usage;
+		if (hasUsage) usage = {
+			promptTokens,
+			completionTokens,
+			totalTokens: promptTokens + completionTokens
+		};
+		return {
+			output,
+			usage
+		};
+	}
+	/**
+	* Produce a completed copy of a streaming MessageObject with final content.
+	*/
+	static completeMessage(msg, content) {
+		return {
+			...msg,
+			status: MessageStatus.Completed,
+			content
+		};
+	}
+	/**
+	* Create an in-progress MessageObject for streaming (before content is known).
+	*/
+	static createStreamMessage(msgId, runId) {
+		return {
+			id: msgId,
+			object: AgentObjectType.ThreadMessage,
+			createdAt: nowUnix(),
+			runId,
+			role: MessageRole.Assistant,
+			status: MessageStatus.InProgress,
+			content: []
+		};
+	}
+	/**
+	* Convert input messages to MessageObjects for thread history.
+	* System messages are filtered out — they are transient instructions, not conversation history.
+	*/
+	static toInputMessageObjects(messages, threadId) {
+		return messages.filter((m) => m.role !== MessageRole.System).map((m) => ({
+			id: newMsgId(),
+			object: AgentObjectType.ThreadMessage,
+			createdAt: nowUnix(),
+			threadId,
+			role: m.role,
+			status: MessageStatus.Completed,
+			content: typeof m.content === "string" ? [{
+				type: ContentBlockType.Text,
+				text: {
+					value: m.content,
+					annotations: []
+				}
+			}] : m.content.map((p) => ({
+				type: ContentBlockType.Text,
+				text: {
+					value: p.text,
+					annotations: []
+				}
+			}))
+		}));
+	}
+};
+
+//#endregion
+export { MessageConverter };

package/dist/OSSAgentStore.d.ts

@@ -0,0 +1,66 @@
+import { AgentRunConfig, AgentStore, InputMessage, MessageObject, ObjectStorageClient, RunRecord, ThreadRecord } from "@eggjs/tegg-types/agent-runtime";
+
+//#region src/OSSAgentStore.d.ts
+interface OSSAgentStoreOptions {
+  client: ObjectStorageClient;
+  prefix?: string;
+}
+/**
+* AgentStore implementation backed by an ObjectStorageClient (OSS, S3, etc.).
+*
+* ## Storage layout
+*
+* ```
+* {prefix}threads/{id}/meta.json      — Thread metadata (JSON)
+* {prefix}threads/{id}/messages.jsonl  — Messages (JSONL, one JSON object per line)
+* {prefix}runs/{id}.json              — Run record (JSON)
+* ```
+*
+* ### Why split threads into two keys?
+*
+* Thread messages are append-only: new messages are added at the end but never
+* modified or deleted. Storing them as a JSONL file allows us to leverage the
+* OSS AppendObject API (or similar) to write new messages without reading the
+* entire thread first. This is much more efficient than read-modify-write for
+* long conversations.
+*
+* If the underlying ObjectStorageClient provides an `append()` method, it will
+* be used for O(1) message writes. Otherwise, the store falls back to
+* get-concat-put (which is NOT atomic and may lose data under concurrent
+* writers — acceptable for single-writer scenarios).
+*
+* ### Atomicity note
+*
+* Run updates still use read-modify-write because run fields are mutated
+* (status, timestamps, output, etc.) — they cannot be modelled as append-only.
+* For multi-writer safety, consider a database-backed AgentStore or ETag-based
+* conditional writes with retry.
+*/
+declare class OSSAgentStore implements AgentStore {
+  private readonly client;
+  private readonly prefix;
+  constructor(options: OSSAgentStoreOptions);
+  /** Key for thread metadata (JSON). */
+  private threadMetaKey;
+  /** Key for thread messages (JSONL, one message per line). */
+  private threadMessagesKey;
+  /** Key for run record (JSON). */
+  private runKey;
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  createThread(metadata?: Record<string, unknown>): Promise<ThreadRecord>;
+  getThread(threadId: string): Promise<ThreadRecord>;
+  /**
+  * Append messages to a thread.
+  *
+  * Each message is serialized as a single JSON line (JSONL format).
+  * When the underlying client supports `append()`, this is a single
+  * O(1) write — no need to read the existing messages first.
+  */
+  appendMessages(threadId: string, messages: MessageObject[]): Promise<void>;
+  createRun(input: InputMessage[], threadId?: string, config?: AgentRunConfig, metadata?: Record<string, unknown>): Promise<RunRecord>;
+  getRun(runId: string): Promise<RunRecord>;
+  updateRun(runId: string, updates: Partial<RunRecord>): Promise<void>;
+}
+//#endregion
+export { OSSAgentStore, OSSAgentStoreOptions };

package/dist/OSSAgentStore.js

@@ -0,0 +1,133 @@
+import { newRunId, newThreadId, nowUnix } from "./AgentStoreUtils.js";
+import { AgentNotFoundError, AgentObjectType, RunStatus } from "@eggjs/tegg-types/agent-runtime";
+
+//#region src/OSSAgentStore.ts
+/**
+* AgentStore implementation backed by an ObjectStorageClient (OSS, S3, etc.).
+*
+* ## Storage layout
+*
+* ```
+* {prefix}threads/{id}/meta.json      — Thread metadata (JSON)
+* {prefix}threads/{id}/messages.jsonl  — Messages (JSONL, one JSON object per line)
+* {prefix}runs/{id}.json              — Run record (JSON)
+* ```
+*
+* ### Why split threads into two keys?
+*
+* Thread messages are append-only: new messages are added at the end but never
+* modified or deleted. Storing them as a JSONL file allows us to leverage the
+* OSS AppendObject API (or similar) to write new messages without reading the
+* entire thread first. This is much more efficient than read-modify-write for
+* long conversations.
+*
+* If the underlying ObjectStorageClient provides an `append()` method, it will
+* be used for O(1) message writes. Otherwise, the store falls back to
+* get-concat-put (which is NOT atomic and may lose data under concurrent
+* writers — acceptable for single-writer scenarios).
+*
+* ### Atomicity note
+*
+* Run updates still use read-modify-write because run fields are mutated
+* (status, timestamps, output, etc.) — they cannot be modelled as append-only.
+* For multi-writer safety, consider a database-backed AgentStore or ETag-based
+* conditional writes with retry.
+*/
+var OSSAgentStore = class {
+	client;
+	prefix;
+	constructor(options) {
+		this.client = options.client;
+		const raw = options.prefix ?? "";
+		this.prefix = raw && !raw.endsWith("/") ? raw + "/" : raw;
+	}
+	/** Key for thread metadata (JSON). */
+	threadMetaKey(threadId) {
+		return `${this.prefix}threads/${threadId}/meta.json`;
+	}
+	/** Key for thread messages (JSONL, one message per line). */
+	threadMessagesKey(threadId) {
+		return `${this.prefix}threads/${threadId}/messages.jsonl`;
+	}
+	/** Key for run record (JSON). */
+	runKey(runId) {
+		return `${this.prefix}runs/${runId}.json`;
+	}
+	async init() {
+		await this.client.init?.();
+	}
+	async destroy() {
+		await this.client.destroy?.();
+	}
+	async createThread(metadata) {
+		const threadId = newThreadId();
+		const meta = {
+			id: threadId,
+			object: AgentObjectType.Thread,
+			metadata: metadata ?? {},
+			createdAt: nowUnix()
+		};
+		await this.client.put(this.threadMetaKey(threadId), JSON.stringify(meta));
+		return {
+			...meta,
+			messages: []
+		};
+	}
+	async getThread(threadId) {
+		const [metaData, messagesData] = await Promise.all([this.client.get(this.threadMetaKey(threadId)), this.client.get(this.threadMessagesKey(threadId))]);
+		if (!metaData) throw new AgentNotFoundError(`Thread ${threadId} not found`);
+		const meta = JSON.parse(metaData);
+		const messages = messagesData ? messagesData.trim().split("\n").filter((line) => line.length > 0).map((line) => JSON.parse(line)) : [];
+		return {
+			...meta,
+			messages
+		};
+	}
+	/**
+	* Append messages to a thread.
+	*
+	* Each message is serialized as a single JSON line (JSONL format).
+	* When the underlying client supports `append()`, this is a single
+	* O(1) write — no need to read the existing messages first.
+	*/
+	async appendMessages(threadId, messages) {
+		if (!await this.client.get(this.threadMetaKey(threadId))) throw new AgentNotFoundError(`Thread ${threadId} not found`);
+		if (messages.length === 0) return;
+		const lines = messages.map((m) => JSON.stringify(m)).join("\n") + "\n";
+		const messagesKey = this.threadMessagesKey(threadId);
+		if (this.client.append) await this.client.append(messagesKey, lines);
+		else {
+			const existing = await this.client.get(messagesKey) ?? "";
+			await this.client.put(messagesKey, existing + lines);
+		}
+	}
+	async createRun(input, threadId, config, metadata) {
+		const runId = newRunId();
+		const record = {
+			id: runId,
+			object: AgentObjectType.ThreadRun,
+			threadId,
+			status: RunStatus.Queued,
+			input,
+			config,
+			metadata,
+			createdAt: nowUnix()
+		};
+		await this.client.put(this.runKey(runId), JSON.stringify(record));
+		return record;
+	}
+	async getRun(runId) {
+		const data = await this.client.get(this.runKey(runId));
+		if (!data) throw new AgentNotFoundError(`Run ${runId} not found`);
+		return JSON.parse(data);
+	}
+	async updateRun(runId, updates) {
+		const run = await this.getRun(runId);
+		const { id: _, object: __, ...safeUpdates } = updates;
+		Object.assign(run, safeUpdates);
+		await this.client.put(this.runKey(runId), JSON.stringify(run));
+	}
+};
+
+//#endregion
+export { OSSAgentStore };

package/dist/OSSObjectStorageClient.d.ts

@@ -0,0 +1,51 @@
+import { ObjectStorageClient } from "@eggjs/tegg-types/agent-runtime";
+import { OSSObject } from "oss-client";
+
+//#region src/OSSObjectStorageClient.d.ts
+
+/**
+* ObjectStorageClient backed by Alibaba Cloud OSS (via oss-client).
+*
+* Supports both `put`/`get` for normal objects and `append` for
+* OSS Appendable Objects. The append path uses a local position cache
+* to avoid extra HEAD requests; on position mismatch it falls back to
+* HEAD + retry automatically.
+*
+* The OSSObject instance should be constructed and injected by the caller,
+* following the IoC/DI principle.
+*/
+declare class OSSObjectStorageClient implements ObjectStorageClient {
+  private readonly client;
+  /**
+  * In-memory cache of next-append positions.
+  *
+  * After each successful `append()`, OSS returns `nextAppendPosition`.
+  * We cache it here so the next append can skip a HEAD round-trip.
+  * If the cached position is stale (e.g., process restarted or another
+  * writer appended), the append will fail with PositionNotEqualToLength
+  * and we fall back to HEAD + retry.
+  */
+  private readonly appendPositions;
+  constructor(client: OSSObject);
+  put(key: string, value: string): Promise<void>;
+  get(key: string): Promise<string | null>;
+  /**
+  * Append data to an OSS Appendable Object.
+  *
+  * OSS AppendObject requires a `position` parameter that must equal the
+  * current object size. We use a three-step strategy:
+  *
+  * 1. Use the cached position (0 for new objects, or the value from the
+  *    last successful append).
+  * 2. If OSS returns PositionNotEqualToLength (cache is stale), issue a
+  *    HEAD request to learn the current object size, then retry once.
+  * 3. Update the cache with `nextAppendPosition` from the response.
+  *
+  * This gives us single-round-trip performance in the common case (single
+  * writer, no restarts) while still being self-healing when the cache is
+  * stale.
+  */
+  append(key: string, value: string): Promise<void>;
+}
+//#endregion
+export { OSSObjectStorageClient };

package/dist/OSSObjectStorageClient.js

@@ -0,0 +1,78 @@
+//#region src/OSSObjectStorageClient.ts
+function isOSSError(err, code) {
+	return err != null && typeof err === "object" && "code" in err && err.code === code;
+}
+/**
+* ObjectStorageClient backed by Alibaba Cloud OSS (via oss-client).
+*
+* Supports both `put`/`get` for normal objects and `append` for
+* OSS Appendable Objects. The append path uses a local position cache
+* to avoid extra HEAD requests; on position mismatch it falls back to
+* HEAD + retry automatically.
+*
+* The OSSObject instance should be constructed and injected by the caller,
+* following the IoC/DI principle.
+*/
+var OSSObjectStorageClient = class {
+	client;
+	/**
+	* In-memory cache of next-append positions.
+	*
+	* After each successful `append()`, OSS returns `nextAppendPosition`.
+	* We cache it here so the next append can skip a HEAD round-trip.
+	* If the cached position is stale (e.g., process restarted or another
+	* writer appended), the append will fail with PositionNotEqualToLength
+	* and we fall back to HEAD + retry.
+	*/
+	appendPositions = /* @__PURE__ */ new Map();
+	constructor(client) {
+		this.client = client;
+	}
+	async put(key, value) {
+		await this.client.put(key, Buffer.from(value, "utf-8"));
+	}
+	async get(key) {
+		try {
+			const result = await this.client.get(key);
+			if (result.content) return Buffer.isBuffer(result.content) ? result.content.toString("utf-8") : String(result.content);
+			return null;
+		} catch (err) {
+			if (isOSSError(err, "NoSuchKey")) return null;
+			throw err;
+		}
+	}
+	/**
+	* Append data to an OSS Appendable Object.
+	*
+	* OSS AppendObject requires a `position` parameter that must equal the
+	* current object size. We use a three-step strategy:
+	*
+	* 1. Use the cached position (0 for new objects, or the value from the
+	*    last successful append).
+	* 2. If OSS returns PositionNotEqualToLength (cache is stale), issue a
+	*    HEAD request to learn the current object size, then retry once.
+	* 3. Update the cache with `nextAppendPosition` from the response.
+	*
+	* This gives us single-round-trip performance in the common case (single
+	* writer, no restarts) while still being self-healing when the cache is
+	* stale.
+	*/
+	async append(key, value) {
+		const buf = Buffer.from(value, "utf-8");
+		const position = this.appendPositions.get(key) ?? 0;
+		try {
+			const result = await this.client.append(key, buf, { position });
+			this.appendPositions.set(key, Number(result.nextAppendPosition));
+		} catch (err) {
+			if (isOSSError(err, "PositionNotEqualToLength")) {
+				const head = await this.client.head(key);
+				const currentPos = Number(head.res.headers["content-length"] ?? 0);
+				const result = await this.client.append(key, buf, { position: currentPos });
+				this.appendPositions.set(key, Number(result.nextAppendPosition));
+			} else throw err;
+		}
+	}
+};
+
+//#endregion
+export { OSSObjectStorageClient };

package/dist/RunBuilder.d.ts

@@ -0,0 +1,47 @@
+import { MessageObject, RunObject, RunRecord } from "@eggjs/tegg-types/agent-runtime";
+
+//#region src/RunBuilder.d.ts
+/** Accumulated token usage — same shape as non-null RunRecord['usage']. */
+type RunUsage = NonNullable<RunRecord["usage"]>;
+/**
+* Encapsulates run state transitions.
+*
+* Mutation methods (`start`, `complete`, `fail`, `cancel`) update internal
+* state and return `Partial<RunRecord>` for the store.
+*
+* `snapshot()` produces a `RunObject` suitable for API responses and SSE events.
+*/
+declare class RunBuilder {
+  private readonly id;
+  private readonly threadId;
+  private readonly createdAt;
+  private readonly metadata?;
+  private readonly config?;
+  private status;
+  private startedAt?;
+  private completedAt?;
+  private cancelledAt?;
+  private failedAt?;
+  private lastError?;
+  private usage?;
+  private output?;
+  private constructor();
+  /** Create a RunBuilder from a store RunRecord, using its own threadId. */
+  static fromRecord(run: RunRecord): RunBuilder;
+  /** Create a RunBuilder from a store RunRecord, restoring all mutable state. */
+  static create(run: RunRecord, threadId: string): RunBuilder;
+  /** queued -> in_progress. Returns store update. */
+  start(): Partial<RunRecord>;
+  /** in_progress -> completed. Returns store update. */
+  complete(output: MessageObject[], usage?: RunUsage): Partial<RunRecord>;
+  /** queued/in_progress -> failed. Returns store update. */
+  fail(error: Error): Partial<RunRecord>;
+  /** in_progress/queued -> cancelling (idempotent if already cancelling). Returns store update. */
+  cancelling(): Partial<RunRecord>;
+  /** cancelling -> cancelled. Returns store update. */
+  cancel(): Partial<RunRecord>;
+  /** Produce a RunObject snapshot for API / SSE. */
+  snapshot(): RunObject;
+}
+//#endregion
+export { RunBuilder, RunUsage };

package/dist/RunBuilder.js

@@ -0,0 +1,129 @@
+import { nowUnix } from "./AgentStoreUtils.js";
+import { AgentErrorCode, AgentObjectType, InvalidRunStateTransitionError, RunStatus } from "@eggjs/tegg-types/agent-runtime";
+
+//#region src/RunBuilder.ts
+/**
+* Encapsulates run state transitions.
+*
+* Mutation methods (`start`, `complete`, `fail`, `cancel`) update internal
+* state and return `Partial<RunRecord>` for the store.
+*
+* `snapshot()` produces a `RunObject` suitable for API responses and SSE events.
+*/
+var RunBuilder = class RunBuilder {
+	id;
+	threadId;
+	createdAt;
+	metadata;
+	config;
+	status;
+	startedAt;
+	completedAt;
+	cancelledAt;
+	failedAt;
+	lastError;
+	usage;
+	output;
+	constructor(id, threadId, createdAt, status, metadata, config) {
+		this.id = id;
+		this.threadId = threadId;
+		this.createdAt = createdAt;
+		this.status = status;
+		this.metadata = metadata;
+		this.config = config;
+	}
+	/** Create a RunBuilder from a store RunRecord, using its own threadId. */
+	static fromRecord(run) {
+		return RunBuilder.create(run, run.threadId ?? "");
+	}
+	/** Create a RunBuilder from a store RunRecord, restoring all mutable state. */
+	static create(run, threadId) {
+		const rb = new RunBuilder(run.id, threadId, run.createdAt, run.status, run.metadata, run.config);
+		rb.startedAt = run.startedAt ?? void 0;
+		rb.completedAt = run.completedAt ?? void 0;
+		rb.cancelledAt = run.cancelledAt ?? void 0;
+		rb.failedAt = run.failedAt ?? void 0;
+		rb.lastError = run.lastError ?? void 0;
+		rb.output = run.output;
+		if (run.usage) rb.usage = { ...run.usage };
+		return rb;
+	}
+	/** queued -> in_progress. Returns store update. */
+	start() {
+		if (this.status !== RunStatus.Queued) throw new InvalidRunStateTransitionError(this.status, RunStatus.InProgress);
+		this.status = RunStatus.InProgress;
+		this.startedAt = nowUnix();
+		return {
+			status: this.status,
+			startedAt: this.startedAt
+		};
+	}
+	/** in_progress -> completed. Returns store update. */
+	complete(output, usage) {
+		if (this.status !== RunStatus.InProgress) throw new InvalidRunStateTransitionError(this.status, RunStatus.Completed);
+		this.status = RunStatus.Completed;
+		this.completedAt = nowUnix();
+		this.output = output;
+		this.usage = usage;
+		return {
+			status: this.status,
+			output,
+			usage,
+			completedAt: this.completedAt
+		};
+	}
+	/** queued/in_progress -> failed. Returns store update. */
+	fail(error) {
+		if (this.status !== RunStatus.InProgress && this.status !== RunStatus.Queued) throw new InvalidRunStateTransitionError(this.status, RunStatus.Failed);
+		this.status = RunStatus.Failed;
+		this.failedAt = nowUnix();
+		this.lastError = {
+			code: AgentErrorCode.ExecError,
+			message: error.message
+		};
+		return {
+			status: this.status,
+			lastError: this.lastError,
+			failedAt: this.failedAt
+		};
+	}
+	/** in_progress/queued -> cancelling (idempotent if already cancelling). Returns store update. */
+	cancelling() {
+		if (this.status === RunStatus.Cancelling) return { status: this.status };
+		if (this.status !== RunStatus.InProgress && this.status !== RunStatus.Queued) throw new InvalidRunStateTransitionError(this.status, RunStatus.Cancelling);
+		this.status = RunStatus.Cancelling;
+		return { status: this.status };
+	}
+	/** cancelling -> cancelled. Returns store update. */
+	cancel() {
+		if (this.status !== RunStatus.Cancelling) throw new InvalidRunStateTransitionError(this.status, RunStatus.Cancelled);
+		this.status = RunStatus.Cancelled;
+		this.cancelledAt = nowUnix();
+		return {
+			status: this.status,
+			cancelledAt: this.cancelledAt
+		};
+	}
+	/** Produce a RunObject snapshot for API / SSE. */
+	snapshot() {
+		return {
+			id: this.id,
+			object: AgentObjectType.ThreadRun,
+			createdAt: this.createdAt,
+			threadId: this.threadId,
+			status: this.status,
+			lastError: this.lastError,
+			startedAt: this.startedAt ?? null,
+			completedAt: this.completedAt ?? null,
+			cancelledAt: this.cancelledAt ?? null,
+			failedAt: this.failedAt ?? null,
+			usage: this.usage ?? null,
+			metadata: this.metadata,
+			output: this.output,
+			config: this.config
+		};
+	}
+};
+
+//#endregion
+export { RunBuilder };

package/dist/SSEWriter.d.ts

@@ -0,0 +1,17 @@
+//#region src/SSEWriter.d.ts
+/**
+* Abstract interface for writing SSE events.
+* Decouples AgentRuntime from HTTP transport details.
+*/
+interface SSEWriter {
+  /** Write an SSE event with the given name and JSON-serializable data. */
+  writeEvent(event: string, data: unknown): void;
+  /** Whether the underlying connection has been closed. */
+  readonly closed: boolean;
+  /** End the SSE stream. */
+  end(): void;
+  /** Register a callback for when the client disconnects. */
+  onClose(callback: () => void): void;
+}
+//#endregion
+export { SSEWriter };

package/dist/SSEWriter.js

@@ -0,0 +1 @@
+export {  };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { SSEWriter } from "./SSEWriter.js";
+import { AGENT_RUNTIME, AgentExecutor, AgentRuntime, AgentRuntimeOptions } from "./AgentRuntime.js";
+import { newMsgId, newRunId, newThreadId, nowUnix } from "./AgentStoreUtils.js";
+import { HttpSSEWriter } from "./HttpSSEWriter.js";
+import { RunBuilder, RunUsage } from "./RunBuilder.js";
+import { MessageConverter } from "./MessageConverter.js";
+import { OSSAgentStore, OSSAgentStoreOptions } from "./OSSAgentStore.js";
+import { OSSObjectStorageClient } from "./OSSObjectStorageClient.js";
+export * from "@eggjs/tegg-types/agent-runtime";
+export { AGENT_RUNTIME, type AgentExecutor, AgentRuntime, type AgentRuntimeOptions, HttpSSEWriter, MessageConverter, OSSAgentStore, OSSAgentStoreOptions, OSSObjectStorageClient, RunBuilder, RunUsage, SSEWriter, newMsgId, newRunId, newThreadId, nowUnix };

package/dist/index.js

@@ -0,0 +1,11 @@
+import { newMsgId, newRunId, newThreadId, nowUnix } from "./AgentStoreUtils.js";
+import { MessageConverter } from "./MessageConverter.js";
+import { RunBuilder } from "./RunBuilder.js";
+import { AGENT_RUNTIME, AgentRuntime } from "./AgentRuntime.js";
+import { HttpSSEWriter } from "./HttpSSEWriter.js";
+import { OSSAgentStore } from "./OSSAgentStore.js";
+import { OSSObjectStorageClient } from "./OSSObjectStorageClient.js";
+
+export * from "@eggjs/tegg-types/agent-runtime"
+
+export { AGENT_RUNTIME, AgentRuntime, HttpSSEWriter, MessageConverter, OSSAgentStore, OSSObjectStorageClient, RunBuilder, newMsgId, newRunId, newThreadId, nowUnix };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@eggjs/agent-runtime",
+  "version": "4.0.2-beta.3",
+  "description": "Agent runtime with store abstraction for Egg.js tegg",
+  "keywords": [
+    "agent",
+    "egg",
+    "runtime",
+    "store",
+    "tegg"
+  ],
+  "homepage": "https://github.com/eggjs/egg/tree/next/tegg/core/agent-runtime",
+  "bugs": {
+    "url": "https://github.com/eggjs/egg/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eggjs/egg.git",
+    "directory": "tegg/core/agent-runtime"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./AgentRuntime": "./dist/AgentRuntime.js",
+    "./AgentStoreUtils": "./dist/AgentStoreUtils.js",
+    "./HttpSSEWriter": "./dist/HttpSSEWriter.js",
+    "./MessageConverter": "./dist/MessageConverter.js",
+    "./OSSAgentStore": "./dist/OSSAgentStore.js",
+    "./OSSObjectStorageClient": "./dist/OSSObjectStorageClient.js",
+    "./RunBuilder": "./dist/RunBuilder.js",
+    "./SSEWriter": "./dist/SSEWriter.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "egg-logger": "^3.5.0",
+    "oss-client": "^2.5.1",
+    "@eggjs/tegg-types": "4.0.2-beta.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
+  }
+}