induscode 0.1.0__py3-none-any.whl

induscode/briefing/contract.py

@@ -0,0 +1,528 @@
+"""Briefing contract — the FROZEN type surface of the prompt layer.
+
+This module is the single typed seam between the coding-agent's runtime state
+and the LLM-facing **briefing** (the system prompt). It declares *only* shapes
+plus a handful of tiny inert helpers — no filesystem walks, no string
+assembly — so every later module (the section pipeline, the macro scanner, and
+the capability-card loader) is written against the names declared here. The
+file is intentionally small, append-mostly, and stable.
+
+Design stance (ported from TS ``src/briefing/contract.ts``):
+
+- The briefing is **declarative, not a string template**. A :data:`Briefing`
+  is an ordered list of :class:`BriefingSection` descriptors, each a small
+  record that decides whether it applies to a :class:`BriefingContext` and
+  renders its own fragment. :func:`~induscode.briefing.compose.compose_briefing`
+  folds the enabled sections into the final prompt; there is no mega-literal
+  with ``{{TOKEN}}`` placeholders.
+- Macros are a **single-pass ``$arg`` model**. A :class:`Macro` carries a body
+  and a source label; expansion is one left-to-right scan over the body that
+  resolves ``$1`` / ``$@`` / ``$ARGUMENTS`` / ``${@:N:L}`` against a
+  :class:`MacroScope`. The contract names the token kinds and the scope; it
+  does not run regexes.
+- A :class:`SkillCard` is a CapabilityCard parsed from a ``SKILL.md`` document.
+  The Agent-Skills *format* (frontmatter keys, name/description limits) is a
+  public spec and is kept; the validation prose and field policy are the
+  briefing's own.
+
+Port note — transcript-export types relocated
+---------------------------------------------
+The TS ``briefing/contract.ts`` additionally hosted the shared types of the
+HTML transcript exporter: the SGR machine (``SgrState`` / ``SgrToken`` /
+``SgrMutation`` / ``SGR_INITIAL_STATE``), the export palette (``ExportTheme``
+/ ``FALLBACK_EXPORT_THEME`` / ``Rgb`` / ``LuminanceLut`` / ``ThemeMode`` /
+``ThemeBridge``), and the publish surface (``TranscriptPart`` /
+``WidgetRender`` / ``PublishOptions`` / ``SHELL_SLOTS`` / ``ShellSlot``).
+In the Python build those types are owned by
+``induscode.transcript_export.contract`` (ported separately) — this module
+holds only the briefing-owned vocabulary: sections, macros, skills,
+:class:`ContextDoc`, and :class:`BriefingFault` (which transcript-export
+imports from here, fault kinds ``publish`` / ``theme`` included, so the closed
+fault set stays in one place).
+
+Framework anchors (all from the ``indusagi`` package — the sibling rebuilt
+framework this app targets):
+
+- :class:`AgentState`, :class:`AgentTool` ← ``indusagi.agent``
+- :class:`TextContent`, :class:`ImageContent` ← ``indusagi.ai``
+
+The briefing never re-declares these; it composes them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from typing import ClassVar, Final, Literal, TypeAlias
+
+from indusagi.agent import AgentState, AgentTool
+from indusagi.ai import ImageContent, TextContent
+
+__all__ = [
+    "AgentState",
+    "AgentTool",
+    "AllToken",
+    "Briefing",
+    "BriefingContext",
+    "BriefingFault",
+    "BriefingFaultKind",
+    "BriefingInputs",
+    "BriefingSection",
+    "ContextDoc",
+    "ImageContent",
+    "LiteralToken",
+    "Macro",
+    "MacroOrigin",
+    "MacroScope",
+    "MacroToken",
+    "MacroTokenKind",
+    "PositionalToken",
+    "SKILL_DESCRIPTION_LIMIT",
+    "SKILL_NAME_LIMIT",
+    "SkillCard",
+    "SkillDiagnostic",
+    "SkillFrontmatter",
+    "SkillLoad",
+    "SkillOutcomeKind",
+    "SliceToken",
+    "SubagentBrief",
+    "TextContent",
+    "briefing_fault",
+]
+
+
+# ---------------------------------------------------------------------------
+# Briefing sections (declarative system-prompt pipeline)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SubagentBrief:
+    """A named delegate role advertised in the subagent section of the briefing.
+
+    The minimum a section needs to list a delegate the primary agent may hand
+    work to: a stable invocation ``name``, a one-line ``purpose``, and an
+    optional ``when`` hint describing the situations the role is suited to.
+    """
+
+    # Stable name the primary agent uses to delegate to this role.
+    name: str
+    # One-line description of what the role is for.
+    purpose: str
+    # Optional hint describing when delegating to this role is appropriate.
+    when: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ContextDoc:
+    """A project-context document inlined into the briefing.
+
+    Project files (AGENTS-style guidance) are surfaced under their own section
+    so the model can read repository conventions. ``path`` labels the source;
+    ``body`` is the verbatim text to inline.
+    """
+
+    # Source path of the document, used as its heading label.
+    path: str
+    # Verbatim document text to inline into the briefing.
+    body: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BriefingContext:
+    """The working context a :class:`BriefingSection` reads when it decides
+    whether to apply and what to render.
+
+    This is the data-driven replacement for the old string-template's
+    placeholder bag. Every field is optional so a section that does not need a
+    given input simply ignores it, and a caller can compose a partial briefing
+    (e.g. one with no skills, or no project docs) without populating the whole
+    shape. A section is pure with respect to this context: it reads, it never
+    mutates.
+
+    - ``workspace`` — absolute working directory the session is scoped to; the
+      footer section surfaces it and skills resolve relative paths against it.
+    - ``tools`` — the capabilities advertised this turn; the tools/guidelines
+      sections gate themselves on which ids are present.
+    - ``cwd`` — alias kept distinct from ``workspace`` for sections that want
+      the *display* path (may be relativized) versus the absolute root.
+    - ``skills`` — the :class:`SkillCard` records eligible for model
+      invocation; the skills section renders these into its block.
+    - ``subagents`` — the named delegate roles to advertise in the delegate
+      block.
+    - ``context_docs`` — project context documents (AGENTS-style files) to
+      inline.
+    - ``now`` — the timestamp the footer stamps; injectable for determinism.
+    - ``extras`` — an open bag for app-novel sections to read bespoke inputs
+      without widening this contract on every addition.
+    """
+
+    # Absolute working directory the session's briefing is scoped to.
+    workspace: str | None = None
+    # The capabilities advertised this turn, by their wire-facing descriptors.
+    tools: Sequence[AgentTool] | None = None
+    # Display path for the working directory (may be relativized).
+    cwd: str | None = None
+    # Capability cards eligible for model invocation, for the skills block.
+    skills: Sequence[SkillCard] | None = None
+    # Named delegate roles to advertise in the subagent/delegate section.
+    subagents: Sequence[SubagentBrief] | None = None
+    # Project context documents to inline under a project-context section.
+    context_docs: Sequence[ContextDoc] | None = None
+    # Timestamp the footer stamps; injectable so renders are deterministic.
+    now: datetime | None = None
+    # Open bag for app-novel sections to read bespoke inputs.
+    extras: Mapping[str, object] | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BriefingSection:
+    """One declarative section of the briefing.
+
+    The unit of the data-driven pipeline that replaces the old string
+    template: an ordered array of these is composed by
+    :func:`~induscode.briefing.compose.compose_briefing`, which renders each
+    applicable section and joins the fragments. A section owns its own gating
+    — via the optional :attr:`applies` predicate — and its own rendering, so
+    adding a section is adding one descriptor to the array, not editing a
+    central literal.
+
+    - ``id`` — stable identifier for ordering, dedup, and selective inclusion.
+    - ``title`` — optional human-facing heading the section may emit.
+    - ``applies`` — optional predicate deciding whether this section
+      contributes to a given context; when ``None`` the section is treated as
+      always applicable.
+    - ``render`` — produce the section's fragment for a context. Pure: reads
+      the context, returns a string, performs no I/O and mutates nothing.
+      Returning an empty string is allowed and is dropped from the composed
+      output.
+    """
+
+    # Stable identifier for ordering, dedup, and selective inclusion.
+    id: str
+    # Optional human-facing heading the section may emit.
+    title: str | None = None
+    # Optional predicate; when None the section always renders.
+    applies: Callable[[BriefingContext], bool] | None = None
+    # Render this section's fragment for a context (pure).
+    render: Callable[[BriefingContext], str]
+
+
+#: An ordered briefing recipe: the sections, in render order.
+#:
+#: ``compose_briefing`` walks this list, skips sections whose
+#: :attr:`BriefingSection.applies` returns ``False``, renders the rest, and
+#: joins the non-empty fragments. The recipe is data; swapping the section set
+#: (or its order) reconfigures the whole prompt without touching the composer.
+Briefing: TypeAlias = Sequence[BriefingSection]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BriefingInputs:
+    """Inputs handed to ``compose_briefing`` to assemble a full briefing string.
+
+    Pairs the :data:`Briefing` recipe with the :class:`BriefingContext` to
+    render it against, plus two override hooks that mirror the legacy
+    custom-prompt path: ``prelude`` text prepended ahead of the sections, and
+    ``append`` text added after them. Both are optional; the common case
+    passes only ``sections`` and ``context``.
+    """
+
+    # The ordered section recipe to render.
+    sections: Briefing
+    # The context the sections render against.
+    context: BriefingContext
+    # Optional text prepended ahead of the rendered sections.
+    prelude: str | None = None
+    # Optional text appended after the rendered sections.
+    append: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Macros (single-pass $arg model)
+# ---------------------------------------------------------------------------
+
+#: Where a :class:`Macro` was discovered, for labelling and precedence.
+#:
+#: - ``user`` — the per-user macro directory.
+#: - ``project`` — the project-local macro directory.
+#: - ``path`` — an explicitly supplied path outside the standard roots.
+#: - ``builtin`` — a macro shipped with the app.
+MacroOrigin: TypeAlias = Literal["user", "project", "path", "builtin"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Macro:
+    """A user-defined slash macro: a named prompt body with ``$arg`` placeholders.
+
+    Discovered from ``*.md`` files (frontmatter + body) under the
+    user/project/path roots. Invoking ``/<name> args…`` resolves the body
+    against a :class:`MacroScope` built from the args, substituting the
+    ``$arg`` tokens in one pass. The field names are the briefing's own; the
+    placeholder *syntax* is the shared cross-tool convention and is preserved.
+
+    - ``name`` — the invocation name (without the leading slash).
+    - ``description`` — one-line summary for command listings; derived from
+      frontmatter or the body's opening, with an ``origin``-derived label.
+    - ``body`` — the prompt text containing the ``$arg`` placeholders.
+    - ``origin`` — where the macro was found, for labelling and precedence.
+    - ``source`` — absolute path of the file the macro was loaded from.
+    """
+
+    # Invocation name, without the leading slash.
+    name: str
+    # One-line description for command listings.
+    description: str
+    # Prompt body containing `$arg` placeholders.
+    body: str
+    # Where the macro was discovered.
+    origin: MacroOrigin
+    # Absolute path of the file the macro was loaded from.
+    source: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MacroScope:
+    """The argument environment a :class:`Macro` body is resolved against.
+
+    Built from a parsed invocation: ``args`` is the positional vector (1-based
+    in the ``$N`` syntax, 0-based in this tuple), ``all`` is the original
+    joined argument string the ``$@`` / ``$ARGUMENTS`` tokens expand to, and
+    ``raw`` is the untouched text after the command name (kept for diagnostics
+    and for tokens that want the pre-split form). A token references this
+    scope; the scanner reads it.
+    """
+
+    # Positional arguments, in order; `$1` maps to index 0.
+    args: tuple[str, ...]
+    # The joined argument string `$@` / `$ARGUMENTS` expand to.
+    all: str
+    # The verbatim text following the command name, before splitting.
+    raw: str
+
+
+#: The kinds of unit the single-pass ``$arg`` scanner emits.
+#:
+#: - ``literal`` — a run of ordinary text copied through unchanged.
+#: - ``positional`` — a ``$N`` reference to one positional argument.
+#: - ``all`` — a ``$@`` or ``$ARGUMENTS`` reference to the joined arguments.
+#: - ``slice`` — a ``${@:N}`` / ``${@:N:L}`` reference to an argument
+#:   sub-range.
+MacroTokenKind: TypeAlias = Literal["literal", "positional", "all", "slice"]
+
+
+@dataclass(frozen=True, slots=True)
+class LiteralToken:
+    """A run of ordinary text copied through unchanged."""
+
+    kind: ClassVar[Literal["literal"]] = "literal"
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class PositionalToken:
+    """A ``$N`` reference carrying the 1-based ``index`` of its argument."""
+
+    kind: ClassVar[Literal["positional"]] = "positional"
+    index: int
+
+
+@dataclass(frozen=True, slots=True)
+class AllToken:
+    """A ``$@`` / ``$ARGUMENTS`` reference; carries nothing beyond its kind."""
+
+    kind: ClassVar[Literal["all"]] = "all"
+
+
+@dataclass(frozen=True, slots=True)
+class SliceToken:
+    """A ``${@:N}`` / ``${@:N:L}`` reference carrying ``start`` and an
+    optional ``length``."""
+
+    kind: ClassVar[Literal["slice"]] = "slice"
+    start: int
+    length: int | None = None
+
+
+#: One unit produced by the single-pass macro scanner.
+#:
+#: The body is scanned left-to-right into a flat token stream; resolving the
+#: stream against a :class:`MacroScope` and concatenating yields the expanded
+#: text. This replaces the legacy multi-pass regex substitution with one scan
+#: emitting these discriminated tokens.
+MacroToken: TypeAlias = LiteralToken | PositionalToken | AllToken | SliceToken
+
+
+# ---------------------------------------------------------------------------
+# Skill cards (CapabilityCard loaded from a SKILL.md)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SkillFrontmatter:
+    """The parsed frontmatter of a ``SKILL.md`` document.
+
+    The Agent-Skills format is a public spec, so these keys are kept; the
+    policy over them (which are required, which are allowed) is the briefing's
+    own. Only ``name`` and ``description`` carry semantics for the prompt; the
+    rest are metadata the loader preserves but does not interpret.
+
+    - ``name`` — the skill's invocation name; must match its directory and use
+      lowercase hyphenated segments.
+    - ``description`` — required, single-line summary the model reads to
+      decide when the skill applies.
+    - ``license`` — optional SPDX-style license tag.
+    - ``compatibility`` — optional free-form compatibility note.
+    - ``metadata`` — optional open key/value bag.
+    - ``allowed_tools`` — optional restriction on which tools the skill may
+      use while active (the format's kebab-case ``allowed-tools`` key).
+    - ``disable_model_invocation`` — when true the skill is hidden from the
+      briefing and exposed only as an explicit ``/skill:<name>`` command (the
+      format's ``disable-model-invocation`` key).
+    """
+
+    # Invocation name; must match the parent directory, lowercase-hyphenated.
+    name: str | None = None
+    # Required single-line summary the model reads to gate the skill.
+    description: str | None = None
+    # Optional SPDX-style license tag.
+    license: str | None = None
+    # Optional free-form compatibility note.
+    compatibility: str | None = None
+    # Optional open metadata bag.
+    metadata: Mapping[str, object] | None = None
+    # Optional restriction on tools the skill may use while active.
+    allowed_tools: tuple[str, ...] | None = None
+    # Hide from the briefing; expose only as an explicit command.
+    disable_model_invocation: bool | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SkillCard:
+    """A capability card loaded from a ``SKILL.md`` document.
+
+    The resolved, validated form of one skill: its ``name``, the
+    ``description`` the model reads, the markdown ``body`` (instructions
+    loaded on demand), and the on-disk ``location`` of the file. ``origin``
+    records where it was discovered and ``frontmatter`` retains the parsed
+    header for introspection. Unlike a deck capability, a skill card is
+    *documentation the model reads*, not a callable — the model loads
+    ``location`` with the reader when a task matches ``description``.
+    """
+
+    # Validated invocation name.
+    name: str
+    # Single-line summary surfaced in the briefing.
+    description: str
+    # Markdown instruction text below the frontmatter.
+    body: str
+    # Absolute path of the `SKILL.md` file.
+    location: str
+    # Where the card was discovered.
+    origin: MacroOrigin
+    # Parsed frontmatter, retained for introspection.
+    frontmatter: SkillFrontmatter
+
+
+#: Outcome categories the skill loader can attach to a candidate file.
+#:
+#: - ``loaded`` — a valid card was produced.
+#: - ``skipped`` — the file was ignored by policy (e.g. not a ``SKILL.md``).
+#: - ``invalid`` — the file was a skill but failed validation.
+#: - ``collision`` — a card with the same name already won; this one was
+#:   dropped.
+SkillOutcomeKind: TypeAlias = Literal["loaded", "skipped", "invalid", "collision"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SkillDiagnostic:
+    """A single diagnostic the skill loader emits for one candidate file.
+
+    Replaces the legacy parallel ``{skills, diagnostics}`` arrays with one
+    tagged record per candidate: ``kind`` is the outcome, ``location`` the
+    file it concerns, and ``detail`` a human-readable explanation written in
+    the briefing's own voice.
+    """
+
+    # Outcome category for the candidate.
+    kind: SkillOutcomeKind
+    # Absolute path of the candidate file the diagnostic concerns.
+    location: str
+    # Human-readable explanation of the outcome.
+    detail: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SkillLoad:
+    """The aggregate result of loading skills from a set of roots.
+
+    ``cards`` are the validated, deduped cards (first writer wins per name);
+    ``diagnostics`` is the flat stream of per-candidate outcomes for surfacing
+    in a load report. A consumer renders ``cards`` into the briefing and may
+    show ``diagnostics`` to the user.
+    """
+
+    # Validated, deduped cards in discovery order.
+    cards: tuple[SkillCard, ...]
+    # Per-candidate outcomes accumulated during the load.
+    diagnostics: tuple[SkillDiagnostic, ...]
+
+
+#: Maximum length of a validated skill name, per the Agent-Skills format.
+SKILL_NAME_LIMIT: Final[int] = 64
+
+#: Maximum length of a validated skill description, per the format.
+SKILL_DESCRIPTION_LIMIT: Final[int] = 1024
+
+
+# ---------------------------------------------------------------------------
+# Faults
+# ---------------------------------------------------------------------------
+
+#: The closed set of failure categories this layer can surface.
+#:
+#: - ``skill_invalid`` — a ``SKILL.md`` failed format validation.
+#: - ``macro_invalid`` — a macro file could not be parsed.
+#: - ``publish`` — building or writing the HTML transcript failed (raised by
+#:   ``induscode.transcript_export``, which shares this fault type).
+#: - ``theme`` — a theme color could not be parsed or derived (ditto).
+BriefingFaultKind: TypeAlias = Literal["skill_invalid", "macro_invalid", "publish", "theme"]
+
+
+class BriefingFault(Exception):
+    """A typed, discriminated failure raised by the briefing/transcript layer.
+
+    ``kind`` selects the category, ``message`` is a human-readable summary,
+    and the optional ``cause`` carries the underlying error for logging
+    without forcing consumers to parse the message. Construct one with
+    :func:`briefing_fault`.
+
+    Port note: the TS shape was a plain frozen record ``throw``-n as a value;
+    Python requires raisables to be exceptions, so the same three fields ride
+    on an :class:`Exception` subclass.
+    """
+
+    def __init__(
+        self, kind: BriefingFaultKind, message: str, cause: object | None = None
+    ) -> None:
+        super().__init__(message)
+        # Failure category — the discriminant consumers switch on.
+        self.kind: BriefingFaultKind = kind
+        # Human-readable, single-line summary of what went wrong.
+        self.message: str = message
+        # Underlying error or structured detail, if any.
+        self.cause: object | None = cause
+
+
+def briefing_fault(
+    kind: BriefingFaultKind, message: str, cause: object | None = None
+) -> BriefingFault:
+    """Construct a :class:`BriefingFault`. The single sanctioned way to mint
+    one, so the shape stays uniform across every producer.
+
+    :param kind: the failure category
+    :param message: a human-readable, single-line summary
+    :param cause: optional underlying error or structured detail
+    """
+    return BriefingFault(kind, message, cause)