@janux/agent 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @janux/agent
+
+Embedded agent runtime for [Janux](https://github.com/aralroca/Janux): zero-config model resolution (`JANUX_MODEL` or provider API key sniffing), Anthropic/OpenAI/Google providers, and the tool loop that executes `api.*` tools server-side and returns `ui_calls` for the client bridge.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@janux/agent",
+  "version": "0.1.0",
+  "description": "Janux embedded agent runtime: zero-config model resolution, provider routing and the ui/api tool loop.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aralroca/Janux.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Aral Roca Gomez",
+    "email": "contact@aralroca.com"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "janux": "0.1.0",
+    "@janux/server": "0.1.0"
+  },
+  "homepage": "https://github.com/aralroca/Janux#readme",
+  "bugs": "https://github.com/aralroca/Janux/issues",
+  "keywords": [
+    "janux",
+    "agentic-ui",
+    "mcp",
+    "webmcp",
+    "ai-agents",
+    "fullstack",
+    "framework",
+    "bun",
+    "vite",
+    "resumability",
+    "copilot"
+  ],
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'bun:test';
+import { component, intent, jsx, schema, str } from 'janux';
+import { api, createJanuxServer } from '@janux/server';
+import { resolveModel } from './model';
+import { defineAgent } from './agent';
+
+describe('model resolution (RFC §8.1)', () => {
+  const env = { ANTHROPIC_API_KEY: 'sk-a', OPENAI_API_KEY: 'sk-o' };
+
+  it('explicit model wins', () => {
+    const model = resolveModel('openai/gpt-5.2', env)!;
+
+    expect(model).toMatchObject({ provider: 'openai', model: 'gpt-5.2', source: 'defineAgent({ model })' });
+  });
+
+  it('JANUX_MODEL env comes second', () => {
+    const model = resolveModel(undefined, { ...env, JANUX_MODEL: 'anthropic/claude-fable-5' })!;
+
+    expect(model).toMatchObject({ provider: 'anthropic', model: 'claude-fable-5', source: 'JANUX_MODEL' });
+  });
+
+  it('sniffs the provider from the first available API key', () => {
+    const model = resolveModel(undefined, { OPENAI_API_KEY: 'sk-o' })!;
+
+    expect(model.provider).toBe('openai');
+    expect(model.source).toContain('OPENAI_API_KEY');
+  });
+
+  it('returns undefined with no keys (setup card path)', () => {
+    expect(resolveModel(undefined, {})).toBeUndefined();
+  });
+});
+
+function anthropicReply(blocks: unknown[]): Response {
+  return new Response(JSON.stringify({ content: blocks }), { status: 200 });
+}
+
+function scriptedFetch(replies: Response[]) {
+  const calls: { url: string; body: any }[] = [];
+  const fetchImpl = async (url: string, init: RequestInit) => {
+    calls.push({ url, body: JSON.parse(String(init.body)) });
+
+    return replies.shift() ?? anthropicReply([{ type: 'text', text: 'done' }]);
+  };
+
+  return { fetchImpl, calls };
+}
+
+const counter = component({
+  name: 'counter',
+  state: schema({ label: str() }),
+  intents: { rename: intent({ input: schema({ label: str() }), run: () => {} }) },
+  view: () => jsx('p', { children: 'hi' }),
+});
+
+function buildServer(agent: ReturnType<typeof defineAgent>) {
+  return createJanuxServer({
+    routes: { '/': () => jsx(counter as any, {}) },
+    apis: {
+      shop: {
+        search: api({ input: schema({ q: str() }), run: ({ input }) => [`found:${input.q}`] }),
+      },
+    },
+    agent,
+  });
+}
+
+const ask = (server: ReturnType<typeof buildServer>, body: unknown) =>
+  server.fetch(
+    new Request('http://test/_janux/agent', {
+      method: 'POST',
+      body: JSON.stringify(body),
+      headers: { 'content-type': 'application/json' },
+    }),
+  );
+
+describe('agent loop', () => {
+  const env = { ANTHROPIC_API_KEY: 'sk-test' };
+
+  it('returns a setup card when no model is configured', async () => {
+    const server = buildServer(defineAgent({}, { env: {} }));
+    const body: any = await (await ask(server, { messages: [] })).json();
+
+    expect(body.type).toBe('setup');
+    expect(body.message).toContain('JANUX_MODEL');
+  });
+
+  it('answers plain text and reports the resolved model', async () => {
+    const { fetchImpl } = scriptedFetch([anthropicReply([{ type: 'text', text: 'Hello!' }])]);
+    const server = buildServer(defineAgent({}, { env, fetchImpl }));
+    const body: any = await (await ask(server, { messages: [{ role: 'user', content: 'hi' }] })).json();
+
+    expect(body).toMatchObject({ type: 'text', text: 'Hello!', model: 'anthropic/claude-sonnet-5' });
+  });
+
+  it('executes api.* tools server-side and continues the loop', async () => {
+    const { fetchImpl, calls } = scriptedFetch([
+      anthropicReply([{ type: 'tool_use', id: 't1', name: 'api__shop__search', input: { q: 'shoes' } }]),
+      anthropicReply([{ type: 'text', text: 'Found 1 result' }]),
+    ]);
+    const server = buildServer(defineAgent({}, { env, fetchImpl }));
+    const body: any = await (await ask(server, { messages: [{ role: 'user', content: 'search shoes' }] })).json();
+
+    expect(body.type).toBe('text');
+    expect(body.text).toBe('Found 1 result');
+    const toolResult = calls[1]!.body.messages.find((m: any) => m.content?.[0]?.type === 'tool_result');
+
+    expect(toolResult.content[0].content).toBe('["found:shoes"]');
+  });
+
+  it('returns ui_calls for UI tools so the client bridge executes them', async () => {
+    const { fetchImpl } = scriptedFetch([
+      anthropicReply([{ type: 'tool_use', id: 't2', name: 'counter__rename', input: { label: 'x' } }]),
+    ]);
+    const server = buildServer(defineAgent({}, { env, fetchImpl }));
+    const body: any = await (await ask(server, { messages: [{ role: 'user', content: 'rename' }] })).json();
+
+    expect(body.type).toBe('ui_calls');
+    expect(body.calls).toEqual([{ id: 't2', name: 'counter.rename', input: { label: 'x' } }]);
+    expect(body.messages.at(-1).toolCalls).toHaveLength(1);
+  });
+
+  it('coalesces parallel tool results into one user message (Anthropic alternation)', async () => {
+    const { fetchImpl, calls } = scriptedFetch([
+      anthropicReply([
+        { type: 'tool_use', id: 'a1', name: 'api__shop__search', input: { q: 'x' } },
+        { type: 'tool_use', id: 'a2', name: 'api__shop__search', input: { q: 'y' } },
+      ]),
+      anthropicReply([{ type: 'text', text: 'both done' }]),
+    ]);
+    const server = buildServer(defineAgent({}, { env, fetchImpl }));
+    const body: any = await (await ask(server, { messages: [{ role: 'user', content: 'go' }] })).json();
+
+    expect(body.text).toBe('both done');
+    const secondRequest = calls[1]!.body.messages;
+    const userMessages = secondRequest.filter((m: any) => m.role === 'user');
+
+    expect(userMessages).toHaveLength(2);
+    expect(userMessages[1].content).toHaveLength(2);
+    expect(userMessages[1].content.map((b: any) => b.tool_use_id)).toEqual(['a1', 'a2']);
+    secondRequest.forEach((message: any, index: number) => {
+      if (index === 0) return;
+      expect(message.role).not.toBe(secondRequest[index - 1].role);
+    });
+  });
+
+  it('exposes manifest tools with guard annotations to the model', async () => {
+    const { fetchImpl, calls } = scriptedFetch([anthropicReply([{ type: 'text', text: 'ok' }])]);
+    const server = buildServer(defineAgent({}, { env, fetchImpl }));
+
+    await ask(server, { messages: [{ role: 'user', content: 'hi' }], path: '/' });
+    const toolNames = calls[0]!.body.tools.map((tool: any) => tool.name);
+
+    expect(toolNames).toContain('counter__rename');
+    expect(toolNames).toContain('api__shop__search');
+  });
+});

