talis-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{talis_cli-0.2.0 → talis_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talis-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: Command-line client for the Talis trading platform. Sign in via device flow, manage sessions, view portfolio, place orders.
 Author: Talis
 License-Expression: Apache-2.0
@@ -114,6 +114,27 @@ suitable for parsing from scripts or LLM agents. Force JSON anywhere with
 The CLI stores its session token at `~/.talis/credentials` with `chmod 600`
 on POSIX systems. The token is a JWT; treat it like any other credential.
 
+### Sessions renew themselves
+
+You should not have to think about session expiry. When the CLI or the MCP
+server runs with under 48 hours left on the clock, it renews in place against
+`POST /auth/session/refresh` before doing its work — at most once every 15
+minutes, so a burst of commands costs one renewal, not one each. Renewal
+preserves the
+session's **original grant**, not a fresh maximum — a token issued with a 24h
+life renews to another 24h, never to something longer. That is deliberate: an
+auto-renewing session must not be able to ratchet itself into a longer-lived
+credential than the one you approved.
+
+Renewal is best-effort and silent: if it cannot happen, your existing
+credential is left untouched and the command still runs. What you WILL see is a
+`session_warning` on MCP tool responses once renewal stops keeping up, or when
+under six hours remain. If that appears and keeps counting down, renewal is
+failing — run `talis login` to sign in again.
+
+A steady `session_hours_remaining` with no `session_warning` is the healthy
+state, not a countdown to worry about.
+
 ## Relationship to `cli/jarvis_cli.sh`
 
 The bash script at [`cli/jarvis_cli.sh`](../../cli/jarvis_cli.sh) is the legacy
@@ -142,12 +163,16 @@ your portfolio, pull Talis Research, place paper trades, create strategies,
 set price alerts, and talk to the Talis chat agent. Log in first
 (`talis login`); the server authenticates as the logged-in user.
 
-Add it to **Claude Code**:
+Install and add it to **Claude Code**:
 
 ```bash
+pip install talis-cli        # or: uv tool install talis-cli
+talis login                  # device-flow browser approval, once
 claude mcp add talis -- talis mcp
 ```
 
+No local checkout required — `talis` is on PyPI.
+
 Or to **Claude Desktop** (and other clients using the `mcpServers` config
 shape) — `claude_desktop_config.json`:
 
@@ -162,14 +187,26 @@ shape) — `claude_desktop_config.json`:
 }
 ```
 
-Tools: `whoami`, `portfolio`, `balance`, `research`, `packets`,
-`brief_latest`, `history`, `buy`, `sell`, `close`, `create_strategy`, `chat`,
-`notifications_create`.
+Tools (25):
+
+`amend_strategy`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
+`cancel_order`, `chat`, `close`, `create_strategy`, `history`,
+`notifications_create`, `open_orders`, `outcomes`, `packets`, `place_order`,
+`portfolio`, `research`, `sell`, `start_strategy`, `stop_strategy`,
+`strategies`, `strategy`, `strategy_activity`, `validate_strategy`, `whoami`.
+
+**Safety — read this before pointing an agent at it.** The trading tools
+(`buy` / `sell` / `close` / `create_strategy`) execute with **REAL MONEY by
+default** (`paper=False`). Pass `paper=True` to simulate instead.
+
+`buy`, `sell` and `create_strategy` additionally refuse to spend real money
+unless the caller passes `confirm_real_money=True`. `close` deliberately has no
+such gate: a protective exit must never be blocked by a missing flag.
+`place_order` (limit orders, spot, HIP-4 outcome markets) has **no paper mode
+at all** and refuses without `confirm_real_money=True`.
 
-**Safety**: the trading tools (`buy` / `sell` / `close` / `create_strategy`)
-default to `paper=True` — an isolated simulated book. An agent must pass
-`paper=False` explicitly to trade real money. Set `TALIS_PAPER=1` in the
-server's environment to force paper mode regardless of tool arguments.
+Set `TALIS_PAPER=1` in the server's environment to force paper mode regardless
+of tool arguments.
 Withdrawals and wallet creation are not exposed over MCP. For a strictly
 read-only agent, log in with `talis login --read-only` — the server rejects
 every mutation at the API layer.

{talis_cli-0.2.0 → talis_cli-0.2.1}/README.md

@@ -86,6 +86,27 @@ suitable for parsing from scripts or LLM agents. Force JSON anywhere with
 The CLI stores its session token at `~/.talis/credentials` with `chmod 600`
 on POSIX systems. The token is a JWT; treat it like any other credential.
 
+### Sessions renew themselves
+
+You should not have to think about session expiry. When the CLI or the MCP
+server runs with under 48 hours left on the clock, it renews in place against
+`POST /auth/session/refresh` before doing its work — at most once every 15
+minutes, so a burst of commands costs one renewal, not one each. Renewal
+preserves the
+session's **original grant**, not a fresh maximum — a token issued with a 24h
+life renews to another 24h, never to something longer. That is deliberate: an
+auto-renewing session must not be able to ratchet itself into a longer-lived
+credential than the one you approved.
+
+Renewal is best-effort and silent: if it cannot happen, your existing
+credential is left untouched and the command still runs. What you WILL see is a
+`session_warning` on MCP tool responses once renewal stops keeping up, or when
+under six hours remain. If that appears and keeps counting down, renewal is
+failing — run `talis login` to sign in again.
+
+A steady `session_hours_remaining` with no `session_warning` is the healthy
+state, not a countdown to worry about.
+
 ## Relationship to `cli/jarvis_cli.sh`
 
 The bash script at [`cli/jarvis_cli.sh`](../../cli/jarvis_cli.sh) is the legacy
@@ -114,12 +135,16 @@ your portfolio, pull Talis Research, place paper trades, create strategies,
 set price alerts, and talk to the Talis chat agent. Log in first
 (`talis login`); the server authenticates as the logged-in user.
 
-Add it to **Claude Code**:
+Install and add it to **Claude Code**:
 
 ```bash
