@sixb/agent 0.2.2 → 0.2.4

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 (105) hide show
  1. package/README.md +2 -2
  2. package/dist/artifacts/board-previews.d.ts +41 -0
  3. package/dist/artifacts/board-previews.d.ts.map +1 -0
  4. package/dist/artifacts/layout-check/layout-check.d.ts +38 -6
  5. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  6. package/dist/artifacts/layout-check/overview.d.ts +17 -0
  7. package/dist/artifacts/layout-check/overview.d.ts.map +1 -0
  8. package/dist/artifacts/materialize.d.ts +56 -24
  9. package/dist/artifacts/materialize.d.ts.map +1 -1
  10. package/dist/artifacts/publish-tool.d.ts +35 -27
  11. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  12. package/dist/ask-tool.d.ts +62 -0
  13. package/dist/ask-tool.d.ts.map +1 -0
  14. package/dist/attachments.d.ts +1 -1
  15. package/dist/attachments.d.ts.map +1 -1
  16. package/dist/background-commands.d.ts +3 -3
  17. package/dist/background-commands.d.ts.map +1 -1
  18. package/dist/background-notices.d.ts.map +1 -1
  19. package/dist/child-files.d.ts +1 -1
  20. package/dist/child-questions.d.ts +1 -1
  21. package/dist/index.d.ts +2 -1
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +12309 -10490
  24. package/dist/index.js.map +41 -35
  25. package/dist/run-agent-turn.d.ts.map +1 -1
  26. package/dist/run-conversation-turn.d.ts.map +1 -1
  27. package/dist/run-environment.d.ts +4 -1
  28. package/dist/run-environment.d.ts.map +1 -1
  29. package/dist/run-subagent.d.ts +1 -1
  30. package/dist/sandbox-files.d.ts +19 -0
  31. package/dist/sandbox-files.d.ts.map +1 -1
  32. package/dist/subagent-tools.d.ts +23 -2
  33. package/dist/subagent-tools.d.ts.map +1 -1
  34. package/dist/tools/background.d.ts +50 -18
  35. package/dist/tools/background.d.ts.map +1 -1
  36. package/dist/tools/bash.d.ts +1 -0
  37. package/dist/tools/bash.d.ts.map +1 -1
  38. package/dist/tools/edit-text.d.ts +22 -0
  39. package/dist/tools/edit-text.d.ts.map +1 -0
  40. package/dist/tools/edit.d.ts +54 -0
  41. package/dist/tools/edit.d.ts.map +1 -0
  42. package/dist/tools/file-writes.d.ts +52 -0
  43. package/dist/tools/file-writes.d.ts.map +1 -0
  44. package/dist/tools/model-spec.d.ts.map +1 -1
  45. package/dist/tools/read.d.ts +16 -3
  46. package/dist/tools/read.d.ts.map +1 -1
  47. package/dist/tools/tool-files.d.ts.map +1 -1
  48. package/dist/tools/view-file.d.ts +20 -23
  49. package/dist/tools/view-file.d.ts.map +1 -1
  50. package/dist/tools/web-fetch/tool.d.ts +1 -0
  51. package/dist/tools/web-fetch/tool.d.ts.map +1 -1
  52. package/dist/tools/web-search.d.ts +1 -0
  53. package/dist/tools/web-search.d.ts.map +1 -1
  54. package/dist/tools/write.d.ts +36 -0
  55. package/dist/tools/write.d.ts.map +1 -0
  56. package/dist/types.d.ts +5 -4
  57. package/dist/types.d.ts.map +1 -1
  58. package/package.json +7 -6
  59. package/src/agent-prompt.ts +10 -10
  60. package/src/artifacts/board-previews.ts +218 -0
  61. package/src/artifacts/layout-check/check.cjs +304 -80
  62. package/src/artifacts/layout-check/layout-check.ts +119 -9
  63. package/src/artifacts/layout-check/overview.ts +291 -0
  64. package/src/artifacts/materialize.ts +181 -55
  65. package/src/artifacts/publish-tool.ts +475 -163
  66. package/src/ask-tool.ts +223 -0
  67. package/src/attachments.ts +7 -6
  68. package/src/background-commands.ts +5 -5
  69. package/src/background-notices.ts +5 -12
  70. package/src/child-files.ts +1 -1
  71. package/src/child-questions.ts +1 -1
  72. package/src/context-compaction.ts +4 -1
  73. package/src/index.ts +2 -1
  74. package/src/run-agent-turn.ts +14 -4
  75. package/src/run-child.ts +1 -1
  76. package/src/run-conversation-turn.ts +4 -1
  77. package/src/run-environment.ts +40 -26
  78. package/src/run-subagent.ts +3 -3
  79. package/src/sandbox-api-context.ts +1 -1
  80. package/src/sandbox-files.ts +86 -0
  81. package/src/skills/sixb-artifacts/SKILL.md +48 -25
  82. package/src/skills/sixb-artifacts/canvas.md +140 -18
  83. package/src/skills/sixb-artifacts/examples/canvas/onboarding-flow/canvas.json +1 -1
  84. package/src/skills/sixb-artifacts/page.md +2 -2
  85. package/src/skills/sixb-artifacts/references.md +15 -12
  86. package/src/skills/sixb-artifacts/sheet.md +1 -1
  87. package/src/skills/sixb-artifacts/slides.md +2 -2
  88. package/src/subagent-tools.ts +134 -88
  89. package/src/tools/background.ts +227 -67
  90. package/src/tools/bash.ts +2 -1
  91. package/src/tools/edit-text.ts +241 -0
  92. package/src/tools/edit.ts +166 -0
  93. package/src/tools/file-writes.ts +270 -0
  94. package/src/tools/model-spec.ts +9 -12
  95. package/src/tools/read.ts +75 -9
  96. package/src/tools/tool-files.ts +3 -1
  97. package/src/tools/tool-outputs.ts +2 -2
  98. package/src/tools/view-file.ts +78 -80
  99. package/src/tools/web-fetch/tool.ts +2 -1
  100. package/src/tools/web-search.ts +1 -0
  101. package/src/tools/write.ts +95 -0
  102. package/src/types.ts +5 -4
  103. package/dist/ask-parent-tool.d.ts +0 -36
  104. package/dist/ask-parent-tool.d.ts.map +0 -1
  105. package/src/ask-parent-tool.ts +0 -100