package/src/agent.ts

@@ -0,0 +1,113 @@
+import type { AgentDeps, AgentMount } from '@janux/server';
+import { resolveModel, setupCard, type ModelEnv } from './model';
+import { callProvider, type AgentTool, type ChatMessage, type FetchLike, type ToolCall } from './providers';
+
+export interface AgentConfig {
+  instructions?: string;
+  model?: string;
+  maxTurns?: number;
+  tools?: { include?: string[] };
+}
+
+export interface AgentOverrides {
+  env?: ModelEnv;
+  fetchImpl?: FetchLike;
+}
+
+interface AgentRequestBody {
+  messages: ChatMessage[];
+  path?: string;
+}
+
+const SYSTEM_PREAMBLE = [
+  'You are the built-in copilot of a Janux application.',
+  'Tools prefixed "api." run on the server. All other tools operate the live UI;',
+  'tools marked [guard:confirm] return a proposal the human approves on the real UI.',
+  'Read resource state before acting. Never invent tool names.',
+].join(' ');
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+function includeTool(name: string, patterns: string[] | undefined): boolean {
+  if (!patterns || patterns.length === 0) return true;
+
+  return patterns.some((pattern) =>
+    pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : name === pattern,
+  );
+}
+
+function manifestTools(manifest: any, patterns: string[] | undefined): AgentTool[] {
+  return (manifest.tools ?? [])
+    .filter((tool: any) => includeTool(tool.name, patterns))
+    .map((tool: any) => ({
+      name: tool.name,
+      description: `${tool.description ?? ''} [guard:${tool.guard}]`.trim(),
+      input: tool.input,
+    }));
+}
+
+function systemPrompt(config: AgentConfig, manifest: any): string {
+  const resources = JSON.stringify(manifest.resources ?? []);
+
+  return [config.instructions, SYSTEM_PREAMBLE, `Mounted resources: ${resources}`]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+async function runServerCalls(calls: ToolCall[], deps: AgentDeps): Promise<ChatMessage[]> {
+  const results: ChatMessage[] = [];
+
+  for (const call of calls) {
+    const content = await deps
+      .invoke(call.name, call.input)
+      .then((result) => JSON.stringify(result ?? null))
+      .catch((error) => JSON.stringify({ error: String(error) }));
+
+    results.push({ role: 'tool', toolCallId: call.id, content });
+  }
+
+  return results;
+}
+
+/**
+ * Zero-config embedded agent. Stateless HTTP turn protocol:
+ * - `{type:'text'}` final answer;
+ * - `{type:'ui_calls'}` the client executes via the gui-agent bridge and re-POSTs;
+ * - `{type:'setup'}` when no model/provider is configured.
+ */
+export function defineAgent(config: AgentConfig = {}, overrides: AgentOverrides = {}): AgentMount {
+  const env = overrides.env ?? (process.env as ModelEnv);
+  const fetchImpl = overrides.fetchImpl ?? ((url, init) => fetch(url, init));
+  const maxTurns = config.maxTurns ?? 6;
+
+  return {
+    async handle(req: Request, deps: AgentDeps): Promise<Response> {
+      const model = resolveModel(config.model, env);
+
+      if (!model) return json(setupCard());
+      const body = (await req.json().catch(() => ({ messages: [] }))) as AgentRequestBody;
+      const manifest: any = await deps.manifestFor(body.path ?? '/');
+      const tools = manifestTools(manifest, config.tools?.include);
+      const system = systemPrompt(config, manifest);
+      const messages = [...(body.messages ?? [])];
+
+      for (let turn = 0; turn < maxTurns; turn += 1) {
+        const reply = await callProvider(model, system, messages, tools, fetchImpl);
+
+        messages.push({ role: 'assistant', content: reply.text, toolCalls: reply.toolCalls });
+        if (reply.toolCalls.length === 0) {
+          return json({ type: 'text', text: reply.text, messages, model: `${model.provider}/${model.model}` });
+        }
+        const serverCalls = reply.toolCalls.filter((call) => call.name.startsWith('api.'));
+        const uiCalls = reply.toolCalls.filter((call) => !call.name.startsWith('api.'));
+
+        messages.push(...(await runServerCalls(serverCalls, deps)));
+        if (uiCalls.length > 0) return json({ type: 'ui_calls', calls: uiCalls, messages });
+      }
+
+      return json({ type: 'text', text: 'I could not finish within the turn limit.', messages });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { defineAgent, type AgentConfig, type AgentOverrides } from './agent';
+export { resolveModel, setupCard, type ResolvedModel, type ModelEnv } from './model';
+export {
+  callProvider,
+  type AgentTool,
+  type ChatMessage,
+  type ToolCall,
+  type ProviderReply,
+  type FetchLike,
+} from './providers';

package/src/model.ts

@@ -0,0 +1,68 @@
+export interface ResolvedModel {
+  provider: 'anthropic' | 'openai' | 'google';
+  model: string;
+  apiKey: string;
+  source: string;
+}
+
+export interface ModelEnv {
+  [key: string]: string | undefined;
+}
+
+const PROVIDER_KEYS: Record<ResolvedModel['provider'], string> = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  google: 'GOOGLE_GENERATIVE_AI_API_KEY',
+};
+
+const DEFAULT_MODELS: Record<ResolvedModel['provider'], string> = {
+  anthropic: 'claude-sonnet-5',
+  openai: 'gpt-5.2',
+  google: 'gemini-3-pro',
+};
+
+function fromIdentifier(identifier: string, env: ModelEnv, source: string): ResolvedModel | undefined {
+  const [provider, ...rest] = identifier.split('/') as [ResolvedModel['provider'], ...string[]];
+  const apiKey = env[PROVIDER_KEYS[provider] ?? ''];
+
+  if (!PROVIDER_KEYS[provider] || rest.length === 0) return undefined;
+  if (!apiKey) return undefined;
+
+  return { provider, model: rest.join('/'), apiKey, source };
+}
+
+function sniffProvider(env: ModelEnv): ResolvedModel | undefined {
+  const available = (Object.keys(PROVIDER_KEYS) as ResolvedModel['provider'][]).filter(
+    (provider) => env[PROVIDER_KEYS[provider]],
+  );
+  const provider = available[0];
+
+  if (!provider) return undefined;
+
+  return {
+    provider,
+    model: DEFAULT_MODELS[provider],
+    apiKey: env[PROVIDER_KEYS[provider]]!,
+    source: `inferred from ${PROVIDER_KEYS[provider]}`,
+  };
+}
+
+/**
+ * RFC §8.1 resolution order: explicit code → JANUX_MODEL env → provider key
+ * sniffing → undefined (the app still boots; the agent answers with a setup card).
+ */
+export function resolveModel(explicit: string | undefined, env: ModelEnv): ResolvedModel | undefined {
+  if (explicit) return fromIdentifier(explicit, env, 'defineAgent({ model })');
+  if (env.JANUX_MODEL) return fromIdentifier(env.JANUX_MODEL, env, 'JANUX_MODEL');
+
+  return sniffProvider(env);
+}
+
+export function setupCard(): Record<string, unknown> {
+  return {
+    type: 'setup',
+    message:
+      'No model configured. Set JANUX_MODEL="provider/model" or one provider API key ' +
+      `(${Object.values(PROVIDER_KEYS).join(', ')}).`,
+  };
+}

package/src/providers.ts

@@ -0,0 +1,169 @@
+import type { ResolvedModel } from './model';
+
+export interface AgentTool {
+  name: string;
+  description?: string;
+  input?: Record<string, unknown>;
+}
+
+export interface ChatMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  toolCalls?: ToolCall[];
+  toolCallId?: string;
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: unknown;
+}
+
+export interface ProviderReply {
+  text: string;
+  toolCalls: ToolCall[];
+}
+
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+function anthropicMessages(messages: ChatMessage[]): unknown[] {
+  return messages.reduce<any[]>((acc, message) => {
+    if (message.role === 'tool') {
+      const block = { type: 'tool_result', tool_use_id: message.toolCallId, content: message.content };
+      const last = acc.at(-1);
+      const lastIsToolResults =
+        last?.role === 'user' && Array.isArray(last.content) && last.content[0]?.type === 'tool_result';
+
+      lastIsToolResults ? last.content.push(block) : acc.push({ role: 'user', content: [block] });
+
+      return acc;
+    }
+    if (message.role === 'assistant' && message.toolCalls?.length) {
+      acc.push({
+        role: 'assistant',
+        content: [
+          ...(message.content ? [{ type: 'text', text: message.content }] : []),
+          ...message.toolCalls.map((call) => ({ type: 'tool_use', id: call.id, name: call.name, input: call.input })),
+        ],
+      });
+
+      return acc;
+    }
+    acc.push({ role: message.role, content: message.content });
+
+    return acc;
+  }, []);
+}
+
+async function callAnthropic(
+  model: ResolvedModel,
+  system: string,
+  messages: ChatMessage[],
+  tools: AgentTool[],
+  fetchImpl: FetchLike,
+): Promise<ProviderReply> {
+  const response = await fetchImpl('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-api-key': model.apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: model.model,
+      max_tokens: 4096,
+      system,
+      messages: anthropicMessages(messages),
+      tools: tools.map((tool) => ({
+        name: tool.name.replace(/\./g, '__'),
+        description: tool.description ?? '',
+        input_schema: tool.input ?? { type: 'object', properties: {} },
+      })),
+    }),
+  });
+
+  if (!response.ok) throw new Error(`Anthropic API error ${response.status}: ${await response.text()}`);
+  const body: any = await response.json();
+  const blocks: any[] = body.content ?? [];
+
+  return {
+    text: blocks.filter((block) => block.type === 'text').map((block) => block.text).join(''),
+    toolCalls: blocks
+      .filter((block) => block.type === 'tool_use')
+      .map((block) => ({ id: block.id, name: block.name.replace(/__/g, '.'), input: block.input })),
+  };
+}
+
+const OPENAI_COMPAT_URLS: Record<string, string> = {
+  openai: 'https://api.openai.com/v1/chat/completions',
+  google: 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',
+};
+
+async function callOpenAi(
+  model: ResolvedModel,
+  system: string,
+  messages: ChatMessage[],
+  tools: AgentTool[],
+  fetchImpl: FetchLike,
+): Promise<ProviderReply> {
+  const response = await fetchImpl(OPENAI_COMPAT_URLS[model.provider]!, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${model.apiKey}` },
+    body: JSON.stringify({
+      model: model.model,
+      messages: [
+        { role: 'system', content: system },
+        ...messages.map((message) => openAiMessage(message)),
+      ],
+      tools: tools.map((tool) => ({
+        type: 'function',
+        function: { name: tool.name.replace(/\./g, '__'), description: tool.description ?? '', parameters: tool.input ?? {} },
+      })),
+    }),
+  });
+
+  if (!response.ok) throw new Error(`OpenAI API error ${response.status}: ${await response.text()}`);
+  const body: any = await response.json();
+  const choice = body.choices?.[0]?.message ?? {};
+
+  return {
+    text: choice.content ?? '',
+    toolCalls: (choice.tool_calls ?? []).map((call: any) => ({
+      id: call.id,
+      name: call.function.name.replace(/__/g, '.'),
+      input: JSON.parse(call.function.arguments || '{}'),
+    })),
+  };
+}
+
+function openAiMessage(message: ChatMessage): unknown {
+  if (message.role === 'tool') {
+    return { role: 'tool', tool_call_id: message.toolCallId, content: message.content };
+  }
+  if (message.role === 'assistant' && message.toolCalls?.length) {
+    return {
+      role: 'assistant',
+      content: message.content || null,
+      tool_calls: message.toolCalls.map((call) => ({
+        id: call.id,
+        type: 'function',
+        function: { name: call.name.replace(/\./g, '__'), arguments: JSON.stringify(call.input ?? {}) },
+      })),
+    };
+  }
+
+  return { role: message.role, content: message.content };
+}
+
+/** Routes a chat turn to the resolved provider. Google reuses the OpenAI-compatible endpoint. */
+export async function callProvider(
+  model: ResolvedModel,
+  system: string,
+  messages: ChatMessage[],
+  tools: AgentTool[],
+  fetchImpl: FetchLike,
+): Promise<ProviderReply> {
+  if (model.provider === 'anthropic') return callAnthropic(model, system, messages, tools, fetchImpl);
+
+  return callOpenAi(model, system, messages, tools, fetchImpl);
+}