pi-daddy 0.49.5 → 0.50.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 (149) hide show
  1. package/CHANGELOG.md +51 -1
  2. package/README.md +217 -27
  3. package/dist/governance/initiative-coordinator.d.ts +58 -0
  4. package/dist/governance/initiative-coordinator.d.ts.map +1 -0
  5. package/dist/governance/initiative-coordinator.js +348 -0
  6. package/dist/governance/initiative-coordinator.js.map +1 -0
  7. package/dist/governance/initiative-effects.d.ts +20 -0
  8. package/dist/governance/initiative-effects.d.ts.map +1 -0
  9. package/dist/governance/initiative-effects.js +108 -0
  10. package/dist/governance/initiative-effects.js.map +1 -0
  11. package/dist/governance/initiative-state.d.ts +13 -0
  12. package/dist/governance/initiative-state.d.ts.map +1 -0
  13. package/dist/governance/initiative-state.js +122 -0
  14. package/dist/governance/initiative-state.js.map +1 -0
  15. package/dist/governance/operation-artifact-io.d.ts +8 -0
  16. package/dist/governance/operation-artifact-io.d.ts.map +1 -0
  17. package/dist/governance/operation-artifact-io.js +95 -0
  18. package/dist/governance/operation-artifact-io.js.map +1 -0
  19. package/dist/governance/operation-artifact-scan.d.ts +13 -0
  20. package/dist/governance/operation-artifact-scan.d.ts.map +1 -0
  21. package/dist/governance/operation-artifact-scan.js +71 -0
  22. package/dist/governance/operation-artifact-scan.js.map +1 -0
  23. package/dist/governance/operation-artifacts.d.ts +53 -0
  24. package/dist/governance/operation-artifacts.d.ts.map +1 -0
  25. package/dist/governance/operation-artifacts.js +309 -0
  26. package/dist/governance/operation-artifacts.js.map +1 -0
  27. package/dist/governance/runtime-settlement.d.ts +2 -0
  28. package/dist/governance/runtime-settlement.d.ts.map +1 -1
  29. package/dist/governance/runtime-settlement.js +26 -0
  30. package/dist/governance/runtime-settlement.js.map +1 -1
  31. package/dist/governance/workspace-acceptance.d.ts +5 -0
  32. package/dist/governance/workspace-acceptance.d.ts.map +1 -1
  33. package/dist/governance/workspace-acceptance.js +16 -0
  34. package/dist/governance/workspace-acceptance.js.map +1 -1
  35. package/dist/index.d.ts +8 -0
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +8 -0
  38. package/dist/index.js.map +1 -1
  39. package/dist/kernel/dashboard-observation.d.ts +76 -0
  40. package/dist/kernel/dashboard-observation.d.ts.map +1 -0
  41. package/dist/kernel/dashboard-observation.js +49 -0
  42. package/dist/kernel/dashboard-observation.js.map +1 -0
  43. package/dist/kernel/dispatch-operation.d.ts +2 -0
  44. package/dist/kernel/dispatch-operation.d.ts.map +1 -1
  45. package/dist/kernel/dispatch-operation.js.map +1 -1
  46. package/dist/kernel/initiative.d.ts +94 -0
  47. package/dist/kernel/initiative.d.ts.map +1 -0
  48. package/dist/kernel/initiative.js +38 -0
  49. package/dist/kernel/initiative.js.map +1 -0
  50. package/dist/kernel/operation-artifact.d.ts +49 -0
  51. package/dist/kernel/operation-artifact.d.ts.map +1 -0
  52. package/dist/kernel/operation-artifact.js +4 -0
  53. package/dist/kernel/operation-artifact.js.map +1 -0
  54. package/dist/kernel/principal-binding.d.ts +4 -0
  55. package/dist/kernel/principal-binding.d.ts.map +1 -0
  56. package/dist/kernel/principal-binding.js +94 -0
  57. package/dist/kernel/principal-binding.js.map +1 -0
  58. package/dist/kernel/project-paths.d.ts +6 -0
  59. package/dist/kernel/project-paths.d.ts.map +1 -1
  60. package/dist/kernel/project-paths.js +12 -0
  61. package/dist/kernel/project-paths.js.map +1 -1
  62. package/dist/kernel/selected-definitions.d.ts.map +1 -1
  63. package/dist/kernel/selected-definitions.js +5 -91
  64. package/dist/kernel/selected-definitions.js.map +1 -1
  65. package/dist/kernel/workspace-diagnostics.d.ts +24 -0
  66. package/dist/kernel/workspace-diagnostics.d.ts.map +1 -0
  67. package/dist/kernel/workspace-diagnostics.js +81 -0
  68. package/dist/kernel/workspace-diagnostics.js.map +1 -0
  69. package/dist/products/activity-storage.d.ts +2 -0
  70. package/dist/products/activity-storage.d.ts.map +1 -0
  71. package/dist/products/activity-storage.js +119 -0
  72. package/dist/products/activity-storage.js.map +1 -0
  73. package/dist/products/activity-timeline.d.ts +4 -0
  74. package/dist/products/activity-timeline.d.ts.map +1 -1
  75. package/dist/products/activity-timeline.js +12 -0
  76. package/dist/products/activity-timeline.js.map +1 -1
  77. package/dist/products/dashboard-cli.d.ts +2 -0
  78. package/dist/products/dashboard-cli.d.ts.map +1 -1
  79. package/dist/products/dashboard-cli.js +41 -9
  80. package/dist/products/dashboard-cli.js.map +1 -1
  81. package/dist/products/dashboard-display-controls.d.ts.map +1 -1
  82. package/dist/products/dashboard-display-controls.js +30 -0
  83. package/dist/products/dashboard-display-controls.js.map +1 -1
  84. package/dist/products/dashboard-file-cache.d.ts +10 -0
  85. package/dist/products/dashboard-file-cache.d.ts.map +1 -0
  86. package/dist/products/dashboard-file-cache.js +38 -0
  87. package/dist/products/dashboard-file-cache.js.map +1 -0
  88. package/dist/products/dashboard-panels.d.ts +6 -0
  89. package/dist/products/dashboard-panels.d.ts.map +1 -0
  90. package/dist/products/dashboard-panels.js +179 -0
  91. package/dist/products/dashboard-panels.js.map +1 -0
  92. package/dist/products/dashboard-screen.d.ts +8 -0
  93. package/dist/products/dashboard-screen.d.ts.map +1 -1
  94. package/dist/products/dashboard-screen.js +86 -15
  95. package/dist/products/dashboard-screen.js.map +1 -1
  96. package/dist/products/dashboard-session-client.d.ts +16 -2
  97. package/dist/products/dashboard-session-client.d.ts.map +1 -1
  98. package/dist/products/dashboard-session-client.js +64 -11
  99. package/dist/products/dashboard-session-client.js.map +1 -1
  100. package/dist/products/dashboard-settings.d.ts.map +1 -1
  101. package/dist/products/dashboard-settings.js +4 -6
  102. package/dist/products/dashboard-settings.js.map +1 -1
  103. package/dist/products/ecosystem-versions.d.ts +1 -1
  104. package/dist/products/ecosystem-versions.d.ts.map +1 -1
  105. package/extensions/activity-timeline.ts +3 -1
  106. package/extensions/artifact-bridge.ts +130 -0
  107. package/extensions/dashboard-live.ts +63 -0
  108. package/extensions/dashboard-observation.ts +39 -0
  109. package/extensions/dashboard-session-server.ts +45 -3
  110. package/extensions/dashboard-sources.ts +124 -0
  111. package/extensions/delegation-artifacts.ts +125 -0
  112. package/extensions/delegation-operations.ts +42 -13
  113. package/extensions/ecosystem-versions.ts +12 -5
  114. package/extensions/grants-command.ts +34 -6
  115. package/extensions/grants.ts +9 -20
  116. package/extensions/initiative-dashboard.ts +143 -0
  117. package/extensions/initiative-runtime.ts +406 -0
  118. package/extensions/runtime-snapshot.ts +118 -2
  119. package/extensions/session-environment.ts +13 -1
  120. package/extensions/session.ts +28 -10
  121. package/extensions/workspace-diagnostics.ts +90 -0
  122. package/package.json +1 -1
  123. package/src/governance/initiative-coordinator.ts +400 -0
  124. package/src/governance/initiative-effects.ts +146 -0
  125. package/src/governance/initiative-state.ts +144 -0
  126. package/src/governance/operation-artifact-io.ts +103 -0
  127. package/src/governance/operation-artifact-scan.ts +77 -0
  128. package/src/governance/operation-artifacts.ts +363 -0
  129. package/src/governance/runtime-settlement.ts +28 -0
  130. package/src/governance/workspace-acceptance.ts +18 -0
  131. package/src/index.ts +13 -0
  132. package/src/kernel/dashboard-observation.ts +109 -0
  133. package/src/kernel/dispatch-operation.ts +2 -0
  134. package/src/kernel/initiative.ts +126 -0
  135. package/src/kernel/operation-artifact.ts +46 -0
  136. package/src/kernel/principal-binding.ts +104 -0
  137. package/src/kernel/project-paths.ts +16 -0
  138. package/src/kernel/selected-definitions.ts +5 -100
  139. package/src/kernel/workspace-diagnostics.ts +110 -0
  140. package/src/products/activity-storage.ts +128 -0
  141. package/src/products/activity-timeline.ts +11 -0
  142. package/src/products/dashboard-cli.ts +44 -9
  143. package/src/products/dashboard-display-controls.ts +27 -0
  144. package/src/products/dashboard-file-cache.ts +38 -0
  145. package/src/products/dashboard-panels.ts +217 -0
  146. package/src/products/dashboard-screen.ts +107 -17
  147. package/src/products/dashboard-session-client.ts +78 -14
  148. package/src/products/dashboard-settings.ts +4 -6
  149. package/src/products/ecosystem-versions.ts +2 -1
