From 20a12acb903e6e09116b3bb4f537970c9ce874d3 Mon Sep 17 00:00:00 2001 From: Bolin Chen Date: Thu, 22 Oct 2026 04:29:55 +0000 Subject: [PATCH] refactor: split change_card_catalog.py into kinds and plans owners change_card_catalog.py (2,742 lines) was over the 2,000-line file cap. It keeps its path as the one import path and patch surface: a _facade_mirror facade that keeps the evidence, undo, result and manual-change code, over two sibling owners moved verbatim: - change_card_catalog_kinds.py: kind ids, risk and limit constants, the KINDS table, list_kinds and parameter validation - change_card_catalog_plans.py: plan steps and fills, the stores and dashboard setting tables, the display helpers, the plan pieces Apply and Undo share, and build_preview A test patches LIST_SETTING_WORDING through the facade and the moved build_preview reads it as a global, so the mirror carries a write of any facade name to every module holding it. CardCatalogError keeps the facade __module__. The change-card redaction sink row follows the redactor call into the plans owner, the line-cap baseline row goes, the facade gains its campaign inventory and patch-reach test, one test reads dir() so its namespace check still covers the moved names, and the docs cite the new homes. Part of #20192 --- .github/file-line-cap-baseline.txt | 1 - docs/architecture/mcp.md | 10 + docs/feature-map/README.md | 2 +- docs/request-for-change/rfc-crewmate-share.md | 4 +- src/kiro_crew/change_card_catalog.py | 2444 ++--------------- src/kiro_crew/change_card_catalog_kinds.py | 1137 ++++++++ src/kiro_crew/change_card_catalog_plans.py | 1198 ++++++++ src/kiro_crew/security_posture.py | 2 +- .../kiro_crew.change_card_catalog.json | 125 + test/test_change_card_catalog_facade.py | 281 ++ test/test_first_crewmate_ordinary.py | 2 +- 11 files changed, 2945 insertions(+), 2261 deletions(-) create mode 100644 src/kiro_crew/change_card_catalog_kinds.py create mode 100644 src/kiro_crew/change_card_catalog_plans.py create mode 100644 test/campaign_facade_inventories/kiro_crew.change_card_catalog.json create mode 100644 test/test_change_card_catalog_facade.py diff --git a/.github/file-line-cap-baseline.txt b/.github/file-line-cap-baseline.txt index 41427d2ab899..2ddfd739f431 100644 --- a/.github/file-line-cap-baseline.txt +++ b/.github/file-line-cap-baseline.txt @@ -17,7 +17,6 @@ 6697 src/kiro_crew/agent.py 2579 src/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-prepare-pr/scripts/pr_status.py 2232 src/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-prepare-pr/scripts/push_guard.py -2058 src/kiro_crew/change_card_catalog.py 3161 src/kiro_crew/cron_script.py 18473 src/kiro_crew/dashboard/chat_runner.py 2284 src/kiro_crew/sandbox_launcher_program.py diff --git a/docs/architecture/mcp.md b/docs/architecture/mcp.md index 02f908e106a4..99d8af74f475 100644 --- a/docs/architecture/mcp.md +++ b/docs/architecture/mcp.md @@ -2229,6 +2229,16 @@ names only (`history.md`, "Card rows"). Every owner mutation through the hooked routes, card or manual, appends one names-only line to Global memory history. +`kiro_crew/change_card_catalog.py` keeps the evidence, undo and result code +(`extract_evidence`, `build_undo`, `result_summary`) and the manual-change memory +lines (`describe_manual_change`, `HOOKED_ROUTES`, `MEMORY_ROUTES`), and is a mirror +facade (`kiro_crew._facade_mirror`) over two sibling owners, so every other name +still reads and patches as `change_card_catalog.`. New work goes to the owner +of its responsibility: `change_card_catalog_kinds.py` (the kind ids, the `KINDS` +table, the risk and limit constants and the parameter validation) and +`change_card_catalog_plans.py` (the plan steps and fills, the stores and dashboard +setting tables, the display helpers and `build_preview`). + `kirocrew-panel` is opt-in and reaches a crew member's DM session the way `kirocrew-dashboard` does: as a session-level `mcpServers` entry carrying that session's identity (`members.member_panel_session_server`), plus diff --git a/docs/feature-map/README.md b/docs/feature-map/README.md index 8975a8ef983c..065e098a96a3 100644 --- a/docs/feature-map/README.md +++ b/docs/feature-map/README.md @@ -450,7 +450,7 @@ old `?tab=` links redirect there. | Crash report notice | Desktop-only banner on the launch after a crash: a count of new own-app crash artifacts, **Show diagnostics** (reveals the crash ledger in the OS file manager), **Report issue** (opens the shared Report a Problem dialog with the crash count in its note) and dismiss | Appears automatically on the next launch after a desktop crash — no navigation | `components/CrashReportNotice.tsx` (mounted app-wide in `App.tsx`), `components/ReportProblemModal.tsx` | `website/electron/crash-collector.js`, `website/electron/ipc-registrar.js`, `website/electron/preload.js` (`crashReportsAPI`); `diagnostics.py` for the report | IPC for the banner: `crash-reports:get`, `crash-reports:reveal`; HTTP for the report: `POST /api/diagnostics/collect` | | Startup feature video | One short clip introducing a new feature, shown once on the launch after it ships and retired permanently by a `seen` or `dismissed` verdict; yields the whole launch to release notes, an update popup or first-run onboarding, and is skipped in incognito/temporary sessions. A clip is always played from disk -- the release folder for a downloaded one, the shipped assets for a built-in one -- and never streamed from the CDN: the browser only plays bytes the gateway downloaded and sha256-checked first, so an uncached hosted clip waits for the next launch. Every offer's files were proved on disk by the request that offered it, so the dialog opens on the `/next` answer alone | Appears by itself at startup, with no navigation, on the first launch where nothing else claimed the screen and the catalog still has an entry this install has not used | `components/StartupVideoModal.tsx`, `components/startupVideoGate.ts` (sequencing policy), mounted app-wide through `shell/boot/startupVideo.tsx` | `feature_videos.py`, `feature_videos_manifest.py` (signed hosted catalog), `feature_videos_cache.py` (local clip cache + serving) | `GET /api/feature-videos/next`, `POST /api/feature-videos/feedback`, `GET /feature-videos//` | | UI guides | An agent offers the owner a pointer through a REGISTERED dashboard action (`settings.show`, `crewmate.create`, `mcp.open_add`, `ui.show` — point at one indexed UI location by its id and walk its stored plan, including the reveal and list-`pick` steps that open a panel or wait for the owner to choose a session/artifact/app/job/crewmate — and `ui.find` — point at a control by its on-screen name on one page); the tab highlights the target and the owner makes the change with the page's own controls. A `crewmate.create` step completes only from the success response of the owner's own `POST /api/agents`, never from a client claim. Served by the `kirocrew-guide` MCP server, a platform capability every mate and dashboard session mounts | No page of its own: the offer (title, Dismiss, Start) is a row of the offering slot's conversation, at the point the agent offered it (a `card` transcript row the gateway writes), waiting there when another slot is viewed and collapsing in place to a result line once the guide ends (a completed show-me guide's line offers Show again, which replays it from the first step; a guide that saved a change does not); the walk-through is a floating pill and arrow over the page the action names | `guide/GuideOfferCard.tsx` (drawn by `cards/ConversationCard.tsx` from `pages/chat/transcriptRenderers.tsx`), `guide/GuideLayer.tsx`, `guide/GuideContext.tsx` (mounted in `App.tsx`), `guide/guideActions.ts`, `guide/useGuideStepTracker.ts`, `guide/liveRegistry.ts`, `guide/GuideRevealScope.tsx`, `guide/liveObservation.ts`, `api/guide.ts`, `hooks/useSettingHighlight.ts`, `hooks/useWebSocket.ts` (`guide_update` frame) | `handlers/guide.py`, `dashboard/guide_runs.py`, `dashboard/guide_observe.py`, `dashboard/chat_cards.py` (the conversation row and the `guide/*` crew-log entries), `guide_catalog.py`, `mcp_guide.py`, `handlers/agents.py` (`run_guided_crewmate_create` around `POST /api/agents`) | agent half (MCP-only, strict-internal): `GET /api/guide/agent/actions`, `POST /api/guide/agent/start`, `GET /api/guide/agent/status`, `POST /api/guide/agent/cancel`, `POST /api/guide/agent/observe`, `GET /api/guide/agent/language`; browser half (owner-only): `GET /api/guide/pending`, `POST /api/guide/claim`, `POST /api/guide/progress`, `POST /api/guide/heartbeat`, `POST /api/guide/cancel`, `POST /api/guide/dismiss`, `POST /api/guide/replay`, `POST /api/guide/refuse`, `POST /api/guide/replan`, `POST /api/guide/observe`; the `guide_update` and `guide_observe` WS frames | -| Change cards | An agent proposes ONE registered change (setting, schedule, mate, capabilities, template, MCP server, connection, secret, app trust, denied-command rule) and the chat shows a fixed card: what changes (gateway-written), the proposer's reason under its own name (the mate's display name, or Kiro Crew outside a mate chat), the computed risk (a widening needs a checkbox), editable fields that re-preview. The owner's click sends the exact plan to the existing settings route; the card collapses to a result line with Details / Undo. Secrets are typed into the card and sent only to the vault route. Nothing automated can confirm a card; owner changes through those routes, card or manual, become names-only Global memory events | The proposing chat, as a row of the conversation at the point the agent proposed it (a `card` transcript row the gateway writes); it updates in place and, once finished, stays there as its one-line result, after a reload too | `cards/` (`ConversationCard.tsx`, `ChangeCard.tsx`, `CardResultLine.tsx`, `cardRegistry.ts`), `api/cards.ts`, `pages/chat/transcriptRenderers.tsx`, `hooks/useWebSocket.ts` (`card_update` frame) | `handlers/change_cards.py` (routes + the card hook on the existing settings routes), `dashboard/change_cards.py` (store), `dashboard/change_cards_readers.py` (state readers), `dashboard/change_cards_settings.py` (setting lookup and diagnosis), `dashboard/chat_cards.py` (the conversation row and the `card/*` crew-log entries), `change_card_catalog.py`, `mcp_guide.py` (`list_change_kinds`, `find_setting`, `get_member_capabilities`, `diagnose_settings`, `propose_change`, `get_change_status`), `context_blocks.py` (`[CHANGE CARD RESULTS]`) | agent half (MCP-only, strict-internal): `GET /api/cards/agent/kinds`, `GET /api/cards/agent/settings`, `GET /api/cards/agent/capabilities`, `GET /api/cards/agent/diagnose`, `POST /api/cards/agent/propose`, `GET /api/cards/agent/status`; browser half (owner-only): `GET /api/cards/pending`, `POST /api/cards/{id}/preview`, `POST /api/cards/{id}/cancel`, `POST /api/cards/{id}/dismiss`; apply/undo ride the existing routes with `X-Card-Id`/`-Revision`/`-Op`/`-Step`; the `card_update` WS frame | +| Change cards | An agent proposes ONE registered change (setting, schedule, mate, capabilities, template, MCP server, connection, secret, app trust, denied-command rule) and the chat shows a fixed card: what changes (gateway-written), the proposer's reason under its own name (the mate's display name, or Kiro Crew outside a mate chat), the computed risk (a widening needs a checkbox), editable fields that re-preview. The owner's click sends the exact plan to the existing settings route; the card collapses to a result line with Details / Undo. Secrets are typed into the card and sent only to the vault route. Nothing automated can confirm a card; owner changes through those routes, card or manual, become names-only Global memory events | The proposing chat, as a row of the conversation at the point the agent proposed it (a `card` transcript row the gateway writes); it updates in place and, once finished, stays there as its one-line result, after a reload too | `cards/` (`ConversationCard.tsx`, `ChangeCard.tsx`, `CardResultLine.tsx`, `cardRegistry.ts`), `api/cards.ts`, `pages/chat/transcriptRenderers.tsx`, `hooks/useWebSocket.ts` (`card_update` frame) | `handlers/change_cards.py` (routes + the card hook on the existing settings routes), `dashboard/change_cards.py` (store), `dashboard/change_cards_readers.py` (state readers), `dashboard/change_cards_settings.py` (setting lookup and diagnosis), `dashboard/chat_cards.py` (the conversation row and the `card/*` crew-log entries), `change_card_catalog.py` (evidence, undo, results), `change_card_catalog_kinds.py` (kinds and parameter validation), `change_card_catalog_plans.py` (plans and previews), `mcp_guide.py` (`list_change_kinds`, `find_setting`, `get_member_capabilities`, `diagnose_settings`, `propose_change`, `get_change_status`), `context_blocks.py` (`[CHANGE CARD RESULTS]`) | agent half (MCP-only, strict-internal): `GET /api/cards/agent/kinds`, `GET /api/cards/agent/settings`, `GET /api/cards/agent/capabilities`, `GET /api/cards/agent/diagnose`, `POST /api/cards/agent/propose`, `GET /api/cards/agent/status`; browser half (owner-only): `GET /api/cards/pending`, `POST /api/cards/{id}/preview`, `POST /api/cards/{id}/cancel`, `POST /api/cards/{id}/dismiss`; apply/undo ride the existing routes with `X-Card-Id`/`-Revision`/`-Op`/`-Step`; the `card_update` WS frame | | Feature-video cache readout | How much of the current release's clips is on disk, which one is downloading, and one control to fetch them all now. Read-only apart from that control; the control is absent when policy forbids downloads, and the whole row is absent on a gateway whose `status` predates the cache fields | `/settings/chat/discovery`, beside Feature Tips | `pages/settings/ChatPanel.tsx`, `pages/settings/useChatPanelDashboard.ts` | `feature_videos.py`, `feature_videos_cache.py` | `GET /api/feature-videos/status`, `POST /api/feature-videos/fetch-all` | | OpenAI-compatible API | Chat-completions shim for external clients | External clients only | — | `openai_compat.py` | `POST /v1/chat/completions` | diff --git a/docs/request-for-change/rfc-crewmate-share.md b/docs/request-for-change/rfc-crewmate-share.md index b2892dd96004..baecc35e0d34 100644 --- a/docs/request-for-change/rfc-crewmate-share.md +++ b/docs/request-for-change/rfc-crewmate-share.md @@ -34,7 +34,7 @@ A bundle carries the crewmate's shape: name, description, avatar, rules, skill r - **There is no one-crewmate export.** `GET /api/portability/export` (`create_export_zip` in `portability_stream.py`, route in `dashboard/routes/taskrunner.py`) writes the whole install. Its Merge import installs `config.json` only when absent (`_merge_settings` in `portability.py`), so it cannot add one crewmate to a running install. - **Template bundling exists inside that zip and is the closest reusable piece.** `placeholder_mcp_values` (`portability_templates.py`) replaces every MCP `env`, `headers` and `oauth.clientSecret` value with a placeholder and keeps the keys. `_install_agent_templates` (`portability_templates.py`) writes each template with `O_EXCL` and runs `sanitize_agent_config_governance` (`portability_templates.py`) so `allowedTools` and `autoApprove` are cut to this host's ceiling. - **Apps cannot create a crewmate.** `POST /api/agents` runs `_require_owner(request, "agent.create")` (`_api_kirocrew_agents_create` in `dashboard/agent_admin/crew_records.py`). The template read `GET /api/agents/detail/{name}` is also owner-only (`api_agent_detail` in `dashboard/agent_admin/agent_detail.py`). An App Kit manifest can register namespaced agent templates, skills and crons (`docs/app-kit/manifest-reference.md`, `_register_agents` in `apps/bridges_agents.py`), never a crew record. -- **An owner-press path for creating a crewmate already exists for agents.** The change-card kind `crewmate.create` (`KIND_CREWMATE_CREATE` in `change_card_catalog.py`) builds a plan against the owner routes `POST /api/agents` and `PUT /api/members/{slug}/goals/long-term` (`build_preview` in `change_card_catalog.py`). `change_card_middleware` refuses an app token, an internal-secret caller or an agent on those routes (`dashboard/handlers/change_cards.py` module docstring; route set `HOOKED_ROUTES`, `change_card_catalog.py`). The guide action `crewmate.create` (`guide_catalog.py`) follows the same rule: "The crewmate is created only by the human's own click on the existing owner-only `POST /api/agents`." +- **An owner-press path for creating a crewmate already exists for agents.** The change-card kind `crewmate.create` (`KIND_CREWMATE_CREATE` in `change_card_catalog_kinds.py`) builds a plan against the owner routes `POST /api/agents` and `PUT /api/members/{slug}/goals/long-term` (`build_preview` in `change_card_catalog_plans.py`). `change_card_middleware` refuses an app token, an internal-secret caller or an agent on those routes (`dashboard/handlers/change_cards.py` module docstring; route set `HOOKED_ROUTES`, `change_card_catalog.py`). The guide action `crewmate.create` (`guide_catalog.py`) follows the same rule: "The crewmate is created only by the human's own click on the existing owner-only `POST /api/agents`." - **No MCP tool or App SDK call exports or imports a crewmate.** ### Problems @@ -175,7 +175,7 @@ The card shows: Risk is computed from the diff, as for every card. An MCP server with a local `command` is `code_exec`, because it runs on the receiver's machine. -The press applies an ordered plan through existing owner routes, the same way `crewmate.create` does (`build_preview` in `change_card_catalog.py`): +The press applies an ordered plan through existing owner routes, the same way `crewmate.create` does (`build_preview` in `change_card_catalog_plans.py`): 1. `POST /api/agents` creates the record with `approval_mode: "normal"` in the same write. The create path mints a fresh `member_id` (`memory_stores._allocate_member_id`), an empty memory store and its own workspace. The mode rides on the create because an unset mode resolves to `trust` (`MEMBER_APPROVAL_MODE_UNSET_EFFECTIVE` in `config/sections_agent_fields.py`), and `_api_kirocrew_agents_create` takes no `approval_mode`. Phase 1 adds that one optional create field, validated against `MEMBER_APPROVAL_MODES`. No imported crewmate exists for any moment in `trust`. 2. The mate-owned file `~/.kiro/mates/agents/.json` receives the bundle's `mcpServers` and `skills` through the in-place edit path of the mate-owned config RFC (§5.4 there). `sanitize_agent_config_governance` runs on the way to disk. diff --git a/src/kiro_crew/change_card_catalog.py b/src/kiro_crew/change_card_catalog.py index 8c49ade1710e..43fcdfa01541 100644 --- a/src/kiro_crew/change_card_catalog.py +++ b/src/kiro_crew/change_card_catalog.py @@ -35,2266 +35,63 @@ from __future__ import annotations -import copy -import json -import re -import shlex +import importlib as _importlib +import sys as _sys import urllib.parse -from dataclasses import dataclass -from datetime import datetime -from typing import Any +from typing import TYPE_CHECKING, Any -from kiro_crew import guide_catalog +from kiro_crew import _facade_mirror, guide_catalog from kiro_crew import member_goals as _goals -from kiro_crew.config.sections import ( - DEFAULT_MODEL, - MEMBER_APPROVAL_MODE_UNSET_EFFECTIVE, - MEMBER_APPROVAL_MODES, - effective_pin_scope, - normalize_agent_model, +from kiro_crew.change_card_catalog_kinds import ( + CHECK_IN_FIELDS, + CREWMATE_CREATE_GOAL_STEP, + CREWMATE_CREATE_SCHEDULE_STEP, + CREWMATE_CREATING_KINDS, + KIND_CONNECTION_CONNECT, + KIND_CREWMATE_CAPABILITIES, + KIND_CREWMATE_CHECK_INS, + KIND_CREWMATE_CREATE, + KIND_CREWMATE_GOAL, + KIND_CREWMATE_KEY_RESULTS, + KIND_CREWMATE_UPDATE, + KIND_DENIED_COMMAND, + KIND_FOLDER_STEERING, + KIND_MCP_ADD_CUSTOM, + KIND_MCP_INSTALL, + KIND_MCP_TOGGLE, + KIND_SCHEDULE_CREATE, + KIND_SECRET_SAVE, + KIND_SETTING_CHANGE, + KIND_TEMPLATE_UPDATE, + LIST_OP_ADD, + LIST_OP_REMOVE, + OP_APPLY, ) - -KIND_SETTING_CHANGE = "setting.change" -KIND_SCHEDULE_CREATE = "schedule.create" -KIND_SCHEDULE_UPDATE = "schedule.update" -KIND_CREWMATE_CREATE = "crewmate.create" -KIND_CREWMATE_UPDATE = "crewmate.update" -KIND_CREWMATE_CAPABILITIES = "crewmate.capabilities" -KIND_CREWMATE_GOAL = "crewmate.goal" -KIND_CREWMATE_KEY_RESULTS = "crewmate.key_results" -KIND_CREWMATE_CHECK_INS = "crewmate.check_ins" -KIND_TEMPLATE_UPDATE = "template.update" -KIND_MCP_INSTALL = "mcp.install" -KIND_MCP_ADD_CUSTOM = "mcp.add_custom" -KIND_MCP_TOGGLE = "mcp.toggle" -KIND_CONNECTION_CONNECT = "connection.connect" -KIND_SECRET_SAVE = "secret.save" -KIND_TRUST_APP = "trust.app" -KIND_DENIED_COMMAND = "denied_command" -KIND_FOLDER_STEERING = "folder.steering" -#: An app's proposal of one crewmate from a ``.crewmate`` bundle -#: (``docs/request-for-change/rfc-crewmate-share.md``). Only an app that -#: declares ``permissions.proposeCrewmate`` raises it, through ``ctx.crewmate``; -#: an agent cannot, so :func:`list_kinds` leaves it out. -KIND_CREWMATE_IMPORT = "crewmate.import" -#: The kinds whose apply step 0 creates a crewmate, so they share its evidence, -#: its identity-checked Undo (delete that crewmate) and its state reads. -CREWMATE_CREATING_KINDS = (KIND_CREWMATE_CREATE, KIND_CREWMATE_IMPORT) -APP_ONLY_KINDS = frozenset({KIND_CREWMATE_IMPORT}) -#: The ``.crewmate`` ``formatVersion`` values this version reads. Any added -#: field bumps the version, so a newer file is refused rather than guessed at. -CREWMATE_FORMAT_VERSIONS = (1,) -#: The parts a ``crewmate.import`` card names as left out, as codes the -#: dashboard words: the bundle carried them and this version does not write them. -NOT_IMPORTED_CODES = ("crons", "keyResults", "avatar", "model", "dashboardTemplate") - -#: The steps of a ``crewmate.create`` apply: the crewmate (0), its first goal -#: in its goal record (1), and its optional work schedule (2). -CREWMATE_CREATE_GOAL_STEP = 1 -CREWMATE_CREATE_SCHEDULE_STEP = 2 - -LIST_OP_ADD = "add" -LIST_OP_REMOVE = "remove" -_LIST_OPS = (LIST_OP_ADD, LIST_OP_REMOVE) -_LIST_ITEM_MAX = 200 - -RISK_NORMAL = "normal" -RISK_TIGHTEN = "tighten" -RISK_WIDEN = "widen" -RISK_CODE_EXEC = "code_exec" - -OP_APPLY = "apply" -OP_UNDO = "undo" - -#: The crewmate template a proposed crewmate is built from: the one the -#: Crewmates page's New crewmate card builds from (``NewCrewmateDialog.tsx`` -#: ``DEFAULT_CREWMATE_TEMPLATE``). -DEFAULT_CREWMATE_TEMPLATE = "kirocrew" - -REASON_MAX_CHARS = 500 -_NAME_MAX = 128 -_TEXT_MAX = 4000 -_CREWMATE_NAME_MAX = 24 -_CREWMATE_GOAL_MAX = 200 -_CREWMATE_DESCRIPTION_MAX = 1000 -#: A crewmate's goals and key results: the record's own bounds, so a -#: validated card never fails on apply and the record accepts nothing a card -#: could not propose. -_LONG_TERM_GOAL_MAX = _goals.LONG_TERM_MAX_CHARS -_KR_TEXT_MAX = _goals.KR_TEXT_MAX_CHARS -_KR_VALUE_MAX = _goals.KR_VALUE_MAX_CHARS -_PATTERN_MAX = 500 -_MAX_CUSTOM_SERVERS = 8 -_MAX_LIST_ITEMS = 300 -_MAX_CAPABILITY_OPS = 100 -_PARAMS_MAX_BYTES = 32 * 1024 -#: The folder route's per-entry bound (``chat_folders.MAX_FOLDER_STEERING_DIR_LEN``), -#: so a canonical path the route accepts is one a stored card keeps. -FOLDER_STEERING_DIR_MAX = 4096 -#: The ``template.update`` fields that hold a list, replaced whole, and so the ones -#: its ``clear`` may name. -_TEMPLATE_LIST_FIELDS = ("tools", "allowedTools", "skills") - -#: The grammars the real routes enforce, so a card is never stricter than the -#: Settings page: a template name (``validation.TEMPLATE_NAME_RE``) and an app -#: grant name (``apps.execution.APP_NAME_RE``). Crewmate names follow -#: ``members.validate_member_name`` (free text, any script); stored-credential -#: names follow ``POST /api/secrets`` (any non-empty text). -_TEMPLATE_NAME_RE = re.compile(r"^(?:[A-Za-z0-9][A-Za-z0-9_.-]{0,61}[A-Za-z0-9]|[A-Za-z0-9])$") -_APP_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$") -_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$") -_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$") -_MCP_NAME_RE = re.compile(r"^[@a-zA-Z0-9][@a-zA-Z0-9/_.:-]*$") -_CONFIG_PATH_RE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$") -_SETTING_ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]*$") -_CRON_EXPR_RE = re.compile(r"^[0-9*/,\- A-Za-z?#LW]{1,100}$") - -#: Settings whose change can widen what the agent may do without asking. Each -#: entry orders the values from tightest to widest, so a move toward the end is -#: ``widen`` and a move toward the start is ``tighten``. -_SETTING_ORDER: dict[str, tuple[Any, ...]] = { - "agent.approval_mode": ("interactive", "auto"), - "agent.sandbox": ("strict", "auto", "off"), - "agent.yolo_duration": ("30m", "1h", "6h", "12h", "24h", "until_shutdown"), - "agent.sandbox_allow_no_isolation": (False, True), - "dashboard.tailscale.enabled": (False, True), - "dashboard.tailscale.trust_identity": (False, True), - "dashboard.tailscale.bind_refresh_chains": (True, False), - # ``login`` lets one session move between every device of the same tailnet - # login; ``node`` pins it to one device. - "dashboard.tailscale.pin_scope": ("node", "login"), - "instances.enabled": (False, True), - # On, an agent may add documents to the knowledge library - # (``knowledge_add_document``); off, that tool refuses. - "knowledge.auto_add_documents": (False, True), - "skills.approval_required": (True, False), - "telemetry.beacon_enabled": (False, True), -} - -#: Card-editable config paths (``_EDITABLE_CONFIG``) that no value can widen -#: what an agent may do: models, efforts, timeouts, budgets, display and -#: background-work switches (``skills.extra_paths`` is the one entry listed for -#: completeness only; see its note). Every editable path is in exactly one of this set, -#: ``_SETTING_ORDER`` or ``_CODE_EXEC_SETTINGS``, so a new path is classified -#: before a card can show it. -_CANNOT_WIDEN_SETTINGS: frozenset[str] = frozenset( - { - "agent.chat_turn_timeout_secs", - "agent.completion_keep", - "agent.completion_keep_chars", - "agent.fallback_model", - "agent.model", - "agent.provider", - "agent.reasoning_effort", - "agent.refusal_fallback_model", - "agent.role_efforts.background", - "agent.role_efforts.subagent", - "agent.role_models.background", - "agent.role_models.subagent", - "agent.soft_stop_budget_secs", - "agent.tool_search", - "auto_update", - "computer_use.max_tree_nodes", - "computer_use.screenshot_max_px", - "dashboard.crewmate_threads", - "dashboard.dynamic_dashboard_cards", - "dashboard.folder_sort", - "dashboard.mcp_probe_timeout_secs", - "dashboard.prevent_sleep", - "dashboard.recent_tint_count", - "dashboard.session_sort", - # Stored only: the edition's login handler re-checks every flag against - # its own allowlist before it runs anything. - "dashboard.sso_login_flags", - "dashboard.terminal.completion.enabled", - # An allowlist id, not a command: it names which allowlisted terminal - # app the Files tab's "Open in " row starts, and only the owner's - # own click in the desktop app, approved by the gateway's launch grant, - # ever starts it. No value lets an agent launch anything. - "dashboard.terminal.external_app", - "dashboard.terminal.reuse_current", - "dashboard.title_refresh_every_turns", - "dashboard.update_nudge", - "dashboard.user_role", - "dashboard.user_role_other", - "dashboard.user_technical_level", - "decisions.bucket", - "decisions.model_route.complex", - "decisions.model_route.medium", - "decisions.model_route.simple", - "decisions.nudge_wake.llm_model", - "decisions.nudge_wake.provider", - "knowledge.auto_ingest_artifacts", - "knowledge.dedup_every_n_sweeps", - "knowledge.embed_rate_limit", - "knowledge.extraction_effort", - "knowledge.extraction_model", - "knowledge.extraction_pool_size", - "knowledge.folder_ingest_chunk_budget", - "knowledge.import_chunk_budget", - "knowledge.sweep_chunk_budget", - "monitoring.prefer_structured_arming", - "session.autocompact_pct", - "session.compact_wait_secs", - "session.pool_size", - "session.pool_ttl_secs", - "session.timeout_secs", - "session_summary.enabled", - # Listed for exactly-one completeness, not because a card can reach it: a card - # carries no list value (``setting.change.value`` is scalar and ``op``/``item`` - # is confined to the dashboard store), so no card proposes this path. A list of - # skill directories can widen what an agent loads, so if cards ever carry list - # values this moves out of here to a widening class with a type-guarded list - # comparator. - "skills.extra_paths", - # Generated skills still wait for approval unless - # ``skills.approval_required`` (ordered above) is turned off. - "skills.auto_create_from_sessions", - # Local recording only: the write route refuses the enable on a host - # where it would start sending data out. - "telemetry.enabled", - } -) - -#: Settings whose VALUE is a command this machine then runs, so changing one is -#: ``code_exec`` the same as installing an MCP server: the diff is a widen/tighten -#: order only if its direction is meaningful, which a free-form command string -#: has none of. ``dashboard.terminal.shell`` is the shell the dashboard terminal -#: launches; an agent that sets it chooses what program runs on every new -#: terminal, so the card says it runs code regardless of the before/after values. -#: ``agent.acp_backend`` picks the harness program every new session runs, and -#: harnesses differ in how they are made to ask before a tool runs -#: (``agent_sdk.backends.ACP_BACKEND_ROUTING``), so no fixed order fits it either. -#: ``session.pool_agent`` names the agent spec warm-pool processes start with, and -#: a session that names no agent claims one (``session_pool._claim_from_pool``), -#: so it picks which tool grants that session runs under. ``agent.kas_bundle`` -#: swaps the program the KAS harness is spawned from (the installed kiro-cli or -#: Kiro Crew's own pinned engine bundle, ``acp.harness.kas.KasHarness.resolve_spawn``); a -#: different binary with its own update cadence is a different program, so a -#: bool flip here is code exec, not a widen or tighten. -_CODE_EXEC_SETTINGS: frozenset[str] = frozenset( - { - "agent.acp_backend", - "agent.kas_bundle", - "dashboard.terminal.shell", - "session.pool_agent", - } +from kiro_crew.change_card_catalog_plans import ( + DASHBOARD_KEYS, + DASHBOARD_LIST_OP_KEYS, + LEGACY_CREWMATE_CREATE_SCHEDULE_STEP, + UNDO_NO_IDENTITY_CHECK, + _capability_plan, + _check_ins_path, + _create_schedule_index, + _crewmate_put_body, + _folder_steering_step, + _goal_path, + _key_results_path, + _q, + _scrub_kr_records, + _scrub_kr_shape, + _short, + _toggle_step, + capability_inverse, + list_op_step, + offers_no_undo, + setting_write_step, + step, + string_items, ) - -_PLACEHOLDER = "{{%s}}" - - -class CardCatalogError(ValueError): - """A proposal naming an unknown kind or carrying bad parameters.""" - - def __init__(self, code: str, message: str) -> None: - super().__init__(message) - self.code = code - self.message = message - - -@dataclass(frozen=True) -class KindDef: - id: str - summary: str - params_schema: dict[str, Any] - editable: tuple[str, ...] - - -def _obj(props: dict[str, Any], required: list[str]) -> dict[str, Any]: - return { - "type": "object", - "properties": props, - "required": required, - "additionalProperties": False, - } - - -_STR = {"type": "string"} -_BOOL = {"type": "boolean"} -_CRON_FIELDS = { - "cron_expr": {"type": "string", "description": "5-field cron, e.g. '0 9 * * 1-5'"}, - "timezone": {"type": "string", "description": "IANA timezone, e.g. 'America/New_York'"}, -} - -#: A one-shot schedule's wall-clock time: an ISO-8601 local date-time with no -#: offset, read in the card's ``timezone`` (the configured zone when omitted). -_AT_FIELD = { - "type": "string", - "description": ( - "One-time run: ISO-8601 local date-time, e.g. '2026-10-04T09:00', read in " - "`timezone`. Use instead of cron_expr." - ), -} -_AT_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?$") - -KINDS: dict[str, KindDef] = { - k.id: k - for k in ( - KindDef( - KIND_SETTING_CHANGE, - "Change one setting. Pass `setting_id` from find_setting (preferred) " - "or a raw config `path`, and the new `value`. For a setting find_setting " - "reports as value_type 'string_list', pass `op` ('add' or 'remove') and " - "one `item` instead of `value`.", - _obj( - { - "setting_id": _STR, - "path": _STR, - "value": {}, - "op": {"type": "string", "enum": [LIST_OP_ADD, LIST_OP_REMOVE]}, - "item": _STR, - }, - [], - ), - ("value",), - ), - KindDef( - KIND_SCHEDULE_CREATE, - "Create a scheduled job that sends `message` to an agent. Give exactly " - "one of `cron_expr` (recurring) or `at` (runs ONCE, e.g. 'remind me " - "tomorrow at 9am'), plus the `timezone` either is read in.", - _obj( - {"name": _STR, "message": _STR, **_CRON_FIELDS, "at": _AT_FIELD}, - ["name", "message"], - ), - ("name", "message", "cron_expr", "at", "timezone"), - ), - KindDef( - KIND_SCHEDULE_UPDATE, - "Change an existing schedule's name, message, cron or timezone.", - _obj( - { - "id": _STR, - "fields": _obj({"name": _STR, "message": _STR, **_CRON_FIELDS}, []), - }, - ["id", "fields"], - ), - ("fields",), - ), - KindDef( - KIND_CREWMATE_CREATE, - "Create a crewmate that owns a goal, optionally on a daily/cron schedule.", - _obj( - { - "name": {"type": "string", "maxLength": _CREWMATE_NAME_MAX}, - "goal": {"type": "string", "maxLength": _CREWMATE_GOAL_MAX}, - "schedule": _obj(dict(_CRON_FIELDS), ["cron_expr"]), - }, - ["name", "goal"], - ), - ("name", "goal", "schedule"), - ), - KindDef( - KIND_CREWMATE_UPDATE, - "Change one crewmate's description, display name, model, effort or the " - "approval mode of its own chat (normal, trust_reads, trust).", - _obj( - { - "name": _STR, - "fields": _obj( - { - "description": _STR, - "display_name": _STR, - "model": _STR, - "reasoning_effort": _STR, - "approval_mode": _STR, - }, - [], - ), - }, - ["name", "fields"], - ), - ("fields",), - ), - KindDef( - KIND_CREWMATE_CAPABILITIES, - "Change one crewmate's tools / MCP servers / skills / autoApprove. `draft` is " - "{operations:[{section,id,action:set|remove|inherit,value?}], enroll?}.", - _obj( - { - "member": _STR, - "draft": _obj( - {"operations": {"type": "array"}, "enroll": _BOOL}, - ["operations"], - ), - }, - ["member", "draft"], - ), - ("draft",), - ), - KindDef( - KIND_CREWMATE_GOAL, - "Add one goal for a crewmate, or replace one of its goals: what it works " - "toward. Without `goal_id` the text is added as a new goal; with the id of " - "one of its goals (goal_read lists them) " - "it replaces that goal's text. Goals are stored in its goal record, never " - "in its rules.", - _obj( - { - "member": _STR, - "long_term": {"type": "string", "maxLength": _LONG_TERM_GOAL_MAX}, - "goal_id": {"type": "string", "maxLength": 9}, - }, - ["member", "long_term"], - ), - ("long_term",), - ), - KindDef( - KIND_CREWMATE_KEY_RESULTS, - "Set one crewmate's key results: readings that show how far it " - "is from its goals, replacing the current set. `items` is " - "[{text, target, goal_ids?}], target a number or a word such as 'yes', " - "goal_ids the ids of the goals that key result serves.", - _obj( - { - "member": _STR, - "items": { - "type": "array", - "items": _obj( - { - "text": {"type": "string", "maxLength": _KR_TEXT_MAX}, - "target": {"type": "string", "maxLength": _KR_VALUE_MAX}, - "goal_ids": { - "type": "array", - "items": _STR, - }, - }, - ["text", "target"], - ), - }, - }, - ["member", "items"], - ), - ("items",), - ), - KindDef( - KIND_CREWMATE_CHECK_INS, - "Turn one crewmate's check-ins on or off and set when they run: daily " - "(the Daily Goal Reminder), weekly (the Weekly report, on `weekday`, " - "0 = Sunday) and monthly (the Monthly review, on `month_day`, 1-28), " - "all at `time` (HH:MM, 24-hour), and heartbeat (a wake every `interval` " - f"minutes, {_goals.interval_minutes_text()}, read as " - f"{_goals.interval_choices()}, in which the crewmate moves its " - "work forward on its own; each run uses credits). Give only the fields " - "that change.", - _obj( - { - "member": _STR, - "daily": _BOOL, - "weekly": _BOOL, - "monthly": _BOOL, - "heartbeat": _BOOL, - "weekday": {"type": "integer", "minimum": 0, "maximum": 6}, - "month_day": {"type": "integer", "minimum": 1, "maximum": _goals.MAX_MONTH_DAY}, - "time": {"type": "string", "maxLength": 5}, - "interval": {"type": "integer", "enum": list(_goals.HEARTBEAT_INTERVALS)}, - }, - ["member"], - ), - ( - "daily", - "weekly", - "monthly", - "heartbeat", - "weekday", - "month_day", - "time", - "interval", - ), - ), - KindDef( - KIND_TEMPLATE_UPDATE, - "Change an agent template's tools, allowedTools, skills or model. Affects " - "every member built from it. A list field is replaced whole; to empty one, " - "name it in `clear` (e.g. clear: ['allowedTools']) rather than passing [], " - "which some clients drop before it reaches the server.", - _obj( - { - "template": _STR, - "fields": _obj( - { - "tools": {"type": "array", "items": _STR}, - "allowedTools": {"type": "array", "items": _STR}, - "skills": {"type": "array", "items": _STR}, - "model": _STR, - }, - [], - ), - "clear": { - "type": "array", - "items": {"type": "string", "enum": list(_TEMPLATE_LIST_FIELDS)}, - }, - }, - ["template"], - ), - ("fields",), - ), - KindDef( - KIND_MCP_INSTALL, - "Install an MCP server from a discovery provider (runs third-party code).", - _obj({"provider": _STR, "id": _STR}, ["provider", "id"]), - (), - ), - KindDef( - KIND_MCP_ADD_CUSTOM, - "Add custom MCP server(s): {servers:{name:{command,args?,env?}|{url}}, enable}.", - _obj({"servers": {"type": "object"}, "enable": _BOOL}, ["servers"]), - ("enable",), - ), - KindDef( - KIND_MCP_TOGGLE, - "Enable/disable an MCP server ({name, enabled}) or one tool ({server, tool, enabled}).", - _obj({"name": _STR, "server": _STR, "tool": _STR, "enabled": _BOOL}, ["enabled"]), - ("enabled",), - ), - KindDef( - KIND_CONNECTION_CONNECT, - "Connect an account (OAuth) from the Connections registry by slug.", - _obj({"slug": _STR}, ["slug"]), - (), - ), - KindDef( - KIND_SECRET_SAVE, - "Ask the user to store a secret under `name`. The user types the value into the " - "card; you never see or send it.", - _obj({"name": _STR}, ["name"]), - (), - ), - KindDef( - KIND_TRUST_APP, - "Allow a third-party app's code to run (widens permissions).", - _obj({"name": _STR, "repository": _STR}, ["name"]), - (), - ), - KindDef( - KIND_DENIED_COMMAND, - "Add a user denied-command rule ({action:'add', pattern, note?}) or toggle one " - "({action:'toggle', id, enabled}).", - _obj( - { - "action": {"type": "string", "enum": ["add", "toggle"]}, - "pattern": _STR, - "note": _STR, - "id": _STR, - "enabled": _BOOL, - }, - ["action"], - ), - ("note", "enabled"), - ), - KindDef( - KIND_FOLDER_STEERING, - "Replace a sidebar folder's additional steering directories (Folder settings " - "-> Additional steering). `folder` is a folder id from chat_folder_tree; " - "`steering_dirs` is the COMPLETE new list of absolute directory paths. To " - "empty it, pass `clear: true` with no steering_dirs ([] means the same, but " - "some clients drop it before it reaches the server).", - _obj( - { - "folder": _STR, - "steering_dirs": {"type": "array", "items": _STR}, - "clear": _BOOL, - }, - ["folder"], - ), - ("steering_dirs",), - ), - KindDef( - KIND_CREWMATE_IMPORT, - "Import one crewmate from a .crewmate bundle (apps only).", - _obj( - { - "name": {"type": "string", "maxLength": _CREWMATE_NAME_MAX}, - "description": _STR, - "goal": _STR, - "sender": _STR, - "format_version": {"type": "integer"}, - "not_imported": {"type": "array", "items": _STR}, - }, - ["name", "format_version"], - ), - ("name",), - ), - ) -} - - -def list_kinds() -> list[dict[str, Any]]: - """The catalog as the ``list_change_kinds`` tool returns it, app-only kinds left out.""" - return [ - { - "id": k.id, - "summary": k.summary, - "params_schema": copy.deepcopy(k.params_schema), - "editable": list(k.editable), - } - for k in KINDS.values() - if k.id not in APP_ONLY_KINDS - ] - - -# ── parameter validation ── - - -def _fail(code: str, message: str) -> CardCatalogError: - return CardCatalogError(code, message) - - -def _clean_str( - params: dict[str, Any], - key: str, - *, - required: bool = True, - max_len: int = _NAME_MAX, - pattern: re.Pattern[str] | None = None, - allow_empty: bool = False, -) -> str | None: - value = params.get(key) - if value is None: - if required: - raise _fail("missing_param", f"'{key}' is required") - return None - if not isinstance(value, str): - raise _fail("invalid_param", f"'{key}' must be a string") - value = value.strip() - if not value and not allow_empty: - raise _fail("invalid_param", f"'{key}' must not be empty") - if len(value) > max_len: - raise _fail("invalid_param", f"'{key}' must be at most {max_len} characters") - if any(ord(ch) < 0x20 and ch not in "\n\t" for ch in value): - raise _fail("invalid_param", f"'{key}' has control characters") - if pattern is not None and value and not pattern.fullmatch(value): - raise _fail("invalid_param", f"'{key}' has invalid characters") - return value - - -def _goal_text(params: dict[str, Any], key: str, *, max_len: int, multiline: bool) -> str: - """*key* as the goal record stores it (:func:`kiro_crew.member_goals.clean_text`). - - A card's params are what its apply writes and what its after-read is compared - with, so they carry the record's own normalisation: a tab, a line break in a - one-line field or a format character reads as the store will keep it. - """ - from kiro_crew import member_goals - - raw = _clean_str(params, key, max_len=max_len) - try: - value = member_goals.clean_text(raw, max_chars=max_len, multiline=multiline, what=key) - except member_goals.GoalError as exc: - raise _fail("invalid_param", f"'{key}': {exc}") from None - if not value: - raise _fail("invalid_param", f"'{key}' must not be empty") - return value - - -def _member_name(params: dict[str, Any], key: str, *, max_len: int = _NAME_MAX) -> str: - """A crewmate name exactly as ``POST /api/agents`` accepts it (any script).""" - from kiro_crew.members import MemberNameError, validate_member_name - - value = _clean_str(params, key, max_len=max_len) - assert value is not None - try: - return validate_member_name(value) - except MemberNameError as exc: - raise _fail("invalid_param", f"'{key}': {exc}") from None - - -def _clean_bool(params: dict[str, Any], key: str, *, required: bool = True) -> bool | None: - value = params.get(key) - if value is None and not required: - return None - if not isinstance(value, bool): - raise _fail("invalid_param", f"'{key}' must be a boolean") - return value - - -def _only(params: dict[str, Any], allowed: set[str], where: str = "params") -> None: - unknown = sorted(set(params) - allowed) - if unknown: - raise _fail("unknown_param", f"unknown field '{unknown[0][:64]}' in {where}") - - -def _clean_cron(params: dict[str, Any], *, required: bool) -> tuple[str | None, str | None]: - expr = _clean_str(params, "cron_expr", required=required, max_len=100, pattern=_CRON_EXPR_RE) - if expr is not None and len(expr.split()) != 5: - raise _fail("invalid_cron", "'cron_expr' must have 5 fields") - tz = _clean_str(params, "timezone", required=False, max_len=64, allow_empty=True) - return expr, (tz or None) - - -def _clean_at(params: dict[str, Any]) -> str: - """A one-shot ``at``: a real local date-time, normalized, with no offset. - - An offset is refused rather than honoured so the card has ONE zone, the - ``timezone`` field the user sees and can edit; ``2026-10-04T09:00-04:00`` - beside ``timezone: America/Los_Angeles`` would otherwise mean two instants. - """ - value = _clean_str(params, "at", max_len=32, pattern=_AT_RE) - assert value is not None - try: - parsed = datetime.fromisoformat(value) - except ValueError: - raise _fail("invalid_at", "'at' is not a real date and time") from None - return parsed.isoformat(timespec="minutes" if parsed.second == 0 else "seconds") - - -def _str_list(value: Any, key: str, *, max_len: int = 512) -> list[str]: - if not isinstance(value, list) or len(value) > _MAX_LIST_ITEMS: - raise _fail("invalid_param", f"'{key}' must be a list of at most {_MAX_LIST_ITEMS}") - out: list[str] = [] - for item in value: - if not isinstance(item, str) or not item or len(item) > max_len: - raise _fail("invalid_param", f"'{key}' items must be non-empty strings") - if item not in out: - out.append(item) - return out - - -def _template_clear(params: dict[str, Any]) -> tuple[str, ...]: - """The ``template.update`` list fields a card empties, named in ``clear``. - - A list of names rather than ``fields: {"allowedTools": []}``, because a client - that drops empty containers delivers that request with the key missing. - """ - if "clear" not in params: - return () - names = params["clear"] - if not isinstance(names, list) or not all( - isinstance(n, str) and n in _TEMPLATE_LIST_FIELDS for n in names - ): - raise _fail( - "invalid_param", - "'clear' must list template fields to empty: " + ", ".join(_TEMPLATE_LIST_FIELDS), - ) - return tuple(dict.fromkeys(names)) - - -def _check_mcp_spec_shapes(name: str, spec: dict[str, Any]) -> None: - """Refuse a custom MCP spec whose launch fields have the wrong type. - - The preview builds a launch line from these and the apply step sends them - verbatim, so a wrong shape is a bad request (400), never a crash (500). - """ - for key in ("command", "url"): - if key in spec and not isinstance(spec[key], str): - raise _fail("invalid_param", f"server '{name}' {key} must be a string") - if "args" in spec: - args = spec["args"] - if not isinstance(args, list) or not all(isinstance(a, str) for a in args): - raise _fail("invalid_param", f"server '{name}' args must be a list of strings") - for key in ("env", "headers"): - if key in spec: - values = spec[key] - if not isinstance(values, dict) or not all( - isinstance(k, str) and isinstance(v, str) for k, v in values.items() - ): - raise _fail("invalid_param", f"server '{name}' {key} must map strings to strings") - - -def validate_params(kind: str, params: Any) -> dict[str, Any]: - """Normalize *params* for *kind*. Raises :class:`CardCatalogError`.""" - if kind not in KINDS: - raise _fail("unknown_kind", f"unknown card kind '{str(kind)[:64]}'") - if not isinstance(params, dict): - raise _fail("invalid_params", "params must be an object") - try: - size = len(json.dumps(params, ensure_ascii=False)) - except (TypeError, ValueError): - raise _fail("invalid_params", "params must be JSON") from None - if size > _PARAMS_MAX_BYTES: - raise _fail("invalid_params", "params are too large") - p = params - out: dict[str, Any] - f: dict[str, Any] - if kind == KIND_SETTING_CHANGE: - _only(p, {"setting_id", "path", "value", "op", "item"}) - if ("setting_id" in p) == ("path" in p): - raise _fail("invalid_param", "give exactly one of 'setting_id' or 'path'") - if "setting_id" in p: - out = {"setting_id": _clean_str(p, "setting_id", max_len=200, pattern=_SETTING_ID_RE)} - else: - out = {"path": _clean_str(p, "path", max_len=200, pattern=_CONFIG_PATH_RE)} - if "op" in p or "item" in p: - # List membership: one item added to or removed from a string list. - if "value" in p: - raise _fail("invalid_param", "give either 'value' or 'op' with 'item', not both") - if p.get("op") not in _LIST_OPS: - raise _fail("invalid_param", "'op' must be 'add' or 'remove'") - if not isinstance(p.get("item"), str): - raise _fail("invalid_param", "'item' must be a string") - out["op"] = p["op"] - out["item"] = _clean_str(p, "item", max_len=_LIST_ITEM_MAX) - return out - if "value" not in p: - raise _fail("missing_param", "'value' is required") - if isinstance(p["value"], list): - raise _fail("invalid_param", "'value' must be a scalar or a record") - out["value"] = copy.deepcopy(p["value"]) - return out - if kind == KIND_SCHEDULE_CREATE: - _only(p, {"name", "message", "cron_expr", "at", "timezone"}) - if ("cron_expr" in p) == ("at" in p): - raise _fail("invalid_param", "give exactly one of 'cron_expr' or 'at'") - out = { - "name": _clean_str(p, "name"), - "message": _clean_str(p, "message", max_len=_TEXT_MAX), - } - if "at" in p: - out["at"] = _clean_at(p) - tz = _clean_str(p, "timezone", required=False, max_len=64, allow_empty=True) - else: - out["cron_expr"], tz = _clean_cron(p, required=True) - if tz: - out["timezone"] = tz - return out - if kind == KIND_SCHEDULE_UPDATE: - _only(p, {"id", "fields"}) - job_id = _clean_str(p, "id", pattern=_ID_RE) - fields = p.get("fields") - if not isinstance(fields, dict) or not fields: - raise _fail("invalid_param", "'fields' must be a non-empty object") - _only(fields, {"name", "message", "cron_expr", "timezone"}, "fields") - f = {} - if "name" in fields: - f["name"] = _clean_str(fields, "name") - if "message" in fields: - f["message"] = _clean_str(fields, "message", max_len=_TEXT_MAX) - if "cron_expr" in fields: - f["cron_expr"] = _clean_cron(fields, required=True)[0] - if "timezone" in fields: - f["timezone"] = _clean_str(fields, "timezone", max_len=64, allow_empty=True) or "" - return {"id": job_id, "fields": f} - if kind == KIND_CREWMATE_CREATE: - _only(p, {"name", "goal", "schedule"}) - out = { - "name": _member_name(p, "name", max_len=_CREWMATE_NAME_MAX), - "goal": _clean_str(p, "goal", max_len=_CREWMATE_GOAL_MAX), - } - schedule = p.get("schedule") - if schedule is not None: - if not isinstance(schedule, dict): - raise _fail("invalid_param", "'schedule' must be an object") - _only(schedule, {"cron_expr", "timezone"}, "schedule") - expr, tz = _clean_cron(schedule, required=True) - out["schedule"] = {"cron_expr": expr, **({"timezone": tz} if tz else {})} - return out - if kind == KIND_CREWMATE_IMPORT: - _only(p, set(KINDS[kind].params_schema["properties"])) - if p.get("format_version") not in CREWMATE_FORMAT_VERSIONS: - raise _fail("invalid_param", "'format_version' is not one this version reads") - out = { - "name": _member_name(p, "name", max_len=_CREWMATE_NAME_MAX), - "format_version": p["format_version"], - } - for key, max_len in (("description", _CREWMATE_DESCRIPTION_MAX), ("sender", 64)): - text = _clean_str(p, key, required=False, max_len=max_len, allow_empty=True) - if text: - out[key] = text - if p.get("goal") is not None: - out["goal"] = _goal_text(p, "goal", max_len=_LONG_TERM_GOAL_MAX, multiline=True) - left_out = _str_list(p.get("not_imported", []), "not_imported", max_len=32) - if not set(left_out) <= set(NOT_IMPORTED_CODES): - raise _fail("invalid_param", "'not_imported' names a part this version does not know") - if left_out: - out["not_imported"] = left_out - return out - if kind == KIND_CREWMATE_UPDATE: - _only(p, {"name", "fields"}) - name = _member_name(p, "name") - fields = p.get("fields") - if not isinstance(fields, dict) or not fields: - raise _fail("invalid_param", "'fields' must be a non-empty object") - _only( - fields, - {"description", "display_name", "model", "reasoning_effort", "approval_mode"}, - "fields", - ) - f = {} - for key in fields: - f[key] = _clean_str( - fields, key, max_len=_TEXT_MAX if key == "description" else 64, allow_empty=True - ) - if "approval_mode" in f and f["approval_mode"] not in MEMBER_APPROVAL_MODES: - raise _fail( - "invalid_param", - "'approval_mode' must be one of " + ", ".join(MEMBER_APPROVAL_MODES), - ) - return {"name": name, "fields": f} - if kind == KIND_CREWMATE_CAPABILITIES: - _only(p, {"member", "draft"}) - member = _member_name(p, "member") - draft = p.get("draft") - if not isinstance(draft, dict): - raise _fail("invalid_param", "'draft' must be an object") - _only(draft, {"operations", "enroll"}, "draft") - ops = draft.get("operations") - if not isinstance(ops, list) or not ops or len(ops) > _MAX_CAPABILITY_OPS: - raise _fail("invalid_param", "'draft.operations' must be a non-empty list") - clean_ops = [] - for op in ops: - if not isinstance(op, dict): - raise _fail("invalid_param", "each operation must be an object") - _only(op, {"section", "id", "action", "value"}, "operation") - if op.get("action") not in ("set", "remove", "inherit"): - raise _fail("invalid_param", "operation action must be set, remove or inherit") - if not isinstance(op.get("section"), str) or not isinstance(op.get("id"), str): - raise _fail("invalid_param", "operation needs section and id") - if op["action"] == "set" and "value" not in op: - raise _fail("invalid_param", "a set operation needs a value") - clean_ops.append(copy.deepcopy(op)) - clean_draft: dict[str, Any] = {"operations": clean_ops} - if "enroll" in draft: - clean_draft["enroll"] = _clean_bool(draft, "enroll") - return {"member": member, "draft": clean_draft} - if kind == KIND_CREWMATE_GOAL: - _only(p, {"member", "long_term", "goal_id"}) - out_goal: dict[str, Any] = { - "member": _member_name(p, "member"), - "long_term": _goal_text(p, "long_term", max_len=_LONG_TERM_GOAL_MAX, multiline=True), - } - if "goal_id" in p: - if not _goals.is_goal_id(p["goal_id"]): - raise _fail("invalid_param", "'goal_id' must be one of the crewmate's goal ids") - out_goal["goal_id"] = p["goal_id"] - return out_goal - if kind == KIND_CREWMATE_KEY_RESULTS: - _only(p, {"member", "items"}) - raw = p.get("items") - if not isinstance(raw, list) or not raw: - raise _fail("invalid_param", "'items' must hold at least one key result") - items: list[dict[str, Any]] = [] - for item in raw: - if not isinstance(item, dict): - raise _fail("invalid_param", "each key result is {text, target, goal_ids?}") - _only(item, {"text", "target", "goal_ids"}, "key result") - kr: dict[str, Any] = { - "text": _goal_text(item, "text", max_len=_KR_TEXT_MAX, multiline=False), - "target": _goal_text(item, "target", max_len=_KR_VALUE_MAX, multiline=False), - } - if any((k["text"], k["target"]) == (kr["text"], kr["target"]) for k in items): - raise _fail("invalid_param", "two key results have the same text and target") - if "goal_ids" in item: - links = item["goal_ids"] - if not isinstance(links, list) or not all(_goals.is_goal_id(g) for g in links): - raise _fail("invalid_param", "'goal_ids' is a list of the crewmate's goal ids") - kr["goal_ids"] = list(dict.fromkeys(links)) - items.append(kr) - return {"member": _member_name(p, "member"), "items": items} - if kind == KIND_CREWMATE_CHECK_INS: - _only(p, {"member", *CHECK_IN_FIELDS}) - out_ci: dict[str, Any] = {"member": _member_name(p, "member")} - for key in ("daily", "weekly", "monthly", "heartbeat"): - if key in p: - out_ci[key] = _clean_bool(p, key) - for key, low, high in (("weekday", 0, 6), ("month_day", 1, _goals.MAX_MONTH_DAY)): - if key in p: - v = p[key] - if not isinstance(v, int) or isinstance(v, bool) or not low <= v <= high: - raise _fail("invalid_param", f"'{key}' must be {low} to {high}") - out_ci[key] = v - if "time" in p: - t = p["time"] - if not isinstance(t, str) or not _goals.is_check_in_time(t): - raise _fail("invalid_param", "'time' must be HH:MM (24-hour)") - out_ci["time"] = t - if "interval" in p: - if not _goals.is_heartbeat_interval(p["interval"]): - raise _fail( - "invalid_param", - "'interval' must be one of " - + ", ".join(str(m) for m in _goals.HEARTBEAT_INTERVALS), - ) - out_ci["interval"] = p["interval"] - if len(out_ci) == 1: - raise _fail("invalid_param", "give at least one check-in or its timing") - return out_ci - if kind == KIND_TEMPLATE_UPDATE: - _only(p, {"template", "fields", "clear"}) - template = _clean_str(p, "template", pattern=_TEMPLATE_NAME_RE) - clear = _template_clear(p) - fields = p.get("fields") - if fields is None and clear: - # ``clear`` is a whole request on its own: a client that drops empty - # containers delivers no ``fields`` when it held only ``[]`` values. - fields = {} - if not isinstance(fields, dict) or not (fields or clear): - raise _fail( - "invalid_param", - "'fields' must be a non-empty object; to empty a list field, name it in 'clear'", - ) - _only(fields, {*_TEMPLATE_LIST_FIELDS, "model"}, "fields") - f = {} - for key in _TEMPLATE_LIST_FIELDS: - if key in fields: - f[key] = _str_list(fields[key], key) - if key in clear: - if f.get(key): - raise _fail( - "invalid_param", f"'{key}' is named in 'clear' and given items in 'fields'" - ) - f[key] = [] - if "model" in fields: - f["model"] = _clean_str(fields, "model", max_len=64, allow_empty=True) - # Normalized to the plain replacement, so the preview, the apply step, the - # person's edit and Undo read one shape whichever spelling the agent used. - return {"template": template, "fields": f} - if kind == KIND_MCP_INSTALL: - _only(p, {"provider", "id"}) - return { - "provider": _clean_str(p, "provider", max_len=32, pattern=_SLUG_RE), - "id": _clean_str(p, "id", max_len=256, pattern=_MCP_NAME_RE), - } - if kind == KIND_MCP_ADD_CUSTOM: - _only(p, {"servers", "enable"}) - servers = p.get("servers") - if not isinstance(servers, dict) or not servers or len(servers) > _MAX_CUSTOM_SERVERS: - raise _fail("invalid_param", "'servers' must be a non-empty object of servers") - clean: dict[str, Any] = {} - for name, spec in servers.items(): - if not isinstance(name, str) or not valid_mcp_name(name): - raise _fail("invalid_param", "invalid MCP server name") - if not isinstance(spec, dict) or not ( - isinstance(spec.get("command"), str) or isinstance(spec.get("url"), str) - ): - raise _fail("invalid_param", f"server '{name}' needs a command or a url") - _check_mcp_spec_shapes(name, spec) - clean[name] = copy.deepcopy(spec) - enable = p.get("enable", True) - if not isinstance(enable, bool): - raise _fail("invalid_param", "'enable' must be a boolean") - return {"servers": clean, "enable": enable} - if kind == KIND_MCP_TOGGLE: - _only(p, {"name", "server", "tool", "enabled"}) - enabled = _clean_bool(p, "enabled") - if "tool" in p or "server" in p: - if "name" in p: - raise _fail("invalid_param", "give either name, or server and tool") - return { - "server": _clean_str(p, "server", pattern=_MCP_NAME_RE), - "tool": _clean_str(p, "tool", max_len=256, pattern=_MCP_NAME_RE), - "enabled": enabled, - } - return {"name": _clean_str(p, "name", pattern=_MCP_NAME_RE), "enabled": enabled} - if kind == KIND_CONNECTION_CONNECT: - _only(p, {"slug"}) - return {"slug": _clean_str(p, "slug", max_len=64, pattern=_SLUG_RE)} - if kind == KIND_SECRET_SAVE: - # No ``value`` field exists: a secret's value is typed by the person into - # the card and sent by the browser straight to the vault route. - _only(p, {"name"}) - return {"name": _clean_str(p, "name", max_len=_NAME_MAX)} - if kind == KIND_TRUST_APP: - _only(p, {"name", "repository"}) - out = {"name": _clean_str(p, "name", max_len=64, pattern=_APP_NAME_RE)} - repo = _clean_str(p, "repository", required=False, max_len=512) - if repo: - out["repository"] = repo - return out - if kind == KIND_FOLDER_STEERING: - _only(p, {"folder", "steering_dirs", "clear"}) - folder = _clean_str(p, "folder", pattern=_ID_RE) - if _clean_bool(p, "clear", required=False): - # The spelling of ``steering_dirs: []`` that survives a client which drops - # an empty list, normalized to that list so every later step reads one shape. - if p.get("steering_dirs"): - raise _fail( - "invalid_param", "'clear' empties the list, so give it without 'steering_dirs'" - ) - return {"folder": folder, "steering_dirs": []} - if "steering_dirs" not in p: - raise _fail( - "invalid_param", - "'steering_dirs' is required; to empty the list, pass 'clear': true", - ) - return { - "folder": folder, - "steering_dirs": _str_list( - p.get("steering_dirs"), "steering_dirs", max_len=FOLDER_STEERING_DIR_MAX - ), - } - # KIND_DENIED_COMMAND - action = p.get("action") - if action == "add": - _only(p, {"action", "pattern", "note"}) - pattern = _clean_str(p, "pattern", max_len=_PATTERN_MAX) - try: - re.compile(pattern or "") - except re.error: - raise _fail("invalid_param", "'pattern' is not a valid regex") from None - note = _clean_str(p, "note", required=False, max_len=200, allow_empty=True) or "" - return {"action": "add", "pattern": pattern, "note": note} - if action == "toggle": - _only(p, {"action", "id", "enabled"}) - return { - "action": "toggle", - "id": _clean_str(p, "id", pattern=_ID_RE), - "enabled": _clean_bool(p, "enabled"), - } - raise _fail("invalid_param", "'action' must be 'add' or 'toggle'") - - -def valid_mcp_name(name: str) -> bool: - return ( - bool(name) - and len(name) <= _NAME_MAX - and ".." not in name - and bool(_MCP_NAME_RE.fullmatch(name)) - ) - - -def check_editable(kind: str, old: dict[str, Any], new: dict[str, Any]) -> None: - """Refuse a re-preview that changes a field the kind does not mark editable.""" - editable = set(KINDS[kind].editable) - for key in set(old) | set(new): - if key not in editable and old.get(key) != new.get(key): - raise _fail("field_not_editable", f"'{key}' cannot be changed on this card") - - -# ── plans ── - - -def _q(segment: str) -> str: - return urllib.parse.quote(segment, safe="") - - -def step( - method: str, - path: str, - body: Any = None, - *, - fill: list[dict[str, Any]] | None = None, - repeat: bool = False, -) -> dict[str, Any]: - s: dict[str, Any] = {"method": method, "path": path, "body": body} - if fill: - s["fill"] = fill - if repeat: - s["repeat"] = True - return s - - -def _user_fill(field: str) -> dict[str, Any]: - return {"field": field, "source": "user"} - - -def _step_fill(field: str, step_index: int, key: str) -> dict[str, Any]: - return {"field": field, "source": "step", "step": step_index, "key": key} - - -def _step_path_fill(field: str, step_index: int, key: str) -> dict[str, Any]: - """A ``step`` fill of one path segment instead of a body field. - - The step's path carries :func:`placeholder` where the segment goes, and the - value must be a plain identifier (:data:`PATH_FILL_VALUE`), so an earlier - response can never add a segment or a query to the path. - """ - return {**_step_fill(field, step_index, key), "in": "path"} - - -def is_path_fill(fill: dict[str, Any]) -> bool: - return fill.get("in") == "path" - - -#: What a path fill may stand for: one segment of identifier characters. -PATH_FILL_VALUE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}\Z") - - -def placeholder(fill: dict[str, Any]) -> str: - if fill["source"] == "user": - return _PLACEHOLDER % f"user:{fill['field']}" - return _PLACEHOLDER % f"step{fill['step']}.{fill['key']}" - - -def _with_fills(body: dict[str, Any], fills: list[dict[str, Any]]) -> dict[str, Any]: - out = dict(body) - for f in fills: - out[f["field"]] = placeholder(f) - return out - - -def _cron_body(fields: dict[str, Any]) -> dict[str, Any]: - body: dict[str, Any] = {} - for key in ("name", "message", "timezone"): - if key in fields: - body[key] = fields[key] - if "cron_expr" in fields: - body["cron"] = fields["cron_expr"] - return body - - -def _list_diff(before: list[str], after: list[str]) -> tuple[list[str], list[str]]: - return [x for x in after if x not in before], [x for x in before if x not in after] - - -def _order_risk(order: tuple[Any, ...], before: Any, after: Any) -> str: - """Rank a move along *order* (tightest first): toward the end widens.""" - if before not in order or after not in order: - return RISK_NORMAL - b, a = order.index(before), order.index(after) - if a > b: - return RISK_WIDEN - if a < b: - return RISK_TIGHTEN - return RISK_NORMAL - - -def _setting_risk(path: str, before: Any, after: Any) -> str: - if path in _CODE_EXEC_SETTINGS: - return RISK_CODE_EXEC - order = _SETTING_ORDER.get(path) - if path == "dashboard.tailscale.pin_scope": - # The route takes any short string and the loader applies its - # normalised form, so rank the values the gateway will apply. - before, after = effective_pin_scope(before), effective_pin_scope(after) - if order is not None and before in order and after in order: - return _order_risk(order, before, after) - segments = set(guide_catalog._SEGMENT_SPLIT.split(path.lower())) - if segments & guide_catalog._EXCLUDED_SETTING_SEGMENTS: - return RISK_WIDEN - return RISK_NORMAL - - -STORE_KIROCREW = "kirocrew" -STORE_DASHBOARD = "dashboard" - -#: Settings whose Settings-page control writes the DASHBOARD config -#: (``PUT /api/dashboard/config``, partial body) rather than a config path: each -#: registry id maps to the body key ``ChatPanel.tsx`` / ``BrowserPanel.tsx`` send -#: and the values that control offers. A registry id absent here, with no -#: editable ``configKey`` either, has no write path a card may use. -_BOOL_VALUES: tuple[Any, ...] = (True, False) -DASHBOARD_SETTINGS: dict[str, tuple[str, tuple[Any, ...]]] = { - "chat.response-verbosity": ("verbosity", ("default", "concise", "ultra", "answer_only")), - "chat.widget-density": ("widget_density", ("more", "less")), - "chat.quick-send": ("quick_send", _BOOL_VALUES), - "chat.merge-queued-messages": ("merge_queued_messages", _BOOL_VALUES), - "chat.link-previews": ("link_previews", _BOOL_VALUES), - "chat.mcp-apps-in-side-panel": ("mcp_app_panel", _BOOL_VALUES), - "chat.auto-open-git-in-side-panel": ("auto_open_git_panel", _BOOL_VALUES), - "chat.split-view-session-grid": ("session_grid", _BOOL_VALUES), - "chat.tail-only-fork": ("tail_fork_enabled", _BOOL_VALUES), - "chat.restore-sessions": ("restore_sessions", _BOOL_VALUES), - "chat.restore-window": ("restore_window_minutes", (15, 30, 60, 120, 360, 720, 1440, 0)), - "chat.pr-and-issue-chips-on-session-cards": ("session_card_source_links", _BOOL_VALUES), - "chat.folder-suggestions": ("folder_suggestions_enabled", _BOOL_VALUES), - "chat.default-memory-mode": ("default_memory_mode", ()), - "browser.use-the-built-in-browser": ("use_builtin_browser", _BOOL_VALUES), -} -#: Body keys of ``PUT /api/dashboard/config`` a card may write, by key. -DASHBOARD_KEYS = {key: values for key, values in DASHBOARD_SETTINGS.values()} - -#: Dashboard settings whose value is a STRING LIST the Settings page edits one -#: item at a time: registry id -> (stored key, add body key, remove body key), -#: exactly the delta keys ``ChatPanel.tsx``'s Selectable Models control sends to -#: ``PUT /api/dashboard/config``. A ``setting.change`` card on one of these takes -#: ``op``/``item`` instead of ``value``. -DASHBOARD_LIST_SETTINGS: dict[str, tuple[str, str, str]] = { - "chat.selectable-models": ( - "model_picker_hidden_models", - "model_picker_hidden_models_add", - "model_picker_hidden_models_remove", - ), -} -#: The same, by stored key. -DASHBOARD_LIST_KEYS = {v[0]: v for v in DASHBOARD_LIST_SETTINGS.values()} -#: How a one-item edit of a list setting reads, by stored key: (row label, add -#: title, remove title). The registry label names the Settings control, which -#: can say the opposite of the stored list ("Selectable Models" edits the HIDDEN -#: list), so the card names the list it really edits and says what the person -#: will see. A list without an entry reads "Add X to