@cloudhal/agent-runtime 0.0.0-stage → 0.1.1

package/dist/src/modes.js

@@ -0,0 +1,279 @@
+/**
+ * Agent modes (ADR-0015): how independently an agent works, chosen per API key by its owner —
+ * the same idea as an IDE agent's permission modes. A mode never grants scopes; it narrows what
+ * the key's scopes allow and decides where a person must approve.
+ */
+                                         
+
+                                                                        
+
+/** In order of increasing autonomy. */
+export const AGENT_MODES                       = ["plan", "manual", "edits", "auto", "bypass"];
+
+/** What existing keys and new keys without a choice get. */
+export const DEFAULT_AGENT_MODE            = "edits";
+
+/** Modes a remote (HTTP, API key) agent may hold. `bypass` is for local stdio only. */
+export const REMOTE_AGENT_MODES                       = ["plan", "manual", "edits", "auto"];
+
+export function isAgentMode(value         )                     {
+  return typeof value === "string" && (AGENT_MODES                     ).includes(value);
+}
+
+/** The scopes a key needs to be useful in a mode (offered by default when creating one). */
+export function scopesForMode(mode           )          {
+  // `analytics:read` is read-only and carries no personal data: every mode, plan included (RFC-0006).
+  // `comments:read` likewise: reader text, never an email or IP hash (RFC-0007 D2).
+  const read          = [
+    "site:read",
+    "content:read",
+    "preview:create",
+    "analytics:read",
+    "comments:read",
+    // RFC-0008 §10.1: the schedule, read-only, in every mode.
+    "schedules:read",
+  ];
+  // RFC-0014 §5 (ADR-0028): a plan key may propose body edits; they change nothing until a person
+  // accepts them. Other modes get it through `content:write`.
+  if (mode === "plan") return [...read, "content:propose"];
+  // `asset:upload` is part of the default agent-key scopes outside plan (RFC-0004, ADR-0018);
+  // `schedules:write` lets the agent propose and ask for releases (RFC-0008 §10.1).
+  return [
+    ...read,
+    "content:write",
+    "asset:upload",
+    "site:publish",
+    "site:rollback",
+    "schedules:write",
+  ];
+}
+
+/** Limits for an `auto`-mode publish that goes live without a person (see `isLowRiskPublish`). */
+export const AUTO_PUBLISH_LIMIT = 20;
+
+                                
+             
+               
+ 
+
+/** Why `auto` mode did or did not let a publish through, as data (Studio words it itself). */
+                           
+              
+                     
+             
+               
+              
+                                                                              
+           
+                                                                                                   
+                    
+                                                                                                 
+                 
+
+/** The `auto`-mode check behind a publish (stored on audit rows and approvals, ADR-0015). */
+                            
+                                                                                          
+                                                
+                   
+                      
+                                                                            
+                  
+                                                       
+                
+ 
+
+const AUTO_CHECK_TEXT                                                  = {
+  "low-risk": (c) => `${c.changes} article change(s) only`,
+  "removes-content": () => "it removes content",
+  nothing: () => "nothing to publish",
+  structure: () => "it changes pages, menus, site settings, taxonomies or redirects",
+  "too-many": (c) => `it changes more than ${c.limit} articles`,
+  media: () => "it adds or changes media that is not part of an article change",
+  "outside-window": () =>
+    "it would run after your autonomy ends (the elevation's end, or 24 hours from now)",
+  correction: () => "it adds a correction to a published article",
+};
+
+/** English wording of a check, for agents and audit reasons. */
+export function describeAutoCheck(check           )         {
+  return AUTO_CHECK_TEXT[check.code](check);
+}
+
+/**
+ * Low risk = only articles added or edited, nothing removed, no pages, menus, site settings,
+ * taxonomies, terms or redirects touched (RFC-0002 §6.4, RFC-0003 §6.4), and at most `AUTO_PUBLISH_LIMIT` changes. Anything
+ * else waits for a person even in `auto`.
+ *
+ * Media (RFC-0004 §6.3, answer 1): an added asset whose id is in `ridingAssets` (a new raster
+ * image used only by articles in the same publish; the store decides) goes out with them and does
+ * not count toward the limit. Any other asset change is `media` and waits for a person.
+ *
+ * Corrections (RFC-0019 §2.4): an entry in `corrections` (it adds a correction to its live
+ * version; the store decides) makes the publish wait for a person.
+ */
+export function checkAutoPublish(
+  diff   
+                           
+                                        
+                             
+   ,
+  options                                                                            = {},
+)            {
+  const riding = options.ridingAssets ?? new Set        ();
+  const corrects = options.corrections ?? new Set        ();
+  const rides = (n               ) => n.kind === "asset" && riding.has(n.id);
+  const added = diff.added.filter((n) => !rides(n));
+  const touched = [...added, ...diff.changed.map((c) => c.after)];
+  const base = {
+    rule: "low-risk-publish"         ,
+    changes: touched.length + diff.removed.length,
+    limit: AUTO_PUBLISH_LIMIT,
+  };
+  const media = touched.some((n) => n.kind === "asset");
+  const code                =
+    diff.removed.length > 0
+      ? "removes-content"
+      : touched.length === 0
+        ? "nothing"
+        : touched.some((n) => n.kind !== "contentEntry" && n.kind !== "asset")
+          ? "structure"
+          : media
+            ? "media"
+            : touched.some((n) => corrects.has(n.id))
+              ? "correction"
+              : touched.length > AUTO_PUBLISH_LIMIT
+                ? "too-many"
+                : "low-risk";
+  return { ...base, code, lowRisk: code === "low-risk" };
+}
+
+/**
+ * Time-boxed elevation (ADR-0016): the owner lets a key work in a more autonomous mode until
+ * `until`; afterwards it is back in its own mode without anyone doing anything (the effective mode
+ * is computed on every call).
+ */
+                                
+                  
+                                     
+                
+                                               
+                    
+                    
+                                                                   
+                              
+ 
+
+/** Shortest and longest elevation an owner can grant. */
+export const ELEVATION_MIN_MINUTES = 5;
+export const ELEVATION_MAX_MINUTES = 24 * 60;
+
+/** `a` lets the agent do more on its own than `b` (AGENT_MODES order). */
+export function isMoreAutonomous(a           , b           )          {
+  return AGENT_MODES.indexOf(a) > AGENT_MODES.indexOf(b);
+}
+
+/**
+ * Why an elevation request is refused, or undefined when it is acceptable: a remote mode more
+ * autonomous than the key's own, for between `ELEVATION_MIN_MINUTES` and `ELEVATION_MAX_MINUTES`.
+ */
+export function elevationProblem(
+  base           ,
+  mode           ,
+  minutes        ,
+)                     {
+  if (!REMOTE_AGENT_MODES.includes(mode))
+    return `mode "${mode}" is not available for API keys (bypass is local only)`;
+  if (!isMoreAutonomous(mode, base))
+    return `an elevation must be more autonomous than the key's own mode (${base})`;
+  if (
+    !Number.isInteger(minutes) ||
+    minutes < ELEVATION_MIN_MINUTES ||
+    minutes > ELEVATION_MAX_MINUTES
+  )
+    return `minutes must be a whole number between ${ELEVATION_MIN_MINUTES} and ${ELEVATION_MAX_MINUTES}`;
+  return undefined;
+}
+
+/** The elevation that applies right now, if any (expired or no-longer-higher ones do not). */
+export function activeElevation(
+  base           ,
+  elevation                           ,
+  now      ,
+)                            {
+  if (!elevation || !REMOTE_AGENT_MODES.includes(elevation.mode)) return undefined;
+  if (!isMoreAutonomous(elevation.mode, base)) return undefined;
+  const until = Date.parse(elevation.until);
+  return Number.isFinite(until) && until > now.getTime() ? elevation : undefined;
+}
+
+/** How long before an elevation ends that owners and the agent are told (Studio notifications, `get_mode`). */
+export const ELEVATION_NOTICE_MINUTES = 10;
+
+/** Whole minutes left until `until` (rounded up; 0 once it has ended). */
+export function minutesLeft(until        , now      )         {
+  const ms = Date.parse(until) - now.getTime();
+  return Number.isFinite(ms) && ms > 0 ? Math.ceil(ms / 60_000) : 0;
+}
+
+/** True during the last `ELEVATION_NOTICE_MINUTES` of an elevation. */
+export function endsSoon(until        , now      )          {
+  const left = minutesLeft(until, now);
+  return left > 0 && left <= ELEVATION_NOTICE_MINUTES;
+}
+
+/** The longest an `auto`-mode release may wait without a person (RFC-0008 §10.7, D9). */
+export const AUTO_RELEASE_WINDOW_HOURS = 24;
+
+/** A release item as the low-risk check sees it (RFC-0008 §10.3). */
+                                  
+                         
+                 
+                   
+                                                      
+                
+                                                                      
+                           
+                                                                         
+                     
+ 
+
+/**
+ * `checkAutoPublish` applied to a release (RFC-0008 §10.3): articles only, nothing removed, at most
+ * `AUTO_PUBLISH_LIMIT` changes; a new asset rides along when an article item of the same release
+ * references it.
+ */
+export function checkAutoRelease(items                            )            {
+  const riding = new Set        ();
+  for (const i of items)
+    if (i.kind === "set" && i.nodeKind === "contentEntry")
+      for (const d of i.deps ?? []) riding.add(d);
+  const ref = (i                 ) => ({ id: i.nodeId, kind: i.nodeKind });
+  const set = items.filter((i) => i.kind === "set");
+  const check = checkAutoPublish(
+    {
+      added: set.filter((i) => !i.live).map(ref),
+      changed: set.filter((i) => i.live).map((i) => ({ after: ref(i) })),
+      removed: items.filter((i) => i.kind === "remove").map(ref),
+    },
+    {
+      ridingAssets: new Set(
+        set
+          .filter((i) => i.nodeKind === "asset" && !i.live && riding.has(i.nodeId))
+          .map((i) => i.nodeId),
+      ),
+      corrections: new Set(set.filter((i) => i.corrects).map((i) => i.nodeId)),
+    },
+  );
+  return { ...check, rule: "low-risk-release" };
+}
+
+/**
+ * The latest an `auto`-mode release may run and still go ahead without a person (RFC-0008 §10.7,
+ * D9): the end of the key's elevation (when `auto` comes from one) or 24 hours from now, whichever
+ * comes first.
+ */
+export function autoReleaseWindowEnds(now      , elevationUntil         )         {
+  const day = now.getTime() + AUTO_RELEASE_WINDOW_HOURS * 3_600_000;
+  const until = elevationUntil ? Date.parse(elevationUntil) : Number.NaN;
+  return new Date(Number.isFinite(until) ? Math.min(day, until) : day).toISOString();
+}

