imperal-sdk 4.2.12__tar.gz → 4.2.13__tar.gz

{imperal_sdk-4.2.12 → imperal_sdk-4.2.13}/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 4.2.13 — 2026-05-14
+
+**Feat: `@chat.function(background=True)` declarative flag**
+
+Sugar over `ctx.background_task(coro, ...)` from v4.2.12 — author writes
+one handler body, the SDK auto-wraps the call in `ctx.background_task()`
+when the flag is set.
+
+### Added
+
+- **`@chat.function(..., background=True, long_running=False)`** — when
+  `background=True`, the SDK chat handler wraps the function call in
+  `ctx.background_task()` instead of running the handler synchronously.
+  The LLM receives an immediate ack envelope carrying `task_id`; the
+  platform delivers the handler's returned `ActionResult` as a fresh
+  bot turn when the work finishes. `long_running=True` raises the
+  federal 180-second cap to 1800 seconds.
+
+  ```python
+  @chat.function(
+      "refine_output",
+      description="Refine the given text via AI completion.",
+      action_type="write",
+      event="text_refined",
+      background=True,        # auto-wrap in ctx.background_task
+      long_running=False,     # default cap 180s; True → 1800s
+  )
+  async def refine_output(ctx, params: RefineParams) -> ActionResult:
+      # Body runs detached. No inner _work() wrapper, no manual task_id.
+      await ctx.progress(50, "Generating with AI")
+      resp = await ctx.http.post(api_url, json={...}, timeout=120)
+      return ActionResult.success(
+          summary="Refined output ready!",
+          data={"text": resp.body["text"]},
+      )
+  ```
+
+- **Manifest emission** — tools in `imperal.json` now carry `background`
+  and `long_running` booleans. Strict `Manifest.Tool` schema gains
+  matching optional fields.
+
+### Trade-offs vs. explicit `ctx.background_task(coro)`
+
+- **Sugar** is best for handlers whose entire body is the long work.
+- **Explicit** stays preferred when you need to return a custom
+  acknowledgement summary, choose `background_task()` conditionally at
+  runtime, or run mixed sync + background work in the same handler.
+
+### Migration
+
+None required — `background` defaults to `False`. Existing
+`@chat.function` handlers work unchanged.
+
 ## 4.2.12 — 2026-05-14
 
 **Feat: LONGRUN-V1 Session 1 — long-running operations primitives**
@@ -23,27 +76,21 @@ Three new SDK surfaces for ops that exceed the 30s `ctx.http` ceiling:
   (`LONG_RUNNING_TASK_S`). Returns task_id immediately.
 
 - **`ctx.deliver_chat_message(text, *, msg_type="response", refresh_panels=None)`**
-  — public API for extension-initiated bot turn injection. Posts to
-  auth-gw `/v1/internal/chat/inject`. Text truncated to 64KB with marker.
-  `msg_type` ∈ `{response, system, tool_result}`.
+  — public API for extension-initiated bot turn injection. Text truncated
+  to 64KB with marker. `msg_type` ∈ `{response, system, tool_result}`.
 
 ### Federal invariants (new)
 
-- `I-LONGRUN-HTTP-CAP-180S` — per-call timeout federal cap
-- `I-LONGRUN-BG-CORO-RETURNS-ACTIONRESULT` — coro contract enforced
-  kernel-side via `_explicit_background_task_completion` isinstance
-  check; violation writes critical audit row + delivers fallback error.
-- `I-LONGRUN-BG-USER-SCOPED` — task bound to `(ext_id, user_id)` at
-  creation (existing `util/task_manager.py` invariant).
-- `I-LONGRUN-CHAT-INJECT-USER-SCOPED` — `X-Acting-User` header must
-  match `body.user_id` (auth-gw 403 on mismatch).
-- `I-LONGRUN-CHAT-INJECT-AUDIT-EVERY` — every inject writes an
-  `action_ledger` row through the `write_audit` chokepoint.
-
-### Spec
-
-`superpowers/specs/2026-05-13-longrun-v1-design.md`. Sessions 2 (Sharelock
-canary migration) and 3 (docs + observability) ship after 24h soak.
+- `I-LONGRUN-HTTP-CAP-180S` — per-call timeout federal cap.
+- `I-LONGRUN-BG-CORO-RETURNS-ACTIONRESULT` — the coroutine MUST return
+  `ActionResult`; non-ActionResult return triggers a critical audit row
+  and delivers a fallback error to chat.
+- `I-LONGRUN-BG-USER-SCOPED` — every background task is bound to
+  `(ext_id, user_id)` at creation; cross-user cancel/status returns 403.
+- `I-LONGRUN-CHAT-INJECT-USER-SCOPED` — chat inject scoped to
+  `(ext_id, user_id)`; cross-user inject returns 403.
+- `I-LONGRUN-CHAT-INJECT-AUDIT-EVERY` — every chat inject writes an
+  audit row.
 
 ### Migration
 

