induscode 0.1.0__py3-none-any.whl

induscode/addons/surface.py

@@ -0,0 +1,199 @@
+"""AddonSurface implementation — the recording registration API.
+
+This module realizes the contract's central design stance: an addon's
+``register`` entry point is handed an :class:`~induscode.addons.contract.AddonSurface`
+and *records* its intent — event subscriptions, tool interceptors, slash
+commands, contributed tools — rather than mutating any shared runtime. Each
+surface is a small, per-addon accumulator: every ``on`` / ``intercept_tool``
+/ ``add_command`` / ``add_tool`` call appends to a private list, and
+:meth:`RecordingSurface.manifest` reads the accumulated
+:class:`RegisteredManifest` back out for the host to fold.
+
+Because registration is pure recording, the host stays in control of *what to
+do* with the contributions. The surface only:
+
+- stamps every recorded shape with the owning :data:`AddonId` (so a later
+  fault is attributable) and fills the ``match`` / ``name`` fields the
+  surface methods take separately from the handler object;
+- threads the host-supplied :class:`FrameworkHandles` through unchanged, so
+  an addon can act at registration time and the same handles reach its
+  command contexts; and
+- returns an immutable snapshot from :meth:`RecordingSurface.manifest` (a
+  frozen dataclass over tuples), so a read after ``register`` settles cannot
+  be mutated by a stray later call.
+
+The surface performs no dispatch, no loading, and no conflict resolution —
+those are the host's job once it has folded every addon's manifest. Keeping
+the surface this thin is what makes registration a description of capability
+rather than a side effect on the agent.
+"""
+
+from __future__ import annotations
+
+from .contract import (
+    AddonCommand,
+    AddonId,
+    AddonSurface,
+    AddonTool,
+    CommandSpec,
+    EventSubscription,
+    FrameworkHandles,
+    HookEvent,
+    HookHandler,
+    InterceptorStage,
+    RegisteredManifest,
+    ToolInterceptor,
+)
+
+__all__ = [
+    "RecordingSurface",
+    "create_surface",
+]
+
+
+# ---------------------------------------------------------------------------
+# Recording surface
+# ---------------------------------------------------------------------------
+
+
+class RecordingSurface:
+    """The concrete, per-addon :class:`AddonSurface` the host hands to one
+    addon's ``register``.
+
+    Construct one with :func:`create_surface` (the host mints a fresh surface
+    per addon, scoped to that addon's :data:`AddonId` and the session's
+    :class:`FrameworkHandles`). The surface accumulates contributions into
+    private lists and exposes them as a frozen :class:`RegisteredManifest`
+    once ``register`` has run.
+    """
+
+    def __init__(
+        self,
+        id: AddonId,
+        handles: FrameworkHandles,
+        version: str | None = None,
+    ) -> None:
+        """
+        :param id: the addon this surface is scoped to (stamped onto every shape)
+        :param handles: the session's framework handles, threaded through unchanged
+        :param version: optional addon version, carried into the manifest
+        """
+        self._id = id
+        self._handles = handles
+        self._version = version
+        # Event subscriptions recorded via `on`, in call order.
+        self._subscriptions: list[EventSubscription] = []
+        # Tool interceptors recorded via `intercept_tool`, in call order.
+        self._interceptors: list[ToolInterceptor] = []
+        # Slash commands recorded via `add_command`, in call order.
+        self._commands: list[AddonCommand] = []
+        # Contributed tools recorded via `add_tool`, in call order.
+        self._tools: list[AddonTool] = []
+
+    @property
+    def id(self) -> AddonId:
+        """The id of the addon this surface is scoped to."""
+        return self._id
+
+    @property
+    def handles(self) -> FrameworkHandles:
+        """The session's framework handles, threaded through unchanged."""
+        return self._handles
+
+    def on(self, event: HookEvent, handler: HookHandler) -> None:
+        """Record a :data:`HookHandler` subscription to a colon-named
+        :data:`HookEvent`.
+
+        The handler's payload type is erased to the contract's recorded
+        :class:`EventSubscription` shape; the dispatcher re-narrows it per
+        dispatch.
+
+        :param event: the event to hook
+        :param handler: the observe/transform/gate middleware
+        """
+        self._subscriptions.append(
+            EventSubscription(event=event, handler=handler, addon=self._id)
+        )
+
+    def intercept_tool(self, name: str, stage: InterceptorStage) -> None:
+        """Record a :class:`ToolInterceptor`, filling its ``match`` (the tool
+        name or ``"*"``) and ``addon`` from the surface around the supplied
+        enter/exit stage.
+
+        :param name: the tool name to intercept, or ``"*"`` for every tool
+        :param stage: the enter/exit stage (its ``match``/``addon`` are filled here)
+        """
+        self._interceptors.append(
+            ToolInterceptor(
+                match=name,
+                addon=self._id,
+                enter=stage.enter,
+                exit=stage.exit,
+            )
+        )
+
+    def add_command(self, name: str, spec: CommandSpec) -> None:
+        """Record a slash :class:`AddonCommand`, filling its ``name`` and
+        ``addon`` from the surface around the supplied definition.
+
+        :param name: the invocation token (no leading slash)
+        :param spec: the command definition (its ``name``/``addon`` are filled here)
+        """
+        self._commands.append(
+            AddonCommand(
+                name=name,
+                summary=spec.summary,
+                addon=self._id,
+                run=spec.run,
+            )
+        )
+
+    def add_tool(self, card: AddonTool) -> None:
+        """Record an LLM-callable :data:`AddonTool` the addon contributes.
+
+        :param card: the framework tool to add to the session's deck
+        """
+        self._tools.append(card)
+
+    def manifest(self) -> RegisteredManifest:
+        """The accumulated :class:`RegisteredManifest` of everything recorded
+        so far.
+
+        Returns an immutable snapshot: the lists are copied into tuples on a
+        frozen dataclass, so a later surface call cannot retroactively alter a
+        manifest the host has already read, and a consumer cannot mutate the
+        host's view either (the TS ``Object.freeze`` parity).
+        """
+        return RegisteredManifest(
+            addon=self._id,
+            version=self._version,
+            subscriptions=tuple(self._subscriptions),
+            interceptors=tuple(self._interceptors),
+            commands=tuple(self._commands),
+            tools=tuple(self._tools),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Construction
+# ---------------------------------------------------------------------------
+
+
+def create_surface(
+    id: AddonId,
+    handles: FrameworkHandles,
+    version: str | None = None,
+) -> AddonSurface:
+    """Mint a fresh :class:`AddonSurface` for one addon.
+
+    The host calls this once per addon, scoping the surface to that addon's
+    :data:`AddonId` and the session's :class:`FrameworkHandles`, then passes
+    the surface to the addon's ``register``. After ``register`` settles the
+    host reads :meth:`AddonSurface.manifest` to obtain the contributions to
+    fold.
+
+    :param id: the addon the surface is scoped to
+    :param handles: the framework handles the addon (and its commands) may act through
+    :param version: optional addon version carried into the recorded manifest
+    """
+    return RecordingSurface(id, handles, version)

induscode/boot/__init__.py

@@ -0,0 +1,108 @@
+"""Boot subsystem — public barrel (port of TS ``src/boot/index.ts``).
+
+Re-exports the frozen contract type surface plus the assembled boot layer:
+the orchestrator (:func:`boot`), the stage pipeline (:func:`run_stages` /
+:data:`STAGES`), the invocation projection (:func:`tokenize_invocation`),
+the runner registry (:func:`select_runner` / :data:`RUNNERS`), the disk
+credential vault (:func:`create_auth_vault`), and the upgrade driver
+(:func:`apply_upgrades`). Consumers import the boot type surface and
+behavior from ``induscode.boot`` rather than reaching into individual
+modules.
+
+The workspace surface is re-exported too, so ``induscode.boot`` is a
+one-stop boot import site (as the TS barrel was).
+"""
+
+from __future__ import annotations
+
+from induscode.workspace import (
+    BRAND,
+    Brand,
+    Workspace,
+    WorkspaceOverrides,
+    create_workspace,
+    ensure_dirs,
+)
+
+from .auth_vault import DiskAuthVault, create_auth_vault
+from .boot import boot
+from .contract import (
+    BootContext,
+    Closable,
+    CredentialGraph,
+    Invocation,
+    Runner,
+    RunnerId,
+    Stage,
+    StartupResources,
+    ThinkingLevel,
+)
+from .invocation import to_runner_id, tokenize_invocation, wants_help, wants_version
+from .runners import (
+    RUNNERS,
+    ConsoleMount,
+    ReplServices,
+    build_session_conductor,
+    link_runner,
+    oneshot_runner,
+    repl_runner,
+    select_runner,
+    session_scope_dir,
+    set_console_mount,
+)
+from .stages import (
+    STAGES,
+    build_invocation,
+    locate_workspace,
+    resolve_resources,
+    run_stages,
+    select_runner_stage,
+    upgrade_stage,
+)
+from .upgrade import UPGRADES, Upgrade, UpgradeReport, apply_upgrades
+
+__all__ = [
+    "BRAND",
+    "BootContext",
+    "Brand",
+    "Closable",
+    "ConsoleMount",
+    "CredentialGraph",
+    "DiskAuthVault",
+    "Invocation",
+    "RUNNERS",
+    "ReplServices",
+    "Runner",
+    "RunnerId",
+    "STAGES",
+    "Stage",
+    "StartupResources",
+    "ThinkingLevel",
+    "UPGRADES",
+    "Upgrade",
+    "UpgradeReport",
+    "Workspace",
+    "WorkspaceOverrides",
+    "apply_upgrades",
+    "boot",
+    "build_invocation",
+    "build_session_conductor",
+    "create_auth_vault",
+    "create_workspace",
+    "ensure_dirs",
+    "link_runner",
+    "locate_workspace",
+    "oneshot_runner",
+    "repl_runner",
+    "resolve_resources",
+    "run_stages",
+    "select_runner",
+    "select_runner_stage",
+    "session_scope_dir",
+    "set_console_mount",
+    "to_runner_id",
+    "tokenize_invocation",
+    "upgrade_stage",
+    "wants_help",
+    "wants_version",
+]

induscode/boot/auth_vault.py

@@ -0,0 +1,323 @@
+"""Disk-backed credential vault — the boot-layer implementation of the launch
+:class:`~induscode.launch.AuthVault` Protocol.
+
+Port of TS ``src/boot/auth-vault.ts``. The store is a single JSON file
+(``auth.json`` under the profile directory), keyed provider → account →
+record. Each record is a discriminated union: it holds *either* a stored api
+key or a set of browser-sign-in credentials, plus a default marker:
+
+- ``{"kind": "apiKey", "key": ..., "isDefault": bool}``
+- ``{"kind": "oauth", "isDefault": bool, "access": ..., "refresh": ...,
+  "expires": ...}`` (the launch :class:`~induscode.launch.OAuthCredentials`
+  fields flattened in, exactly as the TS spread laid them out)
+
+A legacy pre-discriminant ``{"apiKey": ..., "isDefault": bool}`` record is
+tolerated on read. An entry that cannot be understood is dropped.
+
+The adapter is deliberately small and self-contained: it reads / rewrites the
+whole file each time (the file is tiny and the operations are interactive, so
+atomic-rewrite simplicity beats incremental I/O), and every rewrite applies
+owner-only ``0600`` permissions.
+
+Two kinds of read are offered. The default-account lookup is plain
+bookkeeping; :meth:`DiskAuthVault.read_usable_key` resolves a record to a
+live api-key string — for an api-key record it returns the stored key
+verbatim, and for a browser-sign-in record it refreshes an expired access
+token through the launch OAuth adapter
+(:func:`~induscode.launch.refresh_oauth_credentials`), persisting the rotated
+credentials back to disk, before handing back the usable key.
+
+Port notes
+----------
+- TS delegated freshness to the framework's ``ensureFreshOAuthCredentials``
+  (refresh-when-expired) and then asked the provider object for
+  ``getApiKey(credentials)``. The Python framework has no provider objects:
+  the vault itself owns the expiry check (refresh when the stored ``expires``
+  deadline is within a one-minute margin of now) and the usable key for a
+  browser-sign-in record *is* its access token.
+- TS returned ``undefined`` from ``readUsableKey`` when no OAuth provider was
+  registered for the record's provider id; the port keeps that (the registry
+  is primed explicitly by the boot layer, never at import time).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Final, Literal
+
+from induscode.launch import (
+    AuthVault,
+    OAuthCredentials,
+    get_oauth_provider,
+    refresh_oauth_credentials,
+)
+
+__all__ = [
+    "DiskAuthVault",
+    "create_auth_vault",
+]
+
+#: Owner-only read/write file mode for the credential store.
+_SECURE_FILE_MODE: Final[int] = 0o600
+
+#: Refresh a stored browser token this many milliseconds *before* its
+#: recorded ``expires`` deadline, so a token never dies mid-request. (The TS
+#: margin lived inside the framework's ``ensureFreshOAuthCredentials``; the
+#: port owns it here.)
+_EXPIRY_MARGIN_MS: Final[int] = 60_000
+
+#: One stored record (the on-disk dict shape, camelCase keys verbatim).
+_Record = dict[str, Any]
+
+#: The on-disk shape: provider → account → record.
+_AuthFile = dict[str, dict[str, _Record]]
+
+
+def _normalise_record(value: object) -> _Record | None:
+    """Normalise a parsed record to the discriminated shape, tolerating the
+    older ``{apiKey, isDefault}`` layout that predates the discriminant. An
+    entry that cannot be understood is dropped (returned as ``None``)."""
+    if not isinstance(value, Mapping):
+        return None
+    is_default = value.get("isDefault") is True
+
+    if value.get("kind") == "oauth":
+        if isinstance(value.get("access"), str) and isinstance(value.get("refresh"), str):
+            record = dict(value)
+            record["kind"] = "oauth"
+            record["isDefault"] = is_default
+            return record
+        return None
+
+    if value.get("kind") == "apiKey" and isinstance(value.get("key"), str):
+        return {"kind": "apiKey", "key": value["key"], "isDefault": is_default}
+    # Legacy pre-discriminant layout: a bare { apiKey, isDefault } record.
+    if isinstance(value.get("apiKey"), str):
+        return {"kind": "apiKey", "key": value["apiKey"], "isDefault": is_default}
+    return None
+
+
+def _read_auth_file(path: Path) -> _AuthFile:
+    """Read the auth file, tolerating a missing or malformed file as empty."""
+    try:
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(parsed, Mapping):
+            return {}
+        file: _AuthFile = {}
+        for provider, accounts in parsed.items():
+            if not isinstance(accounts, Mapping):
+                continue
+            normalised: dict[str, _Record] = {}
+            for account, record in accounts.items():
+                value = _normalise_record(record)
+                if value is not None:
+                    normalised[str(account)] = value
+            file[str(provider)] = normalised
+        return file
+    except Exception:
+        return {}
+
+
+def _write_auth_file(path: Path, data: _AuthFile) -> None:
+    """Persist the auth file, creating the parent directory if needed and
+    applying the owner-only mode authoritatively (the rewrite path keeps the
+    mode even when the file pre-existed with looser bits)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"{json.dumps(data, indent=2)}\n", encoding="utf-8")
+    os.chmod(path, _SECURE_FILE_MODE)
+
+
+def _to_credentials(record: _Record) -> OAuthCredentials:
+    """Strip the bookkeeping fields off an oauth record, leaving the launch
+    credential shape the refresh seam speaks."""
+    refresh = record.get("refresh")
+    expires = record.get("expires")
+    return OAuthCredentials(
+        access=str(record.get("access", "")),
+        refresh=refresh if isinstance(refresh, str) else None,
+        expires=int(expires) if isinstance(expires, (int, float)) and not isinstance(expires, bool) else None,
+    )
+
+
+def _is_expired(credentials: OAuthCredentials) -> bool:
+    """Whether a stored browser token's recorded deadline has passed (or is
+    inside the early-refresh margin). A record with no deadline is treated as
+    fresh — the refresh path only fires when expiry is actually known."""
+    if credentials.expires is None:
+        return False
+    return credentials.expires <= int(time.time() * 1000) + _EXPIRY_MARGIN_MS
+
+
+def _clear_defaults(accounts: dict[str, _Record]) -> None:
+    """Clear the default flag on every account in a provider bucket."""
+    for name, record in list(accounts.items()):
+        accounts[name] = {**record, "isDefault": False}
+
+
+class DiskAuthVault:
+    """The disk vault: a structural implementation of the launch
+    :class:`~induscode.launch.AuthVault` Protocol persisting to one
+    ``auth.json``. Construct via :func:`create_auth_vault`."""
+
+    __slots__ = ("_path",)
+
+    def __init__(self, auth_path: str | os.PathLike[str]) -> None:
+        self._path = Path(auth_path)
+
+    async def list_accounts(self, provider: str) -> list[str]:
+        """Stored account names for a provider, in insertion order."""
+        file = _read_auth_file(self._path)
+        return list(file.get(provider, {}).keys())
+
+    async def default_account(self, provider: str) -> str | None:
+        """The account flagged default for a provider, if any."""
+        file = _read_auth_file(self._path)
+        for account, record in file.get(provider, {}).items():
+            if record.get("isDefault") is True:
+                return account
+        return None
+
+    async def put_api_key(
+        self,
+        provider: str,
+        account: str,
+        api_key: str,
+        make_default: bool = False,
+    ) -> None:
+        """Persist an api key under a provider / account, optionally as the
+        provider's default (clearing any prior default)."""
+        file = _read_auth_file(self._path)
+        accounts = dict(file.get(provider, {}))
+        if make_default:
+            _clear_defaults(accounts)
+        accounts[account] = {"kind": "apiKey", "key": api_key, "isDefault": make_default}
+        file[provider] = accounts
+        _write_auth_file(self._path, file)
+
+    async def put_oauth(
+        self,
+        provider: str,
+        account: str,
+        credentials: OAuthCredentials,
+        make_default: bool = False,
+    ) -> None:
+        """Persist browser-sign-in credentials under a provider / account,
+        optionally as the provider's default (clearing any prior default)."""
+        file = _read_auth_file(self._path)
+        accounts = dict(file.get(provider, {}))
+        if make_default:
+            _clear_defaults(accounts)
+        record: _Record = {
+            "access": credentials.access,
+            "kind": "oauth",
+            "isDefault": make_default,
+        }
+        if credentials.refresh is not None:
+            record["refresh"] = credentials.refresh
+        if credentials.expires is not None:
+            record["expires"] = credentials.expires
+        accounts[account] = record
+        file[provider] = accounts
+        _write_auth_file(self._path, file)
+
+    async def auth_kind(
+        self, provider: str, account: str
+    ) -> Literal["apiKey", "oauth"] | None:
+        """Report whether a stored account holds an api key or browser
+        sign-in credentials, or ``None`` when nothing is stored there."""
+        file = _read_auth_file(self._path)
+        record = file.get(provider, {}).get(account)
+        kind = record.get("kind") if record is not None else None
+        return kind if kind in ("apiKey", "oauth") else None
+
+    async def read_usable_key(self, provider: str, account: str) -> str | None:
+        """Resolve a stored account to a live api-key string.
+
+        An api-key record yields its key verbatim. A browser-sign-in record
+        yields its access token, refreshing first (and persisting the rotated
+        credentials, preserving the default flag) when the recorded expiry
+        deadline has passed. Resolves ``None`` when nothing usable is stored
+        or no OAuth adapter is registered for the provider.
+        """
+        file = _read_auth_file(self._path)
+        record = file.get(provider, {}).get(account)
+        if record is None:
+            return None
+
+        if record.get("kind") == "apiKey":
+            key = record.get("key")
+            return key if isinstance(key, str) else None
+
+        # A browser-sign-in record: hand the launch adapter the chance to
+        # rotate an expired access token, persisting refreshed credentials.
+        if get_oauth_provider(provider) is None:
+            return None
+
+        current = _to_credentials(record)
+        if not _is_expired(current):
+            return current.access
+
+        refreshed = await refresh_oauth_credentials(provider, current)
+        accounts = dict(file.get(provider, {}))
+        rotated: _Record = {
+            "access": refreshed.access,
+            "kind": "oauth",
+            "isDefault": record.get("isDefault") is True,
+        }
+        if refreshed.refresh is not None:
+            rotated["refresh"] = refreshed.refresh
+        if refreshed.expires is not None:
+            rotated["expires"] = refreshed.expires
+        accounts[account] = rotated
+        file[provider] = accounts
+        _write_auth_file(self._path, file)
+        return refreshed.access
+
+    async def remove(self, provider: str, account: str | None = None) -> bool:
+        """Remove a stored credential.
+
+        With no ``account``, the whole provider bucket is removed. Removing
+        the default account promotes the first surviving account to default;
+        removing the last account drops the provider bucket entirely.
+        Resolves ``False`` when nothing was removed.
+        """
+        file = _read_auth_file(self._path)
+        accounts = file.get(provider)
+        if accounts is None:
+            return False
+
+        if account is None:
+            del file[provider]
+            _write_auth_file(self._path, file)
+            return True
+
+        if account not in accounts:
+            return False
+        was_default = accounts[account].get("isDefault") is True
+        del accounts[account]
+
+        # Promote a surviving account to default if the removed one was it.
+        survivors = list(accounts.keys())
+        if was_default and survivors:
+            first = survivors[0]
+            accounts[first] = {**accounts[first], "isDefault": True}
+        if not survivors:
+            del file[provider]
+        else:
+            file[provider] = accounts
+        _write_auth_file(self._path, file)
+        return True
+
+
+def create_auth_vault(auth_path: str | os.PathLike[str]) -> AuthVault:
+    """Build a disk-backed :class:`~induscode.launch.AuthVault` persisting to
+    ``auth_path``.
+
+    :param auth_path: absolute path of the JSON credential store
+        (e.g. ``auth.json``)
+    """
+    return DiskAuthVault(auth_path)