agentic-assistant 0.0.0-stage → 0.2.0

package/dist/worker.js

@@ -0,0 +1,276 @@
+import {
+  VERSION,
+  createPrincipal,
+  hasScope,
+  parseScope,
+  runAssistant
+} from "./chunk-T4ZMDOB4.js";
+
+// src/api.ts
+var MAX_BODY_BYTES = 65536;
+var MAX_MESSAGE_CHARS = 1e4;
+var MAX_REASON_CHARS = 500;
+var DEFAULT_MAX_CONCURRENT_RUNS = 4;
+var KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+var APPROVER_SCOPE = "assistant:admin";
+var json = (body, status = 200, headers = {}) => Response.json(body, { status, headers: { "cache-control": "no-store", ...headers } });
+var fail = (status, error, headers = {}) => json({ error }, status, headers);
+function toCaller(context) {
+  if (typeof context !== "object" || context === null) return void 0;
+  const { principalId, kind, chain, scopes } = context;
+  if (typeof principalId !== "string" || principalId === "" || !KINDS.includes(kind)) return void 0;
+  if (!Array.isArray(chain) || chain.length === 0 || chain[chain.length - 1]?.id !== principalId) return void 0;
+  if (chain[chain.length - 1]?.kind !== kind || kind === "human" && chain.length !== 1) return void 0;
+  const ids = chain.map((step) => step?.id);
+  if (ids.some((id) => typeof id !== "string" || id === "")) return void 0;
+  const rootId = ids[0];
+  if (!Array.isArray(scopes)) return void 0;
+  try {
+    for (const scope of scopes) parseScope(scope);
+  } catch {
+    return void 0;
+  }
+  return { id: principalId, kind, rootId, chain: ids, scopes: [...scopes] };
+}
+var assistantId = (caller) => `assistant:${caller.id}`;
+async function readJson(request) {
+  if (Number(request.headers.get("content-length") ?? 0) > MAX_BODY_BYTES) return void 0;
+  let text = "";
+  if (request.body !== null) {
+    const reader = request.body.getReader();
+    const decoder = new TextDecoder();
+    let bytes = 0;
+    for (; ; ) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > MAX_BODY_BYTES) {
+        await reader.cancel();
+        return void 0;
+      }
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    text += decoder.decode();
+  }
+  try {
+    const body = JSON.parse(text);
+    return typeof body === "object" && body !== null && !Array.isArray(body) ? body : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function sseChunk(event) {
+  return new TextEncoder().encode(`event: ${event.type}
+data: ${JSON.stringify(event)}
+
+`);
+}
+function createAssistantApi(options) {
+  const pending = /* @__PURE__ */ new Map();
+  const running = /* @__PURE__ */ new Map();
+  const maxRuns = options.maxConcurrentRuns ?? DEFAULT_MAX_CONCURRENT_RUNS;
+  function whyNotDecide(caller, entry) {
+    const { proposer } = entry;
+    if (caller.id === assistantId(proposer)) return "an agent cannot decide on its own action";
+    if (proposer.kind !== "human") {
+      if (caller.chain.includes(proposer.id) || caller.kind !== "human" && proposer.chain.includes(caller.id)) {
+        return "an agent cannot decide on its own action, or on one from an agent it made or that made it";
+      }
+    }
+    if (caller.kind !== "human" && !hasScope(caller.scopes, APPROVER_SCOPE)) {
+      return `an agent needs the ${APPROVER_SCOPE} scope to decide`;
+    }
+    const tool = options.registry.get(entry.request.tool);
+    if (tool === void 0 || !hasScope(caller.scopes, tool.scope)) return "the approver does not hold the scope of this tool";
+    return void 0;
+  }
+  const gateFor = (proposer) => ({
+    request(request, signal) {
+      return new Promise((resolve, reject) => {
+        if (signal.aborted) return reject(new Error("the request was cancelled"));
+        pending.set(request.id, { request, proposer, resolve });
+        signal.addEventListener(
+          "abort",
+          () => {
+            pending.delete(request.id);
+            reject(new Error("the request was cancelled"));
+          },
+          { once: true }
+        );
+      });
+    }
+  });
+  function chat(request, caller, message) {
+    const abort = new AbortController();
+    running.set(caller.id, (running.get(caller.id) ?? 0) + 1);
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      const left = (running.get(caller.id) ?? 1) - 1;
+      if (left <= 0) running.delete(caller.id);
+      else running.set(caller.id, left);
+    };
+    request.signal.addEventListener(
+      "abort",
+      () => {
+        abort.abort();
+        release();
+      },
+      { once: true }
+    );
+    let events;
+    try {
+      events = runAssistant({
+        provider: options.provider(),
+        registry: options.registry,
+        // The assistant holds the caller's scopes and no more.
+        principal: createPrincipal({
+          id: assistantId(caller),
+          kind: "agent_of_human",
+          parentId: caller.id,
+          scopes: caller.scopes,
+          // Each check asks the Auth again. A key revoked during a run, or one with other scopes, stops it.
+          isRevoked: async () => {
+            const now = toCaller(await options.auth.authenticate(request));
+            return now?.id !== caller.id || [...now.scopes].sort().join(" ") !== [...caller.scopes].sort().join(" ");
+          }
+        }),
+        approvals: gateFor(caller),
+        messages: [{ role: "user", content: [{ type: "text", text: message }] }],
+        system: options.system,
+        limits: options.limits,
+        signal: abort.signal
+      });
+    } catch {
+      release();
+      return fail(500, "the assistant could not start");
+    }
+    const body = new ReadableStream({
+      async pull(controller) {
+        try {
+          const next = await events.next();
+          if (next.done) {
+            release();
+            controller.close();
+          } else controller.enqueue(sseChunk(next.value));
+        } catch {
+          release();
+          controller.enqueue(sseChunk({ type: "error", error: "the run failed" }));
+          controller.close();
+        }
+      },
+      cancel() {
+        abort.abort();
+        release();
+        void events.return(void 0).catch(() => void 0);
+      }
+    });
+    return new Response(body, {
+      headers: { "content-type": "text/event-stream", "cache-control": "no-store", "x-accel-buffering": "no" }
+    });
+  }
+  async function decide(request, caller, id, approve) {
+    const body = await readJson(request);
+    if (body === void 0) return fail(400, "the body must be a JSON object");
+    const entry = pending.get(id);
+    if (entry === void 0 || entry.proposer.rootId !== caller.rootId) return fail(404, "no pending approval with this id");
+    const why = whyNotDecide(caller, entry);
+    if (why !== void 0) return fail(403, why);
+    let decision;
+    if (approve) {
+      if (body.digest !== entry.request.digest) return fail(409, "digest does not match the pending call");
+      decision = { requestId: id, approved: true, digest: entry.request.digest, decidedBy: caller.id, approverKind: caller.kind === "human" ? "human" : "agent" };
+    } else {
+      const reason = typeof body.reason === "string" ? body.reason.slice(0, MAX_REASON_CHARS) : void 0;
+      decision = { requestId: id, approved: false, decidedBy: caller.id, reason };
+    }
+    pending.delete(id);
+    entry.resolve(decision);
+    return json({ requestId: id, approved: approve, decidedBy: caller.id, machineMade: caller.kind !== "human" });
+  }
+  return {
+    async fetch(request) {
+      const url = new URL(request.url);
+      const match = /^\/api\/v1\/(tools|chat|approvals)(?:\/([^/]+)\/(approve|deny))?\/?$/.exec(url.pathname);
+      if (match === null) return fail(404, "not found");
+      const [, route, id, verb] = match;
+      const allowed = route === "chat" || verb !== void 0 ? "POST" : "GET";
+      if (request.method !== allowed) return fail(405, "method not allowed", { allow: allowed });
+      if (route !== "approvals" && id !== void 0) return fail(404, "not found");
+      let caller;
+      try {
+        caller = toCaller(await options.auth.authenticate(request));
+      } catch {
+        caller = void 0;
+      }
+      if (caller === void 0) return fail(401, "sign in with a valid key", { "www-authenticate": "Bearer" });
+      if (route === "tools") {
+        const tools = options.registry.list().filter((tool) => hasScope(caller.scopes, tool.scope)).map(({ name, description, scope, risk, inputSchema }) => ({ name, description, scope, risk, inputSchema }));
+        return json({ tools });
+      }
+      if (route === "approvals" && verb === void 0) {
+        const list = [...pending.values()].filter((entry) => entry.proposer.rootId === caller.rootId).filter((entry) => {
+          const tool = options.registry.get(entry.request.tool);
+          return tool !== void 0 && hasScope(caller.scopes, tool.scope);
+        }).map((entry) => ({
+          id: entry.request.id,
+          tool: entry.request.tool,
+          risk: entry.request.risk,
+          input: entry.request.input,
+          digest: entry.request.digest,
+          proposedBy: entry.request.actor,
+          requestedBy: entry.proposer.id,
+          canDecide: whyNotDecide(caller, entry) === void 0
+        }));
+        return json({ approvals: list });
+      }
+      if (route === "approvals" && id !== void 0) {
+        let requestId;
+        try {
+          requestId = decodeURIComponent(id);
+        } catch {
+          return fail(404, "no pending approval with this id");
+        }
+        return decide(request, caller, requestId, verb === "approve");
+      }
+      const body = await readJson(request);
+      const message = body?.message;
+      if (typeof message !== "string" || message.trim() === "" || message.length > MAX_MESSAGE_CHARS) {
+        return fail(400, `message must be a text of 1 to ${MAX_MESSAGE_CHARS} characters`);
+      }
+      if ((running.get(caller.id) ?? 0) >= maxRuns) return fail(429, "too many chat turns at once", { "retry-after": "5" });
+      return chat(request, caller, message);
+    }
+  };
+}
+
+// src/worker.ts
+var health = (env) => Response.json({ ok: true, pack: env.PACK_NAME ?? "agentic-assistant", version: VERSION });
+function createWorker(options) {
+  const api = createAssistantApi(options);
+  return {
+    async fetch(request, env = {}) {
+      const url = new URL(request.url);
+      if (request.method === "GET" && url.pathname === "/health") return health(env);
+      if (url.pathname.startsWith("/api/v1/")) return api.fetch(request);
+      return Response.json({ error: "not found" }, { status: 404 });
+    }
+  };
+}
+var worker_default = {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    if (request.method === "GET" && url.pathname === "/health") return health(env);
+    if (url.pathname.startsWith("/api/v1/")) {
+      return Response.json({ error: "the API is not set up: build the Worker with createWorker" }, { status: 503 });
+    }
+    return Response.json({ error: "not found" }, { status: 404 });
+  }
+};
+export {
+  APPROVER_SCOPE,
+  createAssistantApi,
+  createWorker,
+  worker_default as default
+};

