@eggjs/agent-runtime 0.0.0 → 3.73.0-beta.1

package/dist/src/FileAgentStore.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileAgentStore = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+class FileAgentStore {
+    constructor(options) {
+        this.dataDir = options.dataDir;
+        this.threadsDir = node_path_1.default.join(this.dataDir, 'threads');
+        this.runsDir = node_path_1.default.join(this.dataDir, 'runs');
+    }
+    safePath(baseDir, id) {
+        if (!id) {
+            throw new Error('Invalid id: id must not be empty');
+        }
+        const filePath = node_path_1.default.join(baseDir, `${id}.json`);
+        if (!filePath.startsWith(baseDir + node_path_1.default.sep)) {
+            throw new Error(`Invalid id: ${id}`);
+        }
+        return filePath;
+    }
+    async init() {
+        await promises_1.default.mkdir(this.threadsDir, { recursive: true });
+        await promises_1.default.mkdir(this.runsDir, { recursive: true });
+    }
+    async createThread(metadata) {
+        const threadId = `thread_${node_crypto_1.default.randomUUID()}`;
+        const record = {
+            id: threadId,
+            object: 'thread',
+            messages: [],
+            metadata: metadata !== null && metadata !== void 0 ? metadata : {},
+            created_at: Math.floor(Date.now() / 1000),
+        };
+        await this.writeFile(this.safePath(this.threadsDir, threadId), record);
+        return record;
+    }
+    async getThread(threadId) {
+        const filePath = this.safePath(this.threadsDir, threadId);
+        const data = await this.readFile(filePath);
+        if (!data) {
+            throw new Error(`Thread ${threadId} not found`);
+        }
+        return data;
+    }
+    // Note: read-modify-write without locking. Concurrent appends to the same thread may lose messages.
+    // This is acceptable for a default file-based store; production stores should implement proper locking.
+    async appendMessages(threadId, messages) {
+        const thread = await this.getThread(threadId);
+        thread.messages.push(...messages);
+        await this.writeFile(this.safePath(this.threadsDir, threadId), thread);
+    }
+    async createRun(input, threadId, config, metadata) {
+        const runId = `run_${node_crypto_1.default.randomUUID()}`;
+        const record = {
+            id: runId,
+            object: 'thread.run',
+            thread_id: threadId,
+            status: 'queued',
+            input,
+            config,
+            metadata,
+            created_at: Math.floor(Date.now() / 1000),
+        };
+        await this.writeFile(this.safePath(this.runsDir, runId), record);
+        return record;
+    }
+    async getRun(runId) {
+        const filePath = this.safePath(this.runsDir, runId);
+        const data = await this.readFile(filePath);
+        if (!data) {
+            throw new Error(`Run ${runId} not found`);
+        }
+        return data;
+    }
+    async updateRun(runId, updates) {
+        const run = await this.getRun(runId);
+        Object.assign(run, updates);
+        await this.writeFile(this.safePath(this.runsDir, runId), run);
+    }
+    async writeFile(filePath, data) {
+        const tmpPath = `${filePath}.${node_crypto_1.default.randomUUID()}.tmp`;
+        await promises_1.default.writeFile(tmpPath, JSON.stringify(data), 'utf-8');
+        await promises_1.default.rename(tmpPath, filePath);
+    }
+    async readFile(filePath) {
+        try {
+            const content = await promises_1.default.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return null;
+            }
+            throw err;
+        }
+    }
+}
+exports.FileAgentStore = FileAgentStore;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiRmlsZUFnZW50U3RvcmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvRmlsZUFnZW50U3RvcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7O0FBQUEsMERBQTZCO0FBQzdCLGdFQUFrQztBQUNsQyw4REFBaUM7QUFRakMsTUFBYSxjQUFjO0lBS3pCLFlBQVksT0FBOEI7UUFDeEMsSUFBSSxDQUFDLE9BQU8sR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDO1FBQy9CLElBQUksQ0FBQyxVQUFVLEdBQUcsbUJBQUksQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLE9BQU8sRUFBRSxTQUFTLENBQUMsQ0FBQztRQUNyRCxJQUFJLENBQUMsT0FBTyxHQUFHLG1CQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDakQsQ0FBQztJQUVPLFFBQVEsQ0FBQyxPQUFlLEVBQUUsRUFBVTtRQUMxQyxJQUFJLENBQUMsRUFBRSxFQUFFLENBQUM7WUFDUixNQUFNLElBQUksS0FBSyxDQUFDLGtDQUFrQyxDQUFDLENBQUM7UUFDdEQsQ0FBQztRQUNELE1BQU0sUUFBUSxHQUFHLG1CQUFJLENBQUMsSUFBSSxDQUFDLE9BQU8sRUFBRSxHQUFHLEVBQUUsT0FBTyxDQUFDLENBQUM7UUFDbEQsSUFBSSxDQUFDLFFBQVEsQ0FBQyxVQUFVLENBQUMsT0FBTyxHQUFHLG1CQUFJLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztZQUM3QyxNQUFNLElBQUksS0FBSyxDQUFDLGVBQWUsRUFBRSxFQUFFLENBQUMsQ0FBQztRQUN2QyxDQUFDO1FBQ0QsT0FBTyxRQUFRLENBQUM7SUFDbEIsQ0FBQztJQUVELEtBQUssQ0FBQyxJQUFJO1FBQ1IsTUFBTSxrQkFBRSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsVUFBVSxFQUFFLEVBQUUsU0FBUyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7UUFDckQsTUFBTSxrQkFB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

