@arcote.tech/arc-ai 0.5.1 → 0.5.5

package/src/tool/tool.ts

@@ -1,12 +1,18 @@
 import {
-  ArcFunction,
-  defaultFunctionData,
-  object,
+  arcFunctionWithCtx,
+  type ArcFunction,
+  type ArcId,
   type ArcRawShape,
-  type $type,
   type ArcContextElement,
   type ArcFunctionData,
+  type ArcObjectAny,
+  type FnContext,
+  type Merge,
+  type $type,
+  type DefaultFunctionData,
+  ArcObject,
 } from "@arcote.tech/arc";
+import type { ComponentType } from "react";
 
 // ─── JSON Schema Tool Definition (sent to LLM) ──────────────────
 
@@ -16,68 +22,153 @@ export interface JsonSchemaToolDef {
   parameters: Record<string, unknown>;
 }
 
-// ─── Tool Context (passed to handle) ────────────────────────────
+// ─── View Props ─────────────────────────────────────────────────
 
-export interface ToolContext {
-  mutate: (element: ArcContextElement<any>) => any;
-  query: (element: ArcContextElement<any>) => any;
-  identifyBy: string;
-}
+export type ServerToolViewProps<P, R> = {
+  params: P;
+  result: R | undefined;
+  calling: boolean;
+  error?: string;
+};
+
+export type InteractiveToolViewProps<P, R> = {
+  params: P;
+  respond: (result: R) => void;
+  calling: boolean;
+};
 
 // ─── ArcTool ─────────────────────────────────────────────────────
 
 export class ArcTool<
   const Name extends string = string,
