@kitn.ai/ui 0.28.0 → 0.29.0

package/src/agent-tooling/integrations/openrouter.ts

@@ -1,82 +0,0 @@
-import type { Integration } from '../types';
-
-const openrouter: Integration = {
-  id: 'openrouter',
-  title: 'OpenRouter',
-  category: 'gateway',
-  language: 'ts',
-  streamFormat: 'openai-sse',
-  envVars: ['OPENROUTER_API_KEY'],
-  // No per-framework templates: the handler below is web-standard, so the
-  // scaffolder wraps it in whatever the target framework routes with. This used
-  // to be a `next`-only entry that every other framework inherited verbatim.
-  routeTemplates: {},
-  webRoute: `async function chatHandler(request: Request): Promise<Response> {
-  // tools is undefined unless the front end sent one; JSON.stringify drops it,
-  // so the same handler serves a tool archetype and a plain chat.
-  let chatBody: ChatRequestBody;
-  try {
-    chatBody = await readChatRequest(request);
-  } catch (error) {
-    return toChatErrorResponse(error);
-  }
-  const { model, messages, tools } = chatBody;
-
-  const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
-    method: 'POST',
-    headers: {
-      Authorization: \`Bearer \${process.env.OPENROUTER_API_KEY}\`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({ model, messages, tools, stream: true }),
-  });
-
-  // FORWARD THE STATUS. Returning 200 here is how a missing key turns into
-  // silence: the 401 body is JSON, it goes out labelled text/event-stream, the
-  // SSE reader finds no frame, and the turn resolves empty with nothing logged
-  // and no bubble. With the status intact readOpenAIStream throws a WireError
-  // carrying the provider's own message.
-  if (!upstream.ok) {
-    return new Response(await upstream.text(), {
-      status: upstream.status,
-      headers: {
-        'Content-Type': upstream.headers.get('content-type') ?? 'application/json',
-      },
-    });
-  }
-  if (!upstream.body) {
-    return new Response(JSON.stringify({ error: { message: 'The provider returned no body to stream.' } }), {
-      status: 502,
-      headers: { 'Content-Type': 'application/json' },
-    });
-  }
-
-  return new Response(upstream.body, {
-    status: 200,
-    headers: {
-      'Content-Type': 'text/event-stream; charset=utf-8',
-      // no-transform stops a proxy buffering the stream into one blob.
-      'Cache-Control': 'no-cache, no-transform',
-      Connection: 'keep-alive',
-    },
-  });
-}`,
-  streamMapping:
-    'OpenRouter returns OpenAI-format SSE. Pipe upstream.body straight to the browser; readOpenAIStream from @kitn.ai/ui/wire parses it, including tool calls and reasoning.',
-  runNote: 'Set OPENROUTER_API_KEY. Model ids are vendor/model, e.g. openai/gpt-4o.',
-  docsSlug: 'integrations/connect-any-model',
-  // The route forwards both, so a scaffold's editable consts reach the gateway.
-  forwardsFromClient: ['model', 'tools'],
-  // The handler puts the client's `tools` straight into an OpenAI-compatible
-  // /chat/completions body, unconverted — so the client must send OpenAI's own
-  // `{ type: 'function', function: { parameters } }` envelope.
-  clientToolFormat: 'openai',
-  // Nothing to install. The route is global `fetch` and imports no module.
-  deps: { npm: [], pip: [] },
-  // The route reads OPENROUTER_API_KEY into an `Authorization: Bearer` header.
-  keyExposure: 'needs-proxy',
-  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
-  outOfBand: 'none',
-};
-
-export default openrouter;

package/src/agent-tooling/integrations/pi.ts

