minimal-agent 0.10.0 → 0.12.0

package/src/session/runtimeStore.js

@@ -0,0 +1,149 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, readdir, rename, rm, stat, } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { agentStateDir } from '../context/agentHome.js';
+function segment(value, fallback) {
+    return ((value ?? fallback).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) ||
+        fallback);
+}
+export function sessionRuntimeDir(identity) {
+    return join(agentStateDir(), 'runtime', segment(identity.workspaceId, 'local'), segment(identity.sessionId, 'local'));
+}
+const queues = new Map();
+export async function withRuntimeFileLock(path, work) {
+    const key = resolve(path);
+    const previous = queues.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((done) => {
+        release = done;
+    });
+    const tail = previous.then(() => current);
+    queues.set(key, tail);
+    await previous.catch(() => undefined);
+    let lockHandle;
+    const lockPath = `${path}.lock`;
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    try {
+        const deadline = Date.now() + 10_000;
+        while (!lockHandle) {
+            try {
+                lockHandle = await open(lockPath, 'wx', 0o600);
+                await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const age = Date.now() -
+                    (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+                if (age > 30_000)
+                    await rm(lockPath, { force: true });
+                else if (Date.now() >= deadline)
+                    throw new Error(`runtime lock timeout: ${path}`);
+                else
+                    await new Promise((r) => setTimeout(r, 25));
+            }
+        }
+        return await work();
+    }
+    finally {
+        await lockHandle?.close().catch(() => undefined);
+        if (lockHandle)
+            await rm(lockPath, { force: true }).catch(() => undefined);
+        release();
+        if (queues.get(key) === tail)
+            queues.delete(key);
+    }
+}
+export async function readRuntimeJson(path, fallback) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function writeRuntimeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(temp, 'wx', 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temp, path);
+    }
+    finally {
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+export async function mutateRuntimeJson(path, fallback, mutate) {
+    return withRuntimeFileLock(path, async () => {
+        const next = await mutate(await readRuntimeJson(path, fallback));
+        await writeRuntimeJson(path, next);
+        return next;
+    });
+}
+export async function removeManagedPath(path, expectedRoot) {
+    const target = resolve(path);
+    const root = resolve(expectedRoot);
+    const rel = target.slice(root.length);
+    if (target === root || !target.startsWith(`${root}/`) || rel.includes('\0')) {
+        throw new Error(`拒绝清理托管根目录之外的路径：${target}`);
+    }
+    await rm(target, { recursive: true, force: true });
+}
+export async function runtimeFileVersion(path) {
+    const info = await stat(path);
+    return `${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}`;
+}
+const activeOutputs = new Set();
+const OUTPUT_RETENTION_MS = 7 * 24 * 60 * 60_000;
+const OUTPUT_GLOBAL_LIMIT = 5 * 1024 * 1024 * 1024;
+let pruneOutputsPromise;
+export function registerRuntimeOutput(path) {
+    activeOutputs.add(resolve(path));
+}
+export function unregisterRuntimeOutput(path) {
+    activeOutputs.delete(resolve(path));
+}
+export function pruneRuntimeOutputs() {
+    pruneOutputsPromise ??= (async () => {
+        const root = join(agentStateDir(), 'runtime');
+        const files = [];
+        for (const workspace of await readdir(root).catch(() => [])) {
+            const workspaceDir = join(root, workspace);
+            for (const session of await readdir(workspaceDir).catch(() => [])) {
+                const outputDir = join(workspaceDir, session, 'outputs');
+                const sessionFiles = [];
+                for (const name of await readdir(outputDir).catch(() => [])) {
+                    const path = join(outputDir, name);
+                    const info = await stat(path).catch(() => undefined);
+                    if (info?.isFile() && !activeOutputs.has(resolve(path))) {
+                        sessionFiles.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+                    }
+                }
+                sessionFiles.sort((left, right) => right.mtimeMs - left.mtimeMs);
+                await Promise.all(sessionFiles
+                    .slice(50)
+                    .map((file) => rm(file.path, { force: true }).catch(() => undefined)));
+                files.push(...sessionFiles.slice(0, 50));
+            }
+        }
+        files.sort((left, right) => right.mtimeMs - left.mtimeMs);
+        let retainedBytes = 0;
+        const cutoff = Date.now() - OUTPUT_RETENTION_MS;
+        for (const file of files) {
+            retainedBytes += file.size;
+            if (file.mtimeMs < cutoff || retainedBytes > OUTPUT_GLOBAL_LIMIT) {
+                await rm(file.path, { force: true }).catch(() => undefined);
+            }
+        }
+    })().finally(() => {
+        pruneOutputsPromise = undefined;
+    });
+    return pruneOutputsPromise;
+}

package/src/session/runtimeStore.ts

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto';
+import {
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+} from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { agentStateDir } from '../context/agentHome.js';
+
+export interface RuntimeIdentity {
+  workspaceId?: string;
+  sessionId?: string;
+}
+
+function segment(value: string | undefined, fallback: string): string {
+  return (
+    (value ?? fallback).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) ||
+    fallback
+  );
+}
+
+export function sessionRuntimeDir(identity: RuntimeIdentity): string {
+  return join(
+    agentStateDir(),
+    'runtime',
+    segment(identity.workspaceId, 'local'),
+    segment(identity.sessionId, 'local'),
+  );
+}
+
+const queues = new Map<string, Promise<unknown>>();
+export async function withRuntimeFileLock<T>(
+  path: string,
+  work: () => Promise<T>,
+): Promise<T> {
+  const key = resolve(path);
+  const previous = queues.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>((done) => {
+    release = done;
+  });
+  const tail = previous.then(() => current);
+  queues.set(key, tail);
+  await previous.catch(() => undefined);
+  let lockHandle: Awaited<ReturnType<typeof open>> | undefined;
+  const lockPath = `${path}.lock`;
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  try {
+    const deadline = Date.now() + 10_000;
+    while (!lockHandle) {
+      try {
+        lockHandle = await open(lockPath, 'wx', 0o600);
+        await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        const age =
+          Date.now() -
+          (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+        if (age > 30_000) await rm(lockPath, { force: true });
+        else if (Date.now() >= deadline)
+          throw new Error(`runtime lock timeout: ${path}`);
+        else await new Promise((r) => setTimeout(r, 25));
+      }
+    }
+    return await work();
+  } finally {
+    await lockHandle?.close().catch(() => undefined);
+    if (lockHandle) await rm(lockPath, { force: true }).catch(() => undefined);
+    release();
+    if (queues.get(key) === tail) queues.delete(key);
+  }
+}
+
+export async function readRuntimeJson<T>(
+  path: string,
+  fallback: T,
+): Promise<T> {
+  try {
+    return JSON.parse(await readFile(path, 'utf8')) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeRuntimeJson(
+  path: string,
+  value: unknown,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    const handle = await open(temp, 'wx', 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true }).catch(() => undefined);
+  }
+}
+
+export async function mutateRuntimeJson<T>(
+  path: string,
+  fallback: T,
+  mutate: (value: T) => T | Promise<T>,
+): Promise<T> {
+  return withRuntimeFileLock(path, async () => {
+    const next = await mutate(await readRuntimeJson(path, fallback));
+    await writeRuntimeJson(path, next);
+    return next;
+  });
+}
+
+export async function removeManagedPath(
+  path: string,
+  expectedRoot: string,
+): Promise<void> {
+  const target = resolve(path);
+  const root = resolve(expectedRoot);
+  const rel = target.slice(root.length);
+  if (target === root || !target.startsWith(`${root}/`) || rel.includes('\0')) {
+    throw new Error(`拒绝清理托管根目录之外的路径：${target}`);
+  }
+  await rm(target, { recursive: true, force: true });
+}
+
+export async function runtimeFileVersion(path: string): Promise<string> {
+  const info = await stat(path);
+  return `${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}`;
+}
+
+const activeOutputs = new Set<string>();
+const OUTPUT_RETENTION_MS = 7 * 24 * 60 * 60_000;
+const OUTPUT_GLOBAL_LIMIT = 5 * 1024 * 1024 * 1024;
+let pruneOutputsPromise: Promise<void> | undefined;
+
+export function registerRuntimeOutput(path: string): void {
+  activeOutputs.add(resolve(path));
+}
+
+export function unregisterRuntimeOutput(path: string): void {
+  activeOutputs.delete(resolve(path));
+}
+
+export function pruneRuntimeOutputs(): Promise<void> {
+  pruneOutputsPromise ??= (async () => {
+    const root = join(agentStateDir(), 'runtime');
+    const files: Array<{ path: string; size: number; mtimeMs: number }> = [];
+    for (const workspace of await readdir(root).catch(() => [])) {
+      const workspaceDir = join(root, workspace);
+      for (const session of await readdir(workspaceDir).catch(() => [])) {
+        const outputDir = join(workspaceDir, session, 'outputs');
+        const sessionFiles: Array<{
+          path: string;
+          size: number;
+          mtimeMs: number;
+        }> = [];
+        for (const name of await readdir(outputDir).catch(() => [])) {
+          const path = join(outputDir, name);
+          const info = await stat(path).catch(() => undefined);
+          if (info?.isFile() && !activeOutputs.has(resolve(path))) {
+            sessionFiles.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+          }
+        }
+        sessionFiles.sort((left, right) => right.mtimeMs - left.mtimeMs);
+        await Promise.all(
+          sessionFiles
+            .slice(50)
+            .map((file) =>
+              rm(file.path, { force: true }).catch(() => undefined),
+            ),
+        );
+        files.push(...sessionFiles.slice(0, 50));
+      }
+    }
+    files.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    let retainedBytes = 0;
+    const cutoff = Date.now() - OUTPUT_RETENTION_MS;
+    for (const file of files) {
+      retainedBytes += file.size;
+      if (file.mtimeMs < cutoff || retainedBytes > OUTPUT_GLOBAL_LIMIT) {
+        await rm(file.path, { force: true }).catch(() => undefined);
+      }
+    }
+  })().finally(() => {
+    pruneOutputsPromise = undefined;
+  });
+  return pruneOutputsPromise;
+}

package/src/session/sessionState.js

@@ -4,16 +4,92 @@
  * ------------------------------------------------------------
  *  把 reactiveCompact + microCompactLite 的可注入状态打包。
  *
- *  TUI / print 不需要它（不传 → 默认走模块单例，行为不变）；
- *  HTTP server per-request 调 createSessionState() 拿独立一份，
- *  让每个 chatId 的工具结果去重缓存、反应式自救标记互不串扰。
+ *  长生命周期宿主按 workspace + session 复用一份；一次性 CLI 可直接创建。
+ *  让每个 chatId 的工具结果去重缓存、文件读取证据和后台任务互不串扰。
  * ============================================================
  */
 import { createMicroCompactState, } from '../context/microCompactLite.js';
 import { createReactiveCompactState, } from '../context/reactiveCompact.js';
+import { createFileReadState } from '../tools/shared/fileState.js';
+import { createBackgroundTaskState, disposeBackgroundTaskState, } from '../tools/tasks/backgroundTaskService.js';
+import { createAgentTaskState, stopAllAgentTasks } from '../tools/agent/agentTaskService.js';
 export function createSessionState() {
     return {
         reactive: createReactiveCompactState(),
         microCompact: createMicroCompactState(),
+        fileReads: createFileReadState(),
+        backgroundTasks: createBackgroundTaskState(),
+        agentTasks: createAgentTaskState(),
     };
 }
+const persistentStates = new Map();
+const MAX_PERSISTENT_STATES = 128;
+const MAX_IDLE_MS = 24 * 60 * 60_000;
+/** Collision-free durable key shared by Desktop, CLI and headless hosts. */
+export function sessionStateKey(identity) {
+    return JSON.stringify([
+        identity.surface,
+        identity.workspaceId ?? '',
+        identity.cwd ?? '',
+        identity.sessionId,
+    ]);
+}
+/**
+ * Return process-local state scoped to a durable host session key. This keeps
+ * read evidence and background tasks available across user turns without ever
+ * sharing them between workspaces or conversations.
+ */
+export function getOrCreateSessionState(key) {
+    const now = Date.now();
+    let entry = persistentStates.get(key);
+    if (!entry) {
+        entry = { state: createSessionState(), lastUsedAt: now };
+        persistentStates.set(key, entry);
+    }
+    else {
+        entry.lastUsedAt = now;
+    }
+    prunePersistentStates(now, key);
+    return entry.state;
+}
+export async function disposeSessionState(key) {
+    const entry = persistentStates.get(key);
+    if (!entry)
+        return;
+    persistentStates.delete(key);
+    await disposeBackgroundTaskState(entry.state.backgroundTasks);
+    await stopAllAgentTasks(entry.state.agentTasks);
+    entry.state.fileReads.entries.clear();
+}
+export async function disposeAllSessionStates() {
+    const entries = [...persistentStates.values()];
+    persistentStates.clear();
+    await Promise.all(entries.map(async ({ state }) => {
+        await disposeBackgroundTaskState(state.backgroundTasks);
+        await stopAllAgentTasks(state.agentTasks);
+        state.fileReads.entries.clear();
+    }));
+}
+export async function disposeDetachedSessionState(state) {
+    await disposeBackgroundTaskState(state.backgroundTasks);
+    await stopAllAgentTasks(state.agentTasks);
+    state.fileReads.entries.clear();
+}
+function prunePersistentStates(now, keepKey) {
+    const removable = [...persistentStates.entries()]
+        .filter(([key, entry]) => key !== keepKey && now - entry.lastUsedAt > MAX_IDLE_MS)
+        .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt);
+    while (persistentStates.size - removable.length > MAX_PERSISTENT_STATES) {
+        const next = [...persistentStates.entries()]
+            .filter(([key]) => key !== keepKey && !removable.some(([candidate]) => candidate === key))
+            .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt)[0];
+        if (!next)
+            break;
+        removable.push(next);
+    }
+    for (const [key, entry] of removable) {
+        persistentStates.delete(key);
+        void disposeBackgroundTaskState(entry.state.backgroundTasks);
+        entry.state.fileReads.entries.clear();
+    }
+}

