autoflow-sdk 1.0.0__tar.gz

autoflow_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: autoflow-sdk
+Version: 1.0.0
+Summary: AutoFlow Python SDK — base utilities for task execution
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# autoflow-sdk — AutoCodeFlow Python SDK
+
+AutoCodeFlow 任务执行器（executor-python）侧的 Python SDK：提供任务上下文
+（`TaskContext`）、日志（`ctx.log`）、Admin API 回调客户端
+（`CallbackClient` + `ctx.report_success()` / `ctx.report_failure()`）与
+通用 HTTP 客户端（`HttpClient` / `AsyncHttpClient`，基于 httpx）。回调契约
+与 Node.js SDK [`@autocodeflow/sdk`](../autocodeflow-node-sdk/README.md) 完全
+对齐（第九轮），双端共用 `CallbackItemDto` 字段。平台侧完整说明见
+[docs/sdk-guide.md](../../docs/sdk-guide.md)。
+
+## 安装
+
+```bash
+pip install autoflow-sdk                     # 公共 PyPI（发布后）
+# 内网私有 registry（apps/registry-pypi）：
+pip install --index-url http://<registry-pypi-host>/simple autoflow-sdk
+```
+
+要求 Python ≥ 3.9；运行时依赖 `httpx`、`pyyaml`、`pydantic>=2`
+（`autoflow_sdk.models` 的协议模型）；开发/测试依赖另需
+`pytest`、`pytest-asyncio`、`respx`（见 `[project.optional-dependencies].dev`）。
+
+## Quickstart
+
+任务脚本由执行器以子进程运行，环境变量注入见下表。
+`TaskContext.from_env()` 读取 `EXECUTION_ID` / `TASK_ID` / `TASK_NAME` 与
+全部 `AUTOFLOW_*` 触发参数（回调凭证三件套除外——它们暴露为专用字段，
+绝不混入 `ctx.params`）：
+
+```python
+# tasks/fetch_data.py
+from autoflow_sdk import TaskContext
+
+ctx = TaskContext.from_env()
+ctx.log.info(f"task {ctx.task_id} started, execution={ctx.execution_id}")
+
+source_url = ctx.get_param("source_url")          # AUTOFLOW_SOURCE_URL
+rows = do_work(source_url)
+
+# 主动回调 Admin API（N23 per-execution token）。旧版执行器不注入凭证，
+# 此时 ctx.callback.enabled 为 False，结果仍由执行器统一上报。
+if ctx.callback.enabled:
+    ctx.report_success(summary=f"{rows} rows written", duration_ms=1200)
+```
+
+失败上报（`error` 映射为 `errorMessage` 并截断至 4 KB；`failure_reason`
+取 admin-api 的 `ExecutionFailureReason` 枚举，默认 `script_error`，非法值
+抛 `ValueError`）：
+
+```python
+try:
+    rows = do_work(source_url)
+except Exception as e:
+    if ctx.callback.enabled:
+        ctx.report_failure(e, failure_reason="script_error")
+    raise
+```
+
+### 底层回调客户端
+
+批量/自定义字段时直接使用 `ctx.callback.report()`，
+`executionId` / `executorAddress` 自动补齐（N27），显式书写的值不会被覆盖：
+
+```python
+ctx.callback.report([
+    {"status": "success", "durationMs": 800},
+    {"status": "success", "durationMs": 900, "logs": "checkpoint 2"},
+])
+```
+
+凭证缺失时任何上报调用抛 `CallbackDisabledError` 并指明缺失变量
+（fail-closed，与 Node `HttpClient.disabledReason` 语义对齐）。
+
+### HttpClient 直用
+
+通用 HTTP 客户端（非回调专用）可独立构造：
+
+```python
+from autoflow_sdk import HttpClient, AsyncHttpClient
+
+http = HttpClient(base_url="http://admin-api:3105", timeout=30.0,
+                  headers={"Authorization": f"Bearer {token}"})
+resp = http.get("/api/tasks")            # 返回 httpx.Response
+
+async with AsyncHttpClient(base_url=...) as ahttp:
+    resp = await ahttp.post("/api/x", json={"a": 1})
+```
+
+## 执行器注入的环境变量
+
+与 [docs/sdk-guide.md](../../docs/sdk-guide.md) 的注入表逐字一致：
+
+| 变量名 | 说明 | 示例值 |
+|--------|------|--------|
+| `TASK_ID` | 当前任务的唯一标识 | `task_abc123` |
+| `TASK_NAME` | 当前任务名称 | `fetch_data` |
+| `EXECUTION_ID` | 本次执行记录的唯一标识 | `exec_xyz789` |
+| `AUTOFLOW_<KEY>` | 触发参数，按参数名转大写后注入 | `AUTOFLOW_SOURCE_URL=https://api.example.com` |
+| `AUTOFLOW_ADMIN_API_URL` | Admin API 基地址（非机密路由信息，N23 起注入） | `AUTOFLOW_ADMIN_API_URL=http://admin-api:3105` |
+| `AUTOFLOW_CALLBACK_TOKEN` | 本次执行的一次性回调 token（`v1.` HMAC，绑定 executionId、随 TTL 过期，N23 起注入） | `AUTOFLOW_CALLBACK_TOKEN=v1.<uuid>.<exp>.<hmac>` |
+| `AUTOFLOW_EXECUTOR_ADDRESS` | 当前执行器注册地址（非机密路由信息，N27 起注入；SDK 经 `ctx.executorAddress`（Node）/ `ctx.executor_address`（Python）暴露并自动填入回调请求） | `AUTOFLOW_EXECUTOR_ADDRESS=executor-node:8002` |
+
+## 回调契约（与 Node SDK 一致）
+
+`POST {AUTOFLOW_ADMIN_API_URL}/api/executions/callback`，请求体为
+`CallbackItemDto[]`：`executionId` / `status: success|failed` /
+`executorAddress` / `logs` / `errorMessage` / `failureReason` /
+`durationMs`。per-execution token 仅授权本 `executionId` 的回调，越权或
+过期一律 401（fail-closed）；执行器共享 token 绝不进入任务子进程（SEC-01）。
+
+## 版本与发布
+
+- 版本策略：与 `@autocodeflow/sdk`（npm）、`autocodeflow-mcp-server` 走
+  **lockstep** 单版本线，当前 `1.0.0`。
+- 发布管道：[.github/workflows/release.yml](../../.github/workflows/release.yml)。
+  push tag `vX.Y.Z` 触发：版本一致性守卫（tag 必须等于本包
+  `pyproject.toml` version 与 `autoflow_sdk.__version__`，不一致直接
+  fail）→ `publish-pypi` job（python 3.12，`python -m build` +
+  `pypa/gh-action-pypi-publish`）。
+- 凭证：GitHub secret `PYPI_API_TOKEN`（pypi.org API token）；如改用
+  PyPI Trusted Publishing（OIDC）则删 workflow 中 `password` 行。
+- 元数据单一来源：`pyproject.toml`（`setup.py` 仅留 `setup()`）。
+- 本地演练（不真发布）：
+
+  ```bash
+  cd packages/autoflow-sdk
+  python -m pip install build && python -m build --wheel   # 产物在 dist/（已 gitignore）
+  ```
+
+- 发布流程与矩阵说明见
+  [docs/sdk-guide.md「SDK 矩阵」](../../docs/sdk-guide.md)。

