@vertesia/tools-sdk 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260806.125520Z

package/src/types.ts

@@ -3,6 +3,9 @@ import type { VertesiaClient } from '@vertesia/client';
 import type {
     AgentToolDefinition,
     AuthTokenPayload,
+    AppEventHookDelivery as CommonAppEventHookDelivery,
+    AppEventHookPayload as CommonAppEventHookPayload,
+    AppEventSubscriptionDefinition as CommonAppEventSubscriptionDefinition,
     MCPToolAnnotations,
     ProjectConfiguration,
     RenderingTemplateDefinition,
@@ -13,6 +16,9 @@ import type {
 } from '@vertesia/common';
 
 export type { ToolExecutionMetadata };
+export type AppEventSubscriptionDefinition = CommonAppEventSubscriptionDefinition;
+export type AppEventHookDelivery = CommonAppEventHookDelivery;
+export type AppEventHookPayload = CommonAppEventHookPayload;
 
 export type ICollection<T = object> = CollectionProperties & Iterable<T>;
 
@@ -54,6 +60,50 @@ export interface ToolExecutionContext {
     getClient: () => Promise<VertesiaClient>;
 }
 
+export type AppLifecycleHookName = 'install' | 'uninstall';
+
+export interface AppLifecycleHookContext extends ToolExecutionContext {
+    /** Metadata supplied by Studio for this installation lifecycle call. */
+    metadata: ToolExecutionMetadata;
+}
+
+export interface AppLifecycleHookResult {
+    message?: string;
+    data?: Record<string, unknown>;
+}
+
+// biome-ignore lint/suspicious/noConfusingVoidType: lifecycle hooks may complete without a response body.
+export type AppLifecycleHook = (context: AppLifecycleHookContext) => Promise<void | AppLifecycleHookResult>;
+
+export interface AppLifecycleHookDefinition {
+    kind: 'lifecycle';
+    name: AppLifecycleHookName;
+    handler: AppLifecycleHook;
+}
+
+export type AppEventHookContext = ToolExecutionContext;
+export type AppEventHookResult = AppLifecycleHookResult;
+
+export type AppEventHook = (
+    payload: AppEventHookPayload,
+    context: AppEventHookContext,
+) => Promise<AppEventHookResult> | Promise<void>;
+
+export interface AppEventHookDefinition {
+    kind: 'event';
+    /** Kebab-case URL-safe name. The lifecycle names install and uninstall are reserved. */
+    name: string;
+    description?: string;
+    handler: AppEventHook;
+}
+
+/** App-owned hook definitions aggregated from active application modules. */
+export type AppHookDefinition = AppLifecycleHookDefinition | AppEventHookDefinition;
+
+export interface AppLifecycleHookPayload {
+    metadata?: ToolExecutionMetadata;
+}
+
 export interface ToolExecutionResult extends ToolResultContent {
     /**
      * Medata can be used to return more info on the tool execution like stats or user messages.
@@ -149,6 +199,41 @@ export interface Tool<ParamsT extends object = object> extends ToolDefinition {
      * @returns
      */
     isEnabled?: (payload: ToolUseContext) => boolean;
+
+    /**
+     * Declares which parameter carries the *name of another tool*. See {@link ToolDispatchDescriptor}.
+     */
+    dispatch?: ToolDispatchDescriptor;
+}
+
+/**
+ * Which parameter of a tool carries the name of another tool.
+ *
+ * JSON Schema types such a field as `string`, so every phantom name validates against it. Naming
+ * the field here lets build-time validation resolve those names against the registry; without it
+ * the mistake surfaces only when an agent attempts the call and the server rejects it.
+ *
+ * Purely descriptive — nothing reads it at runtime. `@dglabs/workflows` and the skill-markdown
+ * checker each declare a structural twin, since neither can depend on this package.
+ */
+export interface ToolDispatchDescriptor {
+    /**
+     * Path to the parameter holding the tool name, using dots for nesting and `[]` for arrays.
+     * Examples: `tool_name`, `allowed_tools[]`, `agent_runner_options.tool_names[]`.
+     */
+    field: string;
+    /**
+     * Path to the parameter holding the input forwarded to the dispatched tool, if any.
+     * When set, examples can also be validated against the *dispatched* tool's schema.
+     */
+    inputField?: string;
+    /** Tool names this dispatcher refuses at runtime. Referencing one is an error. */
+    deny?: readonly string[];
+    /**
+     * True when the runtime strips a leading `+` or `-` before resolving the name — the selection
+     * prefixes that add to, or remove from, the default toolset.
+     */
+    stripsSelectionPrefix?: boolean;
 }
 
 /**