Skip to content

Commit 399798d

Browse files
rcarmorcarmo
committed
Add workitems from issue #18 feature proposals
Triage aliceisjustplaying/piclaw-customizations contribution offer into four focused inbox items: - extension-broadcast-event-api: typed event API for live UI updates - generic-extension-widget-action-api: generic action/callback routing - dynamic-slash-command-autocomplete: server-sourced command completions - terminal-dock-sizing-and-resize-reliability: dock layout, resize, reattach Refs: #18
1 parent 1fab3e3 commit 399798d

4 files changed

Lines changed: 400 additions & 0 deletions

‎workitems/00-inbox/dynamic-slash-command-autocomplete.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
id: dynamic-slash-command-autocomplete
3+
title: Dynamic slash command autocomplete from registered commands and extensions
4+
status: inbox
5+
created: 2026-04-10
6+
updated: 2026-04-10
7+
tags:
8+
- work-item
9+
- kanban
10+
- web
11+
- ux
12+
- extensions
13+
- compose-box
14+
owner: pi
15+
origin: "https://github.com/rcarmo/piclaw/issues/18"
16+
---
17+
18+
# Dynamic slash command autocomplete from registered commands and extensions
19+
20+
## Summary
21+
22+
The compose-box slash command autocomplete list is currently hardcoded in
23+
`compose-box.ts`. Extension-registered commands work but do not appear in
24+
the autocomplete dropdown, creating a discoverability gap.
25+
26+
Issue #18 highlights this with a small patch that adds two more hardcoded
27+
entries. The real fix is to source the autocomplete list dynamically from
28+
the server's registered command set (core + extensions).
29+
30+
This pairs naturally with the `/extensions` per-chat management workitem
31+
in `10-next` — once extensions can be toggled per chat, the autocomplete
32+
should reflect the active command surface.
33+
34+
## Origin
35+
36+
- GitHub issue: https://github.com/rcarmo/piclaw/issues/18 (item 4)
37+
- External patch: `05-web-update-autocomplete.patch`
38+
- Repo: https://github.com/aliceisjustplaying/piclaw-customizations
39+
40+
## Acceptance Criteria
41+
42+
- [ ] The compose-box autocomplete list is sourced from a backend endpoint
43+
or SSE-delivered registry, not hardcoded.
44+
- [ ] Extension-registered commands appear in autocomplete.
45+
- [ ] Commands removed by per-chat extension toggles disappear from autocomplete.
46+
- [ ] The hardcoded `SLASH_COMMANDS` list becomes a fallback or is removed.
47+
- [ ] No regression in autocomplete speed or UX.
48+
49+
## Implementation Paths
50+
51+
### Path A — Backend /agent/commands endpoint (recommended)
52+
Add a `GET /agent/commands` endpoint that returns the current session's
53+
registered commands with name + description. The compose-box fetches on
54+
mount or listens for a command-registry SSE event.
55+
56+
### Path B — SSE push on session bind
57+
Include the command list in the session-ready SSE payload. Simpler but
58+
less responsive to mid-session extension changes.
59+
60+
## Test Plan
61+
62+
- Applicable regression classes from `workitems/regression-test-planning-reference.md`:
63+
- [ ] Interaction scenario test
64+
- [ ] Unit test: endpoint returns core + extension commands
65+
- [ ] Unit test: toggling an extension removes its commands from the list
66+
- [ ] Frontend test: autocomplete renders dynamic entries
67+
68+
## Definition of Done
69+
70+
- [ ] All acceptance criteria satisfied and verified
71+
- [ ] Tests added or updated — passing locally
72+
- [ ] Type check clean
73+
- [ ] Docs and notes updated with links to ticket
74+
- [ ] Operational impact assessed
75+
- [ ] Follow-up tickets created for deferred scope
76+
- [ ] Update history complete with evidence
77+
- [ ] Ticket front matter updated
78+
79+
## Updates
80+
81+
### 2026-04-10
82+
- Created from GitHub issue #18 triage. The hardcoded-entry patch is
83+
rejected but the underlying need is strong and self-contained.
84+
- Related: `add-per-chat-extensions-command-and-card` in 10-next.
85+
86+
## Notes
87+
88+
## Links
89+
90+
- https://github.com/rcarmo/piclaw/issues/18
91+
- `workitems/10-next/add-per-chat-extensions-command-and-card.md`
92+
- `runtime/web/src/components/compose-box.ts`
93+
- `runtime/src/agent-pool/slash-command.ts`
94+
- `runtime/src/agent-control/command-parsers.ts`

