@sixb/agent 0.2.4 → 0.2.6

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 (117) hide show
  1. package/README.md +2 -2
  2. package/dist/agent-prompt.d.ts +13 -3
  3. package/dist/agent-prompt.d.ts.map +1 -1
  4. package/dist/artifacts/layout-check/layout-check.d.ts +21 -24
  5. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  6. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  7. package/dist/background-commands.d.ts +2 -2
  8. package/dist/context-compaction.d.ts.map +1 -1
  9. package/dist/conversation-messages.d.ts +1 -1
  10. package/dist/conversation-messages.d.ts.map +1 -1
  11. package/dist/index.d.ts +0 -1
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +11082 -9281
  14. package/dist/index.js.map +37 -33
  15. package/dist/login-shell.d.ts +18 -2
  16. package/dist/login-shell.d.ts.map +1 -1
  17. package/dist/model-adapters.d.ts +5 -2
  18. package/dist/model-adapters.d.ts.map +1 -1
  19. package/dist/model-lines.d.ts +1 -0
  20. package/dist/model-lines.d.ts.map +1 -1
  21. package/dist/run-agent-turn.d.ts +3 -14
  22. package/dist/run-agent-turn.d.ts.map +1 -1
  23. package/dist/run-conversation-turn.d.ts.map +1 -1
  24. package/dist/run-environment.d.ts.map +1 -1
  25. package/dist/run-sandbox.d.ts +11 -1
  26. package/dist/run-sandbox.d.ts.map +1 -1
  27. package/dist/run-subagent.d.ts.map +1 -1
  28. package/dist/sandbox-api-context.d.ts.map +1 -1
  29. package/dist/search-script.d.ts +7 -0
  30. package/dist/search-script.d.ts.map +1 -0
  31. package/dist/skills/built-in.d.ts.map +1 -1
  32. package/dist/subagent-tools.d.ts +11 -1
  33. package/dist/subagent-tools.d.ts.map +1 -1
  34. package/dist/tools/bash.d.ts +1 -1
  35. package/dist/tools/bash.d.ts.map +1 -1
  36. package/dist/tools/glob.d.ts +41 -0
  37. package/dist/tools/glob.d.ts.map +1 -0
  38. package/dist/tools/grep.d.ts +64 -0
  39. package/dist/tools/grep.d.ts.map +1 -0
  40. package/dist/tools/model-spec.d.ts.map +1 -1
  41. package/dist/tools/sandbox-search.d.ts +26 -0
  42. package/dist/tools/sandbox-search.d.ts.map +1 -0
  43. package/dist/tools/search/command.d.ts +15 -0
  44. package/dist/tools/search/command.d.ts.map +1 -0
  45. package/dist/tools/search/gitignore.d.ts +28 -0
  46. package/dist/tools/search/gitignore.d.ts.map +1 -0
  47. package/dist/tools/search/glob.d.ts +15 -0
  48. package/dist/tools/search/glob.d.ts.map +1 -0
  49. package/dist/tools/search/main.d.ts +2 -0
  50. package/dist/tools/search/main.d.ts.map +1 -0
  51. package/dist/tools/search/match.d.ts +30 -0
  52. package/dist/tools/search/match.d.ts.map +1 -0
  53. package/dist/tools/search/pattern.d.ts +19 -0
  54. package/dist/tools/search/pattern.d.ts.map +1 -0
  55. package/dist/tools/search/read.d.ts +62 -0
  56. package/dist/tools/search/read.d.ts.map +1 -0
  57. package/dist/tools/search/request.d.ts +80 -0
  58. package/dist/tools/search/request.d.ts.map +1 -0
  59. package/dist/tools/search/search.d.ts +4 -0
  60. package/dist/tools/search/search.d.ts.map +1 -0
  61. package/dist/tools/search/walk.d.ts +43 -0
  62. package/dist/tools/search/walk.d.ts.map +1 -0
  63. package/dist/tools/tool-outputs.d.ts.map +1 -1
  64. package/dist/turn-inbox.d.ts +75 -0
  65. package/dist/turn-inbox.d.ts.map +1 -0
  66. package/package.json +7 -5
  67. package/src/agent-prompt.ts +63 -28
  68. package/src/agent-runtime/preflight.ts +1 -0
  69. package/src/artifacts/layout-check/check.cjs +176 -95
  70. package/src/artifacts/layout-check/layout-check.ts +118 -76
  71. package/src/artifacts/publish-tool.ts +48 -99
  72. package/src/background-commands.ts +8 -6
  73. package/src/context-compaction.ts +1 -0
  74. package/src/conversation-messages.ts +11 -4
  75. package/src/generated/search.mjs +985 -0
  76. package/src/index.ts +0 -1
  77. package/src/login-shell.ts +30 -3
  78. package/src/model-adapters.ts +23 -4
  79. package/src/model-lines.ts +1 -1
  80. package/src/run-agent-turn.ts +85 -129
  81. package/src/run-conversation-turn.ts +15 -6
  82. package/src/run-environment.ts +42 -11
  83. package/src/run-sandbox.ts +60 -1
  84. package/src/run-subagent.ts +9 -2
  85. package/src/sandbox-api-context.ts +10 -1
  86. package/src/search-script-assets.d.ts +5 -0
  87. package/src/search-script.ts +9 -0
  88. package/src/skills/built-in.ts +16 -0
  89. package/src/skills/sixb-artifacts/SKILL.md +7 -7
  90. package/src/skills/sixb-artifacts/canvas.md +3 -2
  91. package/src/skills/sixb-artifacts/document.md +92 -5
  92. package/src/skills/sixb-artifacts/examples/document/service-proposal/design.css +114 -0
  93. package/src/skills/sixb-artifacts/examples/document/service-proposal/document.html +159 -0
  94. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/fieldwise.svg +1 -0
  95. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/harbor-pine.svg +1 -0
  96. package/src/skills/sixb-artifacts/queries.md +2 -1
  97. package/src/subagent-tools.ts +23 -5
  98. package/src/tools/bash.ts +9 -10
  99. package/src/tools/glob.ts +124 -0
  100. package/src/tools/grep.ts +190 -0
  101. package/src/tools/model-spec.ts +4 -0
  102. package/src/tools/sandbox-search.ts +219 -0
  103. package/src/tools/search/command.ts +116 -0
  104. package/src/tools/search/gitignore.ts +101 -0
  105. package/src/tools/search/glob.ts +90 -0
  106. package/src/tools/search/main.ts +9 -0
  107. package/src/tools/search/match.ts +278 -0
  108. package/src/tools/search/pattern.ts +178 -0
  109. package/src/tools/search/read.ts +237 -0
  110. package/src/tools/search/request.ts +101 -0
  111. package/src/tools/search/search.ts +297 -0
  112. package/src/tools/search/walk.ts +145 -0
  113. package/src/tools/tool-outputs.ts +7 -2
  114. package/src/turn-inbox.ts +283 -0
  115. package/dist/artifacts/board-previews.d.ts +0 -41
  116. package/dist/artifacts/board-previews.d.ts.map +0 -1
  117. package/src/artifacts/board-previews.ts +0 -218
