@lotics/app-sdk 0.56.0 → 0.56.1

package/AGENTS.md

@@ -20,7 +20,7 @@ signature; open the file.**
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, preview pairing, filter operators, the server-side delivery bounds. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
-| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — images/PDFs are perceived natively, Word/Excel/CSV/text are materialized into the run; no reader tool to declare. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen. |
 | [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 

package/dist/src/upload/optimize.d.ts

@@ -1,10 +1,11 @@
 /**
  * Browser-side image compression for app uploads.
  *
- * Phone-camera photos are huge (4–10 MB HEIC/JPEG) but documents only need
- * legible bytes, not megapixel ones. Resize to ≤1280px on the long edge and
- * re-encode as JPEG at q=0.75 before uploading — typically 10–20× smaller
- * with no visible quality loss for the doc-scan use case.
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) and no document needs
+ * megapixels. Resize to ≤1568px on the long edge — the vision model's own
+ * working resolution, above which the provider downsamples anyway — and
+ * re-encode as JPEG at q=0.9, which keeps small glyphs (container numbers,
+ * invoice lines) legible to a reader and to an extraction agent.
  *
  * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
  * pass through unchanged. Falls through gracefully on any browser API gap

package/dist/src/upload/optimize.js

@@ -1,10 +1,11 @@
 /**
  * Browser-side image compression for app uploads.
  *
- * Phone-camera photos are huge (4–10 MB HEIC/JPEG) but documents only need
- * legible bytes, not megapixel ones. Resize to ≤1280px on the long edge and
- * re-encode as JPEG at q=0.75 before uploading — typically 10–20× smaller
- * with no visible quality loss for the doc-scan use case.
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) and no document needs
+ * megapixels. Resize to ≤1568px on the long edge — the vision model's own
+ * working resolution, above which the provider downsamples anyway — and
+ * re-encode as JPEG at q=0.9, which keeps small glyphs (container numbers,
+ * invoice lines) legible to a reader and to an extraction agent.
  *
  * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
  * pass through unchanged. Falls through gracefully on any browser API gap
@@ -15,8 +16,10 @@
  * dependency-free (no logger, no UploadIntent abstraction) so the SDK ships
  * as a single drop-in.
  */
-const MAX_IMAGE_DIMENSION_PX = 1280;
-const JPEG_QUALITY = 0.75;
+// MIRRORS `@lotics/shared/image_policy` — the SDK ships dependency-free so it
+// cannot import it. Change both together.
+const MAX_IMAGE_DIMENSION_PX = 1568;
+const JPEG_QUALITY = 0.9;
 const CONVERTIBLE_EXTENSION_PATTERN = /\.(heic|heif|png|webp)$/i;
 export async function optimizeImageForUpload(file) {
     const format = getOptimizableFormat(file);

package/docs/ai.md

@@ -20,7 +20,7 @@ A declaration carries:
 | Field | Meaning |
 |---|---|
 | `instructions` | System instructions — the task the agent performs per run |
-| `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. **This is the capability boundary** — the run can use nothing else. May be empty for a pure-reasoning agent |
+| `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. **This is the capability boundary** — the run can use nothing else. May be empty — including for an agent that reads documents, since a [`file` input carries its own content](#file-inputs--what-the-agent-can-actually-see) |
 | `model_id` | The chat model the agent runs on |
 | `effort_level` | Optional reasoning depth for adaptive-thinking models |
 | `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 |
@@ -181,9 +181,21 @@ On recovery, `output` adopts the row's output **only when it is an object** (a s
 
 Sessions are scoped to the authenticated member who ran them: two members using the same `sessionId` string share nothing, and a member can never read or extend another member's thread.
 
-### File inputs → vision
+### File inputs — what the agent can actually see
 
-A declared `file` input (single or `multi`) is materialized into the model's native perception when the type supports it: **`image/*` becomes a vision part, `application/pdf` a document part** — the agent literally sees the file, no OCR tooling needed. Any other type (docx, xlsx, csv, …) is passed as a `file_id` reference instead; the agent can only open it if a file-reading tool is in its declared `tool_names`. Every file in a `multi` input is materialized — nothing is collapsed to the first. Get the ids from [`useFileUpload` / `useAttachments`](./files.md).
+**A `file` input carries its own content. You do not declare a tool to read it.**
+
+| Tier | Types | How the agent gets it |
+|---|---|---|
+| **Perceived natively** | `image/*`, `application/pdf` | A vision / document part — the agent literally sees it |
+| **Materialized** | Word (`.docx`/`.doc`), Excel (`.xlsx`/`.xls`), CSV, and text (`.txt`, `.md`, `.json`, `.eml`, `.html`, `.xml`, `.yaml`) | Read server-side by the same engines `view_files` uses and inlined into the run's message, truncated at 40,000 characters with the agent told when that happened |
+| **Unreadable** | Archives, audio, video | The run fails immediately, naming the file — a fact about the upload, not a gap in your configuration |
+
+Every file in a `multi` input is materialized — nothing is collapsed to the first. Get the ids from [`useFileUpload` / `useAttachments`](./files.md).
+
+**Why no tool:** the content ends up in the agent's context either way, so making it fetch what the server already holds costs a model round-trip and buys nothing. It also keeps the capability boundary tight — an agent that reads its own input never gains the ability to read *other* files in the workspace.
+
+**When to add a tool anyway.** Only to reach *past* what was inlined. A spreadsheet is materialized at 100 rows × 50 columns per sheet and a Word file at 1,000 elements; overflow is reported, never silent. If the agent must read row 4,000 of a large sheet, add `excel_get_range` / `excel_find_cells` (or `view_files` for an ad-hoc second look at a different file).
 
 ### Auth, quota, and bounds
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.56.0",
+  "version": "0.56.1",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {