npm - @absolutejs/agent-control - Versions diffs - 0.2.0 → 0.4.0 - Mend

@absolutejs/agent-control 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -6,7 +6,8 @@ before cleanup, reports partial source failures, restores deliberately, and uses
 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
+an `operationId`, bounded `reason`, same-origin `Origin` header, and
+`X-Agent-Control-Intent: mutate`; PostgreSQL operations can be safely reclaimed
 after a crashed operator process's lease expires.
 `createAgentControlConsoleHandler()` adds a dependency-free authenticated
@@ -32,3 +33,10 @@ 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.
+`createAgentPlaygroundHandler()` adds a provider-neutral plan-then-execute UI
+and API. Planning is a separate, explicitly effect-free adapter operation. The
+server stores the full input and only returns its digest, expires plans quickly,
+binds them to the operator, refuses denied or approval-pending plans, and uses
+the same leased idempotency store for execution. The browser cannot mutate a
+plan between review and execution.

package/dist/index.d.ts CHANGED Viewed

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

package/dist/index.js CHANGED Viewed

@@ -135,25 +135,178 @@ var createAgentControlConsoleHandler = (options) => {
     return Response.json(response);
   };
 };
+// src/playground.ts
+var createMemoryAgentPlaygroundPlanStore = (now = Date.now) => {
+  const plans = new Map;
+  return {
+    get: async (id, operatorId) => {
+      const plan = plans.get(id);
+      if (!plan || plan.operatorId !== operatorId || plan.expiresAt <= now())
+        return;
+      return structuredClone(plan);
+    },
+    save: async (plan) => {
+      for (const [id, existing] of plans)
+        if (existing.expiresAt <= now())
+          plans.delete(id);
+      if (plans.has(plan.planId))
+        throw new Error("Playground plan already exists");
+      plans.set(plan.planId, structuredClone(plan));
+    }
+  };
+};
+var digest = 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 text = (value, field, maximum = 2000) => {
+  if (typeof value !== "string" || value === "" || value.length > maximum)
+    throw new Error(`Invalid playground ${field}`);
+  return value;
+};
+var list = (values, map) => {
+  if (!Array.isArray(values) || values.length > 1000)
+    throw new Error("Playground collection is too large");
+  return values.map(map);
+};
+var safeCatalog = (items) => list(items, (item) => ({
+  ...item.description === undefined ? {} : { description: text(item.description, "description") },
+  id: text(item.id, "agent id", 256),
+  name: text(item.name, "agent name", 256),
+  operations: list(item.operations, (value) => text(value, "operation", 256)),
+  protocols: list(item.protocols, (value) => text(value, "protocol", 128))
+}));
+var page2 = (nonce) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>AbsoluteJS Agent Playground</title><style nonce="${nonce}">:root{color-scheme:dark;font:15px/1.5 system-ui;background:#09090b;color:#fafafa}body{max-width:70rem;margin:auto;padding:2rem}label{display:block;margin:1rem 0}.grid{display:grid;grid-template-columns:1fr 1fr;gap:1rem}select,textarea,button{font:inherit;background:#18181b;color:#fff;border:1px solid #3f3f46;border-radius:.5rem;padding:.7rem;width:100%;box-sizing:border-box}textarea{min-height:14rem;font-family:ui-monospace,monospace}button{cursor:pointer;margin:.4rem 0}.execute{background:#14532d}pre{white-space:pre-wrap;background:#18181b;padding:1rem;border-radius:.5rem}.error{color:#fca5a5}@media(max-width:700px){.grid{grid-template-columns:1fr}}</style></head><body><h1>Agent Playground</h1><p>Plan first. Review exact effects. Execute only a bound server-side plan.</p><div class="grid"><div><label>Agent<select id="agent"></select></label><label>Operation<select id="operation"></select></label><label>JSON input<textarea id="input">{}</textarea></label><button id="plan">Create effect-free plan</button><button id="execute" class="execute" disabled>Execute reviewed plan</button></div><div><h2>Bound plan</h2><pre id="output">No plan yet.</pre></div></div><script nonce="${nonce}">(()=>{const base=location.pathname.replace(//$/,""),agent=document.querySelector("#agent"),operation=document.querySelector("#operation"),input=document.querySelector("#input"),output=document.querySelector("#output"),execute=document.querySelector("#execute");let plan;const headers={"content-type":"application/json","x-agent-control-intent":"mutate"};async function catalog(){const data=await fetch(base+"/api/catalog").then(r=>r.json());for(const item of data){const option=document.createElement("option");option.value=item.id;option.textContent=item.name;option.dataset.operations=JSON.stringify(item.operations);agent.append(option)}changed()}function changed(){operation.replaceChildren();for(const value of JSON.parse(agent.selectedOptions[0]?.dataset.operations??"[]")){const option=document.createElement("option");option.value=value;option.textContent=value;operation.append(option)}}agent.addEventListener("change",changed);document.querySelector("#plan").addEventListener("click",async()=>{try{const response=await fetch(base+"/api/plans",{method:"POST",headers,body:JSON.stringify({agentId:agent.value,operation:operation.value,input:JSON.parse(input.value)})});const data=await response.json();if(!response.ok)throw new Error(data.error??("HTTP "+response.status));plan=data;output.textContent=JSON.stringify(data,null,2);execute.disabled=data.status!=="ready"}catch(error){output.textContent=error.message;output.className="error"}});execute.addEventListener("click",async()=>{if(!plan)return;execute.disabled=true;const response=await fetch(base+"/api/plans/"+encodeURIComponent(plan.planId)+"/execute",{method:"POST",headers:{...headers,"idempotency-key":crypto.randomUUID()},body:"{}"});output.textContent=JSON.stringify(await response.json(),null,2)});catalog()})();</script></body></html>`;
+var createAgentPlaygroundHandler = (options) => {
+  const base = (options.basePath ?? "/agent-playground").replace(/\/$/u, "");
+  const now = options.now ?? Date.now;
+  const mutationAllowed = (request, url) => request.headers.get("origin") === url.origin && request.headers.get("x-agent-control-intent") === "mutate";
+  return async (request) => {
+    const url = new URL(request.url);
+    if (url.pathname !== base && !url.pathname.startsWith(`${base}/`))
+      return null;
+    const operator = await options.authorize(request);
+    if (!operator)
+      return new Response("Unauthorized", { status: 401 });
+    const scope = request.method === "GET" ? "agents:read" : url.pathname.endsWith("/execute") ? "agents:execute" : "agents:simulate";
+    if (!operator.scopes.includes(scope))
+      return new Response("Forbidden", { status: 403 });
+    if (request.method === "GET" && (url.pathname === base || url.pathname === `${base}/`)) {
+      const nonce = crypto.randomUUID().replaceAll("-", "");
+      return new Response(page2(nonce), {
+        headers: {
+          "cache-control": "no-store",
+          "content-security-policy": `default-src 'none'; connect-src 'self'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'; base-uri 'none'; frame-ancestors 'none'`,
+          "content-type": "text/html; charset=utf-8",
+          "x-content-type-options": "nosniff"
+        }
+      });
+    }
+    if (request.method === "GET" && url.pathname === `${base}/api/catalog`)
+      return Response.json(safeCatalog(await options.adapter.catalog(operator)), {
+        headers: { "cache-control": "no-store" }
+      });
+    if (request.method === "POST" && url.pathname === `${base}/api/plans`) {
+      if (!mutationAllowed(request, url))
+        return new Response("Cross-site mutation denied", { status: 403 });
+      const raw = await request.text();
+      if (new TextEncoder().encode(raw).byteLength > 256000)
+        return Response.json({ error: "Input is too large" }, { status: 413 });
+      let body;
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        return Response.json({ error: "Input must be valid JSON" }, { status: 400 });
+      }
+      const agentId = text(body.agentId, "agent id", 256);
+      const operation = text(body.operation, "operation", 256);
+      const inputDigest = await digest(body.input ?? null);
+      const proposed = await options.adapter.plan({ agentId, input: structuredClone(body.input ?? null), operation }, operator);
+      if (proposed.status !== "ready" && proposed.status !== "approval-required" && proposed.status !== "denied")
+        throw new Error("Invalid playground plan status");
+      if (proposed.spend && (!Number.isSafeInteger(proposed.spend.amountMinor) || proposed.spend.amountMinor < 0 || !/^[A-Z]{3}$/u.test(proposed.spend.currency)))
+        throw new Error("Invalid playground plan spend");
+      const plan2 = {
+        agentId,
+        effects: list(proposed.effects, (value) => text(value, "effect", 128)),
+        expiresAt: now() + (options.planTtlMs ?? 10 * 60000),
+        input: structuredClone(body.input ?? null),
+        inputDigest,
+        operation,
+        operatorId: operator.id,
+        planId: `plan_${crypto.randomUUID()}`,
+        ...proposed.spend ? {
+          spend: {
+            amountMinor: proposed.spend.amountMinor,
+            currency: text(proposed.spend.currency, "currency", 3)
+          }
+        } : {},
+        status: proposed.status,
+        steps: list(proposed.steps, (step) => ({
+          description: text(step.description, "step description"),
+          ...step.protocol ? { protocol: text(step.protocol, "protocol", 128) } : {},
+          ...step.target ? { target: text(step.target, "target") } : {}
+        })),
+        summary: text(proposed.summary, "summary")
+      };
+      await options.plans.save(plan2);
+      const { input: _input, ...visible } = plan2;
+      return Response.json(visible, {
+        status: 201,
+        headers: { "cache-control": "no-store" }
+      });
+    }
+    const execute = new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}/api/plans/([^/]+)/execute$`, "u").exec(url.pathname);
+    if (request.method !== "POST" || !execute?.[1])
+      return new Response(null, { status: 405 });
+    if (!mutationAllowed(request, url))
+      return new Response("Cross-site mutation denied", { status: 403 });
+    const operationId = request.headers.get("idempotency-key");
+    if (!operationId)
+      return Response.json({ error: "Idempotency-Key is required" }, { status: 400 });
+    const plan = await options.plans.get(decodeURIComponent(execute[1]), operator.id);
+    if (!plan)
+      return Response.json({ error: "Plan not found or expired" }, { status: 404 });
+    if (plan.status !== "ready")
+      return Response.json({ error: `Plan is ${plan.status}` }, { status: 409 });
+    const binding = await digest({
+      inputDigest: plan.inputDigest,
+      planId: plan.planId
+    });
+    let claim;
+    try {
+      claim = await options.operations.claim(`playground:${plan.planId}`, binding, 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 result = await options.adapter.execute(structuredClone(plan), operator);
+    if (!await options.operations.complete(`playground:${plan.planId}`, binding, result))
+      throw new Error("Playground execution completion lost");
+    return Response.json(result);
+  };
+};
 // src/index.ts
 var createMemoryOperationStore = () => {
   const rows2 = new Map;
   return {
-    claim: async (key, digest, now, leaseMs) => {
+    claim: async (key, digest2, now, leaseMs) => {
       const row = rows2.get(key);
-      if (row?.digest !== undefined && row.digest !== digest)
+      if (row?.digest !== undefined && row.digest !== digest2)
         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 };
-      rows2.set(key, { digest, key, leaseUntil: now + leaseMs });
+      rows2.set(key, { digest: digest2, key, leaseUntil: now + leaseMs });
       return { acquired: true };
     },
-    complete: async (key, digest, response) => {
+    complete: async (key, digest2, response) => {
       const row = rows2.get(key);
-      if (!row || row.digest !== digest)
+      if (!row || row.digest !== digest2)
         return false;
       rows2.set(key, { ...row, response: structuredClone(response) });
       return true;
@@ -186,15 +339,24 @@ var createAgentControlHandler = ({
     return Response.json(await control.inventory(agentId));
   if (request.method !== "POST" || action !== "revoke" && action !== "restore")
     return new Response(null, { status: 405 });
-  const body = await request.json().catch(() => {
-    return;
-  });
-  if (!body?.operationId || !body.reason)
-    return Response.json({ error: "operationId and reason are required" }, { status: 400 });
-  const digest = await hash2({ action, agentId, reason: body.reason });
+  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 raw = await request.text();
+  if (new TextEncoder().encode(raw).byteLength > 4096)
+    return Response.json({ error: "Request body is too large" }, { status: 413 });
+  const body = (() => {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return;
+    }
+  })();
+  if (!body?.operationId || body.operationId.length > 200 || !body.reason || body.reason.length > 1000)
+    return Response.json({ error: "A bounded operationId and reason are required" }, { status: 400 });
+  const digest2 = await hash2({ action, agentId, reason: body.reason });
   let claim;
   try {
-    claim = await operations.claim(body.operationId, digest, now(), 30000);
+    claim = await operations.claim(body.operationId, digest2, now(), 30000);
   } catch (error) {
     return Response.json({ error: error instanceof Error ? error.message : "conflict" }, { status: 409 });
   }
@@ -207,7 +369,7 @@ var createAgentControlHandler = ({
     agentId,
     reason: body.reason
   }) : (await control.restore(agentId), { agentId, restored: true, restoredBy: operator.id });
-  if (!await operations.complete(body.operationId, digest, response))
+  if (!await operations.complete(body.operationId, digest2, response))
     throw new Error("Control operation completion lost");
   return Response.json(response);
 };
@@ -226,12 +388,12 @@ var createPostgresOperationStore = ({
 }) => {
   const ns = nsOf(namespace);
   return {
-    claim: async (key, digest, now, leaseMs) => {
-      const result = await client.query(`INSERT INTO ${ns}.operations (operation_key,digest,lease_until) VALUES ($1,$2,$3) ON CONFLICT (operation_key) DO UPDATE SET lease_until=$3 WHERE ${ns}.operations.digest=$2 AND ${ns}.operations.response IS NULL AND ${ns}.operations.lease_until <= $4 RETURNING digest,response`, [key, digest, now + leaseMs, now]);
+    claim: async (key, digest2, now, leaseMs) => {
+      const result = await client.query(`INSERT INTO ${ns}.operations (operation_key,digest,lease_until) VALUES ($1,$2,$3) ON CONFLICT (operation_key) DO UPDATE SET lease_until=$3 WHERE ${ns}.operations.digest=$2 AND ${ns}.operations.response IS NULL AND ${ns}.operations.lease_until <= $4 RETURNING digest,response`, [key, digest2, now + leaseMs, now]);
       const row = result.rows[0];
       if (!row) {
         const existing = (await client.query(`SELECT digest,response FROM ${ns}.operations WHERE operation_key=$1`, [key])).rows[0];
-        if (existing?.digest !== undefined && existing.digest !== digest)
+        if (existing?.digest !== undefined && existing.digest !== digest2)
           throw new Error("Idempotency key reused with different input");
         return {
           acquired: false,
@@ -240,13 +402,15 @@ var createPostgresOperationStore = ({
       }
       return { acquired: row.response === null || row.response === undefined };
     },
-    complete: async (key, digest, response) => (await client.query(`UPDATE ${ns}.operations SET response=$3::jsonb WHERE operation_key=$1 AND digest=$2 AND response IS NULL RETURNING operation_key`, [key, digest, JSON.stringify(response)])).rows.length === 1
+    complete: async (key, digest2, response) => (await client.query(`UPDATE ${ns}.operations SET response=$3::jsonb WHERE operation_key=$1 AND digest=$2 AND response IS NULL RETURNING operation_key`, [key, digest2, JSON.stringify(response)])).rows.length === 1
   };
 };
 export {
   sanitizeAgentControlSnapshot,
   createPostgresOperationStore,
   createMemoryOperationStore,
+  createMemoryAgentPlaygroundPlanStore,
+  createAgentPlaygroundHandler,
   createAgentControlHandler,
   createAgentControlConsoleHandler,
   agentControlPostgresSchemaSql

package/dist/manifest.js CHANGED Viewed

@@ -5943,7 +5943,7 @@ var manifest = defineManifest()({
   identity: {
     accent: "#dc2626",
     category: "security",
-    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.",
+    description: "Authenticated operator API, CSP-hardened console, and bound plan-then-execute playground for 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 CHANGED Viewed

@@ -3,7 +3,7 @@
 	"identity": {
 		"accent": "#dc2626",
 		"category": "security",
-		"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.",
+		"description": "Authenticated operator API, CSP-hardened console, and bound plan-then-execute playground for 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/playground.d.ts ADDED Viewed

@@ -0,0 +1,53 @@
+import type { OperationStore, Operator } from "./index";
+export type AgentPlaygroundCatalogItem = {
+    description?: string;
+    id: string;
+    name: string;
+    operations: string[];
+    protocols: string[];
+};
+export type AgentPlaygroundPlan = {
+    agentId: string;
+    effects: string[];
+    expiresAt: number;
+    input: unknown;
+    inputDigest: string;
+    operation: string;
+    operatorId: string;
+    planId: string;
+    spend?: {
+        amountMinor: number;
+        currency: string;
+    };
+    status: "ready" | "approval-required" | "denied";
+    steps: Array<{
+        description: string;
+        protocol?: string;
+        target?: string;
+    }>;
+    summary: string;
+};
+export type AgentPlaygroundPlanStore = {
+    get: (planId: string, operatorId: string) => Promise<AgentPlaygroundPlan | undefined>;
+    save: (plan: AgentPlaygroundPlan) => Promise<void>;
+};
+export type AgentPlaygroundAdapter = {
+    catalog: (operator: Operator) => Promise<AgentPlaygroundCatalogItem[]> | AgentPlaygroundCatalogItem[];
+    /** Must not produce external effects. Return only a proposed plan. */
+    plan: (request: {
+        agentId: string;
+        input: unknown;
+        operation: string;
+    }, operator: Operator) => Promise<Omit<AgentPlaygroundPlan, "agentId" | "expiresAt" | "input" | "inputDigest" | "operation" | "operatorId" | "planId">> | Omit<AgentPlaygroundPlan, "agentId" | "expiresAt" | "input" | "inputDigest" | "operation" | "operatorId" | "planId">;
+    execute: (plan: AgentPlaygroundPlan, operator: Operator) => Promise<unknown>;
+};
+export declare const createMemoryAgentPlaygroundPlanStore: (now?: () => number) => AgentPlaygroundPlanStore;
+export declare const createAgentPlaygroundHandler: (options: {
+    adapter: AgentPlaygroundAdapter;
+    authorize: (request: Request) => Promise<Operator | undefined> | Operator | undefined;
+    basePath?: string;
+    now?: () => number;
+    operations: OperationStore;
+    plans: AgentPlaygroundPlanStore;
+    planTtlMs?: number;
+}) => (request: Request) => Promise<Response | null>;

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@absolutejs/agent-control",
-  "version": "0.2.0",
-  "description": "Authenticated AI agent operator API and console for approvals, runs, delegations, memory, reputation, and kill switches.",
+  "version": "0.4.0",
+  "description": "Authenticated AI agent operator API, console, and bound plan-then-execute playground.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     "check:package": "bun run format && bun run typecheck && bun run test && bun run build"
   },
   "dependencies": {
-    "@absolutejs/agency": "^0.4.0",
+    "@absolutejs/agency": "^0.5.0",
     "@absolutejs/manifest": "^0.3.0",
     "@sinclair/typebox": "^0.34.0"
   },