Context inspector

Không phải phase của v1. Follow-up này bắt đầu sau khi đã có trang web admin, vì giao diện chính của nó là một bảng checkbox trên trang đó. Nó cần mọi phase v1 mà nó dựa vào đã xong: chain của phase 7, compaction và estimator của phase 10, memory và skills của phase 11, và usage records của phase 13.

Tổng quan

Cho thấy chính xác hango gửi gì đến model cho một session, từng phần một, và cho phép người dùng bỏ bớt các phần. Một request model được ghép từ nhiều nguồn: system prompt của agent, các block mà mỗi middleware đóng góp (planning, filesystem, subagent, memory, chỉ mục skills), bản tóm tắt compaction, mọi message trong lịch sử và mọi định nghĩa tool. Sau phase 11 không ai thấy được việc ghép này nếu không đọc Langfuse, và không ai thay đổi được nó nếu không sửa code. Follow-up này thêm bốn thứ lên trên chain của phase 7: một endpoint inspect trả về request model kế tiếp của một session dưới dạng danh sách các phần có gắn nhãn kèm ước lượng token, các override được lưu để loại bỏ hoặc thay thế các phần ở những lần gọi model sau, một endpoint try gửi một lần gọi model với các phần loại bỏ tạm thời và trả về câu trả lời mà không đụng đến session, và một bảng trên trang web admin hiển thị các phần, mỗi phần có một checkbox.

Ý tưởng đến từ bảng “Optimize context” của AICoworker và được ghi là A4 trong plans/reports/research-261014-1634-aicoworker-goclaw-hango-comparison.md. AICoworker là một gateway: nó bắt các request trên đường đến provider và nhóm chúng theo API key và cuộc hội thoại. hango là harness, nên nó không cần bắt gì cả. Nó tự xây request, nên chain chỉ cần nhớ mỗi phần đến từ đâu.

Yêu cầu

Chức năng

• Mỗi phần của một request model đã ghép có một part id ổn định, giữ nguyên qua các turn và các run:
  • system:<contributor> cho các block mà một contributor thêm vào, ví dụ system:agent, system:todo, system:filesystem, system:skills, và system:memory:/memories/AGENTS.md cho một nguồn memory.
  • tool:<name> cho một định nghĩa tool.
  • message:<seq> cho một message đã lưu, và summary cho bản tóm tắt compaction của phase 10.
