feat: add poly functions commands and grouped CLI help (DEVP-541, DEVP-543)

[andymohajeri]

Summary

Adds a poly functions command group wrapping the public Functions REST API, so developers can manage Functions programmatically instead of only through the local-file/decorator workflow. Also groups the CLI's subcommand listings under section headers, since this PR pushes the top-level command count to 23.

Motivation

• DEVP-541: Integrate Functions API into ADK
• DEVP-543: Support grouped section headers in poly CLI --help output

A new public Functions REST API was built across platform_ui (Sourcerer/agent-stream) and poly_core. This surfaces it in the ADK for headless/programmatic use.

Note: the ADK already has a "functions" concept (poly/resources/function.py) — local .py files with @func_description/@func_parameter decorators, synced via gRPC/protobuf through push/pull. That mechanism is unrelated and untouched here; the two are intentionally kept separate, with a docs cross-reference so the distinction is discoverable. Unifying them is a likely follow-up.

DEVP-543 is bundled in at reviewer request. The two changes are independent and are separate commits.

Changes

poly functions (DEVP-541)

Follows the audio-cache / conversations command pattern.

• src/poly/cli_commands/functions.py (new): FunctionsCommand with list, get, create, update, delete, execute, duplicate, deploy, validate, references, type-definitions, deployments, and start/end for the branch lifecycle hooks. All support --json. Registered in cli.py via the usual 2-line import + COMMANDS entry.
• src/poly/handlers/platform_api.py: FUNCTIONS_* URL constants and the corresponding PlatformAPIHandler methods. 409 conflicts (orphaned flow-step references, name collisions) are translated into FunctionConflictError, a ValueError subclass carrying orphaned_references so --force and the CLI's conflict reporting can use them.
• src/poly/handlers/interface.py: AgentStudioInterface passthroughs.
• src/poly/output/console.py: print_functions, print_function_detail, print_function_references, print_function_deployments, print_function_validation_issues, and a shared print_code.
• Docs: a poly functions section in docs/docs/reference/cli.md, plus a cross-reference from the local-file Functions docs.

Unreadable --code-file paths and malformed --parameters / --args JSON exit with a clear message rather than a traceback.

Grouped --help sections (DEVP-543)

argparse has no built-in support for section headers within a subparsers group. Implements the ticket's option 2 — a custom HelpFormatter driven by a per-parser {subcommand: group} mapping — so each subcommand's own help= stays the single source of truth.

• poly --help: Getting started / Project sync / Builder API / Other
• poly functions --help: Manage / Run and inspect / Deploy / Lifecycle hooks
• poly branch --help: Branch lifecycle / Inspect

Mechanism lives in cli_commands/base.py: add_grouped_subparsers() creates the subparsers action and drops the outer positional arguments: heading; group_subcommands() reorders the help entries and injects header rows; _GroupedHelpMixin hides the redundant metavar placeholder and tidies whitespace, mixed into both a plain and a raw-text formatter so parsers with hand-formatted descriptions still work. BaseCommand gains a group attribute.

Parsing, error messages and shell completion are unchanged.

Overlap with #247: that PR concurrently rewrites branch.py and takes it from 9 to 15 subcommands, so whoever merges second resolves a conflict in branch.py, interface.py and cli_test.py (the latter two are append-adjacent — take both sides) and extends BRANCH_SUBCOMMAND_GROUPS with the new subcommands. The coverage test fails until they do, so it can't be missed silently.

Reviewer note: this necessarily touches three semi-private argparse attributes (_choices_actions, _action_groups, and a _format_action override) — the ticket anticipates this for option 2. Each has a comment explaining the mechanism, and the tests assert on rendered output so a future Python change fails loudly rather than silently degrading.

Test strategy

• Added/updated unit tests
• Manual CLI testing (poly <command>) — --help for every new command and subcommand, plus both error paths (missing and invalid subcommand) on each grouped parser
• Tested against a live Agent Studio project — not done: no live credentials/region access in this environment. Worth a smoke test against dev before merge.
• N/A

Handler tests live in src/poly/tests/api/platform_api_test.py, CLI tests in src/poly/tests/cli_test.py. Coverage includes the 409-conflict paths (create/update/delete/duplicate), the 204-empty-body delete, and the input-validation exits. Each grouped parser has a test asserting its mapping covers every subcommand it registers, so adding one without grouping it fails CI.

Checklist

• ruff check . and ruff format --check . pass
• pytest passes (1053 passed)
• No breaking changes to the poly CLI interface — poly functions is new, and the --help change is presentational
• Commit messages follow conventional commits

Screenshots / Logs

poly --help:

usage: poly [-h] [-v] <command> ...

