agenticstar-platform 3.2.0__tar.gz → 3.2.1__tar.gz

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 (146) hide show
  1. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/PKG-INFO +129 -5
  2. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/README.md +128 -4
  3. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/__init__.py +1 -1
  4. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/child.py +10 -4
  5. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/context.py +46 -2
  6. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/envelope.py +60 -6
  7. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/runner.py +39 -3
  8. agenticstar_platform-3.2.1/agenticstar_platform/workflow/testing.py +449 -0
  9. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/examples/workflow_reply_agent.py +42 -0
  10. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/pyproject.toml +1 -1
  11. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/agent_fixtures.py +87 -0
  12. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/test_child_failure_summary.py +9 -0
  13. agenticstar_platform-3.2.1/tests/workflow/test_workflow_incomplete.py +322 -0
  14. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/test_workflow_runner.py +14 -8
  15. agenticstar_platform-3.2.1/tests/workflow/test_workflow_testing.py +229 -0
  16. agenticstar_platform-3.2.0/.gitignore +0 -270
  17. agenticstar_platform-3.2.0/tests/workflow/fake_runtime.py +0 -267
  18. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/LICENSE +0 -0
  19. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/_config_utils.py +0 -0
  20. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/ROW_HASH_SPEC.md +0 -0
  21. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/__init__.py +0 -0
  22. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/action_audit.py +0 -0
  23. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/guardrail_alerts.py +0 -0
  24. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/audit/row_hash_fixture.json +0 -0
  25. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/__init__.py +0 -0
  26. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/client.py +0 -0
  27. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/config.py +0 -0
  28. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/exceptions.py +0 -0
  29. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/auth/models.py +0 -0
  30. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/__init__.py +0 -0
  31. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/context_manager.py +0 -0
  32. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/secrets.py +0 -0
  33. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/common/validation.py +0 -0
  34. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/__init__.py +0 -0
  35. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/api_manager.py +0 -0
  36. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/completion_report.py +0 -0
  37. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/config.py +0 -0
  38. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/config_access.py +0 -0
  39. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/data_access.py +0 -0
  40. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/execution_access.py +0 -0
  41. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/factory.py +0 -0
  42. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/manager.py +0 -0
  43. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/pod_runtime.py +0 -0
  44. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/started_fence.py +0 -0
  45. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/telemetry_access.py +0 -0
  46. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/db/wire_types.py +0 -0
  47. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/__init__.py +0 -0
  48. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/emitter.py +0 -0
  49. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/handlers.py +0 -0
  50. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/models.py +0 -0
  51. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/events/types.py +0 -0
  52. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/README.md +0 -0
  53. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/__init__.py +0 -0
  54. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/__main__.py +0 -0
  55. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/checks.py +0 -0
  56. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/docker-compose.yml +0 -0
  57. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/doctor.py +0 -0
  58. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/lab_config.py +0 -0
  59. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/offline_embedding.py +0 -0
  60. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/run_lab.py +0 -0
  61. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/lab/seed.py +0 -0
  62. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/memory/__init__.py +0 -0
  63. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/memory/semantic.py +0 -0
  64. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/metering/__init__.py +0 -0
  65. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/metering/meter.py +0 -0
  66. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/policy/__init__.py +0 -0
  67. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/policy/internal_operations.py +0 -0
  68. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/policy/model.py +0 -0
  69. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/__init__.py +0 -0
  70. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/base.py +0 -0
  71. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/embedding.py +0 -0
  72. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/rag/qdrant_manager.py +0 -0
  73. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/runner.py +0 -0
  74. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/runtime.py +0 -0
  75. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/__init__.py +0 -0
  76. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/aws.py +0 -0
  77. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/azure.py +0 -0
  78. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/base.py +0 -0
  79. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/content_safety_validator.py +0 -0
  80. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/factory.py +0 -0
  81. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/security/gcp.py +0 -0
  82. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/__init__.py +0 -0
  83. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/azure.py +0 -0
  84. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/base.py +0 -0
  85. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/gcs.py +0 -0
  86. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/paths.py +0 -0
  87. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/storage/s3.py +0 -0
  88. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/__init__.py +0 -0
  89. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/canonical.py +0 -0
  90. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/errors.py +0 -0
  91. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/files.py +0 -0
  92. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/runtime_client.py +0 -0
  93. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/agenticstar_platform/workflow/schema.py +0 -0
  94. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/agenticstar_platform.html +0 -0
  95. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/examples/workflow_mock_send_agent.py +0 -0
  96. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/index.html +0 -0
  97. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/docs/search.js +0 -0
  98. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/__init__.py +0 -0
  99. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/audit/__init__.py +0 -0
  100. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/audit/test_action_audit_30.py +0 -0
  101. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/audit/test_row_hash_fixture.py +0 -0
  102. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/__init__.py +0 -0
  103. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_auth_type_bearer_only.py +0 -0
  104. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_get_user_path_encoding.py +0 -0
  105. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_mcp_tokens_expiry.py +0 -0
  106. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/auth/test_mcp_tokens_rejected.py +0 -0
  107. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/__init__.py +0 -0
  108. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_api_manager_drain_and_headers.py +0 -0
  109. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_completion_report.py +0 -0
  110. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_data_access_identifier_validation.py +0 -0
  111. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_manager_execute_query_dispatch.py +0 -0
  112. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_telemetry_tools_used_contract.py +0 -0
  113. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/db/test_wire_param_types.py +0 -0
  114. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/events/__init__.py +0 -0
  115. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/events/test_handler_type_routing.py +0 -0
  116. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/lab/test_lab_contract.py +0 -0
  117. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/lab/test_lab_docker.py +0 -0
  118. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/memory/__init__.py +0 -0
  119. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/memory/test_semantic_converter_base_url.py +0 -0
  120. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/metering/__init__.py +0 -0
  121. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/metering/test_meter_cache_split.py +0 -0
  122. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/__init__.py +0 -0
  123. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_a2a_connection_rule.py +0 -0
  124. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_decision_layer.py +0 -0
  125. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_evaluate_decision_table.py +0 -0
  126. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_policy_model.py +0 -0
  127. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/policy/test_scoped_forbid.py +0 -0
  128. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/__init__.py +0 -0
  129. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/test_embedding_dimensions.py +0 -0
  130. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/test_qdrant_error_hierarchy.py +0 -0
  131. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/rag/test_qdrant_get_statistics.py +0 -0
  132. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/__init__.py +0 -0
  133. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/test_marketplace_runner_contract.py +0 -0
  134. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/test_marketplace_runner_db_fallback.py +0 -0
  135. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/runner/test_marketplace_runner_started_fence.py +0 -0
  136. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/__init__.py +0 -0
  137. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_azure_connect_retry.py +0 -0
  138. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_azure_prompt_shield_documents.py +0 -0
  139. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_factory_vertex_ai_safety.py +0 -0
  140. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/security/test_gcp_vertex_ai_safety.py +0 -0
  141. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/storage/__init__.py +0 -0
  142. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/storage/test_azure_credential.py +0 -0
  143. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/test_lazy_import_contract.py +0 -0
  144. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/test_readme_quickstart.py +0 -0
  145. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/test_storage_provider_extra_contract.py +0 -0
  146. {agenticstar_platform-3.2.0 → agenticstar_platform-3.2.1}/tests/workflow/__init__.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: agenticstar-platform
