glove-foundry 0.4.0 → 0.5.0

package/docs/execution-release.md

@@ -0,0 +1,57 @@
+# Station 3 and execution mounts — release handoff
+
+Verified on 23 September 2026 with Node 22.18 and pnpm 10.28.2. The complete pending Changesets plan has been applied, including package versions and changelogs. npm publication and production documentation deployment have not been performed.
+
+## What ships
+
+- `glove-execution`: optional, adapter-backed browser and sandbox mounts. The default entrypoint is portable; Station adapters live under `glove-execution/station`. Mounts attach tools and transient screenshot context without taking or replacing the agent model.
+- `glove-core`: runtime context providers accept native content parts alongside text. Browser and sandbox implementation dependencies remain outside core. Runtime-context telemetry omits media payloads and URLs.
+- `glove-foundry`: agent jobs run in a managed local Station 3 daemon. Optional `stationDaemon` application configuration starts browser/sandbox providers in that same daemon. Generic mount cleanup handles success, failure and cancellation. Scheduled activation transitions are serialized so delayed daemon acknowledgements cannot overwrite a pause or cancellation.
+- Foundry Operator: a general-purpose example with Steel proxy sessions, Docker sandboxes and server previews, native per-conversation memory, application-owned continuity/compaction prompts, and native Foundry sleep. Telegram is a user request, not a preloaded workflow.
+- Existing Station room examples use Station 3's daemon and separate dashboard rather than the retired `station-kit` entrypoint.
+
+The versioned candidate contains `glove-core` 4.2.0, `glove-foundry` 0.5.0 and the initial `glove-execution` 0.2.0 publication. It also applies the existing VFS changesets and the dependency-driven version bumps computed by Changesets. The pending notes have been consumed into package changelogs; no second Version Packages PR is needed for this candidate. The workspace lockfile was validated after versioning.
+
+## Documentation and illustrations
+
+- [Execution architecture and migration](./execution.md)
+- [Package guide](../../glove-execution/README.md)
+- [Operator setup and verification](../../../examples/foundry-operator/README.md)
+- Site guide: `/docs/execution`
+- Illustrated walkthrough: `/foundry/docs/browser-and-sandbox`
+- Blog: `/blog/agents-with-browsers-and-sandboxes`
+- Updated package catalog, Foundry landing page, documentation navigation and repository agent skills.
+- Both `/llms.txt` and `/llms-full.txt`, and both `/foundry/llms.txt` and `/foundry/llms-full.txt`, include the new package and shared Station configuration. The full references include the Operator documentation once, including ownership and lifecycle limits.
+
+The family diagram explains core, Foundry, mounts and adapters. The architecture diagram shows jobs and optional resources sharing one Station daemon. Public demo screenshots illustrate browser scripting and a sandbox-hosted server without exposing credentials or private conversations.
+
+## Verification
+
+The repository's complete publish build graph (legacy dependency first), package typechecks and site production build passed. The affected suites passed: core 25, execution 11 (one separately verified real-browser integration is opt-in), Foundry 97 and Operator 5. Delayed-acknowledgement regressions exercise pause and cancel while a real daemon run is already visible; existing tests cover updates, recurrence, overdue reconstruction and resumption.
+
+Additional checks cover:
+
+- Registry version preflight and the complete Changesets version plan. After applying that plan, all planned publishable releases are ahead of npm or first publications; the frozen lockfile check and full publish build passed again. Versioned tarballs have valid exports and reference the new dependency versions.
+- Tarball contents, declared export/type targets, daemon/loader entrypoints, packaged imports and CLI scaffolding using the tested workspace dependency closure. This is not a fresh registry install of unpublished versions.
+- Desktop and mobile views of both guides, the blog, package catalog, Foundry landing page and blog index: no JavaScript errors, horizontal overflow or broken images.
+- HTTP 200 responses and new API coverage in all four LLM reference endpoints.
+- Real Chromium integration, and a live Operator run creating a proxied Steel browser, reading a public page, taking a screenshot, closing the browser and checking an existing Docker-hosted server over HTTP.
+- An earlier isolated memory verifier checked compaction and recall. Memory is per agent conversation by default; cross-conversation retrieval and continuity policy belong to the application.
+
+Telegram authentication is **not verified**: its login page remained on a loading state and no QR login completed. Public browser and sandbox verification must not be represented as successful Telegram account control.
+
+## Operational boundaries
+
+Foundry owns the managed local daemon process. Its current job queue is in memory; interrupted live jobs are not restored after process loss. Durable conversation, activation and memory adapters have their own persistence behavior. This release does not add distributed execution or high availability.
+
+Application resource factories run once per daemon and must release partially acquired resources if they throw before returning. Foundry closes returned providers on shutdown and startup failure. Retention across turns is an explicit adapter/application policy; choose scope identities, resource grants, credentials and expiration accordingly.
+
+The private `onReady` connection has Station 3 operator/admin authority. Keep it in trusted host code, never in model context or public UI responses. Steel proxy configuration is an application/provider setting, and still depends on account availability. Foundry requires Node 22+; the portable mount entrypoint does not acquire that requirement.
+
+## Release procedure
+
+1. Review and merge the versioned PR, including generated changelogs and dependent-package bumps.
+2. Pull the merged `main` and run `pnpm install --frozen-lockfile`.
+3. With maintainer npm authentication available, run `pnpm release` from the repository root. This runs the registry preflight, builds the publishable packages and invokes Changesets publication. Version application is already complete.
+4. Verify the published exports and a clean consumer installation.
+5. Deploy the site and verify the new guide, blog, diagrams and four LLM endpoints at their production URLs.