• GET /v1/sessions/{id}/context trả về những gì lần gọi model kế tiếp của session sẽ gửi. Nó tạo một run state mới giống như một run mới, chạy BeforeRun, ghép system block, tool và message qua chain thật, và dừng ở một capture handler thay vì provider. Không có gì được ghi và không model nào được gọi. Response nhóm các phần thành system, tools và messages. Mỗi phần có id, kind, label, một bản xem trước 200 ký tự, một ước lượng token, included (false khi một override loại bỏ nó), và override (exclude, replace hoặc không có). ?full=<part id> trả về toàn bộ nội dung của một phần. Tổng được cho cả trước và sau override.
• Ước lượng token cho từng phần dùng Estimator của phase 10. Tổng của request dùng TokenCounter của provider khi provider có, và dùng ước lượng trong trường hợp còn lại; response cho biết đã dùng cách nào.
• Khi lần gọi kế tiếp sẽ kích hoạt summarization, response inspect báo điều đó bằng would_compact: true và hiển thị các message như hiện tại. Một request inspect không bao giờ gọi summarizer.
• PUT /v1/agents/{id}/context-overrides thay thế các override của agent cho các phần system:* và tool:*. Chúng áp dụng cho mọi session của agent. PUT /v1/sessions/{id}/context-overrides thay thế các override của session cho các phần message:* và summary. Mỗi override là {part, action, replacement} với action là exclude hoặc replace. GET trên cả hai path trả về tập hiện tại. Một danh sách rỗng sẽ xóa nó.
• replace được phép cho các phần system và message, và bị từ chối với 422 cho các phần tool, vì một schema tool đã đổi sẽ không còn khớp với việc kiểm tra argument của tool.
• Override được nạp một lần mỗi run trong BeforeRun, nên một thay đổi áp dụng từ run kế tiếp. Một run không bao giờ thấy context của nó đổi giữa các turn.
• Một tập override phải để lại một request hợp lệ. Loại bỏ một message chứa tool_use cũng loại bỏ message chứa tool_result của nó, và ngược lại. Response của PUT liệt kê mọi phần được thêm vào theo cách này. Một tập sẽ không còn message user nào, hoặc sẽ làm lịch sử bắt đầu bằng một message assistant, bị từ chối với 422 kèm lý do. Việc kiểm tra dùng lại validator sau compaction của phase 10.
• Một override cho một phần không còn tồn tại (một file memory đã xóa, một tool đã bỏ khỏi agent) vẫn được giữ và endpoint inspect báo là stale: true. Nó không làm gì cho đến khi phần đó quay lại.
• POST /v1/sessions/{id}/context/try nhận {exclude: [...], replace: {...}, message: "đoạn text user thêm, không bắt buộc"}, áp dụng các override đã lưu cộng với các override trong body, gửi một lần gọi model và trả về message assistant, stop reason và usage. Các tool call trong câu trả lời được trả về, không được thực thi. Không có gì được thêm vào session và không run nào được tạo. Lần gọi có timeout (HANGO_CONTEXT_TRY_TIMEOUT, mặc định 120s).
• hango context show --session <id> in response inspect thành một bảng theo nhóm: một cột checkbox, part id, label, bản xem trước và token, kèm tổng của từng nhóm. hango context exclude --session <id> <part>..., hango context include ... và hango context try --session <id> [--exclude <part>...] [--message <text>] bọc các endpoint còn lại. Giống hango eval, lệnh này là một HTTP client của API công khai của hango và đọc HANGO_API_URL và HANGO_API_KEY.
• Trang web admin có một bảng “Context” cho một session. Nó hiển thị ba nhóm, system, tools và messages, với một checkbox, label, bản xem trước và số token cho mỗi phần, tổng của từng nhóm, và tổng trước và sau override. Bấm vào một phần sẽ mở toàn bộ nội dung của nó, và một phần system hoặc message có thể được sửa, việc này lưu một override replace. Bỏ chọn hoặc chọn các phần rồi bấm Save sẽ gửi PUT cho agent hoặc session. Nút “Try” gửi lựa chọn hiện tại đến endpoint try và hiển thị câu trả lời cạnh bảng. Các phần được thêm vào vì là cặp đi kèm, các override stale, cached_prefix và would_compact được hiển thị dưới dạng nhãn. Bảng chỉ dùng HTTP API ở trên, giống mọi màn hình khác của trang web admin.

Phân quyền

Các dòng này theo GET /v1/sessions/{id}/messages và PATCH /v1/agents/{id} từ phase 4: ai được đọc message của một session thì được xem context của nó, và ai được thay đổi một agent thì được thay đổi override của nó. Một đối tượng ở tenant khác hoặc của member khác trả về 404.

Phi chức năng

• Override không bao giờ thay đổi lịch sử đã lưu. Giống compaction ở phase 10, chúng chỉ tác động lên request gửi đi.
• Endpoint inspect và try trả nội dung message và memory cho người gọi API, đúng nội dung mà GET /v1/sessions/{id}/messages đã trả về. Chúng không bao giờ đưa nội dung lên span hoặc log. Nội dung trên telemetry vẫn do tenants.trace_llm_content kiểm soát như trước.
• Loại bỏ hoặc thay thế một phần system làm đổi phần đầu của prompt, nên lần gọi kế tiếp sẽ trượt prompt cache. Response inspect đánh dấu các phần nằm trước cache breakpoint bằng cached_prefix: true để người dùng thấy được cái giá phải trả.
• Một lần gọi try là một lần gọi model thật. Nó được ghi vào usage_records với purpose context_try và không có run, và tính vào quota của tenant và rate limit của API key như mọi lần gọi khác. Migration của follow-up này mở rộng điều kiện check của purpose với context_try và cho phép usage_records.run_id nhận null.
• Một request inspect tốn một lần ghép chain và không có lần gọi model nào. Độ trễ của nó bị giới hạn bởi BeforeRun, mà phase 11 đã đặt giới hạn.
• Không thêm Go package mới. Middleware override và part id nằm trong internal/agent, handler trong internal/server, store trong internal/store/pg, và CLI trong cmd/hango. Bảng nằm trong cây mã nguồn của trang web admin.

