sessionkit 0.2.0__tar.gz → 0.3.0__tar.gz

sessionkit-0.3.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: sessionkit
+Version: 0.3.0
+Summary: Session Kit gives your Claude Code sessions voice, mail, a phone line and a tmux sidebar, in one install.
+Author: Mike Bailey
+Author-email: Mike Bailey <mike@sessionkit.ai>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Requires-Dist: click>=8.1
+Requires-Dist: sessionmail>=0.3.0
+Requires-Dist: sessiontools>=0.3.0
+Requires-Dist: sessionphone[media]>=0.3.0
+Requires-Dist: sessionview>=0.3.0
+Requires-Dist: sessionvoice[capture]>=0.3.0
+Requires-Python: >=3.11, <3.15
+Project-URL: Homepage, https://github.com/sessionkit/sessionkit
+Project-URL: Repository, https://github.com/sessionkit/sessionkit
+Description-Content-Type: text/markdown
+
+# Session Kit
+
+Session Kit lets your Claude Code sessions mail each other, hear you and
+answer aloud. One install brings the five family packages and their Claude
+Code plugins.
+
+## Installation
+
+You need macOS, [Claude Code][claude-code], and [Homebrew][brew] or at
+least Apple's Command Line Tools. Homebrew installs the Command Line Tools
+for you ([prerequisites][prereqs]), and the kit needs two of their tools:
+the plugin lines clone with git, and the ears build a Swift helper with
+`swiftc`. Without Homebrew, run `xcode-select --install` to get the Command
+Line Tools alone. If you do not have uv yet, install it with
+`curl -LsSf https://astral.sh/uv/install.sh | sh`, then open a new terminal
+(or run `source ~/.local/bin/env`).
+
+```bash
+uv tool install --python 3.14 sessionkit
+claude plugin marketplace add sessionkit/sessionkit
+claude plugin install sessionkit@sessionkit
+```
+
+The first line puts the commands on your PATH. The other two install the
+kit's plugin and the five family plugins it depends on.
+
+- **Keep `--python 3.14`.** Without it, uv takes the Python it finds: 3.15,
+  where a voice library has no build yet and the install fails, or the
+  Command Line Tools' 3.11. The kit is tested on 3.14.
+- **Upgrade with `uv tool upgrade sessionkit`.** It keeps the Python the
+  install chose. To reinstall, give the pin again:
+  `uv tool install --python 3.14 --reinstall sessionkit`. Without it, uv
+  drops the pin from its record, or, with `--force`, builds the kit again on
+  the Python it finds.
+- **A dialog may ask to install the Command Line Tools.** On a Mac without
+  them, the first `uv tool install` opens it. Click Install and let it
+  finish: the plugin lines need the git it brings.
+- **Phone calls are installed, and walked for a session started with
+  `session start <name>`.** A fresh Mac took a real call and passed. A plain
+  `claude` session does not hear calls you make to it yet. Whether the phone
+  bot signs its mail to your Claude follows your mail carrier:
+  [bot mail signing][phone-signing].
+
+**Then quit Claude Code and start it again**, every window of it, before you
+run anything else. A plugin installed from the shell loads only when Claude
+Code starts, so a session that was already open has no plugin commands on
+its PATH, and no plugin hooks.
+
+The three lines leave the ears without the model they listen with. Fetch it
+once:
+
+```bash
+ears install
+```
+
+It downloads the 2.3 MB voice-activity model to
+`~/.cache/ears/silero_vad.onnx` (network, no sudo) and prints `done`. Without
+it the ears cannot hear you, and `ears services install`, the step that
+starts them ([hearing and speaking][hearing]), refuses with
+`silero MISSING`. The Swift helper is built later, when those services start.
+
+- **The mail hooks start off.** They tell an agent about new mail between
+  its tool calls. To turn them on, set `"hooks": true` in
+  `~/.sessionkit/mail/settings/mail.json`. On a fresh install the file is
+  not there yet, so make it:
+
+  ```bash
+  mkdir -p ~/.sessionkit/mail/settings
+  echo '{"version": 1, "hooks": true}' > ~/.sessionkit/mail/settings/mail.json
+  ```
+
+  If the file is there, change only that key, because it can hold other
+  settings:
+
+  ```bash
+  perl -pi -e 's/"hooks": *false/"hooks": true/' ~/.sessionkit/mail/settings/mail.json
+  ```
+
+Step by step, with every step that needs you marked: [the manual
+install][install].
+
+## Quick start
+
+```bash
+sessionkit --version
+```
+
+It lists the kit and each family package, with its version:
+
+```text
+sessionkit, version 0.3.0
+  sessionmail   0.3.0
+  sessiontools  0.3.0
+  sessionphone  0.3.0
+  sessionview   0.3.0
+  sessionvoice  0.3.0
+```
+
+Start Claude with `session start claude`, never a bare `claude`: mail to
+your agent's box, your phone's included, reaches only a session started as
+that agent. `sessionkit setup` makes the box and the agent first: [first
+checks][checks].
+
+Then, from your agent inside a Claude Code session:
+
+```bash
+session list                                     # your live sessions
+message send <box> -s "PR ready" -f note.md      # mail another agent
+mouth say --device default "the build is green"  # speak one line
+```
+
+- **Mail works inside a session.** `message` and `pager` read who is asking
+  from the session. A plain terminal has no session, so they refuse with
+  `no seat in the environment ... set an identity` ([first checks][checks]).
+  A send never makes a box: the address must have one already ([mail
+  between agents][mail]).
+- **The mouth needs a device.** `--device default` is your Mac's default
+  output; `mouth devices` lists the others.
+- **To hear you**, the ears need a speech-to-text server: [hearing and
+  speaking][hearing].
+- **Your agent talks with the kit's mouth and ears.** sessionvoice's ears
+  skill sets the default:
+
+  > **With the kit, an agent talks through the kit's own mouth and ears: it
+  > speaks with `mouth say` and listens by arming the ears with `ears-arm`. That
+  > is the default whenever the user asks it to talk, speak, listen or use voice,
+  > even on a host that also has VoiceMode's `converse` tool. It uses `converse`
+  > only when the user asks for converse by name.**
+
+## Uninstall
+
+```bash
+claude plugin marketplace remove sessionkit
+uv tool uninstall sessionkit
+```
+
+Removing the marketplace removes its six plugins too, but not the copies they
+ran from. Those copies, the services and your data have their own steps:
+[uninstall][uninstall].
+
+## Usage
+
+Every command answers `--help`, and each has a page: [components][components].
+
+## The family
+
+Session Kit installs these together:
+
+- [sessionmail][pkg-mail]: mail for coding agents. `message`, `pager` and
+  `memory` over one maildir.
+- [sessiontools][pkg-tools]: sessions, status and idle. `session`.
+- [sessionvoice][pkg-voice]: ambient voice. `ears` hears; `mouth` speaks.
+- [sessionphone][pkg-phone]: phone calls to a session over Delta Chat.
+  Installed, and walked on a fresh Mac for a session started with
+  `session start <name>`. A plain `claude` session does not hear calls you
+  make to it yet.
+- [sessionview][pkg-view]: a tmux sidebar of your projects and your agents.
+
+## Components
+
+The commands, services and folders the install adds, and where each
+package logs: [components][components].
+
+## Configuration
+
+Each package configures itself: [configuration][configuration]. How the
+settings files stack: [the settings guide][settings].
+
+## Logs
+
+Each package keeps its own log: [logs][logs]. Which one to read for a
+symptom: [troubleshooting][troubleshooting].
+
+## Development
+
+```bash
+git clone https://github.com/sessionkit/sessionkit
+cd sessionkit
+make install    # editable: uv tool install -e .
+make check      # ruff, shellcheck, then the tests
+```
+
+The rules for changing the kit: [AGENTS.md][agents].
+
+## Status
+
+Alpha, 0.3.0. Tested on macOS 27 on Apple silicon; Linux and Windows are
+untested. What you may still hit: [known gaps][gaps].
+
+Licence: [AGPL-3.0][licence].
+
+[claude-code]: https://claude.ai/code
+[brew]: https://brew.sh
+[install]: INSTALL.md
+[prereqs]: INSTALL.md#1-prerequisites-human
+[checks]: INSTALL.md#4-first-checks
+[hearing]: INSTALL.md#5-hearing-and-speaking-it-hears-me-and-speaks
+[mail]: INSTALL.md#mail-between-agents
+[uninstall]: INSTALL.md#8-uninstall
+[gaps]: INSTALL.md#7-known-gaps-you-will-hit
+[components]: docs/components.md
+[logs]: docs/components.md#logs
+[configuration]: docs/configuration.md
+[settings]: docs/settings.md
+[troubleshooting]: docs/troubleshooting.md
+[agents]: AGENTS.md
+[licence]: LICENSE
+[pkg-mail]: https://github.com/sessionkit/sessionmail
+[pkg-tools]: https://github.com/sessionkit/sessiontools
+[pkg-voice]: https://github.com/sessionkit/sessionvoice
+[pkg-phone]: https://github.com/sessionkit/sessionphone
+[phone-signing]: https://github.com/sessionkit/sessionphone/blob/HEAD/docs/bot-mail-signing.md
+[pkg-view]: https://github.com/sessionkit/sessionview

sessionkit-0.3.0/README.md

@@ -0,0 +1,213 @@
+# Session Kit
+
+Session Kit lets your Claude Code sessions mail each other, hear you and
+answer aloud. One install brings the five family packages and their Claude
+Code plugins.
+
+## Installation
+
+You need macOS, [Claude Code][claude-code], and [Homebrew][brew] or at
+least Apple's Command Line Tools. Homebrew installs the Command Line Tools
+for you ([prerequisites][prereqs]), and the kit needs two of their tools:
+the plugin lines clone with git, and the ears build a Swift helper with
+`swiftc`. Without Homebrew, run `xcode-select --install` to get the Command
+Line Tools alone. If you do not have uv yet, install it with
+`curl -LsSf https://astral.sh/uv/install.sh | sh`, then open a new terminal
+(or run `source ~/.local/bin/env`).
+
+```bash
+uv tool install --python 3.14 sessionkit
+claude plugin marketplace add sessionkit/sessionkit
+claude plugin install sessionkit@sessionkit
+```
+
+The first line puts the commands on your PATH. The other two install the
+kit's plugin and the five family plugins it depends on.
+
+- **Keep `--python 3.14`.** Without it, uv takes the Python it finds: 3.15,
+  where a voice library has no build yet and the install fails, or the
+  Command Line Tools' 3.11. The kit is tested on 3.14.
+- **Upgrade with `uv tool upgrade sessionkit`.** It keeps the Python the
+  install chose. To reinstall, give the pin again:
+  `uv tool install --python 3.14 --reinstall sessionkit`. Without it, uv
+  drops the pin from its record, or, with `--force`, builds the kit again on
+  the Python it finds.
+- **A dialog may ask to install the Command Line Tools.** On a Mac without
+  them, the first `uv tool install` opens it. Click Install and let it
+  finish: the plugin lines need the git it brings.
+- **Phone calls are installed, and walked for a session started with
+  `session start <name>`.** A fresh Mac took a real call and passed. A plain
+  `claude` session does not hear calls you make to it yet. Whether the phone
+  bot signs its mail to your Claude follows your mail carrier:
+  [bot mail signing][phone-signing].
+
+**Then quit Claude Code and start it again**, every window of it, before you
+run anything else. A plugin installed from the shell loads only when Claude
+Code starts, so a session that was already open has no plugin commands on
+its PATH, and no plugin hooks.
+
+The three lines leave the ears without the model they listen with. Fetch it
+once:
+
+```bash
+ears install
+```
+
+It downloads the 2.3 MB voice-activity model to
+`~/.cache/ears/silero_vad.onnx` (network, no sudo) and prints `done`. Without
+it the ears cannot hear you, and `ears services install`, the step that
+starts them ([hearing and speaking][hearing]), refuses with
+`silero MISSING`. The Swift helper is built later, when those services start.
+
+- **The mail hooks start off.** They tell an agent about new mail between
+  its tool calls. To turn them on, set `"hooks": true` in
+  `~/.sessionkit/mail/settings/mail.json`. On a fresh install the file is
+  not there yet, so make it:
+
+  ```bash
+  mkdir -p ~/.sessionkit/mail/settings
+  echo '{"version": 1, "hooks": true}' > ~/.sessionkit/mail/settings/mail.json
+  ```
+
+  If the file is there, change only that key, because it can hold other
+  settings:
+
+  ```bash
+  perl -pi -e 's/"hooks": *false/"hooks": true/' ~/.sessionkit/mail/settings/mail.json
+  ```
+
+Step by step, with every step that needs you marked: [the manual
+install][install].
+
+## Quick start
+
+```bash
+sessionkit --version
+```
+
+It lists the kit and each family package, with its version:
+
+```text
+sessionkit, version 0.3.0
+  sessionmail   0.3.0
+  sessiontools  0.3.0
+  sessionphone  0.3.0
+  sessionview   0.3.0
+  sessionvoice  0.3.0
+```
+
+Start Claude with `session start claude`, never a bare `claude`: mail to
+your agent's box, your phone's included, reaches only a session started as
+that agent. `sessionkit setup` makes the box and the agent first: [first
+checks][checks].
+
+Then, from your agent inside a Claude Code session:
+
+```bash
+session list                                     # your live sessions
+message send <box> -s "PR ready" -f note.md      # mail another agent
+mouth say --device default "the build is green"  # speak one line
+```
+
+- **Mail works inside a session.** `message` and `pager` read who is asking
+  from the session. A plain terminal has no session, so they refuse with
+  `no seat in the environment ... set an identity` ([first checks][checks]).
+  A send never makes a box: the address must have one already ([mail
+  between agents][mail]).
+- **The mouth needs a device.** `--device default` is your Mac's default
+  output; `mouth devices` lists the others.
+- **To hear you**, the ears need a speech-to-text server: [hearing and
+  speaking][hearing].
+- **Your agent talks with the kit's mouth and ears.** sessionvoice's ears
+  skill sets the default:
+
+  > **With the kit, an agent talks through the kit's own mouth and ears: it
+  > speaks with `mouth say` and listens by arming the ears with `ears-arm`. That
+  > is the default whenever the user asks it to talk, speak, listen or use voice,
+  > even on a host that also has VoiceMode's `converse` tool. It uses `converse`
+  > only when the user asks for converse by name.**
+
+## Uninstall
+
+```bash
+claude plugin marketplace remove sessionkit
+uv tool uninstall sessionkit
+```
+
+Removing the marketplace removes its six plugins too, but not the copies they
+ran from. Those copies, the services and your data have their own steps:
+[uninstall][uninstall].
+
+## Usage
+
+Every command answers `--help`, and each has a page: [components][components].
+
+## The family
+
+Session Kit installs these together:
+
+- [sessionmail][pkg-mail]: mail for coding agents. `message`, `pager` and
+  `memory` over one maildir.
+- [sessiontools][pkg-tools]: sessions, status and idle. `session`.
+- [sessionvoice][pkg-voice]: ambient voice. `ears` hears; `mouth` speaks.
+- [sessionphone][pkg-phone]: phone calls to a session over Delta Chat.
+  Installed, and walked on a fresh Mac for a session started with
+  `session start <name>`. A plain `claude` session does not hear calls you
+  make to it yet.
+- [sessionview][pkg-view]: a tmux sidebar of your projects and your agents.
+
+## Components
+
+The commands, services and folders the install adds, and where each
+package logs: [components][components].
+
+## Configuration
+
+Each package configures itself: [configuration][configuration]. How the
+settings files stack: [the settings guide][settings].
+
+## Logs
+
+Each package keeps its own log: [logs][logs]. Which one to read for a
+symptom: [troubleshooting][troubleshooting].
+
+## Development
+
+```bash
+git clone https://github.com/sessionkit/sessionkit
+cd sessionkit
+make install    # editable: uv tool install -e .
+make check      # ruff, shellcheck, then the tests
+```
+
+The rules for changing the kit: [AGENTS.md][agents].
+
+## Status
+
+Alpha, 0.3.0. Tested on macOS 27 on Apple silicon; Linux and Windows are
+untested. What you may still hit: [known gaps][gaps].
+
+Licence: [AGPL-3.0][licence].
+
+[claude-code]: https://claude.ai/code
+[brew]: https://brew.sh
+[install]: INSTALL.md
+[prereqs]: INSTALL.md#1-prerequisites-human
+[checks]: INSTALL.md#4-first-checks
+[hearing]: INSTALL.md#5-hearing-and-speaking-it-hears-me-and-speaks
+[mail]: INSTALL.md#mail-between-agents
+[uninstall]: INSTALL.md#8-uninstall
+[gaps]: INSTALL.md#7-known-gaps-you-will-hit
+[components]: docs/components.md
+[logs]: docs/components.md#logs
+[configuration]: docs/configuration.md
+[settings]: docs/settings.md
+[troubleshooting]: docs/troubleshooting.md
+[agents]: AGENTS.md
+[licence]: LICENSE
+[pkg-mail]: https://github.com/sessionkit/sessionmail
+[pkg-tools]: https://github.com/sessionkit/sessiontools
+[pkg-voice]: https://github.com/sessionkit/sessionvoice
+[pkg-phone]: https://github.com/sessionkit/sessionphone
+[phone-signing]: https://github.com/sessionkit/sessionphone/blob/HEAD/docs/bot-mail-signing.md
+[pkg-view]: https://github.com/sessionkit/sessionview

{sessionkit-0.2.0 → sessionkit-0.3.0}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "sessionkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Session Kit gives your Claude Code sessions voice, mail, a phone line and a tmux sidebar, in one install."
+readme = "README.md"
 license = "AGPL-3.0-or-later"
 license-files = ["LICENSE"]
 classifiers = ["Development Status :: 3 - Alpha"]
@@ -9,16 +10,22 @@ authors = [
     { name = "Mike Bailey", email = "mike@sessionkit.ai" }
 ]
 requires-python = ">=3.11,<3.15"
-# The family, one install. Floored at 0.1.0: every family package is alpha at 0.1.0.
-# PyPI's 0.0.1 name placeholders must never satisfy these.
+# The family, one install. Floored at 0.3.0: the kit is released and tested
+# with the family's 0.3.0, so it needs every family package at 0.3.0 or
+# later, and PyPI's 0.0.1 name placeholders and the 0.1.0 alphas must never
+# satisfy these.
+# sessionphone with its media extra: the bot, calls and `sessionphone web` need it.
 # sessionvoice with its capture extra, so the ears can hear the room.
+# This is the RULED list, kept in tests/_ruled_deps.py with the ruling;
+# tests/test_dependency_gate.py fails when these lines, the built wheel or
+# uv.lock drift from it.
 dependencies = [
     "click>=8.1",
-    "sessionmail>=0.1.0",
-    "sessiontools>=0.1.0",
-    "sessionphone>=0.1.0",
-    "sessionview>=0.1.0",
-    "sessionvoice[capture]>=0.1.0",
+    "sessionmail>=0.3.0",
+    "sessiontools>=0.3.0",
+    "sessionphone[media]>=0.3.0",
+    "sessionview>=0.3.0",
+    "sessionvoice[capture]>=0.3.0",
 ]
 
 [project.urls]
