feat(decisions): metadata field + grant-on-install consent backend (#1429)

Backend for the app permission consent flow (#56), per Jay's answers (forks 31-34):
- Decisions gain an optional metadata JSON column (guarded ALTER migration
  mirroring board_audit; in _JSON_FIELDS; create() passthrough; DecisionIn field).
- capabilities.py: CAPABILITY_DESCRIPTIONS (one human line per known cap) +
  describe_capability() handling network:<origin> and unknowns.
- app_permissions.app_grant_decision_payload(): builds the multi_select consent
  card (options = requested caps, metadata.kind = app_grant). Not wired into
  install yet (live-verify session).
- answer route: _apply_app_grant side-effect writes granted (selected) / denied
  (rest) per capability to the existing app_grants ledger, best-effort.

Reuses the existing AppGrantsStore (app.state.app_grants, #1404/#1405). Tests:
metadata round-trip, metadata echo, app_grant answer writes grants, payload
builder, full capability-description coverage. 61 related tests pass.

Author: jaylfc

tests/test_app_capabilities.py

@@ -2,9 +2,11 @@
 import pytest
 
 from tinyagentos.userspace.capabilities import (
+    CAPABILITY_DESCRIPTIONS,
     FREE_CAPS,
     GATED_CAPS,
     KNOWN_CAPS,
+    describe_capability,
     is_known_capability,
 )
 from tinyagentos.userspace.package import PackageError, parse_manifest
@@ -15,6 +17,20 @@ def test_known_caps_is_free_plus_gated_and_disjoint():
     assert FREE_CAPS.isdisjoint(GATED_CAPS)
 
 
+def test_every_known_cap_has_a_description():
+    # The consent card renders one line per capability; a missing description
+    # would show an empty/raw row, so coverage is enforced.
+    for cap in KNOWN_CAPS:
+        assert CAPABILITY_DESCRIPTIONS.get(cap), f"no description for {cap}"
+
+
+def test_describe_capability_handles_bare_network_and_unknown():
+    assert describe_capability("app.net") == CAPABILITY_DESCRIPTIONS["app.net"]
+    assert describe_capability("network:https://x.com") == "Connect to https://x.com"
+    # Unknown tokens fall back to the raw string rather than an empty row.
+    assert describe_capability("app.bogus") == "app.bogus"
+
+
 def test_broker_reexports_the_same_sets():
     # The broker must enforce the exact vocabulary the parser validates against.
     from tinyagentos.userspace import broker

tests/test_decision_store.py

@@ -33,6 +33,19 @@ async def test_invalid_type_rejected(store):
         await store.create("@a", "q", "bogus_type")
 
 
+@pytest.mark.asyncio
+async def test_metadata_round_trips(store):
+    meta = {"kind": "app_grant", "app_id": "stream-chat", "capabilities": ["app.net"]}
+    d = await store.create("@a", "grant?", "multi_select",
+                           options=[{"label": "Net", "value": "app.net"}], metadata=meta)
+    assert d["metadata"] == meta
+    got = await store.get(d["id"])
+    assert got["metadata"] == meta
+    # Omitted metadata defaults to an empty dict, not None.
+    d2 = await store.create("@a", "q", "free_text")
+    assert d2["metadata"] == {}
+
+
 @pytest.mark.asyncio
 async def test_list_filters(store):
     await store.create("@a", "q1", "approve_deny", project_id="p1", user_id="u1")

tests/test_routes_decisions.py

@@ -137,6 +137,52 @@ async def test_duplicate_labels_get_distinct_values(client):
     assert resp.json()["answer"]["value"] == [one]
 
 
+@pytest.mark.asyncio
+async def test_metadata_echoed_on_create(client):
+    resp = await client.post("/api/decisions", json={
+        "from_agent": "@a", "question": "q", "type": "free_text",
+        "metadata": {"kind": "app_grant", "app_id": "x", "capabilities": ["app.net"]},
+    })
+    assert resp.status_code == 200
+    assert resp.json()["metadata"]["app_id"] == "x"
+
+
+@pytest.mark.asyncio
+async def test_app_grant_answer_writes_grants(client):
+    # An app-grant consent Decision (metadata.kind == app_grant): answering the
+    # multi_select with a subset writes granted for the picked caps and denied
+    # for the rest to the app_grants ledger.
+    app = client._transport.app
+    resp = await client.post("/api/decisions", json={
+        "from_agent": "@taos-app-install", "question": "stream-chat permissions",
+        "type": "multi_select",
+        "options": [{"label": "Net", "value": "app.net"},
+                    {"label": "Memory", "value": "app.memory"}],
+        "metadata": {"kind": "app_grant", "app_id": "stream-chat",
+                     "capabilities": ["app.net", "app.memory"]},
+    })
+    d = resp.json()
+    resp = await client.post(f"/api/decisions/{d['id']}/answer", json={"value": ["app.net"]})
+    assert resp.status_code == 200
+    user_id = d["user_id"]
+    granted = await app.state.app_grants.granted_capabilities(user_id, "stream-chat")
+    assert granted == {"app.net"}
+    grants = {g["capability"]: g["decision"]
+              for g in await app.state.app_grants.list_grants(user_id, "stream-chat")}
+    assert grants == {"app.net": "granted", "app.memory": "denied"}
+
+
+@pytest.mark.asyncio
+async def test_app_grant_payload_builder():
+    from tinyagentos.routes.app_permissions import app_grant_decision_payload
+    payload = app_grant_decision_payload("stream-chat", ["app.net", "app.memory"])
+    assert payload["type"] == "multi_select"
+    assert payload["metadata"] == {"kind": "app_grant", "app_id": "stream-chat",
+                                   "capabilities": ["app.net", "app.memory"]}
+    assert [o["value"] for o in payload["options"]] == ["app.net", "app.memory"]
+    assert payload["options"][0]["label"]
+
+
 @pytest.mark.asyncio
 async def test_answer_routes_back_to_bus_agent(client, monkeypatch):
     import tinyagentos.routes.decisions as dmod

tinyagentos/decisions/decision_store.py

@@ -36,14 +36,15 @@
     deadline           REAL,
     checkpoint_ref     TEXT,
     parent_decision_id TEXT,
-    timeline_id        TEXT
+    timeline_id        TEXT,
+    metadata           TEXT NOT NULL DEFAULT '{}'
 );
 CREATE INDEX IF NOT EXISTS idx_decisions_status ON decisions(status, created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_decisions_project ON decisions(project_id, status);
 CREATE INDEX IF NOT EXISTS idx_decisions_user ON decisions(user_id, status);
 """
 
-_JSON_FIELDS = ("options", "answer")
+_JSON_FIELDS = ("options", "answer", "metadata")
 
 
 def _row_to_decision(row, description) -> dict:
@@ -57,6 +58,22 @@ def _row_to_decision(row, description) -> dict:
 class DecisionStore(BaseStore):
     SCHEMA = DECISIONS_SCHEMA
 
+    async def _post_init(self) -> None:
+        # `metadata` was added after the initial decisions ship. Guarded ALTER
+        # so existing databases gain it without a destructive migration (SQLite
+        # lacks ADD COLUMN IF NOT EXISTS before 3.37). Mirrors board_audit.py.
+        cols = {
+            row[1]
+            for row in await (
+                await self._db.execute("PRAGMA table_info(decisions)")
+            ).fetchall()
+        }
+        if "metadata" not in cols:
+            await self._db.execute(
+                "ALTER TABLE decisions ADD COLUMN metadata TEXT NOT NULL DEFAULT '{}'"
+            )
+            await self._db.commit()
+
     async def create(
         self,
         from_agent: str,
@@ -72,6 +89,7 @@ async def create(
         parent_decision_id: str | None = None,
         checkpoint_ref: str | None = None,
         timeline_id: str | None = None,
+        metadata: dict | None = None,
     ) -> dict:
         if type not in DECISION_TYPES:
             raise ValueError(f"invalid decision type: {type!r}")
@@ -83,11 +101,12 @@ async def create(
             """INSERT INTO decisions
                (id, from_agent, project_id, user_id, question, type, options, context,
                 priority, status, created_at, deadline, parent_decision_id,
-                checkpoint_ref, timeline_id)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?)""",
+                checkpoint_ref, timeline_id, metadata)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?)""",
             (did, from_agent, project_id, user_id, question, type,
              json.dumps(options or []), context, priority, now, deadline,
-             parent_decision_id, checkpoint_ref, timeline_id),
+             parent_decision_id, checkpoint_ref, timeline_id,
+             json.dumps(metadata or {})),
         )
         await self._db.commit()
         return await self.get(did)

