@absolutejs/agent-control 0.1.0 → 0.2.0

package/README.md

@@ -8,3 +8,27 @@ leased idempotency records so operator retries cannot change the requested input
 Scopes are `agents:read`, `agents:revoke`, and `agents:restore`. Mutations require
 an `operationId` and `reason`; PostgreSQL operations can be safely reclaimed
 after a crashed operator process's lease expires.
+
+`createAgentControlConsoleHandler()` adds a dependency-free authenticated
+operator console to the same package. Its snapshot shows agent status, pending
+approvals, durable runs and budgets, delegation scope and expiry, memory
+metadata, and scope-specific reputation without exposing memory contents or raw
+action inputs. Approval decisions require `agents:approve`, same-origin
+requests, an explicit mutation-intent header, a reason, and an idempotency key.
+
+```ts
+const console = createAgentControlConsoleHandler({
+  authorize: verifyOperator,
+  operations: createPostgresOperationStore({ client }),
+  data: {
+    snapshot: (operator) => loadSafeOperatorSnapshot(operator),
+    decideApproval: (decision) => applyAgencyDecision(decision),
+  },
+});
+```
+
+The HTML console uses a per-response Content Security Policy nonce, constructs
+all remote data with DOM `textContent`, cannot be framed, stores no cache, and
+has no third-party assets. The data adapter keeps it provider-neutral and lets
+applications compose `@absolutejs/agency`, `agent-runtime`, `agent-memory`, and
+`agent-reputation` without creating hard dependencies.

package/dist/console.d.ts

