@alumbwe/anvil 1.0.20 → 1.0.22

package/vendor/@anvil/common/src/types/contracts/llm.ts

@@ -0,0 +1,191 @@
+import type { TrackEventFn } from './analytics'
+import type { SendActionFn } from './client'
+import type {
+  OpenRouterProviderRoutingOptions,
+  AgentTemplate,
+} from '../agent-template'
+import type { ParamsExcluding } from '../function-params'
+import type { Logger } from './logger'
+import type { Model } from '../../old-constants'
+import type { Message } from '../messages/anvil-message'
+import type { ProviderMetadata } from '../messages/provider-metadata'
+import type { PromptResult } from '../../util/error'
+import type { generateText, streamText, ToolCallPart } from 'ai'
+import type z from 'zod/v4'
+
+/** Auto-recovered stream endings (see sdk/src/impl/stream-interruption.ts):
+ *  - 'stream-interrupted': the stream ended without a finish marker
+ *    (connection cut mid-response — a server deploy or network drop).
+ *  - 'output-limit': the stream produced only reasoning and no usable answer,
+ *    either by reaching its output limit or by reporting a normal stop. */
+export type StreamRecoverySource = 'stream-interrupted' | 'output-limit'
+
+export type StreamChunk =
+  | {
+      type: 'text'
+      text: string
+      agentId?: string
+    }
+  | {
+      type: 'reasoning'
+      text: string
+      /** Provider metadata for the whole reasoning segment (e.g. OpenRouter
+       *  reasoning_details with thinking signatures), delivered on a final
+       *  empty-text chunk once the segment ends. Stored on the history's
+       *  reasoning part so the next request can replay it. */
+      providerOptions?: ProviderMetadata
+    }
+  | Pick<
+      ToolCallPart,
+      'type' | 'toolCallId' | 'toolName' | 'input' | 'providerOptions'
+    >
+  | {
+      type: 'error'
+      message: string
+      /** When set, this is an auto-recovered stream ending rather than a
+       *  failure: consumers force another agent step so the model can
+       *  continue, instead of wrapping the message as a tool-call failure and
+       *  instead of the turn silently ending. */
+      source?: StreamRecoverySource
+    }
+
+export type CacheDebugUsageData = {
+  inputTokens: number
+  outputTokens: number
+  reasoningOutputTokens?: number
+  cachedInputTokens: number
+  totalTokens: number
+}
+
+/** Provider-reported usage for one model request. */
+export type ModelUsageData = CacheDebugUsageData
+
+/** Provider usage attributed by the runtime to the agent that made the request. */
+export type AgentUsageData = ModelUsageData & {
+  isRoot: boolean
+  agentId?: string
+}
+
+export type ContextCompactionData = {
+  trigger: 'context_limit' | 'cache_expiry' | 'context_limit_and_cache_expiry'
+  thresholdTokens: number
+}
+
+export type PromptAiSdkStreamFn = (
+  params: {
+    apiKey: string
+    runId: string
+    messages: Message[]
+    clientSessionId: string
+    fingerprintId: string
+    model: Model
+    userId: string | undefined
+    chargeUser?: boolean
+    thinkingBudget?: number
+    userInputId: string
+    agentId?: string
+    maxRetries?: number
+    onCostCalculated?: (credits: number) => Promise<void>
+    onCacheDebugProviderRequestBuilt?: (params: {
+      provider: string
+      rawBody: unknown
+      normalizedBody?: unknown
+    }) => void
+    onCacheDebugUsageReceived?: (usage: CacheDebugUsageData) => void
+    onUsageReceived?: (usage: ModelUsageData) => void
+    /** The request ended without an exact final provider usage receipt. */
+    onUsageIncomplete?: () => void
+    includeCacheControl?: boolean
+    cacheDebugCorrelation?: string
+    agentProviderOptions?: OpenRouterProviderRoutingOptions
+    /** List of agents that can be spawned - used to transform agent tool calls */
+    spawnableAgents?: string[]
+    /** Map of locally available agent templates - used to transform agent tool calls */
+    localAgentTemplates?: Record<string, AgentTemplate>
+    /** Cost mode - 'free' mode means 0 credits charged for all agents */
+    costMode?: string
+    /** Extra key/values merged into the request's `anvil_metadata` field.
+     *  Used to forward client-scoped identifiers (e.g. `anvil_instance_id`)
+     *  that server-side gates read from the chat-completions body. */
+    extraAnvilMetadata?: Record<string, string>
+    sendAction: SendActionFn
+    logger: Logger
+    trackEvent: TrackEventFn
+    signal: AbortSignal
+  } & ParamsExcluding<typeof streamText, 'model' | 'messages'>,
+) => AsyncGenerator<StreamChunk, PromptResult<string | null>>
+
+export type PromptAiSdkFn = (
+  params: {
+    apiKey: string
+    runId: string
+    messages: Message[]
+    clientSessionId: string
+    fingerprintId: string
+    userInputId: string
+    model: Model
+    userId: string | undefined
+    chargeUser?: boolean
+    agentId?: string
+    onCostCalculated?: (credits: number) => Promise<void>
+    onCacheDebugProviderRequestBuilt?: (params: {
+      provider: string
+      rawBody: unknown
+      normalizedBody?: unknown
+    }) => void
+    onCacheDebugUsageReceived?: (usage: CacheDebugUsageData) => void
+    includeCacheControl?: boolean
+    cacheDebugCorrelation?: string
+    agentProviderOptions?: OpenRouterProviderRoutingOptions
+    maxRetries?: number
+    /** Cost mode - 'free' mode means 0 credits charged for all agents */
+    costMode?: string
+    sendAction: SendActionFn
+    logger: Logger
+    trackEvent: TrackEventFn
+    n?: number
+    signal: AbortSignal
+  } & ParamsExcluding<typeof generateText, 'model' | 'messages'>,
+) => Promise<PromptResult<string>>
+
+export type PromptAiSdkStructuredInput<T> = {
+  apiKey: string
+  runId: string
+  messages: Message[]
+  schema: z.ZodType<T>
+  clientSessionId: string
+  fingerprintId: string
+  userInputId: string
+  model: Model
+  userId: string | undefined
+  maxTokens?: number
+  temperature?: number
+  timeout?: number
+  chargeUser?: boolean
+  agentId?: string
+  onCostCalculated?: (credits: number) => Promise<void>
+  onCacheDebugProviderRequestBuilt?: (params: {
+    provider: string
+    rawBody: unknown
+    normalizedBody?: unknown
+  }) => void
+  onCacheDebugUsageReceived?: (usage: CacheDebugUsageData) => void
+  includeCacheControl?: boolean
+  cacheDebugCorrelation?: string
+  agentProviderOptions?: OpenRouterProviderRoutingOptions
+  maxRetries?: number
+  sendAction: SendActionFn
+  logger: Logger
+  trackEvent: TrackEventFn
+  signal: AbortSignal
+}
+export type PromptAiSdkStructuredOutput<T> = Promise<PromptResult<T>>
+export type PromptAiSdkStructuredFn = <T>(
+  params: PromptAiSdkStructuredInput<T>,
+) => PromptAiSdkStructuredOutput<T>
+
+export type HandleOpenRouterStreamFn = (params: {
+  body: any
+  userId: string
+  agentId: string
+}) => Promise<ReadableStream>

