@thoth-agents/pi-junie-bridge 0.0.0-stage → 0.1.0

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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,22 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ ## [0.1.0] - 2026-11-15
6
+
7
+ ### Added
8
+
9
+ - Initial Junie ACP model provider using the locally installed, authenticated CLI.
10
+ - Model/effort discovery, streaming, persistent session mappings and Pi tools over
11
+ authenticated loopback MCP.
12
+ - Native-tool permission dialogs with headless rejection and brave mode forced off.
13
+ - On-demand `/junie quota` and `/junie models` commands.
14
+ - Windows Job Object launcher assets and hermetic fake-agent tests.
15
+ - Short Pi model ids mapped to Junie ACP model values.
16
+ - Headless sessions block Junie's native shell and file-mutation tools with a
17
+ model-visible reason pointing to the Pi MCP tools (`pi/bash`, `pi/edit`,
18
+ `pi/write`), so commands and edits follow Pi's tool policy.
19
+ - Per-turn display line with the real Junie model, effort and the cost the bridge
20
+ attributes to that turn (sub-cent costs render as `<$0.0001`). Telemetry is
21
+ fire and forget and never delays the next turn, an abort or shutdown.
22
+ - Process-global state is replaced on extension reload.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 EstebanForge
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,144 @@
1
- # Temporary Holding Version
1
+ # Pi Junie Bridge
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Use your JetBrains AI subscription in Pi through the official Junie CLI. This
4
+ extension registers the `junie` model provider; it is not an AskJunie delegation
5
+ tool or a direct JetBrains inference API client.
6
+
7
+ ## Install
8
+
9
+ Prerequisites: Node >=22.19, Pi >=1.5.0, and the Junie CLI installed and logged in
10
+ with your JetBrains Account. Run `junie` separately to complete login; the bridge
11
+ does not manage credentials or provide Pi `/login` authentication.
12
+
13
+ ```bash
14
+ pi install npm:@thoth-agents/pi-junie-bridge
15
+ ```
16
+
17
+ Restart Pi, run `/junie models` to refresh the available models, then select a
18
+ `junie` model in Pi. Installation is optional/manual, not managed by the Thoth
19
+ installer. If discovery cannot find the CLI, set `JUNIE_BRIDGE_LAUNCHER` to the
20
+ real Junie executable (especially on Windows).
21
+
22
+ ## How it works
23
+
24
+ - Junie runs as an ACP agent provider over stdio. Models and supported effort
25
+ levels are discovered from Junie and cached under Pi's agent directory. Model
26
+ labels use Junie's display names and Pi ids are short (below); Junie always
27
+ receives the exact ACP value. Observed context capacity is cached per model
28
+ and reused on registration (32k fallback until observed). Prompt-response
29
+ token usage is attributed to the terminal message only, not duplicated across
30
+ parked Pi tool segments.
31
+ - Pi lists a model by its id and only prints a name when it differs, so a raw
32
+ ACP value would read as `v1:12:jetbrains-ai:gemini-3.7-flash`. The catalog
33
+ therefore stores both forms: `id` is the Pi-facing short id, the last segment
34
+ of the ACP value, and `value` is the exact ACP value Junie receives.
35
+
36
+ | ACP value | Pi model id |
37
+ | --- | --- |
38
+ | `v1:12:jetbrains-ai:gemini-3.7-flash` | `gemini-3.7-flash` |
39
+ | `v1:12:jetbrains-ai:claude-opus-5-5` | `claude-opus-5-5` |
40
+ | `mix.auto` | `mix.auto` |
41
+ | `v1:12:jetbrains-ai:x` + `v1:99:jetbrains-ai:x` | both keep the full ACP value |
42
+
43
+ Mix presets have no scheme and keep their value as the id. Any ACP value
44
+ without `:` is unchanged, and a segment that would be empty keeps the full
45
+ value. When two ACP values would produce the same short id, both keep their
46
+ full ACP value, so two models never collapse into one entry. Selecting either
47
+ form always puts the ACP value on the wire; a durable Junie session record
48
+ stores the ACP value too, and a record written before short ids existed still
49
+ resumes. With a readable catalog, a selection resolves by exact id, then exact
50
+ ACP value, then the single ACP value whose last segment matches; an ambiguous
51
+ or unknown selection fails the turn before anything is sent to Junie, except
52
+ an unknown bare `mix.*` preset, which is passed through. Without a readable
53
+ catalog the selection is passed through and Junie validates it. Observed
54
+ context capacity is keyed by ACP value only.
55
+
56
+ - Pi tools are exposed through an authenticated loopback MCP server. Calls are
57
+ returned to Pi for execution rather than executed by a second Pi tool loop.
58
+ - With a UI, Junie's native tools remain available and permission requests use
59
+ Pi dialogs with Junie's options; dismissal and timeout reject. In headless
60
+ sessions, a Junie `PreToolUse` hook blocks native shell and file mutation
61
+ tools and directs Junie to `pi/bash`, `pi/edit`, and `pi/write` instead;
62
+ native read-only tools remain available. Other native permission requests
63
+ still reject without a UI. Native tool activity is coalesced into display-only
64
+ session entries, never assistant text or LLM history; headless runs omit it.
65
+ On Windows, if the agent-directory path contains cmd metacharacters, batch
66
+ launchers fail closed rather than launching without the hook. Set
67
+ `JUNIE_BRIDGE_LAUNCHER` to the real `junie.exe` to use that path safely.
68
+ - After each completed Junie prompt, a display-only line names the real Junie
69
+ model behind Pi's provider model and the cost attributed to that turn, for
70
+ example: `Junie · mix.normal → gpt-6.1-terra (low) · $0.0313`, where the first
71
+ name is the Pi model id (short id, or the full ACP value after a collision)
72
+ and the second is the concrete Junie model reported by local settings. The
73
+ model and
74
+ effort are read best-effort from local `~/.junie/sessions/<ACP sessionId>/`
75
+ `settings.json` after the terminal event, fire and forget: nothing waits for
76
+ that read, so a stalled local file can never delay the next turn, an abort or
77
+ shutdown, and no timer exists to hold the process. The line is emitted only
78
+ while it still belongs to a live session instance that no newer prompt has
79
+ superseded; a cancelled or refused turn, a disposed or closed session, and a
80
+ late read overtaken by the next turn all emit nothing, so display order never
81
+ inverts. The cost is exactly the USD amount
82
+ the bridge attributes to that turn's terminal Pi message from cumulative ACP
83
+ usage updates. Costs of at least `$0.0001` print four decimals; smaller
84
+ positive costs print as `<$0.0001` so a real charge never looks free. The
85
+ effort segment is omitted when Junie reports none, and the cost segment is
86
+ omitted when no cost was attributed to the turn. Missing or
87
+ invalid settings omit the line entirely. It never enters assistant text, LLM
88
+ context or prompts sent back to Junie, and headless runs omit it. These files
89
+ are undocumented: `JUNIE_HOME` overrides the bridge's local-file lookup root
90
+ (it does not configure Junie's own storage location).
91
+ - `brave_mode` is forced **off** on new, resumed and forked sessions. Junie session
92
+ mappings persist across Pi restarts. Each Pi session uses its own lifecycle cwd
93
+ (or a cwd supplied by that call/context). If an identified session has neither,
94
+ the bridge warns and uses process cwd only for that session's in-memory state;
95
+ it never borrows another session's cwd or permission UI.
96
+ - Default lean pi-subagents children retain Junie's lifecycle for workspace and
97
+ teardown cleanup. Explicit `lifecycle_passthrough` lists replace defaults, so
98
+ include `@thoth-agents/pi-junie-bridge` when configuring one.
99
+ - On Windows, the bundled pi-core launcher contains Junie in a kill-on-close Job
100
+ Object. If the launcher is unavailable, a warning identifies the leader-only
101
+ fallback, which cannot guarantee descendant cleanup.
102
+
103
+ ## Commands
104
+
105
+ | Command | Purpose |
106
+ | --- | --- |
107
+ | `/junie models` | Refresh the cached model catalog without an inference prompt. |
108
+ | `/junie quota` | Fetch the remaining JetBrains AI balance on demand in an isolated, temporary session. |
109
+
110
+ Quota uses Junie's advertised `/stats` command, never a free-form prompt or the
111
+ user's mapped session. Two consecutive probes of Junie CLI 26.11.1 returned an
112
+ unchanged balance with no usage, thought or tool activity: this is **inferred
113
+ non-consuming behavior**, not a billing guarantee. Unexpected activity, missing
114
+ data or timeout reports quota unavailable and points to JetBrains Account →
115
+ JetBrains AI settings. There is no periodic quota polling.
116
+
117
+ ## Limitations
118
+
119
+ - Junie's built-in tools **cannot be disabled**. Even with `brave_mode` off,
120
+ Junie may run commands it classifies as safe without asking (observed with
121
+ `echo` on Junie 26.11.1). The bridge can only gate permission requests Junie
122
+ sends; headless requests reject. This bridge is not an OS sandbox.
123
+ - Authentication, model availability, ACP details and `/stats` behavior depend on
124
+ the installed Junie version. Live behavior can change upstream.
125
+ - Pi model price rates are zero; message costs use Junie's cumulative USD usage
126
+ reports, not measured subscription fees. Trailing usage received after a
127
+ message ends is attributed to the next message in that session, without
128
+ changing the completed message or delaying its terminal event. The attributed
129
+ baseline persists across resume; an unreported final tail needs a later
130
+ cumulative report to be recovered after restart. The Thoth theme classifies
131
+ `junie` as a subscription provider by default.
132
+ - No captured-token proxy, API-key/BYOK management or npm bootstrap is included.
133
+
134
+ ## Development
135
+
136
+ ```bash
137
+ pnpm --filter @thoth-agents/pi-junie-bridge run typecheck
138
+ pnpm --filter @thoth-agents/pi-junie-bridge run test
139
+ pnpm --filter @thoth-agents/pi-junie-bridge run build
140
+ ```
141
+
142
+ Tests use a fake ACP agent and loopback MCP; they do not require Junie login or
143
+ spend subscription credits. They do not establish live compatibility with every
144
+ Junie version.