-  const S extends ArcRawShape = ArcRawShape,
+  Data extends ArcFunctionData = DefaultFunctionData,
+  IdentifyBy = string,
 > {
   readonly name: Name;
-  #fn: ArcFunction<any>;
-  #handler?: (ctx: ToolContext, params: $type<ReturnType<typeof object<S>>>) => Promise<string>;
-
-  constructor(name: Name, fn?: ArcFunction<any>) {
+  readonly #fn: ArcFunction<Data, { identifyBy: IdentifyBy }>;
+  readonly #view?: ComponentType<any>;
+
+  constructor(
+    name: Name,
+    fn?: ArcFunction<any, any>,
+    view?: ComponentType<any>,
+  ) {
     this.name = name;
-    this.#fn = fn ?? new ArcFunction(defaultFunctionData);
+    this.#fn = fn ?? (arcFunctionWithCtx<{ identifyBy: IdentifyBy }>() as any);
+    this.#view = view;
   }
 
+  // ─── Builder methods ──────────────────────────────────────────
+
   description<const D extends string>(desc: D) {
-    const next = new ArcTool<Name, S>(this.name, this.#fn.description(desc));
-    next.#handler = this.#handler;
-    return next;
+    const nextFn = this.#fn.description(desc);
+    return new ArcTool<Name, Merge<Data, { description: D }>, IdentifyBy>(
+      this.name, nextFn as any, this.#view,
+    );
+  }
+
+  withParams<const S extends ArcRawShape>(shape: S) {
+    const nextFn = this.#fn.withParams(shape);
+    return new ArcTool<Name, Merge<Data, { params: ArcObject<S> }>, IdentifyBy>(
+      this.name, nextFn as any, this.#view,
+    );
   }
 
-  schema<const NewS extends ArcRawShape>(shape: NewS) {
-    const next = new ArcTool<Name, NewS>(this.name, this.#fn.withParams(shape));
-    return next;
+  withResult<const S extends ArcRawShape>(shape: S) {
+    const nextFn = this.#fn.withResult(shape);
+    return new ArcTool<Name, Merge<Data, { result: ArcObject<S> }>, IdentifyBy>(
+      this.name, nextFn as any, this.#view,
+    );
   }
 
-  mutate(elements: ArcContextElement<any>[]) {
-    const next = new ArcTool<Name, S>(this.name, this.#fn.mutate(elements));
-    next.#handler = this.#handler;
-    return next;
+  query<const Elements extends ArcContextElement<any>[]>(elements: Elements) {
+    const nextFn = this.#fn.query(elements);
+    return new ArcTool<Name, Merge<Data, { queryElements: Elements }>, IdentifyBy>(
+      this.name, nextFn as any, this.#view,
+    );
   }
 
-  handle(handler: (ctx: ToolContext, params: $type<ReturnType<typeof object<S>>>) => Promise<string>) {
-    const next = new ArcTool<Name, S>(this.name, this.#fn);
-    next.#handler = handler;
-    return next;
+  mutate<const Elements extends ArcContextElement<any>[]>(elements: Elements) {
+    const nextFn = this.#fn.mutate(elements);
+    return new ArcTool<Name, Merge<Data, { mutationElements: Elements }>, IdentifyBy>(
+      this.name, nextFn as any, this.#view,
+    );
   }
 
+  identifyBy<Id extends ArcId<any>>(_id: Id) {
+    return new ArcTool<Name, Data, $type<Id>>(
+      this.name, this.#fn as any, this.#view,
+    );
+  }
+
+  handle<
+    Handler extends
+      | ((
+          ctx: FnContext<Data, { identifyBy: IdentifyBy }>,
+          ...args: Data["params"] extends ArcObjectAny
+            ? [$type<Data["params"]>]
+            : []
+        ) => Promise<any>)
+      | false,
+  >(handler: Handler) {
+    const nextFn = this.#fn.handle(handler as any);
+    return new ArcTool<Name, Merge<Data, { handler: Handler }>, IdentifyBy>(
+      this.name, nextFn as any, this.#view,
+    );
+  }
+
+  view(
+    component: ComponentType<
+      Data["handler"] extends Function
+        ? ServerToolViewProps<
+            Data["params"] extends ArcObjectAny ? $type<Data["params"]> : {},
+            Data["result"] extends ArcObjectAny
+              ? $type<Data["result"]>
+              : unknown
+          >
+        : InteractiveToolViewProps<
+            Data["params"] extends ArcObjectAny ? $type<Data["params"]> : {},
+            Data["result"] extends ArcObjectAny
+              ? $type<Data["result"]>
+              : unknown
+          >
+    >,
+  ) {
+    return new ArcTool<Name, Data, IdentifyBy>(this.name, this.#fn as any, component);
+  }
+
+  // ─── Getters ──────────────────────────────────────────────────
+
   get hasHandler(): boolean {
-    return !!this.#handler;
+    return !!this.#fn.handler;
   }
 
   get isServerTool(): boolean {
     return this.hasHandler;
   }
 
-  get isClientTool(): boolean {
-    return !this.hasHandler;
+  get isInteractiveTool(): boolean {
+    return !this.hasHandler && !!this.#view;
+  }
+
+  get hasView(): boolean {
+    return !!this.#view;
+  }
+
+  get viewComponent(): ComponentType<any> | undefined {
+    return this.#view;
+  }
+
+  get queryElements(): ArcContextElement<any>[] {
+    return this.#fn.data.queryElements || [];
   }
 
   get mutationElements(): ArcContextElement<any>[] {
     return this.#fn.data.mutationElements || [];
   }
 
+  // ─── JSON Schema (for LLM) ───────────────────────────────────
+
   toJsonSchema(): JsonSchemaToolDef {
     const fnSchema = this.#fn.toJsonSchema();
     return {
@@ -87,28 +178,23 @@ export class ArcTool<
     };
   }
 
-  async executeWithContext(params: Record<string, unknown>, ctx: ToolContext): Promise<string> {
-    if (!this.#handler) {
-      throw new Error(`Tool "${this.name}" has no handler`);
-    }
-    return this.#handler(ctx, params as $type<ReturnType<typeof object<S>>>);
-  }
+  // ─── Execution (called by listener) ──────────────────────────
 
-  async execute(params: Record<string, unknown>): Promise<string> {
-    if (!this.#handler) {
+  async executeWithContext(
+    params: Record<string, unknown>,
+    listenerCtx: any,
+    identifyByValue: string,
+  ): Promise<string> {
+    const handler = this.#fn.handler as Function | false | null;
+    if (!handler) {
       throw new Error(`Tool "${this.name}" has no handler`);
     }
-    if (this.mutationElements.length > 0) {
-      throw new Error(
-        `Tool "${this.name}" has mutation dependencies — use executeWithContext() instead`,
-      );
-    }
-    const emptyCtx: ToolContext = {
-      mutate: () => { throw new Error("No mutation context available"); },
-      query: () => { throw new Error("No query context available"); },
-      identifyBy: "",
-    };
-    return this.#handler(emptyCtx, params as $type<ReturnType<typeof object<S>>>);
+
+    const ctx = { ...listenerCtx, identifyBy: identifyByValue };
+    const result = await (handler as Function)(ctx, params);
+
+    if (typeof result === "string") return result;
+    return JSON.stringify(result);
   }
 }
 
@@ -118,4 +204,4 @@ export function tool<const Name extends string>(name: Name) {
   return new ArcTool(name);
 }
 
-export type ArcToolAny = ArcTool<string, ArcRawShape>;
+export type ArcToolAny = ArcTool<string, any, any>;

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,19 +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;
 }
 
@@ -87,11 +163,20 @@ 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,
     onChunk: (chunk: StreamChunk) => void,
   ): Promise<CompletionResult>;
+  getPricing?(model: string): import("./billing/types").AdapterPricing | undefined;
 }
 
 // ─── Chat Stream (SSE events for chat streaming) ────────────────
@@ -100,7 +185,7 @@ export type ChatStreamEventType =
   | "content_delta"
   | "server_tool_start"
   | "server_tool_result"
-  | "client_tool_request"
+  | "interactive_tool_request"
   | "usage_update"
   | "done"
   | "error";
@@ -118,11 +203,3 @@ export interface ChatStreamEvent {
   error?: string;
 }
 
-// ─── Pricing ─────────────────────────────────────────────────────
-
-export interface PricingConfig {
-  inputPer1M: number;
-  outputPer1M: number;
-  cachedInputPer1M?: number;
-  reasoningPer1M?: number;
-}

package/src/aggregates/budget.ts

@@ -1,137 +0,0 @@
-/// <reference path="../arc.d.ts" />
-import {
-  aggregate,
-  boolean,
-  id,
-  number,
-  string,
-  type ArcId,
-} from "@arcote.tech/arc";
-import type { Token } from "@arcote.tech/arc-auth";
-import type { createCompletionAggregate } from "./completion";
-
-// ─── ID ──────────────────────────────────────────────────────────
-
-export const createBudgetId = <const Name extends string>(data: {
-  name: Name;
-}) => id(`${data.name}Budget`);
-
-export type BudgetId<Name extends string = string> = ReturnType<
-  typeof createBudgetId<Name>
->;
-
-// ─── Aggregate ───────────────────────────────────────────────────
-
-export type BudgetAggregateData = {
-  name: string;
-  budgetId: ArcId<any>;
-  accountId: ArcId<any>;
-  userToken: Token;
-  CompletionAggregate: ReturnType<typeof createCompletionAggregate>;
-};
-
-export const createBudgetAggregate = <
-  const Data extends BudgetAggregateData,
->(
-  data: Data,
-) => {
-  const { budgetId, accountId, userToken, CompletionAggregate } = data;
-
-  const completionFinishedEvent =
-    CompletionAggregate.getEvent("completionFinished");
-
-  return aggregate(`${data.name}Budgets`, budgetId, {
-    accountId,
-    budgetType: string(),
-    limitCents: number(),
-    usedCents: number(),
-    period: string().optional(),
-    isExceeded: boolean(),
-  })
-    .publicEvent(
-      "budgetSet",
-      {
-        budgetId,
-        accountId,
-        budgetType: string(),
-        limitCents: number(),
-        period: string().optional(),
-      },
-      async (ctx, event) => {
-        const p = event.payload;
-        await ctx.set(p.budgetId, {
-          accountId: p.accountId,
-          budgetType: p.budgetType,
-          limitCents: p.limitCents,
-          usedCents: 0,
-          period: p.period,
-          isExceeded: false,
-        });
-      },
-    )
-
-    .publicEvent(
-      "budgetUsageRecorded",
-      {
-        budgetId,
-        amountCents: number(),
-      },
-      async (ctx, event) => {
-        const existing = await ctx.findOne({ _id: event.payload.budgetId });
-        if (!existing) return;
-
-        const newUsed = existing.usedCents + event.payload.amountCents;
-        await ctx.modify(event.payload.budgetId, {
-          usedCents: newUsed,
-          isExceeded: newUsed >= existing.limitCents,
-        });
-      },
-    )
-
-    .handleEvent(completionFinishedEvent, async (ctx, event) => {
-      // Record usage from completion cost on all matching budgets
-      const budgets = await ctx.find({});
-      for (const budget of budgets) {
-        const newUsed = budget.usedCents + event.payload.costCents;
-        await ctx.modify(budget._id, {
-          usedCents: newUsed,
-          isExceeded: newUsed >= budget.limitCents,
-        });
-      }
-    })
-
-    .mutateMethod(
-      "setBudget",
-      (fn) => fn.withParams({
-          budgetType: string(),
-          limitCents: number(),
-          period: string().optional(),
-        }).handle(
-      ONLY_SERVER &&
-        (async (ctx, params) => {
-          const bId = budgetId.generate();
-          const aId = ctx.$auth.params.accountId;
-
-          await ctx.budgetSet.emit({
-            budgetId: bId,
-            accountId: accountId.parse(aId),
-            budgetType: params.budgetType,
-            limitCents: params.limitCents,
-            period: params.period,
-          });
-
-          return { budgetId: bId };
-        }),
-    ))
-
-    .clientQuery(
-      "getByAccount",
-      (fn) => fn.handle(async (ctx) =>
-        ctx.$query.find({ where: { accountId: ctx.$auth.params.accountId } }),
-    ))
-
-    .protectBy(userToken, (p) => ({ accountId: p.accountId }))
-;
-};
-
-export type BudgetAggregate = ReturnType<typeof createBudgetAggregate>;