glove-foundry 0.4.0 → 0.5.0

package/README.md

@@ -19,7 +19,7 @@ for it to finish before showing next steps. In non-interactive commands, add
 `--install` to install automatically; use `--no-install` to defer it explicitly.
 
 Use Node.js 22.13+ (recommended, including SQLite memory support); the CLI requires
-at least Node 20.12. Run this in a terminal:
+at least Node 22. Run this in a terminal:
 
 ```bash
 npx glove-foundry init
@@ -409,3 +409,19 @@ POST /v1/chat/completions
 The `/v1/chat/completions` endpoint accepts an agent instance id as `model`, supports SSE streaming, and returns `x-foundry-conversation-id`. Reuse `user`, `conversation_id`, or that header to continue the same durable Foundry conversation from an OpenAI-compatible client.
 
 See [Building with Foundry](./docs/building-with-foundry.md), [Architecture](./docs/architecture.md), the compact [`examples/foundry-agent`](../../examples/foundry-agent), and the [Braind Storm workforce](../../examples/foundry-braind-storm).
+
+## Browser, sandbox and daemon execution
+
+Foundry runs agent jobs in a separate managed Station 3 daemon. Applications can
+opt into `glove-execution` and call `mountBrowser` / `mountSandbox` in `configure`,
+using the same mount approach as other capabilities. Browser workflows run as
+scripts through `execute_browser`, with native screenshot observations. See the
+[execution guide](docs/execution.md) for setup, ownership and lifecycle limits.
+
+The [Operator example](../../examples/foundry-operator) combines these mounts into a general-purpose browser and coding agent with a local console, persistent sign-in, container services and a documented live verification.
+
+### Optional resources on the managed Station
+
+Use `daemon: stationDaemon({ stationId, resources, onReady })` in your application definition (`stationDaemon` is exported from `glove-foundry/station`). Foundry then runs agent jobs and the application-supplied browser/sandbox adapters on one managed Station. Resource factories run once inside the daemon; agents still receive capabilities through explicit mounts. Omit this option for jobs only. See [setup, ownership and private connections](./docs/execution.md#one-station-for-jobs-and-resources).
+
+See the [execution release handoff](./docs/execution-release.md) for verification, operational limits and publication steps.

package/dist/chunk-5NFLGHOC.js

@@ -0,0 +1,281 @@
+// src/definition.ts
+import { Displaymanager, Glove } from "glove-core";
+import { Effect } from "effect";
+
+// src/identity.ts
+var identities = /* @__PURE__ */ new WeakMap();
+function fileIdentified(value, kind, explicitId) {
+  const cell = {
+    kind,
+    ...explicitId ? { id: explicitId } : {},
+    explicit: explicitId !== void 0
+  };
+  const identified = { ...value };
+  Object.defineProperty(identified, "id", {
+    enumerable: true,
+    configurable: false,
+    get() {
+      if (cell.id) return cell.id;
+      throw new Error(
+        `Foundry ${kind} identity has not been bound yet. Default-export it from its convention file and let Foundry discovery derive the id.`
+      );
+    }
+  });
+  identities.set(identified, cell);
+  return identified;
+}
+function bindFileIdentity(value, id, expectedKind) {
+  const cell = identities.get(value);
+  if (!cell) {
+    const current = value.id;
+    if (typeof current === "string" && current !== id) {
+      throw new Error(`Foundry file route resolves to "${id}" but the definition declares "${current}".`);
+    }
+    return;
+  }
+  if (expectedKind && cell.kind !== expectedKind) {
+    throw new Error(
+      `Foundry ${expectedKind} route "${id}" received a ${cell.kind} definition.`
+    );
+  }
+  if (cell.id && cell.id !== id) {
+    throw new Error(
+      `Foundry ${cell.kind} route resolves to "${id}" but the definition declares "${cell.id}". Remove the explicit id and let the file own identity.`
+    );
+  }
+  cell.id = id;
+}
+function fileDefinitionKey(value) {
+  const cell = identities.get(value);
+  return cell ?? value;
+}
+function fileDefinitionLabel(value) {
+  const cell = identities.get(value);
+  return cell?.id ?? `<${cell?.kind ?? "definition"} file route>`;
+}
+
+// src/definition.ts
+var FOUNDRY_AGENT_DEFINITION_BRAND = /* @__PURE__ */ Symbol.for(
+  "glove-foundry-agent-definition"
+);
+var FOUNDRY_AGENT_BRAND = FOUNDRY_AGENT_DEFINITION_BRAND;
+var FOUNDRY_EVENT_PREFIX = "__GLOVE_FOUNDRY_EVENT__";
+var FOUNDRY_APPLICATION_ENV = "GLOVE_FOUNDRY_APPLICATION_FILE";
+var FOUNDRY_AGENT_ROUTE_ENV = "GLOVE_FOUNDRY_AGENT_ROUTE";
+var FOUNDRY_AGENT_FILE_ENV = "GLOVE_FOUNDRY_AGENT_FILE";
+var FOUNDRY_EXECUTION_MARKER = "__glove_foundry_execution_v1";
+function defineCall(options) {
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(options.name)) {
+    throw new Error(`Invalid Foundry call name "${options.name}".`);
+  }
+  return Object.freeze({ ...options });
+}
+var ROUTE_PATTERN = /^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)*$/;
+function assertAgentRoute(route) {
+  if (!ROUTE_PATTERN.test(route)) {
+    throw new Error(
+      `Invalid Foundry agent id "${route}". Use lowercase path segments containing letters, digits, and hyphens.`
+    );
+  }
+  if (route.includes("__")) {
+    throw new Error(`Invalid Foundry agent id "${route}": "__" is reserved.`);
+  }
+}
+function internalAgentName(route) {
+  assertAgentRoute(route);
+  return `foundry_${route.replaceAll("/", "__").replaceAll("-", "_")}`;
+}
+function routeFromInternalAgentName(name) {
+  if (!name.startsWith("foundry_")) return name;
+  return name.slice("foundry_".length).replaceAll("__", "/").replaceAll("_", "-");
+}
+function isFoundryAgentDefinition(value) {
+  return Boolean(
+    value && typeof value === "object" && value[FOUNDRY_AGENT_DEFINITION_BRAND] === true
+  );
+}
+var isFoundryAgent = isFoundryAgentDefinition;
+function validateDefinition(options, route) {
+  const id = route ?? options.id;
+  if (id) assertAgentRoute(id);
+  if (!options.model && !options.run && !options.handler && !options.spawn) {
+    throw new Error(`Foundry agent "${id ?? "<file route>"}" must define model, run, handler, or spawn.`);
+  }
+  if (options.model && options.systemPrompt === void 0) {
+    throw new Error(`Foundry agent "${id ?? "<file route>"}" must define systemPrompt when it defines a model.`);
+  }
+  if (options.inboxes !== void 0 && typeof options.inboxes !== "function") {
+    throw new Error(
+      `Foundry agent "${id ?? "<file route>"}" inboxes must be a lazy resolver function.`
+    );
+  }
+  const forbidden = ["input", "output"];
+  for (const key of forbidden) {
+    if (key in options) {
+      throw new Error(`Foundry agent "${id ?? "<file route>"}" cannot define ${key}; invocation contracts are framework-owned.`);
+    }
+  }
+}
+function defineAgent(options) {
+  validateDefinition(options);
+  const { id, ...definition } = options;
+  return Object.freeze(fileIdentified({
+    ...definition,
+    tags: Object.freeze([...options.tags ?? []]),
+    [FOUNDRY_AGENT_DEFINITION_BRAND]: true
+  }, "agent", id));
+}
+var CONVENTION_EXPORTS = [
+  "id",
+  "description",
+  "tags",
+  "components",
+  "mcpAdapter",
+  "accountSessions",
+  "store",
+  "model",
+  "systemPrompt",
+  "displayManager",
+  "serverMode",
+  "maxRetries",
+  "maxConsecutiveErrors",
+  "compactionLimit",
+  "compactionInstructions",
+  "maxTurns",
+  "enableToolResultSummary",
+  "tools",
+  "hooks",
+  "skills",
+  "subagents",
+  "memory",
+  "goals",
+  "facts",
+  "forms",
+  "contextProviders",
+  "inboxes",
+  "subscribers",
+  "layers",
+  "calls",
+  "schedules",
+  "playbooks",
+  "mesh",
+  "workingEnvironment",
+  "repl",
+  "configure",
+  "build",
+  "spawn",
+  "run",
+  "handler"
+];
+function defineAgentFromModule(route, module) {
+  assertAgentRoute(route);
+  if (isFoundryAgentDefinition(module.default)) {
+    const definition2 = module.default;
+    bindFileIdentity(definition2, route, "agent");
+    validateDefinition(definition2, route);
+    return definition2;
+  }
+  if (!module.description) {
+    throw new Error(`Foundry route "${route}" must default-export defineAgent(...) or export description.`);
+  }
+  const options = {};
+  for (const key of CONVENTION_EXPORTS) {
+    if (module[key] !== void 0) options[key] = module[key];
+  }
+  const definition = defineAgent(options);
+  bindFileIdentity(definition, route, "agent");
+  return definition;
+}
+function defineSubagent(options) {
+  if (!/^[A-Za-z][\w-]*$/.test(options.name)) throw new Error(`Invalid Foundry subagent name "${options.name}".`);
+  return Object.freeze({
+    name: options.name,
+    description: options.description,
+    factory: async ({ parentStore, parentControls, prompt }) => {
+      const store = await parentStore.createSubAgentStore?.(options.name, options.durable ?? false) ?? void 0;
+      const tools = typeof options.tools === "function" ? await resolveResolvable(options.tools({
+        name: options.name,
+        prompt,
+        parent: parentControls.glove
+      })) : options.tools ?? [];
+      const glove = new Glove({
+        ...store ? { store } : {},
+        model: options.model ?? parentControls.glove.model,
+        displayManager: parentControls.displayManager ?? new Displaymanager(),
+        systemPrompt: options.systemPrompt,
+        serverMode: options.serverMode ?? parentControls.glove.serverMode,
+        ...options.maxRetries !== void 0 ? { maxRetries: options.maxRetries } : {},
+        ...options.maxConsecutiveErrors !== void 0 ? { maxConsecutiveErrors: options.maxConsecutiveErrors } : {},
+        compaction_config: {
+          compaction_instructions: options.compactionInstructions ?? `Preserve the ${options.name} subagent's findings and unresolved work.`,
+          ...options.maxTurns !== void 0 ? { max_turns: options.maxTurns } : {},
+          ...options.compactionLimit !== void 0 ? { compaction_context_limit: options.compactionLimit } : {}
+        },
+        ...options.enableToolResultSummary !== void 0 ? { enableToolResultSummary: options.enableToolResultSummary } : {}
+      }).build();
+      for (const tool of tools) glove.fold(tool);
+      for (const hook of options.hooks ?? []) glove.defineHook(hook.name, hook.handler);
+      for (const skill of options.skills ?? []) glove.defineSkill(skill);
+      for (const subagent of options.subagents ?? []) glove.defineSubAgent(subagent);
+      if (options.configure) {
+        const message = { sender: "user", text: prompt };
+        const request = {
+          agentId: options.name,
+          conversationId: `subagent:${options.name}`,
+          workspaceId: "subagent",
+          message: prompt,
+          source: { kind: "spawn" }
+        };
+        await resolveResolvable(options.configure({
+          definitionId: options.name,
+          agentId: options.name,
+          conversationId: request.conversationId,
+          workspaceId: request.workspaceId,
+          runId: `subagent:${options.name}`,
+          input: prompt,
+          request,
+          message,
+          messageInput: prompt,
+          messageText: prompt,
+          history: [],
+          messages: [message],
+          glove,
+          signal: new AbortController().signal,
+          emit: () => void 0
+        }));
+      }
+      return glove;
+    }
+  });
+}
+async function resolveResolvable(value) {
+  if (Effect.isEffect(value)) return Effect.runPromise(value);
+  return Promise.resolve(value);
+}
+function defineRoutes(routes) {
+  return Object.freeze({ ...routes });
+}
+
+export {
+  fileIdentified,
+  bindFileIdentity,
+  fileDefinitionKey,
+  fileDefinitionLabel,
+  FOUNDRY_AGENT_DEFINITION_BRAND,
+  FOUNDRY_AGENT_BRAND,
+  FOUNDRY_EVENT_PREFIX,
+  FOUNDRY_APPLICATION_ENV,
+  FOUNDRY_AGENT_ROUTE_ENV,
+  FOUNDRY_AGENT_FILE_ENV,
+  FOUNDRY_EXECUTION_MARKER,
+  defineCall,
+  internalAgentName,
+  routeFromInternalAgentName,
+  isFoundryAgentDefinition,
+  isFoundryAgent,
+  defineAgent,
+  defineAgentFromModule,
+  defineSubagent,
+  resolveResolvable,
+  defineRoutes
+};

package/dist/chunk-J7ZBJM54.js

@@ -0,0 +1,6 @@
+// src/execution-protocol.ts
+var executionEvents = ["onSignalDiscovered", "onRunDispatched", "onRunStarted", "onRunCompleted", "onRunTimeout", "onRunRetry", "onRunFailed", "onRunCancelled", "onRunSkipped", "onRunRescheduled", "onCompleteError", "onLogOutput"];
+
+export {
+  executionEvents
+};