@ainative/cody-sdk 0.1.0

package/src/lib/beta-parser.ts

@@ -0,0 +1,148 @@
+import type { Logger } from '../client';
+import { AnthropicError } from '../core/error';
+import {
+  BetaContentBlock,
+  BetaJSONOutputFormat,
+  BetaMessage,
+  BetaOutputConfig,
+  BetaTextBlock,
+  MessageCreateParams,
+} from '../resources/beta/messages/messages';
+
+// vendored from typefest just to make things look a bit nicer on hover
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+
+type AutoParseableBetaOutputConfig = Omit<BetaOutputConfig, 'format'> & {
+  format?: BetaJSONOutputFormat | AutoParseableBetaOutputFormat<any> | null;
+};
+
+export type BetaParseableMessageCreateParams = Simplify<
+  Omit<MessageCreateParams, 'output_format' | 'output_config'> & {
+    /**
+     * @deprecated Use `output_config.format` instead. This parameter will be removed in a future
+     *   release.
+     */
+    output_format?: BetaJSONOutputFormat | AutoParseableBetaOutputFormat<any> | null;
+    output_config?: AutoParseableBetaOutputConfig | null;
+  }
+>;
+
+export type ExtractParsedContentFromBetaParams<Params extends BetaParseableMessageCreateParams> =
+  Params['output_format'] extends AutoParseableBetaOutputFormat<infer P> ? P
+  : Params['output_config'] extends { format: AutoParseableBetaOutputFormat<infer P> } ? P
+  : null;
+
+export type AutoParseableBetaOutputFormat<ParsedT> = BetaJSONOutputFormat & {
+  parse(content: string): ParsedT;
+};
+
+export type ParsedBetaMessage<ParsedT> = BetaMessage & {
+  content: Array<ParsedBetaContentBlock<ParsedT>>;
+  parsed_output: ParsedT | null;
+};
+
+export type ParsedBetaContentBlock<ParsedT> =
+  | (BetaTextBlock & { parsed_output: ParsedT | null })
+  | Exclude<BetaContentBlock, BetaTextBlock>;
+
+function getOutputFormat(
+  params: BetaParseableMessageCreateParams | null,
+): BetaJSONOutputFormat | AutoParseableBetaOutputFormat<any> | null | undefined {
+  // Prefer output_format (deprecated) over output_config.format for backward compatibility
+  return params?.output_format ?? params?.output_config?.format;
+}
+
+export function maybeParseBetaMessage<Params extends BetaParseableMessageCreateParams | null>(
+  message: BetaMessage,
+  params: Params,
+  opts: { logger: Logger },
+): ParsedBetaMessage<ExtractParsedContentFromBetaParams<NonNullable<Params>>> {
+  const outputFormat = getOutputFormat(params);
+  if (!params || !('parse' in (outputFormat ?? {}))) {
+    return {
+      ...message,
+      content: message.content.map((block) => {
+        if (block.type === 'text') {
+          const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+            value: null,
+            enumerable: false,
+          }) as ParsedBetaContentBlock<ExtractParsedContentFromBetaParams<NonNullable<Params>>>;
+
+          return Object.defineProperty(parsedBlock, 'parsed', {
+            get() {
+              opts.logger.warn(
+                'The `parsed` property on `text` blocks is deprecated, please use `parsed_output` instead.',
+              );
+              return null;
+            },
+            enumerable: false,
+          });
+        }
+        return block;
+      }),
+      parsed_output: null,
+    } as ParsedBetaMessage<ExtractParsedContentFromBetaParams<NonNullable<Params>>>;
+  }
+
+  return parseBetaMessage(message, params, opts);
+}
+
+export function parseBetaMessage<Params extends BetaParseableMessageCreateParams>(
+  message: BetaMessage,
+  params: Params,
+  opts: { logger: Logger },
+): ParsedBetaMessage<ExtractParsedContentFromBetaParams<Params>> {
+  let firstParsedOutput: ReturnType<typeof parseBetaOutputFormat<Params>> | null = null;
+
+  const content: Array<ParsedBetaContentBlock<ExtractParsedContentFromBetaParams<Params>>> =
+    message.content.map((block) => {
+      if (block.type === 'text') {
+        const parsedOutput = parseBetaOutputFormat(params, block.text);
+
+        if (firstParsedOutput === null) {
+          firstParsedOutput = parsedOutput;
+        }
+
+        const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+          value: parsedOutput,
+          enumerable: false,
+        }) as ParsedBetaContentBlock<ExtractParsedContentFromBetaParams<Params>>;
+        return Object.defineProperty(parsedBlock, 'parsed', {
+          get() {
+            opts.logger.warn(
+              'The `parsed` property on `text` blocks is deprecated, please use `parsed_output` instead.',
+            );
+            return parsedOutput;
+          },
+          enumerable: false,
+        });
+      }
+      return block;
+    });
+
+  return {
+    ...message,
+    content,
+    parsed_output: firstParsedOutput,
+  } as ParsedBetaMessage<ExtractParsedContentFromBetaParams<Params>>;
+}
+
+function parseBetaOutputFormat<Params extends BetaParseableMessageCreateParams>(
+  params: Params,
+  content: string,
+): ExtractParsedContentFromBetaParams<Params> | null {
+  const outputFormat = getOutputFormat(params);
+  if (outputFormat?.type !== 'json_schema') {
+    return null;
+  }
+
+  try {
+    if ('parse' in outputFormat) {
+      return outputFormat.parse(content);
+    }
+
+    return JSON.parse(content);
+  } catch (error) {
+    throw new AnthropicError(`Failed to parse structured output: ${error}`);
+  }
+}

