agent-messenger 2.27.2 → 2.29.0

package/src/platforms/teams/trouter.test.ts

@@ -0,0 +1,114 @@
+import { expect, it } from 'bun:test'
+import { gzipSync } from 'node:zlib'
+
+import {
+  buildActivityFrame,
+  buildAuthenticateFrame,
+  buildEventAck,
+  buildPingFrame,
+  buildRequestAck,
+  buildWebSocketUrl,
+  decodeMessageBody,
+  extractChatId,
+  isMessageLossFrame,
+  parseRequestFrame,
+  type TrouterInfo,
+} from './trouter'
+
+const info: TrouterInfo = {
+  socketio: 'https://pub-ent-test.trouter.teams.microsoft.com:443/',
+  surl: 'https://pub-ent-test.trouter.teams.microsoft.com:3443/v4/f/HASH/',
+  connectparams: { sr: 'abc', issuer: 'prod-2', sig: 'xyz' },
+}
+
+it('buildWebSocketUrl targets the socket.io v1 websocket path', () => {
+  const url = buildWebSocketUrl(info, 'SESSION123', 'endpoint-uuid')
+  expect(url.startsWith(`${info.socketio}socket.io/1/websocket/SESSION123?`)).toBe(true)
+  expect(url).toContain('epid=endpoint-uuid')
+  expect(url).toContain('sr=abc')
+  expect(url).toContain('auth=true')
+})
+
+it('buildAuthenticateFrame embeds the Bearer id_token and connectparams', () => {
+  const frame = buildAuthenticateFrame(info, 'ID_TOKEN')
+  expect(frame.startsWith('5:::')).toBe(true)
+  const payload = JSON.parse(frame.slice(4))
+  expect(payload.name).toBe('user.authenticate')
+  expect(payload.args[0].headers.Authorization).toBe('Bearer ID_TOKEN')
+  expect(payload.args[0].connectparams).toEqual(info.connectparams)
+})
+
+it('buildActivityFrame and buildPingFrame use the sequence number', () => {
+  expect(buildActivityFrame(3)).toBe('5:3::{"name":"user.activity","args":[{"state":"active"}]}')
+  expect(buildPingFrame(7)).toBe('5:7::{"name":"ping"}')
+})
+
+it('buildRequestAck returns a 200 ack for the request id', () => {
+  const ack = buildRequestAck(42)
+  expect(ack.startsWith('3:::')).toBe(true)
+  expect(JSON.parse(ack.slice(4))).toEqual({ id: 42, status: 200, body: '' })
+})
+
+it('buildEventAck acks numbered event frames and ignores others', () => {
+  expect(buildEventAck('5:12::{"name":"trouter.message_loss"}')).toBe('6:12::')
+  expect(buildEventAck('5:9+::{"name":"x"}')).toBe('6:9::')
+  expect(buildEventAck('1::')).toBeNull()
+  expect(buildEventAck('6:::1["pong"]')).toBeNull()
+})
+
+it('parseRequestFrame parses 3::: frames and rejects others', () => {
+  const frame = '3:::{"id":1,"method":"POST","url":"/v4/f/HASH/messaging","body":"{}"}'
+  const parsed = parseRequestFrame(frame)
+  expect(parsed?.id).toBe(1)
+  expect(parsed?.url).toBe('/v4/f/HASH/messaging')
+  expect(parseRequestFrame('5:1::{}')).toBeNull()
+  expect(parseRequestFrame('3:::not-json')).toBeNull()
+})
+
+it('parseRequestFrame rejects frames without a numeric id', () => {
+  expect(parseRequestFrame('3:::{"url":"/x/messaging"}')).toBeNull()
+  expect(parseRequestFrame('3:::{"id":"abc"}')).toBeNull()
+  expect(parseRequestFrame('3:::"just-a-string"')).toBeNull()
+  expect(parseRequestFrame('3:::null')).toBeNull()
+})
+
+it('isMessageLossFrame detects trouter.message_loss events', () => {
+  expect(isMessageLossFrame('5:2::{"name":"trouter.message_loss","args":[{}]}')).toBe(true)
+  expect(isMessageLossFrame('5:1::{"name":"trouter.connected","args":[{}]}')).toBe(false)
+  expect(isMessageLossFrame('1::')).toBe(false)
+})
+
+it('extractChatId pulls the conversation id from a link', () => {
+  expect(extractChatId('https://notifications.skype.net/v1/users/ME/conversations/19:uni01_abc@thread.v2')).toBe(
+    '19:uni01_abc@thread.v2',
+  )
+  expect(extractChatId('https://x/conversations/19:uni01_abc@thread.v2/messages/123')).toBe('19:uni01_abc@thread.v2')
+  expect(extractChatId(undefined)).toBeNull()
+  expect(extractChatId('no-conversation-here')).toBeNull()
+})
+
+it('decodeMessageBody parses plain JSON bodies', () => {
+  const body = JSON.stringify({ resourceType: 'NewMessage', resource: { id: '1' } })
+  expect(decodeMessageBody({}, body)).toEqual({ resourceType: 'NewMessage', resource: { id: '1' } })
+})
+
+it('decodeMessageBody inflates gzip+base64 bodies', () => {
+  const inner = JSON.stringify({ resourceType: 'NewMessage' })
+  const gzipped = gzipSync(Buffer.from(inner)).toString('base64')
+  const decoded = decodeMessageBody({ 'X-Microsoft-Skype-Content-Encoding': 'gzip' }, gzipped)
+  expect(decoded).toEqual({ resourceType: 'NewMessage' })
+})
+
+it('decodeMessageBody unwraps nested cp (gzip+base64) payloads', () => {
+  const inner = JSON.stringify({ resourceType: 'NewMessage', resource: { content: 'hi' } })
+  const cp = gzipSync(Buffer.from(inner)).toString('base64')
+  const decoded = decodeMessageBody({}, JSON.stringify({ cp }))
+  expect(decoded).toEqual({ resourceType: 'NewMessage', resource: { content: 'hi' } })
+})
+
+it('decodeMessageBody unwraps nested gp (base64) payloads', () => {
+  const inner = JSON.stringify({ resourceType: 'NewMessage' })
+  const gp = Buffer.from(inner).toString('base64')
+  const decoded = decodeMessageBody({}, JSON.stringify({ gp }))
+  expect(decoded).toEqual({ resourceType: 'NewMessage' })
+})