@@ -0,0 +1,363 @@
1
+ /** Durable producer outcomes; opening/reading never starts governance, work, or Bookie registration. */
2
+ import { realpathSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { readBoundedTextSync } from "../kernel/bounded-read-sync.ts";
5
+ import { operationArtifactsDir } from "../kernel/project-paths.ts";
6
+ import { validOperationId, type OperationRequest, type OperationReference } from "../kernel/dispatch-operation.ts";
7
+ import {
8
+ MAX_OPERATION_ARTIFACT_BYTES,
9
+ MAX_OPERATION_MANIFEST_BYTES,
10
+ type OperationArtifactOwner,
11
+ type OperationArtifactRef,
12
+ type OperationArtifactManifest,
13
+ type OperationArtifactOutcome,
14
+ type RetainedOperationFinal,
15
+ } from "../kernel/operation-artifact.ts";
16
+ import {
17
+ artifactHash,
18
+ artifactJson,
19
+ privateArtifactDirectory,
20
+ publishArtifact,
21
+ readArtifactBytes,
22
+ } from "./operation-artifact-io.ts";
23
+ const object = (v: unknown): v is Record<string, any> => !!v && typeof v === "object" && !Array.isArray(v);
24
+ const bounded = (v: unknown, max = 4096): v is string => typeof v === "string" && v.length > 0 && v.length <= max;
25
+ const digest = (v: unknown): v is string => typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
26
+ function ownerCheck(owner: OperationArtifactOwner) {
27
+ if (!object(owner) || !bounded(owner.sessionId, 512) || !bounded(owner.cwd) || !owner.cwd.startsWith("/"))
28
+ throw Error("invalid operation artifact owner");
29
+ }
30
+ function requestCheck(request: OperationRequest) {
31
+ if (
32
+ !object(request) ||
33
+ !validOperationId(request.operationId) ||
34
+ !digest(request.requestDigest) ||
35
+ !bounded(request.executionId, 128) ||
36
+ !request.executionId.startsWith("exec:") ||
37
+ !bounded(request.cwd) ||
38
+ !request.cwd.startsWith("/") ||
39
+ !(request.workspaceId === null || bounded(request.workspaceId, 512))
40
+ )
41
+ throw Error("invalid operation artifact request");
42
+ }
43
+ const requestFields = ["operationId", "executionId", "requestDigest", "cwd", "workspaceId"] as const;
44
+ const sameRequest = (a: OperationRequest, b: OperationRequest) => requestFields.every((key) => a?.[key] === b?.[key]);
45
+ const cleanRequest = (request: OperationRequest): OperationRequest => ({
46
+ operationId: request.operationId,
47
+ executionId: request.executionId,
48
+ requestDigest: request.requestDigest,
49
+ cwd: request.cwd,
50
+ workspaceId: request.workspaceId,
51
+ });
52
+ interface ResolvedScope {
53
+ version: 1;
54
+ executionId: string;
55
+ cwd: string;
56
+ workspaceId: string | null;
57
+ }
58
+ function resolvedScope(path: string, admission: Admission): ResolvedScope | null {
59
+ try {
60
+ const scope = JSON.parse(
61
+ readBoundedTextSync(join(path, "scope.json"), {
62
+ maxBytes: MAX_OPERATION_MANIFEST_BYTES,
63
+ confinedRoot: path,
64
+ }).text,
65
+ );
66
+ if (
67
+ !object(scope) ||
68
+ scope.version !== 1 ||
69
+ scope.executionId !== admission.request.executionId ||
70
+ !bounded(scope.cwd) ||
71
+ !scope.cwd.startsWith("/") ||
72
+ scope.workspaceId !== admission.request.workspaceId ||
73
+ (scope.workspaceId === null && scope.cwd !== admission.request.cwd)
74
+ )
75
+ throw Error("invalid resolved operation scope");
76
+ return scope as ResolvedScope;
77
+ } catch (error) {
78
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
79
+ throw error;
80
+ }
81
+ }
82
+ function location(directory: string | undefined, owner: OperationArtifactOwner, operationId: string) {
83
+ ownerCheck(owner);
84
+ if (!validOperationId(operationId)) throw Error("invalid operation artifact operationId");
85
+ const root = operationArtifactsDir(directory === undefined ? undefined : realpathSync(directory));
86
+ return join(root, artifactHash(JSON.stringify([owner.sessionId, owner.cwd])), artifactHash(operationId));
87
+ }
88
+ interface Admission {
89
+ version: 1;
90
+ producer: "pi-daddy";
91
+ owner: OperationArtifactOwner;
92
+ request: OperationRequest;
93
+ admittedAt: string;
94
+ }
95
+ function parseAdmission(text: string, owner: OperationArtifactOwner, id: string): Admission {
96
+ const v = JSON.parse(text);
97
+ if (
98
+ !object(v) ||
99
+ v.version !== 1 ||
100
+ v.producer !== "pi-daddy" ||
101
+ v.owner?.sessionId !== owner.sessionId ||
102
+ v.owner?.cwd !== owner.cwd ||
103
+ v.request?.operationId !== id ||
104
+ !bounded(v.admittedAt, 64)
105
+ )
106
+ throw Error("invalid operation admission manifest");
107
+ requestCheck(v.request);
108
+ return v as Admission;
109
+ }
110
+ function admissionAt(path: string, owner: OperationArtifactOwner, id: string): Admission | null {
111
+ try {
112
+ privateArtifactDirectory(path);
113
+ return parseAdmission(
114
+ readBoundedTextSync(join(path, "admission.json"), {
115
+ maxBytes: MAX_OPERATION_MANIFEST_BYTES,
116
+ confinedRoot: path,
117
+ }).text,
118
+ owner,
119
+ id,
120
+ );
121
+ } catch (error) {
122
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
123
+ throw error;
124
+ }
125
+ }
126
+ function manifestCheck(v: unknown, admission: Admission, path: string): OperationArtifactManifest {
127
+ if (
128
+ !object(v) ||
129
+ v.version !== 1 ||
130
+ v.producer !== "pi-daddy" ||
131
+ v.owner?.sessionId !== admission.owner.sessionId ||
132
+ v.owner?.cwd !== admission.owner.cwd ||
133
+ !sameRequest(v.request, admission.request) ||
134
+ !object(v.operation) ||
135
+ v.operation.operationId !== admission.request.operationId ||
136
+ v.operation.executionId !== admission.request.executionId ||
137
+ !["settled", "not-started", "uncertain"].includes(v.operation.state) ||
138
+ !bounded(v.observedAt, 64) ||
139
+ !bounded(v.operation.cwd) ||
140
+ !(v.operation.workspaceId === null || bounded(v.operation.workspaceId, 512)) ||
141
+ !bounded(v.operation.startedAt, 64) ||
142
+ !bounded(v.operation.updatedAt, 64) ||
143
+ v.operation.artifact !== undefined
144
+ )
145
+ throw Error("invalid operation result manifest");
146
+ const expectedScope = resolvedScope(path, admission) ?? admission.request;
147
+ if (v.operation.cwd !== expectedScope.cwd || v.operation.workspaceId !== expectedScope.workspaceId)
148
+ throw Error("operation result scope does not match its admitted execution");
149
+ if (v.final) {
150
+ const observed = v.operation.runtime?.final;
151
+ if (
152
+ !object(v.final) ||
153
+ v.final.state !== "complete" ||
154
+ !digest(v.final.sha256) ||
155
+ !["sessionId", "messageId", "leafId"].every((k) => bounded(v.final[k], 512)) ||
156
+ v.final.content?.path !== join(path, "final.txt") ||
157
+ v.final.content?.sha256 !== v.final.sha256 ||
158
+ observed?.state !== "complete" ||
159
+ !["sessionId", "messageId", "leafId", "sha256"].every((k) => observed[k] === v.final[k])
160
+ )
161
+ throw Error("operation native final identity mismatch");
162
+ }
163
+ if (v.partial && v.partial.path !== join(path, "partial.txt")) throw Error("invalid partial artifact path");
164
+ if (v.final && v.partial) throw Error("exact final and partial evidence cannot be conflated");
165
+ return v as OperationArtifactManifest;
166
+ }
167
+ function refFor(manifest: OperationArtifactManifest, content: OperationArtifactRef["manifest"]): OperationArtifactRef {
168
+ return {
169
+ version: 1,
170
+ producer: "pi-daddy",
171
+ owner: { ...manifest.owner },
172
+ operationId: manifest.request.operationId,
173
+ executionId: manifest.request.executionId,
174
+ manifest: content,
175
+ };
176
+ }
177
+ export interface ReadOperationArtifactOptions {
178
+ /** Trusted selected agent directory, never inferred from the reference. */
179
+ agentDirectory?: string;
180
+ /** Maximum returned authored bytes. Metadata has its own 64 KiB bound. */
181
+ maxBytes?: number;
182
+ }
183
+ /** Exact immutable read; a successful read is not current applicability or execution authority. */
184
+ export function readOperationArtifact(reference: OperationArtifactRef, options: ReadOperationArtifactOptions = {}) {
185
+ if (!object(reference) || reference.version !== 1 || reference.producer !== "pi-daddy")
186
+ throw Error("unsupported operation artifact reference");
187
+ const path = location(options.agentDirectory, reference.owner, reference.operationId);
188
+ if (reference.manifest?.path !== join(path, "result.json"))
189
+ throw Error("operation artifact path does not match owner");
190
+ const admission = admissionAt(path, reference.owner, reference.operationId);
191
+ if (!admission || reference.executionId !== admission.request.executionId)
192
+ throw Error("operation artifact admission identity mismatch");
193
+ const manifest = manifestCheck(
194
+ JSON.parse(readArtifactBytes(reference.manifest, path, MAX_OPERATION_MANIFEST_BYTES)),
195
+ admission,
196
+ path,
197
+ );
198
+ const maxBytes = options.maxBytes ?? MAX_OPERATION_ARTIFACT_BYTES;
199
+ if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > MAX_OPERATION_ARTIFACT_BYTES)
200
+ throw Error("invalid operation artifact read limit");
201
+ let final: RetainedOperationFinal | undefined;
202
+ let partial: { text: string; sha256: string } | undefined;
203
+ if (manifest.final) {
204
+ const { content, ...identity } = manifest.final;
205
+ final = { ...identity, text: readArtifactBytes(content, path, maxBytes) };
206
+ }
207
+ if (manifest.partial)
208
+ partial = { text: readArtifactBytes(manifest.partial, path, maxBytes), sha256: manifest.partial.sha256 };
209
+ return { manifest, ...(final ? { final } : {}), ...(partial ? { partial } : {}) };
210
+ }
211
+ export interface OperationArtifactHistory {
212
+ operation: OperationReference;
213
+ requestDigest: string;
214
+ reason?: string;
215
+ artifact?: OperationArtifactRef;
216
+ final?: RetainedOperationFinal;
217
+ partial?: { text: string; sha256: string };
218
+ }
219
+ export function openOperationArtifacts(agentDirectory: string, owner: OperationArtifactOwner) {
220
+ ownerCheck(owner);
221
+ 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;
258
+ return {
259
+ operation: { ...manifest.operation, artifact },
260
+ artifact,
261
+ requestDigest: admission.request.requestDigest,
262
+ ...(content?.final ? { final: content.final } : {}),
263
+ ...(content?.partial ? { partial: content.partial } : {}),
264
+ };
265
+ };
266
+ return {
267
+ owner: Object.freeze({ ...owner }),
268
+ history,
269
+ admit(request: OperationRequest) {
270
+ requestCheck(request);
271
+ request = cleanRequest(request);
272
+ const existing = history(request.operationId, false);
273
+ if (existing) {
274
+ if (existing.requestDigest !== request.requestDigest)
275
+ throw Error("Operation identity conflict with retained request");
276
+ return { created: false, ...existing };
277
+ }
278
+ const path = location(directory, owner, request.operationId);
279
+ privateArtifactDirectory(path, true);
280
+ const admission: Admission = {
281
+ version: 1,
282
+ producer: "pi-daddy",
283
+ owner: { ...owner },
284
+ request: { ...request },
285
+ admittedAt: new Date().toISOString(),
286
+ };
287
+ try {
288
+ publishArtifact(path, "admission.json", artifactJson(admission), false);
289
+ } catch (error) {
290
+ const winner = history(request.operationId, false);
291
+ if (!winner) throw error;
292
+ if (winner.requestDigest !== request.requestDigest)
293
+ throw Error("Operation identity conflict with retained request");
294
+ return { created: false, ...winner };
295
+ }
296
+ return { created: true };
297
+ },
298
+ started(request: OperationRequest, cwd: string, workspaceId: string | null) {
299
+ requestCheck(request);
300
+ const path = location(directory, owner, request.operationId),
301
+ admission = admissionAt(path, owner, request.operationId);
302
+ if (
303
+ !admission ||
304
+ !sameRequest(admission.request, request) ||
305
+ !bounded(cwd) ||
306
+ !cwd.startsWith("/") ||
307
+ workspaceId !== request.workspaceId ||
308
+ (workspaceId === null && cwd !== request.cwd)
309
+ )
310
+ throw Error("resolved operation scope does not match its admitted request");
311
+ publishArtifact(
312
+ path,
313
+ "scope.json",
314
+ artifactJson({ version: 1, executionId: request.executionId, cwd, workspaceId }),
315
+ );
316
+ },
317
+ finish(request: OperationRequest, outcome: OperationArtifactOutcome): OperationArtifactRef {
318
+ requestCheck(request);
319
+ request = cleanRequest(request);
320
+ const path = location(directory, owner, request.operationId);
321
+ const admission = admissionAt(path, owner, request.operationId);
322
+ if (!admission || !sameRequest(admission.request, request))
323
+ throw Error("operation result does not own its admission");
324
+ const { artifact: _artifact, ...operation } = outcome.operation as OperationReference;
325
+ const manifest: OperationArtifactManifest = {
326
+ version: 1,
327
+ producer: "pi-daddy",
328
+ owner: { ...owner },
329
+ request: { ...request },
330
+ operation,
331
+ observedAt: operation.updatedAt,
332
+ };
333
+ if (outcome.final) {
334
+ const { text, ...identity } = outcome.final;
335
+ if (
336
+ typeof text !== "string" ||
337
+ Buffer.byteLength(text) > MAX_OPERATION_ARTIFACT_BYTES ||
338
+ artifactHash(text) !== identity.sha256
339
+ )
340
+ throw Error("invalid or oversized exact final");
341
+ manifest.final = {
342
+ ...identity,
343
+ content: { path: join(path, "final.txt"), sha256: identity.sha256, bytes: Buffer.byteLength(text) },
344
+ };
345
+ } else if (outcome.partial !== undefined) {
346
+ if (typeof outcome.partial !== "string" || Buffer.byteLength(outcome.partial) > MAX_OPERATION_ARTIFACT_BYTES)
347
+ throw Error("oversized partial output");
348
+ manifest.partial = {
349
+ path: join(path, "partial.txt"),
350
+ sha256: artifactHash(outcome.partial),
351
+ bytes: Buffer.byteLength(outcome.partial),
352
+ };
353
+ }
354
+ manifestCheck(manifest, admission, path);
355
+ if (manifest.final) publishArtifact(path, "final.txt", outcome.final!.text);
356
+ if (manifest.partial) publishArtifact(path, "partial.txt", outcome.partial!);
357
+ const text = artifactJson(manifest);
358
+ if (Buffer.byteLength(text) > MAX_OPERATION_MANIFEST_BYTES) throw Error("oversized operation manifest");
359
+ return refFor(manifest, publishArtifact(path, "result.json", text));
360
+ },
361
+ };
362
+ }
363
+ export type OperationArtifactStore = ReturnType<typeof openOperationArtifacts>;
@@ -269,3 +269,31 @@ export async function openRuntimeSettlement(
269
269
  throw error;
270
270
  }
