@indexyz/pi-todo 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 +8 -0
- package/LICENSE +21 -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 +87 -4
- 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/tool/types.ts
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
import { StringEnum } from "@earendil-works/pi-ai";
|
|
2
|
+
import { type Static, Type } from "typebox";
|
|
3
|
+
|
|
4
|
+
// ---------------------------------------------------------------------------
|
|
5
|
+
// Tool / command identity — verbatim string boundaries.
|
|
6
|
+
// Tool name "todo" is the persistence key for branch replay (filtering
|
|
7
|
+
// `toolResult.toolName === "todo"`) AND the permissions entry at
|
|
8
|
+
// `templates/pi-permissions.jsonc:26`. DO NOT rename.
|
|
9
|
+
// ---------------------------------------------------------------------------
|
|
10
|
+
|
|
11
|
+
export const TOOL_NAME = "todo";
|
|
12
|
+
export const TOOL_LABEL = "Todo";
|
|
13
|
+
export const COMMAND_NAME = "todos";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Custom session-entry type carrying the `details` snapshot of every
|
|
17
|
+
* state-changing `todo` call — the replay source that survives calls made
|
|
18
|
+
* through another tool (`ctx.executeTool`, e.g. Pi's codemode), whose results
|
|
19
|
+
* never land on the branch as standalone `toolResult` messages. Persistence key
|
|
20
|
+
* for branch replay, like `TOOL_NAME`. DO NOT rename.
|
|
21
|
+
*/
|
|
22
|
+
export const STATE_ENTRY_TYPE = "rpiv-todo-state";
|
|
23
|
+
|
|
24
|
+
// ---------------------------------------------------------------------------
|
|
25
|
+
// User-facing strings (kept stable for /todos UX parity).
|
|
26
|
+
// ---------------------------------------------------------------------------
|
|
27
|
+
|
|
28
|
+
export const ERR_REQUIRES_INTERACTIVE = "/todos requires interactive mode";
|
|
29
|
+
export const MSG_NO_TODOS = "No todos yet. Ask the agent to add some!";
|
|
30
|
+
|
|
31
|
+
// ---------------------------------------------------------------------------
|
|
32
|
+
// Public domain types
|
|
33
|
+
// ---------------------------------------------------------------------------
|
|
34
|
+
|
|
35
|
+
export type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
|
|
36
|
+
|
|
37
|
+
export type TaskAction = "create" | "update" | "list" | "get" | "delete" | "clear";
|
|
38
|
+
|
|
39
|
+
export interface Task {
|
|
40
|
+
id: number;
|
|
41
|
+
subject: string;
|
|
42
|
+
description?: string;
|
|
43
|
+
activeForm?: string;
|
|
44
|
+
status: TaskStatus;
|
|
45
|
+
blockedBy?: number[];
|
|
46
|
+
owner?: string;
|
|
47
|
+
metadata?: Record<string, unknown>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* In-memory tool details. `tasks` and `nextId` stay available to callers, but
|
|
52
|
+
* the response envelope makes them non-enumerable so session JSON stores the
|
|
53
|
+
* compact action record instead of a cumulative snapshot.
|
|
54
|
+
*/
|
|
55
|
+
export interface TaskDetails extends CompactTaskDetails {
|
|
56
|
+
tasks: Task[];
|
|
57
|
+
nextId: number;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Compact shape read from newly serialized session records. */
|
|
61
|
+
export interface CompactTaskDetails {
|
|
62
|
+
action: TaskAction;
|
|
63
|
+
params: Record<string, unknown>;
|
|
64
|
+
taskStatus?: TaskStatus;
|
|
65
|
+
error?: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Open-shape input bag the reducer accepts. Stays an interface so the index
|
|
70
|
+
* signature (`[key: string]: unknown`) lets the runtime pass through TypeBox
|
|
71
|
+
* `Static<typeof TodoParamsSchema>` without `as` casts.
|
|
72
|
+
*/
|
|
73
|
+
/** One item in a batch `create` `tasks[]` payload. Same create-shaped fields as a single create, minus nested `tasks`. */
|
|
74
|
+
export interface CreateTaskInput {
|
|
75
|
+
subject: string;
|
|
76
|
+
description?: string;
|
|
77
|
+
activeForm?: string;
|
|
78
|
+
blockedBy?: number[];
|
|
79
|
+
owner?: string;
|
|
80
|
+
metadata?: Record<string, unknown>;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export interface TaskMutationParams {
|
|
84
|
+
[key: string]: unknown;
|
|
85
|
+
subject?: string;
|
|
86
|
+
description?: string;
|
|
87
|
+
activeForm?: string;
|
|
88
|
+
status?: TaskStatus;
|
|
89
|
+
blockedBy?: number[];
|
|
90
|
+
addBlockedBy?: number[];
|
|
91
|
+
removeBlockedBy?: number[];
|
|
92
|
+
owner?: string;
|
|
93
|
+
metadata?: Record<string, unknown>;
|
|
94
|
+
id?: number;
|
|
95
|
+
includeDeleted?: boolean;
|
|
96
|
+
/** Batch create items. One-of with `subject` on `create`. */
|
|
97
|
+
tasks?: CreateTaskInput[];
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// ---------------------------------------------------------------------------
|
|
101
|
+
// TypeBox parameter schema — every `description` doubles as LLM-facing prompt
|
|
102
|
+
// copy. Field order and wording are pinned by registration tests.
|
|
103
|
+
// ---------------------------------------------------------------------------
|
|
104
|
+
|
|
105
|
+
const CreateTaskInputSchema = Type.Object({
|
|
106
|
+
subject: Type.String({ description: "Task subject line" }),
|
|
107
|
+
description: Type.Optional(Type.String({ description: "Long-form task description" })),
|
|
108
|
+
activeForm: Type.Optional(
|
|
109
|
+
Type.String({
|
|
110
|
+
description:
|
|
111
|
+
"Present-continuous spinner label shown while status is in_progress (e.g. 'writing tests')",
|
|
112
|
+
}),
|
|
113
|
+
),
|
|
114
|
+
blockedBy: Type.Optional(
|
|
115
|
+
Type.Array(Type.Number(), {
|
|
116
|
+
description:
|
|
117
|
+
"Existing task ids this item waits on. Cannot name another item in this same batch; create the prerequisite first, then the dependent with blockedBy.",
|
|
118
|
+
}),
|
|
119
|
+
),
|
|
120
|
+
owner: Type.Optional(Type.String({ description: "Agent/owner assigned to this task" })),
|
|
121
|
+
metadata: Type.Optional(
|
|
122
|
+
Type.Record(Type.String(), Type.Unknown(), {
|
|
123
|
+
description: "Arbitrary metadata",
|
|
124
|
+
}),
|
|
125
|
+
),
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
export const TodoParamsSchema = Type.Object({
|
|
129
|
+
action: StringEnum(["create", "update", "list", "get", "delete", "clear"] as const),
|
|
130
|
+
subject: Type.Optional(
|
|
131
|
+
Type.String({
|
|
132
|
+
description: "Task subject line (required for create unless tasks[] is set)",
|
|
133
|
+
}),
|
|
134
|
+
),
|
|
135
|
+
description: Type.Optional(Type.String({ description: "Long-form task description" })),
|
|
136
|
+
activeForm: Type.Optional(
|
|
137
|
+
Type.String({
|
|
138
|
+
description:
|
|
139
|
+
"Present-continuous spinner label shown while status is in_progress (e.g. 'writing tests')",
|
|
140
|
+
}),
|
|
141
|
+
),
|
|
142
|
+
status: Type.Optional(
|
|
143
|
+
StringEnum(["pending", "in_progress", "completed", "deleted"] as const, {
|
|
144
|
+
description:
|
|
145
|
+
"Set this task's status (update): one of pending, in_progress, completed, deleted. When action is list, filters returned tasks by this status.",
|
|
146
|
+
}),
|
|
147
|
+
),
|
|
148
|
+
blockedBy: Type.Optional(
|
|
149
|
+
Type.Array(Type.Number(), {
|
|
150
|
+
description: "Initial blockedBy ids (create only)",
|
|
151
|
+
}),
|
|
152
|
+
),
|
|
153
|
+
addBlockedBy: Type.Optional(
|
|
154
|
+
Type.Array(Type.Number(), {
|
|
155
|
+
description: "Task ids to add to blockedBy (update only, additive merge)",
|
|
156
|
+
}),
|
|
157
|
+
),
|
|
158
|
+
removeBlockedBy: Type.Optional(
|
|
159
|
+
Type.Array(Type.Number(), {
|
|
160
|
+
description: "Task ids to remove from blockedBy (update only, additive merge)",
|
|
161
|
+
}),
|
|
162
|
+
),
|
|
163
|
+
owner: Type.Optional(Type.String({ description: "Agent/owner assigned to this task" })),
|
|
164
|
+
metadata: Type.Optional(
|
|
165
|
+
Type.Record(Type.String(), Type.Unknown(), {
|
|
166
|
+
description: "Arbitrary metadata; pass null value for a key to delete that key on update",
|
|
167
|
+
}),
|
|
168
|
+
),
|
|
169
|
+
id: Type.Optional(
|
|
170
|
+
Type.Number({
|
|
171
|
+
description: "Task id (required for update, get, delete)",
|
|
172
|
+
}),
|
|
173
|
+
),
|
|
174
|
+
includeDeleted: Type.Optional(
|
|
175
|
+
Type.Boolean({
|
|
176
|
+
description:
|
|
177
|
+
"If true, list action returns deleted (tombstoned) tasks as well. Default: false.",
|
|
178
|
+
}),
|
|
179
|
+
),
|
|
180
|
+
tasks: Type.Optional(
|
|
181
|
+
Type.Array(CreateTaskInputSchema, {
|
|
182
|
+
description:
|
|
183
|
+
"Batch create: independent tasks in one call, one-of with subject. The whole list is validated then committed together. Items cannot blockedBy each other; create the prerequisite first, then the dependent with blockedBy.",
|
|
184
|
+
}),
|
|
185
|
+
),
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
export type TodoParams = Static<typeof TodoParamsSchema>;
|
package/view/format.ts
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
import type { Theme } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { Text } from "@earendil-works/pi-tui";
|
|
3
|
+
import { formatStatusLabel } from "../state/i18n-bridge.ts";
|
|
4
|
+
import { selectTaskSubjectById } from "../state/selectors.ts";
|
|
5
|
+
import type { TaskState } from "../state/state.ts";
|
|
6
|
+
import { sanitizeTerminalText } from "../tool/sanitize.ts";
|
|
7
|
+
import type {
|
|
8
|
+
Task,
|
|
9
|
+
TaskAction,
|
|
10
|
+
TaskDetails,
|
|
11
|
+
TaskMutationParams,
|
|
12
|
+
TaskStatus,
|
|
13
|
+
} from "../tool/types.ts";
|
|
14
|
+
|
|
15
|
+
// Re-export so legacy import paths (todo.ts, tests) continue to resolve;
|
|
16
|
+
// the canonical definition lives in the i18n bridge.
|
|
17
|
+
export { formatStatusLabel };
|
|
18
|
+
|
|
19
|
+
// ---------------------------------------------------------------------------
|
|
20
|
+
// Status presentation tables — the single source of truth for glyph/color.
|
|
21
|
+
// ---------------------------------------------------------------------------
|
|
22
|
+
|
|
23
|
+
export const STATUS_GLYPH: Record<TaskStatus, string> = {
|
|
24
|
+
pending: "○",
|
|
25
|
+
in_progress: "◐",
|
|
26
|
+
completed: "●",
|
|
27
|
+
deleted: "⊘",
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Color palette for the renderResult status echo. `deleted` uses `muted` so a
|
|
32
|
+
* successful delete is visually distinct from the error branch (which uses
|
|
33
|
+
* `error` + `✗`).
|
|
34
|
+
*/
|
|
35
|
+
export const STATUS_COLOR: Record<TaskStatus, "dim" | "warning" | "success" | "muted"> = {
|
|
36
|
+
pending: "dim",
|
|
37
|
+
in_progress: "warning",
|
|
38
|
+
completed: "success",
|
|
39
|
+
deleted: "muted",
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Per-action prefix glyph for renderCall. `+` create, `→` update, `×` delete,
|
|
44
|
+
* `›` get, `☰` list, `∅` clear.
|
|
45
|
+
*/
|
|
46
|
+
export const ACTION_GLYPH: Record<TaskAction, string> = {
|
|
47
|
+
create: "+",
|
|
48
|
+
update: "→",
|
|
49
|
+
delete: "×",
|
|
50
|
+
get: "›",
|
|
51
|
+
list: "☰",
|
|
52
|
+
clear: "∅",
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Glyph for the persistent overlay's per-task row. Differs from `STATUS_GLYPH`
|
|
57
|
+
* for `completed` (`✓` vs `●`) and `deleted` (`✗` vs `⊘`) because the
|
|
58
|
+
* overlay caller never renders a `deleted` row but uses `✗` in its
|
|
59
|
+
* error-toned palette.
|
|
60
|
+
*/
|
|
61
|
+
export function overlayStatusGlyph(status: TaskStatus, theme: Theme): string {
|
|
62
|
+
switch (status) {
|
|
63
|
+
case "pending":
|
|
64
|
+
return theme.fg("dim", "○");
|
|
65
|
+
case "in_progress":
|
|
66
|
+
return theme.fg("warning", "◐");
|
|
67
|
+
case "completed":
|
|
68
|
+
return theme.fg("success", "✓");
|
|
69
|
+
case "deleted":
|
|
70
|
+
return theme.fg("error", "✗");
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Format a single task row for the persistent overlay. The subject color
|
|
76
|
+
* reflects task state while IDs and supporting metadata stay visually quiet.
|
|
77
|
+
*/
|
|
78
|
+
export function formatOverlayTaskLine(t: Task, theme: Theme, showId: boolean): string {
|
|
79
|
+
const glyph = overlayStatusGlyph(t.status, theme);
|
|
80
|
+
const subjectColor =
|
|
81
|
+
t.status === "in_progress"
|
|
82
|
+
? "accent"
|
|
83
|
+
: t.status === "completed" || t.status === "deleted"
|
|
84
|
+
? "muted"
|
|
85
|
+
: "text";
|
|
86
|
+
let subject = theme.fg(subjectColor, sanitizeTerminalText(t.subject));
|
|
87
|
+
if (t.status === "completed" || t.status === "deleted") {
|
|
88
|
+
subject = theme.strikethrough(subject);
|
|
89
|
+
}
|
|
90
|
+
let line = `${glyph}`;
|
|
91
|
+
if (showId) line += ` ${theme.fg("dim", `#${t.id}`)}`;
|
|
92
|
+
line += ` ${subject}`;
|
|
93
|
+
if (t.status === "in_progress" && t.activeForm) {
|
|
94
|
+
line += ` ${theme.fg("muted", `(${sanitizeTerminalText(t.activeForm)})`)}`;
|
|
95
|
+
}
|
|
96
|
+
if (t.blockedBy && t.blockedBy.length > 0) {
|
|
97
|
+
line += ` ${theme.fg("muted", `⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}`)}`;
|
|
98
|
+
}
|
|
99
|
+
return line;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Format a single task line for the `/todos` slash command (no glyph color,
|
|
104
|
+
* indented bullet prefix).
|
|
105
|
+
*/
|
|
106
|
+
export function formatCommandTaskLine(t: Task, glyph: string): string {
|
|
107
|
+
const form =
|
|
108
|
+
t.status === "in_progress" && t.activeForm ? ` (${sanitizeTerminalText(t.activeForm)})` : "";
|
|
109
|
+
const block = t.blockedBy?.length ? ` ⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}` : "";
|
|
110
|
+
return ` ${glyph} #${t.id} ${sanitizeTerminalText(t.subject)}${form}${block}`;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// ---------------------------------------------------------------------------
|
|
114
|
+
// Tool render hooks — wrapped so `todo.ts` becomes a thin call-site.
|
|
115
|
+
// ---------------------------------------------------------------------------
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* `renderCall` body. Receives the call's args, the theme, and the live
|
|
119
|
+
* `TaskState` (resolved by the caller via `getRenderState()`). The args may
|
|
120
|
+
* still be streaming or may fail validation, so `action` can be absent.
|
|
121
|
+
*/
|
|
122
|
+
export function renderTodoCall(
|
|
123
|
+
args: TaskMutationParams & { action?: TaskAction },
|
|
124
|
+
theme: Theme,
|
|
125
|
+
state: TaskState,
|
|
126
|
+
): Text {
|
|
127
|
+
let text = theme.fg("toolTitle", theme.bold("todo "));
|
|
128
|
+
if (args.action) text += theme.fg("muted", ACTION_GLYPH[args.action] ?? args.action);
|
|
129
|
+
|
|
130
|
+
if (args.action === "create" && args.subject) {
|
|
131
|
+
text += ` ${theme.fg("dim", sanitizeTerminalText(args.subject))}`;
|
|
132
|
+
} else if (args.action === "create" && Array.isArray(args.tasks)) {
|
|
133
|
+
text += ` ${theme.fg("dim", `${args.tasks.length} tasks`)}`;
|
|
134
|
+
} else if (
|
|
135
|
+
(args.action === "update" || args.action === "get" || args.action === "delete") &&
|
|
136
|
+
args.id !== undefined
|
|
137
|
+
) {
|
|
138
|
+
const subject = selectTaskSubjectById(state, args.id);
|
|
139
|
+
text += ` ${theme.fg("accent", subject ? sanitizeTerminalText(subject) : `#${args.id}`)}`;
|
|
140
|
+
} else if (args.action === "list" && args.status) {
|
|
141
|
+
text += ` ${theme.fg("muted", formatStatusLabel(args.status))}`;
|
|
142
|
+
}
|
|
143
|
+
return new Text(text, 0, 0);
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* `renderResult` body. A failed call renders `✗` with its reason; a successful
|
|
148
|
+
* `create`/`update`/`delete` echoes the task's status; anything else is `✓`.
|
|
149
|
+
*/
|
|
150
|
+
export function renderTodoResult(result: ToolResultView, theme: Theme, isError = false): Text {
|
|
151
|
+
const failure = failureReason(result, isError);
|
|
152
|
+
if (failure !== undefined)
|
|
153
|
+
return new Text(theme.fg("error", failure ? `✗ ${failure}` : "✗"), 0, 0);
|
|
154
|
+
|
|
155
|
+
const status = echoedStatus(result.details as TaskDetails | undefined);
|
|
156
|
+
if (status) {
|
|
157
|
+
return new Text(
|
|
158
|
+
theme.fg(STATUS_COLOR[status], `${STATUS_GLYPH[status]} ${formatStatusLabel(status)}`),
|
|
159
|
+
0,
|
|
160
|
+
0,
|
|
161
|
+
);
|
|
162
|
+
}
|
|
163
|
+
return new Text(theme.fg("success", "✓"), 0, 0);
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
type ToolResultView = { content?: Array<{ type: string; text?: string }>; details?: unknown };
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* First line of the failure message, or `undefined` when the call succeeded.
|
|
170
|
+
* The reducer reports through `details.error`; Pi rejects a call before execute
|
|
171
|
+
* with `isError` and the message as text content.
|
|
172
|
+
*/
|
|
173
|
+
function failureReason(result: ToolResultView, isError: boolean): string | undefined {
|
|
174
|
+
const reducerError = (result.details as TaskDetails | undefined)?.error;
|
|
175
|
+
if (!isError && !reducerError) return undefined;
|
|
176
|
+
const message = reducerError ?? result.content?.find((c) => c.type === "text")?.text ?? "";
|
|
177
|
+
return sanitizeTerminalText(message.split("\n")[0]);
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** Status the result card echoes: the task the call created, updated or deleted. */
|
|
181
|
+
function echoedStatus(
|
|
182
|
+
details: (Omit<TaskDetails, "tasks" | "nextId"> & { tasks?: Task[] }) | undefined,
|
|
183
|
+
): TaskStatus | undefined {
|
|
184
|
+
if (!details) return undefined;
|
|
185
|
+
const params = details.params as TaskMutationParams;
|
|
186
|
+
switch (details.action) {
|
|
187
|
+
case "create":
|
|
188
|
+
return details.tasks?.at(-1)?.status ?? "pending";
|
|
189
|
+
case "update":
|
|
190
|
+
return (
|
|
191
|
+
params?.status ??
|
|
192
|
+
details.taskStatus ??
|
|
193
|
+
details.tasks?.find((t) => t.id === params?.id)?.status
|
|
194
|
+
);
|
|
195
|
+
case "delete":
|
|
196
|
+
return details.tasks?.find((t) => t.id === params?.id)?.status ?? "deleted";
|
|
197
|
+
case "list":
|
|
198
|
+
case "get":
|
|
199
|
+
case "clear":
|
|
200
|
+
return undefined;
|
|
201
|
+
}
|
|
202
|
+
}
|