package/dist/src/HttpSSEWriter.d.ts

@@ -0,0 +1,16 @@
+import type { ServerResponse } from 'node:http';
+import type { SSEWriter } from './SSEWriter';
+export 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;
+}

package/dist/src/HttpSSEWriter.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpSSEWriter = void 0;
+class HttpSSEWriter {
+    constructor(res) {
+        this._closed = false;
+        this.closeCallbacks = [];
+        this.headersSent = false;
+        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);
+    }
+}
+exports.HttpSSEWriter = HttpSSEWriter;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiSHR0cFNTRVdyaXRlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9IdHRwU1NFV3JpdGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUlBLE1BQWEsYUFBYTtJQU94QixZQUFZLEdBQW1CO1FBTHZCLFlBQU8sR0FBRyxLQUFLLENBQUM7UUFDaEIsbUJBQWMsR0FBc0IsRUFBRSxDQUFDO1FBQ3ZDLGdCQUFXLEdBQUcsS0FBSyxDQUFDO1FBSTFCLElBQUksQ0FBQyxHQUFHLEdBQUcsR0FBRyxDQUFDO1FBQ2YsSUFBSSxDQUFDLFVBQVUsR0FBRyxHQUFHLEVBQUU7WUFDckIsSUFBSSxDQUFDLE9BQU8sR0FBRyxJQUFJLENBQUM7WUFDcEIsS0FBSyxNQUFNLEVBQUUsSUFBSSxJQUFJLENBQUMsY0FBYztnQkFBRSxFQUFFLEVBQUUsQ0FBQztZQUMzQyxJQUFJLENBQUMsY0FBYyxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUM7UUFDakMsQ0FBQyxDQUFDO1FBQ0YsR0FBRyxDQUFDLEVBQUUsQ0FBQyxPQUFPLEVBQUUsSUFBSSxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQ25DLENBQUM7SUFFRCxrR0FBa0c7SUFDMUYsYUFBYTtRQUNuQixJQUFJLElBQUksQ0FBQyxXQUFXO1lBQUUsT0FBTztRQUM3QixJQUFJLENBQUMsV0FBVyxHQUFHLElBQUksQ0FBQztRQUN4QixJQUFJLENBQUMsR0FBRyxDQUFDLFNBQVMsQ0FBQyxHQUFHLEVBQUU7WUFDdEIsY0FBYyxFQUFFLG1CQUFtQjtZQUNuQyxlQUFlLEVBQUUsVUFBVTtZQUMzQixVQUFVLEVBQUUsWUFBWTtTQUN6QixDQUFDLENBQUM7SUFDTCxDQUFDO0lBRUQsVUFBVSxDQUFDLEtBQWEsRUFBRSxJQUFhO1FBQ3JDLElBQUksSUFBSSxDQUFDLE9BQU87WUFBRSxPQUFPO1FBQ3pCLElBQUksQ0FBQyxhQUFhLEVBQUUsQ0FBQztRQUNyQixJQUFJLENBQUMsR0FBRyxDQUFDLEtBQUssQ0FBQyxVQUFVLEtBQUssV0FBVyxJQUFJLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUN2RSxDQUFDO0lBRUQsSUFBSSxNQUFNO1FBQ1IsT0FBTyxJQUFJLENBQUMsT0FBTyxDQUFDO0lBQ3RCLENBQUM7SUFFRCxHQUFHO1FBQ0QsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsQ0FBQztZQUNsQixJQUFJLENBQUMsT0FBTyxHQUFHLElBQUksQ0FBQztZQUNwQixJQUFJLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxPQUFPLEVBQUUsSUFBSSxDQUFDLFVBQVUsQ0FBQyxDQUFDO1lBQ3ZDLElBQUksQ0FBQyxjQUFjLENBQUMsTUFBTSxHQUFHLENBQUMsQ0FBQztZQUMvQixJQUFJLENBQUMsR0FBRyxDQUFDLEdBQUcsRUFBRSxDQUFDO1FBQ2pCLENBQUM7SUFDSCxDQUFDO0lBRUQsT0FBTyxDQUFDLFFBQW9CO1FBQzFCLElBQUksQ0FBQyxjQUFjLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxDQUFDO0lBQ3JDLENBQUM7Q0FDRjtBQWxERCxzQ0FrREMifQ==

