@plico-ai/runtime 0.0.0-reserved.0 → 0.1.0

package/dist/storage/sqlite/thread-title.js

@@ -0,0 +1,85 @@
+import { suggestThreadTitle } from "../../threads/suggest-title.js";
+import { appendThreadEvent } from "./thread-log.js";
+/** A thread is retitled after each of its first exchanges, then the title is left alone. */
+const retitledExchanges = 3;
+/** Sets the title a user chose. It is never replaced by a generated one afterwards. */
+export function setUserTitle(db, threadId, title, timestamp) {
+    db.prepare("UPDATE threads SET title = ?, title_source = 'user' WHERE thread_id = ?").run(title, threadId);
+    appendThreadEvent(db, threadId, "thread.titled", { title, source: "user" }, timestamp);
+}
+function messageCount(db, threadId) {
+    const row = db
+        .prepare("SELECT COUNT(*) AS count FROM thread_messages WHERE thread_id = ?")
+        .get(threadId);
+    return row.count;
+}
+function isFrozen(db, threadId) {
+    const thread = db
+        .prepare("SELECT title_source AS source FROM threads WHERE thread_id = ?")
+        .get(threadId);
+    if (!thread || thread.source === "user")
+        return true;
+    // Count first: a frozen thread must not load its transcript on every reply.
+    const replies = db
+        .prepare("SELECT COUNT(*) AS count FROM thread_messages WHERE thread_id = ? AND role = 'assistant'")
+        .get(threadId);
+    return replies.count > retitledExchanges;
+}
+/** The transcript to title now, or nothing when the thread is user-titled or past its exchanges. */
+export function getTitleRequest(db, threadId) {
+    if (isFrozen(db, threadId))
+        return undefined;
+    const messages = db
+        .prepare("SELECT role, content FROM thread_messages WHERE thread_id = ? ORDER BY sequence")
+        .all(threadId);
+    return { revision: messageCount(db, threadId), messages };
+}
+/**
+ * Stores a title a titler wrote after a reply. It never replaces a user's title, stops after the
+ * first exchanges like the keyword titler, and rejects a title written from an older transcript
+ * than the one behind the stored title. Returns whether the title changed.
+ */
+export function setGeneratedTitle(db, threadId, title, revision, timestamp) {
+    const thread = db
+        .prepare("SELECT title, title_revision AS stored FROM threads WHERE thread_id = ? AND title_source IS NOT 'user'")
+        .get(threadId);
+    if (!thread || isFrozen(db, threadId) || revision < thread.stored)
+        return false;
+    db.prepare("UPDATE threads SET title_revision = ? WHERE thread_id = ?").run(revision, threadId);
+    if (thread.title === title)
+        return false;
+    db.prepare("UPDATE threads SET title = ?, title_source = 'generated' WHERE thread_id = ?").run(title, threadId);
+    appendThreadEvent(db, threadId, "thread.titled", { title, source: "generated" }, timestamp);
+    return true;
+}
+/**
+ * Names the thread from its transcript. Called inside the transaction that stores a reply, where
+ * a title is only a convenience: if naming fails, the reply is still stored and the run completes.
+ */
+export function retitleThread(db, threadId, timestamp) {
+    db.exec("SAVEPOINT retitle");
+    try {
+        nameThread(db, threadId, timestamp);
+    }
+    catch {
+        db.exec("ROLLBACK TO retitle");
+    }
+    finally {
+        db.exec("RELEASE retitle");
+    }
+}
+function nameThread(db, threadId, timestamp) {
+    const thread = db
+        .prepare("SELECT title, title_source AS source FROM threads WHERE thread_id = ?")
+        .get(threadId);
+    if (!thread || thread.source === "user")
+        return;
+    const request = getTitleRequest(db, threadId);
+    if (!request)
+        return;
+    const title = suggestThreadTitle(request.messages);
+    if (title === undefined || title === thread.title)
+        return;
+    db.prepare("UPDATE threads SET title = ?, title_source = 'generated', title_revision = ? WHERE thread_id = ?").run(title, request.revision, threadId);
+    appendThreadEvent(db, threadId, "thread.titled", { title, source: "generated" }, timestamp);
+}

package/dist/storage/sqlite/threads.d.ts

