@lotics/cli 0.97.0 → 0.99.1

package/dist/src/cli.js

@@ -44165,9 +44165,7 @@ import os2 from "node:os";
 import path7 from "node:path";
 import readline from "node:readline";
 
-// src/client.ts
-import fs from "node:fs";
-import path from "node:path";
+// ../shared/src/transport_error.ts
 function gatewayErrorMessage(status) {
   if (status === 524) {
     return "The request took too long to finish (gateway timeout). It may still be running \u2014 check back in a moment, or try again.";
@@ -44181,6 +44179,10 @@ function transportErrorMessage(status, parsed) {
   const jsonMessage = parsed && typeof parsed.message === "string" ? parsed.message : null;
   return parsed === null || status >= 500 || jsonMessage === null ? gatewayErrorMessage(status) : jsonMessage;
 }
+
+// src/client.ts
+import fs from "node:fs";
+import path from "node:path";
 function findAvailableFilename(dir, filename, reserved) {
   const isTaken = (name) => {
     const full = path.join(dir, name);
@@ -64415,7 +64417,8 @@ var aggregateOperationSchema = external_exports.enum([
   "checked",
   "unchecked",
   "percent_checked",
-  "percent_unchecked"
+  "percent_unchecked",
+  "string_agg"
 ]);
 var OPERATION_FIELD_TYPES = {
   empty: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup"],
@@ -64483,6 +64486,9 @@ var queryOutputColumnSchema = zod_default.object({
   ),
   source_field_key: zod_default.string().optional().describe(
     "Source field this column originates from. Populated alongside source_table_id for passthrough columns."
+  ),
+  computed: zod_default.boolean().optional().describe(
+    "True when the value is DERIVED rather than a passthrough of the addressed field \u2014 a link extraction reads a field on the link TARGET, so the row's own source record is a different table. Such a column may still carry source addressing (it is what resolves labels and option sets), but that addressing is NOT a write target: writable_target is refused on a computed column and on anything that passes one through."
   )
 });
 var queryOutputSchemaSchema = zod_default.object({
@@ -64530,12 +64536,21 @@ var queryProjectionColumnSchema = zod_default.union([
   zod_default.string().describe("Passthrough shorthand: a source field key. Output = the key, type = the field's type."),
   queryProjectionColumnObjectSchema
 ]);
+var STRING_AGG_MAX_VALUES = 100;
+var STRING_AGG_DEFAULT_MAX_VALUES = 20;
 var queryAggregateColumnSchema = zod_default.object({
   output: zod_default.string().describe("Output column name"),
   type: queryColumnTypeSchema.describe("Output column type"),
   operation: aggregateOperationSchema,
   input_column: zod_default.string().optional().describe(
     "Input column to aggregate. Required for non-count operations; ignored for count."
+  ),
+  separator: zod_default.string().max(8).optional().describe('string_agg only. Joins the values. Defaults to ", ".'),
+  distinct: zod_default.boolean().optional().describe(
+    "string_agg only. Collapses repeats \u2014 a group of containers sized 40HC/40HC/20DC aggregates to '20DC, 40HC'. Defaults to true, which is almost always what a summary column wants."
+  ),
+  max_values: zod_default.number().int().min(1).max(STRING_AGG_MAX_VALUES).optional().describe(
+    `string_agg only. Caps how many values are emitted so an unbounded child set cannot produce a giant cell. Defaults to ${STRING_AGG_DEFAULT_MAX_VALUES}. Pair with a \`unique\` aggregate to render an accurate '+N more'.`
   )
 });
 var rankingWindowFunctionSchema = (fn) => zod_default.object({ output: zod_default.string().describe("Output column name"), fn: zod_default.literal(fn) }).strict();
@@ -64892,6 +64907,12 @@ var appAgentDeclarationSchema = zod_default.object({
   knowledge_doc_ids: zod_default.array(zod_default.string().min(1)).optional().describe(
     "Knowledge docs the agent may read, validated at declare time against the app owner's `use` access. Small docs are inlined into the agent's system prompt each run; a doc too large to inline requires the code tools (code_exec) in tool_names and is read by staging it into a code run. Omit for an agent that needs no knowledge."
   ),
+  query_aliases: zod_default.array(zod_default.string().min(1)).optional().describe(
+    "Named queries from this app's manifest the agent may run via `run_app_query`, validated at declare time against the app's own queries. This is the agent's ENTIRE read surface over workspace data \u2014 a template fixes the tables, filters, and projection, so it bounds rows and columns, not just tables. Omit for an agent that reads no records."
+  ),
+  workflow_aliases: zod_default.array(zod_default.string().min(1)).optional().describe(
+    "Workflows from this app's manifest the agent may invoke via `run_app_workflow`, validated at declare time against the app's own workflows. This is the agent's ENTIRE write surface \u2014 the same declared mutation path the app's UI uses, so table hooks and side-effect harvesting apply. Omit for a read-only agent."
+  ),
   model_id: zod_default.string().min(1).optional().describe(
     "Chat model id the agent runs on, validated against ACCEPTED_CHAT_MODEL_IDS. Omit to follow the platform default chat model, resolved at run time \u2014 the preferred choice: the agent tracks model generations with no per-app rewrite. Pin only a deliberate, tested choice."
   ),

package/dist/src/client.d.ts

@@ -1,12 +1,4 @@
 import type { ContractConfigEntry, KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "./package_content_types";
-/**
- * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
- * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
- * 5xx, or a JSON body without a `message` falls back to a body-free,
- * status-derived message. `parsed` is the JSON.parse of the body, or `null`.
- * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
- */
-export declare function transportErrorMessage(status: number, parsed: unknown): string;
 /** One sort key forwarded to the app query RPC (wire shape of a `TableRecordSort` entry). */
 export interface AppQuerySortKey {
     field_key: string;
@@ -89,19 +81,20 @@ export interface ToolInfo {
 }
 /**
  * A single knowledge doc with its HYDRATED body — the shape of
- * `GET /v1/knowledge_docs/{id}`. `content` is resolved server-side from the
- * doc's content file (or the parked column for a legacy row), so this is the
- * one content-read path a non-sandbox client has. `content_file_id` is the
- * concurrency token the REST PATCH echoes; the `update_knowledge` TOOL CASes
- * internally, so a CLI caller never needs to pass it.
+ * `GET /v1/knowledge_docs/{id}`, and the one content-read path a non-sandbox
+ * client has. `content_sha` is the concurrency token the REST PATCH echoes back
+ * as `expected_content_sha`; the `update_knowledge` TOOL CASes internally, so a
+ * CLI caller never needs to pass it.
  */
 export interface KnowledgeDocDetail {
     id: string;
     workspace_id: string;
     name: string;
     description: string;
+    /** Folder address; "" is root. */
+    path: string;
     content: string;
-    content_file_id: string | null;
+    content_sha: string | null;
     files: unknown[];
     created_at: string;
     updated_at: string;

package/dist/src/client.js

@@ -1,36 +1,6 @@
+import { transportErrorMessage } from "@lotics/shared/transport_error";
 import fs from "node:fs";
 import path from "node:path";
-/**
- * A user-facing message for a transport/gateway failure — derived from the HTTP
- * status, never from the response body. A 524 (edge timeout on a long run), any
- * 5xx, or a non-JSON body (an HTML error page) must NOT surface its raw body. In
- * parity (by value, no shared dep) with the published transport in
- * `packages/app-sdk/src/rpc.ts`.
- */
-function gatewayErrorMessage(status) {
-    if (status === 524) {
-        return "The request took too long to finish (gateway timeout). It may still be running — check back in a moment, or try again.";
-    }
-    if (status >= 500) {
-        return "The service is temporarily unavailable. Please try again shortly.";
-    }
-    return "The service returned an unexpected response. Please try again.";
-}
-/**
- * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
- * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
- * 5xx, or a JSON body without a `message` falls back to a body-free,
- * status-derived message. `parsed` is the JSON.parse of the body, or `null`.
- * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
- */
-export function transportErrorMessage(status, parsed) {
-    const jsonMessage = parsed && typeof parsed.message === "string"
-        ? parsed.message
-        : null;
-    return parsed === null || status >= 500 || jsonMessage === null
-        ? gatewayErrorMessage(status)
-        : jsonMessage;
-}
 function findAvailableFilename(dir, filename, reserved) {
     // `reserved` tracks absolute paths claimed by in-flight downloads in the same
     // batch — required for parallel callers because the file may not be on disk

package/docs/knowledge_docs.md

@@ -7,8 +7,8 @@ them on demand** while it works, pulling in only the lines it needs.
 
 They are deliberately **not** injected into the agent wholesale. Bulk-loading every doc into
 every request would burn the context budget and drown the signal. Instead the agent retrieves
-from them through a search funnel, so a 10,000-line tariff book costs nothing until a question
-actually touches it.
+from them line by line — grep, then read — so a 10,000-line tariff book costs nothing until a
+question actually touches it, and a 10MB one is no different.
 
 This is a **capability + usage** guide. For the exact input schema of any tool named here, run
 `lotics tools <tool_name>`.
@@ -34,9 +34,9 @@ This reads the body from your filesystem and creates the doc through `create_kno
 `content` from a file or stdin. Either way, `create_knowledge` takes three things:
 
 - `name` — what it is.
-- `description` — what the doc is **and how to retrieve from it**: its vocabulary, synonyms for
-  colloquial terms, and what to read for detail. This is surfaced when the doc is *found*,
-  before its content is read, so the agent knows whether to open it.
+- `description` — what the doc is **and what to grep it for**: its vocabulary and the synonyms
+  an ambiguous query would use. Surfaced in the tree before any body is read, and truncated at
+  200 characters. See *Write for grep* below.
 - `content` — Markdown.
 
 A new doc is created **owned by you, active in your own agent context, and private** — no one
@@ -61,28 +61,84 @@ So: shared + active → the agent can find and read it. Shared but deactivated
 that member's agent. This is the token economy in action — activation is how a member curates
 which rulebooks their agent carries.
 
-## How an agent uses a doc — catalog, then read
+## How an agent uses a doc — ls, grep, cat
+
+Docs are not injected wholesale. The agent works the corpus like a filesystem, and all three
+verbs respect access + activation, so only docs the caller may use ever surface.
+
+1. **`list_knowledge`** — `ls`. The corpus as a folder tree: name, id, folder, and a truncated
+   description. No bodies.
+2. **`grep_knowledge`** — `grep -rn`. Substring match across every readable doc (or one doc, or
+   one folder), returning **doc, line number, and the matching line**. It runs inside Postgres,
+   so only matching lines cross the wire.
+3. **`read_knowledge`** — `cat` / `sed -n 'X,Yp'`. Read a doc whole or by line range, to see
+   the context around a hit.
+
+Matching is **substring, not ranked** — there is no index and no tokenizer, which is why a
+corpus in any script works and why nothing goes stale. The consequence is that the *agent*
+does the narrowing: a distinctive phrase is sharply selective, a whole question matches
+everything. `grep_knowledge` always reports `total_matches`, so "too broad" is visible and
+cheap to fix.
+
+### Matching options
+
+- **Diacritics fold by default** — `ca phe` matches `cà phê`. `diacritic_insensitive: false` matches
+  tone marks exactly.
+- **Case folds by default**, independently of diacritics. `case_sensitive: true` matches case
+  exactly — useful for an acronym (`NK` vs `nk`) that a folded search would blur.
+- **Whitespace is normalized on both sides.** A body converted from PDF, Word or Excel carries
+  non-breaking spaces, soft hyphens, zero-width marks and padded runs that nobody types into a
+  query; those fold to ordinary single spaces before matching, so a correct search does not return
+  a silent zero on text that is present. Your pattern is normalized the same way.
+- **`regex: true`** treats the pattern as a POSIX regular expression: quantifiers, character
+  classes, alternation, anchors, and **`\y` for a word boundary**. Note `\y`, not `\b` — Postgres
+  spells it differently, and `\b` is rewritten for you rather than silently matching nothing.
+  Literal is the default on purpose: `0901.11.20` as a regex would also match `0901X11Y20`.
 
-Docs are not injected wholesale. The agent finds the right doc from a **catalog**, then reads
-only what it needs. Both steps respect access + activation, so only docs the caller may use ever
-surface.
-
-1. **Catalog** — `list_knowledge` returns every usable doc as `{ id, name, description }` — no
-   bodies. This is why the *description* carries the weight: it is what the agent reads before
-   deciding to open a doc. Write it to sell the doc — its vocabulary, the colloquial synonyms an
-   ambiguous query would use, and what it covers.
-2. **Read** — the chat agent stages the chosen doc's content file into a code run and greps it
-   there (the body arrives as a file to `cat`/`grep`). Over this CLI you read a body directly
-   with `lotics knowledge get <id>`.
-
-Structure your content so a reader lands on the answer without loading the rest:
+```
+grep_knowledge({ pattern: "\\yNK\\y", regex: true, case_sensitive: true })
+```
 
-- Organize under clear Markdown headers.
-- Keep each searchable unit self-contained — a section for prose, **one record per line** for
-  dense/tabular data (a price row, a code entry) — carrying both the terms someone would search
-  for and its answer.
-- Lead with the most-queried fields.
-- Note colloquial synonyms next to official terms, so an ambiguous query still matches.
+### What a result is bounded by
+
+A result carries at most 40.000 characters. Matched lines are admitted first and context fills
+what remains, so an answer is never dropped to make room for a neighbouring line. Anything the
+budget cut is REPORTED — `chars_elided_matches` (an answer was dropped) and
+`context_omitted_matches` (an answer was kept without the context you asked for) mean different
+things and call for different fixes: narrow the pattern, or ask for fewer `context_lines`.
+Individual lines longer than 600 characters are clipped and marked, with `read_knowledge` giving
+the rest.
+
+`total_matches` is always the true total, even when fewer are shown.
+
+## Write for grep — the rules that decide whether an answer is findable
+
+Retrieval addresses **lines**. Every rule below follows from that one fact, and ignoring them
+is the difference between a doc that answers and a doc that merely exists.
+
+- **One self-contained fact per line.** A grep hit returns *that line*. For dense or tabular
+  data — a price row, a tariff code, a charge entry — put the whole record on one line.
+- **Repeat the searchable terms on every line; headings do not carry down.** A line reading
+  `Rate: 15%` under a heading `Roasted coffee` will never match a search for `coffee`. Restate
+  the identifying terms inline, even when it reads redundantly to a human. This is the single
+  rule most often got wrong.
+- **Keep a line under ~600 characters.** Past that the line is truncated in the agent's view
+  and marked as cut; the agent can still `read_knowledge` for the rest, but it costs a round
+  trip. Put the identifying terms early and the long tail late.
+- **Put synonyms and translations on the line itself.** A bilingual row (`Cà phê, đã rang /
+  Coffee, roasted`) matches queries in either language for free. The same trick carries
+  colloquial terms next to official ones.
+- **For prose, keep a rule and its exception close.** A hit returns one line, so a rule on line
+  40 and its exception on line 90 can be retrieved apart. Use `context_lines` when reading, and
+  keep related clauses adjacent when writing.
+
+Markdown headings are ordinary text — useful for a human and for orienting a `read_knowledge`,
+but they carry no retrieval weight of their own.
+
+**The description is the discovery hint.** It is what the agent sees in the tree before it has
+read a byte of the body, so it is the only clue for *what term to grep for*. Write it to name
+the doc's vocabulary — the words that actually appear inside it. Keep it to a sentence: it is
+truncated at 200 characters, and a keyword-stuffed description is cut, not rewarded.
 
 ## Updating a doc — `lotics knowledge update`
 
@@ -95,8 +151,8 @@ Send only the fields you're changing. `--from` / `--content` replaces the body;
 re-reads the current content pointer and version-chains the new body — so there is no version
 token to pass from the CLI. (The chat agent may instead send an `edits` array — anchored
 replace / insert / append — for a surgical change; see `lotics tools update_knowledge`.) Refine
-structure as you learn what users actually ask: add the synonym that failed to match, split the
-section that was too coarse to read.
+structure as you learn what users actually ask: add the synonym that failed to match, split a
+line that was too coarse, restate a term the heading was carrying.
 
 ## Package-managed knowledge
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.97.0",
+  "version": "0.99.1",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {