@sixb/agent 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/README.md +3 -3
  2. package/dist/agent-prompt.d.ts.map +1 -1
  3. package/dist/artifacts/layout-check/layout-check.d.ts +21 -24
  4. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  5. package/dist/artifacts/publish-tool.d.ts +26 -44
  6. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  7. package/dist/ask-tool.d.ts +62 -0
  8. package/dist/ask-tool.d.ts.map +1 -0
  9. package/dist/attachments.d.ts +1 -1
  10. package/dist/attachments.d.ts.map +1 -1
  11. package/dist/background-commands.d.ts +3 -3
  12. package/dist/background-commands.d.ts.map +1 -1
  13. package/dist/background-notices.d.ts.map +1 -1
  14. package/dist/child-files.d.ts +1 -1
  15. package/dist/child-questions.d.ts +1 -1
  16. package/dist/index.d.ts +1 -2
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +10457 -7971
  19. package/dist/index.js.map +46 -38
  20. package/dist/run-agent-turn.d.ts +3 -14
  21. package/dist/run-agent-turn.d.ts.map +1 -1
  22. package/dist/run-conversation-turn.d.ts.map +1 -1
  23. package/dist/run-environment.d.ts +4 -1
  24. package/dist/run-environment.d.ts.map +1 -1
  25. package/dist/run-subagent.d.ts +1 -1
  26. package/dist/run-subagent.d.ts.map +1 -1
  27. package/dist/sandbox-api-context.d.ts.map +1 -1
  28. package/dist/search-script.d.ts +7 -0
  29. package/dist/search-script.d.ts.map +1 -0
  30. package/dist/skills/built-in.d.ts.map +1 -1
  31. package/dist/subagent-tools.d.ts +20 -1
  32. package/dist/subagent-tools.d.ts.map +1 -1
  33. package/dist/tools/background.d.ts +50 -18
  34. package/dist/tools/background.d.ts.map +1 -1
  35. package/dist/tools/bash.d.ts +1 -0
  36. package/dist/tools/bash.d.ts.map +1 -1
  37. package/dist/tools/edit-text.d.ts +22 -0
  38. package/dist/tools/edit-text.d.ts.map +1 -0
  39. package/dist/tools/edit.d.ts +54 -0
  40. package/dist/tools/edit.d.ts.map +1 -0
  41. package/dist/tools/file-writes.d.ts +52 -0
  42. package/dist/tools/file-writes.d.ts.map +1 -0
  43. package/dist/tools/glob.d.ts +41 -0
  44. package/dist/tools/glob.d.ts.map +1 -0
  45. package/dist/tools/grep.d.ts +64 -0
  46. package/dist/tools/grep.d.ts.map +1 -0
  47. package/dist/tools/model-spec.d.ts.map +1 -1
  48. package/dist/tools/read.d.ts +16 -3
  49. package/dist/tools/read.d.ts.map +1 -1
  50. package/dist/tools/sandbox-search.d.ts +26 -0
  51. package/dist/tools/sandbox-search.d.ts.map +1 -0
  52. package/dist/tools/search/command.d.ts +15 -0
  53. package/dist/tools/search/command.d.ts.map +1 -0
  54. package/dist/tools/search/gitignore.d.ts +28 -0
  55. package/dist/tools/search/gitignore.d.ts.map +1 -0
  56. package/dist/tools/search/glob.d.ts +15 -0
  57. package/dist/tools/search/glob.d.ts.map +1 -0
  58. package/dist/tools/search/main.d.ts +2 -0
  59. package/dist/tools/search/main.d.ts.map +1 -0
  60. package/dist/tools/search/match.d.ts +30 -0
  61. package/dist/tools/search/match.d.ts.map +1 -0
  62. package/dist/tools/search/pattern.d.ts +19 -0
  63. package/dist/tools/search/pattern.d.ts.map +1 -0
  64. package/dist/tools/search/read.d.ts +62 -0
  65. package/dist/tools/search/read.d.ts.map +1 -0
  66. package/dist/tools/search/request.d.ts +80 -0
  67. package/dist/tools/search/request.d.ts.map +1 -0
  68. package/dist/tools/search/search.d.ts +4 -0
  69. package/dist/tools/search/search.d.ts.map +1 -0
  70. package/dist/tools/search/walk.d.ts +43 -0
  71. package/dist/tools/search/walk.d.ts.map +1 -0
  72. package/dist/tools/tool-outputs.d.ts.map +1 -1
  73. package/dist/tools/view-file.d.ts +20 -23
  74. package/dist/tools/view-file.d.ts.map +1 -1
  75. package/dist/tools/web-fetch/tool.d.ts +1 -0
  76. package/dist/tools/web-fetch/tool.d.ts.map +1 -1
  77. package/dist/tools/web-search.d.ts +1 -0
  78. package/dist/tools/web-search.d.ts.map +1 -1
  79. package/dist/tools/write.d.ts +36 -0
  80. package/dist/tools/write.d.ts.map +1 -0
  81. package/dist/turn-inbox.d.ts +75 -0
  82. package/dist/turn-inbox.d.ts.map +1 -0
  83. package/package.json +6 -4
  84. package/src/agent-prompt.ts +10 -9
  85. package/src/agent-runtime/preflight.ts +1 -0
  86. package/src/artifacts/layout-check/check.cjs +176 -95
  87. package/src/artifacts/layout-check/layout-check.ts +118 -76
  88. package/src/artifacts/publish-tool.ts +123 -192
  89. package/src/ask-tool.ts +223 -0
  90. package/src/attachments.ts +7 -6
  91. package/src/background-commands.ts +5 -5
  92. package/src/background-notices.ts +5 -12
  93. package/src/child-files.ts +1 -1
  94. package/src/child-questions.ts +1 -1
  95. package/src/context-compaction.ts +4 -1
  96. package/src/generated/search.mjs +985 -0
  97. package/src/index.ts +1 -2
  98. package/src/run-agent-turn.ts +99 -133
  99. package/src/run-child.ts +1 -1
  100. package/src/run-conversation-turn.ts +8 -5
  101. package/src/run-environment.ts +40 -21
  102. package/src/run-subagent.ts +4 -4
  103. package/src/sandbox-api-context.ts +3 -0
  104. package/src/search-script-assets.d.ts +5 -0
  105. package/src/search-script.ts +9 -0
  106. package/src/skills/built-in.ts +16 -0
  107. package/src/skills/sixb-artifacts/SKILL.md +13 -13
  108. package/src/skills/sixb-artifacts/canvas.md +5 -4
  109. package/src/skills/sixb-artifacts/document.md +92 -5
  110. package/src/skills/sixb-artifacts/examples/document/service-proposal/design.css +114 -0
  111. package/src/skills/sixb-artifacts/examples/document/service-proposal/document.html +159 -0
  112. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/fieldwise.svg +1 -0
  113. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/harbor-pine.svg +1 -0
  114. package/src/skills/sixb-artifacts/page.md +2 -2
  115. package/src/skills/sixb-artifacts/queries.md +2 -1
  116. package/src/skills/sixb-artifacts/slides.md +2 -2
  117. package/src/subagent-tools.ts +115 -81
  118. package/src/tools/background.ts +227 -67
  119. package/src/tools/bash.ts +2 -1
  120. package/src/tools/edit-text.ts +241 -0
  121. package/src/tools/edit.ts +166 -0
  122. package/src/tools/file-writes.ts +270 -0
  123. package/src/tools/glob.ts +124 -0
  124. package/src/tools/grep.ts +190 -0
  125. package/src/tools/model-spec.ts +13 -13
  126. package/src/tools/read.ts +75 -9
  127. package/src/tools/sandbox-search.ts +219 -0
  128. package/src/tools/search/command.ts +116 -0
  129. package/src/tools/search/gitignore.ts +101 -0
  130. package/src/tools/search/glob.ts +90 -0
  131. package/src/tools/search/main.ts +9 -0
  132. package/src/tools/search/match.ts +278 -0
  133. package/src/tools/search/pattern.ts +178 -0
  134. package/src/tools/search/read.ts +237 -0
  135. package/src/tools/search/request.ts +101 -0
  136. package/src/tools/search/search.ts +297 -0
  137. package/src/tools/search/walk.ts +145 -0
  138. package/src/tools/tool-outputs.ts +9 -4
  139. package/src/tools/view-file.ts +78 -80
  140. package/src/tools/web-fetch/tool.ts +2 -1
  141. package/src/tools/web-search.ts +1 -0
  142. package/src/tools/write.ts +95 -0
  143. package/src/turn-inbox.ts +283 -0
  144. package/dist/artifacts/board-previews.d.ts +0 -41
  145. package/dist/artifacts/board-previews.d.ts.map +0 -1
  146. package/dist/ask-parent-tool.d.ts +0 -36
  147. package/dist/ask-parent-tool.d.ts.map +0 -1
  148. package/src/artifacts/board-previews.ts +0 -218
  149. package/src/ask-parent-tool.ts +0 -100
