pi-daddy 0.49.5 → 0.51.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 (160) hide show
  1. package/CHANGELOG.md +57 -1
  2. package/README.md +231 -27
  3. package/dist/governance/initiative-coordinator.d.ts +63 -0
  4. package/dist/governance/initiative-coordinator.d.ts.map +1 -0
  5. package/dist/governance/initiative-coordinator.js +364 -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 +50 -10
  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 +72 -2
  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-layout.d.ts +6 -0
  89. package/dist/products/dashboard-layout.d.ts.map +1 -0
  90. package/dist/products/dashboard-layout.js +45 -0
  91. package/dist/products/dashboard-layout.js.map +1 -0
  92. package/dist/products/dashboard-panels.d.ts +10 -0
  93. package/dist/products/dashboard-panels.d.ts.map +1 -0
  94. package/dist/products/dashboard-panels.js +319 -0
  95. package/dist/products/dashboard-panels.js.map +1 -0
  96. package/dist/products/dashboard-recap.d.ts +4 -0
  97. package/dist/products/dashboard-recap.d.ts.map +1 -0
  98. package/dist/products/dashboard-recap.js +47 -0
  99. package/dist/products/dashboard-recap.js.map +1 -0
  100. package/dist/products/dashboard-screen.d.ts +14 -1
  101. package/dist/products/dashboard-screen.d.ts.map +1 -1
  102. package/dist/products/dashboard-screen.js +217 -40
  103. package/dist/products/dashboard-screen.js.map +1 -1
  104. package/dist/products/dashboard-session-client.d.ts +16 -2
  105. package/dist/products/dashboard-session-client.d.ts.map +1 -1
  106. package/dist/products/dashboard-session-client.js +64 -11
  107. package/dist/products/dashboard-session-client.js.map +1 -1
  108. package/dist/products/dashboard-settings.d.ts.map +1 -1
  109. package/dist/products/dashboard-settings.js +4 -6
  110. package/dist/products/dashboard-settings.js.map +1 -1
  111. package/dist/products/ecosystem-versions.d.ts +1 -1
  112. package/dist/products/ecosystem-versions.d.ts.map +1 -1
  113. package/extensions/activity-timeline.ts +3 -1
  114. package/extensions/artifact-bridge.ts +130 -0
  115. package/extensions/dashboard-live.ts +63 -0
  116. package/extensions/dashboard-observation.ts +39 -0
  117. package/extensions/dashboard-session-server.ts +45 -3
  118. package/extensions/dashboard-sources.ts +124 -0
  119. package/extensions/delegation-artifacts.ts +133 -0
  120. package/extensions/delegation-operations.ts +42 -13
  121. package/extensions/ecosystem-versions.ts +12 -5
  122. package/extensions/grants-command.ts +34 -6
  123. package/extensions/grants.ts +9 -20
  124. package/extensions/initiative-dashboard.ts +143 -0
  125. package/extensions/initiative-handoff.ts +59 -0
  126. package/extensions/initiative-runtime.ts +444 -0
  127. package/extensions/runtime-snapshot.ts +118 -2
  128. package/extensions/session-environment.ts +13 -1
  129. package/extensions/session.ts +28 -10
  130. package/extensions/workspace-diagnostics.ts +90 -0
  131. package/package.json +1 -1
  132. package/src/governance/initiative-coordinator.ts +416 -0
  133. package/src/governance/initiative-effects.ts +146 -0
  134. package/src/governance/initiative-state.ts +144 -0
  135. package/src/governance/operation-artifact-io.ts +103 -0
  136. package/src/governance/operation-artifact-scan.ts +77 -0
  137. package/src/governance/operation-artifacts.ts +363 -0
  138. package/src/governance/runtime-settlement.ts +28 -0
  139. package/src/governance/workspace-acceptance.ts +18 -0
  140. package/src/index.ts +13 -0
  141. package/src/kernel/dashboard-observation.ts +109 -0
  142. package/src/kernel/dispatch-operation.ts +2 -0
  143. package/src/kernel/initiative.ts +126 -0
  144. package/src/kernel/operation-artifact.ts +46 -0
  145. package/src/kernel/principal-binding.ts +104 -0
  146. package/src/kernel/project-paths.ts +16 -0
  147. package/src/kernel/selected-definitions.ts +5 -100
  148. package/src/kernel/workspace-diagnostics.ts +110 -0
  149. package/src/products/activity-storage.ts +128 -0
  150. package/src/products/activity-timeline.ts +11 -0
  151. package/src/products/dashboard-cli.ts +53 -10
  152. package/src/products/dashboard-display-controls.ts +63 -2
  153. package/src/products/dashboard-file-cache.ts +38 -0
  154. package/src/products/dashboard-layout.ts +50 -0
  155. package/src/products/dashboard-panels.ts +379 -0
  156. package/src/products/dashboard-recap.ts +48 -0
  157. package/src/products/dashboard-screen.ts +266 -43
  158. package/src/products/dashboard-session-client.ts +78 -14
  159. package/src/products/dashboard-settings.ts +4 -6
  160. package/src/products/ecosystem-versions.ts +2 -1
