induscode 0.1.0__py3-none-any.whl

induscode/window_budget/summarize/condense.py

@@ -0,0 +1,212 @@
+"""Window-budget — model-driven summarization (port of TS
+``src/window-budget/summarize/condense.ts``).
+
+:func:`summarize` is the single condensing primitive: given the dropped
+prefix of a transcript and a :class:`SummarizeDeps` bundle, it flattens those
+messages, asks the injectable model completer to write a structured digest,
+and returns a synthetic :class:`~induscode.window_budget.contract.Summary`
+message that stands in for the slice it covers.
+
+Both condensing scopes flow through this one function:
+
+- ``"session"`` — the active-session checkpoint (head condensed, tail kept by
+  the caller).
+- ``"branch"``  — an abandoned branch archived into one message.
+
+The only difference is the scope flag forwarded into
+:func:`~.prompt.build_summary_prompt` (which selects the framing line).
+:func:`condense_scope` is the thin branch-archival entrypoint that pins
+``scope="branch"``.
+
+The completer is injectable (:attr:`SummarizeDeps.complete`, default the
+framework's :func:`indusagi.ai.complete_simple` — verified Python signature
+``(model, context, options=None, logger=None) -> AssistantMessage``) so tests
+run with no network — pass a stub that returns a canned
+:class:`indusagi.ai.AssistantMessage`. When no ``model`` is supplied there is
+nothing to call, so :func:`summarize` degrades to a deterministic local
+digest rather than guessing a model — keeping it usable in a bare/offline
+build.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, replace
+from typing import Any
+
+from indusagi.ai import (
+    AssistantMessage,
+    Context,
+    SimpleStreamOptions,
+    UserMessage,
+    complete_simple,
+)
+
+from ..contract import (
+    AgentMessage,
+    CompleteFn,
+    CondenseScope,
+    Model,
+    Summary,
+)
+from .prompt import CONDENSER_BRIEF, build_summary_prompt, flatten_transcript
+
+__all__ = [
+    "SummarizeDeps",
+    "condense_scope",
+    "flatten_transcript",
+    "summarize",
+]
+
+
+# ---------------------------------------------------------------------------
+# Dependencies
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SummarizeDeps:
+    """What :func:`summarize` needs. Every field is optional so the function
+    is network-free-testable: omit ``model`` for a local fallback digest, or
+    inject a ``complete`` stub for a scripted model response.
+    """
+
+    # Injectable completer (default: framework complete_simple).
+    complete: CompleteFn | None = None
+
+    # The summarization model. When omitted, a deterministic local digest is used.
+    model: Model | None = None
+
+    # Which kind of condense this is; defaults to "session".
+    scope: CondenseScope = "session"
+
+    # An earlier digest to refresh/extend (iterative-refresh / branch carry-in).
+    prior_digest: str | None = None
+
+    # Cancellation signal forwarded to the completer (the framework's
+    # CancelToken — kept opaque here; it lands on SimpleStreamOptions.signal).
+    signal: Any = None
+
+    # Optional cap on the digest size, in tokens, forwarded to the
+    # completer's `maxTokens`. A modest ceiling keeps the summary itself from
+    # eating the window. When omitted the model's own default applies.
+    max_tokens: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# Synthetic summary message
+# ---------------------------------------------------------------------------
+
+# The header line stamped onto the synthetic summary so a human (and the next
+# condense pass, via the `digest:` flattener case) can tell it apart from a
+# real user turn. Re-authored wording (verbatim from the TS rebuild) — not
+# the legacy `<summary>` framing, and DISTINCT from the framework
+# `indusagi.runtime.memory` compactor's `[condensed earlier context]` heading.
+_DIGEST_HEADER = "[session digest — older turns condensed]"
+_BRANCH_HEADER = "[branch digest — archived from a path not taken]"
+
+
+def _to_summary_message(digest: str, scope: CondenseScope) -> AgentMessage:
+    """Wrap digest text into a synthetic :data:`AgentMessage`. Modeled as a
+    plain ``user``-role message carrying the digest as text: it is the
+    simplest legal ``AgentMessage``, passes through the LLM conversion
+    natively, and the conductor splices it straight back into the message
+    list with no special handling."""
+    header = _BRANCH_HEADER if scope == "branch" else _DIGEST_HEADER
+    return UserMessage(
+        content=f"{header}\n\n{digest}",
+        timestamp=int(time.time() * 1000),
+    )
+
+
+def _text_of(message: AssistantMessage) -> str:
+    """Extract the concatenated text from a completer's assistant message."""
+    parts: list[str] = []
+    for block in message.content:
+        if getattr(block, "type", None) == "text" and block.text.strip():
+            parts.append(block.text)
+    return "\n".join(parts).strip()
+
+
+def _local_fallback_digest(
+    messages: list[AgentMessage], prior_digest: str | None = None
+) -> str:
+    """The offline fallback digest used when no ``model`` is supplied. It is
+    not a model summary — it simply records that the slice was elided and
+    preserves the prior digest if one was carried in, so a bare build never
+    silently loses the marker."""
+    lines = [
+        "# Carryover",
+        f"{len(messages)} earlier message(s) were elided without a summarization model bound.",
+    ]
+    if prior_digest and prior_digest.strip():
+        lines.extend(["", prior_digest.strip()])
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Core
+# ---------------------------------------------------------------------------
+
+
+async def summarize(
+    messages: list[AgentMessage],
+    deps: SummarizeDeps | None = None,
+) -> Summary:
+    """Summarize a slice of dropped messages into a single synthetic
+    :class:`~induscode.window_budget.contract.Summary`.
+
+    One code path for both scopes — ``deps.scope`` (default ``"session"``)
+    only changes the prompt framing. With a ``model`` bound it calls
+    ``deps.complete`` (default :func:`indusagi.ai.complete_simple`) once with
+    :data:`~.prompt.CONDENSER_BRIEF` as the system prompt and
+    :func:`~.prompt.build_summary_prompt` as the user turn; otherwise it
+    returns a deterministic local digest. Never raises on an empty model
+    reply — it falls back to the local digest so a ``Summary`` is always
+    produced.
+
+    :returns: a ``Summary`` whose ``message`` replaces the ``covered_count``
+        source messages it summarizes.
+    """
+    if deps is None:
+        deps = SummarizeDeps()
+    scope: CondenseScope = deps.scope
+    covered_count = len(messages)
+
+    # No model bound → deterministic, network-free local digest.
+    if deps.model is None:
+        digest = _local_fallback_digest(messages, deps.prior_digest)
+        return Summary(message=_to_summary_message(digest, scope), covered_count=covered_count)
+
+    prompt = build_summary_prompt(messages, scope, deps.prior_digest)
+    context = Context(
+        systemPrompt=CONDENSER_BRIEF,
+        messages=[UserMessage(content=prompt, timestamp=int(time.time() * 1000))],
+    )
+    options = SimpleStreamOptions(reasoning="high")
+    if deps.max_tokens is not None:
+        options.maxTokens = deps.max_tokens
+    if deps.signal is not None:
+        options.signal = deps.signal
+
+    complete: CompleteFn = deps.complete if deps.complete is not None else complete_simple
+    reply = await complete(deps.model, context, options)
+
+    digest = _text_of(reply)
+    final_digest = digest or _local_fallback_digest(messages, deps.prior_digest)
+    return Summary(
+        message=_to_summary_message(final_digest, scope),
+        covered_count=covered_count,
+    )
+
+
+async def condense_scope(
+    messages: list[AgentMessage],
+    deps: SummarizeDeps | None = None,
+) -> Summary:
+    """Branch-archival entrypoint: condense an abandoned branch into one
+    summary message. A thin wrapper that pins ``scope="branch"`` and
+    delegates to :func:`summarize` — the branch case is the same machinery,
+    not a separate engine."""
+    base = deps if deps is not None else SummarizeDeps()
+    return await summarize(messages, replace(base, scope="branch"))

