docs: document sdk payload and fetch contracts

src/plugin-sdk/allow-from.ts

@@ -109,6 +109,7 @@ export function isAllowedParsedChatSender(params: {
   return isAllowedParsedChatSenderShared(params);
 }
 
+/** Serializable allowlist resolution record used by setup/status UI surfaces. */
 export type BasicAllowlistResolutionEntry = {
   /** Original allowlist input. */
   input: string;

src/plugin-sdk/fetch-auth.ts

@@ -4,6 +4,7 @@ import {
   normalizeRequestInitHeadersForFetch,
 } from "../infra/fetch-headers.js";
 
+/** Token source used by scoped bearer-auth fetch retries. */
 export type ScopeTokenProvider = {
   /** Return a bearer token for the requested OAuth/API scope. */
   getAccessToken: (scope: string) => Promise<string>;

src/plugin-sdk/fetch-runtime.ts

@@ -31,6 +31,7 @@ type GuardedFetchPresetOptions = Omit<
   "mode" | "proxy" | "dangerouslyAllowEnvProxyWithoutPinnedDns"
 >;
 
+/** Apply the trusted-env-proxy guarded fetch preset without exposing raw mode strings to plugins. */
 export function withTrustedEnvProxyGuardedFetchMode(
   params: GuardedFetchPresetOptions,
 ): GuardedFetchOptions {

src/plugin-sdk/memory-core-host-engine-embeddings.ts

@@ -36,6 +36,7 @@ export {
   withRemoteHttpResponse,
 } from "../../packages/memory-host-sdk/src/engine-embeddings.js";
 
+/** Provider batch status payload shared by memory embedding batch helpers. */
 export type EmbeddingBatchStatus = {
   id?: string;
   status?: string;

src/plugin-sdk/session-transcript-hit.ts

@@ -40,6 +40,7 @@ function normalizeQmdSessionStem(stem: string): string {
     .replace(/^-+|-+$/g, "");
 }
 
+/** Canonical session identity parsed from a transcript search-hit path. */
 export type SessionTranscriptHitIdentity = {
   stem: string;
   liveStem?: string;
@@ -71,6 +72,7 @@ export function extractTranscriptStemFromSessionsMemoryHit(hitPath: string): str
   return extractTranscriptIdentityFromSessionsMemoryHit(hitPath)?.stem ?? null;
 }
 
+/** Parse live/archive ownership metadata from a sessions-memory hit path. */
 export function extractTranscriptIdentityFromSessionsMemoryHit(
   hitPath: string,
 ): SessionTranscriptHitIdentity | null {

src/plugin-sdk/tool-payload.ts

@@ -44,6 +44,7 @@ type ToolPayloadTextBlock = {
   text: string;
 };
 
+/** Minimal tool-result-like object shape accepted by payload extraction helpers. */
 export type ToolPayloadCarrier = {
   /** Structured payload preferred over content text when present. */
   details?: unknown;