@boxes-dev/dvb-runtime 1.0.1103 → 1.0.1105
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.
- package/dist/agent-init-guides/agent-config.md +34 -0
- package/dist/agent-init-guides/app.md +6 -5
- package/dist/agent-init-guides/flow.md +72 -12
- package/dist/agent-init-guides/git-ssh.md +9 -4
- package/dist/agent-init-guides/manifest.md +6 -0
- package/dist/agent-init-guides/recovery.md +22 -0
- package/dist/agent-init-guides/running.md +12 -0
- package/dist/agent-init-guides/untracked.md +2 -1
- package/dist/bin/dvb.mjs +1228 -1758
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/agent-tools.md +32 -5
- package/dist/product-docs/references/automations.md +18 -3
- package/dist/product-docs/references/cli.md +6 -4
- package/dist/product-docs/references/core-concepts.md +1 -1
- package/dist/product-docs/references/desktop-workbench.md +28 -3
- package/dist/product-docs/references/environment-setup-validation.md +22 -0
- package/dist/product-docs/references/files-git-and-review.md +32 -18
- package/dist/product-docs/references/fork-workflows.md +6 -3
- package/dist/product-docs/references/getting-started.md +2 -1
- package/dist/product-docs/references/index.md +2 -1
- package/dist/product-docs/references/linear.md +15 -0
- package/dist/product-docs/references/member-managed-files.md +2 -1
- package/dist/product-docs/references/mobile.md +63 -17
- package/dist/product-docs/references/onbox-agent-tools.md +224 -66
- package/dist/product-docs/references/ports-terminal-and-runtime.md +5 -3
- package/dist/product-docs/references/project-setup.md +67 -17
- package/dist/product-docs/references/security-and-data.md +3 -2
- package/dist/product-docs/references/slack.md +8 -5
- package/dist/product-docs/references/threads-and-agents.md +25 -8
- package/dist/product-docs/references/troubleshooting.md +7 -5
- package/dist/product-docs/references/unattended-work.md +5 -0
- package/dist/prompts/local-services-scan.md +3 -4
- package/package.json +2 -2
|
@@ -19,6 +19,40 @@ selection with a label comment per item, and lists what was left out.
|
|
|
19
19
|
are restored as config and re-authenticated on the Template box after setup
|
|
20
20
|
(the user completes that from the desktop app).
|
|
21
21
|
|
|
22
|
+
`dvb agent-init detect agent-config` lists names, selection ids, and sizes;
|
|
23
|
+
add `--json` for source paths and exact byte counts. Sizes include linked
|
|
24
|
+
support files. Use the detected individual ids, such as `claude:skill:review`
|
|
25
|
+
or `codex:skill:.system/writer`, to choose a subset in `agentConfig.include`.
|
|
26
|
+
These examples illustrate the format; use the actual ids from detection.
|
|
27
|
+
Remove `claude:skills` or `codex:skills` for an agent whose skills you are
|
|
28
|
+
selecting individually. Those whole-folder ids remain supported and will
|
|
29
|
+
include the entire folder if retained, regardless of individual selections.
|
|
30
|
+
Selected skills retain their support files; the local originals are unchanged.
|
|
31
|
+
Whole-folder selections in saved manifests keep their existing meaning.
|
|
32
|
+
|
|
33
|
+
Review the detected configuration and recommend what will help with this
|
|
34
|
+
project and the user's development workflow. Skills for testing, browser
|
|
35
|
+
automation, or code review can be useful even when the app itself does not
|
|
36
|
+
depend on them. Read relevant skill descriptions and consider the tools they
|
|
37
|
+
need on the Template box; neither detection nor optional status alone decides
|
|
38
|
+
whether something belongs in the import.
|
|
39
|
+
|
|
40
|
+
Consider size alongside usefulness. A skill collection can include supporting
|
|
41
|
+
tools, dependencies, browser files, and caches, including linked contents;
|
|
42
|
+
its upload size is not just its Markdown instructions. Inspect relevant skill
|
|
43
|
+
descriptions read-only. Explain any large collection's value and upload cost
|
|
44
|
+
so the user can decide; size alone
|
|
45
|
+
is not a reason to exclude useful configuration or strip required support
|
|
46
|
+
files out of a skill.
|
|
47
|
+
|
|
48
|
+
Propose a reasonable selection, explain notable inclusions and exclusions in
|
|
49
|
+
the existing grouped review, and confirm large or uncertain choices with the
|
|
50
|
+
user. Reuse earlier answers. Do not clear the import merely to minimize bytes.
|
|
51
|
+
|
|
52
|
+
Do not modify the user's installed skills or remove required support files
|
|
53
|
+
to reduce upload size. Review whole-folder selections with the user before
|
|
54
|
+
narrowing the import.
|
|
55
|
+
|
|
22
56
|
Present to the user as a grouped list (per agent: MCP servers, skills,
|
|
23
57
|
settings, memory) and confirm anything credential-bearing. Mention skipped
|
|
24
58
|
Claude hooks during review: their commands may need scripts or tools that are
|
|
@@ -6,9 +6,10 @@ this to get the app running on the Template box and verify the setup worked.
|
|
|
6
6
|
- `app.entrypoints`: the terminal command(s) a developer runs to work on
|
|
7
7
|
the app (`npm run dev`, `just dev`, `cargo run`, ...) with a one-line
|
|
8
8
|
description (what it serves, which port).
|
|
9
|
-
- `app.services`:
|
|
10
|
-
compose services, workers, queues,
|
|
11
|
-
starts it and its HTTP port when it
|
|
9
|
+
- `app.services`: supporting processes the project expects to be running
|
|
10
|
+
during development — databases, docker compose services, workers, queues,
|
|
11
|
+
emulators — each with the command that starts it and its HTTP port when it
|
|
12
|
+
has one (else null).
|
|
12
13
|
|
|
13
14
|
Each service `name` is a unique machine identifier and must match
|
|
14
15
|
`^[A-Za-z0-9._-]+$`. Use `atlas-local`, not `mongodb (Atlas local)`. The
|
|
@@ -32,8 +33,8 @@ app:
|
|
|
32
33
|
- command: npm run dev
|
|
33
34
|
description: Vite dev server on http://localhost:5173
|
|
34
35
|
services:
|
|
35
|
-
- name:
|
|
36
|
-
command:
|
|
36
|
+
- name: worker
|
|
37
|
+
command: npm run worker
|
|
37
38
|
httpPort: null
|
|
38
39
|
```
|
|
39
40
|
|
|
@@ -10,6 +10,12 @@ Ground rules:
|
|
|
10
10
|
|
|
11
11
|
- Investigation is **read-only**. Do not write, create, modify, delete, or
|
|
12
12
|
move any project files while investigating.
|
|
13
|
+
- Run setup commands yourself, using your normal tool approvals. Leave to the
|
|
14
|
+
user only the steps that need them, such as signing in, connecting accounts,
|
|
15
|
+
adding a key to a Git host, setup choices, and launch approval. `dvb` stores
|
|
16
|
+
sign-in and setup state in the user's home folder and connects to
|
|
17
|
+
boxes.dev, so a sandboxed shell may block it. If a command is blocked,
|
|
18
|
+
explain what prevented it from running.
|
|
13
19
|
- Secret **values** never go in the manifest, in chat, or in any command
|
|
14
20
|
output. Reference files and variable names only.
|
|
15
21
|
- The user decides. Present findings, ask when evidence is ambiguous, and get
|
|
@@ -17,6 +23,11 @@ Ground rules:
|
|
|
17
23
|
- Keep discovery focused. Start with tracked manifests and project docs, prune
|
|
18
24
|
dependency/build/vendor/generated directories, and do not open minified or
|
|
19
25
|
unusually large assets just because a recursive search found them.
|
|
26
|
+
- Choose imports for their usefulness to this project and the user's
|
|
27
|
+
development workflow, considering their size. Explain large imports during
|
|
28
|
+
review. Reuse the user's answers and group routine choices
|
|
29
|
+
with your recommendations in one review instead of asking one question per
|
|
30
|
+
empty section.
|
|
20
31
|
- You never need to keep these guides in context: re-print any of them with
|
|
21
32
|
`dvb agent-init guide <topic>`, and re-orient anytime with
|
|
22
33
|
`dvb agent-init status` (it always names the exact next action).
|
|
@@ -98,11 +109,21 @@ repository, every repository and top-level file inside it starts selected;
|
|
|
98
109
|
keep only what belongs in the project in `project.repositories` and
|
|
99
110
|
`project.rootEntries`.
|
|
100
111
|
|
|
112
|
+
The manifest and its staging folder live outside the project, in boxes.dev's
|
|
113
|
+
folder in the user's home directory, so setup doesn't add files to their
|
|
114
|
+
repositories. Editing them is part of setup, not a change to project files.
|
|
115
|
+
Your harness may ask the user to approve each read or edit outside the
|
|
116
|
+
project. Group related changes into a few edits, and avoid redundant reads
|
|
117
|
+
while you have the current contents. Reread the manifest when the user or
|
|
118
|
+
another process may have changed it.
|
|
119
|
+
|
|
101
120
|
When the manifest uses managed GitHub access, `start` also checks whether
|
|
102
121
|
boxes.dev can already use the project's GitHub repositories. If it reports a
|
|
103
|
-
GitHub access problem,
|
|
104
|
-
|
|
105
|
-
access
|
|
122
|
+
GitHub access problem, follow its printed fix before you investigate, so the
|
|
123
|
+
user can finish on GitHub while you work. When the boxes.dev GitHub App can't
|
|
124
|
+
access a repository, ask the user to choose App access or SSH first (see
|
|
125
|
+
Phase 3), and run `dvb agent-init github connect` only if they choose App
|
|
126
|
+
access. `check` verifies access again before launch.
|
|
106
127
|
|
|
107
128
|
Read any worktree, project-overlap, or skipped-repository explanations printed by `start`.
|
|
108
129
|
Explain them to the user during review and confirm the intended project scope.
|
|
@@ -129,14 +150,21 @@ account, with high reasoning where supported.
|
|
|
129
150
|
|
|
130
151
|
For GitHub repos, the manifest defaults to `githubAccess: managed` and keeps
|
|
131
152
|
the seeded GitHub `gitSsh` rows in skip mode. If start or check says GitHub is
|
|
132
|
-
not connected,
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
153
|
+
not connected, run `dvb agent-init github connect`, have the user finish in the
|
|
154
|
+
browser, and then re-run check.
|
|
155
|
+
|
|
156
|
+
If the boxes.dev GitHub App can't access a repository, ask the user how the
|
|
157
|
+
project should pull and push. App access needs the App installed for the
|
|
158
|
+
repository's owner, and an organization owner may need to approve it. SSH uses
|
|
159
|
+
a key added to the user's own GitHub account. Either one covers pull and push;
|
|
160
|
+
automatic pull request updates and follow-ups need App access. With SSH, the
|
|
161
|
+
user can give the App access later for those features and keep SSH for pull
|
|
162
|
+
and push. For App access, run `dvb agent-init github connect`; it opens GitHub
|
|
163
|
+
and prints which account the user should choose. If an installation needs an
|
|
164
|
+
update, follow the exact action printed by check. Set `githubAccess: ssh` and
|
|
165
|
+
the GitHub `gitSsh` rows to setup only when the user chooses SSH, and keep the
|
|
166
|
+
user's choice when access changes later. GitLab and other origins continue to
|
|
167
|
+
use their seeded `gitSsh` entries.
|
|
140
168
|
|
|
141
169
|
Separately, `dvb agent-init github cli status` shows whether boxes.dev will
|
|
142
170
|
sign the `gh` command into the user's connected GitHub account on their boxes.
|
|
@@ -201,8 +229,31 @@ ask the user which one they want, record that key, and remove its marker. The
|
|
|
201
229
|
choice applies to the Template box and all of the project's devboxes and
|
|
202
230
|
cannot be changed after initialization.
|
|
203
231
|
|
|
232
|
+
Recommend the smallest available size that fits the actual workload. Normally
|
|
233
|
+
size for one coding agent and one running instance of the app, plus its
|
|
234
|
+
required services. Separate devboxes do not share one box's CPU or memory;
|
|
235
|
+
do not add their requirements together. The agent's model runs through its
|
|
236
|
+
connected account, so a larger model does not by itself require a larger box.
|
|
237
|
+
|
|
238
|
+
For a marketing site or a modest app, start the recommendation at 4 vCPU /
|
|
239
|
+
8 GB when available. Recommend more memory for evidence such as a required
|
|
240
|
+
local database, browser workload, or build that exceeds that capacity; choose
|
|
241
|
+
more CPUs for work that can use them. Use project docs, relevant local
|
|
242
|
+
measurements, or known service requirements. The user's laptop size, the
|
|
243
|
+
number of repositories, and vague future headroom are not reasons to recommend
|
|
244
|
+
the largest option. Explain uncertainty rather than treating it as a need for
|
|
245
|
+
maximum resources, and explain a team's larger default before recommending it.
|
|
246
|
+
|
|
247
|
+
Read `dvb agent-docs billing-and-limits` for the current box-hour multipliers.
|
|
248
|
+
Show the relative usage cost alongside the size options and explain the
|
|
249
|
+
recommendation in the same review. Larger sizes will consume included
|
|
250
|
+
box-hours and prepaid credits faster for every awake hour, even when the
|
|
251
|
+
extra resources are idle; the choice also applies to future devboxes. Do not
|
|
252
|
+
promise an in-place resize later.
|
|
253
|
+
|
|
204
254
|
If your harness supports parallel subagents, fan out one investigator per
|
|
205
|
-
section (each should read its section guide first
|
|
255
|
+
section (each should read its section guide first and report its findings for
|
|
256
|
+
you to record in the manifest). Otherwise investigate
|
|
206
257
|
serially — the order above works well.
|
|
207
258
|
|
|
208
259
|
Replace each `TODO(agent)` marker with real findings, or an explicit empty
|
|
@@ -217,6 +268,15 @@ databases will be dumped, how the app runs, what is excluded. Concise tables
|
|
|
217
268
|
work well. The user can reply in chat or edit the manifest file directly —
|
|
218
269
|
mention its path so they can open it.
|
|
219
270
|
|
|
271
|
+
Include the estimated upload size and the largest selected categories, noting
|
|
272
|
+
any sizes you have not measured. Follow `guide agent-config` to assess skills
|
|
273
|
+
and their linked contents for usefulness and size, then recommend a selection.
|
|
274
|
+
Explain large imports and confirm uncertain choices with the user. A multi-GB
|
|
275
|
+
upload for a small site deserves investigation before launch, even below the
|
|
276
|
+
bundle limit; useful workflow tools may still justify it. Keep local
|
|
277
|
+
configuration, assets, and unfinished work according to the user's choices;
|
|
278
|
+
do not delete local files to reduce the upload.
|
|
279
|
+
|
|
220
280
|
For a worktree, call out missing expected configuration and any files or symlink
|
|
221
281
|
targets outside it. If a needed file exists in the main checkout, offer to use
|
|
222
282
|
that file through an explicit `from:` entry, obtain the configuration another
|
|
@@ -18,8 +18,10 @@ gitSsh:
|
|
|
18
18
|
Managed access uses the user's existing boxes.dev GitHub connection for the
|
|
19
19
|
Template box and future devboxes. If needed, run `dvb agent-init github
|
|
20
20
|
connect`, let the user finish in the browser, and rerun `check`. When a repo
|
|
21
|
-
is not covered by the boxes.dev GitHub App, the
|
|
22
|
-
|
|
21
|
+
is not covered by the boxes.dev GitHub App, ask the user whether to give the
|
|
22
|
+
App access or use SSH. For App access, the same command opens the GitHub page
|
|
23
|
+
that grants access; an organization owner may need to approve it. Check
|
|
24
|
+
prints the exact GitHub action when a
|
|
23
25
|
repo is not writable or an installation needs updated access. Do not put any returned URL, connection
|
|
24
26
|
id, repository id, or token in the manifest. Managed access can push changes
|
|
25
27
|
under `.github/workflows` after every affected installation accepts the shown
|
|
@@ -53,8 +55,11 @@ projects. If Cargo's built-in Git client cannot use the configured authenticatio
|
|
|
53
55
|
set `CARGO_NET_GIT_FETCH_WITH_CLI=true` during remote setup to make Cargo use Git
|
|
54
56
|
for fetching. See [Cargo's Git authentication guide](https://doc.rust-lang.org/cargo/appendix/git-authentication.html).
|
|
55
57
|
|
|
56
|
-
Set `githubAccess: ssh` to use the key flow below for GitHub.
|
|
57
|
-
|
|
58
|
+
Set `githubAccess: ssh` to use the key flow below for GitHub. SSH pull and
|
|
59
|
+
push don't need the App, but automatic pull request updates and follow-ups do.
|
|
60
|
+
The user can give the App access later for those features without changing
|
|
61
|
+
Git transport.
|
|
62
|
+
Set `skip` to leave GitHub push/pull unconfigured. Use null only when the project has no
|
|
58
63
|
standard GitHub origin. GitLab and other hosts always use `gitSsh`.
|
|
59
64
|
|
|
60
65
|
`githubAccess` controls Git transport only. If `templateMaintenance.watches`
|
|
@@ -97,6 +97,12 @@ validate that key against the current server catalog. Once remote setup starts,
|
|
|
97
97
|
the project is pinned to it; changing the manifest cannot resize an in-progress
|
|
98
98
|
or initialized project.
|
|
99
99
|
|
|
100
|
+
Follow the workload and cost guidance in `guide flow` before recommending a
|
|
101
|
+
size. The seeded team default is a starting value, not evidence that this app
|
|
102
|
+
needs it. Explain the smallest suitable option, the reason for any larger
|
|
103
|
+
recommendation, and its box-hour multiplier from
|
|
104
|
+
`dvb agent-docs billing-and-limits` before recording the user's choice.
|
|
105
|
+
|
|
100
106
|
`githubAccess` is one project-level Git transport choice. Keep `managed` for the
|
|
101
107
|
recommended connected-GitHub HTTPS path, choose `ssh` for the existing key
|
|
102
108
|
flow, choose `skip` for intentionally absent GitHub push/pull, or use null only
|
|
@@ -33,6 +33,28 @@ completed — `destroy --yes` and re-run is the honest repair.
|
|
|
33
33
|
`dvb agent-init diagnostics` prints a redacted state dump (local + remote)
|
|
34
34
|
for debugging when something looks wrong.
|
|
35
35
|
|
|
36
|
+
## Restart with a smaller import or box size
|
|
37
|
+
|
|
38
|
+
Inspect `status --json` first. If setup is already complete, keep the project
|
|
39
|
+
and explain that changing its box size requires recreating the project;
|
|
40
|
+
do not apply the incomplete-setup reset to it.
|
|
41
|
+
|
|
42
|
+
For an incomplete setup, stop and await only its existing local
|
|
43
|
+
`dvb agent-init run` process before resetting, so it cannot keep driving the
|
|
44
|
+
same setup during the reset. Preserve the manifest and local project files. Explain
|
|
45
|
+
that `dvb agent-init destroy --yes` will remove the incomplete Template box and
|
|
46
|
+
setup progress, and use it only with the user's approval. An explicit request
|
|
47
|
+
to reset that incomplete setup supplies approval; do not ask again.
|
|
48
|
+
|
|
49
|
+
Reuse the saved manifest and earlier answers. Review global skills using
|
|
50
|
+
`guide agent-config`, retain the files needed to run the app and preserve
|
|
51
|
+
approved local work, and choose the smallest suitable box using `guide flow`.
|
|
52
|
+
Once an upload has started, a fresh `check` can be blocked by the frozen Git
|
|
53
|
+
access choice, even when only import selections changed. Use the supported
|
|
54
|
+
reset rather than deleting state files or editing them by hand. After reset,
|
|
55
|
+
edit the retained manifest, run `dvb agent-init check`, show the revised size
|
|
56
|
+
and cost summary, and obtain launch approval before `dvb agent-init run`.
|
|
57
|
+
|
|
36
58
|
## Reporting a boxes.dev bug
|
|
37
59
|
|
|
38
60
|
Report a bug with `dvb report-bug --stdin` when a `dvb agent-init` command
|
|
@@ -10,6 +10,15 @@ user-facing language — and records the manifest's content hash.
|
|
|
10
10
|
Errors are structured (`ERROR at <location>: <message> / Fix: ...`) —
|
|
11
11
|
address each and re-run. `--json` gives the machine form.
|
|
12
12
|
|
|
13
|
+
Alongside the launch summary, explain the recommended box size and its
|
|
14
|
+
box-hour multiplier, plus the estimated upload size and largest included
|
|
15
|
+
categories. Use measured sizes where available and label estimates; `check`
|
|
16
|
+
does not prepare the full bundle or establish its final compressed size.
|
|
17
|
+
Explain substantial size surprises and the useful contents behind them, then
|
|
18
|
+
review alternatives with the user. A large import can be reasonable when it
|
|
19
|
+
supports the app or the user's workflow; neither minimizing bytes nor staying
|
|
20
|
+
under the 15GB limit establishes that the selection is appropriate.
|
|
21
|
+
|
|
13
22
|
## User approval (required)
|
|
14
23
|
|
|
15
24
|
Relay the launch summary to the user verbatim or lightly formatted, and get
|
|
@@ -60,5 +69,8 @@ If the command is interrupted, nothing is lost: `dvb agent-init status`
|
|
|
60
69
|
shows where things stand and `dvb agent-init watch` re-attaches (see
|
|
61
70
|
`guide recovery`).
|
|
62
71
|
|
|
72
|
+
Use `run` to resume an unfinished upload; `watch` only follows remote setup
|
|
73
|
+
after the upload has committed and will not upload the missing data.
|
|
74
|
+
|
|
63
75
|
If `run` fails and `dvb agent-init retry` doesn't fix it, report the failure
|
|
64
76
|
with `dvb report-bug --stdin` (see `guide recovery`).
|
|
@@ -42,7 +42,8 @@ Named setup files keep their own selections. Two modes:
|
|
|
42
42
|
|
|
43
43
|
- `mode: defaults` (recommended): include untracked files, minus
|
|
44
44
|
well-known dependency/cache/build folders (node_modules, venvs, build
|
|
45
|
-
output, caches). This matches what
|
|
45
|
+
output, caches) and Git worktrees inside the repository. This matches what
|
|
46
|
+
most users want. A worktree's branch still uploads with the Git history.
|
|
46
47
|
- `mode: custom`: add include/exclude patterns. Use `base: defaults` to keep
|
|
47
48
|
the normal exclusions, or `base: all` to start from all eligible files.
|
|
48
49
|
Omitting `base` retains the older custom behavior: all eligible files.
|