Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

Resolve named X message recipients to observed handles

Emre Sokullu3c698ca9939b
diff --git a/docs/social-publication-contract.md b/docs/social-publication-contract.md
index 1cafbfd79..afa3dd550 100644
--- a/docs/social-publication-contract.md
+++ b/docs/social-publication-contract.md
@@ -59,4 +59,4 @@ The config accepts the existing provider fields (`providerName`, `baseUrl`, `mod
Calls run sequentially. Reports distinguish first-response validity, repairs, semantic contract errors, audit false accepts/rejects, token usage, and median/p95 latency. First-call latency is reported separately without assuming a cold server. Default results are ignored local artifacts under `test/llm/results-social-publication/`, with a Markdown report, per-case JSONL, and prompt/fixture hashes. The runner never invokes a browser action or publishes a post.
-X direct messages use their own message workflow, not the public publication contract. On `/i/chat/<conversation>`, the conversation header binds the recipient; a send binds the exact body and the identities of all mounted message rows, including hidden and pending ones. Completion requires a new matching outgoing row after the prior conversation tail with `data-send-status="sent"`, an empty composer, and the same conversation. The open X chat composer does not override that delivery evidence; other adapters retain their dialog checks. Workflow field requirements are loaded even when repeated-item tracking is disabled. Incoming, pending, failed, or pre-existing messages cannot satisfy it.
+X direct messages use their own message workflow, not the public publication contract. On `/i/chat/<conversation>`, the conversation header binds the recipient. An exact display-name or bare-username match resolves to that header's canonical handle during planning or before dispatch; subsequent verification requires the same handle, never a replacement account with the same display name. A send binds the exact body and the identities of all mounted message rows, including hidden and pending ones. Completion requires a new matching outgoing row after the prior conversation tail with `data-send-status="sent"`, an empty composer, and the same conversation. The open X chat composer does not override that delivery evidence; other adapters retain their dialog checks. Workflow field requirements are loaded even when repeated-item tracking is disabled. Incoming, pending, failed, or pre-existing messages cannot satisfy it.
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 18b8574c9..259ec10f8 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -23069,15 +23069,36 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
return recipients;
}
+ _resolveTwitterNamedMessagingTarget(target, probe) {
+ const named = normalizeMessageTarget(target);
+ if (named?.target_kind !== 'named' || named.recipients.length !== 1
+ || named.recipients[0].role !== 'to'
+ || probe?.success !== true || probe?.conclusive !== true) return null;
+ const candidates = this._messageRecipientCandidates(probe);
+ if (candidates.length !== 1 || candidates[0].role !== 'to') return null;
+ const candidate = candidates[0];
+ const handle = normalizeRecipientIdentity(candidate.identity);
+ if (!/^@[a-z0-9_]{1,15}$/.test(handle)) return null;
+ const expected = normalizeRecipientIdentity(named.recipients[0].identity);
+ // Display names and bare usernames can resolve to the unique observed
+ // header. Once pinned, an @handle must match the account itself: another
+ // account cannot borrow its authorization through a display-name alias.
+ const matches = expected.startsWith('@') ? expected === handle
+ : [candidate.identity, ...(Array.isArray(candidate.aliases) ? candidate.aliases : [])]
+ .some(alias => normalizeRecipientIdentity(alias) === expected);
+ return matches ? { target_kind: 'named', recipients: [{ identity: handle, role: 'to' }] } : null;
+ }
+
async _pinActiveConversationMessagingTarget(tabId, messaging, pageUrl = '') {
const target = normalizeMessageTarget(messaging);
- if (target?.target_kind !== 'active_conversation') return { ok: true, target };
+ if (!target) return { ok: true, target };
let policy = null;
try {
policy = getMessageRecipientGuardPolicy(pageUrl || await this._currentUrl(tabId));
} catch {}
if (!policy?.verifyActiveRecipient) return { ok: true, target };
+ if (target.target_kind === 'named' && policy.adapterName !== 'twitter') return { ok: true, target };
const probe = await this._messageRecipientContentProbe(tabId, {
tool: 'observe_active_conversation',
@@ -23085,6 +23106,11 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
adapterName: policy.adapterName,
supportsRecipientSets: policy.supportsRecipientSets === true,
});
+ if (target.target_kind === 'named') {
+ // If the intended conversation is not open yet, retain the requested
+ // name; dispatch will resolve it once the agent reaches that header.
+ return { ok: true, target: this._resolveTwitterNamedMessagingTarget(target, probe) || target };
+ }
const recipients = this._messageRecipientCandidates(probe);
const identityCountAccepted = policy.supportsRecipientSets === true
? recipients.length > 0
@@ -23195,6 +23221,10 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
}
}
+ const resolvedTwitterTarget = policy.adapterName === 'twitter'
+ && guard?.requiresSubmission === true && guard?.requiresStateChange === true
+ ? this._resolveTwitterNamedMessagingTarget(target, probe) : null;
+ if (resolvedTwitterTarget) target = resolvedTwitterTarget;
const messageBodyBaselineCount = Number(probe?.messageBodyBaselineCount);
const verified = probe?.success === true
&& probe.messageSend === true
@@ -23215,6 +23245,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
error: 'Message send blocked because WebBrain could not bind recipient verification to the final action dispatch. Re-read the active conversation and retry once.',
};
}
+ if (resolvedTwitterTarget) guard.messaging = resolvedTwitterTarget;
if (executionContext && typeof executionContext === 'object') {
executionContext.messageRecipientGuardRequired = true;
executionContext.messageRecipientDispatchBinding = binding;
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 583ec01c1..6f3a45a7a 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -20828,15 +20828,36 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
return recipients;
}
+ _resolveTwitterNamedMessagingTarget(target, probe) {
+ const named = normalizeMessageTarget(target);
+ if (named?.target_kind !== 'named' || named.recipients.length !== 1
+ || named.recipients[0].role !== 'to'
+ || probe?.success !== true || probe?.conclusive !== true) return null;
+ const candidates = this._messageRecipientCandidates(probe);
+ if (candidates.length !== 1 || candidates[0].role !== 'to') return null;
+ const candidate = candidates[0];
+ const handle = normalizeRecipientIdentity(candidate.identity);
+ if (!/^@[a-z0-9_]{1,15}$/.test(handle)) return null;
+ const expected = normalizeRecipientIdentity(named.recipients[0].identity);
+ // Display names and bare usernames can resolve to the unique observed
+ // header. Once pinned, an @handle must match the account itself: another
+ // account cannot borrow its authorization through a display-name alias.
+ const matches = expected.startsWith('@') ? expected === handle
+ : [candidate.identity, ...(Array.isArray(candidate.aliases) ? candidate.aliases : [])]
+ .some(alias => normalizeRecipientIdentity(alias) === expected);
+ return matches ? { target_kind: 'named', recipients: [{ identity: handle, role: 'to' }] } : null;
+ }
+
async _pinActiveConversationMessagingTarget(tabId, messaging, pageUrl = '') {
const target = normalizeMessageTarget(messaging);
- if (target?.target_kind !== 'active_conversation') return { ok: true, target };
+ if (!target) return { ok: true, target };
let policy = null;
try {
policy = getMessageRecipientGuardPolicy(pageUrl || await this._currentUrl(tabId));
} catch {}
if (!policy?.verifyActiveRecipient) return { ok: true, target };
+ if (target.target_kind === 'named' && policy.adapterName !== 'twitter') return { ok: true, target };
const probe = await this._messageRecipientContentProbe(tabId, {
tool: 'observe_active_conversation',
@@ -20844,6 +20865,11 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
adapterName: policy.adapterName,
supportsRecipientSets: policy.supportsRecipientSets === true,
});
+ if (target.target_kind === 'named') {
+ // If the intended conversation is not open yet, retain the requested
+ // name; dispatch will resolve it once the agent reaches that header.
+ return { ok: true, target: this._resolveTwitterNamedMessagingTarget(target, probe) || target };
+ }
const recipients = this._messageRecipientCandidates(probe);
const identityCountAccepted = policy.supportsRecipientSets === true
? recipients.length > 0
@@ -20954,6 +20980,10 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
}
}
+ const resolvedTwitterTarget = policy.adapterName === 'twitter'
+ && guard?.requiresSubmission === true && guard?.requiresStateChange === true
+ ? this._resolveTwitterNamedMessagingTarget(target, probe) : null;
+ if (resolvedTwitterTarget) target = resolvedTwitterTarget;
const messageBodyBaselineCount = Number(probe?.messageBodyBaselineCount);
const verified = probe?.success === true
&& probe.messageSend === true
@@ -20974,6 +21004,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
error: 'Message send blocked because WebBrain could not bind recipient verification to the final action dispatch. Re-read the active conversation and retry once.',
};
}
+ if (resolvedTwitterTarget) guard.messaging = resolvedTwitterTarget;
if (executionContext && typeof executionContext === 'object') {
executionContext.messageRecipientGuardRequired = true;
executionContext.messageRecipientDispatchBinding = binding;
diff --git a/test/fixtures/message-recipient-navigation.mjs b/test/fixtures/message-recipient-navigation.mjs
index 8cce2225f..ecb412330 100644
--- a/test/fixtures/message-recipient-navigation.mjs
+++ b/test/fixtures/message-recipient-navigation.mjs
@@ -181,6 +181,108 @@ export function registerMessageRecipientNavigationFixtures({
assert.equal(evidence(await observe()),null, 'duplicate message identities fail closed');
});
+ register(`${kind}: X named DM recipients resolve header aliases and retain the canonical handle`, async (page) => {
+ const { agent } = await setup(page);
+ const url = 'https://x.com/i/chat/123-456';
+ await page.goto(url);
+ await setupContentHtml(page, `<!doctype html><style>
+ #header {position:fixed;left:400px;top:20px}
+ textarea {position:fixed;left:400px;bottom:20px;width:400px;height:50px}
+ #send {position:fixed;left:820px;bottom:20px}
+ [role=log] {position:fixed;left:400px;top:100px;width:400px;height:300px}
+ </style><a id="header" href="/altryne"><span data-testid="dm-conversation-username">Alex Volkov</span></a>
+ <div role="log" data-testid="dm-message-scroller"></div>
+ <textarea data-testid="dm-composer-textarea"></textarea><button id="send" type="button">Send</button>`, kind);
+ await page.evaluate(() => {
+ window.fixtureSends = 0;
+ document.querySelector('#send').addEventListener('click', () => {
+ const composer = document.querySelector('textarea');
+ const row = document.createElement('div');
+ row.dataset.testid = 'message-' + ++window.fixtureSends;
+ row.dataset.sendStatus = 'sent'; row.className = 'justify-end';
+ const content = document.createElement('div'); content.dataset.testid = 'message-text-' + window.fixtureSends;
+ const body = document.createElement('span'); body.dir = 'auto'; body.textContent = composer.value;
+ content.append(body); row.append(content); document.querySelector('[role=log]').append(row);
+ composer.value = '';
+ });
+ });
+ const named = identity => ({target_kind:'named', recipients:[{identity,role:'to'}]});
+ const canonical = named('@altryne');
+ const workflow = agent._resolvePlannerSiteWorkflow(url, {
+ request_kind:'execute', requires_submission:true, messaging:named('Alex Volkov'),
+ });
+ const start = messaging => {
+ const guard = agent._startPlanExecutionGuard(1, 'act', {
+ requestKind:'execute', requiresStateChange:true, requiresSubmission:true, messaging, siteWorkflow:workflow,
+ });
+ guard.workflowMetadataRequirementsResolved = true;
+ return guard;
+ };
+ const send = execution => agent._messageRecipientGuardBlock(1,'click',{selector:'#send'},url,execution);
+ for (const timing of ['planning', 'after-navigation']) {
+ for (const identity of ['Alex Volkov', 'altryne', '@altryne']) {
+ // The plan can start on the conversation or reach it later.
+ const pinned = await agent._pinActiveConversationMessagingTarget(
+ 1, named(identity), timing === 'planning' ? url : 'https://x.com/home',
+ );
+ assert.equal(pinned.ok, true);
+ assert.deepEqual(pinned.target, timing === 'planning' ? canonical : named(identity));
+ const guard = start(pinned.target);
+ await page.locator('textarea').fill('Hello Alex');
+ const execution = {};
+ assert.equal(await send(execution), null, JSON.stringify({timing,identity}));
+ assert.deepEqual(guard.messaging, canonical, 'bind the account handle before dispatch');
+ const clicked = await call(page, 'click', {selector:'#send', ...execution});
+ assert.equal(clicked.success, true, JSON.stringify(clicked));
+ agent._recordCompletionSubmitAttempt(1,{isSubmit:false},'click',{selector:'#send'},url,url,
+ clicked,'doc','doc',execution);
+ const submit = agent._completionSubmitStates.get(1);
+ assert.deepEqual(submit.workflowBinding.recipientTargets, canonical.recipients);
+ submit.observedAfterSubmit = true;
+ const probe = await call(page,'probe_message_recipient_guard', {
+ tool:'observe_active_conversation', adapterName:'twitter', expectedMessageBody:'Hello Alex',
+ });
+ const terminal = agent._workflowTerminalEvidenceFromDone(1,{relevantFormCount:1},url,
+ {submit,relevantForms:1,verifiedFinalSubmit:false},probe);
+ assert.equal(terminal?.verificationKind, 'message_sent', 'display-name sends can complete');
+ }
+ }
+ assert.equal(await page.evaluate(() => window.fixtureSends), 6);
+
+ await page.locator('textarea').fill('Another message');
+ for (const target of [named('Alex'), named('Someone Else'), named('@someoneelse'),
+ {target_kind:'named', recipients:[{identity:'Alex Volkov',role:'bcc'}]},
+ {target_kind:'named', recipients:['Alex Volkov','Someone Else']}]) {
+ const guard = start(target);
+ const before = structuredClone(guard.messaging);
+ assert.equal((await send({}))?.noDispatch, true, JSON.stringify(target));
+ assert.deepEqual(guard.messaging, before, 'a mismatch cannot change the authorized target');
+ }
+ await page.locator('#header').evaluate(el => {
+ const duplicate = el.cloneNode(true); duplicate.id='other-header';
+ duplicate.href='/someoneelse'; duplicate.style.cssText='position:fixed;left:400px;top:55px'; el.after(duplicate);
+ });
+ start(named('Alex Volkov'));
+ assert.equal((await send({}))?.noDispatch, true, 'ambiguous headers cannot resolve a name');
+ await page.locator('#other-header').evaluate(el => el.remove());
+
+ const guard = start(named('Alex Volkov'));
+ const execution = {};
+ assert.equal(await send(execution), null);
+ assert.deepEqual(guard.messaging, canonical);
+ // A different account must not inherit authorization, even when its
+ // display name is the old handle or the same display-name alias.
+ await page.locator('#header').evaluate(el => { el.href='/someoneelse'; });
+ const stale = await call(page,'click',{selector:'#send', ...execution});
+ assert.equal(stale.noDispatch, true, 'recipient changed between preflight and dispatch');
+ for (const label of ['Alex Volkov','@altryne']) {
+ await page.locator('#header span').evaluate((el,label) => { el.textContent=label; },label);
+ assert.equal((await send({}))?.noDispatch, true, 'canonical handle cannot be rebound through an alias');
+ assert.deepEqual(guard.messaging, canonical);
+ }
+ assert.equal(await page.evaluate(() => window.fixtureSends), 6, 'blocked retries never dispatch');
+ });
+
register(`${kind}: X conversation navigation is not classified as sending a message`, async (page) => {
const { agent } = await setup(page);
await page.goto('https://x.com/i/chat/123-456');