@@ -0,0 +1,47 @@
+import type { Thread, ThreadEvent, ThreadMessage } from "@plico-ai/contracts";
+import { type Metadata } from "../metadata.js";
+import { type TitleRequest } from "./thread-title.js";
+export interface ThreadStore {
+    readonly storageIdentity?: string;
+    /** Release resources owned by this store. */
+    close(): void;
+    createThread(metadata?: Metadata): Promise<Thread>;
+    /** `metadata` keeps threads whose top-level keys equal every given value. */
+    listThreads(filter?: {
+        metadata?: Metadata;
+    }): Promise<Thread[]>;
+    getThread(id: string): Promise<Thread | undefined>;
+    /** Names a thread for the user. Returns undefined for an unknown thread. */
+    renameThread(id: string, title: string): Promise<Thread | undefined>;
+    /** The transcript to title after a reply, or nothing when the thread no longer takes titles. */
+    getTitleRequest(id: string): Promise<TitleRequest | undefined>;
+    /**
+     * Stores a title written after a reply. A title the user chose is never replaced, and a title
+     * from an older `revision` than the stored one is dropped.
+     */
+    setGeneratedTitle(id: string, title: string, revision: number): Promise<boolean>;
+    getThreadForRun(runId: string): Promise<string | undefined>;
+    addMessage(threadId: string, content: string, runId?: string, recovery?: {
+        providerKey: string;
+        projectRoot: string;
+        context?: Metadata;
+    }): Promise<ThreadMessage | undefined>;
+    getMessages(threadId: string): Promise<ThreadMessage[]>;
+    getEvents(threadId: string): Promise<ThreadEvent[]>;
+    listQueuedRuns(): Promise<Array<{
+        runId: string;
+        threadId: string;
+        content: string;
+        providerKey: string | null;
+        projectRoot: string | null;
+        context?: Metadata;
+        history: Array<Pick<ThreadMessage, "role" | "content">>;
+    }>>;
+}
+export declare class ThreadBusyError extends Error {
+    constructor();
+}
+export declare function createSqliteThreadStore({ databasePath, readOnly, }: {
+    databasePath: string;
+    readOnly?: boolean;
+}): ThreadStore;

package/dist/storage/sqlite/threads.js

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { matchesMetadata, parseMetadata } from "../metadata.js";
+import { openDatabase } from "./open.js";
+import { appendThreadEvent } from "./thread-log.js";
+import { getTitleRequest, setGeneratedTitle, setUserTitle, } from "./thread-title.js";
+const selectThread = "SELECT thread_id AS id, created_at AS createdAt, title, metadata_json AS metadataJson FROM threads";
+function toThread(row) {
+    const { title, metadataJson, ...thread } = row;
+    const metadata = parseMetadata(metadataJson);
+    return {
+        ...thread,
+        ...(title === null ? {} : { title }),
+        ...(metadata === undefined ? {} : { metadata }),
+    };
+}
+export class ThreadBusyError extends Error {
+    constructor() {
+        super("Thread already has an active run.");
+        this.name = "ThreadBusyError";
+    }
+}
+export function createSqliteThreadStore({ databasePath, readOnly = false, }) {
+    const db = openDatabase(databasePath, readOnly);
+    return {
+        ...(databasePath === ":memory:"
+            ? {}
+            : {
+                storageIdentity: process.platform === "win32"
+                    ? resolve(databasePath).toLowerCase()
+                    : resolve(databasePath),
+            }),
+        close() {
+            db.close();
+        },
+        async createThread(metadata) {
+            const thread = {
+                id: randomUUID(),
+                createdAt: new Date().toISOString(),
+                ...(metadata === undefined ? {} : { metadata }),
+            };
+            transaction(db, () => {
+                appendThreadEvent(db, thread.id, "thread.created", { thread }, thread.createdAt);
+                db.prepare("INSERT INTO threads (thread_id, created_at, metadata_json) VALUES (?, ?, ?)").run(thread.id, thread.createdAt, metadata === undefined ? null : JSON.stringify(metadata));
+            });
+            return thread;
+        },
+        async listThreads(filter) {
+            return db
+                .prepare(`${selectThread} ORDER BY created_at, rowid`)
+                .all()
+                .map(toThread)
+                .filter((thread) => matchesMetadata(thread.metadata, filter?.metadata));
+        },
+        async getThread(id) {
+            const row = db.prepare(`${selectThread} WHERE thread_id = ?`).get(id);
+            return row === undefined ? undefined : toThread(row);
+        },
+        async renameThread(id, title) {
+            const found = transaction(db, () => {
+                if (!db.prepare("SELECT 1 FROM threads WHERE thread_id = ?").get(id))
+                    return false;
+                setUserTitle(db, id, title, new Date().toISOString());
+                return true;
+            });
+            return found
+                ? toThread(db.prepare(`${selectThread} WHERE thread_id = ?`).get(id))
+                : undefined;
+        },
+        async getTitleRequest(id) {
+            return getTitleRequest(db, id);
+        },
+        async setGeneratedTitle(id, title, revision) {
+            return transaction(db, () => setGeneratedTitle(db, id, title, revision, new Date().toISOString()));
+        },
+        async getThreadForRun(runId) {
+            const row = db.prepare("SELECT thread_id FROM thread_runs WHERE run_id = ?").get(runId);
+            return row?.thread_id;
+        },
+        async addMessage(threadId, content, runId, recovery) {
+            return transaction(db, () => {
+                if (!db.prepare("SELECT 1 FROM threads WHERE thread_id = ?").get(threadId))
+                    return undefined;
+                if (db
+                    .prepare("SELECT 1 FROM thread_runs t LEFT JOIN runs r ON r.run_id = t.run_id WHERE t.thread_id = ? AND (r.status IS NULL OR r.status IN ('running', 'waiting')) LIMIT 1")
+                    .get(threadId))
+                    throw new ThreadBusyError();
+                if (runId !== undefined)
+                    db.prepare("INSERT INTO thread_runs (run_id, thread_id, provider_key, project_root, context_json) VALUES (?, ?, ?, ?, ?)").run(runId, threadId, recovery?.providerKey ?? null, recovery?.projectRoot ?? null, recovery?.context === undefined ? null : JSON.stringify(recovery.context));
+                const message = {
+                    id: randomUUID(),
+                    threadId,
+                    role: "user",
+                    content,
+                    createdAt: new Date().toISOString(),
+                    ...(runId === undefined ? {} : { runId }),
+                };
+                const sequence = appendThreadEvent(db, threadId, "message.created", { message }, message.createdAt);
+                db.prepare("INSERT INTO thread_messages (message_id, thread_id, role, content, created_at, sequence, run_id) VALUES (?, ?, ?, ?, ?, ?, ?)").run(message.id, threadId, message.role, content, message.createdAt, sequence, runId ?? null);
+                return message;
+            });
+        },
+        async getMessages(threadId) {
+            return db
+                .prepare("SELECT message_id AS id, thread_id AS threadId, role, content, created_at AS createdAt, run_id AS runId FROM thread_messages WHERE thread_id = ? ORDER BY sequence")
+                .all(threadId)
+                .map(({ runId, ...message }) => ({
+                ...message,
+                ...(runId === null ? {} : { runId }),
+            }));
+        },
+        async listQueuedRuns() {
+            const queued = db
+                .prepare("SELECT t.run_id AS runId, t.thread_id AS threadId, t.provider_key AS providerKey, t.project_root AS projectRoot, t.context_json AS contextJson, m.content, m.sequence FROM thread_runs t JOIN thread_messages m ON m.run_id = t.run_id AND m.role = 'user' LEFT JOIN runs r ON r.run_id = t.run_id WHERE r.run_id IS NULL")
+                .all();
+            return queued.map(({ sequence, contextJson, ...run }) => ({
+                ...run,
+                ...(contextJson === null ? {} : { context: parseMetadata(contextJson) }),
+                history: db
+                    .prepare("SELECT role, content FROM thread_messages WHERE thread_id = ? AND sequence < ? ORDER BY sequence")
+                    .all(run.threadId, sequence),
+            }));
+        },
+        async getEvents(threadId) {
+            const rows = db
+                .prepare("SELECT sequence, event_id, schema_version, type, timestamp, payload_json FROM events WHERE stream_type = 'thread' AND stream_id = ? ORDER BY sequence")
+                .all(threadId);
+            return rows.map((row) => {
+                if (row.schema_version !== 1)
+                    throw new Error(`Unsupported thread event schema version: ${row.schema_version}.`);
+                return {
+                    schemaVersion: 1,
+                    streamType: "thread",
+                    streamId: threadId,
+                    sequence: row.sequence,
+                    id: row.event_id,
+                    type: row.type,
+                    timestamp: row.timestamp,
+                    payload: JSON.parse(row.payload_json),
+                };
+            });
+        },
+    };
+}
+function transaction(db, fn) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const result = fn();
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}

