pipecatcloud 1.1.0__tar.gz → 1.2.0__tar.gz

{pipecatcloud-1.1.0 → pipecatcloud-1.2.0}/CHANGELOG.md

@@ -5,6 +5,126 @@ All notable changes to **Pipecat Cloud** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-08-27
+
+### Added
+
+- **GitHub integration**, at parity with the dashboard. Connect an
+  organization with `pipecat cloud github connect`: it opens the GitHub App
+  install page and waits while the install completes, so there is nothing to
+  copy back into the terminal. `github status` reports the connected account
+  and whether the App is suspended, `github disconnect` removes the
+  installation and every repository link under it, and `github repos` /
+  `github branches <owner/repo>` list what the App can see (`--query` runs the
+  server-side branch search for repositories with more branches than the list
+  returns).
+
+- Agents can be built from a repository instead of an image. `pipecat cloud
+  deploy --repo owner/repo --branch main` creates a GitHub-sourced agent,
+  skipping the image build and push entirely, and follows the first deploy
+  through its build; a `[git]` section in `pcc-deploy.toml` (`repo`, `branch`,
+  `dockerfile_path`, `subdirectory`) does the same, with flags taking
+  precedence. An existing agent's repository is changed with `pipecat cloud
+  agent link <name> --repo owner/repo --branch main` (also `--dockerfile-path`,
+  `--subdirectory` and `--no-auto-deploy`), and removed with `agent unlink`.
+  Linking never changes what is running.
+
+- `pipecat cloud agent deploy <name> --github` builds and deploys the linked
+  branch's current HEAD without waiting for a push, printing the deploy intent
+  and commit. `--wait` follows the deploy and reports one of four outcomes: it
+  succeeded, it failed, a newer push superseded it (naming the newer commit),
+  or it was still building when the wait ran out. Only an observed failure and
+  a deploy that was never visible at all exit non-zero, so a green `--wait`
+  means the deploy was observed and did not fail, never merely that the wait
+  finished. In `--output json` the outcome is reported as `waitOutcome`.
+
+- `pipecat cloud agent list` gains a GitHub column, and `agent status` reports
+  the linked repository and branch, the Dockerfile path, whether pushes
+  auto-deploy, the commit actually running, and the latest deploy attempt with
+  its failure reason. A running commit that did not come from the current link
+  (a freshly linked agent, or one whose repository or branch was re-pointed)
+  says so and names where it did come from. `pipecat cloud build status` and
+  `build list` show the repository, ref and commit a build came from.
+
+- Architecture selection on deploy: `pipecat cloud deploy --architecture
+  {amd64,arm64}` or an `architecture` key in `pcc-deploy.toml` (the flag
+  wins). Omitted, the region's default applies — set it when your image is
+  built for one architecture, so it schedules on matching nodes instead of
+  failing at startup. The choice is validated against the target region's
+  supported architectures before anything uploads, when the API advertises
+  them. `pipecat cloud regions list` shows each region's supported and
+  default architectures (Daily-hosted regions are arm64-only today), and
+  `pipecat cloud agent status` shows the deployment's architecture.
+
+- Region lifecycle commands for **self-hosted regions**. `pipecat cloud
+  regions register <key>` registers or updates a region (an omit-preserves
+  upsert: options you leave out keep their stored values), with a one-question
+  display-name prompt so region pickers show a friendly name instead of the
+  uppercased key. `regions show <key>` prints the full record, including the
+  enrollment status and intermediate certificate expiry. `regions delete
+  <key>` revokes a region, surfacing the server's refusal while live sessions
+  or deployed services exist; that guard has no bypass, so delete the region's
+  agents first, and `--yes` only skips the confirmation prompt.
+  `regions enroll-token <key>` mints the one-time enrollment token and
+  prints the ready-to-paste `kubectl create secret` command.
+
+- New `pipecat cloud organizations registry-keys` command group for the
+  pull-only registry credentials that fetch the region package chart:
+  `mint` (the key is shown exactly once, with the matching
+  `helm registry login` command), `list` (lifecycle metadata only, never key
+  material), and `revoke`. With these plus `regions register` and
+  `regions enroll-token`, a self-hosted region's control-plane setup needs no
+  raw API calls.
+
+- Explicit agent sizing for **enterprise (self-hosted) regions**. Deploys can
+  now state resources directly instead of selecting an agent profile:
+  `pipecat cloud deploy --resources cpu=2,memory=4Gi`, or a `[resources]`
+  section in `pcc-deploy.toml` with `cpu` and `memory` keys. Explicit
+  resources and `--profile` are mutually exclusive, and the API accepts
+  explicit resources only for agents in self-hosted regions.
+
+- `pipecat cloud agent status` now shows the agent's resolved resources
+  (cpu/memory) from the deployment. For agents deployed with explicit
+  resources rather than a profile, this is the sizing surface.
+
+- New `pipecat cloud agent profiles` command group. `list` shows the platform
+  catalog plus any profiles your organization has defined; `create`, `update`,
+  `disable`, and `enable` manage organization-defined profiles for self-hosted
+  regions. Profile edits apply to future deploys only: running agents keep the
+  resources their deployment captured. Disabling is reversible: a disabled
+  profile can't be selected for new deploys until re-enabled.
+
+- New `pipecat cloud secrets reference <name> --region <region>` command for
+  **self-hosted regions**. It registers an existing Kubernetes Secret from your
+  workloads namespace as a secret set, so agents can use it by set name exactly
+  as they use managed sets, and the Kubernetes Secret's name becomes the secret
+  set name. The secret stays in your cluster: Pipecat Cloud records only its
+  name, region, and readiness, never its values or keys, and you keep managing
+  its contents with your own tooling such as `kubectl`. `--region` is required
+  and must name a self-hosted region; cloud regions are rejected.
+
+### Fixed
+
+- `pipecat cloud deploy` no longer rejects a referenced secret set as "not
+  found". The existence check read the set's array of key names and tested it
+  for truthiness, but referenced sets carry no key names by design (Daily
+  stores name, region and readiness, never the contents), so every healthy
+  referenced set failed the check and no self-hosted deploy could use one. The
+  check now fetches the set itself; readiness is still enforced server-side.
+
+- `pipecat cloud secrets set` no longer treats an existing referenced secret
+  set as nonexistent. It had the same key-names misread as the deploy guard,
+  so it announced "Creating secret set" and then failed on the server's
+  name-uniqueness check. It now refuses before asking for confirmation,
+  pointing at the cluster as the place a referenced set's contents are
+  managed.
+
+- `pipecat cloud agent status` plain output (`--output plain`, or any piped
+  invocation) now includes the Architecture and Resources rows. Both were
+  rendered only in the rich table, so scripted output silently omitted the
+  deployment's architecture and, for agents sized with explicit resources,
+  their only visible sizing.
+
 ## [1.1.0] - 2026-08-05
 
 ### Added

{pipecatcloud-1.1.0 → pipecatcloud-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipecatcloud
-Version: 1.1.0
+Version: 1.2.0
 Summary: Cloud hosting for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Website, https://docs.pipecat.ai/pipecat-cloud

{pipecatcloud-1.1.0 → pipecatcloud-1.2.0}/src/pipecatcloud/_utils/deploy_utils.py

@@ -4,8 +4,10 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+import asyncio
 import functools
 import os
+import time
 from collections.abc import Callable
 from datetime import UTC, datetime
 from enum import Enum
@@ -301,6 +303,120 @@ class KrispVivaConfig:
         return {"audio_filter": self.audio_filter}
 
 
+# Mirrors the server-side k8s quantity validation (positive decimal + optional
+# suffix). Kept client-side so a typo fails before any network round-trip.
+K8S_QUANTITY_PATTERN = r"^[0-9]+(\.[0-9]+)?(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei)?$"
+
+
+@dataclass
+class ResourcesConfig:
+    """Explicit sizing for agents in enterprise (self-hosted) regions.
+
+    Mutually exclusive with agent_profile: a deploy either references a named
+    profile or states cpu/memory directly. Only accepted by the API for
+    services in self-hosted regions.
+    """
+
+    cpu: str | None = None
+    memory: str | None = None
+
+    def __attrs_post_init__(self):
+        import re
+
+        if (self.cpu is None) != (self.memory is None):
+            raise ValueError("resources requires both 'cpu' and 'memory'")
+        for name, value in (("cpu", self.cpu), ("memory", self.memory)):
+            if value is not None and not re.match(K8S_QUANTITY_PATTERN, str(value)):
+                raise ValueError(
+                    f"Invalid {name} quantity '{value}' (expected e.g. '500m', '2', '4Gi')"
+                )
+
+    def is_set(self) -> bool:
+        return self.cpu is not None
+
+    def to_dict(self):
+        return {"cpu": self.cpu, "memory": self.memory}
+
+
+def parse_resources_option(value: str) -> "ResourcesConfig":
+    """Parse the --resources CLI value ("cpu=2,memory=4Gi") into a ResourcesConfig.
+
+    Raises ValueError with a specific message on malformed input (unknown keys,
+    missing cpu/memory, bad quantities) so the caller can surface exactly what
+    was wrong rather than a generic usage error.
+    """
+    parts: dict[str, str] = {}
+    for chunk in value.split(","):
+        key, sep, val = chunk.partition("=")
+        if not sep or not val.strip():
+            raise ValueError(
+                f"Malformed --resources segment '{chunk.strip()}'. "
+                "Expected key=value pairs, e.g. cpu=2,memory=4Gi"
+            )
+        parts[key.strip()] = val.strip()
+    if set(parts.keys()) != {"cpu", "memory"}:
+        raise ValueError(
+            "--resources requires exactly 'cpu' and 'memory', "
+            f"got: {', '.join(sorted(parts.keys())) or 'nothing'}"
+        )
+    # ResourcesConfig raises its own specific ValueError for bad quantities.
+    return ResourcesConfig(cpu=parts["cpu"], memory=parts["memory"])
+
+
+@dataclass
+class GitSourceConfig:
+    """A GitHub repo/branch to build the agent from, instead of an image.
+
+    Only valid when creating an agent: the API accepts `git` on create and
+    ignores it on update, so a binding change on an existing agent goes
+    through `agent link` rather than silently doing nothing here.
+    """
+
+    repo: str | None = None
+    branch: str | None = None
+    dockerfile_path: str | None = None
+    subdirectory: str | None = None
+
+    def __attrs_post_init__(self):
+        # Same rules the API applies, so a typo fails before the round-trip.
+        from pipecatcloud._utils.github_utils import (
+            is_valid_branch_name,
+            is_valid_repo_full_name,
+        )
+
+        if self.repo is not None and not is_valid_repo_full_name(self.repo):
+            raise ValueError(f"Invalid repo '{self.repo}'. Expected the form 'owner/repo'.")
+        if self.branch is not None and not is_valid_branch_name(self.branch):
+            raise ValueError(
+                f"Invalid branch '{self.branch}'. A branch must be a valid git ref with no "
+                "empty or dot-only segments."
+            )
+        # A half-specified source would otherwise reach the API as a plain
+        # image deploy, which is a confusing way to learn the branch is missing.
+        if (self.repo is None) != (self.branch is None):
+            raise ValueError("A GitHub source requires both 'repo' and 'branch'")
+
+    def is_set(self) -> bool:
+        return self.repo is not None
+
+    def to_payload(self) -> dict:
+        """The `git` object for the create-service request."""
+        payload = {"repoFullName": self.repo, "branch": self.branch}
+        if self.dockerfile_path:
+            payload["dockerfilePath"] = self.dockerfile_path
+        if self.subdirectory:
+            payload["subdirectory"] = self.subdirectory
+        return payload
+
+    def to_dict(self):
+        return {
+            "repo": self.repo,
+            "branch": self.branch,
+            "dockerfile_path": self.dockerfile_path,
+            "subdirectory": self.subdirectory,
+        }
+
+
 @dataclass
 class BuildConfig:
     """Configuration for cloud builds."""
@@ -329,10 +445,15 @@ class DeployConfigParams:
     docker_config: dict = field(factory=dict)
     build_config: BuildConfig = field(factory=BuildConfig)  # Cloud build configuration
     agent_profile: str | None = None
+    resources: ResourcesConfig = field(factory=ResourcesConfig)
     krisp_viva: KrispVivaConfig = field(factory=KrispVivaConfig)
+    git: GitSourceConfig = field(factory=GitSourceConfig)
     force_redeploy: bool = False
     websocket_auth: str | None = None
     max_session_duration: int | None = None
+    # CPU architecture the agent image requires (PCC-1105). Exactly the
+    # kubernetes.io/arch vocabulary; omitted = the region's default.
+    architecture: str | None = None
 
     def __attrs_post_init__(self):
         if self.image is not None and ":" not in self.image:
@@ -340,8 +461,19 @@ class DeployConfigParams:
         # Cannot specify both image and build_id
         if self.image is not None and self.build_id is not None:
             raise ValueError("Cannot specify both 'image' and 'build_id'")
+        # A git-sourced agent's image is produced by the build its first deploy
+        # triggers, so there is nothing to supply up front. The API rejects the
+        # combination too; failing here just does it sooner.
+        if self.git.is_set() and (self.image is not None or self.build_id is not None):
+            raise ValueError("Cannot specify a GitHub source together with 'image' or 'build_id'")
         if self.max_session_duration is not None and not 60 <= self.max_session_duration <= 14400:
             raise ValueError("max_session_duration must be between 60 and 14400 seconds")
+        # Sizing is one of: a named profile, or explicit resources (enterprise
+        # regions). The API enforces this too; failing here is just faster.
+        if self.agent_profile is not None and self.resources.is_set():
+            raise ValueError("Cannot specify both 'agent_profile' and 'resources'")
+        if self.architecture is not None and self.architecture not in ("amd64", "arm64"):
+            raise ValueError("architecture must be 'amd64' or 'arm64'")
 
     def to_dict(self):
         return {
@@ -355,12 +487,40 @@ class DeployConfigParams:
             "docker_config": self.docker_config,
             "build_config": self.build_config.to_dict() if self.build_config else None,
             "agent_profile": self.agent_profile,
+            "resources": self.resources.to_dict() if self.resources.is_set() else None,
             "krisp_viva": self.krisp_viva.to_dict() if self.krisp_viva else None,
+            "git": self.git.to_dict() if self.git.is_set() else None,
             "websocket_auth": self.websocket_auth,
             "max_session_duration": self.max_session_duration,
+            "architecture": self.architecture,
         }
 
 
+def validate_git_source_combination(config: DeployConfigParams) -> str | None:
+    """What a GitHub source cannot be combined with, or None when it is fine.
+
+    A separate check from DeployConfigParams' own validation because the deploy
+    command mutates the config field by field after constructing it, so
+    __attrs_post_init__ never sees the merged result.
+    """
+    if not config.git.is_set():
+        return None
+    if config.image or config.build_id:
+        return (
+            "Cannot deploy from a GitHub repository and an image or build at the same "
+            "time. Drop --image/--build-id, or drop --repo."
+        )
+    # A git agent's first-deploy config is stashed on its binding, and explicit
+    # resources are not plumbed through that path yet, so the API refuses the
+    # pair. Saying so here saves the round-trip.
+    if config.resources.is_set():
+        return (
+            "Explicit resources are not yet supported for GitHub-sourced agents. "
+            "Use [bold]--profile[/bold] instead."
+        )
+    return None
+
+
 def load_deploy_config_file() -> DeployConfigParams | None:
     from pipecatcloud.cli.config import deploy_config_path
 
@@ -385,6 +545,14 @@ def load_deploy_config_file() -> DeployConfigParams | None:
         krisp_viva_data = config_data.pop("krisp_viva", {})
         krisp_viva_config = KrispVivaConfig(**krisp_viva_data)
 
+        # Extract explicit resources if present (enterprise regions)
+        resources_data = config_data.pop("resources", {})
+        resources_config = ResourcesConfig(**resources_data)
+
+        # Extract GitHub source if present (PCC-933)
+        git_data = config_data.pop("git", {})
+        git_config = GitSourceConfig(**git_data)
+
         # Extract build configuration if present
         build_data = config_data.pop("build", {})
         exclude_data = build_data.pop("exclude", {})
@@ -408,8 +576,11 @@ def load_deploy_config_file() -> DeployConfigParams | None:
             "build",
             "agent_profile",
             "krisp_viva",
+            "git",
             "websocket_auth",
             "max_session_duration",
+            "resources",
+            "architecture",
         }
 
         # TODO: Remove this enable_krisp migration hint in the 2.0.0 release.
@@ -429,6 +600,8 @@ def load_deploy_config_file() -> DeployConfigParams | None:
             docker_config=docker_data,
             build_config=build_config,
             krisp_viva=krisp_viva_config,
+            resources=resources_config,
+            git=git_config,
         )
 
         return validated_config
@@ -477,3 +650,156 @@ def with_deploy_config(func: Callable) -> Callable:
         return func(*args, **kwargs)
 
     return wrapper
+
+
+# How long `--wait` follows a GitHub deploy before handing it back. A GitHub
+# deploy builds an image first, so it is legitimately slower than an image
+# deploy; the cap exists so a wedged build can't hang a CI job forever, not to
+# express an expected duration.
+GIT_DEPLOY_WAIT_SECONDS = 20 * 60
+GIT_DEPLOY_POLL_SECONDS = 5
+
+
+class GitDeployWait(Enum):
+    """How a `--wait` ended. Four outcomes, because three of them are not
+    "succeeded" and collapsing them loses the distinction that matters."""
+
+    # A status we actually observed reach a terminal state.
+    TERMINAL = "terminal"
+    # Observed, still moving when the budget ran out. Says nothing bad about
+    # the deploy.
+    IN_FLIGHT = "in_flight"
+    # A newer attempt became the agent's latest, so ours is no longer
+    # observable (and, unless it had already reached `deploying`, was
+    # cancelled by the supersede).
+    SUPERSEDED = "superseded"
+    # Never saw our attempt at all: every poll failed, or no attempt was ever
+    # enqueued. We know nothing, which is different from knowing it is fine.
+    UNOBSERVED = "unobserved"
+
+
+@dataclass
+class GitDeployResult:
+    outcome: GitDeployWait
+    deploy: dict | None = None
+    superseded_by: str | None = None
+
+
+async def follow_git_deploy(agent_name: str, org: str | None, commit_sha: str) -> GitDeployResult:
+    """Poll an agent's latest deploy attempt until it resolves.
+
+    Polls the service read endpoint rather than a deploy-intent endpoint: the
+    API surfaces the attempt as `latestDeploy` (PCC-978), which is also what
+    `agent status` reads, so both agree on what a deploy is doing.
+
+    `commit_sha` is the attempt we are entitled to report on. Empty means
+    "whatever attempt exists", which is only correct for an agent's first
+    deploy, where there is nothing that could have superseded it.
+    """
+    # Imported at call time: api.py imports this module for DeployConfigParams,
+    # so a module-level import of the API client would close that cycle.
+    from pipecatcloud._utils.console_utils import console
+    from pipecatcloud._utils.github_utils import is_deploy_in_flight
+    from pipecatcloud.cli.api import API
+
+    deadline = time.monotonic() + GIT_DEPLOY_WAIT_SECONDS
+    latest: dict | None = None
+    last_status: str | None = None
+
+    with console.status("[dim]Waiting for the deploy...[/dim]", spinner="bouncingBar") as live:
+        while time.monotonic() < deadline:
+            # A blip mid-deploy should not abort a wait that is otherwise
+            # healthy; keep polling and let the deadline decide.
+            data, error = await API.bubble_error().agent(agent_name=agent_name, org=org)
+            if not error and data:
+                candidate = data.get("latestDeploy")
+                if candidate:
+                    found_sha = candidate.get("commitSha")
+                    # A different commit is positive evidence, not an absence
+                    # of it. The API reads this from the primary ordered by
+                    # created_at DESC, and our own intent was already
+                    # committed when the trigger answered 202 — so anything
+                    # else holding "latest" is strictly newer, and ours can
+                    # never reclaim the spot. Waiting out the budget here
+                    # would report a stale snapshot twenty minutes later.
+                    if commit_sha and found_sha != commit_sha:
+                        return GitDeployResult(
+                            GitDeployWait.SUPERSEDED,
+                            deploy=latest,
+                            superseded_by=found_sha,
+                        )
+                    latest = candidate
+                    status_value = candidate.get("status")
+                    if status_value != last_status:
+                        last_status = status_value
+                        live.update(f"[dim]Deploy {status_value}...[/dim]")
+                    if not is_deploy_in_flight(candidate):
+                        return GitDeployResult(GitDeployWait.TERMINAL, deploy=latest)
+            await asyncio.sleep(GIT_DEPLOY_POLL_SECONDS)
+
+    if latest is None:
+        return GitDeployResult(GitDeployWait.UNOBSERVED)
+    return GitDeployResult(GitDeployWait.IN_FLIGHT, deploy=latest)
+
+
+def report_git_deploy_result(
+    result: GitDeployResult, agent_name: str, *, first_deploy: bool = False
+) -> None:
+    """Render a finished `--wait` and set the exit code.
+
+    Shared by both wait call sites so the four outcomes can't be interpreted
+    differently in two places.
+
+    On exit codes: only an observed failure and a never-observed deploy exit
+    non-zero. A deploy still building when the budget runs out has not failed,
+    and neither has one that a newer push took over. But a wait that never saw
+    anything cannot tell a healthy build from an API that was down the whole
+    time, and reporting that as success is what would make `--wait` unsafe as
+    a deploy gate.
+    """
+    from pipecatcloud._utils.console_utils import console
+    from pipecatcloud._utils.github_utils import short_sha
+    from pipecatcloud.cli import PIPECAT_CLI_NAME
+
+    check_hint = (
+        f"[dim]Check it with [bold]{PIPECAT_CLI_NAME} agent status {agent_name}[/bold].[/dim]"
+    )
+    label = "First deploy" if first_deploy else "Deploy"
+
+    if result.outcome is GitDeployWait.TERMINAL:
+        deploy = result.deploy or {}
+        status_value = deploy.get("status")
+        commit = deploy.get("commitSha")
+        if status_value == "succeeded":
+            console.success(
+                f"Deployed '{agent_name}'" + (f" from commit {short_sha(commit)}" if commit else "")
+            )
+            return
+        reason = deploy.get("reason") or "No reason reported."
+        console.error(f"{label} of '{agent_name}' {status_value}.\n{reason}")
+        raise typer.Exit(1)
+
+    if result.outcome is GitDeployWait.SUPERSEDED:
+        newer = short_sha(result.superseded_by) if result.superseded_by else "a newer commit"
+        console.print(
+            f"[yellow]Superseded: a newer deploy ({newer}) is now the latest attempt for "
+            f"'{agent_name}', so this one's result is no longer reported.[/yellow]\n" + check_hint
+        )
+        return
+
+    if result.outcome is GitDeployWait.IN_FLIGHT:
+        status_value = (result.deploy or {}).get("status") or "in progress"
+        console.print(
+            f"[yellow]Still {status_value} after waiting. The deploy continues "
+            f"server-side.[/yellow]\n" + check_hint
+        )
+        return
+
+    # UNOBSERVED. Never assert progress we did not see.
+    console.error(
+        f"Could not confirm the deploy of '{agent_name}': no deploy attempt was visible "
+        "while waiting.\n"
+        "[dim]The API may have been unreachable, or the attempt may never have been "
+        f"queued.[/dim]\n" + check_hint
+    )
+    raise typer.Exit(1)

pipecatcloud-1.2.0/src/pipecatcloud/_utils/github_utils.py

@@ -0,0 +1,129 @@
+#
+# Copyright (c) 2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Shared helpers for the GitHub integration commands (PCC-933).
+
+Reading an agent's binding: the API's `git` object is the *configured* intent,
+while `deployedCommit` is the provenance of what is actually running. The two
+can legitimately disagree — a freshly linked agent still serves its pre-link
+image until the next deploy — so they are reported separately rather than
+collapsed into one "GitHub" status.
+"""
+
+import re
+
+# Mirrors the API's isValidRepoFullName. Encoding alone is not enough on the
+# wire: a pure-dot segment still retargets the path after normalization, so the
+# shape is checked rather than escaped.
+_REPO_SEGMENT = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+# Matches the git_configs.dockerfile_path column default.
+DEFAULT_DOCKERFILE_PATH = "Dockerfile"
+
+_REF_BRANCH_PREFIX = "refs/heads/"
+
+# Deploy-intent states that mean an attempt is still in flight. Anything else
+# is terminal, which is what the --wait polling keys off.
+IN_FLIGHT_DEPLOY_STATUSES = ("pending", "building", "deploying")
+
+
+def is_valid_repo_full_name(repo_full_name: str) -> bool:
+    """True for exactly two URL-safe `owner/repo` segments, no pure-dot segment."""
+    segments = repo_full_name.split("/")
+    return len(segments) == 2 and all(
+        _REPO_SEGMENT.match(segment) and not re.fullmatch(r"\.+", segment) for segment in segments
+    )
+
+
+def is_valid_branch_name(branch: str) -> bool:
+    """True for a git ref with no empty or pure-dot segment.
+
+    Rejecting these at bind time is what stops a branch that can never be
+    resolved from failing on the first deploy instead.
+    """
+    if not branch:
+        return False
+    return all(segment and not re.fullmatch(r"\.+", segment) for segment in branch.split("/"))
+
+
+def short_sha(sha: str) -> str:
+    return sha[:7]
+
+
+def ref_to_branch(ref: str) -> str:
+    """`refs/heads/main` -> `main`. Anything else is returned unchanged."""
+    return ref[len(_REF_BRANCH_PREFIX) :] if ref.startswith(_REF_BRANCH_PREFIX) else ref
+
+
+def is_deploy_in_flight(deploy: dict | None) -> bool:
+    return bool(deploy) and (deploy or {}).get("status") in IN_FLIGHT_DEPLOY_STATUSES
+
+
+def installation_settings_url(installation: dict) -> str:
+    """The GitHub page for managing this installation's repo access.
+
+    The path differs for organization and user accounts; the API normalizes
+    `githubAccountType` to lowercase.
+    """
+    login = installation.get("githubAccountLogin", "")
+    installation_id = installation.get("githubInstallationId", "")
+    if str(installation.get("githubAccountType", "")).lower() == "organization":
+        return f"https://github.com/organizations/{login}/settings/installations/{installation_id}"
+    return f"https://github.com/settings/installations/{installation_id}"
+
+
+def repo_url(repo_full_name: str) -> str:
+    return f"https://github.com/{repo_full_name}"
+
+
+def commit_url(repo_full_name: str, sha: str) -> str:
+    return f"https://github.com/{repo_full_name}/commit/{sha}"
+
+
+def binding_summary(git: dict | None) -> str:
+    """One-line `owner/repo@branch` for a binding, or a dash when unlinked."""
+    if not git:
+        return "—"
+    return f"{git.get('repoFullName', '?')}@{git.get('branch', '?')}"
+
+
+def describe_deploy(deploy: dict | None) -> str:
+    """A deploy attempt as `status (abc1234)`, with its reason when it failed."""
+    if not deploy:
+        return "—"
+    status = deploy.get("status", "unknown")
+    sha = deploy.get("commitSha")
+    text = f"{status} ({short_sha(sha)})" if sha else status
+    reason = deploy.get("reason")
+    if reason and status in ("failed", "cancelled"):
+        text += f": {reason}"
+    return text
+
+
+def is_running_linked_binding(git: dict | None, deployed_commit: dict | None) -> bool:
+    """Whether what is running actually came from the linked repo and branch.
+
+    False for the three states worth calling out: an agent just linked and
+    still serving its pre-link image, one whose repo was re-pointed, and one
+    whose branch was changed. All are legitimate, and all mean nothing from
+    this binding is live yet.
+
+    Repo names compare case-insensitively (GitHub treats owner/repo that way);
+    branches compare exactly, since git refs are case-sensitive. A missing
+    `ref` means "unknown", not "mismatched" — an older build recorded without
+    one says nothing about the branch.
+    """
+    if not git or not deployed_commit:
+        return False
+    deployed_repo = deployed_commit.get("repoFullName")
+    if not deployed_repo:
+        return False
+    if deployed_repo.lower() != str(git.get("repoFullName", "")).lower():
+        return False
+    ref = deployed_commit.get("ref")
+    if not ref:
+        return True
+    return ref_to_branch(ref) == git.get("branch")