package/src/platforms/teams/trouter.ts

@@ -0,0 +1,228 @@
+import { gunzipSync } from 'node:zlib'
+
+import type { TeamsAccountType } from './types'
+
+// Trouter is Teams' internal real-time notification service. Protocol shape was
+// reverse-engineered from the Teams web client and cross-checked against the
+// open-source purple-teams and eisbaw/ost implementations. It speaks socket.io
+// v1 (colon-prefixed frames) over a WebSocket, NOT engine.io.
+
+const TROUTER_BOOTSTRAP_URL = 'https://go.trouter.teams.microsoft.com/v4/a'
+// Personal/TFL accounts register against edge.skype.com; work accounts use
+// teams.microsoft.com.
+const REGISTRAR_URL_PERSONAL = 'https://edge.skype.com/registrar/prod/v2/registrations'
+const REGISTRAR_URL_WORK = 'https://teams.microsoft.com/registrar/prod/V2/registrations'
+const CLIENTINFO_VERSION = '27/1.0.0.2024101502'
+const TC = JSON.stringify({ cv: '2024.04.01.1', ua: 'TeamsCDL', hr: '', v: CLIENTINFO_VERSION })
+const USER_AGENT =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Electron/35.3.0'
+const REGISTRATION_TTL_SECONDS = 86400
+
+export interface TrouterConnectParams {
+  [key: string]: string
+}
+
+export interface TrouterInfo {
+  socketio: string
+  surl: string
+  connectparams: TrouterConnectParams
+  ccid?: string
+}
+
+export interface TrouterRequestFrame {
+  id: number
+  url?: string
+  headers?: Record<string, string>
+  body?: string
+}
+
+interface RegistrationSpec {
+  appId: string
+  templateKey: string
+  pathSuffix: string
+  productContext: string
+}
+
+const REGISTRATION_SPECS: RegistrationSpec[] = [
+  {
+    appId: 'NextGenCalling',
+    templateKey: 'DesktopNgc_2.5:SkypeNgc',
+    pathSuffix: 'NGCallManagerWin',
+    productContext: '',
+  },
+  { appId: 'SkypeSpacesWeb', templateKey: 'SkypeSpacesWeb_2.4', pathSuffix: 'SkypeSpacesWeb', productContext: '' },
+  { appId: 'TeamsCDLWebWorker', templateKey: 'TeamsCDLWebWorker_2.6', pathSuffix: '', productContext: 'TFL' },
+]
+
+export function buildTrouterQuery(info: TrouterInfo, endpointId: string): string {
+  const params = new URLSearchParams()
+  params.set('v', 'v4')
+  for (const [key, value] of Object.entries(info.connectparams)) params.set(key, value)
+  params.set('tc', TC)
+  params.set('timeout', '40')
+  params.set('auth', 'true')
+  params.set('epid', endpointId)
+  if (info.ccid) params.set('ccid', info.ccid)
+  params.set('con_num', `${Date.now()}_1`)
+  return params.toString()
+}
+
+export async function fetchTrouterInfo(skypeToken: string, endpointId: string): Promise<TrouterInfo> {
+  const response = await fetch(`${TROUTER_BOOTSTRAP_URL}?epid=${encodeURIComponent(endpointId)}`, {
+    method: 'POST',
+    headers: { 'x-skypetoken': skypeToken, 'Content-Length': '0', 'User-Agent': USER_AGENT },
+  })
+  if (!response.ok) {
+    throw new Error(`Trouter bootstrap failed: ${response.status} ${response.statusText}`)
+  }
+  return (await response.json()) as TrouterInfo
+}
+
+export async function fetchTrouterSessionId(
+  info: TrouterInfo,
+  skypeToken: string,
+  endpointId: string,
+): Promise<string> {
+  const url = `${info.socketio}socket.io/1/?${buildTrouterQuery(info, endpointId)}`
+  const response = await fetch(url, { headers: { 'X-Skypetoken': skypeToken, 'User-Agent': USER_AGENT } })
+  if (!response.ok) {
+    throw new Error(`Trouter handshake failed: ${response.status} ${response.statusText}`)
+  }
+  const body = await response.text()
+  return body.split(':')[0]
+}
+
+export function buildWebSocketUrl(info: TrouterInfo, sessionId: string, endpointId: string): string {
+  return `${info.socketio}socket.io/1/websocket/${sessionId}?${buildTrouterQuery(info, endpointId)}`
+}
+
+export function buildAuthenticateFrame(info: TrouterInfo, idToken: string): string {
+  const message = {
+    name: 'user.authenticate',
+    args: [
+      {
+        headers: {
+          'X-Ms-Test-User': 'False',
+          Authorization: `Bearer ${idToken}`,
+          'X-MS-Migration': 'True',
+        },
+        connectparams: info.connectparams,
+      },
+    ],
+  }
+  return `5:::${JSON.stringify(message)}`
+}
+
+export function buildActivityFrame(sequence: number): string {
+  return `5:${sequence}::{"name":"user.activity","args":[{"state":"active"}]}`
+}
+
+export function buildPingFrame(sequence: number): string {
+  return `5:${sequence}::{"name":"ping"}`
+}
+
+// Trouter delivers messages as socket.io "3:::" data frames, which require an
+// HTTP-style 200 acknowledgement or the server marks the endpoint unresponsive
+// and stops routing.
+export function buildRequestAck(requestId: number): string {
+  return `3:::${JSON.stringify({ id: requestId, status: 200, body: '' })}`
+}
+
+// Server "5:<id>+::" event frames must be acked with "6:<id>::" or trouter
+// eventually drops the connection.
+export function buildEventAck(frame: string): string | null {
+  const match = frame.match(/^5:(\d+)\+?::/)
+  return match ? `6:${match[1]}::` : null
+}
+
+export async function registerEndpoint(
+  info: TrouterInfo,
+  skypeToken: string,
+  idToken: string,
+  endpointId: string,
+  accountType: TeamsAccountType,
+  makeId: () => string,
+): Promise<void> {
+  const registrarUrl = accountType === 'personal' ? REGISTRAR_URL_PERSONAL : REGISTRAR_URL_WORK
+
+  for (const spec of REGISTRATION_SPECS) {
+    // The messaging worker must reuse the endpoint id; call apps get fresh ids.
+    const registrationId = spec.appId === 'TeamsCDLWebWorker' ? endpointId : makeId()
+    const payload = {
+      clientDescription: {
+        appId: spec.appId,
+        aesKey: '',
+        languageId: 'en-US',
+        platform: 'edge',
+        templateKey: spec.templateKey,
+        platformUIVersion: CLIENTINFO_VERSION,
+        productContext: accountType === 'personal' ? spec.productContext : '',
+      },
+      registrationId,
+      nodeId: '',
+      transports: { TROUTER: [{ context: '', path: `${info.surl}${spec.pathSuffix}`, ttl: REGISTRATION_TTL_SECONDS }] },
+    }
+
+    const response = await fetch(registrarUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Skypetoken': skypeToken,
+        Authorization: `Bearer ${idToken}`,
+        'User-Agent': USER_AGENT,
+      },
+      body: JSON.stringify(payload),
+    })
+    if (!response.ok) {
+      throw new Error(`Trouter registration for ${spec.appId} failed: ${response.status}`)
+    }
+  }
+}
+
+export function parseRequestFrame(frame: string): TrouterRequestFrame | null {
+  if (!frame.startsWith('3:::')) return null
+  try {
+    const parsed = JSON.parse(frame.slice(4)) as unknown
+    if (typeof parsed !== 'object' || parsed === null) return null
+    const { id } = parsed as { id?: unknown }
+    if (typeof id !== 'number' || !Number.isFinite(id)) return null
+    return parsed as TrouterRequestFrame
+  } catch {
+    return null
+  }
+}
+
+export function isMessageLossFrame(frame: string): boolean {
+  if (!frame.startsWith('5:')) return false
+  const jsonStart = frame.indexOf('{')
+  if (jsonStart === -1) return false
+  try {
+    const payload = JSON.parse(frame.slice(jsonStart)) as { name?: string }
+    return payload.name === 'trouter.message_loss'
+  } catch {
+    return false
+  }
+}
+
+// Trouter message bodies may be gzip+base64 encoded, and nest a further encoded
+// payload under `cp` (gzip+base64) or `gp` (base64).
+export function decodeMessageBody(headers: Record<string, string>, body: string): Record<string, unknown> {
+  let raw = body
+  if (headers['X-Microsoft-Skype-Content-Encoding'] === 'gzip') {
+    raw = gunzipSync(Buffer.from(body, 'base64')).toString('utf8')
+  }
+  const obj = JSON.parse(raw) as Record<string, unknown>
+  if (typeof obj.cp === 'string') {
+    return JSON.parse(gunzipSync(Buffer.from(obj.cp, 'base64')).toString('utf8')) as Record<string, unknown>
+  }
+  if (typeof obj.gp === 'string') {
+    return JSON.parse(Buffer.from(obj.gp, 'base64').toString('utf8')) as Record<string, unknown>
+  }
+  return obj
+}
+
+export function extractChatId(link: string | undefined): string | null {
+  if (!link) return null
+  const match = link.match(/conversations\/([^/]+)/)
+  return match ? decodeURIComponent(match[1]) : null
+}