271
271
  }
272
+
273
+ /** Read-only evidence for one exact historical execution. Does not adopt its session or rewrite the journal. */
274
+ export async function readRuntimeExecutionSettlement(
275
+ directory: string,
276
+ sessionId: string,
277
+ cwd: string,
278
+ executionId: string,
279
+ ) {
280
+ const root = join(realpathSync(directory), "pi-daddy", "runtime-settlement");
281
+ if (realpathSync(root) !== root) throw Error("runtime settlement root changed");
282
+ const info = lstatSync(root);
283
+ if (!info.isDirectory() || info.uid !== process.getuid?.() || info.mode & 0o077)
284
+ throw Error("runtime settlement root must remain private");
285
+ const path = join(root, settlementHash([sessionId, cwd]) + ".json");
286
+ const text = readBoundedTextSync(path, { maxBytes: MAX_RECORD, confinedRoot: root }).text;
287
+ const journal = validate(JSON.parse(text), sessionId, cwd);
288
+ const e = journal.executions.find((item) => item.id === executionId);
289
+ if (!e || e.problem) return "unknown" as const;
290
+ let result: "settled" | "not-started" | "unknown" = "unknown";
291
+ if (e.state === "not-started" && !e.identity) result = "not-started";
292
+ else if (e.identity) {
293
+ const receipt = await readCapturedWorkerReceipt(e.identity);
294
+ if (receipt && (!e.receiptSha256 || e.receiptSha256 === settlementHash(receipt))) result = "settled";
295
+ }
296
+ if (readBoundedTextSync(path, { maxBytes: MAX_RECORD, confinedRoot: root }).text !== text)
297
+ throw Error("runtime settlement evidence changed during read");
298
+ return result;
299
+ }
@@ -116,6 +116,24 @@ export async function reconcileAcceptedWorkspaces(
116
116
  };
