Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import AsyncStorage from '@react-native-async-storage/async-storage';
import {
isPreconditionFailedRemoteError,
withTransientRemoteRetry,
} from '@cindy/maker-shared/device-link-contract';
/**
* 移动端两步建会话的恢复账本。
*
* 手机在 worktree:create 前先把 sessionId + recoveryKey 持久化;即使进程在 create
* 回包前被系统杀掉,重启后也能让被控端按该随机键解析真实路径并安全回收。拿到
* create 回包后再补写 path,兼容旧的 path-only 记录。账本不保存草稿、消息、凭证
* 或 worktree 内容,并按账号隔离,避免换账号误碰旧设备。
*/
const STORAGE_KEY_PREFIX = 'xdt.mobile.precreated-worktree-recovery.v1.';
const STORAGE_VERSION = 1;
const MAX_RECORDS = 32;
const MAX_RECORD_AGE_MS = 30 * 24 * 60 * 60 * 1000;
const MAX_SESSION_ID_LENGTH = 256;
const MAX_DEVICE_ID_LENGTH = 256;
const MAX_PATH_LENGTH = 4_096;
const MIN_RECOVERY_KEY_LENGTH = 16;
const MAX_RECOVERY_KEY_LENGTH = 256;
const RECOVERY_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
interface PendingPrecreatedWorktreeBase {
sessionId: string;
deviceId: string;
createdAt: number;
/**
* Every phase may have an in-flight create request. Recovery always requires
* the host cancellation fence, including reservations without a create ACK.
*/
phase: 'reserved' | 'precreated' | 'session-create-started';
}
export type PendingPrecreatedWorktree = PendingPrecreatedWorktreeBase & (
| {
/** create 回包后可用;旧账本只有该定位符。 */
path: string;
recoveryKey?: string;
}
| {
path?: never;
/** create 前持久化的新定位符。 */
recoveryKey: string;
}
);
interface StoredRecoveryLedger {
version: typeof STORAGE_VERSION;
records: PendingPrecreatedWorktree[];
}
export interface PrecreatedWorktreeRecoveryDeps {
openLink: (deviceId: string) => Promise<unknown>;
discardPrecreated: (
deviceId: string,
input:
| { sessionId: string; path: string; recoveryKey?: never }
| { sessionId: string; recoveryKey: string; path?: never },
) => Promise<unknown>;
cancelPrecreated?: PrecreatedWorktreeRecoveryDeps['discardPrecreated'];
onDiscarded?: (record: PendingPrecreatedWorktree) => void | Promise<void>;
/**
* PRECONDITION_FAILED 既可能表示会话已经认领 worktree,也可能表示
* worktree 有改动/保留标记。调用方用权威 get-session 区分二者,只有前者
* 才能从账本移除。
*/
isSessionClaimed: (deviceId: string, sessionId: string) => Promise<boolean>;
/** 测试注入;生产使用 withTransientRemoteRetry 的默认退避。 */
sleep?: (ms: number) => Promise<void>;
/** 任务仍在当前进程内时延后,避免恢复 bridge 与创建管线竞态。 */
shouldDefer?: (record: PendingPrecreatedWorktree) => boolean;
/**
* 账号 owner generation fence。账号切换后旧 run 必须在下一次远程 ownership
* probe / discard 前停止;否则稳定的 Device Link callback 可能取到新账号的
* client,对旧账号的 recoveryKey 执行 destructive discard。
*/
isCurrent?: () => boolean;
}
export interface PrecreatedWorktreeRecoveryResult {
attempted: number;
recovered: number;
deferred: number;
retained: number;
storageReadable: boolean;
}
let mutationQueue: Promise<void> = Promise.resolve();
const registrationInFlight = new Map<string, number>();
// AsyncStorage 写失败时仍保留当前进程的 cleanup obligation。它不是跨进程
// 持久化替代品;作用是让本进程重连恢复、并阻止下一次创建继续制造孤儿。
const volatileLedgers = new Map<string, PendingPrecreatedWorktree[]>();
function markRegistrationInFlight(sessionId: string): void {
registrationInFlight.set(
sessionId,
(registrationInFlight.get(sessionId) ?? 0) + 1,
);
}
function unmarkRegistrationInFlight(sessionId: string): void {
const count = registrationInFlight.get(sessionId) ?? 0;
if (count <= 1) {
registrationInFlight.delete(sessionId);
} else {
registrationInFlight.set(sessionId, count - 1);
}
}
function enqueueMutation<T>(operation: () => Promise<T>): Promise<T> {
const run = mutationQueue.then(operation, operation);
mutationQueue = run.then(
() => undefined,
() => undefined,
);
return run;
}
function normalizeAccountId(accountId: string): string {
return typeof accountId === 'string' ? accountId.trim() : '';
}
function storageKeyForAccount(accountId: string): string | null {
const normalized = normalizeAccountId(accountId);
if (!normalized) return null;
// 不把完整账号标识直接作为 key;保留可读前缀便于诊断,同时用 hash
// 防止含特殊字符的账号破坏 AsyncStorage key 约定。
return `${STORAGE_KEY_PREFIX}${sanitizeSegment(normalized)}.${fnv1a(normalized)}`;
}
function sanitizeSegment(value: string): string {
return value.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 48) || 'account';
}
function fnv1a(value: string): string {
let hash = 0x811c9dc5;
for (let index = 0; index < value.length; index += 1) {
hash ^= value.charCodeAt(index);
hash = Math.imul(hash, 0x01000193) >>> 0;
}
return hash.toString(16).padStart(8, '0');
}
function volatileRecordsForAccount(
accountId: string,
): PendingPrecreatedWorktree[] {
const key = storageKeyForAccount(accountId);
return key ? (volatileLedgers.get(key) ?? []) : [];
}
function replaceVolatileRecords(
accountId: string,
records: readonly PendingPrecreatedWorktree[],
): void {
const key = storageKeyForAccount(accountId);
if (!key) return;
const normalized = normalizeRecords(records);
if (normalized.length === 0) {
volatileLedgers.delete(key);
} else {
volatileLedgers.set(key, normalized);
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return !!value && typeof value === 'object' && !Array.isArray(value);
}
function readString(value: unknown, maxLength: number): string | null {
if (typeof value !== 'string') return null;
const normalized = value.trim();
return normalized.length > 0 && normalized.length <= maxLength
? normalized
: null;
}
function readRecoveryKey(value: unknown): string | null {
const normalized = readString(value, MAX_RECOVERY_KEY_LENGTH);
return normalized
&& normalized.length >= MIN_RECOVERY_KEY_LENGTH
&& RECOVERY_KEY_PATTERN.test(normalized)
? normalized
: null;
}
function readRecoveryPhase(
value: unknown,
): PendingPrecreatedWorktreeBase['phase'] {
return value === 'reserved' || value === 'precreated'
|| value === 'session-create-started'
? value
: 'session-create-started';
}
function coerceRecord(
value: unknown,
now: number,
): PendingPrecreatedWorktree | null {
if (!isRecord(value)) return null;
const sessionId = readString(value.sessionId, MAX_SESSION_ID_LENGTH);
const deviceId = readString(value.deviceId, MAX_DEVICE_ID_LENGTH);
const path = readString(value.path, MAX_PATH_LENGTH);
const recoveryKey = readRecoveryKey(value.recoveryKey);
const createdAt =
typeof value.createdAt === 'number' && Number.isFinite(value.createdAt)
? value.createdAt
: 0;
if (!sessionId || !deviceId || (!path && !recoveryKey) || createdAt <= 0) return null;
if (createdAt > now + 5 * 60 * 1000) return null;
if (now - createdAt > MAX_RECORD_AGE_MS) return null;
const base = {
sessionId,
deviceId,
createdAt,
phase: readRecoveryPhase(value.phase),
};
if (path) {
return {
...base,
path,
...(recoveryKey ? { recoveryKey } : {}),
};
}
if (!recoveryKey) return null;
return {
...base,
recoveryKey,
};
}
function normalizeRecords(
value: unknown,
now = Date.now(),
): PendingPrecreatedWorktree[] {
const rawRecords =
isRecord(value) && Array.isArray(value.records)
? value.records
: Array.isArray(value)
? value
: [];
const bySession = new Map<string, PendingPrecreatedWorktree>();
for (const raw of rawRecords) {
const record = coerceRecord(raw, now);
if (!record) continue;
const existing = bySession.get(record.sessionId);
if (
!existing
|| record.createdAt > existing.createdAt
|| (
record.createdAt === existing.createdAt
&& recoveryPhaseRank(record.phase) >= recoveryPhaseRank(existing.phase)
)
) {
bySession.set(record.sessionId, record);
}
}
return [...bySession.values()]
.sort((left, right) => right.createdAt - left.createdAt)
.slice(0, MAX_RECORDS);
}
function recoveryPhaseRank(phase: PendingPrecreatedWorktreeBase['phase']): number {
if (phase === 'session-create-started') return 2;
if (phase === 'precreated') return 1;
return 0;
}
function parseStoredLedgerRecords(
value: unknown,
now: number,
): PendingPrecreatedWorktree[] | null {
if (
!isRecord(value)
|| value.version !== STORAGE_VERSION
|| !Array.isArray(value.records)
|| value.records.length > MAX_RECORDS
) return null;
const seenSessionIds = new Set<string>();
for (const raw of value.records) {
if (!isRecord(raw)) return null;
const sessionId = readString(raw.sessionId, MAX_SESSION_ID_LENGTH);
const deviceId = readString(raw.deviceId, MAX_DEVICE_ID_LENGTH);
const path = raw.path === undefined ? null : readString(raw.path, MAX_PATH_LENGTH);
const recoveryKey = raw.recoveryKey === undefined
? null
: readRecoveryKey(raw.recoveryKey);
const createdAt = typeof raw.createdAt === 'number' && Number.isFinite(raw.createdAt)
? raw.createdAt
: 0;
const phaseValid = raw.phase === undefined
|| raw.phase === 'reserved'
|| raw.phase === 'precreated'
|| raw.phase === 'session-create-started';
if (
!sessionId
|| !deviceId
|| (raw.path !== undefined && !path)
|| (raw.recoveryKey !== undefined && !recoveryKey)
|| (!path && !recoveryKey)
|| createdAt <= 0
|| createdAt > now + 5 * 60 * 1000
|| !phaseValid
) return null;
if (seenSessionIds.has(sessionId)) return null;
seenSessionIds.add(sessionId);
}
return normalizeRecords(value.records, now);
}
async function readRecordsUnserialized(
accountId: string,
now = Date.now(),
): Promise<{
records: PendingPrecreatedWorktree[];
storageReadable: boolean;
}> {
const key = storageKeyForAccount(accountId);
if (!key) return { records: [], storageReadable: false };
let raw: string | null;
try {
raw = await AsyncStorage.getItem(key);
} catch {
return {
records: normalizeRecords(volatileRecordsForAccount(accountId), now),
storageReadable: false,
};
}
let persisted: PendingPrecreatedWorktree[] = [];
if (raw) {
try {
const parsed = parseStoredLedgerRecords(JSON.parse(raw), now);
if (!parsed) {
return {
records: normalizeRecords(volatileRecordsForAccount(accountId), now),
storageReadable: false,
};
}
persisted = parsed;
} catch {
// 损坏的账本可能仍代表未完成的回收义务。不能删除后当空账本继续创建,
// 保留原值并让调用方按不可读状态 fail closed。
return {
records: normalizeRecords(volatileRecordsForAccount(accountId), now),
storageReadable: false,
};
}
}
return {
records: normalizeRecords(
[...volatileRecordsForAccount(accountId), ...persisted],
now,
),
storageReadable: true,
};
}
async function writeRecordsUnserialized(
accountId: string,
records: readonly PendingPrecreatedWorktree[],
): Promise<boolean> {
const key = storageKeyForAccount(accountId);
if (!key) return false;
try {
if (records.length === 0) {
await AsyncStorage.removeItem(key);
} else {
const payload: StoredRecoveryLedger = {
version: STORAGE_VERSION,
records: normalizeRecords(records),
};
await AsyncStorage.setItem(key, JSON.stringify(payload));
}
return true;
} catch {
return false;
}
}
export async function listPendingPrecreatedWorktrees(
accountId: string,
): Promise<PendingPrecreatedWorktree[]> {
const { records } = await readPendingPrecreatedWorktreeLedger(accountId);
return records;
}
async function readPendingPrecreatedWorktreeLedger(
accountId: string,
): Promise<{
records: PendingPrecreatedWorktree[];
storageReadable: boolean;
}> {
return enqueueMutation(async () => {
const {
records: normalized,
storageReadable,
} = await readRecordsUnserialized(accountId);
replaceVolatileRecords(accountId, normalized);
// 读侧顺手清理可解析的过期/无效条目,并把上次因写盘失败只留在内存的
// 记录重新持久化;读取或解析失败时绝不以“空账本”覆盖未知的磁盘真值。
if (storageReadable) {
await writeRecordsUnserialized(accountId, normalized);
}
return { records: normalized, storageReadable };
});
}
export async function registerPendingPrecreatedWorktree(
accountId: string,
record: PendingPrecreatedWorktree,
): Promise<boolean> {
const normalized = coerceRecord(record, Date.now());
if (!storageKeyForAccount(accountId) || !normalized) return false;
// 必须先于任何 await 写内存镜像:即使 AsyncStorage.setItem 与紧随其后的
// discard 同时失败,本进程仍能在重连 / 下次发送时找到这份 obligation。
replaceVolatileRecords(accountId, [
normalized,
...volatileRecordsForAccount(accountId).filter(
(item) => item.sessionId !== normalized.sessionId,
),
]);
markRegistrationInFlight(normalized.sessionId);
try {
return await enqueueMutation(async () => {
const {
records: current,
storageReadable,
} = await readRecordsUnserialized(accountId);
const next = [
normalized,
...current.filter((item) => item.sessionId !== normalized.sessionId),
].slice(0, MAX_RECORDS);
replaceVolatileRecords(accountId, next);
if (!storageReadable) return false;
return writeRecordsUnserialized(accountId, next);
});
} finally {
unmarkRegistrationInFlight(normalized.sessionId);
}
}
/**
* Keep the recovery bridge out of the handoff gap between persisting the ledger
* and registering the in-memory creation task. The caller owns the returned
* release function and must call it once the task is registered or abandoned.
*/
export function holdPrecreatedWorktreeRegistration(sessionId: string): () => void {
const normalized = sessionId.trim();
if (!normalized) return () => undefined;
markRegistrationInFlight(normalized);
let released = false;
return () => {
if (released) return;
released = true;
unmarkRegistrationInFlight(normalized);
};
}
export function isPrecreatedWorktreeRegistrationInFlight(
sessionId: string,
): boolean {
return registrationInFlight.has(sessionId);
}
export async function forgetPendingPrecreatedWorktree(
accountId: string,
target: Pick<PendingPrecreatedWorktree, 'sessionId'> & {
path?: string;
recoveryKey?: string;
createdAt?: number;
},
): Promise<void> {
await enqueueMutation(async () => {
const {
records: current,
storageReadable,
} = await readRecordsUnserialized(accountId);
const next = current.filter(
(item) => {
if (item.sessionId !== target.sessionId) return true;
const locatorMatches = target.recoveryKey !== undefined
? item.recoveryKey === target.recoveryKey
: target.path !== undefined && item.path === target.path;
if (!locatorMatches) return true;
return target.createdAt !== undefined && item.createdAt !== target.createdAt;
},
);
replaceVolatileRecords(accountId, next);
if (storageReadable && next.length !== current.length) {
await writeRecordsUnserialized(accountId, next);
}
});
}
/** Only a complete affirmative ACK proves that destructive cleanup finished. */
export function parseDiscardPrecreatedAck(value: unknown): {
discarded: true;
branchDeleted?: boolean;
} | null {
if (!isRecord(value) || value.discarded !== true) return null;
if (Object.keys(value).some(
(key) => key !== 'discarded' && key !== 'branchDeleted',
)) return null;
if (value.branchDeleted !== undefined && typeof value.branchDeleted !== 'boolean') {
return null;
}
return {
discarded: true,
...(typeof value.branchDeleted === 'boolean'
? { branchDeleted: value.branchDeleted }
: {}),
};
}
async function removeIfCurrent(
accountId: string,
record: PendingPrecreatedWorktree,
): Promise<void> {
await forgetPendingPrecreatedWorktree(accountId, record);
}
function isRecoveryCurrent(deps: PrecreatedWorktreeRecoveryDeps): boolean {
return deps.isCurrent?.() ?? true;
}
/**
* 冷启动 / 重连时主动处理没有当前内存 task 认领的记录。
*
* 处理策略是保守的:成功回收或确认 session 已认领才删账;网络失败、设备不可用、
* worktree 有改动/保留标记,以及老被控端缺少精确回收 channel 都留账,下一次
* 链路恢复或被控端升级后继续尝试。
*/
export async function recoverPendingPrecreatedWorktrees(
accountId: string,
deps: PrecreatedWorktreeRecoveryDeps,
): Promise<PrecreatedWorktreeRecoveryResult> {
const ledger = await readPendingPrecreatedWorktreeLedger(accountId);
const records = ledger.records;
const result: PrecreatedWorktreeRecoveryResult = {
attempted: 0,
recovered: 0,
deferred: 0,
retained: 0,
storageReadable: ledger.storageReadable,
};
for (const record of records) {
if (!isRecoveryCurrent(deps)) break;
if (deps.shouldDefer?.(record)) {
result.deferred += 1;
continue;
}
result.attempted += 1;
try {
await withTransientRemoteRetry(
async () => {
// Check immediately before every remote operation. The recovery bridge's
// openLink/invoke callbacks are stable and resolve the current client at
// call time, so an owner switch can otherwise retarget this old run.
if (!isRecoveryCurrent(deps)) return;
await deps.openLink(record.deviceId);
if (!isRecoveryCurrent(deps)) return;
if (await deps.isSessionClaimed(record.deviceId, record.sessionId)) {
return;
}
if (!isRecoveryCurrent(deps)) return;
const discard = deps.cancelPrecreated;
if (!discard) {
throw new Error('Pre-created worktree session ownership is unresolved');
}
const discardResult = typeof record.recoveryKey === 'string'
? await discard(record.deviceId, {
sessionId: record.sessionId,
recoveryKey: record.recoveryKey,
})
: typeof record.path === 'string'
? await discard(record.deviceId, {
sessionId: record.sessionId,
path: record.path,
})
: null;
if (!parseDiscardPrecreatedAck(discardResult)) {
throw new Error('Invalid pre-created worktree discard acknowledgement');
}
// Persist the draft's cancellation before forgetting its recovery ledger.
if (isRecoveryCurrent(deps)) await deps.onDiscarded?.(record);
},
{
maxAttempts: 2,
...(deps.sleep ? { sleep: deps.sleep } : {}),
},
);
if (!isRecoveryCurrent(deps)) break;
await removeIfCurrent(accountId, record);
result.recovered += 1;
continue;
} catch (error) {
// Do not let the old owner's catch path perform a second ownership probe or
// remove the old ledger after the auth owner has changed.
if (!isRecoveryCurrent(deps)) break;
// 旧工作端可能已经成功创建 session,但不认识新的 discard channel。无论
// discard 以何种错误返回都再对账一次,不能只在 PRECONDITION_FAILED 时查询。
try {
if (!isRecoveryCurrent(deps)) break;
if (await deps.isSessionClaimed(record.deviceId, record.sessionId)) {
if (!isRecoveryCurrent(deps)) break;
await removeIfCurrent(accountId, record);
result.recovered += 1;
continue;
}
} catch {
// 无法确认 ownership 时按原错误分类;未知状态仍保留账本。
}
if (isPreconditionFailedRemoteError(error)) {
result.retained += 1;
continue;
}
result.retained += 1;
}
}
return result;
}
export const __testing = {
storageKeyForAccount,
normalizeRecords,
coerceRecord,
drainMutations: () => mutationQueue,
resetVolatileLedgers: () => volatileLedgers.clear(),
};