A local-first multi-agent app development platform, built on PenguinHarness
/**
* Agent service.
*
* The list is the union of "DB index ∪ directory scan", held to the one rule every Agent route
* applies: an Agent exists while `agents/<id>/agent_state/system_config.yaml` does. Unmanaged
* directories found are backfilled into the DB — this handles Agents created directly via the
* CLI — and an index row whose folder no longer has that file is not listed, so a listed Agent
* can always be opened and deleted.
* Delete: the folder is renamed into `agents/.deleting/` (one rename, so it leaves every list
* and route at once) and its contents are removed in the background, the removal reporting how
* far it got; a server that stops mid-removal resumes it at its next start.
* Create: generate agent-<8hex>, initialize Agent State via core's `createAgent`,
* then write name/description into system_config.yaml (parseDocument preserves the
* template's comments).
*/
import fs from "node:fs/promises";
import type { Dirent } from "node:fs";
import path from "node:path";
import { HttpError } from "../http/errors.js";
import { countEntries, FsLimiter, purgeTree } from "./tree-purge.js";
import {
agentDir,
agentsDir,
agentsMdPath,
BUILTIN_AGENT_IDS,
createAgent as coreCreateAgent,
installPlugin,
installSkill,
listInstalledHooks,
isValidId,
loadAgentVault,
memoryDir,
scheduleDir,
skillsDir,
systemConfigPath,
comparePluginVersions,
libraryPlugin,
loadLibraryPlugins,
parseSkillFrontmatter,
} from "@adelie/core";
import type { LibraryPlugin } from "@adelie/core";
import { SEMANTIC_ID_PATTERN, SEMANTIC_ID_RULE } from "./ids.js";
import { isTopicFileName } from "./memory-service.js";
import type { AgentDeletionInfo, PluginUpdateRef } from "../api/types.js";
import { resolveLibraryPlugins } from "./plugin-library.js";
import { resolveDirectorySkills } from "./directory-skills.js";
import { Component, Use } from "@adelie/core/kernel";
import type { ClassCtx } from "@adelie/core/kernel";
import type { Config, Paths } from "../hmr/capabilities.js";
import type { AgentConfig, AgentLifecycle, Snapshots } from "../mechanisms/agents.js";
import type { AgentIndex } from "../mechanisms/projects.js";
/**
* How much of a SKILL.md is read to answer "which version is installed" (see `installedSkills`).
* Generous against the largest frontmatter block the library ships (under 1 KB) and still a
* bounded read of a file whose body can be tens of kilobytes.
*/
const SKILL_HEAD_BYTES = 4096;
/**
* The first `bytes` of a file as UTF-8. A truncation can split a multi-byte character at the
* tail, which is harmless for every caller here: what is parsed out of the head is ASCII.
*/
async function readHead(file: string, bytes: number): Promise<string> {
const handle = await fs.open(file, "r");
try {
const buffer = Buffer.alloc(bytes);
const { bytesRead } = await handle.read(buffer, 0, bytes, 0);
return buffer.toString("utf8", 0, bytesRead);
} finally {
await handle.close();
}
}
/**
* `agents/.deleting/`: where a deleted Agent's folder waits while its contents are removed. A
* sibling of the Agents, so moving one in is a rename within one directory — never a copy across
* filesystems — and a dot-name, which no Agent id can be, so nothing that walks `agents/` takes
* it for one.
*/
export const DELETING_DIR = ".deleting";
/** `<agentsDir>/.deleting`. */
export function deletingDir(root: string, projectId: string): string {
return path.join(agentsDir(root, projectId), DELETING_DIR);
}
/** A deletion's name, which is its folder's name under `.deleting/`: the Agent id and when. */
const DELETION_NAME = /^(.+)-(\d+)$/;
/**
* Filesystem calls the background removal keeps in flight, across every deletion at once. libuv
* gives file I/O four threads by default; holding two leaves the others free for the requests
* the server is answering meanwhile.
*/
const PURGE_SLOTS = 2;
/** How long a finished deletion stays readable, for a page that polls it a little late. */
const FINISHED_DELETION_TTL_MS = 10 * 60 * 1000;
/**
* Windows refuses to move a folder while a program holds a file in it open; the hold is often
* momentary (an indexer, an antivirus scan), so the move is tried a few times before giving up.
*/
const MOVE_RETRIES = 4;
const MOVE_RETRY_STEP_MS = 100;
const MOVE_BUSY = new Set(["EBUSY", "EPERM", "EACCES"]);
/** Refuses deleting a built-in Agent: they are provisioned with the Project. */
export function refuseBuiltinDeletion(agentId: string): void {
if (BUILTIN_AGENT_IDS.includes(agentId)) {
throw new HttpError(
409,
"cannot_delete_builtin_agent",
"Built-in Agents are provisioned with the Project and cannot be deleted from the web.",
);
}
}
export interface AgentListItem {
agentId: string;
name?: string;
description?: string;
createdAt?: string;
/** Last config modification time: the later of system_config.yaml / AGENTS.md mtime. */
updatedAt?: string;
/** Tool count: number of tools.builtin + tools.mcpServers entries (MCP counted per server). */
toolCount: number;
/** Agent State version number (missing field treated as 1). */
version: number;
/** Whether the config's kernel stamp is behind the current defaults generation (missing stamp = outdated) — the list card's update hint. */
kernelOutdated: boolean;
/** Number of vault keys. */
vaultKeyCount: number;
/** Number of scheduled tasks (count of .toml files directly under schedule/, including invalid ones; archived files under schedule/expired/ are not counted). */
scheduleCount: number;
/** Number of installed Skills (count of skills/<name>/ directories that contain a SKILL.md). */
skillCount: number;
/** Number of installed hook packages (hooks/<name>/ directories with a hooks.json). */
hookCount: number;
/** Installed skills and hook packages the library has a newer version of, by plugin, each carrying that library version. */
pluginUpdates: PluginUpdateRef[];
/** Number of memory topic files across every scope directory under memory/ (independent of the memory switch, like skillCount). */
memoryCount: number;
}
@Component()
export class AgentService implements AgentLifecycle {
@Use() private readonly paths!: Paths;
private get root(): string {
return this.paths.root;
}
@Use() private readonly agents!: AgentIndex;
@Use() private readonly agentConfig!: AgentConfig;
@Use() private readonly snapshots!: Snapshots;
/** Deletions this process knows, by `${projectId}/${deletionId}`. */
private readonly deletions = new Map<string, AgentDeletionInfo>();
/** The removals in flight, by the same key. */
private readonly running = new Map<string, Promise<void>>();
/** Shared by every removal, so two deletions at once still hold only PURGE_SLOTS calls. */
private readonly limiter = new FsLimiter(PURGE_SLOTS);
/** Ends this generation's removals when it is disposed; the next one resumes them from disk. */
private readonly stopping = new AbortController();
setup(ctx: ClassCtx) {
ctx.effect(() => this.stopping.abort());
}
/**
* Union of DB index ∪ directory scan; unmanaged directory Agents are backfilled into the DB.
* Only what `AgentConfig.exists` accepts is listed — the rule every route checks.
*/
async listAgents(projectId: string): Promise<AgentListItem[]> {
const known = new Map(this.agents.list(projectId).map((r) => [r.agentId, r]));
let entries: string[] = [];
try {
const dirents = await fs.readdir(agentsDir(this.root, projectId), { withFileTypes: true });
entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
} catch {
// The Project's agents/ directory doesn't exist yet (no Agent directories): return from the DB index only.
}
for (const agentId of entries) {
if (known.has(agentId) || !isValidId(agentId)) continue;
const configPath = systemConfigPath(this.root, projectId, agentId);
let createdAt: string;
try {
const stat = await fs.stat(configPath);
createdAt = (stat.birthtime.getTime() > 0 ? stat.birthtime : stat.mtime).toISOString();
} catch {
continue; // A directory without system_config.yaml is not an Agent (e.g. a temp folder)
}
const row = { projectId, agentId, createdAt };
this.agents.insertOrIgnore(row);
known.set(agentId, row);
}
// The plugin library is read once for the whole list (every Agent is checked against the
// same files). Meta reads and mtime stats for each Agent run in parallel (Promise.all
// preserves the sorted order).
const library = loadLibraryPlugins(this.root);
// An index row is listed only while its folder is an Agent by the routes' own rule: a row
// whose folder has lost its system_config.yaml would be a card that neither opens nor deletes.
const present = await Promise.all(
[...known.values()].map(async (row) =>
(await this.agentConfig.exists(projectId, row.agentId)) ? row : null,
),
);
const sorted = present
.filter((row) => row !== null)
.sort((a, b) =>
a.createdAt === b.createdAt
? a.agentId.localeCompare(b.agentId)
: a.createdAt < b.createdAt
? -1
: 1,
);
return Promise.all(
sorted.map(async (row) => {
const [meta, updatedAt, vaultKeyCount, scheduleCount, installed, memoryCount] =
await Promise.all([
this.agentConfig.readCardMeta(projectId, row.agentId),
this.configUpdatedAt(projectId, row.agentId),
this.vaultKeyCount(projectId, row.agentId),
this.scheduleCount(projectId, row.agentId),
this.installedPlugins(projectId, row.agentId, library),
this.memoryCount(projectId, row.agentId),
]);
return {
agentId: row.agentId,
...meta,
createdAt: row.createdAt,
...(updatedAt !== undefined ? { updatedAt } : {}),
vaultKeyCount,
scheduleCount,
skillCount: installed.skillCount,
hookCount: installed.hookCount,
pluginUpdates: installed.updates,
memoryCount,
};
}),
);
}
/**
* Every id `createAgent` refuses as taken, as names only: the index rows and every entry under
* `agents/`. Unlike `listAgents`, this includes a folder with no `system_config.yaml`, and it
* opens no Agent.
*/
async takenAgentIds(projectId: string): Promise<string[]> {
let entries: string[] = [];
try {
entries = await fs.readdir(agentsDir(this.root, projectId));
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
}
return [...new Set([...this.agents.list(projectId).map((r) => r.agentId), ...entries])];
}
/** Number of vault keys (falls back to 0 on read failure). */
private async vaultKeyCount(projectId: string, agentId: string): Promise<number> {
try {
return Object.keys(await loadAgentVault(this.root, projectId, agentId)).length;
} catch {
return 0;
}
}
/** Number of scheduled tasks: count of .toml files directly under schedule/ (0 if the directory doesn't exist). The expired/ subdirectory of archived files is not a .toml name, so it is never counted. */
private async scheduleCount(projectId: string, agentId: string): Promise<number> {
try {
const names = await fs.readdir(scheduleDir(this.root, projectId, agentId));
return names.filter((n) => n.endsWith(".toml")).length;
} catch {
return 0;
}
}
/**
* One pass over `skills/` and one over `hooks/`, answering the card's questions: how many
* skills and hook packages are installed, and which of them the plugin library has moved
* past — by plugin, since a plugin is what gets reinstalled to catch up.
*
* Only the HEAD of each SKILL.md is read, and that bound is load-bearing rather than a
* micro-optimization: a preinstalled library is ~180 KB of SKILL.md across seventeen files
* per Agent, so a Project of ten Agents would move ~2 MB through every `GET /agents` — and
* the plugin page reloads that list after each update. The frontmatter block is at the head
* by definition (the parser's regex is anchored there) and the largest one in the library is
* under 1 KB, so {@link SKILL_HEAD_BYTES} covers it many times over; a block that somehow
* overran it would be truncated, fail to parse, and read as an empty version — the same
* fallback an unparseable file already takes, and one that sorts before every real version.
*
* The directory name is the identity (core's listings say so, and install/uninstall address
* by it), so that — not a frontmatter `name` — is what the library is looked up by: a skill
* by the plugin that ships it, a hook package by the plugin of the same name. A skill the
* library does not carry (installed from a zip or a picked directory) has no library version
* to be behind and is never an update. An unreadable skill degrades to "not installed" / "no
* update": a card hint must not be the thing that makes the Agent list fail. The library is
* the caller's, read once per listing rather than once per installed skill.
*/
private async installedPlugins(
projectId: string,
agentId: string,
library: readonly LibraryPlugin[],
): Promise<{ skillCount: number; hookCount: number; updates: PluginUpdateRef[] }> {
const base = skillsDir(this.root, projectId, agentId);
let dirents: Dirent[] = [];
try {
dirents = await fs.readdir(base, { withFileTypes: true });
} catch {
// No skills/ directory: nothing installed.
}
const skills = await Promise.all(
dirents
// Dot-prefixed directories are install staging, never a Skill (a Skill name has no dot).
.filter((d) => d.isDirectory() && !d.name.startsWith("."))
.map(async (d) => {
try {
const head = await readHead(path.join(base, d.name, "SKILL.md"), SKILL_HEAD_BYTES);
return { name: d.name, version: parseSkillFrontmatter(head)?.version ?? "" };
} catch {
return null;
}
}),
);
const hooks = await listInstalledHooks(this.root, projectId, agentId);
const byPlugin = new Map(library.map((p) => [p.name, p] as const));
const bySkill = new Map(library.flatMap((p) => p.skills.map((s) => [s.name, p] as const)));
const updates = new Map<string, string>();
for (const skill of skills) {
if (skill === null) continue;
const plugin = bySkill.get(skill.name);
if (plugin && comparePluginVersions(plugin.version, skill.version) > 0) {
updates.set(plugin.name, plugin.version);
}
}
for (const hook of hooks) {
const plugin = byPlugin.get(hook.name);
if (plugin && comparePluginVersions(plugin.version, hook.version) > 0) {
updates.set(plugin.name, plugin.version);
}
}
return {
skillCount: skills.filter((s) => s !== null).length,
hookCount: hooks.length,
updates: [...updates].map(([name, version]) => ({ name, version })),
};
}
/**
* Where one library plugin stands on one Agent: `installed` is the OLDEST version among the
* plugin's installed skills and its installed hook package — the same "any component behind
* the library is an update" rule {@link installedPlugins} draws the list cards' hints from —
* and null when the Agent carries none of them; `library` is the version the library offers
* now, null when the library has no such plugin. Only the head of each SKILL.md is read
* (see SKILL_HEAD_BYTES), so the answer costs one small read per skill the plugin ships.
*
* The organization runtime asks this per employee per pass to keep company plugins current.
* A skill the Agent does not carry — never installed, or removed by hand — counts for
* nothing: what is compared is the oldest version the Agent actually has, so a plugin whose
* skills are all current reads as current even where one of them is missing. Restoring a
* deleted skill is the Agents page's business, not a pass's.
*/
async pluginVersion(
projectId: string,
agentId: string,
pluginName: string,
): Promise<{ installed: string | null; library: string | null }> {
const plugin = libraryPlugin(pluginName, this.root);
if (!plugin) return { installed: null, library: null };
const base = skillsDir(this.root, projectId, agentId);
const versions: string[] = [];
for (const skill of plugin.skills) {
try {
const head = await readHead(path.join(base, skill.name, "SKILL.md"), SKILL_HEAD_BYTES);
versions.push(parseSkillFrontmatter(head)?.version ?? "");
} catch {
// The Agent does not carry this skill: it says nothing about the installed version.
}
}
if (plugin.hooks !== undefined) {
const hooks = await listInstalledHooks(this.root, projectId, agentId);
const installedHook = hooks.find((h) => h.name === pluginName);
if (installedHook) versions.push(installedHook.version);
}
let installed: string | null = null;
for (const version of versions) {
if (installed === null || comparePluginVersions(version, installed) < 0) installed = version;
}
return { installed, library: plugin.version };
}
/**
* Reinstall one library plugin over an Agent's copy: the same whole-plugin update the
* Agents page performs, through the same `installPlugin` writer, which overwrites every
* skill the plugin ships and its hook package with library content. Throws 404
* `unknown_plugin` when the library does not carry the name. Callers that may hold a cached
* runtime for the Agent invalidate it afterwards — hook packages are bound when a core
* Session is built, unlike skills, which are read from disk on demand.
*/
async updatePlugin(projectId: string, agentId: string, pluginName: string): Promise<void> {
for (const plugin of resolveLibraryPlugins([pluginName], this.root)) {
await installPlugin(this.root, projectId, agentId, plugin);
}
}
/** Number of memory topic files: regular `*.md` files (minus each scope's MEMORY.md index) summed over the scope directories under memory/ (0 if the directory doesn't exist). */
private async memoryCount(projectId: string, agentId: string): Promise<number> {
const base = memoryDir(this.root, projectId, agentId);
let scopes: Dirent[];
try {
scopes = await fs.readdir(base, { withFileTypes: true });
} catch {
return 0;
}
const counts = await Promise.all(
scopes
.filter((d) => d.isDirectory())
.map(async (d) => {
try {
const files = await fs.readdir(path.join(base, d.name), { withFileTypes: true });
return files.filter((f) => f.isFile() && isTopicFileName(f.name)).length;
} catch {
return 0;
}
}),
);
return counts.reduce((sum, n) => sum + n, 0);
}
/** Last config modification time: the later of system_config.yaml and AGENTS.md mtime; omitted if neither is readable. */
private async configUpdatedAt(projectId: string, agentId: string): Promise<string | undefined> {
const paths = [
systemConfigPath(this.root, projectId, agentId),
agentsMdPath(this.root, projectId, agentId),
];
const times = await Promise.all(
paths.map(async (p) => {
try {
return (await fs.stat(p)).mtime.getTime();
} catch {
return 0;
}
}),
);
const max = Math.max(...times);
return max > 0 ? new Date(max).toISOString() : undefined;
}
/**
* Delete an Agent: the built-in Agents cannot be deleted; callers must first drain any active
* run (the session manager's `beginAgentDeletion`) and let go of what holds the folder open.
*
* The folder (Agent State, Traces, scratchpads, temporary Workspaces) is moved to
* `agents/.deleting/<id>-<time>` in one rename and the index row dropped: from then on no list
* shows the Agent and no route accepts it, and a new Agent may take its id. The move is the
* whole of what the caller waits for — the contents are removed in the background, reported by
* the deletion returned (and by `agentDeletion` as it goes). A folder that cannot be moved is
* refused with nothing deleted (409 `agent_folder_busy`). Usage records are kept (historical
* stats are unaffected); the caller drops the Agent's other index rows.
*/
async deleteAgent(projectId: string, agentId: string): Promise<AgentDeletionInfo> {
refuseBuiltinDeletion(agentId);
const deletionId = await this.moveAside(projectId, agentId);
this.agents.delete(projectId, agentId);
if (deletionId === null) {
// The folder was already gone: there is nothing to remove.
return { deletionId: `${agentId}-0`, agentId, phase: "done", total: 0, removed: 0 };
}
return this.startPurge(projectId, deletionId, agentId);
}
agentDeletion(projectId: string, deletionId: string): AgentDeletionInfo | null {
const known = this.deletions.get(`${projectId}/${deletionId}`);
return known ? { ...known } : null;
}
/**
* Every folder left under a Project's `agents/.deleting/` — a deletion the last process did
* not finish, or one that met an entry it could not remove — is removed again, one after
* another. Folders a deletion of this process is already removing are left to it.
*/
async resumeDeletions(): Promise<void> {
let projects: Dirent[] = [];
try {
projects = await fs.readdir(this.root, { withFileTypes: true });
} catch {
return;
}
for (const project of projects) {
if (!project.isDirectory() || !isValidId(project.name)) continue;
let entries: string[] = [];
try {
entries = await fs.readdir(deletingDir(this.root, project.name));
} catch {
continue;
}
for (const name of entries) {
if (this.stopping.signal.aborted) return;
if (!isValidId(name)) continue;
const known = this.deletions.get(`${project.name}/${name}`);
if (known && (known.phase === "counting" || known.phase === "removing")) continue;
const agentId = DELETION_NAME.exec(name)?.[1] ?? name;
this.startPurge(project.name, name, agentId);
await this.running.get(`${project.name}/${name}`);
}
}
}
/**
* Renames the Agent's folder into `.deleting/`. Null when there was no folder to move; a
* folder a program keeps holding is refused with nothing moved.
*/
private async moveAside(projectId: string, agentId: string): Promise<string | null> {
const from = agentDir(this.root, projectId, agentId);
const trash = deletingDir(this.root, projectId);
await fs.mkdir(trash, { recursive: true });
const deletionId = `${agentId}-${Date.now()}`;
for (let attempt = 0; ; attempt++) {
try {
await fs.rename(from, path.join(trash, deletionId));
return deletionId;
} catch (err) {
const code = (err as NodeJS.ErrnoException).code ?? "";
if (code === "ENOENT") return null;
if (!MOVE_BUSY.has(code)) throw err;
if (attempt >= MOVE_RETRIES) {
throw new HttpError(
409,
"agent_folder_busy",
`The agent's folder could not be moved aside (${code}): another program may have a file in it open. Nothing was deleted.`,
);
}
await new Promise((resolve) => setTimeout(resolve, MOVE_RETRY_STEP_MS * (attempt + 1)));
}
}
}
/** Starts removing `.deleting/<deletionId>` in the background; answers its first reading. */
private startPurge(projectId: string, deletionId: string, agentId: string): AgentDeletionInfo {
const key = `${projectId}/${deletionId}`;
const info: AgentDeletionInfo = {
deletionId,
agentId,
phase: "counting",
total: 0,
removed: 0,
};
this.deletions.set(key, info);
const dir = path.join(deletingDir(this.root, projectId), deletionId);
const signal = this.stopping.signal;
const run = (async () => {
try {
const total = await countEntries(dir, {
limiter: this.limiter,
signal,
onCount: (n) => {
info.total = n;
},
});
if (signal.aborted) return;
info.total = total;
info.phase = "removing";
const failure = await purgeTree(dir, {
limiter: this.limiter,
signal,
onRemoved: () => {
info.removed += 1;
},
});
if (signal.aborted) return;
if (failure === null) {
info.phase = "done";
// Something added under the folder after it was counted would read past the total.
info.total = Math.max(info.total, info.removed);
} else {
info.phase = "failed";
info.error = failure.error;
}
} catch (err) {
info.phase = "failed";
info.error = err instanceof Error ? err.message : String(err);
} finally {
this.running.delete(key);
if (info.phase === "done" || info.phase === "failed") {
setTimeout(() => {
if (this.deletions.get(key) === info) this.deletions.delete(key);
}, FINISHED_DELETION_TTL_MS).unref?.();
}
}
})();
this.running.set(key, run);
return { ...info };
}
/**
* Create an Agent: the id is chosen by the creator (a semantic id, checked for
* duplicates against both the DB and the directory within the Project — a 409
* if taken, which naturally also blocks built-in Agent ids) → initialize State →
* write name/description (name defaults to the id) → install the seed plugins.
*
* `pluginNames` are library plugin names picked at creation; they go through the same
* `installPlugin` writer the plugin routes use, inside the same cleanup window as the rest
* of initialization, so an Agent never survives with only part of its picked set. They are
* resolved before anything is created, so an unknown name creates no directory at all.
*
* `archive` is an exported Agent State snapshot package: the fresh Agent is seeded from
* it instead of the default template (explicit name/description override the package's
* values, absent ones keep them — no id fallback). Mutually exclusive with seeding: the
* package carries its own skills and hooks. An invalid package fails the whole creation
* inside the same cleanup window, leaving no empty Agent behind.
*/
async createAgent(
projectId: string,
agentId: string,
name?: string,
description?: string,
pluginNames?: readonly string[],
directory?: { path: string; names: readonly string[] },
archive?: Buffer,
): Promise<AgentListItem> {
if (!SEMANTIC_ID_PATTERN.test(agentId)) {
throw new HttpError(
400,
"invalid_agent_id",
`Agent id must be 2–64 characters: ${SEMANTIC_ID_RULE}.`,
);
}
if (archive !== undefined && (pluginNames?.length || directory)) {
throw new HttpError(
400,
"snapshot_with_plugins",
"Snapshot initialization and seeding are mutually exclusive: the package carries its own skills and hooks.",
);
}
const taken =
this.agents.exists(projectId, agentId) ||
(await fs.stat(agentDir(this.root, projectId, agentId)).then(
() => true,
() => false,
));
if (taken) {
throw new HttpError(409, "agent_exists", `Agent id is already taken: ${agentId}.`);
}
const displayName = name ?? agentId;
// Both sources are resolved before a single file is written, so a name that has since left the
// library or the directory fails while the Agent still does not exist. Directory Skills are
// installed after the library plugins and so win a name collision: the user picked that
// directory for this Agent specifically, which is a narrower intent than "install the
// built-in one".
const librarySeed = resolveLibraryPlugins(pluginNames ?? [], this.root);
const directorySeed = directory
? await resolveDirectorySkills(directory.path, directory.names)
: [];
await coreCreateAgent({ root: this.root, projectId, agentId });
try {
if (archive !== undefined) {
// Seed the fresh state from the snapshot package. No pre-import snapshot and no
// version confirmation: both guards protect existing State, and this Agent has
// none yet — its template state is not worth preserving.
await this.snapshots.importArchive(projectId, agentId, archive, {
confirm: true,
preSnapshot: false,
});
// Explicit name/description override the package's values; absent ones keep them.
// No id fallback here: the package is the identity being copied in.
if (name !== undefined || description !== undefined) {
await this.agentConfig.updateConfig(projectId, agentId, {
config: {
...(name !== undefined ? { name } : {}),
...(description !== undefined ? { description } : {}),
},
});
}
} else {
await this.agentConfig.updateConfig(projectId, agentId, {
config: { name: displayName, ...(description !== undefined ? { description } : {}) },
});
}
for (const plugin of librarySeed) {
await installPlugin(this.root, projectId, agentId, plugin);
}
for (const skill of directorySeed) {
await installSkill(this.root, projectId, agentId, skill);
}
} catch (err) {
// If initialization fails partway through, clean up the directory: an orphaned
// directory would make retries with this agent id 409 forever.
await fs
.rm(agentDir(this.root, projectId, agentId), { recursive: true, force: true })
.catch(() => {});
throw err;
}
const createdAt = new Date().toISOString();
this.agents.insertOrIgnore({ projectId, agentId, createdAt });
// Read back the actual values: the init template ships a default toolset and version
// number, and a snapshot seed brings the package's own name, description, version,
// skills, schedules and memory.
const meta = await this.agentConfig.readCardMeta(projectId, agentId);
const cardName = archive !== undefined ? (meta.name ?? agentId) : displayName;
const cardDescription = archive !== undefined ? meta.description : description;
const installed = await this.installedPlugins(
projectId,
agentId,
loadLibraryPlugins(this.root),
);
return {
agentId,
name: cardName,
...(cardDescription !== undefined ? { description: cardDescription } : {}),
createdAt,
updatedAt: createdAt,
toolCount: meta.toolCount,
version: meta.version,
kernelOutdated: meta.kernelOutdated,
// The vault never travels in a snapshot, so this is 0 either way; the other counts
// are real reads because a package may carry any of them.
vaultKeyCount: 0,
scheduleCount: await this.scheduleCount(projectId, agentId),
skillCount: installed.skillCount,
hookCount: installed.hookCount,
pluginUpdates: installed.updates,
memoryCount: await this.memoryCount(projectId, agentId),
};
}
}