@strand-js/core 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,43 @@
+# @strand-js/core
+
+Core types, client, and state primitives for [Strand](https://github.com/strand-js/strand) — AI state management for React.
+
+## Install
+
+```bash
+npm install @strand-js/core zod
+```
+
+## What's in here
+
+- `createStrandClient(config)` — creates the HTTP client used by all React hooks
+- `SessionStateMachine` — 4-state streaming lifecycle (`idle → submitting → streaming → done`)
+- `ToolCallStore` — per-tool observable state for parallel tool call tracking
+- `processWireEvent` — routes SSE wire events to session and tool state
+- `validateMessages` — input sanitization for server handlers
+- `tool(definition)` — Zod-typed tool definition helper
+- All shared TypeScript types (`Session`, `Message`, `ToolCall`, `WireEvent`, etc.)
+
+## Usage
+
+```ts
+import { createStrandClient } from '@strand-js/core'
+
+const client = createStrandClient({
+  baseUrl: '/api/strand',
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+  contextWindow: { strategy: 'truncate-oldest', maxTokens: 100_000 },
+})
+```
+
+## Part of Strand
+
+| Package | Description |
+|---|---|
+| `@strand-js/core` | Core types and client |
+| `@strand-js/react` | React hooks |
+| `@strand-js/anthropic` | Anthropic server handler |
+| `@strand-js/openai` | OpenAI server handler |
+| `@strand-js/react-native` | React Native streaming patch |
+
+[Full documentation →](https://github.com/strand-js/strand)

package/dist/index.d.mts

@@ -0,0 +1,184 @@
+import { ZodSchema } from 'zod';
+
+type StreamingStatus = 'idle' | 'submitting' | 'streaming' | 'done' | 'error';
+type ToolCallStatus = 'idle' | 'pending' | 'running' | 'done' | 'failed';
+type AgentStatus = 'idle' | 'running' | 'paused' | 'done' | 'failed';
+interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    output: unknown | null;
+    status: ToolCallStatus;
+    error: Error | null;
+}
+interface Message {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    toolCalls?: ToolCall[];
+    createdAt: Date;
+}
+interface TokenUsage {
+    input: number;
+    output: number;
+    total: number;
+}
+interface Session {
+    id: string;
+    messages: Message[];
+    status: StreamingStatus;
+    tokenUsage: TokenUsage;
+    error: Error | null;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ZodSchema;
+}
+type RetryableError = 'rate_limit' | 'server_error' | 'timeout';
+interface RetryConfig {
+    maxAttempts?: number;
+    backoff?: 'exponential' | 'linear' | 'none';
+    retryOn?: RetryableError[];
+}
+type ContextWindowStrategy = 'truncate-oldest' | 'sliding-window' | 'none';
+interface ContextWindowConfig {
+    strategy?: ContextWindowStrategy;
+    maxTokens?: number;
+}
+interface StrandClientConfig {
+    baseUrl: string;
+    retry?: RetryConfig;
+    contextWindow?: ContextWindowConfig;
+}
+interface SendOptions {
+    context?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+interface StrandClient {
+    readonly config: StrandClientConfig;
+    send(messages: Message[], options?: SendOptions): AsyncGenerator<WireEvent>;
+}
+interface ToolCallState<TInput = unknown, TOutput = unknown> {
+    id: string | null;
+    toolName: string | null;
+    status: ToolCallStatus;
+    input: TInput | null;
+    output: TOutput | null;
+    error: Error | null;
+}
+interface AgentStep {
+    index: number;
+    description: string;
+    toolCalls: ToolCall[];
+    output: string | null;
+    status: 'running' | 'done' | 'failed';
+}
+type WireEvent = {
+    type: 'strand:start';
+    sessionId: string;
+    requestId: string;
+} | {
+    type: 'strand:text-delta';
+    delta: string;
+} | {
+    type: 'strand:tool-start';
+    toolCallId: string;
+    toolName: string;
+} | {
+    type: 'strand:tool-input-delta';
+    toolCallId: string;
+    delta: string;
+} | {
+    type: 'strand:tool-input-done';
+    toolCallId: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'strand:tool-result';
+    toolCallId: string;
+    result: unknown;
+} | {
+    type: 'strand:tool-error';
+    toolCallId: string;
+    error: string;
+} | {
+    type: 'strand:done';
+    usage: TokenUsage;
+} | {
+    type: 'strand:error';
+    code: string;
+    message: string;
+    retryAfter?: number;
+};
+
+declare function createStrandClient(config: StrandClientConfig): StrandClient;
+
+declare function tool(definition: ToolDefinition): ToolDefinition;
+
+declare class SessionStateMachine {
+    private _session;
+    private _listeners;
+    private _resetTimer;
+    constructor(sessionId?: string);
+    get session(): Readonly<Session>;
+    subscribe(listener: (session: Session) => void): () => void;
+    private emit;
+    transition(status: StreamingStatus, error?: Error): void;
+    addUserMessage(content: string): void;
+    appendTextDelta(delta: string): void;
+    beginToolCall(toolCallId: string, toolName: string): void;
+    updateToolCall(toolCallId: string, update: Partial<Omit<ToolCall, 'id' | 'name'>>): void;
+    updateTokenUsage(usage: TokenUsage): void;
+    clear(): void;
+}
+declare function generateId(): string;
+
+declare function applyContextWindow(messages: Message[], config: ContextWindowConfig): Message[];
+
+declare class StrandError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, message: string, code: string);
+}
+declare function withRetry<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
+
+declare function parseSSEStream(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<WireEvent>;
+
+declare class ToolCallStore {
+    private _idToName;
+    private _states;
+    private _listeners;
+    getState<TInput = unknown, TOutput = unknown>(toolName: string): ToolCallState<TInput, TOutput>;
+    subscribe(toolName: string, listener: (state: ToolCallState) => void): () => void;
+    onToolStart(toolCallId: string, toolName: string): void;
+    onToolInputDone(toolCallId: string, input: Record<string, unknown>): void;
+    onToolResult(toolCallId: string, result: unknown): void;
+    onToolError(toolCallId: string, error: Error): void;
+    resetAll(): void;
+    private _set;
+}
+
+declare function processWireEvent(event: WireEvent, session: SessionStateMachine, toolStore: ToolCallStore): void;
+
+interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+}
+declare function toolToJsonSchema(tool: ToolDefinition): JsonSchema;
+
+interface RequestValidationConfig {
+    maxMessages?: number;
+    maxMessageLength?: number;
+}
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+declare function validateMessages(messages: unknown, config?: RequestValidationConfig): ValidationResult;
+
+export { type AgentStatus, type AgentStep, type ContextWindowConfig, type ContextWindowStrategy, type JsonSchema, type Message, type RequestValidationConfig, type RetryConfig, type SendOptions, type Session, SessionStateMachine, type StrandClient, type StrandClientConfig, StrandError, type StreamingStatus, type TokenUsage, type ToolCall, type ToolCallState, type ToolCallStatus, ToolCallStore, type ToolDefinition, type ValidationResult, type WireEvent, applyContextWindow, createStrandClient, generateId, parseSSEStream, processWireEvent, tool, toolToJsonSchema, validateMessages, withRetry };

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+import { ZodSchema } from 'zod';
+
+type StreamingStatus = 'idle' | 'submitting' | 'streaming' | 'done' | 'error';
+type ToolCallStatus = 'idle' | 'pending' | 'running' | 'done' | 'failed';
+type AgentStatus = 'idle' | 'running' | 'paused' | 'done' | 'failed';
+interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    output: unknown | null;
+    status: ToolCallStatus;
+    error: Error | null;
+}
+interface Message {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    toolCalls?: ToolCall[];
+    createdAt: Date;
+}
+interface TokenUsage {
+    input: number;
+    output: number;
+    total: number;
+}
+interface Session {
+    id: string;
+    messages: Message[];
+    status: StreamingStatus;
+    tokenUsage: TokenUsage;
+    error: Error | null;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ZodSchema;
+}
+type RetryableError = 'rate_limit' | 'server_error' | 'timeout';
+interface RetryConfig {
+    maxAttempts?: number;
+    backoff?: 'exponential' | 'linear' | 'none';
+    retryOn?: RetryableError[];
+}
+type ContextWindowStrategy = 'truncate-oldest' | 'sliding-window' | 'none';
+interface ContextWindowConfig {
+    strategy?: ContextWindowStrategy;
+    maxTokens?: number;
+}
+interface StrandClientConfig {
+    baseUrl: string;
+    retry?: RetryConfig;
+    contextWindow?: ContextWindowConfig;
+}
+interface SendOptions {
+    context?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+interface StrandClient {
+    readonly config: StrandClientConfig;
+    send(messages: Message[], options?: SendOptions): AsyncGenerator<WireEvent>;
+}
+interface ToolCallState<TInput = unknown, TOutput = unknown> {
+    id: string | null;
+    toolName: string | null;
+    status: ToolCallStatus;
+    input: TInput | null;
+    output: TOutput | null;
+    error: Error | null;
+}
+interface AgentStep {
+    index: number;
+    description: string;
+    toolCalls: ToolCall[];
+    output: string | null;
+    status: 'running' | 'done' | 'failed';
+}
+type WireEvent = {
+    type: 'strand:start';
+    sessionId: string;
+    requestId: string;
+} | {
+    type: 'strand:text-delta';
+    delta: string;
+} | {
+    type: 'strand:tool-start';
+    toolCallId: string;
+    toolName: string;
+} | {
+    type: 'strand:tool-input-delta';
+    toolCallId: string;
+    delta: string;
+} | {
+    type: 'strand:tool-input-done';
+    toolCallId: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'strand:tool-result';
+    toolCallId: string;
+    result: unknown;
+} | {
+    type: 'strand:tool-error';
+    toolCallId: string;
+    error: string;
+} | {
+    type: 'strand:done';
+    usage: TokenUsage;
+} | {
+    type: 'strand:error';
+    code: string;
+    message: string;
+    retryAfter?: number;
+};
+
+declare function createStrandClient(config: StrandClientConfig): StrandClient;
+
+declare function tool(definition: ToolDefinition): ToolDefinition;
+
+declare class SessionStateMachine {
+    private _session;
+    private _listeners;
+    private _resetTimer;
+    constructor(sessionId?: string);
+    get session(): Readonly<Session>;
+    subscribe(listener: (session: Session) => void): () => void;
+    private emit;
+    transition(status: StreamingStatus, error?: Error): void;
+    addUserMessage(content: string): void;
+    appendTextDelta(delta: string): void;
+    beginToolCall(toolCallId: string, toolName: string): void;
+    updateToolCall(toolCallId: string, update: Partial<Omit<ToolCall, 'id' | 'name'>>): void;
+    updateTokenUsage(usage: TokenUsage): void;
+    clear(): void;
+}
+declare function generateId(): string;
+
+declare function applyContextWindow(messages: Message[], config: ContextWindowConfig): Message[];
+
+declare class StrandError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, message: string, code: string);
+}
+declare function withRetry<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
+
+declare function parseSSEStream(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<WireEvent>;
+
+declare class ToolCallStore {
+    private _idToName;
+    private _states;
+    private _listeners;
+    getState<TInput = unknown, TOutput = unknown>(toolName: string): ToolCallState<TInput, TOutput>;
+    subscribe(toolName: string, listener: (state: ToolCallState) => void): () => void;
+    onToolStart(toolCallId: string, toolName: string): void;
+    onToolInputDone(toolCallId: string, input: Record<string, unknown>): void;
+    onToolResult(toolCallId: string, result: unknown): void;
+    onToolError(toolCallId: string, error: Error): void;
+    resetAll(): void;
+    private _set;
+}
+
+declare function processWireEvent(event: WireEvent, session: SessionStateMachine, toolStore: ToolCallStore): void;
+
+interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+}
+declare function toolToJsonSchema(tool: ToolDefinition): JsonSchema;
+
+interface RequestValidationConfig {
+    maxMessages?: number;
+    maxMessageLength?: number;
+}
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+declare function validateMessages(messages: unknown, config?: RequestValidationConfig): ValidationResult;
+
+export { type AgentStatus, type AgentStep, type ContextWindowConfig, type ContextWindowStrategy, type JsonSchema, type Message, type RequestValidationConfig, type RetryConfig, type SendOptions, type Session, SessionStateMachine, type StrandClient, type StrandClientConfig, StrandError, type StreamingStatus, type TokenUsage, type ToolCall, type ToolCallState, type ToolCallStatus, ToolCallStore, type ToolDefinition, type ValidationResult, type WireEvent, applyContextWindow, createStrandClient, generateId, parseSSEStream, processWireEvent, tool, toolToJsonSchema, validateMessages, withRetry };