@@ -31,8 +38,8 @@ Repository = "https://github.com/sessionkit/sessionkit"
 # `uv tool install sessionkit` would put `sessionkit` alone on the PATH.
 # Each entry point is the child's own target, copied verbatim; re-measure them
 # at each child's HEAD whenever a child adds, renames or drops a command.
-# Measured from each child's built wheel (entry_points.txt) at mail 471a6f7,
-# tools ab62717, phone 02d8cf7, view 3fada19, voice eda3f94.
+# Measured from each child's 0.3.0 wheel (entry_points.txt), by wheel sha256:
+# mail 8e4d9476, tools 8d089699, phone ac402a39, view 3942f119, voice ebc1b65c.
 # sessionview's four commands share one target: `sessionview:main` reads the
 # name it was run as and runs that command.
 # The kit itself still ships no `session` of its own: `session` below is

{sessionkit-0.2.0 → sessionkit-0.3.0}/src/sessionkit/cli.py

@@ -90,13 +90,22 @@ def _shape(check):
     help="Your own full mail address (name@host), written as the operator "
     "instead of a mail box.",
 )
+@click.option(
+    "--agent",
+    metavar="NAME",
+    default=operator_setup.DEFAULT_AGENT,
+    show_default=True,
+    callback=_shape(operator_setup.check_agent_shape),
+    help="Your assistant's name: setup writes its agent file and makes its "
+    "mail box, so `session start NAME` starts Claude as NAME, hearing mail to NAME.",
+)
 @click.option(
     "--dry-run",
     is_flag=True,
     help="Run every check and print what would be written; write nothing.",
 )