@@ -1,5 +1,5 @@
1
1
  import { posix } from "node:path"
2
- import type { Principal } from "@sixb/core"
2
+ import type { Principal, SandboxNotRunningError } from "@sixb/core"
3
3
  import {
4
4
  type AgentContextBudget,
5
5
  type AgentRunArtifacts,
@@ -67,7 +67,9 @@ import {
67
67
  type AcquiredRunSandbox,
68
68
  acquireRunSandbox,
69
69
  type BeforeFinalizeOptions,
70
+ endsWhenStopped,
70
71
  type RunSandbox,
72
+ sandboxStoppedError,
71
73
  } from "./run-sandbox"
72
74
  import {
73
75
  AGENT_ARTIFACTS_DIRECTORY,
@@ -91,6 +93,8 @@ import { createStopTool, createWaitTool, type WaitableChildren } from "./tools/b
91
93
  import { createBashTool } from "./tools/bash"
92
94
  import { createEditTool } from "./tools/edit"
93
95
  import { FileReadLedger } from "./tools/file-writes"
96
+ import { createGlobTool } from "./tools/glob"
97
+ import { createGrepTool } from "./tools/grep"
94
98
  import { agentModelToolSpecs, fetchesWeb } from "./tools/model-spec"
95
99
  import { createReadTool, READ_TOOL_SPEC } from "./tools/read"
96
100
  import {
@@ -113,6 +117,13 @@ import type { AgentTurnRuntime } from "./turn-runtime"
113
117
  import type { AgentExecutionContext, AgentRunFiles, AgentTurnContext } from "./types"
114
118
  import { prepareWorkflowInputAttachments } from "./workflow-input-attachments"
115
119
 
120
+ // What each kind of run says when its provider stopped its sandbox, to whoever goes on from it: the
121
+ // person in a conversation, the parent of a child, the run of a workflow step.
122
+ const SANDBOX_STOPPED_TURN_MESSAGE =
123
+ "The sandbox stopped, so this turn ended here. Its work so far is kept: send a message to go on."
124
+ const SANDBOX_STOPPED_CHILD_MESSAGE = "The sandbox stopped, so this agent ended here."
125
+ const SANDBOX_STOPPED_STEP_MESSAGE = "The sandbox stopped, so this step ended here."
126
+
116
127
  export interface AgentExecutionEnvironment {
117
128
  readonly turnContext: AgentTurnContext
118
129
  /** The run's sandbox and file budget, for the files a parent and its children hand each other. */
@@ -403,13 +414,12 @@ export async function createConversationAgentEnvironment(
403
414
  },
404
415
  sandboxSignal,
405
416
  failureSignal: failure.signal,
417
+ onSandboxStopped: (error) =>
418
+ failure.abort(sandboxStoppedError(error, SANDBOX_STOPPED_TURN_MESSAGE)),
406
419
  context,
407
420
  plan,
408
421
  runId: run.id,
409
422
  threadId: run.threadId,
410
- ...(input.thread?.movedAt
411
- ? { workspaceMovedAt: new Date(input.thread.movedAt).toISOString() }
412
- : {}),
413
423
  callTool: (call, options) => input.session.callTool(call, options),
414
424
  webSearch: input.session.models.webSearch,
415
425
  ...(publishing ? { publishing } : {}),
@@ -475,7 +485,9 @@ export async function createConversationAgentEnvironment(
475
485
  export async function createSubagentEnvironment(
476
486
  input: CreateSubagentEnvironmentInput
477
487
  ): Promise<SubagentAgentExecutionEnvironment> {
478
- // A child's workspace is blank, so it has no source credentials to lose.
488
+ // A child's workspace is blank, so it has no source credentials to lose. It ends only when its
489
+ // provider stops the sandbox.
490
+ const failure = new AbortController()
479
491
  const { sandbox, resumed = false } = await input.openSandbox({
480
492
  signal: input.signal ?? NEVER_ABORTED_SIGNAL,
481
493
  onFailure: () => {},
@@ -494,6 +506,9 @@ export async function createSubagentEnvironment(
494
506
  ...input,
495
507
  sandbox,
496
508
  resumed,
509
+ failureSignal: failure.signal,
510
+ onSandboxStopped: (error) =>
511
+ failure.abort(sandboxStoppedError(error, SANDBOX_STOPPED_CHILD_MESSAGE)),
497
512
  acquireBeforeStart: acquire,
498
513
  acquire: () => {
499
514
  provisioning = true
@@ -519,6 +534,9 @@ async function startSubagentEnvironment(
519
534
  readonly sandbox: RunSandbox
520
535
  /** Whether the sandbox is the workspace the paused run left: it holds its files already. */
521
536
  readonly resumed: boolean
537
+ /** Ends the child when its provider stops the sandbox. */
538
+ readonly failureSignal: AbortSignal
539
+ readonly onSandboxStopped: (error: SandboxNotRunningError) => void
522
540
  /** How the summary acquires the workspace its prompt describes, before the environment. */
523
541
  readonly acquireBeforeStart: () => Promise<AcquiredRunSandbox>
524
542
  /** How provisioning acquires it, which from then gives it back. */
@@ -681,6 +699,8 @@ async function startSubagentEnvironment(
681
699
  ...(networkPolicy ? { networkPolicy } : {}),
682
700
  acquire: input.acquire,
683
701
  sandboxSignal: input.signal,
702
+ failureSignal: input.failureSignal,
703
+ onSandboxStopped: input.onSandboxStopped,
684
704
  context,
685
705
  plan,
686
706
  runId: run.id,
@@ -759,6 +779,8 @@ export async function createWorkflowAgentNodeEnvironment(
759
779
  sandbox,
760
780
  sandboxSignal,
761
781
  failureSignal: failure.signal,
782
+ onSandboxStopped: (error) =>
783
+ failure.abort(sandboxStoppedError(error, SANDBOX_STOPPED_STEP_MESSAGE)),
762
784
  context,
763
785
  actorId: run.actorId,
764
786
  plan,
@@ -796,6 +818,11 @@ interface AgentEnvironmentSetup
796
818
  readonly sandboxSignal?: AbortSignal
797
819
  /** Environment-owned failure, such as lost source credentials. */
798
820
  readonly failureSignal?: AbortSignal
821
+ /**
822
+ * Ends the run when a command or a file write finds that the provider stopped the sandbox, such
823
+ * as at the end of a Vercel session: whichever tool met it, nothing more runs in it.
824
+ */
825
+ readonly onSandboxStopped?: (error: SandboxNotRunningError) => void
799
826
  /** How the run calls a project tool. */
800
827
  readonly callTool: AgentToolCaller
801
828
  /** How it searches the web, where the project is: `web_search` calls it. */
@@ -834,8 +861,6 @@ interface AgentEnvironmentSetup
834
861
  }
835
862
  /** A conversation's memory, or a child's to read: installed in the sandbox and in the prompt. */
836
863
  readonly memory?: ConversationMemory
837
- /** When the conversation's turns last moved to where they run now: see its `movedAt`. */
838
- readonly workspaceMovedAt?: string
839
864
  /** Who takes part in a conversation several people write in, for its prompt. */
840
865
  readonly conversation?: string
841
866
  }
@@ -929,6 +954,8 @@ async function startAgentEnvironment(
929
954
  appendBuiltInTool(tools, createReadTool(resolveSandbox, fileReads, fileViewer))
930
955
  appendBuiltInTool(tools, createEditTool(resolveSandbox, fileReads))
931
956
  appendBuiltInTool(tools, createWriteTool(resolveSandbox, fileReads))
957
+ appendBuiltInTool(tools, createGlobTool(resolveSandbox))
958
+ appendBuiltInTool(tools, createGrepTool(resolveSandbox))
932
959
  appendBuiltInTool(tools, createBashTool(resolveSandbox, background))
933
960
  appendBuiltInTool(tools, createWaitTool(resolveSandbox, background, input.children))
934
961
  appendBuiltInTool(tools, createStopTool(resolveSandbox, background, input.children))
@@ -991,6 +1018,7 @@ async function startAgentEnvironment(
991
1018
  ontologyFiles: input.ontologyDocs?.files ?? [],
992
1019
  ...(installedArtifacts ? { artifacts: installedArtifacts } : {}),
993
1020
  ...(input.memory ? { memory: input.memory.repos } : {}),
1021
+ ...(input.onSandboxStopped ? { onSandboxStopped: input.onSandboxStopped } : {}),
994
1022
  })
995
1023
  // Creation failure is surfaced where it is awaited (turn / sandbox tool / dispose); attach a no-op
996
1024
  // catch so a rejection observed by none of them is not reported as unhandled.
@@ -1020,7 +1048,6 @@ async function startAgentEnvironment(
1020
1048
  plan,
1021
1049
  ...(input.ontologyDocs ? { ontologyDocs: input.ontologyDocs } : {}),
1022
1050
  ...(workspace ? { workspace } : {}),
1023
- ...(input.workspaceMovedAt ? { workspaceMovedAt: input.workspaceMovedAt } : {}),
1024
1051
  ...(input.conversation === undefined ? {} : { conversation: input.conversation }),
1025
1052
  ...(input.memory ? { memory: input.memory } : {}),
1026
1053
  })
@@ -1104,7 +1131,6 @@ function measureEnvironmentSystemPrompt(input: {
1104
1131
  readonly ontologyDocs?: RenderedOntologyDocs
1105
1132
  /** The acquired workspace, when the prompt describes it. */
1106
1133
  readonly workspace?: Pick<AcquiredRunSandbox, "promptContext" | "resetAt">
1107
- readonly workspaceMovedAt?: string
1108
1134
  readonly conversation?: string
1109
1135
  readonly memory?: ConversationMemory
1110
1136
  }): AgentSystemPromptSize {
@@ -1121,12 +1147,12 @@ function measureEnvironmentSystemPrompt(input: {
1121
1147
  ? { ontologyIndex: input.ontologyDocs.index }
1122
1148
  : {}),
1123
1149
  sandboxResetAt: workspace?.resetAt,
1124
- ...(input.workspaceMovedAt ? { workspaceMovedAt: input.workspaceMovedAt } : {}),
1125
1150
  workspace: workspace?.promptContext,
1126
1151
  facts: requester === undefined ? {} : { requester },
1127
1152
  ...(input.conversation === undefined ? {} : { conversation: input.conversation }),
1128
1153
  ...(plan.sandboxModels ? { sandboxModels: plan.sandboxModels } : {}),
1129
1154
  ...(input.memory ? { memory: input.memory.prompt } : {}),
1155
+ runningModel: plan.model,
1130
1156
  })
1131
1157
  }
1132
1158
 
@@ -1220,6 +1246,7 @@ interface ProvisionSandboxInput {
1220
1246
  /** The conversation's artifacts, read while the sandbox starts. */
1221
1247
  readonly artifacts?: Promise<MaterializedArtifacts>
1222
1248
  readonly memory?: PrepareAgentSandboxApiContextInput["memory"]
1249
+ readonly onSandboxStopped?: (error: SandboxNotRunningError) => void
1223
1250
  }
1224
1251
 
1225
1252
  /** A sandbox acquired for the run, with the run's files installed in its context directory. */
@@ -1228,7 +1255,10 @@ type ProvisionedRunSandbox = AcquiredRunSandbox & AgentSandboxHandle
1228
1255
  async function provisionSandbox(input: ProvisionSandboxInput): Promise<ProvisionedRunSandbox> {
1229
1256
  const { context, actorId, run, apiBaseUrl, skills, ontologyFiles } = input
1230
1257
  const acquired = await (input.acquire?.() ?? acquireRunSandbox(input.sandbox, input.signal))
1231
- const { sandbox } = acquired
1258
+ // What the run's tools and files reach the sandbox through.
1259
+ const sandbox = input.onSandboxStopped
1260
+ ? endsWhenStopped(acquired.sandbox, input.onSandboxStopped)
1261
+ : acquired.sandbox
1232
1262
  const { contextDirectory } = input.sandbox
1233
1263
  try {
1234
1264
  const apiContext = await prepareAgentSandboxApiContext({
@@ -1252,6 +1282,7 @@ async function provisionSandbox(input: ProvisionSandboxInput): Promise<Provision
1252
1282
  })
1253
1283
  const provisioned = {
1254
1284
  ...acquired,
1285
+ sandbox,
1255
1286
  contextDirectory,
1256
1287
  env: { ...acquired.env, ...apiContext.env },
1257
1288
  }
@@ -1,4 +1,5 @@
1
- import type { Sandbox } from "@sixb/core"
1
+ import { type Sandbox, SandboxNotRunningError } from "@sixb/core"
2
+ import { createSixbError, withFailureMessage } from "@sixb/core/internal/errors"
2
3
  import type { SandboxNetworkPolicy } from "@sixb/core/sandboxes"
3
4
  import type { AgentWorkspacePromptContext } from "./agent-prompt"
4
5
  import type { BackgroundCommands } from "./background-commands"
@@ -102,3 +103,61 @@ export async function acquireRunSandbox(
102
103
 
103
104
  return { ...acquired, promptContext: { ...promptContext, instructions } }
104
105
  }
106
+
107
+ /**
108
+ * The run's sandbox, which calls `onStopped` each time a command or a file write finds that its
109
+ * provider stopped it, such as at the end of a Vercel session. Whichever tool met it, nothing more
110
+ * runs in it: the run ends instead of the model retrying there.
111
+ */
112
+ export function endsWhenStopped(
113
+ session: Sandbox,
114
+ onStopped: (error: SandboxNotRunningError) => void
115
+ ): Sandbox {
116
+ // Watched beside its caller, which gets the provider's own promise: its wait gains no step, and
117
+ // the run has ended before the caller reads the failure.
118
+ const watch = <T>(operation: () => Promise<T>): Promise<T> => {
119
+ const result = operation()
120
+ result.catch((error: unknown) => {
121
+ if (error instanceof SandboxNotRunningError) onStopped(error)
122
+ })
123
+ return result
124
+ }
125
+
126
+ return {
127
+ id: session.id,
128
+ provider: session.provider,
129
+ get status() {
130
+ return session.status
131
+ },
132
+ workingDirectory: session.workingDirectory,
133
+ ...(session.setRequestCredentials
134
+ ? { setRequestCredentials: session.setRequestCredentials.bind(session) }
135
+ : {}),
136
+ ...(session.credentialedUrl ? { credentialedUrl: session.credentialedUrl.bind(session) } : {}),
137
+ runCommand: (command, args, options) => watch(() => session.runCommand(command, args, options)),
138
+ writeFiles: (files) => watch(() => session.writeFiles(files)),
139
+ stop: () => session.stop(),
140
+ destroy: () => session.destroy(),
141
+ }
142
+ }
143
+
144
+ const stops = new WeakMap<Error, SandboxNotRunningError>()
145
+
146
+ /** Why a run whose sandbox stopped ended, in the words its run and its reader see. */
147
+ export function sandboxStoppedError(cause: SandboxNotRunningError, message: string): Error {
148
+ const error = withFailureMessage(
149
+ createSixbError(
150
+ "agent.execution_failed",
151
+ "[SixbAgent] The run's sandbox stopped; nothing more can run in it.",
152
+ { cause }
153
+ ),
154
+ message
155
+ )
156
+ stops.set(error, cause)
157
+ return error
158
+ }
159
+
160
+ /** The provider's stop a run ended on, when `sandboxStoppedError` says that is why it ended. */
161
+ export function sandboxStopOf(error: unknown): SandboxNotRunningError | undefined {
162
+ return error instanceof Error ? stops.get(error) : undefined
163
+ }
@@ -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
 
@@ -132,7 +132,11 @@ export async function runSubagent(input: {
132
132
  : {}),
133
133
  })
134
134
  const sandboxReadiness = monitorSandboxReadiness(context.sandboxReady)
135
- const abortSignal = AbortSignal.any([runtime.signal, sandboxReadiness.signal])
135
+ const abortSignal = AbortSignal.any([
136
+ runtime.signal,
137
+ sandboxReadiness.signal,
138
+ ...(context.environmentFailureSignal ? [context.environmentFailureSignal] : []),
139
+ ])
136
140
  let chunkIndex = 0
137
141
  const generation = await runModelLoop({
138
142
  model: plan.model,
@@ -177,6 +181,7 @@ export async function runSubagent(input: {
177
181
  pauseAfterStep: async () =>
178
182
  inbox.deferred !== undefined || (await input.session.heldCalls.holdsRun()),
179
183
  }).catch((error: unknown) => {
184
+ context.environmentFailureSignal?.throwIfAborted()
180
185
  throw subagentContextFailure(error, run) ?? error
181
186
  })
182
187
  const work = subagentWorkMessages(
@@ -377,11 +382,13 @@ function subagentWorkMessages(
377
382
  }
378
383
 
379
384
  function assertSubagentCanFinalize(input: {
385
+ readonly context: AgentTurnContext
380
386
  readonly runtime: AgentTurnRuntime
381
387
  readonly sandboxReadiness: ReturnType<typeof monitorSandboxReadiness>
382
388
  }): void {
383
389
  throwIfExecutionLost(input.runtime.sourceSignal)
384
390
  input.sandboxReadiness.throwIfFailed()
391
+ input.context.environmentFailureSignal?.throwIfAborted()
385
392
  input.runtime.assertCanContinue()
386
393
  }
387
394
 
@@ -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,14 +126,22 @@ 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 },
133
+ // Bash reads this file in every non-interactive shell, nested ones included. Adding the CLI only
134
+ // when PATH lacks it leaves a nested shell's PATH as its parent ordered it: `bun run <script>`
135
+ // puts `node_modules/.bin` first, so a project's own `sixb` keeps running its scripts.
130
136
  {
131
137
  path: bashEnvPath,
132
138
  contents: [
133
139
  "# Installed by Sixb for every sandboxed bash command.",
134
140
  `if [ -n "\${SIXB_BIN_DIR:-}" ]; then`,
135
- ' export PATH="$SIXB_BIN_DIR:$PATH"',
141
+ ' case ":$PATH:" in',
142
+ ' *":$SIXB_BIN_DIR:"*) ;;',
143
+ ' *) export PATH="$SIXB_BIN_DIR:$PATH" ;;',
144
+ " esac",
136
145
  "fi",
137
146
  "export SIXB_BASH_ENV_READY=1",
138
147
  "",
@@ -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.