pi-daddy 0.59.1 → 0.60.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.
Files changed (118) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +101 -19
  3. package/contracts/ledger-record/v1/README.md +6 -0
  4. package/dist/executors/activity-session.d.ts +4 -0
  5. package/dist/executors/activity-session.d.ts.map +1 -1
  6. package/dist/executors/activity-session.js +19 -0
  7. package/dist/executors/activity-session.js.map +1 -1
  8. package/dist/executors/child-final.d.ts +2 -0
  9. package/dist/executors/child-final.d.ts.map +1 -1
  10. package/dist/executors/child-final.js +4 -0
  11. package/dist/executors/child-final.js.map +1 -1
  12. package/dist/executors/child-usage.d.ts +129 -0
  13. package/dist/executors/child-usage.d.ts.map +1 -0
  14. package/dist/executors/child-usage.js +202 -0
  15. package/dist/executors/child-usage.js.map +1 -0
  16. package/dist/governance/auto-mode-policy.d.ts +3 -0
  17. package/dist/governance/auto-mode-policy.d.ts.map +1 -1
  18. package/dist/governance/auto-mode-policy.js +18 -2
  19. package/dist/governance/auto-mode-policy.js.map +1 -1
  20. package/dist/governance/operation-artifacts.d.ts +2 -0
  21. package/dist/governance/operation-artifacts.d.ts.map +1 -1
  22. package/dist/governance/operation-artifacts.js +20 -1
  23. package/dist/governance/operation-artifacts.js.map +1 -1
  24. package/dist/governance/operation-replay.d.ts +7 -0
  25. package/dist/governance/operation-replay.d.ts.map +1 -0
  26. package/dist/governance/operation-replay.js +47 -0
  27. package/dist/governance/operation-replay.js.map +1 -0
  28. package/dist/governance/parent-tool-calls.d.ts +31 -0
  29. package/dist/governance/parent-tool-calls.d.ts.map +1 -0
  30. package/dist/governance/parent-tool-calls.js +156 -0
  31. package/dist/governance/parent-tool-calls.js.map +1 -0
  32. package/dist/kernel/child-tools.d.ts +9 -1
  33. package/dist/kernel/child-tools.d.ts.map +1 -1
  34. package/dist/kernel/child-tools.js +25 -5
  35. package/dist/kernel/child-tools.js.map +1 -1
  36. package/dist/kernel/delegate-types.d.ts +26 -0
  37. package/dist/kernel/delegate-types.d.ts.map +1 -1
  38. package/dist/kernel/delegate-types.js.map +1 -1
  39. package/dist/kernel/delegate.d.ts.map +1 -1
  40. package/dist/kernel/delegate.js +19 -1
  41. package/dist/kernel/delegate.js.map +1 -1
  42. package/dist/kernel/dispatch-operation.d.ts +14 -0
  43. package/dist/kernel/dispatch-operation.d.ts.map +1 -1
  44. package/dist/kernel/dispatch-operation.js.map +1 -1
  45. package/dist/kernel/env-names.d.ts +16 -0
  46. package/dist/kernel/env-names.d.ts.map +1 -1
  47. package/dist/kernel/env-names.js +20 -0
  48. package/dist/kernel/env-names.js.map +1 -1
  49. package/dist/kernel/parent-tools.d.ts +174 -0
  50. package/dist/kernel/parent-tools.d.ts.map +1 -0
  51. package/dist/kernel/parent-tools.js +268 -0
  52. package/dist/kernel/parent-tools.js.map +1 -0
  53. package/dist/kernel/propagation.d.ts +1 -1
  54. package/dist/kernel/propagation.d.ts.map +1 -1
  55. package/dist/kernel/propagation.js +5 -0
  56. package/dist/kernel/propagation.js.map +1 -1
  57. package/dist/kernel/replay-safe.d.ts +110 -0
  58. package/dist/kernel/replay-safe.d.ts.map +1 -0
  59. package/dist/kernel/replay-safe.js +121 -0
  60. package/dist/kernel/replay-safe.js.map +1 -0
  61. package/dist/products/dashboard-cli.d.ts.map +1 -1
  62. package/dist/products/dashboard-cli.js +1 -0
  63. package/dist/products/dashboard-cli.js.map +1 -1
  64. package/dist/products/dashboard-render.d.ts +5 -0
  65. package/dist/products/dashboard-render.d.ts.map +1 -1
  66. package/dist/products/dashboard-render.js +25 -0
  67. package/dist/products/dashboard-render.js.map +1 -1
  68. package/dist/products/dashboard-session-client.d.ts +6 -0
  69. package/dist/products/dashboard-session-client.d.ts.map +1 -1
  70. package/dist/products/dashboard-session-client.js.map +1 -1
  71. package/dist/products/episode-report.d.ts +2 -0
  72. package/dist/products/episode-report.d.ts.map +1 -1
  73. package/dist/products/episode-report.js +5 -1
  74. package/dist/products/episode-report.js.map +1 -1
  75. package/extensions/chain-plan.ts +6 -1
  76. package/extensions/child-usage-report.ts +77 -0
  77. package/extensions/dashboard-session-server.ts +12 -0
  78. package/extensions/definition-describe.ts +74 -16
  79. package/extensions/delegate-chain.ts +37 -10
  80. package/extensions/delegation-artifacts.ts +43 -1
  81. package/extensions/delegation-operations.ts +71 -33
  82. package/extensions/delegation.ts +86 -15
  83. package/extensions/execute-child.ts +62 -6
  84. package/extensions/execution-evidence.ts +139 -4
  85. package/extensions/fanout-outcome.ts +4 -1
  86. package/extensions/grants-command.ts +12 -1
  87. package/extensions/grants.ts +17 -1
  88. package/extensions/init-command.ts +1 -1
  89. package/extensions/parent-tool-host.ts +228 -0
  90. package/extensions/parent-tool-proxy.ts +44 -0
  91. package/extensions/public-evidence.ts +8 -2
  92. package/extensions/reload-environment.ts +6 -0
  93. package/extensions/replay-retry.ts +119 -0
  94. package/extensions/run-delegation.ts +77 -12
  95. package/extensions/runtime-snapshot.ts +16 -1
  96. package/extensions/session-report.ts +16 -0
  97. package/extensions/session.ts +9 -0
  98. package/extensions/spawn-summary.ts +31 -0
  99. package/package.json +2 -2
  100. package/src/executors/activity-session.ts +28 -0
  101. package/src/executors/child-final.ts +11 -1
  102. package/src/executors/child-usage.ts +280 -0
  103. package/src/governance/auto-mode-policy.ts +19 -2
  104. package/src/governance/operation-artifacts.ts +21 -1
  105. package/src/governance/operation-replay.ts +70 -0
  106. package/src/governance/parent-tool-calls.ts +191 -0
  107. package/src/kernel/child-tools.ts +39 -9
  108. package/src/kernel/delegate-types.ts +26 -0
  109. package/src/kernel/delegate.ts +17 -1
  110. package/src/kernel/dispatch-operation.ts +11 -0
  111. package/src/kernel/env-names.ts +20 -0
  112. package/src/kernel/parent-tools.ts +342 -0
  113. package/src/kernel/propagation.ts +5 -0
  114. package/src/kernel/replay-safe.ts +182 -0
  115. package/src/products/dashboard-cli.ts +1 -0
  116. package/src/products/dashboard-render.ts +25 -0
  117. package/src/products/dashboard-session-client.ts +2 -0
  118. package/src/products/episode-report.ts +8 -1
