@agentproto/workflow-loader 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy André and agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { WorkflowHandle } from '@agentproto/workflow';
+import { WorkflowManifest } from '@agentproto/workflow/manifest';
+
+/**
+ * loadWorkflowHandle — read a WORKFLOW.md off disk into a WorkflowHandle.
+ *
+ * The pure packages stop at the page boundary: `@agentproto/workflow` parses a
+ * manifest *string*, `@agentproto/workflow-runtime` compiles an in-memory
+ * handle. Neither touches the filesystem. This is the host-side seam that does:
+ *
+ *   read file → parse manifest → (if `entry`) import the module + reconcile
+ *
+ * With no `entry`, the manifest IS the workflow (purely-declarative path). With
+ * an `entry`, its default-exported handle is the source of truth for runtime
+ * step logic and the manifest is reconciled against it — the two MUST agree.
+ *
+ * The entry import mirrors the CLI's adapter loader: resolve relative to the
+ * manifest's directory, import via a `file://` URL so an absolute path works
+ * without an `exports` declaration.
+ */
+
+declare class WorkflowLoadError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load and validate a WORKFLOW.md at `workflowMdPath` into a WorkflowHandle.
+ * Throws {@link WorkflowLoadError} on a missing/unreadable file or a bad entry
+ * module, the parser's error on invalid frontmatter, and
+ * {@link WorkflowReconcileError} when an entry's graph disagrees with the
+ * manifest. The returned handle still needs `compileWorkflow` + a tool registry
+ * to run — this stops at the validated, in-memory handle.
+ */
+declare function loadWorkflowHandle(workflowMdPath: string): Promise<WorkflowHandle>;
+
+/**
+ * Reconcile a WORKFLOW.md manifest against the handle its `entry` module
+ * exports. An entry-backed workflow declares its step graph twice — once as
+ * governance-facing manifest data, once as the runnable handle — so the two
+ * MUST agree, or the manifest is lying about what actually runs. This checks
+ * the workflow id and the top-level step (id, kind) sequence; nested step
+ * lists (map / loop / parallel bodies) are the entry's concern.
+ */
+
+declare class WorkflowReconcileError extends Error {
+    constructor(message: string);
+}
+declare function reconcileEntry(manifest: WorkflowManifest, handle: WorkflowHandle): void;
+
+export { WorkflowLoadError, WorkflowReconcileError, loadWorkflowHandle, reconcileEntry };

package/dist/index.mjs

