howone 0.2.2 → 0.2.5

package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md

@@ -1,41 +1,27 @@
-# AI Manifest Handoff (App SDK)
+# AI Manifest Handoff
 
-Use this reference after AI capability artifacts have been synced and app code must call the
-workflow through `@howone/sdk`.
+Use this track after `sync_ai_artifacts` and external workflow submission. It is the short handoff
+from `.howone/ai/manifest.json` to `src/lib/sdk.ts`; use `07-ai-action-calls.md` for execution
+semantics and `10-workflow-execute-sse.md` for wire details.
 
-This file answers: **how does `.howone/ai/manifest.json` become `src/lib/sdk.ts`, and how should UI
-call it?**
+## Handoff protocol
 
-For live stream wire details, read `04-app-sdk/10-workflow-execute-sse.md`. The current endpoint emits
-only `run_start`, `progress`, `run_complete`, `run_error`, and `credit_insufficient`.
+1. Read the current manifest, not a cached tool response.
+2. Confirm every action has an exact UUID `workflowId`.
+3. Generate Zod input/output schemas from the manifest.
+4. Bind with `defineAiAction` and compose with `withAiActions`.
+5. Run `node .howone/skills/howone/scripts/verify-project.mjs`, typecheck, and build.
 
-## Binding Source
+Workflow create/update can rotate the config UUID. After every successful external workflow
+operation, sync and re-read the manifest before deciding whether the app binding changed.
 
-Generate `src/lib/sdk.ts` from `.howone/ai/manifest.json`. Do not write AI bindings from memory,
-from the original prompt, or from the workflow service response.
+There is no action-name fallback. A missing UUID is a module initialization error, not a server
+request that can be repaired later.
 
-For each manifest capability/action:
-
-1. Read stable action name/ID.
-2. Read `workflowId`.
-3. Read `inputSchema`.
-4. Read `outputSchema`.
-5. Generate Zod input and output schemas.
-6. Bind with `defineAiAction(name, { workflowId, inputSchema, outputSchema })`.
-7. Compose with `withAiActions(client, ai)`.
-
-`workflowId` is mandatory. Without it, the SDK falls back to the action name as the execution URL
-segment, and the workflow service will reject it because the segment is not a UUID.
-
-## Generated Binding Example
+## Example
 
 ```ts
-import {
-  createClient,
-  defineAiAction,
-  defineAiActions,
-  withAiActions,
-} from '@howone/sdk'
+import { createClient, defineAiAction, defineAiActions, withAiActions } from '@howone/sdk'
 import { z } from 'zod'
 
 const client = createClient({
@@ -43,22 +29,14 @@ const client = createClient({
   env: import.meta.env.VITE_HOWONE_ENV,
 })
 
-export const summarizeDocumentInputSchema = z.object({
-  document_url: z.string().url(),
-  summary_length: z.string().optional(),
-})
-export type SummarizeDocumentInput = z.infer<typeof summarizeDocumentInputSchema>
+const inputSchema = z.object({ documentUrl: z.string().url() })
+const outputSchema = z.object({ summary: z.string() })
 
-export const summarizeDocumentOutputSchema = z.object({
-  summary: z.string(),
-})
-export type SummarizeDocumentOutput = z.infer<typeof summarizeDocumentOutputSchema>
-
-export const ai = defineAiActions({
+const ai = defineAiActions({
   summarizeDocument: defineAiAction('summarizeDocument', {
     workflowId: '550e8400-e29b-41d4-a716-446655440000',
-    inputSchema: summarizeDocumentInputSchema,
-    outputSchema: summarizeDocumentOutputSchema,
+    inputSchema,
+    outputSchema,
   }),
 })
 
@@ -66,172 +44,47 @@ const howone = withAiActions(client, ai)
 export default howone
 ```
 
-## JSON Schema To Zod
+The UUID above is illustrative only. Copy the real value from the current manifest.
+
+## Schema conversion rules
 
 | JSON Schema | Zod |
 |---|---|
