scripted-runtime-notes

Guides API design decisions for the SGLang scripted runtime test harness.

33.0k|8.4k|Updated Jan 8, 2024
One-click install
npx skills add https://github.com/sgl-project/sglang --skill scripted-runtime-notes
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: scripted-runtime-notes
Source: https://github.com/sgl-project/sglang/tree/main/.claude/skills/scripted-runtime-notes
Command: npx skills add https://github.com/sgl-project/sglang --skill scripted-runtime-notes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When writing tests against the SGLang scripted runtime, engineers often add unnecessary harness wrapper APIs that grow the surface without adding isolation, or probe implementation details instead of asserting real behavior. This Skill codifies the rules for when to add a harness API versus reading scheduler state directly.

Core Features & Use Cases

  • API Decision Rules: Defines the three legitimate cases for adding a harness API: control primitives driving real engine paths, hook-backed accumulators, and widely reused multi-structure derivations.
  • Anti-Pattern Guardrails: Lists what never to do, including weakening assertions to fit missing probes, monkey-patching, and calling scheduler privates synchronously from tests.
  • Use Case: While writing a test that checks scheduler idle behavior, use this Skill to decide whether to add an is_idle helper or read t._scheduler state directly, and to drive engine-self-driven behavior via the real loop with yield instead of calling private methods.

Quick Start

Ask the AI to review your scripted runtime test and decide whether a new harness API is justified according to the scripted runtime notes.

Frequently Asked Questions about scripted-runtime-notes

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
When should I add a harness API to the SGLang scripted runtime?

Add an API only if it does real work: a control primitive driving the engine through a real path, a hook-backed accumulator for values not readable from snapshots, or a widely reused multi-structure derivation. Otherwise read r.req or t._scheduler directly in the test.

How do I test scheduler behavior in SGLang without wrapper APIs?

Read r.req.X and t._scheduler.X directly in the test, since there is no encapsulation boundary. Inline single-use accessors rather than adding thin wrappers that only grow the API surface.

Why should tests not call scheduler private methods directly?

Calling privates like scheduler._abort_on_waiting_timeout() synchronously runs at the wrong loop phase, bypasses the ordered recv_requests and process_input_requests injection, and can fire in states the real loop never reaches. Enable the config and advance the loop with yield instead.

What assertions should scripted runtime tests avoid?

Avoid probing implementation details such as field non-None checks or which branch ran, and never weaken an assertion to fit a missing probe. Assert the observable consequence of the behavior instead.

How do I collect metrics not available in scheduler snapshots?

Accumulate them via scheduler_hook.on_run_batch or the recv proxy such as chunks_done. Keep it read-only, never monkey-patch, and never add counting fields to the srt/ source tree.