diff --git "a/api/routes_external.py" "b/api/routes_external.py" --- "a/api/routes_external.py" +++ "b/api/routes_external.py" @@ -24,7 +24,7 @@ import external_activity import external_freshness import aios_session from deps import Session, err, require_session -from core import audit, external_access, external_oauth, external_tools, perm_scope, sheets +from core import audit, data_binding, external_access, external_oauth, external_tools, perm_scope, sheets from harness import runtime @@ -47,6 +47,7 @@ _VIEW_DRAFT_CONFIG_KEYS = frozenset({ }) _CONFIRMATION_BUCKET = "external_confirmations" _CONFIRMATION_TTL_SECONDS = 5 * 60 +_OPERATION_RETENTION_SECONDS = 24 * 60 * 60 _CONFIRMATION_MAX_BYTES = 512 * 1024 _CONFIRMATION_PHRASE = "CONFIRM SCHEMA OR DESTRUCTIVE CHANGE" _CONFIRMATION_PREFIX = "cfm1" @@ -101,6 +102,8 @@ class _PreviewRuntime: the separate pure planner below because those routes deliberately emit automation callbacks. """ + activity_preview = True + def __init__(self, real): self._real = real self._initial = {} @@ -144,6 +147,9 @@ class _PreviewRuntime: def get_many(self, names): return {str(name): self.get(name) for name in names or ()} + def get_entry(self, name, entry): + return copy.deepcopy((self.get(name) or {}).get(entry)) + def get_projections(self, names, drop=(), timeout_s=None): return {str(name): self.get_projection(name, drop=drop) for name in names or ()} @@ -207,6 +213,15 @@ class _PreviewRuntime: return getattr(self._real, name) +class _ReceiptRuntime(_PreviewRuntime): + """Allow a group's receipt permission check to read without saving anything.""" + + def update(self, *args, **kwargs): + raise err(403, "operation_unavailable", "This operation's access could not be checked safely.") + + put = update + + class _ConfirmationRuntime: """Revision-guard every bucket the confirmed product writer may mutate.""" @@ -233,7 +248,8 @@ class _ConfirmationRuntime: answer = self._real.update( key, callback, flush=flush, expect_rev=rev, audit_row=audit_row) try: - self._expected[key] = copy.deepcopy(self._real.revision(key)) + produced = copy.deepcopy(self._real.revision(key)) + self._expected[key] = produced if produced.get("rev") == rev + 1 else {"rev": rev + 1} except Exception: self._expected[key] = {"rev": rev + 1} return answer @@ -259,9 +275,14 @@ def _diff_documents(documents, *, limit=250): def walk(before, after, path): if len(changes) >= limit or before == after: return - if isinstance(before, dict) and isinstance(after, dict): - for key in sorted(before.keys() | after.keys(), key=str): - walk(before.get(key), after.get(key), [*path, str(key)]) + # An added or removed cell is one complete change, regardless of its property count. + whole_cell = (len(path) == 6 and path[0] == "workbooks" and path[2] == "sheets" + and path[4] == "cells" and (before is None or after is None)) + if not whole_cell and ((isinstance(before, dict) and (after is None or isinstance(after, dict))) or ( + before is None and isinstance(after, dict))): + left, right = before or {}, after or {} + for key in sorted(left.keys() | right.keys(), key=str): + walk(left.get(key), right.get(key), [*path, str(key)]) return if isinstance(before, list) and isinstance(after, list): for index in range(max(len(before), len(after))): @@ -269,14 +290,104 @@ def _diff_documents(documents, *, limit=250): after[index] if index < len(after) else None, [*path, str(index)]) return - changes.append({"path": "/" + "/".join(path), + changes.append({"path": "/" + "/".join(part.replace("~", "~0").replace("/", "~1") for part in path), "before": copy.deepcopy(before), "after": copy.deepcopy(after)}) for bucket, pair in sorted(documents.items()): - walk(pair.get("before"), pair.get("after"), [bucket]) + walk(pair.get("before"), pair.get("after"), bucket.split("/")) return changes, len(changes) >= limit +def _database_preview_documents(session, before, after): + """Project changed records and fields through the caller's current database permissions.""" + import routes_tables + from core import user_tables + + documents = {} + for database in sorted(before.keys() | after.keys()): + if before.get(database) == after.get(database): + continue + pair = {} + for side, bucket in (("before", before), ("after", after)): + table = bucket.get(database) + if not table: + pair[side] = None + continue + rt = _PreviewRuntime(session.runtime) + rt.put(user_tables.STORE_KEY, bucket) + reader = Session(session.tenant, session.user, session.claims, rt) + try: + _assert_database_scope(reader, database) + # A supplied runtime avoids reusing the current grid's cached assembly for the proposed data. + scoped = routes_tables.ut_assembly(reader, database, with_rows=False, st=rt) + except HTTPException as exc: + if exc.status_code not in (403, 404): + raise + pair[side] = None + continue + visible = {field["key"] for field in scoped["fields"]} + pair[side] = { + "fields": {field["key"]: field for field in table.get("fields", []) if field["key"] in visible}, + "records": {str(rid): {key: value for key, value in row.items() if key in visible} + for rid, row in (table.get("rows") or {}).items() + if str(rid).isdigit() and int(rid) in scoped["pids"]}, + } + documents["databases/" + database] = pair + return documents + + +def _request_preview_documents(session, request_id, documents): + """Project a request change through current participation, credential and source access.""" + import tickets + from tool_groups import requests + + pair = {} + for side in ("before", "after"): + snapshot = _PreviewRuntime(session.runtime) + for key, changed in documents.items(): + snapshot.put(key, changed[side]) + reader = Session(session.tenant, session.user, session.claims, _ReceiptRuntime(snapshot)) + ctx = _tool_context(reader, preview=True) + name, _label, _connection, databases = requests._identity(ctx) + task = tickets.get_request_attribution( + reader.runtime, request_id, name, + source_check=lambda source: requests._source_scope(ctx, source, databases)) + if not task["sourceVisible"]: + raise PermissionError("You cannot see the source data this request needs.") + pair[side] = {task["id"]: task} + return {"requests": pair} + + +def _public_preview_documents(session, documents): + """Show readable workbook values without copying private caches or write history.""" + from core import user_tables + + public = {} + for key, pair in documents.items(): + if key == user_tables.STORE_KEY: + public.update(_database_preview_documents(session, pair["before"] or {}, pair["after"] or {})) + elif key.startswith(sheets.WORKBOOK_KEY_PREFIX): + projected = {} + for side in ("before", "after"): + book = pair[side] + if not book: + projected[side] = None + continue + rt = _PreviewRuntime(session.runtime) + for changed_key, changed in documents.items(): + rt.put(changed_key, changed[side]) + reader = Session(session.tenant, session.user, session.claims, rt) + ctx = _tool_context(reader, preview=True) + ctx.require_reader(book) + projected[side] = ctx.project_book(copy.deepcopy(book)) + public["workbooks/" + key[len(sheets.WORKBOOK_KEY_PREFIX):]] = projected + elif key == sheets.INDEX_KEY or key.startswith(sheets.SCOPE_CACHE_KEY_PREFIX): + continue + else: + public[key] = pair + return public + + def _credential_binding(session: Session) -> str: claims = session.claims or {} return str(claims.get("external_credential_id") or claims.get("external_key_id") or "") @@ -315,7 +426,8 @@ def _assert_finite_query_value(value) -> None: "A permitted record contains a value that cannot be represented safely.") from exc -def _cursor_proof(session: Session, query_digest: str, snapshot_digest: str, offset: int) -> str: +def _cursor_proof(session: Session, query_digest: str, snapshot_digest: str, offset: int, + publication=None) -> str: claims = session.claims or {} binding = { "tenant": session.tenant, @@ -326,22 +438,26 @@ def _cursor_proof(session: Session, query_digest: str, snapshot_digest: str, off "offset": offset, "version": 1, } + if publication is not None: + binding["publication"] = publication raw = json.dumps(binding, sort_keys=True, separators=(",", ":")).encode("utf-8") return aios_session._sign(b"external-query:v1:" + raw) def _encode_query_cursor(session: Session, query_digest: str, - snapshot_digest: str, offset: int) -> str: + snapshot_digest: str, offset: int, publication=None) -> str: payload = { "v": 1, "q": query_digest, "s": snapshot_digest, "o": offset, - "p": _cursor_proof(session, query_digest, snapshot_digest, offset), + "p": _cursor_proof(session, query_digest, snapshot_digest, offset, publication), } + if publication is not None: + payload["i"] = publication raw = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("ascii") return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") -def _decode_query_cursor(session: Session, raw, query_digest: str, - snapshot_digest: str) -> int: +def _read_query_cursor(session: Session, raw) -> dict: + """Authenticate a cursor before reading the source publication.""" if not isinstance(raw, str) or not raw or len(raw) > _QUERY_MAX_CURSOR: raise err(400, "query_cursor_invalid", "The query cursor is invalid.") try: @@ -351,23 +467,68 @@ def _decode_query_cursor(session: Session, raw, query_digest: str, except (ValueError, TypeError, UnicodeError, json.JSONDecodeError) as exc: raise err(400, "query_cursor_invalid", "The query cursor is invalid.") from exc if (not isinstance(payload, dict) - or set(payload) != {"v", "q", "s", "o", "p"} - or payload.get("v") != 1 + or set(payload) not in ({"v", "q", "s", "o", "p"}, {"v", "q", "s", "o", "p", "i"}) + or type(payload.get("v")) is not int or payload["v"] != 1 or type(payload.get("o")) is not int or payload["o"] < 0 or not isinstance(payload.get("q"), str) or not isinstance(payload.get("s"), str) or not isinstance(payload.get("p"), str)): raise err(400, "query_cursor_invalid", "The query cursor is invalid.") - expected = _cursor_proof(session, payload["q"], payload["s"], payload["o"]) - if not hmac.compare_digest(payload["p"], expected): + publication = payload.get("i") + if "i" in payload and (not isinstance(publication, dict) + or set(publication) != {"source", "snapshot_id"} + or any(not isinstance(value, str) or not value for value in publication.values())): + raise err(400, "query_cursor_invalid", "The query cursor is invalid.") + expected = _cursor_proof(session, payload["q"], payload["s"], payload["o"], publication) + if not payload["p"].isascii() or not hmac.compare_digest(payload["p"], expected): raise err(400, "query_cursor_invalid", "The query cursor is invalid.") + return payload + + +def _decode_query_cursor(session: Session, raw, query_digest: str, + snapshot_digest: str, publication=None) -> int: + payload = _read_query_cursor(session, raw) + _assert_query_publication(payload.get("i"), publication) if payload["q"] != query_digest or payload["s"] != snapshot_digest: raise err(409, "query_cursor_stale", "The query or its permitted result set changed. Start again without a cursor.") return payload["o"] +def _query_publication(session: Session, database: str): + """Read C6 using the database's declared connector, only when its provider exists.""" + try: + from harness import datastore + absent = object() + provider = getattr(datastore, "snapshot_id", absent) + if provider is absent: + return None + from core import connector_spec + source = connector_spec.connector_of(database) + if not source: + definitions = session.runtime.get_projection("user_tables", drop=("rows",)) + source = str((definitions.get(database) or {}).get("source") or "").strip().lower() + source = {"meta ads": "meta", "amazon sp-api": "amazon"}.get(source, source) + source = connector_spec.CONNECTOR_SPEC_KEYS.get(source, source) + if not source or source in {"blank", "loopable"}: + raise ValueError("Missing connector metadata") + identity = provider(session.tenant, source) + if not isinstance(identity, str) or not identity.strip(): + raise ValueError("Invalid snapshot identity") + return {"source": source, "snapshot_id": identity} + except Exception as exc: + raise err(503, "query_source_unavailable", + "This database is temporarily unavailable. Try the same query again shortly.") from exc + + +def _assert_query_publication(previous, current): + """An absent provider preserves legacy paging, but a present provider must match.""" + if current is not None and previous != current: + raise err(409, "query_cursor_stale", + "The database has a different completed sync. Request a fresh first page.") + + def _sort_atom(value): if isinstance(value, bool): return "bool", 1 if value else 0 @@ -560,6 +721,8 @@ def _assert_database_scope(session, database): def _external_read_scope(session: Session, database, *args, **kwargs): """Attach external refusal details at the shared Assistant read boundary.""" try: + if database == "ut_activity": + return _native_activity_scope(session, *args, **kwargs) return deps.assistant_read_scope(session, database, *args, **kwargs) except HTTPException as exc: error = exc.detail.get("error", {}) if isinstance(exc.detail, dict) else {} @@ -569,9 +732,118 @@ def _external_read_scope(session: Session, database, *args, **kwargs): raise -def _assert_write_scope(session, tool_name): - if not external_access.may_write(_key_scope(session)[0]): +def _activity_predicates(filters, visible_keys): + """Lower only indexed activity predicates, refusing every unsupported condition.""" + from core import activity_log + predicates = {} + count = 0 + + def visit(node, depth=0): + nonlocal count + count += 1 + if depth > _QUERY_MAX_FILTER_DEPTH or count > _QUERY_MAX_FILTER_NODES: + raise err(400, "query_filter_limit", "The activity filter exceeds the query limits.") + if node is None or node == [] or node == {}: + return + if isinstance(node, list): + if len(node) > _QUERY_MAX_FILTER_SIBLINGS: + raise err(400, "query_filter_limit", "The activity filter has too many conditions.") + for child in node: + visit(child, depth + 1) + return + if isinstance(node, dict) and set(node) == {"conj", "nodes"}: + if node["conj"] == "and" and isinstance(node["nodes"], list): + visit(node["nodes"], depth) + return + if isinstance(node, dict) and set(node) == {"colId", "op", "value"}: + field, op, value = node["colId"], node["op"], node["value"] + if not isinstance(field, str) or not isinstance(op, str): + raise err(400, "assistant_bad_filter", "Use named activity fields and operators.") + parameter = {("object", "eq"): "object", ("by", "eq"): "by", + ("occurred_at", "gte"): "since", ("occurred_at", "lte"): "until"}.get((field, op)) + if parameter and field in visible_keys and parameter not in predicates: + try: + if parameter == "object": + activity_log._object(value, allow_key_only=True) + elif parameter == "by": + activity_log._text(value, "by") + else: + activity_log._time(value) + except (TypeError, ValueError) as exc: + raise err(400, "assistant_bad_filter", "Use a valid activity filter value.") from exc + predicates[parameter] = value + return + raise err(400, "assistant_bad_filter", + "Activity supports object and by equality, and occurred_at gte/lte joined with and.") + + visit(filters) + return predicates + + +def _native_activity_scope(session, fields=None, filters=None, *, mode=None): + """Read the native activity contract without admitting a connector mirror.""" + from core import activity_log + import routes_tables + _assert_database_scope(session, "ut_activity") + routes_tables._defn_or_refuse(session, "ut_activity", defs_only=True, scope_applied=True) + try: + activity_log._backend(session.runtime) + except (TypeError, ValueError) as exc: + raise err(503, "query_source_unavailable", "Activity storage is unavailable for this workspace.") from exc + grid = routes_tables._compute_ut_assembly(session, "ut_activity", with_rows=False, fields_only=True) + visible = list(grid["fields"]) + keys = {field["key"] for field in visible} + selected = deps._assistant_requested_fields(fields, visible) + _activity_predicates(filters, keys) + if mode not in ("schema", "query_schema"): + raise err(409, "activity_window_required", "Read activity through query_database one page at a time.") + return {"database": "ut_activity", "label": "Activity", "source_kind": "native_activity", + "source_version": {"read": "native activity"}, "permission_scope_applied": True, + "retrieved_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), + "fields": [field for field in visible if field["key"] in selected], + "filters": copy.deepcopy(filters), "records": []} + + +def _assert_workbook_scope(session, workbook): + """A refresh credential admits only explicitly granted workbooks.""" + if (_key_scope(session)[0] == external_access.ACCESS_REFRESH + and workbook not in external_access.workbooks_of({ + "workbooks": session.claims.get("external_workbooks")})): + raise err(403, "key_workbook_out_of_scope", "This connection cannot refresh this workbook.") + + +def _assert_write_scope(session, tool_name, arguments=None): + access = _key_scope(session)[0] + if access == external_access.ACCESS_REFRESH: + if tool_name != "sheet" or not isinstance(arguments, dict) or arguments.get("action") != "refresh_scope": + raise err(403, "key_refresh_only", "This connection can only refresh source cells in its granted workbooks.") + import tool_groups + _, args = tool_groups.resolve(tool_name, arguments) + _assert_workbook_scope(session, args["workbook_id"]) + elif not external_access.may_write(access): raise err(403, "key_read_only", f"{tool_name} writes, and this credential is read only.") + code = _test_environment_refusal(session) + if code: + raise err(403, code, MCP_RESULT_CODES[code]) + + +def _write_environment(): + """Use the same runtime identity as the store isolation rules.""" + name = data_binding.deployment_id() + return {"name": name or "unknown", "production": data_binding.is_production_deployment(), + "known": bool(name)} + + +def _test_environment_refusal(session): + key_id = session.claims.get("external_key_id") + if not key_id or not external_access.is_test_connection(session.runtime, key_id): + return None + environment = _write_environment() + if environment["production"]: + return "test_connection_production" + if not environment["known"]: + return "test_connection_environment_unknown" + return None def _databases_in_arguments(value): @@ -601,10 +873,12 @@ def _auth_refusal(request: Request | None = None): if request is not None: metadata = _oauth_urls(request)["resource_metadata"] challenge += f' resource_metadata="{metadata}"' + detail = {"error": {"code": external_access.AUTH_ERROR, + "message": "The credential is invalid, expired, or revoked."}} + if request is None or request.url.path.endswith("/mcp"): + detail = _shape_mcp_result({"ok": False, "error": {**detail["error"], "status": 401}}) raise HTTPException( - status_code=401, - detail={"error": {"code": external_access.AUTH_ERROR, - "message": "The credential is invalid, expired, or revoked."}}, + status_code=401, detail=detail, headers={"WWW-Authenticate": challenge}, ) @@ -653,6 +927,7 @@ def require_external_session( "external_credential_id": verified.key_id, "external_key_id": verified.key_id, "external_access": verified.access, + "external_workbooks": list(verified.workbooks), "external_databases": (external_access.ALL_DATABASES if verified.databases == external_access.ALL_DATABASES else list(verified.databases)), @@ -683,13 +958,17 @@ def _can_use_analyst(session: Session) -> bool: def _management_refusal(exc: external_access.ExternalAccessError): if exc.code == "external_access_scope_invalid": - raise err(400, exc.code, "Choose Read only or Read and write.") + raise err(400, exc.code, "Choose Read only, Read and write, or Refresh only for an API key.") + if exc.code == "external_workbooks_invalid": + raise err(400, exc.code, "Choose up to 100 workbook ids. All workbooks is not a valid choice.") if exc.code == "external_databases_invalid": raise err(400, exc.code, "Choose all databases, or name at least one database.") if exc.code == "external_label_invalid": raise err(400, exc.code, "Enter a label between 1 and 80 characters.") if exc.code == "external_expiry_invalid": raise err(400, exc.code, "Choose a future UTC expiry, or no expiry.") + if exc.code == "external_test_connection_invalid": + raise err(400, exc.code, "Set test_connection to true or false.") if exc.code == "external_edit_empty": raise err(400, exc.code, "Change at least one credential setting.") if exc.code == "external_key_not_found": @@ -745,10 +1024,26 @@ def _resolve_external_scope( status = ({database: {"permitted": True, "answerable": True} for database in databases} if strict_schema and databases is not None else deps.assistant_source_status(session, databases=databases)) + if "ut_activity" in status and not strict_schema: + # The Assistant's row decides permission. The native door only narrows it: an access + # refusal drops the source, and an unavailable backend leaves it listed but unanswerable. + try: + _native_activity_scope(session, mode="schema") + except HTTPException as exc: + info = exc.detail.get("error", {}) if isinstance(exc.detail, dict) else {} + row = dict(status["ut_activity"]) + if exc.status_code in (401, 403, 404): + row.update(permitted=False, answerable=False, visible=False) + else: + row["answerable"] = False + row["reason"] = info.get("message") or row.get("reason") or "" + status["ut_activity"] = row definitions = None def fallback_label(database: str) -> str: nonlocal definitions + if database == "ut_activity": + return "Activity" built_in = deps.module_cache_source(database) if built_in: return str(built_in.get("label") or database) @@ -853,8 +1148,8 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: "codex mcp login loopable", "```", "", - ("Cursor: add `{\"mcpServers\": {\"loopable\": {\"url\": \"" + surface_url + "/mcp\"}}}` " - "to `~/.cursor/mcp.json`, keeping any existing servers, then finish the Loopable sign-in."), + ("Cursor: add Loopable in the MCP settings with this server URL, then finish the Loopable sign-in: " + f"`{surface_url}/mcp`."), "", ("For code or an SDK, ask the user to create an API key in Loopable under AI API and to " "store it in an environment variable. Never ask for the key in chat and never print it."), @@ -863,13 +1158,13 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: lines = [ "---", "name: loopable-external-data", - "description: Read governed data and build Sheet workbooks, saved Views and Apps as the key's maker.", + "description: Read data and build Sheet workbooks, saved Views and Apps with your own permissions.", "---", "", "# Loopable external data", "", ("This surface reads governed data and writes only through the named build tools, " - "as the key's maker with the maker's own grants. It applies the same database, " + "with the signed-in user's permissions. It applies the same database, " "field, row and workbook permissions as the Loopable app."), "", # HOTFIX 2026-09-24 (owner: "available for ALL AI API connection so its also skill etc, @@ -879,8 +1174,8 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: "", *MCP_INSTRUCTIONS.split(chr(10)), "", - ("Over remote MCP, call `loopable_guide` first. It returns these rules, your databases " - "and every tool, generated from the running server."), + ("Over remote MCP, call `loopable_guide` first. It returns these rules, workspace connections, " + "your skills and databases, and the tool groups."), "", "## Authentication", "", @@ -894,6 +1189,16 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: f"Base URL: `{surface_url}`", "", *connect, + "## First conversation", + "", + "1. Connect your AI client to Loopable and finish signing in.", + "2. Call `loopable_guide`.", + "3. Say which AI clients are connected in the workspace and who connected each one, using the guide's list.", + "4. List the skills this user may use, using the guide's list. An empty list means none are available.", + "5. Ask three questions, one at a time. Wait for each answer: What is your role? " + "What is your first goal? Which database matters most to you?", + "6. Propose two or three things to build using the answers and the user's available databases and skills.", + "", "## First call: list databases", "", "Endpoint: `GET /api/v1/external/databases`", @@ -1002,7 +1307,8 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: lines.append(f"### `{database}`: {label}") lines.append("") if not row["answerable"]: - reason = _markdown_inline(row.get("reason") or "This source is not answerable right now.") + reason = _mcp_plain(_markdown_inline(row.get("reason")), + "This database is not available right now.", {row["database"]: label}) lines.extend([f"Not answerable right now: {reason}", ""]) if row.get("fields") or row["answerable"]: fields = [ @@ -1030,7 +1336,8 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: "Endpoint: `POST /api/v1/external/mcp`", "", ("Send one JSON-RPC 2.0 object per request. Methods: initialize, tools/list, tools/call " - "and ping. Initialize echoes your protocolVersion and advertises tools. Requests " + "and ping. Initialize returns your protocolVersion when supported, otherwise the " + "newest version Loopable supports, and advertises tools. Requests " "without an id, or with a null id, receive HTTP 204."), "", "```json", @@ -1038,7 +1345,7 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: "```", "", ("A tools/call response has jsonrpc, id and result. The result contains " - "content: [{type: 'text', text: ''}] and isError. " + "content: [{type: 'text', text: ''}] and isError. " "A tool refusal uses HTTP 200 with ok: false and isError: true; its error names " "the tool, code, status and reason. Invalid or revoked credentials receive HTTP 401."), "", @@ -1056,7 +1363,7 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: "", ("View tools use the grid's native config: filters, sorts, groupBy, visible and display. " "Fields omitted from visible are hidden. The grid validates the config. App tools use " - "the Application registry's typed config. app_delete requires the exact current " + "the App's settings. app_delete requires the exact current " "App name in confirmName, including after a rename."), "", ]) @@ -1064,27 +1371,27 @@ def _portable_skill_document(session: Session | None, base_url: str) -> str: lines.extend([ f"### `{name}`", "", - _markdown_inline(tool["description"]), + _mcp_plain(_markdown_inline(tool["description"]), "Read the guide for this action."), "", "Writes: " + ("yes" if tool["write"] else "no") + ".", "", "```json", - json.dumps(tool["inputSchema"], indent=2, ensure_ascii=True), + json.dumps(_mcp_schema_copy(tool["inputSchema"]), indent=2, ensure_ascii=True), "```", "", ]) lines.extend([ "## Limits", "", - ("This surface writes only through the named tools, as the key's maker with the maker's " - "own grants. Workbook roles and database restrictions still apply. Each credential also " + ("This surface writes only through the named tools with your permissions. " + "Workbook roles and database restrictions still apply. Each credential also " "carries its own access level and database scope, set when it is created and shown in " "Loopable Settings. It returns no data " - "the maker cannot already see in Loopable. Sheet cell history records the maker and " - "key label. Saved Views and Apps keep the UI's username attribution; their writers " - "have no author display-name field. No tool writes to Odoo."), + "you cannot already see in Loopable. Sheet cell history records your name and " + "connection. Saved Views and Apps record your username. No tool writes to Odoo."), "", ]) + lines.extend(["", _mcp_code_guide(), ""]) document = "\n".join(lines) if _contains_credential(document): raise RuntimeError("portable skill document contained a credential value") @@ -1098,11 +1405,13 @@ def create_key(body=Body(default=None), session: Session = Depends(require_sessi label = body.get("label") if isinstance(body, dict) else None access = body.get("access") if isinstance(body, dict) else None databases = body.get("databases") if isinstance(body, dict) else None + workbooks = body.get("workbooks") if isinstance(body, dict) else None expires_at = body.get("expires_at") if isinstance(body, dict) else None + test_connection = body.get("test_connection", False) if isinstance(body, dict) else False try: key, token = external_access.mint(session.runtime, session.uname, session.tenant, label, - access=access, databases=databases, - expires_at=expires_at) + access=access, databases=databases, workbooks=workbooks, + expires_at=expires_at, test_connection=test_connection) except external_access.ExternalAccessError as exc: _management_refusal(exc) _credential_audit("credential.added", session, "api_key", access=key["access"], @@ -1126,9 +1435,9 @@ def edit_key(key_id: str, body=Body(default=None), session: Session = Depends(re """Edit metadata and narrowing scope without ever reading or replacing the secret.""" if not isinstance(body, dict): raise err(400, "external_edit_empty", "Change at least one credential setting.") - allowed = {"label", "access", "databases", "expires_at"} + allowed = {"label", "access", "databases", "workbooks", "expires_at", "test_connection"} if not body or set(body) - allowed: - raise err(400, "external_edit_invalid", "Only label, access, databases, and expiry can be changed.") + raise err(400, "external_edit_invalid", "Only label, access, databases, workbooks, expiry, and test connection can be changed.") kwargs = {key: body[key] for key in allowed if key in body} try: key = external_access.edit(session.runtime, session.uname, session.tenant, key_id, **kwargs) @@ -1390,43 +1699,23 @@ def _maybe_session(request: Request, response: Response): _PAGE_STYLE = """ -body.oauth-page{margin:0;background:var(--lp-surface-2); -font-family:Inter,system-ui,-apple-system,Segoe UI,sans-serif;font-size:var(--lp-fs-sm); -color:var(--lp-ink);display:flex;justify-content:center;padding:48px 16px} -.oauth-card{background:var(--lp-surface);border:1px solid var(--lp-line); -border-radius:var(--lp-r-lg);max-width:460px;width:100%;padding:24px} -.oauth-card h1{font-size:var(--lp-fs-lg);font-weight:600;margin:0 0 8px} -.oauth-card p{line-height:var(--lp-lh);margin:0 0 16px;color:var(--lp-muted)} -.oauth-card .row{display:flex;gap:8px;justify-content:flex-end;margin-top:8px} -.oauth-card button{border:0;background:transparent;font:inherit;color:inherit; -border-radius:var(--lp-r-md);padding:8px 16px;cursor:pointer} -.oauth-card button:hover{background:var(--lp-surface-2)} -.oauth-card button.primary{background:var(--lp-primary);color:var(--lp-surface);font-weight:600} -.oauth-card button.primary:hover{background:var(--lp-primary-hover)} -.oauth-card button:focus-visible{outline:2px solid var(--lp-blue-deep);outline-offset:2px} +.oauth-card .row{display:flex;flex-wrap:wrap;gap:8px;justify-content:flex-end;margin-top:8px} .oauth-card .who{font-size:var(--lp-fs-xs);color:var(--lp-muted);margin:16px 0 0} """ def _page_stylesheets() -> str: - """Borrow the emitted app stylesheet, including its canonical tokens and Inter font.""" - index = Path(__file__).resolve().parents[1] / "web" / "dist" / "index.html" - try: - document = index.read_text(encoding="utf-8") - except OSError: - return "" - paths = re.findall(r']*\bhref=[\"\'](/assets/[^\"\']+\.css)[\"\']', document) - return "".join(f'' - for path in dict.fromkeys(paths)) + """Borrow the emitted app stylesheet after the signed-out fallback.""" + from routes_shared_artifact import _page_stylesheets as stylesheets + return stylesheets() def _page(title: str, body: str, status: int = 200): from fastapi.responses import HTMLResponse + from routes_shared_artifact import _document return HTMLResponse( - f"" - f"" - f"{_html.escape(title)}{_page_stylesheets()}" - f"
{body}
", status_code=status, + _document(title, body, page_class="oauth-page", card_class="oauth-card", + styles=_PAGE_STYLE, stylesheets=_page_stylesheets()), status_code=status, headers={"Cache-Control": "no-store", "X-Frame-Options": "DENY", "Content-Security-Policy": "frame-ancestors 'none'"}) @@ -1440,7 +1729,7 @@ def _login_bounce(): # The shell reads this key after a sign-in and comes back here (`Shell.tsx`, onSignedIn). return _page("Sign in to Loopable", ( "

