@aparte/core 0.2.0-alpha.0

package/dist/types/tools.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Aparte Tool Types
+ * Provider-agnostic tool calling interface
+ */
+import type { AparteToolCallSegment } from './segments.js';
+/** Definition of a tool the AI can call */
+export interface AparteTool {
+    name: string;
+    description: string;
+    /** JSON Schema object describing the tool's input parameters */
+    inputSchema: Record<string, unknown>;
+    /** System prompt injected automatically when this tool is registered — tells the AI when and why to use it */
+    systemPrompt?: string;
+    /**
+     * Maximum number of agentic loop turns before aborting.
+     * Overrides the global `maxTurns` in AparteClientOptions for this specific tool.
+     */
+    maxTurns?: number;
+    /**
+     * When true, the agent loop pauses before running this tool's handler and
+     * waits for a human decision (approve / reject) — "human in the loop". The
+     * UI surfaces Approve/Reject (default renderer, or a custom tool renderer)
+     * and resolves it by dispatching an `aparte-tool-decision` event. On reject,
+     * a synthetic "rejected by user" result is injected and the turn stops.
+     */
+    needsApproval?: boolean;
+}
+/**
+ * Detail for `aparte-tool-decision` — the human's verdict on a tool awaiting
+ * approval. Dispatched by the approval UI (built-in or app-provided) and
+ * consumed by the agent loop to resume or reject.
+ */
+export interface AparteToolDecisionDetail {
+    toolCallId: string;
+    approved: boolean;
+    /**
+     * Optional payload from a custom approval surface. When it is a plain object
+     * and the decision is `approved`, the agent loop merges it onto the tool's
+     * input before invoking the handler — so a human can edit the arguments
+     * before the tool runs (correct a path, tighten a query, …). The built-in
+     * Approve/Reject gate sends no payload, so existing flows are unchanged.
+     */
+    payload?: unknown;
+}
+/**
+ * Detail for `aparte-tool-approval-request` — emitted by the loop when a tool
+ * marked `needsApproval` is about to run. Apps may listen to show a richer
+ * approval surface; the built-in renderer already shows Approve/Reject inline.
+ */
+export interface AparteToolApprovalRequestDetail {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Detail for `aparte-tool-action` — a generic callback channel so any rendered
+ * tool UI (via {@link AparteToolRenderer.setup}) can post an interactive action
+ * back toward the host/loop (e.g. a custom confirm/choose/retry button).
+ */
+export interface AparteToolActionDetail {
+    toolCallId: string;
+    action: string;
+    payload?: unknown;
+}
+/** A tool call emitted by the AI during streaming */
+export interface AparteToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/** Result returned after a tool handler resolves */
+export interface AparteToolResult {
+    toolCallId: string;
+    content: string;
+}
+/**
+ * Handler function for a registered tool.
+ * Receives the tool call and an AbortSignal (fires after timeout or on cancellation).
+ * Must resolve with a AparteToolResult.
+ */
+export type AparteToolHandler = (call: AparteToolCall, signal: AbortSignal) => Promise<AparteToolResult>;
+/**
+ * Per-tool segment renderer.
+ * Registered via AparteConfig.registerToolRenderer(toolName, renderer).
+ * When the AI calls a tool, this renderer controls what appears in the bubble
+ * for that specific tool instead of the generic tool_call renderer.
+ *
+ * Return an empty string from render() to render nothing (e.g. for UI-only tools like ask_question).
+ */
+export interface AparteToolRenderer {
+    /** HTML to render for the tool call segment. Return empty string to hide. */
+    render: (segment: AparteToolCallSegment) => string;
+    /** Optional DOM setup (event listeners etc.) called after HTML is injected */
+    setup?: (element: HTMLElement, segment: AparteToolCallSegment) => void;
+    /** Optional CSS to inject once into document.head */
+    getStyles?: () => string;
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/types/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8GAA8G;IAC9G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,+BAA+B;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC5B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,WAAW,KAClB,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAC/B,6EAA6E;IAC7E,MAAM,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,MAAM,CAAC;IACnD,8EAA8E;IAC9E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACvE,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B"}

package/dist/utils/assert-never.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Exhaustiveness guard for discriminated-union `switch`es. The argument narrows to
+ * `never` only when every variant has a matching `case`, so adding a new union
+ * member without handling it becomes a TYPECHECK error here instead of being
+ * silently ignored at runtime. The throw is the runtime backstop (should be
+ * unreachable in well-typed code).
+ */
+export declare function assertNever(value: never): never;
+//# sourceMappingURL=assert-never.d.ts.map

package/dist/utils/assert-never.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-never.d.ts","sourceRoot":"","sources":["../../src/utils/assert-never.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C"}

package/dist/utils/css-escape.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Escape a value for safe interpolation into a DOUBLE-QUOTED CSS attribute
+ * selector: `[attr="${cssEscape(value)}"]`. Inside a quoted CSS string only `"`
+ * (which would end the string) and `\` (the escape char) are special, so escaping
+ * those two is sufficient AND correct here — unlike `CSS.escape`, which targets the
+ * UNquoted identifier context and over-escapes inside quotes (breaking the match),
+ * and which also needs the `CSS` global (absent in SSR / some test runtimes).
+ *
+ * Segment/message ids are random UUIDs in the default flow, so this is
+ * defense-in-depth: a hostile, stream-supplied id containing `"` (e.g. a tool-call
+ * id) can no longer break out of the selector into a `SyntaxError` or a
+ * selector-list that mis-targets another element.
+ */
+export declare function cssEscape(value: string): string;
+//# sourceMappingURL=css-escape.d.ts.map

package/dist/utils/css-escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-escape.d.ts","sourceRoot":"","sources":["../../src/utils/css-escape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@aparte/core",
+  "version": "0.2.0-alpha.0",
+  "description": "High-performance AI conversation engine - Zero-dependency Web Components",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "customElements": "dist/custom-elements.json",
+  "exports": {
+    ".": {
+      "@aparte-workspace/source": "./src/index.ts",
+      "node": {
+        "types": "./dist/index.node.d.ts",
+        "default": "./dist/index.node.js"
+      },
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": {
+      "@aparte-workspace/source": "./src/styles/bundle.css",
+      "default": "./dist/index.css"
+    },
+    "./dist/index.css": "./dist/index.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "^0.11.0",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.2",
+    "typescript": "^5.4.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "keywords": [
+    "web-components",
+    "chat",
+    "ai",
+    "streaming",
+    "llm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apartejs/aparte.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/apartejs/aparte/issues"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc -b --emitDeclarationOnly --force && node scripts/clean-declarations.mjs && pnpm run analyze",
+    "analyze": "cem analyze",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}