agentic-assistant 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.0
+
+Added
+
+- AI transparency. Each tool result whose tool ran, and each run that got a model answer, carries a `provenance` record with `generator: "ai"`, model, provider, time, assistant id, the person it acts for, the tool and its risk, and the approver with a `kind`. A denied call has no record.
+- `createProvenance`, `provenanceMarker` (JSON-LD with the IPTC `trainedAlgorithmicMedia` source type) and `provenanceLabel`.
+- The record is in SDK events, the HTTP chat stream, `--json` output of the CLI, and `assistant_chat` results of the MCP server. The MCP result also holds `label` and `marker`. The CLI prints the label after a run.
+- Approval decisions may carry `approverKind` (`human`, `agent`, or `host`). A decision without it is recorded as `unknown`. `QueueApprovalGate.approve(id, decidedBy, approverKind)` takes it as a third argument: pass it, or every record shows `unknown`. The CLI sets `host` for a pre-approved call and `human` for a typed yes. The HTTP API sets `human` for a person and `agent` for any other caller.
+
+Changed
+
+- A provider that gives an empty model or provider name now ends the run with `provider_error` before any tool runs.
+
+## 0.1.0
+
+First release.

package/README.md

@@ -7,8 +7,8 @@
 
 An AI assistant that acts inside your apps with the user's own permissions.
 
-> Status: version 0.1.0, the first release. The core loop, the tool sources, approvals, and the React panel work.
-> The chat CLI and the MCP server are not built yet. The `agentic-assistant` command only prints help and version.
+> Status: early. The core loop, the tool sources, approvals, the React panel, the CLI, and the MCP server work.
+> There is no hosted HTTP API yet.
 
 ## Install
 
@@ -120,6 +120,99 @@ The panel streams the answer, shows each tool call as a card, and shows an appro
 
 The look comes from plain CSS variables (`--aa-bg`, `--aa-fg`, `--aa-accent`, and others). Set them on `.aa-panel` or a parent. The sheet loads no font, image, or file from another host. A prompt that the run left open (after Stop or an error) is closed and marked expired. Closing the panel stops the run.
 
