streamlit-coco 0.2.2__tar.gz → 0.3.0__tar.gz

{streamlit_coco-0.2.2 → streamlit_coco-0.3.0}/.gitignore

@@ -34,3 +34,9 @@ examples/app_builder/out/
 # Optional Power BI samples (~17 MB) — fetch with examples/bi_samples/powerbi/fetch.sh
 examples/bi_samples/powerbi/Human Resources Sample PBIX.pbix
 examples/bi_samples/powerbi/Employee Hiring and History.pbix
+
+# Skills shop Native App: per-user overrides
+examples/skills_hub_native/snowflake.local.yml
+
+# snow app run output
+examples/skills_hub_native/output/

streamlit_coco-0.3.0/.gitleaks.toml

@@ -0,0 +1,14 @@
+# Gitleaks: the default rules, and one allowlist for the tests that use fake credentials on purpose
+# (tests/test_audit.py checks that the audit log redacts them, tests/test_skills_hub.py that a skill
+# folder holding one is refused). No real secret is in either file.
+title = "streamlit-coco"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Fake credentials used as test data"
+paths = [
+  '''tests/test_audit\.py''',
+  '''tests/test_skills_hub\.py''',
+]

{streamlit_coco-0.2.2 → streamlit_coco-0.3.0}/AGENTS.md

@@ -33,7 +33,8 @@ Canonical SDK docs: https://docs.snowflake.com/en/user-guide/cortex-code-agent-s
 make install      # uv sync --extra dev
 make check        # ruff and the unit tests (not the browser tests)
 make e2e          # Playwright, the window on the scripted agent (Edge if Chromium is missing)
-make audit        # pip-audit
+make audit        # pip-audit: the root lock and every examples/*/uv.lock
+make release-check # before sync-release and the tag: version, public CHANGELOG, audits, Dependabot alerts, sync dry run
 make test-all     # check, e2e, audit
 make simple-chat # panel, a test-prompt picker, rights as pills (`make chat` still runs it)
 make modern-chat # Copilot rail, floating window, or both
@@ -68,6 +69,6 @@ Full test process: [`doc/testing.md`](doc/testing.md).
 
 - Unit tests: `tests/` (`make check`).
 - Browser tests: `tests/e2e/` (the window) and `tests/e2e_classic/` (the 0.1.9 chat helpers) (`make e2e-install` once, then `make e2e`).
-- 0.1.9 compatibility: `tests/test_compat_019.py` holds the package to `tests/fixtures/api_0.1.9.json`. A public name, parameter or default of 0.1.9 does not change; add new parameters last, keyword-only, with a default. Do not delete the 0.1.9 tests (`test_copilot_rail.py`, `test_rich_text.py`, `test_classic_*.py`, `tests/e2e_classic/`).
+- Compatibility with released versions: `tests/test_compat_019.py` holds the package to `tests/fixtures/api_0.1.9.json` `tests/test_compat_022.py` to `tests/fixtures/api_0.2.2.json` (what 0.2.0 to 0.2.2 added: `ask_coco`, `Features`, `get_window`, ...) and `tests/test_compat_030.py` to `tests/fixtures/api_0.3.0.json` (the managed agent, `AuditLog`). A public name, parameter or default of a released version does not change; add new parameters last, keyword-only, with a default. When a release is cut, add `tests/fixtures/api_X.Y.Z.json` and its `test_compat_*` (recipe in `tests/api_snapshot.py`; take the snapshot from the tag's source with the SDK that release used installed, else the SDK's own classes show as stubs). Do not delete the 0.1.9 tests (`test_copilot_rail.py`, `test_rich_text.py`, `test_classic_*.py`, `tests/e2e_classic/`).
 - Manual, live Cortex Code: [`doc/features/ask-coco/test-checklist.md`](doc/features/ask-coco/test-checklist.md) before a release.
 - Process: [`doc/testing.md`](doc/testing.md).

{streamlit_coco-0.2.2 → streamlit_coco-0.3.0}/CHANGELOG.md

