steno-paseo 0.0.0-stage → 0.1.3

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 (46) hide show
  1. package/LICENSE +21 -0
  2. package/OVERVIEW.md +25 -0
  3. package/README.md +146 -2
  4. package/client/agents.tsx +76 -0
  5. package/client/changes.ts +55 -0
  6. package/client/commands.ts +116 -0
  7. package/client/confirm.tsx +53 -0
  8. package/client/document.tsx +75 -0
  9. package/client/drafts.tsx +24 -0
  10. package/client/handoff.ts +114 -0
  11. package/client/model.ts +105 -0
  12. package/client/new-spec.tsx +74 -0
  13. package/client/notice.tsx +49 -0
  14. package/client/panel.tsx +144 -0
  15. package/client/row.tsx +114 -0
  16. package/client/set-up.tsx +62 -0
  17. package/client/sheet.tsx +93 -0
  18. package/client/vendor/host.d.mts +1 -0
  19. package/client/vendor/host.mjs +111 -0
  20. package/client/vendor/logo.ts +2 -0
  21. package/client/web.ts +9 -0
  22. package/index.client.tsx +13 -0
  23. package/index.server.ts +68 -0
  24. package/media/icon.png +0 -0
  25. package/package.json +50 -3
  26. package/paseo-plugin.json +16 -0
  27. package/screenshots/1-panel-dark.png +0 -0
  28. package/screenshots/2-hand-off-light.png +0 -0
  29. package/screenshots/3-document-dark.png +0 -0
  30. package/screenshots/4-command-center-dark.png +0 -0
  31. package/screenshots/5-panel-light.png +0 -0
  32. package/server/agent-steno.ts +16 -0
  33. package/server/agreement.ts +14 -0
  34. package/server/calls.ts +15 -0
  35. package/server/changes.ts +29 -0
  36. package/server/cli.ts +41 -0
  37. package/server/instructions.ts +21 -0
  38. package/server/intent.ts +38 -0
  39. package/server/pool.ts +10 -0
  40. package/server/programs.ts +27 -0
  41. package/server/read.ts +19 -0
  42. package/server/snapshot.ts +113 -0
  43. package/server/vendor/host.d.mts +5 -0
  44. package/server/vendor/host.mjs +4964 -0
  45. package/server/vendor/programs.ts +5 -0
  46. package/shared/contracts.ts +130 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 rizanw
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/OVERVIEW.md ADDED
@@ -0,0 +1,25 @@
1
+ steno adds a panel for spec-driven development to each workspace. You and your agents work through a feature in four stages, requirements, design, tasks and then code, each one a plain Markdown file in the repository. Each stage is checked by steno's lint and approved by you before the next one starts. The steno tab in Explorer shows where every spec stands and gives you the approvals. The agents in Paseo do the writing.
2
+
3
+ ## How it works
4
+
5
+ Specs live in `.steno/specs/` in the workspace, one folder per feature with `requirements.md`, `design.md` and `tasks.md`. The panel lists each spec with its documents and tasks, marks the next task, and shows the lint problems of each document above its text. Documents open read-only: an agent edits them, and you approve.
6
+
7
+ Run Task, Run Next Task, Write, Review and Revise hand the work to an agent. The plugin puts a short skill call, such as `/steno-run T2.1 link-expiry` or `Use the steno-run skill with: T2.1 link-expiry` depending on the agent, in the composer of the agent you have open, else an open New Agent screen, else the most recent agent. It never sends it: you read it and press send. With no agent, the call is copied to the clipboard. Approve, Mark Done and Reopen change the spec directly and need no agent. Every action is also in the Command Center under "steno".
8
+
9
+ ## Setup
10
+
11
+ Paseo 0.16 or later on macOS, Linux or Windows, with plugins turned on. For a folder without steno, Set Up steno in the panel adds the `.steno/` folder and the steno skills for the coding agents you choose.
12
+
13
+ The panel needs nothing else. Your agents, though, run the `steno` command from the daemon's `PATH` when they follow the skills, so install the `steno-spec` npm package globally on the computer running the daemon. If that command is missing or older than the plugin's copy, the panel shows a warning bar with the exact command to run.
14
+
15
+ ## What it reads, writes and runs
16
+
17
+ - It reads the workspace's specs, steering files and agent instruction files such as `AGENTS.md`.
18
+ - Approve, Mark Done and Reopen write `spec.yaml` and `tasks.md` in the spec's folder. New Spec creates a spec folder. Set Up steno writes `.steno/`, the skills folders of the agents you pick, a short steno section in `AGENTS.md` and, for Claude Code, its read-only reviewer agents in `.claude/agents/`.
19
+ - The plugin carries its own steno command and language server. It writes them to `~/.paseo/plugin-data/steno/`, one folder per version, and runs them from there. Removing the plugin leaves that folder in place.
20
+ - It runs `steno --version` from the daemon's `PATH` once per panel to check the copy your agents use.
21
+ - It makes no network requests and calls no model. The only text it puts in front of an agent is the skill call, never file contents. What the agent then reads and sends to its provider is up to the agent.
22
+
23
+ ## Limits
24
+
25
+ The panel is a view and a set of gates, not an editor: write and revise documents through an agent. Each workspace's panel shows the specs of that workspace's folder only. If the language server crashes five times in a row, the panel stops it and offers Restart steno Server.
package/README.md CHANGED
@@ -1,3 +1,147 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/rizanw/steno-spec/main/assets/steno.png" alt="steno logo" width="140">
3
+ </p>
2
4
 
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.
5
+ <h1 align="center">steno spec for Paseo</h1>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/steno-paseo"><img src="https://img.shields.io/npm/v/steno-paseo" alt="npm version"></a>
9
+ <a href="https://paseo.sh/plugins/rizanw/steno"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fplugins.paseo.sh%2Fplugins%2Frizanw%2Fsteno.json&query=%24.artifact.version&label=Paseo&prefix=v" alt="Paseo plugin version"></a>
10
+ <a href="https://github.com/rizanw/steno-spec/actions/workflows/ci.yml"><img src="https://github.com/rizanw/steno-spec/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
11
+ <a href="https://github.com/rizanw/steno-spec/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/steno-spec" alt="MIT license"></a>
12
+ </p>
13
+
14
+ <p align="center">
15
+ <strong>Shorthand specs for any coding agent.</strong><br>
16
+ Plan a feature before you build it: requirements, then design, then tasks, then code. Your agent
17
+ writes each stage in Paseo, and the steno panel shows where every spec stands, lists each lint
18
+ problem and gives you the approvals. It has no model in it and spends no tokens.
19
+ </p>
20
+
21
+ <p align="center">
22
+ <a href="#quick-start">Quick start</a> ·
23
+ <a href="#use-it">Use it</a> ·
24
+ <a href="#troubleshooting">Troubleshooting</a> ·
25
+ <a href="https://github.com/rizanw/steno-spec/blob/main/docs/getting-started.md">Getting started</a> ·
26
+ <a href="https://github.com/rizanw/steno-spec/blob/main/docs/concepts.md">Concepts</a> ·
27
+ <a href="https://github.com/rizanw/steno-spec/blob/main/docs/cli.md">CLI reference</a>
28
+ </p>
29
+
30
+ <p align="center">
31
+ <img src="https://raw.githubusercontent.com/rizanw/steno-spec/main/packages/paseo/screenshots/2-hand-off-light.png" alt="The steno panel beside an agent in Paseo, with a task handed to the agent">
32
+ </p>
33
+
34
+ ---
35
+
36
+ - **Specs are plain Markdown.** `requirements.md`, `design.md` and `tasks.md`, with EARS criteria and
37
+ stable IDs, so whichever agent you run in Paseo can do the writing while you watch.
38
+ - **Every stage has a gate.** Lint errors send a document back for another pass, and only your
39
+ approval moves a spec on.
40
+ - **A task gets a packet, not the whole spec.** Your agent reads `steno ctx T2.1`, usually a few
41
+ hundred tokens. The panel, the lint problems and the approvals cost nothing.
42
+ - **It brings everything it needs.** The plugin carries its own steno language server and skills and
43
+ runs them on Paseo's Node. There is no second runtime to install and no network call.
44
+
45
+ ## Quick start
46
+
47
+ You need **Paseo 0.16 or later** with plugins turned on (Settings → Plugins → Enable plugins), and
48
+ npm on the Paseo daemon's `PATH`.
49
+
50
+ ```bash
51
+ paseo plugin install npm:steno-paseo
52
+ paseo plugin ls # steno shows "running"
53
+ ```
54
+
55
+ The panel works on its own. Your agents are another matter: they call `steno` from their skills, and
56
+ they use the daemon's `PATH`, so install the CLI where the daemon can find it:
57
+
58
+ ```bash
59
+ npm install -g steno-spec
60
+ ```
61
+
62
+ If the `steno` on that `PATH` is missing, older than the plugin's copy or speaks a different protocol,
63
+ the panel shows a warning bar with the exact command to install the right version.
64
+
65
+ Then open a workspace and pick the **steno** tab in the Explorer. If the folder has no `.steno/` yet,
66
+ choose **Set Up steno** and pick the coding agents that should get the steno skills.
67
+
68
+ ## The workflow
69
+
70
+ ```text
71
+ brief? → requirements → design → tasks → execute → done
72
+ approve ↺ lint ↺ lint ↺ lint ↺ next task drift review?
73
+ ↺ review? ↺ review? ↺ review?
74
+ approve → approve → approve →
75
+
76
+ ↺ sends you back to revise the same stage; only approve moves to the next one.
77
+ ```
78
+
79
+ Every stage has a skill that writes it and a gate that ends it. A review is there whenever you want
80
+ one: read-only reviewers look at the document and never see your conversation. Only you can approve.
81
+ No skill and no agent can do it for you.
82
+
83
+ ## Use it
84
+
85
+ | You want to | Do this |
86
+ |---|---|
87
+ | See your specs | Expand a spec to see its documents and tasks. The next task is marked. |
88
+ | Read a document | Tap it. Its lint problems are listed above the text. Documents open read-only, because your agent is the one who edits them. |
89
+ | Move a spec on | Tap **Approve** on the document of the current phase. If lint finds an error, the approval is refused and the problems are listed. |
90
+ | Tick off a task | Tap **Mark Done** on the task. **Reopen** asks you before it changes anything. |
91
+ | Add work to a finished spec | Choose **Reopen Spec** from the spec's "more" menu, then add tasks to `tasks.md`. A finished spec that already has new, unticked tasks is back in execution without it. |
92
+ | Hand work to an agent | Tap **Run Task**, **Run Next Task**, **Write**, **Review** or **Revise** (Write becomes Revise once the document is written). The skill call lands unsent in the agent you have open, or else in an open New Agent screen, or else in your most recent agent. With no agent at all, it is copied to the clipboard. |
93
+ | Start something new | Tap **New Spec** on the Specs header, or **Generate Steering** on the Steering header. |
94
+ | Set up a folder | Tap **Set Up steno** on a folder without `.steno/`, and choose which coding agents get the skills. |
95
+
96
+ Every action is in the Command Center too. Press ⌘K (Ctrl+K on Windows and Linux) and type `steno`. An
97
+ item such as **Approve…** opens the panel with a list of everything it applies to.
98
+
99
+ When a row has more actions than fit as buttons, the rest are behind its **more** button (•••).
100
+
101
+ ## Update and uninstall
102
+
103
+ | To | Run |
104
+ |---|---|
105
+ | Update | `paseo plugin update steno` |
106
+ | Turn it off for a while | `paseo plugin disable steno` (and `enable` to bring it back) |
107
+ | Uninstall | `paseo plugin remove steno` |
108
+
109
+ The plugin unpacks its programs into `~/.paseo/plugin-data/steno/`, one folder per version. Removing
110
+ the plugin leaves that folder behind, so delete it by hand if you want the space back.
111
+
112
+ ## Troubleshooting
113
+
114
+ Start with the plugin's log:
115
+
116
+ ```bash
117
+ paseo plugin logs steno
118
+ ```
119
+
120
+ A healthy start has one line for the unpacked programs and one for each program that started:
121
+
122
+ ```text
123
+ steno: programs in ~/.paseo/plugin-data/steno/<hash>/vendor
124
+ steno: cli started: <version>
125
+ steno: language server started: <name> <version>
126
+ ```
127
+
128
+ | You see | What to do |
129
+ |---|---|
130
+ | steno is missing from `paseo plugin ls` | Turn plugins on in Settings → Plugins, then install it again. |
131
+ | `cli failed` or `language server failed` in the log | Run `paseo plugin update steno`, then `paseo plugin reload steno`. If it keeps happening, [open an issue](https://github.com/rizanw/steno-spec/issues) and attach the log. |
132
+ | `could not unpack the bundled programs` | Make sure `~/.paseo/plugin-data/` is writable. |
133
+ | A warning bar naming `npm install -g steno-spec@<version>` | Your agents' `steno` is missing, older than the plugin's or speaks a different protocol. Run that command on the machine where the daemon runs. |
134
+ | The panel says the steno server stopped | It crashed five times in a row. Choose **Restart steno Server**, and check the log if it stops again. |
135
+ | The install fails on `npm:` | npm must be on the daemon's `PATH` and able to reach the npm registry. |
136
+
137
+ ## Docs
138
+
139
+ - [Getting started](https://github.com/rizanw/steno-spec/blob/main/docs/getting-started.md): a first spec from start to finish, quick mode, bugfixes
140
+ - [Concepts](https://github.com/rizanw/steno-spec/blob/main/docs/concepts.md): phases and gates, IDs, EARS, lint rules, context packets, steering
141
+ - [CLI reference](https://github.com/rizanw/steno-spec/blob/main/docs/cli.md): every command and flag
142
+ - [Agents & integrations](https://github.com/rizanw/steno-spec/blob/main/docs/agents.md): supported agents and reviewers
143
+ - [Contributing](https://github.com/rizanw/steno-spec/blob/main/CONTRIBUTING.md#the-paseo-plugin): build the plugin from source and test it
144
+
145
+ ## License
146
+
147
+ [MIT](https://github.com/rizanw/steno-spec/blob/main/LICENSE)
@@ -0,0 +1,76 @@
1
+ // The live side of a hand-off: the workspace's agents, each one's composer, and the focused composer, kept in refs
2
+ // so a hand-off in progress sees them change while it waits for an opened agent.
3
+ //
4
+ // A composer does not say which agent it belongs to. Paseo hands out one composer object per agent state, the same
5
+ // object for `{ focused: true }` and for `{ agentId }`, so the focused agent is the one whose own composer is the
6
+ // focused composer. That is how a focused agent of another workspace is told apart: it has no probe here.
7
+ import type { AgentRef, PluginComposer, PluginWorkspacePanelProps } from '@getpaseo/plugin/client';
8
+ import { useAgent, useAgents, useComposers, useRpc } from '@getpaseo/plugin/client';
9
+ import { copyText, useToast } from '@getpaseo/plugin/client/ui';
10
+ import { useCallback, useEffect, useMemo, useRef, type ReactNode } from 'react';
11
+ import { Platform } from 'react-native';
12
+ import { call, type Handoff } from '../shared/contracts';
13
+ import { openDrafts } from './drafts';
14
+ import { isMacWeb } from './web';
15
+ import { chooseTarget, performHandoff, type AgentInfo, type HandoffResult } from './handoff';
16
+
17
+ /** The paste shortcut of this client; a phone or tablet has no keyboard shortcut to name. */
18
+ function pasteHint(): string {
19
+ if (Platform.OS !== 'web') return 'paste it';
20
+ return isMacWeb() ? 'press ⌘V' : 'press Ctrl+V';
21
+ }
22
+
23
+ interface Probed { info: AgentInfo; composer: PluginComposer | undefined }
24
+
25
+ /** Renders nothing; reports one agent's snapshot and composer on every change. */
26
+ function AgentProbe({ agent, into }: { agent: AgentRef; into: Map<string, Probed> }) {
27
+ const snapshot = useAgent(agent);
28
+ const [composer] = useComposers({ agentId: agent.id });
29
+ if (snapshot) into.set(agent.id, { info: { id: snapshot.id, provider: snapshot.provider, lastActivityAt: snapshot.lastActivityAt }, composer });
30
+ useEffect(() => () => { into.delete(agent.id); }, [into, agent.id]);
31
+ return null;
32
+ }
33
+
34
+ export interface HandoffApi {
35
+ handOff(handoff: Handoff): Promise<HandoffResult>;
36
+ /** Mount these once in the panel; they keep the agents and composers current. */
37
+ probes: ReactNode;
38
+ }
39
+
40
+ export function useHandoff(workspaceId: string, navigation: PluginWorkspacePanelProps['navigation']): HandoffApi {
41
+ const toast = useToast();
42
+ const sendCall = useRpc(call);
43
+ const query = useMemo(() => ({ where: (a: { workspaceId: string; background: boolean; status: string }) => a.workspaceId === workspaceId && !a.background && a.status !== 'closed' }), [workspaceId]);
44
+ const agents = useAgents(query);
45
+ const [focused] = useComposers({ focused: true });
46
+ const probed = useRef(new Map<string, Probed>()).current;
47
+ const focusedRef = useRef(focused);
48
+ focusedRef.current = focused;
49
+ const navRef = useRef(navigation);
50
+ navRef.current = navigation;
51
+
52
+ const focusedAgentId = useCallback((): string | null => {
53
+ const now = focusedRef.current;
54
+ if (!now) return null;
55
+ for (const [id, p] of probed) if (p.composer === now) return id;
56
+ return null;
57
+ }, [probed]);
58
+
59
+ const handOff = useCallback(async (handoff: Handoff) => {
60
+ const nav = navRef.current;
61
+ const target = chooseTarget(focusedAgentId(), [...probed.values()].map(p => p.info), nav !== undefined, openDrafts().map(d => d.agent.provider));
62
+ return performHandoff(target, {
63
+ call: provider => sendCall({ workspaceId, handoff, ...(provider ? { provider } : {}) }),
64
+ focusedComposer: agentId => (focusedAgentId() === agentId ? focusedRef.current : undefined),
65
+ openAgent: agentId => navRef.current?.openAgent({ agentId }),
66
+ draftComposer: () => { const drafts = openDrafts(); return drafts.length === 1 ? drafts[0] : undefined; },
67
+ sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
68
+ copy: copyText,
69
+ paste: pasteHint(),
70
+ notify: (message, variant) => (variant === 'error' ? toast.error(message) : toast.show(message, { variant })),
71
+ });
72
+ }, [focusedAgentId, probed, sendCall, workspaceId, toast]);
73
+
74
+ const probes = agents.map(agent => <AgentProbe key={agent.id} agent={agent} into={probed} />);
75
+ return { handOff, probes };
76
+ }
@@ -0,0 +1,55 @@
1
+ // Approve, done, reopen and reopening a spec as the panel runs them: which request a row's action makes, the
2
+ // confirmation either reopen needs before anything is sent, and the words for each outcome. No React here, so the rules are tested directly.
3
+ import type { Action, ChangeOutcome, ChangeResult, Diagnostic, Row, StructuredError } from '../shared/contracts';
4
+ import { reopenedMessage, reopenWording as wordingFor } from './vendor/host.mjs';
5
+
6
+ export interface ChangeRequest { kind: 'approve' | 'done' | 'reopen' | 'reopenSpec'; spec: string; phase?: ChangeResult['phase']; task?: string }
7
+
8
+ export const CHANGE_ACTIONS: readonly Action[] = ['approve', 'done', 'reopen', 'reopenSpec'];
9
+
10
+ /** The change a row's action asks for, or none when the action is not a change or the row lacks its target. */
11
+ export function changeFor(row: Row, action: Action): ChangeRequest | undefined {
12
+ const target = row.target;
13
+ if (!target) return undefined;
14
+ if (action === 'approve') return target.phase ? { kind: 'approve', spec: target.spec, phase: target.phase } : undefined;
15
+ if (action === 'done' || action === 'reopen') return target.task ? { kind: action, spec: target.spec, task: target.task } : undefined;
16
+ if (action === 'reopenSpec') return { kind: 'reopenSpec', spec: target.spec };
17
+ return undefined;
18
+ }
19
+
20
+ /**
21
+ * Run one change. Either reopen waits for `confirm` and, when the user declines, sends nothing and returns `undefined`:
22
+ * taking back a finished task or spec is the change the user may not have meant.
23
+ */
24
+ export async function performChange(
25
+ request: ChangeRequest,
26
+ confirm: (request: ChangeRequest) => Promise<boolean>,
27
+ send: (request: ChangeRequest) => Promise<ChangeOutcome>,
28
+ ): Promise<ChangeOutcome | undefined> {
29
+ if ((request.kind === 'reopen' || request.kind === 'reopenSpec') && !(await confirm(request))) return undefined;
30
+ return send(request);
31
+ }
32
+
33
+ /** The question and its explanation, for a task or a whole spec, in the words every host uses. */
34
+ export function reopenWording(request: ChangeRequest): { title: string; body: string } {
35
+ return wordingFor(request.kind === 'reopenSpec' ? { spec: request.spec } : { spec: request.spec, task: request.task ?? '' });
36
+ }
37
+
38
+ const PHASE_NAMES: Record<ChangeResult['phase'], string> = {
39
+ brief: 'Brief', requirements: 'Requirements', design: 'Design', tasks: 'Tasks', execute: 'Execution', done: 'Done',
40
+ };
41
+
42
+ /** The toast after a change the server accepted. */
43
+ export function successMessage(request: ChangeRequest, result: ChangeResult): string {
44
+ if (request.kind === 'done') return `${request.task} of ${result.spec} is done.`;
45
+ if (request.kind === 'reopen') return reopenedMessage({ spec: result.spec, task: request.task ?? '' });
46
+ if (request.kind === 'reopenSpec') return reopenedMessage({ spec: result.spec });
47
+ const approved = request.phase ? `${PHASE_NAMES[request.phase]} approved.` : 'Approved.';
48
+ return result.phase === 'done' ? `${approved} ${result.spec} is finished.` : `${approved} ${result.spec} moves on to ${PHASE_NAMES[result.phase].toLowerCase()}.`;
49
+ }
50
+
51
+ /** One lint problem as the refusal lists it: where, how bad, what. */
52
+ export const problemLine = (d: Diagnostic): string => `${d.file}:${d.line} ${d.severity} ${d.message}`;
53
+
54
+ /** The lines a refusal shows under its message; only a lint block has any. */
55
+ export const refusalProblems = (error: StructuredError): string[] => (error.findings ?? []).map(problemLine);
@@ -0,0 +1,116 @@
1
+ // The panel's actions in Paseo's Command Center (⌘K). An item cannot draw anything itself, so every item that needs
2
+ // the panel leaves an intent with the server and opens the panel; the panel's next snapshot carries the intent, and
3
+ // the panel acts on it. Approve… reaches the server only as an intent: the user still picks the row and presses the
4
+ // button, so no agent can approve through this path.
5
+ import type { PluginClientContext, PluginWorkspaceCommandContext } from '@getpaseo/plugin/client';
6
+ import { intent, restart, type Action, type Row } from '../shared/contracts';
7
+ import { actionLabel } from './model';
8
+
9
+ export const PANEL_ID = 'steno';
10
+
11
+ /** The intents that end in a picker of rows, as the Command Center titles them. */
12
+ export const PICKED_ITEMS: readonly { action: Action; title: string; icon: string }[] = [
13
+ { action: 'approve', title: 'Approve…', icon: 'Check' },
14
+ { action: 'done', title: 'Mark Task Done…', icon: 'CircleCheck' },
15
+ { action: 'reopen', title: 'Reopen Task…', icon: 'Undo2' },
16
+ { action: 'reopenSpec', title: 'Reopen Spec…', icon: 'RotateCcw' },
17
+ { action: 'run', title: 'Run Task…', icon: 'Play' },
18
+ { action: 'runNext', title: 'Run Next Task…', icon: 'FastForward' },
19
+ { action: 'write', title: 'Write This Phase…', icon: 'Pencil' },
20
+ { action: 'review', title: 'Review This Phase…', icon: 'Eye' },
21
+ { action: 'open', title: 'Open Document…', icon: 'FileText' },
22
+ ];
23
+
24
+ /** The rows that offer `action`, in panel order; the picker lists exactly these. */
25
+ export const rowsOffering = (rows: readonly Row[], action: Action): Row[] => rows.filter(row => row.actions.includes(action));
26
+
27
+ /** What the picker asks, worded for the person choosing rather than after the panel's rows. */
28
+ const PICKER_TITLES: Partial<Record<Action, string>> = {
29
+ approve: 'Approve a phase', done: 'Mark a task done', reopen: 'Reopen a task', reopenSpec: 'Reopen a finished spec', run: 'Run a task',
30
+ runNext: 'Run the next task', write: 'Write a phase', review: 'Review a phase', open: 'Open a document',
31
+ };
32
+
33
+ /** Said instead of an empty picker, naming what is missing. */
34
+ const NOTHING_TO_PICK: Partial<Record<Action, string>> = {
35
+ approve: 'Nothing to approve: no spec has a phase waiting for approval.',
36
+ done: 'Nothing to mark done: no spec in execution has an open task.',
37
+ reopen: 'Nothing to reopen: no task is done yet.',
38
+ reopenSpec: 'Nothing to reopen: no spec is finished.',
39
+ run: 'Nothing to run: no spec in execution has an open task.',
40
+ runNext: 'Nothing to run: no spec in execution has a task left.',
41
+ write: 'Nothing to write: no spec has a phase left to write.',
42
+ review: 'Nothing to review: no spec has a phase to review.',
43
+ open: 'Nothing to open: there are no specs or steering files yet.',
44
+ };
45
+
46
+ export const nothingToPick = (action: Action): string => NOTHING_TO_PICK[action] ?? `Nothing to ${actionLabel(action, undefined).toLowerCase()} right now.`;
47
+
48
+ /** One line of the picker. The action is in the picker's title, so a line says only which thing it applies to. */
49
+ export interface PickerEntry { row: Row; label: string; detail?: string }
50
+ /** Lines under one spec's name, or under Steering; a picker of whole specs has one section with no title. */
51
+ export interface PickerSection { key: string; title?: string; entries: PickerEntry[] }
52
+ export interface Picker { action: Action; title: string; sections: PickerSection[] }
53
+
54
+ /** Write and Review read best with the phase they work on, such as Write Tasks, since the spec's name alone hides it. */
55
+ const PHASE_NAMED: readonly Action[] = ['write', 'review'];
56
+
57
+ const problemsText = (row: Row): string | undefined => {
58
+ const { errors = 0, warnings = 0 } = row.problems ?? {};
59
+ const parts = [errors && `${errors} ${errors === 1 ? 'error' : 'errors'}`, warnings && `${warnings} ${warnings === 1 ? 'warning' : 'warnings'}`];
60
+ return parts.filter(Boolean).join(' · ') || undefined;
61
+ };
62
+
63
+ const joined = (...parts: (string | false | undefined)[]): string | undefined => parts.filter(Boolean).join(' · ') || undefined;
64
+
65
+ function entryFor(row: Row, action: Action): PickerEntry {
66
+ if (row.kind === 'spec') return { row, label: row.label, detail: joined(PHASE_NAMED.includes(action) && actionLabel(action, row), row.detail) };
67
+ if (row.kind === 'task') return { row, label: row.label, detail: joined(row.target?.task, row.detail) };
68
+ if (row.kind === 'document') return { row, label: row.label, detail: problemsText(row) };
69
+ return { row, label: row.label, detail: row.detail };
70
+ }
71
+
72
+ /**
73
+ * The picker for `action`, or none when no row offers it. Documents and tasks are grouped under their spec's
74
+ * title, in panel order, so the spec's name is said once instead of on every line; steering files go under Steering.
75
+ */
76
+ export function pickerFor(action: Action, rows: readonly Row[]): Picker | undefined {
77
+ const offering = rowsOffering(rows, action);
78
+ if (!offering.length) return undefined;
79
+ const title = PICKER_TITLES[action] ?? actionLabel(action, undefined);
80
+ const specTitles = new Map(rows.filter(r => r.kind === 'spec' && r.target).map(r => [r.target!.spec, r.label]));
81
+ const sections: PickerSection[] = [];
82
+ for (const row of offering) {
83
+ const group = row.kind === 'spec' ? '' : row.target ? `spec:${row.target.spec}` : row.kind;
84
+ let section = sections.at(-1);
85
+ if (!section || section.key !== group) {
86
+ const heading = row.kind === 'spec' ? undefined : row.target ? specTitles.get(row.target.spec) ?? row.target.spec : row.kind === 'steering' ? 'Steering' : undefined;
87
+ section = { key: group, title: heading, entries: [] };
88
+ sections.push(section);
89
+ }
90
+ section.entries.push(entryFor(row, action));
91
+ }
92
+ return { action, title, sections };
93
+ }
94
+
95
+ const openPanel = (ctx: PluginWorkspaceCommandContext) => ctx.openPanel(PANEL_ID, { location: 'explorer' });
96
+
97
+ /** Leave the intent first, so a panel that opens fresh finds it in its first snapshot. */
98
+ async function sendIntent(ctx: PluginWorkspaceCommandContext, action: Action): Promise<void> {
99
+ await ctx.rpc(intent, { workspaceId: ctx.workspace.ref.id, action });
100
+ openPanel(ctx);
101
+ }
102
+
103
+ export function registerCommands(client: PluginClientContext): () => void {
104
+ const item = (id: string, title: string, icon: string, onSelect: (ctx: PluginWorkspaceCommandContext) => void | Promise<void>) =>
105
+ // Paseo refuses an id with a dot and scopes ids to the plugin itself, so they stay plain kebab-case
106
+ client.addCommandCenterItem({ id, title, icon, keywords: ['steno', 'spec'], context: 'workspace', onSelect });
107
+ const removers = [
108
+ item('open', 'Open steno', 'PanelLeft', openPanel),
109
+ item('new-spec', 'New Spec', 'Plus', ctx => sendIntent(ctx, 'newSpec')),
110
+ item('set-up', 'Set Up steno', 'Wrench', ctx => sendIntent(ctx, 'setUp')),
111
+ item('steer', 'Generate Steering', 'Sparkles', ctx => sendIntent(ctx, 'steer')),
112
+ item('restart', 'Restart steno Server', 'RefreshCw', async ctx => { await ctx.rpc(restart, { workspaceId: ctx.workspace.ref.id }); }),
113
+ ...PICKED_ITEMS.map(({ action, title, icon }) => item(`pick-${action.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)}`, title, icon, ctx => sendIntent(ctx, action))),
114
+ ];
115
+ return () => { for (const remove of removers) remove(); };
116
+ }
@@ -0,0 +1,53 @@
1
+ // The two dialogs around a change: the confirmation either reopen needs, and a refusal with its reason, each lint
2
+ // problem that blocked it, and, when the server is stopped, the way to start it again.
3
+ import type { PluginTheme } from '@getpaseo/plugin';
4
+ import { Modal } from '@getpaseo/plugin/client/ui';
5
+ import { Platform, Text, View } from 'react-native';
6
+ import type { StructuredError } from '../shared/contracts';
7
+ import { refusalProblems, reopenWording, type ChangeRequest } from './changes';
8
+ import { Button } from './row';
9
+
10
+ // iOS has no font called monospace
11
+ const MONO = Platform.select({ ios: 'Menlo', default: 'monospace' });
12
+
13
+ export interface ReopenConfirmProps { request: ChangeRequest | undefined; theme: PluginTheme; onAnswer(reopen: boolean): void }
14
+
15
+ export function ReopenConfirm({ request, theme, onAnswer }: ReopenConfirmProps) {
16
+ const wording = request ? reopenWording(request) : { title: '', body: '' };
17
+ return (
18
+ <Modal title={wording.title} open={request !== undefined} onOpenChange={open => { if (!open) onAnswer(false); }}>
19
+ <Modal.Content>
20
+ <Text style={{ color: theme.colors.foreground }}>{wording.body}</Text>
21
+ <View style={{ flexDirection: 'row', justifyContent: 'flex-end', gap: 8 }}>
22
+ <Button label="Cancel" theme={theme} onPress={() => onAnswer(false)} />
23
+ <Button label="Reopen" theme={theme} primary onPress={() => onAnswer(true)} />
24
+ </View>
25
+ </Modal.Content>
26
+ </Modal>
27
+ );
28
+ }
29
+
30
+ export interface RefusalProps { error: StructuredError | undefined; stopped: boolean; theme: PluginTheme; onClose(): void; onRestart(): void }
31
+
32
+ /**
33
+ * A refusal as a dialog rather than a toast: a toast holds one line and no button, and a lint block needs every
34
+ * problem listed, a stopped server the Restart button.
35
+ */
36
+ export function Refusal({ error, stopped, theme, onClose, onRestart }: RefusalProps) {
37
+ const problems = error ? refusalProblems(error) : [];
38
+ return (
39
+ <Modal title="Nothing changed" open={error !== undefined} onOpenChange={open => { if (!open) onClose(); }}>
40
+ <Modal.Content>
41
+ <Text style={{ color: theme.colors.foreground }}>{error?.message ?? ''}</Text>
42
+ {problems.map(line => (
43
+ <Text key={line} selectable style={{ color: theme.colors.foregroundMuted, fontFamily: MONO, fontSize: 12 }}>{line}</Text>
44
+ ))}
45
+ {stopped ? (
46
+ <View style={{ flexDirection: 'row', justifyContent: 'flex-end' }}>
47
+ <Button label="Restart steno Server" theme={theme} primary onPress={() => { onClose(); onRestart(); }} />
48
+ </View>
49
+ ) : null}
50
+ </Modal.Content>
51
+ </Modal>
52
+ );
53
+ }
@@ -0,0 +1,75 @@
1
+ // One file the panel lists, read-only: the row's actions, the file's lint problems, then its text as formatted
2
+ // Markdown. Each snapshot that still lists the file reads it again, so an edit on disk shows without a tap.
3
+ import type { PluginTheme } from '@getpaseo/plugin';
4
+ import { useRpc } from '@getpaseo/plugin/client';
5
+ import { Icon, Markdown, ScrollView } from '@getpaseo/plugin/client/ui';
6
+ import { useEffect, useState } from 'react';
7
+ import { Pressable, Text, View } from 'react-native';
8
+ import { readFile, type Action, type Diagnostic, type Row } from '../shared/contracts';
9
+ import { ActionButton } from './row';
10
+
11
+ export interface DocumentViewProps {
12
+ workspaceId: string;
13
+ /** the row as the latest snapshot has it; undefined once no row lists the file */
14
+ row: Row | undefined;
15
+ path: string;
16
+ diagnostics: readonly Diagnostic[];
17
+ /** counts snapshots, so each one triggers a fresh read */
18
+ revision: number;
19
+ theme: PluginTheme;
20
+ compact: boolean;
21
+ onBack(): void;
22
+ onAction(row: Row, action: Action): void;
23
+ }
24
+
25
+ type Content = { text: string } | { error: string } | undefined;
26
+
27
+ export function DocumentView({ workspaceId, row, path, diagnostics, revision, theme, compact, onBack, onAction }: DocumentViewProps) {
28
+ const read = useRpc(readFile);
29
+ const [content, setContent] = useState<Content>();
30
+ const listed = row !== undefined;
31
+ useEffect(() => {
32
+ if (!listed) return;
33
+ let current = true;
34
+ read({ workspaceId, path }).then(
35
+ r => { if (current) setContent({ text: r.text }); },
36
+ () => { if (current) setContent({ error: 'not a steno file' }); },
37
+ );
38
+ return () => { current = false; };
39
+ }, [read, workspaceId, path, revision, listed]);
40
+
41
+ const { colors } = theme;
42
+ const pad = compact ? 12 : 16;
43
+ return (
44
+ <View style={{ flex: 1, backgroundColor: colors.surface0 }}>
45
+ <View style={{ flexDirection: 'row', alignItems: 'center', flexWrap: 'wrap', gap: 8, padding: 8, borderBottomWidth: 1, borderColor: colors.border }}>
46
+ <Pressable accessibilityRole="button" accessibilityLabel="Back to the list" onPress={onBack} style={{ padding: 4 }}>
47
+ <Icon name="ArrowLeft" size={16} color={colors.foreground} />
48
+ </Pressable>
49
+ <Text numberOfLines={1} style={{ flexShrink: 1, color: colors.foreground, fontWeight: '600' }}>{row?.label ?? path}</Text>
50
+ <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 2, marginLeft: 'auto' }}>
51
+ {(row?.actions ?? []).filter(a => a !== 'open').map(action => (
52
+ <ActionButton key={action} action={action} row={row!} theme={theme} onPress={() => onAction(row!, action)} />
53
+ ))}
54
+ </View>
55
+ </View>
56
+ <ScrollView contentContainerStyle={{ padding: pad, gap: 12 }}>
57
+ {!listed ? <Text style={{ color: colors.statusWarning }}>The panel no longer lists this file.</Text> : null}
58
+ {diagnostics.length ? (
59
+ <View style={{ gap: 4 }}>
60
+ {diagnostics.map((d, i) => (
61
+ <View key={i} style={{ flexDirection: 'row', gap: 8 }}>
62
+ <Text style={{ color: colors.foregroundMuted, fontSize: 12 }}>{`line ${d.line}`}</Text>
63
+ <Text style={{ color: d.severity === 'error' ? colors.statusDanger : colors.statusWarning, fontSize: 12 }}>{d.severity}</Text>
64
+ <Text style={{ flexShrink: 1, color: colors.foreground, fontSize: 12 }}>{d.message}</Text>
65
+ </View>
66
+ ))}
67
+ </View>
68
+ ) : null}
69
+ {content === undefined ? null
70
+ : 'error' in content ? <Text style={{ color: colors.statusDanger }}>{content.error}</Text>
71
+ : <Markdown>{content.text}</Markdown>}
72
+ </ScrollView>
73
+ </View>
74
+ );
75
+ }
@@ -0,0 +1,24 @@
1
+ // The New Agent screens that are open. Paseo resolves `composers(...)` for running agents only, so a draft's
2
+ // message box is reachable only from inside it: this composer item renders nothing and records the composer it
3
+ // sits in while that composer is a draft. A draft does not say which workspace it belongs to, so the hand-off uses
4
+ // one only when it is the only draft open.
5
+ import { useComposer, type PluginComposer } from '@getpaseo/plugin/client';
6
+ import { useEffect, useRef } from 'react';
7
+
8
+ /** Each mounted draft composer, read through a ref so a hand-off always gets its latest state. */
9
+ const open = new Set<{ current: PluginComposer }>();
10
+
11
+ export function openDrafts(): PluginComposer[] {
12
+ return [...open].map(entry => entry.current).filter(c => c.context === 'draft');
13
+ }
14
+
15
+ export function DraftProbe() {
16
+ const composer = useComposer();
17
+ const entry = useRef({ current: composer }).current;
18
+ entry.current = composer;
19
+ useEffect(() => {
20
+ open.add(entry);
21
+ return () => { open.delete(entry); };
22
+ }, [entry]);
23
+ return null;
24
+ }