@mamund/grail 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@mamund/grail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A runtime for pursuing goals within bounded environments of available capabilities.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "grail": "./cli/grail-cli.js"
+  },
+  "scripts": {
+    "test": "node test/run-all.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agents",
+    "autonomous-agents",
+    "agentic",
+    "runtime",
+    "orchestration",
+    "affordances"
+  ],
+  "author": "Mike Amundsen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mamund/grail-release.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mamund/grail-release/issues"
+  },
+  "homepage": "https://github.com/mamund/grail-release#readme",
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "grail.js",
+    "client.js",
+    "server.js",
+    "affordanceModel.js",
+    "affordanceRegistry.js",
+    "observationStore.js",
+    "worldState.js",
+    "bindings/",
+    "cli/",
+    "config-loader/",
+    "utils/",
+    "schemas/",
+    "docs/",
+    "examples/cli-tour/",
+    "images/"
+  ]
+}

package/schemas/goal.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Goal File",
+  "type": "object",
+  "required": ["goal"],
+  "additionalProperties": false,
+  "properties": {
+    "goal": {
+      "type": "string",
+      "description": "The name of the final goal affordance to pursue"
+    }
+  }
+}
+

package/schemas/inputs.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": true
+}
+

package/schemas/observations.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "GRAIL Observations",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "invocation",
+      "response",
+      "outputs",
+      "result"
+    ],
+    "properties": {
+      "invocation": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "affordance",
+          "timestamp",
+          "request"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "affordance": {
+            "type": "string",
+            "minLength": 1
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "request": {
+            "type": "object"
+          }
+        }
+      },
+      "response": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "status",
+          "headers",
+          "body"
+        ],
+        "properties": {
+          "status": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "headers": {
+            "type": "object"
+          },
+          "body": {}
+        }
+      },
+      "outputs": {
+        "type": "object"
+      },
+      "result": {
+        "type": "string",
+        "enum": [
+          "SUCCESS",
+          "BLOCKED",
+          "FAIL"
+        ]
+      }
+    }
+  }
+}

package/schemas/registry.schema.json

