Persistence

import { resolve } from "node:path";

/** Use an absolute path on a persistent volume in production. */
export const dataDir = resolve(process.env.FOUNDRY_DATA_DIR ?? ".data");

import { createHash, randomUUID } from "node:crypto";
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
import { join } from "node:path";
import {
  MemoryStore,
  type InboxItem,
  type Message,
  type Task,
  type TokenConsumptionCounter,
} from "glove-core";

interface SavedConversation {
  readonly version: 1;
  readonly messages: Message[];
  readonly turns: number;
  readonly consumption: TokenConsumptionCounter;
  readonly tasks: Task[];
  readonly inbox: InboxItem[];
}

/**
 * One JSON file per conversation, rewritten atomically after every change.
 * Single host, one active run per conversation. Use a database-backed
 * StoreAdapter when several hosts or concurrent writers share transcripts.
 */
export class FileConversationStore extends MemoryStore {
  private constructor(identifier: string, private readonly file: string) {
    super(identifier);
  }

  static async open(directory: string, conversationId: string) {
    const name = createHash("sha256").update(conversationId).digest("hex");
    const store = new FileConversationStore(conversationId, join(directory, `${name}.json`));
    await store.restore();
    return store;
  }

  private async restore(): Promise<void> {
    let saved: SavedConversation;
    try {
      saved = JSON.parse(await readFile(this.file, "utf8")) as SavedConversation;
    } catch (cause) {
      if ((cause as NodeJS.ErrnoException).code === "ENOENT") return;
      throw cause;
    }
    await super.appendMessages(saved.messages);
    await super.addTokens(saved.consumption);
    for (let turn = 0; turn < saved.turns; turn++) await super.incrementTurn();
    await super.addTasks(saved.tasks);
    for (const item of saved.inbox) await super.addInboxItem(item);
  }

  private async save(): Promise<void> {
    const saved: SavedConversation = {
      version: 1,
      messages: await this.getMessages(),
      turns: await this.getTurnCount(),
      consumption: await this.getTokenConsumption(),
      tasks: await this.getTasks(),
      inbox: await this.getInboxItems(),
    };
    const directory = join(this.file, "..");
    await mkdir(directory, { recursive: true });
    const temporary = `${this.file}.${randomUUID()}.tmp`;
    await writeFile(temporary, JSON.stringify(saved), { mode: 0o600 });
    await rename(temporary, this.file);
  }

  override async appendMessages(messages: Message[]) { await super.appendMessages(messages); await this.save(); }
  override async addTokens(usage: TokenConsumptionCounter) { await super.addTokens(usage); await this.save(); }
  override async incrementTurn() { await super.incrementTurn(); await this.save(); }
  override async resetCounters() { await super.resetCounters(); await this.save(); }
  override async addTasks(tasks: Task[]) { await super.addTasks(tasks); await this.save(); }
  override async updateTask(id: string, updates: Partial<Pick<Task, "status" | "content" | "activeForm">>) { await super.updateTask(id, updates); await this.save(); }
  override async addInboxItem(item: InboxItem) { await super.addInboxItem(item); await this.save(); }
  override async updateInboxItem(id: string, updates: Partial<Pick<InboxItem, "status" | "response" | "resolved_at">>) { await super.updateInboxItem(id, updates); await this.save(); }
}

import { join } from "node:path";
import { FileFoundryDataAdapter, defineApplication } from "glove-foundry";
import { FileConversationStore } from "./lib/conversation-store.js";
import { dataDir } from "./lib/data-dir.js";

export default defineApplication({
  name: "Support",
  // (1) Foundry runtime data: instances, conversations, schedules, workspace, VFS snapshots…
  data: new FileFoundryDataAdapter({ file: join(dataDir, "foundry.json") }),
  // (2) Glove transcripts for every agent that does not define its own `store`.
  conversationStore: ({ conversationId }) =>
    FileConversationStore.open(join(dataDir, "transcripts"), conversationId),
});

import { join } from "node:path";
import { Effect } from "effect";
import { defineMemory, foundryGuidanceSubject, type AgentDefinitionSurfaceContext } from "glove-foundry";
import { MemorySchema } from "glove-memory/core";
import { createSqliteMemoryAdapters } from "glove-memory/sqlite";
import { dataDir } from "../../../lib/data-dir.js";

const schema = new MemorySchema().defineEpisodeKind({
  name: "interaction",
  description: "A customer request or decision, with its source and date.",
});

// Namespace from trusted instance identity, never from model or user input.
const memoryFor = (context: AgentDefinitionSurfaceContext) =>
  createSqliteMemoryAdapters({
    file: join(dataDir, "memory.sqlite"),
    namespace: foundryGuidanceSubject(context, "instance"),
    schema,
  });

