Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 | /**
* Common type definitions for the StackOne SDK
*/
import type { Tool, ToolSet } from 'ai';
import type { JsonObject, JsonValue } from 'type-fest';
export type { JsonObject, JsonValue };
/**
* JSON Schema type for defining tool input/output schemas as raw JSON Schema objects.
* This allows tools to be defined without Zod when you have JSON Schema definitions available.
*
* @see https://github.com/TanStack/ai/blob/049eb8acd83e6d566c6040c0c4cb53dbe222d46a/packages/typescript/ai/src/types.ts#L5C1-L49C1
*/
export interface JSONSchema {
type?: string | Array<string>;
properties?: Record<string, JSONSchema>;
items?: JSONSchema | Array<JSONSchema>;
required?: Array<string>;
enum?: Array<JsonValue>;
const?: JsonValue;
description?: string;
default?: JsonValue;
$ref?: string;
$defs?: Record<string, JSONSchema>;
definitions?: Record<string, JSONSchema>;
allOf?: Array<JSONSchema>;
anyOf?: Array<JSONSchema>;
oneOf?: Array<JSONSchema>;
not?: JSONSchema;
if?: JSONSchema;
then?: JSONSchema;
else?: JSONSchema;
minimum?: number;
maximum?: number;
exclusiveMinimum?: number;
exclusiveMaximum?: number;
minLength?: number;
maxLength?: number;
pattern?: string;
format?: string;
minItems?: number;
maxItems?: number;
uniqueItems?: boolean;
additionalProperties?: boolean | JSONSchema;
additionalItems?: boolean | JSONSchema;
patternProperties?: Record<string, JSONSchema>;
propertyNames?: JSONSchema;
minProperties?: number;
maxProperties?: number;
title?: string;
examples?: Array<JsonValue>;
[key: string]:
| JsonValue
| JSONSchema
| Array<JSONSchema>
| Record<string, JSONSchema>
| undefined; // Allow additional properties for extensibility
}
/**
* JSON Schema properties type
*/
export type JsonSchemaProperties = Record<string, JSONSchema>;
/**
* How the MCP endpoint lists tools.
*
* `'individual'` (the server default) lists one tool per action — hundreds per account.
* `'search_execute'` lists two meta tools per connector instead: a `*_search_actions` that ranks
* actions for a natural-language query and an `*_execute_action` that runs one by id. The
* catalog stays small however many accounts are linked, which is what keeps it inside a model's
* context.
*/
export type ToolMode = 'individual' | 'search_execute';
/**
* Executes over MCP `tools/call`, on the endpoint that listed the tool. Every tool a toolset
* returns executes this way.
*/
export interface McpExecuteConfig {
kind: 'mcp';
url: string;
toolName: string;
}
/**
* A tool whose `execute` is supplied by the caller rather than by the SDK.
*/
interface LocalExecuteConfig {
kind: 'local';
identifier?: string;
description?: string;
}
/**
* Discriminated union lets call sites branch on execution style without relying on nullable fields.
*/
export type ExecuteConfig = McpExecuteConfig | LocalExecuteConfig;
/**
* Options for executing a tool
*/
export interface ExecuteOptions {
/**
* If true, returns the `tools/call` the tool would send instead of sending it.
*/
dryRun?: boolean;
}
/**
* Execution metadata that can be surfaced to AI SDK tools.
*/
export interface ToolExecution {
/**
* How the tool is executed.
*/
config: ExecuteConfig;
}
/**
* Schema definition for tool parameters: the served `inputSchema`, verbatim.
*
* Every root keyword the server sends (`$schema`, `$defs`, `title`, `additionalProperties`,
* `oneOf`, …) is kept, so {@link BaseTool.toJsonSchema} can hand a model exactly what was served.
*/
export interface ToolParameters extends Record<string, unknown> {
type: string;
properties: JsonSchemaProperties;
required?: string[];
}
/**
* Complete definition of a tool including its schema and execution config
*/
export interface ToolDefinition {
description: string;
parameters: ToolParameters;
execute: ExecuteConfig;
}
/**
* Extended AI SDK tool definition with StackOne-specific execution metadata.
* Extends the base Tool type from the 'ai' package.
*
* NOTE: We avoid defining our own types as much as possible and use existing
* types from dependencies. This type only extends the AI SDK Tool type with
* StackOne-specific metadata that doesn't exist in the original type.
*/
export type AISDKToolDefinition = Tool & {
/**
* StackOne-specific execution metadata for debugging and introspection.
*/
execution?: ToolExecution;
};
/**
* Result type for toAISDK() method.
* Uses the ToolSet type from AI SDK to ensure full compatibility with
* generateText, streamText, and other AI SDK functions.
*
* NOTE: We extend ToolSet with our custom AISDKToolDefinition to ensure
* both AI SDK compatibility and access to StackOne-specific properties
* like `execution` metadata.
*/
export type AISDKToolResult<T extends string = string> = ToolSet & {
[K in T]: AISDKToolDefinition;
};
/**
* Options for toClaudeAgentSdk() method
*/
export interface ClaudeAgentSdkOptions {
/**
* Name of the MCP server. Defaults to 'stackone-tools'.
*/
serverName?: string;
/**
* Version of the MCP server. Defaults to '1.0.0'.
*/
serverVersion?: string;
}
/**
* An account linked to the API key, as `GET /accounts` returns it. Only accounts whose `status`
* is `'active'` can serve tools.
*/
export type StackOneAccount = JsonObject & {
id: string;
provider?: string;
status?: string;
/** Whether the account is shared across end users. */
shared?: boolean;
/**
* The account's end user. For a non-shared account, the toolset sends it as `x-end-user-id` on
* every MCP request for that account.
*/
origin_username?: string | null;
};
/**
* One action a `search()` found, as the server returned it: `action_id` always, the fields below
* when the server sent them, and anything else it adds.
*/
export type SearchResult = JsonObject & {
action_id: string;
/** What the action does. */
description?: string;
/** How well the action matched the query; results are ranked on it, highest first. */
similarity_score?: number;
/**
* The JSON Schema of the arguments `execute()` takes for this action. The server omits it for
* an action that takes none.
*/
input_schema?: JsonObject;
/** A copy-and-edit `execute()` call for the action, served alongside `input_schema`. */
example_request?: JsonObject;
/**
* The `session_id` of the search that produced this hit, when the server issued one. Pass it
* to `execute()` and `submitFeedback()` to link those calls to this search.
*/
session_id?: string;
/**
* The account whose connector found this hit. The same action linked on two accounts is two
* hits; pass this in `execute()`'s `accountIds` to run the action on this one.
*/
account_id: string;
};
/**
* What an action returns: the server's own wrapper, as it wrote it. `toolset.execute()` and
* `submitFeedback()` return one; so does `tool.execute()` on an action tool.
*
* A type for what the server sends, not a check: the SDK returns the result unchanged. A result
* with `isError` set never reaches the caller, since it raises `StackOneAPIError` instead. Any
* key the server adds beyond these is kept.
*/
export type ActionResult = JsonObject & {
isError: false;
/** The action's output. A file action's is `{ download_url, expires_at, file }`. */
result: JsonValue;
/** What StackOne Defender checked, when it ran on this call. */
defenderMetadata?: JsonObject;
/** The policy decision for this call, when a policy applied. */
policyMetadata?: JsonObject;
};
/** The verdict `submitFeedback()` records. */
export type FeedbackRating = 'positive' | 'negative' | 'neutral';
/** Who produced the feedback. */
export type FeedbackSource = 'model' | 'user' | 'system';
/** What the feedback is about. */
export type FeedbackCategory = 'search' | 'execute' | 'defender' | 'connection' | 'general';
|