package/src/lib/parser.ts

@@ -0,0 +1,125 @@
+import type { Logger } from '../client';
+import { AnthropicError } from '../core/error';
+import {
+  ContentBlock,
+  JSONOutputFormat,
+  Message,
+  OutputConfig,
+  TextBlock,
+  MessageCreateParams,
+} from '../resources/messages/messages';
+
+// vendored from typefest just to make things look a bit nicer on hover
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+
+type AutoParseableOutputConfig = Omit<OutputConfig, 'format'> & {
+  format?: JSONOutputFormat | AutoParseableOutputFormat<any> | null;
+};
+
+export type ParseableMessageCreateParams = Simplify<
+  Omit<MessageCreateParams, 'output_config'> & {
+    output_config?: AutoParseableOutputConfig | null;
+  }
+>;
+
+export type ExtractParsedContentFromParams<Params extends ParseableMessageCreateParams> =
+  Params['output_config'] extends { format: AutoParseableOutputFormat<infer P> } ? P : null;
+
+export type AutoParseableOutputFormat<ParsedT> = JSONOutputFormat & {
+  parse(content: string): ParsedT;
+};
+
+export type ParsedMessage<ParsedT> = Message & {
+  content: Array<ParsedContentBlock<ParsedT>>;
+  parsed_output: ParsedT | null;
+};
+
+export type ParsedContentBlock<ParsedT> =
+  | (TextBlock & { parsed_output: ParsedT | null })
+  | Exclude<ContentBlock, TextBlock>;
+
+function getOutputFormat(
+  params: ParseableMessageCreateParams | null,
+): JSONOutputFormat | AutoParseableOutputFormat<any> | null | undefined {
+  return params?.output_config?.format;
+}
+
+export function maybeParseMessage<Params extends ParseableMessageCreateParams | null>(
+  message: Message,
+  params: Params,
+  opts: { logger: Logger },
+): ParsedMessage<ExtractParsedContentFromParams<NonNullable<Params>>> {
+  const outputFormat = getOutputFormat(params);
+  if (!params || !('parse' in (outputFormat ?? {}))) {
+    return {
+      ...message,
+      content: message.content.map((block) => {
+        if (block.type === 'text') {
+          const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+            value: null,
+            enumerable: false,
+          }) as ParsedContentBlock<ExtractParsedContentFromParams<NonNullable<Params>>>;
+
+          return parsedBlock;
+        }
+        return block;
+      }),
+      parsed_output: null,
+    } as ParsedMessage<ExtractParsedContentFromParams<NonNullable<Params>>>;
+  }
+
+  return parseMessage(message, params, opts);
+}
+
+export function parseMessage<Params extends ParseableMessageCreateParams>(
+  message: Message,
+  params: Params,
+  opts: { logger: Logger },
+): ParsedMessage<ExtractParsedContentFromParams<Params>> {
+  let firstParsedOutput: ReturnType<typeof parseOutputFormat<Params>> | null = null;
+
+  const content: Array<ParsedContentBlock<ExtractParsedContentFromParams<Params>>> = message.content.map(
+    (block) => {
+      if (block.type === 'text') {
+        const parsedOutput = parseOutputFormat(params, block.text);
+
+        if (firstParsedOutput === null) {
+          firstParsedOutput = parsedOutput;
+        }
+
+        const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+          value: parsedOutput,
+          enumerable: false,
+        }) as ParsedContentBlock<ExtractParsedContentFromParams<Params>>;
+        return parsedBlock;
+      }
+      return block;
+    },
+  );
+
+  return {
+    ...message,
+    content,
+    parsed_output: firstParsedOutput,
+  } as ParsedMessage<ExtractParsedContentFromParams<Params>>;
+}
+
+function parseOutputFormat<Params extends ParseableMessageCreateParams>(
+  params: Params,
+  content: string,
+): ExtractParsedContentFromParams<Params> | null {
+  const outputFormat = getOutputFormat(params);
+  if (outputFormat?.type !== 'json_schema') {
+    return null;
+  }
+
+  try {
+    if ('parse' in outputFormat) {
+      return outputFormat.parse(content);
+    }
+
+    return JSON.parse(content);
+  } catch (error) {
+    throw new AnthropicError(`Failed to parse structured output: ${error}`);
+  }
+}

