gumdrops-agents 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,61 @@
+# Gum Drops
+
+Gum Drops runs persistent [Pi](https://pi.dev/) coding agents on your computer and gives you a browser UI for them.
+
+An agent is a folder with an `AGENT.md` and a `memory.md`. It keeps one ongoing conversation, splits focused work into threads, remembers what it learns, and can run on a schedule. A small host process runs the agents and serves the UI. It keeps running when you close the browser.
+
+## Install
+
+Requires macOS or Linux and Node.js 22.19 or later.
+
+```sh
+npm i -g gumdrops-agents
+gumdrops setup
+```
+
+`setup` registers the host as a background service (launchd on macOS, a systemd user unit on Linux), starts it, helps you sign Pi in to a model provider, and opens the UI. Run `gumdrops open` to open the UI again.
+
+Manage the service:
+
+```sh
+gumdrops service status
+gumdrops service stop
+gumdrops service start
+gumdrops service uninstall   # stop running at login
+```
+
+`setup` and `service` take `--dry-run` to print the files and commands without running them. The host log is `host.log` in the host data folder (`~/Library/Application Support/GumDrops/host` on macOS, `~/.local/share/gumdrops/host` on Linux).
+
+## Agents
+
+Agents live in `~/.gumdrops/agents/<name>/` or in a project's `.gumdrops/agents/<name>/`. Create one in the UI, or in a project with:
+
+```sh
+gumdrops init
+```
+
+An agent edits its own folder and commits its changes with Git. Every run is snapshotted on a hidden Git ref, so you can inspect and revert changes without touching your branch. See [agent definitions](docs/agent-definitions.md) and [host commands](host/README.md).
+
+## Remote access
+
+The host only listens on this computer by default. To use it from your phone or another machine, put both on a private network such as [Tailscale](https://tailscale.com/) and bind the host to the Tailscale address:
+
+```sh
+gumdrops setup --bind <tailscale ip> --allow-host <machine>.<tailnet>.ts.net
+```
+
+The same flags work with `gumdrops serve` in the foreground. Then run `gumdrops open --host <machine>.<tailnet>.ts.net` and open the printed URL on the other device. The host can run commands on this machine, so never expose it to the public internet.
+
+Want this deployed in your own environment? Get in touch.
+
+## Development
+
+```sh
+npm install
+./run.sh                      # build host and web, run the host in the foreground
+node host/dist/cli.js open    # in another terminal
+npm run check                 # host and web checks
+npm run web:e2e               # browser smoke test against a built host and a fake Pi
+```
+
+`npm run web:build` builds the UI into `web/dist`, which the host serves. Set `GUMDROPS_HOST_DATA_DIR`, `GUMDROPS_CONFIG_DIR` and `GUMDROPS_HOST_PORT` to run a separate host for testing. The e2e test needs Playwright's Chromium once: `npx playwright install chromium`.

package/docs/agent-definitions.md

@@ -0,0 +1,171 @@
+# Agent definitions
+
+An agent is a folder. The folder is the source of truth.
+
+```text
+~/.gumdrops/agents/<name>/              global
+<project>/.gumdrops/agents/<name>/      project
+├── AGENT.md                            settings and role
+├── memory.md                           memory between runs
+├── mcp.json                            optional MCP servers
+├── skills/<name>/SKILL.md              optional skills
+└── avatar.svg                          optional face; initials without it
+```
+
+The host runs the definition that is on disk. Changes take effect on the next run. The host reloads definitions when these files, or installed plugins, change. The browser UI's inspector edits the model, thinking, role, memory and schedules; each save is a Git commit by you.
+
+Create an agent in the UI with just a folder and a name. Its role then defaults to helping with the work in that folder.
+
+The default `~/.gumdrops` directory is a Git repository. Set `GUMDROPS_CONFIG_DIR` to use another global root. Register a project with the host before using its agents.
+
+## AGENT.md
+
+`AGENT.md` has YAML front matter and a required Markdown role body:
+
+```md
+---
+name: Release manager
+model: openai-codex/gpt-5.6-luna
+thinking: high
+workspace: ~/Code/app
+schedule:
+  - name: morning
+    cron: "0 9 * * 1-5"
+    message: Check for new issues.
+---
+
+Prepare releases and report blockers.
+```
+
+Unknown front matter keys are errors. `workspace` resolves from the agent folder. `instructions` resolves from the workspace. `skills`, `extensions`, and MCP `cwd` resolve from the agent folder.
+
+### Front matter keys
+
+| Key | Meaning, default, and validation |
+| --- | --- |
+| `name` | Display name; defaults to the folder name; a supplied value must be a non-empty string. |
+| `title` | Optional non-empty title. |
+| `description` | Optional non-empty description. |
+| `icon` | Optional non-empty icon value. |
+| `model` | Model in `provider/name` form; defaults to `openai-codex/gpt-5.6-luna`. |
+| `thinking` | Optional level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
+| `workspace` | Workspace directory; defaults to `defaultWorkspace`; the directory must exist. |
+| `instructions` | List of existing instruction files, resolved from the workspace; defaults to an empty list. |
+| `tools` | Optional list of Pi built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, or `ls`. Omit it for Pi defaults. |
+| `skills` | Additional existing skill paths, resolved from the agent folder. Folder skills are also included automatically. |
+| `plugins` | List of Claude plugin names. See [Plugins](#plugins). |
+| `extensions` | List of existing extension paths, resolved from the agent folder; defaults to an empty list. |
+| `mcp` | Inline MCP server map; defaults to an empty map. Each server needs a command or an HTTP(S) URL; `type` (`stdio` or `http`) is optional. |
+| `delegation` | `true`, `false`, or a map with `enabled`, positive integer `maxChildren`, and optional child `model` and `thinking`. Enabled by default. |
+| `collaboration` | `true`, `false`, or a map. It defaults to enabled, contacts `[*]`, and `acceptTasks: true`. |
+| `schedule` | List of schedules with valid `cron` and `message` values. Names must be unique. |
+| `timeout` | Positive seconds or a duration such as `30ms`, `30s`, `45m`, `2h`, or `1d`. |
+
+## MCP servers and secrets
+
+Every agent gets the host-wide servers in `~/.gumdrops/mcp.json`, which you manage in the UI under Settings. An agent's own `mcp.json` is optional and has no UI. Both accept a plain server map or `{ "mcpServers": { ... } }`. An agent's `mcp.json` merges with its `mcp` key (duplicate names are errors), and its servers win over host-wide ones with the same name.
+
+```json
+{
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": { "GITHUB_TOKEN": { "secretRef": "secret:GITHUB_TOKEN" } }
+  },
+  "docs": {
+    "url": "https://example.com/mcp",
+    "headers": { "Authorization": { "secretRef": "secret:DOCS_KEY", "prefix": "Bearer " } }
+  }
+}
+```
+
+An `env` or `headers` value is literal text or a `secretRef`:
+
+- `secret:NAME`: the host's secret store, `secrets.json` (mode 0600) in the host data folder. Set values in Settings; the UI never shows them again.
+- `env:NAME`: the host's environment. Under launchd or systemd this is not your shell's environment, so prefer `secret:`.
+- `keychain:SERVICE[/ACCOUNT]`: the macOS Keychain.
+
+A server with `oauth` (as in most plugin connectors) is accepted but skipped when the agent runs, with an activity note: OAuth sign-in isn't supported yet.
+
+## Plugins
+
+`plugins: [marketing]` gives the agent a [Claude plugin](https://github.com/anthropics/knowledge-work-plugins)'s skills, commands and MCP servers, used as they are. The host looks for `~/.gumdrops/plugins/<name>/` first, then for the plugins bundled with it (`gumdrops`). An unknown or unreadable plugin is a definition error.
+
+```text
+~/.gumdrops/plugins/<name>/
+├── .claude-plugin/plugin.json   name, version, description
+├── .mcp.json                     { "mcpServers": { ... } }
+├── skills/<name>/SKILL.md        skills
+├── commands/*.md                 single-file skills; they work the same
+├── agents/*.md                   listed, not used yet
+└── hooks/                        ignored
+```
+
+- `${CLAUDE_PLUGIN_ROOT}` in `.mcp.json` (commands, args, env, cwd, url) is the plugin folder. The agent's prompt says where each plugin is, for skills that mention it.
+- The agent's own skills and MCP servers win over a plugin's with the same name, and earlier plugins win over later ones.
+- The inspector lists each plugin's skills and servers, with notes on what is skipped: hooks, sub-agents, OAuth servers, name clashes.
+- Customise a plugin by editing the installed copy; every agent that uses it sees the change. Editing, adding or removing a plugin reloads the agents.
+
+Install, customise and update plugins by asking the Gum Drops agent (below), or by hand: copy the plugin folder into `~/.gumdrops/plugins/<name>/`.
+
+## Avatars
+
+`avatar.svg` in the agent folder is its face in the UI. The UI loads it only with `<img>`, idle by default, `<file>#working` while the agent runs and `<file>#still` in lists. The `gumdrops` plugin ships 14 designs in `host/plugins/gumdrops/avatars/`; copy one and change its `--avatar-color`.
+
+The file must have `<svg viewBox="0 0 100 110">`, its main colour in `--avatar-color`, and its CSS and animations in one `<style>` block, with `:target` rules for `#working` and `#still` and no motion under `prefers-reduced-motion`. It may not use `<script>`, `<foreignObject>`, images, SMIL animation, `on*` attributes, fonts, `@import`, or `href` and `url()` to anything but `#id` in the file, and must be at most 64 KB. A file that breaks a rule shows initials, with the error in the inspector.
+
+## The Gum Drops agent
+
+`gumdrops setup` creates `~/.gumdrops/agents/gumdrops/` when there are no agents yet. It uses the `gumdrops` plugin and works in `~/.gumdrops`, so it can write agents and plugins: ask it for "a marketing agent for ~/Code/site from knowledge-work-plugins". Its skills, in `host/plugins/gumdrops/skills/`, describe the folder layout, every key, plugin marketplaces, and avatars.
+
+## Identity and memory
+
+The absolute `AGENT.md` path is the agent identity. The database maps that path to an ID. Gum Drops does not write IDs into files. Renaming or moving a folder creates a new agent. The old agent becomes `missing`.
+
+`memory.md` is user-editable. The `remember` tool appends dated notes and creates a `# Memory` header when needed. Memory writes enter history. The last 4,000 bytes appear in the prompt under **Your memory**.
+
+## Change definitions
+
+An agent with file tools edits its own folder directly. It can create an agent by adding `<agentsDir>/<name>/AGENT.md`. It can retire an agent by deleting its folder.
+
+After changing a definition, commit the folder with Git:
+
+```sh
+git add <folder>
+git commit -m "why"
+```
+
+Committing is best practice, not a host requirement. The UI and CLI warn when a definition folder has uncommitted changes. The warning excludes `memory.md`.
+
+## Git history
+
+Gum Drops snapshots definition changes and every root agent run's workspace changes.
+
+- Every run is snapshotted on a hidden ref, so changes can be seen and reverted.
+- For a folder or workspace inside a real Git repository, Gum Drops uses a private index and a hidden `refs/gumdrops/...` ref.
+- It never changes `HEAD`, the user's index, branch, or working tree.
+- A folder outside Git uses a shadow repository in the host data directory.
+- A non-Git workspace has no run snapshot.
+
+Inspect history with:
+
+```sh
+git log refs/gumdrops/history
+gumdrops history <agent> [<commit>]
+gumdrops log <agent> [--limit <n>]
+gumdrops revert <agent> <commit>
+```
+
+The API provides definition history at `/v1/agents/:id/history` and workspace history at `/v1/agents/:id/changes`. History includes diffs and restore or revert actions.
+
+## Migration and commands
+
+Run `gumdrops migrate` to convert old YAML definitions in `<configDir>/agents` and project `.gumdrops/agents` folders. Migration creates agent folders, keeps IDs, moves lessons into `memory.md`, updates database paths, and moves each YAML file into `.migrated/`. Stop the host before migration.
+
+```sh
+gumdrops init [dir] [--name <name>]
+gumdrops migrate
+gumdrops history <agent> [<commit>]
+gumdrops log <agent> [--limit <n>]
+gumdrops revert <agent> <commit>
+```

package/host/dist/agentfile.js

@@ -0,0 +1,418 @@
+/* An agent is a folder. AGENT.md holds its settings in front matter and its role in the
+   body. The agent keeps what it learns in memory.md beside it. The folder is the source of
+   truth for configuration; the host database keeps runtime state. */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { Document, isMap, parseDocument, stringify } from "yaml";
+import { AVATAR_FILE, loadAvatar } from "./avatar.js";
+import { parseCron } from "./cron.js";
+import { forRuntime, MCP_SERVER_NAME, mcpServerEntry } from "./mcp.js";
+import { loadPlugin, pluginFiles, skillName } from "./plugins.js";
+export const AGENT_FILE = "AGENT.md";
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+export const BUILTIN_TOOLS = [
+    "read",
+    "bash",
+    "edit",
+    "write",
+    "grep",
+    "find",
+    "ls",
+];
+export const DEFAULT_MODEL = "openai-codex/gpt-5.6-luna";
+export const DEFAULT_COLLABORATION = { enabled: true, contacts: ["*"], acceptTasks: true };
+/** Every front matter key AGENT.md accepts. The role is the body. */
+const KEYS = [
+    "name",
+    "title",
+    "description",
+    "icon",
+    "model",
+    "thinking",
+    "workspace",
+    "instructions",
+    "tools",
+    "skills",
+    "plugins",
+    "extensions",
+    "mcp",
+    "delegation",
+    "collaboration",
+    "schedule",
+    "timeout",
+];
+const isObj = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const expandHome = (path) => path === "~" ? homedir() : path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+const absolute = (path, base) => resolve(base, expandHome(path));
+export function parseDuration(value, field) {
+    if (typeof value === "number" && value > 0)
+        return value * 1000;
+    const match = typeof value === "string" ? value.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/) : null;
+    if (!match)
+        throw new Error(`${field} must be a duration such as 30s, 45m, 2h or 1d`);
+    const unit = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2]];
+    return Math.round(Number(match[1]) * unit);
+}
+const FRONT_MATTER = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/** Splits AGENT.md into its front matter (as a YAML document) and its body. */
+function split(source) {
+    const match = source.match(FRONT_MATTER);
+    const document = parseDocument(match ? match[1] : "");
+    if (document.errors.length)
+        throw new Error(`Front matter: ${document.errors[0].message}`);
+    const value = document.toJS() ?? {};
+    if (!isObj(value))
+        throw new Error("Front matter must be a YAML mapping");
+    return { document, data: value, body: (match ? source.slice(match[0].length) : source).trim() };
+}
+/** AGENT.md's front matter as plain values. Throws on bad YAML. */
+export const frontMatterOf = (source) => split(source).data;
+/** AGENT.md text from front matter and a role. */
+export function agentMarkdown(data, role) {
+    const front = Object.keys(data).length ? `---\n${stringify(data)}---\n\n` : "";
+    return `${front}${role.trim()}\n`;
+}
+/** The project that owns a folder under `<project>/.gumdrops/agents`, if any. */
+export function projectOf(folder) {
+    const agents = dirname(folder);
+    return basename(agents) === "agents" && basename(dirname(agents)) === ".gumdrops"
+        ? dirname(dirname(agents))
+        : null;
+}
+/** The folder that holds an agent's `agents` folder: `~/.gumdrops` or `<project>/.gumdrops`. */
+export const definitionRootOf = (folder) => dirname(dirname(folder));
+function strings(value, field) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        throw new Error(`${field} must be a list of strings`);
+    return value;
+}
+function existing(paths, field) {
+    for (const path of paths)
+        if (!existsSync(path))
+            throw new Error(`${field}: ${path} does not exist`);
+    return paths;
+}
+function text(value, field, required = false) {
+    if (value === undefined && !required)
+        return undefined;
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${field} must be a non-empty string`);
+    return value;
+}
+function thinking(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!THINKING_LEVELS.includes(value))
+        throw new Error(`${field} must be one of ${THINKING_LEVELS.join(", ")}`);
+    return value;
+}
+/** "provider/name"; the name may itself contain slashes. */
+function model(value, field) {
+    const raw = text(value, field);
+    if (raw === undefined)
+        return undefined;
+    const slash = raw.indexOf("/");
+    if (slash <= 0 || slash === raw.length - 1)
+        throw new Error(`${field} must look like provider/model, such as ${DEFAULT_MODEL}`);
+    return { provider: raw.slice(0, slash).trim(), name: raw.slice(slash + 1).trim() };
+}
+function mcpServers(value, source, base) {
+    if (value === undefined)
+        return {};
+    if (!isObj(value))
+        throw new Error(`${source} must be a mapping of server name to server`);
+    const servers = {};
+    for (const [server, entry] of Object.entries(value)) {
+        const field = `${source}.${server}`;
+        if (!MCP_SERVER_NAME.test(server))
+            throw new Error(`${field}: server names may use letters, digits, _ and -`);
+        servers[server] = forRuntime(mcpServerEntry(entry, field), base);
+    }
+    return servers;
+}
+/** mcp.json in the agent folder, in the shape other MCP clients use. */
+function mcpFile(folder) {
+    const path = join(folder, "mcp.json");
+    if (!existsSync(path))
+        return {};
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`mcp.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return mcpServers(isObj(value) && isObj(value.mcpServers) ? value.mcpServers : value, "mcp.json", folder);
+}
+/** Skills in the folder's skills/ directory: every subfolder with a SKILL.md. */
+function folderSkills(folder) {
+    const skills = join(folder, "skills");
+    try {
+        return readdirSync(skills)
+            .sort()
+            .map((name) => join(skills, name))
+            .filter((path) => existsSync(join(path, "SKILL.md")));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Adds the plugins' skills, commands and MCP servers to the agent's own. The agent's own win on a
+ * name clash, then earlier plugins; each loser is a note on its plugin.
+ */
+function withPlugins(names, configDir, skills, mcp) {
+    const taken = new Set(skills.map(skillName));
+    const servers = {};
+    const commands = [];
+    const plugins = [];
+    const pluginSkills = [];
+    for (const name of new Set(names)) {
+        const { skillFolders, commands: pluginCommands, mcp: pluginServers, ...summary } = loadPlugin(name, configDir);
+        const notes = [...summary.notes];
+        const used = { skills: [], mcpServers: [] };
+        const claim = (skill) => {
+            if (taken.has(skill))
+                notes.push(`Skill ${skill} is already defined, so this plugin's is not used`);
+            else
+                taken.add(skill), used.skills.push(skill);
+            return used.skills.includes(skill);
+        };
+        for (const skill of skillFolders)
+            if (claim(skill.name))
+                pluginSkills.push(skill.path);
+        for (const command of pluginCommands)
+            if (claim(command.name))
+                commands.push(command);
+        for (const [server, entry] of Object.entries(pluginServers))
+            if (mcp[server] || servers[server])
+                notes.push(`MCP server ${server} is already defined, so this plugin's is not used`);
+            else
+                (servers[server] = entry), used.mcpServers.push(server);
+        plugins.push({ ...summary, ...used, notes });
+    }
+    return { skills: [...skills, ...pluginSkills], commands, mcp: { ...servers, ...mcp }, plugins };
+}
+function schedules(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("schedule must be a list");
+    const names = new Set();
+    return value.map((item, index) => {
+        const field = `schedule[${index}]`;
+        if (!isObj(item))
+            throw new Error(`${field} must be a mapping with cron and message`);
+        const cron = text(item.cron, `${field}.cron`, true);
+        const entry = {
+            name: text(item.name, `${field}.name`) ?? cron,
+            cron,
+            timezone: text(item.timezone, `${field}.timezone`),
+            message: text(item.message, `${field}.message`, true),
+        };
+        if (names.has(entry.name))
+            throw new Error(`${field}: two schedules are called "${entry.name}"; give them names`);
+        names.add(entry.name);
+        parseCron(entry.cron);
+        if (entry.timezone)
+            try {
+                new Intl.DateTimeFormat("en-US", { timeZone: entry.timezone });
+            }
+            catch {
+                throw new Error(`${field}.timezone is not a valid IANA time zone`);
+            }
+        return entry;
+    });
+}
+/** The workspace an agent gets when AGENT.md does not name one: its project, or its own folder. */
+export function defaultWorkspace(folder, configDir) {
+    const project = projectOf(folder);
+    return project && resolve(definitionRootOf(folder)) !== resolve(configDir) ? project : folder;
+}
+/**
+ * Loads an agent folder. With `source`, validates that text as the folder's AGENT.md
+ * without writing it. Throws a readable error for anything wrong.
+ */
+export function loadAgent(folder, configDir, source) {
+    const raw = source ?? readFileSync(join(folder, AGENT_FILE), "utf8");
+    const { data, body } = split(raw);
+    for (const key of Object.keys(data))
+        if (!KEYS.includes(key))
+            throw new Error(`Unknown key "${key}" (use ${KEYS.join(", ")})`);
+    if (!body)
+        throw new Error("AGENT.md needs a role: write it below the front matter");
+    const workspace = absolute(text(data.workspace, "workspace") ?? defaultWorkspace(folder, configDir), folder);
+    if (!existsSync(workspace) || !statSync(workspace).isDirectory())
+        throw new Error(`workspace is not a directory: ${workspace}`);
+    const tools = data.tools === undefined ? undefined : strings(data.tools, "tools");
+    for (const tool of tools ?? [])
+        if (!BUILTIN_TOOLS.includes(tool))
+            throw new Error(`tools: unknown built-in tool "${tool}" (use ${BUILTIN_TOOLS.join(", ")})`);
+    const inline = mcpServers(data.mcp, "mcp", folder);
+    const fromFile = mcpFile(folder);
+    for (const server of Object.keys(inline))
+        if (fromFile[server])
+            throw new Error(`MCP server "${server}" is in both AGENT.md and mcp.json`);
+    if (data.delegation !== undefined && typeof data.delegation !== "boolean" && !isObj(data.delegation))
+        throw new Error("delegation must be true, false or a mapping");
+    const delegation = isObj(data.delegation) ? data.delegation : {};
+    for (const key of Object.keys(delegation))
+        if (!["enabled", "maxChildren", "model", "thinking"].includes(key))
+            throw new Error(`delegation.${key} is not a setting (use enabled, maxChildren, model, thinking)`);
+    if (delegation.maxChildren !== undefined && (!Number.isInteger(delegation.maxChildren) || Number(delegation.maxChildren) < 1))
+        throw new Error("delegation.maxChildren must be a positive integer");
+    const childModel = model(delegation.model, "delegation.model");
+    const childThinking = thinking(delegation.thinking, "delegation.thinking");
+    if (data.collaboration !== undefined && typeof data.collaboration !== "boolean" && !isObj(data.collaboration))
+        throw new Error("collaboration must be true, false or a mapping");
+    const collaboration = isObj(data.collaboration) ? data.collaboration : { enabled: data.collaboration };
+    for (const flag of ["enabled", "acceptTasks"])
+        if (collaboration[flag] !== undefined && typeof collaboration[flag] !== "boolean")
+            throw new Error(`collaboration.${flag} must be true or false`);
+    const main = model(data.model, "model") ?? model(DEFAULT_MODEL, "model");
+    const resolved = withPlugins(strings(data.plugins, "plugins"), configDir, [...folderSkills(folder), ...existing(strings(data.skills, "skills").map((path) => absolute(path, folder)), "skills")], { ...fromFile, ...inline });
+    return {
+        id: "",
+        name: text(data.name, "name") ?? basename(folder),
+        folder,
+        title: text(data.title, "title"),
+        description: text(data.description, "description"),
+        icon: text(data.icon, "icon"),
+        role: body,
+        instructionsFiles: existing(strings(data.instructions, "instructions").map((path) => absolute(path, workspace)), "instructions"),
+        model: { ...main, thinking: thinking(data.thinking, "thinking") },
+        workspace,
+        tools,
+        skills: resolved.skills,
+        commands: resolved.commands,
+        plugins: resolved.plugins,
+        extensions: existing(strings(data.extensions, "extensions").map((path) => absolute(path, folder)), "extensions"),
+        mcp: resolved.mcp,
+        ...loadAvatar(folder),
+        delegation: {
+            enabled: data.delegation !== false && delegation.enabled !== false,
+            maxChildren: delegation.maxChildren,
+            model: childModel || childThinking ? { ...childModel, ...(childThinking ? { thinking: childThinking } : {}) } : undefined,
+        },
+        collaboration: {
+            enabled: collaboration.enabled !== false,
+            contacts: collaboration.contacts === undefined
+                ? [...DEFAULT_COLLABORATION.contacts]
+                : strings(collaboration.contacts, "collaboration.contacts"),
+            acceptTasks: collaboration.acceptTasks !== false,
+        },
+        schedule: schedules(data.schedule),
+        limits: { runTimeoutMs: data.timeout === undefined ? undefined : parseDuration(data.timeout, "timeout") },
+    };
+}
+/**
+ * AGENT.md text with front matter keys set (undefined deletes the key) and optionally a new
+ * role, keeping everything else as written.
+ */
+export function editAgentMarkdown(source, keys, role) {
+    const { document: parsed, body } = split(source);
+    // An empty front matter parses to null, not a mapping; start a fresh one.
+    const document = isMap(parsed.contents) ? parsed : new Document({});
+    for (const [key, value] of Object.entries(keys))
+        if (value === undefined)
+            document.delete(key);
+        else
+            document.set(key, document.createNode(value));
+    const front = document.toString().trim();
+    return `${front && front !== "{}" ? `---\n${front}\n---\n\n` : ""}${(role ?? body).trim()}\n`;
+}
+/** Replaces the schedule list in AGENT.md, keeping the rest of the file as written. */
+export function writeSchedules(folder, list) {
+    const path = join(folder, AGENT_FILE);
+    const items = list.map(({ name, cron, timezone, message }) => ({
+        name,
+        cron,
+        ...(timezone ? { timezone } : {}),
+        message,
+    }));
+    writeFileSync(path, editAgentMarkdown(readFileSync(path, "utf8"), { schedule: items.length ? items : undefined }));
+}
+/** What the agent remembers between runs. It writes here; the user may edit it too. */
+export const memoryPath = (folder) => join(folder, "memory.md");
+const read = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+};
+/** Agent folders in one `agents` folder: each subfolder with an AGENT.md. */
+function agentFoldersIn(folder) {
+    try {
+        return readdirSync(folder)
+            .filter((name) => !name.startsWith("."))
+            .sort()
+            .map((name) => join(folder, name))
+            .filter((path) => existsSync(join(path, AGENT_FILE)));
+    }
+    catch {
+        return [];
+    }
+}
+/** Folders searched for agents: `~/.gumdrops/agents` and each project's `.gumdrops/agents`. */
+export const agentsFolders = (roots) => [
+    ...new Set([
+        join(roots.configDir, "agents"),
+        ...roots.projects.map((project) => join(project, ".gumdrops", "agents")),
+    ]),
+];
+/** A cheap fingerprint of every agent folder, so the host reloads only on change. */
+export function fingerprint(roots) {
+    return [
+        ...agentsFolders(roots)
+            .flatMap(agentFoldersIn)
+            .flatMap((folder) => [AGENT_FILE, "memory.md", "mcp.json", "skills", AVATAR_FILE].map((file) => join(folder, file))),
+        // Installed plugins, so editing, installing or updating one reloads the agents that use it.
+        ...pluginFiles(roots.configDir),
+    ]
+        .map((file) => {
+        try {
+            const stat = statSync(file);
+            return `${file}:${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return "";
+        }
+    })
+        .join("\n");
+}
+export function loadAll(roots) {
+    const agents = [];
+    const failures = [];
+    for (const folder of agentsFolders(roots).flatMap(agentFoldersIn)) {
+        const path = join(folder, AGENT_FILE);
+        try {
+            agents.push({ path, spec: loadAgent(folder, roots.configDir), memory: read(memoryPath(folder)).trim() });
+        }
+        catch (error) {
+            failures.push({ path, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { agents, failures };
+}
+export const slug = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "agent";
+/** A free folder for a new agent in an `agents` folder. */
+export function newAgentFolder(agents, name) {
+    let folder = join(agents, slug(name));
+    for (let index = 2; existsSync(folder); index += 1)
+        folder = join(agents, `${slug(name)}-${index}`);
+    return folder;
+}
+//# sourceMappingURL=agentfile.js.map

package/host/dist/api.js

@@ -0,0 +1,3 @@
+/** Bumped only when an existing route or event changes shape. New routes and fields don't bump it. */
+export const API_VERSION = 2;
+//# sourceMappingURL=api.js.map