agentic-assistant 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pooria Arab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# agentic-assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/agentic-assistant)](https://www.npmjs.com/package/agentic-assistant)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit)
+
+[Package](https://www.npmjs.com/package/agentic-assistant) · [Source](https://github.com/pooriaarab/agentic-assistant) · [Support](https://github.com/pooriaarab/agentic-assistant/issues)
+
+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.
+
+## Install
+
+```sh
+npm install agentic-assistant
+```
+
+You need Node.js 18 or newer. The React panel needs `react` 18 or newer.
+
+To build from source:
+
+```sh
+git clone https://github.com/pooriaarab/agentic-assistant && cd agentic-assistant
+npm ci && npm run build
+```
+
+## Quick start
+
+```ts
+import { AnthropicProvider, ToolRegistry, createPrincipal, runAssistant } from "agentic-assistant";
+
+const registry = new ToolRegistry().register({
+  name: "notes_read",
+  description: "Read one note by id",
+  inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+  scope: "notes:read",
+  risk: "safe", // "risky" and "irreversible" tools wait for a person
+  handler: async ({ id }) => ({ text: `note ${id}` }),
+});
+
+// The host decides the scopes. The assistant never widens them.
+const principal = createPrincipal({
+  id: "agent-1",
+  kind: "agent_of_human",
+  parentId: "user-42",
+  scopes: ["notes:read"],
+});
+
+for await (const event of runAssistant({
+  // Reads ANTHROPIC_API_KEY. Model claude-sonnet-5-5. useDefaultEndpoint calls a US-hosted API: pass baseUrl for an EU one.
+  provider: new AnthropicProvider({ useDefaultEndpoint: true }),
+  registry,
+  principal,
+  messages: [{ role: "user", content: [{ type: "text", text: "Read note 7." }] }],
+  limits: { maxTurns: 6, maxTotalTokens: 50_000 },
+})) {
+  if (event.type === "text_delta") process.stdout.write(event.text);
+}
+```
+
+## Load tools from an MCP server
+
+```ts
+import { connectMcpTools } from "agentic-assistant";
+
+const mcp = await connectMcpTools({
+  transport: { type: "stdio", command: "npx", args: ["-y", "some-notes-mcp-server"] },
+  // The host decides the scope of each tool, by name. There is no default. Do not trust
+  // `tool.annotations`: the server writes them. A tool that is not in the list is skipped.
+  scope: (tool) => {
+    const scope = { notes_read: "notes:read", notes_write: "notes:write" }[tool.name];
+    if (scope === undefined) throw new Error("tool is not on the host's list");
+    return scope;
+  },
+  // The host also says how risky each tool is. There is no default.
+  risk: (tool) => (tool.name === "notes_read" ? "safe" : "risky"),
+});
+registry.registerAll(mcp.tools); // mcp.skipped lists tools that were not loaded, with the reason
+// ...run the assistant, then:
+await mcp.close();
+```
+
+An HTTP server works the same way: `{ type: "http", url: "https://tools.example.eu/mcp", headers: { authorization: "Bearer ..." } }`.
+
+## Ask a person before a risky action
+
+```ts
+import { QueueApprovalGate } from "agentic-assistant";
+
+const approvals = new QueueApprovalGate();
+for await (const event of runAssistant({ provider, registry, principal, messages, approvals })) {
+  if (event.type === "approval_request") {
+    showToPerson(event.request); // tool, risk, exact arguments
+    // when the person clicks, from any handler:
+    //   approvals.approve(event.request.id, "user-42")
+    //   approvals.reject(event.request.id, "user-42", "not now")
+  }
+}
+```
+
+An approval covers one request: the tool, the exact arguments, and the acting principal. The request carries a digest of those three. The decision must return the same digest, or the call is refused. The tool runs on a copy of the exact arguments the person saw, so a change to the original object cannot reach it. The agent cannot approve its own action. A gate that fails, a missed deadline (`approvalTimeoutMs`, default five minutes), or a wrong answer means the call is refused. To connect your own approval service, implement `ApprovalGate`: one method that returns a decision.
+
+## Add the side panel
+
+```tsx
+import { AssistantPanel } from "agentic-assistant/react";
+import "agentic-assistant/react.css";
+
+<AssistantPanel
+  title="Notes assistant"
+  // Run the assistant where your app wants: in the page, or behind your own HTTP stream.
+  run={(messages, signal) => runAssistant({ provider, registry, principal, messages, approvals, signal })}
+  // Pass a person's choice to your approval gate. Your app knows who the person is.
+  decide={(id, approved, reason) => (approved ? approvals.approve(id, userId) : approvals.reject(id, userId, reason))}
+/>;
+```
+
+The panel streams the answer, shows each tool call as a card, and shows an approval prompt with the exact arguments. Every message, card, and prompt that the assistant makes carries a visible "Machine-made" label. Tool output is shown as text and never as HTML. The panel does not hold a model, a key, or a gate. It needs `react` 18 or newer.
+
+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.
+
+## 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.
+- **Scoped tools.** Each tool names the scope it needs, for example `notes:write`. Scopes use the same `<resource>:<action>` format as `agentic-identity`. The model sees only the tools inside the scopes. The loop refuses a call to any other tool.
+- **Tool sources.** Load tools from an MCP server over stdio or HTTP, or write typed SDK tools with `defineTool`. The loader skips a tool with a bad name, schema, or scope. It keeps text output and leaves images and other content out. It cuts long output, long descriptions, and long text inside schemas. It skips a duplicate name, a schema that is too large, and a schema with a regular expression (`pattern`). It stops at a page limit, a load time, and a size limit on each HTTP response.
+- **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.
+- **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.
+- **Machine-made labels.** Every tool call, result, and the end of each run carry an `actor` with `machineMade: true`.
+- **Test provider.** `agentic-assistant/testing` exports `ScriptedProvider`. It replays a fixed script for E2E tests.
+
+## Limits
+
+- The chat CLI and the MCP server are not built. The `agentic-assistant` command prints help and version only.
+- 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.
+- 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.
+
+## Develop
+
+```sh
+npm ci
+npm run ci:local
+```
+
+## License
+
+MIT.

package/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: agentic-assistant
+description: An AI assistant that acts inside your apps with the user's own permissions. Use it to embed a scoped, capped, streaming agent loop with a model port. Keywords: assistant,ai,agent,tools,mcp,sdk,side-panel,approvals,eu,model-port.
+---
+
+# agentic-assistant
+
+## Use the SDK
+
+```ts
+import { runAssistant, ToolRegistry, createPrincipal, AnthropicProvider } from "agentic-assistant";
+
+const principal = createPrincipal({ id: "agent-1", kind: "agent_of_human", parentId: "user-42", scopes: ["notes:read"] });
+for await (const event of runAssistant({ provider: new AnthropicProvider({ useDefaultEndpoint: true }), registry, principal, messages })) {
+  // run_start, turn_start, text_delta, tool_call, approval_request, approval_decision, tool_result, turn_end, done
+}
+```
+
+## Load tools from an MCP server
+
+```ts
+const mcp = await connectMcpTools({ transport: { type: "stdio", command: "node", args: ["server.js"] }, scope: "notes:read", risk: "safe" });
+registry.registerAll(mcp.tools);
+```
+
+## Ask a person first
+
+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)`.
+
+## Show a panel
+
+```tsx
+<AssistantPanel run={(messages, signal) => runAssistant({ ...options, messages, signal })} decide={(id, ok) => (ok ? gate.approve(id, userId) : gate.reject(id, userId))} />
+```
+
+Import `agentic-assistant/react.css` too. Label every assistant part as machine-made.
+
+## Test without a model
+
+Use `ScriptedProvider` from `agentic-assistant/testing`. Give it one scripted turn per model call.
+
+## Rules
+
+- Pass only the scopes the person granted.
+- A denied call stays denied.
+- Never approve your own action.
+- Read `done.reason` to learn why a run stopped.

package/dist/chunk-4QE7E5UQ.js

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

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare function runCli(argv: string[], out?: (line: string) => void, err?: (line: string) => void): number;
+
+export { runCli };

package/dist/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import {
+  VERSION
+} from "./chunk-4QE7E5UQ.js";
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { pathToFileURL } from "url";
+var HELP = [
+  `agentic-assistant ${VERSION}`,
+  "An AI assistant that acts inside your apps with the user's own permissions.",
+  "",
+  "Usage: agentic-assistant [--help] [--version]"
+].join("\n");
+function runCli(argv, out = console.log, err = console.error) {
+  const [first] = argv;
+  if (first === void 0 || first === "--help" || first === "-h") {
+    out(HELP);
+    return 0;
+  }
+  if (first === "--version" || first === "-V") {
+    out(VERSION);
+    return 0;
+  }
+  err(`unknown command "${first}"`);
+  err('Run "agentic-assistant --help" for usage.');
+  return 2;
+}
+function isMainModule() {
+  const invoked = process.argv[1];
+  if (typeof invoked !== "string") return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(invoked)).href;
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  const code = runCli(process.argv.slice(2));
+  if (code !== 0) process.exit(code);
+}
+export {
+  runCli
+};

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { S as Scope, T as ToolRisk, a as ToolDefinition } from './loop-CDbbDwSs.js';
+export { A as ACTIONS, b as Action, c as Actor, d as ApprovalDecision, e as ApprovalGate, f as ApprovalRequest, g as AssistantEvent, h as AssistantPrincipal, D as DATA_NOTICE, i as DeniedReason, j as DoneReason, P as PrincipalError, k as PrincipalInput, Q as QueueApprovalGate, R as RunLimits, l as RunOptions, m as RunTotals, n as TOOL_RISKS, o as ToolContext, p as ToolRegistry, q as actorOf, r as assertPrincipal, s as canonicalJson, t as createPrincipal, u as defineTool, v as digestCall, w as hasScope, x as parseScope, y as runAssistant, z as scopeCovers } from './loop-CDbbDwSs.js';
+import Anthropic from '@anthropic-ai/sdk';
+import { M as ModelProvider, P as Pricing, a as ModelRequest, b as ModelEvent } from './types-C47SyHH5.js';
+export { C as ContentBlock, J as JsonSchema, c as Message, d as ProviderError, S as StopReason, T as ToolSpec, U as Usage } from './types-C47SyHH5.js';
+
+declare const VERSION: string;
+
+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 const DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-5-5";
+interface AnthropicProviderOptions {
+    /** Read from ANTHROPIC_API_KEY when absent. */
+    apiKey?: string;
+    /** Point at a gateway or an EU-hosted Anthropic endpoint. Required unless `useDefaultEndpoint` is true. */
+    baseUrl?: string;
+    /** Opt in to api.anthropic.com, a US-hosted endpoint. Without it, `baseUrl` is required. */
+    useDefaultEndpoint?: boolean;
+    model?: string;
+    pricing?: Pricing;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    client?: Anthropic;
+}
+declare class AnthropicProvider implements ModelProvider {
+    readonly name = "anthropic";
+    readonly model: string;
+    readonly pricing?: Pricing;
+    private readonly client;
+    private readonly effort?;
+    constructor(options?: AnthropicProviderOptions);
+    stream(request: ModelRequest): AsyncGenerator<ModelEvent>;
+}
+
+interface OpenAICompatibleOptions {
+    /** Base URL that serves `/chat/completions`, for example an EU-hosted endpoint. Required. */
+    baseUrl: string;
+    model: string;
+    /** Required for any host except localhost. An empty key is refused. */
+    apiKey?: string;
+    pricing?: Pricing;
+    /** Most bytes to read from one response, comments and keep-alive lines included. Default 4,000,000. */
+    maxResponseBytes?: number;
+    /** Provider name in events and errors. Default "openai-compatible". */
+    name?: string;
+}
+/** Speaks the OpenAI chat-completions streaming wire format, so any compatible server works. */
+declare class OpenAICompatibleProvider implements ModelProvider {
+    readonly name: string;
+    readonly model: string;
+    readonly pricing?: Pricing;
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly maxResponseBytes;
+    constructor(options: OpenAICompatibleOptions);
+    stream(request: ModelRequest): AsyncGenerator<ModelEvent>;
+}
+
+export { AnthropicProvider, type AnthropicProviderOptions, type ConnectMcpOptions, DEFAULT_ANTHROPIC_MODEL, type McpToolInfo, type McpTools, type McpTransportConfig, ModelEvent, ModelProvider, ModelRequest, type OpenAICompatibleOptions, OpenAICompatibleProvider, Pricing, Scope, ToolDefinition, ToolRisk, VERSION, connectMcpTools };