@@ -2,7 +2,12 @@ import { posix } from "node:path"
2
2
  import type { Sandbox, SandboxFileRecord } from "@sixb/core"
3
3
  import { formatArtifactAddress } from "@sixb/core/artifacts"
4
4
  import type { AgentRunArtifacts, AgentRunFileStore } from "@sixb/core/internal/agents"
5
- import type { ArtifactOutline, ArtifactRecord, ArtifactVersionRecord } from "@sixb/core/storage"
5
+ import type {
6
+ ArtifactFile,
7
+ ArtifactOutline,
8
+ ArtifactRecord,
9
+ ArtifactVersionRecord,
10
+ } from "@sixb/core/storage"
6
11
  import { NEVER_ABORTED_SIGNAL, waitForAbort } from "../abort"
7
12
 
8
13
  /** How many of the thread's artifacts are installed, newest first, and how many bytes in all. */
@@ -27,42 +32,60 @@ interface ManifestEntry {
27
32
  readonly kind: string
28
33
  readonly title: string
29
34
  readonly version: number
35
+ /** The artifact's revision this copy holds: an update made from it starts from there. */
36
+ readonly revision: number
37
+ /**
38
+ * The version is open: each update replaces it until the user creates a version. A frozen one
39
+ * never changes, and the next update opens the next version.
40
+ */
41
+ readonly open: boolean
30
42
  /** The artifact's address: an artifact that shows it follows its latest version. */
31
43
  readonly address: string
32
- /** The same at this version, which never changes: a reply shows what its words describe. */
33
- readonly pinned: string
44
+ /**
45
+ * The same at this version, once the user created it, which then never changes: a reply shows
46
+ * what its words describe. None while the version is open.
47
+ */
48
+ readonly pinned?: string
34
49
  /**
35
50
  * Addresses of its parts: a document's sections, a sheet's sheets and charts, a deck's slides, a
36
51
  * canvas's boards and sections.
37
52
  */
38
53
  readonly parts?: readonly {
39
54
  readonly address: string
40
- readonly pinned: string
55
+ readonly pinned?: string
41
56
  readonly name: string
42
57
  }[]
43
58
  /** Where the version's files are, as the agent names it; absent when not installed. */
44
59
  readonly directory?: string
45
60
  readonly files: readonly string[]
46
61
  /**
47
- * The latest version was published outside this conversation: a person's edit in the app,
48
- * another conversation, or the project's code. The next version starts from it and keeps its
49
- * changes.
62
+ * The latest version was last written outside this conversation: a person's edit in the app,
63
+ * another conversation, or the project's code. An update starts from it and keeps its changes.
50
64
  */
51
65
  readonly edited?: true
66
+ /** The requester reads it, through an object that holds it, and cannot change it. */
67
+ readonly readOnly?: true
52
68
  }
