feat: replace the chat family with the Ask CoCo window

[alentzjos]

Summary

Applications mount Ask CoCo with ask_coco(cwd): a floating launcher and window with one conversation, explicit approval requests, questions, plans, attachments, structured results and page requests. This replaces the chat, panel and copilot_rail family for 0.2.0; the migration table maps removed public names to the window API. CocoSession and query() remain available for headless use.

The package now owns the conversation, policy, gate, Cortex adapter, window assets, scripted agent, fixtures and harness previously developed in the Spec-First Cockpit. The default FolderPolicy allows reads within the working folder and asks before other actions. A standing file-change permission does not cover .git, secret-named files or flagged paths. Hosts can supply their own labels, context, prompts and policy.

The examples, API reference and feature documentation use the window. The delivery includes the original Ask CoCo design canvas (86 frames, two host-page views, manifest and CSS), a browser index and provenance notes in doc/features/ask-coco/design/.

Features included

• Floating assistant window: one launcher and window mounted by ask_coco(cwd), with connect/disconnect, suggested prompts, streaming answers, tool steps, Stop, queued messages with Take back, and New conversation. A single component runs inside a fragment; idle polling stops and a completed file-changing run refreshes the page once.
• Approval and planning: ordered approval requests, questions with choices or text answers, plan approval or decline, a planning-only mode with Carry out the plan, and a Plan first menu switch. Questions and plans always wait for the user.
• Host-controlled rights: FolderPolicy, exact listed commands, read-only Git helpers, SQL and lookup rules, additional read folders (also_read), and optional standing permissions by family that can be revoked. Protected paths still ask; standing file-change permissions never cover .git, secret-named files or paths flagged by the host. Requests are described from the checked call, with exact command, file or SQL evidence.
• Data and files: structured answers, SQL results rendered as tables, a wider table view with optional CSV download, code blocks and copy controls, files attached in the composer with host-defined limits, and working-folder upload support.
• Page integration: coco.ask() starts a request from a page button, coco.result() hands back a completed result once without losing it while pending, coco.form() hosts a page question, and notices and callbacks connect the window with the app. Optional page text, open-dialog text and selection accompany a message.
• Configuration and session: optional latest-exchange, shortened and raw display modes; reasoning and session details; connection/configuration selection; labels and policy words supplied by the host. Labels can change between runs without resetting the conversation. A missing working folder is reported clearly before connecting.
• Developer tools and examples: Cortex Code adapter and pre-tool gate, a scripted agent with no Snowflake login, named view fixtures, standalone harness and DOM comparison. Chat, approval, upload, structured output and headless examples are updated, along with App Builder, BI to Semantic and Backlog Desk.
• Design and migration deliverables: the original canvas (86 frames and two host-page views), migration table, no-regression evidence, API reference, feature checklist and updated setup/security documentation.

These features were first developed in the Cockpit and are delivered here as reusable package functionality. Optional features are enabled by the host; the default installation does not enable every playground feature.

Type of change

• New feature
• Refactor / tech debt
• Documentation

Compatibility and review

• Companion PR: DevoteamSP/spec-first #15.

• Contribution branch: alentzjos:feat/ask-coco-window, targeting DevoteamSP/streamlit-coco:main.

• Breaking API change from 0.1.9: review the migration sheet in doc/features/ask-coco/ask-coco.md, section 2, and the no-regression table in section 3.

• Version remains 0.2.0.dev0; this PR does not publish or tag a release.

• The companion Spec-First PR consumes the package through a committed development wheel; review and merge the package first.

• Canvas sources are preserved byte for byte. Finished consultation pages omit the original editor scripts and disable links to Cockpit mockups outside the canvas. Montserrat loads from Google Fonts, with a system-font fallback offline.

• The canvas ships in the repository and sdist; the runtime wheel contains only the package and runtime assets.

Validation

Checked locally on 2026-10-13:

• ruff check .: passed.
• Unit tests (pytest tests/ --ignore=tests/e2e -q): 583 passed, 2 skipped, 741 subtests passed.
• Canvas: nine original files match the supplied sources byte for byte, including in the Git index; the manifest resolves all five boards and frames 1-86 each occur once.
• uv build --sdist: passed; all 17 design delivery files are present and match the working copy.
• Five standalone design previews: opened in Edge with CSS loaded, no JavaScript errors and no missing local resources. The index links all five views.
• The local uv.lock is preserved, ignored by Git and excluded from the sdist.
• README/API guidance matches working-folder validation and language changes; historical roadmap links point to the current API or migration sheet.
• git diff --cached --check: passed before both documentation commits.

Design delivery commit: 5bc9c64; cleanup commit: e4807aa; finished-preview delivery without the generator: d4e9a93. The runtime is unchanged by these documentation/packaging commits, so the 583-pass unit result remains applicable; the lint, canvas preview and source archive checks were rerun after cleanup. Browser E2E rerun before opening the PR: 5 passed. Dependency audit (pip-audit --skip-editable): no known vulnerabilities found.

Remaining release checks

• Real Cortex Code / Snowflake integration validation confirmed by the contributor during review; detailed per-scenario results are not recorded here.
• Automated gate: lint, units, browser E2E (5 passed), dependency audit (no known vulnerabilities).
• Version release kit and publication checks, before tagging.

The canvas index uses the original warm palette and local Montserrat, with five static board links and a responsive layout (commit 96849b4). Desktop and mobile rendering were verified in Edge.

GitHub CI initially exposed two Windows-specific path expectations on Linux. Commit 2f98278 corrects the tests to verify native path semantics on each system without changing runtime policy; the local policy suite passed (125 tests, 2 skipped, 577 subtests). All GitHub checks pass on the follow-up commit 152d29c: unit/lint, browser E2E, gitleaks and pip-audit. Native path assertions cover the request and the offered standing permission on each system.