liaise 0.0.2__tar.gz

liaise-0.0.2/.claude/skills/liaise/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: liaise
+description: Use when onboarding a new partner to liaise, checking what liaise is waiting on or has done (liaise status / liaise poll), or explaining what a liaise: state label on a GitHub issue means. Triggers on "add a partner to liaise", "onboard <name> to liaise", "what's liaise waiting on", "check liaise status", "what does liaise:needs-owner mean", "why hasn't liaise picked up this issue".
+---
+
+# liaise: the owner's agent skill
+
+`liaise` runs the loop between a non-technical partner and a coding agent, over GitHub issues. This skill is for the owner's own agent — the one helping the owner run `liaise`, not the one `liaise` dispatches to do the work.
+
+## Onboarding a new partner
+
+Every partner is one config file plus one brief file, both under `~/.config/liaise/`. Nothing about a partner belongs in the `liaise` package itself.
+
+1. Pick a short slug (e.g. `pat`).
+2. Write `~/.config/liaise/partners/<slug>.toml` — at minimum `display_name`, `github_logins`, `repo`, `brief`. See the package README's quick start for the full shape, including `dispatch`, `verify`, `deploy`, `escalate`, and any global default you want to override for just this partner.
+3. Write `~/.config/liaise/briefs/<slug>.md` — how to talk to this partner: tone, what they care about, which decisions are theirs and which are the owner's. This goes verbatim into every prompt the coding agent sees for their issues.
+4. Run `liaise setup <slug>` — creates the partner's label and every `liaise:` state label in their repo. Safe to re-run.
+5. Run `liaise poll --partner <slug>` to confirm `liaise` sees their issues and is computing readiness correctly.
+6. If not already installed, `liaise schedule install` sets up the recurring job (once, covers every partner).
+
+## Reading `liaise status`
+
+`liaise status` reports, per partner: how long ago `liaise` last ran (a stale age past a couple of minutes past the schedule interval means the scheduled job stopped — check `liaise schedule status`), today's dispatch count against the daily cap, and every issue currently in `liaise:needs-owner`. That last list is the actual to-do list — everything else in the loop is either waiting on the partner or already handled.
+
+## What each `liaise:` label means
+
+Exactly one of these is on a `liaise`-tracked issue at a time. `liaise` never closes an issue — that's the partner's or the owner's call.
+
+| Label | What it means | Who set it |
+|---|---|---|
+| `liaise:intake` | Seen. The partner may still be writing, or the quiet window is running. | liaise |
+| `liaise:paused` | The partner asked to wait (a `#wait#` marker). | liaise |
+| `liaise:working` | A coding agent is dispatched and running right now. | liaise |
+| `liaise:needs-partner` | The agent asked a question and is waiting on the partner to answer. | the agent |
+| `liaise:needs-owner` | Needs the owner: an escalation, a decision, or a crashed/stuck run. | the agent, or liaise on a crash or the daily budget cap |
+| `liaise:deployed` | Live. The partner has been told to try it. | the agent, or liaise after a batch deploy |
+| `liaise:budget` | Today's dispatch cap was hit for this partner. Resumes tomorrow. | liaise |
+
+A `liaise:needs-owner` issue is where the owner's own judgment is actually needed — an escalation the agent declined to make alone, or reconciliation after something crashed. Read the issue thread and the dispatch log path (if `liaise` notified with one) before deciding what to do; the label alone only tells you that a decision is due, not what it is.
+
+## Why an issue isn't moving
+
+- **Still in `liaise:intake` well past the quiet window?** Check `liaise poll` — a marker or a comment from someone who isn't the partner (including the owner) never restarts or shortens the clock, only the partner's own edits and comments do.
+- **Nothing happening at all?** `liaise status`'s `last_run` age is the first thing to check — a stale scheduled job looks exactly like an unready issue from the partner's side.
+- **Hit the daily cap?** `liaise:budget` resumes automatically the next day; there's nothing to do.

liaise-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

liaise-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
+# tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
+# transport (the default below) needs a tag from a release after 0.2.14 —
+# older tags don't declare that secret and GitHub then rejects the
+# workflow at parse time.
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Transport: this repo's whole `secrets` context, serialized into the one
+    # secret the reusable workflow declares. Double-encoded (toJSON twice) so
+    # the value is a single line — a multiline secret would register its `{`
+    # and `}` lines as global log masks. Any secret name works; there is no
+    # fixed list to fall outside of. (Cross-owner `secrets: inherit` does not
+    # propagate secrets, so it cannot replace this.)
+    #
+    # Note this hands EVERY secret this repo can read — including org-level
+    # ones — to the called workflow. For a minimal secret surface (only the
+    # names you list), regenerate with
+    #   wads-migrate ci-to-stub --transport named
+    #
+    # *Which* of these become job env vars — and which are required — is
+    # driven entirely by [tool.wads.ci.env] in pyproject.toml; nothing is
+    # exported unless declared there (`wads-secrets add VAR_NAME` declares
+    # one and can set its value). Non-sensitive values don't need a secret:
+    # use [tool.wads.ci.env].defaults (committed literals) or a repository
+    # *variable* (`gh variable set NAME`) — declared names fall back to
+    # repo variables automatically.
+    secrets:
+      WADS_CI_SECRETS_JSON: ${{ toJSON(toJSON(secrets)) }}