3
- Version: 3.2.0
3
+ Version: 3.2.1
4
4
  Summary: AGENTICSTAR Platform SDK - Enterprise AI Agent Infrastructure
5
5
  Project-URL: Homepage, https://developers.fd.agenticstar.tm.softbank.jp/
6
6
  Project-URL: Documentation, https://developers.fd.agenticstar.tm.softbank.jp/
@@ -687,7 +687,9 @@ What `context` provides: correlation (`execution_id` / `run_id` / `operation_key
687
687
  do not start an external write without that acknowledgement), `is_cancel_requested()` /
688
688
  `ensure_can_act()` / `deadline_remaining()`, `skip(reason)` (a step with nothing to do: `no_target` /
689
689
  `not_applicable` / `nothing_to_do` → `skipped`), `policy_unavailable()` (the policy could not be
690
- checked before any external action → `skipped/policy_unavailable`), `log(message)` (written to the runner's
690
+ checked before any external action → `skipped/policy_unavailable`), `incomplete(reason, comment=None)` (SDK ≥ 3.2.1:
691
+ the step could not be completed and running it again would not help → `incomplete/<reason>`; see below),
692
+ `log(message)` (written to the runner's
691
693
  log; `run()` sends SDK logs at INFO to stderr when the process has not configured logging),
692
694
  `gate_decision` (SDK ≥ 3.0.9: the review decision that started this run — `None` unless the run follows a
693
695
  review; otherwise a read-only mapping `{gate_id, decision, decided_by, note, decided_at}` where `decision` is
@@ -730,11 +732,46 @@ async def run(context):
730
732
  ...
731
733
  ```
732
734
 
735
+ **Ending a step as not completed** (SDK ≥ 3.2.1). When your agent cannot complete the step and running it again would
736
+ give the same result — the instructions are missing, a setting is wrong — call `context.incomplete(reason, comment)` and
737
+ return. The platform does not retry the step automatically; it asks a person to check it and shows the reason and the
738
+ comment in the execution record.
739
+
740
+ ```python
741
+ async def run(context):
742
+ instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
743
+ if not instructions.strip():
744
+ await context.incomplete("missing_instructions",
745
+ comment="instructions.md is empty. Write the instructions and run the step again.")
746
+ return
747
+ ...
748
+ ```
749
+
750
+ - `reason` is a reason code with the same rules as `report_completion()` of cycle executions: lowercase snake_case of at
751
+ most 32 characters (`-` and spaces become `_`, upper case becomes lower case). Any other value (a sentence, an exception
752
+ string) becomes `incomplete` and a warning is logged
753
+ - `comment` (optional) is a short explanation for the person who checks the step. It is cut at 2,048 characters (counted
754
+ as UTF-16 code units, like JavaScript). Do not put secrets or personal data in it
755
+ - Declare once. A second call is not recorded (the first one is kept and the runner logs a warning). An exception after
756
+ the declaration still ends the step as `incomplete`
757
+ - An audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and
758
+ a denied tool call decide the outcome before the declaration
759
+ - For a failure that may go away on its own (a timeout of an external service, a rate limit), raise an exception
760
+ instead: the platform retries `failed/agent_error` (up to its retry limit) when the contract's effect mode is
761
+ `read_only` or `idempotent_write` and the effects are known
762
+
763
+ The completion then carries an **end-of-run report**, `completion_report`, in the same form as the platform's own agents:
764
+ `{"completed": false, "reason_code": ..., "comment": ...}`. For `incomplete` the comment is yours (no `comment` key when
765
+ you gave none); for an exception (`failed/agent_error`) the comment is the cause chain the runner writes to stderr —
766
+ class names, the SDK's error code, the HTTP status and the destination host name only, never messages, URLs or tokens.
767
+ Other outcomes carry no report. A platform that does not read the report yet keeps the completion and drops the report.
768
+
733
769
  The outcome describes how the run ended, with 7 values (`completed` / `incomplete` / `failed` /
734
770
  `timeout` / `stopped` / `denied` / `skipped`). **Success means the agent ran to completion**: the agent
735
771
  function returns normally → `completed/completed`, unless an audit persistence failure, a denied tool
736
- call, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
737
- unobserved effects or zero observations do not lower the outcome); an exception → `failed/agent_error`; cancellation →
772
+ call, a declared `incomplete`, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
773
+ unobserved effects or zero observations do not lower the outcome); `context.incomplete(reason)` → `incomplete/<reason>`;
774
+ an exception → `failed/agent_error`; cancellation →
738
775
  `stopped/cancelled`; deadline → `timeout/execution_timeout`; pod stop signal → `failed/runner_stopped`;
739
776
  a call reported with `audit.tool_denied` → `denied`.