117
117
  }
118
118
 
119
+ /** Read-only inspection: unlike reconciliation, absence never creates first-use acceptance. */
120
+ export async function inspectAcceptedWorkspaces(
121
+ registryPath: string,
122
+ env: NodeJS.ProcessEnv = process.env,
123
+ ): Promise<{ state: "absent" | "invalid" | "recorded"; accepted: string[] }> {
124
+ let text: string;
125
+ try {
126
+ text = await readAuthorityText(acceptedWorkspacesPath(registryPath, env));
127
+ } catch (error) {
128
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return { state: "absent", accepted: [] };
129
+ throw error;
130
+ }
131
+ const stored = parse(text);
132
+ return stored && stored.registry === registryPath
133
+ ? { state: "recorded", accepted: [...stored.accepted] }
134
+ : { state: "invalid", accepted: [] };
135
+ }
136
+
119
137
  /** Accept the registry's current ids, replacing what was accepted before. `/grants` drives this. */
120
138
  export async function acceptWorkspaces(
121
139
  registryPath: string,
package/src/index.ts CHANGED
@@ -193,3 +193,16 @@ export {
193
193
  } from "./kernel/workspace-pin.ts";
194
194
 
195
195
  export { exportDiagnostics, parseDiagnosticSelection, type DiagnosticSelection } from "./products/diagnostic-export.ts";
196
+
197
+ export * from "./kernel/operation-artifact.ts";
198
+ export * from "./governance/operation-artifacts.ts";
199
+
200
+ export { openOperationArtifactScan, operationArtifactInstance } from "./governance/operation-artifact-scan.ts";
201
+
202
+ export * from "./kernel/dashboard-observation.ts";
203
+
204
+ export * from "./kernel/initiative.ts";
205
+ export * from "./governance/initiative-state.ts";
206
+ export * from "./governance/initiative-coordinator.ts";
207
+
208
+ export { inspectWorkspaceRouting, type WorkspaceRoutingObservation } from "./kernel/workspace-diagnostics.ts";
@@ -0,0 +1,109 @@
1
+ /** Terminal-only producer observations. None of these fields confer authority or become tool input. */
2
+ export const DASHBOARD_SOURCE_EVENT = "pi-daddy:dashboard-source:v1";
3
+ export const DASHBOARD_SOURCE_LIMIT = 8;
4
+ export const DASHBOARD_SOURCE_BYTES = 4096;
5
+ export type DashboardContributionKind = "goal" | "next" | "work" | "review" | "evidence" | "status";
6
+ export type DashboardObservedState =
7
+ | "observed"
8
+ | "running"
9
+ | "dependency-wait"
10
+ | "approval-wait"
11
+ | "cancel-requested"
12
+ | "settled"
13
+ | "failed"
14
+ | "unknown"
15
+ | "unavailable";
16
+ export interface DashboardContribution {
17
+ id: string;
18
+ kind: DashboardContributionKind;
19
+ label: string;
20
+ state: DashboardObservedState;
21
+ details?: string[];
22
+ /** Display identity only. The terminal never dereferences or executes it. */
23
+ reference?: string;
24
+ }
25
+ export interface DashboardSourceUpdate {
26
+ sequence: number;
27
+ items: DashboardContribution[];
28
+ }
29
+ /** Trusted in-process registration. Callbacks are never serialized to a model or terminal client. */
30
+ export type DashboardSourceRegistrationReply =
31
+ | { version: 1; ok: false; reason: string }
32
+ | { version: 1; ok: true; generation: string; publish(update: DashboardSourceUpdate): boolean; close(): void };
33
+ export interface DashboardSourceRegistration {
34
+ version: 1;
35
+ sessionId: string;
36
+ cwd: string;
37
+ producer: string;
38
+ producerVersion: string;
39
+ reply(value: DashboardSourceRegistrationReply): void;
40
+ }
41
+ export interface DashboardSourceSnapshot extends DashboardSourceUpdate {
42
+ producer: string;
43
+ producerVersion: string;
44
+ generation: string;
45
+ observedAt: string;
46
+ staleAfterMs: number;
47
+ availability: "observed" | "closed";
48
+ }
49
+ export interface DashboardOwnerObservation {
50
+ version: 1;
51
+ sessionId: string;
52
+ cwd: string;
53
+ generation: string;
54
+ sequence: number;
55
+ observedAt: string;
56
+ sources: DashboardSourceSnapshot[];
57
+ logicalOwnerId?: string;
58
+ turn?: DashboardContribution;
59
+ activity?: DashboardContribution[];
60
+ artifacts?: Array<{ operationId: string; executionId: string; sha256: string }>;
61
+ resources: { scope: "owner-process"; sampledAt: string; rssBytes: number; hostHealth: "unknown" };
62
+ capture: { transcripts: boolean; diagnostics: boolean };
63
+ }
64
+ const object = (x: unknown): x is Record<string, unknown> => !!x && typeof x === "object" && !Array.isArray(x);
65
+ const bounded = (x: unknown, max: number): x is string => typeof x === "string" && x.length > 0 && x.length <= max;
66
+ export function validDashboardSourceUpdate(value: unknown): value is DashboardSourceUpdate {
67
+ if (
68
+ !object(value) ||
69
+ Object.keys(value).some((k) => !["sequence", "items"].includes(k)) ||
70
+ !Number.isSafeInteger(value.sequence) ||
71
+ Number(value.sequence) < 0 ||
72
+ !Array.isArray(value.items) ||
73
+ value.items.length > 8
74
+ )
75
+ return false;
76
+ const ids = new Set<string>();
77
+ for (const row of value.items) {
78
+ if (
79
+ !object(row) ||
80
+ Object.keys(row).some((k) => !["id", "kind", "label", "state", "details", "reference"].includes(k)) ||
81
+ !bounded(row.id, 160) ||
82
+ ids.has(row.id) ||
83
+ !bounded(row.label, 240) ||
84
+ !["goal", "next", "work", "review", "evidence", "status"].includes(String(row.kind)) ||
85
+ ![
86
+ "observed",
87
+ "running",
88
+ "dependency-wait",
89
+ "approval-wait",
90
+ "cancel-requested",
91
+ "settled",
92
+ "failed",
93
+ "unknown",
94
+ "unavailable",
95
+ ].includes(String(row.state)) ||
96
+ (row.reference !== undefined && !bounded(row.reference, 512)) ||
97
+ (row.details !== undefined &&
98
+ (!Array.isArray(row.details) || row.details.length > 6 || !row.details.every((x) => bounded(x, 240))))
99
+ )
100
+ return false;
101
+ ids.add(row.id);
102
+ }
103
+ try {
104
+ if (Buffer.byteLength(JSON.stringify(value)) > DASHBOARD_SOURCE_BYTES) return false;
105
+ } catch {
106
+ return false;
107
+ }
108
+ return true;
109
+ }
@@ -1,5 +1,7 @@
1
+ import type { OperationArtifactRef } from "./operation-artifact.ts";
1
2
  /** Explicit operation identity prevents duplicate dispatch, never authorizes work or caches results. */
2
3
  export interface OperationReference {
4
+ artifact?: OperationArtifactRef;
3
5
  operationId: string;
4
6
  executionId: string;
5
7
  state: "admitting" | "running" | "settled" | "not-started" | "uncertain";
@@ -0,0 +1,126 @@
1
+ /** Cooperative local continuation identity; never a capability, task acceptance, or external-effect proof. */
2
+ import type { OperationArtifactOwner } from "./operation-artifact.ts";
3
+ export interface InitiativeTask {
4
+ taskId: string;
5
+ taskRevision: string;
6
+ effectScope: "local" | "external" | "unknown";
7
+ effectTarget?: InitiativeEffectTarget;
8
+ }
9
+ export interface InitiativeAttempt {
10
+ owner: OperationArtifactOwner;
11
+ operationId: string;
12
+ executionId: string;
13
+ requestDigest: string;
14
+ state: "pending" | "not-admitted";
15
+ effectReceipt?: InitiativeEffectReceipt;
16
+ }
17
+ export interface InitiativeTaskRecord extends InitiativeTask {
18
+ generation: number;
19
+ attempts: InitiativeAttempt[];
20
+ }
21
+ export interface InitiativeRecord {
22
+ version: 1;
23
+ initiativeId: string;
24
+ generation: number;
25
+ owner: OperationArtifactOwner;
26
+ state: "owned" | "released";
27
+ tasks: InitiativeTaskRecord[];
28
+ }
29
+ export interface InitiativeObservation {
30
+ status: "observed";
31
+ initiativeId: string;
32
+ taskId: string;
33
+ taskRevision: string;
34
+ ownerGeneration: number;
35
+ claim: "unclaimed" | "owned" | "other-owner" | "uncertain";
36
+ execution: "none" | "running" | "settled" | "unknown";
37
+ reconciliationRequired: boolean;
38
+ effectObservation?: InitiativeEffectObservation;
39
+ assertCurrent(): void | Promise<void>;
40
+ }
41
+ export interface InitiativeTaskIdentity {
42
+ initiativeId: string;
43
+ taskId: string;
44
+ taskRevision: string;
45
+ }
46
+ export const validInitiativeId = (v: unknown): v is string =>
47
+ typeof v === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,255}$/.test(v);
48
+ export const validTaskId = validInitiativeId;
49
+ export const validTaskRevision = (v: unknown): v is string =>
50
+ typeof v === "string" && /^(?:sha256:)?[a-f0-9]{64}$/.test(v);
51
+ export function validInitiativeTask(v: unknown): v is InitiativeTask {
52
+ const t = v as InitiativeTask;
53
+ return (
54
+ !!t &&
55
+ validTaskId(t.taskId) &&
56
+ validTaskRevision(t.taskRevision) &&
57
+ ["local", "external", "unknown"].includes(t.effectScope) &&
58
+ (t.effectTarget === undefined || validEffectTarget(t.effectTarget))
59
+ );
60
+ }
61
+
62
+ /** Exact selected canonical receipt. It records reconciliation, never task acceptance or a permission. */
63
+ export interface InitiativeEffectReceipt {
64
+ reference: string;
65
+ sha256: string;
66
+ observation?: InitiativeEffectReported;
67
+ }
68
+ export interface InitiativeEffectIdentity extends InitiativeTaskIdentity {
69
+ owner: OperationArtifactOwner;
70
+ operationId: string;
71
+ executionId: string;
72
+ effectScope: InitiativeTask["effectScope"];
73
+ }
74
+ export interface InitiativeEffectReconciliation extends InitiativeEffectIdentity {
75
+ receipt: InitiativeEffectReceipt;
76
+ }
77
+ export function validEffectReceipt(value: unknown): value is InitiativeEffectReceipt {
78
+ const r = value as InitiativeEffectReceipt;
79
+ return (
80
+ !!r &&
81
+ typeof r.reference === "string" &&
82
+ r.reference.length > 0 &&
83
+ r.reference.length <= 2048 &&
84
+ !/[\x00-\x1f\x7f]/.test(r.reference) &&
85
+ typeof r.sha256 === "string" &&
86
+ /^[a-f0-9]{64}$/.test(r.sha256) &&
87
+ (r.observation === undefined || validEffectReported(r.observation))
88
+ );
89
+ }
90
+
91
+ /** Neutral target identity supplied by its responsible owner; Daddy does not interpret its domain. */
92
+ export interface InitiativeEffectTarget {
93
+ owner: string;
94
+ kind: string;
95
+ reference: string;
96
+ }
97
+ export interface InitiativeEffectReported {
98
+ target: InitiativeEffectTarget;
99
+ outcome: "applied" | "not-applied" | "unknown";
100
+ provenance: "operator-attested" | "owner-verified";
101
+ }
102
+ export interface InitiativeEffectObservation {
103
+ target: InitiativeEffectTarget;
104
+ outcome: "pending" | InitiativeEffectReported["outcome"];
105
+ provenance: "not-observed" | InitiativeEffectReported["provenance"];
106
+ receipt?: { reference: string; sha256: string };
107
+ attempt?: { owner: OperationArtifactOwner; operationId: string; executionId: string };
108
+ }
109
+ const displayIdentity = (v: unknown, max: number): v is string =>
110
+ typeof v === "string" && v.length > 0 && v.length <= max && !/[\x00-\x1f\x7f]/.test(v);
111
+ export function validEffectTarget(value: unknown): value is InitiativeEffectTarget {
112
+ const t = value as InitiativeEffectTarget;
113
+ return !!t && displayIdentity(t.owner, 48) && displayIdentity(t.kind, 80) && displayIdentity(t.reference, 2048);
114
+ }
115
+ export function sameEffectTarget(a?: InitiativeEffectTarget, b?: InitiativeEffectTarget) {
116
+ return !a || !b ? a === b : a.owner === b.owner && a.kind === b.kind && a.reference === b.reference;
117
+ }
118
+ export function validEffectReported(value: unknown): value is InitiativeEffectReported {
119
+ const o = value as InitiativeEffectReported;
120
+ return (
121
+ !!o &&
122
+ validEffectTarget(o.target) &&
123
+ ["applied", "not-applied", "unknown"].includes(o.outcome) &&
124
+ ["operator-attested", "owner-verified"].includes(o.provenance)
125
+ );
126
+ }