@codespring-app/use-agent 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# `@codespring-app/use-agent`
+
+The supported server and React SDK for CodeSpring Agents. It speaks a versioned
+HTTP protocol and contains no Cloudflare runtime implementation, so the same
+application can target CodeSpring-hosted or self-hosted endpoints.
+
+![An agent built with the use-agent React SDK](./docs/screenshots/default-agent.png)
+
+## Server
+
+```ts
+import { createAgent, createClient } from "@codespring-app/use-agent";
+
+const support = createAgent({
+  id: "support",
+  revision: "7",
+  instructions: "Help the customer clearly and safely.",
+  model: "production-default",
+  skills: [{ id: "returns", version: "1" }],
+});
+
+const agents = createClient({
+  endpoint: process.env.CODESPRING_AGENTS_ENDPOINT!,
+  apiKey: process.env.CODESPRING_AGENTS_API_KEY!,
+});
+
+const session = await agents.sessions.create(support);
+await session.submit("Where is my order?", { idempotencyKey: crypto.randomUUID() });
+```
+
+`production-default` is a reusable, tenant-scoped virtual model profile—not a
+provider model name and not an agent/use-case configuration. Multiple agents can
+reference it. The control plane maps it to encrypted BYOK connections, provider
+candidates, fallback, budgets, and policy. Publishing resolves the profile to an
+immutable policy revision while credential rotation remains independent.
+
+API keys are server-only. Do not pass the server client into a browser bundle.
+
+## Plug-and-play React UI
+
+```tsx
+import {
+  AgentChat,
+  AgentProvider,
+  createAgentAppearance,
+  createAgentClient,
+} from "@codespring-app/use-agent/react";
+
+const agentClient = createAgentClient({
+  endpoint: "https://api.agents.codespring.app/browser",
+  clientTokenEndpoint: "/api/agents/token",
+});
+
+const acmeAppearance = createAgentAppearance({
+  theme: { accent: "#2856D8" },
+  copy: { placeholder: "Ask us anything" },
+});
+
+export function App({ sessionId }: { sessionId: string }) {
+  return (
+    <AgentProvider client={agentClient} appearance={acmeAppearance}>
+      <AgentChat sessionId={sessionId} />
+    </AgentProvider>
+  );
+}
+```
+
+`/api/agents/token` returns `{ token, expiresAt }`. The SDK caches it in memory,
+deduplicates concurrent refreshes, refreshes before expiry, and retries once
+after a 401. It never persists the token. `createAgentAppearance` produces a
+frozen, reusable preset so unrelated renders do not invalidate theme/copy
+consumers; use `useMemo` when appearance must be dynamic.
+
+The `/browser` endpoint is intentional: it accepts only short-lived client
+tokens and is the only runtime surface with browser CORS. Server API keys stay
+on the endpoint root and must never be shipped to a browser.
+
+The default Paper experience renders assistant replies as document content on
+an edge-to-edge canvas, user messages as quiet trailing wells, tool calls as
+compact inspectable activity rows, and the live-edge composer without a shadow.
+`paperLightTheme`, `paperDarkTheme`, theme/copy overrides, slots, and render
+functions are available for customization.
+
+## CSS variables, Tailwind CSS, and StyleX
+
+Every default component resolves theme tokens through inherited
+`--codespring-agent-*` custom properties. Variables override the appearance
+preset; unset variables use the selected Paper or custom appearance value as a
+fallback.
+
+```css
+.acme-agent-theme {
+  --codespring-agent-accent: #2856d8;
+  --codespring-agent-container-radius: 18px;
+  --codespring-agent-content-max-width: 52rem;
+}
+```
+
+The public names are also exported as `agentThemeVariables`. Supported tokens
+are `canvas`, `ink`, `inkSecondary`, `inkTertiary`, `well`, `hairline`,
+`statusGood`, `statusBad`, `statusWarn`, `accent`, `fontFamily`, `monoFamily`,
+`contentMaxWidth`, `containerRadius`, and `wellRadius`.
+
+Tailwind CSS can set the variables on any ancestor:
+
+```css
+@theme {
+  --color-acme-primary: #2856d8;
+}
+```
+
+```tsx
+<div className="[--codespring-agent-accent:var(--color-acme-primary)] [--codespring-agent-container-radius:18px]">
+  <AgentProvider client={agentClient} appearance={acmeAppearance}>
+    <AgentChat sessionId={sessionId} />
+  </AgentProvider>
+</div>
+```
+
+StyleX variables can be used as appearance values and themed from an ancestor:
+
+```tsx
+// agent-theme.stylex.ts
+import * as stylex from "@stylexjs/stylex";
+
+export const agentTokens = stylex.defineVars({ accent: "#3B6AC5" });
+```
+
+```tsx
+import * as stylex from "@stylexjs/stylex";
+import { agentTokens } from "./agent-theme.stylex";
+
+const brandedTheme = stylex.createTheme(agentTokens, { accent: "#2856D8" });
+const stylexAppearance = createAgentAppearance({
+  theme: { accent: agentTokens.accent },
+});
+
+<div {...stylex.props(brandedTheme)}>
+  <AgentProvider client={agentClient} appearance={stylexAppearance}>
+    <AgentChat sessionId={sessionId} />
+  </AgentProvider>
+</div>;
+```
+
+## Headless React
+
+Advanced clients can use `useAgentSession`, `useAgentMessages`,
+`useAgentToolCalls`, `useAgentClient`, `useAgentTheme`, and `useAgentCopy` to
+build a completely custom interface. The composable `AgentMessageList`,
+`AgentMessage`, `AgentToolCall`, and `AgentComposer` primitives can also be
+mixed with client-owned components.
+
+The browser entrypoint never accepts an API key. A trusted application backend
+must issue short-lived, origin-bound client tokens.
+
+## Local showcase
+
+```sh
+bun run showcase
+```
+
+Open `http://127.0.0.1:5173` for the Paper UI or append `?theme=dark` for
+the dark palette. The showcase uses mocked durable events and makes no
+external API calls.

