@geoqiao/paseo-btw 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +97 -64
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,31 +1,66 @@
1
- # @geoqiao/paseo-btw
1
+ # Paseo BTW
2
2
 
3
- Portable Pi commands and [Agent Skills](https://agentskills.io/) for orchestrating coding agents
4
- through [Paseo](https://paseo.sh/).
3
+ [![npm version](https://img.shields.io/npm/v/@geoqiao/paseo-btw)](https://www.npmjs.com/package/@geoqiao/paseo-btw)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
5
5
 
6
- ## Included tools
6
+ **Ask a side question without interrupting the main task.**
7
7
 
8
- ### `/btw` and `paseo-btw`
8
+ `@geoqiao/paseo-btw` opens a lightweight conversation in the same [Paseo](https://paseo.sh/) workspace. The child appears in the **Subagents** track, while you continue working with the parent. In Paseo-managed Pi sessions, the native `/btw` command launches it without a parent LLM turn.
9
9
 
10
- Starts a lightweight side conversation without interrupting the main task.
11
- The side agent runs in the same Paseo workspace and appears in the Subagents track.
10
+ ```text
11
+ /btw why might this API return 409?
12
+ ```
13
+
14
+ [Quick start](#quick-start) · [Native command or Skill](#native-command-or-skill) · [Defaults](#defaults-and-configuration) · [Context and limits](#context-and-limits)
15
+
16
+ ## Quick start
17
+
18
+ ### Prerequisites
19
+
20
+ Run inside a **Paseo-managed agent**. Native Pi commands require the `paseo` CLI to be available; they use the parent identity supplied by Paseo through `PASEO_AGENT_ID`.
21
+
22
+ For the portable Skill, enable orchestration tools under **Settings → your host → Agents → Enable Paseo tools**, then start a new agent or reload the current one. The Skill prefers injected Paseo tools and falls back to the CLI when unavailable.
23
+
24
+ ### Pi
25
+
26
+ ```bash
27
+ pi install npm:@geoqiao/paseo-btw
28
+ ```
12
29
 
13
- In Paseo's Pi provider, use the native extension command:
30
+ Run `/reload` in an already-open Pi session, then ask your side question:
14
31
 
15
32
  ```text
16
- /btw why might this API return 409?
33
+ /btw explain this stack trace
34
+ ```
35
+
36
+ The extension also registers `/paseo-btw`. If another extension owns `/btw`, Pi assigns numeric suffixes; use `/paseo-btw` to avoid that collision.
37
+
38
+ ### Claude Code, Codex, and other Agent Skills clients
39
+
40
+ Install the portable [Agent Skill](https://agentskills.io/) from the repository:
41
+
42
+ ```bash
43
+ npx skills add geoqiao/pi-tools --skill paseo-btw --agent '*' -g
17
44
  ```
18
45
 
19
- The extension also registers the collision-free alias `/paseo-btw`. If another installed extension
20
- already owns `/btw`, Pi assigns numeric suffixes; use `/paseo-btw` or remove the conflicting package.
46
+ Invoke the installed `paseo-btw` Skill using your client's command syntax. Claude Code and Codex may expose `/paseo-btw`; Pi uses `/skill:paseo-btw`. These clients still need a Paseo-managed session and orchestration access—the Skill is not a standalone agent service.
21
47
 
22
- `/btw` is handled before Pi starts an LLM turn. A packaged Node CLI reads the parent settings,
23
- captures inherited context when enabled, and calls `paseo run --background` directly. The text
24
- after `/btw` is passed unchanged as the side question, so the parent transcript gets no reasoning
25
- or tool-call loop.
48
+ The npm package has no install-time script that edits agent configuration. Pi reads its extension and skill manifests; other clients use the skills installer.
26
49
 
27
- The Agent Skill remains a compatibility fallback for Codex, Claude Code, and clients that cannot
28
- load Pi extensions. It necessarily uses one parent model turn:
50
+ ## Native command or Skill?
51
+
52
+ | Capability | Native Pi extension | Model-mediated Skill fallback |
53
+ |---|---|---|
54
+ | Entry point | `/btw` or `/paseo-btw` | Installed Skill command in the host client |
55
+ | Parent model turn | None; the extension calls the launcher directly | One orchestration turn |
56
+ | Defaults | Inherits parent provider/model, thinking setting, and bounded text context | Same defaults; can also copy mode and feature values |
57
+ | Configuration | `/btw-config` | Skill `config` requests |
58
+ | One-off model selectors | Not parsed from the side question; use `/btw-config` | Supports `--model`, `--provider`, and `--profile` |
59
+ | Context | `inherit` or `none` | `inherit`, semantic `summary`, or `none` |
60
+
61
+ **When the Pi extension is loaded, it also intercepts `/skill:paseo-btw` before Skill expansion.** That path behaves like the native command, not the model-mediated fallback. Text after the command is forwarded as the side question rather than parsed as Skill flags.
62
+
63
+ For hosts actually using the model-mediated Skill, examples in Pi-style notation are:
29
64
 
30
65
  ```text
31
66
  /skill:paseo-btw why might this API return 409?
@@ -33,79 +68,77 @@ load Pi extensions. It necessarily uses one parent model turn:
33
68
  /skill:paseo-btw --profile 低成本精修 explain this stack trace
34
69
  ```
35
70
 
36
- When the Pi extension is loaded, it intercepts `/skill:paseo-btw ...` before Skill expansion and
37
- routes it through the same zero-parent-turn CLI. The model-mediated behavior above applies only to
38
- hosts that cannot load the extension.
71
+ Use your host's equivalent invocation syntax. Continue follow-up discussion in the existing child tab rather than starting a new child for every message.
39
72
 
40
- The native command inherits the parent's Paseo provider/model and thinking setting plus a bounded
41
- mechanical snapshot of the parent's Paseo text timeline by default. The model-mediated Skill can
42
- also copy mode and feature values. Configure persistent defaults with:
73
+ ## Defaults and configuration
74
+
75
+ The native command inherits the parent's model and context unless configured otherwise. View current settings without launching a side agent:
43
76
 
44
77
  ```text
45
78
  /btw-config
79
+ ```
80
+
81
+ | Setting | Default | Example |
82
+ |---|---|---|
83
+ | Model | `inherit` | `/btw-config model claude/claude-haiku-4-5` |
84
+ | Context | `inherit` | `/btw-config context none` |
85
+ | Timeline tail (`paseo logs --tail`) | `40` | `/btw-config context-tail 40` |
86
+ | Context limit | `8000` characters | `/btw-config context-max-chars 8000` |
87
+
88
+ Explicit model values use Paseo's `provider/model` format; Pi model IDs can contain another slash, such as `pi/openai-codex/<model-id>`. Choose a model available in your Paseo setup. Restore inheritance or reset all defaults with:
89
+
90
+ ```text
46
91
  /btw-config model inherit
47
- /btw-config model claude/claude-haiku-4-5
48
92
  /btw-config context inherit
49
- /btw-config context none
50
- /btw-config context-tail 40
51
- /btw-config context-max-chars 8000
52
93
  /btw-config reset
53
94
  ```
54
95
 
55
- `context: inherit` uses documented `paseo logs` output after removing the current turn, applying
56
- best-effort secret redaction, and enforcing a size limit. `context: none` sends only the text after
57
- `/btw`. The legacy `summary` mode is available only through the model-mediated Agent Skill because
58
- creating a semantic summary requires a parent model turn. If mechanical capture is unavailable,
59
- the native command still launches with the side question alone and reports the fallback.
96
+ Settings normally live in `~/.config/pi-tools/btw.json`. `PI_TOOLS_CONFIG_HOME`, then `XDG_CONFIG_HOME`, can override the config root. The portable Skill uses the same persisted settings through its `config` requests; one-off Skill selectors override them for that invocation only.
60
97
 
61
- Paseo's app-level **Fork chat from here** also injects mechanically curated text into a new agent;
62
- it is not a provider-native session clone. Native Pi session forking remains a future opt-in mode
63
- and is deliberately not claimed by this release.
98
+ ## Context and limits
64
99
 
65
- Claude Code and Codex may expose the fallback Skill as `/paseo-btw` instead of Pi's
66
- `/skill:paseo-btw` form. They cannot provide Pi's zero-parent-turn extension command.
100
+ | Mode | What the child receives |
101
+ |---|---|
102
+ | `inherit` | A bounded mechanical snapshot of the parent's Paseo text timeline plus the side question |
103
+ | `none` | The side question without parent history |
104
+ | `summary` | A semantic summary prepared by the parent model; available only through the model-mediated Skill |
67
105
 
68
- ## Prerequisite
106
+ Mechanical capture uses documented `paseo logs` output, removes the current turn and reasoning blocks, strips terminal escapes, applies best-effort secret redaction, and enforces the configured size limit. **Redaction is not a guarantee that all sensitive information is removed.** Inherited text is sent to the child agent and its selected provider; use `context none` when you do not want to forward parent history.
69
107
 
70
- Enable Paseo orchestration tools under **Settings → your host → Agents → Enable Paseo tools**,
71
- then start a new agent or reload the current one. The skill prefers Paseo's injected tools and
72
- falls back to the `paseo` CLI when those tools are unavailable.
108
+ If native capture fails, the side conversation still launches with only the question and reports the fallback. If `summary` was saved through the Skill, the native command sends no parent context and warns that semantic summarization requires a model turn. The model-mediated Skill may instead fall back from failed capture to a semantic summary.
73
109
 
74
- ## Installation
110
+ This is **not a provider-native session clone**. Paseo's app-level **Fork chat from here** also curates text for a new agent; native Pi session forking is not implemented by this package.
75
111
 
76
- ### Pi package
112
+ The side conversation shares the parent's workspace; it does not create a worktree or an isolated sandbox. The portable Skill instructs the child to stay read-only and not take over the main task, but that is guidance, not permission enforcement. The native launcher forwards the question without adding the Skill's read-only response contract. Do not rely on either entry point as a security boundary. Pi's `/skill:paseo-btw` interception cannot forward image attachments through the CLI.
77
113
 
78
- After publication:
114
+ <details>
115
+ <summary>How native launch works</summary>
79
116
 
80
- ```bash
81
- pi install npm:@geoqiao/paseo-btw
82
- ```
117
+ Pi handles the extension command before starting an LLM turn. A packaged Node CLI reads persistent defaults, inspects the parent agent, captures context when enabled, and calls `paseo run --background`. It forwards the side question unchanged after trimming; no parent reasoning or tool-call loop is needed.
83
118
 
84
- ### Claude Code, Codex, and other Agent Skills clients
119
+ The child stays in the current Paseo workspace through the inherited parent identity. With model inheritance enabled, the launcher copies the parent's thinking setting and a mode when it can validate that mode against the parent's available modes. It does not promise a complete copy of every provider feature or native session state.
85
120
 
86
- Install from the Git repository with the standard skills installer:
121
+ See the [portable Skill](skills/paseo-btw/SKILL.md) for model-mediated launch, selector handling, context rules, and CLI fallback behavior.
87
122
 
88
- ```bash
89
- npx skills add geoqiao/pi-tools --skill paseo-btw --agent '*' -g
90
- ```
123
+ </details>
91
124
 
92
- During local development:
125
+ ## Development
126
+
127
+ From the monorepo root:
93
128
 
94
129
  ```bash
95
- npx skills add /absolute/path/to/pi-tools/packages/paseo-btw --skill paseo-btw --agent '*' -g
130
+ pnpm --filter @geoqiao/paseo-btw test
131
+ pnpm --filter @geoqiao/paseo-btw pack:check
96
132
  ```
97
133
 
98
- The npm package intentionally has no install-time script that mutates a user's agent
99
- configuration. npm distributes the files; Pi reads the `pi.extensions` and `pi.skills` manifests,
100
- while other harnesses use the Agent Skills installer.
101
-
102
- ## Development
134
+ To install the local Skill into supported clients:
103
135
 
104
136
  ```bash
105
- npm test
106
- npm run pack:check
107
- npx skills add . --list
137
+ npx skills add ./packages/paseo-btw --skill paseo-btw --agent '*' -g
108
138
  ```
109
139
 
110
- This package is developed in the `pi-tools` monorepo and is published independently from the
111
- other workspace packages.
140
+ See [CONTRIBUTING.md](../../CONTRIBUTING.md) for workspace setup and Changesets. This package is published independently from the other workspace packages.
141
+
142
+ ## License
143
+
144
+ [MIT](LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geoqiao/paseo-btw",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Portable Paseo side-conversation commands and skills for Pi, Codex, and Claude Code.",
5
5
  "type": "module",
6
6
  "files": [
@@ -50,4 +50,4 @@
50
50
  "test": "node --test test/*.test.mjs",
51
51
  "pack:check": "npm pack --dry-run"
52
52
  }
53
- }
53
+ }