tinyagentos/routes/app_permissions.py

@@ -19,13 +19,38 @@
 from tinyagentos.auth_context import CurrentUser, current_user
 from tinyagentos.userspace.capabilities import (
     NET_PREFIX,
+    describe_capability,
     is_known_capability,
     is_valid_network_grant,
 )
 
 router = APIRouter()
 
 
+def app_grant_decision_payload(app_id: str, capabilities: list[str]) -> dict:
+    """Build the grant-on-install consent Decision for an app (#56, decision 6).
+
+    A multi_select card where each requested capability is an option the user
+    grants or leaves unchecked; metadata.kind == "app_grant" routes the answer
+    to the app_grants ledger (see _apply_app_grant in routes/decisions.py).
+    Returned as kwargs for DecisionStore.create / POST /api/decisions. The
+    install flow constructs and posts this; it is not wired into install yet."""
+    return {
+        "from_agent": "@taos-app-install",
+        "question": f"{app_id} would like these permissions",
+        "type": "multi_select",
+        "priority": "blocking",
+        "options": [
+            {"label": describe_capability(c), "value": c} for c in capabilities
+        ],
+        "metadata": {
+            "kind": "app_grant",
+            "app_id": app_id,
+            "capabilities": list(capabilities),
+        },
+    }
+
+
 class GrantIn(BaseModel):
     capability: str
     decision: str = "granted"  # "granted" or "denied"

