arcie 0.1.3 → 0.1.5

package/docs/subagents.md

@@ -0,0 +1,95 @@
+# Subagents
+
+A subagent is a child agent that the orchestrator delegates a focused subtask to.
+Each one runs in its own **fresh, isolated session** — it never sees the parent's
+conversation history. The parent passes everything the child needs through a single
+`message` and gets a result back. This keeps the orchestrator's context small and
+each specialist sharply scoped.
+
+## Two kinds
+
+- **Declared subagents** — specialists you define under `agent/subagents/<id>/`.
+  Use one when the child needs a different prompt, a narrower tool surface, or its
+  own runtime context.
+- **The built-in `agent` tool** — every agent can spawn a copy of itself for a
+  focused subtask. The copy inherits the parent's instructions, tools, and skills,
+  but starts with fresh state.
+
+If the agent can keep its own identity and just needs an optional procedure, reach
+for a skill instead of a subagent.
+
+## Defining a subagent
+
+A subagent is a directory that looks like a small agent:
+
+```
+agent/subagents/researcher/
+├── agent.ts          # required — defineAgent({ model, description })
+├── instructions.md   # optional — the subagent's system prompt
+├── tools/            # optional — the subagent's own tools
+└── skills/           # optional — the subagent's own knowledge
+```
+
+```ts
+// agent/subagents/researcher/agent.ts
+import { defineAgent } from "arcie";
+
+export default defineAgent({
+  model: "claude-sonnet-4-5",
+  description: "Investigate ambiguous questions before the parent agent responds.",
+});
+```
+
+The directory name (`researcher`) becomes the tool name the orchestrator calls.
+
+### `description` is required
+
+Unlike the root agent, a subagent **must** declare a `description` — it's how the
+orchestrator decides when to delegate. Leaving it out is a hard error at load time:
+
+```
+Subagent "researcher" must declare a description in agent.ts
+```
+
+A subagent directory with no `agent.ts` is reported by `arcie dev` / `arcie build` as
+`SUBAGENT_MISSING_CONFIG`.
+
+## Isolation
+
+Declared subagents are isolated. They **inherit nothing** from the parent — absent
+slots fall back to the framework default, not to the root agent's version. If two
+subagents need the same procedure, copy it under each one's `skills/`.
+
+This isolation is deliberate: each delegation spins up its own session, so the
+subagent's work never pollutes the parent's context, and the parent only ever sees
+the subagent's final result.
+
+## How delegation works
+
+The orchestrator perceives subagents as tools. Both declared subagents and the
+built-in `agent` tool expose the same interface:
+
+```ts
+{
+  message: string;        // all the context the child needs (it sees nothing else)
+  outputSchema?: object;  // when set, the child returns structured output
+}
+```
+
+When `outputSchema` is provided, the subagent runs in **task mode** and returns
+structured output as the tool result — which is what makes fan-out / map-reduce
+orchestration possible.
+
+Each delegation emits two control-plane events in the parent's stream:
+
+- `subagent.called` — `{ name, callId, childSessionId, turnId }`
+- `subagent.completed` — `{ name, callId, output }`
+
+## Status
+
+Authoring and loading work today: subagents are discovered, validated (including the
+`description` requirement), and loaded into the agent manifest with their own
+instructions and tools — `arcie build` lists them under `subagents` in the manifest.
+The runtime orchestration loop — the model invoking a subagent, spawning the isolated
+child session, and feeding the result back into the parent turn — is being wired
+through the Cencori Sessions API.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "arcie",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "The electronic line — build agents at the speed of light.",
   "bin": {
-    "eline": "dist/cli/index.js"
+    "arcie": "dist/cli/index.js"
   },
   "files": [
     "dist",
@@ -22,6 +22,7 @@
     "./channels": "./dist/channels/index.js",
     "./schedules": "./dist/schedules/index.js",
     "./context": "./dist/context/index.js",
+    "./memory": "./dist/memory/index.js",
     "./agent": "./dist/agent/index.js",
     "./runner": "./dist/runner/index.js",
     "./auth": "./dist/auth/index.js",
@@ -32,19 +33,21 @@
     "*": {
       "*": [
         "./dist/*/index.d.ts",
+        "./dist/*.d.ts",
         "./dist/index.d.ts"
       ]
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "dev": "tsc --watch",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "keywords": [
-    "eline",
+    "arcie",
     "ai",
     "agent",
     "framework",
@@ -55,10 +58,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cencori/eline.git"
+    "url": "git+https://github.com/cencori/arcie.git"
   },
-  "homepage": "https://cencori.com/eline",
+  "homepage": "https://cencori.com/arcie",
   "dependencies": {
+    "@libsql/client": "^0.17.4",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "ora": "^8.0.1",
@@ -66,8 +70,9 @@
     "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^2.0.0"
+    "@types/node": "^26.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
   }
 }

package/templates/default/.env.local

@@ -0,0 +1,12 @@
+# Cencori AI Gateway
+# CENCORI_API_KEY=
+# CENCORI_PROJECT_ID=
+
+# Or bring your own provider (local dev server needs at least one)
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GROQ_API_KEY=
+# DEEPSEEK_API_KEY=
+# MISTRAL_API_KEY=
+# GOOGLE_API_KEY=
+# TOGETHER_API_KEY=

package/templates/default/agent/agent.ts

@@ -1,9 +1,9 @@
-import { defineAgent } from "eline";
+import { defineAgent } from "arcie";
 
 export default defineAgent({
   model: "claude-sonnet-4-5",
   name: "my-agent",
-  description: "An Eline agent powered by Cencori.",
+  description: "An Arcie agent powered by Cencori.",
   cencori: {
     project: process.env.CENCORI_PROJECT_ID,
     billing: {

package/templates/default/package.json

@@ -4,11 +4,11 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "eline dev",
-    "build": "eline build"
+    "dev": "arcie dev",
+    "build": "arcie build"
   },
   "dependencies": {
-    "eline": "^0.1.2",
+    "arcie": "^0.1.2",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/templates/web-chat/.env.local.example

@@ -0,0 +1,4 @@
+# URL of the arcie dev / production HTTP server. The Next.js server route
+# proxies chat messages to this URL. Keep this server-side only (no NEXT_PUBLIC_
+# prefix) so the browser never talks to arcie directly.
+ARCIE_URL=http://localhost:3000

package/templates/web-chat/README.md

@@ -0,0 +1,51 @@
+# web-chat
+
+A Next.js chat UI for your arcie agent. Talks to arcie's HTTP server through a
+server route so the browser never sees the agent's endpoint directly.
+
+## Setup
+
+```bash
+cp .env.local.example .env.local
+# edit ARCIE_URL if your agent isn't on http://localhost:3000
+
+npm install
+npm run dev
+```
+
+Open http://localhost:3001 in a browser. In another terminal, start your agent:
+
+```bash
+# from the parent agent directory
+arcie dev
+```
+
+## Deploy
+
+```bash
+# Vercel
+npx vercel
+
+# Any Node host
+npm run build && npm start
+```
+
+Set `ARCIE_URL` in the host's environment to point at your deployed agent's
+HTTP endpoint.
+
+## Customize
+
+Everything is yours to edit:
+
+- `app/page.tsx` — the chat page
+- `components/chat.tsx` — the main chat container
+- `components/message.tsx` — user + assistant message bubbles
+- `components/tool-call.tsx` — how tool calls render
+- `app/globals.css` — theme tokens (colors, radius)
+- `tailwind.config.ts` — Tailwind config
+
+Add more shadcn components:
+
+```bash
+npx shadcn@latest add card avatar
+```

package/templates/web-chat/app/api/chat/route.ts

@@ -0,0 +1,43 @@
+import { NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const ARCIE_URL = process.env.ARCIE_URL ?? "http://localhost:3000";
+
+export async function POST(req: NextRequest) {
+  const { message } = (await req.json()) as { message: string };
+  if (typeof message !== "string" || message.length === 0) {
+    return new Response("message required", { status: 400 });
+  }
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(ARCIE_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message, stream: true }),
+    });
+  } catch (error) {
+    return Response.json(
+      {
+        error: "Could not reach arcie server",
+        detail: error instanceof Error ? error.message : String(error),
+        hint: `Is arcie running at ${ARCIE_URL}? Start it with \`arcie dev\` in the agent directory.`,
+      },
+      { status: 502 },
+    );
+  }
+
+  if (!upstream.ok || upstream.body === null) {
+    return new Response(await upstream.text(), { status: upstream.status });
+  }
+
+  return new Response(upstream.body, {
+    headers: {
+      "Content-Type": "application/x-ndjson",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    },
+  });
+}

package/templates/web-chat/app/globals.css

@@ -0,0 +1,55 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240 10% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 3.9%;
+    --primary: 240 5.9% 10%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 240 4.8% 95.9%;
+    --secondary-foreground: 240 5.9% 10%;
+    --muted: 240 4.8% 95.9%;
+    --muted-foreground: 240 3.8% 46.1%;
+    --accent: 240 4.8% 95.9%;
+    --accent-foreground: 240 5.9% 10%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 240 5.9% 10%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 240 10% 3.9%;
+    --foreground: 0 0% 98%;
+    --card: 240 10% 3.9%;
+    --card-foreground: 0 0% 98%;
+    --primary: 0 0% 98%;
+    --primary-foreground: 240 5.9% 10%;
+    --secondary: 240 3.7% 15.9%;
+    --secondary-foreground: 0 0% 98%;
+    --muted: 240 3.7% 15.9%;
+    --muted-foreground: 240 5% 64.9%;
+    --accent: 240 3.7% 15.9%;
+    --accent-foreground: 0 0% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 3.7% 15.9%;
+    --input: 240 3.7% 15.9%;
+    --ring: 240 4.9% 83.9%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground antialiased;
+  }
+}

package/templates/web-chat/app/layout.tsx

@@ -0,0 +1,15 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "arcie",
+  description: "Chat with your arcie agent.",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className="h-full">
+      <body className="h-full">{children}</body>
+    </html>
+  );
+}

package/templates/web-chat/app/page.tsx

@@ -0,0 +1,9 @@
+import { Chat } from "@/components/chat";
+
+export default function Page() {
+  return (
+    <main className="flex h-full flex-col">
+      <Chat />
+    </main>
+  );
+}

package/templates/web-chat/components/chat.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import * as React from "react";
+import { Zap } from "lucide-react";
+import { InputBar } from "@/components/input-bar";
+import { Message } from "@/components/message";
+import { readArcieStream } from "@/lib/stream";
+import type { UiMessage, UiToolCall } from "@/lib/types";
+import { cn } from "@/lib/utils";
+
+function newId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function Chat() {
+  const [messages, setMessages] = React.useState<UiMessage[]>([]);
+  const [streaming, setStreaming] = React.useState(false);
+  const abortRef = React.useRef<AbortController | undefined>(undefined);
+  const bottomRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
+  }, [messages]);
+
+  const stop = () => {
+    abortRef.current?.abort();
+    setStreaming(false);
+  };
+
+  const send = async (text: string) => {
+    const userMessage: UiMessage = { id: newId("u"), role: "user", content: text };
+    const assistantId = newId("a");
+    const assistantMessage: UiMessage = {
+      id: assistantId,
+      role: "assistant",
+      content: "",
+      streaming: true,
+      toolCalls: [],
+    };
+    setMessages((prev) => [...prev, userMessage, assistantMessage]);
+    setStreaming(true);
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    const updateAssistant = (patch: (prev: UiMessage) => UiMessage) => {
+      setMessages((prev) =>
+        prev.map((message) => (message.id === assistantId ? patch(message) : message)),
+      );
+    };
+
+    try {
+      const response = await fetch("/api/chat", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: text }),
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        updateAssistant((m) => ({
+          ...m,
+          content: errorBody || `Server error (${response.status})`,
+          streaming: false,
+          errored: true,
+        }));
+        return;
+      }
+
+      const toolIndex = new Map<string, number>();
+
+      for await (const event of readArcieStream(response)) {
+        switch (event.type) {
+          case "message.appended": {
+            const delta = (event.data as { delta?: string }).delta ?? "";
+            updateAssistant((m) => ({ ...m, content: `${m.content}${delta}` }));
+            break;
+          }
+          case "message.completed": {
+            const text = (event.data as { text?: string | null }).text;
+            updateAssistant((m) => ({
+              ...m,
+              content: typeof text === "string" && text.length > 0 ? text : m.content,
+            }));
+            break;
+          }
+          case "reasoning.appended": {
+            const delta = (event.data as { delta?: string }).delta ?? "";
+            updateAssistant((m) => ({ ...m, reasoning: `${m.reasoning ?? ""}${delta}` }));
+            break;
+          }
+          case "tool.started": {
+            const data = event.data as { name: string; callId: string; input: unknown };
+            const call: UiToolCall = {
+              callId: data.callId,
+              name: data.name,
+              input: data.input,
+              status: "running",
+            };
+            updateAssistant((m) => {
+              const toolCalls = m.toolCalls ?? [];
+              toolIndex.set(data.callId, toolCalls.length);
+              return { ...m, toolCalls: [...toolCalls, call] };
+            });
+            break;
+          }
+          case "tool.completed": {
+            const data = event.data as {
+              callId: string;
+              output: unknown;
+              status: string;
+              error?: { code: string; message: string };
+            };
+            updateAssistant((m) => {
+              const toolCalls = [...(m.toolCalls ?? [])];
+              const idx = toolIndex.get(data.callId);
+              if (idx === undefined || toolCalls[idx] === undefined) return m;
+              const previous = toolCalls[idx];
+              const isApproval =
+                data.status === "pending" && data.error?.code === "needs_approval";
+              toolCalls[idx] = {
+                ...previous,
+                status: isApproval
+                  ? "approval"
+                  : data.status === "completed"
+                    ? "done"
+                    : "error",
+                output: data.output,
+                errorMessage: data.error?.message,
+              };
+              return { ...m, toolCalls };
+            });
+            break;
+          }
+          case "step.failed":
+          case "turn.failed":
+          case "session.failed": {
+            const data = event.data as { code?: string; message?: string };
+            updateAssistant((m) => ({
+              ...m,
+              content: data.message ?? "Something went wrong.",
+              streaming: false,
+              errored: true,
+            }));
+            break;
+          }
+        }
+      }
+    } catch (error) {
+      if (controller.signal.aborted) {
+        updateAssistant((m) => ({ ...m, streaming: false }));
+      } else {
+        updateAssistant((m) => ({
+          ...m,
+          content: error instanceof Error ? error.message : String(error),
+          streaming: false,
+          errored: true,
+        }));
+      }
+    } finally {
+      updateAssistant((m) => ({ ...m, streaming: false }));
+      setStreaming(false);
+      abortRef.current = undefined;
+    }
+  };
+
+  return (
+    <div className="flex h-full flex-col">
+      <header className="flex items-center gap-2 border-b border-border px-4 py-3">
+        <Zap className="h-5 w-5 text-amber-500" />
+        <span className="font-semibold">arcie</span>
+        <span className="text-xs text-muted-foreground">web chat</span>
+      </header>
+      <div className="flex-1 overflow-y-auto">
+        <div className="mx-auto flex max-w-3xl flex-col gap-3 px-4 py-6">
+          {messages.length === 0 && <EmptyState />}
+          {messages.map((message) => (
+            <Message key={message.id} message={message} />
+          ))}
+          <div ref={bottomRef} />
+        </div>
+      </div>
+      <InputBar onSend={send} onStop={stop} streaming={streaming} />
+    </div>
+  );
+}
+
+function EmptyState() {
+  return (
+    <div className={cn("mt-24 flex flex-col items-center gap-2 text-center text-muted-foreground")}>
+      <Zap className="h-8 w-8 text-amber-500" />
+      <div className="text-lg font-medium text-foreground">Start a conversation</div>
+      <div className="text-sm">Ask your arcie agent anything.</div>
+    </div>
+  );
+}

package/templates/web-chat/components/input-bar.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import * as React from "react";
+import { Send, StopCircle } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+interface InputBarProps {
+  onSend(message: string): void;
+  onStop(): void;
+  streaming: boolean;
+  disabled?: boolean;
+}
+
+export function InputBar({ onSend, onStop, streaming, disabled }: InputBarProps) {
+  const [value, setValue] = React.useState("");
+  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
+
+  const submit = () => {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || streaming || disabled) return;
+    onSend(trimmed);
+    setValue("");
+  };
+
+  const onKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
+      submit();
+    }
+  };
+
+  React.useEffect(() => {
+    const el = textareaRef.current;
+    if (el === null) return;
+    el.style.height = "auto";
+    el.style.height = `${Math.min(el.scrollHeight, 200)}px`;
+  }, [value]);
+
+  return (
+    <div className="border-t border-border bg-background px-4 py-3">
+      <div className="mx-auto flex max-w-3xl items-end gap-2">
+        <textarea
+          ref={textareaRef}
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+          onKeyDown={onKeyDown}
+          rows={1}
+          placeholder={streaming ? "…" : "Send a message"}
+          disabled={disabled}
+          className={cn(
+            "flex-1 resize-none rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+            "disabled:cursor-not-allowed disabled:opacity-50",
+          )}
+        />
+        {streaming ? (
+          <Button size="icon" variant="outline" onClick={onStop} aria-label="Stop">
+            <StopCircle className="h-4 w-4" />
+          </Button>
+        ) : (
+          <Button
+            size="icon"
+            onClick={submit}
+            disabled={value.trim().length === 0 || disabled}
+            aria-label="Send"
+          >
+            <Send className="h-4 w-4" />
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}