@lotics/app-sdk 0.69.0 → 0.72.0

package/dist/src/hooks.d.ts

@@ -103,6 +103,18 @@ interface PaginatedQueryState<R> extends QueryStateBase {
 export interface QuerySortKey {
     field_key: string;
     order: "asc" | "desc";
+    /**
+     * Where rows BLANK in this column sit — `"bottom"` when omitted, which is what
+     * you want for "the ones with a value first".
+     *
+     * It earns its place on a MULTI-KEY sort over columns that are blank by
+     * position rather than by accident — a pipeline's per-step date stamps, say,
+     * where the first non-blank column IS the row's rank. Reading such a ladder
+     * from the top with blanks at the bottom orders it furthest-along-first; the
+     * reverse reading needs blanks on TOP, and with only the default there is no
+     * way to express it, so the column can be sorted one way and not the other.
+     */
+    blank_position?: "top" | "bottom";
 }
 /** A filter condition over one output column (wire shape of a filter node). */
 export interface QueryFilterCondition {

package/docs/ai.md

@@ -26,6 +26,7 @@ A declaration carries:
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
 | `model_tier` | Optional model tier — `haiku` \| `sonnet` \| `opus`. Omit (preferred) to follow the platform default tier, resolved at run time. A tier names capability, not a version, so the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
 | `effort_level` | Optional reasoning depth for adaptive-thinking tiers. Requires an explicit `model_tier` pin — effort is tuned per tier |
+| `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default (`"5m"`, Anthropic's own) is right for essentially every agent. `"1h"` is a leveraged bet: it doubles the write price (2x the input rate against 1.25x, both reading back at 0.1x) to buy only the five-minute-to-one-hour band, and an entry nothing re-reads inside the hour was paid for twice over. Declining it is never "uncached" — the same prefix stays cached at the default window. Set `"1h"` only with measured cadence showing runs reliably land in that band, such as a scheduled sweep |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it |
 | `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose) |
 

package/docs/queries.md

@@ -770,10 +770,13 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
   it. Record-link membership (`has_any_of` by id) **works** here; so does `is_current_member`
   on a member column. Traversals / `locked` / `current_member` do not — bake those into the
   template.
-- **`sort`** — `[{ field_key, order }]` over output columns — the typed `QuerySortKey` the hooks
-  accept. The wire sort node also honors `blank_position?: "top" | "bottom"` (blanks default to
-  bottom), but that field is **not** on the typed hook option; reach it only through a raw
-  `rpc("query", { sort })` call.
+- **`sort`** — `[{ field_key, order, blank_position? }]` over output columns — the typed
+  `QuerySortKey` the hooks accept. `blank_position` is `"top" | "bottom"`, defaulting to
+  `"bottom"`. It matters on a **multi-key** sort over columns whose blankness IS the ranking —
+  a pipeline's per-step date stamps, where the first non-blank column gives the row's rung.
+  Listing the ladder top-down with blanks at the bottom orders it furthest-along-first; the
+  ascending reading needs `blank_position: "top"` on every key, and without it that direction
+  cannot be expressed at all.
 - **`limit` / `offset` / keyset `cursor`** — pagination. `useQuery` / `usePaginatedQuery` page by
   `offset` (`limit` clamped to the 10,000-row cap, §10); `useInfiniteQuery` opts into **keyset
   (seek)** by sending `keyset: true` + the prior page's `cursor`, and the server returns the next

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.69.0",
-  "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
+  "version": "0.72.0",
+  "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
     ".": {