Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { BRAND_NAME } from '@cindy/maker-shared/branding';
import type { SessionActivitySnapshot } from '@cindy/maker-shared/session-activity';
import type { BotAvatarHue } from './botAvatarHue.js';
import { isSupportedBotAvatarValue } from './botAvatarValue.js';
export type AgentIslandSessionPhase = 'running' | 'needs-interaction' | 'completed' | 'error';
export type AgentIslandInteractionKind =
| 'permission'
| 'ask_user_question'
| 'plan_review'
| 'plugin_setup'
| 'input_handoff';
export type AgentIslandActivityLineKind = 'user' | 'assistant' | 'status' | 'tool';
/**
* Compact terminal-style preview line shown inside the expanded island card.
*/
export interface AgentIslandActivityLine {
id: string;
kind: AgentIslandActivityLineKind;
text: string;
}
/**
* The companion a Bot Session speaks for. The island draws this identity instead
* of the task's title, working directory and agent mark.
*/
export interface AgentIslandCompanionSnapshot {
name: string;
/** Group the member speaks in; absent for the companion's own chat. */
groupName?: string;
/** BotAvatar hue family member; the island resolves it to its dark tint. */
hue: BotAvatarHue;
/** Bounded JPEG thumbnail (base64) when the companion has artwork. */
imageJpeg?: string;
/** Emoji, or the name's initial, painted when there is no artwork. */
glyph: string;
glyphIsInitial: boolean;
}
/**
* Renderer-facing session snapshot for the macOS Agent Island overlay.
*/
export interface AgentIslandSessionSnapshot {
/** Group-message UI only; never a maker task or a remotely relayed activity. */
groupChat?: { avatars: AgentIslandCompanionSnapshot[]; mentionLabel?: string };
/** Opaque identity of the completed card, issued by its owning process. */
completionToken?: string;
/** This completion preserves older unread state without requesting a new alert. */
completionNotification?: 'silent';
sessionId: string;
title: string;
companion?: AgentIslandCompanionSnapshot;
projectName: string | null;
detail: string;
compactDetail: string;
workingPhase?: SessionActivitySnapshot['workingPhase'];
messagePreview: AgentIslandActivityLine | null;
phase: AgentIslandSessionPhase;
agentKind: 'claude-code' | 'codex' | string;
interactionKind?: AgentIslandInteractionKind;
permissionAction: AgentIslandPermissionActionSnapshot | null;
attention: boolean;
activityLines: AgentIslandActivityLine[];
startedAt: number;
lastActivityAt: number;
}
export interface AgentIslandPermissionActionSnapshot {
requestId: string;
canAllowForSession: boolean;
}
/**
* 轻量 per-session 活动快照——桥接给 renderer 侧栏卡片(置顶卡片/列表)用,
* 让卡片在任务执行中显示与灵动岛同源的逐步活动 + 等待交互态。只取卡片要的字段
* (不含 activityLines 多行,控体积)。
*/
export interface AgentIslandSessionActivity
extends Omit<SessionActivitySnapshot, 'phase' | 'interactionKind'> {
completionToken?: string;
completionNotification?: 'silent';
phase: AgentIslandSessionPhase;
interactionKind?: AgentIslandInteractionKind;
/** Compatibility/display alias; canonical probe field is currentActionSummary. */
compactDetail: string;
/** Only marked summaries can bypass legacy Markdown recovery on another host. */
summaryFormat?: 'plain-text';
}
export type AgentIslandDisplayMode = 'compact' | 'expanded';
export type AgentIslandNotchStatus = 'closed' | 'peek' | 'expanded';
export type AgentIslandDisplayPolicy = 'closed' | 'peek' | 'blocking' | 'transient' | 'manualExpanded';
export type AgentIslandDisplaySurface = 'collapsed' | 'sessionList' | 'interactionCard' | 'completionCard';
export type AgentIslandLayoutMode = 'compact' | 'normal';
export type AgentIslandPillStatus = 'idle' | AgentIslandSessionPhase;
export type AgentIslandMascotSkin =
| 'cindy'
| 'blackcat'
| 'pululu'
| 'tarara'
| 'boli'
| 'whitesnow'
| 'annie'
| 'chaku'
| 'muffin'
| 'erika';
export type AgentIslandSoundEvent = 'start' | 'attention' | 'complete' | 'error' | 'select';
export type AgentIslandDisplayTarget =
| { mode: 'all' }
| {
mode: 'display';
displayId: number;
/** Best-effort identity used to remap Electron display ids after reboot. */
displayName?: string;
displayIndex?: number;
displayInternal?: boolean;
displayBounds?: {
x: number;
y: number;
width: number;
height: number;
};
};
export type AgentIslandSoundId =
| 'none'
| 'startup-chime'
| 'ring-chime'
| 'item-found'
| 'gem-collect'
| 'item-fanfare'
| 'victory-fanfare'
| 'error-buzz'
| 'secret-chime';
export type AgentIslandSoundChoice =
| { type: 'builtin'; id: AgentIslandSoundId }
| { type: 'custom'; path: string; name: string };
export interface AgentIslandSoundSettings {
enabled: boolean;
sounds: Record<AgentIslandSoundEvent, AgentIslandSoundChoice>;
}
export interface AgentIslandDisplayOption {
id: number;
index: number;
name: string;
isPrimary: boolean;
internal: boolean;
bounds: {
x: number;
y: number;
width: number;
height: number;
};
}
/** 顺序即设置页「图标皮肤」列表的展示顺序。 */
export const AGENT_ISLAND_MASCOT_SKINS: readonly AgentIslandMascotSkin[] = [
'cindy',
'blackcat',
'pululu',
'tarara',
'boli',
'whitesnow',
'annie',
'chaku',
'muffin',
'erika',
] as const;
export const AGENT_ISLAND_SOUND_EVENTS: readonly AgentIslandSoundEvent[] = [
'start',
'attention',
'complete',
'error',
'select',
] as const;
export const AGENT_ISLAND_SOUND_OPTIONS: readonly AgentIslandSoundId[] = [
'none',
'startup-chime',
'ring-chime',
'item-found',
'gem-collect',
'item-fanfare',
'victory-fanfare',
'error-buzz',
'secret-chime',
] as const;
/**
* 2026-07 内置音效改用中性命名后,旧持久化设置(main settings 与 renderer
* localStorage)里仍可能存着老 ID;normalize 时映射到新 ID,避免用户已选音效被
* 静默重置回默认值。
*/
const LEGACY_AGENT_ISLAND_SOUND_ID_ALIASES: Readonly<Record<string, AgentIslandSoundId>> = {
'gameboy-startup': 'startup-chime',
'sonic-ring': 'ring-chime',
'pokemon-item-found': 'item-found',
'zelda-rupee': 'gem-collect',
'zelda-item-get': 'item-fanfare',
'ff-victory': 'victory-fanfare',
'mario-incorrect': 'error-buzz',
'zelda-secret': 'secret-chime',
};
function resolveAgentIslandSoundId(value: unknown): AgentIslandSoundId | null {
if (typeof value !== 'string') return null;
if (isAgentIslandSoundId(value)) return value;
return LEGACY_AGENT_ISLAND_SOUND_ID_ALIASES[value] ?? null;
}
export const DEFAULT_AGENT_ISLAND_SOUND_SETTINGS: AgentIslandSoundSettings = {
enabled: true,
sounds: {
start: { type: 'builtin', id: 'startup-chime' },
attention: { type: 'builtin', id: 'secret-chime' },
complete: { type: 'builtin', id: 'gem-collect' },
error: { type: 'builtin', id: 'error-buzz' },
select: { type: 'builtin', id: 'none' },
},
};
export const DEFAULT_AGENT_ISLAND_MASCOT_SKIN: AgentIslandMascotSkin = 'pululu';
export const DEFAULT_AGENT_ISLAND_DISPLAY_TARGET: AgentIslandDisplayTarget = { mode: 'all' };
export const AGENT_ISLAND_MIN_DARWIN_MAJOR = 23; // macOS 14 Sonoma.
export function isAgentIslandSupportedPlatform(
platform: string | undefined,
osRelease: string | null | undefined,
): boolean {
if (platform !== 'darwin') return false;
const darwinMajor = parseDarwinMajor(osRelease);
return darwinMajor !== null && darwinMajor >= AGENT_ISLAND_MIN_DARWIN_MAJOR;
}
function parseDarwinMajor(osRelease: string | null | undefined): number | null {
if (!osRelease) return null;
const major = Number.parseInt(osRelease.split('.')[0] ?? '', 10);
return Number.isFinite(major) ? major : null;
}
export function cloneAgentIslandSoundSettings(settings: AgentIslandSoundSettings): AgentIslandSoundSettings {
return {
enabled: settings.enabled,
sounds: Object.fromEntries(
AGENT_ISLAND_SOUND_EVENTS.map((event) => [
event,
{ ...(settings.sounds[event] ?? DEFAULT_AGENT_ISLAND_SOUND_SETTINGS.sounds[event]) },
]),
) as Record<AgentIslandSoundEvent, AgentIslandSoundChoice>,
};
}
export function isAgentIslandMascotSkin(value: unknown): value is AgentIslandMascotSkin {
return typeof value === 'string' && (AGENT_ISLAND_MASCOT_SKINS as readonly string[]).includes(value);
}
export function isAgentIslandSoundId(value: unknown): value is AgentIslandSoundId {
return typeof value === 'string' && (AGENT_ISLAND_SOUND_OPTIONS as readonly string[]).includes(value);
}
export function isAgentIslandSoundChoice(value: unknown): value is AgentIslandSoundChoice {
if (typeof value !== 'object' || value === null) return false;
const record = value as Record<string, unknown>;
if (record.type === 'builtin') {
return isAgentIslandSoundId(record.id);
}
return record.type === 'custom'
&& typeof record.path === 'string'
&& record.path.trim().length > 0;
}
export function normalizeAgentIslandSoundChoice(
raw: unknown,
fallback: AgentIslandSoundChoice,
): AgentIslandSoundChoice {
const bareId = resolveAgentIslandSoundId(raw);
if (bareId !== null) {
return { type: 'builtin', id: bareId };
}
if (typeof raw !== 'object' || raw === null) return { ...fallback };
const record = raw as Record<string, unknown>;
if (record.type === 'builtin') {
const id = resolveAgentIslandSoundId(record.id);
if (id !== null) return { type: 'builtin', id };
}
if (record.type === 'custom' && typeof record.path === 'string') {
const path = record.path.trim();
if (!path) return { ...fallback };
const name = typeof record.name === 'string' && record.name.trim()
? record.name.trim()
: fileNameFromPath(path);
return { type: 'custom', path, name };
}
return { ...fallback };
}
export function isSilentAgentIslandSoundChoice(choice: AgentIslandSoundChoice): boolean {
return choice.type === 'builtin' && choice.id === 'none';
}
export function isAgentIslandSoundEvent(value: unknown): value is AgentIslandSoundEvent {
return typeof value === 'string' && (AGENT_ISLAND_SOUND_EVENTS as readonly string[]).includes(value);
}
export function cloneAgentIslandDisplayTarget(target: AgentIslandDisplayTarget): AgentIslandDisplayTarget {
return target.mode === 'display'
? {
mode: 'display',
displayId: target.displayId,
...(typeof target.displayName === 'string' ? { displayName: target.displayName } : {}),
...(typeof target.displayIndex === 'number' ? { displayIndex: target.displayIndex } : {}),
...(typeof target.displayInternal === 'boolean' ? { displayInternal: target.displayInternal } : {}),
...(target.displayBounds ? { displayBounds: { ...target.displayBounds } } : {}),
}
: { mode: 'all' };
}
export function normalizeAgentIslandDisplayTarget(raw: unknown): AgentIslandDisplayTarget {
if (typeof raw !== 'object' || raw === null) return cloneAgentIslandDisplayTarget(DEFAULT_AGENT_ISLAND_DISPLAY_TARGET);
const record = raw as Record<string, unknown>;
if (record.mode === 'display' && typeof record.displayId === 'number' && Number.isFinite(record.displayId)) {
const rawBounds = record.displayBounds;
const displayBounds = typeof rawBounds === 'object' && rawBounds !== null
? rawBounds as Record<string, unknown>
: null;
const hasBounds = displayBounds
&& typeof displayBounds.x === 'number'
&& typeof displayBounds.y === 'number'
&& typeof displayBounds.width === 'number'
&& typeof displayBounds.height === 'number';
return cloneAgentIslandDisplayTarget({
mode: 'display',
displayId: record.displayId,
...(typeof record.displayName === 'string' && record.displayName.trim()
? { displayName: record.displayName.trim() }
: {}),
...(typeof record.displayIndex === 'number' && Number.isFinite(record.displayIndex)
? { displayIndex: record.displayIndex }
: {}),
...(typeof record.displayInternal === 'boolean'
? { displayInternal: record.displayInternal }
: {}),
...(hasBounds
? {
displayBounds: {
x: displayBounds.x as number,
y: displayBounds.y as number,
width: displayBounds.width as number,
height: displayBounds.height as number,
},
}
: {}),
});
}
if (record.mode === 'all') {
return { mode: 'all' };
}
return cloneAgentIslandDisplayTarget(DEFAULT_AGENT_ISLAND_DISPLAY_TARGET);
}
/**
* Normalizes persisted or IPC-provided Agent Island sound settings. Unknown
* event/sound values are ignored so older clients can safely read newer data.
*/
export function normalizeAgentIslandSoundSettings(raw: unknown): AgentIslandSoundSettings {
const fallback = cloneAgentIslandSoundSettings(DEFAULT_AGENT_ISLAND_SOUND_SETTINGS);
if (typeof raw !== 'object' || raw === null) return fallback;
const record = raw as Record<string, unknown>;
const rawSounds = typeof record.sounds === 'object' && record.sounds !== null
? record.sounds as Record<string, unknown>
: {};
const sounds = { ...fallback.sounds };
for (const event of AGENT_ISLAND_SOUND_EVENTS) {
sounds[event] = normalizeAgentIslandSoundChoice(rawSounds[event], fallback.sounds[event]);
}
return {
enabled: typeof record.enabled === 'boolean' ? record.enabled : fallback.enabled,
sounds,
};
}
function fileNameFromPath(filePath: string): string {
const normalized = filePath.replace(/\\/g, '/');
const parts = normalized.split('/').filter(Boolean);
return parts.at(-1) ?? filePath;
}
/**
* Vibe-style priority summary for the closed/peek pill. The session list can be
* long; this snapshot is the single product answer for what the notch should
* represent while compact.
*/
export interface AgentIslandPillSnapshot {
priorityId: string | null;
priorityStatus: AgentIslandPillStatus;
priorityMicroTitle: string;
priorityCompactTitle: string;
sessionCount: number;
/** Running and not waiting on the user; disjoint from `attentionCount`. */
runningSessionCount: number;
/** Sessions blocked on the user (question / permission). */
pendingInteractionCount: number;
unreadCompletedCount: number;
deferredRevealCount: number;
attentionCount: number;
}
export function createEmptyAgentIslandPillSnapshot(): AgentIslandPillSnapshot {
return {
priorityId: null,
priorityStatus: 'idle',
priorityMicroTitle: '',
priorityCompactTitle: '',
sessionCount: 0,
runningSessionCount: 0,
pendingInteractionCount: 0,
unreadCompletedCount: 0,
deferredRevealCount: 0,
attentionCount: 0,
};
}
/**
* User-visible strings rendered by the native macOS Agent Island helper.
*
* Main owns localization and sends concrete strings with every display state
* so the Swift helper can stay renderer-agnostic.
*/
export interface AgentIslandStrings {
appName: string;
markRead?: string;
archive?: string;
newConversationTitle: string;
newConversationHint: string;
muteSound: string;
enableSound: string;
settings: string;
newMessage: string;
review: string;
needsInput: string;
completed: string;
error: string;
outputLimit: string;
input: string;
done: string;
running: string;
/** `{{attempt}}` / `{{maxAttempts}}` are interpolated by the main-process reducer. */
networkReconnecting: string;
updatingTasks: string;
/** 等待交互摘要(按 interactionKind 出人话,替代过期 tool 状态行;文案与侧栏卡片 awaiting* 对齐)。 */
awaitingPermission: string;
awaitingQuestion: string;
awaitingPlan: string;
permissionPromptTitle: string;
allowOnce: string;
alwaysAllowForSession: string;
deny: string;
}
export const DEFAULT_AGENT_ISLAND_STRINGS: AgentIslandStrings = {
appName: BRAND_NAME,
newConversationTitle: 'New Session',
newConversationHint: 'Start a new session',
muteSound: 'Mute Agent Island',
enableSound: 'Enable Agent Island sound',
settings: 'Agent Island settings',
newMessage: 'New message',
review: 'Review',
needsInput: 'Needs input',
completed: 'Completed',
error: 'Error',
outputLimit: 'The model reached its output limit, so this response may be incomplete. Send the next message to continue.',
input: 'Input',
done: 'Done',
running: 'Running',
networkReconnecting: 'Connection interrupted — reconnecting ({{attempt}}/{{maxAttempts}})…',
updatingTasks: 'Updating tasks',
awaitingPermission: 'Awaiting permission',
awaitingQuestion: 'Awaiting your reply',
awaitingPlan: 'Awaiting plan review',
permissionPromptTitle: 'Confirm permission',
allowOnce: 'Allow once',
alwaysAllowForSession: 'Always allow',
deny: 'Deny',
};
export const AGENT_ISLAND_MAX_EXPANDED_WIDTH = 440;
export const AGENT_ISLAND_MAX_RESIZABLE_WIDTH = 920;
export const AGENT_ISLAND_MIN_EXPANDED_WIDTH = 360;
export const AGENT_ISLAND_IDLE_EXPANDED_WIDTH = 340;
export const AGENT_ISLAND_COMPACT_IDLE_WIDTH = 210;
export const AGENT_ISLAND_COMPACT_MIN_WIDTH = 80;
export const AGENT_ISLAND_COMPACT_ACTIVE_WIDTH = 298;
export const AGENT_ISLAND_SIMULATED_NOTCH_WIDTH_RATIO = 0.14;
export const AGENT_ISLAND_SIMULATED_NOTCH_MIN_WIDTH = 160;
export const AGENT_ISLAND_SIMULATED_NOTCH_MAX_WIDTH = 240;
export const AGENT_ISLAND_COMPACT_SIMULATED_ACTIVE_EXTRA_WIDTH = 88;
export const AGENT_ISLAND_COMPACT_HARDWARE_IDLE_EXTRA_WIDTH = 64;
export const AGENT_ISLAND_COMPACT_HARDWARE_ACTIVE_EXTRA_WIDTH = 64;
export const AGENT_ISLAND_COMPACT_HARDWARE_HIDDEN_PULL_DISTANCE = 48;
// Compact count-badge metrics, kept in sync with `PillBadge` in
// `native/agent-island/macos-agent-island-helper.swift`. These describe the *nominal*
// width used to reserve carrier space — the native helper computes the same nominal
// value (it does not measure the font for layout), while the badge itself is still
// drawn by SwiftUI with the real font. The nominal value is an upper bound of what
// gets drawn, so reserved space is never short.
export const AGENT_ISLAND_COMPACT_BADGE_MIN_WIDTH = 22;
export const AGENT_ISLAND_COMPACT_BADGE_PAIR_MIN_WIDTH = 30;
export const AGENT_ISLAND_COMPACT_BADGE_CONTENT_INSET = 2;
export const AGENT_ISLAND_COMPACT_BADGE_TEXT_SPACING = 1;
/** Generous upper bound for one monospaced 10pt digit (real advance is ~6pt). */
export const AGENT_ISLAND_COMPACT_BADGE_CHAR_WIDTH_BOUND = 7;
/**
* Per-segment rounding slack, mirroring `PillBadge.segmentRoundingSlack` in the Swift
* helper (`ceil(measured + 1)` per `Text`). SwiftUI lays out and rounds every `Text`
* run separately, so the slack is added once per segment — not once per badge. Dropping
* it would make this estimate fall below the native width and let the badge get clipped
* again; `agentIslandCompactBadgeWidth.test.ts` guards that.
*/
export const AGENT_ISLAND_COMPACT_BADGE_SEGMENT_ROUNDING_SLACK = 1;
/** Upper bound of the native `hardwareNotchSideInset` beside the badge. */
export const AGENT_ISLAND_COMPACT_HARDWARE_BADGE_RESERVED_INSET = 9;
export const AGENT_ISLAND_MAX_EXPANDED_HEIGHT = 560;
export const AGENT_ISLAND_SCREEN_EDGE_GUTTER = 112;
export const AGENT_ISLAND_CARRIER_COMPACT_INSET = 20;
export const AGENT_ISLAND_CARRIER_EXPANDED_INSET = 80;
export const AGENT_ISLAND_CLOSED_HEIGHT = 34;
export const AGENT_ISLAND_IDLE_EXPANDED_HEIGHT = 154;
export const AGENT_ISLAND_EXPANDED_MIN_HEIGHT = 176;
export const AGENT_ISLAND_EXPANDED_MEASURED_MIN_HEIGHT = 118;
export const AGENT_ISLAND_EXPANDED_FALLBACK_HEIGHT = 190;
export const AGENT_ISLAND_EXPANDED_LIST_MAX_VISIBLE_ROWS = 5;
export const AGENT_ISLAND_EXPANDED_LIST_ROW_HEIGHT = 90;
export const AGENT_ISLAND_EXPANDED_LIST_VERTICAL_CHROME = 60;
export const AGENT_ISLAND_EXPANDED_MEASURED_HEIGHT_OFFSET = 8;
export const AGENT_ISLAND_EXPANDED_HARDWARE_NOTCH_SIDE_WIDTH = 96;
export const AGENT_ISLAND_EXPANDED_HARDWARE_NOTCH_HORIZONTAL_PADDING = 36;
export interface AgentIslandScreenLayoutMetrics {
hasNotch: boolean;
notchWidth: number;
}
export function computeAgentIslandSimulatedNotchWidth(displayWidth: number): number {
return Math.min(
AGENT_ISLAND_SIMULATED_NOTCH_MAX_WIDTH,
Math.max(AGENT_ISLAND_SIMULATED_NOTCH_MIN_WIDTH, displayWidth * AGENT_ISLAND_SIMULATED_NOTCH_WIDTH_RATIO),
);
}
export type AgentIslandCompactBadgeCounts = Pick<
AgentIslandPillSnapshot,
'attentionCount' | 'runningSessionCount' | 'sessionCount'
>;
/**
* Text segments of the compact count badge, mirroring `PillBadge.segments` in
* `macos-agent-island-helper.swift`:
*
* - only running tasks → `running`
* - something needs attention and tasks are running → `attention · running`
* - only attention → `attention`
* - neither (e.g. read completions still on the island) → session count
*/
export function getAgentIslandCompactBadgeSegments(input: AgentIslandCompactBadgeCounts): string[] {
if (input.attentionCount > 0 && input.runningSessionCount > 0) {
return [`${input.attentionCount}`, '·', `${input.runningSessionCount}`];
}
if (input.attentionCount > 0) return [`${input.attentionCount}`];
if (input.runningSessionCount > 0) return [`${input.runningSessionCount}`];
return [`${Math.max(1, input.sessionCount)}`];
}
/**
* Upper-bound width of the compact count badge the native helper draws, mirroring
* `PillBadge.intrinsicWidth` in `macos-agent-island-helper.swift`.
*
* The carrier window sizes itself from this, so the native side can only ever clamp
* the island *down* to its own exact measurement — never get clipped for lack of room.
* That is why the per-character advance below is deliberately generous: the real
* monospaced 10pt advance is ~6pt, and overestimating only leaves invisible slack
* inside the carrier's transparent inset.
*/
export function getAgentIslandCompactBadgeWidth(input: AgentIslandCompactBadgeCounts): number {
const segments = getAgentIslandCompactBadgeSegments(input);
const segmentsWidth = segments.reduce(
(total, segment) => total
+ segment.length * AGENT_ISLAND_COMPACT_BADGE_CHAR_WIDTH_BOUND
+ AGENT_ISLAND_COMPACT_BADGE_SEGMENT_ROUNDING_SLACK,
0,
);
const spacing = AGENT_ISLAND_COMPACT_BADGE_TEXT_SPACING * Math.max(0, segments.length - 1);
const minWidth = segments.length > 1
? AGENT_ISLAND_COMPACT_BADGE_PAIR_MIN_WIDTH
: AGENT_ISLAND_COMPACT_BADGE_MIN_WIDTH;
return Math.max(
minWidth,
segmentsWidth + spacing + AGENT_ISLAND_COMPACT_BADGE_CONTENT_INSET * 2,
);
}
export function getAgentIslandDefaultContentWidth(input: {
expanded: boolean;
hasSession: boolean;
displayWidth?: number;
screenMetrics?: AgentIslandScreenLayoutMetrics | null;
pillSnapshot?: AgentIslandCompactBadgeCounts | null;
}): number {
if (input.expanded) {
return input.hasSession ? AGENT_ISLAND_MAX_EXPANDED_WIDTH : AGENT_ISLAND_IDLE_EXPANDED_WIDTH;
}
const notchWidth = input.screenMetrics
? input.screenMetrics.notchWidth
: (typeof input.displayWidth === 'number'
? computeAgentIslandSimulatedNotchWidth(input.displayWidth)
: AGENT_ISLAND_COMPACT_IDLE_WIDTH);
if (input.screenMetrics?.hasNotch) {
const baseExtra = input.hasSession
? AGENT_ISLAND_COMPACT_HARDWARE_ACTIVE_EXTRA_WIDTH
: AGENT_ISLAND_COMPACT_HARDWARE_IDLE_EXTRA_WIDTH;
// Both notch sides are symmetric, so a wide badge costs twice its side width.
const badgeExtra = input.hasSession && input.pillSnapshot
? (getAgentIslandCompactBadgeWidth(input.pillSnapshot)
+ AGENT_ISLAND_COMPACT_HARDWARE_BADGE_RESERVED_INSET) * 2
: 0;
return Math.max(
AGENT_ISLAND_COMPACT_IDLE_WIDTH,
notchWidth + Math.max(baseExtra, badgeExtra),
);
}
if (typeof input.displayWidth === 'number' || input.screenMetrics) {
return Math.max(
AGENT_ISLAND_COMPACT_IDLE_WIDTH,
notchWidth + (input.hasSession ? AGENT_ISLAND_COMPACT_SIMULATED_ACTIVE_EXTRA_WIDTH : 0),
);
}
return input.hasSession ? AGENT_ISLAND_COMPACT_ACTIVE_WIDTH : AGENT_ISLAND_COMPACT_IDLE_WIDTH;
}
export function getAgentIslandMinimumContentWidth(input: {
expanded: boolean;
screenMetrics?: AgentIslandScreenLayoutMetrics | null;
}): number {
if (input.expanded) {
if (input.screenMetrics?.hasNotch) {
return Math.max(
AGENT_ISLAND_MIN_EXPANDED_WIDTH,
input.screenMetrics.notchWidth
+ AGENT_ISLAND_EXPANDED_HARDWARE_NOTCH_SIDE_WIDTH * 2
+ AGENT_ISLAND_EXPANDED_HARDWARE_NOTCH_HORIZONTAL_PADDING,
);
}
return AGENT_ISLAND_MIN_EXPANDED_WIDTH;
}
if (input.screenMetrics?.hasNotch) {
return Math.max(1, input.screenMetrics.notchWidth);
}
return AGENT_ISLAND_COMPACT_MIN_WIDTH;
}
export function snapAgentIslandCompactHardwareContentWidth(input: {
desiredWidth: number;
clampedWidth: number;
maxWidth: number;
hasSession: boolean;
screenMetrics?: AgentIslandScreenLayoutMetrics | null;
pillSnapshot?: AgentIslandCompactBadgeCounts | null;
}): number {
if (!input.screenMetrics?.hasNotch) {
return input.clampedWidth;
}
const hiddenWidth = Math.min(input.maxWidth, Math.max(1, input.screenMetrics.notchWidth));
// hidden/basic 的分类必须锚在与徽标无关的 basic 宽度上。否则计数一变多、basic 宽度被撑大后,
// 用户此前停在 basic 的持久化宽度会突然落到 hidden 阈值以下,整个 compact 岛被收起。
const baseBasicWidth = Math.min(
input.maxWidth,
Math.max(hiddenWidth, getAgentIslandDefaultContentWidth({
expanded: false,
hasSession: input.hasSession,
screenMetrics: input.screenMetrics,
})),
);
const basicWidth = Math.min(
input.maxWidth,
Math.max(hiddenWidth, getAgentIslandDefaultContentWidth({
expanded: false,
hasSession: input.hasSession,
screenMetrics: input.screenMetrics,
pillSnapshot: input.pillSnapshot,
})),
);
const gap = baseBasicWidth - hiddenWidth;
if (gap <= 8) {
return hiddenWidth;
}
const hiddenThreshold = baseBasicWidth - Math.min(
AGENT_ISLAND_COMPACT_HARDWARE_HIDDEN_PULL_DISTANCE,
Math.max(24, gap * 0.5),
);
if (input.desiredWidth <= hiddenThreshold) {
return hiddenWidth;
}
// 只有落在与徽标无关的 basic 吸附位及以下的宽度才升级到当前(可能更宽的)basic。
// 用 basicWidth 判定会把介于两个吸附点之间的自由宽度(如旧 basic 264 与 11/12 的 306
// 之间的 280)一并吞掉,再被 native 的持久化归一化改写成 264,永久覆盖用户偏好。
if (input.desiredWidth <= baseBasicWidth) {
return basicWidth;
}
return input.clampedWidth;
}
/**
* Full display payload pushed from main to the native Agent Island helper.
*/
export interface AgentIslandDisplayState {
visible: boolean;
mode: AgentIslandDisplayMode;
notchStatus: AgentIslandNotchStatus;
displayPolicy: AgentIslandDisplayPolicy;
displaySurface: AgentIslandDisplaySurface;
layoutMode: AgentIslandLayoutMode;
appFocused: boolean;
smartSuppressed: boolean;
shadowVisible: boolean;
currentSessionId: string | null;
expandedDisplayId: number | null;
pillSnapshot: AgentIslandPillSnapshot;
sessions: AgentIslandSessionSnapshot[];
totalCount: number;
measuredContentHeight: number;
strings: AgentIslandStrings;
soundSettings: AgentIslandSoundSettings;
mascotSkin: AgentIslandMascotSkin;
updatedAt: number;
}
export function createDefaultAgentIslandDisplayConfig(): Pick<
AgentIslandDisplayState,
'strings' | 'soundSettings' | 'mascotSkin'
> {
return {
strings: { ...DEFAULT_AGENT_ISLAND_STRINGS },
soundSettings: cloneAgentIslandSoundSettings(DEFAULT_AGENT_ISLAND_SOUND_SETTINGS),
mascotSkin: DEFAULT_AGENT_ISLAND_MASCOT_SKIN,
};
}
export function computeAgentIslandContentHeight(input: {
mode: AgentIslandDisplayMode;
displaySurface: AgentIslandDisplaySurface;
hasSession: boolean;
totalCount: number;
measuredContentHeight: number;
}): number {
if (input.mode !== 'expanded') {
return AGENT_ISLAND_CLOSED_HEIGHT;
}
if (!input.hasSession) return AGENT_ISLAND_IDLE_EXPANDED_HEIGHT;
if (input.measuredContentHeight > 0) {
return Math.min(
AGENT_ISLAND_MAX_EXPANDED_HEIGHT,
Math.max(
AGENT_ISLAND_EXPANDED_MEASURED_MIN_HEIGHT,
Math.ceil(input.measuredContentHeight + AGENT_ISLAND_EXPANDED_MEASURED_HEIGHT_OFFSET),
),
);
}
if (input.displaySurface === 'sessionList' && input.totalCount > 1) {
const visibleRows = Math.min(input.totalCount, AGENT_ISLAND_EXPANDED_LIST_MAX_VISIBLE_ROWS);
return Math.max(
AGENT_ISLAND_EXPANDED_MIN_HEIGHT,
Math.min(
AGENT_ISLAND_MAX_EXPANDED_HEIGHT,
AGENT_ISLAND_EXPANDED_LIST_VERTICAL_CHROME
+ visibleRows * AGENT_ISLAND_EXPANDED_LIST_ROW_HEIGHT,
),
);
}
return Math.max(
AGENT_ISLAND_EXPANDED_MIN_HEIGHT,
Math.min(AGENT_ISLAND_MAX_EXPANDED_HEIGHT, AGENT_ISLAND_EXPANDED_FALLBACK_HEIGHT),
);
}
/** main → renderer:per-session 活动快照(侧栏卡片用)。 */
export const AGENT_ISLAND_SESSION_SNAPSHOTS_CHANNEL = 'agent-island:session-snapshots';
export const AGENT_ISLAND_SET_VISIBLE_SESSION_CHANNEL = 'agent-island:set-visible-session';
/**
* renderer(主窗)→ main:灵动岛点击的目标地址已提交,且目标没有处置控件(群专线所在的群、
* 只读历史、不可用的委派任务),请求处置被点的那张卡。参数为 sessionId 与这次点击的
* islandEntryId;main 只认最近一次点击、且卡片身份未变。
*/
export const AGENT_ISLAND_CONSUME_ENTRY_ALERT_CHANNEL = 'agent-island:consume-entry-alert';
export const AGENT_ISLAND_SET_ENABLED_CHANNEL = 'agent-island:set-enabled';
export const AGENT_ISLAND_SET_SOUND_SETTINGS_CHANNEL = 'agent-island:set-sound-settings';
export const AGENT_ISLAND_SET_MASCOT_SKIN_CHANNEL = 'agent-island:set-mascot-skin';
export const AGENT_ISLAND_SET_DISPLAY_TARGET_CHANNEL = 'agent-island:set-display-target';
export const AGENT_ISLAND_GET_DISPLAY_OPTIONS_CHANNEL = 'agent-island:get-display-options';
export const AGENT_ISLAND_PREVIEW_SOUND_CHANNEL = 'agent-island:preview-sound';
export const AGENT_ISLAND_SELECT_SOUND_FILE_CHANNEL = 'agent-island:select-sound-file';
/** renderer(主窗)→ main:按侧栏「任务范围」筛过的远程设备任务活动。 */
export const AGENT_ISLAND_SET_REMOTE_SESSIONS_CHANNEL = 'agent-island:set-remote-sessions';
// Local main-window presentation only; never exposed through device-link.
export const AGENT_ISLAND_SET_COMPANION_CHATS_CHANNEL = 'agent-island:set-companion-chats';
export const AGENT_ISLAND_READ_COMPANION_CHAT_CHANNEL = 'agent-island:read-companion-chat';
export interface AgentIslandCompanionChatInput {
sessionId: string;
botId: string;
deviceId: string | null;
companion: AgentIslandRemoteCompanionInput;
visible: boolean;
unread: boolean;
lastMessageAt: number;
preview: string;
}
export interface AgentIslandCompanionChatsInput {
dataOwnerId: string | null;
ownerGeneration: number;
chats: AgentIslandCompanionChatInput[];
}
export interface AgentIslandCompanionChatRead extends AgentIslandCompanionChatInput {
readThroughAt: number;
}
export function parseAgentIslandCompanionChats(raw: unknown): AgentIslandCompanionChatInput[] | null {
if (!Array.isArray(raw) || raw.length > AGENT_ISLAND_REMOTE_SESSIONS_MAX) return null;
const chats: AgentIslandCompanionChatInput[] = [];
const seen = new Set<string>();
for (const item of raw) {
if (!item || typeof item !== 'object') return null;
const row = item as Record<string, unknown>;
const sessionId = readBoundedString(row.sessionId, AGENT_ISLAND_REMOTE_ID_MAX_LENGTH);
const botId = readBoundedString(row.botId, AGENT_ISLAND_REMOTE_ID_MAX_LENGTH);
const deviceId = row.deviceId === null ? null : readBoundedString(row.deviceId, AGENT_ISLAND_REMOTE_ID_MAX_LENGTH);
const companion = readRemoteCompanion(row.companion);
if (!sessionId || !botId || !companion || (row.deviceId !== null && !deviceId)
|| typeof row.visible !== 'boolean' || typeof row.unread !== 'boolean'
|| typeof row.lastMessageAt !== 'number' || !Number.isFinite(row.lastMessageAt) || row.lastMessageAt < 0
|| seen.has(sessionId)) return null;
seen.add(sessionId);
chats.push({ sessionId, botId, deviceId, companion, visible: row.visible, unread: row.unread,
lastMessageAt: row.lastMessageAt, preview: readBoundedString(row.preview, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH) ?? '' });
}
return chats;
}
/**
* 远程设备(device-link「我控制它」)任务的活动镜像,供本机灵动岛与桌面通知使用。
* 只含 running / needs-interaction / 未读终态;范围由 renderer 按侧栏「任务范围」裁剪。
*/
export interface AgentIslandRemoteSessionInput {
summaryFormat?: 'plain-text';
completionToken?: string;
completionNotification?: 'pending' | 'teammate' | 'silent';
sessionId: string;
deviceId: string;
deviceName: string | null;
title: string | null;
workingDir: string | null;
workspaceKind: string | null;
/** DB 形态('cc' | 'codex' | 'pi')。 */
agentKind: string | null;
phase: AgentIslandSessionPhase;
detail: string;
workingPhase?: string;
interactionKind?: AgentIslandInteractionKind;
/** The companion this chat speaks for, when its main computer is the other device. */
companion?: AgentIslandRemoteCompanionInput;
}
export interface AgentIslandRemoteCompanionInput {
name: string;
/** Stored avatar value as the other computer reports it (grapheme, preset, its blob or a cloud image). */
avatar: string;
avatarColor: string;
}
/** Upper bound the IPC parser accepts; builders trim to it so one extra entry never voids the payload. */
export const AGENT_ISLAND_REMOTE_SESSIONS_MAX = 500;
const AGENT_ISLAND_REMOTE_ID_MAX_LENGTH = 256;
const AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH = 1024;
/** Longest stored companion avatar value (a cloud image address); anything longer is dropped. */
const AGENT_ISLAND_REMOTE_AVATAR_MAX_LENGTH = 2048;
const AGENT_ISLAND_SESSION_PHASES: readonly AgentIslandSessionPhase[] = [
'running',
'needs-interaction',
'completed',
'error',
];
const AGENT_ISLAND_INTERACTION_KINDS: readonly AgentIslandInteractionKind[] = [
'permission',
'ask_user_question',
'plan_review',
'plugin_setup',
'input_handoff',
];
/** renderer payload 的运行时校验:整体形状非法返回 null,单条非法条目丢弃。 */
export function parseAgentIslandRemoteSessions(raw: unknown): AgentIslandRemoteSessionInput[] | null {
if (!Array.isArray(raw) || raw.length > AGENT_ISLAND_REMOTE_SESSIONS_MAX) return null;
const out: AgentIslandRemoteSessionInput[] = [];
const seen = new Set<string>();
for (const item of raw) {
if (typeof item !== 'object' || item === null) continue;
const record = item as Record<string, unknown>;
const sessionId = readBoundedString(record.sessionId, AGENT_ISLAND_REMOTE_ID_MAX_LENGTH);
const deviceId = readBoundedString(record.deviceId, AGENT_ISLAND_REMOTE_ID_MAX_LENGTH);
const phase = record.phase;
if (!sessionId || !deviceId || seen.has(sessionId)) continue;
if (!(AGENT_ISLAND_SESSION_PHASES as readonly unknown[]).includes(phase)) continue;
seen.add(sessionId);
const interactionKind = (AGENT_ISLAND_INTERACTION_KINDS as readonly unknown[]).includes(record.interactionKind)
? record.interactionKind as AgentIslandInteractionKind
: undefined;
const workingPhase = readBoundedString(record.workingPhase, 64);
const completionToken = readBoundedString(record.completionToken, 128);
const companion = readRemoteCompanion(record.companion);
out.push({
sessionId,
deviceId,
...(completionToken ? { completionToken } : {}),
deviceName: readBoundedString(record.deviceName, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH),
title: readBoundedString(record.title, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH),
workingDir: readBoundedString(record.workingDir, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH * 4),
workspaceKind: readBoundedString(record.workspaceKind, 64),
agentKind: readBoundedString(record.agentKind, 64),
phase: phase as AgentIslandSessionPhase,
...(record.completionNotification === 'pending' || record.completionNotification === 'teammate' || record.completionNotification === 'silent'
? { completionNotification: record.completionNotification } : {}),
detail: readBoundedString(record.detail, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH) ?? '',
...(record.summaryFormat === 'plain-text' ? { summaryFormat: 'plain-text' as const } : {}),
...(workingPhase ? { workingPhase } : {}),
...(interactionKind ? { interactionKind } : {}),
...(companion ? { companion } : {}),
});
}
return out;
}
function readRemoteCompanion(value: unknown): AgentIslandRemoteCompanionInput | null {
if (typeof value !== 'object' || value === null) return null;
const record = value as Record<string, unknown>;
const name = readBoundedString(record.name, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH);
if (!name) return null;
// Bound the raw value before trimming or grapheme parsing: an oversized one is never an avatar.
const rawAvatar = typeof record.avatar === 'string' && record.avatar.length <= AGENT_ISLAND_REMOTE_AVATAR_MAX_LENGTH
? record.avatar
: '';
const avatar = rawAvatar.trim();
// Only values a companion avatar can hold: never an arbitrary local path or data URI.
const supportedAvatar = (avatar.startsWith('https://') && avatar.length <= AGENT_ISLAND_REMOTE_AVATAR_MAX_LENGTH)
|| isSupportedBotAvatarValue(avatar);
return {
name,
avatar: supportedAvatar ? avatar : '',
avatarColor: readBoundedString(record.avatarColor, 64) ?? '',
};
}
function readBoundedString(value: unknown, maxLength: number): string | null {
if (typeof value !== 'string') return null;
const trimmed = value.trim();
if (!trimmed) return null;
return trimmed.length > maxLength ? trimmed.slice(0, maxLength) : trimmed;
}