Pi SDK 学习笔记（三）：工具面与安全边界

// 1. allowlist：只启用名单里的工具（自定义工具名也要写进去）
const { session } = await createAgentSession({
  tools: ["read", "grep", "find", "ls"],
});

// 2. denylist：在当前可用集合上再剔除
const { session: s2 } = await createAgentSession({
  excludeTools: ["ask_question"],
});

// 3. 关掉整类
// noTools: "all"     —— 全部关掉
// noTools: "builtin" —— 只关默认内置，保留扩展/自定义工具

read, grep, find, ls, project_status

// lessons/03-tools-and-safety/tool-surface.ts（节选）
const READ_ONLY_BUILTINS = ["read", "grep", "find", "ls"] as const;
const WRITE_BUILTINS = ["edit", "write"] as const;
// bash 被故意排除：长时间运行的 Web 服务不能把任意 shell 交给模型
const FORBIDDEN_BUILTINS = ["bash"] as const;

export function buildToolSurface(config: ToolSurfaceConfig): ToolSurface {
  const cwd = path.resolve(config.workspace); // 服务端解析为绝对路径
  const customTools = [
    createProjectStatusTool(cwd),
    createReadTicketTool(config.authorizedTicketIds ?? ["TICKET-1", "TICKET-2", "TICKET-42"]),
    createSearchDocsTool(config.docsDir),
  ];

  const tools: string[] = [
    ...READ_ONLY_BUILTINS,
    "project_status",
    "read_ticket",
    "search_docs",
  ];
  if (config.enableWriteTools) tools.push(...WRITE_BUILTINS);

  // belt-and-suspenders：禁用工具永远不能混进 allowlist
  for (const name of tools) {
    if ((FORBIDDEN_BUILTINS as readonly string[]).includes(name)) {
      throw new Error(`Internal error: forbidden tool in surface: ${name}`);
    }
  }

  return { cwd, tools, customTools };
}

export function createToolSurfaceResolver(config: ToolSurfaceConfig) {
  const surface = buildToolSurface(config);
  return function resolveToolSurface(clientCwd?: unknown): ToolSurface {
    if (clientCwd !== undefined) {
      throw new Error(
        "Client-supplied cwd is not permitted; the workspace is server-resolved.",
      );
    }
    return surface;
  };
}

import { Type } from "typebox";
import { defineTool } from "@earendil-works/pi-coding-agent";

const myTool = defineTool({
  name: "my_tool",
  label: "My Tool",
  description: "Does something useful",
  parameters: Type.Object({
    input: Type.String({ description: "Input value" }),
  }),
  execute: async (_toolCallId, params) => ({
    content: [{ type: "text", text: `Result: ${params.input}` }],
    details: {},
  }),
});

description:
  "Read a support ticket by its id. The id must look like TICKET-NNNN (1-6 digits). " +
  "Only tickets on the server-configured allowlist can be read; other ids are rejected " +
  "even if they match the id format.",

export const READ_TICKET_ID_PATTERN = "^TICKET-[0-9]{1,6}$";
export const readTicketParameters = Type.Object({
  id: Type.String({ pattern: READ_TICKET_ID_PATTERN }),
});

export function assertAuthorizedTicket(
  id: string,
  authorizedIds: ReadonlySet<string>,
): void {
  if (!authorizedIds.has(id)) {
    // schema 放行的 id 仍可能不在 allowlist 里
    throw new Error(`Unauthorized ticket: ${id}`);
  }
}

export function runReadTicket(
  id: string,
  authorizedIds: ReadonlySet<string>,
): AgentToolResult<{ id: string }> {
  assertAuthorizedTicket(id, authorizedIds);
  return {
    content: [textBlock(`Ticket ${id}: (synthetic body for lesson 3 demo)`)],
    details: { id },
  };
}

// schema 放行
expect(Check(readTicketParameters, { id: "TICKET-999" })).toBe(true);
// 授权层拒绝
expect(() => runReadTicket("TICKET-999", authorized)).toThrow(/Unauthorized ticket/);

export function createProjectStatusTool(workspace: string): ToolDefinition {
  return defineTool({
    name: "project_status",
    label: "Project status",
    description:
      "Report whether the configured project workspace exists and is a directory. " +
      "Takes no arguments; the workspace path is server-configured and never read from input.",
    parameters: projectStatusParameters,
    execute: async () => runProjectStatus(workspace),
  });
}

[surface] read-only tools : read, grep, find, ls, project_status, read_ticket, search_docs
[surface] write-enabled    : read, grep, find, ls, project_status, read_ticket, search_docs, edit, write
[surface] bash in either?  : false

export const searchDocsParameters = Type.Object({
  query: Type.String({ minLength: 2, maxLength: 100 }),
});

export function validateSearchQuery(raw: string): string {
  const query = raw.trim();
  if (query.length < 2 || query.length > 100) {
    throw new Error(`query length must be 2..100 chars after trim (got ${query.length})`);
  }
  return query;
}

// 1. query 只当文本关键词，绝不拼进路径
const needle = query.toLowerCase();

// 2. 枚举时跳过符号链接，防 symlink 指到目录外
if (entry.isSymbolicLink()) continue;

// 3. 每个结果再用 isPathInside 收口
if (!isPathInside(docsDir, abs)) continue;

// 4. 对外只返回相对路径
const rel = path.relative(docsDir, abs);

export function isPathInside(parent: string, child: string): boolean {
  const rel = path.relative(parent, child);
  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
}

// 目录外有匹配文件；query 长得像路径穿越，也只是文本搜索
await writeFile(path.join(outsideDir, "secret.md"), "outside secret");
expect(await searchDocs(docsDir, "../outside/secret")).toEqual([]);
expect(await searchDocs(docsDir, "outside secret")).toEqual([]);

// docsDir 里的 symlink 指向目录外 → 跳过，不跟随
await symlink(outsideDir, path.join(docsDir, "link"), "dir");
expect(await searchDocs(docsDir, "matchme")).toEqual([]);

case "tool_execution_start":
  console.log(`\n[tool] ${event.toolName} start`);
  break;
case "tool_execution_end":
  console.log(`\n[tool] ${event.toolName} end (error=${event.isError})`);
  break;

const tools = ["read", "grep", "find", "ls", "project_status"];
if (config.enableWriteTools) tools.push("edit", "write");
// 没有 bash

pi.on("tool_call", (event) => {
  // Do not log arguments: they may contain source code or secrets.
  console.info(JSON.stringify({ kind: "tool_call", toolName: event.toolName }));
  return undefined;
});

npx vitest run lessons/03-tools-and-safety/tools.test.ts

npm run lesson:03:smoke
# 演示写工具
ENABLE_WRITE_TOOLS=true npm run lesson:03:smoke

npm run lesson:03:homework