@@ -1,176 +0,0 @@
-import type { Integration } from '../types';
-
-const pi: Integration = {
-  id: 'pi',
-  title: 'Pi',
-  category: 'harness',
-  language: 'ts',
-  streamFormat: 'native',
-  envVars: [],
-  routeTemplates: {
-    // Express only, and genuinely so: the bridge spawns a local process, which a
-    // Worker or an edge runtime cannot do. Every other framework gets this under
-    // the scaffolder's "cannot host" warning, the same way pydantic-ai emits a
-    // whole FastAPI service.
-    express: `// server.ts
-import express from 'express';
-import { spawn } from 'node:child_process';
-import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
-
-const app = express();
-app.use(express.json());
-
-class ChatRequestError extends Error {
-  constructor(readonly status: number, message: string) { super(message); }
-}
-
-/** Narrow the JSON body once, at the edge. A bare GET or a missing messages
- *  array is a ChatRequestError with a status — NEVER an unhandled throw
- *  (findings F-10). Malformed JSON is rejected upstream by express.json(),
- *  which the error handler below turns into a JSON 400. */
-function readChatRequest(req: express.Request): { messages: OpenAIWireMessage[] } {
-  if (req.method !== 'POST') {
-    throw new ChatRequestError(405, \`Method \${req.method} not allowed — POST /api/chat.\`);
-  }
-  const body = (req.body ?? {}) as { messages?: OpenAIWireMessage[] };
-  if (!Array.isArray(body.messages)) {
-    throw new ChatRequestError(400, 'Request body must carry a messages array.');
-  }
-  return body as { messages: OpenAIWireMessage[] };
-}
-
-/** Map a guard rejection to the response its status demands; rethrow anything
- *  else — an unexpected error should be loud, not laundered into a 400. */
-function toChatErrorResponse(error: unknown, res: express.Response): void {
-  if (error instanceof ChatRequestError) {
-    res.status(error.status).json({ error: { message: error.message } });
-    return;
-  }
-  throw error;
-}
-
-// express.json() rejects a malformed body at the MIDDLEWARE level, before any
-// handler runs — without this it surfaces as Express's default HTML error page.
-app.use(
-  (
-    err: { status?: number; message?: string },
-    _req: express.Request,
-    res: express.Response,
-    _next: express.NextFunction,
-  ) => {
-    res.status(err?.status ?? 500).json({ error: { message: err?.message ?? 'Request failed.' } });
-  },
-);
-
-// A bare GET is a 405 with the method named, not Express's default 404 —
-// the resource exists, the verb is wrong.
-app.get('/api/chat', (_req, res) => {
-  res.status(405).json({ error: { message: 'Method not allowed — POST /api/chat.' } });
-});
-
-// POST /api/chat: bridge a Pi RPC session to the browser as SSE.
-app.post('/api/chat', (req, res) => {
-  let chatBody: { messages: OpenAIWireMessage[] };
-  try {
-    chatBody = readChatRequest(req);
-  } catch (error) {
-    toChatErrorResponse(error, res);
-    return;
-  }
-  const { messages } = chatBody;
-  const last = messages.at(-1)?.content;
-  // \`content\` is a plain string until the turn carries an attachment, at which
-  // point it is an ARRAY of content parts. Pi's RPC mode takes a TEXT prompt and
-  // has no channel for a file, so an attachment is REFUSED here. Passing the
-  // array straight through would JSON.stringify an object graph into the prompt
-  // — no type error, no crash, just a model reading serialised noise.
-  if (Array.isArray(last) && last.some((part) => part.type !== 'text')) {
-    res.status(400).json({
-      error: {
-        message:
-          'This Pi bridge forwards a text prompt only and has no channel for an attachment. Extract the file content into the message text, or send it through a tool.',
-      },
-    });
-    return;
-  }
-  const prompt =
-    typeof last === 'string'
-      ? last
-      : (last ?? []).map((part) => (part.type === 'text' ? part.text : '')).join('');
-
-  // Headers before the first frame: without text/event-stream the browser
-  // buffers the body and readOpenAIStream never sees a frame.
-  res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
-  // no-transform stops a proxy buffering the stream into one blob.
-  res.setHeader('Cache-Control', 'no-cache, no-transform');
-  res.setHeader('Connection', 'keep-alive');
-
-  // ONE PROCESS PER REQUEST. Pi in RPC mode holds conversation state, so a
-  // module-level process would leak one caller's turns into the next caller's
-  // reply and serialise every request behind a single stdin.
-  const pi = spawn('pi', ['--mode', 'rpc', '--no-session']);
-
-  // A spawn failure (pi not on PATH) arrives asynchronously, by which point the
-  // SSE headers are out and the status is spent, so report IN BAND:
-  // readOpenAIStream lands this on turn.error instead of leaving a blank bubble.
-  pi.on('error', (err) => {
-    res.write(\`data: \${JSON.stringify({ error: { message: err.message } })}\\n\\n\`);
-    res.write('data: [DONE]\\n\\n');
-    res.end();
-  });
-
-  // Send the user's turn. Pi commands are { type, message }.
-  pi.stdin.write(JSON.stringify({ type: 'prompt', message: prompt }) + '\\n');
-
-  let buffer = '';
-  pi.stdout.on('data', (chunk: Buffer) => {
-    buffer += chunk.toString();
-    // Split on \\n rather than readline: readline also breaks on the Unicode
-    // separators U+2028/U+2029, which appear inside model output.
-    const lines = buffer.split('\\n');
-    // pop() is \`string | undefined\`, and the buffer has to stay a string.
-    buffer = lines.pop() ?? ''; // hold the partial line for the next chunk
-    for (const line of lines) {
-      if (!line) continue;
-      const event = JSON.parse(line);
-      const part = event.assistantMessageEvent;
-      if (event.type === 'message_update' && part?.type === 'text_delta') {
-        res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: part.delta } }] })}\\n\\n\`);
-      }
-    }
-  });
-  pi.on('close', () => { res.write('data: [DONE]\\n\\n'); res.end(); });
-});
-
-app.listen(3001, () => console.log('chat api: http://localhost:3001/api/chat'));
-// The front end fetches a RELATIVE /api/chat, so proxy that path to this port
-// from your dev server, or serve both from one origin.`,
-  },
-  streamMapping: "Pi runs as a local stdio process in RPC mode (pi --mode rpc --no-session). It emits newline-delimited JSON events on stdout. Map message_update events where assistantMessageEvent.type === 'text_delta' to data: {choices:[{delta:{content:part.delta}}]} SSE frames; send data: [DONE] on close. Split stdout on \\n (not readline, which breaks on Unicode separators U+2028/U+2029). Pi also emits thinking_delta and toolcall_* events; re-frame them onto delta.reasoning and delta.tool_calls in the same frames. readOpenAIStream from @kitn.ai/ui/wire parses it, including tool calls and reasoning.",
-  runNote: "Pi must be installed locally and available on PATH as 'pi'. No API key is required by the bridge itself; Pi uses its own credentials. Pi runs with full user permissions, so sandbox it before exposing to a public endpoint. See the RPC reference: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md",
-  docsSlug: 'integrations/harnesses',
-  // Nothing. Pi runs with its own credentials, model and tools; the bridge
-  // forwards a prompt, not a model id.
-  forwardsFromClient: [],
-  // `express` only. The bridge's other two imports are excluded by the rule:
-  // `node:child_process` is a builtin and '@kitn.ai/ui/wire' is the kit. Pi
-  // itself is NOT an npm dep of the app — runNote requires it on PATH, and the
-  // route reaches it with spawn('pi'), not an import.
-  deps: { npm: ['express'], pip: [] },
-  // No key anywhere: envVars is empty and Pi uses its own credentials on disk.
-  // This is 'needs-proxy' for the OTHER reason the flag covers — a server-only
-  // capability. The bridge calls spawn(), which no browser can do, and runNote
-  // warns that Pi runs with full user permissions and wants sandboxing before it
-  // is exposed. "No key" is not the same fact as "safe in the browser", and
-  // collapsing the two is exactly how this flag would be got wrong.
-  keyExposure: 'needs-proxy',
-  // Not 'local-server': nothing is listening in advance. The bridge spawns
-  // `pi --mode rpc` per request, so what the developer supplies is an EXECUTABLE
-  // on PATH ("Pi must be installed locally and available on PATH as 'pi'"), and
-  // "start the server first" would be the wrong instruction to print. Pi is not
-  // in `deps` for the same reason — the route reaches it with spawn(), not an
-  // import. The schema's SPAWNS_PROCESS net catches this one independently.
-  outOfBand: 'local-binary',
-};
-
-export default pi;

