pi-daddy 0.58.0 → 0.59.1

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 (35) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +5 -3
  3. package/dist/governance/operation-artifacts.d.ts +2 -0
  4. package/dist/governance/operation-artifacts.d.ts.map +1 -1
  5. package/dist/governance/operation-artifacts.js +48 -44
  6. package/dist/governance/operation-artifacts.js.map +1 -1
  7. package/dist/governance/operation-recovery.d.ts +18 -0
  8. package/dist/governance/operation-recovery.d.ts.map +1 -0
  9. package/dist/governance/operation-recovery.js +47 -0
  10. package/dist/governance/operation-recovery.js.map +1 -0
  11. package/dist/products/dashboard-activity.d.ts +2 -0
  12. package/dist/products/dashboard-activity.d.ts.map +1 -1
  13. package/dist/products/dashboard-activity.js +7 -1
  14. package/dist/products/dashboard-activity.js.map +1 -1
  15. package/dist/products/dashboard-panels.d.ts.map +1 -1
  16. package/dist/products/dashboard-panels.js +7 -2
  17. package/dist/products/dashboard-panels.js.map +1 -1
  18. package/dist/products/dashboard-screen.d.ts.map +1 -1
  19. package/dist/products/dashboard-screen.js +5 -3
  20. package/dist/products/dashboard-screen.js.map +1 -1
  21. package/extensions/dashboard-live.ts +1 -1
  22. package/extensions/definition-describe.ts +50 -4
  23. package/extensions/delegate-chain.ts +8 -6
  24. package/extensions/delegation.ts +14 -8
  25. package/extensions/grants.ts +7 -4
  26. package/extensions/operation-recovery-bridge.ts +100 -0
  27. package/extensions/runtime-snapshot.ts +9 -0
  28. package/extensions/session-report.ts +9 -1
  29. package/extensions/spawn-summary.ts +41 -3
  30. package/package.json +1 -1
  31. package/src/governance/operation-artifacts.ts +51 -41
  32. package/src/governance/operation-recovery.ts +68 -0
  33. package/src/products/dashboard-activity.ts +8 -1
  34. package/src/products/dashboard-panels.ts +7 -2
  35. package/src/products/dashboard-screen.ts +5 -3
@@ -20,18 +20,21 @@
20
20
  * grant it classifies against is the one *inherited*; `deriveOwnGrant` narrows it to the observed tool
21
21
  * surface only when a request is made, and a definition counted spawnable here can be refused afterwards if
22
22
  * its ceiling names a tool this session turns out not to have (R-75, measured live). It is an upper bound,
23
- * and `/grants` run after any request is the settled answer.
23
+ * and a first-request refresh reports the settled answer. Unknown extension tools are presented as still
24
+ * being checked until that native observation arrives; this never changes what dispatch permits.
24
25
  */
25
26
 
26
27
  import type { SkillDefinition } from "../src/kernel/definitions.ts";
27
28
  import type { GatedPlan } from "./run-delegation.ts";
28
29
 
29
- /** Why a definition is not spawnable right now. Three causes, three different fixes. */
30
+ /** Why a definition is not spawnable right now; display never changes the planner's refusal. */
30
31
  export type WithheldReason =
31
32
  /** The grant lacks `agent:<name>`, or lacks a tool the ceiling declares. Fix: widen `PI_DADDY_GRANT`. */
32
33
  | "capability"
33
34
  /** Everything is held, but a gated capability needs a human yes first. Fix: spawn it and answer. */
34
35
  | "approval"
36
+ /** A parent's registered tool has no qualified child provider. More permission does not fix it. */
37
+ | "child-provider"
35
38
  /** Anything else the planner refused — the file, an unknown capability, an unresolvable skill. */
36
39
  | "declaration";
37
40
 