package/src/lib/stainless-helper-header.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared utilities for tracking SDK helper usage.
+ */
+
+import type { BetaMessageParam, BetaToolUnion } from '../resources/beta';
+
+/**
+ * Symbol used to mark objects created by SDK helpers for tracking.
+ * The value is the helper name (e.g., 'mcpTool', 'betaZodTool').
+ */
+export const SDK_HELPER_SYMBOL = Symbol('anthropic.sdk.stainlessHelper');
+
+type StainlessHelperObject = { [SDK_HELPER_SYMBOL]: string };
+
+export function wasCreatedByStainlessHelper(value: unknown): value is StainlessHelperObject {
+  return typeof value === 'object' && value !== null && SDK_HELPER_SYMBOL in value;
+}
+
+/**
+ * Collects helper names from tools and messages arrays.
+ * Returns a deduplicated array of helper names found.
+ */
+export function collectStainlessHelpers(
+  tools: BetaToolUnion[] | undefined,
+  messages: BetaMessageParam[] | undefined,
+): string[] {
+  const helpers = new Set<string>();
+
+  // Collect from tools
+  if (tools) {
+    for (const tool of tools) {
+      if (wasCreatedByStainlessHelper(tool)) {
+        helpers.add(tool[SDK_HELPER_SYMBOL]);
+      }
+    }
+  }
+
+  // Collect from messages and their content blocks
+  if (messages) {
+    for (const message of messages) {
+      if (wasCreatedByStainlessHelper(message)) {
+        helpers.add(message[SDK_HELPER_SYMBOL]);
+      }
+
+      if (Array.isArray(message.content)) {
+        for (const block of message.content) {
+          if (wasCreatedByStainlessHelper(block)) {
+            helpers.add(block[SDK_HELPER_SYMBOL]);
+          }
+        }
+      }
+    }
+  }
+
+  return Array.from(helpers);
+}
+
+/**
+ * Builds x-stainless-helper header value from tools and messages.
+ * Returns an empty object if no helpers are found.
+ */
+export function stainlessHelperHeader(
+  tools: BetaToolUnion[] | undefined,
+  messages: BetaMessageParam[] | undefined,
+): { 'x-stainless-helper'?: string } {
+  const helpers = collectStainlessHelpers(tools, messages);
+  if (helpers.length === 0) return {};
+  return { 'x-stainless-helper': helpers.join(', ') };
+}
+
+/**
+ * Builds x-stainless-helper header value from a file object.
+ * Returns an empty object if the file is not marked with a helper.
+ */
+export function stainlessHelperHeaderFromFile(file: unknown): { 'x-stainless-helper'?: string } {
+  if (wasCreatedByStainlessHelper(file)) {
+    return { 'x-stainless-helper': file[SDK_HELPER_SYMBOL] };
+  }
+  return {};
+}

package/src/lib/tools/BetaRunnableTool.ts

@@ -0,0 +1,40 @@
+import {
+  BetaMemoryTool20250818,
+  BetaTool,
+  BetaToolBash20241022,
+  BetaToolBash20250124,
+  BetaToolComputerUse20241022,
+  BetaToolComputerUse20250124,
+  BetaToolComputerUse20251124,
+  BetaToolResultContentBlockParam,
+  BetaToolTextEditor20241022,
+  BetaToolTextEditor20250124,
+  BetaToolTextEditor20250429,
+  BetaToolTextEditor20250728,
+} from '../../resources/beta';
+
+export type Promisable<T> = T | Promise<T>;
+
+/**
+ * Tool types that can be implemented on the client.
+ * Excludes server-side tools like code execution, web search, and MCP toolsets.
+ */
+export type BetaClientRunnableToolType =
+  | BetaTool
+  | BetaMemoryTool20250818
+  | BetaToolBash20241022
+  | BetaToolBash20250124
+  | BetaToolComputerUse20241022
+  | BetaToolComputerUse20250124
+  | BetaToolComputerUse20251124
+  | BetaToolTextEditor20241022
+  | BetaToolTextEditor20250124
+  | BetaToolTextEditor20250429
+  | BetaToolTextEditor20250728;
+
+// this type is just an extension of BetaTool with a run and parse method
+// that will be called by `toolRunner()` helpers
+export type BetaRunnableTool<Input = any> = BetaClientRunnableToolType & {
+  run: (args: Input) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
+  parse: (content: unknown) => Input;
+};