@sixb/agent 0.2.4 → 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 (90) hide show
  1. package/README.md +2 -2
  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.map +1 -1
  6. package/dist/index.d.ts +0 -1
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +10590 -8888
  9. package/dist/index.js.map +30 -26
  10. package/dist/run-agent-turn.d.ts +3 -14
  11. package/dist/run-agent-turn.d.ts.map +1 -1
  12. package/dist/run-environment.d.ts.map +1 -1
  13. package/dist/run-subagent.d.ts.map +1 -1
  14. package/dist/sandbox-api-context.d.ts.map +1 -1
  15. package/dist/search-script.d.ts +7 -0
  16. package/dist/search-script.d.ts.map +1 -0
  17. package/dist/skills/built-in.d.ts.map +1 -1
  18. package/dist/tools/glob.d.ts +41 -0
  19. package/dist/tools/glob.d.ts.map +1 -0
  20. package/dist/tools/grep.d.ts +64 -0
  21. package/dist/tools/grep.d.ts.map +1 -0
  22. package/dist/tools/model-spec.d.ts.map +1 -1
  23. package/dist/tools/sandbox-search.d.ts +26 -0
  24. package/dist/tools/sandbox-search.d.ts.map +1 -0
  25. package/dist/tools/search/command.d.ts +15 -0
  26. package/dist/tools/search/command.d.ts.map +1 -0
  27. package/dist/tools/search/gitignore.d.ts +28 -0
  28. package/dist/tools/search/gitignore.d.ts.map +1 -0
  29. package/dist/tools/search/glob.d.ts +15 -0
  30. package/dist/tools/search/glob.d.ts.map +1 -0
  31. package/dist/tools/search/main.d.ts +2 -0
  32. package/dist/tools/search/main.d.ts.map +1 -0
  33. package/dist/tools/search/match.d.ts +30 -0
  34. package/dist/tools/search/match.d.ts.map +1 -0
  35. package/dist/tools/search/pattern.d.ts +19 -0
  36. package/dist/tools/search/pattern.d.ts.map +1 -0
  37. package/dist/tools/search/read.d.ts +62 -0
  38. package/dist/tools/search/read.d.ts.map +1 -0
  39. package/dist/tools/search/request.d.ts +80 -0
  40. package/dist/tools/search/request.d.ts.map +1 -0
  41. package/dist/tools/search/search.d.ts +4 -0
  42. package/dist/tools/search/search.d.ts.map +1 -0
  43. package/dist/tools/search/walk.d.ts +43 -0
  44. package/dist/tools/search/walk.d.ts.map +1 -0
  45. package/dist/tools/tool-outputs.d.ts.map +1 -1
  46. package/dist/turn-inbox.d.ts +75 -0
  47. package/dist/turn-inbox.d.ts.map +1 -0
  48. package/package.json +6 -4
  49. package/src/agent-prompt.ts +1 -0
  50. package/src/agent-runtime/preflight.ts +1 -0
  51. package/src/artifacts/layout-check/check.cjs +176 -95
  52. package/src/artifacts/layout-check/layout-check.ts +118 -76
  53. package/src/artifacts/publish-tool.ts +48 -99
  54. package/src/generated/search.mjs +985 -0
  55. package/src/index.ts +0 -1
  56. package/src/run-agent-turn.ts +85 -129
  57. package/src/run-conversation-turn.ts +4 -4
  58. package/src/run-environment.ts +4 -0
  59. package/src/run-subagent.ts +1 -1
  60. package/src/sandbox-api-context.ts +3 -0
  61. package/src/search-script-assets.d.ts +5 -0
  62. package/src/search-script.ts +9 -0
  63. package/src/skills/built-in.ts +16 -0
  64. package/src/skills/sixb-artifacts/SKILL.md +7 -7
  65. package/src/skills/sixb-artifacts/canvas.md +3 -2
  66. package/src/skills/sixb-artifacts/document.md +92 -5
  67. package/src/skills/sixb-artifacts/examples/document/service-proposal/design.css +114 -0
  68. package/src/skills/sixb-artifacts/examples/document/service-proposal/document.html +159 -0
  69. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/fieldwise.svg +1 -0
  70. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/harbor-pine.svg +1 -0
  71. package/src/skills/sixb-artifacts/queries.md +2 -1
  72. package/src/tools/glob.ts +124 -0
  73. package/src/tools/grep.ts +190 -0
  74. package/src/tools/model-spec.ts +4 -0
  75. package/src/tools/sandbox-search.ts +219 -0
  76. package/src/tools/search/command.ts +116 -0
  77. package/src/tools/search/gitignore.ts +101 -0
  78. package/src/tools/search/glob.ts +90 -0
  79. package/src/tools/search/main.ts +9 -0
  80. package/src/tools/search/match.ts +278 -0
  81. package/src/tools/search/pattern.ts +178 -0
  82. package/src/tools/search/read.ts +237 -0
  83. package/src/tools/search/request.ts +101 -0
  84. package/src/tools/search/search.ts +297 -0
  85. package/src/tools/search/walk.ts +145 -0
  86. package/src/tools/tool-outputs.ts +7 -2
  87. package/src/turn-inbox.ts +283 -0
  88. package/dist/artifacts/board-previews.d.ts +0 -41
  89. package/dist/artifacts/board-previews.d.ts.map +0 -1
  90. package/src/artifacts/board-previews.ts +0 -218
