@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
@@ -4,24 +4,31 @@ import {
4
4
  AgentToolPublicError,
5
5
  type ArtifactKind,
6
6
  ArtifactRequestError,
7
- AuthorizationError,
8
7
  type JsonValue,
9
- ObjectQueryExecutionError,
10
8
  type Principal,
11
9
  principalsEqual,
12
10
  } from "@sixb/core"
13
- import { ARTIFACT_KINDS, ARTIFACT_THEME_FILE, parseArtifactTheme } from "@sixb/core/artifacts"
11
+ import {
12
+ ARTIFACT_KINDS,
13
+ ARTIFACT_THEME_FILE,
14
+ CANVAS_FILE,
15
+ type Canvas,
16
+ parseArtifactTheme,
17
+ parseCanvas,
18
+ } from "@sixb/core/artifacts"
14
19
  import {
15
20
  AgentExecutionLostError,
16
21
  type AgentRunArtifacts,
17
22
  type AgentRunFileStore,
23
+ type AgentRunMissingPreview,
18
24
  } from "@sixb/core/internal/agents"
19
- import { frameLayout, serializeArtifactQueryResult } from "@sixb/core/internal/artifacts/frames"
25
+ import { frameLayout } from "@sixb/core/internal/artifacts/frames"
20
26
  import {
21
27
  ARTIFACT_LIMITS,
22
- artifactQueryName,
28
+ answerArtifactQueries,
23
29
  isArtifactId,
24
30
  type PublishedArtifact,
31
+ type RefusedBoardPreview,
25
32
  } from "@sixb/core/internal/artifacts/publish"
26
33
  import { inferFileMediaType } from "@sixb/core/internal/blob-storage"
27
34
  import type { JsonObject, ModelTool } from "@sixb/core/models"
@@ -35,7 +42,9 @@ import {
35
42
  } from "../sandbox-files"
36
43
  import type { AgentSandboxHandle } from "../sandbox-handle"
37
44
  import type { AgentFileBudget } from "../tools/tool-files"
