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

{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agenticstar-platform
-Version: 3.2.0
+Version: 3.2.3
 Summary: AGENTICSTAR Platform SDK - Enterprise AI Agent Infrastructure
 Project-URL: Homepage, https://developers.fd.agenticstar.tm.softbank.jp/
 Project-URL: Documentation, https://developers.fd.agenticstar.tm.softbank.jp/
@@ -224,6 +224,7 @@ Environment variable contract:
 | `REQUEST_SOURCE` / `AGENT_ID` | Same as above (optional) | — |
 | `DB_HOST` / `DB_PORT` / `DB_DATABASE` / `DB_USER` / `DB_PASSWORD` | Env var settings at agent registration (`PostgreSQLConfig.from_env()` contract) | ✅ |
 | `WEBHOOK_URL` | Env var settings at agent registration | ✅ |
+| `ASTER_NOTIFY_TOKEN` | Injected by the Marketplace executor for each execution (SDK >= 3.2.2 sends it as `Authorization: Bearer` on the webhook notification) | — |
 
 Terminal event rules:
 
@@ -235,7 +236,8 @@ Terminal event rules:
 If you need the low-level API (to compose handlers yourself), pass
 `create_marketplace_handler(data_access, webhook_url, user_id, conversation_id, message_id)`
 (a composite handler for DB persistence + webhook notification; requires the `[db]` + `[webhook]`
-extras) directly to `EventEmitter`, as before.
+extras) directly to `EventEmitter`, as before. Without a `token_provider`, it sends the
+`ASTER_NOTIFY_TOKEN` env var as `Authorization: Bearer` when it is set (SDK >= 3.2.2).
 
 ### 2.4 Report completion for a cycle execution (SDK >= 3.0.14, `mp-chat/1`)
 
