Awareness

A good collaborator knows what the people around them are doing without being told: who is in the document, what just changed, which task someone picked up, what another agent finished a minute ago. An agent in Mod needs the same awareness of its space, its project and your World, so it can join in where it helps and stay out of the way where it would collide.

An agent has two ways to perceive the people and agents it works with. It can look, with vision, at what is on screen. And it is told what is happening, at the start of every turn. This page is about the second.

How it works

Told at the start of every turn. Before the person's words, a turn carries a few short blocks, each one thing the agent should know:

• Where. The machine the agent runs on (this Mac, or a VM on it), the projects it works in with how many documents and apps each holds, its folders, and whether the person has this session on screen.
• View. What the person is looking at: the space, then each pane, focused first, with its app's own line for what is shown ("rows 1 to 40 of 212 · B5 selected") and the version of the record on screen. A passage the person selects, in a document or a web page, rides with it. This is what "this" means in their message.
• Activity. What happened since the agent's last turn in what it can reach, ranked: what names this session or the person, then what touches what it holds, then its own, then the rest as a count. Comments are in it, and so is whatever an app says happened.
• Holding. What the agent is working on: the documents it created, edited or was pointed at, the branches it committed to, the pages its browser opened, and what is on screen beside it. Each says why it is there, and is marked when someone else changed it or commented since the agent last looked.
• Notifications. What is addressed to this session, unseen. Delivering it marks it seen.

Only what changed. Each block is sent only when it changed since the agent last had it. The rest are named in one line, "unchanged since your last turn: where, holding", so a turn where nothing moved costs a line, not a page. A session that is resumed or compacted is sent everything again. Every turn records what it sent, so a person can read back exactly what the agent was told.

The person sees the same record. The bar above the composer reads what the last turn sent (thread): its Awareness tab is the view and what is in hand, and its footer says what was sent and what was not sent again.

What the agent can look up. Beyond what it is told, an agent reads more when it needs it: the end of another session's log, who changed a document and why (history), and the view as it is right now, mid-turn, with read_view.

Wakes. A comment that names a session, a reply in a thread the agent wrote in, a comment on a document it is paired to, a notification sent to it, or an app's event marked to wake starts a turn on its own.

Using it as you build

An agent looks further with:

read_view                                      # the window as it is now
list_sessions   { "withState": true }          # what other sessions are doing
read_session    { "sessionId": "<id>" }        # the end of one session's log
read_history    { "documentId": "<id>" }       # who changed a document, and why

Your app adds to what the agent is told with the same calls its view already makes. Mod sees every write, so most apps need only the first:

// the pane's line, said whenever the state changes
const app = mod.app({ state, describe: (s) => `rows ${s.rows[0]} to ${s.rows[1]}` })

// what happened, in your words
mod.activity.add({ type: 'deal.stageChanged', subject: deal.id, line: `${deal.name} moved to Negotiation` })

// something the agent opened that Mod cannot see
mod.holding.add({ ref: { kind: 'site', url, label: 'acme.com/pricing' }, how: 'opened' })

// to one session, or to one person (never sent to an agent)
mod.notifications.add({ to: { session: sessionId }, line: 'Acme replied' })

Make your app work with agents walks through each with one example.

Limits

• Who else is here is not in Where yet: it names only the person whose window this is.
• A pane's line and selection reach the agent with the person's next message, or mid-turn through read_view.
• A line is capped at 300 characters, and an activity block at its top lines with a count for the rest.