glove-foundry 0.3.2 → 0.4.0

package/docs/release-verification.md

@@ -0,0 +1,74 @@
+# Foundry production integration — release handoff
+
+Verified on 9 September 2026 with Node 22.18. This is a **tested release candidate, not a published release or a guarantee for an untested production application**.
+
+## Source and scope
+
+The goals/facts/forms follow-up is included in this candidate. Merge and publication
+remain paused for review. It adds typed lazy fields, native custom context
+providers, execution handles, scoped preparation, durable goal/form/fact adapters,
+the inspector guidance summary, and the guided-intake example. Both repository
+agent skills now describe these first-class fields instead of requiring custom hooks.
+
+Follow-up validation: Foundry **89 tests passed**; memory **202 tests passed**;
+the new preparation tests reuse one verified fact for both a goal and a form.
+The real-worker guided-intake verifier passes before and after stopping and
+reconstructing Foundry, preserving progress, facts and form answers without
+duplicates. Concurrent fact writers and process-death lock recovery pass.
+The canonical architecture/runtime verifiers, package/example typechecks,
+documentation production build, and a freshly generated starter typecheck pass.
+The fresh starter uses the tested workspace dependency closure, not unpublished
+registry versions. The inspector was exercised in the browser; its completed
+progress and corrected final reply were verified. No new live-provider or
+telephony acceptance test is claimed for this follow-up.
+
+- Candidate branch: `codex/foundry-production-release`, built on upstream `main` at `7f6b97b8`.
+- The original `codex/glove-foundry-release` checkout and its dirty Hercules work were preserved. Do not publish that older checkout by mistake.
+- Reconciles reusable Foundry work with upstream `glove-core` 4 and `glove-memory` 2, retaining native runtime context, tasks, facts/forms, voice and document surfaces.
+- Excludes Hercules application updates. Includes durable Foundry instance/conversation data, SQLite structured memory, MCP lifecycle controls, tool approvals, steering, bounded programmatic tools, and multimodal conversation integration.
+- Foundry now requires Station `^2.3.0`; the lockfile resolves the completed-child drain and cancellation escalation fixes in `station-env`, `station-signal`, and `station-schedules` 2.3.0.
+- The Clack setup wizard adds project/target/template/package-manager choices, confirmation, optional installation, and non-interactive flags. Node 20.12+ is required; use Node 22.13+ for SQLite memory.
+- The package README, both generated starter READMEs, handbook, website setup-and-CLI page, navigation, and machine-readable Foundry docs cover setup, commands, troubleshooting, and production boundaries.
+
+The Glove Foundry and Glove skills guided integration against native primitives rather than introducing parallel memory, voice, or workspace systems.
+
+## Verification evidence
+
+| Surface | Result |
+| --- | --- |
+| Entire publish build graph | Passed, including ordered legacy Glovebox dependencies; no publishing command run |
+| Foundry runtime suite | 80 passed, including real completed/cancelled worker process cleanup |
+| New initializer and existing scaffold tests | 11 passed; terminal policy, flags, piped setup, invalid options, Next.js preservation, versions, and all four package-manager dispatch paths |
+| Interactive terminal | Selected minimal starter and npm; confirmed generation; separately cancelled with Ctrl+C and verified no output directory |
+| Packaged CLI | Packed tarball scaffolds a project; generated project type-checks against the tested workspace dependency closure |
+| Real dependency installation | Initializer ran `pnpm install` to completion in a fresh minimal project; registry-installed project type-check passed and next steps correctly omitted reinstalling |
+| Core / JS / Python / Lisp | 24 / 83 / 87 / 99 tests passed |
+| Structured memory | 198 passed, including 10 SQLite durability/isolation/concurrency/corruption tests |
+| MCP | 50 passed with deterministic recycling clock and serialized stdio integration tests |
+| Native working environment / documents | 427 / 98 tests passed |
+| Voice S2S / avatar / LiveKit | 48 / 16 / 10 tests passed; native, React and Next voice hosts type-checked |
+| Facts | 23 tests passed |
+| Canonical Foundry example | Type-check, architecture verifier, and end-to-end runtime verifier passed |
+| Live Gemini integration | Real provider session invoked direction-recording and briefing tools and returned spoken confirmation |
+| Documentation website | Production Next.js build passed, including setup page and Foundry machine-readable routes |
+| Release metadata | Changeset preview, published-version preflight, frozen-lockfile install and whitespace checks passed |
+
+The packed-consumer check uses the tested workspace dependency closure, not a fresh registry-only installation of unreleased packages. The live voice check does not certify a browser microphone, phone carrier, Discord/Telegram installation, or application-specific deployment. Those need acceptance testing with the eventual production application's adapters and credentials. Windows installation dispatch is implemented but was not exercised on this macOS host.
+
+## Release procedure
+
+1. Review and merge the candidate into `main`; let CI run on the merged result.
+2. Review and merge the automated **Version Packages** PR. The pending changeset schedules minor releases for Foundry, core, memory, MCP and the three REPL packages.
+3. Inspect the generated dependent bumps. The existing Changesets peer-dependency policy currently schedules a **major Scratchpad bump** because its optional MCP peer uses `workspace:*`, plus dependent patch bumps. This policy was not silently changed.
+4. From a clean, updated checkout of the repository root, with npm release access configured, run `npx release`. The wrapper builds and publishes already-versioned packages; it does not apply pending changesets itself.
+5. Verify published versions and install a new project from the registry. Exercise the production application's actual voice, documents, persistence, authorization and external integrations before rollout.
+
+No npm publication, main-branch merge, or production deployment was performed. Current tarballs retain pre-release-bump manifest versions and are only local verification artifacts; do not manually publish them over existing versions.
+
+## Day-one production configuration
+
+- Keep credential acquisition and refresh in user-owned adapters. The initializer never asks for API keys.
+- Separate durable Foundry instance/conversation data, agent memory, scheduler/runtime state, and working-environment VFS storage; persisting one does not persist the others. Starter storage is disposable demo storage.
+- SQLite memory is opt-in and single-host. Select different adapters for distributed production requirements.
+- Preserve loopback defaults unless a request-authorization adapter protects the control plane. Set bounded multimodal request limits for documents/media.
+- Maintain application-specific health checks and a rollback plan. Successful framework tests cannot guarantee the behavior of an application that has not yet been provided.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glove-foundry",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "An Effect-native, file-routed framework for typed, observable Glove agent applications",
   "type": "module",
   "license": "MIT",