@@ -0,0 +1,63 @@
+import type { OperationStore, Operator } from "./index";
+export type AgentControlSnapshot = {
+    agents: Array<{
+        description?: string;
+        id: string;
+        status: string;
+    }>;
+    approvals: Array<{
+        action: string;
+        agentId: string;
+        id: string;
+        requestedAt: string;
+        risk?: string;
+        summary: string;
+    }>;
+    delegations: Array<{
+        expiresAt?: string;
+        from: string;
+        id: string;
+        scopes: string[];
+        to: string;
+    }>;
+    memories: Array<{
+        agentId: string;
+        id: string;
+        scope: string;
+        updatedAt: string;
+    }>;
+    reputations: Array<{
+        confidence: number;
+        scope: string;
+        score: number;
+        subject: string;
+    }>;
+    runs: Array<{
+        agentId: string;
+        budget?: {
+            limit: number;
+            spent: number;
+            unit: string;
+        };
+        id: string;
+        startedAt: string;
+        status: string;
+    }>;
+};
+export type AgentControlConsoleData = {
+    decideApproval: (input: {
+        approvalId: string;
+        decision: "approve" | "deny";
+        operatorId: string;
+        reason: string;
+    }) => Promise<unknown>;
+    snapshot: (operator: Operator) => Promise<AgentControlSnapshot>;
+};
+export declare const sanitizeAgentControlSnapshot: (source: AgentControlSnapshot) => AgentControlSnapshot;
+export declare const createAgentControlConsoleHandler: (options: {
+    authorize: (request: Request) => Promise<Operator | undefined> | Operator | undefined;
+    basePath?: string;
+    data: AgentControlConsoleData;
+    now?: () => number;
+    operations: OperationStore;
+}) => (request: Request) => Promise<Response | null>;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { AgentControlPlane } from "@absolutejs/agency";
+export * from "./console";
 export type Operator = {
     id: string;
     scopes: readonly string[];

package/dist/index.js

@@ -1,29 +1,166 @@
 // @bun
+// src/console.ts
+var hash = async (value) => [
+  ...new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(value))))
+].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+var bounded = (value, field) => {
+  if (typeof value !== "string" || value.length > 2000)
+    throw new Error(`Invalid agent control snapshot ${field}`);
+  return value;
+};
+var boundedNumber = (value, field) => {
+  if (typeof value !== "number" || !Number.isFinite(value))
+    throw new Error(`Invalid agent control snapshot ${field}`);
+  return value;
+};
+var rows = (value, map) => {
+  if (!Array.isArray(value) || value.length > 1000)
+    throw new Error("Agent control snapshot collection is too large");
+  return value.map(map);
+};
+var sanitizeAgentControlSnapshot = (source) => ({
+  agents: rows(source.agents, (item) => ({
+    ...item.description === undefined ? {} : { description: bounded(item.description, "agent.description") },
+    id: bounded(item.id, "agent.id"),
+    status: bounded(item.status, "agent.status")
+  })),
+  approvals: rows(source.approvals, (item) => ({
+    action: bounded(item.action, "approval.action"),
+    agentId: bounded(item.agentId, "approval.agentId"),
+    id: bounded(item.id, "approval.id"),
+    requestedAt: bounded(item.requestedAt, "approval.requestedAt"),
+    ...item.risk === undefined ? {} : { risk: bounded(item.risk, "approval.risk") },
+    summary: bounded(item.summary, "approval.summary")
+  })),
+  delegations: rows(source.delegations, (item) => ({
+    ...item.expiresAt === undefined ? {} : { expiresAt: bounded(item.expiresAt, "delegation.expiresAt") },
+    from: bounded(item.from, "delegation.from"),
+    id: bounded(item.id, "delegation.id"),
+    scopes: rows(item.scopes, (scope) => bounded(scope, "delegation.scope")),
+    to: bounded(item.to, "delegation.to")
+  })),
+  memories: rows(source.memories, (item) => ({
+    agentId: bounded(item.agentId, "memory.agentId"),
+    id: bounded(item.id, "memory.id"),
+    scope: bounded(item.scope, "memory.scope"),
+    updatedAt: bounded(item.updatedAt, "memory.updatedAt")
+  })),
+  reputations: rows(source.reputations, (item) => ({
+    confidence: boundedNumber(item.confidence, "reputation.confidence"),
+    scope: bounded(item.scope, "reputation.scope"),
+    score: boundedNumber(item.score, "reputation.score"),
+    subject: bounded(item.subject, "reputation.subject")
+  })),
+  runs: rows(source.runs, (item) => ({
+    agentId: bounded(item.agentId, "run.agentId"),
+    ...item.budget === undefined ? {} : {
+      budget: {
+        limit: boundedNumber(item.budget.limit, "run.budget.limit"),
+        spent: boundedNumber(item.budget.spent, "run.budget.spent"),
+        unit: bounded(item.budget.unit, "run.budget.unit")
+      }
+    },
+    id: bounded(item.id, "run.id"),
+    startedAt: bounded(item.startedAt, "run.startedAt"),
+    status: bounded(item.status, "run.status")
+  }))
+});
+var page = (nonce) => `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>AbsoluteJS Agent Control</title><style nonce="${nonce}">
+:root{color-scheme:dark;font:15px/1.45 system-ui,sans-serif;background:#09090b;color:#fafafa}body{margin:0}header{padding:1.2rem 1.5rem;border-bottom:1px solid #27272a;display:flex;align-items:center;justify-content:space-between}main{padding:1.5rem;display:grid;gap:1.25rem}.status{color:#a1a1aa}.error{color:#fca5a5}section{background:#18181b;border:1px solid #27272a;border-radius:.75rem;overflow:auto}h2{font-size:1rem;margin:0;padding:1rem}table{border-collapse:collapse;width:100%;min-width:42rem}th,td{text-align:left;padding:.7rem 1rem;border-top:1px solid #27272a;vertical-align:top}th{color:#a1a1aa;font-size:.8rem;text-transform:uppercase}button{background:#27272a;color:#fff;border:1px solid #3f3f46;border-radius:.4rem;padding:.4rem .65rem;margin:.15rem;cursor:pointer}button.approve{background:#14532d}button.deny{background:#7f1d1d}code{font-size:.8rem} @media(max-width:700px){main{padding:.75rem}header{padding:1rem}}
+</style></head><body><header><strong>AbsoluteJS Agent Control</strong><span id="status" class="status">Loading\u2026</span></header><main id="content"></main>
+<script nonce="${nonce}">(()=>{const base=location.pathname.replace(//$/,"");const root=document.querySelector("#content"),status=document.querySelector("#status");const columns={agents:["id","status","description"],approvals:["id","agentId","action","summary","risk","requestedAt"],runs:["id","agentId","status","startedAt","budget"],delegations:["id","from","to","scopes","expiresAt"],memories:["id","agentId","scope","updatedAt"],reputations:["subject","scope","score","confidence"]};const text=v=>v==null?"":typeof v==="object"?JSON.stringify(v):String(v);function render(data){root.replaceChildren();for(const [name,fields] of Object.entries(columns)){const section=document.createElement("section"),heading=document.createElement("h2"),table=document.createElement("table"),head=document.createElement("tr");heading.textContent=name[0].toUpperCase()+name.slice(1);for(const field of fields){const th=document.createElement("th");th.textContent=field;head.append(th)}if(name==="approvals"){const th=document.createElement("th");th.textContent="Decision";head.append(th)}table.append(head);for(const item of data[name]??[]){const row=document.createElement("tr");for(const field of fields){const td=document.createElement("td");td.textContent=text(item[field]);row.append(td)}if(name==="approvals"){const td=document.createElement("td");for(const decision of ["approve","deny"]){const button=document.createElement("button");button.className=decision;button.textContent=decision;button.addEventListener("click",()=>decide(item.id,decision));td.append(button)}row.append(td)}table.append(row)}section.append(heading,table);root.append(section)}}async function load(){try{const response=await fetch(base+"/api/snapshot",{headers:{accept:"application/json"}});if(!response.ok)throw new Error("Snapshot failed: "+response.status);render(await response.json());status.textContent="Live";status.className="status"}catch(error){status.textContent=error.message;status.className="error"}}async function decide(id,decision){const reason=prompt("Reason for "+decision+":");if(!reason)return;status.textContent="Applying\u2026";const response=await fetch(base+"/api/approvals/"+encodeURIComponent(id)+"/"+decision,{method:"POST",headers:{"content-type":"application/json","idempotency-key":crypto.randomUUID(),"x-agent-control-intent":"mutate"},body:JSON.stringify({reason})});if(!response.ok){status.textContent="Decision failed: "+response.status;status.className="error";return}await load()}load()})();</script></body></html>`;
+var createAgentControlConsoleHandler = (options) => {
+  const basePath = (options.basePath ?? "/agent-control").replace(/\/$/u, "");
+  const now = options.now ?? Date.now;
+  return async (request) => {
+    const url = new URL(request.url);
+    if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`))
+      return null;
+    const operator = await options.authorize(request);
+    if (!operator)
+      return new Response("Unauthorized", { status: 401 });
+    const required = request.method === "GET" ? "agents:read" : "agents:approve";
+    if (!operator.scopes.includes(required))
+      return new Response("Forbidden", { status: 403 });
+    if (request.method === "GET" && (url.pathname === basePath || url.pathname === `${basePath}/`)) {
+      const nonce = crypto.randomUUID().replaceAll("-", "");
+      return new Response(page(nonce), {
+        headers: {
+          "cache-control": "no-store",
+          "content-security-policy": `default-src 'none'; connect-src 'self'; img-src 'self'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'`,
+          "content-type": "text/html; charset=utf-8",
+          "referrer-policy": "no-referrer",
+          "x-content-type-options": "nosniff"
+        }
+      });
+    }
+    if (request.method === "GET" && url.pathname === `${basePath}/api/snapshot`) {
+      return Response.json(sanitizeAgentControlSnapshot(await options.data.snapshot(operator)), {
+        headers: { "cache-control": "no-store" }
+      });
+    }
+    const match = new RegExp(`^${basePath.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}/api/approvals/([^/]+)/(approve|deny)$`, "u").exec(url.pathname);
+    if (!match?.[1] || !match[2] || request.method !== "POST")
+      return new Response(null, { status: 405 });
+    if (request.headers.get("origin") !== url.origin || request.headers.get("x-agent-control-intent") !== "mutate")
+      return new Response("Cross-site mutation denied", { status: 403 });
+    const operationId = request.headers.get("idempotency-key");
+    const body = await request.json().catch(() => {
+      return;
+    });
+    if (!operationId || !body?.reason || body.reason.length > 1000)
+      return Response.json({ error: "Idempotency-Key and a bounded reason are required" }, { status: 400 });
+    const input = {
+      approvalId: decodeURIComponent(match[1]),
+      decision: match[2],
+      operatorId: operator.id,
+      reason: body.reason
+    };
+    const digest = await hash(input);
+    let claim;
+    try {
+      claim = await options.operations.claim(operationId, digest, now(), 30000);
+    } catch (error) {
+      return Response.json({ error: error instanceof Error ? error.message : "conflict" }, { status: 409 });
+    }
+    if (claim.response !== undefined)
+      return Response.json(claim.response);
+    if (!claim.acquired)
+      return Response.json({ error: "operation in progress" }, { status: 409, headers: { "retry-after": "5" } });
+    const response = await options.data.decideApproval(input);
+    if (!await options.operations.complete(operationId, digest, response))
+      throw new Error("Approval operation completion lost");
+    return Response.json(response);
+  };
+};
+
 // src/index.ts
 var createMemoryOperationStore = () => {
-  const rows = new Map;
+  const rows2 = new Map;
   return {
     claim: async (key, digest, now, leaseMs) => {
-      const row = rows.get(key);
+      const row = rows2.get(key);
       if (row?.digest !== undefined && row.digest !== digest)
         throw new Error("Idempotency key reused with different input");
       if (row?.response !== undefined)
         return { acquired: false, response: structuredClone(row.response) };
       if (row && row.leaseUntil > now)
         return { acquired: false };
-      rows.set(key, { digest, key, leaseUntil: now + leaseMs });
+      rows2.set(key, { digest, key, leaseUntil: now + leaseMs });
       return { acquired: true };
     },
     complete: async (key, digest, response) => {
-      const row = rows.get(key);
+      const row = rows2.get(key);
       if (!row || row.digest !== digest)
         return false;
-      rows.set(key, { ...row, response: structuredClone(response) });
+      rows2.set(key, { ...row, response: structuredClone(response) });
       return true;
     }
   };
 };
