appback-remoteagent 0.13.0

package/dist/services/agent-memory-service.js

@@ -0,0 +1,737 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+const MAX_CONTEXT_CHARS = 2500;
+export class AgentMemoryService {
+    dataDir;
+    rootDir;
+    artifactsPath;
+    secretsPath;
+    docsPath;
+    telegramUploadsDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+        this.rootDir = path.join(dataDir, "managed");
+        this.artifactsPath = path.join(this.rootDir, "artifacts.json");
+        this.secretsPath = path.join(this.rootDir, "secrets.json");
+        this.docsPath = path.join(this.rootDir, "docs-index.json");
+        this.telegramUploadsDir = path.join(dataDir, "uploads", "telegram");
+    }
+    async recordInstruction(session, instruction) {
+        const directive = this.extractInstructionDirective(instruction);
+        const mode = directive?.kind ?? "message";
+        const normalizedInstruction = (directive?.instruction ?? instruction).trim();
+        if (!normalizedInstruction) {
+            return;
+        }
+        const dir = this.sessionDir(session);
+        await fs.mkdir(dir, { recursive: true });
+        const currentPath = path.join(dir, "current.md");
+        const now = new Date().toISOString();
+        const current = await fs.readFile(currentPath, "utf8").catch(() => "");
+        if (current.trim() && mode === "new") {
+            await this.appendHistory(session, {
+                type: "archived",
+                at: now,
+                reason: "new-instruction",
+                text: this.truncate(current, 4000),
+            });
+            await this.resetAttempts(session);
+        }
+        const next = [
+            `# Session State`,
+            ``,
+            `session: ${session.publicId}`,
+            `updatedAt: ${now}`,
+            ``,
+            `## Latest User Instruction`,
+            normalizedInstruction.trim(),
+            ``,
+            `## Harness Rule`,
+            `RemoteAgent records this as session state. It must not block provider execution because a TODO is missing.`,
+            `Use this state to avoid repeating completed work, reverting prior changes, or losing the current workspace after context compaction.`,
+            ``,
+        ].join("\n");
+        await fs.writeFile(currentPath, next, "utf8");
+        await this.appendHistory(session, { type: "instruction", at: now, mode, text: normalizedInstruction.trim() });
+    }
+    async formatSessionState(session) {
+        const current = await this.currentTaskText(session);
+        const todo = await this.readTodo(session);
+        const active = this.activeTodoItems(todo);
+        const history = await this.readRecentHistory(session, 6);
+        return [
+            `Session state for ${session.publicId}`,
+            "",
+            current.trim() ? `Current note:\n${this.summarizeCurrentTask(current)}` : "Current note: none",
+            "",
+            todo.items.length > 0 ? `Legacy TODO notes:\n${this.formatTodoSummary(todo, true)}` : undefined,
+            active.length > 0 ? `legacyActiveTodo: yes` : undefined,
+            history.length > 0 ? ["Recent history:", ...history.map((entry) => `- ${entry}`)].join("\n") : undefined,
+        ].filter(Boolean).join("\n");
+    }
+    async clearSessionState(session, summary) {
+        const dir = this.sessionDir(session);
+        const currentPath = path.join(dir, "current.md");
+        const current = await fs.readFile(currentPath, "utf8").catch(() => "");
+        const todo = await this.readTodo(session);
+        const now = new Date().toISOString();
+        if (todo.items.length > 0) {
+            await this.writeTodo(session, {
+                ...todo,
+                updatedAt: now,
+                items: todo.items.map((item) => this.isActiveTodo(item)
+                    ? { ...item, status: "done", updatedAt: now, note: this.truncate(summary, 500) }
+                    : item),
+            });
+        }
+        await this.appendHistory(session, {
+            type: "completed",
+            at: now,
+            summary: this.truncate(summary, 2000),
+            text: this.truncate(current, 4000),
+        });
+        await fs.rm(currentPath, { force: true }).catch(() => undefined);
+        await this.resetAttempts(session);
+    }
+    async completeTask(session, summary) {
+        await this.clearSessionState(session, summary);
+    }
+    async addSessionNote(session, note) {
+        const normalized = note.trim();
+        if (!normalized) {
+            return;
+        }
+        const dir = this.sessionDir(session);
+        await fs.mkdir(dir, { recursive: true });
+        const now = new Date().toISOString();
+        await this.appendHistory(session, { type: "note", at: now, text: this.truncate(normalized, 2000) });
+        const currentPath = path.join(dir, "current.md");
+        const current = await fs.readFile(currentPath, "utf8").catch(() => "");
+        const next = [
+            current.trim() || [
+                "# Session State",
+                "",
+                `session: ${session.publicId}`,
+                `updatedAt: ${now}`,
+            ].join("\n"),
+            "",
+            "## Operator Note",
+            normalized,
+            "",
+        ].join("\n");
+        await fs.writeFile(currentPath, next, "utf8");
+    }
+    async recordProgress(session, text) {
+        const attempts = await this.readAttempts(session);
+        const signature = this.progressSignature(text);
+        const now = new Date().toISOString();
+        const previous = attempts.progress[signature];
+        const count = (previous?.count ?? 0) + 1;
+        attempts.progress[signature] = {
+            count,
+            lastAt: now,
+            sample: this.truncate(text, 500),
+        };
+        await this.writeAttempts(session, attempts);
+        await this.appendHistory(session, { type: "progress", at: now, count, signature, text: this.truncate(text, 1000) });
+        if (count >= 3) {
+            await this.markActiveTodoBlocked(session, `Repeated similar progress report ${count} times.`);
+        }
+        else {
+            await this.touchActiveTodo(session);
+        }
+        return { count, repeated: count >= 3 };
+    }
+    async recordArtifact(input) {
+        const artifacts = await this.readJson(this.artifactsPath, []);
+        const stat = await fs.stat(input.filePath).catch(() => undefined);
+        const existing = artifacts.find((artifact) => artifact.path === input.filePath);
+        if (existing) {
+            return existing;
+        }
+        const artifact = {
+            id: randomUUID().slice(0, 8),
+            sessionId: input.session?.sessionId,
+            sessionPublicId: input.session?.publicId,
+            botId: input.botId,
+            chatId: input.chatId,
+            kind: input.kind,
+            path: input.filePath,
+            fileName: input.fileName,
+            mimeType: input.mimeType,
+            size: stat?.size,
+            createdAt: new Date().toISOString(),
+        };
+        artifacts.push(artifact);
+        await this.writeJson(this.artifactsPath, artifacts);
+        return artifact;
+    }
+    async listArtifacts(session, limit = 20) {
+        const artifacts = await this.readJson(this.artifactsPath, []);
+        const filtered = session
+            ? artifacts.filter((artifact) => artifact.sessionId === session.sessionId || artifact.sessionPublicId === session.publicId)
+            : artifacts;
+        const recent = filtered.slice().sort((a, b) => b.createdAt.localeCompare(a.createdAt)).slice(0, limit);
+        if (recent.length === 0) {
+            return "No artifacts are indexed yet.";
+        }
+        return [
+            `Artifacts (${recent.length}/${filtered.length})`,
+            ...recent.map((artifact, index) => [
+                `${index + 1}. ${artifact.id} ${artifact.kind}`,
+                `   file: ${artifact.fileName ?? path.basename(artifact.path)}`,
+                `   session: ${artifact.sessionPublicId ?? "unknown"}`,
+                `   size: ${artifact.size ?? "unknown"} bytes`,
+                `   path: ${artifact.path}`,
+            ].join("\n")),
+        ].join("\n");
+    }
+    async cleanupArtifacts(days) {
+        const artifacts = await this.readJson(this.artifactsPath, []);
+        const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+        const kept = [];
+        const keptPaths = new Set();
+        let removedFiles = 0;
+        let removedRecords = 0;
+        for (const artifact of artifacts) {
+            const created = Date.parse(artifact.createdAt);
+            if (artifact.keep || !Number.isFinite(created) || created >= cutoff) {
+                kept.push(artifact);
+                keptPaths.add(path.resolve(artifact.path));
+                continue;
+            }
+            await fs.rm(artifact.path, { force: true }).then(() => {
+                removedFiles += 1;
+            }).catch(() => undefined);
+            removedRecords += 1;
+        }
+        await this.writeJson(this.artifactsPath, kept);
+        const orphanResult = await this.cleanupOrphanTelegramUploads(cutoff, keptPaths);
+        return [
+            "Artifact cleanup finished.",
+            `removedRecords=${removedRecords}`,
+            `removedIndexedFiles=${removedFiles}`,
+            `removedOrphanFiles=${orphanResult.removedFiles}`,
+            `scannedUploadFiles=${orphanResult.scannedFiles}`,
+            `kept=${kept.length}`,
+        ].join(" ");
+    }
+    async setSecret(key, value) {
+        this.assertSecretKey(key);
+        const secrets = await this.readSecrets();
+        const now = new Date().toISOString();
+        secrets[key] = {
+            key,
+            value,
+            createdAt: secrets[key]?.createdAt ?? now,
+            updatedAt: now,
+        };
+        await this.writeSecrets(secrets);
+    }
+    async removeSecret(key) {
+        this.assertSecretKey(key);
+        const secrets = await this.readSecrets();
+        const existed = Boolean(secrets[key]);
+        delete secrets[key];
+        await this.writeSecrets(secrets);
+        return existed;
+    }
+    async getSecret(key) {
+        this.assertSecretKey(key);
+        const secrets = await this.readSecrets();
+        return secrets[key]?.value;
+    }
+    async listSecrets() {
+        const secrets = await this.readSecrets();
+        const records = Object.values(secrets).sort((a, b) => a.key.localeCompare(b.key));
+        if (records.length === 0) {
+            return "No secrets are stored.";
+        }
+        return [
+            `Secrets (${records.length})`,
+            ...records.map((secret) => `- ${secret.key} updatedAt=${secret.updatedAt}`),
+            "",
+            "Values are not shown. Providers may read them through REMOTEAGENT_SECRET_BIN.",
+        ].join("\n");
+    }
+    async pinDocument(keyword, targetPath, note) {
+        const normalized = this.normalizeKeyword(keyword);
+        const docs = await this.readDocs();
+        const now = new Date().toISOString();
+        docs[normalized] = {
+            keyword: normalized,
+            targetPath,
+            note,
+            createdAt: docs[normalized]?.createdAt ?? now,
+            updatedAt: now,
+        };
+        await this.writeJson(this.docsPath, docs);
+    }
+    async removeDocumentPin(keyword) {
+        const normalized = this.normalizeKeyword(keyword);
+        const docs = await this.readDocs();
+        const existed = Boolean(docs[normalized]);
+        delete docs[normalized];
+        await this.writeJson(this.docsPath, docs);
+        return existed;
+    }
+    async findDocuments(keyword) {
+        const normalized = this.normalizeKeyword(keyword);
+        const docs = await this.readDocs();
+        const matches = Object.values(docs)
+            .filter((doc) => doc.keyword.includes(normalized) || normalized.includes(doc.keyword))
+            .sort((a, b) => a.keyword.localeCompare(b.keyword));
+        if (matches.length === 0) {
+            return `No document pins matched: ${keyword}`;
+        }
+        return [
+            `Document pins for "${keyword}" (${matches.length})`,
+            ...matches.map((doc) => `- ${doc.keyword}: ${doc.targetPath}${doc.note ? ` (${doc.note})` : ""}`),
+        ].join("\n");
+    }
+    async listDocuments() {
+        const docs = await this.readDocs();
+        const records = Object.values(docs).sort((a, b) => a.keyword.localeCompare(b.keyword));
+        if (records.length === 0) {
+            return "No document pins are configured.";
+        }
+        return [
+            `Document pins (${records.length})`,
+            ...records.map((doc) => `- ${doc.keyword}: ${doc.targetPath}${doc.note ? ` (${doc.note})` : ""}`),
+        ].join("\n");
+    }
+    async formatProviderContext(session) {
+        const current = await fs.readFile(path.join(this.sessionDir(session), "current.md"), "utf8").catch(() => "");
+        const todo = await this.readTodo(session);
+        const history = await this.readRecentHistory(session, 5);
+        const docs = Object.values(await this.readDocs()).slice(0, 30);
+        const secrets = Object.keys(await this.readSecrets()).sort();
+        const artifacts = (await this.readJson(this.artifactsPath, []))
+            .filter((artifact) => artifact.sessionId === session.sessionId || artifact.sessionPublicId === session.publicId)
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+            .slice(0, 8);
+        const lines = [
+            "RemoteAgent managed context:",
+            [
+                "Session work locations:",
+                `- workspace: ${session.workspace}`,
+                `- memory: ${this.sessionDir(session)}`,
+                "- docs: use managed document pins first, then inspect docs/ under the workspace when relevant.",
+            ].join("\n"),
+            [
+                "Harness execution rules:",
+                "- Treat the user message as the active instruction unless the user explicitly says otherwise.",
+                "- RemoteAgent state is guidance only; never refuse work because a TODO is missing.",
+                "- Use the workspace/memory/docs pointers before searching broadly.",
+                "- Do not claim external delivery, dashboard access, deployment, or file transfer without RemoteAgent-confirmed evidence.",
+                "- If the same action or progress repeats 3 times, stop, mark the blocker, and report the exact blocker.",
+                "- A final report must include concrete evidence: changed files, relevant line references, git diff/status, command output, or log path.",
+            ].join("\n"),
+            todo.items.length > 0
+                ? ["Legacy task notes:", this.formatTodoSummary(todo, true, true)].join("\n")
+                : undefined,
+            current.trim() ? ["Current task note:", this.truncate(current.trim(), 700)].join("\n") : undefined,
+            history.length > 0 ? ["Recent session history:", ...history.map((entry) => `- ${entry}`)].join("\n") : undefined,
+            docs.length > 0
+                ? ["Document index:", ...docs.map((doc) => `- ${doc.keyword}: ${doc.targetPath}${doc.note ? ` (${doc.note})` : ""}`)].join("\n")
+                : undefined,
+            secrets.length > 0
+                ? ["Secret keys available through `node \"$REMOTEAGENT_SECRET_BIN\" get <KEY>`:", ...secrets.map((key) => `- ${key}`)].join("\n")
+                : undefined,
+            artifacts.length > 0
+                ? ["Recent session artifacts:", ...artifacts.map((artifact) => `- ${artifact.id} ${artifact.kind}: ${artifact.path}`)].join("\n")
+                : undefined,
+        ].filter(Boolean).join("\n\n");
+        return this.truncate(lines, MAX_CONTEXT_CHARS);
+    }
+    async currentTaskText(session) {
+        return fs.readFile(path.join(this.sessionDir(session), "current.md"), "utf8").catch(() => "");
+    }
+    async readRecentHistory(session, limit) {
+        const historyPath = path.join(this.sessionDir(session), "history.ndjson");
+        const raw = await fs.readFile(historyPath, "utf8").catch(() => "");
+        return raw
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .slice(-limit)
+            .map((line) => {
+            try {
+                const entry = JSON.parse(line);
+                const kind = entry.mode ? `${entry.type ?? "event"}:${entry.mode}` : entry.type ?? "event";
+                const body = entry.summary ?? entry.text ?? entry.reason ?? "";
+                return `${entry.at ?? "unknown"} ${kind}: ${this.truncate(body.replace(/\s+/g, " ").trim(), 220)}`;
+            }
+            catch {
+                return this.truncate(line.replace(/\s+/g, " ").trim(), 220);
+            }
+        });
+    }
+    todoPath(session) {
+        return path.join(this.sessionDir(session), "todo.json");
+    }
+    async readTodo(session) {
+        const todo = await this.readJson(this.todoPath(session), { createdAt: "", updatedAt: "", items: [] });
+        const normalized = this.normalizeTodoState(todo);
+        if (JSON.stringify(normalized) !== JSON.stringify(todo)) {
+            await this.writeJson(this.todoPath(session), normalized);
+        }
+        return normalized;
+    }
+    async writeTodo(session, todo) {
+        await this.writeJson(this.todoPath(session), {
+            ...todo,
+            items: this.ensureActiveTodo(todo.items),
+        });
+    }
+    extractTodoItems(session, text, now) {
+        if (!this.looksActionableInstruction(text)) {
+            return [];
+        }
+        const listed = this.extractExplicitTodoLines(text);
+        const source = listed.length > 1 ? listed : [text.trim()];
+        return source.slice(0, 20).map((item, index) => this.createTodoItem(session, item, index, now));
+    }
+    extractExplicitTodoLines(text) {
+        const shouldSplit = /쪼개|나눠서|단계별|순서대로|체크리스트|todo/i.test(text);
+        const lines = text
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+        const listed = lines
+            .map((line) => {
+            const match = /^([-*]|\d+[.)])\s+(.+)$/.exec(line);
+            return match?.[2]?.trim();
+        })
+            .filter((line) => Boolean(line && line.length >= 4 && this.looksActionableInstruction(line)));
+        if (listed.length > 1) {
+            return listed;
+        }
+        if (!shouldSplit) {
+            return [];
+        }
+        return lines
+            .map((line) => line.replace(/^[-*]\s+/, "").replace(/^\d+[.)]\s+/, "").trim())
+            .filter((line) => line.length >= 4 && this.looksActionableInstruction(line));
+    }
+    createTodoItem(session, text, index, now) {
+        const purpose = this.truncate(this.normalizeTodoPurpose(text), 500);
+        const sessionMemory = this.sessionDir(session);
+        return {
+            id: `T${String(index + 1).padStart(3, "0")}`,
+            text: purpose,
+            status: index === 0 ? "in_progress" : "pending",
+            createdAt: now,
+            updatedAt: now,
+            attempts: 0,
+            action: this.truncate(text.trim(), 700),
+            workspace: index === 0 ? session.workspace : undefined,
+            memoryPath: index === 0 ? sessionMemory : undefined,
+        };
+    }
+    normalizeTodoPurpose(text) {
+        const compact = text.replace(/\s+/g, " ").trim();
+        const sentence = compact.split(/(?<=[.!?。！？])\s+/u)[0] || compact;
+        return sentence;
+    }
+    looksActionableInstruction(text) {
+        const normalized = text.trim();
+        if (!normalized) {
+            return false;
+        }
+        if (/너는\s+.+담당|담당이야|역할은|프로젝트는/i.test(normalized) && !/개발|진행|등록|처리|시작|작업|수정|고쳐|구현|추가|저장|기록|남겨|배포|테스트|검증|실패|에러|버그|문제|postback|로그|히스토리|마이그레이션|근거|참조|산출물|확인/i.test(normalized)) {
+            return false;
+        }
+        return /개발|진행|등록|처리|시작|작업|구축|연동|작성|수정|고쳐|구현|추가|저장|기록|남겨|배포|테스트|검증|확인|찾아|분석|비교|참조|근거|이유|왜|어떤|어디|어떻게|산출물|자료|데이터|출처|실패|에러|버그|문제|DB|database|api|postback|로그|히스토리|마이그레이션|schema|table|endpoint/i.test(normalized);
+    }
+    activeTodoItems(todo) {
+        return todo.items.filter((item) => this.isActiveTodo(item));
+    }
+    isActiveTodo(item) {
+        return item.status === "pending" || item.status === "in_progress";
+    }
+    ensureActiveTodo(items) {
+        const activeIndex = items.findIndex((item) => item.status === "in_progress");
+        if (activeIndex >= 0) {
+            return items;
+        }
+        const pendingIndex = items.findIndex((item) => item.status === "pending");
+        if (pendingIndex < 0) {
+            return items;
+        }
+        return items.map((item, index) => index === pendingIndex ? { ...item, status: "in_progress" } : item);
+    }
+    normalizeTodoState(todo) {
+        const now = new Date().toISOString();
+        const items = (todo.items ?? []).map((item) => {
+            return item;
+        });
+        return {
+            createdAt: todo.createdAt || now,
+            updatedAt: todo.updatedAt || now,
+            items: this.ensureActiveTodo(items),
+        };
+    }
+    matchesAnyTodo(text, items) {
+        return items.some((item) => this.todoTextSimilarity(text, item.text) >= 0.86);
+    }
+    todoTextSimilarity(left, right) {
+        const a = this.normalizeComparableText(left);
+        const b = this.normalizeComparableText(right);
+        if (!a || !b) {
+            return 0;
+        }
+        if (a === b) {
+            return 1;
+        }
+        const shorter = a.length <= b.length ? a : b;
+        const longer = a.length > b.length ? a : b;
+        if (shorter.length >= 20 && longer.includes(shorter)) {
+            return shorter.length / longer.length;
+        }
+        const aGrams = this.charBigrams(a);
+        const bGrams = this.charBigrams(b);
+        if (aGrams.size === 0 || bGrams.size === 0) {
+            return 0;
+        }
+        let intersection = 0;
+        for (const gram of aGrams) {
+            if (bGrams.has(gram)) {
+                intersection += 1;
+            }
+        }
+        return intersection / (aGrams.size + bGrams.size - intersection);
+    }
+    normalizeComparableText(text) {
+        return text
+            .toLowerCase()
+            .replace(/\s+/g, "")
+            .replace(/[^\p{L}\p{N}가-힣]/gu, "")
+            .trim();
+    }
+    charBigrams(text) {
+        if (text.length <= 1) {
+            return new Set(text ? [text] : []);
+        }
+        const grams = new Set();
+        for (let index = 0; index < text.length - 1; index += 1) {
+            grams.add(text.slice(index, index + 2));
+        }
+        return grams;
+    }
+    async touchActiveTodo(session) {
+        const todo = await this.readTodo(session);
+        const index = todo.items.findIndex((item) => item.status === "in_progress");
+        if (index < 0) {
+            return;
+        }
+        const now = new Date().toISOString();
+        const items = todo.items.slice();
+        items[index] = { ...items[index], attempts: items[index].attempts + 1, updatedAt: now };
+        await this.writeTodo(session, { ...todo, updatedAt: now, items });
+    }
+    async markActiveTodoBlocked(session, note) {
+        const todo = await this.readTodo(session);
+        const now = new Date().toISOString();
+        await this.writeTodo(session, {
+            ...todo,
+            updatedAt: now,
+            items: todo.items.map((item) => item.status === "in_progress"
+                ? { ...item, status: "blocked", updatedAt: now, note }
+                : item),
+        });
+    }
+    extractInstructionDirective(text) {
+        const match = /^(new|새작업|새\s*작업|continue|계속|이어|이어서)\s*[:：]\s*([\s\S]+)$/i.exec(text.trim());
+        if (!match) {
+            return undefined;
+        }
+        const raw = match[1]?.toLowerCase().replace(/\s+/g, "") ?? "";
+        const instruction = match[2]?.trim() ?? "";
+        if (!instruction) {
+            return undefined;
+        }
+        return {
+            kind: raw === "new" || raw === "새작업" ? "new" : "continue",
+            instruction,
+        };
+    }
+    looksLikeContinuation(text) {
+        const normalized = text.trim();
+        return /^(계속|이어|이어서|진행|수정|고쳐|해|다시|확인|검증|배포|빌드|테스트|적용|마무리|커밋|푸시|중단|멈춰|결과|상태|됐어|했어|끝났|완료|continue|go on|resume)/i.test(normalized);
+    }
+    looksLikeNewTask(text) {
+        return /^(새로|새\s*작업|다른\s*작업|이제\s*부터|다음\s*작업|전환|바꿔서|new task)/i.test(text.trim());
+    }
+    summarizeCurrentTask(current) {
+        const instructionIndex = current.indexOf("## Instruction");
+        const body = instructionIndex >= 0 ? current.slice(instructionIndex + "## Instruction".length) : current;
+        const immediateRuleIndex = body.indexOf("## Immediate Rule");
+        const instruction = (immediateRuleIndex >= 0 ? body.slice(0, immediateRuleIndex) : body).trim();
+        return this.truncate(instruction || current.trim(), 700);
+    }
+    formatTodoSummary(todo, includeDone = false, detailed = false) {
+        const items = includeDone ? todo.items : todo.items.filter((item) => item.status !== "done");
+        if (items.length === 0) {
+            return "TODO: none";
+        }
+        return items.map((item, index) => {
+            const marker = item.status === "done" ? "완료" : item.status === "in_progress" ? "진행중" : item.status === "blocked" ? "차단" : "대기";
+            const note = item.note ? ` (${item.note})` : "";
+            if (!detailed) {
+                const attempts = item.attempts > 0 ? ` attempts=${item.attempts}` : "";
+                return `${index + 1}. [${item.id}] ${marker}: ${item.text}${note}${attempts}`;
+            }
+            const details = [
+                `${index + 1}. [${item.id}] ${marker}: ${item.text}${note}`,
+                item.workspace ? `   - 작업 폴더: ${item.workspace}` : undefined,
+                item.memoryPath ? `   - 개인 memory: ${item.memoryPath}` : undefined,
+                item.officialDocs ? `   - 공식 문서 위치: ${item.officialDocs}` : undefined,
+                item.relatedFiles ? `   - 관련 파일: ${item.relatedFiles}` : undefined,
+                item.action ? `   - 해야 할 일: ${item.action}` : undefined,
+                item.caution ? `   - 하지 말 것: ${item.caution}` : undefined,
+                item.doneEvidence ? `   - 완료 조건: ${item.doneEvidence}` : undefined,
+                item.stopCondition ? `   - 중단 조건: ${item.stopCondition}` : undefined,
+                item.reportFormat ? `   - 보고 형식: ${item.reportFormat}` : undefined,
+                `   - attempts: ${item.attempts}`,
+            ].filter(Boolean);
+            return details.join("\n");
+        }).join("\n");
+    }
+    progressSignature(text) {
+        const normalized = text
+            .toLowerCase()
+            .replace(/\d{4}-\d{2}-\d{2}[^\s]*/g, "")
+            .replace(/\b\d+\b/g, "")
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, 240);
+        return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+    }
+    sessionDir(session) {
+        return path.join(this.rootDir, "sessions", session.publicId);
+    }
+    async appendHistory(session, entry) {
+        const dir = this.sessionDir(session);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.appendFile(path.join(dir, "history.ndjson"), `${JSON.stringify(entry)}\n`, "utf8");
+    }
+    async readAttempts(session) {
+        return this.readJson(path.join(this.sessionDir(session), "attempts.json"), { progress: {} });
+    }
+    async writeAttempts(session, attempts) {
+        await this.writeJson(path.join(this.sessionDir(session), "attempts.json"), attempts);
+    }
+    async resetAttempts(session) {
+        await this.writeAttempts(session, { progress: {} });
+    }
+    async readSecrets() {
+        return this.readJson(this.secretsPath, {});
+    }
+    async writeSecrets(secrets) {
+        await fs.mkdir(path.dirname(this.secretsPath), { recursive: true });
+        await fs.writeFile(this.secretsPath, JSON.stringify(secrets, null, 2), { encoding: "utf8", mode: 0o600 });
+        await fs.chmod(this.secretsPath, 0o600).catch(() => undefined);
+    }
+    async readDocs() {
+        return this.readJson(this.docsPath, {});
+    }
+    normalizeKeyword(keyword) {
+        const normalized = keyword.trim().toLowerCase();
+        if (!/^[a-z0-9가-힣._-]{1,80}$/i.test(normalized)) {
+            throw new Error("Keyword must be 1-80 chars and may contain letters, numbers, Korean, dot, underscore, or dash.");
+        }
+        return normalized;
+    }
+    assertSecretKey(key) {
+        if (!/^[A-Z0-9_.-]{1,80}$/.test(key)) {
+            throw new Error("Secret key must be 1-80 chars using A-Z, 0-9, dot, underscore, or dash.");
+        }
+    }
+    async readJson(filePath, fallback) {
+        try {
+            const raw = await fs.readFile(filePath, "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    async cleanupOrphanTelegramUploads(cutoff, keptPaths) {
+        let scannedFiles = 0;
+        let removedFiles = 0;
+        const files = await this.listFilesRecursive(this.telegramUploadsDir);
+        for (const filePath of files) {
+            scannedFiles += 1;
+            const resolved = path.resolve(filePath);
+            if (keptPaths.has(resolved)) {
+                continue;
+            }
+            const stat = await fs.stat(filePath).catch(() => undefined);
+            if (!stat?.isFile() || stat.mtimeMs >= cutoff) {
+                continue;
+            }
+            await fs.rm(filePath, { force: true }).then(() => {
+                removedFiles += 1;
+            }).catch(() => undefined);
+        }
+        await this.removeEmptyDirectories(this.telegramUploadsDir);
+        return { scannedFiles, removedFiles };
+    }
+    async listFilesRecursive(root) {
+        const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+        const files = [];
+        for (const entry of entries) {
+            const entryPath = path.join(root, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...await this.listFilesRecursive(entryPath));
+            }
+            else if (entry.isFile()) {
+                files.push(entryPath);
+            }
+        }
+        return files;
+    }
+    async removeEmptyDirectories(root) {
+        const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+        let empty = entries.length === 0;
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                empty = false;
+                continue;
+            }
+            const childPath = path.join(root, entry.name);
+            const childEmpty = await this.removeEmptyDirectories(childPath);
+            if (!childEmpty) {
+                empty = false;
+            }
+        }
+        if (empty && root !== this.telegramUploadsDir) {
+            await fs.rmdir(root).catch(() => undefined);
+        }
+        return empty;
+    }
+    async writeJson(filePath, value) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    }
+    truncate(text, max) {
+        return text.length > max ? `${text.slice(0, max)}\n[truncated ${text.length - max} chars]` : text;
+    }
+}
+export function readSecretValue(dataDir, key) {
+    if (!/^[A-Z0-9_.-]{1,80}$/.test(key)) {
+        return undefined;
+    }
+    const filePath = path.join(dataDir, "managed", "secrets.json");
+    try {
+        const raw = fsSync.readFileSync(filePath, "utf8");
+        const secrets = JSON.parse(raw);
+        return secrets[key]?.value;
+    }
+    catch {
+        return undefined;
+    }
+}