ama-cli 0.1.0__py3-none-any.whl

ama_cli/launch.py

@@ -0,0 +1,82 @@
+"""Launching the user's agent on a seeded prompt — the "Start now?" step.
+
+A registered MCP server is not a win anyone can see. The win is a live notebook,
+so the last thing onboarding does is offer to hand the user's own agent a prompt
+that produces one, instead of returning them to a shell to guess what to type.
+
+Two kinds of agent, and the difference is not cosmetic:
+
+    terminal agents  take a prompt as argv, so this is an exec
+    editor agents    have no prompt-on-launch equivalent, so the prompt is
+                     printed for the user to paste
+
+An agent is only offered when its binary is on PATH. Detection can fire on a
+config directory alone (the agent ran here once, or was uninstalled), and
+offering to start something we cannot exec would fail in front of the user at
+the exact moment onboarding was meant to pay off.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from ama_cli.agents.base import Env
+
+# How each terminal agent takes a prompt. Verified against each CLI's own
+# documented non-interactive invocation; an agent missing here is one we have
+# not confirmed, and guessing would produce exactly the broken hand-off this
+# step exists to avoid.
+_ARGV_BUILDERS: dict[str, Callable[[str, str], tuple[str, ...]]] = {
+    "claude-code": lambda binary, prompt: (binary, prompt),
+    "codex": lambda binary, prompt: (binary, prompt),
+    "gemini-cli": lambda binary, prompt: (binary, "-p", prompt),
+}
+
+_BINARIES: dict[str, str] = {
+    "claude-code": "claude",
+    "codex": "codex",
+    "gemini-cli": "gemini",
+}
+
+
+@dataclass(frozen=True)
+class Launch:
+    """A command that would start an agent on a prompt."""
+
+    agent_id: str
+    argv: tuple[str, ...]
+
+    @property
+    def display(self) -> str:
+        """The command, shortened for the terminal.
+
+        The prompt is long and multi-line; echoing it whole would bury the point.
+        No secret is involved -- the token is in the agent's config, never here.
+        """
+        head = self.argv[0]
+        return f'{head} "…"' if len(self.argv) > 1 else head
+
+
+def can_launch(agent_id: str) -> bool:
+    """True when this agent takes a prompt on the command line."""
+    return agent_id in _ARGV_BUILDERS
+
+
+def plan_launch(agent_id: str, prompt: str, env: Env) -> Launch | None:
+    """The command to start `agent_id` on `prompt`, or None when we cannot.
+
+    None covers both "editor agent, no prompt-on-launch" and "binary not on
+    PATH". Both mean the same thing to the caller: do not offer this.
+    """
+    builder = _ARGV_BUILDERS.get(agent_id)
+    if builder is None:
+        return None
+    binary = _BINARIES[agent_id]
+    resolved = env.which(binary)
+    if not resolved:
+        return None
+    return Launch(agent_id=agent_id, argv=builder(binary, prompt))
+
+
+__all__ = ["Launch", "can_launch", "plan_launch"]

ama_cli/onboard.py

@@ -0,0 +1,421 @@
+"""`ama onboard` — the whole point of this package.
+
+Composition, not new logic: phase 2's login, phase 3's detect-and-register, and
+one confirm between them. Three interactions, no more:
+
+    1. sign in            (browser)
+    2. confirm            agents + scope, pre-checked
+    3. start now?         launch the agent on a prompt that builds a notebook
+
+Every side effect is injected. The flow is the part most likely to break in ways
+tests should catch -- the wrong default scope, a second key on re-run, success
+declared over a dead key -- and none of that is testable if the function reaches
+for the network, a browser, or subprocess itself.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from ama_cli import auth, credentials, discovery, launch, prompts, verify
+from ama_cli.agents.adapters import get_adapter
+from ama_cli.agents import Detection, Env, detect_all
+from ama_cli.agents.mcp import (
+    DEFAULT_SERVER_NAME,
+    Plan,
+    RemoteServer,
+    Scope,
+    apply_plan,
+)
+from ama_cli.credentials import DEFAULT_HOST, HOST_ENV_VAR, Credentials
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+
+# Stands in for the key --dry-run deliberately does not mint. Shaped like the
+# real thing so the rendered plan is honest, and obviously not a credential so
+# nobody pastes it anywhere.
+_PLACEHOLDER_KEY = "ama_<your-key>"
+
+
+@dataclass(frozen=True)
+class Deps:
+    """Everything `run` does to the outside world.
+
+    Grouped rather than passed loose so the signature stays readable and tests
+    override one thing without restating the rest.
+    """
+
+    discover: Callable = discovery.discover
+    login: Callable = auth.login
+    verify: Callable = verify.verify
+    runner: Callable = subprocess.run
+    exec_agent: Callable = os.execvp
+    confirm: Callable | None = None
+    ask_token: Callable | None = None
+    now: Callable[[], datetime] = datetime.now
+    is_tty: Callable[[], bool] = lambda: sys.stdin.isatty()
+
+
+def resolve_host(flag: str | None, environ: Mapping[str, str]) -> str:
+    """--host beats $AMA_HOST beats ama.dev.
+
+    Self-hosting is a first-class case, so the default is only ever a default.
+    """
+    return (flag or environ.get(HOST_ENV_VAR) or DEFAULT_HOST).rstrip("/")
+
+
+def reusable_credentials(home: Path, host: str) -> Credentials | None:
+    """Stored credentials for this host, or None.
+
+    Idempotence lives here: re-running onboard must not mint a second key. A key
+    for a *different* host is not reusable -- that is a different account.
+
+    A revoked key still passes this and is caught by the verify step, which is
+    the right division: this function knows what we have, not whether it works.
+    """
+    stored = credentials.load(home)
+    if stored is None:
+        return None
+    return stored if stored.host.rstrip("/") == host.rstrip("/") else None
+
+
+def registerable(env: Env, agent: str | None) -> list[Detection]:
+    """The agents to offer: detected, and with an adapter that can act.
+
+    Never pre-emptively touches an undetected agent's config. An explicit
+    --agent overrides detection, because a user naming an agent knows better
+    than our heuristics.
+    """
+    if agent:
+        wanted = [a.strip() for a in agent.split(",") if a.strip()]
+        by_id = {d.agent_id: d for d in detect_all(env)}
+        return [by_id[a] for a in wanted if a in by_id and get_adapter(a)]
+    return [d for d in detect_all(env) if d.detected and get_adapter(d.agent_id)]
+
+
+def launchable(targets: Sequence[Detection], env: Env, prompt: str) -> launch.Launch | None:
+    """The first registered agent we can actually start, or None.
+
+    One offer, not a menu: the user has already made every choice this flow is
+    entitled to ask for.
+    """
+    for detection in targets:
+        planned = launch.plan_launch(detection.agent_id, prompt, env)
+        if planned is not None:
+            return planned
+    return None
+
+
+def _join(names) -> str:
+    """ "a", "a and b", "a, b and c" — this text ends up in a yes/no question."""
+    items = list(names)
+    if len(items) <= 1:
+        return "".join(items)
+    return f"{', '.join(items[:-1])} and {items[-1]}"
+
+
+def manual_instructions(creds: Credentials, name: str = DEFAULT_SERVER_NAME) -> str:
+    """What to print when we cannot register anything for the user.
+
+    Zero detections is a normal outcome -- a fresh machine, an agent we do not
+    know yet -- and it must never dead-end. The key is real and the URL is real,
+    so the user is two lines from working regardless of what we detected.
+
+    Contains the live token: this is printed only to the user's own terminal at
+    their request, and without it the output is useless to them.
+    """
+    return (
+        f"  MCP endpoint : {creds.mcp_url}\n"
+        f"  Header       : Authorization: Bearer {creds.api_key}\n\n"
+        f"  Claude Code  : claude mcp add --transport http -s user {name} "
+        f'{creds.mcp_url} --header "Authorization: Bearer {creds.api_key}"'
+    )
+
+
+def _sign_in(
+    *,
+    env: Env,
+    host: str,
+    mcp_url: str,
+    manifest: discovery.Manifest | None,
+    no_browser: bool,
+    console,
+    deps: Deps,
+) -> Credentials:
+    """Interaction 1. Reuse what we have, else get a key the right way for this host."""
+    existing = reusable_credentials(env.home, host)
+    if existing is not None:
+        console.print(f"[green]✓[/green] Already signed in as [bold]{existing.email or '?'}[/bold]")
+        # The stored URL can be stale (a host that moved, an older CLI). The
+        # manifest is authoritative when we have one.
+        refreshed = Credentials(
+            host=existing.host,
+            api_key=existing.api_key,
+            mcp_url=mcp_url,
+            email=existing.email,
+            tenant_id=existing.tenant_id,
+            created_at=existing.created_at,
+        )
+        credentials.save(refreshed, env.home)
+        return refreshed
+
+    if manifest is not None and manifest.is_notebook_mode:
+        # A local notebook has no tenant, no signup and no OAuth -- it
+        # string-compares AMA_LOCAL_TOKEN. There is nothing to log in to, so
+        # asking the browser to try would strand the user at a 404.
+        console.print("[dim]This host runs in notebook mode — it uses a preshared token.[/dim]")
+        ask = deps.ask_token
+        if ask is None:
+            raise RuntimeError("notebook-mode onboarding needs a token prompt")
+        token = ask()
+        creds = Credentials(host=host, api_key=token, mcp_url=mcp_url)
+        credentials.save(creds, env.home)
+        return creds
+
+    def show_url(url: str) -> None:
+        if no_browser:
+            console.print("\nOpen this URL to sign in:\n")
+            console.print(f"  [cyan]{url}[/cyan]\n")
+        else:
+            console.print("Opening your browser to sign in…")
+
+    import webbrowser
+
+    creds = deps.login(
+        host,
+        open_browser=(lambda _url: False) if no_browser else webbrowser.open,
+        on_url=show_url,
+    )
+    credentials.save(creds, env.home)
+    console.print(f"[green]✓[/green] Signed in as [bold]{creds.email or '?'}[/bold]")
+    console.print(f"  Key {creds.masked_key} created")
+    return creds
+
+
+def _register(
+    *,
+    targets: Sequence[Detection],
+    server: RemoteServer,
+    scope: Scope,
+    env: Env,
+    dry_run: bool,
+    console,
+    render: Callable[[Plan], None],
+    deps: Deps,
+) -> int:
+    """Apply each adapter's plan. Returns the number of failures."""
+    failures = 0
+    for detection in targets:
+        adapter = get_adapter(detection.agent_id)
+        if adapter is None:
+            continue
+        try:
+            plan = adapter.plan_add(server, scope, env)
+        except ValueError as exc:
+            # An unparseable config. Refusing beats clobbering something the
+            # user has and we do not understand.
+            console.print(f"  [red]✗ {detection.display_name}:[/red] {exc}")
+            failures += 1
+            continue
+
+        if plan.unsupported:
+            console.print(f"  [yellow]•[/yellow] {detection.display_name}: {plan.unsupported}")
+            continue
+
+        if dry_run:
+            console.print(f"  [bold]{detection.display_name}[/bold]")
+            render(plan)
+            continue
+
+        result = apply_plan(plan, now=deps.now(), runner=deps.runner)
+        if result.ok:
+            console.print(f"  [green]✓[/green] {detection.display_name}")
+            for bak in result.backups:
+                console.print(f"    [dim]backup: {bak}[/dim]")
+        else:
+            console.print(f"  [red]✗[/red] {detection.display_name}: {result.detail}")
+            failures += 1
+    return failures
+
+
+def _offer_start(
+    *,
+    targets: Sequence[Detection],
+    env: Env,
+    console,
+    deps: Deps,
+) -> None:
+    """Interaction 3. The payoff: a live notebook, built by their own agent.
+
+    Returns normally when declined or impossible. On acceptance this execs and
+    does not return.
+    """
+    prompt = prompts.first_notebook_prompt()
+    planned = launchable(targets, env, prompt)
+
+    if planned is None:
+        # Editor agents have no prompt-on-launch, so the best we can do is hand
+        # over the text. Still better than "you're all set" and nothing to do.
+        console.print("\n[bold]Try this in your agent:[/bold]\n")
+        console.print(f"  [cyan]{prompts.first_notebook_prompt(short=True)}[/cyan]")
+        return
+
+    confirm = deps.confirm
+    if confirm is None or not confirm("\nStart now?"):
+        console.print("\n[bold]Try this in your agent:[/bold]\n")
+        console.print(f"  [cyan]{prompts.first_notebook_prompt(short=True)}[/cyan]")
+        return
+
+    console.print(f"\n[dim]→ {planned.display}[/dim]\n")
+    # exec, not spawn: the agent takes over this terminal. Anything else leaves
+    # a dead parent process holding a pipe the agent needs.
+    deps.exec_agent(planned.argv[0], list(planned.argv))
+
+
+def run(
+    *,
+    env: Env,
+    console,
+    host_flag: str | None = None,
+    scope: Scope = Scope.GLOBAL,
+    agent: str | None = None,
+    yes: bool = False,
+    no_browser: bool = False,
+    dry_run: bool = False,
+    no_start: bool = False,
+    server_name: str = DEFAULT_SERVER_NAME,
+    environ: Mapping[str, str] | None = None,
+    render: Callable[[Plan], None] | None = None,
+    deps: Deps | None = None,
+) -> int:
+    """The onboarding flow. Returns a process exit code."""
+    deps = deps or Deps()
+    environ = os.environ if environ is None else environ
+    render = render or (lambda _plan: None)
+    interactive = deps.is_tty()
+
+    host = resolve_host(host_flag, environ)
+    console.print(f"\n  [bold]Ama[/bold] · [cyan]{host}[/cyan]\n")
+
+    manifest = deps.discover(host)
+    if manifest is None:
+        # Not fatal: the manifest is an optimisation and the path is
+        # conventional. If the host is genuinely unreachable, login says so
+        # next, with a better message than this could give.
+        console.print(
+            f"[dim]Could not read {host}{discovery.DISCOVERY_PATH}; assuming defaults.[/dim]"
+        )
+    mcp_url = manifest.mcp_url if manifest else discovery.default_mcp_url(host)
+
+    if dry_run:
+        # Signing in is not free of consequence: it mints a real key server-side
+        # and writes credentials.json. --dry-run promises to change nothing, and
+        # that has to include the half that happens on the server.
+        creds = reusable_credentials(env.home, host)
+        if creds is None:
+            console.print("[dim]Would sign in via the browser and create a key.[/dim]")
+            creds = Credentials(host=host, api_key=_PLACEHOLDER_KEY, mcp_url=mcp_url)
+        else:
+            console.print(
+                f"[green]✓[/green] Already signed in as [bold]{creds.email or '?'}[/bold]"
+            )
+    else:
+        try:
+            creds = _sign_in(
+                env=env,
+                host=host,
+                mcp_url=mcp_url,
+                manifest=manifest,
+                no_browser=no_browser,
+                console=console,
+                deps=deps,
+            )
+        except auth.LoginError as exc:
+            console.print(f"\n[red]Sign-in failed:[/red] {exc}")
+            return EXIT_FAILED
+
+    targets = registerable(env, agent)
+    if not targets:
+        # Never dead-end.
+        console.print("\n[yellow]No supported coding agents detected.[/yellow]")
+        console.print("Register Ama by hand:\n")
+        console.print(manual_instructions(creds, server_name))
+        return EXIT_OK
+
+    console.print("\n  Detected on this machine:")
+    for detection in targets:
+        console.print(
+            f"    [green]●[/green] {detection.display_name}   [dim]{detection.reason}[/dim]"
+        )
+
+    names = _join(d.display_name for d in targets)
+    if not (yes or dry_run):
+        if not interactive:
+            # Refuse rather than guess: this writes to config files we do not own.
+            console.print(
+                "\n[red]Refusing to modify agent configs without confirmation.[/red]\n"
+                "Re-run with [bold]--yes[/bold] in a non-interactive shell."
+            )
+            return EXIT_FAILED
+        confirm = deps.confirm
+        if confirm is None or not confirm(f"\n  Install {scope.value}ly for {names}?"):
+            console.print("\n[yellow]Nothing was changed.[/yellow]")
+            return EXIT_OK
+
+    server = RemoteServer(url=mcp_url, token=creds.api_key, name=server_name)
+    console.print("")
+    failures = _register(
+        targets=targets,
+        server=server,
+        scope=scope,
+        env=env,
+        dry_run=dry_run,
+        console=console,
+        render=render,
+        deps=deps,
+    )
+
+    if dry_run:
+        console.print("\n[dim]--dry-run: nothing was changed.[/dim]")
+        return EXIT_OK
+
+    if failures:
+        console.print(f"\n[red]{failures} agent(s) could not be configured.[/red]")
+        return EXIT_FAILED
+
+    # Writing a config proves nothing. Connect with the key we just wrote.
+    result = deps.verify(mcp_url, creds.api_key)
+    if result.ok:
+        console.print(f"  [green]✓[/green] {result.summary}")
+    else:
+        console.print(f"\n[red]✗ Registered, but the connection failed:[/red] {result.summary}")
+        if result.unauthorized:
+            console.print("[dim]The key may have been revoked. Try `ama login` again.[/dim]")
+        return EXIT_FAILED
+
+    console.print("\n[dim]Undo anytime: ama mcp remove[/dim]")
+
+    if no_start or not interactive:
+        return EXIT_OK
+    _offer_start(targets=targets, env=env, console=console, deps=deps)
+    return EXIT_OK
+
+
+__all__ = [
+    "Deps",
+    "EXIT_FAILED",
+    "EXIT_OK",
+    "launchable",
+    "manual_instructions",
+    "registerable",
+    "resolve_host",
+    "reusable_credentials",
+    "run",
+]

