Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/content/docs/reference/ceps/cep-22.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ This CEP is focused on **bounded** transfer only. It does not define open-ended

### Capability Advertisement and Negotiation

Support MAY be advertised through the same additive discovery surfaces used by ContextVM features, following [`src/content/docs/spec/ceps/cep-6.md`](src/content/docs/spec/ceps/cep-6.md) and [`src/content/docs/spec/ceps/cep-19.md`](src/content/docs/spec/ceps/cep-19.md).
Support MAY be advertised through the same additive discovery surfaces used by ContextVM features, following [`CEP-6`](/reference/ceps/cep-6) and [`CEP-19`](/reference/ceps/cep-19).

Peers MAY advertise support using `support_oversized_transfer` tags.

Expand Down
12 changes: 6 additions & 6 deletions src/content/docs/reference/ceps/cep-41.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ description: Open-ended streams for ContextVM using progress-notification framin

This CEP defines an additive transport profile for open-ended streaming over ContextVM. It reuses MCP `notifications/progress` as the transfer envelope and uses the request `progressToken` as the stream identifier.

Unlike bounded oversized-payload transfer in [`CEP-22`](/src/content/docs/spec/ceps/cep-22.md), this CEP defines a long-lived stream model where ordered fragments may continue until the sender explicitly closes or aborts the stream. The stream payload itself is the primary incremental output, but it does not replace the final JSON-RPC response for the originating request.
Unlike bounded oversized-payload transfer in [`CEP-22`](/reference/ceps/cep-22), this CEP defines a long-lived stream model where ordered fragments may continue until the sender explicitly closes or aborts the stream. The stream payload itself is the primary incremental output, but it does not replace the final JSON-RPC response for the originating request.

This CEP is intended for cases where data is naturally incremental, long-lived, or unbounded, and where representing the result as one reassembled MCP request or response would be artificial or inefficient.

## Specification

### Overview

ContextVM currently transports MCP JSON-RPC messages through Nostr events. That model fits ordinary request and response exchange well, and [`CEP-22`](/src/content/docs/spec/ceps/cep-22.md) extends it for bounded reassembly of oversized logical messages.
ContextVM currently transports MCP JSON-RPC messages through Nostr events. That model fits ordinary request and response exchange well, and [`CEP-22`](/reference/ceps/cep-22) extends it for bounded reassembly of oversized logical messages.

Some use cases are different in nature:

Expand All @@ -35,11 +35,11 @@ This CEP defines an open-ended stream profile that:
- treats the stream itself as the payload rather than a bounded reassembly artifact
- allows receivers to process fragments incrementally as they arrive

This CEP is intentionally distinct from the bounded reassembly mechanism in [`CEP-22`](/src/content/docs/spec/ceps/cep-22.md). Implementations MUST NOT treat these two profiles as interchangeable.
This CEP is intentionally distinct from the bounded reassembly mechanism in [`CEP-22`](/reference/ceps/cep-22). Implementations MUST NOT treat these two profiles as interchangeable.

### Capability Advertisement and Negotiation

Support for open-ended stream transfer MAY be advertised through the same additive discovery surfaces already used by ContextVM capabilities and transport features, following the patterns in [`CEP-35`](/src/content/docs/spec/ceps/informational/cep-35.md).
Support for open-ended stream transfer MAY be advertised through the same additive discovery surfaces already used by ContextVM capabilities and transport features, following the patterns in [`CEP-35`](/reference/ceps/informational/cep-35).

Peers MAY advertise support using one or more `support_open_stream` tags.

Expand Down Expand Up @@ -166,7 +166,7 @@ Rules:

`accept` is conditional bootstrap confirmation, not a universal requirement.

This mirrors the `accept` semantics defined in [`CEP-22`](/src/content/docs/spec/ceps/cep-22.md), so implementations can reuse the same conceptual model for conditional bootstrap confirmation and avoid semantic drift between the two transfer profiles.
This mirrors the `accept` semantics defined in [`CEP-22`](/reference/ceps/cep-22), so implementations can reuse the same conceptual model for conditional bootstrap confirmation and avoid semantic drift between the two transfer profiles.

- If the sender already knows that the receiver supports this CEP for the exchange through prior negotiation, explicit capability advertisement, or other valid context for the exchange, it MAY send `chunk` frames immediately after `start`.
- If support is not yet known for the exchange, the sender MUST wait for `accept` before sending the first `chunk` frame.
Expand All @@ -186,7 +186,7 @@ Rules:
- For open-stream frames, MCP `progress` is the normative stream-ordering field for all frames.
- Each `chunk` frame MUST use a `progress` value greater than the preceding stream frame's `progress` value.
- `chunkIndex` MUST start at `0` for the first `chunk` frame in the stream and increase contiguously by `1` for each subsequent `chunk` frame.
- `data` carries one ordered fragment of the stream payload, following the same chunk-payload semantics as [`CEP-22`](/src/content/docs/spec/ceps/cep-22.md).
- `data` carries one ordered fragment of the stream payload, following the same chunk-payload semantics as [`CEP-22`](/reference/ceps/cep-22).
- Receivers MUST use `chunkIndex`, not `progress`, to validate chunk contiguity and payload completeness.
- Receivers MAY buffer valid out-of-order `chunk` frames within bounded local limits and process them once the contiguous `chunkIndex` sequence resumes.
- Receivers MAY track missing `chunkIndex` values as provisional gaps while the stream remains active.
Expand Down
14 changes: 7 additions & 7 deletions src/content/docs/reference/ts-sdk/core/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The SDK uses Pino for high-performance logging with structured JSON output. By d