tinyagentos/routes/decisions.py

@@ -12,7 +12,7 @@
 import httpx
 from fastapi import APIRouter, Depends, Request
 from fastapi.responses import JSONResponse
-from pydantic import BaseModel, model_validator
+from pydantic import BaseModel, Field, model_validator
 
 from tinyagentos.auth_context import CurrentUser, current_user
 from tinyagentos.decisions.decision_store import DECISION_TYPES, PRIORITIES
@@ -89,6 +89,7 @@ class DecisionIn(BaseModel):
     parent_decision_id: str | None = None
     checkpoint_ref: str | None = None
     timeline_id: str | None = None
+    metadata: dict = Field(default_factory=dict)
 
     @model_validator(mode="after")
     def _dedupe_option_values(self) -> "DecisionIn":
@@ -147,6 +148,7 @@ async def create_decision(body: DecisionIn, request: Request, user: CurrentUser
         parent_decision_id=parent_id,
         checkpoint_ref=body.checkpoint_ref,
         timeline_id=body.timeline_id,
+        metadata=body.metadata,
     )
 
     # Mark the parent superseded only after the replacement is persisted.
@@ -244,5 +246,33 @@ async def answer_decision(decision_id: str, body: AnswerIn, request: Request, us
     updated = await store.answer(decision_id, body.value, answered_by)
     if updated is None:
         return JSONResponse({"error": "already answered or not pending"}, status_code=409)
+    await _apply_app_grant(request, updated, body.value)
     await _route_answer_to_agent(updated, body.value)
     return updated
+
+
+async def _apply_app_grant(request: Request, decision: dict, value) -> None:
+    """Side effect for an app-grant consent Decision: write the per-capability
+    grant decisions to the app_grants ledger. The decision's metadata carries
+    {kind: "app_grant", app_id, capabilities}; for the multi_select consent card
+    the answer is the list of granted capability values, so the rest are denied.
+    Best-effort: the answer is already persisted, so a grant-store hiccup must
+    not fail the answer."""
+    meta = decision.get("metadata") or {}
+    if meta.get("kind") != "app_grant":
+        return
+    grants = getattr(request.app.state, "app_grants", None)
+    app_id = meta.get("app_id")
+    caps = meta.get("capabilities") or []
+    if grants is None or not app_id:
+        return
+    user_id = decision.get("user_id") or ""
+    granted = set(value if isinstance(value, list) else [value])
+    try:
+        for cap in caps:
+            await grants.set_decision(
+                user_id, app_id, cap,
+                decision="granted" if cap in granted else "denied",
+            )
+    except Exception:
+        pass

tinyagentos/userspace/capabilities.py

@@ -56,3 +56,32 @@ def is_known_capability(perm: str) -> bool:
     if not isinstance(perm, str):
         return False
     return perm in KNOWN_CAPS or perm.startswith(NET_PREFIX)
+
+
+# One-line, human, non-technical description per capability, for the consent
+# card (mirrors the agent SCOPE_DESCRIPTIONS). Every entry in KNOWN_CAPS has
+# one; the test_capabilities suite enforces full coverage. Copy is a draft to
+# be reworded by product.
+CAPABILITY_DESCRIPTIONS: dict[str, str] = {
+    "app.kv": "Store and read its own app data",
+    "app.table": "Store and read its own structured data",
+    "app.files": "Read and write files in its own app folder",
+    "app.notify": "Send you notifications",
+    "app.window": "Open and manage its own windows",
+    "app.net": "Connect to the internet",
+    "app.agent": "Ask your taOS agent for help",
+    "app.llm": "Use a language model",
+    "app.memory": "Read and write your memories",
+}
+
+
+def describe_capability(perm: str) -> str:
+    """A human one-liner for a capability, for the consent card.
+
+    Bare caps map through CAPABILITY_DESCRIPTIONS; a `network:<origin>` grant
+    renders as "Connect to <origin>"; anything unrecognised falls back to the
+    raw token so the card never shows an empty row.
+    """
+    if isinstance(perm, str) and perm.startswith(NET_PREFIX):
+        return f"Connect to {perm[len(NET_PREFIX):]}"
+    return CAPABILITY_DESCRIPTIONS.get(perm, perm)