@circuitwall/jarela 0.14.0 → 1.0.0

package/lib/tools/providers-info.ts

@@ -0,0 +1,106 @@
+// Read-only introspection for LLM provider adapters. Two paired tools:
+//   - list_providers: enumerate every adapter (built-in + external).
+//   - describe_provider: capability map + known model context windows for one.
+// Together they let the agent answer "what can we route to" or pick a model
+// by capability without hand-coded knowledge of the provider catalog.
+
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import {
+  listProviderNames,
+  getProvider,
+  BUILTIN_PROVIDER_NAMES,
+} from "@/lib/providers";
+import { listKnownModels } from "@/lib/providers/known-context-windows";
+import { registerTools } from "./registry";
+
+type ProviderSource = "builtin" | "external";
+
+function sourceOf(name: string): ProviderSource {
+  return BUILTIN_PROVIDER_NAMES.has(name) ? "builtin" : "external";
+}
+
+export const listProvidersTool = tool(
+  async () => {
+    const names = listProviderNames();
+    const providers = names.map((name) => ({
+      name,
+      source: sourceOf(name),
+    }));
+    return JSON.stringify({
+      providers,
+      count: providers.length,
+      builtin_count: providers.filter((p) => p.source === "builtin").length,
+      external_count: providers.filter((p) => p.source === "external").length,
+    });
+  },
+  {
+    name: "list_providers",
+    description:
+      "List every LLM provider adapter registered in this app (built-in like " +
+      "anthropic / openai / gemini / deepseek / github-copilot / langchain, plus " +
+      "any external `.cjs` plugins under ~/.jarela/providers/). Read-only. " +
+      "Use this before suggesting a model swap, or when answering 'what can " +
+      "we route to.' Call describe_provider afterwards for capability details.",
+    schema: z.object({}),
+  },
+);
+
+export const describeProviderTool = tool(
+  async ({ name }) => {
+    let provider;
+    try {
+      provider = getProvider(name);
+    } catch (err) {
+      return JSON.stringify({
+        error: err instanceof Error ? err.message : String(err),
+        hint: "Call list_providers to see registered names.",
+      });
+    }
+
+    // Capability inferred from which methods the adapter implements. We
+    // intentionally don't call listModels() here — that would hit the
+    // network and require valid credentials, which makes this a "read"-class
+    // tool that sometimes fails for credential reasons. Static introspection
+    // only.
+    const capabilities = {
+      chat: typeof provider.chat === "function",
+      invoke: typeof provider.invoke === "function",
+      stream_invoke: typeof provider.streamInvoke === "function",
+      embed: typeof provider.embed === "function",
+      list_models: typeof provider.listModels === "function",
+    };
+
+    const models = listKnownModels(name);
+
+    return JSON.stringify({
+      name,
+      source: sourceOf(name),
+      capabilities,
+      known_models: models,
+      notes: [
+        models.length === 0
+          ? "No static model catalog for this provider — call /api/v1/models?provider=" +
+            name + " for live discovery if the adapter implements list_models."
+          : "Static catalog only. Live `list_models` (when supported) may include " +
+            "newer models not listed here.",
+      ],
+    });
+  },
+  {
+    name: "describe_provider",
+    description:
+      "Return capability flags (chat / invoke / stream / embed / list_models) " +
+      "and the static known-models catalog (with context windows) for one " +
+      "registered provider. Read-only. Use this to choose a model by capability, " +
+      "or to explain provider differences to the user. Call list_providers first " +
+      "if you don't know the provider name.",
+    schema: z.object({
+      name: z
+        .string()
+        .describe("Provider name from list_providers, e.g. 'anthropic', 'openai', 'gemini'"),
+    }),
+  },
+);
+
+registerTools("Config", "read", [listProvidersTool, describeProviderTool]);

package/lib/tools/registry.ts

