tool_results.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/tool_results.py
 
"""
TypedDict shapes for tool return values (CONTRACTS.md §4).
 
Purpose
-------
Every public tool function returns a JSON-serialisable ``dict`` — but
until now those dicts were typed only as ``dict`` or ``dict[str, Any]``,
leaving callers (the ReAct loop, the dependency healer, the presenter)
without static guarantees about which keys exist. This module gives
each conventional shape a TypedDict so callers and tool authors share
a single source of truth.
 
These are plain TypedDicts — at runtime they are still ``dict``s, so
no behavior changes. Annotations only.
 
Responsibilities
----------------
- :class:`CommandResult` — shell / subprocess output
  (``run_command``, all ``oct_*`` tools).
- :class:`ReadFileResult` — successful ``read_file`` payload.
- :class:`WriteFileResult` — successful ``write_file`` payload.
- :class:`ToolError` — the universal ``{"error": "..."}`` fallback.
- :class:`ConfirmationRequired` — Tier-2 gating prompt returned by
  destructive tools before the user has confirmed.
- :class:`MissingDependency` — structured hint emitted when a tool's
  optional dependency (httpx, oct binary, etc.) is not installed; the
  :mod:`~oc_chat.core.dependency_healer` watches for these.
- :data:`ToolReturn` — the union; the return type for tool dispatch.
 
Diagnostics
-----------
Domain: OC_CHAT.TOOLS
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Every TypedDict here mirrors a return shape currently produced by an
  existing tool. The classes themselves carry no validation logic — at
  runtime the underlying ``dict`` may still have extra keys (TypedDicts
  are structural).
- ``total=False`` is used wherever a key is conditionally present at
  runtime. Required keys are kept required.
- Consumers should branch on key presence (e.g. ``"error" in result``)
  rather than ``isinstance`` checks; TypedDict isinstance is a
  type-checker-only construct.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
from typing import Any, NotRequired, TypedDict, Union
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.TOOLS", "module", "loaded", 4)
 
 
class CommandResult(TypedDict, total=False):
    """Result of a subprocess invocation (run_command, oct_* tools).
 
    Required on success: ``stdout``, ``stderr``, ``returncode``.
    Optional metadata: ``command_info`` (run_command only), ``warnings``
    (run_command only).
    """
 
    stdout: str
    stderr: str
    returncode: int
    command_info: dict[str, Any]
    warnings: list[str]
 
 
class ReadFileResult(TypedDict):
    """Successful ``read_file`` return shape.
 
    ``next_offset`` is ``None`` when the file is fully read; otherwise
    it is the byte offset to pass to a follow-up
    ``read_file(path, offset=N)`` call.
 
    ``path`` is the RESOLVED absolute path actually read — model-independent
    ground truth (plan 172 / F13/F25). When the discovery fallback rescued a
    different path than the one requested, ``resolved_via_discovery`` is ``True``
    and ``requested_path`` carries the original argument, so a silent rescue is
    visible instead of masking a wrong path.
    """
 
    content: str
    truncated: bool
    total_size: int
    offset: int
    next_offset: int | None
    lines_count: int
    path: NotRequired[str]
    resolved_via_discovery: NotRequired[bool]
    requested_path: NotRequired[str]
 
 
class WriteFileResult(TypedDict):
    """Successful ``write_file`` return shape.
 
    ``redirected`` is true when the tool re-routed the write to a safer
    path (e.g. ``logs/<name>`` for protected directories); ``actual_path``
    is then the path actually written. ``chunks`` is non-empty when the
    write was split (``chunked=True``).
    """
 
    written: str
    original_path: str
    redirected: bool
    actual_path: str
    size_bytes: int
    timestamp: str
    chunked: bool
    chunks: list[dict[str, Any]]
 
 
class ToolError(TypedDict):
    """Universal error fallback: ``{"error": "<human-readable message>"}``.
 
    Returned by any tool that can fail before producing a typed success
    payload. Callers should detect failures by ``"error" in result``
    (not by absence of success keys).
    """
 
    error: str
 
 
class ConfirmationRequired(TypedDict):
    """Tier-2 gating prompt from destructive tools (e.g. ``rm``, ``mv``).
 
    Emitted by :func:`~oc_chat.tools.shell.run_command` and similar
    callers when a sensitive command would proceed without explicit
    user confirmation. Callers re-invoke with ``confirmed=True``.
    """
 
    requires_confirmation: bool
    command: str
    message: str
 
 
class MissingDependency(TypedDict):
    """Signal that a tool's optional dependency is not installed.
 
    Consumed by :mod:`~oc_chat.core.dependency_healer`, which offers to
    install the dependency on the user's behalf. ``missing_dependency``
    is the package name; ``install_hint`` is a copy-pasteable pip
    command.
    """
 
    missing_dependency: str
    install_hint: str
 
 
ToolReturn = Union[
    CommandResult,
    ReadFileResult,
    WriteFileResult,
    ToolError,
    ConfirmationRequired,
    MissingDependency,
]
"""Union of every conventional tool return shape.
 
Tool functions whose success shape is none of the six (e.g.
``list_dir``, ``text_search``, ``fetch_url``) declare their own
TypedDict locally or remain ``dict[str, Any]`` — they are
single-purpose and do not need the six-way union.
"""
 
 
__all__ = [
    "CommandResult",
    "ReadFileResult",
    "WriteFileResult",
    "ToolError",
    "ConfirmationRequired",
    "MissingDependency",
    "ToolReturn",
]