autoflow_sdk-1.0.0/README.md

@@ -0,0 +1,131 @@
+# autoflow-sdk — AutoCodeFlow Python SDK
+
+AutoCodeFlow 任务执行器（executor-python）侧的 Python SDK：提供任务上下文
+（`TaskContext`）、日志（`ctx.log`）、Admin API 回调客户端
+（`CallbackClient` + `ctx.report_success()` / `ctx.report_failure()`）与
+通用 HTTP 客户端（`HttpClient` / `AsyncHttpClient`，基于 httpx）。回调契约
+与 Node.js SDK [`@autocodeflow/sdk`](../autocodeflow-node-sdk/README.md) 完全
+对齐（第九轮），双端共用 `CallbackItemDto` 字段。平台侧完整说明见
+[docs/sdk-guide.md](../../docs/sdk-guide.md)。
+
+## 安装
+
+```bash
+pip install autoflow-sdk                     # 公共 PyPI（发布后）
+# 内网私有 registry（apps/registry-pypi）：
+pip install --index-url http://<registry-pypi-host>/simple autoflow-sdk
+```
+
+要求 Python ≥ 3.9；运行时依赖 `httpx`、`pyyaml`、`pydantic>=2`
+（`autoflow_sdk.models` 的协议模型）；开发/测试依赖另需
+`pytest`、`pytest-asyncio`、`respx`（见 `[project.optional-dependencies].dev`）。
+
+## Quickstart
+
+任务脚本由执行器以子进程运行，环境变量注入见下表。
+`TaskContext.from_env()` 读取 `EXECUTION_ID` / `TASK_ID` / `TASK_NAME` 与
+全部 `AUTOFLOW_*` 触发参数（回调凭证三件套除外——它们暴露为专用字段，
+绝不混入 `ctx.params`）：
+
+```python
+# tasks/fetch_data.py
+from autoflow_sdk import TaskContext
+
+ctx = TaskContext.from_env()
+ctx.log.info(f"task {ctx.task_id} started, execution={ctx.execution_id}")
+
+source_url = ctx.get_param("source_url")          # AUTOFLOW_SOURCE_URL
+rows = do_work(source_url)
+
+# 主动回调 Admin API（N23 per-execution token）。旧版执行器不注入凭证，
+# 此时 ctx.callback.enabled 为 False，结果仍由执行器统一上报。
+if ctx.callback.enabled:
+    ctx.report_success(summary=f"{rows} rows written", duration_ms=1200)
+```
+
+失败上报（`error` 映射为 `errorMessage` 并截断至 4 KB；`failure_reason`
+取 admin-api 的 `ExecutionFailureReason` 枚举，默认 `script_error`，非法值
+抛 `ValueError`）：
+
+```python
+try:
+    rows = do_work(source_url)
+except Exception as e:
+    if ctx.callback.enabled:
+        ctx.report_failure(e, failure_reason="script_error")
+    raise
+```
+
+### 底层回调客户端
+
+批量/自定义字段时直接使用 `ctx.callback.report()`，
+`executionId` / `executorAddress` 自动补齐（N27），显式书写的值不会被覆盖：
+
+```python
+ctx.callback.report([
+    {"status": "success", "durationMs": 800},
+    {"status": "success", "durationMs": 900, "logs": "checkpoint 2"},
+])
+```
+
+凭证缺失时任何上报调用抛 `CallbackDisabledError` 并指明缺失变量
+（fail-closed，与 Node `HttpClient.disabledReason` 语义对齐）。
+
+### HttpClient 直用
+
+通用 HTTP 客户端（非回调专用）可独立构造：
+
+```python
+from autoflow_sdk import HttpClient, AsyncHttpClient
+
+http = HttpClient(base_url="http://admin-api:3105", timeout=30.0,
+                  headers={"Authorization": f"Bearer {token}"})
+resp = http.get("/api/tasks")            # 返回 httpx.Response
+
+async with AsyncHttpClient(base_url=...) as ahttp:
+    resp = await ahttp.post("/api/x", json={"a": 1})
+```
+
+## 执行器注入的环境变量
+
+与 [docs/sdk-guide.md](../../docs/sdk-guide.md) 的注入表逐字一致：
+
+| 变量名 | 说明 | 示例值 |
+|--------|------|--------|
+| `TASK_ID` | 当前任务的唯一标识 | `task_abc123` |
+| `TASK_NAME` | 当前任务名称 | `fetch_data` |
+| `EXECUTION_ID` | 本次执行记录的唯一标识 | `exec_xyz789` |
+| `AUTOFLOW_<KEY>` | 触发参数，按参数名转大写后注入 | `AUTOFLOW_SOURCE_URL=https://api.example.com` |
+| `AUTOFLOW_ADMIN_API_URL` | Admin API 基地址（非机密路由信息，N23 起注入） | `AUTOFLOW_ADMIN_API_URL=http://admin-api:3105` |
+| `AUTOFLOW_CALLBACK_TOKEN` | 本次执行的一次性回调 token（`v1.` HMAC，绑定 executionId、随 TTL 过期，N23 起注入） | `AUTOFLOW_CALLBACK_TOKEN=v1.<uuid>.<exp>.<hmac>` |
+| `AUTOFLOW_EXECUTOR_ADDRESS` | 当前执行器注册地址（非机密路由信息，N27 起注入；SDK 经 `ctx.executorAddress`（Node）/ `ctx.executor_address`（Python）暴露并自动填入回调请求） | `AUTOFLOW_EXECUTOR_ADDRESS=executor-node:8002` |
+
+## 回调契约（与 Node SDK 一致）
+
+`POST {AUTOFLOW_ADMIN_API_URL}/api/executions/callback`，请求体为
+`CallbackItemDto[]`：`executionId` / `status: success|failed` /
+`executorAddress` / `logs` / `errorMessage` / `failureReason` /
+`durationMs`。per-execution token 仅授权本 `executionId` 的回调，越权或
+过期一律 401（fail-closed）；执行器共享 token 绝不进入任务子进程（SEC-01）。
+
+## 版本与发布
+
+- 版本策略：与 `@autocodeflow/sdk`（npm）、`autocodeflow-mcp-server` 走
+  **lockstep** 单版本线，当前 `1.0.0`。
+- 发布管道：[.github/workflows/release.yml](../../.github/workflows/release.yml)。
+  push tag `vX.Y.Z` 触发：版本一致性守卫（tag 必须等于本包
+  `pyproject.toml` version 与 `autoflow_sdk.__version__`，不一致直接
+  fail）→ `publish-pypi` job（python 3.12，`python -m build` +
+  `pypa/gh-action-pypi-publish`）。
+- 凭证：GitHub secret `PYPI_API_TOKEN`（pypi.org API token）；如改用
+  PyPI Trusted Publishing（OIDC）则删 workflow 中 `password` 行。
+- 元数据单一来源：`pyproject.toml`（`setup.py` 仅留 `setup()`）。
+- 本地演练（不真发布）：
+
+  ```bash
+  cd packages/autoflow-sdk
+  python -m pip install build && python -m build --wheel   # 产物在 dist/（已 gitignore）
+  ```
+
+- 发布流程与矩阵说明见
+  [docs/sdk-guide.md「SDK 矩阵」](../../docs/sdk-guide.md)。