package/dist/threads/stopwords.d.ts

@@ -0,0 +1 @@
+export declare function isStopword(word: string): boolean;

package/dist/threads/stopwords.js

@@ -0,0 +1,16 @@
+// Words that never name a topic: function words, greetings and generic verbs. English is
+// complete enough for titles; Spanish, German and Japanese carry only the most common words.
+const english = `a an the and or but if then so of to in on at by for with from into onto about as is are was were be been being
+am do does did done have has had having i me my mine we us our ours you your yours he him his she her they them their it its
+this that these those there here what which who whom whose when where why how all any some no not only own same too very
+can could would should will shall may might must just also again ok okay yes yeah please thanks thank hi hello hey
+good morning evening afternoon need want like help get got make let lets something anything everything one able sure cannot
+today yesterday tomorrow now still else last next talk tell give show find check see look know think try use getting going go
+that's it's i'm i'd i've don't doesn't didn't can't won't what's`;
+const spanish = "el la los las un una de del al y o en por para con que es necesito nuestra nuestro mi tu su hola puedo cuál cual";
+const german = "der die das den dem des ein eine einen und oder im in über ueber von zu mit für bitte erstelle guten morgen hallo";
+const japanese = "の を に は が で て と も ください しました します です ます こんにちは した";
+const stopwords = new Set([english, spanish, german, japanese].flatMap((list) => list.split(/\s+/)));
+export function isStopword(word) {
+    return stopwords.has(word.toLowerCase()) || /^\d+([.,]\d+)?$/.test(word);
+}

package/dist/threads/suggest-title.d.ts

@@ -0,0 +1,9 @@
+export interface TitleMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+/**
+ * Names a conversation from what the user said, with the assistant only confirming a topic.
+ * Returns undefined while the user has not said enough to name it, such as after "Hi".
+ */
+export declare function suggestThreadTitle(messages: TitleMessage[]): string | undefined;

package/dist/threads/suggest-title.js

@@ -0,0 +1,102 @@
+import { isStopword } from "./stopwords.js";
+import { clip, tokenize, weighSentences } from "./words.js";
+const maxPhraseWords = 3;
+const japanese = /[぀-ヿ一-鿿]/;
+const key = (word) => word.toLowerCase();
+function collect(messages, role) {
+    const frequency = new Map();
+    const firstSeen = new Map();
+    let position = 0;
+    for (const message of messages) {
+        if (message.role !== role)
+            continue;
+        const sentences = role === "user"
+            ? weighSentences(message.content)
+            : [{ text: clip(message.content), weight: 1 }];
+        for (const sentence of sentences) {
+            for (const word of tokenize(sentence.text)) {
+                if (word === null || isStopword(word))
+                    continue;
+                frequency.set(key(word), (frequency.get(key(word)) ?? 0) + sentence.weight);
+                if (!firstSeen.has(key(word)))
+                    firstSeen.set(key(word), position);
+                position++;
+            }
+        }
+    }
+    // Position only means something in short text; in a long paste the ask decides.
+    if (position > 60)
+        for (const word of firstSeen.keys())
+            firstSeen.set(word, 0);
+    return { frequency, firstSeen };
+}
+/** Runs of consecutive non-stopwords, cut into windows of up to three words (as in RAKE). */
+function candidatePhrases(messages) {
+    const phrases = [];
+    for (const message of messages) {
+        let run = [];
+        const flush = () => {
+            for (let size = Math.min(maxPhraseWords, run.length); size >= 1; size--)
+                for (let start = 0; start + size <= run.length; start++)
+                    phrases.push(run.slice(start, start + size));
+            run = [];
+        };
+        for (const word of tokenize(clip(message.content))) {
+            if (word === null || isStopword(word))
+                flush();
+            else
+                run.push(word);
+        }
+        flush();
+    }
+    return phrases;
+}
+/**
+ * Names a conversation from what the user said, with the assistant only confirming a topic.
+ * Returns undefined while the user has not said enough to name it, such as after "Hi".
+ */
+export function suggestThreadTitle(messages) {
+    const user = collect(messages, "user");
+    if (user.frequency.size < 2)
+        return undefined;
+    const assistant = collect(messages, "assistant");
+    const assistantText = messages
+        .filter((message) => message.role === "assistant")
+        .map((message) => clip(message.content).toLowerCase())
+        .join(" ");
+    const wordScore = (word) => {
+        const frequency = user.frequency.get(key(word)) ?? 0;
+        if (frequency === 0)
+            return 0;
+        const early = 1 / Math.log2(2 + (user.firstSeen.get(key(word)) ?? 0) / 4);
+        return (frequency + 0.5 * (assistant.frequency.get(key(word)) ?? 0)) * (0.5 + early);
+    };
+    const scored = new Map();
+    for (const phrase of candidatePhrases(messages)) {
+        const id = phrase.map(key).join(" ");
+        if (scored.has(id) || !phrase.every((word) => user.frequency.has(key(word))))
+            continue;
+        let score = phrase.reduce((sum, word) => sum + wordScore(word), 0);
+        // The assistant restating the user's phrase is a strong topic signal.
+        if (phrase.length > 1 && assistantText.includes(id))
+            score *= 1.5;
+        // A very short single word is a weak title.
+        if (phrase.length === 1 && (phrase[0]?.length ?? 0) < 4)
+            score *= 0.5;
+        scored.set(id, { words: phrase, score });
+    }
+    const ranked = [...scored.values()].sort((a, b) => b.score - a.score);
+    const top = ranked[0];
+    if (!top)
+        return undefined;
+    const used = new Set(top.words.map(key));
+    const second = ranked.find((item) => item !== top &&
+        item.score >= 0.45 * top.score &&
+        !item.words.some((word) => used.has(key(word))));
+    const joiner = japanese.test(top.words.join("")) ? "" : " ";
+    const title = [top, second]
+        .filter((item) => item !== undefined)
+        .map((item) => item.words.join(joiner))
+        .join(" · ");
+    return title.charAt(0).toUpperCase() + title.slice(1);
+}