‎workitems/00-inbox/extension-broadcast-event-api.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
id: extension-broadcast-event-api
3+
title: Typed extension broadcast event API for live UI updates
4+
status: inbox
5+
created: 2026-04-10
6+
updated: 2026-04-10
7+
tags:
8+
- work-item
9+
- kanban
10+
- extensions
11+
- web
12+
- sse
13+
- api
14+
- architecture
15+
owner: pi
16+
origin: "https://github.com/rcarmo/piclaw/issues/18"
17+
---
18+
19+
# Typed extension broadcast event API for live UI updates
20+
21+
## Summary
22+
23+
Extensions need a sanctioned way to push live status/widget updates into
24+
the web client (status panels, toast notifications, widget state changes)
25+
without reaching into web channel internals.
26+
27+
Issue #18 proposes `globalThis.__PICLAW_BROADCAST_EVENT__` as a quick
28+
hook. The underlying need is real, but the implementation should be a
29+
typed, lifecycle-aware extension API rather than a global mutable function.
30+
31+
This aligns with the existing workitem
32+
`define-first-class-extension-ui-surface-for-piclaw-extensions` and
33+
should be designed alongside it.
34+
35+
## Origin
36+
37+
- GitHub issue: https://github.com/rcarmo/piclaw/issues/18 (item 1)
38+
- External patch: `02-bootstrap-broadcast-event.patch`
39+
- Repo: https://github.com/aliceisjustplaying/piclaw-customizations
40+
41+
## Acceptance Criteria
42+
43+
- [ ] Extensions can emit live UI events through a typed API method.
44+
- [ ] Events are scoped to chat/session, not globally broadcast.
45+
- [ ] The API is versioned and documented for extension authors.
46+
- [ ] No `globalThis` mutation required.
47+
- [ ] Existing `extension_ui_*` SSE plumbing is reused or superseded cleanly.
48+
49+
## Implementation Paths
50+
51+
### Path A — Extension context method
52+
Add a `broadcastUIEvent(type, payload)` method to the extension context
53+
passed during registration. Scoped by session/chat.
54+
55+
### Path B — Extension event bus
56+
Expose a typed event bus that extensions can publish to. The web channel
57+
subscribes and bridges to SSE. More flexible but heavier.
58+
59+
## Test Plan
60+
61+
- Applicable regression classes from `workitems/regression-test-planning-reference.md`:
62+
- [ ] Interaction scenario test
63+
- [ ] State-machine / invariant test
64+
- [ ] Unit test: extension emits event → web channel receives it
65+
- [ ] Unit test: event scoping by chat/session
66+
67+
## Definition of Done
68+
69+
- [ ] All acceptance criteria satisfied and verified
70+
- [ ] Tests added or updated — passing locally
71+
- [ ] Type check clean
72+
- [ ] Docs and notes updated with links to ticket
73+
- [ ] Operational impact assessed
74+
- [ ] Follow-up tickets created for deferred scope
75+
- [ ] Update history complete with evidence
76+
- [ ] Ticket front matter updated
77+
78+
## Updates
79+
80+
### 2026-04-10
81+
- Created from GitHub issue #18 triage. External patch reviewed; need is
82+
accepted but implementation shape should be a typed API, not globalThis.
83+
- Related: `define-first-class-extension-ui-surface-for-piclaw-extensions`
84+
85+
## Notes
86+
87+
## Links
88+
89+
- https://github.com/rcarmo/piclaw/issues/18
90+
- `workitems/00-inbox/define-first-class-extension-ui-surface-for-piclaw-extensions.md`
91+
- `runtime/src/runtime/bootstrap.ts`
92+
- `runtime/src/channels/web/theming/ui-bridge.ts`