@@ -1,25 +1,33 @@
-// Tool registry.
-//
-// Each built-in tool module registers its own tools at module load with
-// two orthogonal axes:
-//
-//   * category   — topical group ("Memory", "Files", "Mail", …) used by
-//                  the Agent editor sidebar to organise tools for users.
-//   * capability — safety class ("read" | "write" | "execute") used by
-//                  the future per-capability approval gate, UI badges,
-//                  and the ADR-0037 output validator. See ADR-0038.
-//
-// lib/tools/index.ts only needs to side-effect-import the modules
-// (see ./builtins.ts) — there is no central map listing every tool by
-// name. Adding a new built-in tool now requires touching exactly two
-// files: the tool file itself, and an `import "./<name>";` line in
-// builtins.ts.
-//
-// External tools (loaded from JARELA_TOOLS_DIR at runtime) use the same
-// category vocabulary but are not stored in this registry — see
-// ./external.ts. MCP tools default to category "MCP". Both default to
-// capability "execute" until manifest-level overrides land (ADR-0038
-// follow-up).
+/**
+ * Tool registry.
+ *
+ * Each built-in tool module registers its own tools at module load with
+ * two orthogonal axes:
+ *
+ *   - category   — topical group ("Memory", "Files", "Mail", …) used by
+ *                  the Agent editor sidebar to organise tools for users.
+ *   - capability — safety class ("read" | "write" | "execute") used by
+ *                  the future per-capability approval gate, UI badges,
+ *                  and the ADR-0037 output validator. See ADR-0038.
+ *
+ * `lib/tools/index.ts` only needs to side-effect-import the modules
+ * (see ./builtins.ts) — there is no central map listing every tool by
+ * name. Adding a new built-in tool now requires touching exactly two
+ * files: the tool file itself, and an `import "./<name>";` line in
+ * builtins.ts.
+ *
+ * External tools (loaded from JARELA_TOOLS_DIR at runtime) use the same
+ * category vocabulary but are not stored in this registry — see
+ * ./external.ts. MCP tools default to category "MCP". Both default to
+ * capability "execute" until manifest-level overrides land (ADR-0038
+ * follow-up).
+ *
+ * Public surface (per `package.json#exports`): `ToolCategory`,
+ * `Capability`, `ToolGroup`, `BuiltinCategory`, `registerTools`.
+ * Everything else (`registeredTools` / `registeredNames` /
+ * `registeredCategory` / etc.) is `@internal` — used only by the in-tree
+ * runtime, not part of the plugin contract.
+ */
 
 import type { StructuredToolInterface } from "@langchain/core/tools";
 import { wrapWithWallclock } from "./wallclock";
@@ -81,29 +89,32 @@ export function registerTools<T extends StructuredToolInterface>(
   return wrapped;
 }
 
-/** All registered built-in tools, in registration order. */
+/** @internal — all registered built-in tools, in registration order. */
 export function registeredTools(): StructuredToolInterface[] {
   return Array.from(REGISTRY.values(), (e) => e.tool);
 }
 
-/** Names of all registered built-in tools — used for collision checks. */
+/** @internal — names of all registered built-in tools, used for collision checks. */
 export function registeredNames(): ReadonlySet<string> {
   return new Set(REGISTRY.keys());
 }
 
+/** @internal */
 export function registeredCategory(name: string): BuiltinCategory | undefined {
   return REGISTRY.get(name)?.category;
 }
 
+/** @internal */
 export function registeredCapability(name: string): Capability | undefined {
   return REGISTRY.get(name)?.capability;
 }
 
+/** @internal */
 export function registeredGroup(name: string): ToolGroup | undefined {
   return REGISTRY.get(name)?.group;
 }
 
-/** Test-only: clear the registry between cases. */
+/** @internal — test-only: clear the registry between cases. */
 export function _resetRegistry(): void {
   REGISTRY.clear();
 }

package/lib/tools/types.ts

@@ -1,3 +1,16 @@
+/**
+ * @public
+ *
+ * Public tool extension contract.
+ *
+ * Every type and interface in this file is part of the package's
+ * stable public surface (per `package.json#exports`). External tool
+ * authors — both in-tree built-ins and `~/.jarela/tools/*.cjs` plugins —
+ * use these to describe arguments, results, and message shapes. Removing
+ * or breaking any export here counts as a breaking change under the
+ * deprecation policy in CONTRIBUTING.md.
+ */
+
 import type { StructuredToolInterface } from "@langchain/core/tools";
 
 // LangGraph/LangChain-compatible tool type. All tools implement this interface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circuitwall/jarela",
-  "version": "0.14.0",
+  "version": "1.0.0",
   "description": "Jarela — local chat interface for LangGraph agents (multi-provider, single-process, SQLite-backed).",
   "license": "Apache-2.0",
   "author": "Andrew Ge Wu",
@@ -34,6 +34,14 @@
   "engines": {
     "node": ">=22"
   },
+  "exports": {
+    ".": null,
+    "./package.json": "./package.json",
+    "./lib/providers/types": "./lib/providers/types.ts",
+    "./lib/tools/types": "./lib/tools/types.ts",
+    "./lib/tools/registry": "./lib/tools/registry.ts",
+    "./lib/mcp/registry": "./lib/mcp/registry.ts"
+  },
   "files": [
     ".next/standalone",
     "!.next/standalone/public/sw.js",