@unicity-astrid/sdk 0.1.0

package/dist/contracts.d.ts

@@ -0,0 +1,1104 @@
+/** Types generated from the `types` WIT interface. */
+export declare namespace types {
+    /** A conversation message. */
+    interface Message {
+        role: MessageRole;
+        content: MessageContent;
+    }
+    type MessageRole = "system" | "user" | "assistant" | "tool";
+    /** Message content — text, tool calls, tool results, or mixed. */
+    type MessageContent = {
+        tag: "text";
+        value: string;
+    } | {
+        tag: "tool_calls";
+        value: ToolCall[];
+    } | {
+        tag: "tool_result";
+        value: ToolCallResult;
+    } | {
+        tag: "multi_part";
+        value: ContentPart[];
+    };
+    type ContentPart = {
+        tag: "text";
+        value: string;
+    } | {
+        tag: "image";
+        value: ImageData;
+    };
+    interface ImageData {
+        data: string;
+        media_type: string;
+    }
+    /** A tool call requested by the model. */
+    interface ToolCall {
+        /** Tool call identifier. */
+        id: string;
+        /** Name of the tool to invoke. */
+        name: string;
+        /** JSON-encoded arguments (serde_json::Value in Rust). */
+        arguments: string;
+    }
+    /** Result of executing a tool call. */
+    interface ToolCallResult {
+        call_id: string;
+        content: string;
+        is_error: boolean;
+    }
+    /** A tool definition provided to the model. */
+    interface ToolDefinition {
+        name: string;
+        description?: string;
+        input_schema: string;
+    }
+    /** Token usage statistics. */
+    interface Usage {
+        input_tokens: bigint;
+        output_tokens: bigint;
+    }
+}
+/** Types generated from the `agent` WIT interface. */
+export declare namespace agent {
+    /** A response generated by the agent for the user. */
+    interface Response {
+        /** The text output (may be a streaming delta or a complete reply). */
+        text: string;
+        /** True if this is the final response in the turn. */
+        is_final: boolean;
+        /** Session ID for multi-session attribution. */
+        session_id: string;
+    }
+    /**
+     * Notification that the active session has changed (e.g. cleared,
+     * branched, restored). Uplinks use this to refresh their view.
+     */
+    interface SessionChanged {
+        /** The session ID that is now active. */
+        session_id: string;
+        /** Optional ID of the session that was previously active. */
+        previous_session_id?: string;
+        /** Reason for the change (e.g. "clear", "restore", "branch"). */
+        reason: string;
+    }
+}
+/** Types generated from the `approval` WIT interface. */
+export declare namespace approval {
+    /** An interceptor or capsule request for human authorization. */
+    interface Required {
+        /** Correlation ID matching the response. */
+        request_id: string;
+        /** The action being requested (e.g. `"git push"`). */
+        action: string;
+        /** The resource target (e.g. full command string). */
+        target_resource: string;
+        /** Justification shown to the user. */
+        reason: string;
+    }
+    /** Response to an approval request. */
+    interface Response {
+        /** Must match the `request-id` from the originating request. */
+        request_id: string;
+        /**
+         * The user's decision (e.g. `"approve"`, `"deny"`,
+         * `"approve_session"`, `"approve_always"`, `"allowance"`).
+         */
+        decision: string;
+        /** Optional reason for the decision. */
+        reason?: string;
+    }
+}
+/** Types generated from the `client` WIT interface. */
+export declare namespace client {
+    /** A client has connected to an uplink. */
+    interface Connect {
+        /** Optional client identifier (e.g. process name + PID). */
+        client_id?: string;
+    }
+    /** A client is disconnecting gracefully. */
+    interface Disconnect {
+        /** Optional reason for disconnection (e.g. "quit", "timeout"). */
+        reason?: string;
+    }
+}
+/** Types generated from the `context` WIT interface. */
+export declare namespace context {
+    /** Request to compact messages within a token budget. */
+    interface CompactRequest {
+        session_id: string;
+        messages: types.Message[];
+        max_tokens: bigint;
+        target_tokens: bigint;
+    }
+    /** Result of compaction. */
+    interface CompactResponse {
+        messages: types.Message[];
+        compacted: boolean;
+        messages_removed: number;
+        strategy: string;
+    }
+    /** Request to estimate token count for messages. */
+    interface EstimateRequest {
+        messages: types.Message[];
+    }
+    /** Token count estimate. */
+    interface EstimateResponse {
+        estimated_tokens: bigint;
+    }
+    /** Hook payload sent before compaction (plugins can influence). */
+    interface BeforeCompactionHook {
+        session_id: string;
+        messages: types.Message[];
+        message_count: number;
+        estimated_tokens: bigint;
+        max_tokens: bigint;
+        response_topic: string;
+    }
+    /** Plugin response to before-compaction hook. */
+    interface BeforeCompactionHookResponse {
+        skip?: boolean;
+        pinned_message_ids: string[];
+        custom_strategy?: string;
+    }
+    /** Notification after compaction completes. */
+    interface AfterCompactionEvent {
+        session_id: string;
+        messages_before: number;
+        messages_after: number;
+        tokens_before: bigint;
+        tokens_after: bigint;
+        strategy_used: string;
+    }
+}
+/** Types generated from the `elicit` WIT interface. */
+export declare namespace elicit {
+    /** A lifecycle hook is requesting user input. */
+    interface Request {
+        /** Correlation ID matching the response. */
+        request_id: string;
+        /** The capsule requesting input. */
+        capsule_id: string;
+        /** Field descriptor reusing the onboarding schema. */
+        field: onboarding.Field;
+    }
+    /** Response to an elicit request. */
+    interface Response {
+        /** Must match the `request-id` from the originating request. */
+        request_id: string;
+        /** The user's input. Absent if the user cancelled. */
+        value?: string;
+        /** For `array`-type fields, the collected items. */
+        values?: string[];
+    }
+}
+/** Types generated from the `hook` WIT interface. */
+export declare namespace hook {
+    /** Lifecycle events emitted by the kernel. */
+    type LifecycleEvent = "session_created" | "session_ended" | "tool_call_started" | "tool_call_completed" | "tool_result_persisting" | "message_received" | "message_sending" | "message_sent" | "sub_agent_spawned" | "sub_agent_completed" | "sub_agent_failed" | "sub_agent_cancelled" | "context_compaction_started" | "context_compaction_completed" | "kernel_started" | "kernel_shutdown";
+    /** Merged result from hook fan-out. */
+    interface HookResult {
+        /** Whether the operation should be skipped. */
+        skip?: boolean;
+        /** Merged data from interceptor responses (opaque JSON). */
+        data?: string;
+    }
+}
+/** Types generated from the `llm` WIT interface. */
+export declare namespace llm {
+    /**
+     * Request asking an LLM-provider capsule to describe itself.
+     * Topic: `llm.v1.request.describe`. The registry capsule fans this
+     * out to discover available providers and their per-provider
+     * request / stream topics.
+     */
+    interface DescribeRequest {
+        /**
+         * Correlation ID for the response. The provider replies on
+         * `llm.v1.response.describe.<correlation-id>`.
+         */
+        correlation_id: string;
+    }
+    /**
+     * Provider self-description response.
+     * Topic: `llm.v1.response.describe.<correlation-id>`.
+     */
+    interface DescribeResponse {
+        /** Must match the `correlation-id` from the originating request. */
+        correlation_id: string;
+        /**
+         * Provider entries the capsule offers (one capsule may expose
+         * multiple models — e.g. an OpenAI-compatible front-end serving
+         * several model IDs).
+         */
+        providers: registry.ProviderEntry[];
+    }
+    /** Request to generate a response. */
+    interface GenerateRequest {
+        request_id: string;
+        model: string;
+        messages: types.Message[];
+        tools: types.ToolDefinition[];
+        /** System prompt. */
+        system: string;
+    }
+    /** A streaming event from the provider. */
+    type StreamEvent = {
+        tag: "text_delta";
+        value: string;
+    } | {
+        tag: "tool_call_start";
+        value: ToolCallStartEvent;
+    } | {
+        tag: "tool_call_delta";
+        value: ToolCallDeltaEvent;
+    } | {
+        tag: "tool_call_end";
+        value: ToolCallEndEvent;
+    } | {
+        tag: "reasoning_delta";
+        value: string;
+    } | {
+        tag: "usage";
+        value: types.Usage;
+    } | {
+        tag: "done";
+    } | {
+        tag: "error";
+        value: string;
+    };
+    interface ToolCallStartEvent {
+        id: string;
+        name: string;
+    }
+    interface ToolCallDeltaEvent {
+        id: string;
+        args_delta: string;
+    }
+    interface ToolCallEndEvent {
+        id: string;
+    }
+    /** Final (non-streaming) response. */
+    interface GenerateResponse {
+        message: types.Message;
+        has_tool_calls: boolean;
+        stop_reason: StopReason;
+        usage: types.Usage;
+    }
+    type StopReason = "end_turn" | "max_tokens" | "tool_use" | "stop_sequence";
+}
+/** Types generated from the `onboarding` WIT interface. */
+export declare namespace onboarding {
+    /** A capsule needs environment variables to be provided by the user. */
+    interface Required {
+        /** The ID of the capsule requiring onboarding. */
+        capsule_id: string;
+        /** Rich field descriptors for each missing env var. */
+        fields: Field[];
+    }
+    /** A field descriptor for capsule onboarding. */
+    interface Field {
+        /** The environment variable key. */
+        key: string;
+        /** The prompt shown to the user. */
+        prompt: string;
+        /** Optional description for additional context. */
+        description?: string;
+        /** The input type for this field. */
+        field_type: FieldType;
+        /** Optional default value. */
+        default?: string;
+        /** Placeholder hint text shown when the input is empty (e.g. `"sk-..."`). */
+        placeholder?: string;
+    }
+    /** The type of input expected for an onboarding field. */
+    type FieldType = {
+        tag: "text";
+    } | {
+        tag: "secret";
+    } | {
+        tag: "choice";
+        value: string[];
+    } | {
+        tag: "array";
+    };
+}
+/** Types generated from the `prompt` WIT interface. */
+export declare namespace prompt {
+    /** Request to assemble a prompt for LLM generation. */
+    interface AssembleRequest {
+        messages: types.Message[];
+        system_prompt: string;
+        request_id: string;
+        model: string;
+        provider: string;
+        session_id?: string;
+    }
+    /** Assembled prompt ready for LLM. */
+    interface AssembleResponse {
+        system_prompt: string;
+        user_context_prefix: string;
+        request_id: string;
+        session_id?: string;
+        /** Collected tool schemas from tool-providing capsules. */
+        tools: types.ToolDefinition[];
+        /** Session conversation history messages. */
+        messages: types.Message[];
+    }
+    /** Hook payload sent before prompt build (plugins inject context). */
+    interface BeforeBuildHook {
+        messages: types.Message[];
+        system_prompt: string;
+        request_id: string;
+        model: string;
+        provider: string;
+        response_topic: string;
+    }
+    /** Plugin response to before-build hook. */
+    interface BeforeBuildHookResponse {
+        prepend_system_context?: string;
+        append_system_context?: string;
+        system_prompt?: string;
+        prepend_context?: string;
+    }
+    /** Notification after prompt is built. */
+    interface AfterBuildEvent {
+        system_prompt: string;
+        user_context_prefix: string;
+        request_id: string;
+    }
+}
+/** Types generated from the `registry` WIT interface. */
+export declare namespace registry {
+    /** An available LLM provider entry. */
+    interface ProviderEntry {
+        /** Model ID (e.g. "gpt-5.4", "claude-sonnet-4-20250514"). */
+        id: string;
+        /** Human-readable description. */
+        description: string;
+        /** IPC topic to publish LLM requests to. */
+        request_topic: string;
+        /** IPC topic the provider streams responses on. */
+        stream_topic: string;
+        /** Model capabilities (e.g. "text", "vision", "tools"). */
+        capabilities: string[];
+        /** Provider's context window size in tokens. */
+        context_window?: bigint;
+        /** Provider's max output tokens per request. */
+        max_output_tokens?: bigint;
+    }
+    /** A single option in a selection picker. */
+    interface SelectionOption {
+        /** Machine-readable identifier sent back on the callback. */
+        id: string;
+        /** Human-readable label shown in the picker. */
+        label: string;
+        /** Optional description shown alongside the label. */
+        description?: string;
+    }
+    /**
+     * Capsule asking the user to choose from a set of options. Used by
+     * the registry to drive the LLM-provider picker UI in the TUI.
+     * Topic: `registry.v1.selection.required`.
+     */
+    interface SelectionRequired {
+        /** Correlation ID for the callback. */
+        request_id: string;
+        /** Title or prompt shown above the list. */
+        title: string;
+        /** The selectable options. */
+        options: SelectionOption[];
+        /** IPC topic to publish the user's choice back on. */
+        callback_topic: string;
+    }
+    /**
+     * User's selection sent back to the requesting capsule.
+     * Topic: `registry.v1.selection.callback` (or the `callback-topic`
+     * declared in the matching `selection-required`).
+     */
+    interface SelectionCallback {
+        /**
+         * Must match the `request-id` from the originating
+         * `selection-required`.
+         */
+        request_id: string;
+        /** `id` of the chosen `selection-option`. */
+        selected_id: string;
+    }
+}
+/** Types generated from the `session` WIT interface. */
+export declare namespace session {
+    /** Request to fetch conversation history. */
+    interface GetMessagesRequest {
+        session_id: string;
+        correlation_id: string;
+        append_before_read?: types.Message[];
+    }
+    /** Response containing conversation history. */
+    interface GetMessagesResponse {
+        correlation_id: string;
+        messages: types.Message[];
+    }
+    /** Request to clear a session and start fresh. */
+    interface ClearRequest {
+        session_id: string;
+        correlation_id: string;
+    }
+    /** Response confirming session cleared. */
+    interface ClearResponse {
+        correlation_id: string;
+        new_session_id: string;
+        old_session_id: string;
+    }
+    /** Fire-and-forget append to conversation history. */
+    interface AppendRequest {
+        session_id: string;
+        messages: types.Message[];
+    }
+    /**
+     * Broadcast notification that a session was cleared. Distinct from
+     * `clear-request`/`clear-response` (the request/response pair the
+     * session capsule handles): this is a fan-out event the agent loop
+     * publishes after a successful clear so unrelated capsules can drop
+     * any per-session ephemeral state. Topic: `session.v1.clear`.
+     */
+    interface SessionCleared {
+        /** Session ID that was cleared. */
+        session_id: string;
+    }
+}
+/** Types generated from the `spark` WIT interface. */
+export declare namespace spark {
+    /** Request to build the agent's system prompt. */
+    interface BuildRequest {
+        workspace_root: string;
+        session_id?: string;
+    }
+    /** Response with the assembled system prompt. */
+    interface BuildResponse {
+        prompt: string;
+        session_id?: string;
+    }
+}
+/** Types generated from the `system` WIT interface. */
+export declare namespace system {
+    /**
+     * Published once after every capsule has reported ready, signalling
+     * that the agent stack is fully online. Topic: `astrid.v1.capsules_loaded`.
+     */
+    interface CapsulesLoaded {
+        /** IDs of every capsule that successfully loaded. */
+        capsule_ids: string[];
+    }
+    /**
+     * Periodic kernel watchdog tick, used by long-lived capsules to age
+     * out stale state (timeouts, abandoned correlations, etc.).
+     * Topic: `astrid.v1.watchdog.tick`.
+     */
+    interface WatchdogTick {
+        /** Wall-clock time of the tick (UNIX epoch milliseconds). */
+        timestamp_ms: bigint;
+    }
+    /**
+     * Warning emitted when a subscriber falls behind and the bus had to
+     * drop messages. Subscribers can use this as a signal to drain or
+     * resubscribe. Topic: `astrid.v1.event_bus.lagged`.
+     */
+    interface EventBusLagged {
+        /** Topic that lagged. */
+        topic: string;
+        /** Number of messages dropped. */
+        dropped: bigint;
+    }
+    /**
+     * Cooperative restart signal — the kernel asks long-lived capsules
+     * to flush ephemeral state and re-arm. Topic: `system.v1.lifecycle.restart`.
+     */
+    interface LifecycleRestart {
+        /** Reason for the restart (e.g. `"config-reload"`, `"upgrade"`). */
+        reason: string;
+    }
+    /**
+     * A slash-command typed by a human in an uplink. The CLI capsule
+     * publishes this when the user enters `/<command> [args]`. Routed
+     * to the capsule that registered the command name via its manifest.
+     * Topic: `cli.v1.command.execute`.
+     */
+    interface CommandExecute {
+        /** The command name (without the leading slash). */
+        name: string;
+        /** JSON-encoded arguments (parsed by the receiving capsule). */
+        arguments: string;
+        /** Session ID the command was issued in. */
+        session_id: string;
+    }
+}
+/** Types generated from the `tool` WIT interface. */
+export declare namespace tool {
+    /** Request to cancel in-flight tool executions. */
+    interface CancelRequest {
+        call_ids: string[];
+    }
+    /**
+     * Request asking a tool-providing capsule to enumerate its tools.
+     * Topic: `tool.v1.request.describe`. Empty payload — every responder
+     * returns its full tool list. Routed by the SDK macro from
+     * `#[astrid::tool(...)]` attributes.
+     */
+    interface DescribeRequest {
+        /**
+         * Correlation ID for the response. The capsule replies on
+         * `tool.v1.response.describe.<correlation-id>`.
+         */
+        correlation_id: string;
+    }
+    /**
+     * Response listing the tools a capsule provides.
+     * Topic: `tool.v1.response.describe.<correlation-id>`.
+     */
+    interface DescribeResponse {
+        /** Must match the `correlation-id` from the originating request. */
+        correlation_id: string;
+        /** The capsule's exposed tools. */
+        tools: types.ToolDefinition[];
+    }
+}
+/** Types generated from the `user` WIT interface. */
+export declare namespace user {
+    /** A prompt typed by a human via an uplink. */
+    interface Prompt {
+        /** The raw text input. */
+        text: string;
+        /** Session ID for conversation continuity. Defaults to `"default"`. */
+        session_id: string;
+        /**
+         * Optional extra context (JSON-encoded) — e.g. attachments,
+         * metadata, or per-turn flags the uplink wants to forward.
+         */
+        context?: string;
+    }
+}
+/** Types generated from the `users` WIT interface. */
+export declare namespace users {
+    /**
+     * Multi-tenant request envelope.
+     *
+     * Carries provenance ("which uplink, on behalf of which end-user")
+     * and a correlation token so the originating uplink can match the
+     * response back to the inflight request among many concurrent
+     * end-users on a single principal.
+     *
+     * Pending the broader admin-API correlation convention (kernel
+     * issue #748), `source` lives on this interface; once that
+     * convention formalizes a shared envelope, this record migrates
+     * to the shared location and the records below import it instead.
+     */
+    interface Source {
+        /**
+         * Originating uplink capsule — e.g. `"cli"`, `"sphere"`,
+         * `"discord"`, `"telegram"`. Identifies the capsule making
+         * the request (for audit and routing); distinct from
+         * `frontend-link.platform`, which identifies the external
+         * service being linked.
+         */
+        uplink: string;
+        /**
+         * AstridUserId of the requester when known. `None` for
+         * system flows or pre-login pairing requests.
+         */
+        user_id?: string;
+        /**
+         * Correlation token. The requester subscribes to the response
+         * topic and filters incoming responses by this string.
+         */
+        correlation_id: string;
+    }
+    /**
+     * Canonical Astrid user identity.
+     *
+     * One record per human within the principal's user directory.
+     * `id` is the stable UUID — every `frontend-link` points at this.
+     */
+    interface AstridUser {
+        /**
+         * UUID v4 string (lowercase, hyphenated). Stable for the
+         * lifetime of the user; never reused.
+         */
+        id: string;
+        /**
+         * Optional ed25519 public key (32 bytes raw). Set via
+         * `set-public-key`; used by future verification flows.
+         */
+        public_key?: number[];
+        /**
+         * Operator/canonical Astrid-side display name. Mutable via
+         * `set-display-name`. Distinct from any platform-side name.
+         */
+        display_name?: string;
+        /** Creation timestamp, RFC 3339 string. */
+        created_at: string;
+    }
+    /**
+     * A platform-to-Astrid-user identity link.
+     *
+     * Composite key: `(platform, platform-instance?, platform-user-id)`.
+     * Exactly one link may exist per triple; relinking overwrites.
+     */
+    interface FrontendLink {
+        /**
+         * Normalized platform name (lowercased, trimmed) —
+         * e.g. `"discord"`, `"telegram"`, `"nostr"`, `"slack"`,
+         * `"matrix"`, `"email"`, `"x"`, `"github"`.
+         */
+        platform: string;
+        /**
+         * Optional platform instance for federated / multi-tenant
+         * platforms: Slack workspace, IRC network, XMPP server,
+         * Mattermost instance. `None` for globally-scoped platforms
+         * (Discord, Telegram, X) and for federated platforms whose
+         * identifier already embeds the homeserver in the user-id
+         * (Matrix `@alice:server.org`, Mastodon `@a@server.social`).
+         */
+        platform_instance?: string;
+        /**
+         * Platform-specific stable opaque user identifier
+         * (Discord snowflake, Telegram int64, Slack `U...`, Nostr
+         * npub, email address, E.164 phone). Never the user's
+         * mutable handle.
+         */
+        platform_user_id: string;
+        /** The Astrid user UUID this platform identity maps to. */
+        astrid_user_id: string;
+        /**
+         * When this link was created (RFC 3339). Refreshed on
+         * upsert relink.
+         */
+        linked_at: string;
+        /**
+         * How this link was established — `"admin"`, `"system"`,
+         * `"chat_command"`, `"passkey"`, `"self_declared"`, etc.
+         * Recorded for audit. Free-form string.
+         */
+        method: string;
+        /**
+         * Platform's *global* display name at link time —
+         * e.g. Discord global username `"alice"`, Telegram
+         * `@alice`, X handle. Mutable: re-link to refresh.
+         * Distinct from any per-context override
+         * (see `context-identity`) and from `astrid-user.display-name`
+         * (the operator-set canonical Astrid name).
+         */
+        display_name?: string;
+    }
+    /**
+     * Per-context display-name overlay on a `frontend-link`.
+     *
+     * One row per `(platform, platform-instance?, platform-user-id, context-id)`
+     * tuple. The capsule does NOT parse `context-id`; uplinks define
+     * per-platform schemes. Common conventions:
+     *
+     *   - Discord per-guild nickname:        `context-id = "guild:{guild-id}"`
+     *   - Matrix per-room display name:      `context-id = "room:{room-id}"`
+     *   - Slack per-channel profile:         `context-id = "channel:{channel-id}"`
+     *                                         (workspace lives in `platform-instance`)
+     *   - Mattermost per-team:               `context-id = "team:{team-id}"`
+     *   - Single-context platforms (X, SMS): no rows ever created
+     *
+     * Per-context attributes beyond `display-name` (roles, custom
+     * fields, preferences) intentionally do NOT live here. They
+     * belong in memory or a future authz capsule.
+     */
+    interface ContextIdentity {
+        platform: string;
+        platform_instance?: string;
+        platform_user_id: string;
+        /** Opaque per-platform context key. */
+        context_id: string;
+        /** What this user is called *in this context*. */
+        display_name: string;
+        /** Last update timestamp (RFC 3339). */
+        updated_at: string;
+    }
+    /**
+     * Resolve a platform identity to an Astrid user, optionally
+     * scoped to a context for display-name layering.
+     * Topic: `users.v1.resolve.request`.
+     */
+    interface ResolveRequest {
+        source: Source;
+        platform: string;
+        platform_instance?: string;
+        platform_user_id: string;
+        /**
+         * Optional context. When set, the response's `display-name`
+         * uses the per-context override if one exists. When None,
+         * only the link-global and canonical fallbacks apply.
+         */
+        context_id?: string;
+    }
+    /**
+     * Response for resolve.
+     * Topic: `users.v1.resolve.response`.
+     *
+     * A clean "no link exists" is `user = none` with `error = none`.
+     * Validation or storage failures populate `error` and leave the
+     * other success fields empty.
+     */
+    interface ResolveResponse {
+        correlation_id: string;
+        user?: AstridUser;
+        /**
+         * The right name to address this user. Resolution order
+         * (first non-empty wins):
+         *   1. `context-identity.display-name` (if `context-id` was
+         *      provided in the request and an override exists)
+         *   2. `frontend-link.display-name` (the platform-side name)
+         *   3. `astrid-user.display-name` (the canonical Astrid name)
+         * `None` if none of the three layers carry a name.
+         */
+        display_name?: string;
+        /**
+         * Which layer produced `display-name`. One of `"context"`,
+         * `"link"`, `"canonical"`. `None` when `display-name` is `None`.
+         */
+        display_name_source?: string;
+        error?: string;
+    }
+    /**
+     * Link a platform identity to an existing Astrid user. Upsert
+     * semantics: an existing link for the same
+     * `(platform, platform-instance?, platform-user-id)` is overwritten.
+     * Topic: `users.v1.link.request`.
+     */
+    interface LinkRequest {
+        source: Source;
+        platform: string;
+        platform_instance?: string;
+        platform_user_id: string;
+        /** Target Astrid user UUID. Must already exist. */
+        astrid_user_id: string;
+        /** Audit string — how this link was established. */
+        method: string;
+        /**
+         * Optional platform-side global display name at link time.
+         * Stored on the resulting `frontend-link` for later
+         * resolution / display.
+         */
+        display_name?: string;
+    }
+    /**
+     * Response for link.
+     * Topic: `users.v1.link.response`.
+     */
+    interface LinkResponse {
+        correlation_id: string;
+        link?: FrontendLink;
+        error?: string;
+    }
+    /**
+     * Remove a platform link. Also clears any
+     * `context-identity` overlays attached to it (cascading).
+     * Topic: `users.v1.unlink.request`.
+     */
+    interface UnlinkRequest {
+        source: Source;
+        platform: string;
+        platform_instance?: string;
+        platform_user_id: string;
+    }
+    /**
+     * Response for unlink.
+     * Topic: `users.v1.unlink.response`.
+     */
+    interface UnlinkResponse {
+        correlation_id: string;
+        /**
+         * `true` if a link existed and was removed; `false` for a
+         * no-op delete (link was already absent).
+         */
+        removed: boolean;
+        error?: string;
+    }
+    /**
+     * Create a new Astrid user.
+     * Topic: `users.v1.create.request`.
+     */
+    interface CreateRequest {
+        source: Source;
+        /**
+         * Optional canonical display name. Rejected if it contains
+         * `/` or `\0`.
+         */
+        display_name?: string;
+    }
+    /**
+     * Response for create.
+     * Topic: `users.v1.create.response`.
+     */
+    interface CreateResponse {
+        correlation_id: string;
+        user?: AstridUser;
+        error?: string;
+    }
+    /**
+     * Change an `AstridUser`'s canonical `display-name` without
+     * rotating the UUID or breaking any links.
+     * Topic: `users.v1.set_display_name.request`.
+     *
+     * `display-name = None` clears the name. To leave it unchanged,
+     * don't issue the request.
+     */
+    interface SetDisplayNameRequest {
+        source: Source;
+        astrid_user_id: string;
+        display_name?: string;
+    }
+    /**
+     * Response for set-display-name.
+     * Topic: `users.v1.set_display_name.response`.
+     */
+    interface SetDisplayNameResponse {
+        correlation_id: string;
+        user?: AstridUser;
+        error?: string;
+    }
+    /**
+     * Set or clear an `AstridUser`'s `public-key` without rotating
+     * the UUID.
+     * Topic: `users.v1.set_public_key.request`.
+     *
+     * `public-key = None` clears the key.
+     */
+    interface SetPublicKeyRequest {
+        source: Source;
+        astrid_user_id: string;
+        public_key?: number[];
+    }
+    /**
+     * Response for set-public-key.
+     * Topic: `users.v1.set_public_key.response`.
+     */
+    interface SetPublicKeyResponse {
+        correlation_id: string;
+        user?: AstridUser;
+        error?: string;
+    }
+    /**
+     * List every platform link for one Astrid user.
+     * Topic: `users.v1.links.request`.
+     */
+    interface LinksRequest {
+        source: Source;
+        astrid_user_id: string;
+    }
+    /**
+     * Response for links.
+     * Topic: `users.v1.links.response`.
+     */
+    interface LinksResponse {
+        correlation_id: string;
+        links: FrontendLink[];
+        error?: string;
+    }
+    /**
+     * Fetch a user record by UUID.
+     * Topic: `users.v1.get.request`.
+     */
+    interface GetRequest {
+        source: Source;
+        astrid_user_id: string;
+    }
+    /**
+     * Response for get.
+     * Topic: `users.v1.get.response`.
+     */
+    interface GetResponse {
+        correlation_id: string;
+        user?: AstridUser;
+        error?: string;
+    }
+    /**
+     * Delete a user, every link pointing at it, and every
+     * per-context overlay tied to those links.
+     * Idempotent — deleting an absent UUID returns `deleted = false`.
+     * Topic: `users.v1.delete.request`.
+     */
+    interface DeleteRequest {
+        source: Source;
+        astrid_user_id: string;
+    }
+    /**
+     * Response for delete.
+     * Topic: `users.v1.delete.response`.
+     */
+    interface DeleteResponse {
+        correlation_id: string;
+        /** `true` when a user record existed and was deleted. */
+        deleted: boolean;
+        error?: string;
+    }
+    /**
+     * List every user record in the principal's store. Paginated.
+     * Topic: `users.v1.list.request`.
+     */
+    interface ListRequest {
+        source: Source;
+        /**
+         * Cursor from a prior `list-response.next-cursor`. `None`
+         * on the first call.
+         */
+        cursor?: string;
+        /**
+         * Maximum users to return. `None` lets the capsule pick a
+         * sensible default (current impl: 100).
+         */
+        limit?: number;
+    }
+    /**
+     * Response for list.
+     * Topic: `users.v1.list.response`.
+     */
+    interface ListResponse {
+        correlation_id: string;
+        users: AstridUser[];
+        /**
+         * Pass back as `list-request.cursor` to get the next page.
+         * `None` when no more pages remain.
+         */
+        next_cursor?: string;
+        error?: string;
+    }
+    /**
+     * Set (or upsert) a per-context display-name override for a
+     * linked platform identity. The underlying `frontend-link` must
+     * already exist — context overlays cannot dangle.
+     * Topic: `users.v1.context.set.request`.
+     */
+    interface ContextSetRequest {
+        source: Source;
+        platform: string;
+        platform_instance?: string;
+        platform_user_id: string;
+        context_id: string;
+        display_name: string;
+    }
+    /**
+     * Response for context-set.
+     * Topic: `users.v1.context.set.response`.
+     */
+    interface ContextSetResponse {
+        correlation_id: string;
+        context_identity?: ContextIdentity;
+        error?: string;
+    }
+    /**
+     * Clear a per-context display-name override. Leaves the link
+     * itself and the global link-level display-name untouched.
+     * Topic: `users.v1.context.clear.request`.
+     */
+    interface ContextClearRequest {
+        source: Source;
+        platform: string;
+        platform_instance?: string;
+        platform_user_id: string;
+        context_id: string;
+    }
+    /**
+     * Response for context-clear.
+     * Topic: `users.v1.context.clear.response`.
+     */
+    interface ContextClearResponse {
+        correlation_id: string;
+        /**
+         * `true` if an overlay existed and was removed; `false` for
+         * a no-op clear.
+         */
+        removed: boolean;
+        error?: string;
+    }
+    /**
+     * Fetch the per-context override for one
+     * `(link, context-id)` pair. Useful when the caller wants the
+     * raw override without the `resolve`-style fallback chain.
+     * Topic: `users.v1.context.get.request`.
+     */
+    interface ContextGetRequest {
+        source: Source;
+        platform: string;
+        platform_instance?: string;
+        platform_user_id: string;
+        context_id: string;
+    }
+    /**
+     * Response for context-get.
+     * Topic: `users.v1.context.get.response`.
+     */
+    interface ContextGetResponse {
+        correlation_id: string;
+        context_identity?: ContextIdentity;
+        /**
+         * The same user resolved through the underlying link, when
+         * it exists. Saves the caller a separate `resolve` call.
+         */
+        astrid_user_id?: string;
+        error?: string;
+    }
+    /**
+     * List every context overlay attached to one Astrid user, across
+     * platforms and contexts. Paginated.
+     * Topic: `users.v1.context.list_for_user.request`.
+     */
+    interface ContextListForUserRequest {
+        source: Source;
+        astrid_user_id: string;
+        cursor?: string;
+        limit?: number;
+    }
+    /**
+     * Response for context-list-for-user.
+     * Topic: `users.v1.context.list_for_user.response`.
+     */
+    interface ContextListForUserResponse {
+        correlation_id: string;
+        contexts: ContextIdentity[];
+        next_cursor?: string;
+        error?: string;
+    }
+    /**
+     * List every user known in one specific context (e.g. every
+     * member of one Discord guild who has a per-guild nickname
+     * recorded). Returns the context overlay rows plus the resolved
+     * `astrid-user-id` for each, so the caller can build a member
+     * roster in one paginated call. Paginated.
+     * Topic: `users.v1.context.list_in_context.request`.
+     */
+    interface ContextListInContextRequest {
+        source: Source;
+        platform: string;
+        platform_instance?: string;
+        context_id: string;
+        cursor?: string;
+        limit?: number;
+    }
+    /** One row of the context-list-in-context response. */
+    interface ContextMember {
+        context_identity: ContextIdentity;
+        /**
+         * Resolved Astrid user UUID via the underlying link, when
+         * the link still exists. `None` indicates a stale overlay
+         * (link was unlinked but overlay wasn't cleared — the
+         * capsule cleans these on unlink, so this should be rare).
+         */
+        astrid_user_id?: string;
+    }
+    /**
+     * Response for context-list-in-context.
+     * Topic: `users.v1.context.list_in_context.response`.
+     */
+    interface ContextListInContextResponse {
+        correlation_id: string;
+        members: ContextMember[];
+        next_cursor?: string;
+        error?: string;
+    }
+}
+//# sourceMappingURL=contracts.d.ts.map