Kiến trúc

// internal/agent/parts.go
type PartID string // "system:memory:/memories/AGENTS.md", "tool:read_file", "message:42", "summary"

type Part struct {
	ID     PartID
	Kind   string // "system", "tool", "message", "summary"
	Label  string
	Tokens int
}

// SourcedBlock giữ nguồn gốc cạnh block. provider.Block không đổi,
// nên không có gì riêng của hango bị serialize sang provider.
type SourcedBlock struct {
	Part  PartID
	Block provider.Block
}

// internal/agent/chain.go — SystemBlocks giữ vai trò cũ nhưng trả về nguồn gốc.
func (c *Chain) SystemBlocks(def store.Agent, s *State) []SourcedBlock

// internal/agent/mwoverrides.go
type Override struct {
	Part        PartID
	Action      string // "exclude" hoặc "replace"
	Replacement string
}

type ContextOverridesMiddleware struct {
	Store store.ContextOverrides
} // RunHook (nạp override của agent và session một lần) + ModelWrapper (message và summary)

// internal/agent/inspect.go
type Snapshot struct {
	System, Tools, Messages []Part
	WouldCompact            bool
	TotalBefore, TotalAfter int
	Counted                 string // "provider" hoặc "estimate"
}

// Inspect ghép request kế tiếp của một session qua chain thật và một
// capture handler. Nó không bao giờ gọi provider hoặc summarizer.
func Inspect(ctx context.Context, deps Deps, sessionID uuid.UUID, extra []Override) (*Snapshot, *provider.Request, error)

Mỗi override được áp dụng ở đâu:

1. Các phần system bị bỏ hoặc thay thế bên trong Chain.SystemBlocks, trước khi PromptCacheMiddleware chọn chỉ số breakpoint, nên breakpoint rơi vào một block thực sự được gửi.
2. Các phần tool bị bỏ ở slot ToolAllowlist, slot cuối cùng trong stack, nên không middleware nào sau đó thêm lại được một tool đã bị loại bỏ.
3. Các phần message và summary bị bỏ hoặc thay thế bởi ContextOverridesMiddleware, một slot mới ngay trước Summarization, nên compaction và ngân sách token thấy lịch sử đã được lọc.

-- migrations/NNNNN_context_overrides.sql (số migration còn trống kế tiếp)
create table context_overrides (
  id uuid primary key,
  tenant_id uuid not null references tenants(id) on delete cascade,
  agent_id uuid references agents(id) on delete cascade,
  session_id uuid references sessions(id) on delete cascade,
  part text not null,
  action text not null check (action in ('exclude','replace')),
  replacement text,
  created_by uuid not null references users(id),
  created_at timestamptz not null default now(),
  check (num_nonnulls(agent_id, session_id) = 1),
  check ((action = 'replace') = (replacement is not null)),
  check (agent_id is null or part like 'system:%' or part like 'tool:%'),
  check (session_id is null or part like 'message:%' or part = 'summary')
);
-- cùng migration này mở rộng usage_records cho các lần gọi try
alter table usage_records alter column run_id drop not null;
-- và thay điều kiện check của purpose để cho phép thêm 'context_try'
create unique index context_overrides_agent_part_idx on context_overrides (tenant_id, agent_id, part) where agent_id is not null;
create unique index context_overrides_session_part_idx on context_overrides (tenant_id, session_id, part) where session_id is not null;

