@oyasmi/pipiclaw 0.5.5 → 0.5.6

package/README.md

@@ -11,6 +11,7 @@ npm package: [`@oyasmi/pipiclaw`](https://www.npmjs.com/package/@oyasmi/pipiclaw
 - 配置手册：[docs/configuration.md](./docs/configuration.md)
 - 事件与子代理使用指南：[docs/events-and-sub-agents.md](./docs/events-and-sub-agents.md)
 - 部署与运维指南：[docs/deployment-and-operations.md](./docs/deployment-and-operations.md)
+- 安全文档：[docs/security.md](./docs/security.md)
 
 ## 功能特性（Features）
 
@@ -22,6 +23,20 @@ npm package: [`@oyasmi/pipiclaw`](https://www.npmjs.com/package/@oyasmi/pipiclaw
 - 支持预定义子代理（sub-agent）和临时内联子代理（inline sub-agent）
 - 支持立即、单次、周期三类事件调度
 - 支持自定义模型提供方（provider）和模型（model）配置
+- 内置工具层安全防护：`bash` 命令守卫、文件路径守卫、敏感路径拒绝、阻断审计日志
+
+## 安全说明（Security）
+
+Pipiclaw 当前已经内置一轮工具层安全增强：
+
+- `bash` 会拦截明显高风险命令
+- `read` / `write` / `edit` / `attach` 会做统一路径检查
+- 默认允许访问用户主目录中的普通工作文件，但会拒绝常见凭据、私钥、浏览器资料、系统敏感文件等位置
+- 可通过 `~/.pi/pipiclaw/security.json` 做实例级策略调整
+
+如果你要了解默认策略、已知边界、推荐模板和完整配置示例，请直接看：
+
+- [docs/security.md](./docs/security.md)
 
 ## 快速开始（Quickstart）
 
@@ -146,6 +161,14 @@ pipiclaw
     └── sub-agents/
 ```
 
+默认 app home 是 `~/.pi/pipiclaw/`。如果你希望把 Pipiclaw 的所有配置和运行文件放到别处，可以在启动前设置：
+
+```bash
+export PIPICLAW_HOME=/your/custom/pipiclaw-home
+```
+
+设置后，`channel.json`、`auth.json`、`models.json`、`settings.json` 和整个 `workspace/` 都会改为从这个目录读取和写入。
+
 如果 `channel.json` 仍然是初始化模板，程序会提示你补全配置后再启动。这是正常行为。
 
 #### 4. 创建钉钉应用（Create a DingTalk App）
@@ -327,6 +350,8 @@ pipiclaw
 
 ### 配置文件（Config Files）
 
+默认根目录是 `~/.pi/pipiclaw/`；如果设置了 `PIPICLAW_HOME`，下面这些路径都会切换到该目录下。
+
 | 文件 | 用途 |
 |------|------|
 | `~/.pi/pipiclaw/channel.json` | 钉钉应用配置 |
@@ -339,6 +364,7 @@ pipiclaw
 | 变量 | 用途 |
 |----------|------|
 | `ANTHROPIC_API_KEY` | Anthropic API Key |
+| `PIPICLAW_HOME` | 覆盖默认的 `~/.pi/pipiclaw/` 根目录 |
 | `PIPICLAW_DEBUG` | 调试模式，会把上下文写到 `last_prompt.json` |
 | `DINGTALK_FORCE_PROXY` | 设为 `true` 时保留 axios 代理设置 |
 
@@ -512,8 +538,17 @@ npm run check
 
 - `npm run typecheck`
 - `npm run test`
+- `npm run test:e2e`
 - `npm run check`
 
+端到端测试说明：
+
+- `npm run test:e2e` 会运行“除钉钉渠道外”的完整 E2E
+- 它会使用真实 runtime、真实 `ChannelStore`、真实工具/记忆/Sidecar/LLM
+- 只 mock 钉钉传输层，不连接真实钉钉 Stream
+- 运行前需要可用模型凭据：优先读取 `${PIPICLAW_HOME:-~/.pi/pipiclaw}/auth.json`，否则回退到 `ANTHROPIC_API_KEY`
+- E2E 默认不包含在 `npm run test` 中，避免日常测试被真实 LLM 依赖和调用成本影响
+
 ## 许可证（License）
 
 Apache License 2.0. See [LICENSE](./LICENSE).

package/dist/agent/channel-runner.d.ts

@@ -30,6 +30,7 @@ export declare class ChannelRunner implements AgentRunner {
     handleBuiltinCommand(ctx: DingTalkContext, command: BuiltInCommand): Promise<void>;
     queueSteer(text: string, userName?: string): Promise<void>;
     queueFollowUp(text: string, userName?: string): Promise<void>;
+    flushMemoryForShutdown(): Promise<void>;
     abort(): Promise<void>;
     private sendCommandReply;
     private requireQueuedMessage;

package/dist/agent/channel-runner.js

@@ -323,6 +323,9 @@ export class ChannelRunner {
     async queueFollowUp(text, userName) {
         await this.queueBusyMessage("followUp", this.requireQueuedMessage(text, "followup"), userName);
     }
+    async flushMemoryForShutdown() {
+        await this.memoryLifecycle.flushForShutdown();
+    }
     async abort() {
         await this.session.abort();
     }

package/dist/agent/runner-factory.d.ts

@@ -1,3 +1,5 @@
 import type { SandboxConfig } from "../sandbox.js";
 import type { AgentRunner } from "./types.js";
 export declare function getOrCreateRunner(sandboxConfig: SandboxConfig, channelId: string, channelDir: string): AgentRunner;
+export declare function resetRunner(channelId: string): void;
+export declare function resetAllRunners(): void;

package/dist/agent/runner-factory.js

@@ -8,3 +8,9 @@ export function getOrCreateRunner(sandboxConfig, channelId, channelDir) {
     channelRunners.set(channelId, runner);
     return runner;
 }
+export function resetRunner(channelId) {
+    channelRunners.delete(channelId);
+}
+export function resetAllRunners() {
+    channelRunners.clear();
+}

package/dist/agent/types.d.ts

@@ -10,6 +10,7 @@ export interface AgentRunner {
     handleBuiltinCommand(ctx: DingTalkContext, command: BuiltInCommand): Promise<void>;
     queueSteer(text: string, userName?: string): Promise<void>;
     queueFollowUp(text: string, userName?: string): Promise<void>;
+    flushMemoryForShutdown(): Promise<void>;
     abort(): Promise<void>;
 }
 export type FinalOutcome = {

package/dist/memory/lifecycle.d.ts

@@ -2,7 +2,7 @@ import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { Api, Model } from "@mariozechner/pi-ai";
 import type { ExtensionFactory, SessionEntry } from "@mariozechner/pi-coding-agent";
 import type { PipiclawSessionMemorySettings } from "../settings.js";
-export type ConsolidationReason = "compaction" | "new-session" | "idle";
+export type ConsolidationReason = "compaction" | "new-session" | "idle" | "shutdown";
 export interface MemoryLifecycleOptions {
     channelId: string;
     channelDir: string;
@@ -33,6 +33,7 @@ export declare class MemoryLifecycle {
     noteUserTurnStarted(): void;
     noteToolCall(): void;
     noteCompletedAssistantTurn(): void;
+    flushForShutdown(): Promise<void>;
     private clearIdleConsolidationTimer;
     private shouldForceRefreshFor;
     private refreshSessionMemory;

package/dist/memory/lifecycle.js

@@ -73,6 +73,18 @@ export class MemoryLifecycle {
         }
         this.scheduleIdleConsolidation();
     }
+    async flushForShutdown() {
+        this.clearIdleConsolidationTimer();
+        const run = async () => {
+            if (!this.hasPendingAssistantSnapshot()) {
+                return;
+            }
+            await this.runPreflightConsolidation("shutdown");
+        };
+        const resultPromise = this.backgroundQueue.then(run, run);
+        this.backgroundQueue = resultPromise.then(() => undefined, () => undefined);
+        await resultPromise;
+    }
     clearIdleConsolidationTimer() {
         if (!this.idleConsolidationTimer) {
             return;
@@ -84,7 +96,13 @@ export class MemoryLifecycle {
         if (!settings.enabled) {
             return false;
         }
-        return reason === "compaction" ? settings.forceRefreshBeforeCompact : settings.forceRefreshBeforeNewSession;
+        if (reason === "compaction") {
+            return settings.forceRefreshBeforeCompact;
+        }
+        if (reason === "new-session") {
+            return settings.forceRefreshBeforeNewSession;
+        }
+        return false;
     }
     async refreshSessionMemory(request) {
         const settings = this.options.getSessionMemorySettings();

package/dist/paths.js

@@ -1,7 +1,7 @@
 import { homedir } from "os";
 import { join } from "path";
 export const APP_NAME = "pipiclaw";
-export const APP_HOME_DIR = join(homedir(), ".pi", APP_NAME);
+export const APP_HOME_DIR = process.env.PIPICLAW_HOME ?? join(homedir(), ".pi", APP_NAME);
 export const WORKSPACE_DIR = join(APP_HOME_DIR, "workspace");
 export const SUB_AGENTS_DIR_NAME = "sub-agents";
 export const SUB_AGENTS_DIR = join(WORKSPACE_DIR, SUB_AGENTS_DIR_NAME);

package/dist/runtime/bootstrap.d.ts

@@ -1,5 +1,5 @@
 import { type SandboxConfig } from "../sandbox.js";
-import { DingTalkBot, type DingTalkConfig } from "./dingtalk.js";
+import { DingTalkBot, type DingTalkConfig, type DingTalkHandler } from "./dingtalk.js";
 import { ChannelStore } from "./store.js";
 export interface BootstrapPaths {
     appName: string;
@@ -33,6 +33,11 @@ export interface AppContext {
     store: ChannelStore;
     shutdown: () => Promise<void>;
 }
+export interface RuntimeContext {
+    handler: DingTalkHandler;
+    store: ChannelStore;
+    shutdown: (reason?: NodeJS.Signals | "manual") => Promise<void>;
+}
 export declare const DEFAULT_BOOTSTRAP_PATHS: BootstrapPaths;
 export declare class BootstrapExitError extends Error {
     readonly code: number;
@@ -44,4 +49,20 @@ export declare function bootstrapAppHome(paths?: BootstrapPaths): BootstrapResul
 export declare function printBootstrapSummary(result: BootstrapResult, io?: BootstrapIO, paths?: BootstrapPaths): void;
 export declare function loadConfig(paths?: BootstrapPaths, io?: BootstrapIO): DingTalkConfig;
 export declare function parseArgs(argv: string[], paths?: BootstrapPaths, io?: BootstrapIO): ParsedArgs;
+interface RuntimeContextOptions {
+    paths: BootstrapPaths;
+    sandbox: SandboxConfig;
+    dingtalkConfig: DingTalkConfig;
+    createBot?: (handler: DingTalkHandler, config: DingTalkConfig) => DingTalkBot;
+    createEventsWatcher?: (workspaceDir: string, bot: DingTalkBot) => {
+        start(): void;
+        stop(): void;
+    };
+    startServices?: boolean;
+    registerSignalHandlers?: boolean;
+}
+export declare function createRuntimeContext(options: RuntimeContextOptions): RuntimeContext & {
+    bot: DingTalkBot;
+};
 export declare function bootstrap(argv: string[], options?: BootstrapOptions): Promise<AppContext>;
+export {};

package/dist/runtime/bootstrap.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 import { parseBuiltInCommand } from "../agent/commands.js";
 import { getOrCreateRunner } from "../agent/index.js";
+import { resetRunner } from "../agent/runner-factory.js";
 import * as log from "../log.js";
 import { ensureChannelMemoryFilesSync } from "../memory/files.js";
 import { APP_HOME_DIR, APP_NAME, AUTH_CONFIG_PATH, CHANNEL_CONFIG_PATH, MODELS_CONFIG_PATH, SETTINGS_CONFIG_PATH, WORKSPACE_DIR, } from "../paths.js";
@@ -99,6 +100,7 @@ const CHANNEL_CONFIG_TEMPLATE = {
 };
 const MODELS_CONFIG_TEMPLATE = { providers: {} };
 const SHUTDOWN_WAIT_MS = 15000;
+const SHUTDOWN_FLUSH_WAIT_MS = 25000;
 const SHUTDOWN_ABORT_WAIT_MS = 5000;
 export const DEFAULT_BOOTSTRAP_PATHS = {
     appName: APP_NAME,
@@ -269,25 +271,22 @@ function waitForTasks(tasks, timeoutMs) {
         }),
     ]);
 }
-export async function bootstrap(argv, options = {}) {
-    const env = options.env ?? process.env;
-    const io = options.io ?? console;
-    const paths = options.paths ?? DEFAULT_BOOTSTRAP_PATHS;
-    const registerSignalHandlers = options.registerSignalHandlers ?? true;
-    const startServices = options.startServices ?? true;
-    sanitizeProxyEnv(env);
-    const parsedArgs = parseArgs(argv, paths, io);
-    const sandbox = parsedArgs.sandbox;
-    const bootstrapResult = bootstrapAppHome(paths);
-    printBootstrapSummary(bootstrapResult, io, paths);
-    if (bootstrapResult.channelTemplateCreated) {
-        io.error(`Fill in ${paths.channelConfigPath} and run \`${paths.appName}\` again.`);
-        throw new BootstrapExitError(1);
+function flushInactiveChannelMemory(channelStates) {
+    const flushes = [];
+    for (const [channelId, state] of channelStates) {
+        if (state.running) {
+            continue;
+        }
+        flushes.push(state.runner.flushMemoryForShutdown().catch((err) => {
+            log.logWarning(`[${channelId}] Failed to flush memory during shutdown`, err instanceof Error ? err.message : String(err));
+        }));
     }
-    const dingtalkConfig = loadConfig(paths, io);
-    dingtalkConfig.stateDir = paths.workspaceDir;
-    await validateSandbox(sandbox);
-    const store = new ChannelStore({ workingDir: paths.workspaceDir });
+    return flushes;
+}
+export function createRuntimeContext(options) {
+    const startServices = options.startServices ?? true;
+    const registerSignalHandlers = options.registerSignalHandlers ?? true;
+    const store = new ChannelStore({ workingDir: options.paths.workspaceDir });
     const channelStates = new Map();
     const activeTasks = new Set();
     let shuttingDown = false;
@@ -295,11 +294,11 @@ export async function bootstrap(argv, options = {}) {
     const getState = (channelId) => {
         let state = channelStates.get(channelId);
         if (!state) {
-            const channelDir = ensureChannelDir(paths.workspaceDir, channelId);
+            const channelDir = ensureChannelDir(options.paths.workspaceDir, channelId);
             ensureChannelMemoryFilesSync(channelDir);
             state = {
                 running: false,
-                runner: getOrCreateRunner(sandbox, channelId, channelDir),
+                runner: getOrCreateRunner(options.sandbox, channelId, channelDir),
                 stopRequested: false,
             };
             channelStates.set(channelId, state);
@@ -405,10 +404,13 @@ export async function bootstrap(argv, options = {}) {
             }
         },
     };
-    log.logStartup(paths.workspaceDir, sandbox.type === "host" ? "host" : `docker:${sandbox.container}`);
-    const bot = new DingTalkBot(handler, dingtalkConfig);
-    const eventsWatcher = createEventsWatcher(paths.workspaceDir, bot);
-    const shutdownWithReason = async (reason) => {
+    const bot = options.createBot
+        ? options.createBot(handler, options.dingtalkConfig)
+        : new DingTalkBot(handler, options.dingtalkConfig);
+    const eventsWatcher = options.createEventsWatcher
+        ? options.createEventsWatcher(options.paths.workspaceDir, bot)
+        : createEventsWatcher(options.paths.workspaceDir, bot);
+    const shutdownWithReason = async (reason = "manual") => {
         if (shutdownPromise) {
             return shutdownPromise;
         }
@@ -443,6 +445,17 @@ export async function bootstrap(argv, options = {}) {
                     }
                 }
             }
+            const flushes = flushInactiveChannelMemory(channelStates);
+            if (flushes.length > 0) {
+                log.logInfo(`Flushing memory for ${flushes.length} inactive channel(s) before shutdown`);
+                const flushed = await waitForTasks(flushes, SHUTDOWN_FLUSH_WAIT_MS);
+                if (!flushed) {
+                    log.logWarning(`Shutdown memory flush exceeded ${SHUTDOWN_FLUSH_WAIT_MS}ms`);
+                }
+            }
+            for (const channelId of channelStates.keys()) {
+                resetRunner(channelId);
+            }
         })();
         return shutdownPromise;
     };
