@finalai/agent-definition 0.1.0

package/dist/modules/compiler/diagnostics.d.mts

@@ -0,0 +1,40 @@
+export declare enum DiagnosticSeverity {
+    Error = "error",
+    Warning = "warning",
+    Note = "note"
+}
+export declare enum DiagnosticCode {
+    Input = "input",
+    RejectedSlot = "rejected-slot",
+    Bundle = "bundle",
+    NodeBuiltin = "node-builtin",
+    Evaluation = "evaluation",
+    Module = "module",
+    Conflict = "conflict",
+    Instructions = "instructions",
+    Skills = "skills",
+    Schedule = "schedule",
+    Hook = "hook",
+    Channel = "channel",
+    Sandbox = "sandbox",
+    Harness = "harness",
+    BaseTools = "base-tools",
+    Connections = "connections",
+    Manifest = "manifest",
+    Compatibility = "compatibility",
+    Secrets = "secrets",
+    Dependencies = "dependencies"
+}
+export interface DiagnosticIface {
+    severity: DiagnosticSeverity;
+    code: DiagnosticCode;
+    message: string;
+    path: string | null;
+}
+export declare const diagnostic: (args: {
+    severity: DiagnosticSeverity;
+    code: DiagnosticCode;
+    message: string;
+    path?: string | null;
+}) => DiagnosticIface;
+export declare const hasErrors: (diagnostics: readonly DiagnosticIface[]) => boolean;

package/dist/modules/compiler/diagnostics.mjs

@@ -0,0 +1,38 @@
+var DiagnosticSeverity = /* @__PURE__ */ ((DiagnosticSeverity2) => {
+  DiagnosticSeverity2["Error"] = "error";
+  DiagnosticSeverity2["Warning"] = "warning";
+  DiagnosticSeverity2["Note"] = "note";
+  return DiagnosticSeverity2;
+})(DiagnosticSeverity || {});
+var DiagnosticCode = /* @__PURE__ */ ((DiagnosticCode2) => {
+  DiagnosticCode2["Input"] = "input";
+  DiagnosticCode2["RejectedSlot"] = "rejected-slot";
+  DiagnosticCode2["Bundle"] = "bundle";
+  DiagnosticCode2["NodeBuiltin"] = "node-builtin";
+  DiagnosticCode2["Evaluation"] = "evaluation";
+  DiagnosticCode2["Module"] = "module";
+  DiagnosticCode2["Conflict"] = "conflict";
+  DiagnosticCode2["Instructions"] = "instructions";
+  DiagnosticCode2["Skills"] = "skills";
+  DiagnosticCode2["Schedule"] = "schedule";
+  DiagnosticCode2["Hook"] = "hook";
+  DiagnosticCode2["Channel"] = "channel";
+  DiagnosticCode2["Sandbox"] = "sandbox";
+  DiagnosticCode2["Harness"] = "harness";
+  DiagnosticCode2["BaseTools"] = "base-tools";
+  DiagnosticCode2["Connections"] = "connections";
+  DiagnosticCode2["Manifest"] = "manifest";
+  DiagnosticCode2["Compatibility"] = "compatibility";
+  DiagnosticCode2["Secrets"] = "secrets";
+  DiagnosticCode2["Dependencies"] = "dependencies";
+  return DiagnosticCode2;
+})(DiagnosticCode || {});
+const diagnostic = (args) => ({ ...args, path: args.path ?? null });
+const hasErrors = (diagnostics) => diagnostics.some((item) => item.severity === "error" /* Error */);
+export {
+  DiagnosticCode,
+  DiagnosticSeverity,
+  diagnostic,
+  hasErrors
+};
+//# sourceMappingURL=diagnostics.mjs.map

package/dist/modules/compiler/diagnostics.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/compiler/diagnostics.ts"],
+  "sourcesContent": ["export enum DiagnosticSeverity {\n  Error = 'error',\n  Warning = 'warning',\n  Note = 'note',\n}\n\nexport enum DiagnosticCode {\n  Input = 'input',\n  RejectedSlot = 'rejected-slot',\n  Bundle = 'bundle',\n  NodeBuiltin = 'node-builtin',\n  Evaluation = 'evaluation',\n  Module = 'module',\n  Conflict = 'conflict',\n  Instructions = 'instructions',\n  Skills = 'skills',\n  Schedule = 'schedule',\n  Hook = 'hook',\n  Channel = 'channel',\n  Sandbox = 'sandbox',\n  Harness = 'harness',\n  BaseTools = 'base-tools',\n  Connections = 'connections',\n  Manifest = 'manifest',\n  Compatibility = 'compatibility',\n  Secrets = 'secrets',\n  Dependencies = 'dependencies',\n}\n\nexport interface DiagnosticIface {\n  severity: DiagnosticSeverity;\n  code: DiagnosticCode;\n  message: string;\n  // Directory-relative source file, when one is responsible.\n  path: string | null;\n}\n\nexport const diagnostic = (args: {\n  severity: DiagnosticSeverity;\n  code: DiagnosticCode;\n  message: string;\n  path?: string | null;\n}): DiagnosticIface => ({ ...args, path: args.path ?? null });\n\nexport const hasErrors = (diagnostics: readonly DiagnosticIface[]): boolean =>\n  diagnostics.some((item) => item.severity === DiagnosticSeverity.Error);\n"],
+  "mappings": "AAAO,IAAK,qBAAL,kBAAKA,wBAAL;AACL,EAAAA,oBAAA,WAAQ;AACR,EAAAA,oBAAA,aAAU;AACV,EAAAA,oBAAA,UAAO;AAHG,SAAAA;AAAA,GAAA;AAML,IAAK,iBAAL,kBAAKC,oBAAL;AACL,EAAAA,gBAAA,WAAQ;AACR,EAAAA,gBAAA,kBAAe;AACf,EAAAA,gBAAA,YAAS;AACT,EAAAA,gBAAA,iBAAc;AACd,EAAAA,gBAAA,gBAAa;AACb,EAAAA,gBAAA,YAAS;AACT,EAAAA,gBAAA,cAAW;AACX,EAAAA,gBAAA,kBAAe;AACf,EAAAA,gBAAA,YAAS;AACT,EAAAA,gBAAA,cAAW;AACX,EAAAA,gBAAA,UAAO;AACP,EAAAA,gBAAA,aAAU;AACV,EAAAA,gBAAA,aAAU;AACV,EAAAA,gBAAA,aAAU;AACV,EAAAA,gBAAA,eAAY;AACZ,EAAAA,gBAAA,iBAAc;AACd,EAAAA,gBAAA,cAAW;AACX,EAAAA,gBAAA,mBAAgB;AAChB,EAAAA,gBAAA,aAAU;AACV,EAAAA,gBAAA,kBAAe;AApBL,SAAAA;AAAA,GAAA;AA+BL,MAAM,aAAa,CAAC,UAKH,EAAE,GAAG,MAAM,MAAM,KAAK,QAAQ,KAAK;AAEpD,MAAM,YAAY,CAAC,gBACxB,YAAY,KAAK,CAAC,SAAS,KAAK,aAAa,mBAAwB;",
+  "names": ["DiagnosticSeverity", "DiagnosticCode"]
+}

package/dist/modules/compiler/discovery.d.mts

@@ -0,0 +1,36 @@
+import { type LayoutModuleIface } from "../runtime/layout.mjs";
+export declare const stripModuleExtension: (path: string) => string;
+export declare const isModulePath: (path: string) => boolean;
+export declare enum InstructionSourceKind {
+    Markdown = "markdown",
+    Module = "module"
+}
+export interface InstructionSourceIface {
+    path: string;
+    kind: InstructionSourceKind;
+}
+export interface SkillDirectoryIface {
+    key: string;
+    directory: string;
+    files: string[];
+}
+export interface RejectedSlotIface {
+    path: string;
+    message: string;
+}
+export interface DiscoveryIface {
+    modules: LayoutModuleIface[];
+    instructions: InstructionSourceIface[];
+    skillDirectories: SkillDirectoryIface[];
+    skillMarkdown: {
+        key: string;
+        path: string;
+    }[];
+    scheduleMarkdown: {
+        key: string;
+        path: string;
+    }[];
+    rejected: RejectedSlotIface[];
+    unsupported: RejectedSlotIface[];
+}
+export declare const discover: (paths: readonly string[]) => DiscoveryIface;

package/dist/modules/compiler/discovery.mjs

