@codemation/core-nodes 0.12.0 → 0.14.0

package/dist/metadata.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "packageName": "@codemation/core-nodes",
-  "packageVersion": "0.12.0",
+  "packageVersion": "0.14.0",
   "description": "",
   "kind": "nodes",
   "nodes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "publishConfig": {
     "access": "public"
   },
@@ -33,7 +33,7 @@
     "@ai-sdk/provider": "^3.0.8",
     "ai": "^6.0.168",
     "croner": "^10.0.1",
-    "@codemation/core": "0.14.0"
+    "@codemation/core": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/authoring/defineRestNode.types.ts

@@ -9,27 +9,12 @@ import { SsrfGuard } from "../http/SsrfGuard";
 
 type MaybePromise<T> = T | Promise<T>;
 
-/**
- * API endpoint descriptor.
- */
 export type RestNodeApi = Readonly<{
-  /**
-   * Base URL, e.g. `"https://api.slack.com"`.
-   */
   baseUrl: string;
-  /**
-   * Path relative to `baseUrl`. May contain `{paramName}` placeholders that
-   * are substituted from `input` keys before the request is made.
-   * Example: `"/users/{userId}/profile"`
-   */
   path: string;
-  /** HTTP method (default: GET). */
   method?: string;
 }>;
 
-/**
- * The HTTP result shape passed into the `response` mapper.
- */
 export type RestNodeResponseContext = Readonly<{
   status: number;
   ok: boolean;
@@ -40,25 +25,13 @@ export type RestNodeResponseContext = Readonly<{
   text?: string;
 }>;
 
-/**
- * What the `request` callback may return to customise the request.
- */
 export type RestNodeRequestShape = Readonly<{
-  /** Additional path parameters to substitute (merged with `input`). */
   pathParams?: Readonly<Record<string, string>>;
-  /** Extra query params. */
   query?: Readonly<Record<string, string>>;
-  /** Extra headers. */
   headers?: Readonly<Record<string, string>>;
-  /** Request body. */
   body?: HttpBodySpec;
 }>;
 
-/**
- * Error handling policy for non-2xx responses.
- *  - `"throw"` (default) — throws an `Error` for non-2xx responses.
- *  - `"passthrough"` — returns the result regardless of status.
- */
 export type RestNodeErrorPolicy = "throw" | "passthrough";
 
 export interface DefineRestNodeOptions<
@@ -72,44 +45,16 @@ export interface DefineRestNodeOptions<
   readonly description?: string;
   readonly icon?: string;
   readonly api: RestNodeApi;
-  /**
-   * Credential bindings keyed by slot. Use the built-in credential types from
-   * `@codemation/core-nodes` (e.g. `bearerTokenCredentialType`) or any custom one.
-   * The slot key must match what the `request` callback's context uses.
-   */
   readonly credentials?: TCredentials;
-  /**
-   * Zod schema for per-item input. Validated before `execute`.
-   */
   readonly inputSchema?: ZodType<TInputJson>;
-  /**
-   * Builds the per-request customisations from the item input.
-   * Return `body`, `query`, `headers`, and/or `pathParams`.
-   */
   request?(context: Readonly<{ input: TInputJson }>): MaybePromise<RestNodeRequestShape>;
-  /**
-   * Maps the HTTP response to the node's output JSON.
-   * When omitted, the output is `{ status, ok, statusText, mimeType, headers, json, text }`.
-   */
   response?(context: RestNodeResponseContext & Readonly<{ input: TInputJson }>): MaybePromise<TOutputJson>;
-  /**
-   * How to handle non-2xx responses.
-   * @default "throw"
-   */
   readonly errorPolicy?: RestNodeErrorPolicy;
-  /**
-   * Static configuration summary surfaced in the workflow inspector.
-   * Receives the static config (empty record for defineRestNode — config lives on item input).
-   * Most callers return rows based on the static `api` descriptor instead.
-   */
   readonly inspectorSummary?: (
     args: Readonly<{ config: Record<string, never> }>,
   ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 
-/**
- * Substitutes `{name}` placeholders in a path template using values from `params`.
- */
 function substitutePath(template: string, params: Readonly<Record<string, unknown>>): string {
   return template.replace(/\{([^}]+)}/g, (_match, key: string) => {
     const value = params[key];
@@ -117,30 +62,6 @@ function substitutePath(template: string, params: Readonly<Record<string, unknow
   });
 }
 
-/**
- * Declarative helper for creating thin API-wrapper nodes.
- *
- * Usage:
- * ```ts
- * export const postMessage = defineRestNode({
- *   key: "slack.post-message",
- *   title: "Send Slack message",
- *   icon: "si:slack",
- *   api: { baseUrl: "https://slack.com/api", path: "/chat.postMessage", method: "POST" },
- *   credentials: { auth: bearerTokenCredentialType },
- *   inputSchema: z.object({ channel: z.string(), text: z.string() }),
- *   request: ({ input }) => ({
- *     body: { kind: "json", data: { channel: input.channel, text: input.text } },
- *   }),
- *   response: ({ json }) => ({ messageTs: (json as any).ts }),
- * });
- * ```
- *
- * - `defineRestNode` is a thin wrapper over `defineNode`; it does not introduce a new runtime kind.
- * - Credential sessions are resolved via the `credentials` binding map (same as `defineNode`).
- * - Path `{placeholder}` substitution is applied from `input` keys before the request is made.
- * - Non-2xx responses throw an `Error` by default (`errorPolicy: "throw"`).
- */
 export function defineRestNode<
   TKey extends string,
   TCredentials extends DefinedNodeCredentialBindings | undefined,
@@ -160,13 +81,11 @@ export function defineRestNode<
     inputSchema: options.inputSchema,
     inspectorSummary: options.inspectorSummary,
     async execute({ input, item, ctx }, { credentials }) {
-      // Resolve credential if one is bound.
       const credentialSlot = options.credentials ? Object.keys(options.credentials)[0] : undefined;
       const credential = credentialSlot
         ? await (credentials as Record<string, () => Promise<unknown>>)[credentialSlot]?.()
         : undefined;
 
-      // Build path by substituting `{name}` placeholders from input.
       const inputRecord = (input as Record<string, unknown>) ?? {};
       const requestShape = options.request ? await options.request({ input }) : {};
       const pathParams = { ...inputRecord, ...(requestShape.pathParams ?? {}) };
@@ -210,9 +129,6 @@ export function defineRestNode<
         return await options.response({ ...responseCtx, input });
       }
 
-      // Wrap in `{ json: ... }` so the engine's Item-shape detection unwraps once
-      // and the response context becomes the item's payload as-is (preserving the
-      // inner `json` field on the response for callers).
       return { json: responseCtx } as unknown as TOutputJson;
     },
   }) as unknown as DefinedNode<TKey, Record<string, never>, TInputJson, TOutputJson, TCredentials>;