Một PUT xóa các dòng của đối tượng và chèn tập mới trong một transaction. Các query nằm trong internal/store/pg/queries/context_overrides.sql và đi qua sqlc giống mọi bảng khác kể từ phase 2.1.

Instrumentation

• Span agent.context_inspect cho một request inspect, với hango.context.parts.system, hango.context.parts.tools, hango.context.parts.messages, hango.context.tokens.before, hango.context.tokens.after, hango.context.would_compact.
• Attribute trên mọi span chat: hango.context.overrides (số override đang hoạt động) và hango.context.excluded_tokens. Khi đó một run có context bị sửa tay sẽ hiện ra trong Tempo và Langfuse, giúp trả lời “vì sao agent quên X” trước khi ai đó nghi ngờ model.
• Span event agent.context_override_stale cho mỗi override mà phần của nó không còn tồn tại, và agent.context_override_paired khi một phần đi cặp tool_use/tool_result bị loại bỏ cùng cặp của nó.
• Một lần gọi try là một span chat bình thường với hango.context.try = true nằm dưới một span SERVER context_try, nên nó xuất hiện trong Langfuse cạnh các generation bình thường nhưng có thể lọc ra.
• Metric: histogram hango.context.inspect.duration, counter hango.context.try (attribute outcome), gauge hango.context.overrides.active theo tenant.
• Audit action, thêm vào tập đóng từ phase 2: context.override cho cả hai route PUT (loại đối tượng agent hoặc session, detail chứa các part id và action, không bao giờ chứa text thay thế) và context.try (detail chứa các part id bị loại bỏ và model).

Các file liên quan

Tạo mới

• migrations/NNNNN_context_overrides.sql, dùng số migration còn trống kế tiếp khi follow-up này bắt đầu.
• internal/store/pg/queries/context_overrides.sql, internal/store/pg/context_overrides.go, và các case cô lập trong internal/store/pg/tenancy_test.go.
• internal/agent/parts.go, internal/agent/parts_test.go — part id, label, bản xem trước.
• internal/agent/mwoverrides.go, internal/agent/mwoverrides_test.go.
• internal/agent/inspect.go, internal/agent/inspect_test.go.
• internal/server/handlers_context.go, internal/server/handlers_context_test.go.
• cmd/hango/context.go, cmd/hango/context_test.go.
• docs/learning/context-inspector.md.
• Component bảng Context và API client của nó trong trang web admin.

Sửa đổi

• internal/store/store.go — sub-store ContextOverrides trên Scoped.
• internal/agent/chain.go — SystemBlocks trả về []SourcedBlock, áp dụng override system, và base handler bỏ thông tin nguồn gốc trước khi xây provider.Request.System.
• internal/agent/mwstack.go, internal/agent/mwstack_test.go — slot ContextOverrides trước Summarization; test thứ tự kiểm tra điều này.
• internal/agent/mwallowlist.go — bỏ các tool bị loại bỏ.
• internal/agent/mwcache.go — chọn chỉ số breakpoint sau khi đã áp dụng override system.
• internal/agent/mwsummarize.go — trong một lần gọi chỉ để capture, báo would_compact mà không gọi summarizer.
• Mọi PromptContributor (mwtodo.go, mwfilesystem.go, mwsubagent.go, mwmemory.go, mwskills.go) — gắn part id của nó cho các block của nó.
• internal/server/authz.go, internal/server/authz_test.go — năm dòng route ở trên.
• internal/store/audit.go — context.override và context.try trong tập action.
• internal/config/config.go — HANGO_CONTEXT_TRY_TIMEOUT.
• internal/usage và store của nó — purpose context_try và các record không có run.
• internal/telemetry/attrs.go, internal/telemetry/metrics_names.go — các tên ở trên.
• docs/system-architecture.md, docs/learning/README.md, docs/roadmap.md.

Các bước triển khai