@@ -0,0 +1,285 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Affordance Registry",
+  "type": "object",
+  "additionalProperties": {
+    "type": "object",
+    "required": [
+      "id",
+      "action",
+      "type",
+      "preconditions",
+      "inputs",
+      "effects"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "id": {
+        "type": "string"
+      },
+      "action": {
+        "type": "string"
+      },
+      "type": {
+        "type": "string",
+        "enum": [
+          "task"
+        ]
+      },
+      "preconditions": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "inputs": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "effects": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "execute": {
+        "type": "object",
+        "required": [
+          "type",
+          "name"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "function"
+            ]
+          },
+          "name": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      },
+      "binding": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "protocol",
+              "method",
+              "url"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "protocol": {
+                "type": "string",
+                "enum": [
+                  "http"
+                ]
+              },
+              "method": {
+                "type": "string",
+                "enum": [
+                  "GET",
+                  "POST",
+                  "PUT",
+                  "PATCH",
+                  "DELETE"
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "contentType": {
+                "type": "string",
+                "enum": [
+                  "application/json",
+                  "application/x-www-form-urlencoded"
+                ]
+              },
+              "parameters": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "required": [
+                    "in"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "in": {
+                      "type": "string",
+                      "enum": [
+                        "path",
+                        "query",
+                        "header",
+                        "body"
+                      ]
+                    },
+                    "name": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              },
+              "outputs": {
+                "type": "object",
+                "additionalProperties": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "required": [
+                        "from",
+                        "path"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "from": {
+                          "const": "body"
+                        },
+                        "path": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "from",
+                        "name"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "from": {
+                          "const": "header"
+                        },
+                        "name": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "required": [
+                        "from"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "from": {
+                          "const": "status"
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "protocol",
+              "module",
+              "function"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "protocol": {
+                "const": "node"
+              },
+              "module": {
+                "type": "string",
+                "minLength": 1
+              },
+              "function": {
+                "type": "string",
+                "minLength": 1
+              },
+              "outputs": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "required": [
+                    "from",
+                    "path"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "const": "result"
+                    },
+                    "path": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "protocol",
+              "command"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "protocol": {
+                "const": "stdio"
+              },
+              "command": {
+                "type": "string",
+                "minLength": 1
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "outputs": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "required": [
+                    "from",
+                    "path"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "const": "stdout"
+                    },
+                    "path": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/schemas/worldstate.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": {
+    "type": "boolean"
+  }
+}

package/server.js

@@ -0,0 +1,201 @@
+import { executeBinding } from "./bindings/binding.js";
+
+// server.js (generic broker)
+export class Server {
+  constructor(worldState, affordanceRegistry, observationStore, baseDir = process.cwd()) {
+    this.worldState = worldState;
+    this.affordanceRegistry = affordanceRegistry;
+    this.observationStore = observationStore;
+    this.baseDir = baseDir;
+  }
+
+  async attempt(affordance, inputs) {
+    console.log(`\n[SERVER] Attempting affordance: ${affordance.action}`);
+
+    const unmetPreconditions = affordance.preconditions.filter(
+      pre => !this.worldState.isPreconditionMet(pre)
+    );
+
+    if (unmetPreconditions.length > 0) {
+      const pre = this.selectUnmetCondition(unmetPreconditions);
+
+      console.log(`[SERVER] Blocked: selected unmet precondition: ${pre}`);
+
+      const candidates = this.findAffordancesForCondition(pre);
+      const nextAffordance = this.selectAffordance(candidates);
+
+      if (nextAffordance) {
+        return {
+          result: "BLOCKED",
+          condition: pre,
+          offeredAffordances: [nextAffordance]
+        };
+      }
+
+      return {
+        result: "BLOCKED",
+        condition: pre,
+        offeredAffordances: []
+      };
+    }
+
+    const resolvedInputs = {};
+
+    for (const [inputName, source] of Object.entries(affordance.inputs)) {
+      const resolution = this.resolveInput(source, inputs);
+
+      if (!resolution.resolved) {
+        console.log(`[SERVER] Blocked: missing input: ${inputName}`);
+
+        return {
+          result: "BLOCKED",
+          offeredAffordances: []
+        };
+      }
+
+      resolvedInputs[inputName] = resolution.value;
+    }
+
+    if (
+      affordance.binding &&
+      affordance.binding.enabled !== false
+    ) {
+      const interaction = await executeBinding(
+        affordance.binding,
+        resolvedInputs,
+        this.baseDir
+      );
+
+      console.log(`[SERVER] Executing binding: ${interaction.description}`);
+
+      this.observationStore.append({
+        invocation: {
+          id: this.observationStore.nextInvocationId(),
+          affordance: affordance.action,
+          timestamp: new Date().toISOString(),
+          ...interaction.invocation
+        },
+        response: interaction.response,
+        outputs: interaction.outputs,
+        result: interaction.ok ? "SUCCESS" : "FAIL"
+      });
+
+      if (!interaction.ok) {
+        console.log(`[SERVER] Binding failed: ${interaction.summary}`);
+
+        return {
+          result: "FAIL",
+          offeredAffordances: []
+        };
+      }
+
+      console.log(`[SERVER] Binding succeeded: ${interaction.summary}`);
+    }
+
+    console.log(
+      `[SERVER] Success: applying effects - ${affordance.effects}`
+    );
+
+    this.worldState.applyEffects(affordance.effects);
+
+    return {
+      result: "SUCCESS",
+      offeredAffordances: []
+    };
+  }
+
+  resolveGoal(goal) {
+    if (this.worldState.isPreconditionMet(goal)) {
+      return {
+        result: "SUCCESS",
+        offeredAffordances: []
+      };
+    }
+
+    const candidates = this.findAffordancesForCondition(goal);
+    const nextAffordance = this.selectAffordance(candidates);
+
+    if (nextAffordance) {
+      return {
+        result: "BLOCKED",
+        condition: goal,
+        offeredAffordances: [nextAffordance]
+      };
+    }
+
+    return {
+      result: "BLOCKED",
+      condition: goal,
+      offeredAffordances: []
+    };
+  }
+
+  resolveInput(source, inputs) {
+    const inputPrefix = "$inputs.";
+
+    if (source.startsWith(inputPrefix)) {
+      const inputName = source.slice(inputPrefix.length);
+
+      if (!inputName || !(inputName in inputs)) {
+        return { resolved: false };
+      }
+
+      return {
+        resolved: true,
+        value: inputs[inputName]
+      };
+    }
+
+    if (source.startsWith("$outputs.")) {
+      return this.observationStore.resolve(source);
+    }
+
+    return { resolved: false };
+  }
+
+  selectUnmetCondition(conditions) {
+    if (conditions.length === 0) {
+      return null;
+    }
+
+    return conditions[
+      Math.floor(Math.random() * conditions.length)
+    ];
+  }
+
+  selectAffordance(affordances) {
+    const eligible = affordances.filter(affordance => {
+      const observations =
+        this.observationStore.getByAffordance(affordance.action);
+
+      return !observations.some(
+        observation => observation.result === "FAIL"
+      );
+    });
+
+    if (eligible.length === 0) {
+      return null;
+    }
+
+    return eligible[
+      Math.floor(Math.random() * eligible.length)
+    ];
+  }
+
+  findAffordancesForCondition(condition) {
+    const candidates = [];
+
+    for (let key in this.affordanceRegistry) {
+      const candidate = this.affordanceRegistry[key];
+
+      if (
+        candidate.enabled !== false &&
+        candidate.effects.includes(condition)
+      ) {
+        candidates.push(candidate);
+      }
+    }
+
+    return candidates;
+  }
+}

package/utils/loadJSON.js

@@ -0,0 +1,33 @@
+// utils/loadJSON.js
+import fs from 'fs';
+import path from 'path';
+import { validateConfig } from './validateWithSchema.js';
+
+/**
+ * Load a JSON file from disk and parse it without validation.
+ * Use for legacy or optional config files.
+ *
+ * @param {string} filePath - Full path to the JSON file
+ * @returns {object} Parsed JSON content
+ */
+export function loadJSON(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Load and validate a JSON file using a provided schema.
+ * Throws an error on schema mismatch or parsing failure.
+ *
+ * @param {string} filePath - Full path to the JSON file
+ * @param {string} schemaName - File name of the schema in /schemas (e.g. "goal.schema.json")
+ * @returns {object} Parsed and validated JSON content
+ */
+export function loadAndValidateJSON(filePath, schemaName, { silent = false } = {}) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const json = JSON.parse(raw);
+  validateConfig(json, schemaName, path.basename(filePath), { silent });
+  return json;
+}
+
+