Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/** Host-owned affairs, independent of Session lifecycle and project visibility. */
export interface TodoSource {
kind: 'conversation' | 'mail' | 'feishu' | 'github' | 'community' | 'task';
id: string;
label: string;
ref?: string;
project?: string;
version?: number;
observedAt?: string;
}
export interface TodoDeadline {
kind: 'date' | 'instant';
date: string;
timeZone: string;
at?: string;
sourceId?: string;
sourceVersion?: number;
quote?: string;
observedAt?: string;
}
export interface TodoNext {
label: string;
instruction: string;
kind: 'advance' | 'view' | 'decide';
}
export interface TodoCompletion {
summary: string;
ref?: string;
at: string;
}
export interface TeammateTodo {
id: string;
revision: number;
key: string;
origin: 'assigned' | 'discovered';
title: string;
progress: string;
outcome: string;
value: string;
next: TodoNext | null;
sources: TodoSource[];
associations: Array<{ kind: 'task' | 'pr'; id: string; label: string }>;
status: 'open' | 'done';
createdAt: string;
updatedAt: string;
sourceDeadline: TodoDeadline | null;
deadlineOverride?: { value: TodoDeadline | null };
deadlineCandidate: { value: TodoDeadline; reason: string } | null;
suggestedDate: string | null;
decision: { kind: 'deleted' | 'muted' | 'later'; until?: string } | null;
history: TodoCompletion[];
action: {
requestId: string;
revision: number;
state: 'received' | 'accepted' | 'failed' | 'unknown';
error?: string;
} | null;
legacyId?: string;
legacyFingerprint?: string;
legacyVerdict?: 'unfinished' | 'idea' | 'done';
}
export interface TodoPatch {
id?: string;
expectedRevision?: number;
key?: string;
origin?: TeammateTodo['origin'];
title?: string;
progress?: string;
outcome?: string;
value?: string;
next?: TodoNext | null;
sources?: TodoSource[];
associations?: TeammateTodo['associations'];
sourceDeadline?: TodoDeadline | null;
deadlineOverride?: { value: TodoDeadline | null };
deadlineCandidate?: TeammateTodo['deadlineCandidate'];
suggestedDate?: string | null;
operation?: 'complete' | 'reopen' | 'delete' | 'mute' | 'later' | 'restore' | 'confirm-deadline';
until?: string;
completion?: { summary: string; ref?: string };
resolvedActionRequestId?: string;
}
export interface TodoState {
version: 1;
items: TeammateTodo[];
cursors: Record<string, number>;
receipts: Record<string, string>;
}
export const emptyTodoState = (): TodoState => ({
version: 1,
items: [],
cursors: {},
receipts: {},
});
export class TodoError extends Error {
constructor(
public code: string,
message = code,
) {
super(message);
}
}
const text = (s: unknown, max: number, required = false): string => {
if (typeof s !== 'string' || (required && !s.trim()) || s.length > max)
throw new TodoError('INVALID_INPUT');
return s.trim();
};
export function validateTodoTimestamp(s: unknown): string {
if (
typeof s !== 'string' ||
s.length > 64 ||
!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(s) ||
!Number.isFinite(Date.parse(s))
)
throw new TodoError('INVALID_DATE');
return s;
}
const iso = validateTodoTimestamp;
export function validateTodoDeadline(d: TodoDeadline | null): void {
if (d === null) return;
if (
!d ||
!['date', 'instant'].includes(d.kind) ||
typeof d.date !== 'string' ||
d.date.length !== 10 ||
!/^\d{4}-\d{2}-\d{2}$/.test(d.date) ||
!Number.isFinite(Date.parse(d.date)) ||
new Date(d.date).toISOString().slice(0, 10) !== d.date
)
throw new TodoError('INVALID_DATE');
if (typeof d.timeZone !== 'string' || !d.timeZone.trim() || d.timeZone.length > 100)
throw new TodoError('INVALID_TIME_ZONE');
try {
new Intl.DateTimeFormat('en', { timeZone: d.timeZone }).format();
} catch {
throw new TodoError('INVALID_TIME_ZONE');
}
if (d.kind === 'instant') {
iso(d.at);
if (todoLocalDate(new Date(d.at!), d.timeZone) !== d.date) throw new TodoError('INVALID_DATE');
} else if (d.at !== undefined) throw new TodoError('INVALID_DATE');
if (
d.sourceVersion !== undefined &&
(!Number.isSafeInteger(d.sourceVersion) || d.sourceVersion < 0)
)
throw new TodoError('INVALID_INPUT');
if (d.observedAt !== undefined) iso(d.observedAt);
if (d.sourceId !== undefined) text(d.sourceId, 512, true);
if (d.quote !== undefined) text(d.quote, 2000);
}
export function todoLocalDate(now: Date, zone: string): string {
const parts = new Intl.DateTimeFormat('en', {
timeZone: zone,
year: 'numeric',
month: '2-digit',
day: '2-digit',
}).formatToParts(now);
return ['year', 'month', 'day'].map((k) => parts.find((p) => p.type === k)!.value).join('-');
}
export function effectiveTodoDeadline(t: TeammateTodo): TodoDeadline | null {
return t.deadlineOverride ? t.deadlineOverride.value : t.sourceDeadline;
}
/** One due occurrence of a todo: moving its deadline makes it a new one, so the "due" dot lights again. */
export function todoDueKey(t: TeammateTodo): string {
const deadline = effectiveTodoDeadline(t);
return `${t.id}@${deadline?.kind === 'instant' ? deadline.at : deadline?.date ?? ''}`;
}
/** Date-only items sort at the end of their source-local day, without inventing a stored time. */
export function createTodoDueComparator() {
const values = new Map<string, number>();
const value = (t: TeammateTodo) => {
const d = effectiveTodoDeadline(t);
if (!d) return Infinity;
if (d.kind === 'instant') return Date.parse(d.at!);
const key = d.date + '\0' + d.timeZone;
const cached = values.get(key);
if (cached !== undefined) return cached;
// Locate the next local calendar day, including DST transitions and midnight gaps.
const target = Number(d.date.replaceAll('-', ''));
const nominal = Date.parse(d.date + 'T00:00:00Z') + 86_400_000;
const format = new Intl.DateTimeFormat('en', {
timeZone: d.timeZone,
year: 'numeric',
month: '2-digit',
day: '2-digit',
});
let lo = nominal - 36 * 3_600_000,
hi = nominal + 36 * 3_600_000;
while (lo < hi) {
const mid = Math.floor((lo + hi) / 2),
parts = format.formatToParts(new Date(mid));
const date = Number(
['year', 'month', 'day'].map((k) => parts.find((p) => p.type === k)!.value).join(''),
);
if (date > target) hi = mid;
else lo = mid + 1;
}
values.set(key, lo - 1);
return lo - 1;
};
return (a: TeammateTodo, b: TeammateTodo) => {
const left = value(a),
right = value(b);
return left === right ? 0 : left - right;
};
}
export function todoOverdue(t: TeammateTodo, now = new Date()): boolean {
const d = effectiveTodoDeadline(t);
return (
!!d &&
(d.kind === 'instant'
? Date.parse(d.at!) < now.getTime()
: d.date < todoLocalDate(now, d.timeZone))
);
}
/** An open, visible item whose own deadline is today or already passed (the 近况 red dot). */
export function todoDue(t: TeammateTodo, now = new Date()): boolean {
if (t.status !== 'open' || !todoVisible(t, now)) return false;
const d = effectiveTodoDeadline(t);
if (!d) return false;
if (todoOverdue(t, now)) return true;
return d.kind === 'instant'
? todoLocalDate(new Date(d.at!), d.timeZone) === todoLocalDate(now, d.timeZone)
: d.date === todoLocalDate(now, d.timeZone);
}
/** Glance shows only open, visible affairs with a real deadline within seven days (including overdue).
* Suggestions and unconfirmed candidates never manufacture urgency. Clearing a deadline hides it.
*/
export function todoDueSoon(t: TeammateTodo, now = new Date()): boolean {
if (t.status !== 'open' || !todoVisible(t, now)) return false;
const deadline = effectiveTodoDeadline(t);
if (!deadline) return false;
if (deadline.kind === 'instant') return Date.parse(deadline.at!) <= now.getTime() + 7 * 86_400_000;
const horizon = new Date(todoLocalDate(now, deadline.timeZone) + 'T00:00:00Z');
horizon.setUTCDate(horizon.getUTCDate() + 7);
return deadline.date <= horizon.toISOString().slice(0, 10);
}
export function todoDateLabel(t: TeammateTodo, locale: string, now = new Date()): string {
const d = effectiveTodoDeadline(t);
const dateString = d?.date ?? t.deadlineCandidate?.value.date ?? t.suggestedDate;
if (!dateString) return '';
const date = new Intl.DateTimeFormat(locale, {
timeZone: 'UTC',
month: 'numeric',
day: 'numeric',
}).format(new Date(dateString + 'T12:00:00Z'));
// Hermes (Mobile) has no Intl.RelativeTimeFormat; there "today" falls back to the date itself.
const day =
d && d.date === todoLocalDate(now, d.timeZone) && typeof Intl.RelativeTimeFormat === 'function'
? new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(0, 'day')
: date;
return d?.kind === 'instant'
? day +
' ' +
new Intl.DateTimeFormat(locale, {
timeZone: d.timeZone,
hour: '2-digit',
minute: '2-digit',
}).format(new Date(d.at!))
: day;
}
export function todoVisible(t: TeammateTodo, now = new Date()): boolean {
return (
!t.decision ||
(t.decision.kind === 'later' &&
!!t.decision.until &&
Date.parse(t.decision.until) <= now.getTime())
);
}
/** Deterministic host preflight: repeat events and decisions never wake a model. */
export function preflightTodoEvents(
state: TodoState,
events: Array<{
source: string;
sequence: number;
key: string;
project?: string;
}>,
projects: string[],
) {
if (!Array.isArray(events) || events.length > 100) throw new TodoError('INVALID_EVENT');
for (const e of events)
if (
!e ||
!Number.isSafeInteger(e.sequence) ||
e.sequence < 0 ||
typeof e.key !== 'string' ||
!e.key ||
e.key.length > 512 ||
typeof e.source !== 'string' ||
!e.source ||
e.source.length > 512
)
throw new TodoError('INVALID_EVENT');
return events.map((e) => ({
...e,
decision:
e.project && !projects.includes(e.project)
? 'outside-scope'
: e.sequence <= (Object.hasOwn(state.cursors, e.source) ? state.cursors[e.source] : -1) ||
Object.hasOwn(state.receipts, e.source + ':' + e.sequence)
? 'duplicate'
: state.items.some((t) => t.key === normalizeTodoKey(e.key) && !todoVisible(t))
? 'suppressed'
: state.items.some((t) => t.key === normalizeTodoKey(e.key) && t.status === 'done')
? 'resolved'
: ('review' as const),
}));
}
export function normalizeTodoKey(key: unknown): string {
return text(key, 512, true);
}
export function applyTodoPatch(
state: TodoState,
patch: TodoPatch,
id: string,
now = new Date(),
): TeammateTodo {
if (!patch || typeof patch !== 'object' || Array.isArray(patch))
throw new TodoError('INVALID_INPUT');
const key = patch.key === undefined ? undefined : normalizeTodoKey(patch.key);
const old = patch.id
? state.items.find((t) => t.id === patch.id)
: state.items.find((t) => t.key === key);
if (patch.id && !old) throw new TodoError('NOT_FOUND');
if (old && key !== undefined && key !== old.key) throw new TodoError('KEY_MISMATCH');
if (old && patch.expectedRevision !== old.revision) throw new TodoError('CONFLICT');
if (!old && patch.expectedRevision !== undefined) throw new TodoError('CONFLICT');
if (!old && state.items.length >= 10000) throw new TodoError('CAPACITY_REACHED'); // reject, never evict history
const t: TeammateTodo = old
? structuredClone(old)
: {
id,
revision: 0,
key: normalizeTodoKey(patch.key),
origin: 'assigned',
title: '',
progress: '',
outcome: '',
value: '',
next: null,
sources: [],
associations: [],
status: 'open',
createdAt: now.toISOString(),
updatedAt: '',
sourceDeadline: null,
deadlineCandidate: null,
suggestedDate: null,
decision: null,
history: [],
action: null,
};
for (const field of ['title', 'progress', 'outcome', 'value'] as const)
if (patch[field] !== undefined)
t[field] = text(
patch[field],
field === 'title' ? 300 : 4000,
field === 'title' || field === 'outcome',
);
if (!t.title || !t.outcome) throw new TodoError('INVALID_INPUT');
if (patch.origin !== undefined) {
if (!['assigned', 'discovered'].includes(patch.origin)) throw new TodoError('INVALID_INPUT');
t.origin = patch.origin;
}
if (patch.next !== undefined) {
if (patch.next !== null) {
text(patch.next.label, 100, true);
text(patch.next.instruction, 4000, true);
if (!['advance', 'view', 'decide'].includes(patch.next.kind))
throw new TodoError('INVALID_INPUT');
}
if (JSON.stringify(t.next) !== JSON.stringify(patch.next)) t.action = null;
t.next = patch.next
? {
label: text(patch.next.label, 100, true),
instruction: text(patch.next.instruction, 4000, true),
kind: patch.next.kind,
}
: null;
}
if (patch.sources !== undefined) {
if (!Array.isArray(patch.sources) || patch.sources.length > 100)
throw new TodoError('INVALID_INPUT');
const merged = new Map(t.sources.map((s) => [s.kind + ':' + s.id, s]));
for (const s of patch.sources) {
if (!s || !['conversation', 'mail', 'feishu', 'github', 'community', 'task'].includes(s.kind))
throw new TodoError('INVALID_INPUT');
text(s.id, 512, true);
text(s.label, 300, true);
if (s.ref !== undefined) text(s.ref, 2000);
if (s.ref && !/^https:\/\/[^\s]+$/.test(s.ref)) throw new TodoError('INVALID_REFERENCE');
if (s.version !== undefined && (!Number.isSafeInteger(s.version) || s.version < 0))
throw new TodoError('INVALID_INPUT');
if (s.project !== undefined) text(s.project, 4096, true);
if (s.observedAt !== undefined) iso(s.observedAt);
const previous = merged.get(s.kind + ':' + s.id);
if (!previous || (s.version ?? 0) >= (previous.version ?? 0))
merged.set(s.kind + ':' + s.id, {
...previous,
kind: s.kind,
id: s.id,
label: s.label,
...(s.ref ? { ref: s.ref } : {}),
...(s.project ? { project: s.project } : {}),
...(s.version !== undefined ? { version: s.version } : {}),
...(s.observedAt ? { observedAt: s.observedAt } : {}),
});
}
t.sources = [...merged.values()];
}
if (patch.associations !== undefined) {
if (!Array.isArray(patch.associations) || patch.associations.length > 100)
throw new TodoError('INVALID_INPUT');
const merged = new Map(t.associations.map((a) => [a.kind + ':' + a.id, a]));
for (const a of patch.associations) {
if (!['task', 'pr'].includes(a.kind)) throw new TodoError('INVALID_INPUT');
text(a.id, 512, true);
text(a.label, 300, true);
merged.set(a.kind + ':' + a.id, {
kind: a.kind,
id: a.id,
label: a.label,
});
}
t.associations = [...merged.values()];
}
if (patch.sourceDeadline !== undefined) {
validateTodoDeadline(patch.sourceDeadline);
if (
t.sourceDeadline &&
patch.sourceDeadline &&
// Versions are ordered only within one source. Two missing IDs are the legacy stream.
t.sourceDeadline.sourceId === patch.sourceDeadline.sourceId &&
(patch.sourceDeadline.sourceVersion ?? 0) < (t.sourceDeadline.sourceVersion ?? 0)
)
throw new TodoError('STALE_SOURCE');
t.sourceDeadline = patch.sourceDeadline;
}
if (patch.deadlineOverride !== undefined) {
if (!patch.deadlineOverride || typeof patch.deadlineOverride !== 'object')
throw new TodoError('INVALID_INPUT');
validateTodoDeadline(patch.deadlineOverride.value);
t.deadlineOverride = { value: patch.deadlineOverride.value };
}
if (patch.deadlineCandidate !== undefined) {
if (patch.deadlineCandidate !== null) {
if (
!patch.deadlineCandidate ||
typeof patch.deadlineCandidate !== 'object' ||
Array.isArray(patch.deadlineCandidate)
)
throw new TodoError('INVALID_INPUT');
validateTodoDeadline(patch.deadlineCandidate.value);
text(patch.deadlineCandidate.reason, 2000, true);
}
t.deadlineCandidate = patch.deadlineCandidate;
}
if (patch.suggestedDate !== undefined) {
if (patch.suggestedDate !== null && typeof patch.suggestedDate !== 'string')
throw new TodoError('INVALID_DATE');
if (patch.suggestedDate)
validateTodoDeadline({
kind: 'date',
date: patch.suggestedDate,
timeZone: 'UTC',
});
t.suggestedDate = patch.suggestedDate;
}
if (patch.resolvedActionRequestId !== undefined) {
if (!old?.action || old.action.requestId !== patch.resolvedActionRequestId)
throw new TodoError('STALE_RECEIPT');
if (!patch.progress?.trim()) throw new TodoError('RECEIPT_EVIDENCE_REQUIRED');
t.action = null;
}
switch (patch.operation) {
case 'complete': {
if (!patch.completion) throw new TodoError('COMPLETION_EVIDENCE_REQUIRED');
text(patch.completion.summary, 4000, true);
if (patch.completion.ref !== undefined) text(patch.completion.ref, 2000);
t.history.push({ ...patch.completion, at: now.toISOString() });
t.status = 'done';
t.decision = null;
t.action = null;
break;
}
case 'reopen':
t.status = 'open';
t.decision = null;
t.action = null;
break;
case 'delete':
case 'mute':
t.decision = { kind: patch.operation === 'delete' ? 'deleted' : 'muted' };
break;
case 'later':
if (!patch.until || Date.parse(iso(patch.until)) <= now.getTime())
throw new TodoError('INVALID_DATE');
t.decision = { kind: 'later', until: patch.until };
break;
case 'restore':
t.decision = null;
break;
case 'confirm-deadline':
if (!t.deadlineCandidate) throw new TodoError('INVALID_DATE');
t.deadlineOverride = { value: t.deadlineCandidate.value };
t.deadlineCandidate = null;
break;
case undefined:
break;
default:
throw new TodoError('INVALID_INPUT');
}
t.revision++;
t.updatedAt = now.toISOString();
const at = state.items.findIndex((x) => x.id === t.id);
if (at < 0) state.items.push(t);
else state.items[at] = t;
return t;
}
/** Earliest visibility boundary; independent of pagination, with no reminder or execution side effect. */
export function nextTodoDeferralAt(items: TeammateTodo[], now = new Date()): string | null {
let next: string | null = null;
for (const t of items) {
const until = t.decision?.kind === 'later' ? t.decision.until : undefined;
if (
until &&
Date.parse(until) > now.getTime() &&
(!next || Date.parse(until) < Date.parse(next))
)
next = until;
}
return next;
}
/** One mounted-view refresh; long waits are chunked locally without reading or running work. */
export function scheduleTodoDeferralRefresh(until: string, refresh: () => void): () => void {
const at = Date.parse(until);
if (!Number.isFinite(at)) return () => {};
let timer: ReturnType<typeof setTimeout>;
const arm = () => {
const remaining = at - Date.now();
timer =
remaining > 2_147_483_647
? setTimeout(arm, 2_147_483_647)
: setTimeout(refresh, Math.max(0, remaining));
};
arm();
return () => clearTimeout(timer);
}
export interface TodoListQuery {
query?: string;
view?: 'open' | 'done' | 'hidden';
origin?: 'all' | 'assigned' | 'discovered';
order?: 'due' | 'created';
offset?: number;
limit?: number;
}
export function queryTodoItems(items: TeammateTodo[], q: TodoListQuery = {}, now = new Date()) {
if (
!q ||
typeof q !== 'object' ||
Array.isArray(q) ||
(q.query !== undefined && typeof q.query !== 'string') ||
(q.view !== undefined && !['open', 'done', 'hidden'].includes(q.view)) ||
(q.origin !== undefined && !['all', 'assigned', 'discovered'].includes(q.origin)) ||
(q.order !== undefined && !['due', 'created'].includes(q.order))
)
throw new TodoError('INVALID_INPUT');
const search = (q.query ?? '').trim().toLocaleLowerCase();
if (search.length > 300) throw new TodoError('INVALID_INPUT');
const compareDue = createTodoDueComparator();
const filtered = items
.filter(
(t) =>
(q.view === 'done'
? t.status === 'done' && todoVisible(t, now)
: q.view === 'hidden'
? !todoVisible(t, now)
: t.status === 'open' && todoVisible(t, now)) &&
(!q.origin || q.origin === 'all' || t.origin === q.origin) &&
(!search ||
[t.title, t.progress, ...t.sources.map((s) => s.label)]
.join(' ')
.toLocaleLowerCase()
.includes(search)),
)
.sort(
(a, b) =>
(q.order !== 'created' ? compareDue(a, b) : 0) ||
a.createdAt.localeCompare(b.createdAt) ||
a.id.localeCompare(b.id),
);
const requestedOffset = Number.isSafeInteger(q.offset) && q.offset! >= 0 ? q.offset! : 0;
const limit = Math.min(25, Math.max(1, Number.isSafeInteger(q.limit) ? q.limit! : 25));
const offset = Math.min(
requestedOffset,
Math.max(0, Math.ceil(filtered.length / limit) - 1) * limit,
);
return {
items: filtered.slice(offset, offset + limit),
total: filtered.length,
offset,
limit,
nextDeferredAt: nextTodoDeferralAt(items, now),
completedTotal: items.filter((t) => t.status === 'done' && todoVisible(t, now)).length,
};
}
/** Public transcript copy; the model-only delivery carries the stable affair id separately. */
export function todoActionText(title: string, step: string, locale = 'en'): string {
const prefix = locale.startsWith('zh-TW')
? '繼續'
: locale.startsWith('zh')
? '继续'
: locale.startsWith('ja')
? '続ける'
: locale.startsWith('ko')
? '계속'
: 'Continue';
return `${prefix} “${title}”: ${step}`;
}