@withone/cli 1.50.0 → 1.52.0

package/dist/{migrate-TRUZVAT5.js → migrate-LXDIZMXH.js}

@@ -3,10 +3,10 @@ import {
   dotPathToJsonbExpr,
   memMigrateCommand,
   reviveStringifiedJson
-} from "./chunk-GXOIR3GF.js";
+} from "./chunk-ZOJW6IMU.js";
 import "./chunk-44CV5IMX.js";
 import "./chunk-CLJFSFFM.js";
-import "./chunk-7RV7T5PX.js";
+import "./chunk-Z4KAQGIG.js";
 import "./chunk-C7DWZ7B5.js";
 import "./chunk-SO323PZP.js";
 export {

package/dist/{runtime-2PRVL2NO.js → runtime-HDZCBTWH.js}

@@ -5,7 +5,7 @@ import {
   resetBackendSingleton,
   updateRecord,
   upsertRecord
-} from "./chunk-7RV7T5PX.js";
+} from "./chunk-Z4KAQGIG.js";
 import "./chunk-C7DWZ7B5.js";
 import "./chunk-SO323PZP.js";
 export {

package/dist/{schema-LCRWSFD5.js → schema-SYMG6SRC.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-CLJFSFFM.js";
 import {
   getBackend
-} from "./chunk-7RV7T5PX.js";
+} from "./chunk-Z4KAQGIG.js";
 import "./chunk-C7DWZ7B5.js";
 import "./chunk-SO323PZP.js";
 

package/dist/{sql-HG7R2JML.js → sql-AZDCMY7G.js}

@@ -1,9 +1,9 @@
 import {
   memSqlCommand,
   syncSqlCommand
-} from "./chunk-4WWK3GO5.js";
+} from "./chunk-UV4YYDF3.js";
 import "./chunk-CLJFSFFM.js";
-import "./chunk-7RV7T5PX.js";
+import "./chunk-Z4KAQGIG.js";
 import "./chunk-C7DWZ7B5.js";
 import "./chunk-SO323PZP.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [
@@ -44,6 +44,7 @@
     "@types/node": "^22.13.1",
     "@types/pg": "^8.20.0",
     "tsup": "^8.3.6",
