Treat SessionStorage as a stable public extension point (and allow custom session storage in tau_coding)

[mmpouya]

Motivation

tau_agent is a genuinely portable harness, and some of us - on our team - use it outside the terminal-coding context as the agent brain inside long-running services. In those deployments, session history belongs in a shared database (we use Postgres, but there could be others like Mongo, MySQL, ...) rather than local JSONL files: multiple workers append to the same session, history is backed up with the rest of the system, and sessions can be inspected/queried centrally.

The good news is that the architecture already anticipates this: tau_agent.session.SessionStorage is a small Protocol (append /
read_all), and JsonlSessionStorage is just one implementation. I maintain an external package (tau_hub, https://github.com/mmpouya/tau_hub) that implements this protocol on top of several database backends, and it works as a drop-in replacement today.

This issue asks to make that contract official rather than implicit and incidental.

Note

You've been explicit about that tau_agent must not depend on local config paths, resource loading, or app-specific infrastructure. A registry with TinyDB/Mongo/Redis/Postgres backends, dill, and cryptography is exactly the kind of dependency surface you've deliberately kept out of the core.⁠
That's the main reason I kept tau_hub as an independent package.
But I would be glad if you want to add it to Tau as an optional dependency.

My suggestion:

I'm proposing three small, independent steps. Each one preserves the layer boundaries, and none of them adds a dependency to core.

1. Document SessionStorage as an official extension point:

   • Add a short docs page (e.g. under Internals or Guides) that tells third-party developers how to write their own session storage.
   • It should cove the SessionStorage protocol append(entry) and read_all(), and a promise that this interface is stable across minor versions.
   • And it should state the rules of an implementation, as the storage should be append-only
     now, these rules only exist implicitly, in the behaviour of JsonlSessionStorage. Anyone writing a database-backed storage has to reverse-engineer it from the source.

2. Ship a reusable conformance test for storage implementations:
   A small test helper in tau_agent (or a documented pytest recipe) that runs the rules above against any SessionStorage implementation

3. (Optional, separate PR) Let tau_coding accept a custom SessionStorage instead of hardwiring JSONL paths
   Today, the CLI/TUI always creates JsonlSessionStorage pointed at ~/.tau/sessions/. Add one seam — a config option or factory hook — where a user can supply their own SessionStorage instead.

Non-goals

• Not proposing to merge any database code, drivers, or new dependencies into tau_agent or tau_coding. The core should stay portable and dependency-light; concrete backends belong in external packages.
  I know you want to keep:

The architecture small, readable, and easy to learn from.

---

I'm happy to send PRs for (1) and (2), and a design sketch for (3) if there's interest. I already have working implementations and tests on the tau_hub side to validate the contract against.

I'm not a native English speaker, so I used AI to make it sound native :)) sorry if it looks AI-generated.

[mohamad-tohidi]

thanks
this is a very useful feature

[mohamad-tohidi]

im waiting for this feature @alejandro-ao...