package/src/agent-tooling/integrations/pydantic-ai.ts

@@ -1,108 +0,0 @@
-import type { Integration } from '../types';
-
-const pydanticAi: Integration = {
-  id: 'pydantic-ai',
-  title: 'Pydantic AI',
-  category: 'framework',
-  language: 'python',
-  streamFormat: 'openai-sse',
-  envVars: ['OPENAI_API_KEY'],
-  routeTemplates: {
-    fastapi: `# main.py
-import json
-from fastapi import FastAPI, HTTPException
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import StreamingResponse
-from pydantic import BaseModel
-from pydantic_ai import Agent
-
-agent = Agent('openai:gpt-4o')
-
-app = FastAPI()
-app.add_middleware(
-    CORSMiddleware, allow_origins=['*'], allow_methods=['*'], allow_headers=['*']
-)
-
-class ContentPart(BaseModel):
-    type: str
-    text: str | None = None
-
-class Message(BaseModel):
-    role: str
-    # A plain string until the turn carries an attachment, at which point the
-    # wire sends an ARRAY of content parts. Declaring this \`str\` alone made a
-    # message with a file a 422 that named pydantic rather than the cause.
-    content: str | list[ContentPart] | None = None
-
-class ChatRequest(BaseModel):
-    messages: list[Message]
-
-def prompt_text(message: Message) -> str:
-    """The text of a turn, refusing what this route cannot carry.
-
-    agent.run_stream() takes a TEXT prompt, so an image or a document has no
-    channel here. Dropping it would send the model a turn that silently lost the
-    user's file; a 400 that names the reason is the honest failure.
-    """
-    if message.content is None:
-        return ''
-    if isinstance(message.content, str):
-        return message.content
-    if any(part.type != 'text' for part in message.content):
-        raise HTTPException(
-            status_code=400,
-            detail='This route forwards a text prompt only and has no channel for an attachment. '
-            'Extract the file content into the message text, or send it through a tool.',
-        )
-    return ''.join(part.text or '' for part in message.content)
-
-async def openai_sse(messages: list[Message]):
-    prompt = prompt_text(messages[-1]) if messages else ''
-    async with agent.run_stream(prompt) as result:
-        async for delta in result.stream_text(delta=True):
-            chunk = {'choices': [{'delta': {'content': delta}}]}
-            yield f'data: {json.dumps(chunk)}\\n\\n'
-    yield 'data: [DONE]\\n\\n'
-
-@app.post('/api/chat')
-async def chat(req: ChatRequest):
-    return StreamingResponse(openai_sse(req.messages), media_type='text/event-stream')`,
-  },
-  streamMapping:
-    "Pydantic AI's agent.run_stream() yields text deltas via result.stream_text(delta=True). Each delta is re-framed as a data: {choices:[{delta:{content}}]} SSE line and the stream closes with data: [DONE]. readOpenAIStream from @kitn.ai/ui/wire parses tool calls and reasoning too, but stream_text() yields text only: iterate the run's events instead and re-frame its tool-call events onto delta.tool_calls to fill kai-tool.",
-  // No install list here: `deps` below is the one, and the scaffolder emits it.
-  // This sentence used to open "Install: pip install pydantic-ai fastapi
-  // uvicorn." — three of the four packages, missing the `pydantic` its own route
-  // imports on the next line.
-  runNote:
-    'Set OPENAI_API_KEY. Run: uvicorn main:app --reload (default port 8000). Point kai-chat at http://localhost:8000/api/chat.',
-  docsSlug: 'integrations/pydantic-ai',
-  // Nothing. Agent('openai:gpt-4o') pins the model and the agent registers its
-  // own tools, both server-side.
-  forwardsFromClient: [],
-  // The only python integration, so the only non-empty `pip`. Three of the four
-  // are the route's own imports (`pydantic_ai` is imported under its module
-  // name and installed under its hyphenated one); `uvicorn` is the ASGI server
-  // the run note starts, which nothing imports and without which the app cannot
-  // run. That asymmetry is why the pip guard checks imports ⊆ declared and not
-  // the reverse.
-  deps: { npm: [], pip: ['pydantic-ai', 'fastapi', 'pydantic', 'uvicorn'] },
-  // Agent('openai:gpt-4o') reads OPENAI_API_KEY inside the python process.
-  //
-  // Worth being precise about, because this one looks like an exception: the
-  // FastAPI app sets CORS to allow_origins=['*'] and the browser fetches it
-  // DIRECTLY on :8000, with no JS proxy in front. That still is not
-  // 'frontend-safe' — the flag asks where the SECRET lives, and it lives in the
-  // python process. The FastAPI service IS the server hop.
-  keyExposure: 'needs-proxy',
-  // The emitted backend is a FastAPI service: a python interpreter, the four
-  // `deps.pip` packages, and `uvicorn main:app` on its own port — none of which a
-  // node toolchain provides or starts. It also needs OPENAI_API_KEY, so this is
-  // the entry that proves the groups are not mutually exclusive: a runtime
-  // prerequisite and a key at once. The prompt should lead with the runtime,
-  // because a key is useless until the service runs. The schema's `language ===
-  // 'python'` net catches this one independently.
-  outOfBand: 'language-runtime',
-};
-
-export default pydanticAi;