feat(workflow-kit): typed WorldRunHandle<TResult> + runAndWait (sync result retrieval)

[Killian-Aidalinfo]

Résumé

Le moteur world est durable et découplé : kit.run() renvoie un handle, pas la sortie. Cette PR expose l'API de résultat du Run du SDK pour que la migration de workflows consommés synchronement reste type-safe.

Changements

• WorldRunHandle<TResult> (générique) expose désormais returnValue / status / exists / cancel() typés — au lieu d'un simple { runId } non typé (pass-through).
• WorkflowKit.run<TResult>() générique → returnValue typé depuis la fonction du workflow.
• WorkflowKit.runAndWait() (nouveau) : exécute et résout avec la sortie (les deux moteurs), throw en cas d'échec :
  • legacy → throw si status !== "success" (avec l'erreur du run) ;
  • world → rejette via le SDK (WorkflowRunFailedError / WorkflowRunCancelledError).
• Comportement d'échec confirmé par lecture de la source @workflow/core (run.js : pollReturnValue throw WorkflowRunFailedError/WorkflowRunCancelledError).

Migration (drop-in)

// legacy : const { result } = await reportWorkflow.run({ inputData });
const report = await kit.runAndWait(reportWorkflow, [input]);

Tests

• @ai_kit/core WorkflowKit : 11 passed (dont 4 nouveaux runAndWait : world succès, world échec→reject, legacy succès, legacy non-success→throw).
• @ai_kit/workflow-world : 15 passed (contrat miroir).
• Builds core/workflow-world/mcp-docs : verts.

Docs (EN + FR)

• Guide world-engine : section « Récupérer le résultat d'un run ».
• API ref workflow-kit : run générique, runAndWait, table WorldRunHandle<TResult>.
• Servies aussi à l'IA via @ai_kit/mcp-docs.

Versions

• @ai_kit/core 1.4.0 → 1.5.0
• @ai_kit/workflow-world 0.1.0 → 0.1.1
• @ai_kit/mcp-docs 1.0.7 → 1.0.8

⚠️ Une vraie validation end-to-end de returnValue nécessiterait la compilation Nitro (indisponible sous vitest) ; le comportement d'échec a donc été confirmé par lecture de la source du SDK + tests unitaires de runAndWait (mocks).

🤖 Generated with Claude Code