package/src/index.ts CHANGED
@@ -1,6 +1,5 @@
1
1
  export { waitForAbort } from "./abort"
2
2
  export type { AgentWorkspacePromptContext } from "./agent-prompt"
3
- export { renderBoardPreviews } from "./artifacts/board-previews"
4
3
  export { createAskParentTool } from "./ask-tool"
5
4
  export type { BackgroundCommandStatus } from "./background-commands"
6
5
  export {
@@ -1,4 +1,4 @@
1
- import type { AgentMessage, AgentMessagePart, AgentStepRequestSize } from "@sixb/core"
1
+ import type { AgentStepRequestSize } from "@sixb/core"
2
2
  import {
3
3
  type AgentContextBudget,
4
4
  type AgentRunSession,
@@ -25,10 +25,10 @@ import { conversationModelMessages, conversationModelSettings } from "./conversa
25
25
  import { AgentContextCompactionError, throwIfExecutionLost } from "./errors"
26
26
  import type { ResolvedAgentExecutionPlan } from "./execution-plan"
27
27
  import type { ConversationReaders } from "./message-authors"
28
- import { agentTraceFromModelSteps, agentTraceFromPartialModelLoop } from "./model-adapters"
29
28
  import type { ConversationAgentExecutionEnvironment } from "./run-environment"
30
29
  import { monitorSandboxReadiness } from "./sandbox-readiness"
31
30
  import type { LoadedAgentThreadModelContext } from "./thread-context"
31
+ import { TurnInbox, turnResultMessages, turnWorkMessages } from "./turn-inbox"
32
32
  import { type AgentTurnRuntime, createAgentTurnRuntime } from "./turn-runtime"
33
33
  import type { AgentTurnContext } from "./types"
34
34
 
@@ -69,10 +69,10 @@ export interface RunAgentTurnInput {
69
69
  readonly compactInTurn?: ConversationAgentExecutionEnvironment["compactInTurn"]
70
70
  }
71
71
  /**
72
- * Handed the answer so far after each step that completed, as the message the turn would
73
- * append: a turn that fails then records it with its failure, and keeps that work.
72
+ * Handed the answer so far after each step that completed, as the messages the turn would
73
+ * append: a turn that fails then records them with its failure, and keeps that work.
74
74
  */
75
- readonly onWork?: (message: AppendAgentMessageInput) => void
75
+ readonly onWork?: (messages: readonly AppendAgentMessageInput[]) => void
76
76
  }
77
77
 
78
78
  /**
@@ -118,7 +118,7 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
118
118
  sandboxReadiness.signal,
119
119
  ...(context.environmentFailureSignal ? [context.environmentFailureSignal] : []),
120
120
  ])
121
- let interruptedParts: readonly AgentMessagePart[] | undefined
121
+ let interruptedMessages: readonly AppendAgentMessageInput[] | undefined
122
122
  const stopReason = () =>
123
123
  stoppedByWorker(signal, input.stopSignal) ? { finishReason: "interrupted" as const } : {}
124
124
 
@@ -133,7 +133,7 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
133
133
  run,
134
134
  modelId: plan.model.modelId,
135
135
  ...stopReason(),
136
- parts: interruptedParts,
136
+ messages: interruptedMessages,
137
137
  })
138
138
  }
139
139
 
@@ -202,10 +202,19 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
202
202
  return { ...prepared, ...guarded }
203
203
  }
204
204
  : context.prepareStep
205
+ const turnInbox = new TurnInbox(input.session, {
206
+ retainedMessages: input.threadContext.retainedMessages,
207
+ ...(input.conversation === undefined ? {} : { conversation: input.conversation }),
208
+ project: { timeZone: context.projectTimeZone, locale: context.projectLocale },
209
+ })
205
210
  const prepareStep = async (step: PrepareModelStepInput) => {
206
211
  const prepared = await guardedStep?.(step)
207
- recordRequest(step.stepIndex, prepared?.messages ?? step.messages)
208
- return prepared
212
+ const steers = await turnInbox.take(step.stepIndex)
213
+ const baseMessages = prepared?.messages ?? step.messages
214
+ const nextMessages = steers.length > 0 ? [...baseMessages, ...steers] : baseMessages
215
+ recordRequest(step.stepIndex, nextMessages)
216
+ if (steers.length === 0) return prepared
217
+ return { ...prepared, messages: nextMessages }
209
218
  }
210
219
  const recoverStep =
211
220
  guard &&
@@ -215,32 +224,24 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
215
224
  return recovered
216
225
  })
217
226
 
218
- // The answer so far, as one message whatever step it is at.
219
- const workMessageId = createAgentMessageId()
220
227
  const finishedSteps: ModelStep[] = []
221
228
  const recordStep = (step: ModelStep) => {
222
229
  finishedSteps.push(step)
223
- input.onWork?.({
224
- id: workMessageId,
225
- projectId,
226
- threadId: run.threadId,
227
- runId,
228
- role: "assistant",
229
- parts: recordStepRequests(
230
- markReducedSteps(
231
- agentTraceFromModelSteps(
232
- finishedSteps,
233
- { threadId: run.threadId, runId },
234
- context.outputFileOf
235
- ),
236
- guard?.reducedFromStep()
237
- ),
238
- stepRequests
239
- ),
230
+ const snapshot = turnWorkMessages({
231
+ steps: finishedSteps,
232
+ run,
233
+ deliveries: turnInbox.deliveries,
234
+ ...(guard?.reducedFromStep() === undefined
235
+ ? {}
236
+ : { reducedFromStep: guard.reducedFromStep() }),
237
+ stepRequests,
238
+ ...(context.outputFileOf === undefined ? {} : { outputFileOf: context.outputFileOf }),
240
239
  ...(context.authorPrincipal === undefined
241
240
  ? {}
242
241
  : { authorPrincipal: context.authorPrincipal }),
243
242
  })
243
+ interruptedMessages = snapshot
244
+ input.onWork?.(snapshot)
244
245
  }
245
246
 
246
247
  try {
@@ -261,17 +262,18 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
261
262
  prepareStep,
262
263
  ...(recoverStep ? { recoverStep } : {}),
263
264
  onStepEnd: recordStep,
264
- // A child's question the model has not read comes before its answer ends the turn.
265
- ...(input.children === undefined
266
- ? {}
267
- : {
268
- beforeComplete: async () => {
269
- const unread = await input.children?.unread()
270
- return unread
271
- ? [{ role: "user", content: [{ type: "text", text: unread }] }]
272
- : undefined
273
- },
274
- }),
265
+ // Mid-run steers and unread child questions arrive before the answer ends the turn.
266
+ beforeComplete: async (_step, stepIndex) => {
267
+ const steers = await turnInbox.take(stepIndex + 1, { afterAnswer: true })
268
+ const unread = await input.children?.unread()
269
+ const followUp: ModelMessage[] = [
270
+ ...steers,
271
+ ...(unread
272
+ ? [{ role: "user" as const, content: [{ type: "text" as const, text: unread }] }]
273
+ : []),
274
+ ]
275
+ return followUp.length > 0 ? followUp : undefined
276
+ },
275
277
  signal: abortSignal,
276
278
  onEvent: async (chunk) => {
277
279
  await input.session.events.publishUiChunk({ run, chunkIndex: chunkIndex++, chunk })
@@ -301,24 +303,18 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
301
303
  throw error
302
304
  }
303
305
 
304
- interruptedParts = recordStepRequests(
305
- markReducedSteps(
306
- result.status === "aborted"
307
- ? agentTraceFromPartialModelLoop(
308
- result.steps,
309
- result.partialContent,
310
- { threadId: run.threadId, runId },
311
- context.outputFileOf
312
- )
313
- : agentTraceFromModelSteps(
314
- result.steps,
315
- { threadId: run.threadId, runId },
316
- context.outputFileOf
317
- ),
318
- guard?.reducedFromStep()
319
- ),
320
- stepRequests
321
- )
306
+ interruptedMessages = turnResultMessages(result, {
307
+ run,
308
+ deliveries: turnInbox.deliveries,
309
+ ...(guard?.reducedFromStep() === undefined
310
+ ? {}
311
+ : { reducedFromStep: guard.reducedFromStep() }),
312
+ stepRequests,
313
+ ...(context.outputFileOf === undefined ? {} : { outputFileOf: context.outputFileOf }),
314
+ ...(context.authorPrincipal === undefined
315
+ ? {}
316
+ : { authorPrincipal: context.authorPrincipal }),
317
+ })
322
318
 
323
319
  const interruptedAfterModel = await finalizeIfInterrupted()
324
320
  if (interruptedAfterModel) return interruptedAfterModel
@@ -329,7 +325,7 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
329
325
  run,
330
326
  modelId: plan.model.modelId,
331
327
  ...stopReason(),
332
- parts: interruptedParts,
328
+ messages: interruptedMessages,
333
329
  })
334
330
  }
335
331
 
@@ -354,12 +350,29 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
354
350
  : result.status === "paused"
355
351
  ? "stop"
356
352
  : (coerceAgentRunFinishReason(result.finishReason) ?? "unknown")
357
- const assistant: AgentMessage = { role: "assistant", parts: interruptedParts }
358
353
  const diagnostics = [
359
354
  outputLimitDiagnostic(finishReason),
360
355
  finishReason === "awaiting_approval" ? undefined : stepLimitDiagnostic(result),
361
356
  ].filter((diagnostic) => diagnostic !== undefined)
362
- const assistantMessageId = createAgentMessageId()
357
+ const committedMessages: readonly AppendAgentMessageInput[] =
358
+ interruptedMessages !== undefined && interruptedMessages.length > 0
359
+ ? interruptedMessages
360
+ : [
361
+ {
362
+ id: createAgentMessageId(),
363
+ projectId,
364
+ threadId: run.threadId,
365
+ runId,
366
+ role: "assistant" as const,
367
+ parts: [],
368
+ ...(context.authorPrincipal === undefined
369
+ ? {}
370
+ : { authorPrincipal: context.authorPrincipal }),
371
+ },
372
+ ]
373
+ const lastAssistant = [...committedMessages]
374
+ .reverse()
375
+ .find((message) => message.role === "assistant")
363
376
 
364
377
  const interruptedBeforeCommit = await finalizeIfInterrupted()
365
378
  if (interruptedBeforeCommit) return interruptedBeforeCommit
@@ -372,22 +385,12 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
372
385
  finishReason,
373
386
  ...(diagnostics.length === 0 ? {} : { diagnostics }),
374
387
  },
375
- [
376
- {
377
- id: assistantMessageId,
378
- projectId,
379
- threadId: run.threadId,
380
- runId,
381
- role: assistant.role,
382
- parts: assistant.parts,
383
- ...(context.authorPrincipal === undefined
384
- ? {}
385
- : { authorPrincipal: context.authorPrincipal }),
386
- },
387
- ]
388
+ committedMessages
388
389
  )
389
390
 
390
- await input.session.events.publishMessageFinalized({ run, messageId: assistantMessageId })
391
+ if (lastAssistant) {
392
+ await input.session.events.publishMessageFinalized({ run, messageId: lastAssistant.id })
393
+ }
391
394
  await input.session.events.publishRunFinished(finalizedRun)
392
395
  return finalizedRun
393
396
  } finally {
@@ -400,43 +403,6 @@ export async function runAgentTurn(input: RunAgentTurnInput): Promise<AgentRunRe
400
403
  * waiting, or decided and not reported to the model yet, its children's included.
401
404
  */
402
405
 
403
- /**
404
- * Mark each step from `fromStep` on as answering a request the turn reduced, for the next turn's
405
- * estimate not to go by what those calls read.
406
- */
407
- export function markReducedSteps(
408
- parts: readonly AgentMessagePart[],
409
- fromStep: number | undefined
410
- ): readonly AgentMessagePart[] {
411
- if (fromStep === undefined) return parts
412
-
413
- let step = -1
414
- return parts.map((part) => {
415
- if (part.type !== "step-start") return part
416
-
417
- step += 1
418
- return step >= fromStep ? { type: "step-start", reducedRequest: true } : part
419
- })
420
- }
421
-
422
- /**
423
- * Record on each step-start what its request carried, by step: the next turn's context meter
424
- * reads the system prompt and tools the latest one sent.
425
- */
426
- export function recordStepRequests(
427
- parts: readonly AgentMessagePart[],
428
- requests: readonly (AgentStepRequestSize | undefined)[]
429
- ): readonly AgentMessagePart[] {
430
- let step = -1
431
- return parts.map((part) => {
432
- if (part.type !== "step-start") return part
433
-
434
- step += 1
435
- const request = requests[step]
436
- return request ? { ...part, request } : part
437
- })
438
- }
439
-
440
406
  /**
441
407
  * Whether the worker's stop, rather than the user's, ended the turn. Whichever fired first wins:
442
408
  * the combined turn signal carries the reason of the first source that aborted it.
@@ -481,10 +447,10 @@ async function finalizeInterruptedTurn(input: {
481
447
  readonly run: ConversationAgentRunRecord
482
448
  readonly modelId?: string
483
449
  readonly finishReason?: "interrupted"
484
- readonly parts?: readonly AgentMessagePart[]
450
+ readonly messages?: readonly AppendAgentMessageInput[]
485
451
  }): Promise<AgentRunRecord> {
486
452
  const { session, context, run, modelId, finishReason } = input
487
- const parts = input.parts?.some((part) => part.type !== "step-start") ? input.parts : undefined
453
+ const messages = input.messages && input.messages.length > 0 ? input.messages : undefined
488
454
 
489
455
  await context.beforeFinalize?.()
490
456
 
@@ -493,27 +459,17 @@ async function finalizeInterruptedTurn(input: {
493
459
  ...(modelId === undefined ? {} : { modelId }),
494
460
  ...(finishReason === undefined ? {} : { finishReason }),
495
461
  }
496
- if (!parts) {
462
+ if (!messages) {
497
463
  const finalizedRun = await session.finish(outcome)
498
464
  await session.events.publishRunFinished(finalizedRun)
499
465
  return finalizedRun
500
466
  }
501
467
 
502
- const assistantMessageId = createAgentMessageId()
503
- const finalizedRun = await session.finish(outcome, [
504
- {
505
- id: assistantMessageId,
506
- projectId: run.projectId,
507
- threadId: run.threadId,
508
- runId: run.id,
509
- role: "assistant",
510
- parts,
511
- ...(context.authorPrincipal === undefined
512
- ? {}
513
- : { authorPrincipal: context.authorPrincipal }),
514
- },
515
- ])
516
- await session.events.publishMessageFinalized({ run, messageId: assistantMessageId })
468
+ const finalizedRun = await session.finish(outcome, messages)
469
+ const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant")
470
+ if (lastAssistant) {
471
+ await session.events.publishMessageFinalized({ run, messageId: lastAssistant.id })
472
+ }
517
473
  await session.events.publishRunFinished(finalizedRun)
518
474
  return finalizedRun
519
475
  }
@@ -89,7 +89,7 @@ export async function runConversationTurn(input: {
89
89
  let runtime: AgentTurnRuntime | null = null
90
90
  let delegation: SubagentCoordinator | undefined
91
91
  // The answer so far: a turn that fails keeps the steps it completed.
92
- let work: AppendAgentMessageInput | undefined
92
+ let work: readonly AppendAgentMessageInput[] | undefined
93
93
  // A user cancel joins the turn's abort sources, so it stops the model stream as a shutdown does.
94
94
  const turnSignal = AbortSignal.any([signal, session.cancelled])
95
95
 
@@ -164,8 +164,8 @@ export async function runConversationTurn(input: {
164
164
  ? {}
165
165
  : { bytesPerToken: environment.bytesPerToken }),
166
166
  },
167
- onWork: (message) => {
168
- work = message
167
+ onWork: (messages) => {
168
+ work = messages
169
169
  },
170
170
  })
171
171
  } catch (caughtError) {
@@ -197,7 +197,7 @@ export async function runConversationTurn(input: {
197
197
  session,
198
198
  aborted ? "cancelled" : "failed",
199
199
  interrupted ? new AgentTurnInterruptedError(run.id) : error,
200
- !aborted && work ? [work] : undefined
200
+ !aborted && work && work.length > 0 ? work : undefined
201
201
  )
202
202
  if (finalized) {
203
203
  if (finalized.run.status === "failed") {
@@ -91,6 +91,8 @@ import { createStopTool, createWaitTool, type WaitableChildren } from "./tools/b
91
91
  import { createBashTool } from "./tools/bash"
92
92
  import { createEditTool } from "./tools/edit"
93
93
  import { FileReadLedger } from "./tools/file-writes"
94
+ import { createGlobTool } from "./tools/glob"
95
+ import { createGrepTool } from "./tools/grep"
94
96
  import { agentModelToolSpecs, fetchesWeb } from "./tools/model-spec"
95
97
  import { createReadTool, READ_TOOL_SPEC } from "./tools/read"
96
98
  import {
@@ -929,6 +931,8 @@ async function startAgentEnvironment(
929
931
  appendBuiltInTool(tools, createReadTool(resolveSandbox, fileReads, fileViewer))
930
932
  appendBuiltInTool(tools, createEditTool(resolveSandbox, fileReads))
931
933
  appendBuiltInTool(tools, createWriteTool(resolveSandbox, fileReads))
934
+ appendBuiltInTool(tools, createGlobTool(resolveSandbox))
935
+ appendBuiltInTool(tools, createGrepTool(resolveSandbox))
932
936
  appendBuiltInTool(tools, createBashTool(resolveSandbox, background))
933
937
  appendBuiltInTool(tools, createWaitTool(resolveSandbox, background, input.children))
934
938
  appendBuiltInTool(tools, createStopTool(resolveSandbox, background, input.children))
@@ -27,7 +27,6 @@ import {
27
27
  agentTraceFromModelSteps,
28
28
  agentTraceFromPartialModelLoop,
29
29
  } from "./model-adapters"
30
- import { markReducedSteps } from "./run-agent-turn"
31
30
  import type { SubagentAgentExecutionEnvironment } from "./run-environment"
32
31
  import { monitorSandboxReadiness } from "./sandbox-readiness"
33
32
  import {
@@ -38,6 +37,7 @@ import {
38
37
  } from "./subagent-context"
39
38
  import type { SubagentHistory } from "./subagent-continuation"
40
39
  import type { SubagentDelivery, SubagentInbox } from "./subagent-inbox"
40
+ import { markReducedSteps } from "./turn-inbox"
41
41
  import type { AgentTurnRuntime } from "./turn-runtime"
42
42
  import type { AgentRunFiles, AgentTurnContext } from "./types"
43
43
 
@@ -18,6 +18,7 @@ import type {
18
18
  import { createSixbError } from "@sixb/core/internal/errors"
19
19
  import type { MaterializedArtifacts } from "./artifacts/materialize"
20
20
  import type { PreparedAgentAttachmentContext } from "./attachments"
21
+ import { SEARCH_SCRIPT_SOURCE } from "./search-script"
21
22
  import { TOOL_OUTPUTS_DIRECTORY } from "./tools/tool-outputs"
22
23
 
23
24
  /**
@@ -125,6 +126,8 @@ export async function prepareAgentSandboxApiContext(
125
126
  ...installFiles(ontologyDir, input.ontologyFiles),
126
127
  { path: join(binDir, "sixb"), contents: cli.launcher, mode: 0o755 },
127
128
  { path: join(libDir, "sixb.mjs"), contents: cli.artifact, mode: 0o644 },
129
+ // What `glob` and `grep` run.
130
+ { path: join(libDir, "search.mjs"), contents: SEARCH_SCRIPT_SOURCE, mode: 0o644 },
128
131
  { path: runContextPath, contents: runContext },
129
132
  { path: runtimeProbePath, contents: "first\nsixb-runtime-probe\nthird\n", mode: 0o644 },
130
133
  {
@@ -0,0 +1,5 @@
1
+ // What `search-script.ts` imports as text. Bun's loader reads it; the type checker needs telling.
2
+ declare module "*/generated/search.mjs" {
3
+ const text: string
4
+ export default text
5
+ }
@@ -0,0 +1,9 @@
1
+ /// <reference path="./search-script-assets.d.ts" />
2
+ import script from "./generated/search.mjs" with { type: "text" }
3
+
4
+ /**
5
+ * The engine of `glob` and `grep`, bundled from `tools/search/` by
6
+ * `bun run generate:search-script`. A run installs it at `lib/search.mjs` and runs it on Bun or
7
+ * Node. Part of this module, so that a program compiled to one file carries it too.
8
+ */
9
+ export const SEARCH_SCRIPT_SOURCE: Uint8Array = new TextEncoder().encode(script)
@@ -27,6 +27,18 @@ import operationsReview from "./sixb-artifacts/examples/document/operations-revi
27
27
  import restorationsFigure from "./sixb-artifacts/examples/document/operations-review/figures/restorations.svg" with {
28
28
  type: "text",
29
29
  }