package/src/canvasIconName.ts

@@ -1,8 +1 @@
-/**
- * Canvas / agent presentation:
- * - Lucide: `lucide:<kebab-name>` or legacy kebab name
- * - Built-in brand SVGs: `builtin:<id>` (host resolves to shipped SVG assets under `public/canvas-icons/builtin/`)
- * - Simple Icons: `si:<slug>` (host cherry-picks from `simple-icons`) or builtin asset when slug matches
- * - Image URLs: `http(s):`, `data:`, `/…`
- */
 export type CanvasIconName = string;

package/src/chatModels/CodemationChatModelConfig.ts

@@ -3,14 +3,6 @@ import type { AgentCanvasPresentation, ChatModelConfig } from "@codemation/core"
 import type { CanvasIconName } from "../canvasIconName";
 import { CodemationChatModelFactory } from "./CodemationChatModelFactory";
 
-/**
- * Complexity token sent to the managed LLM broker.
- * The broker maps this to a concrete provider model and thinking effort.
- * low    = cheapest/fastest (short classification, simple extraction)
- * medium = default for most extraction/agent work
- * high   = complex multi-step reasoning
- * xhigh  = hardest problems, most capable model
- */
 export type ManagedComplexity = "low" | "medium" | "high" | "xhigh";
 
 export class CodemationChatModelConfig implements ChatModelConfig {
@@ -30,6 +22,4 @@ export class CodemationChatModelConfig implements ChatModelConfig {
     this.modelName = complexity;
     this.presentation = presentationIn ?? { icon: "lucide:bot", label: name };
   }
-
-  // No getCredentialRequirements() — authentication is implicit via workspace pairing secret.
 }

package/src/chatModels/CodemationChatModelFactory.ts

