induscode 0.1.0__py3-none-any.whl

induscode/launch/contract.py

@@ -0,0 +1,569 @@
+"""Launch contract — the FROZEN type surface of the command-line layer.
+
+This module is the single typed seam between a raw ``argv`` and a fully
+configured run. It owns the *application* command line: the declarative flag
+table vocabulary, the parsed :class:`Invocation` those flags fold into, the
+gathered ``@file`` :class:`Attachments`, and the typed :class:`CredentialFault`
+the sign-in surface raises. It declares *only* shapes plus a few inert, pure
+helpers — no parsing, no terminal I/O, no widgets. The reader
+(:func:`~.invocation.read_invocation`), the usage renderer
+(:func:`~.invocation.render_usage`), the attachment gatherer
+(:func:`~.invocation.gather_attachments`), the model-catalog printer
+(:func:`~.catalog.print_model_catalog`), the resume picker
+(:func:`~.pickers.pick_resume_target`), the settings browser
+(:func:`~.pickers.browse_settings`), and the credential command
+(:func:`~.credentials.run_credential_command`) are each written against the
+names declared here, so the file is intentionally small, append-mostly, and
+stable.
+
+Design stance (TS ``src/launch/contract.ts``, ported):
+
+- There is exactly **one declarative flag table**
+  (:data:`~.invocation.flags.FLAG_SPECS`). The reader walks it to bind tokens;
+  the usage renderer generates the help text *from the same table*. Help and
+  parsing cannot drift, because there is no second hand-maintained help string
+  to drift against.
+- :class:`Invocation` is a superset of the boot-layer minimal invocation: it
+  keeps ``mode`` / ``prompt`` / ``flags`` / ``positionals`` and adds the
+  resolved, strongly-typed launch fields the runtime reads.
+- Failures are typed unions (:class:`CredentialFault`,
+  :class:`~.invocation.attachments.AttachmentError`), never string sentinels.
+- The credential vault (:class:`AuthVault`) is an app-owned **Protocol** here:
+  the framework publishes no credential-store type, and the concrete
+  multi-account disk vault lands with the boot layer. The credential command
+  compiles and is unit-tested against an in-memory stand-in.
+
+Port notes
+----------
+- TS optional-absent fields become explicit ``None`` defaults; TS readonly
+  arrays become tuples on the frozen dataclasses.
+- ``OAuthCredentials`` was imported from ``indusagi/ai`` in TS. The Python
+  framework has no provider-object OAuth surface (its primitives live in
+  :mod:`indusagi.llmgateway.credentials.oauth` and speak ``OAuthTokens``), so
+  the credential shape the *vault* stores is declared here, app-owned, with
+  the TS field names (``access`` / ``refresh`` / ``expires``). The launch
+  OAuth adapter (:mod:`.oauth`) maps framework tokens into this shape.
+- Field names are the mechanical snake_case renames of the TS members
+  (``appendSystem`` → ``append_system``, ``noTools`` → ``no_tools``); the
+  loose flag bag keeps the TS canonical *flag-name* keys verbatim
+  (``"append-system"``, ``"no-tools"``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Final, Literal, Protocol, TypeAlias
+
+from indusagi.agent import SessionInfo
+from indusagi.ai import ImageContent, ThinkingLevel
+from indusagi.shell_app import Settings
+
+__all__ = [
+    "AttachmentOptions",
+    "Attachments",
+    "AuthVault",
+    "CatalogFilter",
+    "CredentialFault",
+    "CredentialFaultKind",
+    "CredentialVerb",
+    "FlagDefault",
+    "FlagKind",
+    "FlagSpec",
+    "FlagValue",
+    "ImageContent",
+    "Invocation",
+    "OAuthCredentials",
+    "OutputMode",
+    "ProviderEntry",
+    "ResumeFault",
+    "ResumeRef",
+    "SessionLoader",
+    "Settings",
+    "SettingsBrowseOptions",
+    "THINKING_EFFORTS",
+    "TOOL_NAMES",
+    "ThinkingEffort",
+    "ThinkingLevel",
+    "ToolName",
+    "credential_fault",
+    "is_output_mode",
+    "is_thinking_effort",
+    "is_tool_name",
+]
+
+
+# ---------------------------------------------------------------------------
+# Re-exported framework vocabulary
+# ---------------------------------------------------------------------------
+
+#: The launch-local alias for the framework session descriptor surfaced by the
+#: resume picker (TS aliased ``SessionInfo as ResumeRef``).
+ResumeRef: TypeAlias = SessionInfo
+
+
+# ---------------------------------------------------------------------------
+# Output modes
+# ---------------------------------------------------------------------------
+
+#: The three terminal output modes the launch layer can resolve to. These map
+#: one-to-one onto the boot runner ids the orchestrator dispatches on:
+#:
+#: - ``text`` — interactive terminal or a single human-readable answer.
+#: - ``json`` — a single non-interactive request whose result is structured.
+#: - ``rpc``  — the headless line protocol for a driving parent process.
+#:
+#: ``text`` is the interactive default; ``json`` is selected by ``--print``
+#: (without the interactive override), and ``rpc`` by ``--json`` / ``--rpc``.
+OutputMode: TypeAlias = Literal["text", "json", "rpc"]
+
+
+def is_output_mode(value: str) -> bool:
+    """Narrow an arbitrary string to an :data:`OutputMode`."""
+    return value == "text" or value == "json" or value == "rpc"
+
+
+# ---------------------------------------------------------------------------
+# Reasoning effort
+# ---------------------------------------------------------------------------
+
+#: One reasoning-effort rung from :data:`THINKING_EFFORTS`.
+ThinkingEffort: TypeAlias = Literal["off", "minimal", "low", "medium", "high", "xhigh"]
+
+#: The ordered reasoning-effort vocabulary accepted by ``--thinking``. ``off``
+#: disables extended reasoning entirely; the remaining rungs ascend in effort.
+#: Ordered so the usage text can enumerate it and :func:`is_thinking_effort`
+#: can validate against it without a second list. It is a superset-compatible
+#: widening of the framework :data:`~indusagi.ai.ThinkingLevel` (which omits
+#: ``off``); callers that hand a level to the framework drop ``off``.
+THINKING_EFFORTS: Final[tuple[ThinkingEffort, ...]] = (
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+)
+
+
+def is_thinking_effort(value: str) -> bool:
+    """Pure membership test against :data:`THINKING_EFFORTS`; the model
+    resolver reuses it to parse the ``model:effort`` shorthand without
+    importing the parser."""
+    return value in THINKING_EFFORTS
+
+
+# ---------------------------------------------------------------------------
+# Tool roster
+# ---------------------------------------------------------------------------
+
+#: One built-in tool identifier from :data:`TOOL_NAMES`.
+ToolName: TypeAlias = Literal[
+    "read",
+    "write",
+    "edit",
+    "bash",
+    "grep",
+    "find",
+    "ls",
+    "task",
+    "todo_read",
+    "todo_write",
+    "web_fetch",
+    "web_search",
+    "composio",
+]
+
+#: The closed roster of built-in tool names the ``--tools`` / ``--no-tools``
+#: flags select against. A literal tuple (rather than the live tool map) so
+#: the launch layer can validate a ``--tools`` list before any tool module is
+#: constructed.
+TOOL_NAMES: Final[tuple[ToolName, ...]] = (
+    "read",
+    "write",
+    "edit",
+    "bash",
+    "grep",
+    "find",
+    "ls",
+    "task",
+    "todo_read",
+    "todo_write",
+    "web_fetch",
+    "web_search",
+    "composio",
+)
+
+
+def is_tool_name(value: str) -> bool:
+    """Narrow an arbitrary string to a known :data:`ToolName`."""
+    return value in TOOL_NAMES
+
+
+# ---------------------------------------------------------------------------
+# Declarative flag table
+# ---------------------------------------------------------------------------
+
+#: The value vocabulary a flag binds to its target field.
+#:
+#: - ``boolean`` — a bare switch; presence sets it true (e.g. ``--print``).
+#: - ``string``  — consumes the following token as text (e.g. ``--model``).
+#: - ``number``  — consumes the following token and coerces to a number.
+#: - ``list``    — accumulates; either repeated or one comma-separated token
+#:   (e.g. ``--mcp a --mcp b``, or ``--tools read,bash``).
+FlagKind: TypeAlias = Literal["boolean", "string", "number", "list"]
+
+#: The default value attached to a :class:`FlagSpec`, narrowed by
+#: :data:`FlagKind`: a boolean default for switches, a string for value flags,
+#: a number for numeric flags, and a string tuple for lists.
+FlagDefault: TypeAlias = bool | str | float | tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class FlagSpec:
+    """One row of the single declarative flag table.
+
+    Every recognised option is described here exactly once. The reader indexes
+    the table by :attr:`name` and :attr:`aliases` to bind tokens to
+    :attr:`Invocation.flags`; the usage generator walks the same rows to render
+    the option reference. There is no second source of truth for either side.
+    """
+
+    # Canonical long spelling, leading dashes included (e.g. "--model"). This
+    # is also the key the parsed value lands under in Invocation.flags, sans
+    # the leading dashes.
+    name: str
+    # The value vocabulary this flag binds (see FlagKind).
+    kind: FlagKind
+    # One-line description rendered verbatim in the generated usage text.
+    describe: str
+    # Accepted alternate spellings — short forms ("-m") and synonyms ("--rpc"
+    # for "--json"). All alias hits normalise to `name`.
+    aliases: tuple[str, ...] = ()
+    # Optional default folded into Invocation.flags when the flag is absent.
+    # Its runtime type must match `kind`.
+    default: FlagDefault | None = None
+
+
+# ---------------------------------------------------------------------------
+# Invocation
+# ---------------------------------------------------------------------------
+
+#: The runtime value a parsed flag can carry in :attr:`Invocation.flags`: a
+#: boolean switch, a scalar value, a numeric value, or an accumulated list.
+FlagValue: TypeAlias = bool | str | float | list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class Invocation:
+    """The fully parsed command line — the launch layer's enrichment of the
+    thin boot routing shape into the complete, strongly-typed surface the
+    runtime reads.
+
+    The first four members (:attr:`mode`, :attr:`prompt`, :attr:`flags`,
+    :attr:`positionals`) are the superset of the boot-layer minimal invocation
+    (``positionals`` is the renamed ``rest``); everything below is the
+    resolved launch configuration. :attr:`flags` retains the loosely-typed bag
+    for extension flags and round-tripping, while the named fields give
+    consumers a precise, pre-coerced view of the options that matter to the
+    runtime. Treat every field as read-only.
+    """
+
+    # Resolved terminal output mode; selects the boot runner.
+    mode: OutputMode
+    # All parsed switches, keyed by canonical flag name (extension-flag escape
+    # hatch).
+    flags: Mapping[str, FlagValue]
+    # Positional tokens not consumed as flags (the boot layer's `rest`).
+    positionals: tuple[str, ...]
+    # First user message assembled from positionals, stdin, and attachments.
+    prompt: str | None = None
+    # `@file` arguments expanded to inline prose plus base64 media, if any.
+    attachments: Attachments | None = None
+    # Explicit model selector (--model / -m), provider-qualified or bare.
+    model: str | None = None
+    # Named credential account to authenticate the run with (--account).
+    account: str | None = None
+    # Working directory the run is scoped to (--cwd); None means process cwd.
+    cwd: str | None = None
+    # Replacement system prompt (--system); None keeps the built-in.
+    system: str | None = None
+    # Extra text appended after the system prompt (--append-system).
+    append_system: str | None = None
+    # Reasoning-effort rung requested via --thinking.
+    thinking: ThinkingEffort | None = None
+    # Explicit tool allow-list (--tools); None means every built-in tool.
+    tools: tuple[ToolName, ...] | None = None
+    # Disable all tools for this run (--no-tools).
+    no_tools: bool = False
+    # External MCP server endpoints to attach (--mcp, repeatable/comma-joined).
+    mcp: tuple[str, ...] = ()
+    # Run a single request and exit, printing only the result (--print / -p).
+    print: bool = False
+    # Force the interactive REPL even alongside a prompt (--interactive / -i).
+    interactive: bool = False
+    # Asking for the usage banner (--help / -h).
+    help: bool = False
+    # Asking for the version string (--version / -v).
+    version: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Attachments
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Attachments:
+    """The result of expanding the ``@file`` arguments collected on the
+    command line.
+
+    Text files are inlined into :attr:`prose` (each wrapped in a delimited
+    block keyed by its path); image files are decoded to framework
+    :class:`~indusagi.ai.ImageContent` and collected in :attr:`media`. Both
+    are concatenated onto the first user message. An invocation with no
+    ``@file`` arguments has no :class:`Attachments` at all rather than an
+    empty one.
+    """
+
+    # Concatenated text of every inlined file, each wrapped with its path.
+    prose: str
+    # Base64 image content decoded from every image @file argument.
+    media: tuple[ImageContent, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class AttachmentOptions:
+    """Options for :func:`~.invocation.gather_attachments`: the cwd that
+    ``@file`` references are resolved against."""
+
+    # Working directory @file references are resolved relative to.
+    cwd: str
+
+
+# ---------------------------------------------------------------------------
+# Credential command
+# ---------------------------------------------------------------------------
+
+#: The two verbs the credential command recognises as the first positional
+#: token. Anything else means the command does not own this invocation and the
+#: caller proceeds to normal launch.
+#:
+#: - ``signin``  — validate and store a credential for a provider / account.
+#: - ``signout`` — remove a stored credential for a provider / account.
+CredentialVerb: TypeAlias = Literal["signin", "signout"]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderEntry:
+    """A provider entry in the credential directory — the facts the sign-in
+    prompts print and validate against. :attr:`env_key` is the conventional
+    environment variable :func:`indusagi.ai.get_env_api_key` reads;
+    :attr:`docs_url` is where the user obtains a key. These are external
+    provider conventions, not derived data."""
+
+    # Stable provider id matching the framework provider vocabulary.
+    id: str
+    # Human-facing provider label for menus and prompts.
+    label: str
+    # Conventional api-key environment variable for this provider.
+    env_key: str
+    # Page where a user obtains an api key for this provider.
+    docs_url: str
+
+
+#: The closed set of failure categories the credential command can raise.
+#: A consumer switches on :attr:`CredentialFault.kind`, never on message text:
+#:
+#: - ``unknown-provider`` — the named provider is not in the directory.
+#: - ``invalid-key``      — the supplied key failed format validation.
+#: - ``invalid-account``  — the account name failed the naming rules.
+#: - ``name-collision``   — the account name already exists for the provider.
+#: - ``not-found``        — sign-out targeted a credential not stored.
+#: - ``vault``            — the underlying credential store failed.
+#: - ``aborted``          — the user cancelled an interactive prompt.
+CredentialFaultKind: TypeAlias = Literal[
+    "unknown-provider",
+    "invalid-key",
+    "invalid-account",
+    "name-collision",
+    "not-found",
+    "vault",
+    "aborted",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialFault:
+    """A typed credential failure. :attr:`kind` drives recovery; :attr:`hint`
+    carries a single actionable next step for the human (e.g. the env-var to
+    set), and :attr:`cause` preserves any wrapped error for diagnostics."""
+
+    # The failure category (the discriminant).
+    kind: CredentialFaultKind
+    # Human-readable summary of what failed.
+    message: str
+    # Optional single actionable suggestion for resolving the fault.
+    hint: str | None = None
+    # Optional wrapped underlying error.
+    cause: object | None = None
+
+
+def credential_fault(
+    kind: CredentialFaultKind,
+    message: str,
+    *,
+    hint: str | None = None,
+    cause: object | None = None,
+) -> CredentialFault:
+    """Construct a :class:`CredentialFault`. A tiny inert helper so call sites
+    raise a well-formed typed fault without re-spelling the shape."""
+    return CredentialFault(kind=kind, message=message, hint=hint, cause=cause)
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthCredentials:
+    """Browser-sign-in credentials as the *vault* stores them (the TS
+    ``indusagi/ai`` ``OAuthCredentials`` shape, app-owned in the port — see
+    the module docstring). ``expires`` is an absolute epoch-millisecond
+    deadline, matching the framework's ``OAuthTokens.expires_at``."""
+
+    # The live access token.
+    access: str
+    # The refresh token, when the provider issued one.
+    refresh: str | None = None
+    # Absolute epoch-millisecond expiry deadline, when known.
+    expires: int | None = None
+
+
+class AuthVault(Protocol):
+    """The credential-vault surface the credential command depends on.
+
+    The framework publishes no credential-store type, so the launch contract
+    forward-declares the slice it needs: per-provider, per-account records
+    keyed by an account name. A record stores *either* an api key or a set of
+    browser-sign-in credentials; the vault refreshes an expired browser token
+    before yielding a usable key. The boot layer supplies the concrete
+    multi-account disk vault; this Protocol lets the credential command be
+    unit-tested against an in-memory stand-in before then.
+    """
+
+    async def list_accounts(self, provider: str) -> list[str]:
+        """Stored account names for a provider, in insertion order."""
+        ...
+
+    async def default_account(self, provider: str) -> str | None:
+        """The default account name for a provider, if one is set."""
+        ...
+
+    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
+        default."""
+        ...
+
+    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 default."""
+        ...
+
+    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."""
+        ...
+
+    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 is refreshed
+        (persisting any rotated token) before its usable key is returned.
+        Resolves ``None`` when nothing usable is stored."""
+        ...
+
+    async def remove(self, provider: str, account: str | None = None) -> bool:
+        """Remove a stored credential; resolves False when nothing was
+        removed."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Model catalog
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogFilter:
+    """The filter applied when rendering the ``--list-models`` table. Every
+    field is optional; an absent field matches everything. :attr:`search` is a
+    plain case-insensitive substring test over the provider/model identifier —
+    no fuzzy matcher and no external ranking."""
+
+    # Restrict to a single provider id.
+    provider: str | None = None
+    # Keep only models that advertise a reasoning budget.
+    thinking_only: bool | None = None
+    # Keep only models that accept image input.
+    images_only: bool | None = None
+    # Case-insensitive substring filter over the model identifier.
+    search: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Resume picker
+# ---------------------------------------------------------------------------
+
+#: A function that loads a set of resumable sessions. The resume picker takes
+#: two: one for the current working directory and one for every directory,
+#: both shaped like the framework session lister.
+SessionLoader: TypeAlias = Callable[[], Awaitable[Sequence[ResumeRef]]]
+
+
+@dataclass(frozen=True, slots=True)
+class ResumeFault:
+    """A launch-time error from the resume flow (the picker failing to mount,
+    or a session store read fault). Typed so the orchestrator can fall back
+    to a fresh session rather than crash."""
+
+    # Human-readable summary of what failed.
+    message: str
+    # Optional wrapped underlying error.
+    cause: object | None = None
+
+
+# ---------------------------------------------------------------------------
+# Settings browser
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsBrowseOptions:
+    """Options for :func:`~.pickers.browse_settings`: the resolved framework
+    settings, the directories of user-authored resources to enumerate, the
+    active cwd, and the profile directory. The browser renders a plain console
+    listing of these — no TUI."""
+
+    # The merged, resolved framework settings.
+    settings: Settings
+    # Resolved absolute paths of discovered resources, grouped by category.
+    resolved_paths: Mapping[str, Sequence[str]]
+    # The active working directory.
+    cwd: str
+    # The profile directory the settings were loaded from.
+    profile_dir: str
+
+
+# Quiet "imported but unused" for the re-exported framework names: they are
+# part of this contract's public surface (`__all__`).
+_REEXPORTS: Final[tuple[Any, ...]] = (ImageContent, ThinkingLevel, Settings, SessionInfo)