@pylonsync/functions 0.20.0 → 0.22.0

package/src/index.ts

@@ -21,6 +21,7 @@
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
 export { workflow } from "./workflows";
+export type { RawResponse, RawResponseInit } from "./response";
 export {
   agent,
   isAgentDefinition,
@@ -30,6 +31,7 @@ export {
 export type {
   AgentDefinition,
   AgentTool,
+  AgentToolRun,
   AgentCallArgs,
   AgentResult,
 } from "./agent";
@@ -80,6 +82,13 @@ export type {
   ShardTransfer,
   MemberRow,
   Workflows,
+  WorkflowRunSummary,
+  WorkflowRunStatus,
+  Audit,
+  AuditLog,
+  AuditEntry,
+  Agents,
+  AgentRunOptions,
   VectorSearchQuery,
   VectorSearchResult,
   SearchResult,
@@ -99,6 +108,7 @@ export type {
   // results (the DNS the end-customer must set).
   Domains,
   TenantDomainResult,
+  TenantDomainRecord,
   TenantDomainDns,
   DomainAvailability,
   DomainContact,

package/src/response.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { response } from "./response";
+
+describe("ctx.response", () => {
+  test("defaults to an empty 200", () => {
+    expect(response()).toEqual({ __pylonResponse: 1, status: 200, headers: {}, body: "" });
+  });
+
+  test("contentType sets the content-type header and replaces one in headers", () => {
+    const r = response({
+      contentType: "text/xml",
+      headers: { "Content-Type": "text/plain", "X-Id": "1" },
+      body: "<Response/>",
+    });
+    expect(r.headers).toEqual({ "X-Id": "1", "content-type": "text/xml" });
+    expect(r.body).toBe("<Response/>");
+  });
+
+  test("rejects out-of-range and non-integer status", () => {
+    for (const status of [99, 101, 600, 200.5, Number.NaN]) {
+      expect(() => response({ status })).toThrow("status");
+    }
+  });
+
+  test("rejects a body on 204", () => {
+    expect(() => response({ status: 204, body: "x" })).toThrow("cannot carry a body");
+    expect(response({ status: 204 }).status).toBe(204);
+  });
+
+  test("rejects header injection and invalid names", () => {
+    expect(() => response({ headers: { "X-A": "a\r\nSet-Cookie: x=1" } })).toThrow("control");
+    expect(() => response({ headers: { "X-A": "café" } })).toThrow("control");
+    expect(() => response({ headers: { "X A": "v" } })).toThrow("token");
+    expect(() => response({ contentType: "text/xml\r\nX: y" })).toThrow("control");
+  });
+
+  test("rejects headers the server owns, in any case", () => {
+    for (const name of ["Content-Length", "set-cookie", "Access-Control-Allow-Origin", "Connection"]) {
+      expect(() => response({ headers: { [name]: "v" } })).toThrow("set by the server");
+    }
+  });
+});

package/src/response.ts

@@ -0,0 +1,109 @@
+/**
+ * Raw HTTP responses from webhook actions.
+ *
+ * An action called through `/api/webhooks/<name>` normally answers with its
+ * return value as JSON and status 200. Returning `ctx.response(...)` sends
+ * the given status, content type, headers, and body instead. Every other
+ * route (`/api/fn/<name>`, `ctx.runAction`) returns the value as ordinary
+ * JSON data.
+ *
+ * The host enforces the same rules (crates/router/src/raw_response.rs), so
+ * a hand-built object cannot bypass them. The two header lists must stay in
+ * sync.
+ */
+
+/** What `ctx.response` accepts. */
+export interface RawResponseInit {
+  /** HTTP status, 200-599. Default 200. */
+  status?: number;
+  /** Shorthand for the `Content-Type` header. Default `text/plain; charset=utf-8`. */
+  contentType?: string;
+  /** Extra response headers. Values must be visible ASCII. */
+  headers?: Record<string, string>;
+  /** Response body. Default empty. Must be empty for 204, 205, and 304. */
+  body?: string;
+}
+
+/** The marked value an action returns. Build it with `ctx.response`. */
+export interface RawResponse {
+  readonly __pylonResponse: 1;
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+
+/** Header names the server sets itself. Compared lowercase. */
+const RESERVED_HEADERS = new Set([
+  "connection",
+  "content-length",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "set-cookie",
+  "permissions-policy",
+  "referrer-policy",
+  "x-content-type-options",
+  "x-frame-options",
+  "x-xss-protection",
+]);
+const RESERVED_HEADER_PREFIXES = ["access-control-"];
+
+const TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const VALUE_RE = /^[\t\x20-\x7e]*$/;
+
+function checkHeader(name: string, value: unknown): void {
+  if (!TOKEN_RE.test(name)) {
+    throw new Error(`ctx.response: header name ${JSON.stringify(name)} is not a valid HTTP token`);
+  }
+  if (typeof value !== "string") {
+    throw new Error(`ctx.response: header "${name}" must have a string value`);
+  }
+  if (!VALUE_RE.test(value)) {
+    throw new Error(
+      `ctx.response: header "${name}" has a value with control or non-ASCII characters`,
+    );
+  }
+  const lower = name.toLowerCase();
+  if (RESERVED_HEADERS.has(lower) || RESERVED_HEADER_PREFIXES.some((p) => lower.startsWith(p))) {
+    throw new Error(`ctx.response: header "${name}" is set by the server`);
+  }
+}
+
+/**
+ * Build a raw HTTP response for a webhook action to return.
+ *
+ * ```ts
+ * return ctx.response({ contentType: "text/xml", body: "<Response/>" });
+ * ```
+ */
+export function response(init: RawResponseInit = {}): RawResponse {
+  const status = init.status ?? 200;
+  if (!Number.isInteger(status) || status < 200 || status > 599) {
+    throw new Error(`ctx.response: status must be an integer from 200 to 599, got ${status}`);
+  }
+  const body = init.body ?? "";
+  if (typeof body !== "string") {
+    throw new Error("ctx.response: body must be a string");
+  }
+  if (body !== "" && (status === 204 || status === 205 || status === 304)) {
+    throw new Error(`ctx.response: status ${status} cannot carry a body`);
+  }
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(init.headers ?? {})) {
+    checkHeader(name, value);
+    headers[name] = value;
+  }
+  if (init.contentType !== undefined) {
+    checkHeader("Content-Type", init.contentType);
+    for (const name of Object.keys(headers)) {
+      if (name.toLowerCase() === "content-type") delete headers[name];
+    }
+    headers["content-type"] = init.contentType;
+  }
+  return { __pylonResponse: 1, status, headers, body };
+}

package/src/runtime-llm-stream.test.ts

@@ -184,3 +184,88 @@ test("llm.stream routes events by op_id, resolves on result; rooms.broadcast rou
   // 6. rooms.broadcast surfaced the host's verdict.
   expect(out.delivered).toBe(true);
 });
+
+const ABORT_SCRIPT = `
+import { buildLlm } from ${JSON.stringify(RUNTIME)};
+
+const llm = buildLlm("c_9");
+const seen = [];
+const controller = new AbortController();
+
+// Aborted before it starts: rejects without sending a frame.
+const early = await llm
+  .stream({ messages: [] }, () => {}, { signal: AbortSignal.abort("stopped") })
+  .then(() => "resolved", (e) => e.code);
+
+const running = llm
+  .stream({ messages: [] }, (e) => {
+    seen.push(e.text);
+    if (seen.length === 2) controller.abort(new Error("user pressed stop"));
+  }, { signal: controller.signal })
+  .then(() => ({ code: "resolved" }), (e) => ({ code: e.code, message: e.message }));
+
+const out = await running;
+// Give late host frames time to arrive; they must be ignored.
+await new Promise((r) => setTimeout(r, 200));
+console.error("RESULT " + JSON.stringify({ early, out, seen }));
+process.exit(0);
+`;
+
+test("an aborted llm.stream rejects with LLM_CANCELLED and sends llm_cancel", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-llm-abort-"));
+  const scriptPath = join(dir, "probe.ts");
+  writeFileSync(scriptPath, ABORT_SCRIPT);
+  const proc = Bun.spawn([process.execPath, scriptPath], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const reader = proc.stdout.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  const frames = () => parseFrames(buffered);
+  const readUntil = async (
+    pred: (fs: Record<string, unknown>[]) => boolean,
+  ) => {
+    while (!pred(frames())) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+    }
+  };
+  const send = (msg: Record<string, unknown>) =>
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+
+  await readUntil((fs) => fs.some((f) => f.type === "llm_stream"));
+  const streams = frames().filter((f) => f.type === "llm_stream");
+  // The pre-aborted stream never reached the host.
+  expect(streams).toHaveLength(1);
+  const opId = streams[0].op_id as string;
+
+  send({ type: "llm_event", call_id: "c_9", op_id: opId, event: { type: "text_delta", text: "a" } });
+  send({ type: "llm_event", call_id: "c_9", op_id: opId, event: { type: "text_delta", text: "b" } });
+  await proc.stdin.flush();
+  await readUntil((fs) => fs.some((f) => f.type === "llm_cancel"));
+  const cancel = frames().find((f) => f.type === "llm_cancel");
+  expect(cancel).toEqual({ type: "llm_cancel", call_id: "c_9", op_id: opId });
+
+  // Frames the host sent before it saw the cancel are dropped.
+  send({ type: "llm_event", call_id: "c_9", op_id: opId, event: { type: "text_delta", text: "c" } });
+  send({
+    type: "result",
+    call_id: "c_9",
+    op_id: opId,
+    data: { model: "m", content: [], stop_reason: "end_turn", usage: { input_tokens: 0, output_tokens: 0 } },
+  });
+  await proc.stdin.flush();
+
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+  const line = stderr.split("\n").find((l) => l.includes("RESULT "));
+  expect(line).toBeDefined();
+  const out = JSON.parse(line!.slice(line!.indexOf("RESULT ") + 7));
+  expect(out.early).toBe("LLM_CANCELLED");
+  expect(out.out.code).toBe("LLM_CANCELLED");
+  expect(out.out.message).toContain("user pressed stop");
+  expect(out.seen).toEqual(["a", "b"]);
+});

package/src/runtime.ts

@@ -33,6 +33,9 @@ import type {
   LlmStreamEvent,
   Rooms,
   Workflows,
+  WorkflowRunSummary,
+  Audit,
+  AuditEntry,
   Connections,
   Domains,
   TenantDomainResult,
@@ -46,13 +49,16 @@ import type {
   AuthInfo,
 } from "./types";
 import { normalizeAuthClaims } from "./auth";
+import { AGENT_INVOCATION, isAgentDefinition } from "./agent";
 import { makeRequireMember } from "./member";
+import { response } from "./response";
 import { isDevMode } from "./ssr-runtime";
 import { validateArgs } from "./validators";
 import { serverBundle } from "./server-bundle";
 import { fenceStdout } from "./stdout-fence";
 import { readdirSync } from "fs";
-import { join, basename } from "path";
+import { join, basename, resolve } from "path";
+import { pathToFileURL } from "url";
 
 // Bun runtime globals this process uses. The runtime executes under Bun, but
 // consuming apps type-check this source under node/DOM where the `Bun` global
@@ -80,6 +86,9 @@ interface CallMessage {
   fn_type: "query" | "mutation" | "action";
   args: Record<string, unknown>;
   auth: AuthInfo;
+  /** Present only when server code started this call with
+   *  `ctx.agents.run`; the host sets it, never a client. */
+  agent?: { context?: Record<string, unknown> | null };
 }
 
 interface ResultMessage {
@@ -388,19 +397,37 @@ function rpcDb(
  * is alive, however long it runs in total, while one whose provider
  * goes silent still trips the safety net. The host's own call deadline
  * remains the real upper bound.
+ *
+ * When `signal` aborts, the promise rejects with `LLM_CANCELLED` at
+ * once and an `llm_cancel` frame tells the host to drop the provider
+ * request. Events and the result that arrive after that are ignored.
  */
 function rpcStreaming(
   callId: string,
   msg: Record<string, unknown>,
   onEvent: (event: unknown) => void,
+  signal?: AbortSignal,
 ): Promise<unknown> {
   throwIfCancelled(callId);
+  if (signal?.aborted) return Promise.reject(streamCancelledError(signal));
   const opId = nextOpId(callId);
   return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      const pending = pendingRpcs.get(opId);
+      if (!pending) return;
+      pendingRpcs.delete(opId);
+      streamSinks.delete(opId);
+      clearTimeout(pending.timeout);
+      send({ type: "llm_cancel", call_id: callId, op_id: opId });
+      reject(streamCancelledError(signal));
+    };
     const fail = () => {
       if (pendingRpcs.has(opId)) {
         pendingRpcs.delete(opId);
         streamSinks.delete(opId);
+        signal?.removeEventListener("abort", onAbort);
+        // Nothing waits for this stream any more; stop the provider.
+        send({ type: "llm_cancel", call_id: callId, op_id: opId });
         reject(
           new Error(
             `RPC timed out after ${RPC_TIMEOUT_MS}ms with no stream activity (call_id=${callId} op_id=${opId})`,
@@ -411,14 +438,17 @@ function rpcStreaming(
     const entry = {
       resolve: (data: unknown) => {
         streamSinks.delete(opId);
+        signal?.removeEventListener("abort", onAbort);
         resolve(data);
       },
       reject: (err: Error) => {
         streamSinks.delete(opId);
+        signal?.removeEventListener("abort", onAbort);
         reject(err);
       },
       timeout: setTimeout(fail, RPC_TIMEOUT_MS),
     };
+    signal?.addEventListener("abort", onAbort, { once: true });
     pendingRpcs.set(opId, entry);
     streamSinks.set(opId, (event) => {
       clearTimeout(entry.timeout);
@@ -436,6 +466,17 @@ function rpcStreaming(
   });
 }
 
+function streamCancelledError(signal?: AbortSignal): Error {
+  const reason = signal?.reason;
+  const detail =
+    reason instanceof Error ? reason.message : reason ? String(reason) : "";
+  const err = new Error(
+    detail ? `ctx.llm.stream was cancelled: ${detail}` : "ctx.llm.stream was cancelled",
+  );
+  (err as { code?: string }).code = "LLM_CANCELLED";
+  return err;
+}
+
 /**
  * Tail of the in-order queue of legacy (call_id-keyed) RPCs, per call.
  * See {@link rpc} for why these serialize.
@@ -840,10 +881,10 @@ function buildScheduler(callId: string): Scheduler {
       return r.id || "";
     },
     async cancel(scheduleId) {
-      await rpc(callId, {
+      return (await rpc(callId, {
         type: "cancel_schedule",
         schedule_id: scheduleId,
-      });
+      })) as { cancelled: boolean };
     },
   };
 }
@@ -937,11 +978,13 @@ export function buildLlm(callId: string): Llm {
     async stream(
       request: LlmCompleteRequest,
       onEvent: (event: LlmStreamEvent) => void,
+      options?: { signal?: AbortSignal },
     ): Promise<LlmCompleteResponse> {
       return (await rpcStreaming(
         callId,
         { type: "llm_stream", request },
         (event) => onEvent(event as LlmStreamEvent),
+        options?.signal,
       )) as LlmCompleteResponse;
     },
 
@@ -985,15 +1028,47 @@ export function buildRooms(callId: string): Rooms {
  * takes it from there, so `start` returns the instance id immediately.
  * Uses the queued call_id-keyed `rpc` (the reply carries no op_id).
  */
+/** Build `ctx.audit` — round-trips `audit_op` frames to the host. */
+export function buildAudit(callId: string): Audit {
+  return {
+    async log(event) {
+      return (await rpc(callId, {
+        type: "audit_op",
+        op: "log",
+        action: event.action,
+        entity: event.entity ?? null,
+        entity_id: event.entityId ?? null,
+        subject: event.subject ?? null,
+        meta: event.meta ?? null,
+      })) as { id: string };
+    },
+    async list(filter) {
+      return (await rpc(callId, {
+        type: "audit_op",
+        op: "list",
+        action: filter?.action ?? null,
+        entity: filter?.entity ?? null,
+        entity_id: filter?.entityId ?? null,
+        actor: filter?.actor ?? null,
+        tenant: filter?.tenant ?? null,
+        before: filter?.before ?? null,
+        before_id: filter?.beforeId ?? null,
+        limit: filter?.limit ?? null,
+      })) as AuditEntry[];
+    },
+  };
+}
+
 export function buildWorkflows(callId: string): Workflows {
   return {
-    async start(name: string, input?: unknown) {
+    async start(name: string, input?: unknown, opts?: { key?: string }) {
       return (await rpc(callId, {
         type: "workflow_op",
         op: "start",
         name,
         input: input ?? null,
-      })) as { id: string };
+        key: opts?.key ?? null,
+      })) as { id: string; created: boolean };
     },
     async sendEvent(workflowId: string, event: string, data?: unknown) {
       return (await rpc(callId, {
@@ -1002,7 +1077,32 @@ export function buildWorkflows(callId: string): Workflows {
         workflow_id: workflowId,
         event,
         data: data ?? null,
-      })) as { delivered: boolean };
+      })) as { delivered: boolean; buffered: boolean };
+    },
+    async cancel(workflowId: string, opts?: { reason?: string }) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "cancel",
+        workflow_id: workflowId,
+        reason: opts?.reason ?? null,
+      })) as { cancelled: boolean };
+    },
+    async get(workflowId: string) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "get",
+        workflow_id: workflowId,
+      })) as WorkflowRunSummary | null;
+    },
+    async list(filter) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "list",
+        name: filter?.name ?? null,
+        key: filter?.key ?? null,
+        status: filter?.status ?? null,
+        limit: filter?.limit ?? null,
+      })) as WorkflowRunSummary[];
     },
   };
 }