@@ -463,10 +476,43 @@ export async function bootstrap(argv, options = {}) {
         void bot.start();
     }
     return {
-        bot,
+        handler,
         store,
+        bot,
+        shutdown: shutdownWithReason,
+    };
+}
+export async function bootstrap(argv, options = {}) {
+    const env = options.env ?? process.env;
+    const io = options.io ?? console;
+    const paths = options.paths ?? DEFAULT_BOOTSTRAP_PATHS;
+    const registerSignalHandlers = options.registerSignalHandlers ?? true;
+    const startServices = options.startServices ?? true;
+    sanitizeProxyEnv(env);
+    const parsedArgs = parseArgs(argv, paths, io);
+    const sandbox = parsedArgs.sandbox;
+    const bootstrapResult = bootstrapAppHome(paths);
+    printBootstrapSummary(bootstrapResult, io, paths);
+    if (bootstrapResult.channelTemplateCreated) {
+        io.error(`Fill in ${paths.channelConfigPath} and run \`${paths.appName}\` again.`);
+        throw new BootstrapExitError(1);
+    }
+    const dingtalkConfig = loadConfig(paths, io);
+    dingtalkConfig.stateDir = paths.workspaceDir;
+    await validateSandbox(sandbox);
+    log.logStartup(paths.workspaceDir, sandbox.type === "host" ? "host" : `docker:${sandbox.container}`);
+    const runtime = createRuntimeContext({
+        paths,
+        sandbox,
+        dingtalkConfig,
+        registerSignalHandlers,
+        startServices,
+    });
+    return {
+        bot: runtime.bot,
+        store: runtime.store,
         shutdown: async () => {
-            await shutdownWithReason("manual");
+            await runtime.shutdown("manual");
         },
     };
 }

package/dist/security/command-guard.d.ts

@@ -0,0 +1,16 @@
+import type { CommandGuardResult, SecurityConfig } from "./types.js";
+interface ParsedCommand {
+    command: string;
+    args: string[];
+    normalized: string;
+}
+declare function splitCommandChain(command: string): string[];
+declare function parseShellWords(command: string): string[];
+declare function parseCommand(command: string): ParsedCommand | null;
+export declare function guardCommand(command: string, config: SecurityConfig["commandGuard"]): CommandGuardResult;
+export declare const internalCommandGuard: {
+    parseShellWords: typeof parseShellWords;
+    parseCommand: typeof parseCommand;
+    splitCommandChain: typeof splitCommandChain;
+};
+export {};