@oisin-ee/pi-dogsled 0.34.2 → 0.36.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.
@@ -1,105 +1,101 @@
1
- import type { CustomEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
2
- import type { ExecutionRef, TodoList, UnitRef } from "./wasm.ts";
3
- import { parse } from "./wasm.ts";
1
+ import type { BranchEntry, ListFrame } from "./branch-state.ts";
2
+ import { DELTA_ENTRY, STATE_ENTRY, stateChange } from "./delta.ts";
3
+ import type { Immutable, TodoDelta } from "./delta.ts";
4
+ import type { Subtask, TodoList } from "./wasm.ts";
5
+ import { deltaData, snapshotData } from "./delta-validation.ts";
6
+ import { BranchState } from "./branch-state.ts";
4
7
 
5
- /** The snapshot of a branch with no list yet. */
6
- const EMPTY: unknown = { tasks: [] },
7
- /** The custom entry that holds the list after every change. */
8
- STATE_ENTRY = "todo-state",
9
- /**
10
- * Whether `entry` is a stored list.
11
- * @param {SessionEntry} entry A branch entry.
12
- * @returns {boolean} True for a `todo-state` custom entry.
13
- */
14
- isStateEntry = (entry: SessionEntry): entry is CustomEntry =>
15
- entry.type === "custom" && entry.customType === STATE_ENTRY,
8
+ /**
9
+ * Replays full snapshots and deltas in branch order, in O(entries + changed tasks).
10
+ * Full lists are materialized only on request; retained frames remain stable.
11
+ * @param {readonly BranchEntry[]} branch Entries in chronological order.
12
+ * @yields {ListFrame} State after each task entry, with changed records and lazy lists.
13
+ */
14
+ const branchList = function* branchList(branch: readonly BranchEntry[]): Generator<ListFrame> {
15
+ const state = new BranchState();
16
+ for (const entry of branch) {
17
+ const frame = state.read(entry);
18
+ if (frame !== undefined) {
19
+ yield frame;
20
+ }
21
+ }
22
+ },
16
23
  /**
17
- * The latest stored snapshot on the branch, unvalidated: the core validates it.
18
- * @param {readonly SessionEntry[]} branch The session branch, oldest entry first.
19
- * @returns {unknown} The latest snapshot, or an empty list when there is none.
24
+ * Finds the final folded frame.
25
+ * @param {readonly BranchEntry[]} branch Current branch.
26
+ * @returns {ListFrame | undefined} Last frame.
20
27
  */
21
- latestSnapshot = (branch: readonly SessionEntry[]): unknown => {
22
- for (const entry of branch.toReversed()) {
23
- if (isStateEntry(entry)) {
24
- return entry.data;
25
- }
28
+ latestFrame = (branch: readonly BranchEntry[]): ListFrame | undefined => {
29
+ let latest: ListFrame | undefined = undefined;
30
+ for (const frame of branchList(branch)) {
31
+ latest = frame;
26
32
  }
27
- return EMPTY;
33
+ return latest;
28
34
  },
29
35
  /**
30
- * Resolves the first branch entry for a contract revision.
31
- * @param {Readonly<UnitRef>} reference Revision identity.
32
- * @param {string} entryId Containing Pi entry.
33
- * @param {Readonly<Map<string, string>>} origins Prior branch origins.
34
- * @returns {string} The revision's originating entry.
36
+ * Reads the final stored list.
37
+ * @param {readonly BranchEntry[]} branch Current branch.
38
+ * @returns {TodoList} Stored list.
35
39
  */
36
- originFor = (
37
- reference: Readonly<UnitRef>,
38
- entryId: string,
39
- origins: Readonly<Map<string, string>>,
40
- ): string => {
41
- const key = JSON.stringify([reference.sessionId, reference.unitId, reference.revision]),
42
- origin = origins.get(key) ?? entryId;
43
- origins.set(key, origin);
44
- return origin;
45
- };
46
-
47
- /** Derives entry provenance without rewriting the imported lead reference. */
48
- class Provenance {
49
- readonly #origins = new Map<string, string>();
50
- readonly #seals = new Map<string, string>();
51
-
40
+ latestSnapshot = (branch: readonly BranchEntry[]): TodoList =>
41
+ latestFrame(branch)?.list ?? { tasks: [] },
52
42
  /**
53
- * Resolves contract and seal provenance for one task snapshot.
54
- * @param {Readonly<object>} unit Task provenance fields.
55
- * @param {string} entryId Snapshot identity.
43
+ * Reads the final list with revision and seal origins.
44
+ * @param {readonly BranchEntry[]} branch Current branch.
45
+ * @returns {TodoList} Resolved list.
56
46
  */
57
- public resolve(
58
- unit: {
59
- readonly reference: Readonly<UnitRef>;
60
- readonly imported:
61
- | {
62
- readonly seed: { readonly execution: Readonly<ExecutionRef> };
63
- readonly seal: { readonly entryId: string } | undefined;
64
- }
65
- | undefined;
66
- },
67
- entryId: string,
68
- ): void {
69
- if (unit.imported === undefined) {
70
- Object.assign(unit.reference, {
71
- contractEntryId: originFor(unit.reference, entryId, this.#origins),
72
- });
73
- } else if (unit.imported.seal !== undefined) {
74
- const key = JSON.stringify(unit.imported.seed.execution),
75
- sealEntry = this.#seals.get(key) ?? entryId;
76
- this.#seals.set(key, sealEntry);
77
- Object.assign(unit.imported.seal, { entryId: sealEntry });
47
+ branchSnapshot = (branch: readonly BranchEntry[]): TodoList =>
48
+ latestFrame(branch)?.snapshot ?? { tasks: [] },
49
+ /**
50
+ * Reads records across the session tree without combining unrelated branches.
51
+ * @param {BranchEntry} entry One persisted entry.
52
+ * @returns {readonly Immutable<Subtask>[]} Validated changed records.
53
+ */
54
+ entryTasks = (entry: BranchEntry): readonly Immutable<Subtask>[] => {
55
+ if (entry.type !== "custom") {
56
+ return [];
78
57
  }
79
- }
80
- }
81
-
82
- /**
83
- * Reads revision origins from the entries that first introduced them.
84
- * Status-only snapshots cannot move a revision's origin.
85
- * @param {readonly SessionEntry[]} branch Current branch in chronological order.
86
- * @returns {TodoList} Validated snapshot with derived provenance.
87
- */
88
- const branchSnapshot = (branch: readonly SessionEntry[]): TodoList => {
89
- const provenance = new Provenance();
90
- let current: TodoList = { tasks: [] };
91
- for (const entry of branch.filter((candidate) => isStateEntry(candidate))) {
92
- current = parse(entry.data);
93
- for (const task of current.tasks.flatMap((root) => [root, ...(root.subtasks ?? [])])) {
94
- if (task.unit !== undefined) {
95
- provenance.resolve(
96
- { imported: task.unit.imported, reference: task.unit.reference },
97
- entry.id,
98
- );
58
+ if (entry.customType === DELTA_ENTRY) {
59
+ return deltaData(entry.data).changed.map((change) => change.task);
60
+ }
61
+ const tasks: Immutable<Subtask>[] = [];
62
+ if (entry.customType === STATE_ENTRY) {
63
+ for (const root of snapshotData(entry.data).list.tasks) {
64
+ tasks.push(root, ...(root.subtasks ?? []));
99
65
  }
100
66
  }
101
- }
102
- return current;
103
- };
67
+ return tasks;
68
+ },
69
+ /**
70
+ * Appends the downgrade fence before the first delta and marks later snapshots.
71
+ * @param {TodoList} before Current list.
72
+ * @param {TodoList} after Changed list.
73
+ * @param {object} session Branch reader and entry writer.
74
+ */
75
+ saveState = (
76
+ before: TodoList,
77
+ after: TodoList,
78
+ session: {
79
+ readonly branch: () => readonly BranchEntry[];
80
+ readonly append: (customType: string, data: TodoList | TodoDelta, list: TodoList) => void;
81
+ },
82
+ ): void => {
83
+ const change = stateChange(before, after),
84
+ fenced = latestFrame(session.branch())?.fenced === true,
85
+ format = "todo-delta/1";
86
+ if (change.customType === DELTA_ENTRY && !fenced) {
87
+ // Authorize the intended mutation before appending even its fence.
88
+ session.append(STATE_ENTRY, Object.assign({}, before, { format }), after);
89
+ }
90
+ session.append(
91
+ change.customType,
92
+ change.customType === STATE_ENTRY && fenced
93
+ ? Object.assign({}, change.data, { format })
94
+ : change.data,
95
+ after,
96
+ );
97
+ };
104
98
 
105
- export { STATE_ENTRY, branchSnapshot, latestSnapshot };
99
+ export { branchList, branchSnapshot, latestSnapshot, entryTasks, saveState };
100
+ export { DELTA_ENTRY, STATE_ENTRY, stateChange } from "./delta.ts";
101
+ export type { TodoDelta } from "./delta.ts";
@@ -1,7 +1,8 @@
1
- import { STATE_ENTRY, branchSnapshot } from "./state.ts";
2
1
  import { apply, view } from "./wasm.ts";
2
+ import { branchSnapshot, saveState } from "./state.ts";
3
3
  import type { SessionEntry } from "@earendil-works/pi-coding-agent";
4
4
  import type { Static } from "typebox";
5
+ import type { TodoDelta } from "./state.ts";
5
6
  import type { TodoList } from "./wasm.ts";
6
7
  import type { parameters } from "./schema.ts";
7
8
  import { workUnitGuidance } from "./guidance.ts";
@@ -13,7 +14,7 @@ type TodoParams = Static<typeof parameters>;
13
14
  interface TodoSession {
14
15
  readonly sessionId: string;
15
16
  readonly branch: () => readonly SessionEntry[];
16
- readonly append: (customType: string, list: TodoList) => void;
17
+ readonly append: (customType: string, data: TodoList | TodoDelta, list: TodoList) => void;
17
18
  }
18
19
 
19
20
  /** The tool result: the summary for the model and the list for rendering. */
@@ -48,7 +49,7 @@ const result = (list: TodoList, creation: boolean): TodoResult => ({
48
49
  sessionId: session.sessionId,
49
50
  });
50
51
  if (persist) {
51
- session.append(STATE_ENTRY, list);
52
+ saveState(current, list, session);
52
53
  }
53
54
  return result(
54
55
  persist ? branchSnapshot(session.branch()) : list,
@@ -25,6 +25,7 @@ export {
25
25
  completion_reminder as completionReminder,
26
26
  init,
27
27
  parse,
28
+ validateTask,
28
29
  sections,
29
30
  view,
30
31
  widget,
@@ -48,6 +48,24 @@ dogsled inbox list
48
48
 
49
49
  `send` writes to the target's inbox on its host. Its reader injects the message: Pi as a steer or a new turn. A target without a reader fails at once and you hear so. Delivery retries with backoff until acknowledged.
50
50
 
51
+ ## Pass files and changes
52
+
53
+ ```sh
54
+ dogsled transfer send NAME_OR_PANE --files notes.md report.png
55
+ dogsled transfer send NAME_OR_PANE --changes [--since REV] [--include-worktree]
56
+ dogsled transfer list
57
+ dogsled transfer show ID
58
+ dogsled transfer apply ID --check
59
+ dogsled transfer apply ID
60
+ dogsled transfer drop ID
61
+ ```
62
+
63
+ Use `transfer` to give another agent files, unpushed commits, or uncommitted work. Do not copy files by hand, and do not push a branch only to share it.
64
+ `send` stores the transfer and puts one notice in the recipient's inbox. It changes no checkout.
65
+ `--changes` sends your commits since `--since` (default: where your checkout left the default branch). Add `--include-worktree` for staged, unstaged, and untracked files.
66
+ When you receive a notice, run `show`, then `apply ID --check`, then `apply ID` in your checkout. `apply` writes working files only and refuses the whole transfer if a touched path differs.
67
+ A transfer does not complete a task. Commit and report as usual.
68
+
51
69
  ## Closing
52
70
 
53
71
  `done` means your work is finished: hand it back, release your resources, and end your agent. Call it during the final working turn, after committing changes. The child host captures your reply and closes your pane and agent worktree when the turn ends. Your branch stays for the owner to land. Closed children remain under TO LAND until integration or branch deletion.