@tangle-network/create-agent-app 0.50.29 → 0.50.31

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/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Scaffold a Tangle agent product on
4
4
  [`@tangle-network/agent-app`](https://github.com/tangle-network/agent-app).
5
5
  Use **`--chat` for the browser sign-in and chat walkthrough below**. Without it,
6
- the CLI generates the tool-loop skeleton, not the assembled chat variant.
6
+ the CLI generates the unchanged tool-loop skeleton, not the assembled chat variant.
7
7
 
8
8
  ## Choose a published version
9
9
 
@@ -19,29 +19,36 @@ npm create "@tangle-network/agent-app@$CREATE_VERSION" my-agent -- --chat
19
19
 
20
20
  Do not continue after a failed registry lookup. The CLI defaults the generated
21
21
  `agent-app` dependency to `<scaffolder-version>`; the generated `package.json`
22
- records the requested dependencies and `packageManager`.
23
- Use that pnpm version.
24
- The generated engine pins match the cohort maintained in Agent App's package manifest.
25
- Upgrade this cohort deliberately and run the product's real flow before deployment.
26
- Do not force a version override or ignore peer failures to conceal an incomplete
27
- release.
22
+ records the requested dependencies and `packageManager`. Use that pnpm version.
23
+ The engine and UI pins match the maintained Agent App cohort. Upgrade this
24
+ cohort deliberately and run the product's real flow before deployment. Do not
25
+ force an override or ignore peer failures to conceal an incomplete release.
28
26
 
29
- An npm dist-tag is not `main`. This walkthrough describes the maintained chat
30
- template; compare it with the files in your generated project. A feature found
31
- only in this repository is not evidence that your selected npm package ships it.
27
+ An npm dist-tag is not `main`. This walkthrough describes the maintained source
28
+ template; compare it with the files in your generated project. In particular,
29
+ check for `web/` and the Vite build configuration. A source-only React template
30
+ change does not prove that the selected registry package already ships it.
32
31
 
33
32
  ## What is generated
34
33
 
35
- The chat variant supplies a Cloudflare Worker, D1 migrations, session-authenticated
36
- chat routes, sandbox-backed turns, and `public/index.html`: a small **development
37
- chat page** with email/password sign-in, a thread list, a composer, and uploads.
38
- It does not generate the React workspace shown in
39
- [`examples/default-workspace.md`](../examples/default-workspace.md).
40
- That example is a product-UI integration guide, not a screenshot of the scaffold.
34
+ The chat variant supplies a standalone React workspace, a Cloudflare Worker,
35
+ D1 migrations, session-authenticated routes, and sandbox-backed turns.
36
+ `web/App.tsx` composes the existing `AgentWorkspaceLayout`, real email/password
37
+ session auth, New thread navigation, and the shared full History panel.
38
+ `web/Conversation.tsx` composes the shared composer, messages, and interaction
39
+ cards with the existing chat, upload, and replay routes. There is no second
40
+ primitive family or product-local sidebar.
41
+
42
+ Vite builds browser JS and standalone CSS into `dist/client`. The CSS imports
43
+ public Agent App and sandbox-ui styles and the public Tailwind preset, scanning
44
+ installed package distributions. Wrangler's custom build serves the same
45
+ compiled assets in development and deployment. Worker and browser typechecking
46
+ use separate configurations; no server config is bundled into the browser.
41
47
 
42
48
  The generated `README.md`, `AGENTS.md`, and `CUSTOMIZE.md` remain the customization
43
- trail. Installing dependencies or passing the template's injected-producer tests
44
- is not proof of a real login, model turn, or durable file.
49
+ trail. A build or an injected-producer test does not prove a hosted login, a live
50
+ model turn, or durable artifact bytes. The source-level default workspace guide
51
+ is at [`examples/default-workspace.md`](../examples/default-workspace.md).
45
52
 
46
53
  ## Configure and start the chat variant
47
54
 
@@ -52,78 +59,84 @@ cp .dev.vars.example .dev.vars
52
59
  ```
53
60
 
54
61
  Keep `.dev.vars` out of version control. Replace its auth-secret placeholder with
55
- a fresh secret (for example, generate one with `openssl rand -base64 32`), and fill
56
- `TANGLE_API_KEY`, `SANDBOX_API_KEY`, and `SANDBOX_GATEWAY_URL` with development
57
- credentials. These are server-side Router and Sandbox credentials, not the
58
- password you will use to sign in to the generated app. Missing sandbox
59
- credentials do not select a demo agent: real turns fail.
62
+ a fresh secret (for example, `openssl rand -base64 32`) and fill the development
63
+ `TANGLE_API_KEY`, `SANDBOX_API_KEY`, and `SANDBOX_GATEWAY_URL` credentials.
64
+ These are server-side Router and Sandbox credentials, not your app password.
65
+ Missing sandbox credentials do not select a demo agent: real turns fail.
60
66
 
61
- In `agent.config.ts`, replace `model.default: 'REPLACE_WITH_MODEL'` with a model
62
- your Router key can use, compatible with the selected harness (`opencode` is the
63
- template default). Review `model.fallbacks` as well; `MODEL_NAME` in `.dev.vars`
64
- can override the default. Customize the persona in `prompts/system.md`.
67
+ Replace `model.default: 'REPLACE_WITH_MODEL'` in `agent.config.ts` with a model
68
+ your Router key can use, compatible with the selected harness (`opencode` by
69
+ default). Review fallbacks and the optional `MODEL_NAME` environment override.
70
+ Customize `prompts/system.md` and the product title in `web/index.html`.
65
71
 
66
72
  Set the `DB` binding's `database_id` in `wrangler.toml` to a **development** D1
67
- database ID; `CUSTOMIZE.md` contains the database-creation instructions. Keep its
68
- `database_name` consistent with the generated migration scripts. Keep
69
- `BETTER_AUTH_URL` at `http://localhost:8787` when using that local origin; change
70
- both together when using another origin. R2 is not required for the chat turn,
71
- and uncommenting its binding alone does not add artifact storage or downloads.
73
+ ID. Keep `database_name` consistent with the migration scripts. Keep
74
+ `BETTER_AUTH_URL` equal to the actual Worker origin, normally
75
+ `http://localhost:8787`. Do not introduce a second Vite origin for cookie auth.
76
+ R2 is not required for a chat turn and does not itself provide downloads.
72
77
 
73
78
  ```bash
74
79
  pnpm db:migrate:local
75
- pnpm typecheck
80
+ pnpm build
81
+ pnpm test
76
82
  pnpm dev
77
83
  ```
78
84
 
79
- The migration command above is local. Neither `pnpm deploy` nor the remote
80
- `pnpm db:migrate` command is part of this local walkthrough. The chat template
81
- uses `wrangler dev`; it does not define a separate `build` script.
85
+ Wrangler compiles the frontend before starting and rebuilds it when the browser
86
+ sources change; refresh after a rebuild. `pnpm build` checks both type boundaries
87
+ and builds browser assets. `pnpm exec wrangler deploy --dry-run` checks the Worker
88
+ bundle without deployment. Neither `pnpm deploy` nor remote `pnpm db:migrate` is
89
+ part of this local walkthrough. APIs retain their JSON responses and are not
90
+ covered by an HTML fallback.
82
91
 
83
92
  ## Sign in and run a normal turn
84
93
 
85
- Open `http://localhost:8787`. In the sign-in dialog, choose **No account? Sign up**
86
- and create a development account with an email and a password of at least eight
87
- characters. Use **Sign in** for an account already in this app's D1 database;
88
- this is not a Tangle CLI login or a provider OAuth flow.
89
-
90
- Choose **New thread** and send a normal message such as “What can you help me
91
- with?” This invokes the real Sandbox and model and can incur usage charges.
92
- Wait for completion, check for an error, and reload the same thread. Look for the
93
- persisted assistant text and model/token metadata, not just a successful HTTP
94
- connection or a locally rendered user message. A second message in that thread
95
- uses the thread ID as the agent session ID.
96
-
97
- Save the resulting URL containing `?threadId=...`. The dev page can reload the
98
- completed transcript; it is not the shared React reconnect/replay client. Do not
99
- use closing the tab mid-turn as a substitute for this completed-turn check.
94
+ Open the Worker origin. Choose **No account? Sign up**, then create a development
95
+ account with an email and a password of at least eight characters. An existing
96
+ account signs in against the same D1 database. This is not a Tangle CLI login or
97
+ provider OAuth flow.
98
+
99
+ Choose **New thread** and send a normal message. This invokes the real Sandbox
100
+ and model and can incur usage charges. Wait for completion, check for errors,
101
+ and reload the saved `?threadId=...` URL. Inspect persisted assistant text and
102
+ model/token metadata, not only a successful HTTP connection or optimistic user
103
+ message. A second message uses the same thread ID as the agent session ID.
104
+
105
+ History is `/?view=history`; its search and sorting cover the existing API's
106
+ pages, not only the capped rail. Native links retain normal browser navigation.
107
+ The shared stream client resumes a dropped stream; reopening a running thread
108
+ uses existing replay handles and durable rows without appending the same text
109
+ twice. Verify that live behavior separately on the target environment.
110
+
111
+ The existing upload endpoint returns inline or sandbox `parts`. The template
112
+ uses `ChatComposer.onSendParts` rather than pretending those responses are the
113
+ store-backed attachments expected by `EntryComposer.uploadUrl`. Model, effort,
114
+ profile, plan-mode, and unsupported thread-action controls stay hidden until
115
+ real catalogs and handlers exist.
100
116
 
101
117
  ## Restart and artifact limits
102
118
 
103
- For a file-producing turn, ask the agent to save a small text file at
104
- `/home/agent/artifacts/quickstart.txt` with a distinctive value you can compare
105
- later. A claim in the assistant's answer is not proof that the file exists.
106
- In the maintained chat template, opening `/api/files` in the same signed-in
107
- browser lists metadata under `/home/agent/artifacts`. Check that your generated
108
- `src/worker.ts` actually mounts this route before relying on it.
109
-
110
- After the turn completes, stop **only the local `pnpm dev` process**, then run
111
- `pnpm dev` again from the same project directory. Preserve the local Wrangler
112
- state (`.wrangler/state`), database configuration, auth secret, and app identity.
113
- Reopen the saved thread URL and sign in to the same app account if needed. Check
114
- the transcript and artifact index again. This exercises a local Worker restart,
115
- not sandbox suspension, deletion, or host-loss recovery.
116
-
117
- **The stock dev page does not reopen artifact contents.** Its file/image parts
118
- are labels, not download links. `/api/files` is a metadata index, not a file-read
119
- endpoint; it returns `warming` when no ready sandbox exists and does not provision
120
- or resume one. Uploading a file and replaying a transcript are also not proof of
121
- saved artifact bytes. Completing a saved-artifact-reopened check requires a
122
- product-owned, authorized file reader/storage integration and a comparison of
123
- the actual contents before and after restart. Do not describe that check as
124
- passed from this scaffold alone.
125
-
126
- For product assembly after this local walkthrough, see
127
- [`examples/chat-app.md`](../examples/chat-app.md) and the shared workspace example
128
- above. The product supplies its UI and artifact access; those examples do not
129
- turn source-only behavior into a published scaffold feature.
119
+ After a completed turn, stop only local `pnpm dev`, then restart it from the same
120
+ project. Preserve `.wrangler/state`, the D1 configuration, auth secret, and app
121
+ identity. Reopen the saved URL and sign in if needed. This checks a local Worker
122
+ restart, not sandbox suspension, deletion, or host-loss recovery.
123
+
124
+ For an artifact-producing turn, ask for a distinctive small file under
125
+ `/home/agent/artifacts`. Check `/api/files` in the signed-in browser; an assistant
126
+ claim alone is not proof. The index returns metadata or `warming`, and does not
127
+ provision, resume, or read files. **Attachment labels are not downloads.** An
128
+ authorized product file reader must compare actual contents before and after
129
+ restart to prove saved bytes reopened. Do not claim that proof from this scaffold.
130
+
131
+ ## Fresh packed consumer proof
132
+
133
+ From a candidate Agent App checkout, run its maintained `pnpm test:generated`
134
+ gate. It installs the packed generator, generates fresh headless and chat apps,
135
+ installs the candidate Agent App tarball, runs typechecks/tests, and builds the
136
+ frontend and Worker. Its Chromium/Worker/D1 lane checks real signup, History,
137
+ thread navigation/reload, sign-out, and the same thread after a fresh process
138
+ and login, with zero model turns. See [proof instructions](./proof/README.md).
139
+
140
+ The existing generated server suite covers message/part persistence and replay
141
+ with an explicitly fake producer. Hosted deployment, live model execution,
142
+ live mid-turn reconnect, and saved artifact bytes remain separate proofs.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tangle-network/create-agent-app",
3
- "version": "0.50.29",
3
+ "version": "0.50.31",
4
4
  "description": "Create a tested Tangle agent application with either a tool loop or a complete chat interface.",
5
5
  "keywords": [
6
6
  "tangle",
@@ -12,6 +12,7 @@ Read [CUSTOMIZE.md](CUSTOMIZE.md) for required configuration and deployment setu
12
12
  - `src/sandbox.ts` resolves sandbox access and profiles; domain reasoning belongs in the agent.
13
13
  - `src/worker.ts` routes requests to those handlers.
14
14
  - `migrations/` must match the persisted schema; the generated application's tests execute the real migration.
15
+ - `web/` composes the maintained React workspace from public package paths, with real auth, navigation, History, and chat callbacks.
15
16
 
16
17
  Extend supported configuration and callbacks before duplicating a shell mechanism or forking the package.
17
18
 
@@ -24,9 +25,21 @@ Agents own reasoning and tools; the application owns durable records, billing, a
24
25
  Agent writes use schema-validated tools rather than records parsed from prose.
25
26
  Preserve the persona's fabrication rule: a real record or an explicit "NOT ON FILE" outcome.
26
27
 
28
+ Keep the maintained `AgentWorkspaceLayout`, session rail, History, composer, and message surfaces.
29
+ Do not add a parallel primitive library, token palette, sidebar, or picker.
30
+ Use only public package imports in `web/`; never import the server config or a repository source alias.
31
+ Keep `/?threadId=...` links and `/api/*` and `/v1/*` routes stable.
32
+ Do not add a transcript title row or a fabricated connection indicator.
33
+ Omit controls without real product data and callbacks.
34
+ The upload adapter preserves inline/sandbox `parts`; it is not the store-backed attachment contract.
35
+ Keep browser DOM types separate from Worker types and scan installed UI package classes in the CSS build.
36
+
27
37
  ## Verification
28
38
 
29
- Run the package's typecheck and test scripts.
39
+ Run `pnpm build` and `pnpm test`.
30
40
  The turn test uses real migrations and shell factories with a fake sandbox event feed; it does not prove live sandbox access.
41
+ The parent repository's fresh packed-generation gate also runs a local Worker/D1 browser proof.
42
+ That proof checks real auth and thread persistence across a Worker restart, but makes no model request.
31
43
  For deployment, complete environment configuration, apply the required database migrations, and exercise the actual page and turn flow.
44
+ Record hosted/model/disconnect proofs separately; do not claim them from compilation or an injected producer.
32
45
  Fix failures without weakening the protected behavior.
@@ -1,118 +1,99 @@
1
1
  # CUSTOMIZE.md — fill this project, in order
2
2
 
3
- This is the trail. Walk it top to bottom. Each step is a checklist item paired
4
- with the DISCOVERY QUESTION it answers — answer the question, then make the
5
- edit. The whole job is filling `agent.config.ts` + `prompts/system.md` (DATA)
6
- and wiring credentials; the chat vertical itself is already assembled and
7
- proven by the e2e test.
8
-
9
- When every box is checked and `pnpm typecheck && pnpm test` are green and a
10
- message round-trips on `pnpm dev`, the app is customized.
11
-
12
- ---
3
+ Customize the agent's data and credentials, then use the generated React
4
+ workspace. The server vertical and frontend assembly already exist. Local
5
+ injected-producer tests are not a substitute for a live model turn.
13
6
 
14
7
  ## ① Identity — `agent.config.ts` + `prompts/system.md`
15
8
 
16
9
  Discovery: **Whose job does this agent do, in whose voice, under what hard rules?**
17
10
 
18
- - [ ] Set `name` in `agent.config.ts` to the product/agent name.
19
- - [ ] Rewrite `prompts/system.md` as the real persona: role + voice + remit +
20
- hard rules. State intents, never implementations (no commands, no tool
21
- scripts — the sandboxed agent picks its own tools).
22
- - [ ] Keep the grounding rule (never fabricate; cite a record or NOT ON FILE).
11
+ - [ ] Set `name` in `agent.config.ts` and the browser title in `web/index.html`.
12
+ - [ ] Rewrite `prompts/system.md` as the real persona: role, voice, remit, and hard rules. State intents, not tool or installation scripts.
13
+ - [ ] Keep the grounding rule: never fabricate; cite a record or NOT ON FILE.
23
14
 
24
- ## ② Model + harness — `agent.config.ts` → `model`, `harness`
15
+ ## ② Model + harness — `agent.config.ts`
25
16
 
26
- Discovery: **Which model answers by default, at what effort, on which harness?**
17
+ Discovery: **Which real model answers, on which harness?**
27
18
 
28
19
  - [ ] Set `model.default` to a model your Tangle Router key can reach.
29
- - [ ] Set `gateway.maxProviderInputTokens` to that model's full input limit.
30
- This covers retained tool and sidecar history that the transcript omits.
31
- - [ ] Pick `harness` (`opencode` default; vendor-locked harnesses like
32
- `claude-code` must pair with their own provider's models).
33
- - [ ] Define the selectable profile catalog for the UI and map each selected
34
- profile id to the real runtime `AgentProfile` before session creation.
35
- Keep that browser catalog to stable display metadata and capability labels;
36
- resolve prompts, tools, permissions, connections, resources, and backend
37
- policy server-side. Put profile authoring in settings, not the composer.
38
- - [ ] Leave per-turn overrides alone — the client can send `model`/`effort`
39
- per request and `MODEL_NAME` overrides without a redeploy.
20
+ - [ ] Set `gateway.maxProviderInputTokens` to its full input limit, including retained tool and sidecar history.
21
+ - [ ] Choose a compatible harness. Vendor-locked harnesses must use their provider's models.
22
+ - [ ] Review fallbacks and the optional `MODEL_NAME` environment override.
23
+ - [ ] Keep unavailable model, effort, profile, and plan-mode controls hidden. Add a display catalog and real callbacks only when your server can honor them. Resolve prompts, tools, permissions, connections, resources, and backend policy server-side. Profile authoring belongs in settings, not a new composer picker.
24
+
25
+ The existing per-turn model/effort wire remains available. The template does
26
+ not manufacture a browser catalog or silently add a model-selection endpoint.
40
27
 
41
28
  ## ③ Infrastructure — `wrangler.toml` + `.dev.vars` + `migrations/`
42
29
 
43
30
  Discovery: **Where does this app live and what may it spend?**
44
31
 
45
- - [ ] `wrangler d1 create <name>` → paste `database_id` into `wrangler.toml`.
46
- - [ ] Copy `.dev.vars.example` → `.dev.vars`; fill `BETTER_AUTH_SECRET`,
47
- `TANGLE_API_KEY`, `SANDBOX_API_KEY`, `SANDBOX_GATEWAY_URL`.
48
- - [ ] `pnpm db:migrate:local` — applies migrations for auth, chat, turn
49
- buffer, API keys, usage, request limits, and spending reservations.
50
- The e2e test executes these same files, so they cannot drift from the schema.
51
- - [ ] Existing generated app: copy and apply `0002_agent_gateway.sql`.
52
- Never edit its already-applied `0001_init.sql`.
53
- - [ ] Apply `0003_gateway_reservations.sql` when adopting the gateway reservation lifecycle.
54
- - [ ] Existing app only: add `sandbox_prewarm_claims` in a new migration.
55
- Do not edit an applied `0001_init.sql`; Wrangler will not run it again.
56
- - [ ] R2 stays commented out unless the product stores artifacts.
57
-
58
- ## ④ Prove the loop — `pnpm dev`
59
-
60
- Discovery: **Does a real message round-trip through a real box?**
61
-
62
- - [ ] `pnpm dev`, open http://localhost:8787, sign up, send a message.
63
- - [ ] Confirm: streamed text renders live, the transcript reloads with parts
64
- and a usage receipt, and a second turn continues the same agent session.
65
- - [ ] Kill the tab mid-turn, reopen the thread — the persisted row is intact
66
- (the turn keeps running server-side and buffers for replay).
67
- - [ ] Create a key through the signed-in `/api/keys` route.
68
- Finite-cap keys require backend enforcement of per-turn spending limits.
69
- The current remote chat adapter rejects capped execution before compute.
70
- Explicitly uncapped keys use the existing chat path.
71
- - [ ] Call `/v1/agents/<slug>/chat/completions` with that key.
72
- Open the returned `X-Tangle-Thread-Url` and confirm it shows the same durable conversation.
73
-
74
- ## ⑤ The product UI — replace the dev page
75
-
76
- Discovery: **What does the real surface look like?**
77
-
78
- - [ ] `public/index.html` is the dev harness, not the product. Build the real
79
- surface in React on `@tangle-network/agent-app/web-react`:
80
- `ChatComposer` (`onSendParts` + `onAttach`), `ChatMessages`,
81
- `streamChatTurn` (start + resume against `/api/chat/replay/:turnId`),
82
- `useChatInteractions` + `InteractionQuestionCard`/`InteractionPlanCard`
83
- for the ask channel this server already exposes.
84
- - [ ] For a chat-first product, use `AgentWorkspaceLayout` from
85
- `@tangle-network/agent-app/workspace-react` for the outer layout and
86
- session rail, `EntryComposer` from
87
- `@tangle-network/agent-app/web-react` for the new-session route, and
88
- `SessionHistoryPanel` from `@tangle-network/agent-app/web-react` for the
89
- full history route.
90
- Pass `agent.profile`, `agent.harness`, `agent.model`, and `agent.effort`
91
- from real product state so the shared control row does not disappear.
92
- Pass `planMode`, `uploadUrl`, and `mentions` only when the corresponding
93
- backend behavior, upload route, and file index are real.
94
- Keep navigation taxonomy, session URLs, domain context, and transcript
95
- cards in the product.
96
- - [ ] Keep the wire contract: `chatTurnRequestInit` from web-react serializes
97
- exactly what `createChatTurnRoutes` parses.
98
-
99
- ## ⑥ Extend, don't fork
100
-
101
- Discovery: **What does this product add beyond the vertical?**
102
-
103
- - [ ] Billing/audit/titles → `onTurnComplete` seam in `src/chat.ts`.
104
- - [ ] PII scrubbing before persistence → `transformFinalText` +
105
- `@tangle-network/agent-app/redact`.
106
- - [ ] Structured agent writes (proposals, records) → the shell's `/tools`
107
- side channel, never prose parsing.
108
- - [ ] Multi-user teams → `@tangle-network/agent-app/teams` and pass your
109
- workspace table to `createChatTables({ workspaceTable })` (new migration).
110
-
111
- ## ⑦ Verify
112
-
113
- Discovery: **Does the customized app hold its contract?**
114
-
115
- - [ ] `pnpm typecheck` — clean.
116
- - [ ] `pnpm test` — green (the e2e turn gate + fail-closed auth).
117
- - [ ] `pnpm dev` — a real turn round-trips end to end.
118
- - [ ] `pnpm deploy` + `pnpm db:migrate` when it's real.
32
+ - [ ] `wrangler d1 create <name>` and set `database_id` in `wrangler.toml`.
33
+ - [ ] Copy `.dev.vars.example` to `.dev.vars`. Set a fresh `BETTER_AUTH_SECRET`, `TANGLE_API_KEY`, `SANDBOX_API_KEY`, and `SANDBOX_GATEWAY_URL`. Never commit credentials.
34
+ - [ ] Keep `BETTER_AUTH_URL` equal to the Worker origin. The frontend and API use the same origin and cookies.
35
+ - [ ] Run `pnpm db:migrate:local` for auth, chat, turn buffer, API keys, usage, claims, and spending reservations.
36
+ - [ ] Upgrading an existing app: apply `0002_agent_gateway.sql` and `0003_gateway_reservations.sql` as needed. Add `sandbox_prewarm_claims` in a new migration. Never edit an already-applied `0001_init.sql`.
37
+ - [ ] Keep R2 disabled unless the product needs object storage.
38
+
39
+ ## ④ Build and use the workspace
40
+
41
+ Discovery: **Does the public-package frontend work on the real Worker origin?**
42
+
43
+ - [ ] Run `pnpm build`. Worker and DOM typechecks are separate; Vite emits `dist/client`.
44
+ - [ ] Run `pnpm exec wrangler deploy --dry-run` to check the Worker bundle without deploying.
45
+ - [ ] Run `pnpm dev`, open the Worker origin, sign up, open History, create a conversation, and retain its `?threadId=...` URL.
46
+ - [ ] Confirm desktop and mobile navigation, sign-out, fresh login, and reopening a saved thread after a local Worker restart.
47
+
48
+ Wrangler's custom build runs the same frontend compiler for development and
49
+ deployment. Refresh the browser after a rebuild. Do not point assets at source
50
+ TSX, add a second auth origin, or introduce an HTML fallback over `/api/*` or
51
+ `/v1/*`. `web/styles.css` imports both maintained public stylesheets and scans
52
+ the installed Agent App, sandbox-ui, and ui distributions. Keep that standalone
53
+ setup; a repository-local Tailwind alias is not a consumer proof.
54
+
55
+ ## ⑤ Extend the product UI, not the primitive family
56
+
57
+ Discovery: **What product behavior belongs beside the maintained workspace?**
58
+
59
+ - [ ] Keep `AgentWorkspaceLayout` and the existing full `SessionHistoryPanel`. Do not add a second History surface or a local sidebar.
60
+ - [ ] Keep native thread links and real session/auth callbacks in `web/App.tsx`. The server remains authoritative after a reload.
61
+ - [ ] Keep the transcript full-space, with no repeated title row.
62
+ Titles belong in History and the document title.
63
+ The shared shell owns the mobile header, navigation drawer, and account menu.
64
+ Do not add a second mobile bar or header inset.
65
+ - [ ] Keep `settingsHref={null}` until the product provides Settings.
66
+ Then pass its real route or `onSettingsClick` callback.
67
+ - [ ] Keep `ChatComposer`, `ChatMessages`, `streamChatTurn`, and the shared interaction cards. Their current callbacks target the existing routes.
68
+ - [ ] Keep the inline/sandbox upload adapter in `web/uploads.ts`. `ChatComposer.onSendParts` matches `/api/chat/upload`; `EntryComposer.uploadUrl` and `useComposerAttachments` expect stored attachment descriptors instead. Do not silently reinterpret those responses or change storage behavior to make a different UI fit.
69
+ - [ ] Add uploads, mentions, integrations, profiles, thread mutations, or plan controls only through real supported product contracts. No empty catalogs, placeholder URLs, or no-op callbacks.
70
+
71
+ For an integration settings surface, reuse `IntegrationsPanel`, `useIntegrations`,
72
+ and `ProviderIcon` from sandbox-ui with authorized data and real callbacks.
73
+ For a new document or workbench surface, follow the maintained default-workspace
74
+ guidance and its page/pane headers rather than creating another layout family.
75
+
76
+ ## ⑥ Prove the real loop and extend through seams
77
+
78
+ Discovery: **Does a real message round-trip through a real sandbox and survive reload?**
79
+
80
+ - [ ] Complete a real model turn, inspect streamed text and tools, then reload the persisted transcript, typed parts, and usage. A second turn must continue the same session.
81
+ - [ ] Close the tab mid-turn and reopen the thread. Verify actual buffered replay and persisted results on the target deployment. Do not infer this from an empty-thread browser proof.
82
+ - [ ] Create a key through `/api/keys`, call `/v1/agents/<slug>/chat/completions`, and open the returned `X-Tangle-Thread-Url`. Finite-cap keys still require backend spending enforcement; the existing remote adapter rejects capped execution before compute.
83
+ - [ ] For saved artifacts, verify actual bytes through an authorized product reader. `/api/files` is metadata only, not a download route.
84
+
85
+ Use `onTurnComplete` in `src/chat.ts` for billing/audit/title extensions and
86
+ `transformFinalText` with `/redact` for persistence scrubbing. Structured writes
87
+ use schema-validated tools, not prose parsing. Team support uses `/teams` and
88
+ `createChatTables({ workspaceTable })` with a new migration.
89
+
90
+ ## ⑦ Record verification honestly
91
+
92
+ Run `pnpm build` and `pnpm test`. The generated test suite uses real migrations,
93
+ auth, routes, persistence, and replay with one fake sandbox producer. The parent
94
+ repository's packed gate additionally exercises real local Worker/D1 auth and
95
+ thread persistence in Chromium, including a process restart, without model calls.
96
+
97
+ Record local build, injected-producer, browser/D1, hosted, live-model, and live
98
+ reconnect results separately. An unrun hosted/model proof stays unrun. Deploy
99
+ and apply remote migrations only after the product is configured and verified.