@@ -47,6 +50,8 @@ export interface WithheldDefinition {
47
50
  export interface SpawnableSummary {
48
51
  spawnable: string[];
49
52
  withheld: WithheldDefinition[];
53
+ /** Extension capabilities have not been observed yet; this is not an installation failure. */
54
+ awaitingTools?: string[];
50
55
  /**
51
56
  * Set when NOTHING can be spawned for a reason about the SESSION rather than about any definition — no
52
57
  * `tool:delegate`, or a depth bound that forbids spawning. Per-definition work is skipped entirely.
@@ -77,6 +82,8 @@ export interface SessionFacts {
77
82
  mayDelegate: boolean;
78
83
  depth: number;
79
84
  maxDepth: number;
85
+ /** Omitted by callers with an already-settled planner; false only before native tool observation. */
86
+ toolsObserved?: boolean;
80
87
  }
81
88
 
82
89
  /**
@@ -129,6 +136,7 @@ export async function summariseSpawnable(
129
136
 
130
137
  const spawnable: string[] = [];
131
138
  const withheld: WithheldDefinition[] = [];
139
+ const awaitingTools: string[] = [];
132
140
 
133
141
  for (const name of names.slice(0, PREVIEW_LIMIT)) {
134
142
  const { plan } = await preview(name);
@@ -136,6 +144,19 @@ export async function summariseSpawnable(
136
144
  spawnable.push(name);
137
145
  continue;
138
146
  }
147
+ // The initial catalog contains built-ins before Pi exposes its callable extension tools. Preserve
148
+ // the refusal for dispatch, but do not tell the human that an unobserved package is uninstalled.
149
+ // Only the catalog's own unknown-tool diagnosis is provisional; other refusals stay explicit.
150
+ if (
151
+ session.toolsObserved === false &&
152
+ plan.refusal?.code === "UNKNOWN_TOOL" &&
153
+ /^unknown capabilit(?:y|ies): (?:tool|ext):[^\s,]+(?:, (?:tool|ext):[^\s,]+)* — not present in this session's catalog/.test(
154
+ plan.reason ?? "",
155
+ )
156
+ ) {
157
+ awaitingTools.push(name);
158
+ continue;
159
+ }
139
160
  // Read off the plan's own result, in the order `planDelegation` decides them: an escalation is reported
140
161
  // before a gate, because a capability the session does not hold cannot be approved into existence.
141
162
  // `denied` carries the ADR-0017 authorisation refusal too — asking to run a definition this session was
@@ -144,13 +165,25 @@ export async function summariseSpawnable(
144
165
  const gated = plan.result.gatedBlocked;
145
166
  if (denied.length > 0) withheld.push({ name, reason: "capability", missing: [...denied].sort() });
146
167
  else if (gated.length > 0) withheld.push({ name, reason: "approval", missing: [...gated].sort() });
168
+ else if (plan.refusal?.details?.kind === "child-tool-unavailable")
169
+ withheld.push({
170
+ name,
171
+ reason: "child-provider",
172
+ missing: String(plan.refusal.details.tools).split(","),
173
+ reasonText: plan.reason,
174
+ });
147
175
  // Everything else: say what the ENFORCER said. Inventing a category here is what told an operator with
148
176
  // an unknown capability, an unresolvable `skill:`, or a universal capability that their file was
149
177
  // written wrong, in wording that contradicted `/grants` on the same screen.
150
178
  else withheld.push({ name, reason: "declaration", missing: [], reasonText: plan.reason });
151
179
  }
152
180
 
153
- return { spawnable, withheld, notChecked: Math.max(0, names.length - PREVIEW_LIMIT) };
181
+ return {
182
+ spawnable,
183
+ withheld,
184
+ ...(awaitingTools.length ? { awaitingTools } : {}),
185
+ notChecked: Math.max(0, names.length - PREVIEW_LIMIT),
186
+ };
154
187
  }
155
188
 
156
189
  /** `a, b, c` — or the first few and a count, so a large skill root does not become the whole line. */
@@ -198,6 +231,8 @@ export function renderSpawnableSummary(summary: SpawnableSummary, total: number)
198
231
  // ADR-0024: a gated `agent:` id is the PARENT's authority to run the definition now, and is deliberately
199
232
  // kept out of what the child receives. "before a child receives it" was wrong for exactly that case.
200
233
  if (w.reason === "approval") return `${name} (needs your approval for ${list(w.missing)})`;
234
+ if (w.reason === "child-provider")
235
+ return `${name} (use the parent Pi session; child tools unavailable: ${list(w.missing.map(safeName))})`;
201
236
  return `${name} (${w.reasonText ?? "cannot be spawned as its file is written"})`;
202
237
  };
