@tangle-network/create-agent-app 0.46.55 → 0.46.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/create-agent-app",
-  "version": "0.46.55",
+  "version": "0.46.57",
   "description": "Create a tested Tangle agent application with either a tool loop or a complete chat interface.",
   "keywords": [
     "tangle",

package/template/AGENTS.md

@@ -1,67 +1,32 @@
-# AGENTS.md — you are customizing an agent-app
+# Customize an agent-app
 
-You are a coding agent working in a project generated by `create-agent-app`. This
-project is a thin customization layer on top of `@tangle-network/agent-app` (the
-shell) and the Tangle agent substrate (the engine). Walk this contract before you
-touch anything. It is a checklist, not prose — follow it in order.
+This project supplies domain configuration and application wiring around `@tangle-network/agent-app`.
+Read [CUSTOMIZE.md](CUSTOMIZE.md) for the customization checklist.
+For knowledge ingestion or proposal checks, read [KNOWLEDGE.md](KNOWLEDGE.md).
 
-## 0. Orient
+## DATA vs CODE
 
-- [ ] Read this file end to end.
-- [ ] Read `CUSTOMIZE.md` — the ordered fill-checklist. It is your task list.
-- [ ] Read `KNOWLEDGE.md` — how the build-loop vs the act-gate work.
-- [ ] Run `pnpm install && pnpm typecheck && pnpm test`. Confirm green BEFORE editing.
+- `agent.config.ts` contains identity, taxonomy, sources, integrations, UI, and model configuration as plain values.
+- `knowledge/` contains domain documents, never secrets.
+- `src/agent-app.ts` composes configuration and bindings through the shell's supported interfaces.
+  Prefer the maintained preset; override a handler only when the preset cannot express required persistence.
+- `src/worker.ts` owns routing and recovers trusted context from authentication.
 
-## 1. The one rule (layering)
+Reuse the shell's mechanisms and its engine peers rather than forking them into this product.
+Keep domain values in configuration and behavior in the composer.
+Use `AgentAppConfig` and its exported JSON Schema from `@tangle-network/agent-app/config` as the configuration contract.
 
-> You change behavior by editing DATA and the COMPOSER — never by editing
-> `@tangle-network/agent-app`.
+## Required boundaries
 
-- The shell (`@tangle-network/agent-app/*`) owns mechanism: the tool loop, the
-  agent→app tool side channel, the approval/proposal contract, the knowledge gate,
-  billing, crypto.
-- The engine (`@tangle-network/agent-eval`, `agent-runtime`, `agent-integrations`)
-  is a peer dependency. Do not bundle it, do not fork it.
-- You own: `agent.config.ts` (DATA) + `src/` (the COMPOSER + routes) + `knowledge/`
-  (DATA). That is the whole surface.
+Regulated proposal types require a named human and cannot execute automatically.
+Keep `regulatedTypes` a subset of `proposalTypes`; never downgrade a regulated action to an immediate tool.
+Derive user, workspace, and thread identity from the server session, never model arguments.
+Keep source attribution in the knowledge loop; low-confidence proposals remain proposals rather than applied changes.
+Domain figures require a real record or an explicit "NOT ON FILE" outcome.
 
-## 2. DATA vs CODE — know which file you're in
+## Verification
 
-- [ ] DATA → `agent.config.ts`: identity, taxonomy, knowledge requirements/sources,
-      integrations, ui, model. Plain values. No control flow. No imports of engine
-      internals. If you're writing an `if`, you're in the wrong file.
-- [ ] DATA → `knowledge/`: domain documents. Content, not code. No secrets.
-- [ ] CODE → `src/agent-app.ts`: the COMPOSER. Wires config + bindings into the
-      shell's seams. Override ONE handler here only when the preset genuinely can't
-      express your persistence — default to the preset.
-- [ ] CODE → `src/worker.ts`: the chat route. Extend the route; recover trusted
-      per-turn context from real auth. Do not move domain values here.
-
-## 3. Invariants — fail-closed, never relax
-
-- [ ] HUMAN-IN-THE-LOOP: every regulated proposal type (`config.taxonomy.regulatedTypes`)
-      is routed to a named human and CANNOT auto-execute. Keep regulated types in
-      `regulatedTypes`. Never downgrade a regulated action to an immediate tool.
-- [ ] `regulatedTypes` ⊆ `proposalTypes`. The test enforces this; keep it green.
-- [ ] GROUNDING: never fabricate a domain figure (price, coverage, clause, id). A
-      real record or an explicit "NOT ON FILE". The persona fragment says this — keep it.
-- [ ] TRUSTED CONTEXT: `userId` / `workspaceId` / `threadId` come from the server
-      session, NEVER from model tool args. The model must not forge identity.
-- [ ] SOURCES ALWAYS RECORDED, PROPOSALS GATED: in the knowledge loop, grounding is
-      never dropped; a low-confidence knowledge PROPOSAL is. Propose, don't apply.
-
-## 4. Verify (every change ends here)
-
-- [ ] `pnpm typecheck` — clean. Proves `agent.config.ts` matches the shell contract.
-- [ ] `pnpm test` — green. Proves the composer wiring + invariants.
-- [ ] `pnpm knowledge:ingest` — enumerates your docs + sources (DRY) without error.
-- [ ] For a real deploy: `pnpm dev` (wrangler) after filling `wrangler.toml`.
-
-If any of these is red, you are not done. Do not weaken a test to pass.
-
-## 5. The schema floor
-
-`agent.config.ts` is validated by the TypeScript type `AgentAppConfig` from
-`@tangle-network/agent-app/config`. A non-TS agent can read the same shape from its
-JSON Schema: `agentAppConfigJsonSchema` (exported from that subpath). That schema +
-this file + `CUSTOMIZE.md` are the complete spec for what you may put where.
+Use the package's typecheck and test scripts to verify configuration, composer behavior, and these boundaries.
+Run `pnpm knowledge:ingest` to check source enumeration without applying changes.
+Before deployment, complete the required environment configuration and exercise the actual user flow.
+Fix a failed check without weakening the behavior it protects.

package/template/CLAUDE.md

@@ -1,6 +1 @@
-# CLAUDE.md
-
-The behavior contract for this project lives in `AGENTS.md`. Read it first, then
-walk `CUSTOMIZE.md` (the fill-checklist) and `KNOWLEDGE.md` (build-loop vs act-gate).
-
 @AGENTS.md

package/template-chat/AGENTS.md

@@ -1,76 +1,32 @@
-# AGENTS.md — you are customizing a chat agent-app
+# Customize a chat agent-app
 
-You are a coding agent working in a project generated by `create-agent-app --chat`.
-This project is a thin customization layer on top of `@tangle-network/agent-app`
-(the shell): the whole server chat vertical — auth, thread/message persistence,
-streaming turns with buffered replay, multimodal uploads, human-in-the-loop asks,
-and API access — is ASSEMBLED from shell factories, not written here.
-Walk this contract before you touch anything.
-It is a checklist, not prose — follow it in order.
+This project composes the shared chat application shell from `@tangle-network/agent-app`.
+Read [CUSTOMIZE.md](CUSTOMIZE.md) for required configuration and deployment setup.
 
-## 0. Orient
+## DATA vs CODE
 
-- [ ] Read this file end to end.
-- [ ] Read `CUSTOMIZE.md` — the ordered fill-checklist. It is your task list.
-- [ ] Run `pnpm install && pnpm typecheck && pnpm test`. Confirm green BEFORE editing.
-      The test suite includes the end-to-end turn gate (fake sandbox producer →
-      streamed turn → persisted transcript) — it proves the assembly, not stubs.
+- `agent.config.ts` contains identity, prompt, model, backend, and renderable interaction choices as plain values.
+- `prompts/system.md` supplies domain intent and evidence requirements.
+  State desired behavior; let the executing agent choose tools instead of embedding command or installation scripts.
+- `src/chat.ts` composes the shell's authentication, persistence, streaming, upload, and interaction factories.
+- `src/sandbox.ts` resolves sandbox access and profiles; domain reasoning belongs in the agent.
+- `src/worker.ts` routes requests to those handlers.
+- `migrations/` must match the persisted schema; the generated application's tests execute the real migration.
 
-## 1. The one rule (layering)
+Extend supported configuration and callbacks before duplicating a shell mechanism or forking the package.
 
-> You change behavior by editing DATA and the COMPOSER — never by editing
-> `@tangle-network/agent-app`.
+## Required boundaries
 
-- The shell owns mechanism: turn protocol + hook order (`createChatTurnRoutes`
-  over agent-runtime's `handleChatTurn`), persistence columns (`createChatTables`),
-  the upload inline-vs-sandbox split, the interaction answer contract, auth guards.
-- You own: `agent.config.ts` + `prompts/system.md` (DATA), `src/` (the COMPOSER +
-  routes), `migrations/` (must mirror the schema — the e2e test executes it),
-  `public/` (the dev page). That is the whole surface.
+Derive user and workspace identity from the authenticated session, never request bodies or model output.
+An inaccessible thread returns 404 without disclosing that it exists.
+Missing sandbox credentials produce an explicit failure, never a canned agent response.
+Agents own reasoning and tools; the application owns durable records, billing, and approval enforcement.
+Agent writes use schema-validated tools rather than records parsed from prose.
+Preserve the persona's fabrication rule: a real record or an explicit "NOT ON FILE" outcome.
 
-## 2. DATA vs CODE — know which file you're in
+## Verification
 
-- [ ] DATA → `agent.config.ts`: name, system prompt, model default + effort,
-      provider input limit, harness, gateway pricing, and renderable ask kinds.
-      Plain values. If you're writing an `if`, you're in the wrong file.
-- [ ] DATA → `prompts/system.md`: the persona. State intents and hard rules,
-      never implementations — no shell commands, CLI flags, or install scripts.
-      The executing agent chooses tools at execution time.
-- [ ] CODE → `src/chat.ts`: the COMPOSER. Wires config + env into the shell's
-      factories. Extend seams here (billing hooks, `transformFinalText`,
-      `onTurnComplete`); never re-implement what a factory already does.
-- [ ] CODE → `src/gateway.ts`: API keys and OpenAI-compatible requests enter
-      the same owned thread and chat route.
-- [ ] CODE → `src/sandbox.ts`: the sandbox lane (box naming, credentials,
-      profile). All agent intelligence lives IN the sandbox; this file only
-      reaches it.
-- [ ] CODE → `src/worker.ts`: routing only. New endpoint = new handler in
-      `src/chat.ts`, one `if` here.
-
-## 3. Invariants — fail-closed, never relax
-
-- [ ] TRUSTED CONTEXT: `userId`/`workspaceId` come from the better-auth SESSION,
-      never from a request body or model output. The `authorize` seam is the only
-      place identity is established — keep it that way.
-- [ ] THREAD ACCESS: an inaccessible thread reads as 404, indistinguishable from
-      a missing one. A cross-workspace probe must not learn the thread exists.
-- [ ] NO MOCK AGENT: without sandbox credentials a turn fails loud with a clear
-      error. Never add a canned-response fallback — a fake answer is worse than
-      an honest failure.
-- [ ] AGENT-NATIVE: intelligence and tooling live in the sandboxed agent;
-      durability (rows, turn buffer) and money live here. If you're about to
-      parse the agent's prose for data, stop — that's a schema-validated tool's
-      job (see the shell's `/tools`).
-- [ ] GROUNDING: the persona's fabrication rule stays. A real record or an
-      explicit "NOT ON FILE".
-
-## 4. Verify (every change ends here)
-
-- [ ] `pnpm typecheck` — clean. Proves the assembly matches the shell contract.
-- [ ] `pnpm test` — green. The e2e gate runs the REAL migration + REAL factories
-      with one fake (the sandbox event feed). If it fails, the app drifted from
-      the framework — fix the drift, not the test.
-- [ ] For a real deploy: fill `wrangler.toml` + `.dev.vars`, run
-      `pnpm db:migrate:local`, then `pnpm dev` and exercise the dev page.
-
-If any of these is red, you are not done. Do not weaken a test to pass.
+Run the package's typecheck and test scripts.
+The turn test uses real migrations and shell factories with a fake sandbox event feed; it does not prove live sandbox access.
+For deployment, complete environment configuration, apply the required database migrations, and exercise the actual page and turn flow.
+Fix failures without weakening the protected behavior.

package/template-chat/CLAUDE.md

@@ -1,6 +1 @@
-# CLAUDE.md
-
-The behavior contract for this project lives in `AGENTS.md`. Read it first, then
-walk `CUSTOMIZE.md` (the fill-checklist).
-
 @AGENTS.md