Fulcra

Get where the user was: at one moment (`time`), or over a range (`start_time` and `end_time`) as one location per sample_rate seconds. Result timestamps include time zones. Always translate them to the user's local time zone when this is known. Args: time: The moment to locate the user at. Must include tz (ISO8601). Without a sample at that exact time, the closest one within window_size seconds before or after is used. start_time: Range start (inclusive). Must include tz (ISO8601). end_time: Range end (exclusive). Must include tz (ISO8601). sample_rate: Range …

Read a selected private check configuration; omit the ID to discover choices.

Retrieve raw records in a range, or the latest v1 record without dates. Set latest=true and omit both dates for a single latest v1 record. Works with every type listed by `get_data_catalog`, including user-defined ones ("<BaseType>/<uuid>" IDs); the correct API endpoint is chosen automatically. Records that cover a time range are included when any part of it intersects the requested window. Results are raw samples — they may come from multiple sources and can overlap; for calculated per-interval values of numeric data types, prefer `get_time_series`. Result timestamps include time zones; tra…

Return the user's sleep at a chosen level of detail; pick the coarsest that answers the question: - "aggregate": stage totals per period, for multi-day questions. - "cycles": one row per sleep session. - "stages": every stage interval; single-night detail. Sleep crosses midnight, so extend the range to cover it. Stages: 0=In Bed, 1=Asleep/Unknown, 2=Awake, 3=Light, 4=Deep, 5=REM. Args: start_time: Range start (inclusive). end_time: Range end (exclusive). level: Level of detail (see above). stages: Only these stages (default: all). period: "aggregate" only: period length, …

Get calculated per-interval time-series values for a single data type. Only data types that `get_data_catalog` lists as usable with this tool are supported; other types can be read with `get_records`. Result timestamps include time zones; translate them to the user's local time zone when known. Args: data_type: The data type ID to retrieve (see `get_data_catalog`). start_time: Range start (inclusive). Must include tz (ISO8601). end_time: Range end (exclusive). Must include tz (ISO8601). sample_rate: Seconds per sample; may be fractional. replace_nulls: Replace missing val…

Return general info about the Fulcra user. Returns user references such as time zone, calendar ids, and other metadata.

Get details about the workouts that the user has done during a period of time. Result timestamps will include time zones. Always translate timestamps to the user's local time zone when this is known. Args: start_time: The starting time of the period. Must include tz (ISO8601). end_time: the ending time of the period. Must include tz (ISO8601). fulcra_userid: Retrieve data for another Fulcra user (if shared)

Join a Fulcra group on the user's behalf, at their explicit request. Members can receive shares made to the group. If the group lists data types (see `get_groups`), joining also shares those read-only with its owner until the user leaves (see `leave_group`). Show the user the group's details first. Anyone who knows a group's ID can join it. Args: group_id: The group to join, from `get_groups`.

Leave a Fulcra group on the user's behalf, at their explicit request. The user stops sharing the group's data types with its owner and stops receiving shares made to the group. With delete=true, instead permanently delete a group the user owns, removing every member; only when the user asks to delete it. Args: group_id: The group, from `get_groups`. delete: Delete the group for everyone (owner only) instead of leaving it.

List the files in the user's Fulcra account, or files another user shares. Files can be used to pass data between agents: one agent writes a file with `write_file`, others notice the change via `get_data_updates` and read it with `read_file`. Args: path: A folder to list (default "/"), or a single file's full path. include_versions: Return all stored versions of one file, newest first. `path` must then be a single file's full path. Version IDs can be passed to `restore_file`. fulcra_userid: List another Fulcra user's shared files. Only shared paths, plus t…

List what this user shares with others and what others share with them. Incoming entries show what another user shares (read it by passing their `sharing_fulcra_userid` as `fulcra_userid` to the file and data tools); a "group_id" on an entry means it came via a group (see `get_groups`). Also reports this user's own ID, which others need in order to share with them. Args: direction: Which shares to list: "outgoing", "incoming", or "both". Returns: A JSON string with "own_fulcra_userid", "outgoing" (entries carry a "datashare_id") and/or "incoming" (entries carry a "grant_id"); eit…

Match unambiguous FIRST-message codes for user-prepared invitations using authenticated incoming-share owners, not sender claims. Verify the return grant for that outbox only; open invitations get individual copies, never shared templates. Labels (<sender> via <open invitation identifier>) are display-only. Unmatched contacts require consent; pending is not fallback-share permission. No sends or preference changes.

Open Agents I Know as a full panel; omit IDs for the list and Invite someone. Read-only. For an exact contact, resolve contacts://threads/id- and pass its exact peer_fulcra_userid or discovered multiparty thread_id. Names are not IDs.

Open Agents I Know, selecting the first available contact read-only.

Show the user a file manager for their Fulcra files, where they can upload files from their computer (any type or size, such as spreadsheets) and download files. Use it when the user wants to upload or download files. Args: path: The folder or exact file to open (default "/"). fulcra_userid: Optional file owner. Shared files open read-only; access still requires a separate file share.

