glove-foundry 0.4.0 → 0.5.0

package/dist/chunk-LW5PJ2FN.js

@@ -0,0 +1,546 @@
+import {
+  resolveResolvable
+} from "./chunk-5NFLGHOC.js";
+
+// src/guidance.ts
+import { createHash } from "node:crypto";
+import { FactPreparation, FactStore, useFacts } from "glove-facts";
+import { useGoalRunner, useFormRunner } from "glove-memory/tools";
+var defineFacts = (options) => Object.freeze({ ...options });
+var defineGoals = (options) => Object.freeze({ ...options });
+var defineForms = (options) => Object.freeze({ ...options });
+function foundryGuidanceSubject(context, scope = "conversation") {
+  return `foundry:${scope}:${createHash("sha256").update(JSON.stringify([
+    context.workspaceId,
+    context.agentId,
+    ...scope === "conversation" ? [context.conversationId] : []
+  ])).digest("hex")}`;
+}
+async function mountFoundryGuidance(glove, context, options) {
+  const { facts, goals, forms } = options;
+  const subject = (scope) => typeof scope === "object" ? scope.subject : foundryGuidanceSubject(context, scope);
+  const handles = {};
+  let preparer;
+  if (facts) {
+    handles.facts = new FactStore(facts.adapter, {
+      scope: typeof facts.scope === "object" ? facts.scope : { subject: subject(facts.scope), context: "conversation-evidence" },
+      maxRevisions: facts.maxRevisions,
+      onUrgent: facts.onUrgent
+    });
+    if (facts.preparationAgent) {
+      if (facts.preparationAgent === glove) throw new Error("Fact preparation requires a dedicated agent.");
+      preparer = new FactPreparation(handles.facts, { agent: facts.preparationAgent });
+    }
+    useFacts(glove, handles.facts, facts.source ?? (() => ({
+      source: { kind: "message", id: context.message.id ?? context.runId },
+      operationId: context.message.id ?? context.runId
+    })));
+  }
+  if ((goals?.preparation || forms?.preparation) && !preparer) {
+    throw new Error("Guidance preparation requires facts with a dedicated preparationAgent.");
+  }
+  if (goals) {
+    const scope = typeof goals.scope === "object" ? goals.scope : {
+      subject: subject(goals.scope),
+      key: goals.program?.key ?? "conversation"
+    };
+    if (goals.preparation && preparer.facts.scope().subject !== scope.subject) throw new Error("Goals and facts must share the same subject.");
+    handles.goals = useGoalRunner(glove, goals.adapter, {
+      ...goals,
+      scope,
+      preparation: goals.preparation ? { ...goals.preparation, preparer } : void 0
+    }).runner;
+    if (goals.program) await handles.goals.start(goals.program, "Initialize definition-provided goals; preserve existing progress.");
+  }
+  if (forms) {
+    if (forms.preparation && preparer.facts.scope().subject !== subject(forms.scope)) throw new Error("Forms and facts must share the same subject.");
+    handles.forms = useFormRunner(glove, forms.adapter, {
+      ...forms,
+      subject: subject(forms.scope),
+      preparation: forms.preparation ? { ...forms.preparation, preparer } : void 0
+    }).runner;
+  }
+  let previous = "";
+  const snapshot = async () => {
+    if (!facts && !goals && !forms && options.contextProviders.length === 0) return;
+    const goalState = await handles.goals?.status();
+    const factState = await handles.facts?.inspect();
+    const formState = forms ? await forms.adapter.findInstances({ subject: subject(forms.scope) }) : void 0;
+    const state = {
+      goals: goalState ? {
+        version: goalState.version,
+        status: goalState.status,
+        activeGoal: goalState.activeGoal,
+        items: goalState.goals.map((g) => ({
+          key: g.definition.key,
+          title: g.definition.title,
+          status: g.status,
+          completed: g.items.filter((i) => i.state?.done).length,
+          total: g.items.length
+        }))
+      } : null,
+      facts: factState ? {
+        version: factState.version,
+        revisions: factState.facts.length,
+        claims: factState.claims.length,
+        urgent: factState.facts.filter((f) => f.urgent).length
+      } : null,
+      forms: formState?.map((f) => ({
+        id: f.id,
+        definitionId: f.defId,
+        version: f.version,
+        status: f.status,
+        answered: Object.values(f.entries).filter((e) => e.cursor >= 0).length,
+        pendingHooks: Object.keys(f.pendingHooks ?? {}).length,
+        blockedOn: f.blockedOn ?? null
+      })) ?? null,
+      contextProviders: options.contextProviders.length
+    };
+    const encoded = JSON.stringify(state);
+    if (encoded !== previous) {
+      context.controls.emit({ type: "foundry.guidance.state", data: state });
+      previous = encoded;
+    }
+  };
+  const cleanups = [];
+  try {
+    for (const provider of options.contextProviders) cleanups.push(glove.addContextProvider(provider));
+    if (facts || goals || forms) {
+      await snapshot();
+      cleanups.push(glove.addContextProvider(async () => {
+        await snapshot();
+        return null;
+      }));
+    }
+    return { handles, snapshot, dispose: () => {
+      for (const remove of cleanups.reverse()) remove();
+    } };
+  } catch (error) {
+    for (const remove of cleanups.reverse()) remove();
+    throw error;
+  }
+}
+
+// src/workbench.ts
+import { Effect } from "effect";
+import {
+  getToolJsonSchema
+} from "glove-core";
+import {
+  JsSession,
+  mountJs
+} from "glove-js";
+import {
+  LispSession,
+  mountLisp
+} from "glove-lisp";
+import {
+  PySession,
+  mountPy
+} from "glove-python";
+import {
+  createWorkingEnvironment,
+  fromSnapshot,
+  mountWorkingEnvironment
+} from "glove-working-environment";
+var FOUNDRY_WORKING_ENVIRONMENT_BRAND = /* @__PURE__ */ Symbol.for(
+  "glove-foundry-working-environment"
+);
+var FOUNDRY_REPL_BRAND = /* @__PURE__ */ Symbol.for("glove-foundry-repl");
+function defineWorkingEnvironment(options = {}) {
+  if (options.create && options.options) {
+    throw new Error(
+      "defineWorkingEnvironment accepts either create or options, not both."
+    );
+  }
+  return Object.freeze({
+    ...options,
+    [FOUNDRY_WORKING_ENVIRONMENT_BRAND]: true
+  });
+}
+function assertSnapshot(value) {
+  if (!value || typeof value !== "object") {
+    throw new Error("Stored working-environment snapshot must be an object.");
+  }
+  const snapshot = value;
+  if (snapshot.version !== 1 || !Array.isArray(snapshot.dirs) || !snapshot.dirs.every((path) => typeof path === "string") || !Array.isArray(snapshot.files) || !snapshot.files.every(
+    (file) => Boolean(
+      file && typeof file === "object" && typeof file.path === "string" && typeof file.data === "string" && typeof file.mtime === "number"
+    )
+  )) {
+    throw new Error("Stored working-environment snapshot is invalid or unsupported.");
+  }
+  return structuredClone(snapshot);
+}
+function environmentSnapshotOwner(scope, context) {
+  return {
+    scope,
+    definitionId: context.definitionId,
+    agentId: context.agentId,
+    conversationId: context.conversationId,
+    workspaceId: context.workspaceId
+  };
+}
+function foundryDataEnvironmentPersistence(options = {}) {
+  const scope = options.scope ?? "agent";
+  const adapter = {
+    identifier: `foundry-data:${scope}`,
+    load(context) {
+      return Effect.map(
+        context.data.getWorkingEnvironmentSnapshot(
+          environmentSnapshotOwner(scope, context)
+        ),
+        (snapshot) => snapshot ? assertSnapshot(snapshot) : null
+      );
+    },
+    save(snapshot, context) {
+      return context.data.putWorkingEnvironmentSnapshot(
+        environmentSnapshotOwner(scope, context),
+        structuredClone(snapshot)
+      );
+    }
+  };
+  return Object.freeze(adapter);
+}
+function defineRepl(options) {
+  const valid = options.language === "javascript" && options.session instanceof JsSession || options.language === "python" && options.session instanceof PySession || options.language === "lisp" && options.session instanceof LispSession;
+  if (!valid) {
+    throw new Error(
+      `Foundry ${options.language} REPL requires the matching native Glove session.`
+    );
+  }
+  return Object.freeze({
+    ...options,
+    [FOUNDRY_REPL_BRAND]: true
+  });
+}
+function isProgrammaticSelection(value) {
+  return typeof value === "object" && value !== null && "tool" in value;
+}
+function parseProgrammaticToolData(data) {
+  if (typeof data !== "string") return data;
+  const text = data.trim();
+  if (!text.startsWith("{") && !text.startsWith("[")) return data;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return data;
+  }
+}
+async function runProgrammaticTool(tool, input, signal) {
+  if (tool.unAbortable || !signal) return tool.run(input, void 0, signal);
+  if (signal.aborted) throw signal.reason ?? new DOMException("Aborted", "AbortError");
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    signal.addEventListener("abort", abort, { once: true });
+    tool.run(input, void 0, signal).then(
+      (value) => {
+        signal.removeEventListener("abort", abort);
+        resolve(value);
+      },
+      (cause) => {
+        signal.removeEventListener("abort", abort);
+        reject(cause);
+      }
+    );
+  });
+}
+function programmaticToolFunction(selection, options) {
+  const decorated = isProgrammaticSelection(selection) ? selection : { tool: selection };
+  const tool = decorated.tool;
+  if (!options.available.has(tool)) {
+    throw new Error(
+      `Programmatic tool "${tool.name}" is not an exact reference from the assembled agent tool registry.`
+    );
+  }
+  const name = decorated.name ?? tool.name;
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(
+      `Programmatic tool name "${name}" is not a valid JavaScript/Python/Lisp identifier; provide a valid name override.`
+    );
+  }
+  return {
+    name,
+    description: tool.description,
+    inputSchema: getToolJsonSchema(tool),
+    ...decorated.readOnly !== void 0 ? { readOnlyHint: decorated.readOnly } : {},
+    ...decorated.server !== void 0 ? { server: decorated.server } : {},
+    ...decorated.serverDescription !== void 0 ? { serverDescription: decorated.serverDescription } : {},
+    ...decorated.resultShape !== void 0 ? { resultShape: decorated.resultShape } : {},
+    async call(input, fnContext = {}) {
+      if (options.budget.used >= options.budget.max) {
+        options.context.controls.emit({
+          type: "foundry.repl.programmatic-tool.limit",
+          data: { tool: tool.name, function: name, maxCalls: options.budget.max }
+        });
+        throw new Error(
+          `Programmatic tool-call limit (${options.budget.max}) reached for this run. Return the result already computed or continue in a new run.`
+        );
+      }
+      options.budget.used += 1;
+      const parsed = tool.input_schema?.safeParse(input);
+      if (parsed && !parsed.success) {
+        throw new Error(
+          parsed.error.issues.slice(0, 3).map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ")
+        );
+      }
+      const validated = parsed?.success ? parsed.data : input;
+      const permission = typeof tool.requiresPermission === "function" ? tool.requiresPermission(validated) : Boolean(tool.requiresPermission);
+      if (permission) {
+        options.context.controls.emit({
+          type: "foundry.repl.programmatic-tool.denied",
+          data: { tool: tool.name, function: name, reason: "interactive-approval-required" }
+        });
+        throw new Error(
+          `Tool "${tool.name}" requires interactive approval and cannot run inside a programmatic workflow. Call it directly so the approval can be shown.`
+        );
+      }
+      const started = Date.now();
+      options.context.controls.emit({
+        type: "foundry.repl.programmatic-tool.started",
+        data: { tool: tool.name, function: name, call: options.budget.used }
+      });
+      try {
+        const result = await runProgrammaticTool(tool, validated, fnContext.signal);
+        if (result.status !== "success") {
+          throw new Error(result.message ?? `Tool "${tool.name}" failed.`);
+        }
+        options.context.controls.emit({
+          type: "foundry.repl.programmatic-tool.completed",
+          data: { tool: tool.name, function: name, durationMs: Date.now() - started }
+        });
+        return parseProgrammaticToolData(result.data);
+      } catch (cause) {
+        options.context.controls.emit({
+          type: "foundry.repl.programmatic-tool.failed",
+          data: {
+            tool: tool.name,
+            function: name,
+            durationMs: Date.now() - started,
+            outcome: "error"
+          }
+        });
+        throw cause;
+      }
+    }
+  };
+}
+async function registerProgrammaticTools(options) {
+  const config = options.repl.programmaticTools;
+  if (!config) return 0;
+  const max = config.maxCalls ?? 50;
+  if (!Number.isInteger(max) || max < 1 || max > 1e3) {
+    throw new Error("Foundry programmaticTools.maxCalls must be an integer from 1 to 1000.");
+  }
+  const tools = Object.freeze([...options.glove.tools]);
+  const selected = await resolveResolvable(config.select({
+    assembly: options.context,
+    glove: options.glove,
+    tools,
+    ...options.workingEnvironment ? { workingEnvironment: options.workingEnvironment } : {},
+    ...options.vfs ? { vfs: options.vfs } : {}
+  }));
+  const available = new Set(tools);
+  const budget = { used: 0, max };
+  const functions = selected.map(
+    (selection) => programmaticToolFunction(selection, { available, budget, context: options.context })
+  );
+  const names = /* @__PURE__ */ new Set();
+  for (const fn of functions) {
+    if (names.has(fn.name)) throw new Error(`Duplicate programmatic function name "${fn.name}".`);
+    names.add(fn.name);
+  }
+  switch (options.repl.language) {
+    case "javascript":
+    case "python":
+      options.repl.session.registerAll(functions);
+      break;
+    case "lisp":
+      options.repl.session.registerFns(functions);
+      break;
+  }
+  return functions.length;
+}
+function persistenceContext(context) {
+  return {
+    definitionId: context.definitionId,
+    agentId: context.agentId,
+    conversationId: context.conversationId,
+    workspaceId: context.workspaceId,
+    runId: context.runId,
+    data: context.data,
+    signal: context.controls.signal
+  };
+}
+async function createEnvironment(definition, context) {
+  if (definition[FOUNDRY_WORKING_ENVIRONMENT_BRAND] !== true) {
+    throw new Error(
+      "Agent workingEnvironment must be created with defineWorkingEnvironment(...)."
+    );
+  }
+  const persistence = persistenceContext(context);
+  const snapshot = definition.persistence ? await resolveResolvable(definition.persistence.load(persistence)) : null;
+  const createContext = {
+    assembly: context,
+    snapshot
+  };
+  if (definition.create) {
+    return {
+      environment: await resolveResolvable(definition.create(createContext)),
+      persistence
+    };
+  }
+  const resolvedOptions = typeof definition.options === "function" ? await resolveResolvable(definition.options(createContext)) : definition.options ?? {};
+  return {
+    environment: await createWorkingEnvironment({
+      ...resolvedOptions,
+      ...snapshot && resolvedOptions.filesystem === void 0 ? { filesystem: fromSnapshot(snapshot) } : {}
+    }),
+    persistence
+  };
+}
+async function mountFoundryWorkbench(options) {
+  let environment;
+  let persistence;
+  let mountedRepl;
+  let replMountPromise;
+  const dispose = async () => {
+    if (!environment || !options.workingEnvironment) return;
+    const failures = [];
+    if (options.workingEnvironment.persistence && persistence) {
+      try {
+        const snapshot = await environment.snapshot();
+        await resolveResolvable(
+          options.workingEnvironment.persistence.save(snapshot, persistence)
+        );
+        options.context.controls.emit({
+          type: "foundry.working-environment.snapshot.saved",
+          data: {
+            persistence: options.workingEnvironment.persistence.identifier,
+            files: snapshot.files.length
+          }
+        });
+      } catch (cause) {
+        failures.push(cause);
+      }
+    }
+    if (options.workingEnvironment.close !== false) {
+      try {
+        await environment.close();
+      } catch (cause) {
+        failures.push(cause);
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures,
+        "Foundry working-environment cleanup failed."
+      );
+    }
+  };
+  const mountRepl = () => {
+    const repl = options.repl;
+    if (!repl) return Promise.resolve();
+    if (replMountPromise) return replMountPromise;
+    replMountPromise = (async () => {
+      if (repl[FOUNDRY_REPL_BRAND] !== true) {
+        throw new Error("Agent repl must be created with defineRepl(...).");
+      }
+      const programmaticTools = await registerProgrammaticTools({
+        repl,
+        glove: options.glove,
+        context: options.context,
+        ...environment ? { workingEnvironment: environment, vfs: environment.fs } : {}
+      });
+      switch (repl.language) {
+        case "javascript":
+          mountJs(options.glove, {
+            session: repl.session,
+            ...repl.mount ?? {},
+            exclusive: false
+          });
+          break;
+        case "python":
+          mountPy(options.glove, {
+            session: repl.session,
+            ...repl.mount ?? {},
+            exclusive: false
+          });
+          break;
+        case "lisp":
+          mountLisp(options.glove, {
+            session: repl.session,
+            ...repl.mount ?? {},
+            exclusive: false
+          });
+          break;
+      }
+      options.context.controls.emit({
+        type: "foundry.repl.mounted",
+        data: {
+          language: repl.language,
+          frame: repl.mount?.frame ?? "repl",
+          programmaticTools
+        }
+      });
+    })();
+    return replMountPromise;
+  };
+  try {
+    if (options.workingEnvironment) {
+      const created = await createEnvironment(
+        options.workingEnvironment,
+        options.context
+      );
+      environment = created.environment;
+      persistence = created.persistence;
+      mountWorkingEnvironment(options.glove, {
+        env: environment,
+        ...options.workingEnvironment.mount ?? {}
+      });
+      options.context.controls.emit({
+        type: "foundry.working-environment.mounted",
+        data: {
+          tools: environment.tools.map((tool) => tool.name),
+          modules: [...environment.moduleDescriptions.keys()],
+          warnings: environment.warnings,
+          persistence: options.workingEnvironment.persistence?.identifier ?? null
+        }
+      });
+    }
+    if (options.repl) {
+      mountedRepl = options.repl.language === "javascript" ? Object.freeze({ language: "javascript", session: options.repl.session }) : options.repl.language === "python" ? Object.freeze({ language: "python", session: options.repl.session }) : Object.freeze({ language: "lisp", session: options.repl.session });
+      if (!options.deferRepl) await mountRepl();
+    }
+    return {
+      ...environment ? { workingEnvironment: environment, vfs: environment.fs } : {},
+      ...mountedRepl ? { repl: mountedRepl } : {},
+      mountRepl,
+      dispose
+    };
+  } catch (cause) {
+    try {
+      await dispose();
+    } catch (cleanupCause) {
+      throw new AggregateError(
+        [cause, cleanupCause],
+        "Foundry workbench mounting and cleanup failed."
+      );
+    }
+    throw cause;
+  }
+}
+
+export {
+  defineFacts,
+  defineGoals,
+  defineForms,
+  foundryGuidanceSubject,
+  mountFoundryGuidance,
+  FOUNDRY_WORKING_ENVIRONMENT_BRAND,
+  FOUNDRY_REPL_BRAND,
+  defineWorkingEnvironment,
+  foundryDataEnvironmentPersistence,
+  defineRepl,
+  mountFoundryWorkbench
+};