‎workitems/00-inbox/generic-extension-widget-action-api.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
id: generic-extension-widget-action-api
3+
title: Generic extension widget action/callback API
4+
status: inbox
5+
created: 2026-04-10
6+
updated: 2026-04-10
7+
tags:
8+
- work-item
9+
- kanban
10+
- extensions
11+
- web
12+
- api
13+
- architecture
14+
owner: pi
15+
origin: "https://github.com/rcarmo/piclaw/issues/18"
16+
---
17+
18+
# Generic extension widget action/callback API
19+
20+
## Summary
21+
22+
Extension-owned UI widgets (status panels, live progress, task cards) need
23+
a return path so the user can trigger actions like stop, dismiss, retry,
24+
or copy. Currently the only upstream pattern is the autoresearch panel's
25+
hardcoded action types.
26+
27+
Issue #18 proposes codex-specific `/agent/codex/stop` and
28+
`/agent/codex/dismiss` endpoints plus matching frontend action handlers.
29+
The need is valid but the implementation should be generic — routed by
30+
extension ID and action key, not feature-specific endpoint names.
31+
32+
This is the server-side counterpart to the extension broadcast event API
33+
and the extension UI surface contract.
34+
35+
## Origin
36+
37+
- GitHub issue: https://github.com/rcarmo/piclaw/issues/18 (items 2–3)
38+
- External patches: `03-dispatch-codex-endpoints.patch`,
39+
`04-web-codex-action-handler.patch`
40+
- Repo: https://github.com/aliceisjustplaying/piclaw-customizations
41+
42+
## Acceptance Criteria
43+
44+
- [ ] A generic `POST /agent/extension-action` (or similar) endpoint exists.
45+
- [ ] Payload includes extension ID, widget key, action key, chat context.
46+
- [ ] The request is routed to the owning extension's registered action handler.
47+
- [ ] The frontend dispatches to the generic endpoint based on action type prefix.
48+
- [ ] Existing autoresearch panel actions migrate to (or coexist with) the new model.
49+
- [ ] No feature-specific route names in core dispatch tables.
50+
51+
## Implementation Paths
52+
53+
### Path A — Single generic action endpoint (recommended)
54+
Add one `POST /agent/extension-action` route. Dispatch by extension ID
55+
from the request body. Extensions register action handlers during init.
56+
57+
### Path B — Extension-namespaced routes
58+
Each extension gets `/agent/ext/<id>/<action>`. More REST-like but
59+
creates route proliferation.
60+
61+
## Test Plan
62+
63+
- Applicable regression classes from `workitems/regression-test-planning-reference.md`:
64+
- [ ] Routing matrix test
65+
- [ ] Interaction scenario test
66+
- [ ] Unit test: action dispatches to correct extension handler
67+
- [ ] Unit test: unknown extension/action returns structured error
68+
- [ ] Frontend test: widget button triggers correct fetch
69+
70+
## Definition of Done
71+
72+
- [ ] All acceptance criteria satisfied and verified
73+
- [ ] Tests added or updated — passing locally
74+
- [ ] Type check clean
75+
- [ ] Docs and notes updated with links to ticket
76+
- [ ] Operational impact assessed
77+
- [ ] Follow-up tickets created for deferred scope
78+
- [ ] Update history complete with evidence
79+
- [ ] Ticket front matter updated
80+
81+
## Updates
82+
83+
### 2026-04-10
84+
- Created from GitHub issue #18 triage. External patches reviewed;
85+
codex-specific route names rejected but the generic capability is wanted.
86+
- Related: extension broadcast event API, extension UI surface contract.
87+
88+
## Notes
89+
90+
## Links
91+
92+
- https://github.com/rcarmo/piclaw/issues/18
93+
- `workitems/00-inbox/extension-broadcast-event-api.md`
94+
- `workitems/00-inbox/define-first-class-extension-ui-surface-for-piclaw-extensions.md`
95+
- `runtime/src/channels/web/http/dispatch-agent.ts`
96+
- `runtime/web/src/ui/app-extension-status.ts`

0 commit comments

Comments
 (0)