@cloudhal/agent-runtime 0.0.0-stage → 0.1.1

package/dist/src/audit.d.ts

@@ -0,0 +1,75 @@
+import type { Actor } from "@cloudhal/core-contracts";
+import type { SqlDriver } from "@cloudhal/storage";
+import type { AutoCheck } from "./modes.js";
+import type { ApprovalCause } from "./policy.js";
+export interface AuditEntry {
+    at: string;
+    actor: Actor;
+    siteId?: string | undefined;
+    tool: string;
+    decision: "allow" | "deny" | "approval-required";
+    reason?: string | undefined;
+    skill?: string | undefined;
+    input?: unknown;
+    outcome?: "ok" | "error" | "pending" | undefined;
+    snapshotId?: string | undefined;
+    durationMs?: number | undefined;
+    /** Agent mode the call ran under (ADR-0015). */
+    mode?: string | undefined;
+    /** Why the call waited for a person (`approval-required` rows). */
+    cause?: ApprovalCause | undefined;
+    /**
+     * The `auto`-mode check behind a publish: `lowRisk` on an `allow` row means it went live without
+     * a person; on an `approval-required` row it says why it waited.
+     */
+    autoCheck?: AutoCheck | undefined;
+    /** The call ran under a time-boxed elevation (ADR-0016): the key's own mode and the end. */
+    elevation?: {
+        from: string;
+        until: string;
+    } | undefined;
+    /** RFC-0008 §5.1, §11.7: the automation run a call belongs to (`audit.run_id`). */
+    runId?: string | undefined;
+    /** RFC-0008 §5.1: the release a row is about (`audit.release_id`). */
+    releaseId?: string | undefined;
+    /** RFC-0008 §11.5: the automation whose key made the call (`audit.automation_id`). */
+    automationId?: string | undefined;
+}
+export interface AuditRow extends AuditEntry {
+    id: number;
+}
+/** Inputs are stored as JSON; oversized ones become a valid `{ truncated, preview }` object. */
+export declare function auditInput(input: unknown): string | null;
+/** Append-only record of every policy decision and tool call (table `audit`, migration 0003). */
+export declare class AuditLog {
+    #private;
+    constructor(sql: SqlDriver);
+    /**
+     * The INSERT of one audit row as a statement, for writes that must put it in their own atomic
+     * `batch()`, last (RFC-0007 §4.4: a comment write and its audit row land together or not at all).
+     */
+    static statement(entry: AuditEntry): {
+        sql: string;
+        params: (string | number | null)[];
+    };
+    record(entry: AuditEntry): Promise<number>;
+    list(filter?: {
+        siteId?: string | undefined;
+        actorId?: string | undefined;
+        /** Only rows by one of these actors (a person's own rows and their keys' rows). */
+        actorIds?: readonly string[] | undefined;
+        /** Only deployment rows (no site: membership, invites, keys). */
+        deployment?: boolean | undefined;
+        /** Only rows of this tool (or event, e.g. `member.role`). */
+        tool?: string | undefined;
+        /** Only rows at or after this ISO time. */
+        since?: string | undefined;
+        /** Only rows older than this id (cursor pagination, newest first). */
+        before?: number | undefined;
+        /** RFC-0008 §11.7: only the rows of one automation run. */
+        runId?: string | undefined;
+        /** RFC-0008: only the rows about one release. */
+        releaseId?: string | undefined;
+        limit?: number | undefined;
+    }): Promise<AuditRow[]>;
+}

package/dist/src/audit.js

