@kontourai/flow-agents 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/.github/workflows/release-please.yml +13 -1
  2. package/.github/workflows/runtime-compat.yml +1 -1
  3. package/AGENTS.md +8 -1
  4. package/CHANGELOG.md +41 -0
  5. package/README.md +38 -19
  6. package/build/src/cli/flow-kit.js +9 -4
  7. package/build/src/cli/runtime-adapter.js +9 -5
  8. package/build/src/cli/telemetry-doctor.js +4 -1
  9. package/build/src/runtime-adapters.js +34 -0
  10. package/build/src/tools/build-universal-bundles.js +18 -1
  11. package/console.telemetry.json +115 -20
  12. package/docs/_layouts/default.html +2 -0
  13. package/docs/index.md +8 -0
  14. package/docs/integrations/index.md +4 -0
  15. package/docs/integrations/knowledge-kit-live.md +211 -0
  16. package/docs/kit-authoring-guide.md +169 -0
  17. package/docs/spec/runtime-hook-surface.md +56 -3
  18. package/evals/acceptance/run.sh +10 -1
  19. package/evals/acceptance/test_knowledge_kit_live.sh +221 -0
  20. package/evals/acceptance/test_pi_harness.sh +15 -0
  21. package/evals/integration/test_runtime_adapter_activation.sh +113 -1
  22. package/evals/static/test_universal_bundles.sh +10 -0
  23. package/integrations/strands/examples/knowledge_kit_live.py +461 -0
  24. package/integrations/strands/flow_agents_strands/steering.py +54 -1
  25. package/integrations/strands/tests/test_hooks.py +88 -0
  26. package/integrations/strands-ts/src/hooks.ts +104 -0
  27. package/integrations/strands-ts/test/test-steering.ts +159 -0
  28. package/kits/catalog.json +6 -0
  29. package/kits/knowledge/adapters/default-store/index.js +902 -0
  30. package/kits/knowledge/adapters/flow-runner/index.js +1469 -0
  31. package/kits/knowledge/adapters/flow-runner/telemetry.js +174 -0
  32. package/kits/knowledge/adapters/similarity-vector/index.js +284 -0
  33. package/kits/knowledge/docs/README.md +328 -0
  34. package/kits/knowledge/docs/store-contract.md +650 -0
  35. package/kits/knowledge/evals/consolidation/suite.test.js +1234 -0
  36. package/kits/knowledge/evals/contract-suite/suite.test.js +675 -0
  37. package/kits/knowledge/evals/ingest-compile/suite.test.js +574 -0
  38. package/kits/knowledge/evals/retirement/suite.test.js +1173 -0
  39. package/kits/knowledge/evals/similarity-vector/suite.test.js +685 -0
  40. package/kits/knowledge/evals/synthesis/suite.test.js +916 -0
  41. package/kits/knowledge/flows/compile.flow.json +60 -0
  42. package/kits/knowledge/flows/consolidate.flow.json +77 -0
  43. package/kits/knowledge/flows/ingest.flow.json +60 -0
  44. package/kits/knowledge/flows/retire.flow.json +77 -0
  45. package/kits/knowledge/flows/store-contract.flow.json +48 -0
  46. package/kits/knowledge/flows/synthesize.flow.json +77 -0
  47. package/kits/knowledge/kit.json +98 -0
  48. package/package.json +1 -1
  49. package/src/cli/flow-kit.ts +10 -4
  50. package/src/cli/runtime-adapter.ts +10 -5
  51. package/src/cli/telemetry-doctor.ts +4 -1
  52. package/src/runtime-adapters.ts +35 -0
  53. package/src/tools/build-universal-bundles.ts +18 -1
package/src/tools/build-universal-bundles.ts CHANGED
@@ -355,6 +355,15 @@ function exportOpencodePlugin(): string {
355
355
  // (for session-start steering context) and tool.execute.before (for
356
356
  // policy). This is the closest reasonable approximation — documented here
357
357
  // as an honest gap matching the codex live-hook-influence caveat pattern.
358
+ //
359
+ // KNOWN GAP (verified 2026-06-11, opencode v1.16.2): session.created is NOT
360
+ // delivered to plugin event handlers in opencode (non-interactive) mode.
361
+ // The session IS created server-side but the event fires before the plugin
362
+ // hook dispatch loop is active. As a result, agentSpawn telemetry (session.start)
363
+ // is never emitted in run-mode sessions — only tool.invoke/tool.result appear.
364
+ // This is an opencode runtime limitation, not a bug in this plugin.
365
+ // Session.start telemetry carries L1 conformance but is unavailable in run mode.
366
+ // See docs/spec/runtime-hook-surface.md opencode mapping row for the full gap note.
358
367
  return `/**
359
368
  * Flow Agents opencode plugin.
360
369
  *
@@ -369,6 +378,13 @@ function exportOpencodePlugin(): string {
369
378
  * cannot intercept mid-session user messages before they are processed.
370
379
  * This is an accepted gap documented here analogously to the codex
371
380
  * live-hook-influence caveat.
381
+ *
382
+ * KNOWN GAP: session.created is NOT delivered to plugin handlers in opencode
383
+ * run (non-interactive) mode (verified v1.16.2, 2026-06-11). agentSpawn
384
+ * telemetry (session.start) is therefore absent from run-mode sessions.
385
+ * tool.invoke and tool.result events (L1) are still recorded normally.
386
+ * This is an opencode runtime limitation; no workaround is available without
387
+ * a different hook surface. See docs/spec/runtime-hook-surface.md for details.
372
388
  */
373
389
 
374
390
  import { spawnSync } from 'node:child_process';
@@ -547,7 +563,8 @@ export default function (pi: ExtensionAPI) {
547
563
  });
548
564
 
549
565
  pi.on("before_agent_start", async (event, _ctx) => {
550
- runTelemetry("before_agent_start");
566
+ // Telemetry for agentSpawn is emitted by session_start above; do not repeat it here
567
+ // to avoid duplicate session.start events in the telemetry log.
551
568
  // Inject workflow steering context at agent start
552
569
  const result = runAdapter("pi-hook-adapter.js", "before_agent_start", "workflow-steering", "workflow-steering.js");
553
570
  if (result.context) {