Apps and connectors
This optional profile describes how a persona defines three parts that work on the same data.
- Agents carry out playbooks.
- Connectors are the operations a playbook may call on an outside service.
- Apps are the views people use to see the result and move it on.
A runtime that supports live sync can keep open views in step with changes from agents and people.
requirementsbotsresources · listresources · app- 1An agent’s playbook reads from a service through a connector requirement.
- 2The agent works on what it read and prepares a result.
- 3A step that needs approval waits for a person’s decision.
- 4A publish step writes the accepted fields to the team list.
- 5The runtime announces the change, and every open view of the list updates.
- 6A person moves the record on in the app. The transition can start the next playbook.
1. The parts Extracted
Section titled “1. The parts ”A persona repository holds a library of playbooks and one or more teams. A team owns its agents, its apps, and its lists and pipelines. Each agent runs one playbook from the library.
An app with its own interface starts in a team, because a team needs it. Creating it registers an app package in its creator’s registry and installs it into that team. From the registry it can be installed into other teams, including teams in another persona.
persona-lane/ the persona folder
Playbook library 17 playbooks
- meeting-watcher
- brief-researcher
- briefing-caller
- meeting-scribe
- pilot-research
- and 12 more
Shared by every team in the folder.
Meeting follow-through team
- Agents
- 6, each runs one playbook
- Apps
- 3 views over lists
- Lists and pipelines
- 1 list, 1 pipeline
Prospect to pilot team
- Agents
- 7, each runs one playbook
- Apps
- 1 view over a list
- Lists and pipelines
- 1 list, 1 pipeline
App registry outside the folder
- Starts in a teamBuilt there, because that team needs it.
- Kept in a registryIts creator’s own, with numbered revisions and a fingerprint.
- Installed into a workspaceThe creator selects a team they can manage and chooses who can open the app.
Team definitions, playbooks, and declarative resources live in assets/studio-teams.json. Workspace installations supply connector accounts, publisher grants, and installed app packages. The team schema uses teams[].bots for agent placements. It allows up to 100 teams, 128 playbooks and 256 team resources in a folder, and up to 64 agents and 50 apps in a team.
| Part | What it is | Where it is declared |
|---|---|---|
| Goal run | A specific outcome, plan, and run | In the workspace, scoped to a team |
| Playbook | A reusable execution or planning definition | playbooks[] |
| Agent | A team member that carries out one playbook | teams[].bots |
| Connector requirement | An operation contract: which service, and which operations | playbooks[].requirements |
| List | Shared records | resources[], kind list |
| Pipeline | The stages a record moves through | resources[], kind pipeline |
| App | A view over a list | resources[], kind app |
| App package | An app with its own interface | Kept in its creator’s package registry and installed into a workspace team. See packages and installations. |
| Connection | A private, authenticated account | Never in a definition. The workspace holds it. |
One distinction runs through this page. A connector is an operation contract. A connection is a private authenticated account. A definition holds the first and never the second.
This section is extracted from one persona that uses teams and from the published team definition schema.
From goals to playbooks
Section titled “From goals to playbooks”In Gabriel Operator, a person gives a team a goal with an outcome and completion criteria. The goal selects and invokes playbooks in that team, ordering them as the outcome and their dependencies require. When the team lacks a playbook, an author can draft and register one from the goal. A saved goal playbook can also plan and delegate within its configured limits. The plan can then run within the workspace’s connector grants and execution limits.
Playbooks declare the operations they need. During a run, authorized connector results and agent outputs can be mapped to named fields on a team list. Apps read that list or use their own declared connector operations. A pipeline transition can start another playbook within its configured limits.
See how a team composes playbooks on the homepage, or follow a Lane run.
2. Connector requirements Extracted
Section titled “2. Connector requirements ”A playbook declares each service it needs as a requirement.
{ "id": "calendar", "label": "Google Calendar", "context": "personal", "providers": ["googlecalendar"], "operations": ["upcoming"], "optional": false}| Field | Description |
|---|---|
id |
The name steps and apps use to refer to this requirement. |
label |
A name for people. |
context |
personal: the account of the person the run acts for. app: a shared destination set up for one of the team’s apps, named in appId. |
providers |
The services that can satisfy the requirement. |
operations |
The named operations the playbook may call. |
optional |
Whether the playbook can run without it. |
Rules:
- A requirement MUST NOT contain a credential, an account identifier or a connection identifier.
- A runtime resolves each requirement to a connection that the person or the team has granted. A requirement that is not optional and has no connection holds the step that needs it.
- A playbook MUST declare every operation it calls. A step refers to a requirement by
idand to one of its declared operations.
3. Steps that use a connector Extracted
Section titled “3. Steps that use a connector ”A step of type connector_operation calls one declared operation.
{ "id": "upcoming", "title": "Discover upcoming occurrences", "instruction": "Read upcoming occurrences from the authorized calendar.", "type": "connector_operation", "dependsOn": [], "operation": { "requirementId": "calendar", "operationId": "upcoming", "values": { "from": "/input/from", "until": "/input/until" }, "effect": "read" }, "outputFields": { "meetings": "/meetings" }, "requiresApproval": false}| Step type | What it does |
|---|---|
connector_operation |
Calls one operation of one requirement. |
reason |
A model works on what earlier steps produced. |
playbook |
Invokes a registered playbook with declared input mappings. |
wait_until |
Waits until the time resolved from a declared pointer. |
publish_list |
Writes named fields to an authorized team list. |
publish_page |
Writes a page. |
An operation states its effect:
| Effect | Meaning |
|---|---|
read |
Fetches from the service and changes nothing there. |
write |
Changes data in the service. |
process |
Starts work in the service that finishes later. |
Rules:
valuesmaps operation arguments to JSON Pointers into the run context, for example/input/fromor/steps/read/meetings.outputFieldsmaps declared names to pointers into this step’s result. A runtime MUST NOT evaluate these mappings as code.- Gabriel pauses a
reasonstep or connector read marked"requiresApproval": truefor a person’s decision. Connectorwriteandprocessoperations always require exact effect approval. Use an explicit review step before publishing when the result needs a person’s decision. See governed execution for how to rehearse an effect and recheck the approved proposal before dispatch. - A step MAY name a
completion: a status operation the runtime checks until the work succeeds, fails or reaches a deadline. - A
publish_liststep names a logical publisher key and the fields it writes. The workspace owner binds that publisher to a permitted destination and field allow-list. Only allowed fields with the required grants reach the list.
{ "id": "cycle", "title": "Publish accepted meeting outcome", "instruction": "Publish the selected fields to the shared meeting list.", "type": "publish_list", "publication": { "target": "meeting-cycles", "fields": { "cycle_id": "/input/occurrence", "status": "/input/status", "summary": "/input/summary", "next_action": "/input/nextAction" } }}4. Lists, pipelines and apps Extracted
Section titled “4. Lists, pipelines and apps ”Lists, pipelines and apps are team resources. Each has the same envelope.
{ "key": "app.lane.meeting-cycles", "teamId": "lane-meeting-follow-through", "revision": 1, "archived": false, "kind": "app", "definition": { "name": "Meeting follow-through", "description": "Shared meeting outcomes, evidence and next actions.", "listRef": "list.lane.meeting-cycles", "view": "board", "fields": ["cycle_id", "attendee_email", "start_at", "status", "summary", "next_action"], "pipelineRef": "pipeline.lane.meeting-cycles", "requirements": ["calendar", "mail", "briefing", "capture", "contacts"] }}| Field of an app | Description |
|---|---|
listRef |
The list the app shows. |
view |
grid or board. |
fields |
The columns of the list the app shows, in order. |
pipelineRef |
Optional. The pipeline whose stages the board uses. |
requirements |
The connector requirements the app depends on. |
Rules:
- An app of this kind is a view. It contains no code.
keyis a resource key. Resources refer to each other by key.- A pipeline transition MAY name a playbook to start. It states the most credits and model calls that one start may use, and which fields the result may share.
5. How the parts stay in step Proposed
Section titled “5. How the parts stay in step ”One round of the loop:
- An agent’s playbook reads from a service through a connector requirement.
- The agent works on what it read and prepares a result.
- A step that needs approval waits for a person’s decision.
- A publish step writes the accepted fields to the team list.
- The runtime announces the change, and every open view of the list updates.
- A person moves the record to the next stage in the app. The transition can start the next playbook.
Steps 1 to 4 and step 6 describe how the extracted parts already work together. Step 5 is the guarantee this draft proposes:
- When a record in a list changes, a runtime that supports live sync SHOULD announce it, so an open view updates without a reload.
- Record changes follow the list validation and permission rules. The operation, step, or destination determines which approval is required.
- Only the fields a step or a binding names leave their private source.
6. Custom app packages Extracted
Section titled “6. Custom app packages ”An app package distributes a custom interface. It has its own registry and lifecycle, separate from the persona that defines the team.
When a grid or a board is not enough, an app can bring its own interface. It is a package: a manifest, the compiled files of the interface, and optional sample data for previews.
{ "manifest": { "schemaVersion": 1, "kind": "studio-connector-app", "name": "Follow-up board", "description": "Shows meeting outcomes and drafts a follow-up on request.", "source": {}, "view": "board", "entities": [], "actions": [], "ui": { "kind": "bundle", "entrypoint": "mcp-app.html" }, "monitoring": [], "state": true, "playbooks": [ { "key": "draft-follow-up", "label": "Draft a follow-up", "inputFields": ["contact"], "maxCredits": 2, "maxModelCalls": 8 } ] }, "files": { "mcp-app.html": "…" }}| Manifest field | Description |
|---|---|
source, connectors |
The services the app needs. Each is named by a key. No account is named. |
entities |
The things the app shows, each with a read operation and an optional write. |
actions |
Other operations the interface may call. |
ui |
generated: the runtime draws the entities. bundle: the package’s own interface. mcp-resource: an interface the service itself provides. |
state |
Whether the app may save one JSON document of its own. |
playbooks |
The playbooks the interface may start, each with a cap for one start. |
monitoring |
Events in the service that the owner may turn into rules. |
The interface reaches data only through calls the manifest declares. A runtime MUST reject any other call.
| Call | Allowed when |
|---|---|
gabriel_connector_read, gabriel_connector_write, gabriel_connector_action |
The entity or action is declared. |
gabriel_app_list_read, gabriel_app_list_write |
An entity is bound to a list. Writing needs a binding in the outbound or both direction. |
gabriel_app_state_read, gabriel_app_state_write |
state is true. The document is one JSON object of at most 256 KB. |
gabriel_app_playbook_start, gabriel_app_playbook_status |
The playbook key is declared. |
Rules:
- A package is at most 4 MB and 100 files.
- The interface runs in a sandbox: scripts only, no network access, no frames and no credential. Code in a package runs in that sandbox and nowhere else. It cannot define what the runtime does.
- Each operation pins the tool it calls with a fingerprint of the tool’s schema. If the schema changes, the runtime holds the work.
- In an operation’s arguments, only values written as
$-prefixed JSON Pointers can vary. Everything else is fixed, including which remote resource is used. - A write carries the revision it expects and a request identifier. A runtime MUST refuse a write against a stale revision, and MUST NOT repeat a write whose outcome is uncertain.
- One playbook start costs at most its declared cap. The owner sets the remaining allowance, and the interface cannot raise it.
The full format is the published package schema.
Packages and installations Extracted
Section titled “Packages and installations ”An app starts in a team and then lives in a registry.
- Create. Someone builds the app in a team, because that team needs it.
- Register. Creating it registers a package in the creator’s registry, with an identifier, numbered revisions and a fingerprint of its contents. The registry entry does not name a team or persona.
- Install. The same step installs the package into the team it was built in. From the registry, its creator can install it into other teams, including teams in another persona.
- Share. The creator chooses who else may open an installation: nobody, anyone signed in, or anyone with the link.
An installation binds one revision of an app package to one team. The same app package can be installed in several teams.
| The package holds | An installation holds |
|---|---|
| The manifest | Which package and which revision |
| The compiled interface | The accounts chosen for its connectors |
| Sample data for previews | How its entities map to that team’s lists |
| The document the app has saved | |
| The remaining allowance for starting playbooks | |
| Who it is shared with |
Rules:
- A revision does not change. Registering different contents under a revision that exists MUST be refused.
- An installation stays on the revision it was installed with until its owner adopts a newer one.
- Only the creator of a package can install it. Other people use it where it is installed.
- An installation of a custom package is visible only to the person who installed it. They choose who else may open it: nobody, anyone signed in, or anyone with the link.
- Removing a package removes its installations in every team.
- A persona MAY turn custom apps off for its teams.
- A package MAY also be registered directly through the account’s API, without starting in a team.
A persona does not reference the app packages its teams have installed. Importing the persona brings its teams, playbooks, lists, and views. Installed apps stay with their workspace.
7. Live sync Extracted
Section titled “7. Live sync ”A runtime tells clients what changed through a stream of events.
{ "event_id": "evt_3f9c…", "type": "gabriel.resource.updated", "created_at": 1794264496, "scope": { "type": "workspace", "id": "…" }, "data": {}}| Transport | Use |
|---|---|
Server-sent events, GET /api/v1/events |
One-way stream that resumes after a disconnect. |
WebSocket, /api/v1/realtime |
Two-way. The client subscribes by sending a message. |
A client chooses what it receives by topic, and says where to resume:
{ "type": "gabriel.subscription.create", "topics": ["gabriel.resource.*"], "after": "evt_3f9c…" }Rules:
- A runtime MUST limit a subscription to the topics the client’s credential allows.
afteris the identifier of the last event the client handled. The runtime replays what followed it.- When the runtime can no longer replay from that point, it sends
gabriel.replay.reset_required. The client MUST reload its state. It MUST NOT assume it missed nothing. - A browser MUST NOT hold a long-lived credential. It connects with a short-lived, single-use secret that a server mints for it.
This section is extracted from the published Persona SDK. Which events a runtime must send for lists, runs and connections is Planned.
8. Presence and following Proposed
Section titled “8. Presence and following ”Presence tells each person who else is working in the same team, and where. Following shows one person exactly what another sees. Both are separate from live sync: presence describes people, not data, and is never stored.
Each participant shares a small state with the others:
| Field | Description |
|---|---|
user |
Who they are. |
tab |
The part of the team they have open. |
pointer |
Where their pointer is, in canvas or panel coordinates, or nothing. |
click |
Their latest press, with a counter so it is shown once and never replayed. |
view |
What they see: which item is open, which side panels are open, the canvas position and zoom, and how far they have scrolled. |
Rules:
- Following shows. It never acts. A follower MUST NOT apply anything that starts something, such as joining a call or adding a playbook.
- A follower’s own access still applies. Following cannot open a place the follower may not open.
- A client MUST check a received view before applying it, and drop anything malformed or oversized.
- Presence MUST NOT be written into a definition, a record or a run.
This section describes one client. In it, presence travels as shared awareness state on the collaboration connection, and the keys inside view belong to that client. A shape that other clients can share is not yet proposed.
9. Open questions
Section titled “9. Open questions”- Names. The interface calls and the events carry the
gabrielprefix of the runtime they were extracted from. Neutral names are undecided. - Pinning. The persona’s root commit versions the Studio team file. The portable registry pins linked workflows, pipelines, and lists. A common format for marketplace playbook packages is still open.
- Agents in presence. Whether a running agent appears to people as a participant is not specified.