|
oc_chat
|
Functions | |
| Optional[str] | _oct_exe () |
| "Callable[[str], None]" | _note_activity_lines_of_one_stream () |
| _OctResult | _run_oct (list[str] args, str cwd, int timeout=60) |
| "ToolError | None" | _reject_operand (str value, str field) |
| "ToolError | None" | _reject_operands ("list[str]" values, str field) |
| _OctResult | oct_lint (str path=".", bool fix_headers=False, bool dry_run=False, bool json_output=False, bool changed_only=False, int timeout=120) |
| _OctResult | oct_health (bool json_output=False, bool verbose=False, int timeout=300) |
| _OctResult | oct_typecheck (bool json_output=False, int timeout=120) |
| _OctResult | oct_new (str path, bool force=False, bool test=False, bool dry_run=False, bool verbose=False, int timeout=30) |
| dict | oct_test (str profile="strict", "int | None" seed=None, "int | str | None" workers=None, "str | None" marker=None, "list[str] | None" nodeids=None, bool dry_run=False, "int | None" per_test_timeout=None, int timeout=900) |
| _OctResult | oct_git_status (bool json_output=False, bool no_check=False, Optional[str] scope=None, int timeout=30) |
| _OctResult | oct_git_check (bool staged_only=False, bool all_files=False, bool include_tests=False, bool fix=False, Optional[str] profile=None, bool json_output=False, bool sandbox=False, int timeout=120) |
| _OctResult | oct_git_init (bool dry_run=False, bool github=False, bool no_hooks=False, int timeout=60) |
| _OctResult | oct_git_add (Optional[list[str]] paths=None, bool patch=False, bool update=False, bool all_files=False, bool dry_run=False, bool json_output=False, int timeout=60) |
| _OctResult | oct_git_commit (list[str] message, bool force=False, bool no_verify=False, Optional[str] profile=None, bool json_output=False, bool ignore_unstaged_mutation=False, int timeout=180) |
| _OctResult | oct_git_branch (Optional[str] create=None, Optional[str] switch=None, bool json_output=False, int timeout=30) |
| _OctResult | oct_git_restore (Optional[list[str]] paths=None, bool staged=False, bool all_files=False, bool yes=False, bool json_output=False, int timeout=30) |
| _OctResult | oct_git_ignore (Optional[list[str]] patterns=None, Optional[str] remove=None, bool list_patterns=False, Optional[str] scope=None, bool json_output=False, int timeout=30) |
| _OctResult | oct_git_commit_msg (str message_file, bool json_output=False, int timeout=30) |
| _OctResult | oct_git_changelog (Optional[str] release=None, Optional[str] since=None, bool dry_run=False, bool json_output=False, int timeout=60) |
| _OctResult | oct_git_hooks (str action, bool force=False, int timeout=30) |
Variables | |
| _OctResult = CommandResult | MissingDependency | ToolError | |
| _OC_CHAT_SUBPROJECT_ROOT = Path(__file__).resolve().parents[2] | |
| int | _OCT_TEST_TIMEOUT_CAP = 1800 |
| int | _OCT_TEST_NON_PASSED_CAP = 50 |
| dict | TOOLS |
| list | SCHEMAS |
oct toolchain integration — lint, health, typecheck, file generator, and git suite.
Purpose
-------
Wraps the ``oct`` CLI (Option C Tools) as callable agent tools so the
model can run ``oct lint``, ``oct health``, ``oct typecheck``,
``oct new``, and the full ``oct git`` subcommand suite (status, check,
init, add, commit, branch, restore, ignore, commit-msg, changelog,
hooks) inside a session.
The ``oct_git_*`` wrappers are the agent's only path to mutating git
operations — raw ``git add`` / ``git commit`` / ``git push`` are
blocked by ``oc_chat/tools/shell.py``'s whitelist, so every agent-
driven commit goes through the Option C quality gate (lint + format
+ secrets) by construction.
Requires: ``pip install -e .[option_c]`` (wires the sibling ``oct``
package). Returns ``{"missing_dependency": ...}`` when ``oct`` is not
installed, which the dependency healer can intercept and offer to
repair.
Responsibilities
----------------
- :func:`_oct_exe` / :func:`_run_oct` — locate the binary and invoke
it with timeout/cwd controls.
- :func:`_note_activity_lines_of_one_stream` — build the per-stream
status-bar observer, redaction and private-key armor state included.
- :func:`oct_lint`, :func:`oct_health`, :func:`oct_typecheck`,
:func:`oct_new` — first-class agent tools (F.2a-i through iv).
- :func:`oct_test` — the Plan-187 consumer of the Plan-184 §20 test
stand-in (``python -m oc_chat.testing``): a subprocess run returning
a distilled ``oct-test/v0.4`` payload (closes F1). Unlike the oct
passthrough wrappers it spawns ``sys.executable``, pins cwd to the
oc_chat SUBPROJECT root (the stand-in's ADR-T-12 walk anchor), and
returns the distilled report rather than ``CommandResult``.
- :func:`oct_git_*` — 11 wrappers around the ``oct git`` subcommand
surface (F.2a-v).
- ``TOOLS`` and ``SCHEMAS`` exports for auto-registration.
Diagnostics
-----------
Domain: OC_CHAT.TOOLS
Levels:
L2 — lifecycle events
L3 — semantic details
L4 — deep tracing
Contracts
---------
- All wrappers are pass-throughs — the schemas and arg parsing live
here, but the actual quality logic lives in ``oct``.
- Missing-binary returns are *structured* (``missing_dependency``)
rather than raising, so the healer can offer to install.
- ``cwd`` is pinned to the effective sandbox root (:func:`oc_chat.tools.filesystem._sandbox_root`) so behaviour
is independent of the user's shell CWD — except :func:`oct_test`,
whose cwd is the oc_chat SUBPROJECT root (the stand-in's discovery
anchor); only its report file uses the sandbox root.
- Every subprocess call honours an explicit ``timeout`` — defaults
are conservative and tunable per-tool.
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.tool_results (CommandResult, MissingDependency and ToolError - the wrappers' result shapes)
- oc_chat.tools.filesystem (_sandbox_root for the pinned cwd and report directory, and the oct_new write-approval gate)
- oc_chat.core.tool_activity (lazy; TOOL_ACTIVITY - the status-bar record each redacted output line is noted on)
- oc_chat.tools._proc (lazy; run_cancellable - the cancellable oct and stand-in subprocesses)
- oc_chat.tools._sandbox (lazy; scrubbed_env, LineRedactor and the write-path checks - the child environment, status-bar redaction and the oct_new gate)
- oct (not imported; the oct CLI found on PATH and run as a subprocess by every wrapper except oct_test)
- oc_chat.testing (not imported; run as python -m oc_chat.testing by oct_test)
See Also
--------
oc_chat/docs/conventions/CONTRACTS.md §3 Tool registry contract; §4 Tool return-
value conventions (oct_* outputs → §4.1; missing-dep hint → §4.6).
|
protected |
Return the observer that shows ONE stream's lines on the status bar. Each line is redacted with the same filter ``run_command`` applies to its result, even though these wrappers return ``result.stdout`` unredacted: what the terminal shows is a different surface from what the tool returns, and the one that is on screen for anyone walking past is the one worth filtering (plan 279). Terminal-only — nothing here reaches the result, the events, the session or the model. One :class:`~oc_chat.tools._sandbox.LineRedactor` per call of this factory, and the runner calls it once per pipe (plan 287), so the private-key armor state the filter carries between lines is this stream's and no other's.
Definition at line 109 of file oct_tools.py.
|
protected |
Return the path to the ``oct`` executable, or ``None`` if absent.
Definition at line 104 of file oct_tools.py.
|
protected |
Refuse a model-supplied oct/git operand that could smuggle an option into the argv (M8.0 WU-3 oct parity / argv-injection guard). The ``oct_*`` wrappers forward model-controlled path / pattern / identifier operands as positional args or option *values* -- never as options. A leading ``-`` would be reparsed by the oct/git argument parser as a flag (e.g. ``paths=["--all"]`` -> ``git add --all``; ``path="--help"``). Reject a non-string, empty, control-char-bearing, or leading-dash operand. Returns a ToolError dict to surface, or ``None`` if the operand is safe.
Definition at line 172 of file oct_tools.py.
|
protected |
Apply :func:`_reject_operand` to each value in a list operand.
Definition at line 192 of file oct_tools.py.
|
protected |
Execute ``oct <args>`` and return ``{stdout, stderr, returncode}``.
Definition at line 135 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_add | ( | Optional[list[str]] | paths = None, |
| bool | patch = False, | ||
| bool | update = False, | ||
| bool | all_files = False, | ||
| bool | dry_run = False, | ||
| bool | json_output = False, | ||
| int | timeout = 60 ) |
Stage files for commit, with optional post-stage quality-gate summary.
Preferred over raw ``git add`` because it scopes to the project (vs. the
whole repo) and runs a quality-gate summary on the staged set.
Parameters
----------
paths : list[str] | None
Files / directories to stage.
patch : bool
Interactive hunk-level staging (passthrough to ``git add -p``).
update : bool
Stage all already-tracked modified files.
all_files : bool
Stage all changes (tracked + untracked) within project scope.
dry_run : bool
Show what would be staged without staging.
json_output : bool
Machine-readable JSON output.
timeout : int
Seconds before the subprocess is killed (default 60).
Definition at line 667 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_branch | ( | Optional[str] | create = None, |
| Optional[str] | switch = None, | ||
| bool | json_output = False, | ||
| int | timeout = 30 ) |
Create or switch branches with Option C naming enforcement.
Preferred over raw ``git branch`` / ``git checkout -b`` because it
enforces the project's branch-naming convention (``feat/``, ``fix/``,
``chore/`` prefixes).
Pass exactly one of ``create`` or ``switch``.
Parameters
----------
create : str | None
Create a new branch from HEAD with this name.
switch : str | None
Switch to an existing branch with this name.
json_output : bool
Machine-readable JSON output.
timeout : int
Seconds before the subprocess is killed (default 30).
Definition at line 772 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_changelog | ( | Optional[str] | release = None, |
| Optional[str] | since = None, | ||
| bool | dry_run = False, | ||
| bool | json_output = False, | ||
| int | timeout = 60 ) |
Generate a changelog from Conventional Commits history.
Preferred over hand-writing ``CHANGELOG.md`` entries because output is
aligned with Option C's CHANGELOG-format spec.
Parameters
----------
release : str | None
Release version tag (e.g. ``"v0.13.0"``). When set (and not
``dry_run``), writes/appends to ``CHANGELOG.md``.
since : str | None
Git ref to start from (default: last tag).
dry_run : bool
Print to stdout without writing.
json_output : bool
Machine-readable JSON output.
timeout : int
Seconds before the subprocess is killed (default 60).
Definition at line 947 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_check | ( | bool | staged_only = False, |
| bool | all_files = False, | ||
| bool | include_tests = False, | ||
| bool | fix = False, | ||
| Optional[str] | profile = None, | ||
| bool | json_output = False, | ||
| bool | sandbox = False, | ||
| int | timeout = 120 ) |
Run the unified Option C quality gate (lint + format + secrets).
Preferred over running ``oct lint`` and ``oct format`` separately
because it bundles secrets scanning and applies the same gate that
``oct git commit`` enforces.
Parameters
----------
staged_only : bool
Check only staged files (default scope).
all_files : bool
Check every Python file in the project.
include_tests : bool
Also run pytest (exit 4 on failure).
fix : bool
Attempt auto-fix of lint/format violations, then re-check.
profile : str | None
Override lint profile: ``"proto"``, ``"compact"``, or ``"strict"``.
json_output : bool
Machine-readable JSON output.
sandbox : bool
Run pytest under MCP sandbox (strips PYTHONPATH and secret env vars).
timeout : int
Seconds before the subprocess is killed (default 120).
Definition at line 576 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_commit | ( | list[str] | message, |
| bool | force = False, | ||
| bool | no_verify = False, | ||
| Optional[str] | profile = None, | ||
| bool | json_output = False, | ||
| bool | ignore_unstaged_mutation = False, | ||
| int | timeout = 180 ) |
Commit staged changes with the Option C quality gate enforced.
Preferred over raw ``git commit`` because the quality gate (lint +
format + secrets) runs before the commit; secrets detection is
non-bypassable even with ``force=True``.
Parameters
----------
message : list[str]
One or more commit message paragraphs (each becomes a ``-m TEXT``).
Required. Must follow Conventional Commits format.
force : bool
Skip lint/format checks (secrets still enforced).
no_verify : bool
Forward ``--no-verify`` to ``git commit`` (skips git hooks; does
NOT skip oct's quality checks).
profile : str | None
Override lint profile: ``"proto"``, ``"compact"``, or ``"strict"``.
json_output : bool
Machine-readable JSON output.
ignore_unstaged_mutation : bool
Downgrade unstaged-tracked-file mutation detection from block to warn.
timeout : int
Seconds before the subprocess is killed (default 180).
Definition at line 718 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_commit_msg | ( | str | message_file, |
| bool | json_output = False, | ||
| int | timeout = 30 ) |
Validate a Conventional Commit message file.
Intended as the entry for the ``commit-msg`` pre-commit-framework
stage. Preferred over hand-rolled regex validation because it matches
exactly what ``oct git commit`` enforces.
Parameters
----------
message_file : str
Path to the commit-message file (e.g. ``.git/COMMIT_EDITMSG``).
json_output : bool
Machine-readable JSON output.
timeout : int
Seconds before the subprocess is killed (default 30).
Definition at line 917 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_hooks | ( | str | action, |
| bool | force = False, | ||
| int | timeout = 30 ) |
Manage Option C pre-commit hooks (install / status / remove).
Preferred over hand-editing ``.pre-commit-config.yaml`` because it
installs the canonical Option C hook set and preserves any non-OCT
hooks already present.
Parameters
----------
action : str
One of ``"install"``, ``"status"``, or ``"remove"``.
force : bool
For ``action="install"``: overwrite existing configuration.
timeout : int
Seconds before the subprocess is killed (default 30).
Definition at line 992 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_ignore | ( | Optional[list[str]] | patterns = None, |
| Optional[str] | remove = None, | ||
| bool | list_patterns = False, | ||
| Optional[str] | scope = None, | ||
| bool | json_output = False, | ||
| int | timeout = 30 ) |
Manage ``.gitignore`` patterns within the OCT-managed block.
Preferred over manually editing ``.gitignore`` because OCT manages a
delimited block that survives ``oct git init`` re-runs.
Pass exactly one of ``patterns``, ``remove``, or ``list_patterns``.
Parameters
----------
patterns : list[str] | None
Patterns to add to ``.gitignore``.
remove : str | None
Pattern to remove from the OCT-managed block.
list_patterns : bool
List currently active ignore patterns.
scope : str | None
Which ``.gitignore`` to target: ``"workspace"``, ``"project"``,
or ``"nearest"`` (default).
json_output : bool
Machine-readable JSON output.
timeout : int
Seconds before the subprocess is killed (default 30).
Definition at line 862 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_init | ( | bool | dry_run = False, |
| bool | github = False, | ||
| bool | no_hooks = False, | ||
| int | timeout = 60 ) |
Initialize / enhance a git repo with Option C conventions.
Preferred over manually editing ``.gitignore`` / ``.gitattributes`` /
``.pre-commit-config.yaml`` because it applies the canonical Option C
templates and merges idempotently.
Parameters
----------
dry_run : bool
Show what would be created/modified without writing.
github : bool
Also generate ``.github/workflows/option-c.yml``.
no_hooks : bool
Skip ``.pre-commit-config.yaml`` creation.
timeout : int
Seconds before the subprocess is killed (default 60).
Definition at line 633 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_restore | ( | Optional[list[str]] | paths = None, |
| bool | staged = False, | ||
| bool | all_files = False, | ||
| bool | yes = False, | ||
| bool | json_output = False, | ||
| int | timeout = 30 ) |
Restore working-tree edits or unstage paths.
Preferred over raw ``git restore`` / ``git checkout --`` because it
scopes to the project and requires explicit confirmation when
discarding all staged changes.
Parameters
----------
paths : list[str] | None
Files / directories to restore.
staged : bool
Unstage from index (leaves working tree intact). Without this,
discards working-tree edits.
all_files : bool
Restore all in-scope paths (requires ``yes=True`` if also ``staged``).
yes : bool
Skip the confirmation prompt for ``staged=True, all_files=True``.
json_output : bool
Machine-readable JSON output.
timeout : int
Seconds before the subprocess is killed (default 30).
Definition at line 814 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_git_status | ( | bool | json_output = False, |
| bool | no_check = False, | ||
| Optional[str] | scope = None, | ||
| int | timeout = 30 ) |
Show git status with Option C compliance annotations.
Preferred over raw ``git status`` because it annotates each file with
its compliance state (lint/format/secrets) on top of the standard
staged/modified/untracked breakdown.
Parameters
----------
json_output : bool
Machine-readable JSON output.
no_check : bool
Skip compliance annotations (plain status).
scope : str | None
File scope: ``"project"`` (default), ``"repo"``, or ``"auto"``.
timeout : int
Seconds before the subprocess is killed (default 30).
Definition at line 539 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_health | ( | bool | json_output = False, |
| bool | verbose = False, | ||
| int | timeout = 300 ) |
Display the Option C project compliance dashboard.
Parameters
----------
json_output : bool
Machine-readable JSON output.
verbose : bool
Detailed per-file breakdown.
timeout : int
Seconds before the subprocess is killed (default 300).
Definition at line 244 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_lint | ( | str | path = ".", |
| bool | fix_headers = False, | ||
| bool | dry_run = False, | ||
| bool | json_output = False, | ||
| bool | changed_only = False, | ||
| int | timeout = 120 ) |
Run ``oct lint`` on the project or a specific path.
Parameters
----------
path : str
File or directory to lint (default: entire project).
fix_headers : bool
Auto-fix shebang, encoding, and path comment headers.
dry_run : bool
Preview fixes without writing (only meaningful with ``fix_headers``).
json_output : bool
Emit machine-readable JSON instead of human text.
changed_only : bool
Lint only git-modified Python files.
timeout : int
Seconds before the subprocess is killed (default 120).
Definition at line 201 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_new | ( | str | path, |
| bool | force = False, | ||
| bool | test = False, | ||
| bool | dry_run = False, | ||
| bool | verbose = False, | ||
| int | timeout = 30 ) |
Create a new Option C-compliant Python file via ``oct new``.
Generates a file with the mandatory 3-line header block (shebang,
encoding, file identity), ``from oc_diagnostics import _dbg``, and
a complete module docstring skeleton with Purpose, Responsibilities,
Diagnostics, and Contracts sections.
Parameters
----------
path : str
Target file path (required, must end in ``.py``).
force : bool
Overwrite the file if it already exists.
test : bool
Also generate a companion test file in ``tests/``.
dry_run : bool
Preview what would be created without writing anything.
verbose : bool
Print generated file content to stdout.
timeout : int
Seconds before the subprocess is killed (default 30).
Definition at line 289 of file oct_tools.py.
| dict oc_chat.tools.oct_tools.oct_test | ( | str | profile = "strict", |
| "int | None" | seed = None, | ||
| "int | str | None" | workers = None, | ||
| "str | None" | marker = None, | ||
| "list[str] | None" | nodeids = None, | ||
| bool | dry_run = False, | ||
| "int | None" | per_test_timeout = None, | ||
| int | timeout = 900 ) |
Run the oc_chat test suite via the Plan-184 §20 stand-in
(``python -m oc_chat.testing``) and return a distilled
``oct-test/v0.4`` payload.
The FULL report is written to ``<sandbox_root>/logs/oct_test-<run_id>.json``
(``report_path`` in the payload); the payload itself carries the report's
top-level fields MINUS ``tests[]``, PLUS ``non_passed_tests[]`` (every
entry with ``outcome != "passed"``) capped at 50 with explicit
``non_passed_total`` / ``non_passed_truncated`` fields. Stand-in exit
codes (0 passed / 1 failed / 2 contract violation / 4 configuration
error) surface as the payload's ``exit_code`` — structured data, never a
raised error (the family's CommandResult philosophy).
Parameters
----------
profile : str
``strict`` (default) | ``smoke`` | ``full`` — validated by the
stand-in (a bad value returns an exit-4 payload).
seed : int | None
Pin pytest-randomly ordering (``--seed N``); unseeded runs are
order-stable with seed 0 reported.
workers : int | str | None
Forwarded verbatim (``auto`` or a count); the serial stand-in
reports ``workers.actual: 1`` truthfully.
marker : str | None
Extra marker expression, AND-composed with the profile expression.
nodeids : list[str] | None
Individual pytest nodeids (repeatable ``--nodeid``).
dry_run : bool
Collection + static checks only; no test executes.
per_test_timeout : int | None
Per-test wall-clock bound in seconds (stand-in watchdog).
timeout : int
Tool-level wall clock (default 900 s; clamped to [1, 1800]).
Definition at line 377 of file oct_tools.py.
| _OctResult oc_chat.tools.oct_tools.oct_typecheck | ( | bool | json_output = False, |
| int | timeout = 120 ) |
Run type checking on the project via ``oct typecheck``.
Parameters
----------
json_output : bool
Machine-readable JSON summary.
timeout : int
Seconds before the subprocess is killed (default 120).
Definition at line 269 of file oct_tools.py.
|
protected |
Definition at line 363 of file oct_tools.py.
|
protected |
Definition at line 374 of file oct_tools.py.
|
protected |
Definition at line 369 of file oct_tools.py.
|
protected |
Definition at line 101 of file oct_tools.py.
| list oc_chat.tools.oct_tools.SCHEMAS |
Definition at line 1041 of file oct_tools.py.
| dict oc_chat.tools.oct_tools.TOOLS |
Definition at line 1022 of file oct_tools.py.