{imperal_sdk-4.2.12 → imperal_sdk-4.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 4.2.12
+Version: 4.2.13
 Summary: SDK for building Imperal Cloud extensions
 Author: Valentin Scerbacov, Imperal, Inc.
 License-Expression: AGPL-3.0-or-later

{imperal_sdk-4.2.12 → imperal_sdk-4.2.13}/src/imperal_sdk/__init__.py

@@ -39,7 +39,7 @@ from imperal_sdk.secrets import (
     SecretValueTooLarge, SecretDeclarationConflict,
 )
 
-__version__ = "4.2.12"
+__version__ = "4.2.13"
 
 __all__ = [
     # Core

{imperal_sdk-4.2.12 → imperal_sdk-4.2.13}/src/imperal_sdk/chat/extension.py

@@ -58,6 +58,12 @@ class FunctionDef:
     chain_callable: bool = True  # federal v4.0.0 — kernel uses typed dispatch
     effects: list[str] = field(default_factory=list)  # ["create:note", "delete:folder", ...]
     id_projection: str = ""  # federal v4.1.2 — params field carrying resolved target id
+    # LONGRUN-V1 Component D (v4.2.13+) — declarative sugar over ctx.background_task.
+    # When background=True, the SDK chat handler auto-wraps the function call in
+    # ctx.background_task(); the LLM sees an immediate ack with task_id and the
+    # platform delivers the handler's ActionResult as a fresh bot turn when done.
+    background: bool = False
+    long_running: bool = False
     _pydantic_model: type | None = None  # auto-detected Pydantic BaseModel class
     _pydantic_param: str = ""  # parameter name that receives the model instance
     _return_model: type | None = None  # auto-detected return Pydantic model
@@ -115,7 +121,9 @@ class ChatExtension:
                  event_schema: type | None = None,
                  chain_callable: bool | None = None,
                  effects: list[str] | None = None,
-                 id_projection: str | None = None):
+                 id_projection: str | None = None,
+                 background: bool = False,
+                 long_running: bool = False):
         """Register a chat function (federal v4.0.0 contract).
 
         Args:
@@ -218,6 +226,8 @@ class ChatExtension:
                 chain_callable=chain_callable,
                 effects=list(effects or []),
                 id_projection=id_projection or "",
+                background=background,
+                long_running=long_running,
                 _pydantic_model=_detected_model, _pydantic_param=_detected_param,
                 _return_model=_detected_return_model,
             )

{imperal_sdk-4.2.12 → imperal_sdk-4.2.13}/src/imperal_sdk/chat/handler.py

@@ -236,7 +236,36 @@ async def _execute_function(
 
     while True:
         try:
-            if _func_def._pydantic_model and _func_def._pydantic_param:
+            # LONGRUN-V1 Component D (v4.2.13+) — declarative background-task sugar.
+            # When the handler is decorated with @chat.function(background=True),
+            # the SDK auto-wraps the call in ctx.background_task() and returns an
+            # immediate ack envelope to the LLM. The actual handler runs detached;
+            # the platform delivers its returned ActionResult as a fresh bot turn.
+            if getattr(_func_def, "background", False):
+                _bg_pydantic_model = _func_def._pydantic_model
+                _bg_pydantic_param = _func_def._pydantic_param
+                _bg_input = current_tu.input or {}
+                _bg_fn = _func_def.func
+
+                async def _bg_coro():
+                    if _bg_pydantic_model and _bg_pydantic_param:
+                        _mi = _bg_pydantic_model(**_bg_input)
+                        return await _bg_fn(ctx, **{_bg_pydantic_param: _mi})
+                    return await _bg_fn(ctx, **_bg_input)
+
+                _bg_task_id = await ctx.background_task(
+                    _bg_coro(),
+                    long_running=bool(getattr(_func_def, "long_running", False)),
+                    name=current_tu.name,
+                )
+                result = ActionResult.success(
+                    summary=(
+                        f"Started '{current_tu.name}' in background — "
+                        "the result will be sent to chat when it finishes."
+                    ),
+                    data={"task_id": _bg_task_id, "background": True},
+                )
+            elif _func_def._pydantic_model and _func_def._pydantic_param:
                 _model_instance = _func_def._pydantic_model(**(current_tu.input or {}))
                 result = await _func_def.func(ctx, **{_func_def._pydantic_param: _model_instance})
             else:

{imperal_sdk-4.2.12 → imperal_sdk-4.2.13}/src/imperal_sdk/manifest.py

@@ -102,6 +102,8 @@ def generate_manifest(ext: Extension) -> dict:
                 "params_schema": params_schema,
                 "return_schema": return_schema,
                 "event": fn_def.event or "",
+                "background": bool(getattr(fn_def, "background", False)),
+                "long_running": bool(getattr(fn_def, "long_running", False)),
                 "scopes": [],
                 "owner_chat_tool": chat_tool_name,
             })

{imperal_sdk-4.2.12 → imperal_sdk-4.2.13}/src/imperal_sdk/manifest_schema.py

@@ -102,6 +102,12 @@ class Tool(BaseModel):
     effects: List[str] = Field(default_factory=list)
     params_schema: Optional[Dict[str, Any]] = None
     return_schema: Optional[Dict[str, Any]] = None
+    # LONGRUN-V1 Component D (v4.2.13+) — declarative background-task sugar.
+    # When background=True, the SDK chat handler auto-wraps invocations of
+    # this tool in ctx.background_task(). long_running=True raises the
+    # federal 180s cap to 1800s.
+    background: Optional[bool] = None
+    long_running: Optional[bool] = None
     event: Optional[str] = None
     owner_chat_tool: Optional[str] = None
     synthetic: Optional[bool] = None

imperal_sdk-4.2.13/tests/test_chat_function_background_flag.py

@@ -0,0 +1,154 @@
+"""Component D — @chat.function(background=True, long_running=True) decorator flag.
+
+Sugar over ctx.background_task(coro) — the kernel auto-wraps the handler call
+in ctx.background_task() under the hood; author writes one handler body, no
+explicit inner coro wrapper.
+"""
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel
+
+from imperal_sdk import ActionResult, Extension
+from imperal_sdk.chat import ChatExtension
+
+
+class _RefineParams(BaseModel):
+    text: str
+
+
+def test_decorator_accepts_background_and_long_running_kwargs():
+    ext = Extension("ext-bg-test", display_name="Bg Test",
+                    description="Background flag smoke test extension.",
+                    actions_explicit=True)
+    chat = ChatExtension(ext, tool_name="ext_bg_test_chat",
+                         description="bg test")
+
+    @chat.function(
+        "refine_output",
+        "Refine some text",
+        action_type="write",
+        event="refined",
+        background=True,
+        long_running=True,
+    )
+    async def refine_output(ctx, params: _RefineParams) -> ActionResult:
+        return ActionResult.success(data={"out": params.text.upper()})
+
+    fn = chat.functions["refine_output"]
+    assert fn.background is True
+    assert fn.long_running is True
+
+
+def test_decorator_defaults_background_false():
+    ext = Extension("ext-bg-default", display_name="Bg Default",
+                    description="Background flag default-False smoke test.",
+                    actions_explicit=True)
+    chat = ChatExtension(ext, tool_name="ext_bg_default_chat",
+                         description="default")
+
+    @chat.function("plain", "Plain handler", action_type="read")
+    async def plain(ctx, params: _RefineParams) -> ActionResult:
+        return ActionResult.success(data={"echo": params.text})
+
+    fn = chat.functions["plain"]
+    assert fn.background is False
+    assert fn.long_running is False
+
+
+def test_manifest_emits_background_and_long_running():
+    """Tool entry in imperal.json carries the new fields."""
+    from imperal_sdk.manifest import generate_manifest
+
+    ext = Extension("ext-bg-manifest", display_name="Bg Manifest",
+                    description="Background flag manifest emission test.",
+                    actions_explicit=True)
+    chat = ChatExtension(ext, tool_name="ext_bg_manifest_chat",
+                         description="manifest")
+
+    @chat.function(
+        "do_long_work",
+        "Do long work",
+        action_type="write",
+        event="work_done",
+        background=True,
+        long_running=True,
+    )
+    async def do_long_work(ctx, params: _RefineParams) -> ActionResult:
+        return ActionResult.success()
+
+    manifest = generate_manifest(ext)
+    tool_entry = next(t for t in manifest["tools"] if t["name"] == "do_long_work")
+    assert tool_entry["background"] is True
+    assert tool_entry["long_running"] is True
+
+
+@pytest.mark.asyncio
+async def test_handler_wraps_in_background_task_when_flag_set():
+    """When background=True, the SDK handler MUST call ctx.background_task
+    instead of running the handler synchronously. The tool result returned
+    to the LLM should be an ack with task_id, not the handler's return value.
+    """
+    from imperal_sdk.chat.handler import _execute_function
+    from imperal_sdk.context import Context
+    from imperal_sdk.types.identity import UserContext
+
+    # Counter to verify spawn hook was called, not the handler synchronously.
+    spawn_calls: list = []
+
+    async def _spawn_hook(coro, *, long_running, name):
+        spawn_calls.append({"long_running": long_running, "name": name})
+        coro.close()
+        return "task_bg_abc"
+
+    ext = Extension("ext-bg-runtime", display_name="Bg Runtime",
+                    description="Background runtime wrap smoke test.",
+                    actions_explicit=True)
+    chat = ChatExtension(ext, tool_name="ext_bg_runtime_chat",
+                         description="runtime")
+
+    handler_ran = []
+
+    @chat.function(
+        "long_refine",
+        "Refine text long-running",
+        action_type="write",
+        event="refined_long",
+        background=True,
+        long_running=True,
+    )
+    async def long_refine(ctx, params: _RefineParams) -> ActionResult:
+        handler_ran.append(True)
+        return ActionResult.success(data={"result": params.text.upper()})
+
+    ctx = Context(user=UserContext(
+        imperal_id="imp_u_t", email="t@t.com", tenant_id="t", role="user",
+    ))
+    ctx._background_task_spawn = _spawn_hook  # type: ignore[attr-defined]
+
+    # Simulate one tool call from the LLM
+    from types import SimpleNamespace
+    tu = SimpleNamespace(name="long_refine", input={"text": "hello"})
+
+    cfg = {
+        "max_result_tokens": 4096,
+        "list_truncate_items": 50,
+        "string_truncate_chars": 200,
+    }
+    chat._functions_called = []
+    result_str = await _execute_function(
+        chat_ext=chat, ctx=ctx, tu=tu,
+        action_type="write", cfg=cfg, retry_ctx=None,
+    )
+
+    # Spawn hook was called → handler is detached
+    assert len(spawn_calls) == 1
+    assert spawn_calls[0]["long_running"] is True
+    assert spawn_calls[0]["name"] == "long_refine"
+    # Handler body did NOT run synchronously (the coro was closed by spawn hook)
+    assert handler_ran == []
+    # Tool result returned to LLM is the background-ack envelope
+    import json as _j
+    res = _j.loads(result_str)
+    assert res.get("status") == "success"
+    assert "task_id" in (res.get("data") or {})