howone 0.1.25 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/{howone-sdk → howone}/03-sdk/07-ai-action-calls.md

@@ -62,17 +62,23 @@ type AiActionConfig<TInput, TOutput> = {
 ```ts
 type AiResult = {
   success: boolean
-  finalResult: Record<string, unknown> | null  // the workflow output payload
+  /** Terminal outcome of the run */
+  outcome: 'success' | 'credit_insufficient' | 'run_error' | null
+  finalResult: Record<string, unknown> | null  // the workflow output payload (from run_complete)
+  /** Accumulated state data from state_update / state_snapshot events */
+  stateData: Record<string, unknown>
   nodeExecutions: Array<{
     nodeName: string
-    content: string
+    agentName?: string
     timestamp: number
   }>
-  costUpdates: Array<{
-    token: number
-    totalToken: number
-    cost: number
-    totalCost: number
+  toolExecutions: Array<{
+    toolCallId: string
+    toolName: string
+    args?: Record<string, unknown>
+    result?: unknown
+    durationMs?: number
+    cost?: number
     timestamp: number
   }>
   totalDuration: number
@@ -92,14 +98,43 @@ type AiSession = {
 
 ### AiEvent (SSE events)
 
+All events share a common base, then carry a typed `payload`:
+
 ```ts
 type AiEvent = {
-  type: string
-  data?: Record<string, unknown>
-  [key: string]: unknown
+  type: string          // see channel catalog below
+  id: string
+  run_id: string
+  workflow_id: string
+  timestamp: string     // ISO 8601 UTC
+  seq: number           // monotonic ordering within the run
+  // Context fields — present when applicable
+  node_name?: string
+  node_status?: 'pending' | 'running' | 'completed' | 'failed'
+  action_step?: number
+  agent_name?: string
+  action_name?: string
+  agent_loop_step?: number
+  message_id?: string
+  tool_call_id?: string
+  payload?: Record<string, unknown>
 }
 ```
 
+**SSE Channels and event types:**
+
+| Channel | Key event types |
+|---|---|
+| `lifecycle` | `run_start`, `run_complete`, `credit_insufficient`, `run_error` |
+| `node` | `node_scheduled`, `node_start`, `node_complete`, `node_failed` |
+| `action` | `action_scheduled`, `action_start`, `action_complete` |
+| `messages` | `ai_message_start`, `ai_message_chunk`, `ai_message_end`, `action_output` |
+| `tools` | `tool_call_start`, `tool_call_end`, `tool_call_error` |
+| `state` | `state_update`, `state_snapshot` |
+| `metadata` | `progress` |
+
+Stream terminates after exactly one of: `run_complete`, `credit_insufficient`, or `run_error`.
+
 ---
 
 ## Defining AI Actions
@@ -195,17 +230,17 @@ When an action omits `outputSchema`, `run()` returns the raw `AiResult` executio
 
 ```ts
 const result = await howone.ai.generateStory.run(input, {
-  onStreamChunk: (chunk) => {
-    console.log('chunk:', chunk)
+  onMessageChunk: (text) => {
+    console.log('chunk:', text)
   },
-  onNodeStart: (nodeName, content) => {
-    console.log(`Node ${nodeName} started`)
+  onNodeStart: (event) => {
+    console.log(`Node ${event.node_name} started`)
   },
-  onCostUpdate: (cost) => {
-    console.log(`Tokens used: ${cost.totalToken}`)
+  onStateUpdate: (delta) => {
+    console.log('State delta:', delta)
   },
-  onProgress: (progress) => {
-    setProgress(progress)
+  onProgress: (percent) => {
+    setProgress(percent)
   },
   onError: (error) => {
     console.error('SSE error:', error)
@@ -237,8 +272,8 @@ try {
 ```ts
 function startStream(input: GenerateStoryInput) {
   const session = howone.ai.generateStory.stream(input, {
-    onStreamChunk: (chunk) => {
-      setOutput(prev => prev + chunk)
+    onMessageChunk: (text) => {
+      setOutput(prev => prev + text)
     },
     onComplete: (result) => {
       console.log('Done:', result.finalResult)
@@ -267,17 +302,27 @@ const result = await session.result
 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 ?? ''))
+      case 'ai_message_chunk':
+        // streaming LLM text delta
+        setOutput(prev => prev + (event.payload?.content_block?.text ?? event.payload?.content ?? ''))
         break
       case 'node_start':
-        console.log('Node started:', event.data?.nodeName)
+        console.log('Node started:', event.node_name)
+        break
+      case 'tool_call_end':
+        console.log('Tool result:', event.tool_call_id, event.payload?.result)
         break
-      case 'cost_update':
-        console.log('Cost:', event.data?.totalCost)
+      case 'state_update':
+        console.log('State delta:', event.payload?.delta)
         break
-      case 'complete':
-        console.log('Final result:', event.data)
+      case 'run_complete':
+        console.log('Final result:', event.payload?.result)
+        break
+      case 'credit_insufficient':
+        showCreditError(event.payload?.details?.reason)
+        break
+      case 'run_error':
+        showExecutionError(event.payload?.details?.reason)
         break
     }
   }
@@ -352,37 +397,43 @@ export const analyzeDataInputSchema = z.object({
 
 ```ts
 type SSEExecutionOptions = {
-  // Called for every raw SSE event
-  onEvent?: (event: { type: string; data?: Record<string, unknown> }) => void
+  // Called for every parsed event with its SSE channel
+  onEvent?: (event: AiEvent, channel: string) => void
 
-  // Called when a workflow node starts executing
-  onNodeStart?: (nodeName: string, content: string) => void
+  // Lifecycle
+  onRunStart?: (event: RunStartEvent) => void
+  onRunComplete?: (event: RunCompleteEvent, result: AiResult) => void
+  /** Credits / quota exhausted — show top-up UI, NOT a generic error */
+  onCreditInsufficient?: (event: CreditInsufficientEvent) => void
+  /** Workflow logic failed — show retry/support UI */
+  onRunError?: (event: RunErrorEvent) => void
 
-  // Called with streaming text delta (for LLM text generation nodes)
-  onStreamContent?: (delta: string) => void
+  // Nodes
+  onNodeStart?: (event: NodeStartEvent) => void
+  onNodeComplete?: (event: NodeCompleteEvent) => void
 
-  // Called with each raw stream chunk
-  onStreamChunk?: (chunk: string) => void
+  // Messages — streaming LLM text
+  onMessageChunk?: (text: string, event: AiMessageChunkEvent) => void
+  onMessageEnd?: (event: AiMessageEndEvent) => void
 
-  // Called when token/cost counters update
-  onCostUpdate?: (cost: {
-    token: number
-    totalToken: number
-    cost: number
-    totalCost: number
-    timestamp: number
-  }) => void
+  // Tools
+  onToolCallStart?: (event: ToolCallStartEvent) => void
+  onToolCallEnd?: (event: ToolCallEndEvent) => void
+  onToolCallError?: (event: ToolCallErrorEvent) => void
 
-  // Called with an estimated progress value (0–100)
-  onProgress?: (progress: number) => void
+  // State — live output panel updates
+  onStateUpdate?: (delta: Record<string, unknown>, event: StateUpdateEvent) => void
 
-  // Called with log messages from workflow nodes
+  // Progress percent 0-100
+  onProgress?: (percent: number, message?: string) => void
+
+  // Internal transport log
   onLog?: (message: string) => void
 
-  // Called if an error occurs
+  // Called on any error (credit or execution)
   onError?: (error: Error) => void
 
-  // Called when the workflow completes with the raw execution envelope
+  // Called when the stream closes (success or error)
   onComplete?: (result: AiResult) => void
 
   // Abort signal — connect to an AbortController for cancellation
@@ -397,6 +448,9 @@ type SSEExecutionOptions = {
 }
 ```
 
+> `onCreditInsufficient` and `onRunError` are **mutually exclusive** terminal events.
+> Do not use a generic `onError` to distinguish them — use the dedicated callbacks.
+
 ---
 
 ## AiSchemaValidationError

package/templates/vite/.howone/skills/{howone-sdk → howone}/04-ai/03-ai-sdk-handoff.md

@@ -117,8 +117,11 @@ Use `.stream()` when UI needs live output or cancellation:
 
 ```ts
 const session = howone.ai.generateStory.stream(input, {
-  onStreamChunk: (chunk) => setDraft((prev) => prev + chunk),
-  onProgress: (progress) => setProgress(progress),
+  onMessageChunk: (text) => setDraft((prev) => prev + text),
+  onStateUpdate: (delta) => updateLivePanel(delta),
+  onProgress: (percent) => setProgress(percent),
+  onCreditInsufficient: (event) => showCreditError(event.payload?.details?.reason),
+  onRunError: (event) => showExecutionError(event.payload?.details?.reason),
   onError: (error) => setError(error.message),
   onComplete: (result) => setRawResult(result),
 })
@@ -131,8 +134,20 @@ Use `.events()` when code wants an async iterable:
 
 ```ts
 for await (const event of howone.ai.generateStory.events(input)) {
-  if (event.type === 'stream_content') {
-    appendText(String(event.data?.delta ?? ''))
+  if (event.type === 'ai_message_chunk') {
+    appendText(String(event.payload?.content_block?.text ?? event.payload?.content ?? ''))
+  }
+  if (event.type === 'state_update') {
+    updateLivePanel(event.payload?.delta ?? {})
+  }
+  if (event.type === 'run_complete') {
+    setFinalResult(event.payload?.result)
+  }
+  if (event.type === 'credit_insufficient') {
+    showCreditError(event.payload?.details?.reason)
+  }
+  if (event.type === 'run_error') {
+    showExecutionError(event.payload?.details?.reason)
   }
 }
 ```

package/templates/vite/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
-    "@howone/sdk": "2.0.0-beta.18",
+    "@howone/sdk": "2.0.0-beta.20",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/templates/vite/src/lib/sdk.ts

@@ -22,7 +22,7 @@ export const ai = defineAiActions({
   // Do not paste JSON Schema objects from .howone/ai/manifest.json here directly.
   // With outputSchema configured, howone.ai.<action>.run() returns the validated finalResult payload.
   // generateImage: defineAiAction("generateImage", {
-  //   workflowId: "<workflow-uuid>", // workflow ID for this capability
+  //   workflowId: "<workflow-config-id>", // config_id for this capability
   //   inputSchema: generateImageInputSchema,
   //   outputSchema: generateImageOutputSchema,
   // }),