@uptimizr/agent-core 0.1.0

package/AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS.md — @uptimizr/agent-core
+
+> Packaged agent guide. For the human reference see [README.md](./README.md); for design
+> rationale see the project ADRs at https://github.com/RaananW/Uptimizr/tree/main/docs/adr.
+
+## What this package is
+
+The **framework-agnostic, browser-safe core** shared by every Uptimizr analytics agent. It defines
+the agent tool surface **once** (ADR 0050 §1) so `@uptimizr/mcp`, the dashboard assistant, and the
+demo assistant never drift apart. It owns:
+
+- the **read-only tool catalog** (`readTools`) — one entry per documented collector query endpoint;
+- a headless **LLM provider-adapter interface** (`LlmProvider`) — messages + tool schemas in, tool
+  calls or final text out;
+- the headless **tool-calling loop** (`runAgent`) — LLM ↔ tools ↔ collector.
+
+The core ships **no model and no key**. It only ever reads a consumer's **own** collector via the
+`CollectorClient` (`GET`-only, `x-api-key`).
+
+## Rules for agents
+
+- **Read-only and privacy-preserving.** Never add ingestion, mutation, or raw per-session event
+  tools. The surface is aggregate-only; no data leaves the consumer's infrastructure (ADR 0003 /
+  ADR 0017). A new tool = a new entry in `readTools` mapping to a documented query endpoint — no
+  aggregation/business logic (that lives in the collector, ADR 0005).
+- **Browser-safe.** No Node dependencies, no `types: ["node"]`; only `zod` at runtime. Anything that
+  needs `process.env`, stdio, or the filesystem belongs in a consumer package (e.g. `@uptimizr/mcp`),
+  not here.
+- Tool definitions are pure (`buildRequest`) and must stay unit-testable without a live collector.
+- Keep provider adapters thin and out of this package: implement `LlmProvider` in the consumer.
+
+## Programmatic API
+
+`readTools`, `createCollectorClient(config)`, `toToolSchemas(tools?)`, `runAgent(options)`, plus the
+`LlmProvider` / `AgentMessage` / `AgentToolCall` / `ProviderResponse` types.
+
+## More
+
+- Package reference: [README.md](./README.md)
+- Integration guide: https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Uptimizr Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,125 @@
+# @uptimizr/agent-core
+
+The **framework-agnostic, browser-safe core** for Uptimizr analytics agents. It defines the agent
+tool surface **once** so every consumer — the [`@uptimizr/mcp`](../mcp/README.md) server, the
+dashboard assistant, and the backend-less demo assistant — asks the same questions of the same
+read-only collector query API (ADR 0050 §1).
+
+It owns three things:
+
+1. **The read-only tool catalog** (`readTools`) — one entry per documented aggregate query
+   endpoint. Pure Zod shapes, no Node dependencies, unit-testable without a live collector.
+2. **A headless LLM provider-adapter interface** (`LlmProvider`) — send messages + tool schemas,
+   receive tool calls or a final answer. The core ships **no model and no key**; adapters
+   (WebLLM/WebGPU, an OpenAI-compatible or Anthropic endpoint) are user-selected and
+   user-controlled (ADR 0050 §4).
+3. **The headless tool-calling loop** (`runAgent`) — drives the LLM ↔ tools ↔ collector round trip,
+   framework-agnostic and runnable in a browser, a Node service, a CLI, or a bot.
+
+Everything here is **strictly read-only**: the loop only ever issues collector `GET`s through the
+catalog. There are **no** ingestion, mutation, or raw per-session event tools (ADR 0003 / ADR 0017).
+
+## Install
+
+```bash
+npm install @uptimizr/agent-core
+```
+
+## Use
+
+```ts
+import { createCollectorClient, runAgent, type LlmProvider } from "@uptimizr/agent-core";
+
+// 1. A read-only client bound to your own collector + project key.
+const client = createCollectorClient({
+  collectorUrl: "https://collect.example.com",
+  apiKey: "utk_…",
+});
+
+// 2. Your chosen LLM backend, adapted to the provider interface.
+const provider: LlmProvider = {
+  async complete({ messages, tools }) {
+    // Call WebLLM / an OpenAI-compatible or Anthropic endpoint here, passing
+    // `tools` as the tool/function schemas, and normalise the reply into either
+    //   { kind: "tool_calls", toolCalls: [...] }  or  { kind: "final", content }.
+    return { kind: "final", content: "…" };
+  },
+};
+
+// 3. Run the loop. It executes any tool calls against the collector for you.
+const result = await runAgent({
+  provider,
+  client,
+  messages: [
+    { role: "system", content: "You are a 3D analytics assistant." },
+    { role: "user", content: "What were the most-clicked meshes this week?" },
+  ],
+});
+
+console.log(result.content); // the model's final answer
+```
+
+## Tool catalog (read-only)
+
+`list_sessions`, `pointer_heatmap`, `world_heatmap`, `camera_heatmap`, `click_rays`, `flow_links`,
+`top_meshes`, `perf_summary`, `list_scenes`, `timeseries`, `event_counts`, `session_meta`,
+`scene_representation`, `funnel`, `aggregate_paths`, `rendering_technology`, `xr_rotation`,
+`xr_sources`, `xr_abandonment`, `xr_locomotion`. Most accept `since`/`until` (epoch ms) plus
+endpoint-specific filters (`scene`, `session`, `source`, `bins`, `cellSize`, `limit`, `cameraMode`,
+`rapidTurn`, `steps`). Each maps one-to-one to a documented
+collector query endpoint (see the [integration guide](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md)).
+
+## API
+
+| Export                         | Purpose                                                           |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `readTools`                    | The read-only tool catalog (one entry per query endpoint).        |
+| `createCollectorClient(cfg)`   | Thin `GET`-only collector client (`fetch`-based, injectable).     |
+| `toToolSchemas(tools?)`        | Convert catalog tools to JSON-Schema tool descriptors for an LLM. |
+| `runAgent(options)`            | The headless tool-calling loop.                                   |
+| `LlmProvider` / `AgentMessage` | The provider-adapter interface and message types.                 |
+
+The loop stops when the provider returns a final answer or after `maxSteps` turns
+(`DEFAULT_MAX_STEPS`, default 8). Unknown tools and invalid arguments are surfaced back to the model
+as tool-error messages so it can recover, never thrown.
+
+## Provider adapters (user-controlled backends)
+
+The core ships **no model and no key**. Two ready-made adapters implement `LlmProvider` and are
+exported from **code-split subpaths**, so consumers who never use the assistant pay nothing for
+them:
+
+```ts
+import { createWebLlmProvider } from "@uptimizr/agent-core/providers/webllm";
+import { createHostedProvider } from "@uptimizr/agent-core/providers/hosted";
+// or the barrel (adds backend-selection + localStorage helpers):
+import {
+  defaultBackendKind,
+  isWebGpuAvailable,
+  loadBackendConfig,
+  saveBackendConfig,
+} from "@uptimizr/agent-core/providers";
+```
+
+- **`createWebLlmProvider`** — local, in-browser inference on WebGPU via
+  [`@mlc-ai/web-llm`](https://github.com/mlc-ai/web-llm). The runtime is an **optional** dependency
+  loaded with a lazy `import()` only on first use; model weights download behind an explicit consent
+  gate and are cached in the browser's Cache Storage (never precached). **Zero data egress.**
+- **`createHostedProvider`** — bring-your-own **OpenAI-compatible** or **Anthropic** endpoint + key,
+  stored only in the browser; the browser calls your provider directly. Only the prompt and
+  aggregated results leave, to **your own** provider (ADR 0050 §4/§5).
+
+Install the WebLLM runtime alongside the assistant if you use the local backend:
+
+```bash
+npm install @mlc-ai/web-llm
+```
+
+See the [assistant guide](https://uptimizr.com/docs/guides/assistant/) for the curated model list,
+privacy trade-offs, and the provider CORS requirements.
+
+## More
+
+- Design rationale: [ADR 0050](https://github.com/RaananW/Uptimizr/blob/main/docs/adr/0050-in-browser-analytics-assistant.md)
+- MCP server built on this catalog: [`@uptimizr/mcp`](../mcp/README.md)
+- Integration & API reference: https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+/** A query-string parameter map. `undefined` values are omitted from the request. */
+export type QueryParams = Record<string, string | number | undefined>;
+/**
+ * A minimal **read-only** HTTP client over the collector query API. It performs
+ * `GET` requests only and holds no business logic — it is a thin transport that
+ * mirrors the dashboard's `CollectorApi` so an agent reads the same aggregated
+ * results a human would (ADR 0005 / ADR 0017).
+ */
+export interface CollectorClient {
+    get(path: string, params?: QueryParams): Promise<unknown>;
+}
+/**
+ * The `(collectorUrl, apiKey)` pair a collector client binds to. Every consumer
+ * (MCP, dashboard, demo) talks only to its **own** collector, authenticated with
+ * its own project API key — nothing is sent to any third party (ADR 0003 / 0017).
+ */
+export interface CollectorClientConfig {
+    /** Base URL of the consumer's Uptimizr collector (e.g. https://collect.example.com). */
+    collectorUrl: string;
+    /** Project API key (`x-api-key`) used for read requests. */
+    apiKey: string;
+}
+/** Thrown when the collector responds with a non-2xx status. */
+export declare class CollectorError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Build a read-only collector client bound to one `(collectorUrl, apiKey)` pair.
+ * `fetchImpl` is injectable for testing; it defaults to the global `fetch`.
+ */
+export declare function createCollectorClient(config: CollectorClientConfig, fetchImpl?: typeof fetch): CollectorClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,GAAE,OAAO,KAAa,GAC9B,eAAe,CAmBjB"}

package/dist/client.js

@@ -0,0 +1,38 @@
+/** Thrown when the collector responds with a non-2xx status. */
+export class CollectorError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "CollectorError";
+    }
+}
+function ensureTrailingSlash(url) {
+    return url.endsWith("/") ? url : `${url}/`;
+}
+/**
+ * Build a read-only collector client bound to one `(collectorUrl, apiKey)` pair.
+ * `fetchImpl` is injectable for testing; it defaults to the global `fetch`.
+ */
+export function createCollectorClient(config, fetchImpl = fetch) {
+    const base = ensureTrailingSlash(config.collectorUrl);
+    return {
+        async get(path, params = {}) {
+            const url = new URL(path.replace(/^\//, ""), base);
+            for (const [key, value] of Object.entries(params)) {
+                if (value != null)
+                    url.searchParams.set(key, String(value));
+            }
+            const res = await fetchImpl(url, {
+                method: "GET",
+                headers: { "x-api-key": config.apiKey },
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new CollectorError(body || res.statusText, res.status);
+            }
+            return res.json();
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAyBA,gEAAgE;AAChE,MAAM,OAAO,cAAe,SAAQ,KAAK;IAG5B;IAFX,YACE,OAAe,EACN,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,SAAS,mBAAmB,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA6B,EAC7B,YAA0B,KAAK;IAE/B,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACtD,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,SAAsB,EAAE;YAC9C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YACnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClD,IAAI,KAAK,IAAI,IAAI;oBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;gBAC/B,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;aACxC,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9C,MAAM,IAAI,cAAc,CAAC,IAAI,IAAI,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC/D,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createCollectorClient, CollectorError, type CollectorClient, type CollectorClientConfig, type QueryParams, } from "./client.js";
+export { readTools, type ReadTool, type ReadToolRequest } from "./tools.js";
+export type { AgentMessage, AgentToolCall, AgentToolSchema, LlmProvider, ProviderRequest, ProviderResponse, } from "./provider.js";
+export { runAgent, toToolSchemas, DEFAULT_MAX_STEPS, type RunAgentOptions, type RunAgentResult, } from "./loop.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5E,YAAY,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createCollectorClient, CollectorError, } from "./client.js";
+export { readTools } from "./tools.js";
+export { runAgent, toToolSchemas, DEFAULT_MAX_STEPS, } from "./loop.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,GAIf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AAS5E,OAAO,EACL,QAAQ,EACR,aAAa,EACb,iBAAiB,GAGlB,MAAM,WAAW,CAAC"}

package/dist/loop.d.ts

@@ -0,0 +1,47 @@
+import type { CollectorClient } from "./client.js";
+import type { AgentMessage, AgentToolSchema, LlmProvider } from "./provider.js";
+import { type ReadTool } from "./tools.js";
+/** Default cap on provider turns before the loop gives up (guards against loops). */
+export declare const DEFAULT_MAX_STEPS = 8;
+/**
+ * Convert the read-only tool catalog into provider-facing tool schemas. Each
+ * tool's Zod raw shape becomes a JSON-Schema object the model can reason about.
+ */
+export declare function toToolSchemas(tools?: readonly ReadTool[]): AgentToolSchema[];
+/** Options for a single {@link runAgent} invocation. */
+export interface RunAgentOptions {
+    /** The LLM backend to drive the conversation. */
+    provider: LlmProvider;
+    /** Read-only collector client used to execute tool calls. */
+    client: CollectorClient;
+    /** The conversation so far (typically a system + user message to start). */
+    messages: AgentMessage[];
+    /** Tool catalog to expose; defaults to the shared read-only catalog. */
+    tools?: readonly ReadTool[];
+    /** Maximum provider turns before returning. Defaults to {@link DEFAULT_MAX_STEPS}. */
+    maxSteps?: number;
+    /** Optional cancellation signal forwarded to the provider. */
+    signal?: AbortSignal;
+}
+/** The outcome of a completed agent run. */
+export interface RunAgentResult {
+    /** The model's final natural-language answer (empty if it never produced one). */
+    content: string;
+    /** The full transcript, including assistant tool calls and tool results. */
+    messages: AgentMessage[];
+    /** How many provider turns were taken. */
+    steps: number;
+    /** True when the loop stopped because it hit `maxSteps` rather than a final answer. */
+    stoppedOnMaxSteps: boolean;
+}
+/**
+ * Run the headless tool-calling loop: ask the provider for the next step, and
+ * while it requests tool calls, execute each against the read-only collector
+ * client and feed the results back. Returns once the provider yields a final
+ * answer or the step cap is reached.
+ *
+ * The loop only ever issues collector `GET`s through the catalog's
+ * `buildRequest` — it can neither ingest nor mutate data (ADR 0003 / 0017).
+ */
+export declare function runAgent(options: RunAgentOptions): Promise<RunAgentResult>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAiB,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,SAAS,QAAQ,EAAc,GAAG,eAAe,EAAE,CAMvF;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,QAAQ,EAAE,WAAW,CAAC;IACtB,6DAA6D;IAC7D,MAAM,EAAE,eAAe,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wEAAwE;IACxE,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA8BhF"}

package/dist/loop.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { readTools } from "./tools.js";
+/** Default cap on provider turns before the loop gives up (guards against loops). */
+export const DEFAULT_MAX_STEPS = 8;
+/**
+ * Convert the read-only tool catalog into provider-facing tool schemas. Each
+ * tool's Zod raw shape becomes a JSON-Schema object the model can reason about.
+ */
+export function toToolSchemas(tools = readTools) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: z.toJSONSchema(z.object(tool.inputSchema)),
+    }));
+}
+/**
+ * Run the headless tool-calling loop: ask the provider for the next step, and
+ * while it requests tool calls, execute each against the read-only collector
+ * client and feed the results back. Returns once the provider yields a final
+ * answer or the step cap is reached.
+ *
+ * The loop only ever issues collector `GET`s through the catalog's
+ * `buildRequest` — it can neither ingest nor mutate data (ADR 0003 / 0017).
+ */
+export async function runAgent(options) {
+    const { provider, client, signal } = options;
+    const tools = options.tools ?? readTools;
+    const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+    const toolsByName = new Map(tools.map((t) => [t.name, t]));
+    const toolSchemas = toToolSchemas(tools);
+    const messages = [...options.messages];
+    let steps = 0;
+    while (steps < maxSteps) {
+        steps += 1;
+        const response = await provider.complete({ messages, tools: toolSchemas, signal });
+        if (response.kind === "final") {
+            messages.push({ role: "assistant", content: response.content });
+            return { content: response.content, messages, steps, stoppedOnMaxSteps: false };
+        }
+        messages.push({
+            role: "assistant",
+            content: response.content ?? "",
+            toolCalls: response.toolCalls,
+        });
+        for (const call of response.toolCalls) {
+            messages.push(await executeToolCall(client, toolsByName.get(call.name), call));
+        }
+    }
+    return { content: "", messages, steps, stoppedOnMaxSteps: true };
+}
+/**
+ * Execute one tool call and return the `tool` result message. Unknown tools and
+ * invalid arguments produce an error result (rather than throwing) so the model
+ * can see the failure and recover on the next turn. Collector errors are
+ * likewise surfaced as text.
+ */
+async function executeToolCall(client, tool, call) {
+    const result = (content) => ({
+        role: "tool",
+        toolCallId: call.id,
+        name: call.name,
+        content,
+    });
+    if (!tool) {
+        return result(`Error: unknown tool "${call.name}".`);
+    }
+    const parsed = z.object(tool.inputSchema).safeParse(call.arguments ?? {});
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("; ");
+        return result(`Error: invalid arguments for "${call.name}": ${issues}`);
+    }
+    try {
+        const { path, params } = tool.buildRequest(parsed.data);
+        const data = await client.get(path, params);
+        return result(JSON.stringify(data));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return result(`Error: ${message}`);
+    }
+}
+//# sourceMappingURL=loop.js.map

package/dist/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"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"}