+pip install talis-cli        # or: uv tool install talis-cli
+talis login                  # device-flow browser approval, once
 claude mcp add talis -- talis mcp
 ```
 
+No local checkout required — `talis` is on PyPI.
+
 Or to **Claude Desktop** (and other clients using the `mcpServers` config
 shape) — `claude_desktop_config.json`:
 
@@ -134,14 +159,26 @@ shape) — `claude_desktop_config.json`:
 }
 ```
 
-Tools: `whoami`, `portfolio`, `balance`, `research`, `packets`,
-`brief_latest`, `history`, `buy`, `sell`, `close`, `create_strategy`, `chat`,
-`notifications_create`.
+Tools (25):
+
+`amend_strategy`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
+`cancel_order`, `chat`, `close`, `create_strategy`, `history`,
+`notifications_create`, `open_orders`, `outcomes`, `packets`, `place_order`,
+`portfolio`, `research`, `sell`, `start_strategy`, `stop_strategy`,
+`strategies`, `strategy`, `strategy_activity`, `validate_strategy`, `whoami`.
+
+**Safety — read this before pointing an agent at it.** The trading tools
+(`buy` / `sell` / `close` / `create_strategy`) execute with **REAL MONEY by
+default** (`paper=False`). Pass `paper=True` to simulate instead.
+
+`buy`, `sell` and `create_strategy` additionally refuse to spend real money
+unless the caller passes `confirm_real_money=True`. `close` deliberately has no
+such gate: a protective exit must never be blocked by a missing flag.
+`place_order` (limit orders, spot, HIP-4 outcome markets) has **no paper mode
+at all** and refuses without `confirm_real_money=True`.
 
-**Safety**: the trading tools (`buy` / `sell` / `close` / `create_strategy`)
-default to `paper=True` — an isolated simulated book. An agent must pass
-`paper=False` explicitly to trade real money. Set `TALIS_PAPER=1` in the
-server's environment to force paper mode regardless of tool arguments.
+Set `TALIS_PAPER=1` in the server's environment to force paper mode regardless
+of tool arguments.
 Withdrawals and wallet creation are not exposed over MCP. For a strictly
 read-only agent, log in with `talis login --read-only` — the server rejects
 every mutation at the API layer.