53
69
 
54
70
  /**
55
71
  * The conversation's artifacts as the run's sandbox holds them: the latest version of each under
56
72
  * `<directory>/<id>/`, listed in the manifest, newest first. A publish replaces its artifact's copy
57
- * and entry, so both stay the latest version for the rest of the run: revising from the copy never
58
- * starts from the version before. A publish refused because the artifact moved on installs the
59
- * version it moved to.
73
+ * and entry, so both stay at the latest revision for the rest of the run: revising from the copy
74
+ * never starts from what the artifact held before. A publish refused because the artifact moved
75
+ * on installs what it moved to.
60
76
  */
61
77
  export class InstalledArtifacts implements MaterializedArtifacts {
62
78
  #entries: readonly ManifestEntry[]
63
79
  /** The installed copies' sizes, by artifact id. */
64
80
  readonly #installed: Map<string, number>
65
- #updates: Promise<void> = Promise.resolve()
81
+ /** The files of the revision each entry lists, by artifact id: what an update starts from. */
82
+ readonly #bases = new Map<string, readonly ArtifactFile[]>()
83
+ /**
84
+ * The folder the Agent last published each artifact from, in the sandbox: it holds what the
85
+ * installed copy holds, so its next update, from there, starts from the base.
86
+ */
87
+ readonly #folders = new Map<string, { readonly path: string; readonly absolute: string }>()
88
+ #updates: Promise<unknown> = Promise.resolve()
66
89
 
67
90
  constructor(
68
91
  private readonly layout: {
@@ -73,32 +96,65 @@ export class InstalledArtifacts implements MaterializedArtifacts {
73
96
  },
74
97
  entries: readonly ManifestEntry[],
75
98
  installed: Map<string, number>,
76
- readonly files: readonly SandboxFileRecord[]
99
+ readonly files: readonly SandboxFileRecord[],
100
+ bases: ReadonlyMap<string, readonly ArtifactFile[]> = new Map()
77
101
  ) {
78
102
  this.#entries = entries
79
103
  this.#installed = installed
104
+ for (const [id, base] of bases) this.#bases.set(id, base)
80
105
  }
81
106
 
82
107
  get manifestJson(): string {
83
- return JSON.stringify({ artifacts: this.#entries }, null, 2)
108
+ return manifestJson(this.#entries)
84
109
  }
85
110
 
86
- /** The version the manifest lists for an artifact: the one its copy holds. */
87
- versionOf(artifactId: string): number | undefined {
88
- return this.#entries.find((entry) => entry.id === artifactId)?.version
111
+ /** The revision the manifest lists for an artifact: the one its copy holds. */
112
+ revisionOf(artifactId: string): number | undefined {
113
+ return this.#entries.find((entry) => entry.id === artifactId)?.revision
114
+ }
115
+
116
+ /** Whether the artifact was installed for the requester to read only. */
117
+ readOnly(artifactId: string): boolean {
118
+ return this.#entries.find((entry) => entry.id === artifactId)?.readOnly === true
119
+ }
120
+
121
+ /** Where an artifact's copy is installed, as the agent names it; none when it is not. */
122
+ directoryOf(artifactId: string): string | undefined {
123
+ return this.#entries.find((entry) => entry.id === artifactId)?.directory
89
124
  }
90
125
 
91
126
  /**
92
- * Install the version just published in place of the artifact's copy, and list it first. One
93
- * update runs at a time, so parallel publishes never write an older manifest over a newer one.
127
+ * The revision an update of an artifact starts from, and its files: those of the copy, which a
128
+ * canvas's update is merged from when others wrote it since.
129
+ */
130
+ baseOf(
131
+ artifactId: string
132
+ ): { readonly revision: number; readonly files: readonly ArtifactFile[] } | undefined {
133
+ const revision = this.revisionOf(artifactId)
134
+ const files = this.#bases.get(artifactId)
135
+ return revision === undefined || !files ? undefined : { revision, files }
136
+ }
137
+
138
+ /** Records the folder the Agent published an artifact from: `path` as it named it. */
139
+ publishedFrom(artifactId: string, folder: { readonly path: string; readonly absolute: string }) {
140
+ this.#folders.set(artifactId, folder)
141
+ }
142
+
143
+ /**
144
+ * Install a revision in place of the artifact's copy, and list it first: the copy, the base of
145
+ * the next update, and the folder the Agent last published it from move together, so an update
146
+ * from that folder never takes out what someone else wrote. One that fails to write them keeps
147
+ * the base as it was, and rejects. One update runs at a time, so
148
+ * parallel publishes never write an older manifest over a newer one. Resolves to the folder it
149
+ * wrote, as the Agent named it, if any.
94
150
  */
95
151
  replace(
96
152
  sandbox: Sandbox,
97
153
  published: { readonly artifact: ArtifactRecord; readonly version: ArtifactVersionRecord },
98
154
  files: readonly PublishedArtifactFile[],
99
155
  signal: AbortSignal,
100
- options: { readonly edited?: boolean } = {}
101
- ): Promise<void> {
156
+ options: { readonly edited?: boolean; readonly readOnly?: boolean } = {}
157
+ ): Promise<string | undefined> {
102
158
  const update = this.#updates.then(() =>
103
159
  this.#replace(sandbox, published, files, signal, options)
104
160
  )
@@ -114,8 +170,8 @@ export class InstalledArtifacts implements MaterializedArtifacts {
114
170
  }: { readonly artifact: ArtifactRecord; readonly version: ArtifactVersionRecord },
115
171
  files: readonly PublishedArtifactFile[],
116
172
  signal: AbortSignal,
117
- options: { readonly edited?: boolean }
118
- ): Promise<void> {
173
+ options: { readonly edited?: boolean; readonly readOnly?: boolean }
174
+ ): Promise<string | undefined> {
119
175
  const { directory: root, manifestPath, maxBytes } = this.layout
120
176
  const directory = posix.join(root, artifact.id)
121
177
  const inSandbox = (path: string) => posix.resolve(sandbox.workingDirectory, path)
@@ -124,7 +180,7 @@ export class InstalledArtifacts implements MaterializedArtifacts {
124
180
  for (const [id, bytes] of this.#installed) if (id !== artifact.id) othersBytes += bytes
125
181
  const install = othersBytes + sizeBytes <= maxBytes
126
182
 
127
- // A version's directory holds exactly that version: files an older one had must not linger.
183
+ // An artifact's directory holds exactly one revision: files an older one had must not linger.
128
184
  const removed = await sandbox.runCommand("bash", ["-c", 'rm -rf -- "$SIXB_ARTIFACT_COPY"'], {
129
185
  env: { SIXB_ARTIFACT_COPY: inSandbox(directory) },
130
186
  timeout: REMOVE_TIMEOUT_MS,
@@ -135,9 +191,10 @@ export class InstalledArtifacts implements MaterializedArtifacts {
135
191
  `[SixbAgent] Could not remove ${directory}: ${removed.stderr.trim() || `exit ${removed.exitCode}`}`
136
192
  )
137
193
  }
138
- if (install) this.#installed.set(artifact.id, sizeBytes)
139
- else this.#installed.delete(artifact.id)
140
- this.#entries = [
194
+ // The copy, the folder and the base move together: until both are written, the next update
195
+ // starts from the revision before, which the folder still holds.
196
+ const previous = this.#bases.get(artifact.id) ?? []
197
+ const entries = [
141
198
  manifestEntry(artifact, version, install ? directory : undefined, options),
142
199
  ...this.#entries.filter((entry) => entry.id !== artifact.id),
143
200
  ]
@@ -148,13 +205,58 @@ export class InstalledArtifacts implements MaterializedArtifacts {
148
205
  contents: file.bytes,
149
206
  }))
150
207
  : []),
151
- { path: inSandbox(manifestPath), contents: this.manifestJson },
208
+ { path: inSandbox(manifestPath), contents: manifestJson(entries) },
152
209
  ])
210
+
211
+ const moved = await this.#writeFolder(sandbox, artifact.id, previous, files, signal)
212
+
213
+ if (install) this.#installed.set(artifact.id, sizeBytes)
214
+ else this.#installed.delete(artifact.id)
215
+ this.#bases.set(artifact.id, version.files)
216
+ this.#entries = entries
217
+ return moved
218
+ }
219
+
220
+ /**
221
+ * The folder the Agent last published an artifact from takes a revision too: each file as it
222
+ * holds it, and none of the files the revision before held that it does not. Resolves to the
223
+ * folder, as the Agent named it, if any.
224
+ */
225
+ async #writeFolder(
226
+ sandbox: Sandbox,
227
+ artifactId: string,
228
+ previous: readonly ArtifactFile[],
229
+ files: readonly PublishedArtifactFile[],
230
+ signal: AbortSignal
231
+ ): Promise<string | undefined> {
232
+ const folder = this.#folders.get(artifactId)
233
+ if (!folder) return undefined
234
+
235
+ const kept = new Set(files.map((file) => file.path))
236
+ const gone = previous
237
+ .filter((file) => !kept.has(file.path))
238
+ .map((file) => posix.join(folder.absolute, file.path))
239
+ if (gone.length > 0) {
240
+ const removedFiles = await sandbox.runCommand(
241
+ "bash",
242
+ ["-c", 'rm -f -- "$@"', "rm", ...gone],
243
+ { timeout: REMOVE_TIMEOUT_MS, signal }
244
+ )
245
+ if (removedFiles.exitCode !== 0 || removedFiles.timedOut) {
246
+ throw new Error(
247
+ `[SixbAgent] Could not update ${folder.path}: ${removedFiles.stderr.trim() || `exit ${removedFiles.exitCode}`}`
248
+ )
249
+ }
250
+ }
251
+ await sandbox.writeFiles(
252
+ files.map((file) => ({ path: posix.join(folder.absolute, file.path), contents: file.bytes }))
253
+ )
254
+ return folder.path
153
255
  }
154
256
  }
155
257
 
156
258
  /** What a turn reads of its conversation's artifacts, as its requester, through its session. */
157
- export type TurnArtifacts = Pick<AgentRunArtifacts, "getVersion" | "list" | "listVersions">
259
+ export type TurnArtifacts = Pick<AgentRunArtifacts, "getVersion" | "list" | "turnWrites">
158
260
 
159
261
  /**
160
262
  * The latest version of each artifact the conversation shares, installed under `<directory>/<id>/`
@@ -182,6 +284,7 @@ export async function materializeThreadArtifacts(input: {
182
284
  const entries: ManifestEntry[] = []
183
285
  const files: SandboxFileRecord[] = []
184
286
  const installed = new Map<string, number>()
287
+ const bases = new Map<string, readonly ArtifactFile[]>()
185
288
  const artifacts = await input.artifacts.list({ limit: MATERIALIZE_MAX_ARTIFACTS })
186
289
  let installedBytes = 0
187
290
  for (const artifact of artifacts) {
@@ -207,12 +310,14 @@ export async function materializeThreadArtifacts(input: {
207
310
  signal.throwIfAborted()
208
311
  // One unreadable blob must not cost every later run of the thread its sandbox.
209
312
  console.warn(
210
- `[SixbAgent] Could not install version ${version.version} of artifact '${artifact.id}':`,
313
+ `[SixbAgent] Could not install revision ${version.revision} of artifact '${artifact.id}':`,
211
314
  error
212
315
  )
213
316
  install = false
214
317
  }
215
318
  }
319
+ bases.set(artifact.id, version.files)
320
+ // Edited when its last write came from anywhere but this conversation.
216
321
  entries.push(
217
322
  manifestEntry(artifact, version, install ? directory : undefined, {
218
323
  edited: version.origin?.threadId !== input.threadId,
@@ -223,46 +328,49 @@ export async function materializeThreadArtifacts(input: {
223
328
  { directory: input.directory, manifestPath: input.manifestPath, maxBytes },
224
329
  entries,
225
330
  installed,
226
- files
331
+ files,
332
+ bases
227
333
  )
228
334
  }
229
335
 
230
336
  /**
231
- * Install the latest version of each thread artifact one of `runIds` published a version of, in
232
- * place of the copy the run holds: a parent turn sees what its children published like its own,
233
- * whoever published since. One that cannot be installed does not stop the others; the error at the
234
- * end names each.
337
+ * Install the latest revision of each thread artifact the run's turn wrote, its children's writes
338
+ * among them, in place of the copy the run holds when it holds another: a parent turn sees what
339
+ * its children wrote like its own, whoever wrote since. One that cannot be installed does not stop
340
+ * the others; the error at the end names each.
235
341
  */
236
- export async function installArtifactsPublishedBy(input: {
342
+ export async function installTurnArtifacts(input: {
237
343
  readonly installed: InstalledArtifacts
238
344
  readonly artifacts: TurnArtifacts
239
345
  readonly blobStorage: AgentRunFileStore
240
346
  readonly sandbox: Sandbox
241
- readonly runIds: readonly string[]
242
347
  readonly signal: AbortSignal
243
- }): Promise<void> {
244
- const runIds = new Set(input.runIds)
245
- const artifacts = await input.artifacts.list({ limit: MATERIALIZE_MAX_ARTIFACTS })
348
+ }): Promise<string[]> {
349
+ const [writes, artifacts] = await Promise.all([
350
+ input.artifacts.turnWrites(),
351
+ input.artifacts.list({ limit: MATERIALIZE_MAX_ARTIFACTS }),
352
+ ])
353
+ const written = new Set(writes.map((write) => write.artifactId))
246
354
 
247
355
  const failed: string[] = []
356
+ const folders: string[] = []
248
357
  // Oldest first: each install lists its artifact first, so the newest ends up first.
249
358
  for (const artifact of [...artifacts].reverse()) {
250
359
  input.signal.throwIfAborted()
251
- if (input.installed.versionOf(artifact.id) === artifact.latestVersion) continue
360
+ if (!written.has(artifact.id)) continue
361
+ if (input.installed.revisionOf(artifact.id) === artifact.revision) continue
252
362
 
253
363
  try {
254
- const versions = await input.artifacts.listVersions(artifact.id, {
255
- limit: artifact.latestVersion,
256
- })
257
- const published = versions?.versions.some(
258
- (version) => version.origin !== undefined && runIds.has(version.origin.runId)
259
- )
260
- if (!published) continue
261
-
262
364
  const version = await input.artifacts.getVersion(artifact.id, artifact.latestVersion)
263
365
  if (!version) continue
264
366
  const files = await readArtifactVersionFiles(input.blobStorage, version, input.signal)
265
- await input.installed.replace(input.sandbox, { artifact, version }, files, input.signal)
367
+ const folder = await input.installed.replace(
368
+ input.sandbox,
369
+ { artifact, version },
370
+ files,
371
+ input.signal
372
+ )
373
+ if (folder) folders.push(folder)
266
374
  } catch (error) {
267
375
  input.signal.throwIfAborted()
268
376
  console.warn(`[SixbAgent] Could not install artifact '${artifact.id}':`, error)
@@ -272,40 +380,58 @@ export async function installArtifactsPublishedBy(input: {
272
380
  if (failed.length > 0) {
273
381
  throw new Error(`[SixbAgent] Could not install artifacts ${failed.join(", ")}.`)
274
382
  }
383
+ return folders
384
+ }
385
+
386
+ /** The manifest the sandbox reads, listing these entries. */
387
+ function manifestJson(entries: readonly ManifestEntry[]): string {
388
+ return JSON.stringify({ artifacts: entries }, null, 2)
275
389
  }
276
390
 
277
391
  function manifestEntry(
278
392
  artifact: Pick<ArtifactRecord, "id" | "kind">,
279
393
  version: ArtifactVersionRecord,
280
394
  directory: string | undefined,
281
- { edited = false }: { readonly edited?: boolean } = {}
395
+ {
396
+ edited = false,
397
+ readOnly = false,
398
+ }: { readonly edited?: boolean; readonly readOnly?: boolean } = {}
282
399
  ): ManifestEntry {
400
+ // Only a frozen version is pinned: an open one changes with every update.
401
+ const pinnedAt = version.frozenAt ? version.version : undefined
283
402
  return {
284
403
  id: artifact.id,
285
404
  kind: artifact.kind,
286
405
  title: version.title,
287
406
  version: version.version,
407
+ revision: version.revision,
408
+ open: version.frozenAt === undefined,
288
409
  address: formatArtifactAddress({ artifactId: artifact.id }),
289
- pinned: formatArtifactAddress({ artifactId: artifact.id, version: version.version }),
290
- ...partsOf(artifact.id, version.version, version.outline),
410
+ ...(pinnedAt === undefined
411
+ ? {}
412
+ : { pinned: formatArtifactAddress({ artifactId: artifact.id, version: pinnedAt }) }),
413
+ ...partsOf(artifact.id, pinnedAt, version.outline),
291
414
  ...(directory === undefined ? {} : { directory }),
292
415
  files: version.files.map((file) => file.path),
293
416
  ...(edited ? { edited: true as const } : {}),
417
+ ...(readOnly ? { readOnly: true as const } : {}),
294
418
  }
295
419
  }
296
420
 
297
421
  /**
298
422
  * The parts an address can name, each with its address written out, so the Agent copies an
299
- * address instead of working out a heading's slug.
423
+ * address instead of working out a heading's slug; pinned too in a frozen version.
300
424
  */
301
425
  function partsOf(
302
426
  artifactId: string,
303
- version: number,
427
+ pinnedAt: number | undefined,
304
428
  outline: ArtifactOutline
305
429
  ): { readonly parts?: ManifestEntry["parts"] } {
306
430
  const part = (name: string, label: string) => ({
307
431
  address: formatArtifactAddress({ artifactId, part: name }),
308
- pinned: formatArtifactAddress({ artifactId, version, part: name }),
432
+ ...(pinnedAt === undefined
433
+ ? {}
434
+ : { pinned: formatArtifactAddress({ artifactId, version: pinnedAt, part: name }) }),
309
435
  name: label,
310
436
  })
311
437
  const parts =