Getting started:
    init               Initialize a new Agent Studio project.
    start              Get started with PolyAI Agent Studio
    login              Log in to an existing Agent Studio account
    studio             Open the current project in Agent Studio (web).
    project            Manage Agent Studio projects.

Project sync:
    pull               Pull the latest project configuration from Agent
                       Studio.
    push               Push the project configuration to Agent Studio.
    status             Check the changed files of the project.
    revert             Revert changes in the project.
    format             Run ruff and YAML/JSON formatting on the project
                       (optional ty with --ty).
    validate           Validate the project configuration locally.
    diff               Show the changes made to the project.
    review             Create a GitHub Gist of Agent Studio project changes to
                       share changes.
    branch             Manage branches in the Agent Studio project.

Builder API:
    deployments        Manage deployments for the project.
    conversations      List and inspect conversations.
    audio-cache        Manage cached TTS audio via the Audio Cache API.
    functions          Manage Functions via the public Functions REST API.
    test               Manage and run tests for the project.
    rtc                Manage Real-Time Configuration.
    chat               Start an interactive chat session with the agent.

Other:
    docs               Outputs documentation for a given topic.
    completion         Generate shell completion scripts

options:
  -h, --help           show this help message and exit
  -v, --version        show the version and exit

poly functions --help:

Manage:
    list               List functions on the current branch.
    get                Get a single function by ID.
    create             Create a new function.
    update             Update an existing function.
    delete             Delete a function.
    duplicate          Duplicate a function.

Run and inspect:
    execute            Execute a function with the given arguments.
    references         Show flow steps that reference a function.
    type-definitions   Show Python type stubs for a function, for IDE autocomplete.

Deploy:
    deploy             Deploy all draft functions on the current branch.
    validate           Validate all functions on the current branch.
    deployments        List function deployment history across environments.

Lifecycle hooks:
    start              Manage the branch's start_function.
    end                Manage the branch's end_function.

🤖 Generated with Claude Code

[linear-code]

DEVP-541

DEVP-543

[josephcesarperez]

lgtm functionally, just curious about the context for why we are introducing the usecase splitting out from the usual local pull push workflow

[Ruari-Phipps]

Yeah following on from what Joey said.
I think we need to allow for some commands to be handed account_id, project_id, region, branch_id directly rather than loading it from local file system.
Mainly the functions one here but we could also allow it for others

[andymohajeri]

@josephcesarperez re: why split this off instead of the standard push/pull workflow — three main reasons:

1. push/pull updates everything on the project, not just the resource being changed. It reads all of flows, entities, topics, agent settings, functions, etc. as one unit. Going through that flow to touch one function pulls the whole project state, which is slow, unnecessary for a single function update, and carries a bigger blast radius — if multiple CI jobs touch different functions, they can clobber each other's unrelated in-flight changes on a shared branch.

2. Some function operations aren't config-sync at all. execute, deployments, validate, references are runtime/operational actions — run a function, check deployment history, check orphaned references. There's no push/pull equivalent for any of that.

3. Different consumers want different things. push/pull is for devs working on a project who want git-style workflows (diff, review, branch). Some of the functions endpoints are meant to be called by CI, scripts, and other services — those want a scoped, stateless operation, not a full local checkout.

To be clear, this isn't replacing anything — the existing local .py-file/decorator Functions mechanism (poly/resources/function.py, synced via push/pull) is untouched and still the right tool for interactive local editing. This is additive, for the automation/headless case.

[github-actions]

Coverage Report

Base (main)	PR	Change
75.1%	75.1%	+0.0% ✅

Changed file coverage

File	Coverage	Change
poly/cli_commands/auth.py	22.7%	+1.1% ✅
poly/cli_commands/testing.py	29.1%	+0.7% ✅
poly/output/console.py	30.9%	-1.5% ⚠️
poly/cli_commands/shared.py	49.3%	+5.6% ✅
poly/cli_commands/project.py	52.8%	+0.3% ✅
poly/cli_commands/rtc.py	57.6%	+0.1% ✅
poly/cli_commands/branch.py	59.0%	+0.3% ✅
poly/cli_commands/utils.py	62.3%	+1.5% ✅
poly/cli_commands/sync.py	63.1%	+0.8% ✅
poly/handlers/interface.py	63.5%	+0.5% ✅
poly/cli_commands/chat.py	64.8%	+0.1% ✅
poly/cli_commands/review.py	67.2%	+0.2% ✅
poly/handlers/platform_api.py	75.5%	+5.1% ✅
poly/cli.py	80.4%	+1.6% ✅
poly/cli_commands/audio_cache.py	81.5%	+0.1% ✅
poly/cli_commands/deployments.py	84.4%	+0.0% ✅
poly/cli_commands/conversations.py	87.9%	+0.2% ✅
poly/cli_commands/base.py	94.7%	+8.1% ✅