package/dist/src/MessageConverter.d.ts

@@ -0,0 +1,32 @@
+import type { CreateRunInput, MessageObject, MessageContentBlock, AgentStreamMessage, AgentStreamMessagePayload } from '@eggjs/tegg-types/agent-runtime';
+import type { RunUsage } from './RunBuilder';
+export 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[];
+}

package/dist/src/MessageConverter.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageConverter = void 0;
+const agent_runtime_1 = require("@eggjs/tegg-types/agent-runtime");
+const AgentStoreUtils_1 = require("./AgentStoreUtils");
+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: agent_runtime_1.ContentBlockType.Text, text: { value: content, annotations: [] } }];
+        }
+        if (Array.isArray(content)) {
+            return content
+                .filter(part => part.type === agent_runtime_1.ContentBlockType.Text)
+                .map(part => ({ type: agent_runtime_1.ContentBlockType.Text, text: { value: part.text, annotations: [] } }));
+        }
+        return [];
+    }
+    /**
+     * Build a completed MessageObject from an AgentStreamMessage payload.
+     */
+    static toMessageObject(msg, runId) {
+        return {
+            id: (0, AgentStoreUtils_1.newMsgId)(),
+            object: agent_runtime_1.AgentObjectType.ThreadMessage,
+            createdAt: (0, AgentStoreUtils_1.nowUnix)(),
+            runId,
+            role: agent_runtime_1.MessageRole.Assistant,
+            status: agent_runtime_1.MessageStatus.Completed,
+            content: MessageConverter.toContentBlocks(msg),
+        };
+    }
+    /**
+     * Extract MessageObjects and accumulated usage from AgentStreamMessage objects.
+     */
+    static extractFromStreamMessages(messages, runId) {
+        var _a, _b;
+        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 += (_a = msg.usage.promptTokens) !== null && _a !== void 0 ? _a : 0;
+                completionTokens += (_b = msg.usage.completionTokens) !== null && _b !== void 0 ? _b : 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: agent_runtime_1.MessageStatus.Completed, content };
+    }
+    /**
+     * Create an in-progress MessageObject for streaming (before content is known).
+     */
+    static createStreamMessage(msgId, runId) {
+        return {
+            id: msgId,
+            object: agent_runtime_1.AgentObjectType.ThreadMessage,
+            createdAt: (0, AgentStoreUtils_1.nowUnix)(),
+            runId,
+            role: agent_runtime_1.MessageRole.Assistant,
+            status: agent_runtime_1.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 !== agent_runtime_1.MessageRole.System)
+            .map(m => ({
+            id: (0, AgentStoreUtils_1.newMsgId)(),
+            object: agent_runtime_1.AgentObjectType.ThreadMessage,
+            createdAt: (0, AgentStoreUtils_1.nowUnix)(),
+            threadId,
+            role: m.role,
+            status: agent_runtime_1.MessageStatus.Completed,
+            content: typeof m.content === 'string'
+                ? [{ type: agent_runtime_1.ContentBlockType.Text, text: { value: m.content, annotations: [] } }]
+                : m.content.map(p => ({ type: agent_runtime_1.ContentBlockType.Text, text: { value: p.text, annotations: [] } })),
+        }));
+    }
+}
+exports.MessageConverter = MessageConverter;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiTWVzc2FnZUNvbnZlcnRlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9NZXNzYWdlQ29udmVydGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQU9BLG1FQUFnSDtBQUVoSCx1REFBc0Q7QUFHdEQsTUFBYSxnQkFBZ0I7SUFDM0I7O09BRUc7SUFDSCxNQUFNLENBQUMsZUFBZSxDQUFDLEdBQThCO1FBQ25ELElBQUksQ0FBQyxHQUFHO1lBQUUsT0FBTyxFQUFFLENBQUM7UUFDcEIsTUFBTSxPQUFPLEdBQUcsR0FBRyxDQUFDLE9BQU8sQ0FBQztRQUM1QixJQUFJLE9BQU8sT0FBTyxLQUFLLFFBQVEsRUFBRSxDQUFDO1lBQ2hDLE9BQU8sQ0FBQyxFQUFFLElBQUksRUFBRSxnQ0FBZ0IsQ0FBQyxJQUFJLEVBQUUsSUFBSSxFQUFFLEVBQUUsS0FBSyxFQUFFLE9BQU8sRUFBRSxXQUFXLEVBQUUsRUFBRSxFQUFFLEVBQUUsQ0FBQyxDQUFDO1FBQ3RGLENBQUM7UUFDRCxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLEVBQUUsQ0FBQztZQUMzQixPQUFPLE9BQU87aUJBQ1gsTUFBTSxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUMsSUFBSSxDQUFDLElBQUksS0FBSyxnQ0FBZ0IsQ0FBQyxJQUFJLENBQUM7aUJBQ25ELEdBQUcsQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDLENBQUMsRUFBRSxJQUFJLEVBQUUsZ0NBQWdCLENBQUMsSUFBSSxFQUFFLElBQUksRUFBRSxFQUFFLEtBQUssRUFBRSxJQUFJLENBQUMsSUFBSSxFQUFFLFdBQVcsRUFBRSxFQUFFLEVBQUUsRUFBRSxDQUFDLENBQUMsQ0FBQztRQUNqRyxDQUFDO1FBQ0QsT0FBTyxFQUFFLENBQUM7SUFDWixDQUFDO0lBRUQ7O09BRUc7SUFDSCxNQUFNLENBQUMsZUFBZSxDQUFDLEdBQThCLEVBQUUsS0FBYztRQUNuRSxPQUFPO1lBQ0wsRUFBRSxFQUFFLElB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