package/src/session/sessionState.ts

@@ -0,0 +1,134 @@
+/**
+ * ============================================================
+ *  src/session/sessionState.ts —— 会话级隔离状态
+ * ------------------------------------------------------------
+ *  把 reactiveCompact + microCompactLite 的可注入状态打包。
+ *
+ *  长生命周期宿主按 workspace + session 复用一份；一次性 CLI 可直接创建。
+ *  让每个 chatId 的工具结果去重缓存、文件读取证据和后台任务互不串扰。
+ * ============================================================
+ */
+
+import {
+  createMicroCompactState,
+  type MicroCompactState,
+} from '../context/microCompactLite.js';
+import {
+  createReactiveCompactState,
+  type ReactiveCompactState,
+} from '../context/reactiveCompact.js';
+import { createFileReadState, type FileReadState } from '../tools/shared/fileState.js';
+import {
+  createBackgroundTaskState,
+  disposeBackgroundTaskState,
+  type BackgroundTaskState,
+} from '../tools/tasks/backgroundTaskService.js';
+import { createAgentTaskState, stopAllAgentTasks, type AgentTaskState } from '../tools/agent/agentTaskService.js';
+
+export interface SessionState {
+  reactive: ReactiveCompactState;
+  microCompact: MicroCompactState;
+  fileReads: FileReadState;
+  backgroundTasks: BackgroundTaskState;
+  agentTasks: AgentTaskState;
+  /** Main-agent worktree changes the effective cwd without changing workspace identity. */
+  activeWorktree?: {
+    id: string;
+    path: string;
+    branch: string;
+    baseSha: string;
+    gitRoot: string;
+  };
+}
+
+export function createSessionState(): SessionState {
+  return {
+    reactive: createReactiveCompactState(),
+    microCompact: createMicroCompactState(),
+    fileReads: createFileReadState(),
+    backgroundTasks: createBackgroundTaskState(),
+    agentTasks: createAgentTaskState(),
+  };
+}
+
+const persistentStates = new Map<string, { state: SessionState; lastUsedAt: number }>();
+const MAX_PERSISTENT_STATES = 128;
+const MAX_IDLE_MS = 24 * 60 * 60_000;
+
+export interface SessionStateIdentity {
+  surface: string;
+  workspaceId?: string;
+  cwd?: string;
+  sessionId: string;
+}
+
+/** Collision-free durable key shared by Desktop, CLI and headless hosts. */
+export function sessionStateKey(identity: SessionStateIdentity): string {
+  return JSON.stringify([
+    identity.surface,
+    identity.workspaceId ?? '',
+    identity.cwd ?? '',
+    identity.sessionId,
+  ]);
+}
+
+/**
+ * Return process-local state scoped to a durable host session key. This keeps
+ * read evidence and background tasks available across user turns without ever
+ * sharing them between workspaces or conversations.
+ */
+export function getOrCreateSessionState(key: string): SessionState {
+  const now = Date.now();
+  let entry = persistentStates.get(key);
+  if (!entry) {
+    entry = { state: createSessionState(), lastUsedAt: now };
+    persistentStates.set(key, entry);
+  } else {
+    entry.lastUsedAt = now;
+  }
+  prunePersistentStates(now, key);
+  return entry.state;
+}
+
+export async function disposeSessionState(key: string): Promise<void> {
+  const entry = persistentStates.get(key);
+  if (!entry) return;
+  persistentStates.delete(key);
+  await disposeBackgroundTaskState(entry.state.backgroundTasks);
+  await stopAllAgentTasks(entry.state.agentTasks);
+  entry.state.fileReads.entries.clear();
+}
+
+export async function disposeAllSessionStates(): Promise<void> {
+  const entries = [...persistentStates.values()];
+  persistentStates.clear();
+  await Promise.all(entries.map(async ({ state }) => {
+    await disposeBackgroundTaskState(state.backgroundTasks);
+    await stopAllAgentTasks(state.agentTasks);
+    state.fileReads.entries.clear();
+  }));
+}
+
+export async function disposeDetachedSessionState(state: SessionState): Promise<void> {
+  await disposeBackgroundTaskState(state.backgroundTasks);
+  await stopAllAgentTasks(state.agentTasks);
+  state.fileReads.entries.clear();
+}
+
+function prunePersistentStates(now: number, keepKey: string): void {
+  const removable = [...persistentStates.entries()]
+    .filter(([key, entry]) => key !== keepKey && now - entry.lastUsedAt > MAX_IDLE_MS)
+    .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt);
+  while (persistentStates.size - removable.length > MAX_PERSISTENT_STATES) {
+    const next = [...persistentStates.entries()]
+      .filter(([key]) => key !== keepKey && !removable.some(([candidate]) => candidate === key))
+      .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt)[0];
+    if (!next) break;
+    removable.push(next);
+  }
+  for (const [key, entry] of removable) {
+    persistentStates.delete(key);
+    void disposeBackgroundTaskState(entry.state.backgroundTasks);
+    entry.state.fileReads.entries.clear();
+  }
+}

