a ctfer on the load

1
/** Build the ordered, independently replaceable sections of the structured system prompt. */
2
export function buildSystemPromptSections(input: BuildSystemPromptOptions): SystemPromptSections {
3
  const options = normalizeBuildSystemPromptOptions(input);
4
  const {
5
    customPrompt,
6
    selectedTools,
7
    hiddenTools,
8
    toolSnippets,
9
    toolGuidelines,
10
    promptGuidelines,
11
    appendSystemPrompt,
12
    sections: customSections,
13
    cwd,
14
    contextFiles,
15
    skills,
16
  } = options;
17

18
  for (const name of Object.keys(customSections)) {
19
    if (!SYSTEM_PROMPT_SECTION_NAME.test(name) || name === "preamble") {
20
      throw new Error(`Invalid system prompt section name: ${name}`);
21
    }
22
  }
23

24
  const declaredTools = selectedTools.filter((name) => !hiddenTools.includes(name));
25
  const promptSections: Record<string, string> = {};
26
  if (customPrompt) {
27
    promptSections.preamble = customPrompt;
28
  } else {
29
    promptSections.preamble =
30
      "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
31
    const visibleTools = declaredTools.filter((name) => !!toolSnippets[name]);
32
    const tools =
33
      visibleTools.length > 0 ? visibleTools.map((name) => `- ${name}: ${toolSnippets[name]}`).join("\n") : "(none)";
34
    promptSections.tools = `${tools}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.`;
35
    promptSections.rules = buildRules(declaredTools, toolGuidelines, promptGuidelines);
36
    promptSections.docs = `Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
37
- Main documentation: ${getReadmePath()}
38
- Additional docs: ${getDocsPath()}
39
- Examples: ${getExamplesPath()} (extensions, custom tools, SDK)
40
- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
41
- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md), MCP servers (docs/mcp.md), codemode scripts and non-LLM models such as classifiers and image models (docs/codemode.md)
42
- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
43
- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
44
  }
45

46
  if (appendSystemPrompt) promptSections.addendum = appendSystemPrompt;
47
  if (contextFiles.length > 0) promptSections.project_context = renderProjectContext(contextFiles);
48
  // A hidden reader is still reachable through another tool, so skills stay but the hint names no tool.
49
  const readers = ["read", "bash"] as const;
50
  const skillFileReadTool =
51
    readers.find((tool) => declaredTools.includes(tool)) ??
52
    (readers.some((tool) => selectedTools.includes(tool)) ? "indirect" : undefined);
53
  if (skillFileReadTool && skills.length > 0) {
54
    const skillsPrompt = formatSkillsForPrompt(skills, skillFileReadTool).trim();
55
    if (skillsPrompt) promptSections.skills = skillsPrompt;
56
  }
57
  promptSections.cwd = cwd.replace(/\\/g, "/");
58
  for (const [name, content] of Object.entries(customSections)) {
59
    if (content) promptSections[name] = content;
60
  }
61

62
  const sections: SystemPromptSections = { preamble: promptSections.preamble };
63
  for (const [name, content] of Object.entries(promptSections)) {
64
    if (name !== "preamble") sections[name] = `<${name}>\n${content}\n</${name}>`;
65
  }
66
  return sections;
67
}

1
<skill>
2
    <name>bun-dev</name>
3
    <description>This skill should be used when working with Bun runtime, bun:sqlite, Bun.serve, bun:test, or when &quot;Bun&quot;, &quot;bun:test&quot;, or Bun-specific patterns are mentioned.</description>
4
    <location>/Users/zsm/.pi/agent/skills/bun-dev/SKILL.md</location>
5
  </skill>

1
---
2
name: bun-dev
3
description: This skill should be used when working with Bun runtime, bun:sqlite, Bun.serve, bun:test, or when "Bun", "bun:test", or Bun-specific patterns are mentioned.
4
metadata:
5
  version: "1.0.0"
6
---

1
You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
2

3
<tools>
4
- read: Read file contents
5
- bash: Execute bash commands (ls, grep, find, etc.)
6
- edit: Make precise file edits with exact text replacement, including multiple disjoint edits in one call
7
- write: Create or overwrite files
8

9
In addition to the tools above, you may have access to other custom tools depending on the project.
10
</tools>
11

12
<rules>
13
- Use bash for file operations like ls, rg, find
14
- Use read to examine files instead of cat or sed.
15
- You can inspect PI_* environment variables for current model and session details.
16
- Use edit for precise changes (edits[].oldText must match exactly)
17
- When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls
18
- Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.
19
- Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.
20
- Use write only for new files or complete rewrites.
21
- Be concise in your responses
22
- Show file paths clearly when working with files
23
</rules>
24

25
<docs>
26
Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
27
- Main documentation:
28
- Additional docs:
29
- Examples: /pi/packages/coding-agent/examples (extensions, custom tools, SDK)
30
- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
31
- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md), MCP servers (docs/mcp.md), codemode scripts and non-LLM models such as classifiers and image models (docs/codemode.md)
32
- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
33
- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)
34
</docs>
35

36
<cwd>
37

38
</cwd>

1
system
2
└── preamble / tools / rules / docs / project_context / skills / cwd / 扩展段
3
user：帮我看看目录下原生pi的默认提示词在那个文件夹
4
assistant：思考 + toolCall(read/bash)
5
toolResult：文件内容
6
user：对目录下代码进行审计
7
...

1
/**
2
 * Render a later system message for APIs that accept system messages mid-conversation.
3
 * Section changes are framed by name so the model can relate them to the leading prompt.
4
 * This framing is request-time only and may change between versions.
5
 */
6
export function renderSystemMessageUpdate(message: SystemMessage): string {
7
  const parts: string[] = [];
8
  const text = contentText(message.content);
9
  if (text.length > 0) parts.push(text);
10
  for (const [name, value] of Object.entries(message.sections ?? {})) {
11
    parts.push(
12
      value === null
13
        ? `Removed system prompt section "${name}".`
14
        : `Updated system prompt section "${name}":\n\n${value}`,
15
    );
16
  }
17
  return parts.join("\n\n");
18
}

1
/** Wrap a ToolDefinition into an AgentTool for the core runtime. */
2
export function wrapToolDefinition<TDetails = unknown>(
3
  definition: ToolDefinition<any, TDetails>,
4
  ctxFactory?: ToolContextFactory,
5
): AgentTool<any, TDetails> {
6
  return {
7
    name: definition.name,
8
    label: definition.label,
9
    description: definition.description,
10
    parameters: definition.parameters,
11
    outputSchema: definition.outputSchema,
12
    constrainedSampling: definition.constrainedSampling,
13
    prepareArguments: definition.prepareArguments,
14
    executionMode: definition.executionMode,
15
    execute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionToolContext) =>
16
      definition.execute(
17
        toolCallId,
18
        params,
19
        signal,
20
        onUpdate,
21
        ctx ?? (ctxFactory?.(toolCallId, signal) as ExtensionToolContext),
22
      ),
23
  };
24
}
25

26
export function createToolDefinitionFromAgentTool(tool: AgentTool<any>): ToolDefinition<any, unknown> {
27
  return {
28
    name: tool.name,
29
    label: tool.label,
30
    description: tool.description,
31
    parameters: tool.parameters as any,
32
    outputSchema: tool.outputSchema,
33
    constrainedSampling: tool.constrainedSampling,
34
    prepareArguments: tool.prepareArguments,
35
    executionMode: tool.executionMode,
36
    execute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),
37
  };
38
}

1
export function createInitialSystemMessage(
2
  systemPrompt: string | undefined,
3
  tools: Tool[] | undefined,
4
): SystemMessage | undefined {
5
  const hasSystemPrompt = systemPrompt !== undefined && systemPrompt.length > 0;
6
  const hasTools = tools !== undefined && tools.length > 0;
7
  if (!hasSystemPrompt && !hasTools) return undefined;
8
  return {
9
    role: "system",
10
    content: systemPrompt ?? "",
11
    ...(hasTools ? { toolsAdded: tools } : {}),
12
    timestamp: 0,
13
  };
14
}

1
function declareToolChanges(context: AgentContext, pendingMessages: AgentMessage[]): AgentMessage[] {
2
  let systemIndex = -1;
3
  for (let i = pendingMessages.length - 1; i >= 0; i--) {
4
    if (pendingMessages[i].role === "system") {
5
      systemIndex = i;
6
      break;
7
    }
8
  }
9
  const pending = pendingMessages[systemIndex] as SystemMessage | undefined;
10
  const baseline = pending
11
    ? pendingMessages.map((message, index) =>
12
        index === systemIndex ? withToolChanges(pending, NO_CHANGES) : message,
13
      )
14
    : pendingMessages;
15
  const changes = getToolStateChanges(
16
    getCurrentTools([...context.messages, ...baseline]),
17
    (context.tools ?? []).map(toToolDeclaration),
18
  );
19
  const unchanged = changes.toolsAdded.length === 0 && changes.toolsRemoved.length === 0;
20

21
  if (pending) {
22
    // Keep the caller's message object when it already declares no tool changes.
23
    if (unchanged && !pending.toolsAdded?.length && !pending.toolsRemoved?.length) return pendingMessages;
24
    return baseline.map((message, index) => (index === systemIndex ? withToolChanges(pending, changes) : message));
25
  }
26
  if (unchanged) return pendingMessages;
27
  const update = withToolChanges({ role: "system", content: "", timestamp: Date.now() }, changes);
28
  const insertIndex = pendingMessages.findIndex((message) => message.role !== "system");
29
  const index = insertIndex === -1 ? pendingMessages.length : insertIndex;
30
  return [...pendingMessages.slice(0, index), update, ...pendingMessages.slice(index)];
31
}

1
function convertTools(
2
  tools: Tool[],
3
  isOAuthToken: boolean,
4
  supportsEagerToolInputStreaming: boolean,
5
  supportsStrictTools: boolean,
6
  cacheControl?: CacheControlEphemeral,
7
): BetaTool[] {
8
  if (!tools) return [];
9

10
  return tools.map((tool, index) => {
11
    const strict = resolveJsonSchemaStrictSampling(tool, supportsStrictTools, isAnthropicStrictUnsupportedKeyword);
12
    const parameters = getJsonSchemaToolParameters(tool, strict);
13
    const schema = parameters as { properties?: unknown; required?: string[] };
14
    const legacyInputSchema = {
15
      type: "object" as const,
16
      properties: schema.properties ?? {},
17
      required: schema.required ?? [],
18
    };
19
    const inputSchema =
20
      strict === true
21
        ? {
22
            ...(parameters as Record<string, unknown>),
23
            ...legacyInputSchema,
24
          }
25
        : legacyInputSchema;
26

27
    return {
28
      name: isOAuthToken ? toClaudeCodeName(tool.name) : tool.name,
29
      description: tool.description,
30
      ...(supportsEagerToolInputStreaming ? { eager_input_streaming: true } : {}),
31
      ...(strict === true ? { strict: true } : {}),
32
      input_schema: inputSchema,
33
      ...(cacheControl && index === tools.length - 1 ? { cache_control: cacheControl } : {}),
34
    };
35
  });
36
}

1
if (toolCalls.length > 0) {
2
        // A "length" stop means the output was cut off by the token limit, so
3
        // every tool call in the message may carry truncated arguments. Fail
4
        // them all instead of executing potentially borked calls.
5
        const executedToolBatch =
6
          message.stopReason === "length"
7
            ? await failToolCallsFromTruncatedMessage(toolCalls, emit)
8
            : await executeToolCalls(currentContext, message, config, signal, emit);
9
        toolResults.push(...executedToolBatch.messages);
10
        hasMoreToolCalls = !executedToolBatch.terminate;
11

12
        for (const result of toolResults) {
13
          currentContext.messages.push(result);
14
          newMessages.push(result);
15
        }
16
      }

1
function prepareToolCallArguments(tool: AgentTool<any>, toolCall: AgentToolCall): AgentToolCall {
2
  if (!tool.prepareArguments) {
3
    return toolCall;
4
  }
5
  const preparedArguments = tool.prepareArguments(toolCall.arguments);
6
  if (preparedArguments === toolCall.arguments) {
7
    return toolCall;
8
  }
9
  return {
10
    ...toolCall,
11
    arguments: preparedArguments as Record<string, any>,
12
  };
13
}

1
export function validateToolArguments(tool: Tool, toolCall: ToolCall): any {
2
  const args = structuredClone(toolCall.arguments);
3
  normalizeOptionalNulls(args, tool.parameters as JsonSchemaObject);
4
  Value.Convert(tool.parameters, args);
5

6
  const validator = getValidator(tool.parameters);
7
  if (!Object.getOwnPropertySymbols(tool.parameters).includes(TYPEBOX_KIND)) {
8
    const coerced = coerceWithJsonSchema(args, tool.parameters as JsonSchemaObject);
9
    if (coerced !== args) {
10
      if (typeof args === "object" && args !== null && typeof coerced === "object" && coerced !== null) {
11
        for (const key of Object.keys(args)) {
12
          delete args[key];
13
        }
14
        Object.assign(args, coerced);
15
      } else {
16
        return validator.Check(coerced) ? coerced : args;
17
      }
18
    }
19
  }
20

21
  if (validator.Check(args)) {
22
    return args;
23
  }
24

25
  const errors =
26
    validator
27
      .Errors(args)
28
      .map((error) => `  - ${formatValidationPath(error)}: ${error.message}`)
29
      .join("\n") || "Unknown validation error";
30

31
  const errorMessage = `Validation failed for tool "${toolCall.name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}`;
32

33
  throw new Error(errorMessage);
34
}

1
async function executePreparedToolCall(
2
  prepared: PreparedToolCall,
3
  signal: AbortSignal | undefined,
4
  onUpdate: ToolUpdateSink,
5
): Promise<ExecutedToolCallOutcome> {
6
  const updateEvents: Promise<void>[] = [];
7
  let acceptingUpdates = true;
8
  const startedAt = performance.now();
9
  const elapsed = () => Math.round(performance.now() - startedAt);
10

11
  try {
12
    const result = await prepared.tool.execute(
13
      prepared.toolCall.id,
14
      prepared.args as never,
15
      signal,
16
      (partialResult) => {
17
        if (!acceptingUpdates) return;
18
        updateEvents.push(Promise.resolve(onUpdate(partialResult)));
19
      },
20
    );
21
    const durationMs = elapsed();
22
    acceptingUpdates = false;
23
    await Promise.all(updateEvents);
24
    return { result, isError: result.isError === true, durationMs };
25
  } catch (error) {
26
    const durationMs = elapsed();
27
    acceptingUpdates = false;
28
    await Promise.all(updateEvents);
29
    return {
30
      result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
31
      isError: true,
32
      durationMs,
33
    };
34
  } finally {
35
    acceptingUpdates = false;
36
  }
37
}

1
function shouldTerminateToolBatch(finalizedCalls: FinalizedToolCallOutcome[]): boolean {
2
  return finalizedCalls.length > 0 && finalizedCalls.every((finalized) => finalized.result.terminate === true);
3
}

1
   tool_search / codemode      → 改变"能看到什么"
2
   exposure + hiddenDeclarations → 决定"声明什么"
3
   transcript system messages  → 记录"声明过什么"（可回放）
4
   agent-loop executeToolCalls → 决定"怎么跑"
5
   runToolCall                 → 嵌套调用复用同一条管道
6
   before/afterToolCall hooks  → 拦截点（权限、结果改写）

1
export function anthropicProvider(): Provider<"anthropic-messages"> {
2
  return createProvider({
3
    id: "anthropic",
4
    name: "Anthropic",
5
    baseUrl: "https://api.anthropic.com",
6
    auth: {
7
      apiKey: anthropicApiKeyAuth(),
8
      oauth: lazyOAuth({
9
        name: "Anthropic (Claude Pro/Max)",
10
        isSubscription: true,
11
        load: loadAnthropicOAuth,
12
      }),
13
    },
14
    models: Object.values(ANTHROPIC_MODELS),
15
    api: anthropicMessagesApi(),
16
  });
17
}

1
function detectCompat(model: Model<"openai-completions">): ResolvedOpenAICompletionsCompat {
2
  const provider = model.provider;
3
  const baseUrl = model.baseUrl;
4

5
  const isZai =
6
    provider === "zai" ||
7
    provider === "zai-coding-cn" ||
8
    baseUrl.includes("api.z.ai") ||
9
    baseUrl.includes("open.bigmodel.cn");
10
  const isTogether =
11
    provider === "together" || baseUrl.includes("api.together.ai") || baseUrl.includes("api.together.xyz");
12
  const isMoonshot = provider === "moonshotai" || provider === "moonshotai-cn" || baseUrl.includes("api.moonshot.");
13
  const isOpenRouter = provider === "openrouter" || baseUrl.includes("openrouter.ai");
14
  const isCloudflareWorkersAI = provider === "cloudflare-workers-ai" || baseUrl.includes("api.cloudflare.com");
15
  const isCloudflareAiGateway = provider === "cloudflare-ai-gateway" || baseUrl.includes("gateway.ai.cloudflare.com");
16
  const isNvidia = provider === "nvidia" || baseUrl.includes("integrate.api.nvidia.com");
17
  const isAntLing = provider === "ant-ling" || baseUrl.includes("api.ant-ling.com");
18
  const isCerebras = provider === "cerebras" || baseUrl.includes("cerebras.ai");
19
  const isDeepSeek = provider === "deepseek" || baseUrl.toLowerCase().includes("deepseek.com");

1
function getCompat(model: Model<"openai-completions">): ResolvedOpenAICompletionsCompat {
2
  const detected = detectCompat(model);
3
  if (!model.compat) return detected;
4

5
  return {
6
    supportsStore: model.compat.supportsStore ?? detected.supportsStore,
7
    supportsDeveloperRole: model.compat.supportsDeveloperRole ?? detected.supportsDeveloperRole,
8
    supportsReasoningEffort: model.compat.supportsReasoningEffort ?? detected.supportsReasoningEffort,
9
    supportsUsageInStreaming: model.compat.supportsUsageInStreaming ?? detected.supportsUsageInStreaming,
10
    supportsFinishReason: model.compat.supportsFinishReason ?? detected.supportsFinishReason,

1
  if (compat.thinkingFormat === "zai" && model.reasoning) {
2
    const zaiParams = params as Omit<typeof params, "reasoning_effort"> & {
3
      thinking?: { type: "enabled" | "disabled"; clear_thinking?: boolean };
4
      reasoning_effort?: string;
5
    };
6
    zaiParams.thinking = options?.reasoningEffort ? { type: "enabled", clear_thinking: false } : { type: "disabled" };
7
    if (options?.reasoningEffort && compat.supportsReasoningEffort) {
8
      const mappedEffort = model.thinkingLevelMap?.[options.reasoningEffort];
9
      const effort = mappedEffort === undefined ? options.reasoningEffort : mappedEffort;
10
      if (typeof effort === "string") {
11
        zaiParams.reasoning_effort = effort;
12
      }
13
    }
14
  }

1
export function lazyStream(
2
  model: Model<Api>,
3
  setup: () => Promise<AsyncIterable<AssistantMessageEvent>>,
4
): AssistantMessageEventStream {
5
  const startedAt = Date.now();
6
  const outer = new AssistantMessageEventStream();
7

8
  setup()
9
    .then((inner) => forwardStream(outer, inner))
10
    .catch((error) => {
11
      const message = createSetupErrorMessage(model, error, startedAt);
12
      outer.push({ type: "error", reason: "error", error: message });
13
      outer.end(message);
14
    });
15

16
  return outer;
17
}

1
   export type Api = KnownApi | (string & {});
2
   export type ImageApi = KnownImageApi | (string & {});
3
   export type ClassifierApi = KnownClassifierApi | (string & {});