liaise-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

liaise-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+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.

liaise-0.0.2/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: liaise
+Version: 0.0.2
+Summary: Run the loop between a non-technical partner who tests an app and a coding agent that answers, fixes, builds and redeploys — over GitHub issues
+Project-URL: Homepage, https://github.com/thorwhalen/liaise
+Project-URL: Repository, https://github.com/thorwhalen/liaise
+Project-URL: Documentation, https://thorwhalen.github.io/liaise
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cw
+Requires-Dist: dol
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# liaise
+
+`liaise` runs the loop between a non-technical partner who tests an app and a coding agent that answers, fixes, builds and redeploys — over GitHub issues. The partner files what they notice as a GitHub issue; `liaise` watches the repo, waits until they've finished writing, hands the ready issue to a coding agent, and keeps the state visible on the issue itself, so nobody has to learn a tool or a syntax to be part of the loop.
+
+## Quick start
+
+```
+pip install liaise
+mkdir -p ~/.config/liaise/partners ~/.config/liaise/briefs
+cat > ~/.config/liaise/config.toml <<'EOF'
+owner_login = "you"
+state_dir = "~/.local/share/liaise"
+EOF
+cat > ~/.config/liaise/partners/pat.toml <<'EOF'
+display_name = "Pat"
+github_logins = ["pat"]
+repo = "example/app"
+brief = "~/.config/liaise/briefs/pat.md"
+EOF
+echo "Pat likes short, plain answers and hates surprises." > ~/.config/liaise/briefs/pat.md
+liaise setup pat
+liaise poll
+```
+
+That's read-only by default (non-negotiable #4) — `poll` reports Pat's issues and their readiness without changing anything. Once you believe the plan it shows, `liaise run --once --dry-run` prints what a real pass would do, still without acting; drop `--dry-run` to actually act; and `liaise schedule install` sets up the recurring job once you're ready to stop running it by hand.
+
+That's a working loop for one partner (`pat`, testing the fictional `example/app`) polling every couple of minutes. Add more partners by adding more files under `partners/` and `briefs/`.
+
+## Concepts
+
+**Partners.** Everything about a partner — who they are on GitHub, which repo they test, how to talk to them, what commands verify and deploy their app — is one TOML file under `~/.config/liaise/partners/`. Nothing about a partner ever lives in this package's code.
+
+**Issues are the channel.** A partner (or an app filing on their behalf) opens a GitHub issue. `liaise` decides an issue is theirs by author or by a `partner:<slug>` label, and only ever reads their own activity — a comment from anyone else, including the owner, never moves the clock.
+
+**Readiness.** `liaise` waits for a quiet window after the partner's last word before treating an issue as ready, so a request written across three comments doesn't get grabbed mid-sentence. A partner can speed that up with a `#startwork#` marker in their text, or pause it with `#wait#` — both optional, and neither is required to use `liaise` at all.
+
+**State labels.** Exactly one `liaise:` label is on an issue at a time: `intake`, `paused`, `working`, `needs-partner`, `needs-owner`, `deployed`, or `budget`. That label is the entire state machine — read it on the issue, and you know exactly where things stand. `liaise` never closes an issue; that's the partner's or the owner's call.
+
+**Dispatch.** A ready issue gets handed to a coding agent (headless `claude` by default) with a composed prompt: the packaged operating rules, the partner's brief, the issue, which label to set on each exit path, the verify/deploy commands, and a budget. The agent asks questions in the thread, does the work in the repo's own conventions (branch, PR, CI, land), and reports back through the label.
+
+**Batch or per-issue deploy.** With `deploy_per = "batch"` (the default), the agent lands each ready issue without deploying, and `liaise` runs the deploy command once after processing every ready issue, then tells each partner it's live. With `deploy_per = "issue"`, the agent deploys and posts itself.
+
+**Budgets.** A per-dispatch timeout and turn cap, and a daily dispatch cap per partner — mandatory, not optional. Hitting the daily cap is a visible `liaise:budget` label, never silence.
+
+**Notifications.** `liaise` has no dashboard. When something needs the owner — a crash, an escalation, a budget cap — it's a label plus an `ntfy` push if `LIAISE_NTFY_TOPIC` (or whatever `notify.ntfy_topic_env` names) is set. Unset, it's silent, never an error.
+
+**Scheduling.** `liaise schedule install` sets up a launchd agent (macOS) or a systemd user timer (Linux) that runs `liaise run --once` every minute or two, with an environment snapshot taken at install time — both schedulers otherwise hand a job a nearly empty environment.
+
+## Commands
+
+- `liaise setup <partner>` — create the partner's label and every state label in their repo. Idempotent.
+- `liaise poll [--partner SLUG]` — report every partner issue, its state, and a readiness countdown. Changes nothing.
+- `liaise run [--once] [--dry-run] [--partner SLUG]` — intake, label, dispatch ready issues, batch-deploy, reconcile. `--dry-run` prints the plan and changes nothing.
+- `liaise status` — the last run's age, today's dispatch counts, and anything waiting on the owner.
+- `liaise partner list` / `liaise partner show <slug>` — see the resolved config, defaults applied.
+- `liaise schedule install` / `uninstall` / `status` — manage the scheduled job.
+
+## Design
+
+The non-negotiables (nothing personal in the package, `gh` as the only GitHub credential, labels as the state machine, read-only by default, mandatory budgets, and the rest) are worth reading if you're extending `liaise` rather than just running it — see the design discussion linked from the project's GitHub repository.