induscode/window_budget/summarize/prompt.py

@@ -0,0 +1,241 @@
+"""Window-budget — summarization prompt assembly (port of TS
+``src/window-budget/summarize/prompt.ts``; re-authored prompt, copied
+VERBATIM here).
+
+When the transcript crosses budget, the older head is *condensed* into one
+synthetic message. This module turns the dropped slice of
+:data:`~induscode.window_budget.contract.AgentMessage` s into the single text
+payload handed to the model completer. Two pieces ship here:
+
+1. :data:`CONDENSER_BRIEF` — the system-prompt brief that frames the model as
+   a *recorder*, not a continuation of the chat: read the transcript as data
+   and emit only the structured digest.
+2. :func:`build_summary_prompt` — flattens the dropped messages into a tagged
+   block and appends the section template the model fills in.
+
+OWN VOCABULARY (an original prompt design):
+
+- Section headings are ``# Objective / # Guardrails /
+  # Status (Shipped / Active / Stuck) / # Rationale / # Plan / # Carryover``.
+- The transcript is wrapped in ``<scrollback>…</scrollback>`` and a prior
+  digest (the branch-archival / iterative-refresh path) in
+  ``<carried-digest>…</carried-digest>``.
+- Per-message lines use ``» role:`` markers (``» you``, ``» agent``,
+  ``» agent.plan``, ``» agent.call``, ``» tool``).
+
+No token math, no model calls, no I/O here — only string assembly. The scope
+flag selects the framing line (active-session checkpoint vs abandoned-branch
+archive); everything else is one code path.
+
+Port note: the flattener's role dispatch covers the agent's custom session
+messages (``bashExecution`` / ``custom`` / ``branchSummary`` /
+``compactionSummary``) EXPLICITLY — the Python ``indusagi.ai.AgentMessage``
+alias excludes them (analysis 05 risk-2), and probing is ``getattr`` duck
+typing over the frozen message dataclasses, not dict access.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from ..contract import AgentMessage, CondenseScope
+
+__all__ = [
+    "CONDENSER_BRIEF",
+    "build_summary_prompt",
+    "flatten_transcript",
+]
+
+
+# ---------------------------------------------------------------------------
+# System brief
+# ---------------------------------------------------------------------------
+
+#: The system-prompt brief for the condenser model. Frames the request as a
+#: record-keeping task — the model must NOT answer, continue, or act on the
+#: conversation; it only transcribes it into the fixed section layout.
+#: Re-authored wording (copied verbatim from the TS rebuild); shares no
+#: sentences with the legacy ``SUMMARIZATION_SYSTEM_PROMPT``.
+CONDENSER_BRIEF = "\n".join(
+    [
+        "You are a transcript recorder for a long-running coding session.",
+        "The text you receive is archival data, not a live chat — do NOT reply to it,",
+        "continue it, run tools, or ask questions. Your sole job is to distill it into",
+        "a compact, faithful digest under the exact headings requested below.",
+        "",
+        "Rules:",
+        "- Preserve concrete facts: file paths, identifiers, commands, error text,",
+        "  decisions, and anything the session would need to resume without the",
+        "  original turns.",
+        "- Prefer specifics over paraphrase; never invent details that are not present.",
+        "- Keep each heading even if a section is empty (write `none` under it).",
+        "- Emit only the digest — no preamble, no sign-off, no commentary.",
+    ]
+)
+
+
+# ---------------------------------------------------------------------------
+# Transcript flattening
+# ---------------------------------------------------------------------------
+
+# Marker prefix for every flattened turn line.
+_TURN_MARK = "»"
+
+_TRAILING_WS_RE = re.compile(r"[ \t]+\n")
+
+
+def _tidy(text: str) -> str:
+    """Collapse runs of whitespace so the flattened block stays compact."""
+    return _TRAILING_WS_RE.sub("\n", text.replace("\r\n", "\n")).strip()
+
+
+def _read_content(content: object) -> str:
+    """Pull plain text out of a string-or-content-blocks field."""
+    if isinstance(content, str):
+        return content
+    parts: list[str] = []
+    if isinstance(content, (list, tuple)):
+        for block in content:
+            block_type = getattr(block, "type", None)
+            if block_type == "text":
+                text = getattr(block, "text", None)
+                if isinstance(text, str):
+                    parts.append(text)
+            elif block_type == "image":
+                parts.append("[image]")
+    return "\n".join(parts)
+
+
+def _safe_json(value: object) -> str:
+    """JSON-serialize that never raises and never explodes the line width."""
+    try:
+        return json.dumps(value, default=str, separators=(",", ":"))
+    except Exception:
+        return "{}"
+
+
+def _flatten_message(message: AgentMessage) -> str:
+    """Render a single :data:`AgentMessage` as one-or-more ``» role:`` lines.
+    Returns ``""`` for messages with no projectable content (they are
+    skipped). This is the re-authored flattener — role markers and ordering
+    differ from the legacy ``serializeConversation``.
+    """
+    role = getattr(message, "role", None)
+
+    if role == "user":
+        text = _tidy(_read_content(getattr(message, "content", None)))
+        return f"{_TURN_MARK} you: {text}" if text else ""
+
+    if role == "assistant":
+        lines: list[str] = []
+        content = getattr(message, "content", None) or ()
+        for block in content:
+            block_type = getattr(block, "type", None)
+            if block_type == "text" and getattr(block, "text", "").strip():
+                lines.append(f"{_TURN_MARK} agent: {_tidy(block.text)}")
+            elif block_type == "thinking" and getattr(block, "thinking", "").strip():
+                lines.append(f"{_TURN_MARK} agent.plan: {_tidy(block.thinking)}")
+            elif block_type == "toolCall":
+                args = _safe_json(getattr(block, "arguments", None))
+                lines.append(f"{_TURN_MARK} agent.call {block.name}: {args}")
+        return "\n".join(lines)
+
+    if role == "toolResult":
+        text = _tidy(_read_content(getattr(message, "content", None)))
+        tag = "tool!err" if getattr(message, "isError", False) else "tool"
+        tool_name = getattr(message, "toolName", "")
+        return f"{_TURN_MARK} {tag} ({tool_name}): {text}"
+
+    if role == "bashExecution":
+        out = _tidy(getattr(message, "output", "") or "")
+        exit_code = getattr(message, "exitCode", None)
+        code = exit_code if exit_code is not None else "n/a"
+        command = _tidy(getattr(message, "command", "") or "")
+        return f"{_TURN_MARK} shell$ {command} [exit {code}]\n{out}"
+
+    if role == "custom":
+        text = _tidy(_read_content(getattr(message, "content", None)))
+        custom_type = getattr(message, "customType", "")
+        return f"{_TURN_MARK} note ({custom_type}): {text}" if text else ""
+
+    if role in ("branchSummary", "compactionSummary"):
+        text = _tidy(getattr(message, "summary", "") or "")
+        return f"{_TURN_MARK} digest: {text}" if text else ""
+
+    return ""
+
+
+def flatten_transcript(messages: list[AgentMessage]) -> str:
+    """Flatten a list of messages into a single ``\\n``-joined block of
+    ``» role:`` lines. Exported so the condenser can reuse it for
+    diagnostics/tests."""
+    lines: list[str] = []
+    for message in messages:
+        rendered = _flatten_message(message)
+        if rendered:
+            lines.append(rendered)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Prompt builder
+# ---------------------------------------------------------------------------
+
+# The re-authored section template the model fills in (verbatim from the TS
+# rebuild — these headings are pinned by tests and the digest parser).
+_SECTION_TEMPLATE = "\n".join(
+    [
+        "# Objective",
+        "# Guardrails",
+        "# Status (Shipped / Active / Stuck)",
+        "# Rationale",
+        "# Plan",
+        "# Carryover",
+    ]
+)
+
+
+def _framing(scope: CondenseScope) -> str:
+    """The scope-specific framing line that precedes the template."""
+    if scope == "branch":
+        return (
+            "Archive this abandoned branch so it can be folded back as context later. "
+            "Distill it under these headings:"
+        )
+    return (
+        "Condense the older portion of this active session so recent turns stay verbatim. "
+        "Distill it under these headings:"
+    )
+
+
+def build_summary_prompt(
+    messages: list[AgentMessage],
+    scope: CondenseScope,
+    prior_digest: str | None = None,
+) -> str:
+    """Build the full summarization prompt for a slice of dropped messages.
+
+    The result is one string: the scope framing, the flattened transcript
+    wrapped in ``<scrollback>``, an optional carried digest wrapped in
+    ``<carried-digest>`` (the iterative-refresh / branch-archival input), and
+    the section template the model fills in. Pass this as the user turn to
+    the injectable completer; pair it with :data:`CONDENSER_BRIEF` as the
+    system prompt.
+
+    :param messages: the dropped prefix to summarize
+    :param scope: ``"session"`` (active checkpoint) or ``"branch"`` (archive)
+    :param prior_digest: an optional earlier digest to refresh/extend,
+        threaded in under ``<carried-digest>`` so the model merges rather
+        than re-derives. Omit for a first-pass condense.
+    """
+    transcript = flatten_transcript(messages)
+    blocks: list[str] = [_framing(scope)]
+
+    if prior_digest and prior_digest.strip():
+        blocks.append(f"<carried-digest>\n{_tidy(prior_digest)}\n</carried-digest>")
+
+    blocks.append(f"<scrollback>\n{transcript}\n</scrollback>")
+    blocks.append(_SECTION_TEMPLATE)
+
+    return "\n\n".join(blocks)

induscode/workspace/__init__.py

@@ -0,0 +1,30 @@
+"""Workspace — product identity (:data:`BRAND`, :data:`VERSION`) and the
+resolved on-disk layout (:class:`Workspace` via :func:`create_workspace`).
+
+Port of the TS ``src/workspace`` barrel (``runtime-detect.ts`` dropped; see
+the :mod:`~induscode.workspace.locator` module docstring for why).
+"""
+
+from .brand import BRAND, Brand, VERSION
+from .locator import (
+    DIRECTORY_KEYS,
+    ENV_FRAMEWORK_HOME,
+    LAYOUT,
+    Workspace,
+    WorkspaceOverrides,
+    create_workspace,
+    ensure_dirs,
+)
+
+__all__ = [
+    "BRAND",
+    "Brand",
+    "DIRECTORY_KEYS",
+    "ENV_FRAMEWORK_HOME",
+    "LAYOUT",
+    "VERSION",
+    "Workspace",
+    "WorkspaceOverrides",
+    "create_workspace",
+    "ensure_dirs",
+]

induscode/workspace/brand.py

@@ -0,0 +1,96 @@
+"""Brand record — the single source of truth for every identity literal.
+
+One frozen :class:`Brand` value. Nothing else in the app hard-codes the
+product name, the bin names, the env-var namespace, or the share-viewer
+origin. A rebrand edits this record and nothing else.
+
+Port note (TS ``src/workspace/brand.ts``)
+-----------------------------------------
+The TS record carried ``profileDirName: ".indusagi"`` plus a nested
+``stateDirName: "agent"`` (profile root ``~/.indusagi/agent``). The Python
+build owns the flat ``~/.pindusagi`` root shared with the ``indusagi``
+framework — there is no ``agent/`` nesting because nothing else shares the
+directory — so ``state_dir_name`` is dropped and :attr:`Brand.profile_dir_name`
+is composed from the framework's own brand record
+(:data:`indusagi.shell_app.locate.BRAND`) so the two can never drift.
+
+The bin names are the locked Python renames (``pindus``/``induscode``; npm
+owns ``indus``/``indusagi``). The env-var names and the share-viewer fields
+are kept verbatim from TS.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import metadata as _metadata
+from typing import Final
+
+from indusagi.shell_app.locate import BRAND as _FRAMEWORK_BRAND
+
+__all__ = ["BRAND", "Brand", "VERSION"]
+
+
+@dataclass(frozen=True, slots=True)
+class Brand:
+    """The shape of the brand record.
+
+    Field names are the mechanical snake_case renames of the TS ``Brand``
+    contract (``boot/contract.ts``); values are the induscode identity.
+    """
+
+    # The product's machine name — printed by `--version`, stamped on traces.
+    name: str
+    # The product's display label, used in banners and prose.
+    label: str
+    # The dot-directory carved under the user's home for all per-user state
+    # (e.g. ".pindusagi"). Composed from the framework brand; the Python build
+    # shares the framework's flat root (no TS-style "agent/" nesting).
+    profile_dir_name: str
+    # The console-script names users invoke (primary first).
+    bin_names: tuple[str, ...]
+    # The namespace prefix on every environment variable the app reads.
+    env_prefix: str
+    # Env var that relocates the entire agent profile directory.
+    env_profile_dir: str
+    # Env var that enables verbose diagnostics.
+    env_debug: str
+    # Env var that overrides the share-viewer origin.
+    env_share_viewer: str
+    # Default origin shared transcripts are viewed at.
+    share_viewer_url: str
+
+
+#: The concrete induscode identity. Frozen so the record cannot be mutated by
+#: any consumer; a drift from the contract is a construction error here rather
+#: than a runtime surprise downstream.
+BRAND: Final[Brand] = Brand(
+    name="induscode",
+    label="induscode",
+    profile_dir_name=_FRAMEWORK_BRAND.profile_dir_name,  # ".pindusagi"
+    bin_names=("pindus", "induscode"),
+    env_prefix="INDUSAGI",
+    env_profile_dir="INDUSAGI_CODING_AGENT_DIR",
+    env_debug="INDUSAGI_DEBUG",
+    env_share_viewer="INDUSAGI_SHARE_VIEWER_URL",
+    share_viewer_url="https://buildwithindusagi.ai/session/",
+)
+
+
+def _detect_version() -> str:
+    """Resolve the product version from the installed package metadata.
+
+    Single-sourced from ``pyproject.toml`` via :mod:`importlib.metadata` —
+    the TS build duplicated the version as a literal (``VERSION = "0.1.62"``
+    in ``brand.ts`` next to ``package.json``); the port fixes that. The
+    fallback only fires when the package is imported without being installed
+    (e.g. straight off a source checkout's ``sys.path``).
+    """
+    try:
+        return _metadata.version("induscode")
+    except _metadata.PackageNotFoundError:  # pragma: no cover - dev checkout only
+        return "0.1.0.dev0"
+
+
+#: The product version — printed by `--version` and shown on the startup
+#: banner. (TS lineage: indusagi-coding-agent v0.1.62.)
+VERSION: Final[str] = _detect_version()