howone 0.1.15 → 0.1.16

package/package.json

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

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

@@ -1,5 +1,32 @@
 # AI Actions
 
+## Manifest Contract — Read This First
+
+**`src/lib/sdk.ts` must be generated from `.howone/ai/manifest.json`. Do not write it from memory or from generic examples.**
+
+For every capability in `manifest.json`:
+1. Read `name`, `workflowId`, `inputSchema`, `outputSchema`
+2. Generate a zod schema from `inputSchema.properties`
+3. Call `defineAiAction(name, { workflowId, inputSchema })` — **`workflowId` is mandatory**
+
+Without `workflowId`, the SDK falls back to using the action name as the URL segment. Action names are not UUIDs — the EAX server will reject the call with "invalid input syntax for type uuid".
+
+## When to Write SDK Bindings
+
+**Do NOT write `defineAiAction` until `.howone/ai/manifest.json` contains a confirmed `workflowId`.**
+
+Correct sequence:
+1. `ai_capability_design` — design the capability schema
+2. `sync_ai_artifacts` — sync manifest to disk
+3. `external_ai_capability` — submit workflow to EAX; returns confirmed `workflowId`
+4. Confirmed `workflowId` is written back to the backend capability record
+5. `sync_ai_artifacts` again — manifest now contains `workflowId`
+6. Read `.howone/ai/manifest.json` → write `src/lib/sdk.ts` with `workflowId`
+
+Building without errors does **not** mean the AI workflow binding is correct. A missing `workflowId` causes a runtime UUID error at the EAX execution call.
+
+---
+
 ## Core Concepts
 
 - `defineAiAction(id, config)` declares a typed AI action from a workflow ID.
@@ -16,6 +43,7 @@
 
 ```ts
 type AiActionConfig<TInput, TOutput> = {
+  workflowId: string                 // REQUIRED — UUID from manifest.json. Without this, SDK uses action name as URL segment (not a UUID → EAX rejects).
   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
@@ -69,12 +97,13 @@ type AiEvent = {
 
 ## Defining AI Actions
 
-### Basic action — input only, output unwrapped manually
+### Basic action — always include workflowId from manifest.json
 
 ```ts
 import { defineAiAction, defineAiActions } from '@howone/sdk'
 import { z } from 'zod'
 
+// Source: .howone/ai/manifest.json → capabilities[0].inputSchema.properties
 export const generateStoryInputSchema = z.object({
   topic: z.string().min(1),
   ageRange: z.enum(['3-5', '6-8', '9-12']),
@@ -82,8 +111,10 @@ export const generateStoryInputSchema = z.object({
 })
 export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
 
+// workflowId from .howone/ai/manifest.json → capabilities[0].workflowId
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
+    workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2', // ← from manifest.json
     inputSchema: generateStoryInputSchema,
   }),
 })
@@ -103,31 +134,39 @@ export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 // AiResult envelope. Instead, cast finalResult after run():
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
+    workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2', // ← from manifest.json
     inputSchema: generateStoryInputSchema,
     // outputSchema: omit — cast manually
   }),
 })
 ```
 
-### Multiple actions
+### Multiple actions — each must have its own workflowId from manifest.json
 
 ```ts
+// Each workflowId is the UUID from .howone/ai/manifest.json for that capability
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
+    workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2',
     inputSchema: z.object({ topic: z.string(), language: z.string() }),
   }),
   translateText: defineAiAction('translateText', {
+    workflowId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
     inputSchema: z.object({ text: z.string(), targetLang: z.string() }),
   }),
   summarizeArticle: defineAiAction('summarizeArticle', {
+    workflowId: 'f9e8d7c6-b5a4-3210-fedc-ba9876543210',
     inputSchema: z.object({ url: z.string().url(), maxWords: z.number().int().optional() }),
   }),
   analyzeImage: defineAiAction('analyzeImage', {
+    workflowId: '11223344-5566-7788-99aa-bbccddeeff00',
     inputSchema: z.object({ imageUrl: z.string().url(), prompt: z.string().optional() }),
   }),
 })
 ```
 
+> **Note**: The UUIDs above are placeholders. Always copy the exact value from `.howone/ai/manifest.json`.
+
 ---
 
 ## Calling AI Actions
@@ -482,6 +521,9 @@ function StreamingStoryGenerator({ input }: { input: GenerateStoryInput }) {
 
 | Mistake | Correct Pattern |
 |---|---|
+| `defineAiAction('generateStory', { inputSchema })` — no `workflowId` | Always include `workflowId` from `manifest.json`; SDK falls back to action name, which is not a UUID → EAX rejects |
+| Writing `src/lib/sdk.ts` before `sync_ai_artifacts` has a confirmed `workflowId` | Run `external_ai_capability` → `sync_ai_artifacts` first; only write bindings after manifest has `workflowId` |
+| Hardcoding `workflowId` from memory or guessing | Always read from `.howone/ai/manifest.json` — copy the exact UUID |
 | `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 |

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

@@ -19,6 +19,7 @@ export const entities = defineEntities({
 export const ai = defineAiActions({
   // Add generated AI action bindings here, for example:
   // generateImage: defineAiAction("generateImage", {
+  //   workflowId: "<workflow-uuid>", // workflow ID for this capability
   //   inputSchema: generateImageInputSchema,
   //   outputSchema: generateImageOutputSchema,
   // }),