@@ -0,0 +1,93 @@
+import { readFile } from 'fs/promises';
+import { isAbsolute, join, dirname } from 'path';
+import { pathToFileURL } from 'url';
+import { parseWorkflowManifest, workflowFromManifest } from '@agentproto/workflow/manifest';
+
+/**
+ * @agentproto/workflow-loader v0.1.0-alpha
+ * Disk loader + entry reconciliation for AIP-15 WORKFLOW.md.
+ */
+
+
+// src/reconcile.ts
+var WorkflowReconcileError = class extends Error {
+  constructor(message) {
+    super(`reconcileEntry: ${message}`);
+    this.name = "WorkflowReconcileError";
+  }
+};
+var idKind = (steps) => steps.map((s) => ({ id: s.id, kind: s.kind }));
+var summary = (steps) => steps.map((s) => `${s.id}:${s.kind}`).join(" \u2192 ") || "(none)";
+function reconcileEntry(manifest, handle) {
+  const fm = manifest.frontmatter;
+  if (fm.id !== handle.id) {
+    throw new WorkflowReconcileError(
+      `manifest id '${fm.id}' \u2260 entry id '${handle.id}'.`
+    );
+  }
+  const declared = idKind(fm.steps);
+  const actual = idKind(handle.steps);
+  if (declared.length !== actual.length) {
+    throw new WorkflowReconcileError(
+      `step count differs \u2014 manifest declares ${declared.length} [${summary(declared)}], entry has ${actual.length} [${summary(actual)}].`
+    );
+  }
+  for (let i = 0; i < declared.length; i++) {
+    const d = declared[i];
+    const a = actual[i];
+    if (d.id !== a.id || d.kind !== a.kind) {
+      throw new WorkflowReconcileError(
+        `step ${i} differs \u2014 manifest '${d.id}:${d.kind}' \u2260 entry '${a.id}:${a.kind}'. manifest [${summary(declared)}] vs entry [${summary(actual)}].`
+      );
+    }
+  }
+}
+
+// src/load-workflow.ts
+var WorkflowLoadError = class extends Error {
+  constructor(message) {
+    super(`loadWorkflow: ${message}`);
+    this.name = "WorkflowLoadError";
+  }
+};
+function isWorkflowHandle(v) {
+  return typeof v === "object" && v !== null && typeof v.id === "string" && Array.isArray(v.steps);
+}
+async function importEntryHandle(workflowMdPath, entry) {
+  const abs = isAbsolute(entry) ? entry : join(dirname(workflowMdPath), entry);
+  let mod;
+  try {
+    mod = await import(pathToFileURL(abs).href);
+  } catch (err) {
+    throw new WorkflowLoadError(
+      `cannot import entry '${entry}': ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const exported = mod.default;
+  if (!isWorkflowHandle(exported)) {
+    throw new WorkflowLoadError(
+      `entry '${entry}' must default-export a WorkflowHandle (e.g. from defineWorkflow) carrying an 'id' + 'steps'; got ${exported === void 0 ? "no default export" : typeof exported}.`
+    );
+  }
+  return exported;
+}
+async function loadWorkflowHandle(workflowMdPath) {
+  let source;
+  try {
+    source = await readFile(workflowMdPath, "utf8");
+  } catch (err) {
+    throw new WorkflowLoadError(
+      `cannot read '${workflowMdPath}': ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const manifest = parseWorkflowManifest(source);
+  const entry = manifest.frontmatter.entry;
+  if (!entry) return workflowFromManifest(manifest);
+  const handle = await importEntryHandle(workflowMdPath, entry);
+  reconcileEntry(manifest, handle);
+  return handle;
+}
+
+export { WorkflowLoadError, WorkflowReconcileError, loadWorkflowHandle, reconcileEntry };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/reconcile.ts","../src/load-workflow.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Reconcile a WORKFLOW.md manifest against the handle its `entry` module\n * exports. An entry-backed workflow declares its step graph twice — once as\n * governance-facing manifest data, once as the runnable handle — so the two\n * MUST agree, or the manifest is lying about what actually runs. This checks\n * the workflow id and the top-level step (id, kind) sequence; nested step\n * lists (map / loop / parallel bodies) are the entry's concern.\n */\n\nimport type { WorkflowManifest } from \"@agentproto/workflow/manifest\"\nimport type { WorkflowHandle } from \"@agentproto/workflow\"\n\nexport class WorkflowReconcileError extends Error {\n  constructor(message: string) {\n    super(`reconcileEntry: ${message}`)\n    this.name = \"WorkflowReconcileError\"\n  }\n}\n\ninterface IdKind {\n  readonly id: string\n  readonly kind: string\n}\n\nconst idKind = (steps: readonly IdKind[]): IdKind[] =>\n  steps.map((s) => ({ id: s.id, kind: s.kind }))\n\nconst summary = (steps: readonly IdKind[]): string =>\n  steps.map((s) => `${s.id}:${s.kind}`).join(\" → \") || \"(none)\"\n\nexport function reconcileEntry(\n  manifest: WorkflowManifest,\n  handle: WorkflowHandle,\n): void {\n  const fm = manifest.frontmatter\n  if (fm.id !== handle.id) {\n    throw new WorkflowReconcileError(\n      `manifest id '${fm.id}' ≠ entry id '${handle.id}'.`,\n    )\n  }\n  const declared = idKind(fm.steps as readonly IdKind[])\n  const actual = idKind(handle.steps as readonly IdKind[])\n  if (declared.length !== actual.length) {\n    throw new WorkflowReconcileError(\n      `step count differs — manifest declares ${declared.length} [${summary(declared)}], ` +\n        `entry has ${actual.length} [${summary(actual)}].`,\n    )\n  }\n  for (let i = 0; i < declared.length; i++) {\n    const d = declared[i]!\n    const a = actual[i]!\n    if (d.id !== a.id || d.kind !== a.kind) {\n      throw new WorkflowReconcileError(\n        `step ${i} differs — manifest '${d.id}:${d.kind}' ≠ entry '${a.id}:${a.kind}'. ` +\n          `manifest [${summary(declared)}] vs entry [${summary(actual)}].`,\n      )\n    }\n  }\n}\n","/**\n * loadWorkflowHandle — read a WORKFLOW.md off disk into a WorkflowHandle.\n *\n * The pure packages stop at the page boundary: `@agentproto/workflow` parses a\n * manifest *string*, `@agentproto/workflow-runtime` compiles an in-memory\n * handle. Neither touches the filesystem. This is the host-side seam that does:\n *\n *   read file → parse manifest → (if `entry`) import the module + reconcile\n *\n * With no `entry`, the manifest IS the workflow (purely-declarative path). With\n * an `entry`, its default-exported handle is the source of truth for runtime\n * step logic and the manifest is reconciled against it — the two MUST agree.\n *\n * The entry import mirrors the CLI's adapter loader: resolve relative to the\n * manifest's directory, import via a `file://` URL so an absolute path works\n * without an `exports` declaration.\n */\n\nimport { readFile } from \"node:fs/promises\"\nimport { dirname, isAbsolute, join } from \"node:path\"\nimport { pathToFileURL } from \"node:url\"\n\nimport {\n  parseWorkflowManifest,\n  workflowFromManifest,\n  type WorkflowManifest,\n} from \"@agentproto/workflow/manifest\"\nimport type { WorkflowHandle } from \"@agentproto/workflow\"\n\nimport { reconcileEntry } from \"./reconcile.js\"\n\nexport class WorkflowLoadError extends Error {\n  constructor(message: string) {\n    super(`loadWorkflow: ${message}`)\n    this.name = \"WorkflowLoadError\"\n  }\n}\n\n/** A handle is a plain object carrying an `id` and a `steps` array. */\nfunction isWorkflowHandle(v: unknown): v is WorkflowHandle {\n  return (\n    typeof v === \"object\" &&\n    v !== null &&\n    typeof (v as { id?: unknown }).id === \"string\" &&\n    Array.isArray((v as { steps?: unknown }).steps)\n  )\n}\n\nasync function importEntryHandle(\n  workflowMdPath: string,\n  entry: string,\n): Promise<WorkflowHandle> {\n  const abs = isAbsolute(entry) ? entry : join(dirname(workflowMdPath), entry)\n  let mod: Record<string, unknown>\n  try {\n    mod = (await import(pathToFileURL(abs).href)) as Record<string, unknown>\n  } catch (err) {\n    throw new WorkflowLoadError(\n      `cannot import entry '${entry}': ${err instanceof Error ? err.message : String(err)}`,\n    )\n  }\n  const exported = mod.default\n  if (!isWorkflowHandle(exported)) {\n    throw new WorkflowLoadError(\n      `entry '${entry}' must default-export a WorkflowHandle (e.g. from defineWorkflow) ` +\n        `carrying an 'id' + 'steps'; got ${exported === undefined ? \"no default export\" : typeof exported}.`,\n    )\n  }\n  return exported\n}\n\n/**\n * Load and validate a WORKFLOW.md at `workflowMdPath` into a WorkflowHandle.\n * Throws {@link WorkflowLoadError} on a missing/unreadable file or a bad entry\n * module, the parser's error on invalid frontmatter, and\n * {@link WorkflowReconcileError} when an entry's graph disagrees with the\n * manifest. The returned handle still needs `compileWorkflow` + a tool registry\n * to run — this stops at the validated, in-memory handle.\n */\nexport async function loadWorkflowHandle(\n  workflowMdPath: string,\n): Promise<WorkflowHandle> {\n  let source: string\n  try {\n    source = await readFile(workflowMdPath, \"utf8\")\n  } catch (err) {\n    throw new WorkflowLoadError(\n      `cannot read '${workflowMdPath}': ${err instanceof Error ? err.message : String(err)}`,\n    )\n  }\n  const manifest: WorkflowManifest = parseWorkflowManifest(source)\n  const entry = manifest.frontmatter.entry\n  if (!entry) return workflowFromManifest(manifest)\n  const handle = await importEntryHandle(workflowMdPath, entry)\n  reconcileEntry(manifest, handle)\n  return handle\n}\n"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@agentproto/workflow-loader",
+  "version": "0.1.0-alpha.0",
+  "description": "Host-side loader for AIP-15 WORKFLOW.md: reads a manifest off disk, imports its optional TypeScript entry module, and reconciles the entry's step graph against the declared manifest. The I/O layer the pure @agentproto/workflow + @agentproto/workflow-runtime packages deliberately omit.",
+  "keywords": [
+    "agentproto",
+    "aip-15",
+    "workflow",
+    "loader",
+    "manifest",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-15",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentproto/workflow": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "zod": "^4.4.3",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}