autoflow_sdk-1.0.0/autoflow_sdk/__init__.py

@@ -0,0 +1,14 @@
+"""AutoFlow SDK — Python base utilities."""
+from .context import TaskContext
+from .logger import get_logger
+from .http import HttpClient, AsyncHttpClient
+from .callback import CallbackClient, CallbackDisabledError
+from .result import TaskResult
+from .models import ExecuteRequest, ExecuteResult, TaskConfig
+
+__version__ = "1.0.0"
+__all__ = [
+    "TaskContext", "get_logger", "HttpClient", "AsyncHttpClient", "TaskResult",
+    "ExecuteRequest", "ExecuteResult", "TaskConfig",
+    "CallbackClient", "CallbackDisabledError",
+]

autoflow_sdk-1.0.0/autoflow_sdk/callback.py

@@ -0,0 +1,179 @@
+"""Per-execution Admin API callback client (N23/N27 parity with node SDK).
+
+Since round 7/8 the executors inject three variables into task subprocesses:
+
+- ``AUTOFLOW_CALLBACK_TOKEN`` — a one-shot ``v1.<executionId>.<exp>.<hmac>``
+  token bound to THIS execution (never the executor shared token, SEC-01);
+- ``AUTOFLOW_ADMIN_API_URL`` — Admin API base URL (non-secret routing info);
+- ``AUTOFLOW_EXECUTOR_ADDRESS`` — the address this executor registered with
+  (N27), stamped onto callback items automatically.
+
+Task code uses them via ``TaskContext``::
+
+    ctx = TaskContext.from_env()
+    if ctx.callback.enabled:
+        ctx.report_success(summary="3 rows written")
+    # or, on failure:
+    ctx.report_failure(ValueError("upstream 503"))
+
+The client is ENABLED only when all three credentials are present. When
+disabled, construction still succeeds (so ``ctx.callback.enabled`` can be
+checked), but any report attempt raises :class:`CallbackDisabledError`
+naming the missing variables — the same contract as the node SDK's
+``HttpClient.disabledReason``.
+
+Payload shape follows admin-api's ``CallbackItemDto``
+(apps/admin-api/src/modules/task/dto/execution-callback.dto.ts):
+``POST {admin_api_url}/api/executions/callback`` with
+``Authorization: Bearer <token>`` and a JSON array body of
+``{executionId, status, executorAddress, logs?, errorMessage?,
+failureReason?, durationMs?}`` items.
+"""
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+# CallbackItemDto field constraints (keep in sync with the admin DTO).
+ERROR_MESSAGE_MAX_LENGTH = 4096
+LOGS_MAX_LENGTH = 512_000
+
+# ExecutionFailureReason enum values accepted by the DTO validation.
+VALID_FAILURE_REASONS = frozenset({
+    "package_fetch_failed",
+    "script_error",
+    "timeout",
+    "executor_offline",
+    "executor_restart",
+    "killed",
+    "unknown",
+})
+
+
+class CallbackDisabledError(RuntimeError):
+    """Raised when a callback is attempted without full credentials."""
+
+
+class CallbackClient:
+    """Synchronous client for ``POST /api/executions/callback``."""
+
+    def __init__(
+        self,
+        admin_api_url: Optional[str] = None,
+        token: Optional[str] = None,
+        executor_address: Optional[str] = None,
+        execution_id: Optional[str] = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self.admin_api_url = (admin_api_url or "").rstrip("/")
+        self.token = token or ""
+        self.executor_address = executor_address or ""
+        self.execution_id = execution_id or ""
+        self.timeout = timeout
+
+        missing = []
+        if not self.admin_api_url:
+            missing.append("AUTOFLOW_ADMIN_API_URL")
+        if not self.token:
+            missing.append("AUTOFLOW_CALLBACK_TOKEN")
+        if not self.executor_address:
+            missing.append("AUTOFLOW_EXECUTOR_ADDRESS")
+        #: Whether all three callback credentials are present.
+        self.enabled = not missing
+        #: Reason for being disabled (populated only when ``enabled`` is False).
+        self.disabled_reason: Optional[str] = None
+        if not self.enabled:
+            self.disabled_reason = (
+                "CallbackClient is disabled: Admin API callback credentials are "
+                "missing (" + ", ".join(missing) + " were not present in the "
+                "environment; older executors never inject them, see SEC-01/N23). "
+                "Provide them via TaskContext(callback_token=..., admin_api_url=..., "
+                "executor_address=...) if callbacks are required."
+            )
+
+    # ------------------------------------------------------------------ url
+
+    @property
+    def callback_url(self) -> str:
+        """Full callback endpoint URL; tolerates a base that already ends in /api."""
+        if self.admin_api_url.endswith("/api"):
+            return f"{self.admin_api_url}/executions/callback"
+        return f"{self.admin_api_url}/api/executions/callback"
+
+    # ------------------------------------------------------------------ core
+
+    def report(self, items: List[Dict[str, Any]]) -> Any:
+        """POST a batch of CallbackItemDto dicts. Returns the parsed response.
+
+        Raises CallbackDisabledError without credentials, httpx.HTTPStatusError
+        on a non-2xx answer from the Admin API.
+        """
+        if not self.enabled:
+            raise CallbackDisabledError(self.disabled_reason)
+        payload = [self._with_defaults(item) for item in items]
+        with httpx.Client(timeout=self.timeout, trust_env=False) as client:
+            resp = client.post(
+                self.callback_url,
+                json=payload,
+                headers={"Authorization": f"Bearer {self.token}"},
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    def _with_defaults(self, item: Dict[str, Any]) -> Dict[str, Any]:
+        """Fill executionId / executorAddress on items that omit them (N27)."""
+        filled = dict(item)
+        if not filled.get("executionId"):
+            filled["executionId"] = self.execution_id
+        if not filled.get("executorAddress"):
+            filled["executorAddress"] = self.executor_address
+        return filled
+
+    # ------------------------------------------------------- convenience
+
+    def report_success(
+        self,
+        summary: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+    ) -> Any:
+        """Report status=success for this client's execution."""
+        item: Dict[str, Any] = {
+            "executionId": self.execution_id,
+            "status": "success",
+            "executorAddress": self.executor_address,
+        }
+        if summary:
+            item["logs"] = summary[:LOGS_MAX_LENGTH]
+        if duration_ms is not None:
+            item["durationMs"] = duration_ms
+        return self.report([item])
+
+    def report_failure(
+        self,
+        error: Any,
+        summary: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+        failure_reason: str = "script_error",
+    ) -> Any:
+        """Report status=failed for this client's execution.
+
+        ``error`` (any object) is stringified into ``errorMessage`` and
+        truncated to the DTO's 4 KB cap; ``failure_reason`` must be one of
+        admin-api's ExecutionFailureReason values (default ``script_error``).
+        """
+        if failure_reason not in VALID_FAILURE_REASONS:
+            raise ValueError(
+                f"invalid failure_reason {failure_reason!r}; expected one of "
+                + ", ".join(sorted(VALID_FAILURE_REASONS))
+            )
+        item: Dict[str, Any] = {
+            "executionId": self.execution_id,
+            "status": "failed",
+            "executorAddress": self.executor_address,
+            "errorMessage": str(error)[:ERROR_MESSAGE_MAX_LENGTH],
+            "failureReason": failure_reason,
+        }
+        if summary:
+            item["logs"] = summary[:LOGS_MAX_LENGTH]
+        if duration_ms is not None:
+            item["durationMs"] = duration_ms
+        return self.report([item])

autoflow_sdk-1.0.0/autoflow_sdk/context.py

@@ -0,0 +1,153 @@
+"""Task execution context — passed to every task handler."""
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+import os
+
+from .callback import CallbackClient
+
+# R9 (round-9): AUTOFLOW_* keys that carry callback credentials / routing
+# info (N23/N27 parity with executor-node). They are exposed as dedicated
+# TaskContext fields and deliberately EXCLUDED from `params` — folding a
+# one-shot HMAC token or a deployment address into user task parameters
+# would pollute the parameter view and leak the credential into any code
+# that dumps ctx.params.
+_CALLBACK_ENV_KEYS = {
+    "AUTOFLOW_CALLBACK_TOKEN": "callback_token",
+    "AUTOFLOW_ADMIN_API_URL": "admin_api_url",
+    "AUTOFLOW_EXECUTOR_ADDRESS": "executor_address",
+}
+
+
+@dataclass
+class TaskContext:
+    """Provides runtime metadata and helpers to a running task."""
+
+    task_id: str
+    execution_id: str
+    task_name: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    env: Dict[str, str] = field(default_factory=dict)
+
+    # Callback credentials injected by the executor (N23/N27). All optional:
+    # older executors never inject them, in which case `ctx.callback` (and
+    # the `ctx.report_success` / `ctx.report_failure` shorthands) stay
+    # disabled and raise a descriptive error when used.
+    # N40 (round-10): repr=False — the dataclass __repr__ is a leak surface
+    # the same as to_dict (N27): a task's `print(ctx)` / f-string debug log
+    # would otherwise carry the one-shot HMAC token into the executor's
+    # captured stdout → admin DB (execution logs), where any JWT user who
+    # can read the execution could replay it within its TTL window.
+    callback_token: Optional[str] = field(default=None, repr=False)
+    admin_api_url: Optional[str] = field(default=None, repr=False)
+    executor_address: Optional[str] = field(default=None, repr=False)
+
+    # Runtime helpers — populated lazily
+    _logger: Optional[Any] = field(default=None, repr=False)
+    _callback_client: Optional[CallbackClient] = field(default=None, repr=False)
+
+    def get_param(self, key: str, default: Any = None) -> Any:
+        """Retrieve a task parameter by key."""
+        return self.params.get(key, default)
+
+    def get_env(self, key: str, default: str = "") -> str:
+        """Retrieve an environment variable (task env first, then OS env)."""
+        return self.env.get(key, os.environ.get(key, default))
+
+    @property
+    def log(self):
+        if self._logger is None:
+            from .logger import get_logger
+            object.__setattr__(self, "_logger", get_logger(self.task_name))
+        return self._logger
+
+    @property
+    def callback(self) -> CallbackClient:
+        """Per-execution Admin API callback client (N23/N27 parity).
+
+        Lazily built from the injected credentials; check
+        ``ctx.callback.enabled`` before reporting (older executors do not
+        inject the credentials). See :class:`autoflow_sdk.callback.CallbackClient`.
+        """
+        if self._callback_client is None:
+            object.__setattr__(
+                self,
+                "_callback_client",
+                CallbackClient(
+                    admin_api_url=self.admin_api_url,
+                    token=self.callback_token,
+                    executor_address=self.executor_address,
+                    execution_id=self.execution_id,
+                ),
+            )
+        return self._callback_client
+
+    def report_success(self, summary: Optional[str] = None, duration_ms: Optional[int] = None) -> Any:
+        """Report this execution's success to the Admin API.
+
+        Shorthand for ``ctx.callback.report_success(...)``; raises
+        ``CallbackDisabledError`` when callback credentials are absent.
+        """
+        return self.callback.report_success(summary=summary, duration_ms=duration_ms)
+
+    def report_failure(
+        self,
+        error: Any,
+        summary: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+        failure_reason: str = "script_error",
+    ) -> Any:
+        """Report this execution's failure to the Admin API.
+
+        ``error`` is mapped to the callback item's ``errorMessage`` and
+        ``failure_reason`` (default ``script_error``) to its structured
+        ``failureReason``. Raises ``CallbackDisabledError`` when callback
+        credentials are absent.
+        """
+        return self.callback.report_failure(
+            error, summary=summary, duration_ms=duration_ms, failure_reason=failure_reason
+        )
+
+    @classmethod
+    def from_env(cls) -> "TaskContext":
+        """
+        Create TaskContext from environment variables injected by the executor.
+
+        Reads EXECUTION_ID, TASK_ID, TASK_NAME, and all AUTOFLOW_* vars as
+        params — except the callback credential keys
+        (``AUTOFLOW_CALLBACK_TOKEN``, ``AUTOFLOW_ADMIN_API_URL``,
+        ``AUTOFLOW_EXECUTOR_ADDRESS``), which are exposed as dedicated
+        fields and never leak into ``params``.
+
+        Usage::
+
+            from autoflow_sdk import TaskContext
+
+            ctx = TaskContext.from_env()
+            ctx.log.info(f"Task {ctx.task_id} started")
+            date = ctx.get_param("date")
+        """
+        params: dict[str, Any] = {}
+        callback_fields: dict[str, str] = {}
+        for k, v in os.environ.items():
+            if not k.startswith("AUTOFLOW_") or not v:
+                continue
+            if k in _CALLBACK_ENV_KEYS:
+                callback_fields[_CALLBACK_ENV_KEYS[k]] = v
+                continue
+            params[k[len("AUTOFLOW_"):].lower()] = v
+
+        return cls(
+            task_id=os.environ.get("TASK_ID", "unknown"),
+            execution_id=os.environ.get("EXECUTION_ID", "unknown"),
+            task_name=os.environ.get("TASK_NAME", "unknown"),
+            params=params,
+            **callback_fields,
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "execution_id": self.execution_id,
+            "task_name": self.task_name,
+            "params": self.params,
+        }