8000 feat(circles): let a circle see when you're free, and find a time by adeelahmad · Pull Request #661 · 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: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,8 +240,9 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
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. In the web app, circles
live under Profile and Share sits on every timeline item and resource. Rules (automations) share what comes in,
like the school's emails, asking you first until you let them run on their own. Agents do the same over MCP, and
the assistant asks you first. ([Circles of trust](docs/circles.md);
like the school's emails, asking you first until you let them run on their own. Let a circle see when you're free
(never what), and agents find a time that suits everyone. Agents do the same over MCP, and the assistant asks you
first before sharing. ([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
Expand Down Expand Up @@ -336,8 +337,8 @@ 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:** 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)).
- **Circles of trust:** asking someone's agent a question (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
5 changes: 5 additions & 0 deletions changelog.d/circles-when-free.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
- **When they're free.** Let a circle see when you're free (never what): its people and their agents ask
`POST /api/v1/circles/when-free`, MCP `when_free` or the assistant for a window and get each person's busy times
and when everyone is free, within the hours of the day asked for. Your events are those you organise or are
invited to, and your own calendar's; each ask shows in your timeline as `agent.asked` ([When they're
free](docs/circles.md#when-theyre-free)).
6 changes: 5 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,7 @@ POST /api/v1/circles
GET /api/v1/circles/people
GET /api/v1/circles/shares
POST /api/v1/circles/shares
POST /api/v1/circles/when-free
DELETE /api/v1/circles/shares/{share_id}
GET /api/v1/circles/{circle_id}
PATCH /api/v1/circles/{circle_id}
Expand All @@ -279,7 +280,10 @@ Your [circles of trust](circles.md) and what you share with them; yours alone. `
`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.
with the permissions it gave. A circle's `lets` says what its people may ask your agent: `free_busy` lets them see when
you're free. `POST /circles/when-free` takes `people`, a window (`start`, `end`, at most 31 days, in `tz`), `minutes`,
`day_start` and `day_end`, and answers each person's busy times (only when, never what) or why not, and the free
stretches when you and all of them are free; each person asked gets `agent.asked` in their timeline.

## automations

Expand Down
3 changes: 2 additions & 1 deletion docs/assistant.md
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,8 @@ When the configured model supports function calling, chat becomes an agent.
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.
person's words; it always waits for their yes, since telling other people is their pick. `when_free` finds when
people in their circles who let them see it are free, to suggest a time for a call or a trip (only when, never what).
- **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
2 changes: 2 additions & 0 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,7 @@ and the paths holding outside text are in `GET /api/v1/activities/kinds` (`event
| `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 |
| `agent.asked` | | `agent_asks` | what someone's agent asked of the person (`what`: `free_busy`, the window as `startTime` and `endTime`); in no namespace; the person asked alone sees it | Sam's agent asked when you're free, Mon 20 Oct – Fri 24 Oct |

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 @@ -783,6 +784,7 @@ A kind belongs to the source named in its `source`, and a source may list more i
- `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`.
- `agent_asks` (`app/domain/circles_ask.py`) reads `agent_ask` the same way, as `agent.asked`, for the person asked.
- `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
27 changes: 22 additions & 5 deletions docs/circles.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ Status: in progress. Circles are built in steps; only what is merged is called b
| 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 | built |
| Rules: an automation shares what you pick (by kind, sender, entity or the decision model) with a circle, asking you first or on its own | built |
| 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 |
| When they're free: a circle can see when you're free (never what), and agents find a time that suits everyone | built |
| Asking someone's agent a question (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
Expand Down Expand Up @@ -66,6 +67,18 @@ you say yes. Let its node run on its own (only you can, signed in) and it shares
shares as you, only what you can see in the automation's namespaces, never from a vault, and is audited as by the
automation; its share says `via: automation`.

## When they're free

Turn on *They can see when you're free* on a circle (`lets: ["free_busy"]`), and its people, or their agents, can
ask when you're busy in a window of up to 31 days. They get only when: each event's start and end, never what it is,
where, or with whom. Nothing is shared until you turn it on, and each ask shows in your timeline as `agent.asked`
("Sam's agent asked when you're free, Mon 20 Oct – Fri 24 Oct").

Your events are the calendar events you can read that you organise or are invited to by your account's email, and
every event in a namespace you alone belong to (your own calendar). Nothing in a vault counts. The answer also gives
the free stretches, at least so many minutes long and within the hours of the day asked for, when the person asking
and everyone who let them see are free, to suggest a time for a call or a trip. No model is called.

## For agents

Everything here works for agents as it does for people.
Expand All @@ -76,10 +89,12 @@ Everything here works for agents as it does for people.
(`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.
`POST /api/v1/circles/when-free` (`people`, `start`, `end`, `tz`, `minutes`, `day_start`, `day_end`) answers when
they're busy and when everyone is free; a circle's `lets` turns it on.
- **MCP:** `list_circles` (with `shares`: received or sent), `save_circle`, `share_with_circle`, `undo_share` and
`when_free`. They are about the person, so a namespace's own MCP server doesn't offer them.
- **The assistant:** `circles` reads them, `share_with_circle` asks the person first (telling other people is always
their pick), and `when_free` finds a time.
- **Automations:** the `share_with_circle` action ([Rules](#rules)), which agents can add with the automation tools.

## What keeps it safe
Expand All @@ -95,5 +110,7 @@ Everything here works for agents as it does for people.

## Refine later

- Count every time a repeating event happens, not only its first, for when someone is free.

- 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.
3 changes: 2 additions & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,10 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ
| `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 |
| `save_circle` | make a circle (`name`, `members` by account id or email) or change one of yours (`circle_id`: rename, set `members`, `add`, `remove`, set `lets` (`free_busy` lets its people see when you're free), 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 |
| `when_free` | when people in your circles are busy in a window, for those who let you see it (only when, never what), and when you and all of them are free for at least `minutes` within the hours of the day, in a time zone: to find a time for a call or a trip. Each person asked sees it in their timeline |
| `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
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,7 @@ request, to another check that proves the same thing; loosening a requirement or
| Circles live under Profile, a suggested circle takes one click and deleting one is undone, not confirmed | [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `makes a suggested circle in one click`; [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `deletes a circle with Undo instead of a confirm` |
| Share on a timeline item or a resource picks the only circle, takes a note and is undone from its toast | [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `picks the only circle, shares with a note, and undoes from the toast` |
| A rule shares what comes in with a circle and a note, asking first until the person lets it run on its own | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_rules_share_on_their_own_only_when_let` |
| A circle sees when you're free only once you let it, only when and never what, each ask in your timeline; agents and the assistant find a time | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_when_people_are_free`; [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `lets a circle see when you're free in one click` |

## See what it costs

Expand Down
35 changes: 31 additions & 4 deletions fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -4519,13 +4519,15 @@ def list_circles(ctx: Context, shares: str | None, limit: int) -> dict[str, Any]
"save_circle",
"Make or change a circle",
"Make a circle of trust (name and members), or change one of yours (circle_id): rename it, set its members, add "
"or take people out. Members are people on this Lens, by account id or email, from list_circles' people. "
"delete: true deletes it (what was shared with it stays shared). Needs a token with the write scope.",
"or take people out, or set what they may ask your agent (lets: free_busy lets them see when you're free). Members "
"are people on this Lens, by account id or email, from list_circles' people. delete: true deletes it (what was "
"shared with it stays shared). Needs a token with the write scope.",
Arg("circle_id", "integer", "the circle to change; leave out to make one"),
Arg("name", "string", "its name, like Immediate family", max_length=80),
Arg("members", "string[]", "everyone in it, by account id or email (replaces who was)"),
Arg("add", "string[]", "people to add"),
Arg("remove", "string[]", "people to take out"),
Arg("lets", "string[]", "what its people may ask your agent: free_busy (when you're free); replaces what they could"),
Arg("delete", "boolean", "delete the circle", default=False),
writes=True,
personal=True,
Expand All @@ -4537,6 +4539,7 @@ def save_circle(
members: list[str] | None,
add: list[str] | None,
remove: list[str] | None,
lets: list[str] | None,
delete: bool,
) -> dict[str, Any]:
from app.domain import circles
Expand All @@ -4548,14 +4551,14 @@ def save_circle(
raise ToolError("name the circle to delete with circle_id")
if not name:
raise ToolError("a new circle needs a name")
cid = circles.create(ctx.db, me, name, list(members or []) + list(add or []))
cid = circles.create(ctx.db, me, name, list(members or []) + list(add or []), lets or ())
auth.audit(ctx.db, ctx.user.as_audit(), "circle.create", f"circle:{cid}", {"via": "mcp"})
return {"circle": circles.get(ctx.db, cid, me["id"])}
if delete:
circles.delete(ctx.db, me, circle_id)
auth.audit(ctx.db, ctx.user.as_audit(), "circle.delete", f"circle:{circle_id}", {"via": "mcp"})
return {"deleted": circle_id}
out = circles.update(ctx.db, me, circle_id, name, members, add or (), remove or ())
out = circles.update(ctx.db, me, circle_id, name, members, add or (), remove or (), lets)
auth.audit(ctx.db, ctx.user.as_audit(), "circle.update", f"circle:{circle_id}", {"via": "mcp"})
return {"circle": out}

Expand Down Expand Up @@ -4627,6 +4630,30 @@ def undo_share(ctx: Context, share_id: int) -> dict[str, Any]:
return out


@tool(
"when_free",
"When people in your circles are free",
"When people in your circles are busy between start and end, for those who let you see it, and when you and all of "
"them are free for at least minutes, within day_start..day_end o'clock each day in tz: to find a time for a call "
"or a trip. Only when, never what, where or with whom. People who haven't let you see come back refused. Each "
"person asked sees that you asked in their own timeline.",
Arg("people", "string[]", "people by account id or email", required=True),
Arg("start", "string", "the window's start, an ISO time like 2026-10-20T09:00 (in tz)", required=True, max_length=40),
Arg("end", "string", "the window's end, at most 31 days later", required=True, max_length=40),
Arg("tz", "string", "the time zone, like Europe/London", default="UTC", max_length=60),
Arg("minutes", "integer", "how long a free stretch must be", default=30, minimum=5, maximum=1440),
Arg("day_start", "integer", "the hour each day starts", default=9, minimum=0, maximum=23),
Arg("day_end", "integer", "the hour each day ends", default=18, minimum=1, maximum=24),
personal=True,
)
def when_free(ctx: Context, people: list[str], start: str, end: str, tz: str, minutes: int, day_start: int, day_end: int) -> dict[str, Any]:
from app.domain import circles_ask

return circles_ask.find_time(
ctx.db, _me(ctx), people, start, end, minutes=minutes, tz=tz, day_start=day_start, day_end=day_end, via="mcp"
)


# ---------- schedules ----------
@tool(
"schedules",
Expand Down
Loading
Loading
0