package/dist/chunk-FAD2XMPA.js

@@ -0,0 +1,220 @@
+// src/client.ts
+var AgentError = class extends Error {
+  constructor(message, status, code, requestId, details) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.details = details;
+    this.name = "AgentError";
+  }
+  status;
+  code;
+  requestId;
+  details;
+};
+var Transport = class {
+  constructor(options) {
+    this.options = options;
+    this.endpoint = normalizeEndpoint(options.endpoint);
+    this.fetchImplementation = options.fetch ?? globalThis.fetch;
+    if (!this.fetchImplementation) throw new TypeError("A fetch implementation is required");
+  }
+  options;
+  endpoint;
+  fetchImplementation;
+  async request(path, init = {}) {
+    let response = await this.fetchWithToken(path, init);
+    if (response.status === 401 && this.options.token.invalidate()) {
+      response = await this.fetchWithToken(path, init);
+    }
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    const payload = await readJson(response);
+    if (!response.ok) {
+      const error = isObject(payload) && isObject(payload.error) ? payload.error : void 0;
+      throw new AgentError(
+        typeof error?.message === "string" ? error.message : `Use Agent request failed with ${response.status}`,
+        response.status,
+        typeof error?.code === "string" ? error.code : "request_failed",
+        requestId,
+        error?.details
+      );
+    }
+    return payload;
+  }
+  async fetchWithToken(path, init) {
+    const headers = new Headers(init.headers);
+    headers.set("Accept", "application/json");
+    headers.set("Authorization", `Bearer ${await this.options.token.get()}`);
+    if (init.body !== void 0) headers.set("Content-Type", "application/json");
+    return this.fetchImplementation(`${this.endpoint}${path}`, { ...init, headers });
+  }
+};
+function jwtExpiry(token) {
+  const encoded = token.split(".")[1];
+  if (!encoded || typeof globalThis.atob !== "function") return void 0;
+  try {
+    const normalized = encoded.replace(/-/gu, "+").replace(/_/gu, "/");
+    const payload = JSON.parse(globalThis.atob(normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=")));
+    return typeof payload.exp === "number" ? payload.exp * 1e3 : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function explicitExpiry(value) {
+  if (typeof value === "number") return value < 1e12 ? value * 1e3 : value;
+  if (typeof value !== "string") return void 0;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+var CachedTokenProvider = class {
+  constructor(load, fallbackTtlMs, refreshSkewMs) {
+    this.load = load;
+    this.fallbackTtlMs = fallbackTtlMs;
+    this.refreshSkewMs = refreshSkewMs;
+  }
+  load;
+  fallbackTtlMs;
+  refreshSkewMs;
+  cached;
+  inFlight;
+  get = async () => {
+    if (this.cached && Date.now() < this.cached.refreshAt) return this.cached.token;
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.refresh();
+    try {
+      return await this.inFlight;
+    } finally {
+      this.inFlight = void 0;
+    }
+  };
+  invalidate = () => {
+    this.cached = void 0;
+    return true;
+  };
+  async refresh() {
+    const loaded = await this.load();
+    const token = typeof loaded === "string" ? loaded : loaded.token;
+    if (!token.trim()) throw new TypeError("getClientToken returned an empty token");
+    const now = Date.now();
+    const expiry = (typeof loaded === "string" ? void 0 : explicitExpiry(loaded.expiresAt)) ?? jwtExpiry(token) ?? now + this.fallbackTtlMs;
+    const lifetime = Math.max(1e3, expiry - now);
+    this.cached = {
+      token,
+      refreshAt: expiry - Math.min(this.refreshSkewMs, Math.max(500, lifetime / 2))
+    };
+    return token;
+  }
+};
+var staticTokenProvider = (token) => ({
+  get: async () => token,
+  invalidate: () => false
+});
+var isObject = (value) => value !== null && typeof value === "object";
+async function readJson(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) {
+    if (!response.ok) return void 0;
+    throw new AgentError("Runtime returned a non-JSON response", response.status, "invalid_response");
+  }
+  return response.json();
+}
+function normalizeEndpoint(endpoint) {
+  const parsed = new URL(endpoint);
+  if (parsed.protocol !== "https:" && parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
+    throw new TypeError("endpoint must use HTTPS outside local development");
+  }
+  parsed.pathname = parsed.pathname.replace(/\/$/u, "");
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.toString().replace(/\/$/u, "");
+}
+var randomIdempotencyKey = () => {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  throw new Error("crypto.randomUUID is required when no idempotency key is supplied");
+};
+var AgentSession = class {
+  constructor(transport, id) {
+    this.transport = transport;
+    this.id = id;
+  }
+  transport;
+  id;
+  get(options = {}) {
+    return this.transport.request(`/v1/sessions/${encodeURIComponent(this.id)}`, {
+      ...options.signal === void 0 ? {} : { signal: options.signal }
+    });
+  }
+  submit(content, options = {}) {
+    const idempotencyKey = options.idempotencyKey ?? randomIdempotencyKey();
+    return this.transport.request(`/v1/sessions/${encodeURIComponent(this.id)}/turns`, {
+      method: "POST",
+      headers: { "Idempotency-Key": idempotencyKey },
+      body: JSON.stringify({ content }),
+      ...options.signal === void 0 ? {} : { signal: options.signal }
+    });
+  }
+  events(after = 0, limit = 100, options = {}) {
+    const query = new URLSearchParams({ after: String(after), limit: String(limit) });
+    return this.transport.request(`/v1/sessions/${encodeURIComponent(this.id)}/events?${query}`, {
+      ...options.signal === void 0 ? {} : { signal: options.signal }
+    });
+  }
+  async cancel(turnId, options = {}) {
+    return this.transport.request(
+      `/v1/sessions/${encodeURIComponent(this.id)}/turns/${encodeURIComponent(turnId)}/cancel`,
+      {
+        method: "POST",
+        ...options.signal === void 0 ? {} : { signal: options.signal }
+      }
+    );
+  }
+};
+var AgentClient = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  sessions = {
+    create: async (agent, options = {}) => {
+      const created = await this.transport.request("/v1/sessions", {
+        method: "POST",
+        body: JSON.stringify({ agentRevisionId: agent.revisionId }),
+        ...options.signal === void 0 ? {} : { signal: options.signal }
+      });
+      return new AgentSession(this.transport, created.sessionId);
+    },
+    get: (sessionId) => new AgentSession(this.transport, sessionId)
+  };
+};
+function createClient(options) {
+  if (!options.apiKey.trim()) throw new TypeError("apiKey is required");
+  return new AgentClient(
+    new Transport({
+      endpoint: options.endpoint,
+      token: staticTokenProvider(options.apiKey),
+      ...options.fetch === void 0 ? {} : { fetch: options.fetch }
+    })
+  );
+}
+function createBrowserClient(options) {
+  return new AgentClient(
+    new Transport({
+      endpoint: options.endpoint,
+      token: new CachedTokenProvider(
+        options.getClientToken,
+        options.clientTokenTtlMs ?? 6e4,
+        options.refreshSkewMs ?? 3e4
+      ),
+      ...options.fetch === void 0 ? {} : { fetch: options.fetch }
+    })
+  );
+}
+
+export {
+  AgentError,
+  AgentSession,
+  AgentClient,
+  createClient,
+  createBrowserClient
+};

package/dist/client-Bz3eVQXx.d.ts

@@ -0,0 +1,156 @@
+type TurnStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+interface AgentEvent {
+    schemaVersion: 1;
+    id: number;
+    sessionId: string;
+    turnId?: string;
+    attempt: number;
+    type: string;
+    createdAt: string;
+    data: unknown;
+}
+interface SessionSnapshot {
+    sessionId: string;
+    agentRevisionId: string;
+    createdAt: string;
+    updatedAt: string;
+    cursor: number;
+    turns: Array<{
+        id: string;
+        status: TurnStatus;
+        attempt: number;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+}
+interface CreateSessionResponse {
+    sessionId: string;
+    agentRevisionId: string;
+    createdAt: string;
+}
+interface SubmitTurnResponse {
+    sessionId: string;
+    turnId: string;
+    status: TurnStatus;
+    cursor: number;
+    duplicate: boolean;
+}
+interface ListEventsResponse {
+    events: AgentEvent[];
+    cursor: number;
+    hasMore: boolean;
+}
+/** Tenant-scoped model profile configured in the CodeSpring control plane. */
+type ModelProfileId = string;
+interface AgentToolReference {
+    name: string;
+    description?: string;
+}
+interface AgentMcpServerReference {
+    id: string;
+    allowedTools?: string[];
+}
+interface AgentSkillReference {
+    id: string;
+    version?: string;
+}
+interface AgentDefinition {
+    readonly id: string;
+    readonly revision: string;
+    readonly revisionId: string;
+    readonly instructions?: string;
+    readonly model?: ModelProfileId;
+    readonly tools: readonly AgentToolReference[];
+    readonly mcpServers: readonly AgentMcpServerReference[];
+    readonly skills: readonly AgentSkillReference[];
+    readonly metadata: Readonly<Record<string, string>>;
+}
+interface CreateAgentOptions {
+    id: string;
+    revision: string;
+    instructions?: string;
+    model?: ModelProfileId;
+    tools?: AgentToolReference[];
+    mcpServers?: AgentMcpServerReference[];
+    skills?: AgentSkillReference[];
+    metadata?: Record<string, string>;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+interface SubmitOptions extends RequestOptions {
+    idempotencyKey?: string;
+}
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+interface AgentClientOptions {
+    endpoint: string;
+    apiKey: string;
+    fetch?: FetchLike;
+}
+interface BrowserAgentClientOptions {
+    endpoint: string;
+    getClientToken: () => Promise<ClientTokenResult>;
+    /** Fallback lifetime for opaque legacy tokens without an expiry. Defaults to 60 seconds. */
+    clientTokenTtlMs?: number;
+    /** Refresh before expiry. Defaults to 30 seconds and is bounded for short tokens. */
+    refreshSkewMs?: number;
+    fetch?: FetchLike;
+}
+type ClientTokenResult = string | {
+    token: string;
+    /** ISO timestamp or Unix time in seconds/milliseconds. */
+    expiresAt?: string | number;
+};
+
+declare class AgentError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status: number, code: string, requestId?: string | undefined, details?: unknown | undefined);
+}
+interface TokenProvider {
+    get: () => Promise<string>;
+    invalidate: () => boolean;
+}
+interface TransportOptions {
+    endpoint: string;
+    token: TokenProvider;
+    fetch?: FetchLike;
+}
+declare class Transport {
+    private readonly options;
+    readonly endpoint: string;
+    readonly fetchImplementation: FetchLike;
+    constructor(options: TransportOptions);
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+    private fetchWithToken;
+}
+declare class AgentSession {
+    private readonly transport;
+    readonly id: string;
+    constructor(transport: Transport, id: string);
+    get(options?: RequestOptions): Promise<SessionSnapshot>;
+    submit(content: string, options?: SubmitOptions): Promise<SubmitTurnResponse>;
+    events(after?: number, limit?: number, options?: RequestOptions): Promise<ListEventsResponse>;
+    cancel(turnId: string, options?: RequestOptions): Promise<TurnStatusResponse>;
+}
+interface TurnStatusResponse {
+    sessionId: string;
+    turnId: string;
+    status: string;
+}
+declare class AgentClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    readonly sessions: {
+        create: (agent: AgentDefinition, options?: RequestOptions) => Promise<AgentSession>;
+        get: (sessionId: string) => AgentSession;
+    };
+}
+/** Server entrypoint. Never pass this client or its API key into a browser bundle. */
+declare function createClient(options: AgentClientOptions): AgentClient;
+/** Browser-safe client used by the React subpath with short-lived client tokens. */
+declare function createBrowserClient(options: BrowserAgentClientOptions): AgentClient;
+
+export { type AgentDefinition as A, type BrowserAgentClientOptions as B, type CreateAgentOptions as C, type FetchLike as F, type ListEventsResponse as L, type ModelProfileId as M, type RequestOptions as R, type SessionSnapshot as S, type TurnStatus as T, AgentClient as a, type AgentClientOptions as b, AgentError as c, type AgentEvent as d, type AgentMcpServerReference as e, AgentSession as f, type AgentSkillReference as g, type AgentToolReference as h, type ClientTokenResult as i, type CreateSessionResponse as j, type SubmitOptions as k, type SubmitTurnResponse as l, createBrowserClient as m, createClient as n };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { C as CreateAgentOptions, A as AgentDefinition } from './client-Bz3eVQXx.js';
+export { a as AgentClient, b as AgentClientOptions, c as AgentError, d as AgentEvent, e as AgentMcpServerReference, f as AgentSession, g as AgentSkillReference, h as AgentToolReference, B as BrowserAgentClientOptions, i as ClientTokenResult, j as CreateSessionResponse, F as FetchLike, L as ListEventsResponse, M as ModelProfileId, R as RequestOptions, S as SessionSnapshot, k as SubmitOptions, l as SubmitTurnResponse, T as TurnStatus, m as createBrowserClient, n as createClient } from './client-Bz3eVQXx.js';
+
+/** Defines a portable agent revision without importing runtime implementation code. */
+declare function createAgent(options: CreateAgentOptions): AgentDefinition;
+
+export { AgentDefinition, CreateAgentOptions, createAgent };

package/dist/index.js

@@ -0,0 +1,48 @@
+import {
+  AgentClient,
+  AgentError,
+  AgentSession,
+  createBrowserClient,
+  createClient
+} from "./chunk-FAD2XMPA.js";
+
+// src/agent.ts
+var identifierPattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u;
+function requireIdentifier(value, name) {
+  const normalized = value.trim();
+  if (!identifierPattern.test(normalized)) {
+    throw new TypeError(`${name} must match ${identifierPattern.source}`);
+  }
+  return normalized;
+}
+function uniqueNames(values, name) {
+  const normalized = values.map((value) => value.name.trim());
+  if (new Set(normalized).size !== normalized.length) {
+    throw new TypeError(`${name} names must be unique`);
+  }
+}
+function createAgent(options) {
+  const id = requireIdentifier(options.id, "id");
+  const revision = requireIdentifier(options.revision, "revision");
+  const tools = (options.tools ?? []).map((tool) => ({ ...tool, name: tool.name.trim() }));
+  uniqueNames(tools, "tool");
+  return Object.freeze({
+    id,
+    revision,
+    revisionId: `${id}@${revision}`,
+    ...options.instructions === void 0 ? {} : { instructions: options.instructions },
+    ...options.model === void 0 ? {} : { model: requireIdentifier(options.model, "model") },
+    tools: Object.freeze(tools.map((tool) => Object.freeze(tool))),
+    mcpServers: Object.freeze((options.mcpServers ?? []).map((server) => Object.freeze({ ...server }))),
+    skills: Object.freeze((options.skills ?? []).map((skill) => Object.freeze({ ...skill }))),
+    metadata: Object.freeze({ ...options.metadata ?? {} })
+  });
+}
+export {
+  AgentClient,
+  AgentError,
+  AgentSession,
+  createAgent,
+  createBrowserClient,
+  createClient
+};