A local-first multi-agent app development platform, built on PenguinHarness
/**
* Agent-scoped workflow routes, mounted at /api/projects/:projectId/agents/:agentId/workflows:
*
* GET / the Agent's workflows (loads any that changed on disk)
* POST /:id/reload re-import the folder now (the watcher does this on change too)
* GET /:id/history recorded versions, newest first
* POST /:id/rollback {revision} restore that version's files and reload
* DELETE /:id remove the folder and its recorded versions
* GET /:id/ui/* a file of the workflow's `ui/` (the pages its tabs name)
* * /:id/api/* handed to the workflow's WorkflowMain.handle: JSON by default, any
* content type when the handler names one (see respond)
*
* Every route requires access to the Project; the UI and api routes are what the
* workflow's own page (an iframe in the Web App, same-origin cookie auth) talks to.
*/
import fs from "node:fs/promises";
import path from "node:path";
import { Hono } from "hono";
import { Bind, Component, Use } from "@adelie/core/kernel";
import type { AppEnv } from "../auth/middleware.js";
import { HttpError } from "../http/errors.js";
import { requireValidId } from "../http/validate.js";
import type { Access } from "../mechanisms/projects.js";
import type { WorkflowRequest, WorkflowResponse, Workflows } from "../mechanisms/workflows.js";
import { WorkflowNotFound } from "./service.js";
const MIME: Record<string, string> = {
".html": "text/html; charset=utf-8",
".htm": "text/html; charset=utf-8",
".js": "text/javascript; charset=utf-8",
".mjs": "text/javascript; charset=utf-8",
".css": "text/css; charset=utf-8",
".json": "application/json; charset=utf-8",
".svg": "image/svg+xml",
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".gif": "image/gif",
".webp": "image/webp",
".ico": "image/x-icon",
".txt": "text/plain; charset=utf-8",
".map": "application/json; charset=utf-8",
".woff": "font/woff",
".woff2": "font/woff2",
};
/** The largest request body a workflow's handler is handed. */
const MAX_BODY_BYTES = 50 * 1024 * 1024;
/** Never shown to a workflow: they are the app's credentials, not the workflow's. */
const WITHHELD_REQUEST_HEADERS = new Set(["cookie", "authorization", "proxy-authorization"]);
/** Never taken from a workflow: the app's cookies, and what the transport decides for itself. */
const DROPPED_RESPONSE_HEADERS = new Set([
"set-cookie",
"connection",
"keep-alive",
"transfer-encoding",
"content-length",
]);
const tooLarge = () =>
new HttpError(
413,
"payload_too_large",
`A workflow request body is at most ${MAX_BODY_BYTES} bytes`,
);
const isJson = (contentType: string | undefined): boolean =>
contentType === undefined || /^application\/([\w.-]+\+)?json\b/i.test(contentType.trim());
function parseJson(bytes: Uint8Array): unknown {
try {
return JSON.parse(new TextDecoder().decode(bytes)) as unknown;
} catch {
return null;
}
}
function forwardedHeaders(headers: Headers): Record<string, string> {
const out: Record<string, string> = {};
headers.forEach((value, name) => {
if (!WITHHELD_REQUEST_HEADERS.has(name.toLowerCase())) out[name.toLowerCase()] = value;
});
return out;
}
/**
* JSON unless the handler says otherwise: a `content-type` header (or `bytes`) makes the
* response the handler's own — a page it proxies from a program it runs, an image, a
* download, a redirect — and `stream` sends it as it is produced. The same origin already serves the workflow's `ui/` files as
* written, so a handler that answers HTML is no wider than a file that is HTML.
*/
/**
* The body, refused the moment it goes past the cap rather than after it is in memory. A
* declared `content-length` is only a claim — a chunked request carries none at all — so the
* count that decides is the one taken while reading. Nothing larger than the cap is ever
* held, and the reader is cancelled so the sender is not left writing into a socket no one
* reads.
*/
async function readCapped(body: ReadableStream<Uint8Array> | null): Promise<Uint8Array> {
if (body === null) return new Uint8Array(0);
const reader = body.getReader();
const chunks: Uint8Array[] = [];
let size = 0;
try {
for (;;) {
const { done, value } = await reader.read();
if (done) break;
size += value.byteLength;
if (size > MAX_BODY_BYTES) throw tooLarge();
chunks.push(value);
}
} finally {
await reader.cancel().catch(() => undefined);
}
const out = new Uint8Array(size);
let at = 0;
for (const chunk of chunks) {
out.set(chunk, at);
at += chunk.byteLength;
}
return out;
}
function respond(response: WorkflowResponse): Response {
const status = response.status ?? 200;
const headers = new Headers();
for (const [name, value] of Object.entries(response.headers ?? {})) {
if (DROPPED_RESPONSE_HEADERS.has(name.toLowerCase())) continue;
// An illegal value (a CR/LF among them, which is why this throws) loses the header, not
// the whole answer: the handler still gets to reply.
try {
headers.set(name, value);
} catch {
continue;
}
}
// The statuses fetch forbids a body on: constructing a Response with one throws, which
// would reach the client as a bare 500 instead of the answer the handler meant.
const bodiless =
status === 101 ||
status === 103 ||
status === 204 ||
status === 205 ||
status === 304 ||
(status >= 300 && status < 400);
if (response.stream !== undefined && bodiless) {
// Nothing will read it, so whatever it holds open is released now.
const it = response.stream[Symbol.asyncIterator]();
void it.return?.(undefined);
}
if (response.stream !== undefined && !bodiless) {
if (!headers.has("content-type")) headers.set("content-type", "application/octet-stream");
return new Response(streamOf(response.stream), { status, headers });
}
if (response.bytes !== undefined) {
if (!headers.has("content-type")) headers.set("content-type", "application/octet-stream");
return new Response(bodiless ? null : response.bytes, { status, headers });
}
if (headers.has("content-type")) {
const text = typeof response.body === "string" ? response.body : "";
return new Response(bodiless ? null : text, { status, headers });
}
if (bodiless) return new Response(null, { status, headers });
headers.set("content-type", "application/json; charset=utf-8");
return new Response(JSON.stringify(response.body ?? null), { status, headers });
}
/**
* The handler's iterator as a response body: one chunk out per chunk yielded, pulled only as
* fast as the client reads. A client that disconnects cancels the stream, which ends the
* iteration — the generator's `finally` runs, and whatever it was relaying is let go.
*/
function streamOf(chunks: AsyncIterable<Uint8Array | string>): ReadableStream<Uint8Array> {
const encoder = new TextEncoder();
let iterator: AsyncIterator<Uint8Array | string> | null = null;
return new ReadableStream<Uint8Array>({
async pull(controller) {
iterator ??= chunks[Symbol.asyncIterator]();
try {
const next = await iterator.next();
if (next.done) controller.close();
else
controller.enqueue(
typeof next.value === "string" ? encoder.encode(next.value) : next.value,
);
} catch (err) {
controller.error(err);
}
},
async cancel() {
await iterator?.return?.();
},
});
}
export interface WorkflowRouteDeps {
access: Access;
workflows: Workflows;
}
export function workflowRoutes(deps: WorkflowRouteDeps): Hono<AppEnv> {
const app = new Hono<AppEnv>();
const scope = (c: {
req: { param(name: string): string | undefined };
var: AppEnv["Variables"];
}) => {
const projectId = requireValidId(c as never, "projectId");
const agentId = requireValidId(c as never, "agentId");
deps.access.requireProjectAccess(c.var.user.userId, projectId);
return { projectId, agentId };
};
const notFound = (err: unknown): never => {
if (err instanceof WorkflowNotFound) throw new HttpError(404, "not_found", err.message);
throw err;
};
app.get("/", async (c) => {
const { projectId, agentId } = scope(c);
return c.json({ workflows: await deps.workflows.list(projectId, agentId) });
});
app.post("/:id/reload", async (c) => {
const { projectId, agentId } = scope(c);
const workflow = await deps.workflows
.reload(projectId, agentId, c.req.param("id"))
.catch(notFound);
return c.json({ workflow });
});
app.get("/:id/history", async (c) => {
const { projectId, agentId } = scope(c);
return c.json({
versions: await deps.workflows.history(projectId, agentId, c.req.param("id")),
});
});
app.post("/:id/rollback", async (c) => {
const { projectId, agentId } = scope(c);
const body = (await c.req.json().catch(() => ({}))) as { revision?: unknown };
if (typeof body.revision !== "string")
throw new HttpError(400, "bad_request", "revision is required");
const workflow = await deps.workflows
.rollback(projectId, agentId, c.req.param("id"), body.revision)
.catch(notFound);
return c.json({ workflow });
});
app.delete("/:id", async (c) => {
const { projectId, agentId } = scope(c);
await deps.workflows.remove(projectId, agentId, c.req.param("id")).catch(notFound);
return c.body(null, 204);
});
app.get("/:id/ui/*", async (c) => {
const { projectId, agentId } = scope(c);
const id = c.req.param("id");
const rel = c.req.path.split(`/workflows/${id}/ui/`)[1] ?? "";
const file = await deps.workflows.uiFile(projectId, agentId, id, decodeURIComponent(rel));
if (file === null) throw new HttpError(404, "not_found", "No such file in the workflow's ui/.");
const body = await fs.readFile(file);
return c.body(body, 200, {
"content-type": MIME[path.extname(file).toLowerCase()] ?? "application/octet-stream",
"cache-control": "no-cache",
});
});
app.all("/:id/api/*", async (c) => {
const { projectId, agentId } = scope(c);
const id = c.req.param("id");
const sub = c.req.path.split(`/workflows/${id}/api`)[1] ?? "/";
const request: WorkflowRequest = {
method: c.req.method,
path: sub === "" ? "/" : sub,
query: c.req.query(),
headers: forwardedHeaders(c.req.raw.headers),
body: null,
};
if (c.req.method !== "GET" && c.req.method !== "HEAD") {
const declared = Number(c.req.header("content-length"));
if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) throw tooLarge();
const bytes = await readCapped(c.req.raw.body);
// JSON stays what it always was — parsed, and `null` when it does not parse. Anything
// else reaches the handler as the bytes that were sent.
if (isJson(c.req.header("content-type"))) request.body = parseJson(bytes);
else if (bytes.byteLength > 0) request.bytes = bytes;
}
const response = await deps.workflows.dispatch(projectId, agentId, id, request).catch(notFound);
return respond(response);
});
return app;
}
@Component({
contributes: {
"HttpModule.routes": [
{
id: "WorkflowsModule.routes",
prefix: "/api/projects/:projectId/agents/:agentId/workflows",
auth: "user",
order: 20,
},
],
},
})
export class WorkflowRoutes {
@Use() private readonly access!: Access;
@Use() private readonly workflows!: Workflows;
@Bind("WorkflowsModule.routes") routes!: Hono<AppEnv>;
setup() {
this.routes = workflowRoutes({ access: this.access, workflows: this.workflows });
}
}