diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c23cf7ae..eee8f442 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,7 @@ If you use an agent, run it from the repository root directory so it picks up `A ## Issue Review -Issues submitted Friday through Sunday are not guaranteed to be reviewed. If something is urgent, ask on Discord: https://discord.com/invite/3cU7Bz4UPx +Issues submitted Friday through Sunday are not guaranteed to be reviewed. If something is urgent, say so at the top of the issue and explain the impact. ## Quality Bar For Issues @@ -108,7 +108,7 @@ If you are adding a new provider to `packages/providers`, see `AGENTS.md` for re ### Why are weekend issues lower priority? -We triage the tracker during working hours. That means more issues can accumulate over the weekend. Anything submitted Friday through Sunday may be missed or given lower priority in the Monday review queue. If a problem is urgent, ask on Discord and include the short version, a repro, and the relevant logs. +We triage the tracker during working hours. That means more issues can accumulate over the weekend. Anything submitted Friday through Sunday may be missed or given lower priority in the Monday review queue. If a problem is urgent, flag it in the issue and include the short version, a repro, and the relevant logs. ### Why do some issues get no reply? diff --git a/docs/plan-loop-cron-workflow-hoh.md b/docs/plan-loop-cron-workflow-hoh.md index b0f8dfec..605fa615 100644 --- a/docs/plan-loop-cron-workflow-hoh.md +++ b/docs/plan-loop-cron-workflow-hoh.md @@ -17,7 +17,7 @@ Step 目前擅长在一个 turn 内完成工作，也已经有 session、subagen | Cron | 在指定时间执行提醒或任务 | project/session 可见 | `durable=true` 时跨 session | | Workflow | 一次调用编排多个 agent 和阶段 | 单次 run，可 resume | run journal 与产物落盘 | -三者都可以把通知送入 Pi 已有的 custom-message/steer 通道，但共享通道不等于 +三者都可以把通知送入运行时已有的 custom-message/steer 通道，但共享通道不等于 共享生命周期或共享实现。任一方向都必须能够在没有另外两个方向时编译、加载、测试 和关闭。 diff --git a/docs/step-configuration.md b/docs/step-configuration.md index 5291256e..201bed16 100644 --- a/docs/step-configuration.md +++ b/docs/step-configuration.md @@ -14,7 +14,7 @@ The retired `step-settings.json` and `settings.json` files are no longer read, written, or covered by the project trust prompt. A project that still ships one is ignored; move any settings it holds into the project `config.toml`. -There is no automatic import from the pre-pi `config.json` layout. `models.json` +There is no automatic import from the legacy pre-Step `config.json` layout. `models.json` and `auth.json` keep their own formats — they hold model definitions and credentials, not settings — and a stale Step endpoint recorded in `models.json` by an older release is still repaired in place at startup. diff --git a/docs/step-unified-config-and-mcp.md b/docs/step-unified-config-and-mcp.md index d34c99a2..c38ed27d 100644 --- a/docs/step-unified-config-and-mcp.md +++ b/docs/step-unified-config-and-mcp.md @@ -15,7 +15,7 @@ | 来源 | 内容 | | --- | --- | -| `~/.stepcode/agent/settings.json` | Pi 原生设置(主题、默认 provider/model、thinking、compaction…) | +| `~/.stepcode/agent/settings.json` | 运行时原生设置(主题、默认 provider/model、thinking、compaction…) | | `~/.stepcode/agent/step-settings.json` | Step 产品设置(permissionPreset、approvalMode、autoResume、feedbackEnabled…) | | 无 | MCP 没有配置位置 | @@ -26,12 +26,12 @@ /.stepcode/config.toml # 项目级(可选) ``` -三类内容并存于同一文档:Pi 原生设置在根表,Step 产品设置在根表,MCP 在 +三类内容并存于同一文档:运行时原生设置在根表,Step 产品设置在根表,MCP 在 `[mcp_servers.]` 子表(Codex 风格)。 关键点: -- **单一真相**:`createStepSettingsManager` 把 Pi 的 `SettingsManager` 与 Step +- **单一真相**:`createStepSettingsManager` 把 运行时的 `SettingsManager` 与 Step 装饰器指向同一份路径。任何在 CLI 内改的设置(`/theme`、权限预设、审批模式等) 都写回 `~/.stepcode/config.toml`,`step` 二进制**不再创建** `settings.json`。 - **项目文件可选**:缺失即"无项目级设置",不报警告、不自动创建;只有显式保存 @@ -127,12 +127,12 @@ - `readStepConfig(path)` —— `readFileSync` 放在 `try` **之外**,让 `ENOENT` 原样 抛出,调用方才能区分"文件不存在"和"TOML 非法"。 - `writeStepConfig(path, doc)` —— 写 `path..tmp` 再 `renameSync`,保证原子。 -- `readGlobalStepDefaults(env)` —— 在 Pi 的 SettingsManager 建立之前同步读取 +- `readGlobalStepDefaults(env)` —— 在 运行时的 SettingsManager 建立之前同步读取 `defaultProvider` / `defaultModel` / `telemetry.*`。这一步必须存在:静默丢弃 `telemetry.enabled = false` 等于把用户关掉的上报又打开。 - `updateGlobalMcpConfig(env, fn)` —— 读改写整体包在 `acquireSettingsLockSync` 内。 -- `StepTomlSettingsStorage` —— 实现 Pi 的 `SettingsStorage` 接口,把 TOML 文档 - (剥掉 `mcp_servers`)以 JSON 字符串形式交给 Pi,写回时再把 `mcp_servers` +- `StepTomlSettingsStorage` —— 实现 运行时的 `SettingsStorage` 接口,把 TOML 文档 + (剥掉 `mcp_servers`)以 JSON 字符串形式交给运行时,写回时再把 `mcp_servers` 合并回去。 ### 3.2 `src/step/mcp.ts`(+294 行) @@ -239,7 +239,7 @@ if (ctx.mode !== "tui") await startup; // 仅 TUI 分离 ### 4.2 设置写入与 `mcp_servers` 互相覆盖 -Pi 的 `SettingsStorage.withLock` 只认识"设置"这一层,它拿到的字符串里没有 +运行时的 `SettingsStorage.withLock` 只认识"设置"这一层,它拿到的字符串里没有 `mcp_servers`。如果读、改、写不在同一个临界区,另一个会话在中间写入就会丢失;而且 写回时必须把**同一次读**里的 `mcp_servers` 合并回去,否则 `/theme` 一改就会把用户 所有 MCP 配置抹掉。 @@ -291,7 +291,7 @@ agent 目录本身,而不是把凭据写到宿主指定的命名空间之外。 ``` ~/.stepcode/ -├── config.toml # ★ 统一配置:Pi 原生设置 + Step 产品设置 + [mcp_servers] +├── config.toml # ★ 统一配置:运行时原生设置 + Step 产品设置 + [mcp_servers] ├── auth.json # ★ Step provider 凭据(0600),由 step login 写入 ├── models.json # ★ 模型目录/覆盖(从 agent/ 上提) ├── .credentials.json # ★ MCP OAuth 令牌(0600),key = "|" @@ -309,7 +309,7 @@ agent 目录本身,而不是把凭据写到宿主指定的命名空间之外。 ├── sessions/ # 顶层会话记录 ├── skills/ # 用户级 skills ├── telemetry/ # 遥测缓冲(spool) -└── agent/ # Pi agent 命名空间 +└── agent/ # agent 命名空间 ├── prompts/ # 用户自定义 prompts ├── sessions/ # agent 会话记录 ├── trust.json # 项目信任存储(ProjectTrustStore) diff --git a/docs/tui-rendering-pipeline.md b/docs/tui-rendering-pipeline.md index 9ed4a2ab..b2479fd1 100644 --- a/docs/tui-rendering-pipeline.md +++ b/docs/tui-rendering-pipeline.md @@ -55,7 +55,7 @@ 退出时反向恢复：关进度、关 bracketed paste、`\x1b[ width` 直接把全部行写进 `pi-crash.log`，清理终端状态后抛错——指向"组件没截断"这个根因。 +10. 硬保险（`tui-main-screen.ts:651-678`）：任何渲染行 `visibleWidth > width` 直接把全部行写进 `tui-crash.log`，清理终端状态后抛错——指向"组件没截断"这个根因。 11. 更新镜像：`previousLines`、`hardwareCursorRow`、`previousViewportTop`、`previousKittyImageIds`、宽高（`tui-main-screen.ts:737-749`），并按需移动硬件光标（`positionHardwareCursor`，`tui-main-screen.ts:757-788`）。 输出统一经过 `BoundedTerminalWriter`（`tui-main-screen.ts:24-80`）：按 1MiB 分块刷盘，超长串按代理对边界切开，避免整帧拼成一个超过 V8 字符串上限的大串。 @@ -169,7 +169,7 @@ alt screen 进入时（`tui-alt-screen.ts:316-318`）：`\x1b[?1049h` + 关 auto ## 7. 产品侧接线（apps/cli） -渲染库只提供机制；"什么事件、什么数据、变成什么组件"由产品层决定，边界遵守 AGENTS.md 的所有权规则（组件编排属 `coding-agent`/宿主，差分渲染原语属 `pi-tui`，产品层不重写渲染循环）。 +渲染库只提供机制；"什么事件、什么数据、变成什么组件"由产品层决定，边界遵守 AGENTS.md 的所有权规则（组件编排属 `coding-agent`/宿主，差分渲染原语属 `@step-harness/pi-tui` 包，产品层不重写渲染循环）。 ### 7.1 组合根 @@ -202,28 +202,28 @@ alt screen 进入时（`tui-alt-screen.ts:316-318`）：`\x1b[?1049h` + 关 auto 主题文件变化（`interactive-mode.ts:1248-1253`）：`ui.invalidate()` + `requestRender()`——`invalidate` 丢弃容器与组件的渲染缓存，主题色在下一帧的归一化行里生效。语法高亮全部加载完成后同样失效重绘（`interactive-mode.ts:1265-1269`）。git 分支变化只触发 `requestRender`（footer 数据提供者推送，`interactive-mode.ts:1256-1258`）。 -## 8. 环境变量与调试开关 +## 8. 渲染开关与调试 -| 变量 | 作用 | -| --- | --- | -| `PI_TUI_DISABLE_INCREMENTAL=1` | 关掉增量渲染，每帧全量走，用于渲染等价测试（`tui.ts:224-229`） | -| `PI_HARDWARE_CURSOR=1` | 显示硬件光标（默认隐藏，`tui.ts:447`） | -| `PI_CLEAR_ON_SHRINK=0` | 内容收缩时不清空多余行，减少慢终端重绘（`tui.ts:448`、`513-515`） | -| `PI_TUI_ESC_TIMEOUT=` | 覆盖裸 ESC 判定超时（默认 10ms，SSH 100ms，`terminal.ts:104-121`） | -| `PI_TUI_WRITE_LOG=` | 把渲染字节流落盘，回放诊断（`terminal.ts:138-151`） | -| `PI_DEBUG_REDRAW=1` | 全量重绘原因写入 `pi-debug.log`（`tui-main-screen.ts:430-437`） | -| `PI_TUI_DEBUG=1` | 每帧差分细节（区间、光标、前后帧）写入 `/tmp/tui`（`tui-main-screen.ts:703-730`） | -| `PI_CODING_AGENT_DIR` | 日志目录（缺省 `~/.pi/agent`，`tui.ts:469`） | +本节的开关都**不是环境变量**。早期版本把它们记作 `PI_TUI_*` / `PI_DEBUG_*` 环境变量，源码中并无任何对应的读取逻辑（`packages/tui/src` 内没有读取过 `PI_` 前缀的环境变量）。实际入口如下： + +| 开关 | 入口 | 作用 | +| --- | --- | --- | +| 增量渲染 | `setIncrementalRenderDisabled(true)`（`tui.ts:227-229`，进程内全局） | 每帧全量渲染，用于渲染等价测试 | +| 硬件光标 | `showHardwareCursor` 设置项 → `ui.setShowHardwareCursor()`（`tui.ts:506-511`） | 显示终端光标，便于 IME（默认隐藏） | +| 收缩清行 | `terminal.clearOnShrink` 设置项 → `ui.setClearOnShrink()`（`tui.ts:524-527`） | 内容收缩时是否清空多余行（默认 false，开启可能闪烁） | +| ESC 超时 | 无开关，按传输自动判定（`terminal.ts:103-116`） | 非 SSH 10ms；检测到 `SSH_CONNECTION`/`SSH_TTY` 时 100ms | + +唯一的落盘诊断是崩溃现场：任何渲染行 `visibleWidth > width` 时，全部行写入 `/tui-crash.log`（`tui-main-screen.ts:628-639`）。`logDirectory` 由 `TUI` 构造参数传入，缺省是 `os.tmpdir()` 下按需创建的 `tui-*` 私有临时目录（`tui.ts:479-484`）。 ## 9. 测试与验证 - `packages/tui/test` 用 `node:test`：差分行为（`container-render-cache.test.ts`、`main-screen-offscreen-change.test.ts`）、overlay 定位（`overlay-*.test.ts`）、布局（`layout.test.ts`）、输入（`stdin-buffer.test.ts`、`keys.test.ts`、`keybindings.test.ts`、`input.test.ts`）、宽度回归（`bug-regression-isimageline-startswith-bug.test.ts`、`tab-width.test.ts` 等）。 -- 渲染等价性：`PI_TUI_DISABLE_INCREMENTAL=1` 强制全量路径，与增量路径逐字节对比——增量复用一旦算错前缀就会在这里现形。 +- 渲染等价性：`setIncrementalRenderDisabled(true)` 强制全量路径，与增量路径逐字节对比——增量复用一旦算错前缀就会在这里现形。 - 产品侧：`apps/cli/test` 的 TUI 快照测试（如 `tui-acceptance-snapshot.test.ts`）锁住视图渲染输出。 ## 10. 归属与约束 - 差分渲染、输入分发、布局合成只存在于 `packages/tui`；`apps/cli` 不 fork、不重写。 - `packages/tui` 保持零 AI 依赖（`docs/step-harness-architecture-redesign.md` 的 `check-tui-no-ai` 检查）。 -- 组件不得输出超过传入宽度的行——主屏渲染器会抛错并把现场写进 `pi-crash.log`；测量用 `visibleWidth()`，截断用 `truncateToWidth()`。 +- 组件不得输出超过传入宽度的行——主屏渲染器会抛错并把现场写进 `tui-crash.log`；测量用 `visibleWidth()`，截断用 `truncateToWidth()`。 - 跨进程渲染契约（远端会话）在 `packages/protocol`；本文只覆盖本地进程内的 TUI 渲染。 diff --git a/packages/agent-core/docs/harness.md b/packages/agent-core/docs/harness.md index 425611a6..9e30c3cd 100644 --- a/packages/agent-core/docs/harness.md +++ b/packages/agent-core/docs/harness.md @@ -230,7 +230,7 @@ Source type provenance: - `TelemetryContext` and typed schema helpers: `packages/telemetry`; the agent-owned schemas remain in `packages/agent/src/harness/telemetry.ts`. - `TSchema` for durable custom-message registration: `typebox`. -The public `QueueMode` remains `"all" | "one-at-a-time"`. Public `RetryPolicy` remains the pi-ai shape `{ enabled, maxRetries, baseDelayMs }`; operation state stores its normalized `{ maxAttempts, baseDelayMs }` equivalent. `maxRetries` and `baseDelayMs` must be finite non-negative safe integers and `maxRetries + 1` must remain safe; disabled retry normalizes to one attempt. Exponential delay and `notBefore` arithmetic saturate at `Number.MAX_SAFE_INTEGER`. Public `CompactionSettings` remains `{ enabled, reserveTokens, keepRecentTokens }`; both token counts must be finite non-negative safe integers. Constructors and setters reject invalid settings before publication. This design adds `deferred?: boolean | { window?: "15m" | "1h" | "24h" }` to `AgentHarnessStreamOptions` and its patch type; structural requests always force it to false. +The public `QueueMode` remains `"all" | "one-at-a-time"`. Public `RetryPolicy` remains the `@step-harness/providers` shape `{ enabled, maxRetries, baseDelayMs }`; operation state stores its normalized `{ maxAttempts, baseDelayMs }` equivalent. `maxRetries` and `baseDelayMs` must be finite non-negative safe integers and `maxRetries + 1` must remain safe; disabled retry normalizes to one attempt. Exponential delay and `notBefore` arithmetic saturate at `Number.MAX_SAFE_INTEGER`. Public `CompactionSettings` remains `{ enabled, reserveTokens, keepRecentTokens }`; both token counts must be finite non-negative safe integers. Constructors and setters reject invalid settings before publication. This design adds `deferred?: boolean | { window?: "15m" | "1h" | "24h" }` to `AgentHarnessStreamOptions` and its patch type; structural requests always force it to false. ```ts type SettledAssistantMessage = AssistantMessage & { diff --git a/packages/agent-core/docs/search.md b/packages/agent-core/docs/search.md index b1c3905f..09d71306 100644 --- a/packages/agent-core/docs/search.md +++ b/packages/agent-core/docs/search.md @@ -1,6 +1,6 @@ # Session Search -Pi search is a small query interface over committed session entries. The shared contract returns only stable hit identity; implementations may extend hits with backend-specific display data. +Session search is a small query interface over committed session entries. The shared contract returns only stable hit identity; implementations may extend hits with backend-specific display data. ## Core API diff --git a/packages/agent-core/docs/telemetry-schema.md b/packages/agent-core/docs/telemetry-schema.md index 9eb8e6e4..4fde6c07 100644 --- a/packages/agent-core/docs/telemetry-schema.md +++ b/packages/agent-core/docs/telemetry-schema.md @@ -1,4 +1,4 @@ -# Pi Agent Telemetry Schemas +# Step Agent Telemetry Schemas diff --git a/packages/agent-core/scripts/generate-telemetry-docs.ts b/packages/agent-core/scripts/generate-telemetry-docs.ts index 31e733ce..a4d94915 100644 --- a/packages/agent-core/scripts/generate-telemetry-docs.ts +++ b/packages/agent-core/scripts/generate-telemetry-docs.ts @@ -83,7 +83,7 @@ function renderSchema(schema: TelemetrySchemaDefinition, title: string): string[ export function renderAgentTelemetrySchemaMarkdown(): string { const lines = [ - "# Pi Agent Telemetry Schemas", + "# Step Agent Telemetry Schemas", "", "", "", diff --git a/packages/agent-core/test/harness/telemetry.test.ts b/packages/agent-core/test/harness/telemetry.test.ts index 92faa063..b7265242 100644 --- a/packages/agent-core/test/harness/telemetry.test.ts +++ b/packages/agent-core/test/harness/telemetry.test.ts @@ -33,8 +33,10 @@ describe("agent telemetry schemas", () => { "pi.harness.event_handler", "pi.session.write", ]); + const expected = renderAgentTelemetrySchemaMarkdown(); + expect(expected).toMatch(/^# Step Agent Telemetry Schemas\n/); const actual = readFileSync(resolve(import.meta.dirname, "../../docs/telemetry-schema.md"), "utf8"); - expect(actual).toBe(renderAgentTelemetrySchemaMarkdown()); + expect(actual).toBe(expected); }); it("starts AI-request and harness spans through one composed typed starter", async () => { diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md index ef73fed0..e2e35dcd 100644 --- a/packages/coding-agent/README.md +++ b/packages/coding-agent/README.md @@ -1,15 +1,24 @@

