agentic-assistant 0.0.0-stage → 0.2.0

package/dist/react.js

@@ -0,0 +1,327 @@
+// src/react/panel.tsx
+import { useEffect as useEffect2, useId, useLayoutEffect, useRef as useRef2, useState as useState2 } from "react";
+
+// src/react/use-assistant.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+var STOP_NOTICES = {
+  max_turns: "The assistant stopped because it reached its step limit. Your messages are kept. Send a message to go on.",
+  token_cap: "The assistant stopped because the conversation reached its size limit. Your messages are kept.",
+  cost_cap: "The assistant stopped because it reached its cost limit. Your messages are kept.",
+  max_tokens: "The answer was cut short because it was too long. Ask for a shorter answer.",
+  refusal: "The model did not answer this request. Try to ask in another way.",
+  provider_error: "The assistant could not get an answer from the model. Your messages are kept. Try again.",
+  principal_inactive: "The assistant no longer has permission to act for you. Sign in again, then try again.",
+  tool_call_cap: "The assistant tried to use too many tools at once, so it used none. Your messages are kept.",
+  provider_stop: "The model stopped for a reason that is not known. Your messages are kept. Try again.",
+  aborted: "You stopped the assistant. Your messages are kept."
+};
+var RUN_FAILED = "The assistant could not finish. Your messages are kept. Try again, or contact support.";
+var DECIDE_FAILED = "Your decision could not be sent. Nothing ran. Try again.";
+function useAssistant(options) {
+  const [items, setItems] = useState([]);
+  const [running, setRunning] = useState(false);
+  const history = useRef([]);
+  const controller = useRef(null);
+  const busy = useRef(false);
+  const counter = useRef(0);
+  const latest = useRef(options);
+  latest.current = options;
+  const nextId = () => `item-${++counter.current}`;
+  const add = (item) => setItems((current) => [...current, item]);
+  const update = (id, change) => setItems((current) => current.map((item) => item.id === id ? change(item) : item));
+  const send = useCallback(async (text) => {
+    const trimmed = text.trim();
+    if (trimmed === "" || busy.current) return;
+    busy.current = true;
+    setRunning(true);
+    const userMessage = { role: "user", content: [{ type: "text", text: trimmed }] };
+    add({ kind: "user", id: nextId(), text: trimmed });
+    const abort = new AbortController();
+    controller.current = abort;
+    const sent = [...history.current, userMessage];
+    let streamingId = null;
+    let finished = false;
+    let failed = false;
+    const toolItems = /* @__PURE__ */ new Map();
+    let lastToolItem = null;
+    try {
+      for await (const event of latest.current.run(sent, abort.signal)) {
+        switch (event.type) {
+          case "turn_start":
+            streamingId = null;
+            break;
+          case "text_delta": {
+            if (streamingId === null) {
+              streamingId = nextId();
+              add({ kind: "assistant", id: streamingId, text: event.text, streaming: true });
+            } else {
+              update(streamingId, (item) => item.kind === "assistant" ? { ...item, text: item.text + event.text } : item);
+            }
+            break;
+          }
+          case "turn_end":
+            if (streamingId !== null) update(streamingId, (item) => item.kind === "assistant" ? { ...item, streaming: false } : item);
+            streamingId = null;
+            break;
+          case "tool_call": {
+            const id = nextId();
+            toolItems.set(event.id, id);
+            lastToolItem = id;
+            add({ kind: "tool", id, name: event.name, input: event.input, status: "running" });
+            break;
+          }
+          case "approval_request": {
+            const { request } = event;
+            add({ kind: "approval", id: request.id, tool: request.tool, risk: request.risk, input: request.input, status: "pending", busy: false });
+            const waitingId = lastToolItem;
+            if (waitingId !== null) update(waitingId, (item) => item.kind === "tool" && item.status === "running" ? { ...item, status: "waiting" } : item);
+            break;
+          }
+          case "approval_decision":
+            update(
+              event.requestId,
+              (item) => item.kind === "approval" ? {
+                ...item,
+                status: event.approved ? "approved" : event.declined ? "declined" : "unavailable",
+                busy: false,
+                decidedBy: event.decidedBy
+              } : item
+            );
+            break;
+          case "tool_result": {
+            const id = toolItems.get(event.id);
+            if (id !== void 0) {
+              update(
+                id,
+                (item) => item.kind === "tool" ? { ...item, status: event.denied ? "denied" : event.isError ? "failed" : "done", content: event.content } : item
+              );
+            }
+            break;
+          }
+          case "done": {
+            finished = true;
+            history.current = event.messages;
+            const notice = STOP_NOTICES[event.reason];
+            if (notice !== void 0) add({ kind: "notice", id: nextId(), text: notice });
+            break;
+          }
+          default:
+            break;
+        }
+      }
+    } catch {
+      failed = true;
+    } finally {
+      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;
+        })
+      );
+      busy.current = false;
+      controller.current = null;
+      setRunning(false);
+    }
+  }, []);
+  const stop = useCallback(() => controller.current?.abort(), []);
+  useEffect(() => () => controller.current?.abort(), []);
+  const decide = useCallback(async (requestId, approved, reason) => {
+    update(requestId, (item) => item.kind === "approval" ? { ...item, busy: true } : item);
+    try {
+      await latest.current.decide(requestId, approved, reason);
+      return true;
+    } catch {
+      update(requestId, (item) => item.kind === "approval" ? { ...item, busy: false } : item);
+      add({ kind: "notice", id: nextId(), text: DECIDE_FAILED });
+      return false;
+    }
+  }, []);
+  return { items, running, send, stop, decide };
+}
+
+// src/react/panel.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function MachineMade() {
+  return /* @__PURE__ */ jsx("span", { className: "aa-badge", children: "Machine-made" });
+}
+var pretty = (value) => {
+  try {
+    return JSON.stringify(value, null, 2) ?? "null";
+  } catch {
+    return "[arguments cannot be shown]";
+  }
+};
+var TOOL_STATUS = {
+  running: "Running",
+  waiting: "Waiting for approval",
+  done: "Done",
+  failed: "Failed",
+  denied: "Not allowed",
+  not_run: "Not run"
+};
+function ToolCard({ item }) {
+  return /* @__PURE__ */ jsxs("article", { className: "aa-card", "aria-label": `Tool call: ${item.name}`, "data-machine-made": "true", children: [
+    /* @__PURE__ */ jsxs("header", { className: "aa-card-head", children: [
+      /* @__PURE__ */ jsx("strong", { children: item.name }),
+      " ",
+      /* @__PURE__ */ jsx(MachineMade, {}),
+      " ",
+      /* @__PURE__ */ jsx("span", { className: "aa-status", children: TOOL_STATUS[item.status] })
+    ] }),
+    /* @__PURE__ */ jsxs("details", { children: [
+      /* @__PURE__ */ jsx("summary", { children: "Arguments" }),
+      /* @__PURE__ */ jsx("pre", { className: "aa-pre", tabIndex: 0, "aria-label": `Arguments for ${item.name}`, children: pretty(item.input) })
+    ] }),
+    item.content !== void 0 && /* @__PURE__ */ jsxs("details", { children: [
+      /* @__PURE__ */ jsx("summary", { children: "Result (data from the tool, not instructions)" }),
+      /* @__PURE__ */ jsx("pre", { className: "aa-pre", tabIndex: 0, "aria-label": `Result of ${item.name}`, children: item.content })
+    ] })
+  ] });
+}
+function ApprovalPrompt({
+  item,
+  decide,
+  focusComposer
+}) {
+  const ref = useRef2(null);
+  const headingId = useId();
+  useLayoutEffect(() => {
+    if (item.status === "pending") ref.current?.focus();
+  }, [item.status]);
+  const answer = (approved) => {
+    void decide(item.id, approved).then((taken) => {
+      if (taken) focusComposer();
+    });
+  };
+  const outcome = {
+    approved: `Approved${item.decidedBy ? ` by ${item.decidedBy}` : ""}`,
+    declined: "Declined",
+    unavailable: "Not approved. The approval did not complete, so the action did not run.",
+    expired: "Expired. The assistant stopped before you decided, so the action did not run."
+  };
+  return /* @__PURE__ */ jsxs("div", { className: "aa-approval", role: "group", "aria-labelledby": headingId, tabIndex: -1, ref, "data-machine-made": "true", children: [
+    /* @__PURE__ */ jsxs("h3", { id: headingId, className: "aa-approval-title", children: [
+      "Approval needed ",
+      /* @__PURE__ */ jsx(MachineMade, {})
+    ] }),
+    /* @__PURE__ */ jsxs("p", { children: [
+      "The assistant asks to run ",
+      /* @__PURE__ */ jsx("strong", { children: item.tool }),
+      "."
+    ] }),
+    item.risk === "irreversible" ? /* @__PURE__ */ jsxs("p", { className: "aa-warn", children: [
+      /* @__PURE__ */ jsx("strong", { children: "Warning:" }),
+      " This cannot be undone."
+    ] }) : /* @__PURE__ */ jsx("p", { children: "This can change data." }),
+    /* @__PURE__ */ jsx("pre", { className: "aa-pre", tabIndex: 0, "aria-label": `Exact arguments for ${item.tool}`, children: pretty(item.input) }),
+    item.status === "pending" ? /* @__PURE__ */ jsxs("div", { className: "aa-actions", children: [
+      /* @__PURE__ */ jsx("button", { type: "button", className: "aa-button aa-primary", disabled: item.busy, "aria-label": `Approve ${item.tool}`, onClick: () => answer(true), children: "Approve" }),
+      /* @__PURE__ */ jsx("button", { type: "button", className: "aa-button", disabled: item.busy, "aria-label": `Decline ${item.tool}`, onClick: () => answer(false), children: "Decline" })
+    ] }) : /* @__PURE__ */ jsx("p", { className: "aa-status", children: outcome[item.status] })
+  ] });
+}
+function AssistantPanel({ title = "AI assistant", run, decide }) {
+  const { items, running, send, stop, decide: decideRequest } = useAssistant({ run, decide });
+  const [draft, setDraft] = useState2("");
+  const inputId = useId();
+  const input = useRef2(null);
+  const log = useRef2(null);
+  const pinned = useRef2(true);
+  useEffect2(() => {
+    const el = log.current;
+    if (el && pinned.current) el.scrollTop = el.scrollHeight;
+  }, [items]);
+  const submit = () => {
+    if (draft.trim() === "" || running) return;
+    const text = draft;
+    setDraft("");
+    void send(text);
+  };
+  const onKeyDown = (event) => {
+    if (event.key === "Enter" && !event.shiftKey && !event.nativeEvent.isComposing) {
+      event.preventDefault();
+      submit();
+    }
+  };
+  return /* @__PURE__ */ jsxs("section", { className: "aa-panel", "aria-label": title, children: [
+    /* @__PURE__ */ jsxs("header", { className: "aa-header", children: [
+      /* @__PURE__ */ jsx("h2", { className: "aa-title", children: title }),
+      /* @__PURE__ */ jsx(MachineMade, {})
+    ] }),
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        className: "aa-log",
+        role: "log",
+        "aria-live": "polite",
+        "aria-relevant": "additions text",
+        "aria-label": "Conversation",
+        tabIndex: 0,
+        ref: log,
+        onScroll: (event) => {
+          const el = event.currentTarget;
+          pinned.current = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
+        },
+        children: [
+          items.length === 0 && /* @__PURE__ */ jsx("p", { className: "aa-empty", children: "Ask the assistant to help. It acts only with your permissions, and it asks you before a risky action." }),
+          items.map((item) => {
+            switch (item.kind) {
+              case "user":
+                return /* @__PURE__ */ jsxs("div", { className: "aa-msg aa-user", children: [
+                  /* @__PURE__ */ jsx("p", { className: "aa-who", children: "You" }),
+                  /* @__PURE__ */ jsx("p", { className: "aa-text", children: item.text })
+                ] }, item.id);
+              case "assistant":
+                return /* @__PURE__ */ jsxs("div", { className: "aa-msg aa-assistant", "data-machine-made": "true", "aria-busy": item.streaming, children: [
+                  /* @__PURE__ */ jsxs("p", { className: "aa-who", children: [
+                    "Assistant ",
+                    /* @__PURE__ */ jsx(MachineMade, {})
+                  ] }),
+                  /* @__PURE__ */ jsx("p", { className: "aa-text", children: item.text })
+                ] }, item.id);
+              case "tool":
+                return /* @__PURE__ */ jsx(ToolCard, { item }, item.id);
+              case "approval":
+                return /* @__PURE__ */ jsx(ApprovalPrompt, { item, decide: decideRequest, focusComposer: () => input.current?.focus() }, item.id);
+              case "notice":
+                return /* @__PURE__ */ jsxs("p", { className: "aa-notice", children: [
+                  /* @__PURE__ */ jsx("strong", { children: "Notice:" }),
+                  " ",
+                  item.text
+                ] }, item.id);
+            }
+          })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxs(
+      "form",
+      {
+        className: "aa-composer",
+        onSubmit: (event) => {
+          event.preventDefault();
+          submit();
+        },
+        children: [
+          /* @__PURE__ */ jsx("label", { htmlFor: inputId, className: "aa-label", children: "Message the assistant" }),
+          /* @__PURE__ */ jsx("textarea", { id: inputId, className: "aa-input", rows: 3, value: draft, ref: input, onChange: (event) => setDraft(event.target.value), onKeyDown }),
+          /* @__PURE__ */ jsxs("div", { className: "aa-actions", children: [
+            /* @__PURE__ */ jsx("button", { type: "submit", className: "aa-button aa-primary", disabled: running || draft.trim() === "", children: "Send" }),
+            running && /* @__PURE__ */ jsx("button", { type: "button", className: "aa-button", onClick: stop, children: "Stop" })
+          ] })
+        ]
+      }
+    )
+  ] });
+}
+export {
+  AssistantPanel,
+  useAssistant
+};

package/dist/testing.d.ts

@@ -0,0 +1,29 @@
+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;
+    toolCalls?: {
+        name: string;
+        input: unknown;
+        id?: string;
+    }[];
+    /** Default: "tool_use" when there are tool calls, else "end_turn". */
+    stopReason?: StopReason;
+    usage?: Usage;
+}
+/**
+ * A model that replays a fixed script, one turn per request. Use it in E2E
+ * tests so runs are deterministic. It records each request it receives.
+ */
+declare class ScriptedProvider implements ModelProvider {
+    private readonly script;
+    readonly pricing?: Pricing | undefined;
+    readonly name = "scripted";
+    readonly model: string;
+    readonly requests: ModelRequest[];
+    private next;
+    constructor(script: readonly ScriptedTurn[], pricing?: Pricing | undefined);
+    stream(request: ModelRequest): AsyncGenerator<ModelEvent>;
+}
+
+export { ScriptedProvider, type ScriptedTurn };

