makelore/.project-docs/30-worklog/tasks/20260924-teacher-context-budget-3a9e6c81.md

Task: Fix teacher context budget rejection

Identity

• Task ID: 20260924-teacher-context-budget-3a9e6c81
• Mode: Feature
• Branch: codex/20260924-teacher-context-budget-3a9e6c81-teacher-context-budget
• Worktree: D:\Datas\OthersProjects.codex-worktrees\makelore\20260924-teacher-context-budget-3a9e6c81
• Base commit: eb3dc85a2f
• Owner: codex
• Status: Ready for Integration

Scope

• Diagnose and fix teacher context-budget rejection for a short question, preserving published configuration, student billing, cloud/legacy execution and current read-only tool boundaries. Own client context budgeting, runner integration, focused regressions, README and this record.

Intent And Constraints

• Official check/start/status passed in the isolated feature worktree above. Read entry, own record, relevant teacher decisions/architecture/domain/evidence/reflection/commitments and 108 peer records. Completed teacher/packaging scopes overlap historically; historical placeholder records remain unknown/read-only with no concrete dependency. Planning Gate Passed; canonical memory, other tasks, main and user project files stay read-only.
• Apply diagnosing-bugs: establish a red runner test, inspect only relevant local topic metadata, reproduce the actual legacy configuration, then correct the budgeting seam and test real preparation/compilation/submission. No subagents, paid model calls, deployment, installation or automatic topic migration.
• Confirmed local metadata: current 方法老师 topic has no runtime=yuxi, no requests or discussion, input budget 8000, output 1500, system prompt 2751 UTF-8 bytes. No user conversation text or secret was printed or copied. The screenshot is a legacy local-topic preflight failure, not proof of a cloud model limit.

Outcome

• Fixed native token budgeting: text, reasoning, tool schemas and calls share an explicit approximate 2 UTF-8 bytes/token estimate; tool-result limits convert back to bytes under the existing 2400-byte cap. Published token ceilings, model limits, student billing and final provider authority remain intact; no configuration or topic migration.

• Context compaction now measures the selected runner's complete envelope. Cloud compilation uses exact JSON query bytes instead of a fixed 256-byte escaping reserve, so ordinary code quotes/newlines cannot pass compilation then fail submission. Excerpts preserve head/tail and source IDs without mutating original read-tool material.

• Fixed configuration/current-discussion overflow is distinguished from oversized questions/references. Teacher behavior, current question, explicit references and discussion instructions remain complete. Updated README explains the approximate native versus exact transport boundary.

• No Renderer workflow changed. Before: a short first question could be rejected with advice to shorten it or start a topic. After: the same 8000-budget legacy shape and cloud long-code case submit successfully; truly oversized fixed inputs identify configuration as the cause.

• Follow-up source audit: teacher availability/default, catalog and published versions are fetched from Works Square (/api/coding-teacher/config, /teachers, /versions/{version}). Main stores each topic's definition/version; the Renderer restores that snapshot for existing topics. Teacher prompts also include client teaching behavior and discussion instructions, so behavioral content is not wholly cloud-owned.

• Friend is not an independently distributed server/Yuxi agent: consultationDefinition(..., 'friend') inherits the published teacher definition's model, limits, runtime and version while replacing its name/persona/welcome/questions and clearing text Skills locally. Friend cloud calls retain the same teacher version and expose no project read tools. Runtime=yuxi uses the Yuxi teacher transport; legacy snapshots use Main's student-model gateway runner. No product behavior or live configuration changed during this audit.

• Reproduced two reachable failures before changing product code: legacy model preparation plus empty-source first discussion needs 9013 byte-based estimated units but allows only 4456 after tool reserves (synthetic 2700-byte prompt matching observed shape); cloud compilation accepts long ordinary quoted code then JSON serialization exceeds its byte budget.

Verification

• Green: 9 focused teacher/context/read/model/structured-discussion/Renderer files, 289 tests passed. Includes actual CodingTeacherService + native runner + real temporary project-file read/continuation at the existing 8000 budget with a 2700-byte prompt and long source; actual service + cloud transport compaction; escaped-code cloud envelope and unchanged protocol; negative fixed-config overflow; six read rounds, cancellation, request identity and scope remain covered.

• pnpm 10.33.4 frozen offline install, standard pnpm run typecheck and scoped ESLint passed. Production Vite build passed for Renderer/Main/Preload/utility. Expanded Main tsc reports 66 diagnostics; a CompilerHost replay substituting exact base versions of all changed Electron files also reports the same 66, with zero new diagnostics. No full-suite or real-model success is claimed.

• Existing Electron UI fixtures replace the Host API and bypass this budget seam; this Main-only change is covered at real service/runner boundaries instead of treating a mocked UI pass as reproduction evidence. No installed application, live Yuxi instance or user topic was modified.

• Follow-up verification: resumed official ownership, checked all 108 peer registry timestamps against the prior scope audit (unchanged), and traced config-client, consultation-role, service creation/send, Renderer restore, cloud-runner and context assembly. This was a source-only clarification; no new runtime tests or paid calls were needed. Previous fix remains unmerged/unpackaged.

• Red loops: pnpm exec vitest run tests/unit/coding-teacher-model.test.ts -t 'existing 8000 budget' --maxWorkers=1; pnpm exec vitest run tests/unit/coding-teacher-cloud.test.ts -t 'long code context' --maxWorkers=1. Both fail with the exact screenshot message at their respective real preflight seam. Empty-source cloud question with the discussion protocol passes.

• Native model limits are tokens; existing implementation equates them to UTF-8 bytes, unlike model tokenization. DeepSeek documentation distinguishes character estimates and actual usage (https://api-docs.deepseek.com/zh-cn/quick_start/token_usage/). Keep native token estimates explicitly approximate and model/usage authoritative; retain the separate exact cloud query byte guard.

Follow-ups

• Merge, rebuilt installer and installed-app verification remain pending. The observed 方法老师 topic is still a legacy definition; selecting/publishing a Yuxi teacher is a separate Operations action and existing topic versions remain fixed.

Promotion Candidates

• Target: teacher architecture/domain/current-state at Integration Gate. Proposal: record distinct approximate native token and exact cloud JSON-byte budgeting, with source excerpt fitting and configuration-specific errors. Evidence: red/green runner cases, 289 tests, type/lint/build and unchanged actual-topic metadata. Future impact: new prompt/protocol content must use the runner's measurement at compilation; no silent topic migration or budget override. No semantic conflict or further product-policy approval identified; feature mode does not promote canonical documents.