@indexyz/pi-todo 0.0.0 → 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 +8 -0
- package/README.md +81 -2
- package/config.ts +141 -0
- package/docs/configuration.md +108 -0
- package/docs/overlay.md +128 -0
- package/docs/tool-schema.md +191 -0
- package/index.ts +302 -0
- package/locales/de.json +19 -0
- package/locales/en.json +17 -0
- package/locales/es.json +19 -0
- package/locales/fr.json +19 -0
- package/locales/pt-BR.json +19 -0
- package/locales/pt.json +19 -0
- package/locales/ru.json +19 -0
- package/locales/uk.json +19 -0
- package/locales/zh.json +19 -0
- package/package.json +78 -8
- package/state/i18n-bridge.ts +64 -0
- package/state/invariants.ts +20 -0
- package/state/replay.ts +142 -0
- package/state/selectors.ts +108 -0
- package/state/state-reducer.ts +324 -0
- package/state/state.ts +18 -0
- package/state/store.ts +125 -0
- package/state/task-graph.ts +61 -0
- package/todo-overlay.ts +255 -0
- package/todo.ts +168 -0
- package/tool/normalize-params.ts +44 -0
- package/tool/response-envelope.ts +114 -0
- package/tool/sanitize.ts +34 -0
- package/tool/types.ts +188 -0
- package/view/format.ts +202 -0
package/CHANGELOG.md
ADDED
package/README.md
CHANGED
|
@@ -1,3 +1,82 @@
|
|
|
1
|
-
# @indexyz/pi-todo
|
|
1
|
+
# @indexyz/pi-todo
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A repository-owned fork of [`@juicesharp/rpiv-todo` 2.15.0](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo), verified with Pi 1.5.0. It adds a `todo` tool, a
|
|
4
|
+
`/todos` command, and a live task panel above the editor. Task state survives
|
|
5
|
+
`/reload`, compaction, and detached sessions, while new session records store
|
|
6
|
+
compact action records instead of repeating the complete task list on every
|
|
7
|
+
call.
|
|
8
|
+
|
|
9
|
+
The runtime identities from the upstream extension are intentionally preserved:
|
|
10
|
+
`todo`, `/todos`, the `rpiv-todo-state` session entry, and the `rpiv-todos`
|
|
11
|
+
widget key. Existing sessions can therefore be replayed by the fork.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pi install npm:@indexyz/pi-todo
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Releases are published to npm as `@indexyz/pi-todo`; each release is tagged
|
|
20
|
+
`@indexyz/pi-todo@<version>`.
|
|
21
|
+
|
|
22
|
+
To try the repository checkout for one session (after `npm install` at the
|
|
23
|
+
repository root):
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pi -e ./pi-todo/index.ts
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
- Ask the agent to track multi-step work; it can call the `todo` tool with
|
|
32
|
+
`create`, `update`, `list`, `get`, `delete`, and `clear` actions.
|
|
33
|
+
- Run `/todos` in an interactive session to display all current tasks grouped by
|
|
34
|
+
status.
|
|
35
|
+
- Press `ctrl+shift+t` to collapse or expand the live panel. Configure this key
|
|
36
|
+
with `collapseKey` or set it to `off`.
|
|
37
|
+
|
|
38
|
+
The task model supports statuses, descriptions, active forms, owners,
|
|
39
|
+
`blockedBy` dependencies, metadata, batch creation, and session-scoped task
|
|
40
|
+
state. The overlay hides completed rows after the current turn and truncates
|
|
41
|
+
large lists according to its configured row budget.
|
|
42
|
+
|
|
43
|
+
### Configuration
|
|
44
|
+
|
|
45
|
+
The extension reads the existing `rpiv-todo` configuration location:
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
$XDG_CONFIG_HOME/rpiv-todo/config.json
|
|
49
|
+
~/.config/rpiv-todo/config.json
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Example:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"maxWidgetLines": 8,
|
|
57
|
+
"collapseKey": "alt+t"
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The optional `guidance` field replaces the built-in model instructions. The
|
|
62
|
+
optional peer `@juicesharp/rpiv-i18n` enables localized UI strings; without it,
|
|
63
|
+
English fallbacks are used.
|
|
64
|
+
|
|
65
|
+
### Session persistence
|
|
66
|
+
|
|
67
|
+
New tool results and `rpiv-todo-state` custom entries serialize the action and
|
|
68
|
+
parameters needed for replay, not the cumulative `tasks` and `nextId` snapshot.
|
|
69
|
+
This applies to both direct calls and nested `ctx.executeTool` calls. Legacy
|
|
70
|
+
sessions containing full snapshots remain readable and do not need migration.
|
|
71
|
+
|
|
72
|
+
## Development
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npm install
|
|
76
|
+
npm run check --workspace @indexyz/pi-todo
|
|
77
|
+
npm run test:e2e -- --package @indexyz/pi-todo
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## License
|
|
81
|
+
|
|
82
|
+
MIT
|
package/config.ts
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { isAbsolute, join } from "node:path";
|
|
4
|
+
|
|
5
|
+
interface TodoConfig {
|
|
6
|
+
guidance?: GuidanceFields;
|
|
7
|
+
maxWidgetLines?: number;
|
|
8
|
+
/**
|
|
9
|
+
* Key spec for the overlay collapse/expand shortcut, in the same format as
|
|
10
|
+
* pi-coding-agent keybinding ids (`modifier+key`, e.g. `ctrl+shift+t`, `alt+o`).
|
|
11
|
+
* Defaults to `"ctrl+shift+t"`. Pass `"off"` to disable the collapse shortcut.
|
|
12
|
+
*/
|
|
13
|
+
collapseKey?: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export interface GuidanceFields {
|
|
17
|
+
promptSnippet?: string;
|
|
18
|
+
promptGuidelines?: string[];
|
|
19
|
+
description?: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** Default content-row budget when the config is missing or invalid. */
|
|
23
|
+
export const DEFAULT_MAX_WIDGET_LINES = 12;
|
|
24
|
+
|
|
25
|
+
/** Key spec for the collapse/expand shortcut. */
|
|
26
|
+
export type CollapseKeySpec = string;
|
|
27
|
+
|
|
28
|
+
/** Default collapse/expand key when the config value is missing or invalid. */
|
|
29
|
+
export const DEFAULT_COLLAPSE_KEY: CollapseKeySpec = "ctrl+shift+t";
|
|
30
|
+
|
|
31
|
+
/** Sentinel value for `collapseKey` that disables the shortcut. */
|
|
32
|
+
export const COLLAPSE_KEY_OFF: CollapseKeySpec = "off";
|
|
33
|
+
|
|
34
|
+
function expandTilde(path: string): string {
|
|
35
|
+
if (path === "~") return homedir();
|
|
36
|
+
if (path.startsWith("~/")) return join(homedir(), path.slice(2));
|
|
37
|
+
return path;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function resolveConfigDir(): string {
|
|
41
|
+
const xdg = process.env.XDG_CONFIG_HOME?.trim();
|
|
42
|
+
if (!xdg) return join(homedir(), ".config");
|
|
43
|
+
const expanded = expandTilde(xdg);
|
|
44
|
+
return isAbsolute(expanded) ? expanded : join(homedir(), ".config");
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function configPath(name: string): string {
|
|
48
|
+
return join(resolveConfigDir(), name, "config.json");
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function legacyConfigPath(name: string): string {
|
|
52
|
+
return join(homedir(), ".config", name, "config.json");
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function loadJsonConfig<T>(path: string): T {
|
|
56
|
+
if (!existsSync(path)) return {} as T;
|
|
57
|
+
try {
|
|
58
|
+
const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
|
|
59
|
+
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {} as T;
|
|
60
|
+
return parsed as T;
|
|
61
|
+
} catch (error) {
|
|
62
|
+
console.warn(`[pi-todo] invalid JSON at ${path}; using defaults: ${String(error)}`);
|
|
63
|
+
return {} as T;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export function loadConfig(): TodoConfig {
|
|
68
|
+
const currentPath = configPath("rpiv-todo");
|
|
69
|
+
if (existsSync(currentPath)) return loadJsonConfig<TodoConfig>(currentPath);
|
|
70
|
+
return loadJsonConfig<TodoConfig>(legacyConfigPath("rpiv-todo"));
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export function getMaxWidgetLines(): number {
|
|
74
|
+
const lines = loadConfig().maxWidgetLines;
|
|
75
|
+
return typeof lines === "number" && lines >= 3 ? lines : DEFAULT_MAX_WIDGET_LINES;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const SPECIAL_KEYS = new Set([
|
|
79
|
+
"escape",
|
|
80
|
+
"esc",
|
|
81
|
+
"enter",
|
|
82
|
+
"return",
|
|
83
|
+
"tab",
|
|
84
|
+
"space",
|
|
85
|
+
"backspace",
|
|
86
|
+
"delete",
|
|
87
|
+
"insert",
|
|
88
|
+
"clear",
|
|
89
|
+
"home",
|
|
90
|
+
"end",
|
|
91
|
+
"pageup",
|
|
92
|
+
"pagedown",
|
|
93
|
+
"up",
|
|
94
|
+
"down",
|
|
95
|
+
"left",
|
|
96
|
+
"right",
|
|
97
|
+
...Array.from({ length: 12 }, (_, index) => `f${index + 1}`),
|
|
98
|
+
]);
|
|
99
|
+
|
|
100
|
+
const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
|
|
101
|
+
|
|
102
|
+
/** Validate a collapse-key spec against pi-tui's KeyId grammar. */
|
|
103
|
+
export function isValidCollapseKeySpec(spec: string): boolean {
|
|
104
|
+
if (!spec || spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
|
|
105
|
+
const parts = spec.split("+");
|
|
106
|
+
const base = parts.at(-1) ?? "";
|
|
107
|
+
const modifiers = parts.slice(0, -1);
|
|
108
|
+
if (modifiers.length !== new Set(modifiers).size) return false;
|
|
109
|
+
if (!modifiers.every((modifier) => MODIFIERS.has(modifier))) return false;
|
|
110
|
+
return base.length === 1
|
|
111
|
+
? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base)
|
|
112
|
+
: SPECIAL_KEYS.has(base);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** Resolve the configured collapse key, falling back to the default. */
|
|
116
|
+
export function resolveCollapseKey(): CollapseKeySpec {
|
|
117
|
+
const configured = loadConfig().collapseKey;
|
|
118
|
+
const raw = typeof configured === "string" ? configured.trim().toLowerCase() : undefined;
|
|
119
|
+
if (!raw) return DEFAULT_COLLAPSE_KEY;
|
|
120
|
+
if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
|
|
121
|
+
return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
export function validateGuidanceFields(fields: unknown): GuidanceFields {
|
|
125
|
+
if (!fields || typeof fields !== "object" || Array.isArray(fields)) return {};
|
|
126
|
+
const value = fields as Record<string, unknown>;
|
|
127
|
+
const result: GuidanceFields = {};
|
|
128
|
+
if (typeof value.promptSnippet === "string" && value.promptSnippet.length > 0) {
|
|
129
|
+
result.promptSnippet = value.promptSnippet;
|
|
130
|
+
}
|
|
131
|
+
if (
|
|
132
|
+
Array.isArray(value.promptGuidelines) &&
|
|
133
|
+
value.promptGuidelines.length > 0 &&
|
|
134
|
+
value.promptGuidelines.every((item) => typeof item === "string" && item.length > 0)
|
|
135
|
+
) {
|
|
136
|
+
result.promptGuidelines = value.promptGuidelines;
|
|
137
|
+
}
|
|
138
|
+
if (typeof value.description === "string" && value.description.length > 0)
|
|
139
|
+
result.description = value.description;
|
|
140
|
+
return result;
|
|
141
|
+
}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Configuration reference
|
|
2
|
+
|
|
3
|
+
Every option `@indexyz/pi-todo` reads, where the file lives, and exactly what happens when a value is wrong.
|
|
4
|
+
|
|
5
|
+
## Where the file lives
|
|
6
|
+
|
|
7
|
+
The config file is optional. It is resolved in this order:
|
|
8
|
+
|
|
9
|
+
1. `$XDG_CONFIG_HOME/rpiv-todo/config.json` — used when `XDG_CONFIG_HOME` is set
|
|
10
|
+
to an absolute path. A bare `~` or a leading `~/` is expanded first; a `~user`
|
|
11
|
+
form is not expanded and therefore falls through.
|
|
12
|
+
2. `~/.config/rpiv-todo/config.json` — used when `XDG_CONFIG_HOME` is unset,
|
|
13
|
+
empty, whitespace-only, or relative.
|
|
14
|
+
3. If the XDG file does not exist, the legacy `~/.config/rpiv-todo/config.json`
|
|
15
|
+
is read anyway, so a pre-XDG file is still found after you set
|
|
16
|
+
`XDG_CONFIG_HOME`. This fallback is one-way: if the XDG file exists but is
|
|
17
|
+
malformed, you get a warning and defaults — it does **not** quietly read the
|
|
18
|
+
legacy file instead.
|
|
19
|
+
|
|
20
|
+
Both files missing means every default applies. Malformed JSON prints a
|
|
21
|
+
`rpiv-config: invalid JSON at …` warning and is treated as `{}`. A JSON array or
|
|
22
|
+
a non-object value (`null`, a string, a number, a boolean) is silently treated as
|
|
23
|
+
`{}` — no warning.
|
|
24
|
+
|
|
25
|
+
`rpiv-todo` never writes this file — you create and edit it yourself, and the
|
|
26
|
+
extension only reads it.
|
|
27
|
+
|
|
28
|
+
## Example
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"maxWidgetLines": 8,
|
|
33
|
+
"collapseKey": "alt+t",
|
|
34
|
+
"guidance": {
|
|
35
|
+
"promptSnippet": "Use the `todo` tool to track multi-step work before starting it.",
|
|
36
|
+
"promptGuidelines": [
|
|
37
|
+
"Create one task per discrete step.",
|
|
38
|
+
"Mark a task in_progress while working on it; completed when done."
|
|
39
|
+
]
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## `maxWidgetLines`
|
|
45
|
+
|
|
46
|
+
**Default `12`.** The content-row budget for the overlay — the heading row and,
|
|
47
|
+
on overflow, the `+N more` summary row both count against it. Only the trailing
|
|
48
|
+
blank spacer sits outside the budget, so `12` renders up to 13 terminal rows.
|
|
49
|
+
|
|
50
|
+
- Floor of `3`. A number below `3` falls back to the default.
|
|
51
|
+
- A non-number falls back to the default.
|
|
52
|
+
- No ceiling.
|
|
53
|
+
- Read fresh on every render, so a change takes effect on the next repaint —
|
|
54
|
+
no `/reload`.
|
|
55
|
+
- Pi's tool-output expansion mode (`ctrl+o` by default) temporarily overrides
|
|
56
|
+
this budget and shows every task; collapsing restores the configured budget.
|
|
57
|
+
|
|
58
|
+
## `collapseKey`
|
|
59
|
+
|
|
60
|
+
**Default `"ctrl+shift+t"`.** The shortcut that collapses and expands the
|
|
61
|
+
overlay.
|
|
62
|
+
|
|
63
|
+
The value is trimmed and lowercased, then matched against Pi's keybinding
|
|
64
|
+
grammar: zero or more distinct modifiers joined by `+`, then a base key.
|
|
65
|
+
|
|
66
|
+
| Part | Accepted |
|
|
67
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
68
|
+
| Modifiers | `ctrl`, `shift`, `alt`, `super` — each at most once |
|
|
69
|
+
| Base key | one printable character (`a`, `7`, `]`, `/`, …) |
|
|
70
|
+
| Base key | a named key: `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`, `f1`–`f12` |
|
|
71
|
+
|
|
72
|
+
Examples: `alt+o`, `ctrl+shift+t`, `super+alt+f5`.
|
|
73
|
+
|
|
74
|
+
- A missing, empty, blank, non-string, or ungrammatical value falls back to the
|
|
75
|
+
default. The grammar is checked strictly on purpose: Pi takes the last `+`-part
|
|
76
|
+
as the base key and ignores unknown parts, so a typo like `ctr+]` would
|
|
77
|
+
otherwise capture every bare `]` keypress globally.
|
|
78
|
+
- `"off"` disables the feature — no shortcut is registered at all.
|
|
79
|
+
- The binding is resolved **once at extension load**. After editing this value,
|
|
80
|
+
run `/reload` to rebind; until you do, the old key stays active even though the
|
|
81
|
+
collapsed panel's hint text (which is resolved per render) already shows the
|
|
82
|
+
new one.
|
|
83
|
+
|
|
84
|
+
## Guidance
|
|
85
|
+
|
|
86
|
+
`guidance.promptSnippet` (string) and `guidance.promptGuidelines` (array of
|
|
87
|
+
strings) replace the prompt copy the `todo` tool advertises to the model. Both
|
|
88
|
+
are absent by default, in which case the built-in snippet and the nine built-in
|
|
89
|
+
guideline bullets are used.
|
|
90
|
+
|
|
91
|
+
- `promptSnippet` must be a non-empty string; an empty string or a wrong type
|
|
92
|
+
falls back to the default.
|
|
93
|
+
- `promptGuidelines` must be a non-empty array of non-empty strings. A non-array,
|
|
94
|
+
or an array containing an empty string, falls back to the default — the array
|
|
95
|
+
is all-or-nothing, not merged item by item.
|
|
96
|
+
- Both are read at extension load, so `/reload` after editing them.
|
|
97
|
+
|
|
98
|
+
## Environment variables
|
|
99
|
+
|
|
100
|
+
| Variable | Effect |
|
|
101
|
+
| ----------------- | ---------------------------------------------------------- |
|
|
102
|
+
| `XDG_CONFIG_HOME` | Relocates the config directory, as described above. |
|
|
103
|
+
| `HOME` | Anchors `~/.config` when `XDG_CONFIG_HOME` does not apply. |
|
|
104
|
+
|
|
105
|
+
`rpiv-todo` reads no environment variables of its own. If you have
|
|
106
|
+
[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
|
|
107
|
+
installed, that package has its own locale configuration and its own env-var
|
|
108
|
+
chain — see its README.
|
package/docs/overlay.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Overlay and `/todos` display
|
|
2
|
+
|
|
3
|
+
How `@indexyz/pi-todo` renders the task list — when the overlay appears, what
|
|
4
|
+
each glyph means, how overflow is trimmed, and which strings localize.
|
|
5
|
+
|
|
6
|
+
## When the overlay exists
|
|
7
|
+
|
|
8
|
+
The widget is mounted above the Pi editor under the key `rpiv-todos`.
|
|
9
|
+
|
|
10
|
+
| Stage | Condition |
|
|
11
|
+
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
12
|
+
| Created | At the first session start that has a UI. A headless session never creates it. |
|
|
13
|
+
| Registered | Only while at least one overlay-visible task exists. The widget unregisters itself when the list empties, and re-registers when a task reappears. |
|
|
14
|
+
| Bound | Only the foreground session's overlay is refreshed. A detached or child session has its own task state and never rebinds or repaints the foreground panel. |
|
|
15
|
+
| Disposed | On the foreground session's shutdown. A child session shutting down leaves the overlay alone. |
|
|
16
|
+
|
|
17
|
+
Task state is partitioned by session id, so parallel sessions cannot read or
|
|
18
|
+
overwrite each other's lists. Nothing is written to disk: on session start,
|
|
19
|
+
compaction, and session-tree changes, the list is rebuilt by walking the branch
|
|
20
|
+
and taking the last saved snapshot, which replaces the whole list
|
|
21
|
+
(last-write-wins). See [tool-schema.md](./tool-schema.md#persistence) for where
|
|
22
|
+
snapshots are saved.
|
|
23
|
+
|
|
24
|
+
## Anatomy of a row
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
● Todos (2/5)
|
|
28
|
+
├─ ✓ Create DemoTodo domain entity
|
|
29
|
+
├─ ✓ Create IDemoTodoRepository interface
|
|
30
|
+
├─ ◐ Create DemoTodoRepository (creating the repository)
|
|
31
|
+
├─ ○ Register DI bindings
|
|
32
|
+
└─ ○ Add integration tests
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
- **Heading** — `● Todos (done/total)` in the accent color while any task is
|
|
36
|
+
`pending` or `in_progress`; `○ Todos (done/total)` dimmed once everything is
|
|
37
|
+
completed.
|
|
38
|
+
- **Glyphs** — `○` pending, `◐` in_progress, `✓` completed, `✗` deleted.
|
|
39
|
+
Completed and deleted subjects render dim and struck through.
|
|
40
|
+
- **activeForm** — appended dim in parentheses, only while the task is
|
|
41
|
+
`in_progress`.
|
|
42
|
+
- **Dependencies** — appended as `⛓ #1,#2` when the task has a `blockedBy` set.
|
|
43
|
+
- **`#id` prefix** — shown on every row only when at least one visible task
|
|
44
|
+
carries a `blockedBy`. Without a `⛓ #N` anywhere, the per-row ids have nothing
|
|
45
|
+
to point at, so they are omitted.
|
|
46
|
+
- **Prefixes** — `├─` on each row, `└─` on the last one. A blank spacer line is
|
|
47
|
+
always appended below the panel so it is not flush against the input box.
|
|
48
|
+
|
|
49
|
+
Rows longer than the terminal width are truncated with `…`.
|
|
50
|
+
|
|
51
|
+
## Overflow
|
|
52
|
+
|
|
53
|
+
The content-row budget is `maxWidgetLines` (default `12`), and the heading counts
|
|
54
|
+
against it. When there are more tasks than fit:
|
|
55
|
+
|
|
56
|
+
1. one row is reserved for the summary line;
|
|
57
|
+
2. completed tasks are dropped first, newest first — the oldest completed rows
|
|
58
|
+
are the last completed rows to go;
|
|
59
|
+
3. if the unfinished tasks alone still overflow, the tail of that list is
|
|
60
|
+
truncated;
|
|
61
|
+
4. the last row becomes `+N more (X completed, Y pending)`.
|
|
62
|
+
|
|
63
|
+
Use Pi's tool-output expansion shortcut (`ctrl+o` by default) to expand the
|
|
64
|
+
widget and show every task. Collapsing Pi's tool output reapplies the configured
|
|
65
|
+
row budget. Unfinished work is therefore the last thing to disappear in the
|
|
66
|
+
compact view. See [configuration.md](./configuration.md#maxwidgetlines) for the
|
|
67
|
+
budget's floor and reload semantics.
|
|
68
|
+
|
|
69
|
+
## Completed tasks fading out
|
|
70
|
+
|
|
71
|
+
A completed task stays on screen for the remainder of the turn in which it was
|
|
72
|
+
completed. At the start of the next agent turn, every completed row that has
|
|
73
|
+
already been displayed is hidden from later renders. Reloading or compacting the
|
|
74
|
+
session resets that tracking, so a fresh session shows the full list again.
|
|
75
|
+
|
|
76
|
+
## Collapsing
|
|
77
|
+
|
|
78
|
+
Press `ctrl+shift+t` to collapse the panel to two lines — the heading plus a dim
|
|
79
|
+
`└─ ctrl+shift+t to expand` hint — and again to expand it. The hint always shows
|
|
80
|
+
the currently configured key.
|
|
81
|
+
|
|
82
|
+
Rebind or disable the shortcut with the `collapseKey` option; see
|
|
83
|
+
[configuration.md](./configuration.md#collapsekey). If the shortcut is set to
|
|
84
|
+
`"off"` while the panel is collapsed, the hint becomes a static `collapsed`
|
|
85
|
+
label rather than advertising an unbindable key.
|
|
86
|
+
|
|
87
|
+
## `/todos`
|
|
88
|
+
|
|
89
|
+
`/todos` prints the whole list grouped by status, independent of the overlay's
|
|
90
|
+
row budget and auto-hiding:
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
2/7 completed · 1 in progress · 4 pending
|
|
94
|
+
── Pending ──
|
|
95
|
+
○ #4 Register DI bindings
|
|
96
|
+
○ #5 Add integration tests ⛓ #4
|
|
97
|
+
○ #6 Wire up the HTTP endpoint
|
|
98
|
+
○ #7 Update the API docs
|
|
99
|
+
── In Progress ──
|
|
100
|
+
◐ #3 Create DemoTodoRepository (creating the repository)
|
|
101
|
+
── Completed ──
|
|
102
|
+
✓ #1 Create DemoTodo domain entity
|
|
103
|
+
✓ #2 Create IDemoTodoRepository interface
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The header omits any count that is zero. Sections appear only when they have
|
|
107
|
+
tasks. Tombstoned tasks are never listed.
|
|
108
|
+
|
|
109
|
+
- With no tasks: `No todos yet. Ask the agent to add some!`
|
|
110
|
+
- In a non-interactive session: `/todos requires interactive mode`
|
|
111
|
+
|
|
112
|
+
## Localization
|
|
113
|
+
|
|
114
|
+
The overlay heading, the `+N more` summary, the collapse hint, the `/todos`
|
|
115
|
+
section headers, and the status words all localize through
|
|
116
|
+
[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
|
|
117
|
+
when that package is installed. Bundled locales: `de`, `en`, `es`, `fr`, `pt`,
|
|
118
|
+
`pt-BR`, `ru`, `uk`, `zh`.
|
|
119
|
+
|
|
120
|
+
LLM-facing output — the tool response envelope, reducer error messages, and the
|
|
121
|
+
schema descriptions — stays English by design.
|
|
122
|
+
|
|
123
|
+
The SDK is a soft optional peer, loaded through a dynamic import at module init.
|
|
124
|
+
When it is absent, every call site returns its inline English literal and the
|
|
125
|
+
extension stays online: no warning, no crash. Install it at any time with
|
|
126
|
+
`pi install npm:@juicesharp/rpiv-i18n` and restart the session. To add or
|
|
127
|
+
override a translation, drop a `locales/<code>.json` file mirroring `en.json` —
|
|
128
|
+
see the `@juicesharp/rpiv-i18n` README's "Contributing translations" section.
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# `todo` tool reference
|
|
2
|
+
|
|
3
|
+
Complete parameter schema, status machine, response envelope, and error strings
|
|
4
|
+
for the `todo` tool registered by `@indexyz/pi-todo`.
|
|
5
|
+
|
|
6
|
+
## Actions
|
|
7
|
+
|
|
8
|
+
| Action | Required params | What it does |
|
|
9
|
+
| -------- | --------------------------------- | ----------------------------------------------------------------- |
|
|
10
|
+
| `create` | `subject` or `tasks[]` (one-of) | Adds one task, or several independent tasks, in `pending`. |
|
|
11
|
+
| `update` | `id` + at least one mutable field | Changes status, fields, or dependencies. |
|
|
12
|
+
| `list` | — | Returns all tasks, optionally filtered by `status`. |
|
|
13
|
+
| `get` | `id` | Returns one task with its `blockedBy` and reverse `blocks` edges. |
|
|
14
|
+
| `delete` | `id` | Tombstones the task (`status: "deleted"`); it is not removed. |
|
|
15
|
+
| `clear` | — | Drops every task and resets the id counter to `1`. |
|
|
16
|
+
|
|
17
|
+
## Parameters
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
todo({
|
|
21
|
+
action: "create" | "update" | "list" | "get" | "delete" | "clear",
|
|
22
|
+
|
|
23
|
+
// create-only (one-of: subject or tasks[])
|
|
24
|
+
subject?: string, // required for single create
|
|
25
|
+
blockedBy?: number[], // initial dependency ids (single create)
|
|
26
|
+
tasks?: Array<{ // batch create; independent items only
|
|
27
|
+
subject: string,
|
|
28
|
+
description?: string,
|
|
29
|
+
activeForm?: string,
|
|
30
|
+
blockedBy?: number[], // existing ids only; no sibling refs
|
|
31
|
+
owner?: string,
|
|
32
|
+
metadata?: Record<string, unknown>,
|
|
33
|
+
}>,
|
|
34
|
+
|
|
35
|
+
// create + update
|
|
36
|
+
description?: string, // long-form detail
|
|
37
|
+
activeForm?: string, // present-continuous label shown while in_progress
|
|
38
|
+
owner?: string, // agent/owner assigned to this task
|
|
39
|
+
metadata?: Record<string, unknown>, // on update, a null value deletes that key
|
|
40
|
+
|
|
41
|
+
// update-only
|
|
42
|
+
addBlockedBy?: number[], // additive merge into blockedBy
|
|
43
|
+
removeBlockedBy?: number[], // additive removal from blockedBy
|
|
44
|
+
|
|
45
|
+
// update / get / delete
|
|
46
|
+
id?: number,
|
|
47
|
+
|
|
48
|
+
// update (sets this task's status) or list (filters by status)
|
|
49
|
+
status?: "pending" | "in_progress" | "completed" | "deleted",
|
|
50
|
+
|
|
51
|
+
// list-only
|
|
52
|
+
includeDeleted?: boolean, // default false — hides tombstones
|
|
53
|
+
})
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`create` takes either `subject` (one task) or `tasks[]` (several independent
|
|
57
|
+
tasks). Passing both is rejected, even with a blank `subject`. Each item carries
|
|
58
|
+
its own `description`, `activeForm`, `blockedBy`, `owner` and `metadata`; the same
|
|
59
|
+
fields at the top level of a batch are rejected rather than dropped. The batch is validated first and committed
|
|
60
|
+
together: one bad item fails the whole call and leaves the list unchanged.
|
|
61
|
+
Items in `tasks[]` cannot `blockedBy` each other; those ids do not exist until
|
|
62
|
+
the call commits. Create the prerequisite first, then the dependent with
|
|
63
|
+
`blockedBy`. `blockedBy` on a batch item may name a task that already exists.
|
|
64
|
+
|
|
65
|
+
`update` merges `metadata` key by key into the existing record; passing `null`
|
|
66
|
+
for a key removes it, and emptying the record drops the field entirely.
|
|
67
|
+
`addBlockedBy` and `removeBlockedBy` are additive — do not resend the whole
|
|
68
|
+
array.
|
|
69
|
+
|
|
70
|
+
## Status transitions
|
|
71
|
+
|
|
72
|
+
| From | Allowed targets |
|
|
73
|
+
| ------------- | ------------------------------------- |
|
|
74
|
+
| `pending` | `in_progress`, `completed`, `deleted` |
|
|
75
|
+
| `in_progress` | `pending`, `completed`, `deleted` |
|
|
76
|
+
| `completed` | `deleted` |
|
|
77
|
+
| `deleted` | _(terminal)_ |
|
|
78
|
+
|
|
79
|
+
A transition to the current status is always accepted and reported as a no-op.
|
|
80
|
+
`delete` keeps the task as a tombstone so historic `blockedBy` references still
|
|
81
|
+
resolve; tombstones are hidden from `list` unless you pass `includeDeleted: true`.
|
|
82
|
+
|
|
83
|
+
## Dependencies
|
|
84
|
+
|
|
85
|
+
`blockedBy` holds the ids this task waits on. Validation runs before the state
|
|
86
|
+
is mutated, so a rejected call leaves the list untouched:
|
|
87
|
+
|
|
88
|
+
- a dependency id that does not exist is rejected;
|
|
89
|
+
- a dependency that is already tombstoned is rejected;
|
|
90
|
+
- blocking a task on itself is rejected;
|
|
91
|
+
- an `addBlockedBy` that would close a cycle in the graph is rejected.
|
|
92
|
+
|
|
93
|
+
`get` also reports the reverse edges as a `blocks:` line, derived from the other
|
|
94
|
+
tasks' `blockedBy` arrays.
|
|
95
|
+
|
|
96
|
+
## Return envelope
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
{
|
|
100
|
+
content: [{ type: "text", text: string }], // human-readable summary of the op
|
|
101
|
+
details: { // compact persisted operation record
|
|
102
|
+
action: TaskAction,
|
|
103
|
+
params: Record<string, unknown>,
|
|
104
|
+
// The live in-memory result also exposes tasks and nextId as compatibility
|
|
105
|
+
// properties; they are omitted from newly serialized session JSON.
|
|
106
|
+
tasks: Array<{
|
|
107
|
+
id: number,
|
|
108
|
+
subject: string,
|
|
109
|
+
description?: string,
|
|
110
|
+
activeForm?: string,
|
|
111
|
+
status: "pending" | "in_progress" | "completed" | "deleted",
|
|
112
|
+
blockedBy?: number[],
|
|
113
|
+
owner?: string,
|
|
114
|
+
metadata?: Record<string, unknown>,
|
|
115
|
+
}>,
|
|
116
|
+
nextId: number,
|
|
117
|
+
taskStatus?: TaskStatus, // render hint for updates without a status parameter
|
|
118
|
+
error?: string, // present only on a rejected call
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Persistence
|
|
124
|
+
|
|
125
|
+
`details` is the persistence boundary. New serialized records contain the
|
|
126
|
+
`action` and `params` needed to replay the operation; they do not repeat the
|
|
127
|
+
cumulative `tasks` and `nextId` snapshot. State-changing calls also save the same
|
|
128
|
+
compact record as a `rpiv-todo-state` custom entry on the session branch. Custom
|
|
129
|
+
entries are never sent to the model.
|
|
130
|
+
|
|
131
|
+
The custom entry matters when `todo` is called from another tool, such as a Pi
|
|
132
|
+
codemode script: Pi records that call only as a short summary on the outer
|
|
133
|
+
tool's result, so its own `details` never reach the branch. Direct calls that
|
|
134
|
+
produce both records are replayed from the custom stream once, not twice.
|
|
135
|
+
|
|
136
|
+
The session-lifecycle handlers rebuild state by replaying compact records in
|
|
137
|
+
branch order. Legacy sessions containing full `tasks`/`nextId` snapshots remain
|
|
138
|
+
supported, and mixed legacy/compact branches are accepted. Either way, tasks
|
|
139
|
+
survive `/reload`, `/resume`, `/tree` and compaction without any disk writes.
|
|
140
|
+
|
|
141
|
+
## Content strings
|
|
142
|
+
|
|
143
|
+
| Situation | `content[0].text` |
|
|
144
|
+
| ------------------------------- | -------------------------------------------------------------------------- |
|
|
145
|
+
| Created | `Created #3: Write the parser (pending)` |
|
|
146
|
+
| Created a batch | one `Created #N: … (pending)` line per task, joined by newlines |
|
|
147
|
+
| Updated with a status change | `Updated #3 (pending → in_progress)` |
|
|
148
|
+
| Updated without a status change | `Updated #3` |
|
|
149
|
+
| Update that changed nothing | `No change: #3 already matches the requested values (status: in_progress)` |
|
|
150
|
+
| Deleted | `Deleted #3: Write the parser` |
|
|
151
|
+
| Cleared | `Cleared 7 tasks` |
|
|
152
|
+
| `list` row | `[in_progress] #3 Write the parser (writing the parser) ⛓ #1,#2` |
|
|
153
|
+
| `list` with nothing to show | `No tasks` |
|
|
154
|
+
| Any rejection | `Error: <message>` |
|
|
155
|
+
|
|
156
|
+
The `No change` reply exists so a model that re-issues an identical update sees
|
|
157
|
+
that it was a no-op instead of a fresh `Updated #N`.
|
|
158
|
+
|
|
159
|
+
## Error messages
|
|
160
|
+
|
|
161
|
+
| Message | Cause |
|
|
162
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
163
|
+
| `subject required for create` | `create` without a non-blank `subject` and without `tasks[]`. |
|
|
164
|
+
| `create requires subject or tasks[], not both` | `create` with both `subject` and `tasks[]`. |
|
|
165
|
+
| `tasks[] must be non-empty` | `create` with `tasks: []`. |
|
|
166
|
+
| `create with tasks[] takes <fields> on each item, not at the top level` | `create` with `tasks[]` and a top-level `description`, `activeForm`, `blockedBy`, `owner`, or `metadata`. |
|
|
167
|
+
| `tasks[N]: subject required for create` | A batch item with a blank or missing subject. |
|
|
168
|
+
| `blockedBy: #N not found` | `create` naming an unknown dependency. |
|
|
169
|
+
| `blockedBy: #N is deleted` | `create` naming a tombstoned dependency. |
|
|
170
|
+
| `blockedBy: #N is another item in this batch; create the prerequisite first, then the dependent with blockedBy` | A `tasks[]` item naming a sibling that this call would assign. |
|
|
171
|
+
| `id required for update` / `get` / `delete` | `id` omitted. |
|
|
172
|
+
| `#N not found` | No task with that id. |
|
|
173
|
+
| `update requires at least one mutable field: subject, description, activeForm, status, owner, metadata, addBlockedBy, or removeBlockedBy` | `update` with only an `id`. |
|
|
174
|
+
| `illegal transition completed → in_progress` | Target status not reachable from the current one. |
|
|
175
|
+
| `cannot block #N on itself` | `addBlockedBy` includes the task's own id. |
|
|
176
|
+
| `addBlockedBy: #N not found` / `is deleted` | Unknown or tombstoned dependency. |
|
|
177
|
+
| `addBlockedBy would create a cycle in the blockedBy graph` | The edge would close a cycle. |
|
|
178
|
+
| `#N is already deleted` | `delete` on a tombstone. |
|
|
179
|
+
|
|
180
|
+
Errors are returned in-band: `content` carries `Error: …` and `details.error`
|
|
181
|
+
carries the bare message. Task state is unchanged.
|
|
182
|
+
|
|
183
|
+
## Prompt guidance
|
|
184
|
+
|
|
185
|
+
The tool ships a `promptSnippet` and nine `promptGuidelines` bullets telling the
|
|
186
|
+
model when to open a list, to create independent tasks in one `tasks[]` call,
|
|
187
|
+
to keep exactly one task `in_progress`, to mark work completed immediately
|
|
188
|
+
rather than in batches, never to complete a task with failing tests, and the
|
|
189
|
+
literal `update {id, status}` call shape for changing a task's status. Both are
|
|
190
|
+
overridable — see
|
|
191
|
+
[configuration.md](./configuration.md#guidance).
|