@@ -471,6 +473,24 @@ config = AzureBlobConfig.from_dict({
 client = AzureBlobStorageClient(config)
 ```
 
+S3 without access keys (3.2.3): leave `aws_access_key_id` and `aws_secret_access_key` both out (or
+empty). The client then passes no keys and lets boto3 find the credentials with its default
+credential chain (for example IRSA on EKS, environment variables, `~/.aws` files, EKS Pod Identity
+or an EC2 instance role; boto3 decides which one is used first). This is what an EKS Pod with IRSA
+needs; do not also give that Pod `AWS_ACCESS_KEY_ID` in its env, which boto3 checks before IRSA.
+The role needs S3 access to the bucket. Give both keys or neither: only one of them raises
+`StorageConfigError`.
+
+```python
+from agenticstar_platform.storage import S3StorageClient, S3Config
+
+config = S3Config.from_dict({
+    "bucket_name": "your-bucket",
+    "region_name": "us-east-1",
+})
+client = S3StorageClient(config)
+```
+
 ### Telemetry / LLM Usage Tracking (Marketplace)
 
 `TelemetryAccess` (under `db` module) writes records to the `ai_telemetry` table. **Unknown fields are stored in the `metadata` jsonb column automatically** — no schema migration is required to add new tracking dimensions.
@@ -687,7 +707,9 @@ What `context` provides: correlation (`execution_id` / `run_id` / `operation_key
 do not start an external write without that acknowledgement), `is_cancel_requested()` /
 `ensure_can_act()` / `deadline_remaining()`, `skip(reason)` (a step with nothing to do: `no_target` /
 `not_applicable` / `nothing_to_do` → `skipped`), `policy_unavailable()` (the policy could not be
-checked before any external action → `skipped/policy_unavailable`), `log(message)` (written to the runner's
+checked before any external action → `skipped/policy_unavailable`), `incomplete(reason, comment=None)` (SDK ≥ 3.2.1:
+the step could not be completed and running it again would not help → `incomplete/<reason>`; see below),
+`log(message)` (written to the runner's
 log; `run()` sends SDK logs at INFO to stderr when the process has not configured logging),
 `gate_decision` (SDK ≥ 3.0.9: the review decision that started this run — `None` unless the run follows a
 review; otherwise a read-only mapping `{gate_id, decision, decided_by, note, decided_at}` where `decision` is
@@ -730,11 +752,47 @@ async def run(context):
     ...
 ```
 
+**Ending a step as not completed** (SDK ≥ 3.2.1). When your agent cannot complete the step and running it again would
+give the same result — the instructions are missing, a setting is wrong — call `context.incomplete(reason, comment)` and
+return. The platform does not retry the step automatically; it asks a person to check it and shows the reason in the
+execution record. A platform that reads the end-of-run report (below) also shows the comment there; Marketplace 3.2.0
+does not show the comment.
+
+```python
+async def run(context):
+    instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
+    if not instructions.strip():
+        await context.incomplete("missing_instructions",
+                                 comment="instructions.md is empty. Write the instructions and run the step again.")
+        return
+    ...
+```
+
+- `reason` is a reason code with the same rules as `report_completion()` of cycle executions: lowercase snake_case of at
+  most 32 characters (`-` and spaces become `_`, upper case becomes lower case). Any other value (a sentence, an exception
+  string) becomes `incomplete` and a warning is logged
+- `comment` (optional) is a short explanation for the person who checks the step. It is cut at 2,048 characters (counted
+  as UTF-16 code units, like JavaScript). Do not put secrets or personal data in it
+- Declare once. A second call is not recorded (the first one is kept and the runner logs a warning). An exception after
+  the declaration still ends the step as `incomplete`
+- An audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and
+  a denied tool call decide the outcome before the declaration
+- For a failure that may go away on its own (a timeout of an external service, a rate limit), raise an exception
+  instead: the platform retries `failed/agent_error` (up to its retry limit) when the contract's effect mode is
+  `read_only` or `idempotent_write` and the effects are known
+
+The completion then carries an **end-of-run report**, `completion_report`, in the same form as the platform's own agents:
+`{"completed": false, "reason_code": ..., "comment": ...}`. For `incomplete` the comment is yours (no `comment` key when
+you gave none); for an exception (`failed/agent_error`) the comment is the cause chain the runner writes to stderr —
+class names, the SDK's error code, the HTTP status and the destination host name only, never messages, URLs or tokens.
+Other outcomes carry no report. A platform that does not read the report yet keeps the completion and drops the report.
+
 The outcome describes how the run ended, with 7 values (`completed` / `incomplete` / `failed` /
 `timeout` / `stopped` / `denied` / `skipped`). **Success means the agent ran to completion**: the agent
 function returns normally → `completed/completed`, unless an audit persistence failure, a denied tool
-call, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
-unobserved effects or zero observations do not lower the outcome); an exception → `failed/agent_error`; cancellation →
+call, a declared `incomplete`, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
+unobserved effects or zero observations do not lower the outcome); `context.incomplete(reason)` → `incomplete/<reason>`;
+an exception → `failed/agent_error`; cancellation →
 `stopped/cancelled`; deadline → `timeout/execution_timeout`; pod stop signal → `failed/runner_stopped`;
 a call reported with `audit.tool_denied` → `denied`.
 What was written is kept in `counts` / `tools` and `had_mutating_success` (true = success observed /
@@ -743,6 +801,83 @@ automatically and go to a human (effects that already happened are never undone)
 source distribution: `docs/examples/workflow_reply_agent.py` (drafting a reply) /
 `workflow_mock_send_agent.py` (a mock send).
 
+**Testing an agent without ASTER** (SDK ≥ 3.2.1). `agenticstar_platform.workflow.testing.FakeRuntime` answers the
+platform's runtime API in memory. Give it your contract, the step's parameters, the input files, the connection tokens,
+the effect mode and the deadline, run one step with `arun(...)`, then read what the runner saved. With this layout:
+
+```text
+my_project/
+  my_agent/__init__.py    (empty)
+  my_agent/main.py        (your agent)
+  try_it.py               (the script below)
+```
+
+```python
+# my_agent/main.py
+async def run(context):
+    instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
+    (context.output_dir / "reply.md").write_text(f"# Reply\n\n{instructions}", encoding="utf-8")
+```
+
+```python
+# try_it.py
+import asyncio
+import tempfile
+
+from agenticstar_platform.workflow import arun
+from agenticstar_platform.workflow.testing import FakeRuntime
+
+CONTRACT = {
+    "runtime_protocol": "mp-workflow/1", "effect_mode": "read_only",
+    "files": [{"name": "instructions", "path": "instructions.md", "format": "markdown", "required": True}],
+    "outputs": [{"name": "reply", "path": "reply.md", "format": "markdown", "required": True}],
+    "limits": {"execution_timeout_seconds": 600},
+}
+
+
+async def main():
+    fake = FakeRuntime(
+        contract=CONTRACT,
+        parameters={"product_code": "P-100", "language": "en"},
+        inputs={"instructions": b"Thank the customer.\n"},       # by the name of a contract file
+        connections={"crm": "test-access-token"},                # slot -> token, or (token, expires_at)
+        deadline_seconds=600,
+    )
+    with tempfile.TemporaryDirectory() as workspace:
+        result = await arun("my_agent.main:run", env=fake.runner_env(), workspace=workspace, transport=fake.transport)
+    print(result.outcome, result.outcome_reason_code)               # completed completed
+    print(fake.saved_artifacts()["reply"]["content"])               # the saved output, by its name
+    print([e["event_type"] for e in fake.saved_audit_events()])     # context.manifest x2, then your audit events
+    print(fake.saved_completion()["envelope"])                      # the completion_envelope
+
+
+asyncio.run(main())
+```
+
+```bash
+cd my_project
+PYTHONPATH="$PWD" python try_it.py
+```
+
+- The runner starts your entrypoint in a child process whose current directory is the work directory, so `my_agent.main`
+  must be importable from `PYTHONPATH` **as an absolute path** (`PYTHONPATH="$PWD"`, not `PYTHONPATH=.`: the child would
+  look for `.` in the work directory) or installed. In a test, set `os.environ["PYTHONPATH"]` to the absolute path before
+  calling `arun`
+- The fake copies the current behaviour of the runtime API (only declared outputs are saved, a `completed` outcome needs
+  the required outputs, writes after cancellation, the end of the run or the deadline are refused except the audit
+  records of what the agent already did (`tool.effect` / `tool.denied`), ...). It **does not check the parameters
+  against `parameters_schema` or validate the contract**: the platform checks those before a run (the admin console's
+  check before registration and the executor). Parameters are passed to your agent as given
+- **Supported surface**: the constructor arguments, `runner_env()`, `transport`, `saved_artifacts()` /
+  `saved_audit_events()` / `saved_completion()`, `sample_contract()` / `sample_parameters()`, the constants
+  `EXECUTION_ID` / `TOKEN` / `BASE_URL`, and the attributes that simulate the platform, which you can change before or
+  during a run: `contract` (a copy of the one you passed; later requests see your changes), `cancel_requested_at` (an ISO time = cancellation
+  was requested), `run_closed`, `deadline_passed`, `gate_decision`, `start_input`, `fail_audit_types`,
+  `fail_upload_times`, `fail_completion_times`, `fail_download_times` (see the module's docstring). Everything else is
+  internal and may change
+- Without arguments the fake uses the contract and parameters of `docs/examples/workflow_reply_agent.py`; run
+  `python docs/examples/workflow_reply_agent.py` (source distribution) to see one step end to end
+
 ### Policy Module — `agenticstar_platform.policy` (SDK ≥ 1.0.0a1)
 
 Pure computation (no I/O, no agent framework): decide **allow / forbid** for a tool call from a two-layer policy.
@@ -993,6 +1128,30 @@ See the [developer portal](https://developers.fd.agenticstar.tm.softbank.jp/) fo
 
 ## Changelog
 
+### 3.2.3 (2026-11-04) — storage: S3 without access keys (IRSA) / events: a failed run ends the chat message
+
+3.2.2 was not published to PyPI; 3.2.3 includes its change (the notify token below).
+
+- **`S3StorageClient` works without access keys.** Leave `aws_access_key_id` and `aws_secret_access_key` both out (or empty) and the client passes no keys and lets boto3 find the credentials with its default credential chain (for example IRSA on EKS with `AWS_ROLE_ARN` + `AWS_WEB_IDENTITY_TOKEN_FILE`, environment variables, `~/.aws` files, EKS Pod Identity or an EC2 instance role; boto3 decides the order). Before, the client raised `StorageConfigError: S3 requires aws_access_key_id and aws_secret_access_key` on an EKS runner Pod that has only IRSA. Giving only one of the two keys still raises `StorageConfigError` (it is a configuration mistake, and the client does not silently fall back to other credentials). Both keys work as before, exactly as given (a non-blank key is not stripped); an empty or whitespace-only key, including a `SecretStr`, counts as not given. With no keys the client is created even when boto3 finds no credentials; the first call then fails (for example `object_exists()` returns `False`). `S3Config` keeps its field order, so positional construction is unchanged; `S3Config.from_dict` no longer requires the two keys.
+- **A failed run ends the chat message.** `create_marketplace_handler` (and so `run_marketplace_agent`) now sends `COMPLETION_FAILURE` with `finish_reason: "stop"`, the same as the platform's own agent worker. The chat front ends a message only on `"stop"`; with the previous `"error"` the failure text was added but the message kept showing as in progress. The failure is told by the message text, as before. `WebhookEventHandler` used on its own keeps `"error"` by default, so a receiver of your own that tells failures by `"error"` is unchanged; the new argument `failure_finish_reason="stop"` sends what the chat front expects. If you pointed `create_marketplace_handler` at a receiver of your own that needs `"error"`, build `WebhookEventHandler` yourself instead.
+- docs: "Ending a step as not completed" now says that the execution record shows the reason, and that the comment is shown only by a platform that reads the end-of-run report (Marketplace 3.2.0 does not show it). In 3.2.1 and 3.2.2 that section said the record shows the comment. The SDK's behavior is unchanged.
+
+### 3.2.2 (2026-10-30) — events: the webhook notification carries the execution's notify token (`ASTER_NOTIFY_TOKEN`)
+
+- **`create_marketplace_handler(...)` sends `Authorization: Bearer <token>` on the webhook notification when the `ASTER_NOTIFY_TOKEN` env var is set.** The Marketplace executor issues this token for each execution and passes it to the agent Pod; the platform checks it when it receives the notification. Without a `token_provider` argument, the handler reads the env var each time it sends. When the env var is missing or empty, no `Authorization` header is sent, as before. A `token_provider` you pass is used as before, and the env var is not read. `run_marketplace_agent` uses this default, so a runner agent sends the token without code changes.
+- `WebhookEventHandler` used on its own does not read `ASTER_NOTIFY_TOKEN`; as before, it sends an `Authorization` header only when you give one (through its `token_provider` or `headers`).
+- To use it, rebuild the agent image with this SDK.
+
+### 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`)
+
+- **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.
+- **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.
+- **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.
+- **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.
+- 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`.
+- `build_envelope(...)` accepts an optional `completion_report`. Other public functions of the runner and the context are unchanged.
+- To use it, rebuild the agent image with this SDK.
+
 ### 3.2.0 (2026-10-26) — auth: the `api_key` authentication mode (`X-Internal-API-Key` header) is removed
 
 The version follows the platform release (3.2.0).
@@ -1429,4 +1588,4 @@ Marketplace SDK reliability fixes (surfaced while building agents from the guide
 
 ## Version
 
-3.2.0
+3.2.3

{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.3}/README.md

@@ -143,6 +143,7 @@ Environment variable contract:
 | `REQUEST_SOURCE` / `AGENT_ID` | Same as above (optional) | — |
 | `DB_HOST` / `DB_PORT` / `DB_DATABASE` / `DB_USER` / `DB_PASSWORD` | Env var settings at agent registration (`PostgreSQLConfig.from_env()` contract) | ✅ |
 | `WEBHOOK_URL` | Env var settings at agent registration | ✅ |
+| `ASTER_NOTIFY_TOKEN` | Injected by the Marketplace executor for each execution (SDK >= 3.2.2 sends it as `Authorization: Bearer` on the webhook notification) | — |
 
 Terminal event rules:
 
@@ -154,7 +155,8 @@ Terminal event rules:
 If you need the low-level API (to compose handlers yourself), pass
 `create_marketplace_handler(data_access, webhook_url, user_id, conversation_id, message_id)`
 (a composite handler for DB persistence + webhook notification; requires the `[db]` + `[webhook]`
-extras) directly to `EventEmitter`, as before.
+extras) directly to `EventEmitter`, as before. Without a `token_provider`, it sends the
+`ASTER_NOTIFY_TOKEN` env var as `Authorization: Bearer` when it is set (SDK >= 3.2.2).
 
 ### 2.4 Report completion for a cycle execution (SDK >= 3.0.14, `mp-chat/1`)
 
@@ -390,6 +392,24 @@ config = AzureBlobConfig.from_dict({
 client = AzureBlobStorageClient(config)
 ```
 
+S3 without access keys (3.2.3): leave `aws_access_key_id` and `aws_secret_access_key` both out (or
+empty). The client then passes no keys and lets boto3 find the credentials with its default
+credential chain (for example IRSA on EKS, environment variables, `~/.aws` files, EKS Pod Identity
+or an EC2 instance role; boto3 decides which one is used first). This is what an EKS Pod with IRSA
+needs; do not also give that Pod `AWS_ACCESS_KEY_ID` in its env, which boto3 checks before IRSA.
+The role needs S3 access to the bucket. Give both keys or neither: only one of them raises
+`StorageConfigError`.
+
+```python
+from agenticstar_platform.storage import S3StorageClient, S3Config
+
+config = S3Config.from_dict({
+    "bucket_name": "your-bucket",
+    "region_name": "us-east-1",
+})
+client = S3StorageClient(config)
+```
+
 ### Telemetry / LLM Usage Tracking (Marketplace)
 
 `TelemetryAccess` (under `db` module) writes records to the `ai_telemetry` table. **Unknown fields are stored in the `metadata` jsonb column automatically** — no schema migration is required to add new tracking dimensions.
@@ -606,7 +626,9 @@ What `context` provides: correlation (`execution_id` / `run_id` / `operation_key
 do not start an external write without that acknowledgement), `is_cancel_requested()` /
 `ensure_can_act()` / `deadline_remaining()`, `skip(reason)` (a step with nothing to do: `no_target` /
 `not_applicable` / `nothing_to_do` → `skipped`), `policy_unavailable()` (the policy could not be
-checked before any external action → `skipped/policy_unavailable`), `log(message)` (written to the runner's
+checked before any external action → `skipped/policy_unavailable`), `incomplete(reason, comment=None)` (SDK ≥ 3.2.1:
+the step could not be completed and running it again would not help → `incomplete/<reason>`; see below),
+`log(message)` (written to the runner's
 log; `run()` sends SDK logs at INFO to stderr when the process has not configured logging),
 `gate_decision` (SDK ≥ 3.0.9: the review decision that started this run — `None` unless the run follows a
 review; otherwise a read-only mapping `{gate_id, decision, decided_by, note, decided_at}` where `decision` is
@@ -649,11 +671,47 @@ async def run(context):
     ...
 ```
 
+**Ending a step as not completed** (SDK ≥ 3.2.1). When your agent cannot complete the step and running it again would
+give the same result — the instructions are missing, a setting is wrong — call `context.incomplete(reason, comment)` and
+return. The platform does not retry the step automatically; it asks a person to check it and shows the reason in the
+execution record. A platform that reads the end-of-run report (below) also shows the comment there; Marketplace 3.2.0
+does not show the comment.
+
+```python
+async def run(context):
+    instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
+    if not instructions.strip():
+        await context.incomplete("missing_instructions",
+                                 comment="instructions.md is empty. Write the instructions and run the step again.")
+        return
+    ...
+```
+
+- `reason` is a reason code with the same rules as `report_completion()` of cycle executions: lowercase snake_case of at
+  most 32 characters (`-` and spaces become `_`, upper case becomes lower case). Any other value (a sentence, an exception
+  string) becomes `incomplete` and a warning is logged
+- `comment` (optional) is a short explanation for the person who checks the step. It is cut at 2,048 characters (counted
+  as UTF-16 code units, like JavaScript). Do not put secrets or personal data in it
+- Declare once. A second call is not recorded (the first one is kept and the runner logs a warning). An exception after
+  the declaration still ends the step as `incomplete`
+- An audit persistence failure, cancellation, the deadline, the execution being closed elsewhere, a pod stop signal and
+  a denied tool call decide the outcome before the declaration
+- For a failure that may go away on its own (a timeout of an external service, a rate limit), raise an exception
+  instead: the platform retries `failed/agent_error` (up to its retry limit) when the contract's effect mode is
+  `read_only` or `idempotent_write` and the effects are known
+
+The completion then carries an **end-of-run report**, `completion_report`, in the same form as the platform's own agents:
+`{"completed": false, "reason_code": ..., "comment": ...}`. For `incomplete` the comment is yours (no `comment` key when
+you gave none); for an exception (`failed/agent_error`) the comment is the cause chain the runner writes to stderr —
+class names, the SDK's error code, the HTTP status and the destination host name only, never messages, URLs or tokens.
+Other outcomes carry no report. A platform that does not read the report yet keeps the completion and drops the report.
+
 The outcome describes how the run ended, with 7 values (`completed` / `incomplete` / `failed` /
 `timeout` / `stopped` / `denied` / `skipped`). **Success means the agent ran to completion**: the agent
 function returns normally → `completed/completed`, unless an audit persistence failure, a denied tool
-call, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
-unobserved effects or zero observations do not lower the outcome); an exception → `failed/agent_error`; cancellation →
+call, a declared `incomplete`, an invalid declared output, a skip or a missing required output decides otherwise (failed writes,
+unobserved effects or zero observations do not lower the outcome); `context.incomplete(reason)` → `incomplete/<reason>`;
+an exception → `failed/agent_error`; cancellation →
 `stopped/cancelled`; deadline → `timeout/execution_timeout`; pod stop signal → `failed/runner_stopped`;
 a call reported with `audit.tool_denied` → `denied`.
 What was written is kept in `counts` / `tools` and `had_mutating_success` (true = success observed /
@@ -662,6 +720,83 @@ automatically and go to a human (effects that already happened are never undone)
 source distribution: `docs/examples/workflow_reply_agent.py` (drafting a reply) /
 `workflow_mock_send_agent.py` (a mock send).
 
+**Testing an agent without ASTER** (SDK ≥ 3.2.1). `agenticstar_platform.workflow.testing.FakeRuntime` answers the
+platform's runtime API in memory. Give it your contract, the step's parameters, the input files, the connection tokens,
+the effect mode and the deadline, run one step with `arun(...)`, then read what the runner saved. With this layout:
+
+```text
+my_project/
+  my_agent/__init__.py    (empty)
+  my_agent/main.py        (your agent)
+  try_it.py               (the script below)
+```
+
+```python
+# my_agent/main.py
+async def run(context):
+    instructions = (context.work_dir / "instructions.md").read_text(encoding="utf-8")
+    (context.output_dir / "reply.md").write_text(f"# Reply\n\n{instructions}", encoding="utf-8")
+```
+
+```python
+# try_it.py
+import asyncio
+import tempfile
+
+from agenticstar_platform.workflow import arun
+from agenticstar_platform.workflow.testing import FakeRuntime
+
+CONTRACT = {
+    "runtime_protocol": "mp-workflow/1", "effect_mode": "read_only",
+    "files": [{"name": "instructions", "path": "instructions.md", "format": "markdown", "required": True}],
+    "outputs": [{"name": "reply", "path": "reply.md", "format": "markdown", "required": True}],
+    "limits": {"execution_timeout_seconds": 600},
+}
+
+
+async def main():
+    fake = FakeRuntime(
+        contract=CONTRACT,
+        parameters={"product_code": "P-100", "language": "en"},
+        inputs={"instructions": b"Thank the customer.\n"},       # by the name of a contract file
+        connections={"crm": "test-access-token"},                # slot -> token, or (token, expires_at)
+        deadline_seconds=600,
+    )
+    with tempfile.TemporaryDirectory() as workspace:
+        result = await arun("my_agent.main:run", env=fake.runner_env(), workspace=workspace, transport=fake.transport)
+    print(result.outcome, result.outcome_reason_code)               # completed completed
+    print(fake.saved_artifacts()["reply"]["content"])               # the saved output, by its name
+    print([e["event_type"] for e in fake.saved_audit_events()])     # context.manifest x2, then your audit events
+    print(fake.saved_completion()["envelope"])                      # the completion_envelope
+
+
+asyncio.run(main())
+```
+
+```bash
+cd my_project
+PYTHONPATH="$PWD" python try_it.py
+```
+
+- The runner starts your entrypoint in a child process whose current directory is the work directory, so `my_agent.main`
+  must be importable from `PYTHONPATH` **as an absolute path** (`PYTHONPATH="$PWD"`, not `PYTHONPATH=.`: the child would
+  look for `.` in the work directory) or installed. In a test, set `os.environ["PYTHONPATH"]` to the absolute path before
+  calling `arun`
+- The fake copies the current behaviour of the runtime API (only declared outputs are saved, a `completed` outcome needs
+  the required outputs, writes after cancellation, the end of the run or the deadline are refused except the audit
+  records of what the agent already did (`tool.effect` / `tool.denied`), ...). It **does not check the parameters
+  against `parameters_schema` or validate the contract**: the platform checks those before a run (the admin console's
+  check before registration and the executor). Parameters are passed to your agent as given
+- **Supported surface**: the constructor arguments, `runner_env()`, `transport`, `saved_artifacts()` /
+  `saved_audit_events()` / `saved_completion()`, `sample_contract()` / `sample_parameters()`, the constants
+  `EXECUTION_ID` / `TOKEN` / `BASE_URL`, and the attributes that simulate the platform, which you can change before or
+  during a run: `contract` (a copy of the one you passed; later requests see your changes), `cancel_requested_at` (an ISO time = cancellation
+  was requested), `run_closed`, `deadline_passed`, `gate_decision`, `start_input`, `fail_audit_types`,
+  `fail_upload_times`, `fail_completion_times`, `fail_download_times` (see the module's docstring). Everything else is
+  internal and may change
+- Without arguments the fake uses the contract and parameters of `docs/examples/workflow_reply_agent.py`; run
+  `python docs/examples/workflow_reply_agent.py` (source distribution) to see one step end to end
+
 ### Policy Module — `agenticstar_platform.policy` (SDK ≥ 1.0.0a1)
 
 Pure computation (no I/O, no agent framework): decide **allow / forbid** for a tool call from a two-layer policy.
@@ -912,6 +1047,30 @@ See the [developer portal](https://developers.fd.agenticstar.tm.softbank.jp/) fo
 
 ## Changelog
 
+### 3.2.3 (2026-11-04) — storage: S3 without access keys (IRSA) / events: a failed run ends the chat message
+
+3.2.2 was not published to PyPI; 3.2.3 includes its change (the notify token below).
+
+- **`S3StorageClient` works without access keys.** Leave `aws_access_key_id` and `aws_secret_access_key` both out (or empty) and the client passes no keys and lets boto3 find the credentials with its default credential chain (for example IRSA on EKS with `AWS_ROLE_ARN` + `AWS_WEB_IDENTITY_TOKEN_FILE`, environment variables, `~/.aws` files, EKS Pod Identity or an EC2 instance role; boto3 decides the order). Before, the client raised `StorageConfigError: S3 requires aws_access_key_id and aws_secret_access_key` on an EKS runner Pod that has only IRSA. Giving only one of the two keys still raises `StorageConfigError` (it is a configuration mistake, and the client does not silently fall back to other credentials). Both keys work as before, exactly as given (a non-blank key is not stripped); an empty or whitespace-only key, including a `SecretStr`, counts as not given. With no keys the client is created even when boto3 finds no credentials; the first call then fails (for example `object_exists()` returns `False`). `S3Config` keeps its field order, so positional construction is unchanged; `S3Config.from_dict` no longer requires the two keys.
+- **A failed run ends the chat message.** `create_marketplace_handler` (and so `run_marketplace_agent`) now sends `COMPLETION_FAILURE` with `finish_reason: "stop"`, the same as the platform's own agent worker. The chat front ends a message only on `"stop"`; with the previous `"error"` the failure text was added but the message kept showing as in progress. The failure is told by the message text, as before. `WebhookEventHandler` used on its own keeps `"error"` by default, so a receiver of your own that tells failures by `"error"` is unchanged; the new argument `failure_finish_reason="stop"` sends what the chat front expects. If you pointed `create_marketplace_handler` at a receiver of your own that needs `"error"`, build `WebhookEventHandler` yourself instead.
+- docs: "Ending a step as not completed" now says that the execution record shows the reason, and that the comment is shown only by a platform that reads the end-of-run report (Marketplace 3.2.0 does not show it). In 3.2.1 and 3.2.2 that section said the record shows the comment. The SDK's behavior is unchanged.
+
+### 3.2.2 (2026-10-30) — events: the webhook notification carries the execution's notify token (`ASTER_NOTIFY_TOKEN`)
+
+- **`create_marketplace_handler(...)` sends `Authorization: Bearer <token>` on the webhook notification when the `ASTER_NOTIFY_TOKEN` env var is set.** The Marketplace executor issues this token for each execution and passes it to the agent Pod; the platform checks it when it receives the notification. Without a `token_provider` argument, the handler reads the env var each time it sends. When the env var is missing or empty, no `Authorization` header is sent, as before. A `token_provider` you pass is used as before, and the env var is not read. `run_marketplace_agent` uses this default, so a runner agent sends the token without code changes.
+- `WebhookEventHandler` used on its own does not read `ASTER_NOTIFY_TOKEN`; as before, it sends an `Authorization` header only when you give one (through its `token_provider` or `headers`).
+- To use it, rebuild the agent image with this SDK.
+
+### 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`)
+
+- **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.
+- **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.
+- **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.
+- **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.
+- 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`.
+- `build_envelope(...)` accepts an optional `completion_report`. Other public functions of the runner and the context are unchanged.
+- To use it, rebuild the agent image with this SDK.
+
 ### 3.2.0 (2026-10-26) — auth: the `api_key` authentication mode (`X-Internal-API-Key` header) is removed
 
 The version follows the platform release (3.2.0).
@@ -1348,4 +1507,4 @@ Marketplace SDK reliability fixes (surfaced while building agents from the guide
 
 ## Version
 
-3.2.0
+3.2.3

{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.3}/agenticstar_platform/__init__.py

@@ -9,7 +9,7 @@ import importlib
 import importlib.util
 from typing import TYPE_CHECKING
 
-__version__ = "3.2.0"
+__version__ = "3.2.3"
 
 # Common utilities are internal - not exported as public API
 # Use agenticstar_platform.common for internal SDK development only

{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.3}/agenticstar_platform/events/handlers.py

@@ -33,6 +33,7 @@ Example:
 import asyncio
 import json
 import logging
+import os
 from typing import Any, Callable, Dict, List, Optional
 
 from .types import EventType
@@ -249,6 +250,7 @@ class WebhookEventHandler:
         chunk_type_map: Optional[Dict[EventType, str]] = None,
         request_source: Optional[str] = None,
         message_type_map: Optional[Dict[EventType, str]] = None,
+        failure_finish_reason: str = "error",
     ):
         """
         WebhookEventHandlerを初期化
@@ -269,6 +271,10 @@ class WebhookEventHandler:
             message_type_map: EventType→トップレベルtypeのカスタムマッピング
                 （オプション）。省略時は HITL系→"vnc_hitl_event"、
                 PROGRESS_MESSAGE→"progress_message" を切り替えるデフォルトを使用。
+            failure_finish_reason: COMPLETION_FAILURE の finish_reason（既定 "error"。3.2.3）。
+                AgenticStar のチャット画面（chatboardfront の監視）へ送るときは "stop" にする:
+                受信側は "stop" のときだけメッセージを終わらせ、"error" は読まない（本体の worker も
+                失敗を "stop" で送る）。create_marketplace_handler はこれを "stop" にして作る
 
         Example:
             >>> handler = WebhookEventHandler(
@@ -309,10 +315,10 @@ class WebhookEventHandler:
             EventType.FINAL_RESULT: None,
         }
 
-        # finish_reasonマッピング
+        # finish_reasonマッピング（失敗の値は failure_finish_reason。既定 "error" は従来どおり）
         self._finish_reason_map = {
             EventType.COMPLETION_SUCCESS: "stop",
-            EventType.COMPLETION_FAILURE: "error",
+            EventType.COMPLETION_FAILURE: failure_finish_reason,
         }
 
         logger.debug(
@@ -502,6 +508,20 @@ class CompositeEventHandler:
             return None
 
 
+# 完了の知らせ（/webhook/notify）に付ける実行ごとのトークンの env。
+# Marketplace executor が実行ごとに発行し、会話の Pod に渡す。受信側（front の監視）が
+# Authorization: Bearer で確かめる。
+NOTIFY_TOKEN_ENV = "ASTER_NOTIFY_TOKEN"
+
+
+def _notify_token_from_env() -> Optional[str]:
+    """env ASTER_NOTIFY_TOKEN から知らせのトークンを返す（無い・空なら None）
+
+    create_marketplace_handler の既定の token_provider。送るたびに env を読む。
+    """
+    return os.environ.get(NOTIFY_TOKEN_ENV) or None
+
+
 def create_marketplace_handler(
     data_access: Any,
     webhook_url: str,
@@ -522,12 +542,19 @@ def create_marketplace_handler(
         user_id: ユーザーID
         conversation_id: 会話ID
         message_id: メッセージID
-        token_provider: 認証トークン取得関数（オプション）
+        token_provider: 認証トークン取得関数（オプション）。
+            省略時（None）は env ASTER_NOTIFY_TOKEN を送るたびに読む既定の関数を使い、
+            値があれば Webhook に Authorization: Bearer <値> を付ける。env が無い・空なら付けない
+            （Marketplace executor が実行ごとに発行して Pod に渡すトークン。呼び出し側のコードは
+            変えなくてよい。SDK 3.2.2 から）。明示した場合はその関数だけを使い、env は読まない。
         request_source: リクエスト発信元（"internal" / "external"）。
             受信側で Progress SSE 配信 と 外部Webhook送信 の振り分けに使われる。
             外部API経由（extapi）からの呼び出しでは "external" を指定すること。
             通常はPod起動スクリプトで os.environ.get("REQUEST_SOURCE", "internal") を渡す。
 
+    失敗の完了（COMPLETION_FAILURE）は finish_reason "stop" で送る（3.2.3。チャット画面は "stop" で
+    メッセージを終わらせる。WebhookEventHandler の既定 "error" とは違う）。
+
     Returns:
         CompositeEventHandler: DB + Webhookの複合ハンドラー
 
@@ -561,8 +588,14 @@ def create_marketplace_handler(
         webhook_url=webhook_url,
         conversation_id=conversation_id,
         message_id=message_id,
-        token_provider=token_provider,
+        token_provider=(
+            token_provider if token_provider is not None else _notify_token_from_env
+        ),
         request_source=request_source,
+        # 失敗も "stop"（3.2.3）: 受信側のチャット画面（chatboardfront の監視）は "stop" のときだけ
+        # メッセージを終わらせ、"error" は読まない。本体の worker も COMPLETION_FAILURE を "stop" で送る
+        # （src/subscribers/common.py の get_finish_reason）。失敗の中身は本文で伝わる
+        failure_finish_reason="stop",
     )
 
     return CompositeEventHandler([db_handler, webhook_handler])

{agenticstar_platform-3.2.0 → agenticstar_platform-3.2.3}/agenticstar_platform/runner.py

@@ -67,7 +67,7 @@ from .db import DataAccess, PostgreSQLConfig, create_postgresql_manager
 from .db.execution_access import ExecutionAccess
 from .db.started_fence import StartedFenceTaken, take_started_fence
 from .events import EventEmitter, EventType
-from .events.handlers import create_marketplace_handler
+from .events.handlers import NOTIFY_TOKEN_ENV, create_marketplace_handler
 
 logger = logging.getLogger(__name__)
 
@@ -315,6 +315,8 @@ async def arun_marketplace_agent(
             conversation_id=identity["CONVERSATION_ID"],
             message_id=identity["MESSAGE_ID"],
             request_source=request_source or env.get("REQUEST_SOURCE", "internal"),
+            # 完了の知らせの実行ごとのトークン（3.2.2）。identity・WEBHOOK_URL と同じく渡された env から読む
+            token_provider=lambda: env.get(NOTIFY_TOKEN_ENV) or None,
         )
 
         execution_id = identity["EXECUTION_ID"]