Sign in to Loopable

Sign in first, then you will come straight back here.

" - "

Continue to sign in

" + "

Continue to sign in

" "")) @@ -1486,7 +1775,7 @@ def _consent_page(request: Request, session: Session, meta: dict, fields: dict): action = _html.escape(str(request.url.path)) return _page(f"Connect {meta['n']} to Loopable", ( f"

Connect {name} to Loopable

" - f"

Allow {name} to connect?

" + f"

{name} can read your data and make changes within your Loopable permissions.

" f"

Return to {host}.

" f"
" f"" @@ -1787,7 +2076,9 @@ def whoami(session: Session = Depends(require_external_analyst)): "access": access, "databases": (external_access.ALL_DATABASES if databases == external_access.ALL_DATABASES else list(databases)), - "write_scope": "Named tools only, as the key's maker with the maker's own grants.", + "workbooks": list(external_access.workbooks_of({ + "workbooks": session.claims.get("external_workbooks")})), + "write_scope": "Use the listed tools to make changes with your own permissions.", } @@ -1829,7 +2120,7 @@ def list_databases(session: Session = Depends(require_external_analyst)): public["reason"] = row.get("reason") or "" databases.append(public) return {"databases": databases, - "write_scope": "Named tools only, as the key's maker with the maker's own grants."} + "write_scope": "Use the listed tools to make changes with your own permissions."} @router.get("/databases/{database}/schema") @@ -1858,11 +2149,74 @@ def query_database( def _query_database(session: Session, database: str, payload: dict): + try: + return _query_database_page(session, database, payload) + except HTTPException as exc: + info = exc.detail.get("error", {}) if isinstance(exc.detail, dict) else {} + if exc.status_code == 503 and info.get("code") in { + "assistant_store_not_ready", "store_not_ready", "amazon_mirror_not_loaded"}: + raise err(503, "query_source_unavailable", + "This database is temporarily unavailable. Try the same query again shortly.") from exc + if info.get("code") == "query_cursor_stale": + info["message"] += " Repeat query_database with retry_query for a fresh first page." + info["retry_query"] = {"database": database, **copy.deepcopy(payload)} + info["retry_query"].pop("cursor", None) + raise + + +def _query_activity_page(session, payload, scoped, selected_keys, sorts, aggregates, groups, limit, cursor): + """Wrap the native continuation with the external query and credential binding.""" + import routes_tables + if sorts not in ([], [{"field": "occurred_at", "direction": "desc"}]): + raise err(400, "query_sorts_invalid", "Activity is ordered by occurred_at descending.") + if aggregates or groups: + raise err(409, "query_groups_unavailable", "Activity supports filtered event pages without aggregates or groups.") + digest = _json_digest({"database": "ut_activity", "query": {**payload, "cursor": None}, + "fields": scoped["fields"], "user": session.user, "claims": session.claims}) + if cursor is not None and (cursor["q"] != digest or cursor.get("i") is not None): + raise err(409, "query_cursor_stale", "The activity query or permissions changed. Start again without a cursor.") + predicates = _activity_predicates(payload.get("filters"), {f["key"] for f in scoped["fields"]}) + page = routes_tables.query_activity(session, **predicates, limit=limit, + cursor=cursor["s"] if cursor else None) + records = [] + for row in page["records"]: + obj = row.get("object") + # A hidden object field cannot prove this credential's source access. + if not isinstance(obj, dict): + if _key_scope(session)[1] != external_access.ALL_DATABASES: + continue + elif "database" in obj: + if not external_access.database_allowed(_key_scope(session)[1], obj["database"]): + continue + elif "app" in obj: + import routes_assets + databases = routes_assets._application_databases(session.runtime, obj["app"]) + if not databases or any(not external_access.database_allowed(_key_scope(session)[1], db) + for db in databases): + continue + records.append({"pid": row["pid"], **{key: copy.deepcopy(row[key]) for key in selected_keys if key in row}}) + offset = cursor["o"] if cursor else 0 + continuation = page.get("next_cursor") + next_cursor = (_encode_query_cursor(session, digest, continuation, offset + len(records)) + if continuation else None) + result = {**scoped, "fields": [f for f in scoped["fields"] if f["key"] in selected_keys], + "records": records, "sorts": [{"field": "occurred_at", "direction": "desc"}], + "aggregates": {}, "page": {"limit": limit, "returned": len(records), "offset": offset, + "has_more": next_cursor is not None, "next_cursor": next_cursor}, + "caps": {"max_page_size": _QUERY_MAX_LIMIT, "max_sorts": 1, "max_aggregates": 0}} + _assert_finite_query_value(result) + external_activity.record_ok(session, "ut_activity") + return result + + +def _query_database_page(session: Session, database: str, payload: dict): if not isinstance(payload, dict) or set(payload) - _QUERY_KEYS: raise err(400, "query_arguments_invalid", "Use only fields, filters, sorts, limit, cursor, aggregates, and groupBy.", {"allowed": sorted(_QUERY_KEYS)}) _assert_database_scope(session, database) + cursor = (_read_query_cursor(session, payload["cursor"]) + if payload.get("cursor") is not None else None) limit = payload.get("limit", _QUERY_DEFAULT_LIMIT) if type(limit) is not int or not 1 <= limit <= _QUERY_MAX_LIMIT: requested = limit @@ -1914,6 +2268,16 @@ def _query_database(session: Session, database: str, payload: dict): sorts.append({"field": rule["field"], "direction": rule["direction"]}) aggregates = _normalise_aggregates(payload.get("aggregates"), visible_keys) groups = _normalise_query_groups(payload.get("groupBy"), visible_keys) + if scoped.get("source_kind") == "native_activity": + return _query_activity_page(session, payload, scoped, selected_keys, sorts, aggregates, groups, limit, cursor) + publication = _query_publication(session, database) if mirror else None + if cursor is not None: + _assert_query_publication(cursor.get("i"), publication) + + def check_publication(): + if publication is not None: + _assert_query_publication(publication, _query_publication(session, database)) + if groups: if not aggregates or sorts: raise err(400, "query_groups_invalid", @@ -1931,7 +2295,7 @@ def _query_database(session: Session, database: str, payload: dict): "fields": visible_fields, "total_groups": summary["total_groups"]}) offset = (0 if payload.get("cursor") is None else - _decode_query_cursor(session, payload["cursor"], digest, snap)) + _decode_query_cursor(session, payload["cursor"], digest, snap, publication)) if offset > summary["total_groups"]: raise err(409, "query_cursor_stale", "The permitted result set changed. Start again without a cursor.") @@ -1946,7 +2310,8 @@ def _query_database(session: Session, database: str, payload: dict): "The permitted result set changed. Start again without a cursor.") returned = len(summary["groups"]) next_offset = offset + returned - next_cursor = (_encode_query_cursor(session, digest, snap, next_offset) + check_publication() + next_cursor = (_encode_query_cursor(session, digest, snap, next_offset, publication) if next_offset < summary["total_groups"] else None) result = {key: copy.deepcopy(value) for key, value in summary.items() if key not in {"server_aggregates", "records"}} @@ -2022,7 +2387,7 @@ def _query_database(session: Session, database: str, payload: dict): "total_rows": first.get("total_rows"), }) if offset is None: - offset = _decode_query_cursor(session, payload.get("cursor"), page_digest, snap) + offset = _decode_query_cursor(session, payload.get("cursor"), page_digest, snap, publication) total_rows = int(first.get("total_rows") or 0) if offset > total_rows: raise err(409, "query_cursor_stale", @@ -2046,7 +2411,8 @@ def _query_database(session: Session, database: str, payload: dict): **{key: copy.deepcopy(row.get(key)) for key in selected_keys}} for row in page_rows] next_offset = offset + limit - next_cursor = (_encode_query_cursor(session, page_digest, snap, next_offset) + check_publication() + next_cursor = (_encode_query_cursor(session, page_digest, snap, next_offset, publication) if next_offset < total_rows else None) result = { "database": page.get("database"), "label": page.get("label"), @@ -2098,7 +2464,7 @@ def _query_database(session: Session, database: str, payload: dict): }) offset = (0 if payload.get("cursor") is None else _decode_query_cursor(session, payload.get("cursor"), - query_digest, snapshot_digest)) + query_digest, snapshot_digest, publication)) if offset > len(rows): raise err(409, "query_cursor_stale", "The permitted result set changed. Start again without a cursor.") @@ -2109,7 +2475,8 @@ def _query_database(session: Session, database: str, payload: dict): for row in page_rows ] next_offset = offset + len(page_rows) - next_cursor = (_encode_query_cursor(session, query_digest, snapshot_digest, next_offset) + check_publication() + next_cursor = (_encode_query_cursor(session, query_digest, snapshot_digest, next_offset, publication) if next_offset < len(rows) else None) result = { "database": scoped.get("database"), @@ -2376,7 +2743,7 @@ def _view_event(session, kind, args): before = ctx.table.find_view(view_id, prefer_owner=session.uname) rerender = grid_events.handle_one(event, ctx) except grid_events.StoreUnavailable as exc: - raise err(503, "store_unavailable", f"View {view_id}: the tenant store is unavailable.") from exc + raise err(503, "store_unavailable", "The View is unavailable right now.") from exc if ctx.out.refusals: refusal = ctx.out.refusals[0] raise err(400, refusal.get("code", "view_refused"), @@ -2407,10 +2774,28 @@ def _view_event(session, kind, args): "draft": "personal", "shared": False} +def _trusted_activity_via(session): + """Resolve attribution from authenticated claims or the internal Assistant call path.""" + claims = session.claims or {} + credential = claims.get("external_credential_id") or claims.get("external_key_id") + kind = claims.get("external_auth_type") + if not any(claims.get(key) for key in ("external", "external_auth_type", "external_credential_id", + "external_key_id", "external_client_id")): + return "Assistant" + if not credential or kind not in (None, "api_key", "oauth"): + raise err(403, "no_agent_identity", "Reconnect this AI client before making changes.") + provider = external_oauth if kind == "oauth" else external_access + label = provider.label_for(session.runtime, credential) + if not isinstance(label, str) or not label.strip() or _contains_credential(label): + raise err(403, "no_agent_identity", "Reconnect this AI client before making changes.") + return label + + def _application_upsert(session, args): import application_registry as applications import routes_assets + attribution = {"via": _trusted_activity_via(session), "on_behalf_of": session.uname} for database in args.get("compatibleDatabases") or []: _assert_database_scope(session, database) if args.get("sourceDatabase") is not None: @@ -2420,7 +2805,7 @@ def _application_upsert(session, args): if "app_id" in args and not str(app_id or "").strip(): raise err(400, "bad_application", "app_id must name an App to update.") if not session.runtime.available(): - raise err(503, "store_unavailable", "The tenant store is unavailable. Nothing was saved.") + raise err(503, "store_unavailable", "The App could not be saved right now.") try: if not app_id: databases = payload.get("compatibleDatabases") or [] @@ -2429,7 +2814,7 @@ def _application_upsert(session, args): allowed, records = _application_access(session, databases, strict=True) return {"application": applications.create( session.runtime, session.tenant, session.uname, payload, - semantic_records=records, allowed_databases=allowed)} + semantic_records=records, allowed_databases=allowed, **attribution)} current = routes_assets._application_databases(session.runtime, app_id) allowed, _ = _application_access(session, current) if not current or not allowed: @@ -2440,7 +2825,28 @@ def _application_upsert(session, args): session.runtime, app_id, session.uname, session.admin, payload, semantic_records=records, allowed_databases=allowed | proposed_allowed, target_database=next((database for database in proposed - if database in proposed_allowed), None))} + if database in proposed_allowed), None), **attribution)} + except (applications.ApplicationError, PermissionError) as exc: + routes_assets._application_error(exc) + + +def _application_delete(session, args): + """Keep the App delete walls while passing authenticated attribution to its sole writer.""" + import application_registry as applications + import routes_assets + via = _trusted_activity_via(session) + app_id = args["app_id"] + try: + if routes_assets.finance_access(session, app_id): + allowed = set() + else: + current = routes_assets._application_databases(session.runtime, app_id) + allowed, _ = _application_access(session, current) + if not allowed: + raise applications.ApplicationError("application does not exist") + return applications.delete(session.runtime, app_id, session.uname, session.admin, + allowed_databases=allowed, confirm_name=args.get("confirmName"), + via=via, on_behalf_of=session.uname) except (applications.ApplicationError, PermissionError) as exc: routes_assets._application_error(exc) @@ -2543,21 +2949,21 @@ def _plan_database_write(session, args): database = str(args.get("database") or "").strip() if action not in {"record_create", "record_update", "record_delete", "field_create", "field_update", "field_delete"} or not database: - raise err(400, "tool_arguments_invalid", "Name a database and a published CRUD action.") + raise err(400, "tool_arguments_invalid", "Name a database and an action that changes records or fields.") _assert_database_scope(session, database) _assert_write_scope(session, "database_object") routes_tables._managed_or_refuse(session, database, mutation=True) bucket_before = session.runtime.get(user_tables.STORE_KEY) if not isinstance(bucket_before, dict): - raise err(503, "store_unavailable", "The database store is unavailable. Nothing was saved.") + raise err(503, "store_unavailable", "The database is unavailable. Nothing was saved.") table = copy.deepcopy(bucket_before.get(database) or {}) if not table or not user_tables.is_user_table(database, st=session.runtime): raise err(403, "connected_source_read_only", - "Connected and Odoo-backed database records are read only.") + "Records from connected sources are read only.") revision = _bucket_revision(session.runtime, user_tables.STORE_KEY, bucket_before) if type(revision.get("rev")) is not int: raise err(503, "confirmation_revision_unavailable", - "This deployment cannot revision-guard a database change.") + "The database version could not be checked. Nothing was saved.") warnings = [] bucket_after = copy.deepcopy(bucket_before) @@ -2597,8 +3003,7 @@ def _plan_database_write(session, args): # This is part of the UI row writer's durable result, not an optional callback. # Include newly encountered select values in the preview and the one guarded commit. user_tables._hydrate_choice_options(target.get("fields") or [], [after]) - changed, truncated = _diff_documents({user_tables.STORE_KEY: { - "before": bucket_before, "after": bucket_after}}) + changed, truncated = _diff_documents(_database_preview_documents(session, bucket_before, bucket_after)) if truncated: warnings.append("The preview diff reached its display cap; split this change.") return {"diff": changed, "affected": {"ids": [record_id], "count": 1}, @@ -2638,7 +3043,7 @@ def _plan_database_write(session, args): raw = args.get("field") if not isinstance(raw, dict) or "renames" in raw: raise err(400, "field_refused", - "External schema updates do not combine choice-value migrations.") + "Change a field's settings and rename its choices in separate steps.") merged = {**raw, "key": field_key} after = user_tables._clean_field( merged, before, recurrence_validator=recurrence_validator, @@ -2679,8 +3084,7 @@ def _plan_database_write(session, args): elif not user_tables.delete_field(database, field_key, st=preview): raise err(403, "field_refused", "That field cannot be removed.") bucket_after = preview.get(user_tables.STORE_KEY) - changed, truncated = _diff_documents({user_tables.STORE_KEY: { - "before": bucket_before, "after": bucket_after}}) + changed, truncated = _diff_documents(_database_preview_documents(session, bucket_before, bucket_after)) if truncated: warnings.append("The preview diff reached its display cap; split this change.") affected_ids = [field_key] @@ -2714,7 +3118,7 @@ def _execute_database_object(session, args, *, plan=None): replacement = copy.deepcopy(plan.get("bucket_after")) if type(expected_rev) is not int or not isinstance(replacement, dict): raise err(503, "confirmation_revision_unavailable", - "This deployment cannot revision-guard a database change.") + "The database version could not be checked. Nothing was saved.") def apply_exact(current): if _json_digest(current) != expected_digest: @@ -2727,8 +3131,10 @@ def _execute_database_object(session, args, *, plan=None): # One customer bucket, one guarded read-modify-write. The expected revision is checked # inside the PG lock where available; the closure's digest check also protects a backend # that can only provide the runtime's documented guarded fallback. - session.runtime.update( - user_tables.STORE_KEY, apply_exact, flush="sync", expect_rev=expected_rev) + user_tables.update_with_activity( + database, apply_exact, st=session.runtime, by=session.uname, + via=_trusted_activity_via(session), row_ids=None, field_keys=None, + flush="sync", expect_rev=expected_rev) except (view_audit.ViewRevisionStale, view_audit.RevisionUnverifiable) as exc: raise err(409, "confirmation_stale", "The database changed after preview. Preview the change again.") from exc @@ -2743,7 +3149,7 @@ def _sheet_compat_contract(): except (ImportError, ModuleNotFoundError): raise sheets.SheetRefusal( "tool_capability_unsupported", - "This deployment has not published the Sheet compatibility manifest.") + "These Sheet actions are not available yet.") manifest = None for name in ("capability_manifest", "get_capability_manifest", "CAPABILITY_MANIFEST", "CAPABILITIES"): @@ -2759,7 +3165,7 @@ def _sheet_compat_contract(): if manifest is None: raise sheets.SheetRefusal( "tool_capability_unsupported", - "This deployment has not published a readable Sheet compatibility manifest.") + "These Sheet actions are not available yet.") return module, manifest @@ -2799,12 +3205,14 @@ def _manifest_operation(manifest, object_name, action): return entry raise sheets.SheetRefusal( "tool_capability_unsupported", - f"The C5 capability manifest does not support {object_name}.{action}.") + f"The Sheet action {object_name}.{action} is not available yet.") def _invoke_compat(dispatcher, *, session, object_name, action, arguments, operations=None): supplied = { "session": session, "runtime": session.runtime, "actor": session.uname, + "by": session.uname, "via": _trusted_activity_via(session), + "on_behalf_of": session.uname, "username": session.uname, "object": object_name, "object_name": object_name, "action": action, "operation": f"{object_name}.{action}" if object_name else None, "arguments": copy.deepcopy(arguments), "operations": copy.deepcopy(operations), @@ -2824,7 +3232,7 @@ def _invoke_compat(dispatcher, *, session, object_name, action, arguments, opera except (TypeError, ValueError, KeyError, AttributeError) as exc: raise sheets.SheetRefusal( "tool_capability_unsupported", - "The published Sheet compatibility dispatcher does not implement this operation.") from exc + "This Sheet action is not available yet.") from exc def _sheet_object(session, args): @@ -2832,45 +3240,177 @@ def _sheet_object(session, args): action = str(args.get("action") or "").strip() module, manifest = _sheet_compat_contract() _manifest_operation(manifest, object_name, action) - dispatcher = next((getattr(module, name, None) for name in ( - "dispatch_object_operation", "dispatch_operation", "execute_operation", "dispatch") - if callable(getattr(module, name, None))), None) + dispatcher = _sheet_object_dispatcher(module) if dispatcher is None: raise sheets.SheetRefusal( "tool_capability_unsupported", - "The published Sheet capability has no object-operation dispatcher.") + "This Sheet action is not available yet.") return _invoke_compat( dispatcher, session=session, object_name=object_name, action=action, arguments={key: copy.deepcopy(value) for key, value in args.items() if key != "object"}) -def _validated_batch(session, args): - operations = args.get("operations") - if not isinstance(operations, list) or not operations: - raise err(400, "tool_arguments_invalid", "A validated batch needs at least one operation.") - module, manifest = _sheet_compat_contract() - normalised = [] - for item in operations: - if not isinstance(item, dict) or set(item) != {"name", "arguments"}: - raise err(400, "tool_arguments_invalid", "Every batch item needs name and arguments.") - name, arguments = item.get("name"), item.get("arguments") - if name not in external_tools._SHEET_OBJECT_ACTIONS or not isinstance(arguments, dict): - raise sheets.SheetRefusal( - "tool_capability_unsupported", "Validated batches contain only C5 object tools.") - object_name = name.removesuffix("_object") - action = str(arguments.get("action") or "") - _manifest_operation(manifest, object_name, action) - normalised.append({"name": name, "arguments": copy.deepcopy(arguments)}) - dispatcher = next((getattr(module, name, None) for name in ( - "dispatch_validated_batch", "execute_validated_batch", "dispatch_batch") +def _sheet_object_dispatcher(module): + """Inspect the native action door without executing an operation.""" + return next((getattr(module, name, None) for name in ( + "dispatch_object_operation", "dispatch_operation", "execute_operation", "dispatch") if callable(getattr(module, name, None))), None) + + +_BATCH_SHEET_TOOLS = frozenset({ + "sheet_create_workbook", "sheet_add_tab", "sheet_delete_tab", "sheet_read_cells", + "sheet_write_cells", "sheet_set_binding", "sheet_set_styles", "sheet_set_dimensions", + "sheet_set_validation", "sheet_set_freeze", "sheet_add_rule", "sheet_set_chart", "sheet_structure", +}) +_BATCH_COMPAT_OPERATIONS = { + ("range_object", "read"): "range.values.read", + ("range_object", "write_values"): "range.values.write", + ("range_object", "write_formulas"): "range.formulas.write", + ("range_object", "write_styles"): "range.styles.write", + ("range_object", "number_format"): "range.number_formats.write", + ("range_object", "fill_down"): "range.fill_down", + ("range_object", "clear"): "range.clear_contents", + ("worksheet_object", "geometry"): "worksheet.geometry.write", + ("worksheet_object", "hidden_bands"): "worksheet.hidden.write", + ("worksheet_object", "freeze"): "worksheet.freeze.write", + ("worksheet_object", "gridlines"): "worksheet.gridlines.write", + ("workbook_object", "named_ranges"): "workbook.names.write", +} +_BATCH_COMPAT_FIELDS = { + "range.values.read": {}, + "range.values.write": {"values": {}, "figure_sources": external_tools._FIGURE_SOURCES}, + "range.formulas.write": {"values": {}, "mode": {"enum": ["a1", "r1c1"]}}, + "range.styles.write": {"values": {}}, + "range.number_formats.write": {"values": {}}, + "range.fill_down": {}, "range.clear_contents": {}, + "worksheet.geometry.write": {"column_width": {"type": "number"}, "row_height": {"type": "number"}}, + "worksheet.hidden.write": {"axis": {"enum": ["rows", "columns"]}, "hidden": {"type": "boolean"}}, + "worksheet.freeze.write": {"rows": {"type": "integer"}, "cols": {"type": "integer"}}, + "worksheet.gridlines.write": {"shown": {"type": "boolean"}}, + "workbook.names.write": {"name": {"type": "string"}, "refers_to": {"type": "string"}}, +} + + +def _batch_sheet_operation(ctx, name, args): + """Use native permissions and writers on a private workbook copy.""" + from core import sheet_compat + + if name not in _BATCH_SHEET_TOOLS and name not in external_tools._SHEET_OBJECT_ACTIONS: + raise sheets.SheetRefusal("tool_capability_unsupported", "A batch can contain only the listed Sheet actions.") + external_tools.validate_arguments(args, external_tools.TOOLS[name]["inputSchema"]) + ctx.session.require("sheets") + action = args.get("action") + nested = copy.deepcopy(args.get("arguments") or {}) + if name == "workbook_object" and action == "create": + return external_tools.dispatch(ctx, "sheet_create_workbook", nested) + if name == "sheet_create_workbook": + return external_tools.dispatch(ctx, name, args) + + writing = external_tools.is_write(name, args) + book = external_tools._book(ctx, args, write=writing) + original = ctx.session.runtime._initial[sheets.workbook_key(book["id"])] or {} + revision_key = "rev" if name in _BATCH_SHEET_TOOLS else "revision" + if revision_key in args: + if args[revision_key] != int(original.get("rev") or 0): + raise sheets.SheetStaleRefusal( + "workbook_revision_stale", "The workbook changed. Preview the batch again.", rev_current=book["rev"]) + args[revision_key] = book["rev"] + if name in _BATCH_SHEET_TOOLS: + return external_tools.dispatch(ctx, name, args) + + target = {"workbook_id": book["id"], "rev": book["rev"]} + if name == "worksheet_object" and action in {"add", "delete"}: + if action == "delete": + target["tab"] = args.get("worksheet", "") + native = "sheet_add_tab" if action == "add" else "sheet_delete_tab" + # Validate the nested payload separately so it cannot replace the permitted target. + properties = {"name": {"type": "string"}} if action == "add" else {} + external_tools.validate_arguments(nested, {"type": "object", "properties": properties, + "required": list(properties), "additionalProperties": False}) + return external_tools.dispatch(ctx, native, {**target, **nested}) + if name in {"workbook_object", "worksheet_object"} and action in {"get", "list"}: + external_tools.validate_arguments(nested, {"type": "object", "additionalProperties": False}) + projected = ctx.project_book(book) + if name == "workbook_object": + return {"workbook": projected} + return ({"tabs": [{"id": tab["id"], "name": tab["name"]} for tab in projected["sheets"]]} + if action == "list" else {"tab": sheets.find_tab(projected, args.get("worksheet"))}) + + operation = _BATCH_COMPAT_OPERATIONS.get((name, action)) + if operation is None: + raise sheets.SheetRefusal("tool_capability_unsupported", "That Sheet action is not available in a batch.") + fields = _BATCH_COMPAT_FIELDS[operation] + required = (["values"] if "values" in fields else ["name", "refers_to"] + if operation == "workbook.names.write" else ["shown"] + if operation == "worksheet.gridlines.write" else ["hidden"] + if operation == "worksheet.hidden.write" else []) + external_tools.validate_arguments(nested, {"type": "object", "properties": fields, + "required": required, "additionalProperties": False}) + address = args.get("range") + if isinstance(address, dict): + address = sheet_compat._range_text(tuple(address[key] + 1 for key in ("row0", "col0", "row1", "col1"))) + planned = {**nested, "sheet": args.get("worksheet"), "range": address, "expected_revision": book["rev"]} + operation_runtime = ctx.session.runtime + if not writing: + # A reader's projected cells must never replace the workbook being staged for a write. + operation_runtime = _PreviewRuntime(ctx.session.runtime) + operation_runtime.put(sheets.workbook_key(book["id"]), ctx.project_book(book)) + result = sheet_compat.execute(operation_runtime, book["id"], operation, planned, + actor=ctx.session.uname, actor_name=ctx.actor_name) + if operation == "range.values.write": + addresses = sheet_compat._addresses(sheet_compat._range(address)) + values = sheet_compat._matrix(nested["values"], len(addresses), len(addresses[0]), "Values") + hints = external_tools._cell_figure_hints(ctx, { + "tab": args.get("worksheet"), "figure_sources": nested.get("figure_sources") or {}, + "cells": {addr: {"kind": "literal", "value": values[row][col]} + for row, line in enumerate(addresses) for col, addr in enumerate(line)}, + }, book) + if hints: + result["warnings"] = hints + return result + + +def _validated_batch(session, args): + module, _manifest = _sheet_compat_contract() + dispatcher = getattr(module, "dispatch_validated_batch", None) if dispatcher is None: raise sheets.SheetRefusal( "tool_capability_unsupported", - "The C5 manifest does not publish an atomic validated-batch dispatcher.") - return _invoke_compat( - dispatcher, session=session, object_name="", action="", arguments=args, - operations=normalised) + "Changing these Sheet items together is not available yet.") + staging = _PreviewRuntime(session.runtime) + staged_session = Session(session.tenant, copy.deepcopy(session.user), copy.deepcopy(session.claims), staging) + ctx = _tool_context(staged_session) + + def dispatch(_staging, name, arguments): + try: + return _batch_sheet_operation(ctx, name, arguments) + except sheets.SheetRefusal as exc: + code = _mcp_public_code(exc.code) + raise sheets.SheetRefusal(code, _mcp_plain(exc.message, MCP_RESULT_CODES[code])) from exc + except HTTPException as exc: + detail = exc.detail if isinstance(exc.detail, dict) else {} + error = detail.get("error", detail) + code = _mcp_public_code(error.get("code"), exc.status_code) + raise sheets.SheetRefusal(code, MCP_RESULT_CODES[code]) from exc + + return dispatcher(runtime=session.runtime, operations=args.get("operations"), staging=staging, + dispatch=dispatch, actor=session.uname, actor_name=ctx.actor_name) + + +def _assert_tool_database_scope(session, name, arguments): + """Keep batch refusal positions without weakening the connection's database scope.""" + if name == "validated_batch" and isinstance(arguments, dict) and isinstance(arguments.get("operations"), list): + for position, item in enumerate(arguments["operations"], 1): + try: + for database in _databases_in_arguments(item): + _assert_database_scope(session, database) + except HTTPException as exc: + info = exc.detail.get("error", {}) if isinstance(exc.detail, dict) else {} + code = _mcp_public_code(info.get("code"), exc.status_code) + raise err(exc.status_code, code, f"Operation {position}: {MCP_RESULT_CODES[code]} Nothing was changed.") from exc + return + for database in _databases_in_arguments(arguments): + _assert_database_scope(session, database) def _tool_context(session: Session, *, preview=False) -> external_tools.ToolContext: @@ -2882,6 +3422,23 @@ def _tool_context(session: Session, *, preview=False) -> external_tools.ToolCont def project(book): served = routes_sheet._read_for(session, book) + if _key_scope(session)[0] == external_access.ACCESS_REFRESH: + from core import sheet_binding + from tool_groups.sheet import refresh_sources + refresh_sources(session, book) + served = copy.deepcopy(served) + cache = sheet_binding.read_refresh_cache(session.runtime, book["id"]) + for tab in served.get("sheets", []): + for addr, cell in tab.get("cells", {}).items(): + if cell.get("kind") != "bound": + continue + binding = cell.get("binding") or {} + slot = routes_sheet._binding_scope_key(session, binding.get("database"), binding) + key = str(tab["id"]) + "!" + addr + if not (cache.get("refreshCells", {}).get(key, {}).get(slot) + or cache.get("cells", {}).get(key, {}).get(slot)): + cell.update(value=None, display="", state="refused", refusal={ + "code": "sheet_refresh_required", "message": "Refresh this workbook with this connection first."}) databases = _key_scope(session)[1] if databases != external_access.ALL_DATABASES: # The owner projection can share cells with its input; key scope is response-only. @@ -2907,9 +3464,7 @@ def _tool_context(session: Session, *, preview=False) -> external_tools.ToolCont # Same best-effort cache fill as the UI's compute_cell. A fresh value must replace # this scope's old slot before an editor's read projection can use that slot. try: - sheets.fill_scope_cache(session.runtime, workbook_id, tab + "!" + addr, - routes_sheet._binding_scope_key(session, resolved["database"], binding), - resolved["value"], routes_sheet._now_iso(), resolved["database"]) + routes_sheet.cache_resolved_binding(session, workbook_id, tab, addr, binding, resolved) except Exception: pass @@ -2924,10 +3479,18 @@ def _tool_context(session: Session, *, preview=False) -> external_tools.ToolCont actor_name = f"{maker} via {attribution_kind} {label}" if _contains_credential(actor_name): raise sheets.SheetRefusal("credential_in_attribution", "Maker names and key labels must not contain credential values.") + def reader(book): + _assert_workbook_scope(session, book.get("id")) + routes_sheet._require_reader(session, book) + + def editor(book): + _assert_workbook_scope(session, book.get("id")) + routes_sheet._require_editor(session, book) + return external_tools.ToolContext( session=session, actor_name=actor_name, - require_reader=lambda book: routes_sheet._require_reader(session, book), - require_editor=lambda book: routes_sheet._require_editor(session, book), + require_reader=reader, + require_editor=editor, project_book=project, resolve_binding=resolve_binding, cache_binding=cache_binding, @@ -2937,9 +3500,8 @@ def _tool_context(session: Session, *, preview=False) -> external_tools.ToolCont view_event=lambda kind, args: _view_event(session, kind, args), view_share_preview=lambda args: _view_share_preview(session, args), app_upsert=lambda args: _application_upsert(session, args), - # Reuse the UI's atomic NameConfirmedDelete wrapper as well as the registry delete. - app_delete=lambda args: routes_assets.delete_application( - args["app_id"], {"confirmName": args["confirmName"]}, session), + # The registry delete checks confirmName atomically. + app_delete=lambda args: _application_delete(session, args), database_object=lambda args: (_plan_database_write(session, args) if preview and external_tools.is_write( "database_object", args) @@ -2951,6 +3513,10 @@ def _tool_context(session: Session, *, preview=False) -> external_tools.ToolCont def _strong_confirmation_required(name, args): + if name not in external_tools.TOOLS: + import tool_groups + resolved = tool_groups.resolve(name, args) + return bool(resolved and resolved[0]["destructive"]) if name == "database_object": return args.get("action") in {"record_delete", "field_create", "field_update", "field_delete"} if name in {"view_delete", "app_delete", "sheet_delete_tab"}: @@ -2985,17 +3551,35 @@ def _affected_for(name, args, diff, result=None): value = result.get(key) if value is not None and str(value) not in values: values.append(str(value)) - return {"ids": values[:100], "count": max(len(values), len(diff))} + app_id = (result.get("application") or {}).get("id") + if app_id and str(app_id) not in values: + values.append(str(app_id)) + ranges = [] + def collect(arguments): + for item in arguments.get("operations") or []: + collect(item.get("arguments") or {}) + addresses = set() + for key in ("cells", "styles", "validations"): + addresses.update((arguments.get(key) or {}).keys()) + if arguments.get("addr"): + addresses.add(arguments["addr"]) + if arguments.get("range"): + addresses.add(str(arguments["range"])) + for address in sorted(addresses): + ranges.append({"workbook_id": arguments.get("workbook_id"), + "tab": arguments.get("tab") or arguments.get("worksheet"), "range": address}) + collect(args) + return {"ids": values[:100], "count": max(len(values), len(diff)), "ranges": ranges} def _preview_external_write(session, name, arguments, *, issue_token=True, execution=None): from core import write_execution - if not external_tools.is_write(name, arguments): + if not _external_is_write(name, arguments): raise err(400, "confirmation_not_write", "Only a write operation can be previewed.") - _assert_write_scope(session, name) + _assert_write_scope(session, name, arguments) + environment = _write_environment() normalised = json.loads(_canonical_json(arguments).decode("utf-8")) - for database in _databases_in_arguments(normalised): - _assert_database_scope(session, database) + _assert_tool_database_scope(session, name, normalised) preview_runtime = _PreviewRuntime(session.runtime) preview_session = Session( @@ -3003,10 +3587,10 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu claims=copy.deepcopy(session.claims), runtime=preview_runtime) execution = execution or {'seed': uuid.uuid4().hex, 'timestamp': time.time()} with write_execution.replay(execution): - result = external_tools.dispatch(_tool_context(preview_session, preview=True), name, normalised) + result = _dispatch_external_tool(_tool_context(preview_session, preview=True), name, normalised) if isinstance(result, dict) and result.get("refused"): raise err(409, "write_partial_refused", - "The writer refused part of this change; nothing was previewed.") + "Part of this change could not be accepted. Nothing was previewed.") plan = result if name == "database_object" else None if plan is not None: @@ -3016,7 +3600,11 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu current_revision = copy.deepcopy(plan.get("revision") or {}) else: documents = preview_runtime.changed() - diff, truncated = _diff_documents(documents) + if name == "requests" and normalised.get("action") in {"answer", "complete"}: + projected = _request_preview_documents(session, normalised["arguments"]["id"], documents) + else: + projected = _public_preview_documents(session, documents) + diff, truncated = _diff_documents(projected) warnings = (["The preview diff reached its display cap; split this change."] if truncated else []) affected = _affected_for(name, normalised, diff, result) @@ -3029,7 +3617,10 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu if any("display cap" in warning for warning in warnings): raise err(413, "confirmation_too_large", "The complete diff does not fit in one confirmation. Split the change.") + if isinstance(result, dict): + warnings.extend(warning for warning in (result.get("warnings") or []) if warning not in warnings) + _canonical_json(diff) diff_digest = _json_digest(diff) revision_digest = _json_digest(current_revision) expires_at = int(time.time()) + _CONFIRMATION_TTL_SECONDS @@ -3039,14 +3630,21 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu "authentication": session.claims.get("external_auth_type", "api_key"), "tool": name, "arguments": normalised, "arguments_digest": _json_digest(normalised), + "environment": environment, "revision_digest": revision_digest, "diff_digest": diff_digest, "expiry": expires_at, "nonce": uuid.uuid4().hex, "strong": _strong_confirmation_required(name, normalised), "affected_count": int(affected.get("count") or 0), "execution": execution, } + payload["operation_id"] = hashlib.sha256(payload["nonce"].encode("utf-8")).hexdigest() + if (name == "sheet" and normalised.get("action") == "refresh_scope" + and _key_scope(session)[0] == external_access.ACCESS_REFRESH): + payload["refresh_authority"] = _refresh_authority(session) response = { + "operation_id": payload["operation_id"], "state": "not_committed", "preview": True, "mutated": False, "tool": name, + "environment": environment, "diff": diff, "diff_digest": diff_digest, "affected": affected, "warnings": warnings, "current_revision": current_revision, @@ -3057,91 +3655,224 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu response["confirmation_phrase"] = _CONFIRMATION_PHRASE if issue_token: response["confirmation_token"] = _confirmation_token(payload) + _store_operation(session, payload, response, preview_runtime) response["_confirmation"] = payload response["_plan"] = plan return response -def _confirmation_claim(session, payload): - nonce = str(payload.get("nonce") or "") - if not nonce: - raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") - nonce_key = hashlib.sha256(nonce.encode("utf-8")).hexdigest() +def _operation_bindings(session): + return {"tenant": session.tenant, "actor": session.uname, + "credential": _credential_binding(session), + "authentication": session.claims.get("external_auth_type", "api_key")} - def claim(raw): - doc = raw if isinstance(raw, dict) else {} - claims = doc.get("claims") if isinstance(doc.get("claims"), dict) else {} - now = int(time.time()) - claims = {key: value for key, value in claims.items() - if isinstance(value, dict) and int(value.get("expiry") or 0) >= now - 3600} - if nonce_key in claims: - raise err(409, "confirmation_replayed", - "This confirmation token has already been used.") - claims[nonce_key] = { - "status": "claimed", "expiry": int(payload["expiry"]), - "tool": str(payload["tool"]), "actor_digest": _json_digest(payload["actor"]), - "diff_digest": str(payload["diff_digest"]), - } - doc["claims"] = claims + +def _refresh_authority(session): + """Bind a refresh preview to its account and connection permissions.""" + return _json_digest([session.user, _key_scope(session), + session.claims.get("external_workbooks", [])]) + + +def _prune_operations(raw): + doc = raw if isinstance(raw, dict) else {} + now = time.time() + doc["claims"] = {key: value for key, value in (doc.get("claims") or {}).items() + if isinstance(value, dict) and + float(value.get("retain_until", value.get("expiry", 0))) >= now} + return doc + + +def _store_operation(session, payload, preview, staged): + """Keep the preview identity outside every affected object's revision.""" + operation_id = payload["operation_id"] + access = { + "user": _json_digest(session.user), + "workbooks": [key for key in staged._docs if key.startswith(sheets.WORKBOOK_KEY_PREFIX)], + "databases": _databases_in_arguments(payload["arguments"]), + "documents": {}, + } + if payload["tool"] in {"app_upsert", "app_delete"}: + import application_registry as applications + app_id = payload["arguments"].get("app_id") or next(iter(preview["affected"].get("ids") or []), None) + access["app_id"] = app_id + for doc in (staged._initial.get(applications._KEY), staged._docs.get(applications._KEY)): + app = ((doc or {}).get("applications") or {}).get(app_id) or {} + access["databases"].extend(_databases_in_arguments(app)) + # Foreign handlers own their object permissions. Pin their consulted documents without calling them on replay. + if payload["tool"] not in external_tools.TOOLS: + access["documents"] = {key: _json_digest(value) for key, value in staged._initial.items() + if key not in {external_access.BUCKET, external_oauth.BUCKET}} + access["after_documents"] = {key: _json_digest(staged._docs[key]) for key in access["documents"]} + item = {"payload": copy.deepcopy(payload), "access": access, "status": "preview", + "retain_until": time.time() + _OPERATION_RETENTION_SECONDS, + "affected": copy.deepcopy(preview["affected"])} + def save(raw): + doc = _prune_operations(raw) + if operation_id in doc["claims"]: + raise err(409, "confirmation_stale", "Preview the change again.") + doc["claims"][operation_id] = item return doc + session.runtime.update(_CONFIRMATION_BUCKET, save, flush="sync") + + +def _operation_access(session, item, *, confirming=False): + """Check today's permissions without invoking a confirmed writer.""" + payload, access = item["payload"], item["access"] + if any(payload.get(key) != value for key, value in _operation_bindings(session).items()): + raise err(404, "operation_unavailable", "That operation is not available to this connection.") + user = external_access.resolve_active_user(session.uname, session.tenant) + session = Session(session.tenant, user, copy.deepcopy(session.claims), session.runtime) + require_external_analyst(session) + ctx = _tool_context(session) + name, args = payload["tool"], payload["arguments"] + _assert_tool_database_scope(session, name, args) + if "refresh_authority" in payload: + _assert_write_scope(session, name, args) + if payload["refresh_authority"] != _refresh_authority(session): + raise err(409, "confirmation_stale", "The connection or account permissions changed. Preview the refresh again.") + if name in external_tools.TOOLS: + grants = external_tools.TOOLS[name]["grants"] + receipt_access = None + else: + import tool_groups + entry, action_args = tool_groups.resolve(name, args) + grants = tool_groups.action_grants(entry, name) + receipt_access = entry.get("receipt_access") + for grant in grants: + session.require(grant) + if item["status"] == "preview" and confirming: + if session.claims.get("external_access") == external_access.ACCESS_REFRESH: + from tool_groups.sheet import refresh_access + refresh_access(ctx, action_args) + return session + for key in access["workbooks"]: + book = session.runtime.get(key, fresh=True) + if book: + ctx.require_reader(book) + elif item["status"] == "committed": + raise err(404, "operation_unavailable", "That operation's workbook is no longer available.") + for database in set(access["databases"]): + _assert_database_scope(session, database) + _external_read_scope(session, database, fields=[]) + if name == "database_object": + import routes_tables + g = routes_tables.ut_write_ctx(session, args["database"]) + action = args["action"] + if action in {"record_create", "record_update"} and item["status"] == "committed": + if any(int(rid) not in g["pids"] for rid in item["affected"]["ids"]): + raise err(403, "operation_unavailable", "That operation's records are no longer available.") + fields = set(args.get("values") or {}) + if args.get("field_key") and action != "field_delete": + fields.add(args["field_key"]) + if not fields <= {field["key"] for field in g["fields"]}: + raise err(403, "operation_unavailable", "That operation's fields are no longer available.") + if name in {"view_upsert", "view_delete", "view_object"}: + view_id = args.get("view_id") or (args.get("view") or {}).get("id") + ctx_view = _view_context(session, args["database"], {}) + found = ctx_view.table.find_view(view_id, prefer_owner=session.uname) + deleting = name == "view_delete" or args.get("action") == "delete" + if (found and str(found[0]).strip().lower() != session.uname.lower()) or (not found and not deleting): + raise err(403, "operation_unavailable", "That operation's View is no longer available.") + if name in {"app_upsert", "app_delete"}: + import application_registry as applications + import routes_assets + app_id = access["app_id"] + databases = set(access["databases"]) | set(routes_assets._application_databases(session.runtime, app_id)) + for database in databases: + _assert_database_scope(session, database) + allowed, _ = _application_access(session, list(databases), strict=True) + visible = applications.list_apps(session.runtime, session.uname, session.admin, allowed_databases=allowed) + if name != "app_delete" and app_id not in {app["id"] for app in visible}: + raise err(403, "operation_unavailable", "That operation's App is no longer available.") + if receipt_access is not None: + read_session = Session(session.tenant, user, session.claims, _ReceiptRuntime(session.runtime)) + if receipt_access(_tool_context(read_session), copy.deepcopy(action_args)) is not True: + raise err(403, "operation_unavailable", "That operation is not available with your current access.") + return session + if access["documents"] and _json_digest(user) != access["user"]: + raise err(403, "operation_unavailable", "That operation is not available with your current access.") + for key, digest in access["documents"].items(): + if _json_digest(session.runtime.get(key, fresh=True)) != digest: + raise err(403, "operation_unavailable", "That operation's access has changed. Read the item again.") + return session + + +def _load_operation(session, operation_id, *, confirming=False): + doc = session.runtime.get(_CONFIRMATION_BUCKET, fresh=True) + item = (doc.get("claims") or {}).get(operation_id) if isinstance(doc, dict) else None + if (not isinstance(item, dict) or "payload" not in item + or item.get("retain_until", 0) < time.time()): + raise err(404, "operation_unavailable", "That operation is not available to this connection.") + return _operation_access(session, item, confirming=confirming), item + + +def _operation_result(operation_id, item): + if item.get("status") == "committed": + return copy.deepcopy(item["result"]) + pending = item.get("status") == "claimed" + return {"operation_id": operation_id, "state": "not_committed", "confirmed": False, + "applied": False, "revision_after": None, "affected": {}, "retry": pending, + "reason": "The change is still being saved. Ask again shortly." if pending + else "This change has not been committed."} + +def _operation_status(session, args): + """Read a retained result without changing any object or operation revision.""" + _, item = _load_operation(session, args["operation_id"]) + return _operation_result(args["operation_id"], item) + + +def _confirmation_claim(session, operation_id): + def claim(raw): + item = raw["claims"][operation_id] + if item["status"] != "preview": + raise _OperationAlreadyClaimed() + if item["payload"]["expiry"] <= time.time(): + raise err(409, "confirmation_expired", "This confirmation expired. Preview the change again.") + item["status"] = "claimed" + item["retain_until"] = time.time() + _OPERATION_RETENTION_SECONDS + return raw session.runtime.update(_CONFIRMATION_BUCKET, claim, flush="sync") - return nonce_key -def _confirmation_already_used(session, payload): - nonce = str(payload.get("nonce") or "") - if not nonce: - raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") - nonce_key = hashlib.sha256(nonce.encode("utf-8")).hexdigest() - doc = session.runtime.get(_CONFIRMATION_BUCKET) - claims = doc.get("claims") if isinstance(doc, dict) and isinstance(doc.get("claims"), dict) else {} - if nonce_key in claims: - raise err(409, "confirmation_replayed", "This confirmation token has already been used.") +class _OperationAlreadyClaimed(Exception): + pass -def _confirmation_status(session, nonce_key, status): +def _confirmation_status(session, operation_id, status, result=None): def mark(raw): - doc = raw if isinstance(raw, dict) else {} - claims = doc.get("claims") if isinstance(doc.get("claims"), dict) else {} - item = claims.get(nonce_key) - if isinstance(item, dict): - claims[nonce_key] = {**item, "status": status} - doc["claims"] = claims - return doc - try: - session.runtime.update(_CONFIRMATION_BUCKET, mark, flush="sync") - except Exception: - pass + item = raw["claims"][operation_id] + item["status"] = status + item["retain_until"] = time.time() + _OPERATION_RETENTION_SECONDS + if result is not None: + item["result"] = copy.deepcopy(result) + item["access"]["documents"] = item["access"].pop("after_documents", {}) + return raw + session.runtime.update(_CONFIRMATION_BUCKET, mark, flush="sync") def _confirm_change(session, args): from core import view_audit, write_execution payload = _read_confirmation_token(args.get("confirmation_token")) - now = int(time.time()) - if int(payload.get("expiry") or 0) <= now: + if any(payload.get(key) != value for key, value in _operation_bindings(session).items()): + raise err(403, "confirmation_principal_changed", + "This confirmation belongs to another account or connection.") + operation_id = payload.get("operation_id", "") + fresh_session, stored = _load_operation(session, operation_id, confirming=True) + if stored["payload"] != payload: + raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") + if stored["status"] != "preview": + return _operation_result(operation_id, stored) + _assert_write_scope(fresh_session, payload.get("tool"), payload.get("arguments")) + if payload.get("environment") != _write_environment(): + raise err(409, "confirmation_stale", "The environment changed. Preview the change again.") + if int(payload.get("expiry") or 0) <= int(time.time()): raise err(409, "confirmation_expired", "This confirmation token expired. Preview the change again.") - bindings = { - "tenant": session.tenant, "actor": session.uname, - "credential": _credential_binding(session), - "authentication": session.claims.get("external_auth_type", "api_key"), - } - if any(payload.get(key) != value for key, value in bindings.items()): - raise err(403, "confirmation_principal_changed", - "This confirmation belongs to another principal or credential.") if payload.get("strong") and args.get("confirmation_phrase") != _CONFIRMATION_PHRASE: raise err(400, "confirmation_phrase_required", "Enter the exact stronger confirmation phrase shown in the preview.") - _confirmation_already_used(session, payload) - - # Freshly resolve the account, AI apps grant, credential revocation/label, credential scope, - # database walls and writer semantics before claiming the nonce or touching customer state. - fresh_user = external_access.resolve_active_user(session.uname, session.tenant) - fresh_session = Session(session.tenant, fresh_user, copy.deepcopy(session.claims), session.runtime) - require_external_analyst(fresh_session) - _tool_context(fresh_session) # credential label lookup is the live revocation check tool, arguments = payload.get("tool"), payload.get("arguments") if not isinstance(tool, str) or tool == "confirm_change" or not isinstance(arguments, dict): raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") @@ -3149,18 +3880,21 @@ def _confirm_change(session, args): if (not isinstance(execution, dict) or not isinstance(execution.get('seed'), str) or not execution['seed'] or type(execution.get('timestamp')) not in (int, float)): raise err(409, 'confirmation_stale', - 'This preview predates the current writer. Preview the change again.') - recomputed = _preview_external_write( - fresh_session, tool, arguments, issue_token=False, execution=execution) - current = recomputed["_confirmation"] - if (payload.get("arguments_digest") != current.get("arguments_digest") - or payload.get("revision_digest") != current.get("revision_digest") - or payload.get("diff_digest") != current.get("diff_digest")): - raise err(409, "confirmation_stale", - "The data, permissions, or resulting diff changed. Preview the change again.") - - nonce_key = _confirmation_claim(fresh_session, payload) + 'This preview is no longer current. Preview the change again.') + try: + _confirmation_claim(fresh_session, operation_id) + except _OperationAlreadyClaimed: + return _operation_status(fresh_session, {"operation_id": operation_id}) try: + recomputed = _preview_external_write( + fresh_session, tool, arguments, issue_token=False, execution=execution) + current = recomputed["_confirmation"] + if (payload.get("arguments_digest") != current.get("arguments_digest") + or payload.get("environment") != current.get("environment") + or payload.get("revision_digest") != current.get("revision_digest") + or payload.get("diff_digest") != current.get("diff_digest")): + raise err(409, "confirmation_stale", + "The data, permissions, or resulting diff changed. Preview the change again.") if tool == "database_object": result = _execute_database_object( fresh_session, arguments, plan=recomputed.get("_plan")) @@ -3170,31 +3904,28 @@ def _confirm_change(session, args): _ConfirmationRuntime( fresh_session.runtime, recomputed.get("current_revision"))) with write_execution.replay(execution): - result = external_tools.dispatch(_tool_context(guarded_session), tool, arguments) + result = _dispatch_external_tool(_tool_context(guarded_session), tool, arguments) if isinstance(result, dict) and result.get("refused"): raise err(409, "write_partial_refused", - "The writer refused part of the confirmed change.") + "Part of the confirmed change could not be accepted.") except (view_audit.ViewRevisionStale, view_audit.RevisionUnverifiable) as exc: - _confirmation_status(fresh_session, nonce_key, "failed") + _confirmation_status(fresh_session, operation_id, "failed") raise err(409, "confirmation_stale", "The data changed while confirmation was committing. Preview it again.") from exc except Exception: - _confirmation_status(fresh_session, nonce_key, "failed") + _confirmation_status(fresh_session, operation_id, "failed") raise - _confirmation_status(fresh_session, nonce_key, "committed") before_revision = copy.deepcopy(recomputed.get("current_revision") or {}) if tool == "database_object": from core import user_tables after_revision = _bucket_revision( fresh_session.runtime, user_tables.STORE_KEY, fresh_session.runtime.get(user_tables.STORE_KEY)) + produced_rev = before_revision["rev"] + 1 + if after_revision.get("rev") != produced_rev: + after_revision = {"rev": produced_rev} else: - after_revision = {} - for key in before_revision if isinstance(before_revision, dict) else (): - try: - after_revision[key] = copy.deepcopy(fresh_session.runtime.revision(key)) - except Exception: - after_revision[key] = None + after_revision = copy.deepcopy(guarded_session.runtime._expected) after_revision_digest = _json_digest(after_revision) receipt = audit.external_write_receipt( fresh_session.tenant, fresh_session.uname, tool=tool, @@ -3202,39 +3933,375 @@ def _confirm_change(session, args): affected_count=payload.get("affected_count"), diff_digest=payload.get("diff_digest"), revision_before=payload.get("revision_digest"), revision_after=after_revision_digest, - confirmation_id=nonce_key) - return { + confirmation_id=operation_id) + response = { + "operation_id": operation_id, "state": "committed", "confirmed": True, "applied": True, "tool": tool, "affected": copy.deepcopy(recomputed.get("affected") or {}), "revision_before": before_revision, "revision_after": after_revision, "audit_receipt": receipt, } + _confirmation_status(fresh_session, operation_id, "committed", response) + return response + + +# Codes are public identifiers. Reasons are product copy, never exception diagnostics. +_MCP_CODE_GROUPS = ( + ("The arguments do not match this action. Read its guide and correct them.", """ + tool_arguments_invalid query_arguments_invalid query_aggregates_invalid query_aggregate_type + query_groups_invalid query_limit_invalid query_sorts_invalid query_value_invalid + bad_application bad_entries bad_value bad_values bad_request bad_recurrence invalid_field_contract + assistant_unknown_field + external_edit_empty external_edit_invalid oauth_edit_empty oauth_edit_invalid + """), + ("You do not have permission to do this with this connection.", """ + forbidden ai_apps_off key_database_out_of_scope key_read_only field_unavailable field_hidden + field_unreadable database_unreadable workbook_read_only grants_changed out_of_scope + owner_required admin_required view_not_yours credential_in_attribution scope_not_applied no_session + scope_not_applicable pid_scope_unresolved + """), + ("That item is not available to this account.", """ + tool_not_found record_unavailable view_unavailable workbook_missing workbook_unavailable + tab_missing folder_missing unknown_table unknown_field view_missing view_not_found operation_unavailable + sheet_structure_tab_missing unknown_sheet_template cell_missing + """), + ("This action is not available right now.", """ + tool_unavailable tool_capability_unsupported capability_unavailable external_access_unavailable + store_unavailable store_not_ready store_catching_up oauth_unavailable not_connected + schema_not_loaded query_groups_unavailable confirmation_revision_unavailable + assistant_source_too_large amazon_mirror_not_loaded + """), + ("The change could not be accepted. Review it before trying again.", """ + tool_refused write_partial_refused field_refused view_refused refused + connected_source_read_only computed_field records_read_only loopable_managed + preset_field_locked zone_membership_read_only not_a_user_table + """), + ("This change would not change anything.", "write_not_changed view_not_changed"), + ("The data or permissions changed. Read them and preview the change again.", """ + confirmation_stale confirmation_expired confirmation_replayed confirmation_principal_changed + workbook_revision_stale sheet_revision_stale view_revision_stale view_permission_changed + repair_snapshot_changed repair_cell_changed repair_workbook_mismatch + """), + ("Use a current preview and its confirmation details.", """ + confirmation_token_invalid confirmation_not_write confirmation_phrase_required + confirmation_too_large + """), + ("Use fewer records or split this change into smaller parts.", """ + query_filter_limit query_sort_too_large sheet_too_many_cells sheet_too_many_rules + sheet_too_many_charts workbook_too_large workbook_too_many_sheets + """), + ("The cell settings are invalid. Read the action's guide and correct them.", """ + cell_address_invalid cell_binding_kind_unknown cell_binding_paths_conflict cell_border_invalid + cell_format_code_missing cell_format_code_too_long cell_format_code_too_many_sections + cell_format_code_unbalanced cell_format_invalid cell_format_kind_unknown cell_formula_kind_unknown + cell_kind_unknown cell_not_an_object cell_state_unknown cell_style_invalid cell_validation_invalid + cells_not_an_object cell_value_kind_unknown cell_value_too_long cell_formula_too_long + cell_text_too_long cell_formula_invalid cell_text_invalid cell_value_invalid + view_binding_fields_invalid view_binding_invalid view_binding_limit_invalid view_binding_mode_unknown + view_binding_sort_invalid view_binding_type_unknown + """), + ("The Sheet settings are invalid. Read the action's guide and correct them.", """ + col_width_column_invalid col_width_invalid col_widths_not_an_object sheet_chart_geometry_invalid + sheet_chart_invalid sheet_chart_kind_unknown sheet_chart_range_invalid sheet_chart_stacking_kind_invalid + sheet_chart_stacking_unknown sheet_charts_not_a_list sheet_extent_invalid sheet_extent_out_of_range + sheet_freeze_invalid sheet_hidden_invalid sheet_hidden_not_a_list sheet_imported_invalid + sheet_not_an_object sheet_pivot_aggregate_unknown sheet_pivot_invalid sheet_print_orientation_unknown + sheet_row_groups_invalid sheet_row_groups_overlap sheet_row_height_invalid sheet_rule_colour_invalid + sheet_rule_formula_missing sheet_rule_formula_too_long sheet_rule_kind_unknown sheet_rule_op_unknown + sheet_rule_scale_type_unknown sheet_rules_not_a_list sheet_tab_kind_unknown sheet_visibility_unknown + sheets_not_a_list sheet_structure_invalid tab_last tab_name_empty tab_name_invalid tab_name_taken + workbook_date_system_unknown workbook_id_invalid workbook_iteration_unsupported workbook_name_empty + workbook_name_taken workbook_names_invalid workbook_not_an_object workbook_not_serializable + workbook_revision_invalid workbook_schema_unknown + """), + ("Check the template's name, fields and databases before saving it.", """ + sheet_template_database_missing sheet_template_key_exists sheet_template_key_invalid + sheet_template_text_invalid sheet_templates_schema_unknown template_cells_refused + """), + ("Check the View's sharing settings before changing it.", """ + view_is_shared view_not_personal share_owner_redundant share_role_unknown share_who_required + """), +) +MCP_RESULT_CODES = { + code: reason for reason, codes in _MCP_CODE_GROUPS for code in codes.split() +} +MCP_RESULT_CODES.update({ + "key_refresh_only": "This connection can only refresh source cells in its granted workbooks.", + "key_workbook_out_of_scope": "This connection cannot refresh this workbook.", + "external_workbooks_invalid": "Choose up to 100 workbook ids. All workbooks is not a valid choice.", + "query_cursor_stale": "The query, data or permissions changed. Repeat the original query without cursor for a fresh first page.", + "query_cursor_invalid": "The query cursor is invalid. Repeat the original query without cursor for a fresh first page.", + "query_source_unavailable": "This database is temporarily unavailable. Try the same query again shortly.", + "test_connection_production": "Test connections cannot write to production. Use a staging environment.", + "test_connection_environment_unknown": "This environment is unknown. Test connections need a named non-production environment.", + "external_test_connection_invalid": "Set test_connection to true or false.", + "ok": "The action completed.", + "preview_ready": "Review the proposed change before confirming it.", + "change_applied": "The confirmed change was applied.", + "operation_pending": "The change is still being saved. Ask again shortly.", + "operation_not_committed": "This change has not been committed.", + "credential_in_arguments": "Remove credential values from the arguments.", + "invalid_external_credential": "The credential is invalid, expired, or revoked.", + "credential_in_output": "The result contained a credential value and was withheld.", + "tool_output_invalid": "The result could not be represented safely.", + "request_invalid": "The request could not be read. Check its format.", + "request_method_unknown": "The requested method is not available.", + "request_rate_limited": "This AI has reached its hourly request cap. Try again later.", +}) +_MCP_INTERNAL_PROSE = re.compile( + r"\b(?:DuckDB|Postgres(?:ql)?|SQLite|Polars|Pandas|SQLAlchemy|PyArrow|HyperFormula)\b|" + r"\b(?:api|web|platform)_[a-z_]+\b|\b(?:verify_\w+|\w+Error)\b|" + r"Traceback|stack trace|\bengine\b|\bmanifest\b|\brevision-guard\b|\bgate\b|" + r"\b(?:tenant store|dispatcher|document cleaner)\b|" + r"(?:[A-Za-z]:[\\/]|/(?:tmp|root|work|home|srv|app)/)|" + r"(?:[\w.-]+[/\\])*[\w.-]+\.(?:py|tsx?|pyc|ps1|sh|json)(?::\d+)?|" + r"\.(?:claude|agents|codex)/|~[/\\]", re.I) +_MCP_PROSE_REPLACEMENTS = ( + (r"strict Assistant scope wall|scope wall|live UI walls|UI walls", "permissions"), + (r"\b[A-Z]\d+ audience\b|\baudience [A-Z]\d+\b", "people with access"), + (r"Sheet document cleaner|document cleaner", "Sheet rules"), + (r"REST door", "data access"), + (r"maker['’]s (?:own )?grants", "user's permissions"), +) + + +def _mcp_plain(value, fallback="Details are unavailable.", labels=None): + """Clean explanatory copy without changing identifiers or customer records.""" + if not isinstance(value, str) or not value.strip(): + return fallback + text = dash_norm.plain(value) + for pattern, replacement in _MCP_PROSE_REPLACEMENTS: + text = re.sub(pattern, replacement, text, flags=re.I) + def database_label(match): + return labels(match[0]) if callable(labels) else (labels or {}).get(match[0], "this database") + text = re.sub(r"\but_[\w]+\b", database_label, text) + if _MCP_INTERNAL_PROSE.search(text) or _contains_credential(text): + return fallback + return text + + +def _mcp_prose_copy(value, labels=None, fallback="Details are unavailable."): + """Shape explanatory strings at every depth without discarding metadata.""" + if isinstance(value, str): + return _mcp_plain(value, fallback, labels) if value.strip() else value + if isinstance(value, (list, tuple)): + return [_mcp_prose_copy(child, labels, fallback) for child in value] + if isinstance(value, dict): + return {key: _mcp_prose_copy(child, labels, fallback) for key, child in value.items()} + if value is None or isinstance(value, (bool, int, float)): + return copy.deepcopy(value) + return _mcp_plain(str(value), fallback, labels) + + +def _mcp_schema_copy(schema): + """Clean schema descriptions while preserving caller-facing keys and constraints.""" + if isinstance(schema, list): + return [_mcp_schema_copy(item) for item in schema] + if not isinstance(schema, dict): + return _mcp_prose_copy(schema) + result = {} + # Constraints and example values are arguments, even when their text resembles diagnostics. + literals = {"const", "enum", "default", "examples", "example", "required", "dependentRequired", + "$schema", "$id", "$ref", "$anchor", "$dynamicRef", "$dynamicAnchor", + "type", "format", "pattern", "contentEncoding", "contentMediaType"} + maps = {"properties", "$defs", "definitions", "patternProperties", "dependentSchemas"} + children = {"items", "prefixItems", "additionalItems", "additionalProperties", "unevaluatedItems", + "unevaluatedProperties", "contains", "propertyNames", "oneOf", "anyOf", "allOf", + "not", "if", "then", "else", "contentSchema"} + for key, child in schema.items(): + if key in literals: + result[key] = copy.deepcopy(child) + elif key in maps and isinstance(child, dict): + result[key] = {name: _mcp_schema_copy(entry) for name, entry in child.items()} + elif key in children: + result[key] = _mcp_schema_copy(child) + elif key == "dependencies" and isinstance(child, dict): + result[key] = {name: copy.deepcopy(entry) if isinstance(entry, list) + else _mcp_schema_copy(entry) for name, entry in child.items()} + else: + result[key] = _mcp_prose_copy(child, fallback="Read the action's guide for details.") + return result + + +def _mcp_public_code(code, status=400): + status = status if type(status) is int else 400 + if isinstance(code, str) and code in MCP_RESULT_CODES: + return code + return {403: "forbidden", 404: "tool_not_found", 429: "request_rate_limited"}.get( + status, "tool_unavailable" if status >= 500 else "tool_refused") + + +class _MCPGuideText(str): + """Mark a guide assembled from shaped prose and exact argument schemas.""" + + +_MCP_RESULT_OPAQUE = frozenset({ + "records", "rows", "cells", "values", "value", "before", "after", "arguments", "diff", + "confirmation_token", "confirmation_phrase", "diff_digest", "current_revision", + "revision_before", "revision_after", "filters", "sorts", "config", "binding", "bindings", +}) +_MCP_RESULT_IDENTIFIERS = frozenset({ + "resourceUri", + "id", "ids", "operation_id", "key", "keys", "pid", "pids", "database", "databases", "sourceDatabase", + "compatibleDatabases", "field", "fields", "field_key", "colId", "metric_key", "groupBy", + "workbook_id", "worksheet", "tab", "view_id", "app_id", "chart_id", "record_id", "contextId", + "path", "paths", "address", "addresses", "range", "cursor", "next_cursor", "token", + "source_version", "code", "tool", "action", "person", "agent", "owner", "author", "from", "to", + "username", "tenant", "createdBy", "updatedBy", "by", "byName", "reads", "approvers", +}) +# Only known product objects carry authored prose. Unknown containers remain explanatory. +_MCP_RESULT_OBJECTS = frozenset({ + "data", "error", "databases", "fields", "tab", "tabs", "workbook", "workbooks", "worksheet", + "worksheets", "file", "files", "request", "requests", "template", "templates", "application", + "applications", "view", "views", "from", "to", "source", "affected", "aggregates", "tools", + "annotations", "serverInfo", "environment", +}) +_MCP_AUTHORED_DESCRIPTIONS = frozenset({ + "fields", "file", "files", "template", "templates", "application", "applications", "view", "views", +}) + + +def _mcp_result_copy(value, labels=None, *, field=None, metadata=False): + """Shape diagnostic fields while leaving data and preview identities intact.""" + if isinstance(value, _MCPGuideText): + return str(value) + if isinstance(value, str): + return copy.deepcopy(value) if field in _MCP_RESULT_IDENTIFIERS else _mcp_prose_copy(value, labels) + if isinstance(value, (list, tuple)): + return [_mcp_result_copy(child, labels, field=field, metadata=metadata) for child in value] + if not isinstance(value, dict): + return copy.deepcopy(value) if field in _MCP_RESULT_IDENTIFIERS else _mcp_prose_copy(value, labels) + result = {} + for key, child in value.items(): + if key == "retry_query" and value.get("code") == "query_cursor_stale": + # These are the caller's original arguments, not explanatory metadata. + result[key] = copy.deepcopy(child) + elif key in _MCP_RESULT_OPAQUE and not metadata: + result[key] = copy.deepcopy(child) + elif key in {"schema", "inputSchema"}: + result[key] = _mcp_schema_copy(child) + elif not metadata and isinstance(child, str) and ( + key in {"name", "title", "label", "body", "content", "text"} + or field in _MCP_AUTHORED_DESCRIPTIONS and key in {"description", "note", "summary"}): + result[key] = copy.deepcopy(child) + elif isinstance(child, str) and key in { + "reason", "message", "sentence", "warning", "description", "error", "detail", "write_scope"}: + code = _mcp_public_code(value.get("code"), value.get("status", 400)) + result[key] = _mcp_plain(child, MCP_RESULT_CODES[code], labels) + elif key in {"traceback", "stack_trace", "exception", "engine", "debug"}: + continue + else: + result[key] = _mcp_result_copy( + child, labels, field=key, metadata=metadata or key not in _MCP_RESULT_OBJECTS) + if "code" in result and any(key in result for key in ("reason", "message", "sentence")): + result["code"] = _mcp_public_code(result["code"], result.get("status", 400)) + return result + + +def _shape_mcp_result(out, session=None): + """Give every tool outcome a published code and a safe, plain reason.""" + labels = None + + def label_for(database): + nonlocal labels + if labels is None: + labels = {} + # Label lookup is lazy and uses only metadata visible to this caller. + if session is not None: + try: + allowed = _key_scope(session)[1] + labels = {row["database"]: _mcp_plain(row["label"], "this database") + for row in _resolve_external_scope(session) + if row["permitted"] and external_access.database_allowed(allowed, row["database"])} + except Exception: + pass + return labels.get(database, "this database") + + result = _mcp_result_copy(out, label_for) + data = result.get("data") + if result.get("ok") and isinstance(data, dict) and ( + data.get("ok") is False or isinstance(data.get("error"), (dict, str)) and bool(data["error"])): + result = {"ok": False, "error": data.get("error") or { + "code": data.get("code"), "message": data.get("reason") or data.get("message")}, "data": data} + if result.get("ok") is True: + code = ("change_applied" if isinstance(data, dict) and data.get("confirmed") + else "preview_ready" if isinstance(data, dict) and data.get("preview") else "ok") + if isinstance(data, dict) and data.get("operation_id") and not data.get("preview") and data.get("state") == "not_committed": + code = "operation_pending" if data.get("retry") else "operation_not_committed" + return {**result, "ok": True, "code": code, "reason": MCP_RESULT_CODES[code]} + error = result.get("error") if isinstance(result.get("error"), dict) else {} + status = error.get("status", 400) + status = status if type(status) is int else 400 + code = _mcp_public_code(error.get("code"), status) + reason = _mcp_plain(error.get("message") or error.get("reason"), MCP_RESULT_CODES[code], label_for) + if reason == "Details are unavailable.": + reason = MCP_RESULT_CODES[code] + return {**result, "ok": False, "code": code, "reason": reason, + "error": {**error, "code": code, "message": reason, "reason": reason, "status": status}} + + +def _mcp_code_guide(): + lines = ["## Result codes", "", "Every tool reply has ok, code and reason. Data and confirmation details keep their original keys.", ""] + for reason, codes in _MCP_CODE_GROUPS: + lines.append(", ".join("`" + code + "`" for code in codes.split()) + ": " + reason) + grouped = {code for _, codes in _MCP_CODE_GROUPS for code in codes.split()} + lines += ["`" + code + "`: " + reason for code, reason in MCP_RESULT_CODES.items() if code not in grouped] + return "\n".join(lines) def _tool_refusal(name, code, message, status=400, **extra): # Never echo arbitrary method/tool names or raw exception text across the bearer seam. tool_name = name if isinstance(name, str) and name in external_tools.TOOLS else "tools/call" - sentence = f"{tool_name}: {_markdown_inline(message)}" + if tool_name == "tools/call" and isinstance(name, str): + import tool_groups + try: + if name == MCP_GUIDE_TOOL or name in tool_groups.groups(): + tool_name = name + except (KeyError, TypeError, ValueError): + pass + sentence = _markdown_inline(message) if _contains_credential(sentence): sentence = f"{tool_name}: The result contained a credential value and was withheld." return {"ok": False, "error": {"tool": tool_name, "code": code, "message": sentence, "status": status, **extra}} -def _mcp_content(rid, out): +def _mcp_content(rid, out, session=None): + # Check the original result before prose shaping can remove credential evidence. + try: + original = json.dumps(out, default=str, ensure_ascii=True, allow_nan=False) + except (TypeError, ValueError, OverflowError): + out = _tool_refusal(None, "tool_output_invalid", "The result could not be represented safely.", 422) + else: + if _contains_credential(original): + out = _tool_refusal(None, "credential_in_output", + "The result contained a credential value and was withheld.") + out = _shape_mcp_result(out, session) try: encoded = json.dumps(out, default=str, ensure_ascii=True, allow_nan=False) except (TypeError, ValueError, OverflowError): - out = _tool_refusal(None, "tool_output_invalid", - "The result could not be represented safely.", 422) + out = _shape_mcp_result(_tool_refusal(None, "tool_output_invalid", + "The result could not be represented safely.", 422)) encoded = json.dumps(out) if _contains_credential(encoded): - out = _tool_refusal(None, "credential_in_output", "The result contained a credential value and was withheld.") + out = _shape_mcp_result(_tool_refusal(None, "credential_in_output", "The result contained a credential value and was withheld.")) encoded = json.dumps(out) return {"jsonrpc": "2.0", "id": rid, "result": { "content": [{"type": "text", "text": encoded}], "isError": not out.get("ok", False)}} +def _mcp_protocol_error(rid, code, message): + public_code = "request_method_unknown" if code == -32601 else "request_invalid" + out = _shape_mcp_result({"ok": False, "error": {"code": public_code, "message": message}}) + return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": out["reason"], "data": out}} + + +def _mcp_protocol_result(rid, data): + out = _shape_mcp_result({"ok": True, "data": data}) + return {"jsonrpc": "2.0", "id": rid, "result": { + **out["data"], "ok": out["ok"], "code": out["code"], "reason": out["reason"]}} + + # ⭐⭐ HOTFIX 2026-09-24 — WHAT AN MCP CLIENT IS TOLD, AND WHERE IT READS THE REST. Owner: does # ChatGPT "have access to Loopable skill so it knows best practice in tool calling". It did not: # skill.md is only offered to coding agents, and `initialize` sent no guidance. Two doors, because @@ -3245,70 +4312,432 @@ MCP_GUIDE_TOOL = "loopable_guide" MCP_INSTRUCTIONS = "\n".join([ "Loopable is a governed business data workspace: databases, saved Views, Sheet workbooks and " "Apps. Every call runs as the signed-in user, with that user's own permissions.", - "1. Call loopable_guide once at the start. It returns this user's databases and the rules " - "for every tool.", - "2. Discover before you query: list_databases, then describe_database for the database you " + "1. Call loopable_guide for the group index. Call it with group to read that group's actions and schemas.", + "2. Discover before you query: use data.list_databases, then data.describe_database for the database you " "need. Use only field keys that describe_database returns; never guess a field name.", - "3. Read with query_database. Filter and sort on the server, ask only for the fields you need, " + "3. Read with data.query_database. Filter and sort on the server, ask only for the fields you need, " "and follow the cursor for more pages instead of reading everything. Report totals from the " "counts the tool returns, not from the rows you happened to read.", - "4. Every write returns a preview first. Show the user what will change and call " + "4. Writes return a preview first. Show the user what will change and call " "confirm_change only after they agree. A destructive change needs the exact phrase the " - "preview names.", + "preview names. The only exception is requests.send: sending a request to a person runs at once, " + "without preview or confirmation. It runs only when the recipient can see the data the request needs, " + "the request names the person whose AI sent it, and each AI has an hourly cap.", "5. A refusal (ok: false) names its code and reason. Tell the user the reason; do not retry " "the same call with a wider scope.", - "6. Never ask for, print or store a credential.", + "6. Never ask for, print or save a credential.", + "7. " + external_tools.CELL_FIGURE_RULE, + "8. Report a limitation or missing field with data.report_limitation. It needs no confirmation " + "and changes no workspace data. Give the tool, action, code and your question in plain words. " + "Omit records, cell values, filters and credentials. Refused calls are logged automatically. " + "To include your question with a call, set params._meta['loopable/question'] to at most 500 characters.", ]) _MCP_GUIDE_SPEC = { "name": MCP_GUIDE_TOOL, - "description": ("Read this first. The Loopable guide for this user: their databases and " - "the rules for calling every other tool."), - "inputSchema": {"type": "object", "properties": {}, "required": [], + "description": "Read workspace connections, your skills, databases and the group index, " + "or choose a group for its actions and argument schemas.", + "inputSchema": {"type": "object", "properties": {"group": {"type": "string"}}, "required": [], "additionalProperties": False}, - "annotations": {"title": "Loopable guide", "readOnlyHint": True, "openWorldHint": False}, + "annotations": {"title": "Loopable guide", "readOnlyHint": True, + "destructiveHint": False, "openWorldHint": False}, } -def _mcp_guide(session: Session) -> str: - """`loopable_guide`'s answer: the rules, this user's databases and every tool, in one read. +def _guide_connections(session: Session) -> list[dict]: + """List active clients and who connected them within this workspace, without credentials.""" + from core import users + from routes_connectors import _external_active, _external_client_id, AI_CONTACT_CLIENTS - ⛔ NO ROWS ARE READ. The first version lent the per-user skill.md, which reads EVERY database - through the Assistant path to list its fields: measured on staging at 52 s and 57 KB, too - slow for a tool whose whole job is to be called first. Fields are one describe_database call - away, for the one database the question is about. - """ + known_clients = {key: label for key, label, _aliases in AI_CONTACT_CLIENTS} + connected = {} + for person in users.assignable_identities(session.tenant): + username = person["username"] + user = external_access.resolve_active_user(username, session.tenant) + if perm_scope.ai_apps_refusal(user, session.runtime): + continue + names = [] + for grant in external_oauth.list_connections(session.runtime, username, session.tenant): + if not _external_active(grant): + continue + try: + names.append(external_oauth.label_for(session.runtime, grant["id"])) + except external_oauth.ExternalOAuthAuthError: + continue + for key in external_access.list_for_user(session.runtime, username, session.tenant): + client = _external_client_id(key) + if client and key.get("last_used") and _external_active(key): + names.append(known_clients[client]) + for name in names: + connected[(username, name)] = { + "name": _markdown_inline(name), "connectedBy": _markdown_inline(person["name"])} + return [connected[key] for key in sorted(connected)] + + +def _guide_skills(session: Session) -> list[dict]: + """Read skill titles through the current user's permissions and connection's database scope.""" + import loopy_skills + + class SkillSession(Session): + def require(self, module_key): + _assert_database_scope(self, module_key) + super().require(module_key) + + scoped = SkillSession(session.tenant, session.user, session.claims, session.runtime) + rows = [{"key": row["key"], "title": _markdown_inline(row["title"])} + for row in loopy_skills.list_skills(scoped)] + try: + files = importlib.import_module("intelligence_store") + except ModuleNotFoundError as exc: + if exc.name != "intelligence_store": + raise + return rows + try: + session.require("intelligence") + except HTTPException as exc: + if exc.status_code != 403: + raise + return rows + offset = 0 + while True: + page = files.list_files(session, section="playbooks", offset=offset, limit=100) + for row in page["files"]: + if row.get("fieldCheck", {}).get("state", "ready") == "ready": + rows.append({"path": row["path"], "title": _markdown_inline(row["title"])}) + offset += len(page["files"]) + if offset >= page["total"]: + return rows + if not page["files"]: + raise err(503, "tool_unavailable", "Your skills could not be listed. Try again.") + + +def _mcp_action_supported(entry): + """Check implementation presence without invoking a reader or writer.""" + legacy = entry.get("legacy_name") + if not callable(entry.get("handler")): + return False + available = entry.get("available") + if callable(available): + try: + if not available(): + return False + except Exception: + return False + if legacy and not callable(external_tools.TOOLS.get(legacy, {}).get("handler")): + return False + if legacy in external_tools._SHEET_OBJECT_ACTIONS or legacy == "validated_batch": + try: + module, manifest = _sheet_compat_contract() + if legacy == "validated_batch": + return callable(getattr(module, "dispatch_validated_batch", None)) + if _sheet_object_dispatcher(module) is None: + return False + _manifest_operation(manifest, legacy.removesuffix("_object"), entry["legacy_action"]) + except sheets.SheetRefusal: + return False + return True + + +def _mcp_database_actions(session, rows): + """Resolve database grants through read-only permission predicates.""" + from core import grid_events, user_tables + import routes_grid + import routes_tables + session = Session(session.tenant, session.user, session.claims, user_tables.lend_defs(session.runtime)) + allowed = {action: False for action in external_tools._DATABASE_ACTIONS if action not in {"list", "describe", "query"}} + for row in rows: + database = row["database"] + try: + routes_tables._managed_or_refuse(session, database, mutation=True) + if not user_tables.is_user_table(database, st=session.runtime): + continue + fields = row.get("fields", []) + try: + routes_tables._records_or_refuse(session, database) + ctx = routes_grid._ctx(session, fields, frozenset(), scope_key=database) + editable = any( + not user_tables.is_computed_cell(field) and field.get("type") != "automation" + and grid_events._may_edit_field_value(ctx, field["key"], field) + for field in fields) + allowed["record_create"] |= editable + allowed["record_update"] |= editable + allowed["record_delete"] = True + except HTTPException: + pass + try: + routes_tables._field_or_refuse(session, database) + allowed["field_create"] = True + except HTTPException: + pass + for field in fields: + key = field["key"] + try: + routes_tables._field_or_refuse(session, database, key) + allowed["field_update"] = True + allowed["field_delete"] |= user_tables.may_delete_field( + database, key, session.uname, session.admin, st=session.runtime) + except HTTPException: + pass + except HTTPException: + continue + return allowed + + +def _mcp_capabilities(session, groups, rows): + """Report action availability from implementation and this request's grants.""" + import tool_groups + database_actions = _mcp_database_actions(session, rows) + environment_refusal = _test_environment_refusal(session) + result = [] + advertised = {**groups, "": {"actions": { + "loopable_guide": {"handler": _mcp_guide, "read": True}, + "confirm_change": {"handler": _confirm_change, "legacy_name": "confirm_change", "read": False}, + }}} + for group, definition in advertised.items(): + for action, entry in definition["actions"].items(): + row = {"group": group, "action": action, "state": "available", "requires": ""} + legacy = entry.get("legacy_name", "") + required = [] + if not _mcp_action_supported(entry): + row["state"] = "not supported here" + else: + grants = tool_groups.action_grants(entry, group) + if legacy == "validated_batch": + grants = (*grants, "sheets") + for grant in grants: + try: + if grant == "ai_apps": + require_external_analyst(session) + else: + session.require(grant) + except HTTPException: + required.append({"ai_apps": "AI apps access", "sheets": "Sheet access", + "intelligence": "Brain access"}.get(grant, "Access to " + grant)) + refresh = (_key_scope(session)[0] == external_access.ACCESS_REFRESH + and ((group == "sheet" and action == "refresh_scope") or legacy == "confirm_change")) + if not entry["read"] and not external_access.may_write(_key_scope(session)[0]) and not refresh: + required.append("a connection with write access") + if refresh and not session.claims.get("external_workbooks"): + required.append("a workbook granted to this connection") + if not entry["read"] and environment_refusal: + required.append("a named non-production environment for this test connection") + if legacy in {"describe_database", "query_database", "view_upsert", "view_delete", "view_share_preview", "view_object", "app_upsert", "app_delete"} or ( + legacy == "database_object" and entry.get("legacy_action") != "list") or legacy == "sheet_set_binding": + if not rows: + required.append("database access for your account and this connection") + if legacy == "database_object" and not entry["read"]: + operation = entry["legacy_action"] + if not database_actions.get(operation): + required.append("permission to " + { + "record_create": "add records with editable fields", + "record_update": "edit record fields", "record_delete": "delete records", + "field_create": "add fields as the database owner or an Administrator", + "field_update": "edit a visible field", "field_delete": "delete a visible field", + }[operation] + " in a writable database") + if required: + row.update(state="not available to you", requires=" and ".join(required)) + result.append(row) + return result + + +def _external_recall(session): + """Return bounded personal recall through fresh account, credential and source admission.""" + try: + import intelligence_learn + return intelligence_learn.recall(session, limit=20) + except Exception: + return {"items": [], "truncated": False, "available": False} + + +@router.get("/conversations/recall") +def recall_conversation(session: Session = Depends(require_external_analyst)): + """Expose admitted personal recall for a new authenticated client session.""" + return _external_recall(session) + + +_CLIENT_TURN_ID = re.compile(r"[A-Za-z0-9_.:-]{1,128}\Z") +_MAX_TURN_TEXT = 4000 + + +def _client_interaction_id(session, client_turn_id): + """A host-owned opaque id: the client's turn id never reaches the learner as written.""" + claims = session.claims or {} + credential = str(claims.get("external_credential_id") or claims.get("external_key_id") or "") + digest = hashlib.sha256("\x1f".join((str(session.tenant), session.uname, credential, + client_turn_id)).encode("utf-8")).hexdigest() + return "xt_" + digest[:40] + + +@router.post("/conversations/turns") +def admit_completed_turn(payload: dict = Body(...), session: Session = Depends(require_external_analyst)): + """S73-T63: one completed human turn an AI client reports, attributed to the signed-in person. + + The person is the credential's, never the payload's. The learner rechecks every named source + against current access and refuses a read-only credential.""" + import intelligence_learn + import intelligence_store as files + + if not isinstance(payload, dict) or set(payload) - {"clientTurnId", "text", "status", "sources"}: + raise err(400, "turn_arguments_invalid", "Send clientTurnId, text, status and sources only.") + client_turn_id, text = payload.get("clientTurnId"), payload.get("text") + status, sources = payload.get("status"), payload.get("sources", []) + if not isinstance(client_turn_id, str) or not _CLIENT_TURN_ID.fullmatch(client_turn_id): + raise err(400, "turn_id_invalid", "Use the client's own turn id, up to 128 plain characters.") + if not isinstance(text, str) or not text.strip() or len(text) > _MAX_TURN_TEXT: + raise err(400, "turn_text_invalid", "Send the person's own words, up to 4000 characters.") + if status not in ("completed", "failed", "canceled", "input-required"): + raise err(400, "turn_status_invalid", "Use completed, failed, canceled or input-required.") + if sources is None: + sources = [] + try: + return intelligence_learn.learn_completed_turn( + session, interaction_id=_client_interaction_id(session, client_turn_id), user_text=text, + author=session.uname, status=status, sources=sources) + except files.IntelligenceError as exc: + raise err(exc.status, exc.code, str(exc)) from None + + +def _mcp_guide(session: Session, group=None) -> str: + """Return the group index or one group's action schemas without reading records.""" + import tool_groups + groups = tool_groups.groups() + if group is not None and group not in groups: + raise sheets.SheetRefusal("tool_not_found", "The requested group is not available.") + key_databases = _key_scope(session)[1] + databases = [row["database"] for row in _resolve_external_scope(session) if row["permitted"] + and external_access.database_allowed(key_databases, row["database"])] + rows = _resolve_external_scope(session, databases=databases, include_schema=True) + rows = [row for row in rows if row["permitted"]] + capabilities = _mcp_capabilities(session, groups, [row for row in rows if row.get("schema")]) lines = ["# Loopable guide", "", f"Signed in as {session.uname}.", "", MCP_INSTRUCTIONS, "", - "## Your databases", "", + "Call a group with action and arguments. Each action keeps its own read or write rules.", + "Previous tool names remain callable for one release, but are absent from tools/list.", ""] + lines += ["Available means this action is supported with your current grants. " + "Choose a database and fields you can access. Workbook, record and personal View permissions " + "still apply to each target. Changes still need their stated confirmation.", ""] + if group is not None: + selected = groups[group] + lines += ["## " + _mcp_plain(selected["title"], "Actions"), "", + _mcp_plain(selected["guide"], "Choose an action below."), ""] + if group == "data": + from tool_groups.data import query_guide + lines += [query_guide(rows), ""] + states = {row["action"]: row for row in capabilities if row["group"] == group} + for action, entry in selected["actions"].items(): + lines += ["### " + action, + "State: " + states[action]["state"] + "." + + (" Needs " + states[action]["requires"] + "." if states[action]["requires"] else ""), + "Read only: " + str(entry["read"]).lower() + + ". Destructive: " + str(entry["destructive"]).lower() + + ". Confirm: " + str(entry["confirm"]).lower() + "."] + if entry.get("legacy_name"): + lines.append("Previous name: `" + entry["legacy_name"] + "`.") + lines += ["```json", json.dumps(_mcp_schema_copy(entry["schema"]), ensure_ascii=True, indent=2), "```", ""] + return _MCPGuideText("\n".join(lines) + "\n") + lines += ["## Connected AI clients", "", + "Client names and who connected them in this workspace. No entries means none are connected.", + "```json", json.dumps(_guide_connections(session), ensure_ascii=True), "```", "", + "## Your skills", "", + "Skills available with your current permissions and this connection's access.", + "```json", json.dumps(_guide_skills(session), ensure_ascii=True), "```", "", + "## Your actions", "", + "Each action is available, not available to you with the grant it needs, or not supported here.", + "An empty group names a tool to call directly.", + "```json", json.dumps(capabilities, ensure_ascii=True), "```", "", + "## Groups", ""] + for name, entry in groups.items(): + lines.append(f"- `{name}`: {_mcp_plain(entry['title'], 'Actions')}. " + + _mcp_plain(entry['guide'], "Read this group's guide for actions.")) + lines += ["", "Use confirm_change to apply an agreed preview. Keep its operation_id. " + "Repeating a confirmation returns its first result. Call data with action operation_status " + "and arguments {operation_id: the id} to check whether it committed. Results remain available " + "for at least 24 hours while your access remains valid. A retry result means the change is still being saved.", + "", "## Your databases", "", "Call describe_database with a key below for its fields before you query it.", ""] - key_databases = _key_scope(session)[1] - rows = [row for row in _resolve_external_scope(session) if row["permitted"] - and external_access.database_allowed(key_databases, row["database"])] for row in rows: - note = "" if row["answerable"] else f" Not queryable right now: {_markdown_inline(row['reason'])}" - lines.append(f"- `{row['database']}`: {_markdown_inline(row['label'])}.{note}") + label = _mcp_plain(_markdown_inline(row["label"]), "Database") + note = "" if row["answerable"] else " Not queryable right now: " + _mcp_plain( + _markdown_inline(row["reason"]), "Try again later.", {row["database"]: label}) + lines.append(f"- `{row['database']}`: {label}.{note}") if not rows: lines.append("- No databases are available to this account.") - lines += ["", "## Tools", ""] - for key, tool in external_tools.TOOLS.items(): - kind = "writes, preview then confirm_change" if tool["write"] else "read only" - lines.append(f"- `{key}` ({kind}): {_markdown_inline(tool['description'])}") - return chr(10).join(lines) + chr(10) + lines += ["", _mcp_code_guide()] + return _MCPGuideText(chr(10).join(lines) + chr(10)) def _mcp_tool_specs() -> list[dict]: - """tools/list: the guide first, then the registry, each with its read or write hint.""" - specs = [_MCP_GUIDE_SPEC] - for key, tool in external_tools.TOOLS.items(): - specs.append({"name": key, "description": tool["description"], - "inputSchema": tool["inputSchema"], - "annotations": {"readOnlyHint": not tool["write"], "openWorldHint": False}}) + """List the guide, discovered groups and confirmation with honest effect hints.""" + import tool_groups + confirm = external_tools.TOOLS["confirm_change"] + specs = [copy.deepcopy(_MCP_GUIDE_SPEC), *tool_groups.tool_specs(), { + "name": "confirm_change", "description": confirm["description"], + "inputSchema": confirm["inputSchema"], + "annotations": {"readOnlyHint": False, "destructiveHint": True, "openWorldHint": True}, + }] + for spec in specs: + if spec["name"] == "sheet": + from tool_groups.sheet import WORKBOOK_RESOURCE_URI + spec["_meta"] = {"ui": {"resourceUri": WORKBOOK_RESOURCE_URI}} + spec["description"] = _mcp_plain(spec["description"], "Read this group's guide for actions.") + spec["inputSchema"] = _mcp_schema_copy(spec["inputSchema"]) + if "title" in spec.get("annotations", {}): + spec["annotations"]["title"] = _mcp_plain(spec["annotations"]["title"], "Actions") return specs +def _external_is_write(name, arguments): + if name in external_tools.TOOLS: + return external_tools.is_write(name, arguments) + import tool_groups + resolved = tool_groups.resolve(name, arguments) + return bool(resolved and not resolved[0]["read"]) + + +def _dispatch_external_tool(ctx, name, arguments): + if name in external_tools.TOOLS: + return external_tools.dispatch(ctx, name, arguments) + import tool_groups + resolved = tool_groups.resolve(name, arguments) + if resolved is None: + raise sheets.SheetRefusal("tool_not_found", "The requested tool is not available.") + entry, args = resolved + for grant in tool_groups.action_grants(entry, name): + if grant == "ai_apps": + require_external_analyst(ctx.session) + else: + ctx.session.require(grant) + return entry["handler"](ctx, args) + + def _handle_mcp(req, session: Session, base_url: str = ""): + """Record each refused response once, after output checks, without changing its result.""" + reply = _dispatch_mcp(req, session, base_url) + try: + if not isinstance(req, dict) or not isinstance(reply, dict): + return reply + params = req.get("params") + params = params if isinstance(params, dict) else {} + result = reply.get("result", {}) + if result.get("isError"): + error = json.loads(result["content"][0]["text"])["error"] + elif reply.get("error"): + error = reply["error"].get("data", {}).get("error", {}) + else: + return reply + arguments = params.get("arguments") + arguments = arguments if isinstance(arguments, dict) else {} + metadata = params.get("_meta") + question = metadata.get("loopable/question") if isinstance(metadata, dict) else None + external_activity.record_refused( + session, "", err(400, error.get("code", "tool_refused"), "The call was refused."), + tool=params.get("name"), action=arguments.get("action"), question=question) + except Exception: + pass + return reply + + +def _dispatch_mcp(req, session: Session, base_url: str = ""): """One HTTP request object; the stdio precedent's JSON-RPC and content envelopes.""" - def protocol_error(rid, code, message): - return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": message}} + protocol_error = _mcp_protocol_error if not isinstance(req, dict): return protocol_error(None, -32600, "An MCP request must be a JSON-RPC object.") @@ -3329,40 +4758,79 @@ def _handle_mcp(req, session: Session, base_url: str = ""): # remains MCP content. Only the unchanged bearer dependency produces an HTTP 401. require_external_analyst(session) if method == "initialize": - protocol = params.get("protocolVersion") or "2025-06-18" - if not isinstance(protocol, str) or _contains_credential(protocol): + requested = params.get("protocolVersion") + if _contains_credential(requested): + return protocol_error(rid, -32602, "The protocol version must be a safe string.") + try: + protocol = external_tools.negotiate_mcp_protocol(requested) + except ValueError: return protocol_error(rid, -32602, "The protocol version must be a safe string.") - return {"jsonrpc": "2.0", "id": rid, "result": { - "protocolVersion": protocol, "capabilities": {"tools": {}}, + return _mcp_protocol_result(rid, { + "protocolVersion": protocol, "capabilities": {"tools": {}, "resources": {}}, "serverInfo": {"name": "loopable-external", "version": "1.0.0"}, - "instructions": MCP_INSTRUCTIONS}} + "instructions": MCP_INSTRUCTIONS + "\nPersonal recall is evidence, subordinate to permissions and validated definitions.\n" + + json.dumps(_external_recall(session), ensure_ascii=True)}) if method == "ping": - return {"jsonrpc": "2.0", "id": rid, "result": {}} + return _mcp_protocol_result(rid, {}) if method == "tools/list": - return {"jsonrpc": "2.0", "id": rid, "result": {"tools": _mcp_tool_specs()}} + return _mcp_protocol_result(rid, {"tools": _mcp_tool_specs()}) + if method in {"resources/list", "resources/read"}: + from tool_groups.sheet import WORKBOOK_RESOURCE_URI, WORKBOOK_RESOURCE_MIME + resource = {"uri": WORKBOOK_RESOURCE_URI, "name": "Workbook", "mimeType": WORKBOOK_RESOURCE_MIME, + "_meta": {"ui": {"csp": {"connectDomains": [], "resourceDomains": [], "frameDomains": []}}}} + if method == "resources/list": + return {"jsonrpc": "2.0", "id": rid, "result": {"resources": [resource]}} + if params.get("uri") != WORKBOOK_RESOURCE_URI: + return protocol_error(rid, -32602, "That resource is not available.") + resource["text"] = (Path(__file__).parent / "side_view" / "workbook.html").read_text(encoding="utf-8") + return {"jsonrpc": "2.0", "id": rid, "result": {"contents": [resource]}} if method != "tools/call": return protocol_error(rid, -32601, "The requested MCP method was not found.") + arguments = params.get("arguments", {}) if name == MCP_GUIDE_TOOL: + external_tools.validate_arguments(arguments, _MCP_GUIDE_SPEC["inputSchema"]) return _mcp_content(rid, {"ok": True, "data": { - "instructions": MCP_INSTRUCTIONS, "guide": _mcp_guide(session)}}) - arguments = params.get("arguments", {}) - for database in _databases_in_arguments(arguments): - _assert_database_scope(session, database) + "instructions": MCP_INSTRUCTIONS, "guide": _mcp_guide(session, arguments.get("group"))}}, session) + import tool_groups + resolved = tool_groups.resolve(name, arguments) + confirm = True + scoped_arguments = arguments + if resolved: + entry, action_args = resolved + confirm = entry["confirm"] + scoped_arguments = action_args + if entry.get("legacy_name"): + name, arguments = entry["legacy_name"], action_args + _assert_tool_database_scope(session, name, scoped_arguments) if name == "confirm_change": data = external_tools.dispatch(_tool_context(session), name, arguments) - elif external_tools.is_write(name, arguments): - _assert_write_scope(session, name) - data = _preview_external_write(session, name, arguments) - data.pop("_confirmation", None) - data.pop("_plan", None) + elif _external_is_write(name, arguments): + _assert_write_scope(session, name, arguments) + if confirm: + data = _preview_external_write(session, name, arguments) + data.pop("_confirmation", None) + data.pop("_plan", None) + else: + data = _dispatch_external_tool(_tool_context(session), name, arguments) else: - data = external_tools.dispatch(_tool_context(session), name, arguments) + data = _dispatch_external_tool(_tool_context(session), name, arguments) if isinstance(data, dict) and data.get("refused"): first = data["refused"][0] out = _tool_refusal(name, first["code"], first["sentence"]) out["error"]["data"] = data # Accepted edits remain visible even on partial refusal. else: out = {"ok": True, "data": data} + if name == "sheet" and arguments.get("action") == "workbook.view" and out.get("ok"): + book = data["workbook"] + reply = _mcp_content(rid, {"ok": True, "data": {"workbook": { + key: book[key] for key in ("id", "name", "rev")}}}, session) + # Component data is still credential checked, but never sent as model content. + encoded = json.dumps(book, ensure_ascii=True, allow_nan=False) + if _contains_credential(encoded): + return _mcp_content(rid, _tool_refusal(name, "credential_in_output", + "The result contained a credential value and was withheld."), session) + reply["result"]["_meta"] = {"workbook": book} + return reply except external_access.ExternalAuthError: _auth_refusal() except external_access.ExternalAccessError: @@ -3377,13 +4845,15 @@ def _handle_mcp(req, session: Session, base_url: str = ""): if exc.status_code == 401: _auth_refusal() info = exc.detail.get("error", {}) if isinstance(exc.detail, dict) else {} + retry = ({"retry_query": info["retry_query"]} + if info.get("code") == "query_cursor_stale" and "retry_query" in info else {}) out = _tool_refusal(name, info.get("code", "tool_refused"), - info.get("message", "The app refused this operation."), exc.status_code) + info.get("message", "The app refused this operation."), exc.status_code, **retry) except (TypeError, ValueError, KeyError, AttributeError): out = _tool_refusal(name, "tool_arguments_invalid", "The arguments could not be read. Use the published input schema.") except Exception: out = _tool_refusal(name, "tool_unavailable", "The tool could not complete this operation.", 503) - return _mcp_content(rid, out) + return _mcp_content(rid, out, session) @router.post("/mcp") @@ -3392,8 +4862,7 @@ async def external_mcp(request: Request, session: Session = Depends(require_exte try: req = await request.json() except (ValueError, UnicodeError): - return {"jsonrpc": "2.0", "id": None, - "error": {"code": -32700, "message": "The request body must be valid JSON."}} + return _mcp_protocol_error(None, -32700, "The request body must be valid JSON.") reply = await run_in_threadpool(_handle_mcp, req, session, str(request.base_url)) return Response(status_code=204) if reply is None else reply @@ -3409,16 +4878,23 @@ _WRITE_TOOLS = frozenset({ "view_upsert", "view_delete", "app_upsert", "app_delete", "database_object", "view_object", "workbook_object", "worksheet_object", "range_object", "calculation_object", "validated_batch", + "confirm_change", }) -def _assert_write_allow_list() -> None: +def _assert_write_allow_list(*, check_groups=False) -> None: declared = {name for name, tool in external_tools.TOOLS.items() if tool.get("write")} undeclared = declared - _WRITE_TOOLS stale = _WRITE_TOOLS - declared if undeclared or stale: raise RuntimeError("External write allow-list mismatch: undeclared=" + repr(sorted(undeclared)) + ", stale=" + repr(sorted(stale))) + if check_groups: + import tool_groups + mapped = {entry.get("legacy_name") for group in tool_groups.groups().values() + for entry in group["actions"].values()} + if set(external_tools.TOOLS) - mapped - {"confirm_change"}: + raise RuntimeError("Every legacy tool must have a grouped action") _assert_write_allow_list() @@ -3442,6 +4918,22 @@ def oauth_resource_metadata_rfc(request: Request): return oauth_resource_metadata(request) +@_discovery_router.get("/.well-known/agent-card.json") +def agent_card_discovery(request: Request, response: Response, + authorization: str | None = Header(default=None, alias="Authorization")): + """Serve the selected workspace's card when its provider is installed.""" + try: + provider = importlib.import_module("agent_card") + except ModuleNotFoundError as exc: + if exc.name != "agent_card": + raise + raise err(404, "agent_card_unavailable", "The Agent Card is not available.") from exc + session = (require_external_analyst(require_external_session(authorization, request)) + if authorization is not None else require_session(request, response)) + response.headers["Cache-Control"] = "private, no-store" + return provider.build(session.runtime, str(request.base_url).rstrip("/")) + + # The PUBLIC skill.md at the site root, like Monid's `monid.ai/SKILL.md`: an agent told # "set up /skill.md" reads it with no session. It is the session-free document, so it # carries no tenant, database or field name; `/api/v1/external/skill.md` keeps the per-user one.