@eggjs/agent-runtime 3.73.0-beta.0 → 4.0.2-beta.4

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 };