docs(evaluations): show a typed outcome grader (EvalGraderFunction / EvalGraderContext / EvalScriptOutcome)

[ScriptedAlchemy]

Fixes #489. Docs only — skip-changeset.

What

website/docs/{en,zh}/guide/development/evaluations.mdx gain a "Writing an outcome grader" subsection right after the suite sample:

• what expectOutcome({ script }) names (a module resolved relative to the suite file, kept inside the suite directory, default-exporting one grader function);
• the sample grader, typed as EvalGraderFunction — examples/skills-starter/evals/graders/release-result.ts verbatim (chosen over mcp-app's status-result.ts because it is self-contained: the mcp-app grader imports the project's compiler-status-contract.ts, which a docs sample cannot carry without diverging from the file). The text says which file it is, and that the suite sample's ./graders/status-result.ts has the same shape;
• a three-row table for EvalGraderContext (fixturePath = the trial's materialised fixture copy the agent ran against, artifactRoot = the prepared artifact, prompt), checked against eval/harness.ts (materializeEvalFixture → fixture.path, options.artifact.root);
• the EvalScriptOutcome shape (outcome: pass | fail | inconclusive; detail shown in the trial record) and the failure semantics from eval/graders.ts (gradeScript → TypeError → EVAL_GRADER_FAILED, result inconclusive);
• links to the TypeDoc pages eval.EvalGraderFunction, eval.EvalGraderContext, eval.EvalScriptOutcome.

The sample is a ts twoslash block, so the docs build type-checks it against the real agent-bundle/eval export.

Checks

pnpm docs:site:build passes (twoslash, dead links/anchors, language parity). No code change; no changeset (the grader types already exist).

Review status

• 5cc849f3a — Codex reviewed; one P2 thread ("Do not promise physical grader containment"): containedPath in eval/graders.ts is a lexical resolve/relative check and jiti follows a symlink inside the suite wherever it points. Addressed in the follow-up commit: the sentence now says the path must not climb out of the suite directory and that the check is on the path, so a symlink inside the suite is followed (en + zh).
• Rebased onto current main. Awaiting the reviewer on the current head. Per this task's rules no PR comments are posted; review threads are answered by commits and recorded here.

[changeset-bot]

⚠️ No Changeset found

Latest commit: eb71b21

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-04T06:29:57.010694Z	5cc849f	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@535

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@535

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@535

commit: eb71b21

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5cc849f3a0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not promise physical grader containment

When an in-suite grader path is a symlink to a module outside the suite, this statement is false: containedPath in packages/agent-bundle/src/eval/graders.ts checks only resolve/relative, and loadJiti().import(target) follows the link without a realpath or symlink check. Either describe this as lexical path containment or enforce physical containment, so users do not rely on a boundary that does not exist.

AGENTS.md reference: AGENTS.md:L78-L81

Useful? React with 👍 / 👎.