@tangle-network/create-agent-app 0.49.33 → 0.49.35
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 +118 -5
- package/package.json +1 -1
- package/template/_package.json +5 -5
- package/template-chat/_package.json +4 -4
package/README.md
CHANGED
|
@@ -1,13 +1,126 @@
|
|
|
1
1
|
# @tangle-network/create-agent-app
|
|
2
2
|
|
|
3
|
-
Scaffold a
|
|
3
|
+
Scaffold a Tangle agent product on
|
|
4
|
+
[`@tangle-network/agent-app`](https://github.com/tangle-network/agent-app).
|
|
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.
|
|
7
|
+
|
|
8
|
+
## Choose a published version
|
|
9
|
+
|
|
10
|
+
The maintained scaffolder requires Node.js 22.13 or newer. Check the published
|
|
11
|
+
package's engine requirement and record the version you will run:
|
|
4
12
|
|
|
5
13
|
```bash
|
|
6
|
-
npm
|
|
14
|
+
CREATE_VERSION=$(npm view @tangle-network/create-agent-app@latest version) &&
|
|
15
|
+
npm view "@tangle-network/create-agent-app@$CREATE_VERSION" engines --json &&
|
|
16
|
+
npm view "@tangle-network/agent-app@^$CREATE_VERSION" version peerDependencies --json &&
|
|
17
|
+
npm create "@tangle-network/agent-app@$CREATE_VERSION" my-agent -- --chat
|
|
7
18
|
```
|
|
8
19
|
|
|
9
|
-
|
|
20
|
+
Do not continue after a failed registry lookup. The CLI defaults the generated
|
|
21
|
+
`agent-app` dependency to `^<scaffolder-version>`; the generated `package.json`
|
|
22
|
+
records the requested dependencies and `packageManager`. Use that pnpm version.
|
|
23
|
+
Do not force a version override or ignore peer failures to conceal an incomplete
|
|
24
|
+
release.
|
|
25
|
+
|
|
26
|
+
An npm dist-tag is not `main`. This walkthrough describes the maintained chat
|
|
27
|
+
template; compare it with the files in your generated project. A feature found
|
|
28
|
+
only in this repository is not evidence that your selected npm package ships it.
|
|
29
|
+
|
|
30
|
+
## What is generated
|
|
10
31
|
|
|
11
|
-
|
|
12
|
-
|
|
32
|
+
The chat variant supplies a Cloudflare Worker, D1 migrations, session-authenticated
|
|
33
|
+
chat routes, sandbox-backed turns, and `public/index.html`: a small **development
|
|
34
|
+
chat page** with email/password sign-in, a thread list, a composer, and uploads.
|
|
35
|
+
It does not generate the React workspace shown in
|
|
13
36
|
[`examples/default-workspace.md`](../examples/default-workspace.md).
|
|
37
|
+
That example is a product-UI integration guide, not a screenshot of the scaffold.
|
|
38
|
+
|
|
39
|
+
The generated `README.md`, `AGENTS.md`, and `CUSTOMIZE.md` remain the customization
|
|
40
|
+
trail. Installing dependencies or passing the template's injected-producer tests
|
|
41
|
+
is not proof of a real login, model turn, or durable file.
|
|
42
|
+
|
|
43
|
+
## Configure and start the chat variant
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
cd my-agent
|
|
47
|
+
pnpm install
|
|
48
|
+
cp .dev.vars.example .dev.vars
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Keep `.dev.vars` out of version control. Replace its auth-secret placeholder with
|
|
52
|
+
a fresh secret (for example, generate one with `openssl rand -base64 32`), and fill
|
|
53
|
+
`TANGLE_API_KEY`, `SANDBOX_API_KEY`, and `SANDBOX_GATEWAY_URL` with development
|
|
54
|
+
credentials. These are server-side Router and Sandbox credentials, not the
|
|
55
|
+
password you will use to sign in to the generated app. Missing sandbox
|
|
56
|
+
credentials do not select a demo agent: real turns fail.
|
|
57
|
+
|
|
58
|
+
In `agent.config.ts`, replace `model.default: 'REPLACE_WITH_MODEL'` with a model
|
|
59
|
+
your Router key can use, compatible with the selected harness (`opencode` is the
|
|
60
|
+
template default). Review `model.fallbacks` as well; `MODEL_NAME` in `.dev.vars`
|
|
61
|
+
can override the default. Customize the persona in `prompts/system.md`.
|
|
62
|
+
|
|
63
|
+
Set the `DB` binding's `database_id` in `wrangler.toml` to a **development** D1
|
|
64
|
+
database ID; `CUSTOMIZE.md` contains the database-creation instructions. Keep its
|
|
65
|
+
`database_name` consistent with the generated migration scripts. Keep
|
|
66
|
+
`BETTER_AUTH_URL` at `http://localhost:8787` when using that local origin; change
|
|
67
|
+
both together when using another origin. R2 is not required for the chat turn,
|
|
68
|
+
and uncommenting its binding alone does not add artifact storage or downloads.
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
pnpm db:migrate:local
|
|
72
|
+
pnpm typecheck
|
|
73
|
+
pnpm dev
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The migration command above is local. Neither `pnpm deploy` nor the remote
|
|
77
|
+
`pnpm db:migrate` command is part of this local walkthrough. The chat template
|
|
78
|
+
uses `wrangler dev`; it does not define a separate `build` script.
|
|
79
|
+
|
|
80
|
+
## Sign in and run a normal turn
|
|
81
|
+
|
|
82
|
+
Open `http://localhost:8787`. In the sign-in dialog, choose **No account? Sign up**
|
|
83
|
+
and create a development account with an email and a password of at least eight
|
|
84
|
+
characters. Use **Sign in** for an account already in this app's D1 database;
|
|
85
|
+
this is not a Tangle CLI login or a provider OAuth flow.
|
|
86
|
+
|
|
87
|
+
Choose **New thread** and send a normal message such as “What can you help me
|
|
88
|
+
with?” This invokes the real Sandbox and model and can incur usage charges.
|
|
89
|
+
Wait for completion, check for an error, and reload the same thread. Look for the
|
|
90
|
+
persisted assistant text and model/token metadata, not just a successful HTTP
|
|
91
|
+
connection or a locally rendered user message. A second message in that thread
|
|
92
|
+
uses the thread ID as the agent session ID.
|
|
93
|
+
|
|
94
|
+
Save the resulting URL containing `?threadId=...`. The dev page can reload the
|
|
95
|
+
completed transcript; it is not the shared React reconnect/replay client. Do not
|
|
96
|
+
use closing the tab mid-turn as a substitute for this completed-turn check.
|
|
97
|
+
|
|
98
|
+
## Restart and artifact limits
|
|
99
|
+
|
|
100
|
+
For a file-producing turn, ask the agent to save a small text file at
|
|
101
|
+
`/home/agent/artifacts/quickstart.txt` with a distinctive value you can compare
|
|
102
|
+
later. A claim in the assistant's answer is not proof that the file exists.
|
|
103
|
+
In the maintained chat template, opening `/api/files` in the same signed-in
|
|
104
|
+
browser lists metadata under `/home/agent/artifacts`. Check that your generated
|
|
105
|
+
`src/worker.ts` actually mounts this route before relying on it.
|
|
106
|
+
|
|
107
|
+
After the turn completes, stop **only the local `pnpm dev` process**, then run
|
|
108
|
+
`pnpm dev` again from the same project directory. Preserve the local Wrangler
|
|
109
|
+
state (`.wrangler/state`), database configuration, auth secret, and app identity.
|
|
110
|
+
Reopen the saved thread URL and sign in to the same app account if needed. Check
|
|
111
|
+
the transcript and artifact index again. This exercises a local Worker restart,
|
|
112
|
+
not sandbox suspension, deletion, or host-loss recovery.
|
|
113
|
+
|
|
114
|
+
**The stock dev page does not reopen artifact contents.** Its file/image parts
|
|
115
|
+
are labels, not download links. `/api/files` is a metadata index, not a file-read
|
|
116
|
+
endpoint; it returns `warming` when no ready sandbox exists and does not provision
|
|
117
|
+
or resume one. Uploading a file and replaying a transcript are also not proof of
|
|
118
|
+
saved artifact bytes. Completing a saved-artifact-reopened check requires a
|
|
119
|
+
product-owned, authorized file reader/storage integration and a comparison of
|
|
120
|
+
the actual contents before and after restart. Do not describe that check as
|
|
121
|
+
passed from this scaffold alone.
|
|
122
|
+
|
|
123
|
+
For product assembly after this local walkthrough, see
|
|
124
|
+
[`examples/chat-app.md`](../examples/chat-app.md) and the shared workspace example
|
|
125
|
+
above. The product supplies its UI and artifact access; those examples do not
|
|
126
|
+
turn source-only behavior into a published scaffold feature.
|
package/package.json
CHANGED
package/template/_package.json
CHANGED
|
@@ -21,17 +21,17 @@
|
|
|
21
21
|
"@tangle-network/agent-app": "__AGENT_APP_VERSION__"
|
|
22
22
|
},
|
|
23
23
|
"peerDependencies": {
|
|
24
|
-
"@tangle-network/agent-eval": "0.
|
|
24
|
+
"@tangle-network/agent-eval": ">=0.199.0 <0.200.0",
|
|
25
25
|
"@tangle-network/agent-integrations": ">=0.54.2 <0.56.0",
|
|
26
26
|
"@tangle-network/agent-interface": "2.13.0",
|
|
27
|
-
"@tangle-network/agent-runtime": ">=0.
|
|
27
|
+
"@tangle-network/agent-runtime": ">=0.282.2 <0.283.0"
|
|
28
28
|
},
|
|
29
29
|
"devDependencies": {
|
|
30
|
-
"@tangle-network/agent-eval": "0.
|
|
30
|
+
"@tangle-network/agent-eval": "0.199.1",
|
|
31
31
|
"@tangle-network/agent-integrations": "0.55.0",
|
|
32
32
|
"@tangle-network/agent-interface": "2.13.0",
|
|
33
|
-
"@tangle-network/agent-knowledge": "17.1.
|
|
34
|
-
"@tangle-network/agent-runtime": "0.
|
|
33
|
+
"@tangle-network/agent-knowledge": "17.1.10",
|
|
34
|
+
"@tangle-network/agent-runtime": "0.282.2",
|
|
35
35
|
"@tangle-network/sandbox": "0.53.0",
|
|
36
36
|
"@types/node": "^22.20.1",
|
|
37
37
|
"typescript": "^7.0.2",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"@tangle-network/agent-app": "__AGENT_APP_VERSION__",
|
|
23
23
|
"@tangle-network/agent-gateway": "0.11.4",
|
|
24
24
|
"@tangle-network/agent-interface": "2.13.0",
|
|
25
|
-
"@tangle-network/agent-runtime": "0.
|
|
25
|
+
"@tangle-network/agent-runtime": "0.282.2",
|
|
26
26
|
"@tangle-network/sandbox": "0.53.0",
|
|
27
27
|
"better-auth": "^1.7.2",
|
|
28
28
|
"drizzle-orm": "^0.45.2",
|
|
@@ -30,13 +30,13 @@
|
|
|
30
30
|
"viem": "^2.0.0"
|
|
31
31
|
},
|
|
32
32
|
"peerDependencies": {
|
|
33
|
-
"@tangle-network/agent-eval": "0.
|
|
33
|
+
"@tangle-network/agent-eval": ">=0.199.0 <0.200.0",
|
|
34
34
|
"@tangle-network/agent-integrations": ">=0.54.2 <0.56.0"
|
|
35
35
|
},
|
|
36
36
|
"devDependencies": {
|
|
37
|
-
"@tangle-network/agent-eval": "0.
|
|
37
|
+
"@tangle-network/agent-eval": "0.199.1",
|
|
38
38
|
"@tangle-network/agent-integrations": "0.55.0",
|
|
39
|
-
"@tangle-network/agent-knowledge": "17.1.
|
|
39
|
+
"@tangle-network/agent-knowledge": "17.1.10",
|
|
40
40
|
"@cloudflare/workers-types": "^5.20260827.1",
|
|
41
41
|
"@types/better-sqlite3": "^9.6.0",
|
|
42
42
|
"@types/node": "^22.20.1",
|