@@ -0,0 +1,158 @@
+import { posix } from "node:path";
+import { SlotKind } from "../runtime/layout.mjs";
+const MODULE_EXTENSION = /\.(ts|mts|js|mjs)$/;
+const stripModuleExtension = (path) => path.replace(MODULE_EXTENSION, "");
+const isModulePath = (path) => MODULE_EXTENSION.test(path) && !path.endsWith(".d.ts");
+var InstructionSourceKind = /* @__PURE__ */ ((InstructionSourceKind2) => {
+  InstructionSourceKind2["Markdown"] = "markdown";
+  InstructionSourceKind2["Module"] = "module";
+  return InstructionSourceKind2;
+})(InstructionSourceKind || {});
+const REJECTED_SLOTS = {
+  subagents: "subagents/ is not supported yet: delegating to subagents needs a harness capability for nested sessions, which no harness implements",
+  extensions: "extensions/ is not supported: extensions have no counterpart; package shared code and import it",
+  memory: "memory/ is not supported yet: memory will be a harness capability (a `memory` field in its config schema) with an MCP-contributed store"
+};
+const UNSUPPORTED_ROOT_FILES = /* @__PURE__ */ new Map([
+  [
+    "instrumentation",
+    "instrumentation is not supported; the session service records the ACP log and telemetry"
+  ]
+]);
+const top = (path) => path.split("/")[0] ?? path;
+const byName = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const discover = (paths) => {
+  const sorted = [...paths].sort(byName);
+  const modules = [];
+  const add = (path, slot, key, base) => {
+    modules.push({ base: base ?? stripModuleExtension(path), path, slot, key });
+  };
+  const rejected = [];
+  const modulePaths = /* @__PURE__ */ new Map();
+  for (const path of sorted.filter(isModulePath)) {
+    const base = stripModuleExtension(path);
+    const previous = modulePaths.get(base);
+    if (previous != null)
+      rejected.push({
+        path,
+        message: `duplicate module ${base}: ${previous} and ${path}; keep one`
+      });
+    modulePaths.set(base, path);
+  }
+  const unsupported = [];
+  for (const [slot, message] of Object.entries(REJECTED_SLOTS)) {
+    const found = sorted.find((path) => top(path) === slot || stripModuleExtension(path) === slot);
+    if (found != null) rejected.push({ path: found, message });
+  }
+  for (const path of sorted) {
+    const message = UNSUPPORTED_ROOT_FILES.get(stripModuleExtension(path));
+    if (message != null && !path.includes("/")) unsupported.push({ path, message });
+  }
+  const agent = sorted.find(
+    (path) => !path.includes("/") && stripModuleExtension(path) === "agent" && isModulePath(path)
+  );
+  if (agent != null) add(agent, SlotKind.Agent, "agent");
+  const sandboxFile = sorted.find(
+    (path) => !path.includes("/") && stripModuleExtension(path) === "sandbox" && isModulePath(path)
+  );
+  const sandboxDirectory = sorted.filter((path) => top(path) === "sandbox" && path.includes("/"));
+  const sandboxIndex = sandboxDirectory.find(
+    (path) => posix.dirname(path) === "sandbox" && stripModuleExtension(path) === "sandbox/index" && isModulePath(path)
+  );
+  if (sandboxFile != null && sandboxDirectory.length > 0) {
+    rejected.push({
+      path: "sandbox",
+      message: "sandbox.ts and a sandbox/ directory are both present; keep one"
+    });
+  } else if (sandboxDirectory.length > 0 && sandboxIndex == null) {
+    rejected.push({
+      path: "sandbox",
+      message: "sandbox/ needs an index.ts that exports the sandbox targets (the same module as sandbox.ts)"
+    });
+  }
+  const sandbox = sandboxFile ?? sandboxIndex;
+  if (sandbox != null) add(sandbox, SlotKind.Sandbox, "sandbox", "sandbox");
+  const instructions = [];
+  const rootInstructions = sorted.filter(
+    (path) => !path.includes("/") && (path === "instructions.md" || stripModuleExtension(path) === "instructions")
+  );
+  for (const path of rootInstructions.sort(
+    (a, b) => a.endsWith(".md") ? -1 : b.endsWith(".md") ? 1 : 0
+  )) {
+    if (path.endsWith(".md")) instructions.push({ path, kind: "markdown" /* Markdown */ });
+    else if (isModulePath(path)) {
+      instructions.push({ path, kind: "module" /* Module */ });
+      add(path, SlotKind.Instructions, "instructions");
+    }
+  }
+  for (const path of sorted) {
+    if (posix.dirname(path) !== "instructions") continue;
+    if (path.endsWith(".md")) instructions.push({ path, kind: "markdown" /* Markdown */ });
+    else if (isModulePath(path)) {
+      instructions.push({ path, kind: "module" /* Module */ });
+      add(path, SlotKind.Instructions, stripModuleExtension(posix.basename(path)));
+    }
+  }
+  const skillDirectories = [];
+  const skillMarkdown = [];
+  for (const path of sorted) {
+    if (top(path) !== "skills") continue;
+    const parent = posix.dirname(path);
+    if (parent === "skills") {
+      if (path.endsWith(".md")) skillMarkdown.push({ key: posix.basename(path, ".md"), path });
+      else if (isModulePath(path))
+        add(path, SlotKind.Skill, stripModuleExtension(posix.basename(path)));
+      continue;
+    }
+    if (posix.basename(path) !== "SKILL.md") continue;
+    if (skillDirectories.some((skill) => parent.startsWith(`${skill.directory}/`))) continue;
+    skillDirectories.push({
+      key: posix.relative("skills", parent).split("/").join("_"),
+      directory: parent,
+      files: sorted.filter((file) => file.startsWith(`${parent}/`))
+    });
+  }
+  for (const path of sorted) {
+    if (posix.dirname(path) === "tools" && isModulePath(path)) {
+      add(path, SlotKind.Tool, stripModuleExtension(posix.basename(path)));
+    }
+  }
+  for (const path of sorted) {
+    if (posix.dirname(path) === "connections" && isModulePath(path)) {
+      add(path, SlotKind.Connection, stripModuleExtension(posix.basename(path)));
+    }
+  }
+  const scheduleMarkdown = [];
+  for (const path of sorted) {
+    if (posix.dirname(path) !== "schedules") continue;
+    if (path.endsWith(".md")) scheduleMarkdown.push({ key: posix.basename(path, ".md"), path });
+    else if (isModulePath(path))
+      add(path, SlotKind.Schedule, stripModuleExtension(posix.basename(path)));
+  }
+  for (const path of sorted) {
+    if (top(path) === "hooks" && path.includes("/") && isModulePath(path)) {
+      add(path, SlotKind.Hook, stripModuleExtension(posix.relative("hooks", path)));
+    }
+  }
+  for (const path of sorted) {
+    if (posix.dirname(path) === "channels" && isModulePath(path)) {
+      add(path, SlotKind.Channel, stripModuleExtension(posix.basename(path)));
+    }
+  }
+  return {
+    modules,
+    instructions,
+    skillDirectories,
+    skillMarkdown,
+    scheduleMarkdown,
+    rejected,
+    unsupported
+  };
+};
+export {
+  InstructionSourceKind,
+  discover,
+  isModulePath,
+  stripModuleExtension
+};
+//# sourceMappingURL=discovery.mjs.map