package/vendor/@anvil/common/src/types/contracts/logger.ts

@@ -0,0 +1,14 @@
+export type LoggerFn = (
+  data: unknown,
+  msg?: string,
+  ...args: unknown[]
+) => unknown
+
+export type Logger = {
+  debug: LoggerFn
+  info: LoggerFn
+  warn: LoggerFn
+  error: LoggerFn
+}
+
+export type LoggerWithContextFn = (context: Record<string, any>) => Logger

package/vendor/@anvil/common/src/types/contracts/logs.ts

@@ -0,0 +1,34 @@
+/** Severity levels for the unified logs stream. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+/** Origin of a log row. */
+export type LogSource = 'server' | 'cli' | 'browser'
+
+/**
+ * One normalized log/event record. This is the provider-agnostic shape the
+ * sink ingests (currently into Axiom — see `@anvil/logging`). An "event" is
+ * just a log row with `event` populated, so all logs and analytics events live
+ * in one stream. See docs/logging.md.
+ */
+export type LogRow = {
+  /** UUID for this row. */
+  id: string
+  /** Event time (becomes Axiom's `_time`). */
+  timestamp: Date
+  level: LogLevel
+  source: LogSource
+  /** Emitting service, e.g. 'web', 'agent-runtime', 'anvil-web', 'cli'. */
+  service?: string | null
+  /** Deploy environment: 'dev' | 'test' | 'prod'. */
+  env: string
+  /** Analytics or operational event name when applicable, else null. */
+  event?: string | null
+  /** Human-readable message (the formatted pino msg). */
+  message?: string | null
+  user_id?: string | null
+  client_session_id?: string | null
+  client_request_id?: string | null
+  fingerprint_id?: string | null
+  /** Structured payload. Serialized to a single string field on ingest. */
+  data?: unknown
+}

