How TeaQL Saves Agent Context

A coding agent building an Order page needs the business requirement, the current model, the relevant API contract and the result of its last check. As work progresses, it can also accumulate modeling instructions, generated implementation files, old Assist responses and complete build logs. Those materials have different useful lifetimes.

TeaQL addresses this at several layers. A reusable runtime supplies common engineering capabilities. A generated type library supplies a broad, composable business vocabulary. Assist provides the precise contract needed for the current task. Skills and temporary outputs have explicit lifetimes; where the host supports it, Context Kit removes expired material before the next model request.

These choices reduce different kinds of work: application code that AI must generate and maintain, implementation text that would otherwise enter context, and API-search and trial-and-error steps before a useful edit.

The useful unit of optimization is the context supplied for the next decision. Durable evidence can remain on disk after its full text leaves that view.

This article separates TeaQL's workflow instructions from Context Kit's executable host integrations. The activation boundaries matter: reading the Skill alone does not enable lifecycle rewriting or marker enforcement.

Context changes with the task stage. A trusted host applies the declared lifetimes to eligible material; original logs and receipts remain on disk. Public contracts, configuration and unresolved findings still belong in context when the current task needs them.

Start with the lifetime of a Skill

The Agent Skills specification describes progressive disclosure: metadata for discovery, instructions when activated, and supporting resources when needed. This limits what must be loaded initially. TeaQL also asks when loaded material should stop participating in subsequent requests.

The build-teaql-app Skill names two phase-specific blocks:

<!--BLOCK_ID:phase_modeling-->
Modeling and evaluation instructions for this phase.
<!--/BLOCK_ID:phase_modeling-->

phase_modeling and phase_codegen identify removable text. Standing rules such as preserving business intent, using current Assist and reporting actual evidence remain relevant after those phases. A named block stays active across requests until a trusted host workflow or control API discards it:

<!--DISCARD_BLOCK:phase_modeling-->

The declaration is exact and case-sensitive. The runtime does not infer semantic phase completion. A model's claim that evaluation passed is not, by itself, a trusted lifecycle event. The host must validate the gate and connect that event to discard. The current TeaQL phase comments and generic lifecycle adapters do not automatically compose that whole workflow.

When a model changes again, its evaluation and affected Assist may need refreshing. The durable model, unresolved findings and task state must survive phase cleanup. An instruction should expire because its scope ended, not merely because it is old.

See the pinned Skill source and lifecycle protocol.

Reuse runtime capabilities across workspaces

Observability, testability and internationalization are reusable runtime capabilities. An Order workspace can use those implementations instead of asking AI to recreate a tracing layer, repository test infrastructure and message resolution engine for each application.

Capability	Reused implementation	Application responsibility
Observability	Typed execution traces, diagnostic/evidence surfaces and telemetry lifecycle hooks.	Configure the selected exporter and sampling, choose permitted attributes and operate the destination.
Testability	Context/provider boundaries and, where supported, a memory repository for fast tests.	Write business scenarios and assertions; retain real-provider tests for database behavior.
Internationalization	Locale catalogs, message resolution, checker-message translation and fallback.	Supply business vocabulary/translations, load the catalog and select the trusted locale.

The workspace concentrates on business behavior, configuration and necessary extensions. It carries less repeated application-owned infrastructure for AI to write, review, modify and rediscover during later repairs. The reusable runtime also keeps fixes to those shared implementations outside each business task.

The total dependency checkout or binary can still be large: this is a reduction in duplicated, AI-authored application code, not a guarantee of smaller disk usage. Availability and configuration remain runtime/version specific. See observability, memory-provider tests and internationalization for concrete boundaries.

Use a large type library through a focused contract

TeaQL's generated type library can be large. It exposes domain entities, fields, relationships, typed query builders and expressions. Selection, predicates, ordering, relation loading and aggregation can be combined to express many business operations. The generator supplies reusable typed building blocks; application code composes the particular operation it needs.

That breadth is useful API capacity. It does not need to become proportionally large model context. The compiler consumes the library's types and signatures; the runtime executes the composed operation. AI works with the current model, the relevant contract and a small amount of application code. A large type library and a focused AI workspace can therefore coexist.

TeaQL generates a domain library so business code can use its public contract. Business-development agents should discover that contract through the application AGENTS.md, the model, current entity/action Assist and the fields they need. Do not inspect or recursively search generated domain-library source to discover methods. Missing guidance is reported as MISSING_ASSIST, with the operation and diagnostic needed to repair the contract.

A marker-aware host can enforce the context boundary with this layout:

application/
  AGENTS.md
  model/
  docs/api/
  src/                       editable application code
  generated-library/
    .agent-no-read.md
    ...                      generated implementation

In the covered host integrations, the marker excludes its directory and descendants from checked reads, searches, listings and automatic project-context loading. Its short body can point to permitted API documentation. The shared policy caps the combined reason and guidance at 1 KiB, excluding response framing and paths. Even a refusal has a bounded context footprint.

The compiler can still use the implementation internally. Controlled build/test tools return permitted diagnostics without forwarding excluded source or arbitrary raw logs. Generation wrappers can restore markers when output directories are rebuilt; automatic inclusion in every language's distributed artifacts requires separate verification.

This boundary applies to business API discovery. Deliberate generator/runtime maintenance is a different task with its own authorized source scope. A marker also requires a cooperating harness: it is not an OS sandbox, does not govern an unrestricted shell, and cannot retract content already sent to a model.

See the marker policy and controlled diagnostics.

Ask Assist for the exact API needed now

Assist makes the generated library usable without repository searches for its method names. Its guidance comes from the model descriptors and generated API inventory, scoped to the requested language, entity/action and field.

Progressive query Assist first returns the entity's executable base query and a compact field index. A second request for entity.field supplies the relevant select, predicate, ordering or aggregation surface. AI obtains the current call shape and composes business code directly, then compiles that caller against the generated library.

This avoids collecting search hits, opening generated implementations and reconstructing an API from scattered examples. Less irrelevant text enters context, and less work is spent locating interfaces or trying guessed methods. The relevant saving is both space in the working request and time spent on API discovery and repair; an end-to-end latency reduction still requires measurement.

This boundary concerns generated API discovery. Finding the application code that needs changing remains part of normal development. Missing or contradictory guidance is an Assist defect to report, not a reason to infer an interface from another language. See Assist and generated workspaces.

The Type Library–Assist connection represents the model and API inventory used to supply a scoped contract. It does not require the agent to read the whole generated library. Build and test tools use the full implementation and return relevant diagnostics; application configuration and business assertions remain the developer's responsibility.

Let one-use output leave the next request

A model may need a detailed tool result to make its next edit. Once that edit has been checked, repeating the complete earlier result can add little useful context. Context Kit supports a consume-once declaration:

<!--ephemeral-->
Detailed tool output needed for the next decision.

The tool or host must actually mark eligible output. This is not automatically enabled for every TeaQL Assist response by installing the Skill.

It marks the entire containing message or tool result, not just a paragraph. The original enters the first applicable model request. After a later assistant response exists, subsequent request copies replace its content with a short placeholder while preserving tool-call pairing metadata:

[EPHEMERAL:Output omitted after consumption;original_bytes=12345]

The byte count above illustrates the format. It is not a measured token saving.

This is what “burn after reading” means here: the full output stops recurring in the model-visible request. The source file, original transcript and tool artifact remain intact. It does not delete provider-side records or guarantee erasure of information the model has already seen.

The host must retain anything required for later decisions in a concise durable form: current model/version, unresolved errors, affected entities, verification status and evidence locations. If a later task needs the details, request the current scoped guidance again. Do not mark standing authorization rules, pending requirements or the only copy of an unresolved finding as disposable.

Express an Order operation through business APIs

Reducing context is also an API-design problem. If application work requires reconstructing physical tables, joins, row mapping and relationship assembly, those details become part of the agent's working material.

This Java fragment is taken from the retained, database-verified Order application:

var rows = Q.customerOrders().withOrderNumberIs("ORD-2026-1001").selectOrderStatus()
    .selectOrderItemListWith(Q.orderItems().orderBySkuCodeAscending().orderByIdAscending().limit(101))
    .limit(2).comment("Load full draft order and complete bounded items")
    .purpose("Validate and edit one draft order").executeForList(context);

The fragment names an Order identity, selected status, ordered and bounded items, and the intent of execution through a trusted context. Its contract is supplied by the model and Assist rather than inferred from generated implementation files.

It is a function-body excerpt with existing imports and startup, not a standalone application. The outer bound allows duplicate-identity detection; 101 children provide an overflow sentinel for the example's maximum of 100. The surrounding application checks cardinality, complete loading, quantities and integer money before saving. A business predicate does not authenticate a buyer or establish tenant isolation.

Compact expression preserves responsibilities while moving repeated persistence mechanics behind a reusable contract. It does not imply fewer database queries, cheaper plans or shorter text than every handwritten SQL query. Follow the Java Order tutorial and its dated source-bound receipt. Its existing published/workspace and RELEASE PENDING qualifications still apply.

Return precise feedback and keep repairs local

An economical tool response must still explain the failure that matters. Otherwise the agent can spend more context trying unrelated repairs or rereading a denied path.

A recorded real-model Pi repair from October 25, 2026 illustrates this. A generic method-unavailable diagnostic first led to an incorrect repair and regeneration. After the diagnostic identified the PurposedQuery<T> receiver and explained query-stage ordering, a fresh run made a localized change in application-owned student.rs: two lines removed and two added. It built successfully without generated-source read attempts or generation calls in that successful run.

The recorded test command executed zero test cases, and that run did not exercise a database. Provider token usage was unavailable. The evidence supports that specific compilation repair and the value of actionable feedback; it does not measure a token-saving rate or establish business-test coverage.

The same division of work keeps repeated validation rules in evaluators, compilers and runtime policy rather than continually expanding Skill prose. Short, typed feedback and localized edits are useful when they preserve the meaning necessary to choose the next action.

Why this matters for large projects and edge AI coding

Deliver larger systems through focused changes

As a project grows, shared infrastructure, generated APIs and historical decisions can grow with it. Reusable runtime capabilities and generated contracts let each business change start from an established foundation. Scoped Assist and explicit context lifetimes help keep the agent's working view focused on that change.

This creates a practical path for using bounded AI tasks inside a much larger system: supply the relevant model and contract, implement a local change, then check it against shared rules and retained evidence. Human review can concentrate on business meaning and integration impact. Cross-module dependencies, contract changes and regression coverage still require explicit coordination; a focused prompt does not resolve them automatically.

Make limited local inference capacity more useful

For an AI coding agent running on an edge device, local memory, compute and context capacity must serve the current task. Avoiding repeated implementation text and expired instructions leaves more of that working capacity for business intent, the relevant API and the next repair. Runtime reuse also reduces how much new application code the model must produce. This is an architectural route for a smaller local model to participate in focused business development with deterministic tools.

Running the coding agent on a device is distinct from producing an application that later runs there. A fully offline workflow additionally needs evaluation and generation tools available locally, matching local or cached Assist, and the build and test toolchain. Cached guidance must match the model and tool versions; a changed model requires fresh evaluation. Local model inference alone does not establish offline availability of those services. Hardware feasibility, latency, energy use and delivery outcomes must be measured on the selected deployment. The checks below do not establish edge-device performance or general large-project delivery.

What the context checks demonstrate

The October 29 verification receipt records 7 passing targeted checks using Node 22.23.4 and Pi SDK 1.4.0. The lifecycle and marker-policy tests exercise distinct entry points. They use the real Pi request/tool loop with a deterministic local faux provider, without a network model, new model generation or database execution.

The captured lifecycle requests were:

Provider request	Modeling block	One-use tool output
1	Visible	Not yet present
2	Visible	Original content
3	Visible	Short placeholder
4, after trusted discard	Absent	Short placeholder

The final transcript check retains the original output and finds no persisted placeholder. The separate marker-policy fixture checks that excluded source and automatic context do not enter captured provider requests, while allowed business source remains readable.

A source census of the pinned Skill commit identifies 11,481 UTF-8 bytes in phase_modeling and 1,859 bytes in phase_codegen, within a 20,230-byte file. These describe addressable source text, not the reduction of a live TeaQL prompt. The receipt identifies the census source separately from the local Skill contract check.

No production token reduction, billing saving, latency improvement or task-success uplift is measured here. Those require comparable tasks, host/model versions, request-level token counts, cache accounting and independently checked outcomes.

Which hosts enforce which parts

Check the selected entry point in the feature activation matrix. The source snapshot behind this article is commit 76d4e2d474f9; its package metadata is 0.5.0, not a claim of a new npm release.

Entry point	Relevant boundary
Pi ordinary lifecycle plugin	Named blocks, trusted discard and consume-once behavior; installation alone does not enable marker enforcement.
Pi dedicated policy harness / native CLI bootstrap	Marker-aware tools and checked context; lifecycle composition and trusted phase wiring depend on the selected entry point.
OpenCode V2 strict plugin	Marker policy and controlled tools, with explicitly configured trusted lifecycle declarations.
Other runtime adapters	Capabilities vary with host hooks; some support current-request context without consume-once history rewriting.
Context Kit guidance for Codex, Claude Code and Cursor	Protocol-authoring guidance; this package does not claim runtime enforcement on these hosts.

Seven TeaQL language runtimes and coding-agent host adapters are separate coverage dimensions. One working adapter or Rust tool integration does not establish a complete seven-language protected workflow.

Reproduce the lifecycle evidence

From a fresh checkout, use Node 22.19 or newer and the pinned repository lockfile:

git clone https://github.com/teaql/teaql-agent-kit.git
cd teaql-agent-kit
git checkout 76d4e2d474f91b8c2eeff63db871b622afe4a771
npm ci
node --test --experimental-strip-types \
  packages/agent-context-kit/test/integration/pi-runtime.test.ts \
  packages/agent-context-kit/test/integration/pi-context.test.ts \
  tests/context-runtime/skill-contract.test.mjs
node --experimental-strip-types \
  packages/agent-context-kit/scripts/pi-runtime-trace.ts \
  .artifacts/pi-context-trace.jsonl

Inspect the provider requests and persistent-transcript record, not only the test exit code. For an application rollout, separately verify trusted phase transitions, readable business sources, marker restoration, diagnostic filtering and the exact adapter capabilities you enable.

For background, the Agent Skills specification documents on-demand loading. Anthropic's context-engineering discussion treats the request's working information as an engineering resource. The 2024 Lost in the Middle study observed position-sensitive retrieval in its tested models and tasks. These motivate careful context selection; they are not measurements of TeaQL or guarantees about every current model.

Continue with the TeaQL Harness, AI coding workflow and Order API usage to apply the same boundaries to a concrete business task.