30
+ import proposalDesign from "./sixb-artifacts/examples/document/service-proposal/design.css" with {
31
+ type: "text",
32
+ }
33
+ import proposalDocument from "./sixb-artifacts/examples/document/service-proposal/document.html" with {
34
+ type: "text",
35
+ }
36
+ import proposalLogo from "./sixb-artifacts/examples/document/service-proposal/images/fieldwise.svg" with {
37
+ type: "text",
38
+ }
39
+ import proposalClientLogo from "./sixb-artifacts/examples/document/service-proposal/images/harbor-pine.svg" with {
40
+ type: "text",
41
+ }
30
42
  import collectionsDeskPage from "./sixb-artifacts/examples/page/collections-desk/index.html" with {
31
43
  type: "text",
32
44
  }
@@ -102,6 +114,10 @@ export const BUILT_IN_SKILLS: readonly AgentSkillDefinition[] = Object.freeze([
102
114
  "examples/document/operations-review/document.md": operationsReview,
103
115
  "examples/document/operations-review/figures/restorations.svg": restorationsFigure,
104
116
  "examples/document/incident-report/document.md": incidentReport,
117
+ "examples/document/service-proposal/document.html": text(proposalDocument),
118
+ "examples/document/service-proposal/design.css": text(proposalDesign),
119
+ "examples/document/service-proposal/images/fieldwise.svg": proposalLogo,
120
+ "examples/document/service-proposal/images/harbor-pine.svg": proposalClientLogo,
105
121
  "sheet.md": sheetGuide,
106
122
  "references.md": referencesGuide,
107
123
  "slides.md": slidesGuide,
@@ -15,7 +15,7 @@ the question, answer in the chat.
15
15
 
16
16
  | Kind | Publish it for | Read first |
17
17
  | --- | --- | --- |
18
- | `document` | A report, brief, memo, plan, or write-up: anything read top to bottom | `document.md` |
18
+ | `document` | A report, brief, memo, plan, or write-up: anything read top to bottom; designed, a proposal, contract, or letter in a business's own look | `document.md` |
19
19
  | `sheet` | Tabular data the reader sorts, sums, charts, or downloads: metrics, lists, trackers, exports | `sheet.md` |
20
20
  | `slides` | A deck to present: a review, a pitch, a plan for a meeting | `slides.md` |
21
21
  | `page` | A small web app the reader works with: a calculator, a planner, a dashboard with filters | `page.md` |
@@ -45,8 +45,8 @@ go beside each picture.
45
45
  cannot, tell the user the deliverable could not be published; never describe it as ready.
46
46
  4. Fix what each warning names and update the artifact when it matters to the reader. A
47
47
  deck also comes back with a screenshot of each slide, a page with one at a laptop's width and
48
- one at a phone's, and a canvas with one of each board: look at them (`slides.md`, `page.md`,
49
- `canvas.md`, Check).
48
+ one at a phone's, a designed document with one of each page, and a canvas with one of each
49
+ board: look at them (`slides.md`, `page.md`, `document.md`, `canvas.md`, Check).
50
50
  5. In the reply, say in a sentence or two what you published and what stands out. Do not paste
51
51
  its content, a path, or its id as text: the user sees the artifact. To show a chart or a range
52
52
  of it in place, use its address (`references.md`). A figure you cite from live data is the one
@@ -76,12 +76,12 @@ publish_artifact({ id: "art_k3m9q2x7tp", path: "work/q3-review", title: "Q3 oper
76
76
  ```
77
77
 
78
78
  An entry with `"edited": true` was last written outside this conversation: most often a person's
79
- edit in the app, such as a sheet's cells or columns or a canvas's notes and layout, but also
80
- another conversation or the project's code. Start from it as it is, and keep its changes in yours
79
+ edit in the app, such as a sheet's cells or columns, a canvas's notes and layout, or a document's
80
+ blocks, designed or not, but also another conversation or the project's code. Start from it as it is, and keep its changes in yours
81
81
  unless the user asks you to undo them; say what you built on when you reply.
82
82
 
83
- When others changed a canvas while you worked, the update merges your changes with theirs
84
- and writes the merged result into the folder you updated from: keep editing it.
83
+ When others changed a canvas or a document while you worked, the update merges your changes with
84
+ theirs and writes the merged result into the folder you updated from: keep editing it.
85
85
 
86
86
  If another kind of artifact changes while you work, the update refuses rather than write
87
87
  over what it never saw, says who changed it, and installs it in place of your copy and in the
@@ -167,8 +167,9 @@ text on a board.
167
167
  Once a canvas publishes, Sixb opens each board at its own size in the sandbox's browser, in light
168
168
  and dark mode or the one its `theme.json` pins, and warns as it does for a page, naming the board.
169
169
  The result names each board's screenshot, `<id>.png`, and `overview.png`, the whole canvas as it
170
- opens, under `$SIXB_CONTEXT_DIR/checks/`. The check also takes each board's preview, the picture
171
- readers see until they open it, so a board that looks wrong there looks wrong on the canvas too.
170
+ opens, under `$SIXB_CONTEXT_DIR/checks/`. Each board's preview, the picture readers see until
171
+ they open it, is taken the same way a few seconds later, so a board that looks wrong there looks
172
+ wrong on the canvas too.
172
173
 
173
174
  1. Open the screenshots with `read` and look at each board as the reader will. Open
174
175
  `overview.png` to see whether the canvas reads at the zoom it opens at, and judge it as a
@@ -1,8 +1,11 @@
1
1
  # Documents
2
2
 
3
3
  A document is Markdown in `document.md`, with its images beside it. The app renders it as a page:
4
- a title and lede, a measured column, an outline of its sections, and figures, callouts, and tables
5
- set for reading.
4
+ a title and lede, a measured column, and figures, callouts, and tables set for reading.
5
+
6
+ A document that needs a design of its own, such as a proposal, a contract, a letter on letterhead,
7
+ or a report in a company's style, is HTML in `document.html` instead: see Designed documents below.
8
+ Everything else is Markdown.
6
9
 
7
10
  ## Structure
8
11
 
@@ -19,6 +22,9 @@ set for reading.
19
22
  GitHub-flavored Markdown: tables, task lists, strikethrough, autolinks, footnotes (`[^1]`), and
20
23
  fenced code blocks with a language. Raw HTML is not rendered.
21
24
 
25
+ Once people edit a document in the app, it is written back as its editor writes Markdown: `-`
26
+ bullets, `*emphasis*`, `**bold**`, `#` headings. Read it again before you change words in place.
27
+
22
28
  | Write | It renders as |
23
29
  | --- | --- |
24
30
  | `> [!NOTE]` as the first line of a quote | A callout. Also `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]` |
@@ -44,7 +50,7 @@ both light and dark pages, and label the axes and units.
44
50
 
45
51
  ## Theme
46
52
 
47
- A document takes the app's theme, light and dark. Only when the user asks for a look, add
53
+ A Markdown document takes the app's theme, light and dark. Only when the user asks for a look, add
48
54
  `theme.json` at the artifact's root:
49
55
 
50
56
  ```json
@@ -57,7 +63,88 @@ A document takes the app's theme, light and dark. Only when the user asks for a
57
63
  `--font-serif`, `--font-mono`, and `--radius`. Colors are hex, `rgb()`, `hsl()`, or `oklch()`;
58
64
  fonts are family names; `--radius` is a length such as `6px`.
59
65
 
66
+ ## Designed documents
67
+
68
+ Write one when the user asks for a document that should look like a business's own, or a project
69
+ skill gives you a design or a template for it. It renders exactly as its stylesheets say, on white
70
+ paper, in the app and as the pages it prints on.
71
+
72
+ ```text
73
+ work/proposal/
74
+ ├── document.html the document: semantic HTML, no document.md beside it
75
+ ├── design.css its design, linked with <link rel="stylesheet" href="design.css">
76
+ ├── fonts/ @font-face files, when the design names a font
77
+ └── images/ logos, figures, screenshots
78
+ ```
79
+
80
+ - **Paper.** Give the stylesheet an `@page` rule with a size and the margins:
81
+ `@page { size: letter; margin: 0.75in 0.85in; }` (or `A4`, or two lengths). That is what makes
82
+ pages: the reader sees them, downloads them as a PDF, and the layout check shoots each one. Keep
83
+ the margins there, not on `<body>`, and give `<body>` no width, margin, or padding of its own.
84
+ - **Editable.** People edit it block by block in the app. Write the `<body>` and `</body>` tags,
85
+ with nothing after `</body>` but `</html>`, and words in elements of their own (`<p>`, `<li>`,
86
+ `<td>`), not loose beside blocks: what does not fit is still kept, but edited word by word.
87
+ - **Markup.** Any HTML that lays out text, tables, figures, and pictures, styled by any CSS: grids,
88
+ columns, `::before` numbering, `<svg>`. No scripts, `on…` handlers, `<iframe>`, `<form>`, or
89
+ `<base>`: publishing refuses them. Images are files in the artifact (or another artifact's,
90
+ `artifact:<id>/<path>`); stylesheets are files in the artifact or Google Fonts.
91
+ - **Style by class**, not by `body > …`: as pages, the body's content is moved into the flow that
92
+ is cut into pages, so a selector on the body's children stops matching.
93
+ - **Pages break where you say.** `break-before: page` starts a section on a new page;
94
+ `break-inside: avoid` keeps a table row, a figure, or the signature block whole; `thead { display:
95
+ table-header-group; }` repeats a table's header on each page it runs onto. Nothing may be wider
96
+ than the space between the margins.
97
+ - **Phones.** On a phone it shows as one sheet at the screen's width, with your CSS. Stack every
98
+ multi-column grid in `@media screen and (max-width: 600px) { … }`, and size images with
99
+ `max-width: 100%`, so nothing runs off the side. Keep `screen` in it: paper as narrow as A5
100
+ would match it when printed.
101
+ - **Type in points**, as print is: body text around 10pt, labels no smaller than 6.5pt.
102
+ - **Headings** `h1`–`h3` make the outline and the sections an address can name, as in Markdown.
103
+ - **A project's design** comes as files in a project skill: copy its stylesheet, fonts, and images,
104
+ or its template, into your directory, and write the content into it. Never link to the skill's
105
+ folder: a version holds everything it shows, so a later change to the design never changes a
106
+ document already sent.
107
+
108
+ ### Live data
109
+
110
+ A designed document an object holds, such as a contract's proposal, shows that object's values as
111
+ each reader reads them, never a copy. Name its type in `<head>`, then mark each value; write in each
112
+ one what it should read, which it keeps where no object holds it yet (a template) and while it is
113
+ edited:
114
+
115
+ ```html
116
+ <meta name="sixb:object-type" content="Contract">
117
+ <h1 data-sixb-field="client.name">Harbor Co</h1>
118
+ <p>A fixed fee of <span data-sixb-field="fee" data-format="money" data-currency-field="currency">$4,000</span>.</p>
119
+ <tr data-sixb-each="milestones"><td data-sixb-field="title">Kickoff</td></tr>
120
+ <tr data-sixb-each="query:past-work"><td data-sixb-field="title">Phase 1</td>
121
+ <td data-sixb-field="signedAt" data-format="date">March 2, 2026</td></tr>
122
+ <span data-sixb-field="query:past-work.total">3</span>
123
+ ```
124
+
125
+ - A path reads the holder's properties, `scope.services[job-flow].amount` (a list's item by its
126
+ `id`), and through one link, `client.name`. Fields in a `data-sixb-each` element read its item.
127
+ - `data-sixb-each="query:<name>"` repeats per row of `queries/<name>.json` (`queries.md`), which
128
+ may start from the holder: `{ "kind": "traverse", "input": { "kind": "holder" }, … }`.
129
+ `query:<name>.total` is how many rows it matched; `query:<name>.facets.<property>` repeats per
130
+ facet value, with `value` and `count`.
131
+ - `data-format` is `money` (with `data-currency="USD"` or `data-currency-field`), `number`,
132
+ `percent` (0.25 reads 25%), or `date`, formatted for `<html lang>`. A total or an instalment is
133
+ a property the object keeps: a document computes nothing.
134
+ - Publishing warns `field_unknown` for a path the type doesn't hold. Freezing the version writes
135
+ the values in and keeps the fields, so the next version is live again; its PDF shows them as
136
+ whoever asks reads them.
137
+ - After a freeze, a `data-sixb-each` element appears once per item, one after the other: they are
138
+ one element, copied from the first, so change the first. One marked `data-sixb-empty` is a list
139
+ that was empty: keep it.
140
+
141
+ After publishing, open each `page-NN.png` the check returns: look at where each page breaks, for
142
+ anything cut off at a page's edge, and for a page left nearly empty. Open `phone.png` too, for
143
+ anything running off the side, then fix and update.
144
+
60
145
  ## Examples
61
146
 
62
- `examples/document/` holds two finished documents to start from: an operations review with a figure
63
- and a table, and an incident report with a timeline and follow-ups.
147
+ `examples/document/` holds three finished documents to start from: an operations review with a
148
+ figure and a table, an incident report with a timeline and follow-ups, and `service-proposal`, a
149
+ designed document on Letter paper: a cover, sections that each start a page, a timeline, pricing
150
+ tables, and a signature block.