// (3) Structured memory, shared by every conversation of one instance.
export default defineMemory({
  description: "What we know about this customer across conversations",
  context: { adapter: (context) => Effect.sync(() => memoryFor(context).context) },
  episodic: {
    access: "curator",
    adapter: (context) => Effect.sync(() => memoryFor(context).episodic),
  },
});

import { createAdapter } from "glove-core/models/providers";
import {
  composeAgent,
  defineAgent,
  defineWorkingEnvironment,
  foundryDataEnvironmentPersistence,
} from "glove-foundry";
import { claimTicket } from "./claim-ticket.js";
import customerMemory from "./memory/customer.memory.js";

// (4) Restored before every run and saved after it, one VFS per conversation.
const caseFiles = defineWorkingEnvironment({
  options: { limits: { maxVfsBytes: 8 * 1024 * 1024 } },
  persistence: foundryDataEnvironmentPersistence({ scope: "conversation" }),
});

export default defineAgent({
  description: "Answers customer questions and keeps case notes",
  // (3) A memory profile must be in the catalogue AND selected in `memory`.
  components: composeAgent(customerMemory),
  memory: [customerMemory],
  workingEnvironment: caseFiles,
  tools: (_agent, ctx) => [claimTicket(ctx)],
  // (2) No `store` here, so transcripts use the application's conversationStore.
  model: () =>
    createAdapter({
      provider: "openrouter",
      model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
      stream: true,
    }),
  systemPrompt: "You are a support agent. Keep running case notes in /case.md.",
});

import { join } from "node:path";
import {
  FileFoundryDataAdapter,
  createConversation,
  defineAgentInstance,
  defineApplication,
} from "glove-foundry";
import support from "./agents/support/agent.js";
import { dataDir } from "./lib/data-dir.js";

export const supportInstance = defineAgentInstance(support, {
  id: "support-main",
  workspaceId: "support",
  context: { tier: "standard" },
});

export default defineApplication({
  name: "Support",
  data: new FileFoundryDataAdapter({
    file: join(dataDir, "foundry.json"),
    // Seeds are inserted only when no record with that id exists yet.
    agents: [supportInstance],
    conversations: [createConversation(supportInstance, { id: "support-main-chat" })],
    lockTimeoutMs: 10_000,
    staleLockMs: 30_000,
  }),
});

import { Effect } from "effect";
import {
  createAgentInstance,
  reconstructAgentInstance,
  type AgentInstance,
  type ProvisionAgentOptions,
} from "glove-foundry";

// your code: any SQL client; this stub only names the shape used below.
declare const sql: {
  query<T>(text: string, values: unknown[]): Promise<{ rows: T[] }>;
};

/** One row per provisioning key, so concurrent callers converge on one instance. */
export function provisionAgent(
  input: ProvisionAgentOptions,
): Effect.Effect<AgentInstance, unknown, never> {
  return Effect.tryPromise({
    try: async () => {
      const candidate = createAgentInstance(input.definitionId, input, input.provisioningKey);
      await sql.query(
        "insert into foundry_agents (id, provisioning_key, record) values ($1, $2, $3) " +
          "on conflict (provisioning_key) do nothing",
        [candidate.id, input.provisioningKey, JSON.stringify(candidate)],
      );
      const { rows } = await sql.query<{ record: AgentInstance }>(
        "select record from foundry_agents where provisioning_key = $1",
        [input.provisioningKey],
      );
      return reconstructAgentInstance(rows[0]!.record);
    },
    catch: (cause) => cause,
  });
}

import { Effect } from "effect";
import type { GloveFoldArgs } from "glove-core";
import type { AgentAssemblyContext } from "glove-foundry";
import { z } from "zod";

const input = z.object({ ticketId: z.string() });

/** First writer wins: an atomic claim on a shared workspace key. */
export function claimTicket(ctx: AgentAssemblyContext): GloveFoldArgs<z.infer<typeof input>> {
  return {
    name: "claim_ticket",
    description: "Claim a ticket so only one agent in this workspace works on it.",
    inputSchema: input,
    async do({ ticketId }) {
      const key = `ticket-owner:${ticketId}`;
      const attempt = ctx.data.compareAndSetWorkspaceEntry?.(
        { workspaceId: ctx.workspaceId, key, value: ctx.agentId, updatedAt: new Date().toISOString() },
        null, // null: succeed only if the key does not exist yet
      );
      if (!attempt) {
        return { status: "error", data: null, message: "This data adapter has no atomic updates." };
      }
      const claimed = await Effect.runPromise(attempt);
      const owner = await Effect.runPromise(ctx.data.getWorkspaceEntry(ctx.workspaceId, key));
      return { status: "success", data: { claimed, owner: owner?.value } };
    },
  };
}