package/vendor/@anvil/common/src/types/contracts/trace.ts

@@ -0,0 +1,21 @@
+import type { Message } from '../messages/anvil-message'
+
+/**
+ * Records agent message histories for debugging (e.g. to a trace.jsonl file).
+ *
+ * Callers pass the agent's full message history at each step boundary;
+ * implementations are expected to persist each message only once (appending
+ * the delta since the previous call for the same agentId), so calling this
+ * every step does not grow storage quadratically.
+ */
+export type TraceWriter = {
+  recordStep: (params: {
+    agentId: string
+    agentType: string
+    runId: string | undefined
+    userInputId: string
+    step: number
+    system: string | undefined
+    messages: Message[]
+  }) => void
+}

package/vendor/@anvil/common/src/types/dynamic-agent-template.ts

@@ -0,0 +1,328 @@
+import { z } from 'zod/v4'
+
+import { ALLOWED_MODEL_PREFIXES, models } from '../old-constants'
+import { mcpConfigSchema } from './mcp'
+
+import type { JSONSchema } from 'zod/v4/core'
+
+// Filter models to only include those that begin with allowed prefixes
+const filteredModels = Object.values(models).filter((model) =>
+  ALLOWED_MODEL_PREFIXES.some((prefix) => model.startsWith(prefix)),
+)
+
+if (filteredModels.length === 0) {
+  throw new Error('No valid models found with allowed prefixes')
+}
+
+// Simplified JSON Schema definition - supports object schemas with nested properties
+export const JsonSchemaSchema: z.ZodType<
+  JSONSchema.BaseSchema,
+  JSONSchema.BaseSchema
+> = z.lazy(() =>
+  z.looseObject({
+    type: z
+      .enum([
+        'object',
+        'array',
+        'string',
+        'number',
+        'boolean',
+        'null',
+        'integer',
+      ])
+      .optional(),
+    description: z.string().optional(),
+    properties: z
+      .record(z.string(), JsonSchemaSchema.or(z.boolean()))
+      .optional(),
+    required: z.string().array().optional(),
+    enum: z
+      .union([z.string(), z.number(), z.boolean(), z.null()])
+      .array()
+      .optional(),
+  }),
+)
+const JsonObjectSchemaSchema = z.intersection(
+  JsonSchemaSchema,
+  z.object({ type: z.literal('object') }),
+)
+
+// Schema for the combined inputSchema object
+const InputSchemaObjectSchema = z
+  .looseObject({
+    prompt: z
+      .looseObject({
+        type: z.literal('string'),
+        description: z.string().optional(),
+      })
+      .optional(), // Optional JSON schema for prompt validation
+    params: JsonObjectSchemaSchema.optional(), // Optional JSON schema for params validation
+  })
+  .optional()
+
+// Schema for prompt fields that can be either a string or a path reference
+const PromptFieldSchema = z.union([
+  z.string(), // Direct string content
+  z.object({ path: z.string() }), // Path reference to external file
+])
+export type PromptField = z.infer<typeof PromptFieldSchema>
+
+const functionSchema = <T extends z.core.$ZodFunction>(schema: T) =>
+  z.custom<Parameters<T['implement']>[0]>((fn: any) => schema.implement(fn))
+// Schema for the Logger interface
+const LoggerSchema = z.object({
+  debug: z.function({
+    input: [z.any(), z.string().optional()],
+    output: z.void(),
+  }),
+  info: z.function({
+    input: [z.any(), z.string().optional()],
+    output: z.void(),
+  }),
+  warn: z.function({
+    input: [z.any(), z.string().optional()],
+    output: z.void(),
+  }),
+  error: z.function({
+    input: [z.any(), z.string().optional()],
+    output: z.void(),
+  }),
+})
+
+// Schema for validating handleSteps function signature
+const HandleStepsSchema = functionSchema(
+  z.function({
+    input: [
+      z.object({
+        agentState: z.object({
+          agentId: z.string(),
+          parentId: z.string(),
+          messageHistory: z.array(z.any()),
+        }),
+        prompt: z.string().optional(),
+        params: z.any().optional(),
+      }),
+      LoggerSchema.optional(),
+    ],
+    output: z.any(),
+  }),
+).optional()
+
+// Validates the Typescript template file.
+export const DynamicAgentDefinitionSchema = z.object({
+  id: z
+    .string()
+    .regex(
+      /^[a-z0-9-]+$/,
+      'Agent ID must contain only lowercase letters, numbers, and hyphens',
+    ), // The unique identifier for this agent
+  version: z.string().optional(),
+  publisher: z.string().optional(),
+
+  // Required fields for new agents
+  displayName: z.string(),
+  model: z.string(),
+  reasoningOptions: z
+    .object({
+      enabled: z.boolean().optional(),
+      exclude: z.boolean().optional(),
+    })
+    .and(
+      z.union([
+        z.object({ max_tokens: z.number() }),
+        z.object({
+          effort: z.enum(['high', 'medium', 'low', 'minimal', 'none']),
+        }),
+      ]),
+    )
+    .optional(),
+  providerOptions: z
+    .object({
+      order: z.array(z.string()).optional(),
+      allow_fallbacks: z.boolean().optional(),
+      require_parameters: z.boolean().optional(),
+      data_collection: z.enum(['allow', 'deny']).optional(),
+      only: z.array(z.string()).optional(),
+      ignore: z.array(z.string()).optional(),
+      quantizations: z
+        .array(
+          z.enum([
+            'int4',
+            'int8',
+            'fp4',
+            'fp6',
+            'fp8',
+            'fp16',
+            'bf16',
+            'fp32',
+            'unknown',
+          ]),
+        )
+        .optional(),
+      sort: z.enum(['price', 'throughput', 'latency']).optional(),
+      max_price: z
+        .object({
+          prompt: z.union([z.number(), z.string()]).optional(),
+          completion: z.union([z.number(), z.string()]).optional(),
+          image: z.union([z.number(), z.string()]).optional(),
+          audio: z.union([z.number(), z.string()]).optional(),
+          request: z.union([z.number(), z.string()]).optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+
+  // Tools and spawnable agents
+  mcpServers: z.record(z.string(), mcpConfigSchema).default(() => ({})),
+  toolNames: z
+    .string()
+    .array()
+    .optional()
+    .default(() => []),
+  spawnableAgents: z
+    .array(z.string())
+    .optional()
+    .default(() => []),
+
+  // Input and output
+  inputSchema: InputSchemaObjectSchema,
+  includeMessageHistory: z.boolean().default(false),
+  inheritParentSystemPrompt: z.boolean().default(false),
+  windowedFileReads: z.boolean().optional(),
+  compactContext: z
+    .union([
+      z.boolean(),
+      z
+        .object({
+          cacheExpiryMs: z.number().nullish(),
+          cacheExpiryMinTokens: z.number().nullish(),
+        })
+        .strict(),
+    ])
+    .optional(),
+  outputMode: z
+    .enum(['last_message', 'all_messages', 'structured_output'])
+    .default('last_message'),
+  outputSchema: JsonObjectSchemaSchema.optional(), // Optional JSON schema for output validation
+
+  // Prompts
+  spawnerPrompt: z.string().optional(),
+  systemPrompt: z.string().optional(),
+  instructionsPrompt: z.string().optional(),
+  stepPrompt: z.string().optional(),
+
+  // Optional generator function for programmatic agents
+  handleSteps: z.union([z.string(), HandleStepsSchema]).optional(),
+})
+export type DynamicAgentDefinition = z.input<
+  typeof DynamicAgentDefinitionSchema
+>
+export type DynamicAgentDefinitionParsed = z.infer<
+  typeof DynamicAgentDefinitionSchema
+>
+
+export const DynamicAgentTemplateSchema = DynamicAgentDefinitionSchema.extend({
+  systemPrompt: z.string(),
+  instructionsPrompt: z.string(),
+  stepPrompt: z.string(),
+  handleSteps: z.string().optional(), // Converted to string after processing
+  // Live copy of handleSteps preserved for in-process execution (the string
+  // form of a bundled/minified function may not survive an eval round-trip).
+  // Never serialized: JSON.stringify drops function values. Typed loosely so
+  // the zod-inferred signature doesn't fight the StepHandler type.
+  handleStepsFn: z
+    .custom<(...args: any[]) => any>((v) => typeof v === 'function')
+    .optional(),
+})
+  .refine(
+    (data) => {
+      // If outputSchema is provided, outputMode must be explicitly set to 'structured_output'
+      if (data.outputSchema && data.outputMode !== 'structured_output') {
+        return false
+      }
+      return true
+    },
+    {
+      message:
+        "outputSchema requires outputMode to be explicitly set to 'structured_output'.",
+      path: ['outputMode'],
+    },
+  )
+  // Note(James): Disabled so that handleSteps could use set_output while the llm does not see or have access to the set_output tool.
+  // .refine(
+  //   (data) => {
+  //     // If outputMode is 'structured_output', 'set_output' tool must be included
+  //     if (
+  //       data.outputMode === 'structured_output' &&
+  //       !data.toolNames.includes('set_output')
+  //     ) {
+  //       return false
+  //     }
+  //     return true
+  //   },
+  //   {
+  //     message:
+  //       "outputMode 'structured_output' requires the 'set_output' tool. Add 'set_output' to toolNames.",
+  //     path: ['toolNames'],
+  //   },
+  // )
+  // Note(James): Disabled so that a parent agent can have set_output tool and 'last_message' outputMode while its subagents use 'structured_output'. (The set_output tool must be included in parent to preserver prompt caching.)
+  // .refine(
+  //   (data) => {
+  //     // If 'set_output' tool is included, outputMode must be 'structured_output'
+  //     if (
+  //       data.toolNames.includes('set_output') &&
+  //       data.outputMode !== 'structured_output'
+  //     ) {
+  //       return false
+  //     }
+  //     return true
+  //   },
+  //   {
+  //     message:
+  //       "'set_output' tool requires outputMode to be 'structured_output'. Change outputMode to 'structured_output' or remove 'set_output' from toolNames.",
+  //     path: ['outputMode'],
+  //   },
+  // )
+  .refine(
+    (data) => {
+      // A non-empty spawnableAgents array requires some way to spawn them:
+      // the 'spawn_agents' or 'spawn_agent_inline' tool, or a programmatic
+      // handleSteps generator (which can yield spawn tool calls without the
+      // LLM having access to the tools).
+      if (
+        data.spawnableAgents.length > 0 &&
+        !data.toolNames.includes('spawn_agents') &&
+        !data.toolNames.includes('spawn_agent_inline') &&
+        !data.handleSteps &&
+        !data.handleStepsFn
+      ) {
+        return false
+      }
+      return true
+    },
+    {
+      message:
+        "Non-empty spawnableAgents array requires the 'spawn_agents' tool. Add 'spawn_agents' to toolNames (or spawn programmatically via handleSteps) or remove spawnableAgents.",
+      path: ['toolNames'],
+    },
+  )
+  .refine(
+    (data) => {
+      // If inheritParentSystemPrompt is true, systemPrompt must be empty or undefined
+      if (
+        data.inheritParentSystemPrompt &&
+        data.systemPrompt &&
+        data.systemPrompt.trim() !== ''
+      ) {
+        return false
+      }
+      return true
+    },
+    {
+      message:
+        'Cannot specify both systemPrompt and inheritParentSystemPrompt. When inheritParentSystemPrompt is true, systemPrompt must be empty.',
+      path: ['systemPrompt'],
+    },
+  )
+export type DynamicAgentTemplate = z.infer<typeof DynamicAgentTemplateSchema>

package/vendor/@anvil/common/src/types/filesystem.ts

@@ -0,0 +1,10 @@
+import type fs from 'fs'
+
+/** File system used for Anvil SDK.
+ *
+ * Compatible with `fs.promises` from the `'fs'` module.
+ */
+export type AnvilFileSystem = Pick<
+  typeof fs.promises,
+  'mkdir' | 'readdir' | 'readFile' | 'stat' | 'unlink' | 'writeFile'
+>

package/vendor/@anvil/common/src/types/function-params.ts

@@ -0,0 +1,33 @@
+import type { UnionToIntersection } from 'bun-types/vendor/expect-type'
+
+type Prettify<T> = {
+  [K in keyof T]: T[K]
+} & {}
+
+type StripExact<T> = T extends infer U & { [x: string]: never } ? U : T
+
+type ParamsOfFunction<T> = T extends (params: infer C) => any
+  ? StripExact<C>
+  : never
+
+type IsUnion<T, U = T> = T extends any ? ([U] extends [T] ? false : true) : false
+type ParamsOfArray<T> = UnionToIntersection<
+  T extends [infer fn, ...infer rest]
+    ? ParamsOfFunction<fn> | ParamsOfArray<rest>
+    : {}
+>
+type ParamsOfUnion<T> = IsUnion<T> extends true
+  ? UnionToIntersection<ParamsOfFunction<T>>
+  : ParamsOfFunction<T>
+
+export type ParamsOf<T> = Prettify<
+  T extends any[] ? ParamsOfArray<T> : ParamsOfUnion<T>
+>
+
+export type OptionalFields<T, K extends keyof T> = Prettify<
+  Omit<T, K> & Partial<Pick<T, K>>
+>
+
+export type ParamsExcluding<T, K extends keyof ParamsOf<T>> = Prettify<
+  Omit<ParamsOf<T>, K>
+>

package/vendor/@anvil/common/src/types/grant.ts

@@ -0,0 +1,20 @@
+export type GrantType =
+  | 'free'
+  | 'referral'
+  | 'referral_legacy'
+  | 'subscription'
+  | 'purchase'
+  | 'admin'
+  | 'organization'
+  | 'ad' // Credits earned from ads (impressions, clicks, acquisitions, etc.)
+
+export const GrantTypeValues = [
+  'free',
+  'referral',
+  'referral_legacy',
+  'subscription',
+  'purchase',
+  'admin',
+  'organization',
+  'ad',
+] as const