package/dist/src/OSSAgentStore.d.ts

@@ -0,0 +1,62 @@
+import type { AgentRunConfig, AgentStore, InputMessage, MessageObject, RunRecord, ThreadRecord, ObjectStorageClient } from '@eggjs/tegg-types/agent-runtime';
+export 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.
+ */
+export 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>;
+}

package/dist/src/OSSAgentStore.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OSSAgentStore = void 0;
+const agent_runtime_1 = require("@eggjs/tegg-types/agent-runtime");
+const AgentStoreUtils_1 = require("./AgentStoreUtils");
+/**
+ * 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.
+ */
+class OSSAgentStore {
+    constructor(options) {
+        var _a;
+        this.client = options.client;
+        // Normalize: ensure non-empty prefix ends with '/'
+        const raw = (_a = options.prefix) !== null && _a !== void 0 ? _a : '';
+        this.prefix = raw && !raw.endsWith('/') ? raw + '/' : raw;
+    }
+    // ── Key helpers ──────────────────────────────────────────────────────
+    /** 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`;
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────
+    async init() {
+        var _a, _b;
+        await ((_b = (_a = this.client).init) === null || _b === void 0 ? void 0 : _b.call(_a));
+    }
+    async destroy() {
+        var _a, _b;
+        await ((_b = (_a = this.client).destroy) === null || _b === void 0 ? void 0 : _b.call(_a));
+    }
+    // ── Thread operations ────────────────────────────────────────────────
+    async createThread(metadata) {
+        const threadId = (0, AgentStoreUtils_1.newThreadId)();
+        const meta = {
+            id: threadId,
+            object: agent_runtime_1.AgentObjectType.Thread,
+            metadata: metadata !== null && metadata !== void 0 ? metadata : {},
+            createdAt: (0, AgentStoreUtils_1.nowUnix)(),
+        };
+        await this.client.put(this.threadMetaKey(threadId), JSON.stringify(meta));
+        // Messages file is created lazily on first appendMessages call.
+        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 agent_runtime_1.AgentNotFoundError(`Thread ${threadId} not found`);
+        }
+        const meta = JSON.parse(metaData);
+        // Parse messages JSONL — may not exist yet if no messages were appended.
+        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) {
+        var _a;
+        // Verify the thread exists before writing messages (or returning early),
+        // so callers always get AgentNotFoundError for invalid threadIds.
+        const metaData = await this.client.get(this.threadMetaKey(threadId));
+        if (!metaData) {
+            throw new agent_runtime_1.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) {
+            // Fast path: use the native append API (e.g., OSS AppendObject).
+            await this.client.append(messagesKey, lines);
+        }
+        else {
+            // Slow path: read-modify-write fallback.
+            // NOTE: Not atomic — concurrent appends may lose data.
+            const existing = (_a = (await this.client.get(messagesKey))) !== null && _a !== void 0 ? _a : '';
+            await this.client.put(messagesKey, existing + lines);
+        }
+    }
+    // ── Run operations ───────────────────────────────────────────────────
+    async createRun(input, threadId, config, metadata) {
+        const runId = (0, AgentStoreUtils_1.newRunId)();
+        const record = {
+            id: runId,
+            object: agent_runtime_1.AgentObjectType.ThreadRun,
+            threadId,
+            status: agent_runtime_1.RunStatus.Queued,
+            input,
+            config,
+            metadata,
+            createdAt: (0, AgentStoreUtils_1.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 agent_runtime_1.AgentNotFoundError(`Run ${runId} not found`);
+        }
+        return JSON.parse(data);
+    }
+    // TODO: read-modify-write is NOT atomic. Concurrent updates may lose data.
+    // Acceptable for single-writer scenarios; for multi-writer, consider ETag-based
+    // conditional writes with retry, or use a database-backed AgentStore instead.
+    async updateRun(runId, updates) {
+        const run = await this.getRun(runId);
+        const safeUpdates = { ...updates };
+        delete safeUpdates.id;
+        delete safeUpdates.object;
+        Object.assign(run, safeUpdates);
+        await this.client.put(this.runKey(runId), JSON.stringify(run));
+    }
+}
+exports.OSSAgentStore = OSSAgentStore;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiT1NTQWdlbnRTdG9yZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9PU1NBZ2VudFN0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQVFBLG1FQUFpRztBQUVqRyx1REFBbUU7QUFhbkU7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQThCRztBQUNILE1BQWEsYUFBYTtJQUl4QixZQUFZLE9BQTZCOztRQUN2QyxJQUFJLENBQUMsTUFBTSxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUM7UUFDN0IsbURBQW1EO1FBQ25ELE1BQU0sR0FBRyxHQUFHLE1BQUEsT0FBTyxDQUFDLE1BQU0sbUNBQUksRUFBRSxDQUFDO1FBQ2pDLElBQUksQ0FBQyxNQUFNLEdBQUcsR0FBRyxJQUFJLENBQUMsR0FBRyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsR0FBRyxHQUFHLEdBQUcsQ0FBQyxDQUFDLENBQUMsR0FBRyxDQUFDO0lBQzVELENBQUM7SUFFRCx3RUFBd0U7SUFFeEUsc0NBQXNDO0lBQzlCLGFBQWEsQ0FBQyxRQUFnQjtRQUNwQyxPQUFPLEdBQUcsSUFBSSxDQUFDLE1BQU0sV0FBVyxRQUFRLFlBQVksQ0FBQztJQUN2RCxDQUFDO0lBRUQsNkRBQTZEO0lBQ3JELGlCQUFpQixDQUFDLFFBQWdCO1FBQ3hDLE9BQU8sR0FBRyxJQUFJLENBQUMsTUFBTSxXQUFXLFFBQVEsaUJBQWlCLENBQUM7SUFDNUQsQ0FBQztJQUVELGlDQUFpQztJQUN6QixNQUFNLENBQUMsS0FBYTtRQUMxQixPQUFPLEdBQUcsSUFBSSxDQUFDLE1BQU0sUUFBUSxLQUFLLE9BQU8sQ0FBQztJQUM1QyxDQUFDO0lBRUQsd0VBQXdFO0lBRXhFLEtBQUssQ0FBQyxJQUFJOztRQUNSLE1BQU0sQ0FBQSxNQUFBLE1BQUEsSUFBSSxDQUFDLE1BQU0sRUFBQyxJQUFJLGtEQUFJLENBQUEsQ0FBQztJQUM3QixDQUFDO0lBRUQsS0FBSyxD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

package/dist/src/OSSObjectStorageClient.d.ts

@@ -0,0 +1,46 @@
+import type { ObjectStorageClient } from '@eggjs/tegg-types/agent-runtime';
+import type { OSSObject } from 'oss-client';
+/**
+ * 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.
+ */
+export 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>;
+}