@absolutejs/agent-control 0.1.0

package/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 AbsoluteJS

package/README.md

@@ -0,0 +1,10 @@
+# @absolutejs/agent-control
+
+Authenticated web-standard operator API over `@absolutejs/agency`'s control
+plane. It inventories every registered source, activates the durable kill switch
+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
+after a crashed operator process's lease expires.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import type { AgentControlPlane } from "@absolutejs/agency";
+export type Operator = {
+    id: string;
+    scopes: readonly string[];
+};
+export type OperationRecord = {
+    digest: string;
+    key: string;
+    leaseUntil: number;
+    response?: unknown;
+};
+export type OperationStore = {
+    claim: (key: string, digest: string, now: number, leaseMs: number) => Promise<{
+        acquired: boolean;
+        response?: unknown;
+    }>;
+    complete: (key: string, digest: string, response: unknown) => Promise<boolean>;
+};
+export declare const createMemoryOperationStore: () => OperationStore;
+export declare const createAgentControlHandler: ({ authorize, basePath, control, operations, now, }: {
+    authorize: (request: Request) => Promise<Operator | undefined> | Operator | undefined;
+    basePath?: string;
+    control: AgentControlPlane;
+    operations: OperationStore;
+    now?: () => number;
+}) => (request: Request) => Promise<Response | null>;
+export type ControlSqlResult<Row> = {
+    rows: Row[];
+};
+export type ControlSqlClient = {
+    query: <Row = Record<string, unknown>>(text: string, values?: readonly unknown[]) => Promise<ControlSqlResult<Row>>;
+};
+export declare const agentControlPostgresSchemaSql: (namespace?: string) => string;
+export declare const createPostgresOperationStore: ({ client, namespace, }: {
+    client: ControlSqlClient;
+    namespace?: string;
+}) => OperationStore;

package/dist/index.js

@@ -0,0 +1,114 @@
+// @bun
+// src/index.ts
+var createMemoryOperationStore = () => {
+  const rows = new Map;
+  return {
+    claim: async (key, digest, now, leaseMs) => {
+      const row = rows.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 });
+      return { acquired: true };
+    },
+    complete: async (key, digest, response) => {
+      const row = rows.get(key);
+      if (!row || row.digest !== digest)
+        return false;
+      rows.set(key, { ...row, response: structuredClone(response) });
+      return true;
+    }
+  };
+};
+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 createAgentControlHandler = ({
+  authorize,
+  basePath = "/agent-control",
+  control,
+  operations,
+  now = Date.now
+}) => async (request) => {
+  const url = new URL(request.url);
+  if (!url.pathname.startsWith(`${basePath}/agents/`))
+    return null;
+  const operator = await authorize(request);
+  if (!operator)
+    return new Response("Unauthorized", { status: 401 });
+  const rest = url.pathname.slice(`${basePath}/agents/`.length).split("/");
+  const agentId = decodeURIComponent(rest[0] ?? "");
+  const action = rest[1];
+  const required = request.method === "GET" ? "agents:read" : action === "restore" ? "agents:restore" : "agents:revoke";
+  if (!operator.scopes.includes(required))
+    return new Response("Forbidden", { status: 403 });
+  if (request.method === "GET" && !action)
+    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 hash({ action, agentId, reason: body.reason });
+  let claim;
+  try {
+    claim = await operations.claim(body.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 = action === "revoke" ? await control.revoke({
+    activatedBy: operator.id,
+    agentId,
+    reason: body.reason
+  }) : (await control.restore(agentId), { agentId, restored: true, restoredBy: operator.id });
+  if (!await operations.complete(body.operationId, digest, response))
+    throw new Error("Control operation completion lost");
+  return Response.json(response);
+};
+var nsOf = (value) => {
+  if (!/^[a-z_][a-z0-9_]*$/.test(value))
+    throw new Error("Control namespace must be a simple identifier");
+  return value;
+};
+var agentControlPostgresSchemaSql = (namespace = "agent_control") => {
+  const ns = nsOf(namespace);
+  return `CREATE SCHEMA IF NOT EXISTS ${ns}; CREATE TABLE IF NOT EXISTS ${ns}.operations (operation_key text PRIMARY KEY, digest text NOT NULL, lease_until bigint NOT NULL, response jsonb);`;
+};
+var createPostgresOperationStore = ({
+  client,
+  namespace = "agent_control"
+}) => {
+  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]);
+      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)
+          throw new Error("Idempotency key reused with different input");
+        return {
+          acquired: false,
+          ...existing?.response === null || existing?.response === undefined ? {} : { response: existing.response }
+        };
+      }
+      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
+  };
+};
+export {
+  createPostgresOperationStore,
+  createMemoryOperationStore,
+  createAgentControlHandler,
+  agentControlPostgresSchemaSql
+};

package/dist/manifest.d.ts

@@ -0,0 +1 @@
+export declare const manifest: import("@absolutejs/manifest").PackageManifest<Record<string, never>, never>;