@strand-js/core 0.1.0 → 0.1.2

package/dist/index.mjs

@@ -0,0 +1,477 @@
+// src/context-window.ts
+function estimateTokens(msg) {
+  return Math.max(1, Math.ceil(msg.content.length / 4));
+}
+function applyContextWindow(messages, config) {
+  if (!messages.length) return [];
+  if (!config.maxTokens || config.strategy === "none") return messages;
+  if (config.strategy === "truncate-oldest") {
+    return truncateOldest(messages, config.maxTokens);
+  }
+  if (config.strategy === "sliding-window") {
+    return slidingWindow(messages, config.maxTokens);
+  }
+  return messages;
+}
+function truncateOldest(messages, maxTokens) {
+  let total = messages.reduce((sum, m) => sum + estimateTokens(m), 0);
+  let start = 0;
+  while (total > maxTokens && start < messages.length - 1) {
+    total -= estimateTokens(messages[start]);
+    start++;
+  }
+  return messages.slice(start);
+}
+function slidingWindow(messages, maxTokens) {
+  const result = [];
+  let total = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const tokens = estimateTokens(messages[i]);
+    if (total + tokens > maxTokens && result.length > 0) break;
+    result.unshift(messages[i]);
+    total += tokens;
+  }
+  return result;
+}
+
+// src/retry.ts
+var StrandError = class extends Error {
+  constructor(status, message, code) {
+    super(message);
+    this.name = "StrandError";
+    this.status = status;
+    this.code = code;
+  }
+};
+function isRetryable(error, retryOn) {
+  if (!(error instanceof StrandError)) return false;
+  return retryOn.includes(error.code);
+}
+function getDelay(backoff, attempt) {
+  const base = 1e3;
+  if (backoff === "none") return 0;
+  if (backoff === "linear") return base;
+  return base * Math.pow(2, attempt);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, config) {
+  const maxAttempts = config.maxAttempts ?? 3;
+  const backoff = config.backoff ?? "exponential";
+  const retryOn = config.retryOn ?? ["rate_limit", "server_error"];
+  let lastError;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (!isRetryable(error, retryOn)) throw error;
+      if (attempt === maxAttempts - 1) throw error;
+      const delay = getDelay(backoff, attempt);
+      if (delay > 0) await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+
+// src/stream.ts
+var KNOWN_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "strand:start",
+  "strand:text-delta",
+  "strand:tool-start",
+  "strand:tool-input-delta",
+  "strand:tool-input-done",
+  "strand:tool-result",
+  "strand:tool-error",
+  "strand:done",
+  "strand:error"
+]);
+function parseSSEBuffer(buffer) {
+  const messages = buffer.split("\n\n");
+  const rest = messages.pop() ?? "";
+  const events = [];
+  for (const message of messages) {
+    if (!message.trim()) continue;
+    let event = "";
+    let data = "";
+    for (const line of message.split("\n")) {
+      if (line.startsWith("event: ")) event = line.slice(7).trim();
+      else if (line.startsWith("data: ")) data = line.slice(6);
+    }
+    if (event && data) events.push({ event, data });
+  }
+  return { events, rest };
+}
+async function* parseSSEStream(body, signal) {
+  const decoder = new TextDecoder();
+  const reader = body.getReader();
+  let buffer = "";
+  try {
+    while (true) {
+      if (signal?.aborted) break;
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const { events: events2, rest } = parseSSEBuffer(buffer);
+      buffer = rest;
+      for (const { event, data } of events2) {
+        if (!KNOWN_EVENT_TYPES.has(event)) continue;
+        try {
+          const parsed = JSON.parse(data);
+          yield { type: event, ...parsed };
+        } catch {
+        }
+      }
+    }
+    buffer += decoder.decode();
+    const { events } = parseSSEBuffer(buffer + "\n\n");
+    for (const { event, data } of events) {
+      if (!KNOWN_EVENT_TYPES.has(event)) continue;
+      try {
+        const parsed = JSON.parse(data);
+        yield { type: event, ...parsed };
+      } catch {
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/client.ts
+var StrandClientImpl = class {
+  constructor(config) {
+    this.config = {
+      baseUrl: config.baseUrl.replace(/\/$/, ""),
+      retry: {
+        maxAttempts: config.retry?.maxAttempts ?? 3,
+        backoff: config.retry?.backoff ?? "exponential",
+        retryOn: config.retry?.retryOn ?? ["rate_limit", "server_error"]
+      },
+      contextWindow: {
+        strategy: config.contextWindow?.strategy ?? "truncate-oldest",
+        maxTokens: config.contextWindow?.maxTokens ?? 1e5
+      }
+    };
+  }
+  async *send(messages, options = {}) {
+    const { signal, context } = options;
+    const windowedMessages = applyContextWindow(messages, this.config.contextWindow);
+    const body = JSON.stringify({
+      messages: windowedMessages.map((m) => ({ role: m.role, content: m.content })),
+      ...context ? { context } : {}
+    });
+    const response = await withRetry(
+      () => fetch(this.config.baseUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/event-stream"
+        },
+        body,
+        signal
+      }),
+      this.config.retry
+    );
+    if (!response.ok) {
+      const text = await response.text().catch(() => response.statusText);
+      const code = response.status === 429 ? "rate_limit" : "server_error";
+      throw new StrandError(response.status, text, code);
+    }
+    if (!response.body) {
+      throw new StrandError(0, "Response body is null", "server_error");
+    }
+    yield* parseSSEStream(response.body, signal);
+  }
+};
+function createStrandClient(config) {
+  if (!config.baseUrl) throw new Error("[strand] createStrandClient: baseUrl is required");
+  return new StrandClientImpl(config);
+}
+
+// src/tool.ts
+function tool(definition) {
+  if (!definition.name) throw new Error("[strand] tool: name is required");
+  if (!definition.description) throw new Error("[strand] tool: description is required");
+  if (!definition.parameters) throw new Error("[strand] tool: parameters schema is required");
+  return definition;
+}
+
+// src/session.ts
+var SessionStateMachine = class {
+  constructor(sessionId) {
+    this._listeners = /* @__PURE__ */ new Set();
+    this._resetTimer = null;
+    this._session = makeInitialSession(sessionId ?? generateId());
+  }
+  get session() {
+    return this._session;
+  }
+  subscribe(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+  emit() {
+    this._listeners.forEach((l) => l(this._session));
+  }
+  transition(status, error) {
+    if (this._resetTimer !== null) {
+      clearTimeout(this._resetTimer);
+      this._resetTimer = null;
+    }
+    this._session = { ...this._session, status, error: error ?? null };
+    this.emit();
+    if (status === "done" || status === "error") {
+      this._resetTimer = setTimeout(() => {
+        this._session = { ...this._session, status: "idle" };
+        this._resetTimer = null;
+        this.emit();
+      }, 0);
+    }
+  }
+  addUserMessage(content) {
+    const msg = {
+      id: generateId(),
+      role: "user",
+      content,
+      createdAt: /* @__PURE__ */ new Date()
+    };
+    this._session = { ...this._session, messages: [...this._session.messages, msg] };
+    this.emit();
+  }
+  appendTextDelta(delta) {
+    const messages = [...this._session.messages];
+    const last = messages.at(-1);
+    if (last?.role === "assistant") {
+      messages[messages.length - 1] = { ...last, content: last.content + delta };
+    } else {
+      messages.push({
+        id: generateId(),
+        role: "assistant",
+        content: delta,
+        createdAt: /* @__PURE__ */ new Date()
+      });
+    }
+    this._session = { ...this._session, messages };
+    this.emit();
+  }
+  beginToolCall(toolCallId, toolName) {
+    const messages = [...this._session.messages];
+    const last = messages.at(-1);
+    const toolCall = {
+      id: toolCallId,
+      name: toolName,
+      input: {},
+      output: null,
+      status: "pending",
+      error: null
+    };
+    if (last?.role === "assistant") {
+      messages[messages.length - 1] = {
+        ...last,
+        toolCalls: [...last.toolCalls ?? [], toolCall]
+      };
+    } else {
+      messages.push({
+        id: generateId(),
+        role: "assistant",
+        content: "",
+        toolCalls: [toolCall],
+        createdAt: /* @__PURE__ */ new Date()
+      });
+    }
+    this._session = { ...this._session, messages };
+    this.emit();
+  }
+  updateToolCall(toolCallId, update) {
+    const messages = this._session.messages.map((msg) => {
+      if (!msg.toolCalls) return msg;
+      const toolCalls = msg.toolCalls.map(
+        (tc) => tc.id === toolCallId ? { ...tc, ...update } : tc
+      );
+      return { ...msg, toolCalls };
+    });
+    this._session = { ...this._session, messages };
+    this.emit();
+  }
+  updateTokenUsage(usage) {
+    this._session = { ...this._session, tokenUsage: usage };
+    this.emit();
+  }
+  clear() {
+    if (this._resetTimer !== null) {
+      clearTimeout(this._resetTimer);
+      this._resetTimer = null;
+    }
+    this._session = makeInitialSession(this._session.id);
+    this.emit();
+  }
+};
+function makeInitialSession(id) {
+  return {
+    id,
+    messages: [],
+    status: "idle",
+    tokenUsage: { input: 0, output: 0, total: 0 },
+    error: null
+  };
+}
+function generateId() {
+  return crypto.randomUUID();
+}
+
+// src/tool-store.ts
+function idleState() {
+  return { id: null, toolName: null, status: "idle", input: null, output: null, error: null };
+}
+var ToolCallStore = class {
+  constructor() {
+    // toolCallId → toolName for reverse lookups
+    this._idToName = /* @__PURE__ */ new Map();
+    // toolName → current state (latest invocation wins)
+    this._states = /* @__PURE__ */ new Map();
+    this._listeners = /* @__PURE__ */ new Map();
+  }
+  getState(toolName) {
+    return this._states.get(toolName) ?? idleState();
+  }
+  subscribe(toolName, listener) {
+    if (!this._listeners.has(toolName)) this._listeners.set(toolName, /* @__PURE__ */ new Set());
+    this._listeners.get(toolName).add(listener);
+    return () => this._listeners.get(toolName)?.delete(listener);
+  }
+  onToolStart(toolCallId, toolName) {
+    this._idToName.set(toolCallId, toolName);
+    this._set(toolName, { id: toolCallId, toolName, status: "pending", input: null, output: null, error: null });
+  }
+  onToolInputDone(toolCallId, input) {
+    const toolName = this._idToName.get(toolCallId);
+    if (!toolName) return;
+    const current = this._states.get(toolName);
+    if (current?.id !== toolCallId) return;
+    this._set(toolName, { ...current, status: "running", input });
+  }
+  onToolResult(toolCallId, result) {
+    const toolName = this._idToName.get(toolCallId);
+    if (!toolName) return;
+    const current = this._states.get(toolName);
+    if (current?.id !== toolCallId) return;
+    this._set(toolName, { ...current, status: "done", output: result });
+  }
+  onToolError(toolCallId, error) {
+    const toolName = this._idToName.get(toolCallId);
+    if (!toolName) return;
+    const current = this._states.get(toolName);
+    if (current?.id !== toolCallId) return;
+    this._set(toolName, { ...current, status: "failed", error });
+  }
+  resetAll() {
+    this._idToName.clear();
+    for (const toolName of this._states.keys()) {
+      this._set(toolName, idleState());
+    }
+  }
+  _set(toolName, state) {
+    this._states.set(toolName, state);
+    this._listeners.get(toolName)?.forEach((l) => l(state));
+  }
+};
+
+// src/wire-processor.ts
+function processWireEvent(event, session, toolStore) {
+  switch (event.type) {
+    case "strand:start":
+      session.transition("submitting");
+      break;
+    case "strand:text-delta":
+      if (session.session.status !== "streaming") session.transition("streaming");
+      session.appendTextDelta(event.delta);
+      break;
+    case "strand:tool-start":
+      session.beginToolCall(event.toolCallId, event.toolName);
+      toolStore.onToolStart(event.toolCallId, event.toolName);
+      break;
+    case "strand:tool-input-delta":
+      break;
+    case "strand:tool-input-done":
+      session.updateToolCall(event.toolCallId, { input: event.input, status: "running" });
+      toolStore.onToolInputDone(event.toolCallId, event.input);
+      break;
+    case "strand:tool-result":
+      session.updateToolCall(event.toolCallId, { output: event.result, status: "done" });
+      toolStore.onToolResult(event.toolCallId, event.result);
+      break;
+    case "strand:tool-error": {
+      const error = new Error(event.error);
+      session.updateToolCall(event.toolCallId, { error, status: "failed" });
+      toolStore.onToolError(event.toolCallId, error);
+      break;
+    }
+    case "strand:done":
+      session.updateTokenUsage(event.usage);
+      session.transition("done");
+      toolStore.resetAll();
+      break;
+    case "strand:error": {
+      const error = new StrandError(0, event.message, event.code);
+      session.transition("error", error);
+      break;
+    }
+  }
+}
+
+// src/schema.ts
+import { zodToJsonSchema } from "zod-to-json-schema";
+function toolToJsonSchema(tool2) {
+  const schema = zodToJsonSchema(tool2.parameters, { target: "openApi3" });
+  const inner = schema;
+  delete inner["$schema"];
+  return inner;
+}
+
+// src/validate.ts
+function validateMessages(messages, config = {}) {
+  if (!Array.isArray(messages)) {
+    return { ok: false, status: 400, error: "messages must be an array" };
+  }
+  const maxMessages = config.maxMessages ?? 100;
+  if (messages.length > maxMessages) {
+    return { ok: false, status: 400, error: `Too many messages \u2014 max ${maxMessages}` };
+  }
+  const maxLen = config.maxMessageLength ?? 5e4;
+  for (const msg of messages) {
+    if (typeof msg !== "object" || msg === null) {
+      return { ok: false, status: 400, error: "Each message must be an object" };
+    }
+    const { role, content } = msg;
+    if (!["user", "assistant"].includes(role)) {
+      return { ok: false, status: 400, error: `Invalid message role: "${role}". Must be "user" or "assistant"` };
+    }
+    if (typeof content !== "string") {
+      return { ok: false, status: 400, error: "Message content must be a string" };
+    }
+    if (content.length > maxLen) {
+      return {
+        ok: false,
+        status: 400,
+        error: `Message content exceeds max length of ${maxLen} characters`
+      };
+    }
+  }
+  return { ok: true };
+}
+export {
+  SessionStateMachine,
+  StrandError,
+  ToolCallStore,
+  applyContextWindow,
+  createStrandClient,
+  generateId,
+  parseSSEStream,
+  processWireEvent,
+  tool,
+  toolToJsonSchema,
+  validateMessages,
+  withRetry
+};

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@strand-js/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "license": "MIT",
   "description": "Provider-agnostic AI state management — core types and client",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -15,6 +16,13 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  },
   "dependencies": {
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5"
@@ -26,12 +34,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "lint": "eslint src"
   }
-}
+}