Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Programmatic calls
Status: phases 1 to 4 are built, except as listed below. Phase 5 (companions) is not.
Not built yet:
- Bot joins. Identities, attendance and orphan-room handling are in place, but the routes
still refuse bot tokens: the
enable-programmatic-callsflag is keyed on a user, and a team-scoped bot token has no acting user. - Approved starts. An agent-attributed start is always refused; approval through
execution.reviewsis not wired. - Reading other participants' registered work: it has no REST route.
Screen share has not been run end to end.
Goal: one supported way for a program to be a participant in a Macro call, able to do everything a person can do there.
The model
Macro decides who may be in which call. LiveKit runs what happens in the room.
The SDK does the Macro half and hands over a LiveKit connection. It does not wrap
LiveKit. LiveKit's own clients already cover audio, video, screen share, data and
subscriptions, and voice agents already build on them through AgentSession. A Macro
wrapper would have to chase all of that, and would get in the way of those tools.
import { Macro } from '@macro-inc/sdk';
const macro = new Macro();
const call = await macro.channels.byId(id).activeCall();
const connection = await call.join();
// connection.url, connection.token: use them with any LiveKit client
import { connectRoom } from '@macro-inc/sdk/calls/node';
const { room, connection } = await connectRoom(call); // a real @livekit/rtc-node Room
await session.start({ agent, room }); // LiveKit AgentSession, unchanged
// ...
await connection.leave();
So there are two levels, and a program can use either:
| Level | Package | Returns | Runs in |
|---|---|---|---|
| Token | @macro-inc/sdk |
CallConnection: URL, token, identity, room name |
Anywhere except code mode |
| Room | @macro-inc/sdk/calls/node and @macro-inc/sdk/calls/browser |
A LiveKit Room, already connected and with Macro's defaults |
Node, Bun or a browser |
Keep room helpers out of the core entry point so ordinary SDK imports and the code-mode bundle never load a media runtime. Optional peers avoid installing it for callers that only use the core API.
Why the current path isn't good enough
A voice agent built outside this repo already joins and talks in calls, using a Macro
user account, an API key and @livekit/rtc-node under Bun. It proves the approach, and
shows what is missing:
| What it has to do today | Why | What replaces it |
|---|---|---|
Cast into the SDK's private client.storage to reach routes listed as app-only |
The SDK wraps none of them | call.join(), channel.startCall() |
| Check for a live call before every join | GET /call/{channel_id} starts a call and rings the channel if the last one just ended |
call.join() can never create a call |
| Hold a local lock around every token request | A token request silently removes the user from their other call | onOtherCall: 'fail', the default for SDK joins |
| Poll active calls and meetings every 3 seconds | Programs get no call events | Events, plus macro.calls.active() to reconcile |
| Merge calls and meetings into one list itself | Two routes, two shapes | macro.calls.active() |
| Run its own timers to leave an empty call | Nothing ends a call that only programs remain in | A server rule (below) |
Call getRingStatus, which accepts only the LiveKit token from a VoIP push, with an API key |
No other way to ask "is this ringing for me" | call.ringState() |
| Hold a separate room connection for the roster | Roster reads need a meeting token and exclude channel calls | call.participants() |
Who a program is
| Principal | Identity in the room | Use | Phase |
|---|---|---|---|
Agent account (team.invite(..., { agent: true }), User.isAgent()) with an API key |
Its own user id | The recommended path: a long-lived program with its own name | 1 |
| A person's API key | That person's user id | Scripts acting as me while I'm not in the call | 1 |
| Meeting guest | A guest UUID | Standalone links, no account | 4 |
| Bot token | New bot|<uuid> handling |
Bots granted a channel. Refused today by UserOrInternal |
4 |
| Companion of a person | New conn:<uuid> |
Sharing into a call while my own app stays in it | 5 |
| Code-mode program | None | Control methods only. It has a 30 second deadline and reaches only Macro hosts, so it can never hold media | - |
Agent accounts go first because they need no changes to attendance, access or identity
handling: to the backend they are already users. Programs must not use LiveKit's
agent participant kind, because the app's call view hides those participants,
including any screen share they publish.
A person's key has one trap: LiveKit allows one connection per identity, so joining
with my key disconnects my app. join() therefore returns already_connected when the
identity is in the room, unless the caller passes replace: true. Companions (phase 5)
are the real answer for that case.
SDK surface
Follows the SDK rule: handles in and out, no raw ids.
CallRecord stays the one noun for a call.
// Find
macro.calls.active(): Promise<CallRecord[]> // every live call I can see, either kind
channel.activeCall(): Promise<CallRecord | undefined>
call.kind // 'channel' | 'standalone'
call.ringState(): Promise<'ringing' | 'answered' | 'declined' | 'ended'>
call.participants(): Promise<CallParticipant[]> // live, with track state
// Enter
channel.startCall(opts?): Promise<CallConnection> // joins if one is running; else rings and records
meeting.join(opts?): Promise<CallConnection> // starts the room on first join
call.join(opts?): Promise<CallConnection> // never creates; fails if the call ended
call.decline(): Promise<void>
interface JoinOptions {
onOtherCall?: 'fail' | 'switch'; // default 'fail'; the app's behavior is 'switch'
replace?: boolean; // take over this identity's existing connection
name?: string; // display name in the room
}
interface CallConnection {
readonly call: CallRecord;
readonly url: string;
readonly token: string; // omitted from toJSON
readonly identity: string;
readonly roomName: string;
readonly started: boolean; // whether this request created the call
leave(): Promise<{ callEnded: boolean }>;
}
The call helpers add only what a program would otherwise get wrong:
connectRoom(target, opts?): Promise<{ room: Room; connection: CallConnection }>
publishScreen(room, source, opts?): Promise<ScreenShare> // screen-share source and encoding
connectRoom turns off Opus DTX the way the app does (LivekitJsCallController.ts: it
clips quiet speech after noise suppression), and calls leave() when the room closes.
publishScreen takes frames in Node (VideoSource.captureFrame) or a MediaStream in a
browser, with the browser picker as its default. Capture itself is up to the caller:
rtc-node has no capture engine, so a page screencast or ffmpeg output goes in as
frames.
The room helpers ship inside the SDK as separate calls/node and calls/browser
exports. The core entry point never imports them. Their build is separate from
core, and LiveKit runtimes are external optional peers, installed only by callers
that need media. Dynamic imports let browser applications load calls on demand.
There is one SDK version, package, and release workflow.
Parity: everything a person can do
Status: Exists in the SDK; Wrap, the route exists; New, needs backend work; LiveKit, use the room directly; Client, app-side behavior with no shared state.
| A person can | A program uses | Status |
|---|---|---|
| See live calls | macro.calls.active() |
Wrap |
| Be rung, and see it stop | call.ringing, call.answered, call.declined events, call.ringState() |
New |
| Decline | call.decline() |
Wrap |
| Start a channel call | channel.startCall() |
New (POST) |
| Start an instant call | macro.meetings.create(), meeting.join() |
Exists, Wrap |
| Schedule a call | macro.calendar |
Exists |
| Join by link | macro.meetings.lookup(token), meeting.join() |
Exists, Wrap |
| Join as a guest | meeting.joinAsGuest(name) |
Wrap, phase 4 |
| Leave | connection.leave() |
New |
| Speak, mute, pick a microphone | room.localParticipant, AudioSource |
LiveKit |
| Show video, pick a camera | room.localParticipant, VideoSource |
LiveKit |
| Share a screen, with audio | publishScreen() |
LiveKit plus helper |
| Hear and see others | Room subscriptions | LiveKit |
| See who is speaking, muted or on camera | Room events | LiveKit |
| See the roster without joining | call.participants() |
New |
| Noise suppression, backgrounds | Same LiveKit processors in /browser; in Node, process your own frames |
Client |
| Focus a tile, maximize a share | Not applicable | Client |
| Read and post in call chat | call.timelinePage() and CallMessage exist; add call.discussion() for the root post and channel-thread calls |
Wrap |
| Rename | call.rename() |
Exists |
| Set team sharing | call.setTeamShare() |
Exists |
| Get a link | call.meeting(), meeting.webUrl() |
Exists |
| Invite teammates to a standalone call | meeting.inviteUsers() |
Exists |
| List and revoke links | macro.meetings.list(), meeting.cancel() |
Exists |
| Register work, see others' work | session.registerAsWork(); add a read of others' work (GraphQL in the app) |
Exists, New |
| Read the transcript and summary | call.transcript, call.summary |
Exists |
| Download the recording | call.recording.bytes(), since code mode cannot reach the presigned URL |
New |
No moderation: people have no mute-others, remove or end-for-everyone controls in a call today, and programs should not get power people lack. If those arrive, they arrive in the app and SDK together.
Backend changes
All in crates/call, in its hexagonal layout.
Routes
| Route | Purpose |
|---|---|
POST /call/{channel_id} |
The explicit start: the same get-or-create as the GET, but as a write, so code mode's dry run treats it as one. The GET stays for shipped clients; the SDK never calls it |
POST /call/record/{call_id}/join |
Join a live call, never create. Allowed for anyone who sees it in active(): channel members, and a standalone call's owner, attendees and invitees. View access alone is not enough, because team-shared viewers must not join. Returns 410 when ended, 409 in_other_call, 409 already_connected |
POST /call/record/{call_id}/leave |
Leave by call id, for one call only, so a stale program can't leave a newer call in the same channel. decline is bound to call id for the same reason |
GET /call/active/all |
Channel and standalone calls in one shape, each with its kind and whether it is ringing for the caller |
GET /call/record/{call_id}/ring |
Ring state for an authenticated user, reusing get_ring_status's logic. The push-token route stays for native clients |
GET /call/record/{call_id}/participants |
Live roster from list_participants, with track state and whether each is a program. Same access as join |
GET /call/record/{call_id}/recording |
Recording bytes through a Macro host |
Refuse tokens in code mode. All token routes return 403 when the request carries
x-macro-code-execution. The sandbox cannot use a token, and it would land in the model's
context and the transcript. Tokens live 6 hours and cannot be revoked. toJSON on
CallConnection also omits the token, and it is never logged or put on a span.
Mark programs in the room. At join, the credential already says who is asking
(CredentialOrigin: UserApiKey and MacroApiJwt versus Session), and is_agent says
what the account is. Mint with a macro.program attribute (with_attributes exists in
the livekit-api crate) and store client on call_participants, with a default of
person per CS-70.
A program must not hold a call open. Today a call ends when its last participant
leaves, so a stuck program could keep a room and its recording running indefinitely. New
rule: when only programs have been in the call for 60 seconds, the existing
finish_empty_call path ends it. That covers people leaving, and a call a program started
that nobody answered within the 30 second ring. stale_call_sweeper is the backstop.
Limit starts. channel.startCall() rings people, so it takes a per-caller rate limit
through the existing rate_limit crate. An agent-attributed credential acting as a person
(is_agent_run) is refused unless approved through execution.reviews, as email.send
is. An agent account's own API key acts as itself, and is only rate limited.
Events. Add these to WebhookEvent, with access checks in fan-out and an SDK hydrator
(src/events/hydrate/call.ts), so macro.events.on() and listen() receive them:
- For everyone who can see the call:
call.started,call.ended,call.participant_joined,call.participant_left,call.recording_ready,call.summarized. - For one user:
call.ringing,call.answered,call.declined,call.invited.
Today the per-user ones are hand-written JSON on the app's websocket and the others are an
internal broker topic. A program reconciles with macro.calls.active() when its stream
reconnects, so a missed event costs a delay and not a missed call.
Client changes
Show an "Agent" badge on any participant with macro.program set, in the tile and in
Participants. People should know when a program is listening. Clients that haven't updated
show it as an ordinary participant, as they already do for these accounts today, so nothing
has to ship first. Being a participant, a program is recorded and transcribed like anyone
else, under the existing call notice.
The web app and native plugins do not move onto the call helpers. They share the routes and the contract, not code.
Observability
- Backend:
call.joinandcall.startwithcall.id, principal kind,call.client, and outcome (in_other_call,already_connected,ended). @macro-inc/sdk/calls:call.sdk.connect,call.sdk.publish_screen(source kind, resolution, fps, outcome),call.sdk.disconnected(reason), sent through the SDK's existing observer, searchable bycall.id.- Never: tokens, display names, share links.
Testing
- SDK: mocked tests for each method;
bun run coveragewith wrapped endpoints removed fromskipped.ts;bun run testin../sdk-docsand../code-mode-sdk. AddgetBatchCallRecordPreviewtopostReadsif wrapped. - Rust: service tests with port fakes for the join errors, the program-only end rule, and refusal in code mode; router tests for the access matrix, including team-shared viewers refused.
- Dry run: the operation catalog marks
POST /call/{channel_id}as a write, and no SDK method calls theGET. - End to end: on a local stack, a program joins with
connectRoom, a second program speaks known audio, and each hears the other. For screen share, a Node program publishes known-color frames and a headless browser in the call asserts the pixels in its share tile. Then the last person leaves and the program's room closes.
Delivery
| Phase | Ships | Result |
|---|---|---|
| 1. Join | Routes above, CallConnection, active(), ringState(), participants(), connectRoom for Node, program marking and badge, the end rule |
The existing voice agent drops its cast, its lock and its ring workaround. Calls and talking are supported |
| 2. Screen share | Spike, then publishScreen for Node and browser, /browser export |
A program can share into a call |
| 3. Events | call.* events and hydrator |
Polling goes away |
| 4. Remaining parity | call.discussion(), recording bytes, others' work, guests, bots |
The parity table is complete |
| 5. Companions | conn: identities, so I can share from a script while my app stays in the call |
Only if phase 2 shows people need it from their own identity |
The phase 2 spike comes first because video is the one unproven piece. rtc-node is proven
for audio under Bun, including its native-library needs on NixOS. Its docs show
VideoSource and TrackSource.SOURCE_SCREENSHARE but no complete screen-share example,
and we need to confirm the app renders one and whether Node has the screen-content mode
Python has (is_screencast), which affects text legibility.
Each phase updates docs/agent-guide/calls.md, crates/call/AGENTS.md and
packages/sdk/AGENTS.md, adds a @routing sentence and @agent rules to the call
namespace, and releases through release-sdk. The optional room entry points are
documented in packages/sdk/CALLS.md. Connections sit behind a server flag so
they can be turned off without an SDK release.
Decisions needed
- First principal. Recommended: agent accounts, with a person's own key also working. Bots follow in phase 4. They add a new identity type to attendance, which is real work for little gain while agent accounts exist.
- Default when already in another call. Recommended:
fail, because a program that is silently moved out of a call is the bug programs hit today. The app keepsswitch. - Programs can't hold a call open. Recommended: yes, with a 60 second total. The cost: two programs can't hold a call with each other. If that is wanted, make it an explicit option on the start.
- Agent badge. Recommended: always shown. A program in a call can hear everything, so people should be able to tell.
- Screen share in code mode. Recommended: not offered. An agent that needs it runs on a paired machine in a real process. A hosted share worker is a new service with its own cost and abuse surface, and should wait for a real need.
Out of scope
- Moderation and recording controls, until the app has them.
- Mobile or native SDKs.
- Moving the web app or native plugins onto the call helpers.
- SIP or phone dial-in.