{talis_cli-0.2.0 → talis_cli-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "talis-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "Command-line client for the Talis trading platform. Sign in via device flow, manage sessions, view portfolio, place orders."
 readme = "README.md"
 license = "Apache-2.0"

{talis_cli-0.2.0 → talis_cli-0.2.1}/talis/cli.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 import typer
 
-from . import __version__, output
+from . import __version__, config, output
 from .commands import auth, mcp_server, trade
 from .commands import chat as chat_cmd
 from .commands import guide as guide_cmd
@@ -83,6 +83,71 @@ app.add_typer(fund_app, name="fund")
 app.command("deposit")(__import__("talis.commands.fund",fromlist=["deposit"]).deposit)
 
 
+# Commands that must NEVER trigger a renewal.
+#   login/signup/approve — there is no session yet to renew.
+#   logout — we are about to revoke the session we hold; renewing it first is
+#     wasted work and muddies the audit trail.
+#   version — must stay answerable with no credentials and no network at all.
+_NO_RENEW = frozenset({"login", "signup", "approve", "logout", "version"})
+
+# Minimum gap between renewal attempts across separate CLI invocations.
+_RENEW_COOLDOWN_SECONDS = 900.0
+
+
+def _renewed_recently() -> bool:
+    """True when the stored credential was rewritten inside the cooldown.
+
+    WHY A COOLDOWN AT ALL. ensure_fresh fires whenever under 48h remain, but a
+    session's grant is 24h — permanently under that threshold. Without a gate,
+    wiring renewal into the CLI would mint a new JWT and pay a network
+    round-trip on EVERY command, forever.
+
+    WHY MTIME rather than a new state file. The MCP server uses an in-memory
+    cooldown, which cannot work here: a CLI process is born and dies per
+    command. The credentials file's mtime is ALREADY an exact record of the
+    last SUCCESSFUL renewal (renewal rewrites it via atomic replace), so use
+    that instead of inventing a second source of truth that could disagree
+    with the first.
+
+    A FAILED renewal leaves mtime untouched, so a broken renewal keeps being
+    retried rather than being silenced by its own failure — the behaviour we
+    want, obtained for free.
+    """
+    import os
+    import time as _t
+    try:
+        age = _t.time() - os.stat(str(config.credentials_path())).st_mtime
+    except OSError:
+        return False          # unreadable/absent: let ensure_fresh decide
+    # A negative age means the clock moved; treat it as recent so a skewed
+    # machine backs off rather than renewing in a tight loop.
+    return age < _RENEW_COOLDOWN_SECONDS
+
+
+@app.callback()
+def _keep_session_alive(ctx: typer.Context) -> None:
+    """Renew a short-lived session before running the command.
+
+    WHY THIS EXISTS: renewal was wired into the MCP server only, so a human
+    running `talis portfolio` every day still watched their session run out —
+    the CLI shipped the renewal code and never called it. The README promised
+    otherwise. This is the code catching up to the claim.
+
+    Best-effort BY CONTRACT: any failure leaves the stored credential exactly
+    as it was and the command runs anyway. config.ensure_fresh also no-ops
+    without touching the network unless the session is genuinely short, so this
+    costs nothing on the overwhelming majority of invocations.
+    """
+    if ctx.invoked_subcommand in _NO_RENEW or _renewed_recently():
+        return
+    try:
+        creds = config.load()
+        if creds:
+            config.ensure_fresh(creds)
+    except Exception:
+        pass
+
+
 @app.command("version")
 def version(json_: bool = typer.Option(False, "--json", help="JSON output.")) -> None:
     """Print the CLI version."""

{talis_cli-0.2.0 → talis_cli-0.2.1}/talis/commands/mcp_server.py

@@ -64,9 +64,31 @@ class NotLoggedInError(RuntimeError):
 # warning, because the tool being used is the only one guaranteed to be seen.
 _SESSION_WARN_HOURS = 48.0
 
+# Below this the session is genuinely at risk and we warn however healthy
+# renewal looks. Above it, a session that is renewing on schedule is NOT news.
+#
+# WHY THIS SECOND TIER EXISTS: /auth/session/refresh deliberately carries the
+# ORIGINAL grant rather than issuing a fresh maximum-length one — a token minted
+# with a 24h life renews to 24h, never to 7d. That is the token-lifetime ceiling
+# working as designed. But it means a perfectly self-renewing session sits
+# permanently at ~24h, which is permanently under a 48h warn floor. Warning on
+# that alone emitted SESSION EXPIRES on every single tool response forever — one
+# second after a successful renewal included. And because the warning is
+# deliberately hoisted to the FRONT of the dict, it was the first thing the model
+# read on every call. A warning that always fires is one the reader learns to
+# skip, including on the day renewal actually breaks.
+_SESSION_CRITICAL_HOURS = 6.0
+
+# What the last renewal attempt actually ACHIEVED. Written by _maybe_renew, read
+# below to tell "short grant, renewing fine" apart from "renewal is broken".
+# Starts "unknown" and "unknown" warns: absence of evidence that renewal works
+# is not evidence that it does.
+_RENEW_OUTCOME = ["unknown"]  # unknown | renewed | not_needed | failed
+_RENEW_HEALTHY = ("renewed", "not_needed")
+
 
 def _session_expiry_warning(creds) -> dict:
-    """{} when the session is comfortably alive, else a loud actionable dict."""
+    """{} when the session is alive AND renewing, else a loud actionable dict."""
     raw = getattr(creds, "expires_at", None)
     if not raw:
         return {}
@@ -84,17 +106,21 @@ def _session_expiry_warning(creds) -> dict:
     if hours <= 0:
         return {"session_expired": True,
                 "session_warning": (
-                    f"SESSION EXPIRED at {raw}. Every call will now fail. Renew with "
-                    "`talis_token_refresh.py --force` (admin key), or a human "
-                    "can run `talis login`.")}
-    return {"session_hours_remaining": round(hours, 1),
+                    f"SESSION EXPIRED at {raw}. Every call will now fail. "
+                    "Automatic renewal did not save it — run `talis login` to "
+                    "sign in again.")}
+    # Always REPORT the number; raise the ALARM only when renewal is not holding
+    # the line. Readers key off `session_warning`, never off this field.
+    remaining = {"session_hours_remaining": round(hours, 1)}
+    if hours > _SESSION_CRITICAL_HOURS and _RENEW_OUTCOME[0] in _RENEW_HEALTHY:
+        return remaining
+    return {**remaining,
             "session_warning": (
-                f"SESSION EXPIRES IN {hours:.1f} HOURS ({raw}). The token itself carries no "
-                "refresh token, but tools/talis-cli/talis_token_refresh.py "
-                "re-mints it via POST /auth/tokens and is installed as a "
-                "LaunchAgent (com.talis.token-refresh, every 6h, renews under "
-                "8h remaining). If this warning keeps counting down below 8h, "
-                "that job is NOT running — check ~/.talis/token-refresh.log.")}
+                f"SESSION EXPIRES IN {hours:.1f} HOURS ({raw}). This client "
+                "renews itself against POST /auth/session/refresh as you use "
+                "it, but the last attempt did not extend the session. If this "
+                "keeps counting down, renewal is failing — run `talis login` "
+                "to sign in again before it expires.")}
 
 
 _LAST_RENEW_ATTEMPT = [0.0]