package/dist/src/ownership.d.ts

@@ -0,0 +1,76 @@
+/**
+ * "Own" (RFC-0005 §4): who owns an entry, what an own-limited caller may do to it, and when a change
+ * set is own-only. REST handlers and MCP tool handlers use the same helpers (I9, I10).
+ */
+import type { Actor, ContentEntry, NodeRef } from "@cloudhal/core-contracts";
+import type { OwnLimit } from "./policy.js";
+/**
+ * Maps an actor to the person behind it (an actor id `user_…`): a person is themselves, an agent is
+ * the person whose key it used (RFC-0005 §4), `system` is nobody. Server-side for now; the optional
+ * contract field `Actor.onBehalfOf` (RFC-0005 §8) is a follow-up.
+ */
+export interface OwnershipResolver {
+    personOf(actor: Actor): Promise<string | undefined>;
+}
+/** People are themselves; agents and the system resolve to nobody (no membership source). */
+export declare const PEOPLE_ONLY_OWNERSHIP: OwnershipResolver;
+export type OwnProblemCode = "not_own" | "draft_only" | "author_immutable" | "no_person";
+/** An own-limited caller tried something outside its limit (REST 403, MCP `denied`). */
+export declare class OwnLimitError extends Error {
+    readonly name = "OwnLimitError";
+    readonly code: OwnProblemCode;
+    constructor(code: OwnProblemCode, message: string);
+}
+type EntryState = Pick<ContentEntry, "author" | "status"> & {
+    publishedAt?: string | undefined;
+};
+/** Never published and still a draft or in review (what a Contributor may touch). */
+export declare function isUnpublishedDraft(entry: EntryState): boolean;
+/** Is `person` an owner of `entry` (its `author`, or the person behind it)? */
+export declare function ownsEntry(owner: OwnershipResolver, person: string, entry: Pick<ContentEntry, "author">): Promise<boolean>;
+/**
+ * Checks an entry write against an own limit (I9). No limit: nothing to check.
+ * - create: the new entry's author is the caller; `draft` also keeps it a draft or in review;
+ * - update: the caller owns the stored entry, `author` is unchanged, and `draft` needs a
+ *   never-published entry that stays draft/review;
+ * - delete: the caller owns it; `draft` needs a never-published entry.
+ */
+export declare function checkEntryLimit(input: {
+    limit: OwnLimit | undefined;
+    op: "create" | "update" | "delete";
+    person: string | undefined;
+    owner: OwnershipResolver;
+    stored?: EntryState | undefined;
+    next?: EntryState | undefined;
+}): Promise<void>;
+/** A diff between the live state and what would go live (core-ts `SnapshotDiff`). */
+export interface ChangeSet {
+    readonly added: readonly NodeRef[];
+    readonly removed: readonly NodeRef[];
+    readonly changed: readonly {
+        readonly before: NodeRef;
+        readonly after: NodeRef;
+    }[];
+}
+/** Reads the two sides of a change set (snapshot blobs, or the current node for "after"). */
+export interface ChangeSetReader {
+    before(ref: NodeRef): Promise<unknown>;
+    after(ref: NodeRef): Promise<unknown>;
+}
+export interface OwnOnlyResult {
+    ownOnly: boolean;
+    /** Structure changed (pages, site, taxonomies, terms, redirects, menus, assets…). */
+    structure: boolean;
+    /** Publicly visible entries the person does not own. */
+    foreign: string[];
+}
+/**
+ * Is a change set own-only for `person` (RFC-0005 §4)? Every publicly visible change must be an
+ * entry they own: entries published before or after count, entries draft/review on both sides are
+ * ignored, and any other node kind (except a site node that only moved its live pointer) makes it
+ * not own-only.
+ */
+export declare function ownOnlyChangeSet(diff: ChangeSet, person: string | undefined, owner: OwnershipResolver, read: ChangeSetReader): Promise<OwnOnlyResult>;
+/** English reason a change set is not own-only (for agents and approval prompts). */
+export declare function describeOwnOnly(result: OwnOnlyResult): string;
+export {};