@@ -1166,6 +1266,7 @@ function buildActionCtx(
     normalizedRequest = {
       method: String(r.method ?? ""),
       path: String(r.path ?? ""),
+      url: String(r.url ?? ""),
       headers: (r.headers as Record<string, string>) ?? {},
       rawBody: String(r.raw_body ?? r.rawBody ?? ""),
     };
@@ -1179,6 +1280,39 @@ function buildActionCtx(
     rooms,
     connections,
     workflows: buildWorkflows(callId),
+    audit: buildAudit(callId),
+    agents: {
+      async run(name, options) {
+        if (!options || typeof options.as?.userId !== "string") {
+          const err = new Error(
+            "ctx.agents.run needs as.userId: the user the run belongs to",
+          );
+          (err as { code?: string }).code = "INVALID_ARGS";
+          throw err;
+        }
+        const context = options.context;
+        if (
+          context !== undefined &&
+          context !== null &&
+          (typeof context !== "object" || Array.isArray(context))
+        ) {
+          const err = new Error("ctx.agents.run: context must be a plain object");
+          (err as { code?: string }).code = "INVALID_ARGS";
+          throw err;
+        }
+        const args: Record<string, unknown> = { input: options.input };
+        if (options.runId !== undefined) args.runId = options.runId;
+        if (options.title !== undefined) args.title = options.title;
+        return rpc(callId, {
+          type: "run_agent",
+          agent: name,
+          args,
+          user_id: options.as.userId,
+          admin: options.as.admin === true,
+          context: options.context ?? null,
+        }) as Promise<any>;
+      },
+    },
     domains: buildDomains(),
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
@@ -1214,6 +1348,7 @@ function buildActionCtx(
       }) as Promise<any[]>,
     ),
     request: normalizedRequest,
