@on-mission/sdk 0.1.4 → 0.1.9

package/dist/index.d.ts

@@ -1,3 +1,862 @@
+import { FileRef, StagingProvenance, ToolCallInput } from '@mission/models';
+export { FileRef, FileRefStore, MAX_STAGING_UPLOAD_BYTES, StagingProvenance, Tool, ToolCallContext, ToolCallEnvelope, ToolCallInput, ToolFunction, ToolFunctionPermission, ToolKind, fileRefSchema } from '@mission/models';
+import { createTRPCProxyClient } from '@trpc/client';
+
+/**
+ * Skill Context
+ *
+ * Bootstrapped from environment variables injected by the Mission control plane
+ * when it starts the skill process inside the Daytona sandbox.
+ *
+ * See docs/technical/legacy/architecture/skills/architecture.md §4.5.
+ */
+type SkillContext = {
+    /** Mission control plane API base URL. */
+    apiUrl: string;
+    /** JWT scoped to this skill installation (for outbound API calls). */
+    skillToken: string;
+    /** Stable identifier for this skill installation (per-workspace). */
+    installationId: string;
+    /** Port assigned by the control plane for this skill's HTTP server. */
+    skillPort: number;
+};
+
+/**
+ * API Client
+ *
+ * Typed tRPC client for all SDK -> Mission gateway communication.
+ * The public SDK surface stays the same (`mission.auth.get()`, etc.),
+ * while transport details are centralized here.
+ *
+ * Transient-error retry: the fetch link below retries connection-level
+ * failures (ECONNREFUSED, socket hang up, ECONNRESET, ETIMEDOUT, generic
+ * `fetch failed` TypeError) and 5xx responses with jittered exponential
+ * backoff for up to ~60 seconds. This is essential at skill startup, when
+ * a sandbox can race the gateway's readiness — without it, a single
+ * transient miss kills the whole skill process and triggers a permanent
+ * connection disconnect via sandboxRestartWorkflow.
+ */
+
+type GatewayClient = ReturnType<typeof createTRPCProxyClient<GatewayRouter>>;
+type ApiClient = {
+    trpc: GatewayClient;
+    baseUrl: string;
+    setToken: (token: string) => void;
+    getToken: () => string;
+};
+
+/**
+ * Auth Module
+ *
+ * Unified interface for all authentication credentials.
+ * `mission.auth.get()` returns a single object containing:
+ *  - User-provided credentials (API keys, tokens, secrets from the connection form)
+ *  - OAuth token data (for managed auth providers like Google, Slack)
+ *
+ * Skill authors always call `auth.get()` regardless of auth type.
+ *
+ * For managed auth (Nango-backed), the SDK caches tokens and refreshes
+ * transparently. See docs/technical/legacy/architecture/skills/authentication.md.
+ *
+ * For custom auth, credentials are collected via a connection form
+ * defined in mission.json's `auth.credentials` schema.
+ *
+ * Transport: tRPC mutation/query via Mission gateway API.
+ */
+
+/**
+ * OAuth credentials returned for managed auth providers.
+ * The control plane handles token refresh (via Nango or equivalent).
+ */
+type OAuthCredentials = {
+    /** The current access token string. */
+    accessToken: string;
+    /** OAuth 1.0a access token secret. Only present for OAuth 1.0a providers. */
+    accessTokenSecret?: string;
+    /** OAuth 1.0a / app-level consumer key. Only present for OAuth 1.0a providers. */
+    consumerKey?: string;
+    /** OAuth 1.0a / app-level consumer secret. Only present for OAuth 1.0a providers. */
+    consumerSecret?: string;
+    /** When this token expires (Unix milliseconds). */
+    expiresAt: number;
+    /** Scopes that were granted. */
+    scopes: string[];
+    /** The provider identifier (e.g. 'google', 'slack'). */
+    provider: string;
+};
+/**
+ * The unified auth response.
+ *
+ * For custom auth (Sentry, Twilio, etc.):
+ *   { credentials: { authToken: 'sntrys_...', organization: 'my-org' } }
+ *
+ * For managed OAuth (Gmail, Slack, etc.):
+ *   { credentials: {}, oauth: { accessToken: 'ya29...', ... } }
+ *
+ * For mixed (future: OAuth + user-provided extras):
+ *   { credentials: { webhookSecret: '...' }, oauth: { accessToken: '...', ... } }
+ */
+type AuthCredentials = {
+    /** User-provided credential values from the connection form. */
+    credentials: Record<string, string>;
+    /** OAuth token data. Present when auth.type is "managed". */
+    oauth?: OAuthCredentials;
+};
+type AuthModule = {
+    /**
+     * Get all authentication data for this skill installation.
+     *
+     * Returns user-provided credentials (API keys, tokens from the
+     * connection form) and, for managed OAuth providers, a current
+     * access token that the SDK keeps refreshed.
+     *
+     * This is safe to call repeatedly — the SDK caches internally.
+     */
+    get: () => Promise<AuthCredentials>;
+};
+
+/**
+ * Config Module
+ *
+ * Fetches per-installation configuration from the control plane.
+ * Accepts optional defaults so skills always get a complete config
+ * object without manual merging.
+ *
+ * The control plane stores config per Connection. Values are set
+ * by the user in the App's settings UI (defined by configSchema in
+ * mission.json). The SDK merges platform values over provided defaults
+ * so the returned object is always complete.
+ *
+ * Transport: tRPC query via Mission gateway API.
+ *
+ * See docs/product/apps.md § App configuration state.
+ */
+
+type ConfigModule = {
+    /**
+     * Fetch the full configuration object for this skill installation.
+     *
+     * If `defaults` are provided, the SDK merges platform-stored values
+     * over them, so the result is always a complete `T` with no undefined
+     * fields. Without defaults, returns whatever the platform has stored.
+     *
+     * @example
+     * ```ts
+     * const config = await mission.config.get<GmailConfig>({
+     *   watchLabels: ['INBOX'],
+     *   maxResults: 20,
+     *   signatureLine: ''
+     * })
+     * // config is guaranteed to have all three fields
+     * ```
+     */
+    get: <T = Record<string, unknown>>(defaults?: Partial<T>) => Promise<T>;
+};
+
+/**
+ * Debug Logging — Local Development
+ *
+ * Writes structured logs to /tmp/mission-debug.log for visibility into
+ * event flow in local sandboxes where console.log isn't visible.
+ *
+ * Only active when DEBUG_MISSION_EVENTS=1 env var is set.
+ */
+declare const debugLog: (topic: string, message: string, data?: Record<string, unknown>) => void;
+declare const clearDebugLog: () => void;
+
+/**
+ * Files Module
+ *
+ * `mission.files` — the skill-facing seam for moving file bytes without ever
+ * routing them through the Mission platform, the model, the tool-call path, or
+ * any log.
+ *
+ * The contract:
+ *
+ *  - The model only ever holds a `FileRef` handle — a PLAIN object reference
+ *    `{store, key, filename, mimeType, sizeBytes}` — never bytes and never any
+ *    authority. The handle is not signed.
+ *  - The skill REDEEMS a `FileRef` for a read URL, never constructs one.
+ *    References are produced server-side by a tool running where authz exists.
+ *    The skill presents `{store, key}` to the gateway, which RE-AUTHORIZES the
+ *    read server-side (first-party gate + workspace/object BOLA pin from the key
+ *    grammar) and mints a signed GCS read URL.
+ *  - Bytes move skill ⇄ GCS DIRECTLY over short-lived signed URLs. The platform
+ *    NEVER proxies bytes.
+ *  - A signed URL is a LIVE CREDENTIAL. It is redeemed once and discarded —
+ *    never logged, never returned in a tool result, never put in model context.
+ *
+ * Authz lives entirely in the gateway endpoint (`skill.redeemFileRef`). The
+ * skill presents a reference; the platform re-authorizes and decides. Reads
+ * only — no write path exists (a write over a caller-named key was rejected by
+ * the security review; inbound bytes use the platform-allocates-key
+ * `stageInboundBytes` flow).
+ *
+ * Transport for the redeem verb: tRPC mutation via the Mission gateway API.
+ * Transport for the byte transfer: a plain `fetch` straight to GCS.
+ */
+
+/**
+ * Thrown when an external byte transfer (a GCS GET/PUT) does not complete within
+ * its deadline. Distinct from an HTTP error so callers can tell a hung
+ * connection from a 4xx/5xx. A hung byte transfer otherwise wedges the sandbox
+ * holding the full attachment buffer until the max_duration kill — the dominant
+ * trigger for the response-lost double-send.
+ */
+declare class FileTransferTimeoutError extends Error {
+    constructor(operation: string);
+}
+type FilesModule = {
+    /**
+     * Redeem a `FileRef` for a signed read URL. Presents `{store, key}` to the
+     * gateway, which re-authorizes the read server-side. The returned `readUrl` is
+     * a live credential — redeem and discard. Prefer `getBytes` unless you need to
+     * drive the GET yourself.
+     */
+    redeemForRead: (ref: FileRef) => Promise<{
+        readUrl: string;
+    }>;
+    /**
+     * Download the bytes a `ref` points at. Wraps `redeemForRead` + the GCS GET
+     * inside the SDK so the signed URL never leaves this module. Bytes stream
+     * GCS → skill; the platform never sees them.
+     */
+    getBytes: (ref: FileRef) => Promise<Buffer>;
+    /**
+     * Stage INBOUND bytes (e.g. an email attachment a skill just downloaded) and
+     * obtain a read `FileRef` over the result — the SAFE, platform-allocates-key
+     * flow.
+     *
+     * The skill NEVER names a storage key. The platform allocates a server-derived,
+     * content-addressed key, hands back a signed PUT URL + the plain allocated key;
+     * the SDK streams the bytes straight to GCS, then presents that key back to mint
+     * the read `FileRef`. The mint is gated server-side by CONTENT SCREENING — the
+     * platform reads the bytes back, screens them, and only mints on pass; on a
+     * screening flag/outage this REJECTS (throws) and no handle is produced.
+     *
+     * Provenance is REQUIRED — it is stamped onto the staged object so a
+     * downstream device-apply / library-promote can show where the bytes came
+     * from. Bytes move skill → GCS over the signed URL; they never enter a tool
+     * result, the model context, or any log.
+     */
+    stageInboundBytes: (input: {
+        bytes: Buffer | Uint8Array;
+        contentType: string;
+        filename: string;
+        provenance: StagingProvenance;
+    }) => Promise<FileRef>;
+};
+
+/**
+ * Shared email-attachment helpers for file-attaching skills (Gmail today;
+ * Outlook reuses these for its own slice). Two provider-agnostic concerns live
+ * here so neither skill hand-rolls them:
+ *
+ *   1. Redeeming `FileRef` attachments to bytes, with a per-provider size cap
+ *      enforced BEFORE any bytes move, and sequential (bounded-concurrency)
+ *      streaming so the base64 memory peak stays bounded.
+ *   2. RFC 2822 `multipart/mixed` MIME assembly (text/plain + optional
+ *      text/html body, plus base64 attachment parts).
+ *
+ * Provider-specific framing (Gmail's base64url raw + resumable-upload threshold;
+ * Outlook's Graph upload session) stays in each skill's client — only the
+ * generic, reusable pieces are here.
+ *
+ * Bytes NEVER enter the model context, the tool-call/result JSON, or any log.
+ * The model holds only the small `FileRef` handle; the bytes are redeemed inside
+ * the SDK (`mission.files.getBytes`), assembled into MIME, and handed to the
+ * provider.
+ */
+
+/** A redeemed attachment: the readable triple + its bytes. */
+type RedeemedAttachment = {
+    filename: string;
+    mimeType: string;
+    bytes: Buffer;
+};
+/**
+ * Per-provider attachment limits. `maxTotalRawBytes` is the cap on the SUM of
+ * raw (pre-base64) attachment bytes — enforced before any byte moves. Gmail's
+ * documented limit is ~25 MB AFTER base64 encoding, which is ~18 MB of raw
+ * bytes (base64 inflates ~4/3). The error message degrades to "send a link".
+ */
+type AttachmentLimits = {
+    /** Provider display name for the error message (e.g. "Gmail"). */
+    provider: string;
+    /** Cap on the sum of raw attachment bytes, pre-base64. */
+    maxTotalRawBytes: number;
+};
+type MimeBodyParts = {
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    /** Plain-text body. */
+    text: string;
+    /** Optional HTML body. */
+    html?: string;
+    inReplyTo?: string;
+    references?: string;
+    /** Extra headers (e.g. a deterministic `Message-ID` for idempotency). */
+    extraHeaders?: Record<string, string>;
+};
+/** The identity that derives a send's deterministic Message-ID. Recipients are
+ * order-insensitive (sorted) so the same logical send hashes identically across
+ * retries; the per-attachment content sha256s fold the attachment set in. */
+type SendMessageIdInput = {
+    workspaceId: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    body: string;
+    html?: string;
+    attachments: RedeemedAttachment[];
+};
+/** The deterministic Message-ID for a send, in both forms a provider needs. */
+type SendMessageId = {
+    /** The bare sha256 hex (e.g. for Gmail's `rfc822msgid:<hash>@mission.send`). */
+    hash: string;
+    /** The framed `<hash@mission.send>` header value (Message-ID / internetMessageId). */
+    messageId: string;
+};
+/**
+ * The shared email-attachment domain. One object, dotted access — the loose
+ * procedure surface is collapsed here so a send tool reaches every reusable
+ * piece (caps, ref parsing, redemption, MIME assembly, header encoding, and the
+ * deterministic Message-ID kernel) through a single import.
+ */
+declare const EmailAttachments: {
+    limits: {
+        gmail: AttachmentLimits;
+        outlook: AttachmentLimits;
+    };
+    parseRefs: (value: unknown) => FileRef[];
+    assertWithinCap: (refs: FileRef[], limits: AttachmentLimits) => void;
+    redeem: (files: FilesModule, refs: FileRef[], limits: AttachmentLimits) => Promise<RedeemedAttachment[]>;
+    assembleMime: (input: MimeBodyParts, attachments: RedeemedAttachment[]) => string;
+    sendMessageId: (input: SendMessageIdInput) => SendMessageId;
+    header: {
+        encode: (value: string, field: string) => string;
+        assertNoCRLF: (value: string, field: string) => string;
+    };
+};
+
+type SkillEvent = {
+    eventType: string;
+    payload: Record<string, unknown>;
+    platform: string;
+    tenantId: string;
+};
+type EventHandler = (event: SkillEvent) => Promise<void> | void;
+type EventHandlerRegistry = {
+    on: (eventName: string, handler: EventHandler) => void;
+    dispatch: (event: SkillEvent) => Promise<{
+        handled: boolean;
+    }>;
+    hasHandlers: () => boolean;
+};
+
+/**
+ * Ingress Module
+ *
+ * Handles inbound traffic from external services (webhooks, WebSocket streams).
+ * Skills register handlers per endpoint name; the HTTP server routes traffic
+ * to them.
+ *
+ * Traffic flow (HTTP-native, no WebSocket control plane):
+ *
+ *   Tool calls from Mission API:
+ *     Mission API → Daytona Standard Preview URL → HTTP server → tool handler
+ *
+ *   Webhooks from external services:
+ *     External service → Daytona Signed Preview URL → HTTP server → ingress handler
+ *
+ *   WebSocket streams (e.g., Twilio media):
+ *     External service → Daytona Signed Preview URL → HTTP server → stream handler
+ *
+ * The HTTP server (started by mission.connect()) dispatches to the registered
+ * handler and sends the response back as a standard HTTP response.
+ *
+ * For WebSocket endpoints: event-based model (connect, message, disconnect).
+ * WebSocket support depends on Daytona Preview URL proxy supporting upgrades.
+ *
+ * Endpoint names are chosen by the skill author at registration time.
+ * There is no need to pre-declare them in mission.json — the SDK registers
+ * them dynamically and reports them to the control plane at ready().
+ *
+ * See docs/technical/legacy/architecture/skills/architecture.md §4.4.
+ * See docs/technical/legacy/architecture/skills/sandbox-runtime.md §2-3.
+ */
+
+type IngressRequest = {
+    /** HTTP method (GET, POST, etc.). */
+    method: string;
+    /** Request path (relative to the ingress endpoint). */
+    path: string;
+    /** Request headers (lowercased keys). */
+    headers: Record<string, string>;
+    /** Raw request body as a string. */
+    body: string;
+    /** Parsed query parameters. */
+    query: Record<string, string>;
+};
+type IngressResponse = {
+    /** HTTP status code. */
+    status: number;
+    /** Response headers. */
+    headers?: Record<string, string>;
+    /** Response body. */
+    body?: string;
+};
+type IngressHandler = (request: IngressRequest) => Promise<IngressResponse>;
+type IngressStreamEvents = {
+    /** Called when a new WebSocket connection is established. */
+    onConnect: (streamId: string, metadata: Record<string, string>) => void;
+    /** Called when a message is received on the WebSocket. */
+    onMessage: (streamId: string, data: string) => void;
+    /** Called when the WebSocket disconnects. */
+    onDisconnect: (streamId: string) => void;
+};
+/**
+ * Result from requesting a public ingress URL.
+ * The URL is a Daytona Signed Preview URL with a configurable TTL.
+ * The skill is responsible for monitoring expiry and re-requesting.
+ */
+type IngressUrl = {
+    /** The public URL to register with external services. */
+    url: string;
+    /** When this URL expires (Unix milliseconds). */
+    expiresAt: number;
+};
+type IngressModule = {
+    /**
+     * Register a handler for an HTTP ingress endpoint.
+     * The endpoint name is chosen by the skill author.
+     *
+     * @example
+     * ```ts
+     * mission.ingress.on('webhook', async (request) => {
+     *   const payload = JSON.parse(request.body)
+     *   // process webhook...
+     *   return { status: 200 }
+     * })
+     * ```
+     */
+    on: (endpointName: string, handler: IngressHandler) => void;
+    /**
+     * Register handlers for a WebSocket ingress endpoint.
+     * The endpoint name is chosen by the skill author.
+     *
+     * @example
+     * ```ts
+     * mission.ingress.onStream('media', {
+     *   onConnect: (streamId, meta) => { startSession(streamId) },
+     *   onMessage: (streamId, data) => { processAudio(streamId, data) },
+     *   onDisconnect: (streamId) => { endSession(streamId) }
+     * })
+     * ```
+     */
+    onStream: (endpointName: string, handlers: IngressStreamEvents) => void;
+    /**
+     * Get a public URL for a named ingress endpoint.
+     *
+     * The control plane generates a Daytona Signed Preview URL with a
+     * configurable TTL. The skill is responsible for:
+     *   1. Registering this URL with the external service.
+     *   2. Monitoring `expiresAt` and calling this again before expiry.
+     *   3. Re-registering the new URL with the external service.
+     *
+     * On sandbox restart, skill processes restart and naturally
+     * re-register during their startup sequence.
+     *
+     * @example
+     * ```ts
+     * const { url, expiresAt } = await mission.ingress.getPublicUrl('webhook')
+     * await twilio.incomingPhoneNumbers(sid).update({ voiceUrl: url })
+     * ```
+     */
+    getPublicUrl: (endpointName: string) => Promise<IngressUrl>;
+};
+
+/**
+ * Logging Module
+ *
+ * Provides two logging mechanisms:
+ *
+ *   1. Console capture — overrides the global `console` object so that
+ *      skill authors who use `console.log()` naturally get their logs
+ *      forwarded to the Mission logging pipeline.
+ *
+ *   2. Structured logger — `mission.log.info(message, data?)` for skills
+ *      that want explicit, structured logging with context.
+ *
+ * Both paths feed into the same transport:
+ *   - **Production**: Buffered in memory and flushed every few seconds to the
+ *     Gateway via `skill.ingestLogs`. The Gateway enriches entries with
+ *     installation metadata and forwards them to Better Stack.
+ *   - **Local dev**: Direct synchronous writes to `.logs/skill-port-*.log`
+ *     (if LOCAL_DEV_MODE=1). This ensures logs survive crashes.
+ *
+ * Transport: skill.ingestLogs tRPC mutation (batched, fire-and-forget) OR
+ *           local file write (sync, immediate, survives crashes).
+ */
+
+type LogModule = {
+    /** Log at info level. */
+    info: (message: string, data?: Record<string, unknown>) => void;
+    /** Log at warn level. */
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    /** Log at error level. */
+    error: (message: string, data?: Record<string, unknown>) => void;
+    /** Log at debug level. */
+    debug: (message: string, data?: Record<string, unknown>) => void;
+};
+
+/**
+ * Send-Intents Module
+ *
+ * `mission.sendIntents` — the skill-facing seam for the durable Outlook
+ * send-intent idempotency ledger. It is the SDK half of the exactly-once guard
+ * that closes the Outlook double-send-on-retry hole (B2): the skill claims a
+ * send's content-identity BEFORE dispatching to Microsoft Graph, marks it sent
+ * on a 2xx, and releases it only on a provable pre-dispatch failure.
+ *
+ * The skill runs in a sandbox with NO database access. Its only durable channel
+ * is the Mission gateway's `skill.*` tRPC router, so each method here is a single
+ * strongly-consistent round-trip to OUR store via the gateway — NEVER a read of
+ * Graph's eventually-consistent Sent Items.
+ *
+ * TENANCY: the skill never passes a workspaceId. The gateway resolves the
+ * authoritative owning workspace SERVER-SIDE from the authenticated connection
+ * (see `skill.outlookSendIntentClaim`). The workspace identity the skill DOES
+ * contribute rides INSIDE the `contentKey` hash, which the skill computes from
+ * its tool-context workspaceId — so the ledger key is workspace-scoped by
+ * construction without the skill asserting tenancy on the wire.
+ *
+ * This module's shape is the concrete backing for the outlook skill's
+ * `SendIntents` port (`skills/outlook-mail/src/send-intents.ts`): `claim`,
+ * `markSent`, `release`, keyed on `contentKey` alone.
+ *
+ * Transport: tRPC mutations via the Mission gateway API. The result shapes
+ * (`SendIntentRecord`, `SendIntentClaimOutcome`, …) are hand-declared here, but
+ * the load-bearing direction is drift-protected: every call goes through the
+ * fully-typed `ApiClient`, so a mutation INPUT that diverges from the server
+ * contract fails to compile, and `claim` returns the procedure's result
+ * directly — assignment-checked against `SendIntentClaimOutcome`. The result
+ * shape is therefore pinned by an assignment check, not derived by inference.
+ */
+
+/** Lifecycle state of a send-intent claim in the durable ledger. */
+type SendIntentStatus = 'in_flight' | 'sent';
+/** A claimed (or already-resolved) send intent, read back from the ledger. */
+type SendIntentRecord = {
+    /** The content-identity sha256 hex (the ledger primary key). */
+    contentKey: string;
+    status: SendIntentStatus;
+    /** Present once `status === 'sent'`: the provider message id we returned. */
+    providerMessageId: string | null;
+    /** Present once `status === 'sent'`: the Graph `conversationId`. */
+    conversationId: string | null;
+};
+/** The provider ids recorded against a claim when the send completes. */
+type SendIntentCompletion = {
+    providerMessageId: string;
+    conversationId: string;
+};
+/** The atomic-claim outcome the gateway relays back to the skill. */
+type SendIntentClaimOutcome = {
+    outcome: 'claimed';
+} | {
+    outcome: 'already_sent';
+    record: SendIntentRecord;
+} | {
+    outcome: 'in_flight';
+    record: SendIntentRecord;
+};
+type SendIntentsModule = {
+    /**
+     * Atomically claim a send's content-identity BEFORE the Graph send.
+     *   - no row → insert `in_flight`, return `{ outcome: 'claimed' }`; the caller
+     *     OWNS the send and proceeds.
+     *   - `sent` row → `{ outcome: 'already_sent', record }`; the caller MUST NOT
+     *     resend; it returns the recorded provider ids.
+     *   - `in_flight` row → `{ outcome: 'in_flight', record }`; a prior attempt
+     *     owns it (concurrent, or crashed before commit); the caller MUST NOT
+     *     double-send.
+     */
+    claim: (contentKey: string) => Promise<SendIntentClaimOutcome>;
+    /**
+     * Mark a claimed intent as sent, recording the provider ids. Called once the
+     * Graph send returns 2xx. Idempotent server-side (guarded on `in_flight`).
+     */
+    markSent: (contentKey: string, completion: SendIntentCompletion) => Promise<void>;
+    /**
+     * Release an in-flight claim WITHOUT marking it sent. Called ONLY when the
+     * failure happened provably BEFORE the Graph send was issued, so a legitimate
+     * retry can re-claim and actually send. MUST NOT be called once the send may
+     * have reached Graph (the irreversible boundary).
+     */
+    release: (contentKey: string) => Promise<void>;
+};
+
+/**
+ * Tool Registry
+ *
+ * Skills register their tool handlers here. When the Gateway sends
+ * a "tools.call" command, the registry dispatches to the right handler.
+ *
+ * Usage:
+ *   mission.tools.register('gmail_search', async ({ params, context }) => { ... })
+ *   mission.tools.registerAll(handlers)
+ */
+
+/**
+ * A tool handler function. Receives params and caller context, returns a result.
+ * The SDK handles wrapping the result in the gateway response protocol.
+ *
+ * `input.context.toolCallId` is a stable, retry-invariant identifier for the
+ * logical tool call: the same value arrives on every Temporal retry, so a
+ * handler can use it as an idempotency key to dedupe mutating effects (mint
+ * IDs once, claim-before-write external sends). Optional to consume — handlers
+ * that don't mutate ignore it. The envelope is decoded into `ToolCallInput` in
+ * `sdk.ts`, which passes `context` through whole, so the field reaches the
+ * handler unchanged.
+ */
+type ToolHandler = (input: ToolCallInput) => Promise<unknown>;
+type ToolsModule = {
+    /** Register a single tool handler by name. */
+    register: (name: string, handler: ToolHandler) => void;
+    /** Register multiple tool handlers at once. */
+    registerAll: (handlers: Record<string, ToolHandler>) => void;
+};
+
+/**
+ * Mission SDK — Main Entry
+ *
+ * Creates the SDK instance that a skill uses to interact with the
+ * Mission platform. Communication is HTTP-native:
+ *
+ *   Outbound (Skill → Mission API):
+ *     Standard REST calls via the API client.
+ *
+ *   Inbound (Mission API → Skill):
+ *     HTTP requests to the skill's HTTP server, exposed via
+ *     Daytona Preview URLs.
+ *
+ * Lifecycle:
+ *   1. const mission = createMissionSDK()     — create SDK (no connection yet)
+ *   2. await mission.connect()                — start HTTP server, install logging
+ *   3. // auth, config are now usable
+ *   4. mission.tools.registerAll(handlers)    — register tool handlers
+ *   5. mission.ingress.on('name', handler)    — register ingress handlers
+ *   6. mission.on('event_type', handler)      — register event handler
+ *   7. mission.onShutdown(() => cleanup())    — register shutdown hooks
+ *   8. await mission.ready()                  — signal readiness, accept traffic
+ *
+ * See docs/technical/legacy/architecture/skills/architecture.md §4 and §6.
+ * See docs/technical/legacy/architecture/skills/sandbox-runtime.md.
+ */
+
+type MissionSDKOptions = {
+    /**
+     * Override the skill context instead of reading from env.
+     * Useful for testing or local development.
+     */
+    context?: Partial<SkillContext>;
+    /**
+     * Override the skill HTTP server port. Normally read from
+     * MISSION_SKILL_PORT (assigned by the control plane).
+     * Must be in the Daytona Preview URL range (3000-9999).
+     */
+    port?: number;
+};
+/**
+ * A message from a skill to the agent.
+ *
+ * Skills process their domain-specific inbound data and produce
+ * human-readable messages that agents can reason about.
+ */
+type AgentMessage = {
+    /**
+     * Human-readable message describing what happened.
+     * This is what the agent sees and reasons about.
+     */
+    message: string;
+    /**
+     * Structured context data the agent can reference.
+     * Include IDs, metadata, and any data that helps the agent
+     * take follow-up actions using the skill's tools.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Optional deduplication key to prevent duplicate processing.
+     * If the platform has already processed a message with this key,
+     * it will be silently dropped.
+     */
+    deduplicationKey?: string;
+};
+type MissionSDK = {
+    /** The resolved skill context. */
+    context: SkillContext;
+    /** Get authentication credentials (user-provided secrets and/or OAuth tokens). */
+    auth: AuthModule;
+    /** Fetch per-installation configuration. */
+    config: ConfigModule;
+    /**
+     * Move file bytes between the skill and storage via platform-minted,
+     * authorized `FileRef` handles. Bytes stream skill ⇄ GCS directly — never
+     * through the platform, the model, or any log.
+     */
+    files: FilesModule;
+    /**
+     * Durable Outlook send-intent idempotency ledger. Claim a send's
+     * content-identity before dispatching to Graph, mark it sent on a 2xx, release
+     * it on a provable pre-dispatch failure — the exactly-once guard behind
+     * `outlook_mail_send`. Each call is a strongly-consistent round-trip to OUR
+     * store via the gateway, never a read of Graph's Sent Items.
+     */
+    sendIntents: SendIntentsModule;
+    /** Register ingress handlers and discover public URLs. */
+    ingress: IngressModule;
+    /** Structured logger — logs are batched and shipped to the Mission platform. */
+    log: LogModule;
+    /** Register tool handlers that the platform can invoke. */
+    tools: ToolsModule;
+    /**
+     * Subscribe to typed events delivered by the platform.
+     * Use '*' to subscribe to all event types.
+     *
+     * @example
+     * ```ts
+     * mission.on('mailbox_activity', async (event) => {
+     *   await mission.emit({ message: '...', context: event.payload })
+     * })
+     * ```
+     */
+    on: (eventName: string, handler: EventHandler) => void;
+    /**
+     * Send a message to the agent about an external event.
+     * The platform routes it to the appropriate agent(s) based on
+     * the workspace's routing configuration.
+     *
+     * Sends an agent message to the platform for processing.
+     *
+     * @example
+     * ```ts
+     * await mission.emit({
+     *   message: 'New email from john@example.com',
+     *   context: { emailAddress: 'john@example.com' },
+     *   deduplicationKey: 'gmail-push-12345'
+     * })
+     * ```
+     */
+    emit: (message: AgentMessage) => Promise<void>;
+    /**
+     * Connect to the Mission platform.
+     *
+     * This starts the skill's HTTP server (for inbound tool calls and
+     * ingress traffic), installs the console override for structured
+     * logging, and begins the keep-alive heartbeat loop.
+     *
+     * After this call, `auth`, `config`, `emit`, and `ingress.getPublicUrl`
+     * are usable.
+     */
+    connect: () => Promise<void>;
+    /**
+     * Signal readiness and start accepting tool calls and ingress traffic.
+     *
+     * Call this AFTER registering all tools, ingress handlers, and event handlers.
+     * The returned promise resolves when the process receives a shutdown
+     * signal (SIGTERM/SIGINT) and graceful shutdown completes.
+     */
+    ready: () => Promise<void>;
+    /**
+     * Register a callback to run during graceful shutdown.
+     * Multiple handlers can be registered; they run in order.
+     *
+     * Shutdown is triggered by SIGTERM or SIGINT (standard container signals).
+     * The SDK stops the HTTP server, drains in-flight requests, runs
+     * shutdown handlers, then exits.
+     *
+     * @example
+     * ```ts
+     * mission.onShutdown(async () => {
+     *   await database.close()
+     *   await cache.flush()
+     * })
+     * ```
+     */
+    onShutdown: (handler: () => Promise<void> | void) => void;
+    /**
+     * Register a health check handler for install-time smoke testing.
+     *
+     * The handler is called by the platform after the skill process starts
+     * during installation. It should verify that the skill can reach its
+     * external dependencies (e.g., API keys work, OAuth tokens are valid).
+     *
+     * This is NOT a tool — it is never exposed to the LLM or listed in
+     * reported tools. It is served on an internal HTTP endpoint
+     * (`POST /_mission/health-check`) that only the platform calls.
+     *
+     * If no handler is registered, the health check is skipped (not failed).
+     *
+     * @example
+     * ```ts
+     * mission.onHealthCheck(async () => {
+     *   await gmail.listLabels()
+     *   return { ok: true }
+     * })
+     * ```
+     */
+    onHealthCheck: (handler: () => Promise<unknown> | unknown) => void;
+};
+/**
+ * Create a Mission SDK instance.
+ *
+ * @example
+ * ```ts
+ * import { createMissionSDK } from '@mission/sdk'
+ *
+ * const mission = createMissionSDK()
+ * await mission.connect()
+ *
+ * const auth = await mission.auth.get()
+ * const config = await mission.config.get<MyConfig>(defaults)
+ *
+ * mission.tools.registerAll(handlers)
+ * mission.ingress.on('webhook', handler)
+ * mission.on('mailbox_activity', async (event) => {
+ *   await mission.emit({ message: '...', context: event.payload })
+ * })
+ * mission.onShutdown(() => cleanup())
+ *
+ * await mission.ready()
+ * ```
+ */
+declare function createMissionSDK(options?: MissionSDKOptions): MissionSDK;
+
+/**
+ * A skill tool failure that carries the upstream HTTP status.
+ *
+ * Skill clients (Airtable, Gmail, …) call third-party REST APIs. When one of
+ * those APIs rejects a request — a 422 for a bad field name, a 404 for a
+ * missing record — the client throws. A plain `Error` loses the status: the
+ * skill runtime's tool dispatch (`POST /_mission/tools/:toolName`) then can't
+ * tell a client mistake from a server fault and blankets every throw to
+ * HTTP 500. That 500 propagates to the executor, which (a) stamps a misleading
+ * "HTTP 500" into the model-facing tool result and (b) treats a deterministic
+ * client error as a retryable server fault.
+ *
+ * Throw this instead of a bare `Error` so the real status survives the hop.
+ * The dispatch layer reads `statusCode` and returns it verbatim, so a 422
+ * stays a 422 all the way to the model.
+ */
+declare class SkillToolHttpError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+
 /**
  * Mission SDK
  *
@@ -5,27 +864,17 @@
  * Communication is HTTP-native: outbound REST calls to the Mission API,
  * inbound HTTP requests via Daytona Preview URLs.
  *
- * See docs/technical/architecture/skills/architecture.md.
- * See docs/technical/architecture/skills/sandbox-runtime.md.
- */
-export type { Tool, ToolFunction, ToolFunctionPermission, ToolKind } from '@mission/models';
-export type { ApiClient } from './api';
-export type { AuthCredentials, AuthModule, OAuthCredentials } from './auth';
-export type { ConfigModule } from './config';
-export type { SkillContext } from './context';
-export type { EventHandler, EventHandlerRegistry, SkillEvent } from './event-handler';
-export type { IngressHandler, IngressModule, IngressRequest, IngressResponse, IngressStreamEvents, IngressUrl } from './ingress';
-export type { LogModule } from './logging';
-export type { AgentMessage, MissionSDK, MissionSDKOptions } from './sdk';
-export { createMissionSDK } from './sdk';
-export type { ToolCallContext, ToolCallEnvelope, ToolCallInput, ToolHandler, ToolsModule } from './tool-registry';
+ * See docs/technical/legacy/architecture/skills/architecture.md.
+ * See docs/technical/legacy/architecture/skills/sandbox-runtime.md.
+ */
+
 /** Incoming webhook request passed to a skill's `webhook()` handler. */
