> ## Documentation Index
> Fetch the complete documentation index at: https://mikting.docs.komo.moe/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug checks

> Private checks through /mikting-debug.

A script in the normal scripts directory can define an optional `debug:`
section. Mikting registers that section as an admin-only
`/mikting-debug <script-name>` subcommand. The script filename supplies the
subcommand name. Names are sanitized to lowercase letters, numbers, hyphens,
and underscores, up to 32 characters. Subfolders are flattened with hyphens.
A separate debug folder is not used.

## Write a check

Keep event actions under the root `actions:` key. Put on-demand actions under
`debug.actions:`. Debug may also define its own conditions; root conditions
apply only to event actions.

```yaml theme={null}
# configs/Mikting/scripts/api-health.yml
actions:
  - id: miktingHttp
    triggers: everyHour
    args:
      url: 'https://api.example.com/health'
      storeAs: health

debug:
  actions:
    - id: miktingHttp
      args:
        url: 'https://api.example.com/health'
        storeAs: check
```

Run `/mikting-debug api-health` to execute only `debug.actions` in the current
guild, channel, and member context. Debug actions do not need triggers. A
script without `debug:` has no debug subcommand. An on-demand-only script can
use `actions: []` at the root.

After the check runs, Mikting updates a private report with the result. Without
a response validator, completion means the actions finished; it does not claim
the API data is valid. Actions can still perform their configured side effects,
so use harmless actions for debug checks.

## Collect text from a form

Set `debug.input` to collect text before running the check:

```yaml theme={null}
debug:
  input:
    title: API check
    label: Text to check
    placeholder: Enter or paste text here.
  actions:
    - id: miktingHttp
      args:
        method: POST
        url: 'https://api.example.com/check'
        json: { text: '[[debug_input]]' }
        storeAs: check
```

The title and label are required and accept 1 to 45 characters. The placeholder
is optional and accepts 1 to 100 characters. The form has one required
multiline input with a 4000 character limit. The submitted value is available
as `[[debug_input]]`. Without `debug.input`, the check runs immediately.

Only an administrator can submit the form opened by their command invocation.
Closing the form runs no actions. Forms expire after five minutes. If the
script reloads while a form is open, run the command again.

## Validate an API response

A debug response check can require a specific HTTP response contract:

```yaml theme={null}
debug:
  response-check:
    type: openai-moderation
    storeAs: probe
  actions:
    - id: miktingHttp
      args:
        method: POST
        url: 'https://api.openai.com/v1/moderations'
        auth: { type: bearer, tokenSecret: OPENAI_API_KEY }
        json: { model: omni-moderation-latest, input: '[[debug_input]]' }
        storeAs: probe
```

Use the form above to provide `[[debug_input]]`. `storeAs` must match the HTTP
action and be a variable name beginning with a letter or underscore. The
standard check type is `openai-moderation`.

It requires a successful HTTP status, valid JSON, no API error envelope, a
nonempty response ID and model, exactly one result, a boolean `flagged`, the
required category flags, scores, and input-type maps. Scores must be numbers
from 0 to 1. Documented nullable illicit flags are accepted, as are additional
fields. A numeric or string verdict fails. The validator follows the
[OpenAI response contract](https://developers.openai.com/api/reference/resources/moderations/methods/create)
and [score definitions](https://developers.openai.com/api/docs/guides/moderation).

For the selected contextual policy, add a second HTTP request and configure a
policy namespace:

```yaml theme={null}
response-check:
  type: openai-moderation
  storeAs: probe
  policyStoreAs: history_probe
  policyType: jev-policy
  policyThreshold: &history_threshold 0.80
```

The Jev request uses a `historical_endorsement` Noul question. Its validation
requires a successful status, valid JSON without an error envelope, a model,
the expected answer type, a finite score from 0 to 1, and valid token counters.
A score at or above `policyThreshold` flags; the default is 0.80. Additional
fields are allowed. Jev does not require a response ID or generate an
explanation. See the [TypeSafe API](https://docs.typesafe.ai/api).

The report shows OpenAI and Jev connectivity and validation separately, then
the combined decision. A valid OpenAI flag applies the existing moderation
path immediately. A valid clean result proceeds to Jev. A failed check names
the failed stage and reason, includes status and request ID when available,
and adds a redacted response excerpt capped at 500 characters. Jev's score is
an estimate; below threshold means no automatic action, not a guarantee of
accuracy. Debug checks do not add strikes or timeouts unless their own actions
are configured to do so.

If the expected HTTP action was skipped or its `storeAs` differs from the
configured namespace, the report identifies the script configuration error.
Failures while sending a report are logged with Mikting's redacting logger. If
the initial acknowledgement fails, the API request does not run.

## Reload and migrate checks

New or changed checks become available after `/reload`. Mikting registers up
to 25 unique sanitized names. Files beginning with `_` are skipped; a broken
file is skipped with a warning.

To migrate a check from `<scripts.dir>/debug/api-health.yml`, move it to
`<scripts.dir>/api-health.yml`, put its old actions and conditions under
`debug:`, then add `actions: []` at the root or retain its event actions. Run
`/reload` after moving it.

## OpenAI and Jev example

`self-scripts/openai-moderation.yml` includes a private input form. Copy it into
the normal scripts directory, reload, then run
`/mikting-debug openai-moderation`. The submitted text is sent to OpenAI and
TypeSafe Jev. The report includes each provider's status and validation, plus
the moderation result. Environment keys such as
`MIKTING_TYPESAFE_API_KEY_1` rotate automatically. An unnumbered key also
works; additional keys do not increase an organization's quota.

Debug sends only the text you submit. It does not delete messages or change
strikes. Mocked HTTP tests cover request and validation behavior, but do not
show live provider connectivity or classification accuracy. Test both with the
bot using text you provide.

[Documentation home](https://mikting.docs.komo.moe/index.md) · [Source Markdown](https://gitlab.com/komomori/mikting/-/blob/main/docs/mikting-debug.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.