Power Actions

Action 是 Power 的显式业务入口，由 description、可选输入 schema/command/api、超时和 execute 组成。

import { create_action } from "@downcity/city/power";
import { z } from "zod";

const status = create_action({
  description: "Read the current execution scope.",
  input_schema: { zod: z.object({}) },
  timeout_ms: 30_000,
  execute: async ({ context }) => ({
    success: true,
    data: {
      agent_id: context.agent.id,
      workspace_id: context.workspace.id,
      session_id: context.session?.id ?? null,
      turn_id: context.turn?.id ?? null,
      tool_call_id: context.call.tool_call_id ?? null,
    },
  }),
});

每次调用只有一个只读输入 context：它包含受限 City、Agent、Workspace、Session、Turn、 Config 与 Storage 句柄，同时承载本次调用身份。context.call.tool_call_id 是模型协议分配的 工具调用标识（非工具入口为空），context.abort_signal 是本次调用的取消信号。

Action 应把 context.abort_signal 传给网络请求、轮询和长耗时任务。timeout_ms 只触发协作式 取消，底层操作必须响应信号。返回值必须是可 JSON 序列化的 PowerActionResult。

Action 可通过 messages 返回当前 Turn 的附加内容。role: "agent" 的 text/file/data Parts 会写入当前 Agent Message；role: "user" 的 text/context/file Parts 只作为下一模型 Step 的 临时输入，不会伪装成已持久化的 Session Message。Session 领域内统一使用 agent，只有模型协议 边界使用 assistant。

command 只把 Commander 输入映射为 payload；api 只把 HTTP 请求映射为 payload。它们不创建 第二套业务入口，最终都执行同一个 execute。

模型通过 Power 自身的工具调用 Action，工具名即 Power 名。Power 内部可以通过 context.city.powers.run_action() 调用 City 中的其他 Power；应用代码则从 city.powers.scope({ agent_id: agent.id, workspace_id: workspace.id }) 创建明确的执行视图，再调用 run_action()。