+    response,
   };
 }
 
@@ -1240,6 +1375,32 @@ registry.set("__pylonMemberLookup", {
 // Handler
 // ---------------------------------------------------------------------------
 
+/** Why a `ctx.agents.run` target may not run, or null when it may. */
+function agentInvocationRefusal(
+  def: FnDefinition,
+  rawAuth: AuthInfo,
+): { code: string; message: string } | null {
+  if (!isAgentDefinition(def)) {
+    return {
+      code: "AGENT_NOT_FOUND",
+      message: "ctx.agents.run can only run a function defined with agent()",
+    };
+  }
+  const auth = normalizeAuthClaims(rawAuth as unknown as Record<string, unknown>);
+  const mode = (def as { auth?: string }).auth ?? "user";
+  if (mode === "admin" && !auth.isAdmin) {
+    return {
+      code: "FORBIDDEN",
+      message:
+        "this agent is declared auth: \"admin\"; pass as: { userId, admin: true } from an admin caller",
+    };
+  }
+  if ((mode === "user" || mode === "admin") && !auth.userId) {
+    return { code: "UNAUTHENTICATED", message: "the agent needs a user" };
+  }
+  return null;
+}
+
 async function handleCall(msg: CallMessage): Promise<void> {
   const def = registry.get(msg.fn_name);
 
@@ -1268,6 +1429,18 @@ async function handleCall(msg: CallMessage): Promise<void> {
     return;
   }
 
+  // `ctx.agents.run`: the host checked who may start this and as whom.
+  // What is left is the target: it must be an agent, and the identity
+  // must satisfy the agent's own auth mode, exactly as an HTTP call to
+  // it would have to.
+  if (msg.agent) {
+    const refusal = agentInvocationRefusal(def, msg.auth);
+    if (refusal) {
+      send({ type: "error", call_id: msg.call_id, ...refusal });
+      return;
+    }
+  }
+
   if (def.args) {
     const { valid, errors } = validateArgs(msg.args, def.args);
     if (!valid) {
@@ -1372,6 +1545,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         rooms,
         connections,
         workflows: buildWorkflows(msg.call_id),
+        audit: buildAudit(msg.call_id),
         error(code, message) {
           const err = new Error(message);
           (err as any).code = code;
@@ -1404,6 +1578,13 @@ async function handleCall(msg: CallMessage): Promise<void> {
   // the switch so all three ctx shapes get it without threading another
   // parameter through each builder.
   (ctx as { signal?: AbortSignal }).signal = abort.signal;
+  if (msg.agent) {
+    // Read by the agent loop only. A symbol key, so nothing a client
+    // sends (args are plain JSON) can set it.
+    (ctx as unknown as Record<symbol, unknown>)[AGENT_INVOCATION] = {
+      context: msg.agent.context ?? null,
+    };
+  }
 
   try {
     const result = await def.handler(ctx, msg.args);
@@ -1496,19 +1677,29 @@ function firstStackFrame(err: unknown): string {
  */
 function listModuleFiles(
   dir: string,
+  opts: { reportMissing?: boolean } = {},
 ): Array<{ name: string; file: string; load: () => Promise<any> }> {
   let files: string[];
   try {
     files = readdirSync(dir).filter(
       (f) => f.endsWith(".ts") || f.endsWith(".js"),
     );
-  } catch {
+  } catch (err) {
+    // A missing default directory is normal (see above). Anything else, or
+    // a directory the app named explicitly, means its functions would
+    // silently not register, so say why.
+    const missing = (err as NodeJS.ErrnoException)?.code === "ENOENT";
+    if (!missing || opts.reportMissing) {
+      console.error(`[functions] Cannot read ${dir}:`, err);
+    }
     return [];
   }
   return files.map((file) => ({
     name: basename(file, file.endsWith(".ts") ? ".ts" : ".js"),
     file,
-    load: () => import(join(dir, file)),
+    // A file URL: a bare Windows path ("D:\\app\\x.ts") is not a module
+    // specifier everywhere.
+    load: () => import(pathToFileURL(join(dir, file)).href),
   }));
 }
 
@@ -1519,6 +1710,9 @@ async function main() {
   fenceStdout();
 
   const fnDir = process.argv[2] || "./functions";
+  // `resolve`, not `join`: an absolute PYLON_FUNCTIONS_DIR (including a
+  // Windows drive path) must be used as is, not appended to the cwd.
+  const fnDirIsDefault = fnDir === "functions" || fnDir === "./functions";
   const bundle = serverBundle();
 
   const fnSources = bundle
@@ -1527,7 +1721,9 @@ async function main() {
         file: `${name} (bundled)`,
         load: bundle.functions[name],
       }))
-    : listModuleFiles(join(process.cwd(), fnDir));
+    : listModuleFiles(resolve(process.cwd(), fnDir), {
+        reportMissing: !fnDirIsDefault,
+      });
 
   const { isAgentDefinition, AGENT_MARKER } = await import("./agent");
   let agentsPresent = false;
@@ -1585,7 +1781,7 @@ async function main() {
         file: `${name} (bundled)`,
         load: bundle.workflows[name],
       }))
-    : listModuleFiles(join(process.cwd(), "workflows"));
+    : listModuleFiles(resolve(process.cwd(), "workflows"));
   for (const { file, load } of wfSources) {
     try {
       const mod = await load();