#### Basic Usage

[`typescript`](src/content/docs/ts-sdk/core/logging.md:10)


```typescript
import { createLogger } from '@contextvm/sdk/core';
Expand All @@ -23,7 +23,7 @@ logger.error('An error occurred', { error: 'details' });

#### Configuration Options

[`typescript`](src/content/docs/ts-sdk/core/logging.md:20)


```typescript
import { createLogger, LoggerConfig } from '@contextvm/sdk/core';
Expand Down Expand Up @@ -53,7 +53,7 @@ The logger can be configured using environment variables, which is useful for ad

##### Configuration in Node.js

[`bash`](src/content/docs/ts-sdk/core/logging.md:49)


```bash
# Set log level to debug
Expand All @@ -68,7 +68,7 @@ LOG_ENABLED=false node app.js

##### Configuration in Browsers

[`javascript`](src/content/docs/ts-sdk/core/logging.md:63)


```javascript
// Set this in a <script> tag in your HTML or at the top of your entry point
Expand All @@ -81,7 +81,7 @@ logger.debug('This is a debug message.');

#### Module-specific Loggers

[`typescript`](src/content/docs/ts-sdk/core/logging.md:75)


```typescript
const baseLogger = createLogger('my-app');
Expand Down Expand Up @@ -112,7 +112,7 @@ dbLogger.debug('Query executed', { query: 'SELECT * FROM users' });

#### Examples (Best Practice)

[`typescript`](src/content/docs/ts-sdk/core/logging.md:105)


```typescript
logger.info('payment.processed', {
Expand Down Expand Up @@ -143,4 +143,4 @@ try {

---

See also: [`src/content/docs/ts-sdk/core/interfaces.md`](src/content/docs/ts-sdk/core/interfaces.md:1)
See also: [Core Interfaces](/reference/ts-sdk/core/interfaces)
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ console.log('Available tools:', tools);

### Identity input precedence

[`NostrClientTransport`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md:56) resolves server identity and relays conservatively:
`NostrClientTransport` resolves server identity and relays conservatively:

1. explicit operational relays from `relayHandler`
2. relay hints embedded in `nprofile`
Expand Down Expand Up @@ -130,17 +130,17 @@ For requests that may receive progress notifications over a longer period, `rese

## Server Discovery and Relay Selection

The client transport accepts a known [`serverPubkey`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md:28) in multiple forms and can now resolve operational relays automatically when needed.
The client transport accepts a known `serverPubkey` in multiple forms and can now resolve operational relays automatically when needed.

Typical flow:

1. If explicit operational relays are configured, the transport uses them directly.
2. Else, if the server identity is an `nprofile` with relay hints, the transport uses those hints as the operational relay set.
3. Else, the transport starts CEP-17 relay-list discovery and fallback operational relay probing in parallel.
4. If CEP-17 returns a usable `kind:10002` relay list first, that authoritative result is used.
5. If [`fallbackOperationalRelayUrls`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md) proves connectivity first while discovery is still unresolved, the transport proceeds with that non-authoritative relay set.
6. If [`discoveryRelayUrls`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md:31) is omitted, the transport still uses the SDK bootstrap relays for the CEP-17 lookup.
7. The transport prefers unmarked `r` tags as the operational relay set, matching the recommended ContextVM profile in [`CEP-17`](contextvm-docs/src/content/docs/spec/ceps/cep-17.md:52).
5. If `fallbackOperationalRelayUrls` proves connectivity first while discovery is still unresolved, the transport proceeds with that non-authoritative relay set.
6. If `discoveryRelayUrls` is omitted, the transport still uses the SDK bootstrap relays for the CEP-17 lookup.
7. The transport prefers unmarked `r` tags as the operational relay set, matching the recommended ContextVM profile in [`CEP-17`](/reference/ceps/cep-17).

Example with discovery fallback:

Expand Down Expand Up @@ -185,9 +185,9 @@ In this case the client will attempt to resolve operational relays automatically

### Authoritative vs fallback relays

- [`relayHandler`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md:29) is authoritative and explicit.
- [`discoveryRelayUrls`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md:31) identifies where the client should look for CEP-17 metadata.
- [`fallbackOperationalRelayUrls`](contextvm-docs/src/content/docs/ts-sdk/transports/nostr-client-transport.md) is non-authoritative and only exists to reduce latency when discovery is slow or unresolved.
- `relayHandler` is authoritative and explicit.
- `discoveryRelayUrls` identifies where the client should look for CEP-17 metadata.
- `fallbackOperationalRelayUrls` is non-authoritative and only exists to reduce latency when discovery is slow or unresolved.

This separation keeps protocol correctness intact while still allowing practical connection recovery.

Expand Down