@cloudhal/agent-runtime 0.0.0-stage → 0.1.1

package/dist/src/taxonomy.js

@@ -0,0 +1,78 @@
+/**
+ * Agent-layer rules for taxonomies and redirects (RFC-0002 §6.4). Data invariants (limits, required
+ * terms, slugs) live in core-ts; what an *agent* may do — create terms, point redirects off-site,
+ * approve proposals — is decided here, the same for every transport.
+ */
+                                                      
+import { holds,                } from "./policy.js";
+
+/** `Taxonomy.allowNewTerms`. */
+                                                        
+
+/** What a term created by an actor becomes, or why it may not be created. */
+                          
+                                                                      
+                                                         
+
+/**
+ * Invariant 11 for an actor: people (and the system) create active terms; agents create proposed
+ * terms under `propose`, active ones under `free`, and none under `none` ("ask a person").
+ *
+ * Given a principal, a person whose role lacks `site:write` (Contributor, Author; RFC-0005 §2.2) is
+ * treated like an agent: they propose tags and never add categories.
+ */
+export function termCreation(
+  who                                             ,
+  allowNewTerms               ,
+)               {
+  const actor = "actor" in who ? who.actor : who;
+  const governs = "actor" in who ? holds(who.scopes, "site:write") : true;
+  if (actor.kind !== "agent" && governs) return { allowed: true, status: "active" };
+  switch (allowNewTerms) {
+    case "free":
+      return { allowed: true, status: "active" };
+    case "propose":
+      return { allowed: true, status: "proposed" };
+    case "none":
+      return {
+        allowed: false,
+        reason: "only people add terms to this taxonomy; ask a person (Cloudhal Studio)",
+      };
+  }
+}
+
+/**
+ * Why an actor may not point a redirect at `to`, or undefined. Agents redirect to paths of the same
+ * site only; an external target (open-redirect risk) is a person's decision (RFC-0002, Security).
+ */
+export function redirectTargetProblem(actor       , to        )                     {
+  if (actor.kind !== "agent") return undefined;
+  if (!to.startsWith("/") || to.startsWith("//") || to.includes("\\"))
+    return "agents may only redirect to a path on this site (starting with a single '/'); an external target needs a person in Cloudhal Studio";
+  return undefined;
+}
+
+/** A review decision on a proposed term. */
+                                                                
+
+/**
+ * Why an actor may not take a review decision on a term, or undefined. An agent never approves a
+ * term it proposed itself (the person's review is the point of `propose`).
+ */
+export function termReviewProblem(
+  actor       ,
+  term                                             ,
+  decision                    ,
+)                     {
+  if (actor.kind !== "agent" || decision !== "approve") return undefined;
+  if (term.proposedBy?.kind === "agent" && term.proposedBy.id === actor.id)
+    return "an agent cannot approve a term it proposed; a person reviews it in Cloudhal Studio";
+  return undefined;
+}
+
+/** Freeing an old slug (`reclaim`) deletes a redirect people may rely on: people only. */
+export function reclaimProblem(actor       )                     {
+  return actor.kind === "agent"
+    ? "reclaiming a slug from a term's history is for people only; choose another slug"
+    : undefined;
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@cloudhal/agent-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Cloudhal agent runtime: policy engine (actors, scopes, approvals), skill loader, audit log",
+  "license": "Apache-2.0",
+  "homepage": "https://cloudhal.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudhal-dev/cloudhal.git",
+    "directory": "packages/agent-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/cloudhal-dev/cloudhal/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@cloudhal/core-contracts": "0.1.1",
+    "@cloudhal/storage": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "better-sqlite3": "13.0.3",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm test"
+  }
 }