Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
Download web/src/query/queryApi.ts from fsanyoto/runloopable: direct link, hf CLI and curl.
- Browser
- Download file 32.8 kB
-
https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/query/queryApi.ts
- Command line
-
hf download hf://spaces/fsanyoto/runloopable/web/src/query/queryApi.ts
-
curl -L -o queryApi.ts https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/query/queryApi.ts
32.8 kB
| // Query's public contract. Assistant owns the conversation; Query owns only the | |
| // immutable, per-user artefacts the conversation creates. | |
| import { API_V1, CREDENTIALS } from "../apiContract"; | |
| export type Result<T> = | |
| | { ok: true; value: T } | |
| | { ok: false; status: number; message: string; code?: string; sentence?: string }; | |
| /** C2: the one sentence a failed or refused Assistant turn shows, per server code. */ | |
| export const REFUSAL_SENTENCES: Readonly<Record<string, string>> = { | |
| assistant_forbidden: "You do not have access to that database.", | |
| query_source_unavailable: "That source is still syncing. Try again in a few minutes.", | |
| source_needs_filter: "That question needs every row at once. Add a filter or ask for a total.", | |
| provider_unreachable: "The model did not answer. Try again in a moment.", | |
| provider_limited: "The model is busy. Your answer resumes shortly.", | |
| store_unavailable: "Loopable could not reach its store. Try again in a moment.", | |
| question_too_long: "That question is too long. Shorten it and send it again.", | |
| semantic_field_unapproved: "That field is not approved for answers yet. Ask an Administrator.", | |
| session_expired: "Your session ended. Sign in again.", | |
| }; | |
| export const REFUSAL_FALLBACK = "This database could not answer right now. Please try again."; | |
| /** C2: an unknown code or no code reads as the fallback sentence. */ | |
| export function refusalSentence(code?: string): string { | |
| return code && Object.prototype.hasOwnProperty.call(REFUSAL_SENTENCES, code) | |
| ? REFUSAL_SENTENCES[code] : REFUSAL_FALLBACK; | |
| } | |
| /** C2 does not fix where the pair sits: read the top level, then `error`, then `detail`. */ | |
| export function refusalPair(body: unknown): { code?: string; message?: string } { | |
| const row = body && typeof body === "object" ? body as Record<string, unknown> : {}; | |
| const layer = (value: unknown) => value && typeof value === "object" ? value as Record<string, unknown> : {}; | |
| const detail = layer(row.detail); | |
| const layers = [row, layer(row.error), detail, layer(detail.error)]; | |
| const first = (key: string) => layers.map((item) => item[key]) | |
| .find((value): value is string => typeof value === "string" && value.length > 0); | |
| return { code: first("code"), message: first("message") }; | |
| } | |
| export interface QuerySource { | |
| database: string; | |
| label: string; | |
| source_kind: string; | |
| source_version: unknown; | |
| retrieved_at: string; | |
| fields: Array<{ key: string; label?: string; type?: string }>; | |
| filters: unknown; | |
| permission_scope_applied: boolean; | |
| } | |
| export interface QueryCitation { | |
| id: string; | |
| href: string; | |
| database: string; | |
| snapshot: { kind: string; version: unknown }; | |
| fields: string[]; | |
| filters: unknown; | |
| permission_scope_applied: boolean; | |
| aggregation: { op: string; field?: string | null }; | |
| contributing_record_count: number; | |
| retrieved_at: string; | |
| } | |
| export interface SavedQuery { | |
| id: string; | |
| viewId: string; | |
| scope: string; | |
| name: string; | |
| /** R20: a label the reader owns. The SPEC beside it stays immutable, which is the whole split. */ | |
| description: string; | |
| kind: string; | |
| question: string; | |
| explain: string; | |
| threadId: string; | |
| createdAt: string; | |
| virtual: true; | |
| source: QuerySource; | |
| view: Record<string, unknown>; | |
| citationIds: string[]; | |
| numeric: { label: string; value: number | null; contributing_record_count: number }; | |
| /** | |
| * ββ W35-T25 Β· CONTRACT C4 (R3) β THE AI'S OWN SPEC, AND WHETHER THIS ONE STILL MATCHES IT. | |
| * | |
| * `original_spec` is written ONCE, at creation, and is what "Revert to AI original" restores. | |
| * `edited` is DERIVED on the server by comparing the two, never stored β so a revert clears the | |
| * badge by construction rather than by remembering to. | |
| * | |
| * β `null` IS A REAL ANSWER AND THE CLIENT MUST HONOUR IT. An artefact created before this wave | |
| * has no original: it reports `edited: false` and offers no Revert. C4 is explicit that a Revert | |
| * with nothing to revert to is worse than an absent one. | |
| * β The snake_case key is contract C4's own spelling, not a slip. It is the wire name both | |
| * halves were specified against and renaming it here would be a silent one-sided change. | |
| */ | |
| original_spec: Record<string, unknown> | null; | |
| edited: boolean; | |
| } | |
| export interface QueryThread { | |
| id: string; | |
| title: string; | |
| createdAt: string; | |
| updatedAt: string; | |
| sources: string[]; | |
| model: string; | |
| activeViewId?: string; | |
| } | |
| export interface QueryMessage { | |
| id: string; | |
| threadId: string; | |
| role: "user" | "assistant"; | |
| content: string; | |
| createdAt: string; | |
| targetDatabase?: string; | |
| sources?: string[]; | |
| requestedModel?: string; | |
| model?: string | null; | |
| reason?: string | null; | |
| viewId?: string | null; | |
| citationIds?: string[]; | |
| numeric?: SavedQuery["numeric"] | null; | |
| /** R20's thumbs. Read by the server's own replay, not only written. */ | |
| provenance?: AnswerProvenance; | |
| rating?: "up" | "down" | null; | |
| ratingReason?: string; | |
| toolCalls?: AgentToolCall[]; | |
| pendingDelete?: ArtifactPendingDelete | null; | |
| artifacts?: string[]; | |
| } | |
| /** The answer basis is a disclosure, never a grant. */ | |
| export type AnswerBasis = "authorized_app_data" | "retrieved_knowledge" | "model_guidance"; | |
| export interface AnswerProvenance { | |
| basis: AnswerBasis; | |
| /** Opaque ids are resolved only against the caller's already-permitted citations. */ | |
| citationIds: string[]; | |
| modelGuidance: boolean; | |
| /** A stable explanation when no permitted source can be named. */ | |
| noneUsedReason?: string; | |
| } | |
| /** | |
| * This sentence is deliberately not inferred from a question, database, record, or citation id. | |
| * It is the deterministic, truthful fallback when a response has no permitted source to show. | |
| */ | |
| export const NO_CITED_SOURCES_REASON = | |
| "No authorized application data or retrieved knowledge was cited for this answer."; | |
| /** | |
| * The only user-facing source footer. Source names and opaque ids never cross this boundary: | |
| * callers may resolve ids to citations they can already see, but the footer states the basis only. | |
| */ | |
| export function answerSourceFooter( | |
| provenance: AnswerProvenance | undefined, | |
| permittedCitations: QueryCitation[], | |
| ): string { | |
| if (permittedCitations.length && provenance?.basis === "authorized_app_data") { | |
| return provenance.modelGuidance | |
| ? "Sources: Authorized application data; model guidance composed the answer." | |
| : "Sources: Authorized application data."; | |
| } | |
| if (permittedCitations.length && provenance?.basis === "retrieved_knowledge") { | |
| return provenance.modelGuidance | |
| ? "Sources: Retrieved knowledge; model guidance composed the answer." | |
| : "Sources: Retrieved knowledge."; | |
| } | |
| const noneUsed = provenance?.noneUsedReason || NO_CITED_SOURCES_REASON; | |
| return provenance?.modelGuidance | |
| ? `Sources: ${noneUsed} Model guidance only.` | |
| : `Sources: ${noneUsed}`; | |
| } | |
| /** | |
| * A source this caller HOLDS, and whether it can actually be asked. | |
| * | |
| * β `permitted` and `answerable` are different questions and the picker needs the second. | |
| * Measured on tenant #0: twelve chips offered, two answerable β the rest are the `ut_odoo_*` | |
| * grids, whose rows live uncapped in the connector mirror and are read THROUGH it, which the | |
| * Assistant's read boundary refuses by design. `reason` is what the chip says instead of making | |
| * the reader spend a prompt to find out. | |
| */ | |
| export interface QuerySourceStatus { | |
| database: string; | |
| answerable: boolean; | |
| reason: string; | |
| } | |
| /** | |
| * A model this deployment OFFERS, and whether it can actually be called. | |
| * | |
| * β The same shape `QuerySourceStatus` uses, for the same reason one control to the left: a | |
| * picker that lists a model whose key is not set spends a click and a turn to be told | |
| * "unavailable" by a server that knew before the click. | |
| */ | |
| export interface QueryModelStatus { | |
| model: string; | |
| available: boolean; | |
| reason: string; | |
| /** | |
| * ββ CONTRACT C5 (W36-T35, published by session E) β THE THREE DECLARATIONS A PICKER NEEDS. | |
| * | |
| * β `toolCalling` IS WHY W36-T34's `done-when` IS EXPRESSIBLE AT ALL: *"a model the ladder | |
| * declares incapable of tool calling is not offered for a tool-calling turn."* That sentence | |
| * needs a DECLARATION to read, not a runtime guess β the retired `_FAILED_GEN` regex, which | |
| * recovered a tool call out of a 400, is the evidence that guessing failed | |
| * [[permitted-is-not-answerable]]. | |
| * β `outOfCredit` IS NOT THE SAME AS `!available`, and collapsing them loses R4's whole point: | |
| * an empty balance is a thing somebody can FIX today, while "not configured on this deployment" | |
| * is a thing they must ask an admin about. The server sends a distinct `reason` for each. | |
| * β ALL THREE DEFAULT PERMISSIVELY on an older server that omits them, for the reason the | |
| * `available` parse states one field up: a missing field must not disable a whole picker. | |
| */ | |
| toolCalling: boolean; | |
| jsonMode: boolean; | |
| outOfCredit: boolean; | |
| } | |
| export interface QueryIndex { | |
| threads: QueryThread[]; | |
| messages: QueryMessage[]; | |
| views: SavedQuery[]; | |
| citations: QueryCitation[]; | |
| models: string[]; | |
| modelStatus: QueryModelStatus[]; | |
| sources: QuerySourceStatus[]; | |
| } | |
| export interface ChatResult { | |
| thread: QueryThread; | |
| userMessage: QueryMessage; | |
| message: QueryMessage; | |
| view: SavedQuery | null; | |
| citations: QueryCitation[]; | |
| toolCalls: AgentToolCall[]; | |
| pendingDelete: ArtifactPendingDelete | null; | |
| artifacts: string[]; | |
| } | |
| export interface ArtifactToolCall { | |
| name: string; args: Record<string, unknown>; | |
| } | |
| export interface AgentToolCall extends ArtifactToolCall { | |
| effect: "read" | "write" | "delete"; ok: boolean; ref: string | null; | |
| } | |
| export interface ArtifactPendingDelete { id: string; summary: string; expiresAt: string | number; } | |
| export interface ArtifactTurnResult { | |
| reply: string; refused: string | null; toolCalls: AgentToolCall[]; | |
| pendingDelete: ArtifactPendingDelete | null; artifacts: string[]; | |
| } | |
| export interface AssistantArtifact { | |
| id: string; kind: "view" | "sheet" | "report" | "run" | "query" | "schedule" | "pdf" | "xlsx" | "image" | "snapshot"; | |
| title: string; ref: string | null; door: "app" | "whatsapp" | "wake"; | |
| createdAt: string; status: "active" | "paused" | "deleted"; | |
| toolCall: ArtifactToolCall; | |
| file_id?: string; mime?: string; link?: string; frozen_at?: string; | |
| actions: Array<"open" | "run" | "pause" | "resume" | "rename" | "delete">; | |
| } | |
| export interface ArtifactIndex { items: AssistantArtifact[]; nextCursor: string | null; } | |
| /** The cross-fence B contract: source reads and virtual workspace writes are separate. */ | |
| export interface QueryVirtualBinding { | |
| artifactId: string; | |
| dataScope: string; | |
| workspaceBinding: { kind: "query"; key: string }; | |
| mutation: QueryMutationPolicy; | |
| source: QuerySource; | |
| view: Record<string, unknown>; | |
| citationIds: string[]; | |
| /** Complete, clickable provenance for this exact virtual artefact. */ | |
| citations: QueryCitation[]; | |
| /* | |
| * β NO `edited` HERE, AND THE ABSENCE IS THE DESIGN (W35-T23 + T25). | |
| * | |
| * A draft of this carried one, because the grid kept the reader's spec in a local bucket and | |
| * needed a flag to decide whether that copy or the server's was current. That flag went stale | |
| * inside a session β `binding` is memoised on the artefact and nothing refetches it after an | |
| * autosave β so the first edit of a session survived a full reload and vanished on an in-session | |
| * remount. The fix was to delete the second store, not to freshen the flag: `view` above IS the | |
| * artefact's spec, and it is the only copy. The `edited` a reader SEES lives on `SavedQuery`, | |
| * where the rail reads it, and the renderer has no business asking. | |
| */ | |
| } | |
| /** | |
| * The Query workspace's mutation policy. | |
| * | |
| * ββ W35-T23 (owner item 4 / R2) β `update` NO LONGER MEANS "REFUSED", and this block is the | |
| * contract, so the change is stated here rather than only where it is enforced. A Query view is a | |
| * live view of its source database: resize, sort, group, hide and row height all write its spec, | |
| * through `POST /query/{qid}/events` and nowhere else. `create` is still refused β an artefact | |
| * holds exactly one view β and `delete` still removes the artefact itself. | |
| * β `QUERY_MUTATION_POLICY.update` is kept in the shape because the wire contract has three | |
| * readers and dropping a member is a breaking change; what it describes is now the refusal a | |
| * mismatched id gets, not every edit. | |
| */ | |
| export type QueryMutationOperation = "create" | "update" | "delete"; | |
| export interface QueryMutationRefusal { | |
| durable: false; | |
| transport: "none"; | |
| code: "query_view_immutable"; | |
| message: string; | |
| } | |
| export interface QueryDeleteMutation { | |
| durable: true; | |
| transport: "query_event"; | |
| endpoint: "POST /query/{workspaceBinding.key}/events"; | |
| event: "view_delete"; | |
| } | |
| export interface QueryMutationPolicy { | |
| create: QueryMutationRefusal; | |
| update: QueryMutationRefusal; | |
| delete: QueryDeleteMutation; | |
| } | |
| export interface QueryMutationResult extends QueryMutationRefusal { | |
| artifactId: string; | |
| workspaceKey: string; | |
| operation: "create" | "update"; | |
| } | |
| const IMMUTABLE_MUTATION: QueryMutationRefusal = { | |
| durable: false, | |
| transport: "none", | |
| code: "query_view_immutable", | |
| // ββ W35-T23 (R2) β THE SENTENCE MOVED WITH THE RULE. It read *"This Query view is immutable. | |
| // Ask the Assistant to create a revised view."* and that is no longer true: a Query view's | |
| // spec is editable now, and the reader who resized a column would have been told to go and ask | |
| // a chatbot. What this refusal still covers is the ONE thing R2 did not open β a SECOND view | |
| // inside an artefact that holds exactly one. | |
| // β The CODE is unchanged (`query_view_immutable`): it is the wire contract three gates and | |
| // the server's own refusal key on, and the reason for the refusal did not change, only its | |
| // scope. Renaming it would be a protocol change dressed as a copy edit. | |
| // "the Assistant" β the rail's own word since W34-T13. Copy that names a module must name it | |
| // the way the reader sees it, or the sentence sends them looking for a door that is not there. | |
| message: "A Query view holds one saved answer, so it cannot take a second view. " | |
| + "Ask the Assistant for another one.", | |
| }; | |
| export const QUERY_MUTATION_POLICY: QueryMutationPolicy = { | |
| create: IMMUTABLE_MUTATION, | |
| update: IMMUTABLE_MUTATION, | |
| delete: { | |
| durable: true, | |
| transport: "query_event", | |
| endpoint: "POST /query/{workspaceBinding.key}/events", | |
| event: "view_delete", | |
| }, | |
| }; | |
| /** The durable Query-only event payload; no source scope is permitted here. */ | |
| export interface QueryWorkspaceEvent { | |
| id?: string; | |
| type: "view_create" | "view_upsert" | "view_delete"; | |
| viewId?: string; | |
| view?: Record<string, unknown>; | |
| } | |
| export interface QueryWorkspaceMutation { | |
| workspaceBinding: { kind: "query"; key: string }; | |
| event: "view_delete"; | |
| deleted: string; | |
| } | |
| export const QUERY_BINDING_EVENT = "aios:query-virtual-binding"; | |
| /** The local refusal B must use for every grid create, update, or delete attempt. */ | |
| export function refuseQueryMutation( | |
| binding: Pick<QueryVirtualBinding, "artifactId" | "workspaceBinding">, | |
| operation: "create" | "update", | |
| ): QueryMutationResult { | |
| return { | |
| ...IMMUTABLE_MUTATION, | |
| artifactId: binding.artifactId, | |
| workspaceKey: binding.workspaceBinding.key, | |
| operation, | |
| }; | |
| } | |
| export function bindingFor(view: SavedQuery, citations: QueryCitation[]): QueryVirtualBinding { | |
| const ids = new Set(view.citationIds); | |
| return { | |
| artifactId: view.id, | |
| dataScope: view.source.database, | |
| workspaceBinding: { kind: "query", key: view.id }, | |
| mutation: QUERY_MUTATION_POLICY, | |
| source: view.source, | |
| view: view.view, | |
| citationIds: view.citationIds, | |
| citations: citations.filter((citation) => ids.has(citation.id) && citation.database === view.source.database), | |
| }; | |
| } | |
| export function errorMessage(status: number, message?: string): string { | |
| if (status >= 500 || !message) { | |
| return status >= 500 | |
| ? "Something went wrong on our side. Try again in a moment." | |
| : `The server answered ${status}.`; | |
| } | |
| return message; | |
| } | |
| // Exported for the Assistant conversation clients (S68-T52): one transport, one error reader. | |
| export async function call<T>(path: string, init: RequestInit, read: (body: unknown) => T): Promise<Result<T>> { | |
| let res: Response; | |
| try { | |
| res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init }); | |
| } catch { | |
| return { ok: false, status: 0, message: "Cannot reach the server.", sentence: refusalSentence() }; | |
| } | |
| const body = (await res.json().catch(() => null)) as unknown; | |
| if (!res.ok) { | |
| const detail = (body as { error?: { message?: string } } | null)?.error?.message; | |
| const { code } = refusalPair(body); | |
| // C2: `sentence` rides beside `message` so the dock reads it without a runtime import of this file. | |
| return { ok: false, status: res.status, message: errorMessage(res.status, detail), ...(code ? { code } : {}), | |
| sentence: refusalSentence(code) }; | |
| } | |
| // C2: a 200 that says `status: "refused"` with a code is a non-answer, not a value. | |
| const refused = (body as { status?: unknown } | null)?.status === "refused" ? refusalPair(body) : {}; | |
| if (refused.code) { | |
| const sentence = refusalSentence(refused.code); | |
| return { ok: false, status: res.status, message: sentence, code: refused.code, sentence }; | |
| } | |
| return { ok: true, value: read(body) }; | |
| } | |
| const sends = (method: string, data: unknown): RequestInit => ({ | |
| method, headers: { "Content-Type": "application/json" }, body: JSON.stringify(data), | |
| }); | |
| const json = (data: unknown): RequestInit => sends("POST", data); | |
| const str = (value: unknown): string => (typeof value === "string" ? value : ""); | |
| const rows = (value: unknown): Record<string, unknown>[] => | |
| Array.isArray(value) ? value.filter((row): row is Record<string, unknown> => !!row && typeof row === "object") : []; | |
| function provenance(value: unknown): AnswerProvenance | undefined { | |
| const row = value as Record<string, unknown> | null; | |
| const basis = str(row?.basis); | |
| if (basis !== "authorized_app_data" && basis !== "retrieved_knowledge" && basis !== "model_guidance") { | |
| return undefined; | |
| } | |
| return { | |
| basis, | |
| citationIds: (Array.isArray(row?.citationIds) ? row.citationIds : []) | |
| .filter((id): id is string => typeof id === "string"), | |
| modelGuidance: row?.modelGuidance === true, | |
| noneUsedReason: str(row?.noneUsedReason) || undefined, | |
| }; | |
| } | |
| function source(value: unknown): QuerySource | null { | |
| const row = value as Record<string, unknown> | null; | |
| if (!row || !str(row.database) || !str(row.label) || !str(row.retrieved_at)) return null; | |
| return { | |
| database: str(row.database), label: str(row.label), source_kind: str(row.source_kind), | |
| source_version: row.source_version, retrieved_at: str(row.retrieved_at), | |
| fields: rows(row.fields).filter((field) => !!str(field.key)).map((field) => ({ | |
| key: str(field.key), label: str(field.label) || undefined, type: str(field.type) || undefined, | |
| })), | |
| filters: row.filters, permission_scope_applied: row.permission_scope_applied === true, | |
| }; | |
| } | |
| function saved(value: unknown): SavedQuery | null { | |
| const row = value as Record<string, unknown> | null; | |
| const src = source(row?.source); | |
| if (!row || !src || !str(row.id) || !str(row.viewId) || !str(row.threadId) || row.virtual !== true) return null; | |
| return { | |
| id: str(row.id), viewId: str(row.viewId), scope: str(row.scope) || src.database, | |
| name: str(row.name) || "Query", description: str(row.description), kind: str(row.kind) || "grid", | |
| question: str(row.question), explain: str(row.explain), threadId: str(row.threadId), | |
| createdAt: str(row.createdAt), virtual: true, source: src, | |
| view: (row.view && typeof row.view === "object" ? row.view : {}) as Record<string, unknown>, | |
| citationIds: (row.citationIds as unknown[] || []).filter((id): id is string => typeof id === "string"), | |
| numeric: ((row.numeric && typeof row.numeric === "object" ? row.numeric : {}) as SavedQuery["numeric"]), | |
| // β ABSENT β NOT EDITED AND NOT REVERTABLE, which is the safe direction: an older server that | |
| // sends neither key leaves the badge off and the control hidden, rather than offering a Revert | |
| // whose endpoint will 409. | |
| original_spec: (row.original_spec && typeof row.original_spec === "object" | |
| ? row.original_spec : null) as Record<string, unknown> | null, | |
| edited: row.edited === true, | |
| }; | |
| } | |
| function message(value: unknown): QueryMessage | null { | |
| const row = value as Record<string, unknown> | null; | |
| const role = str(row?.role); | |
| if (!row || !str(row.id) || !str(row.threadId) || !str(row.content) || !str(row.createdAt) | |
| || (role !== "user" && role !== "assistant")) return null; | |
| return { id: str(row.id), threadId: str(row.threadId), role, content: str(row.content), createdAt: str(row.createdAt), | |
| targetDatabase: str(row.targetDatabase) || undefined, | |
| sources: (row.sources as unknown[] || []).filter((v): v is string => typeof v === "string"), | |
| requestedModel: str(row.requestedModel) || undefined, model: str(row.model) || null, | |
| reason: str(row.reason) || null, viewId: str(row.viewId) || null, | |
| citationIds: (Array.isArray(row.citationIds) ? row.citationIds : []) | |
| .filter((v): v is string => typeof v === "string"), | |
| numeric: (row.numeric && typeof row.numeric === "object" ? row.numeric : null) as QueryMessage["numeric"], | |
| provenance: provenance(row.provenance), | |
| rating: row.rating === "up" || row.rating === "down" ? row.rating : null, | |
| ratingReason: str(row.ratingReason), | |
| ...turnFields(row), | |
| }; | |
| } | |
| function thread(value: unknown): QueryThread | null { | |
| const row = value as Record<string, unknown> | null; | |
| if (!row || !str(row.id) || !str(row.createdAt) || !str(row.updatedAt)) return null; | |
| return { id: str(row.id), title: str(row.title) || "New chat", createdAt: str(row.createdAt), | |
| updatedAt: str(row.updatedAt), sources: (row.sources as unknown[] || []).filter((v): v is string => typeof v === "string"), | |
| model: str(row.model) || "auto", activeViewId: str(row.activeViewId) || undefined }; | |
| } | |
| function citation(value: unknown): QueryCitation | null { | |
| const row = value as Record<string, unknown> | null; | |
| const snap = row?.snapshot as Record<string, unknown> | null; | |
| if (!row || !snap || !str(row.id) || !str(row.href) || !str(row.database) || !str(row.retrieved_at)) return null; | |
| return { id: str(row.id), href: str(row.href), database: str(row.database), | |
| snapshot: { kind: str(snap.kind), version: snap.version }, | |
| fields: (row.fields as unknown[] || []).filter((v): v is string => typeof v === "string"), | |
| filters: row.filters, permission_scope_applied: row.permission_scope_applied === true, | |
| aggregation: (row.aggregation && typeof row.aggregation === "object" ? row.aggregation : {}) as QueryCitation["aggregation"], | |
| contributing_record_count: Number(row.contributing_record_count) || 0, retrieved_at: str(row.retrieved_at) }; | |
| } | |
| export function parseIndex(body: unknown): QueryIndex { | |
| const row = body as Record<string, unknown> | null; | |
| return { | |
| threads: rows(row?.threads).map(thread).filter((v): v is QueryThread => !!v), | |
| messages: rows(row?.messages).map(message).filter((v): v is QueryMessage => !!v), | |
| views: rows(row?.views).map(saved).filter((v): v is SavedQuery => !!v), | |
| citations: rows(row?.citations).map(citation).filter((v): v is QueryCitation => !!v), | |
| models: (row?.models as unknown[] || []).filter((v): v is string => typeof v === "string"), | |
| // β ABSENT β TREATED AS AVAILABLE, the same way an absent source row is treated as answerable: | |
| // the server is the authority and its refusal is still the wall. A client that greyed out | |
| // every model it had not heard about would disable the whole picker the moment this field | |
| // failed to arrive. | |
| modelStatus: rows(row?.modelStatus).filter((item) => !!str(item.model)).map((item) => ({ | |
| model: str(item.model), available: item.available !== false, reason: str(item.reason), | |
| // β `!== false`, not `=== true`: an older server that sends no capability flags must read as | |
| // "capable", or the Agent chat's tool-calling filter would empty its own picker against a | |
| // deployment that is working fine. Same rule the line above already follows. | |
| toolCalling: item.toolCalling !== false, jsonMode: item.jsonMode !== false, | |
| // β AND THIS ONE INVERTS, deliberately: absent means NOT out of credit. Defaulting it the | |
| // other way would paint every model on an older server as broke. | |
| outOfCredit: item.outOfCredit === true, | |
| })), | |
| sources: rows(row?.sources).filter((item) => !!str(item.database)).map((item) => ({ | |
| database: str(item.database), answerable: item.answerable === true, reason: str(item.reason), | |
| })), | |
| }; | |
| } | |
| export function fetchQueries(): Promise<Result<QueryIndex>> { | |
| return call("/query", {}, parseIndex); | |
| } | |
| // The Artifacts page needs only the saved views. `only=views` skips resolving every source. | |
| export function parseViews(body: unknown): SavedQuery[] { | |
| const row = body as Record<string, unknown> | null; | |
| return rows(row?.views).map(saved).filter((v): v is SavedQuery => !!v); | |
| } | |
| export function fetchQueryViews(): Promise<Result<SavedQuery[]>> { | |
| return call("/query?only=views", {}, parseViews); | |
| } | |
| export function submitChat(body: { | |
| question: string; database: string; sources: string[]; threadId?: string; model: string; | |
| }): Promise<Result<ChatResult>> { | |
| return call("/query/chat", json(body), (raw) => { | |
| const row = raw as Record<string, unknown> | null; | |
| return { | |
| thread: thread(row?.thread) as QueryThread, | |
| userMessage: message(row?.userMessage) as QueryMessage, | |
| message: message(row?.message) as QueryMessage, | |
| view: saved(row?.view), | |
| citations: rows(row?.citations).map(citation).filter((v): v is QueryCitation => !!v), | |
| ...turnFields(row), | |
| }; | |
| }); | |
| } | |
| export function deleteQuery(id: string): Promise<Result<true>> { | |
| return call(`/query/${encodeURIComponent(id)}`, { method: "DELETE" }, () => true as const); | |
| } | |
| function turnFields(row: Record<string, unknown> | null) { | |
| const pending = row?.pendingDelete as Record<string, unknown> | null; | |
| return { | |
| toolCalls: rows(row?.toolCalls).filter((tool) => !!str(tool.name)).map((tool) => ({ | |
| name: str(tool.name), args: (tool.args || {}) as Record<string, unknown>, | |
| effect: (tool.effect === "delete" || tool.effect === "write" ? tool.effect : "read") as AgentToolCall["effect"], | |
| ok: tool.ok === true, ref: str(tool.ref) || null, | |
| })), | |
| pendingDelete: pending && str(pending.id) ? { | |
| id: str(pending.id), summary: str(pending.summary), expiresAt: Number(pending.expiresAt), | |
| } : null, | |
| artifacts: (Array.isArray(row?.artifacts) ? row.artifacts : []).filter((id): id is string => typeof id === "string"), | |
| }; | |
| } | |
| export function fetchArtifacts(cursor?: string): Promise<Result<ArtifactIndex>> { | |
| return call(`/artifacts${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`, {}, (raw) => { | |
| const row = raw as Record<string, unknown> | null; | |
| return { items: rows(row?.items) as unknown as AssistantArtifact[], nextCursor: str(row?.nextCursor) || null }; | |
| }); | |
| } | |
| function artifactAction(id: string, action: string): Promise<Result<ArtifactTurnResult>> { | |
| return call(`/artifacts/${encodeURIComponent(id)}/${action}`, json({}), (raw) => { | |
| const row = raw as Record<string, unknown> | null; | |
| return { reply: str(row?.reply), refused: str(row?.refused) || null, ...turnFields(row) }; | |
| }); | |
| } | |
| export const runArtifact = (id: string) => artifactAction(id, "run"); | |
| export const pauseArtifact = (id: string) => artifactAction(id, "pause"); | |
| export const resumeArtifact = (id: string) => artifactAction(id, "resume"); | |
| export function deleteArtifact(id: string): Promise<Result<{ pendingDelete: ArtifactPendingDelete }>> { | |
| return call(`/artifacts/${encodeURIComponent(id)}/delete`, json({}), (raw) => | |
| ({ pendingDelete: turnFields(raw as Record<string, unknown>).pendingDelete as ArtifactPendingDelete })); | |
| } | |
| /** | |
| * ββ R20 β THE THREE DOORS THAT ARE **NOT** `mutateQueryWorkspace`, and the distinction is the | |
| * whole design rather than a routing detail. | |
| * | |
| * `QUERY_MUTATION_POLICY` above is unchanged and still refuses create and update: the generated | |
| * SPEC and its provenance are immutable, because a cited number is only worth citing if the thing | |
| * it was computed from cannot be edited underneath it. What R20 opens is the LABELS beside it, | |
| * and a copy, and a read. Each gets its own named endpoint with a server-side allow-list, because | |
| * `routeQueryViewMutation` refuses `view_upsert` on a query binding LOCALLY, before any request | |
| * leaves the browser: opening that transport would give one question two answers. | |
| */ | |
| export function renameQuery(id: string, patch: { name?: string; description?: string }): Promise<Result<SavedQuery>> { | |
| return call(`/query/${encodeURIComponent(id)}`, sends("PATCH", patch), | |
| (raw) => saved(raw) as SavedQuery); | |
| } | |
| export function duplicateQuery(id: string): Promise<Result<SavedQuery>> { | |
| return call(`/query/${encodeURIComponent(id)}/duplicate`, json({}), (raw) => saved(raw) as SavedQuery); | |
| } | |
| /** | |
| * ββ W35-T25 Β· CONTRACT C4 (R3) β "Revert to AI original". | |
| * | |
| * β IT RESTORES THE VIEW SPEC AND NOTHING ELSE, and the caller must SAY so before it acts. A | |
| * Query view is live now, so a cell the reader changed through it is a real write to a real | |
| * record in the source database; putting the filters back cannot walk that back. R3 requires the | |
| * confirm to state that BEFORE the click, not after. | |
| */ | |
| export function revertQuery(id: string): Promise<Result<SavedQuery>> { | |
| return call(`/query/${encodeURIComponent(id)}/revert`, json({}), (raw) => saved(raw) as SavedQuery); | |
| } | |
| /** | |
| * A DOWNLOAD, not a fetch: an ordinary same-origin link carries the session cookie, and the server | |
| * names the file through `Content-Disposition`. Building a Blob here would mean holding the whole | |
| * export in memory to hand it straight back to the browser. | |
| */ | |
| export function exportQueryHref(id: string): string { | |
| return `${API_V1}/query/${encodeURIComponent(id)}/export`; | |
| } | |
| /** | |
| * β R20's thumbs. `null` CLEARS the rating: a mis-click that cannot be taken back is worse than | |
| * no control, and the server reads a thumbs-down back into the next turn of the same thread, so | |
| * an uncorrected one keeps steering. | |
| */ | |
| /** What the database's own validator would not take, named rather than quietly missing. */ | |
| export interface QuerySaveResult { | |
| scope: string; | |
| viewId: string; | |
| name: string; | |
| dropped: string[]; | |
| } | |
| /** | |
| * β R20: the answer becomes an ordinary view of its own database. | |
| * | |
| * β The server does NOT trust the write's own 200: `view_upsert` returns the same shape when it | |
| * saved and when it silently refused, so it reads the store back and refuses out loud instead. | |
| * There is nothing for this client to retry, which is the point. | |
| */ | |
| export function saveQueryToDatabase(id: string): Promise<Result<QuerySaveResult>> { | |
| return call(`/query/${encodeURIComponent(id)}/save-to-database`, json({}), (raw) => { | |
| const row = raw as Record<string, unknown> | null; | |
| return { | |
| scope: str(row?.scope), viewId: str(row?.viewId), name: str(row?.name), | |
| dropped: (row?.dropped as unknown[] || []).filter((v): v is string => typeof v === "string"), | |
| }; | |
| }); | |
| } | |
| export function rateMessage(id: string, rating: "up" | "down" | null, reason?: string): Promise<Result<QueryMessage>> { | |
| return call(`/query/messages/${encodeURIComponent(id)}/rating`, | |
| json({ rating, ...(reason ? { reason } : {}) }), (raw) => message(raw) as QueryMessage); | |
| } | |
| /** | |
| * The sole mutation path for a virtual Query workspace. This intentionally never falls through | |
| * to the native grid event transport and never sends `dataScope`: the opaque Query key is the authority. | |
| * The server accepts delete and explicitly refuses create/update because AI artefacts are immutable. | |
| */ | |
| export function mutateQueryWorkspace(binding: QueryVirtualBinding, event: QueryWorkspaceEvent): Promise<Result<QueryWorkspaceMutation>> { | |
| const key = binding.workspaceBinding.key; | |
| return call(`/query/${encodeURIComponent(key)}/events`, json({ | |
| workspaceBinding: binding.workspaceBinding, event, | |
| }), (raw) => { | |
| const row = raw as Record<string, unknown> | null; | |
| return { | |
| workspaceBinding: { kind: "query", key: str((row?.workspaceBinding as Record<string, unknown> | null)?.key) }, | |
| event: str(row?.event) as QueryWorkspaceMutation["event"], | |
| deleted: str(row?.deleted), | |
| }; | |
| }); | |
| } | |