liaise-0.0.2/README.md

@@ -0,0 +1,60 @@
+# liaise
+
+`liaise` runs the loop between a non-technical partner who tests an app and a coding agent that answers, fixes, builds and redeploys — over GitHub issues. The partner files what they notice as a GitHub issue; `liaise` watches the repo, waits until they've finished writing, hands the ready issue to a coding agent, and keeps the state visible on the issue itself, so nobody has to learn a tool or a syntax to be part of the loop.
+
+## Quick start
+
+```
+pip install liaise
+mkdir -p ~/.config/liaise/partners ~/.config/liaise/briefs
+cat > ~/.config/liaise/config.toml <<'EOF'
+owner_login = "you"
+state_dir = "~/.local/share/liaise"
+EOF
+cat > ~/.config/liaise/partners/pat.toml <<'EOF'
+display_name = "Pat"
+github_logins = ["pat"]
+repo = "example/app"
+brief = "~/.config/liaise/briefs/pat.md"
+EOF
+echo "Pat likes short, plain answers and hates surprises." > ~/.config/liaise/briefs/pat.md
+liaise setup pat
+liaise poll
+```
+
+That's read-only by default (non-negotiable #4) — `poll` reports Pat's issues and their readiness without changing anything. Once you believe the plan it shows, `liaise run --once --dry-run` prints what a real pass would do, still without acting; drop `--dry-run` to actually act; and `liaise schedule install` sets up the recurring job once you're ready to stop running it by hand.
+
+That's a working loop for one partner (`pat`, testing the fictional `example/app`) polling every couple of minutes. Add more partners by adding more files under `partners/` and `briefs/`.
+
+## Concepts
+
+**Partners.** Everything about a partner — who they are on GitHub, which repo they test, how to talk to them, what commands verify and deploy their app — is one TOML file under `~/.config/liaise/partners/`. Nothing about a partner ever lives in this package's code.
+
+**Issues are the channel.** A partner (or an app filing on their behalf) opens a GitHub issue. `liaise` decides an issue is theirs by author or by a `partner:<slug>` label, and only ever reads their own activity — a comment from anyone else, including the owner, never moves the clock.
+
+**Readiness.** `liaise` waits for a quiet window after the partner's last word before treating an issue as ready, so a request written across three comments doesn't get grabbed mid-sentence. A partner can speed that up with a `#startwork#` marker in their text, or pause it with `#wait#` — both optional, and neither is required to use `liaise` at all.
+
+**State labels.** Exactly one `liaise:` label is on an issue at a time: `intake`, `paused`, `working`, `needs-partner`, `needs-owner`, `deployed`, or `budget`. That label is the entire state machine — read it on the issue, and you know exactly where things stand. `liaise` never closes an issue; that's the partner's or the owner's call.
+
+**Dispatch.** A ready issue gets handed to a coding agent (headless `claude` by default) with a composed prompt: the packaged operating rules, the partner's brief, the issue, which label to set on each exit path, the verify/deploy commands, and a budget. The agent asks questions in the thread, does the work in the repo's own conventions (branch, PR, CI, land), and reports back through the label.
+
+**Batch or per-issue deploy.** With `deploy_per = "batch"` (the default), the agent lands each ready issue without deploying, and `liaise` runs the deploy command once after processing every ready issue, then tells each partner it's live. With `deploy_per = "issue"`, the agent deploys and posts itself.
+
+**Budgets.** A per-dispatch timeout and turn cap, and a daily dispatch cap per partner — mandatory, not optional. Hitting the daily cap is a visible `liaise:budget` label, never silence.
+
+**Notifications.** `liaise` has no dashboard. When something needs the owner — a crash, an escalation, a budget cap — it's a label plus an `ntfy` push if `LIAISE_NTFY_TOPIC` (or whatever `notify.ntfy_topic_env` names) is set. Unset, it's silent, never an error.
+
+**Scheduling.** `liaise schedule install` sets up a launchd agent (macOS) or a systemd user timer (Linux) that runs `liaise run --once` every minute or two, with an environment snapshot taken at install time — both schedulers otherwise hand a job a nearly empty environment.
+
+## Commands
+
+- `liaise setup <partner>` — create the partner's label and every state label in their repo. Idempotent.
+- `liaise poll [--partner SLUG]` — report every partner issue, its state, and a readiness countdown. Changes nothing.
+- `liaise run [--once] [--dry-run] [--partner SLUG]` — intake, label, dispatch ready issues, batch-deploy, reconcile. `--dry-run` prints the plan and changes nothing.
+- `liaise status` — the last run's age, today's dispatch counts, and anything waiting on the owner.
+- `liaise partner list` / `liaise partner show <slug>` — see the resolved config, defaults applied.
+- `liaise schedule install` / `uninstall` / `status` — manage the scheduled job.
+
+## Design
+
+The non-negotiables (nothing personal in the package, `gh` as the only GitHub credential, labels as the state machine, read-only by default, mandatory budgets, and the rest) are worth reading if you're extending `liaise` rather than just running it — see the design discussion linked from the project's GitHub repository.

