# SDK API Reference

Package:

```text
jwebot-sdk
```

Current API version:

```text
1
```

## Event

`Event` is the normalized incoming message exposed to extension code.

Important fields:

- `event_id`
- `observed_at`
- `sender`
- `text`
- `group_fingerprint`
- `mention_bot`
- `confidence`
- `sender_confidence`
- `body_confidence`
- `source`

`sender` is an untrusted display label. `group_fingerprint` binds kernel
delivery safety but is not a selectable target.

## ReplyPlan

```python
ReplyPlan.text("visible reply")
ReplyPlan.no_reply()
```

Maximum visible text length is 900 characters.

## Fact

```python
Fact(kind="topic", text="likes servers", confidence=0.8)
```

Facts are candidates. The kernel still applies scope, sensitivity, evidence,
expiry, and deduplication policy.

## ExtensionResult

```python
ExtensionResult(
    reply=ReplyPlan.text("visible reply"),
    facts=(Fact(...),),
    metadata={"source": "plugin-id"},
)
```

Limits:

- at most 12 facts;
- at most 16 metadata entries;
- short string metadata only.

## SingleGroupContext

Protocols exposed through the context:

- `commands`
- `storage`
- `http`
- `services`
- `facts`
- `scheduler`
- `logger`

Not exposed:

- GUI sender;
- group selector;
- raw OCR or screenshots;
- ledger or SQLite;
- filesystem;
- environment;
- subprocess or shell;
- arbitrary sockets or HTTP;
- credentials.

## CommandRegistry

```python
context.commands.register("/hello", handler)
```

The registered command must be declared in `plugin.toml`. The Kernel catalog
detects conflicts during startup and freezes before runtime routing.
User-visible `description` and `help` metadata also live in `plugin.toml`;
bundled `/功能列表` output is generated from the reviewed metadata rather than
from handler code.

## ApprovedHttpClient

```python
context.http.request(
    "approved-profile",
    method="GET",
    path="/bounded/path",
    query={"key": "value"},
)
```

The kernel owns host allowlists, credentials, proxy, timeout, cache, and
response limits. API version 1 does not expose a general-purpose URL client.

## ApprovedServiceBroker

```python
context.services.call(
    "reviewed-profile",
    operation="execute",
    payload={"bounded": "data"},
)
```

Reviewed local adapters use named profiles to request Kernel-owned behavior without
receiving raw Ledger, provider, process, or GUI objects. Undeclared or
unconfigured profiles fail closed.