ama_cli/prompts.py

@@ -0,0 +1,53 @@
+"""The seeded prompt — the content half of "Start now?".
+
+This is copy, and it will need iterating, so it lives in one place rather than
+inline in the flow.
+
+Every tool named here is real and reachable in the mode Ama actually deploys
+(`AMA_MODE=notebook`), checked against the `@mcp.tool` registrations in
+`src/ama/mcp/server.py`. That matters more than it looks: a prompt naming a tool
+that does not exist turns the payoff moment into the agent apologising. In
+particular there is **no** `notebook.add_cell` / `notebook.edit_cell` — cells are
+driven through `notebook.execute_code`, so the prompt must not imply otherwise.
+
+The shape follows the loop Ama already documents to agents in `AGENTS.md` and
+`docs/quickstart-for-agents.mdx`: bootstrap, open a notebook, surface the
+browser_url, then run something real.
+"""
+
+from __future__ import annotations
+
+# The payoff is not a configured MCP server -- the user cannot see that. It is a
+# live notebook in their browser, built by their own agent, in one step. So the
+# prompt's real job is to get `browser_url` on screen fast.
+_FULL = """Use the ama MCP server to get me started.
+
+1. Call workspace.bootstrap to set up my workspace and see what's there.
+2. Create or open a notebook, then show me the browser_url it returns — that's
+   where I watch you work, live.
+3. Use notebook.execute_code to build something real in the kernel: load a small
+   sample dataset, explore it, and plot it. Render the plot as text/ASCII with
+   plotext so I can see it in your output too.
+4. Then tell me, in two sentences, what else I can do here.
+
+Go ahead and do all of it now — show me the notebook link as soon as you have it."""
+
+# For agents with no prompt-on-launch, where the user pastes this by hand. Long
+# multi-line text is miserable to paste into a chat box, so this says the same
+# thing in one line.
+_SHORT = (
+    "Use the ama MCP server: call workspace.bootstrap, create a notebook, show me its "
+    "browser_url, then use notebook.execute_code to load and plot a small sample dataset "
+    "(render it as ASCII with plotext)."
+)
+
+
+def first_notebook_prompt(short: bool = False) -> str:
+    """The prompt that takes a fresh user to a live notebook.
+
+    `short` returns the one-line form for pasting by hand.
+    """
+    return _SHORT if short else _FULL
+
+
+__all__ = ["first_notebook_prompt"]