package/dist/modules/compiler/discovery.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/compiler/discovery.ts"],
+  "sourcesContent": ["import { posix } from 'node:path';\nimport { SlotKind, type LayoutModuleIface } from \"../runtime/layout.mjs\";\n\n// Agent directory layout: agent.ts; instructions.md, instructions.ts, then instructions/*\n// (sorted, non-recursive, .md and .ts, one fragment each); skills/*/SKILL.md\n// (+ sibling files), skills/<name>.md and skills/<name>.ts; tools/*.ts;\n// connections/*.ts; schedules/*.md and schedules/*.ts; hooks/** (recursive);\n// channels/*.ts; sandbox.ts or sandbox/index.ts. subagents/, extensions/ and\n// memory/ are rejected.\n\nconst MODULE_EXTENSION = /\\.(ts|mts|js|mjs)$/;\n\nexport const stripModuleExtension = (path: string): string => path.replace(MODULE_EXTENSION, '');\n\nexport const isModulePath = (path: string): boolean =>\n  MODULE_EXTENSION.test(path) && !path.endsWith('.d.ts');\n\nexport enum InstructionSourceKind {\n  Markdown = 'markdown',\n  Module = 'module',\n}\n\nexport interface InstructionSourceIface {\n  path: string;\n  kind: InstructionSourceKind;\n}\n\nexport interface SkillDirectoryIface {\n  key: string;\n  directory: string;\n  // Directory-relative paths of every file in the skill, SKILL.md included.\n  files: string[];\n}\n\nexport interface RejectedSlotIface {\n  path: string;\n  message: string;\n}\n\nexport interface DiscoveryIface {\n  modules: LayoutModuleIface[];\n  instructions: InstructionSourceIface[];\n  skillDirectories: SkillDirectoryIface[];\n  // skills/<name>.md\n  skillMarkdown: { key: string; path: string }[];\n  scheduleMarkdown: { key: string; path: string }[];\n  rejected: RejectedSlotIface[];\n  unsupported: RejectedSlotIface[];\n}\n\nconst REJECTED_SLOTS = {\n  subagents:\n    'subagents/ is not supported yet: delegating to subagents needs a harness capability for nested sessions, which no harness implements',\n  extensions:\n    'extensions/ is not supported: extensions have no counterpart; package shared code and import it',\n  memory:\n    'memory/ is not supported yet: memory will be a harness capability (a `memory` field in its config schema) with an MCP-contributed store',\n};\n\nconst UNSUPPORTED_ROOT_FILES = new Map([\n  [\n    'instrumentation',\n    'instrumentation is not supported; the session service records the ACP log and telemetry',\n  ],\n]);\n\nconst top = (path: string): string => path.split('/')[0] ?? path;\n\nconst byName = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);\n\nexport const discover = (paths: readonly string[]): DiscoveryIface => {\n  const sorted = [...paths].sort(byName);\n  const modules: LayoutModuleIface[] = [];\n  const add = (path: string, slot: SlotKind, key: string, base?: string): void => {\n    modules.push({ base: base ?? stripModuleExtension(path), path, slot, key });\n  };\n  const rejected: RejectedSlotIface[] = [];\n  const modulePaths = new Map<string, string>();\n  for (const path of sorted.filter(isModulePath)) {\n    const base = stripModuleExtension(path);\n    const previous = modulePaths.get(base);\n    if (previous != null)\n      rejected.push({\n        path,\n        message: `duplicate module ${base}: ${previous} and ${path}; keep one`,\n      });\n    modulePaths.set(base, path);\n  }\n  const unsupported: RejectedSlotIface[] = [];\n  for (const [slot, message] of Object.entries(REJECTED_SLOTS)) {\n    const found = sorted.find((path) => top(path) === slot || stripModuleExtension(path) === slot);\n    if (found != null) rejected.push({ path: found, message });\n  }\n  for (const path of sorted) {\n    const message = UNSUPPORTED_ROOT_FILES.get(stripModuleExtension(path));\n    if (message != null && !path.includes('/')) unsupported.push({ path, message });\n  }\n\n  const agent = sorted.find(\n    (path) => !path.includes('/') && stripModuleExtension(path) === 'agent' && isModulePath(path),\n  );\n  if (agent != null) add(agent, SlotKind.Agent, 'agent');\n  // sandbox.ts, or a sandbox/ directory whose index module is the same module\n  // (its other files are helpers it imports). Exports keep the `sandbox` base.\n  const sandboxFile = sorted.find(\n    (path) => !path.includes('/') && stripModuleExtension(path) === 'sandbox' && isModulePath(path),\n  );\n  const sandboxDirectory = sorted.filter((path) => top(path) === 'sandbox' && path.includes('/'));\n  const sandboxIndex = sandboxDirectory.find(\n    (path) =>\n      posix.dirname(path) === 'sandbox' &&\n      stripModuleExtension(path) === 'sandbox/index' &&\n      isModulePath(path),\n  );\n  if (sandboxFile != null && sandboxDirectory.length > 0) {\n    rejected.push({\n      path: 'sandbox',\n      message: 'sandbox.ts and a sandbox/ directory are both present; keep one',\n    });\n  } else if (sandboxDirectory.length > 0 && sandboxIndex == null) {\n    rejected.push({\n      path: 'sandbox',\n      message:\n        'sandbox/ needs an index.ts that exports the sandbox targets (the same module as sandbox.ts)',\n    });\n  }\n  const sandbox = sandboxFile ?? sandboxIndex;\n  if (sandbox != null) add(sandbox, SlotKind.Sandbox, 'sandbox', 'sandbox');\n\n  const instructions: InstructionSourceIface[] = [];\n  const rootInstructions = sorted.filter(\n    (path) =>\n      !path.includes('/') &&\n      (path === 'instructions.md' || stripModuleExtension(path) === 'instructions'),\n  );\n  for (const path of rootInstructions.sort((a, b) =>\n    a.endsWith('.md') ? -1 : b.endsWith('.md') ? 1 : 0,\n  )) {\n    if (path.endsWith('.md')) instructions.push({ path, kind: InstructionSourceKind.Markdown });\n    else if (isModulePath(path)) {\n      instructions.push({ path, kind: InstructionSourceKind.Module });\n      add(path, SlotKind.Instructions, 'instructions');\n    }\n  }\n  for (const path of sorted) {\n    if (posix.dirname(path) !== 'instructions') continue;\n    if (path.endsWith('.md')) instructions.push({ path, kind: InstructionSourceKind.Markdown });\n    else if (isModulePath(path)) {\n      instructions.push({ path, kind: InstructionSourceKind.Module });\n      add(path, SlotKind.Instructions, stripModuleExtension(posix.basename(path)));\n    }\n  }\n\n  const skillDirectories: SkillDirectoryIface[] = [];\n  const skillMarkdown: { key: string; path: string }[] = [];\n  for (const path of sorted) {\n    if (top(path) !== 'skills') continue;\n    const parent = posix.dirname(path);\n    if (parent === 'skills') {\n      if (path.endsWith('.md')) skillMarkdown.push({ key: posix.basename(path, '.md'), path });\n      else if (isModulePath(path))\n        add(path, SlotKind.Skill, stripModuleExtension(posix.basename(path)));\n      continue;\n    }\n    if (posix.basename(path) !== 'SKILL.md') continue;\n    // A nested SKILL.md inside another skill belongs to that skill.\n    if (skillDirectories.some((skill) => parent.startsWith(`${skill.directory}/`))) continue;\n    skillDirectories.push({\n      key: posix.relative('skills', parent).split('/').join('_'),\n      directory: parent,\n      files: sorted.filter((file) => file.startsWith(`${parent}/`)),\n    });\n  }\n\n  for (const path of sorted) {\n    if (posix.dirname(path) === 'tools' && isModulePath(path)) {\n      add(path, SlotKind.Tool, stripModuleExtension(posix.basename(path)));\n    }\n  }\n  for (const path of sorted) {\n    if (posix.dirname(path) === 'connections' && isModulePath(path)) {\n      add(path, SlotKind.Connection, stripModuleExtension(posix.basename(path)));\n    }\n  }\n  const scheduleMarkdown: { key: string; path: string }[] = [];\n  for (const path of sorted) {\n    if (posix.dirname(path) !== 'schedules') continue;\n    if (path.endsWith('.md')) scheduleMarkdown.push({ key: posix.basename(path, '.md'), path });\n    else if (isModulePath(path))\n      add(path, SlotKind.Schedule, stripModuleExtension(posix.basename(path)));\n  }\n  for (const path of sorted) {\n    if (top(path) === 'hooks' && path.includes('/') && isModulePath(path)) {\n      add(path, SlotKind.Hook, stripModuleExtension(posix.relative('hooks', path)));\n    }\n  }\n  for (const path of sorted) {\n    if (posix.dirname(path) === 'channels' && isModulePath(path)) {\n      add(path, SlotKind.Channel, stripModuleExtension(posix.basename(path)));\n    }\n  }\n  return {\n    modules,\n    instructions,\n    skillDirectories,\n    skillMarkdown,\n    scheduleMarkdown,\n    rejected,\n    unsupported,\n  };\n};\n"],
+  "mappings": "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",
+  "names": ["InstructionSourceKind"]
+}