+    "tsx": "^4.23.1",
     "typescript": "^5.7.3"
   },
   "repository": {

package/profiles/fathom/meetings.json

@@ -17,6 +17,10 @@
   "queryParams": {
     "include_action_items": "true"
   },
+  "identityKeys": [
+    { "prefix": "email", "path": "recorded_by.email" },
+    { "prefix": "email", "path": "calendar_invitees[].email" }
+  ],
   "enrich": {
     "actionId": "conn_mod_def::GIpBYFV5Mog::G6aag6ykQ-uD6XCeUUnq7Q",
     "pathVars": {

package/profiles/gmail/gmailThreads.json

@@ -15,6 +15,11 @@
   "defaultLimit": 100,
   "pathVars": { "userId": "me" },
   "queryParams": { "q": "category:primary" },
+  "identityKeys": [
+    { "prefix": "email", "path": "messages[].payload.headers[name=From].value" },
+    { "prefix": "email", "path": "messages[].payload.headers[name=To].value" },
+    { "prefix": "email", "path": "messages[].payload.headers[name=Cc].value" }
+  ],
   "enrich": {
     "actionId": "conn_mod_def::GJ3ok0Eq0R8::AAzgZVLqTg2iBuITKpJLZg",
     "pathVars": { "userId": "me", "id": "{id}" },

package/profiles/google-calendar/events.json

@@ -13,5 +13,9 @@
   },
   "pathVars": { "calendarId": "primary" },
   "defaultLimit": 250,
-  "limitParam": "maxResults"
+  "limitParam": "maxResults",
+  "identityKeys": [
+    { "prefix": "email", "path": "organizer.email" },
+    { "prefix": "email", "path": "attendees[].email" }
+  ]
 }

package/skills/one/SKILL.md

@@ -189,10 +189,17 @@ one --agent mem search "deadline"                       # hybrid if key set, els
 one --agent mem list note --limit 20
 one --agent mem link <from-id> <to-id> relates_to --bi
 
-# Identity keys (first-class column, NOT data). Unique across ACTIVE records;
-# archiving a record frees its keys. `mem update '{"keys":[...]}'` is rejected.
-one --agent mem key <id> --add email:x@y.com            # add/--remove/--set
-one --agent mem find-by-source email:x@y.com            # prefers the active owner
+# Merge keys — the `keys[]` column (first-class, NOT data). Unique across ACTIVE
+# records; archiving a record frees its keys. `mem update '{"keys":[...]}'` is rejected.
+one --agent mem key <id> --add email:x@y.com            # add/--remove/--set — EDITS keys[]
+one --agent mem find-by-source attio/attioPeople:abc-1  # ONE record (prefers the active owner)
+
+# Identity keys — cross-platform lookup. READ-ONLY query, does not edit anything.
+# Spans BOTH `keys[]` (record IS the entity) and `identity_keys[]` (record INVOLVES
+# the entity: Gmail thread From/To/Cc, calendar attendees — never merges).
+one --agent mem find-by-key email:jane@acme.com                # every record involving this person
+one --agent mem find-by-key email:jane@acme.com --type gmail/gmailThreads
+one --agent mem find-by-key email:a@x.com email:b@y.com        # intersection — records with BOTH
 
 # Backfill searchable_text (no embedding provider needed) — fixes NULL/noisy text
 one --agent mem reindex --searchable --type attio/attioPeople
@@ -202,6 +209,33 @@ one --agent mem status                                  # backend, provider, _up
 one --agent mem doctor                                  # full health report
 ```
 
+**Don't confuse `mem key` with `mem find-by-key`.** `mem key` WRITES the merge column (`keys[]`) on one record — adding a key another active record already owns is an error, and `--set` replaces the whole array. `mem find-by-key` only READS, across both key columns. If you want "show me everything about this person", you always want `find-by-key`.
+
+`find-by-key` agent output is grouped by record type:
+
+```json
+{
+  "keys": ["email:jane@acme.com"],
+  "total": 13,
+  "truncated": false,
+  "fetchCap": 2000,
+  "perTypeLimit": 10,
+  "byType": {
+    "attio/attioPeople": { "count": 1,  "items": [ {"id": "...", "type": "...", "data": {}, "keys": ["attio/attioPeople:J1", "email:jane@acme.com"], "updated_at": "..."} ] },
+    "gmail/gmailThreads": { "count": 12, "items": [] }
+  }
+}
+```
+
+`items` are whole mem records. `keys` and `identity_keys` are OMITTED, not `[]`, when the record has none — the contact above matched on `keys[]` and so carries no `identity_keys` field at all. Always read them as `(item.identity_keys ?? [])`.
+
+Read it in this order:
+
+1. **`truncated`** — if `true`, more than `fetchCap` (2000) records matched. `total` and every `count` are then floors, and because rows come back ordered by type, whole types sorting after the cut are MISSING from `byType` entirely. Re-run with `--type <type>` to get an accurate answer; do not report the counts as-is.
+2. **`total` / `count`** — ungrouped and per-type match counts (accurate when `truncated` is `false`).
+3. **`items`** — whole mem records, same fields as `mem get`, capped at `perTypeLimit` (`--limit`, default 10). `count > items.length` just means display truncation — raise `--limit`.
+4. **`keys`** — the key form that actually matched. Lookups are lowercased/trimmed first (matching how sync writes them), with a one-shot verbatim retry for hand-written mixed-case keys, so `email:Jane@Acme.com` finds `email:jane@acme.com`.
+
 ### Adding OpenAI for semantic search
 
 Stored at the top level of `~/.one/config.json` as `openaiApiKey`, same precedence as `ONE_SECRET` (env > `.onerc OPENAI_API_KEY=...` > project > global). Three equivalent ways to set:
@@ -277,7 +311,16 @@ Without declared paths, the default walker concatenates every string in the reco
 
 **Connections are late-bound** — profiles use `"connection": { "platform": "<name>" }`, not literal `connectionKey` strings. The key is resolved at sync time, so `one add <platform>` (re-auth) doesn't break the profile. For multi-account platforms, add `"tag": "<connection-tag>"` to disambiguate, and create the tagged connection with `one add <platform> --tag <name>`. Don't hardcode connection keys in profiles.
 
-**Advanced features** (enrich, transform, exclude, identityKey, hooks, --full-refresh, alternative backends, embedding tuning): run `one guide memory` or `one guide sync` for the full reference.
+**Cross-platform identity on a profile.** Two separate fields, and picking the wrong one silently mangles data:
+
+- `"identityKey": "properties.email"` — singular. "This record IS this entity." One dot-path; the value lands in `keys[]` and MERGES records for the same entity across platforms (HubSpot + Attio for one person collapse into a single record).
+- `"identityKeys": [{"prefix": "email", "path": "attendees[].email"}]` — plural. "This record INVOLVES these people." Paths support `[]` wildcards and a `[name=From]` equality filter (Gmail headers). Values land in the separate `identity_keys[]` column, which does NOT merge — a 20-attendee event stays one event, not 20 contacts. Use this for anything with N participants.
+
+Both are queryable with `one --agent mem find-by-key <prefix>:<value>`.
+
+**Enriching profiles** (`gmail/gmailThreads`, `fathom/meetings`) sync in two phases: a list pass, then a detail pass that fetches full bodies/transcripts. Two things follow. Enrichment happens **once per record** — phase 2 only visits rows it has never enriched, and `--full-refresh` does *not* reset that, so re-running a sync will not refresh detail content (delete `.one/sync/data/<platform>.db` to force it). And the list pass never overwrites an enriched record: `data` merges rather than replaces, and `searchable_text` / `identity_keys[]` are left alone. `sync run` reports these as `memPreserved`. So on an enriching profile, a record whose upstream *detail* changed will look stale until the mirror is cleared — that is expected, not a sync failure.
+
+**Advanced features** (enrich, transform, exclude, hooks, --full-refresh, alternative backends, embedding tuning): run `one guide memory` or `one guide sync` for the full reference.
 
 ## Beyond Single Actions
 

package/skills/one/references/flows.md

@@ -478,10 +478,12 @@ e.g. if sub-flow `enrich-customer` has a step `load` that returns `{ TEAM: "acme
 {
   "id": "analyze",
   "type": "bash",
-  "bash": { "command": "cat /tmp/data.json | claude --print 'Analyze this' --output-format json", "timeout": 180000, "parseJson": true }
+  "bash": { "command": "cat /tmp/data.json | claude --print 'Analyze this' --output-format json", "timeout": 180000, "parseEnvelope": true }
 }
 ```
 
+**Parsing output.** `parseJson: true` parses stdout as JSON (and strips outer code fences). For **`claude --print --output-format json`** steps use **`parseEnvelope: true`** instead — `claude` wraps the model's answer in a CLI envelope `{ "type": "result", "result": "```json\n{...}\n```" }`, and `parseEnvelope` unwraps `.result`, strips the inner code fences, drops any preamble/trailer text, and parses the inner JSON as `$.steps.<id>.output`. If the unwrapped payload isn't valid JSON the step fails (no silently-broken data). No more hand-rolled `unwrap()` helpers in code steps.
+
 **Safe interpolation.** Plain `{{$.input.x}}` does string substitution and is **unsafe** for bash — values containing quotes, `$`, backticks, `&`, etc. will break the command (or worse). Use the `q` helper to POSIX-shell-quote the value:
 
 ```json
@@ -665,8 +667,8 @@ Each substep inside `parallel.steps` must have the full step schema: `id`, `name
 
 When raw data needs analysis, use this pattern:
 1. `file-write` — save data to temp file (API responses are too large to inline)
-2. `bash` — call `claude --print` to analyze (set timeout to 180000+, use `--output-format json`)
-3. `code` — parse and structure the AI output for downstream steps
+2. `bash` — call `claude --print` to analyze (set timeout to 180000+, use `--output-format json` and `"parseEnvelope": true` so `$.steps.<id>.output` is the clean parsed JSON)
+3. `code` — structure the AI output for downstream steps (no manual envelope unwrap needed — `parseEnvelope` already did it)
 
 ## CLI Commands