1. Viết migration (bảng cộng với thay đổi usage_records), file query và scoped store với List(target) và Replace(target, []Override) trong một transaction. Thêm các case cô lập giữa các tenant và trong cùng tenant cho context_overrides vào bảng cô lập.
2. Viết parts.go: hàm tạo và phân tích part id, label cho từng loại (tên tool, #seq role, path memory), và một bản xem trước cắt ở 200 ký tự đúng ranh giới rune.
3. Đổi Chain.SystemBlocks để trả về []SourcedBlock và gắn nhãn các block của mọi contributor hiện có. Cho base handler bỏ thông tin nguồn gốc. Mọi test chain và test thứ tự hiện có phải qua mà không đổi gì ngoài kiểu dữ liệu.
4. Viết mwoverrides.go: BeforeRun nạp override của agent và session vào state riêng có kiểu. WrapModelCall bỏ và thay các phần message và summary, rồi chạy validator cặp của phase 10 trên kết quả. Nếu kiểm tra thất bại ở đây nghĩa là tập đã lưu bị hỏng sau khi lưu (một message mới hơn làm đổi việc ghép cặp); khi đó middleware gửi request không kèm các override message, ghi log mức error và ghi một span event. Nó không bao giờ gửi một request không hợp lệ.
5. Áp dụng override system trong SystemBlocks trước khi chọn cache breakpoint, và override tool trong slot allowlist. Thêm slot ContextOverrides vào DefaultStack và vào test thứ tự.
6. Viết inspect.go: xây chain cho agent của session, chạy BeforeRun trên một state mới tạo từ các message đã lưu, gọi ModelCall với một capture handler, và biến request bắt được thành một Snapshot. Đánh dấu lần gọi summarizer là chỉ capture để nó báo would_compact thay vì gọi model.
7. Viết handlers_context.go: các route inspect, overrides và try với các dòng phân quyền và audit action của chúng. PUT overrides kiểm tra tập dựa trên lịch sử hiện tại, thêm các phần đi cặp, và trả về tập đã lưu cộng các phần được thêm. Route try chạy Inspect với các override thêm, gửi request bắt được qua provider với timeout, và trả về câu trả lời.
8. Viết cmd/hango/context.go với show, exclude, include và try.
9. Xây bảng Context trong trang web admin trên cùng các route.
10. Thêm instrumentation và bước runbook, rồi viết test và tài liệu học.

Dàn ý tài liệu học

docs/learning/context-inspector.md phải có:

• Khái niệm: một request model được ghép lại, không phải được viết ra. Mỗi phần đến từ đâu, mỗi phần tốn bao nhiêu, và vì sao “model thực sự đã thấy gì?” là câu hỏi debug đầu tiên cho một câu trả lời tệ.
• Các lựa chọn thiết kế: gắn nguồn gốc lên block thay vì phân tích prompt sau đó; xem trước bằng cách ghép thử qua chain thật thay vì một đường ghép thứ hai có thể lệch đi; override nạp một lần mỗi run; override cấp agent cho system và tool, cấp session cho message; từ chối replace cho tool.
• Vì sao override phải giữ request hợp lệ: việc ghép cặp tool_use/tool_result, một lịch sử bắt đầu bằng message user, và provider làm gì khi một trong hai quy tắc bị phá.
• Cái giá của việc sửa phần đầu prompt: prompt cache, và vì sao response đánh dấu cached_prefix.
• Đánh đổi: xem trước lần gọi kế tiếp so với lưu bản sao của mọi lần gọi đã qua (dung lượng, quyền riêng tư của message gia đình, Langfuse đã giữ quá khứ khi bật trace nội dung); override đã lưu so với các lần thử một lần; bảng trên trang web admin so với bảng trong CLI.
• So sánh với AICoworker: một gateway bắt từng request, nhóm theo API key và cuộc hội thoại, áp dụng các phần system và tool bị bỏ chọn cho mọi cuộc hội thoại của key và các message bị bỏ chọn cho một cuộc hội thoại, và cho phép người dùng xem và sửa từng phần. hango giữ cách nhóm tương tự với agent thay cho API key, và thêm việc kiểm tra cặp và dấu cache.
• So sánh với goclaw: GET /v1/agents/{id}/system-prompt-preview trong internal/http/agents_prompt_preview.go render system prompt cho một prompt mode với các section có tên, một số đếm token và danh sách tool. Nó chỉ đọc và chỉ bao gồm system prompt.
• So sánh với deepagents: thư viện không có inspector; LangSmith hiển thị input của từng lần gọi model sau khi đã xảy ra.
• Cách debug lớp này: một phần không có trong response inspect nghĩa là contributor của nó chưa gắn nhãn (kiểm tra part id của contributor); một run hành xử khác với bản xem trước nghĩa là override đã đổi sau khi run bắt đầu (override nạp ở BeforeRun); một lần trượt cache bất ngờ sau một override hiện ra dưới dạng sụt giảm hango.cache.read_ratio cùng với hango.context.overrides trên span chat; một override stale hiện ra dưới dạng agent.context_override_stale.
• Bài tập: loại bỏ chỉ mục skills và hỏi agent về một skill; loại bỏ một tool result cũ và xem phần đi cặp bị loại theo; dùng try để so sánh một câu trả lời có và không có memory.
• Ngân sách thời gian: 9h cho API, store và CLI + 4h cho bảng trên trang web admin + 2h tài liệu học.

Tiêu chí thành công

• go build ./... && go vet ./... && go test -race ./... đều qua khi Docker đang chạy, và golangci-lint run báo 0 lỗi.
• Response inspect của một session liệt kê mọi system contributor, mọi tool và mọi message của request kế tiếp, và tổng ước lượng của các phần bằng Estimator.EstimateRequest trên request bắt được (test).
• Một request inspect không gọi provider lẫn summarizer, và không ghi dòng nào (test với một provider giả báo lỗi ở bất kỳ lần gọi nào).
• Khi message:5 bị loại bỏ trên một session, lần gọi model kế tiếp của một run mới trong session đó không chứa message 5, và GET /v1/sessions/{id}/messages vẫn trả về nó (integration test).
• Loại bỏ message có tool_use cũng loại bỏ message có tool_result của nó, và response PUT liệt kê phần được thêm (test).
• Một tập override không còn message user nào bị từ chối với 422 (test).
• replace trên một phần tool:* bị từ chối với 422 (test).
• Một tool bị loại bỏ không có trong danh sách tool của request ngay cả khi allowed_tools của một skill có nêu tên nó (test).
• Chỉ số cache breakpoint rơi vào một block được gửi khi một phần system đứng trước nó bị loại bỏ (test).
• Một lần gọi try trả về câu trả lời, không thêm message nào và không tạo run nào, và span chat của nó mang hango.context.try = true (test).
• Mọi dòng route trong bảng phân quyền đều được bao phủ, gồm cả trường hợp một member đọc context session của member khác (404) và một member thay đổi override agent của member khác (404).
• Các case cô lập giữa các tenant và trong cùng tenant cho context_overrides đều qua.
• Cả hai route PUT ghi một dòng audit context.override và route try ghi context.try; không có text thay thế nào xuất hiện trong detail (test).
• hango context show --session <id> in bảng theo nhóm khi chạy với một server thật.
• Một lần gọi try ghi một dòng usage_records với purpose context_try và không có run, và bị từ chối với 402 khi quota của tenant đã hết (test).
• Trên trang web admin, bỏ chọn một message rồi lưu sẽ loại nó khỏi run kế tiếp, và tổng trên bảng thay đổi khớp với response inspect.
• Trong Tempo, một run có override đang hoạt động hiển thị hango.context.overrides trên các span chat của nó.

Đánh giá rủi ro

Rollback

goose down một bước sẽ xóa context_overrides và khôi phục các ràng buộc của usage_records (sau khi xóa các dòng context_try). Bỏ slot ContextOverrides khỏi DefaultStack và bỏ bộ lọc tool khỏi slot allowlist sẽ khôi phục hành vi trước follow-up này. Thông tin nguồn gốc trên các system block có thể giữ lại, vì nó không bao giờ được gửi đi. Ẩn bảng trên trang web admin sẽ gỡ phần giao diện.