@aintela/chat 0.2.37 → 0.2.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -26,22 +26,31 @@ import { Interaction } from '../../../../models/Interaction';
26
26
  */
27
27
  /** Default args shape when a registration omits its generic. */
28
28
  export type UiToolArgs = Record<string, unknown>;
29
- /** Context handed to every renderer. */
30
- export interface UiToolContext {
29
+ /**
30
+ * Context handed to every renderer.
31
+ *
32
+ * Generic over the tool's INPUT payload (`clientOutput`, i.e. the prefill / client data — the `In`
33
+ * param) and its ANSWER (`answer`'s value — the `Ans` param). Both default to `unknown`, so an
34
+ * un-parametrized registration behaves exactly as before; the codegen'd typed builder methods
35
+ * (e.g. `askUpdateProfile`) bind them so a host reads `ctx.clientOutput` and calls `ctx.answer` fully
36
+ * typed with no casts.
37
+ */
38
+ export interface UiToolContext<In = unknown, Ans = unknown> {
31
39
  /** Normalized tool name (`UI_` marker + `{Plugin}-`/`{Plugin}_` qualifier stripped). */
32
40
  name: string;
33
41
  /** This tool call's id — stable across the call's Composing→Executing→Done lifecycle. */
34
42
  callId: string;
35
- /** The tool RESULT, if any. May be an object or a (possibly double-encoded) JSON string. */
43
+ /** The tool RESULT, if any. May be an object or a (possibly double-encoded) JSON string. Kept
44
+ * `unknown`: this is what the tool RETURNED to the model, not necessarily the answer the user gave. */
36
45
  response: unknown;
37
46
  /**
38
- * The tool's CLIENT-ONLY output — the payload it wrote to its SDK `ToolClientOutput` sink,
39
- * already parsed. This is the preferred render source: it arrives correlated to THIS call (by
40
- * id) on the result event (so multiple UI calls never race), the LLM never saw it, and it
41
- * survives reload. `undefined` until the call has responded, or when the tool didn't opt in
42
- * (fall back to `args`). Replaces the old slot-id-correlated tool-event lookup over `parts`.
47
+ * The tool's CLIENT-ONLY output — the payload it wrote to its SDK client-data sink (`SetClientData`)
48
+ * or pushed as an ask-user prefill, already parsed. This is the preferred render source: it arrives
49
+ * correlated to THIS call (by id) on the result event (so multiple UI calls never race), the LLM never
50
+ * saw it, and it survives reload. `undefined` until the call has responded, or when the tool didn't opt
51
+ * in (fall back to `args`). Typed as `In` — the codegen binds it to the server descriptor's input shape.
43
52
  */
44
- clientOutput: unknown;
53
+ clientOutput: In;
45
54
  /** Sibling parts of the same interaction (e.g. present_tsx's compiled-JS event rides here). */
46
55
  parts: ReadonlyArray<InteractionPart>;
47
56
  /** The whole interaction this part belongs to. */
@@ -50,9 +59,16 @@ export interface UiToolContext {
50
59
  onGoing: boolean;
51
60
  /** True during historical replay / preview — actions must NOT re-fire side effects. */
52
61
  preview: boolean;
62
+ /**
63
+ * Submit the user's answer for this parked ask-user call, then let the library deliver it to the agent
64
+ * (via `answerHumanTool`, keyed by {@link callId}). A string is sent verbatim; anything else is
65
+ * JSON-serialized. Typed as `Ans` — the codegen binds it to the server descriptor's answer shape, so a
66
+ * host can't send the wrong payload. A no-op for render/action tools, which never park for an answer.
67
+ */
68
+ answer(value: Ans): void;
53
69
  }
54
70
  /** Context handed to actions — adds the host environment. */
55
- export interface UiToolActionContext extends UiToolContext {
71
+ export interface UiToolActionContext<In = unknown, Ans = unknown> extends UiToolContext<In, Ans> {
56
72
  /**
57
73
  * The host environment from `EnvironmentProvider` (e.g. `refreshDashboard`,
58
74
  * `createDashboardPad`). Empty `{}` when no provider is in scope or during
@@ -61,30 +77,30 @@ export interface UiToolActionContext extends UiToolContext {
61
77
  */
62
78
  env: Record<string, unknown>;
63
79
  }
64
- export type UiToolRenderFn<TArgs> = (args: TArgs, ctx: UiToolContext) => React.ReactNode;
65
- export type UiToolActionFn<TArgs> = (args: TArgs, ctx: UiToolActionContext) => void | Promise<void>;
80
+ export type UiToolRenderFn<TArgs, In = unknown> = (args: TArgs, ctx: UiToolContext<In>) => React.ReactNode;
81
+ export type UiToolActionFn<TArgs, In = unknown> = (args: TArgs, ctx: UiToolActionContext<In>) => void | Promise<void>;
66
82
  /**
67
83
  * The interactive face of an ASK-USER component — a human-in-the-loop prompt drawn in the docked
68
84
  * ask-user drawer (`AskUserSheet`) while the tool call is PARKED, keyed by the component NAME the
69
85
  * server stamps via `[KernelUIComponent]` (`functionDetails.askUserComponent`), not by the wire tool
70
86
  * name. Same `(args, ctx)` shape as a render tool.
71
87
  */
72
- export type UiToolAskUserQuestionFn<TArgs> = (args: TArgs, ctx: UiToolContext) => React.ReactNode;
88
+ export type UiToolAskUserQuestionFn<In = unknown, Ans = unknown> = (args: UiToolArgs, ctx: UiToolContext<In, Ans>) => React.ReactNode;
73
89
  /**
74
90
  * The ANSWERED face of an ask-user component — the locked summary drawn inline in the transcript once
75
91
  * the tool has responded. Receives the tool's response (also available as `ctx.response`), so a host
76
92
  * can render "you answered X" without re-deriving it from args.
77
93
  */
78
- export type UiToolAskUserResponseFn<TArgs> = (args: TArgs, ctx: UiToolContext, response: unknown) => React.ReactNode;
94
+ export type UiToolAskUserResponseFn<In = unknown, Ans = unknown, Res = unknown> = (args: UiToolArgs, ctx: UiToolContext<In, Ans>, response: Res) => React.ReactNode;
79
95
  /**
80
96
  * A host ask-user registration: the interactive `question` (required, drawn while parked) plus an
81
97
  * optional locked `response` summary (drawn inline once answered). Omit `response` to reuse `question`
82
98
  * in both states — the question component then owns its own answered/locked view (as the built-in
83
99
  * `AskUserPart`/`AskAuthPart` do).
84
100
  */
85
- export interface UiToolAskUserRenderers<TArgs> {
86
- question: UiToolAskUserQuestionFn<TArgs>;
87
- response?: UiToolAskUserResponseFn<TArgs>;
101
+ export interface UiToolAskUserRenderers<In = unknown, Ans = unknown, Res = unknown> {
102
+ question: UiToolAskUserQuestionFn<In, Ans>;
103
+ response?: UiToolAskUserResponseFn<In, Ans, Res>;
88
104
  }
89
105
  export interface UiToolRenderOptions<TArgs> {
90
106
  /** Runtime arg guard/coercion. Return `null` to render nothing (treated as invalid args). */
@@ -103,21 +119,21 @@ export interface UiToolActionOptions<TArgs> {
103
119
  export interface UiToolRenderEntry {
104
120
  kind: 'render';
105
121
  name: string;
106
- render: UiToolRenderFn<any>;
122
+ render: UiToolRenderFn<any, any>;
107
123
  parse?: (raw: unknown) => any;
108
124
  }
109
125
  export interface UiToolActionEntry {
110
126
  kind: 'action';
111
127
  name: string;
112
- run: UiToolActionFn<any>;
128
+ run: UiToolActionFn<any, any>;
113
129
  parse?: (raw: unknown) => any;
114
130
  status?: string | ((args: any, ctx: UiToolActionContext) => string | null);
115
131
  }
116
132
  export interface UiToolAskUserEntry {
117
133
  kind: 'askUser';
118
134
  name: string;
119
- question: UiToolAskUserQuestionFn<any>;
120
- response?: UiToolAskUserResponseFn<any>;
135
+ question: UiToolAskUserQuestionFn<any, any>;
136
+ response?: UiToolAskUserResponseFn<any, any, any>;
121
137
  parse?: (raw: unknown) => any;
122
138
  }
123
139
  export type UiToolEntry = UiToolRenderEntry | UiToolActionEntry | UiToolAskUserEntry;
@@ -135,8 +151,8 @@ export interface UiToolRegistry {
135
151
  names(): string[];
136
152
  }
137
153
  export interface UiToolRegistryBuilder {
138
- render<TArgs = UiToolArgs>(name: string, render: UiToolRenderFn<TArgs>, opts?: UiToolRenderOptions<TArgs>): UiToolRegistryBuilder;
139
- action<TArgs = UiToolArgs>(name: string, run: UiToolActionFn<TArgs>, opts?: UiToolActionOptions<TArgs>): UiToolRegistryBuilder;
154
+ render<TArgs = UiToolArgs, In = unknown>(name: string, render: UiToolRenderFn<TArgs, In>, opts?: UiToolRenderOptions<TArgs>): UiToolRegistryBuilder;
155
+ action<TArgs = UiToolArgs, In = unknown>(name: string, run: UiToolActionFn<TArgs, In>, opts?: UiToolActionOptions<TArgs>): UiToolRegistryBuilder;
140
156
  /**
141
157
  * Register an ASK-USER component drawn in the docked drawer (`AskUserSheet`). `componentName` must
142
158
  * match the server's `[KernelUIComponent("…")]` value (arrives as `functionDetails.askUserComponent`).
@@ -144,8 +160,13 @@ export interface UiToolRegistryBuilder {
144
160
  * when unregistered, so consumers only register their own components (e.g. `AskCreateAccount`).
145
161
  * Pass `{ question, response? }`: `question` is the interactive parked form, `response` the optional
146
162
  * locked summary shown once answered.
163
+ *
164
+ * Generic over `In` (the prefill / client-data shape read as `ctx.clientOutput`) and `Ans` (the shape
165
+ * passed to `ctx.answer`). Both default to `unknown`. The codegen'd typed methods (e.g.
166
+ * `askUpdateProfile`) are this method with those generics pre-bound — declaration-merged onto this
167
+ * interface so the fluent chain stays fully typed.
147
168
  */
148
- askUser<TArgs = UiToolArgs>(componentName: string, renderers: UiToolAskUserRenderers<TArgs>, opts?: UiToolRenderOptions<TArgs>): UiToolRegistryBuilder;
169
+ askUser<In = unknown, Ans = unknown, Res = unknown>(componentName: string, renderers: UiToolAskUserRenderers<In, Ans, Res>, opts?: UiToolRenderOptions<UiToolArgs>): UiToolRegistryBuilder;
149
170
  build(): UiToolRegistry;
150
171
  }
151
172
  /**
@@ -18,7 +18,7 @@ export type { FriendlyState, FriendlyToolEntry } from './AiChat/ChatPane/friendl
18
18
  export { classifyPart, DEFAULT_PART_RENDERERS, TextPart, ThoughtPart, FunctionPart, WaitingPart, SuspendedPart, BoxedPart, UiToolDispatcher, } from './AiChat/ChatPane/parts';
19
19
  export type { PartKind, PartRendererProps, PartRenderer, PartRendererMap, } from './AiChat/ChatPane/parts';
20
20
  export { createUiToolRegistry, parseUiArgs, parseClientOutput } from './AiChat/ChatPane/parts';
21
- export type { UiToolRegistry, UiToolRegistryBuilder, UiToolContext, UiToolActionContext, UiToolArgs, UiToolRenderFn, UiToolActionFn, UiToolRenderOptions, UiToolActionOptions, UiToolEntry, UiToolRenderEntry, UiToolActionEntry, } from './AiChat/ChatPane/parts';
21
+ export type { UiToolRegistry, UiToolRegistryBuilder, UiToolContext, UiToolActionContext, UiToolArgs, UiToolRenderFn, UiToolActionFn, UiToolRenderOptions, UiToolActionOptions, UiToolEntry, UiToolRenderEntry, UiToolActionEntry, UiToolAskUserRenderers, UiToolAskUserQuestionFn, UiToolAskUserResponseFn, UiToolAskUserEntry, } from './AiChat/ChatPane/parts';
22
22
  export { useContainerWidth, useContainerRectangle } from '../hooks/useContainerWidth';
23
23
  export { default as Stopwatch } from './Stopwatch';
24
24
  export { default as LoadingDots } from './Library/LoadingDots';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aintela/chat",
3
- "version": "0.2.37",
3
+ "version": "0.2.38",
4
4
  "type": "module",
5
5
  "publishConfig": {
6
6
  "access": "public"