howone 0.1.11 → 0.1.13

package/templates/vite/.howone/skills/howone-sdk/references/03-ai-actions.md

@@ -0,0 +1,489 @@
+# AI Actions
+
+## Core Concepts
+
+- `defineAiAction(id, config)` declares a typed AI action from a workflow ID.
+- `defineAiActions({ ... })` groups multiple action definitions.
+- `withAiActions(client, actions)` binds them onto the composed client as `howone.ai.*`.
+- Each bound action exposes `.run()`, `.stream()`, and `.events()`.
+- Input/output are validated at runtime using zod schemas.
+
+---
+
+## Type System
+
+### AiActionConfig
+
+```ts
+type AiActionConfig<TInput, TOutput> = {
+  inputSchema?: z.ZodType<TInput>    // validates input before calling the workflow
+  outputSchema?: z.ZodType<TOutput>  // validates the full ExecutionResult envelope (see caution below)
+  mode?: 'run' | 'stream' | 'events' // default: supports all three modes
+}
+```
+
+### AiResult (ExecutionResult)
+
+```ts
+type AiResult = {
+  success: boolean
+  finalResult: Record<string, unknown> | null  // the workflow output payload
+  nodeExecutions: Array<{
+    nodeName: string
+    content: string
+    timestamp: number
+  }>
+  costUpdates: Array<{
+    token: number
+    totalToken: number
+    cost: number
+    totalCost: number
+    timestamp: number
+  }>
+  totalDuration: number
+  errors: string[]
+}
+```
+
+### AiSession (for stream)
+
+```ts
+type AiSession = {
+  result: Promise<AiResult>   // resolves when the stream completes
+  cancel: () => void          // abort the request (safe to call multiple times)
+  signal: AbortSignal
+}
+```
+
+### AiEvent (SSE events)
+
+```ts
+type AiEvent = {
+  type: string
+  data?: Record<string, unknown>
+  [key: string]: unknown
+}
+```
+
+---
+
+## Defining AI Actions
+
+### Basic action — input only, output unwrapped manually
+
+```ts
+import { defineAiAction, defineAiActions } from '@howone/sdk'
+import { z } from 'zod'
+
+export const generateStoryInputSchema = z.object({
+  topic: z.string().min(1),
+  ageRange: z.enum(['3-5', '6-8', '9-12']),
+  language: z.string().default('en'),
+})
+export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
+
+export const ai = defineAiActions({
+  generateStory: defineAiAction('generateStory', {
+    inputSchema: generateStoryInputSchema,
+  }),
+})
+```
+
+### Action with typed output (unwrap finalResult manually)
+
+```ts
+export const generateStoryOutputSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  summary: z.string(),
+})
+export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
+
+// Do NOT put outputSchema in defineAiAction unless it matches the full
+// AiResult envelope. Instead, cast finalResult after run():
+export const ai = defineAiActions({
+  generateStory: defineAiAction('generateStory', {
+    inputSchema: generateStoryInputSchema,
+    // outputSchema: omit — cast manually
+  }),
+})
+```
+
+### Multiple actions
+
+```ts
+export const ai = defineAiActions({
+  generateStory: defineAiAction('generateStory', {
+    inputSchema: z.object({ topic: z.string(), language: z.string() }),
+  }),
+  translateText: defineAiAction('translateText', {
+    inputSchema: z.object({ text: z.string(), targetLang: z.string() }),
+  }),
+  summarizeArticle: defineAiAction('summarizeArticle', {
+    inputSchema: z.object({ url: z.string().url(), maxWords: z.number().int().optional() }),
+  }),
+  analyzeImage: defineAiAction('analyzeImage', {
+    inputSchema: z.object({ imageUrl: z.string().url(), prompt: z.string().optional() }),
+  }),
+})
+```
+
+---
+
+## Calling AI Actions
+
+### run() — await the full result
+
+```ts
+import howone, { type GenerateStoryInput, type GenerateStoryOutput } from '@/lib/sdk'
+
+async function generateStory(input: GenerateStoryInput) {
+  const result = await howone.ai.generateStory.run(input)
+  // result is AiResult
+
+  if (!result.success) {
+    throw new Error(result.errors.join(', '))
+  }
+
+  // Cast finalResult to your output type
+  const output = result.finalResult as GenerateStoryOutput
+  return output
+}
+```
+
+### run() — with SSE callbacks
+
+```ts
+const result = await howone.ai.generateStory.run(input, {
+  onStreamChunk: (chunk) => {
+    console.log('chunk:', chunk)
+  },
+  onNodeStart: (nodeName, content) => {
+    console.log(`Node ${nodeName} started`)
+  },
+  onCostUpdate: (cost) => {
+    console.log(`Tokens used: ${cost.totalToken}`)
+  },
+  onProgress: (progress) => {
+    setProgress(progress)
+  },
+  onError: (error) => {
+    console.error('SSE error:', error)
+  },
+})
+```
+
+### stream() — start and control a session
+
+```ts
+function startStream(input: GenerateStoryInput) {
+  const session = howone.ai.generateStory.stream(input, {
+    onStreamChunk: (chunk) => {
+      setOutput(prev => prev + chunk)
+    },
+    onComplete: (result) => {
+      console.log('Done:', result.finalResult)
+    },
+    onError: (error) => {
+      console.error('Error:', error)
+    },
+  })
+
+  // session.result is a Promise<AiResult>
+  // session.cancel() aborts the stream
+  return session
+}
+
+// Cancel mid-stream
+const session = startStream(myInput)
+setTimeout(() => session.cancel(), 5000)
+
+// Or await the full result via the session
+const result = await session.result
+```
+
+### events() — async iterable SSE events
+
+```ts
+async function consumeEvents(input: GenerateStoryInput) {
+  for await (const event of howone.ai.generateStory.events(input)) {
+    switch (event.type) {
+      case 'stream_content':
+        setOutput(prev => prev + (event.data?.delta ?? ''))
+        break
+      case 'node_start':
+        console.log('Node started:', event.data?.nodeName)
+        break
+      case 'cost_update':
+        console.log('Cost:', event.data?.totalCost)
+        break
+      case 'complete':
+        console.log('Final result:', event.data)
+        break
+    }
+  }
+}
+```
+
+---
+
+## zod Schema Patterns
+
+### JSON Schema → zod mapping
+
+Generate zod from `.howone/ai/manifest.json` inputSchema / outputSchema fields:
+
+| JSON Schema type | zod |
+|---|---|
+| `string` | `z.string()` |
+| `number` | `z.number()` |
+| `integer` | `z.number().int()` |
+| `boolean` | `z.boolean()` |
+| `array of string` | `z.array(z.string())` |
+| `array of object` | `z.array(z.object({ ... }))` |
+| `object` | `z.object({ ... })` |
+| `enum` (string) | `z.enum(['a', 'b', 'c'])` |
+| optional field (not in `required[]`) | `.optional()` on the field |
+| field with default | `.default(value)` |
+| nullable field | `.nullable()` |
+
+### Real examples
+
+```ts
+// Simple text generation
+export const summarizeInputSchema = z.object({
+  text: z.string().min(1).max(10000),
+  maxWords: z.number().int().min(10).max(500).optional(),
+  language: z.string().default('en'),
+})
+
+// Image analysis
+export const analyzeImageInputSchema = z.object({
+  imageUrl: z.string().url(),
+  prompt: z.string().optional(),
+  outputFormat: z.enum(['json', 'text', 'markdown']).default('json'),
+})
+
+// Multi-step generation with options
+export const generatePostInputSchema = z.object({
+  topic: z.string().min(1),
+  tone: z.enum(['professional', 'casual', 'humorous']),
+  platform: z.enum(['twitter', 'linkedin', 'blog']),
+  keywords: z.array(z.string()).min(1).max(10),
+  includeHashtags: z.boolean().default(true),
+})
+
+// Nested object
+export const analyzeDataInputSchema = z.object({
+  dataset: z.array(
+    z.object({
+      id: z.string(),
+      value: z.number(),
+      label: z.string().optional(),
+    })
+  ),
+  aggregationType: z.enum(['sum', 'average', 'median', 'max', 'min']),
+  groupBy: z.string().optional(),
+})
+```
+
+---
+
+## SSEExecutionOptions — All Callbacks
+
+```ts
+type SSEExecutionOptions = {
+  // Called for every raw SSE event
+  onEvent?: (event: { type: string; data?: Record<string, unknown> }) => void
+
+  // Called when a workflow node starts executing
+  onNodeStart?: (nodeName: string, content: string) => void
+
+  // Called with streaming text delta (for LLM text generation nodes)
+  onStreamContent?: (delta: string) => void
+
+  // Called with each raw stream chunk
+  onStreamChunk?: (chunk: string) => void
+
+  // Called when token/cost counters update
+  onCostUpdate?: (cost: {
+    token: number
+    totalToken: number
+    cost: number
+    totalCost: number
+    timestamp: number
+  }) => void
+
+  // Called with an estimated progress value (0–100)
+  onProgress?: (progress: number) => void
+
+  // Called with log messages from workflow nodes
+  onLog?: (message: string) => void
+
+  // Called if an error occurs
+  onError?: (error: Error) => void
+
+  // Called when the workflow completes (same as awaiting run())
+  onComplete?: (result: AiResult) => void
+
+  // Abort signal — connect to an AbortController for cancellation
+  signal?: AbortSignal
+
+  // Limit-exceeded handler (overrides client-level config)
+  limitExceeded?: {
+    onLimitExceeded?: (context: LimitExceededContext) => void
+    showUpgradeToast?: boolean
+    upgradeUrl?: string
+  }
+}
+```
+
+---
+
+## AiSchemaValidationError
+
+Thrown by `run()` when input or output schema validation fails.
+
+```ts
+import { AiSchemaValidationError } from '@howone/sdk'
+
+try {
+  const result = await howone.ai.generateStory.run(input)
+} catch (err) {
+  if (err instanceof AiSchemaValidationError) {
+    console.error('Validation failed:')
+    console.error('  Action:', err.actionId)          // 'generateStory'
+    console.error('  Direction:', err.direction)       // 'input' | 'output'
+    console.error('  Issues:', err.issues)             // [{ path, message, code }]
+  }
+}
+```
+
+---
+
+## AI Result Persistence
+
+When AI-generated content should be saved to an entity:
+
+```ts
+// 1. Run the AI action
+const result = await howone.ai.generateStory.run({
+  topic: 'Dragons and magic',
+  ageRange: '6-8',
+})
+
+if (!result.success) throw new Error(result.errors.join(', '))
+
+const output = result.finalResult as GenerateStoryOutput
+
+// 2. Save to entity
+const saved = await howone.entities.Story.create({
+  title: output.title,
+  content: output.content,
+  authorId: currentUser.id,
+  status: 'draft',
+  wordCount: output.content.split(' ').length,
+  // Track generation metadata
+  promptTopic: 'Dragons and magic',
+  generatedAt: new Date().toISOString(),
+})
+```
+
+---
+
+## React Patterns
+
+### One-shot run with loading state
+
+```tsx
+import { useState } from 'react'
+import { AiSchemaValidationError } from '@howone/sdk'
+import howone, { type GenerateStoryInput, type GenerateStoryOutput } from '@/lib/sdk'
+
+function GenerateStoryButton({ input }: { input: GenerateStoryInput }) {
+  const [loading, setLoading] = useState(false)
+  const [result, setResult] = useState<GenerateStoryOutput | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  async function handleGenerate() {
+    setLoading(true)
+    setError(null)
+    try {
+      const res = await howone.ai.generateStory.run(input)
+      if (!res.success) throw new Error(res.errors.join(', '))
+      setResult(res.finalResult as GenerateStoryOutput)
+    } catch (err) {
+      if (err instanceof AiSchemaValidationError) {
+        setError(`Validation error: ${err.issues.map(i => i.message).join(', ')}`)
+      } else {
+        setError(err instanceof Error ? err.message : 'Unknown error')
+      }
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <>
+      <button onClick={handleGenerate} disabled={loading}>
+        {loading ? 'Generating...' : 'Generate Story'}
+      </button>
+      {result && <div>{result.title}</div>}
+      {error && <div className="error">{error}</div>}
+    </>
+  )
+}
+```
+
+### Streaming with live text output
+
+```tsx
+import { useRef, useState } from 'react'
+import howone, { type GenerateStoryInput } from '@/lib/sdk'
+import type { AiSession } from '@howone/sdk'
+
+function StreamingStoryGenerator({ input }: { input: GenerateStoryInput }) {
+  const [text, setText] = useState('')
+  const [streaming, setStreaming] = useState(false)
+  const sessionRef = useRef<AiSession | null>(null)
+
+  function startGeneration() {
+    setText('')
+    setStreaming(true)
+
+    sessionRef.current = howone.ai.generateStory.stream(input, {
+      onStreamChunk: (chunk) => setText(prev => prev + chunk),
+      onComplete: () => setStreaming(false),
+      onError: (err) => {
+        console.error(err)
+        setStreaming(false)
+      },
+    })
+  }
+
+  function cancelGeneration() {
+    sessionRef.current?.cancel()
+    setStreaming(false)
+  }
+
+  return (
+    <>
+      <button onClick={startGeneration} disabled={streaming}>Start</button>
+      <button onClick={cancelGeneration} disabled={!streaming}>Cancel</button>
+      <pre>{text}</pre>
+    </>
+  )
+}
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Pattern |
+|---|---|
+| `howone.ai.run.generateStory(input)` | `howone.ai.generateStory.run(input)` |
+| Action named `run`, `stream`, or `events` | Rename to e.g. `executeWorkflow`, `streamContent` |
+| `outputSchema: z.object({ title: z.string() })` expecting `finalResult` shape | Omit `outputSchema`; cast `result.finalResult` manually |
+| Not checking `result.success` before using `finalResult` | Always check `if (!result.success) throw new Error(...)` |
+| Calling `howone.ai.generateStory.run(input)` inside JSX render | Move to event handler or useEffect |