package/src/toolGate.ts

@@ -0,0 +1,50 @@
+/**
+ * ============================================================
+ *  src/toolGate.ts —— 工具执行闸门（通用机制，零策略）
+ * ------------------------------------------------------------
+ *  一个可选的、社交无感的「工具执行前审批」缝：loop 在执行每个工具前，
+ *  若宿主注入了 toolGate，就先 await 它拿到 allow/deny。deny 时把 reason 当作
+ *  tool_result 回填给模型（模型据此改道/如实报告），不抛异常、不中断整轮。
+ *
+ *  内核对「为什么要审批」一无所知——它只提供停下来问一句的机制。所有策略
+ *  （谁能驱使这个 agent、要不要本机主人点头、信任名单）都在宿主（如 gateway 的
+ *  跨机指令同意闸门）里。这与 askBridge 同构：内核给机制，宿主给策略。
+ *
+ *  与 askBridge 的分工：askBridge 是**模型主动**调 AskUserQuestion 工具「问人类」；
+ *  toolGate 是**宿主被动**在工具执行前「拦一道」——模型未必知道自己被审批。
+ * ============================================================
+ */
+
+export interface ToolGateRequest {
+  /** 工具名（如 'Bash' / 'Edit'）。 */
+  name: string;
+  /** 原始参数 JSON 串（宿主可解析出摘要给人类看，如 rm -rf src）。 */
+  argsJson: string;
+  /** 该工具是否只读，供宿主按自己的策略决定是否放行。 */
+  isReadOnly: boolean;
+  /** 本次 tool_call id。 */
+  toolCallId: string;
+  /** 宿主提供的运行作用域；模型参数不能伪造这些身份。 */
+  runContext?: {
+    ownerId: string;
+    conversationKey: string;
+    runId: string;
+    surface: 'desktop' | 'tui' | 'cli' | 'workflow' | 'subagent';
+  };
+  /** 受控工具可提供更细的动作语义，供宿主实施确认策略。 */
+  action?: {
+    kind: string;
+    targetApp?: string;
+    transmitsData?: boolean;
+    irreversible?: boolean;
+    capability?: string;
+  };
+}
+
+export type ToolGateDecision = { allow: true } | { allow: false; reason: string };
+
+/** 工具执行闸门：返回放行或（带原因的）拒绝。缺省不注入 = 全放行（行为不变）。 */
+export type ToolGate = (
+  req: ToolGateRequest,
+  signal?: AbortSignal,
+) => Promise<ToolGateDecision>;