package/src/platforms/teams/types.test.ts

@@ -8,6 +8,7 @@ import {
   TeamsFileSchema,
   TeamsMessageSchema,
   TeamsReactionSchema,
+  TeamsSearchResultSchema,
   TeamsTeamSchema,
   TeamsUserSchema,
 } from './types'
@@ -87,6 +88,22 @@ it('TeamsMessageSchema rejects missing required fields', () => {
   expect(result.success).toBe(false)
 })
 
+it('TeamsSearchResultSchema validates search result shape', () => {
+  const result = TeamsSearchResultSchema.safeParse({
+    id: 'msg-123',
+    content: 'Deploy complete',
+    author: { id: 'user-123', displayName: 'Alice' },
+    channel_id: 'channel-123',
+    thread_id: 'thread-123',
+    team_name: 'Team One',
+    channel_name: 'General',
+    timestamp: '2024-01-01T00:00:00.000Z',
+    permalink: 'https://teams.microsoft.com/l/message/msg-123',
+  })
+
+  expect(result.success).toBe(true)
+})
+
 // TeamsUserSchema tests
 it('TeamsUserSchema validates correct user', () => {
   const result = TeamsUserSchema.safeParse({

package/src/platforms/teams/types.ts

@@ -26,6 +26,24 @@ export interface TeamsMessage {
   }
   content: string
   timestamp: string
+  root_message_id?: string
+  parent_message_id?: string
+  is_thread_reply?: boolean
+}
+
+export interface TeamsSearchResult {
+  id: string
+  content: string
+  author: {
+    id: string
+    displayName: string
+  }
+  channel_id: string
+  thread_id?: string
+  team_name?: string
+  channel_name?: string
+  timestamp: string
+  permalink?: string
 }
 
 export interface TeamsUser {
@@ -56,6 +74,8 @@ export interface TeamsFile {
   size: number
   url: string
   contentType?: string
+  sharepoint_url?: string
+  object_url?: string
 }
 
 export interface TeamsCredentials {
@@ -67,6 +87,8 @@ export type TeamsAccountType = 'work' | 'personal'
 
 export type TeamsRegion = 'amer' | 'emea' | 'apac'
 
+export type TeamsAuthMethod = 'device-code' | 'browser' | 'extracted' | 'manual'
+
 export interface TeamsAccount {
   token: string
   token_expires_at?: string
@@ -81,6 +103,10 @@ export interface TeamsAccount {
       team_name: string
     }
   >
+  auth_method?: TeamsAuthMethod
+  aad_refresh_token?: string
+  aad_client_id?: string
+  aad_tenant_id?: string
 }
 
 export interface TeamsConfig {
@@ -125,6 +151,24 @@ export const TeamsMessageSchema = z.object({
   }),
   content: z.string(),
   timestamp: z.string(),
+  root_message_id: z.string().optional(),
+  parent_message_id: z.string().optional(),
+  is_thread_reply: z.boolean().optional(),
+})
+
+export const TeamsSearchResultSchema = z.object({
+  id: z.string(),
+  content: z.string(),
+  author: z.object({
+    id: z.string(),
+    displayName: z.string(),
+  }),
+  channel_id: z.string(),
+  thread_id: z.string().optional(),
+  team_name: z.string().optional(),
+  channel_name: z.string().optional(),
+  timestamp: z.string(),
+  permalink: z.string().optional(),
 })
 
 export const TeamsUserSchema = z.object({
@@ -155,6 +199,8 @@ export const TeamsFileSchema = z.object({
   size: z.number(),
   url: z.string(),
   contentType: z.string().optional(),
+  sharepoint_url: z.string().optional(),
+  object_url: z.string().optional(),
 })
 
 export const TeamsCredentialsSchema = z.object({
@@ -166,6 +212,8 @@ export const TeamsAccountTypeSchema = z.enum(['work', 'personal'])
 
 export const TeamsRegionSchema = z.enum(['amer', 'emea', 'apac'])
 
+export const TeamsAuthMethodSchema = z.enum(['device-code', 'browser', 'extracted', 'manual'])
+
 export const TeamsAccountSchema = z.object({
   token: z.string(),
   token_expires_at: z.string().optional(),
@@ -180,6 +228,10 @@ export const TeamsAccountSchema = z.object({
       team_name: z.string(),
     }),
   ),
+  auth_method: TeamsAuthMethodSchema.optional(),
+  aad_refresh_token: z.string().optional(),
+  aad_client_id: z.string().optional(),
+  aad_tenant_id: z.string().optional(),
 })
 
 export const TeamsConfigSchema = z.object({
@@ -200,6 +252,31 @@ export const TeamsConfigLegacySchema = z.object({
   ),
 })
 
+export interface TeamsRealtimeMessage {
+  id: string
+  chatId: string
+  content: string
+  author: {
+    id: string
+    displayName: string
+  }
+  messageType: string
+  timestamp: string
+}
+
+export interface TeamsTrouterGenericEvent {
+  resourceType: string
+  [key: string]: unknown
+}
+
+export interface TeamsListenerEventMap {
+  message: [message: TeamsRealtimeMessage]
+  teams_event: [event: TeamsTrouterGenericEvent]
+  connected: [info: { endpointId: string }]
+  disconnected: []
+  error: [error: Error]
+}
+
 export class TeamsError extends Error {
   code: string
 
@@ -209,3 +286,12 @@ export class TeamsError extends Error {
     this.code = code
   }
 }
+
+export class TeamsAuthCapabilityError extends Error {
+  constructor() {
+    super(
+      'Requires `agent-teams auth login` — cookie-based auth (`auth extract`) can only provide a Skype token, not the Microsoft token needed for search or SharePoint/OneDrive file downloads.',
+    )
+    this.name = 'TeamsAuthCapabilityError'
+  }
+}

package/src/tui/adapters/imessage-adapter.ts

@@ -0,0 +1,131 @@
+import { ImsgClient } from '@/platforms/imessage/client'
+import { IMessageCredentialManager } from '@/platforms/imessage/credential-manager'
+
+import type { AuthHint, AuthIO, PlatformAdapter, UnifiedChannel, UnifiedMessage, Workspace } from './types'
+
+export class IMessageAdapter implements PlatformAdapter {
+  readonly name = 'iMessage'
+
+  private client: ImsgClient | null = null
+  private credManager = new IMessageCredentialManager()
+  private currentAccount: Workspace | null = null
+  private stopWatch: (() => Promise<void>) | null = null
+
+  async login(): Promise<void> {
+    const resolved = await this.credManager.resolveAccount()
+    if (!resolved) {
+      throw new Error('iMessage is not configured. Run "agent-imessage setup" or set AGENT_IMESSAGE_BIN.')
+    }
+    const client = new ImsgClient()
+    await client.login({ binaryPath: resolved.binary_path, region: resolved.region })
+    await client.connect()
+    this.client = client
+
+    const config = await this.credManager.loadConfig()
+    if (config.current && config.accounts[config.current]) {
+      const acct = config.accounts[config.current]
+      this.currentAccount = { id: acct.account_id, name: acct.label ?? acct.account_id }
+    }
+  }
+
+  async getChannels(): Promise<UnifiedChannel[]> {
+    const client = this.ensureClient()
+    const chats = await client.listChats(50)
+    return chats.map((chat) => ({ id: String(chat.id), name: chat.name }))
+  }
+
+  async getMessages(channelId: string, limit = 50): Promise<UnifiedMessage[]> {
+    const client = this.ensureClient()
+    const messages = await client.getMessages(Number.parseInt(channelId, 10), limit)
+    return messages.map((msg) => ({
+      id: msg.guid,
+      channelId,
+      author: msg.is_outgoing ? 'you' : (msg.from_name ?? msg.from ?? 'unknown'),
+      content: msg.text ?? '',
+      timestamp: msg.timestamp,
+    }))
+  }
+
+  async sendMessage(channelId: string, text: string): Promise<void> {
+    const client = this.ensureClient()
+    await client.sendMessage({ chatId: Number.parseInt(channelId, 10) }, text)
+  }
+
+  async startListening(onMessage: (msg: UnifiedMessage) => void): Promise<void> {
+    const client = this.ensureClient()
+    this.stopWatch = await client.watch(
+      (msg) =>
+        onMessage({
+          id: msg.guid,
+          channelId: String(msg.chat_id),
+          author: msg.is_outgoing ? 'you' : (msg.from_name ?? msg.from ?? 'unknown'),
+          content: msg.text ?? '',
+          timestamp: msg.timestamp,
+        }),
+      { onError: () => undefined },
+    )
+  }
+
+  stopListening(): void {
+    void this.stopWatch?.()
+    this.stopWatch = null
+  }
+
+  async getWorkspaces(): Promise<Workspace[]> {
+    const accounts = await this.credManager.listAccounts()
+    return accounts.map((acct) => ({ id: acct.account_id, name: acct.label ?? acct.account_id }))
+  }
+
+  async switchWorkspace(accountId: string): Promise<void> {
+    if (this.client) {
+      await this.client.close().catch(() => {})
+      this.client = null
+    }
+    const account = await this.credManager.getAccount(accountId)
+    if (!account) throw new Error(`Account ${accountId} not found`)
+
+    const client = new ImsgClient()
+    await client.login({ binaryPath: account.binary_path, region: account.region })
+    await client.connect()
+    this.client = client
+    this.currentAccount = { id: account.account_id, name: account.label ?? account.account_id }
+  }
+
+  getCurrentWorkspace(): Workspace | null {
+    return this.currentAccount
+  }
+
+  getAuthHint(): AuthHint {
+    return {
+      command: 'agent-imessage setup',
+      description: 'iMessage runs on this Mac via the imsg tool. Run the guided setup below.',
+    }
+  }
+
+  async authenticate(io: AuthIO): Promise<void> {
+    const bin = (await io.prompt('Path to imsg binary (blank for "imsg" on PATH)')).trim() || undefined
+    const client = new ImsgClient()
+    await client.login({ binaryPath: bin })
+    await client.connect()
+
+    const { createAccountId } = await import('@/platforms/imessage/types')
+    const now = new Date().toISOString()
+    const accountId = createAccountId(bin ?? 'default')
+    await this.credManager.setAccount({
+      account_id: accountId,
+      provider: 'imsg',
+      binary_path: bin,
+      created_at: now,
+      updated_at: now,
+    })
+    await this.credManager.setCurrent(accountId)
+
+    this.client = client
+    this.currentAccount = { id: accountId, name: accountId }
+  }
+
+  private ensureClient(): ImsgClient {
+    if (!this.client) throw new Error('Not logged in. Call login() first.')
+    return this.client
+  }
+}

package/src/tui/adapters/instagram-adapter.ts

@@ -107,8 +107,21 @@ export class InstagramAdapter implements PlatformAdapter {
       if (!code) throw new Error('Verification code is required')
       const challengeResult = await client.challengeSubmitCode(result.challengePath, code)
       userId = challengeResult.userId || userId
+    } else if (result.oneClickEmailAvailable) {
+      const { parseOneClickLoginLink } = await import('@/platforms/instagram/client')
+      io.print('Password login was rejected; this account can log in by email. Sending a login email...')
+      const { contactPoint } = await client.sendOneClickLoginEmail(username)
+      io.print(contactPoint ? `Login email sent to ${contactPoint}.` : 'Login email sent.')
+      const link = await io.prompt('Paste the "Login as ..." link from the email')
+      if (!link) throw new Error('Login link is required')
+      const parsed = parseOneClickLoginLink(link)
+      if (!parsed) throw new Error('Could not read uid and token from the pasted link')
+      const emailResult = await client.oneClickLogin(parsed.uid, parsed.token)
+      userId = emailResult.userId || userId
     }
 
+    if (!userId) throw new Error('Login did not complete')
+
     const now = new Date().toISOString()
     await this.credManager.setAccount({
       account_id: accountId,