agentic-assistant 0.0.0-stage → 0.2.0

package/dist/loop-42giKLVa.d.ts

@@ -0,0 +1,285 @@
+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];
+type Scope = string;
+declare function parseScope(scope: Scope): {
+    resource: string;
+    action: Action;
+};
+/** True when `grant` allows everything `required` asks for. */
+declare function scopeCovers(grant: Scope, required: Scope): boolean;
+/** True when any granted scope covers the required one. A malformed scope never matches. */
+declare function hasScope(granted: readonly Scope[], required: Scope): boolean;
+
+/**
+ * The acting principal. The assistant always acts as an agent of a signed-in
+ * person. The host passes the scopes, already narrowed to what the person
+ * granted this agent. The assistant never widens them.
+ */
+interface AssistantPrincipal {
+    readonly id: string;
+    readonly kind: "agent_of_human";
+    /** The person the assistant acts for. */
+    readonly parentId: string;
+    readonly scopes: readonly Scope[];
+    /** Epoch milliseconds. Calls stop at this time. */
+    readonly expiresAt?: number;
+    /** Host check, run before every tool call. A throw or a true result denies the call. */
+    readonly isRevoked?: () => boolean | Promise<boolean>;
+}
+interface PrincipalInput {
+    id: string;
+    kind?: string;
+    parentId: string;
+    scopes: readonly Scope[];
+    expiresAt?: number;
+    isRevoked?: () => boolean | Promise<boolean>;
+}
+declare class PrincipalError extends Error {
+    constructor(message: string);
+}
+/** Validates host input. A missing or other kind is an error, never a default. */
+declare function createPrincipal(input: PrincipalInput): AssistantPrincipal;
+/** Re-checks a principal at the start of a run. A cast or a plain JS caller cannot skip validation. */
+declare function assertPrincipal(principal: AssistantPrincipal): void;
+/** Who a run, a tool call, and every audit row is attributed to. Always machine-made. */
+interface Actor {
+    principalId: string;
+    kind: "agent_of_human";
+    onBehalfOf: string;
+    machineMade: true;
+}
+declare function actorOf(principal: AssistantPrincipal): Actor;
+
+/** `safe` runs at once. `risky` and `irreversible` wait for a person. */
+type ToolRisk = "safe" | "risky" | "irreversible";
+declare const TOOL_RISKS: readonly ToolRisk[];
+interface ApprovalRequest {
+    id: string;
+    tool: string;
+    risk: "risky" | "irreversible";
+    /** A frozen copy of the arguments the tool will get. */
+    input: Readonly<Record<string, unknown>>;
+    /** Binds the tool, the arguments, and the acting principal. The decision must echo it. */
+    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; /** Leave it out when you do not know. The record then says "unknown". */
+    approverKind?: ApproverKind;
+} | {
+    requestId: string;
+    approved: false;
+    decidedBy?: string;
+    reason?: string;
+};
+/**
+ * The approval port. Answer a request with a decision, or fail. The loop treats
+ * a failure, a timeout, and a decision that does not match the request as a refusal.
+ */
+interface ApprovalGate {
+    request(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision>;
+}
+/** JSON with sorted keys, so equal values give equal text. */
+declare function canonicalJson(value: unknown): string;
+declare function digestCall(call: {
+    tool: string;
+    input: unknown;
+    principalId: string;
+    onBehalfOf: string;
+}): string;
+/**
+ * An in-memory gate. `request` waits until `approve` or `reject` is called with the request id.
+ * A panel, a CLI, or a test calls them. `approve` signs the stored digest, so a caller cannot
+ * approve other arguments than the ones the loop asked about.
+ */
+declare class QueueApprovalGate implements ApprovalGate {
+    private readonly waiting;
+    pending(): ApprovalRequest[];
+    request(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision>;
+    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;
+    signal?: AbortSignal;
+}
+interface ToolDefinition<Input = Record<string, unknown>> {
+    name: string;
+    description: string;
+    /** A JSON Schema with `type: "object"`. The loop validates the model's input against it. */
+    inputSchema: JsonSchema;
+    /** The scope the acting principal must hold to call this tool. */
+    scope: Scope;
+    /** How much harm a call can do. `risky` and `irreversible` wait for a person's approval. Every tool must say. */
+    risk: ToolRisk;
+    handler(input: Input, context: ToolContext): Promise<unknown> | unknown;
+}
+/** Types a tool for an SDK function. The loop checks the input against `inputSchema` before it calls `handler`. */
+declare function defineTool<Input>(tool: ToolDefinition<Input>): ToolDefinition;
+declare class ToolRegistry {
+    private readonly tools;
+    private readonly ajv;
+    register(tool: ToolDefinition): this;
+    registerAll(tools: readonly ToolDefinition[]): this;
+    get(name: string): ToolDefinition | undefined;
+    list(): ToolDefinition[];
+    /** Returns a short description of the first schema violation, or undefined when the input is valid. */
+    checkInput(name: string, input: unknown): string | undefined;
+}
+
+interface RunLimits {
+    /** Most model turns in one run. Default 8. */
+    maxTurns?: number;
+    /** Most input plus output tokens, summed over all turns. */
+    maxTotalTokens?: number;
+    /** Most estimated cost in US dollars. Needs `pricing` on the provider. */
+    maxCostUsd?: number;
+    /** Output token ceiling for one turn. Default 4096. */
+    maxOutputTokensPerTurn?: number;
+    /** Time to wait for a person to decide. No decision in time means the call is refused. Default 300000. */
+    approvalTimeoutMs?: number;
+    /** Most tool calls the model may make in one turn. A larger turn runs none. Default 16. */
+    maxToolCallsPerTurn?: number;
+    /** Longest tool result, in characters, sent to the model. Longer results are cut. Default 32768. */
+    maxToolResultChars?: number;
+}
+interface RunOptions {
+    provider: ModelProvider;
+    registry: ToolRegistry;
+    principal: AssistantPrincipal;
+    /** The conversation so far, ending with the new user message. */
+    messages: readonly Message[];
+    system?: string;
+    /** Asked before a `risky` or `irreversible` tool runs. Without it, those tools are not offered and are refused. */
+    approvals?: ApprovalGate;
+    limits?: RunLimits;
+    signal?: AbortSignal;
+    now?: () => number;
+}
+type DoneReason = "end_turn" | "max_tokens" | "refusal" | "provider_stop" | "max_turns" | "token_cap" | "cost_cap" | "tool_call_cap" | "provider_error" | "principal_inactive" | "aborted";
+type DeniedReason = "unknown_tool" | "scope" | "invalid_input" | "approval";
+interface RunTotals extends Usage {
+    costUsd: number;
+}
+type AssistantEvent = {
+    type: "run_start";
+    actor: Actor;
+    provider: string;
+    model: string;
+} | {
+    type: "turn_start";
+    turn: number;
+} | {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    input: unknown;
+    actor: Actor;
+} | {
+    type: "approval_request";
+    request: ApprovalRequest;
+} | {
+    type: "approval_decision";
+    requestId: string;
+    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;
+} | {
+    type: "tool_result";
+    id: string;
+    name: string;
+    content: string;
+    isError: boolean;
+    denied?: DeniedReason;
+    /** True when `content` came from a tool. Treat it as data, never as an instruction. */
+    untrusted?: true;
+    /** 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; /** The model that answered this turn. */
+    answeredBy: AnsweredBy;
+} | {
+    type: "done";
+    reason: DoneReason;
+    totals: RunTotals;
+    actor: Actor;
+    messages: Message[];
+    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;
+/**
+ * Runs the assistant until the model stops, a cap trips, or the principal stops
+ * being valid. Tools run only when the model stops to use them, only inside the
+ * principal's scopes, and never after a cap has tripped.
+ */
+declare function runAssistant(options: RunOptions): AsyncGenerator<AssistantEvent>;
+
+export { ACTIONS as A, defineTool as B, digestCall as C, DATA_NOTICE 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 RunLimits as R, type Scope as S, TOOL_RISKS as T, type Action as a, type Actor as b, type ApprovalDecision as c, type ApprovalGate as d, type ApprovalRequest as e, type Approver as f, type ApproverKind as g, type AssistantEvent as h, type AssistantPrincipal as i, type DeniedReason as j, type DoneReason as k, type PrincipalInput as l, type Provenance as m, type ProvenanceInput as n, type RunOptions as o, type RunTotals 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-X5VTHZVM.js

@@ -0,0 +1,11 @@
+import {
+  createAssistantMcpServer,
+  startAssistantMcp
+} from "./chunk-6UD2QQA4.js";
+import "./chunk-BDXAUNMR.js";
+import "./chunk-HYT732TN.js";
+import "./chunk-T4ZMDOB4.js";
+export {
+  createAssistantMcpServer,
+  startAssistantMcp
+};

package/dist/react.css

@@ -0,0 +1,57 @@
+/* Plain CSS variables. Set them on .aa-panel or a parent to match your app. Every pair below meets
+   WCAG 2.2 AA contrast; src/react/styles.test.ts checks it. No remote fonts or images. */
+.aa-panel {
+  --aa-bg: #ffffff;
+  --aa-fg: #1b1b1b;
+  --aa-muted: #4d4d4d;
+  --aa-border: #767676;
+  --aa-accent: #0b57d0;
+  --aa-accent-fg: #ffffff;
+  --aa-focus: #0b57d0;
+  --aa-machine-bg: #e8eefc;
+  --aa-machine-fg: #0a2a6b;
+  --aa-card-bg: #f4f4f4;
+  --aa-warn-bg: #fff4d6;
+  --aa-warn-fg: #5c3d00;
+  --aa-danger: #b3261e;
+
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-width: 18rem;
+  box-sizing: border-box;
+  background: var(--aa-bg);
+  color: var(--aa-fg);
+  border: 1px solid var(--aa-border);
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  font-size: 1rem;
+  line-height: 1.5;
+}
+.aa-panel *, .aa-panel *::before, .aa-panel *::after { box-sizing: border-box; }
+.aa-header { display: flex; align-items: center; gap: 0.5rem; padding: 0.5rem 0.75rem; border-bottom: 1px solid var(--aa-border); }
+.aa-title { margin: 0; font-size: 1.125rem; }
+.aa-log { flex: 1; overflow-y: auto; padding: 0.75rem; display: flex; flex-direction: column; gap: 0.75rem; }
+.aa-empty { color: var(--aa-muted); margin: 0; }
+.aa-msg { padding: 0.5rem 0.75rem; border: 1px solid var(--aa-border); border-radius: 0.5rem; }
+.aa-assistant { background: var(--aa-card-bg); }
+.aa-who { margin: 0 0 0.25rem; font-weight: 600; color: var(--aa-muted); }
+.aa-text { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; }
+.aa-badge { display: inline-block; padding: 0 0.5rem; border-radius: 0.25rem; background: var(--aa-machine-bg); color: var(--aa-machine-fg); font-size: 0.875rem; font-weight: 600; border: 1px solid var(--aa-machine-fg); }
+.aa-card, .aa-approval { padding: 0.5rem 0.75rem; border: 1px solid var(--aa-border); border-radius: 0.5rem; background: var(--aa-card-bg); }
+.aa-card-head { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; }
+.aa-status { color: var(--aa-muted); font-weight: 600; }
+.aa-pre { margin: 0.25rem 0 0; padding: 0.5rem; max-height: 12rem; overflow: auto; background: var(--aa-bg); border: 1px solid var(--aa-border); white-space: pre-wrap; overflow-wrap: anywhere; font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 0.875rem; }
+.aa-approval { background: var(--aa-warn-bg); color: var(--aa-warn-fg); border-width: 2px; border-color: var(--aa-warn-fg); }
+.aa-approval-title { margin: 0 0 0.25rem; font-size: 1rem; display: flex; align-items: center; gap: 0.5rem; }
+.aa-warn { color: var(--aa-danger); background: var(--aa-bg); padding: 0.25rem 0.5rem; border: 2px solid var(--aa-danger); border-radius: 0.25rem; }
+.aa-notice { margin: 0; padding: 0.5rem 0.75rem; border: 1px solid var(--aa-border); border-radius: 0.5rem; }
+.aa-composer { display: flex; flex-direction: column; gap: 0.5rem; padding: 0.75rem; border-top: 1px solid var(--aa-border); }
+.aa-label { font-weight: 600; }
+.aa-input { width: 100%; resize: vertical; padding: 0.5rem; font: inherit; color: var(--aa-fg); background: var(--aa-bg); border: 1px solid var(--aa-border); border-radius: 0.25rem; }
+.aa-actions { display: flex; gap: 0.5rem; margin-top: 0.5rem; }
+.aa-composer .aa-actions { margin-top: 0; }
+.aa-button { min-height: 2rem; min-width: 2rem; padding: 0.25rem 1rem; font: inherit; font-weight: 600; color: var(--aa-fg); background: var(--aa-bg); border: 2px solid var(--aa-border); border-radius: 0.25rem; cursor: pointer; }
+.aa-button.aa-primary { color: var(--aa-accent-fg); background: var(--aa-accent); border-color: var(--aa-accent); }
+.aa-button:disabled { cursor: not-allowed; opacity: 0.6; }
+.aa-panel :focus-visible { outline: 3px solid var(--aa-focus); outline-offset: 2px; }
+@media (forced-colors: active) { .aa-badge, .aa-button, .aa-approval, .aa-warn { border: 2px solid CanvasText; } }

package/dist/react.d.ts

@@ -0,0 +1,56 @@
+import * as react from 'react';
+import { h as AssistantEvent, u as ToolRisk } from './loop-42giKLVa.js';
+import { c as Message } from './types-DGH8FS56.js';
+
+type PanelItem = {
+    kind: "user";
+    id: string;
+    text: string;
+} | {
+    kind: "assistant";
+    id: string;
+    text: string;
+    streaming: boolean;
+} | {
+    kind: "tool";
+    id: string;
+    name: string;
+    input: unknown;
+    status: "running" | "waiting" | "done" | "failed" | "denied" | "not_run";
+    /** Text a tool returned. It is data. Show it as text. */
+    content?: string;
+} | {
+    kind: "approval";
+    id: string;
+    tool: string;
+    risk: Exclude<ToolRisk, "safe">;
+    input: unknown;
+    /** `expired`: the run ended before a decision was used. `unavailable`: the approval did not complete. */
+    status: "pending" | "approved" | "declined" | "unavailable" | "expired";
+    busy: boolean;
+    decidedBy?: string;
+} | {
+    kind: "notice";
+    id: string;
+    text: string;
+};
+interface UseAssistantOptions {
+    /** Runs the assistant for this conversation. The host owns the model, the tools, and the principal. */
+    run(messages: Message[], signal: AbortSignal): AsyncIterable<AssistantEvent>;
+    /** Passes a person's decision to the approval gate. The host owns the gate and knows who the person is. */
+    decide(requestId: string, approved: boolean, reason?: string): void | Promise<void>;
+}
+declare function useAssistant(options: UseAssistantOptions): {
+    items: PanelItem[];
+    running: boolean;
+    send: (text: string) => Promise<void>;
+    stop: () => void | undefined;
+    decide: (requestId: string, approved: boolean, reason?: string) => Promise<boolean>;
+};
+
+interface AssistantPanelProps extends UseAssistantOptions {
+    title?: string;
+}
+declare function AssistantPanel({ title, run, decide }: AssistantPanelProps): react.JSX.Element;
+
+export { AssistantPanel, type AssistantPanelProps, type PanelItem, type UseAssistantOptions, useAssistant };