stratus-sdk 0.5.0

package/README.md

@@ -0,0 +1,429 @@
+<p align="center">
+  <img src=".github/logo.svg" alt="Stratus" width="80" height="80">
+</p>
+
+# Stratus
+
+A TypeScript agent framework for Azure OpenAI. Build multi-agent systems with tools, handoffs, guardrails, streaming, structured output, and more.
+
+`agents` `tools` `streaming` `structured output` `handoffs` `subagents` `guardrails` `hooks` `tracing` `sessions` `abort signals`
+
+## Install
+
+```bash
+bun add stratus
+```
+
+Stratus requires [Zod](https://zod.dev) as a peer dependency:
+
+```bash
+bun add zod
+```
+
+## Quick Start
+
+```ts
+import { z } from "zod";
+import { Agent, AzureChatCompletionsModel, run, tool } from "stratus";
+
+const model = new AzureChatCompletionsModel({
+  endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
+  apiKey: process.env.AZURE_OPENAI_API_KEY!,
+  deployment: "gpt-5.2",
+});
+
+const getWeather = tool({
+  name: "get_weather",
+  description: "Get the current weather for a city",
+  parameters: z.object({
+    city: z.string().describe("The city name"),
+  }),
+  execute: async (_ctx, { city }) => {
+    return `72°F and sunny in ${city}`;
+  },
+});
+
+const agent = new Agent({
+  name: "weather-assistant",
+  instructions: "You are a helpful weather assistant.",
+  model,
+  tools: [getWeather],
+});
+
+const result = await run(agent, "What's the weather in New York?");
+console.log(result.output);
+```
+
+## Core Concepts
+
+### Agents
+
+Agents are the primary building block. Each agent has a name, instructions, a model, and optional tools, handoffs, guardrails, and hooks.
+
+```ts
+const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model,
+  tools: [myTool],
+});
+
+// Dynamic instructions based on context
+const agent = new Agent({
+  name: "my-agent",
+  instructions: (ctx) => `You are helping ${ctx.userName}.`,
+  model,
+});
+```
+
+### Tools
+
+Define tools with Zod schemas for type-safe parameter validation:
+
+```ts
+const searchTool = tool({
+  name: "search",
+  description: "Search for information",
+  parameters: z.object({
+    query: z.string().describe("Search query"),
+    limit: z.number().optional().describe("Max results"),
+  }),
+  execute: async (context, { query, limit }) => {
+    // Tool logic here
+    return "search results";
+  },
+});
+```
+
+### Streaming
+
+Stream responses token-by-token:
+
+```ts
+const { stream: s, result } = stream(agent, "Tell me a story");
+
+for await (const event of s) {
+  if (event.type === "content_delta") {
+    process.stdout.write(event.content);
+  } else if (event.type === "tool_call_start") {
+    console.log(`Calling: ${event.toolCall.name}`);
+  }
+}
+
+const finalResult = await result;
+```
+
+### Structured Output
+
+Use Zod schemas to get typed, validated output:
+
+```ts
+const PersonSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  occupation: z.string(),
+});
+
+const agent = new Agent({
+  name: "extractor",
+  instructions: "Extract person information.",
+  model,
+  outputType: PersonSchema,
+});
+
+const result = await run(agent, "Marie Curie was a 66-year-old physicist.");
+console.log(result.finalOutput); // { name: "Marie Curie", age: 66, occupation: "physicist" }
+```
+
+### Sessions
+
+Sessions maintain conversation history across multiple interactions:
+
+```ts
+import { createSession } from "stratus";
+
+const session = createSession({ model, tools: [myTool] });
+
+session.send("Hello!");
+for await (const event of session.stream()) {
+  // handle events
+}
+
+session.send("Follow-up question");
+for await (const event of session.stream()) {
+  // handle events
+}
+
+// Save and resume sessions
+const snapshot = session.save();
+const resumed = resumeSession(snapshot, { model });
+
+// Fork a session (new ID, same history)
+const forked = forkSession(snapshot, { model });
+
+// Cleanup
+session.close();
+// Or use Symbol.asyncDispose:
+await using session = createSession({ model });
+```
+
+### Handoffs
+
+Transfer control between specialized agents:
+
+```ts
+import { handoff } from "stratus";
+
+const orderAgent = new Agent({
+  name: "order_specialist",
+  instructions: "Help with order inquiries.",
+  model,
+  tools: [lookupOrder],
+  handoffDescription: "Transfer for order questions",
+});
+
+const triageAgent = new Agent({
+  name: "triage",
+  instructions: "Route to the right specialist.",
+  model,
+  handoffs: [
+    orderAgent, // shorthand
+    handoff({    // with options
+      agent: refundAgent,
+      onHandoff: () => console.log("Transferring..."),
+    }),
+  ],
+});
+
+const result = await run(triageAgent, "Where is my order?");
+console.log(result.lastAgent.name); // "order_specialist"
+```
+
+### Subagents
+
+Delegate subtasks to child agents that run independently:
+
+```ts
+import { subagent } from "stratus";
+
+const researcher = new Agent({
+  name: "researcher",
+  instructions: "Research topics thoroughly.",
+  model,
+});
+
+const parentAgent = new Agent({
+  name: "parent",
+  instructions: "Use the researcher for deep dives.",
+  model,
+  subagents: [
+    subagent({
+      agent: researcher,
+      inputSchema: z.object({ topic: z.string() }),
+      mapInput: ({ topic }) => `Research: ${topic}`,
+    }),
+  ],
+});
+```
+
+### Guardrails
+
+Validate inputs and outputs with guardrails:
+
+```ts
+import type { InputGuardrail, OutputGuardrail } from "stratus";
+
+const profanityFilter: InputGuardrail = {
+  name: "profanity_filter",
+  execute: (input) => ({
+    tripwireTriggered: containsProfanity(input),
+    outputInfo: "Blocked by profanity filter",
+  }),
+};
+
+const piiFilter: OutputGuardrail = {
+  name: "pii_filter",
+  execute: (output) => ({
+    tripwireTriggered: /\d{3}-\d{2}-\d{4}/.test(output),
+    outputInfo: "Output contained PII",
+  }),
+};
+
+const agent = new Agent({
+  name: "guarded",
+  model,
+  inputGuardrails: [profanityFilter],
+  outputGuardrails: [piiFilter],
+});
+```
+
+Guardrails run in parallel. When a tripwire is triggered, an `InputGuardrailTripwireTriggered` or `OutputGuardrailTripwireTriggered` error is thrown.
+
+### Hooks
+
+Lifecycle hooks for observability and control:
+
+```ts
+import type { AgentHooks } from "stratus";
+
+const hooks: AgentHooks = {
+  beforeRun: ({ agent, input }) => { /* ... */ },
+  afterRun: ({ agent, result }) => { /* ... */ },
+
+  // Return a decision to allow, deny, or modify tool calls
+  beforeToolCall: ({ toolCall }) => {
+    if (toolCall.function.name === "dangerous_tool") {
+      return { decision: "deny", reason: "Not allowed" };
+    }
+    return { decision: "allow" };
+  },
+  afterToolCall: ({ toolCall, result }) => { /* ... */ },
+
+  // Allow or deny handoffs
+  beforeHandoff: ({ fromAgent, toAgent }) => {
+    return { decision: "allow" };
+  },
+};
+```
+
+### Tracing
+
+Opt-in tracing with zero overhead when inactive:
+
+```ts
+import { withTrace } from "stratus";
+
+const { result, trace } = await withTrace("my-workflow", () =>
+  run(agent, "Hello"),
+);
+
+console.log(trace.id);
+console.log(trace.duration);
+for (const span of trace.spans) {
+  console.log(`[${span.type}] ${span.name} (${span.duration}ms)`);
+  // span.type: "model_call" | "tool_execution" | "handoff" | "guardrail" | "subagent" | "custom"
+}
+```
+
+### Abort Signals
+
+Cancel runs with `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  const result = await run(agent, "Long task...", {
+    signal: controller.signal,
+  });
+} catch (error) {
+  if (error instanceof RunAbortedError) {
+    console.log("Run was cancelled");
+  }
+}
+```
+
+### Tool Choice & Tool Use Behavior
+
+Control how the model uses tools:
+
+```ts
+const agent = new Agent({
+  name: "my-agent",
+  model,
+  tools: [myTool],
+  modelSettings: {
+    // "auto" | "none" | "required" | { type: "function", function: { name: "..." } }
+    toolChoice: "required",
+  },
+  // "run_llm_again" (default) | "stop_on_first_tool" | { stopAtToolNames: ["..."] }
+  toolUseBehavior: "stop_on_first_tool",
+});
+```
+
+## Imports
+
+Stratus provides three export paths:
+
+```ts
+// Everything (core + Azure)
+import { Agent, run, tool, AzureChatCompletionsModel, AzureResponsesModel } from "stratus";
+
+// Core only (provider-agnostic)
+import { Agent, run, tool } from "stratus/core";
+
+// Azure provider only
+import { AzureChatCompletionsModel, AzureResponsesModel } from "stratus/azure";
+```
+
+## Configuration
+
+### Azure OpenAI
+
+Stratus includes two interchangeable Azure model implementations:
+
+```ts
+// Chat Completions API
+const model = new AzureChatCompletionsModel({
+  endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
+  apiKey: process.env.AZURE_OPENAI_API_KEY!,
+  deployment: "gpt-5.2",
+  apiVersion: "2025-03-01-preview", // optional, this is the default
+});
+
+// Responses API
+const model = new AzureResponsesModel({
+  endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
+  apiKey: process.env.AZURE_OPENAI_API_KEY!,
+  deployment: "gpt-5.2",
+  apiVersion: "2025-04-01-preview", // optional, this is the default
+});
+```
+
+Both implement the same `Model` interface — swap one for the other without changing any agent, tool, or session code.
+
+### Environment Variables
+
+```
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
+AZURE_OPENAI_API_KEY=your-api-key
+```
+
+## Error Handling
+
+All errors extend `StratusError`:
+
+| Error | Description |
+|---|---|
+| `StratusError` | Base error class |
+| `ModelError` | API call failures (includes `status` and `code`) |
+| `ContentFilterError` | Content filtered by Azure's content management policy |
+| `MaxTurnsExceededError` | Agent exceeded the `maxTurns` limit |
+| `OutputParseError` | Structured output failed Zod validation |
+| `RunAbortedError` | Run cancelled via `AbortSignal` |
+| `InputGuardrailTripwireTriggered` | Input guardrail blocked the request |
+| `OutputGuardrailTripwireTriggered` | Output guardrail blocked the response |
+
+```ts
+import { ModelError, MaxTurnsExceededError, RunAbortedError } from "stratus";
+
+try {
+  await run(agent, input);
+} catch (error) {
+  if (error instanceof MaxTurnsExceededError) {
+    // Agent ran too many turns
+  } else if (error instanceof ModelError) {
+    console.log(error.status, error.code);
+  }
+}
+```
+
+## Development
+
+```bash
+bun test          # Run tests
+bun run lint      # Lint with Biome
+bun run typecheck # TypeScript type checking
+```

package/dist/azure/chat-completions-model.d.ts

@@ -0,0 +1,19 @@
+import type { Model, ModelRequest, ModelRequestOptions, ModelResponse, StreamEvent } from "../core/model";
+export interface AzureChatCompletionsModelConfig {
+    endpoint: string;
+    apiKey: string;
+    deployment: string;
+    apiVersion?: string;
+}
+export declare class AzureChatCompletionsModel implements Model {
+    private readonly url;
+    private readonly apiKey;
+    constructor(config: AzureChatCompletionsModelConfig);
+    getResponse(request: ModelRequest, options?: ModelRequestOptions): Promise<ModelResponse>;
+    getStreamedResponse(request: ModelRequest, options?: ModelRequestOptions): AsyncGenerator<StreamEvent>;
+    private buildRequestBody;
+    private doFetch;
+    private handleErrorResponse;
+    private parseResponse;
+}
+//# sourceMappingURL=chat-completions-model.d.ts.map

package/dist/azure/chat-completions-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-completions-model.d.ts","sourceRoot":"","sources":["../../src/azure/chat-completions-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,KAAK,EACL,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,WAAW,EAEX,MAAM,eAAe,CAAC;AAKvB,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,qBAAa,yBAA0B,YAAW,KAAK;IACtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,+BAA+B;IAS7C,WAAW,CAChB,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC;IAOlB,mBAAmB,CACzB,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC3B,cAAc,CAAC,WAAW,CAAC;IAiG9B,OAAO,CAAC,gBAAgB;YAyCV,OAAO;YAmCP,mBAAmB;IA2BjC,OAAO,CAAC,aAAa;CAyCrB"}

package/dist/azure/chat-completions-model.js

@@ -0,0 +1,256 @@
+import { ContentFilterError, ModelError } from "../core/errors";
+import { resolveChatCompletionsUrl } from "./endpoint";
+import { parseSSE } from "./sse-parser";
+const DEFAULT_API_VERSION = "2025-03-01-preview";
+export class AzureChatCompletionsModel {
+    url;
+    apiKey;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.url = resolveChatCompletionsUrl(config.endpoint, config.deployment, config.apiVersion ?? DEFAULT_API_VERSION);
+    }
+    async getResponse(request, options) {
+        const body = this.buildRequestBody(request, false);
+        const response = await this.doFetch(body, options?.signal);
+        const json = await response.json();
+        return this.parseResponse(json);
+    }
+    async *getStreamedResponse(request, options) {
+        const body = this.buildRequestBody(request, true);
+        const response = await this.doFetch(body, options?.signal);
+        if (!response.body) {
+            throw new ModelError("Response body is null");
+        }
+        let content = "";
+        const toolCalls = new Map();
+        let finishReason;
+        let usage;
+        for await (const data of parseSSE(response.body)) {
+            let chunk;
+            try {
+                chunk = JSON.parse(data);
+            }
+            catch {
+                continue;
+            }
+            if (chunk.usage) {
+                usage = {
+                    promptTokens: chunk.usage.prompt_tokens,
+                    completionTokens: chunk.usage.completion_tokens,
+                    totalTokens: chunk.usage.total_tokens,
+                    ...(chunk.usage.prompt_tokens_details?.cached_tokens !== undefined
+                        ? { cacheReadTokens: chunk.usage.prompt_tokens_details.cached_tokens }
+                        : {}),
+                    ...(chunk.usage.completion_tokens_details?.reasoning_tokens !== undefined
+                        ? { reasoningTokens: chunk.usage.completion_tokens_details.reasoning_tokens }
+                        : {}),
+                };
+            }
+            const choice = chunk.choices?.[0];
+            if (!choice)
+                continue;
+            if (choice.finish_reason) {
+                finishReason = choice.finish_reason;
+            }
+            const delta = choice.delta;
+            if (!delta)
+                continue;
+            if (delta.content) {
+                content += delta.content;
+                yield { type: "content_delta", content: delta.content };
+            }
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    const existing = toolCalls.get(tc.index);
+                    if (!existing) {
+                        const id = tc.id ?? "";
+                        const name = tc.function?.name ?? "";
+                        toolCalls.set(tc.index, { id, name, arguments: tc.function?.arguments ?? "" });
+                        if (id && name) {
+                            yield { type: "tool_call_start", toolCall: { id, name } };
+                        }
+                    }
+                    else {
+                        if (tc.id)
+                            existing.id = tc.id;
+                        if (tc.function?.name)
+                            existing.name = tc.function.name;
+                        if (tc.function?.arguments) {
+                            existing.arguments += tc.function.arguments;
+                            yield {
+                                type: "tool_call_delta",
+                                toolCallId: existing.id,
+                                arguments: tc.function.arguments,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+        const finalToolCalls = Array.from(toolCalls.values()).map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: { name: tc.name, arguments: tc.arguments },
+        }));
+        for (const tc of finalToolCalls) {
+            yield { type: "tool_call_done", toolCallId: tc.id };
+        }
+        yield {
+            type: "done",
+            response: {
+                content: content || null,
+                toolCalls: finalToolCalls,
+                usage,
+                finishReason,
+            },
+        };
+    }
+    buildRequestBody(request, stream) {
+        const body = {
+            messages: request.messages.map(serializeMessage),
+        };
+        if (stream) {
+            body.stream = true;
+            body.stream_options = { include_usage: true };
+        }
+        if (request.tools && request.tools.length > 0) {
+            body.tools = request.tools;
+        }
+        if (request.responseFormat) {
+            body.response_format = request.responseFormat;
+        }
+        const s = request.modelSettings;
+        if (s) {
+            if (s.temperature !== undefined)
+                body.temperature = s.temperature;
+            if (s.topP !== undefined)
+                body.top_p = s.topP;
+            if (s.maxTokens !== undefined)
+                body.max_tokens = s.maxTokens;
+            if (s.maxCompletionTokens !== undefined)
+                body.max_completion_tokens = s.maxCompletionTokens;
+            if (s.stop !== undefined)
+                body.stop = s.stop;
+            if (s.presencePenalty !== undefined)
+                body.presence_penalty = s.presencePenalty;
+            if (s.frequencyPenalty !== undefined)
+                body.frequency_penalty = s.frequencyPenalty;
+            if (s.toolChoice !== undefined)
+                body.tool_choice = s.toolChoice;
+            if (s.parallelToolCalls !== undefined)
+                body.parallel_tool_calls = s.parallelToolCalls;
+            if (s.seed !== undefined)
+                body.seed = s.seed;
+            if (s.reasoningEffort !== undefined)
+                body.reasoning_effort = s.reasoningEffort;
+            if (s.promptCacheKey !== undefined)
+                body.prompt_cache_key = s.promptCacheKey;
+        }
+        return body;
+    }
+    async doFetch(body, signal) {
+        const maxRetries = 3;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const response = await fetch(this.url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "api-key": this.apiKey,
+                },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (response.status === 429 && attempt < maxRetries) {
+                const retryAfter = response.headers.get("retry-after");
+                const waitMs = retryAfter
+                    ? Number.parseInt(retryAfter, 10) * 1000
+                    : Math.min(1000 * 2 ** attempt, 30000);
+                await new Promise((r) => setTimeout(r, waitMs));
+                continue;
+            }
+            if (!response.ok) {
+                await this.handleErrorResponse(response);
+            }
+            return response;
+        }
+        throw new ModelError("Max retries exceeded for Azure API request");
+    }
+    async handleErrorResponse(response) {
+        let errorBody;
+        try {
+            errorBody = await response.text();
+        }
+        catch {
+            errorBody = "";
+        }
+        if (response.status === 400) {
+            let parsed;
+            try {
+                parsed = JSON.parse(errorBody);
+            }
+            catch {
+                // ignore parse errors
+            }
+            if (parsed?.error?.code === "content_filter") {
+                throw new ContentFilterError(parsed.error.message, { status: 400 });
+            }
+        }
+        throw new ModelError(`Azure API error (${response.status}): ${errorBody || response.statusText}`, { status: response.status });
+    }
+    parseResponse(json) {
+        const choice = json.choices?.[0];
+        if (!choice) {
+            throw new ModelError("No choices in response");
+        }
+        if (choice.finish_reason === "content_filter") {
+            throw new ContentFilterError();
+        }
+        const toolCalls = (choice.message.tool_calls ?? []).map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: {
+                name: tc.function.name,
+                arguments: tc.function.arguments,
+            },
+        }));
+        const usage = json.usage
+            ? {
+                promptTokens: json.usage.prompt_tokens,
+                completionTokens: json.usage.completion_tokens,
+                totalTokens: json.usage.total_tokens,
+                ...(json.usage.prompt_tokens_details?.cached_tokens !== undefined
+                    ? { cacheReadTokens: json.usage.prompt_tokens_details.cached_tokens }
+                    : {}),
+                ...(json.usage.completion_tokens_details?.reasoning_tokens !== undefined
+                    ? { reasoningTokens: json.usage.completion_tokens_details.reasoning_tokens }
+                    : {}),
+            }
+            : undefined;
+        return {
+            content: choice.message.content,
+            toolCalls,
+            usage,
+            finishReason: choice.finish_reason,
+        };
+    }
+}
+function serializeMessage(msg) {
+    switch (msg.role) {
+        case "system":
+            return { role: "system", content: msg.content };
+        case "developer":
+            return { role: "developer", content: msg.content };
+        case "user":
+            return { role: "user", content: msg.content };
+        case "assistant": {
+            const out = { role: "assistant", content: msg.content };
+            if (msg.tool_calls && msg.tool_calls.length > 0) {
+                out.tool_calls = msg.tool_calls;
+            }
+            return out;
+        }
+        case "tool":
+            return { role: "tool", tool_call_id: msg.tool_call_id, content: msg.content };
+    }
+}
+//# sourceMappingURL=chat-completions-model.js.map