@@ -0,0 +1,182 @@
1
+ /**
2
+ * Replay-safe children: the kernel half (owner decision of 2026-11-17, "Read-only work, once").
3
+ *
4
+ * A child whose effective capabilities only read cannot change anything, so one failed attempt of it may be run
5
+ * again with the same inputs. Everything else still stops and asks. Two pure questions are answered here, and
6
+ * nowhere else:
7
+ *
8
+ * - is a capability set replay-safe (`replaySafe`), and is a declared ceiling (`replaySafeCeiling`);
9
+ * - does a first attempt that failed qualify for its one retry (`replayRetryDecision`), judged only from facts
10
+ * Daddy settled itself: exit code, timeout and cancellation flags, the captured final and the cleanup receipt;
11
+ * under a stable operation the same answer only marks the failure replayable for the operation's owner.
12
+ *
13
+ * Nothing here spawns, reserves capacity, plans or reads the environment. Composition supplies the facts and runs
14
+ * the retry through the ordinary delegation path, so the retry is planned, gated, recorded and bounded exactly as a
15
+ * fresh delegation is.
16
+ */
17
+ import { isContextCapability } from "./context-handoff.ts";
18
+ import { ENV_REPLAY_RETRY } from "./env-names.ts";
19
+ import type { Capability } from "./resolve.ts";
20
+
21
+ /**
22
+ * Native Pi tools that only read. Closed, and widened only by a dated decision in AGENTS.md: `bash`, `write`,
23
+ * `edit`, `edit-diff` and `parallel` are absent, as are `delegate`, every extension tool (a parent-run tool such as
24
+ * `scout_research` has external effects and cost) and every wildcard.
25
+ */
26
+ export const REPLAY_SAFE_TOOLS: readonly Capability[] = Object.freeze([
27
+ "tool:find",
28
+ "tool:grep",
29
+ "tool:ls",
30
+ "tool:read",
31
+ ]);
32
+
33
+ /**
34
+ * True only when every capability is a read-only native tool or a context handoff mode. Context modes only read:
35
+ * the parent names files, writes a summary, or lends a copy of its session, and the child writes none of them.
36
+ * Any other namespace (`agent:`, `skill:`, `ext:`, `workspace:`) makes the set unsafe. An empty set is safe: a
37
+ * child with no tools can only answer.
38
+ */
39
+ export function replaySafe(capabilities: readonly Capability[]): boolean {
40
+ return capabilities.every((capability) => REPLAY_SAFE_TOOLS.includes(capability) || isContextCapability(capability));
41
+ }
42
+
43
+ /**
44
+ * A definition's declared ceiling. An undeclared or pattern ceiling is never replay-safe, whatever its explicit
45
+ * entries say: the planner refuses both, and an empty undeclared list must not read as "no tools".
46
+ */
47
+ export function replaySafeCeiling(ceiling: {
48
+ capabilities: readonly Capability[];
49
+ patterns: readonly string[];
50
+ undeclared: boolean;
51
+ }): boolean {
52
+ return !ceiling.undeclared && ceiling.patterns.length === 0 && replaySafe(ceiling.capabilities);
53
+ }
54
+
55
+ /**
56
+ * The operator's kill switch for the automatic retry; replay-safe marking is unaffected. Unset or literal `1`
57
+ * leaves it on, literal `0` turns it off, and anything else is malformed and also off.
58
+ */
59
+ export function replayRetrySwitch(raw: string | undefined): { enabled: boolean; malformed: boolean } {
60
+ if (raw === undefined || raw === "1") return { enabled: true, malformed: false };
61
+ return { enabled: false, malformed: raw !== "0" };
62
+ }
63
+
64
+ /** Why the first attempt failed, in one fixed phrase. Fixed, so child output never reaches the model through it. */
65
+ export type ReplayFailure =
66
+ "process exited without a final" | "spawn failed transiently" | "timed out" | "provider request failed";
67
+
68
+ /** Resource exhaustion before a worker existed. Anything else a spawn reports is a configuration fault. */
69
+ const TRANSIENT_SPAWN = /\b(?:EAGAIN|EMFILE|ENFILE|ENOMEM)\b/;
70
+
71
+ /** The settlement facts of one finished attempt, as Daddy recorded them. */
72
+ export interface ReplayAttempt {
73
+ ok: boolean;
74
+ /** Absent only when nothing ran: the planner, a gate or a preflight refused before launch. */
75
+ work?: string;
76
+ exitCode: number | null;
77
+ timedOut?: boolean;
78
+ aborted?: boolean;
79
+ spawnFailed?: boolean;
80
+ spawnError?: string;
81
+ control?: "failed";
82
+ final?: { state: string; providerError?: true };
83
+ cleanup?: { state: string };
84
+ observation?: { state: string };
85
+ }
86
+
87
+ /** The transient failure this attempt shows, or none. A child that produced a complete final has answered. */
88
+ export function replayableFailure(attempt: ReplayAttempt): ReplayFailure | undefined {
89
+ if (attempt.ok || attempt.aborted || attempt.final?.state === "complete") return undefined;
90
+ if (attempt.timedOut) return "timed out";
91
+ if (attempt.spawnFailed)
92
+ return TRANSIENT_SPAWN.test(attempt.spawnError ?? "") ? "spawn failed transiently" : undefined;
93
+ if (attempt.exitCode !== 0) return "process exited without a final";
94
+ return attempt.final?.providerError ? "provider request failed" : undefined;
95
+ }
96
+
97
+ /** Everything the decision reads. Each field is one guard; `replayRetryDecision` names the one that refused. */
98
+ export interface ReplayRetryFacts {
99
+ /** `replayRetrySwitch(...).enabled`. */
100
+ enabled: boolean;
101
+ /** The first attempt's effective capabilities, as planned. */
102
+ capabilities: readonly Capability[];
103
+ attempt: ReplayAttempt;
104
+ /**
105
+ * A stable operation claimed one execution identity; its admission record cannot name a second. Checked last:
106
+ * an otherwise eligible failure is then marked replayable for the operation's owner, never retried here.
107
+ */
108
+ operation: boolean;
109
+ /** A Herdr pane is operable by a human, so a stop there cannot be told from a person's. */
110
+ executor: "process" | "herdr";
111
+ /** The parent tool call's own abort signal. */
112
+ parentAborted: boolean;
113
+ /** An upstream controller's veto is an answer, not a fault. */
114
+ criticalAssuranceBlock: boolean;
115
+ /** A gate answered for the first attempt: prompt, store, Auto or a chain's upfront dialog. */
116
+ approvalSpent: boolean;
117
+ /** Time left before the first attempt's wall-clock deadline, and the configured inactivity bound. */
118
+ remainingMs: number;
119
+ idleMs: number;
120
+ }
121
+
122
+ export type ReplayRetryRefusal =
123
+ | "disabled"
124
+ | "not-replay-safe"
125
+ | "stable-operation"
126
+ | "executor"
127
+ | "cancelled"
128
+ | "refused"
129
+ | "assurance-block"
130
+ | "not-transient"
131
+ | "cleanup-unsettled"
132
+ | "approval-spent"
133
+ | "deadline";
134
+
135
+ /**
136
+ * Retry once, or name the first guard that refuses. All must hold: the plan is replay-safe; the attempt failed
137
+ * without answering (`replayableFailure`); neither the parent's cancellation nor a refusal before launch caused it
138
+ * (a process killed from outside looks like a crash and is retried); the first attempt's cleanup
139
+ * settled (or no worker started) and its observation is complete; no approval was spent on it; and at least one
140
+ * inactivity bound remains before its wall-clock deadline, which the retry inherits.
141
+ *
142
+ * The stable-operation guard is checked last, so its refusal means every other guard held. Daddy does not retry
143
+ * under an operation; it reports the failure as `replayable` and the caller that owns the operation retries it
144
+ * under a new one (owner decision of 2026-11-17, "Principal retries once").
145
+ */
146
+ export function replayRetryDecision(
147
+ facts: ReplayRetryFacts,
148
+ ):
149
+ | { retry: true; cause: ReplayFailure }
150
+ | { retry: false; because: "stable-operation"; replayable: ReplayFailure }
151
+ | { retry: false; because: Exclude<ReplayRetryRefusal, "stable-operation"> } {
152
+ const refuse = (because: Exclude<ReplayRetryRefusal, "stable-operation">) => ({ retry: false as const, because });
153
+ if (!facts.enabled) return refuse("disabled");
154
+ if (!replaySafe(facts.capabilities)) return refuse("not-replay-safe");
155
+ if (facts.executor !== "process") return refuse("executor");
156
+ if (facts.parentAborted || facts.attempt.aborted) return refuse("cancelled");
157
+ if (facts.attempt.work === undefined) return refuse("refused");
158
+ if (facts.criticalAssuranceBlock) return refuse("assurance-block");
159
+ const cause = replayableFailure(facts.attempt);
160
+ if (!cause) return refuse("not-transient");
161
+ const { cleanup, control, observation } = facts.attempt;
162
+ if (
163
+ !(cleanup?.state === "settled" || cleanup?.state === "not-started") ||
164
+ control === "failed" ||
165
+ observation?.state !== "complete"
166
+ )
167
+ return refuse("cleanup-unsettled");
168
+ if (facts.approvalSpent) return refuse("approval-spent");
169
+ if (!(facts.remainingMs >= facts.idleMs)) return refuse("deadline");
170
+ if (facts.operation) return { retry: false, because: "stable-operation", replayable: cause };
171
+ return { retry: true, cause };
172
+ }
173
+
174
+ /**
175
+ * What the operator is told beside the replay-safe mark (startup summary, `/grants`): exactly when this session
176
+ * does not retry. Every case the decision refuses for the whole session is named; per-attempt guards are not.
177
+ */
178
+ export function replayRetryNotice(enabled: boolean, executor: "process" | "herdr"): string {
179
+ if (!enabled) return `not retried or marked replayable: switched off by ${ENV_REPLAY_RETRY}`;
180
+ if (executor !== "process") return "not retried or marked replayable under the Herdr executor";
181
+ return "retried once automatically if it fails without answering; with operation_id, marked replayable for the coordinator to retry instead";
182
+ }
@@ -318,6 +318,7 @@ export async function dashboardFrame(options: DashboardFrameOptions): Promise<st
318
318
  history: options.history,
