Xây dựng Durable Agent thử nghiệm
Xây dựng host Pi 1.0.0 Durable với ranh giới chính xác cho recovery, replay, ownership, Document và quan sát.
Thử nghiệm.
@earendil-works/pi-durablelà package thử nghiệm mới của Pi1.0.0. API có thể đổi mà không báo trước giữa các release. Hãy ghim version và diễn tập recovery với storage trước khi nâng cấp.
Pi Durable là nền tảng điều phối agent dựa trên storage. Conversation, checkpoint của Task và Document của ứng dụng cùng đi qua một dòng Commit. Hướng dẫn này dựng một host offline nhỏ, sau đó chỉ ra những phần host production phải tự cung cấp: model, execution environment, idempotency của hệ thống bên ngoài và policy cho client.
Trạng thái và ranh giới sản phẩm
Durable không thay thế Coding Agent. Coding Agent vẫn là sản phẩm terminal dành cho một người làm việc trên máy local hoặc remote. Durable là harness thử nghiệm riêng cho ứng dụng cần Conversation chạy dài, phục hồi sau restart hoặc nhiều client cùng điều hướng một công việc. Nó chia sẻ Pi AI và một số nguyên tắc thiết kế với Coding Agent, nhưng không phải Agent Core API ổn định hay bản thay thế trực tiếp cho SessionManager. Hãy chọn nó khi ứng dụng thực sự sở hữu scheduler và storage bền vững.
Release này làm cho work đã được nhận có thể recover; nó không bảo đảm exactly-once cho external side effect. Một lần trừ tiền, deploy, gửi email hay ghi từ xa có thể đã hoàn tất trước khi process ghi được outcome. Phase của Task có thể chạy ít nhất một lần rồi chạy lại; external effect có thể xảy ra không lần nào, một lần hoặc nhiều lần, tùy thời điểm lỗi. Hãy xử lý trạng thái chưa chắc chắn bằng idempotency key hoặc reconciliation API của chính service đó. Từ “durable” không tạo transaction chung giữa model provider, Tool environment và storage.
Harness, Conversation, run và Task
Harness mở một Session trên một storage backend, tuần tự hóa Commit và schedule Task. Conversation là handle không giữ state, được nhận diện bằng id. Các Entry bất biến tạo thành transcript: input của user, response của assistant, Tool result, thay đổi system, reset, compaction hoặc kind của ứng dụng. Commit công bố nguyên tử Entry, thay đổi Document, Task mới và thay đổi Submission. Observer chỉ thấy Commit hoàn chỉnh, không thấy các edit trung gian.
Một run bắt đầu từ input đã được nhận và kéo dài qua các model turn cho đến final answer hoặc lỗi. Một turn gồm model response và Tool round của response đó. pi.generation là Task có checkpoint; nó sở hữu pi.tool Task và chờ result. Custom Task dùng cùng cơ chế checkpoint và ownership. Conversation chỉ busy khi pi.live.run tồn tại; Task khác có thể khiến ownership scope chưa idle mà không làm Conversation busy. Mọi Task đều có owner là Conversation hoặc Task khác; Conversation có thể ownerless.
Mọi lời gọi bất đồng bộ nhận Chord Context. BACKGROUND_CONTEXT tiện cho ví dụ có kiểm soát nhưng không bao giờ cancel. Cancel một waiter chỉ dừng việc chờ, còn Task đã nhận vẫn tiếp tục. Khi muốn dừng durable work, hãy dùng abort của Submission, Conversation hoặc Task. Handle gắn với một lần invocation của Task hay Tool không được giữ lại sau khi invocation kết thúc.
Quyền sở hữu storage và môi trường chạy
MemoryStorage deterministic nhưng mất khi process dừng. openNodeSqliteStorage(file) lưu một database file; WAL với synchronous = NORMAL chịu được process crash nhưng Commit mới nhất có thể mất sau sự cố điện hoặc host. openNodeJsonlStorage(directory, context, options) lưu file append-only; fsync: true tăng độ bền của commit marker và giảm throughput. Đây là ranh giới của từng backend, không phải bảo đảm cho external side effect. Mỗi thời điểm chỉ một process được sở hữu một storage; Durable không cung cấp cross-process locking. Nhiều client phải được route tới process sở hữu storage đó.
Core SQLite và JSONL portable có thể chạy trong JavaScript runtime khác khi host cấp database hay filesystem adapter tương ứng. Quyền truy cập file và shell của Tool tách biệt với storage: HarnessOptions.env tạo ExecutionEnv cho từng Tool call, prompt section hoặc runtime request từ Conversation ID, cwd và committed read. Không có environment thì CodingTools built-in trả error result. Vì vậy Tool có thể chạy trong container remote trong khi Harness và storage ở máy khác. Host cần giữ environment ID ổn định nếu cùng path phải chỉ cùng file.
Ví dụ executable đầu tiên đồng bộ với contract fixture Pi 1.0.0. Nó mở Harness offline, đặt compaction policy ở settings của host, quan sát root rồi đóng lại. Không có provider request nào được giả lập hoặc gửi đi.
import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
import { createModels } from "@earendil-works/pi-ai/models";
import {
createRegistry,
defineDoc,
defineEntry,
defineExtension,
Harness,
MemoryStorage,
watchEvents,
type Conversation,
} from "@earendil-works/pi-durable";
export async function verifyPi1000DurableContracts(): Promise<number> {
const context = BACKGROUND_CONTEXT;
const harness = await Harness.open(
new MemoryStorage(),
{
models: createModels(),
registry: createRegistry(),
settings: {
compaction: {
enabled: true,
reserveTokens: 16_384,
keepRecentTokens: 20_000,
backgroundTokens: 32_768,
},
},
},
context,
);
try {
const root: Conversation = await harness.root(context);
const view = await root.viewState(context);
try {
void view.value;
} finally {
view.dispose();
}
return root.id;
} finally {
await harness.close(context);
}
}Harness.open() chuyển Task còn running thành pending work có thể recover. root() tạo Conversation ID 1 dành riêng ở lần đầu, hoặc trả lại root cũ khi mở lại. close() chặn admission mới, join invocation đang hoạt động rồi đóng storage; unfinished durable work vẫn ở đó cho lần mở sau. Hãy luôn close trong finally.
Submission và khử trùng lặp bằng requestId
Khi host đã cung cấp provider và model thật, root.submit({ type: "input", content, requestId }, context) nhận input và trả về Submission. Với Conversation idle và inbox rỗng, admission Commit cùng lúc đặt pi.user Entry, tạo generation Task và live run. Input đến lúc busy đi vào pi.inbox để được đặt ở boundary sau. Submission type: "write" chỉ append Entry, không gọi model. Submission.wait() trả done hoặc unanswered; status() quan sát mà không chờ, còn harness.submission(id, context) tìm lại Submission sau restart.
Dùng requestId ổn định khi caller có thể retry sau timeout hoặc restart. Cùng ID trong cùng Conversation sẽ trả về Submission cũ thay vì nhận request thứ hai. Hãy lưu ID trong record của caller. Đổi ID sẽ tạo work mới; key này không deduplicate giữa các Conversation hoặc ở external provider. Ngay cả claim exactly-once về admission cũng chỉ nói đến local storage record, không nói đến remote effect bất kỳ.
Khi busy, followUp chờ câu trả lời hiện tại rồi khởi động run tiếp; steer tham gia run đang chạy sau Tool round hiện tại; reject throw ConversationBusy và không ghi gì. Host settings quyết định đặt một hay tất cả steer/follow-up đang queue ở mỗi boundary. Nếu run lỗi, item trong queue còn nguyên cho tới lần submit sau và được đặt theo thứ tự cũ nhất. Submission.abort() rút được queued input hoặc write, còn Conversation.abort() chỉ rút queued input. Không thao tác nào thu hồi Entry đã đặt.
Khôi phục checkpoint và model call bị gián đoạn
Mỗi phase của Task commit checkpoint tiếp theo hoặc terminal outcome. Khi mở lại persistent storage, Task running bị gián đoạn được điều hòa về pending; resume() bắt đầu scheduling. Submission hoặc progress wait mới cũng khởi động scheduler. Model request không nằm trong storage transaction: nếu bị gián đoạn, generation Task có thể gửi lại request từ checkpoint cuối. Partial output đã commit vẫn hiện với aborted marker; cửa sổ partial chưa commit có thể mất. Đây là recovery từ checkpoint, không phải phát lại toàn transcript từ đầu.
Hãy lưu Submission.id và xem settlement của chính Submission đó sau restart. harness.inspect(context) phân biệt ready work với blocked work; thiếu code của Task, definition quá cũ hoặc migration lỗi có thể giữ Task ở trạng thái blocked. Cài đúng definition trước khi resume, hoặc chọn policy migration/abort tường minh. Close process cũng là gián đoạn của invocation đang chạy; nó không biến toàn bộ pending Task thành thành công.
Provider timeout và retry policy cần cùng kỷ luật. Một model attempt có thể có provider-level retry, còn durable generation attempt có checkpoint riêng. Host log nên ghi request ID, số attempt và phase cuối đã commit. Hủy Context của waiter không cancel model hay durable run; hãy gọi abort của đúng scope nếu đó là ý định của người dùng.
Ranh giới an toàn khi replay Tool
Mỗi Tool call là một Task; intent của nó được commit trước execute(). Chỉ Tool khai báo replay: "safe" mới có thể chạy lại lúc recovery. Mặc định là unsafe: call unsafe bị gián đoạn tạo interrupted error result cùng output đã commit, và Tool unsafe không tự động replay. Chỉ đánh dấu safe khi toàn bộ execution có thể lặp lại hoặc external system dùng idempotency protocol ổn định. Ngay cả Tool “chỉ đọc” vẫn có thể unsafe nếu read làm tiến cursor hoặc acknowledge một message.
Giả sử đã trừ tiền thẻ rồi crash trước receipt Commit. Checkpoint local không thể biết charge đã xảy ra chưa. Hãy dùng provider idempotency key xuất phát từ Task identity ổn định và reconcile receipt trước khi settle; nếu không, trả trạng thái chưa chắc chắn cho model hoặc operator. Tool output, details và diagnostics có thể stream vào pi.live, nhưng terminal pi.tool-result Entry và Tool usage được commit sau đó. Error bị throw thành result model có thể thấy. control.terminate và control.handoff đổi run flow, không đổi độ an toàn replay.
beforeTool có thể block hoặc sửa arguments trước intent; afterTool có thể thay result. prepareArguments của Tool phải pure vì có thể được chạy lại trước lúc intent được ghi. External effect trong bất kỳ phase nào cũng cần chính sách idempotency riêng. Đừng đánh dấu payment hay deploy là safe chỉ vì function có catch.
Conversation đồng thời và fork
Một Harness schedule nhiều Conversation đồng thời: thread đang idle có thể tiến triển khi Conversation khác đang chờ Tool hoặc model. Busy boundary chỉ tuần tự hóa input trong một Conversation, không khóa cả Harness. Điều này phù hợp với channel và thread, các reviewer chạy song song hoặc nhiều Conversation của worker được một process phục vụ. Ứng dụng phải kiểm tra quyền truy cập trước khi nhận input từ nhiều người.
fork(entryId, { ownership }, context) tạo branch ở một Entry cụ thể mà parent nhìn thấy. fork child thấy Entry của parent đến fork point, rồi phát triển độc lập. Nó không copy transcript parent thành một log mutable thứ hai. Scan Entry có nhận biết fork sẽ đi qua branch ancestry. Child bắt đầu với agent của parent tại Entry đó; thay đổi sau này của parent không âm thầm tác động lên fork. createConversation() mới thì không có transcript ancestry; child do Task sở hữu bắt đầu với agent của Conversation owner.
Ownership và ancestry là hai cạnh khác nhau. Thread ownerless tham gia idle check toàn Harness và cần lifecycle riêng. Child do Task sở hữu thuộc scope abort và idle của Task đó. Khi replay một subagent Tool, hãy query ownership index để tìm child cũ trước khi tạo child mới, sau đó submit bằng request ID ổn định. Cách này tránh nhân đôi child khi Tool resume.
Cấu hình Agent theo Conversation
Mỗi Conversation lưu lựa chọn Agent trong Document pi.agent: model, thinking level, extension được chọn, Tool filter, instructions bổ sung và working directory. Conversation.configure(change, context) commit thay đổi; agent(context) resolve các tên đã lưu với Registry và host default hiện tại. Array extension chọn đúng những extension đó theo thứ tự; { add, remove } chỉnh default. Array Tool chọn đúng những Tool đó; { remove } loại bớt. null xóa field đã lưu để quay về host default. Không có “Agent hiện tại” duy nhất của process mà mọi Conversation bắt buộc dùng.
Model, Tools được cung cấp và prompt của một request được cố định lúc request chuẩn bị. Thay đổi cấu hình tác động từ request kế tiếp. Tool call và hook resolve Agent ở phase riêng; thay đổi cwd hoặc extension có thể ảnh hưởng tới call model đã phát ra nhưng chưa bắt đầu execute. Hãy tính điều này khi đổi safety policy giữa run. Host-wide settings được đọc tại mỗi lần dùng và không lưu vào storage; sau restart host phải cung cấp policy tương thích.
Execution environment theo cwd đã resolve của Conversation. Reviewer có thể dùng model rẻ hơn và Tool chỉ đọc trong checkout riêng, trong khi agent chính giữ lựa chọn của nó. Document chỉ nên lưu tên public và JSON choice; credential và provider object thuộc cấu hình host, không nên copy vào fork.
Extension, section, Tool và wrap
Một extension có tên gom section, Tool, hook, wrap và Task. Ứng dụng cài nó vào Registry rồi chọn theo Conversation. Mặc định tất cả extension đã cài được chọn theo thứ tự install. Conversation lưu tên extension và Tool, không lưu executable code. Tên thiếu sau restart sẽ tạm thời không đóng góp behavior cho tới khi host cài lại; deployment của extension là một phần của recovery.
Prompt section được render trước mỗi request từ Agent đã resolve, environment và committed Document. Durable ghi thay đổi system theo vị trí trong transcript để fork hoặc restart thấy đúng thứ model đã thấy; tránh section biến động liên tục như timestamp vì làm mất hiệu quả provider prompt cache. instructions của Conversation render sau cùng. defineTool() validate arguments bằng TypeBox schema. CodingTools built-in gồm read, write, edit, bash qua environment đã cấp và có thể được bỏ hoặc override theo Conversation.
Tool trùng tên trong extension được chọn sẽ do extension sau thắng. wrapTool() trang trí Tool thắng cuộc, còn wrapSection() làm tương tự với prompt section. Wrapper phải giữ đúng replay classification của Tool được bọc và báo lỗi rõ ràng. Registry có thể đổi khi đang chạy, nhưng Tool invocation đã bắt đầu vẫn dùng implementation ban đầu.
Hook và quyết định memo bền vững
Hook chạy trong phase xác định của Task, không phải global event bus. Generation có beforeRequest, afterResponse, onYield và afterTools; Tool execution có beforeTool và afterTool; Compaction có beforeCompact. Hook của extension được chọn chạy theo chain theo thứ tự của Conversation. Block đầu tiên của beforeTool thắng, continuation đầu tiên của onYield thắng, còn observer hook chạy hết chain. beforeTool throw sẽ block call; lỗi ở hook khác được report rồi chain tiếp tục.
Hook có thể chạy lại sau crash. api.memo(name, candidate, context) lưu quyết định JSON nhỏ cùng Task đang hỏi; lần ghi đầu thắng. Hãy đọc memo trước khi hỏi approval lần nữa. Memo làm quyết định local bền vững, nhưng không thể thu hồi thông báo bên ngoài đã gửi trước memo Commit. Nếu approval đến từ Slack hay service khác, hãy dùng request identity của service đó và reconcile duplicate.
Hook API cung cấp committed Document read, nên policy có thể dựa vào state của ứng dụng tại phase. Registry mới ảnh hưởng Task phase tiếp theo, không thay hook đã execute. Hãy hạn chế side effect trong hook quan sát, đồng thời ghi phase và Task ID chính xác khi debug quyết định policy.
Task tùy chỉnh, chính sách chờ và cây ownership
defineTask() khai báo tên, version, initial checkpoint, phase handler và abort handler. Hãy register custom Task trước recovery. Mỗi phase nên commit checkpoint tiếp hoặc terminal result; timer và sleep không thay thế persisted checkpoint. Task có thể tạo child Task hoặc Conversation trong Commit của nó. Cây ownership, không phải mảng Promise tách rời, quyết định work nào phải join và abort đi tới đâu.
Checkpoint waiting liệt kê Task ID trong on và chọn allSettled hoặc failFast. Waiter chỉ resume sau khi mọi Task được liệt kê đều terminal. on có thể nêu Task đã terminal hoặc Task waiter không sở hữu, nhưng Task không thuộc sở hữu bắt buộc dùng allSettled. failFast chỉ hợp lệ khi mọi Task trong danh sách là child do waiter sở hữu; failure đầu tiên abort các sibling. Task có outcome đã quyết định vẫn có thể ở completing cho tới khi ordinary owned work drain. Owner fail hoặc abort sẽ abort descendant trong phạm vi trước.
Task graph hiển thị live node cùng owner edge và status để debug. Danh sách node không phải lịch sử vĩnh viễn: Task terminal rời graph. harness.inspect() cho biết riêng pending Task có bị chặn vì thiếu code không. Dùng waitForTask() khi cần terminal receipt, và truyền Context có thể cancel nếu UI có thể detach mà không abort Task.
Phạm vi abort foreground và background
Work foreground do Task sở hữu giữ owner chưa terminal cho tới lúc join. Ordinary idle traversal và abort đi qua foreground descendant. Task background thì khác: background: true chỉ hợp lệ với Task do Conversation sở hữu và tạo boundary cho idle cùng abort của toàn bộ subtree nó sở hữu. Task vẫn thuộc Conversation đó; “background” không biến nó thành ownerless.
Conversation abort thông thường dừng foreground work trong phạm vi và rút queued input, nhưng Conversation abort thông thường không hủy descendant background. abort(context, { background: true }) vượt background boundary đã tồn tại lúc abort được nhận. Nó không hứa bắt background work mới được tạo sau đó. Abort chạy từ dưới lên: descendant trong phạm vi settle trước khi abort handler của owner Task bắt đầu, nhờ vậy handler chỉ cần dọn effect của chính nó.
Dùng foreground child khi Tool phải trả answer của child và failure phải dừng child. Reporter hay subagent lâu dài có thể ở sau background anchor Task do Conversation sở hữu; lúc đó host cần stop command riêng. waitForIdle() dùng ordinary scope và có thể resolve dù background work còn chạy. Khi shutdown hoàn toàn, hãy stop background work rõ ràng và await receipt trước khi close Harness.
Compaction background và thủ công, retry khi overflow
Compaction đổi active context của model, không đổi transcript đã lưu: compaction giữ lại Entry cũ. Head marker pi.compaction chứa summary và Entry đầu tiên giữ nguyên văn. settings.compaction của host điều khiển automatic behavior: reserveTokens đặt blocking threshold dưới context capacity, keepRecentTokens ước lượng recent tail giữ nguyên, còn backgroundTokens bắt đầu summarization sớm hơn threshold. Đặt backgroundTokens bằng zero chỉ tắt background compaction. compact() thủ công vẫn dùng được khi automatic compaction bị tắt.
Background compaction chạy trong khi Conversation vẫn làm việc. Summary được đặt ngay khi idle hoặc tại turn boundary kế tiếp khi busy. compact(instructions, context) trả Task ID; terminal result có thể trỏ tới write Submission, và settlement của Submission cho biết placement thành công hay stale. Summary đến muộn với cut point cũ không thể thay active head mới. Usage của summarization tính vào pi.usage, còn pi.live.compactions cho thấy attempt và retry backoff.
Nếu request tiếp theo vượt threshold mà background summary chưa sẵn sàng, generation chạy blocking compaction. Provider context-overflow response có thể kích hoạt một lần compaction và một lần retry, chỉ khi automatic compaction đang bật, có cut hợp lệ và path đó chưa bị dùng hết bởi overflow hay blocking compaction trước đó. Trường hợp còn lại ghi error mà không retry. Retry này gửi lại model request; nó không cho phép chạy lại Tool effect đã hoàn tất.
Reset, handoff và lịch sử được giữ lại
reset(handoff, context) nhận một Entry pi.reset. Model chỉ nhìn active context từ marker đó trở đi; Entry cũ vẫn nằm trong storage và có thể xem qua history API. Chuỗi handoff thành user message trong context mới. Tool có thể yêu cầu cùng flow bằng control.handoff. Reset được queue khi busy sẽ đặt ở boundary; nếu đặt trong Tool round, nó kết thúc run hiện tại.
Reset không phải thao tác xóa, privacy purge hay fork. Nó chỉ đổi message đóng góp vào model request tương lai. Compaction marker cũng đổi context và giữ source Entry, nhưng mang summary và cut point thay vì optional handoff của user. Retention policy và access control thuộc về storage cùng ứng dụng. Đừng hứa reset xóa nội dung cũ khỏi backup hay snapshot client đã nhận.
Sau restart, reset marker vẫn là phần của committed transcript. Client tham gia muộn nên xây display từ committed Entry và head marker thay vì giả định list trong bộ nhớ UI là context hiện tại model thấy.
Document nguyên tử và chính sách fork
Document và Entry được commit nguyên tử. Document có type có thể giữ application state bên cạnh transcript, để audit Entry, thay đổi state và Task mới cùng mô tả một business transition. defineDoc() hoặc defineDocFamily() khai báo kind, version, scope, history, fork behavior và initializer. Chỉ cập nhật qua tx.doc() trong Commit; đọc qua snapshot hoặc attached state. Chọn history: "rewindable" khi cần giá trị quá khứ; latest tránh lưu các giá trị Document cũ.
Với Conversation Document, fork: "initial" cho child state mới, fork: "current" copy giá trị hiện tại của parent, còn fork: "asOf" copy giá trị tại fork point. Cách cuối cần rewindable history. Hãy chọn có chủ đích: draft riêng tư có thể cần child mới tinh, còn task list gắn transcript có thể cần asOf. Entry ancestry của fork và policy copy Document là hai quy tắc khác nhau. Snippet dưới đây dùng import phía trên và đồng bộ với offline fixture. Nó fork sau một Commit Document cùng Entry nguyên tử, rồi sửa parent khi ba observer đang theo dõi. Ví dụ kiểm tra child asOf với parent sau sửa đổi, quan sát Entry mới, thay extension đã cài và giải phóng mọi observer.
const NoteEntry = defineEntry<{ text: string }>("app.note");
const Notes = defineDoc<{ items: string[] }>({
kind: "app.notes",
version: 1,
scope: "conversation",
history: "rewindable",
fork: "asOf",
initial: () => ({ items: [] }),
});
function signal<T>() {
let resolve!: (value: T) => void;
const promise = new Promise<T>((done) => {
resolve = done;
});
return { promise, resolve };
}
async function within<T>(promise: Promise<T>, label: string): Promise<T> {
let timeout: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
promise,
new Promise<never>((_, reject) => {
timeout = setTimeout(
() => reject(new Error(`Timed out: ${label}`)),
5000,
);
}),
]);
} finally {
if (timeout !== undefined) clearTimeout(timeout);
}
}
export async function verifyPi1000DurableStateContracts() {
const context = BACKGROUND_CONTEXT;
const registry = createRegistry();
registry.install(
defineExtension({
name: "notes",
sections: [{ key: "notes_initial", render: () => "Initial notes" }],
}),
);
const firstRegistry = registry.snapshot();
const harness = await Harness.open(
new MemoryStorage(),
{ models: createModels(), registry },
context,
);
try {
const root = await harness.root(context);
const marker = await root.commit(async (tx) => {
(await tx.doc(Notes, root.id)).items.push("write docs");
return tx.appendEntry(NoteEntry, root.id, { data: { text: "saved" } });
}, context);
const fork = await root.fork(
marker.id,
{ ownership: { kind: "ownerless" } },
context,
);
const view = await root.viewState(context);
try {
const watch = await root.watch(context);
try {
const events = await watchEvents(harness, root.id, context);
try {
const viewBefore = view.value.entries.length;
const watchBefore = watch.value.entries.length;
const viewUpdate = signal<number>();
const watchUpdate = signal<number>();
const appended = signal<{ id: number; text: string }>();
const unsubscribe = view.subscribe((value, _context, delivery) => {
if (
delivery.kind === "update" &&
value.entries.length > viewBefore
) {
viewUpdate.resolve(value.entries.length);
}
});
try {
watch.start(async (value) => {
if (value.entries.length > watchBefore) {
watchUpdate.resolve(value.entries.length);
}
});
events.start(async (batch) => {
for (const event of batch) {
if (
event.type === "entry_appended" &&
event.entry.kind === "app.note" &&
event.entry.data !== undefined &&
event.entry.data !== null &&
typeof event.entry.data === "object" &&
!Array.isArray(event.entry.data) &&
typeof event.entry.data.text === "string"
) {
appended.resolve({
id: event.entry.id,
text: event.entry.data.text,
});
}
}
});
const later = await root.commit(async (tx) => {
(await tx.doc(Notes, root.id)).items.push("later update");
return tx.appendEntry(NoteEntry, root.id, {
data: { text: "later update" },
});
}, context);
const [viewUpdateEntries, watchUpdateEntries, appendedEntry] =
await within(
Promise.all([
viewUpdate.promise,
watchUpdate.promise,
appended.promise,
]),
"Durable live view, watch, and event updates",
);
registry.install(
defineExtension({
name: "notes",
sections: [
{ key: "notes_revised", render: () => "Revised notes" },
],
}),
);
const agent = await root.agent(context);
return {
rootId: root.id,
rootItems: (await harness.snapshot(Notes, root.id, context))
?.items,
forkItems: (await harness.snapshot(Notes, fork.id, context))
?.items,
viewBefore,
watchBefore,
viewUpdateEntries,
watchUpdateEntries,
laterEntryId: later.id,
appendedEventId: appendedEntry.id,
appendedEventText: appendedEntry.text,
initialSection:
firstRegistry.extension("notes")?.sections?.[0]?.key,
replacedSection: registry.snapshot().extension("notes")
?.sections?.[0]?.key,
priorSnapshotSection:
firstRegistry.extension("notes")?.sections?.[0]?.key,
resolvedSection: agent.sections.find((section) =>
section.key.startsWith("notes_"),
)?.key,
};
} finally {
unsubscribe();
}
} finally {
await events.stop();
}
} finally {
await watch.stop();
}
} finally {
view.dispose();
}
} finally {
await harness.close(context);
}
}Fixture không gọi model hay provider. Ở host thật, conversationCreated và init có thể tạo application Document ngay trong creation Commit, kể cả raw child creation trong Tool transaction. Exception sẽ rollback cả Commit; observer không bao giờ nhìn thấy Task thiếu state tương ứng.
Thay Registry và khả năng thay đổi
Registry chứa executable code, còn Conversation persist tên của nó. Install extension với tên đã có sẽ thay thế tại chỗ và publish Registry snapshot mới; uninstall xóa tên đã cài. Đây là malleability ở Task-phase boundary, không phải thay code của invocation đang execute. Tool đang chạy hoàn tất với implementation nó đã lấy. Request, Task phase hoặc Tool call sau mới resolve code mới. Nếu extension biến mất khi restart, custom Task chưa xong của nó có thể blocked cho tới khi được cài lại.
Tên Tool trùng nhau giữa các extension được chọn được resolve theo thứ tự, Tool sau thắng và wrap trang trí Tool thắng đó. Tên extension thiếu trong pi.agent không đóng góp gì cho tới khi cài lại. Vì thế deployment đổi tên Tool có thể thay capability được cung cấp cho Conversation cũ. Hãy review tên đã lưu và Task version khi rollout; dùng inspect() để hiển thị blocked work thay vì âm thầm báo agent khỏe mạnh.
Registry replacement chỉ ở process hiện tại. Nó không migrate storage record, không sửa Entry đã commit và không phát code sang process khác. Quy tắc một owner cho storage vẫn áp dụng khi nhiều client quan sát hoặc steer cùng Conversation.
viewState, watch và watchEvents cho nhiều người xem
viewState() trả attached read-only Chord state có cấu trúc; đọc value, subscribe update rồi gọi dispose() khi xong. watch() cho current view cùng callback tuần tự chứa Chord operation chính xác của mỗi Commit về sau; gọi stop() để giải phóng. watchEvents() là adapter thử nghiệm suy ra batch event kiểu Coding Agent từ committed change và bắt đầu bằng snapshot. Nó hữu ích cho UI quen thuộc nhưng không phải event-history log có thể replay.
Nhiều viewer có thể attach cùng Conversation, kể cả client đến giữa run. Mỗi client bắt đầu từ snapshot hiện tại rồi nhận thay đổi. Structural watch chậm giữ tối đa 100 pending frame trước khi thay bằng newest full view; event stream chậm cũng thay batch đang đợi bằng snapshot sau 100. Consumer phải chấp nhận reset về state chuẩn, không giả định mọi delta trung gian đều tới. Partial model và Tool output được commit tối đa mỗi 100 ms, nên cửa sổ partial mới nhất có thể biến mất khi crash.
View công khai active Entry, tiến trình generation và Tool trong pi.live, pi.inbox, pi.agent và pi.usage. Nó không tự cấp quyền steer. Host phải xác thực client và authorize submission, sau đó chuyển committed view qua transport. Hãy dispose hoặc stop mọi attachment khi browser tab hay socket rời đi.
Failure mode và nguồn ghim chính xác
Hãy diễn tập failure trước khi nhận production traffic. Crash sau admission, giữa model request, giữa Tool safe và unsafe; mở lại backend cũ và quan sát Submission ban đầu. Retry requestId ổn định, rồi cố ý đổi nó để thấy admission mới vẫn có thể xảy ra. Cancel waiter và xác nhận Task tiếp tục. Abort foreground child, ordinary Conversation scope và explicit background scope riêng rẽ. Ép thiếu custom Task definition và inspect blocked state. Fork tại Entry sau Document edit rồi so sánh policy initial, current và asOf. Ép background, blocking, manual cùng overflow compaction và xác minh source Entry vẫn được lưu.
Log Conversation ID, Task ID, kind, phase, attempt, outcome và quyết định retry. Redact prompt content, Tool arguments, credential và Document field nhạy cảm. Durable transcript là dữ liệu ứng dụng có thể nằm lâu trong backend file và backup. Theo dõi provider usage riêng với pi.usage đã commit khi xảy ra outage; attempt lỗi hoặc abort vẫn có thể phát sinh chi phí. Hãy khớp kỳ vọng process crash và power loss với backend, và đừng mở cùng storage từ các process cạnh tranh.
Hướng dẫn được review ngày 2026-10-06 theo Pi 1.0.0, tag v1.0.0, commit chính xác a13d35a742c6ef8462812a28fbe1d8c8b7431c32. Durable README, CHANGELOG, package export map, root exports, Harness implementation và public Harness types quyết định signature và edge behavior. Bài viết ra mắt giải thích động cơ và ví dụ; exact tag quyết định contract trong hướng dẫn.