- Discord npm

--- -Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Pi Packages](#pi-packages) and share them with others via npm or git. +`@step-harness/coding-agent` is the StepCode runtime: a minimal terminal coding harness. Adapt it to your workflows, not the other way around, without forking and modifying the internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in a [StepCode package](#packages) and share it with others via npm or git. -Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow. +StepCode ships with powerful defaults but skips opinionated features like sub agents and plan mode. Instead, ask it to build what you want, or install a third-party package that matches your workflow. -Pi runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. +StepCode runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. + +### Upstream lineage and naming + +The shipped entrypoint is `step`, and its config and package root is `~/.stepcode/`. This runtime is derived from an upstream project whose CLI carried a different name, which survives in three identifiers that are compatibility contracts rather than branding, and that are therefore documented as-is below: + +- the `pi` manifest key the package loader reads from `package.json` +- the `pi-package` npm keyword used for package discovery +- the published `@step-harness/pi-tui` component package + +Telemetry span and attribute names keep the same legacy prefix; see [telemetry-schema.md](../agent-core/docs/telemetry-schema.md). ## Table of Contents @@ -30,7 +39,7 @@ Pi runs in four modes: interactive, print or JSON, RPC for process integration, - [Skills](#skills) - [Extensions](#extensions) - [Themes](#themes) - - [Pi Packages](#pi-packages) + - [Packages](#packages) - [Programmatic Usage](#programmatic-usage) - [Philosophy](#philosophy) - [CLI Reference](#cli-reference) @@ -43,23 +52,23 @@ Pi runs in four modes: interactive, print or JSON, RPC for process integration, npm install -g --ignore-scripts @step-harness/coding-agent ``` -`--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs. +`--ignore-scripts` disables dependency lifecycle scripts during install. StepCode does not require install scripts for normal npm installs. Authenticate with an API key: ```bash export STEP_API_KEY=... -pi +step ``` Or use your existing subscription: ```bash -pi +step /login # Then select provider ``` -Then just talk to pi. By default, pi gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [pi packages](#pi-packages). +Then just talk to StepCode. By default, it gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [packages](#packages). **Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md) @@ -69,11 +78,11 @@ Then just talk to pi. By default, pi gives the model four tools: `read`, `write` The shipped build authenticates against the **Step provider** by default. Log in with `/login` (or set `STEP_API_KEY`), then select a Step model via `/model` (or Ctrl+L). Press Ctrl+S in the model picker to save the highlighted model as the startup default. -No other provider catalog is bundled. Add OpenAI- or Anthropic-compatible providers yourself via `~/.pi/agent/models.json`; configured catalogs refresh automatically, and `pi update --models` forces an immediate refresh. For custom APIs or OAuth, use extensions. +No other provider catalog is bundled. Add OpenAI- or Anthropic-compatible providers yourself via `~/.stepcode/agent/models.json`; configured catalogs refresh automatically, and `step update --models` forces an immediate refresh. For custom APIs or OAuth, use extensions. -Pi also supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage downloads and loaded models with `/llama`, then select a loaded model with `/model`. See [docs/llama-cpp.md](docs/llama-cpp.md) for setup and usage. +StepCode also supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage downloads and loaded models with `/llama`, then select a loaded model with `/model`. See [docs/llama-cpp.md](docs/llama-cpp.md) for setup and usage. -**Custom providers & models:** Add providers via `~/.pi/agent/models.json` if they speak a supported API (OpenAI or Anthropic). See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md), or [@step-harness/providers](../providers/README.md) for the underlying protocols. +**Custom providers & models:** Add providers via `~/.stepcode/agent/models.json` if they speak a supported API (OpenAI or Anthropic). See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md), or [@step-harness/providers](../providers/README.md) for the underlying protocols. --- @@ -130,11 +139,11 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist | `/share` | Upload as private GitHub gist with shareable HTML link | | `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files | | `/hotkeys` | Show all keyboard shortcuts | -| `/quit` | Quit pi | +| `/quit` | Quit step | ### Keyboard Shortcuts -See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md). +See `/hotkeys` for the full list. Customize via `~/.stepcode/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md). **Commonly used:** @@ -161,7 +170,7 @@ Submit messages while the agent is working: Follow-up delivery remains available to extensions, RPC clients, and custom `app.message.followUp` keybindings, but has no default shortcut. -On Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so pi can receive the newline shortcut. +On Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so step can receive the newline shortcut. Configure delivery in [settings](docs/settings.md): `steeringMode` and `followUpMode` can be `"one-at-a-time"` (default, waits for response) or `"all"` (delivers all queued at once). `transport` selects provider transport preference (`"sse"`, `"websocket"`, or `"auto"`) for providers that support multiple transports. @@ -173,15 +182,15 @@ Sessions are stored as JSONL files with a tree structure. Each entry has an `id` ### Management -Sessions auto-save to `~/.pi/agent/sessions/` organized by working directory. +Sessions auto-save to `~/.stepcode/agent/sessions/` organized by working directory. ```bash -pi -c # Continue most recent session -pi -r # Browse and select from past sessions -pi --no-session # Ephemeral mode (don't save) -pi --name "my task" # Set session display name at startup -pi --session # Use specific session file or ID -pi --fork # Fork specific session file or ID into a new session +step -c # Continue most recent session +step -r # Browse and select from past sessions +step --no-session # Ephemeral mode (don't save) +step --name "my task" # Set session display name at startup +step --session # Use specific session file or ID +step --fork # Fork specific session file or ID into a new session ``` Use `/session` in interactive mode to see the current session ID before reusing it with `--session ` or `--fork `. @@ -221,35 +230,35 @@ Use `/settings` to modify common options, or edit JSON files directly: | Location | Scope | |----------|-------| -| `~/.pi/agent/settings.json` | Global (all projects) | -| `.pi/settings.json` | Project (overrides global) | +| `~/.stepcode/agent/settings.json` | Global (all projects) | +| `.stepcode/settings.json` | Project (overrides global) | See [docs/settings.md](docs/settings.md) for all options. ### Project Trust -On interactive startup, pi asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` or `.claude/skills` and has no saved decision for the folder or a parent folder in `~/.pi/agent/trust.json`. Trusting a project allows pi to load `.pi/settings.json` and `.pi` resources, install missing project packages, and execute project extensions. +On interactive startup, step asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` or `.claude/skills` and has no saved decision for the folder or a parent folder in `~/.stepcode/agent/trust.json`. Trusting a project allows step to load `.stepcode/settings.json` and `.stepcode` resources, install missing project packages, and execute project extensions. -Before the trust decision, pi loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process. +Before the trust decision, step loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process. Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run. -If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.pi/agent/settings.json`, or change it with `/settings`. +If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.stepcode/agent/settings.json`, or change it with `/settings`. -`pi config` and package commands use the same project trust flow, except `pi update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them. +`step config` and package commands use the same project trust flow, except `step update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them. -Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.pi/agent/trust.json` only; the current session is not reloaded, so restart pi for changes to take effect. +Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.stepcode/agent/trust.json` only; the current session is not reloaded, so restart step for changes to take effect. --- ## Context Files -Pi loads `AGENTS.md` (or `CLAUDE.md`) at startup from: -- `~/.pi/agent/AGENTS.md` (global) +StepCode loads `AGENTS.md` (or `CLAUDE.md`) at startup from: +- `~/.stepcode/agent/AGENTS.md` (global) - Parent directories (walking up from cwd) - Current directory -If a directory contains `AGENTS.override.md`, Pi loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories are still concatenated. +If a directory contains `AGENTS.override.md`, StepCode loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories are still concatenated. Use for project instructions (`AGENTS.md`/`CLAUDE.md`), conventions, common commands. All matching files are concatenated. @@ -257,7 +266,7 @@ Disable context file loading with `--no-context-files` (or `-nc`). ### System Prompt -Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`. +Replace the default system prompt with `.stepcode/SYSTEM.md` (project) or `~/.stepcode/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`. --- @@ -268,19 +277,19 @@ Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent Reusable prompts as Markdown files. Type `/name` to expand. ```markdown - + Review this code for bugs, security issues, and performance problems. Focus on: {{focus}} ``` -Place in `~/.pi/agent/prompts/`, `.pi/prompts/`, or a [pi package](#pi-packages) to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md). +Place in `~/.stepcode/agent/prompts/`, `.stepcode/prompts/`, or a [package](#packages) to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md). ### Skills On-demand capability packages following the [Agent Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically. ```markdown - + # My Skill Use this skill when the user asks about X. @@ -289,13 +298,13 @@ Use this skill when the user asks about X. 2. Then that ``` -Place in `~/.pi/agent/skills/`, `~/.pi/skills/`, `~/.agents/skills/`, `~/.claude/skills/`, `.pi/skills/`, `.agents/skills/`, or `.claude/skills/` (the last two from `cwd` up through parent directories) or a [pi package](#pi-packages) to share with others. See [docs/skills.md](docs/skills.md). +Place in `~/.stepcode/agent/skills/`, `~/.stepcode/skills/`, `~/.agents/skills/`, `~/.claude/skills/`, `.stepcode/skills/`, `.agents/skills/`, or `.claude/skills/` (the last two from `cwd` up through parent directories) or a [package](#packages) to share with others. See [docs/skills.md](docs/skills.md). ### Extensions

Doom Extension

-TypeScript modules that extend pi with custom tools, commands, keyboard shortcuts, event handlers, and UI components. +TypeScript modules that extend step with custom tools, commands, keyboard shortcuts, event handlers, and UI components. ```typescript export default function (pi: ExtensionAPI) { @@ -305,7 +314,7 @@ export default function (pi: ExtensionAPI) { } ``` -The default export can also be `async`. pi waits for async extension factories before startup continues, which is useful for one-time initialization such as fetching remote model lists before calling `pi.registerProvider()`. +The default export can also be `async`. step waits for async extension factories before startup continues, which is useful for one-time initialization such as fetching remote model lists before calling `pi.registerProvider()`. **What's possible:** - Custom tools (or replace built-in tools entirely) @@ -317,24 +326,23 @@ The default export can also be `async`. pi waits for async extension factories b - Git checkpointing and auto-commit - SSH and sandbox execution - MCP server integration -- Make pi look like Claude Code +- Make step look like Claude Code - Games while waiting (yes, Doom runs) - ...anything you can dream up -Place in `~/.pi/agent/extensions/`, `.pi/extensions/`, or a [pi package](#pi-packages) to share with others. See [docs/extensions.md](docs/extensions.md) and [examples/extensions/](examples/extensions/). +Place in `~/.stepcode/agent/extensions/`, `.stepcode/extensions/`, or a [package](#packages) to share with others. See [docs/extensions.md](docs/extensions.md) and [examples/extensions/](examples/extensions/). ### Themes -Built-in: `dark`, `light`, `sage`, `step-blue`, `step-violet`, `step-violet-light`. Themes hot-reload: modify the active theme file and pi immediately applies changes. +Built-in: `dark`, `light`, `sage`, `step-blue`, `step-violet`, `step-violet-light`. Themes hot-reload: modify the active theme file and step immediately applies changes. -Place in `~/.pi/agent/themes/`, `.pi/themes/`, or a [pi package](#pi-packages) to share with others. See [docs/themes.md](docs/themes.md). +Place in `~/.stepcode/agent/themes/`, `.stepcode/themes/`, or a [package](#packages) to share with others. See [docs/themes.md](docs/themes.md). ### Step entrypoint -The `step` binary is a thin product entrypoint over the same pi coding-agent -runtime and native TUI. It selects the `step` provider and model by default, -uses the built-in `step-blue` theme (one blue palette, no light/dark variants), and stores sessions -under `~/.stepcode/`. +The `step` binary selects the `step` provider and model by default, uses the +built-in `step-blue` theme (one blue palette, no light/dark variants), and +stores sessions under `~/.stepcode/`. ```bash STEP_API_KEY=... step @@ -343,45 +351,45 @@ step --help Step-specific behavior is registered as an extension (`/init`, provider login, and branding). The editor, input protocol, selectors, overlays, queueing, and -agent lifecycle remain pi-owned. +agent lifecycle are owned by the shared runtime. -### Pi Packages +### Packages -Bundle and share extensions, skills, prompts, and themes via npm or git. Find packages on [npmjs.com](https://www.npmjs.com/search?q=keywords%3Api-package) or [Discord](https://discord.com/channels/1456806362351669492/1457744485428629628). +Bundle and share extensions, skills, prompts, and themes via npm or git. Find packages on [npmjs.com](https://www.npmjs.com/search?q=keywords%3Api-package). -> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages. +> **Security:** StepCode packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages. ```bash -pi install npm:@foo/pi-tools -pi install npm:@foo/pi-tools@1.2.3 # pinned version -pi install git:github.com/user/repo -pi install git:github.com/user/repo@v1 # tag or commit -pi install git:git@github.com:user/repo -pi install git:git@github.com:user/repo@v1 # tag or commit -pi install https://github.com/user/repo -pi install https://github.com/user/repo@v1 # tag or commit -pi install ssh://git@github.com/user/repo -pi install ssh://git@github.com/user/repo@v1 # tag or commit -pi remove npm:@foo/pi-tools -pi uninstall npm:@foo/pi-tools # alias for remove -pi list -pi update # update pi only -pi update --all # update pi and packages -pi update --extensions # update packages only -pi update --models # refresh model catalogs only -pi update --self # update pi only -pi update --self --force # reinstall pi even if current -pi update npm:@foo/pi-tools # update one package -pi config # enable/disable extensions, skills, prompts, themes +step install npm:@foo/step-tools +step install npm:@foo/step-tools@1.2.3 # pinned version +step install git:github.com/user/repo +step install git:github.com/user/repo@v1 # tag or commit +step install git:git@github.com:user/repo +step install git:git@github.com:user/repo@v1 # tag or commit +step install https://github.com/user/repo +step install https://github.com/user/repo@v1 # tag or commit +step install ssh://git@github.com/user/repo +step install ssh://git@github.com/user/repo@v1 # tag or commit +step remove npm:@foo/step-tools +step uninstall npm:@foo/step-tools # alias for remove +step list +step update # update StepCode only +step update --all # update StepCode and packages +step update --extensions # update packages only +step update --models # refresh model catalogs only +step update --self # update StepCode only +step update --self --force # reinstall StepCode even if current +step update npm:@foo/step-tools # update one package +step config # enable/disable extensions, skills, prompts, themes ``` -Packages install to `~/.pi/agent/git/` (git) or `~/.pi/agent/npm/` (npm). Use `-l` for project-local installs (`.pi/git/`, `.pi/npm/`). Git `@ref` values are pinned tags or commits; pinned packages are skipped by `pi update --extensions` and `pi update --all`, so use `pi install git:host/user/repo@new-ref` to move an existing package to a new ref. Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers. If you use a Node version manager and want package installs to reuse a stable npm context, set `npmCommand` in `settings.json`, for example `["mise", "exec", "node@20", "--", "npm"]`. +Packages install to `~/.stepcode/agent/git/` (git) or `~/.stepcode/agent/npm/` (npm). Use `-l` for project-local installs (`.stepcode/git/`, `.stepcode/npm/`). Git `@ref` values are pinned tags or commits; pinned packages are skipped by `step update --extensions` and `step update --all`, so use `step install git:host/user/repo@new-ref` to move an existing package to a new ref. Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers. If you use a Node version manager and want package installs to reuse a stable npm context, set `npmCommand` in `settings.json`, for example `["mise", "exec", "node@20", "--", "npm"]`. -Create a package by adding a `pi` key to `package.json`: +Create a package by adding a `pi` manifest key to `package.json`. The key keeps its upstream name so already-published packages stay discoverable: ```json { - "name": "my-pi-package", + "name": "my-step-package", "keywords": ["pi-package"], "pi": { "extensions": ["./extensions"], @@ -392,7 +400,7 @@ Create a package by adding a `pi` key to `package.json`: } ``` -Without a `pi` manifest, pi auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`). +Without a `pi` manifest, StepCode auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`). See [docs/packages.md](docs/packages.md). @@ -423,7 +431,7 @@ See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/). For non-Node.js integrations, use RPC mode over stdin/stdout: ```bash -pi --mode rpc +step --mode rpc ``` RPC mode uses strict LF-delimited JSONL framing. Clients must split records on `\n` only. Do not use generic line readers like Node `readline`, which also split on Unicode separators inside JSON payloads. @@ -434,11 +442,11 @@ See [docs/rpc.md](docs/rpc.md) for the protocol. ## Philosophy -Pi is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with [extensions](#extensions), [skills](#skills), or installed from third-party [pi packages](#pi-packages). This keeps the core minimal while letting you shape pi to fit how you work. +StepCode is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with [extensions](#extensions), [skills](#skills), or installed from third-party [packages](#packages). This keeps the core minimal while letting you shape StepCode to fit how you work. -**No MCP.** Build CLI tools with READMEs (see [Skills](#skills)), or build an extension that adds MCP support. [Why?](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/) +**No MCP.** Build CLI tools with READMEs (see [Skills](#skills)), or build an extension that adds MCP support. -**No sub-agents.** There's many ways to do this. Spawn pi instances via tmux, or build your own with [extensions](#extensions), or install a package that does it your way. +**No sub-agents.** There's many ways to do this. Spawn StepCode instances via tmux, or build your own with [extensions](#extensions), or install a package that does it your way. **No permission popups.** Run in a container, or build your own confirmation flow with [extensions](#extensions) inline with your environment and security requirements. @@ -448,34 +456,35 @@ Pi is aggressively extensible so it doesn't have to dictate your workflow. Featu **No background bash.** Use tmux. Full observability, direct interaction. -Read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/) for the full rationale. +This design is deliberate: the runtime stays small, and anything opinionated is +something you add. --- ## CLI Reference ```bash -pi [options] [--] [@files...] [messages...] +step [options] [--] [@files...] [messages...] ``` ### Package Commands ```bash -pi install [-l] # Install package, -l for project-local -pi remove [-l] # Remove package -pi uninstall [-l] # Alias for remove -pi update [source|self|pi] # Update pi only, or one package source -pi update --all # Update pi and packages -pi update --extensions # Update packages only -pi update --models # Refresh model catalogs only -pi update --self # Update pi only -pi update --self --force # Reinstall pi even if current -pi update --extension # Update one package -pi list # List installed packages -pi config # Enable/disable package resources +step install [-l] # Install package, -l for project-local +step remove [-l] # Remove package +step uninstall [-l] # Alias for remove +step update [source|self|step] # Update StepCode only, or one package source +step update --all # Update StepCode and packages +step update --extensions # Update packages only +step update --models # Refresh model catalogs only +step update --self # Update StepCode only +step update --self --force # Reinstall StepCode even if current +step update --extension # Update one package +step list # List installed packages +step config # Enable/disable package resources ``` -`pi config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `pi update` never prompts for project trust. +`step config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `step update` never prompts for project trust. ### Modes @@ -487,10 +496,10 @@ pi config # Enable/disable package resources | `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) | | `--export [out]` | Export session to HTML | -In print mode, pi also reads piped stdin and merges it into the initial prompt: +In print mode, step also reads piped stdin and merges it into the initial prompt: ```bash -cat README.md | pi -p "Summarize this text" +cat README.md | step -p "Summarize this text" ``` ### Model Options @@ -563,49 +572,49 @@ Combine `--no-*` with explicit flags to load exactly what you need, ignoring set Prefix files with `@` to include in the message: ```bash -pi @prompt.md "Answer this" -pi -p @screenshot.png "What's in this image?" -pi @code.ts @test.ts "Review these files" +step @prompt.md "Answer this" +step -p @screenshot.png "What's in this image?" +step @code.ts @test.ts "Review these files" ``` ### Examples ```bash # Interactive with initial prompt -pi "List all .ts files in src/" +step "List all .ts files in src/" # Non-interactive -pi -p "Summarize this codebase" +step -p "Summarize this codebase" # Prompt beginning with a dash -pi -p -- "- Summarize these points" +step -p -- "- Summarize these points" # Non-interactive with piped stdin -cat README.md | pi -p "Summarize this text" +cat README.md | step -p "Summarize this text" # Named one-shot session -pi --name "release audit" -p "Audit this repository" +step --name "release audit" -p "Audit this repository" # Different model -pi --provider openai --model gpt-4o "Help me refactor" +step --provider openai --model gpt-4o "Help me refactor" # Model with provider prefix (no --provider needed) -pi --model openai/gpt-4o "Help me refactor" +step --model openai/gpt-4o "Help me refactor" # Model with thinking level shorthand -pi --model sonnet:high "Solve this complex problem" +step --model sonnet:high "Solve this complex problem" # Limit model cycling -pi --models "claude-*,gpt-4o" +step --models "claude-*,gpt-4o" # Read-only mode -pi --tools read,grep,find,ls -p "Review the code" +step --tools read,grep,find,ls -p "Review the code" # Disable one extension or built-in tool while keeping the rest available -pi --exclude-tools ask_question +step --exclude-tools ask_question # High thinking level -pi --thinking high "Solve this complex problem" +step --thinking high "Solve this complex problem" ``` ### Environment Variables diff --git a/packages/coding-agent/docs/custom-provider.md b/packages/coding-agent/docs/custom-provider.md index c9ab1185..f92b507a 100644 --- a/packages/coding-agent/docs/custom-provider.md +++ b/packages/coding-agent/docs/custom-provider.md @@ -29,7 +29,7 @@ adapter's license and credential handling before loading it. ## Quick Reference -Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Step composes `models.json` overrides above registered native providers. +Extensions can register either a complete `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Step composes `models.json` overrides above registered native providers. ```typescript import { createProvider, openAICompletionsApi } from "@step-harness/providers"; diff --git a/packages/coding-agent/docs/development.md b/packages/coding-agent/docs/development.md index d75152d3..724daf94 100644 --- a/packages/coding-agent/docs/development.md +++ b/packages/coding-agent/docs/development.md @@ -39,8 +39,8 @@ Configure via `package.json`: ```json { "piConfig": { - "name": "pi", - "configDir": ".pi" + "name": "step", + "configDir": ".stepcode" } } ``` diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.md index eb77b04c..54aa26fb 100644 --- a/packages/coding-agent/docs/extensions.md +++ b/packages/coding-agent/docs/extensions.md @@ -1012,7 +1012,7 @@ ctx.sessionManager.getLeafId() // Current leaf entry ID ### ctx.modelRegistry / ctx.model / ctx.thinkingLevel / ctx.scopedModels -Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective pi-ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model, and `ctx.thinkingLevel` is its current effective thinking level. +Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model, and `ctx.thinkingLevel` is its current effective thinking level. `ctx.scopedModels` is the read-only list of models scoped to the current session — the same set the `/scoped-models` command shows. It is resolved at session start from the `--models` CLI flag and the `enabledModels` setting (matched against the available catalogue with minimatch on `provider/modelId` or a bare `modelId`). It is empty when no scoping is configured, meaning every available model is usable. Each entry is `{ model, thinkingLevel? }`, where `thinkingLevel` is set only when a pattern pinned it (e.g. `anthropic/*:high`). Use it to populate a model picker that mirrors the built-in one instead of enumerating the whole catalogue via `ctx.modelRegistry.getAvailable()`. @@ -1866,7 +1866,7 @@ pi.registerProvider("corporate-ai", { }); ``` -The object form accepts a complete pi-ai `Provider`, including native `auth`, `getModels`, `refreshModels`, `filterModels`, `stream`, and `streamSimple` behavior. +The object form accepts a complete `Provider`, including native `auth`, `getModels`, `refreshModels`, `filterModels`, `stream`, and `streamSimple` behavior. **Legacy config options:** - `name` - Display name for the provider in UI such as `/login`. @@ -2645,7 +2645,7 @@ ctx.ui.setFooter((tui, theme) => ({ ctx.ui.setFooter(undefined); // Restore built-in footer // Terminal title -ctx.ui.setTitle("pi - my-project"); +ctx.ui.setTitle("step - my-project"); // Editor text ctx.ui.setEditorText("Prefill text"); diff --git a/packages/coding-agent/docs/models.md b/packages/coding-agent/docs/models.md index a25447f3..42d42eee 100644 --- a/packages/coding-agent/docs/models.md +++ b/packages/coding-agent/docs/models.md @@ -485,8 +485,8 @@ For providers with partial OpenAI compatibility, use the `compat` field. | `requiresThinkingAsText` | Convert thinking blocks to plain text | | `requiresReasoningContentOnAssistantMessages` | Include empty `reasoning_content` on all replayed assistant messages when reasoning is enabled | | `thinkingFormat` | Use `reasoning_effort`, `openrouter`, `deepseek`, `together`, `baseten`, `zai`, `qwen`, `chat-template`, or `qwen-chat-template` thinking parameters | -| `chatTemplateKwargs` | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values | -| `chatTemplateArgs` | `chat_template_args` values for `thinkingFormat: "baseten"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values | +| `chatTemplateKwargs` | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for agent-controlled thinking values | +| `chatTemplateArgs` | `chat_template_args` values for `thinkingFormat: "baseten"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for agent-controlled thinking values | | `thinkingTokenBudgetField` | Top-level request field used to cap reasoning tokens from `thinkingBudgets`, clamped so at least 1024 tokens remain for the answer. `"thinking_token_budget"` (vLLM), `"thinking_budget"` (Qwen/DashScope/SGLang), `"thinking_budget_tokens"` (llama.cpp). Off by default; not set on the generated catalog. | | `supportsThinkingTokenBudget` | Alias for `thinkingTokenBudgetField: "thinking_token_budget"` (vLLM). Prefer `thinkingTokenBudgetField`. Default: `false`. | | `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user, assistant, or tool-result text content. Currently only `anthropic` is supported. | diff --git a/packages/coding-agent/docs/packages.md b/packages/coding-agent/docs/packages.md index 8097b124..8e6f5487 100644 --- a/packages/coding-agent/docs/packages.md +++ b/packages/coding-agent/docs/packages.md @@ -8,7 +8,7 @@ Step packages bundle extensions, skills, prompt templates, and themes so you can - [Install and Manage](#install-and-manage) - [Package Sources](#package-sources) -- [Creating a Step Package](#creating-a-pi-package) +- [Creating a Step Package](#creating-a-step-package) - [Package Structure](#package-structure) - [Dependencies](#dependencies) - [Package Filtering](#package-filtering) @@ -115,7 +115,7 @@ Local paths point to files or directories on disk and are added to settings with ## Creating a Step Package -Add a `step` manifest to `package.json` or use conventional directories. Include the `pi-package` keyword for discoverability. +Add the manifest to `package.json` or use conventional directories. The key itself is `pi` and the discovery keyword is `pi-package`; both keep their legacy spelling so packages published before the rename stay discoverable, and both are read as-is by the loader. ```json { diff --git a/packages/coding-agent/docs/prompt-templates.md b/packages/coding-agent/docs/prompt-templates.md index ba2280d1..280295a9 100644 --- a/packages/coding-agent/docs/prompt-templates.md +++ b/packages/coding-agent/docs/prompt-templates.md @@ -10,7 +10,7 @@ Step loads prompt templates from: - Global: `~/.stepcode/agent/prompts/*.md` - Project: `.stepcode/prompts/*.md` (only after the project is trusted) -- Packages: `prompts/` directories or `pi.prompts` entries in `package.json` +- Packages: `prompts/` directories, or `pi.prompts` entries in `package.json` (the manifest key keeps its legacy name; see [Packages](packages.md)) - Settings: `prompts` array with files or directories - CLI: `--prompt-template ` (repeatable) diff --git a/packages/coding-agent/docs/rpc.md b/packages/coding-agent/docs/rpc.md index d65376b0..303f08aa 100644 --- a/packages/coding-agent/docs/rpc.md +++ b/packages/coding-agent/docs/rpc.md @@ -233,7 +233,7 @@ Response: } ``` -Messages are `AgentMessage` objects (see [Message Types](#message-types)). +Messages are `AgentMessage` objects. ### Model diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md index 402e3be3..25567175 100644 --- a/packages/coding-agent/docs/sdk.md +++ b/packages/coding-agent/docs/sdk.md @@ -471,7 +471,7 @@ const customRuntime = await ModelRuntime.create({ modelsPath: "/my/app/models.json", }); -// Or inject any pi-ai CredentialStore +// Or inject any `@step-harness/providers` CredentialStore const credentials = new InMemoryCredentialStore(); const inMemoryRuntime = await ModelRuntime.create({ credentials }); @@ -1176,7 +1176,7 @@ createAgentSessionRuntime AgentSessionRuntime // Auth and Models -ModelRuntime // implements pi-ai Models and owns credential storage +ModelRuntime // implements the providers-package Models and owns credential storage ModelRegistry // synchronous extension compatibility facade CredentialSynchronizationError resolveCliModel diff --git a/packages/coding-agent/docs/session-format.md b/packages/coding-agent/docs/session-format.md index 8a97a1d9..2c1db3e2 100644 --- a/packages/coding-agent/docs/session-format.md +++ b/packages/coding-agent/docs/session-format.md @@ -69,7 +69,7 @@ interface ToolCall { } ``` -### Base Message Types (from pi-ai) +### Base Message Types (from `@step-harness/providers`) ```typescript interface UserMessage { @@ -117,11 +117,11 @@ interface Usage { } ``` -The exported pi-ai `StopReason` type also includes `"pending"`, but that value is reserved for partial messages in streaming events. Terminal `done`/`error` messages replace it with a completion reason before step persists the assistant message, so `"pending"` should never appear in session JSONL. +The exported `StopReason` type also includes `"pending"`, but that value is reserved for partial messages in streaming events. Terminal `done`/`error` messages replace it with a completion reason before step persists the assistant message, so `"pending"` should never appear in session JSONL. Session totals and the cost breakdown use the shared [`usage-totals.ts`](../src/core/usage-totals.ts) ledger. It includes assistant, tool, compaction, branch-summary and incremental `step-auto-clm-usage` records; cumulative maintenance summaries are excluded. Token increments must contain nonnegative safe integers and must not overflow the accumulated total. A missing/invalid cost does not hide valid tokens. `SessionStats.tokens.input` excludes caches, which are reported separately; the [Account summary](account-usage.md) combines them into complete input. -### Extended Message Types (from pi-coding-agent) +### Extended Message Types (from the coding agent) ```typescript interface BashExecutionMessage { @@ -246,7 +246,7 @@ Optional fields: - `usage`: LLM usage from generating the summary; included in session token and cost totals - `retainedTail`: Materialized `AgentMessage[]` kept after compaction. This is optional only for backward compatibility with older sessions. Newer harness-generated compactions include it so we can rebuild context from this checkpoint without walking older entries before the compaction entry. - `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions) -- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name) +- `fromHook`: `true` if generated by an extension, `false`/`undefined` if generated by the agent itself (legacy field name) - `firstKeptEntryId`: for compatibility with old entry format. ### BranchSummaryEntry @@ -260,7 +260,7 @@ Created when switching branches via `/tree` with an LLM generated summary of the Optional fields: - `usage`: LLM usage from generating the summary; included in session token and cost totals - `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions -- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name) +- `fromHook`: `true` if generated by an extension, `false`/`undefined` if generated by the agent itself (legacy field name) ### CustomEntry diff --git a/packages/coding-agent/docs/settings.md b/packages/coding-agent/docs/settings.md index 33c40c74..985e1668 100644 --- a/packages/coding-agent/docs/settings.md +++ b/packages/coding-agent/docs/settings.md @@ -313,7 +313,7 @@ String form loads all resources from a package: ```json { - "packages": ["pi-skills", "@org/my-extension"] + "packages": ["step-skills", "@org/my-extension"] } ``` @@ -323,7 +323,7 @@ Object form filters which resources to load: { "packages": [ { - "source": "pi-skills", + "source": "step-skills", "skills": ["brave-search", "transcribe"], "extensions": [] } @@ -357,7 +357,7 @@ See [packages.md](packages.md) for package management details. "warnings": { "anthropicExtraUsage": true }, - "packages": ["pi-skills"] + "packages": ["step-skills"] } ``` diff --git a/packages/coding-agent/docs/skills.md b/packages/coding-agent/docs/skills.md index 4188ad30..acb62f65 100644 --- a/packages/coding-agent/docs/skills.md +++ b/packages/coding-agent/docs/skills.md @@ -31,7 +31,7 @@ Step loads skills from: - Project (only after the project is trusted): - `.stepcode/skills/` - `.agents/skills/` and `.claude/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo) -- Packages: `skills/` directories or `pi.skills` entries in `package.json` +- Packages: `skills/` directories, or `pi.skills` entries in `package.json` (the manifest key keeps its legacy name; see [Packages](packages.md)) - Settings: `skills` array with files or directories - CLI: `--skill ` (repeatable, additive even with `--no-skills`) @@ -236,4 +236,4 @@ cd /path/to/brave-search && npm install ## Skill Repositories - [Anthropic Skills](https://github.com/anthropics/skills) - Document processing (docx, pdf, pptx, xlsx), web development -- [Step Skills](https://github.com/badlogic/pi-skills) - Web search, browser automation, Google APIs, transcription +- [Skills collection](https://github.com/badlogic/pi-skills) - Web search, browser automation, Google APIs, transcription diff --git a/packages/coding-agent/docs/step-integration.md b/packages/coding-agent/docs/step-integration.md index 00271dbd..527b8702 100644 --- a/packages/coding-agent/docs/step-integration.md +++ b/packages/coding-agent/docs/step-integration.md @@ -1,48 +1,48 @@ # Step Integration -The Step entrypoint is intentionally an adapter around pi's coding-agent -runtime. The Step entrypoint sets product defaults and calls `main()` with the -Step extension; it does not create a second event loop or a second TUI. +The Step entrypoint is intentionally a thin adapter around the shared +coding-agent runtime. It sets product defaults and calls `main()` with the Step +extension; it does not create a second event loop or a second TUI. ## Ownership - `InteractiveMode`, selectors, overlays, rendering, and input decoding stay in - pi. Step selects a presentation-only `StepEditor` subclass that delegates - `handleInput()` to pi's `CustomEditor`, plus Step welcome/footer components; - these wrappers only format rendered lines and never own input or session - state. + the shared runtime. Step selects a presentation-only `StepEditor` subclass + that delegates `handleInput()` to the native `CustomEditor`, plus Step + welcome/footer components; these wrappers only format rendered lines and + never own input or session state. - `AgentSessionRuntime` remains the session and agent-loop authority. - `extensions/step-provider` supplies the Step model catalog and browser OAuth - flow through pi's provider API. + flow through the shared provider API. - `stepcode.ts` is a forwarding facade for hosts that need a Step-named boundary; it delegates prompt, queue, model, event, and disposal operations - directly to pi. Event subscriptions follow the active session when pi handles - `/new`, `/resume`, or `/fork`. + directly to the runtime. Event subscriptions follow the active session when + the runtime handles `/new`, `/resume`, or `/fork`. - `step/stdio.ts` contains the length-prefixed frame codec and the small transport-neutral event bridge. - `step/feedback/` owns Step's user-initiated feedback contract: input validation and redaction, collector endpoint selection, optional diagnostics - and session-bundle construction, ordered delivery, and pending retries. Pi - supplies the active `SessionManager` and extension UI; feedback does not own - session state or participate in the agent loop. + and session-bundle construction, ordered delivery, and pending retries. The + runtime supplies the active `SessionManager` and extension UI; feedback does + not own session state or participate in the agent loop. - `step/stdio-host.ts` is the optional `step --sdk-stdio` adapter. It owns only framing, request validation, reverse UI requests, and wire projections. Query declared SDK tools and lifecycle hooks are installed as temporary wrappers - around Pi's public `Agent` callbacks; their actual execution, validation, - transcript updates, and abort semantics still run in Pi's agent loop. The - host rebinds after session replacement and serializes writes so stdout stays - a valid byte stream. Unsupported query options are reported in the init + around the runtime's public `Agent` callbacks; their actual execution, + validation, transcript updates, and abort semantics still run in the shared + agent loop. The host rebinds after session replacement and serializes writes + so stdout stays a valid byte stream. Unsupported query options are reported in the init message instead of being silently ignored. The stdio handshake advertises `streaming-input`, `sdk-tools`, `permission-callback`, `hooks`, and `sessions`. Partial text events are emitted only when `includePartialMessages` is enabled; final assistant and - tool-result events always come from the Pi session event stream. + tool-result events always come from the runtime session event stream. ## Product defaults The `step` entrypoint uses `STEP_CODING_AGENT_DIR` and -`STEP_CODING_AGENT_SESSION_DIR` when present. Without a session override, Pi's +`STEP_CODING_AGENT_SESSION_DIR` when present. Without a session override, the native layout is `~/.stepcode/agent/sessions/`. Project-local resources use `.stepcode/`. When no explicit theme has been saved, the built-in `step-blue` palette is used for either terminal appearance, without @@ -51,18 +51,18 @@ automatic violet light/dark switching. Non-interactive `step --export` uses the same precedence as startup: explicit `--use-theme`, saved settings, then the Step product default. Set `STEP_PROVIDER`, `STEP_MODEL`, `STEP_API_KEY`, or the provider endpoint -variables to override the defaults. The Step launcher also disables pi release -and install checks so the product does not contact upstream services. +variables to override the defaults. The Step launcher also disables upstream +release and install checks so the product does not contact those services. The Step `Working...` row measures elapsed time from `agent_start` across model and tool turns. While a response streams, it estimates output tokens from the normalized thinking, text, and tool-call deltas at four characters per token; positive final `usage.output` replaces that response's estimate. Anthropic and OpenAI-compatible providers share this normalized event path. The `thinking` -label follows thinking events and clears when text or tool output begins. Pi's +label follows thinking events and clears when text or tool output begins. The native presentation does not run this tracker or display these metrics. -The built-in Step provider uses pi's `anthropic-messages` adapter. Pi appends +The built-in Step provider uses the `anthropic-messages` adapter, which appends `/v1/messages` to the configured base URL, so the canonical Step base is `https://api.stepfun.com/step_plan`. For compatibility, `STEP_BASE_URL` also accepts the older `.../v1` and `.../v1/messages` spellings; the provider @@ -121,32 +121,32 @@ reusing the value would authenticate a gateway key against `api.stepfun.com` and fail. Session storage is also selected through the Step wrapper. The wrapper keeps -Pi's `SessionManager` class, JSONL format, and tree operations unchanged, but -binds its `create`, `open`, `continueRecent`, `forkFrom`, `list`, and `listAll` +the native `SessionManager` class, JSONL format, and tree operations unchanged, +but binds its `create`, `open`, `continueRecent`, `forkFrom`, `list`, and `listAll` operations to the active Step agent root. Runtime replacement flows (`/new`, `/resume`, `/fork`, and `/import`) use that same bound factory, so a later -operation cannot fall back to Pi's default `~/.stepcode/agent/sessions` directory. +operation cannot fall back to the default `~/.stepcode/agent/sessions` +directory. Managed `fd` and `rg` binaries follow the same explicit `agentDir` boundary and are installed under `/bin`. -These presentation/runtime switches are passed to pi's composition root as +These presentation/runtime switches are passed to the composition root as explicit options: `defaultTheme` selects the single blue Step palette and `disableBackgroundServices` suppresses optional catalog, update, and install telemetry work. It is deliberately distinct from interactive `offline` mode, so disabling those background services does not prevent the first-run OAuth flow. `tuiStyle: "step"` selects the Step presentation variant for the native interactive mode. The shared `main.ts`, InteractiveMode, and theme controller -do not inspect Step-specific environment variables; the ordinary `pi` entrypoint -does not pass these options and keeps its upstream defaults. +do not inspect Step-specific environment variables; callers that pass no such +options keep the default behavior. Step also injects a settings decorator through `settingsManagerFactory`. The -decorator delegates Pi's complete `SettingsManager` API, including global and +decorator delegates the complete `SettingsManager` API, including global and project merging, trust, reload, and flush. Product-only permission policy is kept in the unified `config.toml` files at `~/.stepcode/config.toml` and `/.stepcode/config.toml`, with the same global-then-project precedence and file locking. This keeps fields such as `permissionPreset` and `autoResume` out -of Pi's native `settings.json` schema while leaving ordinary Pi startup -unchanged. +of the native `settings.json` schema while leaving default startup unchanged. Top-level `step feedback` and interactive `/feedback` use a Step-owned gate, configured by `feedbackEnabled` in the Step config and the legacy feedback @@ -174,14 +174,14 @@ cannot succeed and the report or archive must be changed before resubmission. Embedded Step hosts can use `createStepAgentSession()` or `createStepAgentSessionServices()` from the Step surface. These are thin -wrappers around Pi's corresponding factories: they resolve the Step global -agent directory and decorate an existing Pi manager when one is supplied. -They do not alter Pi's session file format or agent loop. Callers that supply a -custom or in-memory Pi manager should pass explicit `stepSettingsPaths` when +wrappers around the corresponding factories: they resolve the Step global +agent directory and decorate an existing manager when one is supplied. +They do not alter the session file format or agent loop. Callers that supply a +custom or in-memory manager should pass explicit `stepSettingsPaths` when they need to control where the Step sidecar is stored. -`/init` submits a Codex-style repository-instructions prompt through pi's -normal user-message path. The model inspects the project and uses pi's native +`/init` submits a Codex-style repository-instructions prompt through the +normal user-message path. The model inspects the project and uses the native write and approval flow; the prompt explicitly preserves an existing `AGENTS.md` instead of replacing it. @@ -200,7 +200,7 @@ over the 120-second default. For a server, watcher, or longer job, use `run_in_background: true`, inspect the returned log path, and stop the process with the returned command when it is no longer needed. Background execution keeps its session-bound lifecycle and ignores the foreground timeout fields. -Pi's separate native `bash` tool retains its optional timeout contract. +The separate native `bash` tool retains its optional timeout contract. On Linux, timeout and abort cleanup snapshots the command's current descendants before killing its process group. Descendants in separate process groups are @@ -428,22 +428,22 @@ separation, not model-specific restrictions on which task tools are available. ## Compatibility matrix The following is the current audit against the previous StepCode. “Native” -means the behavior is supplied by Pi and is intentionally not duplicated in +means the behavior is supplied by the shared runtime and is intentionally not duplicated in the Step layer; “adapter” means a small wrapper in `src/step/` or the Step extension. Entries marked “separate product” require a gateway or external service and are not silently faked by this fork. | Previous Step surface | Current ownership | State | | --- | --- | --- | -| Model/provider selection, compaction, resume, fork, new session | Pi native commands and `SessionManager` | aligned | +| Model/provider selection, compaction, resume, fork, new session | Native commands and `SessionManager` | aligned | | StepCode OAuth login/logout and legacy credential normalization | `features/step-provider`, `step/auth.ts`, `step/models-endpoint-repair.ts` | aligned; endpoint repair is tested | -| Global/project settings and session paths | Pi managers wrapped by `step/settings-manager.ts` and `step/session.ts` | aligned; writes use `.stepcode` | -| Step permissions, `/permissions`, `/init` | Step extension/facades over Pi selectors and hooks | aligned; `/effort` replaces Pi's native `/thinking`, while `/permission` and `/mode` remain absent | +| Global/project settings and session paths | Native managers wrapped by `step/settings-manager.ts` and `step/session.ts` | aligned; writes use `.stepcode` | +| Step permissions, `/permissions`, `/init` | Step extension/facades over native selectors and hooks | aligned; `/effort` replaces the native `/thinking`, while `/permission` and `/mode` remain absent | | Built-in `search_web` | Step tool profile backed by `stepsearch.web_search` over Streamable HTTP MCP | aligned; uses search-specific environment overrides and the Step login credential fallback | -| Top-level `step feedback` and TUI `/feedback` | `step/feedback/`, `stepcode.ts`, and the Step extension over Pi's current session/UI | aligned; the body and optional session bundle use separate Step collector requests | +| Top-level `step feedback` and TUI `/feedback` | `step/feedback/`, `stepcode.ts`, and the Step extension over the current session/UI | aligned; the body and optional session bundle use separate Step collector requests | | `/status`, self-memory/skills governance, `/refresh`, `/rewind`, `/copy` full-transcript semantics | Previous gateway/TUI product layer | not yet ported; no misleading alias is registered | | `/multi-agent`, `/connect`, `/trace`, gateway/cron | Previous gateway and external channel services | separate product; requires an explicit Step service implementation | -| Legacy top-level `models`, `serve`, `goal`, and related gateway commands | Previous command dispatcher | separate product; Pi package commands remain unchanged | +| Legacy top-level `models`, `serve`, `goal`, and related gateway commands | Previous command dispatcher | separate product; the package commands remain unchanged | This distinction is deliberate: a missing external service is reported as a gap instead of being represented by a command that appears to work but changes @@ -451,18 +451,18 @@ session or approval semantics. ## Distribution -The npm package exposes both `pi` and `step` from bundled entrypoints. The -standalone archives likewise contain both executables (`pi`/`step`, or their -Windows `.exe` variants); the Step executable uses the same Bun runtime setup as -Pi before loading the Step product adapter. +The npm package exposes a single `step` bin from the bundled entrypoint. The +standalone archives contain the matching `step` executable (`step.exe` on +Windows); it uses the shared Bun runtime setup before loading the Step product +adapter. ## Non-goals This layer does not reimplement editor key handling, UTF-8 buffering, render throttling, selectors, or agent scheduling. Step's permission extension only -defines the product tiers and dangerous-command policy; it invokes Pi's +defines the product tiers and dangerous-command policy; it invokes the native `tool_call` confirmation and `ui.select` flows. Auto-resume likewise -toggles Pi's native retry setting and adds only a bounded continuation after a +toggles the native retry setting and adds only a bounded continuation after a settled retryable failure. Changes to the underlying interaction or scheduling -behavior belong in Pi's shared packages and should be consumed here through +behavior belong in the shared packages and should be consumed here through their public APIs. diff --git a/packages/coding-agent/docs/themes.md b/packages/coding-agent/docs/themes.md index 8aca0601..5416bae7 100644 --- a/packages/coding-agent/docs/themes.md +++ b/packages/coding-agent/docs/themes.md @@ -21,7 +21,7 @@ Step loads themes from: - Built-in: `dark`, `light`, `sage`, `step-blue`, `step-violet`, `step-violet-light` - Global: `~/.stepcode/agent/themes/*.json` - Project: `.stepcode/themes/*.json` (only after the project is trusted) -- Packages: `themes/` directories or `pi.themes` entries in `package.json` +- Packages: `themes/` directories, or `pi.themes` entries in `package.json` (the manifest key keeps its legacy name; see [Packages](packages.md)) - Settings: `themes` array with files or directories - CLI: `--theme ` (repeatable) diff --git a/packages/coding-agent/docs/tui.md b/packages/coding-agent/docs/tui.md index d0d85e8e..ae99521f 100644 --- a/packages/coding-agent/docs/tui.md +++ b/packages/coding-agent/docs/tui.md @@ -1,4 +1,4 @@ -> pi can create TUI components. Ask it to build one for your use case. +> step can create TUI components. Ask it to build one for your use case. # TUI Components @@ -757,7 +757,7 @@ ctx.ui.setStatus("my-ext", undefined); ### Pattern 4b: Working Indicator Customization -Customize the inline working indicator shown while pi is streaming a response. +Customize the inline working indicator shown while step is streaming a response. ```typescript // Static indicator @@ -777,7 +777,7 @@ ctx.ui.setWorkingIndicator({ // Hide the indicator entirely ctx.ui.setWorkingIndicator({ frames: [] }); -// Restore pi's default spinner +// Restore the default spinner ctx.ui.setWorkingIndicator(); ``` diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.md index 4fdebeae..b423bc8e 100644 --- a/packages/coding-agent/docs/usage.md +++ b/packages/coding-agent/docs/usage.md @@ -306,4 +306,4 @@ Step keeps the core small and pushes workflow-specific behavior into extensions, It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux. -For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/). +For the full rationale, see [the philosophy section of the README](../README.md#philosophy). diff --git a/packages/coding-agent/examples/README.md b/packages/coding-agent/examples/README.md index 87505184..c3b7b3bf 100644 --- a/packages/coding-agent/examples/README.md +++ b/packages/coding-agent/examples/README.md @@ -1,6 +1,6 @@ # Examples -Example code for pi-coding-agent SDK and extensions. +Example code for the coding agent SDK and extensions. ## Directories diff --git a/packages/coding-agent/examples/extensions/README.md b/packages/coding-agent/examples/extensions/README.md index 42f952a9..c615f225 100644 --- a/packages/coding-agent/examples/extensions/README.md +++ b/packages/coding-agent/examples/extensions/README.md @@ -1,15 +1,15 @@ # Extension Examples -Example extensions for pi-coding-agent. +Example extensions for the step coding agent. ## Usage ```bash # Load an extension with --extension flag -pi --extension examples/extensions/permission-gate.ts +step --extension examples/extensions/permission-gate.ts # Or copy to extensions directory for auto-discovery -cp permission-gate.ts ~/.pi/agent/extensions/ +cp permission-gate.ts ~/.stepcode/agent/extensions/ ``` ## Examples @@ -99,7 +99,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/ | Extension | Description | |-----------|-------------| -| `mac-system-theme.ts` | Syncs pi theme with macOS dark/light mode | +| `mac-system-theme.ts` | Syncs step theme with macOS dark/light mode | ### Resources diff --git a/packages/coding-agent/examples/extensions/doom-overlay/README.md b/packages/coding-agent/examples/extensions/doom-overlay/README.md index 420bd80b..c8d21bbd 100644 --- a/packages/coding-agent/examples/extensions/doom-overlay/README.md +++ b/packages/coding-agent/examples/extensions/doom-overlay/README.md @@ -1,11 +1,11 @@ # DOOM Overlay Demo -Play DOOM as an overlay in pi. Demonstrates that the overlay system can handle real-time game rendering at 35 FPS. +Play DOOM as an overlay in step. Demonstrates that the overlay system can handle real-time game rendering at 35 FPS. ## Usage ```bash -pi --extension ./examples/extensions/doom-overlay +step --extension ./examples/extensions/doom-overlay ``` Then run: @@ -43,4 +43,4 @@ Height is calculated from width to maintain DOOM's 3.2:1 aspect ratio (accountin - [id Software](https://github.com/id-Software/DOOM) for the original DOOM - [doomgeneric](https://github.com/ozkl/doomgeneric) for the portable DOOM implementation -- [pi-doom](https://github.com/badlogic/pi-doom) for the original pi integration +- [pi-doom](https://github.com/badlogic/pi-doom) for the original upstream integration diff --git a/packages/coding-agent/examples/extensions/subagent/README.md b/packages/coding-agent/examples/extensions/subagent/README.md index 351e78d2..1ab028ed 100644 --- a/packages/coding-agent/examples/extensions/subagent/README.md +++ b/packages/coding-agent/examples/extensions/subagent/README.md @@ -4,7 +4,7 @@ Delegate tasks to specialized subagents with isolated context windows. ## Features -- **Isolated context**: Each subagent runs in a separate `pi` process +- **Isolated context**: Each subagent runs in a separate `step` process - **Streaming output**: See tool calls and progress as they happen - **Parallel streaming**: All parallel tasks stream updates simultaneously - **Markdown rendering**: Final output rendered with proper formatting (expanded view) @@ -35,30 +35,30 @@ From the repository root, symlink the files: ```bash # Symlink the extension (must be in a subdirectory with index.ts) -mkdir -p ~/.pi/agent/extensions/subagent -ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.pi/agent/extensions/subagent/index.ts -ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts +mkdir -p ~/.stepcode/agent/extensions/subagent +ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.stepcode/agent/extensions/subagent/index.ts +ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.stepcode/agent/extensions/subagent/agents.ts # Symlink agents -mkdir -p ~/.pi/agent/agents +mkdir -p ~/.stepcode/agent/agents for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do - ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f") + ln -sf "$(pwd)/$f" ~/.stepcode/agent/agents/$(basename "$f") done # Symlink workflow prompts -mkdir -p ~/.pi/agent/prompts +mkdir -p ~/.stepcode/agent/prompts for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do - ln -sf "$(pwd)/$f" ~/.pi/agent/prompts/$(basename "$f") + ln -sf "$(pwd)/$f" ~/.stepcode/agent/prompts/$(basename "$f") done ``` ## Security Model -This tool executes a separate `pi` subprocess with a delegated system prompt and tool/model configuration. +This tool executes a separate `step` subprocess with a delegated system prompt and tool/model configuration. -**Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc. +**Project-local agents** (`.stepcode/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc. -**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`. +**Default behavior:** Only loads **user-level agents** from `~/.stepcode/agent/agents`. To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust. @@ -140,8 +140,8 @@ System prompt for the agent goes here. When `model` is omitted, the subagent inherits the dispatching session's active model and thinking level. **Locations:** -- `~/.pi/agent/agents/*.md` - User-level (always loaded) -- `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`) +- `~/.stepcode/agent/agents/*.md` - User-level (always loaded) +- `.stepcode/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`) Project agents override user agents with the same name when `agentScope: "both"`. diff --git a/packages/coding-agent/examples/sdk/README.md b/packages/coding-agent/examples/sdk/README.md index 9899b49f..efaa8a74 100644 --- a/packages/coding-agent/examples/sdk/README.md +++ b/packages/coding-agent/examples/sdk/README.md @@ -1,6 +1,6 @@ # SDK Examples -Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`. +Programmatic usage of the coding agent via `createAgentSession()` and `createAgentSessionRuntime()`. The runtime example shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes. @@ -107,7 +107,7 @@ await session.prompt("Hello"); |--------|---------|-------------| | `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime | | `cwd` | `process.cwd()` | Working directory | -| `agentDir` | `~/.pi/agent` | Config directory | +| `agentDir` | `~/.stepcode/agent` | Config directory | | `model` | From settings/first available | Model to use | | `thinkingLevel` | From settings/"off" | off, low, medium, high | | `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools | diff --git a/packages/providers/README.md b/packages/providers/README.md index b2a3d5e6..7c6cc0bc 100644 --- a/packages/providers/README.md +++ b/packages/providers/README.md @@ -69,7 +69,7 @@ DeepSeek, ZAI, Qwen, Kimi, OpenRouter, Ant Ling, and OpenCode. Configure providers and models at runtime against any OpenAI- or Anthropic-compatible endpoint on those protocols: -- Declare custom providers in `~/.pi/agent/models.json`. +- Declare custom providers in `~/.stepcode/agent/models.json`. - Fetch a live catalog from a provider's `/v1/models` endpoint (for example the Step provider registered by the product). - Build a provider from parts with `createProvider()` (see [Custom Providers](#custom-providers)). @@ -359,7 +359,7 @@ Header names are merged case-insensitively. Explicit headers override auth/model ### Credential Store -Stored credentials (API keys entered interactively, OAuth tokens) live in a `CredentialStore` — one type-tagged credential per provider. pi-ai ships an in-memory default; apps inject persistent storage: +Stored credentials (API keys entered interactively, OAuth tokens) live in a `CredentialStore` — one type-tagged credential per provider. This package ships an in-memory default; apps inject persistent storage: ```typescript import { createModels, type CredentialStore } from '@step-harness/providers'; @@ -369,7 +369,7 @@ const models = createModels({ credentials: myFileBackedStore }); The contract is small: `read(providerId)`, `list()` for non-secret `{ providerId, type }` metadata, `modify(providerId, fn)` (the only write path — a serialized read-modify-write), and `delete(providerId)`. Each operation accepts optional cancellation options. Enumeration must not resolve secrets or execute configured key commands. OAuth token refresh runs inside `modify`, so concurrent requests and processes cannot double-refresh a rotated token. A stored credential *owns* its provider: environment variables are only consulted when nothing is stored, and a failed refresh never silently falls back to an env key. -API-key credentials use the same discriminator as pi's `auth.json` and can carry provider-scoped env/config values: +API-key credentials use the same discriminator as the agent `auth.json` and can carry provider-scoped env/config values: ```typescript const credential = { @@ -644,7 +644,7 @@ All streaming events emitted during assistant message generation: | `done` | Stream complete | `reason`: Stop reason ("stop", "length", "toolUse"), `message`: Final assistant message | | `error` | Error occurred | `reason`: Error type ("error" or "aborted"), `error`: AssistantMessage with partial content | -Streaming events for different content blocks are not guaranteed to be contiguous. Providers may emit deltas for text, thinking, and tool calls in the same upstream chunk, and pi may surface corresponding events interleaved, for example `text_start`, `text_delta`, `toolcall_start`, `text_delta`, `toolcall_delta`. Consumers must use `contentIndex` to associate each delta/end event with its block and must not assume that a block's `*_start`/`*_delta`/`*_end` sequence is uninterrupted by events for other blocks. +Streaming events for different content blocks are not guaranteed to be contiguous. Providers may emit deltas for text, thinking, and tool calls in the same upstream chunk, and the runtime may surface corresponding events interleaved, for example `text_start`, `text_delta`, `toolcall_start`, `text_delta`, `toolcall_delta`. Consumers must use `contentIndex` to associate each delta/end event with its block and must not assume that a block's `*_start`/`*_delta`/`*_end` sequence is uninterrupted by events for other blocks. ## Image Input @@ -992,7 +992,7 @@ Custom models can carry `headers` (e.g. proxies behind bot detection) and `compa Some OpenAI-compatible servers do not understand the `developer` role used for reasoning-capable models. For those providers, set `compat.supportsDeveloperRole` to `false` so the system prompt is sent as a `system` message instead. If the server also does not support `reasoning_effort`, set `compat.supportsReasoningEffort` to `false` too. This commonly applies to Ollama, vLLM, SGLang, and similar OpenAI-compatible servers. -Use model-level `thinkingLevelMap` to describe model-specific thinking controls. Keys are pi thinking levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). Missing standard levels through `high` use provider defaults; `xhigh` and `max` are opt-in and require a non-null map entry. String values are sent to the provider, `null` marks a level unsupported, and maps may skip levels. +Use model-level `thinkingLevelMap` to describe model-specific thinking controls. Keys are agent thinking levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). Missing standard levels through `high` use provider defaults; `xhigh` and `max` are opt-in and require a non-null map entry. String values are sent to the provider, `null` marks a level unsupported, and maps may skip levels. ```typescript const ollamaReasoningModel: Model<'openai-completions'> = { @@ -1064,8 +1064,8 @@ interface OpenAICompletionsCompat { requiresThinkingAsText?: boolean; // Whether thinking blocks must be converted to text (default: false) requiresReasoningContentOnAssistantMessages?: boolean; // Whether all replayed assistant messages must include empty reasoning_content when reasoning is enabled (default: auto-detected for DeepSeek) thinkingFormat?: 'openai' | 'openrouter' | 'deepseek' | 'together' | 'baseten' | 'zai' | 'qwen' | 'chat-template' | 'qwen-chat-template' | 'string-thinking' | 'ant-ling'; // Format for reasoning param: 'openai' uses reasoning_effort, 'openrouter' uses reasoning: { effort }, 'deepseek' uses thinking: { type } plus reasoning_effort when supported, 'together' uses reasoning: { enabled } plus reasoning_effort when supported, 'baseten' uses configurable chat_template_args plus reasoning_effort when supported, 'zai' uses thinking: { type }, 'qwen' uses enable_thinking, 'chat-template' uses configurable chat_template_kwargs, 'qwen-chat-template' uses chat_template_kwargs.enable_thinking and preserve_thinking, 'string-thinking' uses top-level thinking, 'ant-ling' uses reasoning: { effort } only for mapped efforts (default: openai) - chatTemplateKwargs?: Record; // chat_template_kwargs values; use $var for pi-controlled thinking values - chatTemplateArgs?: Record; // chat_template_args values for thinkingFormat: 'baseten'; use $var for pi-controlled thinking values + chatTemplateKwargs?: Record; // chat_template_kwargs values; use $var for agent-controlled thinking values + chatTemplateArgs?: Record; // chat_template_args values for thinkingFormat: 'baseten'; use $var for agent-controlled thinking values thinkingTokenBudgetField?: 'thinking_token_budget' | 'thinking_budget' | 'thinking_budget_tokens'; // Top-level field that caps reasoning tokens from thinkingBudgets (vLLM / Qwen / llama.cpp). Off by default. supportsThinkingTokenBudget?: boolean; // Alias for thinkingTokenBudgetField: 'thinking_token_budget' (vLLM). Prefer thinkingTokenBudgetField. Default: false. cacheControlFormat?: 'anthropic'; // Anthropic-style cache_control on system prompt, last tool, and last user/assistant text content @@ -1411,7 +1411,7 @@ Compat is a strict superset of the root entrypoint, so a file can switch its imp ### Adding a New Provider -> The Step-only build ships no built-in providers; the supported way to add one is [`createProvider()`](#createprovider) / a `~/.pi/agent/models.json` entry, no package changes required. +> The Step-only build ships no built-in providers; the supported way to add one is [`createProvider()`](#createprovider) / a `~/.stepcode/agent/models.json` entry, no package changes required. Adding a new LLM provider requires changes across multiple files. The layered layout: API implementations live in `src/api/`, provider factories in `src/providers/`, stable generated catalog wrappers live in `src/providers/.models.ts`, and `src/models.generated.ts` registers them. This checklist covers all necessary steps: diff --git a/packages/telemetry/README.md b/packages/telemetry/README.md index a4c298e1..6414749e 100644 --- a/packages/telemetry/README.md +++ b/packages/telemetry/README.md @@ -1,6 +1,6 @@ # @step-harness/telemetry -Vendor-neutral telemetry contracts and typed schema utilities for pi packages. +Vendor-neutral telemetry contracts and typed schema utilities for step packages. This package provides: @@ -10,7 +10,7 @@ This package provides: - serializable schema definitions with inferred TypeScript types; - no exporter, global current-span state, or dependency on a telemetry backend. -Applications can use the in-memory reference or provide an adapter for OpenTelemetry, Sentry, logs, or another backend. Pi packages pass telemetry contexts explicitly and define their domain schemas separately. +Applications can use the in-memory reference or provide an adapter for OpenTelemetry, Sentry, logs, or another backend. Step packages pass telemetry contexts explicitly and define their domain schemas separately. ## Table of Contents @@ -24,7 +24,7 @@ Applications can use the in-memory reference or provide an adapter for OpenTelem - [Typed Schemas](#typed-schemas) - [Start and Completion Attributes](#start-and-completion-attributes) - [Schema Metadata](#schema-metadata) -- [Pi Package Integration](#pi-package-integration) +- [Package Integration](#package-integration) - [Security and Portability](#security-and-portability) - [API Reference](#api-reference) - [Development](#development) @@ -129,7 +129,7 @@ An adapter implements `TelemetryContext` and bridges the generic API to its back - ignore calls made after settlement; - ignore a failed recording call atomically, suppress backend failures, and still execute the business callback exactly once. -Adapters may activate backend-native ambient context internally for automatic instrumentation, but pi code always propagates the parent through `TelemetryContext` arguments. Exporter buffering, flushing, sampling, backend IDs, and backend-specific context objects belong to the adapter. Use the [adapter conformance suite](#adapter-conformance) to check these observable semantics. +Adapters may activate backend-native ambient context internally for automatic instrumentation, but step code always propagates the parent through `TelemetryContext` arguments. Exporter buffering, flushing, sampling, backend IDs, and backend-specific context objects belong to the adapter. Use the [adapter conformance suite](#adapter-conformance) to check these observable semantics. ## No-op Context @@ -362,13 +362,13 @@ Parent metadata is descriptive schema data: Adapters do not need to understand schema objects. Instrumentation helpers and tests use them to keep emitted names and attributes consistent. -## Pi Package Integration +## Package Integration Package ownership is intentionally split: - `@step-harness/telemetry` owns the vendor-neutral contract, no-op and in-memory reference contexts, schema utilities, and adapter conformance suite; - `@step-harness/providers` accepts and propagates `telemetryContext` in provider request options but owns no telemetry schema; -- `@step-harness/agent-core` owns and exports the pi AI-request and harness schemas, their combined readonly schema tuple, and typed span helpers. +- `@step-harness/agent-core` owns and exports the AI-request and harness schemas, their combined readonly schema tuple, and typed span helpers. ```typescript import { @@ -380,7 +380,7 @@ import { } from '@step-harness/agent-core'; ``` -The pi schemas use pi-owned `pi.ai.*`, `pi.harness.*`, and `pi.session.*` names. Adapters may translate them to backend conventions without changing the emitted pi vocabulary. +The schemas use `pi.ai.*`, `pi.harness.*`, and `pi.session.*` span names. That prefix is part of the emitted telemetry contract, so adapters may translate it to backend conventions but the vocabulary itself does not change. ## Security and Portability diff --git a/packages/tui/docs/editor-styling.md b/packages/tui/docs/editor-styling.md index 26653586..64c9c9c1 100644 --- a/packages/tui/docs/editor-styling.md +++ b/packages/tui/docs/editor-styling.md @@ -6,4 +6,4 @@ Subclasses may override the protected `styleText(text, line, startIndex)` hook t - The hook runs after wrapping and scrolling. A fragment can be part of a longer token or only one side of the cursor. - Preserve the input characters and display width. Only add self-contained ANSI styles that reset before the fragment ends. - The cursor grapheme, cursor marker, padding, borders and autocomplete list bypass this hook. The base implementation returns the text unchanged. -- Product-specific keyword detection, theme resolution and animation lifecycle belong to the caller, not `pi-tui`. +- Product-specific keyword detection, theme resolution and animation lifecycle belong to the caller, not `@step-harness/pi-tui`.