induscode 0.1.0__py3-none-any.whl

induscode/conductor/signal_hub.py

@@ -0,0 +1,382 @@
+"""signal-hub — the conductor's product-event hub + framework-event translator.
+
+Two cooperating pieces sitting between the framework ``Agent`` loop and the
+conductor's consumers:
+
+- :class:`SignalHub` — a synchronous, insertion-ordered fan-out bus over the
+  :data:`SessionSignal` stream. Behavior modules emit into it; UI/print/RPC
+  consumers subscribe to it.
+- :func:`translate_agent_event` — the pure projection that turns a single
+  framework ``AgentEvent`` into the zero-or-more :data:`SessionSignal` values
+  that flow through the hub. :data:`TRANSLATOR_TABLE` is the underlying
+  dispatch table (exported for inspection/testing).
+
+Typical wiring: subscribe the framework loop, run each raw event through
+``translate_agent_event``, and ``emit`` the results on a :class:`SignalHub`.
+
+Hub design (deliberately the conductor's own, not the framework's loop
+emitter; ported from TS ``src/conductor/signal-hub/hub.ts``):
+
+- Handlers live in an insertion-ordered registry (a ``dict`` keyed by the
+  handler — Python's ordered-``dict`` stands in for the TS insertion-ordered
+  ``Set``), so registration order is the delivery order and duplicate handler
+  identities collapse to one slot.
+- :meth:`SignalHub.subscribe` returns an unsubscribe thunk; calling it (even
+  during a dispatch, even more than once) is safe and idempotent.
+- :meth:`SignalHub.emit` fans out over a *snapshot* of the handler registry,
+  so a handler that subscribes or unsubscribes mid-dispatch never corrupts
+  the in-progress iteration — the change takes effect on the next emit.
+- A throwing handler is isolated: its error is routed to the optional
+  ``on_handler_error`` sink and the remaining handlers still run. One bad
+  consumer never silences the others.
+
+Translator design (ported from TS ``src/conductor/signal-hub/translate.ts``):
+
+- The mapping is keyed on the framework event's ``type`` discriminant, so it
+  is expressed as a ``dict[str, Callable]`` — one entry per framework event
+  tag. TS enforced exhaustiveness with a mapped type at compile time; the
+  Python port enforces it with a key-coverage test asserting the table's
+  keys equal the tags of every ``AgentEvent`` union member (exhaustiveness
+  moved compiler → test).
+- Each rule is a pure, side-effect-free function over a single event.
+- ``MessageUpdateEvent.assistantMessageEvent`` is a **best-effort dict** in
+  the Python framework (a small mapping such as
+  ``{"type": "text_delta", "delta": ...}``), so the inner streaming dispatch
+  reads keys defensively — and every other payload probe accepts both
+  mapping- and attribute-shaped values, since the live agent passes frozen
+  dataclass messages while tests may pass plain dicts.
+
+Mapping rules (framework ``type`` → product signals):
+
+- ``agent_start`` / ``turn_start`` / ``message_start`` / ``agent_end``
+  → ``[]``  (loop bookkeeping; not product-visible)
+- ``message_end``           → one ``prompt`` for a *user* message (the turn
+  is now committed), one ``fault`` for an errored *assistant* message,
+  else ``[]``
+- ``tool_execution_start``  → one ``tool_start``  (id, name)
+- ``tool_execution_update`` → ``[]``  (partial tool progress not surfaced)
+- ``tool_execution_end``    → one ``tool_end``    (id, ok = not isError)
+- ``turn_end``              → one ``turn_end``    (usage)
+- ``message_update``        → delegated to the inner streaming dispatch on
+  ``assistantMessageEvent["type"]``:
+  ``text_delta`` → ``text``; ``thinking_delta`` → ``thinking``;
+  ``error`` → ``fault`` (model); everything else → ``[]``
+
+Faults: a streaming ``error`` sub-event becomes a typed ``model`` fault. The
+conductor layers its own ``aborted`` / ``tool`` / ``persistence`` /
+``overflow`` faults elsewhere; the translator only mints the one fault the
+framework stream actually carries.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from indusagi.agent import AgentEvent
+from indusagi.ai import Usage, create_zero_usage
+
+from .contract import (
+    FaultSignal,
+    PromptSignal,
+    SessionSignal,
+    SignalHandler,
+    TextSignal,
+    ThinkingSignal,
+    ToolEndSignal,
+    ToolStartSignal,
+    TurnEndSignal,
+    conductor_fault,
+)
+
+__all__ = [
+    "SignalHub",
+    "TRANSLATOR_TABLE",
+    "translate_agent_event",
+]
+
+
+# ---------------------------------------------------------------------------
+# SignalHub — the synchronous fan-out bus
+# ---------------------------------------------------------------------------
+
+
+class SignalHub:
+    """A synchronous fan-out bus for :data:`SessionSignal` values.
+
+    Construct one per session; subscribe consumers; emit signals. Not a
+    framework type and not wired to one — purely the conductor's own event
+    surface.
+
+    :param on_handler_error: invoked when a subscribed handler raises during
+        :meth:`emit` — lets the owner observe/log faults in consumer code
+        without aborting the fan-out. If omitted, handler errors are
+        swallowed so a misbehaving consumer cannot break signal delivery to
+        the others. This sink is itself guarded — if it raises, the raise is
+        ignored. (The TS ``SignalHubOptions`` bag collapses to this single
+        keyword argument.)
+    """
+
+    def __init__(
+        self,
+        *,
+        on_handler_error: Callable[[Exception, SessionSignal], None] | None = None,
+    ) -> None:
+        # Insertion-ordered live registry of subscribed handlers. A dict
+        # keyed by the handler (values unused) — the Python stand-in for the
+        # TS insertion-ordered Set: registration order is delivery order and
+        # duplicate identities collapse to one slot.
+        self._handlers: dict[SignalHandler, None] = {}
+        self._on_handler_error = on_handler_error
+
+    def subscribe(self, handler: SignalHandler) -> Callable[[], None]:
+        """Register a handler to receive every subsequently emitted signal.
+
+        Registering the same function reference twice is a no-op (the
+        registry collapses it). The returned thunk removes the handler; it is
+        idempotent and safe to call during a dispatch.
+
+        :param handler: the consumer callback
+        :returns: an unsubscribe function
+        """
+        self._handlers[handler] = None
+        active = True
+
+        def unsubscribe() -> None:
+            nonlocal active
+            if not active:
+                return
+            active = False
+            self._handlers.pop(handler, None)
+
+        return unsubscribe
+
+    def emit(self, signal: SessionSignal) -> None:
+        """Fan a signal out to every currently-subscribed handler, in
+        registration order.
+
+        Iterates a snapshot of the handler registry, so subscribe/unsubscribe
+        performed by a handler mid-dispatch affects only later emits. A
+        throwing handler is isolated via the ``on_handler_error`` sink; the
+        remaining handlers still run.
+
+        :param signal: the signal to deliver
+        """
+        # Snapshot so concurrent (re-entrant) (un)subscribes don't disturb
+        # this pass.
+        for handler in list(self._handlers):
+            try:
+                handler(signal)
+            except Exception as error:  # noqa: BLE001 — isolation is the point
+                self._report(error, signal)
+
+    @property
+    def size(self) -> int:
+        """Number of currently-subscribed handlers."""
+        return len(self._handlers)
+
+    def clear(self) -> None:
+        """Remove every handler. Subsequent :meth:`emit` calls deliver to no
+        one."""
+        self._handlers.clear()
+
+    def _report(self, error: Exception, signal: SessionSignal) -> None:
+        """Route a handler error to the sink, guarding the sink itself."""
+        if self._on_handler_error is None:
+            return
+        try:
+            self._on_handler_error(error, signal)
+        except Exception:  # noqa: BLE001
+            # A throwing error-sink must not break the fan-out.
+            pass
+
+
+# ---------------------------------------------------------------------------
+# translate_agent_event — the framework-event → SessionSignal projector
+# ---------------------------------------------------------------------------
+
+
+def _field(obj: Any, name: str, default: Any = None) -> Any:
+    """Defensive payload probe: read ``name`` off a mapping key or an
+    attribute, whichever the value carries.
+
+    The framework's events are frozen dataclasses with camelCase fields, but
+    their ``message`` / ``assistantMessageEvent`` payloads are best-effort
+    (dict-shaped in the shim, dataclass-shaped from the live loop) — and the
+    TS translator probed structurally for the same reason. Never raises on an
+    unexpected payload.
+    """
+    if isinstance(obj, Mapping):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+def _usage_of(message: Any) -> Usage:
+    """Pull the cumulative :class:`Usage` off a settled turn's message.
+
+    ``turn_end.message`` is an ``AgentMessage`` (a union); only an assistant
+    message carries ``usage``. We structurally probe for it rather than
+    importing a guard, and fall back to a zero-usage value so the
+    ``turn_end`` signal always carries a well-formed ``Usage``.
+    """
+    usage = _field(message, "usage")
+    if usage is not None:
+        return usage
+    return create_zero_usage()
+
+
+def _prompt_text_of(content: Any) -> str:
+    """Best-effort plain text of a user message's content.
+
+    A user ``AgentMessage`` carries its content either as a bare string or as
+    a sequence of content blocks; we want the readable text either way.
+    Blocks without a string ``text`` field (e.g. images) contribute nothing.
+    Structurally probed rather than imported so the translator stays
+    decoupled from the message shape, and never raises on an unexpected
+    payload.
+    """
+    if isinstance(content, str):
+        return content
+    if isinstance(content, Sequence):
+        parts: list[str] = []
+        for block in content:
+            text = _field(block, "text")
+            parts.append(text if isinstance(text, str) else "")
+        return "".join(parts)
+    return ""
+
+
+def _fault_message_of(error: Any) -> str:
+    """Best-effort human-readable summary for a streaming-error payload."""
+    message = _field(error, "errorMessage")
+    if isinstance(message, str):
+        return message
+    return "model stream error"
+
+
+def _translate_stream_event(sub: Any) -> list[SessionSignal]:
+    """Inner dispatch for ``message_update``: map the streaming
+    ``AssistantMessageEvent`` sub-event to a product signal.
+
+    Keyed on the sub-event's own ``type`` discriminant — read defensively,
+    because the Python framework forwards it as a best-effort **dict** (e.g.
+    ``{"type": "text_delta", "delta": ...}``). Only the three
+    product-visible sub-events (``text_delta``, ``thinking_delta``,
+    ``error``) produce a signal; the lifecycle/partial sub-events
+    (``*_start``, ``*_end``, ``toolcall_*``, ``done``) are loop-internal and
+    map to ``[]``.
+    """
+    sub_type = _field(sub, "type")
+    if sub_type == "text_delta":
+        return [TextSignal(delta=_field(sub, "delta"))]
+    if sub_type == "thinking_delta":
+        return [ThinkingSignal(delta=_field(sub, "delta"))]
+    if sub_type == "error":
+        error = _field(sub, "error")
+        return [
+            FaultSignal(fault=conductor_fault("model", _fault_message_of(error), error))
+        ]
+    return []
+
+
+def _none(_event: Any) -> list[SessionSignal]:
+    """No product signal for this framework event."""
+    return []
+
+
+def _message_end(event: Any) -> list[SessionSignal]:
+    # Two settled-message cases are product-visible:
+    #   1. A user message_end means the just-submitted prompt has entered the
+    #      conversation. Surface it as a `prompt` signal so a UI can echo the
+    #      user turn the instant it is accepted — before the model's first
+    #      token — and not appear to "hang" until the reply streams. (The
+    #      agent appends the user message to its state on this same event, so
+    #      by the time consumers react the message is already readable from
+    #      `messages()`.)
+    #   2. An assistant message_end carries the failure when a call errored
+    #      (e.g. a 404 for a retired model): surface it as a fault so the
+    #      turn is not silently empty. The successful text itself streams via
+    #      `message_update`/`text_delta`, not here.
+    message = _field(event, "message")
+    role = _field(message, "role")
+    if role == "user":
+        return [PromptSignal(text=_prompt_text_of(_field(message, "content")))]
+    error_message = _field(message, "errorMessage")
+    if role == "assistant" and (
+        _field(message, "stopReason") == "error" or isinstance(error_message, str)
+    ):
+        return [
+            FaultSignal(
+                fault=conductor_fault(
+                    "model",
+                    error_message
+                    if isinstance(error_message, str)
+                    else "the model call failed",
+                )
+            )
+        ]
+    return []
+
+
+def _turn_end(event: Any) -> list[SessionSignal]:
+    # Settled turn: surface cumulative usage.
+    return [TurnEndSignal(usage=_usage_of(_field(event, "message")))]
+
+
+def _message_update(event: Any) -> list[SessionSignal]:
+    # Streaming deltas + stream error: delegate to the inner dispatch.
+    return _translate_stream_event(_field(event, "assistantMessageEvent"))
+
+
+def _tool_execution_start(event: Any) -> list[SessionSignal]:
+    return [ToolStartSignal(id=_field(event, "toolCallId"), name=_field(event, "toolName"))]
+
+
+def _tool_execution_end(event: Any) -> list[SessionSignal]:
+    return [ToolEndSignal(id=_field(event, "toolCallId"), ok=not _field(event, "isError"))]
+
+
+#: The frozen mapping from each framework event tag to its product-signal
+#: rule — exactly one rule per ``AgentEvent`` union member.
+#:
+#: TS declared this as a full mapped type so the compiler rejected the module
+#: until every framework event variant had a rule; the Python port asserts
+#: the same exhaustiveness with a key-coverage test
+#: (``tests/conductor/test_contract_hub_skill.py``) comparing these keys to
+#: the ``type`` tags of every ``AgentEvent`` union member.
+#:
+#: Exported for testing/inspection; production code calls
+#: :func:`translate_agent_event`, which is the table applied.
+TRANSLATOR_TABLE: dict[str, Callable[[Any], list[SessionSignal]]] = {
+    # --- Lifecycle / turn / message bookkeeping: not product-visible -------
+    "agent_start": _none,
+    "agent_end": _none,
+    "turn_start": _none,
+    "message_start": _none,
+    "message_end": _message_end,
+    # --- Settled turn: surface cumulative usage -----------------------------
+    "turn_end": _turn_end,
+    # --- Streaming deltas + stream error: delegate to the inner dispatch ----
+    "message_update": _message_update,
+    # --- Tool lifecycle ------------------------------------------------------
+    "tool_execution_start": _tool_execution_start,
+    "tool_execution_update": _none,
+    "tool_execution_end": _tool_execution_end,
+}
+
+
+def translate_agent_event(event: AgentEvent) -> list[SessionSignal]:
+    """Translate a single framework ``AgentEvent`` into the product-level
+    :data:`SessionSignal` values it produces (zero, one, or — for future
+    fan-out — many).
+
+    Pure and total over the known event union: every framework event variant
+    has a rule (asserted by the key-coverage test), so this never raises on a
+    known event and returns ``[]`` for events that carry no product meaning.
+
+    :param event: a framework agent loop event
+    :returns: the ordered product signals derived from it
+    :raises KeyError: on an event tag outside the framework union (the TS
+        table was compiler-total; the Python port fails loud)
+    """
+    return TRANSLATOR_TABLE[_field(event, "type")](event)

induscode/conductor/skill_parse.py

@@ -0,0 +1,294 @@
+"""Skill-invocation block parser — an attribute-scanning hand parser.
+
+The coding agent lets a turn carry a *skill invocation*: an XML-ish opener
+tag that names a capability card to run, optionally locates its on-disk
+file, and wraps a trailing user message (the body) the skill should act on.
+The shape is the framework Agent-Skills convention::
+
+    <skill name="commit-helper" location="/abs/path/SKILL.md">
+    please tidy the staged diff and write a message
+    </skill>
+
+This module re-derives that parse from the *format spec*, deliberately NOT
+as one monolithic capture regex. It is a small hand-written scanner: it
+walks the input, finds the opener, scans ``key=value`` attributes one at a
+time (handling single- or double-quoted and bare values, with
+``&amp;``/``&lt;``/``&gt;``/``&quot;``/``&#39;`` entity decoding), then
+captures the body up to the matching close tag. Reading attributes
+incrementally — rather than matching the whole block in a single pattern —
+is what makes this an independent implementation and lets the parser keep
+*every* attribute the author wrote, not just a fixed ``name``/``location``
+pair.
+
+Block grammar (informal)::
+
+    block   := WS? '<' TAG WS attrs? WS? '>' body '</' TAG WS? '>'
+    TAG     := 'skill'            (case-insensitive)
+    attrs   := (attr WS?)*
+    attr    := key ('=' value)?
+    key     := [A-Za-z_][A-Za-z0-9_:.-]*
+    value   := '"' ... '"' | '\\'' ... '\\'' | bare   (bare stops at WS / '>')
+    body    := any text, captured verbatim up to the close tag
+
+A valid block must (a) be the leading content of the text (only leading
+whitespace may precede the opener), (b) name the ``skill`` tag, (c) carry a
+non-empty ``name`` attribute, and (d) be closed by ``</skill>``. Anything
+else yields ``None``, signalling "this turn is ordinary text, not a skill
+call".
+
+Port note (TS ``src/conductor/skill-parse/parse.ts``): the index-walking
+scanner ports verbatim, with one mechanical difference — TS ``text[i]`` past
+the end is ``undefined`` while Python raises, so every cursor read carries
+an explicit bounds guard where TS leaned on ``undefined``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+__all__ = [
+    "SkillInvocation",
+    "parse_skill_invocation",
+]
+
+
+# The recognised opener/closer tag name (compared case-insensitively).
+_SKILL_TAG = "skill"
+
+# The attribute whose value is promoted to the result's ``name`` field.
+_NAME_ATTR = "name"
+
+
+@dataclass(frozen=True, slots=True)
+class SkillInvocation:
+    """The structured result of a successful parse.
+
+    - ``name`` — the value of the required ``name`` attribute (the skill to
+      run).
+    - ``args`` — every attribute the opener carried, keyed by (lower-cased)
+      name, including ``name`` itself and any ``location``/custom keys. A
+      bare attribute with no ``=value`` maps to the empty string.
+    - ``body`` — the verbatim text between the opener and the ``</skill>``
+      close, with a single leading and trailing newline trimmed (the common
+      case where the opener/closer sit on their own lines) but inner
+      whitespace preserved.
+    """
+
+    name: str
+    args: Mapping[str, str]
+    body: str
+
+
+def _is_space(ch: str) -> bool:
+    """True for ASCII whitespace the scanner skips between tokens."""
+    return ch in (" ", "\t", "\n", "\r", "\f", "\v")
+
+
+def _is_key_start(ch: str) -> bool:
+    """True for the first character of an attribute key."""
+    return ("a" <= ch <= "z") or ("A" <= ch <= "Z") or ch == "_"
+
+
+def _is_key_char(ch: str) -> bool:
+    """True for a continuing character of an attribute key."""
+    return _is_key_start(ch) or ("0" <= ch <= "9") or ch in ("-", ":", ".")
+
+
+def _skip_space(text: str, i: int) -> int:
+    """Advance past any run of whitespace from ``i``; returns the new index."""
+    j = i
+    while j < len(text) and _is_space(text[j]):
+        j += 1
+    return j
+
+
+_ENTITY_RE = re.compile(r"&(#39|#x27|#34|#x22|amp|lt|gt|quot|apos);", re.IGNORECASE)
+
+
+def _decode_entities(raw: str) -> str:
+    """Decode the small set of XML/HTML entities an author might write inside
+    an attribute value or the body. Only the canonical five (plus the two
+    common numeric apostrophe/quote forms) are recognised; everything else is
+    left as written so arbitrary text passes through untouched."""
+    if "&" not in raw:
+        return raw
+
+    def repl(match: re.Match[str]) -> str:
+        code = match.group(1).lower()
+        if code == "amp":
+            return "&"
+        if code == "lt":
+            return "<"
+        if code == "gt":
+            return ">"
+        if code in ("quot", "#34", "#x22"):
+            return '"'
+        if code in ("apos", "#39", "#x27"):
+            return "'"
+        return match.group(0)
+
+    return _ENTITY_RE.sub(repl, raw)
+
+
+@dataclass(frozen=True, slots=True)
+class _AttrScan:
+    """The cursor result of scanning a single attribute."""
+
+    key: str
+    value: str
+    next: int
+
+
+def _scan_attribute(text: str, i: int) -> _AttrScan | None:
+    """Scan one ``key`` / ``key="value"`` / ``key='value'`` / ``key=bare``
+    attribute starting at ``i`` (which must sit on a key-start character).
+    Returns the decoded key/value and the index just past the attribute, or
+    ``None`` if the key is malformed."""
+    j = i
+    key_start = j
+    if not _is_key_start(text[j]):
+        return None
+    j += 1
+    while j < len(text) and _is_key_char(text[j]):
+        j += 1
+    key = text[key_start:j].lower()
+
+    # Look for an `=` (whitespace may sit on either side of it).
+    after_key = _skip_space(text, j)
+    if after_key >= len(text) or text[after_key] != "=":
+        # Bare attribute: present, no value.
+        return _AttrScan(key=key, value="", next=j)
+
+    v = _skip_space(text, after_key + 1)
+    quote = text[v] if v < len(text) else None
+    if quote in ('"', "'"):
+        val_start = v + 1
+        k = val_start
+        while k < len(text) and text[k] != quote:
+            k += 1
+        if k >= len(text):
+            # Unterminated quote — treat the remainder as the value (best effort).
+            return _AttrScan(key=key, value=_decode_entities(text[val_start:]), next=len(text))
+        return _AttrScan(key=key, value=_decode_entities(text[val_start:k]), next=k + 1)
+
+    # Bare value: read until whitespace or the tag terminator.
+    val_start = v
+    while v < len(text) and not _is_space(text[v]) and text[v] not in (">", "/"):
+        v += 1
+    return _AttrScan(key=key, value=_decode_entities(text[val_start:v]), next=v)
+
+
+def _trim_body_edges(body: str) -> str:
+    """Strip one leading and one trailing newline (with optional CR) from the
+    body."""
+    s = body
+    if s.startswith("\r\n"):
+        s = s[2:]
+    elif s.startswith("\n") or s.startswith("\r"):
+        s = s[1:]
+    if s.endswith("\r\n"):
+        s = s[:-2]
+    elif s.endswith("\n") or s.endswith("\r"):
+        s = s[:-1]
+    return s
+
+
+def parse_skill_invocation(text: str) -> SkillInvocation | None:
+    """Parse a skill-invocation block out of ``text``.
+
+    Walks the string by hand: skips leading whitespace, confirms a
+    ``<skill …>`` opener, scans each attribute into an ``args`` record,
+    captures the body up to the matching ``</skill>``, and decodes entities.
+    Returns the structured invocation, or ``None`` when the text is not a
+    well-formed leading skill block (ordinary turns simply parse to
+    ``None``).
+
+    :param text: the raw turn text that may begin with a skill block
+    :returns: the parsed :class:`SkillInvocation`, or ``None`` if not a
+        skill block
+    """
+    i = _skip_space(text, 0)
+
+    # 1) Opener: '<' then the tag name (case-insensitive), bounded by a delimiter.
+    if i >= len(text) or text[i] != "<":
+        return None
+    i += 1
+    tag_start = i
+    while i < len(text) and _is_key_char(text[i]):
+        i += 1
+    tag = text[tag_start:i].lower()
+    if tag != _SKILL_TAG:
+        return None
+    # The tag must be followed by whitespace or the tag terminator, not more name.
+    after_tag = text[i] if i < len(text) else None
+    if after_tag is not None and not _is_space(after_tag) and after_tag not in (">", "/"):
+        return None
+
+    # 2) Attributes: scan `key[=value]` pairs until the opener's '>'.
+    args: dict[str, str] = {}
+    while True:
+        i = _skip_space(text, i)
+        if i >= len(text):
+            return None  # opener never closed
+        ch = text[i]
+        if ch == ">":
+            i += 1
+            break
+        if ch == "/":
+            # A self-closing `<skill .../>` carries no body; reject (a skill
+            # call needs one).
+            return None
+        if not _is_key_start(ch):
+            return None  # junk where an attribute or '>' was expected
+        scan = _scan_attribute(text, i)
+        if scan is None:
+            return None
+        if scan.key not in args:
+            args[scan.key] = scan.value  # first writer wins per key
+        i = scan.next
+
+    # 3) A skill call is identified by a non-empty `name` attribute.
+    name = args.get(_NAME_ATTR)
+    if name is None or len(name) == 0:
+        return None
+
+    # 4) Body: capture verbatim up to the matching close tag `</skill>`.
+    body_start = i
+    close = _find_close_tag(text, i)
+    if close is None:
+        return None
+    body = _trim_body_edges(_decode_entities(text[body_start:close]))
+
+    return SkillInvocation(name=name, args=MappingProxyType(args), body=body)
+
+
+def _find_close_tag(text: str, i: int) -> int | None:
+    """From ``i``, find the index of the ``<`` that begins the matching
+    ``</skill>`` close tag (case-insensitive, tolerant of whitespace before
+    the ``>``). Returns the index of that ``<``, or ``None`` if no close tag
+    is found."""
+    j = i
+    while j < len(text):
+        lt = text.find("<", j)
+        if lt == -1:
+            return None
+        k = lt + 1
+        if k >= len(text) or text[k] != "/":
+            j = lt + 1
+            continue
+        k = _skip_space(text, k + 1)
+        name_start = k
+        while k < len(text) and _is_key_char(text[k]):
+            k += 1
+        close_tag = text[name_start:k].lower()
+        if close_tag != _SKILL_TAG:
+            j = lt + 1
+            continue
+        k = _skip_space(text, k)
+        if k < len(text) and text[k] == ">":
+            return lt
+        j = lt + 1
+    return None