@@ -9,7 +9,6 @@ export class CodemationChatModelFactory implements ChatModelFactory<CodemationCh
   async create(
     args: Readonly<{ config: CodemationChatModelConfig; ctx: NodeExecutionContext<any> }>,
   ): Promise<ChatLanguageModel> {
-    // D5: read at session-create time so unpairing or misconfiguration surfaces at workflow run, not boot.
     // eslint-disable-next-line no-restricted-properties -- LLM_GATEWAY_URL is injected by the control-plane provisioner into the workspace process env; reading it at factory-create time is the justified boundary.
     const gatewayUrl = process.env["LLM_GATEWAY_URL"];
     if (!gatewayUrl) {
@@ -25,13 +24,7 @@ export class CodemationChatModelFactory implements ChatModelFactory<CodemationCh
     }
 
     const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret);
-    // Lazy import: pulls @ai-sdk/anthropic + the `ai` SDK (~28MB RSS) only when a
-    // chat model is actually built. Non-AI workflows never load it.
-    // Using the Anthropic-native route so the broker's injected `thinking` /
-    // `output_config.effort` fields survive (they are stripped by the OpenAI-compat route).
     const { createAnthropic } = await import("@ai-sdk/anthropic");
-    // apiKey is required by the AI SDK but unused — authentication is handled by the HMAC-signed fetch wrapper.
-    // baseURL: the SDK appends /messages → hits the broker's /v1/messages Anthropic-native route.
     const provider = createAnthropic({ baseURL: `${gatewayUrl}/v1`, apiKey: "codemation-managed", fetch: hmacFetch });
     const languageModel = provider(args.config.complexity);
 

package/src/chatModels/ManagedHmacSignerFactory.types.ts

@@ -1,44 +1,16 @@
 import { createHmac, createHash, randomBytes } from "node:crypto";
 
 export interface ManagedHmacSignerOptions {
-  /**
-   * When true (the default), the signer hashes the request body and includes
-   * the hash in the HMAC base string. Use for small JSON payloads (LLM chat).
-   *
-   * When false (doc-scanner / LD11 mode), the signer computes the signature
-   * over sha256("") regardless of the actual body bytes, and forwards those
-   * bytes to the upstream fetch untouched. The HMAC binds the workspace
-   * identity, not the file content — enabling streaming without buffering.
-   */
   signBody?: boolean;
-  /** Override wall-clock seconds for deterministic testing. */
   now?: () => number;
-  /** Override nonce generation for deterministic testing. */
   nonce?: () => string;
 }
 
-/**
- * Creates an HMAC-signing fetch wrapper that authenticates requests to
- * Codemation managed services (LLM broker, doc-scanner) with the
- * Codemation-Hmac v=1 scheme.
- *
- * Mirrors HmacRequestSigner from @codemation/host/pairing without importing
- * that package (which would create a circular dependency since @codemation/host
- * depends on @codemation/core-nodes).
- *
- * @param workspaceId   - Workspace identifier injected by the CP provisioner.
- * @param pairingSecret - Base64-encoded 32-byte HMAC key injected by the provisioner.
- * @param options       - Optional behaviour flags and test seams.
- */
 export function managedHmacFetchFactory(
   workspaceId: string,
   pairingSecret: string,
   options?: ManagedHmacSignerOptions,
 ): typeof fetch {
-  // LLM chat (the existing caller) signs its small JSON body → signBody defaults true.
-  // The doc-scanner node passes signBody:false (LD11): the HMAC binds the WORKSPACE,
-  // not the file, so we never read/normalise the (possibly large, binary) body —
-  // it is forwarded untouched and the signature covers an empty body hash.
   const signBody = options?.signBody ?? true;
 
   return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
@@ -55,18 +27,11 @@ export function managedHmacFetchFactory(
     const headers = new Headers(init?.headers as Record<string, string> | undefined);
     headers.set("Authorization", authHeader);
 
-    // When signing the body, forward the (possibly normalised) string.
-    // When not signing (signBody:false), forward the ORIGINAL body untouched
-    // so binary/streamed payloads are never buffered or re-encoded.
     const outgoingBody = signBody ? bodyForSigning || init?.body : init?.body;
     return fetch(input, { ...init, body: outgoingBody, headers });
   };
 }
 
