DreamLake

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

ts
import {createClient} from '@dreamlake/dreamlake-cli/api';
const dl = createClient({remote: 'https://api.dreamlake.ai', token,
  agent: {conversationId: 'codex:one-stable-task-id', name: 'Codex'}});
const notes = dl.notes('acme');
const note = await notes.resolve('release-plan');
const files = notes.files(note);

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 / optionTypeScript operationOutput and behavior
notes presence NOTE --jsonnotes.presence(note){participants, observedAt} from GET /presence?format=json; never joins or renews.
notes presence NOTEnotes.presenceText(note)Server roster text; the CLI adds a trailing newline for display.
notes visit NOTE --intent TEXT --jsonnotes.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] --jsonnotes.selectText(note, {text, section, occurrence, hash})Identical note, hash, text, scope, range, occurrence, matches, published, selectionExpiresAt, presenceExpiresAt receipt.
notes select CSS --note NOTE --jsonnotes.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

ts
const stop = new AbortController();
await notes.linger(note, {signal: stop.signal, debounce: '2s', throttle: '2s'},
  async event => {
    if (event.type === 'snapshot') consumeInitial(event.content, event.revision);
    else consumeUpdate(event);
    if (finished()) stop.abort();
  });

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 commandTypeScript operationOutput and capabilities
notes files list [GLOB] --note NOTE [--trashed] [--content-type MIME] [--limit N] [--offset N] --jsonfiles.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] --jsonfiles.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 --jsonfiles.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] --jsonfiles.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] --jsonfiles.move(ref, path, {overwrite, ifMatch})Updated file row.
notes files cp FILE TO --note NOTE [--overwrite] [--idempotency-key KEY] --jsonfiles.copy(ref, path, {overwrite, idempotencyKey})File row plus journal operationId.
notes files status OP --note NOTE --jsonfiles.status(operationId)Validated journal receipt; GET /file-publications/OP.
notes files reconcile OP --note NOTE --jsonfiles.reconcile(operationId)Validated receipt; POST /file-publications/OP/reconcile, original bytes and authority.
notes files cancel OP --note NOTE --jsonfiles.cancel(operationId)Validated receipt; POST /file-publications/OP/abort, allowed before write authorization only.
notes files rm FILE --note NOTE [--purge] [--if-match ETAG] --jsonfiles.delete(ref, {purge, ifMatch}){id, purged}; default trash, explicit purge.
notes files restore FILE --note NOTE [--path PATH] --jsonfiles.restore(ref, path)Restored file row; path lookup includes trash.
notes files preview FILE --note NOTE [--share] --jsonfiles.preview(ref, share){url, kind, previewKind}; session versus explicitly requested shared access.
notes files preview FILE --note NOTE --revokefiles.revokePreview(ref)Server {id, shared} acknowledgement; CLI confirmation is on stderr.
notes files preview FILE --openfiles.preview(ref) then caller opens urlOpening 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.