package/dist/src/ownership.js

@@ -0,0 +1,200 @@
+/**
+ * "Own" (RFC-0005 §4): who owns an entry, what an own-limited caller may do to it, and when a change
+ * set is own-only. REST handlers and MCP tool handlers use the same helpers (I9, I10).
+ */
+                                                                                   
+                                            
+
+/**
+ * Maps an actor to the person behind it (an actor id `user_…`): a person is themselves, an agent is
+ * the person whose key it used (RFC-0005 §4), `system` is nobody. Server-side for now; the optional
+ * contract field `Actor.onBehalfOf` (RFC-0005 §8) is a follow-up.
+ */
+                                    
+                                                      
+ 
+
+/** People are themselves; agents and the system resolve to nobody (no membership source). */
+export const PEOPLE_ONLY_OWNERSHIP                    = {
+  async personOf(actor) {
+    return actor.kind === "human" ? actor.id : undefined;
+  },
+};
+
+                                                                                         
+
+/** An own-limited caller tried something outside its limit (REST 403, MCP `denied`). */
+export class OwnLimitError extends Error {
+                    name = "OwnLimitError";
+           code                ;
+  constructor(code                , message        ) {
+    super(message);
+    this.code = code;
+  }
+}
+
+                                                                                                 
+
+/** Never published and still a draft or in review (what a Contributor may touch). */
+export function isUnpublishedDraft(entry            )          {
+  return !entry.publishedAt && (entry.status === "draft" || entry.status === "review");
+}
+
+function sameActor(a       , b       )          {
+  return a.kind === b.kind && a.id === b.id;
+}
+
+/** Is `person` an owner of `entry` (its `author`, or the person behind it)? */
+export async function ownsEntry(
+  owner                   ,
+  person        ,
+  entry                              ,
+)                   {
+  return (await owner.personOf(entry.author)) === person;
+}
+
+/**
+ * Checks an entry write against an own limit (I9). No limit: nothing to check.
+ * - create: the new entry's author is the caller; `draft` also keeps it a draft or in review;
+ * - update: the caller owns the stored entry, `author` is unchanged, and `draft` needs a
+ *   never-published entry that stays draft/review;
+ * - delete: the caller owns it; `draft` needs a never-published entry.
+ */
+export async function checkEntryLimit(input   
+                              
+                                     
+                             
+                           
+                                  
+                                
+ )                {
+  const { limit, op, person, owner, stored, next } = input;
+  if (limit?.target !== "entry") return;
+  if (!person)
+    throw new OwnLimitError("no_person", "ownership cannot be established for this caller");
+  const draft = limit.level === "draft";
+  const stayDraft = (e                        ) => {
+    if (draft && e && !isUnpublishedDraft(e))
+      throw new OwnLimitError(
+        "draft_only",
+        "your role can only keep articles as drafts or send them for review; an Editor publishes them",
+      );
+  };
+  if (op === "create") {
+    if (next && !(await ownsEntry(owner, person, next)))
+      throw new OwnLimitError(
+        "author_immutable",
+        "your role cannot file articles for someone else",
+      );
+    stayDraft(next);
+    return;
+  }
+  if (!stored) return;
+  if (!(await ownsEntry(owner, person, stored)))
+    throw new OwnLimitError("not_own", "your role can only change your own articles");
+  if (draft && !isUnpublishedDraft(stored))
+    throw new OwnLimitError(
+      "draft_only",
+      "this article was published; only an Editor (or its Author) can change it now",
+    );
+  if (op === "update" && next) {
+    if (!sameActor(stored.author, next.author))
+      throw new OwnLimitError("author_immutable", "your role cannot change an article's author");
+    stayDraft(next);
+  }
+}
+
+/** A diff between the live state and what would go live (core-ts `SnapshotDiff`). */
+                            
+                                     
+                                       
+                                                                                     
+ 
+
+/** Reads the two sides of a change set (snapshot blobs, or the current node for "after"). */
+                                  
+                                         
+                                        
+ 
+
+                                
+                   
+                                                                                       
+                     
+                                                          
+                    
+ 
+
+function isPublished(node         )          {
+  return (node                                    )?.status === "published";
+}
+
+/** JSON with object keys sorted at every level (stable comparison). */
+function stable(value         )         {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (value && typeof value === "object")
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stable((value                           )[k])}`)
+      .join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+/** The site node without what publishing itself rewrites (pointer, rev, timestamp). */
+function stripSite(site      )         {
+  const { publishedSnapshotId: _p, rev: _r, updatedAt: _u, ...rest } = site;
+  return stable(rest);
+}
+
+/**
+ * Is a change set own-only for `person` (RFC-0005 §4)? Every publicly visible change must be an
+ * entry they own: entries published before or after count, entries draft/review on both sides are
+ * ignored, and any other node kind (except a site node that only moved its live pointer) makes it
+ * not own-only.
+ */
+export async function ownOnlyChangeSet(
+  diff           ,
+  person                    ,
+  owner                   ,
+  read                 ,
+)                         {
+  const foreign           = [];
+  let structure = false;
+  const owned = async (node         ) =>
+    person !== undefined &&
+    (await ownsEntry(owner, person, node                                ).catch(() => false));
+  const entry = async (id        , before         , after         ) => {
+    if (!isPublished(before) && !isPublished(after)) return;
+    for (const side of [before, after])
+      if (side !== undefined && !(await owned(side))) {
+        if (!foreign.includes(id)) foreign.push(id);
+        return;
+      }
+  };
+  for (const ref of diff.added) {
+    if (ref.kind !== "contentEntry") structure = true;
+    else await entry(ref.id, undefined, await read.after(ref));
+  }
+  for (const ref of diff.removed) {
+    if (ref.kind !== "contentEntry") structure = true;
+    else await entry(ref.id, await read.before(ref), undefined);
+  }
+  for (const c of diff.changed) {
+    if (c.after.kind === "site") {
+      const [a, b] = [await read.before(c.before), await read.after(c.after)];
+      if (!a || !b || stripSite(a        ) !== stripSite(b        )) structure = true;
+      continue;
+    }
+    if (c.after.kind !== "contentEntry") structure = true;
+    else await entry(c.after.id, await read.before(c.before), await read.after(c.after));
+  }
+  return { ownOnly: !structure && foreign.length === 0, structure, foreign };
+}
+
+/** English reason a change set is not own-only (for agents and approval prompts). */
+export function describeOwnOnly(result               )         {
+  if (result.ownOnly) return "every public change is your own";
+  if (result.structure)
+    return "it changes pages, site settings, taxonomies, terms or redirects, which needs an Editor";
+  return `it includes ${result.foreign.length} published article(s) by someone else, which needs an Editor`;
+}