@finalai/agents 0.8.0

package/dist/modules/cli/dev.mjs

@@ -0,0 +1,263 @@
+import {
+  DiagnosticSeverity,
+  hasErrors,
+  loadBundleInLocalIsolate
+} from "@finalai/agent-definition/compiler";
+import { ProviderRefKind } from "@finalai/agent-provider";
+import { openChannelSocket } from "@finalai/agent-provider/local-channel-socket";
+import { watch } from "node:fs";
+import { createServer } from "node:http";
+import * as z from "zod";
+import { compile } from "../compile.mjs";
+import { attachDevChannelSockets } from "./channel-socket.mjs";
+import { diagnosticLine } from "./output.mjs";
+const DEFAULT_DEV_PORT = 3e3;
+const localSecretsSchema = z.record(z.string(), z.string());
+const listeningAddressSchema = z.object({ port: z.number() });
+const parseLocalSecrets = (text) => {
+  if (text == null || text.length === 0) return {};
+  try {
+    const parsed = localSecretsSchema.safeParse(JSON.parse(text));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+};
+const readBody = async (request) => {
+  const chunks = [];
+  for await (const chunk of request) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks);
+};
+const toRequest = async (request, origin) => {
+  const method = request.method ?? "GET";
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (value == null) continue;
+    for (const item of Array.isArray(value) ? value : [value]) headers.append(name, item);
+  }
+  const body = method === "GET" || method === "HEAD" ? null : await readBody(request);
+  return new Request(new URL(request.url ?? "/", origin), {
+    method,
+    headers,
+    body: body == null || body.byteLength === 0 ? null : new Uint8Array(body)
+  });
+};
+const writeResponse = async (response, out) => {
+  out.statusCode = response.status;
+  response.headers.forEach((value, name) => out.setHeader(name, value));
+  out.end(Buffer.from(await response.arrayBuffer()));
+};
+const plain = (out, status, text) => {
+  out.statusCode = status;
+  out.setHeader("content-type", "text/plain; charset=utf-8");
+  out.end(`${text}
+`);
+};
+const splitPath = (pathname) => {
+  const match = /^\/([^/]+)(\/.*)?$/.exec(pathname);
+  if (match?.[1] == null) return null;
+  return { stem: decodeURIComponent(match[1]), path: match[2] ?? "/" };
+};
+const loadAgent = async (args) => {
+  const result = await compile({ dir: args.dir });
+  for (const item of result.diagnostics) {
+    (item.severity === DiagnosticSeverity.Error ? args.output.stderr : args.output.stdout)(
+      diagnosticLine(item)
+    );
+  }
+  if (hasErrors(result.diagnostics) || result.manifest == null) return null;
+  const bundle = result.bundle == null ? null : await loadBundleInLocalIsolate(
+    result.bundle.code,
+    args.fetch == null ? {} : { fetch: args.fetch }
+  );
+  const channels = /* @__PURE__ */ new Map();
+  const routes = [];
+  for (const binding of result.manifest.channels) {
+    if (binding.channel.kind !== ProviderRefKind.Bundle) continue;
+    channels.set(binding.key, binding.channel.export);
+    for (const route of result.bundle?.channelRoutes[binding.channel.export] ?? []) {
+      routes.push({ stem: binding.key, method: route.method, path: route.path });
+    }
+  }
+  return { manifest: result.manifest, bundle, channels, routes };
+};
+const startDevServer = async (args) => {
+  const { output } = args;
+  let agent = null;
+  let origin = "";
+  const printRoutes = () => {
+    if (agent == null) return;
+    if (agent.routes.length === 0) {
+      output.stdout("no custom channel routes (channels/*.ts) to serve");
+      return;
+    }
+    for (const route of agent.routes) {
+      output.stdout(`  ${route.method} ${origin}/${route.stem}${route.path}`);
+    }
+  };
+  const reload = async () => {
+    const next = await loadAgent({ dir: args.dir, output, fetch: args.fetch });
+    if (next == null) {
+      output.stderr(
+        agent == null ? "compile failed" : "compile failed; still serving the last bundle"
+      );
+      return false;
+    }
+    agent = next;
+    return true;
+  };
+  const handle = async (request, out) => {
+    const current = agent;
+    const target = splitPath(new URL(request.url ?? "/", origin).pathname);
+    const exportName = target == null ? null : current?.channels.get(target.stem) ?? null;
+    if (current?.bundle == null || target == null || exportName == null) {
+      plain(out, 404, "no custom channel route here");
+      return;
+    }
+    const allowed = new Set(current.manifest.secrets);
+    const stem = target.stem;
+    const response = await current.bundle.runtime.handleChannelRoute({
+      export: exportName,
+      request: await toRequest(request, origin),
+      path: target.path,
+      secrets: {
+        get: async (name) => {
+          if (!allowed.has(name)) {
+            output.stderr(`secrets.get(${JSON.stringify(name)}): not in the manifest's secrets`);
+            return null;
+          }
+          return args.secrets[name] ?? null;
+        }
+      },
+      receive: async (input) => {
+        output.stdout(`receive (${stem}): ${JSON.stringify(input)}`);
+        return { conversationId: "local" };
+      }
+    });
+    if (response == null) {
+      plain(out, 404, `no ${request.method ?? "GET"} ${target.path} route on channel ${stem}`);
+      return;
+    }
+    await writeResponse(response, out);
+  };
+  const server = createServer((request, out) => {
+    handle(request, out).catch((cause) => {
+      output.stderr(`route failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+      if (!out.headersSent) plain(out, 500, "route failed");
+      else out.end();
+    });
+  });
+  const channelSockets = attachDevChannelSockets({
+    server,
+    log: output.stderr,
+    open: async (incoming, signal) => {
+      const current = agent;
+      const target = splitPath(new URL(incoming.url ?? "/", origin).pathname);
+      const exportName = target == null ? null : current?.channels.get(target.stem);
+      if (current?.bundle == null || target == null || exportName == null)
+        return {
+          ok: false,
+          response: new Response("No custom channel socket route", { status: 404 })
+        };
+      const bundle = current.bundle;
+      const allowed = new Set(current.manifest.secrets);
+      const request = new Request(await toRequest(incoming, origin), { signal });
+      return openChannelSocket({
+        signal,
+        context: {
+          request,
+          secrets: {
+            get: async (name) => allowed.has(name) ? args.secrets[name] ?? null : null
+          },
+          receive: async (input) => {
+            output.stdout(`receive (${target.stem}): ${JSON.stringify(input)}`);
+            return { conversationId: "local" };
+          }
+        },
+        handler: async (ctx) => {
+          const response = await bundle.runtime.handleChannelSocket({
+            export: exportName,
+            path: target.path,
+            ...ctx
+          });
+          return response === null ? new Response("No custom channel socket route", { status: 404 }) : response;
+        }
+      });
+    }
+  });
+  const hostname = args.hostname ?? "localhost";
+  await new Promise((done, fail) => {
+    server.once("error", fail);
+    server.listen(args.port, hostname, () => {
+      server.off("error", fail);
+      done();
+    });
+  });
+  const port = listeningAddressSchema.safeParse(server.address()).data?.port ?? args.port;
+  origin = `http://${hostname}:${port}`;
+  await reload();
+  output.stdout(`serving ${args.dir} at ${origin}`);
+  printRoutes();
+  return {
+    url: origin,
+    reload: async () => {
+      const ok = await reload();
+      if (ok) printRoutes();
+      return ok;
+    },
+    close: async () => {
+      await channelSockets.close();
+      await new Promise((done) => {
+        server.closeAllConnections();
+        server.close(() => done());
+      });
+    }
+  };
+};
+const RECOMPILE_DEBOUNCE_MS = 150;
+const isBuildOutput = (path) => path.startsWith(".final") || path.split(/[\\/]/).includes("node_modules");
+const runDev = async (args) => {
+  const secrets = parseLocalSecrets(args.env["AGENT_LOCAL_SECRETS_JSON"]);
+  if (secrets == null) {
+    args.output.stderr("error: AGENT_LOCAL_SECRETS_JSON must be a JSON object of name \u2192 value");
+    return 2;
+  }
+  let server;
+  try {
+    server = await startDevServer({ dir: args.dir, port: args.port, secrets, output: args.output });
+  } catch (cause) {
+    args.output.stderr(`error: ${cause instanceof Error ? cause.message : String(cause)}`);
+    return 1;
+  }
+  let timer = null;
+  let watcher = null;
+  try {
+    watcher = watch(args.dir, { recursive: true }, (_event, file) => {
+      if (file != null && isBuildOutput(file)) return;
+      if (timer != null) clearTimeout(timer);
+      timer = setTimeout(() => {
+        args.output.stdout("change detected; recompiling");
+        void server.reload();
+      }, RECOMPILE_DEBOUNCE_MS);
+    });
+  } catch (cause) {
+    args.output.stderr(
+      `not watching for changes: ${cause instanceof Error ? cause.message : String(cause)}`
+    );
+  }
+  await new Promise((done) => {
+    if (args.signal.aborted) done();
+    else args.signal.addEventListener("abort", () => done(), { once: true });
+  });
+  if (timer != null) clearTimeout(timer);
+  watcher?.close();
+  await server.close();
+  return 0;
+};
+export {
+  DEFAULT_DEV_PORT,
+  parseLocalSecrets,
+  runDev,
+  startDevServer
+};
+//# sourceMappingURL=dev.mjs.map

package/dist/modules/cli/dev.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/cli/dev.ts"],
+  "sourcesContent": ["import {\n  DiagnosticSeverity,\n  hasErrors,\n  loadBundleInLocalIsolate,\n  type LoadedBundleIface,\n} from '@finalai/agent-definition/compiler';\nimport { ProviderRefKind, type AgentManifestIface, type JsonValue } from '@finalai/agent-provider';\nimport { openChannelSocket } from '@finalai/agent-provider/local-channel-socket';\nimport { watch, type FSWatcher } from 'node:fs';\nimport { createServer, type IncomingMessage, type ServerResponse } from 'node:http';\nimport * as z from 'zod';\nimport { compile } from \"../compile.mjs\";\nimport { attachDevChannelSockets } from \"./channel-socket.mjs\";\nimport { diagnosticLine, type OutputIface } from \"./output.mjs\";\n\n// `final agents dev`: serves the agent's custom channel\n// routes at http://localhost:<port>/<channel-stem><path>, the local\n// counterpart of https://agents.final.ai/<org>/<agent>/<channel-stem><path>.\n// Routes run in a local stand-in for the Worker isolate (a realm with Worker\n// globals only). There is no platform behind it: `receive` prints what the\n// route would deliver, and `secrets.get` reads AGENT_LOCAL_SECRETS_JSON,\n// limited to the manifest's secrets. Edits recompile and swap the bundle.\n\nexport const DEFAULT_DEV_PORT = 3000;\n\nconst localSecretsSchema = z.record(z.string(), z.string());\n\n// node:http's address() for a TCP listener.\nconst listeningAddressSchema = z.object({ port: z.number() });\n\nexport const parseLocalSecrets = (text: string | undefined): Record<string, string> | null => {\n  if (text == null || text.length === 0) return {};\n  try {\n    const parsed = localSecretsSchema.safeParse(JSON.parse(text));\n    return parsed.success ? parsed.data : null;\n  } catch {\n    return null;\n  }\n};\n\ninterface LoadedAgentIface {\n  manifest: AgentManifestIface;\n  bundle: LoadedBundleIface | null;\n  // Channel stem \u2192 bundle export, for the custom channels the bundle serves.\n  channels: Map<string, string>;\n  routes: { stem: string; method: string; path: string }[];\n}\n\nexport interface DevServerArgsIface {\n  dir: string;\n  port: number;\n  hostname?: string;\n  secrets: Record<string, string>;\n  output: OutputIface;\n  // The isolate realm's fetch (tests).\n  fetch?: typeof fetch;\n}\n\nexport interface DevServerIface {\n  url: string;\n  // Recompiles; false (and the previous bundle kept) when the compile fails.\n  reload(): Promise<boolean>;\n  close(): Promise<void>;\n}\n\nconst readBody = async (request: IncomingMessage): Promise<Buffer> => {\n  const chunks: Buffer[] = [];\n  for await (const chunk of request) chunks.push(Buffer.from(chunk));\n  return Buffer.concat(chunks);\n};\n\nconst toRequest = async (request: IncomingMessage, origin: string): Promise<Request> => {\n  const method = request.method ?? 'GET';\n  const headers = new Headers();\n  for (const [name, value] of Object.entries(request.headers)) {\n    if (value == null) continue;\n    for (const item of Array.isArray(value) ? value : [value]) headers.append(name, item);\n  }\n  const body = method === 'GET' || method === 'HEAD' ? null : await readBody(request);\n  return new Request(new URL(request.url ?? '/', origin), {\n    method,\n    headers,\n    body: body == null || body.byteLength === 0 ? null : new Uint8Array(body),\n  });\n};\n\nconst writeResponse = async (response: Response, out: ServerResponse): Promise<void> => {\n  out.statusCode = response.status;\n  response.headers.forEach((value, name) => out.setHeader(name, value));\n  out.end(Buffer.from(await response.arrayBuffer()));\n};\n\nconst plain = (out: ServerResponse, status: number, text: string): void => {\n  out.statusCode = status;\n  out.setHeader('content-type', 'text/plain; charset=utf-8');\n  out.end(`${text}\\n`);\n};\n\n// `/<stem><path>`: the first segment names the channel, the rest is its route path.\nconst splitPath = (pathname: string): { stem: string; path: string } | null => {\n  const match = /^\\/([^/]+)(\\/.*)?$/.exec(pathname);\n  if (match?.[1] == null) return null;\n  return { stem: decodeURIComponent(match[1]), path: match[2] ?? '/' };\n};\n\nconst loadAgent = async (args: {\n  dir: string;\n  output: OutputIface;\n  fetch?: typeof fetch;\n}): Promise<LoadedAgentIface | null> => {\n  const result = await compile({ dir: args.dir });\n  for (const item of result.diagnostics) {\n    (item.severity === DiagnosticSeverity.Error ? args.output.stderr : args.output.stdout)(\n      diagnosticLine(item),\n    );\n  }\n  if (hasErrors(result.diagnostics) || result.manifest == null) return null;\n  const bundle =\n    result.bundle == null\n      ? null\n      : await loadBundleInLocalIsolate(\n          result.bundle.code,\n          args.fetch == null ? {} : { fetch: args.fetch },\n        );\n  const channels = new Map<string, string>();\n  const routes: LoadedAgentIface['routes'] = [];\n  for (const binding of result.manifest.channels) {\n    if (binding.channel.kind !== ProviderRefKind.Bundle) continue;\n    channels.set(binding.key, binding.channel.export);\n    for (const route of result.bundle?.channelRoutes[binding.channel.export] ?? []) {\n      routes.push({ stem: binding.key, method: route.method, path: route.path });\n    }\n  }\n  return { manifest: result.manifest, bundle, channels, routes };\n};\n\nexport const startDevServer = async (args: DevServerArgsIface): Promise<DevServerIface> => {\n  const { output } = args;\n  let agent: LoadedAgentIface | null = null;\n  let origin = '';\n\n  const printRoutes = (): void => {\n    if (agent == null) return;\n    if (agent.routes.length === 0) {\n      output.stdout('no custom channel routes (channels/*.ts) to serve');\n      return;\n    }\n    for (const route of agent.routes) {\n      output.stdout(`  ${route.method} ${origin}/${route.stem}${route.path}`);\n    }\n  };\n\n  const reload = async (): Promise<boolean> => {\n    const next = await loadAgent({ dir: args.dir, output, fetch: args.fetch });\n    if (next == null) {\n      output.stderr(\n        agent == null ? 'compile failed' : 'compile failed; still serving the last bundle',\n      );\n      return false;\n    }\n    agent = next;\n    return true;\n  };\n\n  const handle = async (request: IncomingMessage, out: ServerResponse): Promise<void> => {\n    const current = agent;\n    const target = splitPath(new URL(request.url ?? '/', origin).pathname);\n    const exportName = target == null ? null : (current?.channels.get(target.stem) ?? null);\n    if (current?.bundle == null || target == null || exportName == null) {\n      plain(out, 404, 'no custom channel route here');\n      return;\n    }\n    const allowed = new Set(current.manifest.secrets);\n    const stem = target.stem;\n    const response = await current.bundle.runtime.handleChannelRoute({\n      export: exportName,\n      request: await toRequest(request, origin),\n      path: target.path,\n      secrets: {\n        get: async (name) => {\n          if (!allowed.has(name)) {\n            output.stderr(`secrets.get(${JSON.stringify(name)}): not in the manifest's secrets`);\n            return null;\n          }\n          return args.secrets[name] ?? null;\n        },\n      },\n      receive: async (input: JsonValue) => {\n        output.stdout(`receive (${stem}): ${JSON.stringify(input)}`);\n        return { conversationId: 'local' };\n      },\n    });\n    if (response == null) {\n      plain(out, 404, `no ${request.method ?? 'GET'} ${target.path} route on channel ${stem}`);\n      return;\n    }\n    await writeResponse(response, out);\n  };\n\n  const server = createServer((request, out) => {\n    handle(request, out).catch((cause: unknown) => {\n      output.stderr(`route failed: ${cause instanceof Error ? cause.message : String(cause)}`);\n      if (!out.headersSent) plain(out, 500, 'route failed');\n      else out.end();\n    });\n  });\n  const channelSockets = attachDevChannelSockets({\n    server,\n    log: output.stderr,\n    open: async (incoming, signal) => {\n      const current = agent;\n      const target = splitPath(new URL(incoming.url ?? '/', origin).pathname);\n      const exportName = target == null ? null : current?.channels.get(target.stem);\n      if (current?.bundle == null || target == null || exportName == null)\n        return {\n          ok: false,\n          response: new Response('No custom channel socket route', { status: 404 }),\n        };\n      const bundle = current.bundle;\n      const allowed = new Set(current.manifest.secrets);\n      const request = new Request(await toRequest(incoming, origin), { signal });\n      return openChannelSocket({\n        signal,\n        context: {\n          request,\n          secrets: {\n            get: async (name) => (allowed.has(name) ? (args.secrets[name] ?? null) : null),\n          },\n          receive: async (input) => {\n            output.stdout(`receive (${target.stem}): ${JSON.stringify(input)}`);\n            return { conversationId: 'local' };\n          },\n        },\n        handler: async (ctx) => {\n          const response = await bundle.runtime.handleChannelSocket({\n            export: exportName,\n            path: target.path,\n            ...ctx,\n          });\n          return response === null\n            ? new Response('No custom channel socket route', { status: 404 })\n            : response;\n        },\n      });\n    },\n  });\n  const hostname = args.hostname ?? 'localhost';\n  await new Promise<void>((done, fail) => {\n    server.once('error', fail);\n    server.listen(args.port, hostname, () => {\n      server.off('error', fail);\n      done();\n    });\n  });\n  const port = listeningAddressSchema.safeParse(server.address()).data?.port ?? args.port;\n  origin = `http://${hostname}:${port}`;\n  await reload();\n  output.stdout(`serving ${args.dir} at ${origin}`);\n  printRoutes();\n\n  return {\n    url: origin,\n    reload: async () => {\n      const ok = await reload();\n      if (ok) printRoutes();\n      return ok;\n    },\n    close: async () => {\n      await channelSockets.close();\n      await new Promise<void>((done) => {\n        server.closeAllConnections();\n        server.close(() => done());\n      });\n    },\n  };\n};\n\nconst RECOMPILE_DEBOUNCE_MS = 150;\n\nconst isBuildOutput = (path: string): boolean =>\n  path.startsWith('.final') || path.split(/[\\\\/]/).includes('node_modules');\n\nexport const runDev = async (args: {\n  dir: string;\n  port: number;\n  env: Record<string, string | undefined>;\n  output: OutputIface;\n  signal: AbortSignal;\n}): Promise<number> => {\n  const secrets = parseLocalSecrets(args.env['AGENT_LOCAL_SECRETS_JSON']);\n  if (secrets == null) {\n    args.output.stderr('error: AGENT_LOCAL_SECRETS_JSON must be a JSON object of name \u2192 value');\n    return 2;\n  }\n  let server: DevServerIface;\n  try {\n    server = await startDevServer({ dir: args.dir, port: args.port, secrets, output: args.output });\n  } catch (cause) {\n    args.output.stderr(`error: ${cause instanceof Error ? cause.message : String(cause)}`);\n    return 1;\n  }\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let watcher: FSWatcher | null = null;\n  try {\n    watcher = watch(args.dir, { recursive: true }, (_event, file) => {\n      if (file != null && isBuildOutput(file)) return;\n      if (timer != null) clearTimeout(timer);\n      timer = setTimeout(() => {\n        args.output.stdout('change detected; recompiling');\n        void server.reload();\n      }, RECOMPILE_DEBOUNCE_MS);\n    });\n  } catch (cause) {\n    args.output.stderr(\n      `not watching for changes: ${cause instanceof Error ? cause.message : String(cause)}`,\n    );\n  }\n  await new Promise<void>((done) => {\n    if (args.signal.aborted) done();\n    else args.signal.addEventListener('abort', () => done(), { once: true });\n  });\n  if (timer != null) clearTimeout(timer);\n  watcher?.close();\n  await server.close();\n  return 0;\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/cli/files.d.mts

@@ -0,0 +1,18 @@
+export type ListFiles = (dir: string) => Promise<string[]>;
+export declare const gitListFiles: ListFiles;
+export interface LocalFilesIface {
+    files: Record<string, string>;
+    problems: string[];
+}
+export declare const readLocalFiles: (args: {
+    dir: string;
+    listFiles: ListFiles;
+}) => Promise<LocalFilesIface>;
+export interface FileChangeIface {
+    path: string;
+    content: string | null;
+}
+export declare const fileChanges: (args: {
+    local: Record<string, string>;
+    remote: Record<string, string>;
+}) => FileChangeIface[];

package/dist/modules/cli/files.mjs

@@ -0,0 +1,66 @@
+import { execFile } from "node:child_process";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const gitListFiles = async (dir) => {
+  try {
+    const { stdout } = await run(
+      "git",
+      ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--deduplicate"],
+      { cwd: dir, maxBuffer: 64 * 1024 * 1024 }
+    );
+    return stdout.split("\0").filter((path) => path.length > 0);
+  } catch (cause) {
+    throw new Error(
+      `${dir} is not inside a git checkout (${cause instanceof Error ? cause.message.trim() : String(cause)})`,
+      { cause }
+    );
+  }
+};
+const isBuildOutput = (path) => path === ".final/compile" || path.startsWith(".final/compile/");
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const readLocalFiles = async (args) => {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const files = {};
+  const problems = [];
+  const root = await realpath(args.dir);
+  for (const path of (await args.listFiles(args.dir)).toSorted()) {
+    if (isBuildOutput(path)) continue;
+    let bytes;
+    try {
+      const localPath = join(root, ...path.split("/"));
+      const location = relative(root, await realpath(localPath));
+      if (isAbsolute(location) || location === ".." || location.startsWith("../") || (await lstat(localPath)).isSymbolicLink()) {
+        problems.push(`${path} is a symlink or resolves outside the agent directory`);
+        continue;
+      }
+      bytes = await readFile(localPath);
+    } catch (cause) {
+      if (isMissing(cause)) continue;
+      throw cause;
+    }
+    try {
+      files[path] = decoder.decode(bytes);
+    } catch {
+      problems.push(`${path} is not UTF-8 text; agent directories hold text files only`);
+    }
+  }
+  return { files, problems };
+};
+const fileChanges = (args) => {
+  const changes = [];
+  for (const [path, content] of Object.entries(args.local)) {
+    if (args.remote[path] !== content) changes.push({ path, content });
+  }
+  for (const path of Object.keys(args.remote)) {
+    if (!(path in args.local)) changes.push({ path, content: null });
+  }
+  return changes.toSorted((a, b) => a.path.localeCompare(b.path));
+};
+export {
+  fileChanges,
+  gitListFiles,
+  readLocalFiles
+};
+//# sourceMappingURL=files.mjs.map

package/dist/modules/cli/files.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/cli/files.ts"],
+  "sourcesContent": ["import { execFile } from 'node:child_process';\nimport { lstat, readFile, realpath } from 'node:fs/promises';\nimport { isAbsolute, join, relative } from 'node:path';\nimport { promisify } from 'node:util';\n\n// The files `final agents publish` commits: what git would commit from the\n// checkout (tracked plus untracked-but-not-ignored, so `.gitignore`d files\n// such as local env files never leave the machine), minus build output.\n\nexport type ListFiles = (dir: string) => Promise<string[]>;\n\nconst run = promisify(execFile);\n\n// Paths relative to `dir`, restricted to it.\nexport const gitListFiles: ListFiles = async (dir) => {\n  try {\n    const { stdout } = await run(\n      'git',\n      ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--deduplicate'],\n      { cwd: dir, maxBuffer: 64 * 1024 * 1024 },\n    );\n    return stdout.split('\\0').filter((path) => path.length > 0);\n  } catch (cause) {\n    throw new Error(\n      `${dir} is not inside a git checkout (${cause instanceof Error ? cause.message.trim() : String(cause)})`,\n      { cause },\n    );\n  }\n};\n\nconst isBuildOutput = (path: string): boolean =>\n  path === '.final/compile' || path.startsWith('.final/compile/');\n\nconst isMissing = (cause: unknown): boolean =>\n  cause instanceof Error && 'code' in cause && cause.code === 'ENOENT';\n\nexport interface LocalFilesIface {\n  files: Record<string, string>;\n  problems: string[];\n}\n\n// Text only: the definition API stores UTF-8 file contents.\nexport const readLocalFiles = async (args: {\n  dir: string;\n  listFiles: ListFiles;\n}): Promise<LocalFilesIface> => {\n  const decoder = new TextDecoder('utf-8', { fatal: true });\n  const files: Record<string, string> = {};\n  const problems: string[] = [];\n  const root = await realpath(args.dir);\n  for (const path of (await args.listFiles(args.dir)).toSorted()) {\n    if (isBuildOutput(path)) continue;\n    let bytes: Buffer;\n    try {\n      const localPath = join(root, ...path.split('/'));\n      const location = relative(root, await realpath(localPath));\n      if (\n        isAbsolute(location) ||\n        location === '..' ||\n        location.startsWith('../') ||\n        (await lstat(localPath)).isSymbolicLink()\n      ) {\n        problems.push(`${path} is a symlink or resolves outside the agent directory`);\n        continue;\n      }\n      bytes = await readFile(localPath);\n    } catch (cause) {\n      // Tracked but deleted in the working tree: not part of the commit.\n      if (isMissing(cause)) continue;\n      throw cause;\n    }\n    try {\n      files[path] = decoder.decode(bytes);\n    } catch {\n      problems.push(`${path} is not UTF-8 text; agent directories hold text files only`);\n    }\n  }\n  return { files, problems };\n};\n\nexport interface FileChangeIface {\n  path: string;\n  // Null deletes the file.\n  content: string | null;\n}\n\nexport const fileChanges = (args: {\n  local: Record<string, string>;\n  remote: Record<string, string>;\n}): FileChangeIface[] => {\n  const changes: FileChangeIface[] = [];\n  for (const [path, content] of Object.entries(args.local)) {\n    if (args.remote[path] !== content) changes.push({ path, content });\n  }\n  for (const path of Object.keys(args.remote)) {\n    if (!(path in args.local)) changes.push({ path, content: null });\n  }\n  return changes.toSorted((a, b) => a.path.localeCompare(b.path));\n};\n"],
+  "mappings": "AAAA,SAAS,gBAAgB;AACzB,SAAS,OAAO,UAAU,gBAAgB;AAC1C,SAAS,YAAY,MAAM,gBAAgB;AAC3C,SAAS,iBAAiB;AAQ1B,MAAM,MAAM,UAAU,QAAQ;AAGvB,MAAM,eAA0B,OAAO,QAAQ;AACpD,MAAI;AACF,UAAM,EAAE,OAAO,IAAI,MAAM;AAAA,MACvB;AAAA,MACA,CAAC,YAAY,MAAM,YAAY,YAAY,sBAAsB,eAAe;AAAA,MAChF,EAAE,KAAK,KAAK,WAAW,KAAK,OAAO,KAAK;AAAA,IAC1C;AACA,WAAO,OAAO,MAAM,IAAI,EAAE,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC;AAAA,EAC5D,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,GAAG,GAAG,kCAAkC,iBAAiB,QAAQ,MAAM,QAAQ,KAAK,IAAI,OAAO,KAAK,CAAC;AAAA,MACrG,EAAE,MAAM;AAAA,IACV;AAAA,EACF;AACF;AAEA,MAAM,gBAAgB,CAAC,SACrB,SAAS,oBAAoB,KAAK,WAAW,iBAAiB;AAEhE,MAAM,YAAY,CAAC,UACjB,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS;AAQvD,MAAM,iBAAiB,OAAO,SAGL;AAC9B,QAAM,UAAU,IAAI,YAAY,SAAS,EAAE,OAAO,KAAK,CAAC;AACxD,QAAM,QAAgC,CAAC;AACvC,QAAM,WAAqB,CAAC;AAC5B,QAAM,OAAO,MAAM,SAAS,KAAK,GAAG;AACpC,aAAW,SAAS,MAAM,KAAK,UAAU,KAAK,GAAG,GAAG,SAAS,GAAG;AAC9D,QAAI,cAAc,IAAI,EAAG;AACzB,QAAI;AACJ,QAAI;AACF,YAAM,YAAY,KAAK,MAAM,GAAG,KAAK,MAAM,GAAG,CAAC;AAC/C,YAAM,WAAW,SAAS,MAAM,MAAM,SAAS,SAAS,CAAC;AACzD,UACE,WAAW,QAAQ,KACnB,aAAa,QACb,SAAS,WAAW,KAAK,MACxB,MAAM,MAAM,SAAS,GAAG,eAAe,GACxC;AACA,iBAAS,KAAK,GAAG,IAAI,uDAAuD;AAC5E;AAAA,MACF;AACA,cAAQ,MAAM,SAAS,SAAS;AAAA,IAClC,SAAS,OAAO;AAEd,UAAI,UAAU,KAAK,EAAG;AACtB,YAAM;AAAA,IACR;AACA,QAAI;AACF,YAAM,IAAI,IAAI,QAAQ,OAAO,KAAK;AAAA,IACpC,QAAQ;AACN,eAAS,KAAK,GAAG,IAAI,4DAA4D;AAAA,IACnF;AAAA,EACF;AACA,SAAO,EAAE,OAAO,SAAS;AAC3B;AAQO,MAAM,cAAc,CAAC,SAGH;AACvB,QAAM,UAA6B,CAAC;AACpC,aAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,KAAK,KAAK,GAAG;AACxD,QAAI,KAAK,OAAO,IAAI,MAAM,QAAS,SAAQ,KAAK,EAAE,MAAM,QAAQ,CAAC;AAAA,EACnE;AACA,aAAW,QAAQ,OAAO,KAAK,KAAK,MAAM,GAAG;AAC3C,QAAI,EAAE,QAAQ,KAAK,OAAQ,SAAQ,KAAK,EAAE,MAAM,SAAS,KAAK,CAAC;AAAA,EACjE;AACA,SAAO,QAAQ,SAAS,CAAC,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC;AAChE;",
+  "names": []
+}

package/dist/modules/cli/harness-descriptions.d.mts

@@ -0,0 +1,20 @@
+import { type HarnessDescriptionContextIface } from '@finalai/agent-definition/compiler';
+import { type HarnessDescriptionIface, type ProviderRef } from '@finalai/agent-provider';
+import type { AgentClientIface } from "../agent-client/client.mjs";
+import { type ProviderEntryIface } from "../agent-client/index.mjs";
+import { type OutputIface } from "./output.mjs";
+export declare const descriptionOf: (entry: ProviderEntryIface) => HarnessDescriptionIface | null;
+export declare const createInstalledHarnessDescriptions: (args: {
+    client: AgentClientIface;
+    output: OutputIface;
+}) => ((ref: ProviderRef) => Promise<HarnessDescriptionIface | null>);
+export declare const describeBundleHarness: (args: {
+    exportName: string;
+    bundle: {
+        code: string;
+    };
+}) => Promise<HarnessDescriptionIface | null>;
+export declare const createHarnessDescriptions: (args: {
+    client: AgentClientIface | null;
+    output: OutputIface;
+}) => ((ref: ProviderRef, context: HarnessDescriptionContextIface) => Promise<HarnessDescriptionIface | null>);

package/dist/modules/cli/harness-descriptions.mjs

@@ -0,0 +1,70 @@
+import {
+  loadBundleInLocalIsolate
+} from "@finalai/agent-definition/compiler";
+import {
+  formatProviderRef,
+  harnessDescriptionSchema,
+  jsonObjectSchema,
+  ProviderRefKind
+} from "@finalai/agent-provider";
+import { ProviderKind } from "../agent-client/index.mjs";
+import { errorLines } from "./output.mjs";
+const wireRefText = (entry) => `${String(entry.ref.kind)}:${entry.ref.specifier ?? entry.ref.export ?? ""}`;
+const descriptionOf = (entry) => {
+  const capabilities = jsonObjectSchema.safeParse(entry.capabilities);
+  if (!capabilities.success || entry.configSchema == null) return null;
+  const parsed = harnessDescriptionSchema.safeParse({
+    ...capabilities.data,
+    configSchema: entry.configSchema
+  });
+  return parsed.success ? parsed.data : null;
+};
+const createInstalledHarnessDescriptions = (args) => {
+  return async (ref) => {
+    let providers;
+    try {
+      providers = await args.client.providers.list();
+    } catch (cause) {
+      for (const line of errorLines(cause)) args.output.stderr(`providers: ${line}`);
+      return null;
+    }
+    const wanted = formatProviderRef(ref);
+    const entry = providers.find(
+      (candidate) => candidate.kind === ProviderKind.Harness && wireRefText(candidate) === wanted
+    );
+    return entry == null ? null : descriptionOf(entry);
+  };
+};
+const describeBundleHarness = async (args) => {
+  const loaded = await loadBundleInLocalIsolate(args.bundle.code);
+  const described = await loaded.callExportMethod({
+    exportName: args.exportName,
+    method: "describe",
+    args: []
+  });
+  return harnessDescriptionSchema.safeParse(described).data ?? null;
+};
+const createHarnessDescriptions = (args) => {
+  const installed = args.client == null ? null : createInstalledHarnessDescriptions({ client: args.client, output: args.output });
+  return async (ref, context) => {
+    if (ref.kind === ProviderRefKind.Bundle) {
+      if (context.bundle == null) return null;
+      try {
+        return await describeBundleHarness({ exportName: ref.export, bundle: context.bundle });
+      } catch (cause) {
+        args.output.stderr(
+          `describe ${ref.export}: ${cause instanceof Error ? cause.message : String(cause)}`
+        );
+        return null;
+      }
+    }
+    return installed == null ? null : installed(ref);
+  };
+};
+export {
+  createHarnessDescriptions,
+  createInstalledHarnessDescriptions,
+  describeBundleHarness,
+  descriptionOf
+};
+//# sourceMappingURL=harness-descriptions.mjs.map

package/dist/modules/cli/harness-descriptions.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/cli/harness-descriptions.ts"],
+  "sourcesContent": ["import {\n  loadBundleInLocalIsolate,\n  type HarnessDescriptionContextIface,\n} from '@finalai/agent-definition/compiler';\nimport {\n  formatProviderRef,\n  harnessDescriptionSchema,\n  jsonObjectSchema,\n  ProviderRefKind,\n  type HarnessDescriptionIface,\n  type ProviderRef,\n} from '@finalai/agent-provider';\nimport type { AgentClientIface } from \"../agent-client/client.mjs\";\nimport { ProviderKind, type ProviderEntryIface } from \"../agent-client/index.mjs\";\nimport { errorLines, type OutputIface } from \"./output.mjs\";\n\n// The compatibility report checks against the harnesses installed on the\n// platform: `GET /v1/providers` carries each harness's description (its\n// config schema and capabilities).\n\nconst wireRefText = (entry: ProviderEntryIface): string =>\n  `${String(entry.ref.kind)}:${entry.ref.specifier ?? entry.ref.export ?? ''}`;\n\nexport const descriptionOf = (entry: ProviderEntryIface): HarnessDescriptionIface | null => {\n  const capabilities = jsonObjectSchema.safeParse(entry.capabilities);\n  if (!capabilities.success || entry.configSchema == null) return null;\n  const parsed = harnessDescriptionSchema.safeParse({\n    ...capabilities.data,\n    configSchema: entry.configSchema,\n  });\n  return parsed.success ? parsed.data : null;\n};\n\nexport const createInstalledHarnessDescriptions = (args: {\n  client: AgentClientIface;\n  output: OutputIface;\n}): ((ref: ProviderRef) => Promise<HarnessDescriptionIface | null>) => {\n  return async (ref) => {\n    let providers: ProviderEntryIface[];\n    try {\n      providers = await args.client.providers.list();\n    } catch (cause) {\n      for (const line of errorLines(cause)) args.output.stderr(`providers: ${line}`);\n      return null;\n    }\n    const wanted = formatProviderRef(ref);\n    const entry = providers.find(\n      (candidate) => candidate.kind === ProviderKind.Harness && wireRefText(candidate) === wanted,\n    );\n    return entry == null ? null : descriptionOf(entry);\n  };\n};\n\n// A harness declared in the bundle is described by running its\n// own describe in the local isolate, so the report needs no platform.\nexport const describeBundleHarness = async (args: {\n  exportName: string;\n  bundle: { code: string };\n}): Promise<HarnessDescriptionIface | null> => {\n  const loaded = await loadBundleInLocalIsolate(args.bundle.code);\n  const described = await loaded.callExportMethod({\n    exportName: args.exportName,\n    method: 'describe',\n    args: [],\n  });\n  return harnessDescriptionSchema.safeParse(described).data ?? null;\n};\n\nexport const createHarnessDescriptions = (args: {\n  client: AgentClientIface | null;\n  output: OutputIface;\n}): ((\n  ref: ProviderRef,\n  context: HarnessDescriptionContextIface,\n) => Promise<HarnessDescriptionIface | null>) => {\n  const installed =\n    args.client == null\n      ? null\n      : createInstalledHarnessDescriptions({ client: args.client, output: args.output });\n  return async (ref, context) => {\n    if (ref.kind === ProviderRefKind.Bundle) {\n      if (context.bundle == null) return null;\n      try {\n        return await describeBundleHarness({ exportName: ref.export, bundle: context.bundle });\n      } catch (cause) {\n        args.output.stderr(\n          `describe ${ref.export}: ${cause instanceof Error ? cause.message : String(cause)}`,\n        );\n        return null;\n      }\n    }\n    return installed == null ? null : installed(ref);\n  };\n};\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AAEP,SAAS,oBAA6C;AACtD,SAAS,kBAAoC;AAM7C,MAAM,cAAc,CAAC,UACnB,GAAG,OAAO,MAAM,IAAI,IAAI,CAAC,IAAI,MAAM,IAAI,aAAa,MAAM,IAAI,UAAU,EAAE;AAErE,MAAM,gBAAgB,CAAC,UAA8D;AAC1F,QAAM,eAAe,iBAAiB,UAAU,MAAM,YAAY;AAClE,MAAI,CAAC,aAAa,WAAW,MAAM,gBAAgB,KAAM,QAAO;AAChE,QAAM,SAAS,yBAAyB,UAAU;AAAA,IAChD,GAAG,aAAa;AAAA,IAChB,cAAc,MAAM;AAAA,EACtB,CAAC;AACD,SAAO,OAAO,UAAU,OAAO,OAAO;AACxC;AAEO,MAAM,qCAAqC,CAAC,SAGoB;AACrE,SAAO,OAAO,QAAQ;AACpB,QAAI;AACJ,QAAI;AACF,kBAAY,MAAM,KAAK,OAAO,UAAU,KAAK;AAAA,IAC/C,SAAS,OAAO;AACd,iBAAW,QAAQ,WAAW,KAAK,EAAG,MAAK,OAAO,OAAO,cAAc,IAAI,EAAE;AAC7E,aAAO;AAAA,IACT;AACA,UAAM,SAAS,kBAAkB,GAAG;AACpC,UAAM,QAAQ,UAAU;AAAA,MACtB,CAAC,cAAc,UAAU,SAAS,aAAa,WAAW,YAAY,SAAS,MAAM;AAAA,IACvF;AACA,WAAO,SAAS,OAAO,OAAO,cAAc,KAAK;AAAA,EACnD;AACF;AAIO,MAAM,wBAAwB,OAAO,SAGG;AAC7C,QAAM,SAAS,MAAM,yBAAyB,KAAK,OAAO,IAAI;AAC9D,QAAM,YAAY,MAAM,OAAO,iBAAiB;AAAA,IAC9C,YAAY,KAAK;AAAA,IACjB,QAAQ;AAAA,IACR,MAAM,CAAC;AAAA,EACT,CAAC;AACD,SAAO,yBAAyB,UAAU,SAAS,EAAE,QAAQ;AAC/D;AAEO,MAAM,4BAA4B,CAAC,SAMO;AAC/C,QAAM,YACJ,KAAK,UAAU,OACX,OACA,mCAAmC,EAAE,QAAQ,KAAK,QAAQ,QAAQ,KAAK,OAAO,CAAC;AACrF,SAAO,OAAO,KAAK,YAAY;AAC7B,QAAI,IAAI,SAAS,gBAAgB,QAAQ;AACvC,UAAI,QAAQ,UAAU,KAAM,QAAO;AACnC,UAAI;AACF,eAAO,MAAM,sBAAsB,EAAE,YAAY,IAAI,QAAQ,QAAQ,QAAQ,OAAO,CAAC;AAAA,MACvF,SAAS,OAAO;AACd,aAAK,OAAO;AAAA,UACV,YAAY,IAAI,MAAM,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAAA,QACnF;AACA,eAAO;AAAA,MACT;AAAA,IACF;AACA,WAAO,aAAa,OAAO,OAAO,UAAU,GAAG;AAAA,EACjD;AACF;",
+  "names": []
+}

package/dist/modules/cli/main.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import 'zod/compile';

package/dist/modules/cli/main.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import "zod/compile";
+import { runAgentsCommand } from "./cli.mjs";
+const stop = new AbortController();
+for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => stop.abort());
+process.exit(
+  await runAgentsCommand({
+    argv: process.argv.slice(2),
+    env: process.env,
+    cwd: process.cwd(),
+    signal: stop.signal,
+    output: {
+      stdout: (line) => process.stdout.write(`${line}
+`),
+      stderr: (line) => process.stderr.write(`${line}
+`)
+    }
+  })
+);
+//# sourceMappingURL=main.mjs.map

package/dist/modules/cli/main.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/cli/main.ts"],
+  "sourcesContent": ["#!/usr/bin/env node\nimport 'zod/compile';\nimport { runAgentsCommand } from \"./cli.mjs\";\n\n// `final-agents build|dev|publish|conformance`: `final agents \u2026` until a general `final` CLI exists.\n\nconst stop = new AbortController();\nfor (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => stop.abort());\n\nprocess.exit(\n  await runAgentsCommand({\n    argv: process.argv.slice(2),\n    env: process.env,\n    cwd: process.cwd(),\n    signal: stop.signal,\n    output: {\n      stdout: (line) => process.stdout.write(`${line}\\n`),\n      stderr: (line) => process.stderr.write(`${line}\\n`),\n    },\n  }),\n);\n"],
+  "mappings": ";AACA,OAAO;AACP,SAAS,wBAAwB;AAIjC,MAAM,OAAO,IAAI,gBAAgB;AACjC,WAAW,UAAU,CAAC,UAAU,SAAS,EAAY,SAAQ,KAAK,QAAQ,MAAM,KAAK,MAAM,CAAC;AAE5F,QAAQ;AAAA,EACN,MAAM,iBAAiB;AAAA,IACrB,MAAM,QAAQ,KAAK,MAAM,CAAC;AAAA,IAC1B,KAAK,QAAQ;AAAA,IACb,KAAK,QAAQ,IAAI;AAAA,IACjB,QAAQ,KAAK;AAAA,IACb,QAAQ;AAAA,MACN,QAAQ,CAAC,SAAS,QAAQ,OAAO,MAAM,GAAG,IAAI;AAAA,CAAI;AAAA,MAClD,QAAQ,CAAC,SAAS,QAAQ,OAAO,MAAM,GAAG,IAAI;AAAA,CAAI;AAAA,IACpD;AAAA,EACF,CAAC;AACH;",
+  "names": []
+}

package/dist/modules/cli/output.d.mts

@@ -0,0 +1,14 @@
+import type { CompatibilityReportIface } from '@finalai/agent-definition/compatibility';
+import type { DiagnosticIface } from '@finalai/agent-definition/compiler';
+import { type AgentManifestIface } from '@finalai/agent-provider';
+import { type PublishResultIface } from "../agent-client/index.mjs";
+export interface OutputIface {
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+}
+export declare const manifestSummaryLines: (manifest: AgentManifestIface) => string[];
+export declare const hookLines: (manifest: AgentManifestIface) => string[];
+export declare const reportLines: (report: CompatibilityReportIface) => string[];
+export declare const diagnosticLine: (item: DiagnosticIface) => string;
+export declare const errorLines: (cause: unknown) => string[];
+export declare const publishResultLines: (result: PublishResultIface) => string[];