@janux/agent 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@janux/agent",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Janux embedded agent runtime: zero-config model resolution, provider routing and the ui/api tool loop.",
   "repository": {
     "type": "git",
@@ -14,11 +14,30 @@
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./local": "./src/local/index.ts"
   },
   "dependencies": {
-    "janux": "0.1.0",
-    "@janux/server": "0.1.0"
+    "janux": "0.2.1",
+    "@janux/server": "0.2.1",
+    "@aralroca/gui-agent": "^0.5.0",
+    "ai": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@browser-ai/transformers-js": ">=2.2.0",
+    "@huggingface/transformers": ">=3.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@browser-ai/transformers-js": {
+      "optional": true
+    },
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@browser-ai/transformers-js": "^2.2.2",
+    "@happy-dom/global-registrator": "^15.11.0"
   },
   "homepage": "https://github.com/aralroca/Janux#readme",
   "bugs": "https://github.com/aralroca/Janux/issues",

package/src/agent.ts

@@ -1,4 +1,5 @@
 import type { AgentDeps, AgentMount } from '@janux/server';
+import { createLlmHandler } from './llm-endpoint';
 import { resolveModel, setupCard, type ModelEnv } from './model';
 import { callProvider, type AgentTool, type ChatMessage, type FetchLike, type ToolCall } from './providers';
 