203
238
 
@@ -206,6 +241,9 @@ export function renderSpawnableSummary(summary: SpawnableSummary, total: number)
206
241
  const extra = summary.withheld.length - shown.length;
207
242
  lines.push(` withheld: ${shown.join("; ")}${extra > 0 ? `; … and ${extra} more` : ""}`);
208
243
  }
244
+ if (summary.awaitingTools?.length) {
245
+ lines.push(` checking available tools: ${list(summary.awaitingTools.map(safeName))} — updates when work starts`);
246
+ }
209
247
  if (summary.notChecked > 0) {
210
248
  lines.push(` ${summary.notChecked} more not checked (first ${PREVIEW_LIMIT} only) — /grants lists them`);
211
249
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-daddy",
3
- "version": "0.58.0",
3
+ "version": "0.59.1",
4
4
  "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -216,53 +216,63 @@ export interface OperationArtifactHistory {
216
216
  final?: RetainedOperationFinal;
217
217
  partial?: { text: string; sha256: string };
218
218
  }
219
- export function openOperationArtifacts(agentDirectory: string, owner: OperationArtifactOwner) {
219
+ /** Exact read without creating directories, adopting an owner, or publishing an admission. */
220
+ export function readOperationHistory(
221
+ agentDirectory: string,
222
+ owner: OperationArtifactOwner,
223
+ operationId: string,
224
+ includeFinal = true,
225
+ ): OperationArtifactHistory | null {
220
226
  ownerCheck(owner);
221
227
  const directory = realpathSync(agentDirectory);
222
- privateArtifactDirectory(operationArtifactsDir(directory), true);
223
- const history = (operationId: string, includeFinal = true): OperationArtifactHistory | null => {
224
- const path = location(directory, owner, operationId);
225
- const admission = admissionAt(path, owner, operationId);
226
- if (!admission) return null;
227
- let text: string;
228
- try {
229
- text = readBoundedTextSync(join(path, "result.json"), {
230
- maxBytes: MAX_OPERATION_MANIFEST_BYTES,
231
- confinedRoot: path,
232
- }).text;
233
- } catch (error) {
234
- if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
235
- const scope = resolvedScope(path, admission) ?? admission.request;
236
- const operation: OperationReference = {
237
- operationId,
238
- executionId: admission.request.executionId,
239
- cwd: scope.cwd,
240
- workspaceId: scope.workspaceId,
241
- state: "uncertain",
242
- startedAt: admission.admittedAt,
243
- updatedAt: admission.admittedAt,
244
- };
245
- return {
246
- operation,
247
- requestDigest: admission.request.requestDigest,
248
- reason: "admission retained without a published result; no retry or no-start proof",
249
- };
250
- }
251
- const manifest = manifestCheck(JSON.parse(text), admission, path);
252
- const artifact = refFor(manifest, {
253
- path: join(path, "result.json"),
254
- sha256: artifactHash(text),
255
- bytes: Buffer.byteLength(text),
256
- });
257
- const content = includeFinal ? readOperationArtifact(artifact, { agentDirectory: directory }) : undefined;
228
+ const path = location(directory, owner, operationId);
229
+ const admission = admissionAt(path, owner, operationId);
230
+ if (!admission) return null;
231
+ let text: string;
232
+ try {
233
+ text = readBoundedTextSync(join(path, "result.json"), {
234
+ maxBytes: MAX_OPERATION_MANIFEST_BYTES,
235
+ confinedRoot: path,
236
+ }).text;
237
+ } catch (error) {
238
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
239
+ const scope = resolvedScope(path, admission) ?? admission.request;
240
+ const operation: OperationReference = {
241
+ operationId,
242
+ executionId: admission.request.executionId,
243
+ cwd: scope.cwd,
244
+ workspaceId: scope.workspaceId,
245
+ state: "uncertain",
246
+ startedAt: admission.admittedAt,
247
+ updatedAt: admission.admittedAt,
248
+ };
258
249
  return {
259
- operation: { ...manifest.operation, artifact },
260
- artifact,
250
+ operation,
261
251
  requestDigest: admission.request.requestDigest,
262
- ...(content?.final ? { final: content.final } : {}),
263
- ...(content?.partial ? { partial: content.partial } : {}),
252
+ reason: "admission retained without a published result; no retry or no-start proof",
264
253
  };
254
+ }
255
+ const manifest = manifestCheck(JSON.parse(text), admission, path);
256
+ const artifact = refFor(manifest, {
257
+ path: join(path, "result.json"),
258
+ sha256: artifactHash(text),
259
+ bytes: Buffer.byteLength(text),
260
+ });
261
+ const content = includeFinal ? readOperationArtifact(artifact, { agentDirectory: directory }) : undefined;
262
+ return {
263
+ operation: { ...manifest.operation, artifact },
264
+ artifact,
265
+ requestDigest: admission.request.requestDigest,
266
+ ...(content?.final ? { final: content.final } : {}),
267
+ ...(content?.partial ? { partial: content.partial } : {}),
265
268
  };
269
+ }
270
+ export function openOperationArtifacts(agentDirectory: string, owner: OperationArtifactOwner) {
271
+ ownerCheck(owner);
272
+ const directory = realpathSync(agentDirectory);
273
+ privateArtifactDirectory(operationArtifactsDir(directory), true);
274
+ const history = (operationId: string, includeFinal = true) =>
275
+ readOperationHistory(directory, owner, operationId, includeFinal);
266
276
  return {
267
277
  owner: Object.freeze({ ...owner }),
268
278
  history,
@@ -0,0 +1,68 @@
1
+ /** Historical producer facts only. No owner adoption, admission, retry or execution authority. */
2
+ import type { OperationArtifactOwner } from "../kernel/operation-artifact.ts";
3
+ import { readOperationHistory, type OperationArtifactHistory } from "./operation-artifacts.ts";
4
+ import { readRuntimeExecutionSettlement } from "./runtime-settlement.ts";
5
+
6
+ export interface OperationRecoverySource {
7
+ owner: OperationArtifactOwner;
8
+ operationId: string;
9
+ }
10
+ export interface OperationRecoveryObservation extends Partial<OperationArtifactHistory> {
11
+ admission: "present" | "absent";
12
+ result: "present" | "absent";
13
+ cleanup: { state: "settled" | "not-started" | "unknown" };
14
+ /** Positive immutable terminal evidence for this exact attempt, never permission for another attempt. */
15
+ noStartProven: boolean;
16
+ }
17
+ export async function readOperationRecovery(
18
+ agentDirectory: string,
19
+ source: OperationRecoverySource,
20
+ ): Promise<OperationRecoveryObservation> {
21
+ const retained = readOperationHistory(agentDirectory, source.owner, source.operationId);
22
+ if (!retained)
23
+ return {
24
+ admission: "absent",
25
+ result: "absent",
26
+ cleanup: { state: "unknown" },
27
+ noStartProven: false,
28
+ reason: "No retained admission for this exact owner and operation; absence is not no-start proof.",
29
+ };
30
+ const before = JSON.stringify(retained);
31
+ const { operation, artifact, final, partial } = retained;
32
+ const runtime = operation.runtime;
33
+ const terminalNoStart =
34
+ !!artifact &&
35
+ operation.state === "not-started" &&
36
+ runtime?.cleanup?.state === "not-started" &&
37
+ (runtime.cleanup.executionId === undefined || runtime.cleanup.executionId === operation.executionId) &&
38
+ runtime.cleanup.receiptPath === undefined &&
39
+ (runtime.work === undefined || runtime.work === "unknown") &&
40
+ runtime.final === undefined &&
41
+ !final &&
42
+ !partial;
43
+ let settlement: "settled" | "not-started" | "unknown" = "unknown";
44
+ try {
45
+ settlement = await readRuntimeExecutionSettlement(
46
+ agentDirectory,
47
+ source.owner.sessionId,
48
+ source.owner.cwd,
49
+ operation.executionId,
50
+ );
51
+ } catch {
52
+ // A missing or invalid journal cannot strengthen the immutable result or prove no execution.
53
+ }
54
+ if (JSON.stringify(readOperationHistory(agentDirectory, source.owner, source.operationId)) !== before)
55
+ throw Error("operation recovery evidence changed during read");
56
+ const contradictory = operation.state === "not-started" && (!terminalNoStart || settlement === "settled");
57
+ const noStartProven = terminalNoStart && !contradictory;
58
+ return {
59
+ ...retained,
60
+ admission: "present",
61
+ result: artifact ? "present" : "absent",
62
+ cleanup: { state: contradictory ? "unknown" : noStartProven ? "not-started" : settlement },
63
+ noStartProven,
64
+ ...(contradictory
65
+ ? { reason: "The retained no-start record contains conflicting or incomplete execution evidence." }
66
+ : {}),
67
+ };
68
+ }
@@ -10,6 +10,8 @@ const clean = (value: string) =>
10
10
  .trim();
11
11
 
12
12
  export function activityTaskTitle(task: TimelineTask): string {
13
+ if (activityTaskStatus(task) === "turn-ended")
14
+ return task.trigger?.type === "custom" ? "Extension turn ended" : "Pi turn ended";
13
15
  const lastAction = task.lastEvent?.kind === "tool_started" || task.status !== "active";
14
16
  const observed = lastAction
15
17
  ? (safeDashboardSummary(task.lastPurpose) ?? (task.lastEvent?.tool ? toolPurpose(task.lastEvent.tool) : undefined))
@@ -22,6 +24,11 @@ export function activityTaskTitle(task: TimelineTask): string {
22
24
  return task.status === "active" ? "Pi is working on your request" : "Pi handled your request";
23
25
  }
24
26
 
27
+ /** A settled parent response says nothing about delivery; child execution outcomes remain distinct. */
28
+ export function activityTaskStatus(task: TimelineTask): string {
29
+ return !task.agent && !task.parentTaskId && task.status === "finished" ? "turn-ended" : task.status;
30
+ }
31
+
25
32
  /** Ledger entries retain authoritative state and identity. Only the same owner's matching execution may add a title. */
26
33
  export function applyOwnerTaskTitles(items: DashboardItem[], tasks: TimelineTask[], rootId: string): DashboardItem[] {
27
34
  const known = new Map(tasks.filter((task) => task.rootId === rootId && task.agent).map((task) => [task.id, task]));
@@ -55,7 +62,7 @@ export function activityStoryItems(
55
62
  if (raw === "agent_start" || raw === "agent_end") starts.clear();
56
63
  stories.push({
57
64
  events: [event],
58
- label: raw === "agent_start" ? "Pi started a turn" : raw === "agent_end" ? "Pi finished its turn" : raw,
65
+ label: raw === "agent_start" ? "Pi started a turn" : raw === "agent_end" ? "Pi turn ended" : raw,
59
66
  status: "observed",
60
67
  calls: 1,
61
68
  });
@@ -312,7 +312,12 @@ export function sessionDashboardItems(options: DashboardScreenOptions): Dashboar
312
312
  ...input,
313
313
  ...components.filter(needsUserInput),
314
314
  ...(ownerTurn && !parentShown
315
- ? [row(ownerTurn, `owner:${observed.generation}:${ownerTurn.id}`, "Pi owner", staleOwner)]
315
+ ? [
316
+ {
317
+ ...row(ownerTurn, `owner:${observed.generation}:${ownerTurn.id}`, "Pi owner", staleOwner),
318
+ ...(ownerTurn.state === "settled" && !staleOwner ? { label: "Pi turn ended", status: "turn-ended" } : {}),
319
+ },
320
+ ]
316
321
  : []),
317
322
  ...tasks,
318
323
  ...bookieOpenChoices(options),
@@ -386,7 +391,7 @@ function workGroup(item: DashboardItem): string {
386
391
  if (item.status === "dependency-wait") return "Waiting on a dependency";
387
392
  if (item.status === "incomplete") return "Outcome unknown";
388
393
  if (["running", "active", "starting", "authorised", "cancel-requested"].includes(item.status)) return "In progress";
389
- if (["settled", "completed", "finished", "cancelled", "failed", "refused"].includes(item.status))
394
+ if (["turn-ended", "settled", "completed", "finished", "cancelled", "failed", "refused"].includes(item.status))
390
395
  return "Recently finished";
391
396
  return "Other tasks";
392
397
  }
@@ -9,7 +9,7 @@ import {
9
9
  DASHBOARD_DESTINATIONS,
10
10
  type DashboardDestination,
11
11
  } from "./dashboard-panels.ts";
12
- import { activityTaskTitle } from "./dashboard-activity.ts";
12
+ import { activityTaskStatus, activityTaskTitle } from "./dashboard-activity.ts";
13
13
  import { versionLines } from "./dashboard-components.ts";
14
14
  import { sessionRecapLines } from "./dashboard-recap.ts";
15
15
  import { colorSessionLine, previewWidth, sectionHeading } from "./dashboard-layout.ts";
@@ -114,6 +114,7 @@ export const friendlyStatus = (status: string) =>
114
114
  "approval-wait": "Awaiting decision",
115
115
  "dependency-wait": "Waiting on dependency",
116
116
  "last-observed": "Last seen",
117
+ "turn-ended": "Ended",
117
118
  settled: "Finished",
118
119
  completed: "Finished",
119
120
  finished: "Finished",
@@ -166,7 +167,7 @@ export function activityDashboardItems(
166
167
  label: human
167
168
  ? activityTaskTitle(task)
168
169
  : `${task.agent || (task.trigger?.type === "custom" ? "Extension turn" : "User turn")} [${aliases.selector(task)}]`,
169
- status: task.status,
170
+ status: activityTaskStatus(task),
170
171
  updatedAt: task.endedAt ?? task.lastEvent?.at ?? task.startedAt,
171
172
  elapsed: elapsed(Date.parse(task.endedAt ?? now.toISOString()) - Date.parse(task.startedAt)),
172
173
  observation: task.lastEvent
@@ -176,7 +177,8 @@ export function activityDashboardItems(
176
177
  skills: task.skills.length > 0,
177
178
  details: [
178
179
  `Task: ${aliases.selector(task)}`,
179
- `State: ${friendlyStatus(task.status)} (observation, not acceptance)`,
180
+ `State: ${friendlyStatus(activityTaskStatus(task))} (observation, not acceptance)`,
181
+ ...(task.lastPurpose ? [`Last action: ${clean(task.lastPurpose)}`] : []),
180
182
  ...(task.trigger?.type === "custom" ? [`Trigger: extension message (${task.trigger.customType})`] : []),
181
183
  ...(task.cwd ? [`Working directory: ${task.cwd}`] : ["Working directory: not recorded"]),
182
184
  ...(task.lastEvent