@@ -111,7 +137,9 @@ def _maybe_renew() -> None:
     and config.ensure_fresh itself no-ops unless the session is actually short.
 
     Silent by contract: a renewal that cannot happen must never turn into a
-    tool error. The session_warning that follows is what tells the reader.
+    tool error. The session_warning that follows is what tells the reader — and
+    it can only tell the truth if this records what actually happened, so every
+    exit path here writes _RENEW_OUTCOME.
     """
     import time as _t
 
@@ -121,10 +149,30 @@ def _maybe_renew() -> None:
     _LAST_RENEW_ATTEMPT[0] = now
     try:
         creds = config.load()
-        if creds:
-            config.ensure_fresh(creds)
+        if not creds:
+            _RENEW_OUTCOME[0] = "unknown"
+            return
+        before_token = getattr(creds, "token", None)
+        before_hours = config.hours_remaining(creds)
+        fresh = config.ensure_fresh(creds)
+        after_token = getattr(fresh, "token", None)
+        if after_token and after_token != before_token:
+            # A DIFFERENT token came back — renewal demonstrably worked. Keyed
+            # on token identity, not on elapsed hours: comparing expiries means
+            # comparing floats across a wall-clock read, and a no-op would drift
+            # below its own start value on any slow call.
+            _RENEW_OUTCOME[0] = "renewed"
+        elif before_hours is None or before_hours > config.REFRESH_UNDER_HOURS:
+            # ensure_fresh no-ops above the threshold, and for API-key creds
+            # which carry no expiry at all. Nothing was attempted, so nothing
+            # failed — do not cry wolf.
+            _RENEW_OUTCOME[0] = "not_needed"
+        else:
+            # Under the threshold and the token did not change: renewal was
+            # attempted and did not take. THIS is the state worth shouting at.
+            _RENEW_OUTCOME[0] = "failed"
     except Exception:
-        pass
+        _RENEW_OUTCOME[0] = "failed"
 
 
 def _with_session_warning(fn):

{talis_cli-0.2.0 → talis_cli-0.2.1}/talis_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talis-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: Command-line client for the Talis trading platform. Sign in via device flow, manage sessions, view portfolio, place orders.
 Author: Talis
 License-Expression: Apache-2.0
@@ -114,6 +114,27 @@ suitable for parsing from scripts or LLM agents. Force JSON anywhere with
 The CLI stores its session token at `~/.talis/credentials` with `chmod 600`
 on POSIX systems. The token is a JWT; treat it like any other credential.
 
+### Sessions renew themselves
+
+You should not have to think about session expiry. When the CLI or the MCP
+server runs with under 48 hours left on the clock, it renews in place against
+`POST /auth/session/refresh` before doing its work — at most once every 15
+minutes, so a burst of commands costs one renewal, not one each. Renewal
+preserves the
+session's **original grant**, not a fresh maximum — a token issued with a 24h
+life renews to another 24h, never to something longer. That is deliberate: an
+auto-renewing session must not be able to ratchet itself into a longer-lived
+credential than the one you approved.
+
+Renewal is best-effort and silent: if it cannot happen, your existing
+credential is left untouched and the command still runs. What you WILL see is a
+`session_warning` on MCP tool responses once renewal stops keeping up, or when
+under six hours remain. If that appears and keeps counting down, renewal is
+failing — run `talis login` to sign in again.
+
+A steady `session_hours_remaining` with no `session_warning` is the healthy
+state, not a countdown to worry about.
+
 ## Relationship to `cli/jarvis_cli.sh`
 
 The bash script at [`cli/jarvis_cli.sh`](../../cli/jarvis_cli.sh) is the legacy
@@ -142,12 +163,16 @@ your portfolio, pull Talis Research, place paper trades, create strategies,
 set price alerts, and talk to the Talis chat agent. Log in first
 (`talis login`); the server authenticates as the logged-in user.
 
-Add it to **Claude Code**:
+Install and add it to **Claude Code**:
 
 ```bash
+pip install talis-cli        # or: uv tool install talis-cli
+talis login                  # device-flow browser approval, once
 claude mcp add talis -- talis mcp
 ```
 
+No local checkout required — `talis` is on PyPI.
+
 Or to **Claude Desktop** (and other clients using the `mcpServers` config
 shape) — `claude_desktop_config.json`:
 
@@ -162,14 +187,26 @@ shape) — `claude_desktop_config.json`:
 }
 ```
 
-Tools: `whoami`, `portfolio`, `balance`, `research`, `packets`,
-`brief_latest`, `history`, `buy`, `sell`, `close`, `create_strategy`, `chat`,
-`notifications_create`.
+Tools (25):
+
+`amend_strategy`, `balance`, `brief_latest`, `buy`, `cancel_all_orders`,
+`cancel_order`, `chat`, `close`, `create_strategy`, `history`,
+`notifications_create`, `open_orders`, `outcomes`, `packets`, `place_order`,
+`portfolio`, `research`, `sell`, `start_strategy`, `stop_strategy`,
+`strategies`, `strategy`, `strategy_activity`, `validate_strategy`, `whoami`.
+
+**Safety — read this before pointing an agent at it.** The trading tools
+(`buy` / `sell` / `close` / `create_strategy`) execute with **REAL MONEY by
+default** (`paper=False`). Pass `paper=True` to simulate instead.
+
+`buy`, `sell` and `create_strategy` additionally refuse to spend real money
+unless the caller passes `confirm_real_money=True`. `close` deliberately has no
+such gate: a protective exit must never be blocked by a missing flag.
+`place_order` (limit orders, spot, HIP-4 outcome markets) has **no paper mode
+at all** and refuses without `confirm_real_money=True`.
 
-**Safety**: the trading tools (`buy` / `sell` / `close` / `create_strategy`)
-default to `paper=True` — an isolated simulated book. An agent must pass
-`paper=False` explicitly to trade real money. Set `TALIS_PAPER=1` in the
-server's environment to force paper mode regardless of tool arguments.
+Set `TALIS_PAPER=1` in the server's environment to force paper mode regardless
+of tool arguments.
 Withdrawals and wallet creation are not exposed over MCP. For a strictly
 read-only agent, log in with `talis login --read-only` — the server rejects
 every mutation at the API layer.

{talis_cli-0.2.0 → talis_cli-0.2.1}/tests/test_mcp_docstring_contract.py

@@ -103,3 +103,48 @@ class TestInstructionsMatchRealDefaults:
         assert "real money" in low and "paper=false" in low, (
             "the instructions must say plainly that the default spends real "
             "money — an agent reads this before it acts")
+
+
+class TestTheREADMEMatchesTheCode:
+    """The README is what a user reads BEFORE installing, which makes a wrong
+    safety claim there worse than one in a docstring.
+
+    It said "the trading tools default to paper=True — an isolated simulated
+    book" while every signature read `paper: bool = False`. That was the SAME
+    inverted claim already fixed in the server instructions and the tool
+    docstrings — a third copy nobody thought to grep. Asserted against the
+    signatures, so prose and code cannot drift apart again.
+    """
+
+    def _readme(self):
+        import pathlib
+        return (pathlib.Path(__file__).resolve().parent.parent
+                / "README.md").read_text()
+
+    def test_readme_does_not_claim_paper_by_default(self):
+        low = self._readme().lower()
+        assert "default to `paper=true`" not in low
+        assert "default to paper=true" not in low
+
+    def test_readme_states_real_money_is_the_default(self):
+        low = self._readme().lower()
+        assert "real money" in low and "paper=false" in low
+
+    def test_readme_matches_the_actual_signature(self):
+        import inspect
+
+        from talis.commands import mcp_server as m
+        for tool in ("buy", "sell", "close", "create_strategy"):
+            default = inspect.signature(getattr(m, tool)).parameters["paper"].default
+            assert default is False, (
+                f"{tool} no longer defaults to real money — update README.md "
+                "in the same commit")
+
+    def test_readme_lists_every_tool_the_server_registers(self):
+        """A stale list (13 of 25) hides half the surface from anyone
+        evaluating what an agent can reach."""
+        from talis.commands.mcp_server import TOOL_FUNCTIONS
+        readme = self._readme()
+        missing = [f.__name__ for f in TOOL_FUNCTIONS
+                   if f"`{f.__name__}`" not in readme]
+        assert not missing, f"README omits registered tools: {missing}"