@inetafrica/open-claudia 3.5.14 → 3.5.17

package/core/runner.js

@@ -9,6 +9,7 @@ const crypto = require("crypto");
 const { spawn, execFileSync } = require("child_process");
 const {
   AUTO_COMPACT_TOKENS, MIN_COMPACT_INTERVAL_MS, MAX_PROCESS_TIMEOUT, COMPACT_SUMMARY_TIMEOUT,
+  TOKEN_DIET_CONVERSATIONS, TOKEN_DIET_COMPACT_TOKENS, TOKEN_DIET_COLD_MINUTES, TOKEN_DIET_COLD_MIN_TOKENS,
   CONFIG_DIR, WORKSPACE, config,
 } = require("./config");
 const {
@@ -16,10 +17,11 @@ const {
   resetSessionUsage, admitLane, cancelTargets, getActiveProvider, getProjectKey,
   laneFor, laneForRun, peekLane, laneBusy, runLaneKey, waitingLanes, slotBlocker, pruneIdleLanes,
   getProviderSession, setProviderSession, clearProviderSession, quarantineProviderSession, getUsageForSession, commitProviderCompaction,
-  resolveProviderSettings,
+  resolveProviderSettings, getProjectSessions,
 } = require("./state");
 const { chatContext, currentChannelId, currentAdapter, currentThreadId } = require("./context");
 const { buildTurnPrompt } = require("./system-prompt");
+const turnJournal = require("./turn-journal");
 const { getProvider, resolveProviderForRun } = require("./providers");
 const { validateInvocation } = require("./providers/contract");
 const { selectTerminalText } = require("./providers/events");
@@ -143,6 +145,9 @@ function applyUsageToState(state, usage, costUsd, opts = {}) {
     ? getUsageForSession(state, project, backend, sessionId)
     : state.sessionUsage;
   u.turns += 1;
+  // When the conversation's last turn ended: past the prompt cache's lifetime
+  // a resume re-writes the whole context (token diet cold-resume check).
+  u.lastTurnAt = Date.now();
   u.inputTokens += parts.input;
   u.outputTokens += parts.output;
   u.cacheReadTokens += parts.cacheRead;
@@ -992,12 +997,38 @@ function resolveRunCwd(cwd) {
 
 const CODEX_WINDOW_COMPACT_FRACTION = 0.8;
 
+// Token diet canary (core/config.js). `opts.tokenDiet` overrides the
+// configured values (tests).
+function tokenDietSettings(override = null) {
+  const num = (value, fallback) => (Number.isFinite(value) && value > 0 ? value : fallback);
+  const o = override || {};
+  return {
+    conversations: Array.isArray(o.conversations) ? o.conversations : TOKEN_DIET_CONVERSATIONS,
+    compactTokens: num(o.compactTokens ?? TOKEN_DIET_COMPACT_TOKENS, 200000),
+    coldMinutes: num(o.coldMinutes ?? TOKEN_DIET_COLD_MINUTES, 60),
+    coldMinTokens: num(o.coldMinTokens ?? TOKEN_DIET_COLD_MIN_TOKENS, 120000),
+  };
+}
+
+function tokenDietListed(conversationKey, override = null) {
+  const key = String(conversationKey || "");
+  if (!key) return false;
+  const list = tokenDietSettings(override).conversations;
+  return list.includes("*") || list.includes(key);
+}
+
+// The threshold a conversation compacts at when /compactwindow sets none.
+function defaultCompactTokens(conversationKey, override = null) {
+  if (tokenDietListed(conversationKey, override)) return tokenDietSettings(override).compactTokens;
+  return Number.isFinite(AUTO_COMPACT_TOKENS) ? AUTO_COMPACT_TOKENS : 380000;
+}
+
 function effectiveCompactThreshold(state = currentState(), opts = {}) {
   const override = state.settings?.compactWindow;
   if (override === 0) return 0;
   const base = Number.isFinite(override) && override > 0
     ? override
-    : (Number.isFinite(AUTO_COMPACT_TOKENS) ? AUTO_COMPACT_TOKENS : 380000);
+    : defaultCompactTokens(opts.conversationKey || getProjectKey(state), opts.tokenDiet);
   // Codex's window (258k for gpt-6-astra) sits below the default threshold, so
   // measured honestly the bot would never compact a Codex session — and would
   // lose the brief that feeds memory. Compact at 80% of the reported window.
@@ -1011,7 +1042,7 @@ function effectiveCompactThreshold(state = currentState(), opts = {}) {
 function shouldAutoCompact(state = currentState(), opts = {}) {
   if (opts.skipAutoCompact || opts.fresh || opts.continueSession || peekLane(state, opts.laneKey)?.isCompacting) return false;
   if (!getProviderSession(state, getActiveProvider(state), getProjectKey(state))) return false;
-  const threshold = effectiveCompactThreshold(state);
+  const threshold = effectiveCompactThreshold(state, { tokenDiet: opts.tokenDiet });
   if (threshold === 0) return false;
   const activeUsage = state.sessionUsage;
   const contextTokens = activeUsage?.liveContextTokens || activeUsage?.lastInputTokens || 0;
@@ -1025,6 +1056,136 @@ function shouldAutoCompact(state = currentState(), opts = {}) {
   return true;
 }
 
+// Token diet: compact BEFORE a turn that resumes a listed conversation whose
+// prompt cache has expired (last turn ended more than coldMinutes ago) while
+// its context is large: resuming would re-write the whole context at the cache
+// write price, then keep re-reading it every step. Compacting first costs one
+// summary read and the turn runs on a small fresh session. Never for
+// compaction stages, fresh or continue runs, a live call, a lane already
+// compacting, or within MIN_COMPACT_INTERVAL of the last compaction.
+function lastTurnEndedAt(state, usage, provider, project, sessionId) {
+  const at = Number(usage?.lastTurnAt);
+  if (Number.isFinite(at) && at > 0) return at;
+  // Usage recorded before lastTurnAt existed: the session history's lastUsed.
+  try {
+    const record = getProjectSessions(state.userId, project, provider).find((entry) => entry.id === sessionId);
+    const used = Date.parse(record?.lastUsed || "");
+    return Number.isFinite(used) ? used : 0;
+  } catch (_) { return 0; }
+}
+
+function coldResumeDecision(state, runContext, opts = {}) {
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const key = runContext?.project?.name || null;
+  const no = (reason, extra = {}) => ({ compact: false, reason, key, ...extra });
+  if (!tokenDietListed(key, opts.tokenDiet)) return no("not-listed");
+  const purpose = runContext.purpose;
+  if (purpose === "compact-summary" || purpose === "compact-seed") return no("compaction-run");
+  if (runContext.fresh || runContext.continueSession || runContext.liveCall) return no("fresh-or-continue");
+  const provider = runContext.provider;
+  const sessionId = runContext.sessionId || null;
+  if (!sessionId || getProviderSession(state, provider, key) !== sessionId) return no("no-session");
+  if (peekLane(state, opts.laneKey || runLaneKey(runContext))?.isCompacting) return no("compacting");
+  if (effectiveCompactThreshold(state, { conversationKey: key, tokenDiet: opts.tokenDiet }) === 0) return no("compaction-off");
+  const settings = tokenDietSettings(opts.tokenDiet);
+  const usage = getUsageForSession(state, key, provider, sessionId);
+  const endedAt = lastTurnEndedAt(state, usage, provider, key, sessionId);
+  if (!endedAt) return no("never-ran");
+  const idleMinutes = Math.floor((now - endedAt) / 60000);
+  const contextTokens = usage?.liveContextTokens || usage?.lastInputTokens || 0;
+  if (now - endedAt <= settings.coldMinutes * 60000) return no("warm", { idleMinutes, contextTokens });
+  if (contextTokens <= settings.coldMinTokens) return no("small", { idleMinutes, contextTokens });
+  const minInterval = Number.isFinite(MIN_COMPACT_INTERVAL_MS) ? MIN_COMPACT_INTERVAL_MS : 1800000;
+  const checkpointTime = Date.parse(usage?.compactionCheckpoint?.at || "");
+  const lastCompactedAt = Number(usage?.lastCompactedAt) || (Number.isFinite(checkpointTime) ? checkpointTime : 0);
+  if (lastCompactedAt && now - lastCompactedAt < minInterval) return no("recently-compacted", { idleMinutes, contextTokens });
+  return { compact: true, reason: "cold-resume", key, idleMinutes, contextTokens };
+}
+
+// Runs the cold-resume compaction for a turn that holds its lane, and returns
+// the turn's run context on the fresh session (or the unchanged one).
+async function compactColdResume(runContext, state, lane, deps = {}) {
+  const decide = deps.decide || coldResumeDecision;
+  const compact = deps.compact || compactActiveSession;
+  let decision;
+  try { decision = decide(state, runContext, { laneKey: lane.key, now: deps.now, tokenDiet: deps.tokenDiet }); }
+  catch (error) {
+    console.warn(`[token-diet] cold-resume check failed: ${redactSensitive(error.message)}`);
+    return runContext;
+  }
+  if (!decision.compact) {
+    // Only a cold resume that was held back is worth a line; warm turns and
+    // unlisted conversations are the normal case.
+    if (decision.idleMinutes !== undefined && decision.reason !== "warm") {
+      console.log(`[token-diet] cold-resume skip ${decision.key} reason=${decision.reason} ctx=${decision.contextTokens} idle=${decision.idleMinutes}m`);
+    }
+    return runContext;
+  }
+  console.log(`[token-diet] cold-resume compact ${decision.key} ctx=${decision.contextTokens} idle=${decision.idleMinutes}m`);
+  let result;
+  try {
+    result = await compact(runContext.project.dir, {
+      notify: false, laneKey: lane.key, admissionHeld: true,
+      compactReason: "cold-resume", contextTokensBefore: decision.contextTokens,
+    });
+  } catch (error) {
+    console.warn(`[token-diet] cold-resume compaction failed: ${redactSensitive(error.message)}`);
+    return runContext;
+  }
+  if (!result?.compacted || !result.newSessionId) {
+    console.warn(`[token-diet] cold-resume compaction did not complete: ${result?.reason || "unknown"}`);
+    return runContext;
+  }
+  return deepFreeze({
+    ...runContext,
+    sessionId: result.newSessionId,
+    admittedSessionId: result.newSessionId,
+    previousSessionId: result.newSessionId,
+    resumeSessionId: result.newSessionId,
+    continueSession: false,
+    fresh: false,
+  });
+}
+
+// One usage-ledger record per compaction (its provider stages run with
+// persistence off, so they never got a per-turn record): why it ran, the
+// context it replaced, and what the summary + seed runs cost. Kept apart from
+// turn records (kind "compaction", tokens nested) so turn counts and averages
+// stay comparable with the history before it.
+function recordCompactionUsage(entry, deps = {}) {
+  const append = deps.appendUsageRecord || appendUsageRecord;
+  const totals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, costUsd: 0 };
+  for (const run of [entry.summaryRun, entry.seedRun]) {
+    if (!run) continue;
+    if (run.usage) {
+      try {
+        const parts = usageParts(run.usage, entry.provider);
+        totals.inputTokens += parts.input;
+        totals.outputTokens += parts.output;
+        totals.cacheReadTokens += parts.cacheRead;
+        totals.cacheCreationTokens += parts.cacheCreation;
+      } catch (_) { /* unknown provider: tokens stay 0 */ }
+    }
+    if (typeof run.costUsd === "number") totals.costUsd += run.costUsd;
+  }
+  return append({
+    ts: new Date().toISOString(),
+    version: PKG_VERSION,
+    kind: "compaction",
+    compactReason: entry.compactReason || "manual",
+    backend: entry.provider,
+    provider: entry.provider,
+    model: entry.model || null,
+    userId: entry.userId || null,
+    project: entry.project || null,
+    previousSessionId: entry.previousSessionId || null,
+    newSessionId: entry.newSessionId || null,
+    ok: !!entry.ok,
+    contextTokensBefore: Number.isFinite(entry.contextTokensBefore) ? entry.contextTokensBefore : null,
+    compactionUsage: totals,
+  });
+}
+
 function compactSummaryPrompt() {
   return [
     "Summarize this conversation for a fresh compacted continuation.",
@@ -1311,6 +1472,7 @@ function createCompactionService(dependencies = {}) {
   const collectRecent = dependencies.collectRecentTurns || collectRecentTurns;
   const ackSchemaPath = dependencies.ackSchemaPath || ensureCompactionAckSchemaPath;
   const drainQueue = dependencies.drainQueue || drainQueuedMessages;
+  const recordCompaction = dependencies.recordCompaction || recordCompactionUsage;
 
   // Compaction acts on ONE conversation: the lane it is asked from (/compact)
   // or the lane whose turn just finished (auto-compaction, admissionHeld).
@@ -1349,10 +1511,17 @@ function createCompactionService(dependencies = {}) {
     // The recent turns come from THIS conversation's transcript: the captured
     // project, not the state's legacy "Workspace" session (which read another file).
     const recentTurns = collectRecent(capturedStateView(state, summaryContext));
+    const usageBefore = state.sessionUsage;
+    const contextTokensBefore = Number.isFinite(opts.contextTokensBefore)
+      ? opts.contextTokensBefore
+      : (usageBefore?.liveContextTokens || usageBefore?.lastInputTokens || 0);
+    let summaryRun = null;
+    let seedRun = null;
+    let committedSessionId = null;
     lane.isCompacting = true;
     try {
       if (opts.notify) await send(opts.message || "Context is getting large, compacting first so this stays fast…");
-      const summaryRun = await runCapture(summaryPrompt, summaryContext.cwd || cwd, {
+      summaryRun = await runCapture(summaryPrompt, summaryContext.cwd || cwd, {
         runContext: summaryContext,
         persist: false,
       });
@@ -1385,7 +1554,7 @@ function createCompactionService(dependencies = {}) {
         outputSchemaPath,
         recallQuery: seedRecallQuery(condensed || fullBrief),
       });
-      const seedRun = await runCapture(seedPrompt, seedContext.cwd || cwd, {
+      seedRun = await runCapture(seedPrompt, seedContext.cwd || cwd, {
         runContext: seedContext,
         persist: false,
       });
@@ -1410,6 +1579,7 @@ function createCompactionService(dependencies = {}) {
       } catch (error) {
         return { compacted: false, reason: `Compaction commit failed: ${redactSensitive(error.message)}` };
       }
+      committedSessionId = seedRun.sessionId;
       let briefPath = null;
       try { briefPath = archiveBrief(fullBrief, capturedStateView(state, summaryContext)); } catch (_) {}
       try {
@@ -1429,9 +1599,27 @@ function createCompactionService(dependencies = {}) {
         project: summaryContext.project.name,
         summary,
         commit,
+        compactReason: opts.compactReason || "manual",
       };
     } finally {
       lane.isCompacting = false;
+      if (summaryRun) {
+        try {
+          recordCompaction({
+            compactReason: opts.compactReason || "manual",
+            provider: summaryContext.provider,
+            model: summaryContext.providerSettings?.model || null,
+            userId: summaryContext.canonicalUserId,
+            project: summaryContext.project.name,
+            previousSessionId: oldSessionId,
+            newSessionId: committedSessionId,
+            ok: !!committedSessionId,
+            contextTokensBefore,
+            summaryRun,
+            seedRun,
+          });
+        } catch (error) { console.warn(`[compact] usage record failed: ${redactSensitive(error.message)}`); }
+      }
       // A bare cancel flag names no run: whatever it was for is over now.
       if (lane.cancelRequested === true) lane.cancelRequested = false;
       try { await drainQueue(state); }
@@ -1769,10 +1957,13 @@ async function deliverForegroundResult(result, runContext, state = currentState(
     finalText = parts.text || parts.script || finalText;
   }
 
+  // botTags: the final answer is the only post that may tag (wake) another
+  // bot in a group (channels/kazee/bot-handoffs.js); adapters without bot tags
+  // ignore it.
   const chunks = splitMessage(finalText);
   for (let index = 0; index < chunks.length; index += 1) {
-    let sent = await send(chunks[index], telegramHtmlOpts(index === 0 ? { replyTo: runContext.replyToMsgId } : {}));
-    if (!sent.ok) sent = await send(chunks[index], telegramHtmlOpts());
+    let sent = await send(chunks[index], telegramHtmlOpts(index === 0 ? { replyTo: runContext.replyToMsgId, botTags: true } : { botTags: true }));
+    if (!sent.ok) sent = await send(chunks[index], telegramHtmlOpts({ botTags: true }));
     if (!sent.ok) throw new Error(`failed to deliver response chunk ${index + 1}`);
   }
 
@@ -2355,6 +2546,33 @@ function quarantineRefusedRun(result, runContext, state) {
   }
 }
 
+// A resume whose saved conversation no longer exists on disk (its transcript file is gone, or
+// was never written) fails EVERY turn of that conversation with "No conversation found with
+// session ID" until someone sends /new (chat-spaces-bot's Agent Space chat, 6 Oct 2026).
+// Recovery: retire the stale id like a refused session, then replay the message once in a
+// fresh session. Never for captures, background work, or a run that is itself a retry.
+const MISSING_CONVERSATION = /No conversation found with session ID/i;
+function shouldRetryMissingConversation(result, runContext, { capture = false, refusalRetried = false } = {}) {
+  return !capture
+    && !refusalRetried
+    && runContext?.purpose === "foreground"
+    && !!runContext?.sessionId
+    && !!result
+    && !result.ok
+    && MISSING_CONVERSATION.test(`${result.error?.message || ""}\n${result.stderr || ""}`);
+}
+
+function retireMissingConversation(runContext, state) {
+  try {
+    quarantineProviderSession(state, runContext.provider, runContext.project?.name, runContext.sessionId, { reason: "missing" });
+    saveState({ strict: true });
+    return true;
+  } catch (error) {
+    console.error("missing-conversation reset failed:", redactSensitive(String(error.message || error)));
+    return false;
+  }
+}
+
 function refusalRetryContext(runContext, state) {
   return deepFreeze({
     ...runContext,
@@ -2409,6 +2627,9 @@ async function runAdmitted(runContext, state, store, capture, ownsAdmissionLock,
   const persistCapture = executionOptions.persistCapture !== false;
   const internalCapture = capture && !persistCapture;
   if (tracksMainRun) lane.activeRunContext = runContext;
+  // Turn journal "lock": a foreground chat turn that a restart cuts short is
+  // resumed after boot (core/turn-journal).
+  if (tracksMainRun) turnJournal.begin(runContext);
   if (!internalCapture) runContext = consumeOneShotBudget(runContext, state, executionOptions);
   const stopTyping = startTypingHeartbeat(state, store, runLaneKey(runContext));
   const holdsLane = () => ownsAdmissionLock
@@ -2420,6 +2641,15 @@ async function runAdmitted(runContext, state, store, capture, ownsAdmissionLock,
   });
   let result;
   try {
+    // Token diet: a listed conversation resumed after its prompt cache expired
+    // is compacted first and the turn runs on the fresh session.
+    if (!capture && ownsAdmissionLock && !executionOptions.refusalRetried && sameCapturedProject(state, runContext)) {
+      const rebased = await compactColdResume(runContext, state, lane);
+      if (rebased !== runContext) {
+        if (tracksMainRun && lane.activeRunContext === runContext) lane.activeRunContext = rebased;
+        runContext = rebased;
+      }
+    }
     result = await service.executeCaptured(runContext.userPrompt, runContext, { capture });
     if ((result.persistence.transcript.skipped || (!capture && result.delivery.skipped)) && !internalCapture) {
       result = await settleImmediateEffects(result, runContext, { state, store, capture });
@@ -2454,6 +2684,14 @@ async function runAdmitted(runContext, state, store, capture, ownsAdmissionLock,
     return runAdmitted(refusalRetryContext(runContext, state), state, store, capture, ownsAdmissionLock, { ...executionOptions, refusalRetried: true });
   }
 
+  if (shouldRetryMissingConversation(result, runContext, { capture, refusalRetried: executionOptions.refusalRetried })
+    && retireMissingConversation(runContext, state)) {
+    try { service.turnObserver?.onTurnSettled(false); } catch (e) { /* best-effort */ }
+    if (holdsLane()) lane.preparingRun = true;
+    await send("♻️ This conversation's saved history is missing, so I started a fresh one and am answering your message there.").catch(() => {});
+    return runAdmitted(refusalRetryContext(runContext, state), state, store, capture, ownsAdmissionLock, { ...executionOptions, refusalRetried: true });
+  }
+
   if (tracksMainRun) {
     sideChatCoordinator.noteMainResult(runContext, result);
     for (const item of lane.messageQueue) {
@@ -2470,10 +2708,13 @@ async function runAdmitted(runContext, state, store, capture, ownsAdmissionLock,
   // A thread's first delivered reply may name the thread. Detached: it never
   // delays this turn, the lane or the queue behind it.
   if (!capture) nameThreadAfterTurn(result, runContext, store);
+  // "Unlock": the turn ended — answered, cancelled or failed. (A shutdown's
+  // kill keeps it journaled; see turn-journal.end.)
+  if (tracksMainRun) turnJournal.end(runContext);
   // Auto-compaction is part of the lane's turn: only when nothing waits in
   // this conversation, and it compacts this conversation only.
   if (!capture && !runContext.skipAutoCompact && result.ok && lane.messageQueue.length === 0 && sameCapturedProject(state, runContext) && shouldAutoCompact(state, { laneKey: lane.key })) {
-    try { await compactActiveSession(runContext.project.dir, { notify: false, laneKey: lane.key, admissionHeld: ownsAdmissionLock }); }
+    try { await compactActiveSession(runContext.project.dir, { notify: false, laneKey: lane.key, admissionHeld: ownsAdmissionLock, compactReason: "threshold" }); }
     catch (error) { console.warn(`[proactive-compact] failed: ${redactSensitive(error.message)}`); }
   }
   return result;
@@ -2557,6 +2798,13 @@ function runAgent(prompt, cwd, replyToMsgId, opts = {}) {
   });
 
   if (obsoleteCallTurn(store)) return Promise.resolve(cancelledCallRunResult(runContext));
+  // A planned restart is draining: no new turn starts now. The message is
+  // journaled as queued and runs right after the restart.
+  if (turnJournal.isDraining() && turnJournal.journalable(runContext)) {
+    turnJournal.enqueue(runContext);
+    send("Restarting in a moment — I'll pick this up as soon as I'm back.", { replyTo: replyToMsgId }).catch(() => {});
+    return Promise.resolve({ ok: false, status: "deferred", runId: runContext.runId, error: { code: "RESTARTING", message: "Queued until after the restart" } });
+  }
   const admission = admitLane(state, runLaneKey(runContext));
   if (!admission.ok) {
     const lane = admission.lane;
@@ -2571,6 +2819,7 @@ function runAgent(prompt, cwd, replyToMsgId, opts = {}) {
     // `text` is what the person typed (before reply/context blocks were added),
     // so /stop can say which queued messages it dropped.
     const item = queueInLane(lane, { runContext, store, deferred, queuedAt: Date.now(), text: admitted.userPrompt || prompt });
+    turnJournal.enqueue(runContext);
     cancelQueuedCallOnAbort(lane, item);
     // Waiting for a slot: admit whatever the free slots allow, oldest first.
     // This message may be among them, and then it needs no notice.
@@ -2712,6 +2961,8 @@ module.exports = {
   shouldRetryRefusedRun,
   quarantineRefusedRun,
   refusalRetryContext,
+  shouldRetryMissingConversation,
+  retireMissingConversation,
   shouldStartSideChat,
   runSideChatRequest,
   enqueueSideChatRequest,
@@ -2720,6 +2971,11 @@ module.exports = {
   deriveCompactionRunContext,
   getActiveSessionId,
   shouldAutoCompact,
+  tokenDietListed,
+  defaultCompactTokens,
+  coldResumeDecision,
+  compactColdResume,
+  recordCompactionUsage,
   effectiveCompactThreshold,
   usageParts,
   peakContextTokens,

package/core/safe-filename.js

@@ -0,0 +1,47 @@
+"use strict";
+
+// Sender-chosen file names (Kazee and Telegram documents) become paths under
+// FILES_DIR. A name like "../auth.json" must never climb out of that folder,
+// yet "Invoice March (final).pdf" or "ripoti ya mauzo.xlsx" should stay as the
+// sender wrote them. Anything unusable falls back to the adapter's generated
+// name.
+
+const path = require("path");
+
+const MAX_BYTES = 200;   // well under the usual 255-byte filesystem limit
+const MAX_EXT_BYTES = 20;
+
+function capBytes(text, max) {
+  let out = "";
+  for (const ch of text) {
+    if (Buffer.byteLength(out + ch) > max) break;
+    out += ch;
+  }
+  return out;
+}
+
+// The cleaned name, or `fallback` when nothing safe is left.
+function safeFileName(name, fallback) {
+  let s = String(name ?? "").split(/[\\/]/).pop();
+  s = s.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+  s = s.replace(/[^\p{L}\p{M}\p{N} ._\-()]/gu, "_").trim();
+  if (!s || s === "." || s === ".." || s.startsWith(".")) return fallback;
+  if (Buffer.byteLength(s) > MAX_BYTES) {
+    let ext = path.extname(s);
+    if (Buffer.byteLength(ext) > MAX_EXT_BYTES) ext = "";
+    s = capBytes(s.slice(0, s.length - ext.length), MAX_BYTES - Buffer.byteLength(ext)).trim() + ext;
+    if (!s || s.startsWith(".")) return fallback;
+  }
+  return s;
+}
+
+// baseDir joined with the cleaned name; the generated fallback whenever the
+// result would not sit directly inside baseDir.
+function safeJoin(baseDir, name, fallback) {
+  const root = path.resolve(baseDir);
+  const result = path.resolve(root, safeFileName(name, fallback));
+  if (!result.startsWith(root + path.sep) || path.dirname(result) !== root) return path.join(root, fallback);
+  return result;
+}
+
+module.exports = { safeFileName, safeJoin };