@@ -54,22 +54,24 @@
     "agent-applications"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=20.12.0"
   },
   "dependencies": {
+    "@clack/prompts": "^1.8.0",
     "effect": "^3.22.1",
-    "station-env": "^2.2.0",
-    "station-signal": "^2.2.0",
-    "station-schedules": "^2.2.0",
+    "station-env": "^2.3.0",
+    "station-signal": "^2.3.0",
+    "station-schedules": "^2.3.0",
     "tsx": "^4.21.0",
     "zod": "^4.3.6",
-    "glove-core": "3.7.1",
-    "glove-js": "0.4.2",
-    "glove-memory": "1.2.0",
-    "glove-mcp": "1.1.2",
-    "glove-python": "0.3.2",
-    "glove-lisp": "0.4.2",
-    "glove-mesh": "0.1.3",
+    "glove-core": "4.1.0",
+    "glove-facts": "0.1.2",
+    "glove-lisp": "0.5.0",
+    "glove-js": "0.5.0",
+    "glove-mcp": "1.2.0",
+    "glove-memory": "2.1.0",
+    "glove-python": "0.4.0",
+    "glove-mesh": "0.1.5",
     "glove-working-environment": "0.6.1"
   },
   "devDependencies": {

package/templates/minimal/README.md

@@ -2,6 +2,13 @@
 
 A [Glove Foundry](https://github.com/porkytheblack/glove/tree/main/packages/glove-foundry) application.
 
+## First run
+
+Use Node.js 22.13+ (recommended; minimum 20.12). This minimal starter needs an
+OpenRouter key. For a keyless first look, choose the guided travel-concierge
+template instead. Run these commands from this project's directory; skip
+installation if you already accepted it in the setup wizard.
+
 ```bash
 cp .env.example .env.local     # add your OPENROUTER_API_KEY
 {{installCommand}}
@@ -10,6 +17,24 @@ cp .env.example .env.local     # add your OPENROUTER_API_KEY
 
 Then open **http://127.0.0.1:4141** and press **Start a run**.
 
+Choose **assistant**, send a short request, and open the run to inspect its events.
+Edit `agents/assistant/agent.ts`, save, and run again. The dev server reloads your
+definition. Run `{{typecheckCommand}}` and `{{lintCommand}}` after changes.
+
+The initializer never asks for secrets. Add `OPENROUTER_API_KEY` to `.env.local`
+yourself and restart the dev server. Do not commit the key. If a run fails, check
+the trace for authentication or rate-limit errors. If port 4141 is occupied, use
+the local `glove foundry dev --port 4142` command.
+
+## Before using real data
+
+The starter uses disposable in-memory storage. Configure durable Foundry runtime
+data, a durable Glove conversation store, native memory adapters, and VFS
+persistence independently. For a single host, Foundry includes
+`FileFoundryDataAdapter`; `glove-memory/sqlite` supports Node 22.13+. Use your own
+transactional adapters across hosts. A non-loopback listener requires an
+application-owned `requestAuthorization` adapter and a deliberate network boundary.
+
 ## The one idea to understand first
 
 Foundry separates a **definition** (code — what an agent can assemble, at `agents/assistant/agent.ts`) from an **instance** (data — one persisted identity with its own context, installed apps, and conversations). One definition serves many instances.
@@ -32,10 +57,13 @@ Any file matching these names under an agent folder is discovered automatically.
 | `memory/*.memory.ts` | A memory profile | `defineMemory` |
 | `layers/*.layer.ts` | Native Glove setup | `defineLayer` |
 | `subscribers/*.subscriber.ts` | An observer | `defineSubscriber` |
-| `schedules/*.ts` | Recurring or future work | `defineSchedule` |
 
 Create the file, add it to `composeAgent(...)`, and the dev server picks it up and regenerates types.
 
+Schedules are data, not auto-discovered file routes. You may keep a `defineSchedule`
+value in an ordinary colocated module and import it into the agent's lazy
+`schedules` field, or create future work dynamically with Foundry's scheduling tools.
+
 Want a worked example with a calendar application, a chat transport, memory, a schedule, and a sandboxed REPL? Scaffold the travel concierge:
 
 ```bash
@@ -46,7 +74,7 @@ npx glove-foundry init my-concierge --template travel-concierge
 
 | Command | What it does |
 | --- | --- |
-| `{{devCommand}}` | Discover agents, typecheck, generate routes, serve the runtime and inspector |
+| `{{devCommand}}` | Discover agents, generate routes, serve the runtime and inspector |
 | `{{startCommand}}` | Run without file watching |
 | `{{lintCommand}}` | Lint, including the Foundry file-routing rules |
 | `{{typecheckCommand}}` | `tsc --noEmit` |

package/templates/travel-concierge/README.md

@@ -4,6 +4,12 @@ A [Glove Foundry](https://github.com/porkytheblack/glove/tree/main/packages/glov
 
 It runs before you configure anything — there is a built-in demo model, so you get real runs and a real event trace with no API key.
 
+## First run, step by step
+
+Use Node.js 22.13+ (recommended); the CLI requires Node 20.12 or newer. Open a
+terminal in this project's directory. If the setup wizard already installed
+dependencies, you can skip the install command below.
+
 ```bash
 cp .env.example .env.local     # optional: add OPENROUTER_API_KEY for real answers
 {{installCommand}}
@@ -12,6 +18,23 @@ cp .env.example .env.local     # optional: add OPENROUTER_API_KEY for real answe
 
 Then open **http://127.0.0.1:4141** and press **Start a run**.
 
+Choose **concierge** and send “Find a flight to Nairobi.” Open the resulting run
+to follow its model calls, tool calls and result. This is a deterministic demo:
+flights, calendar and messaging are examples, not live provider integrations.
+Change `agents/concierge/agent.ts`, save, and try another run to see the reload.
+
+To get live model answers, put your own `OPENROUTER_API_KEY` in `.env.local`, then
+restart the dev server. Never commit that file. The wizard does not collect keys.
+Setting a model key does not connect a real calendar or messenger by itself.
+
+## If something goes wrong
+
+- Check `node --version` if you get an engine or SQLite error.
+- Run `{{installCommand}}` again if installation was interrupted; project files are retained.
+- If port 4141 is occupied, run the local `glove foundry dev --port 4142` command and open that address.
+- If a run fails, open its event trace; a provider rate limit is different from a typecheck failure.
+- In-memory demo state resets across workers/restarts. Read **Going to production** before storing real user work.
+
 ---
 
 ## The one idea to understand first
@@ -71,11 +94,10 @@ Any file matching these names under an agent folder is discovered automatically.
 | `memory/*.memory.ts` | A memory profile | `defineMemory` |
 | `layers/*.layer.ts` | Native Glove setup | `defineLayer` |
 | `subscribers/*.subscriber.ts` | An observer | `defineSubscriber` |
-| `schedules/*.ts` | Recurring or future work | `defineSchedule` |
 | `connections/*.connection.ts` | A long-lived inbound worker | `defineConnection` |
 | `actions/*.action.ts` | A playbook action | `definePlaybookAction` |
 
-Every field of `defineAgent` accepts **a value or a function**. A function runs per request with the full context — message, history, instance, installations — which is how one definition adapts without branching inside a prompt.
+Assembly fields such as tools, memory, and schedules accept **a value or a function**. A resolver receives the current assembly context, including the message and instance, so one definition can adapt its capabilities to the request.
 
 ---
 
@@ -124,7 +146,12 @@ For inbound, point the provider's webhook at your own HTTP handler and call `dis
 
 ### Schedule work
 
-Agents never call `setTimeout`. Add a `schedules/*.ts` definition, or let the agent create one at runtime through Foundry's scheduling tools. Either way it becomes a persisted activation you can see under **Automations**.
+Use Foundry's scheduling tools for durable future work instead of `setTimeout`.
+Schedules are data, not auto-discovered file routes. This example imports an
+ordinary `schedules/trip-countdown.ts` module and returns its value from the agent's
+lazy `schedules` field. You can also let the agent create schedules at runtime.
+Foundry persists the activation so it can wake the instance later; inspect these
+under **Automations**.
 
 ### Call agents from your own code
 
@@ -163,11 +190,12 @@ Filters live in the URL, so `/runs?status=failed` is a link you can send. Press
 
 ## Going to production
 
-1. **Replace the data adapter.** `MemoryFoundryDataAdapter` in `foundry.application.ts` loses everything on restart. Implement `FoundryDataAdapter` against your database.
+1. **Persist each store.** `MemoryFoundryDataAdapter` in `foundry.application.ts` is disposable. Use `FileFoundryDataAdapter` for single-host runtime data or a transactional database adapter for multiple hosts. Also replace the agent's `MemoryStore` with a durable conversation store, provide durable native memory adapters (such as `glove-memory/sqlite` on Node 22.13+), and persist the working-environment VFS. Persisting one does not persist the others.
 2. **Delete `lib/demo-model.ts`** and the fallback in `agent.ts` once `OPENROUTER_API_KEY` is set.
 3. **Own your credentials.** Foundry stores account *references*, never secrets. Keep tokens in your own adapter or secret manager.
 4. **Run `{{startCommand}}`** rather than `dev` — no file watching, no restart-on-change.
 5. **Keep the ESLint preset.** `glove-foundry/eslint` rejects patterns that break file routing, such as a hand-written `id` on a file-routed definition.
+6. **Protect the control plane.** A non-loopback bind requires an application-owned `requestAuthorization` adapter. Put TLS and network/rate policy in front of it.
 
 ---
 
@@ -191,7 +219,7 @@ Add an environment package when you need it — `glove-env-documents`, `glove-en
 
 | Command | What it does |
 | --- | --- |
-| `{{devCommand}}` | Discover agents, typecheck, generate routes, serve the runtime and inspector |
+| `{{devCommand}}` | Discover agents, generate routes, serve the runtime and inspector |
 | `{{startCommand}}` | Run without file watching |
 | `{{lintCommand}}` | Lint, including the Foundry file-routing rules |
 | `{{typecheckCommand}}` | `tsc --noEmit` |