+## Use the CLI
+
+```sh
+export ANTHROPIC_API_KEY=...
+agentic-assistant chat \
+  --tools https://notes.example.eu/mcp --tools-header-env authorization=NOTES_TOKEN \
+  --scope notes:read --tool-scope notes:read --tool-risk safe \
+  --use-default-endpoint \
+  "What does note 7 say?"
+```
+
+The assistant prints its answer on stdout. The answer starts with `Assistant (machine-made):`. Tool calls and approval requests on stderr start with `[machine-made]`, and so does the question that `--approve ask` shows. Control characters are removed from all text it prints for a person, so a tool cannot move your cursor or change your terminal title. `--json` events are not changed: they carry the `actor` with `machineMade: true` on each action, and the text events belong to the labeled run. Add `--json` to get one event per line on stdout: that is the form for agents and tests. The exit code is 0 when the run ends normally, 1 when it stops for another reason (a cap, an error), and 2 for a usage error.
+
+- `--tools` takes an `https` MCP URL, or a command that starts a server on stdio (words split on spaces, or a JSON list like `'["node","server.js"]'`).
+- `--scope` is what the assistant may hold. `--tool-scope` is what each tool needs. Both are required, and the CLI guesses neither.
+- `--tool-risk` defaults to `risky`. A risky call needs approval. Approve one exact call ahead of time with `--approve-call '{"tool":"notes_write","input":{"id":"7","text":"hi"}}'`. The call must match the tool and the arguments, and each approval is used once. On a terminal, `--approve ask` asks you.
+- Keys come from the environment: `ANTHROPIC_API_KEY`, or the variable named by `--api-key-env`. There is no flag that takes a key.
+- For an EU-hosted model, use `--provider openai-compatible --base-url https://models.example.eu/v1 --model <id> --api-key-env EU_KEY`. Add `--price-in` and `--price-out` to use the cost cap.
+- A message on stdin may be up to 1 MB.
+- Limits: `--max-turns`, `--max-tokens`, `--max-cost`, `--max-tool-calls`.
+- `--provider scripted --script turns.json` replays fixed turns. It is for tests.
+
+## Run it as an MCP server
+
+```sh
+agentic-assistant mcp --tools https://notes.example.eu/mcp --scope notes:read --tool-scope notes:read --tool-risk safe --use-default-endpoint
+```
+
+Add this to an MCP client as a stdio server. It offers one tool, `assistant_chat`, with one argument, `message`. Each call starts a new conversation. The reply is JSON with `machineMade: true`, the answer, the stop reason, and the tool calls. A run that stops on a cap is an error result. The caps (`--max-turns`, `--max-cost`) apply to one call, and the server has no total limit, so set a limit in the client that calls it. The server stops when the client closes its input. A call that is still running is cancelled and dropped: the client gets no reply for it. The tool servers are closed. The server cannot ask a person, so a risky call runs only when you started the server with a matching `--approve-call`.
+
+## Run it as a hosted HTTP API
+
+```ts
+// src/index.ts of your Worker. `store`, `registry`, and `Env` are yours.
+import { createWorker } from "agentic-assistant/worker";
+import { AnthropicProvider } from "agentic-assistant";
+import { createStoreAuth } from "agentic-identity";
+
+let worker: ReturnType<typeof createWorker> | undefined;
+
+export default {
+  fetch(request: Request, env: Env) {
+    // Build the worker once. It keeps the pending approvals, so a new one per request would lose them.
+    worker ??= createWorker({
+      auth: createStoreAuth(store(env)),
+      registry,
+      provider: () => new AnthropicProvider({ baseUrl: env.MODEL_URL, apiKey: env.MODEL_KEY }),
+    });
+    return worker.fetch(request, env);
+  },
+};
+```
+
+Every route is under `/api/v1` and needs `Authorization: Bearer <key>`. The key resolves to an `agentic-identity` principal. A person, an agent, and a token that acts for a user all work. A missing, bad, or odd credential is a 401.
+
+| Route | What it does |
+|---|---|
+| `GET /tools` | The tools inside the caller's scopes: name, description, scope, risk, input schema. |
+| `POST /chat` `{"message":"..."}` | One new conversation. The answer is a stream of server-sent events (`event: <type>`, `data: <json>`), the same events as `runAssistant`, ending with `done`. |
+| `GET /approvals` | Pending risky calls of the same owner, with the digest and `canDecide`. |
+| `POST /approvals/:id/approve` `{"digest":"..."}` | Approve the exact call. A wrong digest is a 409. |
+| `POST /approvals/:id/deny` `{"reason":"..."}` | Refuse the call. |
+
+The assistant holds the caller's scopes and no more. A chat turn waits at a risky call until another principal decides. The stream stays open for that time. A principal that asked for the turn never decides on its own proposal: an agent gets a 403 for both approve and deny. The same holds for an agent it made and for the agent that made it. A person who asks may decide, because the assistant proposed the call. Another agent may decide only when it holds `assistant:admin` and the scope of the tool. A principal with another owner sees a 404. The list hides a call whose tool the caller has no scope for. If a client hangs up, the run stops and its pending calls go. If the key is revoked or its scopes change during a run, the run stops before its next tool call.
+
+## AI transparency
+
+The package marks what the assistant makes as AI-generated. This follows the idea of EU AI Act Article 50.
+
+Each tool result and each finished run carries a `provenance` record: `generator: "ai"`, the model, the provider, the time, the assistant id, the person it acts for, and the tool, its risk, and the approver when someone approved the call. The approver has a `kind`: `human`, `agent`, `host` (a rule you set), or `unknown`. Say "a person approved" only for `human`. After a fallback, the record names the model that answered. A denied call has no record, because nothing ran.
+
+```ts
+import { provenanceLabel, provenanceMarker } from "agentic-assistant";
+
+for await (const event of runAssistant(options)) {
+  if (event.type === "tool_result" && event.provenance) {
+    provenanceLabel(event.provenance); // "AI-generated by model-1 (acme), approved by ana"
+    provenanceMarker(event.provenance); // JSON-LD with the IPTC trainedAlgorithmicMedia source type
+  }
+}
+```
+
+The record is in the SDK events, in the HTTP chat stream, in `--json` output of the CLI, and in the `assistant_chat` result of the MCP server. The MCP result also holds `label` and `marker`. The CLI prints the label after each run.
+
+The host must still do these things:
+
+- Store the marker with every document or file the assistant changes.
+- Show the label to people where they read the content.
+- Label chat text that the assistant makes, if you show it outside this package.
+- Keep records as long as the law needs, and get legal advice. This package does not make a deployment compliant.
+
+The record says who made the content. It does not say the content is true.
+
 ## Features
 
 - **Model port.** `ModelProvider` has two adapters. `AnthropicProvider` needs a `baseUrl`, or `useDefaultEndpoint: true` to call `api.anthropic.com`, which is a US-hosted endpoint. There is no silent default. `OpenAICompatibleProvider` calls any server that speaks the chat-completions stream, so you can use an EU-hosted model. Both adapters need an `https` URL, except for `localhost`. If you pass your own `client` to `AnthropicProvider`, you own its endpoint. The OpenAI-compatible adapter needs an API key for any other host and cuts a response at a size limit.