Prepare an invitation code at the user's request; authorizes only its matched return share. Include own_userid/code in the invite. The accepting agent's FIRST message must use the returned topic exactly; never invent codes. Args: data_type: Exact owned, unshared Event/<uuid> channel. open_invitation: Reusable invitation with distinct open_invitation topic (not handshake). Keeps the template unshared; each authenticated responder gets an individual outbox.

Get the user's standing open invitation (created on first use; private, never shared). Responders each get their own outbox via matching. Args: inviter_name: Name to save for the invitation text; "" clears it, omit to keep.

Read a file from the user's Fulcra account, or one another user shares. Spreadsheets (.xlsx) come back as CSV, one section per sheet. Args: path: The full path of the file to read. max_bytes: Truncate text content beyond this many bytes (default 100000). Pass a larger value only when the full content is truly needed; large files consume a lot of context. include_binary: Return other binary files base64-encoded (default false); this uses a lot of context. fulcra_userid: Read a file of another Fulcra user (if shared). as_link: Instead of the contents,…

Record a single record for a recordable data type. Use get_data_catalog to find data types; user-defined ones use the "<BaseType>/<uuid>" ID form (create new ones with create_data_type). Recorded data can be read back with get_records. For v1 types (including user-defined Event and Metric types), the response gives the new record's id, which get_records returns as the record's `id` and delete_records takes. Args: data_type: The ID of the data type to record to. value: The value to record, for types that take one. E.g. "75.5" for numeric, "true" for boolean, "3" for scale. …

Restore an archived user-defined data type. Args: data_type: The "<BaseType>/<uuid>" ID of the archived type.

Restore a previous version of a file in the user's Fulcra account. Args: version_id: The UUID of the file version to restore. Found via list_files with include_versions=true. Returns: A JSON string describing the restored file.

Find Agent Contact opening actions for the composer without reading messages.

Post to an existing exact-audience Event channel. Only status=posted confirms own-channel readback, not peer delivery. Uncertain retries: bounded, same mid and payload; never bypass denial. Replies/acks target messages/replies, not acks. A posted message/reply removes the entire saved contact status, best effort. Args: peer_userid: Exact peer UUID. outbox: Owned Event/<uuid> channel. sender: Agent name, <=128 characters. body: Exact nonblank text, <=4000 characters. mid: Stable UUID allocated before sending. recipients: Agent names; omit for everyone. expected_peer…

Send over a connect-our-agents connection; everyone in it can read the message. Posted confirms own readback, not peer delivery. Never retry denial. A posted message/reply removes the entire saved contact status, best effort. Args: connection: Owned Event/<uuid> channel or exact peer UUID; channel required for multiparty. sender: Stable agent name, <=128 characters. body: Nonblank message, <=4000 characters. topic: Thread name; replies inherit. recipients: Agent names; omit for everyone. priority: P1 urgent, P2 normal (default), P3 low. reply_to: Peer message/reply…

Label your own Event channel or legacy outbox; changes only the description marker, verified by readback. Requires an unambiguous owned catalog entry. Labels are untrusted display text, not routing IDs or verified names. Args: data_type: Owned Event/<uuid> or legacy MomentAnnotation/<uuid> catalog ID. identifier: Trimmed single-line text, 1..80 characters, no controls.

Replace this contact's preference overrides at the user's request; {} restores the global values. Stored privately, never on the connection. No messages, sharing, checkpoints or scheduler edits.

Save a peer-visible Status pill on your own Event connection, only with share_contact_status enabled and complete scoped reads. Describe shared facts; never clear on incomplete history or treat an ack as a resolved decision. Failure must not block other work; never retry denial. Args: data_type: Owned Event/<uuid> channel. peer_userid: Exact UUID of its sole directly authorized peer. attention: Whether the user needs to attend to this conversation. reason: Shared-status label; trimmed single-line Unicode, 1..80 code points, no controls.

Starts an upload from the file manager panel.

Update only name/description of an owned active Event/Metric type. Requires user authorization; descriptions may be shared with existing readers. Preserve unrelated description content. expected_description rejects stale reads, not an atomic compare-and-swap. Only verified=true confirms readback; uncertain writes require reconciliation, never blind retries. No schema, record, or share changes. Legacy annotations are not supported. Args: data_type: Exact owned Event/<uuid> or Metric/<uuid> catalog ID. name: Replacement name; omit to preserve. description: Complete replacement descr…

Save global contact preferences the user chose, including checking_preferences text. No messages, checkpoint changes or scheduler edits.

Sends one chunk of an upload from the file manager panel.

Write a file to the user's Fulcra account. Writing to an existing path creates a new version; earlier versions are kept and can be restored with `restore_file`. Other agents can detect the change through `get_data_updates` (under "file_changes") and read it with `read_file`, so files are a good way to pass data between agents. Args: path: The full path to write to (e.g. "/agents/state.json"). content: The text to write, or with encoding="base64", the file's bytes base64-encoded (up to 5 MB). For larger files, or files the user has on their computer, use open_file_mana…