740
777
  What was written is kept in `counts` / `tools` and `had_mutating_success` (true = success observed /
@@ -743,6 +780,83 @@ automatically and go to a human (effects that already happened are never undone)
743
780
  source distribution: `docs/examples/workflow_reply_agent.py` (drafting a reply) /
744
781
  `workflow_mock_send_agent.py` (a mock send).
745
782
 
783
+ **Testing an agent without ASTER** (SDK ≥ 3.2.1). `agenticstar_platform.workflow.testing.FakeRuntime` answers the
784
+ platform's runtime API in memory. Give it your contract, the step's parameters, the input files, the connection tokens,
785
+ the effect mode and the deadline, run one step with `arun(...)`, then read what the runner saved. With this layout:
786
+
787
+ ```text
788
+ my_project/
789
+ my_agent/__init__.py (empty)
790
+ my_agent/main.py (your agent)
791
+ try_it.py (the script below)
792
+ ```
793
+
794
+ ```python
795
+ # my_agent/main.py
796
+ async def run(context):
797
+ instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
798
+ (context.output_dir / "reply.md").write_text(f"# Reply\n\n{instructions}", encoding="utf-8")
799
+ ```
800
+
801
+ ```python
802
+ # try_it.py
803
+ import asyncio
804
+ import tempfile
805
+
806
+ from agenticstar_platform.workflow import arun
807
+ from agenticstar_platform.workflow.testing import FakeRuntime
808
+
809
+ CONTRACT = {
810
+ "runtime_protocol": "mp-workflow/1", "effect_mode": "read_only",
811
+ "files": [{"name": "instructions", "path": "instructions.md", "format": "markdown", "required": True}],
812
+ "outputs": [{"name": "reply", "path": "reply.md", "format": "markdown", "required": True}],
813
+ "limits": {"execution_timeout_seconds": 600},
814
+ }
815
+
816
+
817
+ async def main():
818
+ fake = FakeRuntime(
819
+ contract=CONTRACT,
820
+ parameters={"product_code": "P-100", "language": "en"},
821
+ inputs={"instructions": b"Thank the customer.\n"}, # by the name of a contract file
822
+ connections={"crm": "test-access-token"}, # slot -> token, or (token, expires_at)
823
+ deadline_seconds=600,
824
+ )
825
+ with tempfile.TemporaryDirectory() as workspace:
826
+ result = await arun("my_agent.main:run", env=fake.runner_env(), workspace=workspace, transport=fake.transport)
827
+ print(result.outcome, result.outcome_reason_code) # completed completed
828
+ print(fake.saved_artifacts()["reply"]["content"]) # the saved output, by its name
829
+ print([e["event_type"] for e in fake.saved_audit_events()]) # context.manifest x2, then your audit events
830
+ print(fake.saved_completion()["envelope"]) # the completion_envelope
831
+
832
+
833
+ asyncio.run(main())
834
+ ```
835
+
836
+ ```bash
837
+ cd my_project
838
+ PYTHONPATH="$PWD" python try_it.py
839
+ ```
840
+
841
+ - The runner starts your entrypoint in a child process whose current directory is the work directory, so `my_agent.main`
842
+ must be importable from `PYTHONPATH` **as an absolute path** (`PYTHONPATH="$PWD"`, not `PYTHONPATH=.`: the child would
843
+ look for `.` in the work directory) or installed. In a test, set `os.environ["PYTHONPATH"]` to the absolute path before
844
+ calling `arun`
845
+ - The fake copies the current behaviour of the runtime API (only declared outputs are saved, a `completed` outcome needs
846
+ the required outputs, writes after cancellation, the end of the run or the deadline are refused except the audit
847
+ records of what the agent already did (`tool.effect` / `tool.denied`), ...). It **does not check the parameters
848
+ against `parameters_schema` or validate the contract**: the platform checks those before a run (the admin console's
849
+ check before registration and the executor). Parameters are passed to your agent as given
850
+ - **Supported surface**: the constructor arguments, `runner_env()`, `transport`, `saved_artifacts()` /
851
+ `saved_audit_events()` / `saved_completion()`, `sample_contract()` / `sample_parameters()`, the constants
852
+ `EXECUTION_ID` / `TOKEN` / `BASE_URL`, and the attributes that simulate the platform, which you can change before or
853
+ during a run: `contract` (a copy of the one you passed; later requests see your changes), `cancel_requested_at` (an ISO time = cancellation
854
+ was requested), `run_closed`, `deadline_passed`, `gate_decision`, `start_input`, `fail_audit_types`,
855
+ `fail_upload_times`, `fail_completion_times`, `fail_download_times` (see the module's docstring). Everything else is
856
+ internal and may change
857
+ - Without arguments the fake uses the contract and parameters of `docs/examples/workflow_reply_agent.py`; run
858
+ `python docs/examples/workflow_reply_agent.py` (source distribution) to see one step end to end
859
+
746
860
  ### Policy Module — `agenticstar_platform.policy` (SDK ≥ 1.0.0a1)
747
861
 
748
862
  Pure computation (no I/O, no agent framework): decide **allow / forbid** for a tool call from a two-layer policy.
@@ -993,6 +1107,16 @@ See the [developer portal](https://developers.fd.agenticstar.tm.softbank.jp/) fo
993
1107
 
994
1108
  ## Changelog
995
1109
 
1110
+ ### 3.2.1 (2026-10-28) — workflow: end a step as not completed (`context.incomplete`) with an end-of-run report / a fake runtime for testing (`agenticstar_platform.workflow.testing`)
1111
+
1112
+ - **New `WorkflowContext.incomplete(reason, comment=None)`.** An agent that cannot complete its step, where running it again would give the same result (missing instructions, a wrong setting), ends the step as `incomplete` with `reason` as the reason code. The platform does not retry it automatically and asks a person to check it. `reason` follows the rules of `report_completion()` (lowercase snake_case of at most 32 characters; any other value becomes `incomplete` with a warning); `comment` is cut at 2,048 UTF-16 code units. The declaration comes after an audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and a denied tool call, and before an exception (an exception after the declaration still ends as `incomplete`), an invalid output, a skip and a missing required output. A second declaration is not recorded. See "Ending a step as not completed" in the Workflow Runner section.
1113
+ - **The completion carries an end-of-run report** (`completion_report`: `completed: false`, `reason_code`, `comment`) for `incomplete` (the agent's comment) and for an agent exception, `failed/agent_error` (the redacted cause chain the child already writes to stderr since 3.1.3: class names, the SDK's error code, the HTTP status and the host name; at most 2,048 UTF-16 code units, also with `ASTER_WORKFLOW_DEBUG_TRACEBACK=1`). Other outcomes carry no report, so their completion is the same as in 3.2. A platform that does not read the report yet keeps the completion and drops the report. A `comment` that is not a string (an exception, for example) is left out with a warning, so its message never reaches the report.
1114
+ - **The cause chain shows an `error_code` only in the SDK's own form** (upper-case snake_case of at most 64 characters, such as `REQUEST_ERROR`), in stderr and in the report. An SDK exception that agent code created with another value no longer shows that value.
1115
+ - **New `agenticstar_platform.workflow.testing`**: `FakeRuntime`, an in-memory copy of the platform's runtime API for testing an agent without ASTER. It takes the contract, parameters, input files, connection tokens, effect mode, deadline and instructions as arguments, and `saved_artifacts()` / `saved_audit_events()` / `saved_completion()` read what the runner saved. It does not check the parameters or the contract (the platform checks them before a run). Like the platform, it accepts the audit records of what the agent already did (`tool.effect` / `tool.denied`) after cancellation, the end of the run or the deadline, and reports the end of the run in the context's `cancel_requested_at`. The supported surface (constructor arguments, `runner_env()`, `transport`, the `saved_*()` readers and the listed simulation attributes) is described in the module's docstring; everything else is internal. The SDK's own tests now use it. `import agenticstar_platform.workflow` does not import it.
1116
+ - The sample `docs/examples/workflow_reply_agent.py` ends as `incomplete/missing_instructions` when the instructions are empty, and running the file runs one step against `FakeRuntime`.
1117
+ - `build_envelope(...)` accepts an optional `completion_report`. Other public functions of the runner and the context are unchanged.
1118
+ - To use it, rebuild the agent image with this SDK.
1119
+
996
1120
  ### 3.2.0 (2026-10-26) — auth: the `api_key` authentication mode (`X-Internal-API-Key` header) is removed
997
1121
 
998
1122
  The version follows the platform release (3.2.0).
@@ -1429,4 +1553,4 @@ Marketplace SDK reliability fixes (surfaced while building agents from the guide
1429
1553
 
1430
1554
  ## Version
1431
1555
 
1432
- 3.2.0
1556
+ 3.2.1
@@ -606,7 +606,9 @@ What `context` provides: correlation (`execution_id` / `run_id` / `operation_key
606
606
  do not start an external write without that acknowledgement), `is_cancel_requested()` /
607
607
  `ensure_can_act()` / `deadline_remaining()`, `skip(reason)` (a step with nothing to do: `no_target` /
608
608
  `not_applicable` / `nothing_to_do` → `skipped`), `policy_unavailable()` (the policy could not be
609
- checked before any external action → `skipped/policy_unavailable`), `log(message)` (written to the runner's
609
+ checked before any external action → `skipped/policy_unavailable`), `incomplete(reason, comment=None)` (SDK ≥ 3.2.1:
610
+ the step could not be completed and running it again would not help → `incomplete/<reason>`; see below),
611
+ `log(message)` (written to the runner's
610
612
  log; `run()` sends SDK logs at INFO to stderr when the process has not configured logging),
611
613
  `gate_decision` (SDK ≥ 3.0.9: the review decision that started this run — `None` unless the run follows a
612
614
  review; otherwise a read-only mapping `{gate_id, decision, decided_by, note, decided_at}` where `decision` is
@@ -649,11 +651,46 @@ async def run(context):
649
651
  ...
650
652
  ```
651
653
 
654
+ **Ending a step as not completed** (SDK ≥ 3.2.1). When your agent cannot complete the step and running it again would
655
+ give the same result — the instructions are missing, a setting is wrong — call `context.incomplete(reason, comment)` and
656
+ return. The platform does not retry the step automatically; it asks a person to check it and shows the reason and the
657
+ comment in the execution record.
658
+
659
+ ```python
660
+ async def run(context):
661
+ instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
662
+ if not instructions.strip():
663
+ await context.incomplete("missing_instructions",
664
+ comment="instructions.md is empty. Write the instructions and run the step again.")
665
+ return
666
+ ...
667
+ ```
668
+
669
+ - `reason` is a reason code with the same rules as `report_completion()` of cycle executions: lowercase snake_case of at
670
+ most 32 characters (`-` and spaces become `_`, upper case becomes lower case). Any other value (a sentence, an exception
671
+ string) becomes `incomplete` and a warning is logged
672
+ - `comment` (optional) is a short explanation for the person who checks the step. It is cut at 2,048 characters (counted
673
+ as UTF-16 code units, like JavaScript). Do not put secrets or personal data in it
674
+ - Declare once. A second call is not recorded (the first one is kept and the runner logs a warning). An exception after
675
+ the declaration still ends the step as `incomplete`
676
+ - An audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and
677
+ a denied tool call decide the outcome before the declaration
678
+ - For a failure that may go away on its own (a timeout of an external service, a rate limit), raise an exception
679
+ instead: the platform retries `failed/agent_error` (up to its retry limit) when the contract's effect mode is
680
+ `read_only` or `idempotent_write` and the effects are known
681
+
682
+ The completion then carries an **end-of-run report**, `completion_report`, in the same form as the platform's own agents:
683
+ `{"completed": false, "reason_code": ..., "comment": ...}`. For `incomplete` the comment is yours (no `comment` key when
684
+ you gave none); for an exception (`failed/agent_error`) the comment is the cause chain the runner writes to stderr —
685
+ class names, the SDK's error code, the HTTP status and the destination host name only, never messages, URLs or tokens.
686
+ Other outcomes carry no report. A platform that does not read the report yet keeps the completion and drops the report.
687
+
652
688
  The outcome describes how the run ended, with 7 values (`completed` / `incomplete` / `failed` /
653
689
  `timeout` / `stopped` / `denied` / `skipped`). **Success means the agent ran to completion**: the agent
654
690
  function returns normally → `completed/completed`, unless an audit persistence failure, a denied tool
655
- call, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
656
- unobserved effects or zero observations do not lower the outcome); an exception → `failed/agent_error`; cancellation →
691
+ call, a declared `incomplete`, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
692
+ unobserved effects or zero observations do not lower the outcome); `context.incomplete(reason)` → `incomplete/<reason>`;
693
+ an exception → `failed/agent_error`; cancellation →
657
694
  `stopped/cancelled`; deadline → `timeout/execution_timeout`; pod stop signal → `failed/runner_stopped`;
658
695
  a call reported with `audit.tool_denied` → `denied`.
659
696
  What was written is kept in `counts` / `tools` and `had_mutating_success` (true = success observed /
@@ -662,6 +699,83 @@ automatically and go to a human (effects that already happened are never undone)
662
699
  source distribution: `docs/examples/workflow_reply_agent.py` (drafting a reply) /
663
700
  `workflow_mock_send_agent.py` (a mock send).
664
701
 
702
+ **Testing an agent without ASTER** (SDK ≥ 3.2.1). `agenticstar_platform.workflow.testing.FakeRuntime` answers the
703
+ platform's runtime API in memory. Give it your contract, the step's parameters, the input files, the connection tokens,
704
+ the effect mode and the deadline, run one step with `arun(...)`, then read what the runner saved. With this layout:
705
+
706
+ ```text
707
+ my_project/
708
+ my_agent/__init__.py (empty)
709
+ my_agent/main.py (your agent)
710
+ try_it.py (the script below)
711
+ ```
712
+
713
+ ```python
714
+ # my_agent/main.py
715
+ async def run(context):
716
+ instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
717
+ (context.output_dir / "reply.md").write_text(f"# Reply\n\n{instructions}", encoding="utf-8")
718
+ ```
719
+
720
+ ```python
721
+ # try_it.py
722
+ import asyncio
723
+ import tempfile
724
+
725
+ from agenticstar_platform.workflow import arun
726
+ from agenticstar_platform.workflow.testing import FakeRuntime
727
+
728
+ CONTRACT = {
729
+ "runtime_protocol": "mp-workflow/1", "effect_mode": "read_only",
730
+ "files": [{"name": "instructions", "path": "instructions.md", "format": "markdown", "required": True}],
731
+ "outputs": [{"name": "reply", "path": "reply.md", "format": "markdown", "required": True}],
732
+ "limits": {"execution_timeout_seconds": 600},
733
+ }
734
+
735
+
736
+ async def main():
737
+ fake = FakeRuntime(
738
+ contract=CONTRACT,
739
+ parameters={"product_code": "P-100", "language": "en"},
740
+ inputs={"instructions": b"Thank the customer.\n"}, # by the name of a contract file
741
+ connections={"crm": "test-access-token"}, # slot -> token, or (token, expires_at)
742
+ deadline_seconds=600,
743
+ )
744
+ with tempfile.TemporaryDirectory() as workspace:
745
+ result = await arun("my_agent.main:run", env=fake.runner_env(), workspace=workspace, transport=fake.transport)
746
+ print(result.outcome, result.outcome_reason_code) # completed completed
747
+ print(fake.saved_artifacts()["reply"]["content"]) # the saved output, by its name
748
+ print([e["event_type"] for e in fake.saved_audit_events()]) # context.manifest x2, then your audit events
749
+ print(fake.saved_completion()["envelope"]) # the completion_envelope
750
+
751
+
752
+ asyncio.run(main())
753
+ ```
754
+
755
+ ```bash
756
+ cd my_project
757
+ PYTHONPATH="$PWD" python try_it.py
758
+ ```
759
+
760
+ - The runner starts your entrypoint in a child process whose current directory is the work directory, so `my_agent.main`
761
+ must be importable from `PYTHONPATH` **as an absolute path** (`PYTHONPATH="$PWD"`, not `PYTHONPATH=.`: the child would
762
+ look for `.` in the work directory) or installed. In a test, set `os.environ["PYTHONPATH"]` to the absolute path before
763
+ calling `arun`
764
+ - The fake copies the current behaviour of the runtime API (only declared outputs are saved, a `completed` outcome needs
765
+ the required outputs, writes after cancellation, the end of the run or the deadline are refused except the audit
766
+ records of what the agent already did (`tool.effect` / `tool.denied`), ...). It **does not check the parameters
767
+ against `parameters_schema` or validate the contract**: the platform checks those before a run (the admin console's
768
+ check before registration and the executor). Parameters are passed to your agent as given
769
+ - **Supported surface**: the constructor arguments, `runner_env()`, `transport`, `saved_artifacts()` /
770
+ `saved_audit_events()` / `saved_completion()`, `sample_contract()` / `sample_parameters()`, the constants
771
+ `EXECUTION_ID` / `TOKEN` / `BASE_URL`, and the attributes that simulate the platform, which you can change before or
772
+ during a run: `contract` (a copy of the one you passed; later requests see your changes), `cancel_requested_at` (an ISO time = cancellation
773
+ was requested), `run_closed`, `deadline_passed`, `gate_decision`, `start_input`, `fail_audit_types`,
774
+ `fail_upload_times`, `fail_completion_times`, `fail_download_times` (see the module's docstring). Everything else is
775
+ internal and may change
776
+ - Without arguments the fake uses the contract and parameters of `docs/examples/workflow_reply_agent.py`; run
777
+ `python docs/examples/workflow_reply_agent.py` (source distribution) to see one step end to end
778
+
665
779
  ### Policy Module — `agenticstar_platform.policy` (SDK ≥ 1.0.0a1)
666
780
 
667
781
  Pure computation (no I/O, no agent framework): decide **allow / forbid** for a tool call from a two-layer policy.
@@ -912,6 +1026,16 @@ See the [developer portal](https://developers.fd.agenticstar.tm.softbank.jp/) fo
912
1026
 
913
1027
  ## Changelog
914
1028
 
1029
+ ### 3.2.1 (2026-10-28) — workflow: end a step as not completed (`context.incomplete`) with an end-of-run report / a fake runtime for testing (`agenticstar_platform.workflow.testing`)
1030
+
1031
+ - **New `WorkflowContext.incomplete(reason, comment=None)`.** An agent that cannot complete its step, where running it again would give the same result (missing instructions, a wrong setting), ends the step as `incomplete` with `reason` as the reason code. The platform does not retry it automatically and asks a person to check it. `reason` follows the rules of `report_completion()` (lowercase snake_case of at most 32 characters; any other value becomes `incomplete` with a warning); `comment` is cut at 2,048 UTF-16 code units. The declaration comes after an audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and a denied tool call, and before an exception (an exception after the declaration still ends as `incomplete`), an invalid output, a skip and a missing required output. A second declaration is not recorded. See "Ending a step as not completed" in the Workflow Runner section.
1032
+ - **The completion carries an end-of-run report** (`completion_report`: `completed: false`, `reason_code`, `comment`) for `incomplete` (the agent's comment) and for an agent exception, `failed/agent_error` (the redacted cause chain the child already writes to stderr since 3.1.3: class names, the SDK's error code, the HTTP status and the host name; at most 2,048 UTF-16 code units, also with `ASTER_WORKFLOW_DEBUG_TRACEBACK=1`). Other outcomes carry no report, so their completion is the same as in 3.2. A platform that does not read the report yet keeps the completion and drops the report. A `comment` that is not a string (an exception, for example) is left out with a warning, so its message never reaches the report.
1033
+ - **The cause chain shows an `error_code` only in the SDK's own form** (upper-case snake_case of at most 64 characters, such as `REQUEST_ERROR`), in stderr and in the report. An SDK exception that agent code created with another value no longer shows that value.
1034
+ - **New `agenticstar_platform.workflow.testing`**: `FakeRuntime`, an in-memory copy of the platform's runtime API for testing an agent without ASTER. It takes the contract, parameters, input files, connection tokens, effect mode, deadline and instructions as arguments, and `saved_artifacts()` / `saved_audit_events()` / `saved_completion()` read what the runner saved. It does not check the parameters or the contract (the platform checks them before a run). Like the platform, it accepts the audit records of what the agent already did (`tool.effect` / `tool.denied`) after cancellation, the end of the run or the deadline, and reports the end of the run in the context's `cancel_requested_at`. The supported surface (constructor arguments, `runner_env()`, `transport`, the `saved_*()` readers and the listed simulation attributes) is described in the module's docstring; everything else is internal. The SDK's own tests now use it. `import agenticstar_platform.workflow` does not import it.
1035
+ - The sample `docs/examples/workflow_reply_agent.py` ends as `incomplete/missing_instructions` when the instructions are empty, and running the file runs one step against `FakeRuntime`.
1036
+ - `build_envelope(...)` accepts an optional `completion_report`. Other public functions of the runner and the context are unchanged.
1037
+ - To use it, rebuild the agent image with this SDK.
1038
+
915
1039
  ### 3.2.0 (2026-10-26) — auth: the `api_key` authentication mode (`X-Internal-API-Key` header) is removed
916
1040
 
917
1041
  The version follows the platform release (3.2.0).
@@ -1348,4 +1472,4 @@ Marketplace SDK reliability fixes (surfaced while building agents from the guide
1348
1472
 
1349
1473
  ## Version
1350
1474
 
1351
- 3.2.0
1475
+ 3.2.1
@@ -9,7 +9,7 @@ import importlib
9
9
  import importlib.util
10
10
  from typing import TYPE_CHECKING
11
11
 
12
- __version__ = "3.2.0"
12
+ __version__ = "3.2.1"
13
13
 
14
14
  # Common utilities are internal - not exported as public API
15
15
  # Use agenticstar_platform.common for internal SDK development only
@@ -5,6 +5,8 @@ stdout / stderr は Agent の通常出力(本文は制御チャネルに混ざ
5
5
  例外は既定でクラス名だけを stderr に出す(本文 / token を Pod ログへ写さない)。`ASTER_WORKFLOW_DEBUG_TRACEBACK=1` で全文。
6
6
  クラス名の後ろに、原因の連鎖(クラス名・SDK の error_code / HTTP status・通信先のホスト名だけ)を 1 行で添える
7
7
  (devdocs 3.2req reviews 06: `SecurityAPIError` だけでは、egress のサイドカーの 503 か Azure の障害かが分からなかった)。
8
+ 同じ原因の連鎖は done の `failure_summary` で runner に渡し、終了時の報告(envelope の `completion_report.comment`)にも載る
9
+ (3.2.1。`ASTER_WORKFLOW_DEBUG_TRACEBACK=1` でも報告に載るのは連鎖だけで、traceback は載せない)。
8
10
  """
9
11
  from __future__ import annotations
10
12
 
@@ -12,6 +14,7 @@ import asyncio
12
14
  import importlib
13
15
  import json
14
16
  import os
17
+ import re
15
18
  import sys
16
19
  import traceback
17
20
 
@@ -19,6 +22,7 @@ from .context import WorkflowContext, _Ipc
19
22
 
20
23
 
21
24
  _MAX_CAUSES = 5
25
+ _ERROR_CODE_RE = re.compile(r"[A-Z][A-Z0-9_]{0,63}") # SDK の error_code の語の形 (REQUEST_ERROR など)
22
26
 
23
27
 
24
28
  def _safe_failure_summary(exc: BaseException) -> str:
@@ -49,9 +53,10 @@ def _failure_chain(exc: BaseException) -> str:
49
53
  def _describe_exception(exc: BaseException) -> str:
50
54
  """例外 1 件を ``クラス名(error_code=..., status=..., host=...)`` にする (出せる属性が無ければクラス名だけ)。"""
51
55
  attrs = []
52
- # error_code は SDK 自身の例外 (SDK が決まった語を入れる) のときだけ。Agent の例外の属性は文言と同じ扱いで出さない
56
+ # error_code は SDK 自身の例外 (SDK が決まった語を入れる) のときだけ。Agent の例外の属性は文言と同じ扱いで出さない。
57
+ # SDK の例外クラスを Agent が自分の値で作ることもあるので、SDK の語の形 (大文字の snake_case) に合うものだけ出す
53
58
  code = _attr(exc, "error_code") if type(exc).__module__.startswith("agenticstar_platform.") else None
54
- if isinstance(code, str) and code.isidentifier():
59
+ if isinstance(code, str) and _ERROR_CODE_RE.fullmatch(code):
55
60
  attrs.append(f"error_code={code}")
56
61
  status = _attr(exc, "status_code")
57
62
  if isinstance(status, int) and not isinstance(status, bool):
@@ -120,11 +125,12 @@ async def _main() -> int:
120
125
  if asyncio.iscoroutine(result):
121
126
  await result
122
127
  except Exception as e: # noqa: BLE001
128
+ summary = _safe_failure_summary(e)
123
129
  if os.environ.get("ASTER_WORKFLOW_DEBUG_TRACEBACK") == "1":
124
130
  traceback.print_exc(file=sys.stderr)
125
131
  else:
126
- sys.stderr.write(f"agent entrypoint failed: {type(e).__name__} [{_safe_failure_summary(e)}]\n")
127
- await ipc.call("done", status="error", error_class=type(e).__name__)
132
+ sys.stderr.write(f"agent entrypoint failed: {type(e).__name__} [{summary}]\n")
133
+ await ipc.call("done", status="error", error_class=type(e).__name__, failure_summary=summary)
128
134
  return 1
129
135
  await ipc.call("done", status="ok")
130
136
  return 0
@@ -1,7 +1,7 @@
1
1
  """顧客 Agent の entrypoint に渡す `context`(marketplace-3.0 03 §2)。
2
2
 
3
3
  read-only の相関、parameters、input/work/output_dir、operation_key、監査(tool.invoked / tool.effect / tool.denied)、
4
- 取消 / 期限の確認、permitted skip の宣言、起動のきっかけになった確認の決定(`gate_decision`)、外から呼んだ run の
4
+ 取消 / 期限の確認、permitted skip と「完遂できなかった」(incomplete)の宣言、起動のきっかけになった確認の決定(`gate_decision`)、外から呼んだ run の
5
5
  開始の入力(`start_input`)を提供する。
6
6
  gate を決定するメソッドや任意 DB 接続は提供しない。
7
7
  実体は子プロセス側にあり、監査と取消確認は親 runner へ IPC で委譲する。
@@ -26,11 +26,32 @@ from pathlib import Path
26
26
  from types import MappingProxyType
27
27
  from typing import Any, Callable, Mapping, Optional
28
28
 
29
- from .envelope import PRE_ACTION_SKIP_REASONS, SKIP_REASONS
29
+ from .envelope import PRE_ACTION_SKIP_REASONS, SKIP_REASONS, reason_code, report_comment
30
30
  from .errors import AuditNotPersisted, WorkflowError
31
31
 
32
32
  logger = logging.getLogger(__name__)
33
33
 
34
+ INCOMPLETE = "incomplete"
35
+
36
+
37
+ def _incomplete_reason(reason: Any, execution_id: str) -> str:
38
+ """`incomplete()` の理由コード。会話の `report_completion()`(`db/completion_report.normalize_reason`)と同じ正規化と検査:
39
+ 前後の空白を除き、小文字にし、`-` と空白を `_` にして `^[a-z][a-z0-9_]{0,31}$` に合えばその値。省略・空は `incomplete`。
40
+ 合わない値(文章・例外の文字列・長すぎる値)も `incomplete` にして警告する(値はログに出さない)。str の派生
41
+ (StrEnum など)は名前ではなく値を使う。db パッケージは asyncpg を読み込むので import せず、同じ規則をここに置く。"""
42
+ try:
43
+ text = str.__str__(reason) if isinstance(reason, str) else str(reason or "")
44
+ code: Optional[str] = text.strip().lower().replace("-", "_").replace(" ", "_")
45
+ except Exception: # noqa: BLE001 — 文字列にできない値も Agent の処理を止めない
46
+ code = None
47
+ if code == "":
48
+ return INCOMPLETE
49
+ if code is not None and reason_code(code, "") == code:
50
+ return code
51
+ logger.warning("[%s] incomplete reason is not a short snake_case code (^[a-z][a-z0-9_]{0,31}$); using %r",
52
+ execution_id, INCOMPLETE)
53
+ return INCOMPLETE
54
+
34
55
  MUTATING_EFFECT_KINDS = ("write", "create", "update", "delete", "send", "mutate")
35
56
  READ_EFFECT_KINDS = ("read", "list", "query", "fetch")
36
57
  MAX_LINE = 256 * 1024
@@ -375,5 +396,28 @@ class WorkflowContext:
375
396
  if not reply.get("ok"):
376
397
  raise WorkflowError(f"skip not recorded: {reply.get('error') or 'unknown'}")
377
398
 
399
+ async def incomplete(self, reason: str, comment: Optional[str] = None) -> None:
400
+ """「完遂できなかった」で工程を終える宣言(3.2.1)。指示が無い・設定の誤りのように、やり直しても同じ結果になる失敗に使う。
401
+ outcome は `incomplete`、理由コードは `reason`。front は自動で再実行せず、人の確認に回す。
402
+
403
+ 宣言の後は関数から戻る(宣言の後に例外で抜けても `incomplete` のまま)。監査の保存の失敗・取消・期限・他所の終端・runner の停止・
404
+ 拒否(tool.denied)はこの宣言より先に決まる。宣言は 1 回: 2 回目は記録されず、最初の宣言が残る(runner が警告を出す)。
405
+ reason: 理由コード(`report_completion()` と同じ: 小文字の snake_case、32 字まで。`-` と空白は `_` に、大文字は小文字に
406
+ する。合わない値は `incomplete` にして警告)
407
+ comment: 人が読む短い説明(任意)。終了時の報告(envelope の `completion_report.comment`)に載る。2,048 字(UTF-16 の
408
+ 単位)を超えた分は切る。文字列でない値(例外など)は載せずに警告する。秘密の値や個人の情報を
409
+ 書かない"""
410
+ code = _incomplete_reason(reason, self.execution_id)
411
+ text = None
412
+ if comment is not None:
413
+ # 文字列だけを載せる(例外などを渡すと、その本文が報告に載る)。runner も文字列でない comment を捨てる
414
+ text = report_comment(comment) if isinstance(comment, str) else None
415
+ if text is None and not (isinstance(comment, str) and comment == ""):
416
+ logger.warning("[%s] incomplete comment left out: it must be a str of valid UTF-8 text (got %s)",
417
+ self.execution_id, type(comment).__name__)
418
+ reply = await self._ipc.call("incomplete", reason=code, comment=text)
419
+ if not reply.get("ok"):
420
+ raise WorkflowError(f"incomplete not recorded: {reply.get('error') or 'unknown'}")
421
+
378
422
  async def log(self, message: str) -> None:
379
423
  await self._ipc.call("log", message=str(message)[:2000])
@@ -2,7 +2,10 @@
2
2
 
3
3
  - outcome は「どう終わったか」の 7 値: completed / incomplete / failed / timeout / stopped / denied / skipped。
4
4
  **成否 = Agent が完遂したか**。Agent の関数が正常に戻れば `completed`。write の失敗・未観測の効果・tool 記録が無いことは
5
- outcome を下げない(Agent が完遂できなかったなら、Agent が例外で終わる)。何を書いたかは `counts` / `tools` / `had_mutating_success` の側に残す
5
+ outcome を下げない(Agent が完遂できなかったなら、Agent が `incomplete()` で宣言するか(3.2.1。やり直しても同じ結果になる失敗。
6
+ front は自動で再実行せず人の確認に回す)、例外で終わる)。何を書いたかは `counts` / `tools` / `had_mutating_success` の側に残す
7
+ - `incomplete` と、Agent の例外による `failed/agent_error` には、終了時の報告 `completion_report`(SaaS の worker と同じ形:
8
+ `completed: false`・`reason_code`・`comment`)を載せる(3.2.1)。ほかの終わり方では載せない(欄ごと無い)
6
9
  - tally は runner が保存済み(ack 済み)監査から数える
7
10
  - mutating な tool.invoked は **呼出し(invoked event_id)単位** で effect の status を対応付け、成功 / 失敗 / 不明を区別する
8
11
  (`action_ref` は外部の冪等キーで、集計キーではない = 同じ action_ref を共有する 2 回の呼出しが結果を共有しない)
@@ -30,6 +33,8 @@ SKIP_REASONS = ("no_target", "not_applicable", "nothing_to_do")
30
33
  # 外部行為の **前** に policy を照合できなかった: front は budget 内で再照合(retryOrHold)する。次工程へは進めない
31
34
  PRE_ACTION_SKIP_REASONS = ("policy_unavailable",)
32
35
  _REASON_RE = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
36
+ # 終了時の報告の comment の上限。front は JS の length(UTF-16 の単位)で 2,048 まで残す
37
+ COMPLETION_REPORT_COMMENT_MAX = 2048
33
38
 
34
39
 
35
40
  def reason_code(value: Any, default: str) -> str:
@@ -37,6 +42,40 @@ def reason_code(value: Any, default: str) -> str:
37
42
  return v if _REASON_RE.match(v) else default
38
43
 
39
44
 
45
+ def cut_utf16(text: str, limit: int) -> str:
46
+ """JS の length(UTF-16 の単位。BMP の外の文字は 2)で `limit` までに切る(runner の `_error_class` と同じ数え方)。"""
47
+ units = 0
48
+ for i, ch in enumerate(text):
49
+ units += 2 if ord(ch) > 0xFFFF else 1
50
+ if units > limit:
51
+ return text[:i]
52
+ return text
53
+
54
+
55
+ def report_comment(value: Any) -> Optional[str]:
56
+ """終了時の報告の comment: 文字列だけを 2,048 単位までに切る。空・UTF-8 にできない値(孤立したサロゲート)は None
57
+ (front へ送れない値で completion ごと落とさない)。"""
58
+ if not isinstance(value, str):
59
+ return None
60
+ text = cut_utf16(value, COMPLETION_REPORT_COMMENT_MAX)
61
+ if not text:
62
+ return None
63
+ try:
64
+ text.encode("utf-8")
65
+ except UnicodeEncodeError:
66
+ return None
67
+ return text
68
+
69
+
70
+ def build_completion_report(reason: str, comment: Optional[str]) -> dict[str, Any]:
71
+ """終了時の報告(SaaS の worker の `completion_report` と同じ形)。完遂できなかったときだけ作るので `completed` は false。
72
+ comment が無ければ欄なし。"""
73
+ report: dict[str, Any] = {"completed": False, "reason_code": reason}
74
+ if comment:
75
+ report["comment"] = comment
76
+ return report
77
+
78
+
40
79
  @dataclass
41
80
  class EffectTally:
42
81
  """保存済み(ack 済み)監査から集計する。ack されていない event は数えない。"""
@@ -47,6 +86,8 @@ class EffectTally:
47
86
  denials: list[str] = field(default_factory=list) # reason codes
48
87
  persist_failures: int = 0 # 必須監査(manifest / invoked / effect / denied)の保存失敗
49
88
  skip_reason: Optional[str] = None # Agent が宣言した skip 理由(SKIP_REASONS / PRE_ACTION)
89
+ incomplete_reason: Optional[str] = None # Agent が宣言した「完遂できなかった」の理由(incomplete())
90
+ incomplete_comment: Optional[str] = None # その説明(終了時の報告の comment)
50
91
 
51
92
  def record(self, event_type: str, event_id: str, metadata: dict[str, Any], reason: Optional[str] = None) -> None:
52
93
  if event_type == "tool.invoked":
@@ -68,7 +109,8 @@ class EffectTally:
68
109
  def to_dict(self) -> dict[str, Any]:
69
110
  return {"invoked": self.invoked, "effects": self.effects, "orphan_effects": self.orphan_effects,
70
111
  "effect_conflicts": self.effect_conflicts, "denials": list(self.denials),
71
- "persist_failures": self.persist_failures, "skip_reason": self.skip_reason}
112
+ "persist_failures": self.persist_failures, "skip_reason": self.skip_reason,
113
+ "incomplete_reason": self.incomplete_reason, "incomplete_comment": self.incomplete_comment}
72
114
 
73
115
  @classmethod
74
116
  def from_dict(cls, data: Any) -> "EffectTally":
@@ -85,6 +127,9 @@ class EffectTally:
85
127
  t.persist_failures = int(data.get("persist_failures") or 0)
86
128
  sr = data.get("skip_reason")
87
129
  t.skip_reason = sr if sr in SKIP_REASONS + PRE_ACTION_SKIP_REASONS else None
130
+ ir = data.get("incomplete_reason")
131
+ t.incomplete_reason = ir if isinstance(ir, str) and _REASON_RE.match(ir) else None
132
+ t.incomplete_comment = report_comment(data.get("incomplete_comment")) if t.incomplete_reason else None
88
133
  return t
89
134
 
90
135
  @property
@@ -155,7 +200,8 @@ def decide_outcome(*, tally: EffectTally, agent_error: Optional[str], stop_reaso
155
200
  outputs_collected: int, required_missing: list[str], effect_mode: str,
156
201
  collection_failed: bool = False, effects_uncertain: bool = False) -> tuple[str, str, Optional[bool]]:
157
202
  """(outcome, outcome_reason_code, had_mutating_success)。優先順位(00 §7 / 03 §4):
158
- 監査保存失敗 → 取消 → 期限 → 他所終端 → runner 停止 → 拒否 → 例外
203
+ 監査保存失敗 → 取消 → 期限 → 他所終端 → runner 停止 → 拒否 → 宣言された incomplete(3.2.1。宣言の後に例外で抜けても
204
+ incomplete)→ 例外
159
205
  → 回収失敗(宣言 output が不正 / 読めない。skip でも隠さない)→ skip(成功が無い場合。skip = 成果物を作らないので
160
206
  必須 output の **欠落** より先)→ 必須 output 欠落 → 完遂。
161
207
 
@@ -179,6 +225,9 @@ def decide_outcome(*, tally: EffectTally, agent_error: Optional[str], stop_reaso
179
225
  return "failed", "runner_stopped", had
180
226
  if tally.denied:
181
227
  return "denied", tally.denials[0], had # 成功 / 必須 output より優先(front は hold / on_denied)
228
+ if tally.incomplete_reason:
229
+ # Agent が宣言した「完遂できなかった」。例外・回収の失敗・skip・必須 output の欠落より先(front は自動で再実行せず人へ)
230
+ return "incomplete", tally.incomplete_reason, had
182
231
  if agent_error:
183
232
  return "failed", "agent_error", had
184
233
  if collection_failed:
@@ -195,11 +244,13 @@ def decide_outcome(*, tally: EffectTally, agent_error: Optional[str], stop_reaso
195
244
 
196
245
 
197
246
  def build_envelope(*, outcome: str, reason: str, had_mutating_success: Optional[bool], tally: EffectTally,
198
- error_class: Optional[str] = None, runner: Optional[dict[str, Any]] = None) -> dict[str, Any]:
199
- """`runner`: runner 自身の終わり方(停止理由 / 再起動 / cleanup 未完)。Agent の成否ではなく実行環境の記録。"""
247
+ error_class: Optional[str] = None, runner: Optional[dict[str, Any]] = None,
248
+ completion_report: Optional[dict[str, Any]] = None) -> dict[str, Any]:
249
+ """`runner`: runner 自身の終わり方(停止理由 / 再起動 / cleanup 未完)。Agent の成否ではなく実行環境の記録。
250
+ `completion_report`: 終了時の報告(`build_completion_report`)。None なら欄ごと載せない(3.2 までと同じ envelope)。"""
200
251
  if outcome not in OUTCOMES:
201
252
  raise ValueError(f"unknown outcome {outcome}")
202
- return {
253
+ envelope = {
203
254
  "version": ENVELOPE_VERSION,
204
255
  "envelope_version": ENVELOPE_VERSION,
205
256
  "outcome": outcome,
@@ -212,3 +263,6 @@ def build_envelope(*, outcome: str, reason: str, had_mutating_success: Optional[
212
263
  "runner": runner,
213
264
  "written_by": "agenticstar-platform-sdk",
214
265
  }
266
+ if completion_report is not None:
267
+ envelope["completion_report"] = completion_report
268
+ return envelope