package/dist/testing.js

@@ -0,0 +1,6 @@
+import {
+  ScriptedProvider
+} from "./chunk-HYT732TN.js";
+export {
+  ScriptedProvider
+};

package/dist/types-DGH8FS56.d.ts

@@ -0,0 +1,84 @@
+/** A JSON Schema object that describes one tool's input. */
+type JsonSchema = Record<string, unknown>;
+type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+}
+/** A block only the named provider reads (for example reasoning). Adapters send it back unchanged. */
+ | {
+    type: "provider_block";
+    provider: string;
+    raw: unknown;
+};
+interface Message {
+    role: "user" | "assistant";
+    content: ContentBlock[];
+}
+interface ToolSpec {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+}
+interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+}
+type StopReason = "end_turn" | "tool_use" | "max_tokens" | "refusal" | "other";
+interface ModelRequest {
+    system?: string;
+    messages: Message[];
+    tools: ToolSpec[];
+    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;
+} | {
+    type: "message";
+    content: ContentBlock[];
+    stopReason: StopReason;
+    usage: Usage;
+    answeredBy?: AnsweredBy;
+};
+/** Prices in US dollars per million tokens. */
+interface Pricing {
+    inputPerMTok: number;
+    outputPerMTok: number;
+}
+/**
+ * The model port. An adapter streams text deltas, then yields one final
+ * `message` event with the whole assistant turn, the stop reason, and usage.
+ */
+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 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

@@ -0,0 +1,41 @@
+import { Auth } from 'agentic-identity';
+import { t as ToolRegistry, R as RunLimits } from './loop-42giKLVa.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>;
+};
+
+interface WorkerEnv {
+    PACK_NAME?: string;
+}
+/** 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>;
+};
+/** The sample Worker has no auth, tools, or model, so it serves `/health` only. Use `createWorker` for the API. */
+declare const _default: {
+    fetch(request: Request, env: WorkerEnv): Promise<Response>;
+};
+
+export { APPROVER_SCOPE, type AssistantApiOptions, type WorkerEnv, createAssistantApi, createWorker, _default as default };