howone 0.1.28 → 0.1.29

package/package.json

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

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

@@ -62,27 +62,14 @@ type AiActionConfig<TInput, TOutput> = {
 ```ts
 type AiResult = {
   success: boolean
+  runId?: string
   /** 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
-    agentName?: string
-    timestamp: number
-  }>
-  toolExecutions: Array<{
-    toolCallId: string
-    toolName: string
-    args?: Record<string, unknown>
-    result?: unknown
-    durationMs?: number
-    cost?: number
-    timestamp: number
-  }>
+  finalResult: Record<string, unknown> | null  // run_complete.message
+  progressLogs: string[]                       // progress.message lines
   totalDuration: number
   errors: string[]
+  events: AiEvent[]
 }
 ```
 
@@ -98,42 +85,20 @@ type AiSession = {
 
 ### AiEvent (SSE events)
 
-All events share a common base, then carry a typed `payload`:
+All workflow execute SSE events use the current envelope shape:
 
 ```ts
 type AiEvent = {
-  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>
+  type: 'run_start' | 'progress' | 'run_complete' | 'run_error' | 'credit_insufficient'
+  event: AiEvent['type']
+  message: string | Record<string, unknown>
+  payload?: Record<string, unknown> // present for run_complete as a compatibility alias of message
 }
 ```
 
-**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`.
+For the full wire protocol, read `03-sdk/09-workflow-execute-sse.md`.
 
 ---
 
@@ -230,17 +195,12 @@ When an action omits `outputSchema`, `run()` returns the raw `AiResult` executio
 
 ```ts
 const result = await howone.ai.generateStory.run(input, {
-  onMessageChunk: (text) => {
-    console.log('chunk:', text)
-  },
-  onNodeStart: (event) => {
-    console.log(`Node ${event.node_name} started`)
-  },
-  onStateUpdate: (delta) => {
-    console.log('State delta:', delta)
+  onMessageChunk: (line) => {
+    appendLog(line)
   },
-  onProgress: (percent) => {
-    setProgress(percent)
+  onProgress: (percent, line) => {
+    if (line?.startsWith('[DISPLAY]')) setStatus(line.replace('[DISPLAY]', '').trim())
+    if (percent === 100) setProgress(100)
   },
   onError: (error) => {
     console.error('SSE error:', error)
@@ -302,27 +262,20 @@ const result = await session.result
 async function consumeEvents(input: GenerateStoryInput) {
   for await (const event of howone.ai.generateStory.events(input)) {
     switch (event.type) {
-      case 'ai_message_chunk':
-        // streaming LLM text delta
-        setOutput(prev => prev + (event.payload?.content_block?.text ?? event.payload?.content ?? ''))
+      case 'run_start':
+        setStatus('running')
         break
-      case 'node_start':
-        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 'state_update':
-        console.log('State delta:', event.payload?.delta)
+      case 'progress':
+        appendLog(String(event.message))
         break
       case 'run_complete':
-        console.log('Final result:', event.payload?.result)
+        console.log('Final result:', event.message)
         break
       case 'credit_insufficient':
-        showCreditError(event.payload?.details?.reason)
+        showCreditError(String(event.message))
         break
       case 'run_error':
-        showExecutionError(event.payload?.details?.reason)
+        showExecutionError(String(event.message))
         break
     }
   }
@@ -397,7 +350,7 @@ export const analyzeDataInputSchema = z.object({
 
 ```ts
 type SSEExecutionOptions = {
-  // Called for every parsed event with its SSE channel
+  // Called for every parsed workflow envelope. channel is always "workflow".
   onEvent?: (event: AiEvent, channel: string) => void
 
   // Lifecycle
@@ -408,23 +361,10 @@ type SSEExecutionOptions = {
   /** Workflow logic failed — show retry/support UI */
   onRunError?: (event: RunErrorEvent) => void
 
-  // Nodes
-  onNodeStart?: (event: NodeStartEvent) => void
-  onNodeComplete?: (event: NodeCompleteEvent) => void
-
-  // Messages — streaming LLM text
-  onMessageChunk?: (text: string, event: AiMessageChunkEvent) => void
-  onMessageEnd?: (event: AiMessageEndEvent) => void
-
-  // Tools
-  onToolCallStart?: (event: ToolCallStartEvent) => void
-  onToolCallEnd?: (event: ToolCallEndEvent) => void
-  onToolCallError?: (event: ToolCallErrorEvent) => void
-
-  // State — live output panel updates
-  onStateUpdate?: (delta: Record<string, unknown>, event: StateUpdateEvent) => void
+  // Progress log lines from progress.message
+  onMessageChunk?: (text: string, event: ProgressEvent) => void
 
-  // Progress percent 0-100
+  // Progress compatibility callback: progress lines fire as (0, message), success fires as (100)
   onProgress?: (percent: number, message?: string) => void
 
   // Internal transport log
@@ -448,6 +388,8 @@ type SSEExecutionOptions = {
 }
 ```
 
+> The current workflow execute SSE endpoint does not emit `node_start`, `tool_call_end`,
+> `state_update`, or `ai_message_chunk`. Do not write generated app code that expects those events.
 > `onCreditInsufficient` and `onRunError` are **mutually exclusive** terminal events.
 > Do not use a generic `onError` to distinguish them — use the dedicated callbacks.
 

package/templates/vite/.howone/skills/howone/03-sdk/09-workflow-execute-sse.md

@@ -0,0 +1,105 @@
+# Workflow Execute SSE
+
+Use this reference for `@howone/sdk` AI action streaming and raw workflow execution calls.
+
+## Endpoint Contract
+
+The SDK uses the current workflow execute SSE endpoint:
+
+| Method | Path |
+|---|---|
+| `POST` | `/workflow/execute/{project_short_id}/{config_id}` |
+
+The request body is:
+
+```json
+{
+  "inputs": {},
+  "priority": "normal"
+}
+```
+
+`priority` is optional. All requests require `Authorization: Bearer <JWT>`.
+
+The successful HTTP response includes:
+
+| Header | Meaning |
+|---|---|
+| `Content-Type: text/event-stream` | Streaming response |
+| `X-Run-Id` | Execution task id for status/cancel follow-up |
+
+Do not use or generate code for old endpoints such as
+`/workflow/{appId}/{workflowId}/execute_sse`.
+
+## Wire Format
+
+Frames contain only a `data:` line and a blank line:
+
+```text
+data: {"id":"evt_8ae6d6e8a4ea","event":"run_start","message":"execution with sse is started"}
+
+data: {"id":"evt_241ff985450b","event":"progress","message":"[DISPLAY] Executing node: Extract"}
+
+data: {"id":"evt_f3a1b2c3d4e5","event":"run_complete","message":{"video_url":"https://..."}}
+```
+
+There are no separate SSE `event:` or `id:` lines. The JSON envelope owns those fields.
+
+## Envelope
+
+```ts
+type WorkflowSseEnvelope = {
+  id: string
+  event: 'run_start' | 'progress' | 'run_complete' | 'run_error' | 'credit_insufficient'
+  message: string | Record<string, unknown>
+}
+```
+
+Event meanings:
+
+| Event | Message | Meaning |
+|---|---|---|
+| `run_start` | string | Stream opened and execution started. |
+| `progress` | string | One worker log line. `[DISPLAY]` lines are intended for UI. |
+| `run_complete` | object | Final workflow-specific output. SDK maps this to `AiResult.finalResult`. |
+| `run_error` | string | Workflow failed. |
+| `credit_insufficient` | string | Billing/credit block. |
+
+The terminal event is exactly one of `run_complete`, `run_error`, or `credit_insufficient`.
+There is no `stream_end` event.
+
+## SDK Mapping
+
+`howone.ai.run(configId, inputs)` and typed action `.run()` call the endpoint above.
+
+`AiResult` maps the stream as:
+
+```ts
+type AiResult = {
+  success: boolean
+  runId?: string
+  outcome: 'success' | 'credit_insufficient' | 'run_error' | null
+  finalResult: Record<string, unknown> | null
+  progressLogs: string[]
+  errors: string[]
+  events: AiEvent[]
+}
+```
+
+For typed actions with an `outputSchema`, `.run()` returns the validated `run_complete.message`
+object directly.
+
+## Callback Rules
+
+- `onRunStart(event)` receives the `run_start` envelope.
+- `onMessageChunk(text, event)` receives each `progress.message` line.
+- `onProgress(0, message)` receives each progress line; `onProgress(100)` fires on success.
+- `onRunComplete(event, result)` receives `event.message` as the final object.
+- `onRunError(event)` receives `event.message` as the error string.
+- `onCreditInsufficient(event)` receives `event.message` as the credit error string.
+- `onEvent(event, 'workflow')` fires for every parsed envelope.
+
+Do not write UI code that expects `event.payload.result`, `event.payload.details.reason`,
+`node_start`, `tool_call_end`, `state_update`, or `ai_message_chunk`. Those belong to an old
+multi-channel protocol and are not part of the current workflow execute SSE contract.
+

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

@@ -6,6 +6,9 @@ workflow through `@howone/sdk`.
 This file answers: **how does `.howone/ai/manifest.json` become `src/lib/sdk.ts`, and how should UI
 call it?**
 
+For live stream wire details, read `03-sdk/09-workflow-execute-sse.md`. The current endpoint emits
+only `run_start`, `progress`, `run_complete`, `run_error`, and `credit_insufficient`.
+
 ## Binding Source
 
 Generate `src/lib/sdk.ts` from `.howone/ai/manifest.json`. Do not write AI bindings from memory,
@@ -117,11 +120,13 @@ Use `.stream()` when UI needs live output or cancellation:
 
 ```ts
 const session = howone.ai.generateStory.stream(input, {
-  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),
+  onMessageChunk: (line) => appendLog(line),
+  onProgress: (percent, line) => {
+    if (line?.startsWith('[DISPLAY]')) setStatus(line.replace('[DISPLAY]', '').trim())
+    if (percent === 100) setProgress(100)
+  },
+  onCreditInsufficient: (event) => showCreditError(event.message),
+  onRunError: (event) => showExecutionError(event.message),
   onError: (error) => setError(error.message),
   onComplete: (result) => setRawResult(result),
 })
@@ -134,20 +139,17 @@ Use `.events()` when code wants an async iterable:
 
 ```ts
 for await (const event of howone.ai.generateStory.events(input)) {
-  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 === 'progress') {
+    appendLog(String(event.message))
   }
   if (event.type === 'run_complete') {
-    setFinalResult(event.payload?.result)
+    setFinalResult(event.message)
   }
   if (event.type === 'credit_insufficient') {
-    showCreditError(event.payload?.details?.reason)
+    showCreditError(String(event.message))
   }
   if (event.type === 'run_error') {
-    showExecutionError(event.payload?.details?.reason)
+    showExecutionError(String(event.message))
   }
 }
 ```

package/templates/vite/.howone/skills/howone/SKILL.md

@@ -50,7 +50,7 @@ Read references by task shape. Prefer exact references over generic examples.
 - File upload: read `03-sdk/05-file-upload.md`.
 - Raw HTTP escape hatch: read `03-sdk/06-raw-http.md`.
 - App-side AI action calls after `.howone/ai/manifest.json` exists: read
-  `03-sdk/07-ai-action-calls.md`.
+  `03-sdk/07-ai-action-calls.md` and `03-sdk/09-workflow-execute-sse.md`.
 - External workflow create/update/status: read `04-ai/05-workflow-operations.md`.
 - Common AI feature templates: read `04-ai/06-ai-feature-playbooks.md`.
 
@@ -71,7 +71,7 @@ Before writing code, classify the touched surfaces:
 | AI capability or workflow design | `04-ai/01-ai-capability-architecture.md`, `04-ai/04-service-capability-catalog.md`, `04-ai/02-workflow-contract-rules.md` |
 | External workflow create/update/status | `04-ai/05-workflow-operations.md` |
 | Common AI feature examples | `04-ai/06-ai-feature-playbooks.md` |
-| AI manifest handoff to app code | `04-ai/03-ai-sdk-handoff.md`, `03-sdk/07-ai-action-calls.md` |
+| AI manifest handoff to app code | `04-ai/03-ai-sdk-handoff.md`, `03-sdk/07-ai-action-calls.md`, `03-sdk/09-workflow-execute-sse.md` |
 | File upload | `03-sdk/05-file-upload.md` |
 | Raw HTTP escape hatch | `03-sdk/06-raw-http.md` |
 | SDK extensibility / adapter boundaries | `03-sdk/08-extension-boundaries.md` |

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.20",
+    "@howone/sdk": "2.0.0-beta.21",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",