aihook 0.1.5__tar.gz

aihook-0.1.5/.github/workflows/python-app.yml

@@ -0,0 +1,79 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: CI
+
+on:
+  push:
+    branches:
+    - main
+    - develop
+  pull_request:
+    branches:
+    - main
+    - develop
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    env:
+      # note: 'true' only works if no error occurred.
+      # DEBUG_WITH_SSH: 'true'
+      DEBUG_WITH_SSH: false
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+
+    # we use uv because it is much faster than normal pip
+    - name: Install uv
+      run: |
+        python -m pip install uv
+
+    - name: Installing requirements and package
+      run: |
+        # install this package
+        pwd
+        uv pip install --system -r requirements.txt
+        uv pip install --system -e .
+
+    - name: configure git
+      run: |
+        git config --global user.email "ci-user@ci-server.com"
+        git config --global user.name "CI User"
+        git config --global init.defaultBranch main
+
+    - name: run all tests
+      run: |
+        pytest
+
+
+    # debugging (set env.DEBUG_WITH_SSH to true (see above))
+    - name: Setup tmate session
+      if: env.DEBUG_WITH_SSH == 'true'
+      id: tmate
+      uses: mxschmitt/action-tmate@v3
+      with:
+        detached: true
+
+    # this exports the ad-hoc ssh-connection address to an text file such that it can be accessed via API
+    # this allows to connect to the debugging ssh server without manual copy-pasting
+    # see https://github.com/cknoll/github-ci-ssh-connect
+
+    - name: Capture tmate output
+      if: env.DEBUG_WITH_SSH == 'true'
+      run: |
+          echo $(cat /home/runner/work/_temp/_runner_file_commands/* | grep ::notice::SSH | awk '{print $NF}') > tmate-connection.txt
+
+    - name: Upload tmate logs as artifact
+      if: env.DEBUG_WITH_SSH == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: tmate-connection
+        path: tmate-connection.txt

aihook-0.1.5/.gitignore

@@ -0,0 +1,7 @@
+*.pyc
+*/__pycache__/*
+*/.directory
+.directory
+*/.ipynb_checkpoints/*
+src/*.egg-info/*
+dist

aihook-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Knoll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aihook-0.1.5/MANIFEST.in

@@ -0,0 +1,2 @@
+include requirements.txt
+include src/aihook/SKILL.md

aihook-0.1.5/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: aihook
+Version: 0.1.5
+Summary: interactive embedded shell for agents 
+Author-email: Carsten Knoll <firstname.lastname@domain.org>
+License-Expression: GPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipydex
+Requires-Dist: pytest
+Requires-Dist: PyYAML
+Requires-Dist: platformdirs
+Dynamic: license-file
+
+# aihook
+
+**Pause a running Python script and let an AI agent inspect and manipulate its live state — without restarting.**
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+
+---
+
+## The problem
+
+Some scripts are expensive to restart. A Selenium browser session takes 60 seconds to reach the
+interesting state. An ML pipeline loads a 4 GB model before the first inference. A scraper
+re-authenticates and paginates through 200 pages before getting to the data you care about.
+
+When debugging these scripts, the standard loop — edit, restart, wait, observe — is brutal.
+Each hypothesis costs a full restart.
+
+## What aihook does
+
+Drop one call into your script:
+
+```python
+from aihook import agent_hook
+agent_hook()   # script pauses here; HTTP REPL starts
+```
+
+The script pauses at that line. An HTTP server starts on a free port. The calling frame's
+variables are all live and accessible. An AI agent (or you) can then probe, manipulate, and
+test fixes against the real running state:
+
+```bash
+aihook 'browser.find_by_css(".comment__replies")'
+aihook -f snippet.py        # run a multi-line snippet, edit, repeat
+aihook --exit               # resume the script
+```
+
+Each probe takes 2–5 seconds instead of 60.
+
+---
+
+## Real-world example
+
+This is what a session looks like in practice. The script is a Selenium browser automation that
+was failing silently on every "show replies" button click:
+
+```bash
+# Start the slow script in the background
+python fetch_comments.py --url "https://example.com/article" > aihook-host.log 2>&1 &
+
+# Wait for it to reach agent_hook() — CLI validates pid + port, times out after 180s
+# aihook: session found after 94.3s
+
+# Probe the live DOM
+aihook 'browser.find_by_css("[data-comment-id]")'
+# -> []   ← the attribute does not exist
+
+aihook 'browser.find_by_css("[id^=cid-]")'
+# -> [<Element id="cid-4821">  ...  ]   ← found it
+
+# Try the JS click that works despite the overlay
+aihook -f snippet.py   # snippet tests execute_script("arguments[0].click()", btn)
+# -> reply count went from 8 to 28
+
+aihook --exit
+```
+
+Five probes. Zero restarts. A working script at the end.
+
+---
+
+## Install
+
+```bash
+pip install aihook
+```
+
+### Set up the AI agent skill
+
+For Claude Code:
+```bash
+aihook --bootstrap --agent claude
+```
+
+For aider / aider-desk:
+```bash
+aihook --bootstrap --agent aider
+```
+
+This installs `SKILL.md` (the agent's instruction file for using aihook) and creates a
+`learnings/` directory where agent-accumulated tips are stored across sessions.
+
+---
+
+## CLI reference
+
+| Command | Description |
+|---|---|
+| `aihook '<code>'` | Execute code; single expressions auto-print their `repr()` |
+| `aihook -f FILE` | Send contents of FILE (`-f -` reads from stdin) |
+| `aihook --exit` | Shut down the session and let the script resume |
+| `aihook --status` | Show whether a session is active (exits 0 if healthy) |
+| `aihook --clean` | Remove a stale lock file |
+| `aihook --wait N` | Wait up to N seconds for a healthy session (default: 180s) |
+| `aihook -p PORT` | Target a specific port (skips lock-file discovery) |
+| `aihook --lockfile PATH` | Use a custom lock-file path |
+| `aihook --bootstrap` | Install SKILL.md and create learnings directory |
+
+Exit code is non-zero if the remote code raised an exception or wrote to stderr.
+
+**Auto-print:** if the submitted code is a single expression, its `repr()` is printed
+automatically. For multi-line snippets, use explicit `print()` — auto-print only applies to
+single expressions.
+
+---
+
+## How it works
+
+`agent_hook()` does three things:
+
+1. Captures the calling frame's `globals` and `locals` into a shared namespace.
+2. Starts a minimal HTTP server on a free port in `5001–5101` (configurable).
+3. Writes `./aihook-lock.yml` containing `pid`, `port`, `cwd`, and `start_time`.
+
+The CLI reads the lock file to find the port, POSTs code to `/execute`, and prints the
+result. The server shuts down on `exit()`, the lock file is removed, and the host script
+resumes.
+
+The banner printed on startup includes the source file and line number where `agent_hook()`
+was called — useful when a script has multiple hook points.
+
+---
+
+## One caveat: local variable write-back
+
+Rebinding a **local** variable of the calling function from inside the REPL does **not**
+write back to that function's fast-locals. This is the same limitation as `pdb`:
+
+```python
+# Inside my_function():
+x = 1
+agent_hook()
+print(x)   # still prints 1 even if you did `x = 2` via aihook
+```
+
+**Mutating mutable objects works fine:**
+
+```python
+my_list.append(99)           # visible in the host afterwards
+my_dict["key"] = "new"       # same
+obj.attribute = "changed"    # same
+```
+
+When testing a fix, mutate containers or attributes rather than rebinding local names.
+
+(Of course, this is documented for agents in [SKILL.md](src/aihook/SKILL.md).)
+
+---
+
+## Optional environment variables
+
+| Variable | Effect |
+|---|---|
+| `AIHOOK_PORT=NNNN` | Force a specific port |
+| `AIHOOK_PORT_RANGE=LO-HI` | Override the default `5001-5101` range |
+
+---
+
+## Development
+
+```bash
+git clone <repo-url>
+cd aihook
+pip install -e .
+pytest
+```
+
+The learnings directory (created by `--bootstrap`) accumulates session tips in
+`~/.local/share/aihook/learnings/` (Linux) or the platform equivalent. Add
+`topic_<name>.md` files there to share domain-specific knowledge across agent sessions.

aihook-0.1.5/README.md

@@ -0,0 +1,180 @@
+# aihook
+
+**Pause a running Python script and let an AI agent inspect and manipulate its live state — without restarting.**
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+
+---
+
+## The problem
+
+Some scripts are expensive to restart. A Selenium browser session takes 60 seconds to reach the
+interesting state. An ML pipeline loads a 4 GB model before the first inference. A scraper
+re-authenticates and paginates through 200 pages before getting to the data you care about.
+
+When debugging these scripts, the standard loop — edit, restart, wait, observe — is brutal.
+Each hypothesis costs a full restart.
+
+## What aihook does
+
+Drop one call into your script:
+
+```python
+from aihook import agent_hook
+agent_hook()   # script pauses here; HTTP REPL starts
+```
+
+The script pauses at that line. An HTTP server starts on a free port. The calling frame's
+variables are all live and accessible. An AI agent (or you) can then probe, manipulate, and
+test fixes against the real running state:
+
+```bash
+aihook 'browser.find_by_css(".comment__replies")'
+aihook -f snippet.py        # run a multi-line snippet, edit, repeat
+aihook --exit               # resume the script
+```
+
+Each probe takes 2–5 seconds instead of 60.
+
+---
+
+## Real-world example
+
+This is what a session looks like in practice. The script is a Selenium browser automation that
+was failing silently on every "show replies" button click:
+
+```bash
+# Start the slow script in the background
+python fetch_comments.py --url "https://example.com/article" > aihook-host.log 2>&1 &
+
+# Wait for it to reach agent_hook() — CLI validates pid + port, times out after 180s
+# aihook: session found after 94.3s
+
+# Probe the live DOM
+aihook 'browser.find_by_css("[data-comment-id]")'
+# -> []   ← the attribute does not exist
+
+aihook 'browser.find_by_css("[id^=cid-]")'
+# -> [<Element id="cid-4821">  ...  ]   ← found it
+
+# Try the JS click that works despite the overlay
+aihook -f snippet.py   # snippet tests execute_script("arguments[0].click()", btn)
+# -> reply count went from 8 to 28
+
+aihook --exit
+```
+
+Five probes. Zero restarts. A working script at the end.
+
+---
+
+## Install
+
+```bash
+pip install aihook
+```
+
+### Set up the AI agent skill
+
+For Claude Code:
+```bash
+aihook --bootstrap --agent claude
+```
+
+For aider / aider-desk:
+```bash
+aihook --bootstrap --agent aider
+```
+
+This installs `SKILL.md` (the agent's instruction file for using aihook) and creates a
+`learnings/` directory where agent-accumulated tips are stored across sessions.
+
+---
+
+## CLI reference
+
+| Command | Description |
+|---|---|
+| `aihook '<code>'` | Execute code; single expressions auto-print their `repr()` |
+| `aihook -f FILE` | Send contents of FILE (`-f -` reads from stdin) |
+| `aihook --exit` | Shut down the session and let the script resume |
+| `aihook --status` | Show whether a session is active (exits 0 if healthy) |
+| `aihook --clean` | Remove a stale lock file |
+| `aihook --wait N` | Wait up to N seconds for a healthy session (default: 180s) |
+| `aihook -p PORT` | Target a specific port (skips lock-file discovery) |
+| `aihook --lockfile PATH` | Use a custom lock-file path |
+| `aihook --bootstrap` | Install SKILL.md and create learnings directory |
+
+Exit code is non-zero if the remote code raised an exception or wrote to stderr.
+
+**Auto-print:** if the submitted code is a single expression, its `repr()` is printed
+automatically. For multi-line snippets, use explicit `print()` — auto-print only applies to
+single expressions.
+
+---
+
+## How it works
+
+`agent_hook()` does three things:
+
+1. Captures the calling frame's `globals` and `locals` into a shared namespace.
+2. Starts a minimal HTTP server on a free port in `5001–5101` (configurable).
+3. Writes `./aihook-lock.yml` containing `pid`, `port`, `cwd`, and `start_time`.
+
+The CLI reads the lock file to find the port, POSTs code to `/execute`, and prints the
+result. The server shuts down on `exit()`, the lock file is removed, and the host script
+resumes.
+
+The banner printed on startup includes the source file and line number where `agent_hook()`
+was called — useful when a script has multiple hook points.
+
+---
+
+## One caveat: local variable write-back
+
+Rebinding a **local** variable of the calling function from inside the REPL does **not**
+write back to that function's fast-locals. This is the same limitation as `pdb`:
+
+```python
+# Inside my_function():
+x = 1
+agent_hook()
+print(x)   # still prints 1 even if you did `x = 2` via aihook
+```
+
+**Mutating mutable objects works fine:**
+
+```python
+my_list.append(99)           # visible in the host afterwards
+my_dict["key"] = "new"       # same
+obj.attribute = "changed"    # same
+```
+
+When testing a fix, mutate containers or attributes rather than rebinding local names.
+
+(Of course, this is documented for agents in [SKILL.md](src/aihook/SKILL.md).)
+
+---
+
+## Optional environment variables
+
+| Variable | Effect |
+|---|---|
+| `AIHOOK_PORT=NNNN` | Force a specific port |
+| `AIHOOK_PORT_RANGE=LO-HI` | Override the default `5001-5101` range |
+
+---
+
+## Development
+
+```bash
+git clone <repo-url>
+cd aihook
+pip install -e .
+pytest
+```
+
+The learnings directory (created by `--bootstrap`) accumulates session tips in
+`~/.local/share/aihook/learnings/` (Linux) or the platform equivalent. Add
+`topic_<name>.md` files there to share domain-specific knowledge across agent sessions.

aihook-0.1.5/improvement-plan.md

@@ -0,0 +1,199 @@
+# aihook — Improvement Plan
+
+Derived from a real first-time agent session and a follow-up Q&A with the testing agent.
+
+Items are ordered by value / cost ratio. Each item lists the affected
+file(s), the concrete change, and an acceptance test.
+
+---
+
+## 1. Fix multi-statement execution (HIGH priority, highest value)
+
+### Problem
+
+Snippets with more than one top-level statement fail with a confusing
+`SyntaxError`. Reproducer (confirmed by the testing agent):
+
+```python
+# /tmp/aihook_probe.py
+def foo():
+    return 42
+
+print(foo())
+```
+
+```
+$ aihook -f /tmp/aihook_probe.py
+  File "<console>", line 4
+    print(foo())
+    ^^^^^
+SyntaxError: invalid syntax
+```
+
+### Root cause
+
+`AgenticREPL.execute_command` in `src/aihook/core.py` first tries
+`compile(command, "<agent>", "eval")`. On `SyntaxError` it falls back to
+`self.console.push(command)`. `InteractiveConsole.push` is **line-oriented**:
+it mimics a human typing at a `>>>` prompt, splitting on newlines and
+feeding lines one at a time through `compile_command`. It cannot execute a
+whole multi-line source string in one call the way `exec(compile(..., "exec"))`
+can — hence the spurious error on the second top-level statement.
+
+### Fix
+
+In `src/aihook/core.py`, replace the `else` branch of `execute_command`
+(the `self.console.push(command)` call) with a direct `exec` of the
+compiled module:
+
+```python
+else:
+    code_obj = compile(command, "<agent>", "exec")
+    exec(code_obj, self.namespace)
+```
+
+Keep the expression-first path unchanged (single expressions still
+auto-print their `repr`). Drop the now-unused `self.console` attribute
+(and the `import code` + `self.console = code.InteractiveConsole(...)` in
+`__init__`) unless we find another use for it — leaner is better.
+
+Rationale: the `InteractiveConsole` machinery was only needed for the
+interactive line-by-line prompt semantics, which we do not want. Agents
+send complete, already-edited source fragments; `exec` is the right tool.
+
+### Acceptance tests
+
+Add to `tests/test_integration.py`:
+
+1. Multi-statement block executes and produces the expected stdout:
+   ```python
+   cmd = "def foo():\n    return 42\n\nprint(foo())\n"
+   # expect stdout == "42\n", stderr == "", exit 0
+   ```
+2. `def` alone (no trailing call) defines the function in the namespace
+   (verify by a follow-up `aihook 'foo()'`).
+3. Assignment + use in one snippet:
+   ```python
+   cmd = "x = 7\nprint(x * 6)\n"
+   # expect stdout == "42\n"
+   ```
+4. Genuine `SyntaxError` in a multi-statement block still reports cleanly
+   (non-zero exit, traceback on stderr).
+5. Single-expression path unchanged: `aihook '1+2'` still auto-prints `3`.
+
+---
+
+## 2. Print a startup hint about the fast-locals caveat (LOW priority, low cost)
+
+### Problem
+
+The CPython caveat (rebinding locals of the calling function does not
+propagate back) is documented but remains a trap. Not discoverable at
+runtime.
+
+### Fix
+
+In `AgenticREPL.run`, after the existing banner lines (the
+`AIHOOK AgenticREPL:` / `AIHOOK_PORT=` block) in `src/aihook/core.py`,
+print one concise stderr hint:
+
+```python
+sys.stderr.write(
+    "AIHOOK: note: rebinding a local variable of the calling function "
+    "does not propagate back (CPython fast-locals; same as pdb). "
+    "Mutate containers / attributes instead. See SKILL.md.\n"
+)
+sys.stderr.flush()
+```
+
+Keep the banner itself on stdout unchanged (agents grep for `AIHOOK_PORT=`
+there). The hint goes to stderr so it doesn't pollute machine-parseable
+output.
+
+### Acceptance test
+
+Integration test asserts the hint substring appears in the host process's
+combined log.
+
+---
+
+## 3. Documentation updates in `src/aihook/SKILL.md` (LOW priority, zero risk)
+
+Three small additions:
+
+### 3a. Promote the iterative `-f FILE` loop as the canonical workflow
+
+In the "Canonical agent workflow" section, add an explicit bullet framing
+the dominant debugging pattern:
+
+> **Iterative probe loop.** For anything beyond a one-liner, keep a
+> `snippet.py` next to the host script and rerun it after each edit:
+> ```
+> # edit snippet.py
+> aihook -f snippet.py
+> # observe, edit snippet.py again, repeat
+> ```
+> This is the primary workflow; the single-expression form is for quick
+> probes only.
+
+### 3b. Document `-f FILE` path resolution
+
+Add a note under the CLI reference:
+
+> `-f FILE` is opened by the CLI process (agent side), so relative paths
+> resolve against the **agent's** current working directory, not the host
+> script's. Use an absolute path (e.g. `-f "$PWD/snippet.py"`) if you are
+> not certain the cwds match, or if your shell tool chains `cd` commands
+> unreliably.
+
+### 3c. Document lock-file discovery scope and manual cleanup
+
+Extend the "Session discovery" section with:
+
+> Lock-file discovery does **not** walk up parent directories — `aihook`
+> only looks at `./aihook-lock.yml` in the invoking shell's exact cwd.
+> Run `aihook` from the same directory as the host script.
+>
+> If the host process is killed uncleanly (e.g. `SIGKILL`, OOM), the lock
+> file may remain. A subsequent `agent_hook()` call in the same cwd will
+> detect this automatically (pid not alive) and overwrite it. To clean up
+> manually, just `rm ./aihook-lock.yml`.
+
+---
+
+## 4. Nice-to-haves (deferred, consider after items 1-3 land)
+
+These are not worth doing now but are recorded for future consideration:
+
+- **`--echo` / `--verbose` flag** that always prints the last value (or
+  `None`) regardless of statement vs. expression. Low value once item 1
+  lands, because the agent can just wrap in `print(...)` in a multi-line
+  block.
+- **Resolve `-f FILE` relative to `lockfile["cwd"]`** when a relative path
+  is given and the file is not found locally. Rejected for now: the CLI
+  may run on a different machine than the host, and the current behavior
+  is consistent with every other Unix tool that reads files.
+- **Walk up parents for lock-file discovery.** Rejected for now: breaks
+  the "one aihook per cwd" invariant and invites cross-project confusion.
+
+---
+
+## Out of scope / non-issues confirmed by Q&A
+
+- Banner reaches agents via log file reliably (Q4a).
+- `--wait 5` default is a good middle ground (Q4b).
+- Exit-code semantics are correct (Q4c). The `REPL: Exiting` message is
+  written to **stdout**, not stderr, so there is no spurious stderr on
+  successful `--exit` — the testing agent's suspicion was unfounded.
+- `aihook --exit` shutdown + lock-file cleanup work reliably (Q4d).
+
+---
+
+## Implementation order
+
+1. Item 1 (exec fix + tests) — single commit.
+2. Item 3 (docs) — single commit, can precede or follow item 1.
+3. Item 2 (startup hint) — single commit.
+
+Each item is independently mergeable. Item 1 is the only one with
+behavioural risk; its test suite additions are mandatory.