Deploy AIOS web (React glide grid + FastAPI slice)
Browse filesThis view is limited to 50 files because it contains too many changes. Β See raw diff
- RELEASES.json +13 -1
- VERSION +1 -1
- api/ai_review.py +591 -591
- api/connectors_tt.py +568 -568
- api/providers.py +0 -0
- api/routes_agent_harness.py +455 -455
- api/routes_keychain.py +0 -0
- api/routes_oauth.py +114 -114
- api/routes_records.py +211 -211
- api/routes_script_views.py +439 -439
- api/routes_slack.py +789 -789
- api/routes_statements.py +298 -298
- api/routes_web_agent.py +84 -84
- platform/core/script_sandbox.py +519 -519
- platform/core/store.py +0 -0
- platform/harness/meta_store.py +521 -521
- platform/model/metrics/sales.yml +149 -149
- platform/model/topics/odoo_accounts.yml +60 -60
- platform/model/topics/odoo_agents.yml +91 -91
- platform/model/topics/odoo_bills.yml +86 -86
- platform/model/topics/odoo_invoices.yml +98 -98
- platform/model/topics/odoo_orders.yml +87 -87
- platform/model/topics/odoo_vendors.yml +103 -103
- platform/modules/agent.py +385 -385
- platform/modules/collections_send.py +267 -267
- requirements.txt +55 -55
- web/index.html +46 -46
- web/src/App.tsx +41 -41
- web/src/account/SubscriptionPage.tsx +49 -49
- web/src/account/UsagePage.tsx +297 -297
- web/src/account/account.css +371 -371
- web/src/account/accountApi.ts +188 -188
- web/src/alerts/alertsModel.ts +418 -418
- web/src/automation/AutomationFind.tsx +893 -893
- web/src/automation/HarnessPanel.tsx +413 -413
- web/src/automation/PresetPlan.tsx +122 -122
- web/src/automation/automation.css +556 -556
- web/src/connectors/brandMarks.tsx +413 -413
- web/src/customer-grid/GridChat.tsx +512 -512
- web/src/customer-grid/ImportDialog.css +154 -154
- web/src/customer-grid/ImportDialog.tsx +299 -299
- web/src/customer-grid/SwipeView.tsx +586 -586
- web/src/customer-grid/chatDock.css +48 -48
- web/src/customer-grid/gridChat.css +294 -294
- web/src/customer-grid/gridChat.ts +461 -461
- web/src/customer-grid/scriptView.css +509 -509
- web/src/customer-grid/scriptViews.ts +387 -387
- web/src/customer-grid/viewEcho.ts +272 -272
- web/src/index.css +5 -5
- web/src/manage-agent/agentsApi.ts +143 -143
RELEASES.json
CHANGED
|
@@ -1,6 +1,18 @@
|
|
| 1 |
{
|
| 2 |
-
"current": "
|
| 3 |
"releases": [
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4 |
{
|
| 5 |
"version": "v56",
|
| 6 |
"sha": "2970b72",
|
|
|
|
| 1 |
{
|
| 2 |
+
"current": "c526ced",
|
| 3 |
"releases": [
|
| 4 |
+
{
|
| 5 |
+
"version": "v58",
|
| 6 |
+
"sha": "c526ced",
|
| 7 |
+
"date": "2026-08-29",
|
| 8 |
+
"subject": "release v58"
|
| 9 |
+
},
|
| 10 |
+
{
|
| 11 |
+
"version": "v57",
|
| 12 |
+
"sha": "4859c03",
|
| 13 |
+
"date": "2026-08-29",
|
| 14 |
+
"subject": "release v57"
|
| 15 |
+
},
|
| 16 |
{
|
| 17 |
"version": "v56",
|
| 18 |
"sha": "2970b72",
|
VERSION
CHANGED
|
@@ -1 +1 @@
|
|
| 1 |
-
|
|
|
|
| 1 |
+
c526ced
|
api/ai_review.py
CHANGED
|
@@ -1,591 +1,591 @@
|
|
| 1 |
-
"""AI REVIEW β let a model decide which stage a card moves to (wave 23, owner ruling R4/R14).
|
| 2 |
-
|
| 3 |
-
β WHAT THIS IS. A review stage holds a record until somebody decides where it goes next. R4 made
|
| 4 |
-
that somebody optionally a MODEL: the engine hands over the record's own values, the review's
|
| 5 |
-
prompt, and the list of stages the review is allowed to send a card to, and gets back ONE of
|
| 6 |
-
those stage labels plus a one-line reason. Every decision is written to the same `reviews` audit
|
| 7 |
-
log a human click writes to, tagged `by: "ai"` with the provider and model that made it.
|
| 8 |
-
|
| 9 |
-
β FAIL-CLOSED IN EVERY DIRECTION, and this is the whole safety story. No key configured, a
|
| 10 |
-
network failure, a slow answer, a malformed answer, or an answer naming a stage the review does
|
| 11 |
-
not offer β all return `("", {...})`, and the caller leaves the card exactly where a human would
|
| 12 |
-
have found it. The feature can be absent, broken or wrong and the worst outcome is a person doing
|
| 13 |
-
the work. Nothing here can move a card somewhere the review does not already permit.
|
| 14 |
-
|
| 15 |
-
β CHEAP FIRST (owner R14, verbatim: *"Claude is a bit too expensive"*). The ladder is
|
| 16 |
-
`groq β cerebras β openrouter β anthropic`; the first CONFIGURED provider wins, and Anthropic is
|
| 17 |
-
last rather than absent β it is the quality backstop, not the default. `AIOS_AI_REVIEW_PROVIDER`
|
| 18 |
-
pins one; `AIOS_AI_MODEL` overrides the model.
|
| 19 |
-
|
| 20 |
-
ββ THE ANTHROPIC LEG IS ON THE OFFICIAL SDK NOW (D-346, W37-T39, 2026-08-19). β THIS PARAGRAPH
|
| 21 |
-
USED TO ARGUE THE OPPOSITE and is rewritten rather than deleted, because a comment left asserting
|
| 22 |
-
the reverse of its own code is [[two-gates-can-assert-opposite-things]] with no gate to catch it.
|
| 23 |
-
The retired text said raw HTTP was *"a deliberate deviation β¦ booked as a DEBT line so the
|
| 24 |
-
integrator can overturn it deliberately rather than by drift"*. This is that overturn.
|
| 25 |
-
|
| 26 |
-
Its two reasons were real and are both answered rather than waved away:
|
| 27 |
-
1. *"one SDK leg beside three hand-rolled ones is two implementations of the same call."* It is
|
| 28 |
-
not, because the leg does not live here: `providers.anthropic_send` owns the wire, prefers
|
| 29 |
-
the SDK, and normalises BOTH transports to one `(status, body)` pair. This file gained no
|
| 30 |
-
Anthropic knowledge β it lost some.
|
| 31 |
-
2. *"adding a pinned dependency rebuilds the container, a real deploy risk."* Still true, so the
|
| 32 |
-
import is LAZY and its absence is a FALLBACK, not a crash: with no `anthropic` package the
|
| 33 |
-
same raw POST runs and `LAST_ANTHROPIC_TRANSPORT` reports `'http'`. The pin is owed in BOTH
|
| 34 |
-
manifests ([[pin-deps-space-rebuilds]]) and is outside every worker fence this wave.
|
| 35 |
-
β The other three legs stay OpenAI-chat-shaped over `requests` β they have no shared SDK, and that
|
| 36 |
-
half of the original reasoning never expired.
|
| 37 |
-
|
| 38 |
-
The Messages shape below is the current one: `x-api-key` + `anthropic-version: 2023-06-01`, and
|
| 39 |
-
`stop_reason: "refusal"` is checked BEFORE reading `content` β a refusal answers HTTP 200 with an
|
| 40 |
-
empty content list, so code that indexes `content[0]` unconditionally breaks on it.
|
| 41 |
-
"""
|
| 42 |
-
from __future__ import annotations
|
| 43 |
-
|
| 44 |
-
import json
|
| 45 |
-
import os
|
| 46 |
-
import re
|
| 47 |
-
|
| 48 |
-
import requests
|
| 49 |
-
|
| 50 |
-
#: The ladder. Order IS the policy (R14) β cheapest capable first, Anthropic last.
|
| 51 |
-
PROVIDERS = [
|
| 52 |
-
# ββ D-345, FIXED W37-T39 (2026-08-19). This read `llama-3.3-70b-versatile` and Groq RETIRED
|
| 53 |
-
# it: a real POST with the live key answers HTTP 404 `model_not_found`, and the id is absent
|
| 54 |
-
# from `GET /openai/v1/models`. β THE `openai/` PREFIX IS PART OF GROQ'S ID and is NOT a typo
|
| 55 |
-
# for the cerebras rung below, which serves the same family bare as `gpt-oss-120b`.
|
| 56 |
-
{"name": "groq", "env": "GROQ_API_KEY", "shape": "openai",
|
| 57 |
-
"url": "https://api.groq.com/openai/v1/chat/completions",
|
| 58 |
-
"model": "openai/gpt-oss-120b"},
|
| 59 |
-
{"name": "cerebras", "env": "CEREBRAS_API_KEY", "shape": "openai",
|
| 60 |
-
"url": "https://api.cerebras.ai/v1/chat/completions",
|
| 61 |
-
"model": "gpt-oss-120b"},
|
| 62 |
-
{"name": "openrouter", "env": "OPENROUTER_API_KEY", "shape": "openai",
|
| 63 |
-
"url": "https://openrouter.ai/api/v1/chat/completions",
|
| 64 |
-
"model": "openai/gpt-4o-mini"},
|
| 65 |
-
# β haiku-class DELIBERATELY, not the default Opus tier: R14 put Anthropic on this ladder as
|
| 66 |
-
# the backstop for a one-line classification, and this is the cheapest current Claude that
|
| 67 |
-
# does it well. A bigger model here would be spending the owner's money to pick between two
|
| 68 |
-
# labels it already has in front of it.
|
| 69 |
-
{"name": "anthropic", "env": "ANTHROPIC_API_KEY", "shape": "anthropic",
|
| 70 |
-
"url": "https://api.anthropic.com/v1/messages",
|
| 71 |
-
# β AN ENV LEVER, NOT A NEW DEFAULT (W36-T35): haiku stays the choice for the reasons above,
|
| 72 |
-
# and a deployment whose side rungs are out of credit can raise the tier without a release.
|
| 73 |
-
"model": os.environ.get("AIOS_AI_REVIEW_ANTHROPIC_MODEL") or "claude-haiku-4-5"},
|
| 74 |
-
]
|
| 75 |
-
ANTHROPIC_VERSION = "2023-06-01"
|
| 76 |
-
TIMEOUT_SECONDS = float(os.environ.get("AIOS_AI_REVIEW_TIMEOUT") or 20)
|
| 77 |
-
MAX_FIELD_CHARS = 200 # per value handed to the model
|
| 78 |
-
MAX_FIELDS = 30 # columns handed to the model
|
| 79 |
-
MAX_REASON = 200
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
def ladder():
|
| 83 |
-
"""The providers that are actually usable here, in order. Empty = the feature is off."""
|
| 84 |
-
pin = (os.environ.get("AIOS_AI_REVIEW_PROVIDER") or "").strip().lower()
|
| 85 |
-
live = [p for p in PROVIDERS if (os.environ.get(p["env"]) or "").strip()]
|
| 86 |
-
if pin:
|
| 87 |
-
live = [p for p in live if p["name"] == pin]
|
| 88 |
-
return live
|
| 89 |
-
|
| 90 |
-
|
| 91 |
-
def configured():
|
| 92 |
-
return bool(ladder())
|
| 93 |
-
|
| 94 |
-
|
| 95 |
-
def _record_text(row, fields):
|
| 96 |
-
"""The record, as the model sees it. Values are truncated and the column set is bounded β
|
| 97 |
-
an automation table can carry a 32 KB JSON blob per row (C7) and a review decision does not
|
| 98 |
-
need it. Machine bookkeeping columns are dropped: a stage cell naming the stage the card is
|
| 99 |
-
sitting at would be the model reading its own question back."""
|
| 100 |
-
keys = [k for k in (fields or list((row or {}).keys()))
|
| 101 |
-
if not str(k).startswith("stage_")][:MAX_FIELDS]
|
| 102 |
-
lines = []
|
| 103 |
-
for k in keys:
|
| 104 |
-
v = (row or {}).get(k)
|
| 105 |
-
if v is None or str(v).strip() == "":
|
| 106 |
-
continue
|
| 107 |
-
lines.append(f"{k}: {str(v)[:MAX_FIELD_CHARS]}")
|
| 108 |
-
return "\n".join(lines) or "(this record has no filled-in values)"
|
| 109 |
-
|
| 110 |
-
|
| 111 |
-
def _instruction(prompt, options, label):
|
| 112 |
-
return (
|
| 113 |
-
f"You are deciding what happens to one record waiting at a review step called "
|
| 114 |
-
f"{label!r} in a workflow.\n\n"
|
| 115 |
-
f"The person who built this workflow told you: {prompt}\n\n"
|
| 116 |
-
f"Choose EXACTLY ONE of these next steps, by its exact name:\n"
|
| 117 |
-
+ "\n".join(f"- {o}" for o in options)
|
| 118 |
-
+ "\n\nAnswer with one line of JSON and nothing else:\n"
|
| 119 |
-
'{"choice": "<one name from the list above>", "reason": "<one short sentence>"}\n'
|
| 120 |
-
"If the record does not give you enough to decide, answer "
|
| 121 |
-
'{"choice": "", "reason": "why not"} and a person will decide instead.'
|
| 122 |
-
)
|
| 123 |
-
|
| 124 |
-
|
| 125 |
-
def _parse(text, options):
|
| 126 |
-
"""The model's line β `(choice, reason)`. A choice that is not one of the offered stages is
|
| 127 |
-
DISCARDED, not fuzzy-matched: the offered list is a permission boundary, and a near-miss
|
| 128 |
-
resolved by string distance is how a card ends up somewhere nobody authorised."""
|
| 129 |
-
raw = str(text or "").strip()
|
| 130 |
-
obj = None
|
| 131 |
-
m = re.search(r"\{.*\}", raw, re.S)
|
| 132 |
-
if m:
|
| 133 |
-
try:
|
| 134 |
-
obj = json.loads(m.group(0))
|
| 135 |
-
except (ValueError, TypeError):
|
| 136 |
-
obj = None
|
| 137 |
-
if not isinstance(obj, dict):
|
| 138 |
-
return "", ""
|
| 139 |
-
choice = str(obj.get("choice") or "").strip()
|
| 140 |
-
reason = str(obj.get("reason") or "").strip()[:MAX_REASON]
|
| 141 |
-
for opt in options:
|
| 142 |
-
if choice.lower() == str(opt).lower():
|
| 143 |
-
return str(opt), reason # the OFFERED spelling wins, never the model's
|
| 144 |
-
return "", reason
|
| 145 |
-
|
| 146 |
-
|
| 147 |
-
# ββ WAVE 35 Β· W35-T41 / C7 β THE TWO TRANSPORTS RETURN THE RESPONSE BODY'S `usage`.
|
| 148 |
-
#
|
| 149 |
-
# β THIS FILE'S OWN HEADER USED TO BE THE PRODUCT'S CONFESSION THAT NOTHING COUNTED: `ai_enrich`'s
|
| 150 |
-
# docstring says *"`ai_review.decide` -- the product's only other LLM entry -- has no token
|
| 151 |
-
# accounting of ANY kind"*. R9 asks for ONE meter for every AI surface, so the counting has to reach
|
| 152 |
-
# this transport rather than be bolted onto its caller β the caller never sees the body.
|
| 153 |
-
#
|
| 154 |
-
# β A THIRD RETURN VALUE, NOT A MUTATED ARGUMENT, and both call sites are in `decide` below. The
|
| 155 |
-
# tuple grew from `(text, err)` to `(text, err, usage)`; `usage` is the raw `usage` OBJECT (or None),
|
| 156 |
-
# because reading it is `usage_ledger`'s job and a second reader here would be the two-normalizers
|
| 157 |
-
# shape this repo keeps paying for.
|
| 158 |
-
def _call_openai(p, model, system, user, timeout):
|
| 159 |
-
r = requests.post(p["url"], timeout=timeout,
|
| 160 |
-
headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
|
| 161 |
-
"Content-Type": "application/json"},
|
| 162 |
-
json={"model": model, "max_tokens": 300, "temperature": 0,
|
| 163 |
-
"messages": [{"role": "system", "content": system},
|
| 164 |
-
{"role": "user", "content": user}]})
|
| 165 |
-
if r.status_code >= 400:
|
| 166 |
-
# β NO BODY ON A 4xx/5xx: an error envelope carries no usage, and a provider that refused
|
| 167 |
-
# before running the model has nothing to bill. The call is still COUNTED by `decide`.
|
| 168 |
-
return "", f"{p['name']} answered {r.status_code}", None
|
| 169 |
-
body = r.json()
|
| 170 |
-
choices = body.get("choices") or []
|
| 171 |
-
if not choices:
|
| 172 |
-
return "", f"{p['name']} returned no choices", body
|
| 173 |
-
return str(((choices[0] or {}).get("message") or {}).get("content") or ""), "", body
|
| 174 |
-
|
| 175 |
-
|
| 176 |
-
#: What transport the last Anthropic call actually used: `'sdk'`, `'http'`, or `''` before any.
|
| 177 |
-
#: β PROCESS-LOCAL AND FOR REPORTING ONLY. It exists so `GET /meta` and `verify_web_agent` can say
|
| 178 |
-
#: WHICH path ran rather than inferring it from a requirements file nobody in this lane can edit.
|
| 179 |
-
LAST_ANTHROPIC_TRANSPORT = ""
|
| 180 |
-
|
| 181 |
-
|
| 182 |
-
def _call_anthropic(p, model, system, user, timeout):
|
| 183 |
-
"""One classification turn on the Messages API, through `providers.anthropic_send`.
|
| 184 |
-
|
| 185 |
-
β D-346 (W37-T39): this used to hand-roll the POST. It now goes through the shared wire, which
|
| 186 |
-
prefers the OFFICIAL `anthropic` SDK and falls back to the same raw POST when the package is
|
| 187 |
-
absent. The shape of what comes back is unchanged, deliberately: `anthropic_send` normalises
|
| 188 |
-
both transports to `(status, body)`, so every line below this call is untouched.
|
| 189 |
-
"""
|
| 190 |
-
global LAST_ANTHROPIC_TRANSPORT
|
| 191 |
-
import providers as _prov # noqa: PLC0415
|
| 192 |
-
# β NO TOOLS ON THIS PATH. The builder omits `tool_choice` for exactly that case, so there is
|
| 193 |
-
# nothing to strip here β the rule lives in `anthropic_request`, beside the thing it constrains.
|
| 194 |
-
req = _prov.anthropic_request(
|
| 195 |
-
model=model, key=os.environ[p["env"]].strip(), system=system,
|
| 196 |
-
messages=[{"role": "user", "content": user}], tools=[], max_tokens=300)
|
| 197 |
-
status, body, transport = _prov.anthropic_send(req, timeout=timeout)
|
| 198 |
-
LAST_ANTHROPIC_TRANSPORT = transport
|
| 199 |
-
if status >= 400 or status == 0:
|
| 200 |
-
# β THE SENTENCE COMES FROM THE LADDER, NOT FROM HERE. `refusal_sentence` already names the
|
| 201 |
-
# vendor and the action for every status R4 enumerated, so a bare "anthropic answered 402"
|
| 202 |
-
# (which is what this line used to say, and what the owner quoted back at us) cannot recur.
|
| 203 |
-
return "", _prov.refusal_sentence("anthropic", status, json.dumps(body)[:400]), None
|
| 204 |
-
body = body or {}
|
| 205 |
-
# β stop_reason FIRST. A safety refusal is a successful 200 with an EMPTY content list, so
|
| 206 |
-
# reading content[0] before this check turns a refusal into an IndexError inside a run.
|
| 207 |
-
# β A refusal IS billed and its body carries `usage`, so the body rides back on this branch too.
|
| 208 |
-
if body.get("stop_reason") == "refusal":
|
| 209 |
-
return "", "anthropic declined to answer this record", body
|
| 210 |
-
parts = [b.get("text") or "" for b in (body.get("content") or [])
|
| 211 |
-
if isinstance(b, dict) and b.get("type") == "text"]
|
| 212 |
-
if not parts:
|
| 213 |
-
return "", "anthropic returned no text", body
|
| 214 |
-
return "".join(parts), "", body
|
| 215 |
-
|
| 216 |
-
|
| 217 |
-
def decide(*, prompt, options, row, fields=(), label="Review", timeout=None, st=None, user=""):
|
| 218 |
-
"""Pick this record's next stage. Returns `(choice, meta)`.
|
| 219 |
-
|
| 220 |
-
`choice` is "" whenever a person should decide β which is every failure mode there is.
|
| 221 |
-
`meta` carries `provider`, `model`, `reason` on success, and `problem` on refusal to answer.
|
| 222 |
-
|
| 223 |
-
β W35-T41 / C7 β `st` and `user` are the USAGE LEDGER's target. Both default to absent because
|
| 224 |
-
this function's caller is `automation_engine.ai_decide(rt, ...)`, in another lane's fence: it
|
| 225 |
-
HAS the runtime and does not pass it yet, so until it does, a review's tokens are counted as
|
| 226 |
-
unattributed and REPORTED by `GET /usage` rather than dropped. See `usage_ledger`'s header for
|
| 227 |
-
why they cannot be resolved implicitly (measured: a contextvar does not survive a FastAPI
|
| 228 |
-
dependency).
|
| 229 |
-
"""
|
| 230 |
-
import usage_ledger # noqa: PLC0415
|
| 231 |
-
opts = [str(o) for o in (options or []) if str(o).strip()]
|
| 232 |
-
if not opts:
|
| 233 |
-
return "", {"problem": "the review offers no next stages"}
|
| 234 |
-
if not str(prompt or "").strip():
|
| 235 |
-
return "", {"problem": "the review has no prompt for the model to follow"}
|
| 236 |
-
live = ladder()
|
| 237 |
-
if not live:
|
| 238 |
-
return "", {"problem": "no AI provider is configured on this deployment"}
|
| 239 |
-
system = _instruction(prompt, opts, label)
|
| 240 |
-
user = "Here is the record:\n\n" + _record_text(row, fields)
|
| 241 |
-
tmo = float(timeout or TIMEOUT_SECONDS)
|
| 242 |
-
override = (os.environ.get("AIOS_AI_MODEL") or "").strip()
|
| 243 |
-
problems = []
|
| 244 |
-
for p in live:
|
| 245 |
-
model = override or p["model"]
|
| 246 |
-
body = None
|
| 247 |
-
try:
|
| 248 |
-
text, err, body = (_call_anthropic if p["shape"] == "anthropic" else _call_openai)(
|
| 249 |
-
p, model, system, user, tmo)
|
| 250 |
-
except Exception as e: # noqa: BLE001
|
| 251 |
-
text, err = "", f"{p['name']} failed: {type(e).__name__}"
|
| 252 |
-
# ββ C7 β THE LEDGER LINE, BEFORE ANY BRANCH BELOW READS THE ANSWER.
|
| 253 |
-
# β IT IS WRITTEN ON EVERY OUTCOME THAT REACHED A PROVIDER, including a refusal and an
|
| 254 |
-
# unusable answer. A meter that books only successes reports a cheap week for a run that
|
| 255 |
-
# spent its budget being declined β and a declined call is billed. The only path that does
|
| 256 |
-
# NOT record is a transport that never reached the vendor (`body is None`), which spent
|
| 257 |
-
# nothing.
|
| 258 |
-
if body is not None:
|
| 259 |
-
ins, outs = usage_ledger.tokens_from(body)
|
| 260 |
-
usage_ledger.record("ai_review", p["name"], model, ins, outs,
|
| 261 |
-
total=usage_ledger.total_from(body), st=st, user=user)
|
| 262 |
-
if err:
|
| 263 |
-
problems.append(err)
|
| 264 |
-
continue # ladder: a dead provider degrades to the next one
|
| 265 |
-
choice, reason = _parse(text, opts)
|
| 266 |
-
if not choice:
|
| 267 |
-
# The provider ANSWERED and declined (or answered unusably). That is a decision about
|
| 268 |
-
# this record, not a fault in the provider, so it does NOT fall through to a more
|
| 269 |
-
# expensive one β the card goes to a human, which is what the model just asked for.
|
| 270 |
-
return "", {"provider": p["name"], "model": model,
|
| 271 |
-
"problem": reason or "the model did not choose one of the stages"}
|
| 272 |
-
return choice, {"provider": p["name"], "model": model, "reason": reason}
|
| 273 |
-
return "", {"problem": "; ".join(problems)[:300] or "no provider answered"}
|
| 274 |
-
|
| 275 |
-
|
| 276 |
-
# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ the FLOW WRITER
|
| 277 |
-
# ββ WAVE 33 Β· W33-T54/T55 (owner item 7, ruling R3) β A PROMPT BECOMES A DRAFT AUTOMATION.
|
| 278 |
-
#
|
| 279 |
-
# Owner, verbatim: *"lay out the foundation with custom tools we provide"* β and the tools are the
|
| 280 |
-
# action catalog, which has been machine-readable since wave 23. So this writes no new vocabulary:
|
| 281 |
-
# it hands the model the SAME `ACTION_CATALOG` the menu paints, the SAME `ACTION_REQUIRED` the
|
| 282 |
-
# runner blocks on, and the SAME trigger keys `clean_trigger` accepts, and asks for one JSON object
|
| 283 |
-
# in that vocabulary.
|
| 284 |
-
#
|
| 285 |
-
# β WHY IT LIVES IN `ai_review.py` RATHER THAN A NEW FILE. Two reasons, both about ownership. This
|
| 286 |
-
# is the one module in the API package that already holds an LLM ladder and its credentials, so a
|
| 287 |
-
# second one would be a second place a rotated key has to be noticed; and a new `routes_*.py` needs
|
| 288 |
-
# a `main.py` line from another lane (contract C2) to be reachable at all, which is how wave 23
|
| 289 |
-
# shipped three finished routers 404-dead behind green gates. The DOOR is a route on
|
| 290 |
-
# `routes_automation.py`, which is already mounted.
|
| 291 |
-
#
|
| 292 |
-
# ββ CONTRACT C7 IS THE DESIGN, NOT A CHECK AT THE END: *"the flow writer may emit only kinds
|
| 293 |
-
# present in `ACTION_CATALOG`, and its output must pass `clean_actions` unchanged."* Both halves are
|
| 294 |
-
# enforced mechanically rather than asked for politely β the kind list is an `enum` in the schema
|
| 295 |
-
# the model fills, and the caller runs `clean_actions` and DIFFS the result. That diff matters
|
| 296 |
-
# because `clean_actions` has no disclosure channel (D-75): it drops a key it does not recognise
|
| 297 |
-
# and answers 200, so a draft accepted without the diff would show a person a flow that is not the
|
| 298 |
-
# flow the model described, with nothing anywhere saying so.
|
| 299 |
-
#
|
| 300 |
-
# β `chat` IS INJECTABLE, exactly as `routes_query._call_model`'s is, and it is the reason this door
|
| 301 |
-
# can be proven end to end with no API key and no spend. A gate that can only run where a
|
| 302 |
-
# credential exists is a gate that never runs.
|
| 303 |
-
|
| 304 |
-
#: Cerebras first, NOT the cheap-first order `ladder()` uses. Same reason `routes_query` inverts it:
|
| 305 |
-
#: this contract includes a REFUSAL, and refusing honestly ("I cannot build that from the steps you
|
| 306 |
-
#: have") is a model property. A cheaper rung answers an impossible request with a plausible flow,
|
| 307 |
-
#: which is worse than no flow. Override with `AIOS_FLOW_PROVIDER`.
|
| 308 |
-
FLOW_PROVIDER_ORDER = ("cerebras", "groq", "openrouter", "anthropic")
|
| 309 |
-
MAX_DRAFT_ACTIONS = 12 # a draft a person reads in one screen; the engine's own cap is 25
|
| 310 |
-
MAX_PROMPT_CHARS = 2000
|
| 311 |
-
|
| 312 |
-
|
| 313 |
-
def flow_providers(pin=None):
|
| 314 |
-
"""The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off.
|
| 315 |
-
|
| 316 |
-
β `pin` IS ASK D-18 (2026-08-18): the Agent chat's model toggle must configure something, and
|
| 317 |
-
the draft door used to read `prompt` off the body and nothing else β so the key the client sent
|
| 318 |
-
was accepted and dropped, and the picker was a control over nothing.
|
| 319 |
-
β AN UNKNOWN OR UNCONFIGURED PIN FALLS BACK TO THE LADDER rather than refusing. A model the
|
| 320 |
-
ladder stopped offering must not turn every later draft into an error; the caller is told which
|
| 321 |
-
rung actually answered, which is the honest half.
|
| 322 |
-
"""
|
| 323 |
-
by_name = {p["name"]: p for p in PROVIDERS}
|
| 324 |
-
live = [n for n in FLOW_PROVIDER_ORDER
|
| 325 |
-
if n in by_name and (os.environ.get(by_name[n]["env"]) or "").strip()]
|
| 326 |
-
wanted = str(pin or os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
|
| 327 |
-
if wanted and wanted in live:
|
| 328 |
-
return [by_name[wanted]]
|
| 329 |
-
return [by_name[n] for n in live]
|
| 330 |
-
|
| 331 |
-
|
| 332 |
-
def flow_schema(kinds, trigger_keys, table_keys):
|
| 333 |
-
"""The tool schema the model fills β the catalog's OWN key lists as enums.
|
| 334 |
-
|
| 335 |
-
β `kind` AND `trigger` ARE ENUMS, not free strings, and that is C7's first half enforced by the
|
| 336 |
-
transport rather than by a check afterwards. A model asked for "any action name" invents
|
| 337 |
-
`send_slack_message` on a deployment that has no such kind, and the failure then surfaces as a
|
| 338 |
-
400 from `clean_actions` carrying a sentence about a word the person never typed.
|
| 339 |
-
β `required` IS `["kind"]` ALONE, deliberately: a REFUSAL carries no name and no actions, and a
|
| 340 |
-
schema demanding them turns an honest refusal into a provider-side 400 that reads exactly like a
|
| 341 |
-
transport failure (`routes_query._spec_schema` carries the same note, for the same measured
|
| 342 |
-
reason).
|
| 343 |
-
"""
|
| 344 |
-
return {
|
| 345 |
-
"type": "object",
|
| 346 |
-
"properties": {
|
| 347 |
-
"kind": {"type": "string", "enum": ["flow", "refused"],
|
| 348 |
-
"description": "refused = this cannot be built from the steps available"},
|
| 349 |
-
"refusal": {"type": "string",
|
| 350 |
-
"description": "when kind=refused: ONE plain sentence naming what is "
|
| 351 |
-
"missing, in the words a non-technical person would use"},
|
| 352 |
-
"name": {"type": "string", "description": "a short title for the automation"},
|
| 353 |
-
"trigger": {"type": "string", "enum": sorted(trigger_keys),
|
| 354 |
-
"description": "what starts this automation"},
|
| 355 |
-
"table": {"type": "string", "enum": sorted(table_keys),
|
| 356 |
-
"description": "the database whose records this flow walks, if any"},
|
| 357 |
-
"actions": {
|
| 358 |
-
"type": "array",
|
| 359 |
-
"maxItems": MAX_DRAFT_ACTIONS,
|
| 360 |
-
"items": {
|
| 361 |
-
"type": "object",
|
| 362 |
-
"properties": {
|
| 363 |
-
"kind": {"type": "string", "enum": sorted(kinds)},
|
| 364 |
-
"why": {"type": "string",
|
| 365 |
-
"description": "one short sentence: why this step is here"},
|
| 366 |
-
"config": {"type": "object", "additionalProperties": True,
|
| 367 |
-
"description": "the step's settings, using ONLY the keys named "
|
| 368 |
-
"for that kind in the system message"},
|
| 369 |
-
},
|
| 370 |
-
"required": ["kind"],
|
| 371 |
-
},
|
| 372 |
-
},
|
| 373 |
-
},
|
| 374 |
-
"required": ["kind"],
|
| 375 |
-
}
|
| 376 |
-
|
| 377 |
-
|
| 378 |
-
def flow_system_prompt(catalog, required, triggers, tables):
|
| 379 |
-
"""What the model is told it may build with β DERIVED, never written down twice.
|
| 380 |
-
|
| 381 |
-
Every list here is the server's own: the catalog rows the menu paints, the required-key table
|
| 382 |
-
the runner blocks on, the trigger keys `clean_trigger` accepts, and this tenant's real databases
|
| 383 |
-
with their real columns. Nothing about the vocabulary is restated by hand, so a kind added to
|
| 384 |
-
the catalog is offered here on the same deploy and a kind removed stops being offered.
|
| 385 |
-
"""
|
| 386 |
-
lines = ["You build small automations for a business tool. You are given the EXACT set of "
|
| 387 |
-
"steps this tool can perform. You may use nothing else.",
|
| 388 |
-
"", "THE STEPS YOU MAY USE:"]
|
| 389 |
-
# β BOTH HALVES, `key (phrase)`. The KEY is what the model must write into `config` and the
|
| 390 |
-
# PHRASE is the only human wording of that requirement anywhere β the one the runner's own
|
| 391 |
-
# refusal sentence is built from. Keys alone leave the model guessing what `field` means on a
|
| 392 |
-
# `web_read` (it is a column to write into, not a form field); phrases alone leave it guessing
|
| 393 |
-
# what to call the setting. Handing it one and hoping is how a draft comes back configured
|
| 394 |
-
# against a key the validator drops.
|
| 395 |
-
req = {str(k): [f"{key} ({phrase})" for phrase, key in v] for k, v in (required or {}).items()}
|
| 396 |
-
for row in catalog or []:
|
| 397 |
-
if not row.get("ready"):
|
| 398 |
-
continue
|
| 399 |
-
kind = str(row.get("kind") or "")
|
| 400 |
-
need = req.get(kind) or []
|
| 401 |
-
lines.append(f"- {kind}: {row.get('label')} - {row.get('detail') or ''}"
|
| 402 |
-
+ (f" REQUIRED settings: {', '.join(need)}" if need else ""))
|
| 403 |
-
lines += ["", "WHAT CAN START AN AUTOMATION:"]
|
| 404 |
-
for t in triggers or []:
|
| 405 |
-
if t.get("planned") or not t.get("ready", True):
|
| 406 |
-
continue
|
| 407 |
-
lines.append(f"- {t.get('key')}: {t.get('label')}")
|
| 408 |
-
lines += ["", "THE DATABASES THIS PERSON HAS:"]
|
| 409 |
-
for t in (tables or [])[:40]:
|
| 410 |
-
cols = ", ".join(str(f.get("key")) for f in (t.get("fields") or [])[:25])
|
| 411 |
-
lines.append(f"- {t.get('key')} ({t.get('label')}): {cols or 'no columns yet'}")
|
| 412 |
-
if not tables:
|
| 413 |
-
lines.append("- (none - do not name a database)")
|
| 414 |
-
lines += [
|
| 415 |
-
"",
|
| 416 |
-
"RULES:",
|
| 417 |
-
"1. Use ONLY the step kinds listed above. If what is asked needs a step that is not there, "
|
| 418 |
-
"answer kind=refused and say plainly which capability is missing.",
|
| 419 |
-
"2. Fill in every REQUIRED setting you can from what the person told you. Leave one blank "
|
| 420 |
-
"rather than inventing a web address, a CSS selector or a column name.",
|
| 421 |
-
"3. A web address must start with http:// or https://.",
|
| 422 |
-
"4. To use a value from the record the flow is walking, write it as {{Column name}}.",
|
| 423 |
-
"5. Name a database only from the list above, by its key.",
|
| 424 |
-
"6. Keep it short. Fewer steps that work beat more steps that guess.",
|
| 425 |
-
]
|
| 426 |
-
return "\n".join(lines)
|
| 427 |
-
|
| 428 |
-
|
| 429 |
-
def _flow_from_tool_call(obj):
|
| 430 |
-
"""The model's tool arguments -> `(draft, refusal)`. A shape error is a refusal, never a crash."""
|
| 431 |
-
if not isinstance(obj, dict):
|
| 432 |
-
return None, "the assistant's answer could not be read"
|
| 433 |
-
if str(obj.get("kind") or "") == "refused":
|
| 434 |
-
return None, (str(obj.get("refusal") or "").strip()
|
| 435 |
-
or "the assistant could not build this from the steps available")
|
| 436 |
-
acts = obj.get("actions")
|
| 437 |
-
if not isinstance(acts, list) or not acts:
|
| 438 |
-
return None, ("the assistant did not produce any steps - try describing what should "
|
| 439 |
-
"happen, one action at a time")
|
| 440 |
-
out = []
|
| 441 |
-
for a in acts[:MAX_DRAFT_ACTIONS]:
|
| 442 |
-
if not isinstance(a, dict) or not str(a.get("kind") or "").strip():
|
| 443 |
-
continue
|
| 444 |
-
cfg = a.get("config")
|
| 445 |
-
out.append({"kind": str(a["kind"]).strip(),
|
| 446 |
-
"config": cfg if isinstance(cfg, dict) else {},
|
| 447 |
-
"why": str(a.get("why") or "").strip()[:200]})
|
| 448 |
-
if not out:
|
| 449 |
-
return None, "the assistant's steps could not be read"
|
| 450 |
-
return {"name": str(obj.get("name") or "").strip()[:80] or "New automation",
|
| 451 |
-
"trigger": str(obj.get("trigger") or "").strip(),
|
| 452 |
-
"table": str(obj.get("table") or "").strip(),
|
| 453 |
-
# ββ THE TRUNCATION IS REPORTED, and it is a STANDING RULE that it must be (owner,
|
| 454 |
-
# 2026-08-12, W30/R6 second sentence): *"if there is lag or it can't be done, you need
|
| 455 |
-
# to explicitly tell me why and recommend a fix"* β **a silent truncation IS the
|
| 456 |
-
# violation, not the limit.** `acts[:MAX_DRAFT_ACTIONS]` above dropped everything past
|
| 457 |
-
# the twelfth and said nothing, so a model that answered with a twenty-step journey had
|
| 458 |
-
# eight steps deleted between the answer and the screen, with no key anywhere in the
|
| 459 |
-
# response naming them. `MAX_ACTIONS` is 20, so those steps were STORABLE β this
|
| 460 |
-
# ceiling is the draft door's own, which makes reporting it the whole obligation.
|
| 461 |
-
# β Found by the verifier that checked this ticket, not by a gate.
|
| 462 |
-
"asked": len([a for a in acts if isinstance(a, dict)]),
|
| 463 |
-
"actions": out}, ""
|
| 464 |
-
|
| 465 |
-
|
| 466 |
-
def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeout=None,
|
| 467 |
-
st=None, user="", model=None):
|
| 468 |
-
"""A sentence -> `(draft, refusal_sentence, provider)`. β NOTHING IS SAVED HERE.
|
| 469 |
-
|
| 470 |
-
Exactly one of `draft` and `refusal_sentence` is truthy β the same contract
|
| 471 |
-
`web_agent.run_step` keeps, so a caller has no third case to get wrong.
|
| 472 |
-
|
| 473 |
-
β W35-T41 / C7 β `st`/`user` are the usage ledger's target, exactly as on `decide` above and for
|
| 474 |
-
the same reason: both of this function's callers (`automation_engine._ai_agent_plan` and
|
| 475 |
-
`routes_automation`'s draft door) are in lane D's fence. C7 says E adds the ledger line here and
|
| 476 |
-
D asserts it; the two keywords are what D has to pass for the line to be attributable.
|
| 477 |
-
"""
|
| 478 |
-
# β DECLARED AT THE TOP OF THE FUNCTION, not beside the assignment inside the provider loop.
|
| 479 |
-
# It parses either way; a reader scanning for the declaration does not look inside a `for`.
|
| 480 |
-
global LAST_ANTHROPIC_TRANSPORT
|
| 481 |
-
import usage_ledger # noqa: PLC0415
|
| 482 |
-
text = str(prompt or "").strip()[:MAX_PROMPT_CHARS]
|
| 483 |
-
if not text:
|
| 484 |
-
return None, "type what you want the automation to do", None
|
| 485 |
-
kinds = sorted({str(r.get("kind")) for r in (catalog or []) if r.get("ready")})
|
| 486 |
-
if not kinds:
|
| 487 |
-
return None, "this deployment offers no automation steps to build with", None
|
| 488 |
-
trigger_keys = sorted({str(t.get("key")) for t in (triggers or [])
|
| 489 |
-
if t.get("key") and not t.get("planned")}) or ["manual"]
|
| 490 |
-
table_keys = sorted({str(t.get("key")) for t in (tables or []) if t.get("key")}) or [""]
|
| 491 |
-
tools = [{"type": "function", "function": {
|
| 492 |
-
"name": "build_automation",
|
| 493 |
-
"description": "Emit the automation, or refuse.",
|
| 494 |
-
"parameters": flow_schema(kinds, trigger_keys, table_keys)}}]
|
| 495 |
-
messages = [{"role": "system",
|
| 496 |
-
"content": flow_system_prompt(catalog, required, triggers, tables)},
|
| 497 |
-
{"role": "user", "content": text}]
|
| 498 |
-
|
| 499 |
-
if chat is not None:
|
| 500 |
-
# β THE INJECTED PATH IS THE PROVEN PATH. It runs the SAME parse and the SAME refusal
|
| 501 |
-
# branches as a live call; only the transport is replaced.
|
| 502 |
-
draft, refusal = _flow_from_tool_call(chat(messages, tools))
|
| 503 |
-
return draft, refusal, "injected"
|
| 504 |
-
|
| 505 |
-
provs = flow_providers(model)
|
| 506 |
-
if not provs:
|
| 507 |
-
# β SAY SO. An AI feature that silently does nothing is indistinguishable from one that was
|
| 508 |
-
# never built [[flag-shipped-without-its-writer]].
|
| 509 |
-
return None, ("the assistant is not configured on this deployment, so an automation cannot "
|
| 510 |
-
"be drafted from a description yet"), None
|
| 511 |
-
tmo = float(timeout or TIMEOUT_SECONDS)
|
| 512 |
-
problems = []
|
| 513 |
-
import providers as _prov
|
| 514 |
-
for p in provs:
|
| 515 |
-
# ββ W36-T35 / R4 β THE OWNER QUOTED THIS LINE BACK AT US. It used to read
|
| 516 |
-
# `problems.append(f"{p['name']}: tool calls are not wired for this shape")` and `continue`,
|
| 517 |
-
# so the sentence *"anthropic: tool calls are not wired for this shape"* appeared under the
|
| 518 |
-
# Agent module verbatim. R4: *"Anthropic becomes the tool-calling path that always works."*
|
| 519 |
-
# It is wired now, through the ONE wire in `providers`, and it matters more than it looks:
|
| 520 |
-
# every side rung on this account is refusing today (cerebras 402, groq 404, openrouter
|
| 521 |
-
# 402), so without this branch the drafter cannot answer at all.
|
| 522 |
-
# β NO `effort` ON THIS DOOR β `output_config.effort` errors on Haiku 4.5, the tier this
|
| 523 |
-
# ladder runs. The parameter is the caller's to send, which is why the wire takes it.
|
| 524 |
-
# β D-346 (W37-T39): BOTH shapes now yield the SAME `(status, body)` pair, so every branch
|
| 525 |
-
# below reads one thing. The anthropic side gets there through `anthropic_send` (official
|
| 526 |
-
# SDK when installed, the identical raw POST when not); the openai side still posts here
|
| 527 |
-
# because there is no shared SDK across three different vendors on that wire.
|
| 528 |
-
global LAST_ANTHROPIC_TRANSPORT
|
| 529 |
-
try:
|
| 530 |
-
if p["shape"] == "anthropic":
|
| 531 |
-
req = _prov.anthropic_request(
|
| 532 |
-
model=p["model"], key=os.environ[p["env"]].strip(), system=None,
|
| 533 |
-
messages=messages, tools=tools, max_tokens=1500, tool_choice="required")
|
| 534 |
-
status, body, transport = _prov.anthropic_send(req, timeout=tmo)
|
| 535 |
-
LAST_ANTHROPIC_TRANSPORT = transport
|
| 536 |
-
else:
|
| 537 |
-
r = requests.post(p["url"], timeout=tmo,
|
| 538 |
-
headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
|
| 539 |
-
"Content-Type": "application/json"},
|
| 540 |
-
json={"model": p["model"], "messages": messages, "tools": tools,
|
| 541 |
-
"tool_choice": "required", "temperature": 0.1,
|
| 542 |
-
"max_tokens": 1500})
|
| 543 |
-
status = r.status_code
|
| 544 |
-
body = r.json() if (r.content and r.status_code == 200) else {"_text": r.text}
|
| 545 |
-
except Exception as e: # noqa: BLE001
|
| 546 |
-
problems.append(f"{p['name']}: {type(e).__name__}")
|
| 547 |
-
continue
|
| 548 |
-
if status != 200:
|
| 549 |
-
# β A SENTENCE, NOT `HTTP 402` (R4's third clause). The owner read the status codes off
|
| 550 |
-
# this very door. `refusal_sentence` also decides whether this was a CREDIT failure, and
|
| 551 |
-
# the memo makes the next turn SKIP the empty account instead of paying for it again.
|
| 552 |
-
# β The body is re-serialised for the substring test because the SDK path never had a
|
| 553 |
-
# `.text` β that is the one thing this normalisation costs, and it costs nothing else.
|
| 554 |
-
detail = json.dumps(body)[:600] if isinstance(body, dict) else str(body)[:600]
|
| 555 |
-
if _prov.is_credit_failure(status, detail):
|
| 556 |
-
_prov.mark_no_credit(p["name"])
|
| 557 |
-
problems.append(_prov.refusal_sentence(p["name"], status, detail))
|
| 558 |
-
continue
|
| 559 |
-
try:
|
| 560 |
-
body = body or {}
|
| 561 |
-
if p["shape"] == "anthropic":
|
| 562 |
-
_text, args, _refused = _prov.anthropic_read(body)
|
| 563 |
-
if _refused:
|
| 564 |
-
problems.append(f"{p['name']}: {_refused}")
|
| 565 |
-
continue
|
| 566 |
-
else:
|
| 567 |
-
calls = (((body.get("choices") or [{}])[0].get("message") or {})
|
| 568 |
-
.get("tool_calls") or [])
|
| 569 |
-
args = json.loads(calls[0]["function"]["arguments"]) if calls else None
|
| 570 |
-
except Exception as e: # noqa: BLE001
|
| 571 |
-
problems.append(f"{p['name']}: unreadable answer ({type(e).__name__})")
|
| 572 |
-
continue
|
| 573 |
-
# ββ C7 β THE LEDGER LINE. Placed after the parse rather than before it so an UNREADABLE
|
| 574 |
-
# answer is not double-counted by the `continue` above... β which means an unreadable answer
|
| 575 |
-
# is NOT counted at all, and that is a deliberate, disclosed loss: a body this code cannot
|
| 576 |
-
# parse is a body whose `usage` it also cannot trust, and `body` is out of scope in that
|
| 577 |
-
# branch by construction. The 200-with-junk case is rare and named here rather than
|
| 578 |
-
# silently rounded to zero.
|
| 579 |
-
ins, outs = usage_ledger.tokens_from(body)
|
| 580 |
-
usage_ledger.record("automation_draft", p["name"], p["model"], ins, outs,
|
| 581 |
-
total=usage_ledger.total_from(body), st=st, user=user)
|
| 582 |
-
draft, refusal = _flow_from_tool_call(args)
|
| 583 |
-
if draft is None and isinstance(args, dict) and str(args.get("kind")) == "refused":
|
| 584 |
-
# β A REFUSAL IS AN ANSWER, NOT A FAULT, so it does NOT fall through to a more
|
| 585 |
-
# expensive rung β the model has just said this cannot be built. `decide()` takes the
|
| 586 |
-
# same posture for the same reason.
|
| 587 |
-
return None, refusal, p["name"]
|
| 588 |
-
if draft is not None:
|
| 589 |
-
return draft, "", p["name"]
|
| 590 |
-
problems.append(f"{p['name']}: {refusal}")
|
| 591 |
-
return None, ("; ".join(problems)[:300] or "no provider answered"), None
|
|
|
|
| 1 |
+
"""AI REVIEW β let a model decide which stage a card moves to (wave 23, owner ruling R4/R14).
|
| 2 |
+
|
| 3 |
+
β WHAT THIS IS. A review stage holds a record until somebody decides where it goes next. R4 made
|
| 4 |
+
that somebody optionally a MODEL: the engine hands over the record's own values, the review's
|
| 5 |
+
prompt, and the list of stages the review is allowed to send a card to, and gets back ONE of
|
| 6 |
+
those stage labels plus a one-line reason. Every decision is written to the same `reviews` audit
|
| 7 |
+
log a human click writes to, tagged `by: "ai"` with the provider and model that made it.
|
| 8 |
+
|
| 9 |
+
β FAIL-CLOSED IN EVERY DIRECTION, and this is the whole safety story. No key configured, a
|
| 10 |
+
network failure, a slow answer, a malformed answer, or an answer naming a stage the review does
|
| 11 |
+
not offer β all return `("", {...})`, and the caller leaves the card exactly where a human would
|
| 12 |
+
have found it. The feature can be absent, broken or wrong and the worst outcome is a person doing
|
| 13 |
+
the work. Nothing here can move a card somewhere the review does not already permit.
|
| 14 |
+
|
| 15 |
+
β CHEAP FIRST (owner R14, verbatim: *"Claude is a bit too expensive"*). The ladder is
|
| 16 |
+
`groq β cerebras β openrouter β anthropic`; the first CONFIGURED provider wins, and Anthropic is
|
| 17 |
+
last rather than absent β it is the quality backstop, not the default. `AIOS_AI_REVIEW_PROVIDER`
|
| 18 |
+
pins one; `AIOS_AI_MODEL` overrides the model.
|
| 19 |
+
|
| 20 |
+
ββ THE ANTHROPIC LEG IS ON THE OFFICIAL SDK NOW (D-346, W37-T39, 2026-08-19). β THIS PARAGRAPH
|
| 21 |
+
USED TO ARGUE THE OPPOSITE and is rewritten rather than deleted, because a comment left asserting
|
| 22 |
+
the reverse of its own code is [[two-gates-can-assert-opposite-things]] with no gate to catch it.
|
| 23 |
+
The retired text said raw HTTP was *"a deliberate deviation β¦ booked as a DEBT line so the
|
| 24 |
+
integrator can overturn it deliberately rather than by drift"*. This is that overturn.
|
| 25 |
+
|
| 26 |
+
Its two reasons were real and are both answered rather than waved away:
|
| 27 |
+
1. *"one SDK leg beside three hand-rolled ones is two implementations of the same call."* It is
|
| 28 |
+
not, because the leg does not live here: `providers.anthropic_send` owns the wire, prefers
|
| 29 |
+
the SDK, and normalises BOTH transports to one `(status, body)` pair. This file gained no
|
| 30 |
+
Anthropic knowledge β it lost some.
|
| 31 |
+
2. *"adding a pinned dependency rebuilds the container, a real deploy risk."* Still true, so the
|
| 32 |
+
import is LAZY and its absence is a FALLBACK, not a crash: with no `anthropic` package the
|
| 33 |
+
same raw POST runs and `LAST_ANTHROPIC_TRANSPORT` reports `'http'`. The pin is owed in BOTH
|
| 34 |
+
manifests ([[pin-deps-space-rebuilds]]) and is outside every worker fence this wave.
|
| 35 |
+
β The other three legs stay OpenAI-chat-shaped over `requests` β they have no shared SDK, and that
|
| 36 |
+
half of the original reasoning never expired.
|
| 37 |
+
|
| 38 |
+
The Messages shape below is the current one: `x-api-key` + `anthropic-version: 2023-06-01`, and
|
| 39 |
+
`stop_reason: "refusal"` is checked BEFORE reading `content` β a refusal answers HTTP 200 with an
|
| 40 |
+
empty content list, so code that indexes `content[0]` unconditionally breaks on it.
|
| 41 |
+
"""
|
| 42 |
+
from __future__ import annotations
|
| 43 |
+
|
| 44 |
+
import json
|
| 45 |
+
import os
|
| 46 |
+
import re
|
| 47 |
+
|
| 48 |
+
import requests
|
| 49 |
+
|
| 50 |
+
#: The ladder. Order IS the policy (R14) β cheapest capable first, Anthropic last.
|
| 51 |
+
PROVIDERS = [
|
| 52 |
+
# ββ D-345, FIXED W37-T39 (2026-08-19). This read `llama-3.3-70b-versatile` and Groq RETIRED
|
| 53 |
+
# it: a real POST with the live key answers HTTP 404 `model_not_found`, and the id is absent
|
| 54 |
+
# from `GET /openai/v1/models`. β THE `openai/` PREFIX IS PART OF GROQ'S ID and is NOT a typo
|
| 55 |
+
# for the cerebras rung below, which serves the same family bare as `gpt-oss-120b`.
|
| 56 |
+
{"name": "groq", "env": "GROQ_API_KEY", "shape": "openai",
|
| 57 |
+
"url": "https://api.groq.com/openai/v1/chat/completions",
|
| 58 |
+
"model": "openai/gpt-oss-120b"},
|
| 59 |
+
{"name": "cerebras", "env": "CEREBRAS_API_KEY", "shape": "openai",
|
| 60 |
+
"url": "https://api.cerebras.ai/v1/chat/completions",
|
| 61 |
+
"model": "gpt-oss-120b"},
|
| 62 |
+
{"name": "openrouter", "env": "OPENROUTER_API_KEY", "shape": "openai",
|
| 63 |
+
"url": "https://openrouter.ai/api/v1/chat/completions",
|
| 64 |
+
"model": "openai/gpt-4o-mini"},
|
| 65 |
+
# β haiku-class DELIBERATELY, not the default Opus tier: R14 put Anthropic on this ladder as
|
| 66 |
+
# the backstop for a one-line classification, and this is the cheapest current Claude that
|
| 67 |
+
# does it well. A bigger model here would be spending the owner's money to pick between two
|
| 68 |
+
# labels it already has in front of it.
|
| 69 |
+
{"name": "anthropic", "env": "ANTHROPIC_API_KEY", "shape": "anthropic",
|
| 70 |
+
"url": "https://api.anthropic.com/v1/messages",
|
| 71 |
+
# β AN ENV LEVER, NOT A NEW DEFAULT (W36-T35): haiku stays the choice for the reasons above,
|
| 72 |
+
# and a deployment whose side rungs are out of credit can raise the tier without a release.
|
| 73 |
+
"model": os.environ.get("AIOS_AI_REVIEW_ANTHROPIC_MODEL") or "claude-haiku-4-5"},
|
| 74 |
+
]
|
| 75 |
+
ANTHROPIC_VERSION = "2023-06-01"
|
| 76 |
+
TIMEOUT_SECONDS = float(os.environ.get("AIOS_AI_REVIEW_TIMEOUT") or 20)
|
| 77 |
+
MAX_FIELD_CHARS = 200 # per value handed to the model
|
| 78 |
+
MAX_FIELDS = 30 # columns handed to the model
|
| 79 |
+
MAX_REASON = 200
|
| 80 |
+
|
| 81 |
+
|
| 82 |
+
def ladder():
|
| 83 |
+
"""The providers that are actually usable here, in order. Empty = the feature is off."""
|
| 84 |
+
pin = (os.environ.get("AIOS_AI_REVIEW_PROVIDER") or "").strip().lower()
|
| 85 |
+
live = [p for p in PROVIDERS if (os.environ.get(p["env"]) or "").strip()]
|
| 86 |
+
if pin:
|
| 87 |
+
live = [p for p in live if p["name"] == pin]
|
| 88 |
+
return live
|
| 89 |
+
|
| 90 |
+
|
| 91 |
+
def configured():
|
| 92 |
+
return bool(ladder())
|
| 93 |
+
|
| 94 |
+
|
| 95 |
+
def _record_text(row, fields):
|
| 96 |
+
"""The record, as the model sees it. Values are truncated and the column set is bounded β
|
| 97 |
+
an automation table can carry a 32 KB JSON blob per row (C7) and a review decision does not
|
| 98 |
+
need it. Machine bookkeeping columns are dropped: a stage cell naming the stage the card is
|
| 99 |
+
sitting at would be the model reading its own question back."""
|
| 100 |
+
keys = [k for k in (fields or list((row or {}).keys()))
|
| 101 |
+
if not str(k).startswith("stage_")][:MAX_FIELDS]
|
| 102 |
+
lines = []
|
| 103 |
+
for k in keys:
|
| 104 |
+
v = (row or {}).get(k)
|
| 105 |
+
if v is None or str(v).strip() == "":
|
| 106 |
+
continue
|
| 107 |
+
lines.append(f"{k}: {str(v)[:MAX_FIELD_CHARS]}")
|
| 108 |
+
return "\n".join(lines) or "(this record has no filled-in values)"
|
| 109 |
+
|
| 110 |
+
|
| 111 |
+
def _instruction(prompt, options, label):
|
| 112 |
+
return (
|
| 113 |
+
f"You are deciding what happens to one record waiting at a review step called "
|
| 114 |
+
f"{label!r} in a workflow.\n\n"
|
| 115 |
+
f"The person who built this workflow told you: {prompt}\n\n"
|
| 116 |
+
f"Choose EXACTLY ONE of these next steps, by its exact name:\n"
|
| 117 |
+
+ "\n".join(f"- {o}" for o in options)
|
| 118 |
+
+ "\n\nAnswer with one line of JSON and nothing else:\n"
|
| 119 |
+
'{"choice": "<one name from the list above>", "reason": "<one short sentence>"}\n'
|
| 120 |
+
"If the record does not give you enough to decide, answer "
|
| 121 |
+
'{"choice": "", "reason": "why not"} and a person will decide instead.'
|
| 122 |
+
)
|
| 123 |
+
|
| 124 |
+
|
| 125 |
+
def _parse(text, options):
|
| 126 |
+
"""The model's line β `(choice, reason)`. A choice that is not one of the offered stages is
|
| 127 |
+
DISCARDED, not fuzzy-matched: the offered list is a permission boundary, and a near-miss
|
| 128 |
+
resolved by string distance is how a card ends up somewhere nobody authorised."""
|
| 129 |
+
raw = str(text or "").strip()
|
| 130 |
+
obj = None
|
| 131 |
+
m = re.search(r"\{.*\}", raw, re.S)
|
| 132 |
+
if m:
|
| 133 |
+
try:
|
| 134 |
+
obj = json.loads(m.group(0))
|
| 135 |
+
except (ValueError, TypeError):
|
| 136 |
+
obj = None
|
| 137 |
+
if not isinstance(obj, dict):
|
| 138 |
+
return "", ""
|
| 139 |
+
choice = str(obj.get("choice") or "").strip()
|
| 140 |
+
reason = str(obj.get("reason") or "").strip()[:MAX_REASON]
|
| 141 |
+
for opt in options:
|
| 142 |
+
if choice.lower() == str(opt).lower():
|
| 143 |
+
return str(opt), reason # the OFFERED spelling wins, never the model's
|
| 144 |
+
return "", reason
|
| 145 |
+
|
| 146 |
+
|
| 147 |
+
# ββ WAVE 35 Β· W35-T41 / C7 β THE TWO TRANSPORTS RETURN THE RESPONSE BODY'S `usage`.
|
| 148 |
+
#
|
| 149 |
+
# β THIS FILE'S OWN HEADER USED TO BE THE PRODUCT'S CONFESSION THAT NOTHING COUNTED: `ai_enrich`'s
|
| 150 |
+
# docstring says *"`ai_review.decide` -- the product's only other LLM entry -- has no token
|
| 151 |
+
# accounting of ANY kind"*. R9 asks for ONE meter for every AI surface, so the counting has to reach
|
| 152 |
+
# this transport rather than be bolted onto its caller β the caller never sees the body.
|
| 153 |
+
#
|
| 154 |
+
# β A THIRD RETURN VALUE, NOT A MUTATED ARGUMENT, and both call sites are in `decide` below. The
|
| 155 |
+
# tuple grew from `(text, err)` to `(text, err, usage)`; `usage` is the raw `usage` OBJECT (or None),
|
| 156 |
+
# because reading it is `usage_ledger`'s job and a second reader here would be the two-normalizers
|
| 157 |
+
# shape this repo keeps paying for.
|
| 158 |
+
def _call_openai(p, model, system, user, timeout):
|
| 159 |
+
r = requests.post(p["url"], timeout=timeout,
|
| 160 |
+
headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
|
| 161 |
+
"Content-Type": "application/json"},
|
| 162 |
+
json={"model": model, "max_tokens": 300, "temperature": 0,
|
| 163 |
+
"messages": [{"role": "system", "content": system},
|
| 164 |
+
{"role": "user", "content": user}]})
|
| 165 |
+
if r.status_code >= 400:
|
| 166 |
+
# β NO BODY ON A 4xx/5xx: an error envelope carries no usage, and a provider that refused
|
| 167 |
+
# before running the model has nothing to bill. The call is still COUNTED by `decide`.
|
| 168 |
+
return "", f"{p['name']} answered {r.status_code}", None
|
| 169 |
+
body = r.json()
|
| 170 |
+
choices = body.get("choices") or []
|
| 171 |
+
if not choices:
|
| 172 |
+
return "", f"{p['name']} returned no choices", body
|
| 173 |
+
return str(((choices[0] or {}).get("message") or {}).get("content") or ""), "", body
|
| 174 |
+
|
| 175 |
+
|
| 176 |
+
#: What transport the last Anthropic call actually used: `'sdk'`, `'http'`, or `''` before any.
|
| 177 |
+
#: β PROCESS-LOCAL AND FOR REPORTING ONLY. It exists so `GET /meta` and `verify_web_agent` can say
|
| 178 |
+
#: WHICH path ran rather than inferring it from a requirements file nobody in this lane can edit.
|
| 179 |
+
LAST_ANTHROPIC_TRANSPORT = ""
|
| 180 |
+
|
| 181 |
+
|
| 182 |
+
def _call_anthropic(p, model, system, user, timeout):
|
| 183 |
+
"""One classification turn on the Messages API, through `providers.anthropic_send`.
|
| 184 |
+
|
| 185 |
+
β D-346 (W37-T39): this used to hand-roll the POST. It now goes through the shared wire, which
|
| 186 |
+
prefers the OFFICIAL `anthropic` SDK and falls back to the same raw POST when the package is
|
| 187 |
+
absent. The shape of what comes back is unchanged, deliberately: `anthropic_send` normalises
|
| 188 |
+
both transports to `(status, body)`, so every line below this call is untouched.
|
| 189 |
+
"""
|
| 190 |
+
global LAST_ANTHROPIC_TRANSPORT
|
| 191 |
+
import providers as _prov # noqa: PLC0415
|
| 192 |
+
# β NO TOOLS ON THIS PATH. The builder omits `tool_choice` for exactly that case, so there is
|
| 193 |
+
# nothing to strip here β the rule lives in `anthropic_request`, beside the thing it constrains.
|
| 194 |
+
req = _prov.anthropic_request(
|
| 195 |
+
model=model, key=os.environ[p["env"]].strip(), system=system,
|
| 196 |
+
messages=[{"role": "user", "content": user}], tools=[], max_tokens=300)
|
| 197 |
+
status, body, transport = _prov.anthropic_send(req, timeout=timeout)
|
| 198 |
+
LAST_ANTHROPIC_TRANSPORT = transport
|
| 199 |
+
if status >= 400 or status == 0:
|
| 200 |
+
# β THE SENTENCE COMES FROM THE LADDER, NOT FROM HERE. `refusal_sentence` already names the
|
| 201 |
+
# vendor and the action for every status R4 enumerated, so a bare "anthropic answered 402"
|
| 202 |
+
# (which is what this line used to say, and what the owner quoted back at us) cannot recur.
|
| 203 |
+
return "", _prov.refusal_sentence("anthropic", status, json.dumps(body)[:400]), None
|
| 204 |
+
body = body or {}
|
| 205 |
+
# β stop_reason FIRST. A safety refusal is a successful 200 with an EMPTY content list, so
|
| 206 |
+
# reading content[0] before this check turns a refusal into an IndexError inside a run.
|
| 207 |
+
# β A refusal IS billed and its body carries `usage`, so the body rides back on this branch too.
|
| 208 |
+
if body.get("stop_reason") == "refusal":
|
| 209 |
+
return "", "anthropic declined to answer this record", body
|
| 210 |
+
parts = [b.get("text") or "" for b in (body.get("content") or [])
|
| 211 |
+
if isinstance(b, dict) and b.get("type") == "text"]
|
| 212 |
+
if not parts:
|
| 213 |
+
return "", "anthropic returned no text", body
|
| 214 |
+
return "".join(parts), "", body
|
| 215 |
+
|
| 216 |
+
|
| 217 |
+
def decide(*, prompt, options, row, fields=(), label="Review", timeout=None, st=None, user=""):
|
| 218 |
+
"""Pick this record's next stage. Returns `(choice, meta)`.
|
| 219 |
+
|
| 220 |
+
`choice` is "" whenever a person should decide β which is every failure mode there is.
|
| 221 |
+
`meta` carries `provider`, `model`, `reason` on success, and `problem` on refusal to answer.
|
| 222 |
+
|
| 223 |
+
β W35-T41 / C7 β `st` and `user` are the USAGE LEDGER's target. Both default to absent because
|
| 224 |
+
this function's caller is `automation_engine.ai_decide(rt, ...)`, in another lane's fence: it
|
| 225 |
+
HAS the runtime and does not pass it yet, so until it does, a review's tokens are counted as
|
| 226 |
+
unattributed and REPORTED by `GET /usage` rather than dropped. See `usage_ledger`'s header for
|
| 227 |
+
why they cannot be resolved implicitly (measured: a contextvar does not survive a FastAPI
|
| 228 |
+
dependency).
|
| 229 |
+
"""
|
| 230 |
+
import usage_ledger # noqa: PLC0415
|
| 231 |
+
opts = [str(o) for o in (options or []) if str(o).strip()]
|
| 232 |
+
if not opts:
|
| 233 |
+
return "", {"problem": "the review offers no next stages"}
|
| 234 |
+
if not str(prompt or "").strip():
|
| 235 |
+
return "", {"problem": "the review has no prompt for the model to follow"}
|
| 236 |
+
live = ladder()
|
| 237 |
+
if not live:
|
| 238 |
+
return "", {"problem": "no AI provider is configured on this deployment"}
|
| 239 |
+
system = _instruction(prompt, opts, label)
|
| 240 |
+
user = "Here is the record:\n\n" + _record_text(row, fields)
|
| 241 |
+
tmo = float(timeout or TIMEOUT_SECONDS)
|
| 242 |
+
override = (os.environ.get("AIOS_AI_MODEL") or "").strip()
|
| 243 |
+
problems = []
|
| 244 |
+
for p in live:
|
| 245 |
+
model = override or p["model"]
|
| 246 |
+
body = None
|
| 247 |
+
try:
|
| 248 |
+
text, err, body = (_call_anthropic if p["shape"] == "anthropic" else _call_openai)(
|
| 249 |
+
p, model, system, user, tmo)
|
| 250 |
+
except Exception as e: # noqa: BLE001
|
| 251 |
+
text, err = "", f"{p['name']} failed: {type(e).__name__}"
|
| 252 |
+
# ββ C7 β THE LEDGER LINE, BEFORE ANY BRANCH BELOW READS THE ANSWER.
|
| 253 |
+
# β IT IS WRITTEN ON EVERY OUTCOME THAT REACHED A PROVIDER, including a refusal and an
|
| 254 |
+
# unusable answer. A meter that books only successes reports a cheap week for a run that
|
| 255 |
+
# spent its budget being declined β and a declined call is billed. The only path that does
|
| 256 |
+
# NOT record is a transport that never reached the vendor (`body is None`), which spent
|
| 257 |
+
# nothing.
|
| 258 |
+
if body is not None:
|
| 259 |
+
ins, outs = usage_ledger.tokens_from(body)
|
| 260 |
+
usage_ledger.record("ai_review", p["name"], model, ins, outs,
|
| 261 |
+
total=usage_ledger.total_from(body), st=st, user=user)
|
| 262 |
+
if err:
|
| 263 |
+
problems.append(err)
|
| 264 |
+
continue # ladder: a dead provider degrades to the next one
|
| 265 |
+
choice, reason = _parse(text, opts)
|
| 266 |
+
if not choice:
|
| 267 |
+
# The provider ANSWERED and declined (or answered unusably). That is a decision about
|
| 268 |
+
# this record, not a fault in the provider, so it does NOT fall through to a more
|
| 269 |
+
# expensive one β the card goes to a human, which is what the model just asked for.
|
| 270 |
+
return "", {"provider": p["name"], "model": model,
|
| 271 |
+
"problem": reason or "the model did not choose one of the stages"}
|
| 272 |
+
return choice, {"provider": p["name"], "model": model, "reason": reason}
|
| 273 |
+
return "", {"problem": "; ".join(problems)[:300] or "no provider answered"}
|
| 274 |
+
|
| 275 |
+
|
| 276 |
+
# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ the FLOW WRITER
|
| 277 |
+
# ββ WAVE 33 Β· W33-T54/T55 (owner item 7, ruling R3) β A PROMPT BECOMES A DRAFT AUTOMATION.
|
| 278 |
+
#
|
| 279 |
+
# Owner, verbatim: *"lay out the foundation with custom tools we provide"* β and the tools are the
|
| 280 |
+
# action catalog, which has been machine-readable since wave 23. So this writes no new vocabulary:
|
| 281 |
+
# it hands the model the SAME `ACTION_CATALOG` the menu paints, the SAME `ACTION_REQUIRED` the
|
| 282 |
+
# runner blocks on, and the SAME trigger keys `clean_trigger` accepts, and asks for one JSON object
|
| 283 |
+
# in that vocabulary.
|
| 284 |
+
#
|
| 285 |
+
# β WHY IT LIVES IN `ai_review.py` RATHER THAN A NEW FILE. Two reasons, both about ownership. This
|
| 286 |
+
# is the one module in the API package that already holds an LLM ladder and its credentials, so a
|
| 287 |
+
# second one would be a second place a rotated key has to be noticed; and a new `routes_*.py` needs
|
| 288 |
+
# a `main.py` line from another lane (contract C2) to be reachable at all, which is how wave 23
|
| 289 |
+
# shipped three finished routers 404-dead behind green gates. The DOOR is a route on
|
| 290 |
+
# `routes_automation.py`, which is already mounted.
|
| 291 |
+
#
|
| 292 |
+
# ββ CONTRACT C7 IS THE DESIGN, NOT A CHECK AT THE END: *"the flow writer may emit only kinds
|
| 293 |
+
# present in `ACTION_CATALOG`, and its output must pass `clean_actions` unchanged."* Both halves are
|
| 294 |
+
# enforced mechanically rather than asked for politely β the kind list is an `enum` in the schema
|
| 295 |
+
# the model fills, and the caller runs `clean_actions` and DIFFS the result. That diff matters
|
| 296 |
+
# because `clean_actions` has no disclosure channel (D-75): it drops a key it does not recognise
|
| 297 |
+
# and answers 200, so a draft accepted without the diff would show a person a flow that is not the
|
| 298 |
+
# flow the model described, with nothing anywhere saying so.
|
| 299 |
+
#
|
| 300 |
+
# β `chat` IS INJECTABLE, exactly as `routes_query._call_model`'s is, and it is the reason this door
|
| 301 |
+
# can be proven end to end with no API key and no spend. A gate that can only run where a
|
| 302 |
+
# credential exists is a gate that never runs.
|
| 303 |
+
|
| 304 |
+
#: Cerebras first, NOT the cheap-first order `ladder()` uses. Same reason `routes_query` inverts it:
|
| 305 |
+
#: this contract includes a REFUSAL, and refusing honestly ("I cannot build that from the steps you
|
| 306 |
+
#: have") is a model property. A cheaper rung answers an impossible request with a plausible flow,
|
| 307 |
+
#: which is worse than no flow. Override with `AIOS_FLOW_PROVIDER`.
|
| 308 |
+
FLOW_PROVIDER_ORDER = ("cerebras", "groq", "openrouter", "anthropic")
|
| 309 |
+
MAX_DRAFT_ACTIONS = 12 # a draft a person reads in one screen; the engine's own cap is 25
|
| 310 |
+
MAX_PROMPT_CHARS = 2000
|
| 311 |
+
|
| 312 |
+
|
| 313 |
+
def flow_providers(pin=None):
|
| 314 |
+
"""The rungs usable here, in THIS module's refusal-first order. Empty = the feature is off.
|
| 315 |
+
|
| 316 |
+
β `pin` IS ASK D-18 (2026-08-18): the Agent chat's model toggle must configure something, and
|
| 317 |
+
the draft door used to read `prompt` off the body and nothing else β so the key the client sent
|
| 318 |
+
was accepted and dropped, and the picker was a control over nothing.
|
| 319 |
+
β AN UNKNOWN OR UNCONFIGURED PIN FALLS BACK TO THE LADDER rather than refusing. A model the
|
| 320 |
+
ladder stopped offering must not turn every later draft into an error; the caller is told which
|
| 321 |
+
rung actually answered, which is the honest half.
|
| 322 |
+
"""
|
| 323 |
+
by_name = {p["name"]: p for p in PROVIDERS}
|
| 324 |
+
live = [n for n in FLOW_PROVIDER_ORDER
|
| 325 |
+
if n in by_name and (os.environ.get(by_name[n]["env"]) or "").strip()]
|
| 326 |
+
wanted = str(pin or os.environ.get("AIOS_FLOW_PROVIDER") or "").strip().lower()
|
| 327 |
+
if wanted and wanted in live:
|
| 328 |
+
return [by_name[wanted]]
|
| 329 |
+
return [by_name[n] for n in live]
|
| 330 |
+
|
| 331 |
+
|
| 332 |
+
def flow_schema(kinds, trigger_keys, table_keys):
|
| 333 |
+
"""The tool schema the model fills β the catalog's OWN key lists as enums.
|
| 334 |
+
|
| 335 |
+
β `kind` AND `trigger` ARE ENUMS, not free strings, and that is C7's first half enforced by the
|
| 336 |
+
transport rather than by a check afterwards. A model asked for "any action name" invents
|
| 337 |
+
`send_slack_message` on a deployment that has no such kind, and the failure then surfaces as a
|
| 338 |
+
400 from `clean_actions` carrying a sentence about a word the person never typed.
|
| 339 |
+
β `required` IS `["kind"]` ALONE, deliberately: a REFUSAL carries no name and no actions, and a
|
| 340 |
+
schema demanding them turns an honest refusal into a provider-side 400 that reads exactly like a
|
| 341 |
+
transport failure (`routes_query._spec_schema` carries the same note, for the same measured
|
| 342 |
+
reason).
|
| 343 |
+
"""
|
| 344 |
+
return {
|
| 345 |
+
"type": "object",
|
| 346 |
+
"properties": {
|
| 347 |
+
"kind": {"type": "string", "enum": ["flow", "refused"],
|
| 348 |
+
"description": "refused = this cannot be built from the steps available"},
|
| 349 |
+
"refusal": {"type": "string",
|
| 350 |
+
"description": "when kind=refused: ONE plain sentence naming what is "
|
| 351 |
+
"missing, in the words a non-technical person would use"},
|
| 352 |
+
"name": {"type": "string", "description": "a short title for the automation"},
|
| 353 |
+
"trigger": {"type": "string", "enum": sorted(trigger_keys),
|
| 354 |
+
"description": "what starts this automation"},
|
| 355 |
+
"table": {"type": "string", "enum": sorted(table_keys),
|
| 356 |
+
"description": "the database whose records this flow walks, if any"},
|
| 357 |
+
"actions": {
|
| 358 |
+
"type": "array",
|
| 359 |
+
"maxItems": MAX_DRAFT_ACTIONS,
|
| 360 |
+
"items": {
|
| 361 |
+
"type": "object",
|
| 362 |
+
"properties": {
|
| 363 |
+
"kind": {"type": "string", "enum": sorted(kinds)},
|
| 364 |
+
"why": {"type": "string",
|
| 365 |
+
"description": "one short sentence: why this step is here"},
|
| 366 |
+
"config": {"type": "object", "additionalProperties": True,
|
| 367 |
+
"description": "the step's settings, using ONLY the keys named "
|
| 368 |
+
"for that kind in the system message"},
|
| 369 |
+
},
|
| 370 |
+
"required": ["kind"],
|
| 371 |
+
},
|
| 372 |
+
},
|
| 373 |
+
},
|
| 374 |
+
"required": ["kind"],
|
| 375 |
+
}
|
| 376 |
+
|
| 377 |
+
|
| 378 |
+
def flow_system_prompt(catalog, required, triggers, tables):
|
| 379 |
+
"""What the model is told it may build with β DERIVED, never written down twice.
|
| 380 |
+
|
| 381 |
+
Every list here is the server's own: the catalog rows the menu paints, the required-key table
|
| 382 |
+
the runner blocks on, the trigger keys `clean_trigger` accepts, and this tenant's real databases
|
| 383 |
+
with their real columns. Nothing about the vocabulary is restated by hand, so a kind added to
|
| 384 |
+
the catalog is offered here on the same deploy and a kind removed stops being offered.
|
| 385 |
+
"""
|
| 386 |
+
lines = ["You build small automations for a business tool. You are given the EXACT set of "
|
| 387 |
+
"steps this tool can perform. You may use nothing else.",
|
| 388 |
+
"", "THE STEPS YOU MAY USE:"]
|
| 389 |
+
# β BOTH HALVES, `key (phrase)`. The KEY is what the model must write into `config` and the
|
| 390 |
+
# PHRASE is the only human wording of that requirement anywhere β the one the runner's own
|
| 391 |
+
# refusal sentence is built from. Keys alone leave the model guessing what `field` means on a
|
| 392 |
+
# `web_read` (it is a column to write into, not a form field); phrases alone leave it guessing
|
| 393 |
+
# what to call the setting. Handing it one and hoping is how a draft comes back configured
|
| 394 |
+
# against a key the validator drops.
|
| 395 |
+
req = {str(k): [f"{key} ({phrase})" for phrase, key in v] for k, v in (required or {}).items()}
|
| 396 |
+
for row in catalog or []:
|
| 397 |
+
if not row.get("ready"):
|
| 398 |
+
continue
|
| 399 |
+
kind = str(row.get("kind") or "")
|
| 400 |
+
need = req.get(kind) or []
|
| 401 |
+
lines.append(f"- {kind}: {row.get('label')} - {row.get('detail') or ''}"
|
| 402 |
+
+ (f" REQUIRED settings: {', '.join(need)}" if need else ""))
|
| 403 |
+
lines += ["", "WHAT CAN START AN AUTOMATION:"]
|
| 404 |
+
for t in triggers or []:
|
| 405 |
+
if t.get("planned") or not t.get("ready", True):
|
| 406 |
+
continue
|
| 407 |
+
lines.append(f"- {t.get('key')}: {t.get('label')}")
|
| 408 |
+
lines += ["", "THE DATABASES THIS PERSON HAS:"]
|
| 409 |
+
for t in (tables or [])[:40]:
|
| 410 |
+
cols = ", ".join(str(f.get("key")) for f in (t.get("fields") or [])[:25])
|
| 411 |
+
lines.append(f"- {t.get('key')} ({t.get('label')}): {cols or 'no columns yet'}")
|
| 412 |
+
if not tables:
|
| 413 |
+
lines.append("- (none - do not name a database)")
|
| 414 |
+
lines += [
|
| 415 |
+
"",
|
| 416 |
+
"RULES:",
|
| 417 |
+
"1. Use ONLY the step kinds listed above. If what is asked needs a step that is not there, "
|
| 418 |
+
"answer kind=refused and say plainly which capability is missing.",
|
| 419 |
+
"2. Fill in every REQUIRED setting you can from what the person told you. Leave one blank "
|
| 420 |
+
"rather than inventing a web address, a CSS selector or a column name.",
|
| 421 |
+
"3. A web address must start with http:// or https://.",
|
| 422 |
+
"4. To use a value from the record the flow is walking, write it as {{Column name}}.",
|
| 423 |
+
"5. Name a database only from the list above, by its key.",
|
| 424 |
+
"6. Keep it short. Fewer steps that work beat more steps that guess.",
|
| 425 |
+
]
|
| 426 |
+
return "\n".join(lines)
|
| 427 |
+
|
| 428 |
+
|
| 429 |
+
def _flow_from_tool_call(obj):
|
| 430 |
+
"""The model's tool arguments -> `(draft, refusal)`. A shape error is a refusal, never a crash."""
|
| 431 |
+
if not isinstance(obj, dict):
|
| 432 |
+
return None, "the assistant's answer could not be read"
|
| 433 |
+
if str(obj.get("kind") or "") == "refused":
|
| 434 |
+
return None, (str(obj.get("refusal") or "").strip()
|
| 435 |
+
or "the assistant could not build this from the steps available")
|
| 436 |
+
acts = obj.get("actions")
|
| 437 |
+
if not isinstance(acts, list) or not acts:
|
| 438 |
+
return None, ("the assistant did not produce any steps - try describing what should "
|
| 439 |
+
"happen, one action at a time")
|
| 440 |
+
out = []
|
| 441 |
+
for a in acts[:MAX_DRAFT_ACTIONS]:
|
| 442 |
+
if not isinstance(a, dict) or not str(a.get("kind") or "").strip():
|
| 443 |
+
continue
|
| 444 |
+
cfg = a.get("config")
|
| 445 |
+
out.append({"kind": str(a["kind"]).strip(),
|
| 446 |
+
"config": cfg if isinstance(cfg, dict) else {},
|
| 447 |
+
"why": str(a.get("why") or "").strip()[:200]})
|
| 448 |
+
if not out:
|
| 449 |
+
return None, "the assistant's steps could not be read"
|
| 450 |
+
return {"name": str(obj.get("name") or "").strip()[:80] or "New automation",
|
| 451 |
+
"trigger": str(obj.get("trigger") or "").strip(),
|
| 452 |
+
"table": str(obj.get("table") or "").strip(),
|
| 453 |
+
# ββ THE TRUNCATION IS REPORTED, and it is a STANDING RULE that it must be (owner,
|
| 454 |
+
# 2026-08-12, W30/R6 second sentence): *"if there is lag or it can't be done, you need
|
| 455 |
+
# to explicitly tell me why and recommend a fix"* β **a silent truncation IS the
|
| 456 |
+
# violation, not the limit.** `acts[:MAX_DRAFT_ACTIONS]` above dropped everything past
|
| 457 |
+
# the twelfth and said nothing, so a model that answered with a twenty-step journey had
|
| 458 |
+
# eight steps deleted between the answer and the screen, with no key anywhere in the
|
| 459 |
+
# response naming them. `MAX_ACTIONS` is 20, so those steps were STORABLE β this
|
| 460 |
+
# ceiling is the draft door's own, which makes reporting it the whole obligation.
|
| 461 |
+
# β Found by the verifier that checked this ticket, not by a gate.
|
| 462 |
+
"asked": len([a for a in acts if isinstance(a, dict)]),
|
| 463 |
+
"actions": out}, ""
|
| 464 |
+
|
| 465 |
+
|
| 466 |
+
def draft_flow(*, prompt, catalog, required, triggers, tables, chat=None, timeout=None,
|
| 467 |
+
st=None, user="", model=None):
|
| 468 |
+
"""A sentence -> `(draft, refusal_sentence, provider)`. β NOTHING IS SAVED HERE.
|
| 469 |
+
|
| 470 |
+
Exactly one of `draft` and `refusal_sentence` is truthy β the same contract
|
| 471 |
+
`web_agent.run_step` keeps, so a caller has no third case to get wrong.
|
| 472 |
+
|
| 473 |
+
β W35-T41 / C7 β `st`/`user` are the usage ledger's target, exactly as on `decide` above and for
|
| 474 |
+
the same reason: both of this function's callers (`automation_engine._ai_agent_plan` and
|
| 475 |
+
`routes_automation`'s draft door) are in lane D's fence. C7 says E adds the ledger line here and
|
| 476 |
+
D asserts it; the two keywords are what D has to pass for the line to be attributable.
|
| 477 |
+
"""
|
| 478 |
+
# β DECLARED AT THE TOP OF THE FUNCTION, not beside the assignment inside the provider loop.
|
| 479 |
+
# It parses either way; a reader scanning for the declaration does not look inside a `for`.
|
| 480 |
+
global LAST_ANTHROPIC_TRANSPORT
|
| 481 |
+
import usage_ledger # noqa: PLC0415
|
| 482 |
+
text = str(prompt or "").strip()[:MAX_PROMPT_CHARS]
|
| 483 |
+
if not text:
|
| 484 |
+
return None, "type what you want the automation to do", None
|
| 485 |
+
kinds = sorted({str(r.get("kind")) for r in (catalog or []) if r.get("ready")})
|
| 486 |
+
if not kinds:
|
| 487 |
+
return None, "this deployment offers no automation steps to build with", None
|
| 488 |
+
trigger_keys = sorted({str(t.get("key")) for t in (triggers or [])
|
| 489 |
+
if t.get("key") and not t.get("planned")}) or ["manual"]
|
| 490 |
+
table_keys = sorted({str(t.get("key")) for t in (tables or []) if t.get("key")}) or [""]
|
| 491 |
+
tools = [{"type": "function", "function": {
|
| 492 |
+
"name": "build_automation",
|
| 493 |
+
"description": "Emit the automation, or refuse.",
|
| 494 |
+
"parameters": flow_schema(kinds, trigger_keys, table_keys)}}]
|
| 495 |
+
messages = [{"role": "system",
|
| 496 |
+
"content": flow_system_prompt(catalog, required, triggers, tables)},
|
| 497 |
+
{"role": "user", "content": text}]
|
| 498 |
+
|
| 499 |
+
if chat is not None:
|
| 500 |
+
# β THE INJECTED PATH IS THE PROVEN PATH. It runs the SAME parse and the SAME refusal
|
| 501 |
+
# branches as a live call; only the transport is replaced.
|
| 502 |
+
draft, refusal = _flow_from_tool_call(chat(messages, tools))
|
| 503 |
+
return draft, refusal, "injected"
|
| 504 |
+
|
| 505 |
+
provs = flow_providers(model)
|
| 506 |
+
if not provs:
|
| 507 |
+
# β SAY SO. An AI feature that silently does nothing is indistinguishable from one that was
|
| 508 |
+
# never built [[flag-shipped-without-its-writer]].
|
| 509 |
+
return None, ("the assistant is not configured on this deployment, so an automation cannot "
|
| 510 |
+
"be drafted from a description yet"), None
|
| 511 |
+
tmo = float(timeout or TIMEOUT_SECONDS)
|
| 512 |
+
problems = []
|
| 513 |
+
import providers as _prov
|
| 514 |
+
for p in provs:
|
| 515 |
+
# ββ W36-T35 / R4 β THE OWNER QUOTED THIS LINE BACK AT US. It used to read
|
| 516 |
+
# `problems.append(f"{p['name']}: tool calls are not wired for this shape")` and `continue`,
|
| 517 |
+
# so the sentence *"anthropic: tool calls are not wired for this shape"* appeared under the
|
| 518 |
+
# Agent module verbatim. R4: *"Anthropic becomes the tool-calling path that always works."*
|
| 519 |
+
# It is wired now, through the ONE wire in `providers`, and it matters more than it looks:
|
| 520 |
+
# every side rung on this account is refusing today (cerebras 402, groq 404, openrouter
|
| 521 |
+
# 402), so without this branch the drafter cannot answer at all.
|
| 522 |
+
# β NO `effort` ON THIS DOOR β `output_config.effort` errors on Haiku 4.5, the tier this
|
| 523 |
+
# ladder runs. The parameter is the caller's to send, which is why the wire takes it.
|
| 524 |
+
# β D-346 (W37-T39): BOTH shapes now yield the SAME `(status, body)` pair, so every branch
|
| 525 |
+
# below reads one thing. The anthropic side gets there through `anthropic_send` (official
|
| 526 |
+
# SDK when installed, the identical raw POST when not); the openai side still posts here
|
| 527 |
+
# because there is no shared SDK across three different vendors on that wire.
|
| 528 |
+
global LAST_ANTHROPIC_TRANSPORT
|
| 529 |
+
try:
|
| 530 |
+
if p["shape"] == "anthropic":
|
| 531 |
+
req = _prov.anthropic_request(
|
| 532 |
+
model=p["model"], key=os.environ[p["env"]].strip(), system=None,
|
| 533 |
+
messages=messages, tools=tools, max_tokens=1500, tool_choice="required")
|
| 534 |
+
status, body, transport = _prov.anthropic_send(req, timeout=tmo)
|
| 535 |
+
LAST_ANTHROPIC_TRANSPORT = transport
|
| 536 |
+
else:
|
| 537 |
+
r = requests.post(p["url"], timeout=tmo,
|
| 538 |
+
headers={"Authorization": f"Bearer {os.environ[p['env']].strip()}",
|
| 539 |
+
"Content-Type": "application/json"},
|
| 540 |
+
json={"model": p["model"], "messages": messages, "tools": tools,
|
| 541 |
+
"tool_choice": "required", "temperature": 0.1,
|
| 542 |
+
"max_tokens": 1500})
|
| 543 |
+
status = r.status_code
|
| 544 |
+
body = r.json() if (r.content and r.status_code == 200) else {"_text": r.text}
|
| 545 |
+
except Exception as e: # noqa: BLE001
|
| 546 |
+
problems.append(f"{p['name']}: {type(e).__name__}")
|
| 547 |
+
continue
|
| 548 |
+
if status != 200:
|
| 549 |
+
# β A SENTENCE, NOT `HTTP 402` (R4's third clause). The owner read the status codes off
|
| 550 |
+
# this very door. `refusal_sentence` also decides whether this was a CREDIT failure, and
|
| 551 |
+
# the memo makes the next turn SKIP the empty account instead of paying for it again.
|
| 552 |
+
# β The body is re-serialised for the substring test because the SDK path never had a
|
| 553 |
+
# `.text` β that is the one thing this normalisation costs, and it costs nothing else.
|
| 554 |
+
detail = json.dumps(body)[:600] if isinstance(body, dict) else str(body)[:600]
|
| 555 |
+
if _prov.is_credit_failure(status, detail):
|
| 556 |
+
_prov.mark_no_credit(p["name"])
|
| 557 |
+
problems.append(_prov.refusal_sentence(p["name"], status, detail))
|
| 558 |
+
continue
|
| 559 |
+
try:
|
| 560 |
+
body = body or {}
|
| 561 |
+
if p["shape"] == "anthropic":
|
| 562 |
+
_text, args, _refused = _prov.anthropic_read(body)
|
| 563 |
+
if _refused:
|
| 564 |
+
problems.append(f"{p['name']}: {_refused}")
|
| 565 |
+
continue
|
| 566 |
+
else:
|
| 567 |
+
calls = (((body.get("choices") or [{}])[0].get("message") or {})
|
| 568 |
+
.get("tool_calls") or [])
|
| 569 |
+
args = json.loads(calls[0]["function"]["arguments"]) if calls else None
|
| 570 |
+
except Exception as e: # noqa: BLE001
|
| 571 |
+
problems.append(f"{p['name']}: unreadable answer ({type(e).__name__})")
|
| 572 |
+
continue
|
| 573 |
+
# ββ C7 β THE LEDGER LINE. Placed after the parse rather than before it so an UNREADABLE
|
| 574 |
+
# answer is not double-counted by the `continue` above... β which means an unreadable answer
|
| 575 |
+
# is NOT counted at all, and that is a deliberate, disclosed loss: a body this code cannot
|
| 576 |
+
# parse is a body whose `usage` it also cannot trust, and `body` is out of scope in that
|
| 577 |
+
# branch by construction. The 200-with-junk case is rare and named here rather than
|
| 578 |
+
# silently rounded to zero.
|
| 579 |
+
ins, outs = usage_ledger.tokens_from(body)
|
| 580 |
+
usage_ledger.record("automation_draft", p["name"], p["model"], ins, outs,
|
| 581 |
+
total=usage_ledger.total_from(body), st=st, user=user)
|
| 582 |
+
draft, refusal = _flow_from_tool_call(args)
|
| 583 |
+
if draft is None and isinstance(args, dict) and str(args.get("kind")) == "refused":
|
| 584 |
+
# β A REFUSAL IS AN ANSWER, NOT A FAULT, so it does NOT fall through to a more
|
| 585 |
+
# expensive rung β the model has just said this cannot be built. `decide()` takes the
|
| 586 |
+
# same posture for the same reason.
|
| 587 |
+
return None, refusal, p["name"]
|
| 588 |
+
if draft is not None:
|
| 589 |
+
return draft, "", p["name"]
|
| 590 |
+
problems.append(f"{p['name']}: {refusal}")
|
| 591 |
+
return None, ("; ".join(problems)[:300] or "no provider answered"), None
|
api/connectors_tt.py
CHANGED
|
@@ -1,568 +1,568 @@
|
|
| 1 |
-
"""connectors_tt.py β the TIKTOK connector (wave 29 Β· item 7 Β· DEBT D-9 Β· rulings R1 + R2).
|
| 2 |
-
|
| 3 |
-
Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
|
| 4 |
-
automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
|
| 5 |
-
exists at all rather than another thousand lines inside the engine.
|
| 6 |
-
|
| 7 |
-
β **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema β 40 profile / 43
|
| 8 |
-
post / 17 comment fields, each with the vendor's own type, description and `pii` flag β was read
|
| 9 |
-
live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
|
| 10 |
-
`.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
|
| 11 |
-
close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
|
| 12 |
-
name below reads through a candidate list it is because the vendor has two names for one fact
|
| 13 |
-
(`biography`/`signature`, `region`/`country`), never because the name is uncertain.
|
| 14 |
-
|
| 15 |
-
β **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned β
|
| 16 |
-
public data through a supplier, exactly the rail `connectors_ig.py` states for Instagram. The
|
| 17 |
-
vendor key is a key to a SUPPLIER.
|
| 18 |
-
|
| 19 |
-
β **THE TRANSPORT IS `connectors_bd.py` β SHARED, VENDOR-NAMED, AND NO LONGER BORROWED FROM THE
|
| 20 |
-
OTHER PLATFORM'S CONNECTOR** (WAVE 30 Β· T09, DEBT D-128). `bd_call`, `bd_scrape` and
|
| 21 |
-
`bd_filter_start` take the dataset id as a PARAMETER β they are Bright Data's wire, not
|
| 22 |
-
Instagram's β and re-implementing them here would be a second copy of the deferral handling, the
|
| 23 |
-
truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
|
| 24 |
-
Until wave 30 the code was right and the NAME was wrong: this file imported thirteen symbols from
|
| 25 |
-
`connectors_ig`, which read as a dependency on Instagram and was really a dependency on a supplier.
|
| 26 |
-
β **This file now imports ZERO names from `connectors_ig`, and a gate check asserts that**, because
|
| 27 |
-
the sentence above is the kind that quietly stops being true.
|
| 28 |
-
|
| 29 |
-
β **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
|
| 30 |
-
1. the real ROW shape β `/metadata` describes a DATASET, and Instagram's rows carry undeclared
|
| 31 |
-
envelope keys (`timestamp`, `input`) that no metadata call mentions;
|
| 32 |
-
2. that a declared field POPULATES β Bright Data's Instagram Reels *declares* `views: number`
|
| 33 |
-
and delivers an account-grain wrong number (Β§4e). **Declared is not delivered**, and the one
|
| 34 |
-
TikTok claim that matters most (`play_count`) is exactly a declaration.
|
| 35 |
-
"""
|
| 36 |
-
from __future__ import annotations
|
| 37 |
-
|
| 38 |
-
import automation_engine as engine
|
| 39 |
-
# β T09 β FOUR NAMES CAME OFF THIS LIST AND NOTHING BROKE, which is the point of deriving an
|
| 40 |
-
# import block from the AST both ways. `bd_call`, `bd_filter_start`, `bd_key` and `bd_ready` were
|
| 41 |
-
# imported here under a comment claiming they were *"re-exported for the runners"*; no runner ever
|
| 42 |
-
# read them off this module (the engine imports them from the transport itself), so they were four
|
| 43 |
-
# lines of dependency nobody was paying for. `[[artifact-with-no-importer]]` in its smallest form.
|
| 44 |
-
from connectors_bd import (
|
| 45 |
-
_bd_first_url,
|
| 46 |
-
_bd_flag,
|
| 47 |
-
_bd_list,
|
| 48 |
-
_bd_source_payload,
|
| 49 |
-
_first,
|
| 50 |
-
_ig_int,
|
| 51 |
-
bd_scrape,
|
| 52 |
-
)
|
| 53 |
-
|
| 54 |
-
# ---------------------------------------------------------------------------------------------
|
| 55 |
-
# THE DATASETS
|
| 56 |
-
# ---------------------------------------------------------------------------------------------
|
| 57 |
-
# β CATALOGUE PRESENCE IS NOT ENTITLEMENT β the same finding Instagram produced. `GET
|
| 58 |
-
# /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
|
| 59 |
-
# full field list, and the two DISCOVERY halves answer **404 for our key**:
|
| 60 |
-
# `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
|
| 61 |
-
# β TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
|
| 62 |
-
# does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
|
| 63 |
-
TT_DS_PROFILES = "gd_l1villgoiiidt09ci" # TikTok - Profiles. 40 fields, 152,000,000 records
|
| 64 |
-
TT_DS_POSTS = "gd_lu702nij2f790tmv9h" # TikTok - Posts. 43 fields
|
| 65 |
-
TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k" # TikTok - Comments. 17 fields
|
| 66 |
-
|
| 67 |
-
#: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
|
| 68 |
-
#: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
|
| 69 |
-
TT_POST_TYPE_VIDEO = "video"
|
| 70 |
-
TT_POST_TYPE_CONTENT = "content"
|
| 71 |
-
|
| 72 |
-
#: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
|
| 73 |
-
#: beside the dataset ids because it is the same class of vendor fact.
|
| 74 |
-
#: β ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
|
| 75 |
-
#: string from `_PROFILE_RULES` (contract C2, E's half) β this exists for the connector's own
|
| 76 |
-
#: batch calls, and the gate asserts the two agree rather than trusting that they do.
|
| 77 |
-
TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
|
| 78 |
-
|
| 79 |
-
|
| 80 |
-
def tt_profile_url(handle):
|
| 81 |
-
"""`nurilab` β `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
|
| 82 |
-
h = str(handle or "").strip().lstrip("@")
|
| 83 |
-
return TT_PROFILE_URL.format(handle=h) if h else ""
|
| 84 |
-
|
| 85 |
-
|
| 86 |
-
# ---------------------------------------------------------------------------------------------
|
| 87 |
-
# THE FIELD MAPS
|
| 88 |
-
# ---------------------------------------------------------------------------------------------
|
| 89 |
-
# Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
|
| 90 |
-
# in `automation_engine`. The rules they all obey, stated once:
|
| 91 |
-
#
|
| 92 |
-
# * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
|
| 93 |
-
# so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
|
| 94 |
-
# returns `None` (never 0) when nothing matches, which is what makes that possible.
|
| 95 |
-
# * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
|
| 96 |
-
# rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
|
| 97 |
-
# * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
|
| 98 |
-
# vendor's side is preserved rather than silently discarded while our column model catches up.
|
| 99 |
-
# * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
|
| 100 |
-
# (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
|
| 101 |
-
# ride in `source_payload` where they make no claim.
|
| 102 |
-
|
| 103 |
-
|
| 104 |
-
def _tt_str(node, *names):
|
| 105 |
-
"""The first non-empty string among `names`, or None when the vendor sent nothing.
|
| 106 |
-
|
| 107 |
-
β `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest β
|
| 108 |
-
an empty string written into a cell claims "we looked and it is empty".
|
| 109 |
-
"""
|
| 110 |
-
v = _first(node, *names)
|
| 111 |
-
if v is None:
|
| 112 |
-
return None
|
| 113 |
-
s = str(v).strip()
|
| 114 |
-
return s or None
|
| 115 |
-
|
| 116 |
-
|
| 117 |
-
def _tt_pct(node, *names):
|
| 118 |
-
"""A vendor 0β1 engagement fraction β our stored 0β100 percentage, or None.
|
| 119 |
-
|
| 120 |
-
β THE Γ100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
|
| 121 |
-
the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` β
|
| 122 |
-
measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
|
| 123 |
-
"""
|
| 124 |
-
v = _first(node, *names)
|
| 125 |
-
if v is None:
|
| 126 |
-
return None
|
| 127 |
-
out = engine._pct100(v)
|
| 128 |
-
return out or None
|
| 129 |
-
|
| 130 |
-
|
| 131 |
-
def _tt_day(node, *names):
|
| 132 |
-
"""A vendor stamp β `YYYY-MM-DD`, or None. Our `date` columns store a day."""
|
| 133 |
-
v = _first(node, *names)
|
| 134 |
-
if v is None:
|
| 135 |
-
return None
|
| 136 |
-
return engine._day(v) or None
|
| 137 |
-
|
| 138 |
-
|
| 139 |
-
def _drop_blanks(row):
|
| 140 |
-
"""The one place a mapped row loses its `None`s β see the BLANK MEANS NOT READ rule above."""
|
| 141 |
-
return {k: v for k, v in row.items() if v is not None and v != ""}
|
| 142 |
-
|
| 143 |
-
|
| 144 |
-
def normalize_profile(node, handle=""):
|
| 145 |
-
"""A TikTok Profiles row β the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
|
| 146 |
-
|
| 147 |
-
β TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
|
| 148 |
-
* `biography` is PRIMARY and `signature` the FALLBACK β the probe measured `signature`
|
| 149 |
-
populated on 85% of rows and they carry the same text;
|
| 150 |
-
* `region` is PRIMARY and `country` the FALLBACK β `region` is the one with a documented
|
| 151 |
-
two-letter-ISO description, `country` has no description at all.
|
| 152 |
-
β `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
|
| 153 |
-
`ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
|
| 154 |
-
only count of its kind the dataset offers.
|
| 155 |
-
"""
|
| 156 |
-
node = node if isinstance(node, dict) else {}
|
| 157 |
-
account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
|
| 158 |
-
return _drop_blanks({
|
| 159 |
-
"platform": engine.PLATFORM_TIKTOK,
|
| 160 |
-
"handle": account,
|
| 161 |
-
"full_name": _tt_str(node, "nickname"),
|
| 162 |
-
"tt_id": _tt_str(node, "id"),
|
| 163 |
-
"profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
|
| 164 |
-
"bio": _tt_str(node, "biography", "signature"),
|
| 165 |
-
"external_url": _bd_first_url(_first(node, "bio_link")),
|
| 166 |
-
"verified": _bd_flag(node, "is_verified"),
|
| 167 |
-
"is_private": _bd_flag(node, "is_private"),
|
| 168 |
-
# β APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
|
| 169 |
-
# on their own description. It is the closest thing TikTok has to Instagram's
|
| 170 |
-
# `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent β so
|
| 171 |
-
# the approximation only ever fills a cell the vendor actually answered.
|
| 172 |
-
"is_business": _bd_flag(node, "is_commerce_user"),
|
| 173 |
-
"followers": _ig_int(_first(node, "followers")),
|
| 174 |
-
"following": _ig_int(_first(node, "following")),
|
| 175 |
-
"posts_count": _ig_int(_first(node, "videos_count")),
|
| 176 |
-
# β `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
|
| 177 |
-
# nulls). It is not a post-level number and it is not our `likes` column, which is why it
|
| 178 |
-
# is stored under a different name.
|
| 179 |
-
"likes_received": _ig_int(_first(node, "likes")),
|
| 180 |
-
"avg_engagement": _tt_pct(node, "awg_engagement_rate"),
|
| 181 |
-
"like_engagement": _tt_pct(node, "like_engagement_rate"),
|
| 182 |
-
"comment_engagement": _tt_pct(node, "comment_engagement_rate"),
|
| 183 |
-
"country_code": _tt_str(node, "region", "country"),
|
| 184 |
-
"region": _tt_str(node, "region"),
|
| 185 |
-
"predicted_lang": _tt_str(node, "predicted_lang"),
|
| 186 |
-
# β ACCOUNT AGE, NOT A MEASUREMENT STAMP β `create_time` on a profile is when the ACCOUNT
|
| 187 |
-
# was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
|
| 188 |
-
# which is why the append law dates a snapshot by when WE read it.
|
| 189 |
-
"account_created_at": _tt_day(node, "create_time"),
|
| 190 |
-
"source_payload": _bd_source_payload(node),
|
| 191 |
-
})
|
| 192 |
-
|
| 193 |
-
|
| 194 |
-
def tt_post_type(node):
|
| 195 |
-
"""A TikTok post row β one of OUR three type options, or None.
|
| 196 |
-
|
| 197 |
-
β THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
|
| 198 |
-
`"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
|
| 199 |
-
vendor's token would fail `_clean_field`'s option check on the way in and would put an
|
| 200 |
-
untranslated API word in front of a user on the way out.
|
| 201 |
-
|
| 202 |
-
So: `video` is `video`, and `content` β TikTok's photo-mode post β is `image`, EXCEPT when the
|
| 203 |
-
row carries more than one `carousel_images` entry, which is what a carousel IS on either
|
| 204 |
-
network. β The multi-image branch is decided from the IMAGES, never from the type token: the
|
| 205 |
-
token cannot express it, so inferring `carousel` from the word would be inventing a fact.
|
| 206 |
-
β An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
|
| 207 |
-
that is exactly what would make the wrong default invisible).
|
| 208 |
-
"""
|
| 209 |
-
raw = str((node or {}).get("post_type") or "").strip().lower()
|
| 210 |
-
if raw == TT_POST_TYPE_VIDEO:
|
| 211 |
-
return "video"
|
| 212 |
-
if raw != TT_POST_TYPE_CONTENT:
|
| 213 |
-
return None
|
| 214 |
-
images = (node or {}).get("carousel_images")
|
| 215 |
-
return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
|
| 216 |
-
|
| 217 |
-
|
| 218 |
-
def normalize_post(node):
|
| 219 |
-
"""A TikTok Posts row β the `ut_tt_posts` cell shape. None when it carries no identity.
|
| 220 |
-
|
| 221 |
-
β THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
|
| 222 |
-
Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
|
| 223 |
-
fact β `play_count` IS the count TikTok displays under a video β so it maps to `views` and
|
| 224 |
-
`ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
|
| 225 |
-
manufacture a second measurement that a rollup could average or double-count, which is a worse
|
| 226 |
-
outcome than the missing column it would paper over.
|
| 227 |
-
|
| 228 |
-
β `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
|
| 229 |
-
the probe measured them as the same shape. That equality is what lets the commentsβposts link
|
| 230 |
-
join with NO normaliser, which the Instagram side never had.
|
| 231 |
-
β `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
|
| 232 |
-
β `commerce_info` is a business/commerce LOCATION per its own description β cities and
|
| 233 |
-
countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
|
| 234 |
-
no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
|
| 235 |
-
"""
|
| 236 |
-
node = node if isinstance(node, dict) else {}
|
| 237 |
-
shortcode = _tt_str(node, "shortcode", "post_id")
|
| 238 |
-
if not shortcode:
|
| 239 |
-
return None
|
| 240 |
-
return _drop_blanks({
|
| 241 |
-
"platform": engine.PLATFORM_TIKTOK,
|
| 242 |
-
"shortcode": shortcode,
|
| 243 |
-
# ββ `account_id`, NOT `profile_username` β MEASURED on a real Posts row 2026-08-12.
|
| 244 |
-
# The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
|
| 245 |
-
# @handle (`"d1na_th"`) β the same field `normalize_profile` already reads for `handle`, so
|
| 246 |
-
# one name means one thing across both corpora. Reading the display name silently broke the
|
| 247 |
-
# only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
|
| 248 |
-
# NOTHING, so a person could not filter posts by creator and a rollup would count zero.
|
| 249 |
-
# β NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
|
| 250 |
-
# different fact, and filling a join key with it is worse than leaving it blank β a blank
|
| 251 |
-
# is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
|
| 252 |
-
# The URL is the honest second source: it carries the handle by construction.
|
| 253 |
-
"influencer_key": (_tt_str(node, "account_id")
|
| 254 |
-
or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
|
| 255 |
-
"posted_at": _tt_day(node, "create_time"),
|
| 256 |
-
"type": tt_post_type(node),
|
| 257 |
-
"caption": _tt_str(node, "description"),
|
| 258 |
-
"url": _tt_str(node, "url"),
|
| 259 |
-
"hashtags": _bd_list(node, "hashtags"),
|
| 260 |
-
"tagged_location": _tt_str(node, "commerce_info"),
|
| 261 |
-
"views": _ig_int(_first(node, "play_count")),
|
| 262 |
-
"likes": _ig_int(_first(node, "digg_count")),
|
| 263 |
-
"comments": _ig_int(_first(node, "comment_count")),
|
| 264 |
-
"shares": _ig_int(_first(node, "num_share_count")),
|
| 265 |
-
"saves": _ig_int(_first(node, "collect_count")),
|
| 266 |
-
"video_duration": _ig_int(_first(node, "video_duration")),
|
| 267 |
-
"source_payload": _bd_source_payload(node),
|
| 268 |
-
})
|
| 269 |
-
|
| 270 |
-
|
| 271 |
-
def normalize_comment(node):
|
| 272 |
-
"""A TikTok Comments row β the `ut_tt_comments` cell shape. None without a comment id.
|
| 273 |
-
|
| 274 |
-
β THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
|
| 275 |
-
`replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
|
| 276 |
-
`source_payload`. Reading the array's length instead would be a second, disagreeing answer to
|
| 277 |
-
a question the vendor already answers β and it would disagree, because a page of replies is not
|
| 278 |
-
all of them.
|
| 279 |
-
β `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
|
| 280 |
-
text and needs defensive parsing. It still goes through `_tt_day` β one date path, so a vendor
|
| 281 |
-
that changes its mind cannot change ours.
|
| 282 |
-
β The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
|
| 283 |
-
PII) stay in `source_payload` and are promoted to no column, which is the same posture the
|
| 284 |
-
Instagram comment schema takes for the same D-24 reason.
|
| 285 |
-
"""
|
| 286 |
-
node = node if isinstance(node, dict) else {}
|
| 287 |
-
comment_key = _tt_str(node, "comment_id")
|
| 288 |
-
if not comment_key:
|
| 289 |
-
return None
|
| 290 |
-
return _drop_blanks({
|
| 291 |
-
"platform": engine.PLATFORM_TIKTOK,
|
| 292 |
-
"comment_key": comment_key,
|
| 293 |
-
"shortcode": _tt_str(node, "post_id"),
|
| 294 |
-
# ββ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
|
| 295 |
-
# vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
|
| 296 |
-
# primary first, so a row carrying the rich form is not silently served the plain one.
|
| 297 |
-
# β The commenter's identity is deliberately NOT promoted β see `TT_COMMENT_FIELDS`.
|
| 298 |
-
"text": _tt_str(node, "comment_text", "comment_text_only"),
|
| 299 |
-
"commented_at": _tt_day(node, "date_created"),
|
| 300 |
-
"likes": _ig_int(_first(node, "num_likes")),
|
| 301 |
-
"replies": _ig_int(_first(node, "num_replies")),
|
| 302 |
-
"source_payload": _bd_source_payload(node),
|
| 303 |
-
})
|
| 304 |
-
|
| 305 |
-
|
| 306 |
-
#: β The three maps, addressable by name β so a gate (and the runners in T04-T06) can walk them
|
| 307 |
-
#: rather than naming three functions, and so adding a fourth dataset is one entry.
|
| 308 |
-
TT_NORMALIZERS = {
|
| 309 |
-
"tt_profile": normalize_profile,
|
| 310 |
-
"tt_post_metrics": normalize_post,
|
| 311 |
-
"tt_comments": normalize_comment,
|
| 312 |
-
}
|
| 313 |
-
|
| 314 |
-
|
| 315 |
-
# ---------------------------------------------------------------------------------------------
|
| 316 |
-
# THE FETCH β wave 30 Β· W30-T08 (carrying wave-29's dropped T05)
|
| 317 |
-
# ---------------------------------------------------------------------------------------------
|
| 318 |
-
|
| 319 |
-
def tt_handle(url):
|
| 320 |
-
"""A TikTok profile URL **or** a bare handle β the handle. `''` when it is neither.
|
| 321 |
-
|
| 322 |
-
Deliberately permissive about the input and strict about the output, because the two callers
|
| 323 |
-
hand it different things: an automation stores whatever a person typed in the profile column
|
| 324 |
-
(`@nurilab`, `nurilab`, or the full URL), while the discovery runner already holds a clean
|
| 325 |
-
`account_id`. One normaliser, so a row found by discovery and a row typed by hand cannot
|
| 326 |
-
resolve to two different handles.
|
| 327 |
-
"""
|
| 328 |
-
s = str(url or "").strip()
|
| 329 |
-
if not s:
|
| 330 |
-
return ""
|
| 331 |
-
if "tiktok.com" in s.lower():
|
| 332 |
-
# Everything after the first `@`, up to the next path segment or query.
|
| 333 |
-
tail = s.split("@", 1)[1] if "@" in s else ""
|
| 334 |
-
s = tail.split("/")[0].split("?")[0].split("#")[0]
|
| 335 |
-
s = s.strip().lstrip("@").strip()
|
| 336 |
-
# A handle is the vendor's `account_id` shape: alphanumerics, dots and underscores.
|
| 337 |
-
return s if s and all(c.isalnum() or c in "._" for c in s) else ""
|
| 338 |
-
|
| 339 |
-
|
| 340 |
-
def tt_post_urls(node, limit=0):
|
| 341 |
-
"""β WAVE 30 Β· T10 β the profile row's own post permalinks, newest-first as the vendor sends.
|
| 342 |
-
|
| 343 |
-
β THIS IS WHY TIKTOK POST CAPTURE COSTS NO EXTRA DISCOVERY. `top_videos` rides the PROFILE row
|
| 344 |
-
we have already bought, so the posts read is a scrape of links we hold, never a search for them.
|
| 345 |
-
The two TikTok DISCOVERY datasets (posts-by-profile, posts-by-keyword) are **404 for our key**,
|
| 346 |
-
so a design that reached for either would not merely be dearer, it would not work.
|
| 347 |
-
|
| 348 |
-
ββ CORRECTED 2026-08-12 β THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
|
| 349 |
-
array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
|
| 350 |
-
read `/datasets/{id}/metadata` β a DATASET description β and the phrase quoted was the field's
|
| 351 |
-
`ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
|
| 352 |
-
(measured below), so the reader built against the quoted sentence found nothing, forever, in
|
| 353 |
-
silence. β The transferable half: *"the probe measured X"* and *"the probe read a declaration
|
| 354 |
-
of X"* are different claims, and prose cannot be told apart by a reader downstream β which is
|
| 355 |
-
why the correction names the method, not just the value.
|
| 356 |
-
|
| 357 |
-
β `top_posts_data` is deliberately NOT read: the probe calls it *"a thin dup of `top_videos`"*,
|
| 358 |
-
and preferring whichever happened to be longer is how one creator's window silently differs
|
| 359 |
-
from another's.
|
| 360 |
-
β `limit <= 0` means "everything the row carried". The CAP IS THE CALLER'S β `config.maxPosts`,
|
| 361 |
-
validated 1..12 β and it is applied here rather than after the scrape so an unwanted post is
|
| 362 |
-
never bought. [[a-constant-two-features-share]]: the 12 is the vendor's measured profile window,
|
| 363 |
-
not a number this function may invent.
|
| 364 |
-
"""
|
| 365 |
-
raw = (node or {}).get("top_videos")
|
| 366 |
-
out = []
|
| 367 |
-
for item in raw if isinstance(raw, list) else []:
|
| 368 |
-
# ββ MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
|
| 369 |
-
# `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
|
| 370 |
-
# live handle returns **19 DICTS**, keyed
|
| 371 |
-
# `video_url Β· video_id Β· playcount Β· diggcount Β· commentcount Β· share_count Β·
|
| 372 |
-
# favorites_count Β· create_date Β· cover_image`.
|
| 373 |
-
# The docstring above cites the $0 probe as having "measured" permalinks β it had not, and
|
| 374 |
-
# could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
|
| 375 |
-
# so in terms (*"what $0 cannot buy β¦ the real ROW shape β¦ that a declared field
|
| 376 |
-
# POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
|
| 377 |
-
# declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
|
| 378 |
-
# the first. [[reachable-is-not-the-same-as-built]]
|
| 379 |
-
# β The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
|
| 380 |
-
# list on every real profile β post capture could not have worked for anybody, and the
|
| 381 |
-
# T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
|
| 382 |
-
# written from a schema tests the schema.
|
| 383 |
-
# β `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
|
| 384 |
-
# because it costs nothing and is what a future corpus revision would most likely use. The
|
| 385 |
-
# bare-string branch stays for the same reason β this widens what is ACCEPTED and invents
|
| 386 |
-
# nothing: a shape that yields no `httpβ¦` value still degrades to "no posts", exactly as
|
| 387 |
-
# before, rather than to a URL built out of a guess.
|
| 388 |
-
# β `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
|
| 389 |
-
# whichever array happened to be longer is how one creator's window silently differs from
|
| 390 |
-
# another's, and that reasoning is unchanged by this correction.
|
| 391 |
-
if isinstance(item, dict):
|
| 392 |
-
u = str(item.get("video_url") or item.get("url") or "").strip()
|
| 393 |
-
else:
|
| 394 |
-
u = str(item or "").strip()
|
| 395 |
-
if u.lower().startswith("http") and u not in out:
|
| 396 |
-
out.append(u)
|
| 397 |
-
return out[:limit] if limit and limit > 0 else out
|
| 398 |
-
|
| 399 |
-
|
| 400 |
-
def pull_posts_tt(post_urls, log=print, deferred=None):
|
| 401 |
-
"""The TikTok Posts dataset for a list of permalinks β `(rows, note)`, already normalised.
|
| 402 |
-
|
| 403 |
-
β ONE CALL FOR THE WHOLE WINDOW. `bd_scrape` has always taken a list, and the Instagram side
|
| 404 |
-
measured what happens when a caller forgets: 25 records, one billed snapshot each, a walk still
|
| 405 |
-
running at 67 minutes. Nothing here loops per URL.
|
| 406 |
-
"""
|
| 407 |
-
urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
|
| 408 |
-
if not urls:
|
| 409 |
-
return [], ""
|
| 410 |
-
rows, note = bd_scrape(TT_DS_POSTS, urls, deferred=deferred)
|
| 411 |
-
if note:
|
| 412 |
-
log(f"[aios-tt] posts: {note}")
|
| 413 |
-
return [], note
|
| 414 |
-
out = [r for r in (normalize_post(n) for n in rows) if r]
|
| 415 |
-
return out, ""
|
| 416 |
-
|
| 417 |
-
|
| 418 |
-
def pull_comments_tt(post_urls, log=print, deferred=None):
|
| 419 |
-
"""The TikTok Comments dataset for a list of POST permalinks β `(rows, note)`, normalised.
|
| 420 |
-
|
| 421 |
-
β THE MOST EXPENSIVE THING THIS PRODUCT BUYS, and the reason `commentMetrics` defaults OFF on
|
| 422 |
-
both networks: a comments scrape ingests identifiable third parties who never entered anybody's
|
| 423 |
-
list (D-24). The mapper already keeps every commenter field in `source_payload` and promotes
|
| 424 |
-
none of them to a column; this function adds no new exposure, it just has to be asked for.
|
| 425 |
-
"""
|
| 426 |
-
urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
|
| 427 |
-
if not urls:
|
| 428 |
-
return [], ""
|
| 429 |
-
rows, note = bd_scrape(TT_DS_COMMENTS, urls, deferred=deferred)
|
| 430 |
-
if note:
|
| 431 |
-
log(f"[aios-tt] comments: {note}")
|
| 432 |
-
return [], note
|
| 433 |
-
out = [r for r in (normalize_comment(n) for n in rows) if r]
|
| 434 |
-
return out, ""
|
| 435 |
-
|
| 436 |
-
|
| 437 |
-
#: ββ WAVE 30 Β· D-156 β THE MEDIA DATASETS, AS A SET, SO THE HAND-OFF CAN FILTER ON IDENTITY.
|
| 438 |
-
#: `_media_deferrals` uses this to lift ONLY posts/comments snapshots out of the local deferral
|
| 439 |
-
#: list. That is what makes it structurally impossible to file a PROFILE snapshot in the engine's
|
| 440 |
-
#: metric queue β the defect a draft of T10 shipped and A-39 booked as "the wrong fix is worse
|
| 441 |
-
#: than the gap". A membership test cannot be got wrong by a later edit the way `if` order can.
|
| 442 |
-
TT_MEDIA_DATASETS = (TT_DS_POSTS, TT_DS_COMMENTS)
|
| 443 |
-
|
| 444 |
-
|
| 445 |
-
def _media_deferrals(deferred):
|
| 446 |
-
"""The POSTS/COMMENTS entries of a `bd_scrape` deferral list β never the profile's.
|
| 447 |
-
|
| 448 |
-
β The engine, not this module, decides what a deferral MEANS: it stamps `kind` and the
|
| 449 |
-
handle and files it. TikTok needs no `_tag_metric_deferrals` twin because one dataset is one
|
| 450 |
-
kind here, so the id already carries everything a mapper choice depends on β and importing
|
| 451 |
-
Instagram's tagger is not available anyway (W30-T09 gates ZERO `from connectors_ig` lines).
|
| 452 |
-
"""
|
| 453 |
-
out = []
|
| 454 |
-
for d in deferred or []:
|
| 455 |
-
if isinstance(d, dict) and str(d.get("datasetId") or "") in TT_MEDIA_DATASETS:
|
| 456 |
-
out.append(dict(d))
|
| 457 |
-
return out
|
| 458 |
-
|
| 459 |
-
|
| 460 |
-
def pull_profile_tt(url, log=print, pending_profile=None, prefetch=None,
|
| 461 |
-
max_posts=0, post_metrics=False, comment_metrics=False):
|
| 462 |
-
"""ONE TikTok profile from the vendor. Same return contract as `pull_profile`.
|
| 463 |
-
|
| 464 |
-
`{state, profile, posts, comments, via, note}` with `state β ok | partial | blocked | error`,
|
| 465 |
-
so the engine's enrich branch treats every network identically and no caller learns a new
|
| 466 |
-
shape.
|
| 467 |
-
|
| 468 |
-
β WAVE 30 Β· T10 β POSTS AND COMMENTS ARE REAL NOW, AND BOTH DEFAULT OFF, exactly as Instagram's
|
| 469 |
-
do. `post_metrics` scrapes the profile row's own `top_videos` permalinks (see `tt_post_urls` β
|
| 470 |
-
no discovery call, because both TikTok discovery datasets 404 for our key); `comment_metrics`
|
| 471 |
-
then scrapes the comments of the posts that came back. β COMMENTS REQUIRE POSTS by construction
|
| 472 |
-
rather than by a rule: their input IS a post permalink, so asking for comments with post capture
|
| 473 |
-
off is a request with no subject, and it returns none instead of quietly buying posts nobody
|
| 474 |
-
asked for.
|
| 475 |
-
|
| 476 |
-
β `partial` IS THE SUCCESS STATE WHENEVER NO MEDIA WAS READ, and that is deliberate rather than
|
| 477 |
-
pessimistic. The Instagram contract reads `ok` only when identity AND media both landed
|
| 478 |
-
(`pull_profile_bd`: *"identity without media is still partial ... a run that wrote a follower
|
| 479 |
-
count and no posts must not paint green over a posts table that did not grow"*). So: posts not
|
| 480 |
-
ASKED for β `partial`, saying so; posts asked for and landed β `ok`; asked for and none came β
|
| 481 |
-
`partial` with the vendor's reason. The state answers "did this pull deliver what it went for",
|
| 482 |
-
never "did the function finish".
|
| 483 |
-
|
| 484 |
-
β **NO FREE RUNG, AND NO FALLBACK CHAIN.** Instagram's `pull_profile` drops to Apify when the
|
| 485 |
-
paid rung refuses; `providers.DEFAULT_CHAINS["tt_profile"]` is deliberately single-provider,
|
| 486 |
-
with its own note explaining that a multi-provider chain is a promise something walks it and
|
| 487 |
-
that nothing walks Instagram's second name today either. So a refusal here is final, and it
|
| 488 |
-
says so instead of implying a retry somewhere.
|
| 489 |
-
"""
|
| 490 |
-
handle = tt_handle(url)
|
| 491 |
-
if not handle:
|
| 492 |
-
return {"state": "error", "profile": {}, "posts": [], "comments": [], "via": "",
|
| 493 |
-
"note": f"{url!r} is not a TikTok profile URL or handle"}
|
| 494 |
-
|
| 495 |
-
# β THE BATCH FAST PATH, same shape as the Instagram side: `prefetch` is `{handle: node}` from
|
| 496 |
-
# one multi-URL scrape covering a whole selection. A hit is a vendor round trip that does not
|
| 497 |
-
# happen; a miss falls through to the single-URL call below.
|
| 498 |
-
cached = prefetch.get(handle) if isinstance(prefetch, dict) else None
|
| 499 |
-
_deferred = []
|
| 500 |
-
if isinstance(cached, dict) and cached:
|
| 501 |
-
rows, note = [cached], ""
|
| 502 |
-
else:
|
| 503 |
-
rows, note = bd_scrape(TT_DS_PROFILES, [tt_profile_url(handle)], deferred=_deferred)
|
| 504 |
-
|
| 505 |
-
node = rows[0] if rows else {}
|
| 506 |
-
profile = normalize_profile(node, handle) if node else {}
|
| 507 |
-
# β THE READABILITY TEST IS `followers`/`following`, NOT "did we get a dict". `normalize_profile`
|
| 508 |
-
# drops blanks, so an unreadable row still returns `{"platform": β¦, "handle": β¦}` β truthy, and
|
| 509 |
-
# carrying nothing anybody asked for. The Instagram rung tests exactly this pair for exactly
|
| 510 |
-
# this reason, and answering "0 followers" instead is the failure it exists to prevent.
|
| 511 |
-
unreadable = profile.get("followers") is None and profile.get("following") is None
|
| 512 |
-
if note or unreadable:
|
| 513 |
-
# β THE DEFERRAL IS HANDED OVER RATHER THAN DISCARDED. A snapshot the vendor is still
|
| 514 |
-
# building HAS ALREADY BEEN PAID FOR; dropping its id bills again on the next run for the
|
| 515 |
-
# same record. That was live on the Instagram profile path until 2026-08-09 β measured on
|
| 516 |
-
# nurilab as two runs, two fresh snapshots, both abandoned β and it is not being
|
| 517 |
-
# reintroduced here by omission.
|
| 518 |
-
if isinstance(pending_profile, list):
|
| 519 |
-
for d in _deferred:
|
| 520 |
-
pending_profile.append({**d, "kind": "profile", "influencer": handle})
|
| 521 |
-
why = note or ("the scrape answered, but no follower/following counts were readable in it "
|
| 522 |
-
"(the field names may have moved - see tiktok-capture.md)")
|
| 523 |
-
return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
|
| 524 |
-
"deferredProfile": [d.get("snapshotId") for d in _deferred],
|
| 525 |
-
"note": why}
|
| 526 |
-
|
| 527 |
-
# --- W30-T10: THE MEDIA, ONLY WHEN IT WAS ASKED FOR. ------------------------------------
|
| 528 |
-
if not post_metrics:
|
| 529 |
-
return {"state": "partial", "profile": profile, "posts": [], "comments": [],
|
| 530 |
-
"via": "brightdata",
|
| 531 |
-
"note": note or "profile read; post capture is off for this step"}
|
| 532 |
-
urls = tt_post_urls(node, limit=max_posts)
|
| 533 |
-
if not urls:
|
| 534 |
-
# β NOT AN ERROR AND NOT A RETRY. A creator with no `top_videos` has nothing to buy, and
|
| 535 |
-
# saying so is what stops the next run paying to be told the same thing.
|
| 536 |
-
return {"state": "partial", "profile": profile, "posts": [], "comments": [],
|
| 537 |
-
"via": "brightdata",
|
| 538 |
-
"note": note or "profile read; this account's row carried no post links"}
|
| 539 |
-
posts, p_note = pull_posts_tt(urls, log=log, deferred=_deferred)
|
| 540 |
-
comments, c_note = ([], "")
|
| 541 |
-
if comment_metrics and posts:
|
| 542 |
-
# The comments dataset is keyed on a POST permalink, so it reads the posts we just bought β
|
| 543 |
-
# `url` from the mapper, never the profile's raw array, so a post the posts scrape refused
|
| 544 |
-
# is not silently asked about again one rung later.
|
| 545 |
-
comments, c_note = pull_comments_tt([p.get("url") for p in posts if p.get("url")],
|
| 546 |
-
log=log, deferred=_deferred)
|
| 547 |
-
# ββ WAVE 30 Β· D-156 β THE MEDIA DEFERRALS ARE HANDED BACK, and the shape of the hand-off is
|
| 548 |
-
# the whole lesson. An earlier draft of T10 appended every `_deferred` entry to
|
| 549 |
-
# `pending_profile` tagged `kind: "profile"`. By the time control reaches here a PROFILE
|
| 550 |
-
# deferral is impossible β the profile branch above returns `blocked` on any note β so **every
|
| 551 |
-
# id fanned out that way was a POSTS or COMMENTS snapshot in the PROFILE queue**, whose
|
| 552 |
-
# collector writes preset profile cells onto somebody's record from post rows. The engine keeps
|
| 553 |
-
# the two queues apart deliberately (`_pending_profile_tasks` vs `_pending_metric_tasks`).
|
| 554 |
-
# β So this returns them under their OWN key, filtered by dataset identity
|
| 555 |
-
# (`_media_deferrals`), and the engine files them in the metric queue with the handle it
|
| 556 |
-
# already holds. Returning rather than appending also keeps the queue's vocabulary out of a
|
| 557 |
-
# connector: this module knows which CORPUS deferred, never what the engine calls it.
|
| 558 |
-
# β `deferredMedia` rides BOTH returns on purpose. The empty-posts case is the one that
|
| 559 |
-
# matters most β that is exactly the run where the vendor took too long, so a caller reading
|
| 560 |
-
# the ids only from the success path would lose every batch it actually paid for.
|
| 561 |
-
deferred_media = _media_deferrals(_deferred)
|
| 562 |
-
if not posts:
|
| 563 |
-
return {"state": "partial", "profile": profile, "posts": [], "comments": [],
|
| 564 |
-
"via": "brightdata", "deferredMedia": deferred_media,
|
| 565 |
-
"note": p_note or note or "profile read; the post source returned nothing"}
|
| 566 |
-
return {"state": "ok", "profile": profile, "posts": posts, "comments": comments,
|
| 567 |
-
"via": "brightdata", "deferredMedia": deferred_media,
|
| 568 |
-
"note": c_note or note or ""}
|
|
|
|
| 1 |
+
"""connectors_tt.py β the TIKTOK connector (wave 29 Β· item 7 Β· DEBT D-9 Β· rulings R1 + R2).
|
| 2 |
+
|
| 3 |
+
Everything in this file knows what a VENDOR's TikTok row looks like. Nothing in it knows what an
|
| 4 |
+
automation is. That split is `connectors_ig.py`'s (wave 27 item 23) and it is the reason this file
|
| 5 |
+
exists at all rather than another thousand lines inside the engine.
|
| 6 |
+
|
| 7 |
+
β **EVERY VENDOR FIELD NAME HERE WAS PROBED, NOT GUESSED.** The whole schema β 40 profile / 43
|
| 8 |
+
post / 17 comment fields, each with the vendor's own type, description and `pii` flag β was read
|
| 9 |
+
live from `GET /datasets/{id}/metadata` for **$0.00** and written down in
|
| 10 |
+
`.claude/wiki/waves/wave29/proto/tiktok-schema.md` (promoted to `tiktok-capture.md` at
|
| 11 |
+
close-out). That document is the AUTHORITY: do not re-probe it, and do not invent a key. Where a
|
| 12 |
+
name below reads through a candidate list it is because the vendor has two names for one fact
|
| 13 |
+
(`biography`/`signature`, `region`/`country`), never because the name is uncertain.
|
| 14 |
+
|
| 15 |
+
β **NOTHING HERE EVER AUTHENTICATES TO TIKTOK.** No login, no cookie, no account to get banned β
|
| 16 |
+
public data through a supplier, exactly the rail `connectors_ig.py` states for Instagram. The
|
| 17 |
+
vendor key is a key to a SUPPLIER.
|
| 18 |
+
|
| 19 |
+
β **THE TRANSPORT IS `connectors_bd.py` β SHARED, VENDOR-NAMED, AND NO LONGER BORROWED FROM THE
|
| 20 |
+
OTHER PLATFORM'S CONNECTOR** (WAVE 30 Β· T09, DEBT D-128). `bd_call`, `bd_scrape` and
|
| 21 |
+
`bd_filter_start` take the dataset id as a PARAMETER β they are Bright Data's wire, not
|
| 22 |
+
Instagram's β and re-implementing them here would be a second copy of the deferral handling, the
|
| 23 |
+
truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
|
| 24 |
+
Until wave 30 the code was right and the NAME was wrong: this file imported thirteen symbols from
|
| 25 |
+
`connectors_ig`, which read as a dependency on Instagram and was really a dependency on a supplier.
|
| 26 |
+
β **This file now imports ZERO names from `connectors_ig`, and a gate check asserts that**, because
|
| 27 |
+
the sentence above is the kind that quietly stops being true.
|
| 28 |
+
|
| 29 |
+
β **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
|
| 30 |
+
1. the real ROW shape β `/metadata` describes a DATASET, and Instagram's rows carry undeclared
|
| 31 |
+
envelope keys (`timestamp`, `input`) that no metadata call mentions;
|
| 32 |
+
2. that a declared field POPULATES β Bright Data's Instagram Reels *declares* `views: number`
|
| 33 |
+
and delivers an account-grain wrong number (Β§4e). **Declared is not delivered**, and the one
|
| 34 |
+
TikTok claim that matters most (`play_count`) is exactly a declaration.
|
| 35 |
+
"""
|
| 36 |
+
from __future__ import annotations
|
| 37 |
+
|
| 38 |
+
import automation_engine as engine
|
| 39 |
+
# β T09 β FOUR NAMES CAME OFF THIS LIST AND NOTHING BROKE, which is the point of deriving an
|
| 40 |
+
# import block from the AST both ways. `bd_call`, `bd_filter_start`, `bd_key` and `bd_ready` were
|
| 41 |
+
# imported here under a comment claiming they were *"re-exported for the runners"*; no runner ever
|
| 42 |
+
# read them off this module (the engine imports them from the transport itself), so they were four
|
| 43 |
+
# lines of dependency nobody was paying for. `[[artifact-with-no-importer]]` in its smallest form.
|
| 44 |
+
from connectors_bd import (
|
| 45 |
+
_bd_first_url,
|
| 46 |
+
_bd_flag,
|
| 47 |
+
_bd_list,
|
| 48 |
+
_bd_source_payload,
|
| 49 |
+
_first,
|
| 50 |
+
_ig_int,
|
| 51 |
+
bd_scrape,
|
| 52 |
+
)
|
| 53 |
+
|
| 54 |
+
# ---------------------------------------------------------------------------------------------
|
| 55 |
+
# THE DATASETS
|
| 56 |
+
# ---------------------------------------------------------------------------------------------
|
| 57 |
+
# β CATALOGUE PRESENCE IS NOT ENTITLEMENT β the same finding Instagram produced. `GET
|
| 58 |
+
# /datasets/list` returned 1,735 rows of which 12 are TikTok; the three below answer 200 with a
|
| 59 |
+
# full field list, and the two DISCOVERY halves answer **404 for our key**:
|
| 60 |
+
# `gd_lj71gn6l68bz7y9hc` (posts by profile) and `gd_lilwhto81z415d9mdl` (posts by keyword).
|
| 61 |
+
# β TikTok discovery routes through the PROFILES dataset's corpus filter, exactly as Instagram's
|
| 62 |
+
# does. A ticket that reaches for a by-keyword endpoint is reaching for a 404.
|
| 63 |
+
TT_DS_PROFILES = "gd_l1villgoiiidt09ci" # TikTok - Profiles. 40 fields, 152,000,000 records
|
| 64 |
+
TT_DS_POSTS = "gd_lu702nij2f790tmv9h" # TikTok - Posts. 43 fields
|
| 65 |
+
TT_DS_COMMENTS = "gd_lkf2st302ap89utw5k" # TikTok - Comments. 17 fields
|
| 66 |
+
|
| 67 |
+
#: The vendor's two post-type tokens, verbatim from the dataset's own `ai_description`
|
| 68 |
+
#: (*"strictly these two"*, video = 99.5% of rows). Ours are `image`/`video`/`carousel`.
|
| 69 |
+
TT_POST_TYPE_VIDEO = "video"
|
| 70 |
+
TT_POST_TYPE_CONTENT = "content"
|
| 71 |
+
|
| 72 |
+
#: What a TikTok profile URL looks like, for the runner that has a handle and needs a URL. Kept
|
| 73 |
+
#: beside the dataset ids because it is the same class of vendor fact.
|
| 74 |
+
#: β ONE SPELLING. `platform/core/user_tables.profile_url(handle, 'tiktok')` builds the identical
|
| 75 |
+
#: string from `_PROFILE_RULES` (contract C2, E's half) β this exists for the connector's own
|
| 76 |
+
#: batch calls, and the gate asserts the two agree rather than trusting that they do.
|
| 77 |
+
TT_PROFILE_URL = "https://www.tiktok.com/@{handle}"
|
| 78 |
+
|
| 79 |
+
|
| 80 |
+
def tt_profile_url(handle):
|
| 81 |
+
"""`nurilab` β `https://www.tiktok.com/@nurilab`. `''` for a blank handle, never a bare `@`."""
|
| 82 |
+
h = str(handle or "").strip().lstrip("@")
|
| 83 |
+
return TT_PROFILE_URL.format(handle=h) if h else ""
|
| 84 |
+
|
| 85 |
+
|
| 86 |
+
# ---------------------------------------------------------------------------------------------
|
| 87 |
+
# THE FIELD MAPS
|
| 88 |
+
# ---------------------------------------------------------------------------------------------
|
| 89 |
+
# Each function turns ONE vendor row into the cell dict for one of the `ut_tt_*` schemas declared
|
| 90 |
+
# in `automation_engine`. The rules they all obey, stated once:
|
| 91 |
+
#
|
| 92 |
+
# * **BLANK MEANS NOT READ, NEVER "THEY HAVE NONE".** A key the vendor did not send is OMITTED,
|
| 93 |
+
# so a later, richer pull fills it instead of being overwritten by this one's silence. `_first`
|
| 94 |
+
# returns `None` (never 0) when nothing matches, which is what makes that possible.
|
| 95 |
+
# * **A zero from the vendor is a MEASUREMENT and survives.** (Instagram's `_ig_zero_is_blank`
|
| 96 |
+
# rule is scoped to a paid rung whose zeros were proven fictional; nothing here has earned it.)
|
| 97 |
+
# * **Every unpromoted vendor key stays whole in `source_payload`.** A schema addition on the
|
| 98 |
+
# vendor's side is preserved rather than silently discarded while our column model catches up.
|
| 99 |
+
# * **Nothing here writes a session token.** `tt_chain_token`, `secu_id` (~85% null), `short_id`
|
| 100 |
+
# (100% null in the sample), `ftc` (100% null) and `relation` are deliberately unmapped; they
|
| 101 |
+
# ride in `source_payload` where they make no claim.
|
| 102 |
+
|
| 103 |
+
|
| 104 |
+
def _tt_str(node, *names):
|
| 105 |
+
"""The first non-empty string among `names`, or None when the vendor sent nothing.
|
| 106 |
+
|
| 107 |
+
β `None`, NOT `""`. The callers below drop `None` keys, which is what keeps a blank honest β
|
| 108 |
+
an empty string written into a cell claims "we looked and it is empty".
|
| 109 |
+
"""
|
| 110 |
+
v = _first(node, *names)
|
| 111 |
+
if v is None:
|
| 112 |
+
return None
|
| 113 |
+
s = str(v).strip()
|
| 114 |
+
return s or None
|
| 115 |
+
|
| 116 |
+
|
| 117 |
+
def _tt_pct(node, *names):
|
| 118 |
+
"""A vendor 0β1 engagement fraction β our stored 0β100 percentage, or None.
|
| 119 |
+
|
| 120 |
+
β THE Γ100 IS NOT COSMETIC (wave 26, amendment C1-a). Our `pct` renderer appends the sign to
|
| 121 |
+
the STORED number, so writing the vendor's raw 0.0656 would print a 6.6% creator as `0.0%` β
|
| 122 |
+
measured on the Instagram side, and TikTok sends the same shape on all three of its rates.
|
| 123 |
+
"""
|
| 124 |
+
v = _first(node, *names)
|
| 125 |
+
if v is None:
|
| 126 |
+
return None
|
| 127 |
+
out = engine._pct100(v)
|
| 128 |
+
return out or None
|
| 129 |
+
|
| 130 |
+
|
| 131 |
+
def _tt_day(node, *names):
|
| 132 |
+
"""A vendor stamp β `YYYY-MM-DD`, or None. Our `date` columns store a day."""
|
| 133 |
+
v = _first(node, *names)
|
| 134 |
+
if v is None:
|
| 135 |
+
return None
|
| 136 |
+
return engine._day(v) or None
|
| 137 |
+
|
| 138 |
+
|
| 139 |
+
def _drop_blanks(row):
|
| 140 |
+
"""The one place a mapped row loses its `None`s β see the BLANK MEANS NOT READ rule above."""
|
| 141 |
+
return {k: v for k, v in row.items() if v is not None and v != ""}
|
| 142 |
+
|
| 143 |
+
|
| 144 |
+
def normalize_profile(node, handle=""):
|
| 145 |
+
"""A TikTok Profiles row β the `ut_tt_profile` / `ut_tt_snapshots` cell shape.
|
| 146 |
+
|
| 147 |
+
β TWO FIELDS READ THROUGH A CANDIDATE PAIR, and both pairs are the vendor's, not a guess:
|
| 148 |
+
* `biography` is PRIMARY and `signature` the FALLBACK β the probe measured `signature`
|
| 149 |
+
populated on 85% of rows and they carry the same text;
|
| 150 |
+
* `region` is PRIMARY and `country` the FALLBACK β `region` is the one with a documented
|
| 151 |
+
two-letter-ISO description, `country` has no description at all.
|
| 152 |
+
β `videos_count` is mapped to `posts_count` with a caveat recorded rather than hidden: its
|
| 153 |
+
`ai_description` ranges 1-89, so it may be a WINDOW rather than a lifetime total. It is the
|
| 154 |
+
only count of its kind the dataset offers.
|
| 155 |
+
"""
|
| 156 |
+
node = node if isinstance(node, dict) else {}
|
| 157 |
+
account = _tt_str(node, "account_id") or str(handle or "").strip().lstrip("@")
|
| 158 |
+
return _drop_blanks({
|
| 159 |
+
"platform": engine.PLATFORM_TIKTOK,
|
| 160 |
+
"handle": account,
|
| 161 |
+
"full_name": _tt_str(node, "nickname"),
|
| 162 |
+
"tt_id": _tt_str(node, "id"),
|
| 163 |
+
"profile_url": _tt_str(node, "url") or (tt_profile_url(account) or None),
|
| 164 |
+
"bio": _tt_str(node, "biography", "signature"),
|
| 165 |
+
"external_url": _bd_first_url(_first(node, "bio_link")),
|
| 166 |
+
"verified": _bd_flag(node, "is_verified"),
|
| 167 |
+
"is_private": _bd_flag(node, "is_private"),
|
| 168 |
+
# β APPROXIMATE, and the word is the vendor's: `is_commerce_user` has *"many null values"*
|
| 169 |
+
# on their own description. It is the closest thing TikTok has to Instagram's
|
| 170 |
+
# `is_business_account`, and `_bd_flag` writes nothing at all when the key is absent β so
|
| 171 |
+
# the approximation only ever fills a cell the vendor actually answered.
|
| 172 |
+
"is_business": _bd_flag(node, "is_commerce_user"),
|
| 173 |
+
"followers": _ig_int(_first(node, "followers")),
|
| 174 |
+
"following": _ig_int(_first(node, "following")),
|
| 175 |
+
"posts_count": _ig_int(_first(node, "videos_count")),
|
| 176 |
+
# β `likes` on a PROFILE row is likes RECEIVED across the account's videos (18-110,200, no
|
| 177 |
+
# nulls). It is not a post-level number and it is not our `likes` column, which is why it
|
| 178 |
+
# is stored under a different name.
|
| 179 |
+
"likes_received": _ig_int(_first(node, "likes")),
|
| 180 |
+
"avg_engagement": _tt_pct(node, "awg_engagement_rate"),
|
| 181 |
+
"like_engagement": _tt_pct(node, "like_engagement_rate"),
|
| 182 |
+
"comment_engagement": _tt_pct(node, "comment_engagement_rate"),
|
| 183 |
+
"country_code": _tt_str(node, "region", "country"),
|
| 184 |
+
"region": _tt_str(node, "region"),
|
| 185 |
+
"predicted_lang": _tt_str(node, "predicted_lang"),
|
| 186 |
+
# β ACCOUNT AGE, NOT A MEASUREMENT STAMP β `create_time` on a profile is when the ACCOUNT
|
| 187 |
+
# was made. TikTok stamps nothing with "when this number was true", exactly like Instagram,
|
| 188 |
+
# which is why the append law dates a snapshot by when WE read it.
|
| 189 |
+
"account_created_at": _tt_day(node, "create_time"),
|
| 190 |
+
"source_payload": _bd_source_payload(node),
|
| 191 |
+
})
|
| 192 |
+
|
| 193 |
+
|
| 194 |
+
def tt_post_type(node):
|
| 195 |
+
"""A TikTok post row β one of OUR three type options, or None.
|
| 196 |
+
|
| 197 |
+
β THE FIRST OF THE PROBE DOC'S TWO NAMED BLOCKERS. The vendor's vocabulary is `"video"` /
|
| 198 |
+
`"content"`; ours is `image` / `video` / `carousel` and has no `"content"`. Writing the
|
| 199 |
+
vendor's token would fail `_clean_field`'s option check on the way in and would put an
|
| 200 |
+
untranslated API word in front of a user on the way out.
|
| 201 |
+
|
| 202 |
+
So: `video` is `video`, and `content` β TikTok's photo-mode post β is `image`, EXCEPT when the
|
| 203 |
+
row carries more than one `carousel_images` entry, which is what a carousel IS on either
|
| 204 |
+
network. β The multi-image branch is decided from the IMAGES, never from the type token: the
|
| 205 |
+
token cannot express it, so inferring `carousel` from the word would be inventing a fact.
|
| 206 |
+
β An UNKNOWN token returns None rather than defaulting to `video` (99.5% of rows are video, and
|
| 207 |
+
that is exactly what would make the wrong default invisible).
|
| 208 |
+
"""
|
| 209 |
+
raw = str((node or {}).get("post_type") or "").strip().lower()
|
| 210 |
+
if raw == TT_POST_TYPE_VIDEO:
|
| 211 |
+
return "video"
|
| 212 |
+
if raw != TT_POST_TYPE_CONTENT:
|
| 213 |
+
return None
|
| 214 |
+
images = (node or {}).get("carousel_images")
|
| 215 |
+
return "carousel" if isinstance(images, list) and len(images) > 1 else "image"
|
| 216 |
+
|
| 217 |
+
|
| 218 |
+
def normalize_post(node):
|
| 219 |
+
"""A TikTok Posts row β the `ut_tt_posts` cell shape. None when it carries no identity.
|
| 220 |
+
|
| 221 |
+
β THE SECOND NAMED BLOCKER, RESOLVED HERE AND NOWHERE ELSE: `play_count` is ONE number and
|
| 222 |
+
Instagram's schema has TWO columns for it (`plays` and `views`). On TikTok they are the same
|
| 223 |
+
fact β `play_count` IS the count TikTok displays under a video β so it maps to `views` and
|
| 224 |
+
`ut_tt_posts` HAS NO `plays` COLUMN. Copying one vendor number into two of our columns would
|
| 225 |
+
manufacture a second measurement that a rollup could average or double-count, which is a worse
|
| 226 |
+
outcome than the missing column it would paper over.
|
| 227 |
+
|
| 228 |
+
β `shortcode` reads `shortcode` then `post_id`: both are 19-digit numerics on this dataset and
|
| 229 |
+
the probe measured them as the same shape. That equality is what lets the commentsβposts link
|
| 230 |
+
join with NO normaliser, which the Instagram side never had.
|
| 231 |
+
β `num_share_count` (a number) is preferred over `share_count` (typed TEXT by the vendor).
|
| 232 |
+
β `commerce_info` is a business/commerce LOCATION per its own description β cities and
|
| 233 |
+
countries. It is NOT a paid-partnership flag, and nothing in this dataset is: TikTok declares
|
| 234 |
+
no equivalent, so `paid_partnership`/`partner` have no column on this family at all.
|
| 235 |
+
"""
|
| 236 |
+
node = node if isinstance(node, dict) else {}
|
| 237 |
+
shortcode = _tt_str(node, "shortcode", "post_id")
|
| 238 |
+
if not shortcode:
|
| 239 |
+
return None
|
| 240 |
+
return _drop_blanks({
|
| 241 |
+
"platform": engine.PLATFORM_TIKTOK,
|
| 242 |
+
"shortcode": shortcode,
|
| 243 |
+
# ββ `account_id`, NOT `profile_username` β MEASURED on a real Posts row 2026-08-12.
|
| 244 |
+
# The vendor's `profile_username` is the DISPLAY NAME (`"Dina"`), while `account_id` is the
|
| 245 |
+
# @handle (`"d1na_th"`) β the same field `normalize_profile` already reads for `handle`, so
|
| 246 |
+
# one name means one thing across both corpora. Reading the display name silently broke the
|
| 247 |
+
# only join this table has: `ut_tt_posts.influencer_key` -> `ut_tt_profile.handle` matched
|
| 248 |
+
# NOTHING, so a person could not filter posts by creator and a rollup would count zero.
|
| 249 |
+
# β NO FALLBACK TO `profile_username`, deliberately. It is not a degraded handle, it is a
|
| 250 |
+
# different fact, and filling a join key with it is worse than leaving it blank β a blank
|
| 251 |
+
# is visibly missing, a display name looks like an answer [[one-question-two-normalizers]].
|
| 252 |
+
# The URL is the honest second source: it carries the handle by construction.
|
| 253 |
+
"influencer_key": (_tt_str(node, "account_id")
|
| 254 |
+
or tt_handle(_tt_str(node, "profile_url", "url") or "") or None),
|
| 255 |
+
"posted_at": _tt_day(node, "create_time"),
|
| 256 |
+
"type": tt_post_type(node),
|
| 257 |
+
"caption": _tt_str(node, "description"),
|
| 258 |
+
"url": _tt_str(node, "url"),
|
| 259 |
+
"hashtags": _bd_list(node, "hashtags"),
|
| 260 |
+
"tagged_location": _tt_str(node, "commerce_info"),
|
| 261 |
+
"views": _ig_int(_first(node, "play_count")),
|
| 262 |
+
"likes": _ig_int(_first(node, "digg_count")),
|
| 263 |
+
"comments": _ig_int(_first(node, "comment_count")),
|
| 264 |
+
"shares": _ig_int(_first(node, "num_share_count")),
|
| 265 |
+
"saves": _ig_int(_first(node, "collect_count")),
|
| 266 |
+
"video_duration": _ig_int(_first(node, "video_duration")),
|
| 267 |
+
"source_payload": _bd_source_payload(node),
|
| 268 |
+
})
|
| 269 |
+
|
| 270 |
+
|
| 271 |
+
def normalize_comment(node):
|
| 272 |
+
"""A TikTok Comments row β the `ut_tt_comments` cell shape. None without a comment id.
|
| 273 |
+
|
| 274 |
+
β THE NAME COLLISION, RESOLVED: TikTok's `replies` is an ARRAY of reply objects and OUR
|
| 275 |
+
`replies` column is an INT count. The count comes from `num_replies`; the array stays whole in
|
| 276 |
+
`source_payload`. Reading the array's length instead would be a second, disagreeing answer to
|
| 277 |
+
a question the vendor already answers β and it would disagree, because a page of replies is not
|
| 278 |
+
all of them.
|
| 279 |
+
β `date_created` is typed `date` by this vendor, unlike Instagram's `comment_date` which is
|
| 280 |
+
text and needs defensive parsing. It still goes through `_tt_day` β one date path, so a vendor
|
| 281 |
+
that changes its mind cannot change ours.
|
| 282 |
+
β The comment TEXT and every identifiable commenter field (`commenter_user_name` is flagged
|
| 283 |
+
PII) stay in `source_payload` and are promoted to no column, which is the same posture the
|
| 284 |
+
Instagram comment schema takes for the same D-24 reason.
|
| 285 |
+
"""
|
| 286 |
+
node = node if isinstance(node, dict) else {}
|
| 287 |
+
comment_key = _tt_str(node, "comment_id")
|
| 288 |
+
if not comment_key:
|
| 289 |
+
return None
|
| 290 |
+
return _drop_blanks({
|
| 291 |
+
"platform": engine.PLATFORM_TIKTOK,
|
| 292 |
+
"comment_key": comment_key,
|
| 293 |
+
"shortcode": _tt_str(node, "post_id"),
|
| 294 |
+
# ββ OWNER RULING 2026-08-12: the comment's CONTENT gets a column. `comment_text` is the
|
| 295 |
+
# vendor's own key and `comment_text_only` its stripped variant (the probe recorded both);
|
| 296 |
+
# primary first, so a row carrying the rich form is not silently served the plain one.
|
| 297 |
+
# β The commenter's identity is deliberately NOT promoted β see `TT_COMMENT_FIELDS`.
|
| 298 |
+
"text": _tt_str(node, "comment_text", "comment_text_only"),
|
| 299 |
+
"commented_at": _tt_day(node, "date_created"),
|
| 300 |
+
"likes": _ig_int(_first(node, "num_likes")),
|
| 301 |
+
"replies": _ig_int(_first(node, "num_replies")),
|
| 302 |
+
"source_payload": _bd_source_payload(node),
|
| 303 |
+
})
|
| 304 |
+
|
| 305 |
+
|
| 306 |
+
#: β The three maps, addressable by name β so a gate (and the runners in T04-T06) can walk them
|
| 307 |
+
#: rather than naming three functions, and so adding a fourth dataset is one entry.
|
| 308 |
+
TT_NORMALIZERS = {
|
| 309 |
+
"tt_profile": normalize_profile,
|
| 310 |
+
"tt_post_metrics": normalize_post,
|
| 311 |
+
"tt_comments": normalize_comment,
|
| 312 |
+
}
|
| 313 |
+
|
| 314 |
+
|
| 315 |
+
# ---------------------------------------------------------------------------------------------
|
| 316 |
+
# THE FETCH β wave 30 Β· W30-T08 (carrying wave-29's dropped T05)
|
| 317 |
+
# ---------------------------------------------------------------------------------------------
|
| 318 |
+
|
| 319 |
+
def tt_handle(url):
|
| 320 |
+
"""A TikTok profile URL **or** a bare handle β the handle. `''` when it is neither.
|
| 321 |
+
|
| 322 |
+
Deliberately permissive about the input and strict about the output, because the two callers
|
| 323 |
+
hand it different things: an automation stores whatever a person typed in the profile column
|
| 324 |
+
(`@nurilab`, `nurilab`, or the full URL), while the discovery runner already holds a clean
|
| 325 |
+
`account_id`. One normaliser, so a row found by discovery and a row typed by hand cannot
|
| 326 |
+
resolve to two different handles.
|
| 327 |
+
"""
|
| 328 |
+
s = str(url or "").strip()
|
| 329 |
+
if not s:
|
| 330 |
+
return ""
|
| 331 |
+
if "tiktok.com" in s.lower():
|
| 332 |
+
# Everything after the first `@`, up to the next path segment or query.
|
| 333 |
+
tail = s.split("@", 1)[1] if "@" in s else ""
|
| 334 |
+
s = tail.split("/")[0].split("?")[0].split("#")[0]
|
| 335 |
+
s = s.strip().lstrip("@").strip()
|
| 336 |
+
# A handle is the vendor's `account_id` shape: alphanumerics, dots and underscores.
|
| 337 |
+
return s if s and all(c.isalnum() or c in "._" for c in s) else ""
|
| 338 |
+
|
| 339 |
+
|
| 340 |
+
def tt_post_urls(node, limit=0):
|
| 341 |
+
"""β WAVE 30 Β· T10 β the profile row's own post permalinks, newest-first as the vendor sends.
|
| 342 |
+
|
| 343 |
+
β THIS IS WHY TIKTOK POST CAPTURE COSTS NO EXTRA DISCOVERY. `top_videos` rides the PROFILE row
|
| 344 |
+
we have already bought, so the posts read is a scrape of links we hold, never a search for them.
|
| 345 |
+
The two TikTok DISCOVERY datasets (posts-by-profile, posts-by-keyword) are **404 for our key**,
|
| 346 |
+
so a design that reached for either would not merely be dearer, it would not work.
|
| 347 |
+
|
| 348 |
+
ββ CORRECTED 2026-08-12 β THIS DOCSTRING USED TO SAY *"the probe MEASURED `top_videos` as an
|
| 349 |
+
array of video permalinks, NO empties"*, AND THAT SENTENCE IS WHAT SHIPPED THE BUG. The probe
|
| 350 |
+
read `/datasets/{id}/metadata` β a DATASET description β and the phrase quoted was the field's
|
| 351 |
+
`ai_description`, not an observation of a row. The real row sends **dicts keyed `video_url`**
|
| 352 |
+
(measured below), so the reader built against the quoted sentence found nothing, forever, in
|
| 353 |
+
silence. β The transferable half: *"the probe measured X"* and *"the probe read a declaration
|
| 354 |
+
of X"* are different claims, and prose cannot be told apart by a reader downstream β which is
|
| 355 |
+
why the correction names the method, not just the value.
|
| 356 |
+
|
| 357 |
+
β `top_posts_data` is deliberately NOT read: the probe calls it *"a thin dup of `top_videos`"*,
|
| 358 |
+
and preferring whichever happened to be longer is how one creator's window silently differs
|
| 359 |
+
from another's.
|
| 360 |
+
β `limit <= 0` means "everything the row carried". The CAP IS THE CALLER'S β `config.maxPosts`,
|
| 361 |
+
validated 1..12 β and it is applied here rather than after the scrape so an unwanted post is
|
| 362 |
+
never bought. [[a-constant-two-features-share]]: the 12 is the vendor's measured profile window,
|
| 363 |
+
not a number this function may invent.
|
| 364 |
+
"""
|
| 365 |
+
raw = (node or {}).get("top_videos")
|
| 366 |
+
out = []
|
| 367 |
+
for item in raw if isinstance(raw, list) else []:
|
| 368 |
+
# ββ MEASURED ON A REAL ROW 2026-08-12, AND IT IS NOT WHAT THE SCHEMA SAID.
|
| 369 |
+
# `top_videos` is NOT an array of permalink strings. One paid TikTok Profiles scrape of a
|
| 370 |
+
# live handle returns **19 DICTS**, keyed
|
| 371 |
+
# `video_url Β· video_id Β· playcount Β· diggcount Β· commentcount Β· share_count Β·
|
| 372 |
+
# favorites_count Β· create_date Β· cover_image`.
|
| 373 |
+
# The docstring above cites the $0 probe as having "measured" permalinks β it had not, and
|
| 374 |
+
# could not: `/datasets/{id}/metadata` describes a DATASET, and the probe's own verdict says
|
| 375 |
+
# so in terms (*"what $0 cannot buy β¦ the real ROW shape β¦ that a declared field
|
| 376 |
+
# POPULATES"*, `wave29/proto/tiktok-schema.md`). This is the SECOND time this vendor's
|
| 377 |
+
# declaration has diverged from its delivery on this exact axis; BD's IG Reels `views` was
|
| 378 |
+
# the first. [[reachable-is-not-the-same-as-built]]
|
| 379 |
+
# β The consequence, live: `TT_DS_POSTS` was never reached, because this returned an EMPTY
|
| 380 |
+
# list on every real profile β post capture could not have worked for anybody, and the
|
| 381 |
+
# T10 gate stayed green because its canned fixture encoded the DECLARED shape. A fixture
|
| 382 |
+
# written from a schema tests the schema.
|
| 383 |
+
# β `video_url` is FIRST because it is the key the vendor actually sends; `url` is kept
|
| 384 |
+
# because it costs nothing and is what a future corpus revision would most likely use. The
|
| 385 |
+
# bare-string branch stays for the same reason β this widens what is ACCEPTED and invents
|
| 386 |
+
# nothing: a shape that yields no `httpβ¦` value still degrades to "no posts", exactly as
|
| 387 |
+
# before, rather than to a URL built out of a guess.
|
| 388 |
+
# β `top_posts_data` is STILL not read (it carries `post_url` and would work): preferring
|
| 389 |
+
# whichever array happened to be longer is how one creator's window silently differs from
|
| 390 |
+
# another's, and that reasoning is unchanged by this correction.
|
| 391 |
+
if isinstance(item, dict):
|
| 392 |
+
u = str(item.get("video_url") or item.get("url") or "").strip()
|
| 393 |
+
else:
|
| 394 |
+
u = str(item or "").strip()
|
| 395 |
+
if u.lower().startswith("http") and u not in out:
|
| 396 |
+
out.append(u)
|
| 397 |
+
return out[:limit] if limit and limit > 0 else out
|
| 398 |
+
|
| 399 |
+
|
| 400 |
+
def pull_posts_tt(post_urls, log=print, deferred=None):
|
| 401 |
+
"""The TikTok Posts dataset for a list of permalinks β `(rows, note)`, already normalised.
|
| 402 |
+
|
| 403 |
+
β ONE CALL FOR THE WHOLE WINDOW. `bd_scrape` has always taken a list, and the Instagram side
|
| 404 |
+
measured what happens when a caller forgets: 25 records, one billed snapshot each, a walk still
|
| 405 |
+
running at 67 minutes. Nothing here loops per URL.
|
| 406 |
+
"""
|
| 407 |
+
urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
|
| 408 |
+
if not urls:
|
| 409 |
+
return [], ""
|
| 410 |
+
rows, note = bd_scrape(TT_DS_POSTS, urls, deferred=deferred)
|
| 411 |
+
if note:
|
| 412 |
+
log(f"[aios-tt] posts: {note}")
|
| 413 |
+
return [], note
|
| 414 |
+
out = [r for r in (normalize_post(n) for n in rows) if r]
|
| 415 |
+
return out, ""
|
| 416 |
+
|
| 417 |
+
|
| 418 |
+
def pull_comments_tt(post_urls, log=print, deferred=None):
|
| 419 |
+
"""The TikTok Comments dataset for a list of POST permalinks β `(rows, note)`, normalised.
|
| 420 |
+
|
| 421 |
+
β THE MOST EXPENSIVE THING THIS PRODUCT BUYS, and the reason `commentMetrics` defaults OFF on
|
| 422 |
+
both networks: a comments scrape ingests identifiable third parties who never entered anybody's
|
| 423 |
+
list (D-24). The mapper already keeps every commenter field in `source_payload` and promotes
|
| 424 |
+
none of them to a column; this function adds no new exposure, it just has to be asked for.
|
| 425 |
+
"""
|
| 426 |
+
urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
|
| 427 |
+
if not urls:
|
| 428 |
+
return [], ""
|
| 429 |
+
rows, note = bd_scrape(TT_DS_COMMENTS, urls, deferred=deferred)
|
| 430 |
+
if note:
|
| 431 |
+
log(f"[aios-tt] comments: {note}")
|
| 432 |
+
return [], note
|
| 433 |
+
out = [r for r in (normalize_comment(n) for n in rows) if r]
|
| 434 |
+
return out, ""
|
| 435 |
+
|
| 436 |
+
|
| 437 |
+
#: ββ WAVE 30 Β· D-156 β THE MEDIA DATASETS, AS A SET, SO THE HAND-OFF CAN FILTER ON IDENTITY.
|
| 438 |
+
#: `_media_deferrals` uses this to lift ONLY posts/comments snapshots out of the local deferral
|
| 439 |
+
#: list. That is what makes it structurally impossible to file a PROFILE snapshot in the engine's
|
| 440 |
+
#: metric queue β the defect a draft of T10 shipped and A-39 booked as "the wrong fix is worse
|
| 441 |
+
#: than the gap". A membership test cannot be got wrong by a later edit the way `if` order can.
|
| 442 |
+
TT_MEDIA_DATASETS = (TT_DS_POSTS, TT_DS_COMMENTS)
|
| 443 |
+
|
| 444 |
+
|
| 445 |
+
def _media_deferrals(deferred):
|
| 446 |
+
"""The POSTS/COMMENTS entries of a `bd_scrape` deferral list β never the profile's.
|
| 447 |
+
|
| 448 |
+
β The engine, not this module, decides what a deferral MEANS: it stamps `kind` and the
|
| 449 |
+
handle and files it. TikTok needs no `_tag_metric_deferrals` twin because one dataset is one
|
| 450 |
+
kind here, so the id already carries everything a mapper choice depends on β and importing
|
| 451 |
+
Instagram's tagger is not available anyway (W30-T09 gates ZERO `from connectors_ig` lines).
|
| 452 |
+
"""
|
| 453 |
+
out = []
|
| 454 |
+
for d in deferred or []:
|
| 455 |
+
if isinstance(d, dict) and str(d.get("datasetId") or "") in TT_MEDIA_DATASETS:
|
| 456 |
+
out.append(dict(d))
|
| 457 |
+
return out
|
| 458 |
+
|
| 459 |
+
|
| 460 |
+
def pull_profile_tt(url, log=print, pending_profile=None, prefetch=None,
|
| 461 |
+
max_posts=0, post_metrics=False, comment_metrics=False):
|
| 462 |
+
"""ONE TikTok profile from the vendor. Same return contract as `pull_profile`.
|
| 463 |
+
|
| 464 |
+
`{state, profile, posts, comments, via, note}` with `state β ok | partial | blocked | error`,
|
| 465 |
+
so the engine's enrich branch treats every network identically and no caller learns a new
|
| 466 |
+
shape.
|
| 467 |
+
|
| 468 |
+
β WAVE 30 Β· T10 β POSTS AND COMMENTS ARE REAL NOW, AND BOTH DEFAULT OFF, exactly as Instagram's
|
| 469 |
+
do. `post_metrics` scrapes the profile row's own `top_videos` permalinks (see `tt_post_urls` β
|
| 470 |
+
no discovery call, because both TikTok discovery datasets 404 for our key); `comment_metrics`
|
| 471 |
+
then scrapes the comments of the posts that came back. β COMMENTS REQUIRE POSTS by construction
|
| 472 |
+
rather than by a rule: their input IS a post permalink, so asking for comments with post capture
|
| 473 |
+
off is a request with no subject, and it returns none instead of quietly buying posts nobody
|
| 474 |
+
asked for.
|
| 475 |
+
|
| 476 |
+
β `partial` IS THE SUCCESS STATE WHENEVER NO MEDIA WAS READ, and that is deliberate rather than
|
| 477 |
+
pessimistic. The Instagram contract reads `ok` only when identity AND media both landed
|
| 478 |
+
(`pull_profile_bd`: *"identity without media is still partial ... a run that wrote a follower
|
| 479 |
+
count and no posts must not paint green over a posts table that did not grow"*). So: posts not
|
| 480 |
+
ASKED for β `partial`, saying so; posts asked for and landed β `ok`; asked for and none came β
|
| 481 |
+
`partial` with the vendor's reason. The state answers "did this pull deliver what it went for",
|
| 482 |
+
never "did the function finish".
|
| 483 |
+
|
| 484 |
+
β **NO FREE RUNG, AND NO FALLBACK CHAIN.** Instagram's `pull_profile` drops to Apify when the
|
| 485 |
+
paid rung refuses; `providers.DEFAULT_CHAINS["tt_profile"]` is deliberately single-provider,
|
| 486 |
+
with its own note explaining that a multi-provider chain is a promise something walks it and
|
| 487 |
+
that nothing walks Instagram's second name today either. So a refusal here is final, and it
|
| 488 |
+
says so instead of implying a retry somewhere.
|
| 489 |
+
"""
|
| 490 |
+
handle = tt_handle(url)
|
| 491 |
+
if not handle:
|
| 492 |
+
return {"state": "error", "profile": {}, "posts": [], "comments": [], "via": "",
|
| 493 |
+
"note": f"{url!r} is not a TikTok profile URL or handle"}
|
| 494 |
+
|
| 495 |
+
# β THE BATCH FAST PATH, same shape as the Instagram side: `prefetch` is `{handle: node}` from
|
| 496 |
+
# one multi-URL scrape covering a whole selection. A hit is a vendor round trip that does not
|
| 497 |
+
# happen; a miss falls through to the single-URL call below.
|
| 498 |
+
cached = prefetch.get(handle) if isinstance(prefetch, dict) else None
|
| 499 |
+
_deferred = []
|
| 500 |
+
if isinstance(cached, dict) and cached:
|
| 501 |
+
rows, note = [cached], ""
|
| 502 |
+
else:
|
| 503 |
+
rows, note = bd_scrape(TT_DS_PROFILES, [tt_profile_url(handle)], deferred=_deferred)
|
| 504 |
+
|
| 505 |
+
node = rows[0] if rows else {}
|
| 506 |
+
profile = normalize_profile(node, handle) if node else {}
|
| 507 |
+
# β THE READABILITY TEST IS `followers`/`following`, NOT "did we get a dict". `normalize_profile`
|
| 508 |
+
# drops blanks, so an unreadable row still returns `{"platform": β¦, "handle": β¦}` β truthy, and
|
| 509 |
+
# carrying nothing anybody asked for. The Instagram rung tests exactly this pair for exactly
|
| 510 |
+
# this reason, and answering "0 followers" instead is the failure it exists to prevent.
|
| 511 |
+
unreadable = profile.get("followers") is None and profile.get("following") is None
|
| 512 |
+
if note or unreadable:
|
| 513 |
+
# β THE DEFERRAL IS HANDED OVER RATHER THAN DISCARDED. A snapshot the vendor is still
|
| 514 |
+
# building HAS ALREADY BEEN PAID FOR; dropping its id bills again on the next run for the
|
| 515 |
+
# same record. That was live on the Instagram profile path until 2026-08-09 β measured on
|
| 516 |
+
# nurilab as two runs, two fresh snapshots, both abandoned β and it is not being
|
| 517 |
+
# reintroduced here by omission.
|
| 518 |
+
if isinstance(pending_profile, list):
|
| 519 |
+
for d in _deferred:
|
| 520 |
+
pending_profile.append({**d, "kind": "profile", "influencer": handle})
|
| 521 |
+
why = note or ("the scrape answered, but no follower/following counts were readable in it "
|
| 522 |
+
"(the field names may have moved - see tiktok-capture.md)")
|
| 523 |
+
return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
|
| 524 |
+
"deferredProfile": [d.get("snapshotId") for d in _deferred],
|
| 525 |
+
"note": why}
|
| 526 |
+
|
| 527 |
+
# --- W30-T10: THE MEDIA, ONLY WHEN IT WAS ASKED FOR. ------------------------------------
|
| 528 |
+
if not post_metrics:
|
| 529 |
+
return {"state": "partial", "profile": profile, "posts": [], "comments": [],
|
| 530 |
+
"via": "brightdata",
|
| 531 |
+
"note": note or "profile read; post capture is off for this step"}
|
| 532 |
+
urls = tt_post_urls(node, limit=max_posts)
|
| 533 |
+
if not urls:
|
| 534 |
+
# β NOT AN ERROR AND NOT A RETRY. A creator with no `top_videos` has nothing to buy, and
|
| 535 |
+
# saying so is what stops the next run paying to be told the same thing.
|
| 536 |
+
return {"state": "partial", "profile": profile, "posts": [], "comments": [],
|
| 537 |
+
"via": "brightdata",
|
| 538 |
+
"note": note or "profile read; this account's row carried no post links"}
|
| 539 |
+
posts, p_note = pull_posts_tt(urls, log=log, deferred=_deferred)
|
| 540 |
+
comments, c_note = ([], "")
|
| 541 |
+
if comment_metrics and posts:
|
| 542 |
+
# The comments dataset is keyed on a POST permalink, so it reads the posts we just bought β
|
| 543 |
+
# `url` from the mapper, never the profile's raw array, so a post the posts scrape refused
|
| 544 |
+
# is not silently asked about again one rung later.
|
| 545 |
+
comments, c_note = pull_comments_tt([p.get("url") for p in posts if p.get("url")],
|
| 546 |
+
log=log, deferred=_deferred)
|
| 547 |
+
# ββ WAVE 30 Β· D-156 β THE MEDIA DEFERRALS ARE HANDED BACK, and the shape of the hand-off is
|
| 548 |
+
# the whole lesson. An earlier draft of T10 appended every `_deferred` entry to
|
| 549 |
+
# `pending_profile` tagged `kind: "profile"`. By the time control reaches here a PROFILE
|
| 550 |
+
# deferral is impossible β the profile branch above returns `blocked` on any note β so **every
|
| 551 |
+
# id fanned out that way was a POSTS or COMMENTS snapshot in the PROFILE queue**, whose
|
| 552 |
+
# collector writes preset profile cells onto somebody's record from post rows. The engine keeps
|
| 553 |
+
# the two queues apart deliberately (`_pending_profile_tasks` vs `_pending_metric_tasks`).
|
| 554 |
+
# β So this returns them under their OWN key, filtered by dataset identity
|
| 555 |
+
# (`_media_deferrals`), and the engine files them in the metric queue with the handle it
|
| 556 |
+
# already holds. Returning rather than appending also keeps the queue's vocabulary out of a
|
| 557 |
+
# connector: this module knows which CORPUS deferred, never what the engine calls it.
|
| 558 |
+
# β `deferredMedia` rides BOTH returns on purpose. The empty-posts case is the one that
|
| 559 |
+
# matters most β that is exactly the run where the vendor took too long, so a caller reading
|
| 560 |
+
# the ids only from the success path would lose every batch it actually paid for.
|
| 561 |
+
deferred_media = _media_deferrals(_deferred)
|
| 562 |
+
if not posts:
|
| 563 |
+
return {"state": "partial", "profile": profile, "posts": [], "comments": [],
|
| 564 |
+
"via": "brightdata", "deferredMedia": deferred_media,
|
| 565 |
+
"note": p_note or note or "profile read; the post source returned nothing"}
|
| 566 |
+
return {"state": "ok", "profile": profile, "posts": posts, "comments": comments,
|
| 567 |
+
"via": "brightdata", "deferredMedia": deferred_media,
|
| 568 |
+
"note": c_note or note or ""}
|
api/providers.py
CHANGED
|
The diff for this file is too large to render.
See raw diff
|
|
|
api/routes_agent_harness.py
CHANGED
|
@@ -1,455 +1,455 @@
|
|
| 1 |
-
"""routes_agent_harness.py β CONTRACT C4: the agent's HARNESS, kept as versioned files.
|
| 2 |
-
|
| 3 |
-
Owner item 3, verbatim (2026-08-18): *"This new module under agent is supposed to host any file
|
| 4 |
-
pertaining to the agent skills, router etc. So we build a user can build a custom harness for each
|
| 5 |
-
agent through the chat interface."*
|
| 6 |
-
|
| 7 |
-
GET /api/v1/agents/{id}/harness the file LIST (no bodies)
|
| 8 |
-
GET /api/v1/agents/{id}/harness?path=β¦ one file: current body + its versions
|
| 9 |
-
GET /api/v1/agents/{id}/harness?path=β¦&version=N one older body, verbatim
|
| 10 |
-
PUT /api/v1/agents/{id}/harness write a NEW version of one file
|
| 11 |
-
DELETE /api/v1/agents/{id}/harness?path=β¦ drop a file and its history
|
| 12 |
-
|
| 13 |
-
ββ **R8 IS THE WHOLE SHAPE: BOTH PRINCIPALS WRITE, AND NOTHING IS EVER OVERWRITTEN.** A write
|
| 14 |
-
appends a version; a roll-back is a write of an older body (`restoredFrom`), never a delete. So the
|
| 15 |
-
history is a record of what happened rather than of what somebody last wanted it to look like.
|
| 16 |
-
|
| 17 |
-
β **R8 IS DELIBERATELY NOT R9.** An agent-authored ACTION's configuration is agent-only (item 8,
|
| 18 |
-
`routes_automation`); a harness file is not. Do not copy this file's posture over there or that
|
| 19 |
-
one's over here β the two rulings differ on purpose and they sit one screen apart in the product.
|
| 20 |
-
|
| 21 |
-
β **`author` IS THE SESSION, `authorKind` IS THE PROVENANCE, AND THEY ARE DIFFERENT FACTS.** Every
|
| 22 |
-
write through this router is made BY a signed-in administrator, so `author` is stamped from the
|
| 23 |
-
session and can never be supplied by the caller. `authorKind` says whether the BODY was drafted by
|
| 24 |
-
a person or by the agent in the chat β a claim the client is entitled to make, because both are
|
| 25 |
-
permitted (R8) and so nothing is bought by forging it. `record_version()` below is the server-side
|
| 26 |
-
door the automation engine uses when the agent writes with no session at all; that one stamps the
|
| 27 |
-
agent's own id as the author, which is the only case where `author` is not a username.
|
| 28 |
-
|
| 29 |
-
β **THE VERSION LIST IS CAPPED AND THE CAP IS REPORTED, NEVER SILENT.** `MAX_VERSIONS` versions of
|
| 30 |
-
one file are kept; past that the OLDEST are dropped and the count of what was dropped rides in
|
| 31 |
-
`trimmed` on every payload that mentions the file, so a reader can see that the history is partial
|
| 32 |
-
rather than infer that the file was only ever saved twice. This is the tenant document, which is
|
| 33 |
-
already 28.6 MB on tenant #0 and is deep-copied on every read: an unbounded per-agent history is
|
| 34 |
-
a store-sized leak with a UI in front of it.
|
| 35 |
-
"""
|
| 36 |
-
from datetime import datetime, timezone
|
| 37 |
-
|
| 38 |
-
from fastapi import APIRouter, Body, Depends
|
| 39 |
-
|
| 40 |
-
from deps import Session, err, require_session
|
| 41 |
-
|
| 42 |
-
router = APIRouter(prefix="/api/v1")
|
| 43 |
-
|
| 44 |
-
#: The tenant's harness files: `{agent_id: {path: file_record}}`. A per-tenant bucket, so it rides
|
| 45 |
-
#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace β the same rule
|
| 46 |
-
#: `routes_slack.AGENTS_KEY` follows for the agent records these hang off.
|
| 47 |
-
HARNESS_KEY = "agent_harness"
|
| 48 |
-
|
| 49 |
-
#: One body. Generous for a skill or a router file and far under the point where a single write
|
| 50 |
-
#: would move the tenant document measurably. A larger body is a REFUSAL at the door, not a
|
| 51 |
-
#: truncation: a silently truncated skill file is a harness that does not do what its text says.
|
| 52 |
-
MAX_BODY_BYTES = 128 * 1024
|
| 53 |
-
|
| 54 |
-
#: Files per agent. A refusal, not a trim β creating the 65th file is a different act from saving
|
| 55 |
-
#: the 101st version of one, and only the second can be a routine consequence of ordinary editing.
|
| 56 |
-
MAX_FILES = 64
|
| 57 |
-
|
| 58 |
-
#: Versions kept per file. Past this the oldest go and `trimmed` counts them (see the header).
|
| 59 |
-
MAX_VERSIONS = 100
|
| 60 |
-
|
| 61 |
-
MAX_PATH = 200
|
| 62 |
-
|
| 63 |
-
#: What a path may contain. β THIS IS NOT A FILESYSTEM PATH AND NOTHING HERE EVER TOUCHES A DISK β
|
| 64 |
-
#: the "files" are keys in a store bucket. The character rule exists so the key is displayable, is
|
| 65 |
-
#: safe to put in a URL, and cannot carry a traversal sequence that would look meaningful to a
|
| 66 |
-
#: future reader who assumes it IS a filesystem path. Fail-closed on the character set, not on a
|
| 67 |
-
#: list of forbidden sequences: an allow-list cannot be walked around by a spelling.
|
| 68 |
-
_PATH_OK = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-/")
|
| 69 |
-
|
| 70 |
-
AUTHOR_KINDS = ("user", "agent")
|
| 71 |
-
|
| 72 |
-
|
| 73 |
-
def _now():
|
| 74 |
-
return datetime.now(timezone.utc).isoformat(timespec="seconds")
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
def _all(rt):
|
| 78 |
-
"""`{agent_id: {path: record}}` for one tenant. `{}` on any failure β an unreadable bucket must
|
| 79 |
-
degrade to "this agent has no harness files", never to a 500 on the pane that lists them."""
|
| 80 |
-
try:
|
| 81 |
-
found = rt.get(HARNESS_KEY) or {}
|
| 82 |
-
except Exception: # noqa: BLE001
|
| 83 |
-
return {}
|
| 84 |
-
return found if isinstance(found, dict) else {}
|
| 85 |
-
|
| 86 |
-
|
| 87 |
-
def _files(rt, agent_id):
|
| 88 |
-
found = _all(rt).get(str(agent_id))
|
| 89 |
-
return found if isinstance(found, dict) else {}
|
| 90 |
-
|
| 91 |
-
|
| 92 |
-
#: What kind of principal an id names. `None` = this tenant has no agent with that id.
|
| 93 |
-
#:
|
| 94 |
-
#: ββ THERE ARE TWO AGENT REGISTRIES IN THIS PRODUCT AND THE FIRST DRAFT OF THIS FILE KNEW ONLY
|
| 95 |
-
#: ONE (ASK D-5, 2026-08-18). `routes_slack._agents` is the per-Slack-channel permission wall under
|
| 96 |
-
#: Manage users. The **Agents module** the owner's item 3 is about is the AUTOMATION surface β
|
| 97 |
-
#: `Shell.tsx` mounts `<Lazily surface="Agents"><AutomationSurface /></Lazily>`, and
|
| 98 |
-
#: `AutomationDetail`'s `panelTabs` is literally the `Properties | Run history` strip R7 adds
|
| 99 |
-
#: "Harness" to. Keyed on the Slack bucket alone, every `GET/PUT /agents/{id}/harness` from that
|
| 100 |
-
#: tab would have answered **404 no_agent**: whole, gate-green and dead on arrival
|
| 101 |
-
#: [[reachable-is-not-the-same-as-built]]. Verified independently before acting, not taken on
|
| 102 |
-
#: report: `surface="Agents"` mounts `AutomationSurface`, and `ManageAgentPane` contains ZERO
|
| 103 |
-
#: occurrences of Canvas, Properties, Run history or panelTabs.
|
| 104 |
-
#:
|
| 105 |
-
#: β ONE STORE, BOTH PRINCIPALS β never a second bucket keyed by surface. The owner's "agent
|
| 106 |
-
#: skills, router" files in two places is the parallel code path item 13 exists to refuse.
|
| 107 |
-
AGENT_SLACK = "slack"
|
| 108 |
-
AGENT_AUTOMATION = "automation"
|
| 109 |
-
|
| 110 |
-
|
| 111 |
-
def agent_kind(rt, agent_id):
|
| 112 |
-
"""Which registry holds this id β `AGENT_SLACK`, `AGENT_AUTOMATION`, or `None`.
|
| 113 |
-
|
| 114 |
-
β A SYNTHETIC ROW IS NOT AN AGENT FOR THIS PURPOSE. `field:` and `system:` ids are DERIVED at
|
| 115 |
-
read time from a column definition or a connector schedule; they have no stored home, so a
|
| 116 |
-
harness file hung off one is an orphan the moment the column changes. `patch_automation`
|
| 117 |
-
already refuses those ids for the neighbouring reason, and this refuses them by simply not
|
| 118 |
-
finding them β `all_definitions` holds stored automations only.
|
| 119 |
-
"""
|
| 120 |
-
import routes_slack
|
| 121 |
-
aid = str(agent_id or "")
|
| 122 |
-
if isinstance(routes_slack._agents(rt).get(aid), dict):
|
| 123 |
-
return AGENT_SLACK
|
| 124 |
-
import automation_engine as engine
|
| 125 |
-
try:
|
| 126 |
-
known = engine.all_definitions(rt) or {}
|
| 127 |
-
except Exception: # noqa: BLE001
|
| 128 |
-
return None
|
| 129 |
-
return AGENT_AUTOMATION if aid in known else None
|
| 130 |
-
|
| 131 |
-
|
| 132 |
-
def _known_agent(rt, agent_id):
|
| 133 |
-
"""Does this tenant have an agent with this id, in EITHER registry?"""
|
| 134 |
-
return agent_kind(rt, agent_id) is not None
|
| 135 |
-
|
| 136 |
-
|
| 137 |
-
def agent_wall(session, agent_id):
|
| 138 |
-
"""404 for an unknown id, else apply the wall THAT PRINCIPAL'S OWN SURFACE applies.
|
| 139 |
-
|
| 140 |
-
ββ ONE DOOR, TWO WALLS, AND THAT IS NOT A SECOND CODE PATH β it is the refusal to invent a
|
| 141 |
-
THIRD wall. A Slack channel agent is administered under Manage users and every `/agents/*` door
|
| 142 |
-
in `routes_slack` is `admin_gate`; an automation lives in the Agents module and every door in
|
| 143 |
-
`routes_automation` is `module_gate("automation")`. A harness file is configuration OF the
|
| 144 |
-
agent it hangs off, so it is reached by whoever may already configure that agent. Picking one
|
| 145 |
-
of the two walls for both would either lock the Agents module's own users out of a tab the
|
| 146 |
-
owner asked for, or hand the Slack permission wall to anyone with an automation grant.
|
| 147 |
-
"""
|
| 148 |
-
kind = agent_kind(session.runtime, agent_id)
|
| 149 |
-
if kind is None:
|
| 150 |
-
raise err(404, "no_agent", "there is no agent with that id in this workspace")
|
| 151 |
-
if kind == AGENT_SLACK:
|
| 152 |
-
import core.perms as perms
|
| 153 |
-
if not perms.is_admin(session.user):
|
| 154 |
-
raise err(403, "forbidden", "administrators only")
|
| 155 |
-
else:
|
| 156 |
-
session.require("automation")
|
| 157 |
-
return kind
|
| 158 |
-
|
| 159 |
-
|
| 160 |
-
def normalize_path(raw):
|
| 161 |
-
"""THE path rule, in ONE place. Returns the cleaned path, or `None` if it is not acceptable.
|
| 162 |
-
|
| 163 |
-
ββ ONE RULE, TWO DOORS, AND THAT IS WHY THIS IS A FUNCTION RATHER THAN TWO IF-BLOCKS. There
|
| 164 |
-
are two ways into this store β the HTTP route (which must answer 400) and `record_version()`
|
| 165 |
-
(which must raise `ValueError`, having no response to put a status into). Written twice, the
|
| 166 |
-
two copies are [[one-question-two-normalizers]] waiting to happen: the first weakening of one
|
| 167 |
-
copy is invisible because the other still refuses, so nothing goes red and the wall is now
|
| 168 |
-
half there. Written once, a change to the rule is felt at both doors and by the gate.
|
| 169 |
-
"""
|
| 170 |
-
path = str(raw or "").strip().strip("/")
|
| 171 |
-
if not path or len(path) > MAX_PATH:
|
| 172 |
-
return None
|
| 173 |
-
if set(path) - _PATH_OK or ".." in path or "//" in path:
|
| 174 |
-
return None
|
| 175 |
-
return path
|
| 176 |
-
|
| 177 |
-
|
| 178 |
-
def _clean_path(raw):
|
| 179 |
-
"""`normalize_path` at the HTTP door, where a refusal is a 400 with a reason."""
|
| 180 |
-
path = normalize_path(raw)
|
| 181 |
-
if path is None:
|
| 182 |
-
if not str(raw or "").strip().strip("/"):
|
| 183 |
-
raise err(400, "no_path", "a harness file needs a path, for example skills/router.md")
|
| 184 |
-
if len(str(raw)) > MAX_PATH:
|
| 185 |
-
raise err(400, "path_too_long", f"a harness path is at most {MAX_PATH} characters")
|
| 186 |
-
raise err(400, "bad_path",
|
| 187 |
-
"a harness path may use letters, digits, dot, dash, underscore and / only")
|
| 188 |
-
return path
|
| 189 |
-
|
| 190 |
-
|
| 191 |
-
def _blank(path, author, author_kind):
|
| 192 |
-
return {"path": path, "versions": [], "trimmed": 0,
|
| 193 |
-
"created": _now(), "createdBy": author, "createdKind": author_kind}
|
| 194 |
-
|
| 195 |
-
|
| 196 |
-
def _append(record, body, author, author_kind, restored_from=None):
|
| 197 |
-
"""Append ONE version to a file record, in place, and report what was trimmed.
|
| 198 |
-
|
| 199 |
-
The version NUMBER is monotonic and survives trimming β it counts writes, not stored entries.
|
| 200 |
-
A version list whose numbers restart at 1 after a trim would make two different bodies share a
|
| 201 |
-
name, and `restoredFrom` would then point at whichever one happened to be in the window.
|
| 202 |
-
"""
|
| 203 |
-
# β A NEW LIST, NEVER `versions.append(...)` ON THE STORED ONE. `update()` hands the callback
|
| 204 |
-
# the live document and may run it more than once; appending in place would then stack two
|
| 205 |
-
# copies of the same version into the history on a retry.
|
| 206 |
-
prior = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 207 |
-
last = max((int(v.get("version") or 0) for v in prior if isinstance(v, dict)), default=0)
|
| 208 |
-
entry = {"version": last + 1, "body": body, "author": author, "authorKind": author_kind,
|
| 209 |
-
"created": _now(), "bytes": len(body.encode("utf-8"))}
|
| 210 |
-
if restored_from:
|
| 211 |
-
entry["restoredFrom"] = int(restored_from)
|
| 212 |
-
versions = [*prior, entry]
|
| 213 |
-
dropped = max(0, len(versions) - MAX_VERSIONS)
|
| 214 |
-
if dropped:
|
| 215 |
-
versions = versions[dropped:]
|
| 216 |
-
record["versions"] = versions
|
| 217 |
-
record["trimmed"] = int(record.get("trimmed") or 0) + dropped
|
| 218 |
-
return entry
|
| 219 |
-
|
| 220 |
-
|
| 221 |
-
def _head(record):
|
| 222 |
-
"""The newest version of a file record, or `None` for a record with no versions at all."""
|
| 223 |
-
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 224 |
-
return versions[-1] if versions else None
|
| 225 |
-
|
| 226 |
-
|
| 227 |
-
def _row(record):
|
| 228 |
-
"""One file, as the LIST door reports it: everything except the bodies.
|
| 229 |
-
|
| 230 |
-
β NO BODY, AND THAT IS THE POINT. A list door that carried every version of every file would
|
| 231 |
-
ship the whole harness on every pane render; the Harness tab lists first and opens one file
|
| 232 |
-
second, which is exactly the shape this answers.
|
| 233 |
-
"""
|
| 234 |
-
head = _head(record) or {}
|
| 235 |
-
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 236 |
-
return {"path": record.get("path") or "",
|
| 237 |
-
"version": int(head.get("version") or 0),
|
| 238 |
-
"bytes": int(head.get("bytes") or 0),
|
| 239 |
-
"author": head.get("author") or record.get("createdBy") or "",
|
| 240 |
-
"authorKind": head.get("authorKind") or record.get("createdKind") or "user",
|
| 241 |
-
"updated": head.get("created") or record.get("created") or "",
|
| 242 |
-
"created": record.get("created") or "",
|
| 243 |
-
"versions": len(versions),
|
| 244 |
-
"trimmed": int(record.get("trimmed") or 0)}
|
| 245 |
-
|
| 246 |
-
|
| 247 |
-
def _version_rows(record):
|
| 248 |
-
"""The history of one file, newest first, WITHOUT the bodies.
|
| 249 |
-
|
| 250 |
-
A body per version is what makes a diff possible, and it is also what makes this payload big:
|
| 251 |
-
100 versions of a 128 KB file is 12 MB. The client asks for the two bodies it is diffing
|
| 252 |
-
(`?path=β¦&version=N`), which is two round trips for a diff and none for a history list.
|
| 253 |
-
"""
|
| 254 |
-
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 255 |
-
out = []
|
| 256 |
-
for entry in reversed(versions):
|
| 257 |
-
if not isinstance(entry, dict):
|
| 258 |
-
continue
|
| 259 |
-
row = {"version": int(entry.get("version") or 0),
|
| 260 |
-
"author": entry.get("author") or "",
|
| 261 |
-
"authorKind": entry.get("authorKind") or "user",
|
| 262 |
-
"created": entry.get("created") or "",
|
| 263 |
-
"bytes": int(entry.get("bytes") or 0)}
|
| 264 |
-
if entry.get("restoredFrom"):
|
| 265 |
-
row["restoredFrom"] = int(entry["restoredFrom"])
|
| 266 |
-
out.append(row)
|
| 267 |
-
return out
|
| 268 |
-
|
| 269 |
-
|
| 270 |
-
def _limits():
|
| 271 |
-
"""The caps, IN the payload, so a client can say "this file is full" before a write fails.
|
| 272 |
-
|
| 273 |
-
β A limit the client cannot see is a limit the user meets as an error. `trimmed` reports the
|
| 274 |
-
one cap that acts without refusing; these report the three that refuse.
|
| 275 |
-
"""
|
| 276 |
-
return {"maxBodyBytes": MAX_BODY_BYTES, "maxFiles": MAX_FILES,
|
| 277 |
-
"maxVersions": MAX_VERSIONS, "maxPath": MAX_PATH}
|
| 278 |
-
|
| 279 |
-
|
| 280 |
-
# ββ the write door the SERVER uses (no session) ββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 281 |
-
def record_version(runtime, agent_id, path, body, author="", author_kind="agent",
|
| 282 |
-
restored_from=None):
|
| 283 |
-
"""Write one version from INSIDE the server β the agent's own half of R8.
|
| 284 |
-
|
| 285 |
-
β THIS IS THE FUNCTION, NOT THE ROUTE, THAT MAKES "editable by BOTH the user and the agent"
|
| 286 |
-
true. An agent acting inside an automation run holds no session and no cookie; if its only way
|
| 287 |
-
to write were the HTTP door it would have to borrow a person's identity, and the authorship
|
| 288 |
-
column would then be a record of who was logged in rather than of what wrote the file.
|
| 289 |
-
|
| 290 |
-
Returns the appended entry. Raises nothing the caller cannot handle: an unknown agent is a
|
| 291 |
-
`ValueError`, because a server-side caller has no HTTP response to put a 404 into.
|
| 292 |
-
"""
|
| 293 |
-
agent_id = str(agent_id or "")
|
| 294 |
-
if not _known_agent(runtime, agent_id):
|
| 295 |
-
raise ValueError(f"no agent {agent_id!r} in this workspace")
|
| 296 |
-
path = normalize_path(path)
|
| 297 |
-
if path is None:
|
| 298 |
-
raise ValueError("that is not an acceptable harness path")
|
| 299 |
-
body = str(body or "")
|
| 300 |
-
if len(body.encode("utf-8")) > MAX_BODY_BYTES:
|
| 301 |
-
raise ValueError("harness body is over the size limit")
|
| 302 |
-
kind = author_kind if author_kind in AUTHOR_KINDS else "agent"
|
| 303 |
-
author = str(author or agent_id)
|
| 304 |
-
# β THE FILE-COUNT CEILING IS CHECKED HERE, NOT INSIDE `_set`. An exception raised inside a
|
| 305 |
-
# store `update` callback propagates out of a half-run read-modify-write, and the one thing a
|
| 306 |
-
# refusal must never do is leave the caller unsure whether the write happened.
|
| 307 |
-
existing = _files(runtime, agent_id)
|
| 308 |
-
if path not in existing and len(existing) >= MAX_FILES:
|
| 309 |
-
raise ValueError(f"this agent already has {MAX_FILES} harness files")
|
| 310 |
-
appended = {}
|
| 311 |
-
|
| 312 |
-
def _set(cur):
|
| 313 |
-
cur = dict(cur or {})
|
| 314 |
-
files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
|
| 315 |
-
record = dict(files[path]) if isinstance(files.get(path), dict) else _blank(path, author, kind)
|
| 316 |
-
appended.clear()
|
| 317 |
-
appended.update(_append(record, body, author, kind, restored_from))
|
| 318 |
-
files[path] = record
|
| 319 |
-
cur[agent_id] = files
|
| 320 |
-
return cur
|
| 321 |
-
|
| 322 |
-
runtime.update(HARNESS_KEY, _set, flush="sync")
|
| 323 |
-
return appended
|
| 324 |
-
|
| 325 |
-
|
| 326 |
-
# ββ the routes ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 327 |
-
@router.get("/agents/{agent_id}/harness")
|
| 328 |
-
def get_harness(agent_id: str, path: str = "", version: int = 0,
|
| 329 |
-
session: Session = Depends(require_session)):
|
| 330 |
-
"""The list, one file, or one older body β decided by the query string (C4).
|
| 331 |
-
|
| 332 |
-
β ADMIN-GATED LIKE EVERY OTHER AGENT DOOR (`routes_slack`), and for a stronger reason than
|
| 333 |
-
consistency: a harness file is what the agent is INSTRUCTED to do, so writing one is closer to
|
| 334 |
-
editing a permission than to editing a document.
|
| 335 |
-
"""
|
| 336 |
-
agent_id = str(agent_id or "")
|
| 337 |
-
agent_wall(session, agent_id)
|
| 338 |
-
files = _files(session.runtime, agent_id)
|
| 339 |
-
if not path:
|
| 340 |
-
rows = [_row(rec) for _p, rec in sorted(files.items()) if isinstance(rec, dict)]
|
| 341 |
-
return {"agent": agent_id, "files": rows, "limits": _limits()}
|
| 342 |
-
|
| 343 |
-
wanted = _clean_path(path)
|
| 344 |
-
record = files.get(wanted)
|
| 345 |
-
if not isinstance(record, dict):
|
| 346 |
-
raise err(404, "no_file", f"this agent has no harness file at {wanted}")
|
| 347 |
-
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 348 |
-
if version:
|
| 349 |
-
for entry in versions:
|
| 350 |
-
if isinstance(entry, dict) and int(entry.get("version") or 0) == int(version):
|
| 351 |
-
return {"agent": agent_id, **_row(record), "body": entry.get("body") or "",
|
| 352 |
-
"atVersion": int(version), "history": _version_rows(record),
|
| 353 |
-
"limits": _limits()}
|
| 354 |
-
# β A TRIMMED VERSION IS A NAMED REFUSAL, NOT A 404 SHAPED LIKE A TYPO. The client asked
|
| 355 |
-
# for something that existed and no longer does, and telling it apart from a bad number is
|
| 356 |
-
# the difference between "roll back to v3" failing loudly and failing as if v3 never was.
|
| 357 |
-
trimmed = int(record.get("trimmed") or 0)
|
| 358 |
-
if trimmed and int(version) <= trimmed:
|
| 359 |
-
raise err(410, "version_trimmed",
|
| 360 |
-
f"version {int(version)} is older than the {MAX_VERSIONS} versions kept "
|
| 361 |
-
f"for this file, and its body is gone")
|
| 362 |
-
raise err(404, "no_version", f"this file has no version {int(version)}")
|
| 363 |
-
head = _head(record) or {}
|
| 364 |
-
return {"agent": agent_id, **_row(record), "body": head.get("body") or "",
|
| 365 |
-
"atVersion": int(head.get("version") or 0), "history": _version_rows(record),
|
| 366 |
-
"limits": _limits()}
|
| 367 |
-
|
| 368 |
-
|
| 369 |
-
@router.put("/agents/{agent_id}/harness")
|
| 370 |
-
def put_harness(agent_id: str, body: dict = Body(default=None),
|
| 371 |
-
session: Session = Depends(require_session)):
|
| 372 |
-
"""Write a NEW version of one harness file. `{path, body, authorKind?, restoredFrom?}` (C4).
|
| 373 |
-
|
| 374 |
-
β THERE IS NO OVERWRITE HERE AND THERE IS NO EDIT-IN-PLACE. R8's "every version kept" is not a
|
| 375 |
-
UI affordance; it is this function refusing to have a code path that replaces a body. A
|
| 376 |
-
roll-back arrives as an ordinary write carrying `restoredFrom`, so the history records that
|
| 377 |
-
somebody went back rather than pretending the intervening versions never happened.
|
| 378 |
-
"""
|
| 379 |
-
agent_id = str(agent_id or "")
|
| 380 |
-
agent_wall(session, agent_id)
|
| 381 |
-
body = body if isinstance(body, dict) else {}
|
| 382 |
-
path = _clean_path(body.get("path"))
|
| 383 |
-
text = body.get("body")
|
| 384 |
-
if not isinstance(text, str):
|
| 385 |
-
raise err(400, "no_body", "a harness file needs a body, even an empty one")
|
| 386 |
-
if len(text.encode("utf-8")) > MAX_BODY_BYTES:
|
| 387 |
-
raise err(413, "body_too_long",
|
| 388 |
-
f"a harness file is at most {MAX_BODY_BYTES // 1024} KB; this one is larger")
|
| 389 |
-
|
| 390 |
-
# β THE CALLER DECLARES THE PROVENANCE AND THE SERVER STAMPS THE IDENTITY. `authorKind` is a
|
| 391 |
-
# claim about who WROTE the text (the person, or the agent in the chat panel); `author` is the
|
| 392 |
-
# session and is never read off the request. Nothing is bought by forging the first β both
|
| 393 |
-
# principals may write (R8) β and everything would be bought by forging the second.
|
| 394 |
-
kind = str(body.get("authorKind") or "user").strip().lower()
|
| 395 |
-
if kind not in AUTHOR_KINDS:
|
| 396 |
-
raise err(400, "bad_author_kind", "authorKind is either user or agent")
|
| 397 |
-
restored = body.get("restoredFrom")
|
| 398 |
-
try:
|
| 399 |
-
restored = int(restored) if restored else None
|
| 400 |
-
except (TypeError, ValueError):
|
| 401 |
-
raise err(400, "bad_version", "restoredFrom must be a version number")
|
| 402 |
-
|
| 403 |
-
files = _files(session.runtime, agent_id)
|
| 404 |
-
if path not in files and len(files) >= MAX_FILES:
|
| 405 |
-
raise err(409, "too_many_files",
|
| 406 |
-
f"this agent already has {MAX_FILES} harness files; delete one to add another")
|
| 407 |
-
try:
|
| 408 |
-
record_version(session.runtime, agent_id, path, text,
|
| 409 |
-
author=session.uname, author_kind=kind, restored_from=restored)
|
| 410 |
-
except ValueError as exc:
|
| 411 |
-
raise err(400, "refused", str(exc))
|
| 412 |
-
|
| 413 |
-
fresh = _files(session.runtime, agent_id).get(path)
|
| 414 |
-
if not isinstance(fresh, dict) or not _head(fresh):
|
| 415 |
-
# The store took the write and did not record it. A 200 here would tell an administrator
|
| 416 |
-
# their skill file was saved when it was not β the shape `routes_slack` refuses too.
|
| 417 |
-
raise err(503, "store_unavailable", "the harness file was NOT saved")
|
| 418 |
-
head = _head(fresh)
|
| 419 |
-
return {"agent": agent_id, **_row(fresh), "body": head.get("body") or "",
|
| 420 |
-
"atVersion": int(head.get("version") or 0), "history": _version_rows(fresh),
|
| 421 |
-
"limits": _limits()}
|
| 422 |
-
|
| 423 |
-
|
| 424 |
-
@router.delete("/agents/{agent_id}/harness")
|
| 425 |
-
def delete_harness(agent_id: str, path: str = "", session: Session = Depends(require_session)):
|
| 426 |
-
"""Drop one harness file AND its history.
|
| 427 |
-
|
| 428 |
-
β THIS IS NOT THE THING R8 FORBIDS. R8 forbids a ROLL-BACK implemented as a delete β losing
|
| 429 |
-
versions as a side effect of an edit. Deleting a file is a person deciding the file should not
|
| 430 |
-
exist, which is a different act with a different button, and a store with no way to remove a
|
| 431 |
-
file is one where a typo'd path is permanent.
|
| 432 |
-
"""
|
| 433 |
-
agent_id = str(agent_id or "")
|
| 434 |
-
agent_wall(session, agent_id)
|
| 435 |
-
wanted = _clean_path(path)
|
| 436 |
-
if wanted not in _files(session.runtime, agent_id):
|
| 437 |
-
raise err(404, "no_file", f"this agent has no harness file at {wanted}")
|
| 438 |
-
|
| 439 |
-
def _set(cur):
|
| 440 |
-
cur = dict(cur or {})
|
| 441 |
-
files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
|
| 442 |
-
files.pop(wanted, None)
|
| 443 |
-
# An agent with no harness files leaves NO key behind. An empty dict per agent id is how a
|
| 444 |
-
# bucket accumulates a row for every agent anybody ever opened the tab on.
|
| 445 |
-
if files:
|
| 446 |
-
cur[agent_id] = files
|
| 447 |
-
else:
|
| 448 |
-
cur.pop(agent_id, None)
|
| 449 |
-
return cur
|
| 450 |
-
|
| 451 |
-
session.runtime.update(HARNESS_KEY, _set, flush="sync")
|
| 452 |
-
return {"agent": agent_id, "deleted": wanted,
|
| 453 |
-
"files": [_row(rec) for _p, rec in sorted(_files(session.runtime, agent_id).items())
|
| 454 |
-
if isinstance(rec, dict)],
|
| 455 |
-
"limits": _limits()}
|
|
|
|
| 1 |
+
"""routes_agent_harness.py β CONTRACT C4: the agent's HARNESS, kept as versioned files.
|
| 2 |
+
|
| 3 |
+
Owner item 3, verbatim (2026-08-18): *"This new module under agent is supposed to host any file
|
| 4 |
+
pertaining to the agent skills, router etc. So we build a user can build a custom harness for each
|
| 5 |
+
agent through the chat interface."*
|
| 6 |
+
|
| 7 |
+
GET /api/v1/agents/{id}/harness the file LIST (no bodies)
|
| 8 |
+
GET /api/v1/agents/{id}/harness?path=β¦ one file: current body + its versions
|
| 9 |
+
GET /api/v1/agents/{id}/harness?path=β¦&version=N one older body, verbatim
|
| 10 |
+
PUT /api/v1/agents/{id}/harness write a NEW version of one file
|
| 11 |
+
DELETE /api/v1/agents/{id}/harness?path=β¦ drop a file and its history
|
| 12 |
+
|
| 13 |
+
ββ **R8 IS THE WHOLE SHAPE: BOTH PRINCIPALS WRITE, AND NOTHING IS EVER OVERWRITTEN.** A write
|
| 14 |
+
appends a version; a roll-back is a write of an older body (`restoredFrom`), never a delete. So the
|
| 15 |
+
history is a record of what happened rather than of what somebody last wanted it to look like.
|
| 16 |
+
|
| 17 |
+
β **R8 IS DELIBERATELY NOT R9.** An agent-authored ACTION's configuration is agent-only (item 8,
|
| 18 |
+
`routes_automation`); a harness file is not. Do not copy this file's posture over there or that
|
| 19 |
+
one's over here β the two rulings differ on purpose and they sit one screen apart in the product.
|
| 20 |
+
|
| 21 |
+
β **`author` IS THE SESSION, `authorKind` IS THE PROVENANCE, AND THEY ARE DIFFERENT FACTS.** Every
|
| 22 |
+
write through this router is made BY a signed-in administrator, so `author` is stamped from the
|
| 23 |
+
session and can never be supplied by the caller. `authorKind` says whether the BODY was drafted by
|
| 24 |
+
a person or by the agent in the chat β a claim the client is entitled to make, because both are
|
| 25 |
+
permitted (R8) and so nothing is bought by forging it. `record_version()` below is the server-side
|
| 26 |
+
door the automation engine uses when the agent writes with no session at all; that one stamps the
|
| 27 |
+
agent's own id as the author, which is the only case where `author` is not a username.
|
| 28 |
+
|
| 29 |
+
β **THE VERSION LIST IS CAPPED AND THE CAP IS REPORTED, NEVER SILENT.** `MAX_VERSIONS` versions of
|
| 30 |
+
one file are kept; past that the OLDEST are dropped and the count of what was dropped rides in
|
| 31 |
+
`trimmed` on every payload that mentions the file, so a reader can see that the history is partial
|
| 32 |
+
rather than infer that the file was only ever saved twice. This is the tenant document, which is
|
| 33 |
+
already 28.6 MB on tenant #0 and is deep-copied on every read: an unbounded per-agent history is
|
| 34 |
+
a store-sized leak with a UI in front of it.
|
| 35 |
+
"""
|
| 36 |
+
from datetime import datetime, timezone
|
| 37 |
+
|
| 38 |
+
from fastapi import APIRouter, Body, Depends
|
| 39 |
+
|
| 40 |
+
from deps import Session, err, require_session
|
| 41 |
+
|
| 42 |
+
router = APIRouter(prefix="/api/v1")
|
| 43 |
+
|
| 44 |
+
#: The tenant's harness files: `{agent_id: {path: file_record}}`. A per-tenant bucket, so it rides
|
| 45 |
+
#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace β the same rule
|
| 46 |
+
#: `routes_slack.AGENTS_KEY` follows for the agent records these hang off.
|
| 47 |
+
HARNESS_KEY = "agent_harness"
|
| 48 |
+
|
| 49 |
+
#: One body. Generous for a skill or a router file and far under the point where a single write
|
| 50 |
+
#: would move the tenant document measurably. A larger body is a REFUSAL at the door, not a
|
| 51 |
+
#: truncation: a silently truncated skill file is a harness that does not do what its text says.
|
| 52 |
+
MAX_BODY_BYTES = 128 * 1024
|
| 53 |
+
|
| 54 |
+
#: Files per agent. A refusal, not a trim β creating the 65th file is a different act from saving
|
| 55 |
+
#: the 101st version of one, and only the second can be a routine consequence of ordinary editing.
|
| 56 |
+
MAX_FILES = 64
|
| 57 |
+
|
| 58 |
+
#: Versions kept per file. Past this the oldest go and `trimmed` counts them (see the header).
|
| 59 |
+
MAX_VERSIONS = 100
|
| 60 |
+
|
| 61 |
+
MAX_PATH = 200
|
| 62 |
+
|
| 63 |
+
#: What a path may contain. β THIS IS NOT A FILESYSTEM PATH AND NOTHING HERE EVER TOUCHES A DISK β
|
| 64 |
+
#: the "files" are keys in a store bucket. The character rule exists so the key is displayable, is
|
| 65 |
+
#: safe to put in a URL, and cannot carry a traversal sequence that would look meaningful to a
|
| 66 |
+
#: future reader who assumes it IS a filesystem path. Fail-closed on the character set, not on a
|
| 67 |
+
#: list of forbidden sequences: an allow-list cannot be walked around by a spelling.
|
| 68 |
+
_PATH_OK = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-/")
|
| 69 |
+
|
| 70 |
+
AUTHOR_KINDS = ("user", "agent")
|
| 71 |
+
|
| 72 |
+
|
| 73 |
+
def _now():
|
| 74 |
+
return datetime.now(timezone.utc).isoformat(timespec="seconds")
|
| 75 |
+
|
| 76 |
+
|
| 77 |
+
def _all(rt):
|
| 78 |
+
"""`{agent_id: {path: record}}` for one tenant. `{}` on any failure β an unreadable bucket must
|
| 79 |
+
degrade to "this agent has no harness files", never to a 500 on the pane that lists them."""
|
| 80 |
+
try:
|
| 81 |
+
found = rt.get(HARNESS_KEY) or {}
|
| 82 |
+
except Exception: # noqa: BLE001
|
| 83 |
+
return {}
|
| 84 |
+
return found if isinstance(found, dict) else {}
|
| 85 |
+
|
| 86 |
+
|
| 87 |
+
def _files(rt, agent_id):
|
| 88 |
+
found = _all(rt).get(str(agent_id))
|
| 89 |
+
return found if isinstance(found, dict) else {}
|
| 90 |
+
|
| 91 |
+
|
| 92 |
+
#: What kind of principal an id names. `None` = this tenant has no agent with that id.
|
| 93 |
+
#:
|
| 94 |
+
#: ββ THERE ARE TWO AGENT REGISTRIES IN THIS PRODUCT AND THE FIRST DRAFT OF THIS FILE KNEW ONLY
|
| 95 |
+
#: ONE (ASK D-5, 2026-08-18). `routes_slack._agents` is the per-Slack-channel permission wall under
|
| 96 |
+
#: Manage users. The **Agents module** the owner's item 3 is about is the AUTOMATION surface β
|
| 97 |
+
#: `Shell.tsx` mounts `<Lazily surface="Agents"><AutomationSurface /></Lazily>`, and
|
| 98 |
+
#: `AutomationDetail`'s `panelTabs` is literally the `Properties | Run history` strip R7 adds
|
| 99 |
+
#: "Harness" to. Keyed on the Slack bucket alone, every `GET/PUT /agents/{id}/harness` from that
|
| 100 |
+
#: tab would have answered **404 no_agent**: whole, gate-green and dead on arrival
|
| 101 |
+
#: [[reachable-is-not-the-same-as-built]]. Verified independently before acting, not taken on
|
| 102 |
+
#: report: `surface="Agents"` mounts `AutomationSurface`, and `ManageAgentPane` contains ZERO
|
| 103 |
+
#: occurrences of Canvas, Properties, Run history or panelTabs.
|
| 104 |
+
#:
|
| 105 |
+
#: β ONE STORE, BOTH PRINCIPALS β never a second bucket keyed by surface. The owner's "agent
|
| 106 |
+
#: skills, router" files in two places is the parallel code path item 13 exists to refuse.
|
| 107 |
+
AGENT_SLACK = "slack"
|
| 108 |
+
AGENT_AUTOMATION = "automation"
|
| 109 |
+
|
| 110 |
+
|
| 111 |
+
def agent_kind(rt, agent_id):
|
| 112 |
+
"""Which registry holds this id β `AGENT_SLACK`, `AGENT_AUTOMATION`, or `None`.
|
| 113 |
+
|
| 114 |
+
β A SYNTHETIC ROW IS NOT AN AGENT FOR THIS PURPOSE. `field:` and `system:` ids are DERIVED at
|
| 115 |
+
read time from a column definition or a connector schedule; they have no stored home, so a
|
| 116 |
+
harness file hung off one is an orphan the moment the column changes. `patch_automation`
|
| 117 |
+
already refuses those ids for the neighbouring reason, and this refuses them by simply not
|
| 118 |
+
finding them β `all_definitions` holds stored automations only.
|
| 119 |
+
"""
|
| 120 |
+
import routes_slack
|
| 121 |
+
aid = str(agent_id or "")
|
| 122 |
+
if isinstance(routes_slack._agents(rt).get(aid), dict):
|
| 123 |
+
return AGENT_SLACK
|
| 124 |
+
import automation_engine as engine
|
| 125 |
+
try:
|
| 126 |
+
known = engine.all_definitions(rt) or {}
|
| 127 |
+
except Exception: # noqa: BLE001
|
| 128 |
+
return None
|
| 129 |
+
return AGENT_AUTOMATION if aid in known else None
|
| 130 |
+
|
| 131 |
+
|
| 132 |
+
def _known_agent(rt, agent_id):
|
| 133 |
+
"""Does this tenant have an agent with this id, in EITHER registry?"""
|
| 134 |
+
return agent_kind(rt, agent_id) is not None
|
| 135 |
+
|
| 136 |
+
|
| 137 |
+
def agent_wall(session, agent_id):
|
| 138 |
+
"""404 for an unknown id, else apply the wall THAT PRINCIPAL'S OWN SURFACE applies.
|
| 139 |
+
|
| 140 |
+
ββ ONE DOOR, TWO WALLS, AND THAT IS NOT A SECOND CODE PATH β it is the refusal to invent a
|
| 141 |
+
THIRD wall. A Slack channel agent is administered under Manage users and every `/agents/*` door
|
| 142 |
+
in `routes_slack` is `admin_gate`; an automation lives in the Agents module and every door in
|
| 143 |
+
`routes_automation` is `module_gate("automation")`. A harness file is configuration OF the
|
| 144 |
+
agent it hangs off, so it is reached by whoever may already configure that agent. Picking one
|
| 145 |
+
of the two walls for both would either lock the Agents module's own users out of a tab the
|
| 146 |
+
owner asked for, or hand the Slack permission wall to anyone with an automation grant.
|
| 147 |
+
"""
|
| 148 |
+
kind = agent_kind(session.runtime, agent_id)
|
| 149 |
+
if kind is None:
|
| 150 |
+
raise err(404, "no_agent", "there is no agent with that id in this workspace")
|
| 151 |
+
if kind == AGENT_SLACK:
|
| 152 |
+
import core.perms as perms
|
| 153 |
+
if not perms.is_admin(session.user):
|
| 154 |
+
raise err(403, "forbidden", "administrators only")
|
| 155 |
+
else:
|
| 156 |
+
session.require("automation")
|
| 157 |
+
return kind
|
| 158 |
+
|
| 159 |
+
|
| 160 |
+
def normalize_path(raw):
|
| 161 |
+
"""THE path rule, in ONE place. Returns the cleaned path, or `None` if it is not acceptable.
|
| 162 |
+
|
| 163 |
+
ββ ONE RULE, TWO DOORS, AND THAT IS WHY THIS IS A FUNCTION RATHER THAN TWO IF-BLOCKS. There
|
| 164 |
+
are two ways into this store β the HTTP route (which must answer 400) and `record_version()`
|
| 165 |
+
(which must raise `ValueError`, having no response to put a status into). Written twice, the
|
| 166 |
+
two copies are [[one-question-two-normalizers]] waiting to happen: the first weakening of one
|
| 167 |
+
copy is invisible because the other still refuses, so nothing goes red and the wall is now
|
| 168 |
+
half there. Written once, a change to the rule is felt at both doors and by the gate.
|
| 169 |
+
"""
|
| 170 |
+
path = str(raw or "").strip().strip("/")
|
| 171 |
+
if not path or len(path) > MAX_PATH:
|
| 172 |
+
return None
|
| 173 |
+
if set(path) - _PATH_OK or ".." in path or "//" in path:
|
| 174 |
+
return None
|
| 175 |
+
return path
|
| 176 |
+
|
| 177 |
+
|
| 178 |
+
def _clean_path(raw):
|
| 179 |
+
"""`normalize_path` at the HTTP door, where a refusal is a 400 with a reason."""
|
| 180 |
+
path = normalize_path(raw)
|
| 181 |
+
if path is None:
|
| 182 |
+
if not str(raw or "").strip().strip("/"):
|
| 183 |
+
raise err(400, "no_path", "a harness file needs a path, for example skills/router.md")
|
| 184 |
+
if len(str(raw)) > MAX_PATH:
|
| 185 |
+
raise err(400, "path_too_long", f"a harness path is at most {MAX_PATH} characters")
|
| 186 |
+
raise err(400, "bad_path",
|
| 187 |
+
"a harness path may use letters, digits, dot, dash, underscore and / only")
|
| 188 |
+
return path
|
| 189 |
+
|
| 190 |
+
|
| 191 |
+
def _blank(path, author, author_kind):
|
| 192 |
+
return {"path": path, "versions": [], "trimmed": 0,
|
| 193 |
+
"created": _now(), "createdBy": author, "createdKind": author_kind}
|
| 194 |
+
|
| 195 |
+
|
| 196 |
+
def _append(record, body, author, author_kind, restored_from=None):
|
| 197 |
+
"""Append ONE version to a file record, in place, and report what was trimmed.
|
| 198 |
+
|
| 199 |
+
The version NUMBER is monotonic and survives trimming β it counts writes, not stored entries.
|
| 200 |
+
A version list whose numbers restart at 1 after a trim would make two different bodies share a
|
| 201 |
+
name, and `restoredFrom` would then point at whichever one happened to be in the window.
|
| 202 |
+
"""
|
| 203 |
+
# β A NEW LIST, NEVER `versions.append(...)` ON THE STORED ONE. `update()` hands the callback
|
| 204 |
+
# the live document and may run it more than once; appending in place would then stack two
|
| 205 |
+
# copies of the same version into the history on a retry.
|
| 206 |
+
prior = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 207 |
+
last = max((int(v.get("version") or 0) for v in prior if isinstance(v, dict)), default=0)
|
| 208 |
+
entry = {"version": last + 1, "body": body, "author": author, "authorKind": author_kind,
|
| 209 |
+
"created": _now(), "bytes": len(body.encode("utf-8"))}
|
| 210 |
+
if restored_from:
|
| 211 |
+
entry["restoredFrom"] = int(restored_from)
|
| 212 |
+
versions = [*prior, entry]
|
| 213 |
+
dropped = max(0, len(versions) - MAX_VERSIONS)
|
| 214 |
+
if dropped:
|
| 215 |
+
versions = versions[dropped:]
|
| 216 |
+
record["versions"] = versions
|
| 217 |
+
record["trimmed"] = int(record.get("trimmed") or 0) + dropped
|
| 218 |
+
return entry
|
| 219 |
+
|
| 220 |
+
|
| 221 |
+
def _head(record):
|
| 222 |
+
"""The newest version of a file record, or `None` for a record with no versions at all."""
|
| 223 |
+
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 224 |
+
return versions[-1] if versions else None
|
| 225 |
+
|
| 226 |
+
|
| 227 |
+
def _row(record):
|
| 228 |
+
"""One file, as the LIST door reports it: everything except the bodies.
|
| 229 |
+
|
| 230 |
+
β NO BODY, AND THAT IS THE POINT. A list door that carried every version of every file would
|
| 231 |
+
ship the whole harness on every pane render; the Harness tab lists first and opens one file
|
| 232 |
+
second, which is exactly the shape this answers.
|
| 233 |
+
"""
|
| 234 |
+
head = _head(record) or {}
|
| 235 |
+
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 236 |
+
return {"path": record.get("path") or "",
|
| 237 |
+
"version": int(head.get("version") or 0),
|
| 238 |
+
"bytes": int(head.get("bytes") or 0),
|
| 239 |
+
"author": head.get("author") or record.get("createdBy") or "",
|
| 240 |
+
"authorKind": head.get("authorKind") or record.get("createdKind") or "user",
|
| 241 |
+
"updated": head.get("created") or record.get("created") or "",
|
| 242 |
+
"created": record.get("created") or "",
|
| 243 |
+
"versions": len(versions),
|
| 244 |
+
"trimmed": int(record.get("trimmed") or 0)}
|
| 245 |
+
|
| 246 |
+
|
| 247 |
+
def _version_rows(record):
|
| 248 |
+
"""The history of one file, newest first, WITHOUT the bodies.
|
| 249 |
+
|
| 250 |
+
A body per version is what makes a diff possible, and it is also what makes this payload big:
|
| 251 |
+
100 versions of a 128 KB file is 12 MB. The client asks for the two bodies it is diffing
|
| 252 |
+
(`?path=β¦&version=N`), which is two round trips for a diff and none for a history list.
|
| 253 |
+
"""
|
| 254 |
+
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 255 |
+
out = []
|
| 256 |
+
for entry in reversed(versions):
|
| 257 |
+
if not isinstance(entry, dict):
|
| 258 |
+
continue
|
| 259 |
+
row = {"version": int(entry.get("version") or 0),
|
| 260 |
+
"author": entry.get("author") or "",
|
| 261 |
+
"authorKind": entry.get("authorKind") or "user",
|
| 262 |
+
"created": entry.get("created") or "",
|
| 263 |
+
"bytes": int(entry.get("bytes") or 0)}
|
| 264 |
+
if entry.get("restoredFrom"):
|
| 265 |
+
row["restoredFrom"] = int(entry["restoredFrom"])
|
| 266 |
+
out.append(row)
|
| 267 |
+
return out
|
| 268 |
+
|
| 269 |
+
|
| 270 |
+
def _limits():
|
| 271 |
+
"""The caps, IN the payload, so a client can say "this file is full" before a write fails.
|
| 272 |
+
|
| 273 |
+
β A limit the client cannot see is a limit the user meets as an error. `trimmed` reports the
|
| 274 |
+
one cap that acts without refusing; these report the three that refuse.
|
| 275 |
+
"""
|
| 276 |
+
return {"maxBodyBytes": MAX_BODY_BYTES, "maxFiles": MAX_FILES,
|
| 277 |
+
"maxVersions": MAX_VERSIONS, "maxPath": MAX_PATH}
|
| 278 |
+
|
| 279 |
+
|
| 280 |
+
# ββ the write door the SERVER uses (no session) ββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 281 |
+
def record_version(runtime, agent_id, path, body, author="", author_kind="agent",
|
| 282 |
+
restored_from=None):
|
| 283 |
+
"""Write one version from INSIDE the server β the agent's own half of R8.
|
| 284 |
+
|
| 285 |
+
β THIS IS THE FUNCTION, NOT THE ROUTE, THAT MAKES "editable by BOTH the user and the agent"
|
| 286 |
+
true. An agent acting inside an automation run holds no session and no cookie; if its only way
|
| 287 |
+
to write were the HTTP door it would have to borrow a person's identity, and the authorship
|
| 288 |
+
column would then be a record of who was logged in rather than of what wrote the file.
|
| 289 |
+
|
| 290 |
+
Returns the appended entry. Raises nothing the caller cannot handle: an unknown agent is a
|
| 291 |
+
`ValueError`, because a server-side caller has no HTTP response to put a 404 into.
|
| 292 |
+
"""
|
| 293 |
+
agent_id = str(agent_id or "")
|
| 294 |
+
if not _known_agent(runtime, agent_id):
|
| 295 |
+
raise ValueError(f"no agent {agent_id!r} in this workspace")
|
| 296 |
+
path = normalize_path(path)
|
| 297 |
+
if path is None:
|
| 298 |
+
raise ValueError("that is not an acceptable harness path")
|
| 299 |
+
body = str(body or "")
|
| 300 |
+
if len(body.encode("utf-8")) > MAX_BODY_BYTES:
|
| 301 |
+
raise ValueError("harness body is over the size limit")
|
| 302 |
+
kind = author_kind if author_kind in AUTHOR_KINDS else "agent"
|
| 303 |
+
author = str(author or agent_id)
|
| 304 |
+
# β THE FILE-COUNT CEILING IS CHECKED HERE, NOT INSIDE `_set`. An exception raised inside a
|
| 305 |
+
# store `update` callback propagates out of a half-run read-modify-write, and the one thing a
|
| 306 |
+
# refusal must never do is leave the caller unsure whether the write happened.
|
| 307 |
+
existing = _files(runtime, agent_id)
|
| 308 |
+
if path not in existing and len(existing) >= MAX_FILES:
|
| 309 |
+
raise ValueError(f"this agent already has {MAX_FILES} harness files")
|
| 310 |
+
appended = {}
|
| 311 |
+
|
| 312 |
+
def _set(cur):
|
| 313 |
+
cur = dict(cur or {})
|
| 314 |
+
files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
|
| 315 |
+
record = dict(files[path]) if isinstance(files.get(path), dict) else _blank(path, author, kind)
|
| 316 |
+
appended.clear()
|
| 317 |
+
appended.update(_append(record, body, author, kind, restored_from))
|
| 318 |
+
files[path] = record
|
| 319 |
+
cur[agent_id] = files
|
| 320 |
+
return cur
|
| 321 |
+
|
| 322 |
+
runtime.update(HARNESS_KEY, _set, flush="sync")
|
| 323 |
+
return appended
|
| 324 |
+
|
| 325 |
+
|
| 326 |
+
# ββ the routes ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 327 |
+
@router.get("/agents/{agent_id}/harness")
|
| 328 |
+
def get_harness(agent_id: str, path: str = "", version: int = 0,
|
| 329 |
+
session: Session = Depends(require_session)):
|
| 330 |
+
"""The list, one file, or one older body β decided by the query string (C4).
|
| 331 |
+
|
| 332 |
+
β ADMIN-GATED LIKE EVERY OTHER AGENT DOOR (`routes_slack`), and for a stronger reason than
|
| 333 |
+
consistency: a harness file is what the agent is INSTRUCTED to do, so writing one is closer to
|
| 334 |
+
editing a permission than to editing a document.
|
| 335 |
+
"""
|
| 336 |
+
agent_id = str(agent_id or "")
|
| 337 |
+
agent_wall(session, agent_id)
|
| 338 |
+
files = _files(session.runtime, agent_id)
|
| 339 |
+
if not path:
|
| 340 |
+
rows = [_row(rec) for _p, rec in sorted(files.items()) if isinstance(rec, dict)]
|
| 341 |
+
return {"agent": agent_id, "files": rows, "limits": _limits()}
|
| 342 |
+
|
| 343 |
+
wanted = _clean_path(path)
|
| 344 |
+
record = files.get(wanted)
|
| 345 |
+
if not isinstance(record, dict):
|
| 346 |
+
raise err(404, "no_file", f"this agent has no harness file at {wanted}")
|
| 347 |
+
versions = record.get("versions") if isinstance(record.get("versions"), list) else []
|
| 348 |
+
if version:
|
| 349 |
+
for entry in versions:
|
| 350 |
+
if isinstance(entry, dict) and int(entry.get("version") or 0) == int(version):
|
| 351 |
+
return {"agent": agent_id, **_row(record), "body": entry.get("body") or "",
|
| 352 |
+
"atVersion": int(version), "history": _version_rows(record),
|
| 353 |
+
"limits": _limits()}
|
| 354 |
+
# β A TRIMMED VERSION IS A NAMED REFUSAL, NOT A 404 SHAPED LIKE A TYPO. The client asked
|
| 355 |
+
# for something that existed and no longer does, and telling it apart from a bad number is
|
| 356 |
+
# the difference between "roll back to v3" failing loudly and failing as if v3 never was.
|
| 357 |
+
trimmed = int(record.get("trimmed") or 0)
|
| 358 |
+
if trimmed and int(version) <= trimmed:
|
| 359 |
+
raise err(410, "version_trimmed",
|
| 360 |
+
f"version {int(version)} is older than the {MAX_VERSIONS} versions kept "
|
| 361 |
+
f"for this file, and its body is gone")
|
| 362 |
+
raise err(404, "no_version", f"this file has no version {int(version)}")
|
| 363 |
+
head = _head(record) or {}
|
| 364 |
+
return {"agent": agent_id, **_row(record), "body": head.get("body") or "",
|
| 365 |
+
"atVersion": int(head.get("version") or 0), "history": _version_rows(record),
|
| 366 |
+
"limits": _limits()}
|
| 367 |
+
|
| 368 |
+
|
| 369 |
+
@router.put("/agents/{agent_id}/harness")
|
| 370 |
+
def put_harness(agent_id: str, body: dict = Body(default=None),
|
| 371 |
+
session: Session = Depends(require_session)):
|
| 372 |
+
"""Write a NEW version of one harness file. `{path, body, authorKind?, restoredFrom?}` (C4).
|
| 373 |
+
|
| 374 |
+
β THERE IS NO OVERWRITE HERE AND THERE IS NO EDIT-IN-PLACE. R8's "every version kept" is not a
|
| 375 |
+
UI affordance; it is this function refusing to have a code path that replaces a body. A
|
| 376 |
+
roll-back arrives as an ordinary write carrying `restoredFrom`, so the history records that
|
| 377 |
+
somebody went back rather than pretending the intervening versions never happened.
|
| 378 |
+
"""
|
| 379 |
+
agent_id = str(agent_id or "")
|
| 380 |
+
agent_wall(session, agent_id)
|
| 381 |
+
body = body if isinstance(body, dict) else {}
|
| 382 |
+
path = _clean_path(body.get("path"))
|
| 383 |
+
text = body.get("body")
|
| 384 |
+
if not isinstance(text, str):
|
| 385 |
+
raise err(400, "no_body", "a harness file needs a body, even an empty one")
|
| 386 |
+
if len(text.encode("utf-8")) > MAX_BODY_BYTES:
|
| 387 |
+
raise err(413, "body_too_long",
|
| 388 |
+
f"a harness file is at most {MAX_BODY_BYTES // 1024} KB; this one is larger")
|
| 389 |
+
|
| 390 |
+
# β THE CALLER DECLARES THE PROVENANCE AND THE SERVER STAMPS THE IDENTITY. `authorKind` is a
|
| 391 |
+
# claim about who WROTE the text (the person, or the agent in the chat panel); `author` is the
|
| 392 |
+
# session and is never read off the request. Nothing is bought by forging the first β both
|
| 393 |
+
# principals may write (R8) β and everything would be bought by forging the second.
|
| 394 |
+
kind = str(body.get("authorKind") or "user").strip().lower()
|
| 395 |
+
if kind not in AUTHOR_KINDS:
|
| 396 |
+
raise err(400, "bad_author_kind", "authorKind is either user or agent")
|
| 397 |
+
restored = body.get("restoredFrom")
|
| 398 |
+
try:
|
| 399 |
+
restored = int(restored) if restored else None
|
| 400 |
+
except (TypeError, ValueError):
|
| 401 |
+
raise err(400, "bad_version", "restoredFrom must be a version number")
|
| 402 |
+
|
| 403 |
+
files = _files(session.runtime, agent_id)
|
| 404 |
+
if path not in files and len(files) >= MAX_FILES:
|
| 405 |
+
raise err(409, "too_many_files",
|
| 406 |
+
f"this agent already has {MAX_FILES} harness files; delete one to add another")
|
| 407 |
+
try:
|
| 408 |
+
record_version(session.runtime, agent_id, path, text,
|
| 409 |
+
author=session.uname, author_kind=kind, restored_from=restored)
|
| 410 |
+
except ValueError as exc:
|
| 411 |
+
raise err(400, "refused", str(exc))
|
| 412 |
+
|
| 413 |
+
fresh = _files(session.runtime, agent_id).get(path)
|
| 414 |
+
if not isinstance(fresh, dict) or not _head(fresh):
|
| 415 |
+
# The store took the write and did not record it. A 200 here would tell an administrator
|
| 416 |
+
# their skill file was saved when it was not β the shape `routes_slack` refuses too.
|
| 417 |
+
raise err(503, "store_unavailable", "the harness file was NOT saved")
|
| 418 |
+
head = _head(fresh)
|
| 419 |
+
return {"agent": agent_id, **_row(fresh), "body": head.get("body") or "",
|
| 420 |
+
"atVersion": int(head.get("version") or 0), "history": _version_rows(fresh),
|
| 421 |
+
"limits": _limits()}
|
| 422 |
+
|
| 423 |
+
|
| 424 |
+
@router.delete("/agents/{agent_id}/harness")
|
| 425 |
+
def delete_harness(agent_id: str, path: str = "", session: Session = Depends(require_session)):
|
| 426 |
+
"""Drop one harness file AND its history.
|
| 427 |
+
|
| 428 |
+
β THIS IS NOT THE THING R8 FORBIDS. R8 forbids a ROLL-BACK implemented as a delete β losing
|
| 429 |
+
versions as a side effect of an edit. Deleting a file is a person deciding the file should not
|
| 430 |
+
exist, which is a different act with a different button, and a store with no way to remove a
|
| 431 |
+
file is one where a typo'd path is permanent.
|
| 432 |
+
"""
|
| 433 |
+
agent_id = str(agent_id or "")
|
| 434 |
+
agent_wall(session, agent_id)
|
| 435 |
+
wanted = _clean_path(path)
|
| 436 |
+
if wanted not in _files(session.runtime, agent_id):
|
| 437 |
+
raise err(404, "no_file", f"this agent has no harness file at {wanted}")
|
| 438 |
+
|
| 439 |
+
def _set(cur):
|
| 440 |
+
cur = dict(cur or {})
|
| 441 |
+
files = dict(cur.get(agent_id) or {}) if isinstance(cur.get(agent_id), dict) else {}
|
| 442 |
+
files.pop(wanted, None)
|
| 443 |
+
# An agent with no harness files leaves NO key behind. An empty dict per agent id is how a
|
| 444 |
+
# bucket accumulates a row for every agent anybody ever opened the tab on.
|
| 445 |
+
if files:
|
| 446 |
+
cur[agent_id] = files
|
| 447 |
+
else:
|
| 448 |
+
cur.pop(agent_id, None)
|
| 449 |
+
return cur
|
| 450 |
+
|
| 451 |
+
session.runtime.update(HARNESS_KEY, _set, flush="sync")
|
| 452 |
+
return {"agent": agent_id, "deleted": wanted,
|
| 453 |
+
"files": [_row(rec) for _p, rec in sorted(_files(session.runtime, agent_id).items())
|
| 454 |
+
if isinstance(rec, dict)],
|
| 455 |
+
"limits": _limits()}
|
api/routes_keychain.py
CHANGED
|
The diff for this file is too large to render.
See raw diff
|
|
|
api/routes_oauth.py
CHANGED
|
@@ -1,114 +1,114 @@
|
|
| 1 |
-
"""routes_oauth.py β the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
|
| 2 |
-
|
| 3 |
-
Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
|
| 4 |
-
shapes and status codes here; every decision that could be wrong lives in the module a gate
|
| 5 |
-
can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
|
| 6 |
-
so the day a second provider lands here is the day nothing in this file changes.
|
| 7 |
-
|
| 8 |
-
MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
|
| 9 |
-
`main.py`, and `routes_automation` is already included there β so this router rides inside it
|
| 10 |
-
(`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
|
| 11 |
-
alters no path.
|
| 12 |
-
|
| 13 |
-
β THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
|
| 14 |
-
screen** β it is a top-level navigation the client reaches by `<a href>`, never JSON. The
|
| 15 |
-
callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
|
| 16 |
-
`oauth_connect.safe_next`), so the user lands where they left β connected or not, whatever
|
| 17 |
-
went wrong rides in the query string; a dead-end error page where the app used to be reads as
|
| 18 |
-
"the product broke", not "the connect failed".
|
| 19 |
-
"""
|
| 20 |
-
import os
|
| 21 |
-
|
| 22 |
-
from fastapi import APIRouter, Depends, Request
|
| 23 |
-
from fastapi.responses import RedirectResponse
|
| 24 |
-
|
| 25 |
-
import oauth_connect
|
| 26 |
-
from deps import Session, err, require_session
|
| 27 |
-
|
| 28 |
-
router = APIRouter(prefix="/oauth")
|
| 29 |
-
|
| 30 |
-
|
| 31 |
-
def _redirect_uri(request: Request, provider: str) -> str:
|
| 32 |
-
"""The redirect URI this deployment registers at the provider β env-pinned when the
|
| 33 |
-
container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
|
| 34 |
-
the request. MUST match a console-registered URI verbatim, so it is computed in exactly
|
| 35 |
-
one place.
|
| 36 |
-
|
| 37 |
-
β WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
|
| 38 |
-
the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
|
| 39 |
-
the request-derived fallback below is effectively dev-only.
|
| 40 |
-
β THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
|
| 41 |
-
this returns is where the provider sends the user BACK, and the session cookie is host-only
|
| 42 |
-
(`aios_session.py:114-117`, no `domain=`) β so a callback base that disagrees with the host
|
| 43 |
-
the user actually browsed plants the session on the wrong hostname and they return logged
|
| 44 |
-
out. Moving the app to a new hostname means moving this value AND re-registering the
|
| 45 |
-
resulting URI in the provider console; one without the other fails closed.
|
| 46 |
-
Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
|
| 47 |
-
base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
|
| 48 |
-
if not base:
|
| 49 |
-
base = f"{request.url.scheme}://{request.url.netloc}"
|
| 50 |
-
return f"{base}/api/v1/oauth/{provider}/callback"
|
| 51 |
-
|
| 52 |
-
|
| 53 |
-
@router.get("/status")
|
| 54 |
-
def oauth_status(session: Session = Depends(require_session)):
|
| 55 |
-
"""C5's status shape for the SESSION user, one entry per registry provider:
|
| 56 |
-
`{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
|
| 57 |
-
`ready` reads through."""
|
| 58 |
-
return oauth_connect.status(session.runtime, session.uname)
|
| 59 |
-
|
| 60 |
-
|
| 61 |
-
def _offered_or_404(provider: str):
|
| 62 |
-
"""ββ W32-T14 / OWNER ITEM 12 / R6 β A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
|
| 63 |
-
|
| 64 |
-
The owner pasted the failure this replaces: clicking Connect on the Google card answered
|
| 65 |
-
`503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error β it is that the flow is
|
| 66 |
-
not offered at all, so the honest status is the one for a URL that does not exist. `404`
|
| 67 |
-
rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
|
| 68 |
-
coming back until somebody pays for CASA verification (D-45, ~$540β1,800/yr).
|
| 69 |
-
|
| 70 |
-
β Every door in this router goes through it, START included, because the JSON the owner saw
|
| 71 |
-
came from the start route and a guard on one leg is a guard on one leg.
|
| 72 |
-
"""
|
| 73 |
-
if not oauth_connect.offered(provider):
|
| 74 |
-
raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
@router.get("/{provider}/start")
|
| 78 |
-
def oauth_start(provider: str, request: Request, next: str = "",
|
| 79 |
-
session: Session = Depends(require_session)):
|
| 80 |
-
"""302 to the provider's consent screen (A3 β a navigation, never JSON). `?next=` is the
|
| 81 |
-
RELATIVE path the callback returns the browser to; it rides inside the single-use state,
|
| 82 |
-
sanitised, so the round trip cannot be steered off-origin."""
|
| 83 |
-
_offered_or_404(provider)
|
| 84 |
-
url, problem = oauth_connect.start(provider, session.uname,
|
| 85 |
-
_redirect_uri(request, provider), next_path=next)
|
| 86 |
-
if problem:
|
| 87 |
-
raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
|
| 88 |
-
return RedirectResponse(url, status_code=302)
|
| 89 |
-
|
| 90 |
-
|
| 91 |
-
@router.get("/{provider}/callback")
|
| 92 |
-
def oauth_callback(provider: str, request: Request,
|
| 93 |
-
session: Session = Depends(require_session),
|
| 94 |
-
state: str = "", code: str = "", error: str = ""):
|
| 95 |
-
"""The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
|
| 96 |
-
the browser back to the state's return path β connected or not (see module header)."""
|
| 97 |
-
_offered_or_404(provider)
|
| 98 |
-
if error:
|
| 99 |
-
home = "/#/"
|
| 100 |
-
return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
|
| 101 |
-
email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
|
| 102 |
-
sep = "&" if "?" in home else "?"
|
| 103 |
-
if problem:
|
| 104 |
-
return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
|
| 105 |
-
return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
|
| 106 |
-
|
| 107 |
-
|
| 108 |
-
@router.post("/{provider}/disconnect")
|
| 109 |
-
def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
|
| 110 |
-
_offered_or_404(provider)
|
| 111 |
-
if oauth_connect.provider_def(provider) is None:
|
| 112 |
-
raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
|
| 113 |
-
oauth_connect.disconnect(session.runtime, session.uname, provider)
|
| 114 |
-
return {"disconnected": provider}
|
|
|
|
| 1 |
+
"""routes_oauth.py β the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
|
| 2 |
+
|
| 3 |
+
Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
|
| 4 |
+
shapes and status codes here; every decision that could be wrong lives in the module a gate
|
| 5 |
+
can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
|
| 6 |
+
so the day a second provider lands here is the day nothing in this file changes.
|
| 7 |
+
|
| 8 |
+
MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
|
| 9 |
+
`main.py`, and `routes_automation` is already included there β so this router rides inside it
|
| 10 |
+
(`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
|
| 11 |
+
alters no path.
|
| 12 |
+
|
| 13 |
+
β THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
|
| 14 |
+
screen** β it is a top-level navigation the client reaches by `<a href>`, never JSON. The
|
| 15 |
+
callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
|
| 16 |
+
`oauth_connect.safe_next`), so the user lands where they left β connected or not, whatever
|
| 17 |
+
went wrong rides in the query string; a dead-end error page where the app used to be reads as
|
| 18 |
+
"the product broke", not "the connect failed".
|
| 19 |
+
"""
|
| 20 |
+
import os
|
| 21 |
+
|
| 22 |
+
from fastapi import APIRouter, Depends, Request
|
| 23 |
+
from fastapi.responses import RedirectResponse
|
| 24 |
+
|
| 25 |
+
import oauth_connect
|
| 26 |
+
from deps import Session, err, require_session
|
| 27 |
+
|
| 28 |
+
router = APIRouter(prefix="/oauth")
|
| 29 |
+
|
| 30 |
+
|
| 31 |
+
def _redirect_uri(request: Request, provider: str) -> str:
|
| 32 |
+
"""The redirect URI this deployment registers at the provider β env-pinned when the
|
| 33 |
+
container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
|
| 34 |
+
the request. MUST match a console-registered URI verbatim, so it is computed in exactly
|
| 35 |
+
one place.
|
| 36 |
+
|
| 37 |
+
β WAVE 29 (R4): `deploy_web.py` now PUSHES `AIOS_PUBLIC_BASE` on every deploy, defaulted to
|
| 38 |
+
the same URL as `APP_BASE_URL`, so the pinned branch is the one that runs in production and
|
| 39 |
+
the request-derived fallback below is effectively dev-only.
|
| 40 |
+
β THAT MAKES THIS FUNCTION A CUSTOM-DOMAIN COUPLING, not merely a scheme fix. Whatever host
|
| 41 |
+
this returns is where the provider sends the user BACK, and the session cookie is host-only
|
| 42 |
+
(`aios_session.py:114-117`, no `domain=`) β so a callback base that disagrees with the host
|
| 43 |
+
the user actually browsed plants the session on the wrong hostname and they return logged
|
| 44 |
+
out. Moving the app to a new hostname means moving this value AND re-registering the
|
| 45 |
+
resulting URI in the provider console; one without the other fails closed.
|
| 46 |
+
Runbook: `.claude/wiki/research/loopable-domain-runbook.md`."""
|
| 47 |
+
base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
|
| 48 |
+
if not base:
|
| 49 |
+
base = f"{request.url.scheme}://{request.url.netloc}"
|
| 50 |
+
return f"{base}/api/v1/oauth/{provider}/callback"
|
| 51 |
+
|
| 52 |
+
|
| 53 |
+
@router.get("/status")
|
| 54 |
+
def oauth_status(session: Session = Depends(require_session)):
|
| 55 |
+
"""C5's status shape for the SESSION user, one entry per registry provider:
|
| 56 |
+
`{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
|
| 57 |
+
`ready` reads through."""
|
| 58 |
+
return oauth_connect.status(session.runtime, session.uname)
|
| 59 |
+
|
| 60 |
+
|
| 61 |
+
def _offered_or_404(provider: str):
|
| 62 |
+
"""ββ W32-T14 / OWNER ITEM 12 / R6 β A PROVIDER THE PRODUCT DOES NOT OFFER HAS NO DOOR.
|
| 63 |
+
|
| 64 |
+
The owner pasted the failure this replaces: clicking Connect on the Google card answered
|
| 65 |
+
`503 oauth_unavailable` as raw JSON. R6's fix is not a nicer error β it is that the flow is
|
| 66 |
+
not offered at all, so the honest status is the one for a URL that does not exist. `404`
|
| 67 |
+
rather than `503`, deliberately: a 503 says *"come back later"* about a door that is not
|
| 68 |
+
coming back until somebody pays for CASA verification (D-45, ~$540β1,800/yr).
|
| 69 |
+
|
| 70 |
+
β Every door in this router goes through it, START included, because the JSON the owner saw
|
| 71 |
+
came from the start route and a guard on one leg is a guard on one leg.
|
| 72 |
+
"""
|
| 73 |
+
if not oauth_connect.offered(provider):
|
| 74 |
+
raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
|
| 75 |
+
|
| 76 |
+
|
| 77 |
+
@router.get("/{provider}/start")
|
| 78 |
+
def oauth_start(provider: str, request: Request, next: str = "",
|
| 79 |
+
session: Session = Depends(require_session)):
|
| 80 |
+
"""302 to the provider's consent screen (A3 β a navigation, never JSON). `?next=` is the
|
| 81 |
+
RELATIVE path the callback returns the browser to; it rides inside the single-use state,
|
| 82 |
+
sanitised, so the round trip cannot be steered off-origin."""
|
| 83 |
+
_offered_or_404(provider)
|
| 84 |
+
url, problem = oauth_connect.start(provider, session.uname,
|
| 85 |
+
_redirect_uri(request, provider), next_path=next)
|
| 86 |
+
if problem:
|
| 87 |
+
raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
|
| 88 |
+
return RedirectResponse(url, status_code=302)
|
| 89 |
+
|
| 90 |
+
|
| 91 |
+
@router.get("/{provider}/callback")
|
| 92 |
+
def oauth_callback(provider: str, request: Request,
|
| 93 |
+
session: Session = Depends(require_session),
|
| 94 |
+
state: str = "", code: str = "", error: str = ""):
|
| 95 |
+
"""The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
|
| 96 |
+
the browser back to the state's return path β connected or not (see module header)."""
|
| 97 |
+
_offered_or_404(provider)
|
| 98 |
+
if error:
|
| 99 |
+
home = "/#/"
|
| 100 |
+
return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
|
| 101 |
+
email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
|
| 102 |
+
sep = "&" if "?" in home else "?"
|
| 103 |
+
if problem:
|
| 104 |
+
return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
|
| 105 |
+
return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
|
| 106 |
+
|
| 107 |
+
|
| 108 |
+
@router.post("/{provider}/disconnect")
|
| 109 |
+
def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
|
| 110 |
+
_offered_or_404(provider)
|
| 111 |
+
if oauth_connect.provider_def(provider) is None:
|
| 112 |
+
raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
|
| 113 |
+
oauth_connect.disconnect(session.runtime, session.uname, provider)
|
| 114 |
+
return {"disconnected": provider}
|
api/routes_records.py
CHANGED
|
@@ -1,211 +1,211 @@
|
|
| 1 |
-
"""Record detail routes: durable comments, scoped to the caller's book β ON EVERY DATABASE.
|
| 2 |
-
|
| 3 |
-
β WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
|
| 4 |
-
customer-shaped wall bolted to the module import line: `_in_book` asked
|
| 5 |
-
`routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
|
| 6 |
-
typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
|
| 7 |
-
panel answered "that customer is not in your book" β the owner's report. The dangerous half is
|
| 8 |
-
the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
|
| 9 |
-
is filed against somebody's customer where the whole team can read it.
|
| 10 |
-
|
| 11 |
-
THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
|
| 12 |
-
events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
|
| 13 |
-
per scope β the GRANT and the ROW SET β by asking that topic's own route, never by re-deriving
|
| 14 |
-
one here:
|
| 15 |
-
|
| 16 |
-
customer / cohort `routes_customers.allowed_pids` behind the `customer_data` grant
|
| 17 |
-
product `routes_products.scoped_pool` behind the `product_data` grant
|
| 18 |
-
ut_<slug> `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
|
| 19 |
-
(404 unknown / 403 not yours β a user table has no module grant).
|
| 20 |
-
β W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` β the pool builds every
|
| 21 |
-
ROW to derive a pid set this module discards, and RAISES 409 on a
|
| 22 |
-
read-through grid past one window, which is why the record drawer painted
|
| 23 |
-
an error page on `ut_odoo_gl_lines`.
|
| 24 |
-
|
| 25 |
-
β THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
|
| 26 |
-
section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
|
| 27 |
-
another session's gate mid-wave β the WALL is the query parameter, not the word.
|
| 28 |
-
|
| 29 |
-
β NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
|
| 30 |
-
shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
|
| 31 |
-
400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
|
| 32 |
-
the same reason: a typo served as `customer` answers a question nobody asked).
|
| 33 |
-
"""
|
| 34 |
-
from fastapi import APIRouter, Body, Depends, Query
|
| 35 |
-
|
| 36 |
-
from deps import Session, err, require_session
|
| 37 |
-
|
| 38 |
-
router = APIRouter(prefix="/api/v1")
|
| 39 |
-
|
| 40 |
-
#: The customer topic's two names β one book, two surfaces (the Cohort page is the customer table
|
| 41 |
-
#: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
|
| 42 |
-
_CUSTOMER_SCOPES = ("", "customer", "cohort")
|
| 43 |
-
|
| 44 |
-
|
| 45 |
-
def _scope_or_400(raw):
|
| 46 |
-
scope = str(raw or "customer").strip().lower()
|
| 47 |
-
if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
|
| 48 |
-
return "customer" if scope in _CUSTOMER_SCOPES else scope
|
| 49 |
-
raise err(400, "bad_scope",
|
| 50 |
-
"scope must be customer, cohort, product or a ut_ database β refusing to guess")
|
| 51 |
-
|
| 52 |
-
|
| 53 |
-
def _pool_or_refuse(session: Session, scope: str):
|
| 54 |
-
"""The pids this session may attach comments to ON THIS DATABASE β grant wall included.
|
| 55 |
-
|
| 56 |
-
Returns **`(pids, unbounded)`** β a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
|
| 57 |
-
so a caller who may not open the surface never learns anything about the row they asked about.
|
| 58 |
-
|
| 59 |
-
β `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
|
| 60 |
-
one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
|
| 61 |
-
`frozenset()` for both β see the branch below.
|
| 62 |
-
β THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
|
| 63 |
-
do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
|
| 64 |
-
that REPLACES this function with its own lambda. A gate's test double is a caller
|
| 65 |
-
([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
|
| 66 |
-
bare frozenset and the section died on `ValueError: too many values to unpack` β no tally, no
|
| 67 |
-
failing name. Change the shape here and that double changes with it.
|
| 68 |
-
"""
|
| 69 |
-
if scope == "product":
|
| 70 |
-
from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
|
| 71 |
-
|
| 72 |
-
session.require(PRODUCT_MODULE)
|
| 73 |
-
pids, _team, _rows, _fields = scoped_pool(session)
|
| 74 |
-
# β `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
|
| 75 |
-
# after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
|
| 76 |
-
# a `TypeError` β a 500 on every product comment β while both other branches worked. A
|
| 77 |
-
# return shape is a contract even when the function is private.
|
| 78 |
-
return (pids, False)
|
| 79 |
-
if scope.startswith("ut_"):
|
| 80 |
-
# No module grant exists for a user table β `_defn_or_refuse` inside `scoped_pids` IS
|
| 81 |
-
# the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
|
| 82 |
-
# rows routes do.
|
| 83 |
-
#
|
| 84 |
-
# ββ W33-T03 / D-183 β `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
|
| 85 |
-
# `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
|
| 86 |
-
# a read-through grid larger than one window it RAISES `409 window_required`. So opening the
|
| 87 |
-
# record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page β for a panel
|
| 88 |
-
# that renders comments about ONE row it already has. `scoped_pids` answers the identical
|
| 89 |
-
# question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
|
| 90 |
-
# W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
|
| 91 |
-
# used to become openable on those two grids.
|
| 92 |
-
from routes_tables import scoped_pids
|
| 93 |
-
|
| 94 |
-
limits = []
|
| 95 |
-
pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
|
| 96 |
-
# β AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
|
| 97 |
-
# how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
|
| 98 |
-
# database with no rows and for a read-through grid too big to enumerate β it distinguishes
|
| 99 |
-
# them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
|
| 100 |
-
# from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
|
| 101 |
-
# is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
|
| 102 |
-
# β ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
|
| 103 |
-
# THE TENANT IS THE UNIT β `scoped_pool` itself carries "no per-row owner filter; the
|
| 104 |
-
# table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
|
| 105 |
-
# `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
|
| 106 |
-
return (pids, bool(limits))
|
| 107 |
-
from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
|
| 108 |
-
|
| 109 |
-
session.require(CUSTOMER_MODULE)
|
| 110 |
-
return (frozenset(allowed_pids(session)), False)
|
| 111 |
-
|
| 112 |
-
|
| 113 |
-
def _in_book(pid, session, scope):
|
| 114 |
-
pids, unbounded = _pool_or_refuse(session, scope)
|
| 115 |
-
if unbounded:
|
| 116 |
-
# The table wall passed and the row set is larger than this process will enumerate. Said
|
| 117 |
-
# out loud rather than silently admitting: R6's second sentence is that a limit which
|
| 118 |
-
# cannot be removed gets REPORTED, and this is the one place the report has no envelope to
|
| 119 |
-
# ride in.
|
| 120 |
-
print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) β "
|
| 121 |
-
f"admitting on the table wall alone, per D-72")
|
| 122 |
-
return
|
| 123 |
-
if pid not in pids:
|
| 124 |
-
# 403, not 404: the record may exist, but this session may not inspect it.
|
| 125 |
-
raise err(403, "out_of_scope", "that record is not in your book")
|
| 126 |
-
|
| 127 |
-
|
| 128 |
-
def _unavailable():
|
| 129 |
-
return err(
|
| 130 |
-
503,
|
| 131 |
-
"store_unavailable",
|
| 132 |
-
"record comments are temporarily unavailable β no change was saved",
|
| 133 |
-
)
|
| 134 |
-
|
| 135 |
-
|
| 136 |
-
# β WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments β comments hang off a RECORD
|
| 137 |
-
# in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
|
| 138 |
-
# wall was always the query param). The old path stays as an ALIAS because the shipped client
|
| 139 |
-
# still calls it; verify_api pins the canonical path AND that the alias answers, so removing
|
| 140 |
-
# the alias later is a decision, never an accident.
|
| 141 |
-
@router.get("/records/{pid}/comments")
|
| 142 |
-
@router.get("/customers/{pid}/comments")
|
| 143 |
-
def comments(pid: int, scope: str = Query(default="customer"),
|
| 144 |
-
session: Session = Depends(require_session)):
|
| 145 |
-
from core import record_comments
|
| 146 |
-
|
| 147 |
-
scope = _scope_or_400(scope)
|
| 148 |
-
_in_book(pid, session, scope)
|
| 149 |
-
try:
|
| 150 |
-
rows = record_comments.list_comments(session.runtime, pid, scope=scope)
|
| 151 |
-
except record_comments.CommentsUnavailable:
|
| 152 |
-
raise _unavailable()
|
| 153 |
-
return {"comments": rows}
|
| 154 |
-
|
| 155 |
-
|
| 156 |
-
@router.post("/records/{pid}/comments", status_code=201)
|
| 157 |
-
@router.post("/customers/{pid}/comments", status_code=201)
|
| 158 |
-
def create_comment(
|
| 159 |
-
pid: int,
|
| 160 |
-
body: dict = Body(default=None),
|
| 161 |
-
scope: str = Query(default="customer"),
|
| 162 |
-
session: Session = Depends(require_session),
|
| 163 |
-
):
|
| 164 |
-
from core import record_comments
|
| 165 |
-
|
| 166 |
-
scope = _scope_or_400(scope)
|
| 167 |
-
_in_book(pid, session, scope)
|
| 168 |
-
try:
|
| 169 |
-
comment = record_comments.add_comment(
|
| 170 |
-
session.runtime,
|
| 171 |
-
pid,
|
| 172 |
-
(body or {}).get("body"),
|
| 173 |
-
session.uname,
|
| 174 |
-
session.user.get("name") or session.uname,
|
| 175 |
-
scope=scope,
|
| 176 |
-
)
|
| 177 |
-
except ValueError as exc:
|
| 178 |
-
raise err(400, "bad_comment", str(exc))
|
| 179 |
-
except record_comments.CommentsUnavailable:
|
| 180 |
-
raise _unavailable()
|
| 181 |
-
return {"comment": comment}
|
| 182 |
-
|
| 183 |
-
|
| 184 |
-
@router.delete("/records/{pid}/comments/{comment_id}")
|
| 185 |
-
@router.delete("/customers/{pid}/comments/{comment_id}")
|
| 186 |
-
def remove_comment(
|
| 187 |
-
pid: int,
|
| 188 |
-
comment_id: str,
|
| 189 |
-
scope: str = Query(default="customer"),
|
| 190 |
-
session: Session = Depends(require_session),
|
| 191 |
-
):
|
| 192 |
-
from core import record_comments
|
| 193 |
-
|
| 194 |
-
scope = _scope_or_400(scope)
|
| 195 |
-
_in_book(pid, session, scope)
|
| 196 |
-
try:
|
| 197 |
-
deleted = record_comments.delete_comment(
|
| 198 |
-
session.runtime,
|
| 199 |
-
pid,
|
| 200 |
-
comment_id,
|
| 201 |
-
session.uname,
|
| 202 |
-
admin=session.admin,
|
| 203 |
-
scope=scope,
|
| 204 |
-
)
|
| 205 |
-
except record_comments.CommentForbidden:
|
| 206 |
-
raise err(403, "comment_forbidden", "only the author may delete this comment")
|
| 207 |
-
except record_comments.CommentsUnavailable:
|
| 208 |
-
raise _unavailable()
|
| 209 |
-
if not deleted:
|
| 210 |
-
raise err(404, "comment_not_found", "that comment no longer exists")
|
| 211 |
-
return {"ok": True, "id": comment_id}
|
|
|
|
| 1 |
+
"""Record detail routes: durable comments, scoped to the caller's book β ON EVERY DATABASE.
|
| 2 |
+
|
| 3 |
+
β WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
|
| 4 |
+
customer-shaped wall bolted to the module import line: `_in_book` asked
|
| 5 |
+
`routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
|
| 6 |
+
typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
|
| 7 |
+
panel answered "that customer is not in your book" β the owner's report. The dangerous half is
|
| 8 |
+
the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
|
| 9 |
+
is filed against somebody's customer where the whole team can read it.
|
| 10 |
+
|
| 11 |
+
THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
|
| 12 |
+
events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
|
| 13 |
+
per scope β the GRANT and the ROW SET β by asking that topic's own route, never by re-deriving
|
| 14 |
+
one here:
|
| 15 |
+
|
| 16 |
+
customer / cohort `routes_customers.allowed_pids` behind the `customer_data` grant
|
| 17 |
+
product `routes_products.scoped_pool` behind the `product_data` grant
|
| 18 |
+
ut_<slug> `routes_tables.scoped_pids`, whose `_defn_or_refuse` IS the wall
|
| 19 |
+
(404 unknown / 403 not yours β a user table has no module grant).
|
| 20 |
+
β W33-T03/D-183: `scoped_pIDs`, not `scoped_pOOL` β the pool builds every
|
| 21 |
+
ROW to derive a pid set this module discards, and RAISES 409 on a
|
| 22 |
+
read-through grid past one window, which is why the record drawer painted
|
| 23 |
+
an error page on `ut_odoo_gl_lines`.
|
| 24 |
+
|
| 25 |
+
β THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
|
| 26 |
+
section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
|
| 27 |
+
another session's gate mid-wave β the WALL is the query parameter, not the word.
|
| 28 |
+
|
| 29 |
+
β NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
|
| 30 |
+
shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
|
| 31 |
+
400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
|
| 32 |
+
the same reason: a typo served as `customer` answers a question nobody asked).
|
| 33 |
+
"""
|
| 34 |
+
from fastapi import APIRouter, Body, Depends, Query
|
| 35 |
+
|
| 36 |
+
from deps import Session, err, require_session
|
| 37 |
+
|
| 38 |
+
router = APIRouter(prefix="/api/v1")
|
| 39 |
+
|
| 40 |
+
#: The customer topic's two names β one book, two surfaces (the Cohort page is the customer table
|
| 41 |
+
#: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
|
| 42 |
+
_CUSTOMER_SCOPES = ("", "customer", "cohort")
|
| 43 |
+
|
| 44 |
+
|
| 45 |
+
def _scope_or_400(raw):
|
| 46 |
+
scope = str(raw or "customer").strip().lower()
|
| 47 |
+
if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
|
| 48 |
+
return "customer" if scope in _CUSTOMER_SCOPES else scope
|
| 49 |
+
raise err(400, "bad_scope",
|
| 50 |
+
"scope must be customer, cohort, product or a ut_ database β refusing to guess")
|
| 51 |
+
|
| 52 |
+
|
| 53 |
+
def _pool_or_refuse(session: Session, scope: str):
|
| 54 |
+
"""The pids this session may attach comments to ON THIS DATABASE β grant wall included.
|
| 55 |
+
|
| 56 |
+
Returns **`(pids, unbounded)`** β a 2-tuple on EVERY branch. Raises the topic's own 403/404/503,
|
| 57 |
+
so a caller who may not open the surface never learns anything about the row they asked about.
|
| 58 |
+
|
| 59 |
+
β `unbounded` is TRUE only when the row set could not be ENUMERATED (a read-through grid past
|
| 60 |
+
one window), never when it is merely EMPTY. Those are opposite answers and `scoped_pids` returns
|
| 61 |
+
`frozenset()` for both β see the branch below.
|
| 62 |
+
β THE SHAPE IS A CONTRACT EVEN THOUGH THIS FUNCTION IS PRIVATE, and it has two consumers that
|
| 63 |
+
do not travel together: `_in_book` here, and a NEGATIVE CONTROL in `aios-web/api/verify_scopes.py`
|
| 64 |
+
that REPLACES this function with its own lambda. A gate's test double is a caller
|
| 65 |
+
([[test-double-patched-by-a-name-list]]); when this signature moved, that double kept returning a
|
| 66 |
+
bare frozenset and the section died on `ValueError: too many values to unpack` β no tally, no
|
| 67 |
+
failing name. Change the shape here and that double changes with it.
|
| 68 |
+
"""
|
| 69 |
+
if scope == "product":
|
| 70 |
+
from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
|
| 71 |
+
|
| 72 |
+
session.require(PRODUCT_MODULE)
|
| 73 |
+
pids, _team, _rows, _fields = scoped_pool(session)
|
| 74 |
+
# β `(pids, unbounded)` on EVERY branch. This one returned a bare frozenset for ten minutes
|
| 75 |
+
# after the `ut_` branch grew its second element, and `_in_book`'s unpack would have raised
|
| 76 |
+
# a `TypeError` β a 500 on every product comment β while both other branches worked. A
|
| 77 |
+
# return shape is a contract even when the function is private.
|
| 78 |
+
return (pids, False)
|
| 79 |
+
if scope.startswith("ut_"):
|
| 80 |
+
# No module grant exists for a user table β `_defn_or_refuse` inside `scoped_pids` IS
|
| 81 |
+
# the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
|
| 82 |
+
# rows routes do.
|
| 83 |
+
#
|
| 84 |
+
# ββ W33-T03 / D-183 β `scoped_pids`, NOT `scoped_pool`, AND THAT ONE WORD IS THE BUG.
|
| 85 |
+
# `scoped_pool` builds every ROW to derive a pid set this function then throws away, and on
|
| 86 |
+
# a read-through grid larger than one window it RAISES `409 window_required`. So opening the
|
| 87 |
+
# record drawer on `ut_odoo_gl_lines` (975,137 rows) painted an error page β for a panel
|
| 88 |
+
# that renders comments about ONE row it already has. `scoped_pids` answers the identical
|
| 89 |
+
# question (its docstring: *"the pid set is IDENTICAL, not merely equivalent"*) and takes
|
| 90 |
+
# W31-T20's `limits` OUT-PARAMETER instead of raising, which is the same shape `/workspace`
|
| 91 |
+
# used to become openable on those two grids.
|
| 92 |
+
from routes_tables import scoped_pids
|
| 93 |
+
|
| 94 |
+
limits = []
|
| 95 |
+
pids, _fields, _defn = scoped_pids(session, scope, limits=limits)
|
| 96 |
+
# β AN EMPTY PID SET AND AN UNRESOLVABLE ONE ARE OPPOSITE ANSWERS, and collapsing them is
|
| 97 |
+
# how a fail-closed default becomes a lie. `scoped_pids` returns `frozenset()` BOTH for a
|
| 98 |
+
# database with no rows and for a read-through grid too big to enumerate β it distinguishes
|
| 99 |
+
# them by APPENDING R6's sentence to `limits`. Without this branch the drawer would move
|
| 100 |
+
# from a 409 error page to a 403 "not in your book" on a row the user is looking at, which
|
| 101 |
+
# is the same defect wearing a politer message ([[empty-answer-vs-unfinished-answer]]).
|
| 102 |
+
# β ADMITTING HERE IS NOT A WIDENING, and the ruling is wave 27 / D-72: on a `ut_*` database
|
| 103 |
+
# THE TENANT IS THE UNIT β `scoped_pool` itself carries "no per-row owner filter; the
|
| 104 |
+
# table-level wall is the WHOLE wall". `_defn_or_refuse` has already run inside
|
| 105 |
+
# `scoped_pids` and answered 404/403. The pid set was only ever an existence check.
|
| 106 |
+
return (pids, bool(limits))
|
| 107 |
+
from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
|
| 108 |
+
|
| 109 |
+
session.require(CUSTOMER_MODULE)
|
| 110 |
+
return (frozenset(allowed_pids(session)), False)
|
| 111 |
+
|
| 112 |
+
|
| 113 |
+
def _in_book(pid, session, scope):
|
| 114 |
+
pids, unbounded = _pool_or_refuse(session, scope)
|
| 115 |
+
if unbounded:
|
| 116 |
+
# The table wall passed and the row set is larger than this process will enumerate. Said
|
| 117 |
+
# out loud rather than silently admitting: R6's second sentence is that a limit which
|
| 118 |
+
# cannot be removed gets REPORTED, and this is the one place the report has no envelope to
|
| 119 |
+
# ride in.
|
| 120 |
+
print(f"[records] {scope}: pid membership unresolved (read-through beyond one window) β "
|
| 121 |
+
f"admitting on the table wall alone, per D-72")
|
| 122 |
+
return
|
| 123 |
+
if pid not in pids:
|
| 124 |
+
# 403, not 404: the record may exist, but this session may not inspect it.
|
| 125 |
+
raise err(403, "out_of_scope", "that record is not in your book")
|
| 126 |
+
|
| 127 |
+
|
| 128 |
+
def _unavailable():
|
| 129 |
+
return err(
|
| 130 |
+
503,
|
| 131 |
+
"store_unavailable",
|
| 132 |
+
"record comments are temporarily unavailable β no change was saved",
|
| 133 |
+
)
|
| 134 |
+
|
| 135 |
+
|
| 136 |
+
# β WAVE 21 (D-17): the CANONICAL path is /records/{pid}/comments β comments hang off a RECORD
|
| 137 |
+
# in whatever topic `?scope=` names, and the customer-flavoured noun was wave-19 residue (the
|
| 138 |
+
# wall was always the query param). The old path stays as an ALIAS because the shipped client
|
| 139 |
+
# still calls it; verify_api pins the canonical path AND that the alias answers, so removing
|
| 140 |
+
# the alias later is a decision, never an accident.
|
| 141 |
+
@router.get("/records/{pid}/comments")
|
| 142 |
+
@router.get("/customers/{pid}/comments")
|
| 143 |
+
def comments(pid: int, scope: str = Query(default="customer"),
|
| 144 |
+
session: Session = Depends(require_session)):
|
| 145 |
+
from core import record_comments
|
| 146 |
+
|
| 147 |
+
scope = _scope_or_400(scope)
|
| 148 |
+
_in_book(pid, session, scope)
|
| 149 |
+
try:
|
| 150 |
+
rows = record_comments.list_comments(session.runtime, pid, scope=scope)
|
| 151 |
+
except record_comments.CommentsUnavailable:
|
| 152 |
+
raise _unavailable()
|
| 153 |
+
return {"comments": rows}
|
| 154 |
+
|
| 155 |
+
|
| 156 |
+
@router.post("/records/{pid}/comments", status_code=201)
|
| 157 |
+
@router.post("/customers/{pid}/comments", status_code=201)
|
| 158 |
+
def create_comment(
|
| 159 |
+
pid: int,
|
| 160 |
+
body: dict = Body(default=None),
|
| 161 |
+
scope: str = Query(default="customer"),
|
| 162 |
+
session: Session = Depends(require_session),
|
| 163 |
+
):
|
| 164 |
+
from core import record_comments
|
| 165 |
+
|
| 166 |
+
scope = _scope_or_400(scope)
|
| 167 |
+
_in_book(pid, session, scope)
|
| 168 |
+
try:
|
| 169 |
+
comment = record_comments.add_comment(
|
| 170 |
+
session.runtime,
|
| 171 |
+
pid,
|
| 172 |
+
(body or {}).get("body"),
|
| 173 |
+
session.uname,
|
| 174 |
+
session.user.get("name") or session.uname,
|
| 175 |
+
scope=scope,
|
| 176 |
+
)
|
| 177 |
+
except ValueError as exc:
|
| 178 |
+
raise err(400, "bad_comment", str(exc))
|
| 179 |
+
except record_comments.CommentsUnavailable:
|
| 180 |
+
raise _unavailable()
|
| 181 |
+
return {"comment": comment}
|
| 182 |
+
|
| 183 |
+
|
| 184 |
+
@router.delete("/records/{pid}/comments/{comment_id}")
|
| 185 |
+
@router.delete("/customers/{pid}/comments/{comment_id}")
|
| 186 |
+
def remove_comment(
|
| 187 |
+
pid: int,
|
| 188 |
+
comment_id: str,
|
| 189 |
+
scope: str = Query(default="customer"),
|
| 190 |
+
session: Session = Depends(require_session),
|
| 191 |
+
):
|
| 192 |
+
from core import record_comments
|
| 193 |
+
|
| 194 |
+
scope = _scope_or_400(scope)
|
| 195 |
+
_in_book(pid, session, scope)
|
| 196 |
+
try:
|
| 197 |
+
deleted = record_comments.delete_comment(
|
| 198 |
+
session.runtime,
|
| 199 |
+
pid,
|
| 200 |
+
comment_id,
|
| 201 |
+
session.uname,
|
| 202 |
+
admin=session.admin,
|
| 203 |
+
scope=scope,
|
| 204 |
+
)
|
| 205 |
+
except record_comments.CommentForbidden:
|
| 206 |
+
raise err(403, "comment_forbidden", "only the author may delete this comment")
|
| 207 |
+
except record_comments.CommentsUnavailable:
|
| 208 |
+
raise _unavailable()
|
| 209 |
+
if not deleted:
|
| 210 |
+
raise err(404, "comment_not_found", "that comment no longer exists")
|
| 211 |
+
return {"ok": True, "id": comment_id}
|
api/routes_script_views.py
CHANGED
|
@@ -1,439 +1,439 @@
|
|
| 1 |
-
"""routes_script_views.py β CONTRACT C3: a database View that is a PYTHON SCRIPT (R3 / R5 / R10).
|
| 2 |
-
|
| 3 |
-
Owner item 6, verbatim (2026-08-18): *"Add code script as an interface (database View) so a user
|
| 4 |
-
can build whatever they want through the Agent chat interface. be able to create any dashboard
|
| 5 |
-
they want. User should have the ability to see the code AND the dashboard output of course⦠Limit
|
| 6 |
-
the code script View per database⦠Any agent can add into more AI script, so we can see different
|
| 7 |
-
versions or different things the AI code for us."*
|
| 8 |
-
|
| 9 |
-
GET /api/v1/script-views?database=K the views bound to ONE database
|
| 10 |
-
POST /api/v1/script-views create one {database, name?, source}
|
| 11 |
-
GET /api/v1/script-views/{id} one view, its source and its history
|
| 12 |
-
PUT /api/v1/script-views/{id} a NEW VERSION of the source
|
| 13 |
-
DELETE /api/v1/script-views/{id} drop it
|
| 14 |
-
POST /api/v1/script-views/{id}/run run it -> {ok, spec | error, stdout, ms}
|
| 15 |
-
POST /api/v1/script-views/{id}/revert go back to an earlier version {version}
|
| 16 |
-
|
| 17 |
-
ββ **R3 IS "SCOPED, NOT CAPPED", AND THE TWO HALVES POINT OPPOSITE WAYS.** *Scoped*: a view may
|
| 18 |
-
read ONLY the database it lives in, and a script that names another database is REFUSED with a
|
| 19 |
-
message naming both. *Not capped*: there is **no limit on how many script views a database may
|
| 20 |
-
carry**, because that is how an agent offers three attempts and the owner picks one. So nothing
|
| 21 |
-
below counts views. What IS bounded is what makes them big β one source is capped, and one view's
|
| 22 |
-
edit history is capped and REPORTS what it dropped.
|
| 23 |
-
|
| 24 |
-
β **THE RUN IS THE CALLER'S, NEVER THE AUTHOR'S (R5).** `script_sandbox.run_view` is handed
|
| 25 |
-
`session.user`, so a script written by an administrator and opened by a scoped analyst reads the
|
| 26 |
-
ANALYST's rows. The author decides what the code does; the reader decides what it can see.
|
| 27 |
-
β And the reverse case is safe rather than lucky: a narrowly-scoped author cannot write a script
|
| 28 |
-
that exfiltrates anything, because the only thing a script can return is a render spec drawn on
|
| 29 |
-
the screen of the person who ran it. There is no network, no file and no second reader.
|
| 30 |
-
|
| 31 |
-
β **`run` IS `def`, NOT `async def`.** It waits on a subprocess for up to ten seconds; as a
|
| 32 |
-
coroutine that would block the event loop for every other request in the container. FastAPI runs a
|
| 33 |
-
plain `def` in the threadpool, which is what makes one slow script one slow REQUEST.
|
| 34 |
-
"""
|
| 35 |
-
import threading
|
| 36 |
-
from datetime import datetime, timezone
|
| 37 |
-
|
| 38 |
-
from fastapi import APIRouter, Body, Depends
|
| 39 |
-
|
| 40 |
-
from deps import Session, err, require_session
|
| 41 |
-
|
| 42 |
-
router = APIRouter(prefix="/api/v1")
|
| 43 |
-
|
| 44 |
-
#: The tenant's script views: `{id: record}`. Per tenant, so it rides `runtime.store_key`.
|
| 45 |
-
VIEWS_KEY = "script_views"
|
| 46 |
-
|
| 47 |
-
MAX_NAME = 80
|
| 48 |
-
MAX_SOURCE_BYTES = 128 * 1024
|
| 49 |
-
|
| 50 |
-
#: Edit history per view. β NOT a cap on the NUMBER of views (R3 forbids that) β a cap on how far
|
| 51 |
-
#: back ONE view's source is kept. Past this the oldest go and `trimmed` counts them, so a reader
|
| 52 |
-
#: can see the history is partial instead of concluding the view was only ever saved twice.
|
| 53 |
-
MAX_HISTORY = 40
|
| 54 |
-
|
| 55 |
-
#: β HOW MANY SCRIPTS MAY BE RUNNING IN THIS CONTAINER AT ONCE, and it is a REPORTED refusal
|
| 56 |
-
#: rather than a queue. Each run is a real subprocess with a ten-second wall clock; without this,
|
| 57 |
-
#: holding down refresh forks until the box gives up, and the tenant's ONE FastAPI process is what
|
| 58 |
-
#: gives up. A 429 that says so is honest; an unbounded fork is not.
|
| 59 |
-
MAX_CONCURRENT_RUNS = 4
|
| 60 |
-
_RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
|
| 61 |
-
|
| 62 |
-
|
| 63 |
-
def _now():
|
| 64 |
-
return datetime.now(timezone.utc).isoformat(timespec="seconds")
|
| 65 |
-
|
| 66 |
-
|
| 67 |
-
def _all(rt):
|
| 68 |
-
"""`{id: record}` for one tenant. `{}` on any failure β an unreadable bucket must degrade to
|
| 69 |
-
"this database has no script views", never to a 500 on the view rail."""
|
| 70 |
-
try:
|
| 71 |
-
found = rt.get(VIEWS_KEY) or {}
|
| 72 |
-
except Exception: # noqa: BLE001
|
| 73 |
-
return {}
|
| 74 |
-
return found if isinstance(found, dict) else {}
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
def _database_ok(session, database):
|
| 78 |
-
"""Does this database EXIST, and may this caller read it? Answered by C1, never by a list.
|
| 79 |
-
|
| 80 |
-
β `perm_scope.may_read` ALONE IS NOT ENOUGH and the reason is easy to miss: it answers True
|
| 81 |
-
for an ADMIN on any key at all, including one no database answers to. So a create validated
|
| 82 |
-
with `may_read` would let an administrator bind a view to a typo and leave an orphan nothing
|
| 83 |
-
can ever run. `scoped_fields` is the cheap half of C1 (a `ut_*` definition, no rows) and it
|
| 84 |
-
RAISES `UnknownTable`, which is exactly the question being asked.
|
| 85 |
-
"""
|
| 86 |
-
import core.perm_scope as perm_scope
|
| 87 |
-
try:
|
| 88 |
-
perm_scope.scoped_fields(session.user, database, st=session.runtime)
|
| 89 |
-
except perm_scope.UnknownTable:
|
| 90 |
-
raise err(404, "no_database", f"there is no database '{database}' in this workspace")
|
| 91 |
-
except perm_scope.Denied:
|
| 92 |
-
raise err(403, "forbidden", f"your account may not read '{database}'")
|
| 93 |
-
except perm_scope.Unresolvable as exc:
|
| 94 |
-
# The database is real and cannot be served under this call's constraints. Standing rule
|
| 95 |
-
# 1's second sentence: report the cause and the recommendation, never a bare refusal.
|
| 96 |
-
raise err(409, "unresolvable", str(exc)) from None
|
| 97 |
-
|
| 98 |
-
|
| 99 |
-
def _clean_source(raw, *, allow_empty=False):
|
| 100 |
-
"""The stored source, or a 400. `allow_empty` is CREATE's alone and the asymmetry is the point.
|
| 101 |
-
|
| 102 |
-
ββ W37-T41 β WHY CREATE MAY BE EMPTY AND SAVE MAY NOT.
|
| 103 |
-
Picking "Custom View" in the mode picker mints the view immediately, before a line of code
|
| 104 |
-
exists, so that `mode === 'script'` always implies a real id and no reader has to carry a
|
| 105 |
-
"the id might be missing" branch (the create semantics handed to lane C in mailbox E-7).
|
| 106 |
-
A view that has been created and not yet written is therefore a REAL, legible state: the editor
|
| 107 |
-
shows its starter placeholder and the Run control is right there.
|
| 108 |
-
A PUT is a different act. It appends a VERSION to a history capped at 40, and blanking a
|
| 109 |
-
working script by saving nothing over it is not an edit anybody means to make. So the guard
|
| 110 |
-
stays exactly where it was on that door, and a person who wants the view gone deletes it.
|
| 111 |
-
|
| 112 |
-
β THIS WAS FOUND BY THE GATE, NOT BY READING. `core.script_sandbox.check_source("")` returns
|
| 113 |
-
None, so "an empty script is storable" looked true and was written into a mailbox answer another
|
| 114 |
-
lane was about to build on. The refusal was HERE, one layer above, in a function the sandbox
|
| 115 |
-
knows nothing about. Two validators for one question, disagreeing
|
| 116 |
-
[[one-question-two-normalizers]] β and the one that would have bitten a person is the one no
|
| 117 |
-
unit of this feature was asserting.
|
| 118 |
-
"""
|
| 119 |
-
source = str(raw or "")
|
| 120 |
-
if not source.strip() and not allow_empty:
|
| 121 |
-
raise err(400, "no_source", "a script view needs some code")
|
| 122 |
-
if len(source.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
|
| 123 |
-
raise err(413, "source_too_long",
|
| 124 |
-
f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of code")
|
| 125 |
-
return source
|
| 126 |
-
|
| 127 |
-
|
| 128 |
-
def _row(rec, *, source=False):
|
| 129 |
-
"""One view as the list door reports it. β NO SOURCE unless asked: the rail lists names."""
|
| 130 |
-
out = {"id": rec.get("id") or "", "database": rec.get("database") or "",
|
| 131 |
-
"name": rec.get("name") or "", "author": rec.get("author") or "",
|
| 132 |
-
"version": int(rec.get("version") or 1),
|
| 133 |
-
"created": rec.get("created") or "", "updated": rec.get("updated") or "",
|
| 134 |
-
"versions": len(rec.get("history") or []) + 1,
|
| 135 |
-
"trimmed": int(rec.get("trimmed") or 0),
|
| 136 |
-
# β W37-T46: which version this one was RESTORED from, when it was. Present on the
|
| 137 |
-
# row (not only the history) because the editor's header is where a person reads "what
|
| 138 |
-
# am I looking at", and "v5, restored from v2" is the sentence that makes a roll-back
|
| 139 |
-
# legible as an event rather than as a coincidence of matching code.
|
| 140 |
-
"restoredFrom": rec.get("restoredFrom")}
|
| 141 |
-
if source:
|
| 142 |
-
out["source"] = rec.get("source") or ""
|
| 143 |
-
out["history"] = [{"version": int(h.get("version") or 0), "author": h.get("author") or "",
|
| 144 |
-
"created": h.get("created") or "",
|
| 145 |
-
"bytes": len(str(h.get("source") or "").encode("utf-8", "replace"))}
|
| 146 |
-
for h in reversed(rec.get("history") or []) if isinstance(h, dict)]
|
| 147 |
-
return out
|
| 148 |
-
|
| 149 |
-
|
| 150 |
-
def _limits():
|
| 151 |
-
return {"maxSourceBytes": MAX_SOURCE_BYTES, "maxName": MAX_NAME,
|
| 152 |
-
"maxHistory": MAX_HISTORY, "maxConcurrentRuns": MAX_CONCURRENT_RUNS,
|
| 153 |
-
# β SAID OUT LOUD, because R3's "not capped" half is the one a reader assumes wrong.
|
| 154 |
-
"maxViewsPerDatabase": None}
|
| 155 |
-
|
| 156 |
-
|
| 157 |
-
def _put(session, view_id, mutate):
|
| 158 |
-
"""Read-modify-write ONE view, synchronously β the client re-reads the rail immediately."""
|
| 159 |
-
def _set(cur):
|
| 160 |
-
cur = dict(cur or {})
|
| 161 |
-
nxt = mutate(cur.get(view_id) if isinstance(cur.get(view_id), dict) else None)
|
| 162 |
-
if nxt is None:
|
| 163 |
-
cur.pop(view_id, None)
|
| 164 |
-
else:
|
| 165 |
-
cur[view_id] = nxt
|
| 166 |
-
return cur
|
| 167 |
-
|
| 168 |
-
session.runtime.update(VIEWS_KEY, _set, flush="sync")
|
| 169 |
-
|
| 170 |
-
|
| 171 |
-
def _mine_or_admin(session, rec):
|
| 172 |
-
"""Who may EDIT or DELETE a view: its author, or an administrator.
|
| 173 |
-
|
| 174 |
-
β RUNNING IS A DIFFERENT QUESTION and deliberately wider β anybody who may read the database
|
| 175 |
-
may run any view on it, under their OWN scope. That is the whole of "so we can see different
|
| 176 |
-
versions or different things the AI code for us": a colleague's attempt is worth nothing if
|
| 177 |
-
only its author can open it.
|
| 178 |
-
"""
|
| 179 |
-
if session.admin or str(rec.get("author") or "") == session.uname:
|
| 180 |
-
return
|
| 181 |
-
raise err(403, "forbidden", "only the author or an administrator can change this script view")
|
| 182 |
-
|
| 183 |
-
|
| 184 |
-
# ββ the routes βββββββββββββββββββββββ
|
| 185 |
-
@router.get("/script-views")
|
| 186 |
-
def list_script_views(database: str = "", session: Session = Depends(require_session)):
|
| 187 |
-
"""Every script view bound to ONE database, newest first. `database` is required."""
|
| 188 |
-
key = str(database or "").strip()
|
| 189 |
-
if not key:
|
| 190 |
-
raise err(400, "no_database", "name the database whose script views you want")
|
| 191 |
-
_database_ok(session, key)
|
| 192 |
-
rows = [_row(rec) for rec in _all(session.runtime).values()
|
| 193 |
-
if isinstance(rec, dict) and str(rec.get("database") or "") == key]
|
| 194 |
-
rows.sort(key=lambda r: (r["created"], r["id"]), reverse=True)
|
| 195 |
-
return {"database": key, "views": rows, "limits": _limits()}
|
| 196 |
-
|
| 197 |
-
|
| 198 |
-
@router.post("/script-views")
|
| 199 |
-
def create_script_view(body: dict = Body(default=None),
|
| 200 |
-
session: Session = Depends(require_session)):
|
| 201 |
-
"""Create one. β THE SOURCE IS CHECKED BEFORE IT IS STORED, not first at run time.
|
| 202 |
-
|
| 203 |
-
A script view that cannot be run is a broken feature the reader discovers by pressing a button,
|
| 204 |
-
and the agent that wrote it is long gone by then. `check_source` is pure and costs no process,
|
| 205 |
-
so the refusal arrives while the author still has the code in front of them.
|
| 206 |
-
"""
|
| 207 |
-
import secrets # noqa: PLC0415
|
| 208 |
-
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 209 |
-
|
| 210 |
-
body = body if isinstance(body, dict) else {}
|
| 211 |
-
database = str(body.get("database") or "").strip()
|
| 212 |
-
if not database:
|
| 213 |
-
raise err(400, "no_database", "a script view is bound to one database")
|
| 214 |
-
_database_ok(session, database)
|
| 215 |
-
# β `allow_empty` is CREATE's alone - see `_clean_source`. The picker mints a view the
|
| 216 |
-
# moment a person chooses the mode, so the empty source is the normal first state, not a slip.
|
| 217 |
-
source = _clean_source(body.get("source"), allow_empty=True)
|
| 218 |
-
refusal = sandbox.check_source(source)
|
| 219 |
-
if refusal is not None:
|
| 220 |
-
raise err(400, refusal.code, refusal.message)
|
| 221 |
-
|
| 222 |
-
view_id = "sv_" + secrets.token_urlsafe(9)
|
| 223 |
-
rec = {"id": view_id, "database": database,
|
| 224 |
-
"name": " ".join(str(body.get("name") or "Script view").split())[:MAX_NAME],
|
| 225 |
-
"source": source, "author": session.uname, "version": 1,
|
| 226 |
-
"created": _now(), "updated": _now(), "history": [], "trimmed": 0}
|
| 227 |
-
_put(session, view_id, lambda _prior: rec)
|
| 228 |
-
fresh = _all(session.runtime).get(view_id)
|
| 229 |
-
if not isinstance(fresh, dict):
|
| 230 |
-
# The store took the write and did not record it. A 200 here would tell the author their
|
| 231 |
-
# script was saved when it was not.
|
| 232 |
-
raise err(503, "store_unavailable", "the script view was NOT created")
|
| 233 |
-
return {"view": _row(fresh, source=True), "limits": _limits()}
|
| 234 |
-
|
| 235 |
-
|
| 236 |
-
@router.get("/script-views/{view_id}")
|
| 237 |
-
def get_script_view(view_id: str, session: Session = Depends(require_session)):
|
| 238 |
-
"""One view WITH its source and its edit history. Owner item 6's *"see the code"* half."""
|
| 239 |
-
rec = _all(session.runtime).get(str(view_id))
|
| 240 |
-
if not isinstance(rec, dict):
|
| 241 |
-
raise err(404, "no_view", "there is no script view with that id")
|
| 242 |
-
_database_ok(session, str(rec.get("database") or ""))
|
| 243 |
-
return {"view": _row(rec, source=True), "limits": _limits()}
|
| 244 |
-
|
| 245 |
-
|
| 246 |
-
@router.put("/script-views/{view_id}")
|
| 247 |
-
def update_script_view(view_id: str, body: dict = Body(default=None),
|
| 248 |
-
session: Session = Depends(require_session)):
|
| 249 |
-
"""A NEW VERSION of one view's source. The prior source is KEPT, never replaced in place."""
|
| 250 |
-
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 251 |
-
|
| 252 |
-
view_id = str(view_id)
|
| 253 |
-
rec = _all(session.runtime).get(view_id)
|
| 254 |
-
if not isinstance(rec, dict):
|
| 255 |
-
raise err(404, "no_view", "there is no script view with that id")
|
| 256 |
-
_mine_or_admin(session, rec)
|
| 257 |
-
body = body if isinstance(body, dict) else {}
|
| 258 |
-
source = _clean_source(body.get("source"))
|
| 259 |
-
refusal = sandbox.check_source(source)
|
| 260 |
-
if refusal is not None:
|
| 261 |
-
raise err(400, refusal.code, refusal.message)
|
| 262 |
-
|
| 263 |
-
def _mutate(prior):
|
| 264 |
-
prior = dict(prior or rec)
|
| 265 |
-
history = list(prior.get("history") or [])
|
| 266 |
-
history.append({"version": int(prior.get("version") or 1),
|
| 267 |
-
"source": prior.get("source") or "",
|
| 268 |
-
"author": prior.get("author") or "", "created": prior.get("updated") or ""})
|
| 269 |
-
dropped = max(0, len(history) - MAX_HISTORY)
|
| 270 |
-
prior["history"] = history[dropped:] if dropped else history
|
| 271 |
-
prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
|
| 272 |
-
prior["source"] = source
|
| 273 |
-
prior["version"] = int(prior.get("version") or 1) + 1
|
| 274 |
-
prior["updated"] = _now()
|
| 275 |
-
if body.get("name"):
|
| 276 |
-
prior["name"] = " ".join(str(body["name"]).split())[:MAX_NAME]
|
| 277 |
-
return prior
|
| 278 |
-
|
| 279 |
-
_put(session, view_id, _mutate)
|
| 280 |
-
fresh = _all(session.runtime).get(view_id)
|
| 281 |
-
if not isinstance(fresh, dict):
|
| 282 |
-
raise err(503, "store_unavailable", "the new version was NOT saved")
|
| 283 |
-
return {"view": _row(fresh, source=True), "limits": _limits()}
|
| 284 |
-
|
| 285 |
-
|
| 286 |
-
@router.post("/script-views/{view_id}/revert")
|
| 287 |
-
def revert_script_view(view_id: str, body: dict = Body(default=None),
|
| 288 |
-
session: Session = Depends(require_session)):
|
| 289 |
-
"""Put one view back to an earlier version. D-338 / W37-T46.
|
| 290 |
-
|
| 291 |
-
ββ A ROLL-BACK IS A NEW VERSION, NEVER A DELETE OF THE ONES AFTER IT, and that is the whole
|
| 292 |
-
point of the ticket rather than an implementation detail. The history is what lets a person
|
| 293 |
-
trust an agent with their code: if reverting destroyed the versions it stepped over, one
|
| 294 |
-
mistaken revert would cost exactly what the history existed to protect, and there would be no
|
| 295 |
-
way back from the way back. So this appends, and `restoredFrom` records where the text came
|
| 296 |
-
from β the same posture the agent-harness roll-back already takes, so a reader who has seen one
|
| 297 |
-
is not surprised by the other.
|
| 298 |
-
|
| 299 |
-
β IT LIVES ON THE SERVER BECAUSE THE HISTORY DOES. The list door deliberately serves history
|
| 300 |
-
entries WITHOUT their source (`_row`: the rail lists names), so a client cannot assemble an old
|
| 301 |
-
version's text to re-PUT it. Handing the source out just so the client could send it straight
|
| 302 |
-
back would widen a payload for a round trip that does not need to exist, and would make the
|
| 303 |
-
revert non-atomic: two calls, and a failure between them leaves the person looking at code that
|
| 304 |
-
is not what is stored.
|
| 305 |
-
β `_clean_source` is NOT re-run. The text being restored was already validated when it was
|
| 306 |
-
first saved, and a source that a later, stricter rule would now reject is exactly the source a
|
| 307 |
-
person is most likely to want back. `check_source` still runs, because the SANDBOX's refusal is
|
| 308 |
-
about what the code would DO and that must never be bypassed by a route.
|
| 309 |
-
"""
|
| 310 |
-
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 311 |
-
|
| 312 |
-
view_id = str(view_id)
|
| 313 |
-
rec = _all(session.runtime).get(view_id)
|
| 314 |
-
if not isinstance(rec, dict):
|
| 315 |
-
raise err(404, "no_view", "there is no script view with that id")
|
| 316 |
-
_mine_or_admin(session, rec)
|
| 317 |
-
body = body if isinstance(body, dict) else {}
|
| 318 |
-
try:
|
| 319 |
-
want = int(body.get("version"))
|
| 320 |
-
except (TypeError, ValueError):
|
| 321 |
-
raise err(400, "no_version", "say which version to go back to") from None
|
| 322 |
-
|
| 323 |
-
history = [h for h in (rec.get("history") or []) if isinstance(h, dict)]
|
| 324 |
-
match = next((h for h in history if int(h.get("version") or 0) == want), None)
|
| 325 |
-
if match is None:
|
| 326 |
-
# β TWO REASONS A VERSION IS MISSING AND THEY ARE NOT THE SAME FACT. One was never
|
| 327 |
-
# written; the other was TRIMMED off the 40-deep history and the record even counts how
|
| 328 |
-
# many. Saying "that version is gone" for the first would be a lie a person could act on.
|
| 329 |
-
trimmed = int(rec.get("trimmed") or 0)
|
| 330 |
-
if trimmed and want <= trimmed:
|
| 331 |
-
raise err(410, "version_trimmed",
|
| 332 |
-
f"version {want} is older than this view's history keeps "
|
| 333 |
-
f"({trimmed} earlier versions have been dropped)")
|
| 334 |
-
raise err(404, "no_version", f"this view has no version {want}")
|
| 335 |
-
|
| 336 |
-
source = str(match.get("source") or "")
|
| 337 |
-
refusal = sandbox.check_source(source)
|
| 338 |
-
if refusal is not None:
|
| 339 |
-
# An older version that today's sandbox refuses. The person is told which version and why,
|
| 340 |
-
# rather than being handed a 400 about code they did not just type.
|
| 341 |
-
raise err(400, refusal.code, f"version {want} cannot be restored: {refusal.message}")
|
| 342 |
-
|
| 343 |
-
def _mutate(prior):
|
| 344 |
-
prior = dict(prior or rec)
|
| 345 |
-
history_now = list(prior.get("history") or [])
|
| 346 |
-
history_now.append({"version": int(prior.get("version") or 1),
|
| 347 |
-
"source": prior.get("source") or "",
|
| 348 |
-
"author": prior.get("author") or "",
|
| 349 |
-
"created": prior.get("updated") or ""})
|
| 350 |
-
dropped = max(0, len(history_now) - MAX_HISTORY)
|
| 351 |
-
prior["history"] = history_now[dropped:] if dropped else history_now
|
| 352 |
-
prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
|
| 353 |
-
prior["source"] = source
|
| 354 |
-
prior["version"] = int(prior.get("version") or 1) + 1
|
| 355 |
-
prior["updated"] = _now()
|
| 356 |
-
# β ON THE RECORD, so the history reads as WHAT HAPPENED rather than as a version that
|
| 357 |
-
# mysteriously matches an older one. Without it a reader sees v5 and v2 with identical
|
| 358 |
-
# code and no way to tell a revert from a coincidence.
|
| 359 |
-
prior["restoredFrom"] = want
|
| 360 |
-
return prior
|
| 361 |
-
|
| 362 |
-
_put(session, view_id, _mutate)
|
| 363 |
-
fresh = _all(session.runtime).get(view_id)
|
| 364 |
-
if not isinstance(fresh, dict):
|
| 365 |
-
raise err(503, "store_unavailable", "the roll-back was NOT saved")
|
| 366 |
-
return {"view": _row(fresh, source=True), "restoredFrom": want, "limits": _limits()}
|
| 367 |
-
|
| 368 |
-
|
| 369 |
-
@router.delete("/script-views/{view_id}")
|
| 370 |
-
def delete_script_view(view_id: str, session: Session = Depends(require_session)):
|
| 371 |
-
view_id = str(view_id)
|
| 372 |
-
rec = _all(session.runtime).get(view_id)
|
| 373 |
-
if not isinstance(rec, dict):
|
| 374 |
-
raise err(404, "no_view", "there is no script view with that id")
|
| 375 |
-
_mine_or_admin(session, rec)
|
| 376 |
-
_put(session, view_id, lambda _prior: None)
|
| 377 |
-
return {"deleted": view_id}
|
| 378 |
-
|
| 379 |
-
|
| 380 |
-
@router.post("/script-views/{view_id}/run")
|
| 381 |
-
def run_script_view(view_id: str, body: dict = Body(default=None),
|
| 382 |
-
session: Session = Depends(require_session)):
|
| 383 |
-
"""CONTRACT C3's run door: `{ok, spec | error, stdout, ms}`.
|
| 384 |
-
|
| 385 |
-
β `spec` IS A DESCRIPTION THE CLIENT DRAWS. It is never HTML and never text the browser
|
| 386 |
-
executes β the sandbox refuses a spec carrying an `html`, `script`, `src`, `href` or `on*` key
|
| 387 |
-
before this function ever sees it, so a renderer cannot be talked into running something by a
|
| 388 |
-
script that was itself perfectly well behaved.
|
| 389 |
-
|
| 390 |
-
β AND IT IS PLAIN `def`, NOT `async def` β see this module's header. A ten-second subprocess
|
| 391 |
-
wait on the event loop is a ten-second outage for the whole container.
|
| 392 |
-
"""
|
| 393 |
-
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 394 |
-
|
| 395 |
-
rec = _all(session.runtime).get(str(view_id))
|
| 396 |
-
if not isinstance(rec, dict):
|
| 397 |
-
raise err(404, "no_view", "there is no script view with that id")
|
| 398 |
-
database = str(rec.get("database") or "")
|
| 399 |
-
# A DRAFT run: the editor sends unsaved code so the author can try it before committing to it.
|
| 400 |
-
# It is checked exactly as a stored one is, because "unsaved" is not a permission.
|
| 401 |
-
draft = (body or {}).get("source") if isinstance(body, dict) else None
|
| 402 |
-
source = _clean_source(draft) if draft else str(rec.get("source") or "")
|
| 403 |
-
# β NO `_database_ok` CALL HERE. `run_view` asks C1 the identical question a line later, and
|
| 404 |
-
# asking twice builds a registry topic's pool twice. The three refusals are translated below
|
| 405 |
-
# instead, which is the same wall reached through the same door.
|
| 406 |
-
|
| 407 |
-
if not _RUN_SLOTS.acquire(blocking=False):
|
| 408 |
-
raise err(429, "busy",
|
| 409 |
-
f"{MAX_CONCURRENT_RUNS} script views are already running on this server. "
|
| 410 |
-
f"Try again in a moment")
|
| 411 |
-
try:
|
| 412 |
-
out = sandbox.run_view(session.user, database, source, st=session.runtime)
|
| 413 |
-
finally:
|
| 414 |
-
_RUN_SLOTS.release()
|
| 415 |
-
|
| 416 |
-
# β C1'S THREE REFUSALS ARE HTTP STATUSES, NOT `ok:false`. "You may not read this database"
|
| 417 |
-
# answered 200 would be a permission decision the client has to go looking for, and every
|
| 418 |
-
# other door in this app answers 403 for it. Everything BELOW this line is a well-formed
|
| 419 |
-
# request whose ANSWER is that the script did not produce a view β that is a 200 with
|
| 420 |
-
# `ok:false`, the shape `routes_web_agent.test` already uses for the same reason.
|
| 421 |
-
if out.get("code") == "unknown_table":
|
| 422 |
-
raise err(404, "no_database", out.get("message") or f"there is no database '{database}'")
|
| 423 |
-
if out.get("code") == "denied":
|
| 424 |
-
raise err(403, "forbidden", out.get("message") or "your account may not read that database")
|
| 425 |
-
if out.get("code") == "unresolvable":
|
| 426 |
-
refusal = err(409, "unresolvable", out.get("message") or "these rows cannot be served")
|
| 427 |
-
refusal.detail["error"]["limit"] = out.get("limit") or {}
|
| 428 |
-
raise refusal
|
| 429 |
-
|
| 430 |
-
answer = {"ok": bool(out.get("ok")), "spec": out.get("spec"),
|
| 431 |
-
"stdout": out.get("stdout") or "", "truncated": bool(out.get("truncated")),
|
| 432 |
-
"ms": int(out.get("ms") or 0), "code": out.get("code") or "",
|
| 433 |
-
# β `caps` RIDES ON THE ANSWER (standing rule 1). On a POSIX host all three limits
|
| 434 |
-
# were applied; on a Windows host the memory and CPU ones were not, and a screen
|
| 435 |
-
# that claims an enforcement which did not happen is the failure the rule is about.
|
| 436 |
-
"caps": out.get("caps") or {}}
|
| 437 |
-
if not answer["ok"]:
|
| 438 |
-
answer["error"] = out.get("message") or "the script view did not produce a view"
|
| 439 |
-
return answer
|
|
|
|
| 1 |
+
"""routes_script_views.py β CONTRACT C3: a database View that is a PYTHON SCRIPT (R3 / R5 / R10).
|
| 2 |
+
|
| 3 |
+
Owner item 6, verbatim (2026-08-18): *"Add code script as an interface (database View) so a user
|
| 4 |
+
can build whatever they want through the Agent chat interface. be able to create any dashboard
|
| 5 |
+
they want. User should have the ability to see the code AND the dashboard output of course⦠Limit
|
| 6 |
+
the code script View per database⦠Any agent can add into more AI script, so we can see different
|
| 7 |
+
versions or different things the AI code for us."*
|
| 8 |
+
|
| 9 |
+
GET /api/v1/script-views?database=K the views bound to ONE database
|
| 10 |
+
POST /api/v1/script-views create one {database, name?, source}
|
| 11 |
+
GET /api/v1/script-views/{id} one view, its source and its history
|
| 12 |
+
PUT /api/v1/script-views/{id} a NEW VERSION of the source
|
| 13 |
+
DELETE /api/v1/script-views/{id} drop it
|
| 14 |
+
POST /api/v1/script-views/{id}/run run it -> {ok, spec | error, stdout, ms}
|
| 15 |
+
POST /api/v1/script-views/{id}/revert go back to an earlier version {version}
|
| 16 |
+
|
| 17 |
+
ββ **R3 IS "SCOPED, NOT CAPPED", AND THE TWO HALVES POINT OPPOSITE WAYS.** *Scoped*: a view may
|
| 18 |
+
read ONLY the database it lives in, and a script that names another database is REFUSED with a
|
| 19 |
+
message naming both. *Not capped*: there is **no limit on how many script views a database may
|
| 20 |
+
carry**, because that is how an agent offers three attempts and the owner picks one. So nothing
|
| 21 |
+
below counts views. What IS bounded is what makes them big β one source is capped, and one view's
|
| 22 |
+
edit history is capped and REPORTS what it dropped.
|
| 23 |
+
|
| 24 |
+
β **THE RUN IS THE CALLER'S, NEVER THE AUTHOR'S (R5).** `script_sandbox.run_view` is handed
|
| 25 |
+
`session.user`, so a script written by an administrator and opened by a scoped analyst reads the
|
| 26 |
+
ANALYST's rows. The author decides what the code does; the reader decides what it can see.
|
| 27 |
+
β And the reverse case is safe rather than lucky: a narrowly-scoped author cannot write a script
|
| 28 |
+
that exfiltrates anything, because the only thing a script can return is a render spec drawn on
|
| 29 |
+
the screen of the person who ran it. There is no network, no file and no second reader.
|
| 30 |
+
|
| 31 |
+
β **`run` IS `def`, NOT `async def`.** It waits on a subprocess for up to ten seconds; as a
|
| 32 |
+
coroutine that would block the event loop for every other request in the container. FastAPI runs a
|
| 33 |
+
plain `def` in the threadpool, which is what makes one slow script one slow REQUEST.
|
| 34 |
+
"""
|
| 35 |
+
import threading
|
| 36 |
+
from datetime import datetime, timezone
|
| 37 |
+
|
| 38 |
+
from fastapi import APIRouter, Body, Depends
|
| 39 |
+
|
| 40 |
+
from deps import Session, err, require_session
|
| 41 |
+
|
| 42 |
+
router = APIRouter(prefix="/api/v1")
|
| 43 |
+
|
| 44 |
+
#: The tenant's script views: `{id: record}`. Per tenant, so it rides `runtime.store_key`.
|
| 45 |
+
VIEWS_KEY = "script_views"
|
| 46 |
+
|
| 47 |
+
MAX_NAME = 80
|
| 48 |
+
MAX_SOURCE_BYTES = 128 * 1024
|
| 49 |
+
|
| 50 |
+
#: Edit history per view. β NOT a cap on the NUMBER of views (R3 forbids that) β a cap on how far
|
| 51 |
+
#: back ONE view's source is kept. Past this the oldest go and `trimmed` counts them, so a reader
|
| 52 |
+
#: can see the history is partial instead of concluding the view was only ever saved twice.
|
| 53 |
+
MAX_HISTORY = 40
|
| 54 |
+
|
| 55 |
+
#: β HOW MANY SCRIPTS MAY BE RUNNING IN THIS CONTAINER AT ONCE, and it is a REPORTED refusal
|
| 56 |
+
#: rather than a queue. Each run is a real subprocess with a ten-second wall clock; without this,
|
| 57 |
+
#: holding down refresh forks until the box gives up, and the tenant's ONE FastAPI process is what
|
| 58 |
+
#: gives up. A 429 that says so is honest; an unbounded fork is not.
|
| 59 |
+
MAX_CONCURRENT_RUNS = 4
|
| 60 |
+
_RUN_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_RUNS)
|
| 61 |
+
|
| 62 |
+
|
| 63 |
+
def _now():
|
| 64 |
+
return datetime.now(timezone.utc).isoformat(timespec="seconds")
|
| 65 |
+
|
| 66 |
+
|
| 67 |
+
def _all(rt):
|
| 68 |
+
"""`{id: record}` for one tenant. `{}` on any failure β an unreadable bucket must degrade to
|
| 69 |
+
"this database has no script views", never to a 500 on the view rail."""
|
| 70 |
+
try:
|
| 71 |
+
found = rt.get(VIEWS_KEY) or {}
|
| 72 |
+
except Exception: # noqa: BLE001
|
| 73 |
+
return {}
|
| 74 |
+
return found if isinstance(found, dict) else {}
|
| 75 |
+
|
| 76 |
+
|
| 77 |
+
def _database_ok(session, database):
|
| 78 |
+
"""Does this database EXIST, and may this caller read it? Answered by C1, never by a list.
|
| 79 |
+
|
| 80 |
+
β `perm_scope.may_read` ALONE IS NOT ENOUGH and the reason is easy to miss: it answers True
|
| 81 |
+
for an ADMIN on any key at all, including one no database answers to. So a create validated
|
| 82 |
+
with `may_read` would let an administrator bind a view to a typo and leave an orphan nothing
|
| 83 |
+
can ever run. `scoped_fields` is the cheap half of C1 (a `ut_*` definition, no rows) and it
|
| 84 |
+
RAISES `UnknownTable`, which is exactly the question being asked.
|
| 85 |
+
"""
|
| 86 |
+
import core.perm_scope as perm_scope
|
| 87 |
+
try:
|
| 88 |
+
perm_scope.scoped_fields(session.user, database, st=session.runtime)
|
| 89 |
+
except perm_scope.UnknownTable:
|
| 90 |
+
raise err(404, "no_database", f"there is no database '{database}' in this workspace")
|
| 91 |
+
except perm_scope.Denied:
|
| 92 |
+
raise err(403, "forbidden", f"your account may not read '{database}'")
|
| 93 |
+
except perm_scope.Unresolvable as exc:
|
| 94 |
+
# The database is real and cannot be served under this call's constraints. Standing rule
|
| 95 |
+
# 1's second sentence: report the cause and the recommendation, never a bare refusal.
|
| 96 |
+
raise err(409, "unresolvable", str(exc)) from None
|
| 97 |
+
|
| 98 |
+
|
| 99 |
+
def _clean_source(raw, *, allow_empty=False):
|
| 100 |
+
"""The stored source, or a 400. `allow_empty` is CREATE's alone and the asymmetry is the point.
|
| 101 |
+
|
| 102 |
+
ββ W37-T41 β WHY CREATE MAY BE EMPTY AND SAVE MAY NOT.
|
| 103 |
+
Picking "Custom View" in the mode picker mints the view immediately, before a line of code
|
| 104 |
+
exists, so that `mode === 'script'` always implies a real id and no reader has to carry a
|
| 105 |
+
"the id might be missing" branch (the create semantics handed to lane C in mailbox E-7).
|
| 106 |
+
A view that has been created and not yet written is therefore a REAL, legible state: the editor
|
| 107 |
+
shows its starter placeholder and the Run control is right there.
|
| 108 |
+
A PUT is a different act. It appends a VERSION to a history capped at 40, and blanking a
|
| 109 |
+
working script by saving nothing over it is not an edit anybody means to make. So the guard
|
| 110 |
+
stays exactly where it was on that door, and a person who wants the view gone deletes it.
|
| 111 |
+
|
| 112 |
+
β THIS WAS FOUND BY THE GATE, NOT BY READING. `core.script_sandbox.check_source("")` returns
|
| 113 |
+
None, so "an empty script is storable" looked true and was written into a mailbox answer another
|
| 114 |
+
lane was about to build on. The refusal was HERE, one layer above, in a function the sandbox
|
| 115 |
+
knows nothing about. Two validators for one question, disagreeing
|
| 116 |
+
[[one-question-two-normalizers]] β and the one that would have bitten a person is the one no
|
| 117 |
+
unit of this feature was asserting.
|
| 118 |
+
"""
|
| 119 |
+
source = str(raw or "")
|
| 120 |
+
if not source.strip() and not allow_empty:
|
| 121 |
+
raise err(400, "no_source", "a script view needs some code")
|
| 122 |
+
if len(source.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
|
| 123 |
+
raise err(413, "source_too_long",
|
| 124 |
+
f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of code")
|
| 125 |
+
return source
|
| 126 |
+
|
| 127 |
+
|
| 128 |
+
def _row(rec, *, source=False):
|
| 129 |
+
"""One view as the list door reports it. β NO SOURCE unless asked: the rail lists names."""
|
| 130 |
+
out = {"id": rec.get("id") or "", "database": rec.get("database") or "",
|
| 131 |
+
"name": rec.get("name") or "", "author": rec.get("author") or "",
|
| 132 |
+
"version": int(rec.get("version") or 1),
|
| 133 |
+
"created": rec.get("created") or "", "updated": rec.get("updated") or "",
|
| 134 |
+
"versions": len(rec.get("history") or []) + 1,
|
| 135 |
+
"trimmed": int(rec.get("trimmed") or 0),
|
| 136 |
+
# β W37-T46: which version this one was RESTORED from, when it was. Present on the
|
| 137 |
+
# row (not only the history) because the editor's header is where a person reads "what
|
| 138 |
+
# am I looking at", and "v5, restored from v2" is the sentence that makes a roll-back
|
| 139 |
+
# legible as an event rather than as a coincidence of matching code.
|
| 140 |
+
"restoredFrom": rec.get("restoredFrom")}
|
| 141 |
+
if source:
|
| 142 |
+
out["source"] = rec.get("source") or ""
|
| 143 |
+
out["history"] = [{"version": int(h.get("version") or 0), "author": h.get("author") or "",
|
| 144 |
+
"created": h.get("created") or "",
|
| 145 |
+
"bytes": len(str(h.get("source") or "").encode("utf-8", "replace"))}
|
| 146 |
+
for h in reversed(rec.get("history") or []) if isinstance(h, dict)]
|
| 147 |
+
return out
|
| 148 |
+
|
| 149 |
+
|
| 150 |
+
def _limits():
|
| 151 |
+
return {"maxSourceBytes": MAX_SOURCE_BYTES, "maxName": MAX_NAME,
|
| 152 |
+
"maxHistory": MAX_HISTORY, "maxConcurrentRuns": MAX_CONCURRENT_RUNS,
|
| 153 |
+
# β SAID OUT LOUD, because R3's "not capped" half is the one a reader assumes wrong.
|
| 154 |
+
"maxViewsPerDatabase": None}
|
| 155 |
+
|
| 156 |
+
|
| 157 |
+
def _put(session, view_id, mutate):
|
| 158 |
+
"""Read-modify-write ONE view, synchronously β the client re-reads the rail immediately."""
|
| 159 |
+
def _set(cur):
|
| 160 |
+
cur = dict(cur or {})
|
| 161 |
+
nxt = mutate(cur.get(view_id) if isinstance(cur.get(view_id), dict) else None)
|
| 162 |
+
if nxt is None:
|
| 163 |
+
cur.pop(view_id, None)
|
| 164 |
+
else:
|
| 165 |
+
cur[view_id] = nxt
|
| 166 |
+
return cur
|
| 167 |
+
|
| 168 |
+
session.runtime.update(VIEWS_KEY, _set, flush="sync")
|
| 169 |
+
|
| 170 |
+
|
| 171 |
+
def _mine_or_admin(session, rec):
|
| 172 |
+
"""Who may EDIT or DELETE a view: its author, or an administrator.
|
| 173 |
+
|
| 174 |
+
β RUNNING IS A DIFFERENT QUESTION and deliberately wider β anybody who may read the database
|
| 175 |
+
may run any view on it, under their OWN scope. That is the whole of "so we can see different
|
| 176 |
+
versions or different things the AI code for us": a colleague's attempt is worth nothing if
|
| 177 |
+
only its author can open it.
|
| 178 |
+
"""
|
| 179 |
+
if session.admin or str(rec.get("author") or "") == session.uname:
|
| 180 |
+
return
|
| 181 |
+
raise err(403, "forbidden", "only the author or an administrator can change this script view")
|
| 182 |
+
|
| 183 |
+
|
| 184 |
+
# ββ the routes ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 185 |
+
@router.get("/script-views")
|
| 186 |
+
def list_script_views(database: str = "", session: Session = Depends(require_session)):
|
| 187 |
+
"""Every script view bound to ONE database, newest first. `database` is required."""
|
| 188 |
+
key = str(database or "").strip()
|
| 189 |
+
if not key:
|
| 190 |
+
raise err(400, "no_database", "name the database whose script views you want")
|
| 191 |
+
_database_ok(session, key)
|
| 192 |
+
rows = [_row(rec) for rec in _all(session.runtime).values()
|
| 193 |
+
if isinstance(rec, dict) and str(rec.get("database") or "") == key]
|
| 194 |
+
rows.sort(key=lambda r: (r["created"], r["id"]), reverse=True)
|
| 195 |
+
return {"database": key, "views": rows, "limits": _limits()}
|
| 196 |
+
|
| 197 |
+
|
| 198 |
+
@router.post("/script-views")
|
| 199 |
+
def create_script_view(body: dict = Body(default=None),
|
| 200 |
+
session: Session = Depends(require_session)):
|
| 201 |
+
"""Create one. β THE SOURCE IS CHECKED BEFORE IT IS STORED, not first at run time.
|
| 202 |
+
|
| 203 |
+
A script view that cannot be run is a broken feature the reader discovers by pressing a button,
|
| 204 |
+
and the agent that wrote it is long gone by then. `check_source` is pure and costs no process,
|
| 205 |
+
so the refusal arrives while the author still has the code in front of them.
|
| 206 |
+
"""
|
| 207 |
+
import secrets # noqa: PLC0415
|
| 208 |
+
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 209 |
+
|
| 210 |
+
body = body if isinstance(body, dict) else {}
|
| 211 |
+
database = str(body.get("database") or "").strip()
|
| 212 |
+
if not database:
|
| 213 |
+
raise err(400, "no_database", "a script view is bound to one database")
|
| 214 |
+
_database_ok(session, database)
|
| 215 |
+
# β `allow_empty` is CREATE's alone - see `_clean_source`. The picker mints a view the
|
| 216 |
+
# moment a person chooses the mode, so the empty source is the normal first state, not a slip.
|
| 217 |
+
source = _clean_source(body.get("source"), allow_empty=True)
|
| 218 |
+
refusal = sandbox.check_source(source)
|
| 219 |
+
if refusal is not None:
|
| 220 |
+
raise err(400, refusal.code, refusal.message)
|
| 221 |
+
|
| 222 |
+
view_id = "sv_" + secrets.token_urlsafe(9)
|
| 223 |
+
rec = {"id": view_id, "database": database,
|
| 224 |
+
"name": " ".join(str(body.get("name") or "Script view").split())[:MAX_NAME],
|
| 225 |
+
"source": source, "author": session.uname, "version": 1,
|
| 226 |
+
"created": _now(), "updated": _now(), "history": [], "trimmed": 0}
|
| 227 |
+
_put(session, view_id, lambda _prior: rec)
|
| 228 |
+
fresh = _all(session.runtime).get(view_id)
|
| 229 |
+
if not isinstance(fresh, dict):
|
| 230 |
+
# The store took the write and did not record it. A 200 here would tell the author their
|
| 231 |
+
# script was saved when it was not.
|
| 232 |
+
raise err(503, "store_unavailable", "the script view was NOT created")
|
| 233 |
+
return {"view": _row(fresh, source=True), "limits": _limits()}
|
| 234 |
+
|
| 235 |
+
|
| 236 |
+
@router.get("/script-views/{view_id}")
|
| 237 |
+
def get_script_view(view_id: str, session: Session = Depends(require_session)):
|
| 238 |
+
"""One view WITH its source and its edit history. Owner item 6's *"see the code"* half."""
|
| 239 |
+
rec = _all(session.runtime).get(str(view_id))
|
| 240 |
+
if not isinstance(rec, dict):
|
| 241 |
+
raise err(404, "no_view", "there is no script view with that id")
|
| 242 |
+
_database_ok(session, str(rec.get("database") or ""))
|
| 243 |
+
return {"view": _row(rec, source=True), "limits": _limits()}
|
| 244 |
+
|
| 245 |
+
|
| 246 |
+
@router.put("/script-views/{view_id}")
|
| 247 |
+
def update_script_view(view_id: str, body: dict = Body(default=None),
|
| 248 |
+
session: Session = Depends(require_session)):
|
| 249 |
+
"""A NEW VERSION of one view's source. The prior source is KEPT, never replaced in place."""
|
| 250 |
+
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 251 |
+
|
| 252 |
+
view_id = str(view_id)
|
| 253 |
+
rec = _all(session.runtime).get(view_id)
|
| 254 |
+
if not isinstance(rec, dict):
|
| 255 |
+
raise err(404, "no_view", "there is no script view with that id")
|
| 256 |
+
_mine_or_admin(session, rec)
|
| 257 |
+
body = body if isinstance(body, dict) else {}
|
| 258 |
+
source = _clean_source(body.get("source"))
|
| 259 |
+
refusal = sandbox.check_source(source)
|
| 260 |
+
if refusal is not None:
|
| 261 |
+
raise err(400, refusal.code, refusal.message)
|
| 262 |
+
|
| 263 |
+
def _mutate(prior):
|
| 264 |
+
prior = dict(prior or rec)
|
| 265 |
+
history = list(prior.get("history") or [])
|
| 266 |
+
history.append({"version": int(prior.get("version") or 1),
|
| 267 |
+
"source": prior.get("source") or "",
|
| 268 |
+
"author": prior.get("author") or "", "created": prior.get("updated") or ""})
|
| 269 |
+
dropped = max(0, len(history) - MAX_HISTORY)
|
| 270 |
+
prior["history"] = history[dropped:] if dropped else history
|
| 271 |
+
prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
|
| 272 |
+
prior["source"] = source
|
| 273 |
+
prior["version"] = int(prior.get("version") or 1) + 1
|
| 274 |
+
prior["updated"] = _now()
|
| 275 |
+
if body.get("name"):
|
| 276 |
+
prior["name"] = " ".join(str(body["name"]).split())[:MAX_NAME]
|
| 277 |
+
return prior
|
| 278 |
+
|
| 279 |
+
_put(session, view_id, _mutate)
|
| 280 |
+
fresh = _all(session.runtime).get(view_id)
|
| 281 |
+
if not isinstance(fresh, dict):
|
| 282 |
+
raise err(503, "store_unavailable", "the new version was NOT saved")
|
| 283 |
+
return {"view": _row(fresh, source=True), "limits": _limits()}
|
| 284 |
+
|
| 285 |
+
|
| 286 |
+
@router.post("/script-views/{view_id}/revert")
|
| 287 |
+
def revert_script_view(view_id: str, body: dict = Body(default=None),
|
| 288 |
+
session: Session = Depends(require_session)):
|
| 289 |
+
"""Put one view back to an earlier version. D-338 / W37-T46.
|
| 290 |
+
|
| 291 |
+
ββ A ROLL-BACK IS A NEW VERSION, NEVER A DELETE OF THE ONES AFTER IT, and that is the whole
|
| 292 |
+
point of the ticket rather than an implementation detail. The history is what lets a person
|
| 293 |
+
trust an agent with their code: if reverting destroyed the versions it stepped over, one
|
| 294 |
+
mistaken revert would cost exactly what the history existed to protect, and there would be no
|
| 295 |
+
way back from the way back. So this appends, and `restoredFrom` records where the text came
|
| 296 |
+
from β the same posture the agent-harness roll-back already takes, so a reader who has seen one
|
| 297 |
+
is not surprised by the other.
|
| 298 |
+
|
| 299 |
+
β IT LIVES ON THE SERVER BECAUSE THE HISTORY DOES. The list door deliberately serves history
|
| 300 |
+
entries WITHOUT their source (`_row`: the rail lists names), so a client cannot assemble an old
|
| 301 |
+
version's text to re-PUT it. Handing the source out just so the client could send it straight
|
| 302 |
+
back would widen a payload for a round trip that does not need to exist, and would make the
|
| 303 |
+
revert non-atomic: two calls, and a failure between them leaves the person looking at code that
|
| 304 |
+
is not what is stored.
|
| 305 |
+
β `_clean_source` is NOT re-run. The text being restored was already validated when it was
|
| 306 |
+
first saved, and a source that a later, stricter rule would now reject is exactly the source a
|
| 307 |
+
person is most likely to want back. `check_source` still runs, because the SANDBOX's refusal is
|
| 308 |
+
about what the code would DO and that must never be bypassed by a route.
|
| 309 |
+
"""
|
| 310 |
+
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 311 |
+
|
| 312 |
+
view_id = str(view_id)
|
| 313 |
+
rec = _all(session.runtime).get(view_id)
|
| 314 |
+
if not isinstance(rec, dict):
|
| 315 |
+
raise err(404, "no_view", "there is no script view with that id")
|
| 316 |
+
_mine_or_admin(session, rec)
|
| 317 |
+
body = body if isinstance(body, dict) else {}
|
| 318 |
+
try:
|
| 319 |
+
want = int(body.get("version"))
|
| 320 |
+
except (TypeError, ValueError):
|
| 321 |
+
raise err(400, "no_version", "say which version to go back to") from None
|
| 322 |
+
|
| 323 |
+
history = [h for h in (rec.get("history") or []) if isinstance(h, dict)]
|
| 324 |
+
match = next((h for h in history if int(h.get("version") or 0) == want), None)
|
| 325 |
+
if match is None:
|
| 326 |
+
# β TWO REASONS A VERSION IS MISSING AND THEY ARE NOT THE SAME FACT. One was never
|
| 327 |
+
# written; the other was TRIMMED off the 40-deep history and the record even counts how
|
| 328 |
+
# many. Saying "that version is gone" for the first would be a lie a person could act on.
|
| 329 |
+
trimmed = int(rec.get("trimmed") or 0)
|
| 330 |
+
if trimmed and want <= trimmed:
|
| 331 |
+
raise err(410, "version_trimmed",
|
| 332 |
+
f"version {want} is older than this view's history keeps "
|
| 333 |
+
f"({trimmed} earlier versions have been dropped)")
|
| 334 |
+
raise err(404, "no_version", f"this view has no version {want}")
|
| 335 |
+
|
| 336 |
+
source = str(match.get("source") or "")
|
| 337 |
+
refusal = sandbox.check_source(source)
|
| 338 |
+
if refusal is not None:
|
| 339 |
+
# An older version that today's sandbox refuses. The person is told which version and why,
|
| 340 |
+
# rather than being handed a 400 about code they did not just type.
|
| 341 |
+
raise err(400, refusal.code, f"version {want} cannot be restored: {refusal.message}")
|
| 342 |
+
|
| 343 |
+
def _mutate(prior):
|
| 344 |
+
prior = dict(prior or rec)
|
| 345 |
+
history_now = list(prior.get("history") or [])
|
| 346 |
+
history_now.append({"version": int(prior.get("version") or 1),
|
| 347 |
+
"source": prior.get("source") or "",
|
| 348 |
+
"author": prior.get("author") or "",
|
| 349 |
+
"created": prior.get("updated") or ""})
|
| 350 |
+
dropped = max(0, len(history_now) - MAX_HISTORY)
|
| 351 |
+
prior["history"] = history_now[dropped:] if dropped else history_now
|
| 352 |
+
prior["trimmed"] = int(prior.get("trimmed") or 0) + dropped
|
| 353 |
+
prior["source"] = source
|
| 354 |
+
prior["version"] = int(prior.get("version") or 1) + 1
|
| 355 |
+
prior["updated"] = _now()
|
| 356 |
+
# β ON THE RECORD, so the history reads as WHAT HAPPENED rather than as a version that
|
| 357 |
+
# mysteriously matches an older one. Without it a reader sees v5 and v2 with identical
|
| 358 |
+
# code and no way to tell a revert from a coincidence.
|
| 359 |
+
prior["restoredFrom"] = want
|
| 360 |
+
return prior
|
| 361 |
+
|
| 362 |
+
_put(session, view_id, _mutate)
|
| 363 |
+
fresh = _all(session.runtime).get(view_id)
|
| 364 |
+
if not isinstance(fresh, dict):
|
| 365 |
+
raise err(503, "store_unavailable", "the roll-back was NOT saved")
|
| 366 |
+
return {"view": _row(fresh, source=True), "restoredFrom": want, "limits": _limits()}
|
| 367 |
+
|
| 368 |
+
|
| 369 |
+
@router.delete("/script-views/{view_id}")
|
| 370 |
+
def delete_script_view(view_id: str, session: Session = Depends(require_session)):
|
| 371 |
+
view_id = str(view_id)
|
| 372 |
+
rec = _all(session.runtime).get(view_id)
|
| 373 |
+
if not isinstance(rec, dict):
|
| 374 |
+
raise err(404, "no_view", "there is no script view with that id")
|
| 375 |
+
_mine_or_admin(session, rec)
|
| 376 |
+
_put(session, view_id, lambda _prior: None)
|
| 377 |
+
return {"deleted": view_id}
|
| 378 |
+
|
| 379 |
+
|
| 380 |
+
@router.post("/script-views/{view_id}/run")
|
| 381 |
+
def run_script_view(view_id: str, body: dict = Body(default=None),
|
| 382 |
+
session: Session = Depends(require_session)):
|
| 383 |
+
"""CONTRACT C3's run door: `{ok, spec | error, stdout, ms}`.
|
| 384 |
+
|
| 385 |
+
β `spec` IS A DESCRIPTION THE CLIENT DRAWS. It is never HTML and never text the browser
|
| 386 |
+
executes β the sandbox refuses a spec carrying an `html`, `script`, `src`, `href` or `on*` key
|
| 387 |
+
before this function ever sees it, so a renderer cannot be talked into running something by a
|
| 388 |
+
script that was itself perfectly well behaved.
|
| 389 |
+
|
| 390 |
+
β AND IT IS PLAIN `def`, NOT `async def` β see this module's header. A ten-second subprocess
|
| 391 |
+
wait on the event loop is a ten-second outage for the whole container.
|
| 392 |
+
"""
|
| 393 |
+
import core.script_sandbox as sandbox # noqa: PLC0415
|
| 394 |
+
|
| 395 |
+
rec = _all(session.runtime).get(str(view_id))
|
| 396 |
+
if not isinstance(rec, dict):
|
| 397 |
+
raise err(404, "no_view", "there is no script view with that id")
|
| 398 |
+
database = str(rec.get("database") or "")
|
| 399 |
+
# A DRAFT run: the editor sends unsaved code so the author can try it before committing to it.
|
| 400 |
+
# It is checked exactly as a stored one is, because "unsaved" is not a permission.
|
| 401 |
+
draft = (body or {}).get("source") if isinstance(body, dict) else None
|
| 402 |
+
source = _clean_source(draft) if draft else str(rec.get("source") or "")
|
| 403 |
+
# β NO `_database_ok` CALL HERE. `run_view` asks C1 the identical question a line later, and
|
| 404 |
+
# asking twice builds a registry topic's pool twice. The three refusals are translated below
|
| 405 |
+
# instead, which is the same wall reached through the same door.
|
| 406 |
+
|
| 407 |
+
if not _RUN_SLOTS.acquire(blocking=False):
|
| 408 |
+
raise err(429, "busy",
|
| 409 |
+
f"{MAX_CONCURRENT_RUNS} script views are already running on this server. "
|
| 410 |
+
f"Try again in a moment")
|
| 411 |
+
try:
|
| 412 |
+
out = sandbox.run_view(session.user, database, source, st=session.runtime)
|
| 413 |
+
finally:
|
| 414 |
+
_RUN_SLOTS.release()
|
| 415 |
+
|
| 416 |
+
# β C1'S THREE REFUSALS ARE HTTP STATUSES, NOT `ok:false`. "You may not read this database"
|
| 417 |
+
# answered 200 would be a permission decision the client has to go looking for, and every
|
| 418 |
+
# other door in this app answers 403 for it. Everything BELOW this line is a well-formed
|
| 419 |
+
# request whose ANSWER is that the script did not produce a view β that is a 200 with
|
| 420 |
+
# `ok:false`, the shape `routes_web_agent.test` already uses for the same reason.
|
| 421 |
+
if out.get("code") == "unknown_table":
|
| 422 |
+
raise err(404, "no_database", out.get("message") or f"there is no database '{database}'")
|
| 423 |
+
if out.get("code") == "denied":
|
| 424 |
+
raise err(403, "forbidden", out.get("message") or "your account may not read that database")
|
| 425 |
+
if out.get("code") == "unresolvable":
|
| 426 |
+
refusal = err(409, "unresolvable", out.get("message") or "these rows cannot be served")
|
| 427 |
+
refusal.detail["error"]["limit"] = out.get("limit") or {}
|
| 428 |
+
raise refusal
|
| 429 |
+
|
| 430 |
+
answer = {"ok": bool(out.get("ok")), "spec": out.get("spec"),
|
| 431 |
+
"stdout": out.get("stdout") or "", "truncated": bool(out.get("truncated")),
|
| 432 |
+
"ms": int(out.get("ms") or 0), "code": out.get("code") or "",
|
| 433 |
+
# β `caps` RIDES ON THE ANSWER (standing rule 1). On a POSIX host all three limits
|
| 434 |
+
# were applied; on a Windows host the memory and CPU ones were not, and a screen
|
| 435 |
+
# that claims an enforcement which did not happen is the failure the rule is about.
|
| 436 |
+
"caps": out.get("caps") or {}}
|
| 437 |
+
if not answer["ok"]:
|
| 438 |
+
answer["error"] = out.get("message") or "the script view did not produce a view"
|
| 439 |
+
return answer
|
api/routes_slack.py
CHANGED
|
@@ -1,789 +1,789 @@
|
|
| 1 |
-
"""routes_slack.py β MANAGE AGENT: a bot per Slack channel, walled by the engine that walls a
|
| 2 |
-
person. (wave 33, owner item 10 Β· `W33-T38` / `W33-T39` / `W33-T67`.)
|
| 3 |
-
|
| 4 |
-
Owner, verbatim (2026-08-14): *"Expand Slack we need to be able to configure an AI bot PER channel
|
| 5 |
-
whose permissions we can toggle based on Fields etc of the databases, exactly like how we toggle
|
| 6 |
-
permissioning per user."*
|
| 7 |
-
|
| 8 |
-
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 9 |
-
ββ D-84 SAID THIS WAS "adapted from OpenTag" AND THAT PREMISE IS FALSE (PRD amendment A1).
|
| 10 |
-
|
| 11 |
-
`PENDING.md` D-84 has named OpenTag as the model for per-Slack-channel permissioning since
|
| 12 |
-
2026-08-08. **OpenTag has no permission model to adapt.** `app/runtime-host.ts` is
|
| 13 |
-
`identifyUser: () => OPENTAG_SERVICE_USER` β ONE constant identity for every request β and its own
|
| 14 |
-
`sender-context.ts` says the Slack sender is *"informational only⦠not gating access."* Its
|
| 15 |
-
authorization ceiling is whole-MCP-server, decided once at process boot from env vars. It is a
|
| 16 |
-
live specimen of identity that LOOKS like a permission and is not.
|
| 17 |
-
|
| 18 |
-
`core/perm_scope.py` is already strictly more expressive: per database, per row, per FIELD, per
|
| 19 |
-
principal. So item 10 is OUR engine projected onto a CHANNEL principal β see `agent_principal`
|
| 20 |
-
below, which is the whole projection and is nine lines. Study:
|
| 21 |
-
`.claude/wiki/research/opentag-adoption.md` (licence gate: MIT, PASSED).
|
| 22 |
-
|
| 23 |
-
What OpenTag genuinely contributes is the WRITE-APPROVAL interceptor (`W33-T67`, `approval_card`
|
| 24 |
-
below) and nothing else. Its TRANSPORT is AVOID wholesale β hosted CopilotKit Intelligence, a
|
| 25 |
-
second Node process, a persistent outbound socket and each tenant's Slack credentials held by a
|
| 26 |
-
third party, against ONE process on the HF free tier. The door here is `routes_forms.py`'s proven
|
| 27 |
-
unauthenticated-public shape plus Slack's signing-secret check.
|
| 28 |
-
|
| 29 |
-
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 30 |
-
β A CHANNEL IS A PRINCIPAL, NOT A PERSON. The wall binds to the Slack conversation id, so every
|
| 31 |
-
human in that channel reads through the same rules. That is the honest reading of "a bot per
|
| 32 |
-
channel" and the pane says it out loud, because the alternative is an admin assuming per-person
|
| 33 |
-
scoping from a screen that looks exactly like the per-person one.
|
| 34 |
-
|
| 35 |
-
β AND THE IDENTITY IS THE CHANNEL ID, NEVER ITS NAME. A channel can be renamed; its id cannot.
|
| 36 |
-
A wall bound to `#sales` silently re-points the day somebody renames the channel.
|
| 37 |
-
"""
|
| 38 |
-
import hmac
|
| 39 |
-
import json
|
| 40 |
-
import os
|
| 41 |
-
import secrets
|
| 42 |
-
import time
|
| 43 |
-
from datetime import datetime, timezone
|
| 44 |
-
|
| 45 |
-
from fastapi import APIRouter, Body, Depends, Request
|
| 46 |
-
|
| 47 |
-
from deps import Session, err, require_session
|
| 48 |
-
from routes_admin import admin_gate
|
| 49 |
-
|
| 50 |
-
router = APIRouter(prefix="/api/v1")
|
| 51 |
-
|
| 52 |
-
#: The tenant's channel agents: `{id: record}`. A per-tenant bucket, so it rides
|
| 53 |
-
#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace.
|
| 54 |
-
AGENTS_KEY = "slack_agents"
|
| 55 |
-
|
| 56 |
-
#: Pending mutations awaiting a human's click (`W33-T67`). Server-only, per tenant.
|
| 57 |
-
PENDING_KEY = "slack_pending_writes"
|
| 58 |
-
|
| 59 |
-
#: How long an approval card stays clickable. An approval is a statement about the world as it was
|
| 60 |
-
#: when the card was rendered; an hour later the values it names may no longer be the values it
|
| 61 |
-
#: would write. Expiring is the honest behaviour, and an expired card says so rather than 403ing.
|
| 62 |
-
APPROVAL_TTL_S = 15 * 60
|
| 63 |
-
|
| 64 |
-
#: Slack rejects a replayed request older than 5 minutes; so do we, before any signature work.
|
| 65 |
-
SLACK_MAX_SKEW_S = 60 * 5
|
| 66 |
-
|
| 67 |
-
MAX_BODY_BYTES = 64 * 1024
|
| 68 |
-
|
| 69 |
-
#: β ROW-CAPPED BECAUSE AN APPROVER WHO CANNOT READ THE CARD CANNOT APPROVE IT. Copied
|
| 70 |
-
#: deliberately from OpenTag's `agent/write_confirmation.py`, which caps for the same reason:
|
| 71 |
-
#: past a certain length Slack collapses a message behind "Show more", and a human clicking
|
| 72 |
-
#: Approve on a card whose tail they never saw is worse than no card at all.
|
| 73 |
-
APPROVAL_MAX_ROWS = 12
|
| 74 |
-
|
| 75 |
-
|
| 76 |
-
# ββ the tenant's agent records βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 77 |
-
def _agents(rt):
|
| 78 |
-
"""`{id: record}` for one tenant. `{}` on any failure β an unreadable bucket must degrade to
|
| 79 |
-
"this tenant has no agents", never to a 500 on the settings pane."""
|
| 80 |
-
try:
|
| 81 |
-
found = rt.get(AGENTS_KEY) or {}
|
| 82 |
-
except Exception: # noqa: BLE001
|
| 83 |
-
return {}
|
| 84 |
-
return found if isinstance(found, dict) else {}
|
| 85 |
-
|
| 86 |
-
|
| 87 |
-
def _clean_agent(raw, prior=None):
|
| 88 |
-
"""One stored record, built KEY BY KEY.
|
| 89 |
-
|
| 90 |
-
β Never `dict(raw)` and never `**raw`. This record is the SUBJECT of a permission decision;
|
| 91 |
-
a client-supplied key landing in it is a client-supplied input to `perm_scope`. The same rule
|
| 92 |
-
`routes_forms._public_form` follows on the way out, applied here on the way in.
|
| 93 |
-
"""
|
| 94 |
-
prior = prior if isinstance(prior, dict) else {}
|
| 95 |
-
out = {
|
| 96 |
-
"id": str(prior.get("id") or raw.get("id") or ""),
|
| 97 |
-
"channel": str(raw.get("channel") or prior.get("channel") or "").strip()[:64],
|
| 98 |
-
"channelName": str(raw.get("channelName") or prior.get("channelName") or "").strip()[:80],
|
| 99 |
-
"label": " ".join(str(raw.get("label") or prior.get("label") or "").split())[:80],
|
| 100 |
-
"active": bool(raw.get("active", prior.get("active", True))),
|
| 101 |
-
# β DEFAULT TRUE, AND `is not False` RATHER THAN TRUTHINESS. A record written before this
|
| 102 |
-
# key existed must read as "approval required": the one direction a default here is
|
| 103 |
-
# allowed to be wrong in is the safe one, because an unattended write cannot be undone by
|
| 104 |
-
# revoking the bot afterwards [[default-must-pass-its-own-guard]].
|
| 105 |
-
"writeApproval": raw.get("writeApproval", prior.get("writeApproval", True)) is not False,
|
| 106 |
-
# The permission block. Same shape, same validator, same engine as a user's.
|
| 107 |
-
"perms": prior.get("perms") if isinstance(prior.get("perms"), dict) else {},
|
| 108 |
-
"perms_v": int(prior.get("perms_v") or 0),
|
| 109 |
-
"createdBy": str(prior.get("createdBy") or raw.get("createdBy") or ""),
|
| 110 |
-
"createdAt": str(prior.get("createdAt") or raw.get("createdAt") or ""),
|
| 111 |
-
}
|
| 112 |
-
return out
|
| 113 |
-
|
| 114 |
-
|
| 115 |
-
def _put_agent(session, agent_id, mutate):
|
| 116 |
-
"""Read-modify-write ONE agent under the tenant's bucket, synchronously.
|
| 117 |
-
|
| 118 |
-
`flush="sync"` because the client re-reads the list immediately after every write here, and an
|
| 119 |
-
async flush would let the refetch win the race and paint the pre-write state β the
|
| 120 |
-
[[refetch-eats-its-own-write]] shape.
|
| 121 |
-
"""
|
| 122 |
-
def _set(cur):
|
| 123 |
-
cur = dict(cur or {})
|
| 124 |
-
rec = cur.get(agent_id) if isinstance(cur.get(agent_id), dict) else None
|
| 125 |
-
nxt = mutate(rec)
|
| 126 |
-
if nxt is None:
|
| 127 |
-
cur.pop(agent_id, None)
|
| 128 |
-
else:
|
| 129 |
-
cur[agent_id] = nxt
|
| 130 |
-
return cur
|
| 131 |
-
|
| 132 |
-
session.runtime.update(AGENTS_KEY, _set, flush="sync")
|
| 133 |
-
|
| 134 |
-
|
| 135 |
-
# ββ ββ THE PROJECTION β THE WHOLE OF "the same engine that permissions a user" βββββββββββββββ
|
| 136 |
-
def agent_principal(agent):
|
| 137 |
-
"""A channel agent, as a PRINCIPAL `core/perm_scope` already understands.
|
| 138 |
-
|
| 139 |
-
ββ THIS IS THE ENTIRE POINT OF THE TICKET AND IT IS NINE LINES. `perm_scope` takes a user
|
| 140 |
-
RECORD β a plain dict with `perms`, `perms_v` and `role` β not a User object and not a session.
|
| 141 |
-
So a channel agent carrying a `perms` block simply IS such a record, and `may_access`,
|
| 142 |
-
`visible_fields`, `hidden_keys` and `apply_row_scope` work on it unmodified. There is no second
|
| 143 |
-
engine, no parallel vocabulary, and nothing about a channel to keep in step with anything about
|
| 144 |
-
a person. That is what the owner's *"exactly like how we toggle permissioning per user"* means
|
| 145 |
-
when it is true in code rather than in appearance.
|
| 146 |
-
|
| 147 |
-
β `role` IS HARDCODED NON-ADMIN AND MUST STAY SO. `perm_scope.may_access` returns True
|
| 148 |
-
unconditionally for `role == 'admin'` β the break-glass clause that keeps the owner out of a
|
| 149 |
-
locked store. A bot has no such emergency and no hands: an agent record that could carry
|
| 150 |
-
`role: 'admin'` would be one stored key away from bypassing every wall on this page. The key is
|
| 151 |
-
not copied from the record; it is written here, every time.
|
| 152 |
-
|
| 153 |
-
β AND `perms_v` IS FORCED TO THE CURRENT VERSION, which makes an UNDECLARED database DENY
|
| 154 |
-
(C-PERM amendment 4). Without it a fresh agent would fall through to `perms.may_open`'s legacy
|
| 155 |
-
grant wall and read `modules: 'all'`-shaped defaults β i.e. a brand-new bot would start with
|
| 156 |
-
access to everything. Fail-closed from the first byte.
|
| 157 |
-
"""
|
| 158 |
-
import core.perm_scope as perm_scope
|
| 159 |
-
return {
|
| 160 |
-
"username": f"slack:{(agent or {}).get('channel') or '?'}",
|
| 161 |
-
"role": "agent",
|
| 162 |
-
"perms": (agent or {}).get("perms") or {},
|
| 163 |
-
"perms_v": perm_scope.PERMS_VERSION,
|
| 164 |
-
# No `bus`, no `agent`: a channel is not a business unit and not a salesperson. Absent
|
| 165 |
-
# rather than 'all' β `perms.allowed_bu_labels` narrows on absence, which is the direction
|
| 166 |
-
# this must fail in.
|
| 167 |
-
}
|
| 168 |
-
|
| 169 |
-
|
| 170 |
-
def agent_may_read(agent, module):
|
| 171 |
-
"""May this channel open `module` at all?"""
|
| 172 |
-
import core.perm_scope as perm_scope
|
| 173 |
-
if not (agent or {}).get("active", True):
|
| 174 |
-
return False
|
| 175 |
-
return bool(perm_scope.may_access(agent_principal(agent), module))
|
| 176 |
-
|
| 177 |
-
|
| 178 |
-
def agent_visible_fields(agent, fields, module):
|
| 179 |
-
"""`fields` minus this channel's hidden closure β the SAME transitive closure a person gets,
|
| 180 |
-
so a formula over a hidden column cannot leak it back through arithmetic."""
|
| 181 |
-
import core.perm_scope as perm_scope
|
| 182 |
-
return perm_scope.visible_fields(fields, agent_principal(agent), module)
|
| 183 |
-
|
| 184 |
-
|
| 185 |
-
def agent_rows(agent, rows, module, fields, ctx=None, st=None):
|
| 186 |
-
"""The rows this channel may receive β `permits()`, so an unanswerable permanent filter DENIES
|
| 187 |
-
rather than being ignored.
|
| 188 |
-
|
| 189 |
-
ββ `st` IS THE TENANT HANDLE AND IT IS HERE BECAUSE OF THE SENTENCE IN `agent_principal`:
|
| 190 |
-
a channel agent IS a principal of the same wall, so a permanent filter naming a
|
| 191 |
-
user-generated column has to mean the SAME thing here as it does on the grid (owner I16).
|
| 192 |
-
A door that lends the handle and a door that does not are one stored rule with two meanings.
|
| 193 |
-
|
| 194 |
-
β PASS THE TENANT'S OWN RUNTIME β every other store read in this file takes
|
| 195 |
-
`session.runtime`, and a channel is not a second tenancy. It is a keyword with a `None`
|
| 196 |
-
default for the same reason `perm_scope.apply_row_scope`'s is: without one this is
|
| 197 |
-
byte-identical to the wall that shipped before the argument existed.
|
| 198 |
-
|
| 199 |
-
β `hidden_keys` DELIBERATELY DOES NOT TAKE IT IN THIS CHANGE. Its field-grant leg
|
| 200 |
-
under-hides without a handle (see `perm_scope.visible_overlays`), which is a real and
|
| 201 |
-
separate gap on this surface β but it is the FIELD wall, it moves what a channel receives
|
| 202 |
-
rather than what I16 asked for, and widening two walls in one ticket is how a permission
|
| 203 |
-
change stops being reviewable.
|
| 204 |
-
"""
|
| 205 |
-
import core.perm_scope as perm_scope
|
| 206 |
-
p = agent_principal(agent)
|
| 207 |
-
hide = perm_scope.hidden_keys(p, module, fields)
|
| 208 |
-
kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx, st=st)
|
| 209 |
-
# Both wires, never one: the field list and the row payload are separate, and stripping only
|
| 210 |
-
# the first leaves the value sitting in the second where anyone can read it.
|
| 211 |
-
return [perm_scope.strip_row(r, hide) for r in kept]
|
| 212 |
-
|
| 213 |
-
|
| 214 |
-
# ββ the credential βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 215 |
-
def slack_creds(rt):
|
| 216 |
-
"""This TENANT's Slack credentials from its own keychain, or None.
|
| 217 |
-
|
| 218 |
-
β NO ENVIRONMENT FALLBACK, DELIBERATELY, AND THIS IS D-202's LESSON APPLIED BEFORE IT
|
| 219 |
-
HAPPENS AGAIN. Meta Ads shipped loading end-to-end and was still not a connector, because
|
| 220 |
-
`keychain.meta_creds` had no caller and the token came from the owner's `.env` β making it a
|
| 221 |
-
tenant-#0 FACT indistinguishable from a screenshot. `keychain.meta_creds`' own docstring spells
|
| 222 |
-
out the rule: handing the environment's credential to a tenant whose admin has not stored one
|
| 223 |
-
is the leak the resolver exists to prevent. So a tenant with no entry gets None and the pane
|
| 224 |
-
SAYS so.
|
| 225 |
-
|
| 226 |
-
β Reads through `list_entries` + `read_fields` (both public) rather than `keychain._first_creds`
|
| 227 |
-
(private, and in a file outside this lane's fence). Same deterministic rule: entries are
|
| 228 |
-
id-sorted, so "first" is stable across reads rather than dict-order luck.
|
| 229 |
-
"""
|
| 230 |
-
try:
|
| 231 |
-
import core.keychain as keychain
|
| 232 |
-
for row in keychain.list_entries(rt):
|
| 233 |
-
if str(row.get("type") or "") != "slack":
|
| 234 |
-
continue
|
| 235 |
-
fields = keychain.read_fields(rt, row.get("id"))
|
| 236 |
-
if isinstance(fields, dict) and fields.get("signing_secret"):
|
| 237 |
-
return fields
|
| 238 |
-
except Exception: # noqa: BLE001
|
| 239 |
-
# A locked or unreadable keychain reads as "not configured" for the PANE, which is honest;
|
| 240 |
-
# the signature check below fails closed regardless, so this cannot widen anything.
|
| 241 |
-
return None
|
| 242 |
-
return None
|
| 243 |
-
|
| 244 |
-
|
| 245 |
-
# ββ the authenticated doors (the Manage agent surface) βββββββββββββββββββββββββββββββββββββββ
|
| 246 |
-
def _summary(agent, modules):
|
| 247 |
-
"""One sentence per agent for the list row β computed here, because the alternative is one
|
| 248 |
-
round trip per row to fill one cell (the same reason `AdminUser.access` exists)."""
|
| 249 |
-
# β W36-T22 / C2 β every listed database is governed now; the `enforced` flag it used to
|
| 250 |
-
# filter on is DELETED, and `m.get("enforced")` would have gone silently falsy here and
|
| 251 |
-
# summarised every agent as "" (no databases at all).
|
| 252 |
-
governed = list(modules)
|
| 253 |
-
perms = agent.get("perms") or {}
|
| 254 |
-
open_n = sum(1 for m in governed if (perms.get(m["key"]) or {}).get("access"))
|
| 255 |
-
if not governed:
|
| 256 |
-
return ""
|
| 257 |
-
if open_n == 0:
|
| 258 |
-
return "No access"
|
| 259 |
-
restricted = sum(1 for m in governed
|
| 260 |
-
if (perms.get(m["key"]) or {}).get("access")
|
| 261 |
-
and ((perms.get(m["key"]) or {}).get("filter")
|
| 262 |
-
or (perms.get(m["key"]) or {}).get("hiddenFields")))
|
| 263 |
-
head = (f"All {open_n} database{'' if open_n == 1 else 's'}" if open_n == len(governed)
|
| 264 |
-
else f"{open_n} of {len(governed)} databases")
|
| 265 |
-
return f"{head}, {restricted} restricted" if restricted else head
|
| 266 |
-
|
| 267 |
-
|
| 268 |
-
@router.get("/agents")
|
| 269 |
-
def list_channel_agents(session: Session = Depends(admin_gate)):
|
| 270 |
-
"""This tenant's channel agents, plus whether Slack is reachable at all."""
|
| 271 |
-
import routes_admin
|
| 272 |
-
modules = routes_admin._perm_modules(session)
|
| 273 |
-
rows = []
|
| 274 |
-
for aid, a in sorted(_agents(session.runtime).items()):
|
| 275 |
-
if not isinstance(a, dict):
|
| 276 |
-
continue
|
| 277 |
-
rows.append({"id": aid, "channel": a.get("channel") or "",
|
| 278 |
-
"channelName": a.get("channelName") or "",
|
| 279 |
-
"label": a.get("label") or "", "active": a.get("active", True) is not False,
|
| 280 |
-
"writeApproval": a.get("writeApproval", True) is not False,
|
| 281 |
-
"summary": _summary(a, modules)})
|
| 282 |
-
return {"agents": rows, "configured": slack_creds(session.runtime) is not None}
|
| 283 |
-
|
| 284 |
-
|
| 285 |
-
@router.post("/agents")
|
| 286 |
-
def create_channel_agent(body: dict = Body(default=None),
|
| 287 |
-
session: Session = Depends(admin_gate)):
|
| 288 |
-
body = body if isinstance(body, dict) else {}
|
| 289 |
-
channel = str(body.get("channel") or "").strip()
|
| 290 |
-
if not channel:
|
| 291 |
-
raise err(400, "no_channel", "a Slack channel ID is required")
|
| 292 |
-
existing = _agents(session.runtime)
|
| 293 |
-
# β ONE AGENT PER CHANNEL. Two records for one conversation would mean two walls, and nothing
|
| 294 |
-
# anywhere decides which one applies β the [[one-question-two-normalizers]] shape, in the one
|
| 295 |
-
# place where the two answers are "may read" and "may not".
|
| 296 |
-
for a in existing.values():
|
| 297 |
-
if isinstance(a, dict) and str(a.get("channel") or "") == channel:
|
| 298 |
-
raise err(409, "channel_taken",
|
| 299 |
-
"that channel already has an agent β edit it instead of adding a second")
|
| 300 |
-
aid = secrets.token_urlsafe(9)
|
| 301 |
-
rec = _clean_agent(dict(body, id=aid, createdBy=session.uname,
|
| 302 |
-
createdAt=datetime.now(timezone.utc).isoformat(timespec="seconds")))
|
| 303 |
-
_put_agent(session, aid, lambda _prior: rec)
|
| 304 |
-
fresh = _agents(session.runtime).get(aid)
|
| 305 |
-
if not isinstance(fresh, dict):
|
| 306 |
-
# The store took the write and did not record it. A 200 here would tell an administrator
|
| 307 |
-
# the agent exists when it does not.
|
| 308 |
-
raise err(503, "store_unavailable", "the agent was NOT created")
|
| 309 |
-
return {"agent": {"id": aid, "channel": rec["channel"], "channelName": rec["channelName"],
|
| 310 |
-
"label": rec["label"], "active": rec["active"],
|
| 311 |
-
"writeApproval": rec["writeApproval"], "summary": "No access"}}
|
| 312 |
-
|
| 313 |
-
|
| 314 |
-
@router.get("/agents/{agent_id}")
|
| 315 |
-
def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
|
| 316 |
-
"""The agent PLUS the permission envelope β the SAME shape `get_perms` answers with.
|
| 317 |
-
|
| 318 |
-
β ONE PAYLOAD SHAPE FOR TWO ROOMS. `permsModel.parsePermsPayload` parses this, and
|
| 319 |
-
`settings/ModulePermsList` renders it, because they are literally the same client code. A
|
| 320 |
-
second envelope here would mean a second parser and a second set of defaults within a wave.
|
| 321 |
-
"""
|
| 322 |
-
import routes_admin
|
| 323 |
-
a = _agents(session.runtime).get(str(agent_id))
|
| 324 |
-
if not isinstance(a, dict):
|
| 325 |
-
raise err(404, "no_such_agent", "no agent with that id")
|
| 326 |
-
modules = routes_admin._perm_modules(session)
|
| 327 |
-
# ββ W36-T22 / C2 β EVERY listed database, `ut_*` included. β THIS IS WHY THE FLAG'S
|
| 328 |
-
# DELETION IS NOT A ONE-FILE CHANGE: `m.get("enforced")` on a row that no longer carries the
|
| 329 |
-
# key is None, so this list would have been EMPTY and the channel perms editor would have
|
| 330 |
-
# governed ZERO databases while looking entirely correct. A Slack channel is a principal of
|
| 331 |
-
# the SAME wall (`verify_perm_scope` section H) and gets the same catalogue.
|
| 332 |
-
governed = [m["key"] for m in modules]
|
| 333 |
-
stored = a.get("perms") or {}
|
| 334 |
-
principal = agent_principal(a)
|
| 335 |
-
import core.perm_scope as perm_scope
|
| 336 |
-
perms_out = {}
|
| 337 |
-
for k in governed:
|
| 338 |
-
e = stored.get(k)
|
| 339 |
-
# β W36-T22 β `may_read`, the same evaluator the read door uses, for the reason spelled
|
| 340 |
-
# out at `routes_admin.get_perms`. β It answers DIFFERENTLY here and correctly so: a
|
| 341 |
-
# channel agent is not a person with a share, so a `ut_*` key it has not been granted
|
| 342 |
-
# defaults CLOSED β which is the fail-closed direction for a bot, and the same answer the
|
| 343 |
-
# table routes would give it.
|
| 344 |
-
perms_out[k] = e if isinstance(e, dict) else {
|
| 345 |
-
"access": bool(perm_scope.may_read(principal, k, st=session.runtime)),
|
| 346 |
-
"filter": None, "hiddenFields": []}
|
| 347 |
-
return {"id": str(agent_id), "channel": a.get("channel") or "",
|
| 348 |
-
"channelName": a.get("channelName") or "", "label": a.get("label") or "",
|
| 349 |
-
"active": a.get("active", True) is not False,
|
| 350 |
-
"writeApproval": a.get("writeApproval", True) is not False,
|
| 351 |
-
"perms": perms_out,
|
| 352 |
-
# β ALWAYS THE CURRENT VERSION, because `agent_principal` forces it: the editor must
|
| 353 |
-
# render "undeclared = denied", not the legacy-grant reading it would show at 0.
|
| 354 |
-
"perms_v": perm_scope.PERMS_VERSION,
|
| 355 |
-
# A bot is NEVER an admin β see `agent_principal`. Sent so the editor never paints
|
| 356 |
-
# the "Everything (admin)" state for a principal that cannot have it.
|
| 357 |
-
"is_admin": False,
|
| 358 |
-
"modules": modules,
|
| 359 |
-
"fields_by_module": {k: routes_admin._module_fields(k, session=session)
|
| 360 |
-
for k in governed}}
|
| 361 |
-
|
| 362 |
-
|
| 363 |
-
@router.put("/agents/{agent_id}/perms")
|
| 364 |
-
def put_channel_agent_perms(agent_id: str, body: dict = Body(default=None),
|
| 365 |
-
session: Session = Depends(admin_gate)):
|
| 366 |
-
"""Replace this agent's permission block wholesale β the same validator a user's block gets."""
|
| 367 |
-
import routes_admin
|
| 368 |
-
body = body if isinstance(body, dict) else {}
|
| 369 |
-
if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 370 |
-
raise err(404, "no_such_agent", "no agent with that id")
|
| 371 |
-
if "perms" not in body:
|
| 372 |
-
raise err(400, "empty_patch", "no perms to save")
|
| 373 |
-
mods = routes_admin._perm_modules(session)
|
| 374 |
-
# β THE SAME `_clean_perms`, NOT A COPY OF IT. It refuses a filter this module cannot
|
| 375 |
-
# evaluate, refuses a hiddenFields key that names nothing, and refuses a BU condition the
|
| 376 |
-
# pushdown cannot read. Every one of those is exactly as true for a channel as for a person,
|
| 377 |
-
# and a second validator here is a second place for one of them to go missing.
|
| 378 |
-
# β CORRECTED W36-T22: this list used to end "refuses an unenforced `ut_*` key". That refusal
|
| 379 |
-
# is DELETED β W36-T21 armed the wall over every database, so there is no unenforced key left
|
| 380 |
-
# to refuse, and a comment naming a rule that no longer exists is how the next wave re-derives
|
| 381 |
-
# it ([[two-gates-can-assert-opposite-things]]).
|
| 382 |
-
cleaned = routes_admin._clean_perms(
|
| 383 |
-
body.get("perms"),
|
| 384 |
-
governed_keys={m["key"] for m in mods}, session=session) or {}
|
| 385 |
-
|
| 386 |
-
import core.perm_scope as perm_scope
|
| 387 |
-
|
| 388 |
-
def _mut(prior):
|
| 389 |
-
if not isinstance(prior, dict):
|
| 390 |
-
return None
|
| 391 |
-
nxt = dict(prior)
|
| 392 |
-
nxt["perms"] = cleaned
|
| 393 |
-
nxt["perms_v"] = perm_scope.PERMS_VERSION
|
| 394 |
-
return nxt
|
| 395 |
-
|
| 396 |
-
_put_agent(session, str(agent_id), _mut)
|
| 397 |
-
fresh = _agents(session.runtime).get(str(agent_id)) or {}
|
| 398 |
-
if (fresh.get("perms") or {}) != cleaned:
|
| 399 |
-
# The one direction this must never fail in: telling an administrator the wall is up when
|
| 400 |
-
# it is not.
|
| 401 |
-
raise err(503, "store_unavailable", "the permissions were not saved β the agent is UNCHANGED")
|
| 402 |
-
return {"id": str(agent_id), "perms": fresh.get("perms") or {},
|
| 403 |
-
"perms_v": int(fresh.get("perms_v") or 0)}
|
| 404 |
-
|
| 405 |
-
|
| 406 |
-
@router.patch("/agents/{agent_id}")
|
| 407 |
-
def patch_channel_agent(agent_id: str, body: dict = Body(default=None),
|
| 408 |
-
session: Session = Depends(admin_gate)):
|
| 409 |
-
body = body if isinstance(body, dict) else {}
|
| 410 |
-
if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 411 |
-
raise err(404, "no_such_agent", "no agent with that id")
|
| 412 |
-
#: β `perms` IS NOT PATCHABLE HERE. It has its own door with its own validator; accepting it
|
| 413 |
-
#: on the metadata route would be a second, unvalidated way to write the wall.
|
| 414 |
-
allowed = {k: v for k, v in body.items()
|
| 415 |
-
if k in ("label", "active", "writeApproval", "channelName")}
|
| 416 |
-
if not allowed:
|
| 417 |
-
raise err(400, "empty_patch", "nothing to change")
|
| 418 |
-
|
| 419 |
-
def _mut(prior):
|
| 420 |
-
return _clean_agent(allowed, prior=prior) if isinstance(prior, dict) else None
|
| 421 |
-
|
| 422 |
-
_put_agent(session, str(agent_id), _mut)
|
| 423 |
-
import routes_admin
|
| 424 |
-
a = _agents(session.runtime).get(str(agent_id)) or {}
|
| 425 |
-
return {"agent": {"id": str(agent_id), "channel": a.get("channel") or "",
|
| 426 |
-
"channelName": a.get("channelName") or "", "label": a.get("label") or "",
|
| 427 |
-
"active": a.get("active", True) is not False,
|
| 428 |
-
"writeApproval": a.get("writeApproval", True) is not False,
|
| 429 |
-
"summary": _summary(a, routes_admin._perm_modules(session))}}
|
| 430 |
-
|
| 431 |
-
|
| 432 |
-
@router.delete("/agents/{agent_id}")
|
| 433 |
-
def delete_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
|
| 434 |
-
if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 435 |
-
raise err(404, "no_such_agent", "no agent with that id")
|
| 436 |
-
_put_agent(session, str(agent_id), lambda _prior: None)
|
| 437 |
-
if isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 438 |
-
raise err(503, "store_unavailable", "the agent was NOT removed")
|
| 439 |
-
return {"ok": True}
|
| 440 |
-
|
| 441 |
-
|
| 442 |
-
# ββ β W33-T67: THE WRITE-APPROVAL GATE βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 443 |
-
def _is_empty(value):
|
| 444 |
-
"""Is this value ABSENT, as opposed to falsy?
|
| 445 |
-
|
| 446 |
-
β COPIED EXACTLY FROM OpenTag's `agent/write_confirmation.py`, and the exactness is the point:
|
| 447 |
-
`0` and `False` are VALUES a human must see on the card. Setting a price to 0 or a flag to
|
| 448 |
-
False is precisely the kind of write somebody needs to approve, and a naive `if not value`
|
| 449 |
-
drops both rows silently β the approver then reads a card that does not describe the write
|
| 450 |
-
they are approving. The MIT licence gate for this borrowing is recorded in
|
| 451 |
-
`.claude/wiki/research/opentag-adoption.md`.
|
| 452 |
-
"""
|
| 453 |
-
return value is None or (isinstance(value, str) and value.strip() == "")
|
| 454 |
-
|
| 455 |
-
|
| 456 |
-
def approval_card(action, values, agent=None):
|
| 457 |
-
"""The card a human reads before a bot writes. `{action, rows, truncated, note}`.
|
| 458 |
-
|
| 459 |
-
β ROW-CAPPED, and the cap is a SAFETY property rather than a layout one: past a certain
|
| 460 |
-
length Slack collapses a message behind "Show more", and **an approver who cannot read the
|
| 461 |
-
card cannot approve it.** When rows are dropped the card SAYS how many β a truncation nobody
|
| 462 |
-
was told about is the violation, not the truncation (wave-30 R6's second sentence).
|
| 463 |
-
"""
|
| 464 |
-
rows = [{"field": str(k), "value": v}
|
| 465 |
-
for k, v in (values or {}).items() if not _is_empty(v)]
|
| 466 |
-
rows.sort(key=lambda r: r["field"])
|
| 467 |
-
shown, dropped = rows[:APPROVAL_MAX_ROWS], max(0, len(rows) - APPROVAL_MAX_ROWS)
|
| 468 |
-
return {
|
| 469 |
-
"action": str(action or "")[:80],
|
| 470 |
-
"rows": shown,
|
| 471 |
-
"truncated": dropped,
|
| 472 |
-
"note": (f"{dropped} more field(s) not shown β open the record to review them before "
|
| 473 |
-
f"approving." if dropped else ""),
|
| 474 |
-
"agent": (agent or {}).get("label") or (agent or {}).get("channel") or "",
|
| 475 |
-
}
|
| 476 |
-
|
| 477 |
-
|
| 478 |
-
def intercept_write(agent, action, values, stash):
|
| 479 |
-
"""THE INTERCEPTOR. Returns `("commit", None)` or `("await_approval", card)`.
|
| 480 |
-
|
| 481 |
-
β The one thing worth taking from OpenTag: a MUTATING tool call is halted, rendered as a card
|
| 482 |
-
naming the action and its values, and committed only on an explicit human accept. Everything
|
| 483 |
-
else in that repo β the transport, the runtime, the identity model β is AVOID (amendment A1).
|
| 484 |
-
|
| 485 |
-
β FAIL-CLOSED ON A MISSING FLAG: `is not False`, so a record written before `writeApproval`
|
| 486 |
-
existed requires approval. The unsafe direction here is not recoverable β revoking a bot does
|
| 487 |
-
not un-write what it wrote.
|
| 488 |
-
"""
|
| 489 |
-
if (agent or {}).get("writeApproval", True) is not False:
|
| 490 |
-
card = approval_card(action, values, agent)
|
| 491 |
-
stash(card)
|
| 492 |
-
return "await_approval", card
|
| 493 |
-
return "commit", None
|
| 494 |
-
|
| 495 |
-
|
| 496 |
-
def _pending(rt):
|
| 497 |
-
try:
|
| 498 |
-
found = rt.get(PENDING_KEY) or {}
|
| 499 |
-
except Exception: # noqa: BLE001
|
| 500 |
-
return {}
|
| 501 |
-
return found if isinstance(found, dict) else {}
|
| 502 |
-
|
| 503 |
-
|
| 504 |
-
def stash_pending(rt, agent, action, values, now=None):
|
| 505 |
-
"""Store one awaiting-approval mutation and return its token.
|
| 506 |
-
|
| 507 |
-
The token is what rides the card's button, so it is `secrets.token_urlsafe` and not the
|
| 508 |
-
action's id: a guessable value on an unauthenticated door is a way to approve somebody else's
|
| 509 |
-
write. Server-only bucket, per tenant, exactly as `routes_forms.TOKENS_KEY` is.
|
| 510 |
-
"""
|
| 511 |
-
token = secrets.token_urlsafe(18)
|
| 512 |
-
row = {"at": float(now if now is not None else time.time()),
|
| 513 |
-
"channel": str((agent or {}).get("channel") or ""),
|
| 514 |
-
"action": str(action or "")[:80],
|
| 515 |
-
"values": values if isinstance(values, dict) else {}}
|
| 516 |
-
rt.update(PENDING_KEY, lambda cur: {**(cur or {}), token: row}, flush="sync")
|
| 517 |
-
return token
|
| 518 |
-
|
| 519 |
-
|
| 520 |
-
#: `{action kind: fn(rt, row) -> None}`. Registered by whatever can actually perform a mutation.
|
| 521 |
-
#:
|
| 522 |
-
#: ββ EMPTY IN PRODUCTION TODAY, AND SAYING SO IS THE POINT. `commit_pending` below is the ONE
|
| 523 |
-
#: place an approved write may be performed, so it is the place a negative control can bite β but
|
| 524 |
-
#: a gate is only as honest as what it guards. Until something registers here, an approved card
|
| 525 |
-
#: performs NOTHING and `commit_pending` returns `no_committer` rather than pretending. That is a
|
| 526 |
-
#: declared absence, not a silent one [[flag-shipped-without-its-writer]].
|
| 527 |
-
_COMMITTERS = {}
|
| 528 |
-
|
| 529 |
-
|
| 530 |
-
def register_committer(kind, fn):
|
| 531 |
-
"""Declare who may perform an approved mutation of `kind`. Idempotent by key."""
|
| 532 |
-
_COMMITTERS[str(kind)] = fn
|
| 533 |
-
|
| 534 |
-
|
| 535 |
-
def commit_pending(rt, token, approved, now=None):
|
| 536 |
-
"""Resolve ONE approval card. Returns one of
|
| 537 |
-
`expired` Β· `unknown` Β· `rejected` Β· `no_committer` Β· `committed` Β· `failed`.
|
| 538 |
-
|
| 539 |
-
ββ THIS IS THE WRITE GATE, AND IT IS A SEPARATE FUNCTION FROM THE ROUTE ON PURPOSE. T67's
|
| 540 |
-
`done-when` asks for an NC proving a REJECTED card writes nothing. A control aimed at the
|
| 541 |
-
route could not bite while the route had no write in it at all β it would stay green with the
|
| 542 |
-
guard deleted, because there would be nothing for the guard to be protecting anything from
|
| 543 |
-
([[gate-can-report-green-on-nothing]], and a verifier caught exactly that on this ticket's
|
| 544 |
-
first draft). Putting the commit behind ONE named seam gives the control a real subject: the
|
| 545 |
-
gate registers a recorder, and `rejected` must leave it untouched while `approve` must call it
|
| 546 |
-
exactly once.
|
| 547 |
-
|
| 548 |
-
β THE TOKEN IS CONSUMED BEFORE EITHER BRANCH, and before any committer runs. A card that
|
| 549 |
-
survives its own click is a replayable write, and "approve twice" must never mean "write
|
| 550 |
-
twice". The delete is `flush="sync"` for the same reason.
|
| 551 |
-
"""
|
| 552 |
-
now = float(now if now is not None else time.time())
|
| 553 |
-
row = _pending(rt).get(str(token))
|
| 554 |
-
if not isinstance(row, dict):
|
| 555 |
-
return "unknown"
|
| 556 |
-
# Consume FIRST β before the TTL verdict, before the approve/reject branch, before any write.
|
| 557 |
-
rt.update(PENDING_KEY,
|
| 558 |
-
lambda cur: {k: v for k, v in (cur or {}).items() if k != str(token)},
|
| 559 |
-
flush="sync")
|
| 560 |
-
if now - float(row.get("at") or 0) > APPROVAL_TTL_S:
|
| 561 |
-
return "expired"
|
| 562 |
-
if not approved:
|
| 563 |
-
# β NOTHING BELOW THIS LINE RUNS FOR A REJECTED CARD. The whole gate is this return.
|
| 564 |
-
return "rejected"
|
| 565 |
-
fn = _COMMITTERS.get(str(row.get("action") or ""))
|
| 566 |
-
if fn is None:
|
| 567 |
-
return "no_committer"
|
| 568 |
-
try:
|
| 569 |
-
fn(rt, row)
|
| 570 |
-
except Exception: # noqa: BLE001
|
| 571 |
-
# A committer that raises must not read as a commit. The card is already consumed, so the
|
| 572 |
-
# honest report is that it failed, and the human asks again.
|
| 573 |
-
return "failed"
|
| 574 |
-
return "committed"
|
| 575 |
-
|
| 576 |
-
|
| 577 |
-
# ββ the UNAUTHENTICATED Slack door βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 578 |
-
#: Sliding window, keyed on the SLACK TEAM, never the client IP.
|
| 579 |
-
#:
|
| 580 |
-
#: β WHY NOT THE IP, WHICH IS WHAT `routes_forms` DOES. Every Slack event arrives from Slack's own
|
| 581 |
-
#: infrastructure, so an IP window is one shared bucket for every workspace on the platform: one
|
| 582 |
-
#: busy tenant would spend the allowance for all of them, and the symptom would be another
|
| 583 |
-
#: tenant's bot going quiet. The team id is the closest thing to the actual noisy party.
|
| 584 |
-
#: β It is attacker-CONTROLLED before the signature is checked, so the window is applied AFTER
|
| 585 |
-
#: verification, never before β an unsigned request is refused on cost grounds anyway (a signature
|
| 586 |
-
#: check is a single HMAC).
|
| 587 |
-
RATE_WINDOW_S, RATE_PER_WINDOW = 60, 60
|
| 588 |
-
_HITS: dict = {}
|
| 589 |
-
|
| 590 |
-
|
| 591 |
-
def _rate_ok(key, now):
|
| 592 |
-
seen = [t for t in _HITS.get(key, ()) if now - t < RATE_WINDOW_S]
|
| 593 |
-
seen.append(now)
|
| 594 |
-
_HITS[key] = seen
|
| 595 |
-
if len(_HITS) > 4096:
|
| 596 |
-
for k in [k for k, v in _HITS.items() if not v or now - v[-1] > RATE_WINDOW_S]:
|
| 597 |
-
_HITS.pop(k, None)
|
| 598 |
-
return len(seen) <= RATE_PER_WINDOW
|
| 599 |
-
|
| 600 |
-
|
| 601 |
-
async def _raw_body(request):
|
| 602 |
-
"""The body as RAW BYTES, capped.
|
| 603 |
-
|
| 604 |
-
ββ RAW, NOT PARSED, AND THAT IS NOT A STYLE CHOICE. Slack signs the literal string
|
| 605 |
-
`v0:{timestamp}:{body}` byte for byte. `routes_forms._bounded_body` β the function this is
|
| 606 |
-
otherwise copied from β returns only the parsed dict and DISCARDS the bytes, so a verbatim
|
| 607 |
-
copy of it could not verify a Slack signature at all: re-serialising the dict changes
|
| 608 |
-
whitespace and key order and the HMAC no longer matches. The bug would look like "Slack
|
| 609 |
-
signatures are always invalid", which is indistinguishable from a wrong secret.
|
| 610 |
-
|
| 611 |
-
β And it streams rather than calling `request.body()`: FastAPI would otherwise have buffered
|
| 612 |
-
the whole body before the handler's first line, so a content-length check inside the handler
|
| 613 |
-
caps nothing (`routes_forms`' own scar, recorded in its docstring).
|
| 614 |
-
"""
|
| 615 |
-
size, chunks = 0, []
|
| 616 |
-
async for chunk in request.stream():
|
| 617 |
-
size += len(chunk)
|
| 618 |
-
if size > MAX_BODY_BYTES:
|
| 619 |
-
raise err(413, "body_too_large", "that request is too large")
|
| 620 |
-
chunks.append(chunk)
|
| 621 |
-
return b"".join(chunks)
|
| 622 |
-
|
| 623 |
-
|
| 624 |
-
def _refuse():
|
| 625 |
-
"""ONE refusal for every reason. No oracle.
|
| 626 |
-
|
| 627 |
-
A wrong signature, a stale timestamp, an unknown team, an unconfigured tenant and a channel
|
| 628 |
-
with no agent all answer identically β otherwise the door tells an unauthenticated caller
|
| 629 |
-
which tenants exist and which channels are configured, which is the question it was built to
|
| 630 |
-
not answer. `routes_forms._refuse` takes the same posture for the same reason.
|
| 631 |
-
"""
|
| 632 |
-
return err(403, "bad_request", "that request could not be verified")
|
| 633 |
-
|
| 634 |
-
|
| 635 |
-
def _verify(secret, timestamp, raw, signature, now):
|
| 636 |
-
"""Slack's v0 signature, with the replay window checked FIRST."""
|
| 637 |
-
try:
|
| 638 |
-
ts = int(str(timestamp or "0"))
|
| 639 |
-
except ValueError:
|
| 640 |
-
return False
|
| 641 |
-
if abs(now - ts) > SLACK_MAX_SKEW_S:
|
| 642 |
-
return False
|
| 643 |
-
base = b"v0:" + str(ts).encode("ascii") + b":" + (raw or b"")
|
| 644 |
-
import hashlib
|
| 645 |
-
expected = "v0=" + hmac.new(str(secret).encode("utf-8"), base, hashlib.sha256).hexdigest()
|
| 646 |
-
return hmac.compare_digest(expected, str(signature or ""))
|
| 647 |
-
|
| 648 |
-
|
| 649 |
-
def _resolve_tenant(raw, timestamp, signature, now):
|
| 650 |
-
"""`(slug, runtime, creds)` for the tenant whose signing secret verifies this request.
|
| 651 |
-
|
| 652 |
-
β THE TENANT IS DECIDED BY THE SIGNATURE, NEVER BY THE PAYLOAD. A body-supplied `team_id`
|
| 653 |
-
would let an unauthenticated caller name the tenant it wants to be β the exact widening
|
| 654 |
-
`deps._user_for`'s tenant-equality check closes on the authenticated side. So every configured
|
| 655 |
-
tenant's secret is tried and the one that VERIFIES names the tenant.
|
| 656 |
-
|
| 657 |
-
β NO EARLY `break` ON A FAILED CANDIDATE and no per-tenant error: the loop's cost must not
|
| 658 |
-
depend on which tenant matched. `routes_forms._resolve` walks tenants the same way, for the
|
| 659 |
-
same reason β a public door has no session to ask.
|
| 660 |
-
"""
|
| 661 |
-
from harness import runtime as _rt
|
| 662 |
-
hit = None
|
| 663 |
-
try:
|
| 664 |
-
slugs = list(_rt.known_tenants())
|
| 665 |
-
except Exception: # noqa: BLE001
|
| 666 |
-
return None, None, None
|
| 667 |
-
for slug in slugs:
|
| 668 |
-
try:
|
| 669 |
-
rt = _rt.get_runtime(slug)
|
| 670 |
-
except Exception: # noqa: BLE001
|
| 671 |
-
continue
|
| 672 |
-
creds = slack_creds(rt)
|
| 673 |
-
if not creds:
|
| 674 |
-
continue
|
| 675 |
-
if _verify(creds.get("signing_secret"), timestamp, raw, signature, now) and hit is None:
|
| 676 |
-
hit = (slug, rt, creds)
|
| 677 |
-
return hit if hit else (None, None, None)
|
| 678 |
-
|
| 679 |
-
|
| 680 |
-
@router.post("/slack/events")
|
| 681 |
-
async def slack_events(request: Request):
|
| 682 |
-
"""Slack's Events API. UNAUTHENTICATED BY CONSTRUCTION β no `Depends(require_session)`.
|
| 683 |
-
|
| 684 |
-
β Built like `routes_forms.py`'s public door and not like OpenTag's: one process, no vendor,
|
| 685 |
-
no second runtime, no persistent outbound socket, and this tenant's Slack secret never leaves
|
| 686 |
-
this deployment (amendment A1).
|
| 687 |
-
"""
|
| 688 |
-
now = time.time()
|
| 689 |
-
raw = await _raw_body(request)
|
| 690 |
-
ts = request.headers.get("x-slack-request-timestamp")
|
| 691 |
-
sig = request.headers.get("x-slack-signature")
|
| 692 |
-
slug, rt, _creds = _resolve_tenant(raw, ts, sig, now)
|
| 693 |
-
if not rt:
|
| 694 |
-
raise _refuse()
|
| 695 |
-
|
| 696 |
-
try:
|
| 697 |
-
payload = json.loads(raw or b"{}")
|
| 698 |
-
except ValueError:
|
| 699 |
-
raise _refuse()
|
| 700 |
-
if not isinstance(payload, dict):
|
| 701 |
-
raise _refuse()
|
| 702 |
-
|
| 703 |
-
# Slack's one-time endpoint handshake. Answered ONLY after the signature verified β an
|
| 704 |
-
# unsigned challenge echo would confirm the endpoint exists to anyone who probes it.
|
| 705 |
-
if payload.get("type") == "url_verification":
|
| 706 |
-
return {"challenge": str(payload.get("challenge") or "")[:512]}
|
| 707 |
-
|
| 708 |
-
team = str(payload.get("team_id") or slug)
|
| 709 |
-
if not _rate_ok(f"{slug}:{team}", now):
|
| 710 |
-
raise err(429, "too_many_requests", "too many requests β wait a moment and try again")
|
| 711 |
-
|
| 712 |
-
event = payload.get("event") if isinstance(payload.get("event"), dict) else {}
|
| 713 |
-
channel = str(event.get("channel") or "")
|
| 714 |
-
agent = None
|
| 715 |
-
for a in _agents(rt).values():
|
| 716 |
-
if isinstance(a, dict) and str(a.get("channel") or "") == channel:
|
| 717 |
-
agent = a
|
| 718 |
-
break
|
| 719 |
-
# β NO AGENT, OR AN INACTIVE ONE, IS SILENCE β a 200 with no action. Not a 403: Slack retries
|
| 720 |
-
# a non-2xx up to three times, so refusing here would turn "this channel is not configured"
|
| 721 |
-
# into three refusals per message, and the retry storm would be the only visible symptom.
|
| 722 |
-
# β And it must not say WHICH β a distinguishable answer tells an unauthenticated caller which
|
| 723 |
-
# channels this workspace has configured.
|
| 724 |
-
if not isinstance(agent, dict) or agent.get("active", True) is False:
|
| 725 |
-
return {"ok": True}
|
| 726 |
-
|
| 727 |
-
# ββ THE ANSWERING HALF IS NOT BUILT YET, AND SAYING SO IS THE POINT. What ships here is the
|
| 728 |
-
# DOOR and the WALL: a verified request, resolved to a tenant by signature, matched to a
|
| 729 |
-
# channel agent whose `perms` block is a `perm_scope` principal (`agent_principal`). Composing
|
| 730 |
-
# a reply means an LLM call on the cheap-first ladder plus the read path, and a half-built
|
| 731 |
-
# answerer that returns something plausible is worse than one that returns nothing.
|
| 732 |
-
# Booked rather than faked [[flag-shipped-without-its-writer]].
|
| 733 |
-
return {"ok": True}
|
| 734 |
-
|
| 735 |
-
|
| 736 |
-
@router.post("/slack/interact")
|
| 737 |
-
async def slack_interact(request: Request):
|
| 738 |
-
"""The approval card's button (`W33-T67`). UNAUTHENTICATED, signature-verified, same shape."""
|
| 739 |
-
now = time.time()
|
| 740 |
-
raw = await _raw_body(request)
|
| 741 |
-
slug, rt, _creds = _resolve_tenant(raw, request.headers.get("x-slack-request-timestamp"),
|
| 742 |
-
request.headers.get("x-slack-signature"), now)
|
| 743 |
-
if not rt:
|
| 744 |
-
raise _refuse()
|
| 745 |
-
# Slack posts interactions as `application/x-www-form-urlencoded` with a `payload=` field.
|
| 746 |
-
from urllib.parse import parse_qs
|
| 747 |
-
try:
|
| 748 |
-
form = parse_qs(raw.decode("utf-8"))
|
| 749 |
-
payload = json.loads((form.get("payload") or ["{}"])[0])
|
| 750 |
-
except Exception: # noqa: BLE001
|
| 751 |
-
raise _refuse()
|
| 752 |
-
if not isinstance(payload, dict):
|
| 753 |
-
raise _refuse()
|
| 754 |
-
if not _rate_ok(f"{slug}:interact", now):
|
| 755 |
-
raise err(429, "too_many_requests", "too many requests β wait a moment and try again")
|
| 756 |
-
|
| 757 |
-
actions = payload.get("actions") if isinstance(payload.get("actions"), list) else []
|
| 758 |
-
choice = (actions[0] if actions and isinstance(actions[0], dict) else {})
|
| 759 |
-
token = str(choice.get("value") or "")
|
| 760 |
-
# β ANYTHING THAT IS NOT LITERALLY "approve" IS A REJECT. Fail-closed on a malformed,
|
| 761 |
-
# truncated or unknown action id: the direction that can be wrong here without anyone
|
| 762 |
-
# noticing is the one that writes.
|
| 763 |
-
approved = str(choice.get("action_id") or "") == "approve"
|
| 764 |
-
# β THE ROUTE DOES NOT DECIDE β `commit_pending` does, and it is the ONE seam a negative
|
| 765 |
-
# control can aim at. Consumption, the TTL, the reject branch and the committer lookup all
|
| 766 |
-
# live there; this handler only turns its verdict into a sentence.
|
| 767 |
-
verdict = commit_pending(rt, token, approved, now=now)
|
| 768 |
-
return {"text": {
|
| 769 |
-
# An unknown, already-used or expired token is not an error: a person clicking a stale
|
| 770 |
-
# card should be told it is stale, not shown a failure.
|
| 771 |
-
"unknown": "That approval is no longer available. Ask the bot again.",
|
| 772 |
-
"expired": "That approval expired before it was answered. Ask the bot again.",
|
| 773 |
-
"rejected": "Rejected. Nothing was changed.",
|
| 774 |
-
# β HONEST, not reassuring: the answering half that would register a committer is booked,
|
| 775 |
-
# so an approved card today performs nothing and says exactly that rather than "Approved."
|
| 776 |
-
"no_committer": "Approved β but this workspace has nothing configured to carry it out yet.",
|
| 777 |
-
"failed": "That change could not be completed. Nothing was saved; ask the bot again.",
|
| 778 |
-
"committed": "Approved.",
|
| 779 |
-
}.get(verdict, "That approval is no longer available. Ask the bot again.")}
|
| 780 |
-
|
| 781 |
-
|
| 782 |
-
@router.get("/slack/health")
|
| 783 |
-
def slack_health(session: Session = Depends(require_session)):
|
| 784 |
-
"""Is Slack configured for THIS tenant? Session-gated, and it answers about one tenant only β
|
| 785 |
-
enumerating the others would answer a question about our customer list."""
|
| 786 |
-
creds = slack_creds(session.runtime)
|
| 787 |
-
return {"configured": creds is not None,
|
| 788 |
-
"agents": len(_agents(session.runtime)),
|
| 789 |
-
"hasBotToken": bool((creds or {}).get("bot_token"))}
|
|
|
|
| 1 |
+
"""routes_slack.py β MANAGE AGENT: a bot per Slack channel, walled by the engine that walls a
|
| 2 |
+
person. (wave 33, owner item 10 Β· `W33-T38` / `W33-T39` / `W33-T67`.)
|
| 3 |
+
|
| 4 |
+
Owner, verbatim (2026-08-14): *"Expand Slack we need to be able to configure an AI bot PER channel
|
| 5 |
+
whose permissions we can toggle based on Fields etc of the databases, exactly like how we toggle
|
| 6 |
+
permissioning per user."*
|
| 7 |
+
|
| 8 |
+
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 9 |
+
ββ D-84 SAID THIS WAS "adapted from OpenTag" AND THAT PREMISE IS FALSE (PRD amendment A1).
|
| 10 |
+
|
| 11 |
+
`PENDING.md` D-84 has named OpenTag as the model for per-Slack-channel permissioning since
|
| 12 |
+
2026-08-08. **OpenTag has no permission model to adapt.** `app/runtime-host.ts` is
|
| 13 |
+
`identifyUser: () => OPENTAG_SERVICE_USER` β ONE constant identity for every request β and its own
|
| 14 |
+
`sender-context.ts` says the Slack sender is *"informational only⦠not gating access."* Its
|
| 15 |
+
authorization ceiling is whole-MCP-server, decided once at process boot from env vars. It is a
|
| 16 |
+
live specimen of identity that LOOKS like a permission and is not.
|
| 17 |
+
|
| 18 |
+
`core/perm_scope.py` is already strictly more expressive: per database, per row, per FIELD, per
|
| 19 |
+
principal. So item 10 is OUR engine projected onto a CHANNEL principal β see `agent_principal`
|
| 20 |
+
below, which is the whole projection and is nine lines. Study:
|
| 21 |
+
`.claude/wiki/research/opentag-adoption.md` (licence gate: MIT, PASSED).
|
| 22 |
+
|
| 23 |
+
What OpenTag genuinely contributes is the WRITE-APPROVAL interceptor (`W33-T67`, `approval_card`
|
| 24 |
+
below) and nothing else. Its TRANSPORT is AVOID wholesale β hosted CopilotKit Intelligence, a
|
| 25 |
+
second Node process, a persistent outbound socket and each tenant's Slack credentials held by a
|
| 26 |
+
third party, against ONE process on the HF free tier. The door here is `routes_forms.py`'s proven
|
| 27 |
+
unauthenticated-public shape plus Slack's signing-secret check.
|
| 28 |
+
|
| 29 |
+
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 30 |
+
β A CHANNEL IS A PRINCIPAL, NOT A PERSON. The wall binds to the Slack conversation id, so every
|
| 31 |
+
human in that channel reads through the same rules. That is the honest reading of "a bot per
|
| 32 |
+
channel" and the pane says it out loud, because the alternative is an admin assuming per-person
|
| 33 |
+
scoping from a screen that looks exactly like the per-person one.
|
| 34 |
+
|
| 35 |
+
β AND THE IDENTITY IS THE CHANNEL ID, NEVER ITS NAME. A channel can be renamed; its id cannot.
|
| 36 |
+
A wall bound to `#sales` silently re-points the day somebody renames the channel.
|
| 37 |
+
"""
|
| 38 |
+
import hmac
|
| 39 |
+
import json
|
| 40 |
+
import os
|
| 41 |
+
import secrets
|
| 42 |
+
import time
|
| 43 |
+
from datetime import datetime, timezone
|
| 44 |
+
|
| 45 |
+
from fastapi import APIRouter, Body, Depends, Request
|
| 46 |
+
|
| 47 |
+
from deps import Session, err, require_session
|
| 48 |
+
from routes_admin import admin_gate
|
| 49 |
+
|
| 50 |
+
router = APIRouter(prefix="/api/v1")
|
| 51 |
+
|
| 52 |
+
#: The tenant's channel agents: `{id: record}`. A per-tenant bucket, so it rides
|
| 53 |
+
#: `runtime.store_key`'s prefix and never lands in tenant #0's namespace.
|
| 54 |
+
AGENTS_KEY = "slack_agents"
|
| 55 |
+
|
| 56 |
+
#: Pending mutations awaiting a human's click (`W33-T67`). Server-only, per tenant.
|
| 57 |
+
PENDING_KEY = "slack_pending_writes"
|
| 58 |
+
|
| 59 |
+
#: How long an approval card stays clickable. An approval is a statement about the world as it was
|
| 60 |
+
#: when the card was rendered; an hour later the values it names may no longer be the values it
|
| 61 |
+
#: would write. Expiring is the honest behaviour, and an expired card says so rather than 403ing.
|
| 62 |
+
APPROVAL_TTL_S = 15 * 60
|
| 63 |
+
|
| 64 |
+
#: Slack rejects a replayed request older than 5 minutes; so do we, before any signature work.
|
| 65 |
+
SLACK_MAX_SKEW_S = 60 * 5
|
| 66 |
+
|
| 67 |
+
MAX_BODY_BYTES = 64 * 1024
|
| 68 |
+
|
| 69 |
+
#: β ROW-CAPPED BECAUSE AN APPROVER WHO CANNOT READ THE CARD CANNOT APPROVE IT. Copied
|
| 70 |
+
#: deliberately from OpenTag's `agent/write_confirmation.py`, which caps for the same reason:
|
| 71 |
+
#: past a certain length Slack collapses a message behind "Show more", and a human clicking
|
| 72 |
+
#: Approve on a card whose tail they never saw is worse than no card at all.
|
| 73 |
+
APPROVAL_MAX_ROWS = 12
|
| 74 |
+
|
| 75 |
+
|
| 76 |
+
# ββ the tenant's agent records βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 77 |
+
def _agents(rt):
|
| 78 |
+
"""`{id: record}` for one tenant. `{}` on any failure β an unreadable bucket must degrade to
|
| 79 |
+
"this tenant has no agents", never to a 500 on the settings pane."""
|
| 80 |
+
try:
|
| 81 |
+
found = rt.get(AGENTS_KEY) or {}
|
| 82 |
+
except Exception: # noqa: BLE001
|
| 83 |
+
return {}
|
| 84 |
+
return found if isinstance(found, dict) else {}
|
| 85 |
+
|
| 86 |
+
|
| 87 |
+
def _clean_agent(raw, prior=None):
|
| 88 |
+
"""One stored record, built KEY BY KEY.
|
| 89 |
+
|
| 90 |
+
β Never `dict(raw)` and never `**raw`. This record is the SUBJECT of a permission decision;
|
| 91 |
+
a client-supplied key landing in it is a client-supplied input to `perm_scope`. The same rule
|
| 92 |
+
`routes_forms._public_form` follows on the way out, applied here on the way in.
|
| 93 |
+
"""
|
| 94 |
+
prior = prior if isinstance(prior, dict) else {}
|
| 95 |
+
out = {
|
| 96 |
+
"id": str(prior.get("id") or raw.get("id") or ""),
|
| 97 |
+
"channel": str(raw.get("channel") or prior.get("channel") or "").strip()[:64],
|
| 98 |
+
"channelName": str(raw.get("channelName") or prior.get("channelName") or "").strip()[:80],
|
| 99 |
+
"label": " ".join(str(raw.get("label") or prior.get("label") or "").split())[:80],
|
| 100 |
+
"active": bool(raw.get("active", prior.get("active", True))),
|
| 101 |
+
# β DEFAULT TRUE, AND `is not False` RATHER THAN TRUTHINESS. A record written before this
|
| 102 |
+
# key existed must read as "approval required": the one direction a default here is
|
| 103 |
+
# allowed to be wrong in is the safe one, because an unattended write cannot be undone by
|
| 104 |
+
# revoking the bot afterwards [[default-must-pass-its-own-guard]].
|
| 105 |
+
"writeApproval": raw.get("writeApproval", prior.get("writeApproval", True)) is not False,
|
| 106 |
+
# The permission block. Same shape, same validator, same engine as a user's.
|
| 107 |
+
"perms": prior.get("perms") if isinstance(prior.get("perms"), dict) else {},
|
| 108 |
+
"perms_v": int(prior.get("perms_v") or 0),
|
| 109 |
+
"createdBy": str(prior.get("createdBy") or raw.get("createdBy") or ""),
|
| 110 |
+
"createdAt": str(prior.get("createdAt") or raw.get("createdAt") or ""),
|
| 111 |
+
}
|
| 112 |
+
return out
|
| 113 |
+
|
| 114 |
+
|
| 115 |
+
def _put_agent(session, agent_id, mutate):
|
| 116 |
+
"""Read-modify-write ONE agent under the tenant's bucket, synchronously.
|
| 117 |
+
|
| 118 |
+
`flush="sync"` because the client re-reads the list immediately after every write here, and an
|
| 119 |
+
async flush would let the refetch win the race and paint the pre-write state β the
|
| 120 |
+
[[refetch-eats-its-own-write]] shape.
|
| 121 |
+
"""
|
| 122 |
+
def _set(cur):
|
| 123 |
+
cur = dict(cur or {})
|
| 124 |
+
rec = cur.get(agent_id) if isinstance(cur.get(agent_id), dict) else None
|
| 125 |
+
nxt = mutate(rec)
|
| 126 |
+
if nxt is None:
|
| 127 |
+
cur.pop(agent_id, None)
|
| 128 |
+
else:
|
| 129 |
+
cur[agent_id] = nxt
|
| 130 |
+
return cur
|
| 131 |
+
|
| 132 |
+
session.runtime.update(AGENTS_KEY, _set, flush="sync")
|
| 133 |
+
|
| 134 |
+
|
| 135 |
+
# ββ ββ THE PROJECTION β THE WHOLE OF "the same engine that permissions a user" βββββββββββββββ
|
| 136 |
+
def agent_principal(agent):
|
| 137 |
+
"""A channel agent, as a PRINCIPAL `core/perm_scope` already understands.
|
| 138 |
+
|
| 139 |
+
ββ THIS IS THE ENTIRE POINT OF THE TICKET AND IT IS NINE LINES. `perm_scope` takes a user
|
| 140 |
+
RECORD β a plain dict with `perms`, `perms_v` and `role` β not a User object and not a session.
|
| 141 |
+
So a channel agent carrying a `perms` block simply IS such a record, and `may_access`,
|
| 142 |
+
`visible_fields`, `hidden_keys` and `apply_row_scope` work on it unmodified. There is no second
|
| 143 |
+
engine, no parallel vocabulary, and nothing about a channel to keep in step with anything about
|
| 144 |
+
a person. That is what the owner's *"exactly like how we toggle permissioning per user"* means
|
| 145 |
+
when it is true in code rather than in appearance.
|
| 146 |
+
|
| 147 |
+
β `role` IS HARDCODED NON-ADMIN AND MUST STAY SO. `perm_scope.may_access` returns True
|
| 148 |
+
unconditionally for `role == 'admin'` β the break-glass clause that keeps the owner out of a
|
| 149 |
+
locked store. A bot has no such emergency and no hands: an agent record that could carry
|
| 150 |
+
`role: 'admin'` would be one stored key away from bypassing every wall on this page. The key is
|
| 151 |
+
not copied from the record; it is written here, every time.
|
| 152 |
+
|
| 153 |
+
β AND `perms_v` IS FORCED TO THE CURRENT VERSION, which makes an UNDECLARED database DENY
|
| 154 |
+
(C-PERM amendment 4). Without it a fresh agent would fall through to `perms.may_open`'s legacy
|
| 155 |
+
grant wall and read `modules: 'all'`-shaped defaults β i.e. a brand-new bot would start with
|
| 156 |
+
access to everything. Fail-closed from the first byte.
|
| 157 |
+
"""
|
| 158 |
+
import core.perm_scope as perm_scope
|
| 159 |
+
return {
|
| 160 |
+
"username": f"slack:{(agent or {}).get('channel') or '?'}",
|
| 161 |
+
"role": "agent",
|
| 162 |
+
"perms": (agent or {}).get("perms") or {},
|
| 163 |
+
"perms_v": perm_scope.PERMS_VERSION,
|
| 164 |
+
# No `bus`, no `agent`: a channel is not a business unit and not a salesperson. Absent
|
| 165 |
+
# rather than 'all' β `perms.allowed_bu_labels` narrows on absence, which is the direction
|
| 166 |
+
# this must fail in.
|
| 167 |
+
}
|
| 168 |
+
|
| 169 |
+
|
| 170 |
+
def agent_may_read(agent, module):
|
| 171 |
+
"""May this channel open `module` at all?"""
|
| 172 |
+
import core.perm_scope as perm_scope
|
| 173 |
+
if not (agent or {}).get("active", True):
|
| 174 |
+
return False
|
| 175 |
+
return bool(perm_scope.may_access(agent_principal(agent), module))
|
| 176 |
+
|
| 177 |
+
|
| 178 |
+
def agent_visible_fields(agent, fields, module):
|
| 179 |
+
"""`fields` minus this channel's hidden closure β the SAME transitive closure a person gets,
|
| 180 |
+
so a formula over a hidden column cannot leak it back through arithmetic."""
|
| 181 |
+
import core.perm_scope as perm_scope
|
| 182 |
+
return perm_scope.visible_fields(fields, agent_principal(agent), module)
|
| 183 |
+
|
| 184 |
+
|
| 185 |
+
def agent_rows(agent, rows, module, fields, ctx=None, st=None):
|
| 186 |
+
"""The rows this channel may receive β `permits()`, so an unanswerable permanent filter DENIES
|
| 187 |
+
rather than being ignored.
|
| 188 |
+
|
| 189 |
+
ββ `st` IS THE TENANT HANDLE AND IT IS HERE BECAUSE OF THE SENTENCE IN `agent_principal`:
|
| 190 |
+
a channel agent IS a principal of the same wall, so a permanent filter naming a
|
| 191 |
+
user-generated column has to mean the SAME thing here as it does on the grid (owner I16).
|
| 192 |
+
A door that lends the handle and a door that does not are one stored rule with two meanings.
|
| 193 |
+
|
| 194 |
+
β PASS THE TENANT'S OWN RUNTIME β every other store read in this file takes
|
| 195 |
+
`session.runtime`, and a channel is not a second tenancy. It is a keyword with a `None`
|
| 196 |
+
default for the same reason `perm_scope.apply_row_scope`'s is: without one this is
|
| 197 |
+
byte-identical to the wall that shipped before the argument existed.
|
| 198 |
+
|
| 199 |
+
β `hidden_keys` DELIBERATELY DOES NOT TAKE IT IN THIS CHANGE. Its field-grant leg
|
| 200 |
+
under-hides without a handle (see `perm_scope.visible_overlays`), which is a real and
|
| 201 |
+
separate gap on this surface β but it is the FIELD wall, it moves what a channel receives
|
| 202 |
+
rather than what I16 asked for, and widening two walls in one ticket is how a permission
|
| 203 |
+
change stops being reviewable.
|
| 204 |
+
"""
|
| 205 |
+
import core.perm_scope as perm_scope
|
| 206 |
+
p = agent_principal(agent)
|
| 207 |
+
hide = perm_scope.hidden_keys(p, module, fields)
|
| 208 |
+
kept = perm_scope.apply_row_scope(rows, p, module, fields, ctx, st=st)
|
| 209 |
+
# Both wires, never one: the field list and the row payload are separate, and stripping only
|
| 210 |
+
# the first leaves the value sitting in the second where anyone can read it.
|
| 211 |
+
return [perm_scope.strip_row(r, hide) for r in kept]
|
| 212 |
+
|
| 213 |
+
|
| 214 |
+
# ββ the credential βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 215 |
+
def slack_creds(rt):
|
| 216 |
+
"""This TENANT's Slack credentials from its own keychain, or None.
|
| 217 |
+
|
| 218 |
+
β NO ENVIRONMENT FALLBACK, DELIBERATELY, AND THIS IS D-202's LESSON APPLIED BEFORE IT
|
| 219 |
+
HAPPENS AGAIN. Meta Ads shipped loading end-to-end and was still not a connector, because
|
| 220 |
+
`keychain.meta_creds` had no caller and the token came from the owner's `.env` β making it a
|
| 221 |
+
tenant-#0 FACT indistinguishable from a screenshot. `keychain.meta_creds`' own docstring spells
|
| 222 |
+
out the rule: handing the environment's credential to a tenant whose admin has not stored one
|
| 223 |
+
is the leak the resolver exists to prevent. So a tenant with no entry gets None and the pane
|
| 224 |
+
SAYS so.
|
| 225 |
+
|
| 226 |
+
β Reads through `list_entries` + `read_fields` (both public) rather than `keychain._first_creds`
|
| 227 |
+
(private, and in a file outside this lane's fence). Same deterministic rule: entries are
|
| 228 |
+
id-sorted, so "first" is stable across reads rather than dict-order luck.
|
| 229 |
+
"""
|
| 230 |
+
try:
|
| 231 |
+
import core.keychain as keychain
|
| 232 |
+
for row in keychain.list_entries(rt):
|
| 233 |
+
if str(row.get("type") or "") != "slack":
|
| 234 |
+
continue
|
| 235 |
+
fields = keychain.read_fields(rt, row.get("id"))
|
| 236 |
+
if isinstance(fields, dict) and fields.get("signing_secret"):
|
| 237 |
+
return fields
|
| 238 |
+
except Exception: # noqa: BLE001
|
| 239 |
+
# A locked or unreadable keychain reads as "not configured" for the PANE, which is honest;
|
| 240 |
+
# the signature check below fails closed regardless, so this cannot widen anything.
|
| 241 |
+
return None
|
| 242 |
+
return None
|
| 243 |
+
|
| 244 |
+
|
| 245 |
+
# ββ the authenticated doors (the Manage agent surface) βββββββββββββββββββββββββββββββββββββββ
|
| 246 |
+
def _summary(agent, modules):
|
| 247 |
+
"""One sentence per agent for the list row β computed here, because the alternative is one
|
| 248 |
+
round trip per row to fill one cell (the same reason `AdminUser.access` exists)."""
|
| 249 |
+
# β W36-T22 / C2 β every listed database is governed now; the `enforced` flag it used to
|
| 250 |
+
# filter on is DELETED, and `m.get("enforced")` would have gone silently falsy here and
|
| 251 |
+
# summarised every agent as "" (no databases at all).
|
| 252 |
+
governed = list(modules)
|
| 253 |
+
perms = agent.get("perms") or {}
|
| 254 |
+
open_n = sum(1 for m in governed if (perms.get(m["key"]) or {}).get("access"))
|
| 255 |
+
if not governed:
|
| 256 |
+
return ""
|
| 257 |
+
if open_n == 0:
|
| 258 |
+
return "No access"
|
| 259 |
+
restricted = sum(1 for m in governed
|
| 260 |
+
if (perms.get(m["key"]) or {}).get("access")
|
| 261 |
+
and ((perms.get(m["key"]) or {}).get("filter")
|
| 262 |
+
or (perms.get(m["key"]) or {}).get("hiddenFields")))
|
| 263 |
+
head = (f"All {open_n} database{'' if open_n == 1 else 's'}" if open_n == len(governed)
|
| 264 |
+
else f"{open_n} of {len(governed)} databases")
|
| 265 |
+
return f"{head}, {restricted} restricted" if restricted else head
|
| 266 |
+
|
| 267 |
+
|
| 268 |
+
@router.get("/agents")
|
| 269 |
+
def list_channel_agents(session: Session = Depends(admin_gate)):
|
| 270 |
+
"""This tenant's channel agents, plus whether Slack is reachable at all."""
|
| 271 |
+
import routes_admin
|
| 272 |
+
modules = routes_admin._perm_modules(session)
|
| 273 |
+
rows = []
|
| 274 |
+
for aid, a in sorted(_agents(session.runtime).items()):
|
| 275 |
+
if not isinstance(a, dict):
|
| 276 |
+
continue
|
| 277 |
+
rows.append({"id": aid, "channel": a.get("channel") or "",
|
| 278 |
+
"channelName": a.get("channelName") or "",
|
| 279 |
+
"label": a.get("label") or "", "active": a.get("active", True) is not False,
|
| 280 |
+
"writeApproval": a.get("writeApproval", True) is not False,
|
| 281 |
+
"summary": _summary(a, modules)})
|
| 282 |
+
return {"agents": rows, "configured": slack_creds(session.runtime) is not None}
|
| 283 |
+
|
| 284 |
+
|
| 285 |
+
@router.post("/agents")
|
| 286 |
+
def create_channel_agent(body: dict = Body(default=None),
|
| 287 |
+
session: Session = Depends(admin_gate)):
|
| 288 |
+
body = body if isinstance(body, dict) else {}
|
| 289 |
+
channel = str(body.get("channel") or "").strip()
|
| 290 |
+
if not channel:
|
| 291 |
+
raise err(400, "no_channel", "a Slack channel ID is required")
|
| 292 |
+
existing = _agents(session.runtime)
|
| 293 |
+
# β ONE AGENT PER CHANNEL. Two records for one conversation would mean two walls, and nothing
|
| 294 |
+
# anywhere decides which one applies β the [[one-question-two-normalizers]] shape, in the one
|
| 295 |
+
# place where the two answers are "may read" and "may not".
|
| 296 |
+
for a in existing.values():
|
| 297 |
+
if isinstance(a, dict) and str(a.get("channel") or "") == channel:
|
| 298 |
+
raise err(409, "channel_taken",
|
| 299 |
+
"that channel already has an agent β edit it instead of adding a second")
|
| 300 |
+
aid = secrets.token_urlsafe(9)
|
| 301 |
+
rec = _clean_agent(dict(body, id=aid, createdBy=session.uname,
|
| 302 |
+
createdAt=datetime.now(timezone.utc).isoformat(timespec="seconds")))
|
| 303 |
+
_put_agent(session, aid, lambda _prior: rec)
|
| 304 |
+
fresh = _agents(session.runtime).get(aid)
|
| 305 |
+
if not isinstance(fresh, dict):
|
| 306 |
+
# The store took the write and did not record it. A 200 here would tell an administrator
|
| 307 |
+
# the agent exists when it does not.
|
| 308 |
+
raise err(503, "store_unavailable", "the agent was NOT created")
|
| 309 |
+
return {"agent": {"id": aid, "channel": rec["channel"], "channelName": rec["channelName"],
|
| 310 |
+
"label": rec["label"], "active": rec["active"],
|
| 311 |
+
"writeApproval": rec["writeApproval"], "summary": "No access"}}
|
| 312 |
+
|
| 313 |
+
|
| 314 |
+
@router.get("/agents/{agent_id}")
|
| 315 |
+
def get_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
|
| 316 |
+
"""The agent PLUS the permission envelope β the SAME shape `get_perms` answers with.
|
| 317 |
+
|
| 318 |
+
β ONE PAYLOAD SHAPE FOR TWO ROOMS. `permsModel.parsePermsPayload` parses this, and
|
| 319 |
+
`settings/ModulePermsList` renders it, because they are literally the same client code. A
|
| 320 |
+
second envelope here would mean a second parser and a second set of defaults within a wave.
|
| 321 |
+
"""
|
| 322 |
+
import routes_admin
|
| 323 |
+
a = _agents(session.runtime).get(str(agent_id))
|
| 324 |
+
if not isinstance(a, dict):
|
| 325 |
+
raise err(404, "no_such_agent", "no agent with that id")
|
| 326 |
+
modules = routes_admin._perm_modules(session)
|
| 327 |
+
# ββ W36-T22 / C2 β EVERY listed database, `ut_*` included. β THIS IS WHY THE FLAG'S
|
| 328 |
+
# DELETION IS NOT A ONE-FILE CHANGE: `m.get("enforced")` on a row that no longer carries the
|
| 329 |
+
# key is None, so this list would have been EMPTY and the channel perms editor would have
|
| 330 |
+
# governed ZERO databases while looking entirely correct. A Slack channel is a principal of
|
| 331 |
+
# the SAME wall (`verify_perm_scope` section H) and gets the same catalogue.
|
| 332 |
+
governed = [m["key"] for m in modules]
|
| 333 |
+
stored = a.get("perms") or {}
|
| 334 |
+
principal = agent_principal(a)
|
| 335 |
+
import core.perm_scope as perm_scope
|
| 336 |
+
perms_out = {}
|
| 337 |
+
for k in governed:
|
| 338 |
+
e = stored.get(k)
|
| 339 |
+
# β W36-T22 β `may_read`, the same evaluator the read door uses, for the reason spelled
|
| 340 |
+
# out at `routes_admin.get_perms`. β It answers DIFFERENTLY here and correctly so: a
|
| 341 |
+
# channel agent is not a person with a share, so a `ut_*` key it has not been granted
|
| 342 |
+
# defaults CLOSED β which is the fail-closed direction for a bot, and the same answer the
|
| 343 |
+
# table routes would give it.
|
| 344 |
+
perms_out[k] = e if isinstance(e, dict) else {
|
| 345 |
+
"access": bool(perm_scope.may_read(principal, k, st=session.runtime)),
|
| 346 |
+
"filter": None, "hiddenFields": []}
|
| 347 |
+
return {"id": str(agent_id), "channel": a.get("channel") or "",
|
| 348 |
+
"channelName": a.get("channelName") or "", "label": a.get("label") or "",
|
| 349 |
+
"active": a.get("active", True) is not False,
|
| 350 |
+
"writeApproval": a.get("writeApproval", True) is not False,
|
| 351 |
+
"perms": perms_out,
|
| 352 |
+
# β ALWAYS THE CURRENT VERSION, because `agent_principal` forces it: the editor must
|
| 353 |
+
# render "undeclared = denied", not the legacy-grant reading it would show at 0.
|
| 354 |
+
"perms_v": perm_scope.PERMS_VERSION,
|
| 355 |
+
# A bot is NEVER an admin β see `agent_principal`. Sent so the editor never paints
|
| 356 |
+
# the "Everything (admin)" state for a principal that cannot have it.
|
| 357 |
+
"is_admin": False,
|
| 358 |
+
"modules": modules,
|
| 359 |
+
"fields_by_module": {k: routes_admin._module_fields(k, session=session)
|
| 360 |
+
for k in governed}}
|
| 361 |
+
|
| 362 |
+
|
| 363 |
+
@router.put("/agents/{agent_id}/perms")
|
| 364 |
+
def put_channel_agent_perms(agent_id: str, body: dict = Body(default=None),
|
| 365 |
+
session: Session = Depends(admin_gate)):
|
| 366 |
+
"""Replace this agent's permission block wholesale β the same validator a user's block gets."""
|
| 367 |
+
import routes_admin
|
| 368 |
+
body = body if isinstance(body, dict) else {}
|
| 369 |
+
if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 370 |
+
raise err(404, "no_such_agent", "no agent with that id")
|
| 371 |
+
if "perms" not in body:
|
| 372 |
+
raise err(400, "empty_patch", "no perms to save")
|
| 373 |
+
mods = routes_admin._perm_modules(session)
|
| 374 |
+
# β THE SAME `_clean_perms`, NOT A COPY OF IT. It refuses a filter this module cannot
|
| 375 |
+
# evaluate, refuses a hiddenFields key that names nothing, and refuses a BU condition the
|
| 376 |
+
# pushdown cannot read. Every one of those is exactly as true for a channel as for a person,
|
| 377 |
+
# and a second validator here is a second place for one of them to go missing.
|
| 378 |
+
# β CORRECTED W36-T22: this list used to end "refuses an unenforced `ut_*` key". That refusal
|
| 379 |
+
# is DELETED β W36-T21 armed the wall over every database, so there is no unenforced key left
|
| 380 |
+
# to refuse, and a comment naming a rule that no longer exists is how the next wave re-derives
|
| 381 |
+
# it ([[two-gates-can-assert-opposite-things]]).
|
| 382 |
+
cleaned = routes_admin._clean_perms(
|
| 383 |
+
body.get("perms"),
|
| 384 |
+
governed_keys={m["key"] for m in mods}, session=session) or {}
|
| 385 |
+
|
| 386 |
+
import core.perm_scope as perm_scope
|
| 387 |
+
|
| 388 |
+
def _mut(prior):
|
| 389 |
+
if not isinstance(prior, dict):
|
| 390 |
+
return None
|
| 391 |
+
nxt = dict(prior)
|
| 392 |
+
nxt["perms"] = cleaned
|
| 393 |
+
nxt["perms_v"] = perm_scope.PERMS_VERSION
|
| 394 |
+
return nxt
|
| 395 |
+
|
| 396 |
+
_put_agent(session, str(agent_id), _mut)
|
| 397 |
+
fresh = _agents(session.runtime).get(str(agent_id)) or {}
|
| 398 |
+
if (fresh.get("perms") or {}) != cleaned:
|
| 399 |
+
# The one direction this must never fail in: telling an administrator the wall is up when
|
| 400 |
+
# it is not.
|
| 401 |
+
raise err(503, "store_unavailable", "the permissions were not saved β the agent is UNCHANGED")
|
| 402 |
+
return {"id": str(agent_id), "perms": fresh.get("perms") or {},
|
| 403 |
+
"perms_v": int(fresh.get("perms_v") or 0)}
|
| 404 |
+
|
| 405 |
+
|
| 406 |
+
@router.patch("/agents/{agent_id}")
|
| 407 |
+
def patch_channel_agent(agent_id: str, body: dict = Body(default=None),
|
| 408 |
+
session: Session = Depends(admin_gate)):
|
| 409 |
+
body = body if isinstance(body, dict) else {}
|
| 410 |
+
if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 411 |
+
raise err(404, "no_such_agent", "no agent with that id")
|
| 412 |
+
#: β `perms` IS NOT PATCHABLE HERE. It has its own door with its own validator; accepting it
|
| 413 |
+
#: on the metadata route would be a second, unvalidated way to write the wall.
|
| 414 |
+
allowed = {k: v for k, v in body.items()
|
| 415 |
+
if k in ("label", "active", "writeApproval", "channelName")}
|
| 416 |
+
if not allowed:
|
| 417 |
+
raise err(400, "empty_patch", "nothing to change")
|
| 418 |
+
|
| 419 |
+
def _mut(prior):
|
| 420 |
+
return _clean_agent(allowed, prior=prior) if isinstance(prior, dict) else None
|
| 421 |
+
|
| 422 |
+
_put_agent(session, str(agent_id), _mut)
|
| 423 |
+
import routes_admin
|
| 424 |
+
a = _agents(session.runtime).get(str(agent_id)) or {}
|
| 425 |
+
return {"agent": {"id": str(agent_id), "channel": a.get("channel") or "",
|
| 426 |
+
"channelName": a.get("channelName") or "", "label": a.get("label") or "",
|
| 427 |
+
"active": a.get("active", True) is not False,
|
| 428 |
+
"writeApproval": a.get("writeApproval", True) is not False,
|
| 429 |
+
"summary": _summary(a, routes_admin._perm_modules(session))}}
|
| 430 |
+
|
| 431 |
+
|
| 432 |
+
@router.delete("/agents/{agent_id}")
|
| 433 |
+
def delete_channel_agent(agent_id: str, session: Session = Depends(admin_gate)):
|
| 434 |
+
if not isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 435 |
+
raise err(404, "no_such_agent", "no agent with that id")
|
| 436 |
+
_put_agent(session, str(agent_id), lambda _prior: None)
|
| 437 |
+
if isinstance(_agents(session.runtime).get(str(agent_id)), dict):
|
| 438 |
+
raise err(503, "store_unavailable", "the agent was NOT removed")
|
| 439 |
+
return {"ok": True}
|
| 440 |
+
|
| 441 |
+
|
| 442 |
+
# ββ β W33-T67: THE WRITE-APPROVAL GATE βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 443 |
+
def _is_empty(value):
|
| 444 |
+
"""Is this value ABSENT, as opposed to falsy?
|
| 445 |
+
|
| 446 |
+
β COPIED EXACTLY FROM OpenTag's `agent/write_confirmation.py`, and the exactness is the point:
|
| 447 |
+
`0` and `False` are VALUES a human must see on the card. Setting a price to 0 or a flag to
|
| 448 |
+
False is precisely the kind of write somebody needs to approve, and a naive `if not value`
|
| 449 |
+
drops both rows silently β the approver then reads a card that does not describe the write
|
| 450 |
+
they are approving. The MIT licence gate for this borrowing is recorded in
|
| 451 |
+
`.claude/wiki/research/opentag-adoption.md`.
|
| 452 |
+
"""
|
| 453 |
+
return value is None or (isinstance(value, str) and value.strip() == "")
|
| 454 |
+
|
| 455 |
+
|
| 456 |
+
def approval_card(action, values, agent=None):
|
| 457 |
+
"""The card a human reads before a bot writes. `{action, rows, truncated, note}`.
|
| 458 |
+
|
| 459 |
+
β ROW-CAPPED, and the cap is a SAFETY property rather than a layout one: past a certain
|
| 460 |
+
length Slack collapses a message behind "Show more", and **an approver who cannot read the
|
| 461 |
+
card cannot approve it.** When rows are dropped the card SAYS how many β a truncation nobody
|
| 462 |
+
was told about is the violation, not the truncation (wave-30 R6's second sentence).
|
| 463 |
+
"""
|
| 464 |
+
rows = [{"field": str(k), "value": v}
|
| 465 |
+
for k, v in (values or {}).items() if not _is_empty(v)]
|
| 466 |
+
rows.sort(key=lambda r: r["field"])
|
| 467 |
+
shown, dropped = rows[:APPROVAL_MAX_ROWS], max(0, len(rows) - APPROVAL_MAX_ROWS)
|
| 468 |
+
return {
|
| 469 |
+
"action": str(action or "")[:80],
|
| 470 |
+
"rows": shown,
|
| 471 |
+
"truncated": dropped,
|
| 472 |
+
"note": (f"{dropped} more field(s) not shown β open the record to review them before "
|
| 473 |
+
f"approving." if dropped else ""),
|
| 474 |
+
"agent": (agent or {}).get("label") or (agent or {}).get("channel") or "",
|
| 475 |
+
}
|
| 476 |
+
|
| 477 |
+
|
| 478 |
+
def intercept_write(agent, action, values, stash):
|
| 479 |
+
"""THE INTERCEPTOR. Returns `("commit", None)` or `("await_approval", card)`.
|
| 480 |
+
|
| 481 |
+
β The one thing worth taking from OpenTag: a MUTATING tool call is halted, rendered as a card
|
| 482 |
+
naming the action and its values, and committed only on an explicit human accept. Everything
|
| 483 |
+
else in that repo β the transport, the runtime, the identity model β is AVOID (amendment A1).
|
| 484 |
+
|
| 485 |
+
β FAIL-CLOSED ON A MISSING FLAG: `is not False`, so a record written before `writeApproval`
|
| 486 |
+
existed requires approval. The unsafe direction here is not recoverable β revoking a bot does
|
| 487 |
+
not un-write what it wrote.
|
| 488 |
+
"""
|
| 489 |
+
if (agent or {}).get("writeApproval", True) is not False:
|
| 490 |
+
card = approval_card(action, values, agent)
|
| 491 |
+
stash(card)
|
| 492 |
+
return "await_approval", card
|
| 493 |
+
return "commit", None
|
| 494 |
+
|
| 495 |
+
|
| 496 |
+
def _pending(rt):
|
| 497 |
+
try:
|
| 498 |
+
found = rt.get(PENDING_KEY) or {}
|
| 499 |
+
except Exception: # noqa: BLE001
|
| 500 |
+
return {}
|
| 501 |
+
return found if isinstance(found, dict) else {}
|
| 502 |
+
|
| 503 |
+
|
| 504 |
+
def stash_pending(rt, agent, action, values, now=None):
|
| 505 |
+
"""Store one awaiting-approval mutation and return its token.
|
| 506 |
+
|
| 507 |
+
The token is what rides the card's button, so it is `secrets.token_urlsafe` and not the
|
| 508 |
+
action's id: a guessable value on an unauthenticated door is a way to approve somebody else's
|
| 509 |
+
write. Server-only bucket, per tenant, exactly as `routes_forms.TOKENS_KEY` is.
|
| 510 |
+
"""
|
| 511 |
+
token = secrets.token_urlsafe(18)
|
| 512 |
+
row = {"at": float(now if now is not None else time.time()),
|
| 513 |
+
"channel": str((agent or {}).get("channel") or ""),
|
| 514 |
+
"action": str(action or "")[:80],
|
| 515 |
+
"values": values if isinstance(values, dict) else {}}
|
| 516 |
+
rt.update(PENDING_KEY, lambda cur: {**(cur or {}), token: row}, flush="sync")
|
| 517 |
+
return token
|
| 518 |
+
|
| 519 |
+
|
| 520 |
+
#: `{action kind: fn(rt, row) -> None}`. Registered by whatever can actually perform a mutation.
|
| 521 |
+
#:
|
| 522 |
+
#: ββ EMPTY IN PRODUCTION TODAY, AND SAYING SO IS THE POINT. `commit_pending` below is the ONE
|
| 523 |
+
#: place an approved write may be performed, so it is the place a negative control can bite β but
|
| 524 |
+
#: a gate is only as honest as what it guards. Until something registers here, an approved card
|
| 525 |
+
#: performs NOTHING and `commit_pending` returns `no_committer` rather than pretending. That is a
|
| 526 |
+
#: declared absence, not a silent one [[flag-shipped-without-its-writer]].
|
| 527 |
+
_COMMITTERS = {}
|
| 528 |
+
|
| 529 |
+
|
| 530 |
+
def register_committer(kind, fn):
|
| 531 |
+
"""Declare who may perform an approved mutation of `kind`. Idempotent by key."""
|
| 532 |
+
_COMMITTERS[str(kind)] = fn
|
| 533 |
+
|
| 534 |
+
|
| 535 |
+
def commit_pending(rt, token, approved, now=None):
|
| 536 |
+
"""Resolve ONE approval card. Returns one of
|
| 537 |
+
`expired` Β· `unknown` Β· `rejected` Β· `no_committer` Β· `committed` Β· `failed`.
|
| 538 |
+
|
| 539 |
+
ββ THIS IS THE WRITE GATE, AND IT IS A SEPARATE FUNCTION FROM THE ROUTE ON PURPOSE. T67's
|
| 540 |
+
`done-when` asks for an NC proving a REJECTED card writes nothing. A control aimed at the
|
| 541 |
+
route could not bite while the route had no write in it at all β it would stay green with the
|
| 542 |
+
guard deleted, because there would be nothing for the guard to be protecting anything from
|
| 543 |
+
([[gate-can-report-green-on-nothing]], and a verifier caught exactly that on this ticket's
|
| 544 |
+
first draft). Putting the commit behind ONE named seam gives the control a real subject: the
|
| 545 |
+
gate registers a recorder, and `rejected` must leave it untouched while `approve` must call it
|
| 546 |
+
exactly once.
|
| 547 |
+
|
| 548 |
+
β THE TOKEN IS CONSUMED BEFORE EITHER BRANCH, and before any committer runs. A card that
|
| 549 |
+
survives its own click is a replayable write, and "approve twice" must never mean "write
|
| 550 |
+
twice". The delete is `flush="sync"` for the same reason.
|
| 551 |
+
"""
|
| 552 |
+
now = float(now if now is not None else time.time())
|
| 553 |
+
row = _pending(rt).get(str(token))
|
| 554 |
+
if not isinstance(row, dict):
|
| 555 |
+
return "unknown"
|
| 556 |
+
# Consume FIRST β before the TTL verdict, before the approve/reject branch, before any write.
|
| 557 |
+
rt.update(PENDING_KEY,
|
| 558 |
+
lambda cur: {k: v for k, v in (cur or {}).items() if k != str(token)},
|
| 559 |
+
flush="sync")
|
| 560 |
+
if now - float(row.get("at") or 0) > APPROVAL_TTL_S:
|
| 561 |
+
return "expired"
|
| 562 |
+
if not approved:
|
| 563 |
+
# β NOTHING BELOW THIS LINE RUNS FOR A REJECTED CARD. The whole gate is this return.
|
| 564 |
+
return "rejected"
|
| 565 |
+
fn = _COMMITTERS.get(str(row.get("action") or ""))
|
| 566 |
+
if fn is None:
|
| 567 |
+
return "no_committer"
|
| 568 |
+
try:
|
| 569 |
+
fn(rt, row)
|
| 570 |
+
except Exception: # noqa: BLE001
|
| 571 |
+
# A committer that raises must not read as a commit. The card is already consumed, so the
|
| 572 |
+
# honest report is that it failed, and the human asks again.
|
| 573 |
+
return "failed"
|
| 574 |
+
return "committed"
|
| 575 |
+
|
| 576 |
+
|
| 577 |
+
# ββ the UNAUTHENTICATED Slack door βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 578 |
+
#: Sliding window, keyed on the SLACK TEAM, never the client IP.
|
| 579 |
+
#:
|
| 580 |
+
#: β WHY NOT THE IP, WHICH IS WHAT `routes_forms` DOES. Every Slack event arrives from Slack's own
|
| 581 |
+
#: infrastructure, so an IP window is one shared bucket for every workspace on the platform: one
|
| 582 |
+
#: busy tenant would spend the allowance for all of them, and the symptom would be another
|
| 583 |
+
#: tenant's bot going quiet. The team id is the closest thing to the actual noisy party.
|
| 584 |
+
#: β It is attacker-CONTROLLED before the signature is checked, so the window is applied AFTER
|
| 585 |
+
#: verification, never before β an unsigned request is refused on cost grounds anyway (a signature
|
| 586 |
+
#: check is a single HMAC).
|
| 587 |
+
RATE_WINDOW_S, RATE_PER_WINDOW = 60, 60
|
| 588 |
+
_HITS: dict = {}
|
| 589 |
+
|
| 590 |
+
|
| 591 |
+
def _rate_ok(key, now):
|
| 592 |
+
seen = [t for t in _HITS.get(key, ()) if now - t < RATE_WINDOW_S]
|
| 593 |
+
seen.append(now)
|
| 594 |
+
_HITS[key] = seen
|
| 595 |
+
if len(_HITS) > 4096:
|
| 596 |
+
for k in [k for k, v in _HITS.items() if not v or now - v[-1] > RATE_WINDOW_S]:
|
| 597 |
+
_HITS.pop(k, None)
|
| 598 |
+
return len(seen) <= RATE_PER_WINDOW
|
| 599 |
+
|
| 600 |
+
|
| 601 |
+
async def _raw_body(request):
|
| 602 |
+
"""The body as RAW BYTES, capped.
|
| 603 |
+
|
| 604 |
+
ββ RAW, NOT PARSED, AND THAT IS NOT A STYLE CHOICE. Slack signs the literal string
|
| 605 |
+
`v0:{timestamp}:{body}` byte for byte. `routes_forms._bounded_body` β the function this is
|
| 606 |
+
otherwise copied from β returns only the parsed dict and DISCARDS the bytes, so a verbatim
|
| 607 |
+
copy of it could not verify a Slack signature at all: re-serialising the dict changes
|
| 608 |
+
whitespace and key order and the HMAC no longer matches. The bug would look like "Slack
|
| 609 |
+
signatures are always invalid", which is indistinguishable from a wrong secret.
|
| 610 |
+
|
| 611 |
+
β And it streams rather than calling `request.body()`: FastAPI would otherwise have buffered
|
| 612 |
+
the whole body before the handler's first line, so a content-length check inside the handler
|
| 613 |
+
caps nothing (`routes_forms`' own scar, recorded in its docstring).
|
| 614 |
+
"""
|
| 615 |
+
size, chunks = 0, []
|
| 616 |
+
async for chunk in request.stream():
|
| 617 |
+
size += len(chunk)
|
| 618 |
+
if size > MAX_BODY_BYTES:
|
| 619 |
+
raise err(413, "body_too_large", "that request is too large")
|
| 620 |
+
chunks.append(chunk)
|
| 621 |
+
return b"".join(chunks)
|
| 622 |
+
|
| 623 |
+
|
| 624 |
+
def _refuse():
|
| 625 |
+
"""ONE refusal for every reason. No oracle.
|
| 626 |
+
|
| 627 |
+
A wrong signature, a stale timestamp, an unknown team, an unconfigured tenant and a channel
|
| 628 |
+
with no agent all answer identically β otherwise the door tells an unauthenticated caller
|
| 629 |
+
which tenants exist and which channels are configured, which is the question it was built to
|
| 630 |
+
not answer. `routes_forms._refuse` takes the same posture for the same reason.
|
| 631 |
+
"""
|
| 632 |
+
return err(403, "bad_request", "that request could not be verified")
|
| 633 |
+
|
| 634 |
+
|
| 635 |
+
def _verify(secret, timestamp, raw, signature, now):
|
| 636 |
+
"""Slack's v0 signature, with the replay window checked FIRST."""
|
| 637 |
+
try:
|
| 638 |
+
ts = int(str(timestamp or "0"))
|
| 639 |
+
except ValueError:
|
| 640 |
+
return False
|
| 641 |
+
if abs(now - ts) > SLACK_MAX_SKEW_S:
|
| 642 |
+
return False
|
| 643 |
+
base = b"v0:" + str(ts).encode("ascii") + b":" + (raw or b"")
|
| 644 |
+
import hashlib
|
| 645 |
+
expected = "v0=" + hmac.new(str(secret).encode("utf-8"), base, hashlib.sha256).hexdigest()
|
| 646 |
+
return hmac.compare_digest(expected, str(signature or ""))
|
| 647 |
+
|
| 648 |
+
|
| 649 |
+
def _resolve_tenant(raw, timestamp, signature, now):
|
| 650 |
+
"""`(slug, runtime, creds)` for the tenant whose signing secret verifies this request.
|
| 651 |
+
|
| 652 |
+
β THE TENANT IS DECIDED BY THE SIGNATURE, NEVER BY THE PAYLOAD. A body-supplied `team_id`
|
| 653 |
+
would let an unauthenticated caller name the tenant it wants to be β the exact widening
|
| 654 |
+
`deps._user_for`'s tenant-equality check closes on the authenticated side. So every configured
|
| 655 |
+
tenant's secret is tried and the one that VERIFIES names the tenant.
|
| 656 |
+
|
| 657 |
+
β NO EARLY `break` ON A FAILED CANDIDATE and no per-tenant error: the loop's cost must not
|
| 658 |
+
depend on which tenant matched. `routes_forms._resolve` walks tenants the same way, for the
|
| 659 |
+
same reason β a public door has no session to ask.
|
| 660 |
+
"""
|
| 661 |
+
from harness import runtime as _rt
|
| 662 |
+
hit = None
|
| 663 |
+
try:
|
| 664 |
+
slugs = list(_rt.known_tenants())
|
| 665 |
+
except Exception: # noqa: BLE001
|
| 666 |
+
return None, None, None
|
| 667 |
+
for slug in slugs:
|
| 668 |
+
try:
|
| 669 |
+
rt = _rt.get_runtime(slug)
|
| 670 |
+
except Exception: # noqa: BLE001
|
| 671 |
+
continue
|
| 672 |
+
creds = slack_creds(rt)
|
| 673 |
+
if not creds:
|
| 674 |
+
continue
|
| 675 |
+
if _verify(creds.get("signing_secret"), timestamp, raw, signature, now) and hit is None:
|
| 676 |
+
hit = (slug, rt, creds)
|
| 677 |
+
return hit if hit else (None, None, None)
|
| 678 |
+
|
| 679 |
+
|
| 680 |
+
@router.post("/slack/events")
|
| 681 |
+
async def slack_events(request: Request):
|
| 682 |
+
"""Slack's Events API. UNAUTHENTICATED BY CONSTRUCTION β no `Depends(require_session)`.
|
| 683 |
+
|
| 684 |
+
β Built like `routes_forms.py`'s public door and not like OpenTag's: one process, no vendor,
|
| 685 |
+
no second runtime, no persistent outbound socket, and this tenant's Slack secret never leaves
|
| 686 |
+
this deployment (amendment A1).
|
| 687 |
+
"""
|
| 688 |
+
now = time.time()
|
| 689 |
+
raw = await _raw_body(request)
|
| 690 |
+
ts = request.headers.get("x-slack-request-timestamp")
|
| 691 |
+
sig = request.headers.get("x-slack-signature")
|
| 692 |
+
slug, rt, _creds = _resolve_tenant(raw, ts, sig, now)
|
| 693 |
+
if not rt:
|
| 694 |
+
raise _refuse()
|
| 695 |
+
|
| 696 |
+
try:
|
| 697 |
+
payload = json.loads(raw or b"{}")
|
| 698 |
+
except ValueError:
|
| 699 |
+
raise _refuse()
|
| 700 |
+
if not isinstance(payload, dict):
|
| 701 |
+
raise _refuse()
|
| 702 |
+
|
| 703 |
+
# Slack's one-time endpoint handshake. Answered ONLY after the signature verified β an
|
| 704 |
+
# unsigned challenge echo would confirm the endpoint exists to anyone who probes it.
|
| 705 |
+
if payload.get("type") == "url_verification":
|
| 706 |
+
return {"challenge": str(payload.get("challenge") or "")[:512]}
|
| 707 |
+
|
| 708 |
+
team = str(payload.get("team_id") or slug)
|
| 709 |
+
if not _rate_ok(f"{slug}:{team}", now):
|
| 710 |
+
raise err(429, "too_many_requests", "too many requests β wait a moment and try again")
|
| 711 |
+
|
| 712 |
+
event = payload.get("event") if isinstance(payload.get("event"), dict) else {}
|
| 713 |
+
channel = str(event.get("channel") or "")
|
| 714 |
+
agent = None
|
| 715 |
+
for a in _agents(rt).values():
|
| 716 |
+
if isinstance(a, dict) and str(a.get("channel") or "") == channel:
|
| 717 |
+
agent = a
|
| 718 |
+
break
|
| 719 |
+
# β NO AGENT, OR AN INACTIVE ONE, IS SILENCE β a 200 with no action. Not a 403: Slack retries
|
| 720 |
+
# a non-2xx up to three times, so refusing here would turn "this channel is not configured"
|
| 721 |
+
# into three refusals per message, and the retry storm would be the only visible symptom.
|
| 722 |
+
# β And it must not say WHICH β a distinguishable answer tells an unauthenticated caller which
|
| 723 |
+
# channels this workspace has configured.
|
| 724 |
+
if not isinstance(agent, dict) or agent.get("active", True) is False:
|
| 725 |
+
return {"ok": True}
|
| 726 |
+
|
| 727 |
+
# ββ THE ANSWERING HALF IS NOT BUILT YET, AND SAYING SO IS THE POINT. What ships here is the
|
| 728 |
+
# DOOR and the WALL: a verified request, resolved to a tenant by signature, matched to a
|
| 729 |
+
# channel agent whose `perms` block is a `perm_scope` principal (`agent_principal`). Composing
|
| 730 |
+
# a reply means an LLM call on the cheap-first ladder plus the read path, and a half-built
|
| 731 |
+
# answerer that returns something plausible is worse than one that returns nothing.
|
| 732 |
+
# Booked rather than faked [[flag-shipped-without-its-writer]].
|
| 733 |
+
return {"ok": True}
|
| 734 |
+
|
| 735 |
+
|
| 736 |
+
@router.post("/slack/interact")
|
| 737 |
+
async def slack_interact(request: Request):
|
| 738 |
+
"""The approval card's button (`W33-T67`). UNAUTHENTICATED, signature-verified, same shape."""
|
| 739 |
+
now = time.time()
|
| 740 |
+
raw = await _raw_body(request)
|
| 741 |
+
slug, rt, _creds = _resolve_tenant(raw, request.headers.get("x-slack-request-timestamp"),
|
| 742 |
+
request.headers.get("x-slack-signature"), now)
|
| 743 |
+
if not rt:
|
| 744 |
+
raise _refuse()
|
| 745 |
+
# Slack posts interactions as `application/x-www-form-urlencoded` with a `payload=` field.
|
| 746 |
+
from urllib.parse import parse_qs
|
| 747 |
+
try:
|
| 748 |
+
form = parse_qs(raw.decode("utf-8"))
|
| 749 |
+
payload = json.loads((form.get("payload") or ["{}"])[0])
|
| 750 |
+
except Exception: # noqa: BLE001
|
| 751 |
+
raise _refuse()
|
| 752 |
+
if not isinstance(payload, dict):
|
| 753 |
+
raise _refuse()
|
| 754 |
+
if not _rate_ok(f"{slug}:interact", now):
|
| 755 |
+
raise err(429, "too_many_requests", "too many requests β wait a moment and try again")
|
| 756 |
+
|
| 757 |
+
actions = payload.get("actions") if isinstance(payload.get("actions"), list) else []
|
| 758 |
+
choice = (actions[0] if actions and isinstance(actions[0], dict) else {})
|
| 759 |
+
token = str(choice.get("value") or "")
|
| 760 |
+
# β ANYTHING THAT IS NOT LITERALLY "approve" IS A REJECT. Fail-closed on a malformed,
|
| 761 |
+
# truncated or unknown action id: the direction that can be wrong here without anyone
|
| 762 |
+
# noticing is the one that writes.
|
| 763 |
+
approved = str(choice.get("action_id") or "") == "approve"
|
| 764 |
+
# β THE ROUTE DOES NOT DECIDE β `commit_pending` does, and it is the ONE seam a negative
|
| 765 |
+
# control can aim at. Consumption, the TTL, the reject branch and the committer lookup all
|
| 766 |
+
# live there; this handler only turns its verdict into a sentence.
|
| 767 |
+
verdict = commit_pending(rt, token, approved, now=now)
|
| 768 |
+
return {"text": {
|
| 769 |
+
# An unknown, already-used or expired token is not an error: a person clicking a stale
|
| 770 |
+
# card should be told it is stale, not shown a failure.
|
| 771 |
+
"unknown": "That approval is no longer available. Ask the bot again.",
|
| 772 |
+
"expired": "That approval expired before it was answered. Ask the bot again.",
|
| 773 |
+
"rejected": "Rejected. Nothing was changed.",
|
| 774 |
+
# β HONEST, not reassuring: the answering half that would register a committer is booked,
|
| 775 |
+
# so an approved card today performs nothing and says exactly that rather than "Approved."
|
| 776 |
+
"no_committer": "Approved β but this workspace has nothing configured to carry it out yet.",
|
| 777 |
+
"failed": "That change could not be completed. Nothing was saved; ask the bot again.",
|
| 778 |
+
"committed": "Approved.",
|
| 779 |
+
}.get(verdict, "That approval is no longer available. Ask the bot again.")}
|
| 780 |
+
|
| 781 |
+
|
| 782 |
+
@router.get("/slack/health")
|
| 783 |
+
def slack_health(session: Session = Depends(require_session)):
|
| 784 |
+
"""Is Slack configured for THIS tenant? Session-gated, and it answers about one tenant only β
|
| 785 |
+
enumerating the others would answer a question about our customer list."""
|
| 786 |
+
creds = slack_creds(session.runtime)
|
| 787 |
+
return {"configured": creds is not None,
|
| 788 |
+
"agents": len(_agents(session.runtime)),
|
| 789 |
+
"hasBotToken": bool((creds or {}).get("bot_token"))}
|
api/routes_statements.py
CHANGED
|
@@ -1,298 +1,298 @@
|
|
| 1 |
-
"""routes_statements.py β the statement-of-account sender, ported off Streamlit (EXIT-6).
|
| 2 |
-
|
| 3 |
-
β THIS IS THE ONE SANCTIONED ODOO WRITER IN THE ENTIRE SYSTEM. Everything else in AIOS is
|
| 4 |
-
read-only on Odoo by hard block. `modules/collections_send.py` owns a narrow client that whitelists
|
| 5 |
-
exactly `mail.mail create` (queueing an outbound email) and nothing else; these routes call it and
|
| 6 |
-
add no write of their own.
|
| 7 |
-
|
| 8 |
-
WHY IT EXISTS SEPARATELY FROM THE COLLECTIONS PAGE. Owner ruling wave-17 item 15 retired the
|
| 9 |
-
Collections *dashboard* β the worklist is the shared "Collections" view on the Customer grid, from
|
| 10 |
-
the same reconciled blocks. What that ruling explicitly left "untouched" is this send workflow, so
|
| 11 |
-
when `app.py` is deleted it is the ONLY live Streamlit-only feature, and it moves here rather than
|
| 12 |
-
dying with the host. Ported faithfully: same tiers, same filters, same template placeholders, same
|
| 13 |
-
preview, same test-send, same two-step confirm.
|
| 14 |
-
|
| 15 |
-
THE THREE GUARDRAILS, and where each is enforced:
|
| 16 |
-
1. SAFE_MODE (default ON) β in the DATA LAYER (`collections_send.queue_statement`), so no route,
|
| 17 |
-
payload or UI can bypass it. These routes only REPORT it; they never re-implement the check.
|
| 18 |
-
2. Admin only β `admin_gate` (role, fail-closed), mirroring the Streamlit `if not is_admin()`.
|
| 19 |
-
3. β TENANT β NEW HERE, and it did not exist in Streamlit because it could not. `cs_mod.Odoo()`
|
| 20 |
-
reads Odoo credentials from the ENVIRONMENT, which after the keychain cutover belongs to
|
| 21 |
-
TENANT #0 ALONE. On the multi-tenant API an unguarded route would let a nurilab or gtmlab
|
| 22 |
-
admin queue mail from Royal Imports' Odoo, as Royal Imports. `_royal_only` closes that; the
|
| 23 |
-
single-tenant Streamlit host never had the exposure, so this is a port that must ADD a wall
|
| 24 |
-
rather than copy one.
|
| 25 |
-
|
| 26 |
-
NOTHING SENDS ON A GET. The send route requires an explicit customer list in the body; there is no
|
| 27 |
-
"send all" parameter, deliberately β the confirm step is a product requirement, not a formality.
|
| 28 |
-
"""
|
| 29 |
-
from fastapi import APIRouter, Body, Depends
|
| 30 |
-
|
| 31 |
-
from deps import Session, err
|
| 32 |
-
from routes_admin import admin_gate
|
| 33 |
-
|
| 34 |
-
# W35-T35 (C8): the tenant predicate, held once. See `_royal_only` for why the import runs this
|
| 35 |
-
# way round. `main.py` already imports both modules, so this adds no load.
|
| 36 |
-
import automation_engine as engine
|
| 37 |
-
|
| 38 |
-
router = APIRouter(prefix="/api/v1")
|
| 39 |
-
|
| 40 |
-
#: Cache the Odoo follow-up pull briefly. The Streamlit page used `@st.cache_data(ttl=1800)`; the
|
| 41 |
-
#: list moves slowly (it is a dunning worklist, not a live feed) and the pull is a multi-model read.
|
| 42 |
-
_TTL = 1800
|
| 43 |
-
_cache = {"at": 0.0, "rows": None}
|
| 44 |
-
|
| 45 |
-
|
| 46 |
-
def _cs():
|
| 47 |
-
import modules.collections_send as cs
|
| 48 |
-
return cs
|
| 49 |
-
|
| 50 |
-
|
| 51 |
-
def _royal_only(session: Session) -> Session:
|
| 52 |
-
"""β See the module docstring, guardrail 3. The send client is env-credentialed, so it is
|
| 53 |
-
tenant #0's and only tenant #0's. Refuse for anyone else rather than send as the wrong company.
|
| 54 |
-
|
| 55 |
-
Keyed on the runtime, never on a request field: a tenant is a property of the SESSION.
|
| 56 |
-
|
| 57 |
-
ββ WAVE 35 Β· T35 / CONTRACT C8 β THE TEST ITSELF NOW LIVES IN ONE PLACE. Statements became an
|
| 58 |
-
agent step this wave, so the automation engine has to answer the same question at two more
|
| 59 |
-
doors (which tenants see the action, which tenants may store it). C8's words are "the predicate
|
| 60 |
-
is imported, never re-expressed", and this is the direction that import can run: the engine
|
| 61 |
-
imports no route module and no FastAPI, so reaching `_royal_only` FROM it would drag `deps` and
|
| 62 |
-
`routes_admin` into a route-free module. The engine holds the boolean; this holds the refusal.
|
| 63 |
-
β WHAT STAYS HERE IS THE HTTP SHAPE, and that is deliberate β a 404 rather than a 403, so the
|
| 64 |
-
surface is invisible rather than forbidden. The engine must not know about status codes."""
|
| 65 |
-
if not engine.is_statement_tenant(session.runtime):
|
| 66 |
-
raise err(404, "not_found", "statements are not configured for this workspace")
|
| 67 |
-
return session
|
| 68 |
-
|
| 69 |
-
|
| 70 |
-
def _gate(session: Session = Depends(admin_gate)) -> Session:
|
| 71 |
-
return _royal_only(session)
|
| 72 |
-
|
| 73 |
-
|
| 74 |
-
def _rows(force=False):
|
| 75 |
-
import time
|
| 76 |
-
cs = _cs()
|
| 77 |
-
if force or _cache["rows"] is None or (time.time() - _cache["at"]) > _TTL:
|
| 78 |
-
_cache["rows"] = cs.load_collection_list(cs.Odoo())
|
| 79 |
-
_cache["at"] = time.time()
|
| 80 |
-
return _cache["rows"], time.strftime("%Y-%m-%d %H:%M", time.localtime(_cache["at"]))
|
| 81 |
-
|
| 82 |
-
|
| 83 |
-
def _public(row):
|
| 84 |
-
"""Strip the internals the Streamlit grid also hid (`_`-prefixed + partner_id is kept, because
|
| 85 |
-
the client needs a stable row identity that is not the display name)."""
|
| 86 |
-
return {k: v for k, v in row.items() if not str(k).startswith("_")}
|
| 87 |
-
|
| 88 |
-
|
| 89 |
-
@router.get("/admin/statements")
|
| 90 |
-
def statements(refresh: int = 0, session: Session = Depends(_gate)):
|
| 91 |
-
"""The worklist + everything the sender UI needs to render itself honestly."""
|
| 92 |
-
cs = _cs()
|
| 93 |
-
try:
|
| 94 |
-
rows, loaded_at = _rows(force=bool(refresh))
|
| 95 |
-
except Exception as e:
|
| 96 |
-
raise err(502, "odoo_unavailable", f"could not load the collection list: {str(e)[:200]}")
|
| 97 |
-
return {
|
| 98 |
-
"rows": [_public(r) for r in rows],
|
| 99 |
-
"loadedAt": loaded_at,
|
| 100 |
-
# The guardrail is reported, never decided, here β the data layer owns it.
|
| 101 |
-
"safeMode": bool(cs.SAFE_MODE),
|
| 102 |
-
"safeRecipients": sorted(cs.SAFE_RECIPIENTS),
|
| 103 |
-
"sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL,
|
| 104 |
-
"replyTo": cs.REPLY_TO, "company": cs.COMPANY},
|
| 105 |
-
"templates": {"subject": cs.DEFAULT_SUBJECT, "intro": cs.DEFAULT_INTRO,
|
| 106 |
-
"footer": cs.DEFAULT_FOOTER},
|
| 107 |
-
# W35-T35: ONE literal, read from the engine, so the sender's worklist and a statements
|
| 108 |
-
# agent's tier filter cannot come to mean different things.
|
| 109 |
-
"tiers": list(engine.STATEMENT_TIERS),
|
| 110 |
-
}
|
| 111 |
-
|
| 112 |
-
|
| 113 |
-
def _find(rows, customer):
|
| 114 |
-
return next((r for r in rows if r.get("Customer") == customer), None)
|
| 115 |
-
|
| 116 |
-
|
| 117 |
-
@router.post("/admin/statements/preview")
|
| 118 |
-
def preview(body: dict = Body(default=None), session: Session = Depends(_gate)):
|
| 119 |
-
"""Render ONE customer's statement exactly as the send path would."""
|
| 120 |
-
cs = _cs()
|
| 121 |
-
body = body or {}
|
| 122 |
-
rows, _ = _rows()
|
| 123 |
-
row = _find(rows, body.get("customer"))
|
| 124 |
-
if row is None:
|
| 125 |
-
raise err(404, "not_found", "no such customer on the collection list")
|
| 126 |
-
t = body.get("templates") or {}
|
| 127 |
-
import datetime as dt
|
| 128 |
-
month = dt.date.today().strftime("%B %Y")
|
| 129 |
-
subject = (t.get("subject") or cs.DEFAULT_SUBJECT)
|
| 130 |
-
try:
|
| 131 |
-
subject = subject.format(customer=row["Customer"], company=cs.COMPANY, month=month)
|
| 132 |
-
except Exception: # noqa: BLE001
|
| 133 |
-
# An unknown placeholder is the user's typo, not a 500. Show the template verbatim so they
|
| 134 |
-
# can see what they typed rather than getting an opaque error.
|
| 135 |
-
# β W36-T42: THIS CAUGHT THREE OF THE WAYS `str.format` FAILS AND THERE ARE MORE.
|
| 136 |
-
# `{customer` is a ValueError, `{customer.x}` an AttributeError, `{customer:%Y}` a
|
| 137 |
-
# TypeError, and every one of them is the same user mistake this branch was written for.
|
| 138 |
-
# Naming a subset of the exception types turns a typo in the OTHER half into a 500 on the
|
| 139 |
-
# one screen somebody opens to avoid mailing 200 people the wrong thing.
|
| 140 |
-
pass
|
| 141 |
-
return {
|
| 142 |
-
"html": cs.render_statement_html(row, t.get("intro") or cs.DEFAULT_INTRO,
|
| 143 |
-
t.get("footer") or cs.DEFAULT_FOOTER),
|
| 144 |
-
"to": row.get("Email") or "",
|
| 145 |
-
"subject": subject,
|
| 146 |
-
}
|
| 147 |
-
|
| 148 |
-
|
| 149 |
-
@router.post("/admin/statements/send")
|
| 150 |
-
def send(body: dict = Body(default=None), session: Session = Depends(_gate)):
|
| 151 |
-
"""Queue statements. Returns per-customer outcomes β NEVER a bare count.
|
| 152 |
-
|
| 153 |
-
`overrideTo` is the test-send path: one customer, one address. SAFE_MODE still applies (the
|
| 154 |
-
data layer refuses an address outside the allow-list), which is why the route does not check it.
|
| 155 |
-
"""
|
| 156 |
-
cs = _cs()
|
| 157 |
-
body = body or {}
|
| 158 |
-
names = [str(n) for n in (body.get("customers") or []) if str(n).strip()]
|
| 159 |
-
if not names:
|
| 160 |
-
raise err(400, "bad_request", "name at least one customer")
|
| 161 |
-
# ββ W36-T42 / D-299 β A DECLARED TEST SEND WITH NO ADDRESS REFUSES. IT DOES NOT BECOME A
|
| 162 |
-
# REAL ONE. This read `(body.get("overrideTo") or "").strip() or None`, so a caller who sent
|
| 163 |
-
# `overrideTo: ""` (the field left blank, the state not yet typed into, a trimmed-away space)
|
| 164 |
-
# got a REAL statement mailed to the debtor's own address, reported back as `test: false`. On
|
| 165 |
-
# the one route in this product that is allowed to write to Odoo, the difference between a
|
| 166 |
-
# rehearsal and mailing a live customer was one empty string.
|
| 167 |
-
#
|
| 168 |
-
# β THE DISCRIMINATOR IS THE CALLER'S DECLARATION, NOT THE VALUE. A body with no `overrideTo`
|
| 169 |
-
# key and no `test` flag is the PRODUCTION send, and refusing that would delete the feature
|
| 170 |
-
# D-299 exists to preserve. What can be refused is a caller who SAID this is a test: the key
|
| 171 |
-
# being present, or `test: true`, is that statement, and an empty address beside it is the
|
| 172 |
-
# mistake. So both spellings of "absent" are covered: the key present and blank, and `test`
|
| 173 |
-
# asserted with no key at all.
|
| 174 |
-
#
|
| 175 |
-
# β THIS IS THE SECOND OF THREE WALLS AND THE ONLY ONE A PAYLOAD CANNOT ROUTE AROUND.
|
| 176 |
-
# `automationApi.testSendStatement` refuses an empty address before the request is built, and
|
| 177 |
-
# SAFE_MODE refuses an address outside the allow-list inside `queue_statement`. The client
|
| 178 |
-
# wall is bypassable by construction (anything can POST); this one is not.
|
| 179 |
-
declared_test = ("overrideTo" in body) or bool(body.get("test"))
|
| 180 |
-
override = str(body.get("overrideTo") or "").strip()
|
| 181 |
-
if declared_test and not override:
|
| 182 |
-
raise err(400, "no_override_address",
|
| 183 |
-
"a test send needs the address to send the test to. Without one this would "
|
| 184 |
-
"mail the customer's own address, which is the opposite of a test")
|
| 185 |
-
override = override or None
|
| 186 |
-
if override and len(names) != 1:
|
| 187 |
-
raise err(400, "bad_request", "a test send takes exactly one customer")
|
| 188 |
-
t = body.get("templates") or {}
|
| 189 |
-
rows, _ = _rows()
|
| 190 |
-
|
| 191 |
-
sent, failed, skipped = [], [], []
|
| 192 |
-
for name in names:
|
| 193 |
-
row = _find(rows, name)
|
| 194 |
-
if row is None:
|
| 195 |
-
failed.append({"customer": name, "error": "not on the current collection list"})
|
| 196 |
-
continue
|
| 197 |
-
if not override and not row.get("Email"):
|
| 198 |
-
# The Streamlit page warned and skipped these. Reporting them SEPARATELY from failures
|
| 199 |
-
# keeps "we could not" distinct from "there was nowhere to send".
|
| 200 |
-
skipped.append({"customer": name, "reason": "no email address on the customer record"})
|
| 201 |
-
continue
|
| 202 |
-
try:
|
| 203 |
-
mid = cs.queue_statement(cs.Odoo(), row, t.get("subject") or cs.DEFAULT_SUBJECT,
|
| 204 |
-
t.get("intro") or cs.DEFAULT_INTRO,
|
| 205 |
-
t.get("footer") or cs.DEFAULT_FOOTER, override_to=override)
|
| 206 |
-
sent.append({"customer": name, "to": override or row.get("Email"), "mailId": mid})
|
| 207 |
-
except Exception as e:
|
| 208 |
-
# SafeModeBlocked lands here too, and that is correct: to the caller a guardrail refusal
|
| 209 |
-
# and an Odoo error are both "this one did not go", each with its own honest message.
|
| 210 |
-
failed.append({"customer": name, "error": str(e)[:200]})
|
| 211 |
-
return {"sent": sent, "failed": failed, "skipped": skipped,
|
| 212 |
-
"safeMode": bool(cs.SAFE_MODE), "test": bool(override)}
|
| 213 |
-
|
| 214 |
-
|
| 215 |
-
# ---------------------------------------------------------------------------------------------
|
| 216 |
-
# WAVE 35 Β· T36 / CONTRACT C8 / OWNER RULING R10 β THE AGENT'S PARKED BATCH.
|
| 217 |
-
#
|
| 218 |
-
# ββ THE AGENT ASSEMBLES; A PERSON CLICKS SEND. `automation_engine.run_statements` renders a batch
|
| 219 |
-
# and parks it on the automation definition, and it imports no mail path at all. THIS is the only
|
| 220 |
-
# door that releases one, and it is deliberately built out of the parts already here:
|
| 221 |
-
# Β· `_gate` β `admin_gate` THEN `_royal_only`, byte-for-byte the dependency the other three
|
| 222 |
-
# endpoints use. Not a copy of the checks: the same object.
|
| 223 |
-
# Β· `cs.queue_statement` β the same call `send()` above makes, so SAFE_MODE's allow-list refusal
|
| 224 |
-
# happens in the DATA LAYER, where no route, payload or UI can reach around it.
|
| 225 |
-
# β Nothing about the guardrails is re-expressed here, which is what makes "unchanged" checkable.
|
| 226 |
-
#
|
| 227 |
-
# β WHY THE BATCH IS RE-RENDERED FROM THE LIVE WORKLIST RATHER THAN SENT AS STORED. The parked
|
| 228 |
-
# `html` is what a person APPROVED and is what the review screen shows; but a balance can move
|
| 229 |
-
# between the parking and the click, and mailing a figure we know to be stale is worse than mailing
|
| 230 |
-
# a fresh one. So the parked batch decides WHO and WITH WHAT WORDS, and the live row decides the
|
| 231 |
-
# NUMBERS β the same split `preview` already makes. A customer who has left the worklist entirely
|
| 232 |
-
# (they paid) is reported as skipped rather than invoiced.
|
| 233 |
-
|
| 234 |
-
@router.get("/admin/statements/agent/{auto_id}")
|
| 235 |
-
def agent_batch(auto_id: str, session: Session = Depends(_gate)):
|
| 236 |
-
"""What is parked and waiting for a click, for ONE agent. `null` when nothing is."""
|
| 237 |
-
defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
|
| 238 |
-
pending = defn.get("pendingStatements")
|
| 239 |
-
if not isinstance(pending, dict):
|
| 240 |
-
return {"pending": None}
|
| 241 |
-
# β The rendered `html` is NOT returned in the list β a 200-statement batch of rendered mail is
|
| 242 |
-
# megabytes, and the review screen needs the count and the names to decide. `preview` already
|
| 243 |
-
# renders ONE on demand.
|
| 244 |
-
return {"pending": {
|
| 245 |
-
"ts": pending.get("ts"), "count": int(pending.get("count") or 0),
|
| 246 |
-
"notes": list(pending.get("notes") or []),
|
| 247 |
-
"items": [{k: v for k, v in it.items() if k != "html"}
|
| 248 |
-
for it in (pending.get("items") or [])],
|
| 249 |
-
"safeMode": bool(_cs().SAFE_MODE)}}
|
| 250 |
-
|
| 251 |
-
|
| 252 |
-
@router.post("/admin/statements/agent/{auto_id}/send")
|
| 253 |
-
def agent_send(auto_id: str, body: dict = Body(default=None),
|
| 254 |
-
session: Session = Depends(_gate)):
|
| 255 |
-
"""Release a parked batch. THE CLICK R10 REQUIRES β nothing else in the system calls this.
|
| 256 |
-
|
| 257 |
-
β IT REFUSES AN EMPTY OR MISSING BATCH rather than answering 200 with nothing sent: a send
|
| 258 |
-
that reports success and mails nobody is the `view_upsert` failure mode (200 OK, zero writes)
|
| 259 |
-
arriving on the one route in this system that talks to a mail server.
|
| 260 |
-
"""
|
| 261 |
-
cs = _cs()
|
| 262 |
-
defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
|
| 263 |
-
pending = defn.get("pendingStatements")
|
| 264 |
-
items = list((pending or {}).get("items") or []) if isinstance(pending, dict) else []
|
| 265 |
-
if not items:
|
| 266 |
-
raise err(404, "no_batch", "there is nothing parked for this agent to send")
|
| 267 |
-
# β An explicit subset is allowed (a person unticking a customer on the review screen) but it
|
| 268 |
-
# may only NARROW the parked batch. A name that was never parked cannot be introduced by the
|
| 269 |
-
# payload, or the review stops being what authorised the send.
|
| 270 |
-
want = {str(n) for n in (body or {}).get("customers") or []}
|
| 271 |
-
if want:
|
| 272 |
-
items = [it for it in items if str(it.get("customer")) in want]
|
| 273 |
-
if not items:
|
| 274 |
-
raise err(400, "bad_request", "none of those customers are in the parked batch")
|
| 275 |
-
rows, _ = _rows()
|
| 276 |
-
sent, failed, skipped = [], [], []
|
| 277 |
-
for it in items:
|
| 278 |
-
name = str(it.get("customer") or "")
|
| 279 |
-
row = _find(rows, name)
|
| 280 |
-
if row is None:
|
| 281 |
-
skipped.append({"customer": name,
|
| 282 |
-
"reason": "no longer on the collection list, so nothing is owed"})
|
| 283 |
-
continue
|
| 284 |
-
try:
|
| 285 |
-
# β THE SAME DATA-LAYER CALL `send()` MAKES. SafeModeBlocked is raised INSIDE
|
| 286 |
-
# `queue_statement`, so the guardrail cannot be argued with from here.
|
| 287 |
-
mid = cs.queue_statement(cs.Odoo(), row,
|
| 288 |
-
str(it.get("subject") or "") or cs.DEFAULT_SUBJECT,
|
| 289 |
-
cs.DEFAULT_INTRO, cs.DEFAULT_FOOTER)
|
| 290 |
-
sent.append({"customer": name, "to": row.get("Email"), "mailId": mid})
|
| 291 |
-
except Exception as e: # noqa: BLE001
|
| 292 |
-
failed.append({"customer": name, "error": str(e)[:200]})
|
| 293 |
-
# β CLEARED ONLY WHEN NOTHING IS LEFT TO RETRY. A batch dropped while some of it failed would
|
| 294 |
-
# lose the list of who still needs a statement, and nobody would know to look.
|
| 295 |
-
if sent and not failed:
|
| 296 |
-
engine.clear_statements(session.runtime, auto_id)
|
| 297 |
-
return {"sent": sent, "failed": failed, "skipped": skipped,
|
| 298 |
-
"safeMode": bool(cs.SAFE_MODE), "cleared": bool(sent and not failed)}
|
|
|
|
| 1 |
+
"""routes_statements.py β the statement-of-account sender, ported off Streamlit (EXIT-6).
|
| 2 |
+
|
| 3 |
+
β THIS IS THE ONE SANCTIONED ODOO WRITER IN THE ENTIRE SYSTEM. Everything else in AIOS is
|
| 4 |
+
read-only on Odoo by hard block. `modules/collections_send.py` owns a narrow client that whitelists
|
| 5 |
+
exactly `mail.mail create` (queueing an outbound email) and nothing else; these routes call it and
|
| 6 |
+
add no write of their own.
|
| 7 |
+
|
| 8 |
+
WHY IT EXISTS SEPARATELY FROM THE COLLECTIONS PAGE. Owner ruling wave-17 item 15 retired the
|
| 9 |
+
Collections *dashboard* β the worklist is the shared "Collections" view on the Customer grid, from
|
| 10 |
+
the same reconciled blocks. What that ruling explicitly left "untouched" is this send workflow, so
|
| 11 |
+
when `app.py` is deleted it is the ONLY live Streamlit-only feature, and it moves here rather than
|
| 12 |
+
dying with the host. Ported faithfully: same tiers, same filters, same template placeholders, same
|
| 13 |
+
preview, same test-send, same two-step confirm.
|
| 14 |
+
|
| 15 |
+
THE THREE GUARDRAILS, and where each is enforced:
|
| 16 |
+
1. SAFE_MODE (default ON) β in the DATA LAYER (`collections_send.queue_statement`), so no route,
|
| 17 |
+
payload or UI can bypass it. These routes only REPORT it; they never re-implement the check.
|
| 18 |
+
2. Admin only β `admin_gate` (role, fail-closed), mirroring the Streamlit `if not is_admin()`.
|
| 19 |
+
3. β TENANT β NEW HERE, and it did not exist in Streamlit because it could not. `cs_mod.Odoo()`
|
| 20 |
+
reads Odoo credentials from the ENVIRONMENT, which after the keychain cutover belongs to
|
| 21 |
+
TENANT #0 ALONE. On the multi-tenant API an unguarded route would let a nurilab or gtmlab
|
| 22 |
+
admin queue mail from Royal Imports' Odoo, as Royal Imports. `_royal_only` closes that; the
|
| 23 |
+
single-tenant Streamlit host never had the exposure, so this is a port that must ADD a wall
|
| 24 |
+
rather than copy one.
|
| 25 |
+
|
| 26 |
+
NOTHING SENDS ON A GET. The send route requires an explicit customer list in the body; there is no
|
| 27 |
+
"send all" parameter, deliberately β the confirm step is a product requirement, not a formality.
|
| 28 |
+
"""
|
| 29 |
+
from fastapi import APIRouter, Body, Depends
|
| 30 |
+
|
| 31 |
+
from deps import Session, err
|
| 32 |
+
from routes_admin import admin_gate
|
| 33 |
+
|
| 34 |
+
# W35-T35 (C8): the tenant predicate, held once. See `_royal_only` for why the import runs this
|
| 35 |
+
# way round. `main.py` already imports both modules, so this adds no load.
|
| 36 |
+
import automation_engine as engine
|
| 37 |
+
|
| 38 |
+
router = APIRouter(prefix="/api/v1")
|
| 39 |
+
|
| 40 |
+
#: Cache the Odoo follow-up pull briefly. The Streamlit page used `@st.cache_data(ttl=1800)`; the
|
| 41 |
+
#: list moves slowly (it is a dunning worklist, not a live feed) and the pull is a multi-model read.
|
| 42 |
+
_TTL = 1800
|
| 43 |
+
_cache = {"at": 0.0, "rows": None}
|
| 44 |
+
|
| 45 |
+
|
| 46 |
+
def _cs():
|
| 47 |
+
import modules.collections_send as cs
|
| 48 |
+
return cs
|
| 49 |
+
|
| 50 |
+
|
| 51 |
+
def _royal_only(session: Session) -> Session:
|
| 52 |
+
"""β See the module docstring, guardrail 3. The send client is env-credentialed, so it is
|
| 53 |
+
tenant #0's and only tenant #0's. Refuse for anyone else rather than send as the wrong company.
|
| 54 |
+
|
| 55 |
+
Keyed on the runtime, never on a request field: a tenant is a property of the SESSION.
|
| 56 |
+
|
| 57 |
+
ββ WAVE 35 Β· T35 / CONTRACT C8 β THE TEST ITSELF NOW LIVES IN ONE PLACE. Statements became an
|
| 58 |
+
agent step this wave, so the automation engine has to answer the same question at two more
|
| 59 |
+
doors (which tenants see the action, which tenants may store it). C8's words are "the predicate
|
| 60 |
+
is imported, never re-expressed", and this is the direction that import can run: the engine
|
| 61 |
+
imports no route module and no FastAPI, so reaching `_royal_only` FROM it would drag `deps` and
|
| 62 |
+
`routes_admin` into a route-free module. The engine holds the boolean; this holds the refusal.
|
| 63 |
+
β WHAT STAYS HERE IS THE HTTP SHAPE, and that is deliberate β a 404 rather than a 403, so the
|
| 64 |
+
surface is invisible rather than forbidden. The engine must not know about status codes."""
|
| 65 |
+
if not engine.is_statement_tenant(session.runtime):
|
| 66 |
+
raise err(404, "not_found", "statements are not configured for this workspace")
|
| 67 |
+
return session
|
| 68 |
+
|
| 69 |
+
|
| 70 |
+
def _gate(session: Session = Depends(admin_gate)) -> Session:
|
| 71 |
+
return _royal_only(session)
|
| 72 |
+
|
| 73 |
+
|
| 74 |
+
def _rows(force=False):
|
| 75 |
+
import time
|
| 76 |
+
cs = _cs()
|
| 77 |
+
if force or _cache["rows"] is None or (time.time() - _cache["at"]) > _TTL:
|
| 78 |
+
_cache["rows"] = cs.load_collection_list(cs.Odoo())
|
| 79 |
+
_cache["at"] = time.time()
|
| 80 |
+
return _cache["rows"], time.strftime("%Y-%m-%d %H:%M", time.localtime(_cache["at"]))
|
| 81 |
+
|
| 82 |
+
|
| 83 |
+
def _public(row):
|
| 84 |
+
"""Strip the internals the Streamlit grid also hid (`_`-prefixed + partner_id is kept, because
|
| 85 |
+
the client needs a stable row identity that is not the display name)."""
|
| 86 |
+
return {k: v for k, v in row.items() if not str(k).startswith("_")}
|
| 87 |
+
|
| 88 |
+
|
| 89 |
+
@router.get("/admin/statements")
|
| 90 |
+
def statements(refresh: int = 0, session: Session = Depends(_gate)):
|
| 91 |
+
"""The worklist + everything the sender UI needs to render itself honestly."""
|
| 92 |
+
cs = _cs()
|
| 93 |
+
try:
|
| 94 |
+
rows, loaded_at = _rows(force=bool(refresh))
|
| 95 |
+
except Exception as e:
|
| 96 |
+
raise err(502, "odoo_unavailable", f"could not load the collection list: {str(e)[:200]}")
|
| 97 |
+
return {
|
| 98 |
+
"rows": [_public(r) for r in rows],
|
| 99 |
+
"loadedAt": loaded_at,
|
| 100 |
+
# The guardrail is reported, never decided, here β the data layer owns it.
|
| 101 |
+
"safeMode": bool(cs.SAFE_MODE),
|
| 102 |
+
"safeRecipients": sorted(cs.SAFE_RECIPIENTS),
|
| 103 |
+
"sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL,
|
| 104 |
+
"replyTo": cs.REPLY_TO, "company": cs.COMPANY},
|
| 105 |
+
"templates": {"subject": cs.DEFAULT_SUBJECT, "intro": cs.DEFAULT_INTRO,
|
| 106 |
+
"footer": cs.DEFAULT_FOOTER},
|
| 107 |
+
# W35-T35: ONE literal, read from the engine, so the sender's worklist and a statements
|
| 108 |
+
# agent's tier filter cannot come to mean different things.
|
| 109 |
+
"tiers": list(engine.STATEMENT_TIERS),
|
| 110 |
+
}
|
| 111 |
+
|
| 112 |
+
|
| 113 |
+
def _find(rows, customer):
|
| 114 |
+
return next((r for r in rows if r.get("Customer") == customer), None)
|
| 115 |
+
|
| 116 |
+
|
| 117 |
+
@router.post("/admin/statements/preview")
|
| 118 |
+
def preview(body: dict = Body(default=None), session: Session = Depends(_gate)):
|
| 119 |
+
"""Render ONE customer's statement exactly as the send path would."""
|
| 120 |
+
cs = _cs()
|
| 121 |
+
body = body or {}
|
| 122 |
+
rows, _ = _rows()
|
| 123 |
+
row = _find(rows, body.get("customer"))
|
| 124 |
+
if row is None:
|
| 125 |
+
raise err(404, "not_found", "no such customer on the collection list")
|
| 126 |
+
t = body.get("templates") or {}
|
| 127 |
+
import datetime as dt
|
| 128 |
+
month = dt.date.today().strftime("%B %Y")
|
| 129 |
+
subject = (t.get("subject") or cs.DEFAULT_SUBJECT)
|
| 130 |
+
try:
|
| 131 |
+
subject = subject.format(customer=row["Customer"], company=cs.COMPANY, month=month)
|
| 132 |
+
except Exception: # noqa: BLE001
|
| 133 |
+
# An unknown placeholder is the user's typo, not a 500. Show the template verbatim so they
|
| 134 |
+
# can see what they typed rather than getting an opaque error.
|
| 135 |
+
# β W36-T42: THIS CAUGHT THREE OF THE WAYS `str.format` FAILS AND THERE ARE MORE.
|
| 136 |
+
# `{customer` is a ValueError, `{customer.x}` an AttributeError, `{customer:%Y}` a
|
| 137 |
+
# TypeError, and every one of them is the same user mistake this branch was written for.
|
| 138 |
+
# Naming a subset of the exception types turns a typo in the OTHER half into a 500 on the
|
| 139 |
+
# one screen somebody opens to avoid mailing 200 people the wrong thing.
|
| 140 |
+
pass
|
| 141 |
+
return {
|
| 142 |
+
"html": cs.render_statement_html(row, t.get("intro") or cs.DEFAULT_INTRO,
|
| 143 |
+
t.get("footer") or cs.DEFAULT_FOOTER),
|
| 144 |
+
"to": row.get("Email") or "",
|
| 145 |
+
"subject": subject,
|
| 146 |
+
}
|
| 147 |
+
|
| 148 |
+
|
| 149 |
+
@router.post("/admin/statements/send")
|
| 150 |
+
def send(body: dict = Body(default=None), session: Session = Depends(_gate)):
|
| 151 |
+
"""Queue statements. Returns per-customer outcomes β NEVER a bare count.
|
| 152 |
+
|
| 153 |
+
`overrideTo` is the test-send path: one customer, one address. SAFE_MODE still applies (the
|
| 154 |
+
data layer refuses an address outside the allow-list), which is why the route does not check it.
|
| 155 |
+
"""
|
| 156 |
+
cs = _cs()
|
| 157 |
+
body = body or {}
|
| 158 |
+
names = [str(n) for n in (body.get("customers") or []) if str(n).strip()]
|
| 159 |
+
if not names:
|
| 160 |
+
raise err(400, "bad_request", "name at least one customer")
|
| 161 |
+
# ββ W36-T42 / D-299 β A DECLARED TEST SEND WITH NO ADDRESS REFUSES. IT DOES NOT BECOME A
|
| 162 |
+
# REAL ONE. This read `(body.get("overrideTo") or "").strip() or None`, so a caller who sent
|
| 163 |
+
# `overrideTo: ""` (the field left blank, the state not yet typed into, a trimmed-away space)
|
| 164 |
+
# got a REAL statement mailed to the debtor's own address, reported back as `test: false`. On
|
| 165 |
+
# the one route in this product that is allowed to write to Odoo, the difference between a
|
| 166 |
+
# rehearsal and mailing a live customer was one empty string.
|
| 167 |
+
#
|
| 168 |
+
# β THE DISCRIMINATOR IS THE CALLER'S DECLARATION, NOT THE VALUE. A body with no `overrideTo`
|
| 169 |
+
# key and no `test` flag is the PRODUCTION send, and refusing that would delete the feature
|
| 170 |
+
# D-299 exists to preserve. What can be refused is a caller who SAID this is a test: the key
|
| 171 |
+
# being present, or `test: true`, is that statement, and an empty address beside it is the
|
| 172 |
+
# mistake. So both spellings of "absent" are covered: the key present and blank, and `test`
|
| 173 |
+
# asserted with no key at all.
|
| 174 |
+
#
|
| 175 |
+
# β THIS IS THE SECOND OF THREE WALLS AND THE ONLY ONE A PAYLOAD CANNOT ROUTE AROUND.
|
| 176 |
+
# `automationApi.testSendStatement` refuses an empty address before the request is built, and
|
| 177 |
+
# SAFE_MODE refuses an address outside the allow-list inside `queue_statement`. The client
|
| 178 |
+
# wall is bypassable by construction (anything can POST); this one is not.
|
| 179 |
+
declared_test = ("overrideTo" in body) or bool(body.get("test"))
|
| 180 |
+
override = str(body.get("overrideTo") or "").strip()
|
| 181 |
+
if declared_test and not override:
|
| 182 |
+
raise err(400, "no_override_address",
|
| 183 |
+
"a test send needs the address to send the test to. Without one this would "
|
| 184 |
+
"mail the customer's own address, which is the opposite of a test")
|
| 185 |
+
override = override or None
|
| 186 |
+
if override and len(names) != 1:
|
| 187 |
+
raise err(400, "bad_request", "a test send takes exactly one customer")
|
| 188 |
+
t = body.get("templates") or {}
|
| 189 |
+
rows, _ = _rows()
|
| 190 |
+
|
| 191 |
+
sent, failed, skipped = [], [], []
|
| 192 |
+
for name in names:
|
| 193 |
+
row = _find(rows, name)
|
| 194 |
+
if row is None:
|
| 195 |
+
failed.append({"customer": name, "error": "not on the current collection list"})
|
| 196 |
+
continue
|
| 197 |
+
if not override and not row.get("Email"):
|
| 198 |
+
# The Streamlit page warned and skipped these. Reporting them SEPARATELY from failures
|
| 199 |
+
# keeps "we could not" distinct from "there was nowhere to send".
|
| 200 |
+
skipped.append({"customer": name, "reason": "no email address on the customer record"})
|
| 201 |
+
continue
|
| 202 |
+
try:
|
| 203 |
+
mid = cs.queue_statement(cs.Odoo(), row, t.get("subject") or cs.DEFAULT_SUBJECT,
|
| 204 |
+
t.get("intro") or cs.DEFAULT_INTRO,
|
| 205 |
+
t.get("footer") or cs.DEFAULT_FOOTER, override_to=override)
|
| 206 |
+
sent.append({"customer": name, "to": override or row.get("Email"), "mailId": mid})
|
| 207 |
+
except Exception as e:
|
| 208 |
+
# SafeModeBlocked lands here too, and that is correct: to the caller a guardrail refusal
|
| 209 |
+
# and an Odoo error are both "this one did not go", each with its own honest message.
|
| 210 |
+
failed.append({"customer": name, "error": str(e)[:200]})
|
| 211 |
+
return {"sent": sent, "failed": failed, "skipped": skipped,
|
| 212 |
+
"safeMode": bool(cs.SAFE_MODE), "test": bool(override)}
|
| 213 |
+
|
| 214 |
+
|
| 215 |
+
# ---------------------------------------------------------------------------------------------
|
| 216 |
+
# WAVE 35 Β· T36 / CONTRACT C8 / OWNER RULING R10 β THE AGENT'S PARKED BATCH.
|
| 217 |
+
#
|
| 218 |
+
# ββ THE AGENT ASSEMBLES; A PERSON CLICKS SEND. `automation_engine.run_statements` renders a batch
|
| 219 |
+
# and parks it on the automation definition, and it imports no mail path at all. THIS is the only
|
| 220 |
+
# door that releases one, and it is deliberately built out of the parts already here:
|
| 221 |
+
# Β· `_gate` β `admin_gate` THEN `_royal_only`, byte-for-byte the dependency the other three
|
| 222 |
+
# endpoints use. Not a copy of the checks: the same object.
|
| 223 |
+
# Β· `cs.queue_statement` β the same call `send()` above makes, so SAFE_MODE's allow-list refusal
|
| 224 |
+
# happens in the DATA LAYER, where no route, payload or UI can reach around it.
|
| 225 |
+
# β Nothing about the guardrails is re-expressed here, which is what makes "unchanged" checkable.
|
| 226 |
+
#
|
| 227 |
+
# β WHY THE BATCH IS RE-RENDERED FROM THE LIVE WORKLIST RATHER THAN SENT AS STORED. The parked
|
| 228 |
+
# `html` is what a person APPROVED and is what the review screen shows; but a balance can move
|
| 229 |
+
# between the parking and the click, and mailing a figure we know to be stale is worse than mailing
|
| 230 |
+
# a fresh one. So the parked batch decides WHO and WITH WHAT WORDS, and the live row decides the
|
| 231 |
+
# NUMBERS β the same split `preview` already makes. A customer who has left the worklist entirely
|
| 232 |
+
# (they paid) is reported as skipped rather than invoiced.
|
| 233 |
+
|
| 234 |
+
@router.get("/admin/statements/agent/{auto_id}")
|
| 235 |
+
def agent_batch(auto_id: str, session: Session = Depends(_gate)):
|
| 236 |
+
"""What is parked and waiting for a click, for ONE agent. `null` when nothing is."""
|
| 237 |
+
defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
|
| 238 |
+
pending = defn.get("pendingStatements")
|
| 239 |
+
if not isinstance(pending, dict):
|
| 240 |
+
return {"pending": None}
|
| 241 |
+
# β The rendered `html` is NOT returned in the list β a 200-statement batch of rendered mail is
|
| 242 |
+
# megabytes, and the review screen needs the count and the names to decide. `preview` already
|
| 243 |
+
# renders ONE on demand.
|
| 244 |
+
return {"pending": {
|
| 245 |
+
"ts": pending.get("ts"), "count": int(pending.get("count") or 0),
|
| 246 |
+
"notes": list(pending.get("notes") or []),
|
| 247 |
+
"items": [{k: v for k, v in it.items() if k != "html"}
|
| 248 |
+
for it in (pending.get("items") or [])],
|
| 249 |
+
"safeMode": bool(_cs().SAFE_MODE)}}
|
| 250 |
+
|
| 251 |
+
|
| 252 |
+
@router.post("/admin/statements/agent/{auto_id}/send")
|
| 253 |
+
def agent_send(auto_id: str, body: dict = Body(default=None),
|
| 254 |
+
session: Session = Depends(_gate)):
|
| 255 |
+
"""Release a parked batch. THE CLICK R10 REQUIRES β nothing else in the system calls this.
|
| 256 |
+
|
| 257 |
+
β IT REFUSES AN EMPTY OR MISSING BATCH rather than answering 200 with nothing sent: a send
|
| 258 |
+
that reports success and mails nobody is the `view_upsert` failure mode (200 OK, zero writes)
|
| 259 |
+
arriving on the one route in this system that talks to a mail server.
|
| 260 |
+
"""
|
| 261 |
+
cs = _cs()
|
| 262 |
+
defn = (engine.all_definitions(session.runtime) or {}).get(str(auto_id)) or {}
|
| 263 |
+
pending = defn.get("pendingStatements")
|
| 264 |
+
items = list((pending or {}).get("items") or []) if isinstance(pending, dict) else []
|
| 265 |
+
if not items:
|
| 266 |
+
raise err(404, "no_batch", "there is nothing parked for this agent to send")
|
| 267 |
+
# β An explicit subset is allowed (a person unticking a customer on the review screen) but it
|
| 268 |
+
# may only NARROW the parked batch. A name that was never parked cannot be introduced by the
|
| 269 |
+
# payload, or the review stops being what authorised the send.
|
| 270 |
+
want = {str(n) for n in (body or {}).get("customers") or []}
|
| 271 |
+
if want:
|
| 272 |
+
items = [it for it in items if str(it.get("customer")) in want]
|
| 273 |
+
if not items:
|
| 274 |
+
raise err(400, "bad_request", "none of those customers are in the parked batch")
|
| 275 |
+
rows, _ = _rows()
|
| 276 |
+
sent, failed, skipped = [], [], []
|
| 277 |
+
for it in items:
|
| 278 |
+
name = str(it.get("customer") or "")
|
| 279 |
+
row = _find(rows, name)
|
| 280 |
+
if row is None:
|
| 281 |
+
skipped.append({"customer": name,
|
| 282 |
+
"reason": "no longer on the collection list, so nothing is owed"})
|
| 283 |
+
continue
|
| 284 |
+
try:
|
| 285 |
+
# β THE SAME DATA-LAYER CALL `send()` MAKES. SafeModeBlocked is raised INSIDE
|
| 286 |
+
# `queue_statement`, so the guardrail cannot be argued with from here.
|
| 287 |
+
mid = cs.queue_statement(cs.Odoo(), row,
|
| 288 |
+
str(it.get("subject") or "") or cs.DEFAULT_SUBJECT,
|
| 289 |
+
cs.DEFAULT_INTRO, cs.DEFAULT_FOOTER)
|
| 290 |
+
sent.append({"customer": name, "to": row.get("Email"), "mailId": mid})
|
| 291 |
+
except Exception as e: # noqa: BLE001
|
| 292 |
+
failed.append({"customer": name, "error": str(e)[:200]})
|
| 293 |
+
# β CLEARED ONLY WHEN NOTHING IS LEFT TO RETRY. A batch dropped while some of it failed would
|
| 294 |
+
# lose the list of who still needs a statement, and nobody would know to look.
|
| 295 |
+
if sent and not failed:
|
| 296 |
+
engine.clear_statements(session.runtime, auto_id)
|
| 297 |
+
return {"sent": sent, "failed": failed, "skipped": skipped,
|
| 298 |
+
"safeMode": bool(cs.SAFE_MODE), "cleared": bool(sent and not failed)}
|
api/routes_web_agent.py
CHANGED
|
@@ -1,84 +1,84 @@
|
|
| 1 |
-
"""routes_web_agent.py β the door that lets a person TEST the web agent (wave 31, R10 / D-51).
|
| 2 |
-
|
| 3 |
-
The owner's words are the whole reason this file exists: *"we already laid the foundation of this
|
| 4 |
-
but never test anything."* The capability is otherwise reachable only from inside an automation
|
| 5 |
-
run, which means the first person to discover it is broken is a customer at 3am.
|
| 6 |
-
|
| 7 |
-
GET /api/v1/web-agent/capability any session β can this deployment run a web step, and
|
| 8 |
-
if not, the SENTENCE saying why
|
| 9 |
-
POST /api/v1/web-agent/test ADMIN β run one real `web_read` and show what
|
| 10 |
-
came back, or the sentence
|
| 11 |
-
|
| 12 |
-
β NEITHER ROUTE IS THE SEAM. `automation_engine` calls `web_agent.run_step` directly (contract
|
| 13 |
-
C5); these are an operator surface over the same function, so a green test here and a red run
|
| 14 |
-
there cannot disagree about anything except the input.
|
| 15 |
-
|
| 16 |
-
β `POST /test` BLOCKS FOR ~10-30 s and COSTS A FRACTION OF A CENT. It is `def`, not `async def`,
|
| 17 |
-
so FastAPI runs it in the threadpool and one test cannot stall the event loop for everybody.
|
| 18 |
-
|
| 19 |
-
β ON THE URL IT WILL FETCH: the fetch happens inside an ephemeral HF Job on Hugging Face's
|
| 20 |
-
network, never from this server, so this is not a door into our own infrastructure. It is still
|
| 21 |
-
admin-gated, because it spends money and because D-51 Β§5's authorisation posture ("only systems
|
| 22 |
-
the tenant is authorised to use, at their instruction") is not something an ordinary member
|
| 23 |
-
should be able to commit the tenant to.
|
| 24 |
-
|
| 25 |
-
β MOUNTED, and the gate is what says so rather than this sentence: `main.py:80` imports it and
|
| 26 |
-
`main.py:316` includes it, and `verify_web_agent.py` asserts the route answers rather than trusting
|
| 27 |
-
either line. This paragraph read "NOT MOUNTED YET" for a whole wave after the mount landed, which
|
| 28 |
-
is the same class of stale claim as a green gate on a router nobody wired: three finished routers
|
| 29 |
-
once shipped 404-dead behind entirely green gates, and prose is not the control that stops it.
|
| 30 |
-
"""
|
| 31 |
-
from fastapi import APIRouter, Body, Depends
|
| 32 |
-
|
| 33 |
-
import web_agent
|
| 34 |
-
from deps import Session, require_session, err
|
| 35 |
-
from routes_admin import admin_gate
|
| 36 |
-
|
| 37 |
-
router = APIRouter(prefix="/api/v1")
|
| 38 |
-
|
| 39 |
-
MAX_URL = 2000
|
| 40 |
-
MAX_SELECTOR = 400
|
| 41 |
-
|
| 42 |
-
|
| 43 |
-
@router.get("/web-agent/capability")
|
| 44 |
-
def web_agent_capability(session: Session = Depends(require_session)):
|
| 45 |
-
"""Can a web step run here at all? Configuration, not liveness β see `web_agent.capability`.
|
| 46 |
-
|
| 47 |
-
Deliberately NARROW: it answers the question a UI needs ("may I offer this, and what do I say
|
| 48 |
-
if not") and withholds the deployment detail (namespace, which token key, the image) that
|
| 49 |
-
only an operator has any use for. Nothing here is ever a credential.
|
| 50 |
-
"""
|
| 51 |
-
cap = web_agent.capability()
|
| 52 |
-
return {"ready": bool(cap["ready"]), "reason": cap["reason"],
|
| 53 |
-
"runnableKinds": cap["runnableKinds"], "profile": cap["profile"]}
|
| 54 |
-
|
| 55 |
-
|
| 56 |
-
@router.post("/web-agent/test")
|
| 57 |
-
def web_agent_test(session: Session = Depends(admin_gate), body: dict = Body(...)):
|
| 58 |
-
"""Run ONE real `web_read` and report exactly what the seam returned.
|
| 59 |
-
|
| 60 |
-
The response mirrors the seam's own contract rather than flattening it: `ok` plus a `value`,
|
| 61 |
-
or `ok:false` plus the SENTENCE. A test surface that turns a named failure into "something
|
| 62 |
-
went wrong" would hide the one thing it exists to show.
|
| 63 |
-
"""
|
| 64 |
-
url = str(body.get("url") or "").strip()
|
| 65 |
-
selector = str(body.get("selector") or "").strip()
|
| 66 |
-
if len(url) > MAX_URL or len(selector) > MAX_SELECTOR:
|
| 67 |
-
raise err(400, "too_long", "the URL or selector is longer than this door accepts")
|
| 68 |
-
|
| 69 |
-
step = {"kind": "web_read", "id": "test", "url": url, "selector": selector,
|
| 70 |
-
"attr": (body.get("attr") or "text"), "all": bool(body.get("all")),
|
| 71 |
-
"timeoutMs": int(body.get("timeoutMs") or 20000)}
|
| 72 |
-
if body.get("waitFor"):
|
| 73 |
-
step["waitFor"] = str(body["waitFor"])
|
| 74 |
-
|
| 75 |
-
notes = []
|
| 76 |
-
result, error = web_agent.run_step(
|
| 77 |
-
step, {"tenant": session.tenant, "runId": f"test-{session.tenant}-{session.uname}",
|
| 78 |
-
"log": notes.append})
|
| 79 |
-
if error:
|
| 80 |
-
# 200 with `ok:false`, not a 4xx: the request was well-formed and the ANSWER is that the
|
| 81 |
-
# web step did not succeed. A 500 here would make an ordinary "the selector matched
|
| 82 |
-
# nothing" look like a server fault.
|
| 83 |
-
return {"ok": False, "error": error, "log": notes[-6:]}
|
| 84 |
-
return {"ok": True, "result": result, "log": notes[-6:]}
|
|
|
|
| 1 |
+
"""routes_web_agent.py β the door that lets a person TEST the web agent (wave 31, R10 / D-51).
|
| 2 |
+
|
| 3 |
+
The owner's words are the whole reason this file exists: *"we already laid the foundation of this
|
| 4 |
+
but never test anything."* The capability is otherwise reachable only from inside an automation
|
| 5 |
+
run, which means the first person to discover it is broken is a customer at 3am.
|
| 6 |
+
|
| 7 |
+
GET /api/v1/web-agent/capability any session β can this deployment run a web step, and
|
| 8 |
+
if not, the SENTENCE saying why
|
| 9 |
+
POST /api/v1/web-agent/test ADMIN β run one real `web_read` and show what
|
| 10 |
+
came back, or the sentence
|
| 11 |
+
|
| 12 |
+
β NEITHER ROUTE IS THE SEAM. `automation_engine` calls `web_agent.run_step` directly (contract
|
| 13 |
+
C5); these are an operator surface over the same function, so a green test here and a red run
|
| 14 |
+
there cannot disagree about anything except the input.
|
| 15 |
+
|
| 16 |
+
β `POST /test` BLOCKS FOR ~10-30 s and COSTS A FRACTION OF A CENT. It is `def`, not `async def`,
|
| 17 |
+
so FastAPI runs it in the threadpool and one test cannot stall the event loop for everybody.
|
| 18 |
+
|
| 19 |
+
β ON THE URL IT WILL FETCH: the fetch happens inside an ephemeral HF Job on Hugging Face's
|
| 20 |
+
network, never from this server, so this is not a door into our own infrastructure. It is still
|
| 21 |
+
admin-gated, because it spends money and because D-51 Β§5's authorisation posture ("only systems
|
| 22 |
+
the tenant is authorised to use, at their instruction") is not something an ordinary member
|
| 23 |
+
should be able to commit the tenant to.
|
| 24 |
+
|
| 25 |
+
β MOUNTED, and the gate is what says so rather than this sentence: `main.py:80` imports it and
|
| 26 |
+
`main.py:316` includes it, and `verify_web_agent.py` asserts the route answers rather than trusting
|
| 27 |
+
either line. This paragraph read "NOT MOUNTED YET" for a whole wave after the mount landed, which
|
| 28 |
+
is the same class of stale claim as a green gate on a router nobody wired: three finished routers
|
| 29 |
+
once shipped 404-dead behind entirely green gates, and prose is not the control that stops it.
|
| 30 |
+
"""
|
| 31 |
+
from fastapi import APIRouter, Body, Depends
|
| 32 |
+
|
| 33 |
+
import web_agent
|
| 34 |
+
from deps import Session, require_session, err
|
| 35 |
+
from routes_admin import admin_gate
|
| 36 |
+
|
| 37 |
+
router = APIRouter(prefix="/api/v1")
|
| 38 |
+
|
| 39 |
+
MAX_URL = 2000
|
| 40 |
+
MAX_SELECTOR = 400
|
| 41 |
+
|
| 42 |
+
|
| 43 |
+
@router.get("/web-agent/capability")
|
| 44 |
+
def web_agent_capability(session: Session = Depends(require_session)):
|
| 45 |
+
"""Can a web step run here at all? Configuration, not liveness β see `web_agent.capability`.
|
| 46 |
+
|
| 47 |
+
Deliberately NARROW: it answers the question a UI needs ("may I offer this, and what do I say
|
| 48 |
+
if not") and withholds the deployment detail (namespace, which token key, the image) that
|
| 49 |
+
only an operator has any use for. Nothing here is ever a credential.
|
| 50 |
+
"""
|
| 51 |
+
cap = web_agent.capability()
|
| 52 |
+
return {"ready": bool(cap["ready"]), "reason": cap["reason"],
|
| 53 |
+
"runnableKinds": cap["runnableKinds"], "profile": cap["profile"]}
|
| 54 |
+
|
| 55 |
+
|
| 56 |
+
@router.post("/web-agent/test")
|
| 57 |
+
def web_agent_test(session: Session = Depends(admin_gate), body: dict = Body(...)):
|
| 58 |
+
"""Run ONE real `web_read` and report exactly what the seam returned.
|
| 59 |
+
|
| 60 |
+
The response mirrors the seam's own contract rather than flattening it: `ok` plus a `value`,
|
| 61 |
+
or `ok:false` plus the SENTENCE. A test surface that turns a named failure into "something
|
| 62 |
+
went wrong" would hide the one thing it exists to show.
|
| 63 |
+
"""
|
| 64 |
+
url = str(body.get("url") or "").strip()
|
| 65 |
+
selector = str(body.get("selector") or "").strip()
|
| 66 |
+
if len(url) > MAX_URL or len(selector) > MAX_SELECTOR:
|
| 67 |
+
raise err(400, "too_long", "the URL or selector is longer than this door accepts")
|
| 68 |
+
|
| 69 |
+
step = {"kind": "web_read", "id": "test", "url": url, "selector": selector,
|
| 70 |
+
"attr": (body.get("attr") or "text"), "all": bool(body.get("all")),
|
| 71 |
+
"timeoutMs": int(body.get("timeoutMs") or 20000)}
|
| 72 |
+
if body.get("waitFor"):
|
| 73 |
+
step["waitFor"] = str(body["waitFor"])
|
| 74 |
+
|
| 75 |
+
notes = []
|
| 76 |
+
result, error = web_agent.run_step(
|
| 77 |
+
step, {"tenant": session.tenant, "runId": f"test-{session.tenant}-{session.uname}",
|
| 78 |
+
"log": notes.append})
|
| 79 |
+
if error:
|
| 80 |
+
# 200 with `ok:false`, not a 4xx: the request was well-formed and the ANSWER is that the
|
| 81 |
+
# web step did not succeed. A 500 here would make an ordinary "the selector matched
|
| 82 |
+
# nothing" look like a server fault.
|
| 83 |
+
return {"ok": False, "error": error, "log": notes[-6:]}
|
| 84 |
+
return {"ok": True, "result": result, "log": notes[-6:]}
|
platform/core/script_sandbox.py
CHANGED
|
@@ -1,519 +1,519 @@
|
|
| 1 |
-
"""core/script_sandbox.py β WAVE 36 (R5 / R10, contract C1): running a tenant's OWN Python.
|
| 2 |
-
|
| 3 |
-
Owner item 6: *"Add code script as an interface (database View) so a user can build whatever they
|
| 4 |
-
want through the Agent chat interface."* Item 8: *"We need to really guardrail the reach of this
|
| 5 |
-
script. So let's really grill this down."* R10 ruled it SERVER-SIDE PYTHON after the trade was
|
| 6 |
-
stated, so this file is the guardrail, and one engine serves both items.
|
| 7 |
-
|
| 8 |
-
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 9 |
-
ββ THE ONE PARAGRAPH TO READ BEFORE CHANGING ANYTHING HERE.
|
| 10 |
-
|
| 11 |
-
In-process CPython cannot deliver two of this ticket's clauses. An AST allow-list plus a curated
|
| 12 |
-
namespace stops import, file, network and environment access β but it **cannot cap memory and
|
| 13 |
-
cannot interrupt a runaway loop**, because a `while True:` in the same interpreter is not a slow
|
| 14 |
-
request, it is the tenant's ONE FastAPI process gone. So the script runs in a **SUBPROCESS**:
|
| 15 |
-
`resource.setrlimit` for address space and CPU, a hard wall-clock kill from the parent, and the
|
| 16 |
-
allow-list inside. Neither half is sufficient; both are load-bearing.
|
| 17 |
-
|
| 18 |
-
β AND THE SUBPROCESS RECEIVES **ROWS, NEVER A STORE**. The parent calls C1's `scoped_table` under
|
| 19 |
-
the CALLING user's record and serialises the result; the child imports nothing from this repo and
|
| 20 |
-
holds no credential, no runtime and no store handle. Wiring W1 ("the sandbox has no second store
|
| 21 |
-
path") is then true by CONSTRUCTION rather than by discipline, and it is checkable: the child
|
| 22 |
-
reports its own `sys.modules`, and no `core.*` name may appear in it.
|
| 23 |
-
|
| 24 |
-
β NEVER A BLACKLIST. Every rule below is an ALLOW-LIST β a set of node types, a set of attribute
|
| 25 |
-
names, a dict of builtins. A blacklist of dangerous spellings is bypassable by construction, and
|
| 26 |
-
the bypass is usually one string method away (`"{0.__class__}".format(x)` performs its attribute
|
| 27 |
-
lookup inside `format`, so there is no `ast.Attribute` node to refuse).
|
| 28 |
-
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 29 |
-
|
| 30 |
-
The two layers, and they refuse DIFFERENT things on purpose:
|
| 31 |
-
|
| 32 |
-
1. `check_source()` β a pure function over source text. Refuses a construct the language offers
|
| 33 |
-
and this sandbox does not: `import`, `class`, `with`, `async`, `yield`, `global`, and every
|
| 34 |
-
attribute name outside `ALLOWED_ATTRS`.
|
| 35 |
-
2. `SANDBOX_BUILTINS` β the names that resolve at all. `__import__`, `open`, `eval`, `exec`,
|
| 36 |
-
`compile`, `getattr`, `globals`, `vars` and `type` are simply absent, so a source that gets
|
| 37 |
-
past layer 1 still finds nothing to call.
|
| 38 |
-
|
| 39 |
-
β THAT DUPLICATION IS DELIBERATE AND IT CHANGES HOW THE GATE MUST BE WRITTEN. `import os` is
|
| 40 |
-
refused twice, so a negative control that drops ONE layer sees the other refuse and reports
|
| 41 |
-
green β the shape that already cost this wave one missed control in `routes_agent_harness`. So
|
| 42 |
-
each layer is tested AT ITS OWN BOUNDARY: `check_source()` is called directly on source strings,
|
| 43 |
-
and `run()` is driven end to end. An NC drops one entry from one frozenset and the matching
|
| 44 |
-
boundary goes red.
|
| 45 |
-
"""
|
| 46 |
-
import ast
|
| 47 |
-
import json
|
| 48 |
-
import os
|
| 49 |
-
import subprocess
|
| 50 |
-
import sys
|
| 51 |
-
import tempfile
|
| 52 |
-
import time
|
| 53 |
-
from pathlib import Path
|
| 54 |
-
|
| 55 |
-
#: Wall clock, enforced by the PARENT with a kill. The one cap that works on every platform.
|
| 56 |
-
DEFAULT_TIMEOUT_S = 10.0
|
| 57 |
-
|
| 58 |
-
#: Address space for the child (`RLIMIT_AS`). POSIX only β see `run()`'s `caps` report.
|
| 59 |
-
DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024
|
| 60 |
-
|
| 61 |
-
#: CPU seconds for the child (`RLIMIT_CPU`). POSIX only. Deliberately above the wall clock: the
|
| 62 |
-
#: wall-clock kill is the primary control and this is the backstop for a child that stops being
|
| 63 |
-
#: reachable. A CPU limit BELOW the timeout would make every slow script look like a CPU refusal.
|
| 64 |
-
DEFAULT_CPU_SECONDS = 15
|
| 65 |
-
|
| 66 |
-
#: What the script may print, in bytes. `print` is a curated builtin writing to a capped buffer,
|
| 67 |
-
#: and the child's real stdout goes to DEVNULL β so a script cannot fill a pipe, and anything
|
| 68 |
-
#: that escaped far enough to write to fd 1 has nowhere for it to land.
|
| 69 |
-
MAX_STDOUT_BYTES = 64 * 1024
|
| 70 |
-
|
| 71 |
-
#: The serialised ROW payload handed to the child. β A REFUSAL, NEVER A TRUNCATION (standing rule
|
| 72 |
-
#: 1): a short answer from a data tool is a wrong answer that looks right. Over this, `run()`
|
| 73 |
-
#: returns a named limit carrying its cause and a recommendation.
|
| 74 |
-
MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
|
| 75 |
-
|
| 76 |
-
#: The emitted spec. A render spec is a description of a picture; one larger than this is data
|
| 77 |
-
#: pretending to be a description.
|
| 78 |
-
MAX_SPEC_BYTES = 2 * 1024 * 1024
|
| 79 |
-
|
| 80 |
-
MAX_SOURCE_BYTES = 128 * 1024
|
| 81 |
-
|
| 82 |
-
|
| 83 |
-
# ββββββ
|
| 84 |
-
#: Every `ast` node class a script may contain. β THE ABSENCES ARE THE POLICY: `Import` /
|
| 85 |
-
#: `ImportFrom` (no module reaches the script), `ClassDef` (a class body is a namespace with its
|
| 86 |
-
#: own scoping rules and buys a data script nothing), `With` (a context manager is `__enter__`
|
| 87 |
-
#: by another spelling), `Global` / `Nonlocal` (rebinding the sandbox's own names), and every
|
| 88 |
-
#: `Async*` / `Await` / `Yield` form (this engine is synchronous; a coroutine that is never
|
| 89 |
-
#: awaited is a silent no-op that looks like a working script).
|
| 90 |
-
ALLOWED_NODES = frozenset("""
|
| 91 |
-
Module Expr Assign AugAssign AnnAssign NamedExpr Return Pass Break Continue Delete Assert Raise
|
| 92 |
-
If For While Try TryStar ExceptHandler FunctionDef Lambda arguments arg keyword
|
| 93 |
-
BoolOp BinOp UnaryOp IfExp Dict Set List Tuple Starred Subscript Slice Compare Call Attribute Name
|
| 94 |
-
Constant JoinedStr FormattedValue ListComp SetComp DictComp GeneratorExp comprehension
|
| 95 |
-
Load Store Del
|
| 96 |
-
And Or Not Invert UAdd USub
|
| 97 |
-
Add Sub Mult Div FloorDiv Mod Pow LShift RShift BitOr BitXor BitAnd MatMult
|
| 98 |
-
Eq NotEq Lt LtE Gt GtE Is IsNot In NotIn
|
| 99 |
-
""".split())
|
| 100 |
-
|
| 101 |
-
#: Every attribute name a script may READ or CALL. ββ THIS IS THE LOAD-BEARING SET, and it is
|
| 102 |
-
#: an allow-list of NAMES rather than a refusal of dunders, because the interesting escapes are
|
| 103 |
-
#: ordinary-looking: `f.__globals__` on any function reaches the runner's own module namespace,
|
| 104 |
-
#: `e.__traceback__.tb_frame.f_globals` reaches it from an exception handler, and `().__class__`
|
| 105 |
-
#: reaches `object.__subclasses__`. None of those names is here, and neither is any name this
|
| 106 |
-
#: sandbox has not been asked for.
|
| 107 |
-
#: β `format` IS ABSENT DELIBERATELY. `"{0.__class__}".format(x)` performs the attribute lookup
|
| 108 |
-
#: INSIDE `str.format`, where no `ast.Attribute` node exists for layer 1 to see. f-strings are
|
| 109 |
-
#: fine β `f"{x.__class__}"` compiles to a real `Attribute` node and is refused.
|
| 110 |
-
ALLOWED_ATTRS = frozenset("""
|
| 111 |
-
append extend insert pop remove clear sort reverse copy count index
|
| 112 |
-
keys values items get setdefault update
|
| 113 |
-
add discard union intersection difference issubset issuperset
|
| 114 |
-
join split rsplit splitlines strip lstrip rstrip lower upper title capitalize casefold
|
| 115 |
-
replace startswith endswith find rfind zfill ljust rjust center partition removeprefix removesuffix
|
| 116 |
-
isdigit isalpha isalnum isspace isupper islower isnumeric
|
| 117 |
-
real imag numerator denominator
|
| 118 |
-
""".split())
|
| 119 |
-
|
| 120 |
-
|
| 121 |
-
class Refused(Exception):
|
| 122 |
-
"""A named refusal: `code` for a caller to branch on, `message` for a person to read."""
|
| 123 |
-
|
| 124 |
-
def __init__(self, code, message):
|
| 125 |
-
self.code, self.message = code, message
|
| 126 |
-
super().__init__(f"{code}: {message}")
|
| 127 |
-
|
| 128 |
-
|
| 129 |
-
def _attr_ok(name):
|
| 130 |
-
"""An attribute name passes only if it is on the list AND is not private.
|
| 131 |
-
|
| 132 |
-
β THE SECOND TEST IS NOT A BLACKLIST β it narrows an allow-list that already excludes every
|
| 133 |
-
private name. It is here so that adding a name to `ALLOWED_ATTRS` cannot open a dunder by
|
| 134 |
-
accident, which is the one edit a future reader is most likely to make in a hurry.
|
| 135 |
-
"""
|
| 136 |
-
return name in ALLOWED_ATTRS and not name.startswith("_")
|
| 137 |
-
|
| 138 |
-
|
| 139 |
-
def check_source(source):
|
| 140 |
-
"""LAYER 1. Return a `Refused` for source this sandbox will not run, or `None`.
|
| 141 |
-
|
| 142 |
-
β PURE, AND THAT IS WHAT MAKES IT TESTABLE AT ITS OWN BOUNDARY. It reads no file, spawns no
|
| 143 |
-
process and touches no store, so a gate can hand it a hundred hostile strings for free and an
|
| 144 |
-
NC can drop one entry from one frozenset and watch exactly this function change its answer.
|
| 145 |
-
"""
|
| 146 |
-
text = str(source or "")
|
| 147 |
-
if len(text.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
|
| 148 |
-
return Refused("source_too_long",
|
| 149 |
-
f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of source")
|
| 150 |
-
try:
|
| 151 |
-
tree = ast.parse(text)
|
| 152 |
-
except SyntaxError as exc:
|
| 153 |
-
return Refused("syntax", f"line {exc.lineno or 0}: {exc.msg}")
|
| 154 |
-
|
| 155 |
-
for node in ast.walk(tree):
|
| 156 |
-
kind = type(node).__name__
|
| 157 |
-
if kind not in ALLOWED_NODES:
|
| 158 |
-
return Refused("refused_construct",
|
| 159 |
-
f"line {getattr(node, 'lineno', 0)}: this sandbox does not run "
|
| 160 |
-
f"{_english(kind)}")
|
| 161 |
-
if isinstance(node, ast.Attribute) and not _attr_ok(node.attr):
|
| 162 |
-
return Refused("refused_attribute",
|
| 163 |
-
f"line {getattr(node, 'lineno', 0)}: the attribute "
|
| 164 |
-
f"'{node.attr}' is not available inside a script view")
|
| 165 |
-
# β A NAME may not be private either. `_` prefixed names are the runner's own, and a
|
| 166 |
-
# script that could bind one could shadow the machinery it runs on top of.
|
| 167 |
-
if isinstance(node, ast.Name) and node.id.startswith("_"):
|
| 168 |
-
return Refused("reserved_name",
|
| 169 |
-
f"line {getattr(node, 'lineno', 0)}: names starting with an "
|
| 170 |
-
f"underscore are reserved by the sandbox")
|
| 171 |
-
if isinstance(node, (ast.FunctionDef, ast.arg, ast.ExceptHandler)) and str(
|
| 172 |
-
getattr(node, "name", None) or getattr(node, "arg", "") or "").startswith("_"):
|
| 173 |
-
return Refused("reserved_name",
|
| 174 |
-
f"line {getattr(node, 'lineno', 0)}: names starting with an "
|
| 175 |
-
f"underscore are reserved by the sandbox")
|
| 176 |
-
if isinstance(node, ast.keyword) and str(node.arg or "").startswith("_"):
|
| 177 |
-
return Refused("reserved_name",
|
| 178 |
-
f"line {getattr(node, 'lineno', 0)}: keyword arguments starting with "
|
| 179 |
-
f"an underscore are reserved by the sandbox")
|
| 180 |
-
return None
|
| 181 |
-
|
| 182 |
-
|
| 183 |
-
_ENGLISH = {
|
| 184 |
-
"Import": "an import", "ImportFrom": "an import", "ClassDef": "a class definition",
|
| 185 |
-
"With": "a with block", "AsyncWith": "a with block", "AsyncFor": "an async loop",
|
| 186 |
-
"AsyncFunctionDef": "an async function", "Await": "await", "Yield": "yield",
|
| 187 |
-
"YieldFrom": "yield from", "Global": "a global statement", "Nonlocal": "a nonlocal statement",
|
| 188 |
-
"Match": "a match statement",
|
| 189 |
-
}
|
| 190 |
-
|
| 191 |
-
|
| 192 |
-
def _english(kind):
|
| 193 |
-
return _ENGLISH.get(kind, f"a {kind} expression")
|
| 194 |
-
|
| 195 |
-
|
| 196 |
-
# ββββββββββββββββββββββββββββββββββββββββββ LAYER 2 β the namespace, and the child program βββββ
|
| 197 |
-
#: The builtins a script may reach, BY NAME. Everything else is a `NameError` in the child.
|
| 198 |
-
#: β THE ABSENCES, again, are the policy: `__import__` `open` `eval` `exec` `compile` `input`
|
| 199 |
-
#: `getattr` `setattr` `delattr` `globals` `locals` `vars` `dir` `type` `super` `object` `help`
|
| 200 |
-
#: `exit` `breakpoint` `memoryview` `id`. Several are harmless on their own; each one is a step
|
| 201 |
-
#: on a published escape, and none has ever been asked for by a script that shapes rows.
|
| 202 |
-
#: β THE EXCEPTION CLASSES ARE HERE BECAUSE `try:` IS, and a `try` block whose `except` clause
|
| 203 |
-
#: cannot name what it catches is a construct that reads as supported and is not. They are safe
|
| 204 |
-
#: for the same reason everything else is: `Exception.__subclasses__` needs an attribute this
|
| 205 |
-
#: sandbox does not allow, so a class object in the namespace is a leaf, not a doorway.
|
| 206 |
-
SANDBOX_BUILTIN_NAMES = (
|
| 207 |
-
"abs all any bool bytes callable chr dict divmod enumerate filter float frozenset hash hex "
|
| 208 |
-
"int isinstance issubclass iter len list map max min next oct ord pow range repr reversed "
|
| 209 |
-
"round set slice sorted str sum tuple zip True False None "
|
| 210 |
-
"Exception ValueError TypeError KeyError IndexError ZeroDivisionError ArithmeticError "
|
| 211 |
-
"AttributeError StopIteration OverflowError"
|
| 212 |
-
).split()
|
| 213 |
-
|
| 214 |
-
#: The literal program the child runs. It is TEXT rather than a module because the child must
|
| 215 |
-
#: import nothing from this repo: a module would be found on `sys.path` and would drag `core`
|
| 216 |
-
#: with it, which is exactly the second store path W1 forbids.
|
| 217 |
-
#: β Every name in here is underscore-prefixed and layer 1 refuses a script from binding one, so
|
| 218 |
-
#: the runner's own machinery cannot be shadowed by the source it executes.
|
| 219 |
-
_RUNNER = r'''
|
| 220 |
-
import json as _json, os as _os, sys as _sys
|
| 221 |
-
|
| 222 |
-
_pay = _json.loads(open(_sys.argv[1], "r", encoding="utf-8").read())
|
| 223 |
-
_out = {"ok": False, "code": "not_run", "message": "the script did not run",
|
| 224 |
-
"stdout": "", "spec": None, "caps": {"wallClock": True, "memory": False, "cpu": False}}
|
| 225 |
-
|
| 226 |
-
# ββ the caps this platform can actually apply, reported either way (standing rule 1) ββββββββββ
|
| 227 |
-
try:
|
| 228 |
-
import resource as _res
|
| 229 |
-
_mem = int(_pay["memoryBytes"])
|
| 230 |
-
_res.setrlimit(_res.RLIMIT_AS, (_mem, _mem))
|
| 231 |
-
_out["caps"]["memory"] = True
|
| 232 |
-
_cpu = int(_pay["cpuSeconds"])
|
| 233 |
-
_res.setrlimit(_res.RLIMIT_CPU, (_cpu, _cpu))
|
| 234 |
-
_out["caps"]["cpu"] = True
|
| 235 |
-
except Exception:
|
| 236 |
-
# `resource` is POSIX only. The wall-clock kill in the parent still applies, and `caps` says
|
| 237 |
-
# which of the three held, never a silent partial.
|
| 238 |
-
pass
|
| 239 |
-
|
| 240 |
-
_printed = []
|
| 241 |
-
_spent = [0]
|
| 242 |
-
_LIMIT = int(_pay["maxStdout"])
|
| 243 |
-
|
| 244 |
-
|
| 245 |
-
def _print(*_a, **_k):
|
| 246 |
-
_text = (_k.get("sep") or " ").join(str(_x) for _x in _a) + (_k.get("end") or "\n")
|
| 247 |
-
_room = _LIMIT - _spent[0]
|
| 248 |
-
if _room > 0:
|
| 249 |
-
_printed.append(_text[:_room])
|
| 250 |
-
_spent[0] += len(_text)
|
| 251 |
-
|
| 252 |
-
|
| 253 |
-
class _Refusal(Exception):
|
| 254 |
-
"""The SANDBOX refusing, as distinct from the SCRIPT failing.
|
| 255 |
-
|
| 256 |
-
Without its own class these arrive as `ValueError`, indistinguishable from a `ValueError` the
|
| 257 |
-
script raised itself, and the answer then says "refused" about an ordinary bug in the tenant's
|
| 258 |
-
own code. Two different facts, two different codes.
|
| 259 |
-
"""
|
| 260 |
-
|
| 261 |
-
|
| 262 |
-
_emitted = []
|
| 263 |
-
|
| 264 |
-
|
| 265 |
-
def _emit(_spec):
|
| 266 |
-
if not isinstance(_spec, dict):
|
| 267 |
-
raise _Refusal("emit() takes a view spec, which is a dictionary")
|
| 268 |
-
if _emitted:
|
| 269 |
-
raise _Refusal("emit() was already called; a script view emits exactly one view")
|
| 270 |
-
_emitted.append(_spec)
|
| 271 |
-
|
| 272 |
-
|
| 273 |
-
_rows = _pay["rows"]
|
| 274 |
-
_fields = _pay["fields"]
|
| 275 |
-
_bound = _pay["table"]
|
| 276 |
-
|
| 277 |
-
|
| 278 |
-
def _scoped_table(_table=None):
|
| 279 |
-
if _table is not None and str(_table) != _bound:
|
| 280 |
-
raise _Refusal(
|
| 281 |
-
"this script view is bound to the database '" + _bound + "' and asked for '"
|
| 282 |
-
+ str(_table) + "'. A script view reads its own database only")
|
| 283 |
-
return [dict(_r) for _r in _rows]
|
| 284 |
-
|
| 285 |
-
|
| 286 |
-
def _scoped_fields():
|
| 287 |
-
return [dict(_f) for _f in _fields]
|
| 288 |
-
|
| 289 |
-
|
| 290 |
-
_ns = {"__builtins__": {_n: __builtins__[_n] if isinstance(__builtins__, dict)
|
| 291 |
-
else getattr(__builtins__, _n)
|
| 292 |
-
for _n in _pay["builtins"]}}
|
| 293 |
-
_ns["__builtins__"]["print"] = _print
|
| 294 |
-
_ns["print"] = _print
|
| 295 |
-
_ns["emit"] = _emit
|
| 296 |
-
_ns["scoped_table"] = _scoped_table
|
| 297 |
-
_ns["scoped_fields"] = _scoped_fields
|
| 298 |
-
_ns["table"] = _bound
|
| 299 |
-
|
| 300 |
-
try:
|
| 301 |
-
exec(compile(_pay["source"], "<script view>", "exec"), _ns)
|
| 302 |
-
if not _emitted:
|
| 303 |
-
_out.update(ok=False, code="no_view",
|
| 304 |
-
message="the script finished without calling emit(spec)")
|
| 305 |
-
else:
|
| 306 |
-
_out.update(ok=True, code="", message="", spec=_emitted[0])
|
| 307 |
-
except _Refusal as _e:
|
| 308 |
-
_out.update(ok=False, code="refused", message=str(_e)[:400])
|
| 309 |
-
except MemoryError:
|
| 310 |
-
_out.update(ok=False, code="memory",
|
| 311 |
-
message="the script used more memory than a script view is allowed")
|
| 312 |
-
except NameError as _e:
|
| 313 |
-
_out.update(ok=False, code="refused_name",
|
| 314 |
-
message=str(_e)[:200] + ". A script view may use only the names the sandbox "
|
| 315 |
-
"provides")
|
| 316 |
-
except BaseException as _e:
|
| 317 |
-
_out.update(ok=False, code="error",
|
| 318 |
-
message=type(_e).__name__ + ": " + str(_e)[:400])
|
| 319 |
-
|
| 320 |
-
_out["stdout"] = "".join(_printed)
|
| 321 |
-
_out["truncated"] = _spent[0] > _LIMIT
|
| 322 |
-
# β THE PROBE: what this child actually had. The PARENT strips it unless it was asked for, so a
|
| 323 |
-
# production run never carries it and a gate can still prove that no `core.*` module and no
|
| 324 |
-
# secret-shaped environment key was ever inside this process.
|
| 325 |
-
# β SNAPSHOTTED AFTER `exec`, and `os` is imported at the TOP so this list does not depend on
|
| 326 |
-
# dict-literal evaluation order. The first draft called `__import__("os")` inside this very
|
| 327 |
-
# expression, so whether `os` appeared depended on which value Python built first: a probe whose
|
| 328 |
-
# contents move with an unrelated edit is a probe a gate cannot assert against.
|
| 329 |
-
_out["probe"] = {"modules": sorted(_sys.modules), "env": sorted(_os.environ)}
|
| 330 |
-
open(_sys.argv[2], "w", encoding="utf-8").write(_json.dumps(_out, default=str))
|
| 331 |
-
'''
|
| 332 |
-
|
| 333 |
-
|
| 334 |
-
def _child_env():
|
| 335 |
-
"""The child's WHOLE environment. An allow-list of two keys, and neither is a credential.
|
| 336 |
-
|
| 337 |
-
β NOT `os.environ.copy()` MINUS SOMETHING. A subtractive environment ships every key nobody
|
| 338 |
-
thought to name: `HF_TOKEN`, `ODOO_PASSWORD`, `ANTHROPIC_API_KEY` and whatever the next
|
| 339 |
-
connector adds. The three names below are here because Python will not start on Windows
|
| 340 |
-
without them; on Linux this returns `{}` and the child runs with no environment at all.
|
| 341 |
-
"""
|
| 342 |
-
env = {}
|
| 343 |
-
for name in ("SystemRoot", "SYSTEMROOT", "WINDIR"):
|
| 344 |
-
if os.environ.get(name):
|
| 345 |
-
env[name] = os.environ[name]
|
| 346 |
-
return env
|
| 347 |
-
|
| 348 |
-
|
| 349 |
-
def run(source, rows, fields, table_key, *, timeout_s=DEFAULT_TIMEOUT_S,
|
| 350 |
-
memory_bytes=DEFAULT_MEMORY_BYTES, cpu_seconds=DEFAULT_CPU_SECONDS, probe=False):
|
| 351 |
-
"""Run ONE script over rows that are ALREADY scoped. Returns C3's envelope plus `caps`.
|
| 352 |
-
|
| 353 |
-
{ok, code, message, spec, stdout, truncated, ms, caps: {wallClock, memory, cpu}}
|
| 354 |
-
|
| 355 |
-
β THIS FUNCTION NEVER TOUCHES A STORE, AND THAT IS THE POINT: it takes rows. `run_view()`
|
| 356 |
-
below is the door that fetches them through C1; keeping the two apart is what lets a gate
|
| 357 |
-
drive the sandbox with no tenant, no runtime and no credential anywhere in the process.
|
| 358 |
-
|
| 359 |
-
β `caps` IS PART OF THE ANSWER, NOT DEBUG OUTPUT. On Windows `resource` does not exist, so
|
| 360 |
-
the memory and CPU limits are NOT applied and this says so. A caller that reports `ok:true`
|
| 361 |
-
without reading `caps` is claiming an enforcement that did not happen (standing rule 1).
|
| 362 |
-
"""
|
| 363 |
-
started = time.monotonic()
|
| 364 |
-
refusal = check_source(source)
|
| 365 |
-
if refusal is not None:
|
| 366 |
-
return _refusal(refusal.code, refusal.message, started)
|
| 367 |
-
|
| 368 |
-
payload = {"source": str(source or ""), "rows": rows, "fields": fields,
|
| 369 |
-
"table": str(table_key or ""), "builtins": SANDBOX_BUILTIN_NAMES,
|
| 370 |
-
"maxStdout": MAX_STDOUT_BYTES, "memoryBytes": int(memory_bytes),
|
| 371 |
-
"cpuSeconds": int(cpu_seconds)}
|
| 372 |
-
try:
|
| 373 |
-
blob = json.dumps(payload, default=str)
|
| 374 |
-
except (TypeError, ValueError) as exc:
|
| 375 |
-
return _refusal("bad_rows", f"these rows cannot be handed to a script ({exc})", started)
|
| 376 |
-
if len(blob.encode("utf-8", "replace")) > MAX_PAYLOAD_BYTES:
|
| 377 |
-
# β REPORTED, NOT TRUNCATED (standing rule 1's second sentence): cause and recommendation,
|
| 378 |
-
# in the words the owner asked for, rather than a quietly short answer.
|
| 379 |
-
return _refusal(
|
| 380 |
-
"payload_too_large",
|
| 381 |
-
f"this database's rows are larger than the {MAX_PAYLOAD_BYTES // (1024 * 1024)} MB a "
|
| 382 |
-
f"script view can be handed at once. Narrow the view with a filter, or raise the "
|
| 383 |
-
f"sandbox payload limit for this deployment", started)
|
| 384 |
-
|
| 385 |
-
with tempfile.TemporaryDirectory(prefix="aios-script-") as work:
|
| 386 |
-
pay_path = Path(work) / "payload.json"
|
| 387 |
-
res_path = Path(work) / "result.json"
|
| 388 |
-
pay_path.write_text(blob, encoding="utf-8")
|
| 389 |
-
# `-I` isolates the interpreter (no PYTHON* env, no user site), `-S` skips site-packages,
|
| 390 |
-
# and the program arrives on STDIN so there is no file for anything to import it as.
|
| 391 |
-
# β `-X utf8` AND AN EXPLICIT `encoding` ARE NOT TIDINESS. Without them this pipe is
|
| 392 |
-
# encoded with the parent's locale codec, which on this Windows box is cp1252: the runner
|
| 393 |
-
# text below cannot be represented in it and `subprocess.run` died with
|
| 394 |
-
# `UnicodeEncodeError` before the child ever started. A sandbox whose behaviour depends on
|
| 395 |
-
# the operator's locale is a sandbox with two behaviours. `-I` implies `-E`, so
|
| 396 |
-
# `PYTHONUTF8` in the environment could not have carried this, it has to be a flag.
|
| 397 |
-
argv = [sys.executable, "-I", "-S", "-X", "utf8", "-", str(pay_path), str(res_path)]
|
| 398 |
-
try:
|
| 399 |
-
done = subprocess.run(
|
| 400 |
-
argv, input=_RUNNER, text=True, encoding="utf-8", errors="replace",
|
| 401 |
-
cwd=work, env=_child_env(),
|
| 402 |
-
stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout_s)
|
| 403 |
-
except subprocess.TimeoutExpired:
|
| 404 |
-
return _refusal("timeout",
|
| 405 |
-
f"the script ran longer than {timeout_s:g} seconds and was stopped",
|
| 406 |
-
started)
|
| 407 |
-
except OSError as exc:
|
| 408 |
-
return _refusal("no_sandbox",
|
| 409 |
-
f"a script view could not be started on this deployment ({exc})",
|
| 410 |
-
started)
|
| 411 |
-
|
| 412 |
-
if not res_path.is_file():
|
| 413 |
-
# The child died without writing an answer: an rlimit signal, an OOM kill, or a crash.
|
| 414 |
-
# β NAMED BY ITS RETURN CODE rather than reported as a generic failure β a memory kill
|
| 415 |
-
# and a bug in this file must not read identically to an operator.
|
| 416 |
-
return _refusal(*_died(done), started)
|
| 417 |
-
try:
|
| 418 |
-
out = json.loads(res_path.read_text(encoding="utf-8"))
|
| 419 |
-
except (OSError, ValueError) as exc:
|
| 420 |
-
return _refusal("unreadable", f"the script's answer could not be read ({exc})",
|
| 421 |
-
started)
|
| 422 |
-
|
| 423 |
-
out["ms"] = int((time.monotonic() - started) * 1000)
|
| 424 |
-
if out.get("ok"):
|
| 425 |
-
spec_error = _check_spec(out.get("spec"))
|
| 426 |
-
if spec_error:
|
| 427 |
-
out.update(ok=False, code="bad_spec", message=spec_error, spec=None)
|
| 428 |
-
if not probe:
|
| 429 |
-
out.pop("probe", None)
|
| 430 |
-
return out
|
| 431 |
-
|
| 432 |
-
|
| 433 |
-
def _died(done):
|
| 434 |
-
"""`(code, message)` for a child that produced no answer."""
|
| 435 |
-
rc = done.returncode
|
| 436 |
-
tail = " ".join((done.stderr or "").split())[-300:]
|
| 437 |
-
if rc in (-9, 137):
|
| 438 |
-
return "memory", "the script was stopped for using too much memory"
|
| 439 |
-
if rc in (-24, 152):
|
| 440 |
-
return "timeout", "the script used more processor time than a script view is allowed"
|
| 441 |
-
return "crashed", f"the script view engine stopped without an answer{': ' + tail if tail else ''}"
|
| 442 |
-
|
| 443 |
-
|
| 444 |
-
def _refusal(code, message, started):
|
| 445 |
-
return {"ok": False, "code": code, "message": message, "spec": None, "stdout": "",
|
| 446 |
-
"truncated": False, "ms": int((time.monotonic() - started) * 1000),
|
| 447 |
-
"caps": {"wallClock": True, "memory": False, "cpu": False}}
|
| 448 |
-
|
| 449 |
-
|
| 450 |
-
def _check_spec(spec):
|
| 451 |
-
"""C3: a spec is a DESCRIPTION the client draws. Never HTML, never a script, never a URL.
|
| 452 |
-
|
| 453 |
-
β THE CHECK IS ON THE KEYS, NOT ON THE STRING CONTENTS. Scanning values for `<script>` is a
|
| 454 |
-
blacklist and would pass `<SCR` + `IPT>`; refusing a spec that carries an `html`, `script`,
|
| 455 |
-
`src` or `onclick` key refuses the SHAPE that would let a renderer be talked into executing
|
| 456 |
-
something. The vocabulary of legal `kind`s is the ROUTE's business (W36-T37) β this is the
|
| 457 |
-
floor every caller gets whether or not the route above it remembers.
|
| 458 |
-
"""
|
| 459 |
-
if not isinstance(spec, dict):
|
| 460 |
-
return "the script emitted something that is not a view spec"
|
| 461 |
-
try:
|
| 462 |
-
blob = json.dumps(spec)
|
| 463 |
-
except (TypeError, ValueError):
|
| 464 |
-
return "the emitted view spec is not something the client can be sent"
|
| 465 |
-
if len(blob.encode("utf-8", "replace")) > MAX_SPEC_BYTES:
|
| 466 |
-
return (f"the emitted view spec is over {MAX_SPEC_BYTES // (1024 * 1024)} MB. A view spec "
|
| 467 |
-
f"describes a picture; it is not where the rows go")
|
| 468 |
-
banned = {"html", "innerhtml", "script", "src", "srcdoc", "href", "style", "onclick", "onload"}
|
| 469 |
-
found = sorted(k for k in _keys_of(spec) if str(k).lower() in banned)
|
| 470 |
-
if found:
|
| 471 |
-
return (f"a view spec may not carry {', '.join(found)}. The client DRAWS a spec, so a "
|
| 472 |
-
f"markup or URL key would be a script by another name")
|
| 473 |
-
return None
|
| 474 |
-
|
| 475 |
-
|
| 476 |
-
def _keys_of(value, depth=0):
|
| 477 |
-
"""Every key anywhere in a nested spec. Bounded, so a deep structure cannot spin this."""
|
| 478 |
-
if depth > 12:
|
| 479 |
-
return
|
| 480 |
-
if isinstance(value, dict):
|
| 481 |
-
for key, sub in value.items():
|
| 482 |
-
yield key
|
| 483 |
-
yield from _keys_of(sub, depth + 1)
|
| 484 |
-
elif isinstance(value, (list, tuple)):
|
| 485 |
-
for sub in value:
|
| 486 |
-
yield from _keys_of(sub, depth + 1)
|
| 487 |
-
|
| 488 |
-
|
| 489 |
-
# ββββββββββββββββββββββββββββββββββββββββββββββ THE DOOR β C1 is the ONLY way to a row βββββββββ
|
| 490 |
-
def run_view(user, table_key, source, st=None, **kw):
|
| 491 |
-
"""Fetch through C1 under `user`'s scope, then run the script over what came back (R5).
|
| 492 |
-
|
| 493 |
-
ββ THE FETCH HAPPENS IN THE PARENT AND ONLY ROWS CROSS INTO THE CHILD. That is wiring W1
|
| 494 |
-
made structural: the child has no runtime to ask, no store handle to open and no credential
|
| 495 |
-
to use, so "a script cannot read what its caller cannot read" is not a rule anybody has to
|
| 496 |
-
keep β there is no second path for it to be broken through.
|
| 497 |
-
|
| 498 |
-
β C1'S THREE EXCEPTIONS ARE ANSWERED, NEVER SWALLOWED. `UnknownTable`, `Denied` and
|
| 499 |
-
`Unresolvable` mean three different things to a person; collapsing them into "no rows" is the
|
| 500 |
-
silent-empty answer C1 was written to make impossible. `Unresolvable.as_limit()` is handed
|
| 501 |
-
through in the words it was raised with β standing rule 1's second sentence, verbatim.
|
| 502 |
-
"""
|
| 503 |
-
import core.perm_scope as perm_scope
|
| 504 |
-
|
| 505 |
-
key = str(table_key or "")
|
| 506 |
-
try:
|
| 507 |
-
rows = perm_scope.scoped_table(user, key, st=st)
|
| 508 |
-
fields = perm_scope.scoped_fields(user, key, st=st)
|
| 509 |
-
except perm_scope.UnknownTable as exc:
|
| 510 |
-
return _refusal("unknown_table", str(exc) or f"there is no database '{key}'",
|
| 511 |
-
time.monotonic())
|
| 512 |
-
except perm_scope.Denied as exc:
|
| 513 |
-
return _refusal("denied", str(exc) or "this account may not read that database",
|
| 514 |
-
time.monotonic())
|
| 515 |
-
except perm_scope.Unresolvable as exc:
|
| 516 |
-
out = _refusal("unresolvable", str(exc), time.monotonic())
|
| 517 |
-
out["limit"] = exc.as_limit()
|
| 518 |
-
return out
|
| 519 |
-
return run(source, rows, fields, key, **kw)
|
|
|
|
| 1 |
+
"""core/script_sandbox.py β WAVE 36 (R5 / R10, contract C1): running a tenant's OWN Python.
|
| 2 |
+
|
| 3 |
+
Owner item 6: *"Add code script as an interface (database View) so a user can build whatever they
|
| 4 |
+
want through the Agent chat interface."* Item 8: *"We need to really guardrail the reach of this
|
| 5 |
+
script. So let's really grill this down."* R10 ruled it SERVER-SIDE PYTHON after the trade was
|
| 6 |
+
stated, so this file is the guardrail, and one engine serves both items.
|
| 7 |
+
|
| 8 |
+
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 9 |
+
ββ THE ONE PARAGRAPH TO READ BEFORE CHANGING ANYTHING HERE.
|
| 10 |
+
|
| 11 |
+
In-process CPython cannot deliver two of this ticket's clauses. An AST allow-list plus a curated
|
| 12 |
+
namespace stops import, file, network and environment access β but it **cannot cap memory and
|
| 13 |
+
cannot interrupt a runaway loop**, because a `while True:` in the same interpreter is not a slow
|
| 14 |
+
request, it is the tenant's ONE FastAPI process gone. So the script runs in a **SUBPROCESS**:
|
| 15 |
+
`resource.setrlimit` for address space and CPU, a hard wall-clock kill from the parent, and the
|
| 16 |
+
allow-list inside. Neither half is sufficient; both are load-bearing.
|
| 17 |
+
|
| 18 |
+
β AND THE SUBPROCESS RECEIVES **ROWS, NEVER A STORE**. The parent calls C1's `scoped_table` under
|
| 19 |
+
the CALLING user's record and serialises the result; the child imports nothing from this repo and
|
| 20 |
+
holds no credential, no runtime and no store handle. Wiring W1 ("the sandbox has no second store
|
| 21 |
+
path") is then true by CONSTRUCTION rather than by discipline, and it is checkable: the child
|
| 22 |
+
reports its own `sys.modules`, and no `core.*` name may appear in it.
|
| 23 |
+
|
| 24 |
+
β NEVER A BLACKLIST. Every rule below is an ALLOW-LIST β a set of node types, a set of attribute
|
| 25 |
+
names, a dict of builtins. A blacklist of dangerous spellings is bypassable by construction, and
|
| 26 |
+
the bypass is usually one string method away (`"{0.__class__}".format(x)` performs its attribute
|
| 27 |
+
lookup inside `format`, so there is no `ast.Attribute` node to refuse).
|
| 28 |
+
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 29 |
+
|
| 30 |
+
The two layers, and they refuse DIFFERENT things on purpose:
|
| 31 |
+
|
| 32 |
+
1. `check_source()` β a pure function over source text. Refuses a construct the language offers
|
| 33 |
+
and this sandbox does not: `import`, `class`, `with`, `async`, `yield`, `global`, and every
|
| 34 |
+
attribute name outside `ALLOWED_ATTRS`.
|
| 35 |
+
2. `SANDBOX_BUILTINS` β the names that resolve at all. `__import__`, `open`, `eval`, `exec`,
|
| 36 |
+
`compile`, `getattr`, `globals`, `vars` and `type` are simply absent, so a source that gets
|
| 37 |
+
past layer 1 still finds nothing to call.
|
| 38 |
+
|
| 39 |
+
β THAT DUPLICATION IS DELIBERATE AND IT CHANGES HOW THE GATE MUST BE WRITTEN. `import os` is
|
| 40 |
+
refused twice, so a negative control that drops ONE layer sees the other refuse and reports
|
| 41 |
+
green β the shape that already cost this wave one missed control in `routes_agent_harness`. So
|
| 42 |
+
each layer is tested AT ITS OWN BOUNDARY: `check_source()` is called directly on source strings,
|
| 43 |
+
and `run()` is driven end to end. An NC drops one entry from one frozenset and the matching
|
| 44 |
+
boundary goes red.
|
| 45 |
+
"""
|
| 46 |
+
import ast
|
| 47 |
+
import json
|
| 48 |
+
import os
|
| 49 |
+
import subprocess
|
| 50 |
+
import sys
|
| 51 |
+
import tempfile
|
| 52 |
+
import time
|
| 53 |
+
from pathlib import Path
|
| 54 |
+
|
| 55 |
+
#: Wall clock, enforced by the PARENT with a kill. The one cap that works on every platform.
|
| 56 |
+
DEFAULT_TIMEOUT_S = 10.0
|
| 57 |
+
|
| 58 |
+
#: Address space for the child (`RLIMIT_AS`). POSIX only β see `run()`'s `caps` report.
|
| 59 |
+
DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024
|
| 60 |
+
|
| 61 |
+
#: CPU seconds for the child (`RLIMIT_CPU`). POSIX only. Deliberately above the wall clock: the
|
| 62 |
+
#: wall-clock kill is the primary control and this is the backstop for a child that stops being
|
| 63 |
+
#: reachable. A CPU limit BELOW the timeout would make every slow script look like a CPU refusal.
|
| 64 |
+
DEFAULT_CPU_SECONDS = 15
|
| 65 |
+
|
| 66 |
+
#: What the script may print, in bytes. `print` is a curated builtin writing to a capped buffer,
|
| 67 |
+
#: and the child's real stdout goes to DEVNULL β so a script cannot fill a pipe, and anything
|
| 68 |
+
#: that escaped far enough to write to fd 1 has nowhere for it to land.
|
| 69 |
+
MAX_STDOUT_BYTES = 64 * 1024
|
| 70 |
+
|
| 71 |
+
#: The serialised ROW payload handed to the child. β A REFUSAL, NEVER A TRUNCATION (standing rule
|
| 72 |
+
#: 1): a short answer from a data tool is a wrong answer that looks right. Over this, `run()`
|
| 73 |
+
#: returns a named limit carrying its cause and a recommendation.
|
| 74 |
+
MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
|
| 75 |
+
|
| 76 |
+
#: The emitted spec. A render spec is a description of a picture; one larger than this is data
|
| 77 |
+
#: pretending to be a description.
|
| 78 |
+
MAX_SPEC_BYTES = 2 * 1024 * 1024
|
| 79 |
+
|
| 80 |
+
MAX_SOURCE_BYTES = 128 * 1024
|
| 81 |
+
|
| 82 |
+
|
| 83 |
+
# ββββββββββββββββββββββββββββββββββββββββββββββββββββββ LAYER 1 β the AST allow-list βββββββββββ
|
| 84 |
+
#: Every `ast` node class a script may contain. β THE ABSENCES ARE THE POLICY: `Import` /
|
| 85 |
+
#: `ImportFrom` (no module reaches the script), `ClassDef` (a class body is a namespace with its
|
| 86 |
+
#: own scoping rules and buys a data script nothing), `With` (a context manager is `__enter__`
|
| 87 |
+
#: by another spelling), `Global` / `Nonlocal` (rebinding the sandbox's own names), and every
|
| 88 |
+
#: `Async*` / `Await` / `Yield` form (this engine is synchronous; a coroutine that is never
|
| 89 |
+
#: awaited is a silent no-op that looks like a working script).
|
| 90 |
+
ALLOWED_NODES = frozenset("""
|
| 91 |
+
Module Expr Assign AugAssign AnnAssign NamedExpr Return Pass Break Continue Delete Assert Raise
|
| 92 |
+
If For While Try TryStar ExceptHandler FunctionDef Lambda arguments arg keyword
|
| 93 |
+
BoolOp BinOp UnaryOp IfExp Dict Set List Tuple Starred Subscript Slice Compare Call Attribute Name
|
| 94 |
+
Constant JoinedStr FormattedValue ListComp SetComp DictComp GeneratorExp comprehension
|
| 95 |
+
Load Store Del
|
| 96 |
+
And Or Not Invert UAdd USub
|
| 97 |
+
Add Sub Mult Div FloorDiv Mod Pow LShift RShift BitOr BitXor BitAnd MatMult
|
| 98 |
+
Eq NotEq Lt LtE Gt GtE Is IsNot In NotIn
|
| 99 |
+
""".split())
|
| 100 |
+
|
| 101 |
+
#: Every attribute name a script may READ or CALL. ββ THIS IS THE LOAD-BEARING SET, and it is
|
| 102 |
+
#: an allow-list of NAMES rather than a refusal of dunders, because the interesting escapes are
|
| 103 |
+
#: ordinary-looking: `f.__globals__` on any function reaches the runner's own module namespace,
|
| 104 |
+
#: `e.__traceback__.tb_frame.f_globals` reaches it from an exception handler, and `().__class__`
|
| 105 |
+
#: reaches `object.__subclasses__`. None of those names is here, and neither is any name this
|
| 106 |
+
#: sandbox has not been asked for.
|
| 107 |
+
#: β `format` IS ABSENT DELIBERATELY. `"{0.__class__}".format(x)` performs the attribute lookup
|
| 108 |
+
#: INSIDE `str.format`, where no `ast.Attribute` node exists for layer 1 to see. f-strings are
|
| 109 |
+
#: fine β `f"{x.__class__}"` compiles to a real `Attribute` node and is refused.
|
| 110 |
+
ALLOWED_ATTRS = frozenset("""
|
| 111 |
+
append extend insert pop remove clear sort reverse copy count index
|
| 112 |
+
keys values items get setdefault update
|
| 113 |
+
add discard union intersection difference issubset issuperset
|
| 114 |
+
join split rsplit splitlines strip lstrip rstrip lower upper title capitalize casefold
|
| 115 |
+
replace startswith endswith find rfind zfill ljust rjust center partition removeprefix removesuffix
|
| 116 |
+
isdigit isalpha isalnum isspace isupper islower isnumeric
|
| 117 |
+
real imag numerator denominator
|
| 118 |
+
""".split())
|
| 119 |
+
|
| 120 |
+
|
| 121 |
+
class Refused(Exception):
|
| 122 |
+
"""A named refusal: `code` for a caller to branch on, `message` for a person to read."""
|
| 123 |
+
|
| 124 |
+
def __init__(self, code, message):
|
| 125 |
+
self.code, self.message = code, message
|
| 126 |
+
super().__init__(f"{code}: {message}")
|
| 127 |
+
|
| 128 |
+
|
| 129 |
+
def _attr_ok(name):
|
| 130 |
+
"""An attribute name passes only if it is on the list AND is not private.
|
| 131 |
+
|
| 132 |
+
β THE SECOND TEST IS NOT A BLACKLIST β it narrows an allow-list that already excludes every
|
| 133 |
+
private name. It is here so that adding a name to `ALLOWED_ATTRS` cannot open a dunder by
|
| 134 |
+
accident, which is the one edit a future reader is most likely to make in a hurry.
|
| 135 |
+
"""
|
| 136 |
+
return name in ALLOWED_ATTRS and not name.startswith("_")
|
| 137 |
+
|
| 138 |
+
|
| 139 |
+
def check_source(source):
|
| 140 |
+
"""LAYER 1. Return a `Refused` for source this sandbox will not run, or `None`.
|
| 141 |
+
|
| 142 |
+
β PURE, AND THAT IS WHAT MAKES IT TESTABLE AT ITS OWN BOUNDARY. It reads no file, spawns no
|
| 143 |
+
process and touches no store, so a gate can hand it a hundred hostile strings for free and an
|
| 144 |
+
NC can drop one entry from one frozenset and watch exactly this function change its answer.
|
| 145 |
+
"""
|
| 146 |
+
text = str(source or "")
|
| 147 |
+
if len(text.encode("utf-8", "replace")) > MAX_SOURCE_BYTES:
|
| 148 |
+
return Refused("source_too_long",
|
| 149 |
+
f"a script view is at most {MAX_SOURCE_BYTES // 1024} KB of source")
|
| 150 |
+
try:
|
| 151 |
+
tree = ast.parse(text)
|
| 152 |
+
except SyntaxError as exc:
|
| 153 |
+
return Refused("syntax", f"line {exc.lineno or 0}: {exc.msg}")
|
| 154 |
+
|
| 155 |
+
for node in ast.walk(tree):
|
| 156 |
+
kind = type(node).__name__
|
| 157 |
+
if kind not in ALLOWED_NODES:
|
| 158 |
+
return Refused("refused_construct",
|
| 159 |
+
f"line {getattr(node, 'lineno', 0)}: this sandbox does not run "
|
| 160 |
+
f"{_english(kind)}")
|
| 161 |
+
if isinstance(node, ast.Attribute) and not _attr_ok(node.attr):
|
| 162 |
+
return Refused("refused_attribute",
|
| 163 |
+
f"line {getattr(node, 'lineno', 0)}: the attribute "
|
| 164 |
+
f"'{node.attr}' is not available inside a script view")
|
| 165 |
+
# β A NAME may not be private either. `_` prefixed names are the runner's own, and a
|
| 166 |
+
# script that could bind one could shadow the machinery it runs on top of.
|
| 167 |
+
if isinstance(node, ast.Name) and node.id.startswith("_"):
|
| 168 |
+
return Refused("reserved_name",
|
| 169 |
+
f"line {getattr(node, 'lineno', 0)}: names starting with an "
|
| 170 |
+
f"underscore are reserved by the sandbox")
|
| 171 |
+
if isinstance(node, (ast.FunctionDef, ast.arg, ast.ExceptHandler)) and str(
|
| 172 |
+
getattr(node, "name", None) or getattr(node, "arg", "") or "").startswith("_"):
|
| 173 |
+
return Refused("reserved_name",
|
| 174 |
+
f"line {getattr(node, 'lineno', 0)}: names starting with an "
|
| 175 |
+
f"underscore are reserved by the sandbox")
|
| 176 |
+
if isinstance(node, ast.keyword) and str(node.arg or "").startswith("_"):
|
| 177 |
+
return Refused("reserved_name",
|
| 178 |
+
f"line {getattr(node, 'lineno', 0)}: keyword arguments starting with "
|
| 179 |
+
f"an underscore are reserved by the sandbox")
|
| 180 |
+
return None
|
| 181 |
+
|
| 182 |
+
|
| 183 |
+
_ENGLISH = {
|
| 184 |
+
"Import": "an import", "ImportFrom": "an import", "ClassDef": "a class definition",
|
| 185 |
+
"With": "a with block", "AsyncWith": "a with block", "AsyncFor": "an async loop",
|
| 186 |
+
"AsyncFunctionDef": "an async function", "Await": "await", "Yield": "yield",
|
| 187 |
+
"YieldFrom": "yield from", "Global": "a global statement", "Nonlocal": "a nonlocal statement",
|
| 188 |
+
"Match": "a match statement",
|
| 189 |
+
}
|
| 190 |
+
|
| 191 |
+
|
| 192 |
+
def _english(kind):
|
| 193 |
+
return _ENGLISH.get(kind, f"a {kind} expression")
|
| 194 |
+
|
| 195 |
+
|
| 196 |
+
# ββββββββββββββββββββββββββββββββββββββββββ LAYER 2 β the namespace, and the child program βββββ
|
| 197 |
+
#: The builtins a script may reach, BY NAME. Everything else is a `NameError` in the child.
|
| 198 |
+
#: β THE ABSENCES, again, are the policy: `__import__` `open` `eval` `exec` `compile` `input`
|
| 199 |
+
#: `getattr` `setattr` `delattr` `globals` `locals` `vars` `dir` `type` `super` `object` `help`
|
| 200 |
+
#: `exit` `breakpoint` `memoryview` `id`. Several are harmless on their own; each one is a step
|
| 201 |
+
#: on a published escape, and none has ever been asked for by a script that shapes rows.
|
| 202 |
+
#: β THE EXCEPTION CLASSES ARE HERE BECAUSE `try:` IS, and a `try` block whose `except` clause
|
| 203 |
+
#: cannot name what it catches is a construct that reads as supported and is not. They are safe
|
| 204 |
+
#: for the same reason everything else is: `Exception.__subclasses__` needs an attribute this
|
| 205 |
+
#: sandbox does not allow, so a class object in the namespace is a leaf, not a doorway.
|
| 206 |
+
SANDBOX_BUILTIN_NAMES = (
|
| 207 |
+
"abs all any bool bytes callable chr dict divmod enumerate filter float frozenset hash hex "
|
| 208 |
+
"int isinstance issubclass iter len list map max min next oct ord pow range repr reversed "
|
| 209 |
+
"round set slice sorted str sum tuple zip True False None "
|
| 210 |
+
"Exception ValueError TypeError KeyError IndexError ZeroDivisionError ArithmeticError "
|
| 211 |
+
"AttributeError StopIteration OverflowError"
|
| 212 |
+
).split()
|
| 213 |
+
|
| 214 |
+
#: The literal program the child runs. It is TEXT rather than a module because the child must
|
| 215 |
+
#: import nothing from this repo: a module would be found on `sys.path` and would drag `core`
|
| 216 |
+
#: with it, which is exactly the second store path W1 forbids.
|
| 217 |
+
#: β Every name in here is underscore-prefixed and layer 1 refuses a script from binding one, so
|
| 218 |
+
#: the runner's own machinery cannot be shadowed by the source it executes.
|
| 219 |
+
_RUNNER = r'''
|
| 220 |
+
import json as _json, os as _os, sys as _sys
|
| 221 |
+
|
| 222 |
+
_pay = _json.loads(open(_sys.argv[1], "r", encoding="utf-8").read())
|
| 223 |
+
_out = {"ok": False, "code": "not_run", "message": "the script did not run",
|
| 224 |
+
"stdout": "", "spec": None, "caps": {"wallClock": True, "memory": False, "cpu": False}}
|
| 225 |
+
|
| 226 |
+
# ββ the caps this platform can actually apply, reported either way (standing rule 1) ββββββββββ
|
| 227 |
+
try:
|
| 228 |
+
import resource as _res
|
| 229 |
+
_mem = int(_pay["memoryBytes"])
|
| 230 |
+
_res.setrlimit(_res.RLIMIT_AS, (_mem, _mem))
|
| 231 |
+
_out["caps"]["memory"] = True
|
| 232 |
+
_cpu = int(_pay["cpuSeconds"])
|
| 233 |
+
_res.setrlimit(_res.RLIMIT_CPU, (_cpu, _cpu))
|
| 234 |
+
_out["caps"]["cpu"] = True
|
| 235 |
+
except Exception:
|
| 236 |
+
# `resource` is POSIX only. The wall-clock kill in the parent still applies, and `caps` says
|
| 237 |
+
# which of the three held, never a silent partial.
|
| 238 |
+
pass
|
| 239 |
+
|
| 240 |
+
_printed = []
|
| 241 |
+
_spent = [0]
|
| 242 |
+
_LIMIT = int(_pay["maxStdout"])
|
| 243 |
+
|
| 244 |
+
|
| 245 |
+
def _print(*_a, **_k):
|
| 246 |
+
_text = (_k.get("sep") or " ").join(str(_x) for _x in _a) + (_k.get("end") or "\n")
|
| 247 |
+
_room = _LIMIT - _spent[0]
|
| 248 |
+
if _room > 0:
|
| 249 |
+
_printed.append(_text[:_room])
|
| 250 |
+
_spent[0] += len(_text)
|
| 251 |
+
|
| 252 |
+
|
| 253 |
+
class _Refusal(Exception):
|
| 254 |
+
"""The SANDBOX refusing, as distinct from the SCRIPT failing.
|
| 255 |
+
|
| 256 |
+
Without its own class these arrive as `ValueError`, indistinguishable from a `ValueError` the
|
| 257 |
+
script raised itself, and the answer then says "refused" about an ordinary bug in the tenant's
|
| 258 |
+
own code. Two different facts, two different codes.
|
| 259 |
+
"""
|
| 260 |
+
|
| 261 |
+
|
| 262 |
+
_emitted = []
|
| 263 |
+
|
| 264 |
+
|
| 265 |
+
def _emit(_spec):
|
| 266 |
+
if not isinstance(_spec, dict):
|
| 267 |
+
raise _Refusal("emit() takes a view spec, which is a dictionary")
|
| 268 |
+
if _emitted:
|
| 269 |
+
raise _Refusal("emit() was already called; a script view emits exactly one view")
|
| 270 |
+
_emitted.append(_spec)
|
| 271 |
+
|
| 272 |
+
|
| 273 |
+
_rows = _pay["rows"]
|
| 274 |
+
_fields = _pay["fields"]
|
| 275 |
+
_bound = _pay["table"]
|
| 276 |
+
|
| 277 |
+
|
| 278 |
+
def _scoped_table(_table=None):
|
| 279 |
+
if _table is not None and str(_table) != _bound:
|
| 280 |
+
raise _Refusal(
|
| 281 |
+
"this script view is bound to the database '" + _bound + "' and asked for '"
|
| 282 |
+
+ str(_table) + "'. A script view reads its own database only")
|
| 283 |
+
return [dict(_r) for _r in _rows]
|
| 284 |
+
|
| 285 |
+
|
| 286 |
+
def _scoped_fields():
|
| 287 |
+
return [dict(_f) for _f in _fields]
|
| 288 |
+
|
| 289 |
+
|
| 290 |
+
_ns = {"__builtins__": {_n: __builtins__[_n] if isinstance(__builtins__, dict)
|
| 291 |
+
else getattr(__builtins__, _n)
|
| 292 |
+
for _n in _pay["builtins"]}}
|
| 293 |
+
_ns["__builtins__"]["print"] = _print
|
| 294 |
+
_ns["print"] = _print
|
| 295 |
+
_ns["emit"] = _emit
|
| 296 |
+
_ns["scoped_table"] = _scoped_table
|
| 297 |
+
_ns["scoped_fields"] = _scoped_fields
|
| 298 |
+
_ns["table"] = _bound
|
| 299 |
+
|
| 300 |
+
try:
|
| 301 |
+
exec(compile(_pay["source"], "<script view>", "exec"), _ns)
|
| 302 |
+
if not _emitted:
|
| 303 |
+
_out.update(ok=False, code="no_view",
|
| 304 |
+
message="the script finished without calling emit(spec)")
|
| 305 |
+
else:
|
| 306 |
+
_out.update(ok=True, code="", message="", spec=_emitted[0])
|
| 307 |
+
except _Refusal as _e:
|
| 308 |
+
_out.update(ok=False, code="refused", message=str(_e)[:400])
|
| 309 |
+
except MemoryError:
|
| 310 |
+
_out.update(ok=False, code="memory",
|
| 311 |
+
message="the script used more memory than a script view is allowed")
|
| 312 |
+
except NameError as _e:
|
| 313 |
+
_out.update(ok=False, code="refused_name",
|
| 314 |
+
message=str(_e)[:200] + ". A script view may use only the names the sandbox "
|
| 315 |
+
"provides")
|
| 316 |
+
except BaseException as _e:
|
| 317 |
+
_out.update(ok=False, code="error",
|
| 318 |
+
message=type(_e).__name__ + ": " + str(_e)[:400])
|
| 319 |
+
|
| 320 |
+
_out["stdout"] = "".join(_printed)
|
| 321 |
+
_out["truncated"] = _spent[0] > _LIMIT
|
| 322 |
+
# β THE PROBE: what this child actually had. The PARENT strips it unless it was asked for, so a
|
| 323 |
+
# production run never carries it and a gate can still prove that no `core.*` module and no
|
| 324 |
+
# secret-shaped environment key was ever inside this process.
|
| 325 |
+
# β SNAPSHOTTED AFTER `exec`, and `os` is imported at the TOP so this list does not depend on
|
| 326 |
+
# dict-literal evaluation order. The first draft called `__import__("os")` inside this very
|
| 327 |
+
# expression, so whether `os` appeared depended on which value Python built first: a probe whose
|
| 328 |
+
# contents move with an unrelated edit is a probe a gate cannot assert against.
|
| 329 |
+
_out["probe"] = {"modules": sorted(_sys.modules), "env": sorted(_os.environ)}
|
| 330 |
+
open(_sys.argv[2], "w", encoding="utf-8").write(_json.dumps(_out, default=str))
|
| 331 |
+
'''
|
| 332 |
+
|
| 333 |
+
|
| 334 |
+
def _child_env():
|
| 335 |
+
"""The child's WHOLE environment. An allow-list of two keys, and neither is a credential.
|
| 336 |
+
|
| 337 |
+
β NOT `os.environ.copy()` MINUS SOMETHING. A subtractive environment ships every key nobody
|
| 338 |
+
thought to name: `HF_TOKEN`, `ODOO_PASSWORD`, `ANTHROPIC_API_KEY` and whatever the next
|
| 339 |
+
connector adds. The three names below are here because Python will not start on Windows
|
| 340 |
+
without them; on Linux this returns `{}` and the child runs with no environment at all.
|
| 341 |
+
"""
|
| 342 |
+
env = {}
|
| 343 |
+
for name in ("SystemRoot", "SYSTEMROOT", "WINDIR"):
|
| 344 |
+
if os.environ.get(name):
|
| 345 |
+
env[name] = os.environ[name]
|
| 346 |
+
return env
|
| 347 |
+
|
| 348 |
+
|
| 349 |
+
def run(source, rows, fields, table_key, *, timeout_s=DEFAULT_TIMEOUT_S,
|
| 350 |
+
memory_bytes=DEFAULT_MEMORY_BYTES, cpu_seconds=DEFAULT_CPU_SECONDS, probe=False):
|
| 351 |
+
"""Run ONE script over rows that are ALREADY scoped. Returns C3's envelope plus `caps`.
|
| 352 |
+
|
| 353 |
+
{ok, code, message, spec, stdout, truncated, ms, caps: {wallClock, memory, cpu}}
|
| 354 |
+
|
| 355 |
+
β THIS FUNCTION NEVER TOUCHES A STORE, AND THAT IS THE POINT: it takes rows. `run_view()`
|
| 356 |
+
below is the door that fetches them through C1; keeping the two apart is what lets a gate
|
| 357 |
+
drive the sandbox with no tenant, no runtime and no credential anywhere in the process.
|
| 358 |
+
|
| 359 |
+
β `caps` IS PART OF THE ANSWER, NOT DEBUG OUTPUT. On Windows `resource` does not exist, so
|
| 360 |
+
the memory and CPU limits are NOT applied and this says so. A caller that reports `ok:true`
|
| 361 |
+
without reading `caps` is claiming an enforcement that did not happen (standing rule 1).
|
| 362 |
+
"""
|
| 363 |
+
started = time.monotonic()
|
| 364 |
+
refusal = check_source(source)
|
| 365 |
+
if refusal is not None:
|
| 366 |
+
return _refusal(refusal.code, refusal.message, started)
|
| 367 |
+
|
| 368 |
+
payload = {"source": str(source or ""), "rows": rows, "fields": fields,
|
| 369 |
+
"table": str(table_key or ""), "builtins": SANDBOX_BUILTIN_NAMES,
|
| 370 |
+
"maxStdout": MAX_STDOUT_BYTES, "memoryBytes": int(memory_bytes),
|
| 371 |
+
"cpuSeconds": int(cpu_seconds)}
|
| 372 |
+
try:
|
| 373 |
+
blob = json.dumps(payload, default=str)
|
| 374 |
+
except (TypeError, ValueError) as exc:
|
| 375 |
+
return _refusal("bad_rows", f"these rows cannot be handed to a script ({exc})", started)
|
| 376 |
+
if len(blob.encode("utf-8", "replace")) > MAX_PAYLOAD_BYTES:
|
| 377 |
+
# β REPORTED, NOT TRUNCATED (standing rule 1's second sentence): cause and recommendation,
|
| 378 |
+
# in the words the owner asked for, rather than a quietly short answer.
|
| 379 |
+
return _refusal(
|
| 380 |
+
"payload_too_large",
|
| 381 |
+
f"this database's rows are larger than the {MAX_PAYLOAD_BYTES // (1024 * 1024)} MB a "
|
| 382 |
+
f"script view can be handed at once. Narrow the view with a filter, or raise the "
|
| 383 |
+
f"sandbox payload limit for this deployment", started)
|
| 384 |
+
|
| 385 |
+
with tempfile.TemporaryDirectory(prefix="aios-script-") as work:
|
| 386 |
+
pay_path = Path(work) / "payload.json"
|
| 387 |
+
res_path = Path(work) / "result.json"
|
| 388 |
+
pay_path.write_text(blob, encoding="utf-8")
|
| 389 |
+
# `-I` isolates the interpreter (no PYTHON* env, no user site), `-S` skips site-packages,
|
| 390 |
+
# and the program arrives on STDIN so there is no file for anything to import it as.
|
| 391 |
+
# β `-X utf8` AND AN EXPLICIT `encoding` ARE NOT TIDINESS. Without them this pipe is
|
| 392 |
+
# encoded with the parent's locale codec, which on this Windows box is cp1252: the runner
|
| 393 |
+
# text below cannot be represented in it and `subprocess.run` died with
|
| 394 |
+
# `UnicodeEncodeError` before the child ever started. A sandbox whose behaviour depends on
|
| 395 |
+
# the operator's locale is a sandbox with two behaviours. `-I` implies `-E`, so
|
| 396 |
+
# `PYTHONUTF8` in the environment could not have carried this, it has to be a flag.
|
| 397 |
+
argv = [sys.executable, "-I", "-S", "-X", "utf8", "-", str(pay_path), str(res_path)]
|
| 398 |
+
try:
|
| 399 |
+
done = subprocess.run(
|
| 400 |
+
argv, input=_RUNNER, text=True, encoding="utf-8", errors="replace",
|
| 401 |
+
cwd=work, env=_child_env(),
|
| 402 |
+
stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout_s)
|
| 403 |
+
except subprocess.TimeoutExpired:
|
| 404 |
+
return _refusal("timeout",
|
| 405 |
+
f"the script ran longer than {timeout_s:g} seconds and was stopped",
|
| 406 |
+
started)
|
| 407 |
+
except OSError as exc:
|
| 408 |
+
return _refusal("no_sandbox",
|
| 409 |
+
f"a script view could not be started on this deployment ({exc})",
|
| 410 |
+
started)
|
| 411 |
+
|
| 412 |
+
if not res_path.is_file():
|
| 413 |
+
# The child died without writing an answer: an rlimit signal, an OOM kill, or a crash.
|
| 414 |
+
# β NAMED BY ITS RETURN CODE rather than reported as a generic failure β a memory kill
|
| 415 |
+
# and a bug in this file must not read identically to an operator.
|
| 416 |
+
return _refusal(*_died(done), started)
|
| 417 |
+
try:
|
| 418 |
+
out = json.loads(res_path.read_text(encoding="utf-8"))
|
| 419 |
+
except (OSError, ValueError) as exc:
|
| 420 |
+
return _refusal("unreadable", f"the script's answer could not be read ({exc})",
|
| 421 |
+
started)
|
| 422 |
+
|
| 423 |
+
out["ms"] = int((time.monotonic() - started) * 1000)
|
| 424 |
+
if out.get("ok"):
|
| 425 |
+
spec_error = _check_spec(out.get("spec"))
|
| 426 |
+
if spec_error:
|
| 427 |
+
out.update(ok=False, code="bad_spec", message=spec_error, spec=None)
|
| 428 |
+
if not probe:
|
| 429 |
+
out.pop("probe", None)
|
| 430 |
+
return out
|
| 431 |
+
|
| 432 |
+
|
| 433 |
+
def _died(done):
|
| 434 |
+
"""`(code, message)` for a child that produced no answer."""
|
| 435 |
+
rc = done.returncode
|
| 436 |
+
tail = " ".join((done.stderr or "").split())[-300:]
|
| 437 |
+
if rc in (-9, 137):
|
| 438 |
+
return "memory", "the script was stopped for using too much memory"
|
| 439 |
+
if rc in (-24, 152):
|
| 440 |
+
return "timeout", "the script used more processor time than a script view is allowed"
|
| 441 |
+
return "crashed", f"the script view engine stopped without an answer{': ' + tail if tail else ''}"
|
| 442 |
+
|
| 443 |
+
|
| 444 |
+
def _refusal(code, message, started):
|
| 445 |
+
return {"ok": False, "code": code, "message": message, "spec": None, "stdout": "",
|
| 446 |
+
"truncated": False, "ms": int((time.monotonic() - started) * 1000),
|
| 447 |
+
"caps": {"wallClock": True, "memory": False, "cpu": False}}
|
| 448 |
+
|
| 449 |
+
|
| 450 |
+
def _check_spec(spec):
|
| 451 |
+
"""C3: a spec is a DESCRIPTION the client draws. Never HTML, never a script, never a URL.
|
| 452 |
+
|
| 453 |
+
β THE CHECK IS ON THE KEYS, NOT ON THE STRING CONTENTS. Scanning values for `<script>` is a
|
| 454 |
+
blacklist and would pass `<SCR` + `IPT>`; refusing a spec that carries an `html`, `script`,
|
| 455 |
+
`src` or `onclick` key refuses the SHAPE that would let a renderer be talked into executing
|
| 456 |
+
something. The vocabulary of legal `kind`s is the ROUTE's business (W36-T37) β this is the
|
| 457 |
+
floor every caller gets whether or not the route above it remembers.
|
| 458 |
+
"""
|
| 459 |
+
if not isinstance(spec, dict):
|
| 460 |
+
return "the script emitted something that is not a view spec"
|
| 461 |
+
try:
|
| 462 |
+
blob = json.dumps(spec)
|
| 463 |
+
except (TypeError, ValueError):
|
| 464 |
+
return "the emitted view spec is not something the client can be sent"
|
| 465 |
+
if len(blob.encode("utf-8", "replace")) > MAX_SPEC_BYTES:
|
| 466 |
+
return (f"the emitted view spec is over {MAX_SPEC_BYTES // (1024 * 1024)} MB. A view spec "
|
| 467 |
+
f"describes a picture; it is not where the rows go")
|
| 468 |
+
banned = {"html", "innerhtml", "script", "src", "srcdoc", "href", "style", "onclick", "onload"}
|
| 469 |
+
found = sorted(k for k in _keys_of(spec) if str(k).lower() in banned)
|
| 470 |
+
if found:
|
| 471 |
+
return (f"a view spec may not carry {', '.join(found)}. The client DRAWS a spec, so a "
|
| 472 |
+
f"markup or URL key would be a script by another name")
|
| 473 |
+
return None
|
| 474 |
+
|
| 475 |
+
|
| 476 |
+
def _keys_of(value, depth=0):
|
| 477 |
+
"""Every key anywhere in a nested spec. Bounded, so a deep structure cannot spin this."""
|
| 478 |
+
if depth > 12:
|
| 479 |
+
return
|
| 480 |
+
if isinstance(value, dict):
|
| 481 |
+
for key, sub in value.items():
|
| 482 |
+
yield key
|
| 483 |
+
yield from _keys_of(sub, depth + 1)
|
| 484 |
+
elif isinstance(value, (list, tuple)):
|
| 485 |
+
for sub in value:
|
| 486 |
+
yield from _keys_of(sub, depth + 1)
|
| 487 |
+
|
| 488 |
+
|
| 489 |
+
# ββββββββββββββββββββββββββββββββββββββββββββββ THE DOOR β C1 is the ONLY way to a row βββββββββ
|
| 490 |
+
def run_view(user, table_key, source, st=None, **kw):
|
| 491 |
+
"""Fetch through C1 under `user`'s scope, then run the script over what came back (R5).
|
| 492 |
+
|
| 493 |
+
ββ THE FETCH HAPPENS IN THE PARENT AND ONLY ROWS CROSS INTO THE CHILD. That is wiring W1
|
| 494 |
+
made structural: the child has no runtime to ask, no store handle to open and no credential
|
| 495 |
+
to use, so "a script cannot read what its caller cannot read" is not a rule anybody has to
|
| 496 |
+
keep β there is no second path for it to be broken through.
|
| 497 |
+
|
| 498 |
+
β C1'S THREE EXCEPTIONS ARE ANSWERED, NEVER SWALLOWED. `UnknownTable`, `Denied` and
|
| 499 |
+
`Unresolvable` mean three different things to a person; collapsing them into "no rows" is the
|
| 500 |
+
silent-empty answer C1 was written to make impossible. `Unresolvable.as_limit()` is handed
|
| 501 |
+
through in the words it was raised with β standing rule 1's second sentence, verbatim.
|
| 502 |
+
"""
|
| 503 |
+
import core.perm_scope as perm_scope
|
| 504 |
+
|
| 505 |
+
key = str(table_key or "")
|
| 506 |
+
try:
|
| 507 |
+
rows = perm_scope.scoped_table(user, key, st=st)
|
| 508 |
+
fields = perm_scope.scoped_fields(user, key, st=st)
|
| 509 |
+
except perm_scope.UnknownTable as exc:
|
| 510 |
+
return _refusal("unknown_table", str(exc) or f"there is no database '{key}'",
|
| 511 |
+
time.monotonic())
|
| 512 |
+
except perm_scope.Denied as exc:
|
| 513 |
+
return _refusal("denied", str(exc) or "this account may not read that database",
|
| 514 |
+
time.monotonic())
|
| 515 |
+
except perm_scope.Unresolvable as exc:
|
| 516 |
+
out = _refusal("unresolvable", str(exc), time.monotonic())
|
| 517 |
+
out["limit"] = exc.as_limit()
|
| 518 |
+
return out
|
| 519 |
+
return run(source, rows, fields, key, **kw)
|
platform/core/store.py
CHANGED
|
The diff for this file is too large to render.
See raw diff
|
|
|
platform/harness/meta_store.py
CHANGED
|
@@ -1,521 +1,521 @@
|
|
| 1 |
-
"""meta_store.py β the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
|
| 2 |
-
|
| 3 |
-
python platform/harness/meta_store.py --sync pull into tenant #0's mirror
|
| 4 |
-
python platform/harness/meta_store.py --sync --tenant gtmlab
|
| 5 |
-
python platform/harness/meta_store.py --status what is in the mirror now
|
| 6 |
-
|
| 7 |
-
β WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
|
| 8 |
-
hardwired to XML-RPC β it does `import core.odoo as O` and speaks `search_read` β so no amount of
|
| 9 |
-
spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
|
| 10 |
-
per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
|
| 11 |
-
delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
|
| 12 |
-
store with two loaders, not two stores.**
|
| 13 |
-
|
| 14 |
-
β THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
|
| 15 |
-
the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
|
| 16 |
-
`XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
|
| 17 |
-
`Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
|
| 18 |
-
different first hop.
|
| 19 |
-
|
| 20 |
-
β EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
|
| 21 |
-
carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
|
| 22 |
-
Ad Account 45 Β· Campaign 35 Β· Ad Set 54 Β· Ad 36 Β· Creative 58 Β· Insights 57
|
| 23 |
-
β AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
|
| 24 |
-
came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
|
| 25 |
-
nothing going red β which is exactly the "do not drop any column" instruction, broken silently.
|
| 26 |
-
The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
|
| 27 |
-
|
| 28 |
-
β `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
|
| 29 |
-
answers `403 (#200) Requires business_management permission`, which this token does not carry. One
|
| 30 |
-
column of 285. R6's second sentence β a limit that cannot be removed gets stated with its cause.
|
| 31 |
-
|
| 32 |
-
β IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
|
| 33 |
-
larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
|
| 34 |
-
(W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
|
| 35 |
-
"""
|
| 36 |
-
import argparse
|
| 37 |
-
import json
|
| 38 |
-
import os
|
| 39 |
-
import sys
|
| 40 |
-
import time
|
| 41 |
-
import urllib.error
|
| 42 |
-
import urllib.parse
|
| 43 |
-
import urllib.request
|
| 44 |
-
from pathlib import Path
|
| 45 |
-
|
| 46 |
-
_HERE = Path(__file__).resolve().parent
|
| 47 |
-
if str(_HERE.parent) not in sys.path:
|
| 48 |
-
sys.path.insert(0, str(_HERE.parent))
|
| 49 |
-
|
| 50 |
-
from harness import datastore # noqa: E402
|
| 51 |
-
|
| 52 |
-
GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
|
| 53 |
-
GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
|
| 54 |
-
|
| 55 |
-
#: Numeric columns, by name. Everything else is VARCHAR β including ids (see the header) and
|
| 56 |
-
#: including anything Graph returns as a nested object, which is stored as compact JSON text.
|
| 57 |
-
_INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
|
| 58 |
-
"inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
|
| 59 |
-
"account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
|
| 60 |
-
"min_daily_budget", "min_campaign_group_spend_cap"}
|
| 61 |
-
_DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
|
| 62 |
-
"inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
|
| 63 |
-
"daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
|
| 64 |
-
"daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
|
| 65 |
-
"lifetime_spend_cap", "lifetime_imps"}
|
| 66 |
-
|
| 67 |
-
#: β THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
|
| 68 |
-
#: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
|
| 69 |
-
#: the grid links in `meta_relational`.
|
| 70 |
-
ACCOUNT_FIELDS = (
|
| 71 |
-
"account_id account_status age amount_spent balance business_city business_country_code "
|
| 72 |
-
"business_name business_state business_street business_street2 business_zip capabilities "
|
| 73 |
-
"created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
|
| 74 |
-
"has_migrated_permissions id io_number is_attribution_spec_system_default "
|
| 75 |
-
"is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
|
| 76 |
-
"is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
|
| 77 |
-
"name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
|
| 78 |
-
"timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
|
| 79 |
-
).split()
|
| 80 |
-
|
| 81 |
-
CAMPAIGN_FIELDS = (
|
| 82 |
-
"account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
|
| 83 |
-
"campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
|
| 84 |
-
"created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
|
| 85 |
-
"last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
|
| 86 |
-
"promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
|
| 87 |
-
"special_ad_category special_ad_category_country spend_cap start_time status stop_time "
|
| 88 |
-
"topline_id updated_time"
|
| 89 |
-
).split()
|
| 90 |
-
|
| 91 |
-
ADSET_FIELDS = (
|
| 92 |
-
"account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
|
| 93 |
-
"bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
|
| 94 |
-
"campaign_active_time campaign_attribution campaign_id configured_status created_time "
|
| 95 |
-
"creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
|
| 96 |
-
"effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
|
| 97 |
-
"issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
|
| 98 |
-
"lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
|
| 99 |
-
"optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
|
| 100 |
-
"rf_prediction_id source_adset source_adset_id start_time status targeting "
|
| 101 |
-
"targeting_optimization_types time_based_ad_rotation_id_blocks "
|
| 102 |
-
"time_based_ad_rotation_intervals updated_time use_new_app_click"
|
| 103 |
-
).split()
|
| 104 |
-
|
| 105 |
-
AD_FIELDS = (
|
| 106 |
-
"account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
|
| 107 |
-
"adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
|
| 108 |
-
"conversion_domain created_time creative demolink_hash display_sequence effective_status "
|
| 109 |
-
"engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
|
| 110 |
-
"preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
|
| 111 |
-
"tracking_and_conversion_with_defaults tracking_specs updated_time"
|
| 112 |
-
).split()
|
| 113 |
-
|
| 114 |
-
CREATIVE_FIELDS = (
|
| 115 |
-
"account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
|
| 116 |
-
"branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
|
| 117 |
-
"category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
|
| 118 |
-
"destination_set_id dynamic_ad_voice effective_authorization_category "
|
| 119 |
-
"effective_instagram_media_id effective_object_story_id enable_direct_install "
|
| 120 |
-
"enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
|
| 121 |
-
"instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
|
| 122 |
-
"link_deep_link_url link_destination_display_url link_og_id link_url "
|
| 123 |
-
"messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
|
| 124 |
-
"object_type object_url place_page_set_id platform_customizations playable_asset_id "
|
| 125 |
-
"portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
|
| 126 |
-
"template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
|
| 127 |
-
"use_page_actor_override video_id"
|
| 128 |
-
).split()
|
| 129 |
-
|
| 130 |
-
INSIGHT_FIELDS = (
|
| 131 |
-
"account_currency account_id account_name action_values actions ad_id ad_name adset_id "
|
| 132 |
-
"adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
|
| 133 |
-
"clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
|
| 134 |
-
"cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
|
| 135 |
-
"date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
|
| 136 |
-
"impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
|
| 137 |
-
"optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
|
| 138 |
-
"social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
|
| 139 |
-
"video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
|
| 140 |
-
"video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
|
| 141 |
-
"video_play_actions video_thruplay_watched_actions website_purchase_roas"
|
| 142 |
-
).split()
|
| 143 |
-
|
| 144 |
-
#: table -> (graph edge on the account | None, measured fields, parent column)
|
| 145 |
-
SPECS = {
|
| 146 |
-
"meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
|
| 147 |
-
"meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
|
| 148 |
-
"meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
|
| 149 |
-
"meta_ads": ("ads", AD_FIELDS, "adset_id"),
|
| 150 |
-
"meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
|
| 151 |
-
}
|
| 152 |
-
|
| 153 |
-
#: The daily Insights grain (R2). One row per (ad, day) β the id is synthesised because Insights
|
| 154 |
-
#: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
|
| 155 |
-
INSIGHTS_TABLE = "meta_insights_daily"
|
| 156 |
-
INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
|
| 157 |
-
|
| 158 |
-
#: β INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
|
| 159 |
-
#: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
|
| 160 |
-
#: β Graph's way of saying the synchronous query is too heavy (the async report-run API is the
|
| 161 |
-
#: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
|
| 162 |
-
#: page 25 answer 200. So the window is walked in slices with every column intact:
|
| 163 |
-
#: 57 fields Β· ad level Β· 7d Β· limit 25 -> 200, 25 rows
|
| 164 |
-
#: 57 fields Β· account level Β· 7d -> 200, 7 rows
|
| 165 |
-
#: β Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over β
|
| 166 |
-
#: it drops columns R2 requires, and it does so invisibly.
|
| 167 |
-
INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
|
| 168 |
-
INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
|
| 169 |
-
INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
|
| 170 |
-
|
| 171 |
-
|
| 172 |
-
def _slices(days, size):
|
| 173 |
-
"""[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
|
| 174 |
-
from datetime import date, timedelta
|
| 175 |
-
end = date.today()
|
| 176 |
-
start = end - timedelta(days=max(1, days) - 1)
|
| 177 |
-
out, cur = [], start
|
| 178 |
-
while cur <= end:
|
| 179 |
-
stop = min(cur + timedelta(days=max(1, size) - 1), end)
|
| 180 |
-
out.append((cur.isoformat(), stop.isoformat()))
|
| 181 |
-
cur = stop + timedelta(days=1)
|
| 182 |
-
return out
|
| 183 |
-
|
| 184 |
-
#: β A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
|
| 185 |
-
#: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
|
| 186 |
-
#: not a row cap on a connected source (R6 forbids that) β it is a runaway guard, and reaching it
|
| 187 |
-
#: is reported as a problem, never absorbed.
|
| 188 |
-
MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
|
| 189 |
-
PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
|
| 190 |
-
|
| 191 |
-
|
| 192 |
-
class MetaError(RuntimeError):
|
| 193 |
-
"""A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
|
| 194 |
-
|
| 195 |
-
|
| 196 |
-
def token():
|
| 197 |
-
"""The Meta token from the environment or gitignored `platform/.env`; "" when absent.
|
| 198 |
-
|
| 199 |
-
β Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
|
| 200 |
-
`platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
|
| 201 |
-
(`core` never imports up). Fifteen lines is the price of that boundary.
|
| 202 |
-
"""
|
| 203 |
-
tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
|
| 204 |
-
if tok:
|
| 205 |
-
return tok.strip()
|
| 206 |
-
env = _HERE.parent / ".env"
|
| 207 |
-
if env.exists():
|
| 208 |
-
for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
|
| 209 |
-
if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
|
| 210 |
-
_, _, v = line.partition("=")
|
| 211 |
-
return v.strip().strip('"').strip("'")
|
| 212 |
-
return ""
|
| 213 |
-
|
| 214 |
-
|
| 215 |
-
def _get(path, tok, **params):
|
| 216 |
-
params["access_token"] = tok
|
| 217 |
-
url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
|
| 218 |
-
req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
|
| 219 |
-
try:
|
| 220 |
-
with urllib.request.urlopen(req, timeout=120) as r:
|
| 221 |
-
return json.loads(r.read().decode("utf-8", "replace"))
|
| 222 |
-
except urllib.error.HTTPError as e:
|
| 223 |
-
try:
|
| 224 |
-
msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
|
| 225 |
-
).get("message") or ""
|
| 226 |
-
except Exception:
|
| 227 |
-
msg = ""
|
| 228 |
-
raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
|
| 229 |
-
except Exception as e:
|
| 230 |
-
raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
|
| 231 |
-
|
| 232 |
-
|
| 233 |
-
#: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
|
| 234 |
-
#: why it cannot be treated as "the server is broken, give up".
|
| 235 |
-
_TOO_MUCH = "reduce the amount of data"
|
| 236 |
-
|
| 237 |
-
#: β THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
|
| 238 |
-
#: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
|
| 239 |
-
#: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" β the
|
| 240 |
-
#: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
|
| 241 |
-
#: β It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
|
| 242 |
-
#: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
|
| 243 |
-
#: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
|
| 244 |
-
_RATE_LIMITED = "too many calls"
|
| 245 |
-
_RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
|
| 246 |
-
_RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
|
| 247 |
-
|
| 248 |
-
|
| 249 |
-
def _walk(path, tok, log, **params):
|
| 250 |
-
"""Every page of an edge, paged by CURSOR under our own parameters.
|
| 251 |
-
|
| 252 |
-
β IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
|
| 253 |
-
first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
|
| 254 |
-
you're asking for"**, the retry at limit=25 succeeds β and then `next` carries the ORIGINAL
|
| 255 |
-
limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
|
| 256 |
-
Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
|
| 257 |
-
|
| 258 |
-
β It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
|
| 259 |
-
silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
|
| 260 |
-
every column per row.
|
| 261 |
-
|
| 262 |
-
-> (rows, hit_page_cap)
|
| 263 |
-
"""
|
| 264 |
-
out, pages = [], 0
|
| 265 |
-
limit = int(params.pop("limit", None) or PAGE)
|
| 266 |
-
after, waited = None, 0
|
| 267 |
-
while True:
|
| 268 |
-
call = dict(params, limit=limit)
|
| 269 |
-
if after:
|
| 270 |
-
call["after"] = after
|
| 271 |
-
try:
|
| 272 |
-
body = _get(path, tok, **call)
|
| 273 |
-
except MetaError as e:
|
| 274 |
-
if _TOO_MUCH in str(e) and limit > 5:
|
| 275 |
-
limit = max(5, limit // 4)
|
| 276 |
-
log(f" page too heavy for /{path} - retrying at limit={limit} "
|
| 277 |
-
f"(a payload ceiling, not a row cap; every column is still asked for)")
|
| 278 |
-
continue
|
| 279 |
-
if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
|
| 280 |
-
waited += 1
|
| 281 |
-
log(f" rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
|
| 282 |
-
f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
|
| 283 |
-
time.sleep(_RATE_WAIT)
|
| 284 |
-
continue
|
| 285 |
-
if _RATE_LIMITED in str(e).lower():
|
| 286 |
-
log(f" !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
|
| 287 |
-
f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
|
| 288 |
-
f"limit is per ad account and persists for minutes. Fix: re-run "
|
| 289 |
-
f"`--sync --only <table>` later; the upsert is idempotent.")
|
| 290 |
-
return out, True
|
| 291 |
-
raise
|
| 292 |
-
out.extend(body.get("data") or [])
|
| 293 |
-
pages += 1
|
| 294 |
-
after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
|
| 295 |
-
has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
|
| 296 |
-
if not has_next:
|
| 297 |
-
return out, False
|
| 298 |
-
if pages >= MAX_PAGES:
|
| 299 |
-
log(f" !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
|
| 300 |
-
f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
|
| 301 |
-
f"window with META_INSIGHTS_DAYS.")
|
| 302 |
-
return out, True
|
| 303 |
-
|
| 304 |
-
|
| 305 |
-
def _cell(value):
|
| 306 |
-
"""One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
|
| 307 |
-
being dropped: R2 says every field the API returns, and `targeting` is a field."""
|
| 308 |
-
if value is None or isinstance(value, (str, int, float, bool)):
|
| 309 |
-
return value
|
| 310 |
-
return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
|
| 311 |
-
|
| 312 |
-
|
| 313 |
-
def _coltype(name, rows=None):
|
| 314 |
-
"""The DuckDB type for one column β decided by the DATA when there is data, by the name only
|
| 315 |
-
as a fallback.
|
| 316 |
-
|
| 317 |
-
β THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
|
| 318 |
-
`cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
|
| 319 |
-
action-type objects** on the Insights edge:
|
| 320 |
-
[{"action_type":"outbound_click","value":"1.459854"}]
|
| 321 |
-
Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
|
| 322 |
-
'[{...}]' to DOUBLE` β after five entity tables had already been written, so the sync looked
|
| 323 |
-
like it worked and then blew up on the last table.
|
| 324 |
-
β Same principle the field CATALOG is built on, applied one layer down: **ask the response,
|
| 325 |
-
do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
|
| 326 |
-
that is what `_cell` stores; anything else falls back to the measured name hints.
|
| 327 |
-
"""
|
| 328 |
-
if rows:
|
| 329 |
-
seen, kinds = 0, set()
|
| 330 |
-
for r in rows:
|
| 331 |
-
v = r.get(name)
|
| 332 |
-
if v is None or v == "":
|
| 333 |
-
continue
|
| 334 |
-
kinds.add("json" if isinstance(v, (list, dict)) else
|
| 335 |
-
"bool" if isinstance(v, bool) else
|
| 336 |
-
"int" if isinstance(v, int) else
|
| 337 |
-
"float" if isinstance(v, float) else "str")
|
| 338 |
-
seen += 1
|
| 339 |
-
if seen >= 200:
|
| 340 |
-
break
|
| 341 |
-
if kinds:
|
| 342 |
-
if "json" in kinds or "str" in kinds:
|
| 343 |
-
return "VARCHAR" # a JSON blob, or a numeric STRING
|
| 344 |
-
if kinds <= {"int", "bool"}:
|
| 345 |
-
return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
|
| 346 |
-
return "DOUBLE"
|
| 347 |
-
if name in _INT:
|
| 348 |
-
return "BIGINT"
|
| 349 |
-
if name in _DBL:
|
| 350 |
-
return "DOUBLE"
|
| 351 |
-
return "VARCHAR" # ids included β see the header
|
| 352 |
-
|
| 353 |
-
|
| 354 |
-
def _ensure(con, table, fields, rows=None):
|
| 355 |
-
"""Create or widen the table, with every column typed from `rows` when they are available.
|
| 356 |
-
|
| 357 |
-
β AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
|
| 358 |
-
column in place, and this table is DERIVED data that can be re-pulled in minutes β so a type
|
| 359 |
-
disagreement drops and recreates rather than limping on with a column that refuses every
|
| 360 |
-
insert. The alternative is a mirror that is permanently unwritable for one bad guess.
|
| 361 |
-
"""
|
| 362 |
-
want = {f: _coltype(f, rows) for f in fields}
|
| 363 |
-
have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
|
| 364 |
-
if have:
|
| 365 |
-
clash = [f for f, ty in want.items() if f in have and have[f] != ty
|
| 366 |
-
and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
|
| 367 |
-
if clash:
|
| 368 |
-
con.execute(f"DROP TABLE {table}")
|
| 369 |
-
have = {}
|
| 370 |
-
if not have:
|
| 371 |
-
cols = ", ".join(f"{f} {want[f]}" for f in fields)
|
| 372 |
-
con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
|
| 373 |
-
if "id" not in fields else
|
| 374 |
-
f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
|
| 375 |
-
return
|
| 376 |
-
for f in fields:
|
| 377 |
-
if f not in have:
|
| 378 |
-
con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
|
| 379 |
-
|
| 380 |
-
|
| 381 |
-
def _upsert(con, table, fields, rows):
|
| 382 |
-
"""Delete-then-insert by id β the same idempotence `datastore._upsert` gives the Odoo half, so
|
| 383 |
-
a re-sync updates in place and can never append a second copy of the same object."""
|
| 384 |
-
if not rows:
|
| 385 |
-
return 0
|
| 386 |
-
cols = list(fields)
|
| 387 |
-
ids = [str(r.get("id") or "") for r in rows]
|
| 388 |
-
q = ",".join("?" for _ in ids)
|
| 389 |
-
con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
|
| 390 |
-
con.executemany(
|
| 391 |
-
f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
|
| 392 |
-
[[_cell(r.get(c)) for c in cols] for r in rows])
|
| 393 |
-
return len(rows)
|
| 394 |
-
|
| 395 |
-
|
| 396 |
-
def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
|
| 397 |
-
"""Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
|
| 398 |
-
|
| 399 |
-
Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
|
| 400 |
-
exactly as `odoo_relational.refresh` is.
|
| 401 |
-
"""
|
| 402 |
-
tok = tok or token()
|
| 403 |
-
# β THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME β and the difference cost a
|
| 404 |
-
# live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
|
| 405 |
-
# `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
|
| 406 |
-
# imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
|
| 407 |
-
# that trips the per-ad-account rate limit and never finishes. The comment beside that call
|
| 408 |
-
# claimed a short window the code could not deliver.
|
| 409 |
-
# β The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
|
| 410 |
-
# makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
|
| 411 |
-
days = int(insights_days or INSIGHTS_DAYS)
|
| 412 |
-
report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
|
| 413 |
-
if not tok:
|
| 414 |
-
report["problems"].append(
|
| 415 |
-
"META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
|
| 416 |
-
"was pulled. This is a missing CREDENTIAL, not a missing capability.")
|
| 417 |
-
return report
|
| 418 |
-
|
| 419 |
-
path = datastore.path_for(tenant_key)
|
| 420 |
-
if Path(datastore.DB_PATH) != Path(path):
|
| 421 |
-
datastore.use_path(path)
|
| 422 |
-
con = datastore.connect()
|
| 423 |
-
log(f" mirror: {Path(path).name}")
|
| 424 |
-
|
| 425 |
-
accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
|
| 426 |
-
report["accounts"] = [a.get("id") for a in accts]
|
| 427 |
-
if not accts:
|
| 428 |
-
report["problems"].append("the token reaches no ad accounts")
|
| 429 |
-
return report
|
| 430 |
-
|
| 431 |
-
# ββ the five entity levels ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 432 |
-
for table, (edge, fields, _parent) in SPECS.items():
|
| 433 |
-
rows, capped = [], False
|
| 434 |
-
for acct in accts:
|
| 435 |
-
aid = acct["id"]
|
| 436 |
-
if edge is None:
|
| 437 |
-
rows.append(_get(aid, tok, fields=",".join(fields)))
|
| 438 |
-
else:
|
| 439 |
-
got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
|
| 440 |
-
rows.extend(got)
|
| 441 |
-
capped = capped or hit
|
| 442 |
-
_ensure(con, table, fields, rows)
|
| 443 |
-
n = _upsert(con, table, fields, rows)
|
| 444 |
-
total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
|
| 445 |
-
report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
|
| 446 |
-
log(f" {table:<20} pulled {n:>6} mirror total {total:>6}"
|
| 447 |
-
+ (" !! PAGE CAP HIT" if capped else ""))
|
| 448 |
-
if capped:
|
| 449 |
-
report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
|
| 450 |
-
|
| 451 |
-
# ββ the daily Insights grain ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 452 |
-
if insights:
|
| 453 |
-
rows, capped = [], False
|
| 454 |
-
for acct in accts:
|
| 455 |
-
for since, until in _slices(days, INSIGHTS_SLICE):
|
| 456 |
-
got, hit = _walk(f"{acct['id']}/insights", tok, log,
|
| 457 |
-
fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
|
| 458 |
-
time_increment="1", limit=INSIGHTS_PAGE,
|
| 459 |
-
time_range=json.dumps({"since": since, "until": until}))
|
| 460 |
-
rows.extend(got)
|
| 461 |
-
capped = capped or hit
|
| 462 |
-
# β Insights rows carry no id. The key must be STABLE across runs or every re-sync
|
| 463 |
-
# appends a second copy of the same day β so it is composed from the grain itself.
|
| 464 |
-
for r in rows:
|
| 465 |
-
r["id"] = ":".join(str(r.get(k) or "") for k in
|
| 466 |
-
(f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
|
| 467 |
-
fields = ["id"] + INSIGHT_FIELDS
|
| 468 |
-
_ensure(con, INSIGHTS_TABLE, fields, rows)
|
| 469 |
-
n = _upsert(con, INSIGHTS_TABLE, fields, rows)
|
| 470 |
-
total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
|
| 471 |
-
report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
|
| 472 |
-
log(f" {INSIGHTS_TABLE:<20} pulled {n:>6} mirror total {total:>6}"
|
| 473 |
-
+ (" !! PAGE CAP HIT" if capped else ""))
|
| 474 |
-
|
| 475 |
-
con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
|
| 476 |
-
["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
|
| 477 |
-
sum(t["in_mirror"] for t in report["tables"].values()),
|
| 478 |
-
time.strftime("%Y-%m-%d %H:%M:%S")])
|
| 479 |
-
return report
|
| 480 |
-
|
| 481 |
-
|
| 482 |
-
def status(tenant_key="royal-imports"):
|
| 483 |
-
"""What is in the mirror right now, per table. Never fetches."""
|
| 484 |
-
path = datastore.path_for(tenant_key)
|
| 485 |
-
if Path(datastore.DB_PATH) != Path(path):
|
| 486 |
-
datastore.use_path(path)
|
| 487 |
-
out = {}
|
| 488 |
-
con = datastore.connect()
|
| 489 |
-
for table in list(SPECS) + [INSIGHTS_TABLE]:
|
| 490 |
-
try:
|
| 491 |
-
out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
|
| 492 |
-
except Exception:
|
| 493 |
-
out[table] = None # table absent = never synced
|
| 494 |
-
return out
|
| 495 |
-
|
| 496 |
-
|
| 497 |
-
def main(argv=None):
|
| 498 |
-
ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
|
| 499 |
-
ap.add_argument("--sync", action="store_true")
|
| 500 |
-
ap.add_argument("--status", action="store_true")
|
| 501 |
-
ap.add_argument("--tenant", default="royal-imports")
|
| 502 |
-
ap.add_argument("--no-insights", action="store_true")
|
| 503 |
-
ap.add_argument("--insights-days", type=int, default=None,
|
| 504 |
-
help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
|
| 505 |
-
a = ap.parse_args(argv)
|
| 506 |
-
if a.status:
|
| 507 |
-
for k, v in status(a.tenant).items():
|
| 508 |
-
print(f" {k:<20} {'(never synced)' if v is None else v}")
|
| 509 |
-
return 0
|
| 510 |
-
if not a.sync:
|
| 511 |
-
ap.print_help()
|
| 512 |
-
return 2
|
| 513 |
-
rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
|
| 514 |
-
for p in rep["problems"]:
|
| 515 |
-
print(" PROBLEM:", p)
|
| 516 |
-
print(f" accounts: {len(rep['accounts'])} tables: {len(rep['tables'])}")
|
| 517 |
-
return 1 if rep["problems"] else 0
|
| 518 |
-
|
| 519 |
-
|
| 520 |
-
if __name__ == "__main__":
|
| 521 |
-
sys.exit(main())
|
|
|
|
| 1 |
+
"""meta_store.py β the REST loader for a mirror whose only other loader is XML-RPC (W31-T48).
|
| 2 |
+
|
| 3 |
+
python platform/harness/meta_store.py --sync pull into tenant #0's mirror
|
| 4 |
+
python platform/harness/meta_store.py --sync --tenant gtmlab
|
| 5 |
+
python platform/harness/meta_store.py --status what is in the mirror now
|
| 6 |
+
|
| 7 |
+
β WHY THIS IS A SIBLING AND NOT A ROW IN `datastore.ENTITIES`. `datastore.sync_entity` is
|
| 8 |
+
hardwired to XML-RPC β it does `import core.odoo as O` and speaks `search_read` β so no amount of
|
| 9 |
+
spec data makes it fetch over HTTPS. What IS reusable is everything *below* the fetch: the
|
| 10 |
+
per-tenant file (`path_for`), the process-singleton connection (`connect`), and the
|
| 11 |
+
delete-then-insert upsert. This module borrows those and brings its own reader. **The mirror is one
|
| 12 |
+
store with two loaders, not two stores.**
|
| 13 |
+
|
| 14 |
+
β THE SHAPE OF THE WHOLE THING, because it is the owner's actual request: *"we just need to pull
|
| 15 |
+
the data into our template database for Meta"*, working *"just like Odoo"*. Odoo's path is
|
| 16 |
+
`XML-RPC -> DuckDB mirror -> odoo_relational -> ut_odoo_* locked grids`. Meta's is
|
| 17 |
+
`Graph -> DuckDB mirror -> meta_relational -> ut_meta_* locked grids`. Same middle, same end, one
|
| 18 |
+
different first hop.
|
| 19 |
+
|
| 20 |
+
β EVERY COLUMN NAME BELOW WAS MEASURED, NOT READ OFF A DOC (R8). `proto/meta-entity-fields.json`
|
| 21 |
+
carries the run: each level's list is what the API ACCEPTED when asked, on a real ad account.
|
| 22 |
+
Ad Account 45 Β· Campaign 35 Β· Ad Set 54 Β· Ad 36 Β· Creative 58 Β· Insights 57
|
| 23 |
+
β AND `ACCEPTED` IS NOT `RETURNED`. Graph omits null fields from a response, so a 20-field ask
|
| 24 |
+
came back with 14 keys. Building a schema from what came back would drop ~30% of the columns with
|
| 25 |
+
nothing going red β which is exactly the "do not drop any column" instruction, broken silently.
|
| 26 |
+
The lists below are therefore the ASKED-AND-ACCEPTED set, and a column with no value is NULL.
|
| 27 |
+
|
| 28 |
+
β `owner` IS ABSENT FROM THE AD ACCOUNT LIST AND THAT IS A REPORTED LIMIT, NOT AN OMISSION: it
|
| 29 |
+
answers `403 (#200) Requires business_management permission`, which this token does not carry. One
|
| 30 |
+
column of 285. R6's second sentence β a limit that cannot be removed gets stated with its cause.
|
| 31 |
+
|
| 32 |
+
β IDS ARE TEXT, ALWAYS. A Meta object id is a 17-digit decimal string; `120273975028650555` is
|
| 33 |
+
larger than 2^53, so any float or JS-number path silently corrupts it. Same ruling as `ig_id`
|
| 34 |
+
(W26/R3), for the same reason, and it is why every `id` column here is VARCHAR.
|
| 35 |
+
"""
|
| 36 |
+
import argparse
|
| 37 |
+
import json
|
| 38 |
+
import os
|
| 39 |
+
import sys
|
| 40 |
+
import time
|
| 41 |
+
import urllib.error
|
| 42 |
+
import urllib.parse
|
| 43 |
+
import urllib.request
|
| 44 |
+
from pathlib import Path
|
| 45 |
+
|
| 46 |
+
_HERE = Path(__file__).resolve().parent
|
| 47 |
+
if str(_HERE.parent) not in sys.path:
|
| 48 |
+
sys.path.insert(0, str(_HERE.parent))
|
| 49 |
+
|
| 50 |
+
from harness import datastore # noqa: E402
|
| 51 |
+
|
| 52 |
+
GRAPH_VERSION = os.environ.get("META_GRAPH_VERSION") or "v21.0"
|
| 53 |
+
GRAPH = f"https://graph.facebook.com/{GRAPH_VERSION}"
|
| 54 |
+
|
| 55 |
+
#: Numeric columns, by name. Everything else is VARCHAR β including ids (see the header) and
|
| 56 |
+
#: including anything Graph returns as a nested object, which is stored as compact JSON text.
|
| 57 |
+
_INT = {"impressions", "reach", "clicks", "unique_clicks", "inline_link_clicks",
|
| 58 |
+
"inline_post_engagement", "full_view_impressions", "estimated_ad_recallers",
|
| 59 |
+
"account_status", "age", "timezone_id", "timezone_offset_hours_utc", "io_number",
|
| 60 |
+
"min_daily_budget", "min_campaign_group_spend_cap"}
|
| 61 |
+
_DBL = {"spend", "social_spend", "ctr", "unique_ctr", "cpc", "cpm", "cpp", "frequency",
|
| 62 |
+
"inline_link_click_ctr", "outbound_clicks_ctr", "amount_spent", "balance", "spend_cap",
|
| 63 |
+
"daily_budget", "lifetime_budget", "budget_remaining", "bid_amount", "canvas_avg_view_time",
|
| 64 |
+
"daily_min_spend_target", "daily_spend_cap", "lifetime_min_spend_target",
|
| 65 |
+
"lifetime_spend_cap", "lifetime_imps"}
|
| 66 |
+
|
| 67 |
+
#: β THE MEASURED CATALOG. `edge` is the connection on the ad account; `None` means the account
|
| 68 |
+
#: itself. `parent` names the column that ties a row to its parent, used by nothing here and by
|
| 69 |
+
#: the grid links in `meta_relational`.
|
| 70 |
+
ACCOUNT_FIELDS = (
|
| 71 |
+
"account_id account_status age amount_spent balance business_city business_country_code "
|
| 72 |
+
"business_name business_state business_street business_street2 business_zip capabilities "
|
| 73 |
+
"created_time currency disable_reason end_advertiser end_advertiser_name funding_source "
|
| 74 |
+
"has_migrated_permissions id io_number is_attribution_spec_system_default "
|
| 75 |
+
"is_direct_deals_enabled is_notifications_enabled is_personal is_prepay_account "
|
| 76 |
+
"is_tax_id_required line_numbers media_agency min_campaign_group_spend_cap min_daily_budget "
|
| 77 |
+
"name offsite_pixels_tos_accepted partner spend_cap tax_id tax_id_status tax_id_type "
|
| 78 |
+
"timezone_id timezone_name timezone_offset_hours_utc tos_accepted user_tasks user_tos_accepted"
|
| 79 |
+
).split()
|
| 80 |
+
|
| 81 |
+
CAMPAIGN_FIELDS = (
|
| 82 |
+
"account_id bid_strategy boosted_object_id budget_rebalance_flag budget_remaining buying_type "
|
| 83 |
+
"campaign_group_active_time can_create_brand_lift_study can_use_spend_cap configured_status "
|
| 84 |
+
"created_time daily_budget effective_status id is_skadnetwork_attribution issues_info "
|
| 85 |
+
"last_budget_toggling_time lifetime_budget name objective pacing_type primary_attribution "
|
| 86 |
+
"promoted_object smart_promotion_type source_campaign source_campaign_id special_ad_categories "
|
| 87 |
+
"special_ad_category special_ad_category_country spend_cap start_time status stop_time "
|
| 88 |
+
"topline_id updated_time"
|
| 89 |
+
).split()
|
| 90 |
+
|
| 91 |
+
ADSET_FIELDS = (
|
| 92 |
+
"account_id adlabels adset_schedule asset_feed_id attribution_spec bid_adjustments bid_amount "
|
| 93 |
+
"bid_constraints bid_info bid_strategy billing_event budget_remaining campaign "
|
| 94 |
+
"campaign_active_time campaign_attribution campaign_id configured_status created_time "
|
| 95 |
+
"creative_sequence daily_budget daily_min_spend_target daily_spend_cap destination_type "
|
| 96 |
+
"effective_status end_time frequency_control_specs id instagram_actor_id is_dynamic_creative "
|
| 97 |
+
"issues_info learning_stage_info lifetime_budget lifetime_imps lifetime_min_spend_target "
|
| 98 |
+
"lifetime_spend_cap multi_optimization_goal_weight name optimization_goal "
|
| 99 |
+
"optimization_sub_event pacing_type promoted_object recurring_budget_semantics review_feedback "
|
| 100 |
+
"rf_prediction_id source_adset source_adset_id start_time status targeting "
|
| 101 |
+
"targeting_optimization_types time_based_ad_rotation_id_blocks "
|
| 102 |
+
"time_based_ad_rotation_intervals updated_time use_new_app_click"
|
| 103 |
+
).split()
|
| 104 |
+
|
| 105 |
+
AD_FIELDS = (
|
| 106 |
+
"account_id ad_active_time ad_review_feedback ad_schedule_end_time ad_schedule_start_time "
|
| 107 |
+
"adlabels adset adset_id bid_amount bid_info bid_type campaign campaign_id configured_status "
|
| 108 |
+
"conversion_domain created_time creative demolink_hash display_sequence effective_status "
|
| 109 |
+
"engagement_audience failed_delivery_checks id issues_info last_updated_by_app_id name "
|
| 110 |
+
"preview_shareable_link priority recommendations source_ad source_ad_id status targeting "
|
| 111 |
+
"tracking_and_conversion_with_defaults tracking_specs updated_time"
|
| 112 |
+
).split()
|
| 113 |
+
|
| 114 |
+
CREATIVE_FIELDS = (
|
| 115 |
+
"account_id actor_id adlabels applink_treatment asset_feed_spec authorization_category body "
|
| 116 |
+
"branded_content_sponsor_page_id bundle_folder_id call_to_action_type categorization_criteria "
|
| 117 |
+
"category_media_source collaborative_ads_lsb_image_bank_id degrees_of_freedom_spec "
|
| 118 |
+
"destination_set_id dynamic_ad_voice effective_authorization_category "
|
| 119 |
+
"effective_instagram_media_id effective_object_story_id enable_direct_install "
|
| 120 |
+
"enable_launch_instant_app id image_crops image_hash image_url instagram_actor_id "
|
| 121 |
+
"instagram_permalink_url instagram_story_id instagram_user_id interactive_components_spec "
|
| 122 |
+
"link_deep_link_url link_destination_display_url link_og_id link_url "
|
| 123 |
+
"messenger_sponsored_message name object_id object_store_url object_story_id object_story_spec "
|
| 124 |
+
"object_type object_url place_page_set_id platform_customizations playable_asset_id "
|
| 125 |
+
"portrait_customizations product_set_id recommender_settings source_instagram_media_id status "
|
| 126 |
+
"template_url template_url_spec thumbnail_id thumbnail_url title url_tags "
|
| 127 |
+
"use_page_actor_override video_id"
|
| 128 |
+
).split()
|
| 129 |
+
|
| 130 |
+
INSIGHT_FIELDS = (
|
| 131 |
+
"account_currency account_id account_name action_values actions ad_id ad_name adset_id "
|
| 132 |
+
"adset_name attribution_setting buying_type campaign_id campaign_name canvas_avg_view_time "
|
| 133 |
+
"clicks conversion_rate_ranking conversion_values conversions cost_per_action_type "
|
| 134 |
+
"cost_per_inline_link_click cost_per_thruplay cost_per_unique_click cpc cpm cpp ctr date_start "
|
| 135 |
+
"date_stop engagement_rate_ranking estimated_ad_recallers frequency full_view_impressions "
|
| 136 |
+
"impressions inline_link_click_ctr inline_link_clicks inline_post_engagement objective "
|
| 137 |
+
"optimization_goal outbound_clicks outbound_clicks_ctr purchase_roas quality_ranking reach "
|
| 138 |
+
"social_spend spend unique_clicks unique_ctr unique_outbound_clicks "
|
| 139 |
+
"video_avg_time_watched_actions video_p100_watched_actions video_p25_watched_actions "
|
| 140 |
+
"video_p50_watched_actions video_p75_watched_actions video_p95_watched_actions "
|
| 141 |
+
"video_play_actions video_thruplay_watched_actions website_purchase_roas"
|
| 142 |
+
).split()
|
| 143 |
+
|
| 144 |
+
#: table -> (graph edge on the account | None, measured fields, parent column)
|
| 145 |
+
SPECS = {
|
| 146 |
+
"meta_ad_accounts": (None, ACCOUNT_FIELDS, None),
|
| 147 |
+
"meta_campaigns": ("campaigns", CAMPAIGN_FIELDS, "account_id"),
|
| 148 |
+
"meta_adsets": ("adsets", ADSET_FIELDS, "campaign_id"),
|
| 149 |
+
"meta_ads": ("ads", AD_FIELDS, "adset_id"),
|
| 150 |
+
"meta_creatives": ("adcreatives", CREATIVE_FIELDS, "account_id"),
|
| 151 |
+
}
|
| 152 |
+
|
| 153 |
+
#: The daily Insights grain (R2). One row per (ad, day) β the id is synthesised because Insights
|
| 154 |
+
#: has no id of its own, and it must be STABLE so a re-run updates instead of appending.
|
| 155 |
+
INSIGHTS_TABLE = "meta_insights_daily"
|
| 156 |
+
INSIGHTS_LEVEL = os.environ.get("META_INSIGHTS_LEVEL") or "ad"
|
| 157 |
+
|
| 158 |
+
#: β INSIGHTS IS FETCHED IN TIME SLICES, AND THE REASON IS MEASURED, NOT DEFENSIVE. All 57 fields
|
| 159 |
+
#: at ad level over `last_90d` with a 100-row page answers **HTTP 500 "An unknown error occurred"**
|
| 160 |
+
#: β Graph's way of saying the synchronous query is too heavy (the async report-run API is the
|
| 161 |
+
#: other answer, and it costs a poll loop this does not need). The SAME 57 fields over 7 days at
|
| 162 |
+
#: page 25 answer 200. So the window is walked in slices with every column intact:
|
| 163 |
+
#: 57 fields Β· ad level Β· 7d Β· limit 25 -> 200, 25 rows
|
| 164 |
+
#: 57 fields Β· account level Β· 7d -> 200, 7 rows
|
| 165 |
+
#: β Narrowing the FIELD list would also have "fixed" it, and that is the wrong fix twice over β
|
| 166 |
+
#: it drops columns R2 requires, and it does so invisibly.
|
| 167 |
+
INSIGHTS_DAYS = int(os.environ.get("META_INSIGHTS_DAYS") or 90)
|
| 168 |
+
INSIGHTS_SLICE = int(os.environ.get("META_INSIGHTS_SLICE_DAYS") or 7)
|
| 169 |
+
INSIGHTS_PAGE = int(os.environ.get("META_INSIGHTS_PAGE") or 25)
|
| 170 |
+
|
| 171 |
+
|
| 172 |
+
def _slices(days, size):
|
| 173 |
+
"""[(since, until)] covering the last `days`, oldest first, in `size`-day windows."""
|
| 174 |
+
from datetime import date, timedelta
|
| 175 |
+
end = date.today()
|
| 176 |
+
start = end - timedelta(days=max(1, days) - 1)
|
| 177 |
+
out, cur = [], start
|
| 178 |
+
while cur <= end:
|
| 179 |
+
stop = min(cur + timedelta(days=max(1, size) - 1), end)
|
| 180 |
+
out.append((cur.isoformat(), stop.isoformat()))
|
| 181 |
+
cur = stop + timedelta(days=1)
|
| 182 |
+
return out
|
| 183 |
+
|
| 184 |
+
#: β A REAL CEILING, AND R6's SECOND SENTENCE APPLIES TO IT. Graph pages at 25-100 rows; this is
|
| 185 |
+
#: the number of PAGES a single edge may walk before the loader stops and SAYS it stopped. It is
|
| 186 |
+
#: not a row cap on a connected source (R6 forbids that) β it is a runaway guard, and reaching it
|
| 187 |
+
#: is reported as a problem, never absorbed.
|
| 188 |
+
MAX_PAGES = int(os.environ.get("META_MAX_PAGES") or 200)
|
| 189 |
+
PAGE = int(os.environ.get("META_PAGE_SIZE") or 100)
|
| 190 |
+
|
| 191 |
+
|
| 192 |
+
class MetaError(RuntimeError):
|
| 193 |
+
"""A Graph refusal carrying Meta's own words. Safe to print: no token ever reaches it."""
|
| 194 |
+
|
| 195 |
+
|
| 196 |
+
def token():
|
| 197 |
+
"""The Meta token from the environment or gitignored `platform/.env`; "" when absent.
|
| 198 |
+
|
| 199 |
+
β Same resolver `aios-web/api/connectors_meta.py` uses. Duplicated deliberately and minimally:
|
| 200 |
+
`platform/` must not import from `aios-web/api/`, which is the layering rule this repo keeps
|
| 201 |
+
(`core` never imports up). Fifteen lines is the price of that boundary.
|
| 202 |
+
"""
|
| 203 |
+
tok = os.environ.get("META_ADS_ACCESS_TOKEN") or ""
|
| 204 |
+
if tok:
|
| 205 |
+
return tok.strip()
|
| 206 |
+
env = _HERE.parent / ".env"
|
| 207 |
+
if env.exists():
|
| 208 |
+
for line in env.read_text(encoding="utf-8", errors="replace").splitlines():
|
| 209 |
+
if line.strip().startswith("META_ADS_ACCESS_TOKEN"):
|
| 210 |
+
_, _, v = line.partition("=")
|
| 211 |
+
return v.strip().strip('"').strip("'")
|
| 212 |
+
return ""
|
| 213 |
+
|
| 214 |
+
|
| 215 |
+
def _get(path, tok, **params):
|
| 216 |
+
params["access_token"] = tok
|
| 217 |
+
url = f"{GRAPH}/{path.lstrip('/')}?" + urllib.parse.urlencode(params)
|
| 218 |
+
req = urllib.request.Request(url, headers={"User-Agent": "aios-meta-store/1"})
|
| 219 |
+
try:
|
| 220 |
+
with urllib.request.urlopen(req, timeout=120) as r:
|
| 221 |
+
return json.loads(r.read().decode("utf-8", "replace"))
|
| 222 |
+
except urllib.error.HTTPError as e:
|
| 223 |
+
try:
|
| 224 |
+
msg = (json.loads(e.read().decode("utf-8", "replace")).get("error") or {}
|
| 225 |
+
).get("message") or ""
|
| 226 |
+
except Exception:
|
| 227 |
+
msg = ""
|
| 228 |
+
raise MetaError(f"HTTP {e.code} on /{path.lstrip('/')}: {msg[:200]}") from None
|
| 229 |
+
except Exception as e:
|
| 230 |
+
raise MetaError(f"{type(e).__name__} on /{path.lstrip('/')}") from None
|
| 231 |
+
|
| 232 |
+
|
| 233 |
+
#: Graph's own words when a page is too heavy. It arrives as an HTTP **500**, not a 4xx, which is
|
| 234 |
+
#: why it cannot be treated as "the server is broken, give up".
|
| 235 |
+
_TOO_MUCH = "reduce the amount of data"
|
| 236 |
+
|
| 237 |
+
#: β THE ADS-MANAGEMENT RATE LIMIT, WHICH IS PER AD ACCOUNT AND NOT PER TOKEN. Measured: after a
|
| 238 |
+
#: heavy backfill Graph answers **HTTP 400 "There have been too many calls to this ad-account.
|
| 239 |
+
#: Wait a bit and try again."** It is a 4xx, so nothing about the status code says "retry" β the
|
| 240 |
+
#: MESSAGE is the only signal, which is why it is matched here rather than inferred from a code.
|
| 241 |
+
#: β It persists for minutes, so the backoff is measured in minutes and BOUNDED: after
|
| 242 |
+
#: `_RATE_TRIES` waits the loader STOPS and reports what it got, rather than sitting in a retry
|
| 243 |
+
#: loop nobody can see. A partial mirror that says it is partial beats a hung sync.
|
| 244 |
+
_RATE_LIMITED = "too many calls"
|
| 245 |
+
_RATE_TRIES = int(os.environ.get("META_RATE_TRIES") or 3)
|
| 246 |
+
_RATE_WAIT = int(os.environ.get("META_RATE_WAIT_S") or 90)
|
| 247 |
+
|
| 248 |
+
|
| 249 |
+
def _walk(path, tok, log, **params):
|
| 250 |
+
"""Every page of an edge, paged by CURSOR under our own parameters.
|
| 251 |
+
|
| 252 |
+
β IT DOES NOT FOLLOW GRAPH'S `paging.next` URL, AND THAT IS THE WHOLE POINT. Measured: the
|
| 253 |
+
first call to `/adcreatives` at limit=100 answers **HTTP 500 "Please reduce the amount of data
|
| 254 |
+
you're asking for"**, the retry at limit=25 succeeds β and then `next` carries the ORIGINAL
|
| 255 |
+
limit=100 and fails again on page 2. A backoff that cannot reach every page is not a backoff.
|
| 256 |
+
Re-issuing each page ourselves with `after=<cursor>` keeps the reduced limit for the whole walk.
|
| 257 |
+
|
| 258 |
+
β It shrinks the PAGE, never the FIELD LIST. Dropping columns to make a request fit is the
|
| 259 |
+
silent omission R2 forbids, and nothing downstream could see it. Fewer rows per call, always
|
| 260 |
+
every column per row.
|
| 261 |
+
|
| 262 |
+
-> (rows, hit_page_cap)
|
| 263 |
+
"""
|
| 264 |
+
out, pages = [], 0
|
| 265 |
+
limit = int(params.pop("limit", None) or PAGE)
|
| 266 |
+
after, waited = None, 0
|
| 267 |
+
while True:
|
| 268 |
+
call = dict(params, limit=limit)
|
| 269 |
+
if after:
|
| 270 |
+
call["after"] = after
|
| 271 |
+
try:
|
| 272 |
+
body = _get(path, tok, **call)
|
| 273 |
+
except MetaError as e:
|
| 274 |
+
if _TOO_MUCH in str(e) and limit > 5:
|
| 275 |
+
limit = max(5, limit // 4)
|
| 276 |
+
log(f" page too heavy for /{path} - retrying at limit={limit} "
|
| 277 |
+
f"(a payload ceiling, not a row cap; every column is still asked for)")
|
| 278 |
+
continue
|
| 279 |
+
if _RATE_LIMITED in str(e).lower() and waited < _RATE_TRIES:
|
| 280 |
+
waited += 1
|
| 281 |
+
log(f" rate-limited on /{path} (per AD ACCOUNT, not per token) - waiting "
|
| 282 |
+
f"{_RATE_WAIT}s, attempt {waited}/{_RATE_TRIES}")
|
| 283 |
+
time.sleep(_RATE_WAIT)
|
| 284 |
+
continue
|
| 285 |
+
if _RATE_LIMITED in str(e).lower():
|
| 286 |
+
log(f" !! GIVING UP on /{path} after {waited} waits: still rate-limited. "
|
| 287 |
+
f"{len(out)} row(s) collected so far are kept. Cause: the ads-management "
|
| 288 |
+
f"limit is per ad account and persists for minutes. Fix: re-run "
|
| 289 |
+
f"`--sync --only <table>` later; the upsert is idempotent.")
|
| 290 |
+
return out, True
|
| 291 |
+
raise
|
| 292 |
+
out.extend(body.get("data") or [])
|
| 293 |
+
pages += 1
|
| 294 |
+
after = ((body.get("paging") or {}).get("cursors") or {}).get("after")
|
| 295 |
+
has_next = bool((body.get("paging") or {}).get("next")) and bool(after)
|
| 296 |
+
if not has_next:
|
| 297 |
+
return out, False
|
| 298 |
+
if pages >= MAX_PAGES:
|
| 299 |
+
log(f" !! STOPPED at MAX_PAGES={MAX_PAGES} on /{path} with more pages left. "
|
| 300 |
+
f"Cause: a runaway guard, not a row cap. Fix: raise META_MAX_PAGES, or narrow the "
|
| 301 |
+
f"window with META_INSIGHTS_DAYS.")
|
| 302 |
+
return out, True
|
| 303 |
+
|
| 304 |
+
|
| 305 |
+
def _cell(value):
|
| 306 |
+
"""One Graph value -> one DuckDB cell. Nested structures become compact JSON TEXT rather than
|
| 307 |
+
being dropped: R2 says every field the API returns, and `targeting` is a field."""
|
| 308 |
+
if value is None or isinstance(value, (str, int, float, bool)):
|
| 309 |
+
return value
|
| 310 |
+
return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
|
| 311 |
+
|
| 312 |
+
|
| 313 |
+
def _coltype(name, rows=None):
|
| 314 |
+
"""The DuckDB type for one column β decided by the DATA when there is data, by the name only
|
| 315 |
+
as a fallback.
|
| 316 |
+
|
| 317 |
+
β THE NAME LIST WAS WRONG AND ONLY THE API COULD SAY SO. `cost_per_unique_click`,
|
| 318 |
+
`cost_per_action_type`, `purchase_roas` and friends READ like money and are **arrays of
|
| 319 |
+
action-type objects** on the Insights edge:
|
| 320 |
+
[{"action_type":"outbound_click","value":"1.459854"}]
|
| 321 |
+
Typed DOUBLE from `_DBL`, the insert died with `Conversion Error: Could not convert string
|
| 322 |
+
'[{...}]' to DOUBLE` β after five entity tables had already been written, so the sync looked
|
| 323 |
+
like it worked and then blew up on the last table.
|
| 324 |
+
β Same principle the field CATALOG is built on, applied one layer down: **ask the response,
|
| 325 |
+
do not assert from a list.** A value that ever arrives as a list or dict is JSON TEXT, because
|
| 326 |
+
that is what `_cell` stores; anything else falls back to the measured name hints.
|
| 327 |
+
"""
|
| 328 |
+
if rows:
|
| 329 |
+
seen, kinds = 0, set()
|
| 330 |
+
for r in rows:
|
| 331 |
+
v = r.get(name)
|
| 332 |
+
if v is None or v == "":
|
| 333 |
+
continue
|
| 334 |
+
kinds.add("json" if isinstance(v, (list, dict)) else
|
| 335 |
+
"bool" if isinstance(v, bool) else
|
| 336 |
+
"int" if isinstance(v, int) else
|
| 337 |
+
"float" if isinstance(v, float) else "str")
|
| 338 |
+
seen += 1
|
| 339 |
+
if seen >= 200:
|
| 340 |
+
break
|
| 341 |
+
if kinds:
|
| 342 |
+
if "json" in kinds or "str" in kinds:
|
| 343 |
+
return "VARCHAR" # a JSON blob, or a numeric STRING
|
| 344 |
+
if kinds <= {"int", "bool"}:
|
| 345 |
+
return "BIGINT" if name in _INT else ("VARCHAR" if "bool" in kinds else "BIGINT")
|
| 346 |
+
return "DOUBLE"
|
| 347 |
+
if name in _INT:
|
| 348 |
+
return "BIGINT"
|
| 349 |
+
if name in _DBL:
|
| 350 |
+
return "DOUBLE"
|
| 351 |
+
return "VARCHAR" # ids included β see the header
|
| 352 |
+
|
| 353 |
+
|
| 354 |
+
def _ensure(con, table, fields, rows=None):
|
| 355 |
+
"""Create or widen the table, with every column typed from `rows` when they are available.
|
| 356 |
+
|
| 357 |
+
β AN EXISTING COLUMN WHOSE TYPE IS NOW WRONG IS REBUILT, NOT PATCHED. DuckDB cannot retype a
|
| 358 |
+
column in place, and this table is DERIVED data that can be re-pulled in minutes β so a type
|
| 359 |
+
disagreement drops and recreates rather than limping on with a column that refuses every
|
| 360 |
+
insert. The alternative is a mirror that is permanently unwritable for one bad guess.
|
| 361 |
+
"""
|
| 362 |
+
want = {f: _coltype(f, rows) for f in fields}
|
| 363 |
+
have = {r[1]: str(r[2]).upper() for r in con.execute(f"PRAGMA table_info('{table}')").fetchall()}
|
| 364 |
+
if have:
|
| 365 |
+
clash = [f for f, ty in want.items() if f in have and have[f] != ty
|
| 366 |
+
and not (have[f].startswith("VARCHAR") and ty == "VARCHAR")]
|
| 367 |
+
if clash:
|
| 368 |
+
con.execute(f"DROP TABLE {table}")
|
| 369 |
+
have = {}
|
| 370 |
+
if not have:
|
| 371 |
+
cols = ", ".join(f"{f} {want[f]}" for f in fields)
|
| 372 |
+
con.execute(f"CREATE TABLE IF NOT EXISTS {table} (id VARCHAR PRIMARY KEY, {cols})"
|
| 373 |
+
if "id" not in fields else
|
| 374 |
+
f"CREATE TABLE IF NOT EXISTS {table} ({cols})")
|
| 375 |
+
return
|
| 376 |
+
for f in fields:
|
| 377 |
+
if f not in have:
|
| 378 |
+
con.execute(f"ALTER TABLE {table} ADD COLUMN {f} {want[f]}")
|
| 379 |
+
|
| 380 |
+
|
| 381 |
+
def _upsert(con, table, fields, rows):
|
| 382 |
+
"""Delete-then-insert by id β the same idempotence `datastore._upsert` gives the Odoo half, so
|
| 383 |
+
a re-sync updates in place and can never append a second copy of the same object."""
|
| 384 |
+
if not rows:
|
| 385 |
+
return 0
|
| 386 |
+
cols = list(fields)
|
| 387 |
+
ids = [str(r.get("id") or "") for r in rows]
|
| 388 |
+
q = ",".join("?" for _ in ids)
|
| 389 |
+
con.execute(f"DELETE FROM {table} WHERE id IN ({q})", ids)
|
| 390 |
+
con.executemany(
|
| 391 |
+
f"INSERT INTO {table} ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})",
|
| 392 |
+
[[_cell(r.get(c)) for c in cols] for r in rows])
|
| 393 |
+
return len(rows)
|
| 394 |
+
|
| 395 |
+
|
| 396 |
+
def sync(tenant_key="royal-imports", tok=None, log=print, insights=True, insights_days=None):
|
| 397 |
+
"""Pull every level into the tenant's mirror. -> a report dict; raises only on a bad token.
|
| 398 |
+
|
| 399 |
+
Idempotent: re-running updates rows in place. Safe to call at boot and on the resync loop,
|
| 400 |
+
exactly as `odoo_relational.refresh` is.
|
| 401 |
+
"""
|
| 402 |
+
tok = tok or token()
|
| 403 |
+
# β THE WINDOW IS A PARAMETER, NOT AN ENVIRONMENT READ AT CALL TIME β and the difference cost a
|
| 404 |
+
# live deploy. `INSIGHTS_DAYS` binds at IMPORT (module scope), so `main._pull_meta`'s
|
| 405 |
+
# `os.environ.setdefault("META_INSIGHTS_DAYS", "7")` executed AFTER this module was already
|
| 406 |
+
# imported and changed nothing: every boot pulled **90 days**, not 7, which is the slow path
|
| 407 |
+
# that trips the per-ad-account rate limit and never finishes. The comment beside that call
|
| 408 |
+
# claimed a short window the code could not deliver.
|
| 409 |
+
# β The shape: **a knob read at import cannot be turned by a caller at runtime.** Passing it
|
| 410 |
+
# makes the caller's intent effective instead of aspirational; the env var stays the DEFAULT.
|
| 411 |
+
days = int(insights_days or INSIGHTS_DAYS)
|
| 412 |
+
report = {"tenant": tenant_key, "tables": {}, "problems": [], "accounts": []}
|
| 413 |
+
if not tok:
|
| 414 |
+
report["problems"].append(
|
| 415 |
+
"META_ADS_ACCESS_TOKEN is not set in the environment or in platform/.env, so nothing "
|
| 416 |
+
"was pulled. This is a missing CREDENTIAL, not a missing capability.")
|
| 417 |
+
return report
|
| 418 |
+
|
| 419 |
+
path = datastore.path_for(tenant_key)
|
| 420 |
+
if Path(datastore.DB_PATH) != Path(path):
|
| 421 |
+
datastore.use_path(path)
|
| 422 |
+
con = datastore.connect()
|
| 423 |
+
log(f" mirror: {Path(path).name}")
|
| 424 |
+
|
| 425 |
+
accts, _ = _walk("me/adaccounts", tok, log, fields="id,name", limit=PAGE)
|
| 426 |
+
report["accounts"] = [a.get("id") for a in accts]
|
| 427 |
+
if not accts:
|
| 428 |
+
report["problems"].append("the token reaches no ad accounts")
|
| 429 |
+
return report
|
| 430 |
+
|
| 431 |
+
# ββ the five entity levels ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 432 |
+
for table, (edge, fields, _parent) in SPECS.items():
|
| 433 |
+
rows, capped = [], False
|
| 434 |
+
for acct in accts:
|
| 435 |
+
aid = acct["id"]
|
| 436 |
+
if edge is None:
|
| 437 |
+
rows.append(_get(aid, tok, fields=",".join(fields)))
|
| 438 |
+
else:
|
| 439 |
+
got, hit = _walk(f"{aid}/{edge}", tok, log, fields=",".join(fields), limit=PAGE)
|
| 440 |
+
rows.extend(got)
|
| 441 |
+
capped = capped or hit
|
| 442 |
+
_ensure(con, table, fields, rows)
|
| 443 |
+
n = _upsert(con, table, fields, rows)
|
| 444 |
+
total = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
|
| 445 |
+
report["tables"][table] = {"pulled": n, "in_mirror": total, "capped": capped}
|
| 446 |
+
log(f" {table:<20} pulled {n:>6} mirror total {total:>6}"
|
| 447 |
+
+ (" !! PAGE CAP HIT" if capped else ""))
|
| 448 |
+
if capped:
|
| 449 |
+
report["problems"].append(f"{table}: stopped at MAX_PAGES={MAX_PAGES}")
|
| 450 |
+
|
| 451 |
+
# ββ the daily Insights grain ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 452 |
+
if insights:
|
| 453 |
+
rows, capped = [], False
|
| 454 |
+
for acct in accts:
|
| 455 |
+
for since, until in _slices(days, INSIGHTS_SLICE):
|
| 456 |
+
got, hit = _walk(f"{acct['id']}/insights", tok, log,
|
| 457 |
+
fields=",".join(INSIGHT_FIELDS), level=INSIGHTS_LEVEL,
|
| 458 |
+
time_increment="1", limit=INSIGHTS_PAGE,
|
| 459 |
+
time_range=json.dumps({"since": since, "until": until}))
|
| 460 |
+
rows.extend(got)
|
| 461 |
+
capped = capped or hit
|
| 462 |
+
# β Insights rows carry no id. The key must be STABLE across runs or every re-sync
|
| 463 |
+
# appends a second copy of the same day β so it is composed from the grain itself.
|
| 464 |
+
for r in rows:
|
| 465 |
+
r["id"] = ":".join(str(r.get(k) or "") for k in
|
| 466 |
+
(f"{INSIGHTS_LEVEL}_id", "date_start", "date_stop"))
|
| 467 |
+
fields = ["id"] + INSIGHT_FIELDS
|
| 468 |
+
_ensure(con, INSIGHTS_TABLE, fields, rows)
|
| 469 |
+
n = _upsert(con, INSIGHTS_TABLE, fields, rows)
|
| 470 |
+
total = con.execute(f"SELECT count(*) FROM {INSIGHTS_TABLE}").fetchone()[0]
|
| 471 |
+
report["tables"][INSIGHTS_TABLE] = {"pulled": n, "in_mirror": total, "capped": capped}
|
| 472 |
+
log(f" {INSIGHTS_TABLE:<20} pulled {n:>6} mirror total {total:>6}"
|
| 473 |
+
+ (" !! PAGE CAP HIT" if capped else ""))
|
| 474 |
+
|
| 475 |
+
con.execute("INSERT OR REPLACE INTO _sync_state VALUES (?,?,?,?,?,?)",
|
| 476 |
+
["meta", "done", 0, f"{days}d/{INSIGHTS_SLICE}d@{INSIGHTS_LEVEL}",
|
| 477 |
+
sum(t["in_mirror"] for t in report["tables"].values()),
|
| 478 |
+
time.strftime("%Y-%m-%d %H:%M:%S")])
|
| 479 |
+
return report
|
| 480 |
+
|
| 481 |
+
|
| 482 |
+
def status(tenant_key="royal-imports"):
|
| 483 |
+
"""What is in the mirror right now, per table. Never fetches."""
|
| 484 |
+
path = datastore.path_for(tenant_key)
|
| 485 |
+
if Path(datastore.DB_PATH) != Path(path):
|
| 486 |
+
datastore.use_path(path)
|
| 487 |
+
out = {}
|
| 488 |
+
con = datastore.connect()
|
| 489 |
+
for table in list(SPECS) + [INSIGHTS_TABLE]:
|
| 490 |
+
try:
|
| 491 |
+
out[table] = con.execute(f"SELECT count(*) FROM {table}").fetchone()[0]
|
| 492 |
+
except Exception:
|
| 493 |
+
out[table] = None # table absent = never synced
|
| 494 |
+
return out
|
| 495 |
+
|
| 496 |
+
|
| 497 |
+
def main(argv=None):
|
| 498 |
+
ap = argparse.ArgumentParser(description="Pull Meta Ads into the tenant's DuckDB mirror.")
|
| 499 |
+
ap.add_argument("--sync", action="store_true")
|
| 500 |
+
ap.add_argument("--status", action="store_true")
|
| 501 |
+
ap.add_argument("--tenant", default="royal-imports")
|
| 502 |
+
ap.add_argument("--no-insights", action="store_true")
|
| 503 |
+
ap.add_argument("--insights-days", type=int, default=None,
|
| 504 |
+
help="override the Insights window for THIS run (default INSIGHTS_DAYS); the env var is the default, this is the caller's say")
|
| 505 |
+
a = ap.parse_args(argv)
|
| 506 |
+
if a.status:
|
| 507 |
+
for k, v in status(a.tenant).items():
|
| 508 |
+
print(f" {k:<20} {'(never synced)' if v is None else v}")
|
| 509 |
+
return 0
|
| 510 |
+
if not a.sync:
|
| 511 |
+
ap.print_help()
|
| 512 |
+
return 2
|
| 513 |
+
rep = sync(a.tenant, insights=not a.no_insights, insights_days=a.insights_days)
|
| 514 |
+
for p in rep["problems"]:
|
| 515 |
+
print(" PROBLEM:", p)
|
| 516 |
+
print(f" accounts: {len(rep['accounts'])} tables: {len(rep['tables'])}")
|
| 517 |
+
return 1 if rep["problems"] else 0
|
| 518 |
+
|
| 519 |
+
|
| 520 |
+
if __name__ == "__main__":
|
| 521 |
+
sys.exit(main())
|
platform/model/metrics/sales.yml
CHANGED
|
@@ -1,149 +1,149 @@
|
|
| 1 |
-
# Metrics: sales β the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
|
| 2 |
-
# metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
|
| 3 |
-
# Fields per metric:
|
| 4 |
-
# key/label/description β identity + the human definition (visibility = trust)
|
| 5 |
-
# agg + field β sum | count_distinct over the topic's entity
|
| 6 |
-
# agg: ratio β numerator/denominator are metric KEYS (resolved recursively)
|
| 7 |
-
# agg: derived + expr β arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
|
| 8 |
-
# format β usd | int | pct (rendering hint for surfaces)
|
| 9 |
-
# ai_context β what a small model must know to use the metric correctly
|
| 10 |
-
# validate β the INDEPENDENT Odoo cross-check contract (named method implemented in
|
| 11 |
-
# harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
|
| 12 |
-
# empty β W37 C1's EMPTY-WINDOW FAMILY. See below; a metric an ENTITY topic
|
| 13 |
-
# offers as a lookback column MUST declare one.
|
| 14 |
-
#
|
| 15 |
-
# ββ `empty:` β WHAT A ROW WITH NO ACTIVITY IN THE WINDOW RENDERS AS (wave 37, contract C1).
|
| 16 |
-
# Measured and load-bearing: only 1,646 of 5,836 active products sold in the last 90 days, so a
|
| 17 |
-
# per-SKU lookback metric has NO GROUP for 72% of the catalogue. Get the default wrong and every
|
| 18 |
-
# product grid reads as broken. Two values, and the difference is whether the blank cell would be
|
| 19 |
-
# a TRUE STATEMENT:
|
| 20 |
-
# empty: zero ADDITIVE β units, revenue, margin $, COGS. "It sold nothing" is a real
|
| 21 |
-
# measurement, so 0 is the honest cell and a blank would hide a fact.
|
| 22 |
-
# empty: blank RATIO / DERIVED-FROM-A-RATIO β GM %, ASP. A 0% margin on zero sales is a
|
| 23 |
-
# FALSE statement, not a missing one. β AND THE GUARD IS THE DENOMINATOR, NOT
|
| 24 |
-
# THE MISSING GROUP: `semantic._post_compute` returns 0.0 for `num/0`, so a SKU
|
| 25 |
-
# that DID sell at $0 would print "0.0%" with a group behind it. The resolver
|
| 26 |
-
# blanks on a zero denominator, which is the only reading that is never a lie.
|
| 27 |
-
# β A metric with no `empty:` is REFUSED by `entity_measures()` rather than defaulted β a
|
| 28 |
-
# defaulted family is a guess about truth, and C1 says a metric that cannot say which family it
|
| 29 |
-
# is in does not ship.
|
| 30 |
-
topic: sales_lines
|
| 31 |
-
metrics:
|
| 32 |
-
- key: revenue
|
| 33 |
-
label: Revenue
|
| 34 |
-
agg: sum
|
| 35 |
-
field: price_subtotal
|
| 36 |
-
format: usd
|
| 37 |
-
empty: zero
|
| 38 |
-
description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
|
| 39 |
-
ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
|
| 40 |
-
validate:
|
| 41 |
-
method: order_level_revenue
|
| 42 |
-
note: "Ξ£ line price_subtotal must equal Ξ£ parent-order amount_untaxed under the same scope, to the cent (line vs order basis β the built-in cross-check)."
|
| 43 |
-
|
| 44 |
-
- key: units
|
| 45 |
-
label: Units sold
|
| 46 |
-
agg: sum
|
| 47 |
-
field: product_uom_qty
|
| 48 |
-
format: int
|
| 49 |
-
empty: zero
|
| 50 |
-
description: "Total quantity across confirmed wholesale order lines."
|
| 51 |
-
ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
|
| 52 |
-
|
| 53 |
-
- key: margin
|
| 54 |
-
label: Gross margin $
|
| 55 |
-
agg: sum
|
| 56 |
-
field: margin
|
| 57 |
-
format: usd
|
| 58 |
-
empty: zero
|
| 59 |
-
description: "Line revenue minus line cost (Odoo Margin module), summed."
|
| 60 |
-
ai_context: "margin is read_group-aggregatable (Margin module installed). COGS = revenue - margin. purchase_price is per-UNIT cost β never sum it as a total."
|
| 61 |
-
|
| 62 |
-
- key: cogs
|
| 63 |
-
label: COGS
|
| 64 |
-
agg: derived
|
| 65 |
-
expr: "revenue - margin"
|
| 66 |
-
format: usd
|
| 67 |
-
empty: zero
|
| 68 |
-
description: "Cost of goods sold, derived: revenue minus gross margin."
|
| 69 |
-
ai_context: "Derived, not pulled β Odoo carries cost on lines as margin; COGS is the difference."
|
| 70 |
-
|
| 71 |
-
- key: margin_pct
|
| 72 |
-
label: Gross margin %
|
| 73 |
-
agg: ratio
|
| 74 |
-
numerator: margin
|
| 75 |
-
denominator: revenue
|
| 76 |
-
format: pct
|
| 77 |
-
empty: blank
|
| 78 |
-
description: "Gross margin as a share of revenue."
|
| 79 |
-
ai_context: "Compare across BUs/categories at the same scope only. β TWO ZERO-REVENUE BEHAVIOURS, deliberately: the scalar/analyst path returns 0 (semantic._post_compute's guard), while an ENTITY LOOKBACK COLUMN renders BLANK (empty: blank) β on a grid, a printed 0.0% beside 5,836 products would assert a margin nobody measured."
|
| 80 |
-
|
| 81 |
-
# β W37-T10 β ASP, the fifth SHIP-FIRST per-SKU metric (proto/P3). Blended $18.76 over 1,646
|
| 82 |
-
# SKUs in the 90 days to 2026-08-19. A RATIO of two same-topic base measures, so it survives a
|
| 83 |
-
# GROUPED store_query (only a CROSS-TOPIC component is refused β that is what stops `aov`,
|
| 84 |
-
# whose denominator `orders` lives on sales_orders).
|
| 85 |
-
# β UNITS ARE AS-ORDERED, mixed UoM. `units` says so and this inherits it: a SKU sold in cases
|
| 86 |
-
# and in singles has an ASP blended across both, which is the true average selling price of a
|
| 87 |
-
# line unit and NOT a per-piece price.
|
| 88 |
-
- key: asp
|
| 89 |
-
label: Average selling price
|
| 90 |
-
agg: ratio
|
| 91 |
-
numerator: revenue
|
| 92 |
-
denominator: units
|
| 93 |
-
format: usd
|
| 94 |
-
empty: blank
|
| 95 |
-
description: "Revenue per unit sold β the blended average selling price."
|
| 96 |
-
ai_context: "revenue Γ· units at identical scope. Mixed units of measure are summed as ordered quantity, so this is per ordered unit, not per piece. Blank when nothing sold: an ASP of $0 on zero units is a false statement, not a missing one."
|
| 97 |
-
|
| 98 |
-
- key: orders
|
| 99 |
-
label: Orders
|
| 100 |
-
topic: sales_orders
|
| 101 |
-
agg: count
|
| 102 |
-
format: int
|
| 103 |
-
description: "Confirmed wholesale orders in the window (order-header count β what the scorecards show)."
|
| 104 |
-
ai_context: "Order-level count; slightly higher than distinct-orders-from-lines because a few confirmed orders carry zero lines (a data-health artifact the reconciliation contract counts exactly)."
|
| 105 |
-
validate:
|
| 106 |
-
method: order_count
|
| 107 |
-
note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
|
| 108 |
-
|
| 109 |
-
- key: customers
|
| 110 |
-
label: Active customers
|
| 111 |
-
agg: count_distinct
|
| 112 |
-
field: order_partner_id
|
| 113 |
-
format: int
|
| 114 |
-
empty: zero
|
| 115 |
-
description: "Distinct customers with at least one confirmed wholesale order line in the window."
|
| 116 |
-
ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
|
| 117 |
-
|
| 118 |
-
- key: aov
|
| 119 |
-
label: Average order value
|
| 120 |
-
agg: ratio
|
| 121 |
-
numerator: revenue
|
| 122 |
-
denominator: orders
|
| 123 |
-
format: usd
|
| 124 |
-
description: "Revenue per distinct order."
|
| 125 |
-
ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
|
| 126 |
-
|
| 127 |
-
# β Wave 21 R2 β the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
|
| 128 |
-
# not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
|
| 129 |
-
# invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
|
| 130 |
-
# `live_domain` filters the live path β BOTH or store_parity compares two different questions.
|
| 131 |
-
- key: revenue_invoiced
|
| 132 |
-
label: Sales β fully invoiced
|
| 133 |
-
agg: sum
|
| 134 |
-
field: price_subtotal
|
| 135 |
-
store_filter_sql: "o.invoice_status = 'invoiced'"
|
| 136 |
-
live_domain: [["order_id.invoice_status", "=", "invoiced"]]
|
| 137 |
-
format: usd
|
| 138 |
-
description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
|
| 139 |
-
ai_context: "Same scope as revenue, narrowed by the ORDER-level fully-invoiced flag. This is NOT posted-invoice-line revenue: a partially invoiced order is excluded entirely until Odoo flips the flag. Reconciled store-vs-live per BU by store_parity."
|
| 140 |
-
|
| 141 |
-
- key: orders_invoiced
|
| 142 |
-
label: Orders β fully invoiced
|
| 143 |
-
topic: sales_orders
|
| 144 |
-
agg: count
|
| 145 |
-
store_filter_sql: "o.invoice_status = 'invoiced'"
|
| 146 |
-
live_domain: [["invoice_status", "=", "invoiced"]]
|
| 147 |
-
format: int
|
| 148 |
-
description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
|
| 149 |
-
ai_context: "Order-header count under the orders scope plus the fully-invoiced flag; partially invoiced and not-yet-invoiced orders are excluded. Reconciled store-vs-live per BU by store_parity."
|
|
|
|
| 1 |
+
# Metrics: sales β the core wholesale metrics, defined ONCE (OM-0). Every surface (pages, the
|
| 2 |
+
# metric dictionary, the Analyst, MCP) resolves these by key through harness/semantic.py.
|
| 3 |
+
# Fields per metric:
|
| 4 |
+
# key/label/description β identity + the human definition (visibility = trust)
|
| 5 |
+
# agg + field β sum | count_distinct over the topic's entity
|
| 6 |
+
# agg: ratio β numerator/denominator are metric KEYS (resolved recursively)
|
| 7 |
+
# agg: derived + expr β arithmetic over metric keys (safe parser; +,-,*,/ and parens only)
|
| 8 |
+
# format β usd | int | pct (rendering hint for surfaces)
|
| 9 |
+
# ai_context β what a small model must know to use the metric correctly
|
| 10 |
+
# validate β the INDEPENDENT Odoo cross-check contract (named method implemented in
|
| 11 |
+
# harness/semantic.py _VALIDATORS; a metric that can't tie out says so)
|
| 12 |
+
# empty β W37 C1's EMPTY-WINDOW FAMILY. See below; a metric an ENTITY topic
|
| 13 |
+
# offers as a lookback column MUST declare one.
|
| 14 |
+
#
|
| 15 |
+
# ββ `empty:` β WHAT A ROW WITH NO ACTIVITY IN THE WINDOW RENDERS AS (wave 37, contract C1).
|
| 16 |
+
# Measured and load-bearing: only 1,646 of 5,836 active products sold in the last 90 days, so a
|
| 17 |
+
# per-SKU lookback metric has NO GROUP for 72% of the catalogue. Get the default wrong and every
|
| 18 |
+
# product grid reads as broken. Two values, and the difference is whether the blank cell would be
|
| 19 |
+
# a TRUE STATEMENT:
|
| 20 |
+
# empty: zero ADDITIVE β units, revenue, margin $, COGS. "It sold nothing" is a real
|
| 21 |
+
# measurement, so 0 is the honest cell and a blank would hide a fact.
|
| 22 |
+
# empty: blank RATIO / DERIVED-FROM-A-RATIO β GM %, ASP. A 0% margin on zero sales is a
|
| 23 |
+
# FALSE statement, not a missing one. β AND THE GUARD IS THE DENOMINATOR, NOT
|
| 24 |
+
# THE MISSING GROUP: `semantic._post_compute` returns 0.0 for `num/0`, so a SKU
|
| 25 |
+
# that DID sell at $0 would print "0.0%" with a group behind it. The resolver
|
| 26 |
+
# blanks on a zero denominator, which is the only reading that is never a lie.
|
| 27 |
+
# β A metric with no `empty:` is REFUSED by `entity_measures()` rather than defaulted β a
|
| 28 |
+
# defaulted family is a guess about truth, and C1 says a metric that cannot say which family it
|
| 29 |
+
# is in does not ship.
|
| 30 |
+
topic: sales_lines
|
| 31 |
+
metrics:
|
| 32 |
+
- key: revenue
|
| 33 |
+
label: Revenue
|
| 34 |
+
agg: sum
|
| 35 |
+
field: price_subtotal
|
| 36 |
+
format: usd
|
| 37 |
+
empty: zero
|
| 38 |
+
description: "Untaxed revenue of confirmed wholesale order lines (the owner's 'sales' number)."
|
| 39 |
+
ai_context: "Always untaxed; excludes Amazon (GIFTWARE DEALS) and unconfirmed orders. Filter one BU via team_id (Fisch=5, Royal=6)."
|
| 40 |
+
validate:
|
| 41 |
+
method: order_level_revenue
|
| 42 |
+
note: "Ξ£ line price_subtotal must equal Ξ£ parent-order amount_untaxed under the same scope, to the cent (line vs order basis β the built-in cross-check)."
|
| 43 |
+
|
| 44 |
+
- key: units
|
| 45 |
+
label: Units sold
|
| 46 |
+
agg: sum
|
| 47 |
+
field: product_uom_qty
|
| 48 |
+
format: int
|
| 49 |
+
empty: zero
|
| 50 |
+
description: "Total quantity across confirmed wholesale order lines."
|
| 51 |
+
ai_context: "Mixed UoMs are summed as ordered quantity; for weight/case analysis convert per product UoM first."
|
| 52 |
+
|
| 53 |
+
- key: margin
|
| 54 |
+
label: Gross margin $
|
| 55 |
+
agg: sum
|
| 56 |
+
field: margin
|
| 57 |
+
format: usd
|
| 58 |
+
empty: zero
|
| 59 |
+
description: "Line revenue minus line cost (Odoo Margin module), summed."
|
| 60 |
+
ai_context: "margin is read_group-aggregatable (Margin module installed). COGS = revenue - margin. purchase_price is per-UNIT cost β never sum it as a total."
|
| 61 |
+
|
| 62 |
+
- key: cogs
|
| 63 |
+
label: COGS
|
| 64 |
+
agg: derived
|
| 65 |
+
expr: "revenue - margin"
|
| 66 |
+
format: usd
|
| 67 |
+
empty: zero
|
| 68 |
+
description: "Cost of goods sold, derived: revenue minus gross margin."
|
| 69 |
+
ai_context: "Derived, not pulled β Odoo carries cost on lines as margin; COGS is the difference."
|
| 70 |
+
|
| 71 |
+
- key: margin_pct
|
| 72 |
+
label: Gross margin %
|
| 73 |
+
agg: ratio
|
| 74 |
+
numerator: margin
|
| 75 |
+
denominator: revenue
|
| 76 |
+
format: pct
|
| 77 |
+
empty: blank
|
| 78 |
+
description: "Gross margin as a share of revenue."
|
| 79 |
+
ai_context: "Compare across BUs/categories at the same scope only. β TWO ZERO-REVENUE BEHAVIOURS, deliberately: the scalar/analyst path returns 0 (semantic._post_compute's guard), while an ENTITY LOOKBACK COLUMN renders BLANK (empty: blank) β on a grid, a printed 0.0% beside 5,836 products would assert a margin nobody measured."
|
| 80 |
+
|
| 81 |
+
# β W37-T10 β ASP, the fifth SHIP-FIRST per-SKU metric (proto/P3). Blended $18.76 over 1,646
|
| 82 |
+
# SKUs in the 90 days to 2026-08-19. A RATIO of two same-topic base measures, so it survives a
|
| 83 |
+
# GROUPED store_query (only a CROSS-TOPIC component is refused β that is what stops `aov`,
|
| 84 |
+
# whose denominator `orders` lives on sales_orders).
|
| 85 |
+
# β UNITS ARE AS-ORDERED, mixed UoM. `units` says so and this inherits it: a SKU sold in cases
|
| 86 |
+
# and in singles has an ASP blended across both, which is the true average selling price of a
|
| 87 |
+
# line unit and NOT a per-piece price.
|
| 88 |
+
- key: asp
|
| 89 |
+
label: Average selling price
|
| 90 |
+
agg: ratio
|
| 91 |
+
numerator: revenue
|
| 92 |
+
denominator: units
|
| 93 |
+
format: usd
|
| 94 |
+
empty: blank
|
| 95 |
+
description: "Revenue per unit sold β the blended average selling price."
|
| 96 |
+
ai_context: "revenue Γ· units at identical scope. Mixed units of measure are summed as ordered quantity, so this is per ordered unit, not per piece. Blank when nothing sold: an ASP of $0 on zero units is a false statement, not a missing one."
|
| 97 |
+
|
| 98 |
+
- key: orders
|
| 99 |
+
label: Orders
|
| 100 |
+
topic: sales_orders
|
| 101 |
+
agg: count
|
| 102 |
+
format: int
|
| 103 |
+
description: "Confirmed wholesale orders in the window (order-header count β what the scorecards show)."
|
| 104 |
+
ai_context: "Order-level count; slightly higher than distinct-orders-from-lines because a few confirmed orders carry zero lines (a data-health artifact the reconciliation contract counts exactly)."
|
| 105 |
+
validate:
|
| 106 |
+
method: order_count
|
| 107 |
+
note: "Order-level count must equal distinct line-parent orders + line-less orders, exactly (surfaces empty orders instead of hiding them in a tolerance)."
|
| 108 |
+
|
| 109 |
+
- key: customers
|
| 110 |
+
label: Active customers
|
| 111 |
+
agg: count_distinct
|
| 112 |
+
field: order_partner_id
|
| 113 |
+
format: int
|
| 114 |
+
empty: zero
|
| 115 |
+
description: "Distinct customers with at least one confirmed wholesale order line in the window."
|
| 116 |
+
ai_context: "Customer = the order's partner. Agent attribution uses res.partner.agent_ids, NOT the order user_id."
|
| 117 |
+
|
| 118 |
+
- key: aov
|
| 119 |
+
label: Average order value
|
| 120 |
+
agg: ratio
|
| 121 |
+
numerator: revenue
|
| 122 |
+
denominator: orders
|
| 123 |
+
format: usd
|
| 124 |
+
description: "Revenue per distinct order."
|
| 125 |
+
ai_context: "Ratio of two registered metrics at identical scope; never average per-order averages."
|
| 126 |
+
|
| 127 |
+
# β Wave 21 R2 β the FULLY-INVOICED basis, as separate metrics (owner ruling: picker entries,
|
| 128 |
+
# not a basis dropdown). Same topics, same scope, ONE predicate narrower: the order's Odoo
|
| 129 |
+
# invoice_status = 'invoiced'. `store_filter_sql` filters the store path (sum/count CASE);
|
| 130 |
+
# `live_domain` filters the live path β BOTH or store_parity compares two different questions.
|
| 131 |
+
- key: revenue_invoiced
|
| 132 |
+
label: Sales β fully invoiced
|
| 133 |
+
agg: sum
|
| 134 |
+
field: price_subtotal
|
| 135 |
+
store_filter_sql: "o.invoice_status = 'invoiced'"
|
| 136 |
+
live_domain: [["order_id.invoice_status", "=", "invoiced"]]
|
| 137 |
+
format: usd
|
| 138 |
+
description: "Untaxed revenue of confirmed wholesale order lines whose parent order Odoo marks fully invoiced (invoice_status = invoiced)."
|
| 139 |
+
ai_context: "Same scope as revenue, narrowed by the ORDER-level fully-invoiced flag. This is NOT posted-invoice-line revenue: a partially invoiced order is excluded entirely until Odoo flips the flag. Reconciled store-vs-live per BU by store_parity."
|
| 140 |
+
|
| 141 |
+
- key: orders_invoiced
|
| 142 |
+
label: Orders β fully invoiced
|
| 143 |
+
topic: sales_orders
|
| 144 |
+
agg: count
|
| 145 |
+
store_filter_sql: "o.invoice_status = 'invoiced'"
|
| 146 |
+
live_domain: [["invoice_status", "=", "invoiced"]]
|
| 147 |
+
format: int
|
| 148 |
+
description: "Confirmed wholesale orders Odoo marks fully invoiced (invoice_status = invoiced)."
|
| 149 |
+
ai_context: "Order-header count under the orders scope plus the fully-invoiced flag; partially invoiced and not-yet-invoiced orders are excluded. Reconciled store-vs-live per BU by store_parity."
|
platform/model/topics/odoo_accounts.yml
CHANGED
|
@@ -1,60 +1,60 @@
|
|
| 1 |
-
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
-
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
-
#
|
| 4 |
-
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
-
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
-
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
-
# trained on a schema the product does not have.
|
| 8 |
-
key: odoo_accounts
|
| 9 |
-
label: "Odoo GL accounts"
|
| 10 |
-
entity: account.account
|
| 11 |
-
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
-
grid: ut_odoo_accounts
|
| 13 |
-
subject: "odoo:account.account"
|
| 14 |
-
grain: "one row per GL account in the chart of accounts"
|
| 15 |
-
scope:
|
| 16 |
-
population: "every account.account record (192 measured)"
|
| 17 |
-
store:
|
| 18 |
-
table: account_account
|
| 19 |
-
alias: a
|
| 20 |
-
# NO date_col β a registry is not a dated event stream. Stated rather than
|
| 21 |
-
# omitted, so its absence reads as a fact and not as an unfinished file.
|
| 22 |
-
dims:
|
| 23 |
-
account_type: {label: "Account type"}
|
| 24 |
-
|
| 25 |
-
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 26 |
-
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 27 |
-
# from another topic; a `link` points at another database.
|
| 28 |
-
fields:
|
| 29 |
-
- key: account_code
|
| 30 |
-
label: "Code"
|
| 31 |
-
type: text
|
| 32 |
-
kind: data
|
| 33 |
-
- key: account_name
|
| 34 |
-
label: "Account"
|
| 35 |
-
type: text
|
| 36 |
-
kind: data
|
| 37 |
-
- key: odoo_id
|
| 38 |
-
label: "Odoo ID"
|
| 39 |
-
type: int
|
| 40 |
-
kind: data
|
| 41 |
-
means: "The `account.account` id. Also this row's id."
|
| 42 |
-
- key: account_type
|
| 43 |
-
label: "Type"
|
| 44 |
-
type: select
|
| 45 |
-
kind: data
|
| 46 |
-
- key: is_expense
|
| 47 |
-
label: "Expense account"
|
| 48 |
-
type: checkbox
|
| 49 |
-
kind: data
|
| 50 |
-
means: "Ticked for the expense family - the same predicate the semantic layer's gl_lines topic uses, so this column and that topic cannot disagree."
|
| 51 |
-
- key: refreshed
|
| 52 |
-
label: "Refreshed"
|
| 53 |
-
type: date
|
| 54 |
-
kind: data
|
| 55 |
-
means: "When this row was last reconciled against Odoo."
|
| 56 |
-
|
| 57 |
-
ai_context: >
|
| 58 |
-
The chart of accounts β the registry gl_lines posts against.
|
| 59 |
-
Use it to resolve an account code to a name or a type.
|
| 60 |
-
β `is_expense` is a DERIVED boolean standing in for Odoo's five-value `internal_group` (asset/liability/equity/income/expense), which the mirror does not yet carry.
|
|
|
|
| 1 |
+
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
+
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
+
#
|
| 4 |
+
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
+
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
+
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
+
# trained on a schema the product does not have.
|
| 8 |
+
key: odoo_accounts
|
| 9 |
+
label: "Odoo GL accounts"
|
| 10 |
+
entity: account.account
|
| 11 |
+
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
+
grid: ut_odoo_accounts
|
| 13 |
+
subject: "odoo:account.account"
|
| 14 |
+
grain: "one row per GL account in the chart of accounts"
|
| 15 |
+
scope:
|
| 16 |
+
population: "every account.account record (192 measured)"
|
| 17 |
+
store:
|
| 18 |
+
table: account_account
|
| 19 |
+
alias: a
|
| 20 |
+
# NO date_col β a registry is not a dated event stream. Stated rather than
|
| 21 |
+
# omitted, so its absence reads as a fact and not as an unfinished file.
|
| 22 |
+
dims:
|
| 23 |
+
account_type: {label: "Account type"}
|
| 24 |
+
|
| 25 |
+
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 26 |
+
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 27 |
+
# from another topic; a `link` points at another database.
|
| 28 |
+
fields:
|
| 29 |
+
- key: account_code
|
| 30 |
+
label: "Code"
|
| 31 |
+
type: text
|
| 32 |
+
kind: data
|
| 33 |
+
- key: account_name
|
| 34 |
+
label: "Account"
|
| 35 |
+
type: text
|
| 36 |
+
kind: data
|
| 37 |
+
- key: odoo_id
|
| 38 |
+
label: "Odoo ID"
|
| 39 |
+
type: int
|
| 40 |
+
kind: data
|
| 41 |
+
means: "The `account.account` id. Also this row's id."
|
| 42 |
+
- key: account_type
|
| 43 |
+
label: "Type"
|
| 44 |
+
type: select
|
| 45 |
+
kind: data
|
| 46 |
+
- key: is_expense
|
| 47 |
+
label: "Expense account"
|
| 48 |
+
type: checkbox
|
| 49 |
+
kind: data
|
| 50 |
+
means: "Ticked for the expense family - the same predicate the semantic layer's gl_lines topic uses, so this column and that topic cannot disagree."
|
| 51 |
+
- key: refreshed
|
| 52 |
+
label: "Refreshed"
|
| 53 |
+
type: date
|
| 54 |
+
kind: data
|
| 55 |
+
means: "When this row was last reconciled against Odoo."
|
| 56 |
+
|
| 57 |
+
ai_context: >
|
| 58 |
+
The chart of accounts β the registry gl_lines posts against.
|
| 59 |
+
Use it to resolve an account code to a name or a type.
|
| 60 |
+
β `is_expense` is a DERIVED boolean standing in for Odoo's five-value `internal_group` (asset/liability/equity/income/expense), which the mirror does not yet carry.
|
platform/model/topics/odoo_agents.yml
CHANGED
|
@@ -1,91 +1,91 @@
|
|
| 1 |
-
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
-
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
-
#
|
| 4 |
-
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
-
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
-
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
-
# trained on a schema the product does not have.
|
| 8 |
-
key: odoo_agents
|
| 9 |
-
label: "Odoo agents"
|
| 10 |
-
entity: res.partner
|
| 11 |
-
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
-
grid: ut_odoo_agents
|
| 13 |
-
subject: "odoo:res.partner.agent"
|
| 14 |
-
grain: "one row per sales agent"
|
| 15 |
-
scope:
|
| 16 |
-
population: "a UNION of two disagreeing sources β partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
|
| 17 |
-
why_union: "measured 2026-08-09: 16 carry commission lines, 17 carry the flag, and the union is 19 β either source alone silently drops real agents"
|
| 18 |
-
store:
|
| 19 |
-
table: res_partner
|
| 20 |
-
alias: p
|
| 21 |
-
# NO date_col β a registry is not a dated event stream. Stated rather than
|
| 22 |
-
# omitted, so its absence reads as a fact and not as an unfinished file.
|
| 23 |
-
|
| 24 |
-
# ββ W37-T12 / owner item 4 (R1) β THE LOOKBACK-MEASURE BINDING, the agent half of
|
| 25 |
-
# *"It should apply to Odoo agents database as well."* Same contract as
|
| 26 |
-
# `odoo_products.yml`: a FACT topic, and the dim of that topic which carries THIS
|
| 27 |
-
# entity's identity.
|
| 28 |
-
#
|
| 29 |
-
# ββ WHICH AGENT SOURCE, STATED β because there are THREE in this Odoo and they name
|
| 30 |
-
# DIFFERENT PEOPLE (`proto/P3-metric-catalog.md`: 9 agents carry route-1 revenue, 12
|
| 31 |
-
# carry commission lines, 17 carry the flag). This binds ROUTE 1, the CUSTOMER-MASTER
|
| 32 |
-
# BOOK: `sales_lines.agent` is `rp.agent_id`, the customer's assigned agent, so every
|
| 33 |
-
# order of that customer counts toward their agent. That is "whose book is this" and it
|
| 34 |
-
# is the right question for a column on the AGENT REGISTRY.
|
| 35 |
-
# β It is NOT commission. `account.invoice.line.agent` (topic `commission_lines`) is the
|
| 36 |
-
# per-INVOICE-LINE credited agent and answers a different question; `sales_lines.yml`'s
|
| 37 |
-
# own `agent` dim comment carries the full disagreement and says never to "fix" one by
|
| 38 |
-
# reading the other.
|
| 39 |
-
#
|
| 40 |
-
# β THE JOIN NEEDS NO NEW DIM, unlike the product side. `sales_lines.agent` declares a
|
| 41 |
-
# `name_col`, so `store_query` emits `agent_id` β which IS `res.partner.id`, which IS
|
| 42 |
-
# this grid's `odoo_id` identity. Product needed `product_code` because its grid keys on
|
| 43 |
-
# `default_code`; this one already keys on the same integer the fact topic groups by.
|
| 44 |
-
measures:
|
| 45 |
-
source: sales_lines
|
| 46 |
-
dim: agent
|
| 47 |
-
keys: [revenue, units, margin, cogs, margin_pct, asp, customers]
|
| 48 |
-
not_yet:
|
| 49 |
-
- key: orders / aov
|
| 50 |
-
cause: "`orders` lives on topic `sales_orders`, so under a `group_by` it is a CROSS-TOPIC measure and `semantic.store_query` refuses it (scalar-only). `aov` inherits the refusal through its denominator"
|
| 51 |
-
fix: "add an ORDER-COUNT metric to `sales_lines` itself β `count_distinct` over `l.order_id` β which answers the same question at this grain in one pass"
|
| 52 |
-
- key: commission_amount
|
| 53 |
-
cause: "the commission basis lives on `account.invoice.line.agent` (topic `commission_lines`), a different topic AND a different grain; `invoice_lines` deduplicates to at most one agent per line"
|
| 54 |
-
fix: "bind a SECOND measures block per source once the contract allows more than one, and label the columns so the two routes can never be read as the same number"
|
| 55 |
-
|
| 56 |
-
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 57 |
-
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 58 |
-
# from another topic; a `link` points at another database.
|
| 59 |
-
fields:
|
| 60 |
-
- key: agent
|
| 61 |
-
label: "Agent"
|
| 62 |
-
type: text
|
| 63 |
-
kind: data
|
| 64 |
-
- key: odoo_id
|
| 65 |
-
label: "Odoo ID"
|
| 66 |
-
type: int
|
| 67 |
-
kind: data
|
| 68 |
-
means: "The `res.partner` id. Also this row's id."
|
| 69 |
-
- key: agent_id
|
| 70 |
-
label: "Odoo agent id"
|
| 71 |
-
type: int
|
| 72 |
-
kind: data
|
| 73 |
-
- key: flagged
|
| 74 |
-
label: "Flagged in Odoo"
|
| 75 |
-
type: checkbox
|
| 76 |
-
kind: data
|
| 77 |
-
means: "Ticked = `res.partner.agent` is set. Unticked agents were found by their commission lines instead - both are real, which is why this table is the union of the two."
|
| 78 |
-
- key: commissioned
|
| 79 |
-
label: "Has commission lines"
|
| 80 |
-
type: checkbox
|
| 81 |
-
kind: data
|
| 82 |
-
- key: refreshed
|
| 83 |
-
label: "Refreshed"
|
| 84 |
-
type: date
|
| 85 |
-
kind: data
|
| 86 |
-
means: "When this row was last reconciled against Odoo."
|
| 87 |
-
|
| 88 |
-
ai_context: >
|
| 89 |
-
The sales-agent registry.
|
| 90 |
-
`flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
|
| 91 |
-
For an agent's BOOK use sales_lines/commission_lines with the agent dim.
|
|
|
|
| 1 |
+
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
+
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
+
#
|
| 4 |
+
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
+
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
+
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
+
# trained on a schema the product does not have.
|
| 8 |
+
key: odoo_agents
|
| 9 |
+
label: "Odoo agents"
|
| 10 |
+
entity: res.partner
|
| 11 |
+
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
+
grid: ut_odoo_agents
|
| 13 |
+
subject: "odoo:res.partner.agent"
|
| 14 |
+
grain: "one row per sales agent"
|
| 15 |
+
scope:
|
| 16 |
+
population: "a UNION of two disagreeing sources β partners carrying commission lines, and partners flagged res_partner.agent = TRUE"
|
| 17 |
+
why_union: "measured 2026-08-09: 16 carry commission lines, 17 carry the flag, and the union is 19 β either source alone silently drops real agents"
|
| 18 |
+
store:
|
| 19 |
+
table: res_partner
|
| 20 |
+
alias: p
|
| 21 |
+
# NO date_col β a registry is not a dated event stream. Stated rather than
|
| 22 |
+
# omitted, so its absence reads as a fact and not as an unfinished file.
|
| 23 |
+
|
| 24 |
+
# ββ W37-T12 / owner item 4 (R1) β THE LOOKBACK-MEASURE BINDING, the agent half of
|
| 25 |
+
# *"It should apply to Odoo agents database as well."* Same contract as
|
| 26 |
+
# `odoo_products.yml`: a FACT topic, and the dim of that topic which carries THIS
|
| 27 |
+
# entity's identity.
|
| 28 |
+
#
|
| 29 |
+
# ββ WHICH AGENT SOURCE, STATED β because there are THREE in this Odoo and they name
|
| 30 |
+
# DIFFERENT PEOPLE (`proto/P3-metric-catalog.md`: 9 agents carry route-1 revenue, 12
|
| 31 |
+
# carry commission lines, 17 carry the flag). This binds ROUTE 1, the CUSTOMER-MASTER
|
| 32 |
+
# BOOK: `sales_lines.agent` is `rp.agent_id`, the customer's assigned agent, so every
|
| 33 |
+
# order of that customer counts toward their agent. That is "whose book is this" and it
|
| 34 |
+
# is the right question for a column on the AGENT REGISTRY.
|
| 35 |
+
# β It is NOT commission. `account.invoice.line.agent` (topic `commission_lines`) is the
|
| 36 |
+
# per-INVOICE-LINE credited agent and answers a different question; `sales_lines.yml`'s
|
| 37 |
+
# own `agent` dim comment carries the full disagreement and says never to "fix" one by
|
| 38 |
+
# reading the other.
|
| 39 |
+
#
|
| 40 |
+
# β THE JOIN NEEDS NO NEW DIM, unlike the product side. `sales_lines.agent` declares a
|
| 41 |
+
# `name_col`, so `store_query` emits `agent_id` β which IS `res.partner.id`, which IS
|
| 42 |
+
# this grid's `odoo_id` identity. Product needed `product_code` because its grid keys on
|
| 43 |
+
# `default_code`; this one already keys on the same integer the fact topic groups by.
|
| 44 |
+
measures:
|
| 45 |
+
source: sales_lines
|
| 46 |
+
dim: agent
|
| 47 |
+
keys: [revenue, units, margin, cogs, margin_pct, asp, customers]
|
| 48 |
+
not_yet:
|
| 49 |
+
- key: orders / aov
|
| 50 |
+
cause: "`orders` lives on topic `sales_orders`, so under a `group_by` it is a CROSS-TOPIC measure and `semantic.store_query` refuses it (scalar-only). `aov` inherits the refusal through its denominator"
|
| 51 |
+
fix: "add an ORDER-COUNT metric to `sales_lines` itself β `count_distinct` over `l.order_id` β which answers the same question at this grain in one pass"
|
| 52 |
+
- key: commission_amount
|
| 53 |
+
cause: "the commission basis lives on `account.invoice.line.agent` (topic `commission_lines`), a different topic AND a different grain; `invoice_lines` deduplicates to at most one agent per line"
|
| 54 |
+
fix: "bind a SECOND measures block per source once the contract allows more than one, and label the columns so the two routes can never be read as the same number"
|
| 55 |
+
|
| 56 |
+
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 57 |
+
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 58 |
+
# from another topic; a `link` points at another database.
|
| 59 |
+
fields:
|
| 60 |
+
- key: agent
|
| 61 |
+
label: "Agent"
|
| 62 |
+
type: text
|
| 63 |
+
kind: data
|
| 64 |
+
- key: odoo_id
|
| 65 |
+
label: "Odoo ID"
|
| 66 |
+
type: int
|
| 67 |
+
kind: data
|
| 68 |
+
means: "The `res.partner` id. Also this row's id."
|
| 69 |
+
- key: agent_id
|
| 70 |
+
label: "Odoo agent id"
|
| 71 |
+
type: int
|
| 72 |
+
kind: data
|
| 73 |
+
- key: flagged
|
| 74 |
+
label: "Flagged in Odoo"
|
| 75 |
+
type: checkbox
|
| 76 |
+
kind: data
|
| 77 |
+
means: "Ticked = `res.partner.agent` is set. Unticked agents were found by their commission lines instead - both are real, which is why this table is the union of the two."
|
| 78 |
+
- key: commissioned
|
| 79 |
+
label: "Has commission lines"
|
| 80 |
+
type: checkbox
|
| 81 |
+
kind: data
|
| 82 |
+
- key: refreshed
|
| 83 |
+
label: "Refreshed"
|
| 84 |
+
type: date
|
| 85 |
+
kind: data
|
| 86 |
+
means: "When this row was last reconciled against Odoo."
|
| 87 |
+
|
| 88 |
+
ai_context: >
|
| 89 |
+
The sales-agent registry.
|
| 90 |
+
`flagged` and `commissioned` are the two SOURCES, kept as separate columns rather than merged, because they disagree and the disagreement is information.
|
| 91 |
+
For an agent's BOOK use sales_lines/commission_lines with the agent dim.
|
platform/model/topics/odoo_bills.yml
CHANGED
|
@@ -1,86 +1,86 @@
|
|
| 1 |
-
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
-
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
-
#
|
| 4 |
-
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
-
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
-
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
-
# trained on a schema the product does not have.
|
| 8 |
-
key: odoo_bills
|
| 9 |
-
label: "Odoo vendor bills"
|
| 10 |
-
entity: account.move
|
| 11 |
-
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
-
grid: ut_odoo_bills
|
| 13 |
-
subject: "odoo:account.move.vendor"
|
| 14 |
-
grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
|
| 15 |
-
scope:
|
| 16 |
-
population: "move_type in (in_invoice, in_refund) AND state = posted"
|
| 17 |
-
signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
|
| 18 |
-
store:
|
| 19 |
-
table: account_move
|
| 20 |
-
alias: m
|
| 21 |
-
date_col: "m.invoice_date"
|
| 22 |
-
dims:
|
| 23 |
-
vendor: {label: "Vendor"}
|
| 24 |
-
payment_state: {label: "Payment state"}
|
| 25 |
-
move_type: {label: "Document type"}
|
| 26 |
-
|
| 27 |
-
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 28 |
-
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 29 |
-
# from another topic; a `link` points at another database.
|
| 30 |
-
fields:
|
| 31 |
-
- key: bill_no
|
| 32 |
-
label: "Bill"
|
| 33 |
-
type: text
|
| 34 |
-
kind: data
|
| 35 |
-
- key: odoo_id
|
| 36 |
-
label: "Odoo ID"
|
| 37 |
-
type: int
|
| 38 |
-
kind: data
|
| 39 |
-
means: "The `account.move` id. Also this row's id."
|
| 40 |
-
- key: vendor
|
| 41 |
-
label: "Vendor"
|
| 42 |
-
type: text
|
| 43 |
-
kind: data
|
| 44 |
-
- key: vendor_id
|
| 45 |
-
label: "Odoo vendor id"
|
| 46 |
-
type: int
|
| 47 |
-
kind: data
|
| 48 |
-
- key: invoice_date
|
| 49 |
-
label: "Bill date"
|
| 50 |
-
type: date
|
| 51 |
-
kind: data
|
| 52 |
-
- key: due_date
|
| 53 |
-
label: "Due date"
|
| 54 |
-
type: date
|
| 55 |
-
kind: data
|
| 56 |
-
- key: amount_untaxed
|
| 57 |
-
label: "Billed $"
|
| 58 |
-
type: currency
|
| 59 |
-
kind: data
|
| 60 |
-
- key: residual
|
| 61 |
-
label: "Outstanding $"
|
| 62 |
-
type: currency
|
| 63 |
-
kind: data
|
| 64 |
-
- key: payment_state
|
| 65 |
-
label: "Payment state"
|
| 66 |
-
type: select
|
| 67 |
-
kind: data
|
| 68 |
-
- key: move_type
|
| 69 |
-
label: "Document"
|
| 70 |
-
type: select
|
| 71 |
-
kind: data
|
| 72 |
-
- key: vendor_link
|
| 73 |
-
label: "Vendor record"
|
| 74 |
-
type: link
|
| 75 |
-
kind: link
|
| 76 |
-
to_grid: ut_odoo_vendors
|
| 77 |
-
- key: refreshed
|
| 78 |
-
label: "Refreshed"
|
| 79 |
-
type: date
|
| 80 |
-
kind: data
|
| 81 |
-
means: "When this row was last reconciled against Odoo."
|
| 82 |
-
|
| 83 |
-
ai_context: >
|
| 84 |
-
Vendor bills at DOCUMENT grain β the payables side of account_move.
|
| 85 |
-
Use it for AP questions.
|
| 86 |
-
β The census found `ref` (the VENDOR's own invoice number), `journal_id` and `currency_id` populated in Odoo and absent from the mirror, so they cannot be answered from here yet.
|
|
|
|
| 1 |
+
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
+
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
+
#
|
| 4 |
+
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
+
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
+
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
+
# trained on a schema the product does not have.
|
| 8 |
+
key: odoo_bills
|
| 9 |
+
label: "Odoo vendor bills"
|
| 10 |
+
entity: account.move
|
| 11 |
+
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
+
grid: ut_odoo_bills
|
| 13 |
+
subject: "odoo:account.move.vendor"
|
| 14 |
+
grain: "one row per posted VENDOR bill or vendor credit note (document grain)"
|
| 15 |
+
scope:
|
| 16 |
+
population: "move_type in (in_invoice, in_refund) AND state = posted"
|
| 17 |
+
signs: "for payables the residual is negative on the Odoo side; take the absolute value for an AP figure"
|
| 18 |
+
store:
|
| 19 |
+
table: account_move
|
| 20 |
+
alias: m
|
| 21 |
+
date_col: "m.invoice_date"
|
| 22 |
+
dims:
|
| 23 |
+
vendor: {label: "Vendor"}
|
| 24 |
+
payment_state: {label: "Payment state"}
|
| 25 |
+
move_type: {label: "Document type"}
|
| 26 |
+
|
| 27 |
+
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 28 |
+
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 29 |
+
# from another topic; a `link` points at another database.
|
| 30 |
+
fields:
|
| 31 |
+
- key: bill_no
|
| 32 |
+
label: "Bill"
|
| 33 |
+
type: text
|
| 34 |
+
kind: data
|
| 35 |
+
- key: odoo_id
|
| 36 |
+
label: "Odoo ID"
|
| 37 |
+
type: int
|
| 38 |
+
kind: data
|
| 39 |
+
means: "The `account.move` id. Also this row's id."
|
| 40 |
+
- key: vendor
|
| 41 |
+
label: "Vendor"
|
| 42 |
+
type: text
|
| 43 |
+
kind: data
|
| 44 |
+
- key: vendor_id
|
| 45 |
+
label: "Odoo vendor id"
|
| 46 |
+
type: int
|
| 47 |
+
kind: data
|
| 48 |
+
- key: invoice_date
|
| 49 |
+
label: "Bill date"
|
| 50 |
+
type: date
|
| 51 |
+
kind: data
|
| 52 |
+
- key: due_date
|
| 53 |
+
label: "Due date"
|
| 54 |
+
type: date
|
| 55 |
+
kind: data
|
| 56 |
+
- key: amount_untaxed
|
| 57 |
+
label: "Billed $"
|
| 58 |
+
type: currency
|
| 59 |
+
kind: data
|
| 60 |
+
- key: residual
|
| 61 |
+
label: "Outstanding $"
|
| 62 |
+
type: currency
|
| 63 |
+
kind: data
|
| 64 |
+
- key: payment_state
|
| 65 |
+
label: "Payment state"
|
| 66 |
+
type: select
|
| 67 |
+
kind: data
|
| 68 |
+
- key: move_type
|
| 69 |
+
label: "Document"
|
| 70 |
+
type: select
|
| 71 |
+
kind: data
|
| 72 |
+
- key: vendor_link
|
| 73 |
+
label: "Vendor record"
|
| 74 |
+
type: link
|
| 75 |
+
kind: link
|
| 76 |
+
to_grid: ut_odoo_vendors
|
| 77 |
+
- key: refreshed
|
| 78 |
+
label: "Refreshed"
|
| 79 |
+
type: date
|
| 80 |
+
kind: data
|
| 81 |
+
means: "When this row was last reconciled against Odoo."
|
| 82 |
+
|
| 83 |
+
ai_context: >
|
| 84 |
+
Vendor bills at DOCUMENT grain β the payables side of account_move.
|
| 85 |
+
Use it for AP questions.
|
| 86 |
+
β The census found `ref` (the VENDOR's own invoice number), `journal_id` and `currency_id` populated in Odoo and absent from the mirror, so they cannot be answered from here yet.
|
platform/model/topics/odoo_invoices.yml
CHANGED
|
@@ -1,98 +1,98 @@
|
|
| 1 |
-
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
-
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
-
#
|
| 4 |
-
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
-
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
-
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
-
# trained on a schema the product does not have.
|
| 8 |
-
key: odoo_invoices
|
| 9 |
-
label: "Odoo invoices"
|
| 10 |
-
entity: account.move
|
| 11 |
-
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
-
grid: ut_odoo_invoices
|
| 13 |
-
subject: "odoo:account.move.customer"
|
| 14 |
-
grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
|
| 15 |
-
scope:
|
| 16 |
-
population: "move_type in (out_invoice, out_refund) AND state = posted"
|
| 17 |
-
signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
|
| 18 |
-
store:
|
| 19 |
-
table: account_move
|
| 20 |
-
alias: m
|
| 21 |
-
date_col: "m.invoice_date"
|
| 22 |
-
dims:
|
| 23 |
-
customer: {label: "Customer"}
|
| 24 |
-
payment_state: {label: "Payment state"}
|
| 25 |
-
move_type: {label: "Document type"}
|
| 26 |
-
|
| 27 |
-
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 28 |
-
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 29 |
-
# from another topic; a `link` points at another database.
|
| 30 |
-
fields:
|
| 31 |
-
- key: invoice_no
|
| 32 |
-
label: "Invoice"
|
| 33 |
-
type: text
|
| 34 |
-
kind: data
|
| 35 |
-
- key: odoo_id
|
| 36 |
-
label: "Odoo ID"
|
| 37 |
-
type: int
|
| 38 |
-
kind: data
|
| 39 |
-
means: "The `account.move` id. Also this row's id."
|
| 40 |
-
- key: customer
|
| 41 |
-
label: "Customer"
|
| 42 |
-
type: text
|
| 43 |
-
kind: data
|
| 44 |
-
- key: partner_id
|
| 45 |
-
label: "Odoo partner id"
|
| 46 |
-
type: int
|
| 47 |
-
kind: data
|
| 48 |
-
- key: invoice_date
|
| 49 |
-
label: "Invoice date"
|
| 50 |
-
type: date
|
| 51 |
-
kind: data
|
| 52 |
-
- key: due_date
|
| 53 |
-
label: "Due date"
|
| 54 |
-
type: date
|
| 55 |
-
kind: data
|
| 56 |
-
- key: residual
|
| 57 |
-
label: "Outstanding $"
|
| 58 |
-
type: currency
|
| 59 |
-
kind: data
|
| 60 |
-
means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
|
| 61 |
-
- key: amount_untaxed
|
| 62 |
-
label: "Invoiced $"
|
| 63 |
-
type: currency
|
| 64 |
-
kind: data
|
| 65 |
-
- key: payment_state
|
| 66 |
-
label: "Payment state"
|
| 67 |
-
type: select
|
| 68 |
-
kind: data
|
| 69 |
-
- key: move_type
|
| 70 |
-
label: "Document"
|
| 71 |
-
type: select
|
| 72 |
-
kind: data
|
| 73 |
-
- key: wholesale_scope
|
| 74 |
-
label: "In wholesale scope"
|
| 75 |
-
type: checkbox
|
| 76 |
-
kind: data
|
| 77 |
-
means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
|
| 78 |
-
- key: origin_order
|
| 79 |
-
label: "Source order"
|
| 80 |
-
type: text
|
| 81 |
-
kind: data
|
| 82 |
-
means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
|
| 83 |
-
- key: order_link
|
| 84 |
-
label: "Order record"
|
| 85 |
-
type: link
|
| 86 |
-
kind: link
|
| 87 |
-
to_grid: ut_odoo_orders
|
| 88 |
-
- key: refreshed
|
| 89 |
-
label: "Refreshed"
|
| 90 |
-
type: date
|
| 91 |
-
kind: data
|
| 92 |
-
means: "When this row was last reconciled against Odoo."
|
| 93 |
-
|
| 94 |
-
ai_context: >
|
| 95 |
-
Customer invoices at DOCUMENT grain β one row per invoice, not per line.
|
| 96 |
-
Use it for AR questions: what is open, what is overdue, what was invoiced.
|
| 97 |
-
For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
|
| 98 |
-
`origin_order` is the single stored key that joins an invoice back to the order it was raised from.
|
|
|
|
| 1 |
+
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
+
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
+
#
|
| 4 |
+
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
+
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
+
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
+
# trained on a schema the product does not have.
|
| 8 |
+
key: odoo_invoices
|
| 9 |
+
label: "Odoo invoices"
|
| 10 |
+
entity: account.move
|
| 11 |
+
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
+
grid: ut_odoo_invoices
|
| 13 |
+
subject: "odoo:account.move.customer"
|
| 14 |
+
grain: "one row per posted CUSTOMER invoice or credit note (document grain)"
|
| 15 |
+
scope:
|
| 16 |
+
population: "move_type in (out_invoice, out_refund) AND state = posted"
|
| 17 |
+
signs: "amount_residual_signed is POSITIVE for an invoice and NEGATIVE for a credit note, so summing it nets the credit notes correctly"
|
| 18 |
+
store:
|
| 19 |
+
table: account_move
|
| 20 |
+
alias: m
|
| 21 |
+
date_col: "m.invoice_date"
|
| 22 |
+
dims:
|
| 23 |
+
customer: {label: "Customer"}
|
| 24 |
+
payment_state: {label: "Payment state"}
|
| 25 |
+
move_type: {label: "Document type"}
|
| 26 |
+
|
| 27 |
+
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 28 |
+
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 29 |
+
# from another topic; a `link` points at another database.
|
| 30 |
+
fields:
|
| 31 |
+
- key: invoice_no
|
| 32 |
+
label: "Invoice"
|
| 33 |
+
type: text
|
| 34 |
+
kind: data
|
| 35 |
+
- key: odoo_id
|
| 36 |
+
label: "Odoo ID"
|
| 37 |
+
type: int
|
| 38 |
+
kind: data
|
| 39 |
+
means: "The `account.move` id. Also this row's id."
|
| 40 |
+
- key: customer
|
| 41 |
+
label: "Customer"
|
| 42 |
+
type: text
|
| 43 |
+
kind: data
|
| 44 |
+
- key: partner_id
|
| 45 |
+
label: "Odoo partner id"
|
| 46 |
+
type: int
|
| 47 |
+
kind: data
|
| 48 |
+
- key: invoice_date
|
| 49 |
+
label: "Invoice date"
|
| 50 |
+
type: date
|
| 51 |
+
kind: data
|
| 52 |
+
- key: due_date
|
| 53 |
+
label: "Due date"
|
| 54 |
+
type: date
|
| 55 |
+
kind: data
|
| 56 |
+
- key: residual
|
| 57 |
+
label: "Outstanding $"
|
| 58 |
+
type: currency
|
| 59 |
+
kind: data
|
| 60 |
+
means: "Odoo's signed residual. Exactly 0 on every settled document, which is why AR rollups need no filter."
|
| 61 |
+
- key: amount_untaxed
|
| 62 |
+
label: "Invoiced $"
|
| 63 |
+
type: currency
|
| 64 |
+
kind: data
|
| 65 |
+
- key: payment_state
|
| 66 |
+
label: "Payment state"
|
| 67 |
+
type: select
|
| 68 |
+
kind: data
|
| 69 |
+
- key: move_type
|
| 70 |
+
label: "Document"
|
| 71 |
+
type: select
|
| 72 |
+
kind: data
|
| 73 |
+
- key: wholesale_scope
|
| 74 |
+
label: "In wholesale scope"
|
| 75 |
+
type: checkbox
|
| 76 |
+
kind: data
|
| 77 |
+
means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
|
| 78 |
+
- key: origin_order
|
| 79 |
+
label: "Source order"
|
| 80 |
+
type: text
|
| 81 |
+
kind: data
|
| 82 |
+
means: "Odoo's `invoice_origin` - usually the order name, sometimes blank."
|
| 83 |
+
- key: order_link
|
| 84 |
+
label: "Order record"
|
| 85 |
+
type: link
|
| 86 |
+
kind: link
|
| 87 |
+
to_grid: ut_odoo_orders
|
| 88 |
+
- key: refreshed
|
| 89 |
+
label: "Refreshed"
|
| 90 |
+
type: date
|
| 91 |
+
kind: data
|
| 92 |
+
means: "When this row was last reconciled against Odoo."
|
| 93 |
+
|
| 94 |
+
ai_context: >
|
| 95 |
+
Customer invoices at DOCUMENT grain β one row per invoice, not per line.
|
| 96 |
+
Use it for AR questions: what is open, what is overdue, what was invoiced.
|
| 97 |
+
For anything at product or line grain use invoice_lines; for the reconciled receivables view use receivables.
|
| 98 |
+
`origin_order` is the single stored key that joins an invoice back to the order it was raised from.
|
platform/model/topics/odoo_orders.yml
CHANGED
|
@@ -1,87 +1,87 @@
|
|
| 1 |
-
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
-
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
-
#
|
| 4 |
-
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
-
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
-
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
-
# trained on a schema the product does not have.
|
| 8 |
-
key: odoo_orders
|
| 9 |
-
label: "Odoo orders"
|
| 10 |
-
entity: sale.order
|
| 11 |
-
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
-
grid: ut_odoo_orders
|
| 13 |
-
subject: "odoo:sale.order"
|
| 14 |
-
grain: "one row per confirmed sales order (document grain)"
|
| 15 |
-
scope:
|
| 16 |
-
population: "state in (sale, done) β quotations and cancellations excluded"
|
| 17 |
-
vs_sales_orders: "β DISTINCT from the `sales_orders` topic: that one is the wholesale-scoped analytical view (teams 5/6, house accounts excluded); THIS one is the registry a person opens as a grid, and carries the row set the app shows"
|
| 18 |
-
store:
|
| 19 |
-
table: sale_order
|
| 20 |
-
alias: o
|
| 21 |
-
date_col: "o.date_order"
|
| 22 |
-
dims:
|
| 23 |
-
customer: {label: "Customer"}
|
| 24 |
-
team: {label: "Business unit"}
|
| 25 |
-
state: {label: "State"}
|
| 26 |
-
invoice_status: {label: "Invoice status"}
|
| 27 |
-
|
| 28 |
-
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 29 |
-
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 30 |
-
# from another topic; a `link` points at another database.
|
| 31 |
-
fields:
|
| 32 |
-
- key: order_no
|
| 33 |
-
label: "Order"
|
| 34 |
-
type: text
|
| 35 |
-
kind: data
|
| 36 |
-
- key: odoo_id
|
| 37 |
-
label: "Odoo ID"
|
| 38 |
-
type: int
|
| 39 |
-
kind: data
|
| 40 |
-
means: "The `sale.order` id. Also this row's id."
|
| 41 |
-
- key: customer
|
| 42 |
-
label: "Customer"
|
| 43 |
-
type: text
|
| 44 |
-
kind: data
|
| 45 |
-
- key: partner_id
|
| 46 |
-
label: "Odoo partner id"
|
| 47 |
-
type: int
|
| 48 |
-
kind: data
|
| 49 |
-
- key: order_date
|
| 50 |
-
label: "Order date"
|
| 51 |
-
type: date
|
| 52 |
-
kind: data
|
| 53 |
-
- key: amount_untaxed
|
| 54 |
-
label: "Order $"
|
| 55 |
-
type: currency
|
| 56 |
-
kind: data
|
| 57 |
-
- key: team
|
| 58 |
-
label: "Business unit"
|
| 59 |
-
type: select
|
| 60 |
-
kind: data
|
| 61 |
-
- key: state
|
| 62 |
-
label: "State"
|
| 63 |
-
type: select
|
| 64 |
-
kind: data
|
| 65 |
-
- key: invoice_status
|
| 66 |
-
label: "Invoice status"
|
| 67 |
-
type: select
|
| 68 |
-
kind: data
|
| 69 |
-
- key: wholesale_scope
|
| 70 |
-
label: "In wholesale scope"
|
| 71 |
-
type: checkbox
|
| 72 |
-
kind: data
|
| 73 |
-
means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
|
| 74 |
-
- key: invoices
|
| 75 |
-
label: "Invoices"
|
| 76 |
-
type: link
|
| 77 |
-
kind: link
|
| 78 |
-
to_grid: ut_odoo_invoices
|
| 79 |
-
- key: refreshed
|
| 80 |
-
label: "Refreshed"
|
| 81 |
-
type: date
|
| 82 |
-
kind: data
|
| 83 |
-
means: "When this row was last reconciled against Odoo."
|
| 84 |
-
|
| 85 |
-
ai_context: >
|
| 86 |
-
Sales orders at DOCUMENT grain, as the app's grid shows them.
|
| 87 |
-
β If you are asked for revenue, prefer `sales_lines` (line grain, wholesale scope) or `sales_orders` β this topic exists to describe the ORDER RECORD a person can open, and its scope is the grid's, not the analytical model's.
|
|
|
|
| 1 |
+
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
+
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
+
#
|
| 4 |
+
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
+
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
+
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
+
# trained on a schema the product does not have.
|
| 8 |
+
key: odoo_orders
|
| 9 |
+
label: "Odoo orders"
|
| 10 |
+
entity: sale.order
|
| 11 |
+
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
+
grid: ut_odoo_orders
|
| 13 |
+
subject: "odoo:sale.order"
|
| 14 |
+
grain: "one row per confirmed sales order (document grain)"
|
| 15 |
+
scope:
|
| 16 |
+
population: "state in (sale, done) β quotations and cancellations excluded"
|
| 17 |
+
vs_sales_orders: "β DISTINCT from the `sales_orders` topic: that one is the wholesale-scoped analytical view (teams 5/6, house accounts excluded); THIS one is the registry a person opens as a grid, and carries the row set the app shows"
|
| 18 |
+
store:
|
| 19 |
+
table: sale_order
|
| 20 |
+
alias: o
|
| 21 |
+
date_col: "o.date_order"
|
| 22 |
+
dims:
|
| 23 |
+
customer: {label: "Customer"}
|
| 24 |
+
team: {label: "Business unit"}
|
| 25 |
+
state: {label: "State"}
|
| 26 |
+
invoice_status: {label: "Invoice status"}
|
| 27 |
+
|
| 28 |
+
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 29 |
+
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 30 |
+
# from another topic; a `link` points at another database.
|
| 31 |
+
fields:
|
| 32 |
+
- key: order_no
|
| 33 |
+
label: "Order"
|
| 34 |
+
type: text
|
| 35 |
+
kind: data
|
| 36 |
+
- key: odoo_id
|
| 37 |
+
label: "Odoo ID"
|
| 38 |
+
type: int
|
| 39 |
+
kind: data
|
| 40 |
+
means: "The `sale.order` id. Also this row's id."
|
| 41 |
+
- key: customer
|
| 42 |
+
label: "Customer"
|
| 43 |
+
type: text
|
| 44 |
+
kind: data
|
| 45 |
+
- key: partner_id
|
| 46 |
+
label: "Odoo partner id"
|
| 47 |
+
type: int
|
| 48 |
+
kind: data
|
| 49 |
+
- key: order_date
|
| 50 |
+
label: "Order date"
|
| 51 |
+
type: date
|
| 52 |
+
kind: data
|
| 53 |
+
- key: amount_untaxed
|
| 54 |
+
label: "Order $"
|
| 55 |
+
type: currency
|
| 56 |
+
kind: data
|
| 57 |
+
- key: team
|
| 58 |
+
label: "Business unit"
|
| 59 |
+
type: select
|
| 60 |
+
kind: data
|
| 61 |
+
- key: state
|
| 62 |
+
label: "State"
|
| 63 |
+
type: select
|
| 64 |
+
kind: data
|
| 65 |
+
- key: invoice_status
|
| 66 |
+
label: "Invoice status"
|
| 67 |
+
type: select
|
| 68 |
+
kind: data
|
| 69 |
+
- key: wholesale_scope
|
| 70 |
+
label: "In wholesale scope"
|
| 71 |
+
type: checkbox
|
| 72 |
+
kind: data
|
| 73 |
+
means: "Unticked = the GIFTWARE DEALS / Amazon channel, which every wholesale metric in this product excludes. The row is kept so no Odoo id is missing; filter on this column to reconcile against the AR page."
|
| 74 |
+
- key: invoices
|
| 75 |
+
label: "Invoices"
|
| 76 |
+
type: link
|
| 77 |
+
kind: link
|
| 78 |
+
to_grid: ut_odoo_invoices
|
| 79 |
+
- key: refreshed
|
| 80 |
+
label: "Refreshed"
|
| 81 |
+
type: date
|
| 82 |
+
kind: data
|
| 83 |
+
means: "When this row was last reconciled against Odoo."
|
| 84 |
+
|
| 85 |
+
ai_context: >
|
| 86 |
+
Sales orders at DOCUMENT grain, as the app's grid shows them.
|
| 87 |
+
β If you are asked for revenue, prefer `sales_lines` (line grain, wholesale scope) or `sales_orders` β this topic exists to describe the ORDER RECORD a person can open, and its scope is the grid's, not the analytical model's.
|
platform/model/topics/odoo_vendors.yml
CHANGED
|
@@ -1,103 +1,103 @@
|
|
| 1 |
-
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
-
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
-
#
|
| 4 |
-
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
-
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
-
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
-
# trained on a schema the product does not have.
|
| 8 |
-
key: odoo_vendors
|
| 9 |
-
label: "Odoo vendors"
|
| 10 |
-
entity: res.partner
|
| 11 |
-
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
-
grid: ut_odoo_vendors
|
| 13 |
-
subject: "odoo:res.partner.vendor"
|
| 14 |
-
grain: "one row per partner we have posted a vendor bill to"
|
| 15 |
-
scope:
|
| 16 |
-
population: "DERIVED FROM THE BILLS β a partner with no posted vendor bill has no payable history to show, so the bill is the population"
|
| 17 |
-
asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
|
| 18 |
-
overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
|
| 19 |
-
store:
|
| 20 |
-
table: res_partner
|
| 21 |
-
alias: p
|
| 22 |
-
# NO date_col β a registry is not a dated event stream. Stated rather than
|
| 23 |
-
# omitted, so its absence reads as a fact and not as an unfinished file.
|
| 24 |
-
dims:
|
| 25 |
-
country: {label: "Country"}
|
| 26 |
-
|
| 27 |
-
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 28 |
-
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 29 |
-
# from another topic; a `link` points at another database.
|
| 30 |
-
fields:
|
| 31 |
-
- key: vendor
|
| 32 |
-
label: "Vendor"
|
| 33 |
-
type: text
|
| 34 |
-
kind: data
|
| 35 |
-
- key: odoo_id
|
| 36 |
-
label: "Odoo ID"
|
| 37 |
-
type: int
|
| 38 |
-
kind: data
|
| 39 |
-
means: "The `res.partner` id. Also this row's id."
|
| 40 |
-
- key: vendor_id
|
| 41 |
-
label: "Odoo vendor id"
|
| 42 |
-
type: int
|
| 43 |
-
kind: data
|
| 44 |
-
- key: country
|
| 45 |
-
label: "Country"
|
| 46 |
-
type: text
|
| 47 |
-
kind: data
|
| 48 |
-
- key: email
|
| 49 |
-
label: "Email"
|
| 50 |
-
type: text
|
| 51 |
-
kind: data
|
| 52 |
-
- key: phone
|
| 53 |
-
label: "Phone"
|
| 54 |
-
type: text
|
| 55 |
-
kind: data
|
| 56 |
-
- key: mobile
|
| 57 |
-
label: "Mobile"
|
| 58 |
-
type: text
|
| 59 |
-
kind: data
|
| 60 |
-
- key: vat
|
| 61 |
-
label: "Tax ID"
|
| 62 |
-
type: text
|
| 63 |
-
kind: data
|
| 64 |
-
means: "Odoo `vat` β the vendor's tax/VAT registration number."
|
| 65 |
-
- key: vendor_ref
|
| 66 |
-
label: "Vendor reference"
|
| 67 |
-
type: text
|
| 68 |
-
kind: data
|
| 69 |
-
means: "Odoo `res.partner.ref` β our internal reference for this vendor."
|
| 70 |
-
- key: website
|
| 71 |
-
label: "Website"
|
| 72 |
-
type: url
|
| 73 |
-
kind: data
|
| 74 |
-
- key: street
|
| 75 |
-
label: "Street"
|
| 76 |
-
type: text
|
| 77 |
-
kind: data
|
| 78 |
-
- key: street2
|
| 79 |
-
label: "Street 2"
|
| 80 |
-
type: text
|
| 81 |
-
kind: data
|
| 82 |
-
- key: city
|
| 83 |
-
label: "City"
|
| 84 |
-
type: text
|
| 85 |
-
kind: data
|
| 86 |
-
- key: zip
|
| 87 |
-
label: "ZIP"
|
| 88 |
-
type: text
|
| 89 |
-
kind: data
|
| 90 |
-
- key: bills
|
| 91 |
-
label: "Bills"
|
| 92 |
-
type: link
|
| 93 |
-
kind: link
|
| 94 |
-
to_grid: ut_odoo_bills
|
| 95 |
-
- key: refreshed
|
| 96 |
-
label: "Refreshed"
|
| 97 |
-
type: date
|
| 98 |
-
kind: data
|
| 99 |
-
means: "When this row was last reconciled against Odoo."
|
| 100 |
-
|
| 101 |
-
ai_context: >
|
| 102 |
-
The vendor/supplier registry, with contact and tax identity (W33-T48 widened it from 5 columns to 15 after a census found 76 populated fields on the underlying partner)
|
| 103 |
-
β The contact columns are SPARSE by nature β measured 65/393 with an email, 13/393 with a tax id β so 'blank' means Odoo has no value, never that the sync failed.
|
|
|
|
| 1 |
+
# ββ W33-T49 (owner item 13) β an ENTITY topic: the semantic layer can finally see
|
| 2 |
+
# the databases a person actually opens, not only the line and document grains.
|
| 3 |
+
#
|
| 4 |
+
# β THE `fields:` BLOCK IS GENERATED FROM THE GRID'S OWN FIELD CONTRACT
|
| 5 |
+
# and is held to it by `verify_query.py::section_entity_topics`. Do not hand-edit a
|
| 6 |
+
# field row: add the column to the grid contract and re-emit, or the agent is being
|
| 7 |
+
# trained on a schema the product does not have.
|
| 8 |
+
key: odoo_vendors
|
| 9 |
+
label: "Odoo vendors"
|
| 10 |
+
entity: res.partner
|
| 11 |
+
# The database this topic DESCRIBES β the same store key the nav opens (W33-T46).
|
| 12 |
+
grid: ut_odoo_vendors
|
| 13 |
+
subject: "odoo:res.partner.vendor"
|
| 14 |
+
grain: "one row per partner we have posted a vendor bill to"
|
| 15 |
+
scope:
|
| 16 |
+
population: "DERIVED FROM THE BILLS β a partner with no posted vendor bill has no payable history to show, so the bill is the population"
|
| 17 |
+
asymmetry: "deliberately unlike odoo_customers, which is NOT derived from its documents; there is no second document universe for vendors"
|
| 18 |
+
overlap: "measured: only 9 of the vendors also appear in the customer population, so a vendor is not a customer row"
|
| 19 |
+
store:
|
| 20 |
+
table: res_partner
|
| 21 |
+
alias: p
|
| 22 |
+
# NO date_col β a registry is not a dated event stream. Stated rather than
|
| 23 |
+
# omitted, so its absence reads as a fact and not as an unfinished file.
|
| 24 |
+
dims:
|
| 25 |
+
country: {label: "Country"}
|
| 26 |
+
|
| 27 |
+
# key / label / type / kind, derived from the grid contract. `kind` says where the
|
| 28 |
+
# value COMES FROM: a `data` column is stored on the row; a `rollup` is computed
|
| 29 |
+
# from another topic; a `link` points at another database.
|
| 30 |
+
fields:
|
| 31 |
+
- key: vendor
|
| 32 |
+
label: "Vendor"
|
| 33 |
+
type: text
|
| 34 |
+
kind: data
|
| 35 |
+
- key: odoo_id
|
| 36 |
+
label: "Odoo ID"
|
| 37 |
+
type: int
|
| 38 |
+
kind: data
|
| 39 |
+
means: "The `res.partner` id. Also this row's id."
|
| 40 |
+
- key: vendor_id
|
| 41 |
+
label: "Odoo vendor id"
|
| 42 |
+
type: int
|
| 43 |
+
kind: data
|
| 44 |
+
- key: country
|
| 45 |
+
label: "Country"
|
| 46 |
+
type: text
|
| 47 |
+
kind: data
|
| 48 |
+
- key: email
|
| 49 |
+
label: "Email"
|
| 50 |
+
type: text
|
| 51 |
+
kind: data
|
| 52 |
+
- key: phone
|
| 53 |
+
label: "Phone"
|
| 54 |
+
type: text
|
| 55 |
+
kind: data
|
| 56 |
+
- key: mobile
|
| 57 |
+
label: "Mobile"
|
| 58 |
+
type: text
|
| 59 |
+
kind: data
|
| 60 |
+
- key: vat
|
| 61 |
+
label: "Tax ID"
|
| 62 |
+
type: text
|
| 63 |
+
kind: data
|
| 64 |
+
means: "Odoo `vat` β the vendor's tax/VAT registration number."
|
| 65 |
+
- key: vendor_ref
|
| 66 |
+
label: "Vendor reference"
|
| 67 |
+
type: text
|
| 68 |
+
kind: data
|
| 69 |
+
means: "Odoo `res.partner.ref` β our internal reference for this vendor."
|
| 70 |
+
- key: website
|
| 71 |
+
label: "Website"
|
| 72 |
+
type: url
|
| 73 |
+
kind: data
|
| 74 |
+
- key: street
|
| 75 |
+
label: "Street"
|
| 76 |
+
type: text
|
| 77 |
+
kind: data
|
| 78 |
+
- key: street2
|
| 79 |
+
label: "Street 2"
|
| 80 |
+
type: text
|
| 81 |
+
kind: data
|
| 82 |
+
- key: city
|
| 83 |
+
label: "City"
|
| 84 |
+
type: text
|
| 85 |
+
kind: data
|
| 86 |
+
- key: zip
|
| 87 |
+
label: "ZIP"
|
| 88 |
+
type: text
|
| 89 |
+
kind: data
|
| 90 |
+
- key: bills
|
| 91 |
+
label: "Bills"
|
| 92 |
+
type: link
|
| 93 |
+
kind: link
|
| 94 |
+
to_grid: ut_odoo_bills
|
| 95 |
+
- key: refreshed
|
| 96 |
+
label: "Refreshed"
|
| 97 |
+
type: date
|
| 98 |
+
kind: data
|
| 99 |
+
means: "When this row was last reconciled against Odoo."
|
| 100 |
+
|
| 101 |
+
ai_context: >
|
| 102 |
+
The vendor/supplier registry, with contact and tax identity (W33-T48 widened it from 5 columns to 15 after a census found 76 populated fields on the underlying partner)
|
| 103 |
+
β The contact columns are SPARSE by nature β measured 65/393 with an email, 13/393 with a tax id β so 'blank' means Odoo has no value, never that the sync failed.
|
platform/modules/agent.py
CHANGED
|
@@ -1,385 +1,385 @@
|
|
| 1 |
-
"""Agent module β per-agent (res.partner.agent_ids) analytics.
|
| 2 |
-
|
| 3 |
-
An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
|
| 4 |
-
module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
|
| 5 |
-
with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
|
| 6 |
-
trend, returns, top SKUs (with profit/order) and the FULL customer list β INCLUDING inactive
|
| 7 |
-
accounts (no recent orders) so a rep sees who they've stopped selling to.
|
| 8 |
-
|
| 9 |
-
Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
|
| 10 |
-
so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
|
| 11 |
-
everything else is BU-filterable via team_id.
|
| 12 |
-
"""
|
| 13 |
-
import sys
|
| 14 |
-
import datetime as dt
|
| 15 |
-
from pathlib import Path
|
| 16 |
-
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
| 17 |
-
import core.odoo as O
|
| 18 |
-
import core.periods as P
|
| 19 |
-
import modules.sales as sales_mod
|
| 20 |
-
import modules.customers as cust_mod
|
| 21 |
-
|
| 22 |
-
|
| 23 |
-
def options(t=None, team_id=None):
|
| 24 |
-
"""Agent names with book activity β for the page/drawer picker."""
|
| 25 |
-
return cust_mod.agent_options(t, team_id)
|
| 26 |
-
|
| 27 |
-
|
| 28 |
-
def _book(name):
|
| 29 |
-
"""frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
|
| 30 |
-
return cust_mod.agent_partner_ids(name)
|
| 31 |
-
|
| 32 |
-
|
| 33 |
-
def _rev(date_from, date_to, team_id, book):
|
| 34 |
-
return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
|
| 35 |
-
'amount_untaxed')
|
| 36 |
-
|
| 37 |
-
|
| 38 |
-
def _orders(date_from, date_to, team_id, book):
|
| 39 |
-
return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
|
| 40 |
-
|
| 41 |
-
|
| 42 |
-
def _custs(date_from, date_to, team_id, book):
|
| 43 |
-
return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
|
| 44 |
-
'partner_id')
|
| 45 |
-
|
| 46 |
-
|
| 47 |
-
# ------------------------------------------------------------ period scorecard (custom dating)
|
| 48 |
-
# Today / WTD / Last week / MTD / QTD / YTD β each carries its window so the UI can decompose it
|
| 49 |
-
# and so "what did this agent sell this/last week" is a click, not a date-math exercise.
|
| 50 |
-
_PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
|
| 51 |
-
('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
|
| 52 |
-
|
| 53 |
-
|
| 54 |
-
def _window(key, t):
|
| 55 |
-
if key == 'today':
|
| 56 |
-
return P._d(t), P._d(t)
|
| 57 |
-
if key == 'lwk': # the full prior MonβSun week
|
| 58 |
-
f, _tt = P.wtd(t)
|
| 59 |
-
start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
|
| 60 |
-
return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
|
| 61 |
-
return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
|
| 62 |
-
|
| 63 |
-
|
| 64 |
-
def scorecard(name, t=None, team_id=None):
|
| 65 |
-
"""Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
|
| 66 |
-
t = t or P.today()
|
| 67 |
-
book = _book(name)
|
| 68 |
-
out = []
|
| 69 |
-
for label, key in _PERIODS:
|
| 70 |
-
f, tt = _window(key, t)
|
| 71 |
-
wk = key in ('today', 'wtd', 'lwk') # weekday-align the short windows' LY compare
|
| 72 |
-
cf, ct = P.shift_year(f, tt, weeks=wk)
|
| 73 |
-
rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
|
| 74 |
-
out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
|
| 75 |
-
'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
|
| 76 |
-
'orders': _orders(f, tt, team_id, book)})
|
| 77 |
-
return out
|
| 78 |
-
|
| 79 |
-
|
| 80 |
-
def headline(name, date_from, date_to, team_id=None):
|
| 81 |
-
"""Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
|
| 82 |
-
active customers, AOV and returns $ / return rate."""
|
| 83 |
-
book = _book(name)
|
| 84 |
-
cf, ct = P.shift_year(date_from, date_to, weeks=False)
|
| 85 |
-
rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
|
| 86 |
-
orders = _orders(date_from, date_to, team_id, book)
|
| 87 |
-
ret = sales_mod._returns_amt(date_from, date_to, book)
|
| 88 |
-
return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
|
| 89 |
-
'revenue': rev, 'revenue_ly': rev_ly,
|
| 90 |
-
'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
|
| 91 |
-
'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
|
| 92 |
-
'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
|
| 93 |
-
|
| 94 |
-
|
| 95 |
-
# ------------------------------------------------------------ sales trend
|
| 96 |
-
def _book_monthly_rev(book, date_from, date_to, team_id=None):
|
| 97 |
-
g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
|
| 98 |
-
['amount_untaxed:sum'], ['date_order:month'], lazy=False)
|
| 99 |
-
out = {}
|
| 100 |
-
for r in g:
|
| 101 |
-
ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
|
| 102 |
-
if ym:
|
| 103 |
-
out[ym] = r.get('amount_untaxed') or 0.0
|
| 104 |
-
return out
|
| 105 |
-
|
| 106 |
-
|
| 107 |
-
def monthly(name, n=13, t=None, team_id=None):
|
| 108 |
-
"""Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
|
| 109 |
-
t = t or P.today()
|
| 110 |
-
book = _book(name)
|
| 111 |
-
mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
|
| 112 |
-
rows = []
|
| 113 |
-
for ym, _s, _e in P.month_starts(n, t):
|
| 114 |
-
y, m = int(ym[:4]) - 1, int(ym[5:7])
|
| 115 |
-
this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
|
| 116 |
-
rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
|
| 117 |
-
return rows
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
# ------------------------------------------------------------ full customer book (incl. inactive)
|
| 121 |
-
def customers(name, t=None, team_id=None):
|
| 122 |
-
"""EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) β those
|
| 123 |
-
show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
|
| 124 |
-
carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
|
| 125 |
-
t = t or P.today()
|
| 126 |
-
book = _book(name)
|
| 127 |
-
yf, yt = P.ytd(t)
|
| 128 |
-
lf, lt = P.ytd_last_year(t)
|
| 129 |
-
this = cust_mod._cust_rev(yf, yt, team_id, book)
|
| 130 |
-
last = cust_mod._cust_rev(lf, lt, team_id, book)
|
| 131 |
-
lastord = cust_mod._last_order_dates(None, None, team_id, book) # all-time last order = recency
|
| 132 |
-
ids = list(book) if book is not None else list(set(this) | set(last))
|
| 133 |
-
attrs = cust_mod._partner_attrs(set(ids))
|
| 134 |
-
namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
|
| 135 |
-
rows = []
|
| 136 |
-
for p in ids:
|
| 137 |
-
tr = this.get(p, {}).get('rev', 0.0)
|
| 138 |
-
lr = last.get(p, {}).get('rev', 0.0)
|
| 139 |
-
a = attrs.get(p, {})
|
| 140 |
-
lo = lastord.get(p, '')
|
| 141 |
-
recency = (t - dt.date.fromisoformat(lo)).days if lo else None
|
| 142 |
-
status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
|
| 143 |
-
rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
|
| 144 |
-
'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
|
| 145 |
-
'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
|
| 146 |
-
'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
|
| 147 |
-
'agent': a.get('agent', name)})
|
| 148 |
-
rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
|
| 149 |
-
return rows
|
| 150 |
-
|
| 151 |
-
|
| 152 |
-
# ------------------------------------------------------------ top SKUs (with profit/order)
|
| 153 |
-
def top_skus(name, t=None, team_id=None, top=30):
|
| 154 |
-
"""The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
|
| 155 |
-
t = t or P.today()
|
| 156 |
-
book = _book(name)
|
| 157 |
-
if book is not None and not book:
|
| 158 |
-
return []
|
| 159 |
-
yf, yt = P.ytd(t)
|
| 160 |
-
lex = [('order_partner_id', 'in', list(book))] if book is not None else None
|
| 161 |
-
return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
|
| 162 |
-
|
| 163 |
-
|
| 164 |
-
# ------------------------------------------------------------ returns (book-scoped, consolidated)
|
| 165 |
-
def returns_trend(name, n=13, t=None):
|
| 166 |
-
return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
|
| 167 |
-
|
| 168 |
-
|
| 169 |
-
def returns_headline(name, t=None):
|
| 170 |
-
return sales_mod.returns_headline(t, partner_ids=_book(name))
|
| 171 |
-
|
| 172 |
-
|
| 173 |
-
# ------------------------------------------------------------ all-agents rollup (the page table)
|
| 174 |
-
def _returns_by_agent(t=None):
|
| 175 |
-
"""{agent_name: returns$ YTD} β credit notes mapped to each customer's agent."""
|
| 176 |
-
by_p = sales_mod.returns_by_partner(t)
|
| 177 |
-
attrs = cust_mod._partner_attrs(list(by_p))
|
| 178 |
-
agg = {}
|
| 179 |
-
for pid, amt in by_p.items():
|
| 180 |
-
a = (attrs.get(pid) or {}).get('agent') or '(none)'
|
| 181 |
-
agg[a] = agg.get(a, 0.0) + amt
|
| 182 |
-
return agg
|
| 183 |
-
|
| 184 |
-
|
| 185 |
-
def rollup(t=None, team_id=None):
|
| 186 |
-
"""Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
|
| 187 |
-
rate. Reuses the Customers MECE agent rollup, so Ξ£(agents) == total YTD revenue."""
|
| 188 |
-
rows = cust_mod.by_dimension('agent', t, team_id=team_id)
|
| 189 |
-
ret = _returns_by_agent(t)
|
| 190 |
-
for r in rows:
|
| 191 |
-
r['agent'] = r['group']
|
| 192 |
-
r['returns'] = ret.get(r['group'], 0.0)
|
| 193 |
-
r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
|
| 194 |
-
return rows
|
| 195 |
-
|
| 196 |
-
|
| 197 |
-
# ------------------------------------------------------------ VALIDATION
|
| 198 |
-
def validate(t=None, team_id=None):
|
| 199 |
-
"""Reconcile the agent rollup to Odoo. (1) Ξ£(agent book revenue) == total YTD revenue β the
|
| 200 |
-
rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
|
| 201 |
-
t = t or P.today()
|
| 202 |
-
yf, yt = P.ytd(t)
|
| 203 |
-
checks = []
|
| 204 |
-
rows = rollup(t, team_id=team_id)
|
| 205 |
-
agent_sum = sum(r['revenue'] for r in rows)
|
| 206 |
-
total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
|
| 207 |
-
checks.append({'check': 'YTD revenue: Ξ£(agent book) == total', 'a': round(agent_sum, 2),
|
| 208 |
-
'b': round(total, 2), 'gap': round(agent_sum - total, 2),
|
| 209 |
-
'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
|
| 210 |
-
# sampled agent: scorecard YTD == headline YTD for the same window
|
| 211 |
-
sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
|
| 212 |
-
if sample:
|
| 213 |
-
sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
|
| 214 |
-
hl = headline(sample, yf, yt, team_id)['revenue']
|
| 215 |
-
checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
|
| 216 |
-
'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
|
| 217 |
-
checks.extend(validate_measures(t=t, team_id=team_id))
|
| 218 |
-
return checks
|
| 219 |
-
|
| 220 |
-
|
| 221 |
-
def validate_measures(t=None, team_id=None, days=90):
|
| 222 |
-
"""ββ W37-T12 β the minted PER-AGENT lookback columns, against a DIRECT Odoo aggregate.
|
| 223 |
-
|
| 224 |
-
β WHICH AGENT SOURCE, AND THE TICKET REQUIRES IT SAID OUT LOUD: this reconciles ROUTE 1, the
|
| 225 |
-
CUSTOMER-MASTER BOOK (`res.partner.agent_ids` -> the mirror's `res_partner.agent_id`, which is
|
| 226 |
-
`sales_lines`' `agent` dim). It is NOT the OCA commission route below β measured 2026-08-19,
|
| 227 |
-
9 agents carry route-1 revenue against 12 on commission lines and 17 carrying the flag, so the
|
| 228 |
-
two produce materially different rankings and a check that mixed them would be comparing two
|
| 229 |
-
different questions and calling the gap an error.
|
| 230 |
-
|
| 231 |
-
β THE ORACLE IS THE ORDER HEADER, not the mirror the columns are served from. `sale.order`
|
| 232 |
-
grouped by `partner_id`, mapped to each customer's agent CLIENT-SIDE β a different model, a
|
| 233 |
-
different grain and a different code path from `store_query`'s line-level sum, so agreement
|
| 234 |
-
between them is evidence rather than tautology.
|
| 235 |
-
β Windowed to the MIRROR'S newest order, like `product_data.validate_measures`, so the
|
| 236 |
-
residual is about EDITS to a shared period and not about orders the mirror has never seen.
|
| 237 |
-
"""
|
| 238 |
-
from harness import datastore as DS
|
| 239 |
-
from harness import semantic as sem
|
| 240 |
-
|
| 241 |
-
t = t or P.today()
|
| 242 |
-
checks = []
|
| 243 |
-
try:
|
| 244 |
-
if not DS.ready():
|
| 245 |
-
return [{'check': 'agent lookback measures reconcile to Odoo', 'a': 'no mirror',
|
| 246 |
-
'b': '-', 'ok': False,
|
| 247 |
-
'detail': 'the tenant store is not readable, so this is UNPROVEN, which standing rule '
|
| 248 |
-
'8 does not accept as green'}]
|
| 249 |
-
except Exception as e: # noqa: BLE001
|
| 250 |
-
return [{'check': 'agent lookback measures reconcile to Odoo', 'a': type(e).__name__,
|
| 251 |
-
'b': '-', 'ok': False, 'detail': str(e)[:200]}]
|
| 252 |
-
|
| 253 |
-
offer = sem.entity_measures('odoo_agents')
|
| 254 |
-
checks.append({'check': 'the agent measure OFFER is non-empty and every key resolves '
|
| 255 |
-
'(owner item 4 / R1)',
|
| 256 |
-
'a': len(offer), 'b': '>0', 'ok': bool(offer),
|
| 257 |
-
'detail': {'keys': [m['key'] for m in offer],
|
| 258 |
-
'refused': sem.entity_measure_refusals('odoo_agents')}})
|
| 259 |
-
if not offer:
|
| 260 |
-
return checks
|
| 261 |
-
|
| 262 |
-
con = DS.ro_cursor()
|
| 263 |
-
try:
|
| 264 |
-
newest = con.execute('SELECT max(date_order) FROM sale_order').fetchone()
|
| 265 |
-
finally:
|
| 266 |
-
con.close()
|
| 267 |
-
d_to = t - dt.timedelta(days=2)
|
| 268 |
-
if newest and newest[0]:
|
| 269 |
-
try:
|
| 270 |
-
d_to = min(d_to, dt.date.fromisoformat(str(newest[0])[:10]) - dt.timedelta(days=1))
|
| 271 |
-
except ValueError:
|
| 272 |
-
pass
|
| 273 |
-
d_from = d_to - dt.timedelta(days=days)
|
| 274 |
-
DF, DT = d_from.isoformat(), d_to.isoformat()
|
| 275 |
-
|
| 276 |
-
ours = sem.entity_measure_values('odoo_agents', ['revenue'], date_from=DF, date_to=DT,
|
| 277 |
-
team_id=team_id, offer=offer)
|
| 278 |
-
# THE ORACLE β order headers, grouped by customer, mapped to that customer's agent here.
|
| 279 |
-
o = O.get_odoo()
|
| 280 |
-
grp = o.read_group('sale.order', sales_mod.order_domain(DF, DT, team_id),
|
| 281 |
-
['partner_id', 'amount_untaxed:sum'], ['partner_id'], lazy=False)
|
| 282 |
-
pids = sorted({r['partner_id'][0] for r in grp if r.get('partner_id')})
|
| 283 |
-
agent_of = {}
|
| 284 |
-
for i in range(0, len(pids), 500):
|
| 285 |
-
for p in o.search_read('res.partner', [('id', 'in', pids[i:i + 500])],
|
| 286 |
-
['id', 'agent_ids']):
|
| 287 |
-
ag = (p.get('agent_ids') or [])
|
| 288 |
-
if ag:
|
| 289 |
-
agent_of[p['id']] = ag[0] # the Customers-module convention: agent_ids[0]
|
| 290 |
-
theirs = {}
|
| 291 |
-
for r in grp:
|
| 292 |
-
if not r.get('partner_id'):
|
| 293 |
-
continue
|
| 294 |
-
a = agent_of.get(r['partner_id'][0])
|
| 295 |
-
if a is not None:
|
| 296 |
-
theirs[a] = theirs.get(a, 0.0) + r['amount_untaxed']
|
| 297 |
-
|
| 298 |
-
ours_tot = round(sum(c.get('revenue', 0) for c in ours.values()), 2)
|
| 299 |
-
theirs_tot = round(sum(theirs.values()), 2)
|
| 300 |
-
# β ORDER-HEADER vs LINE-SUM is a REAL basis difference (an order's untaxed total includes
|
| 301 |
-
# lines this topic's service filter drops), so the tolerance is a stated 3% rather than a
|
| 302 |
-
# cent β and the FIGURE is reported so a drift is readable instead of absorbed.
|
| 303 |
-
gap = ours_tot - theirs_tot
|
| 304 |
-
checks.append({
|
| 305 |
-
'check': 'per-agent revenue (BOOK route) vs an INDEPENDENT Odoo order-header aggregate '
|
| 306 |
-
'mapped through res.partner.agent_ids',
|
| 307 |
-
'a': ours_tot, 'b': theirs_tot, 'gap': round(gap, 2),
|
| 308 |
-
'ok': bool(theirs_tot) and abs(gap) <= 0.03 * theirs_tot,
|
| 309 |
-
'detail': {'window': [DF, DT], 'agents_ours': len(ours), 'agents_theirs': len(theirs),
|
| 310 |
-
'gap_pct': round(gap / theirs_tot * 100, 3) if theirs_tot else None,
|
| 311 |
-
'route': 'customer-master book (res.partner.agent_ids), NOT the OCA '
|
| 312 |
-
'commission table; the two name different people'}})
|
| 313 |
-
# β AND PER AGENT, because a total can agree while every row is keyed wrong β the join-key
|
| 314 |
-
# trap contract C1 names. Here the key is the `res.partner` id at both ends.
|
| 315 |
-
off_by = sorted(((abs(ours.get(a, {}).get('revenue', 0.0) - v), a)
|
| 316 |
-
for a, v in theirs.items() if v), reverse=True)
|
| 317 |
-
bad = [(a, round(ours.get(a, {}).get('revenue', 0.0), 2), round(theirs[a], 2))
|
| 318 |
-
for d, a in off_by if d > 0.03 * theirs[a]]
|
| 319 |
-
checks.append({
|
| 320 |
-
'check': 'each agent\'s own figure ties (the C1 join-key test: a wrong key agrees in '
|
| 321 |
-
'total and disagrees on every row)',
|
| 322 |
-
'a': len(bad), 'b': 0, 'ok': not bad,
|
| 323 |
-
'detail': {'worst': [(a, ours_v, th_v) for a, ours_v, th_v in bad[:5]],
|
| 324 |
-
'agents_compared': len(theirs)}})
|
| 325 |
-
return checks
|
| 326 |
-
|
| 327 |
-
|
| 328 |
-
# ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
|
| 329 |
-
# A SECOND agent source. Everything above this line attributes by BOOK β the customer's assigned
|
| 330 |
-
# agent (res.partner.agent_ids) β over confirmed SALES ORDERS. This section attributes per INVOICE
|
| 331 |
-
# LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
|
| 332 |
-
# commission_lines). The two disagree on purpose and answer different questions:
|
| 333 |
-
#
|
| 334 |
-
# book -> "whose customer is this / who owns the relationship" (order basis)
|
| 335 |
-
# invoice -> "what was actually credited to an agent on the billing" + the ONLY source that can
|
| 336 |
-
# say what is NOT allocated to an agent (invoice basis)
|
| 337 |
-
#
|
| 338 |
-
# β A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT β `res.partner.agent` is the flag.
|
| 339 |
-
# "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
|
| 340 |
-
# dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
|
| 341 |
-
# See [[invoice-line-agent-commission]].
|
| 342 |
-
|
| 343 |
-
_ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
|
| 344 |
-
'none': 'Not allocated'}
|
| 345 |
-
|
| 346 |
-
|
| 347 |
-
def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
|
| 348 |
-
"""Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
|
| 349 |
-
|
| 350 |
-
Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
|
| 351 |
-
'unallocated': float, 'basis': str} β or {'error': msg} when the tenant store is not
|
| 352 |
-
ready (this path is store-only; there is no live fallback that stays honest about the
|
| 353 |
-
unallocated bucket).
|
| 354 |
-
"""
|
| 355 |
-
import harness.semantic as S
|
| 356 |
-
t = t or P.today()
|
| 357 |
-
yf, yt = P.ytd(t)
|
| 358 |
-
dim = 'commission_name' if include_salespeople else 'agent'
|
| 359 |
-
try:
|
| 360 |
-
by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
|
| 361 |
-
date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
|
| 362 |
-
alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
|
| 363 |
-
date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
|
| 364 |
-
tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
|
| 365 |
-
team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
|
| 366 |
-
except Exception as e: # store not ready / model error β say so, don't fake
|
| 367 |
-
return {'error': str(e)}
|
| 368 |
-
# store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
|
| 369 |
-
# (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
|
| 370 |
-
# returns None for every row and silently renders the whole table as "no agent".
|
| 371 |
-
rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
|
| 372 |
-
'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
|
| 373 |
-
rows.sort(key=lambda r: -r['revenue'])
|
| 374 |
-
amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
|
| 375 |
-
allocated = amap.get('agent', 0.0)
|
| 376 |
-
return {
|
| 377 |
-
'by_agent': rows,
|
| 378 |
-
'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
|
| 379 |
-
for k in ('agent', 'salesperson', 'none') if k in amap or True],
|
| 380 |
-
'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
|
| 381 |
-
'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
|
| 382 |
-
'window': (yf, yt),
|
| 383 |
-
'basis': ('invoice line Β· commission names incl. salespeople' if include_salespeople
|
| 384 |
-
else 'invoice line Β· real agents only'),
|
| 385 |
-
}
|
|
|
|
| 1 |
+
"""Agent module β per-agent (res.partner.agent_ids) analytics.
|
| 2 |
+
|
| 3 |
+
An *agent* owns a **book** of customers (the same attribute the Customers module slices by). This
|
| 4 |
+
module reports that book the way Sales/Customers/SKU report the whole company: a period scorecard
|
| 5 |
+
with custom date windows (Today / WTD / Last week / MTD / QTD / YTD / any custom range), a sales
|
| 6 |
+
trend, returns, top SKUs (with profit/order) and the FULL customer list β INCLUDING inactive
|
| 7 |
+
accounts (no recent orders) so a rep sees who they've stopped selling to.
|
| 8 |
+
|
| 9 |
+
Scope: reuses the Sales `order_domain` (Fisch+Royal, excluded accounts removed, state sale/done)
|
| 10 |
+
so numbers tie to every other module. Returns are consolidated (credit notes aren't BU-tagged);
|
| 11 |
+
everything else is BU-filterable via team_id.
|
| 12 |
+
"""
|
| 13 |
+
import sys
|
| 14 |
+
import datetime as dt
|
| 15 |
+
from pathlib import Path
|
| 16 |
+
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
| 17 |
+
import core.odoo as O
|
| 18 |
+
import core.periods as P
|
| 19 |
+
import modules.sales as sales_mod
|
| 20 |
+
import modules.customers as cust_mod
|
| 21 |
+
|
| 22 |
+
|
| 23 |
+
def options(t=None, team_id=None):
|
| 24 |
+
"""Agent names with book activity β for the page/drawer picker."""
|
| 25 |
+
return cust_mod.agent_options(t, team_id)
|
| 26 |
+
|
| 27 |
+
|
| 28 |
+
def _book(name):
|
| 29 |
+
"""frozenset of every partner id assigned to the agent (incl. inactive). None only for 'All'."""
|
| 30 |
+
return cust_mod.agent_partner_ids(name)
|
| 31 |
+
|
| 32 |
+
|
| 33 |
+
def _rev(date_from, date_to, team_id, book):
|
| 34 |
+
return O.sum_field('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
|
| 35 |
+
'amount_untaxed')
|
| 36 |
+
|
| 37 |
+
|
| 38 |
+
def _orders(date_from, date_to, team_id, book):
|
| 39 |
+
return O.get_odoo().search_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book))
|
| 40 |
+
|
| 41 |
+
|
| 42 |
+
def _custs(date_from, date_to, team_id, book):
|
| 43 |
+
return O.distinct_count('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
|
| 44 |
+
'partner_id')
|
| 45 |
+
|
| 46 |
+
|
| 47 |
+
# ------------------------------------------------------------ period scorecard (custom dating)
|
| 48 |
+
# Today / WTD / Last week / MTD / QTD / YTD β each carries its window so the UI can decompose it
|
| 49 |
+
# and so "what did this agent sell this/last week" is a click, not a date-math exercise.
|
| 50 |
+
_PERIODS = [('Today', 'today'), ('Week to date', 'wtd'), ('Last week', 'lwk'),
|
| 51 |
+
('Month to date', 'mtd'), ('Quarter to date', 'qtd'), ('Year to date', 'ytd')]
|
| 52 |
+
|
| 53 |
+
|
| 54 |
+
def _window(key, t):
|
| 55 |
+
if key == 'today':
|
| 56 |
+
return P._d(t), P._d(t)
|
| 57 |
+
if key == 'lwk': # the full prior MonβSun week
|
| 58 |
+
f, _tt = P.wtd(t)
|
| 59 |
+
start = dt.date.fromisoformat(f) - dt.timedelta(days=7)
|
| 60 |
+
return start.isoformat(), (dt.date.fromisoformat(f) - dt.timedelta(days=1)).isoformat()
|
| 61 |
+
return {'wtd': P.wtd, 'mtd': P.mtd, 'qtd': P.qtd, 'ytd': P.ytd}[key](t)
|
| 62 |
+
|
| 63 |
+
|
| 64 |
+
def scorecard(name, t=None, team_id=None):
|
| 65 |
+
"""Book revenue (+ YoY same-period), orders for Today / WTD / Last week / MTD / QTD / YTD."""
|
| 66 |
+
t = t or P.today()
|
| 67 |
+
book = _book(name)
|
| 68 |
+
out = []
|
| 69 |
+
for label, key in _PERIODS:
|
| 70 |
+
f, tt = _window(key, t)
|
| 71 |
+
wk = key in ('today', 'wtd', 'lwk') # weekday-align the short windows' LY compare
|
| 72 |
+
cf, ct = P.shift_year(f, tt, weeks=wk)
|
| 73 |
+
rev, rev_ly = _rev(f, tt, team_id, book), _rev(cf, ct, team_id, book)
|
| 74 |
+
out.append({'key': key, 'label': label, 'date_from': f, 'date_to': tt, 'cmp_from': cf, 'cmp_to': ct,
|
| 75 |
+
'revenue': rev, 'revenue_ly': rev_ly, 'yoy_pct': P.yoy_pct(rev, rev_ly),
|
| 76 |
+
'orders': _orders(f, tt, team_id, book)})
|
| 77 |
+
return out
|
| 78 |
+
|
| 79 |
+
|
| 80 |
+
def headline(name, date_from, date_to, team_id=None):
|
| 81 |
+
"""Book KPIs for an ARBITRARY window (custom dating): revenue + YoY (same window LY), orders,
|
| 82 |
+
active customers, AOV and returns $ / return rate."""
|
| 83 |
+
book = _book(name)
|
| 84 |
+
cf, ct = P.shift_year(date_from, date_to, weeks=False)
|
| 85 |
+
rev, rev_ly = _rev(date_from, date_to, team_id, book), _rev(cf, ct, team_id, book)
|
| 86 |
+
orders = _orders(date_from, date_to, team_id, book)
|
| 87 |
+
ret = sales_mod._returns_amt(date_from, date_to, book)
|
| 88 |
+
return {'date_from': date_from, 'date_to': date_to, 'cmp_from': cf, 'cmp_to': ct,
|
| 89 |
+
'revenue': rev, 'revenue_ly': rev_ly,
|
| 90 |
+
'yoy_pct': P.yoy_pct(rev, rev_ly), 'orders': orders,
|
| 91 |
+
'customers': _custs(date_from, date_to, team_id, book), 'aov': (rev / orders) if orders else 0.0,
|
| 92 |
+
'returns': ret, 'return_rate_pct': (ret / rev * 100.0) if rev else 0.0}
|
| 93 |
+
|
| 94 |
+
|
| 95 |
+
# ------------------------------------------------------------ sales trend
|
| 96 |
+
def _book_monthly_rev(book, date_from, date_to, team_id=None):
|
| 97 |
+
g = O.read_group('sale.order', sales_mod.order_domain(date_from, date_to, team_id, partner_ids=book),
|
| 98 |
+
['amount_untaxed:sum'], ['date_order:month'], lazy=False)
|
| 99 |
+
out = {}
|
| 100 |
+
for r in g:
|
| 101 |
+
ym = ((r.get('__range') or {}).get('date_order:month') or {}).get('from', '')[:7]
|
| 102 |
+
if ym:
|
| 103 |
+
out[ym] = r.get('amount_untaxed') or 0.0
|
| 104 |
+
return out
|
| 105 |
+
|
| 106 |
+
|
| 107 |
+
def monthly(name, n=13, t=None, team_id=None):
|
| 108 |
+
"""Book sales per month vs the same month last year (one month-grouped query over 2 years)."""
|
| 109 |
+
t = t or P.today()
|
| 110 |
+
book = _book(name)
|
| 111 |
+
mrev = _book_monthly_rev(book, dt.date(t.year - 2, t.month, 1).isoformat(), t.isoformat(), team_id)
|
| 112 |
+
rows = []
|
| 113 |
+
for ym, _s, _e in P.month_starts(n, t):
|
| 114 |
+
y, m = int(ym[:4]) - 1, int(ym[5:7])
|
| 115 |
+
this, last = mrev.get(ym, 0.0), mrev.get(f'{y:04d}-{m:02d}', 0.0)
|
| 116 |
+
rows.append({'month': ym, 'revenue': this, 'revenue_ly': last, 'yoy_pct': P.yoy_pct(this, last)})
|
| 117 |
+
return rows
|
| 118 |
+
|
| 119 |
+
|
| 120 |
+
# ------------------------------------------------------------ full customer book (incl. inactive)
|
| 121 |
+
def customers(name, t=None, team_id=None):
|
| 122 |
+
"""EVERY customer in the agent's book, including inactive accounts (no YTD/LY orders) β those
|
| 123 |
+
show $0 with status 'Inactive'/'Dormant'. Each row is clickable to the customer drawer and
|
| 124 |
+
carries recency so a rep can see who's gone quiet. Sorted by YTD revenue desc (inactive last)."""
|
| 125 |
+
t = t or P.today()
|
| 126 |
+
book = _book(name)
|
| 127 |
+
yf, yt = P.ytd(t)
|
| 128 |
+
lf, lt = P.ytd_last_year(t)
|
| 129 |
+
this = cust_mod._cust_rev(yf, yt, team_id, book)
|
| 130 |
+
last = cust_mod._cust_rev(lf, lt, team_id, book)
|
| 131 |
+
lastord = cust_mod._last_order_dates(None, None, team_id, book) # all-time last order = recency
|
| 132 |
+
ids = list(book) if book is not None else list(set(this) | set(last))
|
| 133 |
+
attrs = cust_mod._partner_attrs(set(ids))
|
| 134 |
+
namemap = {r['id']: r.get('name') for r in O.search_read('res.partner', [('id', 'in', ids)], ['name'])}
|
| 135 |
+
rows = []
|
| 136 |
+
for p in ids:
|
| 137 |
+
tr = this.get(p, {}).get('rev', 0.0)
|
| 138 |
+
lr = last.get(p, {}).get('rev', 0.0)
|
| 139 |
+
a = attrs.get(p, {})
|
| 140 |
+
lo = lastord.get(p, '')
|
| 141 |
+
recency = (t - dt.date.fromisoformat(lo)).days if lo else None
|
| 142 |
+
status = 'Active' if tr > 0 else ('Dormant' if (lr > 0 or lo) else 'Inactive')
|
| 143 |
+
rows.append({'pid': p, 'customer': namemap.get(p) or (this.get(p) or last.get(p) or {}).get('name', '?'),
|
| 144 |
+
'rev_ytd': tr, 'rev_ly': lr, 'change': tr - lr, 'yoy_pct': P.yoy_pct(tr, lr),
|
| 145 |
+
'orders': this.get(p, {}).get('orders', 0), 'last_order': lo, 'recency_days': recency,
|
| 146 |
+
'status': status, 'city': a.get('city', '(none)'), 'state': a.get('state', '(none)'),
|
| 147 |
+
'agent': a.get('agent', name)})
|
| 148 |
+
rows.sort(key=lambda r: (r['rev_ytd'] <= 0, -r['rev_ytd'], -(r['rev_ly'])))
|
| 149 |
+
return rows
|
| 150 |
+
|
| 151 |
+
|
| 152 |
+
# ------------------------------------------------------------ top SKUs (with profit/order)
|
| 153 |
+
def top_skus(name, t=None, team_id=None, top=30):
|
| 154 |
+
"""The book's top SKUs YTD (line-level), each with revenue, units, margin and profit/order."""
|
| 155 |
+
t = t or P.today()
|
| 156 |
+
book = _book(name)
|
| 157 |
+
if book is not None and not book:
|
| 158 |
+
return []
|
| 159 |
+
yf, yt = P.ytd(t)
|
| 160 |
+
lex = [('order_partner_id', 'in', list(book))] if book is not None else None
|
| 161 |
+
return sales_mod.decompose(yf, yt, team_id, line_extra=lex, top=top)['skus']
|
| 162 |
+
|
| 163 |
+
|
| 164 |
+
# ------------------------------------------------------------ returns (book-scoped, consolidated)
|
| 165 |
+
def returns_trend(name, n=13, t=None):
|
| 166 |
+
return sales_mod.returns_monthly(n, t, partner_ids=_book(name))
|
| 167 |
+
|
| 168 |
+
|
| 169 |
+
def returns_headline(name, t=None):
|
| 170 |
+
return sales_mod.returns_headline(t, partner_ids=_book(name))
|
| 171 |
+
|
| 172 |
+
|
| 173 |
+
# ------------------------------------------------------------ all-agents rollup (the page table)
|
| 174 |
+
def _returns_by_agent(t=None):
|
| 175 |
+
"""{agent_name: returns$ YTD} β credit notes mapped to each customer's agent."""
|
| 176 |
+
by_p = sales_mod.returns_by_partner(t)
|
| 177 |
+
attrs = cust_mod._partner_attrs(list(by_p))
|
| 178 |
+
agg = {}
|
| 179 |
+
for pid, amt in by_p.items():
|
| 180 |
+
a = (attrs.get(pid) or {}).get('agent') or '(none)'
|
| 181 |
+
agg[a] = agg.get(a, 0.0) + amt
|
| 182 |
+
return agg
|
| 183 |
+
|
| 184 |
+
|
| 185 |
+
def rollup(t=None, team_id=None):
|
| 186 |
+
"""Every agent ranked by YTD book revenue (+ YoY, customers, orders) with returns $ and return
|
| 187 |
+
rate. Reuses the Customers MECE agent rollup, so Ξ£(agents) == total YTD revenue."""
|
| 188 |
+
rows = cust_mod.by_dimension('agent', t, team_id=team_id)
|
| 189 |
+
ret = _returns_by_agent(t)
|
| 190 |
+
for r in rows:
|
| 191 |
+
r['agent'] = r['group']
|
| 192 |
+
r['returns'] = ret.get(r['group'], 0.0)
|
| 193 |
+
r['return_rate_pct'] = (r['returns'] / r['revenue'] * 100.0) if r.get('revenue') else 0.0
|
| 194 |
+
return rows
|
| 195 |
+
|
| 196 |
+
|
| 197 |
+
# ------------------------------------------------------------ VALIDATION
|
| 198 |
+
def validate(t=None, team_id=None):
|
| 199 |
+
"""Reconcile the agent rollup to Odoo. (1) Ξ£(agent book revenue) == total YTD revenue β the
|
| 200 |
+
rollup is MECE over customers. (2) A sampled agent's scorecard YTD == its headline YTD."""
|
| 201 |
+
t = t or P.today()
|
| 202 |
+
yf, yt = P.ytd(t)
|
| 203 |
+
checks = []
|
| 204 |
+
rows = rollup(t, team_id=team_id)
|
| 205 |
+
agent_sum = sum(r['revenue'] for r in rows)
|
| 206 |
+
total = O.sum_field('sale.order', sales_mod.order_domain(yf, yt, team_id), 'amount_untaxed')
|
| 207 |
+
checks.append({'check': 'YTD revenue: Ξ£(agent book) == total', 'a': round(agent_sum, 2),
|
| 208 |
+
'b': round(total, 2), 'gap': round(agent_sum - total, 2),
|
| 209 |
+
'ok': abs(agent_sum - total) <= max(1.0, 0.001 * (total or 1))})
|
| 210 |
+
# sampled agent: scorecard YTD == headline YTD for the same window
|
| 211 |
+
sample = next((r['agent'] for r in rows if r['agent'] not in ('(none)',)), None)
|
| 212 |
+
if sample:
|
| 213 |
+
sc_ytd = next((s['revenue'] for s in scorecard(sample, t, team_id) if s['key'] == 'ytd'), 0.0)
|
| 214 |
+
hl = headline(sample, yf, yt, team_id)['revenue']
|
| 215 |
+
checks.append({'check': f'Agent "{sample}": scorecard YTD == headline YTD', 'a': round(sc_ytd, 2),
|
| 216 |
+
'b': round(hl, 2), 'gap': round(sc_ytd - hl, 2), 'ok': abs(sc_ytd - hl) <= 1.0})
|
| 217 |
+
checks.extend(validate_measures(t=t, team_id=team_id))
|
| 218 |
+
return checks
|
| 219 |
+
|
| 220 |
+
|
| 221 |
+
def validate_measures(t=None, team_id=None, days=90):
|
| 222 |
+
"""ββ W37-T12 β the minted PER-AGENT lookback columns, against a DIRECT Odoo aggregate.
|
| 223 |
+
|
| 224 |
+
β WHICH AGENT SOURCE, AND THE TICKET REQUIRES IT SAID OUT LOUD: this reconciles ROUTE 1, the
|
| 225 |
+
CUSTOMER-MASTER BOOK (`res.partner.agent_ids` -> the mirror's `res_partner.agent_id`, which is
|
| 226 |
+
`sales_lines`' `agent` dim). It is NOT the OCA commission route below β measured 2026-08-19,
|
| 227 |
+
9 agents carry route-1 revenue against 12 on commission lines and 17 carrying the flag, so the
|
| 228 |
+
two produce materially different rankings and a check that mixed them would be comparing two
|
| 229 |
+
different questions and calling the gap an error.
|
| 230 |
+
|
| 231 |
+
β THE ORACLE IS THE ORDER HEADER, not the mirror the columns are served from. `sale.order`
|
| 232 |
+
grouped by `partner_id`, mapped to each customer's agent CLIENT-SIDE β a different model, a
|
| 233 |
+
different grain and a different code path from `store_query`'s line-level sum, so agreement
|
| 234 |
+
between them is evidence rather than tautology.
|
| 235 |
+
β Windowed to the MIRROR'S newest order, like `product_data.validate_measures`, so the
|
| 236 |
+
residual is about EDITS to a shared period and not about orders the mirror has never seen.
|
| 237 |
+
"""
|
| 238 |
+
from harness import datastore as DS
|
| 239 |
+
from harness import semantic as sem
|
| 240 |
+
|
| 241 |
+
t = t or P.today()
|
| 242 |
+
checks = []
|
| 243 |
+
try:
|
| 244 |
+
if not DS.ready():
|
| 245 |
+
return [{'check': 'agent lookback measures reconcile to Odoo', 'a': 'no mirror',
|
| 246 |
+
'b': '-', 'ok': False,
|
| 247 |
+
'detail': 'the tenant store is not readable, so this is UNPROVEN, which standing rule '
|
| 248 |
+
'8 does not accept as green'}]
|
| 249 |
+
except Exception as e: # noqa: BLE001
|
| 250 |
+
return [{'check': 'agent lookback measures reconcile to Odoo', 'a': type(e).__name__,
|
| 251 |
+
'b': '-', 'ok': False, 'detail': str(e)[:200]}]
|
| 252 |
+
|
| 253 |
+
offer = sem.entity_measures('odoo_agents')
|
| 254 |
+
checks.append({'check': 'the agent measure OFFER is non-empty and every key resolves '
|
| 255 |
+
'(owner item 4 / R1)',
|
| 256 |
+
'a': len(offer), 'b': '>0', 'ok': bool(offer),
|
| 257 |
+
'detail': {'keys': [m['key'] for m in offer],
|
| 258 |
+
'refused': sem.entity_measure_refusals('odoo_agents')}})
|
| 259 |
+
if not offer:
|
| 260 |
+
return checks
|
| 261 |
+
|
| 262 |
+
con = DS.ro_cursor()
|
| 263 |
+
try:
|
| 264 |
+
newest = con.execute('SELECT max(date_order) FROM sale_order').fetchone()
|
| 265 |
+
finally:
|
| 266 |
+
con.close()
|
| 267 |
+
d_to = t - dt.timedelta(days=2)
|
| 268 |
+
if newest and newest[0]:
|
| 269 |
+
try:
|
| 270 |
+
d_to = min(d_to, dt.date.fromisoformat(str(newest[0])[:10]) - dt.timedelta(days=1))
|
| 271 |
+
except ValueError:
|
| 272 |
+
pass
|
| 273 |
+
d_from = d_to - dt.timedelta(days=days)
|
| 274 |
+
DF, DT = d_from.isoformat(), d_to.isoformat()
|
| 275 |
+
|
| 276 |
+
ours = sem.entity_measure_values('odoo_agents', ['revenue'], date_from=DF, date_to=DT,
|
| 277 |
+
team_id=team_id, offer=offer)
|
| 278 |
+
# THE ORACLE β order headers, grouped by customer, mapped to that customer's agent here.
|
| 279 |
+
o = O.get_odoo()
|
| 280 |
+
grp = o.read_group('sale.order', sales_mod.order_domain(DF, DT, team_id),
|
| 281 |
+
['partner_id', 'amount_untaxed:sum'], ['partner_id'], lazy=False)
|
| 282 |
+
pids = sorted({r['partner_id'][0] for r in grp if r.get('partner_id')})
|
| 283 |
+
agent_of = {}
|
| 284 |
+
for i in range(0, len(pids), 500):
|
| 285 |
+
for p in o.search_read('res.partner', [('id', 'in', pids[i:i + 500])],
|
| 286 |
+
['id', 'agent_ids']):
|
| 287 |
+
ag = (p.get('agent_ids') or [])
|
| 288 |
+
if ag:
|
| 289 |
+
agent_of[p['id']] = ag[0] # the Customers-module convention: agent_ids[0]
|
| 290 |
+
theirs = {}
|
| 291 |
+
for r in grp:
|
| 292 |
+
if not r.get('partner_id'):
|
| 293 |
+
continue
|
| 294 |
+
a = agent_of.get(r['partner_id'][0])
|
| 295 |
+
if a is not None:
|
| 296 |
+
theirs[a] = theirs.get(a, 0.0) + r['amount_untaxed']
|
| 297 |
+
|
| 298 |
+
ours_tot = round(sum(c.get('revenue', 0) for c in ours.values()), 2)
|
| 299 |
+
theirs_tot = round(sum(theirs.values()), 2)
|
| 300 |
+
# β ORDER-HEADER vs LINE-SUM is a REAL basis difference (an order's untaxed total includes
|
| 301 |
+
# lines this topic's service filter drops), so the tolerance is a stated 3% rather than a
|
| 302 |
+
# cent β and the FIGURE is reported so a drift is readable instead of absorbed.
|
| 303 |
+
gap = ours_tot - theirs_tot
|
| 304 |
+
checks.append({
|
| 305 |
+
'check': 'per-agent revenue (BOOK route) vs an INDEPENDENT Odoo order-header aggregate '
|
| 306 |
+
'mapped through res.partner.agent_ids',
|
| 307 |
+
'a': ours_tot, 'b': theirs_tot, 'gap': round(gap, 2),
|
| 308 |
+
'ok': bool(theirs_tot) and abs(gap) <= 0.03 * theirs_tot,
|
| 309 |
+
'detail': {'window': [DF, DT], 'agents_ours': len(ours), 'agents_theirs': len(theirs),
|
| 310 |
+
'gap_pct': round(gap / theirs_tot * 100, 3) if theirs_tot else None,
|
| 311 |
+
'route': 'customer-master book (res.partner.agent_ids), NOT the OCA '
|
| 312 |
+
'commission table; the two name different people'}})
|
| 313 |
+
# β AND PER AGENT, because a total can agree while every row is keyed wrong β the join-key
|
| 314 |
+
# trap contract C1 names. Here the key is the `res.partner` id at both ends.
|
| 315 |
+
off_by = sorted(((abs(ours.get(a, {}).get('revenue', 0.0) - v), a)
|
| 316 |
+
for a, v in theirs.items() if v), reverse=True)
|
| 317 |
+
bad = [(a, round(ours.get(a, {}).get('revenue', 0.0), 2), round(theirs[a], 2))
|
| 318 |
+
for d, a in off_by if d > 0.03 * theirs[a]]
|
| 319 |
+
checks.append({
|
| 320 |
+
'check': 'each agent\'s own figure ties (the C1 join-key test: a wrong key agrees in '
|
| 321 |
+
'total and disagrees on every row)',
|
| 322 |
+
'a': len(bad), 'b': 0, 'ok': not bad,
|
| 323 |
+
'detail': {'worst': [(a, ours_v, th_v) for a, ours_v, th_v in bad[:5]],
|
| 324 |
+
'agents_compared': len(theirs)}})
|
| 325 |
+
return checks
|
| 326 |
+
|
| 327 |
+
|
| 328 |
+
# ------------------------------------------------------------ INVOICE-LINE ATTRIBUTION (2026-07-28)
|
| 329 |
+
# A SECOND agent source. Everything above this line attributes by BOOK β the customer's assigned
|
| 330 |
+
# agent (res.partner.agent_ids) β over confirmed SALES ORDERS. This section attributes per INVOICE
|
| 331 |
+
# LINE, from the OCA sale-commission module, via the semantic layer (topics invoice_lines /
|
| 332 |
+
# commission_lines). The two disagree on purpose and answer different questions:
|
| 333 |
+
#
|
| 334 |
+
# book -> "whose customer is this / who owns the relationship" (order basis)
|
| 335 |
+
# invoice -> "what was actually credited to an agent on the billing" + the ONLY source that can
|
| 336 |
+
# say what is NOT allocated to an agent (invoice basis)
|
| 337 |
+
#
|
| 338 |
+
# β A NAME ON A COMMISSION LINE IS NOT NECESSARILY AN AGENT β `res.partner.agent` is the flag.
|
| 339 |
+
# "Anna" and "Shantal Erlich" are internal SALESPEOPLE who carry commission lines; the `agent`
|
| 340 |
+
# dim excludes them and `include_salespeople` folds them back in as a clearly-labelled variant.
|
| 341 |
+
# See [[invoice-line-agent-commission]].
|
| 342 |
+
|
| 343 |
+
_ALLOC_LABEL = {'agent': 'Allocated to an agent', 'salesperson': 'Salesperson only',
|
| 344 |
+
'none': 'Not allocated'}
|
| 345 |
+
|
| 346 |
+
|
| 347 |
+
def invoice_line_rollup(t=None, team_id=None, include_salespeople=False):
|
| 348 |
+
"""Per-name invoice-line revenue + the MECE allocation split, for a YTD window.
|
| 349 |
+
|
| 350 |
+
Returns {'by_agent': [...], 'allocation': [...], 'total': float, 'allocated': float,
|
| 351 |
+
'unallocated': float, 'basis': str} β or {'error': msg} when the tenant store is not
|
| 352 |
+
ready (this path is store-only; there is no live fallback that stays honest about the
|
| 353 |
+
unallocated bucket).
|
| 354 |
+
"""
|
| 355 |
+
import harness.semantic as S
|
| 356 |
+
t = t or P.today()
|
| 357 |
+
yf, yt = P.ytd(t)
|
| 358 |
+
dim = 'commission_name' if include_salespeople else 'agent'
|
| 359 |
+
try:
|
| 360 |
+
by = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=[dim],
|
| 361 |
+
date_from=yf, date_to=yt, team_id=team_id, limit=200).get('rows') or []
|
| 362 |
+
alloc = S.store_query('invoice_lines', ['invoiced_line_sales'], group_by=['allocation'],
|
| 363 |
+
date_from=yf, date_to=yt, team_id=team_id, limit=10).get('rows') or []
|
| 364 |
+
tot = (S.store_query('invoice_lines', ['invoiced_line_sales'], date_from=yf, date_to=yt,
|
| 365 |
+
team_id=team_id).get('rows') or [{}])[0].get('invoiced_line_sales') or 0.0
|
| 366 |
+
except Exception as e: # store not ready / model error β say so, don't fake
|
| 367 |
+
return {'error': str(e)}
|
| 368 |
+
# store_query row shape: the DIM KEY carries the display NAME and `<dim>_id` the raw value
|
| 369 |
+
# (allocation -> 'Salesperson only', allocation_id -> 'salesperson'). Reading `<dim>_name`
|
| 370 |
+
# returns None for every row and silently renders the whole table as "no agent".
|
| 371 |
+
rows = [{'agent': (r.get(dim) or '(no agent on the line)'),
|
| 372 |
+
'revenue': r.get('invoiced_line_sales') or 0.0} for r in by]
|
| 373 |
+
rows.sort(key=lambda r: -r['revenue'])
|
| 374 |
+
amap = {r.get('allocation_id') or 'none': (r.get('invoiced_line_sales') or 0.0) for r in alloc}
|
| 375 |
+
allocated = amap.get('agent', 0.0)
|
| 376 |
+
return {
|
| 377 |
+
'by_agent': rows,
|
| 378 |
+
'allocation': [{'bucket': _ALLOC_LABEL[k], 'revenue': amap.get(k, 0.0)}
|
| 379 |
+
for k in ('agent', 'salesperson', 'none') if k in amap or True],
|
| 380 |
+
'total': tot, 'allocated': allocated, 'unallocated': tot - allocated,
|
| 381 |
+
'strict_none': amap.get('none', 0.0), 'salesperson_only': amap.get('salesperson', 0.0),
|
| 382 |
+
'window': (yf, yt),
|
| 383 |
+
'basis': ('invoice line Β· commission names incl. salespeople' if include_salespeople
|
| 384 |
+
else 'invoice line Β· real agents only'),
|
| 385 |
+
}
|
platform/modules/collections_send.py
CHANGED
|
@@ -1,267 +1,267 @@
|
|
| 1 |
-
"""Collections statements β the send layer behind the Collections page's Statements section.
|
| 2 |
-
|
| 3 |
-
Folded in from the standalone collections_app (2026-07-05). THE one sanctioned exception to the
|
| 4 |
-
app's read-only-on-Odoo rule, unchanged from the standalone tool: WRITE is whitelisted to exactly
|
| 5 |
-
one operation β
|
| 6 |
-
|
| 7 |
-
create on mail.mail (queueing an outbound statement email)
|
| 8 |
-
|
| 9 |
-
A mail.mail record with state='outgoing' is picked up by Odoo's "Mail: Email Queue Manager" cron
|
| 10 |
-
(every ~15 min) and delivered through the company's Office 365 relay. Because we set model/res_id,
|
| 11 |
-
each sent statement also appears in the customer's chatter in Odoo β the audit log lives where AR
|
| 12 |
-
already works. This module has its OWN narrow XML-RPC client; the app-wide odoo_client stays
|
| 13 |
-
hard-blocking on all writes. The UI gates the section to admin users; SAFE_MODE is enforced HERE
|
| 14 |
-
in the data layer so the UI cannot bypass it.
|
| 15 |
-
|
| 16 |
-
Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
|
| 17 |
-
Optional: SAFE_MODE (default ON), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
|
| 18 |
-
COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
|
| 19 |
-
"""
|
| 20 |
-
import os
|
| 21 |
-
import datetime as dt
|
| 22 |
-
import xmlrpc.client
|
| 23 |
-
from pathlib import Path
|
| 24 |
-
|
| 25 |
-
try: # self-contained: load credentials from the app root .env if present (HF uses Secrets)
|
| 26 |
-
from dotenv import load_dotenv
|
| 27 |
-
load_dotenv(Path(__file__).resolve().parents[1] / '.env')
|
| 28 |
-
except Exception:
|
| 29 |
-
pass
|
| 30 |
-
|
| 31 |
-
WRITE_WHITELIST = {('mail.mail', 'create')}
|
| 32 |
-
|
| 33 |
-
EXCLUDE_NAMES = {'GIFTWARE DEALS'} # the Amazon channel β not part of Fisch or Royal collections
|
| 34 |
-
DOMAIN = [('followup_reminder_type', '=', 'automatic'), ('credit', '>', 1)]
|
| 35 |
-
|
| 36 |
-
COMPANY = os.environ.get('COMPANY_NAME', 'Royal Imports')
|
| 37 |
-
|
| 38 |
-
# --- Sender identity (statements go out AS Royal Imports) ---
|
| 39 |
-
# Odoo routes outbound mail to the matching ir.mail_server by from_filter, and the Office 365
|
| 40 |
-
# relay only accepts sends as its authenticated address. The "Office 365 - Royal" server (id 2)
|
| 41 |
-
# authenticates as contact@royalimports.com with from_filter='contact@royalimports.com' β so the
|
| 42 |
-
# From MUST be that address for delivery to succeed. Friendly display name; replies routed to AR.
|
| 43 |
-
SENDER_NAME = os.environ.get('SENDER_NAME', 'Royal Imports Accounts Receivable')
|
| 44 |
-
SENDER_EMAIL = os.environ.get('SENDER_EMAIL', 'contact@royalimports.com')
|
| 45 |
-
REPLY_TO = os.environ.get('REPLY_TO', 'accounting@royalimports.com')
|
| 46 |
-
ROYAL_MAIL_SERVER_ID = int(os.environ.get('ROYAL_MAIL_SERVER_ID', '2'))
|
| 47 |
-
ROYAL_AUTHOR_ID = int(os.environ.get('ROYAL_AUTHOR_ID', '8978')) # "Royal Imports" partner
|
| 48 |
-
|
| 49 |
-
SENDER_DISPLAY = f'"{SENDER_NAME}" <{SENDER_EMAIL}>'
|
| 50 |
-
|
| 51 |
-
|
| 52 |
-
class WriteBlocked(RuntimeError):
|
| 53 |
-
pass
|
| 54 |
-
|
| 55 |
-
|
| 56 |
-
class SafeModeBlocked(RuntimeError):
|
| 57 |
-
pass
|
| 58 |
-
|
| 59 |
-
|
| 60 |
-
# --- Testing guardrail -------------------------------------------------------
|
| 61 |
-
# While SAFE_MODE is on, NO email can be queued to any address outside the allow-list β enforced
|
| 62 |
-
# here in the data layer so the UI cannot bypass it. Default: ON. To go live for real customers,
|
| 63 |
-
# set the Space secret SAFE_MODE=0.
|
| 64 |
-
SAFE_MODE = os.environ.get('SAFE_MODE', '1').strip().lower() not in ('0', 'false', 'no', '')
|
| 65 |
-
SAFE_RECIPIENTS = {a.strip().lower() for a in
|
| 66 |
-
os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
|
| 67 |
-
if a.strip()}
|
| 68 |
-
|
| 69 |
-
|
| 70 |
-
def safe_recipient_ok(addr):
|
| 71 |
-
return (not SAFE_MODE) or (str(addr or '').strip().lower() in SAFE_RECIPIENTS)
|
| 72 |
-
|
| 73 |
-
|
| 74 |
-
class Odoo:
|
| 75 |
-
"""Narrow client: read anything, write ONLY the whitelisted mail.mail create."""
|
| 76 |
-
|
| 77 |
-
def __init__(self):
|
| 78 |
-
self.url = os.environ.get('ODOO_URL', '').rstrip('/')
|
| 79 |
-
self.db = os.environ.get('ODOO_DB', '')
|
| 80 |
-
self.user = os.environ.get('ODOO_USER', '')
|
| 81 |
-
self.key = os.environ.get('ODOO_API_KEY', '')
|
| 82 |
-
missing = [k for k, v in [('ODOO_URL', self.url), ('ODOO_DB', self.db),
|
| 83 |
-
('ODOO_USER', self.user), ('ODOO_API_KEY', self.key)] if not v]
|
| 84 |
-
if missing:
|
| 85 |
-
raise RuntimeError(f"Missing secrets: {', '.join(missing)}")
|
| 86 |
-
common = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/common')
|
| 87 |
-
self.uid = common.authenticate(self.db, self.user, self.key, {})
|
| 88 |
-
if not self.uid:
|
| 89 |
-
raise RuntimeError('Odoo authentication failed')
|
| 90 |
-
self.models = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/object')
|
| 91 |
-
|
| 92 |
-
def _exec(self, model, method, args, kwargs=None):
|
| 93 |
-
mutating = method in ('write', 'create', 'unlink', 'copy') or \
|
| 94 |
-
any(method.startswith(p) for p in ('action_', 'button_', 'do_', 'send_',
|
| 95 |
-
'set_', 'update_', 'process_'))
|
| 96 |
-
if mutating and (model, method) not in WRITE_WHITELIST:
|
| 97 |
-
raise WriteBlocked(f'{method} on {model} is not allowed from this app')
|
| 98 |
-
return self.models.execute_kw(self.db, self.uid, self.key,
|
| 99 |
-
model, method, args, kwargs or {})
|
| 100 |
-
|
| 101 |
-
def search_read(self, model, domain=None, fields=None, limit=None, order=None):
|
| 102 |
-
kw = {'fields': fields or []}
|
| 103 |
-
if limit is not None:
|
| 104 |
-
kw['limit'] = limit
|
| 105 |
-
if order:
|
| 106 |
-
kw['order'] = order
|
| 107 |
-
return self._exec(model, 'search_read', [domain or []], kw)
|
| 108 |
-
|
| 109 |
-
def queue_mail(self, payload):
|
| 110 |
-
"""The single allowed write: queue an outbound email."""
|
| 111 |
-
return self._exec('mail.mail', 'create', [payload])
|
| 112 |
-
|
| 113 |
-
|
| 114 |
-
# --------------------------------------------------------------- data builders
|
| 115 |
-
def load_collection_list(odoo):
|
| 116 |
-
"""The saved follow-up filter (Reminders=Automatic, Receivable>$1), GIFTWARE excluded,
|
| 117 |
-
with priority tiers."""
|
| 118 |
-
partners = odoo.search_read('res.partner', DOMAIN,
|
| 119 |
-
['name', 'credit', 'total_overdue', 'followup_status',
|
| 120 |
-
'followup_next_action_date', 'followup_responsible_id',
|
| 121 |
-
'email', 'phone', 'mobile'])
|
| 122 |
-
partners = [p for p in partners if (p['name'] or '').strip().upper() not in EXCLUDE_NAMES]
|
| 123 |
-
pids = [p['id'] for p in partners]
|
| 124 |
-
|
| 125 |
-
docs = odoo.search_read('account.move',
|
| 126 |
-
[('move_type', 'in', ['out_invoice', 'out_refund']), ('state', '=', 'posted'),
|
| 127 |
-
('payment_state', 'in', ['not_paid', 'partial']), ('partner_id', 'in', pids)],
|
| 128 |
-
['name', 'partner_id', 'move_type', 'invoice_date', 'invoice_date_due',
|
| 129 |
-
'amount_total', 'amount_residual_signed'])
|
| 130 |
-
|
| 131 |
-
today = dt.date.today()
|
| 132 |
-
by_partner = {}
|
| 133 |
-
for d in docs:
|
| 134 |
-
pid = d['partner_id'][0]
|
| 135 |
-
due = d.get('invoice_date_due')
|
| 136 |
-
try:
|
| 137 |
-
days = (today - dt.date.fromisoformat(due)).days if due else 0
|
| 138 |
-
except Exception:
|
| 139 |
-
days = 0
|
| 140 |
-
d['days_overdue'] = max(days, 0)
|
| 141 |
-
d['open_signed'] = d['amount_residual_signed']
|
| 142 |
-
by_partner.setdefault(pid, []).append(d)
|
| 143 |
-
|
| 144 |
-
rows = []
|
| 145 |
-
for p in partners:
|
| 146 |
-
pid = p['id']
|
| 147 |
-
odoo_overdue = float(p.get('total_overdue') or 0)
|
| 148 |
-
docs_p = sorted(by_partner.get(pid, []), key=lambda x: x.get('invoice_date_due') or '')
|
| 149 |
-
inv_overdue = sum(d['open_signed'] for d in docs_p if d['days_overdue'] > 0)
|
| 150 |
-
oldest = max((d['days_overdue'] for d in docs_p), default=0)
|
| 151 |
-
gap = inv_overdue - odoo_overdue
|
| 152 |
-
reconcile = abs(gap) > 50
|
| 153 |
-
|
| 154 |
-
if odoo_overdue >= 5000 or (odoo_overdue > 0 and oldest > 90):
|
| 155 |
-
tier = 'A-Urgent'
|
| 156 |
-
elif odoo_overdue >= 1000 or (odoo_overdue > 0 and oldest > 30):
|
| 157 |
-
tier = 'B-Active'
|
| 158 |
-
elif odoo_overdue > 0:
|
| 159 |
-
tier = 'C-Light'
|
| 160 |
-
else:
|
| 161 |
-
tier = 'Monitor'
|
| 162 |
-
|
| 163 |
-
rows.append({
|
| 164 |
-
'partner_id': pid,
|
| 165 |
-
'Customer': p['name'],
|
| 166 |
-
'Tier': tier,
|
| 167 |
-
'Overdue': odoo_overdue,
|
| 168 |
-
'Receivable': float(p.get('credit') or 0),
|
| 169 |
-
'Oldest (days)': oldest,
|
| 170 |
-
'Open Docs': len(docs_p),
|
| 171 |
-
'Email': p.get('email') or '',
|
| 172 |
-
'Phone': p.get('phone') or p.get('mobile') or '',
|
| 173 |
-
'Status': (p.get('followup_status') or '').replace('_', ' '),
|
| 174 |
-
'Reconcile?': 'YES' if reconcile else '',
|
| 175 |
-
'_docs': docs_p,
|
| 176 |
-
})
|
| 177 |
-
tier_rank = {'A-Urgent': 0, 'B-Active': 1, 'C-Light': 2, 'Monitor': 3}
|
| 178 |
-
rows.sort(key=lambda r: (tier_rank[r['Tier']], -r['Overdue']))
|
| 179 |
-
return rows
|
| 180 |
-
|
| 181 |
-
|
| 182 |
-
# --------------------------------------------------------------- statement email
|
| 183 |
-
# β STANDING RULE 2, AND THIS IS THE ONE STRING IN THE PRODUCT THAT LEAVES THE BUILDING.
|
| 184 |
-
# Every other finding `web_prose` reports is copy on a screen somebody here opens; this is the
|
| 185 |
-
# SUBJECT LINE of mail queued to a real debtor, over the single sanctioned Odoo write. It read
|
| 186 |
-
# 'Statement of Account (em dash) {company} (em dash) {month}' until W36-T42.
|
| 187 |
-
DEFAULT_SUBJECT = 'Statement of Account from {company}, {month}'
|
| 188 |
-
DEFAULT_INTRO = (
|
| 189 |
-
'Dear {customer},<br><br>'
|
| 190 |
-
'Please find below your current statement of account with {company}. '
|
| 191 |
-
'According to our records, the following invoices remain open:'
|
| 192 |
-
)
|
| 193 |
-
DEFAULT_FOOTER = (
|
| 194 |
-
'If you have already sent payment, please disregard this notice, and thank you. '
|
| 195 |
-
'For any questions about an invoice, simply reply to this email.<br><br>'
|
| 196 |
-
'Thank you for your business,<br>{company}<br>Accounts Receivable'
|
| 197 |
-
)
|
| 198 |
-
|
| 199 |
-
|
| 200 |
-
def render_statement_html(row, intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER):
|
| 201 |
-
month = dt.date.today().strftime('%B %Y')
|
| 202 |
-
intro = intro_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
|
| 203 |
-
footer = footer_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
|
| 204 |
-
|
| 205 |
-
lines = []
|
| 206 |
-
total_open = 0.0
|
| 207 |
-
for d in row['_docs']:
|
| 208 |
-
kind = 'Credit Note' if d['move_type'] == 'out_refund' else 'Invoice'
|
| 209 |
-
amt = d['open_signed']
|
| 210 |
-
total_open += amt
|
| 211 |
-
overdue_txt = f"{d['days_overdue']}d overdue" if d['days_overdue'] > 0 else 'current'
|
| 212 |
-
color = '#C0392B' if d['days_overdue'] > 0 else '#1F4E78'
|
| 213 |
-
lines.append(
|
| 214 |
-
f"<tr><td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d['name']} <span style='color:#888'>({kind})</span></td>"
|
| 215 |
-
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date') or ''}</td>"
|
| 216 |
-
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date_due') or ''}</td>"
|
| 217 |
-
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;color:{color}'>{overdue_txt}</td>"
|
| 218 |
-
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;text-align:right'>${amt:,.2f}</td></tr>")
|
| 219 |
-
|
| 220 |
-
table = (
|
| 221 |
-
"<table style='border-collapse:collapse;font-size:14px;margin:14px 0'>"
|
| 222 |
-
"<tr style='background:#1F4E78;color:#fff'>"
|
| 223 |
-
"<th style='padding:7px 10px;text-align:left'>Document</th>"
|
| 224 |
-
"<th style='padding:7px 10px;text-align:left'>Date</th>"
|
| 225 |
-
"<th style='padding:7px 10px;text-align:left'>Due</th>"
|
| 226 |
-
"<th style='padding:7px 10px;text-align:left'>Status</th>"
|
| 227 |
-
"<th style='padding:7px 10px;text-align:right'>Open Balance</th></tr>"
|
| 228 |
-
+ ''.join(lines) +
|
| 229 |
-
f"<tr><td colspan='4' style='padding:8px 10px;font-weight:bold;text-align:right'>Total open</td>"
|
| 230 |
-
f"<td style='padding:8px 10px;font-weight:bold;text-align:right'>${total_open:,.2f}</td></tr>"
|
| 231 |
-
f"<tr><td colspan='4' style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>Of which overdue</td>"
|
| 232 |
-
f"<td style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>${row['Overdue']:,.2f}</td></tr>"
|
| 233 |
-
"</table>")
|
| 234 |
-
|
| 235 |
-
return (f"<div style='font-family:Calibri,Arial,sans-serif;color:#1a1a1a;font-size:14px'>"
|
| 236 |
-
f"{intro}{table}{footer}</div>")
|
| 237 |
-
|
| 238 |
-
|
| 239 |
-
def queue_statement(odoo, row, subject_tpl=DEFAULT_SUBJECT,
|
| 240 |
-
intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER,
|
| 241 |
-
override_to=None):
|
| 242 |
-
"""Queue one statement email in Odoo. Returns mail.mail id.
|
| 243 |
-
override_to: send to a different address (used by the test-send button)."""
|
| 244 |
-
to = override_to or row['Email']
|
| 245 |
-
if not to:
|
| 246 |
-
raise ValueError(f"{row['Customer']} has no email address")
|
| 247 |
-
# Hard guardrail β refuse any recipient outside the allow-list while SAFE_MODE is on.
|
| 248 |
-
if not safe_recipient_ok(to):
|
| 249 |
-
raise SafeModeBlocked(
|
| 250 |
-
f"Guardrail ON: refusing to email {to}. Only {', '.join(sorted(SAFE_RECIPIENTS))} "
|
| 251 |
-
f"is allowed right now. (Set SAFE_MODE=0 to send to real customers.)")
|
| 252 |
-
month = dt.date.today().strftime('%B %Y')
|
| 253 |
-
subject = subject_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
|
| 254 |
-
payload = {
|
| 255 |
-
'subject': subject,
|
| 256 |
-
'body_html': render_statement_html(row, intro_tpl, footer_tpl),
|
| 257 |
-
'email_to': to,
|
| 258 |
-
'email_from': SENDER_DISPLAY, # From: Royal Imports
|
| 259 |
-
'reply_to': REPLY_TO, # replies -> AR
|
| 260 |
-
'mail_server_id': ROYAL_MAIL_SERVER_ID, # force Royal O365 relay
|
| 261 |
-
'author_id': ROYAL_AUTHOR_ID, # clean attribution in chatter
|
| 262 |
-
'state': 'outgoing',
|
| 263 |
-
'auto_delete': False,
|
| 264 |
-
'model': 'res.partner',
|
| 265 |
-
'res_id': row['partner_id'],
|
| 266 |
-
}
|
| 267 |
-
return odoo.queue_mail(payload)
|
|
|
|
| 1 |
+
"""Collections statements β the send layer behind the Collections page's Statements section.
|
| 2 |
+
|
| 3 |
+
Folded in from the standalone collections_app (2026-07-05). THE one sanctioned exception to the
|
| 4 |
+
app's read-only-on-Odoo rule, unchanged from the standalone tool: WRITE is whitelisted to exactly
|
| 5 |
+
one operation β
|
| 6 |
+
|
| 7 |
+
create on mail.mail (queueing an outbound statement email)
|
| 8 |
+
|
| 9 |
+
A mail.mail record with state='outgoing' is picked up by Odoo's "Mail: Email Queue Manager" cron
|
| 10 |
+
(every ~15 min) and delivered through the company's Office 365 relay. Because we set model/res_id,
|
| 11 |
+
each sent statement also appears in the customer's chatter in Odoo β the audit log lives where AR
|
| 12 |
+
already works. This module has its OWN narrow XML-RPC client; the app-wide odoo_client stays
|
| 13 |
+
hard-blocking on all writes. The UI gates the section to admin users; SAFE_MODE is enforced HERE
|
| 14 |
+
in the data layer so the UI cannot bypass it.
|
| 15 |
+
|
| 16 |
+
Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
|
| 17 |
+
Optional: SAFE_MODE (default ON), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
|
| 18 |
+
COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
|
| 19 |
+
"""
|
| 20 |
+
import os
|
| 21 |
+
import datetime as dt
|
| 22 |
+
import xmlrpc.client
|
| 23 |
+
from pathlib import Path
|
| 24 |
+
|
| 25 |
+
try: # self-contained: load credentials from the app root .env if present (HF uses Secrets)
|
| 26 |
+
from dotenv import load_dotenv
|
| 27 |
+
load_dotenv(Path(__file__).resolve().parents[1] / '.env')
|
| 28 |
+
except Exception:
|
| 29 |
+
pass
|
| 30 |
+
|
| 31 |
+
WRITE_WHITELIST = {('mail.mail', 'create')}
|
| 32 |
+
|
| 33 |
+
EXCLUDE_NAMES = {'GIFTWARE DEALS'} # the Amazon channel β not part of Fisch or Royal collections
|
| 34 |
+
DOMAIN = [('followup_reminder_type', '=', 'automatic'), ('credit', '>', 1)]
|
| 35 |
+
|
| 36 |
+
COMPANY = os.environ.get('COMPANY_NAME', 'Royal Imports')
|
| 37 |
+
|
| 38 |
+
# --- Sender identity (statements go out AS Royal Imports) ---
|
| 39 |
+
# Odoo routes outbound mail to the matching ir.mail_server by from_filter, and the Office 365
|
| 40 |
+
# relay only accepts sends as its authenticated address. The "Office 365 - Royal" server (id 2)
|
| 41 |
+
# authenticates as contact@royalimports.com with from_filter='contact@royalimports.com' β so the
|
| 42 |
+
# From MUST be that address for delivery to succeed. Friendly display name; replies routed to AR.
|
| 43 |
+
SENDER_NAME = os.environ.get('SENDER_NAME', 'Royal Imports Accounts Receivable')
|
| 44 |
+
SENDER_EMAIL = os.environ.get('SENDER_EMAIL', 'contact@royalimports.com')
|
| 45 |
+
REPLY_TO = os.environ.get('REPLY_TO', 'accounting@royalimports.com')
|
| 46 |
+
ROYAL_MAIL_SERVER_ID = int(os.environ.get('ROYAL_MAIL_SERVER_ID', '2'))
|
| 47 |
+
ROYAL_AUTHOR_ID = int(os.environ.get('ROYAL_AUTHOR_ID', '8978')) # "Royal Imports" partner
|
| 48 |
+
|
| 49 |
+
SENDER_DISPLAY = f'"{SENDER_NAME}" <{SENDER_EMAIL}>'
|
| 50 |
+
|
| 51 |
+
|
| 52 |
+
class WriteBlocked(RuntimeError):
|
| 53 |
+
pass
|
| 54 |
+
|
| 55 |
+
|
| 56 |
+
class SafeModeBlocked(RuntimeError):
|
| 57 |
+
pass
|
| 58 |
+
|
| 59 |
+
|
| 60 |
+
# --- Testing guardrail -------------------------------------------------------
|
| 61 |
+
# While SAFE_MODE is on, NO email can be queued to any address outside the allow-list β enforced
|
| 62 |
+
# here in the data layer so the UI cannot bypass it. Default: ON. To go live for real customers,
|
| 63 |
+
# set the Space secret SAFE_MODE=0.
|
| 64 |
+
SAFE_MODE = os.environ.get('SAFE_MODE', '1').strip().lower() not in ('0', 'false', 'no', '')
|
| 65 |
+
SAFE_RECIPIENTS = {a.strip().lower() for a in
|
| 66 |
+
os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
|
| 67 |
+
if a.strip()}
|
| 68 |
+
|
| 69 |
+
|
| 70 |
+
def safe_recipient_ok(addr):
|
| 71 |
+
return (not SAFE_MODE) or (str(addr or '').strip().lower() in SAFE_RECIPIENTS)
|
| 72 |
+
|
| 73 |
+
|
| 74 |
+
class Odoo:
|
| 75 |
+
"""Narrow client: read anything, write ONLY the whitelisted mail.mail create."""
|
| 76 |
+
|
| 77 |
+
def __init__(self):
|
| 78 |
+
self.url = os.environ.get('ODOO_URL', '').rstrip('/')
|
| 79 |
+
self.db = os.environ.get('ODOO_DB', '')
|
| 80 |
+
self.user = os.environ.get('ODOO_USER', '')
|
| 81 |
+
self.key = os.environ.get('ODOO_API_KEY', '')
|
| 82 |
+
missing = [k for k, v in [('ODOO_URL', self.url), ('ODOO_DB', self.db),
|
| 83 |
+
('ODOO_USER', self.user), ('ODOO_API_KEY', self.key)] if not v]
|
| 84 |
+
if missing:
|
| 85 |
+
raise RuntimeError(f"Missing secrets: {', '.join(missing)}")
|
| 86 |
+
common = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/common')
|
| 87 |
+
self.uid = common.authenticate(self.db, self.user, self.key, {})
|
| 88 |
+
if not self.uid:
|
| 89 |
+
raise RuntimeError('Odoo authentication failed')
|
| 90 |
+
self.models = xmlrpc.client.ServerProxy(f'{self.url}/xmlrpc/2/object')
|
| 91 |
+
|
| 92 |
+
def _exec(self, model, method, args, kwargs=None):
|
| 93 |
+
mutating = method in ('write', 'create', 'unlink', 'copy') or \
|
| 94 |
+
any(method.startswith(p) for p in ('action_', 'button_', 'do_', 'send_',
|
| 95 |
+
'set_', 'update_', 'process_'))
|
| 96 |
+
if mutating and (model, method) not in WRITE_WHITELIST:
|
| 97 |
+
raise WriteBlocked(f'{method} on {model} is not allowed from this app')
|
| 98 |
+
return self.models.execute_kw(self.db, self.uid, self.key,
|
| 99 |
+
model, method, args, kwargs or {})
|
| 100 |
+
|
| 101 |
+
def search_read(self, model, domain=None, fields=None, limit=None, order=None):
|
| 102 |
+
kw = {'fields': fields or []}
|
| 103 |
+
if limit is not None:
|
| 104 |
+
kw['limit'] = limit
|
| 105 |
+
if order:
|
| 106 |
+
kw['order'] = order
|
| 107 |
+
return self._exec(model, 'search_read', [domain or []], kw)
|
| 108 |
+
|
| 109 |
+
def queue_mail(self, payload):
|
| 110 |
+
"""The single allowed write: queue an outbound email."""
|
| 111 |
+
return self._exec('mail.mail', 'create', [payload])
|
| 112 |
+
|
| 113 |
+
|
| 114 |
+
# --------------------------------------------------------------- data builders
|
| 115 |
+
def load_collection_list(odoo):
|
| 116 |
+
"""The saved follow-up filter (Reminders=Automatic, Receivable>$1), GIFTWARE excluded,
|
| 117 |
+
with priority tiers."""
|
| 118 |
+
partners = odoo.search_read('res.partner', DOMAIN,
|
| 119 |
+
['name', 'credit', 'total_overdue', 'followup_status',
|
| 120 |
+
'followup_next_action_date', 'followup_responsible_id',
|
| 121 |
+
'email', 'phone', 'mobile'])
|
| 122 |
+
partners = [p for p in partners if (p['name'] or '').strip().upper() not in EXCLUDE_NAMES]
|
| 123 |
+
pids = [p['id'] for p in partners]
|
| 124 |
+
|
| 125 |
+
docs = odoo.search_read('account.move',
|
| 126 |
+
[('move_type', 'in', ['out_invoice', 'out_refund']), ('state', '=', 'posted'),
|
| 127 |
+
('payment_state', 'in', ['not_paid', 'partial']), ('partner_id', 'in', pids)],
|
| 128 |
+
['name', 'partner_id', 'move_type', 'invoice_date', 'invoice_date_due',
|
| 129 |
+
'amount_total', 'amount_residual_signed'])
|
| 130 |
+
|
| 131 |
+
today = dt.date.today()
|
| 132 |
+
by_partner = {}
|
| 133 |
+
for d in docs:
|
| 134 |
+
pid = d['partner_id'][0]
|
| 135 |
+
due = d.get('invoice_date_due')
|
| 136 |
+
try:
|
| 137 |
+
days = (today - dt.date.fromisoformat(due)).days if due else 0
|
| 138 |
+
except Exception:
|
| 139 |
+
days = 0
|
| 140 |
+
d['days_overdue'] = max(days, 0)
|
| 141 |
+
d['open_signed'] = d['amount_residual_signed']
|
| 142 |
+
by_partner.setdefault(pid, []).append(d)
|
| 143 |
+
|
| 144 |
+
rows = []
|
| 145 |
+
for p in partners:
|
| 146 |
+
pid = p['id']
|
| 147 |
+
odoo_overdue = float(p.get('total_overdue') or 0)
|
| 148 |
+
docs_p = sorted(by_partner.get(pid, []), key=lambda x: x.get('invoice_date_due') or '')
|
| 149 |
+
inv_overdue = sum(d['open_signed'] for d in docs_p if d['days_overdue'] > 0)
|
| 150 |
+
oldest = max((d['days_overdue'] for d in docs_p), default=0)
|
| 151 |
+
gap = inv_overdue - odoo_overdue
|
| 152 |
+
reconcile = abs(gap) > 50
|
| 153 |
+
|
| 154 |
+
if odoo_overdue >= 5000 or (odoo_overdue > 0 and oldest > 90):
|
| 155 |
+
tier = 'A-Urgent'
|
| 156 |
+
elif odoo_overdue >= 1000 or (odoo_overdue > 0 and oldest > 30):
|
| 157 |
+
tier = 'B-Active'
|
| 158 |
+
elif odoo_overdue > 0:
|
| 159 |
+
tier = 'C-Light'
|
| 160 |
+
else:
|
| 161 |
+
tier = 'Monitor'
|
| 162 |
+
|
| 163 |
+
rows.append({
|
| 164 |
+
'partner_id': pid,
|
| 165 |
+
'Customer': p['name'],
|
| 166 |
+
'Tier': tier,
|
| 167 |
+
'Overdue': odoo_overdue,
|
| 168 |
+
'Receivable': float(p.get('credit') or 0),
|
| 169 |
+
'Oldest (days)': oldest,
|
| 170 |
+
'Open Docs': len(docs_p),
|
| 171 |
+
'Email': p.get('email') or '',
|
| 172 |
+
'Phone': p.get('phone') or p.get('mobile') or '',
|
| 173 |
+
'Status': (p.get('followup_status') or '').replace('_', ' '),
|
| 174 |
+
'Reconcile?': 'YES' if reconcile else '',
|
| 175 |
+
'_docs': docs_p,
|
| 176 |
+
})
|
| 177 |
+
tier_rank = {'A-Urgent': 0, 'B-Active': 1, 'C-Light': 2, 'Monitor': 3}
|
| 178 |
+
rows.sort(key=lambda r: (tier_rank[r['Tier']], -r['Overdue']))
|
| 179 |
+
return rows
|
| 180 |
+
|
| 181 |
+
|
| 182 |
+
# --------------------------------------------------------------- statement email
|
| 183 |
+
# β STANDING RULE 2, AND THIS IS THE ONE STRING IN THE PRODUCT THAT LEAVES THE BUILDING.
|
| 184 |
+
# Every other finding `web_prose` reports is copy on a screen somebody here opens; this is the
|
| 185 |
+
# SUBJECT LINE of mail queued to a real debtor, over the single sanctioned Odoo write. It read
|
| 186 |
+
# 'Statement of Account (em dash) {company} (em dash) {month}' until W36-T42.
|
| 187 |
+
DEFAULT_SUBJECT = 'Statement of Account from {company}, {month}'
|
| 188 |
+
DEFAULT_INTRO = (
|
| 189 |
+
'Dear {customer},<br><br>'
|
| 190 |
+
'Please find below your current statement of account with {company}. '
|
| 191 |
+
'According to our records, the following invoices remain open:'
|
| 192 |
+
)
|
| 193 |
+
DEFAULT_FOOTER = (
|
| 194 |
+
'If you have already sent payment, please disregard this notice, and thank you. '
|
| 195 |
+
'For any questions about an invoice, simply reply to this email.<br><br>'
|
| 196 |
+
'Thank you for your business,<br>{company}<br>Accounts Receivable'
|
| 197 |
+
)
|
| 198 |
+
|
| 199 |
+
|
| 200 |
+
def render_statement_html(row, intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER):
|
| 201 |
+
month = dt.date.today().strftime('%B %Y')
|
| 202 |
+
intro = intro_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
|
| 203 |
+
footer = footer_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
|
| 204 |
+
|
| 205 |
+
lines = []
|
| 206 |
+
total_open = 0.0
|
| 207 |
+
for d in row['_docs']:
|
| 208 |
+
kind = 'Credit Note' if d['move_type'] == 'out_refund' else 'Invoice'
|
| 209 |
+
amt = d['open_signed']
|
| 210 |
+
total_open += amt
|
| 211 |
+
overdue_txt = f"{d['days_overdue']}d overdue" if d['days_overdue'] > 0 else 'current'
|
| 212 |
+
color = '#C0392B' if d['days_overdue'] > 0 else '#1F4E78'
|
| 213 |
+
lines.append(
|
| 214 |
+
f"<tr><td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d['name']} <span style='color:#888'>({kind})</span></td>"
|
| 215 |
+
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date') or ''}</td>"
|
| 216 |
+
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef'>{d.get('invoice_date_due') or ''}</td>"
|
| 217 |
+
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;color:{color}'>{overdue_txt}</td>"
|
| 218 |
+
f"<td style='padding:6px 10px;border-bottom:1px solid #e3e8ef;text-align:right'>${amt:,.2f}</td></tr>")
|
| 219 |
+
|
| 220 |
+
table = (
|
| 221 |
+
"<table style='border-collapse:collapse;font-size:14px;margin:14px 0'>"
|
| 222 |
+
"<tr style='background:#1F4E78;color:#fff'>"
|
| 223 |
+
"<th style='padding:7px 10px;text-align:left'>Document</th>"
|
| 224 |
+
"<th style='padding:7px 10px;text-align:left'>Date</th>"
|
| 225 |
+
"<th style='padding:7px 10px;text-align:left'>Due</th>"
|
| 226 |
+
"<th style='padding:7px 10px;text-align:left'>Status</th>"
|
| 227 |
+
"<th style='padding:7px 10px;text-align:right'>Open Balance</th></tr>"
|
| 228 |
+
+ ''.join(lines) +
|
| 229 |
+
f"<tr><td colspan='4' style='padding:8px 10px;font-weight:bold;text-align:right'>Total open</td>"
|
| 230 |
+
f"<td style='padding:8px 10px;font-weight:bold;text-align:right'>${total_open:,.2f}</td></tr>"
|
| 231 |
+
f"<tr><td colspan='4' style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>Of which overdue</td>"
|
| 232 |
+
f"<td style='padding:2px 10px;font-weight:bold;text-align:right;color:#C0392B'>${row['Overdue']:,.2f}</td></tr>"
|
| 233 |
+
"</table>")
|
| 234 |
+
|
| 235 |
+
return (f"<div style='font-family:Calibri,Arial,sans-serif;color:#1a1a1a;font-size:14px'>"
|
| 236 |
+
f"{intro}{table}{footer}</div>")
|
| 237 |
+
|
| 238 |
+
|
| 239 |
+
def queue_statement(odoo, row, subject_tpl=DEFAULT_SUBJECT,
|
| 240 |
+
intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER,
|
| 241 |
+
override_to=None):
|
| 242 |
+
"""Queue one statement email in Odoo. Returns mail.mail id.
|
| 243 |
+
override_to: send to a different address (used by the test-send button)."""
|
| 244 |
+
to = override_to or row['Email']
|
| 245 |
+
if not to:
|
| 246 |
+
raise ValueError(f"{row['Customer']} has no email address")
|
| 247 |
+
# Hard guardrail β refuse any recipient outside the allow-list while SAFE_MODE is on.
|
| 248 |
+
if not safe_recipient_ok(to):
|
| 249 |
+
raise SafeModeBlocked(
|
| 250 |
+
f"Guardrail ON: refusing to email {to}. Only {', '.join(sorted(SAFE_RECIPIENTS))} "
|
| 251 |
+
f"is allowed right now. (Set SAFE_MODE=0 to send to real customers.)")
|
| 252 |
+
month = dt.date.today().strftime('%B %Y')
|
| 253 |
+
subject = subject_tpl.format(customer=row['Customer'], company=COMPANY, month=month)
|
| 254 |
+
payload = {
|
| 255 |
+
'subject': subject,
|
| 256 |
+
'body_html': render_statement_html(row, intro_tpl, footer_tpl),
|
| 257 |
+
'email_to': to,
|
| 258 |
+
'email_from': SENDER_DISPLAY, # From: Royal Imports
|
| 259 |
+
'reply_to': REPLY_TO, # replies -> AR
|
| 260 |
+
'mail_server_id': ROYAL_MAIL_SERVER_ID, # force Royal O365 relay
|
| 261 |
+
'author_id': ROYAL_AUTHOR_ID, # clean attribution in chatter
|
| 262 |
+
'state': 'outgoing',
|
| 263 |
+
'auto_delete': False,
|
| 264 |
+
'model': 'res.partner',
|
| 265 |
+
'res_id': row['partner_id'],
|
| 266 |
+
}
|
| 267 |
+
return odoo.queue_mail(payload)
|
requirements.txt
CHANGED
|
@@ -1,55 +1,55 @@
|
|
| 1 |
-
# AIOS web API β the FastAPI backend + the platform data-layer deps it reuses.
|
| 2 |
-
#
|
| 3 |
-
# β STREAMLIT IS GONE (EXIT-6, 2026-08-04) β do not add it back. The line here read
|
| 4 |
-
# `streamlit==1.58.0` with the comment "included only because the shared modules/core may import
|
| 5 |
-
# it at load; it is never served". That stopped being true when the shared layer was cleaned, and
|
| 6 |
-
# it stayed in THIS file β the one the Dockerfile actually installs β while `api/requirements.txt`
|
| 7 |
-
# had already dropped it and a gate reported the omission "verified". ~250 MB of image for a
|
| 8 |
-
# package nothing imported.
|
| 9 |
-
#
|
| 10 |
-
# The lesson is the file, not the package: the PINNED intent and the SHIPPED manifest are two
|
| 11 |
-
# different documents, and checking only the one you wrote is how the other rots.
|
| 12 |
-
# `api/verify_no_streamlit.py` now checks BOTH, and proves the API imports with streamlit,
|
| 13 |
-
# plotly, altair, openpyxl, reportlab and jinja2 all blocked at sys.meta_path.
|
| 14 |
-
# No altair/plotly/reportlab either β those were Streamlit UI/export only. openpyxl RETURNED in
|
| 15 |
-
# wave 21 (C5) as a LAZY dep of routes_uploads.py β the boot proof above still holds because the
|
| 16 |
-
# import lives inside the handler, and the gate now asserts this line exists here.
|
| 17 |
-
fastapi>=0.139
|
| 18 |
-
uvicorn[standard]>=0.30
|
| 19 |
-
python-dotenv>=1.0
|
| 20 |
-
pandas>=2.0
|
| 21 |
-
requests>=2.28
|
| 22 |
-
huggingface_hub>=0.20
|
| 23 |
-
duckdb>=1.0
|
| 24 |
-
pyyaml>=6.0
|
| 25 |
-
pillow>=10.0
|
| 26 |
-
beautifulsoup4>=4.12
|
| 27 |
-
lxml>=5.0
|
| 28 |
-
cryptography>=42.0
|
| 29 |
-
# β WAVE 20 (R1 / D-4) β THE POSTGRES DRIVER, AND IT IS LOAD-BEARING IN THIS FILE SPECIFICALLY.
|
| 30 |
-
# `core/store_pg.py` is the store backend from this wave on, and it is deliberately FAIL-CLOSED:
|
| 31 |
-
# `_pool()` raises rather than falling back to the HF file store, so a container that gets
|
| 32 |
-
# `STORE_BACKEND=pg` without this line does not degrade β it refuses every request that touches
|
| 33 |
-
# the store, which is every authenticated request.
|
| 34 |
-
#
|
| 35 |
-
# β AND THIS IS THE FILE THAT MATTERS: the Dockerfile does `COPY requirements.txt` from the
|
| 36 |
-
# Space root, i.e. THIS manifest, not `api/requirements.txt`. That header's own streamlit story
|
| 37 |
-
# is the same defect in the other direction β the pinned intent and the shipped manifest are two
|
| 38 |
-
# documents. psycopg is now in BOTH, and `ops/verify_portability.py` gates the pair.
|
| 39 |
-
psycopg[binary,pool]>=3.2
|
| 40 |
-
# β WAVE 21 (item 11, C5) β .xlsx preview for Select-from-file; lazy-imported in
|
| 41 |
-
# routes_uploads.py only. verify_no_streamlit asserts this line in BOTH manifests.
|
| 42 |
-
openpyxl>=3.1
|
| 43 |
-
# β AND ITS TRANSPORT, learned from a RUNTIME_ERROR on the first v6 boot: FastAPI demands
|
| 44 |
-
# python-multipart AT IMPORT TIME for any route declaring File(...)/Form(...). Every local gate
|
| 45 |
-
# was green because the dev box happens to have it for unrelated reasons β the container
|
| 46 |
-
# installs exactly this file. The environment-parity twin of the streamlit lesson above.
|
| 47 |
-
python-multipart>=0.0.20
|
| 48 |
-
# β WAVE 37 (D-346, answering `ASK E-1`) β THE OFFICIAL ANTHROPIC SDK. `ai_review.py` called the
|
| 49 |
-
# Messages API over raw `requests`, which meant re-implementing retries, streaming and error
|
| 50 |
-
# taxonomy by hand and drifting from them silently. E ships the SDK behind a LAZY import with the
|
| 51 |
-
# raw-HTTP call still there as the fallback, so the feature works with or without this line β what
|
| 52 |
-
# the line does is turn the fallback into dead weight instead of the live path.
|
| 53 |
-
# β BOTH MANIFESTS, NOT ONE. This file's own streamlit story at the top is exactly what pinning
|
| 54 |
-
# one of them looks like a year later.
|
| 55 |
-
anthropic>=0.96
|
|
|
|
| 1 |
+
# AIOS web API β the FastAPI backend + the platform data-layer deps it reuses.
|
| 2 |
+
#
|
| 3 |
+
# β STREAMLIT IS GONE (EXIT-6, 2026-08-04) β do not add it back. The line here read
|
| 4 |
+
# `streamlit==1.58.0` with the comment "included only because the shared modules/core may import
|
| 5 |
+
# it at load; it is never served". That stopped being true when the shared layer was cleaned, and
|
| 6 |
+
# it stayed in THIS file β the one the Dockerfile actually installs β while `api/requirements.txt`
|
| 7 |
+
# had already dropped it and a gate reported the omission "verified". ~250 MB of image for a
|
| 8 |
+
# package nothing imported.
|
| 9 |
+
#
|
| 10 |
+
# The lesson is the file, not the package: the PINNED intent and the SHIPPED manifest are two
|
| 11 |
+
# different documents, and checking only the one you wrote is how the other rots.
|
| 12 |
+
# `api/verify_no_streamlit.py` now checks BOTH, and proves the API imports with streamlit,
|
| 13 |
+
# plotly, altair, openpyxl, reportlab and jinja2 all blocked at sys.meta_path.
|
| 14 |
+
# No altair/plotly/reportlab either β those were Streamlit UI/export only. openpyxl RETURNED in
|
| 15 |
+
# wave 21 (C5) as a LAZY dep of routes_uploads.py β the boot proof above still holds because the
|
| 16 |
+
# import lives inside the handler, and the gate now asserts this line exists here.
|
| 17 |
+
fastapi>=0.139
|
| 18 |
+
uvicorn[standard]>=0.30
|
| 19 |
+
python-dotenv>=1.0
|
| 20 |
+
pandas>=2.0
|
| 21 |
+
requests>=2.28
|
| 22 |
+
huggingface_hub>=0.20
|
| 23 |
+
duckdb>=1.0
|
| 24 |
+
pyyaml>=6.0
|
| 25 |
+
pillow>=10.0
|
| 26 |
+
beautifulsoup4>=4.12
|
| 27 |
+
lxml>=5.0
|
| 28 |
+
cryptography>=42.0
|
| 29 |
+
# β WAVE 20 (R1 / D-4) β THE POSTGRES DRIVER, AND IT IS LOAD-BEARING IN THIS FILE SPECIFICALLY.
|
| 30 |
+
# `core/store_pg.py` is the store backend from this wave on, and it is deliberately FAIL-CLOSED:
|
| 31 |
+
# `_pool()` raises rather than falling back to the HF file store, so a container that gets
|
| 32 |
+
# `STORE_BACKEND=pg` without this line does not degrade β it refuses every request that touches
|
| 33 |
+
# the store, which is every authenticated request.
|
| 34 |
+
#
|
| 35 |
+
# β AND THIS IS THE FILE THAT MATTERS: the Dockerfile does `COPY requirements.txt` from the
|
| 36 |
+
# Space root, i.e. THIS manifest, not `api/requirements.txt`. That header's own streamlit story
|
| 37 |
+
# is the same defect in the other direction β the pinned intent and the shipped manifest are two
|
| 38 |
+
# documents. psycopg is now in BOTH, and `ops/verify_portability.py` gates the pair.
|
| 39 |
+
psycopg[binary,pool]>=3.2
|
| 40 |
+
# β WAVE 21 (item 11, C5) β .xlsx preview for Select-from-file; lazy-imported in
|
| 41 |
+
# routes_uploads.py only. verify_no_streamlit asserts this line in BOTH manifests.
|
| 42 |
+
openpyxl>=3.1
|
| 43 |
+
# β AND ITS TRANSPORT, learned from a RUNTIME_ERROR on the first v6 boot: FastAPI demands
|
| 44 |
+
# python-multipart AT IMPORT TIME for any route declaring File(...)/Form(...). Every local gate
|
| 45 |
+
# was green because the dev box happens to have it for unrelated reasons β the container
|
| 46 |
+
# installs exactly this file. The environment-parity twin of the streamlit lesson above.
|
| 47 |
+
python-multipart>=0.0.20
|
| 48 |
+
# β WAVE 37 (D-346, answering `ASK E-1`) β THE OFFICIAL ANTHROPIC SDK. `ai_review.py` called the
|
| 49 |
+
# Messages API over raw `requests`, which meant re-implementing retries, streaming and error
|
| 50 |
+
# taxonomy by hand and drifting from them silently. E ships the SDK behind a LAZY import with the
|
| 51 |
+
# raw-HTTP call still there as the fallback, so the feature works with or without this line β what
|
| 52 |
+
# the line does is turn the fallback into dead weight instead of the live path.
|
| 53 |
+
# β BOTH MANIFESTS, NOT ONE. This file's own streamlit story at the top is exactly what pinning
|
| 54 |
+
# one of them looks like a year later.
|
| 55 |
+
anthropic>=0.96
|
web/index.html
CHANGED
|
@@ -1,46 +1,46 @@
|
|
| 1 |
-
<!doctype html>
|
| 2 |
-
<html lang="en">
|
| 3 |
-
<head>
|
| 4 |
-
<meta charset="UTF-8" />
|
| 5 |
-
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
| 6 |
-
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
| 7 |
-
<title>Loopable</title>
|
| 8 |
-
</head>
|
| 9 |
-
<body>
|
| 10 |
-
<!-- ββ WAVE 37 Β· T48 β THE BOOT SKELETON, AND EVERY CHOICE HERE IS FORCED BY WHEN IT HAS TO
|
| 11 |
-
PAINT. Measured on the deployed build (proto/P4-first-load.md Β§A.2): `#root` was EMPTY and
|
| 12 |
-
the screen white for 6.0β8.0 s of an 11.6β16.0 s first open, while one 580 KB entry chunk
|
| 13 |
-
downloaded and parsed. The `<body>` was two empty divs, so there was nothing to show.
|
| 14 |
-
|
| 15 |
-
β INLINE STYLES, NOT A CLASS. `index.css` is its own ~324 KB render-blocking chunk that
|
| 16 |
-
took 3.3 s in that same trace β a skeleton styled from it would wait for the exact asset
|
| 17 |
-
whose arrival it exists to cover, and paint white until then. Inline is the only thing that
|
| 18 |
-
can render from the HTML alone.
|
| 19 |
-
|
| 20 |
-
β INSIDE `#root`, NOT BESIDE IT. `createRoot(...).render()` REPLACES the container's
|
| 21 |
-
children, so this is removed by the mount itself. A skeleton outside `#root` needs JS to
|
| 22 |
-
take it away, which is a second thing that can fail and a flash-of-two-uis if it does.
|
| 23 |
-
|
| 24 |
-
β NO ANIMATION. A shimmer would be a keyframe the CSS chunk has not delivered yet, and a
|
| 25 |
-
static block that never moves is honest about a page that is still downloading; a frozen
|
| 26 |
-
shimmer would read as a hung app. `aria-hidden` + `role="presentation"`: a screen reader
|
| 27 |
-
should hear the app, not its scaffolding. -->
|
| 28 |
-
<div id="root"><div aria-hidden="true" role="presentation" style="height:100vh;display:flex;flex-direction:column;background:#ffffff">
|
| 29 |
-
<div style="height:44px;flex:none;border-bottom:1px solid #e8e8ea;display:flex;align-items:center;padding:0 14px">
|
| 30 |
-
<div style="width:22px;height:22px;border-radius:11px;background:#efedf9"></div>
|
| 31 |
-
<div style="width:96px;height:12px;margin-left:10px;border-radius:3px;background:#efedf9"></div>
|
| 32 |
-
</div>
|
| 33 |
-
<div style="flex:1;display:flex;min-height:0">
|
| 34 |
-
<div style="width:288px;flex:none;border-right:1px solid #e8e8ea;padding:14px 12px">
|
| 35 |
-
<div style="height:11px;width:64%;border-radius:3px;background:#f1f0f4;margin-bottom:14px"></div>
|
| 36 |
-
<div style="height:11px;width:78%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
|
| 37 |
-
<div style="height:11px;width:54%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
|
| 38 |
-
<div style="height:11px;width:70%;border-radius:3px;background:#f4f3f7"></div>
|
| 39 |
-
</div>
|
| 40 |
-
<div style="flex:1;background:#fafafb"></div>
|
| 41 |
-
</div>
|
| 42 |
-
</div></div>
|
| 43 |
-
<div id="portal"></div>
|
| 44 |
-
<script type="module" src="/src/main.tsx"></script>
|
| 45 |
-
</body>
|
| 46 |
-
</html>
|
|
|
|
| 1 |
+
<!doctype html>
|
| 2 |
+
<html lang="en">
|
| 3 |
+
<head>
|
| 4 |
+
<meta charset="UTF-8" />
|
| 5 |
+
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
| 6 |
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
| 7 |
+
<title>Loopable</title>
|
| 8 |
+
</head>
|
| 9 |
+
<body>
|
| 10 |
+
<!-- ββ WAVE 37 Β· T48 β THE BOOT SKELETON, AND EVERY CHOICE HERE IS FORCED BY WHEN IT HAS TO
|
| 11 |
+
PAINT. Measured on the deployed build (proto/P4-first-load.md Β§A.2): `#root` was EMPTY and
|
| 12 |
+
the screen white for 6.0β8.0 s of an 11.6β16.0 s first open, while one 580 KB entry chunk
|
| 13 |
+
downloaded and parsed. The `<body>` was two empty divs, so there was nothing to show.
|
| 14 |
+
|
| 15 |
+
β INLINE STYLES, NOT A CLASS. `index.css` is its own ~324 KB render-blocking chunk that
|
| 16 |
+
took 3.3 s in that same trace β a skeleton styled from it would wait for the exact asset
|
| 17 |
+
whose arrival it exists to cover, and paint white until then. Inline is the only thing that
|
| 18 |
+
can render from the HTML alone.
|
| 19 |
+
|
| 20 |
+
β INSIDE `#root`, NOT BESIDE IT. `createRoot(...).render()` REPLACES the container's
|
| 21 |
+
children, so this is removed by the mount itself. A skeleton outside `#root` needs JS to
|
| 22 |
+
take it away, which is a second thing that can fail and a flash-of-two-uis if it does.
|
| 23 |
+
|
| 24 |
+
β NO ANIMATION. A shimmer would be a keyframe the CSS chunk has not delivered yet, and a
|
| 25 |
+
static block that never moves is honest about a page that is still downloading; a frozen
|
| 26 |
+
shimmer would read as a hung app. `aria-hidden` + `role="presentation"`: a screen reader
|
| 27 |
+
should hear the app, not its scaffolding. -->
|
| 28 |
+
<div id="root"><div aria-hidden="true" role="presentation" style="height:100vh;display:flex;flex-direction:column;background:#ffffff">
|
| 29 |
+
<div style="height:44px;flex:none;border-bottom:1px solid #e8e8ea;display:flex;align-items:center;padding:0 14px">
|
| 30 |
+
<div style="width:22px;height:22px;border-radius:11px;background:#efedf9"></div>
|
| 31 |
+
<div style="width:96px;height:12px;margin-left:10px;border-radius:3px;background:#efedf9"></div>
|
| 32 |
+
</div>
|
| 33 |
+
<div style="flex:1;display:flex;min-height:0">
|
| 34 |
+
<div style="width:288px;flex:none;border-right:1px solid #e8e8ea;padding:14px 12px">
|
| 35 |
+
<div style="height:11px;width:64%;border-radius:3px;background:#f1f0f4;margin-bottom:14px"></div>
|
| 36 |
+
<div style="height:11px;width:78%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
|
| 37 |
+
<div style="height:11px;width:54%;border-radius:3px;background:#f4f3f7;margin-bottom:10px"></div>
|
| 38 |
+
<div style="height:11px;width:70%;border-radius:3px;background:#f4f3f7"></div>
|
| 39 |
+
</div>
|
| 40 |
+
<div style="flex:1;background:#fafafb"></div>
|
| 41 |
+
</div>
|
| 42 |
+
</div></div>
|
| 43 |
+
<div id="portal"></div>
|
| 44 |
+
<script type="module" src="/src/main.tsx"></script>
|
| 45 |
+
</body>
|
| 46 |
+
</html>
|
web/src/App.tsx
CHANGED
|
@@ -1,41 +1,41 @@
|
|
| 1 |
-
import { Suspense, lazy } from "react";
|
| 2 |
-
// ββ WAVE 37 Β· T48 β LAZY, AND IT IS THE LAST OF THE THREE EAGER IMPORTS. `CustomerGrid` (7,715
|
| 3 |
-
// lines) plus glide-data-grid sat in the ENTRY chunk because these three files imported it at the
|
| 4 |
-
// top level, while twelve other surfaces were already `lazy()`. Measured on the deployed build
|
| 5 |
-
// (`proto/P4-first-load.md` Β§A.2): the entry chunk was 580,102 B on the wire and took 5.6-5.8 s,
|
| 6 |
-
// during which `#root` was EMPTY and the screen was white β 6.0-8.0 s of the 11.6-16.0 s first open.
|
| 7 |
-
// β THE EMBED PAYS THIS TOO, and it is the one path where the grid IS the page, so its fallback is
|
| 8 |
-
// deliberately the same skeleton shape the shell uses rather than `null`: a blank iframe is
|
| 9 |
-
// indistinguishable from a broken one.
|
| 10 |
-
const CustomerGrid = lazy(() => import("./customer-grid/CustomerGrid"));
|
| 11 |
-
import { OverlayProvider } from "./customer-grid/OverlaySurface";
|
| 12 |
-
import { isStreamlitComponent } from "./customer-grid/hostBridge";
|
| 13 |
-
import Shell from "./shell/Shell";
|
| 14 |
-
|
| 15 |
-
// HOSTED = either Streamlit path (the component iframe, or the legacy injected
|
| 16 |
-
// payload). There the surrounding app owns all chrome and this tree renders the
|
| 17 |
-
// BARE grid, byte-for-byte the behavior the embed always had. Only the
|
| 18 |
-
// standalone build gets the shell (wave 4, the strangler frame). Computed once
|
| 19 |
-
// at module level, like useCustomerData's own mode constants β the host mode
|
| 20 |
-
// cannot change within a page lifetime.
|
| 21 |
-
// EXPORTED (EXIT wave 1): main.tsx needs the same answer to decide whether to
|
| 22 |
-
// install the standalone event sink, and two copies of a mode predicate is how
|
| 23 |
-
// the two halves of "standalone-only" end up disagreeing.
|
| 24 |
-
export const HOSTED =
|
| 25 |
-
isStreamlitComponent() ||
|
| 26 |
-
typeof (window as unknown as { __AIOS_GRID__?: unknown }).__AIOS_GRID__ !== "undefined";
|
| 27 |
-
|
| 28 |
-
export default function App() {
|
| 29 |
-
if (HOSTED) {
|
| 30 |
-
return (
|
| 31 |
-
<div style={{ width: "100%", height: "100%", overflow: "hidden" }}>
|
| 32 |
-
<OverlayProvider>
|
| 33 |
-
<Suspense fallback={<div className="lp-boot" aria-hidden="true" />}>
|
| 34 |
-
<CustomerGrid />
|
| 35 |
-
</Suspense>
|
| 36 |
-
</OverlayProvider>
|
| 37 |
-
</div>
|
| 38 |
-
);
|
| 39 |
-
}
|
| 40 |
-
return <Shell />;
|
| 41 |
-
}
|
|
|
|
| 1 |
+
import { Suspense, lazy } from "react";
|
| 2 |
+
// ββ WAVE 37 Β· T48 β LAZY, AND IT IS THE LAST OF THE THREE EAGER IMPORTS. `CustomerGrid` (7,715
|
| 3 |
+
// lines) plus glide-data-grid sat in the ENTRY chunk because these three files imported it at the
|
| 4 |
+
// top level, while twelve other surfaces were already `lazy()`. Measured on the deployed build
|
| 5 |
+
// (`proto/P4-first-load.md` Β§A.2): the entry chunk was 580,102 B on the wire and took 5.6-5.8 s,
|
| 6 |
+
// during which `#root` was EMPTY and the screen was white β 6.0-8.0 s of the 11.6-16.0 s first open.
|
| 7 |
+
// β THE EMBED PAYS THIS TOO, and it is the one path where the grid IS the page, so its fallback is
|
| 8 |
+
// deliberately the same skeleton shape the shell uses rather than `null`: a blank iframe is
|
| 9 |
+
// indistinguishable from a broken one.
|
| 10 |
+
const CustomerGrid = lazy(() => import("./customer-grid/CustomerGrid"));
|
| 11 |
+
import { OverlayProvider } from "./customer-grid/OverlaySurface";
|
| 12 |
+
import { isStreamlitComponent } from "./customer-grid/hostBridge";
|
| 13 |
+
import Shell from "./shell/Shell";
|
| 14 |
+
|
| 15 |
+
// HOSTED = either Streamlit path (the component iframe, or the legacy injected
|
| 16 |
+
// payload). There the surrounding app owns all chrome and this tree renders the
|
| 17 |
+
// BARE grid, byte-for-byte the behavior the embed always had. Only the
|
| 18 |
+
// standalone build gets the shell (wave 4, the strangler frame). Computed once
|
| 19 |
+
// at module level, like useCustomerData's own mode constants β the host mode
|
| 20 |
+
// cannot change within a page lifetime.
|
| 21 |
+
// EXPORTED (EXIT wave 1): main.tsx needs the same answer to decide whether to
|
| 22 |
+
// install the standalone event sink, and two copies of a mode predicate is how
|
| 23 |
+
// the two halves of "standalone-only" end up disagreeing.
|
| 24 |
+
export const HOSTED =
|
| 25 |
+
isStreamlitComponent() ||
|
| 26 |
+
typeof (window as unknown as { __AIOS_GRID__?: unknown }).__AIOS_GRID__ !== "undefined";
|
| 27 |
+
|
| 28 |
+
export default function App() {
|
| 29 |
+
if (HOSTED) {
|
| 30 |
+
return (
|
| 31 |
+
<div style={{ width: "100%", height: "100%", overflow: "hidden" }}>
|
| 32 |
+
<OverlayProvider>
|
| 33 |
+
<Suspense fallback={<div className="lp-boot" aria-hidden="true" />}>
|
| 34 |
+
<CustomerGrid />
|
| 35 |
+
</Suspense>
|
| 36 |
+
</OverlayProvider>
|
| 37 |
+
</div>
|
| 38 |
+
);
|
| 39 |
+
}
|
| 40 |
+
return <Shell />;
|
| 41 |
+
}
|
web/src/account/SubscriptionPage.tsx
CHANGED
|
@@ -1,49 +1,49 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// account/SubscriptionPage.tsx β WAVE 35 Β· W35-T20 (owner item 13, contract C6).
|
| 3 |
-
//
|
| 4 |
-
// Owner item 13, verbatim: *"add below settings the following button: Feedback β¦,
|
| 5 |
-
// Usage credits β¦, and a Subscription module β¦ Specialized for the Royal Imports
|
| 6 |
-
// tenant, do not show it."*
|
| 7 |
-
// β "verbatim" IS THE POINT: W37-T02 renamed that surface to "Usage" and this quote KEEPS the
|
| 8 |
-
// owner's own wording. A quote edited to match a later rename is no longer evidence of anything.
|
| 9 |
-
//
|
| 10 |
-
// This is the third of those three, and the only one with nothing behind it yet.
|
| 11 |
-
// So it says so, in the words this app already uses for a boarded door
|
| 12 |
-
// (`Shell.tsx`'s templates note: "Under construction. β¦ will open here in a later
|
| 13 |
-
// release."). One voice for one state β DESIGN.md 1's "variety is a defect".
|
| 14 |
-
//
|
| 15 |
-
// β THIS PAGE DOES NOT HIDE ITSELF, AND THAT IS THE TICKET'S OWN TRAP.
|
| 16 |
-
// C6 puts the Royal Imports rule in TWO places that are both the frame's: the
|
| 17 |
-
// account MENU does not draw the row, and the ROUTE refuses. A third opinion here
|
| 18 |
-
// would be a third thing to keep in step, and the day they disagree the reader
|
| 19 |
-
// gets a menu row that opens a page which says it does not exist. The page renders
|
| 20 |
-
// the same for every tenant that can reach it, because reaching it IS the decision.
|
| 21 |
-
//
|
| 22 |
-
// β AND IT TAKES NO PROPS, WHICH IS ALSO A DECISION rather than an omission.
|
| 23 |
-
// The wave's rule is that a prop must be REQUIRED, never optional β an optional one
|
| 24 |
-
// degrades to "the page does not exist", which is indistinguishable from never
|
| 25 |
-
// built. That rule constrains the props that EXIST; it does not ask for a prop that
|
| 26 |
-
// carries nothing. There is nothing this page needs from the frame: it holds no
|
| 27 |
-
// state, makes no call, and takes no decision the frame has already taken. A
|
| 28 |
-
// `tenant` prop here would be exactly the second opinion the paragraph above
|
| 29 |
-
// refuses. The mount is proven by A's `verify_wiring` row (W2), not by a signature.
|
| 30 |
-
// ---------------------------------------------------------------------------
|
| 31 |
-
|
| 32 |
-
import "./account.css";
|
| 33 |
-
|
| 34 |
-
export default function SubscriptionPage() {
|
| 35 |
-
return (
|
| 36 |
-
<div className="acct-page">
|
| 37 |
-
<h1 className="acct-title">Subscription</h1>
|
| 38 |
-
<div className="acct-col">
|
| 39 |
-
{/* β TWO SHORT SENTENCES AND NO TOUR (DESIGN.md 4 / wave-22 R13: the app does not
|
| 40 |
-
narrate itself). The reader arrived here on purpose and wants one fact: is there
|
| 41 |
-
anything to do? There is not, and every further word would be spent on someone
|
| 42 |
-
who is already leaving. No feature list, no roadmap, no "in the meantime". */}
|
| 43 |
-
<p className="acct-note">
|
| 44 |
-
Under construction. Plans, billing and invoices will open here in a later release.
|
| 45 |
-
</p>
|
| 46 |
-
</div>
|
| 47 |
-
</div>
|
| 48 |
-
);
|
| 49 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// account/SubscriptionPage.tsx β WAVE 35 Β· W35-T20 (owner item 13, contract C6).
|
| 3 |
+
//
|
| 4 |
+
// Owner item 13, verbatim: *"add below settings the following button: Feedback β¦,
|
| 5 |
+
// Usage credits β¦, and a Subscription module β¦ Specialized for the Royal Imports
|
| 6 |
+
// tenant, do not show it."*
|
| 7 |
+
// β "verbatim" IS THE POINT: W37-T02 renamed that surface to "Usage" and this quote KEEPS the
|
| 8 |
+
// owner's own wording. A quote edited to match a later rename is no longer evidence of anything.
|
| 9 |
+
//
|
| 10 |
+
// This is the third of those three, and the only one with nothing behind it yet.
|
| 11 |
+
// So it says so, in the words this app already uses for a boarded door
|
| 12 |
+
// (`Shell.tsx`'s templates note: "Under construction. β¦ will open here in a later
|
| 13 |
+
// release."). One voice for one state β DESIGN.md 1's "variety is a defect".
|
| 14 |
+
//
|
| 15 |
+
// β THIS PAGE DOES NOT HIDE ITSELF, AND THAT IS THE TICKET'S OWN TRAP.
|
| 16 |
+
// C6 puts the Royal Imports rule in TWO places that are both the frame's: the
|
| 17 |
+
// account MENU does not draw the row, and the ROUTE refuses. A third opinion here
|
| 18 |
+
// would be a third thing to keep in step, and the day they disagree the reader
|
| 19 |
+
// gets a menu row that opens a page which says it does not exist. The page renders
|
| 20 |
+
// the same for every tenant that can reach it, because reaching it IS the decision.
|
| 21 |
+
//
|
| 22 |
+
// β AND IT TAKES NO PROPS, WHICH IS ALSO A DECISION rather than an omission.
|
| 23 |
+
// The wave's rule is that a prop must be REQUIRED, never optional β an optional one
|
| 24 |
+
// degrades to "the page does not exist", which is indistinguishable from never
|
| 25 |
+
// built. That rule constrains the props that EXIST; it does not ask for a prop that
|
| 26 |
+
// carries nothing. There is nothing this page needs from the frame: it holds no
|
| 27 |
+
// state, makes no call, and takes no decision the frame has already taken. A
|
| 28 |
+
// `tenant` prop here would be exactly the second opinion the paragraph above
|
| 29 |
+
// refuses. The mount is proven by A's `verify_wiring` row (W2), not by a signature.
|
| 30 |
+
// ---------------------------------------------------------------------------
|
| 31 |
+
|
| 32 |
+
import "./account.css";
|
| 33 |
+
|
| 34 |
+
export default function SubscriptionPage() {
|
| 35 |
+
return (
|
| 36 |
+
<div className="acct-page">
|
| 37 |
+
<h1 className="acct-title">Subscription</h1>
|
| 38 |
+
<div className="acct-col">
|
| 39 |
+
{/* β TWO SHORT SENTENCES AND NO TOUR (DESIGN.md 4 / wave-22 R13: the app does not
|
| 40 |
+
narrate itself). The reader arrived here on purpose and wants one fact: is there
|
| 41 |
+
anything to do? There is not, and every further word would be spent on someone
|
| 42 |
+
who is already leaving. No feature list, no roadmap, no "in the meantime". */}
|
| 43 |
+
<p className="acct-note">
|
| 44 |
+
Under construction. Plans, billing and invoices will open here in a later release.
|
| 45 |
+
</p>
|
| 46 |
+
</div>
|
| 47 |
+
</div>
|
| 48 |
+
);
|
| 49 |
+
}
|
web/src/account/UsagePage.tsx
CHANGED
|
@@ -1,297 +1,297 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// account/UsagePage.tsx β WAVE 35 Β· W35-T19 (owner item 13, ruling R9, C6/C7).
|
| 3 |
-
//
|
| 4 |
-
// R9: ONE meter for every AI surface. It REPORTS weekly usage against an
|
| 5 |
-
// allowance and does not cut anyone off this wave; over the allowance the
|
| 6 |
-
// product still works and the bar is red.
|
| 7 |
-
//
|
| 8 |
-
// ββ THIS PAGE MAY NOT INVENT A FIGURE, AND THAT IS THE WHOLE TICKET.
|
| 9 |
-
// Every number here comes off `GET /usage` β the week, the reset date, the
|
| 10 |
-
// allowance, each surface's tokens and calls. Nothing is derived from a clock,
|
| 11 |
-
// nothing is estimated, and a surface with no ledger lines shows **0**, not a
|
| 12 |
-
// blank and not an omission (E-9 guarantees all four surfaces are always
|
| 13 |
-
// present, so there is no missing-row branch to get wrong).
|
| 14 |
-
// [[no-unverifiable-aggregates]]
|
| 15 |
-
//
|
| 16 |
-
// β AND `unmeasured` IS RENDERED, NOT SWALLOWED. Those are real calls whose
|
| 17 |
-
// provider declined to report a token count, so the total beside them is a
|
| 18 |
-
// FLOOR. A page that hides them presents the floor as a complete figure, which
|
| 19 |
-
// is the cost-surprise failure one step removed β the same reason
|
| 20 |
-
// `usage_ledger` books an unmeasured call as unknown rather than as zero.
|
| 21 |
-
//
|
| 22 |
-
// β SURFACE/READ SPLIT, as on Home and Starred: `renderToStaticMarkup` runs no
|
| 23 |
-
// effect, so a shot of the fetching component photographs only its spinner.
|
| 24 |
-
// ---------------------------------------------------------------------------
|
| 25 |
-
|
| 26 |
-
import { useCallback, useEffect, useRef, useState } from "react";
|
| 27 |
-
|
| 28 |
-
import { fmt } from "../ui/fmt";
|
| 29 |
-
import { loadUsage } from "./accountApi";
|
| 30 |
-
import type { Usage, UsageSurface } from "./accountApi";
|
| 31 |
-
import "./account.css";
|
| 32 |
-
|
| 33 |
-
/**
|
| 34 |
-
* The four surfaces C7 names, in the order R9 lists them.
|
| 35 |
-
*
|
| 36 |
-
* β AN UNKNOWN KEY IS HUMANISED, NEVER DROPPED. Dropping it would hide real usage from a meter
|
| 37 |
-
* whose whole job is to account for it, and printing the raw key would put an internal identifier
|
| 38 |
-
* on screen. The day a fifth LLM entry point lands (this product added two in one wave) it shows
|
| 39 |
-
* up here as a readable name with the right number beside it, and somebody can then decide what
|
| 40 |
-
* to call it.
|
| 41 |
-
*/
|
| 42 |
-
const SURFACE_LABEL: Record<string, string> = {
|
| 43 |
-
assistant: "Assistant",
|
| 44 |
-
field_agent: "Field agents",
|
| 45 |
-
ai_review: "Reviews",
|
| 46 |
-
automation_draft: "Drafting",
|
| 47 |
-
};
|
| 48 |
-
const ORDER = ["assistant", "field_agent", "ai_review", "automation_draft"];
|
| 49 |
-
|
| 50 |
-
export function surfaceLabel(key: string): string {
|
| 51 |
-
const known = SURFACE_LABEL[key];
|
| 52 |
-
if (known) return known;
|
| 53 |
-
const words = key.replace(/[_-]+/g, " ").trim();
|
| 54 |
-
return words ? words.charAt(0).toUpperCase() + words.slice(1) : key;
|
| 55 |
-
}
|
| 56 |
-
|
| 57 |
-
/** C7's order first, then anything the server added, alphabetically. */
|
| 58 |
-
export function orderSurfaces(surfaces: UsageSurface[]): UsageSurface[] {
|
| 59 |
-
const rank = (s: UsageSurface) => {
|
| 60 |
-
const i = ORDER.indexOf(s.surface);
|
| 61 |
-
return i === -1 ? ORDER.length : i;
|
| 62 |
-
};
|
| 63 |
-
return [...surfaces].sort(
|
| 64 |
-
(a, b) => rank(a) - rank(b) || surfaceLabel(a.surface).localeCompare(surfaceLabel(b.surface))
|
| 65 |
-
);
|
| 66 |
-
}
|
| 67 |
-
|
| 68 |
-
/**
|
| 69 |
-
* The bar's fill, as a percentage, CLAMPED to 100.
|
| 70 |
-
*
|
| 71 |
-
* β The clamp is what keeps "over the allowance" a COLOUR rather than a bar that overflows its
|
| 72 |
-
* own track and paints across the page. The number above the bar is unclamped and is where the
|
| 73 |
-
* overage is actually read.
|
| 74 |
-
* β An allowance of 0 (unset) yields 0 rather than a division by zero: no allowance means the
|
| 75 |
-
* meter has nothing to measure against, and a full red bar would be an assertion nobody made.
|
| 76 |
-
*/
|
| 77 |
-
export function barPct(value: number, of: number): number {
|
| 78 |
-
if (!(of > 0)) return 0;
|
| 79 |
-
return Math.max(0, Math.min(100, (value / of) * 100));
|
| 80 |
-
}
|
| 81 |
-
|
| 82 |
-
export type UsageLoad =
|
| 83 |
-
| { phase: "loading" }
|
| 84 |
-
| { phase: "ready"; usage: Usage }
|
| 85 |
-
| { phase: "failed"; message: string };
|
| 86 |
-
|
| 87 |
-
function Bar({ pct, over }: { pct: number; over: boolean }) {
|
| 88 |
-
return (
|
| 89 |
-
<span className="acct-bar" aria-hidden="true">
|
| 90 |
-
<span className={"acct-bar-fill" + (over ? " is-over" : "")} style={{ width: `${pct}%` }} />
|
| 91 |
-
</span>
|
| 92 |
-
);
|
| 93 |
-
}
|
| 94 |
-
|
| 95 |
-
export function UsageSurfaceRows({ usage }: { usage: Usage }) {
|
| 96 |
-
// β SCALED TO THE LARGEST SURFACE, NOT TO THE WEEK'S TOTAL, and the difference is legibility
|
| 97 |
-
// rather than accuracy. `total` is the week's whole figure and can legitimately exceed the sum
|
| 98 |
-
// of these four (unattributed calls are counted there and belong to nobody), so scaling to it
|
| 99 |
-
// shrinks every bar by an amount the reader cannot see the cause of. Scaled to the biggest row,
|
| 100 |
-
// the bars answer the question a row of bars is actually asked: which surface is spending most.
|
| 101 |
-
// The absolute number sits beside each one, so nothing here is only readable as a shape.
|
| 102 |
-
const biggest = usage.surfaces.reduce((m, s) => Math.max(m, s.tokens), 0);
|
| 103 |
-
return (
|
| 104 |
-
<div className="acct-rows">
|
| 105 |
-
{orderSurfaces(usage.surfaces).map((s) => (
|
| 106 |
-
<div key={s.surface} className="acct-row">
|
| 107 |
-
<span className="acct-row-name">{surfaceLabel(s.surface)}</span>
|
| 108 |
-
<Bar pct={barPct(s.tokens, biggest)} over={false} />
|
| 109 |
-
<span className="acct-row-num">{fmt.int(s.tokens)}</span>
|
| 110 |
-
<span className="acct-row-sub">
|
| 111 |
-
{fmt.int(s.calls)} {s.calls === 1 ? "call" : "calls"}
|
| 112 |
-
{/* β NOT HOVER-ONLY. A surface whose provider declined to report tokens has a
|
| 113 |
-
token number that is a floor, and D-253 is a booked defect whose entire content
|
| 114 |
-
is "the explanation was satisfied only on hover". */}
|
| 115 |
-
{s.unmeasured > 0 ? `, ${fmt.int(s.unmeasured)} not measured` : ""}
|
| 116 |
-
</span>
|
| 117 |
-
</div>
|
| 118 |
-
))}
|
| 119 |
-
</div>
|
| 120 |
-
);
|
| 121 |
-
}
|
| 122 |
-
|
| 123 |
-
export function UsageView({
|
| 124 |
-
load,
|
| 125 |
-
scope,
|
| 126 |
-
canSeeTenant,
|
| 127 |
-
onScope,
|
| 128 |
-
onRetry,
|
| 129 |
-
}: {
|
| 130 |
-
load: UsageLoad;
|
| 131 |
-
scope: "me" | "tenant";
|
| 132 |
-
/**
|
| 133 |
-
* Whether the workspace view is reachable AT ALL for this account.
|
| 134 |
-
*
|
| 135 |
-
* β THE TOGGLE IS NOT DRAWN WHEN IT IS NOT, and that is R8's fake-affordance rule applied to a
|
| 136 |
-
* permission: `?scope=tenant` is admin-only and 403s for everybody else, so an always-visible
|
| 137 |
-
* control would be a button most accounts can only be refused by.
|
| 138 |
-
*/
|
| 139 |
-
canSeeTenant: boolean;
|
| 140 |
-
onScope: (scope: "me" | "tenant") => void;
|
| 141 |
-
onRetry: () => void;
|
| 142 |
-
}) {
|
| 143 |
-
return (
|
| 144 |
-
<div className="acct-page">
|
| 145 |
-
<h1 className="acct-title">Usage</h1>
|
| 146 |
-
<div className="acct-col">
|
| 147 |
-
{canSeeTenant ? (
|
| 148 |
-
<div className="acct-scope" role="group" aria-label="Whose usage">
|
| 149 |
-
{(["me", "tenant"] as const).map((key) => (
|
| 150 |
-
<button
|
| 151 |
-
key={key}
|
| 152 |
-
type="button"
|
| 153 |
-
className={"acct-scope-btn" + (scope === key ? " is-on" : "")}
|
| 154 |
-
aria-pressed={scope === key}
|
| 155 |
-
onClick={() => onScope(key)}
|
| 156 |
-
>
|
| 157 |
-
{key === "me" ? "You" : "Workspace"}
|
| 158 |
-
</button>
|
| 159 |
-
))}
|
| 160 |
-
</div>
|
| 161 |
-
) : null}
|
| 162 |
-
{load.phase === "loading" ? (
|
| 163 |
-
<div className="acct-loading">
|
| 164 |
-
<span className="lp-spin lp-spin--lg" role="status" aria-label="Loading" />
|
| 165 |
-
</div>
|
| 166 |
-
) : load.phase === "failed" ? (
|
| 167 |
-
// β NOT A ZERO METER. A failed read and a quiet week look identical on screen unless
|
| 168 |
-
// this branch exists, and a meter reading zero is the most reassuring possible lie.
|
| 169 |
-
<div className="acct-failed">
|
| 170 |
-
<p className="acct-note">{load.message}</p>
|
| 171 |
-
<button type="button" className="acct-retry" onClick={onRetry}>
|
| 172 |
-
Try again
|
| 173 |
-
</button>
|
| 174 |
-
</div>
|
| 175 |
-
) : (
|
| 176 |
-
<>
|
| 177 |
-
<div className="acct-meter">
|
| 178 |
-
{/* β THE METER SAYS WHOSE USAGE IT IS, IN WORDS, and that is not decoration. The
|
| 179 |
-
allowance is a WORKSPACE number; the total beside it is this account's own
|
| 180 |
-
unless the scope says otherwise. A meter that shows a personal figure against a
|
| 181 |
-
shared limit without saying so is a ratio nobody can read correctly, and it is
|
| 182 |
-
the one way this page can be wrong while every number on it is right. */}
|
| 183 |
-
<div className="acct-meter-head">
|
| 184 |
-
<span className="acct-meter-who">
|
| 185 |
-
{load.usage.scope === "tenant" ? "This workspace" : "You"}, this week
|
| 186 |
-
</span>
|
| 187 |
-
</div>
|
| 188 |
-
<div className="acct-meter-head">
|
| 189 |
-
<span className={"acct-meter-value" + (load.usage.over ? " is-over" : "")}>
|
| 190 |
-
{fmt.int(load.usage.total)}
|
| 191 |
-
</span>
|
| 192 |
-
<span className="acct-meter-of">
|
| 193 |
-
of {fmt.int(load.usage.allowance)} tokens
|
| 194 |
-
</span>
|
| 195 |
-
</div>
|
| 196 |
-
<Bar pct={barPct(load.usage.total, load.usage.allowance)} over={load.usage.over} />
|
| 197 |
-
<div className="acct-meter-foot">
|
| 198 |
-
{/* Both facts are the SERVER'S: the week it counted and the date it rolls over.
|
| 199 |
-
A week boundary computed in the browser can disagree with the bucketing that
|
| 200 |
-
produced the number above it, and then the page states a period nobody
|
| 201 |
-
measured. */}
|
| 202 |
-
<span>
|
| 203 |
-
Week {load.usage.week}. Resets {fmt.date(load.usage.resets)}.
|
| 204 |
-
</span>
|
| 205 |
-
<span className="acct-meter-calls">
|
| 206 |
-
{fmt.int(load.usage.calls)} {load.usage.calls === 1 ? "call" : "calls"}
|
| 207 |
-
</span>
|
| 208 |
-
</div>
|
| 209 |
-
</div>
|
| 210 |
-
|
| 211 |
-
{/* β R9's whole point, in one line: over the allowance it STILL WORKS. The bar is
|
| 212 |
-
red, nothing is cut off, and the sentence says which of those two is true so
|
| 213 |
-
nobody has to infer it from a colour. */}
|
| 214 |
-
{load.usage.over ? (
|
| 215 |
-
<p className="acct-error" role="status">
|
| 216 |
-
This workspace is over its weekly allowance. Nothing is cut off; the AI surfaces
|
| 217 |
-
keep working.
|
| 218 |
-
</p>
|
| 219 |
-
) : null}
|
| 220 |
-
|
| 221 |
-
{/* The server's own sentence, present only when something really was unmeasured. */}
|
| 222 |
-
{load.usage.note ? <p className="acct-note acct-note--inline">{load.usage.note}</p> : null}
|
| 223 |
-
|
| 224 |
-
<h2 className="acct-section">By surface</h2>
|
| 225 |
-
<UsageSurfaceRows usage={load.usage} />
|
| 226 |
-
|
| 227 |
-
{load.usage.unattributed > 0 ? (
|
| 228 |
-
// β LABELLED A WIRING GAP, NOT USAGE (E-9). These are AI calls this container could
|
| 229 |
-
// not attribute to an account. Folding them into somebody's total would be an
|
| 230 |
-
// invented attribution, and leaving them out entirely would understate the week.
|
| 231 |
-
<p className="acct-note acct-note--inline">
|
| 232 |
-
{fmt.int(load.usage.unattributed)} tokens this week could not be attributed to an
|
| 233 |
-
account. That is a wiring gap in the meter, not somebody's usage.
|
| 234 |
-
</p>
|
| 235 |
-
) : null}
|
| 236 |
-
</>
|
| 237 |
-
)}
|
| 238 |
-
</div>
|
| 239 |
-
</div>
|
| 240 |
-
);
|
| 241 |
-
}
|
| 242 |
-
|
| 243 |
-
export default function UsagePage() {
|
| 244 |
-
const [load, setLoad] = useState<UsageLoad>({ phase: "loading" });
|
| 245 |
-
const [scope, setScope] = useState<"me" | "tenant">("me");
|
| 246 |
-
/**
|
| 247 |
-
* Whether the workspace view exists for this account, ANSWERED BY ASKING ONCE.
|
| 248 |
-
*
|
| 249 |
-
* β WHY A PROBE RATHER THAN A ROLE CHECK. The frame knows the role, but these pages take no
|
| 250 |
-
* props by contract (C6's trap: a page that decides its own visibility is a second opinion that
|
| 251 |
-
* will one day disagree with the route). The route itself is the authority, so the page asks it
|
| 252 |
-
* once: a 200 means the door is open and the toggle is real; a 403 means it is not and no
|
| 253 |
-
* control is drawn. β That 403 is an ANSWER, not an error β it is never shown to the reader.
|
| 254 |
-
* β AND IT IS WHAT GIVES `?scope=tenant` A DOOR. E built it admin-only; without this it would
|
| 255 |
-
* be a finished capability with no caller, which is this repo's most-repeated failure
|
| 256 |
-
* [[reachable-is-not-the-same-as-built]].
|
| 257 |
-
*/
|
| 258 |
-
const [canSeeTenant, setCanSeeTenant] = useState(false);
|
| 259 |
-
const gen = useRef(0);
|
| 260 |
-
|
| 261 |
-
const read = useCallback((which: "me" | "tenant") => {
|
| 262 |
-
const mine = gen.current + 1;
|
| 263 |
-
gen.current = mine;
|
| 264 |
-
setLoad({ phase: "loading" });
|
| 265 |
-
void loadUsage(which === "tenant" ? "tenant" : undefined).then((r) => {
|
| 266 |
-
if (gen.current !== mine) return;
|
| 267 |
-
setLoad(r.ok ? { phase: "ready", usage: r.value } : { phase: "failed", message: r.message });
|
| 268 |
-
});
|
| 269 |
-
}, []);
|
| 270 |
-
|
| 271 |
-
useEffect(() => {
|
| 272 |
-
read(scope);
|
| 273 |
-
return () => {
|
| 274 |
-
gen.current += 1;
|
| 275 |
-
};
|
| 276 |
-
}, [read, scope]);
|
| 277 |
-
|
| 278 |
-
useEffect(() => {
|
| 279 |
-
let live = true;
|
| 280 |
-
void loadUsage("tenant").then((r) => {
|
| 281 |
-
if (live) setCanSeeTenant(r.ok);
|
| 282 |
-
});
|
| 283 |
-
return () => {
|
| 284 |
-
live = false;
|
| 285 |
-
};
|
| 286 |
-
}, []);
|
| 287 |
-
|
| 288 |
-
return (
|
| 289 |
-
<UsageView
|
| 290 |
-
load={load}
|
| 291 |
-
scope={scope}
|
| 292 |
-
canSeeTenant={canSeeTenant}
|
| 293 |
-
onScope={setScope}
|
| 294 |
-
onRetry={() => read(scope)}
|
| 295 |
-
/>
|
| 296 |
-
);
|
| 297 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// account/UsagePage.tsx β WAVE 35 Β· W35-T19 (owner item 13, ruling R9, C6/C7).
|
| 3 |
+
//
|
| 4 |
+
// R9: ONE meter for every AI surface. It REPORTS weekly usage against an
|
| 5 |
+
// allowance and does not cut anyone off this wave; over the allowance the
|
| 6 |
+
// product still works and the bar is red.
|
| 7 |
+
//
|
| 8 |
+
// ββ THIS PAGE MAY NOT INVENT A FIGURE, AND THAT IS THE WHOLE TICKET.
|
| 9 |
+
// Every number here comes off `GET /usage` β the week, the reset date, the
|
| 10 |
+
// allowance, each surface's tokens and calls. Nothing is derived from a clock,
|
| 11 |
+
// nothing is estimated, and a surface with no ledger lines shows **0**, not a
|
| 12 |
+
// blank and not an omission (E-9 guarantees all four surfaces are always
|
| 13 |
+
// present, so there is no missing-row branch to get wrong).
|
| 14 |
+
// [[no-unverifiable-aggregates]]
|
| 15 |
+
//
|
| 16 |
+
// β AND `unmeasured` IS RENDERED, NOT SWALLOWED. Those are real calls whose
|
| 17 |
+
// provider declined to report a token count, so the total beside them is a
|
| 18 |
+
// FLOOR. A page that hides them presents the floor as a complete figure, which
|
| 19 |
+
// is the cost-surprise failure one step removed β the same reason
|
| 20 |
+
// `usage_ledger` books an unmeasured call as unknown rather than as zero.
|
| 21 |
+
//
|
| 22 |
+
// β SURFACE/READ SPLIT, as on Home and Starred: `renderToStaticMarkup` runs no
|
| 23 |
+
// effect, so a shot of the fetching component photographs only its spinner.
|
| 24 |
+
// ---------------------------------------------------------------------------
|
| 25 |
+
|
| 26 |
+
import { useCallback, useEffect, useRef, useState } from "react";
|
| 27 |
+
|
| 28 |
+
import { fmt } from "../ui/fmt";
|
| 29 |
+
import { loadUsage } from "./accountApi";
|
| 30 |
+
import type { Usage, UsageSurface } from "./accountApi";
|
| 31 |
+
import "./account.css";
|
| 32 |
+
|
| 33 |
+
/**
|
| 34 |
+
* The four surfaces C7 names, in the order R9 lists them.
|
| 35 |
+
*
|
| 36 |
+
* β AN UNKNOWN KEY IS HUMANISED, NEVER DROPPED. Dropping it would hide real usage from a meter
|
| 37 |
+
* whose whole job is to account for it, and printing the raw key would put an internal identifier
|
| 38 |
+
* on screen. The day a fifth LLM entry point lands (this product added two in one wave) it shows
|
| 39 |
+
* up here as a readable name with the right number beside it, and somebody can then decide what
|
| 40 |
+
* to call it.
|
| 41 |
+
*/
|
| 42 |
+
const SURFACE_LABEL: Record<string, string> = {
|
| 43 |
+
assistant: "Assistant",
|
| 44 |
+
field_agent: "Field agents",
|
| 45 |
+
ai_review: "Reviews",
|
| 46 |
+
automation_draft: "Drafting",
|
| 47 |
+
};
|
| 48 |
+
const ORDER = ["assistant", "field_agent", "ai_review", "automation_draft"];
|
| 49 |
+
|
| 50 |
+
export function surfaceLabel(key: string): string {
|
| 51 |
+
const known = SURFACE_LABEL[key];
|
| 52 |
+
if (known) return known;
|
| 53 |
+
const words = key.replace(/[_-]+/g, " ").trim();
|
| 54 |
+
return words ? words.charAt(0).toUpperCase() + words.slice(1) : key;
|
| 55 |
+
}
|
| 56 |
+
|
| 57 |
+
/** C7's order first, then anything the server added, alphabetically. */
|
| 58 |
+
export function orderSurfaces(surfaces: UsageSurface[]): UsageSurface[] {
|
| 59 |
+
const rank = (s: UsageSurface) => {
|
| 60 |
+
const i = ORDER.indexOf(s.surface);
|
| 61 |
+
return i === -1 ? ORDER.length : i;
|
| 62 |
+
};
|
| 63 |
+
return [...surfaces].sort(
|
| 64 |
+
(a, b) => rank(a) - rank(b) || surfaceLabel(a.surface).localeCompare(surfaceLabel(b.surface))
|
| 65 |
+
);
|
| 66 |
+
}
|
| 67 |
+
|
| 68 |
+
/**
|
| 69 |
+
* The bar's fill, as a percentage, CLAMPED to 100.
|
| 70 |
+
*
|
| 71 |
+
* β The clamp is what keeps "over the allowance" a COLOUR rather than a bar that overflows its
|
| 72 |
+
* own track and paints across the page. The number above the bar is unclamped and is where the
|
| 73 |
+
* overage is actually read.
|
| 74 |
+
* β An allowance of 0 (unset) yields 0 rather than a division by zero: no allowance means the
|
| 75 |
+
* meter has nothing to measure against, and a full red bar would be an assertion nobody made.
|
| 76 |
+
*/
|
| 77 |
+
export function barPct(value: number, of: number): number {
|
| 78 |
+
if (!(of > 0)) return 0;
|
| 79 |
+
return Math.max(0, Math.min(100, (value / of) * 100));
|
| 80 |
+
}
|
| 81 |
+
|
| 82 |
+
export type UsageLoad =
|
| 83 |
+
| { phase: "loading" }
|
| 84 |
+
| { phase: "ready"; usage: Usage }
|
| 85 |
+
| { phase: "failed"; message: string };
|
| 86 |
+
|
| 87 |
+
function Bar({ pct, over }: { pct: number; over: boolean }) {
|
| 88 |
+
return (
|
| 89 |
+
<span className="acct-bar" aria-hidden="true">
|
| 90 |
+
<span className={"acct-bar-fill" + (over ? " is-over" : "")} style={{ width: `${pct}%` }} />
|
| 91 |
+
</span>
|
| 92 |
+
);
|
| 93 |
+
}
|
| 94 |
+
|
| 95 |
+
export function UsageSurfaceRows({ usage }: { usage: Usage }) {
|
| 96 |
+
// β SCALED TO THE LARGEST SURFACE, NOT TO THE WEEK'S TOTAL, and the difference is legibility
|
| 97 |
+
// rather than accuracy. `total` is the week's whole figure and can legitimately exceed the sum
|
| 98 |
+
// of these four (unattributed calls are counted there and belong to nobody), so scaling to it
|
| 99 |
+
// shrinks every bar by an amount the reader cannot see the cause of. Scaled to the biggest row,
|
| 100 |
+
// the bars answer the question a row of bars is actually asked: which surface is spending most.
|
| 101 |
+
// The absolute number sits beside each one, so nothing here is only readable as a shape.
|
| 102 |
+
const biggest = usage.surfaces.reduce((m, s) => Math.max(m, s.tokens), 0);
|
| 103 |
+
return (
|
| 104 |
+
<div className="acct-rows">
|
| 105 |
+
{orderSurfaces(usage.surfaces).map((s) => (
|
| 106 |
+
<div key={s.surface} className="acct-row">
|
| 107 |
+
<span className="acct-row-name">{surfaceLabel(s.surface)}</span>
|
| 108 |
+
<Bar pct={barPct(s.tokens, biggest)} over={false} />
|
| 109 |
+
<span className="acct-row-num">{fmt.int(s.tokens)}</span>
|
| 110 |
+
<span className="acct-row-sub">
|
| 111 |
+
{fmt.int(s.calls)} {s.calls === 1 ? "call" : "calls"}
|
| 112 |
+
{/* β NOT HOVER-ONLY. A surface whose provider declined to report tokens has a
|
| 113 |
+
token number that is a floor, and D-253 is a booked defect whose entire content
|
| 114 |
+
is "the explanation was satisfied only on hover". */}
|
| 115 |
+
{s.unmeasured > 0 ? `, ${fmt.int(s.unmeasured)} not measured` : ""}
|
| 116 |
+
</span>
|
| 117 |
+
</div>
|
| 118 |
+
))}
|
| 119 |
+
</div>
|
| 120 |
+
);
|
| 121 |
+
}
|
| 122 |
+
|
| 123 |
+
export function UsageView({
|
| 124 |
+
load,
|
| 125 |
+
scope,
|
| 126 |
+
canSeeTenant,
|
| 127 |
+
onScope,
|
| 128 |
+
onRetry,
|
| 129 |
+
}: {
|
| 130 |
+
load: UsageLoad;
|
| 131 |
+
scope: "me" | "tenant";
|
| 132 |
+
/**
|
| 133 |
+
* Whether the workspace view is reachable AT ALL for this account.
|
| 134 |
+
*
|
| 135 |
+
* β THE TOGGLE IS NOT DRAWN WHEN IT IS NOT, and that is R8's fake-affordance rule applied to a
|
| 136 |
+
* permission: `?scope=tenant` is admin-only and 403s for everybody else, so an always-visible
|
| 137 |
+
* control would be a button most accounts can only be refused by.
|
| 138 |
+
*/
|
| 139 |
+
canSeeTenant: boolean;
|
| 140 |
+
onScope: (scope: "me" | "tenant") => void;
|
| 141 |
+
onRetry: () => void;
|
| 142 |
+
}) {
|
| 143 |
+
return (
|
| 144 |
+
<div className="acct-page">
|
| 145 |
+
<h1 className="acct-title">Usage</h1>
|
| 146 |
+
<div className="acct-col">
|
| 147 |
+
{canSeeTenant ? (
|
| 148 |
+
<div className="acct-scope" role="group" aria-label="Whose usage">
|
| 149 |
+
{(["me", "tenant"] as const).map((key) => (
|
| 150 |
+
<button
|
| 151 |
+
key={key}
|
| 152 |
+
type="button"
|
| 153 |
+
className={"acct-scope-btn" + (scope === key ? " is-on" : "")}
|
| 154 |
+
aria-pressed={scope === key}
|
| 155 |
+
onClick={() => onScope(key)}
|
| 156 |
+
>
|
| 157 |
+
{key === "me" ? "You" : "Workspace"}
|
| 158 |
+
</button>
|
| 159 |
+
))}
|
| 160 |
+
</div>
|
| 161 |
+
) : null}
|
| 162 |
+
{load.phase === "loading" ? (
|
| 163 |
+
<div className="acct-loading">
|
| 164 |
+
<span className="lp-spin lp-spin--lg" role="status" aria-label="Loading" />
|
| 165 |
+
</div>
|
| 166 |
+
) : load.phase === "failed" ? (
|
| 167 |
+
// β NOT A ZERO METER. A failed read and a quiet week look identical on screen unless
|
| 168 |
+
// this branch exists, and a meter reading zero is the most reassuring possible lie.
|
| 169 |
+
<div className="acct-failed">
|
| 170 |
+
<p className="acct-note">{load.message}</p>
|
| 171 |
+
<button type="button" className="acct-retry" onClick={onRetry}>
|
| 172 |
+
Try again
|
| 173 |
+
</button>
|
| 174 |
+
</div>
|
| 175 |
+
) : (
|
| 176 |
+
<>
|
| 177 |
+
<div className="acct-meter">
|
| 178 |
+
{/* β THE METER SAYS WHOSE USAGE IT IS, IN WORDS, and that is not decoration. The
|
| 179 |
+
allowance is a WORKSPACE number; the total beside it is this account's own
|
| 180 |
+
unless the scope says otherwise. A meter that shows a personal figure against a
|
| 181 |
+
shared limit without saying so is a ratio nobody can read correctly, and it is
|
| 182 |
+
the one way this page can be wrong while every number on it is right. */}
|
| 183 |
+
<div className="acct-meter-head">
|
| 184 |
+
<span className="acct-meter-who">
|
| 185 |
+
{load.usage.scope === "tenant" ? "This workspace" : "You"}, this week
|
| 186 |
+
</span>
|
| 187 |
+
</div>
|
| 188 |
+
<div className="acct-meter-head">
|
| 189 |
+
<span className={"acct-meter-value" + (load.usage.over ? " is-over" : "")}>
|
| 190 |
+
{fmt.int(load.usage.total)}
|
| 191 |
+
</span>
|
| 192 |
+
<span className="acct-meter-of">
|
| 193 |
+
of {fmt.int(load.usage.allowance)} tokens
|
| 194 |
+
</span>
|
| 195 |
+
</div>
|
| 196 |
+
<Bar pct={barPct(load.usage.total, load.usage.allowance)} over={load.usage.over} />
|
| 197 |
+
<div className="acct-meter-foot">
|
| 198 |
+
{/* Both facts are the SERVER'S: the week it counted and the date it rolls over.
|
| 199 |
+
A week boundary computed in the browser can disagree with the bucketing that
|
| 200 |
+
produced the number above it, and then the page states a period nobody
|
| 201 |
+
measured. */}
|
| 202 |
+
<span>
|
| 203 |
+
Week {load.usage.week}. Resets {fmt.date(load.usage.resets)}.
|
| 204 |
+
</span>
|
| 205 |
+
<span className="acct-meter-calls">
|
| 206 |
+
{fmt.int(load.usage.calls)} {load.usage.calls === 1 ? "call" : "calls"}
|
| 207 |
+
</span>
|
| 208 |
+
</div>
|
| 209 |
+
</div>
|
| 210 |
+
|
| 211 |
+
{/* β R9's whole point, in one line: over the allowance it STILL WORKS. The bar is
|
| 212 |
+
red, nothing is cut off, and the sentence says which of those two is true so
|
| 213 |
+
nobody has to infer it from a colour. */}
|
| 214 |
+
{load.usage.over ? (
|
| 215 |
+
<p className="acct-error" role="status">
|
| 216 |
+
This workspace is over its weekly allowance. Nothing is cut off; the AI surfaces
|
| 217 |
+
keep working.
|
| 218 |
+
</p>
|
| 219 |
+
) : null}
|
| 220 |
+
|
| 221 |
+
{/* The server's own sentence, present only when something really was unmeasured. */}
|
| 222 |
+
{load.usage.note ? <p className="acct-note acct-note--inline">{load.usage.note}</p> : null}
|
| 223 |
+
|
| 224 |
+
<h2 className="acct-section">By surface</h2>
|
| 225 |
+
<UsageSurfaceRows usage={load.usage} />
|
| 226 |
+
|
| 227 |
+
{load.usage.unattributed > 0 ? (
|
| 228 |
+
// β LABELLED A WIRING GAP, NOT USAGE (E-9). These are AI calls this container could
|
| 229 |
+
// not attribute to an account. Folding them into somebody's total would be an
|
| 230 |
+
// invented attribution, and leaving them out entirely would understate the week.
|
| 231 |
+
<p className="acct-note acct-note--inline">
|
| 232 |
+
{fmt.int(load.usage.unattributed)} tokens this week could not be attributed to an
|
| 233 |
+
account. That is a wiring gap in the meter, not somebody's usage.
|
| 234 |
+
</p>
|
| 235 |
+
) : null}
|
| 236 |
+
</>
|
| 237 |
+
)}
|
| 238 |
+
</div>
|
| 239 |
+
</div>
|
| 240 |
+
);
|
| 241 |
+
}
|
| 242 |
+
|
| 243 |
+
export default function UsagePage() {
|
| 244 |
+
const [load, setLoad] = useState<UsageLoad>({ phase: "loading" });
|
| 245 |
+
const [scope, setScope] = useState<"me" | "tenant">("me");
|
| 246 |
+
/**
|
| 247 |
+
* Whether the workspace view exists for this account, ANSWERED BY ASKING ONCE.
|
| 248 |
+
*
|
| 249 |
+
* β WHY A PROBE RATHER THAN A ROLE CHECK. The frame knows the role, but these pages take no
|
| 250 |
+
* props by contract (C6's trap: a page that decides its own visibility is a second opinion that
|
| 251 |
+
* will one day disagree with the route). The route itself is the authority, so the page asks it
|
| 252 |
+
* once: a 200 means the door is open and the toggle is real; a 403 means it is not and no
|
| 253 |
+
* control is drawn. β That 403 is an ANSWER, not an error β it is never shown to the reader.
|
| 254 |
+
* β AND IT IS WHAT GIVES `?scope=tenant` A DOOR. E built it admin-only; without this it would
|
| 255 |
+
* be a finished capability with no caller, which is this repo's most-repeated failure
|
| 256 |
+
* [[reachable-is-not-the-same-as-built]].
|
| 257 |
+
*/
|
| 258 |
+
const [canSeeTenant, setCanSeeTenant] = useState(false);
|
| 259 |
+
const gen = useRef(0);
|
| 260 |
+
|
| 261 |
+
const read = useCallback((which: "me" | "tenant") => {
|
| 262 |
+
const mine = gen.current + 1;
|
| 263 |
+
gen.current = mine;
|
| 264 |
+
setLoad({ phase: "loading" });
|
| 265 |
+
void loadUsage(which === "tenant" ? "tenant" : undefined).then((r) => {
|
| 266 |
+
if (gen.current !== mine) return;
|
| 267 |
+
setLoad(r.ok ? { phase: "ready", usage: r.value } : { phase: "failed", message: r.message });
|
| 268 |
+
});
|
| 269 |
+
}, []);
|
| 270 |
+
|
| 271 |
+
useEffect(() => {
|
| 272 |
+
read(scope);
|
| 273 |
+
return () => {
|
| 274 |
+
gen.current += 1;
|
| 275 |
+
};
|
| 276 |
+
}, [read, scope]);
|
| 277 |
+
|
| 278 |
+
useEffect(() => {
|
| 279 |
+
let live = true;
|
| 280 |
+
void loadUsage("tenant").then((r) => {
|
| 281 |
+
if (live) setCanSeeTenant(r.ok);
|
| 282 |
+
});
|
| 283 |
+
return () => {
|
| 284 |
+
live = false;
|
| 285 |
+
};
|
| 286 |
+
}, []);
|
| 287 |
+
|
| 288 |
+
return (
|
| 289 |
+
<UsageView
|
| 290 |
+
load={load}
|
| 291 |
+
scope={scope}
|
| 292 |
+
canSeeTenant={canSeeTenant}
|
| 293 |
+
onScope={setScope}
|
| 294 |
+
onRetry={() => read(scope)}
|
| 295 |
+
/>
|
| 296 |
+
);
|
| 297 |
+
}
|
web/src/account/account.css
CHANGED
|
@@ -1,372 +1,372 @@
|
|
| 1 |
-
/* βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 2 |
-
account/account.css β WAVE 35, owner item 13: the three surfaces that hang off the
|
| 3 |
-
account button (Feedback, Usage, Subscription).
|
| 4 |
-
|
| 5 |
-
β ITS OWN STYLESHEET, NOT index.css. That file belongs to the INTEGRATOR for the whole
|
| 6 |
-
wave, and the wave's own rule is that a new surface brings its own sheet. Every selector
|
| 7 |
-
here is .acct-*; nothing in this file redefines a .home-*, .shell-* or .cg-* rule, so
|
| 8 |
-
nothing here can win or lose a source-order fight with the shared sheet.
|
| 9 |
-
|
| 10 |
-
β .acct-page RESTATES .shell-home's five box declarations rather than reusing that class,
|
| 11 |
-
and that is deliberate rather than lazy. .shell-home is Home's box by name and by its own
|
| 12 |
-
region header; borrowing it would make every future Home layout change silently a change
|
| 13 |
-
to three account pages. The VALUES are copied on purpose β DESIGN.md 2's sibling rule
|
| 14 |
-
("a panel matches its sibling's rendered values, not merely the scale") is what makes the
|
| 15 |
-
account pages read as the same system as Home, and .shell-main is overflow:hidden, so a
|
| 16 |
-
page that does not own its own scroll box simply loses everything below the fold.
|
| 17 |
-
|
| 18 |
-
β EVERY font-size IS A --lp-fs-* TOKEN. verify_ui globs src/**.css (every stylesheet in
|
| 19 |
-
the tree, not just index.css) and goes RED on a literal β wave-21 R5.
|
| 20 |
-
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 21 |
-
|
| 22 |
-
.acct-page {
|
| 23 |
-
height: 100%;
|
| 24 |
-
overflow-y: auto;
|
| 25 |
-
padding: 34px 44px 56px;
|
| 26 |
-
box-sizing: border-box;
|
| 27 |
-
background: var(--lp-wash);
|
| 28 |
-
}
|
| 29 |
-
|
| 30 |
-
/* A short plain noun, same size and weight as .home-title, because it is the same role on a
|
| 31 |
-
sibling surface. DESIGN.md 2: headers are 1 to 3 words, never a sentence. */
|
| 32 |
-
.acct-title {
|
| 33 |
-
margin: 0 0 20px;
|
| 34 |
-
font-size: var(--lp-fs-lg);
|
| 35 |
-
font-weight: 650;
|
| 36 |
-
color: var(--lp-ink);
|
| 37 |
-
}
|
| 38 |
-
|
| 39 |
-
/* THE ONE COLUMN. Every account surface is a reading-width column, not a full-bleed page:
|
| 40 |
-
a composer, a meter list and a note are all narrow objects, and stretching them to a
|
| 41 |
-
1600px window is how a page stops looking like it was designed. The reference the owner
|
| 42 |
-
gave for the assistant uses the same centred column for the same reason. */
|
| 43 |
-
.acct-col {
|
| 44 |
-
max-width: 640px;
|
| 45 |
-
}
|
| 46 |
-
|
| 47 |
-
/* ββ the honest note (Subscription today; any boarded account surface tomorrow) βββββββββ
|
| 48 |
-
ONE containment layer: a hairline panel on the wash, no card inside a card, no shadow
|
| 49 |
-
(DESIGN.md 4). It is a panel rather than a bare paragraph so the emptiness reads as
|
| 50 |
-
deliberate instead of as a page that failed to load. */
|
| 51 |
-
.acct-note {
|
| 52 |
-
margin: 0;
|
| 53 |
-
padding: 16px 18px;
|
| 54 |
-
border: 1px solid var(--lp-line);
|
| 55 |
-
border-radius: var(--lp-r-md);
|
| 56 |
background: var(--lp-surface);
|
| 57 |
-
|
| 58 |
-
|
| 59 |
-
|
| 60 |
-
|
| 61 |
-
|
| 62 |
-
|
| 63 |
-
|
| 64 |
-
|
| 65 |
-
|
| 66 |
-
|
| 67 |
-
|
| 68 |
-
|
| 69 |
-
|
| 70 |
-
|
| 71 |
-
|
| 72 |
-
|
| 73 |
-
|
| 74 |
-
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
|
| 78 |
-
|
| 79 |
-
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
|
| 83 |
-
|
| 84 |
-
|
| 85 |
-
|
| 86 |
-
|
| 87 |
-
|
| 88 |
-
|
| 89 |
-
|
| 90 |
-
|
| 91 |
-
|
| 92 |
-
|
| 93 |
-
|
| 94 |
-
|
| 95 |
-
|
| 96 |
-
|
| 97 |
-
|
| 98 |
-
|
| 99 |
-
|
| 100 |
-
|
| 101 |
-
|
| 102 |
-
|
| 103 |
-
|
| 104 |
-
.
|
| 105 |
-
|
| 106 |
-
|
| 107 |
-
|
| 108 |
-
|
| 109 |
-
|
| 110 |
-
|
| 111 |
-
|
| 112 |
-
|
| 113 |
-
|
| 114 |
-
|
| 115 |
-
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
|
| 121 |
-
|
| 122 |
-
|
| 123 |
-
|
| 124 |
-
|
| 125 |
-
|
| 126 |
-
|
| 127 |
-
|
| 128 |
-
|
| 129 |
-
border-
|
| 130 |
-
|
| 131 |
-
|
| 132 |
-
|
| 133 |
-
|
| 134 |
-
border:
|
| 135 |
-
|
| 136 |
-
|
| 137 |
-
|
| 138 |
-
|
| 139 |
-
|
| 140 |
-
|
| 141 |
-
|
| 142 |
-
|
| 143 |
-
|
| 144 |
-
|
| 145 |
-
|
| 146 |
-
|
| 147 |
-
|
| 148 |
-
|
| 149 |
-
|
| 150 |
-
|
| 151 |
-
|
| 152 |
-
|
| 153 |
-
|
| 154 |
-
|
| 155 |
-
|
| 156 |
-
|
| 157 |
-
|
| 158 |
-
|
| 159 |
-
}
|
| 160 |
-
.acct-
|
| 161 |
-
|
| 162 |
-
|
| 163 |
-
|
| 164 |
-
|
| 165 |
-
|
| 166 |
-
|
| 167 |
-
|
| 168 |
-
|
| 169 |
-
|
| 170 |
-
|
| 171 |
-
|
| 172 |
-
|
| 173 |
-
|
| 174 |
-
|
| 175 |
-
|
| 176 |
-
|
| 177 |
-
.acct-
|
| 178 |
-
|
| 179 |
-
|
| 180 |
-
|
| 181 |
-
|
| 182 |
-
|
| 183 |
-
|
| 184 |
-
|
| 185 |
-
|
| 186 |
-
|
| 187 |
-
|
| 188 |
-
|
| 189 |
-
|
| 190 |
-
|
| 191 |
-
|
| 192 |
-
|
| 193 |
-
|
| 194 |
-
|
| 195 |
-
|
| 196 |
-
border:
|
| 197 |
-
border-radius: var(--lp-r-
|
| 198 |
-
background: var(--lp-
|
| 199 |
-
color: var(--lp-
|
| 200 |
-
font: inherit;
|
| 201 |
-
|
| 202 |
-
|
| 203 |
-
|
| 204 |
-
|
| 205 |
-
|
| 206 |
-
|
| 207 |
-
|
| 208 |
-
|
| 209 |
-
|
| 210 |
-
|
| 211 |
-
|
| 212 |
-
|
| 213 |
-
|
| 214 |
-
}
|
| 215 |
-
|
| 216 |
-
|
| 217 |
-
|
| 218 |
-
|
| 219 |
-
|
| 220 |
-
|
| 221 |
-
|
| 222 |
-
|
| 223 |
-
|
| 224 |
-
|
| 225 |
-
|
| 226 |
-
|
| 227 |
-
|
| 228 |
-
|
| 229 |
-
|
| 230 |
-
|
| 231 |
-
|
| 232 |
-
|
| 233 |
-
|
| 234 |
-
|
| 235 |
-
|
| 236 |
-
|
| 237 |
-
|
| 238 |
-
|
| 239 |
-
|
| 240 |
-
|
| 241 |
-
|
| 242 |
-
|
| 243 |
-
|
| 244 |
-
|
| 245 |
-
|
| 246 |
-
|
| 247 |
-
.
|
| 248 |
-
|
| 249 |
-
|
| 250 |
-
|
| 251 |
-
|
| 252 |
-
|
| 253 |
-
|
| 254 |
-
|
| 255 |
-
|
| 256 |
-
|
| 257 |
-
|
| 258 |
-
border
|
| 259 |
-
|
| 260 |
-
|
| 261 |
-
|
| 262 |
-
|
| 263 |
-
|
| 264 |
-
|
| 265 |
-
|
| 266 |
-
|
| 267 |
-
|
| 268 |
-
|
| 269 |
-
|
| 270 |
-
color: var(--lp-muted);
|
| 271 |
-
|
| 272 |
-
|
| 273 |
-
|
| 274 |
-
|
| 275 |
-
|
| 276 |
-
|
| 277 |
-
|
| 278 |
-
|
| 279 |
-
|
| 280 |
-
|
| 281 |
-
|
| 282 |
-
|
| 283 |
-
|
| 284 |
-
|
| 285 |
-
|
| 286 |
-
|
| 287 |
-
|
| 288 |
-
|
| 289 |
-
}
|
| 290 |
-
.acct-meter-
|
| 291 |
-
display: flex;
|
| 292 |
-
align-items: baseline;
|
| 293 |
-
|
| 294 |
-
|
| 295 |
-
|
| 296 |
-
|
| 297 |
-
|
| 298 |
-
|
| 299 |
-
|
| 300 |
-
|
| 301 |
-
|
| 302 |
-
|
| 303 |
-
|
| 304 |
-
|
| 305 |
-
|
| 306 |
-
|
| 307 |
-
|
| 308 |
-
|
| 309 |
-
|
| 310 |
-
|
| 311 |
-
|
| 312 |
-
|
| 313 |
-
|
| 314 |
-
|
| 315 |
-
|
| 316 |
-
|
| 317 |
-
|
| 318 |
-
|
| 319 |
-
|
| 320 |
-
|
| 321 |
-
|
| 322 |
-
|
| 323 |
-
|
| 324 |
-
|
| 325 |
-
|
| 326 |
-
|
| 327 |
-
|
| 328 |
-
.acct-
|
| 329 |
-
|
| 330 |
-
font-
|
| 331 |
-
|
| 332 |
-
|
| 333 |
-
|
| 334 |
-
.
|
| 335 |
-
|
| 336 |
-
|
| 337 |
-
|
| 338 |
-
|
| 339 |
-
|
| 340 |
-
|
| 341 |
-
|
| 342 |
-
|
| 343 |
-
|
| 344 |
-
|
| 345 |
-
|
| 346 |
-
|
| 347 |
-
border-
|
| 348 |
-
|
| 349 |
-
.
|
| 350 |
-
|
| 351 |
-
|
| 352 |
-
|
| 353 |
-
|
| 354 |
-
|
| 355 |
-
|
| 356 |
-
|
| 357 |
-
|
| 358 |
-
|
| 359 |
-
|
| 360 |
-
font-
|
| 361 |
-
color: var(--lp-
|
| 362 |
-
|
| 363 |
-
|
| 364 |
-
|
| 365 |
-
|
| 366 |
-
|
| 367 |
-
|
| 368 |
-
|
| 369 |
-
|
| 370 |
-
|
| 371 |
-
|
| 372 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
/* βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 2 |
+
account/account.css β WAVE 35, owner item 13: the three surfaces that hang off the
|
| 3 |
+
account button (Feedback, Usage, Subscription).
|
| 4 |
+
|
| 5 |
+
β ITS OWN STYLESHEET, NOT index.css. That file belongs to the INTEGRATOR for the whole
|
| 6 |
+
wave, and the wave's own rule is that a new surface brings its own sheet. Every selector
|
| 7 |
+
here is .acct-*; nothing in this file redefines a .home-*, .shell-* or .cg-* rule, so
|
| 8 |
+
nothing here can win or lose a source-order fight with the shared sheet.
|
| 9 |
+
|
| 10 |
+
β .acct-page RESTATES .shell-home's five box declarations rather than reusing that class,
|
| 11 |
+
and that is deliberate rather than lazy. .shell-home is Home's box by name and by its own
|
| 12 |
+
region header; borrowing it would make every future Home layout change silently a change
|
| 13 |
+
to three account pages. The VALUES are copied on purpose β DESIGN.md 2's sibling rule
|
| 14 |
+
("a panel matches its sibling's rendered values, not merely the scale") is what makes the
|
| 15 |
+
account pages read as the same system as Home, and .shell-main is overflow:hidden, so a
|
| 16 |
+
page that does not own its own scroll box simply loses everything below the fold.
|
| 17 |
+
|
| 18 |
+
β EVERY font-size IS A --lp-fs-* TOKEN. verify_ui globs src/**.css (every stylesheet in
|
| 19 |
+
the tree, not just index.css) and goes RED on a literal β wave-21 R5.
|
| 20 |
+
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 21 |
+
|
| 22 |
+
.acct-page {
|
| 23 |
+
height: 100%;
|
| 24 |
+
overflow-y: auto;
|
| 25 |
+
padding: 34px 44px 56px;
|
| 26 |
+
box-sizing: border-box;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 27 |
background: var(--lp-surface);
|
| 28 |
+
}
|
| 29 |
+
|
| 30 |
+
/* A short plain noun, same size and weight as .home-title, because it is the same role on a
|
| 31 |
+
sibling surface. DESIGN.md 2: headers are 1 to 3 words, never a sentence. */
|
| 32 |
+
.acct-title {
|
| 33 |
+
margin: 0 0 20px;
|
| 34 |
+
font-size: var(--lp-fs-lg);
|
| 35 |
+
font-weight: 650;
|
| 36 |
+
color: var(--lp-ink);
|
| 37 |
+
}
|
| 38 |
+
|
| 39 |
+
/* THE ONE COLUMN. Every account surface is a reading-width column, not a full-bleed page:
|
| 40 |
+
a composer, a meter list and a note are all narrow objects, and stretching them to a
|
| 41 |
+
1600px window is how a page stops looking like it was designed. The reference the owner
|
| 42 |
+
gave for the assistant uses the same centred column for the same reason. */
|
| 43 |
+
.acct-col {
|
| 44 |
+
max-width: 640px;
|
| 45 |
+
}
|
| 46 |
+
|
| 47 |
+
/* ββ the honest note (Subscription today; any boarded account surface tomorrow) βββββββββ
|
| 48 |
+
ONE containment layer: a hairline panel on the wash, no card inside a card, no shadow
|
| 49 |
+
(DESIGN.md 4). It is a panel rather than a bare paragraph so the emptiness reads as
|
| 50 |
+
deliberate instead of as a page that failed to load. */
|
| 51 |
+
.acct-note {
|
| 52 |
+
margin: 0;
|
| 53 |
+
padding: 16px 18px;
|
| 54 |
+
border: 1px solid var(--lp-line);
|
| 55 |
+
border-radius: var(--lp-r-md);
|
| 56 |
+
background: var(--lp-surface);
|
| 57 |
+
font-size: var(--lp-fs-xs);
|
| 58 |
+
line-height: var(--lp-lh);
|
| 59 |
+
color: var(--lp-muted);
|
| 60 |
+
}
|
| 61 |
+
|
| 62 |
+
/* ββ loading, and the way back from a failed read βββββββββββββββββββββββββββββββββββββββββββ */
|
| 63 |
+
.acct-loading {
|
| 64 |
+
display: flex;
|
| 65 |
+
align-items: center;
|
| 66 |
+
justify-content: center;
|
| 67 |
+
min-height: 180px;
|
| 68 |
+
}
|
| 69 |
+
.acct-failed {
|
| 70 |
+
display: flex;
|
| 71 |
+
align-items: center;
|
| 72 |
+
gap: 12px;
|
| 73 |
+
}
|
| 74 |
+
/* DESIGN.md 4's quiet button, with the UA chrome reset explicitly (the wave-19 "mystery outer
|
| 75 |
+
lines and tinted fill" rule). */
|
| 76 |
+
.acct-retry {
|
| 77 |
+
flex: 0 0 auto;
|
| 78 |
+
padding: 6px 12px;
|
| 79 |
+
border: 1px solid var(--lp-line);
|
| 80 |
+
border-radius: var(--lp-r-md);
|
| 81 |
+
background: var(--lp-surface);
|
| 82 |
+
color: var(--lp-ink);
|
| 83 |
+
font: inherit;
|
| 84 |
+
font-size: var(--lp-fs-2xs);
|
| 85 |
+
font-weight: 600;
|
| 86 |
+
cursor: pointer;
|
| 87 |
+
}
|
| 88 |
+
.acct-retry:hover {
|
| 89 |
+
background: var(--lp-surface-2);
|
| 90 |
+
border-color: var(--lp-blue-deep);
|
| 91 |
+
}
|
| 92 |
+
|
| 93 |
+
/* ββ the two answers a write can give βββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 94 |
+
Green = positive, red = negative: the fixed semantics (DESIGN.md 3), on the DEEP companions
|
| 95 |
+
because a pastel on white is not a light aesthetic, it is an unreadable one. */
|
| 96 |
+
.acct-ok,
|
| 97 |
+
.acct-error {
|
| 98 |
+
margin: 0 0 12px;
|
| 99 |
+
padding: 9px 12px;
|
| 100 |
+
border-radius: var(--lp-r-md);
|
| 101 |
+
font-size: var(--lp-fs-2xs);
|
| 102 |
+
line-height: var(--lp-lh);
|
| 103 |
+
}
|
| 104 |
+
.acct-ok {
|
| 105 |
+
border: 1px solid var(--lp-green);
|
| 106 |
+
background: var(--lp-green-tint);
|
| 107 |
+
color: var(--lp-green-deep);
|
| 108 |
+
}
|
| 109 |
+
.acct-error {
|
| 110 |
+
border: 1px solid var(--lp-red);
|
| 111 |
+
background: var(--lp-red-tint);
|
| 112 |
+
color: var(--lp-red-deep);
|
| 113 |
+
}
|
| 114 |
+
|
| 115 |
+
/* ββ the composer βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 116 |
+
The ASSISTANT'S anatomy in this module's own rules: one rounded field that contains its own
|
| 117 |
+
control row, so the category and the send button read as part of the thing being written
|
| 118 |
+
rather than as chrome around it. `assistant.css` is another session's file this wave and is
|
| 119 |
+
deliberately not imported; the shape is borrowed, the rules are local.
|
| 120 |
+
β The radius is smaller than the assistant's 22px pill on purpose: this field is a paragraph
|
| 121 |
+
box, not a one-line prompt, and a heavily rounded tall box reads as a speech bubble. */
|
| 122 |
+
.acct-field {
|
| 123 |
+
border: 1px solid var(--lp-line);
|
| 124 |
+
border-radius: var(--lp-r-lg);
|
| 125 |
+
background: var(--lp-surface);
|
| 126 |
+
padding: 12px 10px 10px 14px;
|
| 127 |
+
}
|
| 128 |
+
.acct-field:focus-within {
|
| 129 |
+
border-color: var(--lp-blue-solid);
|
| 130 |
+
}
|
| 131 |
+
.acct-prompt {
|
| 132 |
+
display: block;
|
| 133 |
+
width: 100%;
|
| 134 |
+
border: 0;
|
| 135 |
+
outline: none;
|
| 136 |
+
padding: 0 6px 0 0;
|
| 137 |
+
background: transparent;
|
| 138 |
+
color: var(--lp-ink);
|
| 139 |
+
font: inherit;
|
| 140 |
+
font-size: var(--lp-fs-sm);
|
| 141 |
+
line-height: var(--lp-lh);
|
| 142 |
+
resize: vertical;
|
| 143 |
+
box-sizing: border-box;
|
| 144 |
+
}
|
| 145 |
+
.acct-prompt::placeholder {
|
| 146 |
+
color: var(--lp-muted);
|
| 147 |
+
}
|
| 148 |
+
.acct-field-foot {
|
| 149 |
+
display: flex;
|
| 150 |
+
align-items: center;
|
| 151 |
+
gap: 10px;
|
| 152 |
+
margin-top: 10px;
|
| 153 |
+
}
|
| 154 |
+
.acct-pick {
|
| 155 |
+
display: inline-flex;
|
| 156 |
+
align-items: center;
|
| 157 |
+
gap: 6px;
|
| 158 |
+
min-width: 0;
|
| 159 |
+
}
|
| 160 |
+
.acct-pick-label {
|
| 161 |
+
color: var(--lp-muted);
|
| 162 |
+
font-size: var(--lp-fs-2xs);
|
| 163 |
+
}
|
| 164 |
+
.acct-select {
|
| 165 |
+
max-width: 220px;
|
| 166 |
+
padding: 4px 8px;
|
| 167 |
+
border: 1px solid var(--lp-line);
|
| 168 |
+
border-radius: var(--lp-r-sm);
|
| 169 |
+
background: var(--lp-surface);
|
| 170 |
+
color: var(--lp-ink);
|
| 171 |
+
font: inherit;
|
| 172 |
+
font-size: var(--lp-fs-2xs);
|
| 173 |
+
cursor: pointer;
|
| 174 |
+
}
|
| 175 |
+
/* Tabular figures so the count does not jitter as it climbs. Red only once the limit is actually
|
| 176 |
+
passed: a counter that warns before anything is wrong trains people to ignore it. */
|
| 177 |
+
.acct-count {
|
| 178 |
+
color: var(--lp-muted);
|
| 179 |
+
font-size: var(--lp-fs-3xs);
|
| 180 |
+
font-variant-numeric: tabular-nums;
|
| 181 |
+
}
|
| 182 |
+
.acct-count.is-over {
|
| 183 |
+
color: var(--lp-red-deep);
|
| 184 |
+
font-weight: 600;
|
| 185 |
+
}
|
| 186 |
+
/* The send button takes the ink fill when it can send and the wash when it cannot, which is the
|
| 187 |
+
assistant's own rule: the control says whether there is anything to send before it is pressed. */
|
| 188 |
+
.acct-send {
|
| 189 |
+
flex: 0 0 auto;
|
| 190 |
+
margin-left: auto;
|
| 191 |
+
width: 30px;
|
| 192 |
+
height: 30px;
|
| 193 |
+
display: inline-flex;
|
| 194 |
+
align-items: center;
|
| 195 |
+
justify-content: center;
|
| 196 |
+
border: 0;
|
| 197 |
+
border-radius: var(--lp-r-pill);
|
| 198 |
+
background: var(--lp-ink);
|
| 199 |
+
color: var(--lp-surface);
|
| 200 |
+
font: inherit;
|
| 201 |
+
cursor: pointer;
|
| 202 |
+
}
|
| 203 |
+
.acct-send:disabled {
|
| 204 |
+
background: var(--lp-surface-2);
|
| 205 |
+
color: var(--lp-muted);
|
| 206 |
+
cursor: default;
|
| 207 |
+
}
|
| 208 |
+
.acct-send-icon {
|
| 209 |
+
fill: none;
|
| 210 |
+
stroke: currentColor;
|
| 211 |
+
stroke-width: 1.7;
|
| 212 |
+
stroke-linecap: round;
|
| 213 |
+
stroke-linejoin: round;
|
| 214 |
+
}
|
| 215 |
+
|
| 216 |
+
/* ββ the usage meter (R9) βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 217 |
+
One containment layer, hairline, no shadow. The bar is the only new SHAPE on these pages, and
|
| 218 |
+
the ticket asks for it by name ("over the allowance the bar is red"). */
|
| 219 |
+
.acct-note--inline {
|
| 220 |
+
margin: 12px 0 0;
|
| 221 |
+
padding: 9px 12px;
|
| 222 |
+
font-size: var(--lp-fs-2xs);
|
| 223 |
+
}
|
| 224 |
+
.acct-scope {
|
| 225 |
+
display: inline-flex;
|
| 226 |
+
gap: 2px;
|
| 227 |
+
margin-bottom: 14px;
|
| 228 |
+
padding: 2px;
|
| 229 |
+
border: 1px solid var(--lp-line);
|
| 230 |
+
border-radius: var(--lp-r-md);
|
| 231 |
+
background: var(--lp-surface);
|
| 232 |
+
}
|
| 233 |
+
/* Selection is TINT plus WEIGHT with the ink left alone, which is `.shell-nav-item.is-active`'s
|
| 234 |
+
rule. β NOT `--lp-blue-deep` on `--lp-blue-tint`: that pair measures 2.96:1, under the 4.5:1
|
| 235 |
+
text bar and under the 3:1 graphical one, and this control holds words. */
|
| 236 |
+
.acct-scope-btn {
|
| 237 |
+
padding: 4px 12px;
|
| 238 |
+
border: 0;
|
| 239 |
+
border-radius: var(--lp-r-sm);
|
| 240 |
+
background: transparent;
|
| 241 |
+
color: var(--lp-muted);
|
| 242 |
+
font: inherit;
|
| 243 |
+
font-size: var(--lp-fs-2xs);
|
| 244 |
+
font-weight: 600;
|
| 245 |
+
cursor: pointer;
|
| 246 |
+
}
|
| 247 |
+
.acct-scope-btn:hover {
|
| 248 |
+
background: var(--lp-surface-2);
|
| 249 |
+
}
|
| 250 |
+
.acct-scope-btn.is-on {
|
| 251 |
+
background: var(--lp-blue-tint);
|
| 252 |
+
color: var(--lp-ink);
|
| 253 |
+
}
|
| 254 |
+
|
| 255 |
+
.acct-meter {
|
| 256 |
+
padding: 16px 18px;
|
| 257 |
+
border: 1px solid var(--lp-line);
|
| 258 |
+
border-radius: var(--lp-r-md);
|
| 259 |
+
background: var(--lp-surface);
|
| 260 |
+
}
|
| 261 |
+
.acct-meter-head {
|
| 262 |
+
display: flex;
|
| 263 |
+
align-items: baseline;
|
| 264 |
+
gap: 8px;
|
| 265 |
+
flex-wrap: wrap;
|
| 266 |
+
}
|
| 267 |
+
.acct-meter-who {
|
| 268 |
+
font-size: var(--lp-fs-2xs);
|
| 269 |
+
font-weight: 600;
|
| 270 |
+
color: var(--lp-muted);
|
| 271 |
+
margin-bottom: 4px;
|
| 272 |
+
}
|
| 273 |
+
/* Tabular figures on every financial-grade number (DESIGN.md 2), so a total that climbs does not
|
| 274 |
+
make the label beside it dance. Weight 650, never a display weight. */
|
| 275 |
+
.acct-meter-value {
|
| 276 |
+
font-size: var(--lp-fs-xl);
|
| 277 |
+
font-weight: 650;
|
| 278 |
+
color: var(--lp-ink);
|
| 279 |
+
font-variant-numeric: tabular-nums;
|
| 280 |
+
}
|
| 281 |
+
/* Red = negative/over, the fixed semantic, on the deep companion. */
|
| 282 |
+
.acct-meter-value.is-over {
|
| 283 |
+
color: var(--lp-red-deep);
|
| 284 |
+
}
|
| 285 |
+
.acct-meter-of {
|
| 286 |
+
font-size: var(--lp-fs-xs);
|
| 287 |
+
color: var(--lp-muted);
|
| 288 |
+
font-variant-numeric: tabular-nums;
|
| 289 |
+
}
|
| 290 |
+
.acct-meter-foot {
|
| 291 |
+
display: flex;
|
| 292 |
+
align-items: baseline;
|
| 293 |
+
justify-content: space-between;
|
| 294 |
+
gap: 12px;
|
| 295 |
+
margin-top: 8px;
|
| 296 |
+
font-size: var(--lp-fs-2xs);
|
| 297 |
+
color: var(--lp-muted);
|
| 298 |
+
}
|
| 299 |
+
.acct-meter-calls {
|
| 300 |
+
flex: 0 0 auto;
|
| 301 |
+
font-variant-numeric: tabular-nums;
|
| 302 |
+
}
|
| 303 |
+
|
| 304 |
+
/* The track is the wash so an empty meter still reads as a meter rather than as a missing
|
| 305 |
+
element; the fill is the brand at rest and red once the allowance is passed. */
|
| 306 |
+
.acct-bar {
|
| 307 |
+
display: block;
|
| 308 |
+
width: 100%;
|
| 309 |
+
height: 8px;
|
| 310 |
+
margin-top: 10px;
|
| 311 |
+
border-radius: var(--lp-r-pill);
|
| 312 |
+
background: var(--lp-wash);
|
| 313 |
+
overflow: hidden;
|
| 314 |
+
}
|
| 315 |
+
.acct-bar-fill {
|
| 316 |
+
display: block;
|
| 317 |
+
height: 100%;
|
| 318 |
+
border-radius: var(--lp-r-pill);
|
| 319 |
+
background: var(--lp-primary);
|
| 320 |
+
transition: width 0.18s var(--lp-fold-e);
|
| 321 |
+
}
|
| 322 |
+
.acct-bar-fill.is-over {
|
| 323 |
+
background: var(--lp-red-deep);
|
| 324 |
+
}
|
| 325 |
+
|
| 326 |
+
/* A short plain noun, muted, sentence case, matching `.home-section-title` exactly: the same role
|
| 327 |
+
on a sibling surface takes the same rendered values (DESIGN.md 2). */
|
| 328 |
+
.acct-section {
|
| 329 |
+
margin: 22px 0 9px;
|
| 330 |
+
font-size: var(--lp-fs-2xs);
|
| 331 |
+
font-weight: 600;
|
| 332 |
+
color: var(--lp-muted);
|
| 333 |
+
}
|
| 334 |
+
.acct-rows {
|
| 335 |
+
display: flex;
|
| 336 |
+
flex-direction: column;
|
| 337 |
+
gap: 2px;
|
| 338 |
+
}
|
| 339 |
+
/* One row per surface: name, share bar, tokens, calls. Fixed columns so the four numbers form a
|
| 340 |
+
column a reader can scan rather than four numbers at four different left edges. */
|
| 341 |
+
.acct-row {
|
| 342 |
+
display: grid;
|
| 343 |
+
grid-template-columns: 120px 1fr 92px 150px;
|
| 344 |
+
align-items: center;
|
| 345 |
+
gap: 12px;
|
| 346 |
+
padding: 8px 2px;
|
| 347 |
+
border-bottom: 1px solid var(--lp-line);
|
| 348 |
+
}
|
| 349 |
+
.acct-row:last-child {
|
| 350 |
+
border-bottom: 0;
|
| 351 |
+
}
|
| 352 |
+
.acct-row-name {
|
| 353 |
+
font-size: var(--lp-fs-xs);
|
| 354 |
+
font-weight: 600;
|
| 355 |
+
color: var(--lp-ink);
|
| 356 |
+
}
|
| 357 |
+
/* Numbers right-aligned, text left (DESIGN.md 2), tabular so the column lines up digit for digit. */
|
| 358 |
+
.acct-row-num {
|
| 359 |
+
text-align: right;
|
| 360 |
+
font-size: var(--lp-fs-xs);
|
| 361 |
+
color: var(--lp-ink);
|
| 362 |
+
font-variant-numeric: tabular-nums;
|
| 363 |
+
}
|
| 364 |
+
.acct-row-sub {
|
| 365 |
+
font-size: var(--lp-fs-2xs);
|
| 366 |
+
color: var(--lp-muted);
|
| 367 |
+
font-variant-numeric: tabular-nums;
|
| 368 |
+
}
|
| 369 |
+
.acct-row .acct-bar {
|
| 370 |
+
margin-top: 0;
|
| 371 |
+
height: 6px;
|
| 372 |
+
}
|
web/src/account/accountApi.ts
CHANGED
|
@@ -1,188 +1,188 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// account/accountApi.ts β WAVE 35, owner item 13: the wire behind the two account
|
| 3 |
-
// surfaces that have one (Feedback, contract C6/R8; Usage, C7/R9).
|
| 4 |
-
//
|
| 5 |
-
// β THE CATEGORY VOCABULARY IS THE SERVER'S AND IS FETCHED, NOT DECLARED HERE.
|
| 6 |
-
// That is a decision, not an omission: a client constant beside a server enum is
|
| 7 |
-
// two lists that drift, and the day they do the dropdown offers a value the door
|
| 8 |
-
// refuses. Asked and settled in mailbox B-1 / E-9 β the server serves the list,
|
| 9 |
-
// this file renders it, and there is no local fallback to drift TO.
|
| 10 |
-
//
|
| 11 |
-
// β AND THERE IS NO TENANT-SIDE READ OF A SUBMISSION AT ALL (R8). No "my
|
| 12 |
-
// feedback" list, no edit, no delete: the operator plane is the only reader. The
|
| 13 |
-
// 201 is the receipt. If that ever feels like a gap, it is R8, not a missing
|
| 14 |
-
// endpoint.
|
| 15 |
-
//
|
| 16 |
-
// β NOTHING ON THE USAGE SIDE IS COMPUTED HERE. The allowance, the week and the
|
| 17 |
-
// reset date all ride the payload (E-9), because a week boundary computed in the
|
| 18 |
-
// browser can disagree with the server's own bucketing β and then the page shows
|
| 19 |
-
// a number that traces to no ledger line, which is exactly what R9's meter must
|
| 20 |
-
// never do.
|
| 21 |
-
// ---------------------------------------------------------------------------
|
| 22 |
-
|
| 23 |
-
import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
|
| 24 |
-
|
| 25 |
-
/** The same discriminated result the other feature modules use. */
|
| 26 |
-
export type Result<T> =
|
| 27 |
-
| { ok: true; value: T }
|
| 28 |
-
| { ok: false; status: number; message: string };
|
| 29 |
-
|
| 30 |
-
async function call<T>(
|
| 31 |
-
path: string,
|
| 32 |
-
init: RequestInit,
|
| 33 |
-
read: (body: unknown) => T
|
| 34 |
-
): Promise<Result<T>> {
|
| 35 |
-
let res: Response;
|
| 36 |
-
try {
|
| 37 |
-
res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init });
|
| 38 |
-
} catch {
|
| 39 |
-
return { ok: false, status: 0, message: "Cannot reach the server." };
|
| 40 |
-
}
|
| 41 |
-
if (checkTenant(res)) return { ok: false, status: 0, message: "Reloading." };
|
| 42 |
-
if (res.status === 401) signal(UNAUTHORIZED_EVENT);
|
| 43 |
-
const body = (await res.json().catch(() => null)) as unknown;
|
| 44 |
-
if (!res.ok) {
|
| 45 |
-
// β A 4xx MESSAGE IS POLICY AND IS SHOWN; a 5xx message is an internal detail and is not.
|
| 46 |
-
// `session.ts` states the same rule for sign-in, and E names each 400 case ("unknown
|
| 47 |
-
// category", "empty text", "over maxChars"), so the server's sentence is the useful one.
|
| 48 |
-
const detail = (body as { error?: { message?: string } } | null)?.error?.message;
|
| 49 |
-
return {
|
| 50 |
-
ok: false,
|
| 51 |
-
status: res.status,
|
| 52 |
-
message:
|
| 53 |
-
res.status >= 500 || !detail
|
| 54 |
-
? res.status >= 500
|
| 55 |
-
? "Something went wrong on our side. Try again in a moment."
|
| 56 |
-
: `The server answered ${res.status}.`
|
| 57 |
-
: detail,
|
| 58 |
-
};
|
| 59 |
-
}
|
| 60 |
-
return { ok: true, value: read(body) };
|
| 61 |
-
}
|
| 62 |
-
|
| 63 |
-
const row = (v: unknown): Record<string, unknown> =>
|
| 64 |
-
v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
|
| 65 |
-
const str = (v: unknown): string => (typeof v === "string" ? v : "");
|
| 66 |
-
const int = (v: unknown): number =>
|
| 67 |
-
typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
|
| 68 |
-
|
| 69 |
-
// ββ FEEDBACK (R8, C6) βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 70 |
-
|
| 71 |
-
export interface FeedbackCategory {
|
| 72 |
-
key: string;
|
| 73 |
-
label: string;
|
| 74 |
-
}
|
| 75 |
-
|
| 76 |
-
export interface FeedbackForm {
|
| 77 |
-
categories: FeedbackCategory[];
|
| 78 |
-
maxChars: number;
|
| 79 |
-
}
|
| 80 |
-
|
| 81 |
-
/**
|
| 82 |
-
* `GET /api/v1/feedback/form` β the category list and the length limit, both the server's.
|
| 83 |
-
*
|
| 84 |
-
* β A CATEGORY WITH NO LABEL IS DROPPED, never rendered as its key: an internal identifier in a
|
| 85 |
-
* dropdown is the same defect `parsePages` refuses one layer up ("a nav row with no name is a
|
| 86 |
-
* door with no sign on it"). And an EMPTY list is a real answer the caller must handle, not a
|
| 87 |
-
* reason to invent one.
|
| 88 |
-
*/
|
| 89 |
-
export function parseFeedbackForm(body: unknown): FeedbackForm {
|
| 90 |
-
const r = row(body);
|
| 91 |
-
const categories = (Array.isArray(r.categories) ? r.categories : [])
|
| 92 |
-
.map(row)
|
| 93 |
-
.filter((c) => str(c.key) !== "" && str(c.label) !== "")
|
| 94 |
-
.map((c) => ({ key: str(c.key), label: str(c.label) }));
|
| 95 |
-
return { categories, maxChars: int(r.maxChars) };
|
| 96 |
-
}
|
| 97 |
-
|
| 98 |
-
export function loadFeedbackForm(): Promise<Result<FeedbackForm>> {
|
| 99 |
-
return call("/feedback/form", {}, parseFeedbackForm);
|
| 100 |
-
}
|
| 101 |
-
|
| 102 |
-
export function sendFeedback(category: string, text: string): Promise<Result<{ id: string }>> {
|
| 103 |
-
return call(
|
| 104 |
-
"/feedback",
|
| 105 |
-
{
|
| 106 |
-
method: "POST",
|
| 107 |
-
headers: { "Content-Type": "application/json" },
|
| 108 |
-
body: JSON.stringify({ category, text }),
|
| 109 |
-
},
|
| 110 |
-
(b) => ({ id: str(row(b).id) })
|
| 111 |
-
);
|
| 112 |
-
}
|
| 113 |
-
|
| 114 |
-
// ββ USAGE (R9, C7) ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 115 |
-
|
| 116 |
-
/** One AI surface's week. Every surface is present at zero when unused (E-9), so nothing here
|
| 117 |
-
* branches on a missing row. */
|
| 118 |
-
export interface UsageSurface {
|
| 119 |
-
surface: string;
|
| 120 |
-
calls: number;
|
| 121 |
-
tokens: number;
|
| 122 |
-
tokensIn: number;
|
| 123 |
-
tokensOut: number;
|
| 124 |
-
/**
|
| 125 |
-
* Calls whose provider declined to report a token count.
|
| 126 |
-
*
|
| 127 |
-
* β NOT ZERO-PADDING. These are real calls with an UNKNOWN cost, which is why the total beside
|
| 128 |
-
* them is a FLOOR rather than a figure. A page that hides this presents the floor as complete,
|
| 129 |
-
* and that is the cost-surprise failure one step removed.
|
| 130 |
-
*/
|
| 131 |
-
unmeasured: number;
|
| 132 |
-
}
|
| 133 |
-
|
| 134 |
-
export interface Usage {
|
| 135 |
-
/** ISO year-week, UTC. A string that sorts chronologically, so nothing here parses a date. */
|
| 136 |
-
week: string;
|
| 137 |
-
/** The UTC date the counters roll over, as the server states it. */
|
| 138 |
-
resets: string;
|
| 139 |
-
allowance: number;
|
| 140 |
-
total: number;
|
| 141 |
-
over: boolean;
|
| 142 |
-
calls: number;
|
| 143 |
-
unmeasured: number;
|
| 144 |
-
/** `"me"` or `"tenant"`. Which question the numbers answer, decided by the server. */
|
| 145 |
-
scope: string;
|
| 146 |
-
surfaces: UsageSurface[];
|
| 147 |
-
/** The server's own sentence about `unmeasured`. Empty when there is nothing unmeasured. */
|
| 148 |
-
note: string;
|
| 149 |
-
/**
|
| 150 |
-
* Admin only: AI calls this container could not attribute to an account.
|
| 151 |
-
*
|
| 152 |
-
* β LABEL IT A WIRING GAP, NOT USAGE (E-9). It is the meter reporting on ITSELF, and folding it
|
| 153 |
-
* into somebody's total would be an invented attribution.
|
| 154 |
-
*/
|
| 155 |
-
unattributed: number;
|
| 156 |
-
}
|
| 157 |
-
|
| 158 |
-
export function parseUsage(body: unknown): Usage {
|
| 159 |
-
const r = row(body);
|
| 160 |
-
const surfaces = (Array.isArray(r.surfaces) ? r.surfaces : [])
|
| 161 |
-
.map(row)
|
| 162 |
-
.filter((s) => str(s.surface) !== "")
|
| 163 |
-
.map((s) => ({
|
| 164 |
-
surface: str(s.surface),
|
| 165 |
-
calls: int(s.calls),
|
| 166 |
-
tokens: int(s.tokens),
|
| 167 |
-
tokensIn: int(s.tokens_in),
|
| 168 |
-
tokensOut: int(s.tokens_out),
|
| 169 |
-
unmeasured: int(s.unmeasured),
|
| 170 |
-
}));
|
| 171 |
-
return {
|
| 172 |
-
week: str(r.week),
|
| 173 |
-
resets: str(r.resets),
|
| 174 |
-
allowance: int(r.allowance),
|
| 175 |
-
total: int(r.total),
|
| 176 |
-
over: r.over === true,
|
| 177 |
-
calls: int(r.calls),
|
| 178 |
-
unmeasured: int(r.unmeasured),
|
| 179 |
-
scope: str(r.scope) || "me",
|
| 180 |
-
surfaces,
|
| 181 |
-
note: str(r.note),
|
| 182 |
-
unattributed: int(r.unattributed),
|
| 183 |
-
};
|
| 184 |
-
}
|
| 185 |
-
|
| 186 |
-
export function loadUsage(scope?: "tenant"): Promise<Result<Usage>> {
|
| 187 |
-
return call(scope === "tenant" ? "/usage?scope=tenant" : "/usage", {}, parseUsage);
|
| 188 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// account/accountApi.ts β WAVE 35, owner item 13: the wire behind the two account
|
| 3 |
+
// surfaces that have one (Feedback, contract C6/R8; Usage, C7/R9).
|
| 4 |
+
//
|
| 5 |
+
// β THE CATEGORY VOCABULARY IS THE SERVER'S AND IS FETCHED, NOT DECLARED HERE.
|
| 6 |
+
// That is a decision, not an omission: a client constant beside a server enum is
|
| 7 |
+
// two lists that drift, and the day they do the dropdown offers a value the door
|
| 8 |
+
// refuses. Asked and settled in mailbox B-1 / E-9 β the server serves the list,
|
| 9 |
+
// this file renders it, and there is no local fallback to drift TO.
|
| 10 |
+
//
|
| 11 |
+
// β AND THERE IS NO TENANT-SIDE READ OF A SUBMISSION AT ALL (R8). No "my
|
| 12 |
+
// feedback" list, no edit, no delete: the operator plane is the only reader. The
|
| 13 |
+
// 201 is the receipt. If that ever feels like a gap, it is R8, not a missing
|
| 14 |
+
// endpoint.
|
| 15 |
+
//
|
| 16 |
+
// β NOTHING ON THE USAGE SIDE IS COMPUTED HERE. The allowance, the week and the
|
| 17 |
+
// reset date all ride the payload (E-9), because a week boundary computed in the
|
| 18 |
+
// browser can disagree with the server's own bucketing β and then the page shows
|
| 19 |
+
// a number that traces to no ledger line, which is exactly what R9's meter must
|
| 20 |
+
// never do.
|
| 21 |
+
// ---------------------------------------------------------------------------
|
| 22 |
+
|
| 23 |
+
import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
|
| 24 |
+
|
| 25 |
+
/** The same discriminated result the other feature modules use. */
|
| 26 |
+
export type Result<T> =
|
| 27 |
+
| { ok: true; value: T }
|
| 28 |
+
| { ok: false; status: number; message: string };
|
| 29 |
+
|
| 30 |
+
async function call<T>(
|
| 31 |
+
path: string,
|
| 32 |
+
init: RequestInit,
|
| 33 |
+
read: (body: unknown) => T
|
| 34 |
+
): Promise<Result<T>> {
|
| 35 |
+
let res: Response;
|
| 36 |
+
try {
|
| 37 |
+
res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init });
|
| 38 |
+
} catch {
|
| 39 |
+
return { ok: false, status: 0, message: "Cannot reach the server." };
|
| 40 |
+
}
|
| 41 |
+
if (checkTenant(res)) return { ok: false, status: 0, message: "Reloading." };
|
| 42 |
+
if (res.status === 401) signal(UNAUTHORIZED_EVENT);
|
| 43 |
+
const body = (await res.json().catch(() => null)) as unknown;
|
| 44 |
+
if (!res.ok) {
|
| 45 |
+
// β A 4xx MESSAGE IS POLICY AND IS SHOWN; a 5xx message is an internal detail and is not.
|
| 46 |
+
// `session.ts` states the same rule for sign-in, and E names each 400 case ("unknown
|
| 47 |
+
// category", "empty text", "over maxChars"), so the server's sentence is the useful one.
|
| 48 |
+
const detail = (body as { error?: { message?: string } } | null)?.error?.message;
|
| 49 |
+
return {
|
| 50 |
+
ok: false,
|
| 51 |
+
status: res.status,
|
| 52 |
+
message:
|
| 53 |
+
res.status >= 500 || !detail
|
| 54 |
+
? res.status >= 500
|
| 55 |
+
? "Something went wrong on our side. Try again in a moment."
|
| 56 |
+
: `The server answered ${res.status}.`
|
| 57 |
+
: detail,
|
| 58 |
+
};
|
| 59 |
+
}
|
| 60 |
+
return { ok: true, value: read(body) };
|
| 61 |
+
}
|
| 62 |
+
|
| 63 |
+
const row = (v: unknown): Record<string, unknown> =>
|
| 64 |
+
v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
|
| 65 |
+
const str = (v: unknown): string => (typeof v === "string" ? v : "");
|
| 66 |
+
const int = (v: unknown): number =>
|
| 67 |
+
typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
|
| 68 |
+
|
| 69 |
+
// ββ FEEDBACK (R8, C6) βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 70 |
+
|
| 71 |
+
export interface FeedbackCategory {
|
| 72 |
+
key: string;
|
| 73 |
+
label: string;
|
| 74 |
+
}
|
| 75 |
+
|
| 76 |
+
export interface FeedbackForm {
|
| 77 |
+
categories: FeedbackCategory[];
|
| 78 |
+
maxChars: number;
|
| 79 |
+
}
|
| 80 |
+
|
| 81 |
+
/**
|
| 82 |
+
* `GET /api/v1/feedback/form` β the category list and the length limit, both the server's.
|
| 83 |
+
*
|
| 84 |
+
* β A CATEGORY WITH NO LABEL IS DROPPED, never rendered as its key: an internal identifier in a
|
| 85 |
+
* dropdown is the same defect `parsePages` refuses one layer up ("a nav row with no name is a
|
| 86 |
+
* door with no sign on it"). And an EMPTY list is a real answer the caller must handle, not a
|
| 87 |
+
* reason to invent one.
|
| 88 |
+
*/
|
| 89 |
+
export function parseFeedbackForm(body: unknown): FeedbackForm {
|
| 90 |
+
const r = row(body);
|
| 91 |
+
const categories = (Array.isArray(r.categories) ? r.categories : [])
|
| 92 |
+
.map(row)
|
| 93 |
+
.filter((c) => str(c.key) !== "" && str(c.label) !== "")
|
| 94 |
+
.map((c) => ({ key: str(c.key), label: str(c.label) }));
|
| 95 |
+
return { categories, maxChars: int(r.maxChars) };
|
| 96 |
+
}
|
| 97 |
+
|
| 98 |
+
export function loadFeedbackForm(): Promise<Result<FeedbackForm>> {
|
| 99 |
+
return call("/feedback/form", {}, parseFeedbackForm);
|
| 100 |
+
}
|
| 101 |
+
|
| 102 |
+
export function sendFeedback(category: string, text: string): Promise<Result<{ id: string }>> {
|
| 103 |
+
return call(
|
| 104 |
+
"/feedback",
|
| 105 |
+
{
|
| 106 |
+
method: "POST",
|
| 107 |
+
headers: { "Content-Type": "application/json" },
|
| 108 |
+
body: JSON.stringify({ category, text }),
|
| 109 |
+
},
|
| 110 |
+
(b) => ({ id: str(row(b).id) })
|
| 111 |
+
);
|
| 112 |
+
}
|
| 113 |
+
|
| 114 |
+
// ββ USAGE (R9, C7) ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 115 |
+
|
| 116 |
+
/** One AI surface's week. Every surface is present at zero when unused (E-9), so nothing here
|
| 117 |
+
* branches on a missing row. */
|
| 118 |
+
export interface UsageSurface {
|
| 119 |
+
surface: string;
|
| 120 |
+
calls: number;
|
| 121 |
+
tokens: number;
|
| 122 |
+
tokensIn: number;
|
| 123 |
+
tokensOut: number;
|
| 124 |
+
/**
|
| 125 |
+
* Calls whose provider declined to report a token count.
|
| 126 |
+
*
|
| 127 |
+
* β NOT ZERO-PADDING. These are real calls with an UNKNOWN cost, which is why the total beside
|
| 128 |
+
* them is a FLOOR rather than a figure. A page that hides this presents the floor as complete,
|
| 129 |
+
* and that is the cost-surprise failure one step removed.
|
| 130 |
+
*/
|
| 131 |
+
unmeasured: number;
|
| 132 |
+
}
|
| 133 |
+
|
| 134 |
+
export interface Usage {
|
| 135 |
+
/** ISO year-week, UTC. A string that sorts chronologically, so nothing here parses a date. */
|
| 136 |
+
week: string;
|
| 137 |
+
/** The UTC date the counters roll over, as the server states it. */
|
| 138 |
+
resets: string;
|
| 139 |
+
allowance: number;
|
| 140 |
+
total: number;
|
| 141 |
+
over: boolean;
|
| 142 |
+
calls: number;
|
| 143 |
+
unmeasured: number;
|
| 144 |
+
/** `"me"` or `"tenant"`. Which question the numbers answer, decided by the server. */
|
| 145 |
+
scope: string;
|
| 146 |
+
surfaces: UsageSurface[];
|
| 147 |
+
/** The server's own sentence about `unmeasured`. Empty when there is nothing unmeasured. */
|
| 148 |
+
note: string;
|
| 149 |
+
/**
|
| 150 |
+
* Admin only: AI calls this container could not attribute to an account.
|
| 151 |
+
*
|
| 152 |
+
* β LABEL IT A WIRING GAP, NOT USAGE (E-9). It is the meter reporting on ITSELF, and folding it
|
| 153 |
+
* into somebody's total would be an invented attribution.
|
| 154 |
+
*/
|
| 155 |
+
unattributed: number;
|
| 156 |
+
}
|
| 157 |
+
|
| 158 |
+
export function parseUsage(body: unknown): Usage {
|
| 159 |
+
const r = row(body);
|
| 160 |
+
const surfaces = (Array.isArray(r.surfaces) ? r.surfaces : [])
|
| 161 |
+
.map(row)
|
| 162 |
+
.filter((s) => str(s.surface) !== "")
|
| 163 |
+
.map((s) => ({
|
| 164 |
+
surface: str(s.surface),
|
| 165 |
+
calls: int(s.calls),
|
| 166 |
+
tokens: int(s.tokens),
|
| 167 |
+
tokensIn: int(s.tokens_in),
|
| 168 |
+
tokensOut: int(s.tokens_out),
|
| 169 |
+
unmeasured: int(s.unmeasured),
|
| 170 |
+
}));
|
| 171 |
+
return {
|
| 172 |
+
week: str(r.week),
|
| 173 |
+
resets: str(r.resets),
|
| 174 |
+
allowance: int(r.allowance),
|
| 175 |
+
total: int(r.total),
|
| 176 |
+
over: r.over === true,
|
| 177 |
+
calls: int(r.calls),
|
| 178 |
+
unmeasured: int(r.unmeasured),
|
| 179 |
+
scope: str(r.scope) || "me",
|
| 180 |
+
surfaces,
|
| 181 |
+
note: str(r.note),
|
| 182 |
+
unattributed: int(r.unattributed),
|
| 183 |
+
};
|
| 184 |
+
}
|
| 185 |
+
|
| 186 |
+
export function loadUsage(scope?: "tenant"): Promise<Result<Usage>> {
|
| 187 |
+
return call(scope === "tenant" ? "/usage?scope=tenant" : "/usage", {}, parseUsage);
|
| 188 |
+
}
|
web/src/alerts/alertsModel.ts
CHANGED
|
@@ -1,418 +1,418 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// alerts/alertsModel.ts β WAVE 20 item 25 (contract C-ALERT): the inbox's PURE
|
| 3 |
-
// half. React-free and fetch-free, so `verify_alerts.py` runs it under node.
|
| 4 |
-
//
|
| 5 |
-
// An alert says "tell me when a record ENTERS this view". The client half is
|
| 6 |
-
// small, and every part of it fails silently when it is wrong:
|
| 7 |
-
//
|
| 8 |
-
// Β· an unread count taken from `items.length` rather than from the server's
|
| 9 |
-
// own `unread` disagrees with the badge the moment a page is capped or a
|
| 10 |
-
// read lands in another tab β and a badge that says 3 when the list shows 9
|
| 11 |
-
// teaches the reader to ignore the badge;
|
| 12 |
-
// Β· a notification whose `viewId` no longer resolves must open NOTHING rather
|
| 13 |
-
// than a wrong view β alerts outlive the views they were made from;
|
| 14 |
-
// Β· `topic` is the surface's scope key ("customer", "product", "ut_β¦"), and
|
| 15 |
-
// the ROUTE is a registry key ("customer_data") β mapping one to the other
|
| 16 |
-
// by guesswork sends every click to a page that does not exist.
|
| 17 |
-
// ---------------------------------------------------------------------------
|
| 18 |
-
|
| 19 |
-
/**
|
| 20 |
-
* ββ WAVE 32 Β· T20 Β· CONTRACT C3 β WHERE AN INBOX ITEM OPENS.
|
| 21 |
-
*
|
| 22 |
-
* `module` is the destination surface (`"database"` or `"automation"`) and `id` is what to open
|
| 23 |
-
* in it. `tab` is the SUB-SELECTION inside that module: the literal `"runs"` for an automation's
|
| 24 |
-
* run log, or the VIEW ID to select on a database. One optional key, two destinations.
|
| 25 |
-
*
|
| 26 |
-
* β EVERY FIELD IS A PLAIN `string`, NEVER A UNION, and that is alertsModel's wave-9 law rather
|
| 27 |
-
* than laziness: the vocabulary is the SERVER's, and a client union over it turns "the server grew
|
| 28 |
-
* a module" into "the client silently drops the row". An unknown module is refused by the
|
| 29 |
-
* FRAME's dispatcher, out loud, which is a different thing from never arriving.
|
| 30 |
-
*/
|
| 31 |
-
export interface NotificationTarget {
|
| 32 |
-
module: string;
|
| 33 |
-
id: string;
|
| 34 |
-
tab?: string;
|
| 35 |
-
}
|
| 36 |
-
|
| 37 |
-
/** C3's `kind` vocabulary, mirroring `routes_alerts.NOTIF_KIND_*`. Held as constants so the
|
| 38 |
-
* Inbox's branch and the gate's fixtures cannot disagree about the word. */
|
| 39 |
-
export const NOTIF_KIND_ALERT = "alert";
|
| 40 |
-
export const NOTIF_KIND_AUTOMATION = "automation";
|
| 41 |
-
export const NOTIF_KIND_SHARE = "share";
|
| 42 |
-
|
| 43 |
-
/** C3's `target.module` vocabulary, and the automation sub-selection. */
|
| 44 |
-
export const TARGET_MODULE_DATABASE = "database";
|
| 45 |
-
export const TARGET_MODULE_AUTOMATION = "automation";
|
| 46 |
-
export const TARGET_TAB_RUNS = "runs";
|
| 47 |
-
|
| 48 |
-
/** One notification, as `GET /api/v1/notifications` sends it. */
|
| 49 |
-
export interface Notification {
|
| 50 |
-
id: string;
|
| 51 |
-
alertId: string;
|
| 52 |
-
viewId: string;
|
| 53 |
-
topic: string;
|
| 54 |
-
rowId: string;
|
| 55 |
-
/** What entered β the record's own label. */
|
| 56 |
-
label: string;
|
| 57 |
-
/** What the alert is called, so a row reads without opening anything. */
|
| 58 |
-
alertLabel: string;
|
| 59 |
-
/** UTC WITH OFFSET (D-18). Kept as the server's STRING: re-formatting it here
|
| 60 |
-
* would re-introduce the browser-clock drift the offset exists to remove. */
|
| 61 |
-
at: string;
|
| 62 |
-
read: boolean;
|
| 63 |
-
/**
|
| 64 |
-
* WAVE 23 (contract C6) β WHAT KIND of notification this is.
|
| 65 |
-
*
|
| 66 |
-
* Absent (and every notification written before this wave) means the original one: a record
|
| 67 |
-
* ENTERED a watched view, routed by `topic` + `viewId`. `"automation_review"` means a card
|
| 68 |
-
* arrived at a review stage and routes by `autoId` instead β a different destination reached
|
| 69 |
-
* from the same list.
|
| 70 |
-
*
|
| 71 |
-
* β A STRING, NEVER A UNION, and that is the wave-9 law rather than laziness: the vocabulary
|
| 72 |
-
* is the SERVER's, and a client union over it turns "the server grew a kind" into "the client
|
| 73 |
-
* silently drops the row". Unknown kinds fall through to the view route, which is exactly what
|
| 74 |
-
* they did before this field existed.
|
| 75 |
-
*/
|
| 76 |
-
kind?: string;
|
| 77 |
-
/** `automation_review` only: the automation whose review stage a card reached. Absent on
|
| 78 |
-
* every other kind β and an `automation_review` row that arrives WITHOUT one opens nothing
|
| 79 |
-
* rather than guessing, the same posture `viewId` gets. */
|
| 80 |
-
autoId?: string;
|
| 81 |
-
/** Advisory. A surface that does not scroll to a stage simply selects the automation. */
|
| 82 |
-
stageId?: string;
|
| 83 |
-
/** How many cards arrived in the batch. C6 queues ONE notification per run naming the count,
|
| 84 |
-
* never one per record β so this is the number the row's own text is built from. */
|
| 85 |
-
count?: number;
|
| 86 |
-
/**
|
| 87 |
-
* β WAVE 32 Β· C3 β THE HEADER LINE, so the Inbox can be laid out like mail.
|
| 88 |
-
*
|
| 89 |
-
* `subject` is what the item is ABOUT (the alert's name, the automation's name, the database
|
| 90 |
-
* that was shared); `label` stays what HAPPENED (the record that entered, the run summary).
|
| 91 |
-
* They were one field, which is why the pane could only ever render a sentence with no sender.
|
| 92 |
-
* Absent on a server that predates this wave β {@link subjectOf} falls back rather than
|
| 93 |
-
* rendering a blank header.
|
| 94 |
-
*/
|
| 95 |
-
subject?: string;
|
| 96 |
-
/**
|
| 97 |
-
* ββ WAVE 33 Β· W33-T28 β WHO IT IS FROM. Mail has a sender; this list did not.
|
| 98 |
-
*
|
| 99 |
-
* A `verifier` reading the finished wave-32 Inbox found the row's sender POSITION occupied by
|
| 100 |
-
* `kindLabel(n.kind)` β the literals "Alert" / "Automation" / "Shared with you", a CATEGORY
|
| 101 |
-
* standing where a who belongs β and no sender anywhere on the wire. Derived by the server
|
| 102 |
-
* (`routes_alerts.notification_view`), never here: only it knows that a share has a person
|
| 103 |
-
* behind it and an alert has a machine.
|
| 104 |
-
* β Optional, so a payload from a server that predates this wave keeps today's shape;
|
| 105 |
-
* {@link senderOf} falls back rather than rendering a blank From column.
|
| 106 |
-
*/
|
| 107 |
-
sender?: string;
|
| 108 |
-
/** β WAVE 32 Β· C3 β where clicking it goes. ABSENT when this product cannot resolve a
|
| 109 |
-
* destination (an alert on a table this account can no longer route to), and that absence is
|
| 110 |
-
* load-bearing: the Inbox renders such a row as plainly unclickable rather than as a click
|
| 111 |
-
* that silently does nothing. */
|
| 112 |
-
target?: NotificationTarget;
|
| 113 |
-
}
|
| 114 |
-
|
| 115 |
-
/** One alert, as `GET /api/v1/alerts` sends it. */
|
| 116 |
-
export interface Alert {
|
| 117 |
-
id: string;
|
| 118 |
-
viewId: string;
|
| 119 |
-
topic: string;
|
| 120 |
-
owner: string;
|
| 121 |
-
label: string;
|
| 122 |
-
createdAt: string;
|
| 123 |
-
/** How many records are in its remembered set right now. */
|
| 124 |
-
matched: number;
|
| 125 |
-
seeded: boolean;
|
| 126 |
-
lastRunAt: string;
|
| 127 |
-
lastError: string;
|
| 128 |
-
}
|
| 129 |
-
|
| 130 |
-
export interface Inbox {
|
| 131 |
-
unread: number;
|
| 132 |
-
items: Notification[];
|
| 133 |
-
/**
|
| 134 |
-
* ββ WAVE 33 Β· W33-T28 / D-208 β THE SERVER'S CLOCK, so a stamp can be mail-shaped.
|
| 135 |
-
*
|
| 136 |
-
* β It exists so {@link stampText} never reads the BROWSER's clock, which is D-208's exit
|
| 137 |
-
* condition word for word. `at` is UTC with its offset (D-18) precisely so every reader sees
|
| 138 |
-
* the same instant; asking "is this today?" of a local clock would put the drift back.
|
| 139 |
-
* β Optional: absent, `stampText` returns the old absolute string rather than guessing.
|
| 140 |
-
*/
|
| 141 |
-
now?: string;
|
| 142 |
-
}
|
| 143 |
-
|
| 144 |
-
export const EMPTY_INBOX: Inbox = { unread: 0, items: [] };
|
| 145 |
-
|
| 146 |
-
/**
|
| 147 |
-
* ββ WAVE 31 Β· T23 (owner item 1) β WHAT THE PANE IS ENTITLED TO SAY, AS A FUNCTION.
|
| 148 |
-
*
|
| 149 |
-
* Owner, verbatim: *"Alerts shows notification, but when clicked it says nothing, and it doesn't
|
| 150 |
-
* remove the notification number."* Both halves are ONE mechanism. `AlertsPane` held its own
|
| 151 |
-
* `inbox` seeded to {@link EMPTY_INBOX} and had no pending state, so between opening the panel
|
| 152 |
-
* and `GET /notifications` answering β measured at **3,280 ms live** β and for ever after a
|
| 153 |
-
* failed fetch:
|
| 154 |
-
* Β· `items` was `[]`, so the pane printed **"Nothing new."** β a claim, not a wait;
|
| 155 |
-
* Β· `unread` was `0`, so **"Mark all read" was `disabled`**, and the badge the frame had
|
| 156 |
-
* already loaded could never be cleared.
|
| 157 |
-
* A confident sentence about somebody's inbox, and the one control that would fix it, both
|
| 158 |
-
* switched off by the same uninitialised state.
|
| 159 |
-
*
|
| 160 |
-
* β IT IS A FUNCTION BECAUSE THE PANE IS TSX AND TSX IS NOT UNDER TEST HERE. `verify_alerts`
|
| 161 |
-
* compiles and RUNS this module under node; markup it cannot reach is markup no control can
|
| 162 |
-
* mutate. Deciding here means the truth table is asserted and each branch is load-bearing.
|
| 163 |
-
*/
|
| 164 |
-
export type PaneView = "pending" | "rows" | "empty" | "error";
|
| 165 |
-
|
| 166 |
-
/**
|
| 167 |
-
* `pending` while the first read is in flight Β· `error` when it failed and we have nothing to
|
| 168 |
-
* show Β· `rows` when there is something Β· `empty` ONLY when a successful read returned nothing.
|
| 169 |
-
*
|
| 170 |
-
* β ROWS WIN OVER AN ERROR, and that is deliberate rather than lax: a refresh that fails while
|
| 171 |
-
* the pane already holds notifications should not blank them β the reader loses real information
|
| 172 |
-
* to a transient. The error still reaches them as the pane's message line.
|
| 173 |
-
*/
|
| 174 |
-
export function paneView(
|
| 175 |
-
phase: "pending" | "ready" | "error",
|
| 176 |
-
rowCount: number,
|
| 177 |
-
seededUnread = 0
|
| 178 |
-
): PaneView {
|
| 179 |
-
if (rowCount > 0) return "rows";
|
| 180 |
-
if (phase === "pending") return "pending";
|
| 181 |
-
if (phase === "error") return "error";
|
| 182 |
-
// β A SUCCESSFUL READ WITH NO ROWS AND A NON-ZERO COUNT IS NOT "nothing new". The badge says
|
| 183 |
-
// there is something; the page we were given does not contain it. Saying "Nothing new" there
|
| 184 |
-
// is the same false confidence in a different costume.
|
| 185 |
-
return seededUnread > 0 ? "error" : "empty";
|
| 186 |
-
}
|
| 187 |
-
|
| 188 |
-
/**
|
| 189 |
-
* May "Mark all read" be pressed?
|
| 190 |
-
*
|
| 191 |
-
* β NOT `unread === 0`, WHICH IS THE SHIPPED BUG. That test asked the PANE's own state β zero
|
| 192 |
-
* until its fetch lands, zero for ever if the fetch fails β so the control was dead in exactly
|
| 193 |
-
* the situations the owner hit. The question is about the ACCOUNT, so it is asked of the count
|
| 194 |
-
* the frame already holds, and a failed read does not take the verb away: `POST /notifications/
|
| 195 |
-
* read` with `ids: null` clears the account's inbox whether or not we managed to list it.
|
| 196 |
-
*/
|
| 197 |
-
export function canMarkAll(unread: number, busy = false): boolean {
|
| 198 |
-
return !busy && Math.max(0, Math.floor(unread)) > 0;
|
| 199 |
-
}
|
| 200 |
-
|
| 201 |
-
const str = (v: unknown): string => (typeof v === "string" ? v : "");
|
| 202 |
-
const num = (v: unknown): number => (typeof v === "number" && isFinite(v) ? v : 0);
|
| 203 |
-
|
| 204 |
-
/**
|
| 205 |
-
* β WAVE 32 Β· C3 β one wire `target` β a {@link NotificationTarget}, or `null`.
|
| 206 |
-
*
|
| 207 |
-
* β BOTH `module` AND `id` ARE REQUIRED, and dropping either test is the failure this guard is
|
| 208 |
-
* for: a target with a module and no id dispatches an open request naming NOTHING β a click that
|
| 209 |
-
* appears to work and silently does not, which is this repo's most-repeated shape. `null` is
|
| 210 |
-
* rendered as an unclickable row, which a reader can SEE.
|
| 211 |
-
*/
|
| 212 |
-
export function parseTarget(raw: unknown): NotificationTarget | null {
|
| 213 |
-
if (!raw || typeof raw !== "object") return null;
|
| 214 |
-
const t = raw as Record<string, unknown>;
|
| 215 |
-
const module = str(t.module).trim();
|
| 216 |
-
const id = str(t.id).trim();
|
| 217 |
-
if (!module || !id) return null;
|
| 218 |
-
const tab = str(t.tab).trim();
|
| 219 |
-
return { module, id, ...(tab ? { tab } : {}) };
|
| 220 |
-
}
|
| 221 |
-
|
| 222 |
-
/**
|
| 223 |
-
* `GET /notifications` β the inbox, fail-closed.
|
| 224 |
-
*
|
| 225 |
-
* β `unread` COMES FROM THE SERVER, and is not recounted from `items`. The two
|
| 226 |
-
* can legitimately differ β the list is what this page holds, the count is what
|
| 227 |
-
* the account has β and recomputing it here would make the badge a function of
|
| 228 |
-
* whatever the last fetch happened to include.
|
| 229 |
-
*/
|
| 230 |
-
export function parseInbox(body: unknown): Inbox {
|
| 231 |
-
const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
|
| 232 |
-
const raw = Array.isArray(b.items) ? b.items : [];
|
| 233 |
-
const items: Notification[] = [];
|
| 234 |
-
for (const item of raw) {
|
| 235 |
-
if (!item || typeof item !== "object") continue;
|
| 236 |
-
const n = item as Record<string, unknown>;
|
| 237 |
-
const id = str(n.id);
|
| 238 |
-
// An id-less notification cannot be marked read, so it would sit unread for
|
| 239 |
-
// ever and hold the badge up. Dropped, not rendered.
|
| 240 |
-
if (!id) continue;
|
| 241 |
-
items.push({
|
| 242 |
-
id,
|
| 243 |
-
alertId: str(n.alertId),
|
| 244 |
-
viewId: str(n.viewId),
|
| 245 |
-
topic: str(n.topic),
|
| 246 |
-
rowId: String(n.rowId ?? ""),
|
| 247 |
-
label: str(n.label) || String(n.rowId ?? ""),
|
| 248 |
-
alertLabel: str(n.alertLabel),
|
| 249 |
-
at: str(n.at),
|
| 250 |
-
read: n.read === true,
|
| 251 |
-
// WAVE 23 C6 β ADDITIVE and spread-conditional, exactly like `NavPage`'s flags: a payload
|
| 252 |
-
// that predates this wave keeps today's shape rather than gaining four `undefined` keys,
|
| 253 |
-
// and an `automation_review` row missing its `autoId` is left WITHOUT one rather than
|
| 254 |
-
// with an empty string that would render as a real destination.
|
| 255 |
-
...(str(n.kind) ? { kind: str(n.kind) } : {}),
|
| 256 |
-
...(str(n.autoId) ? { autoId: str(n.autoId) } : {}),
|
| 257 |
-
...(str(n.stageId) ? { stageId: str(n.stageId) } : {}),
|
| 258 |
-
...(num(n.count) > 0 ? { count: num(n.count) } : {}),
|
| 259 |
-
// β WAVE 32 Β· C3 β additive and spread-conditional, exactly like the four above.
|
| 260 |
-
...(str(n.subject) ? { subject: str(n.subject) } : {}),
|
| 261 |
-
// β WAVE 33 Β· W33-T28 β additive and spread-conditional, like every flag above it.
|
| 262 |
-
...(str(n.sender) ? { sender: str(n.sender) } : {}),
|
| 263 |
-
...(parseTarget(n.target) ? { target: parseTarget(n.target)! } : {}),
|
| 264 |
-
});
|
| 265 |
-
}
|
| 266 |
-
// β W33-T28 / D-208 β the server's clock rides through, spread-conditionally like every other
|
| 267 |
-
// additive key here, so a server that predates this wave yields the same object it always did.
|
| 268 |
-
return {
|
| 269 |
-
unread: Math.max(0, num(b.unread)),
|
| 270 |
-
items,
|
| 271 |
-
...(str(b.now) ? { now: str(b.now) } : {}),
|
| 272 |
-
};
|
| 273 |
-
}
|
| 274 |
-
|
| 275 |
-
/** `GET /alerts` β the alert list, fail-closed. */
|
| 276 |
-
export function parseAlerts(body: unknown): Alert[] {
|
| 277 |
-
const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
|
| 278 |
-
const raw = Array.isArray(b.alerts) ? b.alerts : [];
|
| 279 |
-
const out: Alert[] = [];
|
| 280 |
-
for (const item of raw) {
|
| 281 |
-
if (!item || typeof item !== "object") continue;
|
| 282 |
-
const a = item as Record<string, unknown>;
|
| 283 |
-
const id = str(a.id);
|
| 284 |
-
if (!id) continue;
|
| 285 |
-
out.push({
|
| 286 |
-
id,
|
| 287 |
-
viewId: str(a.viewId),
|
| 288 |
-
topic: str(a.topic),
|
| 289 |
-
owner: str(a.owner),
|
| 290 |
-
label: str(a.label) || "Untitled alert",
|
| 291 |
-
createdAt: str(a.createdAt),
|
| 292 |
-
matched: num(a.matched),
|
| 293 |
-
seeded: a.seeded === true,
|
| 294 |
-
lastRunAt: str(a.lastRunAt),
|
| 295 |
-
lastError: str(a.lastError),
|
| 296 |
-
});
|
| 297 |
-
}
|
| 298 |
-
return out;
|
| 299 |
-
}
|
| 300 |
-
|
| 301 |
-
/**
|
| 302 |
-
* A topic (the grid's scope key) β the hash route that renders it.
|
| 303 |
-
*
|
| 304 |
-
* The two built-ins are the only pair that differ, and they differ because the
|
| 305 |
-
* REGISTRY names the surface while the GRID names the scope; a user table is its
|
| 306 |
-
* own key in both. `null` for anything else: a notification for a topic this
|
| 307 |
-
* client cannot route to must do nothing, not navigate somewhere plausible.
|
| 308 |
-
*/
|
| 309 |
-
export function routeForTopic(topic: string): string | null {
|
| 310 |
-
const t = str(topic).trim();
|
| 311 |
-
if (t === "customer") return "customer_data";
|
| 312 |
-
if (t === "product") return "product_data";
|
| 313 |
-
if (/^ut_[A-Za-z0-9_]+$/.test(t)) return t;
|
| 314 |
-
return null;
|
| 315 |
-
}
|
| 316 |
-
|
| 317 |
-
|
| 318 |
-
|
| 319 |
-
|
| 320 |
-
|
| 321 |
-
|
| 322 |
-
/**
|
| 323 |
-
* The stamp, made readable WITHOUT touching a clock.
|
| 324 |
-
*
|
| 325 |
-
* β NO `new Date()`, NO `toLocaleString()`, and that is the whole design. The
|
| 326 |
-
* server sends UTC WITH ITS OFFSET (D-18) precisely so every reader sees the
|
| 327 |
-
* same instant; parsing it into a browser Date and formatting it back would
|
| 328 |
-
* re-introduce the drift the offset exists to remove β a tenant a day ahead
|
| 329 |
-
* being told an event happened tomorrow ([[date-window-vocabulary]]). This is
|
| 330 |
-
* STRING SURGERY: keep the date and the minutes, drop the seconds and the `T`.
|
| 331 |
-
* Anything that does not look like an ISO stamp passes through untouched, so a
|
| 332 |
-
* format this function has never seen is shown as sent rather than mangled.
|
| 333 |
-
*/
|
| 334 |
-
const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
|
| 335 |
-
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
|
| 336 |
-
|
| 337 |
-
export function stampText(at: string, now?: string): string {
|
| 338 |
-
const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(str(at));
|
| 339 |
-
if (!m) return str(at);
|
| 340 |
-
const [, day, hhmm] = m;
|
| 341 |
-
// ββ W33-T28 / D-208 β MAIL-SHAPED, AND STILL STRING SURGERY.
|
| 342 |
-
//
|
| 343 |
-
// β `now` COMES FROM THE SERVER (`inbox.now`), NEVER FROM `new Date()`. That is D-208's exit
|
| 344 |
-
// condition word for word β "without reading the browser clock" β and the reason is the same
|
| 345 |
-
// one this function has always carried: `at` is sent as UTC WITH its offset (D-18) so every
|
| 346 |
-
// reader sees the same instant, and deciding "is this today?" against a browser clock would
|
| 347 |
-
// re-introduce exactly the drift the offset removes. Both operands are the server's.
|
| 348 |
-
//
|
| 349 |
-
// β AND WITHOUT `now` IT DEGRADES TO THE OLD FORMAT RATHER THAN GUESSING. A caller that has no
|
| 350 |
-
// server clock gets `2026-08-13 09:41` β the pre-wave string, unambiguous and never wrong β
|
| 351 |
-
// instead of a relative stamp computed from something we do not trust.
|
| 352 |
-
const today = /^(\d{4}-\d{2}-\d{2})/.exec(str(now));
|
| 353 |
-
if (!today) return `${day} ${hhmm}`;
|
| 354 |
-
if (today[1] === day) return hhmm;
|
| 355 |
-
const [y, mo, d] = day.split("-");
|
| 356 |
-
const month = MONTHS[Number(mo) - 1] || mo;
|
| 357 |
-
// The year only when it differs β a mail client does not print "2026" on a message from March.
|
| 358 |
-
return today[1].slice(0, 4) === y
|
| 359 |
-
? `${month} ${Number(d)}`
|
| 360 |
-
: `${month} ${Number(d)}, ${y}`;
|
| 361 |
-
}
|
| 362 |
-
|
| 363 |
-
/**
|
| 364 |
-
* The badge's text. Never the raw number past 99: a nav row is 236px wide and a
|
| 365 |
-
* four-digit badge pushes the label out of it.
|
| 366 |
-
*/
|
| 367 |
-
export function badgeText(unread: number): string {
|
| 368 |
-
const n = Math.max(0, Math.floor(unread));
|
| 369 |
-
if (n <= 0) return "";
|
| 370 |
-
return n > 99 ? "99+" : String(n);
|
| 371 |
-
}
|
| 372 |
-
|
| 373 |
-
/**
|
| 374 |
-
* Apply a read/unread change LOCALLY, mirroring what the server just stored, and
|
| 375 |
-
* return the new inbox with the count corrected.
|
| 376 |
-
*
|
| 377 |
-
* `ids === null` is "all of them" (the API's own convention for mark-all). The
|
| 378 |
-
* count is derived from the ITEMS here β deliberately, and it is the one place
|
| 379 |
-
* that is right to do so: the server's answer is in flight, and the alternative
|
| 380 |
-
* is a badge that keeps its old number until the refetch lands.
|
| 381 |
-
*/
|
| 382 |
-
export function applyRead(inbox: Inbox, ids: string[] | null, read: boolean): Inbox {
|
| 383 |
-
const wanted = ids === null ? null : new Set(ids);
|
| 384 |
-
const items = inbox.items.map((n) =>
|
| 385 |
-
wanted === null || wanted.has(n.id) ? { ...n, read } : n
|
| 386 |
-
);
|
| 387 |
-
const seenUnread = items.filter((n) => !n.read).length;
|
| 388 |
-
// A page can hold fewer notifications than the account has, so a partial read
|
| 389 |
-
// must SUBTRACT from the server's count rather than replace it with this
|
| 390 |
-
// page's tally β except when marking everything, where zero is the answer.
|
| 391 |
-
if (wanted === null) return { unread: read ? 0 : items.length, items };
|
| 392 |
-
const changed = inbox.items.filter(
|
| 393 |
-
(n) => wanted.has(n.id) && n.read !== read
|
| 394 |
-
).length;
|
| 395 |
-
const delta = read ? -changed : changed;
|
| 396 |
-
return { unread: Math.max(seenUnread, inbox.unread + delta), items };
|
| 397 |
-
}
|
| 398 |
-
|
| 399 |
-
/**
|
| 400 |
-
* The shellβrail channel for "make an alert out of this view" β the view rail
|
| 401 |
-
* raises it, the frame (which knows the current route, and therefore the topic)
|
| 402 |
-
* answers. Same reason as C-SHARE's event: the rail is host-neutral and cannot
|
| 403 |
-
* import the shell, and it does not know its own scope key.
|
| 404 |
-
*/
|
| 405 |
-
export const ALERT_CREATE_EVENT = "aios:alert-create";
|
| 406 |
-
|
| 407 |
-
export interface AlertCreateRequest {
|
| 408 |
-
viewId: string;
|
| 409 |
-
label: string;
|
| 410 |
-
}
|
| 411 |
-
|
| 412 |
-
export function parseAlertCreate(detail: unknown): AlertCreateRequest | null {
|
| 413 |
-
if (!detail || typeof detail !== "object") return null;
|
| 414 |
-
const d = detail as Record<string, unknown>;
|
| 415 |
-
const viewId = str(d.viewId).trim();
|
| 416 |
-
if (!viewId) return null;
|
| 417 |
-
return { viewId, label: str(d.label).trim() || viewId };
|
| 418 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// alerts/alertsModel.ts β WAVE 20 item 25 (contract C-ALERT): the inbox's PURE
|
| 3 |
+
// half. React-free and fetch-free, so `verify_alerts.py` runs it under node.
|
| 4 |
+
//
|
| 5 |
+
// An alert says "tell me when a record ENTERS this view". The client half is
|
| 6 |
+
// small, and every part of it fails silently when it is wrong:
|
| 7 |
+
//
|
| 8 |
+
// Β· an unread count taken from `items.length` rather than from the server's
|
| 9 |
+
// own `unread` disagrees with the badge the moment a page is capped or a
|
| 10 |
+
// read lands in another tab β and a badge that says 3 when the list shows 9
|
| 11 |
+
// teaches the reader to ignore the badge;
|
| 12 |
+
// Β· a notification whose `viewId` no longer resolves must open NOTHING rather
|
| 13 |
+
// than a wrong view β alerts outlive the views they were made from;
|
| 14 |
+
// Β· `topic` is the surface's scope key ("customer", "product", "ut_β¦"), and
|
| 15 |
+
// the ROUTE is a registry key ("customer_data") β mapping one to the other
|
| 16 |
+
// by guesswork sends every click to a page that does not exist.
|
| 17 |
+
// ---------------------------------------------------------------------------
|
| 18 |
+
|
| 19 |
+
/**
|
| 20 |
+
* ββ WAVE 32 Β· T20 Β· CONTRACT C3 β WHERE AN INBOX ITEM OPENS.
|
| 21 |
+
*
|
| 22 |
+
* `module` is the destination surface (`"database"` or `"automation"`) and `id` is what to open
|
| 23 |
+
* in it. `tab` is the SUB-SELECTION inside that module: the literal `"runs"` for an automation's
|
| 24 |
+
* run log, or the VIEW ID to select on a database. One optional key, two destinations.
|
| 25 |
+
*
|
| 26 |
+
* β EVERY FIELD IS A PLAIN `string`, NEVER A UNION, and that is alertsModel's wave-9 law rather
|
| 27 |
+
* than laziness: the vocabulary is the SERVER's, and a client union over it turns "the server grew
|
| 28 |
+
* a module" into "the client silently drops the row". An unknown module is refused by the
|
| 29 |
+
* FRAME's dispatcher, out loud, which is a different thing from never arriving.
|
| 30 |
+
*/
|
| 31 |
+
export interface NotificationTarget {
|
| 32 |
+
module: string;
|
| 33 |
+
id: string;
|
| 34 |
+
tab?: string;
|
| 35 |
+
}
|
| 36 |
+
|
| 37 |
+
/** C3's `kind` vocabulary, mirroring `routes_alerts.NOTIF_KIND_*`. Held as constants so the
|
| 38 |
+
* Inbox's branch and the gate's fixtures cannot disagree about the word. */
|
| 39 |
+
export const NOTIF_KIND_ALERT = "alert";
|
| 40 |
+
export const NOTIF_KIND_AUTOMATION = "automation";
|
| 41 |
+
export const NOTIF_KIND_SHARE = "share";
|
| 42 |
+
|
| 43 |
+
/** C3's `target.module` vocabulary, and the automation sub-selection. */
|
| 44 |
+
export const TARGET_MODULE_DATABASE = "database";
|
| 45 |
+
export const TARGET_MODULE_AUTOMATION = "automation";
|
| 46 |
+
export const TARGET_TAB_RUNS = "runs";
|
| 47 |
+
|
| 48 |
+
/** One notification, as `GET /api/v1/notifications` sends it. */
|
| 49 |
+
export interface Notification {
|
| 50 |
+
id: string;
|
| 51 |
+
alertId: string;
|
| 52 |
+
viewId: string;
|
| 53 |
+
topic: string;
|
| 54 |
+
rowId: string;
|
| 55 |
+
/** What entered β the record's own label. */
|
| 56 |
+
label: string;
|
| 57 |
+
/** What the alert is called, so a row reads without opening anything. */
|
| 58 |
+
alertLabel: string;
|
| 59 |
+
/** UTC WITH OFFSET (D-18). Kept as the server's STRING: re-formatting it here
|
| 60 |
+
* would re-introduce the browser-clock drift the offset exists to remove. */
|
| 61 |
+
at: string;
|
| 62 |
+
read: boolean;
|
| 63 |
+
/**
|
| 64 |
+
* WAVE 23 (contract C6) β WHAT KIND of notification this is.
|
| 65 |
+
*
|
| 66 |
+
* Absent (and every notification written before this wave) means the original one: a record
|
| 67 |
+
* ENTERED a watched view, routed by `topic` + `viewId`. `"automation_review"` means a card
|
| 68 |
+
* arrived at a review stage and routes by `autoId` instead β a different destination reached
|
| 69 |
+
* from the same list.
|
| 70 |
+
*
|
| 71 |
+
* β A STRING, NEVER A UNION, and that is the wave-9 law rather than laziness: the vocabulary
|
| 72 |
+
* is the SERVER's, and a client union over it turns "the server grew a kind" into "the client
|
| 73 |
+
* silently drops the row". Unknown kinds fall through to the view route, which is exactly what
|
| 74 |
+
* they did before this field existed.
|
| 75 |
+
*/
|
| 76 |
+
kind?: string;
|
| 77 |
+
/** `automation_review` only: the automation whose review stage a card reached. Absent on
|
| 78 |
+
* every other kind β and an `automation_review` row that arrives WITHOUT one opens nothing
|
| 79 |
+
* rather than guessing, the same posture `viewId` gets. */
|
| 80 |
+
autoId?: string;
|
| 81 |
+
/** Advisory. A surface that does not scroll to a stage simply selects the automation. */
|
| 82 |
+
stageId?: string;
|
| 83 |
+
/** How many cards arrived in the batch. C6 queues ONE notification per run naming the count,
|
| 84 |
+
* never one per record β so this is the number the row's own text is built from. */
|
| 85 |
+
count?: number;
|
| 86 |
+
/**
|
| 87 |
+
* β WAVE 32 Β· C3 β THE HEADER LINE, so the Inbox can be laid out like mail.
|
| 88 |
+
*
|
| 89 |
+
* `subject` is what the item is ABOUT (the alert's name, the automation's name, the database
|
| 90 |
+
* that was shared); `label` stays what HAPPENED (the record that entered, the run summary).
|
| 91 |
+
* They were one field, which is why the pane could only ever render a sentence with no sender.
|
| 92 |
+
* Absent on a server that predates this wave β {@link subjectOf} falls back rather than
|
| 93 |
+
* rendering a blank header.
|
| 94 |
+
*/
|
| 95 |
+
subject?: string;
|
| 96 |
+
/**
|
| 97 |
+
* ββ WAVE 33 Β· W33-T28 β WHO IT IS FROM. Mail has a sender; this list did not.
|
| 98 |
+
*
|
| 99 |
+
* A `verifier` reading the finished wave-32 Inbox found the row's sender POSITION occupied by
|
| 100 |
+
* `kindLabel(n.kind)` β the literals "Alert" / "Automation" / "Shared with you", a CATEGORY
|
| 101 |
+
* standing where a who belongs β and no sender anywhere on the wire. Derived by the server
|
| 102 |
+
* (`routes_alerts.notification_view`), never here: only it knows that a share has a person
|
| 103 |
+
* behind it and an alert has a machine.
|
| 104 |
+
* β Optional, so a payload from a server that predates this wave keeps today's shape;
|
| 105 |
+
* {@link senderOf} falls back rather than rendering a blank From column.
|
| 106 |
+
*/
|
| 107 |
+
sender?: string;
|
| 108 |
+
/** β WAVE 32 Β· C3 β where clicking it goes. ABSENT when this product cannot resolve a
|
| 109 |
+
* destination (an alert on a table this account can no longer route to), and that absence is
|
| 110 |
+
* load-bearing: the Inbox renders such a row as plainly unclickable rather than as a click
|
| 111 |
+
* that silently does nothing. */
|
| 112 |
+
target?: NotificationTarget;
|
| 113 |
+
}
|
| 114 |
+
|
| 115 |
+
/** One alert, as `GET /api/v1/alerts` sends it. */
|
| 116 |
+
export interface Alert {
|
| 117 |
+
id: string;
|
| 118 |
+
viewId: string;
|
| 119 |
+
topic: string;
|
| 120 |
+
owner: string;
|
| 121 |
+
label: string;
|
| 122 |
+
createdAt: string;
|
| 123 |
+
/** How many records are in its remembered set right now. */
|
| 124 |
+
matched: number;
|
| 125 |
+
seeded: boolean;
|
| 126 |
+
lastRunAt: string;
|
| 127 |
+
lastError: string;
|
| 128 |
+
}
|
| 129 |
+
|
| 130 |
+
export interface Inbox {
|
| 131 |
+
unread: number;
|
| 132 |
+
items: Notification[];
|
| 133 |
+
/**
|
| 134 |
+
* ββ WAVE 33 Β· W33-T28 / D-208 β THE SERVER'S CLOCK, so a stamp can be mail-shaped.
|
| 135 |
+
*
|
| 136 |
+
* β It exists so {@link stampText} never reads the BROWSER's clock, which is D-208's exit
|
| 137 |
+
* condition word for word. `at` is UTC with its offset (D-18) precisely so every reader sees
|
| 138 |
+
* the same instant; asking "is this today?" of a local clock would put the drift back.
|
| 139 |
+
* β Optional: absent, `stampText` returns the old absolute string rather than guessing.
|
| 140 |
+
*/
|
| 141 |
+
now?: string;
|
| 142 |
+
}
|
| 143 |
+
|
| 144 |
+
export const EMPTY_INBOX: Inbox = { unread: 0, items: [] };
|
| 145 |
+
|
| 146 |
+
/**
|
| 147 |
+
* ββ WAVE 31 Β· T23 (owner item 1) β WHAT THE PANE IS ENTITLED TO SAY, AS A FUNCTION.
|
| 148 |
+
*
|
| 149 |
+
* Owner, verbatim: *"Alerts shows notification, but when clicked it says nothing, and it doesn't
|
| 150 |
+
* remove the notification number."* Both halves are ONE mechanism. `AlertsPane` held its own
|
| 151 |
+
* `inbox` seeded to {@link EMPTY_INBOX} and had no pending state, so between opening the panel
|
| 152 |
+
* and `GET /notifications` answering β measured at **3,280 ms live** β and for ever after a
|
| 153 |
+
* failed fetch:
|
| 154 |
+
* Β· `items` was `[]`, so the pane printed **"Nothing new."** β a claim, not a wait;
|
| 155 |
+
* Β· `unread` was `0`, so **"Mark all read" was `disabled`**, and the badge the frame had
|
| 156 |
+
* already loaded could never be cleared.
|
| 157 |
+
* A confident sentence about somebody's inbox, and the one control that would fix it, both
|
| 158 |
+
* switched off by the same uninitialised state.
|
| 159 |
+
*
|
| 160 |
+
* β IT IS A FUNCTION BECAUSE THE PANE IS TSX AND TSX IS NOT UNDER TEST HERE. `verify_alerts`
|
| 161 |
+
* compiles and RUNS this module under node; markup it cannot reach is markup no control can
|
| 162 |
+
* mutate. Deciding here means the truth table is asserted and each branch is load-bearing.
|
| 163 |
+
*/
|
| 164 |
+
export type PaneView = "pending" | "rows" | "empty" | "error";
|
| 165 |
+
|
| 166 |
+
/**
|
| 167 |
+
* `pending` while the first read is in flight Β· `error` when it failed and we have nothing to
|
| 168 |
+
* show Β· `rows` when there is something Β· `empty` ONLY when a successful read returned nothing.
|
| 169 |
+
*
|
| 170 |
+
* β ROWS WIN OVER AN ERROR, and that is deliberate rather than lax: a refresh that fails while
|
| 171 |
+
* the pane already holds notifications should not blank them β the reader loses real information
|
| 172 |
+
* to a transient. The error still reaches them as the pane's message line.
|
| 173 |
+
*/
|
| 174 |
+
export function paneView(
|
| 175 |
+
phase: "pending" | "ready" | "error",
|
| 176 |
+
rowCount: number,
|
| 177 |
+
seededUnread = 0
|
| 178 |
+
): PaneView {
|
| 179 |
+
if (rowCount > 0) return "rows";
|
| 180 |
+
if (phase === "pending") return "pending";
|
| 181 |
+
if (phase === "error") return "error";
|
| 182 |
+
// β A SUCCESSFUL READ WITH NO ROWS AND A NON-ZERO COUNT IS NOT "nothing new". The badge says
|
| 183 |
+
// there is something; the page we were given does not contain it. Saying "Nothing new" there
|
| 184 |
+
// is the same false confidence in a different costume.
|
| 185 |
+
return seededUnread > 0 ? "error" : "empty";
|
| 186 |
+
}
|
| 187 |
+
|
| 188 |
+
/**
|
| 189 |
+
* May "Mark all read" be pressed?
|
| 190 |
+
*
|
| 191 |
+
* β NOT `unread === 0`, WHICH IS THE SHIPPED BUG. That test asked the PANE's own state β zero
|
| 192 |
+
* until its fetch lands, zero for ever if the fetch fails β so the control was dead in exactly
|
| 193 |
+
* the situations the owner hit. The question is about the ACCOUNT, so it is asked of the count
|
| 194 |
+
* the frame already holds, and a failed read does not take the verb away: `POST /notifications/
|
| 195 |
+
* read` with `ids: null` clears the account's inbox whether or not we managed to list it.
|
| 196 |
+
*/
|
| 197 |
+
export function canMarkAll(unread: number, busy = false): boolean {
|
| 198 |
+
return !busy && Math.max(0, Math.floor(unread)) > 0;
|
| 199 |
+
}
|
| 200 |
+
|
| 201 |
+
const str = (v: unknown): string => (typeof v === "string" ? v : "");
|
| 202 |
+
const num = (v: unknown): number => (typeof v === "number" && isFinite(v) ? v : 0);
|
| 203 |
+
|
| 204 |
+
/**
|
| 205 |
+
* β WAVE 32 Β· C3 β one wire `target` β a {@link NotificationTarget}, or `null`.
|
| 206 |
+
*
|
| 207 |
+
* β BOTH `module` AND `id` ARE REQUIRED, and dropping either test is the failure this guard is
|
| 208 |
+
* for: a target with a module and no id dispatches an open request naming NOTHING β a click that
|
| 209 |
+
* appears to work and silently does not, which is this repo's most-repeated shape. `null` is
|
| 210 |
+
* rendered as an unclickable row, which a reader can SEE.
|
| 211 |
+
*/
|
| 212 |
+
export function parseTarget(raw: unknown): NotificationTarget | null {
|
| 213 |
+
if (!raw || typeof raw !== "object") return null;
|
| 214 |
+
const t = raw as Record<string, unknown>;
|
| 215 |
+
const module = str(t.module).trim();
|
| 216 |
+
const id = str(t.id).trim();
|
| 217 |
+
if (!module || !id) return null;
|
| 218 |
+
const tab = str(t.tab).trim();
|
| 219 |
+
return { module, id, ...(tab ? { tab } : {}) };
|
| 220 |
+
}
|
| 221 |
+
|
| 222 |
+
/**
|
| 223 |
+
* `GET /notifications` β the inbox, fail-closed.
|
| 224 |
+
*
|
| 225 |
+
* β `unread` COMES FROM THE SERVER, and is not recounted from `items`. The two
|
| 226 |
+
* can legitimately differ β the list is what this page holds, the count is what
|
| 227 |
+
* the account has β and recomputing it here would make the badge a function of
|
| 228 |
+
* whatever the last fetch happened to include.
|
| 229 |
+
*/
|
| 230 |
+
export function parseInbox(body: unknown): Inbox {
|
| 231 |
+
const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
|
| 232 |
+
const raw = Array.isArray(b.items) ? b.items : [];
|
| 233 |
+
const items: Notification[] = [];
|
| 234 |
+
for (const item of raw) {
|
| 235 |
+
if (!item || typeof item !== "object") continue;
|
| 236 |
+
const n = item as Record<string, unknown>;
|
| 237 |
+
const id = str(n.id);
|
| 238 |
+
// An id-less notification cannot be marked read, so it would sit unread for
|
| 239 |
+
// ever and hold the badge up. Dropped, not rendered.
|
| 240 |
+
if (!id) continue;
|
| 241 |
+
items.push({
|
| 242 |
+
id,
|
| 243 |
+
alertId: str(n.alertId),
|
| 244 |
+
viewId: str(n.viewId),
|
| 245 |
+
topic: str(n.topic),
|
| 246 |
+
rowId: String(n.rowId ?? ""),
|
| 247 |
+
label: str(n.label) || String(n.rowId ?? ""),
|
| 248 |
+
alertLabel: str(n.alertLabel),
|
| 249 |
+
at: str(n.at),
|
| 250 |
+
read: n.read === true,
|
| 251 |
+
// WAVE 23 C6 β ADDITIVE and spread-conditional, exactly like `NavPage`'s flags: a payload
|
| 252 |
+
// that predates this wave keeps today's shape rather than gaining four `undefined` keys,
|
| 253 |
+
// and an `automation_review` row missing its `autoId` is left WITHOUT one rather than
|
| 254 |
+
// with an empty string that would render as a real destination.
|
| 255 |
+
...(str(n.kind) ? { kind: str(n.kind) } : {}),
|
| 256 |
+
...(str(n.autoId) ? { autoId: str(n.autoId) } : {}),
|
| 257 |
+
...(str(n.stageId) ? { stageId: str(n.stageId) } : {}),
|
| 258 |
+
...(num(n.count) > 0 ? { count: num(n.count) } : {}),
|
| 259 |
+
// β WAVE 32 Β· C3 β additive and spread-conditional, exactly like the four above.
|
| 260 |
+
...(str(n.subject) ? { subject: str(n.subject) } : {}),
|
| 261 |
+
// β WAVE 33 Β· W33-T28 β additive and spread-conditional, like every flag above it.
|
| 262 |
+
...(str(n.sender) ? { sender: str(n.sender) } : {}),
|
| 263 |
+
...(parseTarget(n.target) ? { target: parseTarget(n.target)! } : {}),
|
| 264 |
+
});
|
| 265 |
+
}
|
| 266 |
+
// β W33-T28 / D-208 β the server's clock rides through, spread-conditionally like every other
|
| 267 |
+
// additive key here, so a server that predates this wave yields the same object it always did.
|
| 268 |
+
return {
|
| 269 |
+
unread: Math.max(0, num(b.unread)),
|
| 270 |
+
items,
|
| 271 |
+
...(str(b.now) ? { now: str(b.now) } : {}),
|
| 272 |
+
};
|
| 273 |
+
}
|
| 274 |
+
|
| 275 |
+
/** `GET /alerts` β the alert list, fail-closed. */
|
| 276 |
+
export function parseAlerts(body: unknown): Alert[] {
|
| 277 |
+
const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
|
| 278 |
+
const raw = Array.isArray(b.alerts) ? b.alerts : [];
|
| 279 |
+
const out: Alert[] = [];
|
| 280 |
+
for (const item of raw) {
|
| 281 |
+
if (!item || typeof item !== "object") continue;
|
| 282 |
+
const a = item as Record<string, unknown>;
|
| 283 |
+
const id = str(a.id);
|
| 284 |
+
if (!id) continue;
|
| 285 |
+
out.push({
|
| 286 |
+
id,
|
| 287 |
+
viewId: str(a.viewId),
|
| 288 |
+
topic: str(a.topic),
|
| 289 |
+
owner: str(a.owner),
|
| 290 |
+
label: str(a.label) || "Untitled alert",
|
| 291 |
+
createdAt: str(a.createdAt),
|
| 292 |
+
matched: num(a.matched),
|
| 293 |
+
seeded: a.seeded === true,
|
| 294 |
+
lastRunAt: str(a.lastRunAt),
|
| 295 |
+
lastError: str(a.lastError),
|
| 296 |
+
});
|
| 297 |
+
}
|
| 298 |
+
return out;
|
| 299 |
+
}
|
| 300 |
+
|
| 301 |
+
/**
|
| 302 |
+
* A topic (the grid's scope key) β the hash route that renders it.
|
| 303 |
+
*
|
| 304 |
+
* The two built-ins are the only pair that differ, and they differ because the
|
| 305 |
+
* REGISTRY names the surface while the GRID names the scope; a user table is its
|
| 306 |
+
* own key in both. `null` for anything else: a notification for a topic this
|
| 307 |
+
* client cannot route to must do nothing, not navigate somewhere plausible.
|
| 308 |
+
*/
|
| 309 |
+
export function routeForTopic(topic: string): string | null {
|
| 310 |
+
const t = str(topic).trim();
|
| 311 |
+
if (t === "customer") return "customer_data";
|
| 312 |
+
if (t === "product") return "product_data";
|
| 313 |
+
if (/^ut_[A-Za-z0-9_]+$/.test(t)) return t;
|
| 314 |
+
return null;
|
| 315 |
+
}
|
| 316 |
+
|
| 317 |
+
|
| 318 |
+
|
| 319 |
+
|
| 320 |
+
|
| 321 |
+
|
| 322 |
+
/**
|
| 323 |
+
* The stamp, made readable WITHOUT touching a clock.
|
| 324 |
+
*
|
| 325 |
+
* β NO `new Date()`, NO `toLocaleString()`, and that is the whole design. The
|
| 326 |
+
* server sends UTC WITH ITS OFFSET (D-18) precisely so every reader sees the
|
| 327 |
+
* same instant; parsing it into a browser Date and formatting it back would
|
| 328 |
+
* re-introduce the drift the offset exists to remove β a tenant a day ahead
|
| 329 |
+
* being told an event happened tomorrow ([[date-window-vocabulary]]). This is
|
| 330 |
+
* STRING SURGERY: keep the date and the minutes, drop the seconds and the `T`.
|
| 331 |
+
* Anything that does not look like an ISO stamp passes through untouched, so a
|
| 332 |
+
* format this function has never seen is shown as sent rather than mangled.
|
| 333 |
+
*/
|
| 334 |
+
const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
|
| 335 |
+
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
|
| 336 |
+
|
| 337 |
+
export function stampText(at: string, now?: string): string {
|
| 338 |
+
const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(str(at));
|
| 339 |
+
if (!m) return str(at);
|
| 340 |
+
const [, day, hhmm] = m;
|
| 341 |
+
// ββ W33-T28 / D-208 β MAIL-SHAPED, AND STILL STRING SURGERY.
|
| 342 |
+
//
|
| 343 |
+
// β `now` COMES FROM THE SERVER (`inbox.now`), NEVER FROM `new Date()`. That is D-208's exit
|
| 344 |
+
// condition word for word β "without reading the browser clock" β and the reason is the same
|
| 345 |
+
// one this function has always carried: `at` is sent as UTC WITH its offset (D-18) so every
|
| 346 |
+
// reader sees the same instant, and deciding "is this today?" against a browser clock would
|
| 347 |
+
// re-introduce exactly the drift the offset removes. Both operands are the server's.
|
| 348 |
+
//
|
| 349 |
+
// β AND WITHOUT `now` IT DEGRADES TO THE OLD FORMAT RATHER THAN GUESSING. A caller that has no
|
| 350 |
+
// server clock gets `2026-08-13 09:41` β the pre-wave string, unambiguous and never wrong β
|
| 351 |
+
// instead of a relative stamp computed from something we do not trust.
|
| 352 |
+
const today = /^(\d{4}-\d{2}-\d{2})/.exec(str(now));
|
| 353 |
+
if (!today) return `${day} ${hhmm}`;
|
| 354 |
+
if (today[1] === day) return hhmm;
|
| 355 |
+
const [y, mo, d] = day.split("-");
|
| 356 |
+
const month = MONTHS[Number(mo) - 1] || mo;
|
| 357 |
+
// The year only when it differs β a mail client does not print "2026" on a message from March.
|
| 358 |
+
return today[1].slice(0, 4) === y
|
| 359 |
+
? `${month} ${Number(d)}`
|
| 360 |
+
: `${month} ${Number(d)}, ${y}`;
|
| 361 |
+
}
|
| 362 |
+
|
| 363 |
+
/**
|
| 364 |
+
* The badge's text. Never the raw number past 99: a nav row is 236px wide and a
|
| 365 |
+
* four-digit badge pushes the label out of it.
|
| 366 |
+
*/
|
| 367 |
+
export function badgeText(unread: number): string {
|
| 368 |
+
const n = Math.max(0, Math.floor(unread));
|
| 369 |
+
if (n <= 0) return "";
|
| 370 |
+
return n > 99 ? "99+" : String(n);
|
| 371 |
+
}
|
| 372 |
+
|
| 373 |
+
/**
|
| 374 |
+
* Apply a read/unread change LOCALLY, mirroring what the server just stored, and
|
| 375 |
+
* return the new inbox with the count corrected.
|
| 376 |
+
*
|
| 377 |
+
* `ids === null` is "all of them" (the API's own convention for mark-all). The
|
| 378 |
+
* count is derived from the ITEMS here β deliberately, and it is the one place
|
| 379 |
+
* that is right to do so: the server's answer is in flight, and the alternative
|
| 380 |
+
* is a badge that keeps its old number until the refetch lands.
|
| 381 |
+
*/
|
| 382 |
+
export function applyRead(inbox: Inbox, ids: string[] | null, read: boolean): Inbox {
|
| 383 |
+
const wanted = ids === null ? null : new Set(ids);
|
| 384 |
+
const items = inbox.items.map((n) =>
|
| 385 |
+
wanted === null || wanted.has(n.id) ? { ...n, read } : n
|
| 386 |
+
);
|
| 387 |
+
const seenUnread = items.filter((n) => !n.read).length;
|
| 388 |
+
// A page can hold fewer notifications than the account has, so a partial read
|
| 389 |
+
// must SUBTRACT from the server's count rather than replace it with this
|
| 390 |
+
// page's tally β except when marking everything, where zero is the answer.
|
| 391 |
+
if (wanted === null) return { unread: read ? 0 : items.length, items };
|
| 392 |
+
const changed = inbox.items.filter(
|
| 393 |
+
(n) => wanted.has(n.id) && n.read !== read
|
| 394 |
+
).length;
|
| 395 |
+
const delta = read ? -changed : changed;
|
| 396 |
+
return { unread: Math.max(seenUnread, inbox.unread + delta), items };
|
| 397 |
+
}
|
| 398 |
+
|
| 399 |
+
/**
|
| 400 |
+
* The shellβrail channel for "make an alert out of this view" β the view rail
|
| 401 |
+
* raises it, the frame (which knows the current route, and therefore the topic)
|
| 402 |
+
* answers. Same reason as C-SHARE's event: the rail is host-neutral and cannot
|
| 403 |
+
* import the shell, and it does not know its own scope key.
|
| 404 |
+
*/
|
| 405 |
+
export const ALERT_CREATE_EVENT = "aios:alert-create";
|
| 406 |
+
|
| 407 |
+
export interface AlertCreateRequest {
|
| 408 |
+
viewId: string;
|
| 409 |
+
label: string;
|
| 410 |
+
}
|
| 411 |
+
|
| 412 |
+
export function parseAlertCreate(detail: unknown): AlertCreateRequest | null {
|
| 413 |
+
if (!detail || typeof detail !== "object") return null;
|
| 414 |
+
const d = detail as Record<string, unknown>;
|
| 415 |
+
const viewId = str(d.viewId).trim();
|
| 416 |
+
if (!viewId) return null;
|
| 417 |
+
return { viewId, label: str(d.label).trim() || viewId };
|
| 418 |
+
}
|
web/src/automation/AutomationFind.tsx
CHANGED
|
@@ -1,893 +1,893 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// automation/AutomationFind.tsx β the discovery filter, as TOGGLES (owner item 6,
|
| 3 |
-
// contract C4).
|
| 4 |
-
//
|
| 5 |
-
// WHAT CHANGED AND WHY. It was a condition BUILDER: an empty row, a field
|
| 6 |
-
// dropdown listing 21 names, "Add a condition". That shape asks the user to
|
| 7 |
-
// remember what is searchable before they can look, and it hid the only fact
|
| 8 |
-
// that decides whether a search returns anything at all β which fields actually
|
| 9 |
-
// carry values. The corpus is 620 million profiles and every run is billed, so
|
| 10 |
-
// "I did not know I could filter on that" and "I filtered on a field that is
|
| 11 |
-
// empty on every row" are both expensive mistakes made in silence.
|
| 12 |
-
//
|
| 13 |
-
// So every searchable field is ON SCREEN, off by default, and turning one on is
|
| 14 |
-
// what creates its condition. The list leads with the fields MEASURED to carry
|
| 15 |
-
// values; the rest are grouped under what is known about them, and neither group
|
| 16 |
-
// is hidden β R3 already decided that "every filter" means the 21 we can stand
|
| 17 |
-
// behind, so all 21 are visible.
|
| 18 |
-
//
|
| 19 |
-
// β THE VOCABULARY IS THE SERVER'S, ALL OF IT. Field names, operators, which
|
| 20 |
-
// operators take no value, the record ceiling and (once C4 lands it) which
|
| 21 |
-
// fields are populated and which narrow β every one of those rides on
|
| 22 |
-
// `GET /automations`. This file holds no list of its own. The reason is the one
|
| 23 |
-
// `automationApi.ts:11-15` gives for cron presets: the thing that ACCEPTS a
|
| 24 |
-
// filter is Python, and a client copy of what it accepts is a copy that can
|
| 25 |
-
// offer a search the server refuses.
|
| 26 |
-
//
|
| 27 |
-
// β AND IT DOES NOT RE-IMPLEMENT THE GUARD. `guard` carries the server's
|
| 28 |
-
// numbers, so the rows can say which fields narrow β but the refusal is the
|
| 29 |
-
// server's to make and this surface prints it VERBATIM when it comes back
|
| 30 |
-
// (`DiscoverGuard`'s note). A client that predicts the refusal is a second copy
|
| 31 |
-
// of the rule, free to disagree with the first, and when they disagree the user
|
| 32 |
-
// gets a Save button that is disabled for a reason nobody can see.
|
| 33 |
-
// ---------------------------------------------------------------------------
|
| 34 |
-
import { useEffect, useState } from "react";
|
| 35 |
-
// β WAVE 27 item 29 β the overlay layer the grid already owns, consumed rather than
|
| 36 |
-
// re-implemented: it is a body portal (so it escapes `.auto-panel`'s 380px), and it brings
|
| 37 |
-
// the dismiss/focus/placement behaviour every other popover on this product already has.
|
| 38 |
-
import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
|
| 39 |
-
import type { AnchorRect } from "../customer-grid/OverlaySurface";
|
| 40 |
-
|
| 41 |
-
import type {
|
| 42 |
-
DiscoverEstimate,
|
| 43 |
-
DiscoverFieldMeta,
|
| 44 |
-
DiscoverOperator,
|
| 45 |
-
DiscoverVocab,
|
| 46 |
-
Predicate,
|
| 47 |
-
} from "./automationApi";
|
| 48 |
-
import { discoverCategories } from "./automationApi";
|
| 49 |
-
|
| 50 |
-
interface Props {
|
| 51 |
-
/** The server-declared discovery vocabulary (absent until the list loads). */
|
| 52 |
-
discover?: DiscoverVocab;
|
| 53 |
-
recordsLimit: number;
|
| 54 |
-
onRecordsLimit: (n: number) => void;
|
| 55 |
-
joinOp: string;
|
| 56 |
-
onJoinOp: (v: string) => void;
|
| 57 |
-
preds: Predicate[];
|
| 58 |
-
onPreds: (next: Predicate[]) => void;
|
| 59 |
-
estimate: DiscoverEstimate | null;
|
| 60 |
-
onEstimate: () => void;
|
| 61 |
-
}
|
| 62 |
-
|
| 63 |
-
/**
|
| 64 |
-
* A FILTER FIELD'S ICON (owner item 5). Drawn, `currentColor`, never an emoji β and in the
|
| 65 |
-
* existing `TriggerMark`/`ActionMark` language rather than a new one: same 16 viewBox, same 15px
|
| 66 |
-
* box, same 1.4 stroke, so a row here and a card in the builder read as one product.
|
| 67 |
-
*
|
| 68 |
-
* β SHARED SHAPES WHERE THE FIELDS SHARE A MEANING, distinct everywhere else. `TriggerMark`'s
|
| 69 |
-
* note settled the principle β a column of identical glyphs is decoration, the eye learns nothing
|
| 70 |
-
* β but its converse matters just as much here: `bio_hashtags` and `post_hashtags` ARE both
|
| 71 |
-
* hashtags, and drawing two different marks for them would invent a distinction the vendor does
|
| 72 |
-
* not make. Twenty-one contrived glyphs would be twenty-one things to misread.
|
| 73 |
-
*
|
| 74 |
-
* β THE FALLBACK IS NOT A MEMBER OF THE SET, which is the `ActionMark` scar exactly: its default
|
| 75 |
-
* used to BE the pencil, a real member, so every unmatched kind silently borrowed "edit" and a
|
| 76 |
-
* fallback could not be told from a match. The vocabulary is the SERVER's β it can grow a field
|
| 77 |
-
* tomorrow β so an unmatched name draws a neutral mark that is deliberately meaningless.
|
| 78 |
-
*/
|
| 79 |
-
function FilterMark({ name }: { name: string }) {
|
| 80 |
-
const common = {
|
| 81 |
-
width: 15, height: 15, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor",
|
| 82 |
-
strokeWidth: 1.4, strokeLinecap: "round" as const, strokeLinejoin: "round" as const,
|
| 83 |
-
"aria-hidden": true,
|
| 84 |
-
};
|
| 85 |
-
// Audience size β two figures, one behind the other.
|
| 86 |
-
if (name === "followers")
|
| 87 |
-
return (
|
| 88 |
-
<svg {...common}>
|
| 89 |
-
<circle cx="6.2" cy="5.6" r="2.4" />
|
| 90 |
-
<path d="M2.2 13c.5-2 2.1-3.2 4-3.2s3.5 1.2 4 3.2" />
|
| 91 |
-
<path d="M10.6 3.6a2.4 2.4 0 0 1 0 4M11.4 9.9c1.4.4 2.4 1.5 2.8 3.1" />
|
| 92 |
-
</svg>
|
| 93 |
-
);
|
| 94 |
-
// Who this account follows β a figure with an outbound arrow.
|
| 95 |
-
if (name === "following")
|
| 96 |
-
return (
|
| 97 |
-
<svg {...common}>
|
| 98 |
-
<circle cx="6" cy="5.6" r="2.4" />
|
| 99 |
-
<path d="M1.8 13c.5-2 2.1-3.2 4.2-3.2 .6 0 1.2.1 1.7.3" />
|
| 100 |
-
<path d="M9.8 10.6h4.2M12.2 8.8l1.8 1.8-1.8 1.8" />
|
| 101 |
-
</svg>
|
| 102 |
-
);
|
| 103 |
-
if (name === "posts_count")
|
| 104 |
-
return (
|
| 105 |
-
<svg {...common}>
|
| 106 |
-
<rect x="2.6" y="2.6" width="4.6" height="4.6" rx="1" />
|
| 107 |
-
<rect x="8.8" y="2.6" width="4.6" height="4.6" rx="1" />
|
| 108 |
-
<rect x="2.6" y="8.8" width="4.6" height="4.6" rx="1" />
|
| 109 |
-
<rect x="8.8" y="8.8" width="4.6" height="4.6" rx="1" />
|
| 110 |
-
</svg>
|
| 111 |
-
);
|
| 112 |
-
// A story highlight β the ring Instagram draws around one.
|
| 113 |
-
if (name === "highlights_count")
|
| 114 |
-
return (
|
| 115 |
-
<svg {...common}>
|
| 116 |
-
<circle cx="8" cy="8" r="5.6" strokeDasharray="2.6 1.8" />
|
| 117 |
-
<circle cx="8" cy="8" r="2.2" />
|
| 118 |
-
</svg>
|
| 119 |
-
);
|
| 120 |
-
if (name === "avg_engagement")
|
| 121 |
-
return (
|
| 122 |
-
<svg {...common}>
|
| 123 |
-
<path d="M8 13.2 3.4 8.8a2.9 2.9 0 0 1 4.6-3.4 2.9 2.9 0 0 1 4.6 3.4z" />
|
| 124 |
-
</svg>
|
| 125 |
-
);
|
| 126 |
-
if (name === "biography")
|
| 127 |
-
return (
|
| 128 |
-
<svg {...common}>
|
| 129 |
-
<rect x="2.4" y="2.8" width="11.2" height="10.4" rx="1.6" />
|
| 130 |
-
<path d="M4.8 6h6.4M4.8 8.4h6.4M4.8 10.8h3.6" />
|
| 131 |
-
</svg>
|
| 132 |
-
);
|
| 133 |
-
if (name === "category_name" || name === "business_category_name")
|
| 134 |
-
return (
|
| 135 |
-
<svg {...common}>
|
| 136 |
-
<path d="M8.4 2.6H13v4.6l-6.2 6.2-4.6-4.6z" />
|
| 137 |
-
<circle cx="10.8" cy="5.2" r="0.9" />
|
| 138 |
-
</svg>
|
| 139 |
-
);
|
| 140 |
-
if (name === "is_business_account" || name === "is_professional_account")
|
| 141 |
-
return (
|
| 142 |
-
<svg {...common}>
|
| 143 |
-
<rect x="2.2" y="5" width="11.6" height="8.2" rx="1.6" />
|
| 144 |
-
<path d="M6 5V3.6a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1V5" />
|
| 145 |
-
</svg>
|
| 146 |
-
);
|
| 147 |
-
if (name === "is_verified")
|
| 148 |
-
return (
|
| 149 |
-
<svg {...common}>
|
| 150 |
-
<path d="M8 2.2l1.7 1.2 2-.2.6 2 1.7 1.1-.9 1.9.9 1.9-1.7 1.1-.6 2-2-.2L8 14.2l-1.7-1.2-2 .2-.6-2L2 10.1l.9-1.9L2 6.3l1.7-1.1.6-2 2 .2z" />
|
| 151 |
-
<path d="m5.8 8.1 1.5 1.5 3-3.1" />
|
| 152 |
-
</svg>
|
| 153 |
-
);
|
| 154 |
-
// The handle, and the display name it is written under.
|
| 155 |
-
if (name === "account" || name === "profile_name")
|
| 156 |
-
return (
|
| 157 |
-
<svg {...common}>
|
| 158 |
-
<circle cx="8" cy="8" r="2.4" />
|
| 159 |
-
<path d="M10.4 5.6v3.2a1.9 1.9 0 0 0 3.2 1.3A5.8 5.8 0 1 0 11 13.1" />
|
| 160 |
-
</svg>
|
| 161 |
-
);
|
| 162 |
-
if (name === "full_name")
|
| 163 |
-
return (
|
| 164 |
-
<svg {...common}>
|
| 165 |
-
<circle cx="8" cy="5.6" r="2.6" />
|
| 166 |
-
<path d="M3 13.4c.7-2.3 2.6-3.6 5-3.6s4.3 1.3 5 3.6" />
|
| 167 |
-
</svg>
|
| 168 |
-
);
|
| 169 |
-
if (name === "external_url" || name === "profile_url")
|
| 170 |
-
return (
|
| 171 |
-
<svg {...common}>
|
| 172 |
-
<path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
|
| 173 |
-
<path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
|
| 174 |
-
<path d="M6.2 8h3.6" />
|
| 175 |
-
</svg>
|
| 176 |
-
);
|
| 177 |
-
if (name === "bio_hashtags" || name === "post_hashtags")
|
| 178 |
-
return (
|
| 179 |
-
<svg {...common}>
|
| 180 |
-
<path d="M6.2 2.8 4.8 13.2M11.2 2.8 9.8 13.2M2.8 6h10.4M2.2 10h10.4" />
|
| 181 |
-
</svg>
|
| 182 |
-
);
|
| 183 |
-
if (name === "related_accounts")
|
| 184 |
-
return (
|
| 185 |
-
<svg {...common}>
|
| 186 |
-
<circle cx="8" cy="3.6" r="1.8" />
|
| 187 |
-
<circle cx="3.6" cy="12" r="1.8" />
|
| 188 |
-
<circle cx="12.4" cy="12" r="1.8" />
|
| 189 |
-
<path d="M6.8 5.2 4.6 10.4M9.2 5.2l2.2 5.2M5.4 12h5.2" />
|
| 190 |
-
</svg>
|
| 191 |
-
);
|
| 192 |
-
// The vendor's own record keys β the thing you hold to open exactly one row.
|
| 193 |
-
if (name === "id" || name === "fbid")
|
| 194 |
-
return (
|
| 195 |
-
<svg {...common}>
|
| 196 |
-
<circle cx="5.4" cy="10.6" r="2.6" />
|
| 197 |
-
<path d="M7.2 8.8 13 3M10.6 5.4l1.6 1.6M9.2 6.8l1.6 1.6" />
|
| 198 |
-
</svg>
|
| 199 |
-
);
|
| 200 |
-
return (
|
| 201 |
-
<svg {...common}>
|
| 202 |
-
<rect x="3.2" y="3.2" width="9.6" height="9.6" rx="2.2" />
|
| 203 |
-
<circle cx="8" cy="8" r="1.4" />
|
| 204 |
-
</svg>
|
| 205 |
-
);
|
| 206 |
-
}
|
| 207 |
-
|
| 208 |
-
/** One field's line in the list, with everything known about it. */
|
| 209 |
-
interface FieldRow {
|
| 210 |
-
name: string;
|
| 211 |
-
/** What the row is CALLED. Falls back to the raw name only if the server sent none. */
|
| 212 |
-
label: string;
|
| 213 |
-
hint: string;
|
| 214 |
-
kind: string;
|
| 215 |
-
operators: DiscoverOperator[];
|
| 216 |
-
options: { value: string; label: string }[];
|
| 217 |
-
/** Every stored condition naming this field, with its index in the saved array. */
|
| 218 |
-
at: number[];
|
| 219 |
-
/** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
|
| 220 |
-
populated: boolean | null;
|
| 221 |
-
/** A condition here cuts the corpus down. `null` = not said. */
|
| 222 |
-
narrowing: boolean | null;
|
| 223 |
-
}
|
| 224 |
-
|
| 225 |
-
/** A stored value β what the text box shows. A list is the "any of" shape. */
|
| 226 |
-
function valueText(v: Predicate["value"]): string {
|
| 227 |
-
if (Array.isArray(v)) return v.join(", ");
|
| 228 |
-
return v === undefined || v === null ? "" : String(v);
|
| 229 |
-
}
|
| 230 |
-
|
| 231 |
-
/**
|
| 232 |
-
* What the user typed β what is stored. Comma-separated becomes a LIST for the operators that
|
| 233 |
-
* accept one, and stays a plain string for the ones that do not.
|
| 234 |
-
*
|
| 235 |
-
* β A single value stays a SCALAR rather than a one-element list β the server sends scalars
|
| 236 |
-
* flat and lists as a nested OR group, and a one-element group is a shape nothing has been
|
| 237 |
-
* billed against.
|
| 238 |
-
*/
|
| 239 |
-
function parseValue(text: string, multi: boolean): Predicate["value"] {
|
| 240 |
-
if (!multi) return text;
|
| 241 |
-
const parts = text.split(",").map((s) => s.trim()).filter(Boolean);
|
| 242 |
-
if (parts.length > 1) return parts;
|
| 243 |
-
// Keep the RAW text while it is still being typed β trimming here would fight the cursor on
|
| 244 |
-
// every keystroke, and the server trims anyway.
|
| 245 |
-
return text;
|
| 246 |
-
}
|
| 247 |
-
|
| 248 |
-
/**
|
| 249 |
-
* β WAVE 26 Β· DEBT D-69 β A THIRD VALUE COULD NOT BE TYPED, and the cause was one round trip
|
| 250 |
-
* through this pair of functions.
|
| 251 |
-
*
|
| 252 |
-
* `parseValue` returns an ARRAY at 2+ values; `valueText` then renders that array as
|
| 253 |
-
* `join(", ")` β which has NO TRAILING COMMA. So on a controlled input the separator was
|
| 254 |
-
* normalised away between keystrokes: typing `,` onto `skincare, beauty` re-rendered as
|
| 255 |
-
* `skincare, beauty`, and the next character landed as `skincare, beautym`. Two keywords
|
| 256 |
-
* silently became one that matches nothing. β It hit the FIRST surface a new user meets (wave 24
|
| 257 |
-
* made this panel the only door) and it hit precisely the 3+ keyword list the feature was built
|
| 258 |
-
* for β the owner's *"if i want to include many keywords like floral, flower, beauty"*.
|
| 259 |
-
*
|
| 260 |
-
* β THE FIX IS THE ONE `parseValue`'s OWN COMMENT ALREADY DESCRIBES FOR THE 1-VALUE CASE:
|
| 261 |
-
* keep the raw text while it is being typed. That comment was right and its scope was too narrow
|
| 262 |
-
* β it protected the cursor at one value and handed the 2+ case to `join`. So the raw text is
|
| 263 |
-
* held for whichever input is FOCUSED, and the stored value is still parsed on every keystroke
|
| 264 |
-
* (so nothing depends on blur to save) and re-parsed on blur (so the display settles).
|
| 265 |
-
*
|
| 266 |
-
* β KEYED BY THE ROW'S REACT KEY, not by index alone: two conditions on the same field are
|
| 267 |
-
* ordinary here ("Another condition on Bio"), and an index-only key would leak one row's draft
|
| 268 |
-
* into its sibling on a removal.
|
| 269 |
-
*/
|
| 270 |
-
interface Draft {
|
| 271 |
-
key: string;
|
| 272 |
-
text: string;
|
| 273 |
-
}
|
| 274 |
-
|
| 275 |
-
/**
|
| 276 |
-
* The comparison a freshly toggled field starts with β ASKED FOR, never chosen here.
|
| 277 |
-
*
|
| 278 |
-
* β THE THIRD COSTUME OF ONE SCAR, and the reason this function no longer has an opinion.
|
| 279 |
-
* Wave 21 made a new condition NULLARY (`is_not_null`) so it would be saveable without a
|
| 280 |
-
* value, and called that "narrowing-in-the-right-direction". Wave 22 then wrote the narrowing
|
| 281 |
-
* law server-side and `is_not_null` is not in it. From that moment, toggling ANY field on and
|
| 282 |
-
* pressing Save returned "add at least one CONTENT conditionβ¦" β the error told the user to do
|
| 283 |
-
* the exact thing they had just done. Wave 24 deleted the wizard and made this panel the only
|
| 284 |
-
* door, so it stopped being a corner case and became the first thing a new user hits.
|
| 285 |
-
*
|
| 286 |
-
* The fix is not a better guess. It is that the module owning the guard also names the default
|
| 287 |
-
* (`automation_engine.default_operator`, asserted against `predicate_narrows` in
|
| 288 |
-
* `verify_automation.py`), and this file looks it up per FIELD. An absent one falls back to the
|
| 289 |
-
* server's first operator β never to a nullary, which is the thing that could not narrow.
|
| 290 |
-
*/
|
| 291 |
-
function firstOperator(v: DiscoverVocab | undefined, name: string): string {
|
| 292 |
-
const meta = (v?.filterMeta || []).find((m) => m.name === name);
|
| 293 |
-
return meta?.defaultOperator || (v?.operators || [])[0] || "";
|
| 294 |
-
}
|
| 295 |
-
|
| 296 |
-
/**
|
| 297 |
-
* The rows, ordered: measured-populated first, then the rest.
|
| 298 |
-
*
|
| 299 |
-
* TWO SOURCES, AND THE FALLBACK IS NARROWER THAN THE REAL THING. With C4's
|
| 300 |
-
* `filterMeta` the answer is per field and complete. Without it, `lead` names
|
| 301 |
-
* the three fields seen carrying values and says NOTHING about the other
|
| 302 |
-
* eighteen β so those come back `null`, not `false`, and the UI prints no claim
|
| 303 |
-
* about them rather than an invented one.
|
| 304 |
-
*/
|
| 305 |
-
function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
|
| 306 |
-
const meta = new Map<string, DiscoverFieldMeta>(
|
| 307 |
-
(v?.filterMeta || []).map((m) => [m.name, m])
|
| 308 |
-
);
|
| 309 |
-
const lead = new Set(v?.lead || []);
|
| 310 |
-
const byName = new Map<string, number[]>();
|
| 311 |
-
preds.forEach((p, i) => {
|
| 312 |
-
const list = byName.get(p.name);
|
| 313 |
-
if (list) list.push(i);
|
| 314 |
-
else byName.set(p.name, [i]);
|
| 315 |
-
});
|
| 316 |
-
|
| 317 |
-
const rows = (v?.fields || []).map((name) => {
|
| 318 |
-
const m = meta.get(name);
|
| 319 |
-
return {
|
| 320 |
-
name,
|
| 321 |
-
label: m?.label || name,
|
| 322 |
-
hint: m?.hint || "",
|
| 323 |
-
kind: m?.kind || "text",
|
| 324 |
-
// β NO FALLBACK TO THE GLOBAL OPERATOR LIST. An older server that sends no per-field list
|
| 325 |
-
// gets a row with no comparisons rather than all fourteen on every field β visibly
|
| 326 |
-
// unfinished beats quietly offering `at least` on a yes/no column.
|
| 327 |
-
operators: m?.operators || [],
|
| 328 |
-
options: m?.options || [],
|
| 329 |
-
at: byName.get(name) || [],
|
| 330 |
-
populated: m ? !!m.populated : lead.has(name) ? true : null,
|
| 331 |
-
narrowing: m ? !!m.narrowing : null,
|
| 332 |
-
};
|
| 333 |
-
});
|
| 334 |
-
// Stable partition, never a sort: the server's order inside each half is the
|
| 335 |
-
// order the engine lists them in, and re-alphabetising it would be this file
|
| 336 |
-
// having an opinion about a server list.
|
| 337 |
-
return [...rows.filter((r) => r.populated === true), ...rows.filter((r) => r.populated !== true)];
|
| 338 |
-
}
|
| 339 |
-
|
| 340 |
-
export default function AutomationFind({
|
| 341 |
-
discover,
|
| 342 |
-
recordsLimit,
|
| 343 |
-
onRecordsLimit,
|
| 344 |
-
joinOp,
|
| 345 |
-
onJoinOp,
|
| 346 |
-
preds,
|
| 347 |
-
onPreds,
|
| 348 |
-
estimate,
|
| 349 |
-
onEstimate,
|
| 350 |
-
}: Props) {
|
| 351 |
-
const rows = buildRows(preds, discover);
|
| 352 |
-
const known = new Set(discover?.fields || []);
|
| 353 |
-
// The GLOBAL operator list is gone from this component: comparisons are per field now
|
| 354 |
-
// (`row.operators`). `nullary` survives for STRAYS only β a stored condition on a field the
|
| 355 |
-
// vendor dropped has no per-field row to read from, and it still has to render to be removable.
|
| 356 |
-
const nullary = new Set(discover?.nullaryOperators || []);
|
| 357 |
-
const withValues = rows.filter((r) => r.populated === true);
|
| 358 |
-
const rest = rows.filter((r) => r.populated !== true);
|
| 359 |
-
const knownMeta = !!(discover?.filterMeta || []).length;
|
| 360 |
-
// β THE STORED FILTER CAN NAME A FIELD THE LIST NO LONGER HAS β a vocabulary
|
| 361 |
-
// that moved, an automation copied from elsewhere. It must stay VISIBLE and
|
| 362 |
-
// REMOVABLE: a condition the user cannot see is one they cannot delete, and
|
| 363 |
-
// every Save keeps sending it. Same defect as a `<select>` whose value matches
|
| 364 |
-
// no option, one level up.
|
| 365 |
-
const strays = preds
|
| 366 |
-
.map((p, i) => ({ p, i }))
|
| 367 |
-
.filter(({ p }) => !known.has(p.name));
|
| 368 |
-
|
| 369 |
-
const maxRecords = discover?.guard?.maxRecords || discover?.maxRecords || 500;
|
| 370 |
-
|
| 371 |
-
/** D-69 β the raw text of the input a person is typing in right now (see `Draft`). */
|
| 372 |
-
const [draft, setDraft] = useState<Draft | null>(null);
|
| 373 |
-
|
| 374 |
-
/**
|
| 375 |
-
* β WAVE 27 Β· OWNER ITEM 29 β which condition's value is open in the BIG editor, if any.
|
| 376 |
-
*
|
| 377 |
-
* β THE TEXT IS HELD HERE, NOT WRITTEN THROUGH ON EVERY KEYSTROKE, and that is the one place
|
| 378 |
-
* this differs from the rail input beside it. The rail input writes per keystroke on purpose
|
| 379 |
-
* (a Save pressed straight from the field must not store the previous value β D-69's note).
|
| 380 |
-
* A modal has its own Save, so per-keystroke writes would buy nothing and would make Cancel
|
| 381 |
-
* a lie: the value would already be in the config by the time it was pressed.
|
| 382 |
-
* β The ANCHOR is captured at click time and stored, because the button it came from is
|
| 383 |
-
* inside a panel that scrolls β re-reading it later would place the overlay against a rect
|
| 384 |
-
* that has moved.
|
| 385 |
-
*/
|
| 386 |
-
const [big, setBig] = useState<{
|
| 387 |
-
key: string;
|
| 388 |
-
index: number;
|
| 389 |
-
label: string;
|
| 390 |
-
multi: boolean;
|
| 391 |
-
text: string;
|
| 392 |
-
anchor: AnchorRect;
|
| 393 |
-
} | null>(null);
|
| 394 |
-
|
| 395 |
-
/**
|
| 396 |
-
* β ITEM 16 / D-71 β THE OBSERVED CATEGORY VALUES, fetched WHEN THIS PANEL OPENS.
|
| 397 |
-
*
|
| 398 |
-
* β ON MOUNT, ONCE, AND NEVER ON THE POLLED PAYLOAD. This component is rendered only while the
|
| 399 |
-
* Find panel is open, so mounting IS the panel opening β and the server moved these off
|
| 400 |
-
* `GET /automations` after measuring that deriving them reads two user tables plus the platform
|
| 401 |
-
* master, i.e. a network round-trip per open tab every 2.5 s. Putting the request here is the
|
| 402 |
-
* client half of that same decision, not an optimisation.
|
| 403 |
-
*
|
| 404 |
-
* β AN EMPTY LIST IS AN ANSWER AND IS RENDERED AS ONE. It means this deployment has not seen a
|
| 405 |
-
* category value yet β which is TRUE for a fresh tenant β and the field keeps its free-text
|
| 406 |
-
* input either way. It must never read as "loading forever", and it must never be filled in
|
| 407 |
-
* with a guess: D-59 is explicit that an invented taxonomy is worse than no dropdown.
|
| 408 |
-
*/
|
| 409 |
-
const [cats, setCats] = useState<{ value: string; count: number }[]>([]);
|
| 410 |
-
useEffect(() => {
|
| 411 |
-
const ac = new AbortController();
|
| 412 |
-
discoverCategories(ac.signal)
|
| 413 |
-
.then((r) => setCats(Array.isArray(r?.options) ? r.options : []))
|
| 414 |
-
// Fail-quiet, on purpose: the picker is an ASSIST over a control that works without it.
|
| 415 |
-
// An error banner here would report a broken panel when the only thing missing is a
|
| 416 |
-
// convenience β and the free-text input beside it is unaffected.
|
| 417 |
-
.catch(() => setCats([]));
|
| 418 |
-
return () => ac.abort();
|
| 419 |
-
}, []);
|
| 420 |
-
|
| 421 |
-
const setAt = (i: number, patch: Partial<Predicate>) =>
|
| 422 |
-
onPreds(preds.map((p, j) => (j === i ? { ...p, ...patch } : p)));
|
| 423 |
-
|
| 424 |
-
const removeAt = (i: number) => onPreds(preds.filter((_p, j) => j !== i));
|
| 425 |
-
|
| 426 |
-
const toggleField = (row: FieldRow) => {
|
| 427 |
-
if (row.at.length) {
|
| 428 |
-
onPreds(preds.filter((p) => p.name !== row.name));
|
| 429 |
-
return;
|
| 430 |
-
}
|
| 431 |
-
onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }]);
|
| 432 |
-
};
|
| 433 |
-
|
| 434 |
-
/** One condition line β the comparison, its value, and a way out. */
|
| 435 |
-
const condition = (i: number, label: string, row?: FieldRow) => {
|
| 436 |
-
const p = preds[i];
|
| 437 |
-
if (!p) return null;
|
| 438 |
-
// The field's OWN comparisons. `row` is absent only for a stray (a stored condition on a
|
| 439 |
-
// field the vendor no longer offers), which keeps the raw token so it stays removable.
|
| 440 |
-
const ops = row?.operators || [];
|
| 441 |
-
const cur = ops.find((o) => o.value === p.operator);
|
| 442 |
-
const isNullary = cur ? cur.nullary : nullary.has(p.operator);
|
| 443 |
-
const isMulti = !!cur?.multi;
|
| 444 |
-
const options = row?.options || [];
|
| 445 |
-
const rowKey = `${p.name}-${i}`;
|
| 446 |
-
// D-69: the focused input shows what was TYPED; every other one shows the stored value.
|
| 447 |
-
const shown = draft && draft.key === rowKey ? draft.text : valueText(p.value);
|
| 448 |
-
/*
|
| 449 |
-
* β ITEM 16 / D-71 β WHICH FIELDS GET THE OBSERVED-VALUES PICKER, DERIVED OFF THE WIRE.
|
| 450 |
-
*
|
| 451 |
-
* β NOT A CLIENT-SIDE LIST OF FIELD NAMES. Naming the vendor's two category columns here
|
| 452 |
-
* would be the D-55 class verbatim β the wave-9 silent-drop shape, a client copy of a server
|
| 453 |
-
* vocabulary that is free to drift the day the engine adds a third one. (Their literal keys
|
| 454 |
-
* are deliberately not written anywhere in this file: the gate asserts the tokens are ABSENT,
|
| 455 |
-
* and an absence check cannot tell a hard-coded list from the comment forbidding one.)
|
| 456 |
-
* The server already publishes the answer twice over: `kind: "choice"` is its own declaration
|
| 457 |
-
* (`BD_FIELD_KINDS`), and `filter_meta` deliberately ships `options: []` for those fields
|
| 458 |
-
* because their vocabulary is OBSERVED rather than declared and arrives on its own route.
|
| 459 |
-
* So the rule is exactly that: a choice-kind field with no declared options is one whose
|
| 460 |
-
* values we can only have learned by seeing them. A new choice field inherits this for free.
|
| 461 |
-
*/
|
| 462 |
-
const wantsObserved = row?.kind === "choice" && !options.length;
|
| 463 |
-
/** D-71 β APPEND, never replace: the picker has to compose with the comma list. */
|
| 464 |
-
const appendValue = (v: string) => {
|
| 465 |
-
const has = shown
|
| 466 |
-
.split(",")
|
| 467 |
-
.map((s) => s.trim().toLowerCase())
|
| 468 |
-
.filter(Boolean);
|
| 469 |
-
// Picking the same value twice is a no-op rather than a duplicate: the server expands a
|
| 470 |
-
// multi-value condition into an OR, and `beauty OR beauty` costs a slot to say nothing.
|
| 471 |
-
if (has.includes(v.trim().toLowerCase())) return;
|
| 472 |
-
const next = shown.trim() ? `${shown.replace(/[\s,]+$/, "")}, ${v}` : v;
|
| 473 |
-
setDraft(null);
|
| 474 |
-
setAt(i, { value: parseValue(next, isMulti) });
|
| 475 |
-
};
|
| 476 |
-
return (
|
| 477 |
-
<div className="autob-cond" key={rowKey}>
|
| 478 |
-
<select
|
| 479 |
-
className="auto-input is-small"
|
| 480 |
-
aria-label={`Comparison for ${label}`}
|
| 481 |
-
value={p.operator}
|
| 482 |
-
onChange={(e) => setAt(i, { operator: e.target.value })}
|
| 483 |
-
>
|
| 484 |
-
{/* The stored value is ALWAYS an option. A select whose value matches no
|
| 485 |
-
option renders the FIRST one, and the next Save writes a comparison
|
| 486 |
-
nobody chose β this codebase has paid for that twice. */}
|
| 487 |
-
{p.operator && !ops.some((o) => o.value === p.operator) ? (
|
| 488 |
-
<option value={p.operator}>{p.operator}</option>
|
| 489 |
-
) : null}
|
| 490 |
-
{ops.map((o) => (
|
| 491 |
-
<option key={o.value} value={o.value}>
|
| 492 |
-
{o.label}
|
| 493 |
-
</option>
|
| 494 |
-
))}
|
| 495 |
-
</select>
|
| 496 |
-
{isNullary ? null : options.length ? (
|
| 497 |
-
// A fixed vocabulary gets a dropdown. Owner item 2: a yes/no column was a box you
|
| 498 |
-
// typed `true` into, beside a comparison list that offered "at least".
|
| 499 |
-
<select
|
| 500 |
-
className="auto-input is-small"
|
| 501 |
-
aria-label={`Value for ${label}`}
|
| 502 |
-
value={valueText(p.value)}
|
| 503 |
-
onChange={(e) => setAt(i, { value: e.target.value })}
|
| 504 |
-
>
|
| 505 |
-
<option value="">Chooseβ¦</option>
|
| 506 |
-
{options.map((o) => (
|
| 507 |
-
<option key={o.value} value={o.value}>
|
| 508 |
-
{o.label}
|
| 509 |
-
</option>
|
| 510 |
-
))}
|
| 511 |
-
</select>
|
| 512 |
-
) : (
|
| 513 |
-
<input
|
| 514 |
-
className="auto-input is-small"
|
| 515 |
-
type={row?.kind === "number" ? "number" : "text"}
|
| 516 |
-
aria-label={`Value for ${label}`}
|
| 517 |
-
// β OWNER ITEM 3. Several comma-separated values become an "any of" condition, which
|
| 518 |
-
// the server sends as its own OR group β so it does NOT drag Followers into a union
|
| 519 |
-
// the way the Match dropdown would.
|
| 520 |
-
placeholder={isMulti ? "floral, flower, beauty" : ""}
|
| 521 |
-
// D-69: `shown` is the RAW text while this input has focus, so a trailing comma
|
| 522 |
-
// survives long enough to type the next value after it.
|
| 523 |
-
value={shown}
|
| 524 |
-
onFocus={() => setDraft({ key: rowKey, text: valueText(p.value) })}
|
| 525 |
-
onChange={(e) => {
|
| 526 |
-
setDraft({ key: rowKey, text: e.target.value });
|
| 527 |
-
// The STORE still updates on every keystroke. Parsing only on blur would mean a
|
| 528 |
-
// Save pressed straight from the field wrote the previous value β trading a typing
|
| 529 |
-
// bug for a data-loss one.
|
| 530 |
-
setAt(i, { value: parseValue(e.target.value, isMulti) });
|
| 531 |
-
}}
|
| 532 |
-
onBlur={(e) => {
|
| 533 |
-
setDraft(null);
|
| 534 |
-
setAt(i, { value: parseValue(e.target.value, isMulti) });
|
| 535 |
-
}}
|
| 536 |
-
/>
|
| 537 |
-
)}
|
| 538 |
-
{/* β WAVE 27 Β· OWNER ITEM 29 β A WIDE EDITOR FOR THE VALUES THAT DO NOT FIT.
|
| 539 |
-
β THE COMPLAINT IS GEOMETRY, and the geometry is a CHAIN nothing here can widen:
|
| 540 |
-
`.auto-panel` is 380px, `.autob-cond .auto-input` divides what is left across three
|
| 541 |
-
controls, and `.is-small` trims it again β so a bio phrase list ("floral, flower,
|
| 542 |
-
wedding florist, event styling") is typed six characters at a time through a box
|
| 543 |
-
that scrolls sideways. The panel cannot grow; the EDITOR can leave it, and an
|
| 544 |
-
overlay is drawn in a body portal, so it is not bound by that chain at all.
|
| 545 |
-
β ALWAYS OFFERED, never "appears once the text is long": a control that materialises
|
| 546 |
-
at some threshold is one people do not know exists at the moment they need it.
|
| 547 |
-
β NOT on a `<select>` value (a fixed vocabulary has nothing to expand) and not on a
|
| 548 |
-
nullary comparison (which has no value at all). */}
|
| 549 |
-
{!isNullary && !options.length ? (
|
| 550 |
-
<button
|
| 551 |
-
type="button"
|
| 552 |
-
className="auto-input is-small autoc-expand"
|
| 553 |
-
aria-label={`Open a bigger editor for ${label}`}
|
| 554 |
-
title="Edit in a bigger box"
|
| 555 |
-
onClick={(e) => {
|
| 556 |
-
// β READ SYNCHRONOUSLY from the event. `currentTarget` is null by the time React
|
| 557 |
-
// re-invokes a state updater, and a null rect here paints the overlay at 0,0 β
|
| 558 |
-
// measured, in this repo, on a different control ([[react-event-currenttarget-updater]]).
|
| 559 |
-
const r = e.currentTarget.getBoundingClientRect();
|
| 560 |
-
setBig({
|
| 561 |
-
key: rowKey,
|
| 562 |
-
index: i,
|
| 563 |
-
label,
|
| 564 |
-
multi: isMulti,
|
| 565 |
-
text: valueText(p.value),
|
| 566 |
-
anchor: { left: r.left, top: r.top, right: r.right, bottom: r.bottom,
|
| 567 |
-
width: r.width, height: r.height },
|
| 568 |
-
});
|
| 569 |
-
}}
|
| 570 |
-
>
|
| 571 |
-
{/* Drawn, never a glyph: the design constitution's "no emojis in the UI" covers
|
| 572 |
-
the arrow characters too, and every other mark in this product is a path in the
|
| 573 |
-
same 16x16 stroke vocabulary. Two corners pulling apart = "make this bigger". */}
|
| 574 |
-
<svg viewBox="0 0 16 16" aria-hidden className="autoc-expand-icon">
|
| 575 |
-
<path d="M9.5 2.5h4v4M13.5 2.5 9.6 6.4" />
|
| 576 |
-
<path d="M6.5 13.5h-4v-4M2.5 13.5l3.9-3.9" />
|
| 577 |
-
</svg>
|
| 578 |
-
</button>
|
| 579 |
-
) : null}
|
| 580 |
-
{/* β ITEM 16 / D-71 β THE APPEND-PICKER, BESIDE the input and never instead of it.
|
| 581 |
-
Free text stays the primary control: these are the values this deployment has SEEN,
|
| 582 |
-
not the values that exist, so the picker is a shortcut over a superset it cannot
|
| 583 |
-
enumerate. Appending in code also sidesteps D-69 entirely β a picked value never has
|
| 584 |
-
to survive a round trip through the text box. */}
|
| 585 |
-
{wantsObserved && !isNullary ? (
|
| 586 |
-
<select
|
| 587 |
-
className="auto-input is-small autoc-catpick"
|
| 588 |
-
aria-label={`Add a value seen before, to ${label}`}
|
| 589 |
-
title={
|
| 590 |
-
cats.length
|
| 591 |
-
? "Values this workspace has actually seen, most-seen first. Adds to the list."
|
| 592 |
-
: "No category values have been seen in your data yet. Type one."
|
| 593 |
-
}
|
| 594 |
-
value=""
|
| 595 |
-
disabled={!cats.length}
|
| 596 |
-
onChange={(e) => {
|
| 597 |
-
if (e.target.value) appendValue(e.target.value);
|
| 598 |
-
}}
|
| 599 |
-
>
|
| 600 |
-
<option value="">{cats.length ? "Seen beforeβ¦" : "None seen yet"}</option>
|
| 601 |
-
{cats.map((c) => (
|
| 602 |
-
// The COUNT is the honest half (D-59): a value seen once and one seen forty times
|
| 603 |
-
// are different bets, and an alphabetical list of bare strings hides that.
|
| 604 |
-
<option key={c.value} value={c.value}>
|
| 605 |
-
{c.value} ({c.count.toLocaleString()})
|
| 606 |
-
</option>
|
| 607 |
-
))}
|
| 608 |
-
</select>
|
| 609 |
-
) : null}
|
| 610 |
-
{isMulti && Array.isArray(p.value) && p.value.length > 1 ? (
|
| 611 |
-
/*
|
| 612 |
-
* β ITEM 16 / D-71 β HOW MANY VALUES THIS CONDITION CARRIES, and against what ceiling.
|
| 613 |
-
*
|
| 614 |
-
* The COUNT is ours and is always shown. The CEILING is the server's and is shown only
|
| 615 |
-
* when the server sends one (`guard.maxValues` β an open `ASK ->A:`; `guard` ships
|
| 616 |
-
* `{minNarrowing, maxRecords}` today).
|
| 617 |
-
* β NO CLIENT-SIDE `4`. D-71's exit says "how many of D-68's 4 value slots" β but A
|
| 618 |
-
* shipped `depth_refusal()`, which computes the depth of the shape actually emitted
|
| 619 |
-
* rather than budgeting fixed slots, so the number 4 describes a model that no longer
|
| 620 |
-
* exists. Printing it would be a client copy of a server rule that has already changed
|
| 621 |
-
* once, which is the specific failure this file's header refuses to commit
|
| 622 |
-
* ([[measure-the-real-call]]: a correct-looking answer about the wrong subject).
|
| 623 |
-
*/
|
| 624 |
-
<span className="autob-cond-any" title="Any one of these is a match">
|
| 625 |
-
any of {p.value.length}
|
| 626 |
-
{discover?.guard?.maxValues ? ` of ${discover.guard.maxValues}` : ""}
|
| 627 |
-
</span>
|
| 628 |
-
) : null}
|
| 629 |
-
<button
|
| 630 |
-
type="button"
|
| 631 |
-
className="autob-cond-x"
|
| 632 |
-
aria-label={`Remove this condition on ${label}`}
|
| 633 |
-
title="Remove this condition"
|
| 634 |
-
onClick={() => removeAt(i)}
|
| 635 |
-
>
|
| 636 |
-
<svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
|
| 637 |
-
<path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
|
| 638 |
-
</svg>
|
| 639 |
-
</button>
|
| 640 |
-
</div>
|
| 641 |
-
);
|
| 642 |
-
};
|
| 643 |
-
|
| 644 |
-
const fieldRow = (row: FieldRow) => {
|
| 645 |
-
const on = row.at.length > 0;
|
| 646 |
-
return (
|
| 647 |
-
<div className={"autob-tgl" + (on ? " is-on" : "")} key={row.name}>
|
| 648 |
-
<div className="autob-tgl-head">
|
| 649 |
-
<button
|
| 650 |
-
type="button"
|
| 651 |
-
className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
|
| 652 |
-
aria-pressed={on}
|
| 653 |
-
aria-label={`${on ? "Stop searching" : "Search"} on ${row.label}`}
|
| 654 |
-
title={`${on ? "Stop searching" : "Search"} on ${row.label}`}
|
| 655 |
-
onClick={() => toggleField(row)}
|
| 656 |
-
>
|
| 657 |
-
<span className="auto-step-switch-knob" />
|
| 658 |
-
</button>
|
| 659 |
-
<span className="autob-tgl-mark">
|
| 660 |
-
<FilterMark name={row.name} />
|
| 661 |
-
</span>
|
| 662 |
-
{/* β THE HUMAN LABEL (owner item 1: "wtf is id/fbid").
|
| 663 |
-
This used to render the vendor's own column name verbatim, and the comment
|
| 664 |
-
defending it was RIGHT about the reason β a refusal names the field, and a label
|
| 665 |
-
that reads differently makes the error unmatchable. So the label did not move
|
| 666 |
-
alone: `field_label()` is what the SERVER's refusals use too, which is the only
|
| 667 |
-
version of this change that does not trade one confusion for another. */}
|
| 668 |
-
<span className="autob-tgl-name" title={row.hint || undefined}>
|
| 669 |
-
{row.label}
|
| 670 |
-
</span>
|
| 671 |
-
{/*
|
| 672 |
-
β ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
|
| 673 |
-
non-narrowing field "broad" AND every unpopulated one "no values seen" β
|
| 674 |
-
which put two chips on 18 of the 21 rows, and one of them repeated the group
|
| 675 |
-
heading the row was already sitting under. A mark that is on almost every row
|
| 676 |
-
stops being a mark. Read off the screenshot; no assertion could have said it.
|
| 677 |
-
|
| 678 |
-
So: the group label carries POPULATED (it is what the groups ARE), and the
|
| 679 |
-
chip carries NARROWING, inverted to mark the five that DO narrow. That is the
|
| 680 |
-
actionable half β the server refuses a filter with no narrowing condition, so
|
| 681 |
-
"these are the ones that satisfy it" is the sentence a user needs, and
|
| 682 |
-
"this one does not" is not.
|
| 683 |
-
*/}
|
| 684 |
-
{row.narrowing === true ? (
|
| 685 |
-
<span
|
| 686 |
-
className="autob-tgl-flag is-narrow"
|
| 687 |
-
title="A search needs at least one condition like this."
|
| 688 |
-
>
|
| 689 |
-
narrows
|
| 690 |
-
</span>
|
| 691 |
-
) : null}
|
| 692 |
-
</div>
|
| 693 |
-
{on ? (
|
| 694 |
-
<div className="autob-tgl-body">
|
| 695 |
-
{row.at.map((i) => condition(i, row.label, row))}
|
| 696 |
-
{row.hint ? <p className="autob-tgl-hint">{row.hint}</p> : null}
|
| 697 |
-
<button
|
| 698 |
-
type="button"
|
| 699 |
-
className="autob-cond-add"
|
| 700 |
-
onClick={() =>
|
| 701 |
-
onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
|
| 702 |
-
}
|
| 703 |
-
>
|
| 704 |
-
Another condition on {row.label}
|
| 705 |
-
</button>
|
| 706 |
-
</div>
|
| 707 |
-
) : null}
|
| 708 |
-
</div>
|
| 709 |
-
);
|
| 710 |
-
};
|
| 711 |
-
|
| 712 |
-
return (
|
| 713 |
-
<>
|
| 714 |
-
<div className="auto-field">
|
| 715 |
-
<label htmlFor="auto-records">How many profiles to fetch</label>
|
| 716 |
-
<input
|
| 717 |
-
id="auto-records"
|
| 718 |
-
className="auto-input"
|
| 719 |
-
type="number"
|
| 720 |
-
min={1}
|
| 721 |
-
max={maxRecords}
|
| 722 |
-
value={recordsLimit}
|
| 723 |
-
onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
|
| 724 |
-
/>
|
| 725 |
-
</div>
|
| 726 |
-
{/* Owner item 5: "Stop at the 'A search must be at most 500 profiles a run'". The two
|
| 727 |
-
sentences that followed explained the vendor's billing model to somebody who wants a
|
| 728 |
-
list of florists. */}
|
| 729 |
-
<p className="auto-hint">At most {maxRecords.toLocaleString()} profiles a run.</p>
|
| 730 |
-
|
| 731 |
-
<h3>Conditions</h3>
|
| 732 |
-
<div className="auto-field autob-match">
|
| 733 |
-
<label htmlFor="auto-joinop">Match</label>
|
| 734 |
-
<select
|
| 735 |
-
id="auto-joinop"
|
| 736 |
-
className="auto-input"
|
| 737 |
-
value={joinOp}
|
| 738 |
-
onChange={(e) => onJoinOp(e.target.value)}
|
| 739 |
-
>
|
| 740 |
-
<option value="and">All of them</option>
|
| 741 |
-
<option value="or">Any of them</option>
|
| 742 |
-
</select>
|
| 743 |
-
</div>
|
| 744 |
-
|
| 745 |
-
{!rows.length ? (
|
| 746 |
-
<p className="auto-note">
|
| 747 |
-
The searchable fields have not loaded yet.
|
| 748 |
-
</p>
|
| 749 |
-
) : null}
|
| 750 |
-
|
| 751 |
-
{withValues.length ? (
|
| 752 |
-
<div className="autob-tglgroup">
|
| 753 |
-
<p
|
| 754 |
-
className="autob-tglgroup-label"
|
| 755 |
-
title="Most accounts have this filled in."
|
| 756 |
-
>
|
| 757 |
-
Usually filled in
|
| 758 |
-
</p>
|
| 759 |
-
{withValues.map(fieldRow)}
|
| 760 |
-
</div>
|
| 761 |
-
) : null}
|
| 762 |
-
|
| 763 |
-
{rest.length ? (
|
| 764 |
-
<div className="autob-tglgroup">
|
| 765 |
-
<p
|
| 766 |
-
className="autob-tglgroup-label"
|
| 767 |
-
title={
|
| 768 |
-
knownMeta
|
| 769 |
-
? "Most accounts leave these blank, so a condition here can return nothing."
|
| 770 |
-
: "We have not measured how often these are filled in."
|
| 771 |
-
}
|
| 772 |
-
>
|
| 773 |
-
{knownMeta ? "Often blank" : "Not measured"}
|
| 774 |
-
</p>
|
| 775 |
-
{rest.map(fieldRow)}
|
| 776 |
-
</div>
|
| 777 |
-
) : null}
|
| 778 |
-
|
| 779 |
-
{strays.length ? (
|
| 780 |
-
<div className="autob-tglgroup">
|
| 781 |
-
<p className="autob-tglgroup-label">Not in the searchable list</p>
|
| 782 |
-
{strays.map(({ p, i }) => (
|
| 783 |
-
<div className="autob-tgl is-on is-stray" key={`stray-${i}`}>
|
| 784 |
-
<div className="autob-tgl-head">
|
| 785 |
-
{/* A stray gets a mark too β "every filter row" includes the ones the vendor no
|
| 786 |
-
longer offers, and a row missing the icon its neighbours have would read as a
|
| 787 |
-
different KIND of thing rather than as a field that fell out of the list. It
|
| 788 |
-
draws the neutral fallback by construction: a stray is, by definition, not in
|
| 789 |
-
the vocabulary this component has arms for. */}
|
| 790 |
-
<span className="autob-tgl-mark">
|
| 791 |
-
<FilterMark name={p.name} />
|
| 792 |
-
</span>
|
| 793 |
-
<span className="autob-tgl-name">{p.name}</span>
|
| 794 |
-
<span className="autob-tgl-flag is-stray" title="The server will refuse this condition by name.">
|
| 795 |
-
not searchable
|
| 796 |
-
</span>
|
| 797 |
-
</div>
|
| 798 |
-
<div className="autob-tgl-body">{condition(i, p.name)}</div>
|
| 799 |
-
</div>
|
| 800 |
-
))}
|
| 801 |
-
</div>
|
| 802 |
-
) : null}
|
| 803 |
-
|
| 804 |
-
{/* The consequence kept, the mechanism dropped: a condition on an often-blank field
|
| 805 |
-
returning nothing is a thing that will happen to somebody and confuse them. Why the
|
| 806 |
-
search is slow when broad is our problem, not theirs. */}
|
| 807 |
-
<p className="auto-hint">
|
| 808 |
-
Conditions on often-blank fields can come back with nothing.
|
| 809 |
-
</p>
|
| 810 |
-
|
| 811 |
-
<h3>What it costs</h3>
|
| 812 |
-
<div className="auto-head-actions">
|
| 813 |
-
<button type="button" className="auto-btn" onClick={onEstimate}>
|
| 814 |
-
Estimate this search
|
| 815 |
-
</button>
|
| 816 |
-
</div>
|
| 817 |
-
{estimate ? (
|
| 818 |
-
<p className="auto-hint">
|
| 819 |
-
About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
|
| 820 |
-
{estimate.unitUsd} each.{" "}
|
| 821 |
-
{/*
|
| 822 |
-
THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run and this
|
| 823 |
-
deployment cannot read its own balance, so presenting this as a billed figure
|
| 824 |
-
would be inventing a measurement.
|
| 825 |
-
*/}
|
| 826 |
-
<strong>This is an estimate</strong> β {estimate.note}.
|
| 827 |
-
</p>
|
| 828 |
-
) : null}
|
| 829 |
-
|
| 830 |
-
{/* β WAVE 27 Β· OWNER ITEM 29 β THE BIG EDITOR, rendered ONCE for the whole panel.
|
| 831 |
-
β Not one overlay per condition row: `AnchoredOverlay` mounts a body portal and
|
| 832 |
-
installs document-level dismiss/focus handlers, so N of them would be N listener
|
| 833 |
-
stacks fighting over one Escape key. One overlay, told which row it is editing.
|
| 834 |
-
β `role="dialog"`, not "menu": it holds a text field, and the menu layer's arrow-key
|
| 835 |
-
handling would take the cursor keys away from the text being typed. */}
|
| 836 |
-
{big ? (
|
| 837 |
-
<AnchoredOverlay
|
| 838 |
-
anchor={big.anchor}
|
| 839 |
-
className="autoc-bigedit"
|
| 840 |
-
placement="right-start"
|
| 841 |
-
role="dialog"
|
| 842 |
-
ariaLabel={`Value for ${big.label}`}
|
| 843 |
-
onDismiss={() => setBig(null)}
|
| 844 |
-
dataKind="find-value-editor"
|
| 845 |
-
>
|
| 846 |
-
<label htmlFor="autoc-bigedit-text">{big.label}</label>
|
| 847 |
-
<textarea
|
| 848 |
-
id="autoc-bigedit-text"
|
| 849 |
-
className="autoc-bigedit-text"
|
| 850 |
-
data-overlay-autofocus
|
| 851 |
-
autoFocus
|
| 852 |
-
rows={7}
|
| 853 |
-
spellCheck={false}
|
| 854 |
-
value={big.text}
|
| 855 |
-
placeholder={big.multi ? "floral, flower, wedding florist, event styling" : ""}
|
| 856 |
-
onChange={(e) => setBig((cur) => (cur ? { ...cur, text: e.target.value } : cur))}
|
| 857 |
-
onKeyDown={(e) => {
|
| 858 |
-
// Escape abandons; Ctrl/Cmd+Enter commits. A bare Enter types a NEWLINE, because
|
| 859 |
-
// this is a textarea and the whole reason it exists is that the value is long.
|
| 860 |
-
if (e.key === "Escape") setBig(null);
|
| 861 |
-
if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
|
| 862 |
-
setAt(big.index, { value: parseValue(big.text, big.multi) });
|
| 863 |
-
setBig(null);
|
| 864 |
-
}
|
| 865 |
-
}}
|
| 866 |
-
/>
|
| 867 |
-
{/* The same sentence the rail input's placeholder makes, said where there is room
|
| 868 |
-
for it: a comma list is several values, and the server turns them into an OR. */}
|
| 869 |
-
{big.multi ? (
|
| 870 |
-
<p className="auto-hint">
|
| 871 |
-
Separate values with commas. The search matches any of them.
|
| 872 |
-
</p>
|
| 873 |
-
) : null}
|
| 874 |
-
<div className="auto-head-actions">
|
| 875 |
-
<button
|
| 876 |
-
type="button"
|
| 877 |
-
className="auto-btn auto-btn--primary"
|
| 878 |
-
onClick={() => {
|
| 879 |
-
setAt(big.index, { value: parseValue(big.text, big.multi) });
|
| 880 |
-
setBig(null);
|
| 881 |
-
}}
|
| 882 |
-
>
|
| 883 |
-
Done
|
| 884 |
-
</button>
|
| 885 |
-
<button type="button" className="auto-btn" onClick={() => setBig(null)}>
|
| 886 |
-
Cancel
|
| 887 |
-
</button>
|
| 888 |
-
</div>
|
| 889 |
-
</AnchoredOverlay>
|
| 890 |
-
) : null}
|
| 891 |
-
</>
|
| 892 |
-
);
|
| 893 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// automation/AutomationFind.tsx β the discovery filter, as TOGGLES (owner item 6,
|
| 3 |
+
// contract C4).
|
| 4 |
+
//
|
| 5 |
+
// WHAT CHANGED AND WHY. It was a condition BUILDER: an empty row, a field
|
| 6 |
+
// dropdown listing 21 names, "Add a condition". That shape asks the user to
|
| 7 |
+
// remember what is searchable before they can look, and it hid the only fact
|
| 8 |
+
// that decides whether a search returns anything at all β which fields actually
|
| 9 |
+
// carry values. The corpus is 620 million profiles and every run is billed, so
|
| 10 |
+
// "I did not know I could filter on that" and "I filtered on a field that is
|
| 11 |
+
// empty on every row" are both expensive mistakes made in silence.
|
| 12 |
+
//
|
| 13 |
+
// So every searchable field is ON SCREEN, off by default, and turning one on is
|
| 14 |
+
// what creates its condition. The list leads with the fields MEASURED to carry
|
| 15 |
+
// values; the rest are grouped under what is known about them, and neither group
|
| 16 |
+
// is hidden β R3 already decided that "every filter" means the 21 we can stand
|
| 17 |
+
// behind, so all 21 are visible.
|
| 18 |
+
//
|
| 19 |
+
// β THE VOCABULARY IS THE SERVER'S, ALL OF IT. Field names, operators, which
|
| 20 |
+
// operators take no value, the record ceiling and (once C4 lands it) which
|
| 21 |
+
// fields are populated and which narrow β every one of those rides on
|
| 22 |
+
// `GET /automations`. This file holds no list of its own. The reason is the one
|
| 23 |
+
// `automationApi.ts:11-15` gives for cron presets: the thing that ACCEPTS a
|
| 24 |
+
// filter is Python, and a client copy of what it accepts is a copy that can
|
| 25 |
+
// offer a search the server refuses.
|
| 26 |
+
//
|
| 27 |
+
// β AND IT DOES NOT RE-IMPLEMENT THE GUARD. `guard` carries the server's
|
| 28 |
+
// numbers, so the rows can say which fields narrow β but the refusal is the
|
| 29 |
+
// server's to make and this surface prints it VERBATIM when it comes back
|
| 30 |
+
// (`DiscoverGuard`'s note). A client that predicts the refusal is a second copy
|
| 31 |
+
// of the rule, free to disagree with the first, and when they disagree the user
|
| 32 |
+
// gets a Save button that is disabled for a reason nobody can see.
|
| 33 |
+
// ---------------------------------------------------------------------------
|
| 34 |
+
import { useEffect, useState } from "react";
|
| 35 |
+
// β WAVE 27 item 29 β the overlay layer the grid already owns, consumed rather than
|
| 36 |
+
// re-implemented: it is a body portal (so it escapes `.auto-panel`'s 380px), and it brings
|
| 37 |
+
// the dismiss/focus/placement behaviour every other popover on this product already has.
|
| 38 |
+
import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
|
| 39 |
+
import type { AnchorRect } from "../customer-grid/OverlaySurface";
|
| 40 |
+
|
| 41 |
+
import type {
|
| 42 |
+
DiscoverEstimate,
|
| 43 |
+
DiscoverFieldMeta,
|
| 44 |
+
DiscoverOperator,
|
| 45 |
+
DiscoverVocab,
|
| 46 |
+
Predicate,
|
| 47 |
+
} from "./automationApi";
|
| 48 |
+
import { discoverCategories } from "./automationApi";
|
| 49 |
+
|
| 50 |
+
interface Props {
|
| 51 |
+
/** The server-declared discovery vocabulary (absent until the list loads). */
|
| 52 |
+
discover?: DiscoverVocab;
|
| 53 |
+
recordsLimit: number;
|
| 54 |
+
onRecordsLimit: (n: number) => void;
|
| 55 |
+
joinOp: string;
|
| 56 |
+
onJoinOp: (v: string) => void;
|
| 57 |
+
preds: Predicate[];
|
| 58 |
+
onPreds: (next: Predicate[]) => void;
|
| 59 |
+
estimate: DiscoverEstimate | null;
|
| 60 |
+
onEstimate: () => void;
|
| 61 |
+
}
|
| 62 |
+
|
| 63 |
+
/**
|
| 64 |
+
* A FILTER FIELD'S ICON (owner item 5). Drawn, `currentColor`, never an emoji β and in the
|
| 65 |
+
* existing `TriggerMark`/`ActionMark` language rather than a new one: same 16 viewBox, same 15px
|
| 66 |
+
* box, same 1.4 stroke, so a row here and a card in the builder read as one product.
|
| 67 |
+
*
|
| 68 |
+
* β SHARED SHAPES WHERE THE FIELDS SHARE A MEANING, distinct everywhere else. `TriggerMark`'s
|
| 69 |
+
* note settled the principle β a column of identical glyphs is decoration, the eye learns nothing
|
| 70 |
+
* β but its converse matters just as much here: `bio_hashtags` and `post_hashtags` ARE both
|
| 71 |
+
* hashtags, and drawing two different marks for them would invent a distinction the vendor does
|
| 72 |
+
* not make. Twenty-one contrived glyphs would be twenty-one things to misread.
|
| 73 |
+
*
|
| 74 |
+
* β THE FALLBACK IS NOT A MEMBER OF THE SET, which is the `ActionMark` scar exactly: its default
|
| 75 |
+
* used to BE the pencil, a real member, so every unmatched kind silently borrowed "edit" and a
|
| 76 |
+
* fallback could not be told from a match. The vocabulary is the SERVER's β it can grow a field
|
| 77 |
+
* tomorrow β so an unmatched name draws a neutral mark that is deliberately meaningless.
|
| 78 |
+
*/
|
| 79 |
+
function FilterMark({ name }: { name: string }) {
|
| 80 |
+
const common = {
|
| 81 |
+
width: 15, height: 15, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor",
|
| 82 |
+
strokeWidth: 1.4, strokeLinecap: "round" as const, strokeLinejoin: "round" as const,
|
| 83 |
+
"aria-hidden": true,
|
| 84 |
+
};
|
| 85 |
+
// Audience size β two figures, one behind the other.
|
| 86 |
+
if (name === "followers")
|
| 87 |
+
return (
|
| 88 |
+
<svg {...common}>
|
| 89 |
+
<circle cx="6.2" cy="5.6" r="2.4" />
|
| 90 |
+
<path d="M2.2 13c.5-2 2.1-3.2 4-3.2s3.5 1.2 4 3.2" />
|
| 91 |
+
<path d="M10.6 3.6a2.4 2.4 0 0 1 0 4M11.4 9.9c1.4.4 2.4 1.5 2.8 3.1" />
|
| 92 |
+
</svg>
|
| 93 |
+
);
|
| 94 |
+
// Who this account follows β a figure with an outbound arrow.
|
| 95 |
+
if (name === "following")
|
| 96 |
+
return (
|
| 97 |
+
<svg {...common}>
|
| 98 |
+
<circle cx="6" cy="5.6" r="2.4" />
|
| 99 |
+
<path d="M1.8 13c.5-2 2.1-3.2 4.2-3.2 .6 0 1.2.1 1.7.3" />
|
| 100 |
+
<path d="M9.8 10.6h4.2M12.2 8.8l1.8 1.8-1.8 1.8" />
|
| 101 |
+
</svg>
|
| 102 |
+
);
|
| 103 |
+
if (name === "posts_count")
|
| 104 |
+
return (
|
| 105 |
+
<svg {...common}>
|
| 106 |
+
<rect x="2.6" y="2.6" width="4.6" height="4.6" rx="1" />
|
| 107 |
+
<rect x="8.8" y="2.6" width="4.6" height="4.6" rx="1" />
|
| 108 |
+
<rect x="2.6" y="8.8" width="4.6" height="4.6" rx="1" />
|
| 109 |
+
<rect x="8.8" y="8.8" width="4.6" height="4.6" rx="1" />
|
| 110 |
+
</svg>
|
| 111 |
+
);
|
| 112 |
+
// A story highlight β the ring Instagram draws around one.
|
| 113 |
+
if (name === "highlights_count")
|
| 114 |
+
return (
|
| 115 |
+
<svg {...common}>
|
| 116 |
+
<circle cx="8" cy="8" r="5.6" strokeDasharray="2.6 1.8" />
|
| 117 |
+
<circle cx="8" cy="8" r="2.2" />
|
| 118 |
+
</svg>
|
| 119 |
+
);
|
| 120 |
+
if (name === "avg_engagement")
|
| 121 |
+
return (
|
| 122 |
+
<svg {...common}>
|
| 123 |
+
<path d="M8 13.2 3.4 8.8a2.9 2.9 0 0 1 4.6-3.4 2.9 2.9 0 0 1 4.6 3.4z" />
|
| 124 |
+
</svg>
|
| 125 |
+
);
|
| 126 |
+
if (name === "biography")
|
| 127 |
+
return (
|
| 128 |
+
<svg {...common}>
|
| 129 |
+
<rect x="2.4" y="2.8" width="11.2" height="10.4" rx="1.6" />
|
| 130 |
+
<path d="M4.8 6h6.4M4.8 8.4h6.4M4.8 10.8h3.6" />
|
| 131 |
+
</svg>
|
| 132 |
+
);
|
| 133 |
+
if (name === "category_name" || name === "business_category_name")
|
| 134 |
+
return (
|
| 135 |
+
<svg {...common}>
|
| 136 |
+
<path d="M8.4 2.6H13v4.6l-6.2 6.2-4.6-4.6z" />
|
| 137 |
+
<circle cx="10.8" cy="5.2" r="0.9" />
|
| 138 |
+
</svg>
|
| 139 |
+
);
|
| 140 |
+
if (name === "is_business_account" || name === "is_professional_account")
|
| 141 |
+
return (
|
| 142 |
+
<svg {...common}>
|
| 143 |
+
<rect x="2.2" y="5" width="11.6" height="8.2" rx="1.6" />
|
| 144 |
+
<path d="M6 5V3.6a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1V5" />
|
| 145 |
+
</svg>
|
| 146 |
+
);
|
| 147 |
+
if (name === "is_verified")
|
| 148 |
+
return (
|
| 149 |
+
<svg {...common}>
|
| 150 |
+
<path d="M8 2.2l1.7 1.2 2-.2.6 2 1.7 1.1-.9 1.9.9 1.9-1.7 1.1-.6 2-2-.2L8 14.2l-1.7-1.2-2 .2-.6-2L2 10.1l.9-1.9L2 6.3l1.7-1.1.6-2 2 .2z" />
|
| 151 |
+
<path d="m5.8 8.1 1.5 1.5 3-3.1" />
|
| 152 |
+
</svg>
|
| 153 |
+
);
|
| 154 |
+
// The handle, and the display name it is written under.
|
| 155 |
+
if (name === "account" || name === "profile_name")
|
| 156 |
+
return (
|
| 157 |
+
<svg {...common}>
|
| 158 |
+
<circle cx="8" cy="8" r="2.4" />
|
| 159 |
+
<path d="M10.4 5.6v3.2a1.9 1.9 0 0 0 3.2 1.3A5.8 5.8 0 1 0 11 13.1" />
|
| 160 |
+
</svg>
|
| 161 |
+
);
|
| 162 |
+
if (name === "full_name")
|
| 163 |
+
return (
|
| 164 |
+
<svg {...common}>
|
| 165 |
+
<circle cx="8" cy="5.6" r="2.6" />
|
| 166 |
+
<path d="M3 13.4c.7-2.3 2.6-3.6 5-3.6s4.3 1.3 5 3.6" />
|
| 167 |
+
</svg>
|
| 168 |
+
);
|
| 169 |
+
if (name === "external_url" || name === "profile_url")
|
| 170 |
+
return (
|
| 171 |
+
<svg {...common}>
|
| 172 |
+
<path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
|
| 173 |
+
<path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
|
| 174 |
+
<path d="M6.2 8h3.6" />
|
| 175 |
+
</svg>
|
| 176 |
+
);
|
| 177 |
+
if (name === "bio_hashtags" || name === "post_hashtags")
|
| 178 |
+
return (
|
| 179 |
+
<svg {...common}>
|
| 180 |
+
<path d="M6.2 2.8 4.8 13.2M11.2 2.8 9.8 13.2M2.8 6h10.4M2.2 10h10.4" />
|
| 181 |
+
</svg>
|
| 182 |
+
);
|
| 183 |
+
if (name === "related_accounts")
|
| 184 |
+
return (
|
| 185 |
+
<svg {...common}>
|
| 186 |
+
<circle cx="8" cy="3.6" r="1.8" />
|
| 187 |
+
<circle cx="3.6" cy="12" r="1.8" />
|
| 188 |
+
<circle cx="12.4" cy="12" r="1.8" />
|
| 189 |
+
<path d="M6.8 5.2 4.6 10.4M9.2 5.2l2.2 5.2M5.4 12h5.2" />
|
| 190 |
+
</svg>
|
| 191 |
+
);
|
| 192 |
+
// The vendor's own record keys β the thing you hold to open exactly one row.
|
| 193 |
+
if (name === "id" || name === "fbid")
|
| 194 |
+
return (
|
| 195 |
+
<svg {...common}>
|
| 196 |
+
<circle cx="5.4" cy="10.6" r="2.6" />
|
| 197 |
+
<path d="M7.2 8.8 13 3M10.6 5.4l1.6 1.6M9.2 6.8l1.6 1.6" />
|
| 198 |
+
</svg>
|
| 199 |
+
);
|
| 200 |
+
return (
|
| 201 |
+
<svg {...common}>
|
| 202 |
+
<rect x="3.2" y="3.2" width="9.6" height="9.6" rx="2.2" />
|
| 203 |
+
<circle cx="8" cy="8" r="1.4" />
|
| 204 |
+
</svg>
|
| 205 |
+
);
|
| 206 |
+
}
|
| 207 |
+
|
| 208 |
+
/** One field's line in the list, with everything known about it. */
|
| 209 |
+
interface FieldRow {
|
| 210 |
+
name: string;
|
| 211 |
+
/** What the row is CALLED. Falls back to the raw name only if the server sent none. */
|
| 212 |
+
label: string;
|
| 213 |
+
hint: string;
|
| 214 |
+
kind: string;
|
| 215 |
+
operators: DiscoverOperator[];
|
| 216 |
+
options: { value: string; label: string }[];
|
| 217 |
+
/** Every stored condition naming this field, with its index in the saved array. */
|
| 218 |
+
at: number[];
|
| 219 |
+
/** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
|
| 220 |
+
populated: boolean | null;
|
| 221 |
+
/** A condition here cuts the corpus down. `null` = not said. */
|
| 222 |
+
narrowing: boolean | null;
|
| 223 |
+
}
|
| 224 |
+
|
| 225 |
+
/** A stored value β what the text box shows. A list is the "any of" shape. */
|
| 226 |
+
function valueText(v: Predicate["value"]): string {
|
| 227 |
+
if (Array.isArray(v)) return v.join(", ");
|
| 228 |
+
return v === undefined || v === null ? "" : String(v);
|
| 229 |
+
}
|
| 230 |
+
|
| 231 |
+
/**
|
| 232 |
+
* What the user typed β what is stored. Comma-separated becomes a LIST for the operators that
|
| 233 |
+
* accept one, and stays a plain string for the ones that do not.
|
| 234 |
+
*
|
| 235 |
+
* β A single value stays a SCALAR rather than a one-element list β the server sends scalars
|
| 236 |
+
* flat and lists as a nested OR group, and a one-element group is a shape nothing has been
|
| 237 |
+
* billed against.
|
| 238 |
+
*/
|
| 239 |
+
function parseValue(text: string, multi: boolean): Predicate["value"] {
|
| 240 |
+
if (!multi) return text;
|
| 241 |
+
const parts = text.split(",").map((s) => s.trim()).filter(Boolean);
|
| 242 |
+
if (parts.length > 1) return parts;
|
| 243 |
+
// Keep the RAW text while it is still being typed β trimming here would fight the cursor on
|
| 244 |
+
// every keystroke, and the server trims anyway.
|
| 245 |
+
return text;
|
| 246 |
+
}
|
| 247 |
+
|
| 248 |
+
/**
|
| 249 |
+
* β WAVE 26 Β· DEBT D-69 β A THIRD VALUE COULD NOT BE TYPED, and the cause was one round trip
|
| 250 |
+
* through this pair of functions.
|
| 251 |
+
*
|
| 252 |
+
* `parseValue` returns an ARRAY at 2+ values; `valueText` then renders that array as
|
| 253 |
+
* `join(", ")` β which has NO TRAILING COMMA. So on a controlled input the separator was
|
| 254 |
+
* normalised away between keystrokes: typing `,` onto `skincare, beauty` re-rendered as
|
| 255 |
+
* `skincare, beauty`, and the next character landed as `skincare, beautym`. Two keywords
|
| 256 |
+
* silently became one that matches nothing. β It hit the FIRST surface a new user meets (wave 24
|
| 257 |
+
* made this panel the only door) and it hit precisely the 3+ keyword list the feature was built
|
| 258 |
+
* for β the owner's *"if i want to include many keywords like floral, flower, beauty"*.
|
| 259 |
+
*
|
| 260 |
+
* β THE FIX IS THE ONE `parseValue`'s OWN COMMENT ALREADY DESCRIBES FOR THE 1-VALUE CASE:
|
| 261 |
+
* keep the raw text while it is being typed. That comment was right and its scope was too narrow
|
| 262 |
+
* β it protected the cursor at one value and handed the 2+ case to `join`. So the raw text is
|
| 263 |
+
* held for whichever input is FOCUSED, and the stored value is still parsed on every keystroke
|
| 264 |
+
* (so nothing depends on blur to save) and re-parsed on blur (so the display settles).
|
| 265 |
+
*
|
| 266 |
+
* β KEYED BY THE ROW'S REACT KEY, not by index alone: two conditions on the same field are
|
| 267 |
+
* ordinary here ("Another condition on Bio"), and an index-only key would leak one row's draft
|
| 268 |
+
* into its sibling on a removal.
|
| 269 |
+
*/
|
| 270 |
+
interface Draft {
|
| 271 |
+
key: string;
|
| 272 |
+
text: string;
|
| 273 |
+
}
|
| 274 |
+
|
| 275 |
+
/**
|
| 276 |
+
* The comparison a freshly toggled field starts with β ASKED FOR, never chosen here.
|
| 277 |
+
*
|
| 278 |
+
* β THE THIRD COSTUME OF ONE SCAR, and the reason this function no longer has an opinion.
|
| 279 |
+
* Wave 21 made a new condition NULLARY (`is_not_null`) so it would be saveable without a
|
| 280 |
+
* value, and called that "narrowing-in-the-right-direction". Wave 22 then wrote the narrowing
|
| 281 |
+
* law server-side and `is_not_null` is not in it. From that moment, toggling ANY field on and
|
| 282 |
+
* pressing Save returned "add at least one CONTENT conditionβ¦" β the error told the user to do
|
| 283 |
+
* the exact thing they had just done. Wave 24 deleted the wizard and made this panel the only
|
| 284 |
+
* door, so it stopped being a corner case and became the first thing a new user hits.
|
| 285 |
+
*
|
| 286 |
+
* The fix is not a better guess. It is that the module owning the guard also names the default
|
| 287 |
+
* (`automation_engine.default_operator`, asserted against `predicate_narrows` in
|
| 288 |
+
* `verify_automation.py`), and this file looks it up per FIELD. An absent one falls back to the
|
| 289 |
+
* server's first operator β never to a nullary, which is the thing that could not narrow.
|
| 290 |
+
*/
|
| 291 |
+
function firstOperator(v: DiscoverVocab | undefined, name: string): string {
|
| 292 |
+
const meta = (v?.filterMeta || []).find((m) => m.name === name);
|
| 293 |
+
return meta?.defaultOperator || (v?.operators || [])[0] || "";
|
| 294 |
+
}
|
| 295 |
+
|
| 296 |
+
/**
|
| 297 |
+
* The rows, ordered: measured-populated first, then the rest.
|
| 298 |
+
*
|
| 299 |
+
* TWO SOURCES, AND THE FALLBACK IS NARROWER THAN THE REAL THING. With C4's
|
| 300 |
+
* `filterMeta` the answer is per field and complete. Without it, `lead` names
|
| 301 |
+
* the three fields seen carrying values and says NOTHING about the other
|
| 302 |
+
* eighteen β so those come back `null`, not `false`, and the UI prints no claim
|
| 303 |
+
* about them rather than an invented one.
|
| 304 |
+
*/
|
| 305 |
+
function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
|
| 306 |
+
const meta = new Map<string, DiscoverFieldMeta>(
|
| 307 |
+
(v?.filterMeta || []).map((m) => [m.name, m])
|
| 308 |
+
);
|
| 309 |
+
const lead = new Set(v?.lead || []);
|
| 310 |
+
const byName = new Map<string, number[]>();
|
| 311 |
+
preds.forEach((p, i) => {
|
| 312 |
+
const list = byName.get(p.name);
|
| 313 |
+
if (list) list.push(i);
|
| 314 |
+
else byName.set(p.name, [i]);
|
| 315 |
+
});
|
| 316 |
+
|
| 317 |
+
const rows = (v?.fields || []).map((name) => {
|
| 318 |
+
const m = meta.get(name);
|
| 319 |
+
return {
|
| 320 |
+
name,
|
| 321 |
+
label: m?.label || name,
|
| 322 |
+
hint: m?.hint || "",
|
| 323 |
+
kind: m?.kind || "text",
|
| 324 |
+
// β NO FALLBACK TO THE GLOBAL OPERATOR LIST. An older server that sends no per-field list
|
| 325 |
+
// gets a row with no comparisons rather than all fourteen on every field β visibly
|
| 326 |
+
// unfinished beats quietly offering `at least` on a yes/no column.
|
| 327 |
+
operators: m?.operators || [],
|
| 328 |
+
options: m?.options || [],
|
| 329 |
+
at: byName.get(name) || [],
|
| 330 |
+
populated: m ? !!m.populated : lead.has(name) ? true : null,
|
| 331 |
+
narrowing: m ? !!m.narrowing : null,
|
| 332 |
+
};
|
| 333 |
+
});
|
| 334 |
+
// Stable partition, never a sort: the server's order inside each half is the
|
| 335 |
+
// order the engine lists them in, and re-alphabetising it would be this file
|
| 336 |
+
// having an opinion about a server list.
|
| 337 |
+
return [...rows.filter((r) => r.populated === true), ...rows.filter((r) => r.populated !== true)];
|
| 338 |
+
}
|
| 339 |
+
|
| 340 |
+
export default function AutomationFind({
|
| 341 |
+
discover,
|
| 342 |
+
recordsLimit,
|
| 343 |
+
onRecordsLimit,
|
| 344 |
+
joinOp,
|
| 345 |
+
onJoinOp,
|
| 346 |
+
preds,
|
| 347 |
+
onPreds,
|
| 348 |
+
estimate,
|
| 349 |
+
onEstimate,
|
| 350 |
+
}: Props) {
|
| 351 |
+
const rows = buildRows(preds, discover);
|
| 352 |
+
const known = new Set(discover?.fields || []);
|
| 353 |
+
// The GLOBAL operator list is gone from this component: comparisons are per field now
|
| 354 |
+
// (`row.operators`). `nullary` survives for STRAYS only β a stored condition on a field the
|
| 355 |
+
// vendor dropped has no per-field row to read from, and it still has to render to be removable.
|
| 356 |
+
const nullary = new Set(discover?.nullaryOperators || []);
|
| 357 |
+
const withValues = rows.filter((r) => r.populated === true);
|
| 358 |
+
const rest = rows.filter((r) => r.populated !== true);
|
| 359 |
+
const knownMeta = !!(discover?.filterMeta || []).length;
|
| 360 |
+
// β THE STORED FILTER CAN NAME A FIELD THE LIST NO LONGER HAS β a vocabulary
|
| 361 |
+
// that moved, an automation copied from elsewhere. It must stay VISIBLE and
|
| 362 |
+
// REMOVABLE: a condition the user cannot see is one they cannot delete, and
|
| 363 |
+
// every Save keeps sending it. Same defect as a `<select>` whose value matches
|
| 364 |
+
// no option, one level up.
|
| 365 |
+
const strays = preds
|
| 366 |
+
.map((p, i) => ({ p, i }))
|
| 367 |
+
.filter(({ p }) => !known.has(p.name));
|
| 368 |
+
|
| 369 |
+
const maxRecords = discover?.guard?.maxRecords || discover?.maxRecords || 500;
|
| 370 |
+
|
| 371 |
+
/** D-69 β the raw text of the input a person is typing in right now (see `Draft`). */
|
| 372 |
+
const [draft, setDraft] = useState<Draft | null>(null);
|
| 373 |
+
|
| 374 |
+
/**
|
| 375 |
+
* β WAVE 27 Β· OWNER ITEM 29 β which condition's value is open in the BIG editor, if any.
|
| 376 |
+
*
|
| 377 |
+
* β THE TEXT IS HELD HERE, NOT WRITTEN THROUGH ON EVERY KEYSTROKE, and that is the one place
|
| 378 |
+
* this differs from the rail input beside it. The rail input writes per keystroke on purpose
|
| 379 |
+
* (a Save pressed straight from the field must not store the previous value β D-69's note).
|
| 380 |
+
* A modal has its own Save, so per-keystroke writes would buy nothing and would make Cancel
|
| 381 |
+
* a lie: the value would already be in the config by the time it was pressed.
|
| 382 |
+
* β The ANCHOR is captured at click time and stored, because the button it came from is
|
| 383 |
+
* inside a panel that scrolls β re-reading it later would place the overlay against a rect
|
| 384 |
+
* that has moved.
|
| 385 |
+
*/
|
| 386 |
+
const [big, setBig] = useState<{
|
| 387 |
+
key: string;
|
| 388 |
+
index: number;
|
| 389 |
+
label: string;
|
| 390 |
+
multi: boolean;
|
| 391 |
+
text: string;
|
| 392 |
+
anchor: AnchorRect;
|
| 393 |
+
} | null>(null);
|
| 394 |
+
|
| 395 |
+
/**
|
| 396 |
+
* β ITEM 16 / D-71 β THE OBSERVED CATEGORY VALUES, fetched WHEN THIS PANEL OPENS.
|
| 397 |
+
*
|
| 398 |
+
* β ON MOUNT, ONCE, AND NEVER ON THE POLLED PAYLOAD. This component is rendered only while the
|
| 399 |
+
* Find panel is open, so mounting IS the panel opening β and the server moved these off
|
| 400 |
+
* `GET /automations` after measuring that deriving them reads two user tables plus the platform
|
| 401 |
+
* master, i.e. a network round-trip per open tab every 2.5 s. Putting the request here is the
|
| 402 |
+
* client half of that same decision, not an optimisation.
|
| 403 |
+
*
|
| 404 |
+
* β AN EMPTY LIST IS AN ANSWER AND IS RENDERED AS ONE. It means this deployment has not seen a
|
| 405 |
+
* category value yet β which is TRUE for a fresh tenant β and the field keeps its free-text
|
| 406 |
+
* input either way. It must never read as "loading forever", and it must never be filled in
|
| 407 |
+
* with a guess: D-59 is explicit that an invented taxonomy is worse than no dropdown.
|
| 408 |
+
*/
|
| 409 |
+
const [cats, setCats] = useState<{ value: string; count: number }[]>([]);
|
| 410 |
+
useEffect(() => {
|
| 411 |
+
const ac = new AbortController();
|
| 412 |
+
discoverCategories(ac.signal)
|
| 413 |
+
.then((r) => setCats(Array.isArray(r?.options) ? r.options : []))
|
| 414 |
+
// Fail-quiet, on purpose: the picker is an ASSIST over a control that works without it.
|
| 415 |
+
// An error banner here would report a broken panel when the only thing missing is a
|
| 416 |
+
// convenience β and the free-text input beside it is unaffected.
|
| 417 |
+
.catch(() => setCats([]));
|
| 418 |
+
return () => ac.abort();
|
| 419 |
+
}, []);
|
| 420 |
+
|
| 421 |
+
const setAt = (i: number, patch: Partial<Predicate>) =>
|
| 422 |
+
onPreds(preds.map((p, j) => (j === i ? { ...p, ...patch } : p)));
|
| 423 |
+
|
| 424 |
+
const removeAt = (i: number) => onPreds(preds.filter((_p, j) => j !== i));
|
| 425 |
+
|
| 426 |
+
const toggleField = (row: FieldRow) => {
|
| 427 |
+
if (row.at.length) {
|
| 428 |
+
onPreds(preds.filter((p) => p.name !== row.name));
|
| 429 |
+
return;
|
| 430 |
+
}
|
| 431 |
+
onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }]);
|
| 432 |
+
};
|
| 433 |
+
|
| 434 |
+
/** One condition line β the comparison, its value, and a way out. */
|
| 435 |
+
const condition = (i: number, label: string, row?: FieldRow) => {
|
| 436 |
+
const p = preds[i];
|
| 437 |
+
if (!p) return null;
|
| 438 |
+
// The field's OWN comparisons. `row` is absent only for a stray (a stored condition on a
|
| 439 |
+
// field the vendor no longer offers), which keeps the raw token so it stays removable.
|
| 440 |
+
const ops = row?.operators || [];
|
| 441 |
+
const cur = ops.find((o) => o.value === p.operator);
|
| 442 |
+
const isNullary = cur ? cur.nullary : nullary.has(p.operator);
|
| 443 |
+
const isMulti = !!cur?.multi;
|
| 444 |
+
const options = row?.options || [];
|
| 445 |
+
const rowKey = `${p.name}-${i}`;
|
| 446 |
+
// D-69: the focused input shows what was TYPED; every other one shows the stored value.
|
| 447 |
+
const shown = draft && draft.key === rowKey ? draft.text : valueText(p.value);
|
| 448 |
+
/*
|
| 449 |
+
* β ITEM 16 / D-71 β WHICH FIELDS GET THE OBSERVED-VALUES PICKER, DERIVED OFF THE WIRE.
|
| 450 |
+
*
|
| 451 |
+
* β NOT A CLIENT-SIDE LIST OF FIELD NAMES. Naming the vendor's two category columns here
|
| 452 |
+
* would be the D-55 class verbatim β the wave-9 silent-drop shape, a client copy of a server
|
| 453 |
+
* vocabulary that is free to drift the day the engine adds a third one. (Their literal keys
|
| 454 |
+
* are deliberately not written anywhere in this file: the gate asserts the tokens are ABSENT,
|
| 455 |
+
* and an absence check cannot tell a hard-coded list from the comment forbidding one.)
|
| 456 |
+
* The server already publishes the answer twice over: `kind: "choice"` is its own declaration
|
| 457 |
+
* (`BD_FIELD_KINDS`), and `filter_meta` deliberately ships `options: []` for those fields
|
| 458 |
+
* because their vocabulary is OBSERVED rather than declared and arrives on its own route.
|
| 459 |
+
* So the rule is exactly that: a choice-kind field with no declared options is one whose
|
| 460 |
+
* values we can only have learned by seeing them. A new choice field inherits this for free.
|
| 461 |
+
*/
|
| 462 |
+
const wantsObserved = row?.kind === "choice" && !options.length;
|
| 463 |
+
/** D-71 β APPEND, never replace: the picker has to compose with the comma list. */
|
| 464 |
+
const appendValue = (v: string) => {
|
| 465 |
+
const has = shown
|
| 466 |
+
.split(",")
|
| 467 |
+
.map((s) => s.trim().toLowerCase())
|
| 468 |
+
.filter(Boolean);
|
| 469 |
+
// Picking the same value twice is a no-op rather than a duplicate: the server expands a
|
| 470 |
+
// multi-value condition into an OR, and `beauty OR beauty` costs a slot to say nothing.
|
| 471 |
+
if (has.includes(v.trim().toLowerCase())) return;
|
| 472 |
+
const next = shown.trim() ? `${shown.replace(/[\s,]+$/, "")}, ${v}` : v;
|
| 473 |
+
setDraft(null);
|
| 474 |
+
setAt(i, { value: parseValue(next, isMulti) });
|
| 475 |
+
};
|
| 476 |
+
return (
|
| 477 |
+
<div className="autob-cond" key={rowKey}>
|
| 478 |
+
<select
|
| 479 |
+
className="auto-input is-small"
|
| 480 |
+
aria-label={`Comparison for ${label}`}
|
| 481 |
+
value={p.operator}
|
| 482 |
+
onChange={(e) => setAt(i, { operator: e.target.value })}
|
| 483 |
+
>
|
| 484 |
+
{/* The stored value is ALWAYS an option. A select whose value matches no
|
| 485 |
+
option renders the FIRST one, and the next Save writes a comparison
|
| 486 |
+
nobody chose β this codebase has paid for that twice. */}
|
| 487 |
+
{p.operator && !ops.some((o) => o.value === p.operator) ? (
|
| 488 |
+
<option value={p.operator}>{p.operator}</option>
|
| 489 |
+
) : null}
|
| 490 |
+
{ops.map((o) => (
|
| 491 |
+
<option key={o.value} value={o.value}>
|
| 492 |
+
{o.label}
|
| 493 |
+
</option>
|
| 494 |
+
))}
|
| 495 |
+
</select>
|
| 496 |
+
{isNullary ? null : options.length ? (
|
| 497 |
+
// A fixed vocabulary gets a dropdown. Owner item 2: a yes/no column was a box you
|
| 498 |
+
// typed `true` into, beside a comparison list that offered "at least".
|
| 499 |
+
<select
|
| 500 |
+
className="auto-input is-small"
|
| 501 |
+
aria-label={`Value for ${label}`}
|
| 502 |
+
value={valueText(p.value)}
|
| 503 |
+
onChange={(e) => setAt(i, { value: e.target.value })}
|
| 504 |
+
>
|
| 505 |
+
<option value="">Chooseβ¦</option>
|
| 506 |
+
{options.map((o) => (
|
| 507 |
+
<option key={o.value} value={o.value}>
|
| 508 |
+
{o.label}
|
| 509 |
+
</option>
|
| 510 |
+
))}
|
| 511 |
+
</select>
|
| 512 |
+
) : (
|
| 513 |
+
<input
|
| 514 |
+
className="auto-input is-small"
|
| 515 |
+
type={row?.kind === "number" ? "number" : "text"}
|
| 516 |
+
aria-label={`Value for ${label}`}
|
| 517 |
+
// β OWNER ITEM 3. Several comma-separated values become an "any of" condition, which
|
| 518 |
+
// the server sends as its own OR group β so it does NOT drag Followers into a union
|
| 519 |
+
// the way the Match dropdown would.
|
| 520 |
+
placeholder={isMulti ? "floral, flower, beauty" : ""}
|
| 521 |
+
// D-69: `shown` is the RAW text while this input has focus, so a trailing comma
|
| 522 |
+
// survives long enough to type the next value after it.
|
| 523 |
+
value={shown}
|
| 524 |
+
onFocus={() => setDraft({ key: rowKey, text: valueText(p.value) })}
|
| 525 |
+
onChange={(e) => {
|
| 526 |
+
setDraft({ key: rowKey, text: e.target.value });
|
| 527 |
+
// The STORE still updates on every keystroke. Parsing only on blur would mean a
|
| 528 |
+
// Save pressed straight from the field wrote the previous value β trading a typing
|
| 529 |
+
// bug for a data-loss one.
|
| 530 |
+
setAt(i, { value: parseValue(e.target.value, isMulti) });
|
| 531 |
+
}}
|
| 532 |
+
onBlur={(e) => {
|
| 533 |
+
setDraft(null);
|
| 534 |
+
setAt(i, { value: parseValue(e.target.value, isMulti) });
|
| 535 |
+
}}
|
| 536 |
+
/>
|
| 537 |
+
)}
|
| 538 |
+
{/* β WAVE 27 Β· OWNER ITEM 29 β A WIDE EDITOR FOR THE VALUES THAT DO NOT FIT.
|
| 539 |
+
β THE COMPLAINT IS GEOMETRY, and the geometry is a CHAIN nothing here can widen:
|
| 540 |
+
`.auto-panel` is 380px, `.autob-cond .auto-input` divides what is left across three
|
| 541 |
+
controls, and `.is-small` trims it again β so a bio phrase list ("floral, flower,
|
| 542 |
+
wedding florist, event styling") is typed six characters at a time through a box
|
| 543 |
+
that scrolls sideways. The panel cannot grow; the EDITOR can leave it, and an
|
| 544 |
+
overlay is drawn in a body portal, so it is not bound by that chain at all.
|
| 545 |
+
β ALWAYS OFFERED, never "appears once the text is long": a control that materialises
|
| 546 |
+
at some threshold is one people do not know exists at the moment they need it.
|
| 547 |
+
β NOT on a `<select>` value (a fixed vocabulary has nothing to expand) and not on a
|
| 548 |
+
nullary comparison (which has no value at all). */}
|
| 549 |
+
{!isNullary && !options.length ? (
|
| 550 |
+
<button
|
| 551 |
+
type="button"
|
| 552 |
+
className="auto-input is-small autoc-expand"
|
| 553 |
+
aria-label={`Open a bigger editor for ${label}`}
|
| 554 |
+
title="Edit in a bigger box"
|
| 555 |
+
onClick={(e) => {
|
| 556 |
+
// β READ SYNCHRONOUSLY from the event. `currentTarget` is null by the time React
|
| 557 |
+
// re-invokes a state updater, and a null rect here paints the overlay at 0,0 β
|
| 558 |
+
// measured, in this repo, on a different control ([[react-event-currenttarget-updater]]).
|
| 559 |
+
const r = e.currentTarget.getBoundingClientRect();
|
| 560 |
+
setBig({
|
| 561 |
+
key: rowKey,
|
| 562 |
+
index: i,
|
| 563 |
+
label,
|
| 564 |
+
multi: isMulti,
|
| 565 |
+
text: valueText(p.value),
|
| 566 |
+
anchor: { left: r.left, top: r.top, right: r.right, bottom: r.bottom,
|
| 567 |
+
width: r.width, height: r.height },
|
| 568 |
+
});
|
| 569 |
+
}}
|
| 570 |
+
>
|
| 571 |
+
{/* Drawn, never a glyph: the design constitution's "no emojis in the UI" covers
|
| 572 |
+
the arrow characters too, and every other mark in this product is a path in the
|
| 573 |
+
same 16x16 stroke vocabulary. Two corners pulling apart = "make this bigger". */}
|
| 574 |
+
<svg viewBox="0 0 16 16" aria-hidden className="autoc-expand-icon">
|
| 575 |
+
<path d="M9.5 2.5h4v4M13.5 2.5 9.6 6.4" />
|
| 576 |
+
<path d="M6.5 13.5h-4v-4M2.5 13.5l3.9-3.9" />
|
| 577 |
+
</svg>
|
| 578 |
+
</button>
|
| 579 |
+
) : null}
|
| 580 |
+
{/* β ITEM 16 / D-71 β THE APPEND-PICKER, BESIDE the input and never instead of it.
|
| 581 |
+
Free text stays the primary control: these are the values this deployment has SEEN,
|
| 582 |
+
not the values that exist, so the picker is a shortcut over a superset it cannot
|
| 583 |
+
enumerate. Appending in code also sidesteps D-69 entirely β a picked value never has
|
| 584 |
+
to survive a round trip through the text box. */}
|
| 585 |
+
{wantsObserved && !isNullary ? (
|
| 586 |
+
<select
|
| 587 |
+
className="auto-input is-small autoc-catpick"
|
| 588 |
+
aria-label={`Add a value seen before, to ${label}`}
|
| 589 |
+
title={
|
| 590 |
+
cats.length
|
| 591 |
+
? "Values this workspace has actually seen, most-seen first. Adds to the list."
|
| 592 |
+
: "No category values have been seen in your data yet. Type one."
|
| 593 |
+
}
|
| 594 |
+
value=""
|
| 595 |
+
disabled={!cats.length}
|
| 596 |
+
onChange={(e) => {
|
| 597 |
+
if (e.target.value) appendValue(e.target.value);
|
| 598 |
+
}}
|
| 599 |
+
>
|
| 600 |
+
<option value="">{cats.length ? "Seen beforeβ¦" : "None seen yet"}</option>
|
| 601 |
+
{cats.map((c) => (
|
| 602 |
+
// The COUNT is the honest half (D-59): a value seen once and one seen forty times
|
| 603 |
+
// are different bets, and an alphabetical list of bare strings hides that.
|
| 604 |
+
<option key={c.value} value={c.value}>
|
| 605 |
+
{c.value} ({c.count.toLocaleString()})
|
| 606 |
+
</option>
|
| 607 |
+
))}
|
| 608 |
+
</select>
|
| 609 |
+
) : null}
|
| 610 |
+
{isMulti && Array.isArray(p.value) && p.value.length > 1 ? (
|
| 611 |
+
/*
|
| 612 |
+
* β ITEM 16 / D-71 β HOW MANY VALUES THIS CONDITION CARRIES, and against what ceiling.
|
| 613 |
+
*
|
| 614 |
+
* The COUNT is ours and is always shown. The CEILING is the server's and is shown only
|
| 615 |
+
* when the server sends one (`guard.maxValues` β an open `ASK ->A:`; `guard` ships
|
| 616 |
+
* `{minNarrowing, maxRecords}` today).
|
| 617 |
+
* β NO CLIENT-SIDE `4`. D-71's exit says "how many of D-68's 4 value slots" β but A
|
| 618 |
+
* shipped `depth_refusal()`, which computes the depth of the shape actually emitted
|
| 619 |
+
* rather than budgeting fixed slots, so the number 4 describes a model that no longer
|
| 620 |
+
* exists. Printing it would be a client copy of a server rule that has already changed
|
| 621 |
+
* once, which is the specific failure this file's header refuses to commit
|
| 622 |
+
* ([[measure-the-real-call]]: a correct-looking answer about the wrong subject).
|
| 623 |
+
*/
|
| 624 |
+
<span className="autob-cond-any" title="Any one of these is a match">
|
| 625 |
+
any of {p.value.length}
|
| 626 |
+
{discover?.guard?.maxValues ? ` of ${discover.guard.maxValues}` : ""}
|
| 627 |
+
</span>
|
| 628 |
+
) : null}
|
| 629 |
+
<button
|
| 630 |
+
type="button"
|
| 631 |
+
className="autob-cond-x"
|
| 632 |
+
aria-label={`Remove this condition on ${label}`}
|
| 633 |
+
title="Remove this condition"
|
| 634 |
+
onClick={() => removeAt(i)}
|
| 635 |
+
>
|
| 636 |
+
<svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
|
| 637 |
+
<path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
|
| 638 |
+
</svg>
|
| 639 |
+
</button>
|
| 640 |
+
</div>
|
| 641 |
+
);
|
| 642 |
+
};
|
| 643 |
+
|
| 644 |
+
const fieldRow = (row: FieldRow) => {
|
| 645 |
+
const on = row.at.length > 0;
|
| 646 |
+
return (
|
| 647 |
+
<div className={"autob-tgl" + (on ? " is-on" : "")} key={row.name}>
|
| 648 |
+
<div className="autob-tgl-head">
|
| 649 |
+
<button
|
| 650 |
+
type="button"
|
| 651 |
+
className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
|
| 652 |
+
aria-pressed={on}
|
| 653 |
+
aria-label={`${on ? "Stop searching" : "Search"} on ${row.label}`}
|
| 654 |
+
title={`${on ? "Stop searching" : "Search"} on ${row.label}`}
|
| 655 |
+
onClick={() => toggleField(row)}
|
| 656 |
+
>
|
| 657 |
+
<span className="auto-step-switch-knob" />
|
| 658 |
+
</button>
|
| 659 |
+
<span className="autob-tgl-mark">
|
| 660 |
+
<FilterMark name={row.name} />
|
| 661 |
+
</span>
|
| 662 |
+
{/* β THE HUMAN LABEL (owner item 1: "wtf is id/fbid").
|
| 663 |
+
This used to render the vendor's own column name verbatim, and the comment
|
| 664 |
+
defending it was RIGHT about the reason β a refusal names the field, and a label
|
| 665 |
+
that reads differently makes the error unmatchable. So the label did not move
|
| 666 |
+
alone: `field_label()` is what the SERVER's refusals use too, which is the only
|
| 667 |
+
version of this change that does not trade one confusion for another. */}
|
| 668 |
+
<span className="autob-tgl-name" title={row.hint || undefined}>
|
| 669 |
+
{row.label}
|
| 670 |
+
</span>
|
| 671 |
+
{/*
|
| 672 |
+
β ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
|
| 673 |
+
non-narrowing field "broad" AND every unpopulated one "no values seen" β
|
| 674 |
+
which put two chips on 18 of the 21 rows, and one of them repeated the group
|
| 675 |
+
heading the row was already sitting under. A mark that is on almost every row
|
| 676 |
+
stops being a mark. Read off the screenshot; no assertion could have said it.
|
| 677 |
+
|
| 678 |
+
So: the group label carries POPULATED (it is what the groups ARE), and the
|
| 679 |
+
chip carries NARROWING, inverted to mark the five that DO narrow. That is the
|
| 680 |
+
actionable half β the server refuses a filter with no narrowing condition, so
|
| 681 |
+
"these are the ones that satisfy it" is the sentence a user needs, and
|
| 682 |
+
"this one does not" is not.
|
| 683 |
+
*/}
|
| 684 |
+
{row.narrowing === true ? (
|
| 685 |
+
<span
|
| 686 |
+
className="autob-tgl-flag is-narrow"
|
| 687 |
+
title="A search needs at least one condition like this."
|
| 688 |
+
>
|
| 689 |
+
narrows
|
| 690 |
+
</span>
|
| 691 |
+
) : null}
|
| 692 |
+
</div>
|
| 693 |
+
{on ? (
|
| 694 |
+
<div className="autob-tgl-body">
|
| 695 |
+
{row.at.map((i) => condition(i, row.label, row))}
|
| 696 |
+
{row.hint ? <p className="autob-tgl-hint">{row.hint}</p> : null}
|
| 697 |
+
<button
|
| 698 |
+
type="button"
|
| 699 |
+
className="autob-cond-add"
|
| 700 |
+
onClick={() =>
|
| 701 |
+
onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
|
| 702 |
+
}
|
| 703 |
+
>
|
| 704 |
+
Another condition on {row.label}
|
| 705 |
+
</button>
|
| 706 |
+
</div>
|
| 707 |
+
) : null}
|
| 708 |
+
</div>
|
| 709 |
+
);
|
| 710 |
+
};
|
| 711 |
+
|
| 712 |
+
return (
|
| 713 |
+
<>
|
| 714 |
+
<div className="auto-field">
|
| 715 |
+
<label htmlFor="auto-records">How many profiles to fetch</label>
|
| 716 |
+
<input
|
| 717 |
+
id="auto-records"
|
| 718 |
+
className="auto-input"
|
| 719 |
+
type="number"
|
| 720 |
+
min={1}
|
| 721 |
+
max={maxRecords}
|
| 722 |
+
value={recordsLimit}
|
| 723 |
+
onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
|
| 724 |
+
/>
|
| 725 |
+
</div>
|
| 726 |
+
{/* Owner item 5: "Stop at the 'A search must be at most 500 profiles a run'". The two
|
| 727 |
+
sentences that followed explained the vendor's billing model to somebody who wants a
|
| 728 |
+
list of florists. */}
|
| 729 |
+
<p className="auto-hint">At most {maxRecords.toLocaleString()} profiles a run.</p>
|
| 730 |
+
|
| 731 |
+
<h3>Conditions</h3>
|
| 732 |
+
<div className="auto-field autob-match">
|
| 733 |
+
<label htmlFor="auto-joinop">Match</label>
|
| 734 |
+
<select
|
| 735 |
+
id="auto-joinop"
|
| 736 |
+
className="auto-input"
|
| 737 |
+
value={joinOp}
|
| 738 |
+
onChange={(e) => onJoinOp(e.target.value)}
|
| 739 |
+
>
|
| 740 |
+
<option value="and">All of them</option>
|
| 741 |
+
<option value="or">Any of them</option>
|
| 742 |
+
</select>
|
| 743 |
+
</div>
|
| 744 |
+
|
| 745 |
+
{!rows.length ? (
|
| 746 |
+
<p className="auto-note">
|
| 747 |
+
The searchable fields have not loaded yet.
|
| 748 |
+
</p>
|
| 749 |
+
) : null}
|
| 750 |
+
|
| 751 |
+
{withValues.length ? (
|
| 752 |
+
<div className="autob-tglgroup">
|
| 753 |
+
<p
|
| 754 |
+
className="autob-tglgroup-label"
|
| 755 |
+
title="Most accounts have this filled in."
|
| 756 |
+
>
|
| 757 |
+
Usually filled in
|
| 758 |
+
</p>
|
| 759 |
+
{withValues.map(fieldRow)}
|
| 760 |
+
</div>
|
| 761 |
+
) : null}
|
| 762 |
+
|
| 763 |
+
{rest.length ? (
|
| 764 |
+
<div className="autob-tglgroup">
|
| 765 |
+
<p
|
| 766 |
+
className="autob-tglgroup-label"
|
| 767 |
+
title={
|
| 768 |
+
knownMeta
|
| 769 |
+
? "Most accounts leave these blank, so a condition here can return nothing."
|
| 770 |
+
: "We have not measured how often these are filled in."
|
| 771 |
+
}
|
| 772 |
+
>
|
| 773 |
+
{knownMeta ? "Often blank" : "Not measured"}
|
| 774 |
+
</p>
|
| 775 |
+
{rest.map(fieldRow)}
|
| 776 |
+
</div>
|
| 777 |
+
) : null}
|
| 778 |
+
|
| 779 |
+
{strays.length ? (
|
| 780 |
+
<div className="autob-tglgroup">
|
| 781 |
+
<p className="autob-tglgroup-label">Not in the searchable list</p>
|
| 782 |
+
{strays.map(({ p, i }) => (
|
| 783 |
+
<div className="autob-tgl is-on is-stray" key={`stray-${i}`}>
|
| 784 |
+
<div className="autob-tgl-head">
|
| 785 |
+
{/* A stray gets a mark too β "every filter row" includes the ones the vendor no
|
| 786 |
+
longer offers, and a row missing the icon its neighbours have would read as a
|
| 787 |
+
different KIND of thing rather than as a field that fell out of the list. It
|
| 788 |
+
draws the neutral fallback by construction: a stray is, by definition, not in
|
| 789 |
+
the vocabulary this component has arms for. */}
|
| 790 |
+
<span className="autob-tgl-mark">
|
| 791 |
+
<FilterMark name={p.name} />
|
| 792 |
+
</span>
|
| 793 |
+
<span className="autob-tgl-name">{p.name}</span>
|
| 794 |
+
<span className="autob-tgl-flag is-stray" title="The server will refuse this condition by name.">
|
| 795 |
+
not searchable
|
| 796 |
+
</span>
|
| 797 |
+
</div>
|
| 798 |
+
<div className="autob-tgl-body">{condition(i, p.name)}</div>
|
| 799 |
+
</div>
|
| 800 |
+
))}
|
| 801 |
+
</div>
|
| 802 |
+
) : null}
|
| 803 |
+
|
| 804 |
+
{/* The consequence kept, the mechanism dropped: a condition on an often-blank field
|
| 805 |
+
returning nothing is a thing that will happen to somebody and confuse them. Why the
|
| 806 |
+
search is slow when broad is our problem, not theirs. */}
|
| 807 |
+
<p className="auto-hint">
|
| 808 |
+
Conditions on often-blank fields can come back with nothing.
|
| 809 |
+
</p>
|
| 810 |
+
|
| 811 |
+
<h3>What it costs</h3>
|
| 812 |
+
<div className="auto-head-actions">
|
| 813 |
+
<button type="button" className="auto-btn" onClick={onEstimate}>
|
| 814 |
+
Estimate this search
|
| 815 |
+
</button>
|
| 816 |
+
</div>
|
| 817 |
+
{estimate ? (
|
| 818 |
+
<p className="auto-hint">
|
| 819 |
+
About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
|
| 820 |
+
{estimate.unitUsd} each.{" "}
|
| 821 |
+
{/*
|
| 822 |
+
THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run and this
|
| 823 |
+
deployment cannot read its own balance, so presenting this as a billed figure
|
| 824 |
+
would be inventing a measurement.
|
| 825 |
+
*/}
|
| 826 |
+
<strong>This is an estimate</strong> β {estimate.note}.
|
| 827 |
+
</p>
|
| 828 |
+
) : null}
|
| 829 |
+
|
| 830 |
+
{/* β WAVE 27 Β· OWNER ITEM 29 β THE BIG EDITOR, rendered ONCE for the whole panel.
|
| 831 |
+
β Not one overlay per condition row: `AnchoredOverlay` mounts a body portal and
|
| 832 |
+
installs document-level dismiss/focus handlers, so N of them would be N listener
|
| 833 |
+
stacks fighting over one Escape key. One overlay, told which row it is editing.
|
| 834 |
+
β `role="dialog"`, not "menu": it holds a text field, and the menu layer's arrow-key
|
| 835 |
+
handling would take the cursor keys away from the text being typed. */}
|
| 836 |
+
{big ? (
|
| 837 |
+
<AnchoredOverlay
|
| 838 |
+
anchor={big.anchor}
|
| 839 |
+
className="autoc-bigedit"
|
| 840 |
+
placement="right-start"
|
| 841 |
+
role="dialog"
|
| 842 |
+
ariaLabel={`Value for ${big.label}`}
|
| 843 |
+
onDismiss={() => setBig(null)}
|
| 844 |
+
dataKind="find-value-editor"
|
| 845 |
+
>
|
| 846 |
+
<label htmlFor="autoc-bigedit-text">{big.label}</label>
|
| 847 |
+
<textarea
|
| 848 |
+
id="autoc-bigedit-text"
|
| 849 |
+
className="autoc-bigedit-text"
|
| 850 |
+
data-overlay-autofocus
|
| 851 |
+
autoFocus
|
| 852 |
+
rows={7}
|
| 853 |
+
spellCheck={false}
|
| 854 |
+
value={big.text}
|
| 855 |
+
placeholder={big.multi ? "floral, flower, wedding florist, event styling" : ""}
|
| 856 |
+
onChange={(e) => setBig((cur) => (cur ? { ...cur, text: e.target.value } : cur))}
|
| 857 |
+
onKeyDown={(e) => {
|
| 858 |
+
// Escape abandons; Ctrl/Cmd+Enter commits. A bare Enter types a NEWLINE, because
|
| 859 |
+
// this is a textarea and the whole reason it exists is that the value is long.
|
| 860 |
+
if (e.key === "Escape") setBig(null);
|
| 861 |
+
if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
|
| 862 |
+
setAt(big.index, { value: parseValue(big.text, big.multi) });
|
| 863 |
+
setBig(null);
|
| 864 |
+
}
|
| 865 |
+
}}
|
| 866 |
+
/>
|
| 867 |
+
{/* The same sentence the rail input's placeholder makes, said where there is room
|
| 868 |
+
for it: a comma list is several values, and the server turns them into an OR. */}
|
| 869 |
+
{big.multi ? (
|
| 870 |
+
<p className="auto-hint">
|
| 871 |
+
Separate values with commas. The search matches any of them.
|
| 872 |
+
</p>
|
| 873 |
+
) : null}
|
| 874 |
+
<div className="auto-head-actions">
|
| 875 |
+
<button
|
| 876 |
+
type="button"
|
| 877 |
+
className="auto-btn auto-btn--primary"
|
| 878 |
+
onClick={() => {
|
| 879 |
+
setAt(big.index, { value: parseValue(big.text, big.multi) });
|
| 880 |
+
setBig(null);
|
| 881 |
+
}}
|
| 882 |
+
>
|
| 883 |
+
Done
|
| 884 |
+
</button>
|
| 885 |
+
<button type="button" className="auto-btn" onClick={() => setBig(null)}>
|
| 886 |
+
Cancel
|
| 887 |
+
</button>
|
| 888 |
+
</div>
|
| 889 |
+
</AnchoredOverlay>
|
| 890 |
+
) : null}
|
| 891 |
+
</>
|
| 892 |
+
);
|
| 893 |
+
}
|
web/src/automation/HarnessPanel.tsx
CHANGED
|
@@ -1,413 +1,413 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// automation/HarnessPanel.tsx β the HARNESS tab (owner item 3, rulings R7/R8,
|
| 3 |
-
// contract C4 Β· W36-T31).
|
| 4 |
-
//
|
| 5 |
-
// Owner, verbatim (2026-08-18): *"For each of the tenant's Agent, I think we need
|
| 6 |
-
// another tab beside Properties/Run history. This new module under agent is
|
| 7 |
-
// supposed to host any file pertaining to the agent skills, router etc. So we
|
| 8 |
-
// build a user can build a custom harness for each agent through the chat
|
| 9 |
-
// interface."*
|
| 10 |
-
//
|
| 11 |
-
// ββ R8 IS THE WHOLE SHAPE AND IT IS ENFORCED ON THE SERVER, NOT HERE. Every save
|
| 12 |
-
// APPENDS a version; there is no overwrite door and no edit-in-place. A ROLL-BACK
|
| 13 |
-
// IS A WRITE OF AN OLDER BODY, never a delete β so "restore v1" produces v4 whose
|
| 14 |
-
// `restoredFrom` is 1, and the history keeps v2 and v3 saying what actually
|
| 15 |
-
// happened rather than what somebody last wanted it to look like. This panel
|
| 16 |
-
// paints that model; it does not implement it, and it must never offer a control
|
| 17 |
-
// whose name implies otherwise ("Replace", "Overwrite", "Discard v2").
|
| 18 |
-
//
|
| 19 |
-
// β R8 IS DELIBERATELY NOT R9, and the two sit one screen apart. An agent-authored
|
| 20 |
-
// ACTION's config is agent-only (item 8); a harness file is editable by BOTH the
|
| 21 |
-
// user and the agent. Do not copy either posture onto the other.
|
| 22 |
-
//
|
| 23 |
-
// β THIS PANEL IS THE ONE PLACE THE CAPS ARE VISIBLE. `limits` rides every C4
|
| 24 |
-
// payload precisely so a control can say "this file is full" BEFORE a write fails,
|
| 25 |
-
// and `trimmed` reports the one cap that acts WITHOUT refusing β history older than
|
| 26 |
-
// `maxVersions` is gone, and a reader who cannot see that would infer the file was
|
| 27 |
-
// only ever saved twice. Both are rendered, never inferred.
|
| 28 |
-
// ---------------------------------------------------------------------------
|
| 29 |
-
import { useCallback, useEffect, useRef, useState } from "react";
|
| 30 |
-
|
| 31 |
-
import type { HarnessDoc, HarnessFile, HarnessLimits } from "./automationApi";
|
| 32 |
-
import {
|
| 33 |
-
AutomationError, deleteHarness, listHarness, readHarness, writeHarness,
|
| 34 |
-
} from "./automationApi";
|
| 35 |
-
import "./automation.css";
|
| 36 |
-
|
| 37 |
-
/** The files a fresh agent is offered, as NAMES only. Nothing is created until somebody saves. */
|
| 38 |
-
const SUGGESTED_PATHS = ["skills/router.md", "skills/agent.md"];
|
| 39 |
-
|
| 40 |
-
function kb(bytes: number): string {
|
| 41 |
-
if (bytes < 1024) return `${bytes} bytes`;
|
| 42 |
-
return `${(bytes / 1024).toFixed(bytes < 10240 ? 1 : 0)} KB`;
|
| 43 |
-
}
|
| 44 |
-
|
| 45 |
-
/**
|
| 46 |
-
* `2026-08-18T14:50:09Z` as something a person reads. β Falls back to the raw string rather than
|
| 47 |
-
* to an empty cell: an unparseable stamp is still evidence of WHEN, and a blank reads as "never".
|
| 48 |
-
*/
|
| 49 |
-
function when(iso: string): string {
|
| 50 |
-
if (!iso) return "";
|
| 51 |
-
const d = new Date(iso);
|
| 52 |
-
if (Number.isNaN(d.getTime())) return iso;
|
| 53 |
-
return d.toLocaleString(undefined, {
|
| 54 |
-
year: "numeric", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit",
|
| 55 |
-
});
|
| 56 |
-
}
|
| 57 |
-
|
| 58 |
-
/** Who wrote it, in words. R8's point is that BOTH may, so the answer is always stated. */
|
| 59 |
-
const byline = (author: string, kind: string) =>
|
| 60 |
-
`${kind === "agent" ? "the agent" : author || "a person"}`;
|
| 61 |
-
|
| 62 |
-
export default function HarnessPanel({ agentId }: { agentId: string }) {
|
| 63 |
-
const [files, setFiles] = useState<HarnessFile[] | null>(null);
|
| 64 |
-
const [limits, setLimits] = useState<HarnessLimits | null>(null);
|
| 65 |
-
const [listErr, setListErr] = useState("");
|
| 66 |
-
const [open, setOpen] = useState<HarnessDoc | null>(null);
|
| 67 |
-
const [openErr, setOpenErr] = useState("");
|
| 68 |
-
const [draft, setDraft] = useState("");
|
| 69 |
-
const [busy, setBusy] = useState<"" | "open" | "save" | "delete">("");
|
| 70 |
-
const [newPath, setNewPath] = useState("");
|
| 71 |
-
const [note, setNote] = useState("");
|
| 72 |
-
/** Which older version is being previewed, or 0 for the current one. */
|
| 73 |
-
const [at, setAt] = useState(0);
|
| 74 |
-
const dirty = useRef(false);
|
| 75 |
-
/**
|
| 76 |
-
* β THE OPEN THAT WOULD THROW AWAY TYPING, HELD UNTIL IT IS CONFIRMED.
|
| 77 |
-
*
|
| 78 |
-
* Every other control here is safe to misclick: R8 means nothing is ever destroyed on the
|
| 79 |
-
* server. The ONE thing that can be lost is a body somebody has typed and not saved, and it is
|
| 80 |
-
* lost by the most inviting click on the panel (a version in the history, one row from Save).
|
| 81 |
-
* β Deliberately NOT `window.confirm`. A native dialog blocks the whole tab, cannot be styled,
|
| 82 |
-
* and reads as a browser error rather than as this panel asking a question.
|
| 83 |
-
*/
|
| 84 |
-
const [holdOpen, setHoldOpen] = useState<{ path: string; version: number } | null>(null);
|
| 85 |
-
|
| 86 |
-
const refresh = useCallback(async (signal?: AbortSignal) => {
|
| 87 |
-
try {
|
| 88 |
-
const r = await listHarness(agentId, signal);
|
| 89 |
-
if (signal?.aborted) return;
|
| 90 |
-
setFiles(r.files || []);
|
| 91 |
-
setLimits(r.limits || null);
|
| 92 |
-
setListErr("");
|
| 93 |
-
} catch (e: unknown) {
|
| 94 |
-
if (signal?.aborted) return;
|
| 95 |
-
setFiles([]);
|
| 96 |
-
setListErr(e instanceof AutomationError ? e.message : "the harness could not be read");
|
| 97 |
-
}
|
| 98 |
-
}, [agentId]);
|
| 99 |
-
|
| 100 |
-
useEffect(() => {
|
| 101 |
-
const ac = new AbortController();
|
| 102 |
-
void refresh(ac.signal);
|
| 103 |
-
return () => ac.abort();
|
| 104 |
-
}, [refresh]);
|
| 105 |
-
|
| 106 |
-
/**
|
| 107 |
-
* Open one file at one version.
|
| 108 |
-
* β THE DRAFT IS ONLY ADOPTED WHEN IT IS SAFE TO. Reading an OLDER version fills the editor with
|
| 109 |
-
* that body on purpose β that is how a roll-back is composed, and the save button says so β but
|
| 110 |
-
* it must not silently throw away something half-typed, so an unsaved edit is confirmed in words
|
| 111 |
-
* by the caller rather than by a browser dialog this panel cannot style.
|
| 112 |
-
*/
|
| 113 |
-
const openFile = useCallback(async (path: string, version = 0, force = false) => {
|
| 114 |
-
// The guard fires only when something WOULD be lost: a typed body, going somewhere else.
|
| 115 |
-
if (!force && dirty.current && !(open?.path === path && (at || 0) === version)) {
|
| 116 |
-
setHoldOpen({ path, version });
|
| 117 |
-
return;
|
| 118 |
-
}
|
| 119 |
-
setHoldOpen(null);
|
| 120 |
-
setBusy("open");
|
| 121 |
-
setOpenErr("");
|
| 122 |
-
setNote("");
|
| 123 |
-
try {
|
| 124 |
-
const doc = await readHarness(agentId, path, version || undefined);
|
| 125 |
-
setOpen(doc);
|
| 126 |
-
setDraft(doc.body);
|
| 127 |
-
setAt(version || 0);
|
| 128 |
-
dirty.current = false;
|
| 129 |
-
} catch (e: unknown) {
|
| 130 |
-
// β THE SERVER'S OWN SENTENCE. A trimmed version answers 410 with a sentence naming the cap;
|
| 131 |
-
// replacing it with "could not open" throws away the only part a person can act on.
|
| 132 |
-
setOpenErr(e instanceof AutomationError ? e.message : "that file could not be opened");
|
| 133 |
-
} finally {
|
| 134 |
-
setBusy("");
|
| 135 |
-
}
|
| 136 |
-
}, [agentId, open, at]);
|
| 137 |
-
|
| 138 |
-
const save = useCallback(async (restoredFrom?: number) => {
|
| 139 |
-
if (!open) return;
|
| 140 |
-
setBusy("save");
|
| 141 |
-
setNote("");
|
| 142 |
-
try {
|
| 143 |
-
const doc = await writeHarness(agentId, {
|
| 144 |
-
path: open.path,
|
| 145 |
-
body: draft,
|
| 146 |
-
// β `user`, ALWAYS, from this panel. `authorKind` is a claim about who DRAFTED the body,
|
| 147 |
-
// and everything typed here was typed by the person at the keyboard. The agent's own
|
| 148 |
-
// writes go through `record_version()` on the server with no session at all; a client
|
| 149 |
-
// that stamped "agent" on a hand-typed file would make the history a record of nothing.
|
| 150 |
-
authorKind: "user",
|
| 151 |
-
...(restoredFrom ? { restoredFrom } : {}),
|
| 152 |
-
});
|
| 153 |
-
setOpen(doc);
|
| 154 |
-
setDraft(doc.body);
|
| 155 |
-
setAt(0);
|
| 156 |
-
dirty.current = false;
|
| 157 |
-
setNote(restoredFrom
|
| 158 |
-
? `Version ${restoredFrom} is back, saved as version ${doc.atVersion}. Nothing was deleted.`
|
| 159 |
-
: `Saved as version ${doc.atVersion}.`);
|
| 160 |
-
await refresh();
|
| 161 |
-
} catch (e: unknown) {
|
| 162 |
-
setNote(e instanceof AutomationError ? e.message : "that file could not be saved");
|
| 163 |
-
} finally {
|
| 164 |
-
setBusy("");
|
| 165 |
-
}
|
| 166 |
-
}, [agentId, open, draft, refresh]);
|
| 167 |
-
|
| 168 |
-
const create = useCallback(async () => {
|
| 169 |
-
const path = newPath.trim();
|
| 170 |
-
if (!path) return;
|
| 171 |
-
setBusy("save");
|
| 172 |
-
setNote("");
|
| 173 |
-
try {
|
| 174 |
-
const doc = await writeHarness(agentId, { path, body: "", authorKind: "user" });
|
| 175 |
-
setNewPath("");
|
| 176 |
-
setOpen(doc);
|
| 177 |
-
setDraft(doc.body);
|
| 178 |
-
setAt(0);
|
| 179 |
-
dirty.current = false;
|
| 180 |
-
await refresh();
|
| 181 |
-
} catch (e: unknown) {
|
| 182 |
-
setNote(e instanceof AutomationError ? e.message : "that file could not be created");
|
| 183 |
-
} finally {
|
| 184 |
-
setBusy("");
|
| 185 |
-
}
|
| 186 |
-
}, [agentId, newPath, refresh]);
|
| 187 |
-
|
| 188 |
-
const drop = useCallback(async (path: string) => {
|
| 189 |
-
setBusy("delete");
|
| 190 |
-
setNote("");
|
| 191 |
-
try {
|
| 192 |
-
await deleteHarness(agentId, path);
|
| 193 |
-
if (open?.path === path) {
|
| 194 |
-
setOpen(null);
|
| 195 |
-
setDraft("");
|
| 196 |
-
}
|
| 197 |
-
await refresh();
|
| 198 |
-
} catch (e: unknown) {
|
| 199 |
-
setNote(e instanceof AutomationError ? e.message : "that file could not be deleted");
|
| 200 |
-
} finally {
|
| 201 |
-
setBusy("");
|
| 202 |
-
}
|
| 203 |
-
}, [agentId, open, refresh]);
|
| 204 |
-
|
| 205 |
-
const full = !!(limits && files && files.length >= limits.maxFiles);
|
| 206 |
-
const tooBig = !!(limits && new TextEncoder().encode(draft).length > limits.maxBodyBytes);
|
| 207 |
-
|
| 208 |
-
if (files === null) {
|
| 209 |
-
return <p className="auto-note">Reading this agent's harness files.</p>;
|
| 210 |
-
}
|
| 211 |
-
|
| 212 |
-
return (
|
| 213 |
-
<div className="autoh-wrap">
|
| 214 |
-
{listErr ? <p className="auto-note">{listErr}</p> : null}
|
| 215 |
-
|
| 216 |
-
{/* ββ the file list βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 217 |
-
{!files.length && !listErr ? (
|
| 218 |
-
<p className="auto-hint">
|
| 219 |
-
This agent has no harness files yet. A harness file is what the agent is instructed to
|
| 220 |
-
do: its router, its skills, anything it should read before it acts. Both you and the
|
| 221 |
-
agent can write them, and every save keeps the version before it.
|
| 222 |
-
</p>
|
| 223 |
-
) : null}
|
| 224 |
-
|
| 225 |
-
<ul className="autoh-files">
|
| 226 |
-
{files.map((f) => (
|
| 227 |
-
<li key={f.path} className={"autoh-file" + (open?.path === f.path ? " is-on" : "")}>
|
| 228 |
-
<button
|
| 229 |
-
type="button"
|
| 230 |
-
className="autoh-open"
|
| 231 |
-
disabled={busy !== ""}
|
| 232 |
-
onClick={() => void openFile(f.path)}
|
| 233 |
-
>
|
| 234 |
-
<span className="autoh-path">{f.path}</span>
|
| 235 |
-
<span className="autoh-meta">
|
| 236 |
-
v{f.version}, {kb(f.bytes)}, {when(f.updated)} by {byline(f.author, f.authorKind)}
|
| 237 |
-
</span>
|
| 238 |
-
</button>
|
| 239 |
-
{/* β DELETING A FILE IS NOT THE THING R8 FORBIDS. R8 forbids a roll-back implemented as
|
| 240 |
-
a delete. Removing a file is a person deciding it should not exist, which is a
|
| 241 |
-
different act and gets a different, quieter control. */}
|
| 242 |
-
<button
|
| 243 |
-
type="button"
|
| 244 |
-
className="auto-btn is-danger autoh-drop"
|
| 245 |
-
disabled={busy !== ""}
|
| 246 |
-
aria-label={`Delete ${f.path}`}
|
| 247 |
-
onClick={() => void drop(f.path)}
|
| 248 |
-
>
|
| 249 |
-
Delete
|
| 250 |
-
</button>
|
| 251 |
-
</li>
|
| 252 |
-
))}
|
| 253 |
-
</ul>
|
| 254 |
-
|
| 255 |
-
{/* ββ add a file ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 256 |
-
<div className="auto-field">
|
| 257 |
-
<label htmlFor="autoh-new">Add a file</label>
|
| 258 |
-
<div className="autoh-newrow">
|
| 259 |
-
<input
|
| 260 |
-
id="autoh-new"
|
| 261 |
-
className="auto-input"
|
| 262 |
-
value={newPath}
|
| 263 |
-
placeholder={SUGGESTED_PATHS[0]}
|
| 264 |
-
maxLength={limits?.maxPath || 200}
|
| 265 |
-
disabled={busy !== "" || full}
|
| 266 |
-
onChange={(e) => setNewPath(e.target.value)}
|
| 267 |
-
onKeyDown={(e) => {
|
| 268 |
-
if (e.key === "Enter") {
|
| 269 |
-
e.preventDefault();
|
| 270 |
-
void create();
|
| 271 |
-
}
|
| 272 |
-
}}
|
| 273 |
-
/>
|
| 274 |
-
<button
|
| 275 |
-
type="button"
|
| 276 |
-
className="auto-btn"
|
| 277 |
-
disabled={busy !== "" || full || !newPath.trim()}
|
| 278 |
-
onClick={() => void create()}
|
| 279 |
-
>
|
| 280 |
-
Add
|
| 281 |
-
</button>
|
| 282 |
-
</div>
|
| 283 |
-
{/* β THE CAP IS SAID BEFORE IT BITES, not after. `limits` rides the payload for exactly
|
| 284 |
-
this; a ceiling a person meets as a refusal is a ceiling nobody could plan around. */}
|
| 285 |
-
<p className="auto-hint">
|
| 286 |
-
{full
|
| 287 |
-
? `This agent already has the maximum of ${limits?.maxFiles} harness files. `
|
| 288 |
-
+ "Delete one to add another."
|
| 289 |
-
: `A path like ${SUGGESTED_PATHS.join(" or ")}. `
|
| 290 |
-
+ (limits ? `Up to ${limits.maxFiles} files, ${kb(limits.maxBodyBytes)} each.` : "")}
|
| 291 |
-
</p>
|
| 292 |
-
</div>
|
| 293 |
-
|
| 294 |
-
{openErr ? <p className="auto-note">{openErr}</p> : null}
|
| 295 |
-
|
| 296 |
-
{holdOpen ? (
|
| 297 |
-
<div className="autoh-hold">
|
| 298 |
-
<p className="auto-note">
|
| 299 |
-
The changes you typed into {open?.path} have not been saved, and opening{" "}
|
| 300 |
-
{holdOpen.version ? `version ${holdOpen.version}` : holdOpen.path} would replace them.
|
| 301 |
-
</p>
|
| 302 |
-
<div className="autoh-actions">
|
| 303 |
-
<button
|
| 304 |
-
type="button"
|
| 305 |
-
className="auto-btn"
|
| 306 |
-
onClick={() => void openFile(holdOpen.path, holdOpen.version, true)}
|
| 307 |
-
>
|
| 308 |
-
Discard them and open
|
| 309 |
-
</button>
|
| 310 |
-
<button type="button" className="auto-btn" onClick={() => setHoldOpen(null)}>
|
| 311 |
-
Keep editing
|
| 312 |
-
</button>
|
| 313 |
-
</div>
|
| 314 |
-
</div>
|
| 315 |
-
) : null}
|
| 316 |
-
|
| 317 |
-
{/* ββ the editor ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 318 |
-
{open ? (
|
| 319 |
-
<>
|
| 320 |
-
<h3>{open.path}</h3>
|
| 321 |
-
{at ? (
|
| 322 |
-
/* β AN OLDER BODY IS LABELLED AS ONE, LOUDLY. Without this the editor shows an old
|
| 323 |
-
body in the same frame as the current one, and Save then looks like an ordinary
|
| 324 |
-
save rather than a roll-back. Naming it is what makes the next click honest. */
|
| 325 |
-
<p className="auto-note">
|
| 326 |
-
You are reading version {at} of {open.versions + open.trimmed}. Saving it writes a
|
| 327 |
-
NEW version that restores this one. Nothing in between is deleted.
|
| 328 |
-
</p>
|
| 329 |
-
) : null}
|
| 330 |
-
<div className="auto-field">
|
| 331 |
-
<label htmlFor="autoh-body">
|
| 332 |
-
{at ? `Version ${at}` : `Current body, version ${open.atVersion}`}
|
| 333 |
-
</label>
|
| 334 |
-
<textarea
|
| 335 |
-
id="autoh-body"
|
| 336 |
-
className="auto-input is-mono autoh-body"
|
| 337 |
-
rows={14}
|
| 338 |
-
value={draft}
|
| 339 |
-
disabled={busy === "save"}
|
| 340 |
-
onChange={(e) => {
|
| 341 |
-
setDraft(e.target.value);
|
| 342 |
-
dirty.current = true;
|
| 343 |
-
}}
|
| 344 |
-
/>
|
| 345 |
-
<p className="auto-hint">
|
| 346 |
-
{tooBig
|
| 347 |
-
? `This is larger than the ${kb(limits?.maxBodyBytes || 0)} a harness file may be, `
|
| 348 |
-
+ "so it will be refused. Shorten it."
|
| 349 |
-
: `${kb(new TextEncoder().encode(draft).length)} of `
|
| 350 |
-
+ `${kb(limits?.maxBodyBytes || 0)}.`}
|
| 351 |
-
</p>
|
| 352 |
-
</div>
|
| 353 |
-
<div className="autoh-actions">
|
| 354 |
-
<button
|
| 355 |
-
type="button"
|
| 356 |
-
className="auto-btn is-primary"
|
| 357 |
-
disabled={busy !== "" || tooBig}
|
| 358 |
-
onClick={() => void save(at || undefined)}
|
| 359 |
-
>
|
| 360 |
-
{busy === "save"
|
| 361 |
-
? "Saving"
|
| 362 |
-
: at
|
| 363 |
-
? `Restore version ${at}`
|
| 364 |
-
: "Save a new version"}
|
| 365 |
-
</button>
|
| 366 |
-
{at ? (
|
| 367 |
-
<button
|
| 368 |
-
type="button"
|
| 369 |
-
className="auto-btn"
|
| 370 |
-
disabled={busy !== ""}
|
| 371 |
-
onClick={() => void openFile(open.path)}
|
| 372 |
-
>
|
| 373 |
-
Back to current
|
| 374 |
-
</button>
|
| 375 |
-
) : null}
|
| 376 |
-
</div>
|
| 377 |
-
{note ? <p className="auto-note">{note}</p> : null}
|
| 378 |
-
|
| 379 |
-
{/* ββ the history βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 380 |
-
<h3>Version history</h3>
|
| 381 |
-
<ol className="autoh-history">
|
| 382 |
-
{open.history.map((v) => (
|
| 383 |
-
<li key={v.version} className={v.version === (at || open.atVersion) ? "is-on" : ""}>
|
| 384 |
-
<button
|
| 385 |
-
type="button"
|
| 386 |
-
className="autoh-version"
|
| 387 |
-
disabled={busy !== ""}
|
| 388 |
-
onClick={() => void openFile(open.path, v.version)}
|
| 389 |
-
>
|
| 390 |
-
<span className="autoh-vnum">v{v.version}</span>
|
| 391 |
-
<span className="autoh-meta">
|
| 392 |
-
{when(v.created)} by {byline(v.author, v.authorKind)}, {kb(v.bytes)}
|
| 393 |
-
{v.restoredFrom ? `, restored version ${v.restoredFrom}` : ""}
|
| 394 |
-
</span>
|
| 395 |
-
</button>
|
| 396 |
-
</li>
|
| 397 |
-
))}
|
| 398 |
-
</ol>
|
| 399 |
-
{/* β THE CAP THAT ACTS WITHOUT REFUSING. Past `maxVersions` the OLDEST bodies are
|
| 400 |
-
dropped, and a history that simply started at v14 would read as a file first saved
|
| 401 |
-
at v14. R6's second sentence: a limit that bites is REPORTED. */}
|
| 402 |
-
{open.trimmed ? (
|
| 403 |
-
<p className="auto-hint">
|
| 404 |
-
The {open.trimmed} oldest version{open.trimmed === 1 ? "" : "s"} of this file
|
| 405 |
-
{open.trimmed === 1 ? " has" : " have"} been dropped, because only the newest{" "}
|
| 406 |
-
{limits?.maxVersions} are kept. What they said is gone; that they existed is not.
|
| 407 |
-
</p>
|
| 408 |
-
) : null}
|
| 409 |
-
</>
|
| 410 |
-
) : null}
|
| 411 |
-
</div>
|
| 412 |
-
);
|
| 413 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// automation/HarnessPanel.tsx β the HARNESS tab (owner item 3, rulings R7/R8,
|
| 3 |
+
// contract C4 Β· W36-T31).
|
| 4 |
+
//
|
| 5 |
+
// Owner, verbatim (2026-08-18): *"For each of the tenant's Agent, I think we need
|
| 6 |
+
// another tab beside Properties/Run history. This new module under agent is
|
| 7 |
+
// supposed to host any file pertaining to the agent skills, router etc. So we
|
| 8 |
+
// build a user can build a custom harness for each agent through the chat
|
| 9 |
+
// interface."*
|
| 10 |
+
//
|
| 11 |
+
// ββ R8 IS THE WHOLE SHAPE AND IT IS ENFORCED ON THE SERVER, NOT HERE. Every save
|
| 12 |
+
// APPENDS a version; there is no overwrite door and no edit-in-place. A ROLL-BACK
|
| 13 |
+
// IS A WRITE OF AN OLDER BODY, never a delete β so "restore v1" produces v4 whose
|
| 14 |
+
// `restoredFrom` is 1, and the history keeps v2 and v3 saying what actually
|
| 15 |
+
// happened rather than what somebody last wanted it to look like. This panel
|
| 16 |
+
// paints that model; it does not implement it, and it must never offer a control
|
| 17 |
+
// whose name implies otherwise ("Replace", "Overwrite", "Discard v2").
|
| 18 |
+
//
|
| 19 |
+
// β R8 IS DELIBERATELY NOT R9, and the two sit one screen apart. An agent-authored
|
| 20 |
+
// ACTION's config is agent-only (item 8); a harness file is editable by BOTH the
|
| 21 |
+
// user and the agent. Do not copy either posture onto the other.
|
| 22 |
+
//
|
| 23 |
+
// β THIS PANEL IS THE ONE PLACE THE CAPS ARE VISIBLE. `limits` rides every C4
|
| 24 |
+
// payload precisely so a control can say "this file is full" BEFORE a write fails,
|
| 25 |
+
// and `trimmed` reports the one cap that acts WITHOUT refusing β history older than
|
| 26 |
+
// `maxVersions` is gone, and a reader who cannot see that would infer the file was
|
| 27 |
+
// only ever saved twice. Both are rendered, never inferred.
|
| 28 |
+
// ---------------------------------------------------------------------------
|
| 29 |
+
import { useCallback, useEffect, useRef, useState } from "react";
|
| 30 |
+
|
| 31 |
+
import type { HarnessDoc, HarnessFile, HarnessLimits } from "./automationApi";
|
| 32 |
+
import {
|
| 33 |
+
AutomationError, deleteHarness, listHarness, readHarness, writeHarness,
|
| 34 |
+
} from "./automationApi";
|
| 35 |
+
import "./automation.css";
|
| 36 |
+
|
| 37 |
+
/** The files a fresh agent is offered, as NAMES only. Nothing is created until somebody saves. */
|
| 38 |
+
const SUGGESTED_PATHS = ["skills/router.md", "skills/agent.md"];
|
| 39 |
+
|
| 40 |
+
function kb(bytes: number): string {
|
| 41 |
+
if (bytes < 1024) return `${bytes} bytes`;
|
| 42 |
+
return `${(bytes / 1024).toFixed(bytes < 10240 ? 1 : 0)} KB`;
|
| 43 |
+
}
|
| 44 |
+
|
| 45 |
+
/**
|
| 46 |
+
* `2026-08-18T14:50:09Z` as something a person reads. β Falls back to the raw string rather than
|
| 47 |
+
* to an empty cell: an unparseable stamp is still evidence of WHEN, and a blank reads as "never".
|
| 48 |
+
*/
|
| 49 |
+
function when(iso: string): string {
|
| 50 |
+
if (!iso) return "";
|
| 51 |
+
const d = new Date(iso);
|
| 52 |
+
if (Number.isNaN(d.getTime())) return iso;
|
| 53 |
+
return d.toLocaleString(undefined, {
|
| 54 |
+
year: "numeric", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit",
|
| 55 |
+
});
|
| 56 |
+
}
|
| 57 |
+
|
| 58 |
+
/** Who wrote it, in words. R8's point is that BOTH may, so the answer is always stated. */
|
| 59 |
+
const byline = (author: string, kind: string) =>
|
| 60 |
+
`${kind === "agent" ? "the agent" : author || "a person"}`;
|
| 61 |
+
|
| 62 |
+
export default function HarnessPanel({ agentId }: { agentId: string }) {
|
| 63 |
+
const [files, setFiles] = useState<HarnessFile[] | null>(null);
|
| 64 |
+
const [limits, setLimits] = useState<HarnessLimits | null>(null);
|
| 65 |
+
const [listErr, setListErr] = useState("");
|
| 66 |
+
const [open, setOpen] = useState<HarnessDoc | null>(null);
|
| 67 |
+
const [openErr, setOpenErr] = useState("");
|
| 68 |
+
const [draft, setDraft] = useState("");
|
| 69 |
+
const [busy, setBusy] = useState<"" | "open" | "save" | "delete">("");
|
| 70 |
+
const [newPath, setNewPath] = useState("");
|
| 71 |
+
const [note, setNote] = useState("");
|
| 72 |
+
/** Which older version is being previewed, or 0 for the current one. */
|
| 73 |
+
const [at, setAt] = useState(0);
|
| 74 |
+
const dirty = useRef(false);
|
| 75 |
+
/**
|
| 76 |
+
* β THE OPEN THAT WOULD THROW AWAY TYPING, HELD UNTIL IT IS CONFIRMED.
|
| 77 |
+
*
|
| 78 |
+
* Every other control here is safe to misclick: R8 means nothing is ever destroyed on the
|
| 79 |
+
* server. The ONE thing that can be lost is a body somebody has typed and not saved, and it is
|
| 80 |
+
* lost by the most inviting click on the panel (a version in the history, one row from Save).
|
| 81 |
+
* β Deliberately NOT `window.confirm`. A native dialog blocks the whole tab, cannot be styled,
|
| 82 |
+
* and reads as a browser error rather than as this panel asking a question.
|
| 83 |
+
*/
|
| 84 |
+
const [holdOpen, setHoldOpen] = useState<{ path: string; version: number } | null>(null);
|
| 85 |
+
|
| 86 |
+
const refresh = useCallback(async (signal?: AbortSignal) => {
|
| 87 |
+
try {
|
| 88 |
+
const r = await listHarness(agentId, signal);
|
| 89 |
+
if (signal?.aborted) return;
|
| 90 |
+
setFiles(r.files || []);
|
| 91 |
+
setLimits(r.limits || null);
|
| 92 |
+
setListErr("");
|
| 93 |
+
} catch (e: unknown) {
|
| 94 |
+
if (signal?.aborted) return;
|
| 95 |
+
setFiles([]);
|
| 96 |
+
setListErr(e instanceof AutomationError ? e.message : "the harness could not be read");
|
| 97 |
+
}
|
| 98 |
+
}, [agentId]);
|
| 99 |
+
|
| 100 |
+
useEffect(() => {
|
| 101 |
+
const ac = new AbortController();
|
| 102 |
+
void refresh(ac.signal);
|
| 103 |
+
return () => ac.abort();
|
| 104 |
+
}, [refresh]);
|
| 105 |
+
|
| 106 |
+
/**
|
| 107 |
+
* Open one file at one version.
|
| 108 |
+
* β THE DRAFT IS ONLY ADOPTED WHEN IT IS SAFE TO. Reading an OLDER version fills the editor with
|
| 109 |
+
* that body on purpose β that is how a roll-back is composed, and the save button says so β but
|
| 110 |
+
* it must not silently throw away something half-typed, so an unsaved edit is confirmed in words
|
| 111 |
+
* by the caller rather than by a browser dialog this panel cannot style.
|
| 112 |
+
*/
|
| 113 |
+
const openFile = useCallback(async (path: string, version = 0, force = false) => {
|
| 114 |
+
// The guard fires only when something WOULD be lost: a typed body, going somewhere else.
|
| 115 |
+
if (!force && dirty.current && !(open?.path === path && (at || 0) === version)) {
|
| 116 |
+
setHoldOpen({ path, version });
|
| 117 |
+
return;
|
| 118 |
+
}
|
| 119 |
+
setHoldOpen(null);
|
| 120 |
+
setBusy("open");
|
| 121 |
+
setOpenErr("");
|
| 122 |
+
setNote("");
|
| 123 |
+
try {
|
| 124 |
+
const doc = await readHarness(agentId, path, version || undefined);
|
| 125 |
+
setOpen(doc);
|
| 126 |
+
setDraft(doc.body);
|
| 127 |
+
setAt(version || 0);
|
| 128 |
+
dirty.current = false;
|
| 129 |
+
} catch (e: unknown) {
|
| 130 |
+
// β THE SERVER'S OWN SENTENCE. A trimmed version answers 410 with a sentence naming the cap;
|
| 131 |
+
// replacing it with "could not open" throws away the only part a person can act on.
|
| 132 |
+
setOpenErr(e instanceof AutomationError ? e.message : "that file could not be opened");
|
| 133 |
+
} finally {
|
| 134 |
+
setBusy("");
|
| 135 |
+
}
|
| 136 |
+
}, [agentId, open, at]);
|
| 137 |
+
|
| 138 |
+
const save = useCallback(async (restoredFrom?: number) => {
|
| 139 |
+
if (!open) return;
|
| 140 |
+
setBusy("save");
|
| 141 |
+
setNote("");
|
| 142 |
+
try {
|
| 143 |
+
const doc = await writeHarness(agentId, {
|
| 144 |
+
path: open.path,
|
| 145 |
+
body: draft,
|
| 146 |
+
// β `user`, ALWAYS, from this panel. `authorKind` is a claim about who DRAFTED the body,
|
| 147 |
+
// and everything typed here was typed by the person at the keyboard. The agent's own
|
| 148 |
+
// writes go through `record_version()` on the server with no session at all; a client
|
| 149 |
+
// that stamped "agent" on a hand-typed file would make the history a record of nothing.
|
| 150 |
+
authorKind: "user",
|
| 151 |
+
...(restoredFrom ? { restoredFrom } : {}),
|
| 152 |
+
});
|
| 153 |
+
setOpen(doc);
|
| 154 |
+
setDraft(doc.body);
|
| 155 |
+
setAt(0);
|
| 156 |
+
dirty.current = false;
|
| 157 |
+
setNote(restoredFrom
|
| 158 |
+
? `Version ${restoredFrom} is back, saved as version ${doc.atVersion}. Nothing was deleted.`
|
| 159 |
+
: `Saved as version ${doc.atVersion}.`);
|
| 160 |
+
await refresh();
|
| 161 |
+
} catch (e: unknown) {
|
| 162 |
+
setNote(e instanceof AutomationError ? e.message : "that file could not be saved");
|
| 163 |
+
} finally {
|
| 164 |
+
setBusy("");
|
| 165 |
+
}
|
| 166 |
+
}, [agentId, open, draft, refresh]);
|
| 167 |
+
|
| 168 |
+
const create = useCallback(async () => {
|
| 169 |
+
const path = newPath.trim();
|
| 170 |
+
if (!path) return;
|
| 171 |
+
setBusy("save");
|
| 172 |
+
setNote("");
|
| 173 |
+
try {
|
| 174 |
+
const doc = await writeHarness(agentId, { path, body: "", authorKind: "user" });
|
| 175 |
+
setNewPath("");
|
| 176 |
+
setOpen(doc);
|
| 177 |
+
setDraft(doc.body);
|
| 178 |
+
setAt(0);
|
| 179 |
+
dirty.current = false;
|
| 180 |
+
await refresh();
|
| 181 |
+
} catch (e: unknown) {
|
| 182 |
+
setNote(e instanceof AutomationError ? e.message : "that file could not be created");
|
| 183 |
+
} finally {
|
| 184 |
+
setBusy("");
|
| 185 |
+
}
|
| 186 |
+
}, [agentId, newPath, refresh]);
|
| 187 |
+
|
| 188 |
+
const drop = useCallback(async (path: string) => {
|
| 189 |
+
setBusy("delete");
|
| 190 |
+
setNote("");
|
| 191 |
+
try {
|
| 192 |
+
await deleteHarness(agentId, path);
|
| 193 |
+
if (open?.path === path) {
|
| 194 |
+
setOpen(null);
|
| 195 |
+
setDraft("");
|
| 196 |
+
}
|
| 197 |
+
await refresh();
|
| 198 |
+
} catch (e: unknown) {
|
| 199 |
+
setNote(e instanceof AutomationError ? e.message : "that file could not be deleted");
|
| 200 |
+
} finally {
|
| 201 |
+
setBusy("");
|
| 202 |
+
}
|
| 203 |
+
}, [agentId, open, refresh]);
|
| 204 |
+
|
| 205 |
+
const full = !!(limits && files && files.length >= limits.maxFiles);
|
| 206 |
+
const tooBig = !!(limits && new TextEncoder().encode(draft).length > limits.maxBodyBytes);
|
| 207 |
+
|
| 208 |
+
if (files === null) {
|
| 209 |
+
return <p className="auto-note">Reading this agent's harness files.</p>;
|
| 210 |
+
}
|
| 211 |
+
|
| 212 |
+
return (
|
| 213 |
+
<div className="autoh-wrap">
|
| 214 |
+
{listErr ? <p className="auto-note">{listErr}</p> : null}
|
| 215 |
+
|
| 216 |
+
{/* ββ the file list βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 217 |
+
{!files.length && !listErr ? (
|
| 218 |
+
<p className="auto-hint">
|
| 219 |
+
This agent has no harness files yet. A harness file is what the agent is instructed to
|
| 220 |
+
do: its router, its skills, anything it should read before it acts. Both you and the
|
| 221 |
+
agent can write them, and every save keeps the version before it.
|
| 222 |
+
</p>
|
| 223 |
+
) : null}
|
| 224 |
+
|
| 225 |
+
<ul className="autoh-files">
|
| 226 |
+
{files.map((f) => (
|
| 227 |
+
<li key={f.path} className={"autoh-file" + (open?.path === f.path ? " is-on" : "")}>
|
| 228 |
+
<button
|
| 229 |
+
type="button"
|
| 230 |
+
className="autoh-open"
|
| 231 |
+
disabled={busy !== ""}
|
| 232 |
+
onClick={() => void openFile(f.path)}
|
| 233 |
+
>
|
| 234 |
+
<span className="autoh-path">{f.path}</span>
|
| 235 |
+
<span className="autoh-meta">
|
| 236 |
+
v{f.version}, {kb(f.bytes)}, {when(f.updated)} by {byline(f.author, f.authorKind)}
|
| 237 |
+
</span>
|
| 238 |
+
</button>
|
| 239 |
+
{/* β DELETING A FILE IS NOT THE THING R8 FORBIDS. R8 forbids a roll-back implemented as
|
| 240 |
+
a delete. Removing a file is a person deciding it should not exist, which is a
|
| 241 |
+
different act and gets a different, quieter control. */}
|
| 242 |
+
<button
|
| 243 |
+
type="button"
|
| 244 |
+
className="auto-btn is-danger autoh-drop"
|
| 245 |
+
disabled={busy !== ""}
|
| 246 |
+
aria-label={`Delete ${f.path}`}
|
| 247 |
+
onClick={() => void drop(f.path)}
|
| 248 |
+
>
|
| 249 |
+
Delete
|
| 250 |
+
</button>
|
| 251 |
+
</li>
|
| 252 |
+
))}
|
| 253 |
+
</ul>
|
| 254 |
+
|
| 255 |
+
{/* ββ add a file ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 256 |
+
<div className="auto-field">
|
| 257 |
+
<label htmlFor="autoh-new">Add a file</label>
|
| 258 |
+
<div className="autoh-newrow">
|
| 259 |
+
<input
|
| 260 |
+
id="autoh-new"
|
| 261 |
+
className="auto-input"
|
| 262 |
+
value={newPath}
|
| 263 |
+
placeholder={SUGGESTED_PATHS[0]}
|
| 264 |
+
maxLength={limits?.maxPath || 200}
|
| 265 |
+
disabled={busy !== "" || full}
|
| 266 |
+
onChange={(e) => setNewPath(e.target.value)}
|
| 267 |
+
onKeyDown={(e) => {
|
| 268 |
+
if (e.key === "Enter") {
|
| 269 |
+
e.preventDefault();
|
| 270 |
+
void create();
|
| 271 |
+
}
|
| 272 |
+
}}
|
| 273 |
+
/>
|
| 274 |
+
<button
|
| 275 |
+
type="button"
|
| 276 |
+
className="auto-btn"
|
| 277 |
+
disabled={busy !== "" || full || !newPath.trim()}
|
| 278 |
+
onClick={() => void create()}
|
| 279 |
+
>
|
| 280 |
+
Add
|
| 281 |
+
</button>
|
| 282 |
+
</div>
|
| 283 |
+
{/* β THE CAP IS SAID BEFORE IT BITES, not after. `limits` rides the payload for exactly
|
| 284 |
+
this; a ceiling a person meets as a refusal is a ceiling nobody could plan around. */}
|
| 285 |
+
<p className="auto-hint">
|
| 286 |
+
{full
|
| 287 |
+
? `This agent already has the maximum of ${limits?.maxFiles} harness files. `
|
| 288 |
+
+ "Delete one to add another."
|
| 289 |
+
: `A path like ${SUGGESTED_PATHS.join(" or ")}. `
|
| 290 |
+
+ (limits ? `Up to ${limits.maxFiles} files, ${kb(limits.maxBodyBytes)} each.` : "")}
|
| 291 |
+
</p>
|
| 292 |
+
</div>
|
| 293 |
+
|
| 294 |
+
{openErr ? <p className="auto-note">{openErr}</p> : null}
|
| 295 |
+
|
| 296 |
+
{holdOpen ? (
|
| 297 |
+
<div className="autoh-hold">
|
| 298 |
+
<p className="auto-note">
|
| 299 |
+
The changes you typed into {open?.path} have not been saved, and opening{" "}
|
| 300 |
+
{holdOpen.version ? `version ${holdOpen.version}` : holdOpen.path} would replace them.
|
| 301 |
+
</p>
|
| 302 |
+
<div className="autoh-actions">
|
| 303 |
+
<button
|
| 304 |
+
type="button"
|
| 305 |
+
className="auto-btn"
|
| 306 |
+
onClick={() => void openFile(holdOpen.path, holdOpen.version, true)}
|
| 307 |
+
>
|
| 308 |
+
Discard them and open
|
| 309 |
+
</button>
|
| 310 |
+
<button type="button" className="auto-btn" onClick={() => setHoldOpen(null)}>
|
| 311 |
+
Keep editing
|
| 312 |
+
</button>
|
| 313 |
+
</div>
|
| 314 |
+
</div>
|
| 315 |
+
) : null}
|
| 316 |
+
|
| 317 |
+
{/* ββ the editor ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 318 |
+
{open ? (
|
| 319 |
+
<>
|
| 320 |
+
<h3>{open.path}</h3>
|
| 321 |
+
{at ? (
|
| 322 |
+
/* β AN OLDER BODY IS LABELLED AS ONE, LOUDLY. Without this the editor shows an old
|
| 323 |
+
body in the same frame as the current one, and Save then looks like an ordinary
|
| 324 |
+
save rather than a roll-back. Naming it is what makes the next click honest. */
|
| 325 |
+
<p className="auto-note">
|
| 326 |
+
You are reading version {at} of {open.versions + open.trimmed}. Saving it writes a
|
| 327 |
+
NEW version that restores this one. Nothing in between is deleted.
|
| 328 |
+
</p>
|
| 329 |
+
) : null}
|
| 330 |
+
<div className="auto-field">
|
| 331 |
+
<label htmlFor="autoh-body">
|
| 332 |
+
{at ? `Version ${at}` : `Current body, version ${open.atVersion}`}
|
| 333 |
+
</label>
|
| 334 |
+
<textarea
|
| 335 |
+
id="autoh-body"
|
| 336 |
+
className="auto-input is-mono autoh-body"
|
| 337 |
+
rows={14}
|
| 338 |
+
value={draft}
|
| 339 |
+
disabled={busy === "save"}
|
| 340 |
+
onChange={(e) => {
|
| 341 |
+
setDraft(e.target.value);
|
| 342 |
+
dirty.current = true;
|
| 343 |
+
}}
|
| 344 |
+
/>
|
| 345 |
+
<p className="auto-hint">
|
| 346 |
+
{tooBig
|
| 347 |
+
? `This is larger than the ${kb(limits?.maxBodyBytes || 0)} a harness file may be, `
|
| 348 |
+
+ "so it will be refused. Shorten it."
|
| 349 |
+
: `${kb(new TextEncoder().encode(draft).length)} of `
|
| 350 |
+
+ `${kb(limits?.maxBodyBytes || 0)}.`}
|
| 351 |
+
</p>
|
| 352 |
+
</div>
|
| 353 |
+
<div className="autoh-actions">
|
| 354 |
+
<button
|
| 355 |
+
type="button"
|
| 356 |
+
className="auto-btn is-primary"
|
| 357 |
+
disabled={busy !== "" || tooBig}
|
| 358 |
+
onClick={() => void save(at || undefined)}
|
| 359 |
+
>
|
| 360 |
+
{busy === "save"
|
| 361 |
+
? "Saving"
|
| 362 |
+
: at
|
| 363 |
+
? `Restore version ${at}`
|
| 364 |
+
: "Save a new version"}
|
| 365 |
+
</button>
|
| 366 |
+
{at ? (
|
| 367 |
+
<button
|
| 368 |
+
type="button"
|
| 369 |
+
className="auto-btn"
|
| 370 |
+
disabled={busy !== ""}
|
| 371 |
+
onClick={() => void openFile(open.path)}
|
| 372 |
+
>
|
| 373 |
+
Back to current
|
| 374 |
+
</button>
|
| 375 |
+
) : null}
|
| 376 |
+
</div>
|
| 377 |
+
{note ? <p className="auto-note">{note}</p> : null}
|
| 378 |
+
|
| 379 |
+
{/* ββ the history βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */}
|
| 380 |
+
<h3>Version history</h3>
|
| 381 |
+
<ol className="autoh-history">
|
| 382 |
+
{open.history.map((v) => (
|
| 383 |
+
<li key={v.version} className={v.version === (at || open.atVersion) ? "is-on" : ""}>
|
| 384 |
+
<button
|
| 385 |
+
type="button"
|
| 386 |
+
className="autoh-version"
|
| 387 |
+
disabled={busy !== ""}
|
| 388 |
+
onClick={() => void openFile(open.path, v.version)}
|
| 389 |
+
>
|
| 390 |
+
<span className="autoh-vnum">v{v.version}</span>
|
| 391 |
+
<span className="autoh-meta">
|
| 392 |
+
{when(v.created)} by {byline(v.author, v.authorKind)}, {kb(v.bytes)}
|
| 393 |
+
{v.restoredFrom ? `, restored version ${v.restoredFrom}` : ""}
|
| 394 |
+
</span>
|
| 395 |
+
</button>
|
| 396 |
+
</li>
|
| 397 |
+
))}
|
| 398 |
+
</ol>
|
| 399 |
+
{/* β THE CAP THAT ACTS WITHOUT REFUSING. Past `maxVersions` the OLDEST bodies are
|
| 400 |
+
dropped, and a history that simply started at v14 would read as a file first saved
|
| 401 |
+
at v14. R6's second sentence: a limit that bites is REPORTED. */}
|
| 402 |
+
{open.trimmed ? (
|
| 403 |
+
<p className="auto-hint">
|
| 404 |
+
The {open.trimmed} oldest version{open.trimmed === 1 ? "" : "s"} of this file
|
| 405 |
+
{open.trimmed === 1 ? " has" : " have"} been dropped, because only the newest{" "}
|
| 406 |
+
{limits?.maxVersions} are kept. What they said is gone; that they existed is not.
|
| 407 |
+
</p>
|
| 408 |
+
) : null}
|
| 409 |
+
</>
|
| 410 |
+
) : null}
|
| 411 |
+
</div>
|
| 412 |
+
);
|
| 413 |
+
}
|
web/src/automation/PresetPlan.tsx
CHANGED
|
@@ -1,122 +1,122 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// automation/PresetPlan.tsx β WAVE 25 item 4 (ruling R2b, contract C1):
|
| 3 |
-
// WHICH COLUMNS THIS WILL USE, AND WHICH IT WILL CREATE.
|
| 4 |
-
//
|
| 5 |
-
// The owner's words: *"since this is a global fields all tenant use its really
|
| 6 |
-
// just appending it and adding it to the custom database"* β so the Create
|
| 7 |
-
// record action's configuration has to SHOW the two lists before anything is
|
| 8 |
-
// spent, on whatever database that action names, including a hand-made one.
|
| 9 |
-
//
|
| 10 |
-
// β IT RENDERS THE SERVER'S ANSWER AND COMPUTES NOTHING (C1: "the client
|
| 11 |
-
// renders this; it does not compute it"). Diffing the preset set against a
|
| 12 |
-
// table's columns here would be a second implementation of `ut_ensure`'s merge
|
| 13 |
-
// rule β and it would be wrong exactly when the two lists differ, which is the
|
| 14 |
-
// only case this panel exists to answer.
|
| 15 |
-
//
|
| 16 |
-
// β ITS OWN FILE, AND THAT IS THE BUILDER'S LAW BEING KEPT RATHER THAN BENT.
|
| 17 |
-
// `AutomationBuilder` renders SYNCHRONOUSLY from what it was handed (C14 leg 1
|
| 18 |
-
// β the ghost fix: a view that can be in two shapes shows you the wrong one).
|
| 19 |
-
// This panel genuinely needs a fetch, so it owns one, keeps a FIXED-SHAPE
|
| 20 |
-
// skeleton while it is in flight, and never changes the shape of anything above
|
| 21 |
-
// it. Exactly the split the Board already makes.
|
| 22 |
-
// ---------------------------------------------------------------------------
|
| 23 |
-
import { useEffect, useState } from "react";
|
| 24 |
-
|
| 25 |
-
import { getPresetPlan } from "./automationApi";
|
| 26 |
-
import type { PresetPlan as Plan } from "./automationApi";
|
| 27 |
-
|
| 28 |
-
type Load =
|
| 29 |
-
| { phase: "idle" }
|
| 30 |
-
| { phase: "loading" }
|
| 31 |
-
| { phase: "ready"; plan: Plan }
|
| 32 |
-
| { phase: "error" };
|
| 33 |
-
|
| 34 |
-
/**
|
| 35 |
-
* β ONE LINE PER LIST, NOT A TOUR (DESIGN.md 4 / R13). The panel says what will happen and shows
|
| 36 |
-
* the column names; it does not explain what a preset is, why the set is shared across tenants,
|
| 37 |
-
* or what enrichment does. Each of those has a home β the action's own `detail`, the field's grey
|
| 38 |
-
* machine-owned mark, the run log β and repeating them here is the paragraph nobody reads.
|
| 39 |
-
*/
|
| 40 |
-
function List({ title, fields }: { title: string; fields: Plan["fields"] }) {
|
| 41 |
-
if (!fields.length) return null;
|
| 42 |
-
return (
|
| 43 |
-
<div className="autox-preset-list">
|
| 44 |
-
<p className="autox-preset-head">
|
| 45 |
-
{title} <span className="autox-preset-n">{fields.length}</span>
|
| 46 |
-
</p>
|
| 47 |
-
<div className="autox-preset-chips">
|
| 48 |
-
{fields.map((f) => (
|
| 49 |
-
<span className="autox-preset-chip" key={f.key} title={`${f.key} Β· ${f.type}`}>
|
| 50 |
-
{f.label}
|
| 51 |
-
</span>
|
| 52 |
-
))}
|
| 53 |
-
</div>
|
| 54 |
-
</div>
|
| 55 |
-
);
|
| 56 |
-
}
|
| 57 |
-
|
| 58 |
-
export default function PresetPlan({ table }: { table: string }) {
|
| 59 |
-
const [load, setLoad] = useState<Load>({ phase: "idle" });
|
| 60 |
-
|
| 61 |
-
useEffect(() => {
|
| 62 |
-
if (!table) {
|
| 63 |
-
setLoad({ phase: "idle" });
|
| 64 |
-
return;
|
| 65 |
-
}
|
| 66 |
-
const ac = new AbortController();
|
| 67 |
-
setLoad({ phase: "loading" });
|
| 68 |
-
getPresetPlan(table, ac.signal)
|
| 69 |
-
.then((plan) => setLoad({ phase: "ready", plan }))
|
| 70 |
-
.catch((e) => {
|
| 71 |
-
if ((e as Error)?.name === "AbortError") return;
|
| 72 |
-
setLoad({ phase: "error" });
|
| 73 |
-
});
|
| 74 |
-
return () => ac.abort();
|
| 75 |
-
}, [table]);
|
| 76 |
-
|
| 77 |
-
// β NO DATABASE, NO CLAIM. With nothing chosen there is no question to answer, so this renders
|
| 78 |
-
// nothing at all rather than an empty heading β a heading over nothing says "there should be
|
| 79 |
-
// something here", which is a different and false statement (R13, and the same reasoning R14
|
| 80 |
-
// applies to the whole Configuration section).
|
| 81 |
-
if (!table || load.phase === "idle") return null;
|
| 82 |
-
|
| 83 |
-
if (load.phase === "loading") {
|
| 84 |
-
return (
|
| 85 |
-
<p className="auto-note" role="status">
|
| 86 |
-
<span className="lp-spin" aria-label="Loading" />
|
| 87 |
-
</p>
|
| 88 |
-
);
|
| 89 |
-
}
|
| 90 |
-
|
| 91 |
-
// β HONEST, AND IT DOES NOT GUESS. A failed fetch is not "no columns will be created" β that
|
| 92 |
-
// would be a specific, checkable claim about the user's database, invented to keep a panel
|
| 93 |
-
// tidy ([[no-unverifiable-aggregates]]). It says the server did not answer.
|
| 94 |
-
if (load.phase === "error") {
|
| 95 |
-
return <p className="auto-note">Could not read this database's columns just now.</p>;
|
| 96 |
-
}
|
| 97 |
-
|
| 98 |
-
const { plan } = load;
|
| 99 |
-
return (
|
| 100 |
-
<div className="autox-preset">
|
| 101 |
-
{/*
|
| 102 |
-
β THREE STATES, AND THE FIRST TWO ARE DIFFERENT FACTS. A database that does not exist yet
|
| 103 |
-
(R10's spawn-on-save moment β the action names a table nobody has made) is not the same as
|
| 104 |
-
one that exists and shares none of the columns, even though both render an empty "already
|
| 105 |
-
here" list. The server answers `exists` precisely so this line does not have to infer it
|
| 106 |
-
from a length.
|
| 107 |
-
*/}
|
| 108 |
-
{!plan.exists ? (
|
| 109 |
-
<p className="auto-hint">
|
| 110 |
-
This database does not exist yet. Saving makes it, with these columns.
|
| 111 |
-
</p>
|
| 112 |
-
) : null}
|
| 113 |
-
<List title="Already in this database" fields={plan.willUse} />
|
| 114 |
-
<List title="Will be created" fields={plan.willCreate} />
|
| 115 |
-
{/* Both lists empty on a table that DOES exist means the server offered no preset set at
|
| 116 |
-
all. Saying nothing here would leave the panel looking like it failed to load. */}
|
| 117 |
-
{plan.exists && !plan.willUse.length && !plan.willCreate.length ? (
|
| 118 |
-
<p className="auto-note">This server offered no preset columns.</p>
|
| 119 |
-
) : null}
|
| 120 |
-
</div>
|
| 121 |
-
);
|
| 122 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// automation/PresetPlan.tsx β WAVE 25 item 4 (ruling R2b, contract C1):
|
| 3 |
+
// WHICH COLUMNS THIS WILL USE, AND WHICH IT WILL CREATE.
|
| 4 |
+
//
|
| 5 |
+
// The owner's words: *"since this is a global fields all tenant use its really
|
| 6 |
+
// just appending it and adding it to the custom database"* β so the Create
|
| 7 |
+
// record action's configuration has to SHOW the two lists before anything is
|
| 8 |
+
// spent, on whatever database that action names, including a hand-made one.
|
| 9 |
+
//
|
| 10 |
+
// β IT RENDERS THE SERVER'S ANSWER AND COMPUTES NOTHING (C1: "the client
|
| 11 |
+
// renders this; it does not compute it"). Diffing the preset set against a
|
| 12 |
+
// table's columns here would be a second implementation of `ut_ensure`'s merge
|
| 13 |
+
// rule β and it would be wrong exactly when the two lists differ, which is the
|
| 14 |
+
// only case this panel exists to answer.
|
| 15 |
+
//
|
| 16 |
+
// β ITS OWN FILE, AND THAT IS THE BUILDER'S LAW BEING KEPT RATHER THAN BENT.
|
| 17 |
+
// `AutomationBuilder` renders SYNCHRONOUSLY from what it was handed (C14 leg 1
|
| 18 |
+
// β the ghost fix: a view that can be in two shapes shows you the wrong one).
|
| 19 |
+
// This panel genuinely needs a fetch, so it owns one, keeps a FIXED-SHAPE
|
| 20 |
+
// skeleton while it is in flight, and never changes the shape of anything above
|
| 21 |
+
// it. Exactly the split the Board already makes.
|
| 22 |
+
// ---------------------------------------------------------------------------
|
| 23 |
+
import { useEffect, useState } from "react";
|
| 24 |
+
|
| 25 |
+
import { getPresetPlan } from "./automationApi";
|
| 26 |
+
import type { PresetPlan as Plan } from "./automationApi";
|
| 27 |
+
|
| 28 |
+
type Load =
|
| 29 |
+
| { phase: "idle" }
|
| 30 |
+
| { phase: "loading" }
|
| 31 |
+
| { phase: "ready"; plan: Plan }
|
| 32 |
+
| { phase: "error" };
|
| 33 |
+
|
| 34 |
+
/**
|
| 35 |
+
* β ONE LINE PER LIST, NOT A TOUR (DESIGN.md 4 / R13). The panel says what will happen and shows
|
| 36 |
+
* the column names; it does not explain what a preset is, why the set is shared across tenants,
|
| 37 |
+
* or what enrichment does. Each of those has a home β the action's own `detail`, the field's grey
|
| 38 |
+
* machine-owned mark, the run log β and repeating them here is the paragraph nobody reads.
|
| 39 |
+
*/
|
| 40 |
+
function List({ title, fields }: { title: string; fields: Plan["fields"] }) {
|
| 41 |
+
if (!fields.length) return null;
|
| 42 |
+
return (
|
| 43 |
+
<div className="autox-preset-list">
|
| 44 |
+
<p className="autox-preset-head">
|
| 45 |
+
{title} <span className="autox-preset-n">{fields.length}</span>
|
| 46 |
+
</p>
|
| 47 |
+
<div className="autox-preset-chips">
|
| 48 |
+
{fields.map((f) => (
|
| 49 |
+
<span className="autox-preset-chip" key={f.key} title={`${f.key} Β· ${f.type}`}>
|
| 50 |
+
{f.label}
|
| 51 |
+
</span>
|
| 52 |
+
))}
|
| 53 |
+
</div>
|
| 54 |
+
</div>
|
| 55 |
+
);
|
| 56 |
+
}
|
| 57 |
+
|
| 58 |
+
export default function PresetPlan({ table }: { table: string }) {
|
| 59 |
+
const [load, setLoad] = useState<Load>({ phase: "idle" });
|
| 60 |
+
|
| 61 |
+
useEffect(() => {
|
| 62 |
+
if (!table) {
|
| 63 |
+
setLoad({ phase: "idle" });
|
| 64 |
+
return;
|
| 65 |
+
}
|
| 66 |
+
const ac = new AbortController();
|
| 67 |
+
setLoad({ phase: "loading" });
|
| 68 |
+
getPresetPlan(table, ac.signal)
|
| 69 |
+
.then((plan) => setLoad({ phase: "ready", plan }))
|
| 70 |
+
.catch((e) => {
|
| 71 |
+
if ((e as Error)?.name === "AbortError") return;
|
| 72 |
+
setLoad({ phase: "error" });
|
| 73 |
+
});
|
| 74 |
+
return () => ac.abort();
|
| 75 |
+
}, [table]);
|
| 76 |
+
|
| 77 |
+
// β NO DATABASE, NO CLAIM. With nothing chosen there is no question to answer, so this renders
|
| 78 |
+
// nothing at all rather than an empty heading β a heading over nothing says "there should be
|
| 79 |
+
// something here", which is a different and false statement (R13, and the same reasoning R14
|
| 80 |
+
// applies to the whole Configuration section).
|
| 81 |
+
if (!table || load.phase === "idle") return null;
|
| 82 |
+
|
| 83 |
+
if (load.phase === "loading") {
|
| 84 |
+
return (
|
| 85 |
+
<p className="auto-note" role="status">
|
| 86 |
+
<span className="lp-spin" aria-label="Loading" />
|
| 87 |
+
</p>
|
| 88 |
+
);
|
| 89 |
+
}
|
| 90 |
+
|
| 91 |
+
// β HONEST, AND IT DOES NOT GUESS. A failed fetch is not "no columns will be created" β that
|
| 92 |
+
// would be a specific, checkable claim about the user's database, invented to keep a panel
|
| 93 |
+
// tidy ([[no-unverifiable-aggregates]]). It says the server did not answer.
|
| 94 |
+
if (load.phase === "error") {
|
| 95 |
+
return <p className="auto-note">Could not read this database's columns just now.</p>;
|
| 96 |
+
}
|
| 97 |
+
|
| 98 |
+
const { plan } = load;
|
| 99 |
+
return (
|
| 100 |
+
<div className="autox-preset">
|
| 101 |
+
{/*
|
| 102 |
+
β THREE STATES, AND THE FIRST TWO ARE DIFFERENT FACTS. A database that does not exist yet
|
| 103 |
+
(R10's spawn-on-save moment β the action names a table nobody has made) is not the same as
|
| 104 |
+
one that exists and shares none of the columns, even though both render an empty "already
|
| 105 |
+
here" list. The server answers `exists` precisely so this line does not have to infer it
|
| 106 |
+
from a length.
|
| 107 |
+
*/}
|
| 108 |
+
{!plan.exists ? (
|
| 109 |
+
<p className="auto-hint">
|
| 110 |
+
This database does not exist yet. Saving makes it, with these columns.
|
| 111 |
+
</p>
|
| 112 |
+
) : null}
|
| 113 |
+
<List title="Already in this database" fields={plan.willUse} />
|
| 114 |
+
<List title="Will be created" fields={plan.willCreate} />
|
| 115 |
+
{/* Both lists empty on a table that DOES exist means the server offered no preset set at
|
| 116 |
+
all. Saying nothing here would leave the panel looking like it failed to load. */}
|
| 117 |
+
{plan.exists && !plan.willUse.length && !plan.willCreate.length ? (
|
| 118 |
+
<p className="auto-note">This server offered no preset columns.</p>
|
| 119 |
+
) : null}
|
| 120 |
+
</div>
|
| 121 |
+
);
|
| 122 |
+
}
|
web/src/automation/automation.css
CHANGED
|
@@ -1,559 +1,559 @@
|
|
| 1 |
-
/* ---------------------------------------------------------------------------
|
| 2 |
-
automation/automation.css β the Agent module's OWN stylesheet.
|
| 3 |
-
|
| 4 |
-
ββ WAVE 34 Β· W34-T41 β THIS FILE IS NEW, AND ITS EXISTENCE IS THE POINT.
|
| 5 |
-
|
| 6 |
-
Until today this module had NO scoped CSS at all: every `auto-*`, `autob-*` and `autox-*` rule
|
| 7 |
-
lived in the shared global `src/index.css`, which the wave PRD assigns to session C. That made
|
| 8 |
-
any new rule here a cross-fence ask, for styling nobody else can see β the PRD's own remedy is
|
| 9 |
-
"put NEW rules in your own module stylesheet (`automation/*.css`)", and this is that file.
|
| 10 |
-
|
| 11 |
-
β WHAT DOES NOT BELONG HERE: an edit to an existing `auto-*` rule. Those still live in
|
| 12 |
-
`index.css` and are still C's. This file holds rules that did not exist before, so the two can
|
| 13 |
-
never disagree about one selector.
|
| 14 |
-
|
| 15 |
-
β EVERY COLOUR IS A TOKEN. No literal hex, for the reason the palette block in `index.css`
|
| 16 |
-
records: a hand-copied brand value silently paints last wave's brand while a comment asserts
|
| 17 |
-
parity. Light and dark both come free that way.
|
| 18 |
-
--------------------------------------------------------------------------- */
|
| 19 |
-
|
| 20 |
-
/* ββ the Chat view (R17) ββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 21 |
-
|
| 22 |
-
/* Mirrors `.autox-flow`'s box so switching Canvas <-> Chat does not move the frame around it:
|
| 23 |
-
same flex growth, same min-height:0 (without which a scrolling child of a flex parent grows
|
| 24 |
-
the parent instead of scrolling), same scroll ownership. */
|
| 25 |
-
.autoc-chat {
|
| 26 |
-
flex: 1 1 auto;
|
| 27 |
-
min-width: 0;
|
| 28 |
-
min-height: 0;
|
| 29 |
-
display: flex;
|
| 30 |
-
flex-direction: column;
|
| 31 |
-
}
|
| 32 |
-
|
| 33 |
-
.autoc-log {
|
| 34 |
-
flex: 1 1 auto;
|
| 35 |
-
min-height: 0;
|
| 36 |
-
overflow-y: auto;
|
| 37 |
-
padding: 20px 24px 12px;
|
| 38 |
-
display: flex;
|
| 39 |
-
flex-direction: column;
|
| 40 |
-
gap: 14px;
|
| 41 |
-
}
|
| 42 |
-
|
| 43 |
-
/* β `.autoc-empty` STOOD HERE AND WAS DELETED WITH ITS ONLY USER (W36-T30, owner item 4). A rule
|
| 44 |
-
whose class no longer appears in any .tsx is dead weight the next reader has to prove is dead,
|
| 45 |
-
which is why the tombstone is cheaper than the rule. W36-T33's rebuilt empty state gets its own. */
|
| 46 |
-
|
| 47 |
-
.autoc-msg {
|
| 48 |
-
max-width: 60ch;
|
| 49 |
-
padding: 10px 14px;
|
| 50 |
-
border-radius: var(--lp-r-md);
|
| 51 |
-
font-size: var(--lp-fs-sm);
|
| 52 |
-
line-height: 1.5;
|
| 53 |
-
white-space: pre-wrap;
|
| 54 |
-
overflow-wrap: anywhere;
|
| 55 |
-
}
|
| 56 |
-
.autoc-msg.is-you {
|
| 57 |
-
align-self: flex-end;
|
| 58 |
-
background: var(--lp-surface-2);
|
| 59 |
-
color: var(--lp-ink);
|
| 60 |
-
}
|
| 61 |
-
.autoc-msg.is-agent {
|
| 62 |
-
align-self: flex-start;
|
| 63 |
-
border: 1px solid var(--lp-line);
|
| 64 |
-
color: var(--lp-ink);
|
| 65 |
-
}
|
| 66 |
-
/* β A FAILED TURN IS A MESSAGE, NOT A TOAST. A toast is gone before a reader has finished the
|
| 67 |
-
sentence, and this surface's failures are things you act on (rephrase, pick a database).
|
| 68 |
-
β `--lp-red-deep` / `--lp-red-tint`, CHECKED AGAINST THE PALETTE, not typed from memory: the
|
| 69 |
-
first draft of this rule used `--lp-danger` and `--lp-danger-line`, and NEITHER EXISTS. A ghost
|
| 70 |
-
custom property does not fail loudly β it falls back or inherits β so the error message would
|
| 71 |
-
have painted in ordinary ink and looked like an answer. Same defect T14 caught on
|
| 72 |
-
`--lp-ink-muted` in the same wave; the palette is the only source worth trusting. */
|
| 73 |
-
.autoc-msg.is-error {
|
| 74 |
-
align-self: flex-start;
|
| 75 |
-
border: 1px solid var(--lp-red);
|
| 76 |
-
background: var(--lp-red-tint);
|
| 77 |
-
color: var(--lp-red-deep);
|
| 78 |
-
}
|
| 79 |
-
|
| 80 |
-
/* What the model asked for and the validator would not keep. β It renders as ORDINARY content,
|
| 81 |
-
not as a warning ornament: R6's standing rule is that a limit must be REPORTED, and a report
|
| 82 |
-
nobody reads because it looks like chrome is the same as no report. */
|
| 83 |
-
.autoc-dropped {
|
| 84 |
-
align-self: flex-start;
|
| 85 |
-
max-width: 60ch;
|
| 86 |
-
margin: 0;
|
| 87 |
-
padding: 8px 12px;
|
| 88 |
-
border-left: 2px solid var(--lp-line);
|
| 89 |
-
color: var(--lp-muted);
|
| 90 |
-
font-size: var(--lp-fs-xs);
|
| 91 |
-
line-height: 1.5;
|
| 92 |
-
}
|
| 93 |
-
.autoc-dropped ul { margin: 4px 0 0; padding-left: 18px; }
|
| 94 |
-
|
| 95 |
-
/* ββ W36-T33 β THE COMPOSER IS THE ASSISTANT'S, IN THIS MODULE'S NAMES.
|
| 96 |
-
Owner: *"Just as good as the Assistant module."* The done-when is a comparison, so these rules
|
| 97 |
-
mirror `assistant/assistant.css`'s `.as-field` / `.as-prompt` / `.as-field-foot` / `.as-send`
|
| 98 |
-
on the SAME TOKENS. Not `@extend`, not a shared class: `.as-*` belongs to the Assistant's
|
| 99 |
-
stylesheet and reaching into it would make one surface's restyle silently repaint the other.
|
| 100 |
-
β WHAT MUST NOT DRIFT is the pair of numbers that carry the shape β the 22px pill radius and
|
| 101 |
-
the field's shadow β because those are what the eye compares. Both are matched BY VALUE from
|
| 102 |
-
`.as-field`, and the shadow is a literal because THIS PRODUCT HAS NO SHADOW TOKEN: `index.css`
|
| 103 |
-
records that finding in as many words beside `.autoc-bigedit`, where naming a shadow token that
|
| 104 |
-
does not exist would have quietly rendered its own fallback while looking like a token was
|
| 105 |
-
being honoured.
|
| 106 |
-
β AND THAT SENTENCE USED TO NAME THE TOKEN, WHICH BROKE THE GATE THAT READS THIS FILE. R17's
|
| 107 |
-
"every token the new stylesheet uses is DEFINED in the palette" scans the raw text, comments
|
| 108 |
-
included, so quoting `var(--β¦)` in prose counts as USING it: the citation reddened the check
|
| 109 |
-
[[prose-that-becomes-its-own-marker]]. Describe a token you are NOT using; never spell it. */
|
| 110 |
-
|
| 111 |
-
/* β NO HAIRLINE ON THE BAND ANY MORE. The card below has its own border, and a rule across the
|
| 112 |
-
pane above it made two edges 12px apart β the "still so ugly" the owner reported is mostly
|
| 113 |
-
this kind of doubling. What separates the composer from the transcript now is whitespace. */
|
| 114 |
-
.autoc-compose {
|
| 115 |
-
flex: 0 0 auto;
|
| 116 |
-
padding: 8px 24px 20px;
|
| 117 |
-
}
|
| 118 |
-
.autoc-field {
|
| 119 |
-
/* ONE measure for the conversation and the empty state, so the composer does not change width
|
| 120 |
-
when the first message lands. `.as-opening .as-composer` caps at the same 700px. */
|
| 121 |
-
max-width: 700px;
|
| 122 |
-
margin: 0 auto;
|
| 123 |
-
border: 1px solid var(--lp-line);
|
| 124 |
-
border-radius: 22px;
|
| 125 |
-
background: var(--lp-surface);
|
| 126 |
-
padding: 10px 8px 8px 16px;
|
| 127 |
-
box-shadow: 0 1px 2px rgba(20, 24, 40, 0.05);
|
| 128 |
-
box-sizing: border-box;
|
| 129 |
-
}
|
| 130 |
-
.autoc-field:focus-within { border-color: var(--lp-blue-solid); }
|
| 131 |
-
|
| 132 |
-
/* β `rows={1}` PLUS `max-height`, which is `.as-prompt`'s shape and not the two-row box that was
|
| 133 |
-
here. A composer that starts tall claims space before anybody has typed; the Assistant's grows
|
| 134 |
-
into the sentence instead. */
|
| 135 |
-
.autoc-input {
|
| 136 |
-
display: block;
|
| 137 |
-
width: 100%;
|
| 138 |
-
max-height: 180px;
|
| 139 |
-
border: 0;
|
| 140 |
-
outline: none;
|
| 141 |
-
padding: 0 8px 0 0;
|
| 142 |
-
background: transparent;
|
| 143 |
-
color: var(--lp-ink);
|
| 144 |
-
font: inherit;
|
| 145 |
-
font-size: var(--lp-fs-sm);
|
| 146 |
-
line-height: var(--lp-lh);
|
| 147 |
-
resize: none;
|
| 148 |
-
box-sizing: border-box;
|
| 149 |
-
}
|
| 150 |
-
.autoc-input::placeholder { color: var(--lp-muted); }
|
| 151 |
-
|
| 152 |
-
/* The row BELOW the input and INSIDE the card β the reference screenshot's arrangement, and the
|
| 153 |
-
slot W36-T34's model toggle drops into beside the send. */
|
| 154 |
-
.autoc-foot {
|
| 155 |
-
display: flex;
|
| 156 |
-
align-items: center;
|
| 157 |
-
gap: 12px;
|
| 158 |
-
margin-top: 8px;
|
| 159 |
-
}
|
| 160 |
-
|
| 161 |
-
.autoc-send {
|
| 162 |
-
flex: 0 0 auto;
|
| 163 |
-
margin-left: auto;
|
| 164 |
-
width: 30px;
|
| 165 |
-
height: 30px;
|
| 166 |
-
display: inline-flex;
|
| 167 |
-
align-items: center;
|
| 168 |
-
justify-content: center;
|
| 169 |
-
border: 0;
|
| 170 |
-
border-radius: 999px;
|
| 171 |
-
background: var(--lp-ink);
|
| 172 |
-
color: var(--lp-surface);
|
| 173 |
-
cursor: pointer;
|
| 174 |
-
}
|
| 175 |
-
.autoc-send svg {
|
| 176 |
-
fill: none;
|
| 177 |
-
stroke: currentColor;
|
| 178 |
-
stroke-width: 1.7;
|
| 179 |
-
stroke-linecap: round;
|
| 180 |
-
stroke-linejoin: round;
|
| 181 |
-
}
|
| 182 |
-
.autoc-send:disabled { background: var(--lp-surface-2); color: var(--lp-muted); cursor: default; }
|
| 183 |
-
.autoc-send:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 1px; }
|
| 184 |
-
|
| 185 |
-
/* ββ the empty state (mirrors `.as-opening`) ββββββββββββββββββββββββββββββββ */
|
| 186 |
-
|
| 187 |
-
.autoc-opening {
|
| 188 |
-
flex: 1 1 auto;
|
| 189 |
-
min-height: 0;
|
| 190 |
-
display: flex;
|
| 191 |
-
flex-direction: column;
|
| 192 |
-
align-items: center;
|
| 193 |
-
justify-content: center;
|
| 194 |
-
padding: 24px;
|
| 195 |
-
box-sizing: border-box;
|
| 196 |
-
text-align: center;
|
| 197 |
-
}
|
| 198 |
-
.autoc-opening-h {
|
| 199 |
-
margin: 0 0 6px;
|
| 200 |
-
color: var(--lp-ink);
|
| 201 |
-
font-size: var(--lp-fs-lg);
|
| 202 |
-
font-weight: 650;
|
| 203 |
-
}
|
| 204 |
-
.autoc-opening-p {
|
| 205 |
-
max-width: 52ch;
|
| 206 |
-
margin: 0 0 20px;
|
| 207 |
-
color: var(--lp-muted);
|
| 208 |
-
font-size: var(--lp-fs-sm);
|
| 209 |
-
line-height: var(--lp-lh);
|
| 210 |
-
}
|
| 211 |
-
/* The composer is left-aligned inside a centred column, exactly as the Assistant's is: centred
|
| 212 |
-
placeholder text in a wide field reads as a search box, not as somewhere to write a sentence. */
|
| 213 |
-
.autoc-opening .autoc-field { width: 100%; text-align: left; }
|
| 214 |
-
|
| 215 |
-
/* The pending row. β It uses `.lp-spin`, the ONE loading mark app-wide (purple as of this wave's
|
| 216 |
-
T24) β a second spinner vocabulary in a new surface is how an app stops having one. */
|
| 217 |
-
.autoc-pending {
|
| 218 |
-
display: flex;
|
| 219 |
-
align-items: center;
|
| 220 |
-
gap: 8px;
|
| 221 |
-
align-self: flex-start;
|
| 222 |
-
color: var(--lp-muted);
|
| 223 |
-
font-size: var(--lp-fs-sm);
|
| 224 |
-
}
|
| 225 |
-
|
| 226 |
-
/* The accept bar. It is deliberately NOT inside the transcript: accepting is an act on the
|
| 227 |
-
AUTOMATION, not a reply in the conversation, and putting it in the log would make it scroll
|
| 228 |
-
away from the thing it acts on. */
|
| 229 |
-
.autoc-accept {
|
| 230 |
-
flex: 0 0 auto;
|
| 231 |
-
display: flex;
|
| 232 |
-
align-items: center;
|
| 233 |
-
gap: 10px;
|
| 234 |
-
padding: 10px 24px;
|
| 235 |
-
border-top: 1px solid var(--lp-line);
|
| 236 |
-
background: var(--lp-surface-2);
|
| 237 |
-
font-size: var(--lp-fs-sm);
|
| 238 |
-
}
|
| 239 |
-
.autoc-accept-note { color: var(--lp-muted); margin-right: auto; }
|
| 240 |
-
|
| 241 |
-
/* ββ the run log's note disclosure (R21 / W34-T45) ββββββββββββββββββββββββββ */
|
| 242 |
-
|
| 243 |
-
/* β WAVE 34 Β· W34-T45. `notes` is up to 300 chars x 25 entries per run and was rendered
|
| 244 |
-
unconditionally over 20 runs; that is the "too wordy" the owner reported. It is still
|
| 245 |
-
unconditional for a run that FAILED or hit a cap (R6: a limit must be REPORTED) and behind this
|
| 246 |
-
disclosure otherwise.
|
| 247 |
-
β The list INSIDE stays `.auto-run-notes`, which is C's existing rule in `index.css`. Only the
|
| 248 |
-
wrapper is new, so the notes themselves cannot start looking different depending on which
|
| 249 |
-
branch rendered them. */
|
| 250 |
-
.autor-notes {
|
| 251 |
-
margin: 2px 0 0;
|
| 252 |
-
}
|
| 253 |
-
.autor-notes-toggle {
|
| 254 |
-
cursor: pointer;
|
| 255 |
-
color: var(--lp-muted);
|
| 256 |
-
font-size: var(--lp-fs-2xs);
|
| 257 |
-
/* The default triangle is the affordance; no custom marker, because a disclosure that does not
|
| 258 |
-
look like one is how a person decides there is nothing behind it. */
|
| 259 |
-
list-style: revert;
|
| 260 |
-
}
|
| 261 |
-
.autor-notes-toggle:hover { color: var(--lp-ink); }
|
| 262 |
-
.autor-notes-toggle:focus-visible {
|
| 263 |
-
outline: 2px solid var(--lp-blue-deep);
|
| 264 |
-
outline-offset: 1px;
|
| 265 |
-
}
|
| 266 |
-
|
| 267 |
-
/* ββ the parked statements batch (W35-T36 / owner ruling R10) βββββββββββββββ */
|
| 268 |
-
|
| 269 |
-
/* ββ "N STATEMENTS ARE READY", with the ONLY Send control in the product.
|
| 270 |
-
It sits above `.auto-work`, in the banner band, because it is the one thing on this agent that
|
| 271 |
-
needs a person β R10's whole shape is that the run assembles and PARKS, and somebody releases.
|
| 272 |
-
|
| 273 |
-
β IT IS DELIBERATELY NOT A WARNING COLOUR. A parked batch is the system working as designed, and
|
| 274 |
-
painting it amber would teach people to dismiss the panel that guards a real mail send. It is
|
| 275 |
-
the blue tint every other "here is something to look at" surface uses. */
|
| 276 |
-
.auto-batch {
|
| 277 |
-
flex: 0 0 auto;
|
| 278 |
-
margin: 12px 24px 0;
|
| 279 |
-
padding: 12px 14px;
|
| 280 |
-
border: 1px solid var(--lp-blue);
|
| 281 |
-
border-radius: var(--lp-r-md);
|
| 282 |
-
background: var(--lp-blue-tint);
|
| 283 |
-
font-size: var(--lp-fs-sm);
|
| 284 |
-
}
|
| 285 |
-
.auto-batch-head {
|
| 286 |
-
display: flex;
|
| 287 |
-
align-items: baseline;
|
| 288 |
-
flex-wrap: wrap;
|
| 289 |
-
gap: 4px 10px;
|
| 290 |
-
}
|
| 291 |
-
.auto-batch-count {
|
| 292 |
-
font-weight: 650;
|
| 293 |
-
color: var(--lp-ink);
|
| 294 |
-
}
|
| 295 |
-
.auto-batch-note { color: var(--lp-muted); }
|
| 296 |
-
|
| 297 |
-
/* The guardrail line. Same size as a note, because it IS one: the data layer decides, this
|
| 298 |
-
reports (R6's second sentence). */
|
| 299 |
-
.auto-batch-safe,
|
| 300 |
-
.auto-batch-line {
|
| 301 |
-
margin: 6px 0 0;
|
| 302 |
-
color: var(--lp-muted);
|
| 303 |
-
font-size: var(--lp-fs-xs);
|
| 304 |
-
line-height: 1.5;
|
| 305 |
-
max-width: 70ch;
|
| 306 |
-
}
|
| 307 |
-
|
| 308 |
-
/* Who is about to be emailed. β Bounded in the MARKUP at 8 rows with an "and N more" line rather
|
| 309 |
-
than scrolled here: a 200-row list inside a banner pushes the work area off the screen, and the
|
| 310 |
-
panel's job is to say who and how many, not to be the worklist. */
|
| 311 |
-
.auto-batch-list {
|
| 312 |
-
margin: 8px 0 0;
|
| 313 |
-
padding: 0;
|
| 314 |
-
list-style: none;
|
| 315 |
-
display: flex;
|
| 316 |
-
flex-direction: column;
|
| 317 |
-
gap: 2px;
|
| 318 |
-
font-size: var(--lp-fs-xs);
|
| 319 |
-
}
|
| 320 |
-
.auto-batch-list li {
|
| 321 |
-
display: flex;
|
| 322 |
-
gap: 10px;
|
| 323 |
-
align-items: baseline;
|
| 324 |
-
}
|
| 325 |
-
.auto-batch-cust { color: var(--lp-ink); }
|
| 326 |
-
.auto-batch-to { color: var(--lp-muted); overflow-wrap: anywhere; }
|
| 327 |
-
.auto-batch-more { color: var(--lp-muted); }
|
| 328 |
-
|
| 329 |
-
.auto-batch-actions {
|
| 330 |
-
margin-top: 10px;
|
| 331 |
-
display: flex;
|
| 332 |
-
gap: 8px;
|
| 333 |
-
}
|
| 334 |
-
|
| 335 |
-
/* ββ W36-T44 (D-316 + D-299): the statements step's config panel βββββββββββββ */
|
| 336 |
-
|
| 337 |
-
/* NEW rules only, in this module's own stylesheet. Every `auto-*` rule the panel reuses
|
| 338 |
-
(`auto-field`, `auto-input`, `auto-hint`, `auto-note`, `auto-btn`) still lives in the shared
|
| 339 |
-
`index.css` and is still another lane's, so nothing here redefines one. */
|
| 340 |
-
|
| 341 |
-
/* The two action rows (Preview, Send one test). A row rather than a bare button so the two read
|
| 342 |
-
as the same kind of control at the same left edge as every field above them. */
|
| 343 |
-
.autox-stmt-row {
|
| 344 |
-
display: flex;
|
| 345 |
-
gap: 8px;
|
| 346 |
-
margin: 0 0 14px;
|
| 347 |
-
}
|
| 348 |
-
|
| 349 |
-
.autox-stmt-shot {
|
| 350 |
-
margin: 0 0 14px;
|
| 351 |
-
border: 1px solid var(--lp-line);
|
| 352 |
-
border-radius: var(--lp-r-md);
|
| 353 |
-
padding: 10px 12px;
|
| 354 |
-
background: var(--lp-surface-2);
|
| 355 |
-
}
|
| 356 |
-
.autox-stmt-shot .auto-hint {
|
| 357 |
-
margin: 0 0 8px;
|
| 358 |
-
overflow-wrap: anywhere;
|
| 359 |
-
}
|
| 360 |
-
|
| 361 |
-
/* β A FIXED HEIGHT, AND IT SCROLLS INSIDE ITSELF. A statement for a customer with forty open
|
| 362 |
-
invoices is a long document, and a preview that grows to its content pushes the test-send
|
| 363 |
-
control below it off the panel: the one thing somebody must reach after reading a preview.
|
| 364 |
-
|
| 365 |
-
β AND THE LITERAL WHITE IS THE ONE DELIBERATE EXCEPTION TO THIS FILE'S "every colour is a
|
| 366 |
-
token" RULE, booked here rather than left to read as an oversight. What is inside this frame is
|
| 367 |
-
not our chrome, it is the EMAIL: `render_statement_html` hard-codes #1F4E78 headers, #e3e8ef
|
| 368 |
-
rules and near-black body text against an assumed white page, and the recipient's mail client
|
| 369 |
-
will paint it on white whatever this app's theme is. A surface token would go dark in dark mode
|
| 370 |
-
and render the real mail's dark text on a dark ground, so the preview would stop showing what
|
| 371 |
-
goes out at exactly the moment somebody is checking what goes out. */
|
| 372 |
-
.autox-stmt-frame {
|
| 373 |
-
display: block;
|
| 374 |
-
width: 100%;
|
| 375 |
-
height: 260px;
|
| 376 |
-
border: 1px solid var(--lp-line);
|
| 377 |
-
border-radius: var(--lp-r-sm);
|
| 378 |
-
background: #fff;
|
| 379 |
-
}
|
| 380 |
-
|
| 381 |
-
/* ββ W36-T31 (owner item 3, R7/R8, contract C4): the Harness tab βββββββββββββ */
|
| 382 |
-
|
| 383 |
-
/* NEW rules only. Everything shared (`auto-field`, `auto-input`, `auto-btn`, `auto-note`,
|
| 384 |
-
`auto-hint`, `auto-paneltab*`) still lives in `index.css` and is still another lane's. */
|
| 385 |
-
|
| 386 |
-
.autoh-wrap {
|
| 387 |
-
display: flex;
|
| 388 |
-
flex-direction: column;
|
| 389 |
-
gap: 4px;
|
| 390 |
-
}
|
| 391 |
-
|
| 392 |
-
.autoh-files {
|
| 393 |
-
margin: 0 0 14px;
|
| 394 |
-
padding: 0;
|
| 395 |
-
list-style: none;
|
| 396 |
-
display: flex;
|
| 397 |
-
flex-direction: column;
|
| 398 |
-
gap: 2px;
|
| 399 |
-
}
|
| 400 |
-
.autoh-file {
|
| 401 |
-
display: flex;
|
| 402 |
-
align-items: center;
|
| 403 |
-
gap: 6px;
|
| 404 |
-
border-radius: var(--lp-r-sm);
|
| 405 |
-
}
|
| 406 |
-
.autoh-file.is-on { background: var(--lp-blue-tint); }
|
| 407 |
-
|
| 408 |
-
/* The row is a BUTTON, so the whole line opens the file. A path that is only clickable on its
|
| 409 |
-
own glyph-width is a target people miss and then decide is not clickable at all. */
|
| 410 |
-
.autoh-open {
|
| 411 |
-
flex: 1 1 auto;
|
| 412 |
-
min-width: 0;
|
| 413 |
-
display: flex;
|
| 414 |
-
flex-direction: column;
|
| 415 |
-
gap: 1px;
|
| 416 |
-
padding: 5px 8px;
|
| 417 |
-
border: 0;
|
| 418 |
-
border-radius: var(--lp-r-sm);
|
| 419 |
-
background: transparent;
|
| 420 |
-
color: var(--lp-ink);
|
| 421 |
-
font: inherit;
|
| 422 |
-
text-align: left;
|
| 423 |
-
cursor: pointer;
|
| 424 |
-
}
|
| 425 |
-
.autoh-open:hover:not(:disabled) { background: var(--lp-surface-2); }
|
| 426 |
-
.autoh-open:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
|
| 427 |
-
.autoh-open:disabled { cursor: default; }
|
| 428 |
-
|
| 429 |
-
/* β `anywhere`, not `ellipsis`: a harness path is `skills/router.md`, and the half that
|
| 430 |
-
identifies it is the END. Truncating from the right hides exactly the distinguishing part. */
|
| 431 |
-
.autoh-path {
|
| 432 |
-
font-size: var(--lp-fs-sm);
|
| 433 |
-
font-weight: 600;
|
| 434 |
-
overflow-wrap: anywhere;
|
| 435 |
-
}
|
| 436 |
-
.autoh-meta {
|
| 437 |
-
color: var(--lp-muted);
|
| 438 |
-
font-size: var(--lp-fs-2xs);
|
| 439 |
-
overflow-wrap: anywhere;
|
| 440 |
-
}
|
| 441 |
-
|
| 442 |
-
/* Quiet until reached for. Deleting a file is a real act (it takes the history with it), so it is
|
| 443 |
-
present and honest rather than hidden, but it does not compete with opening one. */
|
| 444 |
-
.autoh-drop {
|
| 445 |
-
flex: 0 0 auto;
|
| 446 |
-
opacity: 0.55;
|
| 447 |
-
}
|
| 448 |
-
.autoh-file:hover .autoh-drop,
|
| 449 |
-
.autoh-drop:focus-visible { opacity: 1; }
|
| 450 |
-
|
| 451 |
-
.autoh-newrow {
|
| 452 |
-
display: flex;
|
| 453 |
-
gap: 6px;
|
| 454 |
-
align-items: center;
|
| 455 |
-
}
|
| 456 |
-
|
| 457 |
-
/* Monospace, because a harness file is a router or a skill: its indentation carries meaning and a
|
| 458 |
-
proportional font makes a misaligned block look aligned.
|
| 459 |
-
β THE FACE COMES FROM `.auto-input.is-mono`, WHICH THE TEXTAREA ALSO CARRIES, and this rule sets
|
| 460 |
-
no `font-family` at all. `index.css:12591` records why in as many words: there IS no `--lp-mono`
|
| 461 |
-
token, six sites spell the stack out, and a seventh copy here would put the product's mono face
|
| 462 |
-
in two places that can drift. `WebActionConfig` reaches for the same class. */
|
| 463 |
-
.autoh-body {
|
| 464 |
-
font-size: var(--lp-fs-xs);
|
| 465 |
-
line-height: 1.55;
|
| 466 |
-
resize: vertical;
|
| 467 |
-
}
|
| 468 |
-
|
| 469 |
-
.autoh-actions {
|
| 470 |
-
display: flex;
|
| 471 |
-
gap: 8px;
|
| 472 |
-
margin: 0 0 14px;
|
| 473 |
-
}
|
| 474 |
-
|
| 475 |
-
.autoh-history {
|
| 476 |
-
margin: 0 0 8px;
|
| 477 |
-
padding: 0;
|
| 478 |
-
list-style: none;
|
| 479 |
-
display: flex;
|
| 480 |
-
flex-direction: column;
|
| 481 |
-
gap: 1px;
|
| 482 |
-
}
|
| 483 |
-
.autoh-history li { border-radius: var(--lp-r-sm); }
|
| 484 |
-
.autoh-history li.is-on { background: var(--lp-blue-tint); }
|
| 485 |
-
.autoh-version {
|
| 486 |
-
width: 100%;
|
| 487 |
-
display: flex;
|
| 488 |
-
gap: 8px;
|
| 489 |
-
align-items: baseline;
|
| 490 |
-
padding: 4px 8px;
|
| 491 |
-
border: 0;
|
| 492 |
-
border-radius: var(--lp-r-sm);
|
| 493 |
-
background: transparent;
|
| 494 |
-
color: var(--lp-ink);
|
| 495 |
-
font: inherit;
|
| 496 |
-
text-align: left;
|
| 497 |
-
cursor: pointer;
|
| 498 |
-
}
|
| 499 |
-
.autoh-version:hover:not(:disabled) { background: var(--lp-surface-2); }
|
| 500 |
-
.autoh-version:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
|
| 501 |
-
.autoh-version:disabled { cursor: default; }
|
| 502 |
-
.autoh-vnum {
|
| 503 |
-
flex: 0 0 auto;
|
| 504 |
-
font-size: var(--lp-fs-xs);
|
| 505 |
-
font-weight: 650;
|
| 506 |
-
}
|
| 507 |
-
|
| 508 |
-
/* The unsaved-edit hold. A bordered block rather than a tint, because it is a QUESTION waiting on
|
| 509 |
-
an answer and the two buttons under it are the answer; a tinted note reads as commentary. */
|
| 510 |
-
.autoh-hold {
|
| 511 |
-
margin: 0 0 14px;
|
| 512 |
-
padding: 10px 12px;
|
| 513 |
-
border: 1px solid var(--lp-line);
|
| 514 |
-
border-radius: var(--lp-r-md);
|
| 515 |
-
background: var(--lp-surface-2);
|
| 516 |
-
}
|
| 517 |
-
.autoh-hold .auto-note { margin-top: 0; }
|
| 518 |
-
|
| 519 |
-
/* ββ W36-T32 (owner item 3, R7): the right rail folds behind a "III" βββββββββ */
|
| 520 |
-
|
| 521 |
-
/* β THE FOLD SITS AT THE RAIL'S OWN LEFT EDGE, AND `flex-start` IS ONLY HALF OF WHY.
|
| 522 |
-
W35-T11 put the left rails' fold at their left edge; this rail is on the RIGHT, so its left
|
| 523 |
-
edge is the one facing the chat it widens. `.auto-panel-head` is `space-between` and lives in
|
| 524 |
-
`index.css` (another lane's), so this wrapper is what keeps the fold and the tabs together
|
| 525 |
-
instead of flung to the panel's two edges.
|
| 526 |
-
ββ AND NOTHING IN HERE MAY EVER CARRY `margin-left: auto`. W35-T28's real finding was that a
|
| 527 |
-
sibling's auto margin ate the free space BEFORE `justify-content` applied, so one control sat
|
| 528 |
-
left on one database and right on another: one control, two positions, decided by data. */
|
| 529 |
-
.autod-head {
|
| 530 |
-
flex: 1 1 auto;
|
| 531 |
-
min-width: 0;
|
| 532 |
-
display: flex;
|
| 533 |
-
align-items: center;
|
| 534 |
-
justify-content: flex-start;
|
| 535 |
-
gap: 10px;
|
| 536 |
-
}
|
| 537 |
-
|
| 538 |
-
/* The collapsed rail. Same width token and the same idea as `.auto-rail.is-collapsed` on the
|
| 539 |
-
left of this screen: folding a rail leaves a strip, never a gap, because the strip is where the
|
| 540 |
-
way back lives. */
|
| 541 |
-
.autod-shut {
|
| 542 |
-
flex: 0 0 auto;
|
| 543 |
-
width: var(--lp-rail-min);
|
| 544 |
-
display: flex;
|
| 545 |
-
justify-content: center;
|
| 546 |
-
padding: 14px 6px 0;
|
| 547 |
-
border-left: 1px solid var(--lp-line);
|
| 548 |
-
background: var(--lp-surface);
|
| 549 |
-
}
|
| 550 |
-
|
| 551 |
-
/* β THE FOLD, IN ONE PLACE. Every `.auto-panel` in the work area goes at once β Properties (a
|
| 552 |
-
child of AutomationBuilder), Harness and Run history (children of AutomationDetail) β so a
|
| 553 |
-
panel added later folds without being told to. `display: none` also removes them from the
|
| 554 |
-
accessibility tree, which is the property `hidden` was giving us and the reason a `visibility`
|
| 555 |
-
or `width: 0` treatment would be a regression a screen reader would meet and nobody would see. */
|
| 556 |
-
.autod-folded .auto-panel { display: none; }
|
| 557 |
|
| 558 |
/* ββ W36-T34 (owner item 3, R4, contract C5): the model toggle βββββββββββββββ */
|
| 559 |
|
|
|
|
| 1 |
+
/* ---------------------------------------------------------------------------
|
| 2 |
+
automation/automation.css β the Agent module's OWN stylesheet.
|
| 3 |
+
|
| 4 |
+
ββ WAVE 34 Β· W34-T41 β THIS FILE IS NEW, AND ITS EXISTENCE IS THE POINT.
|
| 5 |
+
|
| 6 |
+
Until today this module had NO scoped CSS at all: every `auto-*`, `autob-*` and `autox-*` rule
|
| 7 |
+
lived in the shared global `src/index.css`, which the wave PRD assigns to session C. That made
|
| 8 |
+
any new rule here a cross-fence ask, for styling nobody else can see β the PRD's own remedy is
|
| 9 |
+
"put NEW rules in your own module stylesheet (`automation/*.css`)", and this is that file.
|
| 10 |
+
|
| 11 |
+
β WHAT DOES NOT BELONG HERE: an edit to an existing `auto-*` rule. Those still live in
|
| 12 |
+
`index.css` and are still C's. This file holds rules that did not exist before, so the two can
|
| 13 |
+
never disagree about one selector.
|
| 14 |
+
|
| 15 |
+
β EVERY COLOUR IS A TOKEN. No literal hex, for the reason the palette block in `index.css`
|
| 16 |
+
records: a hand-copied brand value silently paints last wave's brand while a comment asserts
|
| 17 |
+
parity. Light and dark both come free that way.
|
| 18 |
+
--------------------------------------------------------------------------- */
|
| 19 |
+
|
| 20 |
+
/* ββ the Chat view (R17) ββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 21 |
+
|
| 22 |
+
/* Mirrors `.autox-flow`'s box so switching Canvas <-> Chat does not move the frame around it:
|
| 23 |
+
same flex growth, same min-height:0 (without which a scrolling child of a flex parent grows
|
| 24 |
+
the parent instead of scrolling), same scroll ownership. */
|
| 25 |
+
.autoc-chat {
|
| 26 |
+
flex: 1 1 auto;
|
| 27 |
+
min-width: 0;
|
| 28 |
+
min-height: 0;
|
| 29 |
+
display: flex;
|
| 30 |
+
flex-direction: column;
|
| 31 |
+
}
|
| 32 |
+
|
| 33 |
+
.autoc-log {
|
| 34 |
+
flex: 1 1 auto;
|
| 35 |
+
min-height: 0;
|
| 36 |
+
overflow-y: auto;
|
| 37 |
+
padding: 20px 24px 12px;
|
| 38 |
+
display: flex;
|
| 39 |
+
flex-direction: column;
|
| 40 |
+
gap: 14px;
|
| 41 |
+
}
|
| 42 |
+
|
| 43 |
+
/* β `.autoc-empty` STOOD HERE AND WAS DELETED WITH ITS ONLY USER (W36-T30, owner item 4). A rule
|
| 44 |
+
whose class no longer appears in any .tsx is dead weight the next reader has to prove is dead,
|
| 45 |
+
which is why the tombstone is cheaper than the rule. W36-T33's rebuilt empty state gets its own. */
|
| 46 |
+
|
| 47 |
+
.autoc-msg {
|
| 48 |
+
max-width: 60ch;
|
| 49 |
+
padding: 10px 14px;
|
| 50 |
+
border-radius: var(--lp-r-md);
|
| 51 |
+
font-size: var(--lp-fs-sm);
|
| 52 |
+
line-height: 1.5;
|
| 53 |
+
white-space: pre-wrap;
|
| 54 |
+
overflow-wrap: anywhere;
|
| 55 |
+
}
|
| 56 |
+
.autoc-msg.is-you {
|
| 57 |
+
align-self: flex-end;
|
| 58 |
+
background: var(--lp-surface-2);
|
| 59 |
+
color: var(--lp-ink);
|
| 60 |
+
}
|
| 61 |
+
.autoc-msg.is-agent {
|
| 62 |
+
align-self: flex-start;
|
| 63 |
+
border: 1px solid var(--lp-line);
|
| 64 |
+
color: var(--lp-ink);
|
| 65 |
+
}
|
| 66 |
+
/* β A FAILED TURN IS A MESSAGE, NOT A TOAST. A toast is gone before a reader has finished the
|
| 67 |
+
sentence, and this surface's failures are things you act on (rephrase, pick a database).
|
| 68 |
+
β `--lp-red-deep` / `--lp-red-tint`, CHECKED AGAINST THE PALETTE, not typed from memory: the
|
| 69 |
+
first draft of this rule used `--lp-danger` and `--lp-danger-line`, and NEITHER EXISTS. A ghost
|
| 70 |
+
custom property does not fail loudly β it falls back or inherits β so the error message would
|
| 71 |
+
have painted in ordinary ink and looked like an answer. Same defect T14 caught on
|
| 72 |
+
`--lp-ink-muted` in the same wave; the palette is the only source worth trusting. */
|
| 73 |
+
.autoc-msg.is-error {
|
| 74 |
+
align-self: flex-start;
|
| 75 |
+
border: 1px solid var(--lp-red);
|
| 76 |
+
background: var(--lp-red-tint);
|
| 77 |
+
color: var(--lp-red-deep);
|
| 78 |
+
}
|
| 79 |
+
|
| 80 |
+
/* What the model asked for and the validator would not keep. β It renders as ORDINARY content,
|
| 81 |
+
not as a warning ornament: R6's standing rule is that a limit must be REPORTED, and a report
|
| 82 |
+
nobody reads because it looks like chrome is the same as no report. */
|
| 83 |
+
.autoc-dropped {
|
| 84 |
+
align-self: flex-start;
|
| 85 |
+
max-width: 60ch;
|
| 86 |
+
margin: 0;
|
| 87 |
+
padding: 8px 12px;
|
| 88 |
+
border-left: 2px solid var(--lp-line);
|
| 89 |
+
color: var(--lp-muted);
|
| 90 |
+
font-size: var(--lp-fs-xs);
|
| 91 |
+
line-height: 1.5;
|
| 92 |
+
}
|
| 93 |
+
.autoc-dropped ul { margin: 4px 0 0; padding-left: 18px; }
|
| 94 |
+
|
| 95 |
+
/* ββ W36-T33 β THE COMPOSER IS THE ASSISTANT'S, IN THIS MODULE'S NAMES.
|
| 96 |
+
Owner: *"Just as good as the Assistant module."* The done-when is a comparison, so these rules
|
| 97 |
+
mirror `assistant/assistant.css`'s `.as-field` / `.as-prompt` / `.as-field-foot` / `.as-send`
|
| 98 |
+
on the SAME TOKENS. Not `@extend`, not a shared class: `.as-*` belongs to the Assistant's
|
| 99 |
+
stylesheet and reaching into it would make one surface's restyle silently repaint the other.
|
| 100 |
+
β WHAT MUST NOT DRIFT is the pair of numbers that carry the shape β the 22px pill radius and
|
| 101 |
+
the field's shadow β because those are what the eye compares. Both are matched BY VALUE from
|
| 102 |
+
`.as-field`, and the shadow is a literal because THIS PRODUCT HAS NO SHADOW TOKEN: `index.css`
|
| 103 |
+
records that finding in as many words beside `.autoc-bigedit`, where naming a shadow token that
|
| 104 |
+
does not exist would have quietly rendered its own fallback while looking like a token was
|
| 105 |
+
being honoured.
|
| 106 |
+
β AND THAT SENTENCE USED TO NAME THE TOKEN, WHICH BROKE THE GATE THAT READS THIS FILE. R17's
|
| 107 |
+
"every token the new stylesheet uses is DEFINED in the palette" scans the raw text, comments
|
| 108 |
+
included, so quoting `var(--β¦)` in prose counts as USING it: the citation reddened the check
|
| 109 |
+
[[prose-that-becomes-its-own-marker]]. Describe a token you are NOT using; never spell it. */
|
| 110 |
+
|
| 111 |
+
/* β NO HAIRLINE ON THE BAND ANY MORE. The card below has its own border, and a rule across the
|
| 112 |
+
pane above it made two edges 12px apart β the "still so ugly" the owner reported is mostly
|
| 113 |
+
this kind of doubling. What separates the composer from the transcript now is whitespace. */
|
| 114 |
+
.autoc-compose {
|
| 115 |
+
flex: 0 0 auto;
|
| 116 |
+
padding: 8px 24px 20px;
|
| 117 |
+
}
|
| 118 |
+
.autoc-field {
|
| 119 |
+
/* ONE measure for the conversation and the empty state, so the composer does not change width
|
| 120 |
+
when the first message lands. `.as-opening .as-composer` caps at the same 700px. */
|
| 121 |
+
max-width: 700px;
|
| 122 |
+
margin: 0 auto;
|
| 123 |
+
border: 1px solid var(--lp-line);
|
| 124 |
+
border-radius: 22px;
|
| 125 |
+
background: var(--lp-surface);
|
| 126 |
+
padding: 10px 8px 8px 16px;
|
| 127 |
+
box-shadow: 0 1px 2px rgba(20, 24, 40, 0.05);
|
| 128 |
+
box-sizing: border-box;
|
| 129 |
+
}
|
| 130 |
+
.autoc-field:focus-within { border-color: var(--lp-blue-solid); }
|
| 131 |
+
|
| 132 |
+
/* β `rows={1}` PLUS `max-height`, which is `.as-prompt`'s shape and not the two-row box that was
|
| 133 |
+
here. A composer that starts tall claims space before anybody has typed; the Assistant's grows
|
| 134 |
+
into the sentence instead. */
|
| 135 |
+
.autoc-input {
|
| 136 |
+
display: block;
|
| 137 |
+
width: 100%;
|
| 138 |
+
max-height: 180px;
|
| 139 |
+
border: 0;
|
| 140 |
+
outline: none;
|
| 141 |
+
padding: 0 8px 0 0;
|
| 142 |
+
background: transparent;
|
| 143 |
+
color: var(--lp-ink);
|
| 144 |
+
font: inherit;
|
| 145 |
+
font-size: var(--lp-fs-sm);
|
| 146 |
+
line-height: var(--lp-lh);
|
| 147 |
+
resize: none;
|
| 148 |
+
box-sizing: border-box;
|
| 149 |
+
}
|
| 150 |
+
.autoc-input::placeholder { color: var(--lp-muted); }
|
| 151 |
+
|
| 152 |
+
/* The row BELOW the input and INSIDE the card β the reference screenshot's arrangement, and the
|
| 153 |
+
slot W36-T34's model toggle drops into beside the send. */
|
| 154 |
+
.autoc-foot {
|
| 155 |
+
display: flex;
|
| 156 |
+
align-items: center;
|
| 157 |
+
gap: 12px;
|
| 158 |
+
margin-top: 8px;
|
| 159 |
+
}
|
| 160 |
+
|
| 161 |
+
.autoc-send {
|
| 162 |
+
flex: 0 0 auto;
|
| 163 |
+
margin-left: auto;
|
| 164 |
+
width: 30px;
|
| 165 |
+
height: 30px;
|
| 166 |
+
display: inline-flex;
|
| 167 |
+
align-items: center;
|
| 168 |
+
justify-content: center;
|
| 169 |
+
border: 0;
|
| 170 |
+
border-radius: 999px;
|
| 171 |
+
background: var(--lp-ink);
|
| 172 |
+
color: var(--lp-surface);
|
| 173 |
+
cursor: pointer;
|
| 174 |
+
}
|
| 175 |
+
.autoc-send svg {
|
| 176 |
+
fill: none;
|
| 177 |
+
stroke: currentColor;
|
| 178 |
+
stroke-width: 1.7;
|
| 179 |
+
stroke-linecap: round;
|
| 180 |
+
stroke-linejoin: round;
|
| 181 |
+
}
|
| 182 |
+
.autoc-send:disabled { background: var(--lp-surface-2); color: var(--lp-muted); cursor: default; }
|
| 183 |
+
.autoc-send:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 1px; }
|
| 184 |
+
|
| 185 |
+
/* ββ the empty state (mirrors `.as-opening`) ββββββββββββββββββββββββββββββββ */
|
| 186 |
+
|
| 187 |
+
.autoc-opening {
|
| 188 |
+
flex: 1 1 auto;
|
| 189 |
+
min-height: 0;
|
| 190 |
+
display: flex;
|
| 191 |
+
flex-direction: column;
|
| 192 |
+
align-items: center;
|
| 193 |
+
justify-content: center;
|
| 194 |
+
padding: 24px;
|
| 195 |
+
box-sizing: border-box;
|
| 196 |
+
text-align: center;
|
| 197 |
+
}
|
| 198 |
+
.autoc-opening-h {
|
| 199 |
+
margin: 0 0 6px;
|
| 200 |
+
color: var(--lp-ink);
|
| 201 |
+
font-size: var(--lp-fs-lg);
|
| 202 |
+
font-weight: 650;
|
| 203 |
+
}
|
| 204 |
+
.autoc-opening-p {
|
| 205 |
+
max-width: 52ch;
|
| 206 |
+
margin: 0 0 20px;
|
| 207 |
+
color: var(--lp-muted);
|
| 208 |
+
font-size: var(--lp-fs-sm);
|
| 209 |
+
line-height: var(--lp-lh);
|
| 210 |
+
}
|
| 211 |
+
/* The composer is left-aligned inside a centred column, exactly as the Assistant's is: centred
|
| 212 |
+
placeholder text in a wide field reads as a search box, not as somewhere to write a sentence. */
|
| 213 |
+
.autoc-opening .autoc-field { width: 100%; text-align: left; }
|
| 214 |
+
|
| 215 |
+
/* The pending row. β It uses `.lp-spin`, the ONE loading mark app-wide (purple as of this wave's
|
| 216 |
+
T24) β a second spinner vocabulary in a new surface is how an app stops having one. */
|
| 217 |
+
.autoc-pending {
|
| 218 |
+
display: flex;
|
| 219 |
+
align-items: center;
|
| 220 |
+
gap: 8px;
|
| 221 |
+
align-self: flex-start;
|
| 222 |
+
color: var(--lp-muted);
|
| 223 |
+
font-size: var(--lp-fs-sm);
|
| 224 |
+
}
|
| 225 |
+
|
| 226 |
+
/* The accept bar. It is deliberately NOT inside the transcript: accepting is an act on the
|
| 227 |
+
AUTOMATION, not a reply in the conversation, and putting it in the log would make it scroll
|
| 228 |
+
away from the thing it acts on. */
|
| 229 |
+
.autoc-accept {
|
| 230 |
+
flex: 0 0 auto;
|
| 231 |
+
display: flex;
|
| 232 |
+
align-items: center;
|
| 233 |
+
gap: 10px;
|
| 234 |
+
padding: 10px 24px;
|
| 235 |
+
border-top: 1px solid var(--lp-line);
|
| 236 |
+
background: var(--lp-surface-2);
|
| 237 |
+
font-size: var(--lp-fs-sm);
|
| 238 |
+
}
|
| 239 |
+
.autoc-accept-note { color: var(--lp-muted); margin-right: auto; }
|
| 240 |
+
|
| 241 |
+
/* ββ the run log's note disclosure (R21 / W34-T45) ββββββββββββββββββββββββββ */
|
| 242 |
+
|
| 243 |
+
/* β WAVE 34 Β· W34-T45. `notes` is up to 300 chars x 25 entries per run and was rendered
|
| 244 |
+
unconditionally over 20 runs; that is the "too wordy" the owner reported. It is still
|
| 245 |
+
unconditional for a run that FAILED or hit a cap (R6: a limit must be REPORTED) and behind this
|
| 246 |
+
disclosure otherwise.
|
| 247 |
+
β The list INSIDE stays `.auto-run-notes`, which is C's existing rule in `index.css`. Only the
|
| 248 |
+
wrapper is new, so the notes themselves cannot start looking different depending on which
|
| 249 |
+
branch rendered them. */
|
| 250 |
+
.autor-notes {
|
| 251 |
+
margin: 2px 0 0;
|
| 252 |
+
}
|
| 253 |
+
.autor-notes-toggle {
|
| 254 |
+
cursor: pointer;
|
| 255 |
+
color: var(--lp-muted);
|
| 256 |
+
font-size: var(--lp-fs-2xs);
|
| 257 |
+
/* The default triangle is the affordance; no custom marker, because a disclosure that does not
|
| 258 |
+
look like one is how a person decides there is nothing behind it. */
|
| 259 |
+
list-style: revert;
|
| 260 |
+
}
|
| 261 |
+
.autor-notes-toggle:hover { color: var(--lp-ink); }
|
| 262 |
+
.autor-notes-toggle:focus-visible {
|
| 263 |
+
outline: 2px solid var(--lp-blue-deep);
|
| 264 |
+
outline-offset: 1px;
|
| 265 |
+
}
|
| 266 |
+
|
| 267 |
+
/* ββ the parked statements batch (W35-T36 / owner ruling R10) βββββββββββββββ */
|
| 268 |
+
|
| 269 |
+
/* ββ "N STATEMENTS ARE READY", with the ONLY Send control in the product.
|
| 270 |
+
It sits above `.auto-work`, in the banner band, because it is the one thing on this agent that
|
| 271 |
+
needs a person β R10's whole shape is that the run assembles and PARKS, and somebody releases.
|
| 272 |
+
|
| 273 |
+
β IT IS DELIBERATELY NOT A WARNING COLOUR. A parked batch is the system working as designed, and
|
| 274 |
+
painting it amber would teach people to dismiss the panel that guards a real mail send. It is
|
| 275 |
+
the blue tint every other "here is something to look at" surface uses. */
|
| 276 |
+
.auto-batch {
|
| 277 |
+
flex: 0 0 auto;
|
| 278 |
+
margin: 12px 24px 0;
|
| 279 |
+
padding: 12px 14px;
|
| 280 |
+
border: 1px solid var(--lp-blue);
|
| 281 |
+
border-radius: var(--lp-r-md);
|
| 282 |
+
background: var(--lp-blue-tint);
|
| 283 |
+
font-size: var(--lp-fs-sm);
|
| 284 |
+
}
|
| 285 |
+
.auto-batch-head {
|
| 286 |
+
display: flex;
|
| 287 |
+
align-items: baseline;
|
| 288 |
+
flex-wrap: wrap;
|
| 289 |
+
gap: 4px 10px;
|
| 290 |
+
}
|
| 291 |
+
.auto-batch-count {
|
| 292 |
+
font-weight: 650;
|
| 293 |
+
color: var(--lp-ink);
|
| 294 |
+
}
|
| 295 |
+
.auto-batch-note { color: var(--lp-muted); }
|
| 296 |
+
|
| 297 |
+
/* The guardrail line. Same size as a note, because it IS one: the data layer decides, this
|
| 298 |
+
reports (R6's second sentence). */
|
| 299 |
+
.auto-batch-safe,
|
| 300 |
+
.auto-batch-line {
|
| 301 |
+
margin: 6px 0 0;
|
| 302 |
+
color: var(--lp-muted);
|
| 303 |
+
font-size: var(--lp-fs-xs);
|
| 304 |
+
line-height: 1.5;
|
| 305 |
+
max-width: 70ch;
|
| 306 |
+
}
|
| 307 |
+
|
| 308 |
+
/* Who is about to be emailed. β Bounded in the MARKUP at 8 rows with an "and N more" line rather
|
| 309 |
+
than scrolled here: a 200-row list inside a banner pushes the work area off the screen, and the
|
| 310 |
+
panel's job is to say who and how many, not to be the worklist. */
|
| 311 |
+
.auto-batch-list {
|
| 312 |
+
margin: 8px 0 0;
|
| 313 |
+
padding: 0;
|
| 314 |
+
list-style: none;
|
| 315 |
+
display: flex;
|
| 316 |
+
flex-direction: column;
|
| 317 |
+
gap: 2px;
|
| 318 |
+
font-size: var(--lp-fs-xs);
|
| 319 |
+
}
|
| 320 |
+
.auto-batch-list li {
|
| 321 |
+
display: flex;
|
| 322 |
+
gap: 10px;
|
| 323 |
+
align-items: baseline;
|
| 324 |
+
}
|
| 325 |
+
.auto-batch-cust { color: var(--lp-ink); }
|
| 326 |
+
.auto-batch-to { color: var(--lp-muted); overflow-wrap: anywhere; }
|
| 327 |
+
.auto-batch-more { color: var(--lp-muted); }
|
| 328 |
+
|
| 329 |
+
.auto-batch-actions {
|
| 330 |
+
margin-top: 10px;
|
| 331 |
+
display: flex;
|
| 332 |
+
gap: 8px;
|
| 333 |
+
}
|
| 334 |
+
|
| 335 |
+
/* ββ W36-T44 (D-316 + D-299): the statements step's config panel βββββββββββββ */
|
| 336 |
+
|
| 337 |
+
/* NEW rules only, in this module's own stylesheet. Every `auto-*` rule the panel reuses
|
| 338 |
+
(`auto-field`, `auto-input`, `auto-hint`, `auto-note`, `auto-btn`) still lives in the shared
|
| 339 |
+
`index.css` and is still another lane's, so nothing here redefines one. */
|
| 340 |
+
|
| 341 |
+
/* The two action rows (Preview, Send one test). A row rather than a bare button so the two read
|
| 342 |
+
as the same kind of control at the same left edge as every field above them. */
|
| 343 |
+
.autox-stmt-row {
|
| 344 |
+
display: flex;
|
| 345 |
+
gap: 8px;
|
| 346 |
+
margin: 0 0 14px;
|
| 347 |
+
}
|
| 348 |
+
|
| 349 |
+
.autox-stmt-shot {
|
| 350 |
+
margin: 0 0 14px;
|
| 351 |
+
border: 1px solid var(--lp-line);
|
| 352 |
+
border-radius: var(--lp-r-md);
|
| 353 |
+
padding: 10px 12px;
|
| 354 |
+
background: var(--lp-surface-2);
|
| 355 |
+
}
|
| 356 |
+
.autox-stmt-shot .auto-hint {
|
| 357 |
+
margin: 0 0 8px;
|
| 358 |
+
overflow-wrap: anywhere;
|
| 359 |
+
}
|
| 360 |
+
|
| 361 |
+
/* β A FIXED HEIGHT, AND IT SCROLLS INSIDE ITSELF. A statement for a customer with forty open
|
| 362 |
+
invoices is a long document, and a preview that grows to its content pushes the test-send
|
| 363 |
+
control below it off the panel: the one thing somebody must reach after reading a preview.
|
| 364 |
+
|
| 365 |
+
β AND THE LITERAL WHITE IS THE ONE DELIBERATE EXCEPTION TO THIS FILE'S "every colour is a
|
| 366 |
+
token" RULE, booked here rather than left to read as an oversight. What is inside this frame is
|
| 367 |
+
not our chrome, it is the EMAIL: `render_statement_html` hard-codes #1F4E78 headers, #e3e8ef
|
| 368 |
+
rules and near-black body text against an assumed white page, and the recipient's mail client
|
| 369 |
+
will paint it on white whatever this app's theme is. A surface token would go dark in dark mode
|
| 370 |
+
and render the real mail's dark text on a dark ground, so the preview would stop showing what
|
| 371 |
+
goes out at exactly the moment somebody is checking what goes out. */
|
| 372 |
+
.autox-stmt-frame {
|
| 373 |
+
display: block;
|
| 374 |
+
width: 100%;
|
| 375 |
+
height: 260px;
|
| 376 |
+
border: 1px solid var(--lp-line);
|
| 377 |
+
border-radius: var(--lp-r-sm);
|
| 378 |
+
background: #fff;
|
| 379 |
+
}
|
| 380 |
+
|
| 381 |
+
/* ββ W36-T31 (owner item 3, R7/R8, contract C4): the Harness tab βββββββββββββ */
|
| 382 |
+
|
| 383 |
+
/* NEW rules only. Everything shared (`auto-field`, `auto-input`, `auto-btn`, `auto-note`,
|
| 384 |
+
`auto-hint`, `auto-paneltab*`) still lives in `index.css` and is still another lane's. */
|
| 385 |
+
|
| 386 |
+
.autoh-wrap {
|
| 387 |
+
display: flex;
|
| 388 |
+
flex-direction: column;
|
| 389 |
+
gap: 4px;
|
| 390 |
+
}
|
| 391 |
+
|
| 392 |
+
.autoh-files {
|
| 393 |
+
margin: 0 0 14px;
|
| 394 |
+
padding: 0;
|
| 395 |
+
list-style: none;
|
| 396 |
+
display: flex;
|
| 397 |
+
flex-direction: column;
|
| 398 |
+
gap: 2px;
|
| 399 |
+
}
|
| 400 |
+
.autoh-file {
|
| 401 |
+
display: flex;
|
| 402 |
+
align-items: center;
|
| 403 |
+
gap: 6px;
|
| 404 |
+
border-radius: var(--lp-r-sm);
|
| 405 |
+
}
|
| 406 |
+
.autoh-file.is-on { background: var(--lp-blue-tint); }
|
| 407 |
+
|
| 408 |
+
/* The row is a BUTTON, so the whole line opens the file. A path that is only clickable on its
|
| 409 |
+
own glyph-width is a target people miss and then decide is not clickable at all. */
|
| 410 |
+
.autoh-open {
|
| 411 |
+
flex: 1 1 auto;
|
| 412 |
+
min-width: 0;
|
| 413 |
+
display: flex;
|
| 414 |
+
flex-direction: column;
|
| 415 |
+
gap: 1px;
|
| 416 |
+
padding: 5px 8px;
|
| 417 |
+
border: 0;
|
| 418 |
+
border-radius: var(--lp-r-sm);
|
| 419 |
+
background: transparent;
|
| 420 |
+
color: var(--lp-ink);
|
| 421 |
+
font: inherit;
|
| 422 |
+
text-align: left;
|
| 423 |
+
cursor: pointer;
|
| 424 |
+
}
|
| 425 |
+
.autoh-open:hover:not(:disabled) { background: var(--lp-surface-2); }
|
| 426 |
+
.autoh-open:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
|
| 427 |
+
.autoh-open:disabled { cursor: default; }
|
| 428 |
+
|
| 429 |
+
/* β `anywhere`, not `ellipsis`: a harness path is `skills/router.md`, and the half that
|
| 430 |
+
identifies it is the END. Truncating from the right hides exactly the distinguishing part. */
|
| 431 |
+
.autoh-path {
|
| 432 |
+
font-size: var(--lp-fs-sm);
|
| 433 |
+
font-weight: 600;
|
| 434 |
+
overflow-wrap: anywhere;
|
| 435 |
+
}
|
| 436 |
+
.autoh-meta {
|
| 437 |
+
color: var(--lp-muted);
|
| 438 |
+
font-size: var(--lp-fs-2xs);
|
| 439 |
+
overflow-wrap: anywhere;
|
| 440 |
+
}
|
| 441 |
+
|
| 442 |
+
/* Quiet until reached for. Deleting a file is a real act (it takes the history with it), so it is
|
| 443 |
+
present and honest rather than hidden, but it does not compete with opening one. */
|
| 444 |
+
.autoh-drop {
|
| 445 |
+
flex: 0 0 auto;
|
| 446 |
+
opacity: 0.55;
|
| 447 |
+
}
|
| 448 |
+
.autoh-file:hover .autoh-drop,
|
| 449 |
+
.autoh-drop:focus-visible { opacity: 1; }
|
| 450 |
+
|
| 451 |
+
.autoh-newrow {
|
| 452 |
+
display: flex;
|
| 453 |
+
gap: 6px;
|
| 454 |
+
align-items: center;
|
| 455 |
+
}
|
| 456 |
+
|
| 457 |
+
/* Monospace, because a harness file is a router or a skill: its indentation carries meaning and a
|
| 458 |
+
proportional font makes a misaligned block look aligned.
|
| 459 |
+
β THE FACE COMES FROM `.auto-input.is-mono`, WHICH THE TEXTAREA ALSO CARRIES, and this rule sets
|
| 460 |
+
no `font-family` at all. `index.css:12591` records why in as many words: there IS no `--lp-mono`
|
| 461 |
+
token, six sites spell the stack out, and a seventh copy here would put the product's mono face
|
| 462 |
+
in two places that can drift. `WebActionConfig` reaches for the same class. */
|
| 463 |
+
.autoh-body {
|
| 464 |
+
font-size: var(--lp-fs-xs);
|
| 465 |
+
line-height: 1.55;
|
| 466 |
+
resize: vertical;
|
| 467 |
+
}
|
| 468 |
+
|
| 469 |
+
.autoh-actions {
|
| 470 |
+
display: flex;
|
| 471 |
+
gap: 8px;
|
| 472 |
+
margin: 0 0 14px;
|
| 473 |
+
}
|
| 474 |
+
|
| 475 |
+
.autoh-history {
|
| 476 |
+
margin: 0 0 8px;
|
| 477 |
+
padding: 0;
|
| 478 |
+
list-style: none;
|
| 479 |
+
display: flex;
|
| 480 |
+
flex-direction: column;
|
| 481 |
+
gap: 1px;
|
| 482 |
+
}
|
| 483 |
+
.autoh-history li { border-radius: var(--lp-r-sm); }
|
| 484 |
+
.autoh-history li.is-on { background: var(--lp-blue-tint); }
|
| 485 |
+
.autoh-version {
|
| 486 |
+
width: 100%;
|
| 487 |
+
display: flex;
|
| 488 |
+
gap: 8px;
|
| 489 |
+
align-items: baseline;
|
| 490 |
+
padding: 4px 8px;
|
| 491 |
+
border: 0;
|
| 492 |
+
border-radius: var(--lp-r-sm);
|
| 493 |
+
background: transparent;
|
| 494 |
+
color: var(--lp-ink);
|
| 495 |
+
font: inherit;
|
| 496 |
+
text-align: left;
|
| 497 |
+
cursor: pointer;
|
| 498 |
+
}
|
| 499 |
+
.autoh-version:hover:not(:disabled) { background: var(--lp-surface-2); }
|
| 500 |
+
.autoh-version:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: -2px; }
|
| 501 |
+
.autoh-version:disabled { cursor: default; }
|
| 502 |
+
.autoh-vnum {
|
| 503 |
+
flex: 0 0 auto;
|
| 504 |
+
font-size: var(--lp-fs-xs);
|
| 505 |
+
font-weight: 650;
|
| 506 |
+
}
|
| 507 |
+
|
| 508 |
+
/* The unsaved-edit hold. A bordered block rather than a tint, because it is a QUESTION waiting on
|
| 509 |
+
an answer and the two buttons under it are the answer; a tinted note reads as commentary. */
|
| 510 |
+
.autoh-hold {
|
| 511 |
+
margin: 0 0 14px;
|
| 512 |
+
padding: 10px 12px;
|
| 513 |
+
border: 1px solid var(--lp-line);
|
| 514 |
+
border-radius: var(--lp-r-md);
|
| 515 |
+
background: var(--lp-surface-2);
|
| 516 |
+
}
|
| 517 |
+
.autoh-hold .auto-note { margin-top: 0; }
|
| 518 |
+
|
| 519 |
+
/* ββ W36-T32 (owner item 3, R7): the right rail folds behind a "III" βββββββββ */
|
| 520 |
+
|
| 521 |
+
/* β THE FOLD SITS AT THE RAIL'S OWN LEFT EDGE, AND `flex-start` IS ONLY HALF OF WHY.
|
| 522 |
+
W35-T11 put the left rails' fold at their left edge; this rail is on the RIGHT, so its left
|
| 523 |
+
edge is the one facing the chat it widens. `.auto-panel-head` is `space-between` and lives in
|
| 524 |
+
`index.css` (another lane's), so this wrapper is what keeps the fold and the tabs together
|
| 525 |
+
instead of flung to the panel's two edges.
|
| 526 |
+
ββ AND NOTHING IN HERE MAY EVER CARRY `margin-left: auto`. W35-T28's real finding was that a
|
| 527 |
+
sibling's auto margin ate the free space BEFORE `justify-content` applied, so one control sat
|
| 528 |
+
left on one database and right on another: one control, two positions, decided by data. */
|
| 529 |
+
.autod-head {
|
| 530 |
+
flex: 1 1 auto;
|
| 531 |
+
min-width: 0;
|
| 532 |
+
display: flex;
|
| 533 |
+
align-items: center;
|
| 534 |
+
justify-content: flex-start;
|
| 535 |
+
gap: 10px;
|
| 536 |
+
}
|
| 537 |
+
|
| 538 |
+
/* The collapsed rail. Same width token and the same idea as `.auto-rail.is-collapsed` on the
|
| 539 |
+
left of this screen: folding a rail leaves a strip, never a gap, because the strip is where the
|
| 540 |
+
way back lives. */
|
| 541 |
+
.autod-shut {
|
| 542 |
+
flex: 0 0 auto;
|
| 543 |
+
width: var(--lp-rail-min);
|
| 544 |
+
display: flex;
|
| 545 |
+
justify-content: center;
|
| 546 |
+
padding: 14px 6px 0;
|
| 547 |
+
border-left: 1px solid var(--lp-line);
|
| 548 |
+
background: var(--lp-surface);
|
| 549 |
+
}
|
| 550 |
+
|
| 551 |
+
/* β THE FOLD, IN ONE PLACE. Every `.auto-panel` in the work area goes at once β Properties (a
|
| 552 |
+
child of AutomationBuilder), Harness and Run history (children of AutomationDetail) β so a
|
| 553 |
+
panel added later folds without being told to. `display: none` also removes them from the
|
| 554 |
+
accessibility tree, which is the property `hidden` was giving us and the reason a `visibility`
|
| 555 |
+
or `width: 0` treatment would be a regression a screen reader would meet and nobody would see. */
|
| 556 |
+
.autod-folded .auto-panel { display: none; }
|
| 557 |
|
| 558 |
/* ββ W36-T34 (owner item 3, R4, contract C5): the model toggle βββββββββββββββ */
|
| 559 |
|
web/src/connectors/brandMarks.tsx
CHANGED
|
@@ -1,413 +1,413 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// connectors/brandMarks.tsx β WAVE 30, owner item 7 (rulings R3 + R4):
|
| 3 |
-
// THE ONE PLACE A CONNECTOR'S IDENTITY IS DRAWN.
|
| 4 |
-
//
|
| 5 |
-
// The owner, verbatim and for the third time: *"their Instagram and Tiktok logo
|
| 6 |
-
// to be fucking displayed, same with all logos under the Connectors module."*
|
| 7 |
-
//
|
| 8 |
-
// β THIS SUPERSEDES A RULE THAT WAS STILL SHIPPING. Wave-23 R8 said connector
|
| 9 |
-
// identity is a two-letter monogram in the chip family, and it was enforced β
|
| 10 |
-
// `verify_home.py:section_connectors` asserted a real mark could not appear.
|
| 11 |
-
// R4 replaces it FOR CONNECTOR IDENTITY ONLY. Everything else the design
|
| 12 |
-
// constitution says is untouched: no emojis anywhere, and no decorative
|
| 13 |
-
// third-party imagery outside this file's purpose, which is telling a person
|
| 14 |
-
// which company a row is about.
|
| 15 |
-
//
|
| 16 |
-
// ββ WAVE 33 Β· OWNER ITEM 6 / RULING R4 β THE PARAGRAPH BELOW IS SUPERSEDED FOR
|
| 17 |
-
// A COMPANY'S MARK, AND IT IS KEPT BECAUSE IT IS STILL RIGHT ABOUT WHAT IT WAS
|
| 18 |
-
// ACTUALLY DEFENDING. It read:
|
| 19 |
-
//
|
| 20 |
-
// "INLINE SVG, NEVER A FILE AND NEVER A REMOTE URL. There is no `assets/` or
|
| 21 |
-
// `icons/` directory in this app and there is not going to be one β¦ A remote
|
| 22 |
-
// logo would work today (no CSP header is set) and would be the one thing on
|
| 23 |
-
// the page that can be taken away by somebody else's outage."
|
| 24 |
-
//
|
| 25 |
-
// β THE RULE IT WAS PROTECTING IS **NO THIRD-PARTY ORIGIN**, and that rule is
|
| 26 |
-
// untouched: `/api/v1/brand/<name>` is OUR door, same-origin, session-gated,
|
| 27 |
-
// served off bytes that ship inside the image (`web/public/brand/`). Nobody
|
| 28 |
-
// else's outage can take it away, and there is still no `assets/` directory β
|
| 29 |
-
// there is a brand directory, which is a different thing with a route in front
|
| 30 |
-
// of it.
|
| 31 |
-
// β WHAT DID CHANGE IS THE OWNER'S VERDICT ON THE ARTWORK, twice now. Wave 30's
|
| 32 |
-
// R4 replaced wave 23's two-letter monogram with these hand-drawn marks; wave
|
| 33 |
-
// 33's R4 replaces the hand-drawn marks with each vendor's OFFICIAL artwork,
|
| 34 |
-
// because the honest sentence three paragraphs down β *"recognisable
|
| 35 |
-
// SIMPLIFICATIONS β¦ not the trademarked artwork"* β is exactly what the owner
|
| 36 |
-
// saw: *"Do not generate your own logo for Connectors, they look really uncanny
|
| 37 |
-
// /browse them the PNG, cut appropriately for our needs, verify visually."*
|
| 38 |
-
// A ruling that supersedes a rule leaves that rule's gates green
|
| 39 |
-
// ([[two-gates-can-assert-opposite-things]]); see `mailbox/G.md` G-2/G-3 for the
|
| 40 |
-
// four legs in `verify_automation_ui` / `picker_render.test.tsx` this moves.
|
| 41 |
-
//
|
| 42 |
-
// β THE HAND-DRAWN SET IS NOT DELETED. Every arm below still exists and is what
|
| 43 |
-
// renders when the door does not answer, so a 404, a 401 or a container without
|
| 44 |
-
// the files degrades to the wave-30 mark rather than to a broken-image glyph.
|
| 45 |
-
// Two of the arms are not fallbacks at all: `webhooks` and `scraper` are OURS,
|
| 46 |
-
// there is no vendor artwork to fetch, and they stay inline permanently.
|
| 47 |
-
//
|
| 48 |
-
// β ONE MODULE FOR THREE SURFACES, and that is the whole design. The trigger
|
| 49 |
-
// picker, the action menu and the Connectors directory all answer "which
|
| 50 |
-
// company is this?" β three copies of a logo set is three chances to add a
|
| 51 |
-
// platform in two places and forget the third, which is precisely the defect
|
| 52 |
-
// wave 30 exists to fix on the server side of the same question.
|
| 53 |
-
//
|
| 54 |
-
// β WHAT THESE ARE, HONESTLY: recognisable SIMPLIFICATIONS drawn from each
|
| 55 |
-
// brand's published silhouette and brand colour, at 16px, not the trademarked
|
| 56 |
-
// artwork. That is the right call at this size β the real Google `G` is a
|
| 57 |
-
// 500-byte path that renders as mush in a 15px box β and it is stated here so
|
| 58 |
-
// nobody "upgrades" them by pasting a vendor's asset file into a repo that has
|
| 59 |
-
// no place to put one.
|
| 60 |
-
//
|
| 61 |
-
// β THEME. Marks are brand-coloured and must survive BOTH themes, so no mark
|
| 62 |
-
// relies on pure black or pure white for its silhouette: TikTok's note is
|
| 63 |
-
// `currentColor` with its two brand offsets behind it, which is also how the
|
| 64 |
-
// real mark is constructed.
|
| 65 |
-
// ---------------------------------------------------------------------------
|
| 66 |
-
import type { ReactElement } from "react";
|
| 67 |
-
import { useId, useState } from "react";
|
| 68 |
-
|
| 69 |
-
import { API_V1 } from "../apiContract";
|
| 70 |
-
|
| 71 |
-
/**
|
| 72 |
-
* The canonical brand names this module can draw. Deliberately NOT the same
|
| 73 |
-
* strings as the connector keys or the trigger kinds: three vocabularies point
|
| 74 |
-
* AT this one, and folding them together would make a rename in any of the
|
| 75 |
-
* three a silent loss of an icon.
|
| 76 |
-
*/
|
| 77 |
-
export type BrandName =
|
| 78 |
-
| "instagram"
|
| 79 |
-
| "tiktok"
|
| 80 |
-
| "odoo"
|
| 81 |
-
| "google"
|
| 82 |
-
| "gmail"
|
| 83 |
-
| "stripe"
|
| 84 |
-
| "shopify"
|
| 85 |
-
| "webhooks"
|
| 86 |
-
| "scraper"
|
| 87 |
-
| "slack"
|
| 88 |
-
| "meta";
|
| 89 |
-
|
| 90 |
-
/**
|
| 91 |
-
* Trigger and action KIND -> brand.
|
| 92 |
-
*
|
| 93 |
-
* β KEYED ON THE KIND AND NOT ON THE CONNECTOR, and the reason is R3 itself:
|
| 94 |
-
* after this wave Instagram and TikTok share `connector.key === "scraper"`, so
|
| 95 |
-
* the connector can no longer tell them apart. The kind is the only thing that
|
| 96 |
-
* still distinguishes the two products, which is exactly why the picker's own
|
| 97 |
-
* `TriggerMark` has always been keyed this way.
|
| 98 |
-
*
|
| 99 |
-
* β An unmapped kind returns null and the caller draws its existing glyph β a
|
| 100 |
-
* trigger the engine adds tomorrow renders plainly rather than not at all.
|
| 101 |
-
*/
|
| 102 |
-
export const BRAND_OF_KIND: Record<string, BrandName> = {
|
| 103 |
-
ig_profile_match: "instagram",
|
| 104 |
-
tiktok_profile_match: "tiktok",
|
| 105 |
-
enrich_instagram: "instagram",
|
| 106 |
-
enrich_tiktok: "tiktok",
|
| 107 |
-
field_instagram: "instagram",
|
| 108 |
-
};
|
| 109 |
-
|
| 110 |
-
/**
|
| 111 |
-
* Connector/provider KEY -> brand, for the Connectors directory and for the
|
| 112 |
-
* collapsed connector nests in both automation menus.
|
| 113 |
-
*
|
| 114 |
-
* β `scraper` and `webhooks` are OURS, not brands β they get house glyphs in
|
| 115 |
-
* `currentColor` so they sit in the chip family the way they always have. They
|
| 116 |
-
* are in this map rather than special-cased at the call site so that "what mark
|
| 117 |
-
* does this row wear" has ONE answer, whoever is asking.
|
| 118 |
-
*/
|
| 119 |
-
export const BRAND_OF_CONNECTOR: Record<string, BrandName> = {
|
| 120 |
-
odoo: "odoo",
|
| 121 |
-
// ββ WAVE 32 Β· OWNER ITEM 12 / R6 β THESE TWO MARKS ARE CURRENTLY UNREACHABLE, AND KEPT.
|
| 122 |
-
// `oauth_connect.offered("google")` is False, so the directory serves no `google` row and this
|
| 123 |
-
// map is never asked for either of these. They stay for the reason the ruling is worded as
|
| 124 |
-
// *"HIDDEN until they are real"* rather than "removed": the blocker is money, not code (D-45 β
|
| 125 |
-
// Google's CASA verification, ~$540β1,800/yr, for the `gmail.readonly` scope). The day that is
|
| 126 |
-
// paid for, ONE key flips server-side and the card comes back wearing its own logo. Deleting
|
| 127 |
-
// the art would turn a one-key restore into a re-draw, and would leave the next reader
|
| 128 |
-
// wondering where Gmail's mark went as well as where Gmail went.
|
| 129 |
-
google: "google",
|
| 130 |
-
gmail: "gmail",
|
| 131 |
-
stripe: "stripe",
|
| 132 |
-
shopify: "shopify",
|
| 133 |
-
scraper: "scraper",
|
| 134 |
-
webhooks: "webhooks",
|
| 135 |
-
instagram: "instagram",
|
| 136 |
-
tiktok: "tiktok",
|
| 137 |
-
// β WAVE 31 Β· R7 β the Nango breadth play's first two marks. `meta_ads` is the KEYCHAIN
|
| 138 |
-
// connector (a token an admin pastes today); `meta` would be the delegated-OAuth door the same
|
| 139 |
-
// company owns, so BOTH keys point at one mark rather than the map growing a near-duplicate.
|
| 140 |
-
slack: "slack",
|
| 141 |
-
meta: "meta",
|
| 142 |
-
meta_ads: "meta",
|
| 143 |
-
};
|
| 144 |
-
|
| 145 |
-
/** The house frame every mark is drawn in. 16Γ16 user units, sized by the caller. */
|
| 146 |
-
function frame(size: number) {
|
| 147 |
-
return { width: size, height: size, viewBox: "0 0 16 16", "aria-hidden": true } as const;
|
| 148 |
-
}
|
| 149 |
-
|
| 150 |
-
/**
|
| 151 |
-
* β TIKTOK'S NOTE, DRAWN THREE TIMES. The real mark is one glyph offset in
|
| 152 |
-
* cyan and magenta behind a solid copy; drawing only the solid copy loses the
|
| 153 |
-
* brand entirely at this size, and drawing the offsets in black loses it in
|
| 154 |
-
* dark mode. The solid copy is `currentColor` so it inherits the row.
|
| 155 |
-
*/
|
| 156 |
-
const TT_NOTE =
|
| 157 |
-
"M9.05 1.9h2.02c.13 1.2.87 2.13 2.03 2.3v2.03c-.78 0-1.53-.2-2.18-.58v3.98"
|
| 158 |
-
+ "a3.62 3.62 0 1 1-3.62-3.62c.16 0 .32.01.48.03v2.06a1.6 1.6 0 1 0 1.27 1.56z";
|
| 159 |
-
|
| 160 |
-
/**
|
| 161 |
-
* Brands we hold OFFICIAL artwork for, i.e. the ones `/api/v1/brand/<name>`
|
| 162 |
-
* answers 200 on. β Derived from one place β the server's own directory listing
|
| 163 |
-
* would be a round trip on every chip, and a hardcoded list here would drift the
|
| 164 |
-
* moment a file is added, so `verify_meta::section_brand_door` pins this set
|
| 165 |
-
* against the files on disk in BOTH directions. Adding a mark is: drop the PNG
|
| 166 |
-
* in `web/public/brand/`, add its SOURCES.md row, add the key here.
|
| 167 |
-
*
|
| 168 |
-
* β `webhooks` and `scraper` are ABSENT ON PURPOSE and must stay absent: they are
|
| 169 |
-
* house glyphs in `currentColor`, there is no vendor and no artwork to fetch, and
|
| 170 |
-
* asking the door for one would be a guaranteed 404 on every render.
|
| 171 |
-
*/
|
| 172 |
-
const OFFICIAL: ReadonlySet<BrandName> = new Set<BrandName>([
|
| 173 |
-
"instagram", "tiktok", "odoo", "google", "gmail", "slack", "meta",
|
| 174 |
-
"stripe", "shopify",
|
| 175 |
-
]);
|
| 176 |
-
|
| 177 |
-
/** The door R4 mandates. Relative, so it is same-origin by construction β the
|
| 178 |
-
* one property the superseded "never a remote URL" rule was really protecting. */
|
| 179 |
-
export function brandSrc(name: BrandName): string {
|
| 180 |
-
return `${API_V1}/brand/${name}`;
|
| 181 |
-
}
|
| 182 |
-
|
| 183 |
-
export function BrandMark({
|
| 184 |
-
name,
|
| 185 |
-
size = 15,
|
| 186 |
-
}: {
|
| 187 |
-
name: BrandName;
|
| 188 |
-
size?: number;
|
| 189 |
-
}): ReactElement | null {
|
| 190 |
-
const f = frame(size);
|
| 191 |
-
// ββ WAVE 33 Β· R4 β THE OFFICIAL MARK, FROM OUR OWN DOOR, WITH THE WAVE-30 ART
|
| 192 |
-
// BEHIND IT. `useState` rather than a bare `<img>` because a door that cannot
|
| 193 |
-
// answer must degrade to a mark and never to a browser's broken-image glyph β
|
| 194 |
-
// which is the one outcome worse than the hand-drawn logo the owner complained
|
| 195 |
-
// about. `onError` fires for a 404, a 401 after a session expires, and a
|
| 196 |
-
// container built without `web/public/brand/`, and each of those falls through
|
| 197 |
-
// to the arms below.
|
| 198 |
-
// β Hooks run for EVERY name, including the two house glyphs, because a hook
|
| 199 |
-
// cannot sit behind a conditional return β same reason `useId` is unconditional.
|
| 200 |
-
const [failed, setFailed] = useState(false);
|
| 201 |
-
// Per-instance, for the reason spelled out at the `<defs>` below. It must also run BEFORE
|
| 202 |
-
// the official-image return: `failed` flips on `onError`, and a hook first reached on that
|
| 203 |
-
// re-render is one more hook than the previous render β React #310 on the exact fallback
|
| 204 |
-
// path this component exists to provide.
|
| 205 |
-
const gradId = `aios-brand-ig-${useId()}`;
|
| 206 |
-
if (OFFICIAL.has(name) && !failed)
|
| 207 |
-
return (
|
| 208 |
-
<img
|
| 209 |
-
src={brandSrc(name)}
|
| 210 |
-
width={size}
|
| 211 |
-
height={size}
|
| 212 |
-
alt=""
|
| 213 |
-
aria-hidden="true"
|
| 214 |
-
// β `block` kills the inline-baseline gap that would make a 15px logo sit
|
| 215 |
-
// a pixel lower than the 15px SVG beside it in the same chip row.
|
| 216 |
-
style={{ display: "block", width: size, height: size }}
|
| 217 |
-
onError={() => setFailed(true)}
|
| 218 |
-
/>
|
| 219 |
-
);
|
| 220 |
-
if (name === "instagram")
|
| 221 |
-
return (
|
| 222 |
-
<svg {...f} fill="none">
|
| 223 |
-
{/*
|
| 224 |
-
ββ THE GRADIENT ID IS PER-INSTANCE, AND THE FIXED ONE WAS A REAL BUG β FOUND BY A
|
| 225 |
-
PICTURE, NOT BY A GATE. It shipped for an hour as the constant `aios-brand-ig`, on the
|
| 226 |
-
reasoning that duplicate ids resolve to the FIRST definition and every definition is
|
| 227 |
-
byte-identical, so it cannot matter. MEASURED in the connectors shot: the Scraper card
|
| 228 |
-
holds an Instagram mark inside a COLLAPSED `<details>`, a second card below holds a
|
| 229 |
-
visible one β and the visible one painted NOTHING. A closed `<details>` is
|
| 230 |
-
`content-visibility: hidden`, its subtree is not rendered, and a paint server defined
|
| 231 |
-
inside a skipped subtree does not resolve for a user outside it. "The first definition
|
| 232 |
-
wins" IS the failure: whichever copy happens to be hidden decides for all of them.
|
| 233 |
-
β Nothing about `<details>` is special β `display:none` does the same. Any page holding
|
| 234 |
-
two of this mark with the first one hidden loses the second.
|
| 235 |
-
β `useId` rather than a module counter, so the markup stays DETERMINISTIC for a given
|
| 236 |
-
tree β the render gates could not assert against a random id β and stable across a
|
| 237 |
-
server render and its hydration.
|
| 238 |
-
β Every check that looks for this mark matches the PREFIX `url(#aios-brand-ig`.
|
| 239 |
-
*/}
|
| 240 |
-
<defs>
|
| 241 |
-
{/* β `userSpaceOnUse` IS LOAD-BEARING AND ITS ABSENCE LOOKED FINE. The default is
|
| 242 |
-
`objectBoundingBox`, where the coordinates are FRACTIONS of the shape's box β so
|
| 243 |
-
`1,15 β 15,1` put the whole gradient vector far outside every path and each one
|
| 244 |
-
painted a single clamped stop. The mark still rendered, still read as Instagram,
|
| 245 |
-
and was simply flat pink: a defect only a picture catches, which is why one was
|
| 246 |
-
taken ([[ui-invisible-to-assertions]]). In user space the numbers mean viewBox
|
| 247 |
-
units, which is what they were written as. */}
|
| 248 |
-
<linearGradient
|
| 249 |
-
id={gradId} gradientUnits="userSpaceOnUse"
|
| 250 |
-
x1="2" y1="14" x2="14" y2="2"
|
| 251 |
-
>
|
| 252 |
-
<stop offset="0" stopColor="#FEDA75" />
|
| 253 |
-
<stop offset="0.32" stopColor="#FA7E1E" />
|
| 254 |
-
<stop offset="0.62" stopColor="#D62976" />
|
| 255 |
-
<stop offset="1" stopColor="#962FBF" />
|
| 256 |
-
</linearGradient>
|
| 257 |
-
</defs>
|
| 258 |
-
<rect
|
| 259 |
-
x="1.7" y="1.7" width="12.6" height="12.6" rx="3.7"
|
| 260 |
-
stroke={`url(#${gradId})`} strokeWidth="1.5"
|
| 261 |
-
/>
|
| 262 |
-
<circle cx="8" cy="8" r="3" stroke={`url(#${gradId})`} strokeWidth="1.5" />
|
| 263 |
-
<circle cx="11.6" cy="4.4" r="0.95" fill={`url(#${gradId})`} />
|
| 264 |
-
</svg>
|
| 265 |
-
);
|
| 266 |
-
if (name === "tiktok")
|
| 267 |
-
return (
|
| 268 |
-
<svg {...f}>
|
| 269 |
-
<path d={TT_NOTE} fill="#25F4EE" transform="translate(-0.9 -0.5)" />
|
| 270 |
-
<path d={TT_NOTE} fill="#FE2C55" transform="translate(0.9 0.5)" />
|
| 271 |
-
<path d={TT_NOTE} fill="currentColor" />
|
| 272 |
-
</svg>
|
| 273 |
-
);
|
| 274 |
-
if (name === "odoo")
|
| 275 |
-
return (
|
| 276 |
-
<svg {...f}>
|
| 277 |
-
{/* Odoo's brand purple, and its wordmark's twin `o`s β the part of that
|
| 278 |
-
wordmark that survives being shrunk to 15px. */}
|
| 279 |
-
<rect x="1" y="1" width="14" height="14" rx="3.4" fill="#714B67" />
|
| 280 |
-
<circle cx="5.7" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
|
| 281 |
-
<circle cx="10.4" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
|
| 282 |
-
</svg>
|
| 283 |
-
);
|
| 284 |
-
if (name === "google")
|
| 285 |
-
return (
|
| 286 |
-
<svg {...f} fill="none" strokeWidth="2.3">
|
| 287 |
-
{/* The four-arc G. Each arc is one brand colour, and the bar into the
|
| 288 |
-
centre is what makes it a G rather than a ring. */}
|
| 289 |
-
<path d="M4.46 4.46A5 5 0 0 1 11.54 4.46" stroke="#EA4335" strokeLinecap="round" />
|
| 290 |
-
<path d="M4.46 4.46A5 5 0 0 0 4.46 11.54" stroke="#FBBC05" strokeLinecap="round" />
|
| 291 |
-
<path d="M4.46 11.54A5 5 0 0 0 11.54 11.54" stroke="#34A853" strokeLinecap="round" />
|
| 292 |
-
<path d="M11.54 11.54A5 5 0 0 0 13 8" stroke="#4285F4" strokeLinecap="round" />
|
| 293 |
-
<path d="M13 8H8.4" stroke="#4285F4" />
|
| 294 |
-
</svg>
|
| 295 |
-
);
|
| 296 |
-
if (name === "gmail")
|
| 297 |
-
return (
|
| 298 |
-
<svg {...f} fill="none" stroke="#EA4335" strokeWidth="1.5" strokeLinejoin="round">
|
| 299 |
-
<rect x="1.6" y="3.6" width="12.8" height="9" rx="1.6" />
|
| 300 |
-
<path d="m2 4.4 6 4.6 6-4.6" />
|
| 301 |
-
</svg>
|
| 302 |
-
);
|
| 303 |
-
// β WAVE 31 Β· R7. Slack's mark is FOUR bars in four brand colours, drawn as rounded rects
|
| 304 |
-
// rather than the true interlocking glyph: at 15px the real lozenges collapse into mud, and a
|
| 305 |
-
// mark nobody can identify is worse than a two-letter tile. Colours are Slack's own.
|
| 306 |
-
if (name === "slack")
|
| 307 |
-
return (
|
| 308 |
-
<svg {...f}>
|
| 309 |
-
<rect x="2" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#36C5F0" />
|
| 310 |
-
<rect x="8.6" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#2EB67D" />
|
| 311 |
-
<rect x="6.6" y="2" width="2.8" height="5.4" rx="1.4" fill="#ECB22E" />
|
| 312 |
-
<rect x="6.6" y="8.6" width="2.8" height="5.4" rx="1.4" fill="#E01E5A" />
|
| 313 |
-
</svg>
|
| 314 |
-
);
|
| 315 |
-
// Meta's infinity loop, as two overlapping strokes in the brand blue. β `fill="none"` with a
|
| 316 |
-
// round cap: filled, the two lobes merge into a blob at this size.
|
| 317 |
-
if (name === "meta")
|
| 318 |
-
return (
|
| 319 |
-
<svg {...f} fill="none">
|
| 320 |
-
<path
|
| 321 |
-
d="M2.2 10.4c0-3 1.5-5.2 3.3-5.2 1.2 0 2 .8 3 2.4l1 1.6c.9 1.4 1.5 2.1 2.2 2.1.8 0
|
| 322 |
-
1.3-.8 1.3-2.1 0-1.6-.7-3.4-2-3.4-.9 0-1.7.7-2.6 2"
|
| 323 |
-
stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
|
| 324 |
-
/>
|
| 325 |
-
<path
|
| 326 |
-
d="M2.2 10.4c0 1.3.6 2 1.5 2 .8 0 1.4-.5 2.5-2.2l3-4.6"
|
| 327 |
-
stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
|
| 328 |
-
/>
|
| 329 |
-
</svg>
|
| 330 |
-
);
|
| 331 |
-
if (name === "stripe")
|
| 332 |
-
return (
|
| 333 |
-
<svg {...f}>
|
| 334 |
-
<rect x="1" y="1" width="14" height="14" rx="3.4" fill="#635BFF" />
|
| 335 |
-
<path
|
| 336 |
-
d="M10.5 5.6a2.3 2.3 0 0 0-3.6 1.2c0 2.1 4.1 1.5 4.1 3.5a2.4 2.4 0 0 1-3.7 1.3"
|
| 337 |
-
fill="none" stroke="#FFFFFF" strokeWidth="1.5" strokeLinecap="round"
|
| 338 |
-
/>
|
| 339 |
-
</svg>
|
| 340 |
-
);
|
| 341 |
-
if (name === "shopify")
|
| 342 |
-
return (
|
| 343 |
-
<svg {...f}>
|
| 344 |
-
{/* The bag, in Shopify's two greens: the darker one is the handle, which
|
| 345 |
-
is the part that reads as a bag rather than as a box. */}
|
| 346 |
-
<path d="M3.5 5.2h9l-.75 8.4a.9.9 0 0 1-.9.8H5.15a.9.9 0 0 1-.9-.8z" fill="#95BF47" />
|
| 347 |
-
<path
|
| 348 |
-
d="M6.1 6.4V4.5a1.9 1.9 0 0 1 3.8 0v1.9"
|
| 349 |
-
fill="none" stroke="#5E8E3E" strokeWidth="1.4" strokeLinecap="round"
|
| 350 |
-
/>
|
| 351 |
-
</svg>
|
| 352 |
-
);
|
| 353 |
-
/*
|
| 354 |
-
β THE LAST TWO ARE OURS, NOT BRANDS β `currentColor`, house stroke weight,
|
| 355 |
-
so they sit in the chip family beside the coloured logos rather than
|
| 356 |
-
pretending to be a company. Keeping them here is what lets every caller ask
|
| 357 |
-
one question instead of two.
|
| 358 |
-
*/
|
| 359 |
-
if (name === "webhooks")
|
| 360 |
-
return (
|
| 361 |
-
<svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
|
| 362 |
-
strokeLinecap="round" strokeLinejoin="round">
|
| 363 |
-
<path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
|
| 364 |
-
<path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
|
| 365 |
-
<path d="M6.2 8h3.6" />
|
| 366 |
-
</svg>
|
| 367 |
-
);
|
| 368 |
-
if (name === "scraper")
|
| 369 |
-
return (
|
| 370 |
-
<svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
|
| 371 |
-
strokeLinecap="round" strokeLinejoin="round">
|
| 372 |
-
{/* A magnifier over a grid of rows: it reads a catalogue of profiles and
|
| 373 |
-
makes records out of what matches β which is what the bucket does,
|
| 374 |
-
and it is deliberately NOT either platform's mark, because the whole
|
| 375 |
-
point of R3 is that the bucket is neither one of them. */}
|
| 376 |
-
<path d="M2.6 3.4h10.8M2.6 6.2h5.2M2.6 9h3.4" />
|
| 377 |
-
<circle cx="10.4" cy="10.2" r="3" />
|
| 378 |
-
<path d="m12.6 12.4 1.6 1.6" />
|
| 379 |
-
</svg>
|
| 380 |
-
);
|
| 381 |
-
return null;
|
| 382 |
-
}
|
| 383 |
-
|
| 384 |
-
/**
|
| 385 |
-
* Does this kind wear a LOGO rather than a house glyph?
|
| 386 |
-
*
|
| 387 |
-
* β IT EXISTS BECAUSE THE TILE HAS TO CHANGE TOO, and forgetting that would have shipped the
|
| 388 |
-
* defect quietly: `.autox-card-mark` paints a blue tint and sets `color: var(--lp-blue-deep)`,
|
| 389 |
-
* so TikTok's note β which is `currentColor` by design, so it survives dark mode β would have
|
| 390 |
-
* rendered BLUE, and Instagram's gradient would have sat on a coloured chip. The caller adds
|
| 391 |
-
* `is-brand`, which neutralises both. One predicate, so the mark and its tile cannot disagree
|
| 392 |
-
* about whether a row is branded.
|
| 393 |
-
*/
|
| 394 |
-
export function hasBrandKind(kind: string): boolean {
|
| 395 |
-
return Boolean(BRAND_OF_KIND[kind]);
|
| 396 |
-
}
|
| 397 |
-
|
| 398 |
-
/** The connector-key twin of `hasBrandKind`, for the directory's tiles. */
|
| 399 |
-
export function hasBrandConnector(key: string): boolean {
|
| 400 |
-
return Boolean(BRAND_OF_CONNECTOR[key]);
|
| 401 |
-
}
|
| 402 |
-
|
| 403 |
-
/** The mark for a trigger or action KIND, or null when it is not a branded one. */
|
| 404 |
-
export function brandForKind(kind: string, size = 15): ReactElement | null {
|
| 405 |
-
const name = BRAND_OF_KIND[kind];
|
| 406 |
-
return name ? <BrandMark name={name} size={size} /> : null;
|
| 407 |
-
}
|
| 408 |
-
|
| 409 |
-
/** The mark for a connector/provider KEY, or null when we have no logo for it. */
|
| 410 |
-
export function brandForConnector(key: string, size = 15): ReactElement | null {
|
| 411 |
-
const name = BRAND_OF_CONNECTOR[key];
|
| 412 |
-
return name ? <BrandMark name={name} size={size} /> : null;
|
| 413 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// connectors/brandMarks.tsx β WAVE 30, owner item 7 (rulings R3 + R4):
|
| 3 |
+
// THE ONE PLACE A CONNECTOR'S IDENTITY IS DRAWN.
|
| 4 |
+
//
|
| 5 |
+
// The owner, verbatim and for the third time: *"their Instagram and Tiktok logo
|
| 6 |
+
// to be fucking displayed, same with all logos under the Connectors module."*
|
| 7 |
+
//
|
| 8 |
+
// β THIS SUPERSEDES A RULE THAT WAS STILL SHIPPING. Wave-23 R8 said connector
|
| 9 |
+
// identity is a two-letter monogram in the chip family, and it was enforced β
|
| 10 |
+
// `verify_home.py:section_connectors` asserted a real mark could not appear.
|
| 11 |
+
// R4 replaces it FOR CONNECTOR IDENTITY ONLY. Everything else the design
|
| 12 |
+
// constitution says is untouched: no emojis anywhere, and no decorative
|
| 13 |
+
// third-party imagery outside this file's purpose, which is telling a person
|
| 14 |
+
// which company a row is about.
|
| 15 |
+
//
|
| 16 |
+
// ββ WAVE 33 Β· OWNER ITEM 6 / RULING R4 β THE PARAGRAPH BELOW IS SUPERSEDED FOR
|
| 17 |
+
// A COMPANY'S MARK, AND IT IS KEPT BECAUSE IT IS STILL RIGHT ABOUT WHAT IT WAS
|
| 18 |
+
// ACTUALLY DEFENDING. It read:
|
| 19 |
+
//
|
| 20 |
+
// "INLINE SVG, NEVER A FILE AND NEVER A REMOTE URL. There is no `assets/` or
|
| 21 |
+
// `icons/` directory in this app and there is not going to be one β¦ A remote
|
| 22 |
+
// logo would work today (no CSP header is set) and would be the one thing on
|
| 23 |
+
// the page that can be taken away by somebody else's outage."
|
| 24 |
+
//
|
| 25 |
+
// β THE RULE IT WAS PROTECTING IS **NO THIRD-PARTY ORIGIN**, and that rule is
|
| 26 |
+
// untouched: `/api/v1/brand/<name>` is OUR door, same-origin, session-gated,
|
| 27 |
+
// served off bytes that ship inside the image (`web/public/brand/`). Nobody
|
| 28 |
+
// else's outage can take it away, and there is still no `assets/` directory β
|
| 29 |
+
// there is a brand directory, which is a different thing with a route in front
|
| 30 |
+
// of it.
|
| 31 |
+
// β WHAT DID CHANGE IS THE OWNER'S VERDICT ON THE ARTWORK, twice now. Wave 30's
|
| 32 |
+
// R4 replaced wave 23's two-letter monogram with these hand-drawn marks; wave
|
| 33 |
+
// 33's R4 replaces the hand-drawn marks with each vendor's OFFICIAL artwork,
|
| 34 |
+
// because the honest sentence three paragraphs down β *"recognisable
|
| 35 |
+
// SIMPLIFICATIONS β¦ not the trademarked artwork"* β is exactly what the owner
|
| 36 |
+
// saw: *"Do not generate your own logo for Connectors, they look really uncanny
|
| 37 |
+
// /browse them the PNG, cut appropriately for our needs, verify visually."*
|
| 38 |
+
// A ruling that supersedes a rule leaves that rule's gates green
|
| 39 |
+
// ([[two-gates-can-assert-opposite-things]]); see `mailbox/G.md` G-2/G-3 for the
|
| 40 |
+
// four legs in `verify_automation_ui` / `picker_render.test.tsx` this moves.
|
| 41 |
+
//
|
| 42 |
+
// β THE HAND-DRAWN SET IS NOT DELETED. Every arm below still exists and is what
|
| 43 |
+
// renders when the door does not answer, so a 404, a 401 or a container without
|
| 44 |
+
// the files degrades to the wave-30 mark rather than to a broken-image glyph.
|
| 45 |
+
// Two of the arms are not fallbacks at all: `webhooks` and `scraper` are OURS,
|
| 46 |
+
// there is no vendor artwork to fetch, and they stay inline permanently.
|
| 47 |
+
//
|
| 48 |
+
// β ONE MODULE FOR THREE SURFACES, and that is the whole design. The trigger
|
| 49 |
+
// picker, the action menu and the Connectors directory all answer "which
|
| 50 |
+
// company is this?" β three copies of a logo set is three chances to add a
|
| 51 |
+
// platform in two places and forget the third, which is precisely the defect
|
| 52 |
+
// wave 30 exists to fix on the server side of the same question.
|
| 53 |
+
//
|
| 54 |
+
// β WHAT THESE ARE, HONESTLY: recognisable SIMPLIFICATIONS drawn from each
|
| 55 |
+
// brand's published silhouette and brand colour, at 16px, not the trademarked
|
| 56 |
+
// artwork. That is the right call at this size β the real Google `G` is a
|
| 57 |
+
// 500-byte path that renders as mush in a 15px box β and it is stated here so
|
| 58 |
+
// nobody "upgrades" them by pasting a vendor's asset file into a repo that has
|
| 59 |
+
// no place to put one.
|
| 60 |
+
//
|
| 61 |
+
// β THEME. Marks are brand-coloured and must survive BOTH themes, so no mark
|
| 62 |
+
// relies on pure black or pure white for its silhouette: TikTok's note is
|
| 63 |
+
// `currentColor` with its two brand offsets behind it, which is also how the
|
| 64 |
+
// real mark is constructed.
|
| 65 |
+
// ---------------------------------------------------------------------------
|
| 66 |
+
import type { ReactElement } from "react";
|
| 67 |
+
import { useId, useState } from "react";
|
| 68 |
+
|
| 69 |
+
import { API_V1 } from "../apiContract";
|
| 70 |
+
|
| 71 |
+
/**
|
| 72 |
+
* The canonical brand names this module can draw. Deliberately NOT the same
|
| 73 |
+
* strings as the connector keys or the trigger kinds: three vocabularies point
|
| 74 |
+
* AT this one, and folding them together would make a rename in any of the
|
| 75 |
+
* three a silent loss of an icon.
|
| 76 |
+
*/
|
| 77 |
+
export type BrandName =
|
| 78 |
+
| "instagram"
|
| 79 |
+
| "tiktok"
|
| 80 |
+
| "odoo"
|
| 81 |
+
| "google"
|
| 82 |
+
| "gmail"
|
| 83 |
+
| "stripe"
|
| 84 |
+
| "shopify"
|
| 85 |
+
| "webhooks"
|
| 86 |
+
| "scraper"
|
| 87 |
+
| "slack"
|
| 88 |
+
| "meta";
|
| 89 |
+
|
| 90 |
+
/**
|
| 91 |
+
* Trigger and action KIND -> brand.
|
| 92 |
+
*
|
| 93 |
+
* β KEYED ON THE KIND AND NOT ON THE CONNECTOR, and the reason is R3 itself:
|
| 94 |
+
* after this wave Instagram and TikTok share `connector.key === "scraper"`, so
|
| 95 |
+
* the connector can no longer tell them apart. The kind is the only thing that
|
| 96 |
+
* still distinguishes the two products, which is exactly why the picker's own
|
| 97 |
+
* `TriggerMark` has always been keyed this way.
|
| 98 |
+
*
|
| 99 |
+
* β An unmapped kind returns null and the caller draws its existing glyph β a
|
| 100 |
+
* trigger the engine adds tomorrow renders plainly rather than not at all.
|
| 101 |
+
*/
|
| 102 |
+
export const BRAND_OF_KIND: Record<string, BrandName> = {
|
| 103 |
+
ig_profile_match: "instagram",
|
| 104 |
+
tiktok_profile_match: "tiktok",
|
| 105 |
+
enrich_instagram: "instagram",
|
| 106 |
+
enrich_tiktok: "tiktok",
|
| 107 |
+
field_instagram: "instagram",
|
| 108 |
+
};
|
| 109 |
+
|
| 110 |
+
/**
|
| 111 |
+
* Connector/provider KEY -> brand, for the Connectors directory and for the
|
| 112 |
+
* collapsed connector nests in both automation menus.
|
| 113 |
+
*
|
| 114 |
+
* β `scraper` and `webhooks` are OURS, not brands β they get house glyphs in
|
| 115 |
+
* `currentColor` so they sit in the chip family the way they always have. They
|
| 116 |
+
* are in this map rather than special-cased at the call site so that "what mark
|
| 117 |
+
* does this row wear" has ONE answer, whoever is asking.
|
| 118 |
+
*/
|
| 119 |
+
export const BRAND_OF_CONNECTOR: Record<string, BrandName> = {
|
| 120 |
+
odoo: "odoo",
|
| 121 |
+
// ββ WAVE 32 Β· OWNER ITEM 12 / R6 β THESE TWO MARKS ARE CURRENTLY UNREACHABLE, AND KEPT.
|
| 122 |
+
// `oauth_connect.offered("google")` is False, so the directory serves no `google` row and this
|
| 123 |
+
// map is never asked for either of these. They stay for the reason the ruling is worded as
|
| 124 |
+
// *"HIDDEN until they are real"* rather than "removed": the blocker is money, not code (D-45 β
|
| 125 |
+
// Google's CASA verification, ~$540β1,800/yr, for the `gmail.readonly` scope). The day that is
|
| 126 |
+
// paid for, ONE key flips server-side and the card comes back wearing its own logo. Deleting
|
| 127 |
+
// the art would turn a one-key restore into a re-draw, and would leave the next reader
|
| 128 |
+
// wondering where Gmail's mark went as well as where Gmail went.
|
| 129 |
+
google: "google",
|
| 130 |
+
gmail: "gmail",
|
| 131 |
+
stripe: "stripe",
|
| 132 |
+
shopify: "shopify",
|
| 133 |
+
scraper: "scraper",
|
| 134 |
+
webhooks: "webhooks",
|
| 135 |
+
instagram: "instagram",
|
| 136 |
+
tiktok: "tiktok",
|
| 137 |
+
// β WAVE 31 Β· R7 β the Nango breadth play's first two marks. `meta_ads` is the KEYCHAIN
|
| 138 |
+
// connector (a token an admin pastes today); `meta` would be the delegated-OAuth door the same
|
| 139 |
+
// company owns, so BOTH keys point at one mark rather than the map growing a near-duplicate.
|
| 140 |
+
slack: "slack",
|
| 141 |
+
meta: "meta",
|
| 142 |
+
meta_ads: "meta",
|
| 143 |
+
};
|
| 144 |
+
|
| 145 |
+
/** The house frame every mark is drawn in. 16Γ16 user units, sized by the caller. */
|
| 146 |
+
function frame(size: number) {
|
| 147 |
+
return { width: size, height: size, viewBox: "0 0 16 16", "aria-hidden": true } as const;
|
| 148 |
+
}
|
| 149 |
+
|
| 150 |
+
/**
|
| 151 |
+
* β TIKTOK'S NOTE, DRAWN THREE TIMES. The real mark is one glyph offset in
|
| 152 |
+
* cyan and magenta behind a solid copy; drawing only the solid copy loses the
|
| 153 |
+
* brand entirely at this size, and drawing the offsets in black loses it in
|
| 154 |
+
* dark mode. The solid copy is `currentColor` so it inherits the row.
|
| 155 |
+
*/
|
| 156 |
+
const TT_NOTE =
|
| 157 |
+
"M9.05 1.9h2.02c.13 1.2.87 2.13 2.03 2.3v2.03c-.78 0-1.53-.2-2.18-.58v3.98"
|
| 158 |
+
+ "a3.62 3.62 0 1 1-3.62-3.62c.16 0 .32.01.48.03v2.06a1.6 1.6 0 1 0 1.27 1.56z";
|
| 159 |
+
|
| 160 |
+
/**
|
| 161 |
+
* Brands we hold OFFICIAL artwork for, i.e. the ones `/api/v1/brand/<name>`
|
| 162 |
+
* answers 200 on. β Derived from one place β the server's own directory listing
|
| 163 |
+
* would be a round trip on every chip, and a hardcoded list here would drift the
|
| 164 |
+
* moment a file is added, so `verify_meta::section_brand_door` pins this set
|
| 165 |
+
* against the files on disk in BOTH directions. Adding a mark is: drop the PNG
|
| 166 |
+
* in `web/public/brand/`, add its SOURCES.md row, add the key here.
|
| 167 |
+
*
|
| 168 |
+
* β `webhooks` and `scraper` are ABSENT ON PURPOSE and must stay absent: they are
|
| 169 |
+
* house glyphs in `currentColor`, there is no vendor and no artwork to fetch, and
|
| 170 |
+
* asking the door for one would be a guaranteed 404 on every render.
|
| 171 |
+
*/
|
| 172 |
+
const OFFICIAL: ReadonlySet<BrandName> = new Set<BrandName>([
|
| 173 |
+
"instagram", "tiktok", "odoo", "google", "gmail", "slack", "meta",
|
| 174 |
+
"stripe", "shopify",
|
| 175 |
+
]);
|
| 176 |
+
|
| 177 |
+
/** The door R4 mandates. Relative, so it is same-origin by construction β the
|
| 178 |
+
* one property the superseded "never a remote URL" rule was really protecting. */
|
| 179 |
+
export function brandSrc(name: BrandName): string {
|
| 180 |
+
return `${API_V1}/brand/${name}`;
|
| 181 |
+
}
|
| 182 |
+
|
| 183 |
+
export function BrandMark({
|
| 184 |
+
name,
|
| 185 |
+
size = 15,
|
| 186 |
+
}: {
|
| 187 |
+
name: BrandName;
|
| 188 |
+
size?: number;
|
| 189 |
+
}): ReactElement | null {
|
| 190 |
+
const f = frame(size);
|
| 191 |
+
// ββ WAVE 33 Β· R4 β THE OFFICIAL MARK, FROM OUR OWN DOOR, WITH THE WAVE-30 ART
|
| 192 |
+
// BEHIND IT. `useState` rather than a bare `<img>` because a door that cannot
|
| 193 |
+
// answer must degrade to a mark and never to a browser's broken-image glyph β
|
| 194 |
+
// which is the one outcome worse than the hand-drawn logo the owner complained
|
| 195 |
+
// about. `onError` fires for a 404, a 401 after a session expires, and a
|
| 196 |
+
// container built without `web/public/brand/`, and each of those falls through
|
| 197 |
+
// to the arms below.
|
| 198 |
+
// β Hooks run for EVERY name, including the two house glyphs, because a hook
|
| 199 |
+
// cannot sit behind a conditional return β same reason `useId` is unconditional.
|
| 200 |
+
const [failed, setFailed] = useState(false);
|
| 201 |
+
// Per-instance, for the reason spelled out at the `<defs>` below. It must also run BEFORE
|
| 202 |
+
// the official-image return: `failed` flips on `onError`, and a hook first reached on that
|
| 203 |
+
// re-render is one more hook than the previous render β React #310 on the exact fallback
|
| 204 |
+
// path this component exists to provide.
|
| 205 |
+
const gradId = `aios-brand-ig-${useId()}`;
|
| 206 |
+
if (OFFICIAL.has(name) && !failed)
|
| 207 |
+
return (
|
| 208 |
+
<img
|
| 209 |
+
src={brandSrc(name)}
|
| 210 |
+
width={size}
|
| 211 |
+
height={size}
|
| 212 |
+
alt=""
|
| 213 |
+
aria-hidden="true"
|
| 214 |
+
// β `block` kills the inline-baseline gap that would make a 15px logo sit
|
| 215 |
+
// a pixel lower than the 15px SVG beside it in the same chip row.
|
| 216 |
+
style={{ display: "block", width: size, height: size }}
|
| 217 |
+
onError={() => setFailed(true)}
|
| 218 |
+
/>
|
| 219 |
+
);
|
| 220 |
+
if (name === "instagram")
|
| 221 |
+
return (
|
| 222 |
+
<svg {...f} fill="none">
|
| 223 |
+
{/*
|
| 224 |
+
ββ THE GRADIENT ID IS PER-INSTANCE, AND THE FIXED ONE WAS A REAL BUG β FOUND BY A
|
| 225 |
+
PICTURE, NOT BY A GATE. It shipped for an hour as the constant `aios-brand-ig`, on the
|
| 226 |
+
reasoning that duplicate ids resolve to the FIRST definition and every definition is
|
| 227 |
+
byte-identical, so it cannot matter. MEASURED in the connectors shot: the Scraper card
|
| 228 |
+
holds an Instagram mark inside a COLLAPSED `<details>`, a second card below holds a
|
| 229 |
+
visible one β and the visible one painted NOTHING. A closed `<details>` is
|
| 230 |
+
`content-visibility: hidden`, its subtree is not rendered, and a paint server defined
|
| 231 |
+
inside a skipped subtree does not resolve for a user outside it. "The first definition
|
| 232 |
+
wins" IS the failure: whichever copy happens to be hidden decides for all of them.
|
| 233 |
+
β Nothing about `<details>` is special β `display:none` does the same. Any page holding
|
| 234 |
+
two of this mark with the first one hidden loses the second.
|
| 235 |
+
β `useId` rather than a module counter, so the markup stays DETERMINISTIC for a given
|
| 236 |
+
tree β the render gates could not assert against a random id β and stable across a
|
| 237 |
+
server render and its hydration.
|
| 238 |
+
β Every check that looks for this mark matches the PREFIX `url(#aios-brand-ig`.
|
| 239 |
+
*/}
|
| 240 |
+
<defs>
|
| 241 |
+
{/* β `userSpaceOnUse` IS LOAD-BEARING AND ITS ABSENCE LOOKED FINE. The default is
|
| 242 |
+
`objectBoundingBox`, where the coordinates are FRACTIONS of the shape's box β so
|
| 243 |
+
`1,15 β 15,1` put the whole gradient vector far outside every path and each one
|
| 244 |
+
painted a single clamped stop. The mark still rendered, still read as Instagram,
|
| 245 |
+
and was simply flat pink: a defect only a picture catches, which is why one was
|
| 246 |
+
taken ([[ui-invisible-to-assertions]]). In user space the numbers mean viewBox
|
| 247 |
+
units, which is what they were written as. */}
|
| 248 |
+
<linearGradient
|
| 249 |
+
id={gradId} gradientUnits="userSpaceOnUse"
|
| 250 |
+
x1="2" y1="14" x2="14" y2="2"
|
| 251 |
+
>
|
| 252 |
+
<stop offset="0" stopColor="#FEDA75" />
|
| 253 |
+
<stop offset="0.32" stopColor="#FA7E1E" />
|
| 254 |
+
<stop offset="0.62" stopColor="#D62976" />
|
| 255 |
+
<stop offset="1" stopColor="#962FBF" />
|
| 256 |
+
</linearGradient>
|
| 257 |
+
</defs>
|
| 258 |
+
<rect
|
| 259 |
+
x="1.7" y="1.7" width="12.6" height="12.6" rx="3.7"
|
| 260 |
+
stroke={`url(#${gradId})`} strokeWidth="1.5"
|
| 261 |
+
/>
|
| 262 |
+
<circle cx="8" cy="8" r="3" stroke={`url(#${gradId})`} strokeWidth="1.5" />
|
| 263 |
+
<circle cx="11.6" cy="4.4" r="0.95" fill={`url(#${gradId})`} />
|
| 264 |
+
</svg>
|
| 265 |
+
);
|
| 266 |
+
if (name === "tiktok")
|
| 267 |
+
return (
|
| 268 |
+
<svg {...f}>
|
| 269 |
+
<path d={TT_NOTE} fill="#25F4EE" transform="translate(-0.9 -0.5)" />
|
| 270 |
+
<path d={TT_NOTE} fill="#FE2C55" transform="translate(0.9 0.5)" />
|
| 271 |
+
<path d={TT_NOTE} fill="currentColor" />
|
| 272 |
+
</svg>
|
| 273 |
+
);
|
| 274 |
+
if (name === "odoo")
|
| 275 |
+
return (
|
| 276 |
+
<svg {...f}>
|
| 277 |
+
{/* Odoo's brand purple, and its wordmark's twin `o`s β the part of that
|
| 278 |
+
wordmark that survives being shrunk to 15px. */}
|
| 279 |
+
<rect x="1" y="1" width="14" height="14" rx="3.4" fill="#714B67" />
|
| 280 |
+
<circle cx="5.7" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
|
| 281 |
+
<circle cx="10.4" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
|
| 282 |
+
</svg>
|
| 283 |
+
);
|
| 284 |
+
if (name === "google")
|
| 285 |
+
return (
|
| 286 |
+
<svg {...f} fill="none" strokeWidth="2.3">
|
| 287 |
+
{/* The four-arc G. Each arc is one brand colour, and the bar into the
|
| 288 |
+
centre is what makes it a G rather than a ring. */}
|
| 289 |
+
<path d="M4.46 4.46A5 5 0 0 1 11.54 4.46" stroke="#EA4335" strokeLinecap="round" />
|
| 290 |
+
<path d="M4.46 4.46A5 5 0 0 0 4.46 11.54" stroke="#FBBC05" strokeLinecap="round" />
|
| 291 |
+
<path d="M4.46 11.54A5 5 0 0 0 11.54 11.54" stroke="#34A853" strokeLinecap="round" />
|
| 292 |
+
<path d="M11.54 11.54A5 5 0 0 0 13 8" stroke="#4285F4" strokeLinecap="round" />
|
| 293 |
+
<path d="M13 8H8.4" stroke="#4285F4" />
|
| 294 |
+
</svg>
|
| 295 |
+
);
|
| 296 |
+
if (name === "gmail")
|
| 297 |
+
return (
|
| 298 |
+
<svg {...f} fill="none" stroke="#EA4335" strokeWidth="1.5" strokeLinejoin="round">
|
| 299 |
+
<rect x="1.6" y="3.6" width="12.8" height="9" rx="1.6" />
|
| 300 |
+
<path d="m2 4.4 6 4.6 6-4.6" />
|
| 301 |
+
</svg>
|
| 302 |
+
);
|
| 303 |
+
// β WAVE 31 Β· R7. Slack's mark is FOUR bars in four brand colours, drawn as rounded rects
|
| 304 |
+
// rather than the true interlocking glyph: at 15px the real lozenges collapse into mud, and a
|
| 305 |
+
// mark nobody can identify is worse than a two-letter tile. Colours are Slack's own.
|
| 306 |
+
if (name === "slack")
|
| 307 |
+
return (
|
| 308 |
+
<svg {...f}>
|
| 309 |
+
<rect x="2" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#36C5F0" />
|
| 310 |
+
<rect x="8.6" y="6.6" width="5.4" height="2.8" rx="1.4" fill="#2EB67D" />
|
| 311 |
+
<rect x="6.6" y="2" width="2.8" height="5.4" rx="1.4" fill="#ECB22E" />
|
| 312 |
+
<rect x="6.6" y="8.6" width="2.8" height="5.4" rx="1.4" fill="#E01E5A" />
|
| 313 |
+
</svg>
|
| 314 |
+
);
|
| 315 |
+
// Meta's infinity loop, as two overlapping strokes in the brand blue. β `fill="none"` with a
|
| 316 |
+
// round cap: filled, the two lobes merge into a blob at this size.
|
| 317 |
+
if (name === "meta")
|
| 318 |
+
return (
|
| 319 |
+
<svg {...f} fill="none">
|
| 320 |
+
<path
|
| 321 |
+
d="M2.2 10.4c0-3 1.5-5.2 3.3-5.2 1.2 0 2 .8 3 2.4l1 1.6c.9 1.4 1.5 2.1 2.2 2.1.8 0
|
| 322 |
+
1.3-.8 1.3-2.1 0-1.6-.7-3.4-2-3.4-.9 0-1.7.7-2.6 2"
|
| 323 |
+
stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
|
| 324 |
+
/>
|
| 325 |
+
<path
|
| 326 |
+
d="M2.2 10.4c0 1.3.6 2 1.5 2 .8 0 1.4-.5 2.5-2.2l3-4.6"
|
| 327 |
+
stroke="#0081FB" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round"
|
| 328 |
+
/>
|
| 329 |
+
</svg>
|
| 330 |
+
);
|
| 331 |
+
if (name === "stripe")
|
| 332 |
+
return (
|
| 333 |
+
<svg {...f}>
|
| 334 |
+
<rect x="1" y="1" width="14" height="14" rx="3.4" fill="#635BFF" />
|
| 335 |
+
<path
|
| 336 |
+
d="M10.5 5.6a2.3 2.3 0 0 0-3.6 1.2c0 2.1 4.1 1.5 4.1 3.5a2.4 2.4 0 0 1-3.7 1.3"
|
| 337 |
+
fill="none" stroke="#FFFFFF" strokeWidth="1.5" strokeLinecap="round"
|
| 338 |
+
/>
|
| 339 |
+
</svg>
|
| 340 |
+
);
|
| 341 |
+
if (name === "shopify")
|
| 342 |
+
return (
|
| 343 |
+
<svg {...f}>
|
| 344 |
+
{/* The bag, in Shopify's two greens: the darker one is the handle, which
|
| 345 |
+
is the part that reads as a bag rather than as a box. */}
|
| 346 |
+
<path d="M3.5 5.2h9l-.75 8.4a.9.9 0 0 1-.9.8H5.15a.9.9 0 0 1-.9-.8z" fill="#95BF47" />
|
| 347 |
+
<path
|
| 348 |
+
d="M6.1 6.4V4.5a1.9 1.9 0 0 1 3.8 0v1.9"
|
| 349 |
+
fill="none" stroke="#5E8E3E" strokeWidth="1.4" strokeLinecap="round"
|
| 350 |
+
/>
|
| 351 |
+
</svg>
|
| 352 |
+
);
|
| 353 |
+
/*
|
| 354 |
+
β THE LAST TWO ARE OURS, NOT BRANDS β `currentColor`, house stroke weight,
|
| 355 |
+
so they sit in the chip family beside the coloured logos rather than
|
| 356 |
+
pretending to be a company. Keeping them here is what lets every caller ask
|
| 357 |
+
one question instead of two.
|
| 358 |
+
*/
|
| 359 |
+
if (name === "webhooks")
|
| 360 |
+
return (
|
| 361 |
+
<svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
|
| 362 |
+
strokeLinecap="round" strokeLinejoin="round">
|
| 363 |
+
<path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
|
| 364 |
+
<path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
|
| 365 |
+
<path d="M6.2 8h3.6" />
|
| 366 |
+
</svg>
|
| 367 |
+
);
|
| 368 |
+
if (name === "scraper")
|
| 369 |
+
return (
|
| 370 |
+
<svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
|
| 371 |
+
strokeLinecap="round" strokeLinejoin="round">
|
| 372 |
+
{/* A magnifier over a grid of rows: it reads a catalogue of profiles and
|
| 373 |
+
makes records out of what matches β which is what the bucket does,
|
| 374 |
+
and it is deliberately NOT either platform's mark, because the whole
|
| 375 |
+
point of R3 is that the bucket is neither one of them. */}
|
| 376 |
+
<path d="M2.6 3.4h10.8M2.6 6.2h5.2M2.6 9h3.4" />
|
| 377 |
+
<circle cx="10.4" cy="10.2" r="3" />
|
| 378 |
+
<path d="m12.6 12.4 1.6 1.6" />
|
| 379 |
+
</svg>
|
| 380 |
+
);
|
| 381 |
+
return null;
|
| 382 |
+
}
|
| 383 |
+
|
| 384 |
+
/**
|
| 385 |
+
* Does this kind wear a LOGO rather than a house glyph?
|
| 386 |
+
*
|
| 387 |
+
* β IT EXISTS BECAUSE THE TILE HAS TO CHANGE TOO, and forgetting that would have shipped the
|
| 388 |
+
* defect quietly: `.autox-card-mark` paints a blue tint and sets `color: var(--lp-blue-deep)`,
|
| 389 |
+
* so TikTok's note β which is `currentColor` by design, so it survives dark mode β would have
|
| 390 |
+
* rendered BLUE, and Instagram's gradient would have sat on a coloured chip. The caller adds
|
| 391 |
+
* `is-brand`, which neutralises both. One predicate, so the mark and its tile cannot disagree
|
| 392 |
+
* about whether a row is branded.
|
| 393 |
+
*/
|
| 394 |
+
export function hasBrandKind(kind: string): boolean {
|
| 395 |
+
return Boolean(BRAND_OF_KIND[kind]);
|
| 396 |
+
}
|
| 397 |
+
|
| 398 |
+
/** The connector-key twin of `hasBrandKind`, for the directory's tiles. */
|
| 399 |
+
export function hasBrandConnector(key: string): boolean {
|
| 400 |
+
return Boolean(BRAND_OF_CONNECTOR[key]);
|
| 401 |
+
}
|
| 402 |
+
|
| 403 |
+
/** The mark for a trigger or action KIND, or null when it is not a branded one. */
|
| 404 |
+
export function brandForKind(kind: string, size = 15): ReactElement | null {
|
| 405 |
+
const name = BRAND_OF_KIND[kind];
|
| 406 |
+
return name ? <BrandMark name={name} size={size} /> : null;
|
| 407 |
+
}
|
| 408 |
+
|
| 409 |
+
/** The mark for a connector/provider KEY, or null when we have no logo for it. */
|
| 410 |
+
export function brandForConnector(key: string, size = 15): ReactElement | null {
|
| 411 |
+
const name = BRAND_OF_CONNECTOR[key];
|
| 412 |
+
return name ? <BrandMark name={name} size={size} /> : null;
|
| 413 |
+
}
|
web/src/customer-grid/GridChat.tsx
CHANGED
|
@@ -1,512 +1,512 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// customer-grid / GridChat.tsx β the docked chat for ANY database view (W37-T40, R2, R10, C6).
|
| 3 |
-
//
|
| 4 |
-
// Owner items 10 and 11 are ONE feature (ruling R2): the chat IS the builder. This is its shell β
|
| 5 |
-
// the conversation surface every later ticket in the lane hangs a power off. T42 gives it the
|
| 6 |
-
// schema to answer from, T43 the view controls, T44 the Custom View's code, T45 the confirmed
|
| 7 |
-
// record edit.
|
| 8 |
-
//
|
| 9 |
-
// ββ IT REACHES INTO NOTHING. Contract C6: every action is a callback the host supplies, and
|
| 10 |
-
// EVERY PROP IS REQUIRED. An optional prop is how a panel ships mounted-but-inert β the feature is
|
| 11 |
-
// whole, the gate is green, and the one line that would have passed the callback was never
|
| 12 |
-
// written. This repo shipped five of those in a single wave. A required prop makes the omission a
|
| 13 |
-
// compile error in the mounting file, which is where a person can see it.
|
| 14 |
-
//
|
| 15 |
-
// β THE SHAPE IS THE ONE THIS PRODUCT ALREADY HAS, not a third chat look. `AutomationChat` and
|
| 16 |
-
// `AssistantPage` both render a centred opening while the transcript is empty, then a log with the
|
| 17 |
-
// SAME composer moved to the foot; `FieldAgentChat` reuses the same composer classes rather than
|
| 18 |
-
// drawing a second one. Copying that is not laziness, it is the reason the owner cannot tell which
|
| 19 |
-
// surface was built by whom.
|
| 20 |
-
//
|
| 21 |
-
// β NO `import.meta.env` ANYWHERE IN THIS FILE'S GRAPH, and the constraint is load-bearing rather
|
| 22 |
-
// than stylistic: the gate renders this component from a CommonJS build, and `import.meta` cannot
|
| 23 |
-
// be required from one. `AutomationChat`'s own header records that exact crash. The imports below
|
| 24 |
-
// are `react` + `./gridChat` + the stylesheet, and nothing else.
|
| 25 |
-
// ---------------------------------------------------------------------------
|
| 26 |
-
|
| 27 |
-
import { useCallback, useEffect, useRef, useState } from "react";
|
| 28 |
-
|
| 29 |
-
import {
|
| 30 |
-
answered,
|
| 31 |
-
asked,
|
| 32 |
-
composerHint,
|
| 33 |
-
editSummary,
|
| 34 |
-
emptyChat,
|
| 35 |
-
failed,
|
| 36 |
-
isBusy,
|
| 37 |
-
noted,
|
| 38 |
-
proposedEdits,
|
| 39 |
-
readIntent,
|
| 40 |
-
runSentence,
|
| 41 |
-
wrote,
|
| 42 |
-
} from "./gridChat";
|
| 43 |
-
import type {
|
| 44 |
-
GridChatAnswer,
|
| 45 |
-
GridChatEdit,
|
| 46 |
-
GridChatField,
|
| 47 |
-
GridChatRunResult,
|
| 48 |
-
GridChatState,
|
| 49 |
-
GridChatTurn,
|
| 50 |
-
} from "./gridChat";
|
| 51 |
-
import "./gridChat.css";
|
| 52 |
-
|
| 53 |
-
// β RE-EXPORTED SO THE MOUNTING FILE TAKES ONE IMPORT. The types live in `gridChat.ts` (they have
|
| 54 |
-
// to: the state machine is typed by them and that module must stay React-free), but a host that
|
| 55 |
-
// had to import the component from here and its types from there would be one refactor away from
|
| 56 |
-
// the two drifting. Published to C in mailbox E-4 as a single import line.
|
| 57 |
-
export type {
|
| 58 |
-
GridChatAnswer,
|
| 59 |
-
GridChatEdit,
|
| 60 |
-
GridChatField,
|
| 61 |
-
GridChatRunResult,
|
| 62 |
-
GridChatState,
|
| 63 |
-
GridChatTurn,
|
| 64 |
-
};
|
| 65 |
-
|
| 66 |
-
/**
|
| 67 |
-
* What the host asks the chat to do about the view. β DELIBERATELY NARROW: this is the vocabulary
|
| 68 |
-
* `assistant build_view` already speaks, minus what it cannot express. There is no `rhs` in that
|
| 69 |
-
* tool schema, so a field-versus-field condition is not sayable
|
| 70 |
-
* [[assistant-build-view-is-a-subset]] β W37-T43 has to SAY it cannot rather than fail quietly.
|
| 71 |
-
*/
|
| 72 |
-
export interface GridChatViewSpec {
|
| 73 |
-
/**
|
| 74 |
-
* β RESERVED AND DELIBERATELY NOT POPULATED BY `readIntent` YET. The panel understands
|
| 75 |
-
* sort/group/colour from a sentence; a real FILTER needs the condition vocabulary the host owns,
|
| 76 |
-
* so this is the slot C fills rather than a field the panel quietly leaves empty. Named here so
|
| 77 |
-
* it reads as a contract with a known gap instead of a channel nobody noticed was dead
|
| 78 |
-
* [[flag-shipped-without-its-writer]].
|
| 79 |
-
*/
|
| 80 |
-
filter?: unknown;
|
| 81 |
-
sortBy?: string;
|
| 82 |
-
groupBy?: string;
|
| 83 |
-
colorBy?: string;
|
| 84 |
-
}
|
| 85 |
-
|
| 86 |
-
export interface GridChatProps {
|
| 87 |
-
/** The host owns the toggle. The panel never closes itself except through `onClose`. */
|
| 88 |
-
open: boolean;
|
| 89 |
-
onClose: () => void;
|
| 90 |
-
/** What this chat is reading, in the person's words. Appears in the header and the placeholder. */
|
| 91 |
-
databaseLabel: string;
|
| 92 |
-
/** The columns the chat may reason about. The host decides; the chat never discovers. */
|
| 93 |
-
schema: GridChatField[];
|
| 94 |
-
rowCount: number;
|
| 95 |
-
/**
|
| 96 |
-
* β R10's BOUND, EXPRESSED AS AN AFFORDANCE. `false` means the edit power is not OFFERED, not
|
| 97 |
-
* that it is offered and then refused. The chat is not a privilege escalation: a caller whose
|
| 98 |
-
* own permissions would refuse the write must not be invited to compose one
|
| 99 |
-
* [[permitted-is-not-answerable]].
|
| 100 |
-
*/
|
| 101 |
-
canEdit: boolean;
|
| 102 |
-
/** (a) answer a question about this database. */
|
| 103 |
-
onDescribe: (question: string) => Promise<GridChatAnswer>;
|
| 104 |
-
/** (b) change filter, sort, group or colour on the ACTIVE view. */
|
| 105 |
-
onApplyView: (spec: GridChatViewSpec) => void;
|
| 106 |
-
/** (b, undo half) put the view back the way it was. */
|
| 107 |
-
onUndoView: () => void;
|
| 108 |
-
/** (d) write the cells the person just confirmed. β Reached only from the confirm control. */
|
| 109 |
-
onWriteCells: (edits: GridChatEdit[]) => Promise<void>;
|
| 110 |
-
/** (c) run the Custom View's code and report what happened. */
|
| 111 |
-
onRunScript: (code: string) => Promise<GridChatRunResult>;
|
| 112 |
-
}
|
| 113 |
-
|
| 114 |
-
/** The send mark. β The Assistant's own path, point for point: a second arrow drawn slightly
|
| 115 |
-
* differently is precisely how two surfaces stop looking like one product. */
|
| 116 |
-
function SendMark() {
|
| 117 |
-
return (
|
| 118 |
-
<svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true" fill="none">
|
| 119 |
-
<path d="M8 13V3.6M4 7.4 8 3.4l4 4" stroke="currentColor" strokeWidth="1.5"
|
| 120 |
-
strokeLinecap="round" strokeLinejoin="round" />
|
| 121 |
-
</svg>
|
| 122 |
-
);
|
| 123 |
-
}
|
| 124 |
-
|
| 125 |
-
export default function GridChat(props: GridChatProps) {
|
| 126 |
-
const {
|
| 127 |
-
open, onClose, databaseLabel, schema, rowCount, canEdit,
|
| 128 |
-
onDescribe, onApplyView, onUndoView, onWriteCells, onRunScript,
|
| 129 |
-
} = props;
|
| 130 |
-
|
| 131 |
-
const [state, setState] = useState<GridChatState>(emptyChat);
|
| 132 |
-
const [draft, setDraft] = useState("");
|
| 133 |
-
const [writing, setWriting] = useState(false);
|
| 134 |
-
const logRef = useRef<HTMLDivElement | null>(null);
|
| 135 |
-
const busy = isBusy(state);
|
| 136 |
-
|
| 137 |
-
// β THE UNUSED-POWER GUARD. `onApplyView`, `onUndoView` and `onRunScript` are wired by W37-T43
|
| 138 |
-
// and W37-T44; naming them here keeps them REQUIRED props from the first mount, so C's wiring
|
| 139 |
-
// lands with the shell rather than being remembered two tickets later. `void` is the honest
|
| 140 |
-
// spelling of "held, not yet called" and it survives `noUnusedLocals`.
|
| 141 |
-
// β WHERE EACH CALLBACK IS ACTUALLY REACHED, because saying so is the only thing that stops a
|
| 142 |
-
// required prop becoming a decorative one: `onApplyView` from `send` (T43), `onUndoView` from the
|
| 143 |
-
// Undo control in the foot row, `onRunScript` from `runScript` below, which `send` calls when the
|
| 144 |
-
// host returns generated code (T44), `onWriteCells` from the confirm and the undo (T45, R10).
|
| 145 |
-
|
| 146 |
-
// The transcript follows the newest turn. Guarded on the ref because the log is not rendered at
|
| 147 |
-
// all while the conversation is empty (see the opening below).
|
| 148 |
-
useEffect(() => {
|
| 149 |
-
const log = logRef.current;
|
| 150 |
-
if (log) log.scrollTop = log.scrollHeight;
|
| 151 |
-
}, [state.turns.length, busy]);
|
| 152 |
-
|
| 153 |
-
// β DECLARED BEFORE `send`, AND THE ORDER IS LOAD-BEARING RATHER THAN TIDY. `send`'s
|
| 154 |
-
// dependency array names `runScript`, and a dependency array is evaluated AT RENDER, not
|
| 155 |
-
// when the callback fires. With `runScript` declared after `send` that array reads a `const`
|
| 156 |
-
// in its temporal dead zone and the panel throws `Cannot access 'runScript' before
|
| 157 |
-
// initialization` on its FIRST paint. β `tsc` does not catch it: it is a runtime TDZ, and
|
| 158 |
-
// the build was green with the crash in it.
|
| 159 |
-
/**
|
| 160 |
-
* β W37-T44 β THE CHAT WRITES THE CUSTOM VIEW'S CODE AND RUNS IT.
|
| 161 |
-
* β THE SANDBOX IS NOT WIDENED TO MAKE A GENERATED SCRIPT WORK. `onRunScript` is the host's
|
| 162 |
-
* ordinary run door, the same one a hand-typed script goes through, so a script the chat wrote
|
| 163 |
-
* has exactly the powers a person's own script has and no more. A failure is REPORTED and the
|
| 164 |
-
* code is left in the editor to be fixed by hand, never blanked.
|
| 165 |
-
*/
|
| 166 |
-
const runScript = useCallback((code: string) => {
|
| 167 |
-
void (async () => {
|
| 168 |
-
try {
|
| 169 |
-
const result = await onRunScript(code);
|
| 170 |
-
setState((s) => noted(s, runSentence(result)));
|
| 171 |
-
} catch (err) {
|
| 172 |
-
const why = err instanceof Error && err.message ? err.message : "";
|
| 173 |
-
setState((s) => noted(s, runSentence({ ok: false, error: why })));
|
| 174 |
-
}
|
| 175 |
-
})();
|
| 176 |
-
}, [onRunScript]);
|
| 177 |
-
|
| 178 |
-
const send = useCallback(() => {
|
| 179 |
-
const said = draft.trim();
|
| 180 |
-
if (!said || busy) return;
|
| 181 |
-
setState((s) => asked(s, said));
|
| 182 |
-
setDraft("");
|
| 183 |
-
|
| 184 |
-
// ββ W37-T42/T43/T44 β READ THE SENTENCE BEFORE SPENDING ANYTHING ON IT.
|
| 185 |
-
// β THE REFUSAL BRANCH IS THE POINT OF T42 AND IT COSTS NOTHING. D-339's defect is an agent
|
| 186 |
-
// that cannot read the database answering from words alone and inventing a number. The panel
|
| 187 |
-
// HOLDS the schema, so a question naming a field this database does not have is answered here,
|
| 188 |
-
// truthfully, without a model call that could only guess.
|
| 189 |
-
const intent = readIntent(schema, databaseLabel, said);
|
| 190 |
-
if (intent.refusal) {
|
| 191 |
-
setState((s) => answered(s, said, { text: intent.refusal!, unanswerable: true }));
|
| 192 |
-
return;
|
| 193 |
-
}
|
| 194 |
-
// β ...and a question the panel already knows the answer to is not a paid round trip either.
|
| 195 |
-
if (intent.localAnswer) {
|
| 196 |
-
setState((s) => answered(s, said, { text: intent.localAnswer! }));
|
| 197 |
-
return;
|
| 198 |
-
}
|
| 199 |
-
if (intent.kind === "view") {
|
| 200 |
-
// T43: the VIEW changes through the host's callback (C6), and what could NOT be expressed is
|
| 201 |
-
// named rather than dropped [[assistant-build-view-is-a-subset]].
|
| 202 |
-
if (intent.view) onApplyView(intent.view);
|
| 203 |
-
const applied = intent.view
|
| 204 |
-
? "The view has been changed. Ask again or press Undo to put it back."
|
| 205 |
-
: "I could not tell which field you meant, so the view is unchanged.";
|
| 206 |
-
setState((s) => answered(s, said, {
|
| 207 |
-
text: intent.cannot ? `${applied} ${intent.cannot}` : applied,
|
| 208 |
-
}));
|
| 209 |
-
return;
|
| 210 |
-
}
|
| 211 |
-
|
| 212 |
-
void (async () => {
|
| 213 |
-
try {
|
| 214 |
-
const answer = await onDescribe(said);
|
| 215 |
-
// β THE PROPOSAL BRANCH IS HERE AND NOT IN THE HOST. A host that returned edits and also
|
| 216 |
-
// wrote them would make the confirm cosmetic; the panel decides that edits mean "show the
|
| 217 |
-
// person first", so there is exactly one place that decision can be got wrong.
|
| 218 |
-
// β NO CAST. `GridChatAnswer.edits` is a declared part of the contract now, so the host
|
| 219 |
-
// reads the same channel this line does; it used to be an `as` and the two could drift.
|
| 220 |
-
const edits = answer?.edits;
|
| 221 |
-
setState((s) => (canEdit && Array.isArray(edits) && edits.length
|
| 222 |
-
? proposedEdits(s, said, answer.text, edits)
|
| 223 |
-
: answered(s, said, answer)));
|
| 224 |
-
// β W37-T44 β AND THIS BRANCH IS THE WHOLE POINT OF THE TICKET. The first draft classified
|
| 225 |
-
// a build request correctly and then had nothing consume the classification: `runScript`
|
| 226 |
-
// was defined and `void`ed, so `onRunScript` was unreachable from every path while the
|
| 227 |
-
// ticket claimed it routed. That is [[reachable-is-not-the-same-as-built]], and `void` is
|
| 228 |
-
// what hid it from tsc. The host authors the code; the panel runs it and reports.
|
| 229 |
-
if (typeof answer?.script === "string" && answer.script.trim())
|
| 230 |
-
runScript(answer.script);
|
| 231 |
-
} catch (err) {
|
| 232 |
-
const sentence = err instanceof Error ? err.message : "";
|
| 233 |
-
setState((s) => failed(s, said, sentence));
|
| 234 |
-
}
|
| 235 |
-
})();
|
| 236 |
-
}, [draft, busy, canEdit, onDescribe, onApplyView, runScript, schema, databaseLabel]);
|
| 237 |
-
|
| 238 |
-
const confirmWrite = useCallback((edits: GridChatEdit[]) => {
|
| 239 |
-
if (writing) return;
|
| 240 |
-
setWriting(true);
|
| 241 |
-
void (async () => {
|
| 242 |
-
try {
|
| 243 |
-
await onWriteCells(edits);
|
| 244 |
-
// β `wrote` rather than `noted`: the note it appends CARRIES THE INVERSE, built from the
|
| 245 |
-
// `before` values the person confirmed. An undo assembled after the write would have
|
| 246 |
-
// nothing left to read [[capture-the-inverse-before-the-write]].
|
| 247 |
-
setState((s) => wrote(s, edits));
|
| 248 |
-
} catch (err) {
|
| 249 |
-
const sentence = err instanceof Error && err.message
|
| 250 |
-
? err.message
|
| 251 |
-
: "That write was refused, so nothing changed.";
|
| 252 |
-
setState((s) => noted(s, sentence));
|
| 253 |
-
} finally {
|
| 254 |
-
setWriting(false);
|
| 255 |
-
}
|
| 256 |
-
})();
|
| 257 |
-
}, [onWriteCells, writing]);
|
| 258 |
-
|
| 259 |
-
if (!open) return null;
|
| 260 |
-
return (
|
| 261 |
-
<GridChatView
|
| 262 |
-
state={state}
|
| 263 |
-
draft={draft}
|
| 264 |
-
writing={writing}
|
| 265 |
-
databaseLabel={databaseLabel}
|
| 266 |
-
schema={schema}
|
| 267 |
-
rowCount={rowCount}
|
| 268 |
-
canEdit={canEdit}
|
| 269 |
-
logRef={logRef}
|
| 270 |
-
onClose={onClose}
|
| 271 |
-
onDraft={setDraft}
|
| 272 |
-
onSend={send}
|
| 273 |
-
onUndoView={onUndoView}
|
| 274 |
-
onConfirmWrite={confirmWrite}
|
| 275 |
-
onDeclineWrite={() => setState((s) => noted(s, "Nothing was written."))}
|
| 276 |
-
/>
|
| 277 |
-
);
|
| 278 |
-
}
|
| 279 |
-
|
| 280 |
-
/**
|
| 281 |
-
* ββ THE PRESENTATIONAL HALF, AND IT IS SPLIT OUT FOR A REASON A GATE CAN USE.
|
| 282 |
-
*
|
| 283 |
-
* `<GridChat>` owns the state; this owns the pixels and takes the state as a prop. That split is
|
| 284 |
-
* what makes T40's `done-when` observable at all: the only renderer available in this repo is
|
| 285 |
-
* `react-dom/server`, which fires no events and runs no effects, so a gate can never DRIVE a
|
| 286 |
-
* stateful component into its in-flight or error state. It can render THIS one into any state it
|
| 287 |
-
* likes, because the state is an argument.
|
| 288 |
-
*
|
| 289 |
-
* β THE HOST NEVER IMPORTS THIS. `GridChat` is the default export and the contract C6 describes;
|
| 290 |
-
* every prop on it is required, and nothing here weakens that. Splitting the render out is the
|
| 291 |
-
* opposite of an optional prop: it adds a seam for the gate without adding a way for a mount to
|
| 292 |
-
* be silently inert.
|
| 293 |
-
*/
|
| 294 |
-
export function GridChatView(props: {
|
| 295 |
-
state: GridChatState;
|
| 296 |
-
draft: string;
|
| 297 |
-
writing: boolean;
|
| 298 |
-
databaseLabel: string;
|
| 299 |
-
schema: GridChatField[];
|
| 300 |
-
rowCount: number;
|
| 301 |
-
canEdit: boolean;
|
| 302 |
-
// β Typed exactly as `useRef<HTMLDivElement | null>(null)` produces it, and OPTIONAL only
|
| 303 |
-
// here: a server render has no DOM to scroll, so the gate omits it. The stateful shell
|
| 304 |
-
// above always passes one.
|
| 305 |
-
logRef?: React.Ref<HTMLDivElement>;
|
| 306 |
-
onClose: () => void;
|
| 307 |
-
onDraft: (text: string) => void;
|
| 308 |
-
onSend: () => void;
|
| 309 |
-
onUndoView: () => void;
|
| 310 |
-
onConfirmWrite: (edits: GridChatEdit[]) => void;
|
| 311 |
-
onDeclineWrite: () => void;
|
| 312 |
-
}) {
|
| 313 |
-
const {
|
| 314 |
-
state, draft, writing, databaseLabel, schema, rowCount, canEdit, logRef,
|
| 315 |
-
onClose, onDraft, onSend, onUndoView, onConfirmWrite, onDeclineWrite,
|
| 316 |
-
} = props;
|
| 317 |
-
const busy = isBusy(state);
|
| 318 |
-
const hint = composerHint(databaseLabel, canEdit);
|
| 319 |
-
|
| 320 |
-
const composer = (
|
| 321 |
-
<div className="cg-chat-composer">
|
| 322 |
-
<textarea
|
| 323 |
-
className="cg-chat-input"
|
| 324 |
-
value={draft}
|
| 325 |
-
rows={2}
|
| 326 |
-
placeholder={hint}
|
| 327 |
-
aria-label={hint}
|
| 328 |
-
disabled={busy}
|
| 329 |
-
onChange={(e) => onDraft(e.target.value)}
|
| 330 |
-
onKeyDown={(e) => {
|
| 331 |
-
if (e.key === "Enter" && !e.shiftKey) {
|
| 332 |
-
e.preventDefault();
|
| 333 |
-
onSend();
|
| 334 |
-
}
|
| 335 |
-
}}
|
| 336 |
-
/>
|
| 337 |
-
<div className="cg-chat-composer-foot">
|
| 338 |
-
{/* β THE SCOPE LINE, NOT A DISCLAIMER. It says what the chat is reading, which is the one
|
| 339 |
-
thing a person cannot tell by looking at a docked panel. */}
|
| 340 |
-
<span className="cg-chat-scope">
|
| 341 |
-
{rowCount === 1 ? "1 record" : `${rowCount} records`}
|
| 342 |
-
{schema.length ? `, ${schema.length === 1 ? "1 field" : `${schema.length} fields`}` : ""}
|
| 343 |
-
</span>
|
| 344 |
-
<span className="cg-chat-spacer" />
|
| 345 |
-
{/* β W37-T43's "and the change is undoable", as a control rather than a promise. It sits
|
| 346 |
-
beside Send because that is where the person is after asking for a view change, and it
|
| 347 |
-
calls the host's own undo so there is one place a view can be put back. */}
|
| 348 |
-
<button
|
| 349 |
-
type="button"
|
| 350 |
-
className="cg-chat-ghost"
|
| 351 |
-
onClick={onUndoView}
|
| 352 |
-
title="Put the view back the way it was"
|
| 353 |
-
>
|
| 354 |
-
Undo view
|
| 355 |
-
</button>
|
| 356 |
-
<button
|
| 357 |
-
type="button"
|
| 358 |
-
className="cg-chat-send"
|
| 359 |
-
onClick={onSend}
|
| 360 |
-
disabled={busy || draft.trim() === ""}
|
| 361 |
-
aria-label="Send"
|
| 362 |
-
title="Send"
|
| 363 |
-
>
|
| 364 |
-
<SendMark />
|
| 365 |
-
</button>
|
| 366 |
-
</div>
|
| 367 |
-
</div>
|
| 368 |
-
);
|
| 369 |
-
|
| 370 |
-
return (
|
| 371 |
-
<aside className="cg-chat" aria-label={`Chat about ${databaseLabel}`}>
|
| 372 |
-
<header className="cg-chat-head">
|
| 373 |
-
<span className="cg-chat-title">{databaseLabel}</span>
|
| 374 |
-
<button
|
| 375 |
-
type="button"
|
| 376 |
-
className="cg-chat-close"
|
| 377 |
-
onClick={onClose}
|
| 378 |
-
aria-label="Close the chat"
|
| 379 |
-
title="Close the chat"
|
| 380 |
-
>
|
| 381 |
-
<svg viewBox="0 0 16 16" width="13" height="13" aria-hidden="true" fill="none">
|
| 382 |
-
<path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5"
|
| 383 |
-
strokeLinecap="round" />
|
| 384 |
-
</svg>
|
| 385 |
-
</button>
|
| 386 |
-
</header>
|
| 387 |
-
|
| 388 |
-
{/* β THE LOG IS NOT RENDERED AT ALL WHEN EMPTY, and `hidden` would be the bug. `.cg-chat-log`
|
| 389 |
-
sets `display: flex`, and an author rule beats the user-agent `[hidden] { display: none }`
|
| 390 |
-
whatever its specificity. `hidden` would take the log out of the accessibility tree and
|
| 391 |
-
leave it PAINTED: an empty flex band shoving the centred opening off centre. That exact
|
| 392 |
-
defect was found and written down one wave ago in `AutomationChat`, and it is invisible to
|
| 393 |
-
any assertion that reads markup as text [[ui-invisible-to-assertions]]. */}
|
| 394 |
-
{state.turns.length ? (
|
| 395 |
-
<div className="cg-chat-log" ref={logRef}>
|
| 396 |
-
{state.turns.map((turn, i) => (
|
| 397 |
-
<div className="cg-chat-turn" key={i}>
|
| 398 |
-
<div
|
| 399 |
-
className={
|
| 400 |
-
"cg-chat-msg " +
|
| 401 |
-
(turn.error ? "is-error" : turn.who === "you" ? "is-you"
|
| 402 |
-
: turn.who === "note" ? "is-note" : "is-assistant")
|
| 403 |
-
}
|
| 404 |
-
>
|
| 405 |
-
{turn.text}
|
| 406 |
-
</div>
|
| 407 |
-
|
| 408 |
-
{/* β UNDO, OFFERED FROM THE TRANSCRIPT. R10 says the person confirms before a write;
|
| 409 |
-
this is the other half of taking them seriously. A confirmed write they did not
|
| 410 |
-
mean stays reversible in the place they are already looking, rather than behind a
|
| 411 |
-
toast that faded while they read the result.
|
| 412 |
-
β IT ROUTES THROUGH THE SAME `onWriteCells` the original went through, so the
|
| 413 |
-
undo passes the caller's permission wall exactly as the write did. An undo with
|
| 414 |
-
its own door would be a second write path, and the one nobody tested. */}
|
| 415 |
-
{canEdit && turn.undo?.length ? (
|
| 416 |
-
<div className="cg-chat-undo">
|
| 417 |
-
<button
|
| 418 |
-
type="button"
|
| 419 |
-
className="cg-chat-ghost"
|
| 420 |
-
disabled={writing}
|
| 421 |
-
onClick={() => onConfirmWrite(turn.undo || [])}
|
| 422 |
-
>
|
| 423 |
-
Put it back
|
| 424 |
-
</button>
|
| 425 |
-
</div>
|
| 426 |
-
) : null}
|
| 427 |
-
|
| 428 |
-
{/* ββ R10 ON SCREEN: EXACTLY WHAT WILL BE WRITTEN, BEFORE ANYTHING IS. Not a count,
|
| 429 |
-
not a summary of a summary. The person sees the record, the field, the old value
|
| 430 |
-
and the new one, and nothing reaches `onWriteCells` until they press Write. */}
|
| 431 |
-
{/* ββ `canEdit` IS CHECKED HERE, IN THE VIEW, AND NOT ONLY WHERE THE PROPOSAL IS
|
| 432 |
-
BUILT. The stateful shell already refuses to build a proposal for a caller who
|
| 433 |
-
may not write, so this looked redundant and was left out of the first draft; the
|
| 434 |
-
gate caught it. The wall has to sit where the CONTROL is drawn, because the view
|
| 435 |
-
renders whatever state it is handed and a second caller, a replayed transcript or
|
| 436 |
-
a permission that changed mid-session would otherwise paint a Write button for
|
| 437 |
-
somebody the store is going to refuse [[permitted-is-not-answerable]]. A wall
|
| 438 |
-
that depends on its caller's discipline is not a wall. */}
|
| 439 |
-
{canEdit && turn.edits?.length ? (
|
| 440 |
-
<div className="cg-chat-edits">
|
| 441 |
-
<p className="cg-chat-edits-head">{editSummary(turn.edits)}</p>
|
| 442 |
-
<table className="cg-chat-edits-table">
|
| 443 |
-
<thead>
|
| 444 |
-
<tr><th>Record</th><th>Field</th><th>Now</th><th>Would become</th></tr>
|
| 445 |
-
</thead>
|
| 446 |
-
<tbody>
|
| 447 |
-
{turn.edits.map((edit, j) => (
|
| 448 |
-
<tr key={j}>
|
| 449 |
-
<td>{edit.rowLabel || edit.rowId}</td>
|
| 450 |
-
<td>{edit.fieldLabel || edit.field}</td>
|
| 451 |
-
<td className="cg-chat-before">{edit.before || "empty"}</td>
|
| 452 |
-
<td className="cg-chat-after">{edit.after || "empty"}</td>
|
| 453 |
-
</tr>
|
| 454 |
-
))}
|
| 455 |
-
</tbody>
|
| 456 |
-
</table>
|
| 457 |
-
<div className="cg-chat-edits-act">
|
| 458 |
-
<button
|
| 459 |
-
type="button"
|
| 460 |
-
className="cg-chat-ghost"
|
| 461 |
-
disabled={writing}
|
| 462 |
-
onClick={onDeclineWrite}
|
| 463 |
-
>
|
| 464 |
-
Leave it
|
| 465 |
-
</button>
|
| 466 |
-
<button
|
| 467 |
-
type="button"
|
| 468 |
-
className="cg-chat-go"
|
| 469 |
-
disabled={writing}
|
| 470 |
-
onClick={() => onConfirmWrite(turn.edits || [])}
|
| 471 |
-
>
|
| 472 |
-
{writing ? "Writing" : "Write these"}
|
| 473 |
-
</button>
|
| 474 |
-
</div>
|
| 475 |
-
</div>
|
| 476 |
-
) : null}
|
| 477 |
-
</div>
|
| 478 |
-
))}
|
| 479 |
-
|
| 480 |
-
{/* β `.lp-spin` is the ONE loading mark in this application. A second spinner vocabulary
|
| 481 |
-
in a new surface is how an app stops having one. */}
|
| 482 |
-
{busy ? (
|
| 483 |
-
<div className="cg-chat-pending" role="status">
|
| 484 |
-
<span className="lp-spin" aria-hidden="true" />
|
| 485 |
-
Reading {databaseLabel}
|
| 486 |
-
</div>
|
| 487 |
-
) : null}
|
| 488 |
-
</div>
|
| 489 |
-
) : null}
|
| 490 |
-
|
| 491 |
-
{/* The centred opening, exactly the shape `AssistantPage` and `AutomationChat` already use.
|
| 492 |
-
β NO DECORATIVE MARK: the reference image has a soft dot ring, and neither of this
|
| 493 |
-
product's two existing chat surfaces does. A mark on the third one is the difference the
|
| 494 |
-
owner would notice. */}
|
| 495 |
-
{state.turns.length ? null : (
|
| 496 |
-
<div className="cg-chat-opening">
|
| 497 |
-
<h2 className="cg-chat-opening-h">How can I help?</h2>
|
| 498 |
-
<p className="cg-chat-opening-p">
|
| 499 |
-
{canEdit
|
| 500 |
-
? "Ask about the records in front of you, change what the view shows, or say what to change. Nothing is written until you confirm it."
|
| 501 |
-
: "Ask about the records in front of you, or change what the view shows."}
|
| 502 |
-
</p>
|
| 503 |
-
{composer}
|
| 504 |
-
</div>
|
| 505 |
-
)}
|
| 506 |
-
|
| 507 |
-
{/* β ONE composer const, rendered in exactly one place at a time. Two on screen at once is
|
| 508 |
-
the defect this pattern exists to make impossible. */}
|
| 509 |
-
{state.turns.length ? <div className="cg-chat-foot">{composer}</div> : null}
|
| 510 |
-
</aside>
|
| 511 |
-
);
|
| 512 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// customer-grid / GridChat.tsx β the docked chat for ANY database view (W37-T40, R2, R10, C6).
|
| 3 |
+
//
|
| 4 |
+
// Owner items 10 and 11 are ONE feature (ruling R2): the chat IS the builder. This is its shell β
|
| 5 |
+
// the conversation surface every later ticket in the lane hangs a power off. T42 gives it the
|
| 6 |
+
// schema to answer from, T43 the view controls, T44 the Custom View's code, T45 the confirmed
|
| 7 |
+
// record edit.
|
| 8 |
+
//
|
| 9 |
+
// ββ IT REACHES INTO NOTHING. Contract C6: every action is a callback the host supplies, and
|
| 10 |
+
// EVERY PROP IS REQUIRED. An optional prop is how a panel ships mounted-but-inert β the feature is
|
| 11 |
+
// whole, the gate is green, and the one line that would have passed the callback was never
|
| 12 |
+
// written. This repo shipped five of those in a single wave. A required prop makes the omission a
|
| 13 |
+
// compile error in the mounting file, which is where a person can see it.
|
| 14 |
+
//
|
| 15 |
+
// β THE SHAPE IS THE ONE THIS PRODUCT ALREADY HAS, not a third chat look. `AutomationChat` and
|
| 16 |
+
// `AssistantPage` both render a centred opening while the transcript is empty, then a log with the
|
| 17 |
+
// SAME composer moved to the foot; `FieldAgentChat` reuses the same composer classes rather than
|
| 18 |
+
// drawing a second one. Copying that is not laziness, it is the reason the owner cannot tell which
|
| 19 |
+
// surface was built by whom.
|
| 20 |
+
//
|
| 21 |
+
// β NO `import.meta.env` ANYWHERE IN THIS FILE'S GRAPH, and the constraint is load-bearing rather
|
| 22 |
+
// than stylistic: the gate renders this component from a CommonJS build, and `import.meta` cannot
|
| 23 |
+
// be required from one. `AutomationChat`'s own header records that exact crash. The imports below
|
| 24 |
+
// are `react` + `./gridChat` + the stylesheet, and nothing else.
|
| 25 |
+
// ---------------------------------------------------------------------------
|
| 26 |
+
|
| 27 |
+
import { useCallback, useEffect, useRef, useState } from "react";
|
| 28 |
+
|
| 29 |
+
import {
|
| 30 |
+
answered,
|
| 31 |
+
asked,
|
| 32 |
+
composerHint,
|
| 33 |
+
editSummary,
|
| 34 |
+
emptyChat,
|
| 35 |
+
failed,
|
| 36 |
+
isBusy,
|
| 37 |
+
noted,
|
| 38 |
+
proposedEdits,
|
| 39 |
+
readIntent,
|
| 40 |
+
runSentence,
|
| 41 |
+
wrote,
|
| 42 |
+
} from "./gridChat";
|
| 43 |
+
import type {
|
| 44 |
+
GridChatAnswer,
|
| 45 |
+
GridChatEdit,
|
| 46 |
+
GridChatField,
|
| 47 |
+
GridChatRunResult,
|
| 48 |
+
GridChatState,
|
| 49 |
+
GridChatTurn,
|
| 50 |
+
} from "./gridChat";
|
| 51 |
+
import "./gridChat.css";
|
| 52 |
+
|
| 53 |
+
// β RE-EXPORTED SO THE MOUNTING FILE TAKES ONE IMPORT. The types live in `gridChat.ts` (they have
|
| 54 |
+
// to: the state machine is typed by them and that module must stay React-free), but a host that
|
| 55 |
+
// had to import the component from here and its types from there would be one refactor away from
|
| 56 |
+
// the two drifting. Published to C in mailbox E-4 as a single import line.
|
| 57 |
+
export type {
|
| 58 |
+
GridChatAnswer,
|
| 59 |
+
GridChatEdit,
|
| 60 |
+
GridChatField,
|
| 61 |
+
GridChatRunResult,
|
| 62 |
+
GridChatState,
|
| 63 |
+
GridChatTurn,
|
| 64 |
+
};
|
| 65 |
+
|
| 66 |
+
/**
|
| 67 |
+
* What the host asks the chat to do about the view. β DELIBERATELY NARROW: this is the vocabulary
|
| 68 |
+
* `assistant build_view` already speaks, minus what it cannot express. There is no `rhs` in that
|
| 69 |
+
* tool schema, so a field-versus-field condition is not sayable
|
| 70 |
+
* [[assistant-build-view-is-a-subset]] β W37-T43 has to SAY it cannot rather than fail quietly.
|
| 71 |
+
*/
|
| 72 |
+
export interface GridChatViewSpec {
|
| 73 |
+
/**
|
| 74 |
+
* β RESERVED AND DELIBERATELY NOT POPULATED BY `readIntent` YET. The panel understands
|
| 75 |
+
* sort/group/colour from a sentence; a real FILTER needs the condition vocabulary the host owns,
|
| 76 |
+
* so this is the slot C fills rather than a field the panel quietly leaves empty. Named here so
|
| 77 |
+
* it reads as a contract with a known gap instead of a channel nobody noticed was dead
|
| 78 |
+
* [[flag-shipped-without-its-writer]].
|
| 79 |
+
*/
|
| 80 |
+
filter?: unknown;
|
| 81 |
+
sortBy?: string;
|
| 82 |
+
groupBy?: string;
|
| 83 |
+
colorBy?: string;
|
| 84 |
+
}
|
| 85 |
+
|
| 86 |
+
export interface GridChatProps {
|
| 87 |
+
/** The host owns the toggle. The panel never closes itself except through `onClose`. */
|
| 88 |
+
open: boolean;
|
| 89 |
+
onClose: () => void;
|
| 90 |
+
/** What this chat is reading, in the person's words. Appears in the header and the placeholder. */
|
| 91 |
+
databaseLabel: string;
|
| 92 |
+
/** The columns the chat may reason about. The host decides; the chat never discovers. */
|
| 93 |
+
schema: GridChatField[];
|
| 94 |
+
rowCount: number;
|
| 95 |
+
/**
|
| 96 |
+
* β R10's BOUND, EXPRESSED AS AN AFFORDANCE. `false` means the edit power is not OFFERED, not
|
| 97 |
+
* that it is offered and then refused. The chat is not a privilege escalation: a caller whose
|
| 98 |
+
* own permissions would refuse the write must not be invited to compose one
|
| 99 |
+
* [[permitted-is-not-answerable]].
|
| 100 |
+
*/
|
| 101 |
+
canEdit: boolean;
|
| 102 |
+
/** (a) answer a question about this database. */
|
| 103 |
+
onDescribe: (question: string) => Promise<GridChatAnswer>;
|
| 104 |
+
/** (b) change filter, sort, group or colour on the ACTIVE view. */
|
| 105 |
+
onApplyView: (spec: GridChatViewSpec) => void;
|
| 106 |
+
/** (b, undo half) put the view back the way it was. */
|
| 107 |
+
onUndoView: () => void;
|
| 108 |
+
/** (d) write the cells the person just confirmed. β Reached only from the confirm control. */
|
| 109 |
+
onWriteCells: (edits: GridChatEdit[]) => Promise<void>;
|
| 110 |
+
/** (c) run the Custom View's code and report what happened. */
|
| 111 |
+
onRunScript: (code: string) => Promise<GridChatRunResult>;
|
| 112 |
+
}
|
| 113 |
+
|
| 114 |
+
/** The send mark. β The Assistant's own path, point for point: a second arrow drawn slightly
|
| 115 |
+
* differently is precisely how two surfaces stop looking like one product. */
|
| 116 |
+
function SendMark() {
|
| 117 |
+
return (
|
| 118 |
+
<svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true" fill="none">
|
| 119 |
+
<path d="M8 13V3.6M4 7.4 8 3.4l4 4" stroke="currentColor" strokeWidth="1.5"
|
| 120 |
+
strokeLinecap="round" strokeLinejoin="round" />
|
| 121 |
+
</svg>
|
| 122 |
+
);
|
| 123 |
+
}
|
| 124 |
+
|
| 125 |
+
export default function GridChat(props: GridChatProps) {
|
| 126 |
+
const {
|
| 127 |
+
open, onClose, databaseLabel, schema, rowCount, canEdit,
|
| 128 |
+
onDescribe, onApplyView, onUndoView, onWriteCells, onRunScript,
|
| 129 |
+
} = props;
|
| 130 |
+
|
| 131 |
+
const [state, setState] = useState<GridChatState>(emptyChat);
|
| 132 |
+
const [draft, setDraft] = useState("");
|
| 133 |
+
const [writing, setWriting] = useState(false);
|
| 134 |
+
const logRef = useRef<HTMLDivElement | null>(null);
|
| 135 |
+
const busy = isBusy(state);
|
| 136 |
+
|
| 137 |
+
// β THE UNUSED-POWER GUARD. `onApplyView`, `onUndoView` and `onRunScript` are wired by W37-T43
|
| 138 |
+
// and W37-T44; naming them here keeps them REQUIRED props from the first mount, so C's wiring
|
| 139 |
+
// lands with the shell rather than being remembered two tickets later. `void` is the honest
|
| 140 |
+
// spelling of "held, not yet called" and it survives `noUnusedLocals`.
|
| 141 |
+
// β WHERE EACH CALLBACK IS ACTUALLY REACHED, because saying so is the only thing that stops a
|
| 142 |
+
// required prop becoming a decorative one: `onApplyView` from `send` (T43), `onUndoView` from the
|
| 143 |
+
// Undo control in the foot row, `onRunScript` from `runScript` below, which `send` calls when the
|
| 144 |
+
// host returns generated code (T44), `onWriteCells` from the confirm and the undo (T45, R10).
|
| 145 |
+
|
| 146 |
+
// The transcript follows the newest turn. Guarded on the ref because the log is not rendered at
|
| 147 |
+
// all while the conversation is empty (see the opening below).
|
| 148 |
+
useEffect(() => {
|
| 149 |
+
const log = logRef.current;
|
| 150 |
+
if (log) log.scrollTop = log.scrollHeight;
|
| 151 |
+
}, [state.turns.length, busy]);
|
| 152 |
+
|
| 153 |
+
// β DECLARED BEFORE `send`, AND THE ORDER IS LOAD-BEARING RATHER THAN TIDY. `send`'s
|
| 154 |
+
// dependency array names `runScript`, and a dependency array is evaluated AT RENDER, not
|
| 155 |
+
// when the callback fires. With `runScript` declared after `send` that array reads a `const`
|
| 156 |
+
// in its temporal dead zone and the panel throws `Cannot access 'runScript' before
|
| 157 |
+
// initialization` on its FIRST paint. β `tsc` does not catch it: it is a runtime TDZ, and
|
| 158 |
+
// the build was green with the crash in it.
|
| 159 |
+
/**
|
| 160 |
+
* β W37-T44 β THE CHAT WRITES THE CUSTOM VIEW'S CODE AND RUNS IT.
|
| 161 |
+
* β THE SANDBOX IS NOT WIDENED TO MAKE A GENERATED SCRIPT WORK. `onRunScript` is the host's
|
| 162 |
+
* ordinary run door, the same one a hand-typed script goes through, so a script the chat wrote
|
| 163 |
+
* has exactly the powers a person's own script has and no more. A failure is REPORTED and the
|
| 164 |
+
* code is left in the editor to be fixed by hand, never blanked.
|
| 165 |
+
*/
|
| 166 |
+
const runScript = useCallback((code: string) => {
|
| 167 |
+
void (async () => {
|
| 168 |
+
try {
|
| 169 |
+
const result = await onRunScript(code);
|
| 170 |
+
setState((s) => noted(s, runSentence(result)));
|
| 171 |
+
} catch (err) {
|
| 172 |
+
const why = err instanceof Error && err.message ? err.message : "";
|
| 173 |
+
setState((s) => noted(s, runSentence({ ok: false, error: why })));
|
| 174 |
+
}
|
| 175 |
+
})();
|
| 176 |
+
}, [onRunScript]);
|
| 177 |
+
|
| 178 |
+
const send = useCallback(() => {
|
| 179 |
+
const said = draft.trim();
|
| 180 |
+
if (!said || busy) return;
|
| 181 |
+
setState((s) => asked(s, said));
|
| 182 |
+
setDraft("");
|
| 183 |
+
|
| 184 |
+
// ββ W37-T42/T43/T44 β READ THE SENTENCE BEFORE SPENDING ANYTHING ON IT.
|
| 185 |
+
// β THE REFUSAL BRANCH IS THE POINT OF T42 AND IT COSTS NOTHING. D-339's defect is an agent
|
| 186 |
+
// that cannot read the database answering from words alone and inventing a number. The panel
|
| 187 |
+
// HOLDS the schema, so a question naming a field this database does not have is answered here,
|
| 188 |
+
// truthfully, without a model call that could only guess.
|
| 189 |
+
const intent = readIntent(schema, databaseLabel, said);
|
| 190 |
+
if (intent.refusal) {
|
| 191 |
+
setState((s) => answered(s, said, { text: intent.refusal!, unanswerable: true }));
|
| 192 |
+
return;
|
| 193 |
+
}
|
| 194 |
+
// β ...and a question the panel already knows the answer to is not a paid round trip either.
|
| 195 |
+
if (intent.localAnswer) {
|
| 196 |
+
setState((s) => answered(s, said, { text: intent.localAnswer! }));
|
| 197 |
+
return;
|
| 198 |
+
}
|
| 199 |
+
if (intent.kind === "view") {
|
| 200 |
+
// T43: the VIEW changes through the host's callback (C6), and what could NOT be expressed is
|
| 201 |
+
// named rather than dropped [[assistant-build-view-is-a-subset]].
|
| 202 |
+
if (intent.view) onApplyView(intent.view);
|
| 203 |
+
const applied = intent.view
|
| 204 |
+
? "The view has been changed. Ask again or press Undo to put it back."
|
| 205 |
+
: "I could not tell which field you meant, so the view is unchanged.";
|
| 206 |
+
setState((s) => answered(s, said, {
|
| 207 |
+
text: intent.cannot ? `${applied} ${intent.cannot}` : applied,
|
| 208 |
+
}));
|
| 209 |
+
return;
|
| 210 |
+
}
|
| 211 |
+
|
| 212 |
+
void (async () => {
|
| 213 |
+
try {
|
| 214 |
+
const answer = await onDescribe(said);
|
| 215 |
+
// β THE PROPOSAL BRANCH IS HERE AND NOT IN THE HOST. A host that returned edits and also
|
| 216 |
+
// wrote them would make the confirm cosmetic; the panel decides that edits mean "show the
|
| 217 |
+
// person first", so there is exactly one place that decision can be got wrong.
|
| 218 |
+
// β NO CAST. `GridChatAnswer.edits` is a declared part of the contract now, so the host
|
| 219 |
+
// reads the same channel this line does; it used to be an `as` and the two could drift.
|
| 220 |
+
const edits = answer?.edits;
|
| 221 |
+
setState((s) => (canEdit && Array.isArray(edits) && edits.length
|
| 222 |
+
? proposedEdits(s, said, answer.text, edits)
|
| 223 |
+
: answered(s, said, answer)));
|
| 224 |
+
// β W37-T44 β AND THIS BRANCH IS THE WHOLE POINT OF THE TICKET. The first draft classified
|
| 225 |
+
// a build request correctly and then had nothing consume the classification: `runScript`
|
| 226 |
+
// was defined and `void`ed, so `onRunScript` was unreachable from every path while the
|
| 227 |
+
// ticket claimed it routed. That is [[reachable-is-not-the-same-as-built]], and `void` is
|
| 228 |
+
// what hid it from tsc. The host authors the code; the panel runs it and reports.
|
| 229 |
+
if (typeof answer?.script === "string" && answer.script.trim())
|
| 230 |
+
runScript(answer.script);
|
| 231 |
+
} catch (err) {
|
| 232 |
+
const sentence = err instanceof Error ? err.message : "";
|
| 233 |
+
setState((s) => failed(s, said, sentence));
|
| 234 |
+
}
|
| 235 |
+
})();
|
| 236 |
+
}, [draft, busy, canEdit, onDescribe, onApplyView, runScript, schema, databaseLabel]);
|
| 237 |
+
|
| 238 |
+
const confirmWrite = useCallback((edits: GridChatEdit[]) => {
|
| 239 |
+
if (writing) return;
|
| 240 |
+
setWriting(true);
|
| 241 |
+
void (async () => {
|
| 242 |
+
try {
|
| 243 |
+
await onWriteCells(edits);
|
| 244 |
+
// β `wrote` rather than `noted`: the note it appends CARRIES THE INVERSE, built from the
|
| 245 |
+
// `before` values the person confirmed. An undo assembled after the write would have
|
| 246 |
+
// nothing left to read [[capture-the-inverse-before-the-write]].
|
| 247 |
+
setState((s) => wrote(s, edits));
|
| 248 |
+
} catch (err) {
|
| 249 |
+
const sentence = err instanceof Error && err.message
|
| 250 |
+
? err.message
|
| 251 |
+
: "That write was refused, so nothing changed.";
|
| 252 |
+
setState((s) => noted(s, sentence));
|
| 253 |
+
} finally {
|
| 254 |
+
setWriting(false);
|
| 255 |
+
}
|
| 256 |
+
})();
|
| 257 |
+
}, [onWriteCells, writing]);
|
| 258 |
+
|
| 259 |
+
if (!open) return null;
|
| 260 |
+
return (
|
| 261 |
+
<GridChatView
|
| 262 |
+
state={state}
|
| 263 |
+
draft={draft}
|
| 264 |
+
writing={writing}
|
| 265 |
+
databaseLabel={databaseLabel}
|
| 266 |
+
schema={schema}
|
| 267 |
+
rowCount={rowCount}
|
| 268 |
+
canEdit={canEdit}
|
| 269 |
+
logRef={logRef}
|
| 270 |
+
onClose={onClose}
|
| 271 |
+
onDraft={setDraft}
|
| 272 |
+
onSend={send}
|
| 273 |
+
onUndoView={onUndoView}
|
| 274 |
+
onConfirmWrite={confirmWrite}
|
| 275 |
+
onDeclineWrite={() => setState((s) => noted(s, "Nothing was written."))}
|
| 276 |
+
/>
|
| 277 |
+
);
|
| 278 |
+
}
|
| 279 |
+
|
| 280 |
+
/**
|
| 281 |
+
* ββ THE PRESENTATIONAL HALF, AND IT IS SPLIT OUT FOR A REASON A GATE CAN USE.
|
| 282 |
+
*
|
| 283 |
+
* `<GridChat>` owns the state; this owns the pixels and takes the state as a prop. That split is
|
| 284 |
+
* what makes T40's `done-when` observable at all: the only renderer available in this repo is
|
| 285 |
+
* `react-dom/server`, which fires no events and runs no effects, so a gate can never DRIVE a
|
| 286 |
+
* stateful component into its in-flight or error state. It can render THIS one into any state it
|
| 287 |
+
* likes, because the state is an argument.
|
| 288 |
+
*
|
| 289 |
+
* β THE HOST NEVER IMPORTS THIS. `GridChat` is the default export and the contract C6 describes;
|
| 290 |
+
* every prop on it is required, and nothing here weakens that. Splitting the render out is the
|
| 291 |
+
* opposite of an optional prop: it adds a seam for the gate without adding a way for a mount to
|
| 292 |
+
* be silently inert.
|
| 293 |
+
*/
|
| 294 |
+
export function GridChatView(props: {
|
| 295 |
+
state: GridChatState;
|
| 296 |
+
draft: string;
|
| 297 |
+
writing: boolean;
|
| 298 |
+
databaseLabel: string;
|
| 299 |
+
schema: GridChatField[];
|
| 300 |
+
rowCount: number;
|
| 301 |
+
canEdit: boolean;
|
| 302 |
+
// β Typed exactly as `useRef<HTMLDivElement | null>(null)` produces it, and OPTIONAL only
|
| 303 |
+
// here: a server render has no DOM to scroll, so the gate omits it. The stateful shell
|
| 304 |
+
// above always passes one.
|
| 305 |
+
logRef?: React.Ref<HTMLDivElement>;
|
| 306 |
+
onClose: () => void;
|
| 307 |
+
onDraft: (text: string) => void;
|
| 308 |
+
onSend: () => void;
|
| 309 |
+
onUndoView: () => void;
|
| 310 |
+
onConfirmWrite: (edits: GridChatEdit[]) => void;
|
| 311 |
+
onDeclineWrite: () => void;
|
| 312 |
+
}) {
|
| 313 |
+
const {
|
| 314 |
+
state, draft, writing, databaseLabel, schema, rowCount, canEdit, logRef,
|
| 315 |
+
onClose, onDraft, onSend, onUndoView, onConfirmWrite, onDeclineWrite,
|
| 316 |
+
} = props;
|
| 317 |
+
const busy = isBusy(state);
|
| 318 |
+
const hint = composerHint(databaseLabel, canEdit);
|
| 319 |
+
|
| 320 |
+
const composer = (
|
| 321 |
+
<div className="cg-chat-composer">
|
| 322 |
+
<textarea
|
| 323 |
+
className="cg-chat-input"
|
| 324 |
+
value={draft}
|
| 325 |
+
rows={2}
|
| 326 |
+
placeholder={hint}
|
| 327 |
+
aria-label={hint}
|
| 328 |
+
disabled={busy}
|
| 329 |
+
onChange={(e) => onDraft(e.target.value)}
|
| 330 |
+
onKeyDown={(e) => {
|
| 331 |
+
if (e.key === "Enter" && !e.shiftKey) {
|
| 332 |
+
e.preventDefault();
|
| 333 |
+
onSend();
|
| 334 |
+
}
|
| 335 |
+
}}
|
| 336 |
+
/>
|
| 337 |
+
<div className="cg-chat-composer-foot">
|
| 338 |
+
{/* β THE SCOPE LINE, NOT A DISCLAIMER. It says what the chat is reading, which is the one
|
| 339 |
+
thing a person cannot tell by looking at a docked panel. */}
|
| 340 |
+
<span className="cg-chat-scope">
|
| 341 |
+
{rowCount === 1 ? "1 record" : `${rowCount} records`}
|
| 342 |
+
{schema.length ? `, ${schema.length === 1 ? "1 field" : `${schema.length} fields`}` : ""}
|
| 343 |
+
</span>
|
| 344 |
+
<span className="cg-chat-spacer" />
|
| 345 |
+
{/* β W37-T43's "and the change is undoable", as a control rather than a promise. It sits
|
| 346 |
+
beside Send because that is where the person is after asking for a view change, and it
|
| 347 |
+
calls the host's own undo so there is one place a view can be put back. */}
|
| 348 |
+
<button
|
| 349 |
+
type="button"
|
| 350 |
+
className="cg-chat-ghost"
|
| 351 |
+
onClick={onUndoView}
|
| 352 |
+
title="Put the view back the way it was"
|
| 353 |
+
>
|
| 354 |
+
Undo view
|
| 355 |
+
</button>
|
| 356 |
+
<button
|
| 357 |
+
type="button"
|
| 358 |
+
className="cg-chat-send"
|
| 359 |
+
onClick={onSend}
|
| 360 |
+
disabled={busy || draft.trim() === ""}
|
| 361 |
+
aria-label="Send"
|
| 362 |
+
title="Send"
|
| 363 |
+
>
|
| 364 |
+
<SendMark />
|
| 365 |
+
</button>
|
| 366 |
+
</div>
|
| 367 |
+
</div>
|
| 368 |
+
);
|
| 369 |
+
|
| 370 |
+
return (
|
| 371 |
+
<aside className="cg-chat" aria-label={`Chat about ${databaseLabel}`}>
|
| 372 |
+
<header className="cg-chat-head">
|
| 373 |
+
<span className="cg-chat-title">{databaseLabel}</span>
|
| 374 |
+
<button
|
| 375 |
+
type="button"
|
| 376 |
+
className="cg-chat-close"
|
| 377 |
+
onClick={onClose}
|
| 378 |
+
aria-label="Close the chat"
|
| 379 |
+
title="Close the chat"
|
| 380 |
+
>
|
| 381 |
+
<svg viewBox="0 0 16 16" width="13" height="13" aria-hidden="true" fill="none">
|
| 382 |
+
<path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5"
|
| 383 |
+
strokeLinecap="round" />
|
| 384 |
+
</svg>
|
| 385 |
+
</button>
|
| 386 |
+
</header>
|
| 387 |
+
|
| 388 |
+
{/* β THE LOG IS NOT RENDERED AT ALL WHEN EMPTY, and `hidden` would be the bug. `.cg-chat-log`
|
| 389 |
+
sets `display: flex`, and an author rule beats the user-agent `[hidden] { display: none }`
|
| 390 |
+
whatever its specificity. `hidden` would take the log out of the accessibility tree and
|
| 391 |
+
leave it PAINTED: an empty flex band shoving the centred opening off centre. That exact
|
| 392 |
+
defect was found and written down one wave ago in `AutomationChat`, and it is invisible to
|
| 393 |
+
any assertion that reads markup as text [[ui-invisible-to-assertions]]. */}
|
| 394 |
+
{state.turns.length ? (
|
| 395 |
+
<div className="cg-chat-log" ref={logRef}>
|
| 396 |
+
{state.turns.map((turn, i) => (
|
| 397 |
+
<div className="cg-chat-turn" key={i}>
|
| 398 |
+
<div
|
| 399 |
+
className={
|
| 400 |
+
"cg-chat-msg " +
|
| 401 |
+
(turn.error ? "is-error" : turn.who === "you" ? "is-you"
|
| 402 |
+
: turn.who === "note" ? "is-note" : "is-assistant")
|
| 403 |
+
}
|
| 404 |
+
>
|
| 405 |
+
{turn.text}
|
| 406 |
+
</div>
|
| 407 |
+
|
| 408 |
+
{/* β UNDO, OFFERED FROM THE TRANSCRIPT. R10 says the person confirms before a write;
|
| 409 |
+
this is the other half of taking them seriously. A confirmed write they did not
|
| 410 |
+
mean stays reversible in the place they are already looking, rather than behind a
|
| 411 |
+
toast that faded while they read the result.
|
| 412 |
+
β IT ROUTES THROUGH THE SAME `onWriteCells` the original went through, so the
|
| 413 |
+
undo passes the caller's permission wall exactly as the write did. An undo with
|
| 414 |
+
its own door would be a second write path, and the one nobody tested. */}
|
| 415 |
+
{canEdit && turn.undo?.length ? (
|
| 416 |
+
<div className="cg-chat-undo">
|
| 417 |
+
<button
|
| 418 |
+
type="button"
|
| 419 |
+
className="cg-chat-ghost"
|
| 420 |
+
disabled={writing}
|
| 421 |
+
onClick={() => onConfirmWrite(turn.undo || [])}
|
| 422 |
+
>
|
| 423 |
+
Put it back
|
| 424 |
+
</button>
|
| 425 |
+
</div>
|
| 426 |
+
) : null}
|
| 427 |
+
|
| 428 |
+
{/* ββ R10 ON SCREEN: EXACTLY WHAT WILL BE WRITTEN, BEFORE ANYTHING IS. Not a count,
|
| 429 |
+
not a summary of a summary. The person sees the record, the field, the old value
|
| 430 |
+
and the new one, and nothing reaches `onWriteCells` until they press Write. */}
|
| 431 |
+
{/* ββ `canEdit` IS CHECKED HERE, IN THE VIEW, AND NOT ONLY WHERE THE PROPOSAL IS
|
| 432 |
+
BUILT. The stateful shell already refuses to build a proposal for a caller who
|
| 433 |
+
may not write, so this looked redundant and was left out of the first draft; the
|
| 434 |
+
gate caught it. The wall has to sit where the CONTROL is drawn, because the view
|
| 435 |
+
renders whatever state it is handed and a second caller, a replayed transcript or
|
| 436 |
+
a permission that changed mid-session would otherwise paint a Write button for
|
| 437 |
+
somebody the store is going to refuse [[permitted-is-not-answerable]]. A wall
|
| 438 |
+
that depends on its caller's discipline is not a wall. */}
|
| 439 |
+
{canEdit && turn.edits?.length ? (
|
| 440 |
+
<div className="cg-chat-edits">
|
| 441 |
+
<p className="cg-chat-edits-head">{editSummary(turn.edits)}</p>
|
| 442 |
+
<table className="cg-chat-edits-table">
|
| 443 |
+
<thead>
|
| 444 |
+
<tr><th>Record</th><th>Field</th><th>Now</th><th>Would become</th></tr>
|
| 445 |
+
</thead>
|
| 446 |
+
<tbody>
|
| 447 |
+
{turn.edits.map((edit, j) => (
|
| 448 |
+
<tr key={j}>
|
| 449 |
+
<td>{edit.rowLabel || edit.rowId}</td>
|
| 450 |
+
<td>{edit.fieldLabel || edit.field}</td>
|
| 451 |
+
<td className="cg-chat-before">{edit.before || "empty"}</td>
|
| 452 |
+
<td className="cg-chat-after">{edit.after || "empty"}</td>
|
| 453 |
+
</tr>
|
| 454 |
+
))}
|
| 455 |
+
</tbody>
|
| 456 |
+
</table>
|
| 457 |
+
<div className="cg-chat-edits-act">
|
| 458 |
+
<button
|
| 459 |
+
type="button"
|
| 460 |
+
className="cg-chat-ghost"
|
| 461 |
+
disabled={writing}
|
| 462 |
+
onClick={onDeclineWrite}
|
| 463 |
+
>
|
| 464 |
+
Leave it
|
| 465 |
+
</button>
|
| 466 |
+
<button
|
| 467 |
+
type="button"
|
| 468 |
+
className="cg-chat-go"
|
| 469 |
+
disabled={writing}
|
| 470 |
+
onClick={() => onConfirmWrite(turn.edits || [])}
|
| 471 |
+
>
|
| 472 |
+
{writing ? "Writing" : "Write these"}
|
| 473 |
+
</button>
|
| 474 |
+
</div>
|
| 475 |
+
</div>
|
| 476 |
+
) : null}
|
| 477 |
+
</div>
|
| 478 |
+
))}
|
| 479 |
+
|
| 480 |
+
{/* β `.lp-spin` is the ONE loading mark in this application. A second spinner vocabulary
|
| 481 |
+
in a new surface is how an app stops having one. */}
|
| 482 |
+
{busy ? (
|
| 483 |
+
<div className="cg-chat-pending" role="status">
|
| 484 |
+
<span className="lp-spin" aria-hidden="true" />
|
| 485 |
+
Reading {databaseLabel}
|
| 486 |
+
</div>
|
| 487 |
+
) : null}
|
| 488 |
+
</div>
|
| 489 |
+
) : null}
|
| 490 |
+
|
| 491 |
+
{/* The centred opening, exactly the shape `AssistantPage` and `AutomationChat` already use.
|
| 492 |
+
β NO DECORATIVE MARK: the reference image has a soft dot ring, and neither of this
|
| 493 |
+
product's two existing chat surfaces does. A mark on the third one is the difference the
|
| 494 |
+
owner would notice. */}
|
| 495 |
+
{state.turns.length ? null : (
|
| 496 |
+
<div className="cg-chat-opening">
|
| 497 |
+
<h2 className="cg-chat-opening-h">How can I help?</h2>
|
| 498 |
+
<p className="cg-chat-opening-p">
|
| 499 |
+
{canEdit
|
| 500 |
+
? "Ask about the records in front of you, change what the view shows, or say what to change. Nothing is written until you confirm it."
|
| 501 |
+
: "Ask about the records in front of you, or change what the view shows."}
|
| 502 |
+
</p>
|
| 503 |
+
{composer}
|
| 504 |
+
</div>
|
| 505 |
+
)}
|
| 506 |
+
|
| 507 |
+
{/* β ONE composer const, rendered in exactly one place at a time. Two on screen at once is
|
| 508 |
+
the defect this pattern exists to make impossible. */}
|
| 509 |
+
{state.turns.length ? <div className="cg-chat-foot">{composer}</div> : null}
|
| 510 |
+
</aside>
|
| 511 |
+
);
|
| 512 |
+
}
|
web/src/customer-grid/ImportDialog.css
CHANGED
|
@@ -1,154 +1,154 @@
|
|
| 1 |
-
/* customer-grid / ImportDialog.css β WAVE-29 T25 (owner item 6).
|
| 2 |
-
Tokens only (`--lp-*`): this file may not invent a colour, and `index.css` is another
|
| 3 |
-
session's fence, so the dialog's own styles live beside its component. */
|
| 4 |
-
|
| 5 |
-
.cg-import-scrim {
|
| 6 |
-
position: fixed;
|
| 7 |
-
inset: 0;
|
| 8 |
-
z-index: 60;
|
| 9 |
-
display: flex;
|
| 10 |
-
align-items: center;
|
| 11 |
-
justify-content: center;
|
| 12 |
-
background: rgba(32, 36, 51, 0.28);
|
| 13 |
-
padding: 24px;
|
| 14 |
-
}
|
| 15 |
-
|
| 16 |
-
.cg-import {
|
| 17 |
-
display: flex;
|
| 18 |
-
flex-direction: column;
|
| 19 |
-
width: min(560px, 100%);
|
| 20 |
-
max-height: min(80vh, 720px);
|
| 21 |
-
background: var(--lp-bg);
|
| 22 |
-
border: 1px solid var(--lp-line);
|
| 23 |
-
border-radius: var(--lp-r-lg);
|
| 24 |
-
box-shadow: 0 12px 32px rgba(32, 36, 51, 0.18);
|
| 25 |
-
overflow: hidden;
|
| 26 |
-
}
|
| 27 |
-
|
| 28 |
-
.cg-import-head {
|
| 29 |
-
display: flex;
|
| 30 |
-
align-items: center;
|
| 31 |
-
justify-content: space-between;
|
| 32 |
-
gap: 12px;
|
| 33 |
-
padding: 14px 16px;
|
| 34 |
-
border-bottom: 1px solid var(--lp-line);
|
| 35 |
-
}
|
| 36 |
-
|
| 37 |
-
.cg-import-head h2 {
|
| 38 |
-
margin: 0;
|
| 39 |
-
font-size: var(--lp-fs-md);
|
| 40 |
-
font-weight: 600;
|
| 41 |
-
color: var(--lp-ink);
|
| 42 |
-
}
|
| 43 |
-
|
| 44 |
-
.cg-import-x {
|
| 45 |
-
border: 0;
|
| 46 |
-
background: none;
|
| 47 |
-
color: var(--lp-muted);
|
| 48 |
-
font-size: var(--lp-fs-lg);
|
| 49 |
-
line-height: 1;
|
| 50 |
-
cursor: pointer;
|
| 51 |
-
padding: 2px 6px;
|
| 52 |
-
}
|
| 53 |
-
|
| 54 |
-
.cg-import-x:hover {
|
| 55 |
-
color: var(--lp-ink);
|
| 56 |
-
}
|
| 57 |
-
|
| 58 |
-
.cg-import-body {
|
| 59 |
-
padding: 14px 16px;
|
| 60 |
-
overflow: auto;
|
| 61 |
-
}
|
| 62 |
-
|
| 63 |
-
.cg-import-lede {
|
| 64 |
-
margin: 0 0 8px;
|
| 65 |
-
font-size: var(--lp-fs-sm);
|
| 66 |
-
color: var(--lp-ink);
|
| 67 |
-
}
|
| 68 |
-
|
| 69 |
-
.cg-import-note {
|
| 70 |
-
margin: 0 0 12px;
|
| 71 |
-
font-size: var(--lp-fs-xs);
|
| 72 |
-
color: var(--lp-muted);
|
| 73 |
-
}
|
| 74 |
-
|
| 75 |
-
.cg-import-file {
|
| 76 |
-
font-size: var(--lp-fs-sm);
|
| 77 |
-
}
|
| 78 |
-
|
| 79 |
-
/* The mapping list: the spreadsheet's column on the left, this database's field on the right,
|
| 80 |
-
so the eye reads it as "this becomes that" rather than as a form. */
|
| 81 |
-
.cg-import-map {
|
| 82 |
-
display: flex;
|
| 83 |
-
flex-direction: column;
|
| 84 |
-
gap: 6px;
|
| 85 |
-
}
|
| 86 |
-
|
| 87 |
-
.cg-import-row {
|
| 88 |
-
display: grid;
|
| 89 |
-
grid-template-columns: 1fr 200px;
|
| 90 |
-
align-items: center;
|
| 91 |
-
gap: 10px;
|
| 92 |
-
}
|
| 93 |
-
|
| 94 |
-
.cg-import-col {
|
| 95 |
-
font-size: var(--lp-fs-sm);
|
| 96 |
-
color: var(--lp-ink);
|
| 97 |
-
overflow: hidden;
|
| 98 |
-
text-overflow: ellipsis;
|
| 99 |
-
white-space: nowrap;
|
| 100 |
-
}
|
| 101 |
-
|
| 102 |
-
.cg-import-row select {
|
| 103 |
-
font-family: inherit;
|
| 104 |
-
font-size: var(--lp-fs-xs);
|
| 105 |
-
padding: 4px 6px;
|
| 106 |
-
border: 1px solid var(--lp-line);
|
| 107 |
-
border-radius: var(--lp-r-sm);
|
| 108 |
-
background: var(--lp-bg);
|
| 109 |
-
color: var(--lp-ink);
|
| 110 |
-
}
|
| 111 |
-
|
| 112 |
-
/* A refusal is not an error state to be styled red-alert; it is a list of things to fix, so it
|
| 113 |
-
takes the yellow tint the rest of the product uses for "look at this before continuing". */
|
| 114 |
-
.cg-import-problems {
|
| 115 |
-
margin-top: 12px;
|
| 116 |
-
padding: 10px 12px;
|
| 117 |
-
border: 1px solid var(--lp-yellow);
|
| 118 |
-
border-radius: var(--lp-r-sm);
|
| 119 |
-
background: var(--lp-yellow-tint);
|
| 120 |
-
color: var(--lp-yellow-deep);
|
| 121 |
-
font-size: var(--lp-fs-xs);
|
| 122 |
-
}
|
| 123 |
-
|
| 124 |
-
.cg-import-problems ul {
|
| 125 |
-
margin: 6px 0;
|
| 126 |
-
padding-left: 18px;
|
| 127 |
-
}
|
| 128 |
-
|
| 129 |
-
.cg-import-problems p {
|
| 130 |
-
margin: 6px 0 0;
|
| 131 |
-
}
|
| 132 |
-
|
| 133 |
-
.cg-import-error {
|
| 134 |
-
margin: 0;
|
| 135 |
-
padding: 10px 16px;
|
| 136 |
-
background: var(--lp-red-tint);
|
| 137 |
-
color: var(--lp-red-deep);
|
| 138 |
-
font-size: var(--lp-fs-xs);
|
| 139 |
-
}
|
| 140 |
-
|
| 141 |
-
.cg-import-foot {
|
| 142 |
-
display: flex;
|
| 143 |
-
align-items: center;
|
| 144 |
-
justify-content: flex-end;
|
| 145 |
-
gap: 8px;
|
| 146 |
-
padding: 12px 16px;
|
| 147 |
-
border-top: 1px solid var(--lp-line);
|
| 148 |
-
}
|
| 149 |
-
|
| 150 |
-
.cg-import-count {
|
| 151 |
-
margin-right: auto;
|
| 152 |
-
font-size: var(--lp-fs-xs);
|
| 153 |
-
color: var(--lp-muted);
|
| 154 |
-
}
|
|
|
|
| 1 |
+
/* customer-grid / ImportDialog.css β WAVE-29 T25 (owner item 6).
|
| 2 |
+
Tokens only (`--lp-*`): this file may not invent a colour, and `index.css` is another
|
| 3 |
+
session's fence, so the dialog's own styles live beside its component. */
|
| 4 |
+
|
| 5 |
+
.cg-import-scrim {
|
| 6 |
+
position: fixed;
|
| 7 |
+
inset: 0;
|
| 8 |
+
z-index: 60;
|
| 9 |
+
display: flex;
|
| 10 |
+
align-items: center;
|
| 11 |
+
justify-content: center;
|
| 12 |
+
background: rgba(32, 36, 51, 0.28);
|
| 13 |
+
padding: 24px;
|
| 14 |
+
}
|
| 15 |
+
|
| 16 |
+
.cg-import {
|
| 17 |
+
display: flex;
|
| 18 |
+
flex-direction: column;
|
| 19 |
+
width: min(560px, 100%);
|
| 20 |
+
max-height: min(80vh, 720px);
|
| 21 |
+
background: var(--lp-bg);
|
| 22 |
+
border: 1px solid var(--lp-line);
|
| 23 |
+
border-radius: var(--lp-r-lg);
|
| 24 |
+
box-shadow: 0 12px 32px rgba(32, 36, 51, 0.18);
|
| 25 |
+
overflow: hidden;
|
| 26 |
+
}
|
| 27 |
+
|
| 28 |
+
.cg-import-head {
|
| 29 |
+
display: flex;
|
| 30 |
+
align-items: center;
|
| 31 |
+
justify-content: space-between;
|
| 32 |
+
gap: 12px;
|
| 33 |
+
padding: 14px 16px;
|
| 34 |
+
border-bottom: 1px solid var(--lp-line);
|
| 35 |
+
}
|
| 36 |
+
|
| 37 |
+
.cg-import-head h2 {
|
| 38 |
+
margin: 0;
|
| 39 |
+
font-size: var(--lp-fs-md);
|
| 40 |
+
font-weight: 600;
|
| 41 |
+
color: var(--lp-ink);
|
| 42 |
+
}
|
| 43 |
+
|
| 44 |
+
.cg-import-x {
|
| 45 |
+
border: 0;
|
| 46 |
+
background: none;
|
| 47 |
+
color: var(--lp-muted);
|
| 48 |
+
font-size: var(--lp-fs-lg);
|
| 49 |
+
line-height: 1;
|
| 50 |
+
cursor: pointer;
|
| 51 |
+
padding: 2px 6px;
|
| 52 |
+
}
|
| 53 |
+
|
| 54 |
+
.cg-import-x:hover {
|
| 55 |
+
color: var(--lp-ink);
|
| 56 |
+
}
|
| 57 |
+
|
| 58 |
+
.cg-import-body {
|
| 59 |
+
padding: 14px 16px;
|
| 60 |
+
overflow: auto;
|
| 61 |
+
}
|
| 62 |
+
|
| 63 |
+
.cg-import-lede {
|
| 64 |
+
margin: 0 0 8px;
|
| 65 |
+
font-size: var(--lp-fs-sm);
|
| 66 |
+
color: var(--lp-ink);
|
| 67 |
+
}
|
| 68 |
+
|
| 69 |
+
.cg-import-note {
|
| 70 |
+
margin: 0 0 12px;
|
| 71 |
+
font-size: var(--lp-fs-xs);
|
| 72 |
+
color: var(--lp-muted);
|
| 73 |
+
}
|
| 74 |
+
|
| 75 |
+
.cg-import-file {
|
| 76 |
+
font-size: var(--lp-fs-sm);
|
| 77 |
+
}
|
| 78 |
+
|
| 79 |
+
/* The mapping list: the spreadsheet's column on the left, this database's field on the right,
|
| 80 |
+
so the eye reads it as "this becomes that" rather than as a form. */
|
| 81 |
+
.cg-import-map {
|
| 82 |
+
display: flex;
|
| 83 |
+
flex-direction: column;
|
| 84 |
+
gap: 6px;
|
| 85 |
+
}
|
| 86 |
+
|
| 87 |
+
.cg-import-row {
|
| 88 |
+
display: grid;
|
| 89 |
+
grid-template-columns: 1fr 200px;
|
| 90 |
+
align-items: center;
|
| 91 |
+
gap: 10px;
|
| 92 |
+
}
|
| 93 |
+
|
| 94 |
+
.cg-import-col {
|
| 95 |
+
font-size: var(--lp-fs-sm);
|
| 96 |
+
color: var(--lp-ink);
|
| 97 |
+
overflow: hidden;
|
| 98 |
+
text-overflow: ellipsis;
|
| 99 |
+
white-space: nowrap;
|
| 100 |
+
}
|
| 101 |
+
|
| 102 |
+
.cg-import-row select {
|
| 103 |
+
font-family: inherit;
|
| 104 |
+
font-size: var(--lp-fs-xs);
|
| 105 |
+
padding: 4px 6px;
|
| 106 |
+
border: 1px solid var(--lp-line);
|
| 107 |
+
border-radius: var(--lp-r-sm);
|
| 108 |
+
background: var(--lp-bg);
|
| 109 |
+
color: var(--lp-ink);
|
| 110 |
+
}
|
| 111 |
+
|
| 112 |
+
/* A refusal is not an error state to be styled red-alert; it is a list of things to fix, so it
|
| 113 |
+
takes the yellow tint the rest of the product uses for "look at this before continuing". */
|
| 114 |
+
.cg-import-problems {
|
| 115 |
+
margin-top: 12px;
|
| 116 |
+
padding: 10px 12px;
|
| 117 |
+
border: 1px solid var(--lp-yellow);
|
| 118 |
+
border-radius: var(--lp-r-sm);
|
| 119 |
+
background: var(--lp-yellow-tint);
|
| 120 |
+
color: var(--lp-yellow-deep);
|
| 121 |
+
font-size: var(--lp-fs-xs);
|
| 122 |
+
}
|
| 123 |
+
|
| 124 |
+
.cg-import-problems ul {
|
| 125 |
+
margin: 6px 0;
|
| 126 |
+
padding-left: 18px;
|
| 127 |
+
}
|
| 128 |
+
|
| 129 |
+
.cg-import-problems p {
|
| 130 |
+
margin: 6px 0 0;
|
| 131 |
+
}
|
| 132 |
+
|
| 133 |
+
.cg-import-error {
|
| 134 |
+
margin: 0;
|
| 135 |
+
padding: 10px 16px;
|
| 136 |
+
background: var(--lp-red-tint);
|
| 137 |
+
color: var(--lp-red-deep);
|
| 138 |
+
font-size: var(--lp-fs-xs);
|
| 139 |
+
}
|
| 140 |
+
|
| 141 |
+
.cg-import-foot {
|
| 142 |
+
display: flex;
|
| 143 |
+
align-items: center;
|
| 144 |
+
justify-content: flex-end;
|
| 145 |
+
gap: 8px;
|
| 146 |
+
padding: 12px 16px;
|
| 147 |
+
border-top: 1px solid var(--lp-line);
|
| 148 |
+
}
|
| 149 |
+
|
| 150 |
+
.cg-import-count {
|
| 151 |
+
margin-right: auto;
|
| 152 |
+
font-size: var(--lp-fs-xs);
|
| 153 |
+
color: var(--lp-muted);
|
| 154 |
+
}
|
web/src/customer-grid/ImportDialog.tsx
CHANGED
|
@@ -1,299 +1,299 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// customer-grid / ImportDialog.tsx
|
| 3 |
-
//
|
| 4 |
-
// ββ WAVE-29 T25 (owner item 6) β IMPORT A SPREADSHEET INTO A USER DATABASE.
|
| 5 |
-
//
|
| 6 |
-
// Three steps in one window, because each answers the question the last one raised:
|
| 7 |
-
// 1. pick a file -> the server parses it and says which columns it found
|
| 8 |
-
// 2. map its columns -> to fields, or to nothing; unmapped is the default
|
| 9 |
-
// 3. check + import -> every value coerced FIRST, the problems named BEFORE anything writes
|
| 10 |
-
//
|
| 11 |
-
// β APPEND-ONLY IN V1, AND THE DIALOG SAYS SO. Nothing is matched, nothing is overwritten β every
|
| 12 |
-
// row becomes a new record. The only bulk-merge primitive in the product is upsert-BY-KEY shaped,
|
| 13 |
-
// and choosing a key on the user's behalf is how an import quietly rewrites rows somebody edited.
|
| 14 |
-
// The sentence is on screen rather than in a doc, because that is where the decision is made.
|
| 15 |
-
//
|
| 16 |
-
// β REUSE, NOT A SECOND COERCER. `clipboard.coerceClipboardValue` is THE client answer to "can
|
| 17 |
-
// this text be this field's value" (it is what a paste already goes through), and
|
| 18 |
-
// `POST /api/v1/uploads/tabular` is the parser that already exists β 5 MB / 20,000 rows, xlsx AND
|
| 19 |
-
// csv, and it never writes a row. A second copy of either is a second set of rules for one
|
| 20 |
-
// question ([[one-evaluator-per-question]]).
|
| 21 |
-
//
|
| 22 |
-
// β THE SERVER IS THE WALL, not this dialog. It refuses computed columns BY NAME and refuses the
|
| 23 |
-
// whole batch if it would pass the row cap. What happens here is the part a person needs before
|
| 24 |
-
// they press the button: which column goes where, and what will not survive the trip.
|
| 25 |
-
// ---------------------------------------------------------------------------
|
| 26 |
-
|
| 27 |
-
import { useMemo, useRef, useState } from "react";
|
| 28 |
-
// β From `apiContract`, which is where these two are DECLARED β not re-exported from
|
| 29 |
-
// `apiBridge`, which does not export them and is another session's fence this wave.
|
| 30 |
-
import { API_V1, CREDENTIALS } from "../apiContract";
|
| 31 |
-
import { isImportTarget } from "./types";
|
| 32 |
-
import type { Field } from "./types";
|
| 33 |
-
// β W29-T76 β the plan lives in a pure module so a test can EXECUTE it against the server's real
|
| 34 |
-
// payload. This file holds the WINDOW; `importPlan.ts` holds what would be written.
|
| 35 |
-
import { buildImportPlan } from "./importPlan";
|
| 36 |
-
import type { ImportMapping, ParsedUpload } from "./importPlan";
|
| 37 |
-
import "./ImportDialog.css";
|
| 38 |
-
|
| 39 |
-
/** The one header a JSON POST needs. `apiBridge` keeps its own module-local copy; this is a
|
| 40 |
-
* literal rather than an import because that constant is not exported and that file is not
|
| 41 |
-
* this session's to change. */
|
| 42 |
-
const JSON_HEADERS = { "Content-Type": "application/json" };
|
| 43 |
-
|
| 44 |
-
/** The upload door's answer (`routes_uploads.tabular`) β declared in `importPlan.ts`, beside the
|
| 45 |
-
* only code that reads its shape. β It is COLUMN-MAJOR; the copy that used to live here said
|
| 46 |
-
* `string[][]` and that one wrong word is why nothing ever imported. */
|
| 47 |
-
type Parsed = ParsedUpload;
|
| 48 |
-
|
| 49 |
-
export interface ImportDialogProps {
|
| 50 |
-
/** The target database's fields β the mapping targets, before this file filters them. */
|
| 51 |
-
fields: Field[];
|
| 52 |
-
/** `ut_*` table key; the import door is per-table. */
|
| 53 |
-
scope: string;
|
| 54 |
-
/** How the database calls itself, for the sentence that says where rows are going. */
|
| 55 |
-
tableName: string;
|
| 56 |
-
/** Fired after a successful import so the host can re-read its rows. */
|
| 57 |
-
onImported: (count: number) => void;
|
| 58 |
-
onClose: () => void;
|
| 59 |
-
}
|
| 60 |
-
|
| 61 |
-
const NONE = "";
|
| 62 |
-
|
| 63 |
-
export default function ImportDialog({
|
| 64 |
-
fields,
|
| 65 |
-
scope,
|
| 66 |
-
tableName,
|
| 67 |
-
onImported,
|
| 68 |
-
onClose,
|
| 69 |
-
}: ImportDialogProps): React.ReactElement {
|
| 70 |
-
const [parsed, setParsed] = useState<Parsed | null>(null);
|
| 71 |
-
const [mapping, setMapping] = useState<ImportMapping>({});
|
| 72 |
-
const [busy, setBusy] = useState(false);
|
| 73 |
-
const [error, setError] = useState("");
|
| 74 |
-
const fileRef = useRef<HTMLInputElement | null>(null);
|
| 75 |
-
|
| 76 |
-
const targets = useMemo(() => fields.filter(isImportTarget), [fields]);
|
| 77 |
-
|
| 78 |
-
/**
|
| 79 |
-
* The parse. `FormData` and NO `Content-Type` header: the browser has to set the multipart
|
| 80 |
-
* boundary itself, and spelling the header by hand is the classic way to make a working upload
|
| 81 |
-
* 400 with a message about a missing part.
|
| 82 |
-
*/
|
| 83 |
-
async function pick(file: File): Promise<void> {
|
| 84 |
-
setBusy(true);
|
| 85 |
-
setError("");
|
| 86 |
-
try {
|
| 87 |
-
const form = new FormData();
|
| 88 |
-
form.append("file", file);
|
| 89 |
-
const res = await fetch(`${API_V1}/uploads/tabular`, {
|
| 90 |
-
method: "POST",
|
| 91 |
-
credentials: CREDENTIALS,
|
| 92 |
-
body: form,
|
| 93 |
-
});
|
| 94 |
-
const body = (await res.json().catch(() => null)) as
|
| 95 |
-
| (Parsed & { error?: { message?: string } })
|
| 96 |
-
| null;
|
| 97 |
-
if (!res.ok || !body) {
|
| 98 |
-
setError(
|
| 99 |
-
body?.error?.message ??
|
| 100 |
-
`That file could not be read (the server answered ${res.status}).`
|
| 101 |
-
);
|
| 102 |
-
return;
|
| 103 |
-
}
|
| 104 |
-
setParsed(body);
|
| 105 |
-
// β AUTO-MAP BY NAME, case- and space-insensitively, because the overwhelmingly common
|
| 106 |
-
// case is a sheet exported from this very grid. Every guess is VISIBLE in a picker the
|
| 107 |
-
// user can change β a silent auto-map is only dangerous when it is also invisible.
|
| 108 |
-
const byName = new Map(
|
| 109 |
-
targets.map((f) => [f.label.trim().toLowerCase(), f.key] as const)
|
| 110 |
-
);
|
| 111 |
-
const guess: ImportMapping = {};
|
| 112 |
-
(body.columns ?? []).forEach((name, i) => {
|
| 113 |
-
const hit = byName.get(String(name).trim().toLowerCase());
|
| 114 |
-
if (hit) guess[i] = hit;
|
| 115 |
-
});
|
| 116 |
-
setMapping(guess);
|
| 117 |
-
} catch {
|
| 118 |
-
setError("That file could not be read.");
|
| 119 |
-
} finally {
|
| 120 |
-
setBusy(false);
|
| 121 |
-
}
|
| 122 |
-
}
|
| 123 |
-
|
| 124 |
-
/**
|
| 125 |
-
* What would be written, and what cannot be. The work is `importPlan.buildImportPlan` β a pure
|
| 126 |
-
* module, so the node suite executes it against the server's real payload rather than grepping
|
| 127 |
-
* this file for the shape of a loop.
|
| 128 |
-
*/
|
| 129 |
-
const plan = useMemo(
|
| 130 |
-
() => buildImportPlan(parsed, mapping, targets),
|
| 131 |
-
[parsed, mapping, targets]
|
| 132 |
-
);
|
| 133 |
-
|
| 134 |
-
async function run(): Promise<void> {
|
| 135 |
-
setBusy(true);
|
| 136 |
-
setError("");
|
| 137 |
-
try {
|
| 138 |
-
const res = await fetch(
|
| 139 |
-
`${API_V1}/tables/${encodeURIComponent(scope)}/rows/import`,
|
| 140 |
-
{
|
| 141 |
-
method: "POST",
|
| 142 |
-
credentials: CREDENTIALS,
|
| 143 |
-
headers: JSON_HEADERS,
|
| 144 |
-
body: JSON.stringify({ rows: plan.rows }),
|
| 145 |
-
}
|
| 146 |
-
);
|
| 147 |
-
const body = (await res.json().catch(() => null)) as
|
| 148 |
-
| { imported?: number; error?: { message?: string } }
|
| 149 |
-
| null;
|
| 150 |
-
if (!res.ok) {
|
| 151 |
-
// The server's sentence beats anything invented here: it names the column, or the cap.
|
| 152 |
-
setError(body?.error?.message ?? `The server answered ${res.status}.`);
|
| 153 |
-
return;
|
| 154 |
-
}
|
| 155 |
-
onImported(body?.imported ?? plan.rows.length);
|
| 156 |
-
onClose();
|
| 157 |
-
} catch {
|
| 158 |
-
setError("Nothing was imported β the request did not complete.");
|
| 159 |
-
} finally {
|
| 160 |
-
setBusy(false);
|
| 161 |
-
}
|
| 162 |
-
}
|
| 163 |
-
|
| 164 |
-
const mappedCount = Object.values(mapping).filter((k) => k !== NONE).length;
|
| 165 |
-
|
| 166 |
-
return (
|
| 167 |
-
<div className="cg-import-scrim" role="presentation" onClick={onClose}>
|
| 168 |
-
<div
|
| 169 |
-
className="cg-import"
|
| 170 |
-
role="dialog"
|
| 171 |
-
aria-modal="true"
|
| 172 |
-
aria-label={`Import records into ${tableName}`}
|
| 173 |
-
onClick={(event) => event.stopPropagation()}
|
| 174 |
-
>
|
| 175 |
-
<div className="cg-import-head">
|
| 176 |
-
<h2>Import records</h2>
|
| 177 |
-
<button type="button" className="cg-import-x" aria-label="Close" onClick={onClose}>
|
| 178 |
-
Γ
|
| 179 |
-
</button>
|
| 180 |
-
</div>
|
| 181 |
-
|
| 182 |
-
{!parsed ? (
|
| 183 |
-
<div className="cg-import-body">
|
| 184 |
-
<p className="cg-import-lede">
|
| 185 |
-
Add records to <strong>{tableName}</strong> from a spreadsheet. Excel
|
| 186 |
-
(<code>.xlsx</code>) or <code>.csv</code>, up to 5 MB.
|
| 187 |
-
</p>
|
| 188 |
-
<p className="cg-import-note">
|
| 189 |
-
Every row becomes a <strong>new record</strong>. Nothing already in this database is
|
| 190 |
-
matched or overwritten.
|
| 191 |
-
</p>
|
| 192 |
-
<input
|
| 193 |
-
ref={fileRef}
|
| 194 |
-
type="file"
|
| 195 |
-
accept=".xlsx,.csv"
|
| 196 |
-
className="cg-import-file"
|
| 197 |
-
onChange={(event) => {
|
| 198 |
-
const file = event.currentTarget.files?.[0];
|
| 199 |
-
if (file) void pick(file);
|
| 200 |
-
}}
|
| 201 |
-
/>
|
| 202 |
-
</div>
|
| 203 |
-
) : (
|
| 204 |
-
<div className="cg-import-body">
|
| 205 |
-
<p className="cg-import-lede">
|
| 206 |
-
{parsed.rows.toLocaleString()} row{parsed.rows === 1 ? "" : "s"} read
|
| 207 |
-
{parsed.truncated ? " (the first 20,000 β the rest were not read)" : ""}. Choose
|
| 208 |
-
where each column goes.
|
| 209 |
-
</p>
|
| 210 |
-
<div className="cg-import-map" role="list">
|
| 211 |
-
{parsed.columns.map((name, i) => (
|
| 212 |
-
<label className="cg-import-row" role="listitem" key={`${name}:${i}`}>
|
| 213 |
-
<span className="cg-import-col" title={name}>
|
| 214 |
-
{name || `Column ${i + 1}`}
|
| 215 |
-
</span>
|
| 216 |
-
<select
|
| 217 |
-
value={mapping[i] ?? NONE}
|
| 218 |
-
onChange={(event) => {
|
| 219 |
-
const next = event.target.value;
|
| 220 |
-
setMapping((cur) => ({ ...cur, [i]: next }));
|
| 221 |
-
}}
|
| 222 |
-
>
|
| 223 |
-
<option value={NONE}>Don’t import</option>
|
| 224 |
-
{targets.map((f) => (
|
| 225 |
-
<option key={f.key} value={f.key}>
|
| 226 |
-
{f.label}
|
| 227 |
-
</option>
|
| 228 |
-
))}
|
| 229 |
-
</select>
|
| 230 |
-
</label>
|
| 231 |
-
))}
|
| 232 |
-
</div>
|
| 233 |
-
{plan.problems.length > 0 && (
|
| 234 |
-
<div className="cg-import-problems" role="alert">
|
| 235 |
-
<strong>
|
| 236 |
-
{plan.problems.length.toLocaleString()} value
|
| 237 |
-
{plan.problems.length === 1 ? "" : "s"} cannot go in the column
|
| 238 |
-
{plan.problems.length === 1 ? "" : "s"} chosen for them
|
| 239 |
-
</strong>
|
| 240 |
-
<ul>
|
| 241 |
-
{plan.problems.slice(0, 5).map((p, i) => (
|
| 242 |
-
<li key={i}>
|
| 243 |
-
Row {p.row}, {p.column}: {p.value ? `β${p.value}β` : "(blank)"} is not a
|
| 244 |
-
valid {p.field}
|
| 245 |
-
</li>
|
| 246 |
-
))}
|
| 247 |
-
</ul>
|
| 248 |
-
{plan.problems.length > 5 && (
|
| 249 |
-
<p>β¦and {(plan.problems.length - 5).toLocaleString()} more.</p>
|
| 250 |
-
)}
|
| 251 |
-
<p>
|
| 252 |
-
Fix them in the file, or point that column somewhere else β nothing has been
|
| 253 |
-
imported yet.
|
| 254 |
-
</p>
|
| 255 |
-
</div>
|
| 256 |
-
)}
|
| 257 |
-
</div>
|
| 258 |
-
)}
|
| 259 |
-
|
| 260 |
-
{error && (
|
| 261 |
-
<p className="cg-import-error" role="alert">
|
| 262 |
-
{error}
|
| 263 |
-
</p>
|
| 264 |
-
)}
|
| 265 |
-
|
| 266 |
-
<div className="cg-import-foot">
|
| 267 |
-
{parsed && (
|
| 268 |
-
<span className="cg-import-count">
|
| 269 |
-
{mappedCount === 0
|
| 270 |
-
? "No columns chosen yet"
|
| 271 |
-
: `${plan.rows.length.toLocaleString()} record${
|
| 272 |
-
plan.rows.length === 1 ? "" : "s"
|
| 273 |
-
} from ${mappedCount} column${mappedCount === 1 ? "" : "s"}`}
|
| 274 |
-
</span>
|
| 275 |
-
)}
|
| 276 |
-
<button type="button" className="cg-btn" onClick={onClose}>
|
| 277 |
-
Cancel
|
| 278 |
-
</button>
|
| 279 |
-
{parsed && (
|
| 280 |
-
<button
|
| 281 |
-
type="button"
|
| 282 |
-
className="cg-btn cg-btn--primary"
|
| 283 |
-
/* β DISABLED WHILE ANY VALUE IS REFUSED. The alternative β import the good rows and
|
| 284 |
-
report the rest β leaves somebody reconciling a spreadsheet against a table by
|
| 285 |
-
hand, and neither existing write door demonstrates a partial policy. Refusing
|
| 286 |
-
whole is recoverable in one edit; a half-import is not. */
|
| 287 |
-
disabled={busy || plan.rows.length === 0 || plan.problems.length > 0}
|
| 288 |
-
onClick={() => void run()}
|
| 289 |
-
>
|
| 290 |
-
{busy ? "Importingβ¦" : `Import ${plan.rows.length.toLocaleString()} record${
|
| 291 |
-
plan.rows.length === 1 ? "" : "s"
|
| 292 |
-
}`}
|
| 293 |
-
</button>
|
| 294 |
-
)}
|
| 295 |
-
</div>
|
| 296 |
-
</div>
|
| 297 |
-
</div>
|
| 298 |
-
);
|
| 299 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// customer-grid / ImportDialog.tsx
|
| 3 |
+
//
|
| 4 |
+
// ββ WAVE-29 T25 (owner item 6) β IMPORT A SPREADSHEET INTO A USER DATABASE.
|
| 5 |
+
//
|
| 6 |
+
// Three steps in one window, because each answers the question the last one raised:
|
| 7 |
+
// 1. pick a file -> the server parses it and says which columns it found
|
| 8 |
+
// 2. map its columns -> to fields, or to nothing; unmapped is the default
|
| 9 |
+
// 3. check + import -> every value coerced FIRST, the problems named BEFORE anything writes
|
| 10 |
+
//
|
| 11 |
+
// β APPEND-ONLY IN V1, AND THE DIALOG SAYS SO. Nothing is matched, nothing is overwritten β every
|
| 12 |
+
// row becomes a new record. The only bulk-merge primitive in the product is upsert-BY-KEY shaped,
|
| 13 |
+
// and choosing a key on the user's behalf is how an import quietly rewrites rows somebody edited.
|
| 14 |
+
// The sentence is on screen rather than in a doc, because that is where the decision is made.
|
| 15 |
+
//
|
| 16 |
+
// β REUSE, NOT A SECOND COERCER. `clipboard.coerceClipboardValue` is THE client answer to "can
|
| 17 |
+
// this text be this field's value" (it is what a paste already goes through), and
|
| 18 |
+
// `POST /api/v1/uploads/tabular` is the parser that already exists β 5 MB / 20,000 rows, xlsx AND
|
| 19 |
+
// csv, and it never writes a row. A second copy of either is a second set of rules for one
|
| 20 |
+
// question ([[one-evaluator-per-question]]).
|
| 21 |
+
//
|
| 22 |
+
// β THE SERVER IS THE WALL, not this dialog. It refuses computed columns BY NAME and refuses the
|
| 23 |
+
// whole batch if it would pass the row cap. What happens here is the part a person needs before
|
| 24 |
+
// they press the button: which column goes where, and what will not survive the trip.
|
| 25 |
+
// ---------------------------------------------------------------------------
|
| 26 |
+
|
| 27 |
+
import { useMemo, useRef, useState } from "react";
|
| 28 |
+
// β From `apiContract`, which is where these two are DECLARED β not re-exported from
|
| 29 |
+
// `apiBridge`, which does not export them and is another session's fence this wave.
|
| 30 |
+
import { API_V1, CREDENTIALS } from "../apiContract";
|
| 31 |
+
import { isImportTarget } from "./types";
|
| 32 |
+
import type { Field } from "./types";
|
| 33 |
+
// β W29-T76 β the plan lives in a pure module so a test can EXECUTE it against the server's real
|
| 34 |
+
// payload. This file holds the WINDOW; `importPlan.ts` holds what would be written.
|
| 35 |
+
import { buildImportPlan } from "./importPlan";
|
| 36 |
+
import type { ImportMapping, ParsedUpload } from "./importPlan";
|
| 37 |
+
import "./ImportDialog.css";
|
| 38 |
+
|
| 39 |
+
/** The one header a JSON POST needs. `apiBridge` keeps its own module-local copy; this is a
|
| 40 |
+
* literal rather than an import because that constant is not exported and that file is not
|
| 41 |
+
* this session's to change. */
|
| 42 |
+
const JSON_HEADERS = { "Content-Type": "application/json" };
|
| 43 |
+
|
| 44 |
+
/** The upload door's answer (`routes_uploads.tabular`) β declared in `importPlan.ts`, beside the
|
| 45 |
+
* only code that reads its shape. β It is COLUMN-MAJOR; the copy that used to live here said
|
| 46 |
+
* `string[][]` and that one wrong word is why nothing ever imported. */
|
| 47 |
+
type Parsed = ParsedUpload;
|
| 48 |
+
|
| 49 |
+
export interface ImportDialogProps {
|
| 50 |
+
/** The target database's fields β the mapping targets, before this file filters them. */
|
| 51 |
+
fields: Field[];
|
| 52 |
+
/** `ut_*` table key; the import door is per-table. */
|
| 53 |
+
scope: string;
|
| 54 |
+
/** How the database calls itself, for the sentence that says where rows are going. */
|
| 55 |
+
tableName: string;
|
| 56 |
+
/** Fired after a successful import so the host can re-read its rows. */
|
| 57 |
+
onImported: (count: number) => void;
|
| 58 |
+
onClose: () => void;
|
| 59 |
+
}
|
| 60 |
+
|
| 61 |
+
const NONE = "";
|
| 62 |
+
|
| 63 |
+
export default function ImportDialog({
|
| 64 |
+
fields,
|
| 65 |
+
scope,
|
| 66 |
+
tableName,
|
| 67 |
+
onImported,
|
| 68 |
+
onClose,
|
| 69 |
+
}: ImportDialogProps): React.ReactElement {
|
| 70 |
+
const [parsed, setParsed] = useState<Parsed | null>(null);
|
| 71 |
+
const [mapping, setMapping] = useState<ImportMapping>({});
|
| 72 |
+
const [busy, setBusy] = useState(false);
|
| 73 |
+
const [error, setError] = useState("");
|
| 74 |
+
const fileRef = useRef<HTMLInputElement | null>(null);
|
| 75 |
+
|
| 76 |
+
const targets = useMemo(() => fields.filter(isImportTarget), [fields]);
|
| 77 |
+
|
| 78 |
+
/**
|
| 79 |
+
* The parse. `FormData` and NO `Content-Type` header: the browser has to set the multipart
|
| 80 |
+
* boundary itself, and spelling the header by hand is the classic way to make a working upload
|
| 81 |
+
* 400 with a message about a missing part.
|
| 82 |
+
*/
|
| 83 |
+
async function pick(file: File): Promise<void> {
|
| 84 |
+
setBusy(true);
|
| 85 |
+
setError("");
|
| 86 |
+
try {
|
| 87 |
+
const form = new FormData();
|
| 88 |
+
form.append("file", file);
|
| 89 |
+
const res = await fetch(`${API_V1}/uploads/tabular`, {
|
| 90 |
+
method: "POST",
|
| 91 |
+
credentials: CREDENTIALS,
|
| 92 |
+
body: form,
|
| 93 |
+
});
|
| 94 |
+
const body = (await res.json().catch(() => null)) as
|
| 95 |
+
| (Parsed & { error?: { message?: string } })
|
| 96 |
+
| null;
|
| 97 |
+
if (!res.ok || !body) {
|
| 98 |
+
setError(
|
| 99 |
+
body?.error?.message ??
|
| 100 |
+
`That file could not be read (the server answered ${res.status}).`
|
| 101 |
+
);
|
| 102 |
+
return;
|
| 103 |
+
}
|
| 104 |
+
setParsed(body);
|
| 105 |
+
// β AUTO-MAP BY NAME, case- and space-insensitively, because the overwhelmingly common
|
| 106 |
+
// case is a sheet exported from this very grid. Every guess is VISIBLE in a picker the
|
| 107 |
+
// user can change β a silent auto-map is only dangerous when it is also invisible.
|
| 108 |
+
const byName = new Map(
|
| 109 |
+
targets.map((f) => [f.label.trim().toLowerCase(), f.key] as const)
|
| 110 |
+
);
|
| 111 |
+
const guess: ImportMapping = {};
|
| 112 |
+
(body.columns ?? []).forEach((name, i) => {
|
| 113 |
+
const hit = byName.get(String(name).trim().toLowerCase());
|
| 114 |
+
if (hit) guess[i] = hit;
|
| 115 |
+
});
|
| 116 |
+
setMapping(guess);
|
| 117 |
+
} catch {
|
| 118 |
+
setError("That file could not be read.");
|
| 119 |
+
} finally {
|
| 120 |
+
setBusy(false);
|
| 121 |
+
}
|
| 122 |
+
}
|
| 123 |
+
|
| 124 |
+
/**
|
| 125 |
+
* What would be written, and what cannot be. The work is `importPlan.buildImportPlan` β a pure
|
| 126 |
+
* module, so the node suite executes it against the server's real payload rather than grepping
|
| 127 |
+
* this file for the shape of a loop.
|
| 128 |
+
*/
|
| 129 |
+
const plan = useMemo(
|
| 130 |
+
() => buildImportPlan(parsed, mapping, targets),
|
| 131 |
+
[parsed, mapping, targets]
|
| 132 |
+
);
|
| 133 |
+
|
| 134 |
+
async function run(): Promise<void> {
|
| 135 |
+
setBusy(true);
|
| 136 |
+
setError("");
|
| 137 |
+
try {
|
| 138 |
+
const res = await fetch(
|
| 139 |
+
`${API_V1}/tables/${encodeURIComponent(scope)}/rows/import`,
|
| 140 |
+
{
|
| 141 |
+
method: "POST",
|
| 142 |
+
credentials: CREDENTIALS,
|
| 143 |
+
headers: JSON_HEADERS,
|
| 144 |
+
body: JSON.stringify({ rows: plan.rows }),
|
| 145 |
+
}
|
| 146 |
+
);
|
| 147 |
+
const body = (await res.json().catch(() => null)) as
|
| 148 |
+
| { imported?: number; error?: { message?: string } }
|
| 149 |
+
| null;
|
| 150 |
+
if (!res.ok) {
|
| 151 |
+
// The server's sentence beats anything invented here: it names the column, or the cap.
|
| 152 |
+
setError(body?.error?.message ?? `The server answered ${res.status}.`);
|
| 153 |
+
return;
|
| 154 |
+
}
|
| 155 |
+
onImported(body?.imported ?? plan.rows.length);
|
| 156 |
+
onClose();
|
| 157 |
+
} catch {
|
| 158 |
+
setError("Nothing was imported β the request did not complete.");
|
| 159 |
+
} finally {
|
| 160 |
+
setBusy(false);
|
| 161 |
+
}
|
| 162 |
+
}
|
| 163 |
+
|
| 164 |
+
const mappedCount = Object.values(mapping).filter((k) => k !== NONE).length;
|
| 165 |
+
|
| 166 |
+
return (
|
| 167 |
+
<div className="cg-import-scrim" role="presentation" onClick={onClose}>
|
| 168 |
+
<div
|
| 169 |
+
className="cg-import"
|
| 170 |
+
role="dialog"
|
| 171 |
+
aria-modal="true"
|
| 172 |
+
aria-label={`Import records into ${tableName}`}
|
| 173 |
+
onClick={(event) => event.stopPropagation()}
|
| 174 |
+
>
|
| 175 |
+
<div className="cg-import-head">
|
| 176 |
+
<h2>Import records</h2>
|
| 177 |
+
<button type="button" className="cg-import-x" aria-label="Close" onClick={onClose}>
|
| 178 |
+
Γ
|
| 179 |
+
</button>
|
| 180 |
+
</div>
|
| 181 |
+
|
| 182 |
+
{!parsed ? (
|
| 183 |
+
<div className="cg-import-body">
|
| 184 |
+
<p className="cg-import-lede">
|
| 185 |
+
Add records to <strong>{tableName}</strong> from a spreadsheet. Excel
|
| 186 |
+
(<code>.xlsx</code>) or <code>.csv</code>, up to 5 MB.
|
| 187 |
+
</p>
|
| 188 |
+
<p className="cg-import-note">
|
| 189 |
+
Every row becomes a <strong>new record</strong>. Nothing already in this database is
|
| 190 |
+
matched or overwritten.
|
| 191 |
+
</p>
|
| 192 |
+
<input
|
| 193 |
+
ref={fileRef}
|
| 194 |
+
type="file"
|
| 195 |
+
accept=".xlsx,.csv"
|
| 196 |
+
className="cg-import-file"
|
| 197 |
+
onChange={(event) => {
|
| 198 |
+
const file = event.currentTarget.files?.[0];
|
| 199 |
+
if (file) void pick(file);
|
| 200 |
+
}}
|
| 201 |
+
/>
|
| 202 |
+
</div>
|
| 203 |
+
) : (
|
| 204 |
+
<div className="cg-import-body">
|
| 205 |
+
<p className="cg-import-lede">
|
| 206 |
+
{parsed.rows.toLocaleString()} row{parsed.rows === 1 ? "" : "s"} read
|
| 207 |
+
{parsed.truncated ? " (the first 20,000 β the rest were not read)" : ""}. Choose
|
| 208 |
+
where each column goes.
|
| 209 |
+
</p>
|
| 210 |
+
<div className="cg-import-map" role="list">
|
| 211 |
+
{parsed.columns.map((name, i) => (
|
| 212 |
+
<label className="cg-import-row" role="listitem" key={`${name}:${i}`}>
|
| 213 |
+
<span className="cg-import-col" title={name}>
|
| 214 |
+
{name || `Column ${i + 1}`}
|
| 215 |
+
</span>
|
| 216 |
+
<select
|
| 217 |
+
value={mapping[i] ?? NONE}
|
| 218 |
+
onChange={(event) => {
|
| 219 |
+
const next = event.target.value;
|
| 220 |
+
setMapping((cur) => ({ ...cur, [i]: next }));
|
| 221 |
+
}}
|
| 222 |
+
>
|
| 223 |
+
<option value={NONE}>Don’t import</option>
|
| 224 |
+
{targets.map((f) => (
|
| 225 |
+
<option key={f.key} value={f.key}>
|
| 226 |
+
{f.label}
|
| 227 |
+
</option>
|
| 228 |
+
))}
|
| 229 |
+
</select>
|
| 230 |
+
</label>
|
| 231 |
+
))}
|
| 232 |
+
</div>
|
| 233 |
+
{plan.problems.length > 0 && (
|
| 234 |
+
<div className="cg-import-problems" role="alert">
|
| 235 |
+
<strong>
|
| 236 |
+
{plan.problems.length.toLocaleString()} value
|
| 237 |
+
{plan.problems.length === 1 ? "" : "s"} cannot go in the column
|
| 238 |
+
{plan.problems.length === 1 ? "" : "s"} chosen for them
|
| 239 |
+
</strong>
|
| 240 |
+
<ul>
|
| 241 |
+
{plan.problems.slice(0, 5).map((p, i) => (
|
| 242 |
+
<li key={i}>
|
| 243 |
+
Row {p.row}, {p.column}: {p.value ? `β${p.value}β` : "(blank)"} is not a
|
| 244 |
+
valid {p.field}
|
| 245 |
+
</li>
|
| 246 |
+
))}
|
| 247 |
+
</ul>
|
| 248 |
+
{plan.problems.length > 5 && (
|
| 249 |
+
<p>β¦and {(plan.problems.length - 5).toLocaleString()} more.</p>
|
| 250 |
+
)}
|
| 251 |
+
<p>
|
| 252 |
+
Fix them in the file, or point that column somewhere else β nothing has been
|
| 253 |
+
imported yet.
|
| 254 |
+
</p>
|
| 255 |
+
</div>
|
| 256 |
+
)}
|
| 257 |
+
</div>
|
| 258 |
+
)}
|
| 259 |
+
|
| 260 |
+
{error && (
|
| 261 |
+
<p className="cg-import-error" role="alert">
|
| 262 |
+
{error}
|
| 263 |
+
</p>
|
| 264 |
+
)}
|
| 265 |
+
|
| 266 |
+
<div className="cg-import-foot">
|
| 267 |
+
{parsed && (
|
| 268 |
+
<span className="cg-import-count">
|
| 269 |
+
{mappedCount === 0
|
| 270 |
+
? "No columns chosen yet"
|
| 271 |
+
: `${plan.rows.length.toLocaleString()} record${
|
| 272 |
+
plan.rows.length === 1 ? "" : "s"
|
| 273 |
+
} from ${mappedCount} column${mappedCount === 1 ? "" : "s"}`}
|
| 274 |
+
</span>
|
| 275 |
+
)}
|
| 276 |
+
<button type="button" className="cg-btn" onClick={onClose}>
|
| 277 |
+
Cancel
|
| 278 |
+
</button>
|
| 279 |
+
{parsed && (
|
| 280 |
+
<button
|
| 281 |
+
type="button"
|
| 282 |
+
className="cg-btn cg-btn--primary"
|
| 283 |
+
/* β DISABLED WHILE ANY VALUE IS REFUSED. The alternative β import the good rows and
|
| 284 |
+
report the rest β leaves somebody reconciling a spreadsheet against a table by
|
| 285 |
+
hand, and neither existing write door demonstrates a partial policy. Refusing
|
| 286 |
+
whole is recoverable in one edit; a half-import is not. */
|
| 287 |
+
disabled={busy || plan.rows.length === 0 || plan.problems.length > 0}
|
| 288 |
+
onClick={() => void run()}
|
| 289 |
+
>
|
| 290 |
+
{busy ? "Importingβ¦" : `Import ${plan.rows.length.toLocaleString()} record${
|
| 291 |
+
plan.rows.length === 1 ? "" : "s"
|
| 292 |
+
}`}
|
| 293 |
+
</button>
|
| 294 |
+
)}
|
| 295 |
+
</div>
|
| 296 |
+
</div>
|
| 297 |
+
</div>
|
| 298 |
+
);
|
| 299 |
+
}
|
web/src/customer-grid/SwipeView.tsx
CHANGED
|
@@ -1,586 +1,586 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// customer-grid / SwipeView.tsx
|
| 3 |
-
// β WAVE-27 item 8 (owner ruling R2, contract C3) β the SWIPE deck.
|
| 4 |
-
//
|
| 5 |
-
// One record at a time, decided left or right into two options of ONE
|
| 6 |
-
// single-select. R2 fixes the shape and it is narrow on purpose:
|
| 7 |
-
// Β· SINGLE-SELECT ONLY, one field, two of its options. No checkbox binding.
|
| 8 |
-
// Β· the deck holds only the records whose bound field is EMPTY β a record
|
| 9 |
-
// that already has a value has been decided, and re-asking is not triage.
|
| 10 |
-
// Β· a swipe writes through the NORMAL cell door (`onSwipe`, which the host
|
| 11 |
-
// maps to the same `patchAndRecord` a kanban card move uses), so undo,
|
| 12 |
-
// echo-suppression and the permission wall all hold without being
|
| 13 |
-
// re-implemented here.
|
| 14 |
-
//
|
| 15 |
-
// Honesty rules carried from the other modes:
|
| 16 |
-
// Β· nothing is silently hidden β the deck states what is left, and the
|
| 17 |
-
// empty state names the bound field rather than saying "all done".
|
| 18 |
-
// Β· a lost binding is SHOWN, never repaired by guessing. `_clean_display`
|
| 19 |
-
// validates that `fieldKey` names a field the table HAS and stops there;
|
| 20 |
-
// it cannot know the field is still a select, or that the two options are
|
| 21 |
-
// still in its vocabulary (its docstring draws that line explicitly). So
|
| 22 |
-
// those three losses land here, and each one says what happened and
|
| 23 |
-
// re-opens the picker β the `viewModes.tsx:190-194` rule, which exists
|
| 24 |
-
// because the wave-7 trap was a picker silently falling back to its first
|
| 25 |
-
// option.
|
| 26 |
-
// ---------------------------------------------------------------------------
|
| 27 |
-
|
| 28 |
-
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
| 29 |
-
// ββ W41-T48 (owner instruction 22) β opening a record from the swipe deck folds the shell's
|
| 30 |
-
// navigation rail exactly as a grid cell click does. Guard rationale: `MapView.tsx:2755`.
|
| 31 |
-
import { NAV_MINIMIZE_EVENT, signal } from "../apiContract";
|
| 32 |
-
import { choiceOptions } from "./types";
|
| 33 |
-
import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
|
| 34 |
-
// β `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
|
| 35 |
-
// loaded here) β the same import `RecordComments` takes for the same prop.
|
| 36 |
-
import type { SurfaceScope } from "./apiBridge";
|
| 37 |
-
import RecordComments from "./RecordComments";
|
| 38 |
-
import { Documents } from "./Documents";
|
| 39 |
-
import { formatDisplay } from "./cells";
|
| 40 |
-
import { actionHref } from "./display";
|
| 41 |
-
import { optionTint } from "./choiceColors";
|
| 42 |
-
import { ModeIcon } from "./icons";
|
| 43 |
-
// β W29-T73 β the line its three siblings all have, and the one this file shipped without.
|
| 44 |
-
// `SwipeView.css` had ZERO references anywhere in `src/`, so T26's two new sections rendered
|
| 45 |
-
// unstyled while `.cg-swipe-card` (which lives in `index.css`) kept the card looking right β
|
| 46 |
-
// a partially-styled surface reads as a design choice, which is why nobody reported it and no
|
| 47 |
-
// gate could see it: a side-effect import references no symbol ([[artifact-with-no-importer]]).
|
| 48 |
-
import "./SwipeView.css";
|
| 49 |
-
|
| 50 |
-
export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
|
| 51 |
-
|
| 52 |
-
/** The three ways a stored binding can rot that the host cannot see (see the header note). */
|
| 53 |
-
type BindingFault =
|
| 54 |
-
| { kind: "unbound" }
|
| 55 |
-
| { kind: "field-gone"; fieldKey: string }
|
| 56 |
-
| { kind: "not-select"; field: Field }
|
| 57 |
-
| { kind: "option-gone"; field: Field; missing: string[] };
|
| 58 |
-
|
| 59 |
-
function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
|
| 60 |
-
{ ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
|
| 61 |
-
if (!spec) return { ok: false, fault: { kind: "unbound" } };
|
| 62 |
-
const field = fieldByKey.get(spec.fieldKey);
|
| 63 |
-
if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
|
| 64 |
-
// R2 β SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
|
| 65 |
-
// so "write this option" would mean append-or-replace, and a triage gesture that sometimes
|
| 66 |
-
// adds and sometimes overwrites is two gestures wearing one button.
|
| 67 |
-
if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
|
| 68 |
-
const options = choiceOptions(field);
|
| 69 |
-
const has = new Set(options.map((o) => o.toLowerCase()));
|
| 70 |
-
const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
|
| 71 |
-
if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
|
| 72 |
-
return { ok: true, field, spec };
|
| 73 |
-
}
|
| 74 |
-
|
| 75 |
-
/** The bound cell is EMPTY β the one predicate that decides deck membership (R2). */
|
| 76 |
-
const isUndecided = (row: Row, key: string): boolean =>
|
| 77 |
-
String(row[key] ?? "").trim() === "";
|
| 78 |
-
|
| 79 |
-
export function SwipeView({
|
| 80 |
-
rows,
|
| 81 |
-
fields,
|
| 82 |
-
fieldByKey,
|
| 83 |
-
spec,
|
| 84 |
-
cardKeys,
|
| 85 |
-
detailKeys,
|
| 86 |
-
scope,
|
| 87 |
-
viewer,
|
| 88 |
-
docs,
|
| 89 |
-
docPayload,
|
| 90 |
-
onDocAdd,
|
| 91 |
-
onDocFetch,
|
| 92 |
-
onDocDelete,
|
| 93 |
-
titleKey,
|
| 94 |
-
canWrite,
|
| 95 |
-
readOnlyReason,
|
| 96 |
-
canBind,
|
| 97 |
-
onSpec,
|
| 98 |
-
onSwipe,
|
| 99 |
-
onOpen,
|
| 100 |
-
}: {
|
| 101 |
-
/** DISTINCT data rows from the full pipeline, overlay edits layered β the kanban's contract.
|
| 102 |
-
* The deck re-derives from these, so a written record leaves it as soon as the optimistic
|
| 103 |
-
* patch lands; there is no local cursor to drift out of step with the data. */
|
| 104 |
-
rows: Row[];
|
| 105 |
-
/** Every field, for the picker's field list. */
|
| 106 |
-
fields: Field[];
|
| 107 |
-
fieldByKey: Map<string, Field>;
|
| 108 |
-
/** The stored binding, or undefined for a deck nobody has configured yet. */
|
| 109 |
-
spec: SwipeSpec | undefined;
|
| 110 |
-
/** The handful of visible fields the card lists under its title. */
|
| 111 |
-
cardKeys: string[];
|
| 112 |
-
titleKey: string;
|
| 113 |
-
/** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
|
| 114 |
-
canWrite: boolean;
|
| 115 |
-
/** Stated when the deck cannot be decided β permissions, or a computed column. */
|
| 116 |
-
readOnlyReason: string | null;
|
| 117 |
-
/** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
|
| 118 |
-
* view-editing permission and NOT `canWrite` β conflating the two is
|
| 119 |
-
* [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
|
| 120 |
-
* nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
|
| 121 |
-
canBind: boolean;
|
| 122 |
-
/** `undefined` DELETES the binding β absent is the honest unconfigured state, and storing a
|
| 123 |
-
* half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
|
| 124 |
-
onSpec: (next: SwipeSpec | undefined) => void;
|
| 125 |
-
onSwipe: (pid: number, value: string) => void;
|
| 126 |
-
onOpen: (pid: number) => void;
|
| 127 |
-
/**
|
| 128 |
-
* ββ WAVE-29 T26 (owner R9) β WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.
|
| 129 |
-
*
|
| 130 |
-
* R9: *"the swipe CARD itself renders the record detail inline β fields, comments and
|
| 131 |
-
* attachments β so a reviewer decides without leaving the deck."* Everything below is that,
|
| 132 |
-
* and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply
|
| 133 |
-
* different amounts. A card must render with none of them rather than throw β the standalone
|
| 134 |
-
* embed has no `scope`, and a deployment with no document storage serves no handlers.
|
| 135 |
-
*/
|
| 136 |
-
/** Every field the VIEW shows, in its order β not the three-key card summary. */
|
| 137 |
-
detailKeys?: string[];
|
| 138 |
-
/** The surface these records live on. Comments are keyed by it; absent β no comments section,
|
| 139 |
-
* which is the pre-existing precondition `RecordDetail` already carries. */
|
| 140 |
-
scope?: SurfaceScope;
|
| 141 |
-
viewer?: Viewer;
|
| 142 |
-
/** This record's attachments, and the plumbing. Handlers absent β the section is not rendered
|
| 143 |
-
* at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app
|
| 144 |
-
* cannot keep). */
|
| 145 |
-
/** Keyed by pid, because a deck shows many records β `RecordDetail` takes ONE record's list
|
| 146 |
-
* and that shape cannot serve a deck. */
|
| 147 |
-
docs?: Record<string, CustomerDoc[]>;
|
| 148 |
-
docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };
|
| 149 |
-
/** β EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE
|
| 150 |
-
* open record. A deck paints many records at once, so a handler bound to a single pid would
|
| 151 |
-
* attach every reviewer's upload to whichever card happened to be open. */
|
| 152 |
-
onDocAdd?: (
|
| 153 |
-
pid: number,
|
| 154 |
-
file: { name: string; mime: string; size: number; data_b64: string }
|
| 155 |
-
) => void;
|
| 156 |
-
onDocFetch?: (pid: number, docId: string) => void;
|
| 157 |
-
onDocDelete?: (pid: number, docId: string) => void;
|
| 158 |
-
}) {
|
| 159 |
-
// "Later" β session-only, never stored. A deck with no way past a record you cannot decide
|
| 160 |
-
// blocks on that record forever, so this is navigation WITHIN the deck rather than a third
|
| 161 |
-
// gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
|
| 162 |
-
// state rather than quietly shrinking the deck (rule 8b).
|
| 163 |
-
const [later, setLater] = useState<Set<number>>(new Set());
|
| 164 |
-
const deckRef = useRef<HTMLDivElement>(null);
|
| 165 |
-
|
| 166 |
-
const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
|
| 167 |
-
const boundKey = binding.ok ? binding.field.key : null;
|
| 168 |
-
|
| 169 |
-
const undecided = useMemo(
|
| 170 |
-
() => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
|
| 171 |
-
[rows, boundKey]
|
| 172 |
-
);
|
| 173 |
-
const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
|
| 174 |
-
const card = deck[0];
|
| 175 |
-
|
| 176 |
-
// A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β
|
| 177 |
-
// otherwise the disclosed skip count drifts away from what is actually on the deck.
|
| 178 |
-
useEffect(() => {
|
| 179 |
-
setLater((prev) => {
|
| 180 |
-
if (prev.size === 0) return prev;
|
| 181 |
-
const live = new Set(undecided.map((r) => r.pid));
|
| 182 |
-
const next = new Set([...prev].filter((pid) => live.has(pid)));
|
| 183 |
-
return next.size === prev.size ? prev : next;
|
| 184 |
-
});
|
| 185 |
-
}, [undecided]);
|
| 186 |
-
|
| 187 |
-
const decide = useCallback(
|
| 188 |
-
(value: string) => {
|
| 189 |
-
if (!card || !canWrite) return;
|
| 190 |
-
onSwipe(card.pid, value);
|
| 191 |
-
},
|
| 192 |
-
[card, canWrite, onSwipe]
|
| 193 |
-
);
|
| 194 |
-
|
| 195 |
-
// β / β decide, and they are the SAME two actions the buttons are rather than a second code
|
| 196 |
-
// path: the whole point of the mode is that one hand can clear a queue.
|
| 197 |
-
useEffect(() => {
|
| 198 |
-
if (!binding.ok || !canWrite || !card) return;
|
| 199 |
-
const onKey = (e: KeyboardEvent) => {
|
| 200 |
-
if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
|
| 201 |
-
const el = document.activeElement as HTMLElement | null;
|
| 202 |
-
// Never steal an arrow key from a text field or a native control the user is inside.
|
| 203 |
-
if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
|
| 204 |
-
return;
|
| 205 |
-
if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
|
| 206 |
-
e.preventDefault();
|
| 207 |
-
decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
|
| 208 |
-
};
|
| 209 |
-
window.addEventListener("keydown", onKey);
|
| 210 |
-
return () => window.removeEventListener("keydown", onKey);
|
| 211 |
-
}, [binding, canWrite, card, decide]);
|
| 212 |
-
|
| 213 |
-
if (!binding.ok) {
|
| 214 |
-
return (
|
| 215 |
-
<div className="cg-swipe" ref={deckRef}>
|
| 216 |
-
<SwipeBinder
|
| 217 |
-
fault={binding.fault}
|
| 218 |
-
fields={fields}
|
| 219 |
-
fieldByKey={fieldByKey}
|
| 220 |
-
spec={spec}
|
| 221 |
-
canBind={canBind}
|
| 222 |
-
onSpec={onSpec}
|
| 223 |
-
/>
|
| 224 |
-
</div>
|
| 225 |
-
);
|
| 226 |
-
}
|
| 227 |
-
|
| 228 |
-
const { field } = binding;
|
| 229 |
-
const leftTint = optionTint(field, binding.spec.leftOption);
|
| 230 |
-
const rightTint = optionTint(field, binding.spec.rightOption);
|
| 231 |
-
|
| 232 |
-
return (
|
| 233 |
-
<div className="cg-swipe" ref={deckRef} tabIndex={-1}>
|
| 234 |
-
<div className="cg-swipe-bar">
|
| 235 |
-
<span className="cg-swipe-bound">
|
| 236 |
-
<ModeIcon mode="swipe" />
|
| 237 |
-
Sorting into <strong>{field.label}</strong>
|
| 238 |
-
</span>
|
| 239 |
-
<span className="cg-swipe-left">
|
| 240 |
-
{deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
|
| 241 |
-
</span>
|
| 242 |
-
{canBind && (
|
| 243 |
-
<button
|
| 244 |
-
type="button"
|
| 245 |
-
className="cg-link-btn"
|
| 246 |
-
onClick={() => onSpec(undefined)}
|
| 247 |
-
title="Choose a different field or different options for this deck"
|
| 248 |
-
>
|
| 249 |
-
Change
|
| 250 |
-
</button>
|
| 251 |
-
)}
|
| 252 |
-
</div>
|
| 253 |
-
{readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
|
| 254 |
-
{card ? (
|
| 255 |
-
<div className="cg-swipe-deck">
|
| 256 |
-
<button
|
| 257 |
-
type="button"
|
| 258 |
-
className="cg-swipe-side cg-swipe-side--left"
|
| 259 |
-
disabled={!canWrite}
|
| 260 |
-
style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
|
| 261 |
-
onClick={() => decide(binding.spec.leftOption)}
|
| 262 |
-
title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
|
| 263 |
-
>
|
| 264 |
-
<span aria-hidden className="cg-swipe-arrow">
|
| 265 |
-
<svg width="16" height="16" viewBox="0 0 16 16">
|
| 266 |
-
<path
|
| 267 |
-
d="M11 3.2 6.2 8l4.8 4.8"
|
| 268 |
-
fill="none"
|
| 269 |
-
stroke="currentColor"
|
| 270 |
-
strokeWidth="1.6"
|
| 271 |
-
strokeLinecap="round"
|
| 272 |
-
strokeLinejoin="round"
|
| 273 |
-
/>
|
| 274 |
-
</svg>
|
| 275 |
-
</span>
|
| 276 |
-
{binding.spec.leftOption}
|
| 277 |
-
</button>
|
| 278 |
-
<article
|
| 279 |
-
className="cg-swipe-card"
|
| 280 |
-
role="button"
|
| 281 |
-
tabIndex={0}
|
| 282 |
-
onClick={(e) => {
|
| 283 |
-
// β W41-T48 β the card IS the deck's record open, so it folds the rail.
|
| 284 |
-
// β Nothing that is NOT an open can reach this line: every control inside the
|
| 285 |
-
// card (a url cell, the comments box, the document tray) already stops its own
|
| 286 |
-
// click, and the left/right decision buttons are siblings of the card, not
|
| 287 |
-
// children of it. The deck also has no pointer drag to disambiguate β its swipe
|
| 288 |
-
// is the two buttons and the arrow keys, neither of which opens anything.
|
| 289 |
-
// β `<article role="button">`, not a native button, so a keyboard activation
|
| 290 |
-
// never arrives here as a synthetic click; the keydown path below is the whole
|
| 291 |
-
// keyboard story and the two cannot both fire for one gesture.
|
| 292 |
-
if (e.detail <= 1) signal(NAV_MINIMIZE_EVENT);
|
| 293 |
-
onOpen(card.pid);
|
| 294 |
-
}}
|
| 295 |
-
onKeyDown={(e) => {
|
| 296 |
-
if (e.key !== "Enter" && e.key !== " ") return;
|
| 297 |
-
e.preventDefault();
|
| 298 |
-
// W41-T48 β `!e.repeat` is this path's `e.detail <= 1`: a HELD Enter or Space
|
| 299 |
-
// auto-repeats keydown, and every one of those repeats is the SAME gesture.
|
| 300 |
-
if (!e.repeat) signal(NAV_MINIMIZE_EVENT);
|
| 301 |
-
onOpen(card.pid);
|
| 302 |
-
}}
|
| 303 |
-
>
|
| 304 |
-
<h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
|
| 305 |
-
<div className="cg-swipe-cells">
|
| 306 |
-
{/* β WAVE-29 T26 (R9) β the RECORD's visible fields, not the three-key summary the
|
| 307 |
-
kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not
|
| 308 |
-
been widened yet renders exactly what it rendered before. */}
|
| 309 |
-
{(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {
|
| 310 |
-
const f = fieldByKey.get(k);
|
| 311 |
-
if (!f) return null;
|
| 312 |
-
const text = formatDisplay(f, card[k]);
|
| 313 |
-
if (!text) return null;
|
| 314 |
-
// A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
|
| 315 |
-
// scheme guard β and every gesture that reaches it must be stopped from also
|
| 316 |
-
// reaching the card, which is a button (the kanban card's note, same trap).
|
| 317 |
-
const href = actionHref(f, card[k]);
|
| 318 |
-
return (
|
| 319 |
-
<div key={k} className="cg-swipe-cell">
|
| 320 |
-
<span className="cg-lv-k">{f.label}</span>
|
| 321 |
-
{href ? (
|
| 322 |
-
<a
|
| 323 |
-
className="cg-lv-v"
|
| 324 |
-
href={href}
|
| 325 |
-
target="_blank"
|
| 326 |
-
rel="noopener noreferrer"
|
| 327 |
-
title={text}
|
| 328 |
-
onClick={(e) => e.stopPropagation()}
|
| 329 |
-
onKeyDown={(e) => e.stopPropagation()}
|
| 330 |
-
>
|
| 331 |
-
{text}
|
| 332 |
-
</a>
|
| 333 |
-
) : (
|
| 334 |
-
<span className="cg-lv-v">{text}</span>
|
| 335 |
-
)}
|
| 336 |
-
</div>
|
| 337 |
-
);
|
| 338 |
-
})}
|
| 339 |
-
</div>
|
| 340 |
-
{/* β R9's other two thirds. Both stop their own events: the card is a `role="button"`
|
| 341 |
-
that opens the record, and a click on a comment box or an upload control must not
|
| 342 |
-
also open the modal it exists to make unnecessary (the kanban card's link trap,
|
| 343 |
-
one surface over). */}
|
| 344 |
-
{onDocAdd && onDocFetch && onDocDelete && (
|
| 345 |
-
<div
|
| 346 |
-
className="cg-swipe-docs"
|
| 347 |
-
onClick={(e) => e.stopPropagation()}
|
| 348 |
-
onKeyDown={(e) => e.stopPropagation()}
|
| 349 |
-
role="presentation"
|
| 350 |
-
>
|
| 351 |
-
<Documents
|
| 352 |
-
pid={Number(card.pid)}
|
| 353 |
-
docs={docs?.[String(card.pid)] ?? []}
|
| 354 |
-
docPayload={docPayload}
|
| 355 |
-
onAdd={(file) => onDocAdd(card.pid, file)}
|
| 356 |
-
onFetch={(docId) => onDocFetch(card.pid, docId)}
|
| 357 |
-
onDelete={(docId) => onDocDelete(card.pid, docId)}
|
| 358 |
-
/>
|
| 359 |
-
</div>
|
| 360 |
-
)}
|
| 361 |
-
{scope != null && (
|
| 362 |
-
<div
|
| 363 |
-
className="cg-swipe-comments"
|
| 364 |
-
onClick={(e) => e.stopPropagation()}
|
| 365 |
-
onKeyDown={(e) => e.stopPropagation()}
|
| 366 |
-
role="presentation"
|
| 367 |
-
>
|
| 368 |
-
{/* β KEYED ON scope+pid, the same key `RecordDetail` uses: without it React
|
| 369 |
-
reuses the mounted instance across a card change and paints one record's
|
| 370 |
-
comments under another's name until the fetch returns. */}
|
| 371 |
-
<RecordComments
|
| 372 |
-
key={`${scope}:${Number(card.pid)}`}
|
| 373 |
-
scope={scope}
|
| 374 |
-
pid={Number(card.pid)}
|
| 375 |
-
viewer={viewer}
|
| 376 |
-
/>
|
| 377 |
-
</div>
|
| 378 |
-
)}
|
| 379 |
-
{canWrite && (
|
| 380 |
-
<button
|
| 381 |
-
type="button"
|
| 382 |
-
className="cg-link-btn cg-swipe-later"
|
| 383 |
-
onClick={(e) => {
|
| 384 |
-
e.stopPropagation();
|
| 385 |
-
setLater((prev) => new Set(prev).add(card.pid));
|
| 386 |
-
}}
|
| 387 |
-
>
|
| 388 |
-
Decide later
|
| 389 |
-
</button>
|
| 390 |
-
)}
|
| 391 |
-
</article>
|
| 392 |
-
<button
|
| 393 |
-
type="button"
|
| 394 |
-
className="cg-swipe-side cg-swipe-side--right"
|
| 395 |
-
disabled={!canWrite}
|
| 396 |
-
style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
|
| 397 |
-
onClick={() => decide(binding.spec.rightOption)}
|
| 398 |
-
title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
|
| 399 |
-
>
|
| 400 |
-
{binding.spec.rightOption}
|
| 401 |
-
<span aria-hidden className="cg-swipe-arrow">
|
| 402 |
-
<svg width="16" height="16" viewBox="0 0 16 16">
|
| 403 |
-
<path
|
| 404 |
-
d="M5 3.2 9.8 8 5 12.8"
|
| 405 |
-
fill="none"
|
| 406 |
-
stroke="currentColor"
|
| 407 |
-
strokeWidth="1.6"
|
| 408 |
-
strokeLinecap="round"
|
| 409 |
-
strokeLinejoin="round"
|
| 410 |
-
/>
|
| 411 |
-
</svg>
|
| 412 |
-
</span>
|
| 413 |
-
</button>
|
| 414 |
-
</div>
|
| 415 |
-
) : (
|
| 416 |
-
// The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
|
| 417 |
-
// between "the deck is finished" and "the filter hid everything", and the two want
|
| 418 |
-
// different next actions. `later` is disclosed rather than quietly subtracted.
|
| 419 |
-
<div className="cg-mode-empty cg-swipe-empty">
|
| 420 |
-
{later.size > 0 ? (
|
| 421 |
-
<>
|
| 422 |
-
<p>
|
| 423 |
-
{later.size.toLocaleString()}{" "}
|
| 424 |
-
{later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
|
| 425 |
-
in this view is missing a <strong>{field.label}</strong>.
|
| 426 |
-
</p>
|
| 427 |
-
<button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
|
| 428 |
-
Bring them back
|
| 429 |
-
</button>
|
| 430 |
-
</>
|
| 431 |
-
) : (
|
| 432 |
-
<p>
|
| 433 |
-
Every record in this view already has a <strong>{field.label}</strong>. Widen the
|
| 434 |
-
view's filters to sort more.
|
| 435 |
-
</p>
|
| 436 |
-
)}
|
| 437 |
-
</div>
|
| 438 |
-
)}
|
| 439 |
-
</div>
|
| 440 |
-
);
|
| 441 |
-
}
|
| 442 |
-
|
| 443 |
-
/**
|
| 444 |
-
* The binding picker: field + two options. It is also the surface every LOST binding lands on,
|
| 445 |
-
* with the loss stated above it β one place that answers "what is this deck for", rather than an
|
| 446 |
-
* error screen beside a separate setup screen.
|
| 447 |
-
*/
|
| 448 |
-
function SwipeBinder({
|
| 449 |
-
fault,
|
| 450 |
-
fields,
|
| 451 |
-
fieldByKey,
|
| 452 |
-
spec,
|
| 453 |
-
canBind,
|
| 454 |
-
onSpec,
|
| 455 |
-
}: {
|
| 456 |
-
fault: BindingFault;
|
| 457 |
-
fields: Field[];
|
| 458 |
-
fieldByKey: Map<string, Field>;
|
| 459 |
-
spec: SwipeSpec | undefined;
|
| 460 |
-
canBind: boolean;
|
| 461 |
-
onSpec: (next: SwipeSpec | undefined) => void;
|
| 462 |
-
}) {
|
| 463 |
-
const selects = useMemo(
|
| 464 |
-
() => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
|
| 465 |
-
[fields]
|
| 466 |
-
);
|
| 467 |
-
const [fieldKey, setFieldKey] = useState<string>(() => {
|
| 468 |
-
if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
|
| 469 |
-
return selects[0]?.key ?? "";
|
| 470 |
-
});
|
| 471 |
-
const chosen = fieldByKey.get(fieldKey);
|
| 472 |
-
const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
|
| 473 |
-
const [left, setLeft] = useState<string>("");
|
| 474 |
-
const [right, setRight] = useState<string>("");
|
| 475 |
-
|
| 476 |
-
// The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
|
| 477 |
-
// pick survives re-renders, and reset whenever the field changes β carrying an option from the
|
| 478 |
-
// previous field would offer a value the new field cannot hold.
|
| 479 |
-
useEffect(() => {
|
| 480 |
-
setLeft(options[0] ?? "");
|
| 481 |
-
setRight(options.find((o) => o !== options[0]) ?? "");
|
| 482 |
-
}, [options]);
|
| 483 |
-
|
| 484 |
-
const message = ((): string => {
|
| 485 |
-
switch (fault.kind) {
|
| 486 |
-
case "field-gone":
|
| 487 |
-
return "The field this deck sorted into has been deleted. Pick another one.";
|
| 488 |
-
case "not-select":
|
| 489 |
-
return `β${fault.field.label}β is no longer a single-select, so it has no options to`
|
| 490 |
-
+ " sort into. Pick another field.";
|
| 491 |
-
case "option-gone":
|
| 492 |
-
return `${fault.missing.map((m) => `β${m}β`).join(" and ")} ${
|
| 493 |
-
fault.missing.length === 1 ? "is" : "are"
|
| 494 |
-
} no longer ${fault.missing.length === 1 ? "an option" : "options"} on β${
|
| 495 |
-
fault.field.label
|
| 496 |
-
}β. Pick the sides again.`;
|
| 497 |
-
default:
|
| 498 |
-
return "Sort records one at a time into two options of a single-select field.";
|
| 499 |
-
}
|
| 500 |
-
})();
|
| 501 |
-
|
| 502 |
-
if (!canBind) {
|
| 503 |
-
return (
|
| 504 |
-
<div className="cg-mode-empty">
|
| 505 |
-
<p>{message}</p>
|
| 506 |
-
<p>Its creator or an admin can set this view up.</p>
|
| 507 |
-
</div>
|
| 508 |
-
);
|
| 509 |
-
}
|
| 510 |
-
if (selects.length === 0) {
|
| 511 |
-
// Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
|
| 512 |
-
// requirement is what turns a dead end into a next action.
|
| 513 |
-
return (
|
| 514 |
-
<div className="cg-mode-empty">
|
| 515 |
-
<p>
|
| 516 |
-
A swipe deck sorts into a single-select field with at least two options. This database
|
| 517 |
-
does not have one yet β add a single-select column, then come back.
|
| 518 |
-
</p>
|
| 519 |
-
</div>
|
| 520 |
-
);
|
| 521 |
-
}
|
| 522 |
-
const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
|
| 523 |
-
return (
|
| 524 |
-
<div className="cg-swipe-setup">
|
| 525 |
-
<p className="cg-swipe-setup-note">{message}</p>
|
| 526 |
-
<label className="cg-swipe-setup-row">
|
| 527 |
-
<span>Sort into</span>
|
| 528 |
-
<select
|
| 529 |
-
className="cg-select"
|
| 530 |
-
value={fieldKey}
|
| 531 |
-
onChange={(e) => setFieldKey(e.target.value)}
|
| 532 |
-
>
|
| 533 |
-
{/* Every option carries an explicit `value`: a <select> whose value names nothing
|
| 534 |
-
renders its FIRST option and reports a choice the user never made
|
| 535 |
-
([[cg-condition-builder-items]]). */}
|
| 536 |
-
{selects.map((f) => (
|
| 537 |
-
<option key={f.key} value={f.key}>
|
| 538 |
-
{f.label}
|
| 539 |
-
</option>
|
| 540 |
-
))}
|
| 541 |
-
</select>
|
| 542 |
-
</label>
|
| 543 |
-
<div className="cg-swipe-setup-sides">
|
| 544 |
-
<label className="cg-swipe-setup-row">
|
| 545 |
-
<span>Swipe left</span>
|
| 546 |
-
<select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
|
| 547 |
-
{options.map((o) => (
|
| 548 |
-
<option key={o} value={o}>
|
| 549 |
-
{o}
|
| 550 |
-
</option>
|
| 551 |
-
))}
|
| 552 |
-
</select>
|
| 553 |
-
</label>
|
| 554 |
-
<label className="cg-swipe-setup-row">
|
| 555 |
-
<span>Swipe right</span>
|
| 556 |
-
<select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
|
| 557 |
-
{options.map((o) => (
|
| 558 |
-
<option key={o} value={o}>
|
| 559 |
-
{o}
|
| 560 |
-
</option>
|
| 561 |
-
))}
|
| 562 |
-
</select>
|
| 563 |
-
</label>
|
| 564 |
-
</div>
|
| 565 |
-
{!ready && left && right && (
|
| 566 |
-
// Stated, not silently refused: both engines DROP a binding whose sides are the same
|
| 567 |
-
// option, so a Save that looked like it worked would simply not persist.
|
| 568 |
-
<p className="cg-swipe-setup-warn">
|
| 569 |
-
The two sides must be different options β otherwise both gestures do the same thing.
|
| 570 |
-
</p>
|
| 571 |
-
)}
|
| 572 |
-
<button
|
| 573 |
-
type="button"
|
| 574 |
-
className="cg-btn cg-btn--primary"
|
| 575 |
-
disabled={!ready}
|
| 576 |
-
onClick={() =>
|
| 577 |
-
chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
|
| 578 |
-
}
|
| 579 |
-
>
|
| 580 |
-
Start sorting
|
| 581 |
-
</button>
|
| 582 |
-
</div>
|
| 583 |
-
);
|
| 584 |
-
}
|
| 585 |
-
|
| 586 |
-
export default SwipeView;
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// customer-grid / SwipeView.tsx
|
| 3 |
+
// β WAVE-27 item 8 (owner ruling R2, contract C3) β the SWIPE deck.
|
| 4 |
+
//
|
| 5 |
+
// One record at a time, decided left or right into two options of ONE
|
| 6 |
+
// single-select. R2 fixes the shape and it is narrow on purpose:
|
| 7 |
+
// Β· SINGLE-SELECT ONLY, one field, two of its options. No checkbox binding.
|
| 8 |
+
// Β· the deck holds only the records whose bound field is EMPTY β a record
|
| 9 |
+
// that already has a value has been decided, and re-asking is not triage.
|
| 10 |
+
// Β· a swipe writes through the NORMAL cell door (`onSwipe`, which the host
|
| 11 |
+
// maps to the same `patchAndRecord` a kanban card move uses), so undo,
|
| 12 |
+
// echo-suppression and the permission wall all hold without being
|
| 13 |
+
// re-implemented here.
|
| 14 |
+
//
|
| 15 |
+
// Honesty rules carried from the other modes:
|
| 16 |
+
// Β· nothing is silently hidden β the deck states what is left, and the
|
| 17 |
+
// empty state names the bound field rather than saying "all done".
|
| 18 |
+
// Β· a lost binding is SHOWN, never repaired by guessing. `_clean_display`
|
| 19 |
+
// validates that `fieldKey` names a field the table HAS and stops there;
|
| 20 |
+
// it cannot know the field is still a select, or that the two options are
|
| 21 |
+
// still in its vocabulary (its docstring draws that line explicitly). So
|
| 22 |
+
// those three losses land here, and each one says what happened and
|
| 23 |
+
// re-opens the picker β the `viewModes.tsx:190-194` rule, which exists
|
| 24 |
+
// because the wave-7 trap was a picker silently falling back to its first
|
| 25 |
+
// option.
|
| 26 |
+
// ---------------------------------------------------------------------------
|
| 27 |
+
|
| 28 |
+
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
| 29 |
+
// ββ W41-T48 (owner instruction 22) β opening a record from the swipe deck folds the shell's
|
| 30 |
+
// navigation rail exactly as a grid cell click does. Guard rationale: `MapView.tsx:2755`.
|
| 31 |
+
import { NAV_MINIMIZE_EVENT, signal } from "../apiContract";
|
| 32 |
+
import { choiceOptions } from "./types";
|
| 33 |
+
import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
|
| 34 |
+
// β `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
|
| 35 |
+
// loaded here) β the same import `RecordComments` takes for the same prop.
|
| 36 |
+
import type { SurfaceScope } from "./apiBridge";
|
| 37 |
+
import RecordComments from "./RecordComments";
|
| 38 |
+
import { Documents } from "./Documents";
|
| 39 |
+
import { formatDisplay } from "./cells";
|
| 40 |
+
import { actionHref } from "./display";
|
| 41 |
+
import { optionTint } from "./choiceColors";
|
| 42 |
+
import { ModeIcon } from "./icons";
|
| 43 |
+
// β W29-T73 β the line its three siblings all have, and the one this file shipped without.
|
| 44 |
+
// `SwipeView.css` had ZERO references anywhere in `src/`, so T26's two new sections rendered
|
| 45 |
+
// unstyled while `.cg-swipe-card` (which lives in `index.css`) kept the card looking right β
|
| 46 |
+
// a partially-styled surface reads as a design choice, which is why nobody reported it and no
|
| 47 |
+
// gate could see it: a side-effect import references no symbol ([[artifact-with-no-importer]]).
|
| 48 |
+
import "./SwipeView.css";
|
| 49 |
+
|
| 50 |
+
export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
|
| 51 |
+
|
| 52 |
+
/** The three ways a stored binding can rot that the host cannot see (see the header note). */
|
| 53 |
+
type BindingFault =
|
| 54 |
+
| { kind: "unbound" }
|
| 55 |
+
| { kind: "field-gone"; fieldKey: string }
|
| 56 |
+
| { kind: "not-select"; field: Field }
|
| 57 |
+
| { kind: "option-gone"; field: Field; missing: string[] };
|
| 58 |
+
|
| 59 |
+
function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
|
| 60 |
+
{ ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
|
| 61 |
+
if (!spec) return { ok: false, fault: { kind: "unbound" } };
|
| 62 |
+
const field = fieldByKey.get(spec.fieldKey);
|
| 63 |
+
if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
|
| 64 |
+
// R2 β SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
|
| 65 |
+
// so "write this option" would mean append-or-replace, and a triage gesture that sometimes
|
| 66 |
+
// adds and sometimes overwrites is two gestures wearing one button.
|
| 67 |
+
if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
|
| 68 |
+
const options = choiceOptions(field);
|
| 69 |
+
const has = new Set(options.map((o) => o.toLowerCase()));
|
| 70 |
+
const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
|
| 71 |
+
if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
|
| 72 |
+
return { ok: true, field, spec };
|
| 73 |
+
}
|
| 74 |
+
|
| 75 |
+
/** The bound cell is EMPTY β the one predicate that decides deck membership (R2). */
|
| 76 |
+
const isUndecided = (row: Row, key: string): boolean =>
|
| 77 |
+
String(row[key] ?? "").trim() === "";
|
| 78 |
+
|
| 79 |
+
export function SwipeView({
|
| 80 |
+
rows,
|
| 81 |
+
fields,
|
| 82 |
+
fieldByKey,
|
| 83 |
+
spec,
|
| 84 |
+
cardKeys,
|
| 85 |
+
detailKeys,
|
| 86 |
+
scope,
|
| 87 |
+
viewer,
|
| 88 |
+
docs,
|
| 89 |
+
docPayload,
|
| 90 |
+
onDocAdd,
|
| 91 |
+
onDocFetch,
|
| 92 |
+
onDocDelete,
|
| 93 |
+
titleKey,
|
| 94 |
+
canWrite,
|
| 95 |
+
readOnlyReason,
|
| 96 |
+
canBind,
|
| 97 |
+
onSpec,
|
| 98 |
+
onSwipe,
|
| 99 |
+
onOpen,
|
| 100 |
+
}: {
|
| 101 |
+
/** DISTINCT data rows from the full pipeline, overlay edits layered β the kanban's contract.
|
| 102 |
+
* The deck re-derives from these, so a written record leaves it as soon as the optimistic
|
| 103 |
+
* patch lands; there is no local cursor to drift out of step with the data. */
|
| 104 |
+
rows: Row[];
|
| 105 |
+
/** Every field, for the picker's field list. */
|
| 106 |
+
fields: Field[];
|
| 107 |
+
fieldByKey: Map<string, Field>;
|
| 108 |
+
/** The stored binding, or undefined for a deck nobody has configured yet. */
|
| 109 |
+
spec: SwipeSpec | undefined;
|
| 110 |
+
/** The handful of visible fields the card lists under its title. */
|
| 111 |
+
cardKeys: string[];
|
| 112 |
+
titleKey: string;
|
| 113 |
+
/** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
|
| 114 |
+
canWrite: boolean;
|
| 115 |
+
/** Stated when the deck cannot be decided β permissions, or a computed column. */
|
| 116 |
+
readOnlyReason: string | null;
|
| 117 |
+
/** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
|
| 118 |
+
* view-editing permission and NOT `canWrite` β conflating the two is
|
| 119 |
+
* [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
|
| 120 |
+
* nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
|
| 121 |
+
canBind: boolean;
|
| 122 |
+
/** `undefined` DELETES the binding β absent is the honest unconfigured state, and storing a
|
| 123 |
+
* half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
|
| 124 |
+
onSpec: (next: SwipeSpec | undefined) => void;
|
| 125 |
+
onSwipe: (pid: number, value: string) => void;
|
| 126 |
+
onOpen: (pid: number) => void;
|
| 127 |
+
/**
|
| 128 |
+
* ββ WAVE-29 T26 (owner R9) β WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.
|
| 129 |
+
*
|
| 130 |
+
* R9: *"the swipe CARD itself renders the record detail inline β fields, comments and
|
| 131 |
+
* attachments β so a reviewer decides without leaving the deck."* Everything below is that,
|
| 132 |
+
* and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply
|
| 133 |
+
* different amounts. A card must render with none of them rather than throw β the standalone
|
| 134 |
+
* embed has no `scope`, and a deployment with no document storage serves no handlers.
|
| 135 |
+
*/
|
| 136 |
+
/** Every field the VIEW shows, in its order β not the three-key card summary. */
|
| 137 |
+
detailKeys?: string[];
|
| 138 |
+
/** The surface these records live on. Comments are keyed by it; absent β no comments section,
|
| 139 |
+
* which is the pre-existing precondition `RecordDetail` already carries. */
|
| 140 |
+
scope?: SurfaceScope;
|
| 141 |
+
viewer?: Viewer;
|
| 142 |
+
/** This record's attachments, and the plumbing. Handlers absent β the section is not rendered
|
| 143 |
+
* at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app
|
| 144 |
+
* cannot keep). */
|
| 145 |
+
/** Keyed by pid, because a deck shows many records β `RecordDetail` takes ONE record's list
|
| 146 |
+
* and that shape cannot serve a deck. */
|
| 147 |
+
docs?: Record<string, CustomerDoc[]>;
|
| 148 |
+
docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };
|
| 149 |
+
/** β EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE
|
| 150 |
+
* open record. A deck paints many records at once, so a handler bound to a single pid would
|
| 151 |
+
* attach every reviewer's upload to whichever card happened to be open. */
|
| 152 |
+
onDocAdd?: (
|
| 153 |
+
pid: number,
|
| 154 |
+
file: { name: string; mime: string; size: number; data_b64: string }
|
| 155 |
+
) => void;
|
| 156 |
+
onDocFetch?: (pid: number, docId: string) => void;
|
| 157 |
+
onDocDelete?: (pid: number, docId: string) => void;
|
| 158 |
+
}) {
|
| 159 |
+
// "Later" β session-only, never stored. A deck with no way past a record you cannot decide
|
| 160 |
+
// blocks on that record forever, so this is navigation WITHIN the deck rather than a third
|
| 161 |
+
// gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
|
| 162 |
+
// state rather than quietly shrinking the deck (rule 8b).
|
| 163 |
+
const [later, setLater] = useState<Set<number>>(new Set());
|
| 164 |
+
const deckRef = useRef<HTMLDivElement>(null);
|
| 165 |
+
|
| 166 |
+
const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
|
| 167 |
+
const boundKey = binding.ok ? binding.field.key : null;
|
| 168 |
+
|
| 169 |
+
const undecided = useMemo(
|
| 170 |
+
() => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
|
| 171 |
+
[rows, boundKey]
|
| 172 |
+
);
|
| 173 |
+
const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
|
| 174 |
+
const card = deck[0];
|
| 175 |
+
|
| 176 |
+
// A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β
|
| 177 |
+
// otherwise the disclosed skip count drifts away from what is actually on the deck.
|
| 178 |
+
useEffect(() => {
|
| 179 |
+
setLater((prev) => {
|
| 180 |
+
if (prev.size === 0) return prev;
|
| 181 |
+
const live = new Set(undecided.map((r) => r.pid));
|
| 182 |
+
const next = new Set([...prev].filter((pid) => live.has(pid)));
|
| 183 |
+
return next.size === prev.size ? prev : next;
|
| 184 |
+
});
|
| 185 |
+
}, [undecided]);
|
| 186 |
+
|
| 187 |
+
const decide = useCallback(
|
| 188 |
+
(value: string) => {
|
| 189 |
+
if (!card || !canWrite) return;
|
| 190 |
+
onSwipe(card.pid, value);
|
| 191 |
+
},
|
| 192 |
+
[card, canWrite, onSwipe]
|
| 193 |
+
);
|
| 194 |
+
|
| 195 |
+
// β / β decide, and they are the SAME two actions the buttons are rather than a second code
|
| 196 |
+
// path: the whole point of the mode is that one hand can clear a queue.
|
| 197 |
+
useEffect(() => {
|
| 198 |
+
if (!binding.ok || !canWrite || !card) return;
|
| 199 |
+
const onKey = (e: KeyboardEvent) => {
|
| 200 |
+
if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
|
| 201 |
+
const el = document.activeElement as HTMLElement | null;
|
| 202 |
+
// Never steal an arrow key from a text field or a native control the user is inside.
|
| 203 |
+
if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
|
| 204 |
+
return;
|
| 205 |
+
if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
|
| 206 |
+
e.preventDefault();
|
| 207 |
+
decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
|
| 208 |
+
};
|
| 209 |
+
window.addEventListener("keydown", onKey);
|
| 210 |
+
return () => window.removeEventListener("keydown", onKey);
|
| 211 |
+
}, [binding, canWrite, card, decide]);
|
| 212 |
+
|
| 213 |
+
if (!binding.ok) {
|
| 214 |
+
return (
|
| 215 |
+
<div className="cg-swipe" ref={deckRef}>
|
| 216 |
+
<SwipeBinder
|
| 217 |
+
fault={binding.fault}
|
| 218 |
+
fields={fields}
|
| 219 |
+
fieldByKey={fieldByKey}
|
| 220 |
+
spec={spec}
|
| 221 |
+
canBind={canBind}
|
| 222 |
+
onSpec={onSpec}
|
| 223 |
+
/>
|
| 224 |
+
</div>
|
| 225 |
+
);
|
| 226 |
+
}
|
| 227 |
+
|
| 228 |
+
const { field } = binding;
|
| 229 |
+
const leftTint = optionTint(field, binding.spec.leftOption);
|
| 230 |
+
const rightTint = optionTint(field, binding.spec.rightOption);
|
| 231 |
+
|
| 232 |
+
return (
|
| 233 |
+
<div className="cg-swipe" ref={deckRef} tabIndex={-1}>
|
| 234 |
+
<div className="cg-swipe-bar">
|
| 235 |
+
<span className="cg-swipe-bound">
|
| 236 |
+
<ModeIcon mode="swipe" />
|
| 237 |
+
Sorting into <strong>{field.label}</strong>
|
| 238 |
+
</span>
|
| 239 |
+
<span className="cg-swipe-left">
|
| 240 |
+
{deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
|
| 241 |
+
</span>
|
| 242 |
+
{canBind && (
|
| 243 |
+
<button
|
| 244 |
+
type="button"
|
| 245 |
+
className="cg-link-btn"
|
| 246 |
+
onClick={() => onSpec(undefined)}
|
| 247 |
+
title="Choose a different field or different options for this deck"
|
| 248 |
+
>
|
| 249 |
+
Change
|
| 250 |
+
</button>
|
| 251 |
+
)}
|
| 252 |
+
</div>
|
| 253 |
+
{readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
|
| 254 |
+
{card ? (
|
| 255 |
+
<div className="cg-swipe-deck">
|
| 256 |
+
<button
|
| 257 |
+
type="button"
|
| 258 |
+
className="cg-swipe-side cg-swipe-side--left"
|
| 259 |
+
disabled={!canWrite}
|
| 260 |
+
style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
|
| 261 |
+
onClick={() => decide(binding.spec.leftOption)}
|
| 262 |
+
title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
|
| 263 |
+
>
|
| 264 |
+
<span aria-hidden className="cg-swipe-arrow">
|
| 265 |
+
<svg width="16" height="16" viewBox="0 0 16 16">
|
| 266 |
+
<path
|
| 267 |
+
d="M11 3.2 6.2 8l4.8 4.8"
|
| 268 |
+
fill="none"
|
| 269 |
+
stroke="currentColor"
|
| 270 |
+
strokeWidth="1.6"
|
| 271 |
+
strokeLinecap="round"
|
| 272 |
+
strokeLinejoin="round"
|
| 273 |
+
/>
|
| 274 |
+
</svg>
|
| 275 |
+
</span>
|
| 276 |
+
{binding.spec.leftOption}
|
| 277 |
+
</button>
|
| 278 |
+
<article
|
| 279 |
+
className="cg-swipe-card"
|
| 280 |
+
role="button"
|
| 281 |
+
tabIndex={0}
|
| 282 |
+
onClick={(e) => {
|
| 283 |
+
// β W41-T48 β the card IS the deck's record open, so it folds the rail.
|
| 284 |
+
// β Nothing that is NOT an open can reach this line: every control inside the
|
| 285 |
+
// card (a url cell, the comments box, the document tray) already stops its own
|
| 286 |
+
// click, and the left/right decision buttons are siblings of the card, not
|
| 287 |
+
// children of it. The deck also has no pointer drag to disambiguate β its swipe
|
| 288 |
+
// is the two buttons and the arrow keys, neither of which opens anything.
|
| 289 |
+
// β `<article role="button">`, not a native button, so a keyboard activation
|
| 290 |
+
// never arrives here as a synthetic click; the keydown path below is the whole
|
| 291 |
+
// keyboard story and the two cannot both fire for one gesture.
|
| 292 |
+
if (e.detail <= 1) signal(NAV_MINIMIZE_EVENT);
|
| 293 |
+
onOpen(card.pid);
|
| 294 |
+
}}
|
| 295 |
+
onKeyDown={(e) => {
|
| 296 |
+
if (e.key !== "Enter" && e.key !== " ") return;
|
| 297 |
+
e.preventDefault();
|
| 298 |
+
// W41-T48 β `!e.repeat` is this path's `e.detail <= 1`: a HELD Enter or Space
|
| 299 |
+
// auto-repeats keydown, and every one of those repeats is the SAME gesture.
|
| 300 |
+
if (!e.repeat) signal(NAV_MINIMIZE_EVENT);
|
| 301 |
+
onOpen(card.pid);
|
| 302 |
+
}}
|
| 303 |
+
>
|
| 304 |
+
<h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
|
| 305 |
+
<div className="cg-swipe-cells">
|
| 306 |
+
{/* β WAVE-29 T26 (R9) β the RECORD's visible fields, not the three-key summary the
|
| 307 |
+
kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not
|
| 308 |
+
been widened yet renders exactly what it rendered before. */}
|
| 309 |
+
{(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {
|
| 310 |
+
const f = fieldByKey.get(k);
|
| 311 |
+
if (!f) return null;
|
| 312 |
+
const text = formatDisplay(f, card[k]);
|
| 313 |
+
if (!text) return null;
|
| 314 |
+
// A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
|
| 315 |
+
// scheme guard β and every gesture that reaches it must be stopped from also
|
| 316 |
+
// reaching the card, which is a button (the kanban card's note, same trap).
|
| 317 |
+
const href = actionHref(f, card[k]);
|
| 318 |
+
return (
|
| 319 |
+
<div key={k} className="cg-swipe-cell">
|
| 320 |
+
<span className="cg-lv-k">{f.label}</span>
|
| 321 |
+
{href ? (
|
| 322 |
+
<a
|
| 323 |
+
className="cg-lv-v"
|
| 324 |
+
href={href}
|
| 325 |
+
target="_blank"
|
| 326 |
+
rel="noopener noreferrer"
|
| 327 |
+
title={text}
|
| 328 |
+
onClick={(e) => e.stopPropagation()}
|
| 329 |
+
onKeyDown={(e) => e.stopPropagation()}
|
| 330 |
+
>
|
| 331 |
+
{text}
|
| 332 |
+
</a>
|
| 333 |
+
) : (
|
| 334 |
+
<span className="cg-lv-v">{text}</span>
|
| 335 |
+
)}
|
| 336 |
+
</div>
|
| 337 |
+
);
|
| 338 |
+
})}
|
| 339 |
+
</div>
|
| 340 |
+
{/* β R9's other two thirds. Both stop their own events: the card is a `role="button"`
|
| 341 |
+
that opens the record, and a click on a comment box or an upload control must not
|
| 342 |
+
also open the modal it exists to make unnecessary (the kanban card's link trap,
|
| 343 |
+
one surface over). */}
|
| 344 |
+
{onDocAdd && onDocFetch && onDocDelete && (
|
| 345 |
+
<div
|
| 346 |
+
className="cg-swipe-docs"
|
| 347 |
+
onClick={(e) => e.stopPropagation()}
|
| 348 |
+
onKeyDown={(e) => e.stopPropagation()}
|
| 349 |
+
role="presentation"
|
| 350 |
+
>
|
| 351 |
+
<Documents
|
| 352 |
+
pid={Number(card.pid)}
|
| 353 |
+
docs={docs?.[String(card.pid)] ?? []}
|
| 354 |
+
docPayload={docPayload}
|
| 355 |
+
onAdd={(file) => onDocAdd(card.pid, file)}
|
| 356 |
+
onFetch={(docId) => onDocFetch(card.pid, docId)}
|
| 357 |
+
onDelete={(docId) => onDocDelete(card.pid, docId)}
|
| 358 |
+
/>
|
| 359 |
+
</div>
|
| 360 |
+
)}
|
| 361 |
+
{scope != null && (
|
| 362 |
+
<div
|
| 363 |
+
className="cg-swipe-comments"
|
| 364 |
+
onClick={(e) => e.stopPropagation()}
|
| 365 |
+
onKeyDown={(e) => e.stopPropagation()}
|
| 366 |
+
role="presentation"
|
| 367 |
+
>
|
| 368 |
+
{/* β KEYED ON scope+pid, the same key `RecordDetail` uses: without it React
|
| 369 |
+
reuses the mounted instance across a card change and paints one record's
|
| 370 |
+
comments under another's name until the fetch returns. */}
|
| 371 |
+
<RecordComments
|
| 372 |
+
key={`${scope}:${Number(card.pid)}`}
|
| 373 |
+
scope={scope}
|
| 374 |
+
pid={Number(card.pid)}
|
| 375 |
+
viewer={viewer}
|
| 376 |
+
/>
|
| 377 |
+
</div>
|
| 378 |
+
)}
|
| 379 |
+
{canWrite && (
|
| 380 |
+
<button
|
| 381 |
+
type="button"
|
| 382 |
+
className="cg-link-btn cg-swipe-later"
|
| 383 |
+
onClick={(e) => {
|
| 384 |
+
e.stopPropagation();
|
| 385 |
+
setLater((prev) => new Set(prev).add(card.pid));
|
| 386 |
+
}}
|
| 387 |
+
>
|
| 388 |
+
Decide later
|
| 389 |
+
</button>
|
| 390 |
+
)}
|
| 391 |
+
</article>
|
| 392 |
+
<button
|
| 393 |
+
type="button"
|
| 394 |
+
className="cg-swipe-side cg-swipe-side--right"
|
| 395 |
+
disabled={!canWrite}
|
| 396 |
+
style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
|
| 397 |
+
onClick={() => decide(binding.spec.rightOption)}
|
| 398 |
+
title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
|
| 399 |
+
>
|
| 400 |
+
{binding.spec.rightOption}
|
| 401 |
+
<span aria-hidden className="cg-swipe-arrow">
|
| 402 |
+
<svg width="16" height="16" viewBox="0 0 16 16">
|
| 403 |
+
<path
|
| 404 |
+
d="M5 3.2 9.8 8 5 12.8"
|
| 405 |
+
fill="none"
|
| 406 |
+
stroke="currentColor"
|
| 407 |
+
strokeWidth="1.6"
|
| 408 |
+
strokeLinecap="round"
|
| 409 |
+
strokeLinejoin="round"
|
| 410 |
+
/>
|
| 411 |
+
</svg>
|
| 412 |
+
</span>
|
| 413 |
+
</button>
|
| 414 |
+
</div>
|
| 415 |
+
) : (
|
| 416 |
+
// The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
|
| 417 |
+
// between "the deck is finished" and "the filter hid everything", and the two want
|
| 418 |
+
// different next actions. `later` is disclosed rather than quietly subtracted.
|
| 419 |
+
<div className="cg-mode-empty cg-swipe-empty">
|
| 420 |
+
{later.size > 0 ? (
|
| 421 |
+
<>
|
| 422 |
+
<p>
|
| 423 |
+
{later.size.toLocaleString()}{" "}
|
| 424 |
+
{later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
|
| 425 |
+
in this view is missing a <strong>{field.label}</strong>.
|
| 426 |
+
</p>
|
| 427 |
+
<button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
|
| 428 |
+
Bring them back
|
| 429 |
+
</button>
|
| 430 |
+
</>
|
| 431 |
+
) : (
|
| 432 |
+
<p>
|
| 433 |
+
Every record in this view already has a <strong>{field.label}</strong>. Widen the
|
| 434 |
+
view's filters to sort more.
|
| 435 |
+
</p>
|
| 436 |
+
)}
|
| 437 |
+
</div>
|
| 438 |
+
)}
|
| 439 |
+
</div>
|
| 440 |
+
);
|
| 441 |
+
}
|
| 442 |
+
|
| 443 |
+
/**
|
| 444 |
+
* The binding picker: field + two options. It is also the surface every LOST binding lands on,
|
| 445 |
+
* with the loss stated above it β one place that answers "what is this deck for", rather than an
|
| 446 |
+
* error screen beside a separate setup screen.
|
| 447 |
+
*/
|
| 448 |
+
function SwipeBinder({
|
| 449 |
+
fault,
|
| 450 |
+
fields,
|
| 451 |
+
fieldByKey,
|
| 452 |
+
spec,
|
| 453 |
+
canBind,
|
| 454 |
+
onSpec,
|
| 455 |
+
}: {
|
| 456 |
+
fault: BindingFault;
|
| 457 |
+
fields: Field[];
|
| 458 |
+
fieldByKey: Map<string, Field>;
|
| 459 |
+
spec: SwipeSpec | undefined;
|
| 460 |
+
canBind: boolean;
|
| 461 |
+
onSpec: (next: SwipeSpec | undefined) => void;
|
| 462 |
+
}) {
|
| 463 |
+
const selects = useMemo(
|
| 464 |
+
() => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
|
| 465 |
+
[fields]
|
| 466 |
+
);
|
| 467 |
+
const [fieldKey, setFieldKey] = useState<string>(() => {
|
| 468 |
+
if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
|
| 469 |
+
return selects[0]?.key ?? "";
|
| 470 |
+
});
|
| 471 |
+
const chosen = fieldByKey.get(fieldKey);
|
| 472 |
+
const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
|
| 473 |
+
const [left, setLeft] = useState<string>("");
|
| 474 |
+
const [right, setRight] = useState<string>("");
|
| 475 |
+
|
| 476 |
+
// The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
|
| 477 |
+
// pick survives re-renders, and reset whenever the field changes β carrying an option from the
|
| 478 |
+
// previous field would offer a value the new field cannot hold.
|
| 479 |
+
useEffect(() => {
|
| 480 |
+
setLeft(options[0] ?? "");
|
| 481 |
+
setRight(options.find((o) => o !== options[0]) ?? "");
|
| 482 |
+
}, [options]);
|
| 483 |
+
|
| 484 |
+
const message = ((): string => {
|
| 485 |
+
switch (fault.kind) {
|
| 486 |
+
case "field-gone":
|
| 487 |
+
return "The field this deck sorted into has been deleted. Pick another one.";
|
| 488 |
+
case "not-select":
|
| 489 |
+
return `β${fault.field.label}β is no longer a single-select, so it has no options to`
|
| 490 |
+
+ " sort into. Pick another field.";
|
| 491 |
+
case "option-gone":
|
| 492 |
+
return `${fault.missing.map((m) => `β${m}β`).join(" and ")} ${
|
| 493 |
+
fault.missing.length === 1 ? "is" : "are"
|
| 494 |
+
} no longer ${fault.missing.length === 1 ? "an option" : "options"} on β${
|
| 495 |
+
fault.field.label
|
| 496 |
+
}β. Pick the sides again.`;
|
| 497 |
+
default:
|
| 498 |
+
return "Sort records one at a time into two options of a single-select field.";
|
| 499 |
+
}
|
| 500 |
+
})();
|
| 501 |
+
|
| 502 |
+
if (!canBind) {
|
| 503 |
+
return (
|
| 504 |
+
<div className="cg-mode-empty">
|
| 505 |
+
<p>{message}</p>
|
| 506 |
+
<p>Its creator or an admin can set this view up.</p>
|
| 507 |
+
</div>
|
| 508 |
+
);
|
| 509 |
+
}
|
| 510 |
+
if (selects.length === 0) {
|
| 511 |
+
// Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
|
| 512 |
+
// requirement is what turns a dead end into a next action.
|
| 513 |
+
return (
|
| 514 |
+
<div className="cg-mode-empty">
|
| 515 |
+
<p>
|
| 516 |
+
A swipe deck sorts into a single-select field with at least two options. This database
|
| 517 |
+
does not have one yet β add a single-select column, then come back.
|
| 518 |
+
</p>
|
| 519 |
+
</div>
|
| 520 |
+
);
|
| 521 |
+
}
|
| 522 |
+
const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
|
| 523 |
+
return (
|
| 524 |
+
<div className="cg-swipe-setup">
|
| 525 |
+
<p className="cg-swipe-setup-note">{message}</p>
|
| 526 |
+
<label className="cg-swipe-setup-row">
|
| 527 |
+
<span>Sort into</span>
|
| 528 |
+
<select
|
| 529 |
+
className="cg-select"
|
| 530 |
+
value={fieldKey}
|
| 531 |
+
onChange={(e) => setFieldKey(e.target.value)}
|
| 532 |
+
>
|
| 533 |
+
{/* Every option carries an explicit `value`: a <select> whose value names nothing
|
| 534 |
+
renders its FIRST option and reports a choice the user never made
|
| 535 |
+
([[cg-condition-builder-items]]). */}
|
| 536 |
+
{selects.map((f) => (
|
| 537 |
+
<option key={f.key} value={f.key}>
|
| 538 |
+
{f.label}
|
| 539 |
+
</option>
|
| 540 |
+
))}
|
| 541 |
+
</select>
|
| 542 |
+
</label>
|
| 543 |
+
<div className="cg-swipe-setup-sides">
|
| 544 |
+
<label className="cg-swipe-setup-row">
|
| 545 |
+
<span>Swipe left</span>
|
| 546 |
+
<select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
|
| 547 |
+
{options.map((o) => (
|
| 548 |
+
<option key={o} value={o}>
|
| 549 |
+
{o}
|
| 550 |
+
</option>
|
| 551 |
+
))}
|
| 552 |
+
</select>
|
| 553 |
+
</label>
|
| 554 |
+
<label className="cg-swipe-setup-row">
|
| 555 |
+
<span>Swipe right</span>
|
| 556 |
+
<select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
|
| 557 |
+
{options.map((o) => (
|
| 558 |
+
<option key={o} value={o}>
|
| 559 |
+
{o}
|
| 560 |
+
</option>
|
| 561 |
+
))}
|
| 562 |
+
</select>
|
| 563 |
+
</label>
|
| 564 |
+
</div>
|
| 565 |
+
{!ready && left && right && (
|
| 566 |
+
// Stated, not silently refused: both engines DROP a binding whose sides are the same
|
| 567 |
+
// option, so a Save that looked like it worked would simply not persist.
|
| 568 |
+
<p className="cg-swipe-setup-warn">
|
| 569 |
+
The two sides must be different options β otherwise both gestures do the same thing.
|
| 570 |
+
</p>
|
| 571 |
+
)}
|
| 572 |
+
<button
|
| 573 |
+
type="button"
|
| 574 |
+
className="cg-btn cg-btn--primary"
|
| 575 |
+
disabled={!ready}
|
| 576 |
+
onClick={() =>
|
| 577 |
+
chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
|
| 578 |
+
}
|
| 579 |
+
>
|
| 580 |
+
Start sorting
|
| 581 |
+
</button>
|
| 582 |
+
</div>
|
| 583 |
+
);
|
| 584 |
+
}
|
| 585 |
+
|
| 586 |
+
export default SwipeView;
|
web/src/customer-grid/chatDock.css
CHANGED
|
@@ -1,48 +1,48 @@
|
|
| 1 |
-
/* customer-grid/chatDock.css β W37-T29 (contract C6 + C8): the chat's DOCK and its LAUNCHER.
|
| 2 |
-
*
|
| 3 |
-
* β A SEPARATE SHEET FROM E's `gridChat.css` ON PURPOSE, and the split is the contract rather
|
| 4 |
-
* than taste. C8 hands `index.css` to lane A alone and tells every other lane to add styles in its
|
| 5 |
-
* own per-surface sheet; E owns how the PANEL looks and this file owns where the HOST puts it and
|
| 6 |
-
* how a person opens it. Two lanes editing one sheet is the collision C8 exists to prevent.
|
| 7 |
-
*
|
| 8 |
-
* ββ THE LAUNCHER IS THE WHOLE REASON THIS FILE EXISTS. A panel with no control that opens it is
|
| 9 |
-
* mounted-but-never-offered, which is this repo's most repeated defect: one wave shipped five whole,
|
| 10 |
-
* correct, unreachable features past every gate. E's sheet cannot carry the launcher, because the
|
| 11 |
-
* launcher is not part of the panel.
|
| 12 |
-
* β Tokens only, never fresh hexes (DESIGN.md: navy #1F4E78 + gold #C8A24B). No emojis, no
|
| 13 |
-
* ALL-CAPS chrome.
|
| 14 |
-
*/
|
| 15 |
-
|
| 16 |
-
/* The dock: a flex child of `.cg-shell`, seated between the views rail and the grid, so the panel
|
| 17 |
-
reads as part of the workspace rather than as an overlay floating on top of it. E's `.cg-chat`
|
| 18 |
-
brings its own width floor, ceiling and left border; this wrapper only owns the seat. */
|
| 19 |
-
.cg-chat-dock {
|
| 20 |
-
display: flex;
|
| 21 |
-
min-height: 0;
|
| 22 |
-
align-self: stretch;
|
| 23 |
-
}
|
| 24 |
-
|
| 25 |
-
/* ββ THE LAUNCHER, MOVED 2026-08-19 ON THE OWNER'S INSTRUCTION.
|
| 26 |
-
It was `.cg-chat-open`: a text pill reading "Ask about this data", floating in the gap between
|
| 27 |
-
the views rail and the grid with a `margin: 8px 0 0 8px`. The owner called it *"ugly as hell"*
|
| 28 |
-
and said where it belongs β *"the same Navigation as the View navigation just beside its
|
| 29 |
-
minimize icon"*. It is now a 26px icon button INSIDE `.cg-views-top`, and these rules match
|
| 30 |
-
`.cg-agent-open` (scriptView.css) exactly, because the two controls sit side by side in one
|
| 31 |
-
26px strip and a launcher that is 2px taller than its neighbour is what reads as bolted on.
|
| 32 |
-
β The old class is GONE rather than left orphaned: a dead rule for a removed node is how a
|
| 33 |
-
later reader concludes the feature still has two entry points. */
|
| 34 |
-
.cg-chat-toggle {
|
| 35 |
-
display: inline-flex;
|
| 36 |
-
align-items: center;
|
| 37 |
-
justify-content: center;
|
| 38 |
-
width: 26px;
|
| 39 |
-
height: 26px;
|
| 40 |
-
border: 0;
|
| 41 |
-
border-radius: 6px;
|
| 42 |
-
background: transparent;
|
| 43 |
-
color: var(--lp-text-muted, #667085);
|
| 44 |
-
cursor: pointer;
|
| 45 |
-
}
|
| 46 |
-
.cg-chat-toggle:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 47 |
-
.cg-chat-toggle.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
|
| 48 |
-
.cg-chat-toggle:focus-visible { outline: 2px solid var(--lp-gold, #c8a24b); outline-offset: 1px; }
|
|
|
|
| 1 |
+
/* customer-grid/chatDock.css β W37-T29 (contract C6 + C8): the chat's DOCK and its LAUNCHER.
|
| 2 |
+
*
|
| 3 |
+
* β A SEPARATE SHEET FROM E's `gridChat.css` ON PURPOSE, and the split is the contract rather
|
| 4 |
+
* than taste. C8 hands `index.css` to lane A alone and tells every other lane to add styles in its
|
| 5 |
+
* own per-surface sheet; E owns how the PANEL looks and this file owns where the HOST puts it and
|
| 6 |
+
* how a person opens it. Two lanes editing one sheet is the collision C8 exists to prevent.
|
| 7 |
+
*
|
| 8 |
+
* ββ THE LAUNCHER IS THE WHOLE REASON THIS FILE EXISTS. A panel with no control that opens it is
|
| 9 |
+
* mounted-but-never-offered, which is this repo's most repeated defect: one wave shipped five whole,
|
| 10 |
+
* correct, unreachable features past every gate. E's sheet cannot carry the launcher, because the
|
| 11 |
+
* launcher is not part of the panel.
|
| 12 |
+
* β Tokens only, never fresh hexes (DESIGN.md: navy #1F4E78 + gold #C8A24B). No emojis, no
|
| 13 |
+
* ALL-CAPS chrome.
|
| 14 |
+
*/
|
| 15 |
+
|
| 16 |
+
/* The dock: a flex child of `.cg-shell`, seated between the views rail and the grid, so the panel
|
| 17 |
+
reads as part of the workspace rather than as an overlay floating on top of it. E's `.cg-chat`
|
| 18 |
+
brings its own width floor, ceiling and left border; this wrapper only owns the seat. */
|
| 19 |
+
.cg-chat-dock {
|
| 20 |
+
display: flex;
|
| 21 |
+
min-height: 0;
|
| 22 |
+
align-self: stretch;
|
| 23 |
+
}
|
| 24 |
+
|
| 25 |
+
/* ββ THE LAUNCHER, MOVED 2026-08-19 ON THE OWNER'S INSTRUCTION.
|
| 26 |
+
It was `.cg-chat-open`: a text pill reading "Ask about this data", floating in the gap between
|
| 27 |
+
the views rail and the grid with a `margin: 8px 0 0 8px`. The owner called it *"ugly as hell"*
|
| 28 |
+
and said where it belongs β *"the same Navigation as the View navigation just beside its
|
| 29 |
+
minimize icon"*. It is now a 26px icon button INSIDE `.cg-views-top`, and these rules match
|
| 30 |
+
`.cg-agent-open` (scriptView.css) exactly, because the two controls sit side by side in one
|
| 31 |
+
26px strip and a launcher that is 2px taller than its neighbour is what reads as bolted on.
|
| 32 |
+
β The old class is GONE rather than left orphaned: a dead rule for a removed node is how a
|
| 33 |
+
later reader concludes the feature still has two entry points. */
|
| 34 |
+
.cg-chat-toggle {
|
| 35 |
+
display: inline-flex;
|
| 36 |
+
align-items: center;
|
| 37 |
+
justify-content: center;
|
| 38 |
+
width: 26px;
|
| 39 |
+
height: 26px;
|
| 40 |
+
border: 0;
|
| 41 |
+
border-radius: 6px;
|
| 42 |
+
background: transparent;
|
| 43 |
+
color: var(--lp-text-muted, #667085);
|
| 44 |
+
cursor: pointer;
|
| 45 |
+
}
|
| 46 |
+
.cg-chat-toggle:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 47 |
+
.cg-chat-toggle.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
|
| 48 |
+
.cg-chat-toggle:focus-visible { outline: 2px solid var(--lp-gold, #c8a24b); outline-offset: 1px; }
|
web/src/customer-grid/gridChat.css
CHANGED
|
@@ -1,294 +1,294 @@
|
|
| 1 |
-
/* customer-grid/gridChat.css β the docked chat panel (W37-T40, contract C8).
|
| 2 |
-
*
|
| 3 |
-
* β MODULE-LOCAL BY CONTRACT, not by preference. C8 hands `index.css` (12k+ lines) to lane A
|
| 4 |
-
* alone this wave, and every other lane adds styles in its own per-surface sheet imported by its
|
| 5 |
-
* own component. The precedent already exists next door in `scriptView.css` and `navExtras.css`.
|
| 6 |
-
* β Colours come from the design tokens (navy #1F4E78 + gold #C8A24B, DESIGN.md), never from fresh
|
| 7 |
-
* hexes: a surface that invents its own palette is the thing the constitution exists to prevent.
|
| 8 |
-
* Only the tokens this file actually uses are named.
|
| 9 |
-
* ββ NO FALLBACK LITERAL INSIDE A `font:` SHORTHAND, and this sheet shipped ten of them before
|
| 10 |
-
* `web_ui` said so (lane A, mailbox A-47). A fallback there is a SECOND SOURCE OF TRUTH for a size
|
| 11 |
-
* that silently becomes THE size the day the token is renamed, and `index.css` always loads, so it
|
| 12 |
-
* can never actually fire. Sizes are therefore `var(--lp-fs-xs)` bare; colours keep their fallback
|
| 13 |
-
* because a missing colour is a legibility failure rather than a silent wrong number.
|
| 14 |
-
* β NO EMOJIS AND NO ALL-CAPS CHROME (DESIGN.md). */
|
| 15 |
-
|
| 16 |
-
.cg-chat {
|
| 17 |
-
display: flex;
|
| 18 |
-
flex-direction: column;
|
| 19 |
-
height: 100%;
|
| 20 |
-
min-height: 0;
|
| 21 |
-
/* β A FLOOR AND A CEILING, NOT A FIXED WIDTH. The host docks this beside a grid whose columns
|
| 22 |
-
are the reason the person is here; a panel that cannot give width back squeezes the thing it
|
| 23 |
-
is talking about. Below the floor the transcript stops being readable, so the floor is real. */
|
| 24 |
-
min-width: 280px;
|
| 25 |
-
max-width: 420px;
|
| 26 |
-
flex: 0 0 340px;
|
| 27 |
-
background: var(--lp-surface, #ffffff);
|
| 28 |
-
border-left: 1px solid var(--lp-border, #e4e7ec);
|
| 29 |
-
}
|
| 30 |
-
|
| 31 |
-
/* Below 1024px a docked panel and a grid cannot both be usable, so the panel takes the surface.
|
| 32 |
-
β It does NOT hide itself: hiding would leave the host's toggle saying "open" with nothing on
|
| 33 |
-
screen, which is a worse failure than a full-width panel the person can close. */
|
| 34 |
-
@media (max-width: 1024px) {
|
| 35 |
-
.cg-chat { flex: 1 1 auto; max-width: none; border-left: 0; }
|
| 36 |
-
}
|
| 37 |
-
|
| 38 |
-
.cg-chat-head {
|
| 39 |
-
display: flex;
|
| 40 |
-
align-items: center;
|
| 41 |
-
gap: 8px;
|
| 42 |
-
padding: 10px 12px;
|
| 43 |
-
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 44 |
-
background: var(--lp-surface, #ffffff);
|
| 45 |
-
}
|
| 46 |
-
|
| 47 |
-
.cg-chat-title {
|
| 48 |
-
font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
|
| 49 |
-
color: var(--lp-text, #1d2939);
|
| 50 |
-
/* The database name can be long and the header is narrow. Truncating beats wrapping into a
|
| 51 |
-
two-line header that shifts the whole panel down. */
|
| 52 |
-
overflow: hidden;
|
| 53 |
-
text-overflow: ellipsis;
|
| 54 |
-
white-space: nowrap;
|
| 55 |
-
flex: 1 1 auto;
|
| 56 |
-
min-width: 0;
|
| 57 |
-
}
|
| 58 |
-
|
| 59 |
-
.cg-chat-close {
|
| 60 |
-
display: inline-flex;
|
| 61 |
-
align-items: center;
|
| 62 |
-
justify-content: center;
|
| 63 |
-
width: 24px;
|
| 64 |
-
height: 24px;
|
| 65 |
-
border: 0;
|
| 66 |
-
border-radius: 6px;
|
| 67 |
-
background: transparent;
|
| 68 |
-
color: var(--lp-text-muted, #667085);
|
| 69 |
-
cursor: pointer;
|
| 70 |
-
}
|
| 71 |
-
.cg-chat-close:hover { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-text, #1d2939); }
|
| 72 |
-
|
| 73 |
-
/* ββ the transcript βββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 74 |
-
|
| 75 |
-
.cg-chat-log {
|
| 76 |
-
display: flex;
|
| 77 |
-
flex-direction: column;
|
| 78 |
-
gap: 10px;
|
| 79 |
-
flex: 1 1 auto;
|
| 80 |
-
min-height: 0;
|
| 81 |
-
overflow-y: auto;
|
| 82 |
-
padding: 14px 12px;
|
| 83 |
-
}
|
| 84 |
-
|
| 85 |
-
.cg-chat-turn { display: flex; flex-direction: column; gap: 6px; }
|
| 86 |
-
|
| 87 |
-
.cg-chat-msg {
|
| 88 |
-
max-width: 92%;
|
| 89 |
-
padding: 8px 10px;
|
| 90 |
-
border-radius: 10px;
|
| 91 |
-
font: 400 var(--lp-fs-xs)/1.55 Inter, system-ui, sans-serif;
|
| 92 |
-
white-space: pre-wrap;
|
| 93 |
-
/* β A pasted column name or an id has no spaces to break on and would otherwise push the panel
|
| 94 |
-
wider than its own max-width. */
|
| 95 |
-
overflow-wrap: anywhere;
|
| 96 |
-
}
|
| 97 |
-
|
| 98 |
-
.cg-chat-msg.is-you {
|
| 99 |
-
align-self: flex-end;
|
| 100 |
-
background: var(--lp-navy, #1f4e78);
|
| 101 |
-
color: #ffffff;
|
| 102 |
-
}
|
| 103 |
-
.cg-chat-msg.is-assistant {
|
| 104 |
-
align-self: flex-start;
|
| 105 |
-
background: var(--lp-surface-sunken, #f2f4f7);
|
| 106 |
-
color: var(--lp-text, #1d2939);
|
| 107 |
-
}
|
| 108 |
-
/* β The panel talking about ITSELF (a write landed, a proposal was declined) is neither side of
|
| 109 |
-
the conversation, so it is centred and quiet rather than dressed as an answer. */
|
| 110 |
-
.cg-chat-msg.is-note {
|
| 111 |
-
align-self: center;
|
| 112 |
-
max-width: 100%;
|
| 113 |
-
background: transparent;
|
| 114 |
-
color: var(--lp-text-muted, #667085);
|
| 115 |
-
font-size: var(--lp-fs-2xs, 11px);
|
| 116 |
-
text-align: center;
|
| 117 |
-
padding: 2px 4px;
|
| 118 |
-
}
|
| 119 |
-
/* β An error is a KIND OF TURN, in the transcript where it can be re-read while the person
|
| 120 |
-
rephrases. Not a toast that has already faded by then. */
|
| 121 |
-
.cg-chat-msg.is-error {
|
| 122 |
-
align-self: flex-start;
|
| 123 |
-
background: #fef3f2;
|
| 124 |
-
color: #b42318;
|
| 125 |
-
border: 1px solid #fecdca;
|
| 126 |
-
}
|
| 127 |
-
|
| 128 |
-
.cg-chat-pending {
|
| 129 |
-
display: flex;
|
| 130 |
-
align-items: center;
|
| 131 |
-
gap: 8px;
|
| 132 |
-
padding: 2px 2px 4px;
|
| 133 |
-
font: 400 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 134 |
-
color: var(--lp-text-muted, #667085);
|
| 135 |
-
}
|
| 136 |
-
|
| 137 |
-
/* ββ the write confirm (R10) ββββββββββββββββββββ
|
| 138 |
-
|
| 139 |
-
.cg-chat-edits {
|
| 140 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 141 |
-
border-radius: 10px;
|
| 142 |
-
background: var(--lp-surface, #ffffff);
|
| 143 |
-
padding: 10px;
|
| 144 |
-
}
|
| 145 |
-
|
| 146 |
-
.cg-chat-edits-head {
|
| 147 |
-
margin: 0 0 8px;
|
| 148 |
-
font: 600 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 149 |
-
color: var(--lp-text, #1d2939);
|
| 150 |
-
}
|
| 151 |
-
|
| 152 |
-
.cg-chat-edits-table {
|
| 153 |
-
width: 100%;
|
| 154 |
-
border-collapse: collapse;
|
| 155 |
-
font: 400 var(--lp-fs-3xs)/1.45 Inter, system-ui, sans-serif;
|
| 156 |
-
/* A proposal can name more cells than fit; it scrolls rather than being clipped, because a
|
| 157 |
-
confirm the person cannot fully read is not a confirm. */
|
| 158 |
-
display: block;
|
| 159 |
-
max-height: 220px;
|
| 160 |
-
overflow: auto;
|
| 161 |
-
}
|
| 162 |
-
.cg-chat-edits-table th {
|
| 163 |
-
text-align: left;
|
| 164 |
-
font-weight: 600;
|
| 165 |
-
color: var(--lp-text-muted, #667085);
|
| 166 |
-
padding: 0 8px 4px 0;
|
| 167 |
-
position: sticky;
|
| 168 |
-
top: 0;
|
| 169 |
-
background: var(--lp-surface, #ffffff);
|
| 170 |
-
}
|
| 171 |
-
.cg-chat-edits-table td {
|
| 172 |
-
padding: 3px 8px 3px 0;
|
| 173 |
-
color: var(--lp-text, #1d2939);
|
| 174 |
-
border-top: 1px solid var(--lp-border, #e4e7ec);
|
| 175 |
-
vertical-align: top;
|
| 176 |
-
overflow-wrap: anywhere;
|
| 177 |
-
}
|
| 178 |
-
/* β The two values are told apart by WEIGHT and colour, never by colour alone: a red/green pair
|
| 179 |
-
is unreadable to a substantial minority of people, and this is a confirm before a write. */
|
| 180 |
-
.cg-chat-before { color: var(--lp-text-muted, #667085); text-decoration: line-through; }
|
| 181 |
-
.cg-chat-after { color: var(--lp-navy, #1f4e78); font-weight: 600; }
|
| 182 |
-
|
| 183 |
-
/* β Centred under the note it belongs to, and quiet: an undo control that shouted would read as
|
| 184 |
-
a warning that something went wrong, when what happened is exactly what the person confirmed. */
|
| 185 |
-
.cg-chat-undo { display: flex; justify-content: center; margin-top: 2px; }
|
| 186 |
-
|
| 187 |
-
.cg-chat-edits-act {
|
| 188 |
-
display: flex;
|
| 189 |
-
justify-content: flex-end;
|
| 190 |
-
gap: 8px;
|
| 191 |
-
margin-top: 10px;
|
| 192 |
-
}
|
| 193 |
-
|
| 194 |
-
.cg-chat-ghost,
|
| 195 |
-
.cg-chat-go {
|
| 196 |
-
border-radius: 7px;
|
| 197 |
-
padding: 5px 12px;
|
| 198 |
-
font: 500 var(--lp-fs-2xs)/1.2 Inter, system-ui, sans-serif;
|
| 199 |
-
cursor: pointer;
|
| 200 |
-
}
|
| 201 |
-
.cg-chat-ghost {
|
| 202 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 203 |
-
background: var(--lp-surface, #ffffff);
|
| 204 |
-
color: var(--lp-text, #1d2939);
|
| 205 |
-
}
|
| 206 |
-
.cg-chat-go {
|
| 207 |
-
border: 1px solid var(--lp-navy, #1f4e78);
|
| 208 |
-
background: var(--lp-navy, #1f4e78);
|
| 209 |
-
color: #ffffff;
|
| 210 |
-
}
|
| 211 |
-
.cg-chat-ghost:disabled,
|
| 212 |
-
.cg-chat-go:disabled { opacity: 0.55; cursor: default; }
|
| 213 |
-
|
| 214 |
-
/* ββ the opening and the composer βββββββββββββββββββββββββββββββββββββββββ */
|
| 215 |
-
|
| 216 |
-
.cg-chat-opening {
|
| 217 |
-
display: flex;
|
| 218 |
-
flex-direction: column;
|
| 219 |
-
justify-content: center;
|
| 220 |
-
flex: 1 1 auto;
|
| 221 |
-
min-height: 0;
|
| 222 |
-
gap: 10px;
|
| 223 |
-
padding: 16px 12px;
|
| 224 |
-
text-align: center;
|
| 225 |
-
}
|
| 226 |
-
|
| 227 |
-
.cg-chat-opening-h {
|
| 228 |
-
margin: 0;
|
| 229 |
-
font: 600 var(--lp-fs-lg)/1.3 Inter, system-ui, sans-serif;
|
| 230 |
-
color: var(--lp-text, #1d2939);
|
| 231 |
-
}
|
| 232 |
-
|
| 233 |
-
.cg-chat-opening-p {
|
| 234 |
-
margin: 0 0 6px;
|
| 235 |
-
font: 400 var(--lp-fs-2xs)/1.55 Inter, system-ui, sans-serif;
|
| 236 |
-
color: var(--lp-text-muted, #667085);
|
| 237 |
-
}
|
| 238 |
-
|
| 239 |
-
.cg-chat-foot { padding: 10px 12px 12px; border-top: 1px solid var(--lp-border, #e4e7ec); }
|
| 240 |
-
|
| 241 |
-
.cg-chat-composer {
|
| 242 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 243 |
-
border-radius: 12px;
|
| 244 |
-
background: var(--lp-surface, #ffffff);
|
| 245 |
-
padding: 8px;
|
| 246 |
-
text-align: left;
|
| 247 |
-
}
|
| 248 |
-
.cg-chat-composer:focus-within { border-color: var(--lp-navy, #1f4e78); }
|
| 249 |
-
|
| 250 |
-
.cg-chat-input {
|
| 251 |
-
width: 100%;
|
| 252 |
-
border: 0;
|
| 253 |
-
outline: 0;
|
| 254 |
-
resize: none;
|
| 255 |
-
background: transparent;
|
| 256 |
-
color: var(--lp-text, #1d2939);
|
| 257 |
-
font: 400 var(--lp-fs-xs)/1.5 Inter, system-ui, sans-serif;
|
| 258 |
-
}
|
| 259 |
-
.cg-chat-input::placeholder { color: var(--lp-text-muted, #667085); }
|
| 260 |
-
.cg-chat-input:disabled { color: var(--lp-text-muted, #667085); }
|
| 261 |
-
|
| 262 |
-
/* β The foot row sits INSIDE the composer's border, which is the shape `cg-agent-composer-foot`
|
| 263 |
-
already established. A second card outline under the input would read as two controls. */
|
| 264 |
-
.cg-chat-composer-foot {
|
| 265 |
-
display: flex;
|
| 266 |
-
align-items: center;
|
| 267 |
-
gap: 8px;
|
| 268 |
-
margin-top: 6px;
|
| 269 |
-
}
|
| 270 |
-
|
| 271 |
-
.cg-chat-scope {
|
| 272 |
-
font: 400 var(--lp-fs-3xs)/1.3 Inter, system-ui, sans-serif;
|
| 273 |
-
color: var(--lp-text-muted, #667085);
|
| 274 |
-
}
|
| 275 |
-
|
| 276 |
-
.cg-chat-spacer { flex: 1 1 auto; }
|
| 277 |
-
|
| 278 |
-
.cg-chat-send {
|
| 279 |
-
display: inline-flex;
|
| 280 |
-
align-items: center;
|
| 281 |
-
justify-content: center;
|
| 282 |
-
width: 26px;
|
| 283 |
-
height: 26px;
|
| 284 |
-
border: 0;
|
| 285 |
-
border-radius: 50%;
|
| 286 |
-
background: var(--lp-navy, #1f4e78);
|
| 287 |
-
color: #ffffff;
|
| 288 |
-
cursor: pointer;
|
| 289 |
-
}
|
| 290 |
-
.cg-chat-send:disabled {
|
| 291 |
-
background: var(--lp-surface-sunken, #f2f4f7);
|
| 292 |
-
color: var(--lp-text-muted, #667085);
|
| 293 |
-
cursor: default;
|
| 294 |
-
}
|
|
|
|
| 1 |
+
/* customer-grid/gridChat.css β the docked chat panel (W37-T40, contract C8).
|
| 2 |
+
*
|
| 3 |
+
* β MODULE-LOCAL BY CONTRACT, not by preference. C8 hands `index.css` (12k+ lines) to lane A
|
| 4 |
+
* alone this wave, and every other lane adds styles in its own per-surface sheet imported by its
|
| 5 |
+
* own component. The precedent already exists next door in `scriptView.css` and `navExtras.css`.
|
| 6 |
+
* β Colours come from the design tokens (navy #1F4E78 + gold #C8A24B, DESIGN.md), never from fresh
|
| 7 |
+
* hexes: a surface that invents its own palette is the thing the constitution exists to prevent.
|
| 8 |
+
* Only the tokens this file actually uses are named.
|
| 9 |
+
* ββ NO FALLBACK LITERAL INSIDE A `font:` SHORTHAND, and this sheet shipped ten of them before
|
| 10 |
+
* `web_ui` said so (lane A, mailbox A-47). A fallback there is a SECOND SOURCE OF TRUTH for a size
|
| 11 |
+
* that silently becomes THE size the day the token is renamed, and `index.css` always loads, so it
|
| 12 |
+
* can never actually fire. Sizes are therefore `var(--lp-fs-xs)` bare; colours keep their fallback
|
| 13 |
+
* because a missing colour is a legibility failure rather than a silent wrong number.
|
| 14 |
+
* β NO EMOJIS AND NO ALL-CAPS CHROME (DESIGN.md). */
|
| 15 |
+
|
| 16 |
+
.cg-chat {
|
| 17 |
+
display: flex;
|
| 18 |
+
flex-direction: column;
|
| 19 |
+
height: 100%;
|
| 20 |
+
min-height: 0;
|
| 21 |
+
/* β A FLOOR AND A CEILING, NOT A FIXED WIDTH. The host docks this beside a grid whose columns
|
| 22 |
+
are the reason the person is here; a panel that cannot give width back squeezes the thing it
|
| 23 |
+
is talking about. Below the floor the transcript stops being readable, so the floor is real. */
|
| 24 |
+
min-width: 280px;
|
| 25 |
+
max-width: 420px;
|
| 26 |
+
flex: 0 0 340px;
|
| 27 |
+
background: var(--lp-surface, #ffffff);
|
| 28 |
+
border-left: 1px solid var(--lp-border, #e4e7ec);
|
| 29 |
+
}
|
| 30 |
+
|
| 31 |
+
/* Below 1024px a docked panel and a grid cannot both be usable, so the panel takes the surface.
|
| 32 |
+
β It does NOT hide itself: hiding would leave the host's toggle saying "open" with nothing on
|
| 33 |
+
screen, which is a worse failure than a full-width panel the person can close. */
|
| 34 |
+
@media (max-width: 1024px) {
|
| 35 |
+
.cg-chat { flex: 1 1 auto; max-width: none; border-left: 0; }
|
| 36 |
+
}
|
| 37 |
+
|
| 38 |
+
.cg-chat-head {
|
| 39 |
+
display: flex;
|
| 40 |
+
align-items: center;
|
| 41 |
+
gap: 8px;
|
| 42 |
+
padding: 10px 12px;
|
| 43 |
+
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 44 |
+
background: var(--lp-surface, #ffffff);
|
| 45 |
+
}
|
| 46 |
+
|
| 47 |
+
.cg-chat-title {
|
| 48 |
+
font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
|
| 49 |
+
color: var(--lp-text, #1d2939);
|
| 50 |
+
/* The database name can be long and the header is narrow. Truncating beats wrapping into a
|
| 51 |
+
two-line header that shifts the whole panel down. */
|
| 52 |
+
overflow: hidden;
|
| 53 |
+
text-overflow: ellipsis;
|
| 54 |
+
white-space: nowrap;
|
| 55 |
+
flex: 1 1 auto;
|
| 56 |
+
min-width: 0;
|
| 57 |
+
}
|
| 58 |
+
|
| 59 |
+
.cg-chat-close {
|
| 60 |
+
display: inline-flex;
|
| 61 |
+
align-items: center;
|
| 62 |
+
justify-content: center;
|
| 63 |
+
width: 24px;
|
| 64 |
+
height: 24px;
|
| 65 |
+
border: 0;
|
| 66 |
+
border-radius: 6px;
|
| 67 |
+
background: transparent;
|
| 68 |
+
color: var(--lp-text-muted, #667085);
|
| 69 |
+
cursor: pointer;
|
| 70 |
+
}
|
| 71 |
+
.cg-chat-close:hover { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-text, #1d2939); }
|
| 72 |
+
|
| 73 |
+
/* ββ the transcript βββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 74 |
+
|
| 75 |
+
.cg-chat-log {
|
| 76 |
+
display: flex;
|
| 77 |
+
flex-direction: column;
|
| 78 |
+
gap: 10px;
|
| 79 |
+
flex: 1 1 auto;
|
| 80 |
+
min-height: 0;
|
| 81 |
+
overflow-y: auto;
|
| 82 |
+
padding: 14px 12px;
|
| 83 |
+
}
|
| 84 |
+
|
| 85 |
+
.cg-chat-turn { display: flex; flex-direction: column; gap: 6px; }
|
| 86 |
+
|
| 87 |
+
.cg-chat-msg {
|
| 88 |
+
max-width: 92%;
|
| 89 |
+
padding: 8px 10px;
|
| 90 |
+
border-radius: 10px;
|
| 91 |
+
font: 400 var(--lp-fs-xs)/1.55 Inter, system-ui, sans-serif;
|
| 92 |
+
white-space: pre-wrap;
|
| 93 |
+
/* β A pasted column name or an id has no spaces to break on and would otherwise push the panel
|
| 94 |
+
wider than its own max-width. */
|
| 95 |
+
overflow-wrap: anywhere;
|
| 96 |
+
}
|
| 97 |
+
|
| 98 |
+
.cg-chat-msg.is-you {
|
| 99 |
+
align-self: flex-end;
|
| 100 |
+
background: var(--lp-navy, #1f4e78);
|
| 101 |
+
color: #ffffff;
|
| 102 |
+
}
|
| 103 |
+
.cg-chat-msg.is-assistant {
|
| 104 |
+
align-self: flex-start;
|
| 105 |
+
background: var(--lp-surface-sunken, #f2f4f7);
|
| 106 |
+
color: var(--lp-text, #1d2939);
|
| 107 |
+
}
|
| 108 |
+
/* β The panel talking about ITSELF (a write landed, a proposal was declined) is neither side of
|
| 109 |
+
the conversation, so it is centred and quiet rather than dressed as an answer. */
|
| 110 |
+
.cg-chat-msg.is-note {
|
| 111 |
+
align-self: center;
|
| 112 |
+
max-width: 100%;
|
| 113 |
+
background: transparent;
|
| 114 |
+
color: var(--lp-text-muted, #667085);
|
| 115 |
+
font-size: var(--lp-fs-2xs, 11px);
|
| 116 |
+
text-align: center;
|
| 117 |
+
padding: 2px 4px;
|
| 118 |
+
}
|
| 119 |
+
/* β An error is a KIND OF TURN, in the transcript where it can be re-read while the person
|
| 120 |
+
rephrases. Not a toast that has already faded by then. */
|
| 121 |
+
.cg-chat-msg.is-error {
|
| 122 |
+
align-self: flex-start;
|
| 123 |
+
background: #fef3f2;
|
| 124 |
+
color: #b42318;
|
| 125 |
+
border: 1px solid #fecdca;
|
| 126 |
+
}
|
| 127 |
+
|
| 128 |
+
.cg-chat-pending {
|
| 129 |
+
display: flex;
|
| 130 |
+
align-items: center;
|
| 131 |
+
gap: 8px;
|
| 132 |
+
padding: 2px 2px 4px;
|
| 133 |
+
font: 400 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 134 |
+
color: var(--lp-text-muted, #667085);
|
| 135 |
+
}
|
| 136 |
+
|
| 137 |
+
/* ββ the write confirm (R10) ββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 138 |
+
|
| 139 |
+
.cg-chat-edits {
|
| 140 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 141 |
+
border-radius: 10px;
|
| 142 |
+
background: var(--lp-surface, #ffffff);
|
| 143 |
+
padding: 10px;
|
| 144 |
+
}
|
| 145 |
+
|
| 146 |
+
.cg-chat-edits-head {
|
| 147 |
+
margin: 0 0 8px;
|
| 148 |
+
font: 600 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 149 |
+
color: var(--lp-text, #1d2939);
|
| 150 |
+
}
|
| 151 |
+
|
| 152 |
+
.cg-chat-edits-table {
|
| 153 |
+
width: 100%;
|
| 154 |
+
border-collapse: collapse;
|
| 155 |
+
font: 400 var(--lp-fs-3xs)/1.45 Inter, system-ui, sans-serif;
|
| 156 |
+
/* A proposal can name more cells than fit; it scrolls rather than being clipped, because a
|
| 157 |
+
confirm the person cannot fully read is not a confirm. */
|
| 158 |
+
display: block;
|
| 159 |
+
max-height: 220px;
|
| 160 |
+
overflow: auto;
|
| 161 |
+
}
|
| 162 |
+
.cg-chat-edits-table th {
|
| 163 |
+
text-align: left;
|
| 164 |
+
font-weight: 600;
|
| 165 |
+
color: var(--lp-text-muted, #667085);
|
| 166 |
+
padding: 0 8px 4px 0;
|
| 167 |
+
position: sticky;
|
| 168 |
+
top: 0;
|
| 169 |
+
background: var(--lp-surface, #ffffff);
|
| 170 |
+
}
|
| 171 |
+
.cg-chat-edits-table td {
|
| 172 |
+
padding: 3px 8px 3px 0;
|
| 173 |
+
color: var(--lp-text, #1d2939);
|
| 174 |
+
border-top: 1px solid var(--lp-border, #e4e7ec);
|
| 175 |
+
vertical-align: top;
|
| 176 |
+
overflow-wrap: anywhere;
|
| 177 |
+
}
|
| 178 |
+
/* β The two values are told apart by WEIGHT and colour, never by colour alone: a red/green pair
|
| 179 |
+
is unreadable to a substantial minority of people, and this is a confirm before a write. */
|
| 180 |
+
.cg-chat-before { color: var(--lp-text-muted, #667085); text-decoration: line-through; }
|
| 181 |
+
.cg-chat-after { color: var(--lp-navy, #1f4e78); font-weight: 600; }
|
| 182 |
+
|
| 183 |
+
/* β Centred under the note it belongs to, and quiet: an undo control that shouted would read as
|
| 184 |
+
a warning that something went wrong, when what happened is exactly what the person confirmed. */
|
| 185 |
+
.cg-chat-undo { display: flex; justify-content: center; margin-top: 2px; }
|
| 186 |
+
|
| 187 |
+
.cg-chat-edits-act {
|
| 188 |
+
display: flex;
|
| 189 |
+
justify-content: flex-end;
|
| 190 |
+
gap: 8px;
|
| 191 |
+
margin-top: 10px;
|
| 192 |
+
}
|
| 193 |
+
|
| 194 |
+
.cg-chat-ghost,
|
| 195 |
+
.cg-chat-go {
|
| 196 |
+
border-radius: 7px;
|
| 197 |
+
padding: 5px 12px;
|
| 198 |
+
font: 500 var(--lp-fs-2xs)/1.2 Inter, system-ui, sans-serif;
|
| 199 |
+
cursor: pointer;
|
| 200 |
+
}
|
| 201 |
+
.cg-chat-ghost {
|
| 202 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 203 |
+
background: var(--lp-surface, #ffffff);
|
| 204 |
+
color: var(--lp-text, #1d2939);
|
| 205 |
+
}
|
| 206 |
+
.cg-chat-go {
|
| 207 |
+
border: 1px solid var(--lp-navy, #1f4e78);
|
| 208 |
+
background: var(--lp-navy, #1f4e78);
|
| 209 |
+
color: #ffffff;
|
| 210 |
+
}
|
| 211 |
+
.cg-chat-ghost:disabled,
|
| 212 |
+
.cg-chat-go:disabled { opacity: 0.55; cursor: default; }
|
| 213 |
+
|
| 214 |
+
/* ββ the opening and the composer βββββββββββββββββββββββββββββββββββββββββ */
|
| 215 |
+
|
| 216 |
+
.cg-chat-opening {
|
| 217 |
+
display: flex;
|
| 218 |
+
flex-direction: column;
|
| 219 |
+
justify-content: center;
|
| 220 |
+
flex: 1 1 auto;
|
| 221 |
+
min-height: 0;
|
| 222 |
+
gap: 10px;
|
| 223 |
+
padding: 16px 12px;
|
| 224 |
+
text-align: center;
|
| 225 |
+
}
|
| 226 |
+
|
| 227 |
+
.cg-chat-opening-h {
|
| 228 |
+
margin: 0;
|
| 229 |
+
font: 600 var(--lp-fs-lg)/1.3 Inter, system-ui, sans-serif;
|
| 230 |
+
color: var(--lp-text, #1d2939);
|
| 231 |
+
}
|
| 232 |
+
|
| 233 |
+
.cg-chat-opening-p {
|
| 234 |
+
margin: 0 0 6px;
|
| 235 |
+
font: 400 var(--lp-fs-2xs)/1.55 Inter, system-ui, sans-serif;
|
| 236 |
+
color: var(--lp-text-muted, #667085);
|
| 237 |
+
}
|
| 238 |
+
|
| 239 |
+
.cg-chat-foot { padding: 10px 12px 12px; border-top: 1px solid var(--lp-border, #e4e7ec); }
|
| 240 |
+
|
| 241 |
+
.cg-chat-composer {
|
| 242 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 243 |
+
border-radius: 12px;
|
| 244 |
+
background: var(--lp-surface, #ffffff);
|
| 245 |
+
padding: 8px;
|
| 246 |
+
text-align: left;
|
| 247 |
+
}
|
| 248 |
+
.cg-chat-composer:focus-within { border-color: var(--lp-navy, #1f4e78); }
|
| 249 |
+
|
| 250 |
+
.cg-chat-input {
|
| 251 |
+
width: 100%;
|
| 252 |
+
border: 0;
|
| 253 |
+
outline: 0;
|
| 254 |
+
resize: none;
|
| 255 |
+
background: transparent;
|
| 256 |
+
color: var(--lp-text, #1d2939);
|
| 257 |
+
font: 400 var(--lp-fs-xs)/1.5 Inter, system-ui, sans-serif;
|
| 258 |
+
}
|
| 259 |
+
.cg-chat-input::placeholder { color: var(--lp-text-muted, #667085); }
|
| 260 |
+
.cg-chat-input:disabled { color: var(--lp-text-muted, #667085); }
|
| 261 |
+
|
| 262 |
+
/* β The foot row sits INSIDE the composer's border, which is the shape `cg-agent-composer-foot`
|
| 263 |
+
already established. A second card outline under the input would read as two controls. */
|
| 264 |
+
.cg-chat-composer-foot {
|
| 265 |
+
display: flex;
|
| 266 |
+
align-items: center;
|
| 267 |
+
gap: 8px;
|
| 268 |
+
margin-top: 6px;
|
| 269 |
+
}
|
| 270 |
+
|
| 271 |
+
.cg-chat-scope {
|
| 272 |
+
font: 400 var(--lp-fs-3xs)/1.3 Inter, system-ui, sans-serif;
|
| 273 |
+
color: var(--lp-text-muted, #667085);
|
| 274 |
+
}
|
| 275 |
+
|
| 276 |
+
.cg-chat-spacer { flex: 1 1 auto; }
|
| 277 |
+
|
| 278 |
+
.cg-chat-send {
|
| 279 |
+
display: inline-flex;
|
| 280 |
+
align-items: center;
|
| 281 |
+
justify-content: center;
|
| 282 |
+
width: 26px;
|
| 283 |
+
height: 26px;
|
| 284 |
+
border: 0;
|
| 285 |
+
border-radius: 50%;
|
| 286 |
+
background: var(--lp-navy, #1f4e78);
|
| 287 |
+
color: #ffffff;
|
| 288 |
+
cursor: pointer;
|
| 289 |
+
}
|
| 290 |
+
.cg-chat-send:disabled {
|
| 291 |
+
background: var(--lp-surface-sunken, #f2f4f7);
|
| 292 |
+
color: var(--lp-text-muted, #667085);
|
| 293 |
+
cursor: default;
|
| 294 |
+
}
|
web/src/customer-grid/gridChat.ts
CHANGED
|
@@ -1,461 +1,461 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// customer-grid / gridChat.ts β the chat panel's state, as pure functions (W37-T40, R2, C6).
|
| 3 |
-
//
|
| 4 |
-
// ββ WHY THE STATE LIVES HERE AND NOT IN THE COMPONENT. `<GridChat>` has to demonstrate three
|
| 5 |
-
// things its `done-when` names: a message history, an in-flight state and an error state. If those
|
| 6 |
-
// transitions live in `useState` callbacks inside the .tsx, the only way to assert on them is to
|
| 7 |
-
// render React and match emitted markup β which pins the compiler's output rather than the
|
| 8 |
-
// behaviour, and goes red on a refactor that changed nothing a person can see. Here they are plain
|
| 9 |
-
// functions over a plain object, so the gate checks the STATE MACHINE without React in the process
|
| 10 |
-
// at all, and the render only has to prove the three states paint.
|
| 11 |
-
//
|
| 12 |
-
// ββ NOTHING IN THIS FILE TALKS TO THE NETWORK, THE GRID, OR THE STORE β contract C6, and it is
|
| 13 |
-
// structural rather than a promise. There is no `fetch` here and no import of anything that has
|
| 14 |
-
// one: every action the chat can take arrives as a callback the host supplies. That is what lets
|
| 15 |
-
// the host WALL the chat by simply not passing a power, instead of the chat asking permission and
|
| 16 |
-
// being told no [[permitted-is-not-answerable]].
|
| 17 |
-
//
|
| 18 |
-
// β NO EM DASH OR EN DASH IN ANY STRING THAT REACHES A SCREEN (standing rule 2). The sentences
|
| 19 |
-
// below are user-facing copy, and `web_prose` cannot see a wrapped JSX sentence, so the discipline
|
| 20 |
-
// is on the author. Commas, colons and full stops carry the same weight and are not AI slop.
|
| 21 |
-
// ---------------------------------------------------------------------------
|
| 22 |
-
|
| 23 |
-
/** One column the chat is allowed to know about. The host decides what goes in this list. */
|
| 24 |
-
export interface GridChatField {
|
| 25 |
-
key: string;
|
| 26 |
-
label: string;
|
| 27 |
-
type: string;
|
| 28 |
-
}
|
| 29 |
-
|
| 30 |
-
/**
|
| 31 |
-
* What a host callback hands back for a question.
|
| 32 |
-
*
|
| 33 |
-
* β `text` IS REQUIRED AND `unanswerable` IS THE HONEST OUT. D-339's lesson is that an agent
|
| 34 |
-
* which cannot read the database answers from words alone and invents a number; a host that cannot
|
| 35 |
-
* answer must be able to SAY so rather than return an empty string the panel renders as silence.
|
| 36 |
-
*/
|
| 37 |
-
export interface GridChatAnswer {
|
| 38 |
-
text: string;
|
| 39 |
-
/** Set when the question named something this database does not have. Rendered as an answer,
|
| 40 |
-
* not as a failure: the person asked a reasonable question about the wrong column. */
|
| 41 |
-
unanswerable?: boolean;
|
| 42 |
-
/**
|
| 43 |
-
* ββ R10's PROPOSAL CHANNEL, DECLARED RATHER THAN CAST. The panel reads this to decide that an
|
| 44 |
-
* answer is a proposed WRITE and must be shown for confirmation instead of rendered as prose.
|
| 45 |
-
*
|
| 46 |
-
* β IT WAS A CAST FIRST, AND THAT WAS THE BUG-IN-WAITING. `GridChat` read
|
| 47 |
-
* `(answer as {edits?: ...}).edits` while this interface said nothing about it, so the contract
|
| 48 |
-
* lived in one file and the reader in another. The host reads the PUBLISHED type; a host that
|
| 49 |
-
* never sees `edits` never sends `edits`, the whole confirm path is dead on arrival, and nothing
|
| 50 |
-
* anywhere fails [[flag-shipped-without-its-writer]]. Typing it is the difference between a
|
| 51 |
-
* channel and a coincidence.
|
| 52 |
-
* β Its presence is a PROPOSAL, never an instruction: nothing is written until the person
|
| 53 |
-
* confirms, and a caller with `canEdit:false` is not shown the control at all.
|
| 54 |
-
*/
|
| 55 |
-
edits?: GridChatEdit[];
|
| 56 |
-
/**
|
| 57 |
-
* ββ W37-T44's GENERATION CHANNEL. The host authored a Custom View's code; the panel RUNS it
|
| 58 |
-
* through `onRunScript` and reports what happened.
|
| 59 |
-
*
|
| 60 |
-
* β DECLARED, NOT INFERRED, FOR THE SAME REASON `edits` IS. A channel the reader consumes and
|
| 61 |
-
* the published type does not mention is a channel the host never fills, and nothing anywhere
|
| 62 |
-
* fails [[flag-shipped-without-its-writer]] β which is exactly what a `void`ed callback and a
|
| 63 |
-
* confident `observed:` line looked like in the first draft of this ticket.
|
| 64 |
-
* β AUTHORING IS THE HOST'S, RUNNING IS THE PANEL'S. That split is what keeps the sandbox
|
| 65 |
-
* un-widened: the code goes through the ordinary run door a hand-typed script uses.
|
| 66 |
-
*/
|
| 67 |
-
script?: string;
|
| 68 |
-
}
|
| 69 |
-
|
| 70 |
-
/** The outcome of running a Custom View's code. `error` is a sentence, never a stack trace. */
|
| 71 |
-
export interface GridChatRunResult {
|
| 72 |
-
ok: boolean;
|
| 73 |
-
error?: string;
|
| 74 |
-
}
|
| 75 |
-
|
| 76 |
-
/** One cell the chat proposes to write. R10: the person sees `before` and `after` before anything. */
|
| 77 |
-
export interface GridChatEdit {
|
| 78 |
-
rowId: string;
|
| 79 |
-
rowLabel: string;
|
| 80 |
-
field: string;
|
| 81 |
-
fieldLabel: string;
|
| 82 |
-
before: string;
|
| 83 |
-
after: string;
|
| 84 |
-
}
|
| 85 |
-
|
| 86 |
-
/** Who said it. `note` is the panel talking about itself (a confirm outcome, a cancelled write). */
|
| 87 |
-
export type GridChatWho = "you" | "assistant" | "note";
|
| 88 |
-
|
| 89 |
-
/**
|
| 90 |
-
* One turn. β `error` is a KIND OF TURN rather than a banner, and that is deliberate: a failed
|
| 91 |
-
* question is part of the conversation a person is having. They will rephrase and try again, and a
|
| 92 |
-
* toast that has already faded cannot be re-read while they do. `AutomationChat` made the same
|
| 93 |
-
* call for the same reason; two chat surfaces disagreeing about where failure lives is how one
|
| 94 |
-
* product stops looking like one product.
|
| 95 |
-
*/
|
| 96 |
-
export interface GridChatTurn {
|
| 97 |
-
who: GridChatWho;
|
| 98 |
-
text: string;
|
| 99 |
-
error?: boolean;
|
| 100 |
-
/** Present only on a turn that is proposing writes. The panel renders the before/after list. */
|
| 101 |
-
edits?: GridChatEdit[];
|
| 102 |
-
/**
|
| 103 |
-
* ββ THE INVERSE OF A WRITE THAT ALREADY HAPPENED, CARRIED ON THE NOTE THAT REPORTS IT.
|
| 104 |
-
*
|
| 105 |
-
* β IT IS BUILT FROM THE PROPOSAL, BEFORE THE WRITE, NOT READ BACK AFTER IT
|
| 106 |
-
* [[capture-the-inverse-before-the-write]]. Once the cells are written the old values are gone
|
| 107 |
-
* from the store, so an undo assembled afterwards can only re-read what it just wrote and undo
|
| 108 |
-
* nothing. Every `GridChatEdit` already carries `before` because the person had to SEE it in
|
| 109 |
-
* order to confirm, which means the inverse costs nothing extra and cannot be stale.
|
| 110 |
-
*/
|
| 111 |
-
undo?: GridChatEdit[];
|
| 112 |
-
}
|
| 113 |
-
|
| 114 |
-
/**
|
| 115 |
-
* The whole panel state.
|
| 116 |
-
*
|
| 117 |
-
* β `pending` IS THE IN-FLIGHT STATE AND IT IS THE QUESTION ITSELF, not a boolean. A boolean can
|
| 118 |
-
* go stale against the transcript: two rapid sends with `busy: true` leave no record of which
|
| 119 |
-
* question is actually outstanding, and the answer lands under whichever turn happens to be last.
|
| 120 |
-
* Holding the text means the panel can always say what it is waiting on, and `answered()` can
|
| 121 |
-
* refuse an answer that arrived after the person moved on.
|
| 122 |
-
*/
|
| 123 |
-
export interface GridChatState {
|
| 124 |
-
turns: GridChatTurn[];
|
| 125 |
-
pending: string | null;
|
| 126 |
-
}
|
| 127 |
-
|
| 128 |
-
export function emptyChat(): GridChatState {
|
| 129 |
-
return { turns: [], pending: null };
|
| 130 |
-
}
|
| 131 |
-
|
| 132 |
-
export function isBusy(state: GridChatState): boolean {
|
| 133 |
-
return state.pending !== null;
|
| 134 |
-
}
|
| 135 |
-
|
| 136 |
-
/**
|
| 137 |
-
* The person sent something. Returns the new state, or the SAME state when there is nothing to
|
| 138 |
-
* send or a question is already outstanding.
|
| 139 |
-
*
|
| 140 |
-
* β ONE QUESTION AT A TIME, AND THE REFUSAL IS SILENT BY DESIGN. The composer disables its own
|
| 141 |
-
* send button while `pending`, so a second send can only arrive from a key repeat or a double
|
| 142 |
-
* click. Answering that with an error turn would put a scolding message in a transcript the person
|
| 143 |
-
* did not mean to write in. Returning the same object also lets the caller skip the re-render.
|
| 144 |
-
*/
|
| 145 |
-
export function asked(state: GridChatState, said: string): GridChatState {
|
| 146 |
-
const text = String(said || "").trim();
|
| 147 |
-
if (!text || state.pending !== null) return state;
|
| 148 |
-
return { turns: [...state.turns, { who: "you", text }], pending: text };
|
| 149 |
-
}
|
| 150 |
-
|
| 151 |
-
/**
|
| 152 |
-
* A host callback answered. `forQuestion` is the text `asked()` returned in `pending`.
|
| 153 |
-
*
|
| 154 |
-
* β AN ANSWER TO A QUESTION NOBODY IS WAITING ON IS DROPPED. A slow first answer that lands after
|
| 155 |
-
* the person cancelled and asked something else would otherwise be appended under the new question
|
| 156 |
-
* and read as its answer. Checking the text is enough here because `asked()` refuses to start a
|
| 157 |
-
* second question while one is outstanding, so at most one can ever be in flight.
|
| 158 |
-
*/
|
| 159 |
-
export function answered(
|
| 160 |
-
state: GridChatState,
|
| 161 |
-
forQuestion: string,
|
| 162 |
-
answer: GridChatAnswer,
|
| 163 |
-
): GridChatState {
|
| 164 |
-
if (state.pending === null || state.pending !== forQuestion) return state;
|
| 165 |
-
const said = String(answer?.text || "").trim();
|
| 166 |
-
return {
|
| 167 |
-
turns: [...state.turns, {
|
| 168 |
-
who: "assistant",
|
| 169 |
-
// β An empty answer is a defect in the host, not a blank bubble for the reader to interpret.
|
| 170 |
-
text: said || "That came back empty, so there is nothing to show. Try asking again.",
|
| 171 |
-
error: !said,
|
| 172 |
-
}],
|
| 173 |
-
pending: null,
|
| 174 |
-
};
|
| 175 |
-
}
|
| 176 |
-
|
| 177 |
-
/**
|
| 178 |
-
* A host callback failed. `sentence` is what the person reads.
|
| 179 |
-
*
|
| 180 |
-
* β THE SENTENCE IS THE PRODUCT. `HTTP 402` on a screen tells a reader nothing they can do, and
|
| 181 |
-
* the owner has quoted a raw status back at us twice. A caller with nothing better than an
|
| 182 |
-
* exception name passes nothing and gets the fallback below, which at least says what happened and
|
| 183 |
-
* what to do next.
|
| 184 |
-
*/
|
| 185 |
-
export function failed(
|
| 186 |
-
state: GridChatState,
|
| 187 |
-
forQuestion: string,
|
| 188 |
-
sentence?: string,
|
| 189 |
-
): GridChatState {
|
| 190 |
-
if (state.pending === null || state.pending !== forQuestion) return state;
|
| 191 |
-
const said = String(sentence || "").trim();
|
| 192 |
-
return {
|
| 193 |
-
turns: [...state.turns, {
|
| 194 |
-
who: "assistant",
|
| 195 |
-
text: said || "That did not go through. Nothing was changed, so it is safe to try again.",
|
| 196 |
-
error: true,
|
| 197 |
-
}],
|
| 198 |
-
pending: null,
|
| 199 |
-
};
|
| 200 |
-
}
|
| 201 |
-
|
| 202 |
-
/** The panel telling the person what it just did. Never in flight, never an error. */
|
| 203 |
-
export function noted(state: GridChatState, text: string): GridChatState {
|
| 204 |
-
const said = String(text || "").trim();
|
| 205 |
-
if (!said) return state;
|
| 206 |
-
return { ...state, turns: [...state.turns, { who: "note", text: said }] };
|
| 207 |
-
}
|
| 208 |
-
|
| 209 |
-
/**
|
| 210 |
-
* The assistant is proposing cell writes and wants a confirm (R10).
|
| 211 |
-
*
|
| 212 |
-
* β THE PROPOSAL IS A TURN, not a modal. A modal would cover the transcript the person needs in
|
| 213 |
-
* order to judge the proposal, and it would vanish on a mis-click taking the reasoning with it.
|
| 214 |
-
* β NOTHING IS WRITTEN BY THIS FUNCTION. It appends a turn carrying the before/after list; the
|
| 215 |
-
* host's `onWriteCells` is reached only from the confirm control, which is W37-T45's half.
|
| 216 |
-
*/
|
| 217 |
-
export function proposedEdits(
|
| 218 |
-
state: GridChatState,
|
| 219 |
-
forQuestion: string,
|
| 220 |
-
text: string,
|
| 221 |
-
edits: GridChatEdit[],
|
| 222 |
-
): GridChatState {
|
| 223 |
-
if (state.pending === null || state.pending !== forQuestion) return state;
|
| 224 |
-
const rows = (edits || []).filter((e) => e && e.rowId && e.field);
|
| 225 |
-
if (!rows.length) return answered(state, forQuestion, { text });
|
| 226 |
-
return {
|
| 227 |
-
turns: [...state.turns, {
|
| 228 |
-
who: "assistant",
|
| 229 |
-
text: String(text || "").trim() || "Here is exactly what this would write.",
|
| 230 |
-
edits: rows,
|
| 231 |
-
}],
|
| 232 |
-
pending: null,
|
| 233 |
-
};
|
| 234 |
-
}
|
| 235 |
-
|
| 236 |
-
/**
|
| 237 |
-
* The inverse of a set of edits: what would put every cell back.
|
| 238 |
-
*
|
| 239 |
-
* β CALL THIS BEFORE THE WRITE, NOT AFTER. It reads `before`, which only exists on the proposal
|
| 240 |
-
* the person confirmed; after the write the store holds `after` and there is nothing left to
|
| 241 |
-
* invert from [[capture-the-inverse-before-the-write]].
|
| 242 |
-
* β `rowLabel` and `fieldLabel` are carried through unchanged, so an undo confirm reads in the
|
| 243 |
-
* same words the original proposal did rather than in keys.
|
| 244 |
-
*/
|
| 245 |
-
export function invertEdits(edits: GridChatEdit[]): GridChatEdit[] {
|
| 246 |
-
return (edits || [])
|
| 247 |
-
.filter((e) => e && e.rowId && e.field)
|
| 248 |
-
.map((e) => ({ ...e, before: e.after, after: e.before }));
|
| 249 |
-
}
|
| 250 |
-
|
| 251 |
-
/**
|
| 252 |
-
* A confirmed write landed. The note it appends CARRIES ITS OWN INVERSE, so undo is offered from
|
| 253 |
-
* the transcript rather than from a toast that has already gone.
|
| 254 |
-
*/
|
| 255 |
-
export function wrote(state: GridChatState, edits: GridChatEdit[]): GridChatState {
|
| 256 |
-
const rows = (edits || []).filter((e) => e && e.rowId && e.field);
|
| 257 |
-
if (!rows.length) return state;
|
| 258 |
-
return {
|
| 259 |
-
...state,
|
| 260 |
-
turns: [...state.turns, {
|
| 261 |
-
who: "note",
|
| 262 |
-
text: `Written. ${editSummary(rows)}`,
|
| 263 |
-
undo: invertEdits(rows),
|
| 264 |
-
}],
|
| 265 |
-
};
|
| 266 |
-
}
|
| 267 |
-
|
| 268 |
-
/**
|
| 269 |
-
* The one-line summary a confirm control shows beside the before/after list.
|
| 270 |
-
*
|
| 271 |
-
* β It counts CELLS and RECORDS separately because they are different risks: twenty cells on one
|
| 272 |
-
* record is a correction, one cell on twenty records is a sweep. A single "20 changes" hides which
|
| 273 |
-
* of those the person is about to approve.
|
| 274 |
-
*/
|
| 275 |
-
export function editSummary(edits: GridChatEdit[]): string {
|
| 276 |
-
const rows = (edits || []).filter((e) => e && e.rowId && e.field);
|
| 277 |
-
if (!rows.length) return "Nothing to write.";
|
| 278 |
-
const records = new Set(rows.map((e) => e.rowId)).size;
|
| 279 |
-
const cellWord = rows.length === 1 ? "cell" : "cells";
|
| 280 |
-
const recordWord = records === 1 ? "record" : "records";
|
| 281 |
-
return `${rows.length} ${cellWord} on ${records} ${recordWord}.`;
|
| 282 |
-
}
|
| 283 |
-
|
| 284 |
-
/**
|
| 285 |
-
* What the composer invites the person to type.
|
| 286 |
-
*
|
| 287 |
-
* β IT NAMES THE DATABASE. A chat docked beside a grid is ambiguous about what it is reading the
|
| 288 |
-
* moment a person has two tabs open, and the fix is one word in the placeholder rather than a
|
| 289 |
-
* second header line.
|
| 290 |
-
*/
|
| 291 |
-
export function composerHint(databaseLabel: string, canEdit: boolean): string {
|
| 292 |
-
const where = String(databaseLabel || "").trim() || "this database";
|
| 293 |
-
return canEdit
|
| 294 |
-
? `Ask about ${where}, or say what to change`
|
| 295 |
-
: `Ask about ${where}`;
|
| 296 |
-
}
|
| 297 |
-
|
| 298 |
-
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 299 |
-
// ββ THE INTENT LAYER (W37-T42 Β· T43 Β· T44) β WHAT THE CHAT KNOWS WITHOUT SPENDING ANYTHING
|
| 300 |
-
//
|
| 301 |
-
// ββ ITS JOB IS TO REFUSE HONESTLY BEFORE A MODEL CALL, NOT TO BE CLEVER. D-339's lesson is that
|
| 302 |
-
// an agent which cannot read the database answers from WORDS ALONE and invents a number; the fix
|
| 303 |
-
// is not a better guess, it is knowing what this database actually has and saying so when the
|
| 304 |
-
// question names something it does not. The panel holds the schema, so that answer costs nothing
|
| 305 |
-
// and cannot be wrong in the direction that matters.
|
| 306 |
-
// β EVERYTHING HERE IS PURE AND LOCAL. Anything that needs a model, a query or a write goes out
|
| 307 |
-
// through a host callback (C6). This layer only decides WHICH callback, and catches the questions
|
| 308 |
-
// that should never reach one.
|
| 309 |
-
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 310 |
-
|
| 311 |
-
/** What the panel decided a sentence was asking for. */
|
| 312 |
-
export type GridChatIntentKind = "schema" | "view" | "script" | "ask";
|
| 313 |
-
|
| 314 |
-
export interface GridChatIntent {
|
| 315 |
-
kind: GridChatIntentKind;
|
| 316 |
-
/** A complete answer the panel can give with NO model call. Present only when it truly can. */
|
| 317 |
-
localAnswer?: string;
|
| 318 |
-
/** Set when the sentence names something this database does not have. */
|
| 319 |
-
refusal?: string;
|
| 320 |
-
/** For `view`: what the panel understood, in the vocabulary the host's callback takes. */
|
| 321 |
-
view?: { sortBy?: string; groupBy?: string; colorBy?: string };
|
| 322 |
-
/** For `view`: what was asked for and CANNOT be expressed, named rather than dropped. */
|
| 323 |
-
cannot?: string;
|
| 324 |
-
}
|
| 325 |
-
|
| 326 |
-
const norm = (s: string) => String(s || "").toLowerCase().trim();
|
| 327 |
-
|
| 328 |
-
/**
|
| 329 |
-
* Which known fields a sentence mentions, by label or by key.
|
| 330 |
-
*
|
| 331 |
-
* β LABEL FIRST AND LONGEST FIRST. A person types the label they can see ("Sales rep"), not the
|
| 332 |
-
* key (`agent_id`), and matching short keys first would let a field called `n` match the word "in".
|
| 333 |
-
*/
|
| 334 |
-
export function fieldsNamed(schema: GridChatField[], said: string): GridChatField[] {
|
| 335 |
-
const text = norm(said);
|
| 336 |
-
if (!text) return [];
|
| 337 |
-
return (schema || [])
|
| 338 |
-
.filter((f) => f && (f.label || f.key))
|
| 339 |
-
.slice()
|
| 340 |
-
.sort((a, b) => (b.label || b.key).length - (a.label || a.key).length)
|
| 341 |
-
.filter((f) => {
|
| 342 |
-
const label = norm(f.label);
|
| 343 |
-
const key = norm(f.key);
|
| 344 |
-
return (label.length > 2 && text.includes(label))
|
| 345 |
-
|| (key.length > 2 && text.includes(key));
|
| 346 |
-
});
|
| 347 |
-
}
|
| 348 |
-
|
| 349 |
-
/**
|
| 350 |
-
* A quoted name that this database does not have, if the sentence contains one.
|
| 351 |
-
*
|
| 352 |
-
* β ONLY QUOTED NAMES, DELIBERATELY. Guessing that any capitalised phrase is a column would refuse
|
| 353 |
-
* perfectly good questions ("how many are in New York?"), and a refusal that fires on a real
|
| 354 |
-
* question is worse than a model call that answers it. Quotes are the one place a person has said
|
| 355 |
-
* "this is a name" out loud, so the panel can be certain enough to answer instead of asking.
|
| 356 |
-
* β This is the D-339 half the panel can do alone. Everything unquoted still goes to the host,
|
| 357 |
-
* which knows the data and can say `unanswerable` with better information than a regex has.
|
| 358 |
-
*/
|
| 359 |
-
export function unknownFieldNamed(schema: GridChatField[], said: string): string | null {
|
| 360 |
-
const quoted = String(said || "").match(/"[^"]{1,60}"|'[^']{1,60}'/g) || [];
|
| 361 |
-
const known = new Set((schema || []).flatMap((f) => [norm(f.label), norm(f.key)]));
|
| 362 |
-
for (const raw of quoted) {
|
| 363 |
-
const typed = raw.slice(1, -1).trim();
|
| 364 |
-
// β COMPARE LOWERCASED, RETURN AS TYPED, AND THE FIRST DRAFT DID NOT. It returned the
|
| 365 |
-
// normalised form, so somebody who wrote "Supplier Rep" was told there is no field called
|
| 366 |
-
// "supplier rep" β their own words handed back mangled, which reads as the system having
|
| 367 |
-
// misheard them rather than as an honest answer. Matching is case-insensitive because a person
|
| 368 |
-
// should not have to match a label's capitalisation; the MESSAGE quotes them exactly.
|
| 369 |
-
if (typed && !known.has(norm(typed))) return typed;
|
| 370 |
-
}
|
| 371 |
-
return null;
|
| 372 |
-
}
|
| 373 |
-
|
| 374 |
-
/** The plain-language field list, for a question the panel can answer with no model call at all. */
|
| 375 |
-
export function schemaSentence(schema: GridChatField[], databaseLabel: string): string {
|
| 376 |
-
const where = String(databaseLabel || "").trim() || "this database";
|
| 377 |
-
const names = (schema || []).map((f) => f.label || f.key).filter(Boolean);
|
| 378 |
-
if (!names.length) return where + " has no fields the chat can see.";
|
| 379 |
-
const word = names.length === 1 ? "field" : "fields";
|
| 380 |
-
return where + " has " + names.length + " " + word + ": " + names.join(", ") + ".";
|
| 381 |
-
}
|
| 382 |
-
|
| 383 |
-
/** Sentences that are asking what is here, rather than asking about the data. */
|
| 384 |
-
const SCHEMA_WORDS = ["what fields", "which fields", "what columns", "which columns",
|
| 385 |
-
"list the fields", "list the columns", "what can you see"];
|
| 386 |
-
/** Sentences asking for the VIEW to change rather than for an answer. */
|
| 387 |
-
const VIEW_WORDS = ["sort by", "sorted by", "group by", "grouped by", "colour by", "color by",
|
| 388 |
-
"show me only", "filter"];
|
| 389 |
-
/** Sentences asking for code. */
|
| 390 |
-
const SCRIPT_WORDS = ["build me", "make me", "write a script", "custom view", "dashboard",
|
| 391 |
-
"calculator", "chart"];
|
| 392 |
-
|
| 393 |
-
/**
|
| 394 |
-
* Read a sentence. β THE ORDER IS THE POLICY: refuse first, answer locally second, route third.
|
| 395 |
-
*
|
| 396 |
-
* β A DELIBERATELY SHALLOW READER. It is not trying to understand the question, because the host's
|
| 397 |
-
* model does that. It is trying to catch the two cases where going to the model is WRONG: a name
|
| 398 |
-
* this database does not have (which would come back as an invented number), and a question the
|
| 399 |
-
* panel already knows the answer to (which would be a paid round trip for a list it is holding).
|
| 400 |
-
*/
|
| 401 |
-
export function readIntent(
|
| 402 |
-
schema: GridChatField[],
|
| 403 |
-
databaseLabel: string,
|
| 404 |
-
said: string,
|
| 405 |
-
): GridChatIntent {
|
| 406 |
-
const text = norm(said);
|
| 407 |
-
const where = String(databaseLabel || "").trim() || "this database";
|
| 408 |
-
const missing = unknownFieldNamed(schema, said);
|
| 409 |
-
if (missing) {
|
| 410 |
-
const names = (schema || []).map((f) => f.label || f.key).filter(Boolean);
|
| 411 |
-
return {
|
| 412 |
-
kind: "ask",
|
| 413 |
-
refusal: 'There is no field called "' + missing + '" in ' + where + ". "
|
| 414 |
-
+ (names.length
|
| 415 |
-
? "The fields here are: " + names.join(", ") + "."
|
| 416 |
-
: "This database has no fields the chat can see."),
|
| 417 |
-
};
|
| 418 |
-
}
|
| 419 |
-
if (SCHEMA_WORDS.some((w) => text.includes(w)))
|
| 420 |
-
return { kind: "schema", localAnswer: schemaSentence(schema, databaseLabel) };
|
| 421 |
-
|
| 422 |
-
if (VIEW_WORDS.some((w) => text.includes(w))) {
|
| 423 |
-
const named = fieldsNamed(schema, said);
|
| 424 |
-
const view: { sortBy?: string; groupBy?: string; colorBy?: string } = {};
|
| 425 |
-
if (named.length) {
|
| 426 |
-
if (text.includes("group")) view.groupBy = named[0].key;
|
| 427 |
-
else if (text.includes("colour") || text.includes("color")) view.colorBy = named[0].key;
|
| 428 |
-
else if (text.includes("sort")) view.sortBy = named[0].key;
|
| 429 |
-
}
|
| 430 |
-
// β WHAT IT CANNOT SAY, SAID OUT LOUD. `assistant build_view` has no `rhs` in its tool schema,
|
| 431 |
-
// so a condition comparing one field to another is not expressible anywhere in this product
|
| 432 |
-
// [[assistant-build-view-is-a-subset]]. Dropping it silently would leave a person looking at a
|
| 433 |
-
// view that quietly ignored half their sentence, which is the failure this note exists to stop.
|
| 434 |
-
const fieldVsField = named.length >= 2 && /\b(than|versus|vs\.?|compared to)\b/.test(text);
|
| 435 |
-
return {
|
| 436 |
-
kind: "view",
|
| 437 |
-
view: Object.keys(view).length ? view : undefined,
|
| 438 |
-
cannot: fieldVsField
|
| 439 |
-
? "This build cannot compare one field against another in a view filter, so that part was "
|
| 440 |
-
+ "left out. Everything else was applied."
|
| 441 |
-
: undefined,
|
| 442 |
-
};
|
| 443 |
-
}
|
| 444 |
-
if (SCRIPT_WORDS.some((w) => text.includes(w))) return { kind: "script" };
|
| 445 |
-
return { kind: "ask" };
|
| 446 |
-
}
|
| 447 |
-
|
| 448 |
-
/**
|
| 449 |
-
* The sentence shown when a script the chat wrote is run.
|
| 450 |
-
*
|
| 451 |
-
* β THE VIEW IS NOT BLANKED ON FAILURE (W37-T44's own `done-when`). A script that raised is a fact
|
| 452 |
-
* about the code, and the code is still there to be edited; replacing the panel with nothing would
|
| 453 |
-
* take away the one thing the person needs in order to fix it.
|
| 454 |
-
*/
|
| 455 |
-
export function runSentence(result: GridChatRunResult): string {
|
| 456 |
-
if (result && result.ok) return "That ran. The view is showing what it drew.";
|
| 457 |
-
const why = String((result && result.error) || "").trim();
|
| 458 |
-
return why
|
| 459 |
-
? "That script did not run: " + why + " The code is still in the editor, so you can change it."
|
| 460 |
-
: "That script did not produce a view. The code is still in the editor, so you can change it.";
|
| 461 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// customer-grid / gridChat.ts β the chat panel's state, as pure functions (W37-T40, R2, C6).
|
| 3 |
+
//
|
| 4 |
+
// ββ WHY THE STATE LIVES HERE AND NOT IN THE COMPONENT. `<GridChat>` has to demonstrate three
|
| 5 |
+
// things its `done-when` names: a message history, an in-flight state and an error state. If those
|
| 6 |
+
// transitions live in `useState` callbacks inside the .tsx, the only way to assert on them is to
|
| 7 |
+
// render React and match emitted markup β which pins the compiler's output rather than the
|
| 8 |
+
// behaviour, and goes red on a refactor that changed nothing a person can see. Here they are plain
|
| 9 |
+
// functions over a plain object, so the gate checks the STATE MACHINE without React in the process
|
| 10 |
+
// at all, and the render only has to prove the three states paint.
|
| 11 |
+
//
|
| 12 |
+
// ββ NOTHING IN THIS FILE TALKS TO THE NETWORK, THE GRID, OR THE STORE β contract C6, and it is
|
| 13 |
+
// structural rather than a promise. There is no `fetch` here and no import of anything that has
|
| 14 |
+
// one: every action the chat can take arrives as a callback the host supplies. That is what lets
|
| 15 |
+
// the host WALL the chat by simply not passing a power, instead of the chat asking permission and
|
| 16 |
+
// being told no [[permitted-is-not-answerable]].
|
| 17 |
+
//
|
| 18 |
+
// β NO EM DASH OR EN DASH IN ANY STRING THAT REACHES A SCREEN (standing rule 2). The sentences
|
| 19 |
+
// below are user-facing copy, and `web_prose` cannot see a wrapped JSX sentence, so the discipline
|
| 20 |
+
// is on the author. Commas, colons and full stops carry the same weight and are not AI slop.
|
| 21 |
+
// ---------------------------------------------------------------------------
|
| 22 |
+
|
| 23 |
+
/** One column the chat is allowed to know about. The host decides what goes in this list. */
|
| 24 |
+
export interface GridChatField {
|
| 25 |
+
key: string;
|
| 26 |
+
label: string;
|
| 27 |
+
type: string;
|
| 28 |
+
}
|
| 29 |
+
|
| 30 |
+
/**
|
| 31 |
+
* What a host callback hands back for a question.
|
| 32 |
+
*
|
| 33 |
+
* β `text` IS REQUIRED AND `unanswerable` IS THE HONEST OUT. D-339's lesson is that an agent
|
| 34 |
+
* which cannot read the database answers from words alone and invents a number; a host that cannot
|
| 35 |
+
* answer must be able to SAY so rather than return an empty string the panel renders as silence.
|
| 36 |
+
*/
|
| 37 |
+
export interface GridChatAnswer {
|
| 38 |
+
text: string;
|
| 39 |
+
/** Set when the question named something this database does not have. Rendered as an answer,
|
| 40 |
+
* not as a failure: the person asked a reasonable question about the wrong column. */
|
| 41 |
+
unanswerable?: boolean;
|
| 42 |
+
/**
|
| 43 |
+
* ββ R10's PROPOSAL CHANNEL, DECLARED RATHER THAN CAST. The panel reads this to decide that an
|
| 44 |
+
* answer is a proposed WRITE and must be shown for confirmation instead of rendered as prose.
|
| 45 |
+
*
|
| 46 |
+
* β IT WAS A CAST FIRST, AND THAT WAS THE BUG-IN-WAITING. `GridChat` read
|
| 47 |
+
* `(answer as {edits?: ...}).edits` while this interface said nothing about it, so the contract
|
| 48 |
+
* lived in one file and the reader in another. The host reads the PUBLISHED type; a host that
|
| 49 |
+
* never sees `edits` never sends `edits`, the whole confirm path is dead on arrival, and nothing
|
| 50 |
+
* anywhere fails [[flag-shipped-without-its-writer]]. Typing it is the difference between a
|
| 51 |
+
* channel and a coincidence.
|
| 52 |
+
* β Its presence is a PROPOSAL, never an instruction: nothing is written until the person
|
| 53 |
+
* confirms, and a caller with `canEdit:false` is not shown the control at all.
|
| 54 |
+
*/
|
| 55 |
+
edits?: GridChatEdit[];
|
| 56 |
+
/**
|
| 57 |
+
* ββ W37-T44's GENERATION CHANNEL. The host authored a Custom View's code; the panel RUNS it
|
| 58 |
+
* through `onRunScript` and reports what happened.
|
| 59 |
+
*
|
| 60 |
+
* β DECLARED, NOT INFERRED, FOR THE SAME REASON `edits` IS. A channel the reader consumes and
|
| 61 |
+
* the published type does not mention is a channel the host never fills, and nothing anywhere
|
| 62 |
+
* fails [[flag-shipped-without-its-writer]] β which is exactly what a `void`ed callback and a
|
| 63 |
+
* confident `observed:` line looked like in the first draft of this ticket.
|
| 64 |
+
* β AUTHORING IS THE HOST'S, RUNNING IS THE PANEL'S. That split is what keeps the sandbox
|
| 65 |
+
* un-widened: the code goes through the ordinary run door a hand-typed script uses.
|
| 66 |
+
*/
|
| 67 |
+
script?: string;
|
| 68 |
+
}
|
| 69 |
+
|
| 70 |
+
/** The outcome of running a Custom View's code. `error` is a sentence, never a stack trace. */
|
| 71 |
+
export interface GridChatRunResult {
|
| 72 |
+
ok: boolean;
|
| 73 |
+
error?: string;
|
| 74 |
+
}
|
| 75 |
+
|
| 76 |
+
/** One cell the chat proposes to write. R10: the person sees `before` and `after` before anything. */
|
| 77 |
+
export interface GridChatEdit {
|
| 78 |
+
rowId: string;
|
| 79 |
+
rowLabel: string;
|
| 80 |
+
field: string;
|
| 81 |
+
fieldLabel: string;
|
| 82 |
+
before: string;
|
| 83 |
+
after: string;
|
| 84 |
+
}
|
| 85 |
+
|
| 86 |
+
/** Who said it. `note` is the panel talking about itself (a confirm outcome, a cancelled write). */
|
| 87 |
+
export type GridChatWho = "you" | "assistant" | "note";
|
| 88 |
+
|
| 89 |
+
/**
|
| 90 |
+
* One turn. β `error` is a KIND OF TURN rather than a banner, and that is deliberate: a failed
|
| 91 |
+
* question is part of the conversation a person is having. They will rephrase and try again, and a
|
| 92 |
+
* toast that has already faded cannot be re-read while they do. `AutomationChat` made the same
|
| 93 |
+
* call for the same reason; two chat surfaces disagreeing about where failure lives is how one
|
| 94 |
+
* product stops looking like one product.
|
| 95 |
+
*/
|
| 96 |
+
export interface GridChatTurn {
|
| 97 |
+
who: GridChatWho;
|
| 98 |
+
text: string;
|
| 99 |
+
error?: boolean;
|
| 100 |
+
/** Present only on a turn that is proposing writes. The panel renders the before/after list. */
|
| 101 |
+
edits?: GridChatEdit[];
|
| 102 |
+
/**
|
| 103 |
+
* ββ THE INVERSE OF A WRITE THAT ALREADY HAPPENED, CARRIED ON THE NOTE THAT REPORTS IT.
|
| 104 |
+
*
|
| 105 |
+
* β IT IS BUILT FROM THE PROPOSAL, BEFORE THE WRITE, NOT READ BACK AFTER IT
|
| 106 |
+
* [[capture-the-inverse-before-the-write]]. Once the cells are written the old values are gone
|
| 107 |
+
* from the store, so an undo assembled afterwards can only re-read what it just wrote and undo
|
| 108 |
+
* nothing. Every `GridChatEdit` already carries `before` because the person had to SEE it in
|
| 109 |
+
* order to confirm, which means the inverse costs nothing extra and cannot be stale.
|
| 110 |
+
*/
|
| 111 |
+
undo?: GridChatEdit[];
|
| 112 |
+
}
|
| 113 |
+
|
| 114 |
+
/**
|
| 115 |
+
* The whole panel state.
|
| 116 |
+
*
|
| 117 |
+
* β `pending` IS THE IN-FLIGHT STATE AND IT IS THE QUESTION ITSELF, not a boolean. A boolean can
|
| 118 |
+
* go stale against the transcript: two rapid sends with `busy: true` leave no record of which
|
| 119 |
+
* question is actually outstanding, and the answer lands under whichever turn happens to be last.
|
| 120 |
+
* Holding the text means the panel can always say what it is waiting on, and `answered()` can
|
| 121 |
+
* refuse an answer that arrived after the person moved on.
|
| 122 |
+
*/
|
| 123 |
+
export interface GridChatState {
|
| 124 |
+
turns: GridChatTurn[];
|
| 125 |
+
pending: string | null;
|
| 126 |
+
}
|
| 127 |
+
|
| 128 |
+
export function emptyChat(): GridChatState {
|
| 129 |
+
return { turns: [], pending: null };
|
| 130 |
+
}
|
| 131 |
+
|
| 132 |
+
export function isBusy(state: GridChatState): boolean {
|
| 133 |
+
return state.pending !== null;
|
| 134 |
+
}
|
| 135 |
+
|
| 136 |
+
/**
|
| 137 |
+
* The person sent something. Returns the new state, or the SAME state when there is nothing to
|
| 138 |
+
* send or a question is already outstanding.
|
| 139 |
+
*
|
| 140 |
+
* β ONE QUESTION AT A TIME, AND THE REFUSAL IS SILENT BY DESIGN. The composer disables its own
|
| 141 |
+
* send button while `pending`, so a second send can only arrive from a key repeat or a double
|
| 142 |
+
* click. Answering that with an error turn would put a scolding message in a transcript the person
|
| 143 |
+
* did not mean to write in. Returning the same object also lets the caller skip the re-render.
|
| 144 |
+
*/
|
| 145 |
+
export function asked(state: GridChatState, said: string): GridChatState {
|
| 146 |
+
const text = String(said || "").trim();
|
| 147 |
+
if (!text || state.pending !== null) return state;
|
| 148 |
+
return { turns: [...state.turns, { who: "you", text }], pending: text };
|
| 149 |
+
}
|
| 150 |
+
|
| 151 |
+
/**
|
| 152 |
+
* A host callback answered. `forQuestion` is the text `asked()` returned in `pending`.
|
| 153 |
+
*
|
| 154 |
+
* β AN ANSWER TO A QUESTION NOBODY IS WAITING ON IS DROPPED. A slow first answer that lands after
|
| 155 |
+
* the person cancelled and asked something else would otherwise be appended under the new question
|
| 156 |
+
* and read as its answer. Checking the text is enough here because `asked()` refuses to start a
|
| 157 |
+
* second question while one is outstanding, so at most one can ever be in flight.
|
| 158 |
+
*/
|
| 159 |
+
export function answered(
|
| 160 |
+
state: GridChatState,
|
| 161 |
+
forQuestion: string,
|
| 162 |
+
answer: GridChatAnswer,
|
| 163 |
+
): GridChatState {
|
| 164 |
+
if (state.pending === null || state.pending !== forQuestion) return state;
|
| 165 |
+
const said = String(answer?.text || "").trim();
|
| 166 |
+
return {
|
| 167 |
+
turns: [...state.turns, {
|
| 168 |
+
who: "assistant",
|
| 169 |
+
// β An empty answer is a defect in the host, not a blank bubble for the reader to interpret.
|
| 170 |
+
text: said || "That came back empty, so there is nothing to show. Try asking again.",
|
| 171 |
+
error: !said,
|
| 172 |
+
}],
|
| 173 |
+
pending: null,
|
| 174 |
+
};
|
| 175 |
+
}
|
| 176 |
+
|
| 177 |
+
/**
|
| 178 |
+
* A host callback failed. `sentence` is what the person reads.
|
| 179 |
+
*
|
| 180 |
+
* β THE SENTENCE IS THE PRODUCT. `HTTP 402` on a screen tells a reader nothing they can do, and
|
| 181 |
+
* the owner has quoted a raw status back at us twice. A caller with nothing better than an
|
| 182 |
+
* exception name passes nothing and gets the fallback below, which at least says what happened and
|
| 183 |
+
* what to do next.
|
| 184 |
+
*/
|
| 185 |
+
export function failed(
|
| 186 |
+
state: GridChatState,
|
| 187 |
+
forQuestion: string,
|
| 188 |
+
sentence?: string,
|
| 189 |
+
): GridChatState {
|
| 190 |
+
if (state.pending === null || state.pending !== forQuestion) return state;
|
| 191 |
+
const said = String(sentence || "").trim();
|
| 192 |
+
return {
|
| 193 |
+
turns: [...state.turns, {
|
| 194 |
+
who: "assistant",
|
| 195 |
+
text: said || "That did not go through. Nothing was changed, so it is safe to try again.",
|
| 196 |
+
error: true,
|
| 197 |
+
}],
|
| 198 |
+
pending: null,
|
| 199 |
+
};
|
| 200 |
+
}
|
| 201 |
+
|
| 202 |
+
/** The panel telling the person what it just did. Never in flight, never an error. */
|
| 203 |
+
export function noted(state: GridChatState, text: string): GridChatState {
|
| 204 |
+
const said = String(text || "").trim();
|
| 205 |
+
if (!said) return state;
|
| 206 |
+
return { ...state, turns: [...state.turns, { who: "note", text: said }] };
|
| 207 |
+
}
|
| 208 |
+
|
| 209 |
+
/**
|
| 210 |
+
* The assistant is proposing cell writes and wants a confirm (R10).
|
| 211 |
+
*
|
| 212 |
+
* β THE PROPOSAL IS A TURN, not a modal. A modal would cover the transcript the person needs in
|
| 213 |
+
* order to judge the proposal, and it would vanish on a mis-click taking the reasoning with it.
|
| 214 |
+
* β NOTHING IS WRITTEN BY THIS FUNCTION. It appends a turn carrying the before/after list; the
|
| 215 |
+
* host's `onWriteCells` is reached only from the confirm control, which is W37-T45's half.
|
| 216 |
+
*/
|
| 217 |
+
export function proposedEdits(
|
| 218 |
+
state: GridChatState,
|
| 219 |
+
forQuestion: string,
|
| 220 |
+
text: string,
|
| 221 |
+
edits: GridChatEdit[],
|
| 222 |
+
): GridChatState {
|
| 223 |
+
if (state.pending === null || state.pending !== forQuestion) return state;
|
| 224 |
+
const rows = (edits || []).filter((e) => e && e.rowId && e.field);
|
| 225 |
+
if (!rows.length) return answered(state, forQuestion, { text });
|
| 226 |
+
return {
|
| 227 |
+
turns: [...state.turns, {
|
| 228 |
+
who: "assistant",
|
| 229 |
+
text: String(text || "").trim() || "Here is exactly what this would write.",
|
| 230 |
+
edits: rows,
|
| 231 |
+
}],
|
| 232 |
+
pending: null,
|
| 233 |
+
};
|
| 234 |
+
}
|
| 235 |
+
|
| 236 |
+
/**
|
| 237 |
+
* The inverse of a set of edits: what would put every cell back.
|
| 238 |
+
*
|
| 239 |
+
* β CALL THIS BEFORE THE WRITE, NOT AFTER. It reads `before`, which only exists on the proposal
|
| 240 |
+
* the person confirmed; after the write the store holds `after` and there is nothing left to
|
| 241 |
+
* invert from [[capture-the-inverse-before-the-write]].
|
| 242 |
+
* β `rowLabel` and `fieldLabel` are carried through unchanged, so an undo confirm reads in the
|
| 243 |
+
* same words the original proposal did rather than in keys.
|
| 244 |
+
*/
|
| 245 |
+
export function invertEdits(edits: GridChatEdit[]): GridChatEdit[] {
|
| 246 |
+
return (edits || [])
|
| 247 |
+
.filter((e) => e && e.rowId && e.field)
|
| 248 |
+
.map((e) => ({ ...e, before: e.after, after: e.before }));
|
| 249 |
+
}
|
| 250 |
+
|
| 251 |
+
/**
|
| 252 |
+
* A confirmed write landed. The note it appends CARRIES ITS OWN INVERSE, so undo is offered from
|
| 253 |
+
* the transcript rather than from a toast that has already gone.
|
| 254 |
+
*/
|
| 255 |
+
export function wrote(state: GridChatState, edits: GridChatEdit[]): GridChatState {
|
| 256 |
+
const rows = (edits || []).filter((e) => e && e.rowId && e.field);
|
| 257 |
+
if (!rows.length) return state;
|
| 258 |
+
return {
|
| 259 |
+
...state,
|
| 260 |
+
turns: [...state.turns, {
|
| 261 |
+
who: "note",
|
| 262 |
+
text: `Written. ${editSummary(rows)}`,
|
| 263 |
+
undo: invertEdits(rows),
|
| 264 |
+
}],
|
| 265 |
+
};
|
| 266 |
+
}
|
| 267 |
+
|
| 268 |
+
/**
|
| 269 |
+
* The one-line summary a confirm control shows beside the before/after list.
|
| 270 |
+
*
|
| 271 |
+
* β It counts CELLS and RECORDS separately because they are different risks: twenty cells on one
|
| 272 |
+
* record is a correction, one cell on twenty records is a sweep. A single "20 changes" hides which
|
| 273 |
+
* of those the person is about to approve.
|
| 274 |
+
*/
|
| 275 |
+
export function editSummary(edits: GridChatEdit[]): string {
|
| 276 |
+
const rows = (edits || []).filter((e) => e && e.rowId && e.field);
|
| 277 |
+
if (!rows.length) return "Nothing to write.";
|
| 278 |
+
const records = new Set(rows.map((e) => e.rowId)).size;
|
| 279 |
+
const cellWord = rows.length === 1 ? "cell" : "cells";
|
| 280 |
+
const recordWord = records === 1 ? "record" : "records";
|
| 281 |
+
return `${rows.length} ${cellWord} on ${records} ${recordWord}.`;
|
| 282 |
+
}
|
| 283 |
+
|
| 284 |
+
/**
|
| 285 |
+
* What the composer invites the person to type.
|
| 286 |
+
*
|
| 287 |
+
* β IT NAMES THE DATABASE. A chat docked beside a grid is ambiguous about what it is reading the
|
| 288 |
+
* moment a person has two tabs open, and the fix is one word in the placeholder rather than a
|
| 289 |
+
* second header line.
|
| 290 |
+
*/
|
| 291 |
+
export function composerHint(databaseLabel: string, canEdit: boolean): string {
|
| 292 |
+
const where = String(databaseLabel || "").trim() || "this database";
|
| 293 |
+
return canEdit
|
| 294 |
+
? `Ask about ${where}, or say what to change`
|
| 295 |
+
: `Ask about ${where}`;
|
| 296 |
+
}
|
| 297 |
+
|
| 298 |
+
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 299 |
+
// ββ THE INTENT LAYER (W37-T42 Β· T43 Β· T44) β WHAT THE CHAT KNOWS WITHOUT SPENDING ANYTHING
|
| 300 |
+
//
|
| 301 |
+
// ββ ITS JOB IS TO REFUSE HONESTLY BEFORE A MODEL CALL, NOT TO BE CLEVER. D-339's lesson is that
|
| 302 |
+
// an agent which cannot read the database answers from WORDS ALONE and invents a number; the fix
|
| 303 |
+
// is not a better guess, it is knowing what this database actually has and saying so when the
|
| 304 |
+
// question names something it does not. The panel holds the schema, so that answer costs nothing
|
| 305 |
+
// and cannot be wrong in the direction that matters.
|
| 306 |
+
// β EVERYTHING HERE IS PURE AND LOCAL. Anything that needs a model, a query or a write goes out
|
| 307 |
+
// through a host callback (C6). This layer only decides WHICH callback, and catches the questions
|
| 308 |
+
// that should never reach one.
|
| 309 |
+
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 310 |
+
|
| 311 |
+
/** What the panel decided a sentence was asking for. */
|
| 312 |
+
export type GridChatIntentKind = "schema" | "view" | "script" | "ask";
|
| 313 |
+
|
| 314 |
+
export interface GridChatIntent {
|
| 315 |
+
kind: GridChatIntentKind;
|
| 316 |
+
/** A complete answer the panel can give with NO model call. Present only when it truly can. */
|
| 317 |
+
localAnswer?: string;
|
| 318 |
+
/** Set when the sentence names something this database does not have. */
|
| 319 |
+
refusal?: string;
|
| 320 |
+
/** For `view`: what the panel understood, in the vocabulary the host's callback takes. */
|
| 321 |
+
view?: { sortBy?: string; groupBy?: string; colorBy?: string };
|
| 322 |
+
/** For `view`: what was asked for and CANNOT be expressed, named rather than dropped. */
|
| 323 |
+
cannot?: string;
|
| 324 |
+
}
|
| 325 |
+
|
| 326 |
+
const norm = (s: string) => String(s || "").toLowerCase().trim();
|
| 327 |
+
|
| 328 |
+
/**
|
| 329 |
+
* Which known fields a sentence mentions, by label or by key.
|
| 330 |
+
*
|
| 331 |
+
* β LABEL FIRST AND LONGEST FIRST. A person types the label they can see ("Sales rep"), not the
|
| 332 |
+
* key (`agent_id`), and matching short keys first would let a field called `n` match the word "in".
|
| 333 |
+
*/
|
| 334 |
+
export function fieldsNamed(schema: GridChatField[], said: string): GridChatField[] {
|
| 335 |
+
const text = norm(said);
|
| 336 |
+
if (!text) return [];
|
| 337 |
+
return (schema || [])
|
| 338 |
+
.filter((f) => f && (f.label || f.key))
|
| 339 |
+
.slice()
|
| 340 |
+
.sort((a, b) => (b.label || b.key).length - (a.label || a.key).length)
|
| 341 |
+
.filter((f) => {
|
| 342 |
+
const label = norm(f.label);
|
| 343 |
+
const key = norm(f.key);
|
| 344 |
+
return (label.length > 2 && text.includes(label))
|
| 345 |
+
|| (key.length > 2 && text.includes(key));
|
| 346 |
+
});
|
| 347 |
+
}
|
| 348 |
+
|
| 349 |
+
/**
|
| 350 |
+
* A quoted name that this database does not have, if the sentence contains one.
|
| 351 |
+
*
|
| 352 |
+
* β ONLY QUOTED NAMES, DELIBERATELY. Guessing that any capitalised phrase is a column would refuse
|
| 353 |
+
* perfectly good questions ("how many are in New York?"), and a refusal that fires on a real
|
| 354 |
+
* question is worse than a model call that answers it. Quotes are the one place a person has said
|
| 355 |
+
* "this is a name" out loud, so the panel can be certain enough to answer instead of asking.
|
| 356 |
+
* β This is the D-339 half the panel can do alone. Everything unquoted still goes to the host,
|
| 357 |
+
* which knows the data and can say `unanswerable` with better information than a regex has.
|
| 358 |
+
*/
|
| 359 |
+
export function unknownFieldNamed(schema: GridChatField[], said: string): string | null {
|
| 360 |
+
const quoted = String(said || "").match(/"[^"]{1,60}"|'[^']{1,60}'/g) || [];
|
| 361 |
+
const known = new Set((schema || []).flatMap((f) => [norm(f.label), norm(f.key)]));
|
| 362 |
+
for (const raw of quoted) {
|
| 363 |
+
const typed = raw.slice(1, -1).trim();
|
| 364 |
+
// β COMPARE LOWERCASED, RETURN AS TYPED, AND THE FIRST DRAFT DID NOT. It returned the
|
| 365 |
+
// normalised form, so somebody who wrote "Supplier Rep" was told there is no field called
|
| 366 |
+
// "supplier rep" β their own words handed back mangled, which reads as the system having
|
| 367 |
+
// misheard them rather than as an honest answer. Matching is case-insensitive because a person
|
| 368 |
+
// should not have to match a label's capitalisation; the MESSAGE quotes them exactly.
|
| 369 |
+
if (typed && !known.has(norm(typed))) return typed;
|
| 370 |
+
}
|
| 371 |
+
return null;
|
| 372 |
+
}
|
| 373 |
+
|
| 374 |
+
/** The plain-language field list, for a question the panel can answer with no model call at all. */
|
| 375 |
+
export function schemaSentence(schema: GridChatField[], databaseLabel: string): string {
|
| 376 |
+
const where = String(databaseLabel || "").trim() || "this database";
|
| 377 |
+
const names = (schema || []).map((f) => f.label || f.key).filter(Boolean);
|
| 378 |
+
if (!names.length) return where + " has no fields the chat can see.";
|
| 379 |
+
const word = names.length === 1 ? "field" : "fields";
|
| 380 |
+
return where + " has " + names.length + " " + word + ": " + names.join(", ") + ".";
|
| 381 |
+
}
|
| 382 |
+
|
| 383 |
+
/** Sentences that are asking what is here, rather than asking about the data. */
|
| 384 |
+
const SCHEMA_WORDS = ["what fields", "which fields", "what columns", "which columns",
|
| 385 |
+
"list the fields", "list the columns", "what can you see"];
|
| 386 |
+
/** Sentences asking for the VIEW to change rather than for an answer. */
|
| 387 |
+
const VIEW_WORDS = ["sort by", "sorted by", "group by", "grouped by", "colour by", "color by",
|
| 388 |
+
"show me only", "filter"];
|
| 389 |
+
/** Sentences asking for code. */
|
| 390 |
+
const SCRIPT_WORDS = ["build me", "make me", "write a script", "custom view", "dashboard",
|
| 391 |
+
"calculator", "chart"];
|
| 392 |
+
|
| 393 |
+
/**
|
| 394 |
+
* Read a sentence. β THE ORDER IS THE POLICY: refuse first, answer locally second, route third.
|
| 395 |
+
*
|
| 396 |
+
* β A DELIBERATELY SHALLOW READER. It is not trying to understand the question, because the host's
|
| 397 |
+
* model does that. It is trying to catch the two cases where going to the model is WRONG: a name
|
| 398 |
+
* this database does not have (which would come back as an invented number), and a question the
|
| 399 |
+
* panel already knows the answer to (which would be a paid round trip for a list it is holding).
|
| 400 |
+
*/
|
| 401 |
+
export function readIntent(
|
| 402 |
+
schema: GridChatField[],
|
| 403 |
+
databaseLabel: string,
|
| 404 |
+
said: string,
|
| 405 |
+
): GridChatIntent {
|
| 406 |
+
const text = norm(said);
|
| 407 |
+
const where = String(databaseLabel || "").trim() || "this database";
|
| 408 |
+
const missing = unknownFieldNamed(schema, said);
|
| 409 |
+
if (missing) {
|
| 410 |
+
const names = (schema || []).map((f) => f.label || f.key).filter(Boolean);
|
| 411 |
+
return {
|
| 412 |
+
kind: "ask",
|
| 413 |
+
refusal: 'There is no field called "' + missing + '" in ' + where + ". "
|
| 414 |
+
+ (names.length
|
| 415 |
+
? "The fields here are: " + names.join(", ") + "."
|
| 416 |
+
: "This database has no fields the chat can see."),
|
| 417 |
+
};
|
| 418 |
+
}
|
| 419 |
+
if (SCHEMA_WORDS.some((w) => text.includes(w)))
|
| 420 |
+
return { kind: "schema", localAnswer: schemaSentence(schema, databaseLabel) };
|
| 421 |
+
|
| 422 |
+
if (VIEW_WORDS.some((w) => text.includes(w))) {
|
| 423 |
+
const named = fieldsNamed(schema, said);
|
| 424 |
+
const view: { sortBy?: string; groupBy?: string; colorBy?: string } = {};
|
| 425 |
+
if (named.length) {
|
| 426 |
+
if (text.includes("group")) view.groupBy = named[0].key;
|
| 427 |
+
else if (text.includes("colour") || text.includes("color")) view.colorBy = named[0].key;
|
| 428 |
+
else if (text.includes("sort")) view.sortBy = named[0].key;
|
| 429 |
+
}
|
| 430 |
+
// β WHAT IT CANNOT SAY, SAID OUT LOUD. `assistant build_view` has no `rhs` in its tool schema,
|
| 431 |
+
// so a condition comparing one field to another is not expressible anywhere in this product
|
| 432 |
+
// [[assistant-build-view-is-a-subset]]. Dropping it silently would leave a person looking at a
|
| 433 |
+
// view that quietly ignored half their sentence, which is the failure this note exists to stop.
|
| 434 |
+
const fieldVsField = named.length >= 2 && /\b(than|versus|vs\.?|compared to)\b/.test(text);
|
| 435 |
+
return {
|
| 436 |
+
kind: "view",
|
| 437 |
+
view: Object.keys(view).length ? view : undefined,
|
| 438 |
+
cannot: fieldVsField
|
| 439 |
+
? "This build cannot compare one field against another in a view filter, so that part was "
|
| 440 |
+
+ "left out. Everything else was applied."
|
| 441 |
+
: undefined,
|
| 442 |
+
};
|
| 443 |
+
}
|
| 444 |
+
if (SCRIPT_WORDS.some((w) => text.includes(w))) return { kind: "script" };
|
| 445 |
+
return { kind: "ask" };
|
| 446 |
+
}
|
| 447 |
+
|
| 448 |
+
/**
|
| 449 |
+
* The sentence shown when a script the chat wrote is run.
|
| 450 |
+
*
|
| 451 |
+
* β THE VIEW IS NOT BLANKED ON FAILURE (W37-T44's own `done-when`). A script that raised is a fact
|
| 452 |
+
* about the code, and the code is still there to be edited; replacing the panel with nothing would
|
| 453 |
+
* take away the one thing the person needs in order to fix it.
|
| 454 |
+
*/
|
| 455 |
+
export function runSentence(result: GridChatRunResult): string {
|
| 456 |
+
if (result && result.ok) return "That ran. The view is showing what it drew.";
|
| 457 |
+
const why = String((result && result.error) || "").trim();
|
| 458 |
+
return why
|
| 459 |
+
? "That script did not run: " + why + " The code is still in the editor, so you can change it."
|
| 460 |
+
: "That script did not produce a view. The code is still in the editor, so you can change it.";
|
| 461 |
+
}
|
web/src/customer-grid/scriptView.css
CHANGED
|
@@ -1,509 +1,509 @@
|
|
| 1 |
-
/* customer-grid/scriptView.css β owner item 6, the code-script View.
|
| 2 |
-
*
|
| 3 |
-
* β MODULE-LOCAL BY RULING, not by preference. `index.css` is a 12k-line shared file and this
|
| 4 |
-
* wave's PRD hands it to ONE session; a new surface that grew it would be three lanes editing the
|
| 5 |
-
* monolith at once. It is also item 13's smallest real win: the monolith stops growing.
|
| 6 |
-
* β Colours come from the design tokens (navy #1F4E78 + gold #C8A24B, DESIGN.md), never from
|
| 7 |
-
* fresh hexes: a surface that invents its own palette is the thing the constitution exists to
|
| 8 |
-
* prevent. Only the tokens this file actually uses are named. */
|
| 9 |
-
|
| 10 |
-
.cg-script {
|
| 11 |
-
display: flex;
|
| 12 |
-
flex-direction: column;
|
| 13 |
-
height: 100%;
|
| 14 |
-
min-height: 0;
|
| 15 |
-
background: var(--lp-surface, #ffffff);
|
| 16 |
-
}
|
| 17 |
-
|
| 18 |
-
/* The two halves the owner asked for by name: "the code AND the dashboard output of course."
|
| 19 |
-
Side by side above 900px, stacked below it, and the SPLIT is the point either way. */
|
| 20 |
-
.cg-script-body {
|
| 21 |
-
display: grid;
|
| 22 |
-
grid-template-columns: minmax(280px, 5fr) minmax(320px, 7fr);
|
| 23 |
-
gap: 1px;
|
| 24 |
-
flex: 1 1 auto;
|
| 25 |
-
min-height: 0;
|
| 26 |
-
background: var(--lp-border, #e4e7ec);
|
| 27 |
-
}
|
| 28 |
-
@media (max-width: 900px) {
|
| 29 |
-
.cg-script-body { grid-template-columns: 1fr; grid-template-rows: minmax(180px, 2fr) 3fr; }
|
| 30 |
-
}
|
| 31 |
-
|
| 32 |
-
.cg-script-pane {
|
| 33 |
-
display: flex;
|
| 34 |
-
flex-direction: column;
|
| 35 |
-
min-width: 0;
|
| 36 |
-
min-height: 0;
|
| 37 |
-
background: var(--lp-surface, #ffffff);
|
| 38 |
-
}
|
| 39 |
-
|
| 40 |
-
.cg-script-pane-head {
|
| 41 |
-
display: flex;
|
| 42 |
-
align-items: center;
|
| 43 |
-
gap: 8px;
|
| 44 |
-
padding: 8px 12px;
|
| 45 |
-
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 46 |
-
font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 47 |
-
color: var(--lp-text-muted, #667085);
|
| 48 |
-
}
|
| 49 |
-
.cg-script-pane-head .cg-script-spacer { flex: 1 1 auto; }
|
| 50 |
-
|
| 51 |
-
/* β A textarea, not a highlighted editor. A syntax highlighter is a second parser of the same
|
| 52 |
-
source, and the two disagree the first time either learns a token; the owner asked to SEE the
|
| 53 |
-
code, which a monospaced pane does. */
|
| 54 |
-
.cg-script-code {
|
| 55 |
-
flex: 1 1 auto;
|
| 56 |
-
min-height: 0;
|
| 57 |
-
width: 100%;
|
| 58 |
-
resize: none;
|
| 59 |
-
border: 0;
|
| 60 |
-
outline: none;
|
| 61 |
-
padding: 12px;
|
| 62 |
-
font: 400 var(--lp-fs-xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
|
| 63 |
-
color: var(--lp-text, #1d2939);
|
| 64 |
-
background: var(--lp-surface-sunken, #fbfcfd);
|
| 65 |
-
tab-size: 4;
|
| 66 |
-
white-space: pre;
|
| 67 |
-
overflow: auto;
|
| 68 |
-
}
|
| 69 |
-
.cg-script-code:focus-visible { box-shadow: inset 0 0 0 2px var(--lp-navy, #1f4e78); }
|
| 70 |
-
|
| 71 |
-
.cg-script-out {
|
| 72 |
-
flex: 1 1 auto;
|
| 73 |
-
min-height: 0;
|
| 74 |
-
overflow: auto;
|
| 75 |
-
padding: 14px 16px;
|
| 76 |
-
}
|
| 77 |
-
|
| 78 |
-
.cg-script-run {
|
| 79 |
-
display: inline-flex;
|
| 80 |
-
align-items: center;
|
| 81 |
-
gap: 6px;
|
| 82 |
-
height: 26px;
|
| 83 |
-
padding: 0 12px;
|
| 84 |
-
border: 0;
|
| 85 |
-
border-radius: 6px;
|
| 86 |
-
background: var(--lp-navy, #1f4e78);
|
| 87 |
-
color: #ffffff;
|
| 88 |
-
font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
|
| 89 |
-
cursor: pointer;
|
| 90 |
-
}
|
| 91 |
-
.cg-script-run:disabled { opacity: 0.55; cursor: default; }
|
| 92 |
-
.cg-script-ghost {
|
| 93 |
-
height: 26px;
|
| 94 |
-
padding: 0 10px;
|
| 95 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 96 |
-
border-radius: 6px;
|
| 97 |
-
background: transparent;
|
| 98 |
-
color: var(--lp-text, #1d2939);
|
| 99 |
-
font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
|
| 100 |
-
cursor: pointer;
|
| 101 |
-
}
|
| 102 |
-
.cg-script-ghost:disabled { opacity: 0.5; cursor: default; }
|
| 103 |
-
|
| 104 |
-
.cg-script-meta {
|
| 105 |
-
font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
|
| 106 |
-
color: var(--lp-text-muted, #667085);
|
| 107 |
-
}
|
| 108 |
-
|
| 109 |
-
/* A refusal is CONTENT, not a toast: the reader asked a question and this is the answer, so it
|
| 110 |
-
stays on screen next to the code that caused it. */
|
| 111 |
-
.cg-script-refusal {
|
| 112 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 113 |
-
border-left: 3px solid var(--lp-gold, #c8a24b);
|
| 114 |
-
border-radius: 6px;
|
| 115 |
-
padding: 12px 14px;
|
| 116 |
-
background: var(--lp-surface-sunken, #fbfcfd);
|
| 117 |
-
}
|
| 118 |
-
.cg-script-refusal h4 {
|
| 119 |
-
margin: 0 0 6px;
|
| 120 |
-
font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
|
| 121 |
-
color: var(--lp-text, #1d2939);
|
| 122 |
-
}
|
| 123 |
-
.cg-script-refusal p { margin: 0 0 4px; font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif; }
|
| 124 |
-
.cg-script-refusal dl {
|
| 125 |
-
margin: 8px 0 0;
|
| 126 |
-
display: grid;
|
| 127 |
-
grid-template-columns: auto 1fr;
|
| 128 |
-
gap: 2px 10px;
|
| 129 |
-
font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
|
| 130 |
-
}
|
| 131 |
-
.cg-script-refusal dt { color: var(--lp-text-muted, #667085); }
|
| 132 |
-
.cg-script-refusal dd { margin: 0; }
|
| 133 |
-
|
| 134 |
-
.cg-script-title {
|
| 135 |
-
margin: 0 0 10px;
|
| 136 |
-
font: 600 var(--lp-fs-sm)/1.4 Inter, system-ui, sans-serif;
|
| 137 |
-
color: var(--lp-text, #1d2939);
|
| 138 |
-
}
|
| 139 |
-
|
| 140 |
-
.cg-script-table { width: 100%; border-collapse: collapse; }
|
| 141 |
-
.cg-script-table th,
|
| 142 |
-
.cg-script-table td {
|
| 143 |
-
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 144 |
-
padding: 6px 10px;
|
| 145 |
-
text-align: left;
|
| 146 |
-
font: 400 var(--lp-fs-xs)/1.5 Inter, system-ui, sans-serif;
|
| 147 |
-
vertical-align: top;
|
| 148 |
-
}
|
| 149 |
-
.cg-script-table th {
|
| 150 |
-
font-weight: 600;
|
| 151 |
-
color: var(--lp-text-muted, #667085);
|
| 152 |
-
position: sticky;
|
| 153 |
-
top: 0;
|
| 154 |
-
background: var(--lp-surface, #ffffff);
|
| 155 |
-
}
|
| 156 |
-
|
| 157 |
-
.cg-script-metrics {
|
| 158 |
-
display: grid;
|
| 159 |
-
grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
|
| 160 |
-
gap: 10px;
|
| 161 |
-
}
|
| 162 |
-
.cg-script-metric {
|
| 163 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 164 |
-
border-radius: 8px;
|
| 165 |
-
padding: 10px 12px;
|
| 166 |
-
}
|
| 167 |
-
.cg-script-metric-label {
|
| 168 |
-
font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 169 |
-
color: var(--lp-text-muted, #667085);
|
| 170 |
-
}
|
| 171 |
-
.cg-script-metric-value {
|
| 172 |
-
margin-top: 4px;
|
| 173 |
-
font: 600 var(--lp-fs-lg)/1.2 Inter, system-ui, sans-serif;
|
| 174 |
-
color: var(--lp-text, #1d2939);
|
| 175 |
-
}
|
| 176 |
-
.cg-script-metric-note {
|
| 177 |
-
margin-top: 2px;
|
| 178 |
-
font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 179 |
-
color: var(--lp-text-muted, #667085);
|
| 180 |
-
}
|
| 181 |
-
|
| 182 |
-
.cg-script-bars { display: flex; flex-direction: column; gap: 8px; }
|
| 183 |
-
.cg-script-bar { display: grid; grid-template-columns: minmax(80px, 22%) 1fr auto; gap: 10px;
|
| 184 |
-
align-items: center; font: 400 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; }
|
| 185 |
-
.cg-script-bar-track {
|
| 186 |
-
height: 10px;
|
| 187 |
-
border-radius: 5px;
|
| 188 |
-
background: var(--lp-surface-sunken, #f2f4f7);
|
| 189 |
-
overflow: hidden;
|
| 190 |
-
}
|
| 191 |
-
.cg-script-bar-fill { height: 100%; border-radius: 5px; background: var(--lp-navy, #1f4e78); }
|
| 192 |
-
.cg-script-bar-value { color: var(--lp-text-muted, #667085); font-variant-numeric: tabular-nums; }
|
| 193 |
-
|
| 194 |
-
.cg-script-text {
|
| 195 |
-
margin: 0;
|
| 196 |
-
font: 400 var(--lp-fs-xs)/1.7 Inter, system-ui, sans-serif;
|
| 197 |
-
color: var(--lp-text, #1d2939);
|
| 198 |
-
white-space: pre-wrap;
|
| 199 |
-
word-break: break-word;
|
| 200 |
-
}
|
| 201 |
-
|
| 202 |
-
.cg-script-stdout {
|
| 203 |
-
margin: 14px 0 0;
|
| 204 |
-
padding: 10px 12px;
|
| 205 |
-
border-radius: 6px;
|
| 206 |
-
background: var(--lp-surface-sunken, #fbfcfd);
|
| 207 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 208 |
-
font: 400 var(--lp-fs-3xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
|
| 209 |
-
color: var(--lp-text-muted, #667085);
|
| 210 |
-
white-space: pre-wrap;
|
| 211 |
-
word-break: break-word;
|
| 212 |
-
max-height: 220px;
|
| 213 |
-
overflow: auto;
|
| 214 |
-
}
|
| 215 |
-
|
| 216 |
-
.cg-script-empty {
|
| 217 |
-
font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
|
| 218 |
-
color: var(--lp-text-muted, #667085);
|
| 219 |
-
}
|
| 220 |
-
/* The whole-panel empty state needs its own padding: there is no `.cg-script-out` around it.
|
| 221 |
-
Kept HERE rather than inline, so the renderer's one and only computed style stays the bar
|
| 222 |
-
width, which is arithmetic on a validated number and is asserted as the only one. */
|
| 223 |
-
.cg-script-empty--pad { padding: 16px; }
|
| 224 |
-
|
| 225 |
-
/* βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 226 |
-
W36-T05 β THE VIEW AGENT PANEL, left of the View navigation.
|
| 227 |
-
|
| 228 |
-
β `.cg-agent-panel` IS A CROSS-FENCE CLASS NAME (wiring W8, F's DONE B-3). `index.css` folds
|
| 229 |
-
the main rail on `.shell-root:has(.cg-agent-panel) .shell-side`. Renaming it here silently
|
| 230 |
-
un-folds the rail and leaves 187px of grid at 1440, with nothing going red. Its WIDTH lives
|
| 231 |
-
here because the panel is B's; the FOLD lives in index.css because the rail is F's.
|
| 232 |
-
β ~565px is the reference's own column at 1919px wide, and it is what R14's arithmetic is
|
| 233 |
-
built on: 48 (folded nav) + 565 (this) + 344 (views rail) = 957, leaving 483px of grid.
|
| 234 |
-
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 235 |
-
.cg-agent-panel {
|
| 236 |
-
display: flex;
|
| 237 |
-
flex-direction: column;
|
| 238 |
-
flex: 0 0 565px;
|
| 239 |
-
width: 565px;
|
| 240 |
-
max-width: 46vw;
|
| 241 |
-
min-height: 0;
|
| 242 |
-
border-right: 1px solid var(--lp-border, #e4e7ec);
|
| 243 |
-
background: var(--lp-surface, #ffffff);
|
| 244 |
-
}
|
| 245 |
-
|
| 246 |
-
.cg-agent-head {
|
| 247 |
-
display: flex;
|
| 248 |
-
align-items: center;
|
| 249 |
-
gap: 8px;
|
| 250 |
-
padding: 10px 14px;
|
| 251 |
-
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 252 |
-
}
|
| 253 |
-
.cg-agent-title { font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; color: var(--lp-text, #1d2939); }
|
| 254 |
-
.cg-agent-spacer { flex: 1 1 auto; }
|
| 255 |
-
.cg-agent-icon {
|
| 256 |
-
display: inline-flex;
|
| 257 |
-
align-items: center;
|
| 258 |
-
justify-content: center;
|
| 259 |
-
width: 26px;
|
| 260 |
-
height: 26px;
|
| 261 |
-
border: 0;
|
| 262 |
-
border-radius: 6px;
|
| 263 |
-
background: transparent;
|
| 264 |
-
color: var(--lp-text-muted, #667085);
|
| 265 |
-
cursor: pointer;
|
| 266 |
-
}
|
| 267 |
-
.cg-agent-icon:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 268 |
-
|
| 269 |
-
.cg-agent-body { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 16px; }
|
| 270 |
-
|
| 271 |
-
/* The empty state: centred, one soft mark, one question. Whitespace is the design. */
|
| 272 |
-
.cg-agent-empty {
|
| 273 |
-
height: 100%;
|
| 274 |
-
display: flex;
|
| 275 |
-
flex-direction: column;
|
| 276 |
-
align-items: center;
|
| 277 |
-
justify-content: center;
|
| 278 |
-
gap: 14px;
|
| 279 |
-
}
|
| 280 |
-
.cg-agent-mark {
|
| 281 |
-
width: 54px;
|
| 282 |
-
height: 54px;
|
| 283 |
-
border-radius: 50%;
|
| 284 |
-
border: 2px dotted var(--lp-gold, #c8a24b);
|
| 285 |
-
opacity: 0.55;
|
| 286 |
-
}
|
| 287 |
-
.cg-agent-ask {
|
| 288 |
-
margin: 0;
|
| 289 |
-
font: 500 var(--lp-fs-md)/1.4 Inter, system-ui, sans-serif;
|
| 290 |
-
color: var(--lp-text-muted, #667085);
|
| 291 |
-
}
|
| 292 |
-
|
| 293 |
-
.cg-agent-listhead {
|
| 294 |
-
margin: 0 0 8px;
|
| 295 |
-
font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 296 |
-
color: var(--lp-text-muted, #667085);
|
| 297 |
-
}
|
| 298 |
-
.cg-agent-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column;
|
| 299 |
-
gap: 4px; }
|
| 300 |
-
/* The suggestion row from the reference: icon tile, bold title, muted subtitle, an arrow right. */
|
| 301 |
-
.cg-agent-row {
|
| 302 |
-
display: flex;
|
| 303 |
-
align-items: center;
|
| 304 |
-
gap: 10px;
|
| 305 |
-
width: 100%;
|
| 306 |
-
padding: 8px 10px;
|
| 307 |
-
border: 0;
|
| 308 |
-
border-radius: 8px;
|
| 309 |
-
background: transparent;
|
| 310 |
-
text-align: left;
|
| 311 |
-
cursor: pointer;
|
| 312 |
-
}
|
| 313 |
-
.cg-agent-row:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 314 |
-
.cg-agent-row-tile {
|
| 315 |
-
display: inline-flex;
|
| 316 |
-
align-items: center;
|
| 317 |
-
justify-content: center;
|
| 318 |
-
width: 28px;
|
| 319 |
-
height: 28px;
|
| 320 |
-
flex: 0 0 28px;
|
| 321 |
-
border-radius: 7px;
|
| 322 |
-
background: var(--lp-surface-sunken, #f2f4f7);
|
| 323 |
-
color: var(--lp-navy, #1f4e78);
|
| 324 |
-
}
|
| 325 |
-
.cg-agent-row-text { display: flex; flex-direction: column; min-width: 0; flex: 1 1 auto; }
|
| 326 |
-
.cg-agent-row-title {
|
| 327 |
-
font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
|
| 328 |
-
color: var(--lp-text, #1d2939);
|
| 329 |
-
overflow: hidden;
|
| 330 |
-
text-overflow: ellipsis;
|
| 331 |
-
white-space: nowrap;
|
| 332 |
-
}
|
| 333 |
-
.cg-agent-row-sub {
|
| 334 |
-
font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 335 |
-
color: var(--lp-text-muted, #667085);
|
| 336 |
-
}
|
| 337 |
-
.cg-agent-row-go { color: var(--lp-text-muted, #667085); }
|
| 338 |
-
|
| 339 |
-
.cg-agent-error {
|
| 340 |
-
margin: 12px 0 0;
|
| 341 |
-
font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
|
| 342 |
-
color: var(--lp-text, #1d2939);
|
| 343 |
-
border-left: 3px solid var(--lp-gold, #c8a24b);
|
| 344 |
-
padding-left: 10px;
|
| 345 |
-
}
|
| 346 |
-
|
| 347 |
-
/* ONE card border around the input AND its affordances, which is what the reference does. */
|
| 348 |
-
.cg-agent-composer {
|
| 349 |
-
margin: 0 16px;
|
| 350 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 351 |
-
border-radius: 12px;
|
| 352 |
-
background: var(--lp-surface, #ffffff);
|
| 353 |
-
}
|
| 354 |
-
.cg-agent-input {
|
| 355 |
-
display: block;
|
| 356 |
-
width: 100%;
|
| 357 |
-
border: 0;
|
| 358 |
-
outline: none;
|
| 359 |
-
resize: none;
|
| 360 |
-
padding: 12px 14px 6px;
|
| 361 |
-
background: transparent;
|
| 362 |
-
font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
|
| 363 |
-
color: var(--lp-text, #1d2939);
|
| 364 |
-
}
|
| 365 |
-
.cg-agent-composer:focus-within { border-color: var(--lp-navy, #1f4e78); }
|
| 366 |
-
.cg-agent-composer-foot {
|
| 367 |
-
display: flex;
|
| 368 |
-
align-items: center;
|
| 369 |
-
gap: 8px;
|
| 370 |
-
padding: 6px 8px 8px 12px;
|
| 371 |
-
}
|
| 372 |
-
.cg-agent-pill {
|
| 373 |
-
font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 374 |
-
color: var(--lp-text-muted, #667085);
|
| 375 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 376 |
-
border-radius: 999px;
|
| 377 |
-
padding: 3px 9px;
|
| 378 |
-
}
|
| 379 |
-
.cg-agent-send {
|
| 380 |
-
display: inline-flex;
|
| 381 |
-
align-items: center;
|
| 382 |
-
justify-content: center;
|
| 383 |
-
width: 30px;
|
| 384 |
-
height: 30px;
|
| 385 |
-
border: 0;
|
| 386 |
-
border-radius: 50%;
|
| 387 |
-
background: var(--lp-navy, #1f4e78);
|
| 388 |
-
color: #ffffff;
|
| 389 |
-
cursor: pointer;
|
| 390 |
-
}
|
| 391 |
-
.cg-agent-send:disabled { opacity: 0.4; cursor: default; }
|
| 392 |
-
|
| 393 |
-
.cg-agent-foot {
|
| 394 |
-
margin: 8px 16px 14px;
|
| 395 |
-
font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
|
| 396 |
-
color: var(--lp-text-muted, #667085);
|
| 397 |
-
}
|
| 398 |
-
|
| 399 |
-
/* The robot, beside the views rail's own minimize toggle (W35-T28 keeps that one FIRST). */
|
| 400 |
-
.cg-agent-open {
|
| 401 |
-
display: inline-flex;
|
| 402 |
-
align-items: center;
|
| 403 |
-
justify-content: center;
|
| 404 |
-
width: 26px;
|
| 405 |
-
height: 26px;
|
| 406 |
-
border: 0;
|
| 407 |
-
border-radius: 6px;
|
| 408 |
-
background: transparent;
|
| 409 |
-
color: var(--lp-text-muted, #667085);
|
| 410 |
-
cursor: pointer;
|
| 411 |
-
}
|
| 412 |
-
.cg-agent-open:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 413 |
-
.cg-agent-open.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
|
| 414 |
-
|
| 415 |
-
/* βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 416 |
-
W36-T07 β THE FIELD AGENT, inside the column menu's create pane.
|
| 417 |
-
β It reuses the `cg-agent-*` composer above rather than growing a second chat look. What is
|
| 418 |
-
added here is only what a conversation inside a 320px menu needs that a full-height panel
|
| 419 |
-
does not: a bounded scroll, a proposal card, and the two-button accept row.
|
| 420 |
-
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 421 |
-
.cg-fagent { display: flex; flex-direction: column; gap: 10px; min-width: 0; }
|
| 422 |
-
.cg-fagent-body { max-height: 320px; overflow: auto; }
|
| 423 |
-
.cg-fagent-turns { list-style: none; margin: 0 0 10px; padding: 0; display: flex;
|
| 424 |
-
flex-direction: column; gap: 6px; }
|
| 425 |
-
.cg-fagent-turn { display: flex; justify-content: flex-end; }
|
| 426 |
-
.cg-fagent-said {
|
| 427 |
-
max-width: 88%;
|
| 428 |
-
padding: 6px 10px;
|
| 429 |
-
border-radius: 10px 10px 2px 10px;
|
| 430 |
-
background: var(--lp-surface-sunken, #f2f4f7);
|
| 431 |
-
font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
|
| 432 |
-
color: var(--lp-text, #1d2939);
|
| 433 |
-
word-break: break-word;
|
| 434 |
-
}
|
| 435 |
-
.cg-fagent-card {
|
| 436 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 437 |
-
border-left: 3px solid var(--lp-gold, #c8a24b);
|
| 438 |
-
border-radius: 8px;
|
| 439 |
-
padding: 10px 12px;
|
| 440 |
-
}
|
| 441 |
-
.cg-fagent-card-head {
|
| 442 |
-
margin: 0 0 6px;
|
| 443 |
-
font: 600 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 444 |
-
color: var(--lp-text, #1d2939);
|
| 445 |
-
}
|
| 446 |
-
.cg-fagent-def {
|
| 447 |
-
margin: 0;
|
| 448 |
-
display: grid;
|
| 449 |
-
grid-template-columns: auto 1fr;
|
| 450 |
-
gap: 2px 10px;
|
| 451 |
-
font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
|
| 452 |
-
}
|
| 453 |
-
.cg-fagent-def dt { color: var(--lp-text-muted, #667085); }
|
| 454 |
-
.cg-fagent-def dd { margin: 0; color: var(--lp-text, #1d2939); }
|
| 455 |
-
.cg-fagent-why,
|
| 456 |
-
.cg-fagent-missing {
|
| 457 |
-
margin: 8px 0 0;
|
| 458 |
-
padding-left: 16px;
|
| 459 |
-
font: 400 var(--lp-fs-3xs)/1.55 Inter, system-ui, sans-serif;
|
| 460 |
-
color: var(--lp-text-muted, #667085);
|
| 461 |
-
}
|
| 462 |
-
/* What is still OPEN reads differently from what was decided: the reader has to answer these. */
|
| 463 |
-
.cg-fagent-missing { color: var(--lp-text, #1d2939); }
|
| 464 |
-
.cg-fagent-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 10px; }
|
| 465 |
-
/* The agent's door in the create pane. A quiet row, not a second primary button. */
|
| 466 |
-
.cg-fagent-open {
|
| 467 |
-
display: inline-flex;
|
| 468 |
-
align-items: center;
|
| 469 |
-
gap: 6px;
|
| 470 |
-
width: 100%;
|
| 471 |
-
padding: 7px 10px;
|
| 472 |
-
border: 1px dashed var(--lp-border, #e4e7ec);
|
| 473 |
-
border-radius: 8px;
|
| 474 |
-
background: transparent;
|
| 475 |
-
color: var(--lp-text-muted, #667085);
|
| 476 |
-
font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 477 |
-
cursor: pointer;
|
| 478 |
-
}
|
| 479 |
-
.cg-fagent-open:hover { border-color: var(--lp-navy, #1f4e78); color: var(--lp-navy, #1f4e78); }
|
| 480 |
-
|
| 481 |
-
/* ββ W37-T46 / D-338: the roll-back strip βββββββββββββββββββββββββββββββββββ
|
| 482 |
-
β It sits between the head row and the code, where a person looking for "what came before" is
|
| 483 |
-
already looking. A separate panel or a modal would put the history somewhere you have to go
|
| 484 |
-
rather than somewhere you are. */
|
| 485 |
-
.cg-script-history {
|
| 486 |
-
display: flex;
|
| 487 |
-
align-items: center;
|
| 488 |
-
flex-wrap: wrap;
|
| 489 |
-
gap: 6px;
|
| 490 |
-
padding: 6px 12px;
|
| 491 |
-
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 492 |
-
background: var(--lp-surface-sunken, #fbfcfd);
|
| 493 |
-
}
|
| 494 |
-
.cg-script-history-lead,
|
| 495 |
-
.cg-script-history-trimmed {
|
| 496 |
-
font: 400 var(--lp-fs-3xs)/1.3 Inter, system-ui, sans-serif;
|
| 497 |
-
color: var(--lp-text-muted, #667085);
|
| 498 |
-
}
|
| 499 |
-
.cg-script-history-item {
|
| 500 |
-
border: 1px solid var(--lp-border, #e4e7ec);
|
| 501 |
-
border-radius: 6px;
|
| 502 |
-
background: var(--lp-surface, #ffffff);
|
| 503 |
-
color: var(--lp-navy, #1f4e78);
|
| 504 |
-
font: 500 var(--lp-fs-3xs)/1.2 Inter, system-ui, sans-serif;
|
| 505 |
-
padding: 2px 7px;
|
| 506 |
-
cursor: pointer;
|
| 507 |
-
}
|
| 508 |
-
.cg-script-history-item:hover:enabled { border-color: var(--lp-navy, #1f4e78); }
|
| 509 |
-
.cg-script-history-item:disabled { opacity: 0.5; cursor: default; }
|
|
|
|
| 1 |
+
/* customer-grid/scriptView.css β owner item 6, the code-script View.
|
| 2 |
+
*
|
| 3 |
+
* β MODULE-LOCAL BY RULING, not by preference. `index.css` is a 12k-line shared file and this
|
| 4 |
+
* wave's PRD hands it to ONE session; a new surface that grew it would be three lanes editing the
|
| 5 |
+
* monolith at once. It is also item 13's smallest real win: the monolith stops growing.
|
| 6 |
+
* β Colours come from the design tokens (navy #1F4E78 + gold #C8A24B, DESIGN.md), never from
|
| 7 |
+
* fresh hexes: a surface that invents its own palette is the thing the constitution exists to
|
| 8 |
+
* prevent. Only the tokens this file actually uses are named. */
|
| 9 |
+
|
| 10 |
+
.cg-script {
|
| 11 |
+
display: flex;
|
| 12 |
+
flex-direction: column;
|
| 13 |
+
height: 100%;
|
| 14 |
+
min-height: 0;
|
| 15 |
+
background: var(--lp-surface, #ffffff);
|
| 16 |
+
}
|
| 17 |
+
|
| 18 |
+
/* The two halves the owner asked for by name: "the code AND the dashboard output of course."
|
| 19 |
+
Side by side above 900px, stacked below it, and the SPLIT is the point either way. */
|
| 20 |
+
.cg-script-body {
|
| 21 |
+
display: grid;
|
| 22 |
+
grid-template-columns: minmax(280px, 5fr) minmax(320px, 7fr);
|
| 23 |
+
gap: 1px;
|
| 24 |
+
flex: 1 1 auto;
|
| 25 |
+
min-height: 0;
|
| 26 |
+
background: var(--lp-border, #e4e7ec);
|
| 27 |
+
}
|
| 28 |
+
@media (max-width: 900px) {
|
| 29 |
+
.cg-script-body { grid-template-columns: 1fr; grid-template-rows: minmax(180px, 2fr) 3fr; }
|
| 30 |
+
}
|
| 31 |
+
|
| 32 |
+
.cg-script-pane {
|
| 33 |
+
display: flex;
|
| 34 |
+
flex-direction: column;
|
| 35 |
+
min-width: 0;
|
| 36 |
+
min-height: 0;
|
| 37 |
+
background: var(--lp-surface, #ffffff);
|
| 38 |
+
}
|
| 39 |
+
|
| 40 |
+
.cg-script-pane-head {
|
| 41 |
+
display: flex;
|
| 42 |
+
align-items: center;
|
| 43 |
+
gap: 8px;
|
| 44 |
+
padding: 8px 12px;
|
| 45 |
+
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 46 |
+
font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 47 |
+
color: var(--lp-text-muted, #667085);
|
| 48 |
+
}
|
| 49 |
+
.cg-script-pane-head .cg-script-spacer { flex: 1 1 auto; }
|
| 50 |
+
|
| 51 |
+
/* β A textarea, not a highlighted editor. A syntax highlighter is a second parser of the same
|
| 52 |
+
source, and the two disagree the first time either learns a token; the owner asked to SEE the
|
| 53 |
+
code, which a monospaced pane does. */
|
| 54 |
+
.cg-script-code {
|
| 55 |
+
flex: 1 1 auto;
|
| 56 |
+
min-height: 0;
|
| 57 |
+
width: 100%;
|
| 58 |
+
resize: none;
|
| 59 |
+
border: 0;
|
| 60 |
+
outline: none;
|
| 61 |
+
padding: 12px;
|
| 62 |
+
font: 400 var(--lp-fs-xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
|
| 63 |
+
color: var(--lp-text, #1d2939);
|
| 64 |
+
background: var(--lp-surface-sunken, #fbfcfd);
|
| 65 |
+
tab-size: 4;
|
| 66 |
+
white-space: pre;
|
| 67 |
+
overflow: auto;
|
| 68 |
+
}
|
| 69 |
+
.cg-script-code:focus-visible { box-shadow: inset 0 0 0 2px var(--lp-navy, #1f4e78); }
|
| 70 |
+
|
| 71 |
+
.cg-script-out {
|
| 72 |
+
flex: 1 1 auto;
|
| 73 |
+
min-height: 0;
|
| 74 |
+
overflow: auto;
|
| 75 |
+
padding: 14px 16px;
|
| 76 |
+
}
|
| 77 |
+
|
| 78 |
+
.cg-script-run {
|
| 79 |
+
display: inline-flex;
|
| 80 |
+
align-items: center;
|
| 81 |
+
gap: 6px;
|
| 82 |
+
height: 26px;
|
| 83 |
+
padding: 0 12px;
|
| 84 |
+
border: 0;
|
| 85 |
+
border-radius: 6px;
|
| 86 |
+
background: var(--lp-navy, #1f4e78);
|
| 87 |
+
color: #ffffff;
|
| 88 |
+
font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
|
| 89 |
+
cursor: pointer;
|
| 90 |
+
}
|
| 91 |
+
.cg-script-run:disabled { opacity: 0.55; cursor: default; }
|
| 92 |
+
.cg-script-ghost {
|
| 93 |
+
height: 26px;
|
| 94 |
+
padding: 0 10px;
|
| 95 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 96 |
+
border-radius: 6px;
|
| 97 |
+
background: transparent;
|
| 98 |
+
color: var(--lp-text, #1d2939);
|
| 99 |
+
font: 500 var(--lp-fs-2xs)/1 Inter, system-ui, sans-serif;
|
| 100 |
+
cursor: pointer;
|
| 101 |
+
}
|
| 102 |
+
.cg-script-ghost:disabled { opacity: 0.5; cursor: default; }
|
| 103 |
+
|
| 104 |
+
.cg-script-meta {
|
| 105 |
+
font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
|
| 106 |
+
color: var(--lp-text-muted, #667085);
|
| 107 |
+
}
|
| 108 |
+
|
| 109 |
+
/* A refusal is CONTENT, not a toast: the reader asked a question and this is the answer, so it
|
| 110 |
+
stays on screen next to the code that caused it. */
|
| 111 |
+
.cg-script-refusal {
|
| 112 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 113 |
+
border-left: 3px solid var(--lp-gold, #c8a24b);
|
| 114 |
+
border-radius: 6px;
|
| 115 |
+
padding: 12px 14px;
|
| 116 |
+
background: var(--lp-surface-sunken, #fbfcfd);
|
| 117 |
+
}
|
| 118 |
+
.cg-script-refusal h4 {
|
| 119 |
+
margin: 0 0 6px;
|
| 120 |
+
font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
|
| 121 |
+
color: var(--lp-text, #1d2939);
|
| 122 |
+
}
|
| 123 |
+
.cg-script-refusal p { margin: 0 0 4px; font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif; }
|
| 124 |
+
.cg-script-refusal dl {
|
| 125 |
+
margin: 8px 0 0;
|
| 126 |
+
display: grid;
|
| 127 |
+
grid-template-columns: auto 1fr;
|
| 128 |
+
gap: 2px 10px;
|
| 129 |
+
font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
|
| 130 |
+
}
|
| 131 |
+
.cg-script-refusal dt { color: var(--lp-text-muted, #667085); }
|
| 132 |
+
.cg-script-refusal dd { margin: 0; }
|
| 133 |
+
|
| 134 |
+
.cg-script-title {
|
| 135 |
+
margin: 0 0 10px;
|
| 136 |
+
font: 600 var(--lp-fs-sm)/1.4 Inter, system-ui, sans-serif;
|
| 137 |
+
color: var(--lp-text, #1d2939);
|
| 138 |
+
}
|
| 139 |
+
|
| 140 |
+
.cg-script-table { width: 100%; border-collapse: collapse; }
|
| 141 |
+
.cg-script-table th,
|
| 142 |
+
.cg-script-table td {
|
| 143 |
+
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 144 |
+
padding: 6px 10px;
|
| 145 |
+
text-align: left;
|
| 146 |
+
font: 400 var(--lp-fs-xs)/1.5 Inter, system-ui, sans-serif;
|
| 147 |
+
vertical-align: top;
|
| 148 |
+
}
|
| 149 |
+
.cg-script-table th {
|
| 150 |
+
font-weight: 600;
|
| 151 |
+
color: var(--lp-text-muted, #667085);
|
| 152 |
+
position: sticky;
|
| 153 |
+
top: 0;
|
| 154 |
+
background: var(--lp-surface, #ffffff);
|
| 155 |
+
}
|
| 156 |
+
|
| 157 |
+
.cg-script-metrics {
|
| 158 |
+
display: grid;
|
| 159 |
+
grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
|
| 160 |
+
gap: 10px;
|
| 161 |
+
}
|
| 162 |
+
.cg-script-metric {
|
| 163 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 164 |
+
border-radius: 8px;
|
| 165 |
+
padding: 10px 12px;
|
| 166 |
+
}
|
| 167 |
+
.cg-script-metric-label {
|
| 168 |
+
font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 169 |
+
color: var(--lp-text-muted, #667085);
|
| 170 |
+
}
|
| 171 |
+
.cg-script-metric-value {
|
| 172 |
+
margin-top: 4px;
|
| 173 |
+
font: 600 var(--lp-fs-lg)/1.2 Inter, system-ui, sans-serif;
|
| 174 |
+
color: var(--lp-text, #1d2939);
|
| 175 |
+
}
|
| 176 |
+
.cg-script-metric-note {
|
| 177 |
+
margin-top: 2px;
|
| 178 |
+
font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 179 |
+
color: var(--lp-text-muted, #667085);
|
| 180 |
+
}
|
| 181 |
+
|
| 182 |
+
.cg-script-bars { display: flex; flex-direction: column; gap: 8px; }
|
| 183 |
+
.cg-script-bar { display: grid; grid-template-columns: minmax(80px, 22%) 1fr auto; gap: 10px;
|
| 184 |
+
align-items: center; font: 400 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; }
|
| 185 |
+
.cg-script-bar-track {
|
| 186 |
+
height: 10px;
|
| 187 |
+
border-radius: 5px;
|
| 188 |
+
background: var(--lp-surface-sunken, #f2f4f7);
|
| 189 |
+
overflow: hidden;
|
| 190 |
+
}
|
| 191 |
+
.cg-script-bar-fill { height: 100%; border-radius: 5px; background: var(--lp-navy, #1f4e78); }
|
| 192 |
+
.cg-script-bar-value { color: var(--lp-text-muted, #667085); font-variant-numeric: tabular-nums; }
|
| 193 |
+
|
| 194 |
+
.cg-script-text {
|
| 195 |
+
margin: 0;
|
| 196 |
+
font: 400 var(--lp-fs-xs)/1.7 Inter, system-ui, sans-serif;
|
| 197 |
+
color: var(--lp-text, #1d2939);
|
| 198 |
+
white-space: pre-wrap;
|
| 199 |
+
word-break: break-word;
|
| 200 |
+
}
|
| 201 |
+
|
| 202 |
+
.cg-script-stdout {
|
| 203 |
+
margin: 14px 0 0;
|
| 204 |
+
padding: 10px 12px;
|
| 205 |
+
border-radius: 6px;
|
| 206 |
+
background: var(--lp-surface-sunken, #fbfcfd);
|
| 207 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 208 |
+
font: 400 var(--lp-fs-3xs)/1.6 "SFMono-Regular", Menlo, Consolas, monospace;
|
| 209 |
+
color: var(--lp-text-muted, #667085);
|
| 210 |
+
white-space: pre-wrap;
|
| 211 |
+
word-break: break-word;
|
| 212 |
+
max-height: 220px;
|
| 213 |
+
overflow: auto;
|
| 214 |
+
}
|
| 215 |
+
|
| 216 |
+
.cg-script-empty {
|
| 217 |
+
font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
|
| 218 |
+
color: var(--lp-text-muted, #667085);
|
| 219 |
+
}
|
| 220 |
+
/* The whole-panel empty state needs its own padding: there is no `.cg-script-out` around it.
|
| 221 |
+
Kept HERE rather than inline, so the renderer's one and only computed style stays the bar
|
| 222 |
+
width, which is arithmetic on a validated number and is asserted as the only one. */
|
| 223 |
+
.cg-script-empty--pad { padding: 16px; }
|
| 224 |
+
|
| 225 |
+
/* βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 226 |
+
W36-T05 β THE VIEW AGENT PANEL, left of the View navigation.
|
| 227 |
+
|
| 228 |
+
β `.cg-agent-panel` IS A CROSS-FENCE CLASS NAME (wiring W8, F's DONE B-3). `index.css` folds
|
| 229 |
+
the main rail on `.shell-root:has(.cg-agent-panel) .shell-side`. Renaming it here silently
|
| 230 |
+
un-folds the rail and leaves 187px of grid at 1440, with nothing going red. Its WIDTH lives
|
| 231 |
+
here because the panel is B's; the FOLD lives in index.css because the rail is F's.
|
| 232 |
+
β ~565px is the reference's own column at 1919px wide, and it is what R14's arithmetic is
|
| 233 |
+
built on: 48 (folded nav) + 565 (this) + 344 (views rail) = 957, leaving 483px of grid.
|
| 234 |
+
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 235 |
+
.cg-agent-panel {
|
| 236 |
+
display: flex;
|
| 237 |
+
flex-direction: column;
|
| 238 |
+
flex: 0 0 565px;
|
| 239 |
+
width: 565px;
|
| 240 |
+
max-width: 46vw;
|
| 241 |
+
min-height: 0;
|
| 242 |
+
border-right: 1px solid var(--lp-border, #e4e7ec);
|
| 243 |
+
background: var(--lp-surface, #ffffff);
|
| 244 |
+
}
|
| 245 |
+
|
| 246 |
+
.cg-agent-head {
|
| 247 |
+
display: flex;
|
| 248 |
+
align-items: center;
|
| 249 |
+
gap: 8px;
|
| 250 |
+
padding: 10px 14px;
|
| 251 |
+
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 252 |
+
}
|
| 253 |
+
.cg-agent-title { font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif; color: var(--lp-text, #1d2939); }
|
| 254 |
+
.cg-agent-spacer { flex: 1 1 auto; }
|
| 255 |
+
.cg-agent-icon {
|
| 256 |
+
display: inline-flex;
|
| 257 |
+
align-items: center;
|
| 258 |
+
justify-content: center;
|
| 259 |
+
width: 26px;
|
| 260 |
+
height: 26px;
|
| 261 |
+
border: 0;
|
| 262 |
+
border-radius: 6px;
|
| 263 |
+
background: transparent;
|
| 264 |
+
color: var(--lp-text-muted, #667085);
|
| 265 |
+
cursor: pointer;
|
| 266 |
+
}
|
| 267 |
+
.cg-agent-icon:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 268 |
+
|
| 269 |
+
.cg-agent-body { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 16px; }
|
| 270 |
+
|
| 271 |
+
/* The empty state: centred, one soft mark, one question. Whitespace is the design. */
|
| 272 |
+
.cg-agent-empty {
|
| 273 |
+
height: 100%;
|
| 274 |
+
display: flex;
|
| 275 |
+
flex-direction: column;
|
| 276 |
+
align-items: center;
|
| 277 |
+
justify-content: center;
|
| 278 |
+
gap: 14px;
|
| 279 |
+
}
|
| 280 |
+
.cg-agent-mark {
|
| 281 |
+
width: 54px;
|
| 282 |
+
height: 54px;
|
| 283 |
+
border-radius: 50%;
|
| 284 |
+
border: 2px dotted var(--lp-gold, #c8a24b);
|
| 285 |
+
opacity: 0.55;
|
| 286 |
+
}
|
| 287 |
+
.cg-agent-ask {
|
| 288 |
+
margin: 0;
|
| 289 |
+
font: 500 var(--lp-fs-md)/1.4 Inter, system-ui, sans-serif;
|
| 290 |
+
color: var(--lp-text-muted, #667085);
|
| 291 |
+
}
|
| 292 |
+
|
| 293 |
+
.cg-agent-listhead {
|
| 294 |
+
margin: 0 0 8px;
|
| 295 |
+
font: 500 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 296 |
+
color: var(--lp-text-muted, #667085);
|
| 297 |
+
}
|
| 298 |
+
.cg-agent-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column;
|
| 299 |
+
gap: 4px; }
|
| 300 |
+
/* The suggestion row from the reference: icon tile, bold title, muted subtitle, an arrow right. */
|
| 301 |
+
.cg-agent-row {
|
| 302 |
+
display: flex;
|
| 303 |
+
align-items: center;
|
| 304 |
+
gap: 10px;
|
| 305 |
+
width: 100%;
|
| 306 |
+
padding: 8px 10px;
|
| 307 |
+
border: 0;
|
| 308 |
+
border-radius: 8px;
|
| 309 |
+
background: transparent;
|
| 310 |
+
text-align: left;
|
| 311 |
+
cursor: pointer;
|
| 312 |
+
}
|
| 313 |
+
.cg-agent-row:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 314 |
+
.cg-agent-row-tile {
|
| 315 |
+
display: inline-flex;
|
| 316 |
+
align-items: center;
|
| 317 |
+
justify-content: center;
|
| 318 |
+
width: 28px;
|
| 319 |
+
height: 28px;
|
| 320 |
+
flex: 0 0 28px;
|
| 321 |
+
border-radius: 7px;
|
| 322 |
+
background: var(--lp-surface-sunken, #f2f4f7);
|
| 323 |
+
color: var(--lp-navy, #1f4e78);
|
| 324 |
+
}
|
| 325 |
+
.cg-agent-row-text { display: flex; flex-direction: column; min-width: 0; flex: 1 1 auto; }
|
| 326 |
+
.cg-agent-row-title {
|
| 327 |
+
font: 600 var(--lp-fs-xs)/1.4 Inter, system-ui, sans-serif;
|
| 328 |
+
color: var(--lp-text, #1d2939);
|
| 329 |
+
overflow: hidden;
|
| 330 |
+
text-overflow: ellipsis;
|
| 331 |
+
white-space: nowrap;
|
| 332 |
+
}
|
| 333 |
+
.cg-agent-row-sub {
|
| 334 |
+
font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 335 |
+
color: var(--lp-text-muted, #667085);
|
| 336 |
+
}
|
| 337 |
+
.cg-agent-row-go { color: var(--lp-text-muted, #667085); }
|
| 338 |
+
|
| 339 |
+
.cg-agent-error {
|
| 340 |
+
margin: 12px 0 0;
|
| 341 |
+
font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
|
| 342 |
+
color: var(--lp-text, #1d2939);
|
| 343 |
+
border-left: 3px solid var(--lp-gold, #c8a24b);
|
| 344 |
+
padding-left: 10px;
|
| 345 |
+
}
|
| 346 |
+
|
| 347 |
+
/* ONE card border around the input AND its affordances, which is what the reference does. */
|
| 348 |
+
.cg-agent-composer {
|
| 349 |
+
margin: 0 16px;
|
| 350 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 351 |
+
border-radius: 12px;
|
| 352 |
+
background: var(--lp-surface, #ffffff);
|
| 353 |
+
}
|
| 354 |
+
.cg-agent-input {
|
| 355 |
+
display: block;
|
| 356 |
+
width: 100%;
|
| 357 |
+
border: 0;
|
| 358 |
+
outline: none;
|
| 359 |
+
resize: none;
|
| 360 |
+
padding: 12px 14px 6px;
|
| 361 |
+
background: transparent;
|
| 362 |
+
font: 400 var(--lp-fs-xs)/1.6 Inter, system-ui, sans-serif;
|
| 363 |
+
color: var(--lp-text, #1d2939);
|
| 364 |
+
}
|
| 365 |
+
.cg-agent-composer:focus-within { border-color: var(--lp-navy, #1f4e78); }
|
| 366 |
+
.cg-agent-composer-foot {
|
| 367 |
+
display: flex;
|
| 368 |
+
align-items: center;
|
| 369 |
+
gap: 8px;
|
| 370 |
+
padding: 6px 8px 8px 12px;
|
| 371 |
+
}
|
| 372 |
+
.cg-agent-pill {
|
| 373 |
+
font: 400 var(--lp-fs-3xs)/1.4 Inter, system-ui, sans-serif;
|
| 374 |
+
color: var(--lp-text-muted, #667085);
|
| 375 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 376 |
+
border-radius: 999px;
|
| 377 |
+
padding: 3px 9px;
|
| 378 |
+
}
|
| 379 |
+
.cg-agent-send {
|
| 380 |
+
display: inline-flex;
|
| 381 |
+
align-items: center;
|
| 382 |
+
justify-content: center;
|
| 383 |
+
width: 30px;
|
| 384 |
+
height: 30px;
|
| 385 |
+
border: 0;
|
| 386 |
+
border-radius: 50%;
|
| 387 |
+
background: var(--lp-navy, #1f4e78);
|
| 388 |
+
color: #ffffff;
|
| 389 |
+
cursor: pointer;
|
| 390 |
+
}
|
| 391 |
+
.cg-agent-send:disabled { opacity: 0.4; cursor: default; }
|
| 392 |
+
|
| 393 |
+
.cg-agent-foot {
|
| 394 |
+
margin: 8px 16px 14px;
|
| 395 |
+
font: 400 var(--lp-fs-3xs)/1.5 Inter, system-ui, sans-serif;
|
| 396 |
+
color: var(--lp-text-muted, #667085);
|
| 397 |
+
}
|
| 398 |
+
|
| 399 |
+
/* The robot, beside the views rail's own minimize toggle (W35-T28 keeps that one FIRST). */
|
| 400 |
+
.cg-agent-open {
|
| 401 |
+
display: inline-flex;
|
| 402 |
+
align-items: center;
|
| 403 |
+
justify-content: center;
|
| 404 |
+
width: 26px;
|
| 405 |
+
height: 26px;
|
| 406 |
+
border: 0;
|
| 407 |
+
border-radius: 6px;
|
| 408 |
+
background: transparent;
|
| 409 |
+
color: var(--lp-text-muted, #667085);
|
| 410 |
+
cursor: pointer;
|
| 411 |
+
}
|
| 412 |
+
.cg-agent-open:hover { background: var(--lp-surface-sunken, #f2f4f7); }
|
| 413 |
+
.cg-agent-open.is-on { background: var(--lp-surface-sunken, #f2f4f7); color: var(--lp-navy, #1f4e78); }
|
| 414 |
+
|
| 415 |
+
/* βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 416 |
+
W36-T07 β THE FIELD AGENT, inside the column menu's create pane.
|
| 417 |
+
β It reuses the `cg-agent-*` composer above rather than growing a second chat look. What is
|
| 418 |
+
added here is only what a conversation inside a 320px menu needs that a full-height panel
|
| 419 |
+
does not: a bounded scroll, a proposal card, and the two-button accept row.
|
| 420 |
+
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ */
|
| 421 |
+
.cg-fagent { display: flex; flex-direction: column; gap: 10px; min-width: 0; }
|
| 422 |
+
.cg-fagent-body { max-height: 320px; overflow: auto; }
|
| 423 |
+
.cg-fagent-turns { list-style: none; margin: 0 0 10px; padding: 0; display: flex;
|
| 424 |
+
flex-direction: column; gap: 6px; }
|
| 425 |
+
.cg-fagent-turn { display: flex; justify-content: flex-end; }
|
| 426 |
+
.cg-fagent-said {
|
| 427 |
+
max-width: 88%;
|
| 428 |
+
padding: 6px 10px;
|
| 429 |
+
border-radius: 10px 10px 2px 10px;
|
| 430 |
+
background: var(--lp-surface-sunken, #f2f4f7);
|
| 431 |
+
font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
|
| 432 |
+
color: var(--lp-text, #1d2939);
|
| 433 |
+
word-break: break-word;
|
| 434 |
+
}
|
| 435 |
+
.cg-fagent-card {
|
| 436 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 437 |
+
border-left: 3px solid var(--lp-gold, #c8a24b);
|
| 438 |
+
border-radius: 8px;
|
| 439 |
+
padding: 10px 12px;
|
| 440 |
+
}
|
| 441 |
+
.cg-fagent-card-head {
|
| 442 |
+
margin: 0 0 6px;
|
| 443 |
+
font: 600 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 444 |
+
color: var(--lp-text, #1d2939);
|
| 445 |
+
}
|
| 446 |
+
.cg-fagent-def {
|
| 447 |
+
margin: 0;
|
| 448 |
+
display: grid;
|
| 449 |
+
grid-template-columns: auto 1fr;
|
| 450 |
+
gap: 2px 10px;
|
| 451 |
+
font: 400 var(--lp-fs-2xs)/1.5 Inter, system-ui, sans-serif;
|
| 452 |
+
}
|
| 453 |
+
.cg-fagent-def dt { color: var(--lp-text-muted, #667085); }
|
| 454 |
+
.cg-fagent-def dd { margin: 0; color: var(--lp-text, #1d2939); }
|
| 455 |
+
.cg-fagent-why,
|
| 456 |
+
.cg-fagent-missing {
|
| 457 |
+
margin: 8px 0 0;
|
| 458 |
+
padding-left: 16px;
|
| 459 |
+
font: 400 var(--lp-fs-3xs)/1.55 Inter, system-ui, sans-serif;
|
| 460 |
+
color: var(--lp-text-muted, #667085);
|
| 461 |
+
}
|
| 462 |
+
/* What is still OPEN reads differently from what was decided: the reader has to answer these. */
|
| 463 |
+
.cg-fagent-missing { color: var(--lp-text, #1d2939); }
|
| 464 |
+
.cg-fagent-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 10px; }
|
| 465 |
+
/* The agent's door in the create pane. A quiet row, not a second primary button. */
|
| 466 |
+
.cg-fagent-open {
|
| 467 |
+
display: inline-flex;
|
| 468 |
+
align-items: center;
|
| 469 |
+
gap: 6px;
|
| 470 |
+
width: 100%;
|
| 471 |
+
padding: 7px 10px;
|
| 472 |
+
border: 1px dashed var(--lp-border, #e4e7ec);
|
| 473 |
+
border-radius: 8px;
|
| 474 |
+
background: transparent;
|
| 475 |
+
color: var(--lp-text-muted, #667085);
|
| 476 |
+
font: 500 var(--lp-fs-2xs)/1.4 Inter, system-ui, sans-serif;
|
| 477 |
+
cursor: pointer;
|
| 478 |
+
}
|
| 479 |
+
.cg-fagent-open:hover { border-color: var(--lp-navy, #1f4e78); color: var(--lp-navy, #1f4e78); }
|
| 480 |
+
|
| 481 |
+
/* ββ W37-T46 / D-338: the roll-back strip βββββββββββββββββββββββββββββββββββ
|
| 482 |
+
β It sits between the head row and the code, where a person looking for "what came before" is
|
| 483 |
+
already looking. A separate panel or a modal would put the history somewhere you have to go
|
| 484 |
+
rather than somewhere you are. */
|
| 485 |
+
.cg-script-history {
|
| 486 |
+
display: flex;
|
| 487 |
+
align-items: center;
|
| 488 |
+
flex-wrap: wrap;
|
| 489 |
+
gap: 6px;
|
| 490 |
+
padding: 6px 12px;
|
| 491 |
+
border-bottom: 1px solid var(--lp-border, #e4e7ec);
|
| 492 |
+
background: var(--lp-surface-sunken, #fbfcfd);
|
| 493 |
+
}
|
| 494 |
+
.cg-script-history-lead,
|
| 495 |
+
.cg-script-history-trimmed {
|
| 496 |
+
font: 400 var(--lp-fs-3xs)/1.3 Inter, system-ui, sans-serif;
|
| 497 |
+
color: var(--lp-text-muted, #667085);
|
| 498 |
+
}
|
| 499 |
+
.cg-script-history-item {
|
| 500 |
+
border: 1px solid var(--lp-border, #e4e7ec);
|
| 501 |
+
border-radius: 6px;
|
| 502 |
+
background: var(--lp-surface, #ffffff);
|
| 503 |
+
color: var(--lp-navy, #1f4e78);
|
| 504 |
+
font: 500 var(--lp-fs-3xs)/1.2 Inter, system-ui, sans-serif;
|
| 505 |
+
padding: 2px 7px;
|
| 506 |
+
cursor: pointer;
|
| 507 |
+
}
|
| 508 |
+
.cg-script-history-item:hover:enabled { border-color: var(--lp-navy, #1f4e78); }
|
| 509 |
+
.cg-script-history-item:disabled { opacity: 0.5; cursor: default; }
|
web/src/customer-grid/scriptViews.ts
CHANGED
|
@@ -1,387 +1,387 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// customer-grid / scriptViews.ts β the CLIENT half of contract C3 (owner item 6).
|
| 3 |
-
//
|
| 4 |
-
// β THE ASK, verbatim: *"Add code script as an interface (database View) so a user can build
|
| 5 |
-
// whatever they want through the Agent chat interface β¦ User should have the ability to see the
|
| 6 |
-
// code AND the dashboard output of course."* E owns the engine
|
| 7 |
-
// (`aios-web/api/routes_script_views.py`, published as C3); this module is the typed door to it
|
| 8 |
-
// and holds no policy of its own.
|
| 9 |
-
//
|
| 10 |
-
// ββ THE ONE RULE THIS WHOLE FEATURE RESTS ON: **a run returns a DECLARATIVE SPEC, never HTML
|
| 11 |
-
// and never a script.** R10 puts the Python in a server sandbox precisely so the browser never
|
| 12 |
-
// has to trust the output; a renderer that then evaluated a string would hand back everything the
|
| 13 |
-
// sandbox was built to contain. So nothing in this module or its renderer interprets a value as
|
| 14 |
-
// code, as markup, as a URL or as CSS. `renderableSpec` below is where that is enforced, and the
|
| 15 |
-
// enforcement is a WHITELIST of scalar leaves rather than a blacklist of dangerous keys β E's
|
| 16 |
-
// server already refuses the dangerous keys at any depth, and two blacklists that must agree is
|
| 17 |
-
// exactly the shape this repo keeps paying for.
|
| 18 |
-
//
|
| 19 |
-
// β R3 β SCOPED, NOT CAPPED. A script view may read only the database it lives in, and there is
|
| 20 |
-
// no limit on how many a database holds (`limits.maxViewsPerDatabase` is `null` ON PURPOSE, so
|
| 21 |
-
// an agent can leave three attempts side by side for the owner to compare). Do not build a
|
| 22 |
-
// "you have reached the limit" state; there is none.
|
| 23 |
-
//
|
| 24 |
-
// β R5 β THE RUN IS THE READER'S SCOPE, NEVER THE AUTHOR'S. The same view opened by two accounts
|
| 25 |
-
// returns two different numbers, correctly. Any cache keyed on the view id alone would show one
|
| 26 |
-
// colleague another's totals, which is why nothing here caches a run at all.
|
| 27 |
-
// ---------------------------------------------------------------------------
|
| 28 |
-
|
| 29 |
-
import { API_V1, CREDENTIALS } from "../apiContract";
|
| 30 |
-
import { refusalMessage } from "./apiBridge";
|
| 31 |
-
|
| 32 |
-
/** One script view as the list endpoint returns it (C3 `row`). */
|
| 33 |
-
export interface ScriptViewRow {
|
| 34 |
-
id: string;
|
| 35 |
-
database: string;
|
| 36 |
-
name: string;
|
| 37 |
-
author: string;
|
| 38 |
-
version: number;
|
| 39 |
-
created: string;
|
| 40 |
-
updated: string;
|
| 41 |
-
versions: number;
|
| 42 |
-
trimmed: number;
|
| 43 |
-
/**
|
| 44 |
-
* β W37-T46 / D-338 β which version this one was RESTORED from, if it was.
|
| 45 |
-
* β OPTIONAL BECAUSE MOST VERSIONS WERE NOT A ROLL-BACK, not because the server might forget to
|
| 46 |
-
* send it. A view saved normally has no such fact, and `undefined` is that absence rather than a
|
| 47 |
-
* missing field: rendering "restored from v0" for an ordinary save would be a lie about history.
|
| 48 |
-
*/
|
| 49 |
-
restoredFrom?: number | null;
|
| 50 |
-
}
|
| 51 |
-
|
| 52 |
-
/** One version in a view's history. Newest first, per C3. */
|
| 53 |
-
export interface ScriptViewVersion {
|
| 54 |
-
version: number;
|
| 55 |
-
author: string;
|
| 56 |
-
created: string;
|
| 57 |
-
bytes: number;
|
| 58 |
-
}
|
| 59 |
-
|
| 60 |
-
/** A single view read (C3 `view`): the row, plus the source and its history. */
|
| 61 |
-
export interface ScriptView extends ScriptViewRow {
|
| 62 |
-
source: string;
|
| 63 |
-
history: ScriptViewVersion[];
|
| 64 |
-
}
|
| 65 |
-
|
| 66 |
-
/** C3's `limits` envelope. β `maxViewsPerDatabase` is `null` by ruling R3, not by omission. */
|
| 67 |
-
export interface ScriptLimits {
|
| 68 |
-
maxSourceBytes: number;
|
| 69 |
-
maxName: number;
|
| 70 |
-
maxHistory: number;
|
| 71 |
-
maxConcurrentRuns: number;
|
| 72 |
-
maxViewsPerDatabase: number | null;
|
| 73 |
-
}
|
| 74 |
-
|
| 75 |
-
/**
|
| 76 |
-
* What a run answers.
|
| 77 |
-
*
|
| 78 |
-
* β `ok: false` IS A 200 (E's own note, and it is the half a caller gets wrong). A script that
|
| 79 |
-
* timed out, refused an import or divided by zero is a well-formed request whose ANSWER is that
|
| 80 |
-
* no view was produced. It is rendered, not thrown.
|
| 81 |
-
*/
|
| 82 |
-
export interface ScriptRun {
|
| 83 |
-
ok: boolean;
|
| 84 |
-
spec?: unknown;
|
| 85 |
-
stdout: string;
|
| 86 |
-
truncated: boolean;
|
| 87 |
-
ms: number;
|
| 88 |
-
code: string;
|
| 89 |
-
caps: { wallClock: boolean; memory: boolean; cpu: boolean };
|
| 90 |
-
error?: string;
|
| 91 |
-
/** Only on a 409: the four fields are PRINTED, never re-worded (standing rule 1's second half). */
|
| 92 |
-
limit?: { subject: string; effect: string; cause: string; recommendation: string };
|
| 93 |
-
}
|
| 94 |
-
|
| 95 |
-
/** The three codes that are real HTTP statuses rather than script outcomes (C1's wall). */
|
| 96 |
-
export type ScriptTransport = "not_found" | "forbidden" | "unavailable" | "unreachable";
|
| 97 |
-
|
| 98 |
-
async function body(res: Response): Promise<unknown> {
|
| 99 |
-
try {
|
| 100 |
-
return await res.json();
|
| 101 |
-
} catch {
|
| 102 |
-
return null;
|
| 103 |
-
}
|
| 104 |
-
}
|
| 105 |
-
|
| 106 |
-
/**
|
| 107 |
-
* A transport failure, turned into the same envelope a refused RUN uses, so every caller has one
|
| 108 |
-
* shape to render. β Not an exception: a 403 on a database somebody just lost access to is an
|
| 109 |
-
* ordinary answer to an ordinary question, and a throw here would blank a working surface.
|
| 110 |
-
*/
|
| 111 |
-
function transportRun(res: Response, payload: unknown): ScriptRun {
|
| 112 |
-
const code: ScriptTransport =
|
| 113 |
-
res.status === 404 ? "not_found" : res.status === 403 ? "forbidden" : "unavailable";
|
| 114 |
-
const shaped = payload as { error?: { limit?: ScriptRun["limit"] } } | null;
|
| 115 |
-
const out: ScriptRun = {
|
| 116 |
-
ok: false,
|
| 117 |
-
stdout: "",
|
| 118 |
-
truncated: false,
|
| 119 |
-
ms: 0,
|
| 120 |
-
code,
|
| 121 |
-
caps: { wallClock: false, memory: false, cpu: false },
|
| 122 |
-
error: refusalMessage(payload, res.status, TRANSPORT_TEXT[code]),
|
| 123 |
-
};
|
| 124 |
-
const limit = shaped?.error?.limit;
|
| 125 |
-
if (limit) out.limit = limit;
|
| 126 |
-
return out;
|
| 127 |
-
}
|
| 128 |
-
|
| 129 |
-
/** β No dash of any kind: these strings reach a screen (standing rule 2). */
|
| 130 |
-
const TRANSPORT_TEXT: Record<ScriptTransport, string> = {
|
| 131 |
-
not_found: "This database no longer exists, so its scripts cannot run.",
|
| 132 |
-
forbidden: "You do not have access to this database, so its scripts cannot run.",
|
| 133 |
-
unavailable: "This database cannot be served right now, so its scripts cannot run.",
|
| 134 |
-
unreachable: "The server could not be reached, so nothing was run.",
|
| 135 |
-
};
|
| 136 |
-
|
| 137 |
-
export const DEFAULT_SCRIPT_LIMITS: ScriptLimits = {
|
| 138 |
-
maxSourceBytes: 131_072,
|
| 139 |
-
maxName: 80,
|
| 140 |
-
maxHistory: 40,
|
| 141 |
-
maxConcurrentRuns: 4,
|
| 142 |
-
maxViewsPerDatabase: null,
|
| 143 |
-
};
|
| 144 |
-
|
| 145 |
-
export async function listScriptViews(
|
| 146 |
-
database: string
|
| 147 |
-
): Promise<{ views: ScriptViewRow[]; limits: ScriptLimits; error?: string }> {
|
| 148 |
-
let res: Response;
|
| 149 |
-
try {
|
| 150 |
-
res = await fetch(`${API_V1}/script-views?database=${encodeURIComponent(database)}`,
|
| 151 |
-
{ credentials: CREDENTIALS });
|
| 152 |
-
} catch {
|
| 153 |
-
return { views: [], limits: DEFAULT_SCRIPT_LIMITS, error: TRANSPORT_TEXT.unreachable };
|
| 154 |
-
}
|
| 155 |
-
const payload = await body(res);
|
| 156 |
-
if (!res.ok)
|
| 157 |
-
return { views: [], limits: DEFAULT_SCRIPT_LIMITS,
|
| 158 |
-
error: refusalMessage(payload, res.status, TRANSPORT_TEXT.unavailable) };
|
| 159 |
-
const shaped = payload as { views?: ScriptViewRow[]; limits?: ScriptLimits } | null;
|
| 160 |
-
return { views: Array.isArray(shaped?.views) ? shaped.views : [],
|
| 161 |
-
limits: shaped?.limits ?? DEFAULT_SCRIPT_LIMITS };
|
| 162 |
-
}
|
| 163 |
-
|
| 164 |
-
export async function readScriptView(
|
| 165 |
-
id: string
|
| 166 |
-
): Promise<{ view: ScriptView | null; error?: string }> {
|
| 167 |
-
let res: Response;
|
| 168 |
-
try {
|
| 169 |
-
res = await fetch(`${API_V1}/script-views/${encodeURIComponent(id)}`,
|
| 170 |
-
{ credentials: CREDENTIALS });
|
| 171 |
-
} catch {
|
| 172 |
-
return { view: null, error: TRANSPORT_TEXT.unreachable };
|
| 173 |
-
}
|
| 174 |
-
const payload = await body(res);
|
| 175 |
-
if (!res.ok)
|
| 176 |
-
return { view: null, error: refusalMessage(payload, res.status, TRANSPORT_TEXT.unavailable) };
|
| 177 |
-
const shaped = payload as { view?: ScriptView } | null;
|
| 178 |
-
return { view: shaped?.view ?? null };
|
| 179 |
-
}
|
| 180 |
-
|
| 181 |
-
async function write(
|
| 182 |
-
path: string, method: "POST" | "PUT", payload: Record<string, unknown>
|
| 183 |
-
): Promise<{ view: ScriptView | null; error?: string }> {
|
| 184 |
-
let res: Response;
|
| 185 |
-
try {
|
| 186 |
-
res = await fetch(`${API_V1}${path}`, {
|
| 187 |
-
method,
|
| 188 |
-
credentials: CREDENTIALS,
|
| 189 |
-
headers: { "Content-Type": "application/json" },
|
| 190 |
-
body: JSON.stringify(payload),
|
| 191 |
-
});
|
| 192 |
-
} catch {
|
| 193 |
-
return { view: null, error: TRANSPORT_TEXT.unreachable };
|
| 194 |
-
}
|
| 195 |
-
const answer = await body(res);
|
| 196 |
-
if (!res.ok)
|
| 197 |
-
return { view: null, error: refusalMessage(answer, res.status, TRANSPORT_TEXT.unavailable) };
|
| 198 |
-
const shaped = answer as { view?: ScriptView } | null;
|
| 199 |
-
return { view: shaped?.view ?? null };
|
| 200 |
-
}
|
| 201 |
-
|
| 202 |
-
export function createScriptView(database: string, source: string, name?: string) {
|
| 203 |
-
return write("/script-views", "POST",
|
| 204 |
-
name === undefined ? { database, source } : { database, source, name });
|
| 205 |
-
}
|
| 206 |
-
|
| 207 |
-
/** β A PUT is a NEW VERSION, never an overwrite (R8's shape, applied to scripts). */
|
| 208 |
-
export function saveScriptView(id: string, source: string, name?: string) {
|
| 209 |
-
return write(`/script-views/${encodeURIComponent(id)}`, "PUT",
|
| 210 |
-
name === undefined ? { source } : { source, name });
|
| 211 |
-
}
|
| 212 |
-
|
| 213 |
-
/**
|
| 214 |
-
* ββ W37-T46 / D-338 β GO BACK TO AN EARLIER VERSION, AND IT IS A NEW VERSION.
|
| 215 |
-
*
|
| 216 |
-
* The API already RETURNED `history` newest-first and the editor already showed `v<n>`; there was
|
| 217 |
-
* simply no control, which is D-338 in one sentence. This matters more now that a chat writes the
|
| 218 |
-
* code (R2): generation without roll-back means one bad answer costs somebody their view.
|
| 219 |
-
*
|
| 220 |
-
* β THE SERVER DOES THE RESTORE, and the reason is in the payload rather than in taste: the list
|
| 221 |
-
* door deliberately serves history entries WITHOUT their source, so a client cannot assemble an old
|
| 222 |
-
* version's text to re-save it. One call is also atomic, where read-then-write leaves a window in
|
| 223 |
-
* which a failure shows the person code that is not what is stored.
|
| 224 |
-
*/
|
| 225 |
-
export function revertScriptView(id: string, version: number) {
|
| 226 |
-
return write(`/script-views/${encodeURIComponent(id)}/revert`, "POST", { version });
|
| 227 |
-
}
|
| 228 |
-
|
| 229 |
-
export async function deleteScriptView(id: string): Promise<{ deleted: boolean; error?: string }> {
|
| 230 |
-
let res: Response;
|
| 231 |
-
try {
|
| 232 |
-
res = await fetch(`${API_V1}/script-views/${encodeURIComponent(id)}`,
|
| 233 |
-
{ method: "DELETE", credentials: CREDENTIALS });
|
| 234 |
-
} catch {
|
| 235 |
-
return { deleted: false, error: TRANSPORT_TEXT.unreachable };
|
| 236 |
-
}
|
| 237 |
-
if (!res.ok)
|
| 238 |
-
return { deleted: false,
|
| 239 |
-
error: refusalMessage(await body(res), res.status, TRANSPORT_TEXT.unavailable) };
|
| 240 |
-
return { deleted: true };
|
| 241 |
-
}
|
| 242 |
-
|
| 243 |
-
/**
|
| 244 |
-
* Run a script view. `draft` runs UNSAVED source, checked exactly as stored source is, which is
|
| 245 |
-
* what makes the editor usable: type, run, save when it works (E's note 3).
|
| 246 |
-
*/
|
| 247 |
-
export async function runScriptView(id: string, draft?: string): Promise<ScriptRun> {
|
| 248 |
-
let res: Response;
|
| 249 |
-
try {
|
| 250 |
-
res = await fetch(`${API_V1}/script-views/${encodeURIComponent(id)}/run`, {
|
| 251 |
-
method: "POST",
|
| 252 |
-
credentials: CREDENTIALS,
|
| 253 |
-
headers: { "Content-Type": "application/json" },
|
| 254 |
-
body: JSON.stringify(draft === undefined ? {} : { source: draft }),
|
| 255 |
-
});
|
| 256 |
-
} catch {
|
| 257 |
-
return { ok: false, stdout: "", truncated: false, ms: 0, code: "unreachable",
|
| 258 |
-
caps: { wallClock: false, memory: false, cpu: false },
|
| 259 |
-
error: TRANSPORT_TEXT.unreachable };
|
| 260 |
-
}
|
| 261 |
-
const payload = await body(res);
|
| 262 |
-
if (!res.ok) return transportRun(res, payload);
|
| 263 |
-
const shaped = payload as Partial<ScriptRun> | null;
|
| 264 |
-
return {
|
| 265 |
-
ok: shaped?.ok === true,
|
| 266 |
-
...(shaped?.spec !== undefined ? { spec: shaped.spec } : {}),
|
| 267 |
-
stdout: typeof shaped?.stdout === "string" ? shaped.stdout : "",
|
| 268 |
-
truncated: shaped?.truncated === true,
|
| 269 |
-
ms: typeof shaped?.ms === "number" ? shaped.ms : 0,
|
| 270 |
-
code: typeof shaped?.code === "string" ? shaped.code : "error",
|
| 271 |
-
caps: shaped?.caps ?? { wallClock: false, memory: false, cpu: false },
|
| 272 |
-
...(typeof shaped?.error === "string" ? { error: shaped.error } : {}),
|
| 273 |
-
};
|
| 274 |
-
}
|
| 275 |
-
|
| 276 |
-
// ββ the spec, reduced to what a renderer may DRAW ββββββββββββββββββββββββββββββββββββββββββββ
|
| 277 |
-
//
|
| 278 |
-
// β A WHITELIST OF SHAPES, NOT A BLACKLIST OF KEYS. E's server already refuses `html`,
|
| 279 |
-
// `innerHTML`, `script`, `src`, `srcdoc`, `href`, `style`, `onclick` and `onload` at any depth.
|
| 280 |
-
// Repeating that list here would be a SECOND blacklist that has to stay in step with the first,
|
| 281 |
-
// and the two would drift the first time either side learns a new attribute. Instead this admits
|
| 282 |
-
// only the four shapes the renderer knows how to draw, from scalar leaves β so a key nobody
|
| 283 |
-
// anticipated cannot reach the DOM whatever it is called.
|
| 284 |
-
|
| 285 |
-
export interface SpecCell { text: string }
|
| 286 |
-
export type ScriptSpecKind = "table" | "metrics" | "bars" | "text";
|
| 287 |
-
export interface DrawableSpec {
|
| 288 |
-
kind: ScriptSpecKind;
|
| 289 |
-
title?: string;
|
| 290 |
-
/** `table` */
|
| 291 |
-
columns?: string[];
|
| 292 |
-
rows?: string[][];
|
| 293 |
-
/** `metrics` */
|
| 294 |
-
items?: { label: string; value: string; note?: string }[];
|
| 295 |
-
/** `bars` */
|
| 296 |
-
series?: { label: string; value: number; display: string }[];
|
| 297 |
-
/** `text` */
|
| 298 |
-
body?: string;
|
| 299 |
-
}
|
| 300 |
-
|
| 301 |
-
const MAX_ROWS = 500;
|
| 302 |
-
const MAX_COLS = 40;
|
| 303 |
-
const MAX_ITEMS = 60;
|
| 304 |
-
const MAX_TEXT = 20_000;
|
| 305 |
-
|
| 306 |
-
/** A scalar leaf, as text. Anything else (object, array, function) is NOT drawable and is
|
| 307 |
-
* dropped rather than stringified: `[object Object]` in a cell is a bug wearing a value. */
|
| 308 |
-
function scalar(v: unknown): string | null {
|
| 309 |
-
if (typeof v === "string") return v.slice(0, 2_000);
|
| 310 |
-
if (typeof v === "number") return Number.isFinite(v) ? String(v) : null;
|
| 311 |
-
if (typeof v === "boolean") return v ? "Yes" : "No";
|
| 312 |
-
if (v === null || v === undefined) return "";
|
| 313 |
-
return null;
|
| 314 |
-
}
|
| 315 |
-
|
| 316 |
-
function text(v: unknown, cap = 200): string | undefined {
|
| 317 |
-
const s = scalar(v);
|
| 318 |
-
return typeof s === "string" && s !== "" ? s.slice(0, cap) : undefined;
|
| 319 |
-
}
|
| 320 |
-
|
| 321 |
-
/**
|
| 322 |
-
* The one door a spec passes through before anything is drawn. Returns `null` for a kind this
|
| 323 |
-
* build does not know, which is a legitimate answer and NOT an error: a script whose author
|
| 324 |
-
* invented `kind: "sankey"` deserves a sentence naming the kind, not a blank panel.
|
| 325 |
-
*/
|
| 326 |
-
export function renderableSpec(spec: unknown): DrawableSpec | null {
|
| 327 |
-
if (!spec || typeof spec !== "object" || Array.isArray(spec)) return null;
|
| 328 |
-
const raw = spec as Record<string, unknown>;
|
| 329 |
-
const kind = typeof raw.kind === "string" ? raw.kind : "";
|
| 330 |
-
const title = text(raw.title, 160);
|
| 331 |
-
if (kind === "table") {
|
| 332 |
-
const columns = (Array.isArray(raw.columns) ? raw.columns : [])
|
| 333 |
-
.slice(0, MAX_COLS).map((c) => scalar(c) ?? "").map((c) => c.slice(0, 120));
|
| 334 |
-
if (columns.length === 0) return null;
|
| 335 |
-
const rows = (Array.isArray(raw.rows) ? raw.rows : []).slice(0, MAX_ROWS).map((r) => {
|
| 336 |
-
const cells = Array.isArray(r) ? r : [r];
|
| 337 |
-
return columns.map((_c, i) => scalar(cells[i]) ?? "");
|
| 338 |
-
});
|
| 339 |
-
return { kind: "table", columns, rows, ...(title ? { title } : {}) };
|
| 340 |
-
}
|
| 341 |
-
if (kind === "metrics" || kind === "metric") {
|
| 342 |
-
const source = Array.isArray(raw.items) ? raw.items
|
| 343 |
-
: raw.label !== undefined || raw.value !== undefined ? [raw] : [];
|
| 344 |
-
const items = source.slice(0, MAX_ITEMS).flatMap((it) => {
|
| 345 |
-
if (!it || typeof it !== "object") return [];
|
| 346 |
-
const e = it as Record<string, unknown>;
|
| 347 |
-
const label = text(e.label, 120) ?? "";
|
| 348 |
-
const value = scalar(e.value);
|
| 349 |
-
if (value === null) return [];
|
| 350 |
-
const note = text(e.note, 160);
|
| 351 |
-
return [{ label, value, ...(note ? { note } : {}) }];
|
| 352 |
-
});
|
| 353 |
-
if (items.length === 0) return null;
|
| 354 |
-
return { kind: "metrics", items, ...(title ? { title } : {}) };
|
| 355 |
-
}
|
| 356 |
-
if (kind === "bars" || kind === "bar") {
|
| 357 |
-
const series = (Array.isArray(raw.series) ? raw.series : []).slice(0, MAX_ITEMS)
|
| 358 |
-
.flatMap((it) => {
|
| 359 |
-
if (!it || typeof it !== "object") return [];
|
| 360 |
-
const e = it as Record<string, unknown>;
|
| 361 |
-
const value = typeof e.value === "number" && Number.isFinite(e.value) ? e.value : null;
|
| 362 |
-
if (value === null) return [];
|
| 363 |
-
return [{ label: text(e.label, 120) ?? "", value,
|
| 364 |
-
display: text(e.display, 40) ?? String(value) }];
|
| 365 |
-
});
|
| 366 |
-
if (series.length === 0) return null;
|
| 367 |
-
return { kind: "bars", series, ...(title ? { title } : {}) };
|
| 368 |
-
}
|
| 369 |
-
if (kind === "text") {
|
| 370 |
-
const bodyText = text(raw.body ?? raw.text, MAX_TEXT);
|
| 371 |
-
if (bodyText === undefined) return null;
|
| 372 |
-
return { kind: "text", body: bodyText, ...(title ? { title } : {}) };
|
| 373 |
-
}
|
| 374 |
-
return null;
|
| 375 |
-
}
|
| 376 |
-
|
| 377 |
-
/** The kind a spec CLAIMED, for the sentence shown when this build cannot draw it. */
|
| 378 |
-
export function specKindName(spec: unknown): string {
|
| 379 |
-
if (!spec || typeof spec !== "object" || Array.isArray(spec)) return "";
|
| 380 |
-
const kind = (spec as Record<string, unknown>).kind;
|
| 381 |
-
return typeof kind === "string" ? kind.slice(0, 60) : "";
|
| 382 |
-
}
|
| 383 |
-
|
| 384 |
-
/** The widest bar's value, so every bar is drawn as a share of it. Never zero. */
|
| 385 |
-
export function barScale(series: { value: number }[]): number {
|
| 386 |
-
return series.reduce((m, s) => Math.max(m, Math.abs(s.value)), 0) || 1;
|
| 387 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// customer-grid / scriptViews.ts β the CLIENT half of contract C3 (owner item 6).
|
| 3 |
+
//
|
| 4 |
+
// β THE ASK, verbatim: *"Add code script as an interface (database View) so a user can build
|
| 5 |
+
// whatever they want through the Agent chat interface β¦ User should have the ability to see the
|
| 6 |
+
// code AND the dashboard output of course."* E owns the engine
|
| 7 |
+
// (`aios-web/api/routes_script_views.py`, published as C3); this module is the typed door to it
|
| 8 |
+
// and holds no policy of its own.
|
| 9 |
+
//
|
| 10 |
+
// ββ THE ONE RULE THIS WHOLE FEATURE RESTS ON: **a run returns a DECLARATIVE SPEC, never HTML
|
| 11 |
+
// and never a script.** R10 puts the Python in a server sandbox precisely so the browser never
|
| 12 |
+
// has to trust the output; a renderer that then evaluated a string would hand back everything the
|
| 13 |
+
// sandbox was built to contain. So nothing in this module or its renderer interprets a value as
|
| 14 |
+
// code, as markup, as a URL or as CSS. `renderableSpec` below is where that is enforced, and the
|
| 15 |
+
// enforcement is a WHITELIST of scalar leaves rather than a blacklist of dangerous keys β E's
|
| 16 |
+
// server already refuses the dangerous keys at any depth, and two blacklists that must agree is
|
| 17 |
+
// exactly the shape this repo keeps paying for.
|
| 18 |
+
//
|
| 19 |
+
// β R3 β SCOPED, NOT CAPPED. A script view may read only the database it lives in, and there is
|
| 20 |
+
// no limit on how many a database holds (`limits.maxViewsPerDatabase` is `null` ON PURPOSE, so
|
| 21 |
+
// an agent can leave three attempts side by side for the owner to compare). Do not build a
|
| 22 |
+
// "you have reached the limit" state; there is none.
|
| 23 |
+
//
|
| 24 |
+
// β R5 β THE RUN IS THE READER'S SCOPE, NEVER THE AUTHOR'S. The same view opened by two accounts
|
| 25 |
+
// returns two different numbers, correctly. Any cache keyed on the view id alone would show one
|
| 26 |
+
// colleague another's totals, which is why nothing here caches a run at all.
|
| 27 |
+
// ---------------------------------------------------------------------------
|
| 28 |
+
|
| 29 |
+
import { API_V1, CREDENTIALS } from "../apiContract";
|
| 30 |
+
import { refusalMessage } from "./apiBridge";
|
| 31 |
+
|
| 32 |
+
/** One script view as the list endpoint returns it (C3 `row`). */
|
| 33 |
+
export interface ScriptViewRow {
|
| 34 |
+
id: string;
|
| 35 |
+
database: string;
|
| 36 |
+
name: string;
|
| 37 |
+
author: string;
|
| 38 |
+
version: number;
|
| 39 |
+
created: string;
|
| 40 |
+
updated: string;
|
| 41 |
+
versions: number;
|
| 42 |
+
trimmed: number;
|
| 43 |
+
/**
|
| 44 |
+
* β W37-T46 / D-338 β which version this one was RESTORED from, if it was.
|
| 45 |
+
* β OPTIONAL BECAUSE MOST VERSIONS WERE NOT A ROLL-BACK, not because the server might forget to
|
| 46 |
+
* send it. A view saved normally has no such fact, and `undefined` is that absence rather than a
|
| 47 |
+
* missing field: rendering "restored from v0" for an ordinary save would be a lie about history.
|
| 48 |
+
*/
|
| 49 |
+
restoredFrom?: number | null;
|
| 50 |
+
}
|
| 51 |
+
|
| 52 |
+
/** One version in a view's history. Newest first, per C3. */
|
| 53 |
+
export interface ScriptViewVersion {
|
| 54 |
+
version: number;
|
| 55 |
+
author: string;
|
| 56 |
+
created: string;
|
| 57 |
+
bytes: number;
|
| 58 |
+
}
|
| 59 |
+
|
| 60 |
+
/** A single view read (C3 `view`): the row, plus the source and its history. */
|
| 61 |
+
export interface ScriptView extends ScriptViewRow {
|
| 62 |
+
source: string;
|
| 63 |
+
history: ScriptViewVersion[];
|
| 64 |
+
}
|
| 65 |
+
|
| 66 |
+
/** C3's `limits` envelope. β `maxViewsPerDatabase` is `null` by ruling R3, not by omission. */
|
| 67 |
+
export interface ScriptLimits {
|
| 68 |
+
maxSourceBytes: number;
|
| 69 |
+
maxName: number;
|
| 70 |
+
maxHistory: number;
|
| 71 |
+
maxConcurrentRuns: number;
|
| 72 |
+
maxViewsPerDatabase: number | null;
|
| 73 |
+
}
|
| 74 |
+
|
| 75 |
+
/**
|
| 76 |
+
* What a run answers.
|
| 77 |
+
*
|
| 78 |
+
* β `ok: false` IS A 200 (E's own note, and it is the half a caller gets wrong). A script that
|
| 79 |
+
* timed out, refused an import or divided by zero is a well-formed request whose ANSWER is that
|
| 80 |
+
* no view was produced. It is rendered, not thrown.
|
| 81 |
+
*/
|
| 82 |
+
export interface ScriptRun {
|
| 83 |
+
ok: boolean;
|
| 84 |
+
spec?: unknown;
|
| 85 |
+
stdout: string;
|
| 86 |
+
truncated: boolean;
|
| 87 |
+
ms: number;
|
| 88 |
+
code: string;
|
| 89 |
+
caps: { wallClock: boolean; memory: boolean; cpu: boolean };
|
| 90 |
+
error?: string;
|
| 91 |
+
/** Only on a 409: the four fields are PRINTED, never re-worded (standing rule 1's second half). */
|
| 92 |
+
limit?: { subject: string; effect: string; cause: string; recommendation: string };
|
| 93 |
+
}
|
| 94 |
+
|
| 95 |
+
/** The three codes that are real HTTP statuses rather than script outcomes (C1's wall). */
|
| 96 |
+
export type ScriptTransport = "not_found" | "forbidden" | "unavailable" | "unreachable";
|
| 97 |
+
|
| 98 |
+
async function body(res: Response): Promise<unknown> {
|
| 99 |
+
try {
|
| 100 |
+
return await res.json();
|
| 101 |
+
} catch {
|
| 102 |
+
return null;
|
| 103 |
+
}
|
| 104 |
+
}
|
| 105 |
+
|
| 106 |
+
/**
|
| 107 |
+
* A transport failure, turned into the same envelope a refused RUN uses, so every caller has one
|
| 108 |
+
* shape to render. β Not an exception: a 403 on a database somebody just lost access to is an
|
| 109 |
+
* ordinary answer to an ordinary question, and a throw here would blank a working surface.
|
| 110 |
+
*/
|
| 111 |
+
function transportRun(res: Response, payload: unknown): ScriptRun {
|
| 112 |
+
const code: ScriptTransport =
|
| 113 |
+
res.status === 404 ? "not_found" : res.status === 403 ? "forbidden" : "unavailable";
|
| 114 |
+
const shaped = payload as { error?: { limit?: ScriptRun["limit"] } } | null;
|
| 115 |
+
const out: ScriptRun = {
|
| 116 |
+
ok: false,
|
| 117 |
+
stdout: "",
|
| 118 |
+
truncated: false,
|
| 119 |
+
ms: 0,
|
| 120 |
+
code,
|
| 121 |
+
caps: { wallClock: false, memory: false, cpu: false },
|
| 122 |
+
error: refusalMessage(payload, res.status, TRANSPORT_TEXT[code]),
|
| 123 |
+
};
|
| 124 |
+
const limit = shaped?.error?.limit;
|
| 125 |
+
if (limit) out.limit = limit;
|
| 126 |
+
return out;
|
| 127 |
+
}
|
| 128 |
+
|
| 129 |
+
/** β No dash of any kind: these strings reach a screen (standing rule 2). */
|
| 130 |
+
const TRANSPORT_TEXT: Record<ScriptTransport, string> = {
|
| 131 |
+
not_found: "This database no longer exists, so its scripts cannot run.",
|
| 132 |
+
forbidden: "You do not have access to this database, so its scripts cannot run.",
|
| 133 |
+
unavailable: "This database cannot be served right now, so its scripts cannot run.",
|
| 134 |
+
unreachable: "The server could not be reached, so nothing was run.",
|
| 135 |
+
};
|
| 136 |
+
|
| 137 |
+
export const DEFAULT_SCRIPT_LIMITS: ScriptLimits = {
|
| 138 |
+
maxSourceBytes: 131_072,
|
| 139 |
+
maxName: 80,
|
| 140 |
+
maxHistory: 40,
|
| 141 |
+
maxConcurrentRuns: 4,
|
| 142 |
+
maxViewsPerDatabase: null,
|
| 143 |
+
};
|
| 144 |
+
|
| 145 |
+
export async function listScriptViews(
|
| 146 |
+
database: string
|
| 147 |
+
): Promise<{ views: ScriptViewRow[]; limits: ScriptLimits; error?: string }> {
|
| 148 |
+
let res: Response;
|
| 149 |
+
try {
|
| 150 |
+
res = await fetch(`${API_V1}/script-views?database=${encodeURIComponent(database)}`,
|
| 151 |
+
{ credentials: CREDENTIALS });
|
| 152 |
+
} catch {
|
| 153 |
+
return { views: [], limits: DEFAULT_SCRIPT_LIMITS, error: TRANSPORT_TEXT.unreachable };
|
| 154 |
+
}
|
| 155 |
+
const payload = await body(res);
|
| 156 |
+
if (!res.ok)
|
| 157 |
+
return { views: [], limits: DEFAULT_SCRIPT_LIMITS,
|
| 158 |
+
error: refusalMessage(payload, res.status, TRANSPORT_TEXT.unavailable) };
|
| 159 |
+
const shaped = payload as { views?: ScriptViewRow[]; limits?: ScriptLimits } | null;
|
| 160 |
+
return { views: Array.isArray(shaped?.views) ? shaped.views : [],
|
| 161 |
+
limits: shaped?.limits ?? DEFAULT_SCRIPT_LIMITS };
|
| 162 |
+
}
|
| 163 |
+
|
| 164 |
+
export async function readScriptView(
|
| 165 |
+
id: string
|
| 166 |
+
): Promise<{ view: ScriptView | null; error?: string }> {
|
| 167 |
+
let res: Response;
|
| 168 |
+
try {
|
| 169 |
+
res = await fetch(`${API_V1}/script-views/${encodeURIComponent(id)}`,
|
| 170 |
+
{ credentials: CREDENTIALS });
|
| 171 |
+
} catch {
|
| 172 |
+
return { view: null, error: TRANSPORT_TEXT.unreachable };
|
| 173 |
+
}
|
| 174 |
+
const payload = await body(res);
|
| 175 |
+
if (!res.ok)
|
| 176 |
+
return { view: null, error: refusalMessage(payload, res.status, TRANSPORT_TEXT.unavailable) };
|
| 177 |
+
const shaped = payload as { view?: ScriptView } | null;
|
| 178 |
+
return { view: shaped?.view ?? null };
|
| 179 |
+
}
|
| 180 |
+
|
| 181 |
+
async function write(
|
| 182 |
+
path: string, method: "POST" | "PUT", payload: Record<string, unknown>
|
| 183 |
+
): Promise<{ view: ScriptView | null; error?: string }> {
|
| 184 |
+
let res: Response;
|
| 185 |
+
try {
|
| 186 |
+
res = await fetch(`${API_V1}${path}`, {
|
| 187 |
+
method,
|
| 188 |
+
credentials: CREDENTIALS,
|
| 189 |
+
headers: { "Content-Type": "application/json" },
|
| 190 |
+
body: JSON.stringify(payload),
|
| 191 |
+
});
|
| 192 |
+
} catch {
|
| 193 |
+
return { view: null, error: TRANSPORT_TEXT.unreachable };
|
| 194 |
+
}
|
| 195 |
+
const answer = await body(res);
|
| 196 |
+
if (!res.ok)
|
| 197 |
+
return { view: null, error: refusalMessage(answer, res.status, TRANSPORT_TEXT.unavailable) };
|
| 198 |
+
const shaped = answer as { view?: ScriptView } | null;
|
| 199 |
+
return { view: shaped?.view ?? null };
|
| 200 |
+
}
|
| 201 |
+
|
| 202 |
+
export function createScriptView(database: string, source: string, name?: string) {
|
| 203 |
+
return write("/script-views", "POST",
|
| 204 |
+
name === undefined ? { database, source } : { database, source, name });
|
| 205 |
+
}
|
| 206 |
+
|
| 207 |
+
/** β A PUT is a NEW VERSION, never an overwrite (R8's shape, applied to scripts). */
|
| 208 |
+
export function saveScriptView(id: string, source: string, name?: string) {
|
| 209 |
+
return write(`/script-views/${encodeURIComponent(id)}`, "PUT",
|
| 210 |
+
name === undefined ? { source } : { source, name });
|
| 211 |
+
}
|
| 212 |
+
|
| 213 |
+
/**
|
| 214 |
+
* ββ W37-T46 / D-338 β GO BACK TO AN EARLIER VERSION, AND IT IS A NEW VERSION.
|
| 215 |
+
*
|
| 216 |
+
* The API already RETURNED `history` newest-first and the editor already showed `v<n>`; there was
|
| 217 |
+
* simply no control, which is D-338 in one sentence. This matters more now that a chat writes the
|
| 218 |
+
* code (R2): generation without roll-back means one bad answer costs somebody their view.
|
| 219 |
+
*
|
| 220 |
+
* β THE SERVER DOES THE RESTORE, and the reason is in the payload rather than in taste: the list
|
| 221 |
+
* door deliberately serves history entries WITHOUT their source, so a client cannot assemble an old
|
| 222 |
+
* version's text to re-save it. One call is also atomic, where read-then-write leaves a window in
|
| 223 |
+
* which a failure shows the person code that is not what is stored.
|
| 224 |
+
*/
|
| 225 |
+
export function revertScriptView(id: string, version: number) {
|
| 226 |
+
return write(`/script-views/${encodeURIComponent(id)}/revert`, "POST", { version });
|
| 227 |
+
}
|
| 228 |
+
|
| 229 |
+
export async function deleteScriptView(id: string): Promise<{ deleted: boolean; error?: string }> {
|
| 230 |
+
let res: Response;
|
| 231 |
+
try {
|
| 232 |
+
res = await fetch(`${API_V1}/script-views/${encodeURIComponent(id)}`,
|
| 233 |
+
{ method: "DELETE", credentials: CREDENTIALS });
|
| 234 |
+
} catch {
|
| 235 |
+
return { deleted: false, error: TRANSPORT_TEXT.unreachable };
|
| 236 |
+
}
|
| 237 |
+
if (!res.ok)
|
| 238 |
+
return { deleted: false,
|
| 239 |
+
error: refusalMessage(await body(res), res.status, TRANSPORT_TEXT.unavailable) };
|
| 240 |
+
return { deleted: true };
|
| 241 |
+
}
|
| 242 |
+
|
| 243 |
+
/**
|
| 244 |
+
* Run a script view. `draft` runs UNSAVED source, checked exactly as stored source is, which is
|
| 245 |
+
* what makes the editor usable: type, run, save when it works (E's note 3).
|
| 246 |
+
*/
|
| 247 |
+
export async function runScriptView(id: string, draft?: string): Promise<ScriptRun> {
|
| 248 |
+
let res: Response;
|
| 249 |
+
try {
|
| 250 |
+
res = await fetch(`${API_V1}/script-views/${encodeURIComponent(id)}/run`, {
|
| 251 |
+
method: "POST",
|
| 252 |
+
credentials: CREDENTIALS,
|
| 253 |
+
headers: { "Content-Type": "application/json" },
|
| 254 |
+
body: JSON.stringify(draft === undefined ? {} : { source: draft }),
|
| 255 |
+
});
|
| 256 |
+
} catch {
|
| 257 |
+
return { ok: false, stdout: "", truncated: false, ms: 0, code: "unreachable",
|
| 258 |
+
caps: { wallClock: false, memory: false, cpu: false },
|
| 259 |
+
error: TRANSPORT_TEXT.unreachable };
|
| 260 |
+
}
|
| 261 |
+
const payload = await body(res);
|
| 262 |
+
if (!res.ok) return transportRun(res, payload);
|
| 263 |
+
const shaped = payload as Partial<ScriptRun> | null;
|
| 264 |
+
return {
|
| 265 |
+
ok: shaped?.ok === true,
|
| 266 |
+
...(shaped?.spec !== undefined ? { spec: shaped.spec } : {}),
|
| 267 |
+
stdout: typeof shaped?.stdout === "string" ? shaped.stdout : "",
|
| 268 |
+
truncated: shaped?.truncated === true,
|
| 269 |
+
ms: typeof shaped?.ms === "number" ? shaped.ms : 0,
|
| 270 |
+
code: typeof shaped?.code === "string" ? shaped.code : "error",
|
| 271 |
+
caps: shaped?.caps ?? { wallClock: false, memory: false, cpu: false },
|
| 272 |
+
...(typeof shaped?.error === "string" ? { error: shaped.error } : {}),
|
| 273 |
+
};
|
| 274 |
+
}
|
| 275 |
+
|
| 276 |
+
// ββ the spec, reduced to what a renderer may DRAW ββββββββββββββββββββββββββββββββββββββββββββ
|
| 277 |
+
//
|
| 278 |
+
// β A WHITELIST OF SHAPES, NOT A BLACKLIST OF KEYS. E's server already refuses `html`,
|
| 279 |
+
// `innerHTML`, `script`, `src`, `srcdoc`, `href`, `style`, `onclick` and `onload` at any depth.
|
| 280 |
+
// Repeating that list here would be a SECOND blacklist that has to stay in step with the first,
|
| 281 |
+
// and the two would drift the first time either side learns a new attribute. Instead this admits
|
| 282 |
+
// only the four shapes the renderer knows how to draw, from scalar leaves β so a key nobody
|
| 283 |
+
// anticipated cannot reach the DOM whatever it is called.
|
| 284 |
+
|
| 285 |
+
export interface SpecCell { text: string }
|
| 286 |
+
export type ScriptSpecKind = "table" | "metrics" | "bars" | "text";
|
| 287 |
+
export interface DrawableSpec {
|
| 288 |
+
kind: ScriptSpecKind;
|
| 289 |
+
title?: string;
|
| 290 |
+
/** `table` */
|
| 291 |
+
columns?: string[];
|
| 292 |
+
rows?: string[][];
|
| 293 |
+
/** `metrics` */
|
| 294 |
+
items?: { label: string; value: string; note?: string }[];
|
| 295 |
+
/** `bars` */
|
| 296 |
+
series?: { label: string; value: number; display: string }[];
|
| 297 |
+
/** `text` */
|
| 298 |
+
body?: string;
|
| 299 |
+
}
|
| 300 |
+
|
| 301 |
+
const MAX_ROWS = 500;
|
| 302 |
+
const MAX_COLS = 40;
|
| 303 |
+
const MAX_ITEMS = 60;
|
| 304 |
+
const MAX_TEXT = 20_000;
|
| 305 |
+
|
| 306 |
+
/** A scalar leaf, as text. Anything else (object, array, function) is NOT drawable and is
|
| 307 |
+
* dropped rather than stringified: `[object Object]` in a cell is a bug wearing a value. */
|
| 308 |
+
function scalar(v: unknown): string | null {
|
| 309 |
+
if (typeof v === "string") return v.slice(0, 2_000);
|
| 310 |
+
if (typeof v === "number") return Number.isFinite(v) ? String(v) : null;
|
| 311 |
+
if (typeof v === "boolean") return v ? "Yes" : "No";
|
| 312 |
+
if (v === null || v === undefined) return "";
|
| 313 |
+
return null;
|
| 314 |
+
}
|
| 315 |
+
|
| 316 |
+
function text(v: unknown, cap = 200): string | undefined {
|
| 317 |
+
const s = scalar(v);
|
| 318 |
+
return typeof s === "string" && s !== "" ? s.slice(0, cap) : undefined;
|
| 319 |
+
}
|
| 320 |
+
|
| 321 |
+
/**
|
| 322 |
+
* The one door a spec passes through before anything is drawn. Returns `null` for a kind this
|
| 323 |
+
* build does not know, which is a legitimate answer and NOT an error: a script whose author
|
| 324 |
+
* invented `kind: "sankey"` deserves a sentence naming the kind, not a blank panel.
|
| 325 |
+
*/
|
| 326 |
+
export function renderableSpec(spec: unknown): DrawableSpec | null {
|
| 327 |
+
if (!spec || typeof spec !== "object" || Array.isArray(spec)) return null;
|
| 328 |
+
const raw = spec as Record<string, unknown>;
|
| 329 |
+
const kind = typeof raw.kind === "string" ? raw.kind : "";
|
| 330 |
+
const title = text(raw.title, 160);
|
| 331 |
+
if (kind === "table") {
|
| 332 |
+
const columns = (Array.isArray(raw.columns) ? raw.columns : [])
|
| 333 |
+
.slice(0, MAX_COLS).map((c) => scalar(c) ?? "").map((c) => c.slice(0, 120));
|
| 334 |
+
if (columns.length === 0) return null;
|
| 335 |
+
const rows = (Array.isArray(raw.rows) ? raw.rows : []).slice(0, MAX_ROWS).map((r) => {
|
| 336 |
+
const cells = Array.isArray(r) ? r : [r];
|
| 337 |
+
return columns.map((_c, i) => scalar(cells[i]) ?? "");
|
| 338 |
+
});
|
| 339 |
+
return { kind: "table", columns, rows, ...(title ? { title } : {}) };
|
| 340 |
+
}
|
| 341 |
+
if (kind === "metrics" || kind === "metric") {
|
| 342 |
+
const source = Array.isArray(raw.items) ? raw.items
|
| 343 |
+
: raw.label !== undefined || raw.value !== undefined ? [raw] : [];
|
| 344 |
+
const items = source.slice(0, MAX_ITEMS).flatMap((it) => {
|
| 345 |
+
if (!it || typeof it !== "object") return [];
|
| 346 |
+
const e = it as Record<string, unknown>;
|
| 347 |
+
const label = text(e.label, 120) ?? "";
|
| 348 |
+
const value = scalar(e.value);
|
| 349 |
+
if (value === null) return [];
|
| 350 |
+
const note = text(e.note, 160);
|
| 351 |
+
return [{ label, value, ...(note ? { note } : {}) }];
|
| 352 |
+
});
|
| 353 |
+
if (items.length === 0) return null;
|
| 354 |
+
return { kind: "metrics", items, ...(title ? { title } : {}) };
|
| 355 |
+
}
|
| 356 |
+
if (kind === "bars" || kind === "bar") {
|
| 357 |
+
const series = (Array.isArray(raw.series) ? raw.series : []).slice(0, MAX_ITEMS)
|
| 358 |
+
.flatMap((it) => {
|
| 359 |
+
if (!it || typeof it !== "object") return [];
|
| 360 |
+
const e = it as Record<string, unknown>;
|
| 361 |
+
const value = typeof e.value === "number" && Number.isFinite(e.value) ? e.value : null;
|
| 362 |
+
if (value === null) return [];
|
| 363 |
+
return [{ label: text(e.label, 120) ?? "", value,
|
| 364 |
+
display: text(e.display, 40) ?? String(value) }];
|
| 365 |
+
});
|
| 366 |
+
if (series.length === 0) return null;
|
| 367 |
+
return { kind: "bars", series, ...(title ? { title } : {}) };
|
| 368 |
+
}
|
| 369 |
+
if (kind === "text") {
|
| 370 |
+
const bodyText = text(raw.body ?? raw.text, MAX_TEXT);
|
| 371 |
+
if (bodyText === undefined) return null;
|
| 372 |
+
return { kind: "text", body: bodyText, ...(title ? { title } : {}) };
|
| 373 |
+
}
|
| 374 |
+
return null;
|
| 375 |
+
}
|
| 376 |
+
|
| 377 |
+
/** The kind a spec CLAIMED, for the sentence shown when this build cannot draw it. */
|
| 378 |
+
export function specKindName(spec: unknown): string {
|
| 379 |
+
if (!spec || typeof spec !== "object" || Array.isArray(spec)) return "";
|
| 380 |
+
const kind = (spec as Record<string, unknown>).kind;
|
| 381 |
+
return typeof kind === "string" ? kind.slice(0, 60) : "";
|
| 382 |
+
}
|
| 383 |
+
|
| 384 |
+
/** The widest bar's value, so every bar is drawn as a share of it. Never zero. */
|
| 385 |
+
export function barScale(series: { value: number }[]): number {
|
| 386 |
+
return series.reduce((m, s) => Math.max(m, Math.abs(s.value)), 0) || 1;
|
| 387 |
+
}
|
web/src/customer-grid/viewEcho.ts
CHANGED
|
@@ -1,272 +1,272 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// customer-grid / viewEcho.ts
|
| 3 |
-
// Reconciles the HOST's view echo against this browser's own newer copy at
|
| 4 |
-
// mount time β the fix for the cold-container measure-condition race.
|
| 5 |
-
//
|
| 6 |
-
// THE RACE. Building a measure condition is several picks (field, period, op,
|
| 7 |
-
// then a value or a statistic), and each settled intermediate autosaves: the
|
| 8 |
-
// host receives a SEQUENCE of view_upserts whose early members hold the rule
|
| 9 |
-
// half-typed. On a cold container the first rerun is slow (preset resolves),
|
| 10 |
-
// so it finishes long after the user completed the rule β and a Streamlit
|
| 11 |
-
// rerun REPLACES the iframe, so the remounted grid re-initialises from that
|
| 12 |
-
// rerun's payload: a view whose rule has no value and no rhs yet. A valueless
|
| 13 |
-
// rule is INACTIVE, inactive is ignored, and `pendingMeasures` skips inactive
|
| 14 |
-
// rules β so the toolbar shows the WHOLE BOOK with the pending marker CLEARED,
|
| 15 |
-
// under a count nobody would doubt, until the later rerun lands. That is the
|
| 16 |
-
// widening sin arriving through the state path rather than the engine.
|
| 17 |
-
//
|
| 18 |
-
// THE RULE. localStorage is this browser's newest truth β it is written at
|
| 19 |
-
// every autosave commit, before the emit round-trips. When the local copy is
|
| 20 |
-
// RECENT (an in-flight edit, not archaeology) and holds an ACTIVE measure rule
|
| 21 |
-
// whose stable id the host copy either lacks or holds INACTIVE, the host copy
|
| 22 |
-
// is a provably lagged echo of this very browser's own edit β so the view
|
| 23 |
-
// keeps the LOCAL filter tree. The restored rule is active with no answer yet,
|
| 24 |
-
// which the engine already renders honestly: matches NOTHING, plus the
|
| 25 |
-
// "Calculatingβ¦" marker. A rule with a typed rhs counts as PENDING, never
|
| 26 |
-
// inactive.
|
| 27 |
-
//
|
| 28 |
-
// Deliberately NARROW β everything below returns the host copy unchanged:
|
| 29 |
-
// - stale local copy (past ECHO_RECENT_MS): cross-browser divergence is not
|
| 30 |
-
// an echo, and host state stays the durable truth;
|
| 31 |
-
// - the local rule is inactive too (a genuinely abandoned half-typed rule
|
| 32 |
-
// must not resurrect);
|
| 33 |
-
// - the host rule is ACTIVE with a different value (the deliberate
|
| 34 |
-
// hold-the-previous-answer design, CG-8 Β§6.2.4 β not a lie, self-corrects);
|
| 35 |
-
// - column/cohort-only edits (no measure id to match on β their stale window
|
| 36 |
-
// needs no server answer and closes at the next processed upsert).
|
| 37 |
-
// Matching is by the measure rule's client-generated `id` β the same identity
|
| 38 |
-
// that re-associates the server's answers β never by position.
|
| 39 |
-
// ---------------------------------------------------------------------------
|
| 40 |
-
|
| 41 |
-
import type { FilterNode, FilterRule, SavedView } from "./types";
|
| 42 |
-
import { isFilterGroup, isMeasureRule, isRuleActive } from "./types";
|
| 43 |
-
|
| 44 |
-
/**
|
| 45 |
-
* How long a localStorage copy counts as an IN-FLIGHT edit. The race window it
|
| 46 |
-
* must cover is one cold-container round trip (seconds); minutes past that,
|
| 47 |
-
* a difference between the copies is divergence, not an echo. Browser-clock
|
| 48 |
-
* arithmetic on purpose: both timestamps come from the SAME machine, so this
|
| 49 |
-
* is not the tenant-day rule (`CustomersPayload.today`) β that rule is about
|
| 50 |
-
* two ENGINES agreeing on a date.
|
| 51 |
-
*/
|
| 52 |
-
export const ECHO_RECENT_MS = 120_000;
|
| 53 |
-
/**
|
| 54 |
-
* ββ W36-T03 (owner item 1) β WHICH VIEW DOES THIS BROWSER OPEN ON?
|
| 55 |
-
*
|
| 56 |
-
* β THE DEFECT: `local?.activeViewId ?? payload.workspace?.activeViewId ?? ALL_VIEW_ID`. Every
|
| 57 |
-
* neighbouring local stratum in this file is bounded by `ECHO_RECENT_MS` β a rename, a delete, a
|
| 58 |
-
* filter tree, a field def β on the standing rule that past the window a difference between the
|
| 59 |
-
* copies is DIVERGENCE, not an echo. This one carried **no stamp at all**, so a browser sat on the
|
| 60 |
-
* view it happened to be showing for ever, and two machines on one account could not be brought
|
| 61 |
-
* onto the same view by anything the user did on either of them.
|
| 62 |
-
*
|
| 63 |
-
* β AND THE 2026-07-31 OWNER ITEM STILL HOLDS, which is why this is a re-order and not a deletion.
|
| 64 |
-
* *"Where the user left off survives a new browser"* is served by the SERVER copy, not the local
|
| 65 |
-
* one: `view_select` -> `grid_events` -> `table_store.save_active_view(uname, vid)`, read back as
|
| 66 |
-
* `workspace.activeViewId`. A brand-new browser has no local copy at all and has always resumed
|
| 67 |
-
* from that. Bounding the local preference simply stops it outranking the account's own newer
|
| 68 |
-
* answer.
|
| 69 |
-
*
|
| 70 |
-
* THE ORDER, and each rung earns its place:
|
| 71 |
-
* 1. the LOCAL choice, if this browser made it inside the window β an in-flight `view_select`
|
| 72 |
-
* whose echo has not come back must not be undone by the copy it is about to replace;
|
| 73 |
-
* 2. the SERVER's copy β the account's most recent answer, from whichever machine gave it;
|
| 74 |
-
* 3. the LOCAL choice again, STALE β reached only when the server has no opinion (an older
|
| 75 |
-
* tenant, or a `view_select` that could not be stored because the store was unavailable);
|
| 76 |
-
* a stale local memory beats resetting somebody to the default view;
|
| 77 |
-
* 4. the system view.
|
| 78 |
-
*
|
| 79 |
-
* β `at` HAS TO BE ITS OWN STAMP. `LocalWorkspace.savedAt` cannot serve: the persist effect
|
| 80 |
-
* rewrites it on every field, view and config change, so an `ECHO_RECENT_MS` bound read off it is
|
| 81 |
-
* refreshed by the very activity it is meant to bound β the same trap `filtersKey` documents one
|
| 82 |
-
* screen up.
|
| 83 |
-
*/
|
| 84 |
-
export function resolveActiveView(
|
| 85 |
-
local: { id?: string; at?: number } | undefined,
|
| 86 |
-
hostId: string | undefined,
|
| 87 |
-
systemId: string,
|
| 88 |
-
now: number
|
| 89 |
-
): string {
|
| 90 |
-
const localId = typeof local?.id === "string" && local.id !== "" ? local.id : undefined;
|
| 91 |
-
const host = typeof hostId === "string" && hostId !== "" ? hostId : undefined;
|
| 92 |
-
const fresh = typeof local?.at === "number" && now - local.at <= ECHO_RECENT_MS;
|
| 93 |
-
if (localId !== undefined && fresh) return localId;
|
| 94 |
-
return host ?? localId ?? systemId;
|
| 95 |
-
}
|
| 96 |
-
|
| 97 |
-
|
| 98 |
-
/**
|
| 99 |
-
* The identity of a view's FILTER TREE β BUG-1's re-emit is about this half and no other.
|
| 100 |
-
*
|
| 101 |
-
* Also the re-emit's IDEMPOTENCE KEY. It has to be the tree itself rather than a timestamp
|
| 102 |
-
* because the obvious stamp does not survive: `CustomerGrid`'s local-workspace effect rewrites
|
| 103 |
-
* `savedAt: Date.now()` on every init, so an `ECHO_RECENT_MS`-based bound is refreshed by the
|
| 104 |
-
* very remount it is supposed to bound. This key only changes when the USER edits the
|
| 105 |
-
* conditions again, which is exactly the event that deserves a second emit.
|
| 106 |
-
*/
|
| 107 |
-
export function filtersKey(view: SavedView): string {
|
| 108 |
-
return JSON.stringify([
|
| 109 |
-
view.config?.filters ?? [],
|
| 110 |
-
view.config?.filterConj === "or" ? "or" : "and",
|
| 111 |
-
]);
|
| 112 |
-
}
|
| 113 |
-
|
| 114 |
-
/**
|
| 115 |
-
* BUG-1 (wave 11) β should this reconciled view be pushed back to the host, and under what key?
|
| 116 |
-
* Returns the key to record, or `null` for "say nothing".
|
| 117 |
-
*
|
| 118 |
-
* `reconcileEchoView` restores a filter tree the host copy provably lacks, and then nothing
|
| 119 |
-
* sends it: init seeds `views` and `config` from the same object, so the autosave's
|
| 120 |
-
* `sameConfig` guard reports "saved" forever. The rule stays ACTIVE, PENDING and unknown to the
|
| 121 |
-
* resolver. This is the missing telling.
|
| 122 |
-
*
|
| 123 |
-
* β TWO GUARDS, and each closes a way the naive version loops.
|
| 124 |
-
*
|
| 125 |
-
* 1. **The FILTERS half only.** Identity (`merged !== host`) is not the test: `reconcileEchoView`
|
| 126 |
-
* also returns a fresh object for a DISPLAY-only divergence (a kanban/calendar pick), which
|
| 127 |
-
* has nothing to do with BUG-1 and would make every mode change emit at mount.
|
| 128 |
-
* 2. **Once per tree.** Termination cannot rest on "the host will store it": a measure key
|
| 129 |
-
* outside this user's BU offer is STRIPPED by `clean_filter_tree`, so the host copy never
|
| 130 |
-
* gains the rule, `lagged` stays true, and emit β rerun β remount β emit is unbounded. With
|
| 131 |
-
* the tree as the key we tell the host once and stop, whether or not it could keep it.
|
| 132 |
-
*/
|
| 133 |
-
export function echoReemit(
|
| 134 |
-
merged: SavedView,
|
| 135 |
-
host: SavedView,
|
| 136 |
-
alreadyReemitted: string | undefined
|
| 137 |
-
): string | null {
|
| 138 |
-
const key = filtersKey(merged);
|
| 139 |
-
if (key === filtersKey(host)) return null;
|
| 140 |
-
if (key === alreadyReemitted) return null;
|
| 141 |
-
return key;
|
| 142 |
-
}
|
| 143 |
-
|
| 144 |
-
/** Measure leaves by their stable rule id. Only measure rules carry ids, and
|
| 145 |
-
* only they need one β the id is how a server answer finds its question. */
|
| 146 |
-
function measureLeavesById(
|
| 147 |
-
nodes: FilterNode[] | undefined,
|
| 148 |
-
out: Map<string, FilterRule>
|
| 149 |
-
): void {
|
| 150 |
-
for (const node of nodes ?? []) {
|
| 151 |
-
if (isFilterGroup(node)) {
|
| 152 |
-
measureLeavesById(node.children, out);
|
| 153 |
-
continue;
|
| 154 |
-
}
|
| 155 |
-
const rule = node as FilterRule;
|
| 156 |
-
if (isMeasureRule(node) && rule.id) out.set(rule.id, rule);
|
| 157 |
-
}
|
| 158 |
-
}
|
| 159 |
-
|
| 160 |
-
/**
|
| 161 |
-
* One view, host copy vs local copy. Returns the host view UNTOUCHED unless
|
| 162 |
-
* the local copy is a recent in-flight edit the host copy provably lags β
|
| 163 |
-
* then the host view keeps everything EXCEPT `filters`/`filterConj`, which
|
| 164 |
-
* come from the local copy (the user's completed question). The tree is taken
|
| 165 |
-
* WHOLESALE rather than leaf-spliced: the first valueless echo often predates
|
| 166 |
-
* the leaf entirely (the rule was still a column condition, or did not exist),
|
| 167 |
-
* and re-inserting a leaf at a guessed position into someone's nested groups
|
| 168 |
-
* would answer a question nobody asked once it resolves.
|
| 169 |
-
*/
|
| 170 |
-
export function reconcileEchoView(
|
| 171 |
-
host: SavedView,
|
| 172 |
-
local: SavedView | undefined,
|
| 173 |
-
localSavedAt: number | undefined,
|
| 174 |
-
now: number
|
| 175 |
-
): SavedView {
|
| 176 |
-
if (!local || localSavedAt == null) return host;
|
| 177 |
-
if (now - localSavedAt > ECHO_RECENT_MS) return host;
|
| 178 |
-
|
| 179 |
-
// Wave-7 item W13 (contract C4 as AMENDED) β the DISPLAY half, same recency rule.
|
| 180 |
-
// `config.display` carries the view's mode AND its calendar/kanban field picks; the
|
| 181 |
-
// host stores it only for non-grid modes, so an echo routinely lags this browser's
|
| 182 |
-
// own draft (a pick made seconds ago, or the grid-mode carry that keeps the picks
|
| 183 |
-
// across a mode round trip). A recent local copy whose display differs is that lag;
|
| 184 |
-
// taking the host copy would feed the select its default again β the reported
|
| 185 |
-
// reset-to-"Status" blip, one remount later. A caught-up echo (equal JSON) keeps
|
| 186 |
-
// the HOST object untouched, so nothing churns.
|
| 187 |
-
// ABSENT is a value here: a local draft with NO display means this browser just
|
| 188 |
-
// returned the view to the ref-less grid, and a lagged kanban echo must not flip it
|
| 189 |
-
// back β so the comparison is over the member itself, not only truthy copies.
|
| 190 |
-
let out = host;
|
| 191 |
-
const localDisplay = local.config ? local.config.display : undefined;
|
| 192 |
-
if (
|
| 193 |
-
local.config &&
|
| 194 |
-
JSON.stringify(localDisplay ?? null) !== JSON.stringify(host.config?.display ?? null)
|
| 195 |
-
) {
|
| 196 |
-
const config = { ...host.config };
|
| 197 |
-
if (localDisplay === undefined) delete config.display;
|
| 198 |
-
else config.display = localDisplay;
|
| 199 |
-
out = { ...host, config };
|
| 200 |
-
}
|
| 201 |
-
|
| 202 |
-
// Item 12 (C-LOCK, 2026-08-02) β `cohortLock` needs the SAME splice, and it needs its own
|
| 203 |
-
// because it is a sibling of `display` on ViewConfig, not a member of it: everything this
|
| 204 |
-
// function does not name explicitly is taken from the host wholesale.
|
| 205 |
-
//
|
| 206 |
-
// Without this, locking a view and then receiving a `/workspace` echo that predates the
|
| 207 |
-
// write hands back the pre-lock config β the rail mark disappears and the lock reads as
|
| 208 |
-
// ignored for a round trip. Exactly the blip the display half was written to stop, one key
|
| 209 |
-
// over. ABSENT IS A VALUE here too: a local copy that just UNLOCKED must not be flipped
|
| 210 |
-
// back by a lagged echo that still carries the lock, so the comparison is over the member
|
| 211 |
-
// itself rather than over truthy copies.
|
| 212 |
-
//
|
| 213 |
-
// β Built on `out`, not on `host` β the display splice above may already have replaced it,
|
| 214 |
-
// and rebuilding from `host` here would silently undo that.
|
| 215 |
-
const localLock = local.config ? local.config.cohortLock : undefined;
|
| 216 |
-
if (local.config && localLock !== out.config?.cohortLock) {
|
| 217 |
-
const config = { ...out.config };
|
| 218 |
-
if (localLock === undefined) delete config.cohortLock;
|
| 219 |
-
else config.cohortLock = localLock;
|
| 220 |
-
out = { ...out, config };
|
| 221 |
-
}
|
| 222 |
-
|
| 223 |
-
// β WAVE 32 Β· T24 (R5/C4) β `important` needs THE SAME SPLICE, one key over, and for the
|
| 224 |
-
// identical reason `cohortLock` does: it is a sibling on ViewConfig, and everything this
|
| 225 |
-
// function does not name explicitly is taken from the host wholesale. Without it, marking a
|
| 226 |
-
// view and then receiving a `/workspace` echo that predates the write hands back the unmarked
|
| 227 |
-
// config β the red badge blinks out and the mark reads as ignored for a round trip.
|
| 228 |
-
// β ABSENT IS A VALUE here too: a local copy that just UNMARKED must not be flipped back by a
|
| 229 |
-
// lagged echo still carrying `important: true`, so the comparison is over the member itself.
|
| 230 |
-
// β Built on `out`, never on `host` β the two splices above may already have replaced it.
|
| 231 |
-
const localImportant = local.config ? local.config.important : undefined;
|
| 232 |
-
if (local.config && localImportant !== out.config?.important) {
|
| 233 |
-
const config = { ...out.config };
|
| 234 |
-
if (localImportant === undefined) delete config.important;
|
| 235 |
-
else config.important = localImportant;
|
| 236 |
-
out = { ...out, config };
|
| 237 |
-
}
|
| 238 |
-
|
| 239 |
-
const localFilters = local.config ? local.config.filters : undefined;
|
| 240 |
-
if (!Array.isArray(localFilters) || localFilters.length === 0) return out;
|
| 241 |
-
|
| 242 |
-
const localById = new Map<string, FilterRule>();
|
| 243 |
-
measureLeavesById(localFilters, localById);
|
| 244 |
-
if (localById.size === 0) return out;
|
| 245 |
-
|
| 246 |
-
const hostById = new Map<string, FilterRule>();
|
| 247 |
-
measureLeavesById(host.config ? host.config.filters : undefined, hostById);
|
| 248 |
-
|
| 249 |
-
// Lagged = some measure rule this browser completed is missing or valueless
|
| 250 |
-
// in the host copy. An ACTIVE host twin β even with a different value β is
|
| 251 |
-
// NOT lagged for our purposes: that is the known hold-the-previous-answer
|
| 252 |
-
// window, and fighting it from here would resurrect stale local values.
|
| 253 |
-
let lagged = false;
|
| 254 |
-
for (const [id, leaf] of localById) {
|
| 255 |
-
if (!isRuleActive(leaf)) continue;
|
| 256 |
-
const twin = hostById.get(id);
|
| 257 |
-
if (!twin || !isRuleActive(twin)) {
|
| 258 |
-
lagged = true;
|
| 259 |
-
break;
|
| 260 |
-
}
|
| 261 |
-
}
|
| 262 |
-
if (!lagged) return out;
|
| 263 |
-
|
| 264 |
-
return {
|
| 265 |
-
...out,
|
| 266 |
-
config: {
|
| 267 |
-
...out.config,
|
| 268 |
-
filters: localFilters,
|
| 269 |
-
filterConj: local.config.filterConj ?? host.config.filterConj,
|
| 270 |
-
},
|
| 271 |
-
};
|
| 272 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// customer-grid / viewEcho.ts
|
| 3 |
+
// Reconciles the HOST's view echo against this browser's own newer copy at
|
| 4 |
+
// mount time β the fix for the cold-container measure-condition race.
|
| 5 |
+
//
|
| 6 |
+
// THE RACE. Building a measure condition is several picks (field, period, op,
|
| 7 |
+
// then a value or a statistic), and each settled intermediate autosaves: the
|
| 8 |
+
// host receives a SEQUENCE of view_upserts whose early members hold the rule
|
| 9 |
+
// half-typed. On a cold container the first rerun is slow (preset resolves),
|
| 10 |
+
// so it finishes long after the user completed the rule β and a Streamlit
|
| 11 |
+
// rerun REPLACES the iframe, so the remounted grid re-initialises from that
|
| 12 |
+
// rerun's payload: a view whose rule has no value and no rhs yet. A valueless
|
| 13 |
+
// rule is INACTIVE, inactive is ignored, and `pendingMeasures` skips inactive
|
| 14 |
+
// rules β so the toolbar shows the WHOLE BOOK with the pending marker CLEARED,
|
| 15 |
+
// under a count nobody would doubt, until the later rerun lands. That is the
|
| 16 |
+
// widening sin arriving through the state path rather than the engine.
|
| 17 |
+
//
|
| 18 |
+
// THE RULE. localStorage is this browser's newest truth β it is written at
|
| 19 |
+
// every autosave commit, before the emit round-trips. When the local copy is
|
| 20 |
+
// RECENT (an in-flight edit, not archaeology) and holds an ACTIVE measure rule
|
| 21 |
+
// whose stable id the host copy either lacks or holds INACTIVE, the host copy
|
| 22 |
+
// is a provably lagged echo of this very browser's own edit β so the view
|
| 23 |
+
// keeps the LOCAL filter tree. The restored rule is active with no answer yet,
|
| 24 |
+
// which the engine already renders honestly: matches NOTHING, plus the
|
| 25 |
+
// "Calculatingβ¦" marker. A rule with a typed rhs counts as PENDING, never
|
| 26 |
+
// inactive.
|
| 27 |
+
//
|
| 28 |
+
// Deliberately NARROW β everything below returns the host copy unchanged:
|
| 29 |
+
// - stale local copy (past ECHO_RECENT_MS): cross-browser divergence is not
|
| 30 |
+
// an echo, and host state stays the durable truth;
|
| 31 |
+
// - the local rule is inactive too (a genuinely abandoned half-typed rule
|
| 32 |
+
// must not resurrect);
|
| 33 |
+
// - the host rule is ACTIVE with a different value (the deliberate
|
| 34 |
+
// hold-the-previous-answer design, CG-8 Β§6.2.4 β not a lie, self-corrects);
|
| 35 |
+
// - column/cohort-only edits (no measure id to match on β their stale window
|
| 36 |
+
// needs no server answer and closes at the next processed upsert).
|
| 37 |
+
// Matching is by the measure rule's client-generated `id` β the same identity
|
| 38 |
+
// that re-associates the server's answers β never by position.
|
| 39 |
+
// ---------------------------------------------------------------------------
|
| 40 |
+
|
| 41 |
+
import type { FilterNode, FilterRule, SavedView } from "./types";
|
| 42 |
+
import { isFilterGroup, isMeasureRule, isRuleActive } from "./types";
|
| 43 |
+
|
| 44 |
+
/**
|
| 45 |
+
* How long a localStorage copy counts as an IN-FLIGHT edit. The race window it
|
| 46 |
+
* must cover is one cold-container round trip (seconds); minutes past that,
|
| 47 |
+
* a difference between the copies is divergence, not an echo. Browser-clock
|
| 48 |
+
* arithmetic on purpose: both timestamps come from the SAME machine, so this
|
| 49 |
+
* is not the tenant-day rule (`CustomersPayload.today`) β that rule is about
|
| 50 |
+
* two ENGINES agreeing on a date.
|
| 51 |
+
*/
|
| 52 |
+
export const ECHO_RECENT_MS = 120_000;
|
| 53 |
+
/**
|
| 54 |
+
* ββ W36-T03 (owner item 1) β WHICH VIEW DOES THIS BROWSER OPEN ON?
|
| 55 |
+
*
|
| 56 |
+
* β THE DEFECT: `local?.activeViewId ?? payload.workspace?.activeViewId ?? ALL_VIEW_ID`. Every
|
| 57 |
+
* neighbouring local stratum in this file is bounded by `ECHO_RECENT_MS` β a rename, a delete, a
|
| 58 |
+
* filter tree, a field def β on the standing rule that past the window a difference between the
|
| 59 |
+
* copies is DIVERGENCE, not an echo. This one carried **no stamp at all**, so a browser sat on the
|
| 60 |
+
* view it happened to be showing for ever, and two machines on one account could not be brought
|
| 61 |
+
* onto the same view by anything the user did on either of them.
|
| 62 |
+
*
|
| 63 |
+
* β AND THE 2026-07-31 OWNER ITEM STILL HOLDS, which is why this is a re-order and not a deletion.
|
| 64 |
+
* *"Where the user left off survives a new browser"* is served by the SERVER copy, not the local
|
| 65 |
+
* one: `view_select` -> `grid_events` -> `table_store.save_active_view(uname, vid)`, read back as
|
| 66 |
+
* `workspace.activeViewId`. A brand-new browser has no local copy at all and has always resumed
|
| 67 |
+
* from that. Bounding the local preference simply stops it outranking the account's own newer
|
| 68 |
+
* answer.
|
| 69 |
+
*
|
| 70 |
+
* THE ORDER, and each rung earns its place:
|
| 71 |
+
* 1. the LOCAL choice, if this browser made it inside the window β an in-flight `view_select`
|
| 72 |
+
* whose echo has not come back must not be undone by the copy it is about to replace;
|
| 73 |
+
* 2. the SERVER's copy β the account's most recent answer, from whichever machine gave it;
|
| 74 |
+
* 3. the LOCAL choice again, STALE β reached only when the server has no opinion (an older
|
| 75 |
+
* tenant, or a `view_select` that could not be stored because the store was unavailable);
|
| 76 |
+
* a stale local memory beats resetting somebody to the default view;
|
| 77 |
+
* 4. the system view.
|
| 78 |
+
*
|
| 79 |
+
* β `at` HAS TO BE ITS OWN STAMP. `LocalWorkspace.savedAt` cannot serve: the persist effect
|
| 80 |
+
* rewrites it on every field, view and config change, so an `ECHO_RECENT_MS` bound read off it is
|
| 81 |
+
* refreshed by the very activity it is meant to bound β the same trap `filtersKey` documents one
|
| 82 |
+
* screen up.
|
| 83 |
+
*/
|
| 84 |
+
export function resolveActiveView(
|
| 85 |
+
local: { id?: string; at?: number } | undefined,
|
| 86 |
+
hostId: string | undefined,
|
| 87 |
+
systemId: string,
|
| 88 |
+
now: number
|
| 89 |
+
): string {
|
| 90 |
+
const localId = typeof local?.id === "string" && local.id !== "" ? local.id : undefined;
|
| 91 |
+
const host = typeof hostId === "string" && hostId !== "" ? hostId : undefined;
|
| 92 |
+
const fresh = typeof local?.at === "number" && now - local.at <= ECHO_RECENT_MS;
|
| 93 |
+
if (localId !== undefined && fresh) return localId;
|
| 94 |
+
return host ?? localId ?? systemId;
|
| 95 |
+
}
|
| 96 |
+
|
| 97 |
+
|
| 98 |
+
/**
|
| 99 |
+
* The identity of a view's FILTER TREE β BUG-1's re-emit is about this half and no other.
|
| 100 |
+
*
|
| 101 |
+
* Also the re-emit's IDEMPOTENCE KEY. It has to be the tree itself rather than a timestamp
|
| 102 |
+
* because the obvious stamp does not survive: `CustomerGrid`'s local-workspace effect rewrites
|
| 103 |
+
* `savedAt: Date.now()` on every init, so an `ECHO_RECENT_MS`-based bound is refreshed by the
|
| 104 |
+
* very remount it is supposed to bound. This key only changes when the USER edits the
|
| 105 |
+
* conditions again, which is exactly the event that deserves a second emit.
|
| 106 |
+
*/
|
| 107 |
+
export function filtersKey(view: SavedView): string {
|
| 108 |
+
return JSON.stringify([
|
| 109 |
+
view.config?.filters ?? [],
|
| 110 |
+
view.config?.filterConj === "or" ? "or" : "and",
|
| 111 |
+
]);
|
| 112 |
+
}
|
| 113 |
+
|
| 114 |
+
/**
|
| 115 |
+
* BUG-1 (wave 11) β should this reconciled view be pushed back to the host, and under what key?
|
| 116 |
+
* Returns the key to record, or `null` for "say nothing".
|
| 117 |
+
*
|
| 118 |
+
* `reconcileEchoView` restores a filter tree the host copy provably lacks, and then nothing
|
| 119 |
+
* sends it: init seeds `views` and `config` from the same object, so the autosave's
|
| 120 |
+
* `sameConfig` guard reports "saved" forever. The rule stays ACTIVE, PENDING and unknown to the
|
| 121 |
+
* resolver. This is the missing telling.
|
| 122 |
+
*
|
| 123 |
+
* β TWO GUARDS, and each closes a way the naive version loops.
|
| 124 |
+
*
|
| 125 |
+
* 1. **The FILTERS half only.** Identity (`merged !== host`) is not the test: `reconcileEchoView`
|
| 126 |
+
* also returns a fresh object for a DISPLAY-only divergence (a kanban/calendar pick), which
|
| 127 |
+
* has nothing to do with BUG-1 and would make every mode change emit at mount.
|
| 128 |
+
* 2. **Once per tree.** Termination cannot rest on "the host will store it": a measure key
|
| 129 |
+
* outside this user's BU offer is STRIPPED by `clean_filter_tree`, so the host copy never
|
| 130 |
+
* gains the rule, `lagged` stays true, and emit β rerun β remount β emit is unbounded. With
|
| 131 |
+
* the tree as the key we tell the host once and stop, whether or not it could keep it.
|
| 132 |
+
*/
|
| 133 |
+
export function echoReemit(
|
| 134 |
+
merged: SavedView,
|
| 135 |
+
host: SavedView,
|
| 136 |
+
alreadyReemitted: string | undefined
|
| 137 |
+
): string | null {
|
| 138 |
+
const key = filtersKey(merged);
|
| 139 |
+
if (key === filtersKey(host)) return null;
|
| 140 |
+
if (key === alreadyReemitted) return null;
|
| 141 |
+
return key;
|
| 142 |
+
}
|
| 143 |
+
|
| 144 |
+
/** Measure leaves by their stable rule id. Only measure rules carry ids, and
|
| 145 |
+
* only they need one β the id is how a server answer finds its question. */
|
| 146 |
+
function measureLeavesById(
|
| 147 |
+
nodes: FilterNode[] | undefined,
|
| 148 |
+
out: Map<string, FilterRule>
|
| 149 |
+
): void {
|
| 150 |
+
for (const node of nodes ?? []) {
|
| 151 |
+
if (isFilterGroup(node)) {
|
| 152 |
+
measureLeavesById(node.children, out);
|
| 153 |
+
continue;
|
| 154 |
+
}
|
| 155 |
+
const rule = node as FilterRule;
|
| 156 |
+
if (isMeasureRule(node) && rule.id) out.set(rule.id, rule);
|
| 157 |
+
}
|
| 158 |
+
}
|
| 159 |
+
|
| 160 |
+
/**
|
| 161 |
+
* One view, host copy vs local copy. Returns the host view UNTOUCHED unless
|
| 162 |
+
* the local copy is a recent in-flight edit the host copy provably lags β
|
| 163 |
+
* then the host view keeps everything EXCEPT `filters`/`filterConj`, which
|
| 164 |
+
* come from the local copy (the user's completed question). The tree is taken
|
| 165 |
+
* WHOLESALE rather than leaf-spliced: the first valueless echo often predates
|
| 166 |
+
* the leaf entirely (the rule was still a column condition, or did not exist),
|
| 167 |
+
* and re-inserting a leaf at a guessed position into someone's nested groups
|
| 168 |
+
* would answer a question nobody asked once it resolves.
|
| 169 |
+
*/
|
| 170 |
+
export function reconcileEchoView(
|
| 171 |
+
host: SavedView,
|
| 172 |
+
local: SavedView | undefined,
|
| 173 |
+
localSavedAt: number | undefined,
|
| 174 |
+
now: number
|
| 175 |
+
): SavedView {
|
| 176 |
+
if (!local || localSavedAt == null) return host;
|
| 177 |
+
if (now - localSavedAt > ECHO_RECENT_MS) return host;
|
| 178 |
+
|
| 179 |
+
// Wave-7 item W13 (contract C4 as AMENDED) β the DISPLAY half, same recency rule.
|
| 180 |
+
// `config.display` carries the view's mode AND its calendar/kanban field picks; the
|
| 181 |
+
// host stores it only for non-grid modes, so an echo routinely lags this browser's
|
| 182 |
+
// own draft (a pick made seconds ago, or the grid-mode carry that keeps the picks
|
| 183 |
+
// across a mode round trip). A recent local copy whose display differs is that lag;
|
| 184 |
+
// taking the host copy would feed the select its default again β the reported
|
| 185 |
+
// reset-to-"Status" blip, one remount later. A caught-up echo (equal JSON) keeps
|
| 186 |
+
// the HOST object untouched, so nothing churns.
|
| 187 |
+
// ABSENT is a value here: a local draft with NO display means this browser just
|
| 188 |
+
// returned the view to the ref-less grid, and a lagged kanban echo must not flip it
|
| 189 |
+
// back β so the comparison is over the member itself, not only truthy copies.
|
| 190 |
+
let out = host;
|
| 191 |
+
const localDisplay = local.config ? local.config.display : undefined;
|
| 192 |
+
if (
|
| 193 |
+
local.config &&
|
| 194 |
+
JSON.stringify(localDisplay ?? null) !== JSON.stringify(host.config?.display ?? null)
|
| 195 |
+
) {
|
| 196 |
+
const config = { ...host.config };
|
| 197 |
+
if (localDisplay === undefined) delete config.display;
|
| 198 |
+
else config.display = localDisplay;
|
| 199 |
+
out = { ...host, config };
|
| 200 |
+
}
|
| 201 |
+
|
| 202 |
+
// Item 12 (C-LOCK, 2026-08-02) β `cohortLock` needs the SAME splice, and it needs its own
|
| 203 |
+
// because it is a sibling of `display` on ViewConfig, not a member of it: everything this
|
| 204 |
+
// function does not name explicitly is taken from the host wholesale.
|
| 205 |
+
//
|
| 206 |
+
// Without this, locking a view and then receiving a `/workspace` echo that predates the
|
| 207 |
+
// write hands back the pre-lock config β the rail mark disappears and the lock reads as
|
| 208 |
+
// ignored for a round trip. Exactly the blip the display half was written to stop, one key
|
| 209 |
+
// over. ABSENT IS A VALUE here too: a local copy that just UNLOCKED must not be flipped
|
| 210 |
+
// back by a lagged echo that still carries the lock, so the comparison is over the member
|
| 211 |
+
// itself rather than over truthy copies.
|
| 212 |
+
//
|
| 213 |
+
// β Built on `out`, not on `host` β the display splice above may already have replaced it,
|
| 214 |
+
// and rebuilding from `host` here would silently undo that.
|
| 215 |
+
const localLock = local.config ? local.config.cohortLock : undefined;
|
| 216 |
+
if (local.config && localLock !== out.config?.cohortLock) {
|
| 217 |
+
const config = { ...out.config };
|
| 218 |
+
if (localLock === undefined) delete config.cohortLock;
|
| 219 |
+
else config.cohortLock = localLock;
|
| 220 |
+
out = { ...out, config };
|
| 221 |
+
}
|
| 222 |
+
|
| 223 |
+
// β WAVE 32 Β· T24 (R5/C4) β `important` needs THE SAME SPLICE, one key over, and for the
|
| 224 |
+
// identical reason `cohortLock` does: it is a sibling on ViewConfig, and everything this
|
| 225 |
+
// function does not name explicitly is taken from the host wholesale. Without it, marking a
|
| 226 |
+
// view and then receiving a `/workspace` echo that predates the write hands back the unmarked
|
| 227 |
+
// config β the red badge blinks out and the mark reads as ignored for a round trip.
|
| 228 |
+
// β ABSENT IS A VALUE here too: a local copy that just UNMARKED must not be flipped back by a
|
| 229 |
+
// lagged echo still carrying `important: true`, so the comparison is over the member itself.
|
| 230 |
+
// β Built on `out`, never on `host` β the two splices above may already have replaced it.
|
| 231 |
+
const localImportant = local.config ? local.config.important : undefined;
|
| 232 |
+
if (local.config && localImportant !== out.config?.important) {
|
| 233 |
+
const config = { ...out.config };
|
| 234 |
+
if (localImportant === undefined) delete config.important;
|
| 235 |
+
else config.important = localImportant;
|
| 236 |
+
out = { ...out, config };
|
| 237 |
+
}
|
| 238 |
+
|
| 239 |
+
const localFilters = local.config ? local.config.filters : undefined;
|
| 240 |
+
if (!Array.isArray(localFilters) || localFilters.length === 0) return out;
|
| 241 |
+
|
| 242 |
+
const localById = new Map<string, FilterRule>();
|
| 243 |
+
measureLeavesById(localFilters, localById);
|
| 244 |
+
if (localById.size === 0) return out;
|
| 245 |
+
|
| 246 |
+
const hostById = new Map<string, FilterRule>();
|
| 247 |
+
measureLeavesById(host.config ? host.config.filters : undefined, hostById);
|
| 248 |
+
|
| 249 |
+
// Lagged = some measure rule this browser completed is missing or valueless
|
| 250 |
+
// in the host copy. An ACTIVE host twin β even with a different value β is
|
| 251 |
+
// NOT lagged for our purposes: that is the known hold-the-previous-answer
|
| 252 |
+
// window, and fighting it from here would resurrect stale local values.
|
| 253 |
+
let lagged = false;
|
| 254 |
+
for (const [id, leaf] of localById) {
|
| 255 |
+
if (!isRuleActive(leaf)) continue;
|
| 256 |
+
const twin = hostById.get(id);
|
| 257 |
+
if (!twin || !isRuleActive(twin)) {
|
| 258 |
+
lagged = true;
|
| 259 |
+
break;
|
| 260 |
+
}
|
| 261 |
+
}
|
| 262 |
+
if (!lagged) return out;
|
| 263 |
+
|
| 264 |
+
return {
|
| 265 |
+
...out,
|
| 266 |
+
config: {
|
| 267 |
+
...out.config,
|
| 268 |
+
filters: localFilters,
|
| 269 |
+
filterConj: local.config.filterConj ?? host.config.filterConj,
|
| 270 |
+
},
|
| 271 |
+
};
|
| 272 |
+
}
|
web/src/index.css
CHANGED
|
@@ -5654,7 +5654,7 @@ a.cg-map-ctl-b { text-decoration: none; }
|
|
| 5654 |
.cg-dashview {
|
| 5655 |
height: 100%;
|
| 5656 |
overflow: auto;
|
| 5657 |
-
background: var(--lp-
|
| 5658 |
padding: 10px 12px;
|
| 5659 |
display: flex;
|
| 5660 |
flex-direction: column;
|
|
@@ -7024,7 +7024,7 @@ a.cg-map-ctl-b { text-decoration: none; }
|
|
| 7024 |
.lp-boot {
|
| 7025 |
width: 100%;
|
| 7026 |
height: 100%;
|
| 7027 |
-
background: var(--lp-
|
| 7028 |
}
|
| 7029 |
|
| 7030 |
.set-btn-spin {
|
|
@@ -8404,7 +8404,7 @@ a.cg-map-ctl-b { text-decoration: none; }
|
|
| 8404 |
display: flex;
|
| 8405 |
height: 100%;
|
| 8406 |
min-height: 0;
|
| 8407 |
-
background: var(--lp-
|
| 8408 |
color: var(--lp-ink);
|
| 8409 |
font-size: var(--lp-fs-sm);
|
| 8410 |
}
|
|
@@ -9397,7 +9397,7 @@ a.cg-map-ctl-b { text-decoration: none; }
|
|
| 9397 |
min-height: 0;
|
| 9398 |
display: flex;
|
| 9399 |
flex-direction: column;
|
| 9400 |
-
background: var(--lp-
|
| 9401 |
}
|
| 9402 |
.autob-board-note {
|
| 9403 |
margin: 0;
|
|
@@ -12070,7 +12070,7 @@ a.cg-map-ctl-b { text-decoration: none; }
|
|
| 12070 |
scrollbar-gutter: stable;
|
| 12071 |
padding: 34px 44px 56px;
|
| 12072 |
box-sizing: border-box;
|
| 12073 |
-
background: var(--lp-
|
| 12074 |
}
|
| 12075 |
.home-title {
|
| 12076 |
margin: 0 0 20px;
|
|
|
|
| 5654 |
.cg-dashview {
|
| 5655 |
height: 100%;
|
| 5656 |
overflow: auto;
|
| 5657 |
+
background: var(--lp-surface);
|
| 5658 |
padding: 10px 12px;
|
| 5659 |
display: flex;
|
| 5660 |
flex-direction: column;
|
|
|
|
| 7024 |
.lp-boot {
|
| 7025 |
width: 100%;
|
| 7026 |
height: 100%;
|
| 7027 |
+
background: var(--lp-surface);
|
| 7028 |
}
|
| 7029 |
|
| 7030 |
.set-btn-spin {
|
|
|
|
| 8404 |
display: flex;
|
| 8405 |
height: 100%;
|
| 8406 |
min-height: 0;
|
| 8407 |
+
background: var(--lp-surface);
|
| 8408 |
color: var(--lp-ink);
|
| 8409 |
font-size: var(--lp-fs-sm);
|
| 8410 |
}
|
|
|
|
| 9397 |
min-height: 0;
|
| 9398 |
display: flex;
|
| 9399 |
flex-direction: column;
|
| 9400 |
+
background: var(--lp-surface);
|
| 9401 |
}
|
| 9402 |
.autob-board-note {
|
| 9403 |
margin: 0;
|
|
|
|
| 12070 |
scrollbar-gutter: stable;
|
| 12071 |
padding: 34px 44px 56px;
|
| 12072 |
box-sizing: border-box;
|
| 12073 |
+
background: var(--lp-surface);
|
| 12074 |
}
|
| 12075 |
.home-title {
|
| 12076 |
margin: 0 0 20px;
|
web/src/manage-agent/agentsApi.ts
CHANGED
|
@@ -1,143 +1,143 @@
|
|
| 1 |
-
// ---------------------------------------------------------------------------
|
| 2 |
-
// manage-agent / agentsApi.ts β the client half of the channel-agent doors.
|
| 3 |
-
// (wave 33, owner item 10 Β· W33-T38 / W33-T39.)
|
| 4 |
-
//
|
| 5 |
-
// β THE PERMISSION PAYLOAD SHAPE IS THE USER EDITOR'S, ON PURPOSE.
|
| 6 |
-
// `GET /agents/{id}` answers with the SAME `{modules, fields_by_module, perms,
|
| 7 |
-
// perms_v, is_admin}` envelope as `GET /admin/users/{u}/perms`, so
|
| 8 |
-
// `permsModel.parsePermsPayload` parses both and `settings/ModulePermsList`
|
| 9 |
-
// renders both. The owner's requirement was *"exactly like how we toggle
|
| 10 |
-
// permissioning per user"*; ONE payload shape is what makes that true in code
|
| 11 |
-
// rather than in appearance. A second shape here would be a second parser, a
|
| 12 |
-
// second renderer and a second set of defaults within a wave.
|
| 13 |
-
//
|
| 14 |
-
// β THE CLIENT HIDES; THE SERVER FORBIDS. Every door below is admin-gated
|
| 15 |
-
// server-side. Nothing in this file is a permission check.
|
| 16 |
-
// ---------------------------------------------------------------------------
|
| 17 |
-
|
| 18 |
-
import { API_V1, CREDENTIALS } from "../apiContract";
|
| 19 |
-
import type { ApiResult } from "../settings/settingsApi";
|
| 20 |
-
|
| 21 |
-
/** One configured channel bot, as the list door reports it. */
|
| 22 |
-
export interface ChannelAgent {
|
| 23 |
-
id: string;
|
| 24 |
-
/** The Slack conversation id (`Cβ¦`) β the IDENTITY. A channel can be renamed;
|
| 25 |
-
* its id cannot, and binding a permission wall to a display name is how a
|
| 26 |
-
* rename silently re-points a grant. */
|
| 27 |
-
channel: string;
|
| 28 |
-
/** What Slack calls it today. DISPLAY ONLY, and may be empty. */
|
| 29 |
-
channelName: string;
|
| 30 |
-
label: string;
|
| 31 |
-
active: boolean;
|
| 32 |
-
/**
|
| 33 |
-
* β W33-T67 β may this bot COMMIT a mutation, or only propose one? Defaults
|
| 34 |
-
* TRUE (a human must approve). It is the one setting here whose wrong value
|
| 35 |
-
* cannot be undone by revoking the bot afterwards: the write already happened.
|
| 36 |
-
*/
|
| 37 |
-
writeApproval: boolean;
|
| 38 |
-
/** One sentence for the list row β "3 of 7 databases, 2 restricted" β computed
|
| 39 |
-
* server-side, because the alternative is one round trip per row to fill one
|
| 40 |
-
* cell (the same reason `AdminUser.access` exists). */
|
| 41 |
-
summary?: string;
|
| 42 |
-
}
|
| 43 |
-
|
| 44 |
-
export interface AgentListPayload {
|
| 45 |
-
agents: ChannelAgent[];
|
| 46 |
-
/**
|
| 47 |
-
* Does this deployment hold Slack credentials at all? FALSE β the pane says so
|
| 48 |
-
* instead of offering a control that cannot work. β It is NOT a permission and
|
| 49 |
-
* must never be read as one β the routes refuse a non-admin regardless.
|
| 50 |
-
*/
|
| 51 |
-
configured: boolean;
|
| 52 |
-
}
|
| 53 |
-
|
| 54 |
-
async function call<T>(
|
| 55 |
-
path: string,
|
| 56 |
-
init?: RequestInit & { body?: string }
|
| 57 |
-
): Promise<ApiResult<T>> {
|
| 58 |
-
try {
|
| 59 |
-
const res = await fetch(`${API_V1}${path}`, {
|
| 60 |
-
credentials: CREDENTIALS,
|
| 61 |
-
headers: init?.body ? { "Content-Type": "application/json" } : undefined,
|
| 62 |
-
...init,
|
| 63 |
-
});
|
| 64 |
-
if (res.status === 204) return { ok: true, data: undefined as T };
|
| 65 |
-
let body: unknown = null;
|
| 66 |
-
try {
|
| 67 |
-
body = await res.json();
|
| 68 |
-
} catch {
|
| 69 |
-
/* an empty body is normal on 204; a parse failure is not fatal here */
|
| 70 |
-
}
|
| 71 |
-
if (!res.ok) {
|
| 72 |
-
const err = (body as { error?: { message?: string } } | null)?.error;
|
| 73 |
-
// A 5xx message is never surfaced verbatim β a server stack trace behind a
|
| 74 |
-
// login is still a leak. Same rule as `settingsApi.call`.
|
| 75 |
-
const message =
|
| 76 |
-
res.status >= 500
|
| 77 |
-
? "Something went wrong on our side. Try again in a moment."
|
| 78 |
-
: err?.message ||
|
| 79 |
-
(res.status === 403
|
| 80 |
-
? "Administrators only."
|
| 81 |
-
: "That change could not be saved.");
|
| 82 |
-
return { ok: false, status: res.status, message };
|
| 83 |
-
}
|
| 84 |
-
return { ok: true, data: body as T };
|
| 85 |
-
} catch {
|
| 86 |
-
return { ok: false, status: 0, message: "The server could not be reached." };
|
| 87 |
-
}
|
| 88 |
-
}
|
| 89 |
-
|
| 90 |
-
export function listAgents(): Promise<ApiResult<AgentListPayload>> {
|
| 91 |
-
return call<AgentListPayload>("/agents");
|
| 92 |
-
}
|
| 93 |
-
|
| 94 |
-
export function createAgent(body: {
|
| 95 |
-
channel: string;
|
| 96 |
-
channelName?: string;
|
| 97 |
-
label?: string;
|
| 98 |
-
}): Promise<ApiResult<{ agent: ChannelAgent }>> {
|
| 99 |
-
return call<{ agent: ChannelAgent }>("/agents", {
|
| 100 |
-
method: "POST",
|
| 101 |
-
body: JSON.stringify(body),
|
| 102 |
-
});
|
| 103 |
-
}
|
| 104 |
-
|
| 105 |
-
/** The agent PLUS the permission envelope β parsed by `parsePermsPayload`. */
|
| 106 |
-
export function getAgentPerms(id: string): Promise<ApiResult<unknown>> {
|
| 107 |
-
return call<unknown>(`/agents/${encodeURIComponent(id)}`);
|
| 108 |
-
}
|
| 109 |
-
|
| 110 |
-
/**
|
| 111 |
-
* WHOLE-RECORD REPLACE, exactly like `putUserPerms`. EVERY module the server declared is present
|
| 112 |
-
* in `perms`, including untouched ones: a key omitted from a replace is a DELETION.
|
| 113 |
-
* `permsModel.toPutBody` is the only sanctioned way to build this body.
|
| 114 |
-
*
|
| 115 |
-
* β IT NO LONGER DROPS ANYTHING, and the sentence that said it did has been corrected rather than
|
| 116 |
-
* left (W36-T22 / contract C2, reported by lane C as C-11). `enforced` is DELETED from the payload:
|
| 117 |
-
* every governed database is emitted, `ut_*` included, because once every database is walled a
|
| 118 |
-
* flag distinguishing walled from unwalled is a lie with a green gate behind it. A comment naming
|
| 119 |
-
* a rule that is gone is how the next wave re-derives it [[two-gates-can-assert-opposite-things]].
|
| 120 |
-
*/
|
| 121 |
-
export function putAgentPerms(
|
| 122 |
-
id: string,
|
| 123 |
-
body: { perms: Record<string, unknown> }
|
| 124 |
-
): Promise<ApiResult<unknown>> {
|
| 125 |
-
return call<unknown>(`/agents/${encodeURIComponent(id)}/perms`, {
|
| 126 |
-
method: "PUT",
|
| 127 |
-
body: JSON.stringify(body),
|
| 128 |
-
});
|
| 129 |
-
}
|
| 130 |
-
|
| 131 |
-
export function patchAgent(
|
| 132 |
-
id: string,
|
| 133 |
-
patch: Partial<Pick<ChannelAgent, "label" | "active" | "writeApproval" | "channelName">>
|
| 134 |
-
): Promise<ApiResult<{ agent: ChannelAgent }>> {
|
| 135 |
-
return call<{ agent: ChannelAgent }>(`/agents/${encodeURIComponent(id)}`, {
|
| 136 |
-
method: "PATCH",
|
| 137 |
-
body: JSON.stringify(patch),
|
| 138 |
-
});
|
| 139 |
-
}
|
| 140 |
-
|
| 141 |
-
export function deleteAgent(id: string): Promise<ApiResult<void>> {
|
| 142 |
-
return call<void>(`/agents/${encodeURIComponent(id)}`, { method: "DELETE" });
|
| 143 |
-
}
|
|
|
|
| 1 |
+
// ---------------------------------------------------------------------------
|
| 2 |
+
// manage-agent / agentsApi.ts β the client half of the channel-agent doors.
|
| 3 |
+
// (wave 33, owner item 10 Β· W33-T38 / W33-T39.)
|
| 4 |
+
//
|
| 5 |
+
// β THE PERMISSION PAYLOAD SHAPE IS THE USER EDITOR'S, ON PURPOSE.
|
| 6 |
+
// `GET /agents/{id}` answers with the SAME `{modules, fields_by_module, perms,
|
| 7 |
+
// perms_v, is_admin}` envelope as `GET /admin/users/{u}/perms`, so
|
| 8 |
+
// `permsModel.parsePermsPayload` parses both and `settings/ModulePermsList`
|
| 9 |
+
// renders both. The owner's requirement was *"exactly like how we toggle
|
| 10 |
+
// permissioning per user"*; ONE payload shape is what makes that true in code
|
| 11 |
+
// rather than in appearance. A second shape here would be a second parser, a
|
| 12 |
+
// second renderer and a second set of defaults within a wave.
|
| 13 |
+
//
|
| 14 |
+
// β THE CLIENT HIDES; THE SERVER FORBIDS. Every door below is admin-gated
|
| 15 |
+
// server-side. Nothing in this file is a permission check.
|
| 16 |
+
// ---------------------------------------------------------------------------
|
| 17 |
+
|
| 18 |
+
import { API_V1, CREDENTIALS } from "../apiContract";
|
| 19 |
+
import type { ApiResult } from "../settings/settingsApi";
|
| 20 |
+
|
| 21 |
+
/** One configured channel bot, as the list door reports it. */
|
| 22 |
+
export interface ChannelAgent {
|
| 23 |
+
id: string;
|
| 24 |
+
/** The Slack conversation id (`Cβ¦`) β the IDENTITY. A channel can be renamed;
|
| 25 |
+
* its id cannot, and binding a permission wall to a display name is how a
|
| 26 |
+
* rename silently re-points a grant. */
|
| 27 |
+
channel: string;
|
| 28 |
+
/** What Slack calls it today. DISPLAY ONLY, and may be empty. */
|
| 29 |
+
channelName: string;
|
| 30 |
+
label: string;
|
| 31 |
+
active: boolean;
|
| 32 |
+
/**
|
| 33 |
+
* β W33-T67 β may this bot COMMIT a mutation, or only propose one? Defaults
|
| 34 |
+
* TRUE (a human must approve). It is the one setting here whose wrong value
|
| 35 |
+
* cannot be undone by revoking the bot afterwards: the write already happened.
|
| 36 |
+
*/
|
| 37 |
+
writeApproval: boolean;
|
| 38 |
+
/** One sentence for the list row β "3 of 7 databases, 2 restricted" β computed
|
| 39 |
+
* server-side, because the alternative is one round trip per row to fill one
|
| 40 |
+
* cell (the same reason `AdminUser.access` exists). */
|
| 41 |
+
summary?: string;
|
| 42 |
+
}
|
| 43 |
+
|
| 44 |
+
export interface AgentListPayload {
|
| 45 |
+
agents: ChannelAgent[];
|
| 46 |
+
/**
|
| 47 |
+
* Does this deployment hold Slack credentials at all? FALSE β the pane says so
|
| 48 |
+
* instead of offering a control that cannot work. β It is NOT a permission and
|
| 49 |
+
* must never be read as one β the routes refuse a non-admin regardless.
|
| 50 |
+
*/
|
| 51 |
+
configured: boolean;
|
| 52 |
+
}
|
| 53 |
+
|
| 54 |
+
async function call<T>(
|
| 55 |
+
path: string,
|
| 56 |
+
init?: RequestInit & { body?: string }
|
| 57 |
+
): Promise<ApiResult<T>> {
|
| 58 |
+
try {
|
| 59 |
+
const res = await fetch(`${API_V1}${path}`, {
|
| 60 |
+
credentials: CREDENTIALS,
|
| 61 |
+
headers: init?.body ? { "Content-Type": "application/json" } : undefined,
|
| 62 |
+
...init,
|
| 63 |
+
});
|
| 64 |
+
if (res.status === 204) return { ok: true, data: undefined as T };
|
| 65 |
+
let body: unknown = null;
|
| 66 |
+
try {
|
| 67 |
+
body = await res.json();
|
| 68 |
+
} catch {
|
| 69 |
+
/* an empty body is normal on 204; a parse failure is not fatal here */
|
| 70 |
+
}
|
| 71 |
+
if (!res.ok) {
|
| 72 |
+
const err = (body as { error?: { message?: string } } | null)?.error;
|
| 73 |
+
// A 5xx message is never surfaced verbatim β a server stack trace behind a
|
| 74 |
+
// login is still a leak. Same rule as `settingsApi.call`.
|
| 75 |
+
const message =
|
| 76 |
+
res.status >= 500
|
| 77 |
+
? "Something went wrong on our side. Try again in a moment."
|
| 78 |
+
: err?.message ||
|
| 79 |
+
(res.status === 403
|
| 80 |
+
? "Administrators only."
|
| 81 |
+
: "That change could not be saved.");
|
| 82 |
+
return { ok: false, status: res.status, message };
|
| 83 |
+
}
|
| 84 |
+
return { ok: true, data: body as T };
|
| 85 |
+
} catch {
|
| 86 |
+
return { ok: false, status: 0, message: "The server could not be reached." };
|
| 87 |
+
}
|
| 88 |
+
}
|
| 89 |
+
|
| 90 |
+
export function listAgents(): Promise<ApiResult<AgentListPayload>> {
|
| 91 |
+
return call<AgentListPayload>("/agents");
|
| 92 |
+
}
|
| 93 |
+
|
| 94 |
+
export function createAgent(body: {
|
| 95 |
+
channel: string;
|
| 96 |
+
channelName?: string;
|
| 97 |
+
label?: string;
|
| 98 |
+
}): Promise<ApiResult<{ agent: ChannelAgent }>> {
|
| 99 |
+
return call<{ agent: ChannelAgent }>("/agents", {
|
| 100 |
+
method: "POST",
|
| 101 |
+
body: JSON.stringify(body),
|
| 102 |
+
});
|
| 103 |
+
}
|
| 104 |
+
|
| 105 |
+
/** The agent PLUS the permission envelope β parsed by `parsePermsPayload`. */
|
| 106 |
+
export function getAgentPerms(id: string): Promise<ApiResult<unknown>> {
|
| 107 |
+
return call<unknown>(`/agents/${encodeURIComponent(id)}`);
|
| 108 |
+
}
|
| 109 |
+
|
| 110 |
+
/**
|
| 111 |
+
* WHOLE-RECORD REPLACE, exactly like `putUserPerms`. EVERY module the server declared is present
|
| 112 |
+
* in `perms`, including untouched ones: a key omitted from a replace is a DELETION.
|
| 113 |
+
* `permsModel.toPutBody` is the only sanctioned way to build this body.
|
| 114 |
+
*
|
| 115 |
+
* β IT NO LONGER DROPS ANYTHING, and the sentence that said it did has been corrected rather than
|
| 116 |
+
* left (W36-T22 / contract C2, reported by lane C as C-11). `enforced` is DELETED from the payload:
|
| 117 |
+
* every governed database is emitted, `ut_*` included, because once every database is walled a
|
| 118 |
+
* flag distinguishing walled from unwalled is a lie with a green gate behind it. A comment naming
|
| 119 |
+
* a rule that is gone is how the next wave re-derives it [[two-gates-can-assert-opposite-things]].
|
| 120 |
+
*/
|
| 121 |
+
export function putAgentPerms(
|
| 122 |
+
id: string,
|
| 123 |
+
body: { perms: Record<string, unknown> }
|
| 124 |
+
): Promise<ApiResult<unknown>> {
|
| 125 |
+
return call<unknown>(`/agents/${encodeURIComponent(id)}/perms`, {
|
| 126 |
+
method: "PUT",
|
| 127 |
+
body: JSON.stringify(body),
|
| 128 |
+
});
|
| 129 |
+
}
|
| 130 |
+
|
| 131 |
+
export function patchAgent(
|
| 132 |
+
id: string,
|
| 133 |
+
patch: Partial<Pick<ChannelAgent, "label" | "active" | "writeApproval" | "channelName">>
|
| 134 |
+
): Promise<ApiResult<{ agent: ChannelAgent }>> {
|
| 135 |
+
return call<{ agent: ChannelAgent }>(`/agents/${encodeURIComponent(id)}`, {
|
| 136 |
+
method: "PATCH",
|
| 137 |
+
body: JSON.stringify(patch),
|
| 138 |
+
});
|
| 139 |
+
}
|
| 140 |
+
|
| 141 |
+
export function deleteAgent(id: string): Promise<ApiResult<void>> {
|
| 142 |
+
return call<void>(`/agents/${encodeURIComponent(id)}`, { method: "DELETE" });
|
| 143 |
+
}
|