package/docs/execution.md

@@ -0,0 +1,97 @@
+# Execution daemon, browsers and sandboxes
+
+Foundry's control process owns agent definitions, instances, conversations, applications, policy and inspection. Agent jobs now execute through Station 3 in a **separate managed daemon process**. Foundry no longer constructs a `SignalRunner` in its control process.
+
+```text
+Foundry control process
+  definitions / instances / conversations / approvals / observability
+            │ private process transport
+            ▼
+Managed Station daemon
+  ├─ execution queue / schedules → agent job subprocesses
+  └─ optional resource adapters ← scoped mounts in agent jobs
+       ├─ browser provider (for example Steel)
+       └─ sandbox provider (for example Docker)
+```
+
+An application can host resources on this same Station or connect its mounts to external workers. Hosting resources is optional.
+
+Node 22+ is required by Station 3 (22.13+ for SQLite memory). Existing `glove foundry dev` and `start` commands start the managed execution daemon automatically. Its API uses ephemeral host credentials, and generated signal entrypoints live in a private temporary directory. Keys and backend configuration do not enter agent manifests. The independent Station dashboard is not embedded in Foundry; Foundry retains its inspector.
+
+The daemon owns job processes, queue access and recurring schedule execution. Foundry receives lifecycle/log events across the process boundary and retains its existing run IDs, cancellation, approvals, callbacks, sleep and schedule semantics. Agent identity is passed explicitly when loading definitions, so discovery of several agents does not race on environment variables.
+
+## Lifecycle and current boundary
+
+This implementation manages a local daemon per Foundry runtime. Stopping Foundry gracefully stops its daemon and agent jobs; losing the parent connection also shuts down the managed daemon. It does **not** yet attach agent jobs to an independently administered remote daemon or leave jobs running after the Foundry control process exits. Approvals and core callbacks still use private shared local files. Do not treat this as distributed control-plane failover.
+
+The execution queue remains in-memory, as before. Persist instances, conversations, activations and workspace state through the application adapters. Foundry reconstructs persisted activations on startup; it does not restore an interrupted live agent process. Browser/sandbox workers configured through adapters have independent persistence and ownership. Scope cleanup does not shut down those external daemons.
+
+Station 3 owns its idle polling backoff; Foundry's legacy `idlePollIntervalMs` option is retained for source compatibility but is not forwarded by Station's daemon API. `pollIntervalMs`, concurrency, attempts and retry backoff are forwarded.
+
+## One Station for jobs and resources
+
+Configure the managed daemon in `foundry.application.ts`. Resource providers are optional, application-owned adapters; they do not become agent definition fields or core dependencies.
+
+```ts
+import { defineApplication } from "glove-foundry";
+import { stationDaemon } from "glove-foundry/station";
+
+export default defineApplication({
+  name: "Assistant",
+  daemon: stationDaemon({
+    stationId: "assistant",
+    // Optional: omit port to allocate a free loopback port.
+    port: 4244,
+    resources: async () => ({
+      browser: await createBrowserManager(),
+      sandbox: await createSandboxAdapter(),
+    }),
+    onReady: connection => savePrivateConnection(connection),
+  }),
+});
+```
+
+The factory helpers and private connection storage above belong to the application. See [Operator's application](../../../examples/foundry-operator/foundry.application.ts) and [resource factory](../../../examples/foundry-operator/lib/resources.ts) for a complete Steel/Docker implementation.
+
+`glove foundry start` loads the application file inside the managed execution process, invokes the resource factory once, and starts **one** Station with agent jobs and resource endpoints. Agent runs continue using `mountBrowser` and `mountSandbox` with scoped adapters. Configuring providers on the daemon does not automatically grant agents access. Omit `daemon` to retain the jobs-only default, or supply either resource provider independently. Existing mounts can still connect to external workers.
+
+`onReady` receives `{ url, stationId, token }` after Station starts. The callback runs inside the daemon; use private storage or another application-owned channel when the host needs the connection. This is a trusted operator connection: Station 3 requires admin scope for its operator resource API. Keep it out of model context, manifests, observability and client-side code. Provider credentials stay in the resource adapters. The callback should overwrite stale connection state on each startup.
+
+Foundry stops Station and its resource adapters on shutdown, and cleans up on failed startup or a failed `onReady` callback. Resource factories must release partially acquired resources if they throw before returning. Mount cleanup retains its existing independent semantics; retaining a run scope does not promise a browser survives daemon shutdown. Persistent files and profiles depend on the chosen provider adapters.
+
+Programmatic `FoundryRuntime.discover` calls using a daemon adapter must supply `applicationFilePath`; closures are loaded in the child process, never serialized from the parent. Each Foundry runtime owns its Station instance. A fixed port must be unique per instance; omitting it avoids manual port allocation.
+
+## Optional capability mounts
+
+Browser and sandbox support is opt-in through `glove-execution`. Neither `glove-core` nor Foundry depends on that package. Use the same explicit mounting pattern as other Glove extensions, inside Foundry's existing `configure` hook:
+
+```ts
+import { defineAgent } from "glove-foundry";
+import { mountBrowser } from "glove-execution";
+import { stationBrowserClient } from "glove-execution/station";
+
+export default defineAgent({
+  model: () => createConfiguredModel(),
+  description: "Browser researcher",
+  configure(agent, context) {
+    const adapter = stationBrowserClient(
+      browserConnectionFor(context.agentId),
+      { maxSessions: 1, allowEvaluate: true },
+    );
+    let close = () => adapter.close();
+    context.onCleanup(() => close());
+    const browser = mountBrowser(agent, { adapter });
+    close = () => browser.close();
+  },
+});
+```
+
+The host supplies the model factory and credential-bearing connection resolver. `mountBrowser` attaches tools and a transient context provider that delivers native screenshots after tool results, without wrapping or replacing the agent’s model. Mounting creates a workflow scope; it does not automatically open a browser. Models get `execute_browser`, a persistent, bounded script surface for composing observation, actions, browser evaluation and verification in one model call. `mountSandbox` similarly installs `execute_sandbox`. Existing `repl` selection sees tools mounted during `configure`.
+
+The generic `context.onCleanup` hook registers teardown for any mounted capability. Callbacks run in reverse order on success, failure and cancellation, even if configuration fails. Keep returned mount handles in host code; browser/sandbox handles and fields are not part of Foundry's context or manifest. The portable mount entrypoint has no Node or Station imports; the separate Station adapter entrypoint owns backend integration.
+
+See [glove-execution](../../glove-execution/README.md) for worker connections, resource grants, retained sandbox ownership, scripting, page evaluation, mounting outside Foundry and custom adapters.
+
+## Station 2 consumers
+
+Station retired `station-kit`. Existing room examples now import `defineConfig` from `station-daemon`, start with `stationd`, and use Station 3 dependency ranges. Run the dashboard separately using `station-dashboard@3`, `STATION_DAEMON_URL` and a separate `PORT`. Existing API consumers continue to target the daemon port.

package/docs/release-verification.md

@@ -1,4 +1,6 @@
-# Foundry production integration — release handoff
+# Historical Foundry production integration — release handoff
+
+> This is the September 9 snapshot. See [the execution release handoff](./execution-release.md) for the current Station 3, browser/sandbox and shared-daemon candidate.
 
 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**.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glove-foundry",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An Effect-native, file-routed framework for typed, observable Glove agent applications",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,11 @@
       "types": "./dist/eslint.d.ts",
       "import": "./dist/eslint.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./station": {
+      "types": "./dist/station.d.ts",
+      "import": "./dist/station.js"
+    }
   },
   "files": [
     "dist",
@@ -54,25 +58,29 @@
     "agent-applications"
   ],
   "engines": {
-    "node": ">=20.12.0"
+    "node": ">=22"
   },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "effect": "^3.22.1",