package/dist/modules/compiler/evaluate.d.mts

@@ -0,0 +1,13 @@
+import { type DescribedBundleIface } from "../runtime/described.mjs";
+export type EvaluationResult = {
+    ok: true;
+    described: DescribedBundleIface;
+} | {
+    ok: false;
+    message: string;
+};
+export interface EvaluateOptionsIface {
+    packageRoot?: string;
+    allowCodeGenerationForTests?: boolean;
+}
+export declare const evaluateBundle: (code: string, options?: EvaluateOptionsIface) => Promise<EvaluationResult>;

package/dist/modules/compiler/evaluate.mjs

@@ -0,0 +1,194 @@
+import { transform } from "esbuild";
+import { execFile, spawn } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import * as z from "zod";
+import { describedBundleSchema } from "../runtime/described.mjs";
+import { DEFAULT_packageRoot } from "./bundle.mjs";
+const GLOBAL_NAME = "__finalAgentBundle";
+const PROCESS_TIMEOUT_MS = 2e4;
+const MEMORY_LIMIT_MB = 256;
+const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+const PROCESS_MEMORY_LIMIT_KB = 512 * 1024;
+const MAX_EVALUATIONS = 2;
+const MAX_QUEUED_EVALUATIONS = 16;
+const evaluationWaiters = [];
+let activeEvaluations = 0;
+const childReplySchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), described: z.string() }),
+  z.object({ ok: z.literal(false), message: z.string() })
+]);
+const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+const runChild = async (args) => {
+  const entry = await realpath(
+    resolve(
+      args.options.packageRoot ?? DEFAULT_packageRoot,
+      "src",
+      "compiler",
+      "evaluate-child.mjs"
+    )
+  );
+  const flags = [
+    "--permission",
+    `--allow-fs-read=${entry}`,
+    `--max-old-space-size=${MEMORY_LIMIT_MB}`,
+    // V8's JIT code range exceeds Linux's data limit before evaluation starts.
+    "--jitless",
+    "--no-warnings",
+    ...args.options.allowCodeGenerationForTests === true ? [] : ["--disallow-code-generation-from-strings"]
+  ];
+  return new Promise((done, reject) => {
+    const child = process.platform === "linux" ? spawn(
+      "/bin/sh",
+      [
+        "-c",
+        `ulimit -d ${PROCESS_MEMORY_LIMIT_KB} || exit 1; exec /usr/bin/env -i "$@"`,
+        "evaluate",
+        process.execPath,
+        ...flags,
+        entry
+      ],
+      {
+        env: {},
+        stdio: ["pipe", "pipe", "pipe"]
+      }
+    ) : spawn(process.execPath, [...flags, entry], {
+      env: {},
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const stdout = [];
+    const stderr = [];
+    let size = 0;
+    let timedOut = false;
+    let overflowed = false;
+    let memoryExceeded = false;
+    let checkingMemory = false;
+    const memoryTimer = process.platform === "linux" ? null : setInterval(() => {
+      if (checkingMemory || child.pid == null) return;
+      checkingMemory = true;
+      execFile(
+        "/bin/ps",
+        ["-o", "rss=", "-p", String(child.pid)],
+        { env: {}, timeout: 1e3 },
+        (error, stdout2) => {
+          checkingMemory = false;
+          if (error == null && Number(stdout2.trim()) > PROCESS_MEMORY_LIMIT_KB) {
+            memoryExceeded = true;
+            child.kill("SIGKILL");
+          }
+        }
+      );
+    }, 50);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, PROCESS_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_OUTPUT_BYTES) {
+        overflowed = true;
+        child.kill("SIGKILL");
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      if (stderr.reduce((total, item) => total + item.length, 0) < 64 * 1024) stderr.push(chunk);
+    });
+    child.on("error", (cause) => {
+      clearTimeout(timer);
+      if (memoryTimer != null) clearInterval(memoryTimer);
+      reject(cause);
+    });
+    child.on("close", (exitCode) => {
+      clearTimeout(timer);
+      if (memoryTimer != null) clearInterval(memoryTimer);
+      done({
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        exitCode,
+        timedOut,
+        overflowed,
+        memoryExceeded
+      });
+    });
+    child.stdin.on("error", () => void 0);
+    child.stdin.end(args.script);
+  });
+};
+const lastLine = (text) => text.trim().split("\n").at(-1) ?? "";
+const evaluate = async (code, options = {}) => {
+  let script;
+  try {
+    const converted = await transform(code, {
+      format: "iife",
+      globalName: GLOBAL_NAME,
+      loader: "js",
+      target: "es2024"
+    });
+    script = `${converted.code}
+;${GLOBAL_NAME}.__describe();`;
+  } catch (cause) {
+    const text = messageOf(cause);
+    return {
+      ok: false,
+      message: /top-level await/i.test(text) ? "authored modules may not use top-level await" : `could not prepare the bundle for evaluation: ${text}`
+    };
+  }
+  let output;
+  try {
+    output = await runChild({ script, options });
+  } catch (cause) {
+    return { ok: false, message: `could not start the evaluation process: ${messageOf(cause)}` };
+  }
+  if (output.memoryExceeded)
+    return { ok: false, message: "evaluating the authored modules exceeded its memory limit" };
+  if (output.timedOut) return { ok: false, message: "evaluating the authored modules timed out" };
+  if (output.overflowed)
+    return { ok: false, message: "evaluating the authored modules produced too much output" };
+  let reply;
+  try {
+    reply = childReplySchema.safeParse(JSON.parse(lastLine(output.stdout)));
+  } catch {
+    reply = null;
+  }
+  if (reply == null || !reply.success) {
+    const detail = lastLine(output.stderr);
+    return {
+      ok: false,
+      message: `evaluating the authored modules failed (exit ${output.exitCode ?? "signal"})${detail.length > 0 ? `: ${detail}` : ""}`
+    };
+  }
+  if (!reply.data.ok) return { ok: false, message: reply.data.message };
+  let described;
+  try {
+    described = describedBundleSchema.safeParse(JSON.parse(reply.data.described));
+  } catch {
+    return { ok: false, message: "the bundle did not describe itself" };
+  }
+  if (!described.success) {
+    return {
+      ok: false,
+      message: `the bundle description is malformed: ${described.error.message}`
+    };
+  }
+  return { ok: true, described: described.data };
+};
+const evaluateBundle = async (code, options = {}) => {
+  if (activeEvaluations >= MAX_EVALUATIONS) {
+    if (evaluationWaiters.length >= MAX_QUEUED_EVALUATIONS)
+      return { ok: false, message: "the definition compiler is busy; retry shortly" };
+    await new Promise((resolve2) => evaluationWaiters.push(resolve2));
+  } else activeEvaluations += 1;
+  try {
+    return await evaluate(code, options);
+  } finally {
+    const next = evaluationWaiters.shift();
+    if (next == null) activeEvaluations -= 1;
+    else next();
+  }
+};
+export {
+  evaluateBundle
+};
+//# sourceMappingURL=evaluate.mjs.map