@@ -12,6 +12,41 @@ Living plan (what’s next): [`doc/roadmap.md`](doc/roadmap.md).
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-10-26
+
+Snowflake's managed coding agent runs in the same window, with no `cortex` program, and every decision can be written to an audit log. The SDK is now `snowflake-cortex-agent-sdk` for both. Upgrading from 0.2.x: nothing to change for an application that uses the Cortex Code program (`pip install streamlit-coco[sdk]` installs the new package; replace a pinned `cortex-code-agent-sdk` in your own requirements). Everything new is opt-in, and every new parameter is keyword-only with a default that keeps today's behaviour. The managed agent and the Native App example are experimental (the SDK is a public preview, `0.0.x`).
+
+### Added
+
+- **Approval audit log:** `AuditLog(path, who=...)` and `ask_coco(audit=)` write one JSON line per call that asked the user, was covered by a standing permission or was refused: who, when, the agent, the tool, the decision (`allowed`, `declined`, `expired`, `refused`, `standing`, `revoked`) and the exact command, SQL or path the user was shown. Works with every agent. Off by default; the file is readable by its owner only; a failing write is logged and never stops CoCo (SEC-01 of the threat model). Credentials in what the user was shown are redacted before the write (`redact_secrets`, overridable with `AuditLog(redact=)`, `None` to write as shown; what it does not protect is documented), and an allowed call gets a second `outcome` line (`succeeded`, `failed`, `not_run`, `no_result`) joined by `tool_id`.
+- **Files attached in the managed window:** `ManagedOptions(upload_stage="DB.SCHEMA.STAGE", connection=...)` puts each attached file in a folder of this conversation on a stage mounted at `/uploads` in the sandbox; the agent is told the sandbox path (never the local one), no copy stays in the working folder, and the folder is removed from the stage when the conversation ends. Files go in **before the first message**: the sandbox reads the stage once (checked live), so a later one is refused with a sentence that says to start a new conversation. Without `upload_stage` an attached file is refused and the window says why. An agent opts in with an optional `carry(paths)` (`backend.py`).
+- `check_environment(managed=True)` and `require_environment(managed=True)`: the managed agent runs in Snowflake, so the `cortex` program is not looked for and `ready` needs only the SDK. `CocoEnvironment.managed`.
+- `FolderPolicy(where=)` and `SANDBOX_WHERE`: the request's "Where" line names the Snowflake sandbox, not a local folder the managed agent does not have. An agent can bring its own window words (`labels`); the managed agent's first screen says it works in a sandbox and no longer says it reads project files.
+- Least-privilege role documentation (SEC-02, `doc/security/threat-model.md` section 8) and the threat model for the managed agent and the Native App.
+- Tests: `tests/test_audit.py`, `tests/test_managed_files.py`, the probe tests, and `tests/e2e/test_managed_window.py` on `examples/e2e_managed_harness.py` (the window on the managed agent over a scripted stream of Snowflake's client: first screen, a command that asks in the sandbox, Allow, Decline, the audit lines, an attached file).
+- **Managed agent (experimental):** `ManagedOptions` and `managed_agent` run Snowflake's managed coding agent (Cortex Agent SDK) in the same window, with no `cortex` program: `ask_coco(".", agent=st_coco.managed_agent(ManagedOptions(account=..., token=...)))`. Every approval still goes through the policy and the gate; the run is always created with `permission_policy="always_ask"` and only the user's Allow is sent, as the server's one-call "Allow this command" (never its "Allow all ... for this session"). The server asks only about calls it rates risky; the policy sees those. `options_from_connection(profile, role=...)` builds the options from a `~/.snowflake` profile (session token, least-privilege role) and `SANDBOX_WORDS` tells the request that a command runs in the Snowflake sandbox; `make managed` runs `examples/managed_chat.py`. `streamlit_coco.backend.AgentBackend` names the surface an agent keeps (the Cortex Code agent, the managed agent and the scripted agent). Tested on a scripted stream (`testing/managed_fake.py`) and run live on a Snowflake account (a read-free answer, a declined and an allowed write, with a session token and the `PUBLIC` role).
+
+- **Skills shop example (experimental):** `make skills-hub` runs `examples/skills_hub/`: skills (a `SKILL.md` folder) kept on a Snowflake stage, a shop to browse them and a chat with one chosen skill on the managed agent (`stage_skills`); `make publish-skill` validates and publishes a skill folder (versions never change). Before a chat the app checks that the folder on the stage is the one that was published, an added file included. Run live on a scratch stage. See [`examples/skills_hub/README.md`](examples/skills_hub/README.md).
+
+- **Skills shop as a Native App (experimental):** `examples/skills_hub_native/` packages the shop and the one-skill chat as a Snowflake Native App that runs as a Snowpark Container Services service (`make native-shop-image`, `make native-shop-deploy`, see its `DEPLOY.md`). The service logs in with its own token, publishes the skills baked into the image to the application's stage when it starts (a version already there is never replaced; the stage is in a schema that is not versioned, so skills survive upgrades) and the managed agent runs as the application. Needs two grants to the application for Cortex, in `scripts/grant_privileges.sql`, that you run yourself. Run live on a Snowflake account: the Agent API answered a skill from inside the service. `examples/skills_hub_native/COCO_PROMPT.md` is a prompt for Cortex Code that asks a new user for the parameters (profile, role, warehouse, image repository), checks the account and builds, installs and starts the application, asking before every step that creates, costs credits or grants a right.
+
+- `make release-check` (`scripts/release_check.py`): before a release, the version is free on PyPI and the public tags, the public CHANGELOG has no release this one lacks, every lock is audited, open Dependabot alerts are listed by manifest, and the sync dry run is summarised (deletions, generated `out/` files, dev-only leaks). `make audit` now also audits every `examples/*/uv.lock` (`scripts/audit_locks.py`), which the root audit could not see.
+
+### Changed
+
+- There is no `mode="api"` on `CocoOptions`: the Cortex Agent SDK has one local interface (`mode` is `cli` only) and the managed agent is a separate backend (`managed_agent`, `AgentBackend`), so one library covers both with the same window, policy and gate. The development lock holds `snowflake-cortex-agent-sdk` 0.0.3 (a public preview: pin and re-check before a release).
+- The managed agent no longer reuses the Cortex Code prompt: it has its own instructions (it runs in Snowflake's sandbox, with no question or plan tool) and is told nothing of this computer. Found live: it had answered with the developer's local working folder.
+- The `sdk` and `dev` extras now install `snowflake-cortex-agent-sdk>=0.0.3,<0.1` (a public preview, so capped below `0.1`; the Cortex Agent SDK, `cortex_agent_sdk.cortexcode`) in place of `cortex-code-agent-sdk`. It drives the same local `cortex` program with the same options, messages, `can_use_tool` and hooks; nothing changes for an application (`pip install streamlit-coco[sdk]` stays). The window, the approval gate and `query()` were run against a live Cortex Code 1.2.18. The environment probe and the "SDK missing" messages name the new package. Replace a pinned `cortex-code-agent-sdk` in your own requirements.
+
+### Security
+
+- The development locks (`uv.lock`, `examples/app_builder/uv.lock`) cover Python 3.11 and later (`[tool.uv] environments`). A Python 3.10 branch kept `pillow` 12.3.0 in them (Pillow 13, which fixes its advisories, needs 3.11), and Dependabot reports every version in a lock. The package still declares `requires-python >=3.10` and does not pin Pillow; only `uv sync` and `uv lock` in this repository need Python 3.11. CI and the release workflow already run on 3.11.
+
+### Fixed
+
+- The line that says what a standing permission covers ("CoCo no longer asks before it ...") ended with two full stops.
+- The public CI failed on a fresh `uv sync` (the public tree has no `uv.lock`): with `[tool.uv] environments`, uv 0.13 also resolves for Pyodide (emscripten), where `playwright` has no wheel. The environments now leave emscripten out (both `pyproject.toml` files; locks relocked, no package version changed). Gitleaks flagged the fake credentials the audit and skills-shop tests use on purpose: `.gitleaks.toml` allowlists those two test files and keeps the default rules.
+
 ## [0.2.2] — 2026-10-25
 
 Ask CoCo can leave the corner: attached to an edge on the full height of the page, or on the whole page. The page can be told where the window is, and take the rest of the screen. Upgrading from 0.2.0 or 0.2.1: nothing to change; every new parameter is keyword-only with a default that keeps today's behaviour.

{streamlit_coco-0.2.2 → streamlit_coco-0.3.0}/Makefile

@@ -1,6 +1,6 @@
 # streamlit-coco — local development
 UV       ?= uv
-# Always include [dev] so cortex-code-agent-sdk is available for demos/tests.
+# Always include [dev] so snowflake-cortex-agent-sdk is available for demos/tests.
 PYTHON   ?= $(UV) run --extra dev
 E2E_PYTHON ?= $(UV) run --extra e2e
 STREAMLIT = $(PYTHON) python -m streamlit run
@@ -8,9 +8,9 @@ EXAMPLE  ?= examples/chat_app.py
 
 .DEFAULT_GOAL := help
 
-.PHONY: help install sync test lint format check audit e2e-install e2e test-all \
-	run chat simple-chat modern-chat approval structured headless backlog cwd-upload e2e-harness \
-	bi-semantic tableau-semantic app-builder \
+.PHONY: help install sync test lint format check audit release-check e2e-install e2e test-all \
+	run chat simple-chat modern-chat approval managed structured headless backlog cwd-upload e2e-harness \
+	skills-hub publish-skill native-shop-image native-shop-deploy native-shop-restart native-shop-status native-shop-logs native-shop-teardown bi-semantic tableau-semantic app-builder \
 	build publish sync-release clean adoption-stats adoption-chart \
 	training training-html training-pdf training-check
 
@@ -42,8 +42,12 @@ format: ## Format with ruff
 	$(PYTHON) ruff format .
 	$(PYTHON) ruff check --fix .
 
-audit: ## Dependency vulnerability scan (pip-audit)
+audit: ## Dependency vulnerability scan (pip-audit) of the root lock and every examples/*/uv.lock
 	$(PYTHON) pip-audit --skip-editable
+	$(PYTHON) python scripts/audit_locks.py
+
+release-check: ## Before sync-release and the tag: version free on PyPI/tags, public changelog, audits, alerts, sync dry run
+	$(PYTHON) python scripts/release_check.py
 
 check: lint test ## Lint then unit tests
 
@@ -71,6 +75,37 @@ modern-chat: ## Copilot rail or Ask CoCo window (examples/modern_chat)
 approval: ## Run examples/approval_gate.py
 	$(STREAMLIT) examples/approval_gate.py
 
+managed: ## Run examples/managed_chat.py (Snowflake's managed coding agent, no cortex program)
+	$(STREAMLIT) examples/managed_chat.py
+
+skills-hub: ## Run the skills shop (browse stage skills, chat with one; sample skills need no Snowflake)
+	$(STREAMLIT) examples/skills_hub/app.py
+
+publish-skill: ## Validate and publish a skill folder: make publish-skill SKILL=examples/skills_hub/samples/csv-profile ARGS="--stage DB.SCHEMA.STAGE --profile P --role R"
+	$(PYTHON) python examples/skills_hub/publish.py $(SKILL) $(ARGS)
+
+SNOW_CONNECTION ?= snowflake
+NATIVE_SHOP = examples/skills_hub_native
+
+native-shop-image: ## Build and push the Skills shop image (Docker running)
+	$(NATIVE_SHOP)/containers/build_and_push.sh $(SNOW_CONNECTION)
+
+native-shop-deploy: ## Package and install/upgrade the Skills shop Native App (snow app run)
+	cd $(NATIVE_SHOP) && snow app run --connection $(SNOW_CONNECTION)
+
+native-shop-restart: ## Restart the Skills shop service (suspend, resume)
+	snow sql -q "CALL coco_skills_shop.app_schema.suspend_service()" --connection $(SNOW_CONNECTION)
+	snow sql -q "CALL coco_skills_shop.app_schema.resume_service()" --connection $(SNOW_CONNECTION)
+
+native-shop-status: ## Status of the Skills shop service
+	snow sql -q "CALL coco_skills_shop.app_schema.get_service_status()" --connection $(SNOW_CONNECTION)
+
+native-shop-logs: ## Logs of the Skills shop container
+	snow sql -q "CALL coco_skills_shop.app_schema.get_service_logs('0', 'streamlit')" --connection $(SNOW_CONNECTION)
+
+native-shop-teardown: ## Drop the Skills shop application, its service, pool and package
+	cd $(NATIVE_SHOP) && snow app teardown --connection $(SNOW_CONNECTION) --force --cascade
+
 structured: ## Run examples/structured_output.py
 	$(STREAMLIT) examples/structured_output.py
 

{streamlit_coco-0.2.2 → streamlit_coco-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: streamlit-coco
-Version: 0.2.2
+Version: 0.3.0
 Summary: Streamlit component and Python library for Snowflake CoCo (Cortex Code)
 Project-URL: Homepage, https://github.com/lletourmy/streamlit-coco
 Project-URL: Documentation, https://github.com/lletourmy/streamlit-coco#readme
@@ -22,53 +22,65 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: streamlit>=1.55
 Provides-Extra: dev
-Requires-Dist: cortex-code-agent-sdk>=1.0.7; extra == 'dev'
 Requires-Dist: pbixray>=0.15.4; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: snowflake-cortex-agent-sdk<0.1,>=0.0.3; extra == 'dev'
 Provides-Extra: e2e
-Requires-Dist: cortex-code-agent-sdk>=1.0.7; extra == 'e2e'
 Requires-Dist: pbixray>=0.15.4; extra == 'e2e'
 Requires-Dist: pip-audit>=2.7; extra == 'e2e'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'e2e'
 Requires-Dist: pytest-playwright>=0.6; extra == 'e2e'
 Requires-Dist: pytest>=8.0; extra == 'e2e'
 Requires-Dist: ruff>=0.8; extra == 'e2e'
+Requires-Dist: snowflake-cortex-agent-sdk<0.1,>=0.0.3; extra == 'e2e'
 Provides-Extra: sdk
-Requires-Dist: cortex-code-agent-sdk>=1.0.7; extra == 'sdk'
+Requires-Dist: snowflake-cortex-agent-sdk<0.1,>=0.0.3; extra == 'sdk'
 Description-Content-Type: text/markdown
 
 # streamlit-coco
 
-**Built by Devoteam Snowflake Partner.** Ask CoCo for Streamlit: a floating chat window, in front of a Cortex Code agent, that you add to your own application with one call. You say what the agent may do alone and what it must ask first. The window shows each request in plain words, with the exact command, file text or SQL statement one click away.
+**Built by Devoteam Snowflake Partner.** Ask CoCo for Streamlit: a floating chat window, in front of a Snowflake coding agent, that you add to your own application with one call. You say what the agent may do alone and what it must ask first. The window shows each request in plain words, with the exact command, file text or SQL statement one click away, and every decision can be written to an audit log.
 
 [![CI](https://github.com/lletourmy/streamlit-coco/actions/workflows/ci.yml/badge.svg)](https://github.com/lletourmy/streamlit-coco/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-> `0.2.2` (alpha). The API may still move. The default interface is still the 0.1.9 chat family (`chat`, `panel`, `copilot_rail`). The floating window is opt-in: `mini=True` on those calls, or `ask_coco(cwd)`. See [`doc/features/ask-coco/ask-coco.md`](doc/features/ask-coco/ask-coco.md).
+> `0.3.0` (alpha, the API may still move). The default interface is still the 0.1.9 chat family (`chat`, `panel`, `copilot_rail`); the floating window is opt-in (`mini=True` on those calls, or `ask_coco(cwd)`). **New and experimental:** Snowflake's managed coding agent runs in the same window with no `cortex` program, files attached in the window go to the sandbox, and `AuditLog` records who allowed what. The managed agent rests on a public-preview SDK (`snowflake-cortex-agent-sdk` 0.0.x). Details: [`doc/features/ask-coco/ask-coco.md`](doc/features/ask-coco/ask-coco.md).
 
 **Repo:** [github.com/lletourmy/streamlit-coco](https://github.com/lletourmy/streamlit-coco) *(temporary PyPI source)* · **Dev:** [streamlit-coco-dev](https://github.com/DevoteamSP/streamlit-coco-dev)
-**SDK docs:** [Cortex Code Agent SDK](https://docs.snowflake.com/en/user-guide/cortex-code-agent-sdk/cortex-code-agent-sdk)
+**SDK docs:** [Cortex Agent SDK](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agent-sdk/cortex-agent-sdk) · [Cortex Code Agent SDK](https://docs.snowflake.com/en/user-guide/cortex-code-agent-sdk/cortex-code-agent-sdk)
 
 ---
 
 ## What you get
 
 - A launcher at the bottom right of the page, and a window that opens from it. The window is the whole interface: connect, ask, watch the steps, answer requests.
-- Rights written as code, in one object (a `Policy`). The default is the safest: reading inside the working folder is free, everything else asks, each time.
+- **Rights written as code**, in one object (a `Policy`). The default is the safest: reading inside the working folder is free, everything else asks, each time.
 - Every request names what it is about and shows the exact text of what would run.
+- **Two real agents behind the same window**, the same policy and the same Allow and Decline: the Cortex Code program on the server, or Snowflake's managed coding agent in a Snowflake sandbox (experimental).
+- An **audit log**: one JSON line per decision, with who, when and the exact command shown.
 - Buttons of your own page can ask CoCo something in the user's name, and read the answer back.
 - A scripted agent (`STREAMLIT_COCO_AGENT=mock`) so you can build and test with no Snowflake login.
 - Headless `query()` and `CocoSession` for scripts and CI.
 
+## Which agent
+
+| | Cortex Code program | Managed agent (experimental) | Scripted |
+| --- | --- | --- | --- |
+| Runs | on the Streamlit server, in your working folder | in a Snowflake sandbox | in the page's process |
+| Needs | the `cortex` program on the `PATH`, a Snowflake profile | a Snowflake profile and a role (or a token), outbound HTTPS to the account | nothing |
+| Files it sees | the working folder | what you mount (workspace, stage) and what the user attaches, before the first message | none |
+| Rights | the policy judges every call | the policy judges every call the server asks about; the role of the session is the limit | the policy shows and asks, nothing runs |
+| Use | `ask_coco(".")` | `ask_coco(".", agent=managed_agent(options))` | `STREAMLIT_COCO_AGENT=mock` |
+
 ## When not to use
 
 - **You want CoCo Desktop, the CLI, or an IDE extension.** This is an embed in your Streamlit application. It has no file tree and no editor.
-- **The Streamlit host cannot run CoCo.** The agent runs on the server (the Cortex Code program on the host). Streamlit Community Cloud without that setup will not work.
-- **You are not building in Python and Streamlit.** There is no TypeScript package. Use the [Cortex Code Agent SDK](https://docs.snowflake.com/en/user-guide/cortex-code-agent-sdk/cortex-code-agent-sdk) directly.
-- **You would not type the SQL yourself on this role.** The agent uses the Snowflake role of the connection. Do not wire `ACCOUNTADMIN` into a web page.
+- **The Streamlit host can run neither agent.** The Cortex Code program needs a host that can run it; the managed agent needs outbound HTTPS to your Snowflake account and a login. Streamlit Community Cloud without one of those will not work. (Streamlit in Snowflake is planned, not shipped.)
+- **You are not building in Python and Streamlit.** There is no TypeScript package. Use the [Cortex Agent SDK](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agent-sdk/cortex-agent-sdk) directly.
+- **You would not type the SQL yourself on this role.** The agent uses the Snowflake role of the connection. Do not wire `ACCOUNTADMIN` into a web page: give it the least role that works ([threat model, section 8](doc/security/threat-model.md)).
 
 ---
 
@@ -84,8 +96,9 @@ From a clone (editable, with the tests): `make install`.
 Needs:
 
 1. Python 3.10 or later, Streamlit 1.55 or later.
-2. For a real agent: the Cortex Code program on the `PATH` (`cortex --version`), a Snowflake connection (`~/.snowflake/connections.toml` or `config.toml`), and `cortex-code-agent-sdk` (the `sdk` extra). The window says what is missing and how to fix it.
-3. For a scripted agent: nothing more. See below.
+2. For the Cortex Code agent: the Cortex Code program on the `PATH` (`cortex --version`), a Snowflake connection (`~/.snowflake/connections.toml` or `config.toml`), and `snowflake-cortex-agent-sdk` (the `sdk` extra, pinned `>=0.0.3,<0.1`). The window says what is missing and how to fix it.
+3. For the managed agent: no `cortex` program; a profile and a role to log in with, and the same `sdk` extra. See [The managed agent](#the-managed-agent-experimental).
+4. For a scripted agent: nothing more. See below.
 
 Full local setup: [`doc/deployment/local.md`](doc/deployment/local.md). Every public name: [`doc/api.md`](doc/api.md).
 
@@ -167,24 +180,65 @@ Connect, then type these words. The scripted agent picks its script from a keywo
 | `edit` | A request to change a file: **Allow CoCo to change a file?** It says `README.md`, one line. **Show change** opens the text. |
 | `snowflake drop` | A request to run a statement that can change Snowflake. It says `DROP`. **Show statement** opens `drop table DEMO.PUBLIC.OLD_CALLS`. |
 
-If you type while a request waits, the message is queued behind it ("Queued", with **Take back**) and is sent after Allow or Decline.
+If you type while a request waits, the message is queued behind it ("Queued", with **Take back**) and is sent after Allow or Decline. Nothing runs until the user presses **Allow**; **Decline** ends the call. The scripted agent never runs the command or reaches Snowflake: it only shows and asks. With a real agent the same policy decides, and **Allow** runs the call.
 
-To see a file that `changes` does not call ordinary, give the policy a narrower rule, for example `changes="docs/*.md"`. The `edit` request on `README.md` is then flagged: it reads "Allow CoCo to change a file outside what it usually changes? It cannot be undone.", it names the full path of the file instead of `README.md`, and its note says "1 line, outside what it usually changes". **Show change** still opens the text. With `changes="*.md"` it is the ordinary request shown above.
+What each argument did:
 
-The scripted agent only ever makes its own fixed calls, so it cannot exercise every rule you write:
+- `commands=[status]`: a call whose command is exactly this line is a read, named "Look at what has changed". Any other command asks as a change, with its whole line.
+- `changes="*.md"`: a change to a Markdown file is ordinary. A change to any other file asks too, and says it is unusual. Try `changes="docs/*.md"` and the `edit` request is flagged: "outside what it usually changes", with the full path.
+- `sql=True`: a SQL call shows its exact statement. A statement that surely only reads is a query. Anything else is a statement that can change Snowflake.
 
-- The one command it asks for is `git status --short`. Another command you list in `commands` cannot be tried with it.
-- `edit` changes the first Markdown file of the folder, and `write` creates `coco_note.md`. A rule about other file types shows only as "not ordinary", on those two files.
+The scripted agent makes only its own fixed calls (`git status --short`, an edit of the first Markdown file, `coco_note.md`), so it cannot try every rule you write. More switches (`standing`, `lookups`, `also_read`, `git_readonly`) are in [`doc/api.md`](doc/api.md). A runnable version with a standing permission is `examples/approval_gate.py`.
 
-In each case nothing runs until the user presses **Allow**. **Decline** ends the call. The scripted agent never runs the command or reaches Snowflake: it only shows and asks. With a real agent the same policy decides, and **Allow** runs the call.
+---
 
-What each argument did:
+## The managed agent (experimental)
 
-- `commands=[status]`: a call whose command is exactly this line is a read, named "Look at what has changed". Any other command asks as a change, with its whole line.
-- `changes="*.md"`: a change to a Markdown file is ordinary. A change to any other file asks too, and says it is unusual.
-- `sql=True`: a SQL call shows its exact statement. A statement that surely only reads is a query. Anything else is a statement that can change Snowflake.
+Snowflake's managed coding agent, through the Cortex Agent SDK. It runs in a Snowflake sandbox: no `cortex` program, no working folder. It takes the same window, the same policy and the same Allow and Decline.
+
+```python
+import streamlit as st
 
-More switches (`standing`, `lookups`, `also_read`, `git_readonly`) are in [`doc/api.md`](doc/api.md). A runnable version with a standing permission is `examples/approval_gate.py`.
+import streamlit_coco as st_coco
+from streamlit_coco.policy import FolderPolicy
+
+# Logs in with the connector: do it once per session, never on every rerun.
+if "managed" not in st.session_state:
+    st.session_state.managed = st_coco.options_from_connection(
+        "my_profile",       # a profile of ~/.snowflake
+        role="PUBLIC",      # the agent works with this role's rights: the least that works
+    )
+options = st.session_state.managed
+
+st_coco.ask_coco(
+    ".",
+    agent=st_coco.managed_agent(options),
+    connection=options.label,
+    policy=FolderPolicy(".", words=st_coco.SANDBOX_WORDS, where=st_coco.SANDBOX_WHERE),
+)
+```
+
+`make managed` runs a complete example (profile and role form, then the window).
+
+- **Always asks.** The run is created with `permission_policy="always_ask"`; it is not an option. Only the user's Allow becomes the server's one-call "Allow this command". The server's own "Allow all bash for this session" is never chosen.
+- **The server decides what it asks about.** A command it rates risky pauses the run and reaches your policy; one it rates harmless (`echo hello`) runs unasked. The role of the session, not the window, is the real limit: give it the least rights that work.
+- **No local folder.** `cwd` is only the policy's and is never sent. The agent works on what you mount (`workspace_mounts`, `stage_mounts`, `stage_skills`) and on what the user attaches.
+- **Attach a file.** `Features(attachments=st_coco.Attachments())` with `options_from_connection(..., upload_stage="DB.SCHEMA.STAGE")`: each file goes to a folder of this conversation on that stage, mounted at `/uploads`, and is removed with the conversation. Files go in **before the first message** (the sandbox reads the stage once); a later one is refused with a sentence that says so.
+- **Probe without the program:** `check_environment(managed=True)`.
+- **Not available:** the agent's own questions and plans (Cortex Code's tools), planning only.
+
+Skills on a stage and a chat with one chosen skill: `make skills-hub`, and the same as a Snowflake Native App on Snowpark Container Services: [`examples/skills_hub_native/`](examples/skills_hub_native/DEPLOY.md), which also holds a prompt for Cortex Code that asks for your parameters and deploys it ([`COCO_PROMPT.md`](examples/skills_hub_native/COCO_PROMPT.md)).
+
+---
+
+## Who allowed what: the audit log
+
+```python
+audit = st_coco.AuditLog("logs/coco-audit.jsonl", who=lambda: st.user.get("email"))
+st_coco.ask_coco(".", audit=audit)
+```
+
+One line per call that asked the user, was covered by a standing permission, or was refused: `time`, `who`, `agent`, `tool`, `decision` (`allowed`, `declined`, `expired`, `refused`, `standing`, `revoked`) and the exact command, SQL or path the user was shown, with what looks like a credential replaced by `[redacted]` (`AuditLog(redact=...)` to change it, `None` to turn it off; a secret that looks like nothing, such as a plain `-p hunter2`, is **not** caught). A second line, `decision: "outcome"`, says whether an allowed call `succeeded`, `failed`, was `not_run` or got `no_result`. Reads inside the working folder that run without a question are not logged. The file is readable by its owner only; it is not tamper-proof (ship it to storage the app cannot rewrite if that matters). The library cannot know who answers: give `who`. See [`doc/api.md`](doc/api.md#the-audit-log).
 
 ---
 
@@ -216,7 +270,7 @@ if done:
 | `coco.open()`, `coco.new()`, `coco.disconnect()` | Open the window, end the conversation, end the session. |
 | `coco.latest_answer` | The text of the latest answer, for a page that shows it elsewhere. |
 
-Other arguments of `ask_coco`: `features` (what the window offers), `context` (what your page knows when a message is sent), `labels` (every sentence, to translate), `theme` (colours, font), `options` (model, connection, structured output), `on_files_changed`. All of them are in [`doc/api.md`](doc/api.md).
+Other arguments of `ask_coco`: `features` (what the window offers: attachments, display switches, window places), `context` (what your page knows when a message is sent), `labels` (every sentence, to translate), `theme` (colours, font), `options` (model, connection, structured output), `agent`, `audit`, `on_files_changed`, `on_layout` and `split` (the page makes room when the window is attached to an edge). All of them are in [`doc/api.md`](doc/api.md).
 
 ---
 
@@ -229,6 +283,8 @@ make approval      # a listed command, a file rule, SQL, a standing permission
 make structured    # a result handed to the page as data
 make cwd-upload    # files attached in chat, and an uploader on the page
 make headless      # asyncio query() and a Conversation answered in code
+make managed       # the managed agent: profile and role, then the window (experimental)
+make skills-hub    # skills on a stage, a chat with one chosen skill (experimental)
 make backlog       # Product Backlog Desk: a multipage application
 make bi-semantic   # Tableau / Power BI to semantic view
 make app-builder   # App Builder: type library, brief, Preview
@@ -236,30 +292,33 @@ make app-builder   # App Builder: type library, brief, Preview
 
 Each Streamlit demo has an **Ask CoCo** control (Off / On) in the sidebar. Off keeps that page's chat, panel, or Copilot rail. On leaves Ask CoCo minimized until **Minimize** on that CoCo, which hides it and opens the window. **Restore** in the window closes it and brings the rail or chat back.
 
-To run any of them with no login: `STREAMLIT_COCO_AGENT=mock make simple-chat` (PowerShell: set `$env:STREAMLIT_COCO_AGENT` first). `make chat` still launches the simple demo.
+To run them with no login: `STREAMLIT_COCO_AGENT=mock make simple-chat` (PowerShell: set `$env:STREAMLIT_COCO_AGENT` first); `make skills-hub` shows its sample skills on a scripted chat. `make chat` still launches the simple demo.
 
 Exploratory prompts: [`examples/testdata/prompts.json`](examples/testdata/prompts.json).
-Backlog Desk: [`examples/backlog_desk/README.md`](examples/backlog_desk/README.md) · BI to Semantic: [`examples/bi_to_semantic/README.md`](examples/bi_to_semantic/README.md) · App Builder: [`examples/app_builder/README.md`](examples/app_builder/README.md).
+Backlog Desk: [`examples/backlog_desk/README.md`](examples/backlog_desk/README.md) · BI to Semantic: [`examples/bi_to_semantic/README.md`](examples/bi_to_semantic/README.md) · App Builder: [`examples/app_builder/README.md`](examples/app_builder/README.md) · Skills shop: [`examples/skills_hub/README.md`](examples/skills_hub/README.md) · Skills shop as a Native App: [`examples/skills_hub_native/DEPLOY.md`](examples/skills_hub_native/DEPLOY.md).
 
 ---
 
 ## Architecture
 
-The agent is on the server. The browser sees one Streamlit component.
+The agent is not in the browser. The browser sees one Streamlit component.
 
 ```text
 Browser  ──►  Ask CoCo window (one component, in a fragment)
                   │  one action at a time; the page does not rerun
                   ▼
              Conversation   (thread, steps, requests, queue: plain data)
-                  │  every tool call reaches the Gate
+                  │  every call the agent asks about reaches the Gate
                   ▼
-             Gate + Policy  (free, asks, or refused; waits for Allow / Decline)
+             Gate + Policy  (free, asks, or refused; waits for Allow / Decline; writes the audit log)
                   ▼
-             Cortex adapter ──►  Cortex Code Agent SDK ──►  Cortex Code ──►  Snowflake
+             an agent  (backend.py: one surface, three agents)
+                  ├── Cortex adapter ──►  Cortex Agent SDK (cortexcode) ──►  Cortex Code program ──►  Snowflake
+                  ├── Managed agent  ──►  Cortex Agent SDK ──►  Snowflake's coding agent (sandbox)
+                  └── Scripted agent (tests, demos, no login)
 ```
 
-The scripted agent (`streamlit_coco.testing`) goes through the same Conversation, Policy and Gate. Only the model and the programs are replaced.
+All three go through the same Conversation, Policy and Gate. Only the model and the programs are replaced.
 
 ```text
 streamlit_coco/
@@ -267,10 +326,13 @@ streamlit_coco/
 ├── conversation.py  # the contract between the window and the agent (read its docstring)
 ├── policy.py        # Policy, FolderPolicy, Command, git_readonly, request, inside
 ├── gate.py          # the decision that waits for Allow / Decline
+├── audit.py         # AuditLog
+├── backend.py       # AgentBackend: what an agent is
+├── cortex.py        # the Cortex Code adapter
+├── managed.py       # the managed agent: ManagedOptions, managed_agent, options_from_connection
 ├── features.py      # Features, Attachments
 ├── labels.py        # every sentence of the window, by key
-├── cortex.py        # the Cortex Code adapter
-├── testing/         # scripted agent, fixtures, harness
+├── testing/         # scripted agent, scripted client of the managed agent, fixtures, harness
 ├── static/          # the window's script, styles and font
 ├── session.py       # CocoSession (headless)
 ├── query.py         # query() (headless)
@@ -298,6 +360,8 @@ async def run():
 asyncio.run(run())
 ```
 
+`query()` and `CocoSession` use the Cortex Code program.
+
 ---
 
 ## Development
@@ -306,18 +370,18 @@ asyncio.run(run())
 make install       # uv sync --extra dev
 make check         # ruff and the unit tests (not the browser tests)
 make e2e-install   # Playwright and Chromium, once
-make e2e           # browser tests of the window, on the scripted agent
+make e2e           # browser tests of the window, on the scripted agent and a scripted managed client
 make test-all      # check, e2e and the dependency audit
 make format        # ruff format and fix
 make build         # sdist and wheel
 make help          # every target
 ```
 
-`make e2e` uses the installed Edge when Playwright's Chromium is not installed. No test calls a live agent. Process: [`doc/testing.md`](doc/testing.md). Live checks before a release: [`doc/features/ask-coco/test-checklist.md`](doc/features/ask-coco/test-checklist.md).
+`make e2e` uses the installed Edge when Playwright's Chromium is not installed. No automated test calls a live agent. Process: [`doc/testing.md`](doc/testing.md). Live checks before a release (Cortex Code and the managed agent): [`doc/features/ask-coco/test-checklist.md`](doc/features/ask-coco/test-checklist.md).
 
 Releases: develop here, sync and tag on [`lletourmy/streamlit-coco`](https://github.com/lletourmy/streamlit-coco) for PyPI ([guide](doc/deployment/publish.md)).
 
-**Docs:** [API](doc/api.md) · [Ask CoCo feature file](doc/features/ask-coco/ask-coco.md) · [PRD](doc/prd.md) · [Roadmap](doc/roadmap.md) · [Deployment](doc/deployment/) · [Changelog](CHANGELOG.md) · [AGENTS.md](AGENTS.md)
+**Docs:** [API](doc/api.md) · [Ask CoCo feature file](doc/features/ask-coco/ask-coco.md) · [PRD](doc/prd.md) · [Roadmap](doc/roadmap.md) · [Threat model](doc/security/threat-model.md) · [Deployment](doc/deployment/) · [Changelog](CHANGELOG.md) · [AGENTS.md](AGENTS.md)
 
 ---