-    "station-env": "^2.3.0",
-    "station-signal": "^2.3.0",
-    "station-schedules": "^2.3.0",
+    "station-env": "^3.0.0",
+    "station-signal": "^3.0.0",
+    "station-schedules": "^3.0.0",
     "tsx": "^4.21.0",
     "zod": "^4.3.6",
-    "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"
+    "station-daemon": "^3.0.0",
+    "station-client": "^3.0.0",
+    "station-beacon": "^3.0.0",
+    "station-broadcast": "^3.0.0",
+    "glove-core": "4.2.0",
+    "glove-facts": "0.1.3",
+    "glove-memory": "2.2.1",
+    "glove-lisp": "0.5.1",
+    "glove-js": "0.5.1",
+    "glove-mesh": "0.1.6",
+    "glove-python": "0.4.1",
+    "glove-working-environment": "0.7.0",
+    "glove-mcp": "1.2.1"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",

package/templates/minimal/README.md

@@ -4,7 +4,7 @@ A [Glove Foundry](https://github.com/porkytheblack/glove/tree/main/packages/glov
 
 ## First run
 
-Use Node.js 22.13+ (recommended; minimum 20.12). This minimal starter needs an
+Use Node.js 22.13+ (recommended; minimum 22). 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.

package/templates/travel-concierge/README.md

@@ -6,7 +6,7 @@ It runs before you configure anything — there is a built-in demo model, so you
 
 ## First run, step by step
 
-Use Node.js 22.13+ (recommended); the CLI requires Node 20.12 or newer. Open a
+Use Node.js 22.13+ (recommended); the CLI requires Node 22 or newer. Open a
 terminal in this project's directory. If the setup wizard already installed
 dependencies, you can skip the install command below.