-| `string` | `z.string()` |
-| `string` + `format: "uri"` | `z.string().url()` |
-| `number` | `z.number()` |
-| `integer` | `z.number().int()` |
-| `boolean` | `z.boolean()` |
-| `array` of strings | `z.array(z.string())` |
-| `array` of objects | `z.array(z.object({ ... }))` |
-| `object` | `z.object({ ... })` |
-| string enum | `z.enum([...])` |
-| field not in `required` | `.optional()` |
-| nullable | `.nullable()` |
-
-Rules:
-
-- Required manifest fields must stay required in Zod.
-- Do not add `.passthrough()` to hide execution envelope problems.
-- Do not make outputs optional to silence validation failures.
-- If the workflow returns a different shape, fix the workflow/capability contract.
-
-## Calling Actions
-
-For typed one-shot actions:
-
-```ts
-const output = await howone.ai.summarizeDocument.run({
-  document_url,
-  summary_length: 'short',
-})
-
-setSummary(output.summary)
-```
-
-When `outputSchema` exists, `.run()` returns the validated `finalResult` payload directly.
-
-Do not read:
-
-```ts
-result.finalResult.summary
-result.data.summary
-result.raw.finalResult
-```
-
-Those are execution-envelope paths, not the typed SDK action contract.
-
-## Streaming And Events
-
-Use `.stream()` when UI needs live output or cancellation:
-
-```ts
-const session = howone.ai.generateStory.stream(input, {
-  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),
-})
-
-cancelButton.onclick = () => session.cancel()
-const final = await session.result
-```
-
-Use `.events()` when code wants an async iterable:
-
-```ts
-for await (const event of howone.ai.generateStory.events(input)) {
-  if (event.type === 'progress') {
-    appendLog(String(event.message))
-  }
-  if (event.type === 'run_complete') {
-    setFinalResult(event.message)
-  }
-  if (event.type === 'credit_insufficient') {
-    showCreditError(String(event.message))
-  }
-  if (event.type === 'run_error') {
-    showExecutionError(String(event.message))
-  }
-}
-```
-
-## UI State
-
-The SDK returns data and exposes callbacks. The app owns all visible UI.
-
-Recommended states:
-
-```ts
-type AiUiState<T> =
-  | { status: 'idle' }
-  | { status: 'running'; progress?: number }
-  | { status: 'succeeded'; output: T }
-  | { status: 'failed'; message: string }
-  | { status: 'cancelled' }
-```
+| string | `z.string()` |
+| string URI | `z.string().url()` |
+| number/integer | `z.number()` / `z.number().int()` |
+| boolean | `z.boolean()` |
+| array | `z.array(item)` |
+| object | `z.object({ ... })` |
+| enum | `z.enum([...])` |
+| nullable | `z.nullable(...)` |
+| not required | `.optional()` |
 
-Do not add or import SDK toast APIs. Do not show SDK-owned overlays.
+Do not make required fields optional and do not use `.passthrough()` to conceal a workflow result
+shape mismatch. Typed `.run()` returns the validated final result directly.
 
-## Persistence Handoff
-
-If AI output should survive refresh, use entity persistence after the action returns.
-
-For history-style products, prefer `runAiActionAndPersist()`:
+## Result handoff
 
 ```ts
-const result = await runAiActionAndPersist({
-  entity: howone.entities.Generation,
-  input: { prompt },
-  createPending: (input) => ({
-    prompt: input.prompt,
-    status: 'pending',
-    requestedAt: new Date().toISOString(),
-  }),
-  run: (input) => howone.ai.generateImage.run(input),
-  mapCompleted: ({ output }) => ({
-    status: 'completed',
-    resultUrl: output.generated_image_url,
-    completedAt: new Date().toISOString(),
-  }),
-  mapFailed: ({ error }) => ({
-    status: 'failed',
-    errorMessage: error instanceof Error ? error.message : 'Generation failed',
-  }),
-})
-```
-
-For simple save-after-success:
-
-```ts
-const output = await howone.ai.summarizeDocument.run(input)
+const output = await howone.ai.summarizeDocument.run({ documentUrl })
 await howone.entities.DocumentSummary.create({
-  documentUrl: input.document_url,
+  documentUrl,
   summary: output.summary,
   status: 'completed',
 })
 ```
 
-Do not ask the workflow to write records. Do not pass owner fields for authenticated own entities.
-
-## Workflow Edit Handoff
-
-When changing external workflow behavior later:
-
-1. If schema changes, update AI capability contract first and sync manifest.
-2. Submit update through `external-ai-capability` with `updates: [{ capabilityName, updatePrompt }]`.
-3. Re-read `.howone/ai/manifest.json`; update may rotate `workflowId` to a fresh config UUID.
-4. Regenerate SDK bindings whenever the manifest `workflowId`, input schema, or output schema changed.
-5. Behavior-only updates still require checking the manifest before deciding SDK is unchanged.
+For history, use pending-first `runAiActionAndPersist`. The workflow does not perform database CRUD;
+the app persists through generated entity bindings.
 
-The SDK does not use old `workflowConfigID` status values. It binds to the current manifest
-`workflowId`, which is the EAX config id used in execution URLs.
+For streaming, use `onMessageChunk`, await `session.result`, and catch terminal workflow errors.
+For events, a terminal error event is yielded before the iterator rejects.
 
-## Handoff Checklist
+## Final checklist
 