@@ -20,15 +20,14 @@ import {
20
20
  AgentExecutionLostError,
21
21
  type AgentRunArtifacts,
22
22
  type AgentRunFileStore,
23
- type AgentRunMissingPreview,
24
23
  } from "@sixb/core/internal/agents"
25
24
  import { frameLayout } from "@sixb/core/internal/artifacts/frames"
26
25
  import {
27
26
  ARTIFACT_LIMITS,
28
27
  answerArtifactQueries,
28
+ DOCUMENT_HOLDER_QUERY,
29
29
  isArtifactId,
30
30
  type PublishedArtifact,
31
- type RefusedBoardPreview,
32
31
  } from "@sixb/core/internal/artifacts/publish"
33
32
  import { inferFileMediaType } from "@sixb/core/internal/blob-storage"
34
33
  import type { JsonObject, ModelTool } from "@sixb/core/models"
@@ -42,9 +41,7 @@ import {
42
41
  } from "../sandbox-files"
43
42
  import type { AgentSandboxHandle } from "../sandbox-handle"
44
43
  import type { AgentFileBudget } from "../tools/tool-files"
45
- import { storeCheckedPreviews } from "./board-previews"
46
44
  import {
47
- type CheckedPreview,
48
45
  type CheckedQuery,
49
46
  checkLayout,
50
47
  type LayoutCheck,
@@ -57,18 +54,17 @@ import {
57
54
  } from "./materialize"
58
55
 
59
56
  const CREATE_TOOL = "publish_artifact"
60
- const UPDATE_TOOL = "update_artifact"
61
57
  const OPEN_TOOL = "open_artifact"
62
- type ArtifactToolName = typeof CREATE_TOOL | typeof UPDATE_TOOL | typeof OPEN_TOOL
58
+ type ArtifactToolName = typeof CREATE_TOOL | typeof OPEN_TOOL
63
59
  const SANDBOX_TIMEOUT_MS = 30_000
64
60
  /** The kinds the Agent can create today; each lands with its validator, renderer, and skill. */
65
61
  const PUBLISHABLE_KINDS = ARTIFACT_KINDS
66
62
  type PublishableKind = ArtifactKind
67
63
 
68
- // Creating and revising are two tools, and every argument of each is required and meaningful. A
69
- // mode carried by an optional or null argument is where models differ: some fill every field, some
70
- // send "null" or "" for nothing. Every model picks a tool by name. With all properties required
71
- // and no length or pattern keywords, every model adapter can also send both schemas as strict.
64
+ // One tool creates and revises: `kind` names a new artifact's, `id` the artifact to revise, whose
65
+ // kind stays, so a kind sent with an id is ignored. Every adapter sends the optional fields as it
66
+ // can (strict where it may), and an empty id or "null", which a model sends for nothing, is no id:
67
+ // ids start `art_`.
72
68
  const PATH_PROPERTY = {
73
69
  type: "string",
74
70
  description: "A file or a directory in the sandbox, relative to the working directory.",
@@ -80,40 +76,37 @@ const TITLE_PROPERTY = {
80
76
 
81
77
  export const PUBLISH_ARTIFACT_TOOL_SPEC = {
82
78
  name: CREATE_TOOL,
83
- description:
84
- "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 update_artifact. Returns the artifact's id and version; a refusal says what to fix.",
85
- inputSchema: {
86
- type: "object",
87
- properties: {
88
- path: PATH_PROPERTY,
89
- kind: { type: "string", enum: [...PUBLISHABLE_KINDS] },
90
- title: TITLE_PROPERTY,
91
- },
92
- required: ["path", "kind", "title"],
93
- additionalProperties: false,
94
- } satisfies JsonObject,
95
- } as const
96
-
97
- export const UPDATE_ARTIFACT_TOOL_SPEC = {
98
- name: UPDATE_TOOL,
99
- description:
100
- "Update an artifact of this conversation, or one an object the user may edit holds, from a file or directory in the sandbox: 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. Returns the version and revision it wrote; a refusal says what to fix.",
79
+ strict: true,
80
+ description: [
81
+ "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.",
82
+ "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.",
83
+ "Returns the artifact's id, version and revision; a refusal says what to fix.",
84
+ ].join("\n"),
101
85
  inputSchema: {
102
86
  type: "object",
103
87
  properties: {
104
- id: { type: "string", description: "The artifact's id, such as art_k3m9q2x7tp." },
105
88
  path: PATH_PROPERTY,
106
89
  title: TITLE_PROPERTY,
90
+ kind: {
91
+ type: "string",
92
+ enum: [...PUBLISHABLE_KINDS],
93
+ description: "A new artifact's kind. With an id it is ignored: an update keeps its kind.",
94
+ },
95
+ id: {
96
+ type: "string",
97
+ description: "The artifact to update, such as art_k3m9q2x7tp. Leave it out to create one.",
98
+ },
107
99
  },
108
- required: ["id", "path", "title"],
100
+ required: ["path", "title"],
109
101
  additionalProperties: false,
110
102
  } satisfies JsonObject,
111
103
  } as const
112
104
 
113
105
  export const OPEN_ARTIFACT_TOOL_SPEC = {
114
106
  name: OPEN_TOOL,
107
+ strict: true,
115
108
  description:
116
- "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 update_artifact when the user may change it. Publishes nothing. Returns its title, revision, and whether the user may only read it.",
109
+ "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.",
117
110
  inputSchema: {
118
111
  type: "object",
119
112
  properties: {
@@ -124,17 +117,8 @@ export const OPEN_ARTIFACT_TOOL_SPEC = {
124
117
  } satisfies JsonObject,
125
118
  } as const
126
119
 
127
- export interface PublishArtifactToolInput {
128
- readonly path: string
129
- readonly kind: PublishableKind
130
- readonly title: string
131
- }
132
-
133
- export interface UpdateArtifactToolInput {
134
- readonly id: string
135
- readonly path: string
136
- readonly title: string
137
- }
120
+ /** A publish: of a new artifact by its kind, or of an artifact's current version by its id. */
121
+ export type PublishArtifactToolInput = PublishRequest
138
122
 
139
123
  export interface OpenArtifactToolInput {
140
124
  readonly id: string
@@ -156,10 +140,10 @@ interface PublishToolsInput {
156
140
  }
157
141
 
158
142
  /**
159
- * `publish_artifact` and `update_artifact`: each reads a file or a directory from the sandbox,
160
- * stores its bytes, and publishes them through the run's session, which applies a run's rules (see
161
- * `AgentRunArtifacts.publish`). An update replaces the open version's content, or opens the next
162
- * version after one the user created. What it wrote exists when the tool returns, so the
143
+ * `publish_artifact` reads a file or a directory from the sandbox, stores its bytes, and publishes
144
+ * them through the run's session, which applies a run's rules (see `AgentRunArtifacts.publish`):
145
+ * a new artifact of its kind, or, by id, the open version's content replaced, or the next version
146
+ * opened after one the user created. What it wrote exists when the tool returns, so the
163
147
  * conversation shows it mid-turn and a cancelled run keeps it.
164
148
  *
165
149
  * `open_artifact` installs one the conversation does not list, as the requester reads it, so an
@@ -167,28 +151,15 @@ interface PublishToolsInput {
167
151
  */
168
152
  export function createPublishArtifactTools(
169
153
  input: PublishToolsInput
170
- ): readonly [
171
- ModelTool<PublishArtifactToolInput>,
172
- ModelTool<UpdateArtifactToolInput>,
173
- ModelTool<OpenArtifactToolInput>,
174
- ] {
154
+ ): readonly [ModelTool<PublishArtifactToolInput>, ModelTool<OpenArtifactToolInput>] {
175
155
  return [
176
156
  {
177
157
  ...PUBLISH_ARTIFACT_TOOL_SPEC,
178
158
  parseInput: parsePublishArtifactInput,
179
- execute: (request, { signal }) =>
180
- publish(input, CREATE_TOOL, { ...request, target: { kind: request.kind } }, signal),
181
- toModelOutput: (output) => ({ type: "text", value: publishSummary(output, CREATE_TOOL) }),
159
+ execute: (request, { signal }) => publish(input, request, signal),
160
+ toModelOutput: (output) => ({ type: "text", value: publishSummary(output) }),
182
161
  errorText: (error) => publishErrorText(error, CREATE_TOOL),
183
162
  },
184
- {
185
- ...UPDATE_ARTIFACT_TOOL_SPEC,
186
- parseInput: parseUpdateArtifactInput,
187
- execute: (request, { signal }) =>
188
- publish(input, UPDATE_TOOL, { ...request, target: { artifactId: request.id } }, signal),
189
- toModelOutput: (output) => ({ type: "text", value: publishSummary(output, UPDATE_TOOL) }),
190
- errorText: (error) => publishErrorText(error, UPDATE_TOOL),
191
- },
192
163
  {
193
164
  ...OPEN_ARTIFACT_TOOL_SPEC,
194
165
  parseInput: parseOpenArtifactInput,
@@ -216,10 +187,10 @@ interface PublishRequest {
216
187
 
217
188
  async function publish(
218
189
  input: PublishToolsInput,
219
- tool: ArtifactToolName,
220
190
  request: PublishRequest,
221
191
  signal: AbortSignal
222
192
  ): Promise<JsonValue> {
193
+ const tool = CREATE_TOOL
223
194
  signal.throwIfAborted()
224
195
  const installed = await input.installed
225
196
 
@@ -234,7 +205,7 @@ async function publish(
234
205
 
235
206
  throw publishError(
236
207
  tool,
237
- `artifact '${artifactId}' is not open in this conversation, so nothing was published: call ${OPEN_TOOL} with its id, then revise its copy and update it`
208
+ `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`
238
209
  )
239
210
  }
240
211
 
@@ -242,11 +213,12 @@ async function publish(
242
213
  "kind" in request.target
243
214
  ? request.target.kind
244
215
  : (await updatableArtifact(input, request.target.artifactId, tool, installed)).kind
216
+
245
217
  const handle = await input.resolveSandbox()
246
218
  const sources = await listSources(handle, request.path, kind, tool, signal)
247
219
 
248
220
  // An installed artifact is updated from its copy: writing past the revision the copy holds would
249
- // drop whatever was written since. A canvas is merged instead, from the copy's files.
221
+ // drop whatever was written since. A canvas or a document is merged instead, from the copy's files.
250
222
  const base =
251
223
  "artifactId" in request.target ? installed.baseOf(request.target.artifactId) : undefined
252
224
  const baseRevision =
@@ -304,8 +276,6 @@ async function publish(
304
276
  : { kind }),
305
277
  title: request.title,
306
278
  files,
307
- // The layout check pictures a canvas's boards as it checks them.
308
- rendersPreviews: kind === "canvas",
309
279
  })
310
280
  } catch (error) {
311
281
  // Nothing was published, so the bytes do not count against the run.
@@ -364,9 +334,9 @@ async function publish(
364
334
  )
365
335
  }
366
336
  }
367
- // A published deck, page, or canvas is laid out in the sandbox's browser, so the Agent sees what
368
- // the reader will, and fixes it in its next update.
369
- const layout = frameLayout(kind)
337
+ // A published deck, page, designed document, or canvas is laid out in the sandbox's browser, so
338
+ // the Agent sees what the reader will, and fixes it in its next update.
339
+ const layout = frameLayout(version)
370
340
  const { outline, entry } = version
371
341
  const root = layout ? sources.find((source) => source.path === entry) : undefined
372
342
  // A merged version is checked from its installed copy, which holds what it holds.
@@ -378,10 +348,6 @@ async function publish(
378
348
  const themeFile = checked?.find((file) => file.path === ARTIFACT_THEME_FILE)
379
349
  // Publishing has read it already: a version with a theme.json it refused is not here.
380
350
  const theme = themeFile ? parseArtifactTheme(new TextDecoder().decode(themeFile.bytes)) : null
381
- // A reader sees a canvas's boards as pictures until they open one: the check takes those its
382
- // boards miss, in every mode. A board kept as it was keeps the pictures it had.
383
- const missing = outline.kind === "canvas" ? await missingPreviews(input.artifacts, published) : []
384
- const pictured = new Set(missing.map(({ board }) => board))
385
351
  // What the check opens: a canvas's boards, each at its own size, or the entry.
386
352
  const pages =
387
353
  outline.kind === "canvas"
@@ -397,7 +363,6 @@ async function publish(
397
363
  w: item.w,
398
364
  h: item.h,
399
365
  html,
400
- pictured: pictured.has(item.id),
401
366
  },
402
367
  ]
403
368
  : []
@@ -405,7 +370,11 @@ async function publish(
405
370
  ...canvasOf(bytesOf(CANVAS_FILE)),
406
371
  }
407
372
  : layout && bytesOf(entry)
408
- ? { layout, entry: bytesOf(entry) as Uint8Array }
373
+ ? {
374
+ layout,
375
+ entry: bytesOf(entry) as Uint8Array,
376
+ ...(outline.kind === "document" && outline.paper ? { paper: outline.paper } : {}),
377
+ }
409
378
  : null
410
379
  let check: LayoutCheck | undefined
411
380
  let queries: CheckedQueries = { answers: {}, warnings: [] }
@@ -435,12 +404,10 @@ async function publish(
435
404
  check = { status: "skipped", reason: "the check failed in the sandbox" }
436
405
  }
437
406
  }
438
- const previewWarnings =
439
- check?.status === "checked" && missing.length > 0
440
- ? await storePreviews({ input, handle, published, missing, checked: check.previews, signal })
441
- : []
442
407
  return {
443
408
  artifactId: artifact.id,
409
+ // A new artifact, or a revision of one: what its summary and its row say.
410
+ created: "kind" in request.target,
444
411
  version: version.version,
445
412
  revision: version.revision,
446
413
  // An Agent's write always leaves the version open: only the user creates a version.
@@ -455,7 +422,6 @@ async function publish(
455
422
  ...published.warnings,
456
423
  ...queries.warnings,
457
424
  ...(check?.status === "checked" ? check.warnings : []),
458
- ...previewWarnings,
459
425
  ].map(({ code, message, part }) => ({
460
426
  code,
461
427
  message,
@@ -468,6 +434,7 @@ async function publish(
468
434
  check.status === "checked"
469
435
  ? {
470
436
  screenshots: [...check.screenshots],
437
+ ...(check.pages ? { pages: check.pages } : {}),
471
438
  ...(check.overview ? { overview: check.overview } : {}),
472
439
  }
473
440
  : { skipped: check.reason },
@@ -496,80 +463,6 @@ async function mergedFiles(
496
463
  }
497
464
  }
498
465
 
499
- /**
500
- * The boards of the revision just written that miss a picture. A preview never costs a publish:
501
- * when they cannot be read, the check pictures none and the worker renders what is missing.
502
- */
503
- async function missingPreviews(
504
- artifacts: Pick<AgentRunArtifacts, "missingPreviews">,
505
- published: PublishedArtifact
506
- ): Promise<readonly AgentRunMissingPreview[]> {
507
- try {
508
- return await artifacts.missingPreviews(writtenAt(published))
509
- } catch (error) {
510
- console.warn(
511
- `[SixbAgent] Could not read which boards of '${published.artifact.id}' miss a preview:`,
512
- error
513
- )
514
- return []
515
- }
516
- }
517
-
518
- /**
519
- * Hands the pictures the check took over as the revision's previews, and warns of each board one
520
- * of whose pictures was not kept: it shows its outline in that size and mode. The write exists by
521
- * now, so a failure is only logged: the worker renders what is still missing, and an update
522
- * written since gets its own.
523
- */
524
- async function storePreviews(context: {
525
- readonly input: PublishToolsInput
526
- readonly handle: AgentSandboxHandle
527
- readonly published: PublishedArtifact
528
- readonly missing: readonly AgentRunMissingPreview[]
529
- readonly checked: readonly CheckedPreview[]
530
- readonly signal: AbortSignal
531
- }): Promise<LayoutWarning[]> {
532
- const { input, published, signal } = context
533
- try {
534
- const { previews, dropped } = await storeCheckedPreviews({
535
- handle: context.handle,
536
- checked: context.checked,
537
- missing: context.missing,
538
- blobStorage: input.blobStorage,
539
- signal,
540
- })
541
- const refused = await input.artifacts.storePreviews({ ...writtenAt(published), previews })
542
- return unkeptPreviewWarnings([...dropped, ...refused])
543
- } catch (error) {
544
- if (signal.aborted) throw error
545
- console.warn(
546
- `[SixbAgent] Could not keep the previews of revision ${published.version.revision} of '${published.artifact.id}':`,
547
- error
548
- )
549
- return []
550
- }
551
- }
552
-
553
- /** The version a publish wrote, as it left its content. */
554
- function writtenAt({ artifact, version }: PublishedArtifact) {
555
- return { artifactId: artifact.id, version: version.version, updatedAt: version.updatedAt }
556
- }
557
-
558
- /** One warning per board whose pictures were not all kept, naming each and why. */
559
- function unkeptPreviewWarnings(unkept: readonly RefusedBoardPreview[]): LayoutWarning[] {
560
- const boards = [...new Set(unkept.map(({ board }) => board))]
561
- return boards.map((board) => {
562
- const pictures = unkept
563
- .filter((picture) => picture.board === board)
564
- .map(({ theme, size, reason }) => `the ${size} one in ${theme} mode (${reason})`)
565
- return {
566
- code: "preview_not_kept",
567
- part: board,
568
- message: `Board '${board}' has no preview for ${pictures.join(", ")}: readers see its outline there until they open it.`,
569
- }
570
- })
571
- }
572
-
573
466
  /** A canvas's items, for the check's picture of it as it opens; none when it cannot be read. */
574
467
  function canvasOf(bytes: Uint8Array | undefined): { readonly canvas?: Canvas } {
575
468
  const parsed = bytes ? parseCanvas(new TextDecoder().decode(bytes)) : undefined
@@ -600,8 +493,9 @@ async function checkedQueries(
600
493
 
601
494
  return {
602
495
  answers: Object.fromEntries(answers),
496
+ // A document no object holds yet shows its written text: none of its queries failed.
603
497
  warnings: answers.flatMap(([name, answer]) =>
604
- "error" in answer
498
+ "error" in answer && name !== DOCUMENT_HOLDER_QUERY
605
499
  ? [
606
500
  {
607
501
  code: "query_failed",
@@ -643,7 +537,7 @@ async function updatableArtifact(
643
537
  function noArtifact(tool: ArtifactToolName, artifactId: string): AgentToolPublicError {
644
538
  return publishError(
645
539
  tool,
646
- `there is no artifact '${artifactId}'. $SIXB_ARTIFACTS lists this conversation's artifacts; to create a new one, call ${CREATE_TOOL}`
540
+ `there is no artifact '${artifactId}'. $SIXB_ARTIFACTS lists this conversation's artifacts; to create a new one, leave out id and pass its kind`
647
541
  )
648
542
  }
649
543
 
@@ -662,7 +556,7 @@ async function artifactMoved(
662
556
  signal: AbortSignal
663
557
  ): Promise<AgentToolPublicError> {
664
558
  // Read as the requester: whatever moved it, it is a version they can read.
665
- const artifact = await updatableArtifact(input, artifactId, UPDATE_TOOL)
559
+ const artifact = await updatableArtifact(input, artifactId, CREATE_TOOL)
666
560
  const latest = await input.artifacts.getVersion(artifactId, artifact.latestVersion)
667
561
  if (!latest) {
668
562
  throw new Error(`[SixbAgent] Version ${artifact.latestVersion} of '${artifactId}' is missing.`)
@@ -695,14 +589,14 @@ async function artifactMoved(
695
589
  error
696
590
  )
697
591
  return publishError(
698
- UPDATE_TOOL,
592
+ CREATE_TOOL,
699
593
  `${moved}. Its revision ${latest.revision} could not be installed in the sandbox, so tell the user you could not build on it`
700
594
  )
701
595
  }
702
596
 
703
597
  return publishError(
704
- UPDATE_TOOL,
705
- `${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 update it`
598
+ CREATE_TOOL,
599
+ `${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`
706
600
  )
707
601
  }
708
602
 
@@ -823,7 +717,13 @@ async function listSources(
823
717
  })
824
718
  return [
825
719
  {
826
- path: kind === "document" ? "document.md" : posix.basename(absolutePath),
720
+ // A document's one file is its entry: HTML when it is designed, Markdown otherwise.
721
+ path:
722
+ kind === "document"
723
+ ? /\.html?$/i.test(absolutePath)
724
+ ? "document.html"
725
+ : "document.md"
726
+ : posix.basename(absolutePath),
827
727
  absolutePath,
828
728
  sizeBytes: bytes.byteLength,
829
729
  bytes,
@@ -870,22 +770,22 @@ function openSummary(output: JsonValue): string {
870
770
  `Opened "${String(output.title)}": artifact ${String(output.artifactId)}, version ${String(output.version)} at revision ${String(output.revision)}, ${where}.`,
871
771
  output.readOnly === true
872
772
  ? "The user may read it but not change it: do not update it."
873
- : `To change it, edit a copy of that folder and call ${UPDATE_TOOL} with this id: this conversation then shares it.`,
773
+ : `To change it, edit a copy of that folder and call ${CREATE_TOOL} with this id: this conversation then shares it.`,
874
774
  ].join(" ")
875
775
  }
876
776
 
877
- function publishSummary(output: JsonValue, tool: ArtifactToolName): string {
777
+ function publishSummary(output: JsonValue): string {
878
778
  if (typeof output !== "object" || output === null || Array.isArray(output)) {
879
779
  return JSON.stringify(output)
880
780
  }
881
781
  const written = `artifact ${String(output.artifactId)}, version ${String(output.version)} at revision ${String(output.revision)}`
882
782
  const lines = [
883
- tool === CREATE_TOOL
783
+ output.created === true
884
784
  ? `Published "${String(output.title)}" as ${written}.`
885
785
  : `Updated "${String(output.title)}": ${written}.`,
886
786
  output.open === false
887
787
  ? "The version is frozen."
888
- : `The version is open: each update replaces it until the user creates a version. To change it, call ${UPDATE_TOOL} with this id.`,
788
+ : `The version is open: each update replaces it until the user creates a version. To change it, call ${CREATE_TOOL} with this id.`,
889
789
  ]
890
790
  const copy = `$SIXB_ARTIFACTS_DIR/${String(output.artifactId)}/`
891
791
  const since =
@@ -926,21 +826,29 @@ function publishSummary(output: JsonValue, tool: ArtifactToolName): string {
926
826
  ? "Read index.html and its scripts closely."
927
827
  : kind === "canvas"
928
828
  ? "Read each board's HTML closely."
929
- : "Read index.html slide by slide."
829
+ : kind === "document"
830
+ ? "Read document.html and its stylesheets closely: what fits the paper, and where each page breaks."
831
+ : "Read index.html slide by slide."
930
832
  }`
931
833
  )
932
834
  } else if (screenshots.length > 0) {
933
835
  const directory = posix.dirname(screenshots[0] ?? "")
934
836
  lines.push(
935
837
  kind === "page"
936
- ? `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 update the artifact.`
838
+ ? `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.`
937
839
  : kind === "canvas"
938
- ? `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 update the artifact.${
840
+ ? `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.${
939
841
  typeof check.overview === "string"
940
842
  ? ` Open ${check.overview} to see the canvas as it opens, fitted to a 1440×900 window, and check that it reads at that zoom.`
941
843
  : ""
942
844
  }`
943
- : `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 update the artifact.`
845
+ : kind === "document"
846
+ ? documentShots(
847
+ directory,
848
+ screenshots,
849
+ typeof check.pages === "number" ? check.pages : undefined
850
+ )
851
+ : `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.`
944
852
  )
945
853
  }
946
854
  }
@@ -948,15 +856,36 @@ function publishSummary(output: JsonValue, tool: ArtifactToolName): string {
948
856
  }
949
857
 
950
858
  function parsePublishArtifactInput(value: unknown): PublishArtifactToolInput {
951
- const input = inputObject(value, CREATE_TOOL, ["path", "kind", "title"])
952
- if (!PUBLISHABLE_KINDS.includes(input.kind as PublishableKind)) {
859
+ const input = inputObject(value, CREATE_TOOL, ["path", "title", "kind", "id"])
860
+ const kind = input.kind === undefined || input.kind === null ? undefined : input.kind
861
+ if (kind !== undefined && !PUBLISHABLE_KINDS.includes(kind as PublishableKind)) {
953
862
  throw publishError(CREATE_TOOL, `kind must be one of ${PUBLISHABLE_KINDS.join(", ")}`)
954
863
  }
955
- return {
956
- path: pathInput(input.path, CREATE_TOOL),
957
- kind: input.kind as PublishableKind,
958
- title: titleInput(input.title, CREATE_TOOL),
864
+ if (input.id !== undefined && input.id !== null && typeof input.id !== "string") {
865
+ throw publishError(CREATE_TOOL, "id must be an artifact id such as art_k3m9q2x7tp")
959
866
  }
867
+ // What a model sends for "no id": nothing, an empty string, or the word.
868
+ const id = typeof input.id === "string" ? input.id.trim() : ""
869
+ const noId = id === "" || /^(null|none|undefined)$/i.test(id)
870
+ if (!noId && !isArtifactId(id)) {
871
+ throw publishError(
872
+ CREATE_TOOL,
873
+ `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`
874
+ )
875
+ }
876
+ if (noId && kind === undefined) {
877
+ throw publishError(
878
+ CREATE_TOOL,
879
+ "pass kind to publish a new artifact, or the id of one to update it"
880
+ )
881
+ }
882
+ const path = pathInput(input.path, CREATE_TOOL)
883
+ const title = titleInput(input.title, CREATE_TOOL)
884
+ // With an id, a kind is ignored: an update keeps the artifact's, and a model that sends every
885
+ // field, as strict mode has it, fills one in.
886
+ return noId
887
+ ? { path, title, target: { kind: kind as PublishableKind } }
888
+ : { path, title, target: { artifactId: id } }
960
889
  }
961
890
 
962
891
  function parseOpenArtifactInput(value: unknown): OpenArtifactToolInput {
@@ -968,22 +897,6 @@ function parseOpenArtifactInput(value: unknown): OpenArtifactToolInput {
968
897
  return { id }
969
898
  }
970
899
 
971
- function parseUpdateArtifactInput(value: unknown): UpdateArtifactToolInput {
972
- const input = inputObject(value, UPDATE_TOOL, ["id", "path", "title"])
973
- const id = typeof input.id === "string" ? input.id.trim() : ""
974
- if (!isArtifactId(id)) {
975
- throw publishError(
976
- UPDATE_TOOL,
977
- `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}`
978
- )
979
- }
980
- return {
981
- id,
982
- path: pathInput(input.path, UPDATE_TOOL),
983
- title: titleInput(input.title, UPDATE_TOOL),
984
- }
985
- }
986
-
987
900
  function inputObject(
988
901
  value: unknown,
989
902
  tool: ArtifactToolName,
@@ -1028,3 +941,21 @@ function publishError(tool: ArtifactToolName, message: string): AgentToolPublicE
1028
941
  const sentence = /[.!?]$/.test(message) ? message : `${message}.`
1029
942
  return new AgentToolPublicError(`[SixbAgent] ${tool} refused: ${sentence}`)
1030
943
  }
944
+
945
+ /**
946
+ * Where a designed document's screenshots are: its pages as they print, or its one sheet when it
947
+ * has no paper, and the top of it on a phone.
948
+ */
949
+ function documentShots(
950
+ directory: string,
951
+ screenshots: readonly string[],
952
+ pages: number | undefined
953
+ ): string {
954
+ const shot = screenshots.filter((each) => posix.basename(each).startsWith("page-")).length
955
+ const phone = ` ${directory}/phone.png is its top 4000px on a phone (390px), where it shows as one sheet: check that nothing runs off the side.`
956
+ if (shot === 0) {
957
+ return `Layout check: the document as one sheet is ${directory}/document.png. It has no paper, so no pages: give its stylesheet an @page rule with a size to print it.${phone} Open them with read, fix what the warnings name, and update the artifact.`
958
+ }
959
+ const count = pages ?? shot
960
+ return `Layout check: each page as it prints is ${directory}/page-NN.png (${count} pages${count > shot ? `, the first ${shot} shot` : ""}).${phone} Open them with read, check where each page breaks and that nothing is cut off, fix what the warnings name, and update the artifact.`
961
+ }