8000 feat(circles): circles of trust and sharing with them, with API and MCP by adeelahmad · Pull Request #626 · adeelahmad/lense · GitHub
[go: up one dir, main page]

Skip to content
8000
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,12 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
[converting assets](docs/processing.md#converting-assets), [notifications](docs/notifications.md),
[automations](docs/automations.md), [approvals](docs/automations.md#approvals), [schedules](docs/schedules.md),
[timeline](docs/timeline.md); [checks](docs/requirements.md#automate-it))
- **Share with the people close to you.** Make circles of trust (your family, close family, friends, colleagues) of
people on the same Lens, and share an activity from your timeline or a resource with a circle and a note: each of
them sees it in their own timeline, and you see it in yours, so nothing is shared behind anyone's back. Share with the
item to also let them open the resource; undo takes it all back, and nothing leaves a vault. Agents do the same over
MCP, and the assistant asks you first. ([Circles of trust](docs/circles.md);
[checks](docs/requirements.md#share-with-the-people-close-to-you))
- **See what it costs.** An activity ledger of every model call, with reports, charts and budgets that cap spending.
Setup asks for one overall budget after a cloud model, with a soft limit that warns and a hard limit that stops paid
calls. A meter in the top bar shows spend against the budget, and the Costs page breaks it down by day, model and
Expand Down Expand Up @@ -325,6 +331,9 @@ Open pull requests, not yet part of Lens, are listed here; none right now.

Next, and not in a pull request yet; each links to where it is tracked:

- **Circles of trust:** circles and a Share action in the web app, rules for what your agent shares without asking,
asking someone's agent (when they're free, what a trip needs) answered from what they let you see, and circles
across Lens servers over ActivityPub ([circles of trust](docs/circles.md)).
- **Notes:** nesting a note under its project or area without a click, pages in the graph, and wiki addresses for
topics, recordings and the other things that have pages ([notes](docs/notes.md)).
- **Local models:** GPU builds of llama.cpp fetched by Lens, and local embedding models
Expand Down
7 changes: 7 additions & 0 deletions changelog.d/circles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
- **Circles of trust.** Put the people close to you in circles of your own (Immediate family, Close family, Friends,
Colleagues are suggested) and share an activity from your timeline or a resource with a circle and a note: ea 10BC8 ch of
them gets it in their own timeline as `share.received`, which their automations can follow, and you get
`share.sent`. *With the item* also gives them permission on that one resource (it needs `publish`); undo takes the
share back everywhere, with the permissions it gave. Nothing in a vault can be shared. Works through
`/api/v1/circles`, MCP (`list_circles`, `save_circle`, `share_with_circle`, `undo_share`) and the assistant, which
asks first ([Circles of trust](docs/circles.md)).
22 changes: 22 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,28 @@ namespace), `DELETE` deletes it (its writer or an owner). On an asset's arrival
asset's own comments. `GET /activities` carries everyone's reactions on the page in `reactions` and each item's
comment count in `comments`, by id. Writing needs a session or a write-scope key; a read-only key reads them.

## circles

```
GET /api/v1/circles
POST /api/v1/circles
GET /api/v1/circles/people
GET /api/v1/circles/shares
POST /api/v1/circles/shares
DELETE /api/v1/circles/shares/{share_id}
GET /api/v1/circles/{circle_id}
PATCH /api/v1/circles/{circle_id}
DELETE /api/v1/circles/{circle_id}
```

Your [circles of trust](circles.md) and what you share with them; yours alone. `POST /circles` takes a `name` and
`members` (account ids or emails of people you can add, from `/circles/people`); `PATCH` renames, sets `members`, or
`add`s and `remove`s people. `POST /circles/shares` shares an `activity` (its id) or a `recording` you can see with
`circles` and `people` in them, with a `note`; `with_item` also gives those who can't open the resource permission on
it (needs `publish` there). Each person gets `share.received` in their timeline and you get `share.sent`.
`GET /circles/shares?direction=received|sent` lists them newest first; `DELETE /circles/shares/{id}` takes one back,
with the permissions it gave.

## automations

```
Expand Down
3 changes: 3 additions & 0 deletions docs/assistant.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,9 @@ When the configured model supports function calling, chat becomes an agent.
the person ([Timeline](timeline.md#review-marks)), and `mute_activities` mutes a source, person or kind for them,
for good or until a time ([Muting](timeline.md#muting)). After it has read text from outside Lens, hiding, muting
or marking reviewed waits for their yes; marking important, lifting a mute or bringing things back acts at once.
- **The person's circles:** `circles` reads their [circles of trust](circles.md) and, when asked, what was shared
with them or by them. `share_with_circle` tells people in a circle about an activity or an asset with a note in the
person's words; it always waits for their yes, since telling other people is their pick.
- **The person's approvals:** `approvals` lists what waits for their pick, or what one timeline activity caused
(`activity`) ([Approvals](automations.md#approvals)):
automations' actions about the namespaces the conversation reads, and its own proposals in this conversation.
Expand Down
5 changes: 5 additions & 0 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,8 @@ and the paths holding outside text are in `GET /api/v1/activities/kinds` (`event
| `webhook.received` | | `log` | `{type: Note, hook: the webhook's id, payload: what was sent (JSON, a form's fields or text), content_type, query}`; the actor is the webhook (`Service`, `lens:automation_hook/<id>`, "Webhook for <automation>") | Webhook for Front door was called |
| `approval.waiting` | | `approvals` | `{type: Question, id: lens:approval/<id>, name: what it would do, url: /approvals?id=<id>}`, `status`, `action`, `effect`, `automation`, `automation_name`, `run`, `node`, `about` (the activity that caused it), `expires_at`; its person alone sees it | School emails asks for your pick: Post in the Matterbridge gateway family: “Trip on Friday, bring a packed lunch” |
| `approval.decided` | | `approval_decisions` | as `approval.waiting`, with `status` (done, failed, declined, expired) and `error`; `Accept` when approved, `Reject` when declined or expired | Sam approved: Post in the Matterbridge gateway family: “Trip on Friday, bring a packed lunch” |
| `share.sent` | | `shares_sent` | what was [shared with a circle](circles.md) as it read then (`type`, `id`, `name`, `url`, `summary`: the timeline's line, `media`, `kind` and `about`: the activity shared, `published`), `content` (the note), `share`, `circles`, `people`, `with_item`; tagged with its entities; the sharer alone sees it | Adeel shared “School trip on Friday” with Immediate family |
| `share.received` | | `shares_received` | as `share.sent`, without `circles` and `people`; `url` only when the person can open it; in no namespace; that person alone sees it | Adeel shared “School trip on Friday” with you |

A new asset is one activity, of the most specific kind its row tells, decided by its content type and where it came
from, never by reading its file: an email (content type email, or from an IMAP or Gmail mailbox), a calendar event
Expand Down Expand Up @@ -776,6 +778,9 @@ A kind belongs to the source named in its `source`, and a source may list more i
- `approvals` (`app/domain/events_approvals.py`) reads `approval` by `created_at`, the id breaking ties, as
`approval.waiting`; `approval_decisions` reads the decided ones by `decided_at`, as `approval.decided`. Both page
only the viewer's own approvals.
- `shares_sent` (`app/domain/circles.py`) reads `circle_share` by `at`, the id breaking ties, as `share.sent`;
`shares_received` reads `circle_share_to` (one row for each person a share went to) the same way, as
`share.received`. Both page only the viewer's own; a follower of some namespaces doesn't read `shares_received`.
- `log` reads `event_log`: activities no row of their own records (a deletion, a webhook call), written by
`events.emit(db, kind, *, actor, obj, space, summary, target=None, tag=None, key=None, published=None, spaces=None,
audience=None, owner=None, untrusted=None)`, which gives the id (`log-<n>`). Emitting a `key` again changes
Expand Down
80 changes: 80 additions & 0 deletions docs/circles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Circles of trust

Your agent works from your own data. Circles are how it tells the people close to you what they need to know: your
partner and children, your parents, friends, colleagues. You put people in a circle on purpose, share something from
your timeline or your resources with a circle and a note, and each of them sees it in their own timeline. Both
timelines show it, so nothing is shared behind anyone's back, and no model is called to do it.

Status: in progress. Circles are built in steps; only what is merged is called built.

| Part | Status |
| --- | --- |
| Circles of people on the same Lens, sharing an activity or a resource with them and a note, with the item or without, undo; API, MCP and the assistant | built |
| Circles under Profile in the web app, and a Share action on timeline items and resource pages | planned |
| Rules per circle: what your agent shares without asking (kinds, entities, a match tree) and what it asks you first about | planned |
| Asking someone's agent (when are they free, what does the trip need), answered only from what they let that circle see, with citations | planned |
| Circles across Lens servers over ActivityPub: a signed inbox, an outbox and WebFinger handles like `sam@lens.example` | planned |

## Circles

A circle has a name and people with an account on this Lens. Your circles are yours alone: nobody else sees them,
not even the people in them. The usual ones are offered as suggestions (Immediate family, Close family, Friends,
Colleagues); none is made for you.

You can add people you share a namespace with, and people who have you in a circle of theirs, so your son can add you
back once you have added him. Admins can add anyone. Adding someone tells them nothing; sharing does.

## Sharing

Share one thing at a time with one or more of your circles, or with people in them:

- **An activity** from your [timeline](timeline.md), by its id: an email that came, a calendar event, a sensor alert.
- **A resource** you can read, by its id.

Add a note in your own words ("Sam's trip is on Friday: he needs a packed lunch"). Each person it goes to gets a
`share.received` activity in their own timeline, which they alone see; you get `share.sent` in yours. A share keeps
what it said when you shared it: the name, the line the timeline gave it, the entities it is about, the kind of
activity and your note. Their automations can follow `share.received` like any other kind ("when Dad shares a school
notice, add it to my calendar"), and their agent reads the note and snapshot as outside text.

**With the item.** A share says what the item is, not what is in it. Turn on *with the item* to also give each
person who can't open the resource permission on that one resource, as an owner gives permission on an asset
([Access](access.md#permission-on-an-asset)): they then open it on the visitors' pages. It needs the `publish`
permission in its namespace. People who are members of its namespace already open it in the workspace, and their
share links there.

**Undo.** Take a share back and it leaves every timeline it reached, yours too, and the permissions it gave are taken
back. Deleting a circle doesn't take back what was shared with it.

**Vaults.** Nothing in a [vault](encryption.md#vaults) can be shared: what's in a vault stays in it.

## For agents

Everything here works for agents as it does for people.

- **API:** `GET /api/v1/circles` (your circles, and the suggested names you haven't used), `GET /api/v1/circles/people`
(who you can add), `POST /api/v1/circles` (`name`, `members` by account id or email), `GET`, `PATCH` (`name`,
`members`, `add`, `remove`) and `DELETE /api/v1/circles/{id}`. Share with `POST /api/v1/circles/shares`
(`activity` or `recording`, `circles`, `people`, `note`, `with_item`), list with
`GET /api/v1/circles/shares?direction=received|sent`, and take one back with `DELETE /api/v1/circles/shares/{id}`.
Audited as `circle.create`, `circle.update`, `circle.delete`, `circle.share` and `circle.unshare`.
- **MCP:** `list_circles` (with `shares`: received or sent), `save_circle`, `share_with_circle` and `undo_share`. They
are about the person, so a namespace's own MCP server doesn't offer them.
- **The assistant:** `circles` reads them, and `share_with_circle` asks the person first: telling other people is
always their pick.

## What keeps it safe

- You only add people you already share a namespace with, who have added you, or anyone if you're an admin, so a
circle doesn't reveal who has an account here.
- A share goes to people in your circles, never to anyone else, and only of what you can see yourself (the timeline's
rules decide).
- The snapshot is outside text to every agent that reads it (`lens.untrusted`), wrapped as data in prompts like an
email's subject.
- Someone removed for good loses their circles and what was shared with them; what they shared stays, under their
name.

## Refine later

- Show a received share's sender why they can or can't open it, and let a recipient ask for the item.
- Send a share to the person's chat app (Telegram, Slack, Matterbridge) when they linked one, beside the timeline.
5 changes: 5 additions & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,10 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ
| `comment_on_activity` | write a comment on an activity for the person, or with `parent` a reply on a thread; a `comment.added` activity. Needs a write-scope token |
| `approvals` | what waits for your pick, newest first ([Approvals](automations.md#approvals)): an automation's actions and the assistant's proposals, each with what it would do, why, when it expires, its link and what an agent may do (`can`); one by `id`, by `status` (pending by default, or `any`), `origin`, `automation` or the `activity` that caused them, a page at a time. On a namespace's own server, that namespace's alone. What it would do holds text the automation read from outside Lens |
| `decline_approval` | decline one of your approvals by id: nothing is done, and the run records it. There is no tool to approve: that is your pick, in Lens or your chat app. Needs a write-scope token |
| `list_circles` | your [circles of trust](circles.md), each with its members, the people you can add, and with `shares` (received or sent) what was shared with you or by you, newest first |
| `save_circle` | make a circle (`name`, `members` by account id or email) or change one of yours (`circle_id`: rename, set `members`, `add`, `remove`, or `delete`). Needs a write-scope token |
| `share_with_circle` | tell people in your circles about an activity (by id) or a resource you can see, with a `note`: each sees it in their own timeline; `with_item` also gives them permission on the resource (needs `publish` there). Nothing in a vault. Needs a write-scope token |
| `undo_share` | take a share back: it leaves everyone's timeline, and the permissions it gave are taken back. Needs a write-scope token |
| `automations` | the person's automations ([Automations](automations.md#agents)): each one's triggers, whether it's on, its last run and what waits; with `automation_id` one in full with its latest runs, with `run_id` one run with its trace, log and what its actions did |
| `automation_actions` | what an automation's action nodes can do: each action's params, what it reaches and what it gives back |
| `save_automation` | make an automation, or change one: name, triggers, its If (`condition`), its graph, namespaces, limits; a new one is saved switched off unless `enabled` is true. Problems come back in plain words; a node never runs on its own from here. Needs a write-scope token |
Expand Down Expand Up @@ -195,6 +199,7 @@ which records an undoable change (proposed by default), `undo_graph_change`, `ed
`merge_topics`, `delete_topic` and `undo_topic_change`, which curate entities and topics as an editor does in the web
app (merges and deletes can be undone), `write_note`, which adds a note, `create_podcast`, which
queues an episode, `create_feed` and `publish_to_feed`, which make and fill a [published feed](feeds.md),
`save_circle`, `share_with_circle` and `undo_share`, which change your [circles](circles.md) and what you share with them,
`write_spec`, which queues a spec, `draft_reply` and `edit_reply`, which draft and change [email replies](email-replies.md) (nothing is sent), `send_reply`, which asks to send one (it waits in Approvals), `set_nsfw` and `mark_nsfw`, which change [NSFW classification](nsfw.md) (owners or admins, and
editors), `enhance`, which enhances an image and reads it again (the process permission),
`set_namespace_integrations`, which turns a namespace's own MCP server or chat completions on or off (owners), `set_picture_descriptions`, which changes what describes pictures (admins), `set_file_storage`, which changes where new files are kept (admins), `set_secret_reference`, which points a secret field at a password manager's item (admins), `install_plugin`, which
Expand Down
9 changes: 9 additions & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,6 +275,15 @@ request, to another check that proves the same thing; loosening a requirement or
| In the web app, automations are listed with what sets each off in words, and built in When, If and Then with a test on a recent activity, problems next to their fields | [automations-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automations-ui.test.tsx) `the list reads each automation, and Delete is undone from its toast`, `the builder adds a trigger with a condition and an action, then saves it switched off`, `the test panel runs the draft on a recent activity and says what it would do`, `API problems go next to what they are about`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_lists_read_the_triggers_in_words_and_say_when_it_runs_next` |
| An automation's page shows its runs a page at a time with each one's log, what's coming up, its variables to edit and its costs | [automation-detail.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-detail.test.tsx) `Runs pages back with before, and a run opens to what it did and its log`, `a run held over a budget can run once or be skipped`, `Coming up lists its times, and says why when there are none`, `Variables set from the keyboard, and Clear is undone from its toast` |

## Share with the people close to you

| Requirement | Checks |
| --- | --- |
| Circles of people on the same Lens are each person's own, and hold only people they may add | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_circles_are_your_own` |
| Sharing an activity or a resource with a circle and a note shows it in each member's own timeline and the sharer's, with the item or without, undone with its permissions, never from a vault | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_sharing_with_a_circle` |
| Automations follow what was shared with the person; removing someone takes their circles and what was shared with them | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_automations_follow_shares` |
| Agents make circles and share over MCP; the assistant shares only after the person's yes | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_agents_share_too` |

## See what it costs

| Requirement | Checks |
Expand Down
Loading
Loading
0