-def setup(mailbox: str | None, address: str | None, dry_run: bool) -> None:
-    """Set up mail on this Mac, then write you as the operator: the human other seats ask.
+def setup(mailbox: str | None, address: str | None, agent: str, dry_run: bool) -> None:
+    """Set up mail on this Mac, write you as the operator, and define your assistant.
 
     Mail first: it runs sessionmail's mail setup (`message setup`), which
     makes the mail root and your box, and prints what it did and what is
@@ -109,13 +118,28 @@ def setup(mailbox: str | None, address: str | None, dry_run: bool) -> None:
     confirm who you are: then it says how to name yourself, with --address
     or --mailbox. It writes nothing, too, while the operator file an earlier
     release wrote is still in place and none is at the new path: it names
-    both. Exit 0 all done, 1 refused or failed, 2 usage, 4 done what it
-    could, mail steps left for you. See INSTALL.md, "Operator and
-    administrators" and "Mail between agents".
+    both.
+
+    Then your assistant (--agent, default claude): it writes NAME.md where
+    `session start` looks for agents (~/.session/agents, unless
+    $AGENTS_DIR or ~/.session/agent/config says otherwise), not keyed, and
+    asks `message setup` for the box NAME. A file already there, in either
+    layout, is left as it is. It ends with the one launch step:
+    `session start NAME`.
+
+    Before that step it asks `ears backends`, read only. If the ears'
+    voice-activity model is missing, it says one line naming `ears install`.
+    It never runs `ears install`, and the line never changes the exit.
+
+    Exit 0 all done, 1 refused or failed, 2 usage, 4 done what it could,
+    mail steps left for you. See INSTALL.md, "Operator and administrators"
+    and "Mail between agents".
     """
     if mailbox is not None and address is not None:
         raise click.UsageError("give --mailbox or --address, not both")
-    outcome = operator_setup.run_setup(mailbox=mailbox, address=address, dry_run=dry_run)
+    outcome = operator_setup.run_setup(
+        mailbox=mailbox, address=address, agent=agent, dry_run=dry_run
+    )
     for line in outcome.lines:
         click.echo(line, err=outcome.code != 0)
     raise SystemExit(outcome.code)

{sessionkit-0.2.0 → sessionkit-0.3.0}/src/sessionkit/setup.py

@@ -1,4 +1,8 @@
-"""`sessionkit setup`: make this host's mail ready, then write the operator.
+"""`sessionkit setup`: make this host's mail ready, write the operator, then
+define the assistant (`run_agent`: the file `session start NAME` resolves, and
+the box it hears, so a seat started that way hears mail to NAME). Last, it
+asks `ears backends` whether the ears' model is there, and says so when it is
+not (`ears_model_missing`): read only, never `ears install`, never the exit.
 
 Mail first. sessionmail's mail setup verb (argv in `MAIL_SETUP_ARGV`) makes
 the mail root and the first boxes, the operator's box among them, and the
@@ -132,6 +136,21 @@ def check_mailbox_shape(name: str) -> str:
     return name
 
 
+def check_agent_shape(name: str) -> str:
+    """NAME names the agent's mail box, so it is a mail box name. It names
+    its file too (`<agents folder>/NAME.md`), so it may not start with `.`:
+    `session start --list-agents` hides a dot-file, and a picker never offers it."""
+    try:
+        check_mailbox_shape(name)
+    except ShapeError:
+        raise ShapeError(
+            f"{name!r} is not an agent name: one plain name, no '/', no '@', no spaces"
+        ) from None
+    if name.startswith("."):
+        raise ShapeError(f"{name!r} is not an agent name: it may not start with '.'")
+    return name
+
+
 def check_address_shape(address: str) -> str:
     """ADDRESS is `local@domain`: exactly one `@`, both sides non-empty, no
     whitespace, and not an example domain (a pasted placeholder)."""
@@ -303,8 +322,14 @@ def drop_in_text(block: Mapping[str, str]) -> str:
 def write_exclusive(target: Path, text: str) -> str | None:
     """Create TARGET holding TEXT, only if it does not exist. None on
     success, else why not. Never a partial target and never a stray