-var hash = async (value) => [
+var hash2 = async (value) => [
   ...new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(value))))
 ].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 var createAgentControlHandler = ({
@@ -54,7 +191,7 @@ var createAgentControlHandler = ({
   });
   if (!body?.operationId || !body.reason)
     return Response.json({ error: "operationId and reason are required" }, { status: 400 });
-  const digest = await hash({ action, agentId, reason: body.reason });
+  const digest = await hash2({ action, agentId, reason: body.reason });
   let claim;
   try {
     claim = await operations.claim(body.operationId, digest, now(), 30000);
@@ -107,8 +244,10 @@ var createPostgresOperationStore = ({
   };
 };
 export {
+  sanitizeAgentControlSnapshot,
   createPostgresOperationStore,
   createMemoryOperationStore,
   createAgentControlHandler,
+  createAgentControlConsoleHandler,
   agentControlPostgresSchemaSql
 };

package/dist/manifest.js

@@ -5901,6 +5901,14 @@ var serializedTool = Type.Object({
 });
 var manifestSchema = Type.Object({
   contract: Type.Union([Type.Literal(1), Type.Literal(2)]),
+  discovery: Type.Optional(Type.Object({
+    audiences: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    certificationUrl: Type.Optional(Type.String()),
+    intents: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    keywords: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    protocols: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    url: Type.Optional(Type.String())
+  })),
   identity: Type.Object({
     accent: Type.Optional(Type.String({ pattern: "^#[0-9a-fA-F]{3,8}$" })),
     category: Type.String({ minLength: 1 }),
@@ -5935,7 +5943,7 @@ var manifest = defineManifest()({
   identity: {
     accent: "#dc2626",
     category: "security",
-    description: "Authenticated operator API for agent inventory, durable kill switches, source revocation, restoration, and leased idempotent operations.",
+    description: "Authenticated operator API and CSP-hardened console for agent inventory, approvals, runs, budgets, delegations, memory metadata, reputation, durable kill switches, and leased idempotent operations.",
     docsUrl: "https://github.com/absolutejs/agent-control",
     name: "@absolutejs/agent-control",
     tagline: "See and stop every capability an agent holds."

package/dist/manifest.json

@@ -3,7 +3,7 @@
 	"identity": {
 		"accent": "#dc2626",
 		"category": "security",
-		"description": "Authenticated operator API for agent inventory, durable kill switches, source revocation, restoration, and leased idempotent operations.",
+		"description": "Authenticated operator API and CSP-hardened console for agent inventory, approvals, runs, budgets, delegations, memory metadata, reputation, durable kill switches, and leased idempotent operations.",
 		"docsUrl": "https://github.com/absolutejs/agent-control",
 		"name": "@absolutejs/agent-control",
 		"tagline": "See and stop every capability an agent holds."

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@absolutejs/agent-control",
-  "version": "0.1.0",
-  "description": "Authenticated operator API for AI agent inventory, kill switches, revocation, and restoration.",
+  "version": "0.2.0",
+  "description": "Authenticated AI agent operator API and console for approvals, runs, delegations, memory, reputation, and kill switches.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/absolutejs/agent-control.git"
+    "url": "git+https://github.com/absolutejs/agent-control.git"
   },
   "publishConfig": {
     "access": "public"
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@absolutejs/agency": "^0.4.0",
-    "@absolutejs/manifest": "^0.2.0",
+    "@absolutejs/manifest": "^0.3.0",
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {