glove-foundry 0.4.1 → 0.5.0

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.1",
+  "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-js": "0.5.0",
-    "glove-mcp": "1.2.0",
-    "glove-lisp": "0.5.0",
-    "glove-facts": "0.1.2",
-    "glove-memory": "2.2.0",
-    "glove-mesh": "0.1.5",
-    "glove-python": "0.4.0",
-    "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.