package/dist/modules/compiler/evaluate.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/compiler/evaluate.ts"],
+  "sourcesContent": ["import { transform } from 'esbuild';\nimport { execFile, spawn } from 'node:child_process';\nimport { realpath } from 'node:fs/promises';\nimport { resolve } from 'node:path';\nimport * as z from 'zod';\nimport { describedBundleSchema, type DescribedBundleIface } from \"../runtime/described.mjs\";\nimport { DEFAULT_packageRoot } from \"./bundle.mjs\";\n\nconst GLOBAL_NAME = '__finalAgentBundle';\n// The child's own vm timeout is 10 s; this bounds startup and output too.\nconst PROCESS_TIMEOUT_MS = 20_000;\nconst MEMORY_LIMIT_MB = 256;\nconst MAX_OUTPUT_BYTES = 32 * 1024 * 1024;\nconst PROCESS_MEMORY_LIMIT_KB = 512 * 1024;\nconst MAX_EVALUATIONS = 2;\nconst MAX_QUEUED_EVALUATIONS = 16;\nconst evaluationWaiters: (() => void)[] = [];\nlet activeEvaluations = 0;\n\nexport type EvaluationResult =\n  | { ok: true; described: DescribedBundleIface }\n  | { ok: false; message: string };\n\nexport interface EvaluateOptionsIface {\n  // Root of the installed @finalai/agent-definition package (holds\n  // src/compiler/evaluate-child.mjs); defaults to this source tree.\n  packageRoot?: string;\n  // Tests only: lets code generation from strings through, so a test can\n  // prove the process boundary holds even when the vm boundary does not.\n  allowCodeGenerationForTests?: boolean;\n}\n\nconst childReplySchema = z.discriminatedUnion('ok', [\n  z.object({ ok: z.literal(true), described: z.string() }),\n  z.object({ ok: z.literal(false), message: z.string() }),\n]);\n\nconst messageOf = (cause: unknown): string =>\n  cause instanceof Error ? cause.message : String(cause);\n\ninterface ChildOutputIface {\n  stdout: string;\n  stderr: string;\n  exitCode: number | null;\n  timedOut: boolean;\n  overflowed: boolean;\n  memoryExceeded: boolean;\n}\n\n// Authored top-level code runs in its own Node process: empty environment, the\n// permission model granting only a read of the child entry (no other\n// filesystem access, network, child processes, workers, addons, WASI or\n// inspector), no code generation from strings, a heap cap and a hard timeout.\nconst runChild = async (args: {\n  script: string;\n  options: EvaluateOptionsIface;\n}): Promise<ChildOutputIface> => {\n  const entry = await realpath(\n    resolve(\n      args.options.packageRoot ?? DEFAULT_packageRoot,\n      'src',\n      'compiler',\n      'evaluate-child.mjs',\n    ),\n  );\n  const flags = [\n    '--permission',\n    `--allow-fs-read=${entry}`,\n    `--max-old-space-size=${MEMORY_LIMIT_MB}`,\n    // V8's JIT code range exceeds Linux's data limit before evaluation starts.\n    '--jitless',\n    '--no-warnings',\n    ...(args.options.allowCodeGenerationForTests === true\n      ? []\n      : ['--disallow-code-generation-from-strings']),\n  ];\n  return new Promise((done, reject) => {\n    // Linux RLIMIT_DATA also bounds anonymous mmap-backed ArrayBuffers. A heap\n    // limit alone does not. macOS has no enforceable data-segment limit; monitor\n    // RSS there as well as bounding concurrency and elapsed time.\n    const child =\n      process.platform === 'linux'\n        ? spawn(\n            '/bin/sh',\n            [\n              '-c',\n              `ulimit -d ${PROCESS_MEMORY_LIMIT_KB} || exit 1; exec /usr/bin/env -i \"$@\"`,\n              'evaluate',\n              process.execPath,\n              ...flags,\n              entry,\n            ],\n            {\n              env: {},\n              stdio: ['pipe', 'pipe', 'pipe'],\n            },\n          )\n        : spawn(process.execPath, [...flags, entry], {\n            env: {},\n            stdio: ['pipe', 'pipe', 'pipe'],\n          });\n    const stdout: Buffer[] = [];\n    const stderr: Buffer[] = [];\n    let size = 0;\n    let timedOut = false;\n    let overflowed = false;\n    let memoryExceeded = false;\n    let checkingMemory = false;\n    const memoryTimer =\n      process.platform === 'linux'\n        ? null\n        : setInterval(() => {\n            if (checkingMemory || child.pid == null) return;\n            checkingMemory = true;\n            execFile(\n              '/bin/ps',\n              ['-o', 'rss=', '-p', String(child.pid)],\n              { env: {}, timeout: 1000 },\n              (error, stdout) => {\n                checkingMemory = false;\n                if (error == null && Number(stdout.trim()) > PROCESS_MEMORY_LIMIT_KB) {\n                  memoryExceeded = true;\n                  child.kill('SIGKILL');\n                }\n              },\n            );\n          }, 50);\n    const timer = setTimeout(() => {\n      timedOut = true;\n      child.kill('SIGKILL');\n    }, PROCESS_TIMEOUT_MS);\n    child.stdout.on('data', (chunk: Buffer) => {\n      size += chunk.length;\n      if (size > MAX_OUTPUT_BYTES) {\n        overflowed = true;\n        child.kill('SIGKILL');\n        return;\n      }\n      stdout.push(chunk);\n    });\n    child.stderr.on('data', (chunk: Buffer) => {\n      if (stderr.reduce((total, item) => total + item.length, 0) < 64 * 1024) stderr.push(chunk);\n    });\n    child.on('error', (cause) => {\n      clearTimeout(timer);\n      if (memoryTimer != null) clearInterval(memoryTimer);\n      reject(cause);\n    });\n    child.on('close', (exitCode) => {\n      clearTimeout(timer);\n      if (memoryTimer != null) clearInterval(memoryTimer);\n      done({\n        stdout: Buffer.concat(stdout).toString('utf8'),\n        stderr: Buffer.concat(stderr).toString('utf8'),\n        exitCode,\n        timedOut,\n        overflowed,\n        memoryExceeded,\n      });\n    });\n    child.stdin.on('error', () => undefined);\n    child.stdin.end(args.script);\n  });\n};\n\nconst lastLine = (text: string): string => text.trim().split('\\n').at(-1) ?? '';\n\nconst evaluate = async (\n  code: string,\n  options: EvaluateOptionsIface = {},\n): Promise<EvaluationResult> => {\n  let script: string;\n  try {\n    const converted = await transform(code, {\n      format: 'iife',\n      globalName: GLOBAL_NAME,\n      loader: 'js',\n      target: 'es2024',\n    });\n    script = `${converted.code}\\n;${GLOBAL_NAME}.__describe();`;\n  } catch (cause) {\n    const text = messageOf(cause);\n    return {\n      ok: false,\n      message: /top-level await/i.test(text)\n        ? 'authored modules may not use top-level await'\n        : `could not prepare the bundle for evaluation: ${text}`,\n    };\n  }\n  let output: ChildOutputIface;\n  try {\n    output = await runChild({ script, options });\n  } catch (cause) {\n    return { ok: false, message: `could not start the evaluation process: ${messageOf(cause)}` };\n  }\n  if (output.memoryExceeded)\n    return { ok: false, message: 'evaluating the authored modules exceeded its memory limit' };\n  if (output.timedOut) return { ok: false, message: 'evaluating the authored modules timed out' };\n  if (output.overflowed)\n    return { ok: false, message: 'evaluating the authored modules produced too much output' };\n  let reply;\n  try {\n    reply = childReplySchema.safeParse(JSON.parse(lastLine(output.stdout)));\n  } catch {\n    reply = null;\n  }\n  if (reply == null || !reply.success) {\n    const detail = lastLine(output.stderr);\n    return {\n      ok: false,\n      message: `evaluating the authored modules failed (exit ${output.exitCode ?? 'signal'})${detail.length > 0 ? `: ${detail}` : ''}`,\n    };\n  }\n  if (!reply.data.ok) return { ok: false, message: reply.data.message };\n  let described;\n  try {\n    described = describedBundleSchema.safeParse(JSON.parse(reply.data.described));\n  } catch {\n    return { ok: false, message: 'the bundle did not describe itself' };\n  }\n  if (!described.success) {\n    return {\n      ok: false,\n      message: `the bundle description is malformed: ${described.error.message}`,\n    };\n  }\n  return { ok: true, described: described.data };\n};\n\nexport const evaluateBundle = async (\n  code: string,\n  options: EvaluateOptionsIface = {},\n): Promise<EvaluationResult> => {\n  if (activeEvaluations >= MAX_EVALUATIONS) {\n    if (evaluationWaiters.length >= MAX_QUEUED_EVALUATIONS)\n      return { ok: false, message: 'the definition compiler is busy; retry shortly' };\n    await new Promise<void>((resolve) => evaluationWaiters.push(resolve));\n  } else activeEvaluations += 1;\n  try {\n    return await evaluate(code, options);\n  } finally {\n    const next = evaluationWaiters.shift();\n    if (next == null) activeEvaluations -= 1;\n    else next();\n  }\n};\n"],
+  "mappings": "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",
+  "names": ["stdout", "resolve"]
+}

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

@@ -0,0 +1,19 @@
+export declare const MAX_FILES = 400;
+export declare const MAX_DEPTH = 10;
+export declare const MAX_FILE_BYTES = 512000;
+export interface DirectoryFilesIface {
+    root: string;
+    files: Record<string, string>;
+}
+export declare const readAgentDirectory: (directory: string) => Promise<DirectoryFilesIface>;
+export interface NormalizedFilesIface {
+    files: Record<string, string>;
+    problems: {
+        path: string;
+        message: string;
+    }[];
+}
+export declare const normalizeFiles: (input: Record<string, string>, options?: {
+    enforceSizeLimits?: boolean;
+}) => NormalizedFilesIface;
+export declare const preparationFiles: (files: Record<string, string>) => Record<string, string>;