Memo presence and attachment API parity
CLI 0.90.0 adds the typed presence, selection, live-read and attachment
contracts below. An older installed package may not expose the new methods;
SDK availability does not automatically expose these methods to a production agent.
Implementation lives in src/api/notes.ts, note-presence.ts, note-linger.ts
and note-files.ts in the DreamLake CLI repository. See the exhaustive
API inventory and TypeScript API.
The API returns the same objects printed by CLI --json. Local file handling,
browser opening, signal handlers and login selection belong to the caller.
Bytes stay bytes. SDK imports never execute the CLI or read saved credentials.
SDK availability does not register a built-in agent tool or grant its scopes.
Explicit identity and targets
The CLI uses DREAMLAKE_AGENT_ID and DREAMLAKE_AGENT_NAME; the SDK takes the
same stable task identity explicitly. Attribution is not an account or a grant.
Each request retains the caller's authenticated identity and the server's Memo
ACLs. resolve accepts the CLI's ID, exact slug or exact title in one namespace,
including its 200-note lookup window. Use stable IDs when available; low-level
methods take that resolved ID. There is no cross-namespace fallback.
Selection snapshots
await dl.memos(memoId).presence({selections: true}) and
await notes.presence(noteId, {selections: true}) return the source-bound roster
used by memos presence --selections --json. presenceText accepts the same
option. The exported MemoPresenceOptions and MemoPresenceRoster types describe
this additive contract; older servers omit status fields. See
selection snapshots for fields,
availability and coordinate units. Reading with an empty options object never
publishes presence. Use updatePresence for explicit mutations.
Presence and collaboration commands
| CLI command / option | TypeScript operation | Output and behavior |
|---|---|---|
notes presence NOTE --json | notes.presence(note) | {participants, observedAt} from GET /presence?format=json; never joins or renews. |
notes presence NOTE | notes.presenceText(note) | Server roster text; the CLI adds a trailing newline for display. |
notes visit NOTE --intent TEXT --json | notes.visit(note, {intent}) | Server join receipt {state, ...} without reading the body. Intent is trimmed, 1–280 Unicode code points; omission preserves intent. |
notes select --text TEXT --note NOTE [--section ANCHOR] [-o N] [--hash HASH] --json | notes.selectText(note, {text, section, occurrence, hash}) | Identical note, hash, text, scope, range, occurrence, matches, published, selectionExpiresAt, presenceExpiresAt receipt. |
notes select CSS --note NOTE --json | notes.selectElement(note, css) | {etag, tag, attrs, outer, inner, text}; retained HTML/body inspection without a presence POST. |
notes read NOTE --linger --json [--intent TEXT] [--debounce 2s] [--throttle 2s] [--format diff] [--if-match REV] | notes.linger(note, {signal, intent, debounce, throttle, format, ifMatch}, receive) | Callback receives the CLI JSONL snapshot and update objects. Shared join, heartbeat, source/diff, events and leave logic. |
selectText reads canonical source with lookup attribution suppressed, then
publishes one hash-bound seek. Ranges use Unicode code points; section offsets
are converted to whole-Note ranges. Multiple matches require an occurrence:
positive counts from the beginning, negative from the end. Missing, ambiguous,
stale and unconfirmed selections fail without a success receipt or retry. This
never writes Memo source. Roster presence is separate from browser highlights.
The old presence(note, input) POST overload remains deprecated for
compatibility. Use presence(note) to observe, visit to join once, and
linger to maintain a read. updatePresence supports explicit server actions
for custom clients; the CLI has no manual join/heartbeat/leave subcommands.
Live reads
CLI and SDK share a complete source/hash/revision snapshot, SSE invalidation, debounced incremental diffs, throttled joins/leaves/activity/selections, self filtering and a 20-second lease heartbeat. Duration options accept 250 ms through 5 minutes. There is no idle body/roster polling, hidden reconnect or replay after a stream gap. The stream validates content type, Memo identity, frame size, UTF-8 and a 45-second idle limit. Callback promises provide backpressure. Abort closes the stream and attempts a bounded leave; a leave failure is an error and the lease still expires. SDK code installs no process signal handlers. Historical, partial and HTML reads are not maintained live reads.
notes.events(note, signal, receive) delivers the lower-level validated
observation events without joining, through the explicit transport.
notes.activity(note) returns {activities}. These support live reads; an event
stream is not a substitute for the one-shot roster endpoint.
Attachment commands
files below means notes.files(note). References accept an attachment ID or
exact path. files.resolve(path, includeTrashed) scans all listing pages;
get(id) reads metadata directly. Permission and transport failures are not
converted into empty results.
| CLI command | TypeScript operation | Output and capabilities |
|---|---|---|
notes files list [GLOB] --note NOTE [--trashed] [--content-type MIME] [--limit N] [--offset N] --json | files.list({glob, trashed, contentType, limit, offset}) | {files, total}; same server filter names and pagination. |
notes files upload LOCAL --note NOTE [--path PATH] [--content-type MIME] [--overwrite] --json | files.upload(path, bytesOrStream, {contentType, overwrite, contentLength, signal}) | File row; explicit length supports Node streams. No journaling or replay of raw uploads. |
notes files download FILE --note NOTE [-o LOCAL] [--overwrite] | files.download(ref, signal) | Response with original byte stream, redirect=false; caller owns local overwrite checks and atomic destination writes. |
notes files cat FILE --note NOTE --json | files.cat(ref) / files.text(ref) | {text, etag}; refuses binary content before text retrieval. |
notes files write PATH --note NOTE --text TEXT [--overwrite] [--if-match ETAG] [--content-type MIME] [--idempotency-key KEY] --json | files.write({path, text, overwrite, contentType}, {ifMatch, idempotencyKey}) | File row plus journal operationId when provided. |
notes files mv FILE TO --note NOTE [--overwrite] [--if-match ETAG] --json | files.move(ref, path, {overwrite, ifMatch}) | Updated file row. |
notes files cp FILE TO --note NOTE [--overwrite] [--idempotency-key KEY] --json | files.copy(ref, path, {overwrite, idempotencyKey}) | File row plus journal operationId. |
notes files status OP --note NOTE --json | files.status(operationId) | Validated journal receipt; GET /file-publications/OP. |
notes files reconcile OP --note NOTE --json | files.reconcile(operationId) | Validated receipt; POST /file-publications/OP/reconcile, original bytes and authority. |
notes files cancel OP --note NOTE --json | files.cancel(operationId) | Validated receipt; POST /file-publications/OP/abort, allowed before write authorization only. |
notes files rm FILE --note NOTE [--purge] [--if-match ETAG] --json | files.delete(ref, {purge, ifMatch}) | {id, purged}; default trash, explicit purge. |
notes files restore FILE --note NOTE [--path PATH] --json | files.restore(ref, path) | Restored file row; path lookup includes trash. |
notes files preview FILE --note NOTE [--share] --json | files.preview(ref, share) | {url, kind, previewKind}; session versus explicitly requested shared access. |
notes files preview FILE --note NOTE --revoke | files.revokePreview(ref) | Server {id, shared} acknowledgement; CLI confirmation is on stderr. |
notes files preview FILE --open | files.preview(ref) then caller opens url | Opening a local browser belongs to the caller. |
Deprecated prefix and trash list options remain aliases for an escaped prefix
glob and trashed. Use glob, trashed and contentType in new code.
operation(id, action) remains an alias for the named recovery methods.
Publication and errors
write and copy retain Note-File-Operation-Id in their output, matching CLI
JSON. Their errors retain a known operationId on the original error object.
Never resend bytes after an uncertain result. Inspect the original operation
with the same actor, Memo and namespace. Validate the operation identity,
historicalResult, and state (admitted, write-started, published, or
aborted-before-write). A historical receipt does not prove a new write.
Malformed receipts remain unconfirmed.
Keys are exact 1–256 printable ASCII bytes without surrounding spaces; they are never trimmed or replaced. Idempotency applies to known-byte text write/copy, not raw uploads or media. SDK HTTP errors preserve server status, code, body, request identity and retryability. CLI exit codes are presentation, not SDK return values. Exceptions and lost acknowledgements do not establish no write.
Inline media is separate
notes media upload LOCAL --json maps to notes.media(formData), returning the
same validated {url, contentType, sizeBytes}. Supply a multipart file and
filename; fetch sets its boundary. Media URLs are accessible to anyone holding
them, not governed by a Memo attachment ACL. Uploads are not replayed on redirect.
Verification
src/cli/__tests__/notes-api-parity.test.ts compares CLI JSON and SDK objects
against the same controlled responses. Collaboration regressions cover the
shared live-read engine, Unicode/section selection, ambiguous/stale targets,
stream failure, cancellation and lease cleanup. Attachment tests cover filters,
bytes, journal headers, recovery endpoints, pagination and permission refusal.
Inventory checks verify mapped methods exist; they do not establish production
end-to-end acceptance for every operation.