From 50f4b87c34b05b53c7fabf1981316865121113e8 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Wed, 1 Oct 2025 14:47:41 -0700 Subject: [PATCH] fix: eliminate starlight-typedoc-plugin warnings with code comments --- packages/agents-core/src/agent.ts | 3 --- packages/agents-core/src/helpers/message.ts | 18 +++++++++--------- packages/agents-core/src/result.ts | 4 ++-- packages/agents-core/src/run.ts | 7 ++----- packages/agents-core/src/runContext.ts | 10 +++++----- packages/agents-core/src/tool.ts | 5 ++--- packages/agents-realtime/src/transportLayer.ts | 3 ++- 7 files changed, 22 insertions(+), 28 deletions(-) diff --git a/packages/agents-core/src/agent.ts b/packages/agents-core/src/agent.ts index 1f508d40..cd85cbfb 100644 --- a/packages/agents-core/src/agent.ts +++ b/packages/agents-core/src/agent.ts @@ -150,9 +150,6 @@ export interface AgentConfiguration< TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput, > { - /** - * The name of the agent. - */ name: string; /** diff --git a/packages/agents-core/src/helpers/message.ts b/packages/agents-core/src/helpers/message.ts index 2c34ec49..0ef87e1c 100644 --- a/packages/agents-core/src/helpers/message.ts +++ b/packages/agents-core/src/helpers/message.ts @@ -9,9 +9,9 @@ import { /** * Creates a user message entry * - * @param input The input message from the user - * @param options Any additional options that will be directly passed to the model - * @returns a message entry + * @param input The input message from the user. + * @param options Any additional options that will be directly passed to the model. + * @returns A message entry. */ export function user( input: string | UserContent[], @@ -36,9 +36,9 @@ export function user( /** * Creates a system message entry * - * @param input The system prompt - * @param options Any additional options that will be directly passed to the model - * @returns a message entry + * @param input The system prompt. + * @param options Any additional options that will be directly passed to the model. + * @returns A message entry. */ export function system( input: string, @@ -55,9 +55,9 @@ export function system( /** * Creates an assistant message entry for example for multi-shot prompting * - * @param input The assistant response - * @param options Any additional options that will be directly passed to the model - * @returns a message entry + * @param content The assistant response. + * @param options Any additional options that will be directly passed to the model. + * @returns A message entry. */ export function assistant( content: string | AssistantContent[], diff --git a/packages/agents-core/src/result.ts b/packages/agents-core/src/result.ts index 11618df6..1013d2e3 100644 --- a/packages/agents-core/src/result.ts +++ b/packages/agents-core/src/result.ts @@ -377,9 +377,9 @@ export class StreamedRunResult< /** * Returns a readable stream of the final text output of the agent run. * - * @param options - Options for the stream. - * @param options.compatibleWithNodeStreams - Whether to use Node.js streams or web standard streams. * @returns A readable stream of the final output of the agent run. + * @remarks Pass `{ compatibleWithNodeStreams: true }` to receive a Node.js compatible stream + * instance. */ toTextStream(): ReadableStream; toTextStream(options?: { compatibleWithNodeStreams: true }): Readable; diff --git a/packages/agents-core/src/run.ts b/packages/agents-core/src/run.ts index 47471505..4ff329b7 100644 --- a/packages/agents-core/src/run.ts +++ b/packages/agents-core/src/run.ts @@ -968,11 +968,8 @@ export class Runner extends RunHooks> { * @param agent - The starting agent to run. * @param input - The initial input to the agent. You can pass a string or an array of * `AgentInputItem`. - * @param options - The options for the run. - * @param options.stream - Whether to stream the run. If true, the run will emit events as the - * model responds. - * @param options.context - The context to run the agent with. - * @param options.maxTurns - The maximum number of turns to run the agent. + * @param options - Options for the run, including streaming behavior, execution context, and the + * maximum number of turns. * @returns The result of the run. */ run, TContext = undefined>( diff --git a/packages/agents-core/src/runContext.ts b/packages/agents-core/src/runContext.ts index 250d2cd2..cf5982f8 100644 --- a/packages/agents-core/src/runContext.ts +++ b/packages/agents-core/src/runContext.ts @@ -47,11 +47,11 @@ export class RunContext { /** * Check if a tool call has been approved. * - * @param toolName - The name of the tool. - * @param callId - The call ID of the tool call. + * @param approval - Details about the tool call being evaluated. * @returns `true` if the tool call has been approved, `false` if blocked and `undefined` if not yet approved or rejected. */ - isToolApproved({ toolName, callId }: { toolName: string; callId: string }) { + isToolApproved(approval: { toolName: string; callId: string }) { + const { toolName, callId } = approval; const approvalEntry = this.#approvals.get(toolName); if (approvalEntry?.approved === true && approvalEntry.rejected === true) { logger.warn( @@ -96,8 +96,8 @@ export class RunContext { /** * Approve a tool call. * - * @param toolName - The name of the tool. - * @param callId - The call ID of the tool call. + * @param approvalItem - The tool approval item to approve. + * @param options - Additional approval behavior options. */ approveTool( approvalItem: RunToolApprovalItem, diff --git a/packages/agents-core/src/tool.ts b/packages/agents-core/src/tool.ts index 81bebe8f..3c72eff5 100644 --- a/packages/agents-core/src/tool.ts +++ b/packages/agents-core/src/tool.ts @@ -151,9 +151,8 @@ export type HostedMCPTool = HostedTool & { /** * Creates a hosted MCP tool definition. * - * @param serverLabel - The label identifying the MCP server. - * @param serverUrl - The URL of the MCP server. - * @param requireApproval - Whether tool calls require approval. + * @param options - Configuration for the hosted MCP tool, including server connection details + * and approval requirements. */ export function hostedMcpTool( options: { diff --git a/packages/agents-realtime/src/transportLayer.ts b/packages/agents-realtime/src/transportLayer.ts index 962afda2..33317fcd 100644 --- a/packages/agents-realtime/src/transportLayer.ts +++ b/packages/agents-realtime/src/transportLayer.ts @@ -131,7 +131,8 @@ export interface RealtimeTransportLayer /** * Resets the conversation history / context to a specific state - * @param history - The history to reset to + * @param oldHistory - The history that is currently stored on the session. + * @param newHistory - The history you want the session to use going forward. */ resetHistory(oldHistory: RealtimeItem[], newHistory: RealtimeItem[]): void;