package/dist/threads/titler.d.ts

@@ -0,0 +1,10 @@
+import type { ProjectConfig } from "@plico-ai/contracts";
+import type { ModelProvider } from "../types/index.js";
+import type { TitleMessage } from "./suggest-title.js";
+/** Names a thread from its transcript. May return nothing when there is nothing to say yet. */
+export type ThreadTitler = (messages: TitleMessage[]) => Promise<string | undefined>;
+/**
+ * The titler a project asks for: its `threads/title.ts` function, else the model when
+ * `threads.title` is `model`. Without either, threads keep their keyword titles.
+ */
+export declare function createThreadTitler(root: string, config: ProjectConfig, provider: ModelProvider | undefined): Promise<ThreadTitler | undefined>;

package/dist/threads/titler.js

@@ -0,0 +1,63 @@
+import { pathToFileURL } from "node:url";
+import { findProjectThreadTitleFile } from "@plico-ai/core";
+import { register } from "tsx/esm/api";
+const maxTitleLength = 80;
+const quotes = /^["'`‘’“”]+|["'`‘’“”.]+$/g;
+let registered = false;
+/** Takes the first line, drops quotes and trailing punctuation, and keeps it short. */
+function cleanTitle(text) {
+    const line = text.trim().split(/\r?\n/)[0] ?? "";
+    const title = line.trim().replace(quotes, "").trim();
+    return title === "" ? undefined : title.slice(0, maxTitleLength);
+}
+function modelTitler(provider) {
+    return async (messages) => {
+        const transcript = messages
+            .map((message) => `${message.role === "user" ? "User" : "Assistant"}: ${message.content}`)
+            .join("\n")
+            .slice(0, 4000);
+        let text = "";
+        for await (const chunk of provider.stream({
+            messages: [
+                {
+                    role: "system",
+                    content: "You name chat threads. Reply with the title only, no quotes.",
+                },
+                {
+                    role: "user",
+                    content: `Write a title of at most six words for this conversation:\n\n${transcript}`,
+                },
+            ],
+            maxSteps: 1,
+        }, { signal: AbortSignal.timeout(30_000) }))
+            if (chunk.type === "text")
+                text += chunk.text;
+        return cleanTitle(text);
+    };
+}
+async function moduleTitler(file) {
+    if (!registered) {
+        register();
+        registered = true;
+    }
+    const loaded = (await import(pathToFileURL(file).href));
+    const title = loaded.default;
+    if (typeof title !== "function")
+        throw new Error("threads/title must export a function by default.");
+    return async (messages) => {
+        const result = await title(messages);
+        return typeof result === "string" ? cleanTitle(result) : undefined;
+    };
+}
+/**
+ * The titler a project asks for: its `threads/title.ts` function, else the model when
+ * `threads.title` is `model`. Without either, threads keep their keyword titles.
+ */
+export async function createThreadTitler(root, config, provider) {
+    const file = await findProjectThreadTitleFile(root);
+    if (file)
+        return moduleTitler(file);
+    if (config.threads?.title === "model" && provider)
+        return modelTitler(provider);
+    return undefined;
+}

package/dist/threads/words.d.ts

@@ -0,0 +1,12 @@
+/** Words in order, with `null` marking a phrase break such as punctuation. */
+export declare function tokenize(text: string): Array<string | null>;
+/** Long pastes are mostly context, so keep the start and the end, where the ask usually is. */
+export declare function clip(text: string): string;
+/**
+ * Splits a message into weighted sentences. In a long message the sentence that asks for
+ * something counts most; a short message is all ask, so it stays whole.
+ */
+export declare function weighSentences(text: string): Array<{
+    text: string;
+    weight: number;
+}>;

package/dist/threads/words.js

@@ -0,0 +1,39 @@
+const wordSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+const sentenceSegmenter = new Intl.Segmenter(undefined, { granularity: "sentence" });
+const asks = /[?？]\s*$|\b(please|can you|could you|would you|bitte|por favor)\b|ください/i;
+/** Words in order, with `null` marking a phrase break such as punctuation. */
+export function tokenize(text) {
+    const out = [];
+    let joinNext = false;
+    for (const part of wordSegmenter.segment(text)) {
+        if (!part.isWordLike) {
+            if (part.segment === "-" && typeof out.at(-1) === "string")
+                joinNext = true;
+            else if (/\S/.test(part.segment) && !/^['’]$/.test(part.segment))
+                out.push(null);
+            continue;
+        }
+        const word = part.segment.replace(/['’]s$/i, "");
+        if (joinNext)
+            out[out.length - 1] += `-${word}`;
+        else
+            out.push(word);
+        joinNext = false;
+    }
+    return out;
+}
+/** Long pastes are mostly context, so keep the start and the end, where the ask usually is. */
+export function clip(text) {
+    return text.length <= 4000 ? text : `${text.slice(0, 3000)}\n${text.slice(-1000)}`;
+}
+/**
+ * Splits a message into weighted sentences. In a long message the sentence that asks for
+ * something counts most; a short message is all ask, so it stays whole.
+ */
+export function weighSentences(text) {
+    const parts = [...sentenceSegmenter.segment(clip(text))].map((part) => part.segment);
+    const isAsk = parts.map((part) => asks.test(part.trim()));
+    if (text.split(/\s+/).length <= 60 || !isAsk.includes(true))
+        return [{ text: parts.join(""), weight: 1 }];
+    return parts.map((part, index) => ({ text: part, weight: isAsk[index] ? 3 : 0.5 }));
+}

package/dist/tools/artifact-model-tool-operations.d.ts

@@ -0,0 +1,29 @@
+import type { ArtifactFileMetadata } from "@plico-ai/contracts";
+import type { ToolArtifactContext } from "../types/index.js";
+type ListedArtifact = Pick<ArtifactFileMetadata, "path" | "sizeBytes" | "mimeType" | "version">;
+export declare function listFiles(input: unknown, artifacts: ToolArtifactContext): Promise<{
+    files: ListedArtifact[];
+    offset: number;
+    nextOffset?: number;
+}>;
+export declare function readFile(input: unknown, artifacts: ToolArtifactContext): Promise<{
+    path: string;
+    content: string;
+    mimeType: string;
+    version: number;
+    offset: number;
+    nextOffset?: number;
+} | ({
+    path: string;
+    binary: true;
+} & ArtifactFileMetadata)>;
+export declare function writeFile(input: unknown, artifacts: ToolArtifactContext): Promise<{
+    path: string;
+    version: number;
+}>;
+export declare function editFile(input: unknown, artifacts: ToolArtifactContext): Promise<{
+    path: string;
+    version: number;
+    replacementCount: number;
+}>;
+export {};