45
+ import { storeCheckedPreviews } from "./board-previews"
38
46
  import {
47
+ type CheckedPreview,
39
48
  type CheckedQuery,
40
49
  checkLayout,
41
50
  type LayoutCheck,
@@ -48,17 +57,17 @@ import {
48
57
  } from "./materialize"
49
58
 
50
59
  const CREATE_TOOL = "publish_artifact"
51
- const VERSION_TOOL = "publish_artifact_version"
52
- type PublishToolName = typeof CREATE_TOOL | typeof VERSION_TOOL
60
+ const OPEN_TOOL = "open_artifact"
61
+ type ArtifactToolName = typeof CREATE_TOOL | typeof OPEN_TOOL
53
62
  const SANDBOX_TIMEOUT_MS = 30_000
54
63
  /** The kinds the Agent can create today; each lands with its validator, renderer, and skill. */
55
64
  const PUBLISHABLE_KINDS = ARTIFACT_KINDS
56
65
  type PublishableKind = ArtifactKind
57
66
 
58
- // Creating and revising are two tools, and every argument of each is required and meaningful. A
59
- // mode carried by an optional or null argument is where models differ: some fill every field, some
60
- // send "null" or "" for nothing. Every model picks a tool by name. With all properties required
61
- // and no length or pattern keywords, every model adapter can also send both schemas as strict.
67
+ // One tool creates and revises: `kind` names a new artifact's, `id` the artifact to revise, whose
68
+ // kind stays, so a kind sent with an id is ignored. Every adapter sends the optional fields as it
69
+ // can (strict where it may), and an empty id or "null", which a model sends for nothing, is no id:
70
+ // ids start `art_`.
62
71
  const PATH_PROPERTY = {
63
72
  type: "string",
64
73
  description: "A file or a directory in the sandbox, relative to the working directory.",
@@ -70,46 +79,52 @@ const TITLE_PROPERTY = {
70
79
 
71
80
  export const PUBLISH_ARTIFACT_TOOL_SPEC = {
72
81
  name: CREATE_TOOL,
73
- description:
74
- "Publish a new artifact from a file or directory in the sandbox: a deliverable the user opens beside the conversation. Read the sixb-artifacts skill before the first publish. To change an artifact you already published, use publish_artifact_version. Returns the artifact's id and version; a refusal says what to fix.",
82
+ strict: true,
83
+ description: [
84
+ "Publish a file or directory in the sandbox as an artifact: a deliverable the user opens beside the conversation. Read the sixb-artifacts skill before the first publish.",
85
+ "Pass kind for a new artifact. Pass id to update one of this conversation's, or one an object the user may edit holds: your files replace its current version's, which stays open, and its kind stays; versions the user created stay as they are. $SIXB_ARTIFACTS lists this conversation's artifacts, each with its current version under $SIXB_ARTIFACTS_DIR/<id>/; open one it does not list with open_artifact first.",
86
+ "Returns the artifact's id, version and revision; a refusal says what to fix.",
87
+ ].join("\n"),
75
88
  inputSchema: {
76
89
  type: "object",
77
90
  properties: {
78
91
  path: PATH_PROPERTY,
79
- kind: { type: "string", enum: [...PUBLISHABLE_KINDS] },
80
92
  title: TITLE_PROPERTY,
93
+ kind: {
94
+ type: "string",
95
+ enum: [...PUBLISHABLE_KINDS],
96
+ description: "A new artifact's kind. With an id it is ignored: an update keeps its kind.",
97
+ },
98
+ id: {
99
+ type: "string",
100
+ description: "The artifact to update, such as art_k3m9q2x7tp. Leave it out to create one.",
101
+ },
81
102
  },
82
- required: ["path", "kind", "title"],
103
+ required: ["path", "title"],
83
104
  additionalProperties: false,
84
105
  } satisfies JsonObject,
85
106
  } as const
86
107
 
87
- export const PUBLISH_ARTIFACT_VERSION_TOOL_SPEC = {
88
- name: VERSION_TOOL,
108
+ export const OPEN_ARTIFACT_TOOL_SPEC = {
109
+ name: OPEN_TOOL,
110
+ strict: true,
89
111
  description:
90
- "Publish the next version of an artifact you published, from a file or directory in the sandbox. It keeps its kind, and its earlier versions stay readable. $SIXB_ARTIFACTS lists this conversation's artifacts, each with its latest version under $SIXB_ARTIFACTS_DIR/<id>/. Returns the new version; a refusal says what to fix.",
112
+ "Open an artifact $SIXB_ARTIFACTS does not list, such as one a project object holds: its current version is installed under $SIXB_ARTIFACTS_DIR/<id>/ and listed in $SIXB_ARTIFACTS, to read it, or to revise it with publish_artifact and its id when the user may change it. Publishes nothing. Returns its title, revision, and whether the user may only read it.",
91
113
  inputSchema: {
92
114
  type: "object",
93
115
  properties: {
94
116
  id: { type: "string", description: "The artifact's id, such as art_k3m9q2x7tp." },
95
- path: PATH_PROPERTY,
96
- title: TITLE_PROPERTY,
97
117
  },
98
- required: ["id", "path", "title"],
118
+ required: ["id"],
99
119
  additionalProperties: false,
100
120
  } satisfies JsonObject,
101
121
  } as const
102
122
 
103
- export interface PublishArtifactToolInput {
104
- readonly path: string
105
- readonly kind: PublishableKind
106
- readonly title: string
107
- }
123
+ /** A publish: of a new artifact by its kind, or of an artifact's current version by its id. */
124
+ export type PublishArtifactToolInput = PublishRequest
108
125
 
109
- export interface PublishArtifactVersionToolInput {
126
+ export interface OpenArtifactToolInput {
110
127
  readonly id: string
111
- readonly path: string
112
- readonly title: string
113
128
  }
114
129
 
115
130
  interface PublishToolsInput {
@@ -128,36 +143,38 @@ interface PublishToolsInput {
128
143
  }
129
144
 
130
145
  /**
131
- * `publish_artifact` and `publish_artifact_version`: each reads a file or a directory from the
132
- * sandbox, stores its bytes, and publishes them through the run's session, which applies a run's
133
- * rules (see `AgentRunArtifacts.publish`). The version exists when the tool returns, so the
146
+ * `publish_artifact` reads a file or a directory from the sandbox, stores its bytes, and publishes
147
+ * them through the run's session, which applies a run's rules (see `AgentRunArtifacts.publish`):
148
+ * a new artifact of its kind, or, by id, the open version's content replaced, or the next version
149
+ * opened after one the user created. What it wrote exists when the tool returns, so the
134
150
  * conversation shows it mid-turn and a cancelled run keeps it.
151
+ *
152
+ * `open_artifact` installs one the conversation does not list, as the requester reads it, so an
153
+ * update starts from what it holds.
135
154
  */
136
155
  export function createPublishArtifactTools(
137
156
  input: PublishToolsInput
138
- ): readonly [ModelTool<PublishArtifactToolInput>, ModelTool<PublishArtifactVersionToolInput>] {
157
+ ): readonly [ModelTool<PublishArtifactToolInput>, ModelTool<OpenArtifactToolInput>] {
139
158
  return [
140
159
  {
141
160
  ...PUBLISH_ARTIFACT_TOOL_SPEC,
142
161
  parseInput: parsePublishArtifactInput,
143
- execute: (request, { signal }) =>
144
- publish(input, CREATE_TOOL, { ...request, target: { kind: request.kind } }, signal),
145
- toModelOutput: (output) => ({ type: "text", value: publishSummary(output, CREATE_TOOL) }),
162
+ execute: (request, { signal }) => publish(input, request, signal),
163
+ toModelOutput: (output) => ({ type: "text", value: publishSummary(output) }),
146
164
  errorText: (error) => publishErrorText(error, CREATE_TOOL),
147
165
  },
148
166
  {
149
- ...PUBLISH_ARTIFACT_VERSION_TOOL_SPEC,
150
- parseInput: parsePublishArtifactVersionInput,
151
- execute: (request, { signal }) =>
152
- publish(input, VERSION_TOOL, { ...request, target: { artifactId: request.id } }, signal),
153
- toModelOutput: (output) => ({ type: "text", value: publishSummary(output, VERSION_TOOL) }),
154
- errorText: (error) => publishErrorText(error, VERSION_TOOL),
167
+ ...OPEN_ARTIFACT_TOOL_SPEC,
168
+ parseInput: parseOpenArtifactInput,
169
+ execute: (request, { signal }) => open(input, request.id, signal),
170
+ toModelOutput: (output) => ({ type: "text", value: openSummary(output) }),
171
+ errorText: (error) => publishErrorText(error, OPEN_TOOL),
155
172
  },
156
173
  ]
157
174
  }
158
175
 
159
176
  /** A run that lost its conversation stores nothing, and the trace says so instead of "an error". */
160
- function publishErrorText(error: unknown, tool: PublishToolName): string {
177
+ function publishErrorText(error: unknown, tool: ArtifactToolName): string {
161
178
  return error instanceof AgentExecutionLostError
162
179
  ? publishError(tool, "this run no longer holds its conversation, so nothing was published")
163
180
  .message
@@ -167,29 +184,48 @@ function publishErrorText(error: unknown, tool: PublishToolName): string {
167
184
  interface PublishRequest {
168
185
  readonly path: string
169
186
  readonly title: string
170
- /** A new artifact of this kind, or the next version of this artifact. */
187
+ /** A new artifact of this kind, or this artifact's latest version. */
171
188
  readonly target: { readonly kind: PublishableKind } | { readonly artifactId: string }
172
189
  }
173
190
 
174
191
  async function publish(
175
192
  input: PublishToolsInput,
176
- tool: PublishToolName,
177
193
  request: PublishRequest,
178
194
  signal: AbortSignal
179
195
  ): Promise<JsonValue> {
196
+ const tool = CREATE_TOOL
180
197
  signal.throwIfAborted()
198
+ const installed = await input.installed
199
+
200
+ // One the conversation does not list, such as an artifact an object holds, is opened first: the
201
+ // Agent revises what it holds instead of writing over it unseen.
202
+ if (
203
+ "artifactId" in request.target &&
204
+ installed.revisionOf(request.target.artifactId) === undefined
205
+ ) {
206
+ const { artifactId } = request.target
207
+ if (!(await input.artifacts.get(artifactId))) throw noArtifact(tool, artifactId)
208
+
209
+ throw publishError(
210
+ tool,
211
+ `artifact '${artifactId}' is not open in this conversation, so nothing was published: call ${OPEN_TOOL} with its id, then revise its copy and publish it with its id`
212
+ )
213
+ }
214
+
181
215
  const kind: ArtifactKind =
182
216
  "kind" in request.target
183
217
  ? request.target.kind
184
- : (await updatableArtifact(input, request.target.artifactId, tool)).kind
218
+ : (await updatableArtifact(input, request.target.artifactId, tool, installed)).kind
219
+
185
220
  const handle = await input.resolveSandbox()
186
221
  const sources = await listSources(handle, request.path, kind, tool, signal)
187
222
 
188
- // A version of an installed artifact is made from its copy: publishing past the version the copy
189
- // holds would drop whatever was published since.
190
- const installed = await input.installed
191
- const baseVersion =
192
- "artifactId" in request.target ? installed.versionOf(request.target.artifactId) : undefined
223
+ // An installed artifact is updated from its copy: writing past the revision the copy holds would
224
+ // drop whatever was written since. A canvas is merged instead, from the copy's files.
225
+ const base =
226
+ "artifactId" in request.target ? installed.baseOf(request.target.artifactId) : undefined
227
+ const baseRevision =
228
+ "artifactId" in request.target ? installed.revisionOf(request.target.artifactId) : undefined
193
229
 
194
230
  const totalBytes = sources.reduce((sum, source) => sum + source.sizeBytes, 0)
195
231
  if (totalBytes > ARTIFACT_LIMITS.maxVersionBytes) {
@@ -217,8 +253,8 @@ async function publish(
217
253
  if (bytes.byteLength !== source.sizeBytes) {
218
254
  throw publishError(tool, `'${source.path}' changed while it was being read; publish again`)
219
255
  }
220
- // Blob storage keeps identical bytes once, so a file the run already stored, such as one a
221
- // next version keeps, costs the budget nothing again.
256
+ // Blob storage keeps identical bytes once, so a file the run already stored, such as one an
257
+ // update keeps, costs the budget nothing again.
222
258
  reservation.addContent(createHash("sha256").update(bytes).digest("hex"), bytes.byteLength)
223
259
  const fileName = posix.basename(source.path)
224
260
  const fileRef = await input.blobStorage.put({
@@ -237,11 +273,14 @@ async function publish(
237
273
  ...("artifactId" in request.target
238
274
  ? {
239
275
  artifactId: request.target.artifactId,
240
- ...(baseVersion === undefined ? {} : { baseVersion }),
276
+ ...(baseRevision === undefined ? {} : { baseRevision }),
277
+ ...(base ? { baseFiles: base.files } : {}),
241
278
  }
242
279
  : { kind }),
243
280
  title: request.title,
244
281
  files,
282
+ // The layout check pictures a canvas's boards as it checks them.
283
+ rendersPreviews: kind === "canvas",
245
284
  })
246
285
  } catch (error) {
247
286
  // Nothing was published, so the bytes do not count against the run.
@@ -251,12 +290,12 @@ async function publish(
251
290
  error instanceof ArtifactRequestError &&
252
291
  error.code === "artifact_moved" &&
253
292
  "artifactId" in request.target &&
254
- baseVersion !== undefined
293
+ baseRevision !== undefined
255
294
  ) {
256
295
  throw await artifactMoved(
257
296
  input,
258
297
  { installed, handle },
259
- { artifactId: request.target.artifactId, baseVersion },
298
+ { artifactId: request.target.artifactId, baseRevision },
260
299
  signal
261
300
  )
262
301
  }
@@ -272,27 +311,52 @@ async function publish(
272
311
  throw toPublishError(error, tool)
273
312
  }
274
313
 
275
- // The version exists by now: nothing below may read as a failed publish, which the Agent would
314
+ // The write exists by now: nothing below may read as a failed publish, which the Agent would
276
315
  // publish again.
277
- try {
278
- // Revising from $SIXB_ARTIFACTS_DIR must start from this version, not the one before.
279
- await installed.replace(handle.sandbox, published, contents, signal)
280
- } catch (error) {
281
- if (signal.aborted) throw error
282
- console.warn(
283
- `[SixbAgent] Could not install version ${published.version.version} of artifact '${published.artifact.id}':`,
284
- error
285
- )
316
+ const { artifact, version } = published
317
+ // Merged with what others wrote since, the version holds more than the Agent's files: the copy
318
+ // and the check take what it holds.
319
+ const written = published.merged ? await mergedFiles(input, published, signal) : contents
320
+ // The folder the Agent published from moves with the installed copy from now on: after a merge
321
+ // it takes the merged result, and its next update, from there, holds its own changes alone.
322
+ const folder = publishedFolder(handle, request.path, sources)
323
+ if (folder) installed.publishedFrom(artifact.id, folder)
324
+ // Revising from $SIXB_ARTIFACTS_DIR must start from this revision, not the one before. When the
325
+ // merged result cannot be read or installed, the copy, the folder and the base all stay as they
326
+ // were: the next update is merged from that base, and keeps what others wrote.
327
+ let copy: string | undefined
328
+ let installedRevision = written !== undefined
329
+ if (written) {
330
+ try {
331
+ await installed.replace(handle.sandbox, published, written, signal)
332
+ copy = installed.directoryOf(artifact.id)
333
+ } catch (error) {
334
+ if (signal.aborted) throw error
335
+ installedRevision = false
336
+ console.warn(
337
+ `[SixbAgent] Could not install revision ${version.revision} of artifact '${artifact.id}':`,
338
+ error
339
+ )
340
+ }
286
341
  }
287
342
  // A published deck, page, or canvas is laid out in the sandbox's browser, so the Agent sees what
288
- // the reader will, and fixes it in its next version.
343
+ // the reader will, and fixes it in its next update.
289
344
  const layout = frameLayout(kind)
290
- const { outline, entry } = published.version
345
+ const { outline, entry } = version
291
346
  const root = layout ? sources.find((source) => source.path === entry) : undefined
292
- const bytesOf = (path: string) => contents.find((file) => file.path === path)?.bytes
293
- const themeFile = contents.find((file) => file.path === ARTIFACT_THEME_FILE)
347
+ // A merged version is checked from its installed copy, which holds what it holds.
348
+ const checked = published.merged ? (written && copy ? written : undefined) : contents
349
+ const checkDirectory = published.merged
350
+ ? copy && posix.resolve(handle.sandbox.workingDirectory, copy)
351
+ : root && posix.dirname(root.absolutePath)
352
+ const bytesOf = (path: string) => checked?.find((file) => file.path === path)?.bytes
353
+ const themeFile = checked?.find((file) => file.path === ARTIFACT_THEME_FILE)
294
354
  // Publishing has read it already: a version with a theme.json it refused is not here.
295
355
  const theme = themeFile ? parseArtifactTheme(new TextDecoder().decode(themeFile.bytes)) : null
356
+ // A reader sees a canvas's boards as pictures until they open one: the check takes those its
357
+ // boards miss, in every mode. A board kept as it was keeps the pictures it had.
358
+ const missing = outline.kind === "canvas" ? await missingPreviews(input.artifacts, published) : []
359
+ const pictured = new Set(missing.map(({ board }) => board))
296
360
  // What the check opens: a canvas's boards, each at its own size, or the entry.
297
361
  const pages =
298
362
  outline.kind === "canvas"
@@ -301,25 +365,41 @@ async function publish(
301
365
  boards: outline.items.flatMap((item) => {
302
366
  const html = item.type === "board" ? bytesOf(item.file) : undefined
303
367
  return item.type === "board" && html
304
- ? [{ id: item.id, file: item.file, w: item.w, h: item.h, html }]
368
+ ? [
369
+ {
370
+ id: item.id,
371
+ file: item.file,
372
+ w: item.w,
373
+ h: item.h,
374
+ html,
375
+ pictured: pictured.has(item.id),
376
+ },
377
+ ]
305
378
  : []
306
379
  }),
380
+ ...canvasOf(bytesOf(CANVAS_FILE)),
307
381
  }
308
382
  : layout && bytesOf(entry)
309
383
  ? { layout, entry: bytesOf(entry) as Uint8Array }
310
384
  : null
311
385
  let check: LayoutCheck | undefined
312
386
  let queries: CheckedQueries = { answers: {}, warnings: [] }
313
- if (root && pages && (pages.layout !== "canvas" || pages.boards.length > 0)) {
387
+ if (
388
+ checked &&
389
+ checkDirectory &&
390
+ pages &&
391
+ (pages.layout !== "canvas" || pages.boards.length > 0)
392
+ ) {
314
393
  queries = await checkedQueries(input.artifacts, published)
315
394
  signal.throwIfAborted()
316
395
  try {
317
396
  check = await checkLayout({
318
397
  handle,
319
398
  ...pages,
320
- directory: posix.dirname(root.absolutePath),
321
- files: contents.map((file) => file.path),
322
- name: `${published.artifact.id}-v${published.version.version}`,
399
+ directory: checkDirectory,
400
+ files: checked.map((file) => file.path),
401
+ // A revision's check: two updates of one open version never share their pictures.
402
+ name: `${artifact.id}-r${version.revision}`,
323
403
  ...(theme && "theme" in theme ? { theme: theme.theme } : {}),
324
404
  queries: queries.answers,
325
405
  signal,
@@ -330,15 +410,29 @@ async function publish(
330
410
  check = { status: "skipped", reason: "the check failed in the sandbox" }
331
411
  }
332
412
  }
413
+ const previewWarnings =
414
+ check?.status === "checked" && missing.length > 0
415
+ ? await storePreviews({ input, handle, published, missing, checked: check.previews, signal })
416
+ : []
333
417
  return {
334
- artifactId: published.artifact.id,
335
- version: published.version.version,
336
- kind: published.artifact.kind,
337
- title: published.version.title,
418
+ artifactId: artifact.id,
419
+ // A new artifact, or a revision of one: what its summary and its row say.
420
+ created: "kind" in request.target,
421
+ version: version.version,
422
+ revision: version.revision,
423
+ // An Agent's write always leaves the version open: only the user creates a version.
424
+ open: version.frozenAt === undefined,
425
+ ...(published.merged ? { mergedSince: baseRevision ?? null } : {}),
426
+ ...(installedRevision
427
+ ? {}
428
+ : { notInstalled: true, nextUpdateFrom: installed.revisionOf(artifact.id) ?? null }),
429
+ kind: artifact.kind,
430
+ title: version.title,
338
431
  warnings: [
339
432
  ...published.warnings,
340
433
  ...queries.warnings,
341
434
  ...(check?.status === "checked" ? check.warnings : []),
435
+ ...previewWarnings,
342
436
  ].map(({ code, message, part }) => ({
343
437
  code,
344
438
  message,
@@ -349,12 +443,116 @@ async function publish(
349
443
  : {
350
444
  layoutCheck:
351
445
  check.status === "checked"
352
- ? { screenshots: [...check.screenshots] }
446
+ ? {
447
+ screenshots: [...check.screenshots],
448
+ ...(check.overview ? { overview: check.overview } : {}),
449
+ }
353
450
  : { skipped: check.reason },
354
451
  }),
355
452
  }
356
453
  }
357
454
 
455
+ /**
456
+ * The files of a version merged with what others wrote, as its bytes; none when they cannot be
457
+ * read, and the copy, the folder and the base of the next update then stay as they were.
458
+ */
459
+ async function mergedFiles(
460
+ input: PublishToolsInput,
461
+ published: PublishedArtifact,
462
+ signal: AbortSignal
463
+ ): Promise<PublishedArtifactFile[] | undefined> {
464
+ try {
465
+ return await readArtifactVersionFiles(input.blobStorage, published.version, signal)
466
+ } catch (error) {
467
+ if (signal.aborted) throw error
468
+ console.warn(
469
+ `[SixbAgent] Could not read revision ${published.version.revision} of '${published.artifact.id}', merged:`,
470
+ error
471
+ )
472
+ return undefined
473
+ }
474
+ }
475
+
476
+ /**
477
+ * The boards of the revision just written that miss a picture. A preview never costs a publish:
478
+ * when they cannot be read, the check pictures none and the worker renders what is missing.
479
+ */
480
+ async function missingPreviews(
481
+ artifacts: Pick<AgentRunArtifacts, "missingPreviews">,
482
+ published: PublishedArtifact
483
+ ): Promise<readonly AgentRunMissingPreview[]> {
484
+ try {
485
+ return await artifacts.missingPreviews(writtenAt(published))
486
+ } catch (error) {
487
+ console.warn(
488
+ `[SixbAgent] Could not read which boards of '${published.artifact.id}' miss a preview:`,
489
+ error
490
+ )
491
+ return []
492
+ }
493
+ }
494
+
495
+ /**
496
+ * Hands the pictures the check took over as the revision's previews, and warns of each board one
497
+ * of whose pictures was not kept: it shows its outline in that size and mode. The write exists by
498
+ * now, so a failure is only logged: the worker renders what is still missing, and an update
499
+ * written since gets its own.
500
+ */
501
+ async function storePreviews(context: {
502
+ readonly input: PublishToolsInput
503
+ readonly handle: AgentSandboxHandle
504
+ readonly published: PublishedArtifact
505
+ readonly missing: readonly AgentRunMissingPreview[]
506
+ readonly checked: readonly CheckedPreview[]
507
+ readonly signal: AbortSignal
508
+ }): Promise<LayoutWarning[]> {
509
+ const { input, published, signal } = context
510
+ try {
511
+ const { previews, dropped } = await storeCheckedPreviews({
512
+ handle: context.handle,
513
+ checked: context.checked,
514
+ missing: context.missing,
515
+ blobStorage: input.blobStorage,
516
+ signal,
517
+ })
518
+ const refused = await input.artifacts.storePreviews({ ...writtenAt(published), previews })
519
+ return unkeptPreviewWarnings([...dropped, ...refused])
520
+ } catch (error) {
521
+ if (signal.aborted) throw error
522
+ console.warn(
523
+ `[SixbAgent] Could not keep the previews of revision ${published.version.revision} of '${published.artifact.id}':`,
524
+ error
525
+ )
526
+ return []
527
+ }
528
+ }
529
+
530
+ /** The version a publish wrote, as it left its content. */
531
+ function writtenAt({ artifact, version }: PublishedArtifact) {
532
+ return { artifactId: artifact.id, version: version.version, updatedAt: version.updatedAt }
533
+ }
534
+
535
+ /** One warning per board whose pictures were not all kept, naming each and why. */
536
+ function unkeptPreviewWarnings(unkept: readonly RefusedBoardPreview[]): LayoutWarning[] {
537
+ const boards = [...new Set(unkept.map(({ board }) => board))]
538
+ return boards.map((board) => {
539
+ const pictures = unkept
540
+ .filter((picture) => picture.board === board)
541
+ .map(({ theme, size, reason }) => `the ${size} one in ${theme} mode (${reason})`)
542
+ return {
543
+ code: "preview_not_kept",
544
+ part: board,
545
+ message: `Board '${board}' has no preview for ${pictures.join(", ")}: readers see its outline there until they open it.`,
546
+ }
547
+ })
548
+ }
549
+
550
+ /** A canvas's items, for the check's picture of it as it opens; none when it cannot be read. */
551
+ function canvasOf(bytes: Uint8Array | undefined): { readonly canvas?: Canvas } {
552
+ const parsed = bytes ? parseCanvas(new TextDecoder().decode(bytes)) : undefined
553
+ return parsed && "canvas" in parsed ? { canvas: parsed.canvas } : {}
554
+ }
555
+
358
556
  interface CheckedQueries {
359
557
  readonly answers: Readonly<Record<string, CheckedQuery>>
360
558
  readonly warnings: readonly LayoutWarning[]
@@ -371,22 +569,10 @@ async function checkedQueries(
371
569
  published: PublishedArtifact
372
570
  ): Promise<CheckedQueries> {
373
571
  const { artifact, version } = published
374
- const names = version.files.flatMap((file) => {
375
- const name = artifactQueryName(file.path)
376
- return name === undefined ? [] : [name]
377
- })
378
-
379
- const answers = await Promise.all(
380
- names.map(async (name): Promise<readonly [string, CheckedQuery]> => {
381
- try {
382
- const result = await reader.query(artifact.id, name, { version: version.version })
383
- if (!result) throw new Error(`[SixbAgent] Version ${version.version} is missing.`)
384
-
385
- return [name, { result: serializeArtifactQueryResult(result) }]
386
- } catch (error) {
387
- return [name, { error: queryErrorText(error) }]
388
- }
389
- })
572
+ const answers = Object.entries(
573
+ await answerArtifactQueries(version, (name) =>
574
+ reader.query(artifact.id, name, { version: version.version })
575
+ )
390
576
  )
391
577
 
392
578
  return {
@@ -404,49 +590,44 @@ async function checkedQueries(
404
590
  }
405
591
  }
406
592
 
407
- /** A refusal in the words the API gives a reader; anything else stays internal. */
408
- function queryErrorText(error: unknown): string {
409
- if (
410
- error instanceof ArtifactRequestError ||
411
- error instanceof AuthorizationError ||
412
- error instanceof ObjectQueryExecutionError
413
- ) {
414
- return /[.!?]$/.test(error.message) ? error.message : `${error.message}.`
415
- }
416
-
417
- console.warn("[SixbAgent] A query of the published version did not run:", error)
418
- return "[Sixb] The query could not be read."
419
- }
420
-
421
593
  /** How storing refuses an artifact the requester may not publish to: as if it did not exist. */
422
594
  const UNREACHABLE: ReadonlySet<string> = new Set(["artifact_not_found", "not_shared", "read_only"])
423
595
 
424
596
  /**
425
- * The artifact to publish a version of: one the requester owns, or one this conversation shares
426
- * that they take part in. Another is refused as if it did not exist, even one they could update
427
- * from another conversation: publishing here would share it in this one.
597
+ * The artifact to update: one the requester owns, or one this conversation shares that they take
598
+ * part in. Another is refused as if it did not exist, even one they could update from another
599
+ * conversation: writing it here would share it in this one.
428
600
  */
429
601
  async function updatableArtifact(
430
602
  input: PublishToolsInput,
431
603
  artifactId: string,
432
- tool: PublishToolName
604
+ tool: ArtifactToolName,
605
+ installed?: InstalledArtifacts
433
606
  ): Promise<ArtifactRecord> {
434
607
  const artifact = await input.artifacts.updatable(artifactId)
435
- if (!artifact) throw noArtifact(tool, artifactId)
436
- return artifact
608
+ if (artifact) return artifact
609
+
610
+ // One installed to read is named as such: it exists, and the Agent was told it reads it.
611
+ if (installed?.readOnly(artifactId)) {
612
+ throw publishError(
613
+ tool,
614
+ `you can read artifact '${artifactId}' but not change it, so nothing was published`
615
+ )
616
+ }
617
+ throw noArtifact(tool, artifactId)
437
618
  }
438
619
 
439
- function noArtifact(tool: PublishToolName, artifactId: string): AgentToolPublicError {
620
+ function noArtifact(tool: ArtifactToolName, artifactId: string): AgentToolPublicError {
440
621
  return publishError(
441
622
  tool,
442
- `there is no artifact '${artifactId}'. $SIXB_ARTIFACTS lists this conversation's artifacts; to create a new one, call ${CREATE_TOOL}`
623
+ `there is no artifact '${artifactId}'. $SIXB_ARTIFACTS lists this conversation's artifacts; to create a new one, leave out id and pass its kind`
443
624
  )
444
625
  }
445
626
 
446
627
  /**
447
- * The refusal for a version made from a copy the artifact has moved past, such as a person saving
448
- * in the app while the run works. The version it moved to replaces the copy, so the Agent starts
449
- * again from it instead of publishing over it.
628
+ * The refusal for an update made from a copy the artifact has moved past, such as a person saving
629
+ * in the app while the run works. What it moved to replaces the copy, so the Agent starts again
630
+ * from it instead of writing over it.
450
631
  */
451
632
  async function artifactMoved(
452
633
  input: PublishToolsInput,
@@ -454,50 +635,109 @@ async function artifactMoved(
454
635
  installed,
455
636
  handle,
456
637
  }: { readonly installed: InstalledArtifacts; readonly handle: AgentSandboxHandle },
457
- { artifactId, baseVersion }: { readonly artifactId: string; readonly baseVersion: number },
638
+ { artifactId, baseRevision }: { readonly artifactId: string; readonly baseRevision: number },
458
639
  signal: AbortSignal
459
640
  ): Promise<AgentToolPublicError> {
460
641
  // Read as the requester: whatever moved it, it is a version they can read.
461
- const artifact = await updatableArtifact(input, artifactId, VERSION_TOOL)
642
+ const artifact = await updatableArtifact(input, artifactId, CREATE_TOOL)
462
643
  const latest = await input.artifacts.getVersion(artifactId, artifact.latestVersion)
463
644
  if (!latest) {
464
645
  throw new Error(`[SixbAgent] Version ${artifact.latestVersion} of '${artifactId}' is missing.`)
465
646
  }
466
647
 
467
- const author = principalsEqual(latest.author, input.owner)
468
- ? "its owner"
469
- : `${latest.author.type} '${latest.author.id}'`
648
+ const named = (principal: Principal) =>
649
+ principalsEqual(principal, input.owner) ? "its owner" : `${principal.type} '${principal.id}'`
650
+ const author = named(latest.author)
470
651
  const where =
471
652
  latest.origin === undefined
472
653
  ? `by ${author} outside a conversation, such as in the app`
473
654
  : latest.origin.threadId === input.threadId
474
655
  ? "earlier in this conversation"
475
656
  : `by ${author} in another conversation`
476
- const moved = `artifact '${artifactId}' moved on from version ${baseVersion}, which you started from: version ${latest.version} was published ${where}, so nothing was published`
657
+ const created = latest.frozenBy
658
+ ? `, and then created as a version by ${named(latest.frozenBy)}`
659
+ : ""
660
+ const moved = `artifact '${artifactId}' changed since revision ${baseRevision}, which you started from: it is at revision ${latest.revision}, whose version ${latest.version} was last written ${where}${created}, so nothing was published`
477
661
 
662
+ let folder: string | undefined
478
663
  try {
479
664
  const files = await readArtifactVersionFiles(input.blobStorage, latest, signal)
480
- await installed.replace(handle.sandbox, { artifact, version: latest }, files, signal, {
665
+ folder = await installed.replace(handle.sandbox, { artifact, version: latest }, files, signal, {
481
666
  edited: latest.origin?.threadId !== input.threadId,
482
667
  })
483
668
  } catch (error) {
484
669
  if (signal.aborted) throw error
485
670
  console.warn(
486
- `[SixbAgent] Could not install version ${latest.version} of artifact '${artifactId}':`,
671
+ `[SixbAgent] Could not install revision ${latest.revision} of artifact '${artifactId}':`,
487
672
  error
488
673
  )
489
674
  return publishError(
490
- VERSION_TOOL,
491
- `${moved}. Version ${latest.version} could not be installed in the sandbox, so tell the user you could not build on it`
675
+ CREATE_TOOL,
676
+ `${moved}. Its revision ${latest.revision} could not be installed in the sandbox, so tell the user you could not build on it`
492
677
  )
493
678
  }
494
679
 
495
680
  return publishError(
496
- VERSION_TOOL,
497
- `${moved}. $SIXB_ARTIFACTS lists version ${latest.version}, installed under $SIXB_ARTIFACTS_DIR/${artifactId}/: start again from it as it is, keep its changes, make yours again, and publish`
681
+ CREATE_TOOL,
682
+ `${moved}. $SIXB_ARTIFACTS lists revision ${latest.revision}, installed under $SIXB_ARTIFACTS_DIR/${artifactId}/${folder ? ` and written into ${folder}, the folder you published it from` : ""}: start again from it as it is, keep its changes, make yours again, and publish it with its id`
498
683
  )
499
684
  }
500
685
 
686
+ /**
687
+ * Installs the artifact's latest version under `$SIXB_ARTIFACTS_DIR/<id>/`, as the requester reads
688
+ * it: to read only, when they may not change it. Opening shares nothing: the conversation shares it
689
+ * once the Agent updates it from that copy.
690
+ */
691
+ async function open(
692
+ input: PublishToolsInput,
693
+ artifactId: string,
694
+ signal: AbortSignal
695
+ ): Promise<JsonValue> {
696
+ signal.throwIfAborted()
697
+ const artifact = await input.artifacts.get(artifactId)
698
+ if (!artifact) throw publishError(OPEN_TOOL, `there is no artifact '${artifactId}' you can read`)
699
+
700
+ const [installed, updatable, latest] = await Promise.all([
701
+ input.installed,
702
+ input.artifacts.updatable(artifactId),
703
+ input.artifacts.getVersion(artifactId, artifact.latestVersion),
704
+ ])
705
+ if (!latest) {
706
+ throw new Error(`[SixbAgent] Version ${artifact.latestVersion} of '${artifactId}' is missing.`)
707
+ }
708
+
709
+ const readOnly = updatable === null
710
+ try {
711
+ const { sandbox } = await input.resolveSandbox()
712
+ const files = await readArtifactVersionFiles(input.blobStorage, latest, signal)
713
+ await installed.replace(sandbox, { artifact, version: latest }, files, signal, {
714
+ edited: latest.origin?.threadId !== input.threadId,
715
+ readOnly,
716
+ })
717
+ } catch (error) {
718
+ if (signal.aborted) throw error
719
+ console.warn(
720
+ `[SixbAgent] Could not install revision ${latest.revision} of artifact '${artifactId}':`,
721
+ error
722
+ )
723
+ throw publishError(
724
+ OPEN_TOOL,
725
+ `its revision ${latest.revision} could not be installed in the sandbox, so tell the user you could not open it`
726
+ )
727
+ }
728
+
729
+ const directory = installed.directoryOf(artifactId)
730
+ return {
731
+ artifactId,
732
+ kind: artifact.kind,
733
+ title: latest.title,
734
+ version: latest.version,
735
+ revision: latest.revision,
736
+ readOnly,
737
+ ...(directory ? { directory } : {}),
738
+ }
739
+ }
740
+
501
741
  interface PublishSource {
502
742
  /** The file's path in the artifact. */
503
743
  readonly path: string
@@ -512,11 +752,24 @@ interface PublishSource {
512
752
  * a dot. A single file publishes alone: a document's Markdown as `document.md`, any other file
513
753
  * under its own name.
514
754
  */
755
+ /** The folder the files were published from, when they were a folder's: one file has none. */
756
+ function publishedFolder(
757
+ handle: AgentSandboxHandle,
758
+ path: string,
759
+ sources: readonly PublishSource[]
760
+ ): { readonly path: string; readonly absolute: string } | undefined {
761
+ const absolute = resolveSandboxPath(handle, path)
762
+ const inFolder = sources.every(
763
+ (source) => source.absolutePath === posix.join(absolute, source.path)
764
+ )
765
+ return inFolder ? { path, absolute } : undefined
766
+ }
767
+
515
768
  async function listSources(
516
769
  handle: AgentSandboxHandle,
517
770
  path: string,
518
771
  kind: ArtifactKind,
519
- tool: PublishToolName,
772
+ tool: ArtifactToolName,
520
773
  signal: AbortSignal
521
774
  ): Promise<PublishSource[]> {
522
775
  let absolutePath: string
@@ -580,15 +833,56 @@ async function listSources(
580
833
  }))
581
834
  }
582
835
 
583
- function publishSummary(output: JsonValue, tool: PublishToolName): string {
836
+ /** What the Agent is told of an artifact it opened: where to read it, and whether it may change it. */
837
+ function openSummary(output: JsonValue): string {
838
+ if (typeof output !== "object" || output === null || Array.isArray(output)) {
839
+ return JSON.stringify(output)
840
+ }
841
+
842
+ const where =
843
+ typeof output.directory === "string"
844
+ ? `installed under ${output.directory}/`
845
+ : "listed in $SIXB_ARTIFACTS, but too large to install"
846
+ return [
847
+ `Opened "${String(output.title)}": artifact ${String(output.artifactId)}, version ${String(output.version)} at revision ${String(output.revision)}, ${where}.`,
848
+ output.readOnly === true
849
+ ? "The user may read it but not change it: do not update it."
850
+ : `To change it, edit a copy of that folder and call ${CREATE_TOOL} with this id: this conversation then shares it.`,
851
+ ].join(" ")
852
+ }
853
+
854
+ function publishSummary(output: JsonValue): string {
584
855
  if (typeof output !== "object" || output === null || Array.isArray(output)) {
585
856
  return JSON.stringify(output)
586
857
  }
858
+ const written = `artifact ${String(output.artifactId)}, version ${String(output.version)} at revision ${String(output.revision)}`
587
859
  const lines = [
588
- `Published "${String(output.title)}" as artifact ${String(output.artifactId)}, version ${String(output.version)}.`,
860
+ output.created === true
861
+ ? `Published "${String(output.title)}" as ${written}.`
862
+ : `Updated "${String(output.title)}": ${written}.`,
863
+ output.open === false
864
+ ? "The version is frozen."
865
+ : `The version is open: each update replaces it until the user creates a version. To change it, call ${CREATE_TOOL} with this id.`,
589
866
  ]
590
- if (tool === CREATE_TOOL) {
591
- lines.push(`To change it, publish its next version with ${VERSION_TOOL} and this id.`)
867
+ const copy = `$SIXB_ARTIFACTS_DIR/${String(output.artifactId)}/`
868
+ const since =
869
+ typeof output.mergedSince === "number"
870
+ ? `, since revision ${output.mergedSince}, which you started from`
871
+ : ""
872
+ const from =
873
+ typeof output.nextUpdateFrom === "number"
874
+ ? `your next update starts from revision ${output.nextUpdateFrom} again`
875
+ : "your next update starts from what it held before"
876
+ if ("mergedSince" in output && output.notInstalled === true) {
877
+ lines.push(
878
+ `Merged with changes made meanwhile${since}, but the merged result could not be installed: your folder and ${copy} still hold your own files, and ${from}, so what others wrote stays. Read the version before editing what others may have changed, and say in your reply that others were editing it.`
879
+ )
880
+ } else if ("mergedSince" in output) {
881
+ lines.push(
882
+ `Merged with changes made meanwhile${since}: your folder now holds the merged result, as does ${copy}. Keep editing from it, and say in your reply that others were editing it.`
883
+ )
884
+ } else if (output.notInstalled === true) {
885
+ lines.push(`This revision could not be installed in ${copy}: ${from}.`)
592
886
  }
593
887
  const warnings = Array.isArray(output.warnings) ? output.warnings : []
594
888
  for (const warning of warnings) {
@@ -616,10 +910,14 @@ function publishSummary(output: JsonValue, tool: PublishToolName): string {
616
910
  const directory = posix.dirname(screenshots[0] ?? "")
617
911
  lines.push(
618
912
  kind === "page"
619
- ? `Layout check: the page as the reader sees it, in light mode or the mode its theme.json pins, is ${directory}/desktop.png at 1280px and ${directory}/phone.png at 390px, each its top 4000px. Open them with view_file, fix what the warnings name, and publish the next version.`
913
+ ? `Layout check: the page as the reader sees it, in light mode or the mode its theme.json pins, is ${directory}/desktop.png at 1280px and ${directory}/phone.png at 390px, each its top 4000px. Open them with read, fix what the warnings name, and update the artifact.`
620
914
  : kind === "canvas"
621
- ? `Layout check: each board as the reader sees it, at its own size, in light mode or the mode its theme.json pins, is ${directory}/<id>.png (${screenshots.length} boards). Open them with view_file, fix what the warnings name, and publish the next version.`
622
- : `Layout check: each slide as the reader sees it, in light mode or the mode its theme.json pins, is ${directory}/slide-NN.png (${screenshots.length} slides). Open them with view_file, fix what the warnings name, and publish the next version.`
915
+ ? `Layout check: each board as the reader sees it, at its own size, in light mode or the mode its theme.json pins, is ${directory}/<id>.png (${screenshots.length} boards). Open them with read, fix what the warnings name, and update the artifact.${
916
+ typeof check.overview === "string"
917
+ ? ` Open ${check.overview} to see the canvas as it opens, fitted to a 1440×900 window, and check that it reads at that zoom.`
918
+ : ""
919
+ }`
920
+ : `Layout check: each slide as the reader sees it, in light mode or the mode its theme.json pins, is ${directory}/slide-NN.png (${screenshots.length} slides). Open them with read, fix what the warnings name, and update the artifact.`
623
921
  )
624
922
  }
625
923
  }
@@ -627,36 +925,50 @@ function publishSummary(output: JsonValue, tool: PublishToolName): string {
627
925
  }
628
926
 
629
927
  function parsePublishArtifactInput(value: unknown): PublishArtifactToolInput {
630
- const input = inputObject(value, CREATE_TOOL, ["path", "kind", "title"])
631
- if (!PUBLISHABLE_KINDS.includes(input.kind as PublishableKind)) {
928
+ const input = inputObject(value, CREATE_TOOL, ["path", "title", "kind", "id"])
929
+ const kind = input.kind === undefined || input.kind === null ? undefined : input.kind
930
+ if (kind !== undefined && !PUBLISHABLE_KINDS.includes(kind as PublishableKind)) {
632
931
  throw publishError(CREATE_TOOL, `kind must be one of ${PUBLISHABLE_KINDS.join(", ")}`)
633
932
  }
634
- return {
635
- path: pathInput(input.path, CREATE_TOOL),
636
- kind: input.kind as PublishableKind,
637
- title: titleInput(input.title, CREATE_TOOL),
933
+ if (input.id !== undefined && input.id !== null && typeof input.id !== "string") {
934
+ throw publishError(CREATE_TOOL, "id must be an artifact id such as art_k3m9q2x7tp")
638
935
  }
639
- }
640
-
641
- function parsePublishArtifactVersionInput(value: unknown): PublishArtifactVersionToolInput {
642
- const input = inputObject(value, VERSION_TOOL, ["id", "path", "title"])
936
+ // What a model sends for "no id": nothing, an empty string, or the word.
643
937
  const id = typeof input.id === "string" ? input.id.trim() : ""
644
- if (!isArtifactId(id)) {
938
+ const noId = id === "" || /^(null|none|undefined)$/i.test(id)
939
+ if (!noId && !isArtifactId(id)) {
645
940
  throw publishError(
646
- VERSION_TOOL,
647
- `id must be an artifact id such as art_k3m9q2x7tp. $SIXB_ARTIFACTS lists this conversation's artifacts; to create a new one, call ${CREATE_TOOL}`
941
+ CREATE_TOOL,
942
+ `id must be an artifact id such as art_k3m9q2x7tp. $SIXB_ARTIFACTS lists this conversation's artifacts; to create a new one, leave out id and pass its kind`
648
943
  )
649
944
  }
650
- return {
651
- id,
652
- path: pathInput(input.path, VERSION_TOOL),
653
- title: titleInput(input.title, VERSION_TOOL),
945
+ if (noId && kind === undefined) {
946
+ throw publishError(
947
+ CREATE_TOOL,
948
+ "pass kind to publish a new artifact, or the id of one to update it"
949
+ )
950
+ }
951
+ const path = pathInput(input.path, CREATE_TOOL)
952
+ const title = titleInput(input.title, CREATE_TOOL)
953
+ // With an id, a kind is ignored: an update keeps the artifact's, and a model that sends every
954
+ // field, as strict mode has it, fills one in.
955
+ return noId
956
+ ? { path, title, target: { kind: kind as PublishableKind } }
957
+ : { path, title, target: { artifactId: id } }
958
+ }
959
+
960
+ function parseOpenArtifactInput(value: unknown): OpenArtifactToolInput {
961
+ const input = inputObject(value, OPEN_TOOL, ["id"])
962
+ const id = typeof input.id === "string" ? input.id.trim() : ""
963
+ if (!isArtifactId(id)) {
964
+ throw publishError(OPEN_TOOL, "id must be an artifact id such as art_k3m9q2x7tp")
654
965
  }
966
+ return { id }
655
967
  }
656
968
 
657
969
  function inputObject(
658
970
  value: unknown,
659
- tool: PublishToolName,
971
+ tool: ArtifactToolName,
660
972
  keys: readonly string[]
661
973
  ): Record<string, unknown> {
662
974
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -668,20 +980,20 @@ function inputObject(
668
980
  return input
669
981
  }
670
982
 
671
- function pathInput(value: unknown, tool: PublishToolName): string {
983
+ function pathInput(value: unknown, tool: ArtifactToolName): string {
672
984
  if (typeof value !== "string" || value.trim().length === 0) {
673
985
  throw publishError(tool, "path must be a file or directory in the sandbox")
674
986
  }
675
987
  return value
676
988
  }
677
989
 
678
- function titleInput(value: unknown, tool: PublishToolName): string {
990
+ function titleInput(value: unknown, tool: ArtifactToolName): string {
679
991
  if (typeof value !== "string") throw publishError(tool, "title must be text")
680
992
  return value
681
993
  }
682
994
 
683
995
  /** Refusals the Agent can act on become its error text; anything else stays internal. */
684
- function toPublishError(error: unknown, tool: PublishToolName, path?: string): unknown {
996
+ function toPublishError(error: unknown, tool: ArtifactToolName, path?: string): unknown {
685
997
  if (error instanceof SandboxFileError) {
686
998
  if (error.reason === "not_found" && path !== undefined) {
687
999
  return publishError(tool, `there is no file or directory at '${path}'`)
@@ -694,7 +1006,7 @@ function toPublishError(error: unknown, tool: PublishToolName, path?: string): u
694
1006
  return error
695
1007
  }
696
1008
 
697
- function publishError(tool: PublishToolName, message: string): AgentToolPublicError {
1009
+ function publishError(tool: ArtifactToolName, message: string): AgentToolPublicError {
698
1010
  const sentence = /[.!?]$/.test(message) ? message : `${message}.`
699
1011
  return new AgentToolPublicError(`[SixbAgent] ${tool} refused: ${sentence}`)
700
1012
  }