liaise-0.0.2/liaise/__init__.py

@@ -0,0 +1,86 @@
+"""liaise — the loop between a non-technical partner and a coding agent, over GitHub issues."""
+
+from liaise.config import (
+    Budget,
+    Config,
+    ConfigError,
+    DispatchConfig,
+    EscalateConfig,
+    GlobalConfig,
+    Markers,
+    NotifyConfig,
+    PartnerConfig,
+    load_config,
+)
+from liaise.github import Comment, FakeGitHub, GhCli, GitHub, GitHubError, Issue
+from liaise.intake import (
+    Readiness,
+    compute_readiness,
+    find_partner_issues,
+    is_partner_issue,
+    last_partner_activity,
+)
+from liaise.state import STATE_LABELS, current_state, set_state, state_label
+from liaise.state import setup as setup_labels
+from liaise.dispatch import (
+    ClaudeHeadless,
+    DispatchOutcome,
+    DispatchResult,
+    Dispatcher,
+    EchoDispatcher,
+    Job,
+    daily_dispatch_count,
+    dispatch_issue,
+    stored_session_id,
+)
+from liaise.notify import notify
+from liaise.prompt import compose_prompt
+from liaise.run import PlanItem, RunReport, last_run_age, run_once
+from liaise.schedule import install_schedule, schedule_status, uninstall_schedule
+
+__all__ = [
+    "Budget",
+    "ClaudeHeadless",
+    "Comment",
+    "Config",
+    "ConfigError",
+    "DispatchConfig",
+    "DispatchOutcome",
+    "DispatchResult",
+    "Dispatcher",
+    "EchoDispatcher",
+    "EscalateConfig",
+    "FakeGitHub",
+    "GhCli",
+    "GitHub",
+    "GitHubError",
+    "GlobalConfig",
+    "Issue",
+    "Job",
+    "Markers",
+    "NotifyConfig",
+    "PartnerConfig",
+    "PlanItem",
+    "Readiness",
+    "RunReport",
+    "STATE_LABELS",
+    "compose_prompt",
+    "compute_readiness",
+    "current_state",
+    "daily_dispatch_count",
+    "dispatch_issue",
+    "find_partner_issues",
+    "install_schedule",
+    "is_partner_issue",
+    "last_partner_activity",
+    "last_run_age",
+    "load_config",
+    "notify",
+    "run_once",
+    "schedule_status",
+    "set_state",
+    "setup_labels",
+    "state_label",
+    "stored_session_id",
+    "uninstall_schedule",
+]

liaise-0.0.2/liaise/__main__.py

@@ -0,0 +1,16 @@
+# PYTHON_ARGCOMPLETE_OK
+"""``python -m liaise`` — CLI entry point."""
+
+import cw
+
+from liaise.cli import _dispatch_config, _dispatch_funcs
+
+
+def main():
+    raise SystemExit(
+        cw.dispatch(_dispatch_funcs, config=_dispatch_config, prog="liaise")
+    )
+
+
+if __name__ == "__main__":
+    main()