-/**
- * Produces a Codemation-Hmac v=1 Authorization header value.
- * Algorithm must match HmacVerifier.computeSignature() in the control-plane.
- */
 function buildHmacAuthHeader(
   workspaceId: string,
   pairingSecret: string,

package/src/chatModels/OpenAIChatModelFactory.ts

@@ -10,8 +10,6 @@ export class OpenAIChatModelFactory implements ChatModelFactory<OpenAIChatModelC
     args: Readonly<{ config: OpenAIChatModelConfig; ctx: NodeExecutionContext<any> }>,
   ): Promise<ChatLanguageModel> {
     const session = await args.ctx.getCredential<OpenAiCredentialSession>(args.config.credentialSlotKey);
-    // Lazy import: pulls @ai-sdk/openai + the `ai` SDK (~28MB RSS) only when a
-    // chat model is actually built. Non-AI workflows never load it.
     const { createOpenAI } = await import("@ai-sdk/openai");
     const provider = createOpenAI({
       apiKey: session.apiKey,

package/src/chatModels/OpenAiChatModelPresetsFactory.ts

@@ -1,10 +1,5 @@
 import { OpenAIChatModelConfig } from "./openAiChatModelConfig";
 
-/**
- * Default OpenAI chat model configs for scaffolds and demos (icon + label match {@link OpenAIChatModelConfig} defaults).
- * Prefer importing {@link openAiChatModelPresets} from here or from the consumer template re-export
- * instead of repeating {@link OpenAIChatModelConfig} construction in app workflows.
- */
 export class OpenAiChatModelPresets {
   readonly demoGpt4oMini = new OpenAIChatModelConfig("OpenAI", "gpt-4o-mini");
 

package/src/chatModels/OpenAiCredentialSession.ts

@@ -1,4 +1,3 @@
-/** Resolved credential session for OpenAI-compatible chat models (API key + optional custom base URL). */
 export type OpenAiCredentialSession = Readonly<{
   apiKey: string;
   baseUrl?: string;

package/src/chatModels/OpenAiStrictJsonSchemaFactory.ts

@@ -3,27 +3,6 @@ import { inject, injectable } from "@codemation/core";
 
 import { AIAgentExecutionHelpersFactory } from "../nodes/AIAgentExecutionHelpersFactory";
 
-/**
- * Produces an OpenAI **strict mode**–compliant JSON Schema for an AIAgent `outputSchema`.
- *
- * Why this exists: AI SDK's default Zod → JSON Schema conversion (Zod v4's `toJSONSchema`) can
- * emit `unevaluatedProperties: false` or skip `additionalProperties: false` on object branches.
- * OpenAI's strict-mode validator rejects anything missing `additionalProperties: false` at
- * `context=()` (the root) and requires **all properties** in `required`. We convert here so all
- * legal Zod root shapes work (object, union, discriminated union, nullable-object wrapper, array,
- * intersection, …) and hand AI SDK a pre-tagged `jsonSchema(...)` record that passes straight
- * through to the provider.
- *
- * Rules enforced on the produced JSON Schema record:
- * - Every `type: "object"` node (root and nested under `allOf`/`anyOf`/`oneOf`/`items`/`prefixItems`/`$defs`):
- *   - `additionalProperties: false`
- *   - `required` lists **every** key in `properties` (OpenAI strict requires all properties required;
- *     express optionality via `.nullable()` / `z.union([..., z.null()])`).
- *   - `properties` is always an object (empty object allowed).
- * - `$schema`, `unevaluatedProperties`, and `default` are stripped (OpenAI rejects / ignores them).
- * - `sanitizeJsonSchemaRequiredKeywordsForCfworker` invariants from
- *   {@link AIAgentExecutionHelpersFactory.createJsonSchemaRecord} are preserved as a starting point.
- */
 @injectable()
 export class OpenAiStrictJsonSchemaFactory {
   constructor(

package/src/credentials/ApiKeyCredentialType.ts

@@ -1,9 +1,6 @@
 import { defineCredential } from "@codemation/core";
 import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
 
-/**
- * API key credential that injects a key either as an HTTP header or a query parameter.
- */
 export const apiKeyCredentialType = defineCredential({
   key: "core-nodes.api-key",
   label: "API Key",

package/src/credentials/BasicAuthCredentialType.ts

@@ -1,10 +1,6 @@
 import { defineCredential } from "@codemation/core";
 import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
 
-/**
- * HTTP Basic authentication credential.
- * Session sets `Authorization: Basic <base64(username:password)>`.
- */
 export const basicAuthCredentialType = defineCredential({
   key: "core-nodes.basic-auth",
   label: "Basic Auth",

package/src/credentials/BearerTokenCredentialType.ts

@@ -1,10 +1,6 @@
 import { defineCredential } from "@codemation/core";
 import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
 
-/**
- * Simple Bearer token credential.
- * Session sets `Authorization: Bearer <token>` on every request.
- */
 export const bearerTokenCredentialType = defineCredential({
   key: "core-nodes.bearer-token",
   label: "Bearer Token",

package/src/credentials/OAuth2ClientCredentialsTypeFactory.ts

@@ -2,24 +2,6 @@ import { defineCredential } from "@codemation/core";
 import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
 import { OAuth2TokenExchangeFactory } from "./OAuth2TokenExchangeFactory";
 
-/**
- * OAuth2 client-credentials flow credential.
- *
- * This is a machine-to-machine flow: no user redirect occurs. The session
- * POSTs to the configured `tokenUrl` with `client_credentials` grant, caches
- * the resulting access token for the duration of the session, and injects it
- * as `Authorization: Bearer <token>` on each request.
- *
- * Token caching is per-session only (one createSession call = one token fetch
- * at most). Cross-session caching would require host-level state and is out of
- * scope here. Because the engine creates a fresh session per execution, a new
- * token is fetched once per node activation.
- *
- * NOTE: `auth` is intentionally omitted from the definition. The OAuth2
- * `auth: { kind: "oauth2" }` shape signals an authorization-code / user-redirect
- * flow; using it here would cause the host UI to render an OAuth consent button
- * that goes nowhere. Client-credentials is a purely server-side flow.
- */
 export const oauth2ClientCredentialsType = defineCredential({
   key: "core-nodes.oauth2-client-credentials",
   label: "OAuth2 Client Credentials",
@@ -65,7 +47,6 @@ export const oauth2ClientCredentialsType = defineCredential({
       throw new Error("OAuth2 client credentials are incomplete: tokenUrl, clientId, and clientSecret are required.");
     }
 
-    // Fetch the token eagerly so any failure surfaces at session creation time.
     const accessToken = await new OAuth2TokenExchangeFactory().create({
       tokenUrl,
       clientId,

package/src/credentials/OAuth2TokenExchangeFactory.ts

@@ -1,10 +1,3 @@
-/**
- * Performs an OAuth2 `client_credentials` token exchange against a token endpoint
- * and returns the resulting access token.
- *
- * Lives in a Factory file so the body URLSearchParams construction is allowed at
- * the composition root.
- */
 export type OAuth2ClientCredentialsArgs = Readonly<{
   tokenUrl: string;
   clientId: string;

package/src/http/HttpBodyBuilder.ts

@@ -6,17 +6,9 @@ import type { HttpBodySpec } from "./httpRequest.types";
 
 export type EncodedBody = Readonly<{
   body: NonNullable<RequestInit["body"]>;
-  /**
-   * Desired Content-Type header. Empty string means `fetch` should set it automatically
-   * (used for multipart/form-data so the boundary is set correctly by the browser/Node runtime).
-   */
   contentType: string;
 }>;
 
-/**
- * Builds a fetch-compatible `BodyInit` + Content-Type pair from an {@link HttpBodySpec}.
- * Multipart binaries are read from `item.binary` via `ctx.binary.openReadStream`.
- */
 export class HttpBodyBuilder {
   async build(
     spec: HttpBodySpec | undefined,
@@ -28,9 +20,6 @@ export class HttpBodyBuilder {
     }
 
     if (spec.kind === "json") {
-      // Backstop for callers that reach this with a string despite the `data: object`
-      // type (e.g. via `unknown`/`as`, or a resolved expression): re-stringifying it
-      // would double-encode into `"\"...\""`. Fail loud instead of shipping bad JSON.
       if (typeof spec.data === "string") {
         throw new Error(
           'HttpRequest body kind:"json" expects a serializable object for "data", but received a string. ' +
@@ -72,8 +61,6 @@ export class HttpBodyBuilder {
           }
         }
       }
-      // FormData sets its own Content-Type with boundary; empty string signals that
-      // fetch should set it automatically.
       return {
         body: formData,
         contentType: "",
@@ -92,9 +79,6 @@ export class HttpBodyBuilder {
       if (!readResult) {
         throw new Error(`HttpRequest bodyFormat "binary": could not open read stream for slot "${spec.slot}".`);
       }
-      // Pass the stream straight to fetch — no buffering. fetch's BodyInit
-      // accepts a ReadableStream natively, so big attachments upload without
-      // ever materialising the full payload in memory.
       return {
         body: readResult.body as unknown as NonNullable<RequestInit["body"]>,
         contentType: attachment.mimeType,

package/src/http/HttpRequestExecutor.ts

@@ -4,21 +4,6 @@ import type { HttpBodyBuilder } from "./HttpBodyBuilder";
 import type { HttpUrlBuilder } from "./HttpUrlBuilder";
 import type { SsrfGuard } from "./SsrfGuard";
 
-/**
- * Executes a single HTTP request described by {@link HttpRequestSpec}.
- *
- * - Credential sessions provide header/query deltas via `applyToRequest`.
- * - Body encoding is delegated to {@link HttpBodyBuilder}.
- * - URL query merging is delegated to {@link HttpUrlBuilder}.
- * - SSRF protection is delegated to {@link SsrfGuard} (injected).
- * - Binary response bodies: when `download.mode` triggers binary attach, the
- *   `bodyBinaryName` field is set in the result but the body is NOT read here.
- *   Callers that need binary attachment should use `buildRequest` to get the
- *   resolved URL + init and make the fetch + binary attach themselves.
- *
- * Collaborators (`fetch`, body builder, url builder, ssrfGuard) are injected so
- * callers own construction at composition roots and tests can supply deterministic stubs.
- */
 export class HttpRequestExecutor {
   constructor(
     private readonly fetchFn: typeof globalThis.fetch,
@@ -27,14 +12,6 @@ export class HttpRequestExecutor {
     private readonly ssrfGuard: SsrfGuard,
   ) {}
 
-  /**
-   * Builds the fetch init (headers, query, body) from the spec + credential delta,
-   * returning both the resolved URL and the RequestInit so callers can make the
-   * actual fetch call themselves (useful for streaming / binary attach).
-   *
-   * Also performs SSRF protection via the injected {@link SsrfGuard} before
-   * returning — throws {@link SSRFBlockedError} if the target is a private address.
-   */
   async buildRequest(spec: HttpRequestSpec, item: Item): Promise<Readonly<{ url: string; init: RequestInit }>> {
     await this.ssrfGuard.check(spec.url, spec.allowPrivateNetworkTargets ?? false);
 
@@ -52,10 +29,6 @@ export class HttpRequestExecutor {
 
     const encodedBody = await this.bodyBuilder.build(spec.body, item, spec.ctx);
 
-    // Only set Content-Type from the encoded body when it is non-empty
-    // (empty string = FormData will set it automatically).
-    // Explicit headers always win — only apply the body-derived content-type
-    // when the caller has not already set one (case-insensitive check).
     const hasExplicitContentType = Object.keys(mergedHeaders).some((k) => k.toLowerCase() === "content-type");
     if (encodedBody && encodedBody.contentType && !hasExplicitContentType) {
       mergedHeaders["content-type"] = encodedBody.contentType;
@@ -72,12 +45,6 @@ export class HttpRequestExecutor {
     return { url: resolvedUrl, init };
   }
 
-  /**
-   * Executes an HTTP request and returns parsed result.
-   * For binary downloads (when `shouldAttachBody` is true), the body is NOT consumed
-   * and callers must call `ctx.binary.attach` directly using the resolved URL + init
-   * (available via `buildRequest`).
-   */
   async execute(spec: HttpRequestSpec, item: Item): Promise<HttpRequestResult> {
     const { url: resolvedUrl, init } = await this.buildRequest(spec, item);
 
@@ -97,9 +64,7 @@ export class HttpRequestExecutor {
     let bodyBinaryName: string | undefined;
 
     if (shouldDownload) {
-      // Signal to caller that binary attachment is needed.
       bodyBinaryName = binaryName;
-      // Do NOT read the body here — the caller must handle binary attach separately.
     } else if (isJson) {
       try {
         json = await response.json();

package/src/http/HttpUrlBuilder.ts

@@ -1,7 +1,3 @@
-/**
- * Merges query parameters into a base URL.
- * Handles both scalar and array values, and preserves any existing params.
- */
 export class HttpUrlBuilder {
   build(baseUrl: string, query?: Readonly<Record<string, string | string[]>>): string {
     if (!query || Object.keys(query).length === 0) {

package/src/http/SSRFBlockedError.ts

@@ -1,7 +1,3 @@
-/**
- * Thrown when an HTTP request target resolves to a private, link-local, or
- * loopback address and `allowPrivateNetworkTargets` is not set.
- */
 export class SSRFBlockedError extends Error {
   readonly resolvedIp: string;