imperal-sdk 5.0.0__tar.gz → 5.0.2__tar.gz

{imperal_sdk-5.0.0 → imperal_sdk-5.0.2}/CHANGELOG.md

@@ -2,6 +2,211 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 5.0.2 — 2026-05-26 — Federal source-cite hygiene
+
+**Docs-only release. No behavior change. No new APIs.** Adds two federal-contract
+citation comments in source so the kernel's federal source-cite test gates
+(`I-SDK-DECORATOR-DATA-MODEL-KWARG` + `I-SDK-RETURN-DATA-VALIDATED-AT-EMIT`)
+stay green across SDK reinstalls.
+
+### Touched files
+
+- `src/imperal_sdk/chat/extension.py` — `data_model` kwarg docstring now cites
+  `I-SDK-DECORATOR-DATA-MODEL-KWARG`.
+- `src/imperal_sdk/types/action_result.py` — `validate_against` docstring now
+  cites `I-SDK-RETURN-DATA-VALIDATED-AT-EMIT`.
+
+### Why
+
+The kernel federal suite asserts the literal invariant IDs appear in SDK
+source. 5.0.1 shipped without the comments; the kernel's 2 source-cite
+tests stayed pinned green by an in-place edit of the venv `site-packages`
+copy which would not survive a future `pip install -U`. 5.0.2 closes that
+durability gap.
+
+No federal contracts changed, no public API changes, no schema drift.
+
+## 5.0.1 — 2026-05-17 — Federal Typed Return Contract
+
+**Additive (no breaking changes).** Adds typed return contract for
+`@chat.function` handlers so the platform can validate `$REF` paths in
+multi-step chains against a declared schema and prevent input/output
+field-name drift. Extensions built against 5.0.0 continue to work
+unmodified — V23 ships as **WARN** in 5.0.1 and may promote to **ERROR**
+in a future minor after third-party adoption (env-toggle:
+`IMPERAL_VALIDATOR_V23_SEVERITY=error`).
+
+### What's new
+
+- **`@chat.function(data_model=...)` kwarg.** Declare the Pydantic
+  `BaseModel` subclass that describes `ActionResult.data` for this tool.
+  When declared, the SDK populates `FunctionDef._return_model` directly,
+  emits a `return_schema` field into the manifest, and the platform uses
+  the schema to:
+  1. Validate `$REF:<app_id>[<n>].path` references in chain steps against
+     real field names (closes the "next step references field that doesn't
+     exist" class).
+  2. Render `return_fields` in the classifier envelope so the LLM knows
+     what shape it can read.
+  3. Run `data.model_validate(...)` at emit time (warn-only in 5.0.1).
+- **`ActionResult[T]` generic auto-detection.** `-> ActionResult[NoteRecord]`
+  return annotations now populate `_return_model=NoteRecord` automatically.
+  Resolution priority for `_return_model`:
+  1. Explicit `data_model=` kwarg — wins.
+  2. Direct `-> SomeBaseModel` return annotation.
+  3. `-> ActionResult[T]` generic extraction.
+  4. None of the above → `_return_model = None`.
+- **`ActionResult.validate_against(model_class)` method.** Validates
+  `self.data` against a Pydantic model class, logs a structured warning
+  on mismatch, never raises. Useful for early type assurance in handler
+  code.
+- **Validator V23 (read tools, WARN by default).** Every
+  `@chat.function(action_type="read", ...)` SHOULD declare `data_model=`
+  (or use `-> ActionResult[T]` / `-> SomeBaseModel`). Toggle via
+  `IMPERAL_VALIDATOR_V23_SEVERITY=warn|error`.
+- **Validator V24 (write/destructive tools, WARN).** Same rule as V23
+  but advisory — declaring `data_model` on writes lets the chain narrator
+  and audit ledger describe the resulting entity shape without
+  re-deriving from text.
+- **`V31` first-party allowlist is now env-driven.** The SDK no longer
+  ships with an embedded allowlist. Set `IMPERAL_FIRSTPARTY_AUTHOR_IDS`
+  (comma-separated) at validation time to enable the local check; the
+  Dev Portal continues to enforce server-side at publish.
+- **Synthetic `Secrets` panel is lazy-registered.** Previously every
+  `Extension` got a synthetic `__panel__secrets` entry on the right slot
+  of the chat UI — even when the extension declared zero secrets, the
+  user saw an empty placeholder titled "Secrets" with developer-guidance
+  text. As of 5.0.1 the panel is registered ONLY when the extension
+  calls `@ext.secret(...)` for the first time. Extensions with secrets
+  see the same UI as before; extensions without secrets no longer ship
+  an empty placeholder panel. No code change required for ext authors;
+  no platform-side contract change (the federal secrets contract is
+  enforced manifest-side and is independent of UI presence).
+
+### Migration for extension authors
+
+**Reads (V23).** Add `data_model=...` to every `@chat.function(action_type="read", ...)`:
+
+```python
+from pydantic import BaseModel
+from imperal_sdk import Extension
+from imperal_sdk.chat import ChatExtension
+from imperal_sdk.chat.action_result import ActionResult
+
+class NoteRecord(BaseModel):
+    note_id: str
+    title: str
+    content: str
+    folder_id: str | None = None
+
+class ListNotesParams(BaseModel):
+    folder_id: str | None = None
+    limit: int = 50
+
+@chat.function(
+    name="list_notes",
+    description="List notes — paginated, optionally filtered by folder.",
+    action_type="read",
+    data_model=NoteRecord,
+)
+async def list_notes(ctx, params: ListNotesParams) -> ActionResult:
+    notes = await ctx.api.notes.list(folder_id=params.folder_id, limit=params.limit)
+    return ActionResult.success(data={"notes": notes}, summary=f"{len(notes)} notes")
+```
+
+Equivalent using the `ActionResult[T]` generic (no `data_model` kwarg
+needed):
+
+```python
+async def list_notes(ctx, params: ListNotesParams) -> ActionResult[NoteRecord]:
+    ...
+```
+
+**Field-name symmetry.** Use the **same field names** in your
+`data_model` as in the corresponding input `*Params` model. Closes a real
+drift class where input was `content_text` but the record exposed
+`content`, so chain steps referencing `$REF:notes[0].content_text` silently
+got `None`. If your input uses `content_text`, your `data_model` should
+expose `content_text` too (or vice versa — pick one and be consistent).
+
+**Writes (V24).** Same `data_model=` kwarg, recommended but not required:
+
+```python
+@chat.function(
+    name="create_note",
+    description="Create a new note with title, content, optional folder.",
+    action_type="write",
+    event="notes.created",
+    data_model=NoteRecord,  # what the call returns
+)
+async def create_note(ctx, params: CreateNoteParams) -> ActionResult:
+    note = await ctx.api.notes.create(params.model_dump())
+    return ActionResult.success(data=note, summary=f"Created {note['title']!r}")
+```
+
+### Skeleton contract reminder
+
+The skeleton layer is the **LLM context cache** read by the classifier
+and narrator — handlers must NOT read from it (V24-AST enforces this).
+Conventions when authoring an extension:
+
+1. **Refresh tools** that populate the skeleton MUST be named
+   `skeleton_refresh_<section>` (or use the `@ext.skeleton("<section>")`
+   decorator, which applies the convention automatically). The platform
+   auto-derives `skeleton_sections` rows from these names; tools named
+   `refresh_<section>` are NOT auto-wired (validator V13 WARN).
+2. **Alert tools** that fire when a refreshed section changes MUST be
+   named `skeleton_alert_<section>` (V13 INFO when prefix is missing).
+3. **Skeleton data is read-only to your handlers.** Never write
+   `ctx.skeleton.X = ...` or read `ctx.skeleton.X` inside a
+   `@chat.function` body — validator V24-AST hard-rejects it. Use
+   `ctx.api` to talk to the real backend; skeleton is refreshed
+   automatically after writes via your refresh tools.
+4. **Skeleton sections SHOULD have stable, typed shapes.** Document the
+   shape in a Pydantic model and serialise via `model_dump()` before
+   returning from your refresh tool — this keeps the LLM context cache
+   parseable and helps the classifier hint at what fields it can rely
+   on.
+
+### Dev Portal enforcement (publish gate)
+
+The Dev Portal runs `imperal_sdk.validator.validate_extension` against
+every submitted build. To make V23 a hard publish gate after third-party
+adoption, set the env var on the Dev Portal validator process:
+
+```
+IMPERAL_VALIDATOR_V23_SEVERITY=error
+```
+
+V23 then promotes from WARN to ERROR; submissions missing `data_model`
+on any `read` tool will be rejected at publish with a structured fix-hint
+pointing at the offending function.
+
+### Tests
+
+15 new tests covering:
+
+- `data_model=` kwarg propagation to `FunctionDef._return_model`.
+- Precedence: `data_model=` wins over `-> ActionResult[T]`.
+- `-> ActionResult[T]` generic auto-detection when `data_model` is absent.
+- V23 WARN (default) and ERROR (`IMPERAL_VALIDATOR_V23_SEVERITY=error`)
+  modes for read tools missing `data_model`.
+- V23 passes when `data_model=` declared OR `-> ActionResult[T]` used.
+- V24 WARN for write + destructive tools missing `data_model`.
+- V24 passes when `data_model=` declared.
+- `ActionResult.validate_against` passes / warns / no-ops correctly.
+- Synthetic `Secrets` panel: not registered when no secrets declared,
+  registered after first `@ext.secret(...)` call (lazy registration).
+
+### Compatibility
+
+- **No breaking change.** SDK 5.0.0 extensions continue to load and run
+  unmodified; V23 will surface as WARNs in the validation report but
+  publish stays green by default.
+- **Required platform.** Kernel that ingests `return_schema` from
+  manifests for `$REF` path validation: 5.0.1+. Earlier kernels ignore
+  the new field gracefully.
+
 ## 5.0.0 — 2026-05-15 — Unified Chain Orchestrator
 
 **BREAKING:**

{imperal_sdk-5.0.0 → imperal_sdk-5.0.2}/PKG-INFO

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

{imperal_sdk-5.0.0 → imperal_sdk-5.0.2}/src/imperal_sdk/__init__.py

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

{imperal_sdk-5.0.0 → imperal_sdk-5.0.2}/src/imperal_sdk/chat/extension.py

@@ -27,12 +27,12 @@ _ACTION_WORDS = ("send", "create", "delete", "update", "archive", "reply", "forw
 
 @dataclass
 class FunctionDef:
-    """Federal v4.0.0 — typed function declaration.
+    """Typed function declaration.
 
-    The kernel reads ``chain_callable`` from the manifest to pick typed
+    The platform reads ``chain_callable`` from the manifest to pick typed
     dispatch (direct ``app/func(args)`` call) vs. legacy ChatExtension
     LLM-router delegation. Default ``True`` for any ``action_type`` other
-    than ``"read"`` so the kernel can deterministically execute writes
+    than ``"read"`` so the platform can deterministically execute writes
     without giving the LLM a chance to summarise instead.
 
     ``effects`` declares the side-effect surface (``["create:note"]``,
@@ -41,12 +41,10 @@ class FunctionDef:
 
     ``id_projection`` declares the Pydantic params field that carries the
     resolved target id when this tool runs as a downstream chain step.
-    Default empty — the kernel falls back to a verb-prefix heuristic
+    Default empty — the platform falls back to a verb-prefix heuristic
     (``delete_note`` -> ``note_id``). Required for compound names where
     the heuristic produces a wrong field (``delete_notes_from_folder``
     would naively yield ``notes_from_folder_id`` instead of ``folder_id``).
-    Federal v4.1.2: one of ``id_projection``, the heuristic match, or
-    explicit kernel registration is required for chain step targets.
     """
     name: str
     func: Callable
@@ -55,18 +53,15 @@ class FunctionDef:
     action_type: str = "read"  # "read", "write", or "destructive"
     event: str = ""  # event name for ActionResult publishing (e.g. "mail.sent")
     event_schema: type | None = None  # Pydantic BaseModel for typed event data
-    chain_callable: bool = True  # federal v4.0.0 — kernel uses typed dispatch
+    chain_callable: bool = True  # platform 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.
+    id_projection: str = ""  # params field carrying resolved target id
     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
+    _return_model: type | None = None  # data_model kwarg OR autodetected return Pydantic model
+
 
 class ChatExtension:
     def __init__(self, ext, tool_name: str, description: str, system_prompt: str = "",
@@ -75,43 +70,35 @@ class ChatExtension:
         self.tool_name = tool_name
         self.description = description
         self.system_prompt = system_prompt
-        # Sprint 2 (2026-04-28): the `model=` parameter is deprecated.
-        # LLM resolution moved to kernel ctx-injection (see ctx._llm_configs)
-        # in Sprint 1.2. Removing the constructor argument entirely is
-        # scheduled for SDK 4.0.0 — until then we keep it for backward
-        # compat but emit a class-level WARN-once when it's explicitly
-        # passed. The flag is on the CLASS (not instance) so 11
-        # extensions don't each warn at boot.
         if model is not None:
             if not getattr(ChatExtension, "_model_deprecation_warned", False):
                 log.warning(
                     f"ChatExtension(tool_name={tool_name!r}, model=...): "
                     "the `model=` parameter is deprecated since SDK 3.3.0. "
-                    "LLM model resolution moved to kernel ctx-injection (see "
-                    "ctx._llm_configs). Will be removed in SDK 4.0.0. "
+                    "LLM model resolution moved to platform ctx-injection (see "
+                    "ctx._llm_configs). Will be removed in SDK 6.0.0. "
                     "Remove `model=` from extension app.py."
                 )
                 ChatExtension._model_deprecation_warned = True
             self.model = model
         else:
-            self.model = ""  # historical default no longer meaningful
+            self.model = ""
         self.max_rounds = max_rounds
         self._functions: dict[str, FunctionDef] = {}
-        _self = self
 
-        # SDK IDENTITY GUARD: warn developers about self-identification in prompts.
         if system_prompt and _IDENTITY_PATTERN.search(system_prompt):
             log.warning(
                 f"[SDK] ChatExtension '{tool_name}': system_prompt contains 'You are ...' — "
-                "this will be overridden by kernel OS identity. "
+                "this will be overridden by platform OS identity. "
                 "Use a neutral capability description instead. "
                 "Example: 'Notes module — manage user notes and folders.'"
             )
-        # v5.0.0 (federal: I-MANIFEST-NO-ORCHESTRATOR-TOOL): orchestrator-tool
-        # auto-registration REMOVED. ChatExtension is now purely a @chat.function
-        # bundle declaration — kernel chain_executor dispatches each function
-        # directly via typed dispatch. tool_name kwarg retained for back-compat
-        # but emits DeprecationWarning. Will be removed in 5.1.0.
+
+        # v5.0.0: orchestrator-tool auto-registration REMOVED. ChatExtension
+        # is now purely a @chat.function bundle declaration — the platform
+        # chain executor dispatches each function directly via typed dispatch.
+        # tool_name kwarg retained for back-compat but emits DeprecationWarning.
+        # Will be removed in 5.1.0.
         import warnings as _warnings
         _warnings.warn(
             f"ChatExtension(tool_name={tool_name!r}): kwarg deprecated in SDK 5.0.0 "
@@ -122,7 +109,7 @@ class ChatExtension:
             stacklevel=2,
         )
         ext._chat_extensions = getattr(ext, "_chat_extensions", {})
-        ext._chat_extensions[tool_name] = self  # registry walk still iterates this
+        ext._chat_extensions[tool_name] = self
 
     def function(self, name: str, description: str, params: dict | None = None,
                  action_type: str = "read", event: str = "",
@@ -131,51 +118,63 @@ class ChatExtension:
                  effects: list[str] | None = None,
                  id_projection: str | None = None,
                  background: bool = False,
-                 long_running: bool = False):
-        """Register a chat function (federal v4.0.0 contract).
+                 long_running: bool = False,
+                 data_model: type | None = None):
+        """Register a chat function.
 
         Args:
             name: Function name (used in tool_use calls).
             description: What this function does, ≥20 chars (V16). Shown to LLM.
             params: Parameter definitions dict. SDK auto-derives from a Pydantic
-                BaseModel param annotation when omitted (V17 federal rule —
-                no ``**kwargs`` or untyped handlers).
+                BaseModel param annotation when omitted (V17 — no ``**kwargs``
+                or untyped handlers).
             action_type: ``"read"``, ``"write"``, or ``"destructive"``. Drives
-                KAV verification and the 2-step confirmation gate.
+                kernel action verification and the 2-step confirmation gate.
             event: Event name for ActionResult publishing.
             event_schema: Optional Pydantic BaseModel class for typed event data.
-            chain_callable: Federal v4.0.0 — when ``True`` the kernel issues a
-                direct typed call ``app/func(args)`` instead of delegating to
-                the ChatExtension LLM router. Defaults to ``True`` for
-                ``action_type in ("write","destructive")`` so writes never get
-                lost in LLM paraphrase.
+            chain_callable: When ``True`` the platform issues a direct typed
+                call ``app/func(args)`` instead of delegating to the
+                ChatExtension LLM router. Defaults to ``True`` for ALL
+                action_types since v4.2.10.
             effects: Side-effect surface list — ``["create:note"]``,
-                ``["delete:folder"]``, etc. Used by chain narrator + audit ledger.
-            id_projection: Federal v4.1.2 — name of the params field that
-                carries the resolved target id when this tool runs as a
-                downstream chain step (e.g. ``"folder_id"`` for
-                ``delete_notes_from_folder`` whose params include
-                ``folder_id: str``). When omitted, the kernel falls back to
-                a verb-prefix heuristic (``delete_note`` -> ``note_id``)
-                that fails for compound tool names. REQUIRED whenever the
-                tool name does not directly imply the target field, e.g.
-                ``delete_notes_from_folder``, ``mark_emails_as_read``,
-                ``archive_drafts_in_project``.
+                ``["delete:folder"]``, etc. Used by chain narrator + audit
+                ledger.
+            id_projection: Name of the params field that carries the
+                resolved target id when this tool runs as a downstream
+                chain step (e.g. ``"folder_id"`` for
+                ``delete_notes_from_folder``).
+            data_model: **v5.0.1 — Federal Typed Return Contract.** Explicit
+                Pydantic ``BaseModel`` subclass declaring the shape of
+                ``ActionResult.data`` for this tool. Federal contract:
+                I-SDK-DECORATOR-DATA-MODEL-KWARG. When declared, it
+                populates ``FunctionDef._return_model`` directly, takes
+                precedence over return-annotation auto-detect, and triggers:
+
+                  1. Manifest ``return_schema`` emission.
+                  2. Platform catalog ingestion of ``return_model``.
+                  3. Classifier envelope rendering of ``return_fields``.
+                  4. ``$REF`` resolver path validation against the schema.
+                  5. Runtime ``data.model_validate`` on emit.
+
+                **MUST** be present for ``action_type="read"`` (V23 —
+                initially WARN, ERROR after soak via
+                ``IMPERAL_VALIDATOR_V23_SEVERITY``). Recommended for
+                write/destructive (V24, WARN-only).
+
+                Use the same field names as the corresponding input
+                ``CreateXParams`` for round-trip symmetry — this closes the
+                ``content_text`` (input) / ``content`` (output) drift class.
         """
         if chain_callable is None:
-            # V19 (federal v4.2.10, 2026-05-13): default True for ALL
-            # action_types — reads also typed-dispatch when the classifier
-            # picked them, closing the wrapper-LLM paraphrase risk on
-            # `list_*`, `search_*`, `get_*` style handlers. Authors who
-            # need the wrapper-LLM tool-use loop (catch-all conversational
-            # handlers like `case_chat`) must set `chain_callable=False`
-            # explicitly. Pre-v4.2.10 default kept `False` for reads;
-            # backward-compatible because action_type in ("write",
-            # "destructive") already returned True and continues to.
             chain_callable = True
 
         def decorator(func: Callable) -> Callable:
-            # Auto-detect Pydantic BaseModel params + return type
+            # Auto-detect Pydantic BaseModel params + return type.
+            # Resolution priority for _return_model:
+            #   1. Explicit `data_model` kwarg — wins
+            #   2. Direct `-> SomeBaseModel` return annotation
+            #   3. `-> ActionResult[T]` generic extraction
+            #   4. None of above → _return_model = None
             resolved_params = params
             _detected_model = None
             _detected_param = ""
@@ -187,43 +186,70 @@ class ChatExtension:
                 if ret_ann is not None:
                     try:
                         from pydantic import BaseModel as _BM
+                        # (2) Direct -> SomeBaseModel
                         if isinstance(ret_ann, type) and issubclass(ret_ann, _BM):
                             _detected_return_model = ret_ann
+                        else:
+                            # (3) -> ActionResult[T] generic — extract T via
+                            # typing.get_args. typing.get_origin returns the
+                            # generic class (ActionResult), get_args returns
+                            # the typevar binding (NoteRecord,).
+                            _origin = _typing.get_origin(ret_ann)
+                            _args = _typing.get_args(ret_ann)
+                            if _origin is not None and _args:
+                                _origin_name = getattr(_origin, "__name__", "")
+                                if _origin_name == "ActionResult":
+                                    _t_arg = _args[0]
+                                    if (
+                                        isinstance(_t_arg, type)
+                                        and issubclass(_t_arg, _BM)
+                                    ):
+                                        _detected_return_model = _t_arg
                     except (TypeError, ImportError):
                         pass
             except Exception:
                 pass
+            # (1) Explicit data_model kwarg WINS over auto-detect.
+            if data_model is not None:
+                try:
+                    from pydantic import BaseModel as _BM_chk
+                    if isinstance(data_model, type) and issubclass(data_model, _BM_chk):
+                        _detected_return_model = data_model
+                except (TypeError, ImportError):
+                    pass
             if resolved_params is None:
                 import inspect
+                import typing as _typing2
+                # Use typing.get_type_hints to resolve PEP 563 string
+                # annotations to real classes (no manual codepath needed).
+                try:
+                    _resolved_hints = _typing2.get_type_hints(func)
+                except Exception:
+                    _resolved_hints = {}
                 sig = inspect.signature(func)
                 for pname, param in sig.parameters.items():
                     if pname in ("ctx", "self"):
                         continue
-                    ann = param.annotation
-                    if ann != inspect.Parameter.empty:
-                        # PEP 563: from __future__ import annotations → strings
-                        if isinstance(ann, str):
-                            try:
-                                ann = eval(ann, func.__globals__)
-                            except Exception:
-                                continue
-                        try:
-                            from pydantic import BaseModel
-                            if isinstance(ann, type) and issubclass(ann, BaseModel):
-                                schema = ann.model_json_schema()
-                                resolved_params = {}
-                                for field_name, field_info in schema.get("properties", {}).items():
-                                    resolved_params[field_name] = {
-                                        "type": field_info.get("type", "string"),
-                                        "description": field_info.get("description", field_info.get("title", "")),
-                                    }
-                                    if field_name not in schema.get("required", []):
-                                        resolved_params[field_name]["default"] = field_info.get("default")
-                                _detected_model = ann
-                                _detected_param = pname
-                                break
-                        except (TypeError, ImportError):
-                            pass
+                    ann = _resolved_hints.get(pname, param.annotation)
+                    if ann == inspect.Parameter.empty:
+                        continue
+                    try:
+                        from pydantic import BaseModel
+                        if isinstance(ann, type) and issubclass(ann, BaseModel):
+                            schema = ann.model_json_schema()
+                            resolved_params = {}
+                            for field_name, field_info in schema.get("properties", {}).items():
+                                resolved_params[field_name] = {
+                                    "type": field_info.get("type", "string"),
+                                    "description": field_info.get("description", field_info.get("title", "")),
+                                }
+                                if field_name not in schema.get("required", []):
+                                    resolved_params[field_name]["default"] = field_info.get("default")
+                            _detected_model = ann
+                            _detected_param = pname
+                            break
+                    except (TypeError, ImportError):
+                        pass
             if resolved_params is None:
                 resolved_params = {}
 
@@ -250,13 +276,7 @@ class ChatExtension:
                           message_type: str = "text", intercepted: bool = False,
                           task_cancelled: bool = False, action_meta: dict = None,
                           narration_emission: dict | None = None) -> dict:
-        """Build return dict using ChatResult for typed construction.
-
-        narration_emission: when the LLM completed the turn via
-            EMIT_NARRATION_TOOL (P2 Task 27), this carries the parsed
-            NarrationEmission as a plain dict (.model_dump()). None for
-            free-form text responses or on parse failure.
-        """
+        """Build return dict using ChatResult for typed construction."""
         from imperal_sdk.types.chat_result import ChatResult, FunctionCall as FC
 
         fcs = []
@@ -293,11 +313,9 @@ class ChatExtension:
             at = self._functions[func_name].action_type
             if at != "read":
                 return at
-            # Backwards compat: if still "read" (default), check name for write words
             if any(w in func_name.lower() for w in _ACTION_WORDS):
                 return "write"
             return "read"
-        # Unknown function — try name-based detection
         if any(w in func_name.lower() for w in _ACTION_WORDS):
             return "write"
         return "read"
@@ -322,5 +340,3 @@ class ChatExtension:
 
     def _build_messages(self, history, message, context_window=20, keep_recent=6):
         return build_messages(history, message, context_window, keep_recent)
-
-

{imperal_sdk-5.0.0 → imperal_sdk-5.0.2}/src/imperal_sdk/extension.py

@@ -142,11 +142,14 @@ class Extension:
         # EXT-SECRETS-V1 (v4.2.2) — declared secrets emitted into manifest.secrets[]
         self._secrets: dict[str, "SecretSpec"] = {}
 
-        # EXT-SECRETS-V1 (v4.2.4) — auto-register synthetic 'secrets' panel
-        # unconditionally for every Extension. Empty state (no @ext.secret
-        # declared) renders developer guidance with code example. Federal
-        # contract enforced platform-side regardless of UI presence.
-        self._auto_register_secrets_panel()
+        # v5.0.1 UX fix: synthetic 'secrets' panel is now registered LAZILY
+        # — only when the extension calls @ext.secret(...) for the first
+        # time. Previously the panel was added unconditionally to every
+        # Extension and appeared as an empty placeholder in the right slot
+        # of every chat session even for extensions that declare zero
+        # secrets. Lazy registration happens in ``secret()`` below; the
+        # synthetic Secrets panel UI is identical when the extension
+        # actually has secrets to show.
 
     def _auto_register_secrets_panel(self) -> None:
         """Register the platform-provided 'secrets' panel.