From c1b49bb1d0e608f0856eaee2f3546c9d0a1b9b01 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 22:20:19 -0400
Subject: [PATCH] docs: document sdk payload and fetch contracts

---
 src/plugin-sdk/allow-from.ts                         | 1 +
 src/plugin-sdk/fetch-auth.ts                         | 1 +
 src/plugin-sdk/fetch-runtime.ts                      | 1 +
 src/plugin-sdk/memory-core-host-engine-embeddings.ts | 1 +
 src/plugin-sdk/session-transcript-hit.ts             | 2 ++
 src/plugin-sdk/tool-payload.ts                       | 1 +
 6 files changed, 7 insertions(+)

diff --git a/src/plugin-sdk/allow-from.ts b/src/plugin-sdk/allow-from.ts
index f7ad28044810..75d4fa7c4d79 100644
--- a/src/plugin-sdk/allow-from.ts
+++ b/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;
diff --git a/src/plugin-sdk/fetch-auth.ts b/src/plugin-sdk/fetch-auth.ts
index 398aac7af4f9..f6e0dfd783f7 100644
--- a/src/plugin-sdk/fetch-auth.ts
+++ b/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>;
diff --git a/src/plugin-sdk/fetch-runtime.ts b/src/plugin-sdk/fetch-runtime.ts
index d9fe055dee22..075d19374879 100644
--- a/src/plugin-sdk/fetch-runtime.ts
+++ b/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 {
diff --git a/src/plugin-sdk/memory-core-host-engine-embeddings.ts b/src/plugin-sdk/memory-core-host-engine-embeddings.ts
index 461e55ba3e9c..d8b32a27fd00 100644
--- a/src/plugin-sdk/memory-core-host-engine-embeddings.ts
+++ b/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;
diff --git a/src/plugin-sdk/session-transcript-hit.ts b/src/plugin-sdk/session-transcript-hit.ts
index 83088b2145de..aa842707efb2 100644
--- a/src/plugin-sdk/session-transcript-hit.ts
+++ b/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 {
diff --git a/src/plugin-sdk/tool-payload.ts b/src/plugin-sdk/tool-payload.ts
index 0d01a00be13e..96d2c521c3a0 100644
--- a/src/plugin-sdk/tool-payload.ts
+++ b/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;