package/llms.txt

@@ -0,0 +1,17 @@
+# agentic-assistant
+
+An AI assistant that acts inside your apps with the user's own permissions.
+
+Keywords: assistant,ai,agent,tools,mcp,sdk,side-panel,approvals,eu,model-port.
+
+- SDK: import { runAssistant, ToolRegistry, createPrincipal } from "agentic-assistant".
+- CLI: agentic-assistant chat --tools <mcp-url> --scope <s> --tool-scope <s> "message". MCP server: agentic-assistant mcp.
+- HTTP API: import { createWorker } from "agentic-assistant/worker". Routes under /api/v1: GET /tools, POST /chat (SSE), GET /approvals, POST /approvals/:id/approve|deny. Sign-in with agentic-identity principals.
+- AI marking: events carry `provenance`; use provenanceLabel and provenanceMarker (JSON-LD, IPTC trainedAlgorithmicMedia). Also in HTTP, CLI --json and MCP results.
+- Panel: import { AssistantPanel } from "agentic-assistant/react"; import "agentic-assistant/react.css".
+- Test provider: import { ScriptedProvider } from "agentic-assistant/testing".
+
+## Docs
+
+- README: https://github.com/pooriaarab/agentic-assistant
+- License: MIT

package/package.json

@@ -1,6 +1,97 @@
 {
   "name": "agentic-assistant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "An AI assistant that acts inside your apps with the user's own permissions.",
+  "keywords": [
+    "assistant",
+    "ai",
+    "agent",
+    "tools",
+    "mcp",
+    "sdk",
+    "side-panel",
+    "approvals",
+    "eu",
+    "model-port"
+  ],
+  "license": "MIT",
+  "author": "Pooria Arab",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pooriaarab/agentic-assistant.git"
+  },
+  "type": "module",
+  "private": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "SKILL.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./react.css": "./dist/react.css"
+  },
+  "bin": {
+    "agentic-assistant": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist",
+    "prepack": "npm run build",
+    "ci:local": "npm run build && npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^1.3.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "agentic-identity": "^0.3.0",
+    "ajv": "^8.20.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}