A local-first multi-agent app development platform, built on PenguinHarness
/**
* WorkflowService: boots every workflow folder of an Agent as a module tree of its own.
*
* A workflow is a plugin package: hand-written manifests in `package.json#penguin.modules`
* and an `index.ts` whose default export pairs them with code. Its root module must be
* named `Workflow` and provide `WorkflowMain`; the server publishes `WorkflowHost` to the
* tree as module `Host`, and the slots it opens to workflows under the platform's own
* module names (today `WebModule.sessionTabs`), so a workflow contributes a tab the way a
* plugin does and the host scopes it to the Agent.
*
* Three checks run before any create(), and a failure of any keeps the previous instance
* serving with the problem named: the source is type-checked under `strict` against the
* types the harness wrote into the folder when the workflow was new (./harness-types.ts,
* ./compile.ts); those are compared with this platform's, both ways, by the compiler
* (../plugin/iface-check.ts); and the tree is checked like any other — wiring, slots,
* contribution shapes.
*
* Loading is by content: the folder's revision (store.ts) names the directory the source
* is emitted into, so an edited workflow is a new import URL rather than a hit in the ESM
* cache, and every successful load records the folder as a version the Agent (or the
* user) can roll back to. A watcher on the `workflows/` folder reloads on change, debounced, and the users of
* the Project hear `workflow_updated` on their event stream.
*/
import fs from "node:fs";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { bootModules, Component, parseManifest, Use } from "@adelie/core/kernel";
import type {
ClassCtx,
IfaceDecl,
IfaceTable,
Manifest,
ModuleDef,
ModuleTree,
} from "@adelie/core/kernel";
import { userText } from "@adelie/core";
import table from "../ifaces.json" with { type: "json" };
import type { ServerEvent } from "../api/types.js";
import type { Channels, Clock, Hmr, Log, Paths } from "../hmr/capabilities.js";
import { userChannelKey } from "../http/routes/events.js";
import type { AgentIndex, Members, Projects } from "../mechanisms/projects.js";
import type { SessionIndex } from "../mechanisms/sessions.js";
import type {
WorkflowInfo,
WorkflowInput,
WorkflowRequest,
WorkflowResponse,
WorkflowTab,
WorkflowVersion,
Workflows,
} from "../mechanisms/workflows.js";
import { ScheduleSessionCreator, ScheduleTaskRunner } from "../runtime/scheduler.js";
import { compileWorkflow, pruneBuilds, writeLoadStatus } from "./compile.js";
import { installHarnessTypes, readHarnessTable } from "./harness-types.js";
import { checkIfaces, ifaceQuestions } from "../plugin/iface-check.js";
import { loadTypeScript } from "../plugin/typescript.js";
import {
historyDir,
isSafeRelPath,
isTempName,
isWorkflowId,
listFolders,
listVersions,
readFolder,
readState,
recordVersion,
restoreVersion,
STATE_FILE,
UI_DIR,
workflowsDir,
writeState,
type WorkflowFolder,
} from "./store.js";
const PKG = "@adelie/server";
export const HOST_MODULE = "Host";
export const ROOT_MODULE = "Workflow";
export const HOST_IFACE = `${PKG}#WorkflowHost`;
export const MAIN_IFACE = `${PKG}#WorkflowMain`;
/** The platform module whose slots the host opens to workflows, and the slots it opens. */
export const WEB_MODULE = "WebModule";
export const WEB_IFACE = `${PKG}#WebShell`;
export const TABS_SLOT = "sessionTabs";
const OPEN_WEB_SLOTS = [TABS_SLOT] as const;
/** A burst of file writes (an editor, a git checkout, a rollback) becomes one reload. */
const WATCH_SETTLE_MS = 300;
interface Loaded {
folder: WorkflowFolder;
tree: ModuleTree | null;
main: { handle(request: WorkflowRequest): Promise<WorkflowResponse> } | null;
tabs: WorkflowTab[];
loadedAt: string;
error: string | null;
}
function key(projectId: string, agentId: string, workflowId: string): string {
return `${projectId}/${agentId}/${workflowId}`;
}
function messageOf(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
/** Reads `package.json`: the manifests, and that the package is an ES module. */
async function readManifests(folder: WorkflowFolder): Promise<Manifest[]> {
const raw = JSON.parse(
await fs.promises.readFile(path.join(folder.dir, "package.json"), "utf8"),
) as {
type?: unknown;
penguin?: { modules?: unknown };
};
if (raw.type !== "module") {
throw new Error('package.json must set "type": "module" (a workflow is an ES module)');
}
const list = raw.penguin?.modules;
if (!Array.isArray(list) || list.length === 0) {
throw new Error("package.json#penguin.modules must list at least the `Workflow` module");
}
return list.map((doc, i) => {
try {
return parseManifest(doc);
} catch (err) {
throw new Error(`package.json#penguin.modules[${i}]: ${messageOf(err)}`);
}
});
}
/**
* A workflow that loads and shows nothing is the quietest way to get this wrong: the pages are
* written, the load is green, and no tab appears, because a page is only a file until the
* manifest contributes a tab for it. The author is usually an Agent with nothing but these
* files and the load status, so the status says it, with the entry to add.
*/
export function loadHints(
uiRev: string | null,
tabs: readonly WorkflowTab[],
error: string | null,
): string[] {
if (error !== null || uiRev === null || tabs.length > 0) return [];
const entry = {
key: "main",
title: "<tab title>",
renderer: { iframe: { src: `${UI_DIR}/index.html` } },
};
return [
`${UI_DIR}/ has pages but the manifest contributes no tab, so nothing shows beside the chat. ` +
`In package.json, under penguin.modules[0] (the module named Workflow), set ` +
`"contributes": ${JSON.stringify({ [`${WEB_MODULE}.${TABS_SLOT}`]: [entry] })} — ` +
`one entry per tab, src a file under ${UI_DIR}/.`,
];
}
/**
* The tabs the manifests contribute to `WebModule.sessionTabs`, with each page's path (in
* the folder, under `ui/`) turned into the URL it is served from. The slot's shape was
* checked with the tree; where a page may live is this host's rule.
*/
function contributedTabs(manifests: readonly Manifest[], uiBase: string): WorkflowTab[] {
const tabs: WorkflowTab[] = [];
const keys = new Set<string>();
for (const m of manifests) {
for (const entry of m.contributes[`${WEB_MODULE}.${TABS_SLOT}`] ?? []) {
const tab = entry as unknown as WorkflowTab;
if (keys.has(tab.key)) {
throw new Error(
`contribution '${tab.id}': another tab of this workflow already has the key '${tab.key}'`,
);
}
keys.add(tab.key);
if (!("iframe" in tab.renderer)) {
tabs.push(tab);
continue;
}
const src = tab.renderer.iframe.src;
if (!isSafeRelPath(src) || !src.startsWith(`${UI_DIR}/`)) {
throw new Error(
`contribution '${tab.id}': renderer.iframe.src must be a file under ${UI_DIR}/ (got '${src}')`,
);
}
const rest = src
.slice(UI_DIR.length + 1)
.split("/")
.map(encodeURIComponent)
.join("/");
tabs.push({ ...tab, renderer: { iframe: { src: `${uiBase}/${rest}` } } });
}
}
return tabs;
}
/** Pairs the manifests with the emitted default export, by name. */
async function loadDefs(manifests: readonly Manifest[], entry: string): Promise<ModuleDef> {
const mod = (await import(pathToFileURL(entry).href)) as {
default?: { modules?: Record<string, ModuleDef["create"] | { create: ModuleDef["create"] }> };
};
const code = mod.default?.modules;
if (code === null || typeof code !== "object") {
throw new Error("the default export must be { modules: { <name>: { create } } }");
}
const defs = new Map<string, ModuleDef>();
for (const manifest of manifests) {
const found = code[manifest.name];
const create = typeof found === "function" ? found : found?.create;
if (typeof create !== "function") {
throw new Error(
`package.json names module '${manifest.name}' but the default export has no create() for it`,
);
}
defs.set(manifest.name, { manifest, create });
}
for (const def of defs.values()) {
def.children = def.manifest.children.map((ref) => {
const name = typeof ref === "string" ? ref : ref.keyed;
const child = defs.get(name);
if (!child)
throw new Error(
`module '${def.manifest.name}' lists child '${name}', which package.json does not declare`,
);
return child;
});
}
const root = defs.get(ROOT_MODULE);
if (!root)
throw new Error(`package.json#penguin.modules must include a module named '${ROOT_MODULE}'`);
if (!Object.values(root.manifest.provides).some((ref) => ref === MAIN_IFACE)) {
throw new Error(`module '${ROOT_MODULE}' must provide "${MAIN_IFACE}"`);
}
return root;
}
@Component()
export class WorkflowService implements Workflows {
@Use() private readonly paths!: Paths;
@Use() private readonly clock!: Clock;
@Use() private readonly log!: Log;
@Use() private readonly channels!: Channels;
@Use() private readonly members!: Members;
@Use() private readonly projects!: Projects;
@Use() private readonly hmr!: Hmr;
@Use() private readonly agents!: AgentIndex;
@Use() private readonly sessionIndex!: SessionIndex;
@Use() private readonly runner!: ScheduleTaskRunner;
@Use() private readonly sessions!: ScheduleSessionCreator;
private readonly loaded = new Map<string, Loaded>();
private readonly watchers = new Map<string, fs.FSWatcher>();
private readonly pending = new Map<string, NodeJS.Timeout>();
/** The load in flight per workflow: a load takes a compiler run, so two can overlap. */
private readonly loading = new Map<string, Promise<Loaded>>();
/** The revision the newest queued load will load, while one is queued (see reloadIfChanged). */
private readonly loadingRevision = new Map<string, string>();
/** Workflows whose folder is being deleted: the watcher schedules no reload for them. */
private readonly removing = new Set<string>();
private resources: ClassCtx["resources"] | null = null;
private disposed = false;
setup(ctx: ClassCtx) {
this.resources = ctx.resources;
ctx.effect(() => {
this.disposed = true;
for (const t of this.pending.values()) clearTimeout(t);
for (const w of this.watchers.values()) w.close();
for (const l of this.loaded.values()) l.tree?.dispose();
this.loaded.clear();
});
}
async list(projectId: string, agentId: string): Promise<WorkflowInfo[]> {
this.watch(projectId, agentId);
const folders = await listFolders(workflowsDir(this.paths.root, projectId, agentId));
const out: WorkflowInfo[] = [];
for (const folder of folders) {
const current = this.loaded.get(key(projectId, agentId, folder.id));
const fresh =
current && current.folder.revision === folder.revision
? current
: await this.load(projectId, agentId, folder);
out.push(this.info(folder.id, fresh));
}
// Folders that went away drop their instances.
const alive = new Set(folders.map((f) => key(projectId, agentId, f.id)));
for (const [k, l] of this.loaded) {
if (k.startsWith(`${projectId}/${agentId}/`) && !alive.has(k)) {
this.forget(projectId, agentId, l.folder.id);
}
}
return out;
}
async reload(projectId: string, agentId: string, workflowId: string): Promise<WorkflowInfo> {
const folder = await this.folder(projectId, agentId, workflowId);
return this.info(workflowId, await this.load(projectId, agentId, folder));
}
/**
* The watcher's reload: only when the content differs from what is loaded, or from what the
* load in flight is loading. An event is a hint, not an edit — Windows reports a `change` on
* a directory when a file in it is read or written (the workflow's own state, `.build/`, and
* a load's own reads of the folder), and reloading on those tore the tree down under the
* request that had just written its state, or loaded the same folder twice over. The
* revision is the content hash, so an edit always differs.
*/
private async reloadIfChanged(
projectId: string,
agentId: string,
workflowId: string,
): Promise<void> {
const folder = await this.folder(projectId, agentId, workflowId);
const k = key(projectId, agentId, workflowId);
const current = this.loading.has(k)
? this.loadingRevision.get(k)
: this.loaded.get(k)?.folder.revision;
if (current === folder.revision) return;
await this.load(projectId, agentId, folder);
}
async dispatch(
projectId: string,
agentId: string,
workflowId: string,
request: WorkflowRequest,
): Promise<WorkflowResponse> {
const loaded = await this.current(projectId, agentId, workflowId);
if (loaded.main === null) {
return { status: 503, body: { error: loaded.error ?? "workflow is not loaded" } };
}
return loaded.main.handle(request);
}
async uiFile(
projectId: string,
agentId: string,
workflowId: string,
rel: string,
): Promise<string | null> {
if (!isWorkflowId(workflowId)) return null;
// No default document: which page a tab shows is what its contribution says.
const file = rel;
if (!isSafeRelPath(file)) return null;
const abs = path.join(
workflowsDir(this.paths.root, projectId, agentId),
workflowId,
UI_DIR,
file,
);
try {
return (await fs.promises.stat(abs)).isFile() ? abs : null;
} catch {
return null;
}
}
history(projectId: string, agentId: string, workflowId: string): Promise<WorkflowVersion[]> {
if (!isWorkflowId(workflowId)) return Promise.resolve([]);
return listVersions(historyDir(this.paths.root, projectId, agentId), workflowId);
}
async rollback(
projectId: string,
agentId: string,
workflowId: string,
revision: string,
): Promise<WorkflowInfo> {
const folder = await this.folder(projectId, agentId, workflowId);
if (!/^[0-9a-f]{12}$/.test(revision)) throw new WorkflowNotFound("no such version");
const restored = await restoreVersion(
historyDir(this.paths.root, projectId, agentId),
folder,
revision,
);
if (!restored) throw new WorkflowNotFound("no such version");
return this.reload(projectId, agentId, workflowId);
}
async remove(projectId: string, agentId: string, workflowId: string): Promise<void> {
const folder = await this.folder(projectId, agentId, workflowId);
const k = key(projectId, agentId, workflowId);
// Nothing may write into the folder while it is deleted: a load writes `.build/`, and a
// file recreated there mid-delete fails the rm on Windows (ENOTEMPTY). Pending reloads are
// dropped, none is scheduled until the folder is gone, and one already running finishes.
this.removing.add(k);
try {
const t = this.pending.get(k);
if (t) clearTimeout(t);
this.pending.delete(k);
await this.loading.get(k)?.catch(() => undefined);
await fs.promises.rm(folder.dir, {
recursive: true,
force: true,
maxRetries: 5,
retryDelay: 100,
});
} finally {
this.removing.delete(k);
}
await fs.promises.rm(path.join(historyDir(this.paths.root, projectId, agentId), workflowId), {
recursive: true,
force: true,
});
this.forget(projectId, agentId, workflowId);
}
// ---- internals ------------------------------------------------------------------
private async folder(
projectId: string,
agentId: string,
workflowId: string,
): Promise<WorkflowFolder> {
if (!isWorkflowId(workflowId)) throw new WorkflowNotFound("no such workflow");
const dir = path.join(workflowsDir(this.paths.root, projectId, agentId), workflowId);
const folder = await readFolder(dir, workflowId);
if (!folder) throw new WorkflowNotFound("no such workflow");
return folder;
}
private async current(projectId: string, agentId: string, workflowId: string): Promise<Loaded> {
const folder = await this.folder(projectId, agentId, workflowId);
const k = key(projectId, agentId, workflowId);
const existing = this.loaded.get(k);
if (existing && existing.folder.revision === folder.revision) return existing;
return this.load(projectId, agentId, folder);
}
private info(id: string, l: Loaded): WorkflowInfo {
return {
id,
name: l.folder.pkg.name,
version: l.folder.pkg.version,
revision: l.folder.revision,
uiRev: l.folder.uiRev,
tabs: l.tabs,
loadedAt: l.loadedAt,
error: l.error,
hints: loadHints(l.folder.uiRev, l.tabs, l.error),
};
}
/**
* One load at a time per workflow. The watcher and a request can both ask while the
* compiler is still running for the last edit; the later one waits and then loads what
* is on disk by then, so versions are recorded in order and never concurrently.
*/
private load(projectId: string, agentId: string, folder: WorkflowFolder): Promise<Loaded> {
const k = key(projectId, agentId, folder.id);
const after = this.loading.get(k) ?? Promise.resolve();
const run = after
.catch(() => undefined)
.then(async () => {
const current = (await readFolder(folder.dir, folder.id)) ?? folder;
if (this.loading.get(k) === run) this.loadingRevision.set(k, current.revision);
return this.loadNow(projectId, agentId, current);
});
this.loading.set(k, run);
this.loadingRevision.set(k, folder.revision);
void run
.finally(() => {
if (this.loading.get(k) === run) {
this.loading.delete(k);
this.loadingRevision.delete(k);
}
})
.catch(() => undefined);
return run;
}
/** Boots the folder; on failure keeps the previous instance and reports the error. */
private async loadNow(
projectId: string,
agentId: string,
folder: WorkflowFolder,
): Promise<Loaded> {
const k = key(projectId, agentId, folder.id);
const previous = this.loaded.get(k);
const loadedAt = this.clock.now().toISOString();
let next: Loaded;
/** The tree this attempt booted, so a later throw can let it go instead of leaking it. */
let booted: { dispose: () => void } | null = null;
try {
const manifests = await readManifests(folder);
const tabs = contributedTabs(manifests, uiBase(projectId, agentId, folder.id));
const ts = await loadTypeScript(this.hmr.assetsDir());
// A new workflow takes its types from THIS harness; one that has them keeps them, and
// they are its side of the comparison below.
installHarnessTypes(
folder.dir,
table as unknown as IfaceTable,
[HOST_IFACE, MAIN_IFACE],
this.clock.now(),
);
const entry = compileWorkflow(ts, folder.dir, folder.revision);
const written = readHarnessTable(folder.dir);
if (typeof written === "string") throw new Error(written);
const fit = checkIfaces(
ts,
table as unknown as IfaceTable,
written,
ifaceQuestions(manifests),
);
// An interface the workflow names but holds no types for cannot be compared, and for a
// workflow that is a problem, not a pass.
const misfits = [
...fit.uncompared.map((q) => `${q}: not among the types this workflow was written against`),
...fit.problems,
];
if (misfits.length > 0) throw new Error(misfits.join("\n"));
const root = await loadDefs(manifests, entry);
const host = this.host(projectId, agentId, folder);
const tree = await bootModules(root, {
ifaces: table as unknown as IfaceTable,
resources: this.resources!,
published: {
ifaces: { [HOST_MODULE]: { host: hostDecl() }, [WEB_MODULE]: { web: webSlotsDecl() } },
values: { [HOST_MODULE]: { host }, [WEB_MODULE]: { web: {} } },
},
});
const alias = Object.entries(root.manifest.provides).find(
([, ref]) => ref === MAIN_IFACE,
)![0];
const main = tree.api<Loaded["main"]>(ROOT_MODULE, alias);
next = { folder, tree, main, tabs, loadedAt, error: null };
booted = tree;
// Recording the version is bookkeeping around a load that has already succeeded, so it
// cannot be inside the try that decides whether the load failed: a copy that ENOENTs on
// a file rewritten since it was hashed would hand the caller back the tree disposed
// just above, and leak the one that is actually serving.
previous?.tree?.dispose();
pruneBuilds(folder.dir, folder.revision);
try {
await recordVersion(
historyDir(this.paths.root, projectId, agentId),
folder,
this.clock.now(),
);
} catch (err) {
this.log.line(
`[workflows] ${k}@${folder.revision}: version not recorded: ${messageOf(err)}`,
);
}
} catch (err) {
const error = messageOf(err);
this.log.line(`[workflows] ${k}@${folder.revision}: ${error}`);
// A tree booted before the throw serves nobody: nothing holds it, so it is let go here
// rather than left behind. The previous instance keeps answering — it was never
// disposed, because that only happens once the new one is in place.
booted?.dispose();
next = {
folder,
tree: previous?.tree ?? null,
main: previous?.main ?? null,
tabs: previous?.tabs ?? [],
loadedAt: previous?.loadedAt ?? loadedAt,
error,
};
}
if (this.disposed) {
next.tree?.dispose();
return next;
}
writeLoadStatus(folder.dir, {
revision: folder.revision,
checkedAt: loadedAt,
error: next.error,
tabs: next.tabs.map((tab) => tab.key),
hints: loadHints(folder.uiRev, next.tabs, next.error),
});
this.loaded.set(k, next);
this.notify(projectId, agentId, this.info(folder.id, next));
return next;
}
private host(projectId: string, agentId: string, folder: WorkflowFolder) {
const service = this;
let state: unknown = null;
let stateRead: Promise<void> | null = null;
const ensureState = () => (stateRead ??= readState(folder.dir).then((s) => void (state = s)));
void ensureState();
return {
listAgents: () => service.agents.list(projectId).map((row) => ({ agentId: row.agentId })),
async createSession(opts?: { agentId?: string }) {
const target = opts?.agentId ?? agentId;
if (!service.agents.exists(projectId, target)) {
throw new Error(`createSession: this Project has no Agent '${target}'`);
}
// Unattended, like a scheduled run: allow-all, whatever the default preset asks.
return service.sessions.createSession({
projectId,
agentId: target,
approvalMode: "allow-all",
});
},
async run(sessionId: string, input: WorkflowInput[]) {
service.ownSession(projectId, sessionId, "run");
const texts = (Array.isArray(input) ? input : []).map((item) => item?.text);
if (texts.length === 0 || texts.some((t) => typeof t !== "string" || t === "")) {
throw new Error('run: input is a non-empty list of { text: "…" } items');
}
// Whatever the workflow stamped, the Agent hears the server, never a person.
return service.runner.startTask(
sessionId,
texts.map((text) => userText(text, "server")),
{ queueIfBusy: true },
);
},
sessionStatus: (sessionId: string) => {
service.ownSession(projectId, sessionId, "sessionStatus");
return service.runner.statusOf(sessionId);
},
getState: () => state,
async setState(next: unknown) {
await ensureState();
state = next ?? null;
await writeState(folder.dir, state);
},
log: (message: string) => service.log.line(`[workflow ${folder.id}] ${message}`),
};
}
/** A workflow reaches the Sessions of its own Project and no others. */
private ownSession(projectId: string, sessionId: string, call: string): void {
if (this.sessionIndex.findById(sessionId)?.projectId !== projectId) {
throw new Error(`${call}: this Project has no Session '${sessionId}'`);
}
}
/** Drops a workflow's instance and tells the Project's users it is gone. */
private forget(projectId: string, agentId: string, workflowId: string): void {
const k = key(projectId, agentId, workflowId);
const t = this.pending.get(k);
if (t) clearTimeout(t);
this.pending.delete(k);
this.loaded.get(k)?.tree?.dispose();
this.loaded.delete(k);
this.publish(projectId, { type: "workflow_removed", projectId, agentId, workflowId });
}
private notify(projectId: string, agentId: string, workflow: WorkflowInfo): void {
this.publish(projectId, { type: "workflow_updated", projectId, agentId, workflow });
}
/** Users of the Project (owner + members) hear about the change. */
private publish(projectId: string, event: ServerEvent): void {
const users = new Set(this.members.list(projectId).map((m) => m.userId));
const owner = this.projects.findById(projectId)?.ownerUserId;
if (owner) users.add(owner);
for (const userId of users) {
this.channels.peek(userChannelKey(userId))?.publish(event, "server_event");
}
}
private watch(projectId: string, agentId: string): void {
const k = `${projectId}/${agentId}`;
if (this.watchers.has(k) || this.disposed) return;
const declared = workflowsDir(this.paths.root, projectId, agentId);
if (!fs.existsSync(declared)) {
this.awaitFirstWorkflow(projectId, agentId, declared);
return;
}
// Watch the REAL path: libuv compares each event's filename against the string it was
// given, and a Windows short name (`RUNNER~1\…`, which is what os.tmpdir() hands back
// on a CI runner) never matches the long name the events carry — the mismatch trips an
// assertion inside fs-event.c and aborts the whole process, which no `try` can catch.
let dir: string;
try {
dir = fs.realpathSync.native(declared);
} catch {
dir = declared;
}
let watcher: fs.FSWatcher;
try {
watcher = fs.watch(dir, { recursive: true }, (_event, filename) => {
const segments = typeof filename === "string" ? filename.split(/[\\/]/) : [];
const id = segments[0];
// The workflow's own document is not code, and neither is the staging file a write
// of it goes through: `state.json` used to be the only name skipped, so every
// `setState` recompiled the workflow and tore down the tree that had just written it.
if (id === undefined || !isWorkflowId(id)) return;
if (filename?.endsWith(STATE_FILE) || (filename !== null && isTempName(filename))) return;
// The server's own emit (`.build/`), and any other dot-directory, is not an edit.
if (segments[1]?.startsWith(".")) return;
this.schedule(projectId, agentId, id);
});
} catch {
return;
}
watcher.on("error", () => {
watcher.close();
this.watchers.delete(k);
});
this.watchers.set(k, watcher);
}
/**
* An Agent with no `workflows/` folder yet: watch its own directory for that folder to
* appear. The Agent makes its first workflow with its file tools and nothing else — without
* this, nothing noticed until somebody listed the workflows again, and the Agent sat
* waiting for a load that was never going to happen.
*/
private awaitFirstWorkflow(projectId: string, agentId: string, declared: string): void {
const k = `${projectId}/${agentId}`;
const parent = path.dirname(declared);
let watcher: fs.FSWatcher;
try {
watcher = fs.watch(fs.realpathSync.native(parent), (_event, filename) => {
if (filename !== path.basename(declared) || !fs.existsSync(declared)) return;
watcher.close();
this.watchers.delete(k);
// The folder exists now: watch it properly, and load whatever is already inside.
void this.list(projectId, agentId).catch((err) =>
this.log.line(`[workflows] ${k}: ${messageOf(err)}`),
);
});
} catch {
return;
}
watcher.on("error", () => {
watcher.close();
this.watchers.delete(k);
});
this.watchers.set(k, watcher);
}
private schedule(projectId: string, agentId: string, workflowId: string): void {
const k = key(projectId, agentId, workflowId);
if (this.removing.has(k)) return;
const t = this.pending.get(k);
if (t) clearTimeout(t);
this.pending.set(
k,
setTimeout(() => {
this.pending.delete(k);
void this.reloadIfChanged(projectId, agentId, workflowId).catch((err) => {
if (err instanceof WorkflowNotFound) {
this.forget(projectId, agentId, workflowId);
return;
}
this.log.line(`[workflows] ${k}: ${messageOf(err)}`);
});
}, WATCH_SETTLE_MS),
);
}
}
export class WorkflowNotFound extends Error {}
/** Where a workflow's `ui/` is served from (./routes.ts). */
function uiBase(projectId: string, agentId: string, workflowId: string): string {
const [p, a, w] = [projectId, agentId, workflowId].map(encodeURIComponent);
return `/api/projects/${p}/agents/${a}/workflows/${w}/${UI_DIR}`;
}
/**
* The slots the host opens to a workflow tree, published under the platform module's own
* name: the slot declarations come from the platform's table (so a workflow's contribution
* has the shape a plugin's has), and only the opened ones are there — contributing to any
* other is `no-such-slot`. No members: there is nothing to require from it.
*/
function webSlotsDecl(): IfaceDecl {
const decl = (table as unknown as { ifaces: Record<string, IfaceDecl> }).ifaces[WEB_IFACE];
if (!decl) throw new Error(`${WEB_IFACE} is not in ifaces.json (regenerate it)`);
const slots: IfaceDecl["slots"] = {};
for (const name of OPEN_WEB_SLOTS) {
const slot = decl.slots[name];
if (!slot) throw new Error(`${WEB_IFACE} declares no slot '${name}' (regenerate ifaces.json)`);
slots[name] = slot;
}
return { name: "WorkflowWebSlots", methods: {}, slots };
}
/** The published `WorkflowHost` declaration, straight from the platform's interface table. */
function hostDecl(): IfaceDecl {
const decl = (table as unknown as { ifaces: Record<string, IfaceDecl> }).ifaces[HOST_IFACE];
if (!decl) throw new Error(`${HOST_IFACE} is not in ifaces.json (regenerate it)`);
return decl;
}