@arcote.tech/arc-ai 0.5.2 → 0.5.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-ai",
   "type": "module",
-  "version": "0.5.2",
+  "version": "0.5.6",
   "private": false,
   "description": "AI provider abstraction, completion tracking, and budget management for Arc framework",
   "main": "./src/index.ts",
@@ -10,8 +10,8 @@
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.5.2",
-    "@arcote.tech/arc-auth": "^0.5.2",
+    "@arcote.tech/arc": "^0.5.6",
+    "@arcote.tech/arc-auth": "^0.5.6",
     "typescript": "^5.0.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -25,12 +25,18 @@ export type {
   ProviderName,
   CompletionRequest,
   CompletionResult,
+  Conversation,
+  ConversationTurn,
+  UserTurn,
+  AssistantTurn,
+  ToolResultTurn,
+  AssistantContentBlock,
+  TextBlock,
+  ToolCallBlock,
   StreamChunk,
   StreamEventType,
   ChatStreamEvent,
   ChatStreamEventType,
-  Message,
-  MessageRole,
   ToolCall,
   ToolResult,
   TokenUsage,

package/src/types.ts

@@ -4,32 +4,92 @@ import type { JsonSchemaToolDef } from "./tool/tool";
 
 export type ProviderName = "openai" | "gemini" | "claude";
 
-// ─── Messages ────────────────────────────────────────────────────
+// ─── Tool Calls ──────────────────────────────────────────────────
 
-export type MessageRole = "system" | "user" | "assistant" | "tool";
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
 
-export interface Message {
-  role: MessageRole;
+export interface ToolResult {
+  toolCallId: string;
+  name: string;
   content: string;
-  name?: string;
-  toolCallId?: string;
+  isError: boolean;
 }
 
-// ─── Tool Calls ──────────────────────────────────────────────────
+// ─── Assistant content blocks (ordered) ─────────────────────────
+
+/**
+ * Real model output interleaves text and tool calls — e.g.
+ * "Let me check X" → tool_call → "and now Y" → tool_call. Both OpenAI Responses
+ * (output[]) and Claude (content[]) preserve this order. We mirror it 1:1 to
+ * avoid losing semantic structure.
+ */
+export interface TextBlock {
+  type: "text";
+  text: string;
+}
 
-export interface ToolCall {
+export interface ToolCallBlock {
+  type: "tool_call";
   id: string;
   name: string;
   arguments: Record<string, unknown>;
 }
 
-export interface ToolResult {
+export type AssistantContentBlock = TextBlock | ToolCallBlock;
+
+// ─── Conversation turns ─────────────────────────────────────────
+
+export interface UserTurn {
+  role: "user";
+  content: string;
+}
+
+export interface AssistantTurn {
+  role: "assistant";
+  /** Ordered model output: text and tool_call blocks interleaved as produced. */
+  blocks: AssistantContentBlock[];
+  /**
+   * Provider-issued response identifier for the turn this represents. Used by
+   * adapters that support server-side continuity (OpenAI Responses API) to
+   * anchor `previous_response_id` requests. Other adapters ignore this field.
+   */
+  responseId?: string;
+}
+
+export interface ToolResultTurn {
+  role: "tool_result";
   toolCallId: string;
   name: string;
   content: string;
-  isError: boolean;
+  isError?: boolean;
 }
 
+export type ConversationTurn = UserTurn | AssistantTurn | ToolResultTurn;
+
+// ─── Conversation (full vs continuation) ────────────────────────
+
+/**
+ * Discriminated union telling the adapter exactly what to send.
+ *
+ * - `full`: send every turn from `turns`. Used for cold start, or for any
+ *   provider that does not support server-side continuity (Claude, Gemini).
+ *
+ * - `continuation`: send only `newTurns` (the delta after the previous
+ *   response). Used by providers with server-side state (OpenAI Responses API).
+ *   The provider replays prior context server-side via `previousResponseId`.
+ */
+export type Conversation =
+  | { mode: "full"; turns: ConversationTurn[] }
+  | {
+      mode: "continuation";
+      previousResponseId: string;
+      newTurns: ConversationTurn[];
+    };
+
 // ─── Token Usage ─────────────────────────────────────────────────
 
 export interface TokenUsage {
@@ -46,20 +106,35 @@ export type FinishReason = "stop" | "tool_call" | "max_tokens" | "error";
 
 export interface CompletionRequest {
   model: string;
-  messages: Message[];
+  /**
+   * System prompt for this turn. Sent on every call. Providers that support
+   * server-side continuity (OpenAI Responses API) replace previously stored
+   * instructions for the new turn. Required — pass empty string if there is
+   * nothing to say.
+   */
+  instructions: string;
+  conversation: Conversation;
   tools?: JsonSchemaToolDef[];
   toolChoice?: "auto" | "required" | { type: "function"; name: string };
   webSearch?: boolean;
   temperature?: number;
   maxTokens?: number;
-  previousResponseId?: string;
 }
 
 export interface CompletionResult {
-  content: string;
-  toolCalls: ToolCall[];
+  /**
+   * Ordered output blocks from the model — same shape as `AssistantTurn.blocks`.
+   * Caller can persist this directly as a new AssistantTurn in history.
+   */
+  blocks: AssistantContentBlock[];
   usage: TokenUsage;
   finishReason: FinishReason;
+  /**
+   * Provider-issued response ID. Set by adapters that support server-side
+   * continuity (OpenAI). Caller persists this on the resulting AssistantTurn
+   * and passes it back as `Conversation.continuation.previousResponseId` next
+   * time.
+   */
   responseId?: string;
 }
 
@@ -88,6 +163,14 @@ export interface StreamChunk {
 export interface LLMProvider {
   name: ProviderName;
   models: string[];
+  /**
+   * Capability flag. When `true`, the listener may send
+   * `Conversation.mode = "continuation"` with a `previousResponseId` to skip
+   * resending history (OpenAI Responses API). When `false`, the listener must
+   * always send `Conversation.mode = "full"` with the full conversation
+   * history (Claude, Gemini).
+   */
+  supportsContinuation: boolean;
   complete(request: CompletionRequest): Promise<CompletionResult>;
   streamComplete(
     request: CompletionRequest,