-export type WebhookRequest = {
+type WebhookRequest = {
     body: unknown;
     headers: Record<string, string>;
 };
 /** Optional response a `webhook()` handler can return to the external service. */
-export type WebhookResponse = {
+type WebhookResponse = {
     status: number;
     body: unknown;
 };
@@ -34,8 +883,9 @@ export type WebhookResponse = {
  * - `externalId`: tenant identifier used to route the event to the correct connection(s).
  * - `response`: optional custom HTTP response to send back to the caller.
  */
-export type WebhookResult = {
+type WebhookResult = {
     externalId: string | null;
     response?: WebhookResponse;
 };
-//# sourceMappingURL=index.d.ts.map
+
+export { type AgentMessage, type ApiClient, type AttachmentLimits, type AuthCredentials, type AuthModule, type ConfigModule, EmailAttachments, type EventHandler, type EventHandlerRegistry, FileTransferTimeoutError, type FilesModule, type IngressHandler, type IngressModule, type IngressRequest, type IngressResponse, type IngressStreamEvents, type IngressUrl, type LogModule, type MimeBodyParts, type MissionSDK, type MissionSDKOptions, type OAuthCredentials, type RedeemedAttachment, type SendIntentClaimOutcome, type SendIntentCompletion, type SendIntentRecord, type SendIntentStatus, type SendIntentsModule, type SendMessageId, type SendMessageIdInput, type SkillContext, type SkillEvent, SkillToolHttpError, type ToolHandler, type ToolsModule, type WebhookRequest, type WebhookResponse, type WebhookResult, clearDebugLog, createMissionSDK, debugLog };