agentic-assistant 0.1.0 → 0.3.0

package/dist/{loop-CDbbDwSs.d.ts → loop-D4qWbRu6.d.ts}

@@ -1,4 +1,4 @@
-import { J as JsonSchema, U as Usage, c as Message, M as ModelProvider } from './types-C47SyHH5.js';
+import { J as JsonSchema, U as Usage, A as AnsweredBy, c as Message, M as ModelProvider } from './types-DGH8FS56.js';
 
 declare const ACTIONS: readonly ["read", "comment", "write", "admin"];
 type Action = (typeof ACTIONS)[number];
@@ -65,11 +65,14 @@ interface ApprovalRequest {
     digest: string;
     actor: Actor;
 }
+/** Who gave an approval. The gate says it. `human` means a signed-in person, `host` means a rule the host set up, `agent` means another agent. */
+type ApproverKind = "human" | "agent" | "host";
 type ApprovalDecision = {
     requestId: string;
     approved: true;
     digest: string;
-    decidedBy: string;
+    decidedBy: string; /** Leave it out when you do not know. The record then says "unknown". */
+    approverKind?: ApproverKind;
 } | {
     requestId: string;
     approved: false;
@@ -100,11 +103,57 @@ declare class QueueApprovalGate implements ApprovalGate {
     private readonly waiting;
     pending(): ApprovalRequest[];
     request(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision>;
-    approve(id: string, decidedBy: string): void;
+    approve(id: string, decidedBy: string, approverKind?: ApproverKind): void;
     reject(id: string, decidedBy?: string, reason?: string): void;
     private take;
 }
 
+/** Says that a machine made an output, and which one. Attach it to every result and every edit. */
+interface Provenance {
+    generator: "ai";
+    /** The model that answered. After a fallback, this is the fallback model. */
+    model: string;
+    provider: string;
+    /** ISO 8601 time, in UTC. */
+    createdAt: string;
+    /** The id of the assistant principal that acted. */
+    actor: string;
+    /** The person the assistant acts for. */
+    onBehalfOf: string;
+    /** The tool that ran. Set on a tool result. */
+    tool?: string;
+    /** The risk of that tool. A host may mark only `risky` and `irreversible` results as edits. */
+    risk?: "safe" | "risky" | "irreversible";
+    /** Who approved the action, and what kind of approver it was. Check `kind` before you say a person approved. */
+    approvedBy?: Approver[];
+}
+interface Approver {
+    id: string;
+    /** `unknown` when the approval gate did not say. */
+    kind: ApproverKind | "unknown";
+}
+interface ProvenanceInput {
+    model: string;
+    provider: string;
+    /** Epoch milliseconds. */
+    createdAt: number;
+    actor: string;
+    onBehalfOf: string;
+    tool?: string;
+    risk?: Provenance["risk"];
+    approvedBy?: readonly Approver[];
+}
+/** The IPTC digital source type for content made by a model. */
+declare const TRAINED_ALGORITHMIC_MEDIA = "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia";
+declare function createProvenance(input: ProvenanceInput): Provenance;
+/**
+ * A JSON-LD marker for a document or a file. Store it next to the content the assistant made.
+ * It uses schema.org terms and the IPTC `trainedAlgorithmicMedia` source type.
+ */
+declare function provenanceMarker(provenance: Provenance): Record<string, unknown>;
+/** A short text for a person to read, such as "AI-generated by model-1 (acme), approved by ana". */
+declare function provenanceLabel(provenance: Provenance): string;
+
 interface ToolContext {
     principal: AssistantPrincipal;
     toolUseId: string;
@@ -126,6 +175,11 @@ declare function defineTool<Input>(tool: ToolDefinition<Input>): ToolDefinition;
 declare class ToolRegistry {
     private readonly tools;
     private readonly ajv;
+    /**
+     * Ajv builds validators with `new Function`. Workers refuse that inside a request, though not while a module loads.
+     * So try Ajv first, and use the small checker when this host refuses code generation. A bad schema still throws.
+     */
+    private compile;
     register(tool: ToolDefinition): this;
     registerAll(tools: readonly ToolDefinition[]): this;
     get(name: string): ToolDefinition | undefined;
@@ -191,7 +245,8 @@ type AssistantEvent = {
 } | {
     type: "approval_decision";
     requestId: string;
-    approved: boolean;
+    approved: boolean; /** True only when the approver said no. A timeout or a gate failure is not a decline. */
+    declined: boolean;
     decidedBy?: string;
     reason?: string;
 } | {
@@ -206,18 +261,22 @@ type AssistantEvent = {
     /** The raw failure text. It stays in the event and never goes to the model. */
     detail?: string;
     actor: Actor;
+    /** Marks the result as machine-made. Set when the tool ran. */
+    provenance?: Provenance;
 } | {
     type: "turn_end";
     turn: number;
     usage: Usage;
-    totals: RunTotals;
+    totals: RunTotals; /** The model that answered this turn. */
+    answeredBy: AnsweredBy;
 } | {
     type: "done";
     reason: DoneReason;
     totals: RunTotals;
     actor: Actor;
     messages: Message[];
-    error?: string;
+    error?: string; /** Marks the answer as machine-made. Set once a model has answered. */
+    provenance?: Provenance;
 };
 /** Sent with every request. Tool output is data, never an instruction. */
 declare const DATA_NOTICE: string;
@@ -228,4 +287,4 @@ declare const DATA_NOTICE: string;
  */
 declare function runAssistant(options: RunOptions): AsyncGenerator<AssistantEvent>;
 
-export { ACTIONS as A, DATA_NOTICE as D, PrincipalError as P, QueueApprovalGate as Q, type RunLimits as R, type Scope as S, type ToolRisk as T, type ToolDefinition as a, type Action as b, type Actor as c, type ApprovalDecision as d, type ApprovalGate as e, type ApprovalRequest as f, type AssistantEvent as g, type AssistantPrincipal as h, type DeniedReason as i, type DoneReason as j, type PrincipalInput as k, type RunOptions as l, type RunTotals as m, TOOL_RISKS as n, type ToolContext as o, ToolRegistry as p, actorOf as q, assertPrincipal as r, canonicalJson as s, createPrincipal as t, defineTool as u, digestCall as v, hasScope as w, parseScope as x, runAssistant as y, scopeCovers as z };
+export { type AssistantEvent as A, defineTool as B, digestCall as C, type DeniedReason as D, hasScope as E, parseScope as F, provenanceLabel as G, provenanceMarker as H, runAssistant as I, scopeCovers as J, PrincipalError as P, QueueApprovalGate as Q, type RunTotals as R, type Scope as S, TOOL_RISKS as T, type ApprovalRequest as a, type Actor as b, type DoneReason as c, ACTIONS as d, type Action as e, type ApprovalDecision as f, type ApprovalGate as g, type Approver as h, type ApproverKind as i, type AssistantPrincipal as j, DATA_NOTICE as k, type PrincipalInput as l, type Provenance as m, type ProvenanceInput as n, type RunLimits as o, type RunOptions as p, TRAINED_ALGORITHMIC_MEDIA as q, type ToolContext as r, type ToolDefinition as s, ToolRegistry as t, type ToolRisk as u, actorOf as v, assertPrincipal as w, canonicalJson as x, createPrincipal as y, createProvenance as z };

package/dist/mcp-server-ZPCPYMCT.js

@@ -0,0 +1,12 @@
+import {
+  createAssistantMcpServer,
+  startAssistantMcp
+} from "./chunk-T5WVSGYQ.js";
+import "./chunk-3X6KU636.js";
+import "./chunk-HYT732TN.js";
+import "./chunk-DXTIEMOT.js";
+import "./chunk-3LKTJJ75.js";
+export {
+  createAssistantMcpServer,
+  startAssistantMcp
+};

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { g as AssistantEvent, T as ToolRisk } from './loop-CDbbDwSs.js';
-import { c as Message } from './types-C47SyHH5.js';
+import { A as AssistantEvent, u as ToolRisk } from './loop-D4qWbRu6.js';
+import { c as Message } from './types-DGH8FS56.js';
 
 type PanelItem = {
     kind: "user";

package/dist/react.js

@@ -41,6 +41,7 @@ function useAssistant(options) {
     const sent = [...history.current, userMessage];
     let streamingId = null;
     let finished = false;
+    let failed = false;
     const toolItems = /* @__PURE__ */ new Map();
     let lastToolItem = null;
     try {
@@ -81,7 +82,7 @@ function useAssistant(options) {
               event.requestId,
               (item) => item.kind === "approval" ? {
                 ...item,
-                status: event.approved ? "approved" : event.reason === "the person declined" ? "declined" : "unavailable",
+                status: event.approved ? "approved" : event.declined ? "declined" : "unavailable",
                 busy: false,
                 decidedBy: event.decidedBy
               } : item
@@ -109,11 +110,16 @@ function useAssistant(options) {
         }
       }
     } catch {
-      add({ kind: "notice", id: nextId(), text: RUN_FAILED });
+      failed = true;
     } finally {
-      if (!finished) history.current = sent;
+      if (!finished) {
+        history.current = sent;
+        if (!failed) failed = true;
+      }
+      if (failed) add({ kind: "notice", id: nextId(), text: RUN_FAILED });
       setItems(
         (current) => current.map((item) => {
+          if (item.kind === "assistant" && item.streaming) return { ...item, streaming: false };
           if (item.kind === "approval" && item.status === "pending") return { ...item, status: "expired", busy: false };
           if (item.kind === "tool" && (item.status === "running" || item.status === "waiting")) return { ...item, status: "not_run" };
           return item;

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { M as ModelProvider, P as Pricing, a as ModelRequest, S as StopReason, U as Usage, b as ModelEvent } from './types-C47SyHH5.js';
+import { M as ModelProvider, P as Pricing, a as ModelRequest, S as StopReason, U as Usage, b as ModelEvent } from './types-DGH8FS56.js';
 
 interface ScriptedTurn {
     text?: string;
@@ -19,7 +19,7 @@ declare class ScriptedProvider implements ModelProvider {
     private readonly script;
     readonly pricing?: Pricing | undefined;
     readonly name = "scripted";
-    readonly model = "scripted-1";
+    readonly model: string;
     readonly requests: ModelRequest[];
     private next;
     constructor(script: readonly ScriptedTurn[], pricing?: Pricing | undefined);

package/dist/testing.js

@@ -1,35 +1,6 @@
-// src/testing.ts
-var ScriptedProvider = class {
-  constructor(script, pricing) {
-    this.script = script;
-    this.pricing = pricing;
-  }
-  script;
-  pricing;
-  name = "scripted";
-  model = "scripted-1";
-  requests = [];
-  next = 0;
-  async *stream(request) {
-    this.requests.push({ ...request, messages: structuredClone(request.messages) });
-    const turn = this.script[this.next++];
-    if (turn === void 0) throw new Error(`scripted provider ran out of turns at request ${this.next}`);
-    const content = [];
-    if (turn.text !== void 0) {
-      for (const word of turn.text.split(/(?<= )/)) yield { type: "text_delta", text: word };
-      content.push({ type: "text", text: turn.text });
-    }
-    for (const [index, call] of (turn.toolCalls ?? []).entries()) {
-      content.push({ type: "tool_use", id: call.id ?? `call_${this.next}_${index}`, name: call.name, input: call.input });
-    }
-    yield {
-      type: "message",
-      content,
-      stopReason: turn.stopReason ?? (turn.toolCalls?.length ? "tool_use" : "end_turn"),
-      usage: turn.usage ?? { inputTokens: 10, outputTokens: 5 }
-    };
-  }
-};
+import {
+  ScriptedProvider
+} from "./chunk-HYT732TN.js";
 export {
   ScriptedProvider
 };

package/dist/{types-C47SyHH5.d.ts → types-DGH8FS56.d.ts}

@@ -41,6 +41,15 @@ interface ModelRequest {
     maxOutputTokens: number;
     signal?: AbortSignal;
 }
+/** Which model gave an answer. A provider that picks between models sets it on the final message. */
+interface AnsweredBy {
+    provider: string;
+    model: string;
+    /** True when a fallback model answered. */
+    fallback: boolean;
+    /** Why the first model did not answer. Set only when `fallback` is true. */
+    fallbackFor?: "refusal" | "error";
+}
 type ModelEvent = {
     type: "text_delta";
     text: string;
@@ -49,6 +58,7 @@ type ModelEvent = {
     content: ContentBlock[];
     stopReason: StopReason;
     usage: Usage;
+    answeredBy?: AnsweredBy;
 };
 /** Prices in US dollars per million tokens. */
 interface Pricing {
@@ -63,10 +73,12 @@ interface ModelProvider {
     readonly name: string;
     readonly model: string;
     readonly pricing?: Pricing;
+    /** Most requests one `stream` call may send to a model. Default 1. The loop counts the input of each in its caps. */
+    readonly maxAsks?: number;
     stream(request: ModelRequest): AsyncIterable<ModelEvent>;
 }
 declare class ProviderError extends Error {
     constructor(message: string);
 }
 
-export { type ContentBlock as C, type JsonSchema as J, type ModelProvider as M, type Pricing as P, type StopReason as S, type ToolSpec as T, type Usage as U, type ModelRequest as a, type ModelEvent as b, type Message as c, ProviderError as d };
+export { type AnsweredBy as A, type ContentBlock as C, type JsonSchema as J, type ModelProvider as M, type Pricing as P, type StopReason as S, type ToolSpec as T, type Usage as U, type ModelRequest as a, type ModelEvent as b, type Message as c, ProviderError as d };

package/dist/worker.d.ts

@@ -1,8 +1,49 @@
+import { Auth } from 'agentic-identity';
+import { t as ToolRegistry, o as RunLimits } from './loop-D4qWbRu6.js';
+import { M as ModelProvider } from './types-DGH8FS56.js';
+
+interface AssistantApiOptions {
+    /** Reads the credential on a request. Use an `agentic-identity` Auth, such as `createStoreAuth`. */
+    auth: Auth;
+    /** Makes the model for one chat turn. Called once per request, so a provider may keep state. */
+    provider(): ModelProvider;
+    /** The tools the assistant may use. Each one has a scope and a risk. */
+    registry: ToolRegistry;
+    system?: string;
+    limits?: RunLimits;
+    /** Most chat turns one principal may run at once. Default 4. */
+    maxConcurrentRuns?: number;
+}
+/** An agent needs this scope before it may decide on a tool call. A person needs no extra scope. */
+declare const APPROVER_SCOPE = "assistant:admin";
+/**
+ * The hosted API, under `/api/v1`: `GET /tools`, `POST /chat` (a stream of server-sent events),
+ * `GET /approvals`, and `POST /approvals/:id/approve` or `/deny`. Every route needs a principal.
+ *
+ * A pending approval lives in the memory of this object. Run chat and approval on one instance.
+ */
+declare function createAssistantApi(options: AssistantApiOptions): {
+    fetch(request: Request): Promise<Response>;
+};
+
+/** What one bearer token stands for. The caller is always a person: `kind: "human"`. */
+interface StaticTokenEntry {
+    id: string;
+    scopes: string[];
+}
+/**
+ * An `agentic-identity` Auth that reads `Authorization: Bearer <token>` against a fixed map.
+ * It keeps only SHA-256 digests. It throws on a token shorter than 32 bytes or an entry of the wrong shape.
+ * An empty map is allowed: every request is then a 401.
+ */
+declare function createStaticTokenAuth(tokens: Record<string, StaticTokenEntry>): Promise<Auth>;
+
 interface WorkerEnv {
     PACK_NAME?: string;
 }
-declare const _default: {
-    fetch(request: Request, env: WorkerEnv): Promise<Response>;
+/** A Worker that serves `/health` and the `/api/v1` routes. Build the options in your own entry file. */
+declare function createWorker(options: AssistantApiOptions): {
+    fetch(request: Request, env?: WorkerEnv): Promise<Response>;
 };
 
-export { type WorkerEnv, _default as default };
+export { APPROVER_SCOPE, type AssistantApiOptions, type StaticTokenEntry, type WorkerEnv, createAssistantApi, createStaticTokenAuth, createWorker };

package/dist/worker.js

@@ -1,17 +1,13 @@
 import {
-  VERSION
-} from "./chunk-4QE7E5UQ.js";
-
-// src/worker.ts
-var worker_default = {
-  async fetch(request, env) {
-    const url = new URL(request.url);
-    if (request.method === "GET" && url.pathname === "/health") {
-      return Response.json({ ok: true, pack: env.PACK_NAME ?? "agentic-assistant", version: VERSION });
-    }
-    return Response.json({ error: "not found" }, { status: 404 });
-  }
-};
+  APPROVER_SCOPE,
+  createAssistantApi,
+  createStaticTokenAuth,
+  createWorker
+} from "./chunk-GLU222OQ.js";
+import "./chunk-3LKTJJ75.js";
 export {
-  worker_default as default
+  APPROVER_SCOPE,
+  createAssistantApi,
+  createStaticTokenAuth,
+  createWorker
 };

package/llms.txt

@@ -5,6 +5,10 @@ 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. Chat responses carry x-ai-generated: true. Demo: https://agentic-assistant-demo.hello-fd1.workers.dev (needs a bearer key; no model key set, so chat answers 503 not_configured).
+- HTTP client: import { createClient, AssistantApiError } from "agentic-assistant/client"; createClient({ baseUrl, token, fetch? }) gives health, tools, chat (async generator of events), approvals, approve(id, digest), deny(id, reason?). Typed errors with code and status.
+- 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".
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-assistant",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "An AI assistant that acts inside your apps with the user's own permissions.",
   "keywords": [
     "assistant",
@@ -23,12 +23,13 @@
   "type": "module",
   "private": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "files": [
     "dist",
     "llms.txt",
-    "SKILL.md"
+    "SKILL.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -40,6 +41,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
@@ -58,11 +67,14 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "clean": "rm -rf dist",
+    "deploy:demo": "npm run build && WRANGLER_SEND_METRICS=false wrangler deploy --config wrangler.demo.jsonc",
+    "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.4.0",
     "ajv": "^8.20.0"
   },
   "devDependencies": {
@@ -77,7 +89,8 @@
     "react-dom": "^19.3.1",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "wrangler": "^4.155.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/dist/chunk-4QE7E5UQ.js

@@ -1,7 +0,0 @@
-// src/version.ts
-import { createRequire } from "module";
-var VERSION = true ? "0.1.0" : readPackageVersion();
-
-export {
-  VERSION
-};