@@ -83,6 +84,7 @@ export function defineAgent(config: AgentConfig = {}, overrides: AgentOverrides
   const maxTurns = config.maxTurns ?? 6;
 
   return {
+    handleLlm: createLlmHandler(config.model, env, fetchImpl),
     async handle(req: Request, deps: AgentDeps): Promise<Response> {
       const model = resolveModel(config.model, env);
 

package/src/llm-endpoint.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'bun:test';
+import { defineAgent } from './agent';
+
+const ENV = { ANTHROPIC_API_KEY: 'test-key' };
+
+function anthropicReply(blocks: unknown[]): Response {
+  return new Response(JSON.stringify({ content: blocks }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function llmRequest(body: unknown): Request {
+  return new Request('http://localhost/_janux/llm', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+describe('/_janux/llm handler', () => {
+  it('answers with a setup card (503) when no model is configured', async () => {
+    const mount = defineAgent({}, { env: {} });
+    const response = await mount.handleLlm!(llmRequest({ messages: [], tools: [] }));
+
+    expect(response.status).toBe(503);
+    expect(((await response.json()) as any).type).toBe('setup');
+  });
+
+  it('proxies one turn: system extracted, tools mapped, arguments round-tripped', async () => {
+    let sent: any;
+    const fetchImpl = async (_url: string, init: RequestInit) => {
+      sent = JSON.parse(init.body as string);
+
+      return anthropicReply([
+        { type: 'text', text: 'Searching…' },
+        { type: 'tool_use', id: 'call_1', name: 'search_docs', input: { query: 'islands' } },
+      ]);
+    };
+    const mount = defineAgent({}, { env: ENV, fetchImpl });
+    const response = await mount.handleLlm!(
+      llmRequest({
+        messages: [
+          { role: 'system', content: 'You answer from the docs.' },
+          { role: 'user', content: 'What are islands?' },
+          { role: 'assistant', content: '', toolCalls: [{ id: 'c0', name: 'search_docs', arguments: { query: 'x' } }] },
+          { role: 'tool', content: '{"matches":[]}', toolCallId: 'c0' },
+        ],
+        tools: [{ name: 'search_docs', description: 'Search the docs', inputSchema: { type: 'object' } }],
+      }),
+    );
+    const body = (await response.json()) as any;
+
+    expect(sent.system).toBe('You answer from the docs.');
+    expect(sent.tools).toEqual([{ name: 'search_docs', description: 'Search the docs', input_schema: { type: 'object' } }]);
+    expect(sent.messages[0]).toEqual({ role: 'user', content: 'What are islands?' });
+    expect(body.text).toBe('Searching…');
+    expect(body.toolCalls).toEqual([{ id: 'call_1', name: 'search_docs', arguments: { query: 'islands' } }]);
+  });
+
+  it('tolerates an empty body', async () => {
+    const fetchImpl = async () => anthropicReply([{ type: 'text', text: 'hi' }]);
+    const mount = defineAgent({}, { env: ENV, fetchImpl });
+    const response = await mount.handleLlm!(new Request('http://localhost/_janux/llm', { method: 'POST' }));
+
+    expect(((await response.json()) as any).text).toBe('hi');
+  });
+});

package/src/llm-endpoint.ts

@@ -0,0 +1,85 @@
+import { resolveModel, setupCard, type ModelEnv } from './model';
+import { callProvider, type AgentTool, type ChatMessage, type FetchLike, type ToolCall } from './providers';
+
+/** One turn of the gui-agent remote-Llm protocol: `{ messages, tools }` in, `{ text, toolCalls }` out. */
+interface WireMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  toolCalls?: WireToolCall[];
+  toolCallId?: string;
+}
+
+interface WireToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+interface WireTool {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+}
+
+interface WireBody {
+  messages?: WireMessage[];
+  tools?: WireTool[];
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+function systemOf(messages: WireMessage[]): string {
+  return messages
+    .filter((message) => message.role === 'system')
+    .map((message) => message.content)
+    .join('\n\n');
+}
+
+function toChatMessages(messages: WireMessage[]): ChatMessage[] {
+  return messages
+    .filter((message) => message.role !== 'system')
+    .map((message) => ({
+      role: message.role as ChatMessage['role'],
+      content: message.content,
+      toolCallId: message.toolCallId,
+      toolCalls: message.toolCalls?.map(({ id, name, arguments: input }) => ({ id, name, input })),
+    }));
+}
+
+function toAgentTools(tools: WireTool[]): AgentTool[] {
+  return tools.map(({ name, description, inputSchema }) => ({ name, description, input: inputSchema }));
+}
+
+function toWireCalls(toolCalls: ToolCall[]): WireToolCall[] {
+  return toolCalls.map(({ id, name, input }) => ({
+    id,
+    name,
+    arguments: (input ?? {}) as Record<string, unknown>,
+  }));
+}
+
+/**
+ * The `/_janux/llm` mount: a stateless single-turn proxy for browser-side
+ * agent loops (`serverLlm()` from `@janux/agent/local`). The loop and the
+ * tools stay in the page; only the model call crosses the wire.
+ */
+export function createLlmHandler(model: string | undefined, env: ModelEnv, fetchImpl: FetchLike) {
+  return async (req: Request): Promise<Response> => {
+    const resolved = resolveModel(model, env);
+
+    if (!resolved) return json(setupCard(), 503);
+    const body = (await req.json().catch(() => ({}))) as WireBody;
+    const messages = body.messages ?? [];
+    const reply = await callProvider(
+      resolved,
+      systemOf(messages),
+      toChatMessages(messages),
+      toAgentTools(body.tools ?? []),
+      fetchImpl,
+    );
+
+    return json({ text: reply.text, toolCalls: toWireCalls(reply.toolCalls) });
+  };
+}

package/src/local/copilot.test.ts

@@ -0,0 +1,113 @@
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+import { afterAll, afterEach, beforeAll, describe, expect, it, mock } from 'bun:test';
+import { registry } from '@aralroca/gui-agent';
+import type { LlmRequest, LlmResponse } from '@aralroca/gui-agent';
+import { createCopilot } from './copilot';
+
+beforeAll(() => GlobalRegistrator.register({ url: 'https://app.test/' }));
+afterAll(() => GlobalRegistrator.unregister());
+afterEach(() => {
+  registry.clear();
+  delete (window as any).janux;
+});
+
+const MANIFEST_TOOLS = [
+  { name: 'cart.addItem', description: 'Add an item', guard: 'confirm', input: { type: 'object' } },
+  { name: 'api.docs.searchDocs', description: 'Search docs', guard: 'auto', input: { type: 'object' } },
+];
+
+function installBridge(): ReturnType<typeof mock> {
+  const call = mock(async () => ({ ok: true }));
+
+  (window as any).janux = { manifest: () => ({ tools: MANIFEST_TOOLS }), call };
+
+  return call;
+}
+
+/** An Llm that requests `calls` on its first turn and answers "done" on the next. */
+function scriptedLlm(calls: LlmResponse['toolCalls']): { llm: (request: LlmRequest) => Promise<LlmResponse>; seen: LlmRequest[] } {
+  const seen: LlmRequest[] = [];
+  const llm = async (request: LlmRequest): Promise<LlmResponse> => {
+    seen.push(request);
+
+    return seen.length === 1 ? { toolCalls: calls } : { text: 'done' };
+  };
+
+  return { llm, seen };
+}
+
+describe('createCopilot', () => {
+  it('exposes sanitized manifest tools to the model and routes calls through the bridge', async () => {
+    const call = installBridge();
+    const { llm, seen } = scriptedLlm([{ id: '1', name: 'cart_addItem', arguments: { sku: 'a' } }]);
+    const copilot = createCopilot({ llm });
+    const result = await copilot.ask('add item a');
+
+    expect(seen[0]!.tools.map((tool) => tool.name)).toEqual(['cart_addItem', 'api_docs_searchDocs', 'navigate']);
+    expect(seen[0]!.tools[0]!.description).toContain('a human must approve');
+    expect(call).toHaveBeenCalledWith('cart.addItem', { sku: 'a' });
+    expect(result.text).toBe('done');
+    expect(result.messages.at(-2)?.role).toBe('tool');
+  });
+
+  it('routes api.* tools through /_janux/api instead of the bridge', async () => {
+    const call = installBridge();
+    const originalFetch = globalThis.fetch;
+    const fetchMock = mock(async (url: string) => Response.json({ matches: [] }));
+
+    globalThis.fetch = fetchMock as any;
+    const { llm } = scriptedLlm([{ id: '1', name: 'api_docs_searchDocs', arguments: { query: 'x' } }]);
+
+    await createCopilot({ llm }).ask('search x');
+    globalThis.fetch = originalFetch;
+
+    expect(call).not.toHaveBeenCalled();
+    expect(fetchMock.mock.calls[0]?.[0]).toBe('/_janux/api/docs.searchDocs');
+  });
+
+  it('skips manifest bridging when manifestTools is false, but keeps navigate', async () => {
+    installBridge();
+    const { llm, seen } = scriptedLlm([]);
+
+    await createCopilot({ llm, manifestTools: false }).ask('hi');
+
+    expect(seen[0]!.tools.map((tool) => tool.name)).toEqual(['navigate']);
+  });
+
+  it('navigate drives the page through the framework tool', async () => {
+    installBridge();
+    document.body.innerHTML = '<a href="/docs/guide/cli-and-deployment">CLI</a>';
+    const assign = mock((path: string) => path);
+
+    (location as any).assign = assign;
+    const { llm } = scriptedLlm([{ id: '1', name: 'navigate', arguments: { path: '/docs/guide/cli-and-deployment' } }]);
+
+    await createCopilot({ llm, manifestTools: false }).ask('go to cli');
+    await new Promise((resolve) => setTimeout(resolve, 420));
+
+    expect(assign).toHaveBeenCalledWith('/docs/guide/cli-and-deployment');
+  });
+
+  it('never overwrites a same-named tool the app registered itself', async () => {
+    installBridge();
+    const appExecute = mock(async () => 'app wins');
+
+    registry.register({ name: 'cart_addItem', description: 'App-owned', execute: appExecute });
+    const { llm } = scriptedLlm([{ id: '1', name: 'cart_addItem', arguments: {} }]);
+
+    await createCopilot({ llm }).ask('add');
+
+    expect(appExecute).toHaveBeenCalled();
+  });
+
+  it('dispose unregisters the bridged tools', async () => {
+    installBridge();
+    const { llm } = scriptedLlm([]);
+    const copilot = createCopilot({ llm });
+
+    await copilot.ask('hi');
+    expect(registry.has('cart_addItem')).toBe(true);
+    copilot.dispose();
+    expect(registry.has('cart_addItem')).toBe(false);
+  });
+});

package/src/local/copilot.ts

@@ -0,0 +1,114 @@
+import { GuiAgent, registry } from '@aralroca/gui-agent';
+import type { AgentStep, Confirm, Llm, RunResult, ToolDefinition } from '@aralroca/gui-agent';
+import { createNavigateTool } from 'janux/client';
+
+export interface CopilotOptions {
+  /** The model driving the loop: `localLlm()`, `serverLlm()`, or any custom {@link Llm}. */
+  llm: Llm;
+  /** Extra system prompt appended to gui-agent's built-in instructions. */
+  instructions?: string;
+  /** Maximum tool-calling rounds per question. Default 8. */
+  maxSteps?: number;
+  /** Confirmation gate for non-read-only tool calls. */
+  confirm?: Confirm;
+  /** Observe each step of the loop. */
+  onStep?: (step: AgentStep) => void;
+  /** Expose the Janux manifest tools (intents + api()) to the model. Default true. */
+  manifestTools?: boolean;
+  /** Synthesize generic click/fill/read tools from the live DOM. Default false. */
+  domFallback?: boolean;
+}
+
+export interface Copilot {
+  /** Run the agent loop toward `question`; resolves with the final answer and transcript. */
+  ask(question: string, signal?: AbortSignal): Promise<RunResult>;
+  /** Unregister the manifest tools this copilot bridged into gui-agent. */
+  dispose(): void;
+}
+
+/** Models are steadier with `snake_case` names; mirrors installWebMCP's sanitization. */
+const wireName = (name: string): string => name.replace(/[^\w-]/g, '_');
+
+async function callServerTool(name: string, input: unknown): Promise<unknown> {
+  const response = await fetch(`/_janux/api/${name.slice('api.'.length)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-janux-origin': 'agent' },
+    body: JSON.stringify(input ?? {}),
+  });
+
+  return response.json();
+}
+
+function toDefinition(tool: any, bridge: any): ToolDefinition {
+  const approval = tool.guard === 'confirm' ? ' Returns a proposal a human must approve.' : '';
+
+  return {
+    name: wireName(tool.name),
+    description: `${tool.description ?? `Janux tool ${tool.name}`}${approval}`,
+    inputSchema: tool.input ?? { type: 'object', properties: {} },
+    execute: (input) =>
+      tool.name.startsWith('api.') ? callServerTool(tool.name, input) : bridge.call(tool.name, input),
+  };
+}
+
+/** Re-registers every manifest tool (replace-mode: SPA navigations change the surface). */
+function syncManifestTools(registered: Set<string>): void {
+  const bridge = (window as any).janux;
+
+  if (!bridge) return;
+  bridge.manifest().tools.forEach((tool: any) => {
+    const name = wireName(tool.name);
+
+    // A same-named tool registered by the app itself (defineTool) wins.
+    if (registry.has(name) && !registered.has(name)) return;
+    registry.register(toDefinition(tool, bridge), { replace: true, skipModelContext: true });
+    registered.add(name);
+  });
+}
+
+/** Mirrors the framework's built-in navigate tool into the gui-agent registry. */
+function syncNavigateTool(registered: Set<string>): void {
+  const tool = createNavigateTool();
+
+  if (registry.has(tool.name) && !registered.has(tool.name)) return;
+  registry.register(
+    {
+      name: tool.name,
+      description: tool.description ?? tool.name,
+      inputSchema: tool.inputSchema,
+      execute: (input) => tool.execute(input),
+    },
+    { replace: true, skipModelContext: true },
+  );
+  registered.add(tool.name);
+}
+
+/**
+ * A browser-side copilot for a Janux app: the gui-agent loop over the app's
+ * own tools (manifest intents + api() endpoints, plus anything registered with
+ * `defineTool`), driven by a local or server {@link Llm}.
+ */
+export function createCopilot(options: CopilotOptions): Copilot {
+  const registered = new Set<string>();
+
+  return {
+    ask(question, signal) {
+      if (options.manifestTools !== false) syncManifestTools(registered);
+      syncNavigateTool(registered);
+      const agent = new GuiAgent({
+        llm: options.llm,
+        systemPrompt: options.instructions,
+        maxSteps: options.maxSteps ?? 8,
+        domFallback: options.domFallback ?? false,
+        confirm: options.confirm,
+        onStep: options.onStep,
+      });
+
+      return agent.run(question, signal);
+    },
+    dispose() {
+      registered.forEach((name) => registry.unregister(name));
+      registered.clear();
+    },
+  };
+}

package/src/local/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `@janux/agent/local` — the browser-side copilot runtime.
+ *
+ * The agent loop runs in the page (via `@aralroca/gui-agent`) against the
+ * app's own tools; the model is pluggable: `localLlm()` runs an open-source
+ * model on the visitor's machine (WebGPU), `serverLlm()` keeps it server-side.
+ */
+export { createCopilot, type Copilot, type CopilotOptions } from './copilot';
+export {
+  DEFAULT_LOCAL_MODEL,
+  localLlm,
+  serverLlm,
+  supportsLocalLlm,
+  type LocalLlm,
+  type LocalLlmOptions,
+  type ServerLlmOptions,
+} from './llm';
+export { defineTool, registry } from '@aralroca/gui-agent';
+export type {
+  AgentStep,
+  Confirm,
+  Llm,
+  LlmRequest,
+  LlmResponse,
+  RunResult,
+  ToolDefinition,
+} from '@aralroca/gui-agent';

package/src/local/llm.ts

@@ -0,0 +1,84 @@
+import { createAiSdkLlm, createRemoteLlm } from '@aralroca/gui-agent/ai-sdk';
+import type { Llm, LlmRequest, LlmResponse } from '@aralroca/gui-agent';
+
+/** Apache-2.0, ~500 MB in q4f16 and the strongest tool-caller of its size class. */
+export const DEFAULT_LOCAL_MODEL = 'onnx-community/Qwen3-0.6B-ONNX';
+
+export interface LocalLlmOptions {
+  /** Hugging Face model id (ONNX). Defaults to {@link DEFAULT_LOCAL_MODEL}. */
+  modelId?: string;
+  device?: 'webgpu' | 'wasm';
+  dtype?: string;
+  /** Run inference off the main thread (a worker module using `TransformersJSWorkerHandler`). */
+  worker?: Worker;
+  /** Extra settings forwarded to `generateText` (temperature, maxOutputTokens…). */
+  settings?: Record<string, unknown>;
+}
+
+export interface LocalLlm extends Llm {
+  /** Download the model (or reuse the browser cache) ahead of the first request. */
+  load(options?: { onProgress?: (fraction: number) => void }): Promise<void>;
+}
+
+/** Whether this browser can run the local model (WebGPU available). */
+export function supportsLocalLlm(): boolean {
+  return typeof navigator !== 'undefined' && 'gpu' in navigator;
+}
+
+async function importProvider(): Promise<any> {
+  try {
+    return await import('@browser-ai/transformers-js');
+  } catch (error) {
+    throw new Error(
+      'janux: localLlm() requires "@browser-ai/transformers-js" and its peers ' +
+        `("ai", "@huggingface/transformers") to be installed. (${String(error)})`,
+    );
+  }
+}
+
+async function createSession(options: LocalLlmOptions, onProgress?: (fraction: number) => void): Promise<Llm> {
+  const { transformersJS } = await importProvider();
+  const model = transformersJS(options.modelId ?? DEFAULT_LOCAL_MODEL, {
+    device: options.device ?? 'webgpu',
+    dtype: options.dtype ?? 'q4f16',
+    ...(options.worker ? { worker: options.worker } : {}),
+  });
+
+  await model.createSessionWithProgress((fraction: number) => onProgress?.(fraction));
+
+  return createAiSdkLlm({ model, settings: options.settings });
+}
+
+/**
+ * An {@link Llm} backed by an open-source model running in the visitor's
+ * browser (Transformers.js over WebGPU). The model downloads lazily — call
+ * `load()` first to control when (and show progress).
+ */
+export function localLlm(options: LocalLlmOptions = {}): LocalLlm {
+  let session: Promise<Llm> | undefined;
+
+  const ensure = (onProgress?: (fraction: number) => void): Promise<Llm> =>
+    (session ??= createSession(options, onProgress));
+  const llm = (async (request: LlmRequest): Promise<LlmResponse> => (await ensure())(request)) as LocalLlm;
+
+  llm.load = async ({ onProgress } = {}) => {
+    await ensure(onProgress);
+  };
+
+  return llm;
+}
+
+export interface ServerLlmOptions {
+  /** Defaults to the built-in `/_janux/llm` mount. */
+  endpoint?: string;
+  headers?: Record<string, string>;
+}
+
+/**
+ * An {@link Llm} backed by the app's server (`/_janux/llm`), where the model
+ * and API keys resolve exactly like `defineAgent()`. Same browser-side loop,
+ * different brain.
+ */
+export function serverLlm(options: ServerLlmOptions = {}): Llm {
+  return createRemoteLlm({ api: options.endpoint ?? '/_janux/llm', headers: options.headers });
+}