-    `*.json`: the temp's name ends in `.tmp-<pid>`, and it is removed."""
-    target.parent.mkdir(parents=True, exist_ok=True)
+    `*.json`: the temp's name ends in `.tmp-<pid>`, and it is removed. A
+    folder that cannot be made (a file in the way, no permission) is a
+    reason too, never a traceback: the caller's other halves have run, and
+    their lines must still print."""
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        return f"could not make {target.parent} ({e.strerror or e.__class__.__name__})"
     temp = target.with_name(f".{target.name}.tmp-{os.getpid()}")
     try:
         # A temp by this pid's name is a dead run's leftover (no live process
@@ -344,17 +369,22 @@ MAIL_LEFT = 4
 MAIL_DOC = 'INSTALL.md, "Mail between agents"'
 
 
-def mail_setup_boxes(mailbox: str | None, address: str | None) -> tuple[str, ...]:
+def mail_setup_boxes(
+    mailbox: str | None, address: str | None, agent: str | None
+) -> tuple[str, ...]:
     """The boxes the installer asks the verb for, as `--box NAME` each.
 
-    Exactly one, and only when the user asked for one: `--mailbox NAME`
-    passes NAME, so a named box on a fresh install is made before the
-    operator check looks for it. Otherwise none: the verb's own floor (the
-    operator's box, `operator.mailbox`, else the installing account's name)
-    is all that is made. A seat's own box is made by its pager, never here.
+    `--mailbox NAME` passes NAME, so a named box on a fresh install is made
+    before the operator check looks for it. Then the agent's box (`--agent`,
+    default `claude`): a seat started with `session start NAME` hears the
+    box NAME, so the box must exist for mail to it to land. The verb's own
+    floor (the operator's box, `operator.mailbox`, else the installing
+    account's name) is made besides. A session's own box is made by its
+    pager, never here. The verb is idempotent: a box that exists stays.
     """
     del address  # an address needs no box
-    return (mailbox,) if mailbox is not None else ()
+    boxes = [name for name in (mailbox, agent) if name is not None]
+    return tuple(dict.fromkeys(boxes))
 
 
 def mail_setup_argv(boxes: Sequence[str], dry_run: bool) -> list[str]:
@@ -371,15 +401,18 @@ def _verb() -> str:
     return " ".join(MAIL_SETUP_ARGV)
 
 
-def _no_verb(why: str) -> Outcome:
-    """This sessionmail cannot run the verb: print the exact step instead."""
+def _no_verb(why: str, boxes: Sequence[str] = ()) -> Outcome:
+    """This sessionmail cannot run the verb: print the exact step instead,
+    with the `--box NAME` setup would have passed (the agent's among them),
+    so running it later makes the same boxes a run of the verb would."""
+    step = " ".join(mail_setup_argv(boxes, dry_run=False))
     return Outcome(
         EXIT_STEPS_LEFT,
         [
             f"Mail not set up: {why}.",
             (
                 f"A newer sessionmail has it. Until you have that, set mail up by "
-                f"hand ({MAIL_DOC}); once you do, run: {_verb()}"
+                f"hand ({MAIL_DOC}); once you do, run: {step}"
             ),
         ],
     )
@@ -410,14 +443,15 @@ def run_mail_setup(
     """
     program = MAIL_SETUP_ARGV[0]
     if _find(program, environ) is None:
-        return _no_verb(f"`{program}` is not on the PATH")
+        return _no_verb(f"`{program}` is not on the PATH", boxes)
     probe = _run([*MAIL_SETUP_ARGV, "--help"], environ)
     if probe is None:
-        return _no_verb(f"`{_verb()} --help` did not answer")
+        return _no_verb(f"`{_verb()} --help` did not answer", boxes)
     if probe.returncode != 0:
         return _no_verb(
             f"this sessionmail has no `{_verb()}` "
-            f"(`{_verb()} --help` exited {probe.returncode})"
+            f"(`{_verb()} --help` exited {probe.returncode})",
+            boxes,
         )
 
     argv = mail_setup_argv(boxes, dry_run)
@@ -463,6 +497,175 @@ def run_mail_setup(
     )
 
 
+# --- the agent: the file `session start NAME` resolves -------------------------
+
+# The assistant setup defines when no `--agent` is given.
+DEFAULT_AGENT = "claude"
+
+# Where `session start NAME` looks for agents: sessiontools'
+# `start/agents.py:agents_root`, the same rule, mirrored here so the kit does
+# not import sessiontools' internals. `$AGENTS_DIR`, else
+# `~/.session/agent/config` if that is a directory, else `~/.session/agents`.
+# tests/test_setup.py holds this rule to the installed sessiontools'.
+AGENTS_DIR_ENV = "AGENTS_DIR"
+SESSION_HOME = ".session"
+AGENT_CONFIG_DIR = ("agent", "config")
+AGENTS_DIR_NAME = "agents"
+
+# The reader: every agent `session start` would accept, one name a line.
+LIST_AGENTS_ARGV: tuple[str, ...] = ("session", "start", "--list-agents")
+
+# The one launch step, in sessionphone's final words: the same line its Delta
+# bot prints. Spelled once: change it here only.
+LAUNCH_SENTENCE = "To hear Delta messages, start Claude with: session start {agent}"
+
+# The agent file. No `start:` keys: the seat is NOT keyed. No front matter at
+# all: Claude Code (2.1.304, measured) names an agent by its file, so `name:`
+# and `description:` are not needed. For any NAME but `claude` this text is
+# the agent's prompt; for `claude`, Claude Code's own built-in agent of that
+# name answers, and the file only has to exist for `session start` to find it.
+AGENT_TEXT = """\
+You are {agent}, a Claude Code assistant.
+
+Written by `sessionkit setup`. `session start {agent}` starts Claude as
+{agent}, so the session hears mail to the box {agent}. Edit this file as you
+like: setup never writes over it.
+"""
+
+
+def agents_root(home: Path, environ: Mapping[str, str]) -> Path:
+    """The agents folder `session start` reads, by sessiontools' rule."""
+    named = environ.get(AGENTS_DIR_ENV)
+    if named:
+        return Path(os.path.expanduser(named))
+    config = home / SESSION_HOME / Path(*AGENT_CONFIG_DIR)
+    if config.is_dir():
+        return config
+    return home / SESSION_HOME / AGENTS_DIR_NAME
+
+
+def agent_file(home: Path, environ: Mapping[str, str], agent: str) -> Path:
+    """The file setup writes for AGENT: the flat layout, `<root>/NAME.md`."""
+    return agents_root(home, environ) / f"{agent}.md"
+
+
+def agent_text(agent: str) -> str:
+    return AGENT_TEXT.format(agent=agent)
+
+
+def launch_sentence(agent: str) -> str:
+    return LAUNCH_SENTENCE.format(agent=agent)
+
+
+def read_listed_agents(environ: Mapping[str, str]) -> list[str] | None:
+    """`session start --list-agents`, one name a line, or None when it does
+    not answer (absent, non-zero, a timeout): "not verified", never "absent"."""
+    done = _run(LIST_AGENTS_ARGV, environ)
+    if done is None or done.returncode != 0:
+        return None
+    return [line.strip() for line in done.stdout.splitlines() if line.strip()]
+
+
+def run_agent(
+    *,
+    agent: str,
+    dry_run: bool = False,
+    home: Path | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> Outcome:
+    """Write AGENT's file where `session start` looks, once; then verify.
+
+    Never clobbers: either layout `session start` reads (`<root>/NAME/NAME.md`,
+    which wins, or `<root>/NAME.md`) already there means write nothing. A
+    folder `<root>/NAME/` without its NAME.md, or a flat path that is not a
+    file, is refused: `session start` could not start NAME from it, and
+    writing beside it would not change that. AGENT is already shape-checked.
+    """
+    environ = os.environ if environ is None else environ
+    home = Path.home() if home is None else home
+    root = agents_root(home, environ)
+    folder = root / agent
+    flat = agent_file(home, environ, agent)
+    if folder.is_dir():
+        inside = folder / f"{agent}.md"
+        if inside.is_file():
+            return Outcome(
+                EXIT_OK, [f"Agent {agent!r} is already in {inside}; left as it is."]
+            )
+        return Outcome(
+            EXIT_REFUSED,
+            [
+                (
+                    f"No agent file written: {folder} exists without {agent}.md "
+                    f"in it, so session start cannot start {agent!r}."
+                ),
+                f"Put {agent}.md in that folder, or remove it, then run sessionkit setup again.",
+            ],
+        )
+    if flat.is_file():
+        return Outcome(
+            EXIT_OK, [f"Agent {agent!r} is already in {flat}; left as it is."]
+        )
+    if os.path.lexists(flat):
+        return Outcome(
+            EXIT_REFUSED,
+            [
+                f"No agent file written: {flat} exists and is not a file session start can read.",
+                "Remove it, then run sessionkit setup again.",
+            ],
+        )
+    text = agent_text(agent)
+    if dry_run:
+        return Outcome(EXIT_OK, [f"Would write {flat}:", text.rstrip("\n")])
+
+    failed = write_exclusive(flat, text)
+    if failed is not None:
+        return Outcome(EXIT_REFUSED, [f"No agent file written: {failed}."])
+    lines = [f"Wrote {flat}: the agent {agent!r}, not keyed."]
+
+    listed = read_listed_agents(environ)
+    verb = " ".join(LIST_AGENTS_ARGV)
+    if listed is None:
+        lines.append(f"Written; not verified: `{verb}` did not answer.")
+        return Outcome(EXIT_OK, lines)
+    if agent not in listed:
+        lines.append(
+            f"WARNING: `{verb}` does not list {agent!r}: the `session` on your "
+            "PATH looks in another agents folder ($AGENTS_DIR, or another sessiontools)."
+        )
+        return Outcome(EXIT_REFUSED, lines)
+    lines.append(f"{verb}: lists {agent!r}.")
+    return Outcome(EXIT_OK, lines)
+
+
+# --- the ears' model: read, never fetched -------------------------------------
+
+# sessionvoice's read-only probe. Its last line is `silero    ok: PATH` or
+# `silero    no model: ears install` (sessionvoice 0.2.1, `ears backends`).
+EARS_BACKENDS_ARGV = ("ears", "backends")
+# The probe answers in well under a second; a slow one is never waited on.
+EARS_PROBE_TIMEOUT = 5.0
+EARS_MODEL_LINE = (
+    "The ears have no voice-activity model, so they cannot hear you: "
+    "run `ears install` to fetch it."
+)
+
+
+def ears_model_missing(environ: Mapping[str, str]) -> bool:
+    """True only when `ears backends` answers, exit 0, with a `silero` line
+    saying `no model`. `ears` not on the PATH (no voice here), a timeout, a
+    failure or output we do not know all read as False: say nothing. Setup
+    never runs `ears install`; the user does."""
+    done = _run(EARS_BACKENDS_ARGV, environ, timeout=EARS_PROBE_TIMEOUT)
+    if done is None or done.returncode != 0:
+        return False
+    for line in (done.stdout or "").splitlines():
+        name, _, state = line.strip().partition(" ")
+        if name == "silero":
+            return state.strip().startswith("no model")
+    return False
+
+
 # --- the run ------------------------------------------------------------------
 
 
@@ -513,21 +716,25 @@ def run_setup(
     *,
     mailbox: str | None = None,
     address: str | None = None,
+    agent: str = DEFAULT_AGENT,
     dry_run: bool = False,
     home: Path | None = None,
     environ: Mapping[str, str] | None = None,
 ) -> Outcome:
-    """The stranded check, then mail, then the operator; both halves print.
+    """The stranded check, then mail, the operator and the agent; all print.
 
     An operator file stranded at the 0.1.0 place, with none at the new one,
     stops the whole run before mail: nothing is made or written, one line.
     The verb would otherwise make the operator's box from settings that
-    cannot see that file. Past it, both halves always run. Mail goes first
+    cannot see that file. Past it, all three always run. Mail goes first
     because the operator is written only for a box that exists, and the
-    mail setup verb is what makes the operator's box. The exit is the worse
-    of the two: 1 if either refused or failed, else 4 if mail left steps
-    for you, else 0. MAILBOX / ADDRESS are already shape-checked by the
-    caller.
+    mail setup verb is what makes the operator's box and the agent's. The
+    exit is the worst of the three: 1 if any refused or failed, else 4 if
+    mail left steps for you, else 0. Then `ears backends` is asked, read
+    only: when the ears' model is missing, one line (EARS_MODEL_LINE) names
+    `ears install`; it never changes the exit. With the agent defined, the
+    run ends on the one launch step (LAUNCH_SENTENCE). MAILBOX / ADDRESS /
+    AGENT are already shape-checked by the caller.
     """
     environ = os.environ if environ is None else environ
     resolved = Path.home() if home is None else home
@@ -538,18 +745,32 @@ def run_setup(
     # sessionmail's default carrier, and postfix is the user's opt-in.
     # `--write-maps` is never passed: writing postfix maps is opt-in too.
     mail = run_mail_setup(
-        boxes=mail_setup_boxes(mailbox, address), dry_run=dry_run, environ=environ
+        boxes=mail_setup_boxes(mailbox, address, agent),
+        dry_run=dry_run,
+        environ=environ,
     )
     operator = run_operator(
         mailbox=mailbox, address=address, dry_run=dry_run, home=home, environ=environ
     )
-    if EXIT_REFUSED in (mail.code, operator.code):
+    defined = run_agent(agent=agent, dry_run=dry_run, home=resolved, environ=environ)
+    codes = (mail.code, operator.code, defined.code)
+    if EXIT_REFUSED in codes:
         code = EXIT_REFUSED
-    elif EXIT_STEPS_LEFT in (mail.code, operator.code):
+    elif EXIT_STEPS_LEFT in codes:
         code = EXIT_STEPS_LEFT
     else:
         code = EXIT_OK
-    return Outcome(code, mail.lines + operator.lines)
+    lines = mail.lines + operator.lines + defined.lines
+    if dry_run:
+        lines.append(
+            f"Would ask `{_verb()}` for the agent's box {agent!r} (--box {agent})."
+        )
+    # Read only, and never part of the exit: 4 means mail steps are left.
+    if ears_model_missing(environ):
+        lines.append(EARS_MODEL_LINE)
+    if defined.code == EXIT_OK:
+        lines.append(launch_sentence(agent))
+    return Outcome(code, lines)
 
 
 def run_operator(

sessionkit-0.2.0/PKG-INFO

@@ -1,18 +0,0 @@
-Metadata-Version: 2.4
-Name: sessionkit
-Version: 0.2.0
-Summary: Session Kit gives your Claude Code sessions voice, mail, a phone line and a tmux sidebar, in one install.
-Author: Mike Bailey
-Author-email: Mike Bailey <mike@sessionkit.ai>
-License-Expression: AGPL-3.0-or-later
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Requires-Dist: click>=8.1
-Requires-Dist: sessionmail>=0.1.0
-Requires-Dist: sessiontools>=0.1.0
-Requires-Dist: sessionphone>=0.1.0
-Requires-Dist: sessionview>=0.1.0
-Requires-Dist: sessionvoice[capture]>=0.1.0
-Requires-Python: >=3.11, <3.15
-Project-URL: Homepage, https://github.com/sessionkit/sessionkit
-Project-URL: Repository, https://github.com/sessionkit/sessionkit