Technical documentation / Reference

Jev and internal tooling

Feature docs index · Configuration · Tools and safety model

magi-code uses TypeSafe Jev for bounded semantic judgments. Jev receives state plus a typed question and returns structured probabilities. It does not replace the main conversation model.

All Jev features are optional and disabled by default.

Set up Jev

1. Create a TypeSafe API key.
2. Export it before starting magi-code:

   export TYPESAFE_API_KEY="your-key"
   magi-code

1. Open /settings and select Internal Tooling.
2. Enable Jev tooling, then enable only the features you need.
3. Save settings. Jev becomes available for future actions.

Do not put the API key in settings.json. Enabling Jev without a non-empty TYPESAFE_API_KEY causes settings validation to fail.

Agent tool

Enable agent tool gives the agent a jev tool for one bounded semantic question. Supported question types follow TypeSafe's primitives:

• Choice selects one defined option.
• Score rates state against ordered descriptive levels.
• Noul returns probability of yes.

The agent must supply all evidence in the tool's state. The tool is intended for judgment, routing, ranking, and verification. It is not a text generator, factual lookup service, permission check, or substitute for deterministic code.

Bash protection

Bash protection scores each proposed bash command as low, elevated, or high operational risk. A command needs approval when its risk score reaches the selected threshold or confidence falls below that level's threshold.

Protection levels, from least to most restrictive:

• permissive
• relaxed (default)
• balanced
• cautious
• strict

Mission Control shows Jev's score, confidence, probabilities, cache status, and decision on the tool card. Flagged commands open an approval prompt before execution.

API failure policy controls what happens when Jev cannot assess a command:

• auto_approve allows execution. This is the default.
• auto_deny blocks execution.

Prose protection

Prose protection checks documentation and code comments changed through write or hash_edit. It first decides whether the edit contains prose, then checks whether that prose is clear and natural. A rejected edit tells the agent to load $writer-humanizer, revise, and retry.

Settings:

• Prose detection threshold decides when an edit counts as comments or documentation. Default: 0.7.
• Humanized threshold sets the probability required to allow prose. Default: 0.65.
• API failure policy either allows or denies the edit when assessment fails. Default: auto_deny.

Both thresholds must be between 0 and 1.

Prompt injection protection

Prompt injection protection assesses selected untrusted tool outputs before they return to provider context. It checks for instructions aimed at an agent, injection likelihood, and potential impact.

Assessment defaults to observe-only. Enable Enforce decisions to apply the result:

• annotate retains risky output with a warning.
• quarantine withholds risky output from provider context. This is the default failure policy.

Choose a protection level from permissive, relaxed, balanced (default), cautious, or strict. Maximum assessed bytes bounds content sent for one assessment; default is 32 KiB. Protected tools defaults to web.

write, hash_edit, magi_control, and jev results are trusted control output and bypass this assessment.

Completion verification

Completion verification evaluates a proposed terminal response against bounded evidence from the current turn. It checks whether the request was satisfied, blockers remain, claims have support, and scope was respected.

Assessment defaults to observe-only. With Enforce completion decisions enabled, the verifier can request a bounded corrective continuation or finish with a limitation message.

Settings:

• Completion threshold applies to verification dimensions. Default: 0.7.
• Maximum evidence bytes bounds state sent to Jev. Default: 32 KiB.
• Maximum continuations caps verifier-triggered continuations per user turn. Default: 1.
• Verifier failure policy accepts with a warning or rejects with a warning when verification fails. Default: accept_with_warning.

Cache and data handling

Jev requests send the state needed for an enabled assessment to TypeSafe. This may include commands, proposed file edits, selected tool output, or bounded conversation evidence. Do not enable a feature for data you cannot send to TypeSafe.

Responses are cached by request hash under the magi-code cache directory in jev/; cache files use owner-only permissions on Unix. Open /settings and choose Reset Jev cache to delete them. A repeated request may use its cached response instead of calling TypeSafe again.

Troubleshooting

• TYPESAFE_API_KEY is required when Jev tooling is enabled: export the key in the environment that launches magi-code, then restart.
• Unexpected blocks after an API error: check the feature's failure policy.
• Prompt injection findings do not change behavior: enable Enforce decisions; assessment alone is observe-only.
• Completion findings do not trigger correction: enable Enforce completion decisions.
• Stale-looking assessment: reset the Jev cache and retry.

Edit this page on GitHub ↗