319
319
  modelRows: options.session?.rows,
320
320
  episodeCost: options.session ? { cost: options.session.cost } : undefined,
321
+ childUsage: options.session?.childUsage,
321
322
  });
322
323
  return waiting ? `${rendered}\n\nwaiting for ledger ${ledgerPath}` : rendered;
323
324
  }
@@ -10,6 +10,7 @@ export interface DashboardRenderOptions {
10
10
  completedChildren?: number;
11
11
  modelRows?: Array<{ definition: string; model: string; thinking: string; source: string }>;
12
12
  episodeCost?: { cost: number | null };
13
+ childUsage?: { results: number; recorded: number; cost: number };
13
14
  }
14
15
 
15
16
  const ACTIVE = new Set<DashboardState>(["authorised", "starting", "running"]);
@@ -201,6 +202,28 @@ function renderTree(
201
202
  return lines;
202
203
  }
203
204
 
205
+ /**
206
+ * Child usage the owning Pi session already counts (2026-11-17): a label, never added to any figure here. The
207
+ * numbers come from that session's own record of its delegation results, so a host that did not keep the reported
208
+ * usage is named instead of being claimed as included.
209
+ */
210
+ function childUsageLine(value: DashboardRenderOptions["childUsage"]): string | undefined {
211
+ if (!value) return undefined;
212
+ const { results, recorded, cost } = value;
213
+ const whole = (n: unknown) => Number.isSafeInteger(n) && (n as number) >= 0;
214
+ if (!whole(results) || !whole(recorded) || recorded > results || results === 0) return undefined;
215
+ if (typeof cost !== "number" || !Number.isFinite(cost) || cost < 0) return undefined;
216
+ const from = (n: number) => `${n} delegation result${n === 1 ? "" : "s"}`;
217
+ if (recorded === 0)
218
+ return `child usage not in this Pi session's totals: this Pi did not record it (${from(results)})`;
219
+ const dollars = cost.toFixed(6).replace(/\.?0+$/, "") || "0";
220
+ const rest = results - recorded;
221
+ return (
222
+ `child usage already in this Pi session's totals: $${dollars} from ` +
223
+ (rest ? `${recorded} of ${from(results)}; ${rest} not recorded by this Pi` : from(results))
224
+ );
225
+ }
226
+
204
227
  export function renderDashboard(projection: DashboardProjection, options: DashboardRenderOptions = {}): string {
205
228
  const resolved = {
206
229
  width: Math.max(10, options.width ?? 80),
@@ -222,6 +245,8 @@ export function renderDashboard(projection: DashboardProjection, options: Dashbo
222
245
  ? "episode cost unavailable (usage coverage partial)"
223
246
  : `reported episode cost $${options.episodeCost.cost} (coverage partial)`,
224
247
  );
248
+ const childUsage = childUsageLine(options.childUsage);
249
+ if (childUsage) lines.push(childUsage);
225
250
  lines.push("");
226
251
  }
227
252
 
@@ -12,6 +12,8 @@ import { createConnection } from "node:net";
12
12
  export interface DashboardSessionSnapshot {
13
13
  rows: Array<{ definition: string; model: string; thinking: string; source: string }>;
14
14
  cost: number | null;
15
+ /** Delegation results in the owning Pi session that reported child usage, and those its host recorded. */
16
+ childUsage?: { results: number; recorded: number; cost: number };
15
17
  choiceControls?: { sourceGeneration: string };
16
18
  observation?: DashboardOwnerObservation;
17
19
  activity?: { rootId: string; path: string; taskId: string };
@@ -49,6 +49,8 @@ export interface EpisodeReportGroup extends CostEvidence {
49
49
  }
50
50
  export interface EpisodeReport {
51
51
  costScope: "recorded-child-executions";
52
+ /** Child usage reported by a delegation result is already in the delegating Pi session's totals (2026-11-17). */
53
+ parentSessionTotals: "include-reported-child-usage";
52
54
  rows: EpisodeReportRow[];
53
55
  groups?: EpisodeReportGroup[];
54
56
  groupBy?: EpisodeGroupBy;
@@ -274,6 +276,7 @@ export function reportEpisodes(input: {
274
276
  }
275
277
  return {
276
278
  costScope: "recorded-child-executions",
279
+ parentSessionTotals: "include-reported-child-usage",
277
280
  rows: [],
278
281
  groups: [...groups.values()].sort((a, b) => a.value.localeCompare(b.value)),
279
282
  groupBy: input.options.groupBy,
@@ -283,6 +286,7 @@ export function reportEpisodes(input: {
283
286
  const costs = rows.flatMap((row) => (row.cost === null ? [] : [row.cost]));
284
287
  return {
285
288
  costScope: "recorded-child-executions",
289
+ parentSessionTotals: "include-reported-child-usage",
286
290
  rows,
287
291
  totals: {
288
292
  episodes: rows.length,
@@ -308,7 +312,10 @@ function summarizeCosts(values: readonly CostEvidence[]): CostEvidence {
308
312
  : "unavailable",
309
313
  };
310
314
  }
311
- const costScope = "Cost coverage refers only to recorded child executions; root and unrecorded work are not measured.";
315
+ const costScope =
316
+ "Cost coverage refers only to recorded child executions; root and unrecorded work are not measured. " +
317
+ "Each child's usage is its own model calls. Where its delegation result reported that usage and the host " +
318
+ "recorded it, the delegating Pi session's usage and cost already include it: compare with them, do not add.";
312
319
  const escapeCell = (value: unknown): string => String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
313
320
  const cost = (value: number | null): string =>
314
321
  value === null ? "unavailable" : value.toFixed(6).replace(/\.?0+$/, "") || "0";