-- `.howone/ai/manifest.json` exists and is current.
-- Each action has `workflowId`.
-- Zod input/output schemas match manifest required fields.
-- `defineAiAction` uses action name + exact workflow UUID.
-- UI uses returned typed output, not raw execution envelope.
-- Streaming session is cancellable when UI exposes cancel.
-- Persistence goes through `howone.entities.*`.
-- Visible status/error UI is app-owned.
+- [ ] Current AI manifest was read after the last sync.
+- [ ] Action IDs and UUIDs match exactly.
+- [ ] Zod requiredness/enums match the manifest.
+- [ ] No `aiUrl`, `aiBaseUrl`, or raw EAX URL was added.
+- [ ] App uses `HowOneProvider client={howone}`.
+- [ ] Verifier, typecheck, and build pass.

package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md

@@ -86,7 +86,7 @@ Use callbacks instead:
 
 ```tsx
 <HowOneProvider
-  auth="required"
+  client={howone}
   brand="visible"
   onAuthRedirect={({ mode, returnUrl }) => {
     setAuthUi({ redirecting: true, mode, returnUrl })
@@ -102,8 +102,8 @@ Use callbacks instead:
 Hide the logo only when explicitly requested:
 
 ```tsx
-<HowOneProvider brand="hidden" />
-<HowOneProvider showBrandButton={false} />
+<HowOneProvider client={howone} brand="hidden" />
+<HowOneProvider client={howone} showBrandButton={false} />
 ```
 
 ## UI Feedback Rule
@@ -132,7 +132,7 @@ For streaming workflows, use callbacks/events:
 const session = howone.ai.generateImage.stream(
   { prompt },
   {
-    onStreamContent: (delta) => appendLog(delta),
+    onMessageChunk: (delta) => appendLog(delta),
     onProgress: (progress) => setProgress(progress),
     onError: (error) => setStatus({ type: 'error', message: error.message }),
     onComplete: (result) => setResult(result.finalResult),

package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md

@@ -1,52 +1,40 @@
 # Workflow Execute SSE
 
-Use this reference for `@howone/sdk` AI action streaming and raw workflow execution calls.
+Use this reference when an app needs live workflow progress, cancellation, or raw event iteration.
+For ordinary AI actions, start with `07-ai-action-calls.md` and use the typed action methods.
 
-## Endpoint Contract
+## Environment and endpoint
 
-The SDK uses the current workflow execute SSE endpoint:
+The SDK chooses the EAX base from `createClient({ env })`:
 
-| Method | Path |
+| `env` | EAX base |
 |---|---|
-| `POST` | `/workflow/execute/{project_short_id}/{config_id}` |
+| `local` | `https://eax-backend-orchestrator-dev.fly.dev` |
+| `dev` | `https://eax-backend-orchestrator-dev.fly.dev` |
+| `prod` | `https://eax-backend-orchestrator-prod.fly.dev` |
 
-The request body is:
+Do not construct this URL in app code or override it with `aiUrl`. A workflow action calls:
 
-```json
-{
-  "inputs": {},
-  "priority": "normal"
-}
+```text
+POST {eaxBase}/workflow/execute/{projectId}/{workflowId}
 ```
 
-`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`.
+The request body is `{ inputs: {}, priority?: 'low' | 'normal' | 'high' }` and carries the current
+client token as `Authorization: Bearer ...`.
 
-## Wire Format
+## Wire protocol
 
-Frames contain only a `data:` line and a blank line:
+Frames are JSON `data:` lines separated by a blank line. The JSON envelope owns the ID and event
+name; there are no separate legacy SSE `id:` or `event:` lines:
 
 ```text
-data: {"id":"evt_8ae6d6e8a4ea","event":"run_start","message":"execution with sse is started"}
+data: {"id":"evt_1","event":"run_start","message":"execution with sse is started"}
 
-data: {"id":"evt_241ff985450b","event":"progress","message":"[DISPLAY] Executing node: Extract"}
+data: {"id":"evt_2","event":"progress","message":"[DISPLAY] Executing node: Extract"}
 