@@ -128,7 +221,8 @@ The look comes from plain CSS variables (`--aa-bg`, `--aa-fg`, `--aa-accent`, an
 - **Input validation.** The loop checks each call against the tool's JSON Schema before the handler runs. Nothing is coerced. A bad call returns an error to the model and never reaches the tool.
 - **Tool output is data.** Each result is quoted in `<tool_output>` tags. Every `<` in the output is escaped. Every request carries a notice that tool output is never an instruction. This lowers the risk of prompt injection. It does not remove it: keep tools narrow and scopes small.
 - **Approvals.** Every tool has a required `risk`: `safe`, `risky`, or `irreversible`. The loop asks the `ApprovalGate` before a risky or irreversible call. With no gate, those tools are not offered and are refused. The text a person writes when they decline goes to the event, not to the model.
-- **React panel.** `agentic-assistant/react` has `AssistantPanel` and `useAssistant`. It meets the WCAG 2.2 AA points that code can check: named controls, a live conversation log, keyboard use, focus that moves to an approval prompt and then to the message box, buttons that are at least 32 px, a visible focus ring, and a color palette checked for contrast.
+- **React panel.** `agentic-assistant/react` has `AssistantPanel` and `useAssistant`. It is built to these WCAG 2.2 AA points: named controls, a live conversation log, keyboard use, focus that moves to an approval prompt and then to the message box, buttons that are at least 32 px, a visible focus ring, and a color palette checked for contrast.
+- **CLI and MCP server.** `chat` and `mcp` take the host choices as flags and refuse to guess a scope.
 - **Fixed principal.** The assistant always acts as `agent_of_human`. `createPrincipal` throws when the kind is missing or different.
 - **Caps.** A max-turn cap, a total-token cap, and a cost cap. A cap that trips stops the run. No tool runs after that. A tool result is cut at `maxToolResultChars`. A request that is sure to pass the token cap is not sent. The cost cap also limits the output of each request. A turn with more than `maxToolCallsPerTurn` calls (default 16) runs none of them.
 - **Stops that fail closed.** An expired or revoked principal stops the run. So does a revocation check that throws or returns anything but `false`. The loop checks the principal again at the start of each run. A provider error ends the run with `reason: "provider_error"` and keeps the transcript. Truncated or refused model output never runs its tool calls.
@@ -137,16 +231,18 @@ The look comes from plain CSS variables (`--aa-bg`, `--aa-fg`, `--aa-accent`, an
 
 ## Limits
 
-- The chat CLI and the MCP server are not built. The `agentic-assistant` command prints help and version only.
+- The hosted API keeps pending approvals in the memory of one Worker instance. A decision must reach the instance that holds the chat stream. Run it on one instance or behind sticky routing until a shared queue exists. It has no per-IP limit, only a cap of four chat turns at once per principal.
+- The tests run the API under Node with a fake model. They do not run it under `wrangler dev`. The sample Worker in `wrangler.jsonc` answers `/health` only.
+- The CLI reads one message, or a short conversation on a terminal. It does not keep a conversation between runs.
 - The panel is tested in a simulated browser (jsdom). Contrast is checked from the CSS values. Run a screen reader and a real browser before you ship it to people who need it.
 - The panel shows plain text, not Markdown.
 - The gate trusts the name that `decidedBy` carries. Your gate must check who the person is. `QueueApprovalGate` does not.
 - An MCP server is trusted for its own output only. The assistant does not sandbox the server process. Run stdio servers you trust.
 - Token and cost caps need the provider to report usage. The OpenAI-compatible adapter throws when the server sends none.
-- A cost is an estimate from the `pricing` you give. Cache discounts are not applied. The built-in Anthropic prices are from 2026-10-06. Check them.
+- A cost is an estimate from the `pricing` you give. Cache discounts are not applied. The built-in Anthropic prices were checked on 2026-10-29 (`PRICING_CHECKED_ON`). A test fails when that date is over 120 days old. Haiku has no built-in price, because its rate changes with the prompt size. Pass `pricing` for it. Check the prices before you rely on a cap.
 - The token pre-check guesses three characters per token. It is an estimate.
 - A tool error text goes to the `detail` field of the event. The model sees only `tool failed`.
-- A model refusal stops the run. No automatic fallback model is set up.
+- A model refusal stops the run, unless you set a fallback model. `FallbackProvider(primary, fallback)` or `--fallback-model <id>` asks the second model once when the first refuses or fails. Each `turn_end` event has `answeredBy` with the model that answered. The text of the first model is held until its turn ends, so a turn with a fallback does not stream word by word. A refusal from the fallback stops the run. The fallback gets only the output room that the first ask left, and the caps count the input of both asks, so a token or cost cap holds. A first ask that failed after it streamed is counted by an estimate. If the fallback itself fails after it streamed, the totals of that run leave out the first ask. Its error text is not kept.
 
 ## Develop
 
@@ -155,6 +251,12 @@ npm ci
 npm run ci:local
 ```
 
+The live smoke test calls the real Anthropic API. It costs a few cents, so it runs only when you ask:
+
+```sh
+AGENTIC_ASSISTANT_LIVE=1 ANTHROPIC_API_KEY=... npx vitest run src/live.smoke.test.ts
+```
+
 ## License
 
 MIT.

package/SKILL.md

@@ -27,6 +27,23 @@ registry.registerAll(mcp.tools);
 
 Give each tool a `risk`. Pass `approvals: new QueueApprovalGate()` to `runAssistant`. On an `approval_request` event, show the exact arguments. Then call `approve(id, personId)` or `reject(id, personId)`.
 
+## Serve the HTTP API
+
+```ts
+import { createWorker } from "agentic-assistant/worker";
+const worker = createWorker({ auth, registry, provider: () => model });
+```
+
+Routes: `GET /api/v1/tools`, `POST /api/v1/chat` (server-sent events), `GET /api/v1/approvals`, `POST /api/v1/approvals/:id/approve` with the digest, and `/deny`. The caller that asked for a turn never decides on it, if it is an agent.
+
+## Use the CLI
+
+```sh
+agentic-assistant chat --tools <mcp-url> --scope notes:read --tool-scope notes:read --tool-risk safe --json "message"
+```
+
+Set the key in the environment. Approve one exact risky call with `--approve-call`. Read the exit code: 0 normal, 1 stopped or failed, 2 usage.
+
 ## Show a panel
 
 ```tsx

package/dist/chat-pBg4wRjQ.d.ts

@@ -0,0 +1,120 @@
+import { S as Scope, u as ToolRisk, s as ToolDefinition, R as RunLimits, t as ToolRegistry, d as ApprovalGate, h as AssistantEvent } from './loop-42giKLVa.js';
+import { P as Pricing, M as ModelProvider, c as Message } from './types-DGH8FS56.js';
+
+type McpTransportConfig = {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+} | {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+};
+interface McpToolInfo {
+    name: string;
+    description?: string;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+interface ConnectMcpOptions {
+    transport: McpTransportConfig;
+    /** The scope each tool needs. There is no default. A function can choose per tool. */
+    scope: Scope | ((tool: McpToolInfo) => Scope);
+    /** How risky each tool is. There is no default. A function can choose per tool. Do not trust the server's hints. */
+    risk: ToolRisk | ((tool: McpToolInfo) => ToolRisk);
+    /** Put before each tool name, to keep names from two servers apart. */
+    prefix?: string;
+    /** Most characters of tool output to keep. Default 32768. */
+    maxOutputChars?: number;
+    /** Most tools to load. Default 200. */
+    maxTools?: number;
+    /** Longest tool description to pass to the model. Default 1000. */
+    maxDescriptionChars?: number;
+    /** Time to wait for one tool call. Default 30000. */
+    callTimeoutMs?: number;
+    /** Time to connect and list every tool, all pages together. Default 30000. */
+    loadTimeoutMs?: number;
+    /** Most bytes to read from one HTTP response. Default 4000000. Stdio is limited by the SDK. */
+    maxResponseBytes?: number;
+}
+interface McpTools {
+    tools: ToolDefinition[];
+    /** Tools that were not loaded, with the reason. */
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+    close(): Promise<void>;
+}
+/**
+ * Connects to an MCP server and turns its tools into assistant tools. The host
+ * names the scope each tool needs. Output text is capped, and non-text content is
+ * left out. Tools with a bad name, schema, or scope are skipped, not loaded.
+ */
+declare function connectMcpTools(options: ConnectMcpOptions): Promise<McpTools>;
+
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+interface ChatConfig {
+    /** An http(s) URL of an MCP server, or a command line that starts one on stdio. */
+    tools: string;
+    /** Names of environment variables that hold HTTP headers for the MCP server: `header=ENV_NAME`. */
+    toolHeaderEnv: string[];
+    scopes: string[];
+    toolScope: string;
+    toolRisk: ToolRisk;
+    provider: "anthropic" | "openai-compatible" | "scripted";
+    model?: string;
+    /** A second model on the same provider. It answers once when the first one refuses or fails. */
+    fallbackModel?: string;
+    baseUrl?: string;
+    useDefaultEndpoint: boolean;
+    apiKeyEnv?: string;
+    pricing?: Pricing;
+    script?: string;
+    system?: string;
+    user: string;
+    limits: RunLimits;
+    /** Exact calls a person approved before the run. Each is used once. */
+    preApproved: {
+        tool: string;
+        input: unknown;
+    }[];
+    approve: "deny" | "ask";
+}
+interface ChatIo {
+    env: Record<string, string | undefined>;
+    readFile(path: string): string;
+    /** Ask a person a question and return the answer. Only used for `--approve ask`. */
+    ask?(question: string): Promise<string>;
+}
+interface Setup {
+    provider: ModelProvider;
+    registry: ToolRegistry;
+    gate: ApprovalGate;
+    principalOptions: {
+        id: string;
+        parentId: string;
+        scopes: string[];
+    };
+    limits: RunLimits;
+    system?: string;
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+    close(): Promise<void>;
+}
+/** An http(s) URL is an HTTP server. A JSON array of strings, or words split on spaces, is a command. */
+declare function parseTarget(target: string, headerEnv: string[], env: ChatIo["env"]): McpTransportConfig;
+declare function buildSetup(config: ChatConfig, io: ChatIo): Promise<Setup>;
+declare function runChat(setup: Setup, messages: Message[], signal?: AbortSignal): AsyncGenerator<AssistantEvent>;
+
+export { type ChatConfig as C, type McpToolInfo as M, type Setup as S, type ChatIo as a, ConfigError as b, type ConnectMcpOptions as c, type McpTools as d, type McpTransportConfig as e, buildSetup as f, connectMcpTools as g, parseTarget as p, runChat as r };

package/dist/chunk-6UD2QQA4.js

@@ -0,0 +1,82 @@
+import {
+  runChat
+} from "./chunk-BDXAUNMR.js";
+import {
+  VERSION,
+  provenanceLabel,
+  provenanceMarker
+} from "./chunk-T4ZMDOB4.js";
+
+// src/mcp-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+var MAX_MESSAGE_CHARS = 1e4;
+var TOOL = {
+  name: "assistant_chat",
+  description: "Send one message to the assistant. It acts for a person with the scopes the host gave it. A risky action runs only if the host pre-approved that exact call. The reply says it is machine-made.",
+  inputSchema: {
+    type: "object",
+    properties: { message: { type: "string", minLength: 1, maxLength: MAX_MESSAGE_CHARS, description: "What to ask the assistant." } },
+    required: ["message"],
+    additionalProperties: false
+  },
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
+};
+var fail = (text) => ({ isError: true, content: [{ type: "text", text }] });
+function createAssistantMcpServer(setup, shutdown) {
+  const server = new Server({ name: "agentic-assistant", version: VERSION }, { capabilities: { tools: {} } });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [TOOL] }));
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    if (request.params.name !== TOOL.name) return fail(`unknown tool "${request.params.name}"`);
+    const message = request.params.arguments?.message;
+    if (typeof message !== "string" || message.trim() === "" || message.length > MAX_MESSAGE_CHARS) {
+      return fail(`message must be a text of 1 to ${MAX_MESSAGE_CHARS} characters`);
+    }
+    const call = new AbortController();
+    const stop = () => call.abort();
+    extra.signal.addEventListener("abort", stop, { once: true });
+    shutdown?.addEventListener("abort", stop, { once: true });
+    if (extra.signal.aborted || shutdown?.aborted) stop();
+    let reply = "";
+    const toolCalls = [];
+    let outcome;
+    for await (const event of runChat(setup, [{ role: "user", content: [{ type: "text", text: message }] }], call.signal)) {
+      if (event.type === "text_delta") reply += event.text;
+      else if (event.type === "turn_start") reply = "";
+      else if (event.type === "tool_result") toolCalls.push({ name: event.name, isError: event.isError, ...event.denied ? { denied: event.denied } : {}, ...event.provenance ? { provenance: event.provenance } : {} });
+      else if (event.type === "done") outcome = { reason: event.reason, totals: event.totals, provenance: event.provenance };
+    }
+    extra.signal.removeEventListener("abort", stop);
+    shutdown?.removeEventListener("abort", stop);
+    const provenance = outcome?.provenance;
+    const result = {
+      machineMade: true,
+      reply,
+      reason: outcome?.reason ?? "unknown",
+      toolCalls,
+      totals: outcome?.totals,
+      ...provenance ? { provenance, label: provenanceLabel(provenance), marker: provenanceMarker(provenance) } : {}
+    };
+    return { ...outcome?.reason === "end_turn" ? {} : { isError: true }, content: [{ type: "text", text: JSON.stringify(result) }] };
+  });
+  return server;
+}
+async function startAssistantMcp(setup) {
+  const shutdown = new AbortController();
+  const server = createAssistantMcpServer(setup, shutdown.signal);
+  const ended = new Promise((resolve) => {
+    server.onclose = resolve;
+    process.stdin.once("end", resolve);
+    process.stdin.once("close", resolve);
+  });
+  await server.connect(new StdioServerTransport());
+  await ended;
+  shutdown.abort();
+  await server.close().catch(() => void 0);
+}
+
+export {
+  createAssistantMcpServer,
+  startAssistantMcp
+};