@@ -0,0 +1,209 @@
+                                                      
+                                                   
+                                            
+                                                 
+
+                             
+             
+               
+                              
+               
+                                                   
+                              
+                             
+                  
+                                                   
+                                  
+                                  
+                                                  
+                            
+                                                                     
+                                    
+     
+                                                                                                   
+                                                                   
+     
+                                    
+                                                                                              
+                                                          
+                                                                                     
+                             
+                                                                        
+                                 
+                                                                                        
+                                    
+ 
+
+                                              
+             
+ 
+
+const MAX_INPUT = 4000;
+
+/** Inputs are stored as JSON; oversized ones become a valid `{ truncated, preview }` object. */
+export function auditInput(input         )                {
+  if (input === undefined) return null;
+  const json = JSON.stringify(input) ?? "null";
+  if (json.length <= MAX_INPUT) return json;
+  return JSON.stringify({
+    truncated: true,
+    bytes: json.length,
+    preview: json.slice(0, MAX_INPUT - 200),
+  });
+}
+
+function parseAuditInput(raw               )          {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // rows written before inputs were truncated safely
+    return { truncated: true, preview: raw };
+  }
+}
+
+function parseJson   (raw        )                {
+  try {
+    return JSON.parse(raw)     ;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Append-only record of every policy decision and tool call (table `audit`, migration 0003). */
+export class AuditLog {
+           #sql           ;
+  constructor(sql           ) {
+    this.#sql = sql;
+  }
+
+  /**
+   * The INSERT of one audit row as a statement, for writes that must put it in their own atomic
+   * `batch()`, last (RFC-0007 §4.4: a comment write and its audit row land together or not at all).
+   */
+  static statement(entry            )                                                      {
+    return {
+      sql: "INSERT INTO audit (at, actor_kind, actor_id, actor_name, site_id, tool, decision, reason, skill, input, outcome, snapshot_id, duration_ms, mode, cause, auto_check, elevation, run_id, release_id, automation_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      params: [
+        entry.at,
+        entry.actor.kind,
+        entry.actor.id,
+        entry.actor.name ?? null,
+        entry.siteId ?? null,
+        entry.tool,
+        entry.decision,
+        entry.reason ?? null,
+        entry.skill ?? null,
+        auditInput(entry.input),
+        entry.outcome ?? null,
+        entry.snapshotId ?? null,
+        entry.durationMs ?? null,
+        entry.mode ?? null,
+        entry.cause ?? null,
+        entry.autoCheck ? JSON.stringify(entry.autoCheck) : null,
+        entry.elevation ? JSON.stringify(entry.elevation) : null,
+        entry.runId ?? null,
+        entry.releaseId ?? null,
+        entry.automationId ?? null,
+      ],
+    };
+  }
+
+  async record(entry            )                  {
+    const { sql, params } = AuditLog.statement(entry);
+    const r = await this.#sql.run(sql, params);
+    return r.lastRowId ?? 0;
+  }
+
+  async list(
+    filter   
+                                  
+                                   
+                                                                                         
+                                               
+                                                                       
+                                       
+                                                                   
+                                
+                                                 
+                                 
+                                                                            
+                                  
+                                                                 
+                                 
+                                                       
+                                     
+                                 
+      = {},
+  )                      {
+    const where           = [];
+    const params                      = [];
+    if (filter.before !== undefined) {
+      where.push("id < ?");
+      params.push(filter.before);
+    }
+    if (filter.siteId) {
+      where.push("site_id = ?");
+      params.push(filter.siteId);
+    }
+    if (filter.actorId) {
+      where.push("actor_id = ?");
+      params.push(filter.actorId);
+    }
+    if (filter.actorIds) {
+      // An empty list matches nothing; the caller bounds the list (own keys), capped here at 80.
+      const ids = filter.actorIds.slice(0, 80);
+      where.push(ids.length ? `actor_id IN (${ids.map(() => "?").join(", ")})` : "0");
+      params.push(...ids);
+    }
+    if (filter.deployment) where.push("site_id IS NULL");
+    if (filter.tool) {
+      where.push("tool = ?");
+      params.push(filter.tool);
+    }
+    if (filter.since) {
+      where.push("at >= ?");
+      params.push(filter.since);
+    }
+    if (filter.runId) {
+      where.push("run_id = ?");
+      params.push(filter.runId);
+    }
+    if (filter.releaseId) {
+      where.push("release_id = ?");
+      params.push(filter.releaseId);
+    }
+    params.push(filter.limit ?? 100);
+    const rows = await this.#sql.all                         (
+      `SELECT * FROM audit ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY id DESC LIMIT ?`,
+      params,
+    );
+    return rows.map((r) => ({
+      id: r.id          ,
+      at: r.at          ,
+      actor: {
+        kind: r.actor_kind                 ,
+        id: r.actor_id          ,
+        ...(r.actor_name ? { name: r.actor_name           } : {}),
+      },
+      siteId: (r.site_id                 ) ?? undefined,
+      tool: r.tool          ,
+      decision: r.decision                          ,
+      reason: (r.reason                 ) ?? undefined,
+      skill: (r.skill                 ) ?? undefined,
+      input: parseAuditInput(r.input                 ),
+      outcome: (r.outcome                                ) ?? undefined,
+      snapshotId: (r.snapshot_id                 ) ?? undefined,
+      durationMs: (r.duration_ms                 ) ?? undefined,
+      mode: (r.mode                 ) ?? undefined,
+      ...(r.cause ? { cause: r.cause                  } : {}),
+      ...(r.auto_check ? { autoCheck: parseJson           (r.auto_check          ) } : {}),
+      ...(r.elevation
+        ? { elevation: parseJson                                 (r.elevation          ) }
+        : {}),
+      ...(r.run_id ? { runId: r.run_id           } : {}),
+      ...(r.release_id ? { releaseId: r.release_id           } : {}),
+      ...(r.automation_id ? { automationId: r.automation_id           } : {}),
+    }));
+  }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @cloudhal/agent-runtime — what governs agents: the policy engine (ADR-0004), the skill loader
+ * (ADR-0005) and the audit log. The MCP server and the API call into this package; it never calls them.
+ */
+export * from "./approvals.js";
+export * from "./audit.js";
+export * from "./modes.js";
+export * from "./ownership.js";
+export * from "./policy.js";
+export * from "./roles.js";
+export * from "./site-access.js";
+export * from "./skills.js";
+export * from "./taxonomy.js";

package/dist/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * @cloudhal/agent-runtime — what governs agents: the policy engine (ADR-0004), the skill loader
+ * (ADR-0005) and the audit log. The MCP server and the API call into this package; it never calls them.
+ */
+export * from "./approvals.js";
+export * from "./audit.js";
+export * from "./modes.js";
+export * from "./ownership.js";
+export * from "./policy.js";
+export * from "./roles.js";
+export * from "./site-access.js";
+export * from "./skills.js";
+export * from "./taxonomy.js";

package/dist/src/modes.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+import type { Scope } from "./policy.js";
+export type AgentMode = "plan" | "manual" | "edits" | "auto" | "bypass";
+/** In order of increasing autonomy. */
+export declare const AGENT_MODES: readonly AgentMode[];
+/** What existing keys and new keys without a choice get. */
+export declare const DEFAULT_AGENT_MODE: AgentMode;
+/** Modes a remote (HTTP, API key) agent may hold. `bypass` is for local stdio only. */
+export declare const REMOTE_AGENT_MODES: readonly AgentMode[];
+export declare function isAgentMode(value: unknown): value is AgentMode;
+/** The scopes a key needs to be useful in a mode (offered by default when creating one). */
+export declare function scopesForMode(mode: AgentMode): Scope[];
+/** Limits for an `auto`-mode publish that goes live without a person (see `isLowRiskPublish`). */
+export declare const AUTO_PUBLISH_LIMIT = 20;
+export interface PendingChange {
+    id: string;
+    kind: string;
+}
+/** Why `auto` mode did or did not let a publish through, as data (Studio words it itself). */
+export type AutoCheckCode = "low-risk" | "removes-content" | "nothing" | "structure" | "too-many"
+/** RFC-0004 §6.3: media that does not ride along with an article change. */
+ | "media"
+/** RFC-0008 §10.7 (D9): the release would run after the key's window (elevation end or 24 h). */
+ | "outside-window"
+/** RFC-0019 §2.4: an article gains a correction, an editorial statement a person signs off. */
+ | "correction";
+/** The `auto`-mode check behind a publish (stored on audit rows and approvals, ADR-0015). */
+export interface AutoCheck {
+    /** `low-risk-release`: the same check applied to a release's items (RFC-0008 §10.3). */
+    rule: "low-risk-publish" | "low-risk-release";
+    lowRisk: boolean;
+    code: AutoCheckCode;
+    /** Pending changes the publish would carry (added + edited + removed). */
+    changes: number;
+    /** `AUTO_PUBLISH_LIMIT` at the time of the check. */
+    limit: number;
+}
+/** English wording of a check, for agents and audit reasons. */
+export declare function describeAutoCheck(check: AutoCheck): string;
+/**
+ * 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 declare function checkAutoPublish(diff: {
+    added: PendingChange[];
+    changed: {
+        after: PendingChange;
+    }[];
+    removed: PendingChange[];
+}, options?: {
+    ridingAssets?: ReadonlySet<string>;
+    corrections?: ReadonlySet<string>;
+}): AutoCheck;
+/**
+ * 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).
+ */
+export interface ModeElevation {
+    mode: AgentMode;
+    /** ISO time the elevation ends. */
+    until: string;
+    /** Actor id of the person who granted it. */
+    grantedBy: string;
+    grantedAt: string;
+    /** Why, in the owner's words (shown in Studio and the audit). */
+    reason?: string | undefined;
+}
+/** Shortest and longest elevation an owner can grant. */
+export declare const ELEVATION_MIN_MINUTES = 5;
+export declare const ELEVATION_MAX_MINUTES: number;
+/** `a` lets the agent do more on its own than `b` (AGENT_MODES order). */
+export declare function isMoreAutonomous(a: AgentMode, b: AgentMode): boolean;
+/**
+ * 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 declare function elevationProblem(base: AgentMode, mode: AgentMode, minutes: number): string | undefined;
+/** The elevation that applies right now, if any (expired or no-longer-higher ones do not). */
+export declare function activeElevation(base: AgentMode, elevation: ModeElevation | undefined, now: Date): ModeElevation | undefined;
+/** How long before an elevation ends that owners and the agent are told (Studio notifications, `get_mode`). */
+export declare const ELEVATION_NOTICE_MINUTES = 10;
+/** Whole minutes left until `until` (rounded up; 0 once it has ended). */
+export declare function minutesLeft(until: string, now: Date): number;
+/** True during the last `ELEVATION_NOTICE_MINUTES` of an elevation. */
+export declare function endsSoon(until: string, now: Date): boolean;
+/** The longest an `auto`-mode release may wait without a person (RFC-0008 §10.7, D9). */
+export declare const AUTO_RELEASE_WINDOW_HOURS = 24;
+/** A release item as the low-risk check sees it (RFC-0008 §10.3). */
+export interface ReleaseItemRisk {
+    kind: "set" | "remove";
+    nodeId: string;
+    nodeKind: string;
+    /** The node is live today (the item has a base). */
+    live: boolean;
+    /** Ids the target references (assets that ride with an article). */
+    deps?: readonly string[];
+    /** RFC-0019 §2.4: the target adds a correction to the live version. */
+    corrects?: boolean;
+}
+/**
+ * `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 declare function checkAutoRelease(items: readonly ReleaseItemRisk[]): AutoCheck;
+/**
+ * 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 declare function autoReleaseWindowEnds(now: Date, elevationUntil?: string): string;