-data: {"id":"evt_f3a1b2c3d4e5","event":"run_complete","message":{"video_url":"https://..."}}
+data: {"id":"evt_3","event":"run_complete","message":{"imageUrl":"https://..."}}
 ```
 
-There are no separate SSE `event:` or `id:` lines. The JSON envelope owns those fields.
-
-## Envelope
-
 ```ts
 type WorkflowSseEnvelope = {
   id: string
@@ -55,51 +43,96 @@ type WorkflowSseEnvelope = {
 }
 ```
 
-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.
+There is no `stream_end`, `node_start`, `tool_call_end`, or `ai_message_chunk` event in this
+workflow endpoint.
 
-`AiResult` maps the stream as:
+## SDK mapping
 
 ```ts
 type AiResult = {
   success: boolean
-  runId?: string
+  runId?: string // X-Run-Id response header
   outcome: 'success' | 'credit_insufficient' | 'run_error' | null
   finalResult: Record<string, unknown> | null
   progressLogs: string[]
+  stateData: Record<string, unknown> // deprecated; always empty for this protocol
+  nodeExecutions: unknown[]           // deprecated; always empty
+  toolExecutions: unknown[]           // deprecated; always empty
+  totalDuration: number
   errors: string[]
   events: AiEvent[]
 }
 ```
 
-For typed actions with an `outputSchema`, `.run()` returns the validated `run_complete.message`
-object directly.
+`run_complete.message` becomes `finalResult`. `progress.message` lines append to `progressLogs`.
+`run_error` and `credit_insufficient` append errors and cause `run()`/`stream.result` to reject with
+`WorkflowExecutionError`; the `events()` iterator yields the terminal event before rejecting.
+
+## UI pattern
+
+```tsx
+function WorkflowProgress({ input }: { input: GenerateInput }) {
+  const [logs, setLogs] = useState<string[]>([])
+  const [error, setError] = useState<string | null>(null)
+
+  async function run() {
+    const controller = new AbortController()
+    try {
+      const result = await howone.ai.generate.run(input, {
+        signal: controller.signal,
+        onMessageChunk: (line) => setLogs((current) => [...current, line]),
+      })
+      console.log(result)
+    } catch (value) {
+      setError(value instanceof Error ? value.message : String(value))
+    }
+  }
+
+  return <button onClick={() => void run()}>Run workflow</button>
+}
+```
+
+For a cancel button, keep the controller/session in a ref and call `abort()` or `session.cancel()`.
+Treat abort as a user action in UI; do not report it as an EAX `run_error`.
 
-## Callback Rules
+## 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.
+- `onEvent(event, 'workflow')` fires for each parsed envelope.
+- `onRunStart` fires for `run_start`.
+- `onMessageChunk(text, event)` fires for each non-empty progress line.
+- `onProgress(0, message)` is a compatibility callback for progress lines; `onProgress(100)` fires
+  on successful completion.
+- `onRunComplete` receives the final object.
+- `onRunError` and `onCreditInsufficient` receive terminal messages.
+- `onComplete` receives the assembled result before a terminal failure is rejected.
+- `onError` receives transport and terminal errors.
 
-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.
+Callbacks are not a substitute for awaiting `run()` or `session.result`; always handle the promise.
+The SDK retains at most 1,000 events and 500 progress lines by default while still invoking callbacks
+for every event. Configure the bounds for a diagnostic screen rather than retaining unbounded logs.
 
+## Raw event iteration
+
+```ts
+try {
+  for await (const event of howone.ai.generate.events(input)) {
+    renderEvent(event)
+  }
+} catch (error) {
+  renderFailure(error)
+}
+```
+
+On a terminal failure, consumers see the `run_error` or `credit_insufficient` event before the
+iterator rejects. Breaking the loop cancels the underlying reader.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Calling the old `/workflow/{appId}/{id}/execute_sse` path | Use the typed SDK action. |
+| Adding `/api` to EAX URL | EAX base is not the REST base; app code should not build it. |
+| Using `onStreamChunk`/`onTextChunk` | Use `onMessageChunk`. |
+| Treating `run_error` as a successful result | Catch `WorkflowExecutionError` and inspect `outcome`. |
+| Parsing `event.payload.result` | Read `event.message`; `run_complete` message is the final object. |

package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md

@@ -189,7 +189,7 @@ Schema:
       "create": "scoped",
       "update": "none",
       "delete": "none",
-      "requiredScopes": ["created_by_user_id"],
+      "requiredScopes": ["submissionKey"],
       "allowedFilters": [],
       "allowedSorts": [],
       "defaultLimit": 1,
@@ -203,7 +203,7 @@ Frontend:
 
 ```ts
 await howone.public.entities.Feedback.create({
-  created_by_user_id: projectUserId,
+  submissionKey,
   message,
   rating,
 })
@@ -211,7 +211,8 @@ await howone.public.entities.Feedback.create({
 
 Rules:
 
-- Public create needs a clear `created_by_user_id` source when backend requires ownership mapping.
+- Public create must use the declared public scope/business fields. Never pass ownership/system
+  fields such as `created_by_user_id`; the SDK rejects them and the backend derives ownership/scope.
 - Do not expose public read unless needed.
 - Add anti-abuse UX/server constraints outside the dynamic schema when needed.
 - Never persist UI-only fields from form components.