@@ -0,0 +1,146 @@
1
+ /** Bounded exact reconciliation helpers; receipt authority is supplied by the selected owner, not a model. */
2
+ import {
3
+ validEffectReceipt,
4
+ sameEffectTarget,
5
+ type InitiativeEffectReceipt,
6
+ type InitiativeEffectTarget,
7
+ type InitiativeEffectObservation,
8
+ type InitiativeTask,
9
+ type InitiativeTaskRecord,
10
+ type InitiativeAttempt,
11
+ type InitiativeRecord,
12
+ type InitiativeEffectIdentity,
13
+ type InitiativeEffectReconciliation,
14
+ } from "../kernel/initiative.ts";
15
+ export interface InitiativeResolution {
16
+ resolveAttempt(attempt: InitiativeAttempt): Promise<"settled" | "not-started" | "running" | "unknown">;
17
+ assertEffectReconciled?(input: InitiativeEffectReconciliation): void | Promise<void>;
18
+ }
19
+ export function effectIdentity(
20
+ initiativeId: string,
21
+ task: InitiativeTaskRecord,
22
+ attempt: InitiativeAttempt,
23
+ ): InitiativeEffectIdentity {
24
+ return {
25
+ initiativeId,
26
+ taskId: task.taskId,
27
+ taskRevision: task.taskRevision,
28
+ effectScope: task.effectScope,
29
+ owner: { ...attempt.owner },
30
+ operationId: attempt.operationId,
31
+ executionId: attempt.executionId,
32
+ };
33
+ }
34
+ export async function currentEffectReceipt(
35
+ initiativeId: string,
36
+ task: InitiativeTaskRecord,
37
+ attempt: InitiativeAttempt,
38
+ options: InitiativeResolution,
39
+ ): Promise<InitiativeEffectReceipt | undefined> {
40
+ if (!attempt.effectReceipt || !options.assertEffectReconciled) return undefined;
41
+ if (
42
+ attempt.effectReceipt.observation &&
43
+ !sameEffectTarget(task.effectTarget, attempt.effectReceipt.observation.target)
44
+ )
45
+ return undefined;
46
+ try {
47
+ await options.assertEffectReconciled({
48
+ ...effectIdentity(initiativeId, task, attempt),
49
+ receipt: structuredClone(attempt.effectReceipt),
50
+ });
51
+ return structuredClone(attempt.effectReceipt);
52
+ } catch {
53
+ return undefined;
54
+ }
55
+ }
56
+ export function receiptResolves(task: InitiativeTaskRecord, receipt?: InitiativeEffectReceipt) {
57
+ if (receipt?.observation?.outcome === "unknown") return false;
58
+ return task.effectScope === "local" || (!!receipt && (!task.effectTarget || !!receipt.observation));
59
+ }
60
+ export async function effectCurrent(
61
+ initiativeId: string,
62
+ task: InitiativeTaskRecord,
63
+ attempt: InitiativeAttempt,
64
+ options: InitiativeResolution,
65
+ ) {
66
+ return receiptResolves(task, await currentEffectReceipt(initiativeId, task, attempt, options));
67
+ }
68
+ /** Last exact attempt for the selected target; unknown evidence is never promoted to an applied effect. */
69
+ export function effectObservation(
70
+ target: InitiativeEffectTarget | undefined,
71
+ attempt: InitiativeAttempt | undefined,
72
+ execution: "settled" | "not-started" | "running" | "unknown" | undefined,
73
+ receipt?: InitiativeEffectReceipt,
74
+ ): InitiativeEffectObservation | undefined {
75
+ if (!target) return undefined;
76
+ const identity = attempt
77
+ ? { owner: { ...attempt.owner }, operationId: attempt.operationId, executionId: attempt.executionId }
78
+ : undefined;
79
+ if (!attempt || execution === "not-started")
80
+ return {
81
+ target: structuredClone(target),
82
+ outcome: "pending",
83
+ provenance: "not-observed",
84
+ ...(identity ? { attempt: identity } : {}),
85
+ };
86
+ if (execution === "settled" && receipt?.observation && sameEffectTarget(target, receipt.observation.target))
87
+ return {
88
+ ...structuredClone(receipt.observation),
89
+ receipt: { reference: receipt.reference, sha256: receipt.sha256 },
90
+ attempt: identity,
91
+ };
92
+ return { target: structuredClone(target), outcome: "unknown", provenance: "not-observed", attempt: identity };
93
+ }
94
+ export async function settledInitiative(record: InitiativeRecord, options: InitiativeResolution) {
95
+ for (const task of record.tasks)
96
+ for (const attempt of task.attempts) {
97
+ const status = await options.resolveAttempt(structuredClone(attempt));
98
+ if (status === "not-started") continue;
99
+ if (status !== "settled" || !(await effectCurrent(record.initiativeId, task, attempt, options))) return false;
100
+ }
101
+ return true;
102
+ }
103
+ /** A changed task revision cannot silently repeat an already-applied exact target. */
104
+ export async function assertTaskPriorSettled(
105
+ record: InitiativeRecord,
106
+ task: InitiativeTask,
107
+ options: InitiativeResolution,
108
+ exclude?: InitiativeAttempt,
109
+ ) {
110
+ for (const previous of record.tasks.filter((t) => t.taskId === task.taskId))
111
+ for (const attempt of previous.attempts) {
112
+ if (attempt === exclude) continue;
113
+ const status = await options.resolveAttempt(structuredClone(attempt));
114
+ if (status === "not-started") continue;
115
+ if (status !== "settled") throw Error("task already has unresolved attempts");
116
+ const receipt = await currentEffectReceipt(record.initiativeId, previous, attempt, options);
117
+ if (!receiptResolves(previous, receipt)) throw Error("task prior attempts need reconciliation before start");
118
+ if (
119
+ task.effectTarget &&
120
+ sameEffectTarget(task.effectTarget, previous.effectTarget) &&
121
+ receipt?.observation?.outcome === "applied"
122
+ )
123
+ throw Error("exact task target is already applied; an amended task revision does not authorize repeating it");
124
+ }
125
+ }
126
+ export function exactEffect(record: InitiativeRecord, input: InitiativeEffectReconciliation) {
127
+ if (input.initiativeId !== record.initiativeId || !validEffectReceipt(input.receipt))
128
+ throw Error("invalid effect receipt identity");
129
+ const task = record.tasks.find(
130
+ (t) => t.taskId === input.taskId && t.taskRevision === input.taskRevision && t.effectScope === input.effectScope,
131
+ );
132
+ const attempt = task?.attempts.find(
133
+ (a) =>
134
+ a.owner.sessionId === input.owner?.sessionId &&
135
+ a.owner.cwd === input.owner?.cwd &&
136
+ a.operationId === input.operationId &&
137
+ a.executionId === input.executionId,
138
+ );
139
+ if (!task || !attempt || task.effectScope === "local")
140
+ throw Error("effect attempt is outside the exact retained task");
141
+ if (input.receipt.observation && !sameEffectTarget(task.effectTarget, input.receipt.observation.target))
142
+ throw Error("effect observation target differs from selected task");
143
+ if (task.effectTarget && !input.receipt.observation)
144
+ throw Error("selected effect target requires an explicit outcome observation");
145
+ return { task, attempt };
146
+ }
@@ -0,0 +1,144 @@
1
+ /** Bounded private snapshot under the existing Daddy agent state; callers hold the existing OS lock. */
2
+ import { randomUUID } from "node:crypto";
3
+ import {
4
+ constants,
5
+ openSync,
6
+ closeSync,
7
+ fsyncSync,
8
+ writeFileSync,
9
+ renameSync,
10
+ unlinkSync,
11
+ realpathSync,
12
+ existsSync,
13
+ } from "node:fs";
14
+ import { join } from "node:path";
15
+ import { readBoundedTextSync } from "../kernel/bounded-read-sync.ts";
16
+ import { initiativeStateDir } from "../kernel/project-paths.ts";
17
+ import { validOperationId } from "../kernel/dispatch-operation.ts";
18
+ import {
19
+ validInitiativeId,
20
+ validEffectReceipt,
21
+ sameEffectTarget,
22
+ validInitiativeTask,
23
+ type InitiativeRecord,
24
+ } from "../kernel/initiative.ts";
25
+ import { artifactHash, privateArtifactDirectory } from "./operation-artifact-io.ts";
26
+ const MAX_BYTES = 512 * 1024;
27
+ export const initiativeRevision = (record: InitiativeRecord): string => artifactHash(JSON.stringify(record));
28
+ export function initiativeLocation(directory: string, id: string, create = false) {
29
+ if (!validInitiativeId(id)) throw Error("invalid initiative identity");
30
+ const root = initiativeStateDir(realpathSync(directory));
31
+ privateArtifactDirectory(root, create);
32
+ return { root, path: join(root, artifactHash(id) + ".json") };
33
+ }
34
+ export function validateInitiative(v: unknown, id: string): InitiativeRecord {
35
+ const r = v as InitiativeRecord;
36
+ if (
37
+ !r ||
38
+ r.version !== 1 ||
39
+ r.initiativeId !== id ||
40
+ !Number.isSafeInteger(r.generation) ||
41
+ r.generation < 1 ||
42
+ !r.owner ||
43
+ typeof r.owner.sessionId !== "string" ||
44
+ !r.owner.sessionId ||
45
+ r.owner.sessionId.length > 512 ||
46
+ typeof r.owner.cwd !== "string" ||
47
+ !r.owner.cwd.startsWith("/") ||
48
+ r.owner.cwd.length > 4096 ||
49
+ !["owned", "released"].includes(r.state) ||
50
+ !Array.isArray(r.tasks) ||
51
+ r.tasks.length > 256
52
+ )
53
+ throw Error("invalid initiative record");
54
+ const keys = new Set<string>(),
55
+ operations = new Set<string>();
56
+ let attempts = 0;
57
+ for (const t of r.tasks) {
58
+ const key = JSON.stringify([t.taskId, t.taskRevision]);
59
+ if (
60
+ !validInitiativeTask(t) ||
61
+ keys.has(key) ||
62
+ !Number.isSafeInteger(t.generation) ||
63
+ t.generation < 1 ||
64
+ t.generation > r.generation ||
65
+ !Array.isArray(t.attempts)
66
+ )
67
+ throw Error("invalid initiative task record");
68
+ keys.add(key);
69
+ for (const a of t.attempts) {
70
+ const key = JSON.stringify([a.owner?.sessionId, a.owner?.cwd, a.operationId]);
71
+ if (
72
+ ++attempts > 1024 ||
73
+ operations.has(key) ||
74
+ !validOperationId(a.operationId) ||
75
+ typeof a.executionId !== "string" ||
76
+ !a.executionId.startsWith("exec:") ||
77
+ a.executionId.length > 128 ||
78
+ typeof a.requestDigest !== "string" ||
79
+ !/^[a-f0-9]{64}$/.test(a.requestDigest) ||
80
+ !a.owner?.sessionId ||
81
+ a.owner.sessionId.length > 512 ||
82
+ typeof a.owner.cwd !== "string" ||
83
+ !a.owner.cwd.startsWith("/") ||
84
+ a.owner.cwd.length > 4096 ||
85
+ !["pending", "not-admitted"].includes(a.state) ||
86
+ (a.effectReceipt !== undefined && !validEffectReceipt(a.effectReceipt)) ||
87
+ (a.effectReceipt?.observation !== undefined &&
88
+ !sameEffectTarget(t.effectTarget, a.effectReceipt.observation.target))
89
+ )
90
+ throw Error("invalid initiative attempt record");
91
+ operations.add(key);
92
+ }
93
+ }
94
+ return r;
95
+ }
96
+ export function readInitiativeState(directory: string, id: string) {
97
+ try {
98
+ const { path, root } = initiativeLocation(directory, id);
99
+ const record = validateInitiative(
100
+ JSON.parse(readBoundedTextSync(path, { maxBytes: MAX_BYTES, confinedRoot: root }).text),
101
+ id,
102
+ );
103
+ return { record, revision: initiativeRevision(record) };
104
+ } catch (error) {
105
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
106
+ const root = initiativeStateDir(realpathSync(directory));
107
+ if (existsSync(join(root, artifactHash(id) + ".json.initialized")))
108
+ throw Error("initiative state missing; restore trusted state");
109
+ return null;
110
+ }
111
+ throw error;
112
+ }
113
+ }
114
+ export function saveInitiative(path: string, root: string, record: InitiativeRecord) {
115
+ validateInitiative(record, record.initiativeId);
116
+ const text = JSON.stringify(record) + "\n";
117
+ if (Buffer.byteLength(text) > MAX_BYTES) throw Error("initiative record exceeds bound");
118
+ privateArtifactDirectory(root);
119
+ const temporary = path + "." + randomUUID();
120
+ const fd = openSync(
121
+ temporary,
122
+ constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
123
+ 0o600,
124
+ );
125
+ try {
126
+ writeFileSync(fd, text);
127
+ fsyncSync(fd);
128
+ } finally {
129
+ closeSync(fd);
130
+ }
131
+ try {
132
+ renameSync(temporary, path);
133
+ const parent = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
134
+ try {
135
+ fsyncSync(parent);
136
+ } finally {
137
+ closeSync(parent);
138
+ }
139
+ } finally {
140
+ try {
141
+ unlinkSync(temporary);
142
+ } catch {}
143
+ }
144
+ }
@@ -0,0 +1,103 @@
1
+ /** Small private, immutable files. Cooperative local integrity, not a hostile same-uid boundary. */
2
+ import { createHash, randomUUID } from "node:crypto";
3
+ import {
4
+ constants,
5
+ openSync,
6
+ closeSync,
7
+ fstatSync,
8
+ fsyncSync,
9
+ mkdirSync,
10
+ realpathSync,
11
+ writeFileSync,
12
+ linkSync,
13
+ unlinkSync,
14
+ lstatSync,
15
+ } from "node:fs";
16
+ import { join, dirname } from "node:path";
17
+ import { readBoundedTextSync } from "../kernel/bounded-read-sync.ts";
18
+ import type { OperationArtifactContent } from "../kernel/operation-artifact.ts";
19
+ export const artifactHash = (text: string) => createHash("sha256").update(text, "utf8").digest("hex");
20
+ export const artifactJson = (value: unknown) => JSON.stringify(value) + "\n";
21
+ export function privateArtifactDirectory(path: string, create = false): string {
22
+ if (create) {
23
+ const first = mkdirSync(path, { recursive: true, mode: 0o700 });
24
+ if (first) {
25
+ let parent = dirname(path);
26
+ while (true) {
27
+ const fd = openSync(parent, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
28
+ try {
29
+ fsyncSync(fd);
30
+ } finally {
31
+ closeSync(fd);
32
+ }
33
+ if (parent === dirname(first)) break;
34
+ parent = dirname(parent);
35
+ }
36
+ }
37
+ }
38
+ if (realpathSync(path) !== path) throw Error("operation artifact directory must be canonical without symlinks");
39
+ const info = lstatSync(path);
40
+ if (!info.isDirectory() || info.uid !== process.getuid?.() || info.mode & 0o077)
41
+ throw Error("operation artifact directory must be private and owned by this uid");
42
+ return path;
43
+ }
44
+ export function readArtifactBytes(reference: OperationArtifactContent, root: string, maxBytes: number): string {
45
+ if (
46
+ !reference ||
47
+ typeof reference.path !== "string" ||
48
+ !/^[a-f0-9]{64}$/.test(reference.sha256) ||
49
+ !Number.isSafeInteger(reference.bytes) ||
50
+ reference.bytes < 0 ||
51
+ reference.bytes > maxBytes
52
+ )
53
+ throw Error("invalid or oversized operation artifact reference");
54
+ const text = readBoundedTextSync(reference.path, { maxBytes, confinedRoot: root }).text;
55
+ if (Buffer.byteLength(text) !== reference.bytes || artifactHash(text) !== reference.sha256)
56
+ throw Error("operation artifact content identity mismatch");
57
+ return text;
58
+ }
59
+ /** Publish without overwrite. A losing writer may reuse only byte-identical content. */
60
+ export function publishArtifact(path: string, name: string, text: string, reuse = true): OperationArtifactContent {
61
+ privateArtifactDirectory(path);
62
+ const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
63
+ const held = `/proc/self/fd/${fd}`;
64
+ const temporary = `${name}.${randomUUID()}.tmp`;
65
+ try {
66
+ const info = fstatSync(fd);
67
+ if (!info.isDirectory() || info.uid !== process.getuid?.() || info.mode & 0o077)
68
+ throw Error("invalid artifact owner");
69
+ const file = openSync(
70
+ join(held, temporary),
71
+ constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
72
+ 0o600,
73
+ );
74
+ try {
75
+ writeFileSync(file, text);
76
+ fsyncSync(file);
77
+ } finally {
78
+ closeSync(file);
79
+ }
80
+ const reference = { path: join(path, name), sha256: artifactHash(text), bytes: Buffer.byteLength(text) };
81
+ try {
82
+ linkSync(join(held, temporary), join(held, name));
83
+ } catch (error) {
84
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST" || !reuse) throw error;
85
+ readArtifactBytes(reference, path, reference.bytes);
86
+ }
87
+ fsyncSync(fd);
88
+ const current = lstatSync(path);
89
+ if (realpathSync(path) !== path || current.ino !== info.ino || current.dev !== info.dev)
90
+ throw Error("artifact directory changed before publication");
91
+ return reference;
92
+ } finally {
93
+ try {
94
+ try {
95
+ unlinkSync(join(held, temporary));
96
+ } catch (error) {
97
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
98
+ }
99
+ } finally {
100
+ closeSync(fd);
101
+ }
102
+ }
103
+ }
@@ -0,0 +1,77 @@
1
+ /** Bounded traversal of one trusted producer owner. No recursive discovery or dispatch. */
2
+ import { opendirSync, realpathSync, statSync, type Dir } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { operationArtifactsDir } from "../kernel/project-paths.ts";
5
+ import {
6
+ MAX_OPERATION_MANIFEST_BYTES,
7
+ type OperationArtifactOwner,
8
+ type OperationArtifactRef,
9
+ } from "../kernel/operation-artifact.ts";
10
+ import { readBoundedTextSync } from "../kernel/bounded-read-sync.ts";
11
+ import { artifactHash, privateArtifactDirectory } from "./operation-artifact-io.ts";
12
+ import { openOperationArtifacts } from "./operation-artifacts.ts";
13
+ export function operationArtifactInstance(agentDirectory: string): string {
14
+ const canonical = realpathSync(agentDirectory),
15
+ identity = statSync(canonical, { bigint: true });
16
+ return artifactHash(
17
+ JSON.stringify([canonical, identity.dev.toString(), identity.ino.toString(), identity.birthtimeNs.toString()]),
18
+ );
19
+ }
20
+ export function openOperationArtifactScan(agentDirectory: string, owner: OperationArtifactOwner) {
21
+ const store = openOperationArtifacts(agentDirectory, owner);
22
+ const root = join(
23
+ operationArtifactsDir(realpathSync(agentDirectory)),
24
+ artifactHash(JSON.stringify([owner.sessionId, owner.cwd])),
25
+ );
26
+ let directory: Dir | undefined,
27
+ complete = false;
28
+ try {
29
+ privateArtifactDirectory(root);
30
+ directory = opendirSync(root, { bufferSize: 64 });
31
+ } catch (error) {
32
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
33
+ complete = true;
34
+ }
35
+ const close = () => {
36
+ directory?.closeSync();
37
+ directory = undefined;
38
+ complete = true;
39
+ };
40
+ return {
41
+ close,
42
+ next(limit = 32) {
43
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64) throw Error("invalid artifact scan limit");
44
+ const references: OperationArtifactRef[] = [];
45
+ let scanned = 0,
46
+ uncertain = 0,
47
+ issues = 0;
48
+ while (!complete && scanned < limit) {
49
+ const entry = directory!.readSync();
50
+ if (!entry) {
51
+ close();
52
+ break;
53
+ }
54
+ scanned++;
55
+ try {
56
+ if (!entry.isDirectory() || !/^([a-f0-9]{64})$/.test(entry.name)) throw Error("invalid entry");
57
+ const path = join(root, entry.name);
58
+ privateArtifactDirectory(path);
59
+ const admission = JSON.parse(
60
+ readBoundedTextSync(join(path, "admission.json"), {
61
+ maxBytes: MAX_OPERATION_MANIFEST_BYTES,
62
+ confinedRoot: path,
63
+ }).text,
64
+ );
65
+ const id = admission?.request?.operationId;
66
+ if (typeof id !== "string" || artifactHash(id) !== entry.name) throw Error("invalid identity");
67
+ const retained = store.history(id, false);
68
+ if (retained?.artifact) references.push(retained.artifact);
69
+ else uncertain++;
70
+ } catch {
71
+ issues++;
72
+ }
73
+ }
74
+ return { references, scanned, uncertain, issues, complete };
75
+ },
76
+ };
77
+ }